diff --git a/translated_images/ar/.co-op-translator.json b/translated_images/ar/.co-op-translator.json index a3ac0bd11..a8a754999 100644 --- a/translated_images/ar/.co-op-translator.json +++ b/translated_images/ar/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:43:22+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ar" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:42:58+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ar" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:20:34+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ar" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T13:02:46+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ar" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:20:39+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ar" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:25:39+00:00", diff --git a/translated_images/ar/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ar/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 96e0ba218..000000000 Binary files a/translated_images/ar/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ar/architecture.eedc993a1c576839.webp b/translated_images/ar/architecture.eedc993a1c576839.webp deleted file mode 100644 index d61fcd84d..000000000 Binary files a/translated_images/ar/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ar/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ar/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 4d006011f..000000000 Binary files a/translated_images/ar/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/bg/.co-op-translator.json b/translated_images/bg/.co-op-translator.json index 5a0aa1c0c..b545e64d1 100644 --- a/translated_images/bg/.co-op-translator.json +++ b/translated_images/bg/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:56:34+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "bg" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:56:14+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "bg" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:37:56+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "bg" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:52:34+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "bg" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:38:00+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "bg" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T11:43:41+00:00", diff --git a/translated_images/bg/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/bg/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 065a48c0b..000000000 Binary files a/translated_images/bg/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/bg/architecture.eedc993a1c576839.webp b/translated_images/bg/architecture.eedc993a1c576839.webp deleted file mode 100644 index 7dfbcd8dc..000000000 Binary files a/translated_images/bg/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/bg/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/bg/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index dac954425..000000000 Binary files a/translated_images/bg/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/bn/.co-op-translator.json b/translated_images/bn/.co-op-translator.json index a8ed46cff..6dd564376 100644 --- a/translated_images/bn/.co-op-translator.json +++ b/translated_images/bn/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:11:32+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "bn" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:11:04+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "bn" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:36:57+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "bn" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:46:31+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "bn" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:37:04+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "bn" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:43:02+00:00", diff --git a/translated_images/bn/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/bn/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 579f8cf1a..000000000 Binary files a/translated_images/bn/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/bn/architecture.eedc993a1c576839.webp b/translated_images/bn/architecture.eedc993a1c576839.webp deleted file mode 100644 index 5478dbd39..000000000 Binary files a/translated_images/bn/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/bn/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/bn/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 51f2cdfd3..000000000 Binary files a/translated_images/bn/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/cs/.co-op-translator.json b/translated_images/cs/.co-op-translator.json index 2f79b0f83..c266d168c 100644 --- a/translated_images/cs/.co-op-translator.json +++ b/translated_images/cs/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:25:23+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "cs" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:24:58+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "cs" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:20:47+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "cs" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:44:34+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "cs" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:20:52+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "cs" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T11:26:24+00:00", diff --git a/translated_images/cs/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/cs/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 4157bf623..000000000 Binary files a/translated_images/cs/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/cs/architecture.eedc993a1c576839.webp b/translated_images/cs/architecture.eedc993a1c576839.webp deleted file mode 100644 index 94c534e8d..000000000 Binary files a/translated_images/cs/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/cs/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/cs/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index edf703d46..000000000 Binary files a/translated_images/cs/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/da/.co-op-translator.json b/translated_images/da/.co-op-translator.json index 1ce4b94a2..c1f56eec6 100644 --- a/translated_images/da/.co-op-translator.json +++ b/translated_images/da/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:32:07+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "da" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:31:44+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "da" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T10:45:02+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "da" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:27:44+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "da" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T10:45:07+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "da" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T10:50:15+00:00", diff --git a/translated_images/da/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/da/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 8ccfce27e..000000000 Binary files a/translated_images/da/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/da/architecture.eedc993a1c576839.webp b/translated_images/da/architecture.eedc993a1c576839.webp deleted file mode 100644 index 736aa7fd4..000000000 Binary files a/translated_images/da/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/da/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/da/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index a56adb2e6..000000000 Binary files a/translated_images/da/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/de/.co-op-translator.json b/translated_images/de/.co-op-translator.json index 1b0611352..10ffe9882 100644 --- a/translated_images/de/.co-op-translator.json +++ b/translated_images/de/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:43:14+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "de" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:42:49+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "de" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:20:30+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "de" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T13:02:42+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "de" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:20:35+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "de" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:25:32+00:00", diff --git a/translated_images/de/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/de/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 62973c88a..000000000 Binary files a/translated_images/de/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/de/architecture.eedc993a1c576839.webp b/translated_images/de/architecture.eedc993a1c576839.webp deleted file mode 100644 index d6ffbbc47..000000000 Binary files a/translated_images/de/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/de/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/de/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 856c3d86f..000000000 Binary files a/translated_images/de/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/el/.co-op-translator.json b/translated_images/el/.co-op-translator.json index b5ae1c8f7..7470d7cd8 100644 --- a/translated_images/el/.co-op-translator.json +++ b/translated_images/el/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:57:40+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "el" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:57:16+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "el" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T10:26:28+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "el" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:19:49+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "el" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T10:26:33+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "el" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T10:34:16+00:00", diff --git a/translated_images/el/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/el/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 9834edbae..000000000 Binary files a/translated_images/el/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/el/architecture.eedc993a1c576839.webp b/translated_images/el/architecture.eedc993a1c576839.webp deleted file mode 100644 index b57e2747b..000000000 Binary files a/translated_images/el/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/el/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/el/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 5488b962e..000000000 Binary files a/translated_images/el/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/en/.co-op-translator.json b/translated_images/en/.co-op-translator.json index 69aa33ccd..3e041ed15 100644 --- a/translated_images/en/.co-op-translator.json +++ b/translated_images/en/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T13:44:06+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "en" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T13:43:48+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "en" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:03:11+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "en" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T10:18:22+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "en" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:03:16+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "en" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:09:21+00:00", diff --git a/translated_images/en/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/en/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 5e16bb26d..000000000 Binary files a/translated_images/en/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/en/architecture.eedc993a1c576839.webp b/translated_images/en/architecture.eedc993a1c576839.webp deleted file mode 100644 index e308245cb..000000000 Binary files a/translated_images/en/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/en/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/en/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index ccb8a8093..000000000 Binary files a/translated_images/en/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/es/.co-op-translator.json b/translated_images/es/.co-op-translator.json index 10dc66d06..18a3dd571 100644 --- a/translated_images/es/.co-op-translator.json +++ b/translated_images/es/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T13:44:11+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "es" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T13:43:54+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "es" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:03:14+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "es" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T10:18:29+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "es" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:03:19+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "es" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:09:26+00:00", diff --git a/translated_images/es/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/es/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index e956aea90..000000000 Binary files a/translated_images/es/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/es/architecture.eedc993a1c576839.webp b/translated_images/es/architecture.eedc993a1c576839.webp deleted file mode 100644 index e0d6685d2..000000000 Binary files a/translated_images/es/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/es/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/es/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index a0d4198e2..000000000 Binary files a/translated_images/es/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/et/.co-op-translator.json b/translated_images/et/.co-op-translator.json index e3a78e89f..04f37b36c 100644 --- a/translated_images/et/.co-op-translator.json +++ b/translated_images/et/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T17:09:21+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "et" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T17:09:00+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "et" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T12:28:00+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "et" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:19:29+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "et" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T12:28:05+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "et" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:33:17+00:00", diff --git a/translated_images/et/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/et/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 34328fead..000000000 Binary files a/translated_images/et/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/et/architecture.eedc993a1c576839.webp b/translated_images/et/architecture.eedc993a1c576839.webp deleted file mode 100644 index 182aa589f..000000000 Binary files a/translated_images/et/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/et/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/et/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 870d5bd20..000000000 Binary files a/translated_images/et/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/fa/.co-op-translator.json b/translated_images/fa/.co-op-translator.json index 8054eb542..2c8897ed5 100644 --- a/translated_images/fa/.co-op-translator.json +++ b/translated_images/fa/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:18:29+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "fa" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:18:04+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "fa" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:34:29+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "fa" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T10:26:45+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "fa" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:34:34+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "fa" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:39:25+00:00", diff --git a/translated_images/fa/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/fa/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 596640279..000000000 Binary files a/translated_images/fa/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/fa/architecture.eedc993a1c576839.webp b/translated_images/fa/architecture.eedc993a1c576839.webp deleted file mode 100644 index a4867f835..000000000 Binary files a/translated_images/fa/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/fa/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/fa/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 2de290e69..000000000 Binary files a/translated_images/fa/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/fi/.co-op-translator.json b/translated_images/fi/.co-op-translator.json index eaba3a069..8891d7efa 100644 --- a/translated_images/fi/.co-op-translator.json +++ b/translated_images/fi/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:32:15+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "fi" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:31:51+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "fi" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T10:45:06+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "fi" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:27:49+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "fi" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T10:45:10+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "fi" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T10:50:22+00:00", diff --git a/translated_images/fi/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/fi/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 4151d893e..000000000 Binary files a/translated_images/fi/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/fi/architecture.eedc993a1c576839.webp b/translated_images/fi/architecture.eedc993a1c576839.webp deleted file mode 100644 index a7d29906d..000000000 Binary files a/translated_images/fi/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/fi/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/fi/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 1743c4d30..000000000 Binary files a/translated_images/fi/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/fr/.co-op-translator.json b/translated_images/fr/.co-op-translator.json index 41046298f..7795d06e2 100644 --- a/translated_images/fr/.co-op-translator.json +++ b/translated_images/fr/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T13:44:09+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "fr" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T13:43:51+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "fr" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:03:13+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "fr" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T10:18:26+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "fr" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:03:17+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "fr" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:09:24+00:00", diff --git a/translated_images/fr/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/fr/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index b3b0c0708..000000000 Binary files a/translated_images/fr/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/fr/architecture.eedc993a1c576839.webp b/translated_images/fr/architecture.eedc993a1c576839.webp deleted file mode 100644 index 4476a1253..000000000 Binary files a/translated_images/fr/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/fr/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/fr/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index ac1e03f84..000000000 Binary files a/translated_images/fr/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/he/.co-op-translator.json b/translated_images/he/.co-op-translator.json index b8bfd2bdc..47a00243e 100644 --- a/translated_images/he/.co-op-translator.json +++ b/translated_images/he/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:32:05+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "he" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:31:42+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "he" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:00:04+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "he" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:59:47+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "he" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:00:09+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "he" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T11:06:54+00:00", diff --git a/translated_images/he/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/he/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index baf579b52..000000000 Binary files a/translated_images/he/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/he/architecture.eedc993a1c576839.webp b/translated_images/he/architecture.eedc993a1c576839.webp deleted file mode 100644 index 104308f91..000000000 Binary files a/translated_images/he/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/he/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/he/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index e94948bc5..000000000 Binary files a/translated_images/he/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/hi/.co-op-translator.json b/translated_images/hi/.co-op-translator.json index 37772432e..2b07213a7 100644 --- a/translated_images/hi/.co-op-translator.json +++ b/translated_images/hi/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:38:14+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "hi" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:37:49+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "hi" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:06:34+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "hi" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T10:36:46+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "hi" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:06:39+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "hi" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:12:09+00:00", diff --git a/translated_images/hi/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/hi/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 131dd68da..000000000 Binary files a/translated_images/hi/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/hi/architecture.eedc993a1c576839.webp b/translated_images/hi/architecture.eedc993a1c576839.webp deleted file mode 100644 index 3cd01f35f..000000000 Binary files a/translated_images/hi/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/hi/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/hi/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index f7ef573bd..000000000 Binary files a/translated_images/hi/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/hr/.co-op-translator.json b/translated_images/hr/.co-op-translator.json index c1f017ee7..6ef3cd189 100644 --- a/translated_images/hr/.co-op-translator.json +++ b/translated_images/hr/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:05:46+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "hr" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:05:26+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "hr" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:54:46+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "hr" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:29:04+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "hr" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:54:51+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "hr" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:00:23+00:00", diff --git a/translated_images/hr/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/hr/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 5c5bce5dc..000000000 Binary files a/translated_images/hr/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/hr/architecture.eedc993a1c576839.webp b/translated_images/hr/architecture.eedc993a1c576839.webp deleted file mode 100644 index d27fc5d0b..000000000 Binary files a/translated_images/hr/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/hr/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/hr/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 94788985a..000000000 Binary files a/translated_images/hr/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/hu/.co-op-translator.json b/translated_images/hu/.co-op-translator.json index 9bab8cf3b..38bf6dde7 100644 --- a/translated_images/hu/.co-op-translator.json +++ b/translated_images/hu/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:25:20+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "hu" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:24:55+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "hu" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:20:45+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "hu" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:44:32+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "hu" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:20:50+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "hu" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T11:26:21+00:00", diff --git a/translated_images/hu/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/hu/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 807cd4b4c..000000000 Binary files a/translated_images/hu/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/hu/architecture.eedc993a1c576839.webp b/translated_images/hu/architecture.eedc993a1c576839.webp deleted file mode 100644 index 0b92aef2a..000000000 Binary files a/translated_images/hu/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/hu/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/hu/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index f46285e5d..000000000 Binary files a/translated_images/hu/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/id/.co-op-translator.json b/translated_images/id/.co-op-translator.json index dd794443c..4030efd69 100644 --- a/translated_images/id/.co-op-translator.json +++ b/translated_images/id/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:07:09+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "id" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:06:49+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "id" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:23:17+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "id" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:36:43+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "id" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:23:21+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "id" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:28:30+00:00", diff --git a/translated_images/id/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/id/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 157bdd660..000000000 Binary files a/translated_images/id/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/id/architecture.eedc993a1c576839.webp b/translated_images/id/architecture.eedc993a1c576839.webp deleted file mode 100644 index e64449b16..000000000 Binary files a/translated_images/id/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/id/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/id/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 47c274ca0..000000000 Binary files a/translated_images/id/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/it/.co-op-translator.json b/translated_images/it/.co-op-translator.json index a0a07c727..c1016f7cd 100644 --- a/translated_images/it/.co-op-translator.json +++ b/translated_images/it/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T13:55:39+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "it" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T13:55:17+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "it" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T10:10:16+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "it" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:36:01+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "it" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T10:10:21+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "it" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T10:15:42+00:00", diff --git a/translated_images/it/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/it/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index c16a33deb..000000000 Binary files a/translated_images/it/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/it/architecture.eedc993a1c576839.webp b/translated_images/it/architecture.eedc993a1c576839.webp deleted file mode 100644 index 86470da01..000000000 Binary files a/translated_images/it/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/it/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/it/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 91dd9ae22..000000000 Binary files a/translated_images/it/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/ja/.co-op-translator.json b/translated_images/ja/.co-op-translator.json index 6e54e55b9..cea6c6f3e 100644 --- a/translated_images/ja/.co-op-translator.json +++ b/translated_images/ja/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:38:08+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ja" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:37:41+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ja" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:06:30+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ja" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T10:36:42+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ja" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:06:35+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ja" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:12:03+00:00", diff --git a/translated_images/ja/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ja/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 312a980cd..000000000 Binary files a/translated_images/ja/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ja/architecture.eedc993a1c576839.webp b/translated_images/ja/architecture.eedc993a1c576839.webp deleted file mode 100644 index 3ed88af88..000000000 Binary files a/translated_images/ja/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ja/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ja/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index ad7a7b2b0..000000000 Binary files a/translated_images/ja/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/km/.co-op-translator.json b/translated_images/km/.co-op-translator.json index 055398ae1..d9dfb46c8 100644 --- a/translated_images/km/.co-op-translator.json +++ b/translated_images/km/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-04-06T16:41:53+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "km" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-04-06T16:41:46+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "km" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-04-06T16:42:20+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "km" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-04-06T16:43:26+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "km" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-04-06T16:42:22+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "km" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-04-06T16:45:34+00:00", diff --git a/translated_images/km/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/km/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 78798ff27..000000000 Binary files a/translated_images/km/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/km/architecture.eedc993a1c576839.webp b/translated_images/km/architecture.eedc993a1c576839.webp deleted file mode 100644 index 895b21d87..000000000 Binary files a/translated_images/km/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/km/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/km/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index cfe2880c4..000000000 Binary files a/translated_images/km/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/kn/.co-op-translator.json b/translated_images/kn/.co-op-translator.json index 1a5c89074..e2c9a7e19 100644 --- a/translated_images/kn/.co-op-translator.json +++ b/translated_images/kn/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:53:03+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "kn" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:52:40+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "kn" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T12:44:19+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "kn" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:11:20+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "kn" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T12:44:25+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "kn" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:51:03+00:00", diff --git a/translated_images/kn/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/kn/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 353ea0ebe..000000000 Binary files a/translated_images/kn/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/kn/architecture.eedc993a1c576839.webp b/translated_images/kn/architecture.eedc993a1c576839.webp deleted file mode 100644 index 063556056..000000000 Binary files a/translated_images/kn/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/kn/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/kn/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 84008fe77..000000000 Binary files a/translated_images/kn/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/ko/.co-op-translator.json b/translated_images/ko/.co-op-translator.json index 21351e5bb..07b9bf2d6 100644 --- a/translated_images/ko/.co-op-translator.json +++ b/translated_images/ko/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:38:11+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ko" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:37:45+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ko" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:06:31+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ko" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T10:36:44+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ko" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:06:37+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ko" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:12:06+00:00", diff --git a/translated_images/ko/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ko/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 4616d7aba..000000000 Binary files a/translated_images/ko/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ko/architecture.eedc993a1c576839.webp b/translated_images/ko/architecture.eedc993a1c576839.webp deleted file mode 100644 index ec5d608fc..000000000 Binary files a/translated_images/ko/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ko/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ko/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 63e92648b..000000000 Binary files a/translated_images/ko/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/lt/.co-op-translator.json b/translated_images/lt/.co-op-translator.json index a2e9b0944..947839b11 100644 --- a/translated_images/lt/.co-op-translator.json +++ b/translated_images/lt/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T17:25:42+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "lt" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T17:25:14+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "lt" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T12:11:45+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "lt" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:10:40+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "lt" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T12:11:50+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "lt" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:17:57+00:00", diff --git a/translated_images/lt/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/lt/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 0d85a0b57..000000000 Binary files a/translated_images/lt/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/lt/architecture.eedc993a1c576839.webp b/translated_images/lt/architecture.eedc993a1c576839.webp deleted file mode 100644 index 8aae2da86..000000000 Binary files a/translated_images/lt/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/lt/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/lt/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 7061c045a..000000000 Binary files a/translated_images/lt/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/ml/.co-op-translator.json b/translated_images/ml/.co-op-translator.json index b6980fc0e..b000bfa10 100644 --- a/translated_images/ml/.co-op-translator.json +++ b/translated_images/ml/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:53:00+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ml" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:52:35+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ml" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T12:44:16+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ml" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:11:18+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ml" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T12:44:22+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ml" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:50:59+00:00", diff --git a/translated_images/ml/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ml/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 4e0003a27..000000000 Binary files a/translated_images/ml/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ml/architecture.eedc993a1c576839.webp b/translated_images/ml/architecture.eedc993a1c576839.webp deleted file mode 100644 index d3b5ea431..000000000 Binary files a/translated_images/ml/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ml/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ml/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 239b84d3d..000000000 Binary files a/translated_images/ml/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/mr/.co-op-translator.json b/translated_images/mr/.co-op-translator.json index 13e6904f9..0402e8c35 100644 --- a/translated_images/mr/.co-op-translator.json +++ b/translated_images/mr/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:11:35+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "mr" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:11:11+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "mr" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:37:00+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "mr" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:46:34+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "mr" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:37:06+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "mr" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:43:05+00:00", diff --git a/translated_images/mr/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/mr/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 87d0ec476..000000000 Binary files a/translated_images/mr/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/mr/architecture.eedc993a1c576839.webp b/translated_images/mr/architecture.eedc993a1c576839.webp deleted file mode 100644 index 9bcf6a657..000000000 Binary files a/translated_images/mr/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/mr/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/mr/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 61a009f95..000000000 Binary files a/translated_images/mr/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/ms/.co-op-translator.json b/translated_images/ms/.co-op-translator.json index 3eeb97369..eeacb6d5f 100644 --- a/translated_images/ms/.co-op-translator.json +++ b/translated_images/ms/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:07:11+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ms" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:06:51+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ms" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:23:18+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ms" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:36:47+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ms" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:23:22+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ms" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:28:34+00:00", diff --git a/translated_images/ms/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ms/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index def323f06..000000000 Binary files a/translated_images/ms/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ms/architecture.eedc993a1c576839.webp b/translated_images/ms/architecture.eedc993a1c576839.webp deleted file mode 100644 index 06c9eb7e0..000000000 Binary files a/translated_images/ms/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ms/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ms/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index da3e4a957..000000000 Binary files a/translated_images/ms/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/my/.co-op-translator.json b/translated_images/my/.co-op-translator.json index 4c4a23672..02c5ba185 100644 --- a/translated_images/my/.co-op-translator.json +++ b/translated_images/my/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T17:25:36+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "my" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T17:25:05+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "my" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T12:11:42+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "my" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:10:36+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "my" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T12:11:47+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "my" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:17:51+00:00", diff --git a/translated_images/my/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/my/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 102beb102..000000000 Binary files a/translated_images/my/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/my/architecture.eedc993a1c576839.webp b/translated_images/my/architecture.eedc993a1c576839.webp deleted file mode 100644 index a529a1980..000000000 Binary files a/translated_images/my/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/my/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/my/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index ed1fe8cdc..000000000 Binary files a/translated_images/my/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/ne/.co-op-translator.json b/translated_images/ne/.co-op-translator.json index afb041145..745ffc4ff 100644 --- a/translated_images/ne/.co-op-translator.json +++ b/translated_images/ne/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:11:38+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ne" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:11:15+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ne" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:37:02+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ne" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:46:39+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ne" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:37:07+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ne" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:43:09+00:00", diff --git a/translated_images/ne/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ne/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 8824a5809..000000000 Binary files a/translated_images/ne/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ne/architecture.eedc993a1c576839.webp b/translated_images/ne/architecture.eedc993a1c576839.webp deleted file mode 100644 index 8c10bb513..000000000 Binary files a/translated_images/ne/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ne/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ne/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 8faaa9d09..000000000 Binary files a/translated_images/ne/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/nl/.co-op-translator.json b/translated_images/nl/.co-op-translator.json index b39b3d38b..014fa4228 100644 --- a/translated_images/nl/.co-op-translator.json +++ b/translated_images/nl/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:32:02+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "nl" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:31:39+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "nl" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:00:02+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "nl" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:59:44+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "nl" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:00:08+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "nl" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T11:06:51+00:00", diff --git a/translated_images/nl/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/nl/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 94a1dad83..000000000 Binary files a/translated_images/nl/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/nl/architecture.eedc993a1c576839.webp b/translated_images/nl/architecture.eedc993a1c576839.webp deleted file mode 100644 index 335dc176c..000000000 Binary files a/translated_images/nl/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/nl/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/nl/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index f4fb18cd1..000000000 Binary files a/translated_images/nl/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/no/.co-op-translator.json b/translated_images/no/.co-op-translator.json index 885b05b4c..03f31b0c6 100644 --- a/translated_images/no/.co-op-translator.json +++ b/translated_images/no/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:32:12+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "no" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:31:48+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "no" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T10:45:04+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "no" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:27:46+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "no" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T10:45:09+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "no" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T10:50:18+00:00", diff --git a/translated_images/no/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/no/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index ac3a0f68b..000000000 Binary files a/translated_images/no/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/no/architecture.eedc993a1c576839.webp b/translated_images/no/architecture.eedc993a1c576839.webp deleted file mode 100644 index b05be2d78..000000000 Binary files a/translated_images/no/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/no/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/no/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 3401dac30..000000000 Binary files a/translated_images/no/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/pa/.co-op-translator.json b/translated_images/pa/.co-op-translator.json index f89493d82..e47ad4bde 100644 --- a/translated_images/pa/.co-op-translator.json +++ b/translated_images/pa/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:18:33+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "pa" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:18:08+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "pa" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:53:32+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "pa" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T13:11:48+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "pa" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:53:37+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "pa" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:58:59+00:00", diff --git a/translated_images/pa/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/pa/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 562d93048..000000000 Binary files a/translated_images/pa/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/pa/architecture.eedc993a1c576839.webp b/translated_images/pa/architecture.eedc993a1c576839.webp deleted file mode 100644 index 30a9b9e29..000000000 Binary files a/translated_images/pa/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/pa/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/pa/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index c9794caca..000000000 Binary files a/translated_images/pa/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/pcm/.co-op-translator.json b/translated_images/pcm/.co-op-translator.json index e65b62a05..336231038 100644 --- a/translated_images/pcm/.co-op-translator.json +++ b/translated_images/pcm/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T17:09:24+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "pcm" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T17:09:03+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "pcm" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T12:28:01+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "pcm" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:19:31+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "pcm" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T12:28:06+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "pcm" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:33:20+00:00", diff --git a/translated_images/pcm/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/pcm/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 35b920510..000000000 Binary files a/translated_images/pcm/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/pcm/architecture.eedc993a1c576839.webp b/translated_images/pcm/architecture.eedc993a1c576839.webp deleted file mode 100644 index 1b15acea6..000000000 Binary files a/translated_images/pcm/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/pcm/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/pcm/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index c2d6f18aa..000000000 Binary files a/translated_images/pcm/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/pl/.co-op-translator.json b/translated_images/pl/.co-op-translator.json index 3cf14116e..f008e9d4b 100644 --- a/translated_images/pl/.co-op-translator.json +++ b/translated_images/pl/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T13:55:42+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "pl" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T13:55:21+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "pl" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T10:10:17+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "pl" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:36:04+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "pl" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T10:10:23+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "pl" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T10:15:45+00:00", diff --git a/translated_images/pl/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/pl/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 114c713a2..000000000 Binary files a/translated_images/pl/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/pl/architecture.eedc993a1c576839.webp b/translated_images/pl/architecture.eedc993a1c576839.webp deleted file mode 100644 index fc7366ce5..000000000 Binary files a/translated_images/pl/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/pl/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/pl/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index a2a148711..000000000 Binary files a/translated_images/pl/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/pt-BR/.co-op-translator.json b/translated_images/pt-BR/.co-op-translator.json index da5d40d3f..6b30558c7 100644 --- a/translated_images/pt-BR/.co-op-translator.json +++ b/translated_images/pt-BR/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:18:38+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "pt-BR" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:18:15+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "pt-BR" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:53:35+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "pt-BR" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T13:11:52+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "pt-BR" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:53:40+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "pt-BR" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:59:05+00:00", diff --git a/translated_images/pt-BR/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/pt-BR/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index c4d839ea1..000000000 Binary files a/translated_images/pt-BR/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/pt-BR/architecture.eedc993a1c576839.webp b/translated_images/pt-BR/architecture.eedc993a1c576839.webp deleted file mode 100644 index e9f74016c..000000000 Binary files a/translated_images/pt-BR/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/pt-BR/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/pt-BR/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 6cae18b3a..000000000 Binary files a/translated_images/pt-BR/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/pt-PT/.co-op-translator.json b/translated_images/pt-PT/.co-op-translator.json index 3ec9e550c..506ad448e 100644 --- a/translated_images/pt-PT/.co-op-translator.json +++ b/translated_images/pt-PT/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:18:35+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "pt-PT" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:18:11+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "pt-PT" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:53:33+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "pt-PT" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T13:11:50+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "pt-PT" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:53:38+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "pt-PT" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:59:02+00:00", diff --git a/translated_images/pt-PT/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/pt-PT/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 59d801189..000000000 Binary files a/translated_images/pt-PT/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/pt-PT/architecture.eedc993a1c576839.webp b/translated_images/pt-PT/architecture.eedc993a1c576839.webp deleted file mode 100644 index b9219a3d1..000000000 Binary files a/translated_images/pt-PT/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/pt-PT/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/pt-PT/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 63dd107e5..000000000 Binary files a/translated_images/pt-PT/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/ro/.co-op-translator.json b/translated_images/ro/.co-op-translator.json index dc9aa3aa8..92b066121 100644 --- a/translated_images/ro/.co-op-translator.json +++ b/translated_images/ro/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:56:31+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ro" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:56:11+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ro" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:37:54+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ro" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:52:32+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ro" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:37:59+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ro" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T11:43:38+00:00", diff --git a/translated_images/ro/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ro/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 20310c59b..000000000 Binary files a/translated_images/ro/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ro/architecture.eedc993a1c576839.webp b/translated_images/ro/architecture.eedc993a1c576839.webp deleted file mode 100644 index 5350fbc2d..000000000 Binary files a/translated_images/ro/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ro/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ro/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index da270efc4..000000000 Binary files a/translated_images/ro/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/ru/.co-op-translator.json b/translated_images/ru/.co-op-translator.json index 0d935c826..60ade6da3 100644 --- a/translated_images/ru/.co-op-translator.json +++ b/translated_images/ru/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:43:19+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ru" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:42:55+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ru" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:20:32+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ru" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T13:02:44+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ru" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:20:37+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ru" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:25:36+00:00", diff --git a/translated_images/ru/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ru/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 7727b2c6b..000000000 Binary files a/translated_images/ru/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ru/architecture.eedc993a1c576839.webp b/translated_images/ru/architecture.eedc993a1c576839.webp deleted file mode 100644 index 9b8f921cb..000000000 Binary files a/translated_images/ru/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ru/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ru/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index a96741985..000000000 Binary files a/translated_images/ru/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/sk/.co-op-translator.json b/translated_images/sk/.co-op-translator.json index 26ef204ea..af817f5e3 100644 --- a/translated_images/sk/.co-op-translator.json +++ b/translated_images/sk/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:56:29+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "sk" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:56:08+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "sk" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:37:52+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "sk" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:52:29+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "sk" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:37:57+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "sk" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T11:43:32+00:00", diff --git a/translated_images/sk/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/sk/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 08665c563..000000000 Binary files a/translated_images/sk/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/sk/architecture.eedc993a1c576839.webp b/translated_images/sk/architecture.eedc993a1c576839.webp deleted file mode 100644 index 5c5e65de6..000000000 Binary files a/translated_images/sk/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/sk/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/sk/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index bd012d38b..000000000 Binary files a/translated_images/sk/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/sl/.co-op-translator.json b/translated_images/sl/.co-op-translator.json index 562c48363..380d84d97 100644 --- a/translated_images/sl/.co-op-translator.json +++ b/translated_images/sl/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:05:49+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "sl" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:05:30+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "sl" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:54:47+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "sl" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:29:06+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "sl" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:54:52+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "sl" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:00:27+00:00", diff --git a/translated_images/sl/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/sl/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 7d4b92bc8..000000000 Binary files a/translated_images/sl/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/sl/architecture.eedc993a1c576839.webp b/translated_images/sl/architecture.eedc993a1c576839.webp deleted file mode 100644 index 3692efccb..000000000 Binary files a/translated_images/sl/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/sl/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/sl/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index d3d987319..000000000 Binary files a/translated_images/sl/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/sr/.co-op-translator.json b/translated_images/sr/.co-op-translator.json index 47d4ae1ff..48ac767b9 100644 --- a/translated_images/sr/.co-op-translator.json +++ b/translated_images/sr/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:05:44+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "sr" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:05:22+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "sr" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:54:44+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "sr" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:29:02+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "sr" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:54:49+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "sr" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:00:20+00:00", diff --git a/translated_images/sr/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/sr/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 4762d5582..000000000 Binary files a/translated_images/sr/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/sr/architecture.eedc993a1c576839.webp b/translated_images/sr/architecture.eedc993a1c576839.webp deleted file mode 100644 index 589572bff..000000000 Binary files a/translated_images/sr/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/sr/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/sr/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index a25c8daa0..000000000 Binary files a/translated_images/sr/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/sv/.co-op-translator.json b/translated_images/sv/.co-op-translator.json index 4fc2c9e95..fdf71bfad 100644 --- a/translated_images/sv/.co-op-translator.json +++ b/translated_images/sv/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:57:46+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "sv" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:57:23+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "sv" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T10:26:32+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "sv" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:19:53+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "sv" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T10:26:37+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "sv" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T10:34:23+00:00", diff --git a/translated_images/sv/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/sv/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index c817e909f..000000000 Binary files a/translated_images/sv/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/sv/architecture.eedc993a1c576839.webp b/translated_images/sv/architecture.eedc993a1c576839.webp deleted file mode 100644 index f68f4454e..000000000 Binary files a/translated_images/sv/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/sv/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/sv/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index bc0840138..000000000 Binary files a/translated_images/sv/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/sw/.co-op-translator.json b/translated_images/sw/.co-op-translator.json index 24ef59e0c..caa16a002 100644 --- a/translated_images/sw/.co-op-translator.json +++ b/translated_images/sw/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:25:17+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "sw" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:24:51+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "sw" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:20:43+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "sw" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:44:30+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "sw" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:20:49+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "sw" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T11:26:18+00:00", diff --git a/translated_images/sw/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/sw/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 2fdc7ffd3..000000000 Binary files a/translated_images/sw/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/sw/architecture.eedc993a1c576839.webp b/translated_images/sw/architecture.eedc993a1c576839.webp deleted file mode 100644 index fdf7dc7a3..000000000 Binary files a/translated_images/sw/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/sw/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/sw/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index d01e84f63..000000000 Binary files a/translated_images/sw/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/ta/.co-op-translator.json b/translated_images/ta/.co-op-translator.json index 562c52dc6..663636489 100644 --- a/translated_images/ta/.co-op-translator.json +++ b/translated_images/ta/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T17:09:19+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ta" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T17:08:57+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ta" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T12:27:58+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ta" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:19:25+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ta" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T12:28:03+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ta" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:33:12+00:00", diff --git a/translated_images/ta/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ta/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index e481327c6..000000000 Binary files a/translated_images/ta/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ta/architecture.eedc993a1c576839.webp b/translated_images/ta/architecture.eedc993a1c576839.webp deleted file mode 100644 index 3d4bf60b1..000000000 Binary files a/translated_images/ta/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ta/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ta/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 3d5bd67d4..000000000 Binary files a/translated_images/ta/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/te/.co-op-translator.json b/translated_images/te/.co-op-translator.json index 0dd0d3756..1408eec21 100644 --- a/translated_images/te/.co-op-translator.json +++ b/translated_images/te/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T15:52:57+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "te" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T15:52:31+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "te" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T12:44:14+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "te" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:11:15+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "te" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T12:44:21+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "te" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:50:54+00:00", diff --git a/translated_images/te/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/te/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 59a88cad3..000000000 Binary files a/translated_images/te/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/te/architecture.eedc993a1c576839.webp b/translated_images/te/architecture.eedc993a1c576839.webp deleted file mode 100644 index e0d162d24..000000000 Binary files a/translated_images/te/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/te/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/te/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 136704584..000000000 Binary files a/translated_images/te/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/th/.co-op-translator.json b/translated_images/th/.co-op-translator.json index 309c60ff4..e2c886999 100644 --- a/translated_images/th/.co-op-translator.json +++ b/translated_images/th/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:57:43+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "th" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:57:20+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "th" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T10:26:30+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "th" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:19:51+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "th" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T10:26:36+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "th" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T10:34:19+00:00", diff --git a/translated_images/th/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/th/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 039634ced..000000000 Binary files a/translated_images/th/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/th/architecture.eedc993a1c576839.webp b/translated_images/th/architecture.eedc993a1c576839.webp deleted file mode 100644 index fdd3612cc..000000000 Binary files a/translated_images/th/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/th/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/th/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index e0e7a4bd6..000000000 Binary files a/translated_images/th/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/tl/.co-op-translator.json b/translated_images/tl/.co-op-translator.json index 7d7edc229..787ea940a 100644 --- a/translated_images/tl/.co-op-translator.json +++ b/translated_images/tl/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:07:13+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "tl" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:06:55+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "tl" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T09:23:20+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "tl" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:36:49+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "tl" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T09:23:24+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "tl" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T09:28:39+00:00", diff --git a/translated_images/tl/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/tl/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 47e1337dd..000000000 Binary files a/translated_images/tl/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/tl/architecture.eedc993a1c576839.webp b/translated_images/tl/architecture.eedc993a1c576839.webp deleted file mode 100644 index e308245cb..000000000 Binary files a/translated_images/tl/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/tl/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/tl/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index dbbdd83c7..000000000 Binary files a/translated_images/tl/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/tr/.co-op-translator.json b/translated_images/tr/.co-op-translator.json index 2e7566f68..d44d05635 100644 --- a/translated_images/tr/.co-op-translator.json +++ b/translated_images/tr/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T13:55:44+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "tr" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T13:55:25+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "tr" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T10:10:19+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "tr" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:36:07+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "tr" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T10:10:24+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "tr" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T10:15:48+00:00", diff --git a/translated_images/tr/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/tr/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 4c3a4a799..000000000 Binary files a/translated_images/tr/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/tr/architecture.eedc993a1c576839.webp b/translated_images/tr/architecture.eedc993a1c576839.webp deleted file mode 100644 index 1c223d333..000000000 Binary files a/translated_images/tr/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/tr/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/tr/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index d044b8d2e..000000000 Binary files a/translated_images/tr/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/uk/.co-op-translator.json b/translated_images/uk/.co-op-translator.json index df13bf072..8cb8847ea 100644 --- a/translated_images/uk/.co-op-translator.json +++ b/translated_images/uk/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T17:25:39+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "uk" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T17:25:10+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "uk" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T12:11:43+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "uk" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:10:38+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "uk" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T12:11:48+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "uk" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T12:17:54+00:00", diff --git a/translated_images/uk/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/uk/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 773dc7264..000000000 Binary files a/translated_images/uk/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/uk/architecture.eedc993a1c576839.webp b/translated_images/uk/architecture.eedc993a1c576839.webp deleted file mode 100644 index c8641bbfd..000000000 Binary files a/translated_images/uk/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/uk/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/uk/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index c780cbc7e..000000000 Binary files a/translated_images/uk/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/ur/.co-op-translator.json b/translated_images/ur/.co-op-translator.json index c42c2b177..94612a520 100644 --- a/translated_images/ur/.co-op-translator.json +++ b/translated_images/ur/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:18:31+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "ur" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:18:07+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "ur" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:34:31+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "ur" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T10:26:47+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "ur" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:34:36+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "ur" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:39:29+00:00", diff --git a/translated_images/ur/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/ur/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 89fff7a99..000000000 Binary files a/translated_images/ur/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/ur/architecture.eedc993a1c576839.webp b/translated_images/ur/architecture.eedc993a1c576839.webp deleted file mode 100644 index 8bef9105c..000000000 Binary files a/translated_images/ur/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/ur/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/ur/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 552336752..000000000 Binary files a/translated_images/ur/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/vi/.co-op-translator.json b/translated_images/vi/.co-op-translator.json index 282032792..419fa197c 100644 --- a/translated_images/vi/.co-op-translator.json +++ b/translated_images/vi/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:32:08+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "vi" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:31:47+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "vi" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T11:00:06+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "vi" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T11:59:49+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "vi" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T11:00:11+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "vi" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T11:06:57+00:00", diff --git a/translated_images/vi/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/vi/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index fe70da499..000000000 Binary files a/translated_images/vi/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/vi/architecture.eedc993a1c576839.webp b/translated_images/vi/architecture.eedc993a1c576839.webp deleted file mode 100644 index e6050f5c1..000000000 Binary files a/translated_images/vi/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/vi/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/vi/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 72d82d5fb..000000000 Binary files a/translated_images/vi/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/zh-CN/.co-op-translator.json b/translated_images/zh-CN/.co-op-translator.json index 640279f40..d35f3a03f 100644 --- a/translated_images/zh-CN/.co-op-translator.json +++ b/translated_images/zh-CN/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T14:18:33+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "zh-CN" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T14:18:12+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "zh-CN" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:34:33+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "zh-CN" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T10:26:49+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "zh-CN" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:34:37+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "zh-CN" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:39:32+00:00", diff --git a/translated_images/zh-CN/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/zh-CN/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index bbebc8353..000000000 Binary files a/translated_images/zh-CN/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/zh-CN/architecture.eedc993a1c576839.webp b/translated_images/zh-CN/architecture.eedc993a1c576839.webp deleted file mode 100644 index 107607a8f..000000000 Binary files a/translated_images/zh-CN/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/zh-CN/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/zh-CN/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 5c293bc56..000000000 Binary files a/translated_images/zh-CN/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/zh-HK/.co-op-translator.json b/translated_images/zh-HK/.co-op-translator.json index b24a2b8dc..46a02999a 100644 --- a/translated_images/zh-HK/.co-op-translator.json +++ b/translated_images/zh-HK/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:43:35+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "zh-HK" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:43:13+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "zh-HK" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:49:59+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "zh-HK" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:54:45+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "zh-HK" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:50:04+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "zh-HK" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:56:18+00:00", diff --git a/translated_images/zh-HK/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/zh-HK/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 55dffe67d..000000000 Binary files a/translated_images/zh-HK/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/zh-HK/architecture.eedc993a1c576839.webp b/translated_images/zh-HK/architecture.eedc993a1c576839.webp deleted file mode 100644 index 0677a6cac..000000000 Binary files a/translated_images/zh-HK/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/zh-HK/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/zh-HK/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 310e670e9..000000000 Binary files a/translated_images/zh-HK/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/zh-MO/.co-op-translator.json b/translated_images/zh-MO/.co-op-translator.json index a2d181fbb..d74ac0353 100644 --- a/translated_images/zh-MO/.co-op-translator.json +++ b/translated_images/zh-MO/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:43:32+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "zh-MO" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:43:09+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "zh-MO" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:49:56+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "zh-MO" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:54:43+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "zh-MO" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:50:02+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "zh-MO" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:56:15+00:00", diff --git a/translated_images/zh-MO/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/zh-MO/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index b8b12c5d9..000000000 Binary files a/translated_images/zh-MO/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/zh-MO/architecture.eedc993a1c576839.webp b/translated_images/zh-MO/architecture.eedc993a1c576839.webp deleted file mode 100644 index 385a7acff..000000000 Binary files a/translated_images/zh-MO/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/zh-MO/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/zh-MO/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index 14aa13978..000000000 Binary files a/translated_images/zh-MO/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translated_images/zh-TW/.co-op-translator.json b/translated_images/zh-TW/.co-op-translator.json index ff7e97aa5..df103c63f 100644 --- a/translated_images/zh-TW/.co-op-translator.json +++ b/translated_images/zh-TW/.co-op-translator.json @@ -1,10 +1,4 @@ { - "00-tool-integration.3f573138c2fa4eb2.webp": { - "original_hash": "4e132d8f4b1c5d7d67511ebb718784a6", - "translation_date": "2026-03-03T16:43:38+00:00", - "source_file": "diagrams/00-tool-integration.png", - "language_code": "zh-TW" - }, "04-tools-spring-boot.a1bd8ae23cd098e1.webp": { "original_hash": "79a86ab27b38d69feb8b17f94af99288", "translation_date": "2026-03-03T16:43:16+00:00", @@ -35,12 +29,6 @@ "source_file": "05-mcp/images/agentic-scope.png", "language_code": "zh-TW" }, - "architecture.eedc993a1c576839.webp": { - "original_hash": "add139926cd5d568e3ba2c38eb32312b", - "translation_date": "2026-01-16T08:50:00+00:00", - "source_file": "00-quick-start/images/architecture.png", - "language_code": "zh-TW" - }, "chain-of-thought.5cff6630e2657e2a.webp": { "original_hash": "c396f6bd0295f2bda88ba3ccaaa0f39b", "translation_date": "2026-02-16T12:54:47+00:00", @@ -203,12 +191,6 @@ "source_file": "02-prompt-engineering/images/how-langchain4j-fits.png", "language_code": "zh-TW" }, - "langchain-concept.ad1fe6cf063515e1.webp": { - "original_hash": "7b421aa8262309aaf85a573fa7940b20", - "translation_date": "2026-01-16T08:50:06+00:00", - "source_file": "00-quick-start/images/langchain-concept.png", - "language_code": "zh-TW" - }, "mcp-architecture.b3156d787a4ceac9.webp": { "original_hash": "6ef1f9751daa7566fae670d97f023c49", "translation_date": "2026-01-16T08:56:21+00:00", diff --git a/translated_images/zh-TW/00-tool-integration.3f573138c2fa4eb2.webp b/translated_images/zh-TW/00-tool-integration.3f573138c2fa4eb2.webp deleted file mode 100644 index 07c0f745a..000000000 Binary files a/translated_images/zh-TW/00-tool-integration.3f573138c2fa4eb2.webp and /dev/null differ diff --git a/translated_images/zh-TW/architecture.eedc993a1c576839.webp b/translated_images/zh-TW/architecture.eedc993a1c576839.webp deleted file mode 100644 index bae643cfa..000000000 Binary files a/translated_images/zh-TW/architecture.eedc993a1c576839.webp and /dev/null differ diff --git a/translated_images/zh-TW/langchain-concept.ad1fe6cf063515e1.webp b/translated_images/zh-TW/langchain-concept.ad1fe6cf063515e1.webp deleted file mode 100644 index d714ed811..000000000 Binary files a/translated_images/zh-TW/langchain-concept.ad1fe6cf063515e1.webp and /dev/null differ diff --git a/translations/ar/.co-op-translator.json b/translations/ar/.co-op-translator.json index 08c18baf5..70a791b36 100644 --- a/translations/ar/.co-op-translator.json +++ b/translations/ar/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ar" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T00:26:35+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T08:16:30+00:00", "source_file": "01-introduction/README.md", "language_code": "ar" }, @@ -18,20 +18,20 @@ "language_code": "ar" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T00:28:19+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T08:11:23+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ar" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T00:29:23+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T08:15:28+00:00", "source_file": "03-rag/README.md", "language_code": "ar" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T12:11:45+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T08:14:05+00:00", "source_file": "04-tools/README.md", "language_code": "ar" }, @@ -54,8 +54,8 @@ "language_code": "ar" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:56:47+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T08:09:50+00:00", "source_file": "README.md", "language_code": "ar" }, @@ -72,14 +72,14 @@ "language_code": "ar" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T00:32:07+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T08:12:00+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ar" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T00:32:47+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T08:12:41+00:00", "source_file": "docs/TESTING.md", "language_code": "ar" } diff --git a/translations/ar/00-quick-start/README.md b/translations/ar/00-quick-start/README.md deleted file mode 100644 index 8db284f97..000000000 --- a/translations/ar/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# الوحدة 00: البداية السريعة - -## جدول المحتويات - -- [مقدمة](../../../00-quick-start) -- [ما هو LangChain4j؟](../../../00-quick-start) -- [اعتمادات LangChain4j](../../../00-quick-start) -- [المتطلبات المسبقة](../../../00-quick-start) -- [الإعداد](../../../00-quick-start) - - [1. احصل على رمز GitHub الخاص بك](../../../00-quick-start) - - [2. ضبط الرمز الخاص بك](../../../00-quick-start) -- [تشغيل الأمثلة](../../../00-quick-start) - - [1. الدردشة الأساسية](../../../00-quick-start) - - [2. أنماط الإدخال](../../../00-quick-start) - - [3. استدعاء الدوال](../../../00-quick-start) - - [4. أسئلة وأجوبة الوثائق (RAG السهل)](../../../00-quick-start) - - [5. الذكاء الاصطناعي المسؤول](../../../00-quick-start) -- [ما الذي يُظهره كل مثال](../../../00-quick-start) -- [الخطوات التالية](../../../00-quick-start) -- [استكشاف الأخطاء وإصلاحها](../../../00-quick-start) - -## مقدمة - -تهدف هذه البداية السريعة إلى تمكينك من بدء استخدام LangChain4j بأسرع وقت ممكن. تغطي الأساسيات المطلقة لبناء تطبيقات الذكاء الاصطناعي باستخدام LangChain4j ونماذج GitHub. في الوحدات التالية، ستنتقل إلى Azure OpenAI و GPT-5.2 وتغوص أعمق في كل مفهوم. - -## ما هو LangChain4j؟ - -LangChain4j هو مكتبة Java تبسط بناء تطبيقات مدعومة بالذكاء الاصطناعي. بدلاً من التعامل مع عملاء HTTP وتحليل JSON، تعمل بواجهات برمجة تطبيقات Java نظيفة. - -تشير كلمة "chain" في LangChain إلى ربط مكونات متعددة معًا - قد تربط مطالبة مع نموذج ثم محلل، أو تربط عدة استدعاءات للذكاء الاصطناعي معًا حيث تغذي ناتج واحد الإدخال التالي. تركز هذه البداية السريعة على الأساسيات قبل استكشاف سلاسل أكثر تعقيدًا. - -مفهوم ربط LangChain4j - -*ربط المكونات في LangChain4j - الكتل البنائية تتصل لإنشاء تدفقات عمل ذكية قوية* - -سنستخدم ثلاثة مكونات أساسية: - -**ChatModel** - واجهة للتفاعل مع نماذج الذكاء الاصطناعي. استدعِ `model.chat("prompt")` واحصل على سلسلة رد. نستخدم `OpenAiOfficialChatModel` الذي يعمل مع نقاط نهاية متوافقة مع OpenAI مثل نماذج GitHub. - -**AiServices** - ينشئ واجهات خدمات ذكاء اصطناعي آمنة من حيث النوع. عرّف طرقًا، علّمها بـ `@Tool`، ويتولى LangChain4j التنفيذ. يستدعي الذكاء الاصطناعي طرق Java الخاصة بك تلقائيًا عند الحاجة. - -**MessageWindowChatMemory** - يحتفظ بتاريخ المحادثة. بدون هذا، كل طلب مستقل. به، يتذكّر الذكاء الاصطناعي الرسائل السابقة ويحافظ على السياق عبر دورات متعددة. - -هندسة LangChain4j - -*هندسة LangChain4j - المكونات الأساسية تعمل معًا لتشغيل تطبيقات الذكاء الاصطناعي الخاصة بك* - -## اعتمادات LangChain4j - -تستخدم هذه البداية السريعة ثلاث اعتمادات Maven في [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -يوفر الموديول `langchain4j-open-ai-official` فئة `OpenAiOfficialChatModel` التي تتصل بواجهات API المتوافقة مع OpenAI. تستخدم نماذج GitHub نفس تنسيق API، لذا لا حاجة إلى محول خاص - فقط وجه عنوان القاعدة إلى `https://models.github.ai/inference`. - -يوفر الموديول `langchain4j-easy-rag` تقسيم الوثائق التلقائي، والتضمين، والاسترجاع حتى تتمكن من بناء تطبيقات RAG دون تكوين يدوي لكل خطوة. - -## المتطلبات المسبقة - -**هل تستخدم Dev Container؟** Java و Maven مثبتان بالفعل. أنت فقط بحاجة إلى رمز الوصول الشخصي من GitHub. - -**التطوير المحلي:** -- Java 21+، Maven 3.9+ -- رمز وصول شخصي من GitHub (التعليمات أدناه) - -> **ملاحظة:** تستخدم هذه الوحدة `gpt-4.1-nano` من نماذج GitHub. لا تعدل اسم النموذج في الكود - هو مهيأ للعمل مع نماذج GitHub المتاحة. - -## الإعداد - -### 1. احصل على رمز GitHub الخاص بك - -1. انتقل إلى [إعدادات GitHub → رموز الوصول الشخصية](https://github.com/settings/personal-access-tokens) -2. اضغط على "إنشاء رمز جديد" -3. ضع اسمًا وصفيًا (مثلاً: "LangChain4j Demo") -4. حدد تاريخ انتهاء صلاحية (7 أيام موصى بها) -5. تحت "أذونات الحساب"، ابحث عن "Models" واضبطها على "قراءة فقط" -6. اضغط على "إنشاء رمز" -7. انسخ وصِل رمزك - لن تراه مرة أخرى - -### 2. ضبط الرمز الخاص بك - -**الخيار 1: استخدام VS Code (موصى به)** - -إذا كنت تستخدم VS Code، أضف الرمز الخاص بك إلى ملف `.env` في جذر المشروع: - -إذا لم يكن ملف `.env` موجودًا، انسخ `.env.example` إلى `.env` أو أنشئ ملف `.env` جديد في جذر المشروع. - -**مثال على ملف `.env`:** -```bash -# في /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -ثم يمكنك ببساطة النقر بزر الفأرة الأيمن على أي ملف تجريبي (مثل `BasicChatDemo.java`) في المستكشف واختيار **"Run Java"** أو استخدام تكوينات التشغيل من لوحة Run و Debug. - -**الخيار 2: استخدام الطرفية** - -اضبط الرمز كمتغير بيئة: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## تشغيل الأمثلة - -**باستخدام VS Code:** فقط انقر بزر الفأرة الأيمن على أي ملف تجريبي في المستكشف واختر **"Run Java"**، أو استخدم تكوينات التشغيل من لوحة Run و Debug (تأكد من إضافة الرمز إلى ملف `.env` أولاً). - -**باستخدام Maven:** بدلاً من ذلك، يمكنك التشغيل من سطر الأوامر: - -### 1. الدردشة الأساسية - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. أنماط الإدخال - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -يعرض أنماط بدون أمثلة، مع أمثلة قليلة، السلسلة الفكرية، والإدخال القائم على الأدوار. - -### 3. استدعاء الدوال - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -الذكاء الاصطناعي يستدعي طرق Java الخاصة بك تلقائيًا عند الحاجة. - -### 4. أسئلة وأجوبة الوثائق (RAG السهل) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -اطرح أسئلة حول مستنداتك باستخدام Easy RAG مع التضمين والاسترجاع التلقائي. - -### 5. الذكاء الاصطناعي المسؤول - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -شاهد كيف تمنع فلاتر سلامة الذكاء الاصطناعي المحتوى الضار. - -## ما الذي يُظهره كل مثال - -**الدردشة الأساسية** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -ابدأ هنا لرؤية LangChain4j في أبسط صوره. ستنشئ `OpenAiOfficialChatModel`، ترسل مطالبة باستخدام `.chat()`، وتحصل على رد. هذا يوضح الأساس: كيف تهيئ النماذج بنقاط نهاية ومفاتيح API مخصصة. بمجرد فهمك لهذا النمط، يبنى كل شيء آخر عليه. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 جرّب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) واطرح: -> - "كيف يمكنني التبديل من نماذج GitHub إلى Azure OpenAI في هذا الكود؟" -> - "ما هي المعلمات الأخرى التي يمكنني تكوينها في OpenAiOfficialChatModel.builder()؟" -> - "كيف أضيف ردود تدفق بدلاً من انتظار الرد الكامل؟" - -**هندسة المطالبات** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -الآن بعد أن عرفت كيف تتحدث إلى نموذج، دعنا نستكشف ما تقول له. تستخدم هذه التجربة نفس إعداد النموذج لكنها تعرض خمسة أنماط مختلفة من المطالبات. جرّب مطالبات بدون أمثلة مباشرة، مطالبات مع أمثلة قليلة تتعلم منها، مطالبات السلسلة الفكرية التي تكشف خطوات التفكير، والمطالبات القائمة على الأدوار التي تحدد السياق. سترى كيف يعطي نفس النموذج نتائج مختلفة تمامًا بناءً على كيفية صياغة طلبك. - -تُظهر التجربة أيضًا قوالب المطالبات، وهي طريقة قوية لإنشاء مطالبات قابلة لإعادة الاستخدام مع متغيرات. -يُظهر المثال أدناه مطالبة تستخدم قالب LangChain4j `PromptTemplate` لملء المتغيرات. سيجيب الذكاء الاصطناعي بناءً على الوجهة والنشاط المقدمين. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 جرّب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) واطرح: -> - "ما الفرق بين مطالبة بدون أمثلة ومطالبة مع أمثلة قليلة، ومتى أستخدم كل منهما؟" -> - "كيف يؤثر متغير درجة الحرارة على استجابات النموذج؟" -> - "ما هي بعض التقنيات لمنع هجمات حقن المطالبات في الإنتاج؟" -> - "كيف يمكنني إنشاء كائنات PromptTemplate قابلة لإعادة الاستخدام للأنماط الشائعة؟" - -**تكامل الأدوات** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -هنا يصبح LangChain4j قويًا. ستستخدم `AiServices` لإنشاء مساعد ذكاء اصطناعي يمكنه استدعاء طرق Java الخاصة بك. فقط عين الطرق بـ `@Tool("الوصف")` ويتولى LangChain4j الباقي - يقرر الذكاء الاصطناعي تلقائيًا متى يستخدم كل أداة بناءً على طلب المستخدم. توضح هذه التجربة استدعاء الدوال، وهي تقنية رئيسية لبناء ذكاء اصطناعي يمكنه اتخاذ إجراءات، وليس مجرد الإجابة عن الأسئلة. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 جرّب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) واطرح: -> - "كيف تعمل التعليمة @Tool وماذا يفعل LangChain4j معها خلف الكواليس؟" -> - "هل يمكن للذكاء الاصطناعي استدعاء أدوات متعددة على التوالي لحل مشكلات معقدة؟" -> - "ماذا يحدث إذا رمت أداة استثناء - كيف أتعامل مع الأخطاء؟" -> - "كيف أدمج واجهة برمجة تطبيقات حقيقية بدلاً من مثال الآلة الحاسبة هذا؟" - -**أسئلة وأجوبة الوثائق (RAG السهل)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -هنا ستشاهد RAG (التوليد المعزز بالاسترجاع) باستخدام نهج LangChain4j "Easy RAG". تُحمّل الوثائق، تُقسّم تلقائيًا وتُدمج في ذاكرة داخلية، ثم يزود مسترجع المحتوى الذكاء الاصطناعي بالقطع ذات الصلة وقت الاستعلام. يجيب الذكاء الاصطناعي بناءً على مستنداتك، وليس معرفته العامة. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 جرّب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) واطرح: -> - "كيف يمنع RAG الهلوسة في الذكاء الاصطناعي مقارنة باستخدام بيانات تدريب النموذج؟" -> - "ما الفرق بين هذا النهج السهل وخط أنابيب RAG مخصص؟" -> - "كيف أقوم بتوسيعه ليتعامل مع مستندات متعددة أو قواعد معرفة أكبر؟" - -**الذكاء الاصطناعي المسؤول** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -ابنِ أمان الذكاء الاصطناعي مع دفاع متعدد الطبقات. تعرض هذه التجربة طبقتين من الحماية تعملان معًا: - -**الجزء 1: قواعد حماية الإدخال في LangChain4j** - تمنع المطالبات الخطرة قبل وصولها إلى LLM. أنشئ قواعد حماية مخصصة تتحقق من كلمات أو أنماط محظورة. تعمل هذه في كودك، لذا فهي سريعة ومجانية. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**الجزء 2: فلاتر السلامة لدى المزود** - لدى نماذج GitHub مرشحات مدمجة تلتقط ما قد تفوته قواعد الحماية لديك. سترى حجبًا صارمًا (أخطاء HTTP 400) للانتهاكات الجسيمة والرفض اللطيف حيث يرفض الذكاء الاصطناعي بأدب. - -> **🤖 جرّب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) واطرح: -> - "ما هو InputGuardrail وكيف أصنع واحدًا بنفسي؟" -> - "ما الفرق بين الحجب الصارم والرفض اللطيف؟" -> - "لماذا نستخدم كلًا من قواعد الحماية وفلاتر المزود معًا؟" - -## الخطوات التالية - -**الوحدة التالية:** [01-introduction - البدء مع LangChain4j](../01-introduction/README.md) - ---- - -**التنقل:** [← العودة إلى الرئيسية](../README.md) | [التالي: الوحدة 01 - مقدمة →](../01-introduction/README.md) - ---- - -## استكشاف الأخطاء وإصلاحها - -### بناء Maven لأول مرة - -**المشكلة**: يأخذ الأمر `mvn clean compile` أو `mvn package` الأول وقتًا طويلاً (10-15 دقيقة) - -**السبب**: يحتاج Maven إلى تنزيل جميع اعتمادات المشروع (Spring Boot، مكتبات LangChain4j، مجموعات Azure SDK، إلخ) في البناء الأول. - -**الحل**: هذا سلوك طبيعي. ستكون عمليات البناء اللاحقة أسرع بكثير لأن الاعتمادات مخزنة محليًا. يعتمد وقت التنزيل على سرعة الشبكة الخاصة بك. - -### صياغة أوامر Maven في PowerShell - -**المشكلة**: تفشل أوامر Maven بخطأ `Unknown lifecycle phase ".mainClass=..."` -**السبب**: يقوم PowerShell بتفسير `=` كعامل تخصيص متغير، مما يكسر بناء جملة خصائص Maven - -**الحل**: استخدم عامل إيقاف التحليل `--%` قبل أمر Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -عامل `--%` يخبر PowerShell بتمرير جميع الوسائط المتبقية حرفيًا إلى Maven دون تفسير. - -### عرض الرموز التعبيرية في Windows PowerShell - -**المشكلة**: تظهر استجابات الذكاء الاصطناعي حروفًا تالفة (مثل `????` أو `â??`) بدلاً من الرموز التعبيرية في PowerShell - -**السبب**: الترميز الافتراضي لـ PowerShell لا يدعم الرموز التعبيرية بنمط UTF-8 - -**الحل**: شغّل هذا الأمر قبل تنفيذ تطبيقات Java: -```cmd -chcp 65001 -``` - -هذا يجبر الترميز UTF-8 في الطرفية. بدلاً من ذلك، استخدم Windows Terminal الذي يدعم Unicode بشكل أفضل. - -### تصحيح أخطاء استدعاءات API - -**المشكلة**: أخطاء مصادقة، حدود معدلات، أو استجابات غير متوقعة من نموذج الذكاء الاصطناعي - -**الحل**: تتضمن الأمثلة `.logRequests(true)` و `.logResponses(true)` لعرض استدعاءات API في الكونسول. هذا يساعد في معالجة أخطاء المصادقة، حدود المعدلات، أو الاستجابات غير المتوقعة. قم بإزالة هذه العلامات في بيئة الإنتاج لتقليل ضوضاء السجل. - ---- - - -**تنويه**: -تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). على الرغم من سعينا لتحقيق الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. ينبغي اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق به. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة. - \ No newline at end of file diff --git a/translations/ar/01-introduction/README.md b/translations/ar/01-introduction/README.md index 9bc40d080..72ad51947 100644 --- a/translations/ar/01-introduction/README.md +++ b/translations/ar/01-introduction/README.md @@ -1,87 +1,87 @@ -# الوحدة 01: بدء العمل مع LangChain4j +# الوحدة 01: البدء مع LangChain4j ## جدول المحتويات -- [عرض الفيديو](../../../01-introduction) -- [ما ستتعلمه](../../../01-introduction) -- [المتطلبات الأساسية](../../../01-introduction) -- [فهم المشكلة الأساسية](../../../01-introduction) -- [فهم الرموز](../../../01-introduction) -- [كيفية عمل الذاكرة](../../../01-introduction) -- [كيفية استخدام هذا مع LangChain4j](../../../01-introduction) -- [نشر بنية تحتية Azure OpenAI](../../../01-introduction) -- [تشغيل التطبيق محليًا](../../../01-introduction) -- [استخدام التطبيق](../../../01-introduction) - - [الدردشة بدون حالة (اللوحة اليسرى)](../../../01-introduction) - - [الدردشة مع الحالة (اللوحة اليمنى)](../../../01-introduction) -- [الخطوات التالية](../../../01-introduction) - -## عرض الفيديو +- [جولة فيديو](#جولة-فيديو) +- [ما ستتعلمه](#ما-ستتعلمه) +- [المتطلبات المسبقة](#المتطلبات-المسبقة) +- [فهم المشكلة الأساسية](#فهم-المشكلة-الأساسية) +- [فهم الرموز](#فهم-الرموز) +- [كيفية عمل الذاكرة](#كيفية-عمل-الذاكرة) +- [كيفية استخدام هذا لـ LangChain4j](#كيفية-استخدام-هذا-لـ-langchain4j) +- [نشر بنية Azure OpenAI التحتية](#نشر-بنية-azure-openai-التحتية) +- [تشغيل التطبيق محليًا](#تشغيل-التطبيق-محليًا) +- [استخدام التطبيق](#استخدام-التطبيق) + - [دردشة بدون حالة (اللوحة اليسرى)](#دردشة-بدون-حالة-اللوحة-اليسرى) + - [دردشة بحالة (اللوحة اليمنى)](#دردشة-بحالة-اللوحة-اليمنى) +- [الخطوات التالية](#الخطوات-التالية) + +## جولة فيديو شاهد هذه الجلسة المباشرة التي تشرح كيفية البدء مع هذه الوحدة: -بدء العمل مع LangChain4j - جلسة مباشرة +البدء مع LangChain4j - جلسة مباشرة ## ما ستتعلمه -في البداية السريعة، استخدمت نماذج GitHub لإرسال المطالبات، واستدعاء الأدوات، وبناء خط أنابيب RAG، واختبار الضوابط الأمنية. أظهرت تلك العروض ما هو ممكن — الآن ننتقل إلى Azure OpenAI وGPT-5.2 ونبدأ في بناء تطبيقات أسلوب الإنتاج. تركز هذه الوحدة على الذكاء الاصطناعي الحواري الذي يتذكر السياق ويحافظ على الحالة — المفاهيم التي استخدمتها نماذج البداية السريعة خلف الكواليس ولكنها لم تشرحها. +هذه هي نقطة البداية الخاصة بك مع LangChain4j و Azure OpenAI. نبدأ بالأساسيات ونبدأ ببناء تطبيقات بأسلوب الإنتاج. تركز هذه الوحدة على الذكاء الاصطناعي الحواري الذي يتذكر السياق ويحافظ على الحالة — المفاهيم الأساسية التي تبني عليها كل الوحدات اللاحقة. -سنستخدم GPT-5.2 من Azure OpenAI طوال هذا الدليل لأن قدراته المتقدمة على الاستدلال تجعل سلوك الأنماط المختلفة أكثر وضوحًا. عندما تضيف الذاكرة، سترى الفرق بوضوح. هذا يجعل من الأسهل فهم ما يقدمه كل مكون لتطبيقك. +سنستخدم GPT-5.2 من Azure OpenAI في جميع أنحاء هذا الدليل لأن قدراته المتقدمة في الاستدلال تجعل سلوك الأنماط المختلفة أكثر وضوحًا. عند إضافة الذاكرة، سترى الفرق بوضوح. هذا يجعل من الأسهل فهم ما يضيفه كل مكون إلى تطبيقك. -ستبني تطبيقًا واحدًا يعرض كلا النمطين: +ستبني تطبيقًا واحدًا يوضح كلا النمطين: -**الدردشة بدون حالة** - كل طلب مستقل. النموذج لا يملك ذاكرة عن الرسائل السابقة. هذا هو النمط الذي استخدمته في البداية السريعة. +**الدردشة بدون حالة** - كل طلب مستقل. النموذج لا يتذكر الرسائل السابقة. هذه هي أبسط نقطة بداية. -**المحادثة مع الحالة** - كل طلب يتضمن تاريخ المحادثة. النموذج يحتفظ بالسياق عبر عدة جولات. هذا ما تتطلبه تطبيقات الإنتاج. +**المحادثة بحالة** - كل طلب يشمل تاريخ المحادثة. النموذج يحافظ على السياق عبر عدة تبادلات. هذا ما تتطلبه تطبيقات الإنتاج. -## المتطلبات الأساسية +## المتطلبات المسبقة -- اشتراك Azure مع وصول إلى Azure OpenAI +- اشتراك في Azure مع إمكانية الوصول إلى Azure OpenAI - Java 21، Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **ملاحظة:** Java وMaven وAzure CLI وAzure Developer CLI (azd) مثبتة مسبقًا في الحاوية التطويرية المقدمة. +> **ملاحظة:** Java و Maven و Azure CLI و Azure Developer CLI (azd) مثبتة مسبقًا في حاوية التطوير المقدمة. -> **ملاحظة:** تستخدم هذه الوحدة GPT-5.2 على Azure OpenAI. التهيئة تتم تلقائيًا عبر `azd up` - لا تقم بتعديل اسم النموذج في الكود. +> **ملاحظة:** تستخدم هذه الوحدة GPT-5.2 على Azure OpenAI. يتم تكوين النشر تلقائيًا عبر `azd up` - لا تقم بتعديل اسم النموذج في الشفرة. ## فهم المشكلة الأساسية -نماذج اللغة عديمة الحالة. كل استدعاء API مستقل. إذا أرسلت "اسمي جون" ثم سألت "ما اسمي؟"، النموذج لا يعلم أنك قدمت نفسك للتو. يعامل كل طلب كما لو أنها أول محادثة تجريها. +نماذج اللغة لا تحتفظ بالحالة. كل استدعاء API مستقل. إذا أرسلت "اسمي جون" ثم سألت "ما اسمي؟"، فلا يعلم النموذج أنك قدمت نفسك للتو. يعامل كل طلب كما لو كان أول محادثة تجريها على الإطلاق. -هذا جيد لأسئلة وأجوبة بسيطة لكنه غير مفيد للتطبيقات الحقيقية. تحتاج روبوتات خدمة العملاء إلى تذكر ما قلته لهم. المساعدون الشخصيون يحتاجون إلى السياق. أي محادثة متعددة الجولات تتطلب ذاكرة. +هذا مقبول للأسئلة البسيطة والأجوبة لكنه غير مفيد للتطبيقات الحقيقية. بحاجة روبوتات خدمة العملاء لتذكر ما قلته لهم. المساعدون الشخصيون يحتاجون للسياق. أي محادثة متعددة التناوب تتطلب ذاكرة. -يوضح المخطط التالي الفرق بين النهجين — على اليسار، استدعاء بدون حالة ينسى اسمك؛ وعلى اليمين، استدعاء مع الحالة مدعوم بـ ChatMemory التي تتذكره. +الرسم التوضيحي التالي يقارن بين النهجين — على اليسار، استدعاء بدون حالة ينسى اسمك؛ وعلى اليمين، استدعاء بحالة مدعوم بـ ChatMemory يتذكره. -المحادثات بدون حالة مقابل المحادثات مع حالة +المحادثات بدون حالة مقابل بحالة -*الفرق بين المحادثات بدون حالة (استدعاءات مستقلة) والمحادثات مع حالة (مدركة للسياق)* +*الفرق بين المحادثات بدون حالة (استدعاءات مستقلة) وبحالة (مدركة للسياق)* ## فهم الرموز -قبل الخوض في المحادثات، من المهم فهم الرموز - الوحدات الأساسية للنص التي تعالجها نماذج اللغة: +قبل الخوض في المحادثات، من المهم فهم الرموز — وحدات النص الأساسية التي تعالجها نماذج اللغة: شرح الرموز -*مثال على كيفية تقسيم النص إلى رموز - "أحب الذكاء الاصطناعي!" تصبح 4 وحدات معالجة منفصلة* +*مثال على كيفية تقسيم النص إلى رموز - "I love AI!" تصبح 4 وحدات معالجة منفصلة* -الرموز هي كيفية قياس نماذج الذكاء الاصطناعي ومعالجتها للنص. الكلمات، علامات الترقيم، وحتى الفراغات يمكن أن تكون رموزًا. لدى نموذجك حد لعدد الرموز التي يمكنه معالجتها مرة واحدة (400,000 لـ GPT-5.2، مع ما يصل إلى 272,000 رمز إدخال و128,000 رمز إخراج). يساعد فهم الرموز في إدارة طول المحادثة والتكاليف. +الرموز هي كيفية قياس ومعالجة نماذج الذكاء الاصطناعي للنص. الكلمات، علامات الترقيم، وحتى المساحات قد تكون رموزًا. للنموذج حد أقصى لعدد الرموز التي يمكنه معالجتها مرة واحدة (400,000 لـ GPT-5.2، مع ما يصل إلى 272,000 رمز إدخال و 128,000 رمز إخراج). فهم الرموز يساعدك على إدارة طول المحادثة والتكاليف. ## كيفية عمل الذاكرة -تحل ذاكرة الدردشة مشكلة عديم الحالة من خلال الاحتفاظ بتاريخ المحادثة. قبل إرسال طلبك للنموذج، يقوم الإطار بإضافة الرسائل السابقة ذات الصلة في البداية. عندما تسأل "ما اسمي؟"، يرسل النظام فعليًا كامل تاريخ المحادثة، مما يسمح للنموذج برؤية أنك قلت سابقًا "اسمي جون." +تحل ذاكرة الدردشة مشكلة عدم الاحتفاظ بالحالة من خلال الحفاظ على تاريخ المحادثة. قبل إرسال طلبك إلى النموذج، يقوم الإطار بإضافة الرسائل السابقة ذات الصلة في البداية. عندما تسأل "ما اسمي؟"، يرسل النظام فعليًا تاريخ المحادثة بالكامل، مما يسمح للنموذج برؤية أنك قلت سابقًا "اسمي جون". -يوفر LangChain4j تنفيذات ذاكرة تتعامل مع هذا تلقائيًا. تختار عدد الرسائل التي تحتفظ بها ويدير الإطار نافذة السياق. يوضح المخطط أدناه كيف يحافظ MessageWindowChatMemory على نافذة انزلاقية للرسائل الحديثة. +يوفر LangChain4j تطبيقات للذاكرة تتعامل مع هذا تلقائيًا. تختار عدد الرسائل التي تريد الاحتفاظ بها ويتولى الإطار إدارة نافذة السياق. يوضح الرسم أدناه كيف يحافظ MessageWindowChatMemory على نافذة منزلقة من الرسائل الأخيرة. مفهوم نافذة الذاكرة -*يحافظ MessageWindowChatMemory على نافذة منزلقة من الرسائل الحديثة، ويتخلص تلقائيًا من الرسائل القديمة* +*MessageWindowChatMemory يحافظ على نافذة منزلقة من الرسائل الأخيرة، ويحذف الرسائل القديمة تلقائيًا* -## كيفية استخدام هذا مع LangChain4j +## كيفية استخدام هذا لـ LangChain4j -توسّع هذه الوحدة البداية السريعة من خلال دمج Spring Boot وإضافة ذاكرة المحادثة. إليك كيف تتجمع القطع معًا: +تدمج هذه الوحدة Spring Boot وتضيف ذاكرة المحادثة. هكذا تتكامل القطع معًا: -**المكتبات:** أضف مكتبتين لـ LangChain4j: +**التبعيات** - أضف مكتبتين من LangChain4j: ```xml @@ -94,7 +94,7 @@ ``` -**نموذج الدردشة** - قم بتكوين Azure OpenAI كـ bean في Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**نموذج الدردشة** - قم بتكوين Azure OpenAI كعنصر Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -يقوم المنشئ بقراءة بيانات الاعتماد من متغيرات البيئة التي يضبطها `azd up`. تعيين `baseUrl` إلى نقطة نهاية Azure يجعله يعمل مع Azure OpenAI. +يقرأ المُنشئ بيانات الاعتماد من متغيرات البيئة التي يتم إعدادها بواسطة `azd up`. تعيين `baseUrl` لنقطة نهاية Azure الخاصة بك يجعل عميل OpenAI يعمل مع Azure OpenAI. -**ذاكرة المحادثة** - تتبع سجل الدردشة باستخدام MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**ذاكرة المحادثة** - تتبع سجل الدردشة مع MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,21 +124,21 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -قم بإنشاء ذاكرة مع `withMaxMessages(10)` للاحتفاظ بآخر 10 رسائل. أضف رسائل المستخدم والذكاء الاصطناعي باستخدام التغليف النوعي: `UserMessage.from(text)` و `AiMessage.from(text)`. استرجع التاريخ بـ `memory.messages()` وأرسله للنموذج. يخزن الخادم حالات ذاكرة منفصلة لكل معرف محادثة، مما يسمح لعدة مستخدمين بالدردشة في نفس الوقت. +أنشئ الذاكرة مع `withMaxMessages(10)` للاحتفاظ بآخر 10 رسائل. أضف رسائل المستخدم والذكاء الاصطناعي باستخدام الأغلفة المكتوبة: `UserMessage.from(text)` و `AiMessage.from(text)`. استرجع التاريخ بـ `memory.messages()` وأرسله إلى النموذج. يخزن الخدمة مثيلات ذاكرة منفصلة لكل معرف محادثة، مما يسمح لعدة مستخدمين بالدردشة في نفس الوقت. > **🤖 جرب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) واسأل: -> - "كيف يقرر MessageWindowChatMemory أي الرسائل يتم إسقاطها عندما تمتلئ النافذة؟" +> - "كيف يقرر MessageWindowChatMemory أي الرسائل يجب حذفها عندما تمتلئ النافذة؟" > - "هل يمكنني تنفيذ تخزين ذاكرة مخصص باستخدام قاعدة بيانات بدلاً من الذاكرة الداخلية؟" -> - "كيف يمكنني إضافة التلخيص لضغط تاريخ المحادثة القديم؟" +> - "كيف يمكنني إضافة تلخيص لضغط تاريخ المحادثة القديم؟" -تتخطى نقطة النهاية للدردشة بدون حالة الذاكرة تمامًا - فقط `chatModel.chat(prompt)` مثل البداية السريعة. تضيف نقطة النهاية ذات الحالة الرسائل إلى الذاكرة، تسترجع التاريخ، وتشمل ذلك السياق مع كل طلب. نفس تهيئة النموذج، أنماط مختلفة. +نقطة نهاية الدردشة بدون حالة تتخطى الذاكرة تمامًا - فقط `chatModel.chat(prompt)` كما في البداية السريعة. نقطة نهاية الدردشة بحالة تضيف الرسائل إلى الذاكرة، تسترجع التاريخ، وتضمّن هذا السياق مع كل طلب. نفس تكوين النموذج، أنماط مختلفة. -## نشر بنية تحتية Azure OpenAI +## نشر بنية Azure OpenAI التحتية **Bash:** ```bash cd 01-introduction -azd up # اختر الاشتراك والموقع (يفضل eastus2) +azd up # اختر الاشتراك والموقع (يوصى بـ eastus2) ``` **PowerShell:** @@ -147,28 +147,28 @@ cd 01-introduction azd up # اختر الاشتراك والموقع (يفضل eastus2) ``` -> **ملاحظة:** إذا واجهت خطأ مهلة (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`)، ما عليك سوى تشغيل `azd up` مرة أخرى. قد تكون موارد Azure لا تزال تُنشأ في الخلفية، والمحاولة مجددًا تسمح بإكمال النشر بمجرد وصول الموارد إلى حالة نهائية. +> **ملاحظة:** إذا واجهت خطأ في نفاد المهلة (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`)، فقط شغّل `azd up` مرة أخرى. قد لا تزال موارد Azure في طور الإعداد في الخلفية، وإعادة المحاولة تسمح للنشر بالإكمال بمجرد وصول الموارد إلى حالة نهائية. سيقوم هذا بـ: -1. نشر مورد Azure OpenAI مع نماذج GPT-5.2 وtext-embedding-3-small +1. نشر مورد Azure OpenAI مع نموذج GPT-5.2 ونماذج text-embedding-3-small 2. إنشاء ملف `.env` تلقائيًا في جذر المشروع مع بيانات الاعتماد 3. إعداد جميع متغيرات البيئة المطلوبة -**هل تواجه مشاكل في النشر؟** انظر إلى [ملف README للبنية التحتية](infra/README.md) للحصول على حل مشاكل تفصيلي بما في ذلك تعارض أسماء النطاقات الفرعية، خطوات النشر اليدوي من بوابة Azure، وإرشادات تكوين النموذج. +**هل تواجه مشاكل في النشر؟** اطلع على [ملف README للبنية التحتية](infra/README.md) للحصول على حلول تفصيلية تشمل تعارض أسماء النطاقات الفرعية، خطوات النشر اليدوي عبر بوابة Azure، وإرشادات تكوين النموذج. **تحقق من نجاح النشر:** **Bash:** ```bash -cat ../.env # يجب أن يُظهر AZURE_OPENAI_ENDPOINT، API_KEY، إلخ. +cat ../.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT و API_KEY وما إلى ذلك. ``` **PowerShell:** ```powershell -Get-Content ..\.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT، API_KEY، إلخ. +Get-Content ..\.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT وAPI_KEY، إلخ. ``` -> **ملاحظة:** يقوم الأمر `azd up` تلقائيًا بإنشاء ملف `.env`. إذا احتجت إلى تحديثه لاحقًا، يمكنك تحرير ملف `.env` يدويًا أو إعادة إنشائه بتشغيل: +> **ملاحظة:** يولد أمر `azd up` ملف `.env` تلقائيًا. إذا احتجت لتحديثه لاحقًا، يمكنك إما تعديل ملف `.env` يدويًا أو إعادة إنشائه بتشغيل: > > **Bash:** > ```bash @@ -186,11 +186,11 @@ Get-Content ..\.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT، API_KEY، إ **تحقق من النشر:** -تأكد من وجود ملف `.env` في الدليل الجذر مع بيانات اعتماد Azure. شغّل هذا من دليل الوحدة (`01-introduction/`): +تأكد من وجود ملف `.env` في الدليل الجذر مع بيانات اعتماد Azure. شغل هذا الأمر من دليل الوحدة (`01-introduction/`): **Bash:** ```bash -cat ../.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT و API_KEY و DEPLOYMENT +cat ../.env # يجب أن تظهر AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT ``` **PowerShell:** @@ -200,39 +200,39 @@ Get-Content ..\.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT و API_KEY و **ابدأ التطبيقات:** -**الخيار 1: استخدام لوحة تحكم Spring Boot (موصى لمستخدمي VS Code)** +**الخيار 1: استخدام لوحة تحكم Spring Boot (موصى به لمستخدمي VS Code)** -تشمل الحاوية التطويرية امتداد لوحة تحكم Spring Boot، الذي يوفر واجهة بصرية لإدارة جميع تطبيقات Spring Boot. يمكنك العثور عليه في شريط النشاط على الجانب الأيسر من VS Code (ابحث عن أيقونة Spring Boot). +تتضمن حاوية التطوير ملحق لوحة تحكم Spring Boot، الذي يوفر واجهة بصرية لإدارة كل تطبيقات Spring Boot. يمكنك العثور عليه في شريط النشاط على الجانب الأيسر من VS Code (ابحث عن أيقونة Spring Boot). من لوحة تحكم Spring Boot، يمكنك: -- رؤية جميع تطبيقات Spring Boot المتاحة في بيئة العمل +- رؤية جميع تطبيقات Spring Boot المتوفرة في مساحة العمل - بدء/إيقاف التطبيقات بنقرة واحدة - عرض سجلات التطبيق في الوقت الحقيقي - مراقبة حالة التطبيق -فقط انقر على زر التشغيل بجانب "introduction" لبدء هذه الوحدة، أو ابدأ كل الوحدات مرة واحدة. +انقر ببساطة على زر التشغيل بجوار "introduction" لبدء هذه الوحدة، أو ابدأ جميع الوحدات دفعة واحدة. لوحة تحكم Spring Boot -*لوحة تحكم Spring Boot في VS Code — ابدأ، أوقف، وراقب جميع الوحدات من مكان واحد* +*لوحة تحكم Spring Boot في VS Code — ابدأ، أوقف، وراقب كل الوحدات من مكان واحد* **الخيار 2: استخدام سكريبتات الشل** -ابدأ كل تطبيقات الويب (الوحدات 01-04): +شغل كل تطبيقات الويب (الوحدات 01-04): **Bash:** ```bash -cd .. # من الدليل الجذري +cd .. # من الدليل الجذر ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # من الدليل الجذر +cd .. # من الدليل الجذري .\start-all.ps1 ``` -أو ابدأ فقط هذه الوحدة: +أو شغل هذه الوحدة فقط: **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -كلا السكريبتين يقومان بتحميل متغيرات البيئة تلقائيًا من ملف .env في الجذر وسيبنيان ملفات JAR إذا لم تكن موجودة. +تقوم كلا السكريبتات بتحميل متغيرات البيئة تلقائيًا من ملف `.env` الجذري وستبني ملفات JAR إذا لم تكن موجودة. -> **ملاحظة:** إذا فضلت بناء جميع الوحدات يدويًا قبل البدء: +> **ملاحظة:** إذا كنت تفضل بناء كل الوحدات يدويًا قبل التشغيل: > > **Bash:** > ```bash @@ -270,53 +270,53 @@ cd 01-introduction ```bash ./stop.sh # هذا الوحدة فقط # أو -cd .. && ./stop-all.sh # جميع الوحدات +cd .. && ./stop-all.sh # كل الوحدات ``` **PowerShell:** ```powershell -.\stop.ps1 # هذا الموديول فقط +.\stop.ps1 # هذا الوحدة فقط # أو -cd ..; .\stop-all.ps1 # جميع الموديولات +cd ..; .\stop-all.ps1 # جميع الوحدات ``` ## استخدام التطبيق -يوفر التطبيق واجهة ويب تحتوي على تنفيذين للدردشة جنبًا إلى جنب. +يقدم التطبيق واجهة ويب مع تنفيذين للدردشة جنبًا إلى جنب. -شاشة رئيسية للتطبيق +الشاشة الرئيسية للتطبيق -*لوحة تحكم تعرض كل من الدردشة البسيطة (بدون حالة) والدردشة الحواريّة (مع حالة)* +*لوحة تحكم تعرض خيارا الدردشة البسيطة (بدون حالة) والدردشة الحواريّة (بحالة)* -### الدردشة بدون حالة (اللوحة اليسرى) +### دردشة بدون حالة (اللوحة اليسرى) -جرّب هذا أولاً. اسأل "اسمي جون" ثم اسأل فورًا "ما اسمي؟" لن يتذكر النموذج لأن كل رسالة مستقلة. يوضح هذا المشكلة الأساسية مع دمج نماذج اللغة البسيطة — لا يوجد سياق للمحادثة. +جرب هذا أولاً. اسأل "اسمي جون" ثم اسأل فورًا "ما اسمي؟" لن يتذكر النموذج لأنه كل رسالة مستقلة. هذا يوضح المشكلة الأساسية في دمج نموذج اللغة الأساسي — لا سياق للمحادثة. -عرض توضيحي للدردشة بدون حالة +عرض دردشة بدون حالة *الذكاء الاصطناعي لا يتذكر اسمك من الرسالة السابقة* -### الدردشة مع الحالة (اللوحة اليمنى) +### دردشة بحالة (اللوحة اليمنى) -الآن جرّب نفس التسلسل هنا. اسأل "اسمي جون" ثم "ما اسمي؟" هذه المرة يتذكر. الفرق هو MessageWindowChatMemory - فهي تحافظ على تاريخ المحادثة وتضمّنه مع كل طلب. هكذا يعمل الذكاء الاصطناعي الحواري في الإنتاج. +الآن جرب نفس التسلسل هنا. اسأل "اسمي جون" ثم "ما اسمي؟" هذه المرة يتذكر. الفرق هو MessageWindowChatMemory — يحافظ على سجل المحادثة ويضمّنه مع كل طلب. هكذا يعمل الذكاء الاصطناعي الحواري في الإنتاج. -عرض توضيحي للدردشة مع حالة +عرض دردشة بحالة -*الذكاء الاصطناعي يتذكر اسمك من سابق المحادثة* +*الذكاء الاصطناعي يتذكر اسمك من بداية المحادثة* -تستخدم اللوحتان نفس نموذج GPT-5.2. الاختلاف الوحيد هو الذاكرة. هذا يوضح ما تضيفه الذاكرة إلى تطبيقك ولماذا هي أساسية لحالات الاستخدام الحقيقية. +تستخدم كلتا اللوحتين نفس نموذج GPT-5.2. الفرق الوحيد هو الذاكرة. هذا يوضح ما تضيفه الذاكرة لتطبيقك ولماذا هي ضرورية لحالات الاستخدام الحقيقية. ## الخطوات التالية -**الوحدة التالية:** [02-prompt-engineering - هندسة المطالبات مع GPT-5.2](../02-prompt-engineering/README.md) +**الوحدة التالية:** [02-prompt-engineering - هندسة المُطالبات مع GPT-5.2](../02-prompt-engineering/README.md) --- -**التنقل:** [← السابق: الوحدة 00 - البداية السريعة](../00-quick-start/README.md) | [عودة إلى الرئيسي](../README.md) | [التالي: الوحدة 02 - هندسة المطالبات →](../02-prompt-engineering/README.md) +**التنقل:** [← العودة إلى الرئيسية](../README.md) | [التالي: الوحدة 02 - هندسة المُطالبات →](../02-prompt-engineering/README.md) --- -**تنويه**: -تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). على الرغم من سعينا لتحقيق الدقة، يُرجى العلم بأن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. بالنسبة للمعلومات الهامة، يُنصح بالاعتماد على ترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة. +**تنويه**: +تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة. \ No newline at end of file diff --git a/translations/ar/02-prompt-engineering/README.md b/translations/ar/02-prompt-engineering/README.md index d8d70790b..2cffb5415 100644 --- a/translations/ar/02-prompt-engineering/README.md +++ b/translations/ar/02-prompt-engineering/README.md @@ -2,50 +2,50 @@ ## جدول المحتويات -- [جولة الفيديو](../../../02-prompt-engineering) -- [ما الذي ستتعلمه](../../../02-prompt-engineering) -- [المتطلبات المسبقة](../../../02-prompt-engineering) -- [فهم هندسة المطالبات](../../../02-prompt-engineering) -- [أساسيات هندسة المطالبات](../../../02-prompt-engineering) - - [المطالبة بدون أمثلة](../../../02-prompt-engineering) - - [المطالبة مع بعض الأمثلة](../../../02-prompt-engineering) - - [سلسلة التفكير](../../../02-prompt-engineering) - - [المطالبة المعتمدة على الدور](../../../02-prompt-engineering) - - [قوالب المطالبات](../../../02-prompt-engineering) -- [الأنماط المتقدمة](../../../02-prompt-engineering) -- [تشغيل التطبيق](../../../02-prompt-engineering) -- [لقطات شاشة للتطبيق](../../../02-prompt-engineering) -- [استكشاف الأنماط](../../../02-prompt-engineering) - - [حماس منخفض مقابل حماس مرتفع](../../../02-prompt-engineering) - - [تنفيذ المهمات (مقدمات الأدوات)](../../../02-prompt-engineering) - - [كود التأمل الذاتي](../../../02-prompt-engineering) - - [التحليل المنظم](../../../02-prompt-engineering) - - [الدردشة متعددة الأدوار](../../../02-prompt-engineering) - - [التفكير خطوة بخطوة](../../../02-prompt-engineering) - - [الإخراج المقيد](../../../02-prompt-engineering) -- [ما الذي تتعلمه حقًا](../../../02-prompt-engineering) -- [الخطوات التالية](../../../02-prompt-engineering) - -## جولة الفيديو - -شاهد هذه الجلسة الحية التي تشرح كيفية البدء مع هذه الوحدة: +- [استعراض الفيديو](#استعراض-الفيديو) +- [ما الذي ستتعلمه](#ما-الذي-ستتعلمه) +- [المتطلبات الأساسية](#المتطلبات-الأساسية) +- [فهم هندسة المطالبات](#فهم-هندسة-المطالبات) +- [أساسيات هندسة المطالبات](#أساسيات-هندسة-المطالبات) + - [المطالبة بدون أمثلة](#المطالبة-بدون-أمثلة) + - [المطالبة مع بعض الأمثلة](#المطالبة-مع-بعض-الأمثلة) + - [سلسلة التفكير](#سلسلة-التفكير) + - [المطالبة بناءً على الدور](#المطالبة-بناءً-على-الدور) + - [قوالب المطالبات](#قوالب-المطالبات) +- [الأنماط المتقدمة](#الأنماط-المتقدمة) +- [تشغيل التطبيق](#تشغيل-التطبيق) +- [لقطات شاشة للتطبيق](#لقطات-شاشة-للتطبيق) +- [استكشاف الأنماط](#استكشاف-الأنماط) + - [الحماس المنخفض مقابل المرتفع](#الحماسة-المنخفضة-مقابل-الحماسة-العالية) + - [تنفيذ المهمة (مقدمات الأدوات)](#تنفيذ-المهام-مقدمات-الأدوات) + - [الكود التأملي الذاتي](#الكود-العاكس-للذات) + - [التحليل المنظم](#التحليل-المنظم) + - [الدردشة متعددة الأدوار](#الدردشة-متعددة-الأدوار) + - [التفكير خطوة بخطوة](#التفكير-خطوة-بخطوة) + - [الناتج المقيد](#مخرجات-مقيدة) +- [ما الذي تتعلمه حقًا](#ما-تتعلمه-حقًا) +- [الخطوات التالية](#الخطوات-التالية) + +## استعراض الفيديو + +شاهد هذا الجلسة المباشرة التي تشرح كيفية البدء مع هذه الوحدة: هندسة المطالبات مع LangChain4j - جلسة مباشرة ## ما الذي ستتعلمه -يوفر الرسم البياني التالي نظرة عامة على الموضوعات والمهارات الرئيسية التي ستطورها في هذه الوحدة — من تقنيات تحسين المطالبات إلى سير العمل خطوة بخطوة الذي ستتبعه. +يوفر المخطط التالي نظرة عامة على الموضوعات والمهارات الأساسية التي ستطورها في هذه الوحدة — من تقنيات تحسين المطالبات إلى سير العمل خطوة بخطوة الذي ستتبعه. ما الذي ستتعلمه -في الوحدات السابقة، استكشفت التفاعلات الأساسية مع LangChain4j باستخدام نماذج GitHub ورأيت كيف تُمكّن الذاكرة الذكاء الاصطناعي المحادثي مع Azure OpenAI. الآن سنركز على كيفية طرح الأسئلة — أي المطالبات نفسها — باستخدام GPT-5.2 من Azure OpenAI. الطريقة التي تبني بها مطالباتك تؤثر بشكل كبير على جودة الإجابات التي تحصل عليها. نبدأ بمراجعة تقنيات المطالبة الأساسية، ثم ننتقل إلى ثمانية أنماط متقدمة تستفيد بالكامل من قدرات GPT-5.2. +في الوحدة السابقة، رأيت كيف تمكّن الذاكرة الذكاء الاصطناعي الحواري مع Azure OpenAI. الآن سنركز على كيفية طرح الأسئلة — أي المطالبات نفسها — باستخدام GPT-5.2 من Azure OpenAI. الطريقة التي تبني بها مطالباتك تؤثر بشكل كبير على جودة الردود التي تحصل عليها. نبدأ بمراجعة تقنيات المطالبات الأساسية، ثم ننتقل إلى ثمانية أنماط متقدمة تستغل إمكانيات GPT-5.2 بالكامل. -نستخدم GPT-5.2 لأنه يقدم تحكمًا في التفكير - يمكنك إخبار النموذج بكمية التفكير المطلوبة قبل الإجابة. هذا يجعل استراتيجيات المطالبة المختلفة أكثر وضوحًا ويساعدك على فهم متى تستخدم كل طريقة. سنستفيد أيضًا من حدود المعدل الأقل لـ GPT-5.2 في Azure مقارنة بنماذج GitHub. +سنستخدم GPT-5.2 لأنه يقدم تحكمًا في المنطق — يمكنك إخبار النموذج بكمية التفكير التي يجب أن يقوم بها قبل الإجابة. هذا يجعل استراتيجيات المطالبة المختلفة أكثر وضوحًا ويساعدك على فهم متى تستخدم كل نهج. -## المتطلبات المسبقة +## المتطلبات الأساسية -- إكمال الوحدة 01 (نشر موارد Azure OpenAI) -- ملف `.env` في الدليل الجذري يحتوي على بيانات اعتماد Azure (تم إنشاؤه بواسطة `azd up` في الوحدة 01) +- إكمال الوحدة 01 (تم نشر موارد Azure OpenAI) +- ملف `.env` في الدليل الجذري مع بيانات الاعتماد الخاصة بـ Azure (تم إنشاؤه بواسطة `azd up` في الوحدة 01) > **ملاحظة:** إذا لم تكمل الوحدة 01، اتبع تعليمات النشر هناك أولاً. @@ -55,27 +55,27 @@ ما هي هندسة المطالبات؟ -هندسة المطالبات تتعلق بتصميم نص الإدخال الذي يعطيك النتائج التي تحتاجها بشكل مستمر. الأمر لا يقتصر على طرح الأسئلة فقط - بل يتعلق بهيكلة الطلبات بحيث يفهم النموذج بالضبط ما تريد وكيفية تقديمه. +هندسة المطالبات تتعلق بتصميم نص الإدخال الذي يمنحك النتائج التي تحتاجها بشكل متسق. الأمر ليس مجرد طرح أسئلة — بل هو هيكلة الطلبات بحيث يفهم النموذج بالضبط ما تريد وكيفية تقديمه. -فكر في الأمر كما لو كنت تعطي تعليمات لزميل. "أصلح الخطأ" غامض. "أصلح استثناء المؤشر الخالي في UserService.java السطر 45 بإضافة فحص للقيمة null" محدد. نماذج اللغة تعمل بنفس الطريقة — الدقة والهيكل مهمان. +فكر في الأمر كما لو كنت تعطي تعليمات لزميل في العمل. "أصلح الخطأ" غامض. "أصلح استثناء المؤشر الخالي في UserService.java في السطر 45 بإضافة فحص القيم الخالية" دقيق. نماذج اللغة تعمل بنفس الطريقة — الدقة والهيكل مهمان. -يوضح الرسم البياني أدناه كيف يندمج LangChain4j في هذه الصورة — حيث يربط أنماط مطالباتك بالنموذج من خلال الوحدات الأساسية SystemMessage و UserMessage. +يوضح المخطط أدناه كيف يتناسب LangChain4j مع هذه الصورة — حيث يربط أنماط مطالباتك بالنموذج من خلال وحدات بناء SystemMessage وUserMessage. -كيف يندمج LangChain4j +كيف يتناسب LangChain4j -يجلب LangChain4j البنية التحتية — اتصالات النموذج، الذاكرة، وأنواع الرسائل — في حين أن أنماط المطالبات هي مجرد نص منظم بعناية ترسله عبر هذه البنية التحتية. الوحدات الأساسية الرئيسية هي `SystemMessage` (التي تحدد سلوك وال دور الذكاء الاصطناعي) و`UserMessage` (التي تحمل طلبك الفعلي). +يوفر LangChain4j البنية التحتية — اتصالات النموذج، الذاكرة، وأنواع الرسائل — بينما أنماط المطالبات هي مجرد نص منظم بعناية ترسله عبر هذه البنية. اللبنات الأساسية الرئيسية هي `SystemMessage` (الذي يحدد سلوك ودور الذكاء الاصطناعي) و `UserMessage` (الذي يحمل طلبك الفعلي). ## أساسيات هندسة المطالبات -تشكل التقنيات الأساسية الخمسة الموضحة أدناه أساس هندسة المطالبات الفعالة. كل واحدة تعالج جانبًا مختلفًا من كيفية تواصلك مع نماذج اللغة. +تشكل التقنيات الخمس الأساسية الموضحة أدناه أساس هندسة المطالبات الفعالة. يعالج كل منها جانبًا مختلفًا من كيفية تواصلك مع نماذج اللغة. -نظرة عامة على خمسة أنماط لهندسة المطالبات +نظرة عامة على خمسة أنماط هندسة المطالبات -قبل أن نغوص في الأنماط المتقدمة في هذه الوحدة، دعنا نراجع خمس تقنيات أساسية في المطالبة. إنها اللبنات الأساسية التي يجب أن يعرفها كل مهندس مطالبات. إذا كنت قد عملت بالفعل عبر [وحدة البداية السريعة](../00-quick-start/README.md#2-prompt-patterns)، فقد رأيت هذه التقنيات تعمل — وإليك الإطار المفهومي وراءها. +قبل الغوص في الأنماط المتقدمة في هذه الوحدة، دعنا نراجع خمس تقنيات تأسيسية للمطالبات. هذه هي اللبنات التي يجب أن يعرفها كل مهندس مطالبات. ### المطالبة بدون أمثلة -النهج الأبسط: تعطي النموذج تعليمات مباشرة بدون أمثلة. يعتمد النموذج كليًا على تدريبه لفهم وتنفيذ المهمة. يعمل هذا جيدًا للطلبات المباشرة حيث السلوك المتوقع واضح. +أسهل نهج: أعط النموذج تعليمات مباشرة بدون أمثلة. يعتمد النموذج بالكامل على تدريبه لفهم وتنفيذ المهمة. يعمل هذا جيدًا للطلبات البسيطة حيث السلوك المتوقع واضح. المطالبة بدون أمثلة @@ -84,18 +84,18 @@ ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// الاستجابة: "إيجابي" +// رد: "إيجابي" ``` - + **متى تستخدم:** التصنيفات البسيطة، الأسئلة المباشرة، الترجمات، أو أي مهمة يمكن للنموذج التعامل معها بدون توجيه إضافي. ### المطالبة مع بعض الأمثلة -قدّم أمثلة توضح النمط الذي تريد أن يتبعه النموذج. يتعلم النموذج شكل الإدخال-الإخراج المتوقع من أمثلتك ويطبقه على مدخلات جديدة. هذا يحسن الاتساق بشكل كبير للمهام التي لا يكون فيها النمط أو السلوك المرغوب واضحًا. +قدِّم أمثلة توضح النمط الذي تريد من النموذج اتباعه. يتعلم النموذج تنسيق الإدخال والإخراج المتوقع من أمثلتك ويطبقه على المدخلات الجديدة. هذا يحسّن الاتساق بشكل كبير للمهام التي يكون فيها التنسيق أو السلوك المطلوب غير واضح. المطالبة مع بعض الأمثلة -*التعلم من الأمثلة — يتعرف النموذج على النمط ويطبقه على مدخلات جديدة* +*التعلم من الأمثلة — يتعرف النموذج على النمط ويطبقه على المدخلات الجديدة* ```java String prompt = """ @@ -111,14 +111,14 @@ String prompt = """ """; String response = model.chat(prompt); ``` - + **متى تستخدم:** التصنيفات المخصصة، التنسيق المتسق، المهام الخاصة بالمجال، أو عندما تكون نتائج المطالبة بدون أمثلة غير متسقة. ### سلسلة التفكير -اطلب من النموذج عرض تفكيره خطوة بخطوة. بدلاً من الانتقال مباشرة إلى إجابة، يقسم النموذج المشكلة ويعمل على كل جزء بشكل صريح. هذا يحسن الدقة في مسائل الرياضيات والمنطق والتفكير متعدد الخطوات. +اطلب من النموذج عرض تفكيره خطوة بخطوة. بدلاً من القفز مباشرة إلى الإجابة، يكسر النموذج المشكلة ويعمل على كل جزء بشكل صريح. هذا يحسن الدقة في الرياضيات، المنطق، ومهام التفكير متعدد الخطوات. -مطالبة سلسلة التفكير +المطالبة بسلسلة التفكير *التفكير خطوة بخطوة — تقسيم المشاكل المعقدة إلى خطوات منطقية صريحة* @@ -132,16 +132,16 @@ String prompt = """ String response = model.chat(prompt); // يوضح النموذج: ١٥ - ٨ = ٧، ثم ٧ + ١٢ = ١٩ تفاحة ``` - -**متى تستخدم:** مشاكل الرياضيات، الألغاز المنطقية، تصحيح الأخطاء، أو أي مهمة تحسين فيها عرض عملية التفكير دقة وثقة. -### المطالبة المعتمدة على الدور +**متى تستخدم:** مسائل رياضية، ألغاز منطقية، تصحيح الأخطاء، أو أي مهمة حيث يساعد عرض عملية التفكير في تحسين الدقة والثقة. -حدد شخصية أو دور للذكاء الاصطناعي قبل طرح سؤالك. يوفر هذا سياقًا يشكل نبرة وعمق وتركيز الرد. "مهندس برمجيات" يعطي نصائح مختلفة عن "مطور مبتدئ" أو "مدقق أمني". +### المطالبة بناءً على الدور -المطالبة المعتمدة على الدور +حدد شخصية أو دور للذكاء الاصطناعي قبل طرح سؤالك. هذا يوفر سياقاً يشكل نبرة، عمق، وتركيز الرد. "مهندس برمجيات" يقدم نصائح مختلفة عن "مطور مبتدئ" أو "مدقق أمني". -*تحديد السياق والشخصية — نفس السؤال قد يحصل على رد مختلف بناءً على الدور المعين* +المطالبة بناءً على الدور + +*تحديد السياق والشخصية — نفس السؤال يحصل على رد مختلف بناءً على الدور المعين* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**متى تستخدم:** مراجعة الكود، التعليم، التحليل الخاص بالمجال، أو عندما تحتاج ردودًا مصممة لمستوى خبرة أو منظور معين. + +**متى تستخدم:** مراجعات الكود، التدريس، التحليل الخاص بالمجال، أو عندما تحتاج إلى ردود مخصصة لمستوى خبرة أو منظور معين. ### قوالب المطالبات -أنشئ مطالبات قابلة لإعادة الاستخدام مع متغيرات مكانها. بدلاً من كتابة مطالبة جديدة في كل مرة، عرّف قالبًا مرة واحدة واملأه بقيم مختلفة. يسهل LangChain4j باستخدام صنف `PromptTemplate` مع الصياغة `{{variable}}`. +أنشئ مطالبات قابلة لإعادة الاستخدام مع متغيرات مكان العناصر. بدلاً من كتابة مطالبة جديدة في كل مرة، عرّف قالباً مرة واحدة واملأ قيم مختلفة. تسهل فئة `PromptTemplate` في LangChain4j هذا باستخدام صيغة `{{variable}}`. قوالب المطالبات -*مطالبات قابلة لإعادة الاستخدام مع متغيرات مكانها — قالب واحد، استخدامات كثيرة* +*مطالبات قابلة لإعادة الاستخدام مع متغيرات مكان العناصر — قالب واحد، استخدامات متعددة* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**متى تستخدم:** استفسارات متكررة مع مدخلات مختلفة، معالجة مجموعات، بناء سير عمل ذكاء اصطناعي قابل لإعادة الاستخدام، أو أي سيناريو تبقى فيه هيكلية المطالبة نفسها لكن البيانات تتغير. + +**متى تستخدم:** استعلامات متكررة مع مدخلات مختلفة، المعالجة الدفعية، بناء سير عمل ذكاء اصطناعي قابل لإعادة الاستخدام، أو أي سيناريو يبقى فيه هيكل المطالبة نفسه لكن البيانات تتغير. --- -تعطيك هذه الأساسيات الخمسة مجموعة أدوات متينة لمعظم مهام المطالبة. يبني بقية هذه الوحدة عليها مع **ثمانية أنماط متقدمة** تستغل تحكم التفكير في GPT-5.2، والتقييم الذاتي، وإمكانيات الإخراج المنظم. +هذه الأساسيات الخمسة تزودك بمجموعة أدوات قوية لمعظم مهام المطالبة. بقية هذه الوحدة تبني عليها بـ **ثمانية أنماط متقدمة** تستفيد من تحكم GPT-5.2 في المنطق، التقييم الذاتي، وقدرات الإخراج المهيكل. ## الأنماط المتقدمة -بعد تغطية الأساسيات، دعنا ننتقل إلى الثمانية أنماط المتقدمة التي تجعل هذه الوحدة فريدة. ليست كل المشاكل تحتاج نفس النهج. بعض الأسئلة تحتاج إجابات سريعة، والبعض الآخر يحتاج تفكيرًا عميقًا. بعض تحتاج تفكيرًا مرئيًا، والبعض يحتاج فقط النتائج. كل نمط أدناه مُحسّن لسيناريو مختلف — وتحكم التفكير في GPT-5.2 يجعل الفروقات أكثر وضوحًا. +بعد تغطية الأساسيات، لننتقل إلى الثمانية أنماط المتقدمة التي تميز هذه الوحدة. ليست كل المشاكل تحتاج لنفس النهج. بعض الأسئلة تحتاج إجابات سريعة، وأخرى تحتاج تفكيرًا عميقًا. بعض تحتاج إلى منطق مرئي، والبعض الآخر يحتاج فقط النتائج. كل نمط أدناه مُحسّن لسيناريو مختلف — وتحكم GPT-5.2 في المنطق يجعل الفروقات أكثر وضوحًا. ثمانية أنماط للمطالبة -*نظرة عامة على ثمانية أنماط في هندسة المطالبات وحالات استخدامها* +*نظرة عامة على ثمانية أنماط هندسة المطالبات وحالات استخدامها* -يضيف GPT-5.2 بُعدًا آخر لهذه الأنماط: *التحكم في التفكير*. الشريط المنزلق أدناه يظهر كيف يمكنك ضبط جهد التفكير للنموذج — من إجابات سريعة ومباشرة إلى تحليل عميق وشامل. +يضيف GPT-5.2 بعدًا آخر لهذه الأنماط: *تحكم في المنطق*. يظهر شريط التمرير أدناه كيف يمكنك تعديل جهد التفكير لدى النموذج — من إجابات سريعة ومباشرة إلى تحليل عميق وشامل. -التحكم في التفكير مع GPT-5.2 +التحكم في المنطق مع GPT-5.2 -*يتيح تحكم التفكير في GPT-5.2 لك تحديد مقدار التفكير الذي يجب أن يقوم به النموذج — من إجابات مباشرة سريعة إلى استكشاف عميق* +*تحكم GPT-5.2 في المنطق يتيح لك تحديد مقدار التفكير الذي يجب أن يقوم به النموذج — من إجابات سريعة ومباشرة إلى استكشاف عميق* -**حماس منخفض (سريع ومركز)** - للأسئلة البسيطة حيث تريد إجابات سريعة ومباشرة. يقوم النموذج بأقل قدر من التفكير - بحد أقصى خطوتين. استخدم هذا للحسابات، عمليات البحث، أو الأسئلة المباشرة. +**حماس منخفض (سريع ومركز)** - للأسئلة البسيطة التي تريد فيها إجابات سريعة ومباشرة. يقوم النموذج بأقل قدر من التفكير - بحد أقصى خطوتين. استخدم هذا للحسابات، الاستعلامات، أو الأسئلة البسيطة. ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> 💡 **استكشف مع GitHub Copilot:** افتح [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) واطرح: -> - "ما الفرق بين نمطي المطالبة ذات الحماس المنخفض والحماس العالي؟" -> - "كيف تساعد علامات XML في المطالبات على هيكلة استجابة الذكاء الاصطناعي؟" -> - "متى يجب أن أستخدم أنماط التأمل الذاتي مقابل التعليم المباشر؟" -**حماس مرتفع (عميق وشامل)** - للمشاكل المعقدة حيث تريد تحليلًا شاملاً. يستكشف النموذج بالتفصيل ويعرض تفكيرًا مفصلًا. استخدم هذا لتصميم الأنظمة، قرارات الهندسة المعمارية، أو الأبحاث المعقدة. +> 💡 **استكشف مع GitHub Copilot:** افتح [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) واسأل: +> - "ما الفرق بين نمطي المطالبة الحماسية المنخفضة والحماسية العالية؟" +> - "كيف تساعد علامات XML في المطالبات على هيكلة رد الذكاء الاصطناعي؟" +> - "متى يجب أن أستخدم أنماط التأمل الذاتي مقابل التعليمات المباشرة؟" + +**حماس عالي (عميق وشامل)** - للمشكلات المعقدة التي تريد فيها تحليلاً شاملاً. يستكشف النموذج بدقة ويعرض تفكيرًا مفصلًا. استخدم هذا لتصميم النظم، قرارات الهندسة المعمارية، أو البحث المعقد. ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**تنفيذ المهمة (التقدم خطوة بخطوة)** - لسير العمل متعدد الخطوات. يقدم النموذج خطة مسبقة، يروي كل خطوة أثناء التنفيذ، ثم يعطي ملخصًا. استخدم هذا للهجرات، التطبيقات، أو أي عمليات متعددة الخطوات. + +**تنفيذ المهمة (تقدم خطوة بخطوة)** - لسير العمل متعددة الخطوات. يقدم النموذج خطة مبدئية، يروي كل خطوة أثناء التنفيذ، ثم يعطي ملخصًا. استخدم هذا للهجرات، التطبيقات، أو أي عملية متعددة الخطوات. ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -مطالبة سلسلة التفكير تطلب بوضوح من النموذج عرض عملية تفكيره، مما يحسن الدقة للمهام المعقدة. يساعد التقسيم خطوة بخطوة البشر والذكاء الاصطناعي على فهم المنطق. + +المطالبة بسلسلة التفكير تطلب صراحة من النموذج عرض عملية تفكيره، مما يحسن الدقة للمهام المعقدة. يساعد التفصيل خطوة بخطوة البشر والذكاء الاصطناعي على فهم المنطق. > **🤖 جرب مع دردشة [GitHub Copilot](https://github.com/features/copilot):** اسأل عن هذا النمط: -> - "كيف يمكنني تعديل نمط تنفيذ المهمة للعمليات طويلة الأمد؟" -> - "ما هي أفضل الممارسات لهياكل مقدمات الأدوات في التطبيقات الإنتاجية؟" -> - "كيف يمكنني تسجيل وعرض تحديثات التقدم المرحلي في واجهة المستخدم؟" +> - "كيف يمكنني تكييف نمط تنفيذ المهمة للعمليات طويلة الأمد؟" +> - "ما هي أفضل الممارسات لهياكلة مقدمات الأدوات في تطبيقات الإنتاج؟" +> - "كيف يمكنني التقاط وعرض تحديثات التقدم المرحلية في واجهة المستخدم؟" -يوضح الرسم البياني أدناه هذا سير العمل خطة → تنفيذ → تلخيص. +يوضح المخطط أدناه هذا سير العمل خطة → تنفيذ → تلخيص. نمط تنفيذ المهمة *سير العمل خطة → تنفيذ → تلخيص للمهام متعددة الخطوات* -**كود التأمل الذاتي** - لإنشاء كود بجودة الإنتاج. ينتج النموذج الكود وفقًا لمعايير الإنتاج مع معالجة مناسبة للأخطاء. استخدم هذا عند بناء ميزات أو خدمات جديدة. +**الكود التأملي الذاتي** - لتوليد رمز بجودة الإنتاج. ينتج النموذج كودًا يتبع معايير الإنتاج مع التعامل السليم مع الأخطاء. استخدم هذا عند بناء ميزات أو خدمات جديدة. ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -يوضح الرسم البياني التالي هذه الحلقة التكرارية للتحسين — إنشاء، تقييم، تحديد نقاط الضعف، وتحسين حتى يحقق الكود معايير الإنتاج. + +يوضح المخطط أدناه حلقة التحسين التكرارية هذه — إنتاج، تقييم، تحديد نقاط الضعف، وتحسين حتى يلبي الكود معايير الإنتاج. دورة التأمل الذاتي -*حلقة تحسين تكرارية - إنشاء، تقييم، تحديد المشكلات، تحسين، تكرار* +*حلقة تحسين تكرارية - إنتاج، تقييم، تحديد المشكلات، تحسين، تكرار* -**التحليل المنظم** - لتقييم متسق. يراجع النموذج الكود باستخدام إطار ثابت (الصحة، الممارسات، الأداء، الأمان، القابلية للصيانة). استخدم هذا لمراجعات الكود أو تقييمات الجودة. +**التحليل المنظم** - للتقييم المتسق. يراجع النموذج الكود باستخدام إطار ثابت (الصحة، الممارسات، الأداء، الأمان، قابلية الصيانة). استخدم هذا لمراجعات الكود أو تقييمات الجودة. ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - + > **🤖 جرب مع دردشة [GitHub Copilot](https://github.com/features/copilot):** اسأل عن التحليل المنظم: -> - "كيف يمكنني تخصيص إطار التحليل لأنواع مراجعات الكود المختلفة؟" -> - "ما الطريقة المثلى لتحليل ومعالجة الإخراج المنظم برمجيًا؟" -> - "كيف أضمن مستويات شدة متسقة عبر جلسات مراجعة مختلفة؟" +> - "كيف يمكنني تخصيص إطار التحليل لأنواع مختلفة من مراجعات الكود؟" +> - "ما أفضل طريقة لتحليل والإجراء على الإخراج المنظم برمجيًا؟" +> - "كيف أضمن مستويات شدة متسقة عبر جلسات المراجعة المختلفة؟" -يُظهر الرسم البياني التالي كيف ينظم هذا الإطار المراجعة إلى فئات ثابتة مع مستويات شدة. +يوضح المخطط التالي كيف ينظم هذا الإطار المنظم مراجعة الكود إلى فئات متسقة مع مستويات شدة. نمط التحليل المنظم -*إطار لمراجعات كود متسقة مع مستويات الشدة* +*إطار عمل لمراجعات الكود المتسقة مع مستويات الشدة* -**الدردشة متعددة الأدوار** - للمحادثات التي تحتاج إلى سياق. يتذكر النموذج الرسائل السابقة ويبني عليها. استخدم هذا لجلسات المساعدة التفاعلية أو الأسئلة المعقدة. +**الدردشة متعددة الأدوار** - للمحادثات التي تحتاج للسياق. يتذكر النموذج الرسائل السابقة ويبني عليها. استخدم هذا لجلسات المساعدة التفاعلية أو أسئلة وأجوبة معقدة. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -يوضح الرسم البياني أدناه كيف يتراكم سياق المحادثة مع كل جولة وكيف يرتبط بحد رموز النموذج. + +يوضح المخطط أدناه كيف يتكامل سياق المحادثة مع كل دورة وكيف يرتبط بحدود عدد الرموز للنموذج. ذاكرة السياق -*كيف يتراكم سياق المحادثة عبر عدة جولات حتى الوصول إلى حد الرموز* -**الشرح خطوة بخطوة** - للمشاكل التي تتطلب منطقًا مرئيًا. يعرض النموذج تبريرًا صريحًا لكل خطوة. استخدم هذا للمسائل الرياضية، وألغاز المنطق، أو عندما تحتاج إلى فهم عملية التفكير. +*كيف يتراكم سياق المحادثة عبر عدة دورات حتى الوصول إلى حد الرموز* + +**التفكير خطوة بخطوة** - للمشاكل التي تتطلب منطقًا مرئيًا. يعرض النموذج تفكيرًا صريحًا لكل خطوة. استخدم هذا للمسائل الرياضية، الألغاز المنطقية، أو عندما تحتاج إلى فهم عملية التفكير. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -يوضح الشكل أدناه كيف يقوم النموذج بتقسيم المشاكل إلى خطوات منطقية مرقمة وصريحة. +يوضح المخطط أدناه كيف يكسر النموذج المشاكل إلى خطوات منطقية مرقمة وصريحة. نمط خطوة بخطوة +*تفكيك المشكلات إلى خطوات منطقية صريحة* -*تقسيم المشاكل إلى خطوات منطقية صريحة* - -**الإخراج المقيد** - للردود التي تتطلب تنسيقًا معينًا. يتبع النموذج قواعد التنسيق والطول بدقة. استخدم هذا للملخصات أو عندما تحتاج إلى هيكل إخراج دقيق. +**المخرجات المقيدة** - للردود التي تتطلب تنسيقًا محددًا. يتبع النموذج بدقة قواعد الشكل والطول. استخدم هذا للملخصات أو عندما تحتاج إلى هيكل إخراج دقيق. ```java String prompt = """ @@ -420,53 +420,53 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -يوضح الشكل التالي كيف توجه القيود النموذج لإنتاج إخراج يلتزم بدقة بقواعد التنسيق والطول الخاصة بك. +يُظهر الشكل التالي كيف توجه القيود النموذج لإنتاج مخرجات تلتزم بدقة بمتطلبات التنسيق والطول الخاصة بك. -نمط الإخراج المقيد +نمط المخرجات المقيدة -*فرض متطلبات تنسيق وطول وبنية محددة* +*فرض متطلبات معينة على التنسيق والطول والتركيب* ## تشغيل التطبيق **التحقق من النشر:** -تأكد من وجود ملف `.env` في الدليل الجذري يحتوي على بيانات اعتماد Azure (تم إنشاؤه خلال الوحدة 01). شغّل هذا من دليل الوحدة (`02-prompt-engineering/`): +تأكد من وجود ملف `.env` في الدليل الجذري يحتوي على بيانات اعتماد Azure (تم إنشاؤه خلال الوحدة 01). نفذ هذا من دليل الوحدة (`02-prompt-engineering/`): -**باش:** +**Bash:** ```bash -cat ../.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT و API_KEY و DEPLOYMENT +cat ../.env # يجب عرض AZURE_OPENAI_ENDPOINT و API_KEY و DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # يجب عرض AZURE_OPENAI_ENDPOINT و API_KEY و DEPLOYMENT +Get-Content ..\.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT و API_KEY و DEPLOYMENT ``` **بدء التطبيق:** -> **ملاحظة:** إذا كنت قد بدأت بالفعل جميع التطبيقات باستخدام `./start-all.sh` من الدليل الجذري (كما هو موضح في الوحدة 01)، فإن هذه الوحدة تعمل بالفعل على المنفذ 8083. يمكنك تخطي أوامر البدء أدناه والذهاب مباشرة إلى http://localhost:8083. +> **ملاحظة:** إذا كنت قد بدأت جميع التطبيقات بالفعل باستخدام `./start-all.sh` من الدليل الجذري (كما هو موضح في الوحدة 01)، فإن هذه الوحدة تعمل بالفعل على المنفذ 8083. يمكنك تخطي أوامر البدء أدناه والانتقال مباشرة إلى http://localhost:8083. -**الخيار 1: استخدام Spring Boot Dashboard (مفضل لمستخدمي VS Code)** +**الخيار 1: استخدام لوحة تحكم Spring Boot (موصى به لمستخدمي VS Code)** -يتضمن حاوية التطوير إضافة Spring Boot Dashboard التي توفر واجهة بصرية لإدارة جميع تطبيقات Spring Boot. يمكنك العثور عليها في شريط النشاط على الجانب الأيسر من VS Code (ابحث عن أيقونة Spring Boot). +يشتمل حاوية التطوير على امتداد Spring Boot Dashboard الذي يوفر واجهة مرئية لإدارة جميع تطبيقات Spring Boot. يمكنك العثور عليه في شريط النشاط على الجانب الأيسر من VS Code (ابحث عن أيقونة Spring Boot). -من Spring Boot Dashboard، يمكنك: +من لوحة تحكم Spring Boot، يمكنك: - رؤية جميع تطبيقات Spring Boot المتاحة في مساحة العمل - بدء/إيقاف التطبيقات بنقرة واحدة - عرض سجلات التطبيق في الوقت الحقيقي - مراقبة حالة التطبيق -ما عليك سوى النقر على زر التشغيل بجانب "prompt-engineering" لبدء هذه الوحدة، أو بدء جميع الوحدات دفعة واحدة. +ببساطة انقر على زر التشغيل بجانب "prompt-engineering" لبدء هذه الوحدة، أو ابدأ جميع الوحدات دفعة واحدة. لوحة تحكم Spring Boot *لوحة تحكم Spring Boot في VS Code — بدء، إيقاف، ومراقبة جميع الوحدات من مكان واحد* -**الخيار 2: استخدام سكربتات الشل** +**الخيار 2: استخدام سكربتات الشيل** ابدأ جميع تطبيقات الويب (الوحدات 01-04): -**باش:** +**Bash:** ```bash cd .. # من الدليل الجذري ./start-all.sh @@ -474,13 +474,13 @@ cd .. # من الدليل الجذري **PowerShell:** ```powershell -cd .. # من الدليل الجذر +cd .. # من الدليل الجذري .\start-all.ps1 ``` أو ابدأ هذه الوحدة فقط: -**باش:** +**Bash:** ```bash cd 02-prompt-engineering ./start.sh @@ -492,11 +492,11 @@ cd 02-prompt-engineering .\start.ps1 ``` -كلا السكربتين يقومان تلقائيًا بتحميل متغيرات البيئة من ملف `.env` الجذري وسيبنيان ملفات JAR إذا لم تكن موجودة. +يقوم كلا السكربتين بتحميل متغيرات البيئة تلقائيًا من ملف `.env` في الدليل الجذري وسيبني ملفات JAR إذا لم تكن موجودة. -> **ملاحظة:** إذا أردت بناء جميع الوحدات يدويًا قبل البدء: +> **ملاحظة:** إذا كنت تفضل بناء جميع الوحدات يدويًا قبل البدء: > -> **باش:** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests @@ -510,99 +510,99 @@ cd 02-prompt-engineering افتح http://localhost:8083 في متصفحك. -**لإيقاف التشغيل:** +**للتوقف:** -**باش:** +**Bash:** ```bash -./stop.sh # هذا الموديول فقط +./stop.sh # هذا الوحدة فقط # أو -cd .. && ./stop-all.sh # جميع الموديولات +cd .. && ./stop-all.sh # كل الوحدات ``` **PowerShell:** ```powershell -.\stop.ps1 # هذا الموديول فقط +.\stop.ps1 # هذا الوحدة فقط # أو -cd ..; .\stop-all.ps1 # جميع الموديولات +cd ..; .\stop-all.ps1 # جميع الوحدات ``` ## لقطات شاشة للتطبيق -هنا الواجهة الرئيسية لوحدة هندسة المطالبات، حيث يمكنك تجربة جميع الأنماط الثمانية جنبًا إلى جنب. +إليك الواجهة الرئيسية لوحدة هندسة الحث، حيث يمكنك تجربة جميع الأنماط الثمانية جنبًا إلى جنب. -الصفحة الرئيسية للوحة التحكم +الواجهة الرئيسية للوحة القيادة -*لوحة التحكم الرئيسية تعرض جميع أنماط هندسة المطالبات الثمانية مع خصائصها وحالات استخدامها* +*الواجهة الرئيسية تعرض جميع 8 أنماط هندسة الحث مع خصائصها وحالات استخدامها* ## استكشاف الأنماط -تتيح لك واجهة الويب تجربة استراتيجيات مطالبة مختلفة. كل نمط يحل مشاكل مختلفة - جربها لترى متى يبرز كل نهج. +تتيح لك الواجهة الإلكترونية تجربة استراتيجيات تحفيز مختلفة. كل نمط يحل مشاكل مختلفة - جربها لترى متى يتألق كل نهج. -> **ملاحظة: البث مقابل غير البث** — تقدم كل صفحة نمط زرين: **🔴 بث الاستجابة (مباشر)** وخيار **غير البث**. يستخدم البث أحداث Server-Sent Events (SSE) لعرض الرموز المميزة في الوقت الحقيقي أثناء توليد النموذج لها، لذلك ترى التقدم فورًا. الخيار غير البث ينتظر الاستجابة كاملة قبل العرض. للمطالبات التي تتطلب تفكيرًا عميقًا (مثل حسين الحماس العالي، أو كود التفكير الذاتي)، قد يستغرق الاتصال غير البث وقتًا طويلاً جدًا - أحيانًا دقائق - دون تغذية راجعة مرئية. **استخدم البث عند تجربة المطالبات المعقدة** حتى ترى النموذج يعمل وتتجنب الانطباع بأن الطلب انتهت صلاحيته. +> **ملاحظة: البث مقابل غير البث** — تقدم كل صفحة نمط زرين: **🔴 بث الرد (مباشر)** وخيار **غير بث**. يستخدم البث أحداث الخادم (SSE) لعرض الرموز في الوقت الحقيقي أثناء توليد النموذج لها، لذا ترى التقدم فورًا. خيار غير البث ينتظر الرد الكامل قبل عرضه. بالنسبة للأوامر التي تحفز التفكير العميق (مثل الحماسة العالية، الكود العاكس للذات)، قد يستغرق استدعاء غير البث وقتًا طويلًا - أحيانًا دقائق - دون أي ملاحظات مرئية. **استخدم البث عند تجربة أوامر معقدة** لتتمكن من مشاهدة النموذج يعمل وتجنب انطباع انتهاء المهلة. > -> **ملاحظة: متطلبات المتصفح** — تستخدم ميزة البث واجهة Fetch Streams API (`response.body.getReader()`) التي تتطلب متصفحًا كاملاً (Chrome, Edge, Firefox, Safari). لا تعمل في متصفح VS Code المدمج (Simple Browser)، إذ لا يدعم واجهة ReadableStream API. إذا استخدمت Simple Browser، ستعمل أزرار غير البث بشكل طبيعي — فقط أزرار البث تتأثر. افتح `http://localhost:8083` في متصفح خارجي لتجربة كاملة. +> **ملاحظة: متطلبات المتصفح** — تستخدم ميزة البث واجهة Fetch Streams API (`response.body.getReader()`) التي تتطلب متصفحًا كاملاً (Chrome، Edge، Firefox، Safari). **لا يعمل** في المتصفح البسيط المدمج بداخل VS Code، لأن عرض الويب فيه لا يدعم واجهة ReadableStream API. إذا استخدمت المتصفح البسيط، ستعمل أزرار غير البث بشكل طبيعي — فقط أزرار البث هي المتأثرة. افتح `http://localhost:8083` في متصفح خارجي لتجربة كاملة. -### الحماس المنخفض مقابل الحماس العالي +### الحماسة المنخفضة مقابل الحماسة العالية -اطرح سؤالًا بسيطًا مثل "ما هو 15% من 200؟" باستخدام الحماس المنخفض. ستحصل على إجابة فورية ومباشرة. الآن اسأل شيئًا معقدًا مثل "صمّم استراتيجية تخزين مؤقت لواجهة برمجية ذات حركة مرور عالية" باستخدام الحماس العالي. انقر **🔴 بث الاستجابة (مباشر)** وشاهد تفكير النموذج التفصيلي يظهر رمزًا برمز. نفس النموذج، نفس هيكل السؤال - لكن المطالبة تخبره بكمية التفكير المطلوب. +اطرح سؤالًا بسيطًا مثل "ما هو 15% من 200؟" باستخدام الحماسة المنخفضة. ستحصل على إجابة فورية ومباشرة. الآن اطرح شيئًا معقدًا مثل "صمم استراتيجية تخزين مؤقت لواجهة برمجة تطبيقات عالية الحركة" باستخدام الحماسة العالية. انقر على **🔴 بث الرد (مباشر)** وشاهد التفكير التفصيلي للنموذج يظهر رمزًا تلو الآخر. نفس النموذج، نفس هيكل السؤال - لكن الحث يخبره بكمية التفكير المطلوب. -### تنفيذ المهمة (مقدمات الأدوات) +### تنفيذ المهام (مقدمات الأدوات) -تستفيد سير العمل متعددة الخطوات من التخطيط المسبق وسرد التقدم. يحدد النموذج ما سيفعله، ويروي كل خطوة، ثم يلخص النتائج. +تستفيد تدفقات العمل متعددة الخطوات من التخطيط المسبق وسرد التقدم. يوضح النموذج ما سيفعله، يسرد كل خطوة، ثم يلخص النتائج. -### كود التفكير الذاتي +### الكود العاكس للذات -جرّب "إنشئ خدمة تحقق من البريد الإلكتروني". بدلاً من توليد الكود والتوقف، يولد النموذج، ويقيّم وفقًا لمعايير الجودة، ويحدد نقاط الضعف، ويحسن. سترى تكرارًا حتى يحقق الكود معايير الإنتاج. +جرّب "إنشاء خدمة تحقق من البريد الإلكتروني". بدلاً من مجرد توليد الكود والتوقف، يولد النموذج، ويقيّم وفقاً لمعايير الجودة، ويحدد نقاط الضعف، ويحسّن. سترى تكرار العملية حتى يفي الكود بمعايير الإنتاج. ### التحليل المنظم -مراجعات الكود تحتاج أطر تقييم ثابتة. يحلل النموذج الكود باستخدام فئات محددة (الصحة، الممارسات، الأداء، الأمان) مع مستويات شدة. +تحتاج مراجعات الكود إلى أُطر تقييم متسقة. يحلل النموذج الكود باستخدام فئات ثابتة (الصحة، الممارسات، الأداء، الأمان) مع مستويات شدة. -### المحادثة متعددة الجولات +### الدردشة متعددة الأدوار -اسأل "ما هو Spring Boot؟" ثم تابع فورًا بـ "أرني مثالاً". يتذكر النموذج سؤالك الأول ويعطيك مثالًا محددًا لـ Spring Boot. بدون الذاكرة، سيكون السؤال الثاني غامضًا. +اسأل "ما هو Spring Boot؟" ثم تابع فورًا بـ "اعرض مثالًا". يتذكر النموذج سؤالك الأول ويعطيك مثال Spring Boot محدد. بدون ذاكرة، سيكون السؤال الثاني غامضًا جدًا. -### الشرح خطوة بخطوة +### التفكير خطوة بخطوة -اختر مسألة رياضية وجربها باستخدام كل من الشرح خطوة بخطوة والحماس المنخفض. الحماس المنخفض يعطيك الإجابة فقط - سريع لكنه غير واضح. الشرح خطوة بخطوة يظهر كل عملية حساب وقرار. +اختر مسألة رياضية وجربها مع كل من التفكير خطوة بخطوة والحماسة المنخفضة. الحماسة المنخفضة تعطيك فقط الإجابة - بسرعة ولكن بشكل غامض. التفكير خطوة بخطوة يعرض كل حساب وقرار. -### الإخراج المقيد +### مخرجات مقيدة -عندما تحتاج إلى تنسيقات محددة أو عدد كلمات معين، يفرض هذا النمط الالتزام الصارم. جرب إنشاء ملخص بمائة كلمة بالضبط في صيغة نقاط. +عندما تحتاج إلى تنسيقات محددة أو عدد كلمات محدد، يفرض هذا النمط الالتزام التام. جرّب إنشاء ملخص يحتوي على 100 كلمة تمامًا بصيغة نقاط. -## ما الذي تتعلمه حقًا +## ما تتعلمه حقًا **جهد التفكير يغير كل شيء** -يتيح لك GPT-5.2 التحكم في الجهد الحاسوبي من خلال مطالباتك. الجهد المنخفض يعني ردود سريعة مع استكشاف محدود. الجهد العالي يعني أن النموذج يأخذ وقتًا للتفكير بعمق. أنت تتعلم مطابقة الجهد مع تعقيد المهمة - لا تضيع الوقت على أسئلة بسيطة، ولا تتسرع في القرارات المعقدة. +تتيح لك GPT-5.2 التحكم في الجهد الحاسوبي من خلال ألوماتك. الجهد المنخفض يعني ردود سريعة مع استكشاف قليل، والجهد العالي يعني أن النموذج يأخذ وقتًا للتفكير بعمق. تتعلم مطابقة الجهد مع تعقيد المهمة - لا تهدر الوقت في الأسئلة البسيطة، ولا تتعجل في القرارات المعقدة. -**البنية توجه السلوك** +**التركيب يوجه السلوك** -هل لاحظت علامات XML في المطالبات؟ ليست زخرفية. تتبع النماذج التعليمات المنظمة بشكل أكثر موثوقية من النص الحر. عندما تحتاج إلى عمليات متعددة الخطوات أو منطق معقد، تساعد البنية النموذج على تتبع موقعه وما هو التالي. يوضح الرسم أدناه تحليل مطالبة منظمة جيدًا، يبيّن كيف تنظم العلامات مثل ``, ``, ``, ``, و `` تعليماتك إلى أقسام واضحة. +هل لاحظت علامات XML في الحث؟ ليست للزينة. تتبع النماذج التعليمات المنظمة أكثر موثوقية من النص الحر. عندما تحتاج إلى عمليات متعددة الخطوات أو منطق معقد، يساعد التركيب النموذج على تتبع موقعه والمرحلة التالية. ينفصل المخطط أدناه حثًا منظمًا جيدًا، موضحًا كيف تنظم العلامات مثل ``, ``, ``, ``, و `` تعليماتك إلى أقسام واضحة. -هيكل المطالبة +هيكل الحث -*تشريح مطالبة منظمة جيدًا مع أقسام واضحة وتنظيم بأسلوب XML* +*تشريح حث منظم جيدًا مع أقسام واضحة وتنظيم بأسلوب XML* **الجودة من خلال التقييم الذاتي** -تعمل أنماط التفكير الذاتي من خلال جعل معايير الجودة صريحة. بدلًا من الأمل بأن النموذج "يفعلها بشكل صحيح"، تخبره بالضبط ما يعنيه "الصحيح": المنطق السليم، التعامل مع الأخطاء، الأداء، الأمان. يمكن للنموذج بعد ذلك تقييم مخرجاته وتحسينها. يحول هذا توليد الكود من نوع يانصيب إلى عملية. +تعمل أنماط العاكسة للذات عن طريق جعل معايير الجودة صريحة. بدلاً من الأمل بأن "يفعل النموذج الشيء الصحيح"، أنت تخبره ما هو "الصحيح" بالضبط: منطق صحيح، التعامل مع الأخطاء، الأداء، الأمان. يمكن للنموذج بعد ذلك تقييم مخرجاته وتحسينها. يحول هذا توليد الكود من يانصيب إلى عملية منظمة. **السياق محدود** -تعمل المحادثات متعددة الجولات عبر تضمين تاريخ الرسائل مع كل طلب. لكن هناك حدًا - لكل نموذج حد أقصى لعدد الرموز. مع نمو المحادثات، ستحتاج إلى استراتيجيات للحفاظ على السياق ذي الصلة دون تجاوز الحد. توضح هذه الوحدة كيف تعمل الذاكرة؛ ستتعلم لاحقًا متى تلخص، متى تنسى، ومتى تسترجع. +تعمل المحادثات متعددة الأدوار عن طريق تضمين سجل الرسائل مع كل طلب، لكن هناك حدًا - لكل نموذج حد أقصى للرموز. مع نمو المحادثات، ستحتاج إلى استراتيجيات للحفاظ على السياق ذي الصلة دون الوصول إلى الحد الأعلى. تعرض لك هذه الوحدة كيفية عمل الذاكرة؛ وستتعلم لاحقًا متى تلخص، ومتى تنسى، ومتى تستعيد. -## الخطوات القادمة +## الخطوات التالية -**الوحدة التالية:** [03-rag - التوليد المعزز بالاسترجاع (RAG)](../03-rag/README.md) +**الوحدة التالية:** [03-rag - RAG (التوليد المدعوم بالاستخراج)](../03-rag/README.md) --- -**التنقل:** [← السابق: الوحدة 01 - المقدمة](../01-introduction/README.md) | [العودة إلى الرئيسي](../README.md) | [التالي: الوحدة 03 - RAG →](../03-rag/README.md) +**التنقل:** [← السابق: الوحدة 01 - مقدمة](../01-introduction/README.md) | [عودة للرئيسية](../README.md) | [التالي: الوحدة 03 - RAG →](../03-rag/README.md) --- -**إخلاء مسؤولية**: -تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى جاهدين للدقة، نرجو الانتباه إلى أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. بالنسبة للمعلومات الهامة، يُنصح بالاستعانة بالترجمة البشرية المهنية. نحن غير مسؤولين عن أي سوء فهم أو تفسير خاطئ ناتج عن استخدام هذه الترجمة. +**تنويه**: +تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة. \ No newline at end of file diff --git a/translations/ar/03-rag/README.md b/translations/ar/03-rag/README.md index d9187f9f0..c734780d7 100644 --- a/translations/ar/03-rag/README.md +++ b/translations/ar/03-rag/README.md @@ -1,144 +1,143 @@ -# الوحدة 03: RAG (التوليد المدعوم بالاسترجاع) +# الوحدة 03: RAG (التوليد المعزز بالاسترجاع) ## جدول المحتويات -- [عرض فيديو تفصيلي](../../../03-rag) -- [ما ستتعلمه](../../../03-rag) -- [المتطلبات المسبقة](../../../03-rag) -- [فهم RAG](../../../03-rag) - - [أي نهج RAG يستخدمه هذا الدرس؟](../../../03-rag) -- [كيف يعمل](../../../03-rag) - - [معالجة الوثائق](../../../03-rag) - - [إنشاء التضمينات](../../../03-rag) - - [البحث الدلالي](../../../03-rag) - - [توليد الإجابة](../../../03-rag) -- [تشغيل التطبيق](../../../03-rag) -- [استخدام التطبيق](../../../03-rag) - - [تحميل مستند](../../../03-rag) - - [طرح الأسئلة](../../../03-rag) - - [التحقق من مراجع المصادر](../../../03-rag) - - [التجربة بالأسئلة](../../../03-rag) -- [المفاهيم الرئيسية](../../../03-rag) - - [استراتيجية التجزيء](../../../03-rag) - - [درجات التشابه](../../../03-rag) - - [التخزين في الذاكرة](../../../03-rag) - - [إدارة نافذة السياق](../../../03-rag) -- [متى يكون RAG مهماً](../../../03-rag) -- [الخطوات القادمة](../../../03-rag) - -## عرض فيديو تفصيلي - -شاهد هذا الجلسة الحية التي تشرح كيفية البدء مع هذه الوحدة: - -RAG مع LangChain4j - الجلسة الحية +- [عرض الفيديو](#عرض-الفيديو) +- [ما ستتعلمه](#ما-ستتعلمه) +- [المتطلبات المسبقة](#المتطلبات-المسبقة) +- [فهم RAG](#فهم-rag) + - [أي نهج RAG يستخدم هذا الدرس؟](#أي-نهج-rag-يستخدم-هذا-الدرس؟) +- [كيف يعمل](#كيف-يعمل) + - [معالجة المستندات](#معالجة-المستندات) + - [إنشاء التمثيلات](#إنشاء-التمثيلات) + - [البحث الدلالي](#البحث-الدلالي) + - [توليد الإجابة](#توليد-الإجابة) +- [تشغيل التطبيق](#تشغيل-التطبيق) +- [استخدام التطبيق](#استخدام-التطبيق) + - [تحميل مستند](#رفع-مستند) + - [طرح الأسئلة](#طرح-الأسئلة) + - [فحص مراجع المصادر](#تحقق-من-مراجع-المصادر) + - [التجربة مع الأسئلة](#جرب-بأسئلة-متنوعة) +- [المفاهيم الرئيسية](#المفاهيم-الرئيسية) + - [استراتيجية التقسيم](#استراتيجية-التقسيم-إلى-أجزاء) + - [درجات التشابه](#درجات-التشابه) + - [التخزين في الذاكرة](#التخزين-في-الذاكرة) + - [إدارة نافذة السياق](#إدارة-نافذة-السياق) +- [متى تهم RAG](#متى-يكون-rag-مهمًا) +- [الخطوات التالية](#الخطوات-التالية) + +## عرض الفيديو + +شاهد هذه الجلسة المباشرة التي تشرح كيفية البدء مع هذه الوحدة: + +RAG مع LangChain4j - جلسة مباشرة ## ما ستتعلمه -في الوحدات السابقة، تعلمت كيفية إجراء محادثات مع الذكاء الاصطناعي وتنظيم مطالباتك بفعالية. لكن هناك حد أساسي: نماذج اللغة تعرف فقط ما تعلمته أثناء التدريب. لا يمكنها الإجابة عن أسئلة حول سياسات شركتك، أو توثيق مشروعك، أو أي معلومات لم تتدرب عليها. +في الوحدات السابقة، تعلمت كيفية إجراء محادثات مع الذكاء الاصطناعي وتنظيم مطالباتك بشكل فعّال. لكن هناك قيد أساسي: نماذج اللغة تعرف فقط ما تعلمته أثناء التدريب. لا يمكنها الإجابة عن أسئلة حول سياسات شركتك، أو توثيق مشروعك، أو أي معلومات لم يتم تدريبها عليها. -RAG (التوليد المدعوم بالاسترجاع) يحل هذه المشكلة. بدلاً من محاولة تعليم النموذج معلوماتك (وهو أمر مكلف وغير عملي)، تعطيه القدرة على البحث ضمن مستنداتك. عندما يسأل شخص ما سؤالاً، يجد النظام المعلومات ذات الصلة ويضمّنها في المطالبة. ثم يجيب النموذج بناءً على هذا السياق المسترجع. +RAG (التوليد المعزز بالاسترجاع) يحل هذه المشكلة. بدلًا من محاولة تعليم النموذج معلوماتك (وهو أمر مكلف وغير عملي)، تمنحه القدرة على البحث عبر مستنداتك. عندما يسأل شخص ما سؤالاً، يجد النظام المعلومات ذات الصلة ويُدرجها في المطالبة. ثم يجيب النموذج بناءً على ذلك السياق المسترجع. -فكر في RAG كما لو أنك تمنح النموذج مكتبة مراجع. عندما تسأل سؤالًا، يقوم النظام بـ: +فكر في RAG كأنه يعطي النموذج مكتبة مراجع. عندما تطرح سؤالاً، يقوم النظام بـ: -1. **استعلام المستخدم** - تسأل سؤالًا -2. **التضمين** - يحول سؤالك إلى متجه -3. **بحث المتجهات** - يجد مقاطع مستندات مشابهة +1. **استعلام المستخدم** - أنت تطرح سؤالاً +2. **التمثيل** - يحول سؤالك إلى متجه رقمي +3. **بحث المتجهات** - يعثر على مقاطع مستندات مشابهة 4. **تجميع السياق** - يضيف المقاطع ذات الصلة إلى المطالبة -5. **الرد** - يُولد نموذج اللغة الكبير إجابة بناءً على السياق +5. **الرد** - يقوم نموذج اللغة بتوليد إجابة بناءً على السياق -هذا يجعل ردود النموذج تستند إلى بياناتك الفعلية بدلاً من الاعتماد على معرفته التدريبية أو اختلاق الإجابات. +هذا يجعل ردود النموذج مستندة إلى بياناتك الفعلية بدلاً من الاعتماد على معرفته التدريبية أو اختلاق الإجابات. ## المتطلبات المسبقة -- إتمام [الوحدة 00 - البداية السريعة](../00-quick-start/README.md) (لمثال RAG السهل المشار إليه لاحقًا في هذه الوحدة) -- إتمام [الوحدة 01 - المقدمة](../01-introduction/README.md) (تثبيت موارد Azure OpenAI، بما في ذلك نموذج التضمين `text-embedding-3-small`) -- وجود ملف `.env` في الدليل الجذري يحتوي على بيانات اعتماد Azure (تم إنشاؤه بواسطة أمر `azd up` في الوحدة 01) +- إتمام [الوحدة 01 - المقدمة](../01-introduction/README.md) (نشر موارد Azure OpenAI، بما في ذلك نموذج التمثيل `text-embedding-3-small`) +- وجود ملف `.env` في الدليل الجذري مع بيانات اعتماد Azure (تم إنشاؤه بواسطة `azd up` في الوحدة 01) -> **ملاحظة:** إذا لم تكمل الوحدة 01، فاتبع تعليمات النشر هناك أولاً. يقوم أمر `azd up` بنشر كل من نموذج دردشة GPT ونموذج التضمين المستخدم في هذه الوحدة. +> **ملاحظة:** إذا لم تكمل الوحدة 01، اتبع تعليمات النشر هناك أولاً. تقوم أمر `azd up` بنشر كل من نموذج الدردشة GPT ونموذج التمثيل المستخدم في هذه الوحدة. ## فهم RAG -يوضح الرسم البياني أدناه المفهوم الأساسي: بدلاً من الاعتماد فقط على بيانات تدريب النموذج، يمنح RAG النموذج مكتبة مراجع من مستنداتك ليطلع عليها قبل توليد كل إجابة. +الرسم التوضيحي أدناه يوضح المفهوم الأساسي: بدلًا من الاعتماد فقط على بيانات تدريب النموذج، يمنحه RAG مكتبة مراجعة من مستنداتك ليطلع عليها قبل توليد كل إجابة. ما هو RAG -*يوضح هذا الرسم البياني الفرق بين نموذج لغة كبير قياسي (يخمن بناءً على بيانات التدريب) ونموذج لغة كبير مدعوم بـ RAG (يطلع أولاً على مستنداتك).* +*هذا الرسم يوضح الفرق بين نموذج لغة كبير عادي (يخمن بناءً على بيانات التدريب) ونموذج معزز بـ RAG (يستشير مستنداتك أولاً).* -هكذا تتصل الأجزاء من البداية للنهاية. يتدفق سؤال المستخدم عبر أربع مراحل — التضمين، بحث المتجهات، تجميع السياق، وتوليد الإجابة — كل منها يبني على سابقه: +إليك كيف تتصل الأجزاء من البداية للنهاية. سؤال المستخدم يمر عبر أربع مراحل — التمثيل، بحث المتجه، تجميع السياق، وتوليد الإجابة — كل مرحلة تبني على التي قبلها: -هندسة RAG +هيكلية RAG -*يُظهر هذا الرسم البياني خط أنابيب RAG من البداية للنهاية — حيث يتدفق استعلام المستخدم عبر التضمين، بحث المتجهات، تجميع السياق، وتوليد الإجابة.* +*هذا الرسم يوضح خط أنابيب RAG من البداية إلى النهاية — سؤال المستخدم يمر عبر التمثيل، بحث المتجه، تجميع السياق، وتوليد الإجابة.* -تتبع بقية هذه الوحدة كل مرحلة بالتفصيل، مع الكود الذي يمكنك تشغيله وتعديله. +البقية من هذه الوحدة تشرح كل مرحلة بالتفصيل، مع كود يمكنك تشغيله وتعديله. -### أي نهج RAG يستخدمه هذا الدرس؟ +### أي نهج RAG يستخدم هذا الدرس؟ -يقدم LangChain4j ثلاث طرق لتطبيق RAG، كل منها بمستوى تجريد مختلف. يوضح الرسم البياني أدناه مقارنة بينها جنبًا إلى جنب: +يقدم LangChain4j ثلاث طرق لتنفيذ RAG، كل منها بمستوى مختلف من التجريد. الرسم أدناه يقارنها جنبًا إلى جنب: -ثلاثة نهج لـ RAG في LangChain4j +ثلاثة نهج RAG في LangChain4j -*يقارن هذا الرسم البياني بين الثلاثة نهج لـ RAG في LangChain4j — السهل، والاصلي، والمتقدم — مع عرض مكوناتها الرئيسية وموعد استخدام كل منها.* +*هذا الرسم يقارن بين ثلاثة نهج RAG في LangChain4j — سهولة، أصلي، ومتقدم — موضحًا مكونات كل منهما ومتى تستخدم كل واحد.* -| النهج | ماذا يفعل | المقايضة | +| النهج | ماذا يفعل | الموازنة | |---|---|---| -| **RAG السهل** | يربط كل شيء تلقائيًا عبر `AiServices` و`ContentRetriever`. تقوم بتعريف واجهة، توصل مسترجع المحتوى، ويتولى LangChain4j التعامل مع التضمين، البحث، وتجميع المطالبات في الخلفية. | أقل كود، لكن لا ترى ما يحدث في كل خطوة. | -| **RAG الاصلي** | تستدعي نموذج التضمين، تبحث في المتجر، تبني المطالبة، وتولد الإجابة بنفسك — خطوة صريحة واحدة في كل مرة. | المزيد من الكود، لكن كل مرحلة مرئية وقابلة للتعديل. | -| **RAG المتقدم** | يستخدم إطار عمل `RetrievalAugmentor` مع محولات استعلام قابلة للتوصيل، وموجّهات، وإعادة ترتيب، وحقن محتوى لأنابيب الإنتاج المتقدمة. | أقصى مرونة، لكنه أكثر تعقيدًا بشكل كبير. | +| **RAG السهل** | يربط كل شيء تلقائيًا عبر `AiServices` و `ContentRetriever`. تقوم بالتعليق على واجهة، تربط مسترجعًا، وLangChain4j يتولى التمثيل، البحث، وتجميع المطالبات في الخلفية. | كود قليل، لكن لا ترى ما يحدث في كل خطوة. | +| **RAG الأصلي** | تقوم بنداء نموذج التمثيل، والبحث في المخزن، وبناء المطالبة، وتوليد الإجابة بنفسك — خطوة واحدة صريحة في كل مرة. | كود أكثر، لكن كل مرحلة مرئية وقابلة للتعديل. | +| **RAG المتقدم** | يستخدم إطار `RetrievalAugmentor` مع محولات الاستعلام، الموجهات، معيد الترتيب، وحقن المحتوى، مناسب لأنظمة الإنتاج. | أكبر قدر من المرونة، لكن مع تعقيد أعلى بكثير. | -**يستخدم هذا الدرس النهج الاصلي.** كل خطوة من خط أنابيب RAG — تضمين الاستعلام، البحث في متجر المتجهات، تجميع السياق، وتوليد الإجابة — مكتوبة صراحة في [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). هذا مقصود: كمورد تعلم، من المهم أن ترى وتفهم كل مرحلة بدلاً من تقليل الكود. بمجرد أن تكون مرتاحًا لكيفية ترابط الأجزاء، يمكنك الانتقال إلى RAG السهل للنماذج الأولية السريعة أو RAG المتقدم للأنظمة الإنتاجية. +**هذا الدرس يستخدم النهج الأصلي.** كل خطوة في خط أنابيب RAG — تمثيل الاستعلام، البحث في متجر المتجهات، تجميع السياق، وتوليد الإجابة — مكتوبة بشكل صريح في [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). هذا مقصود: كمورد تعليمي، من المهم أكثر أن ترى وتفهم كل مرحلة بدلاً من تقليل الكود. بمجرد أن تشعر بالراحة مع كيفية توصيل الأجزاء، يمكنك التدرج إلى RAG السهل لنماذج أولية سريعة أو RAG المتقدم لأنظمة الإنتاج. -> **💡 هل سبق ورأيت RAG السهل يعمل؟** تشتمل [وحدة البداية السريعة](../00-quick-start/README.md) على مثال للأسئلة والأجوبة على المستند ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) يستخدم نهج RAG السهل — حيث يتولى LangChain4j التضمين، البحث، وتجميع المطالبات تلقائيًا. تأخذ هذه الوحدة الخطوة التالية بكسر خط الأنابيب لتتمكن من رؤية والتحكم في كل مرحلة بنفسك. +> **💡 مهتم بـ RAG السهل؟** يقدم LangChain4j أيضًا طريقة *RAG سهلة* حيث يتولى `AiServices` و `ContentRetriever` تمثيل، بحث، وتجميع المطالبات تلقائيًا. هذه الوحدة تأخذ الطريق الأكثر صراحة — تكشف ذلك الخط الأنبوبي لتتمكن من رؤية والتحكم في كل مرحلة بنفسك. -يوضح الرسم البياني أدناه خط أنابيب RAG السهل من مثال البداية السريعة هذا. لاحظ كيف تخفي `AiServices` و`EmbeddingStoreContentRetriever` كل التعقيد — فقط تقوم بتحميل مستند، وتوصيل مسترجع، وتحصل على إجابات. النهج الاصلي في هذه الوحدة يكسر كل خطوة مخفية: +الرسم أدناه يوضح خط أنابيب RAG السهل. لاحظ كيف يخفي `AiServices` و `EmbeddingStoreContentRetriever` كل التعقيد — تقوم بتحميل مستند، توصيل مسترجع، وتحصل على إجابات. النهج الأصلي في هذه الوحدة يفتح كل تلك الخطوات الخفية: خط أنابيب RAG السهل - LangChain4j -*يوضح هذا الرسم البياني خط أنابيب RAG السهل من `SimpleReaderDemo.java`. قارن هذا مع النهج الاصلي المستخدم في هذه الوحدة: RAG السهل يخفي التضمين، الاسترجاع، وتجميع المطالبة خلف `AiServices` و`ContentRetriever` — تقوم بتحميل مستند، توصيل مسترجع، وتحصل على إجابات. النهج الاصلي في هذه الوحدة يكسر هذا الخط بحيث تستدعي كل مرحلة (التضمين، البحث، تجميع السياق، التوليد) بنفسك، مما يمنحك رؤية كاملة وتحكمًا كاملاً.* +*هذا الرسم يوضح خط أنابيب RAG السهل. قارن هذا مع النهج الأصلي المستخدم في هذه الوحدة: RAG السهل يخفي التمثيل، الاسترجاع، وتجميع المطالبات خلف `AiServices` و `ContentRetriever` — تقوم بتحميل مستند، توصيل مسترجع، وتحصل على إجابات. النهج الأصلي في هذه الوحدة يفتح هذا الخط الأنبوبي بحيث تستدعي كل مرحلة (التمثيل، البحث، تجميع السياق، التوليد) بنفسك، مما يمنحك رؤية وتحكم كاملين.* ## كيف يعمل -يقسم خط أنابيب RAG في هذه الوحدة إلى أربع مراحل تعمل بالتتابع في كل مرة يطرح المستخدم سؤالًا. أولًا، يتم **تحليل المستند وتحويله إلى مقاطع** يمكن إدارتها. ثم تتحول هذه المقاطع إلى **تضمينات متجهية** ويتم تخزينها لمقارنتها رياضياً. عند وصول استعلام، يجري النظام **بحثًا دلاليًا** لإيجاد المقاطع الأكثر ملاءمة، وأخيراً يمررها كسياق إلى نموذج اللغة الكبير لـ **توليد الإجابة**. الأقسام أدناه تشرح كل مرحلة مع الكود الفعلي والرسوم التوضيحية. لنلق نظرة على الخطوة الأولى. +خط أنابيب RAG في هذه الوحدة يتكون من أربع مراحل تعمل بالتتابع في كل مرة يطرح فيها المستخدم سؤالاً. أولاً، يتم **تحليل المستند وتحويله إلى مقاطع** تُدار بفعالية. ثم تُحوّل هذه المقاطع إلى **تمثيلات متجهة** وتُخزن لتتم مقارنة المتجهات رياضيًا. عند وصول الاستعلام، يقوم النظام بـ **بحث دلالي** لإيجاد المقاطع الأكثر صلة، وأخيرًا يمررها كسياق إلى نموذج اللغة لتوليد **الإجابة**. الأقسام أدناه تشرح كل مرحلة مع الكود الفعلي والرسوم التوضيحية. لننظر في الخطوة الأولى. -### معالجة الوثائق +### معالجة المستندات [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -عندما ترفع مستندًا، يقوم النظام بتحليله (PDF أو نص عادي)، يرفق بيانات وصفية مثل اسم الملف، ثم يقسمه إلى مقاطع — قطع أصغر تناسب نافذة سياق النموذج بشكل مريح. تتداخل هذه المقاطع قليلاً حتى لا تفقد السياق عند الحدود. +عند تحميل مستند، يقوم النظام بتحليله (PDF أو نص عادي)، يضيف بيانات وصفية مثل اسم الملف، ثم يقسمه إلى مقاطع — قطع أصغر تناسب نافذة السياق للنموذج. تتداخل هذه المقاطع قليلاً بحيث لا تفقد السياق عند الحدود. ```java -// تحليل الملف المرفوع وتغليفه في مستند LangChain4j +// تحليل الملف المحمل وتغليفه في مستند LangChain4j Document document = Document.from(content, metadata); -// تقسيم إلى قطع من 300 رمز مع تداخل 30 رمز +// تقسيم إلى أجزاء مكونة من 300 رمز مع تداخل 30 رمز DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -يوضح الرسم البياني أدناه كيف يعمل ذلك بصريًا. لاحظ كيف يشارك كل مقطع بعض الرموز مع جيرانه — تداخل 30 رمزًا يضمن عدم فقدان أي سياق مهم بين المقاطع: +الرسم أدناه يوضح كيف يعمل هذا بصريًا. لاحظ كيف يشارك كل مقطع بعض الرموز المميزة مع جيرانه — تداخل 30 رمزًا يضمن عدم فقدان سياق مهم عند الحدود: -تجزئة المستند +تقسيم المستند إلى مقاطع -*يوضح هذا الرسم البياني مستندًا يُقسم إلى مقاطع مكونة من 300 رمز مع تداخل 30 رمزًا، حفاظًا على السياق عند حدود المقاطع.* +*هذا الرسم يوضح تقسيم مستند إلى مقاطع بحدود 300 رمز مميز مع تداخل 30 رمز مميز، مما يحافظ على السياق عند حدود المقاطع.* -> **🤖 جرب مع دردشة [GitHub Copilot](https://github.com/features/copilot):** افتح [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) واطرح: -> - "كيف يقوم LangChain4j بتقسيم الوثائق إلى مقاطع ولماذا التداخل مهم؟" -> - "ما هو حجم المقطع الأمثل لأنواع الوثائق المختلفة ولماذا؟" -> - "كيف أتعامل مع المستندات متعددة اللغات أو ذات التنسيق الخاص؟" +> **🤖 جرب مع دردشة [GitHub Copilot](https://github.com/features/copilot):** افتح [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) واسأل: +> - "كيف يقسم LangChain4j المستندات إلى مقاطع ولماذا التداخل مهم؟" +> - "ما هو الحجم الأمثل للمقطع لأنواع الوثائق المختلفة ولماذا؟" +> - "كيف أتعامل مع المستندات بلغات متعددة أو ذات تنسيق خاص؟" -### إنشاء التضمينات +### إنشاء التمثيلات [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -يتم تحويل كل مقطع إلى تمثيل رقمي يُسمى تضمينًا — وهو في الأساس محول من معنى إلى أرقام. نموذج التضمين ليس "ذكيًا" مثل نموذج الدردشة؛ لا يمكنه اتباع التعليمات، أو التفكير، أو الإجابة على الأسئلة. ما يمكنه فعله هو رسم النص داخل فضاء رياضي حيث تقع المعاني المتشابهة بالقرب من بعضها البعض — "سيارة" بالقرب من "مركبة"، "سياسة استرداد" بالقرب من "إعادة أموالي". فكر في نموذج الدردشة كشخص تتحدث إليه؛ ونموذج التضمين كنظام تنظيم ملفات فعال للغاية. +يتم تحويل كل مقطع إلى تمثيل رقمي يُسمى التمثيل — وهو محول من المعنى إلى أرقام. نموذج التمثيل ليس "ذكيًا" كما نموذج الدردشة؛ لا يمكنه اتباع التعليمات، أو الاستدلال، أو الإجابة على الأسئلة. ما يمكنه فعله هو تحويل النص إلى فضاء رياضي حيث تتجمع المعاني المتشابهة — مثل "سيارة" بجانب "عربة"، "سياسة استرداد" بجانب "إرجاع أموالي". فكر في نموذج الدردشة كشخص يمكن التحدث إليه؛ ونموذج التمثيل كنظام أرشفة قوي جدًا. -يصور الرسم البياني أدناه هذا المفهوم — يدخل النص، تخرج المتجهات الرقمية، والمعاني المشابهة تنتج متجهات متقاربة: +الرسم أدناه يصور هذا المفهوم — يدخل النص، تخرج متجهات رقمية، والمعاني المشابهة تنتج متجهات قريبة: -مفهوم نموذج التضمين +مفهوم نموذج التمثيل -*يوضح هذا الرسم كيف يحول نموذج التضمين النص إلى متجهات رقمية، موضحًا كيف تترتب المعاني المتشابهة — مثل "سيارة" و"مركبة" — قرب بعضها البعض في الفضاء المتجهي.* +*هذا الرسم يوضح كيف يحول نموذج التمثيل النص إلى متجهات رقمية، بحيث توضع المعاني المشابهة — مثل "سيارة" و"عربة" — متقاربة في فضاء المتجهات.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -يوضح مخطط الفئات أدناه التدفقات المنفصلة في خط أنابيب RAG وفئات LangChain4j التي تنفذها. يتضمن **تدفق الإدخال** (يعمل مرة واحدة عند الرفع) تقسيم المستند، تضمين المقاطع، وتخزينها عبر `.addAll()`. بينما **تدفق الاستعلام** (يعمل في كل مرة يطرح فيها المستخدم سؤالًا) يُضمّن السؤال، يبحث في المتجر عبر `.search()`, ويمرر السياق المطابق إلى نموذج الدردشة. يلتقي التدفقان عند واجهة `EmbeddingStore` المشتركة: +الرسم البياني للطبقات أدناه يُظهر تدفقين منفصلين في خط أنابيب RAG وفئات LangChain4j التي تنفذها. **تدفق الإدخال** (يعمل مرة عند التحميل) يقسم المستند، يمثل المقاطع، ويخزنها عبر `.addAll()`. **تدفق الاستعلام** (يعمل في كل مرة يطرح المستخدم سؤالًا) يمثل السؤال، يبحث في المخزن عبر `.search()`, ويمرر السياق المطابق لنموذج الدردشة. يلتقي التدفقان عند واجهة `EmbeddingStore` المشتركة: -فئات RAG في LangChain4j +فئات LangChain4j RAG -*يوضح هذا الرسم البياني التدفقين في خط أنابيب RAG — الإدخال والاستعلام — وكيف يتصلان عبر EmbeddingStore المشترك.* +*هذا الرسم يوضح التدفقين في خط أنابيب RAG — الإدخال والاستعلام — وكيف يتصلان عبر EmbeddingStore المشتركة.* -بعد تخزين التضمينات، يتجمع المحتوى المتشابه بشكل طبيعي في الفضاء المتجهي. يُظهر التصور أدناه كيف تنتهي الوثائق المتعلقة بموضوعات مشابهة كنقاط متقاربة، وهذا ما يجعل البحث الدلالي ممكنًا: +بعد تخزين التمثيلات، يتجمع المحتوى المشابه تلقائيًا في فضاء المتجهات. التصور أدناه يوضح كيف تنتهي الوثائق ذات المواضيع المتصلة كنقاط قريبة، وهذا ما يجعل البحث الدلالي ممكنًا: -فضاء التضمينات المتجهية +فضاء تمثيلات المتجهات -*يوضح هذا التصور كيف تتجمع الوثائق ذات الصلة معًا في فضاء ثلاثي الأبعاد للمتجهات، مع تكوين مجموعات مميزة مثل الوثائق التقنية، قواعد العمل، والأسئلة الشائعة.* +*هذا التصور يوضح كيف تتجمع الوثائق ذات صلة في فضاء متجه ثلاثي الأبعاد، مع تكتلات لمواضيع مثل الوثائق التقنية، قواعد الأعمال، والأسئلة الشائعة.* -عندما يبحث المستخدم، يتبع النظام أربع خطوات: تضمين الوثائق مرة واحدة، تضمين الاستعلام في كل بحث، مقارنة متجه الاستعلام مع كل المتجهات المخزنة باستخدام تشابه جيب التمام، وإرجاع أعلى K مقطع بحسب الدرجة. يشرح الرسم البياني أدناه كل خطوة وفئات LangChain4j المتضمنة: +عند البحث، يتبع النظام أربع خطوات: تمثيل الوثائق مرة واحدة، تمثيل الاستعلام في كل بحث، مقارنة متجه الاستعلام مع كل المتجهات المخزنة باستخدام تشابه جيب التمام، وإرجاع أفضل المقاطع ذات الدرجات العليا K. الرسم أدناه يشرح كل خطوة وفئات LangChain4j المرتبطة: -خطوات بحث التضمين +خطوات بحث التمثيلات -*يوضح هذا الرسم الخطوات الأربع لعملية بحث التضمين: تضمين الوثائق، تضمين الاستعلام، مقارنة المتجهات باستخدام تشابه جيب التمام، وإرجاع أعلى النتائج K.* +*هذا الرسم يوضح عملية البحث بالتمثيل ذات الأربع خطوات: تمثيل الوثائق، تمثيل الاستعلام، مقارنة المتجهات بتشابه جيب التمام، وإرجاع أفضل النتائج K.* ### البحث الدلالي [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -عندما تطرح سؤالًا، يصبح سؤالك أيضًا تضمينًا. يقارن النظام تضمين سؤالك مع جميع تضمينات مقاطع المستندات. يجد المقاطع التي تحمل معاني متقاربة — ليس مجرد تطابق كلمات مفتاحية، بل التشابه الدلالي الفعلي. +عندما تطرح سؤالًا، يتحول سؤالك أيضًا إلى تمثيل. يقارن النظام تمثيل سؤالك مع تمثيلات كل مقاطع المستندات. يعثر على المقاطع التي تحمل معاني مشابهة - ليس مجرد تطابق كلمات مفتاحية، بل تشابه دلالي حقيقي. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -يوضح الرسم البياني أدناه مقارنة بين البحث الدلالي وبحث الكلمات المفتاحية التقليدي. بحث الكلمة المفتاحية عن "مركبة" يتجاهل مقطعًا عن "السيارات والشاحنات"، لكن البحث الدلالي يفهم أنهما يعنيان نفس الشيء ويُرجع المقطع بدرجة عالية: +الرسم أدناه يقارن البحث الدلالي بالبحث بالكلمة المفتاحية التقليدي. بحث بالكلمة المفتاحية عن "مركبة" يفقد مقطعًا عن "سيارات وشاحنات"، لكن البحث الدلالي يفهم أنهما تعنيان الشيء نفسه ويُرجعها كنتيجة ذات درجة عالية: البحث الدلالي -*يقارن هذا الرسم البحث القائم على الكلمات المفتاحية مع البحث الدلالي، ويُظهر كيف يسترجع البحث الدلالي محتوى مرتبطًا مفهوميًا حتى عندما تختلف الكلمات المفتاحية الدقيقة.* -تحت الغطاء، يتم قياس التشابه باستخدام التشابه الكوني — وهو في الأساس سؤال "هل هذان السهمان يشيران إلى نفس الاتجاه؟" يمكن لقطعتين استخدام كلمات مختلفة تمامًا، ولكن إذا كانتا تعنيان نفس الشيء فإن المتجهات تشير إلى نفس الاتجاه وتحصل على درجة قريبة من 1.0: +*هذا الرسم يقارن البحث المعتمد على الكلمات المفتاحية مع البحث الدلالي، مبيّنًا كيف يسترجع البحث الدلالي محتوى ذا علاقة مفهومية حتى عندما تختلف الكلمات الدقيقة.* -التشابه الكوني +تحت الغطاء، يُقاس التشابه باستخدام تشابه جيب التمام — أي: "هل هذان السهمان يشيران لنفس الاتجاه؟" يمكن أن تستخدم مقطعين كلمات مختلفة تمامًا، ولكن إن كانا يحملان نفس المعنى تكون متجهاتهما متجهات متقاربة وتأتي بدرجة قريبة من 1.0: -*توضح هذه الرسمة التشابه الكوني كزاوية بين متجهات التضمين — المتجهات الأكثر توافقًا تسجل درجة أقرب إلى 1.0، مما يشير إلى تشابه دلالي أعلى.* +تشابه جيب التمام +*يوضح هذا المخطط تشابه جيب التمام كزاوية بين متجهات التضمين — المتجهات الأكثر تطابقًا تحصل على درجة أقرب إلى 1.0، مما يشير إلى تشابه دلالي أعلى.* -> **🤖 جرب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) واسأل: +> **🤖 جرّب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) واسأل: > - "كيف يعمل البحث بالتشابه مع التضمينات وما الذي يحدد الدرجة؟" -> - "ما هو عتبة التشابه التي يجب أن أستخدمها وكيف تؤثر على النتائج؟" -> - "كيف أتعامل مع الحالات التي لا يتم فيها العثور على مستندات ذات صلة؟" +> - "ما هو الحد الأدنى لتشابه يجب استخدامه وكيف يؤثر على النتائج؟" +> - "كيف أتعامل مع الحالات التي لا يتم العثور فيها على مستندات ذات صلة؟" ### توليد الإجابة [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -يتم تجميع القطع الأكثر صلة في مطالبة منظمة تتضمن تعليمات صريحة، والسياق المسترجع، وسؤال المستخدم. يقرأ النموذج هذه القطع المحددة ويجيب بناءً على تلك المعلومات — لا يمكنه استخدام سوى ما هو أمامه، مما يمنع الهلوسة. +يتم تجميع أكثر الأجزاء ذات الصلة في موجه منظم يتضمن تعليمات صريحة، والسياق المسترجع، وسؤال المستخدم. يقرأ النموذج تلك الأجزاء المحددة ويجيب بناءً على تلك المعلومات — يمكنه فقط استخدام ما هو أمامه، مما يمنع الهلوسة. ```java String context = matches.stream() @@ -236,36 +235,36 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` - -تظهر الرسمة أدناه هذا التجميع أثناء العمل — حيث يتم حقن القطع ذات أعلى الدرجات من خطوة البحث في قالب المطالبة، ويولد `OpenAiOfficialChatModel` إجابة موثوقة: -تجميع السياق +يُظهر المخطط أدناه هذا التجميع أثناء العمل — يتم حقن أعلى الأجزاء تقييمًا من خطوة البحث في قالب الموجه، ويولّد `OpenAiOfficialChatModel` إجابة مؤصلة: -*تُظهر هذه الرسمة كيفية تجميع القطع ذات أعلى الدرجات في مطالبة منظمة، مما يسمح للنموذج بتوليد إجابة موثوقة من بياناتك.* +Context Assembly + +*يُظهر هذا المخطط كيفية تجميع الأجزاء الأعلى تقييمًا في موجه منظم، مما يسمح للنموذج بتوليد إجابة مستندة إلى بياناتك.* ## تشغيل التطبيق -**التحقق من النشر:** +**تحقق من النشر:** -تأكد من وجود ملف `.env` في الدليل الجذر يحتوي على بيانات اعتماد Azure (تم إنشاؤها خلال الوحدة 01). شغّل هذا من دليل الوحدة (`03-rag/`): +تأكد من وجود ملف `.env` في الدليل الجذري يحتوي على بيانات اعتماد Azure (تم إنشاؤه أثناء الوحدة 01). شغّل هذا من دليل الوحدة (`03-rag/`): -**Bash:** +**بـاش:** ```bash -cat ../.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT +cat ../.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT و API_KEY و DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT و API_KEY و DEPLOYMENT +Get-Content ..\.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT ``` - -**بدء التطبيق:** -> **ملاحظة:** إذا كنت قد بدأت جميع التطبيقات باستخدام `./start-all.sh` من الدليل الجذر (كما هو موصوف في الوحدة 01)، فإن هذه الوحدة تعمل على المنفذ 8081 بالفعل. يمكنك تخطي أوامر البدء أدناه والانتقال مباشرة إلى http://localhost:8081. +**ابدأ التطبيق:** + +> **ملاحظة:** إذا كنت قد بدأت جميع التطبيقات باستخدام `./start-all.sh` من الدليل الجذري (كما هو موضح في الوحدة 01)، فهذه الوحدة تعمل بالفعل على المنفذ 8081. يمكنك تخطي أوامر البدء أدناه والذهاب مباشرة إلى http://localhost:8081. -**الخيار 1: استخدام لوحة تحكم Spring Boot (مُوصى به لمستخدمي VS Code)** +**الخيار 1: استخدام لوحة تحكم Spring Boot (مُوصَى به لمستخدمي VS Code)** -يتضمن حاوية التطوير امتداد لوحة تحكم Spring Boot الذي يوفر واجهة بصرية لإدارة جميع تطبيقات Spring Boot. يمكنك العثور عليه في شريط النشاط على الجانب الأيسر من VS Code (ابحث عن رمز Spring Boot). +تتضمن الحاوية التطويرية إضافة Spring Boot Dashboard، التي توفر واجهة بصرية لإدارة جميع تطبيقات Spring Boot. يمكنك العثور عليها في شريط النشاط على الجانب الأيسر من VS Code (ابحث عن أيقونة Spring Boot). من لوحة تحكم Spring Boot، يمكنك: - رؤية جميع تطبيقات Spring Boot المتاحة في مساحة العمل @@ -273,154 +272,153 @@ Get-Content ..\.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT و API_KEY و - عرض سجلات التطبيق في الوقت الحقيقي - مراقبة حالة التطبيق -ببساطة انقر على زر التشغيل بجوار "rag" لبدء هذه الوحدة، أو ابدأ جميع الوحدات مرة واحدة. +فقط انقر على زر التشغيل بجانب "rag" لبدء هذه الوحدة، أو ابدأ جميع الوحدات دفعة واحدة. -لوحة تحكم Spring Boot +Spring Boot Dashboard -*تُظهر هذه اللقطة شاشة لوحة تحكم Spring Boot في VS Code، حيث يمكنك بدء وإيقاف ومراقبة التطبيقات بصريًا.* +*تُظهر هذه اللقطة شاشة لوحة تحكم Spring Boot في VS Code، حيث يمكنك بدء التطبيقات وإيقافها ومراقبتها بصريًا.* -**الخيار 2: استخدام سكربتات الشيل** +**الخيار 2: استخدام سكربتات الشِل** ابدأ جميع تطبيقات الويب (الوحدات 01-04): -**Bash:** +**بـاش:** ```bash -cd .. # من دليل الجذر +cd .. # من الدليل الجذري ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell -cd .. # من الدليل الجذري +cd .. # من الدليل الجذر .\start-all.ps1 ``` - + أو ابدأ هذه الوحدة فقط: -**Bash:** +**بـاش:** ```bash cd 03-rag ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 03-rag .\start.ps1 ``` - -كلا السكربتين يقوم تلقائيًا بتحميل متغيرات البيئة من ملف `.env` الجذري وسيبني ملفات JAR إذا لم تكن موجودة. + +يقوم كلا السكربتين بتحميل متغيرات البيئة تلقائيًا من ملف `.env` الجذري وسيبني ملفات JAR إذا لم تكن موجودة. > **ملاحظة:** إذا كنت تفضل بناء جميع الوحدات يدويًا قبل البدء: > -> **Bash:** +> **بـاش:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + افتح http://localhost:8081 في متصفحك. -**لإيقاف التطبيق:** +**لإيقاف التشغيل:** -**Bash:** +**بـاش:** ```bash ./stop.sh # هذا الوحدة فقط # أو -cd .. && ./stop-all.sh # جميع الوحدات +cd .. && ./stop-all.sh # كل الوحدات ``` - -**PowerShell:** + +**PowerShell:** ```powershell -.\stop.ps1 # هذا الوحدة فقط +.\stop.ps1 # هذا الموديول فقط # أو -cd ..; .\stop-all.ps1 # كل الوحدات +cd ..; .\stop-all.ps1 # جميع الموديولات ``` - ## استخدام التطبيق -يوفر التطبيق واجهة ويب لتحميل المستندات وطرح الأسئلة. +يقدم التطبيق واجهة ويب لتحميل المستندات وطرح الأسئلة. -واجهة تطبيق RAG +RAG Application Interface -*توضح هذه اللقطة شاشة واجهة تطبيق RAG حيث تقوم بتحميل المستندات وطرح الأسئلة.* +*تُظهر هذه اللقطة شاشة واجهة تطبيق RAG حيث تقوم بتحميل المستندات وطرح الأسئلة.* -### تحميل مستند +### رفع مستند -ابدأ بتحميل مستند - ملفات TXT تعمل بشكل أفضل للاختبار. يوفر هذا الدليل ملف `sample-document.txt` يحتوي على معلومات حول ميزات LangChain4j وتنفيذ RAG وأفضل الممارسات — مثالي لاختبار النظام. +ابدأ برفع مستند — ملفات TXT هي الأفضل للاختبار. تم توفير `sample-document.txt` في هذا الدليل يحتوي على معلومات حول ميزات LangChain4j، وتنفيذ RAG، وأفضل الممارسات — مثالي لاختبار النظام. -يقوم النظام بمعالجة مستندك، وتقسيمه إلى قطع، وإنشاء تضمينات لكل قطعة. يحدث هذا تلقائيًا عند التحميل. +يقوم النظام بمعالجة مستندك، وتقسيمه إلى أجزاء، وإنشاء تضمينات لكل جزء. يتم ذلك تلقائيًا عند الرفع. ### طرح الأسئلة -اطرح الآن أسئلة محددة حول محتوى المستند. جرّب شيئًا واقعيًا مذكورًا بوضوح في المستند. يبحث النظام عن القطع ذات الصلة، ويضمنها في المطالبة، ويولد الإجابة. +الآن اطرح أسئلة محددة حول محتوى المستند. جرب شيئًا واقعيًا مذكورًا بوضوح في المستند. يبحث النظام عن الأجزاء ذات الصلة، ويضمّنها في الموجه، ثم يولد إجابة. -### التحقق من مراجع المصدر +### تحقق من مراجع المصادر -لاحظ أن كل إجابة تتضمن مراجع للمصدر مع درجات التشابه. تظهر هذه الدرجات (من 0 إلى 1) مدى ملاءمة كل قطعة لسؤالك. الدرجات الأعلى تعني تطابقًا أفضل. هذا يتيح لك التحقق من الإجابة مقابل المادة المصدرية. +لاحظ أن كل إجابة تتضمن مراجع مصادر مع درجات التشابه. تظهر هذه الدرجات (من 0 إلى 1) مدى صلة كل جزء بسؤالك. الدرجات الأعلى تعني تطابقًا أفضل. هذا يتيح لك التحقق من الإجابة مقابل المواد المصدرية. -نتائج استعلام RAG +RAG Query Results -*تُظهر هذه اللقطة شاشة نتائج الاستعلام مع الإجابة المولدة، ومراجع المصدر، ودرجات الصلة لكل قطعة مسترجعة.* +*تُظهر هذه اللقطة شاشة نتائج الاستعلام مع الإجابة المولدة، مراجع المصادر، ودرجات الصلة لكل جزء مسترجَع.* -### جرب أنواعًا مختلفة من الأسئلة +### جرب بأسئلة متنوعة -جرّب أنواعًا مختلفة من الأسئلة: -- حقائق محددة: "ما هو الموضوع الرئيسي؟" -- مقارنات: "ما الفرق بين X و Y؟" -- ملخصات: "لخص النقاط الرئيسية حول Z" +جرب أنواعًا مختلفة من الأسئلة: +- حقائق محددة: "ما الموضوع الرئيسي؟" +- مقارنات: "ما الفرق بين X و Y ؟" +- ملخصات: "لخص النقاط الرئيسية عن Z" -راقب كيف تتغير درجات الصلة بناءً على مدى تطابق سؤالك مع محتوى المستند. +شاهد كيف تتغير درجات الصلة بناءً على مدى تطابق سؤالك مع محتوى المستند. ## المفاهيم الرئيسية -### استراتيجية تقسيم القطع +### استراتيجية التقسيم إلى أجزاء -يتم تقسيم المستندات إلى قطع تحتوي على 300 رمز مع تداخل 30 رمزًا. يضمن هذا التوازن أن تحتوي كل قطعة على سياق كافٍ لتكون ذات معنى بينما تبقى صغيرة بما يكفي لتضمين قطع متعددة في مطالبة. +يتم تقسيم المستندات إلى أجزاء مكونة من 300 رمز مع تداخل 30 رمزًا. هذا التوازن يضمن أن كل جزء لديه سياق كاف ليكون ذا معنى مع بقائه صغيرًا بما يكفي لتضمين عدة أجزاء في الموجه. ### درجات التشابه -كل قطعة مسترجعة تأتي مع درجة تشابه بين 0 و 1 تشير إلى مدى تطابقها مع سؤال المستخدم. توضح الرسمة أدناه نطاقات الدرجات وكيف يستخدمها النظام لتصفية النتائج: +كل جزء مسترجع يأتي مع درجة تشابه بين 0 و 1 تشير إلى مدى قرب تطابقه مع سؤال المستخدم. يوضح المخطط أدناه نطاقات الدرجات وكيف يستخدمها النظام لتصفية النتائج: -درجات التشابه +Similarity Scores -*تُظهر هذه الرسمة نطاقات الدرجات من 0 إلى 1، مع عتبة دنيا 0.5 التي تصفي القطع غير ذات الصلة.* +*يُظهر هذا المخطط نطاقات الدرجات من 0 إلى 1، مع حد أدنى 0.5 لتصفية الأجزاء غير ذات الصلة.* -تتراوح الدرجات من 0 إلى 1: -- 0.7-1.0: ذات صلة عالية، تطابق دقيق -- 0.5-0.7: ذات صلة، سياق جيد -- أقل من 0.5: تم تصفيتها، غير متشابهة بما فيه الكفاية +تتراوح الدرجات من 0 إلى 1: +- 0.7-1.0: ذات صلة عالية، تطابق دقيق +- 0.5-0.7: ذات صلة، سياق جيد +- أقل من 0.5: تم تصفيتها، غير متشابهة كفاية -يسترجع النظام فقط القطع التي تتجاوز العتبة الدنيا لضمان الجودة. +يسترجع النظام فقط الأجزاء التي تتجاوز الحد الأدنى لضمان جودة. -تعمل التضمينات جيدًا عندما تتجمع المعاني بوضوح، لكنها لها نقاط ضعف. توضح الرسمة أدناه أوضاع الفشل الشائعة — القطع الكبيرة جدًا تنتج متجهات غير واضحة، والقطع الصغيرة جدًا تفتقر للسياق، والمصطلحات الغامضة تشير إلى عدة تجمعات، والبحث المطابق تمامًا (معرفات، أرقام أجزاء) لا يعمل مع التضمينات على الإطلاق: +تعمل التضمينات جيدًا عندما تتجمع المعاني بوضوح، لكنها تحتوي على نقاط عمياء. يُظهر المخطط أدناه أوضاع الفشل الشائعة — الأجزاء الكبيرة جدًا تنتج متجهات غير واضحة، الأجزاء الصغيرة جدًا تفتقر للسياق، المصطلحات المبهمة تشير إلى عدة تجمعات، والبحث بالمطابقة الحرفية (المعرفات، أرقام الأجزاء) لا يعمل مع التضمينات على الإطلاق: -أوضاع فشل التضمين +Embedding Failure Modes -*تُظهر هذه الرسمة أوضاع الفشل الشائعة في التضمين: قطع كبيرة جدًا، قطع صغيرة جدًا، مصطلحات غامضة تشير إلى تجمعات متعددة، والبحث المطابق تمامًا مثل المعرفات.* +*يُظهر هذا المخطط أوضاع الفشل الشائعة في التضمين: أجزاء كبيرة جدًا، أجزاء صغيرة جدًا، مصطلحات غامضة تشير إلى عدة تجمعات، وبحث المطابقة الحرفية مثل المعرفات.* ### التخزين في الذاكرة -تستخدم هذه الوحدة التخزين في الذاكرة للبساطة. عند إعادة تشغيل التطبيق، تفقد المستندات المحملة. تستخدم أنظمة الإنتاج قواعد بيانات متجهات دائمة مثل Qdrant أو Azure AI Search. +يستخدم هذا الموديول التخزين في الذاكرة للبساطة. عند إعادة تشغيل التطبيق، تُفقد المستندات المحملة. تستخدم أنظمة الإنتاج قواعد بيانات متجهات دائمة مثل Qdrant أو Azure AI Search. ### إدارة نافذة السياق -لكل نموذج حد أقصى لنافذة السياق. لا يمكنك تضمين كل قطعة من مستند كبير. يسترجع النظام أفضل N قطع ذات صلة (الافتراضي 5) ليبقى ضمن الحدود مع توفير سياق كافٍ لإجابات دقيقة. +لكل نموذج حد أقصى لنافذة السياق. لا يمكنك تضمين كل جزء من مستند كبير. يسترجع النظام أعلى N أجزاء صلة (افتراضي 5) للبقاء ضمن الحدود مع توفير سياق كافٍ لإجابات دقيقة. ## متى يكون RAG مهمًا -ليس RAG دائمًا النهج الصحيح. يساعدك دليل القرار أدناه على تحديد متى يضيف RAG قيمة مقابل متى تكون الأساليب الأبسط — مثل تضمين المحتوى مباشرة في المطالبة أو الاعتماد على المعرفة المدمجة في النموذج — كافية: +لا يكون RAG دائمًا النهج المناسب. يساعدك دليل القرار أدناه على تحديد متى يضيف RAG قيمة مقابل متى تكون الطرق الأبسط — مثل تضمين المحتوى مباشرة في الموجه أو الاعتماد على معرفة النموذج المدمجة — كافية: -متى تستخدم RAG +When to Use RAG -*تُظهر هذه الرسمة دليل قرار لمتى يضيف RAG قيمة مقابل متى تكون الأساليب الأبسط كافية.* +*يُظهر هذا المخطط دليل قرار لمتى يضيف RAG قيمة مقابل متى تكون الطرق الأبسط كافية.* ## الخطوات التالية @@ -428,11 +426,11 @@ cd ..; .\stop-all.ps1 # كل الوحدات --- -**التنقل:** [← السابق: الوحدة 02 - هندسة المطالبة](../02-prompt-engineering/README.md) | [عودة إلى الرئيسي](../README.md) | [التالي: الوحدة 04 - الأدوات →](../04-tools/README.md) +**التنقل:** [← السابق: الوحدة 02 - هندسة الموجه](../02-prompt-engineering/README.md) | [العودة للرئيسية](../README.md) | [التالي: الوحدة 04 - الأدوات →](../04-tools/README.md) --- -**إخلاء المسؤولية**: -تم ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). بالرغم من حرصنا على الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الموثوق والمعتمد. بالنسبة للمعلومات الهامة، يُنصح بالاعتماد على الترجمة الاحترافية من قبل مترجم بشري. نحن غير مسؤولين عن أي سوء فهم أو تفسير خاطئ قد ينشأ بسبب استخدام هذه الترجمة. +**تنويه**: +تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة. \ No newline at end of file diff --git a/translations/ar/04-tools/README.md b/translations/ar/04-tools/README.md index 7d1a52d55..a5f1aead5 100644 --- a/translations/ar/04-tools/README.md +++ b/translations/ar/04-tools/README.md @@ -1,84 +1,84 @@ -# الوحدة 04: الوكلاء الذكاء الاصطناعي مع الأدوات +# الوحدة 04: وكلاء الذكاء الاصطناعي مع الأدوات ## جدول المحتويات -- [الجولة التوضيحية بالفيديو](../../../04-tools) -- [ما ستتعلمه](../../../04-tools) -- [المتطلبات الأساسية](../../../04-tools) -- [فهم وكلاء الذكاء الاصطناعي مع الأدوات](../../../04-tools) -- [كيف يعمل استدعاء الأدوات](../../../04-tools) - - [تعريفات الأدوات](../../../04-tools) - - [اتخاذ القرار](../../../04-tools) - - [التنفيذ](../../../04-tools) - - [توليد الاستجابة](../../../04-tools) - - [البنية: التوصيل التلقائي في Spring Boot](../../../04-tools) -- [سلسلة الأدوات](../../../04-tools) -- [تشغيل التطبيق](../../../04-tools) -- [استخدام التطبيق](../../../04-tools) - - [تجربة استخدام أداة بسيطة](../../../04-tools) - - [اختبار سلسلة الأدوات](../../../04-tools) - - [مشاهدة تدفق المحادثة](../../../04-tools) - - [تجربة طلبات مختلفة](../../../04-tools) -- [المفاهيم الرئيسية](../../../04-tools) - - [نمط ReAct (التفكير والفعل)](../../../04-tools) - - [أهمية وصف الأدوات](../../../04-tools) - - [إدارة الجلسة](../../../04-tools) - - [التعامل مع الأخطاء](../../../04-tools) -- [الأدوات المتاحة](../../../04-tools) -- [متى تستخدم الوكلاء المعتمدين على الأدوات](../../../04-tools) -- [الأدوات مقابل RAG](../../../04-tools) -- [الخطوات التالية](../../../04-tools) - -## الجولة التوضيحية بالفيديو - -شاهد هذه الجلسة المباشرة التي تشرح كيفية البدء مع هذه الوحدة: +- [مرور فيديو](#video-walkthrough) +- [ما الذي ستتعلمه](#what-youll-learn) +- [المتطلبات المسبقة](#prerequisites) +- [فهم وكلاء الذكاء الاصطناعي مع الأدوات](#understanding-ai-agents-with-tools) +- [كيف يعمل استدعاء الأداة](#how-tool-calling-works) + - [تعريفات الأدوات](#tool-definitions) + - [اتخاذ القرار](#decision-making) + - [التنفيذ](#execution) + - [توليد الاستجابة](#response-generation) + - [الهيكلية: الربط التلقائي في Spring Boot](#architecture-spring-boot-auto-wiring) +- [ربط الأدوات](#tool-chaining) +- [تشغيل التطبيق](#run-the-application) +- [استخدام التطبيق](#استخدام-التطبيق) + - [تجربة استخدام أداة بسيطة](#جرب-استخدام-أداة-بسيطة) + - [اختبار ربط الأدوات](#اختبر-ربط-الأدوات) + - [رؤية تدفق المحادثة](#شاهد-سير-المحادثة) + - [تجربة طلبات مختلفة](#جرب-طلبات-مختلفة) +- [المفاهيم الأساسية](#المفاهيم-الرئيسية) + - [نمط ReAct (التفكير والفعل)](#نمط-react-التفكير-والعمل) + - [أهمية أوصاف الأدوات](#وصف-الأدوات-مهم) + - [إدارة الجلسة](#إدارة-الجلسات) + - [التعامل مع الأخطاء](#التعامل-مع-الأخطاء) +- [الأدوات المتاحة](#الأدوات-المتاحة) +- [متى تستخدم الوكلاء المعتمدين على الأدوات](#متى-تستخدم-وكلاء-قائمين-على-الأدوات) +- [الأدوات مقابل RAG](#الأدوات-مقابل-نظام-الاسترجاع-والاستدلال-rag) +- [الخطوات التالية](#الخطوات-التالية) + +## Video Walkthrough + +شاهد هذا الجلسة المباشرة التي تشرح كيفية البدء مع هذه الوحدة: وكلاء الذكاء الاصطناعي مع الأدوات و MCP - جلسة مباشرة -## ما ستتعلمه +## What You'll Learn -حتى الآن، تعلمت كيفية إجراء محادثات مع الذكاء الاصطناعي، وكيفية بناء المطالبات بشكل فعال، وربط الاستجابات بوثائقك. لكن لا يزال هناك قيد أساسي: نماذج اللغة يمكنها فقط توليد النصوص. لا يمكنها التحقق من الطقس، أو إجراء الحسابات، أو الاستعلام عن قواعد البيانات، أو التفاعل مع الأنظمة الخارجية. +حتى الآن، تعلمت كيف تجري محادثات مع الذكاء الاصطناعي، وكيف تهيكل المطالبات بفعالية، وتربط الاستجابات بوثائقك. ولكن هناك قيد أساسي: نماذج اللغة يمكنها فقط توليد النصوص. لا يمكنها التحقق من الطقس، أو إجراء حسابات، أو الاستعلام في قواعد البيانات، أو التفاعل مع الأنظمة الخارجية. -الأدوات تغير هذا. من خلال تزويد النموذج بوصول إلى دوال يمكن استدعاؤها، تتحول من مولد نصوص إلى وكيل يمكنه اتخاذ إجراءات. يقرر النموذج متى يحتاج إلى أداة، وأي أداة يستخدم، وما المعاملات التي يمررها. يقوم الكود الخاص بك بتنفيذ الدالة وإرجاع النتيجة. يدمج النموذج تلك النتيجة في استجابته. +الأدوات تغير هذا. من خلال منح النموذج إمكانية الوصول إلى دوال يمكنه استدعاؤها، تحول النموذج من مولد نص إلى وكيل يمكنه اتخاذ إجراءات. يقرر النموذج متى يحتاج إلى أداة، أي أداة يستخدم، وما هي المعلمات التي يمررها. ينفذ الكود الخاص بك الدالة ويعيد النتيجة. يدمج النموذج تلك النتيجة في استجابته. -## المتطلبات الأساسية +## Prerequisites - إكمال [الوحدة 01 - المقدمة](../01-introduction/README.md) (تم نشر موارد Azure OpenAI) -- يُنصح بإكمال الوحدات السابقة (تشير هذه الوحدة إلى [مفاهيم RAG من الوحدة 03](../03-rag/README.md) في مقارنة الأدوات مقابل RAG) +- إكمال الوحدات السابقة موصى به (تشير هذه الوحدة إلى [مفاهيم RAG من الوحدة 03](../03-rag/README.md) في مقارنة الأدوات مقابل RAG) - وجود ملف `.env` في الدليل الجذري مع بيانات اعتماد Azure (تم إنشاؤه بواسطة `azd up` في الوحدة 01) > **ملاحظة:** إذا لم تكمل الوحدة 01، فاتبع تعليمات النشر هناك أولاً. -## فهم وكلاء الذكاء الاصطناعي مع الأدوات +## Understanding AI Agents with Tools -> **📝 ملاحظة:** مصطلح "الوكلاء" في هذه الوحدة يشير إلى مساعدين ذكيين تم تعزيزهم بقدرات استدعاء الأدوات. وهذا يختلف عن أنماط **Agentic AI** (الوكلاء المستقلون مع التخطيط، والذاكرة، والتفكير متعدد الخطوات) التي سنغطيها في [الوحدة 05: MCP](../05-mcp/README.md). +> **📝 ملاحظة:** مصطلح "وكلاء" في هذه الوحدة يشير إلى مساعدين ذكيين معززین بإمكانات استدعاء الأدوات. هذا يختلف عن أنماط **Agentic AI** (وكلاء مستقلون مع تخطيط وذاكرة وتفكير متعدد الخطوات) التي سنتناولها في [الوحدة 05: MCP](../05-mcp/README.md). -بدون أدوات، يمكن لنموذج اللغة فقط توليد النص من بيانات تدريبه. اسأله عن الطقس الحالي، وسيضطر للتخمين. أعطه أدوات، فيمكنه استدعاء API للطقس، أو إجراء الحسابات، أو الاستعلام في قاعدة بيانات — ثم يدمج تلك النتائج الحقيقية في استجابته. +بدون أدوات، يمكن لنموذج اللغة فقط توليد النص من بيانات التدريب. اسأله عن الطقس الحالي، وعليه التخمين. زوده بالأدوات، ويمكنه استدعاء API الطقس، إجراء الحسابات، أو الاستعلام في قاعدة بيانات — ثم يدمج تلك النتائج الحقيقية في استجابته. بدون أدوات مقابل مع أدوات -*بدون أدوات، يمكن للنموذج فقط التخمين — مع الأدوات يمكنه استدعاء APIs، إجراء الحسابات، وإرجاع بيانات في الوقت الفعلي.* +*بدون أدوات، النموذج يخمن فقط — مع الأدوات يمكنه استدعاء APIs، إجراء حسابات، وإرجاع بيانات في الوقت الحقيقي.* -وكيل الذكاء الاصطناعي مع الأدوات يتبع نمط **ReAct (التفكير والفعل)**. النموذج لا يكتفي بالرد — بل يفكر فيما يحتاجه، يتصرف باستدعاء أداة، يلاحظ النتيجة، ثم يقرر ما إذا كان سيتصرف مجددًا أو يقدّم الإجابة النهائية: +وكيل الذكاء الاصطناعي مع الأدوات يتبع نمط **التفكير والفعل (ReAct)**. النموذج لا يكتفي بالاستجابة — بل يفكر فيما يحتاجه، يتصرف عبر استدعاء أداة، يلاحظ النتيجة، ثم يقرر ما إذا كان عليه التصرف مرة أخرى أو تقديم الإجابة النهائية: -1. **التفكير** — يحلل الوكيل سؤال المستخدم ويحدد ما هي المعلومات التي يحتاجها -2. **الفعل** — يختار الوكيل الأداة الصحيحة، يولد المعاملات المناسبة، ويستدعيها -3. **الملاحظة** — يتلقى الوكيل خرج الأداة ويقيّم النتيجة -4. **التكرار أو الرد** — إذا كانت البيانات الإضافية ضرورية، يعود الوكيل إلى البداية؛ وإلا، يصيغ إجابة بلغة طبيعية +1. **التفكير** — يحلل الوكيل سؤال المستخدم ويحدد المعلومات التي يحتاجها +2. **التصرف** — يختار الوكيل الأداة الصحيحة، يولد المعلمات الصحيحة، ويستدعيها +3. **المراقبة** — يتلقى الوكيل مخرجات الأداة ويقيّم النتيجة +4. **التكرار أو الرد** — إذا كانت هناك حاجة لمزيد من المعلومات، يعود الوكيل للحلقة؛ وإلا يؤلف إجابة بلغة طبيعية نمط ReAct -*دورة ReAct — الوكيل يفكر في ما عليه فعله، يتصرف باستدعاء أداة، يلاحظ النتيجة، ويكرر حتى يقدم الإجابة النهائية.* +*دورة ReAct — الوكيل يفكر في ما يجب فعله، يتصرف باستدعاء أداة، يراقب النتيجة، ويكرر حتى يستطيع تقديم الإجابة النهائية.* -يحدث هذا تلقائيًا. تقوم بتعريف الأدوات وأوصافها. يتولى النموذج اتخاذ القرار حول متى وكيف يستخدمها. +يحدث هذا تلقائيًا. تقوم بتعريف الأدوات وأوصافها. النموذج يتولى اتخاذ القرار حول متى وكيف يستخدمها. -## كيف يعمل استدعاء الأدوات +## How Tool Calling Works -### تعريفات الأدوات +### Tool Definitions [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -تعرف الدوال بوصف واضح ومواصفات المعاملات. يرى النموذج هذه الأوصاف داخل موجه النظام ويفهم ما تقوم به كل أداة. +تعرف دوالًا بأوصاف واضحة ومواصفات المعلمات. يرى النموذج هذه الأوصاف في طلب النظام ويفهم ما تقوم به كل أداة. ```java @Component @@ -96,147 +96,147 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// يتم توصيل المساعد تلقائيًا بواسطة Spring Boot مع: -// - عنصر ChatModel +// يتم ربط المساعد تلقائيًا بواسطة Spring Boot مع: +// - مكون ChatModel // - جميع طرق @Tool من فئات @Component // - مزود ChatMemory لإدارة الجلسات ``` - -يوضح الرسم التخطيطي أدناه كل تعليق توضيحي ويشرح كيف يساعد كل جزء الذكاء الاصطناعي على فهم متى يستدعي الأداة وما هي المعاملات التي يجب تمريرها: + +يوضح المخطط أدناه كل توضيح ويبيّن كيف يساعد كل جزء الذكاء الاصطناعي على معرفة متى يستدعي الأداة وأي المعلمات يمرر: تشريح تعريفات الأدوات -*تشريح تعريف الأداة — @Tool تخبر الذكاء الاصطناعي متى يستخدمها، @P تصف كل معامل، و @AiService توصل كل شيء تلقائيًا عند بدء التشغيل.* +*تشريح تعريف أداة — @Tool يخبر الذكاء الاصطناعي متى يستخدمها، @P يصف كل معلمة، و @AiService يربط كل شيء معًا عند بدء التشغيل.* -> **🤖 جرب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) واسأل: -> - "كيف أدمج API حقيقي للطقس مثل OpenWeatherMap بدلًا من البيانات الوهمية؟" -> - "ما الذي يجعل وصف الأداة جيدًا ويساعد الذكاء الاصطناعي على استخدامها بشكل صحيح؟" -> - "كيف أتعامل مع أخطاء API وحدود المعدل في تنفيذ الأدوات؟" +> **🤖 جرّب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) واسأل: +> - "كيف أدمج API طقس حقيقي مثل OpenWeatherMap بدلًا من بيانات وهمية؟" +> - "ما الذي يجعل وصف الأداة جيدًا ويساعد الذكاء الاصطناعي على استخدامها بشكل صحيح؟" +> - "كيف أتعامل مع أخطاء API وحدود الاستخدام في تنفيذ الأدوات؟" -### اتخاذ القرار +### Decision Making -عندما يسأل المستخدم "ما هو الطقس في سياتل؟"، لا يختار النموذج أداة عشوائيًا. يقارن نية المستخدم مع كل وصف أداة متاح لديه، ويقيم كل واحد من حيث الصلة، ويختار الأنسب. ثم يولد استدعاء دالة منسقًا بالمعاملات الصحيحة — في هذه الحالة، يضبط `location` إلى `"Seattle"`. +عندما يسأل المستخدم "ما حالة الطقس في سياتل؟"، لا يختار النموذج أداة عشوائياً. يقارن نية المستخدم مع كل وصف أداة متاح، يقيم كل واحدة من حيث الصلة، ويختار التطابق الأفضل. ثم يولد استدعاء دالة منظم مع المعلمات الصحيحة — في هذه الحالة، تعيين `location` إلى `"Seattle"`. -إذا لم تطابق أية أداة طلب المستخدم، يلجأ النموذج للإجابة من معارفه. إذا طابقت عدة أدوات، يختار الأداة الأكثر تحديدًا. +إذا لم يتطابق أي أداة مع طلب المستخدم، يعود النموذج ليجيب من معرفته الخاصة. إذا تطابق عدة أدوات، يختار الأكثر تحديدًا. كيف يقرر الذكاء الاصطناعي الأداة التي يستخدمها -*يقيم النموذج كل أداة متاحة مقابل نية المستخدم ويختار الأنسب — لهذا السبب كتابة وصف واضح ومحدد للأدوات مهمة.* +*النموذج يقيم كل أداة متاحة مقابل نية المستخدم ويختار أفضل تطابق — لذلك فإن كتابة أوصاف أدوات واضحة ومحددة مهمة.* -### التنفيذ +### Execution [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -يعتمد Spring Boot التوصيل التلقائي بين واجهة `@AiService` التصريحية وجميع الأدوات المسجلة، وينفذ LangChain4j استدعاءات الأدوات تلقائيًا. خلف الكواليس، يمر استدعاء الأداة الكامل بست مراحل — من سؤال المستخدم بلغة طبيعية حتى إجابة بلغة طبيعية: +يقوم Spring Boot بالربط التلقائي لواجهة `@AiService` التصريحية مع كل الأدوات المسجلة، وينفذ LangChain4j استدعاءات الأدوات تلقائيًا. خلف الكواليس، يمر استدعاء الأداة بمرحلة كاملة من ست مراحل — من سؤال المستخدم بلغة طبيعية حتى الرد بلغة طبيعية: -تدفق استدعاء الأدوات +تدفق استدعاء الأداة -*تدفق من البداية إلى النهاية — يطرح المستخدم سؤالاً، يختار النموذج أداة، ينفذ LangChain4j أداة، ثم يدمج النموذج النتيجة في استجابة طبيعية.* +*التدفق من البداية للنهاية — المستخدم يطرح سؤالًا، النموذج يختار أداة، LangChain4j ينفذها، والنموذج يدمج النتيجة في رد طبيعي.* -إذا شغلت [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) في الوحدة 00، فقد شاهدت هذا النمط فعليًا — حيث تم استدعاء أدوات `Calculator` بنفس الطريقة. يوضح مخطط التسلسل أدناه ما حدث تحت الكواليس أثناء تلك التجربة: +خلف الكواليس، تقوم `AiServices` بتشغيل دورة استدعاء الأداة نفسها لأي أداة — هنا موضحة بـ `Calculator` بسيطة. يوضح مخطط التسلسل أدناه بالضبط ما يحدث تحت الغطاء: -مخطط تسلسل استدعاء الأدوات +مخطط تسلسل استدعاء الأداة -*حلقة استدعاء الأداة من تجربة البدء السريع — `AiServices` يرسل رسالتك ومخططات الأدوات إلى نموذج اللغة الكبير، ويرد النموذج باستدعاء دالة مثل `add(42, 58)`, ثم ينفذ LangChain4j دالة `Calculator` محليًا، ويرجع النتيجة للإجابة النهائية.* +*دورة استدعاء الأداة — `AiServices` يرسل رسالتك ومخططات الأداة إلى LLM، ويرد LLM باستدعاء دالة مثل `add(42, 58)`, LangChain4j ينفذ دالة `Calculator` محليًا، ويرسل النتيجة إلى الجواب النهائي.* -> **🤖 جرب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) واسأل: -> - "كيف يعمل نمط ReAct ولماذا هو فعال لوكلاء الذكاء الاصطناعي؟" -> - "كيف يقرر الوكيل أي أداة يستخدم وبأي ترتيب؟" -> - "ماذا يحدث إذا فشل تنفيذ أداة – كيف أتعامل مع الأخطاء بشكل قوي؟" +> **🤖 جرّب مع [GitHub Copilot](https://github.com/features/copilot) Chat:** افتح [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) واسأل: +> - "كيف يعمل نمط ReAct ولماذا هو فعال لوكلاء الذكاء الاصطناعي؟" +> - "كيف يقرر الوكيل أي أداة يستخدم وبأي ترتيب؟" +> - "ماذا يحدث إذا فشل تنفيذ أداة - كيف أتعامل مع الأخطاء بطريقة قوية؟" -### توليد الاستجابة +### Response Generation -يتلقى النموذج بيانات الطقس ويحوّلها إلى استجابة بلغة طبيعية للمستخدم. +يستلم النموذج بيانات الطقس ويصيغها في رد بلغة طبيعية للمستخدم. -### البنية: التوصيل التلقائي في Spring Boot +### Architecture: Spring Boot Auto-Wiring -تستخدم هذه الوحدة تكامل LangChain4j مع Spring Boot عبر واجهات `@AiService` التصريحية. عند بدء التشغيل، يكتشف Spring Boot كل `@Component` الذي يحتوي على طرق `@Tool`، حمولة `ChatModel`، وموفر الذاكرة `ChatMemoryProvider` — ثم يربطهم كلهم ضمن واجهة `Assistant` واحدة بدون أي شيفرة تمهيدية (boilerplate). +تستخدم هذه الوحدة تكامل LangChain4j مع Spring Boot عبر واجهات `@AiService` التصريحية. عند بدء التشغيل، يكتشف Spring Boot كل `@Component` يحتوي على دوال `@Tool`، وقطعة `ChatModel`، ومزود الذاكرة `ChatMemoryProvider` — ثم يربطها جميعًا في واجهة `Assistant` واحدة بدون أي شيفرة تكرارية. -بنية التوصيل التلقائي في Spring Boot +هيكلية الربط التلقائي في Spring Boot -*واجهة @AiService تربط ChatModel، مكونات الأدوات، وموفر الذاكرة — Spring Boot يدير كل التوصيلات تلقائيًا.* +*واجهة @AiService تربط معًا ChatModel، مكونات الأدوات، ومزود الذاكرة — وSpring Boot يتولى كل الربط تلقائيًا.* -إليك دورة حياة الطلب كاملة كمخطط تسلسلي — من طلب HTTP عبر المتحكم (controller) والخدمة والوكيل المتصل تلقائيًا، وصولًا إلى تنفيذ الأداة والعودة: +ها هي دورة حياة الطلب كاملةً في مخطط تسلسل — من طلب HTTP مرورًا بالتحكم، الخدمة، والوكيل المرتبط تلقائيًا، وحتى تنفيذ الأداة والعودة: -مخطط تسلسل استدعاء الأدوات في Spring Boot +مخطط تسلسل استدعاء أدوات Spring Boot -*دورة حياة طلب Spring Boot كاملة — طلب HTTP يمر عبر المتحكم والخدمة إلى وكيل Assistant الموصل تلقائيًا، الذي ينظم نموذج اللغة الكبير واستدعاءات الأدوات تلقائيًا.* +*دورة حياة طلب Spring Boot كاملة — طلب HTTP يمر عبر المتحكم والخدمة إلى وكيل Assistant المرتبط تلقائيًا، الذي يدير LLM واستدعاءات الأدوات تلقائيًا.* -مزايا هذا النهج الرئيسية: +الفوائد الرئيسية لهذا النهج: -- **التوصيل التلقائي في Spring Boot** — حقن ChatModel والأدوات تلقائيًا -- **نمط @MemoryId** — إدارة الذاكرة الجلسية تلقائيًا -- **مثيل واحد** — يتم إنشاء المساعد مرة واحدة ويعاد استخدامه لتحسين الأداء -- **تنفيذ آمن نوعيًا** — استدعاء طرق Java مباشرة مع تحويل النوع -- **تنسيق متعدد الأدوار** — يدير سلسة الأدوات تلقائيًا -- **لا كود تمهيدي** — لا حاجة لاستدعاءات `AiServices.builder()` يدوية أو جداول HashMap للذاكرة +- **الربط التلقائي في Spring Boot** — حقن ChatModel والأدوات تلقائيًا +- **نمط @MemoryId** — إدارة الذاكرة المبنية على الجلسة تلقائيًا +- **نسخة واحدة** — إنشاء Assistant مرة واحدة وإعادة استخدامها لأداء أفضل +- **تنفيذ آمن نوعيًا** — استدعاء دوال جافا مباشرة مع تحويل نوع المعطيات +- **تنسيق متعدد الجولات** — يتعامل تلقائيًا مع ربط الأدوات +- **صفر شيفرة تكرارية** — لا حاجة لاستدعاءات يدوية لـ `AiServices.builder()` أو HashMap للذاكرة -الطرق البديلة (استخدام `AiServices.builder()` يدويًا) تتطلب شيفرة أكثر وتفتقد مزايا تكامل Spring Boot. +النهج البديلة (اليدوية عبر `AiServices.builder()`) تتطلب مزيدًا من الشيفرة وتفتقد فوائد تكامل Spring Boot. -## سلسلة الأدوات +## Tool Chaining -**سلسلة الأدوات** — القوة الحقيقية للوكلاء المعتمدين على الأدوات تظهر عندما يتطلب سؤال واحد استخدام أدوات متعددة. اسأل "ما هو الطقس في سياتل بالفهرنهايت؟" والوكيل يربط تلقائيًا أداتين: أولًا يستدعي `getCurrentWeather` للحصول على درجة الحرارة بالسيليزي، ثم يمرر تلك القيمة إلى `celsiusToFahrenheit` للتحويل — كل ذلك في جولة محادثة واحدة. +**ربط الأدوات** — القوة الحقيقية للوكلاء المعتمدين على الأدوات تظهر عندما يتطلب سؤال واحد عدة أدوات. اسأل "ما حالة الطقس في سياتل بالفهرنهايت؟" وسيقوم الوكيل تلقائيًا بربط أداتين: أولًا يستدعي `getCurrentWeather` للحصول على درجة الحرارة بالسيليزيوس، ثم يمرر تلك القيمة إلى `celsiusToFahrenheit` للتحويل — كل ذلك في جولة محادثة واحدة. -مثال سلسلة الأدوات +مثال ربط الأدوات -*سلسلة الأدوات قيد التنفيذ — الوكيل يستدعي getCurrentWeather أولًا، ثم يمرر نتيجة السيليزي إلى celsiusToFahrenheit، ويقدم إجابة مدمجة.* +*ربط الأدوات في العمل — الوكيل يستدعي getCurrentWeather أولًا، ثم يمرر النتيجة بالسيليزي إلى celsiusToFahrenheit، ويقدم إجابة مجمعة.* -**التعامل الراقي مع الفشل** — اطلب حالة الطقس في مدينة غير موجودة ضمن البيانات الوهمية. ترجع الأداة رسالة خطأ، ويشرح الذكاء الاصطناعي أنه لا يمكنه المساعدة بدلاً من تعطل التطبيق. تفشل الأدوات بأمان. الرسم أدناه يقارن بين الطريقتين — مع التعامل الصحيح مع الأخطاء، يلتقط الوكيل الاستثناء ويستجيب مع توضيح مفيد، بينما بدون ذلك يتعطل التطبيق بأكمله: +**الفشل اللطيف** — اطلب حالة الطقس في مدينة غير موجودة في بيانات النموذج الوهمية. ترجع الأداة رسالة خطأ، ويشرح الذكاء الاصطناعي أنه لا يمكنه المساعدة بدلاً من التعطل. الأدوات تفشل بأمان. يوضح المخطط أدناه المقارنتين — مع التعامل الصحيح مع الأخطاء، يلتقط الوكيل الاستثناء ويرد بشكل مفيد، بينما بدون ذلك يتعطل التطبيق بأكمله: تدفق التعامل مع الأخطاء -*عندما تفشل الأداة، يلتقط الوكيل الخطأ ويرد بتوضيح مفيد بدلاً من تعطل التطبيق.* +*عندما تفشل الأداة، يلتقط الوكيل الخطأ ويرد بشرح مفيد بدلاً من التعطل.* -يحدث هذا في جولة محادثة واحدة. ينظم الوكيل استدعاءات الأدوات المتعددة بشكل مستقل. +يحدث هذا في جولة محادثة واحدة. الوكيل ينظم استدعاءات متعددة للأدوات بشكل مستقل. -## تشغيل التطبيق +## Run the Application -**تأكد من النشر:** +**تحقق من النشر:** -تأكد من وجود ملف `.env` في الدليل الجذري مع بيانات اعتماد Azure (تم إنشاؤه خلال الوحدة 01). شغّل الأمر التالي من دليل الوحدة (`04-tools/`): +تأكد من وجود ملف `.env` في الدليل الجذري مع بيانات اعتماد Azure (تم إنشاؤه أثناء الوحدة 01). شغّل هذا من دليل الوحدة (`04-tools/`): -**Bash:** +**Bash:** ```bash -cat ../.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT +cat ../.env # يجب عرض AZURE_OPENAI_ENDPOINT و API_KEY و DEPLOYMENT ``` -**PowerShell:** +**PowerShell:** ```powershell -Get-Content ..\.env # يجب أن يعرض AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT +Get-Content ..\.env # يجب عرض AZURE_OPENAI_ENDPOINT وAPI_KEY وDEPLOYMENT ``` **ابدأ التطبيق:** -> **ملاحظة:** إذا كنت قد بدأت جميع التطبيقات باستخدام `./start-all.sh` من الدليل الجذري (كما هو موضح في الوحدة 01)، فإن هذه الوحدة تعمل بالفعل على المنفذ 8084. يمكنك تخطي أوامر البدء أدناه والذهاب مباشرة إلى http://localhost:8084. +> **ملاحظة:** إذا كنت قد بدأت جميع التطبيقات باستخدام `./start-all.sh` من الدليل الجذري (كما هو موضح في الوحدة 01)، فهذه الوحدة تعمل بالفعل على المنفذ 8084. يمكنك تخطي أوامر البدء أدناه والذهاب مباشرة إلى http://localhost:8084. **الخيار 1: استخدام لوحة تحكم Spring Boot (مُوصى به لمستخدمي VS Code)** -تحوي الحاوية التطويرية إضافة لوحة تحكم Spring Boot، التي توفر واجهة بصرية لإدارة جميع تطبيقات Spring Boot. يمكنك إيجادها في شريط النشاط على الجانب الأيسر من VS Code (ابحث عن أيقونة Spring Boot). +تتضمن حاوية التطوير إضافة Spring Boot Dashboard، التي توفر واجهة مرئية لإدارة جميع تطبيقات Spring Boot. يمكنك العثور عليها في شريط الأنشطة على الجانب الأيسر من VS Code (ابحث عن رمز Spring Boot). -من لوحة تحكم Spring Boot يمكنك: -- رؤية جميع تطبيقات Spring Boot المتوفرة في مساحة العمل -- بدء/إيقاف التطبيقات بنقرة واحدة -- عرض سجلات التطبيقات في الوقت الفعلي -- مراقبة حالة التطبيقات -فقط انقر على زر التشغيل بجانب "الأدوات" لبدء هذه الوحدة، أو ابدأ جميع الوحدات دفعة واحدة. +من لوحة تحكم Spring Boot، يمكنك: +- رؤية جميع تطبيقات Spring Boot المتاحة في مساحة العمل +- بدء/إيقاف التطبيقات بنقرة واحدة +- عرض سجلات التطبيق في الوقت الحقيقي +- مراقبة حالة التطبيق -إليك كيف يبدو لوحة تحكم Spring Boot في VS Code: +فقط انقر زر التشغيل بجانب "tools" لبدء هذه الوحدة، أو ابدأ جميع الوحدات دفعة واحدة. -لوحة تحكم Spring Boot +إليك كيف تبدو لوحة تحكم Spring Boot في VS Code: +لوحة معلومات Spring Boot -*لوحة تحكم Spring Boot في VS Code — بدء، إيقاف، ومراقبة جميع الوحدات من مكان واحد* +*لوحة معلومات Spring Boot في VS Code — بدء التشغيل، الإيقاف، والمراقبة لجميع الوحدات من مكان واحد* **الخيار 2: استخدام سكربتات الشل** -ابدأ كل تطبيقات الويب (الوحدات 01-04): +ابدأ جميع تطبيقات الويب (الوحدات 01-04): -**Bash:** +**باش:** ```bash cd .. # من الدليل الجذر ./start-all.sh ``` -**PowerShell:** +**باورشل:** ```powershell cd .. # من الدليل الجذري .\start-all.ps1 @@ -244,29 +244,29 @@ cd .. # من الدليل الجذري أو ابدأ هذه الوحدة فقط: -**Bash:** +**باش:** ```bash cd 04-tools ./start.sh ``` -**PowerShell:** +**باورشل:** ```powershell cd 04-tools .\start.ps1 ``` -كلا السكربتين يقومان تلقائيًا بتحميل متغيرات البيئة من ملف `.env` في الجذر وسيقومان ببناء ملفات JAR إذا لم تكن موجودة. +يقوم كلا السكربتين بتحميل متغيرات البيئة تلقائيًا من ملف `.env` في الجذر وسيبني ملفات JAR إذا لم تكن موجودة. -> **ملاحظة:** إذا كنت تفضل بناء كل الوحدات يدويًا قبل البدء: +> **ملاحظة:** إذا كنت تفضل بناء جميع الوحدات يدويًا قبل البدء: > -> **Bash:** +> **باش:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell:** +> **باورشل:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests @@ -274,102 +274,102 @@ cd 04-tools افتح http://localhost:8084 في متصفحك. -**للتوقف:** +**لإيقاف التشغيل:** -**Bash:** +**باش:** ```bash ./stop.sh # هذا الوحدة فقط # أو -cd .. && ./stop-all.sh # جميع الوحدات +cd .. && ./stop-all.sh # كل الوحدات ``` -**PowerShell:** +**باورشل:** ```powershell -.\stop.ps1 # هذا الوحدة فقط +.\stop.ps1 # هذا الموديول فقط # أو -cd ..; .\stop-all.ps1 # جميع الوحدات +cd ..; .\stop-all.ps1 # جميع الموديولات ``` ## استخدام التطبيق -يوفر التطبيق واجهة ويب حيث يمكنك التفاعل مع وكيل ذكاء اصطناعي يمتلك أدوات للوصول إلى الطقس وتحويل درجات الحرارة. إليك كيف تبدو الواجهة — تتضمن أمثلة بدء سريعة ولوحة محادثة لإرسال الطلبات: +يوفر التطبيق واجهة ويب حيث يمكنك التفاعل مع وكيل ذكاء اصطناعي لديه إمكانية الوصول إلى أدوات الطقس وتحويل درجات الحرارة. هكذا تبدو الواجهة — تشمل أمثلة بداية سريعة ولوحة محادثة لإرسال الطلبات: واجهة أدوات وكيل الذكاء الاصطناعي -*واجهة أدوات وكيل الذكاء الاصطناعي - أمثلة سريعة وواجهة دردشة للتفاعل مع الأدوات* +*واجهة أدوات وكيل الذكاء الاصطناعي - أمثلة سريعة وواجهة محادثة للتفاعل مع الأدوات* ### جرب استخدام أداة بسيطة -ابدأ بطلب مباشر: "حوّل 100 درجة فهرنهايت إلى سلسيوس". يتعرف الوكيل على حاجته لأداة تحويل درجات الحرارة، يستدعيها بالمعاملات الصحيحة، ويعيد النتيجة. لاحظ كم يشعر ذلك طبيعيًا — لم تحدد أي أداة تستخدم أو كيف تستدعيها. +ابدأ بطلب بسيط: "حوّل 100 درجة فهرنهايت إلى مئوية". يدرك الوكيل أنه يحتاج أداة تحويل درجة الحرارة، ويستدعيها بالمعلمات الصحيحة، ويرجع النتيجة. لاحظ كم هذا يبدو طبيعيًا - لم تحدد الأداة التي تستخدمها أو كيفية استدعائها. ### اختبر ربط الأدوات -جرب الآن شيئا أكثر تعقيدًا: "ما هو الطقس في سياتل وقم بتحويله إلى فهرنهايت؟" شاهد الوكيل يعمل على ذلك بخطوات. يحصل أولًا على الطقس (الذي يعيد درجات سلسيوس)، يتعرف على حاجته للتحويل إلى فهرنهايت، يستدعي أداة التحويل، ويجمع كلا النتيجتين في رد واحد. +جرب الآن شيئًا أكثر تعقيدًا: "كيف الطقس في سياتل وحول إلى فهرنهايت؟" شاهد الوكيل يعمل على ذلك خطوة بخطوة. أولًا يحصل على الطقس (الذي يرجع المئوية)، يدرك أنه يحتاج لتحويلها إلى فهرنهايت، يستدعي أداة التحويل، ويدمج النتيجتين في رد واحد. -### شاهد تدفق المحادثة +### شاهد سير المحادثة -تحافظ واجهة الدردشة على سجل المحادثة، مما يسمح لك بإجراء تفاعلات متعددة الجولات. يمكنك رؤية كافة الاستعلامات والردود السابقة، مما يسهل متابعة المحادثة وفهم كيف يبني الوكيل السياق عبر تبادلات متعددة. +تحافظ واجهة المحادثة على سجل المحادثة، مما يتيح لك التفاعل على عدة جولات. يمكنك رؤية جميع الاستفسارات والردود السابقة، مما يسهل تتبع المحادثة وفهم كيف يبني الوكيل السياق عبر عدة تبادلات. محادثة مع استدعاءات أدوات متعددة -*محادثة متعددة الجولات تُظهر تحويلات بسيطة، عمليات بحث عن الطقس، وربط الأدوات* +*محادثة متعددة الجولات تظهر تحويلات بسيطة، استعلامات الطقس، وربط الأدوات* ### جرب طلبات مختلفة -جرب تركيبات متنوعة: -- عمليات بحث الطقس: "ما هو الطقس في طوكيو؟" -- تحويلات الحرارة: "ما هي 25 درجة سلسيوس بالكلفن؟" -- الاستعلامات المركبة: "تحقق من الطقس في باريس وأخبرني إذا كانت أعلى من 20 درجة سلسيوس" +جرّب العديد من التركيبات: +- استعلامات الطقس: "كيف الطقس في طوكيو؟" +- تحويلات درجات الحرارة: "كم تساوي 25 مئوية بالكلفن؟" +- استعلامات مركبة: "تحقق من الطقس في باريس وأخبرني إذا كان فوق 20 درجة مئوية" -لاحظ كيف يفسر الوكيل اللغة الطبيعية ويربطها باستدعاءات الأدوات المناسبة. +لاحظ كيف يفسر الوكيل اللغة الطبيعية ويربطها باستدعاءات الأدوات الملائمة. -## المفاهيم الأساسية +## المفاهيم الرئيسية ### نمط ReAct (التفكير والعمل) -يتناوب الوكيل بين التفكير (تقرير ما يجب فعله) والعمل (استخدام الأدوات). يمكّن هذا النمط من حل المشاكل بشكل مستقل بدلاً من مجرد الاستجابة للتعليمات. +يتناوب الوكيل بين التفكير (تقرير ما يجب فعله) والعمل (استخدام الأدوات). هذا النمط يمكّنه من حل المشكلات بشكل مستقل بدلاً من مجرد الرد على التعليمات. ### وصف الأدوات مهم -جودة وصف أدواتك تؤثر بشكل مباشر على كيفية استخدام الوكيل لها. الأوصاف الواضحة والمحددة تساعد النموذج على فهم متى وكيف يستدعي كل أداة. +جودة وصف الأدوات تؤثر مباشرة على كيفية استخدام الوكيل لها. أوصاف واضحة ومحددة تساعد النموذج على فهم متى وكيف يستدعي كل أداة. -### إدارة الجلسة +### إدارة الجلسات -تمكن التعليمة @MemoryId إدارة الذاكرة القائمة على الجلسات تلقائيًا. يحصل كل معرف جلسة على مثيل `ChatMemory` خاص به يديره الـ `ChatMemoryProvider` بحيث يمكن لعدة مستخدمين التفاعل مع الوكيل في نفس الوقت دون أن تختلط محادثاتهم. يوضح الرسم البياني التالي كيف يتم توجيه عدة مستخدمين إلى خزانات ذاكرة معزولة بناءً على معرفات جلساتهم: +تُمكّن التعليمة `@MemoryId` إدارة الذاكرة القائمة على الجلسات تلقائيًا. كل معرف جلسة يحصل على مثيل خاص من `ChatMemory` تُدار بواسطة وحدة `ChatMemoryProvider`، مما يسمح بتفاعل عدة مستخدمين مع الوكيل في نفس الوقت دون اختلاط محادثاتهم. يُظهر المخطط التالي كيف يتم توجيه المستخدمين إلى مخازن ذاكرة معزولة بناءً على معرفات الجلسة: -إدارة الجلسة مع @MemoryId +إدارة الجلسة باستخدام @MemoryId -*كل معرف جلسة يرتبط بتاريخ محادثة معزول — المستخدمون لا يرون رسائل بعضهم البعض مطلقًا.* +*كل معرف جلسة يربط بسجل محادثة معزول — لا يرى المستخدمون رسائل بعضهم البعض أبدًا.* ### التعامل مع الأخطاء -يمكن أن تفشل الأدوات — مهلات API، قد تكون المعاملات غير صالحة، تخرج الخدمات الخارجية عن العمل. يحتاج الوكلاء في الإنتاج إلى التعامل مع الأخطاء حتى يتمكن النموذج من شرح المشكلات أو محاولة بدائل بدلاً من تعطل التطبيق كله. عندما ترمي أداة استثناء، يمسك LangChain4j به ويرسل رسالة الخطأ إلى النموذج، الذي يمكنه بعد ذلك شرح المشكلة بلغة طبيعية. +قد تفشل الأدوات — انتهاء مهلة الواجهات البرمجية، معلمات خاطئة، تعطل خدمات خارجية. يحتاج الوكلاء في الإنتاج إلى التعامل مع الأخطاء حتى يتمكن النموذج من شرح المشكلات أو تجربة بدائل بدلاً من تعطل التطبيق بالكامل. عندما تُلقي أداة استثناء، يلتقطه LangChain4j ويُرسل رسالة الخطأ إلى النموذج، الذي يشرح المشكلة بعد ذلك بلغة طبيعية. ## الأدوات المتاحة -يُظهر الرسم البياني أدناه النظام البيئي الواسع للأدوات التي يمكنك بناؤها. توضح هذه الوحدة أدوات الطقس ودرجة الحرارة، لكن نمط `@Tool` نفسه يعمل لأي طريقة Java — من استعلامات قواعد البيانات إلى معالجة المدفوعات. +يوضح المخطط أدناه النظام البيئي الواسع للأدوات التي يمكنك بناؤها. تستعرض هذه الوحدة أدوات الطقس وحرارة الطقس، لكن نفس نمط `@Tool` يعمل مع أي طريقة جافا — من استعلامات قواعد البيانات إلى معالجة الدفع. -نظام أدوات +النظام البيئي للأدوات -*أي طريقة Java معنونة بـ @Tool تصبح متاحة للذكاء الاصطناعي — النمط يمتد إلى قواعد البيانات، واجهات برمجة التطبيقات، البريد الإلكتروني، عمليات الملفات، وأكثر.* +*أي طريقة جافا معلمة بـ @Tool تصبح متاحة للذكاء الاصطناعي — هذا النمط يمتد إلى قواعد البيانات، الواجهات البرمجية، البريد الإلكتروني، عمليات الملفات، وأكثر.* -## متى تستخدم الوكلاء المعتمدين على الأدوات +## متى تستخدم وكلاء قائمين على الأدوات -ليس كل طلب يحتاج أدوات. القرار يعود إلى ما إذا كان الذكاء الاصطناعي يحتاج للتفاعل مع أنظمة خارجية أو يمكنه الإجابة من معرفته الخاصة. يختصر الدليل التالي متى تضيف الأدوات قيمة ومتى تكون غير ضرورية: +ليست كل الطلبات تحتاج أدوات. ينبثق القرار من ما إذا كان الذكاء الاصطناعي يحتاج التفاعل مع أنظمة خارجية أو يمكنه الإجابة من معرفته الخاصة. يلخص الدليل التالي متى تضيف الأدوات قيمة ومتى تكون غير ضرورية: متى تستخدم الأدوات *دليل قرار سريع — الأدوات للبيانات الحية، الحسابات، والإجراءات؛ المعرفة العامة والمهام الإبداعية لا تحتاجها.* -## الأدوات مقابل RAG +## الأدوات مقابل نظام الاسترجاع والاستدلال (RAG) -توسع الوحدتان 03 و 04 ما يمكن للذكاء الاصطناعي القيام به، لكن بطرق مختلفة جذريًا. تمكن RAG النموذج من الوصول إلى **المعرفة** من خلال استرجاع المستندات. تمنح الأدوات النموذج القدرة على اتخاذ **إجراءات** عن طريق استدعاء الوظائف. يقارن الرسم البياني أدناه هذين النهجين جنبًا إلى جنب — من كيف يعمل كل تدفق إلى الموازنات بينهما: +الوحدتان 03 و 04 توسعان قدرات الذكاء الاصطناعي، لكن بطرق مختلفة جوهريًا. يوفر RAG للنموذج الوصول إلى **المعرفة** عن طريق استرجاع المستندات. تمنح الأدوات النموذج القدرة على اتخاذ **إجراءات** عن طريق استدعاء الوظائف. يقارن المخطط التالي الطريقتين جنبًا إلى جنب — من كيفية تشغيل كل سير عمل إلى المقاييس بينهما: -مقارنة بين الأدوات و RAG +مقارنة الأدوات وRAG -*تسترجع RAG المعلومات من مستندات ثابتة — تنفذ الأدوات العمليات وتجلب البيانات الديناميكية والحية. العديد من أنظمة الإنتاج تجمع بينهما.* +*يسترجع RAG المعلومات من مستندات ثابتة — تنفذ الأدوات إجراءات وتجلب بيانات حية وديناميكية. تجمع العديد من أنظمة الإنتاج بينهما.* -في الواقع، تجمع العديد من أنظمة الإنتاج بين كلا النهجين: RAG لتثبيت الأجوبة في توثيقاتك، والأدوات لجلب البيانات الحية أو أداء العمليات. +عمليًا، تجمع العديد من أنظمة الإنتاج بين الطريقتين: RAG لتثبيت الأجوبة على وثائقك، والأدوات لجلب البيانات الحية أو تنفيذ العمليات. ## الخطوات التالية @@ -377,11 +377,11 @@ cd ..; .\stop-all.ps1 # جميع الوحدات --- -**التنقل:** [← السابق: الوحدة 03 - RAG](../03-rag/README.md) | [العودة للرئيسية](../README.md) | [التالي: الوحدة 05 - MCP →](../05-mcp/README.md) +**التنقل:** [← السابق: الوحدة 03 - RAG](../03-rag/README.md) | [عودة إلى الرئيسي](../README.md) | [التالي: الوحدة 05 - MCP →](../05-mcp/README.md) --- -**إخلاء مسؤولية**: -تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى لتحقيق الدقة، يُرجى العلم بأن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية هو المصدر المرجعي والمعتمد. بالنسبة للمعلومات الحرجة، يُنصح بالترجمة الاحترافية البشرية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة. +**تنويه**: +تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة. \ No newline at end of file diff --git a/translations/ar/README.md b/translations/ar/README.md index dbf948ab7..1dbb5227f 100644 --- a/translations/ar/README.md +++ b/translations/ar/README.md @@ -2,18 +2,18 @@ # LangChain4j للمبتدئين -دورة لبناء تطبيقات الذكاء الاصطناعي باستخدام LangChain4j و Azure OpenAI GPT-5.2، من المحادثة الأساسية حتى الوكلاء الذكيين. +دورة لبناء تطبيقات الذكاء الاصطناعي باستخدام LangChain4j و Azure OpenAI GPT-5.2، من المحادثات الأساسية إلى وكلاء الذكاء الاصطناعي. ### 🌐 دعم متعدد اللغات #### مدعوم عبر GitHub Action (آلي ودائم التحديث) -[العربية](./README.md) | [البنغالية](../bn/README.md) | [البلغارية](../bg/README.md) | [البورمية (ميانمار)](../my/README.md) | [الصينية (المبسطة)](../zh-CN/README.md) | [الصينية (التقليدية، هونغ كونغ)](../zh-HK/README.md) | [الصينية (التقليدية، ماكاو)](../zh-MO/README.md) | [الصينية (التقليدية، تايوان)](../zh-TW/README.md) | [الكرواتية](../hr/README.md) | [التشيكية](../cs/README.md) | [الدانماركية](../da/README.md) | [الهولندية](../nl/README.md) | [الإستونية](../et/README.md) | [الفنلندية](../fi/README.md) | [الفرنسية](../fr/README.md) | [الألمانية](../de/README.md) | [اليونانية](../el/README.md) | [العبرية](../he/README.md) | [الهندية](../hi/README.md) | [الهنغارية](../hu/README.md) | [الإندونيسية](../id/README.md) | [الإيطالية](../it/README.md) | [اليابانية](../ja/README.md) | [الكانادا](../kn/README.md) | [الخميرية](../km/README.md) | [الكورية](../ko/README.md) | [الليتوانية](../lt/README.md) | [الماليزية](../ms/README.md) | [المالايالامية](../ml/README.md) | [الماراثي](../mr/README.md) | [النيبالية](../ne/README.md) | [البيجنيه النيجيرية](../pcm/README.md) | [النرويجية](../no/README.md) | [الفارسية (اللغة الفارسية)](../fa/README.md) | [البولندية](../pl/README.md) | [البرتغالية (البرازيل)](../pt-BR/README.md) | [البرتغالية (البرتغال)](../pt-PT/README.md) | [البنجابية (جرمخي)](../pa/README.md) | [الرومانية](../ro/README.md) | [الروسية](../ru/README.md) | [الصربية (السيريلية)](../sr/README.md) | [السلوفاكية](../sk/README.md) | [السلوفينية](../sl/README.md) | [الإسبانية](../es/README.md) | [السواحيلية](../sw/README.md) | [السويدية](../sv/README.md) | [التاغالوغية (الفلبينية)](../tl/README.md) | [التاميل](../ta/README.md) | [التيلجو](../te/README.md) | [التايلاندية](../th/README.md) | [التركية](../tr/README.md) | [الأوكرانية](../uk/README.md) | [الأردية](../ur/README.md) | [الفيتنامية](../vi/README.md) +[Arabic](./README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **هل تفضل النسخ محليًا؟** +> **تفضل النسخ محلياً؟** > -> يتضمن هذا المستودع أكثر من 50 ترجمة للغات تزيد بشكل كبير من حجم التنزيل. للنسخ بدون الترجمات، استخدم السحب الانتقائي: +> يحتوي هذا المستودع على أكثر من 50 ترجمة للغات مختلفة مما يزيد بشكل كبير من حجم التنزيل. للنسخ بدون الترجمات، استخدم sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -22,71 +22,68 @@ > git sparse-checkout set --no-cone '/*' '!translations' '!translated_images' > ``` > -> **CMD (ويندوز):** +> **CMD (Windows):** > ```cmd > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> هذا يوفر لك كل ما تحتاجه لإكمال الدورة مع تنزيل أسرع بكثير. +> هذا يمنحك كل ما تحتاجه لإكمال الدورة مع تنزيل أسرع بكثير. ## جدول المحتويات -1. [البدء السريع](00-quick-start/README.md) - ابدأ مع LangChain4j -2. [مقدمة](01-introduction/README.md) - تعلم أساسيات LangChain4j -3. [هندسة الموجهات](02-prompt-engineering/README.md) - إتقان تصميم الموجهات الفعالة -4. [RAG (التوليد المعزز بالاسترجاع)](03-rag/README.md) - بناء أنظمة ذكية مبنية على المعرفة -5. [الأدوات](04-tools/README.md) - دمج الأدوات الخارجية والمساعدين البسيطين -6. [MCP (بروتوكول سياق النموذج)](05-mcp/README.md) - العمل مع بروتوكول سياق النموذج (MCP) والوحدات الوكلائية +1. [مقدمة](01-introduction/README.md) - تعلّم أساسيات LangChain4j +2. [هندسة المُحفزات](02-prompt-engineering/README.md) - اتقن تصميم المُحفزات الفعّالة +3. [RAG (التوليد المدعوم بالاسترجاع)](03-rag/README.md) - بناء أنظمة معرفية ذكية +4. [الأدوات](04-tools/README.md) - دمج الأدوات الخارجية والمساعدين البسيطين +5. [MCP (بروتوكول سياق النموذج)](05-mcp/README.md) - العمل مع بروتوكول سياق النموذج (MCP) والوحدات الوكيلّة -### جولات الفيديو التوضيحية +### جولات فيديو إرشادية -لكل وحدة جلسة مباشرة مصاحبة حيث نشرح المفاهيم والكود خطوة بخطوة. +كل وحدة تحتوي على جلسة مباشرة مصاحبة نمر خلالها على المفاهيم والكود خطوة بخطوة. | الوحدة | الفيديو | |--------|-------| -| 01 - مقدمة | [البداية مع LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - هندسة الموجهات | [هندسة الموجهات مع LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - المقدمة | [البدء مع LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - هندسة المحفزات | [هندسة المُحفز مع LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG مع LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - الأدوات & 05 - MCP | [وكلاء الذكاء الاصطناعي مع الأدوات وMCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - أدوات و 05 - MCP | [وكلاء الذكاء الاصطناعي مع الأدوات و MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## مسار التعلم -**جديد في LangChain4j؟** اطلع على [مسرد المصطلحات](docs/GLOSSARY.md) لتعريفات المصطلحات والمفاهيم الأساسية. +**جديد على LangChain4j؟** اطلع على [مسرد المصطلحات](docs/GLOSSARY.md) لتعريفات المصطلحات والمفاهيم الرئيسية. -> **البدء السريع** +> **بدء سريع** -1. قم بتفرع هذا المستودع إلى حسابك على GitHub -2. اضغط على **الكود** → تبويب **مساحات الشيفرة** → **...** → **جديد مع خيارات...** -3. استخدم الإعدادات الافتراضية – سيختار هذا حاوية التطوير التي تم إنشاؤها لهذه الدورة -4. اضغط **إنشاء مساحة الشيفرة** -5. انتظر من 5 إلى 10 دقائق حتى يصبح البيئة جاهزة -6. انتقل مباشرة إلى [البدء السريع](./00-quick-start/README.md) للبدء! +1. قم بتفريع هذا المستودع إلى حسابك في GitHub +2. اضغط على **Code** → تبويب **Codespaces** → **...** → **جديد مع خيارات...** +3. استخدم الإعدادات الافتراضية – سيختار هذا حاوية التطوير المُنشأة لهذه الدورة +4. اضغط **إنشاء مساحة تعليمات برمجية** +5. انتظر 5-10 دقائق حتى يكون البيئة جاهزة +6. ابدأ مباشرة من [المقدمة](./01-introduction/README.md) للبدء! -بعد إكمال الوحدات، استكشف [دليل الاختبار](docs/TESTING.md) لمشاهدة مفاهيم اختبارات LangChain4j قيد العمل. +بعد إكمال الوحدات، استكشف [دليل الاختبار](docs/TESTING.md) لرؤية مفاهيم اختبار LangChain4j في التطبيق. -> **ملاحظة:** يستخدم هذا التدريب نماذج GitHub ونماذج Azure OpenAI. يستخدم وحدة [البدء السريع](00-quick-start/README.md) نماذج GitHub (لا تحتاج إلى اشتراك Azure)، بينما تستخدم الوحدات 1-5 Azure OpenAI. ابدأ باستخدام [حساب Azure مجاني](https://aka.ms/azure-free-account) إذا لم يكن لديك واحد. +> **ملاحظة:** يستخدم هذا التدريب Azure OpenAI. ابدأ باستخدام [حساب Azure مجاني](https://aka.ms/azure-free-account) إذا لم يكن لديك واحد. +## التعلم باستخدام GitHub Copilot -## التعلم مع GitHub Copilot +للبدء السريع في الترميز، افتح هذا المشروع في GitHub Codespace أو بيئة التطوير المتكاملة المحلية مع devcontainer المقدم. تأتي حاوية التطوير المستخدمة في هذه الدورة مُهيأة مسبقاً مع GitHub Copilot لبرمجة ذكاء اصطناعي مترافق. -للبدء السريع في الكتابة، افتح هذا المشروع في مساحة شيفرة على GitHub أو في بيئة التطوير المحلية لديك مع devcontainer المقدم. تأتي الحاوية المطورة المستخدمة في هذه الدورة معدة مسبقًا مع GitHub Copilot للبرمجة المزدوجة بالذكاء الاصطناعي. +يشمل كل مثال برمجي أسئلة مقترحة يمكنك طرحها على GitHub Copilot لتعميق فهمك. ابحث عن رموز 💡/🤖 في: -كل مثال كود يتضمن أسئلة مقترحة يمكنك طرحها على GitHub Copilot لتعميق فهمك. ابحث عن رموز 💡/🤖 في: +- **رؤوس ملفات Java** - أسئلة خاصة بكل مثال +- **قراءات الوحدات** - محفزات استكشافية بعد أمثلة الكود -- **رؤوس ملفات جافا** - أسئلة محددة لكل مثال -- **ملفات README للوحدات** - تلميحات استكشافية بعد أمثلة الكود +**كيفية الاستخدام:** افتح أي ملف كود واطرح على Copilot الأسئلة المقترحة. لديه سياق كامل لقاعدة الكود ويمكنه الشرح والتمديد واقتراح بدائل. -**كيفية الاستخدام:** افتح أي ملف كود واطرح على Copilot الأسئلة المقترحة. لديه السياق الكامل لقاعدة الشيفرة ويمكنه الشرح، التوسيع، واقتراح البدائل. +هل تريد معرفة المزيد؟ اطلع على [Copilot للبرمجة التشاركية بالذكاء الاصطناعي](https://aka.ms/GitHubCopilotAI). -هل تريد معرفة المزيد؟ اطلع على [Copilot للبرمجة المزدوجة بالذكاء الاصطناعي](https://aka.ms/GitHubCopilotAI). - - -## موارد إضافية +## مصادر إضافية ### LangChain @@ -106,45 +103,45 @@ ### سلسلة الذكاء الاصطناعي التوليدي [![الذكاء الاصطناعي التوليدي للمبتدئين](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![الذكاء الاصطناعي التوليدي (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![الذكاء الاصطناعي التوليدي (جافا)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![الذكاء الاصطناعي التوليدي (جافا سكريبت)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +[![الذكاء الاصطناعي التوليدي (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![الذكاء الاصطناعي التوليدي (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### التعليم الأساسي +### التعلم الأساسي [![تعلم الآلة للمبتدئين](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![علوم البيانات للمبتدئين](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![الذكاء الاصطناعي للمبتدئين](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![الأمن السيبراني للمبتدئين](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) [![تطوير الويب للمبتدئين](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![إنترنت الأشياء للمبتدئين](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![تطوير XR للمبتدئين](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![تطوير الواقع الممتد للمبتدئين](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### سلسلة Copilot -[![Copilot للبرمجة التعاونية بالذكاء الاصطناعي](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot لـ C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![مغامرة Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +### سلسلة كوبيلوت +[![كوبيلوت من أجل البرمجة الزوجية بالذكاء الاصطناعي](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![كوبيلوت من أجل C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![مغامرة كوبيلوت](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## الحصول على المساعدة -إذا واجهت صعوبة أو كان لديك أي أسئلة حول بناء تطبيقات الذكاء الاصطناعي، انضم إلى: +إذا واجهت مشكلة أو كان لديك أي أسئلة حول بناء تطبيقات الذكاء الاصطناعي، انضم إلى: -[![مجتمع Microsoft Foundry في ديسكورد](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) +[![ديسكورد Microsoft Foundry](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -إذا كان لديك ملاحظات على المنتج أو أخطاء أثناء البناء، قم بزيارة: +إذا كان لديك ملاحظات على المنتج أو أخطاء أثناء البناء قم بزيارة: -[![منتدى مطوري Microsoft Foundry على GitHub](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) +[![منتدى مطوري Microsoft Foundry](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## الترخيص -ترخيص MIT - انظر ملف [LICENSE](../../LICENSE) للتفاصيل. +رخصة MIT - راجع ملف [LICENSE](../../LICENSE) للتفاصيل. --- -**تنويه**: -تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم بأن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر المعتمد. بالنسبة للمعلومات الحساسة، يُنصح بالترجمة المهنية البشرية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة. +**تنويه**: +تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة. \ No newline at end of file diff --git a/translations/ar/docs/GLOSSARY.md b/translations/ar/docs/GLOSSARY.md index ef7a7b04a..9cd3a3302 100644 --- a/translations/ar/docs/GLOSSARY.md +++ b/translations/ar/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## جدول المحتويات -- [المفاهيم الأساسية](../../../docs) -- [مكونات LangChain4j](../../../docs) -- [مفاهيم الذكاء الاصطناعي/التعلم الآلي](../../../docs) -- [خطوط الحماية](../../../docs) -- [هندسة المحفزات](../../../docs) -- [RAG (التوليد المدعوم بالاسترجاع)](../../../docs) -- [الوكلاء والأدوات](../../../docs) -- [الوحدة الوكيلة](../../../docs) -- [بروتوكول سياق النموذج (MCP)](../../../docs) -- [خدمات Azure](../../../docs) -- [الاختبار والتطوير](../../../docs) +- [المفاهيم الأساسية](#core-concepts) +- [مكونات LangChain4j](#langchain4j-components) +- [مفاهيم الذكاء الاصطناعي / التعلم الآلي](#aiml-concepts) +- [ضوابط الأمان](#guardrails) +- [هندسة المطالبات](#prompt-engineering---module-02) +- [RAG (التوليد المعزز بالاستخراج)](#rag-retrieval-augmented-generation---module-03) +- [العملاء والأدوات](#agents-and-tools---module-04) +- [الوحدة العميائية](#agentic-module---module-05) +- [بروتوكول سياق النموذج (MCP)](#model-context-protocol-mcp---module-05) +- [خدمات Azure](#azure-services---module-01) +- [الاختبار والتطوير](#testing-and-development---testing-guide) -مرجع سريع للمصطلحات والمفاهيم المستخدمة في جميع أنحاء الدورة. +مرجع سريع للمصطلحات والمفاهيم المستخدمة عبر الدورة. -## المفاهيم الأساسية +## Core Concepts -**الوكيل الذكي (AI Agent)** - نظام يستخدم الذكاء الاصطناعي للتفكير والتصرف بشكل مستقل. [الوحدة 04](../04-tools/README.md) +**وكيل الذكاء الاصطناعي** - نظام يستخدم الذكاء الاصطناعي للتفكير والتصرف بشكل مستقل. [الوحدة 04](../04-tools/README.md) -**السلسلة (Chain)** - تسلسل من العمليات حيث تغذي المخرجات الخطوة التالية. +**سلسلة** - تسلسل من العمليات حيث يُدخَل الناتج في الخطوة التالية. -**التجزئة (Chunking)** - تقسيم الوثائق إلى قطع أصغر. النموذجي: 300-500 رمز مع تداخل. [الوحدة 03](../03-rag/README.md) +**التقسيم** - تقسيم المستندات إلى قطع أصغر. النموذجي: 300-500 رمز مع تداخل. [الوحدة 03](../03-rag/README.md) -**نافذة السياق (Context Window)** - الحد الأقصى لعدد الرموز التي يمكن للنموذج معالجتها. GPT-5.2: 400 ألف رمز (حتى 272 ألف إدخال، 128 ألف إخراج). +**نافذة السياق** - الحد الأقصى لعدد الرموز التي يمكن للنموذج معالجتها. GPT-5.2: 400 ألف رمز (حتى 272 ألف إدخال، 128 ألف إخراج). -**التضمينات (Embeddings)** - متجهات عددية تمثل معنى النص. [الوحدة 03](../03-rag/README.md) +**التضمينات** - متجهات عددية تمثل معنى النص. [الوحدة 03](../03-rag/README.md) -**استدعاء الوظائف (Function Calling)** - النموذج ينشئ طلبات منظمة لاستدعاء وظائف خارجية. [الوحدة 04](../04-tools/README.md) +**استدعاء الوظائف** - النموذج يُنشئ طلبات مُنظمة لاستدعاء وظائف خارجية. [الوحدة 04](../04-tools/README.md) -**الهلاوس (Hallucination)** - عندما تولد النماذج معلومات غير صحيحة ولكنها تبدو منطقية. +**الهلاوس** - عندما تولّد النماذج معلومات غير صحيحة لكنها تبدو معقولة. -**المحفز (Prompt)** - مدخل نصي لنموذج اللغة. [الوحدة 02](../02-prompt-engineering/README.md) +**المطالبة** - نص الإدخال إلى نموذج اللغة. [الوحدة 02](../02-prompt-engineering/README.md) -**البحث الدلالي (Semantic Search)** - بحث بالمعنى باستخدام التضمينات، وليس الكلمات المفتاحية. [الوحدة 03](../03-rag/README.md) +**البحث الدلالي** - البحث بواسطة المعنى باستخدام التضمينات، وليس الكلمات المفتاحية. [الوحدة 03](../03-rag/README.md) -**الحالة الدائمة مقابل الحالة غير الدائمة (Stateful vs Stateless)** - غير دائم: بدون ذاكرة. دائم: يحتفظ بسجل المحادثة. [الوحدة 01](../01-introduction/README.md) +**الدولة مقابل حالة عدم وجود حالة** - بدون حالة: لا ذاكرة. مع حالة: يحتفظ بتاريخ المحادثة. [الوحدة 01](../01-introduction/README.md) -**الرموز (Tokens)** - الوحدات النصية الأساسية التي تعالجها النماذج. تؤثر على التكلفة والقيود. [الوحدة 01](../01-introduction/README.md) +**الرموز** - وحدات النص الأساسية التي تعالجها النماذج. تؤثر على التكاليف والحدود. [الوحدة 01](../01-introduction/README.md) -**تسلسل الأدوات (Tool Chaining)** - تنفيذ الأدوات بشكل متسلسل حيث توجه المخرجات الاستدعاء التالي. [الوحدة 04](../04-tools/README.md) +**تسلسل الأدوات** - تنفيذ متسلسل للأدوات حيث يُخبر الناتج الاستدعاء التالي. [الوحدة 04](../04-tools/README.md) -## مكونات LangChain4j +## LangChain4j Components -**AiServices** - ينشئ واجهات خدمات ذكاء اصطناعي آمنة النوع. +**AiServices** - ينشئ واجهات خدمات الذكاء الاصطناعي الآمنة من حيث النوع. -**OpenAiOfficialChatModel** - عميل موحد لنماذج OpenAI وAzure OpenAI. +**OpenAiOfficialChatModel** - عميل موحد لنماذج OpenAI و Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - ينشئ التضمينات باستخدام عميل OpenAI الرسمي (يدعم كل من OpenAI وAzure OpenAI). +**OpenAiOfficialEmbeddingModel** - ينشئ التضمينات باستخدام عميل OpenAI الرسمي (يدعم كل من OpenAI و Azure OpenAI). **ChatModel** - الواجهة الأساسية لنماذج اللغة. -**ChatMemory** - يحتفظ بسجل المحادثة. +**ChatMemory** - يحتفظ بتاريخ المحادثة. -**ContentRetriever** - يعثر على قطع الوثائق ذات الصلة لـ RAG. +**ContentRetriever** - يعثر على قطع المستندات ذات الصلة لـ RAG. -**DocumentSplitter** - يقسم الوثائق إلى أجزاء. +**DocumentSplitter** - يقسم المستندات إلى قطع. **EmbeddingModel** - يحول النص إلى متجهات عددية. **EmbeddingStore** - يخزن ويسترجع التضمينات. -**MessageWindowChatMemory** - يحافظ على نافذة منزلقة للرسائل الحديثة. +**MessageWindowChatMemory** - يحتفظ بنافذة منزلقة من الرسائل الحديثة. -**PromptTemplate** - ينشئ محفزات قابلة لإعادة الاستخدام مع نُصوص `{{variable}}` المتغيرة. +**PromptTemplate** - ينشئ مطالبات قابلة لإعادة الاستخدام مع متغيرات `{{variable}}`. -**TextSegment** - قطعة نص مع بيانات وصفية. يستخدم في RAG. +**TextSegment** - قطعة نص مع بيانات وصفية. تُستخدم في RAG. **ToolExecutionRequest** - يمثل طلب تنفيذ أداة. **UserMessage / AiMessage / SystemMessage** - أنواع رسائل المحادثة. -## مفاهيم الذكاء الاصطناعي/التعلم الآلي +## AI/ML Concepts -**التعلم بالقليل من الأمثلة (Few-Shot Learning)** - تقديم أمثلة في المحفزات. [الوحدة 02](../02-prompt-engineering/README.md) +**التعلم بالقليل من الأمثلة** - توفير أمثلة في المطالبات. [الوحدة 02](../02-prompt-engineering/README.md) -**نموذج اللغة الكبير (LLM)** - نماذج ذكاء اصطناعي مدربة على كميات ضخمة من النصوص. +**النموذج اللغوي الكبير (LLM)** - نماذج الذكاء الاصطناعي المدربة على كميات كبيرة من النصوص. -**جهد الاستدلال (Reasoning Effort)** - معلمة GPT-5.2 التي تتحكم في عمق التفكير. [الوحدة 02](../02-prompt-engineering/README.md) +**جهد الاستدلال** - معامل GPT-5.2 يتحكم في عمق التفكير. [الوحدة 02](../02-prompt-engineering/README.md) -**درجة الحرارة (Temperature)** - تتحكم في عشوائية المخرجات. منخفض = محدد، مرتفع = إبداعي. +**درجة الحرارة** - تتحكم في عشوائية الإخراج. منخفض = حتمي، مرتفع = إبداعي. -**قاعدة بيانات المتجهات (Vector Database)** - قاعدة بيانات متخصصة للتضمينات. [الوحدة 03](../03-rag/README.md) +**قاعدة بيانات المتجهات** - قاعدة بيانات متخصصة للتضمينات. [الوحدة 03](../03-rag/README.md) -**التعلم بدون أمثلة (Zero-Shot Learning)** - تنفيذ المهام بدون أمثلة. [الوحدة 02](../02-prompt-engineering/README.md) +**التعلم بدون أمثلة** - أداء المهام بدون أمثلة. [الوحدة 02](../02-prompt-engineering/README.md) -## خطوط الحماية - [الوحدة 00](../00-quick-start/README.md) +## Guardrails -**الدفاع العميق (Defense in Depth)** - نهج أمني متعدد الطبقات يجمع بين خطوط حماية على مستوى التطبيق ومرشحات أمان المزود. +**الدفاع على عدة طبقات** - نهج أمني متعدد المستويات يجمع ضوابط الأمان على مستوى التطبيق مع مرشحات أمان المزود. -**حظر صلب (Hard Block)** - المزود يرمي خطأ HTTP 400 لانتهاكات المحتوى الشديدة. +**الكتلة الصلبة** - المزود يرمي خطأ HTTP 400 للمخالفات الشديدة للمحتوى. -**InputGuardrail** - واجهة LangChain4j للتحقق من صحة مدخلات المستخدم قبل وصولها للنموذج. يوفر التكلفة والوقت بحظر المحفزات الضارة مبكراً. +**InputGuardrail** - واجهة LangChain4j للتحقق من صحة مدخلات المستخدم قبل وصولها إلى LLM. يوفر التكلفة والوقت بحجب المطالبات الضارة مبكرًا. -**InputGuardrailResult** - نوع العائد للتحقق من الحماية: `success()` أو `fatal("reason")`. +**InputGuardrailResult** - نوع العودة للتحقق من الضوابط: `success()` أو `fatal("السبب")`. **OutputGuardrail** - واجهة للتحقق من صحة استجابات الذكاء الاصطناعي قبل إرجاعها للمستخدمين. -**مرشحات أمان المزود (Provider Safety Filters)** - مرشحات محتوى مدمجة من مزودي الذكاء الاصطناعي (مثل نماذج GitHub) تكتشف الانتهاكات على مستوى API. +**مرشحات أمان المزود** - مرشحات محتوى مدمجة من مزودي الذكاء الاصطناعي (مثل Azure OpenAI) تكتشف الانتهاكات على مستوى API. -**الرفض اللين (Soft Refusal)** - النموذج يرفض الإجابة بأدب دون رمي خطأ. +**الرفض اللين** - النموذج يرفض بالأدب الإجابة دون إلقاء خطأ. -## هندسة المحفزات - [الوحدة 02](../02-prompt-engineering/README.md) +## Prompt Engineering - [الوحدة 02](../02-prompt-engineering/README.md) -**سلسلة التفكير (Chain-of-Thought)** - التفكير خطوة بخطوة لتحقيق دقة أفضل. +**سلسلة التفكير** - الاستدلال خطوة بخطوة لتحسين الدقة. -**الإخراج المقيد (Constrained Output)** - فرض تنسيق أو هيكل معين. +**الإخراج المقيد** - فرض تنسيق أو هيكل معين. -**الحماس العالي (High Eagerness)** - نمط GPT-5.2 للتفكير التفصيلي. +**الحماس العالي** - نمط GPT-5.2 للتفكير المتعمق. -**الحماس المنخفض (Low Eagerness)** - نمط GPT-5.2 للإجابات السريعة. +**الحماس المنخفض** - نمط GPT-5.2 للإجابات السريعة. -**المحادثة متعددة الأدوار (Multi-Turn Conversation)** - الحفاظ على السياق عبر التبادلات. +**المحادثة متعددة الأدوار** - الحفاظ على السياق عبر التبادلات. -**المحفز المعتمد على الدور (Role-Based Prompting)** - تحديد شخصية النموذج عبر رسائل النظام. +**المطالبة حسب الدور** - تعيين شخصية النموذج عبر رسائل النظام. -**التأمل الذاتي (Self-Reflection)** - النموذج يقيم ويحسن مخرجاته. +**التأمل الذاتي** - النموذج يقيّم ويُحسن مخرجاته. -**التحليل المنظم (Structured Analysis)** - إطار تقييم ثابت. +**التحليل المنظم** - إطار تقييم ثابت. -**نمط تنفيذ المهمة (Task Execution Pattern)** - تخطيط → تنفيذ → تلخيص. +**نمط تنفيذ المهمة** - التخطيط → التنفيذ → التلخيص. -## RAG (التوليد المدعوم بالاسترجاع) - [الوحدة 03](../03-rag/README.md) +## RAG (Retrieval-Augmented Generation) - [الوحدة 03](../03-rag/README.md) -**خط أنابيب معالجة الوثائق (Document Processing Pipeline)** - تحميل → تجزئة → تضمين → تخزين. +**خط أنابيب معالجة المستندات** - تحميل → تقسيم → تضمين → تخزين. -**مخزن التضمينات في الذاكرة (In-Memory Embedding Store)** - تخزين غير دائم للاختبارات. +**مخزن التضمينات في الذاكرة** - تخزين غير دائم للاختبار. -**RAG** - يجمع بين الاسترجاع والتوليد لتدعيم الإجابات. +**RAG** - يجمع بين الاستخراج والتوليد لتأسيس الاستجابات. -**درجة التشابه (Similarity Score)** - مقياس (0-1) للتشابه الدلالي. +**درجة التشابه** - مقياس (0-1) للتشابه الدلالي. -**مرجع المصدر (Source Reference)** - بيانات وصفية عن المحتوى المسترجع. +**مرجع المصدر** - بيانات وصفية عن المحتوى المسترجع. -## الوكلاء والأدوات - [الوحدة 04](../04-tools/README.md) +## Agents and Tools - [الوحدة 04](../04-tools/README.md) -**@Tool Annotation** - يحدد طرق جافا كأدوات قابلة للاستدعاء عبر الذكاء الاصطناعي. +**@Tool Annotation** - يعلّم طرق جافا كأدوات يمكن للذكاء الاصطناعي استدعاؤها. -**نمط ReAct** - استدلال → تصرف → مراقبة → تكرار. +**نمط ReAct** - التفكير → الفعل → الملاحظة → التكرار. -**إدارة الجلسة (Session Management)** - سياقات منفصلة لمستخدمين مختلفين. +**إدارة الجلسة** - سياقات منفصلة لمستخدمين مختلفين. -**الأداة (Tool)** - وظيفة يمكن لوكيل الذكاء الاصطناعي استدعاؤها. +**الأداة** - وظيفة يمكن لوكيل الذكاء الاصطناعي استدعاؤها. -**وصف الأداة (Tool Description)** - توثيق هدف الأداة ومعاملاتها. +**وصف الأداة** - توثيق غرض الأداة ومعلماتها. -## الوحدة الوكيلة - [الوحدة 05](../05-mcp/README.md) +## Agentic Module - [الوحدة 05](../05-mcp/README.md) -**@Agent Annotation** - يحدد الواجهات كوكلاء ذكاء اصطناعي مع تعريف سلوك تصريحي. +**@Agent Annotation** - يعلّم الواجهات كوكلاء ذكاء اصطناعي مع تعريف سلوكي إعلاني. -**المستمع الوكلي (Agent Listener)** - نقطة متابعة تنفيذ الوكيل عبر `beforeAgentInvocation()` و`afterAgentInvocation()`. +**مراقب الوكيل** - تعليقة لمراقبة تنفيذ الوكيل عبر `beforeAgentInvocation()` و `afterAgentInvocation()`. -**نطاق وكالي (Agentic Scope)** - ذاكرة مشتركة تخزن بها الوكلاء المخرجات باستخدام `outputKey` لكي يستهلكها الوكلاء اللاحقون. +**نطاق الوكيل** - ذاكرة مشتركة يخزن فيها الوكلاء المخرجات باستخدام `outputKey` ليستهلكها الوكلاء التابعون. -**AgenticServices** - مصنع لإنشاء وكلاء باستخدام `agentBuilder()` و`supervisorBuilder()`. +**AgenticServices** - مصنع لإنشاء الوكلاء باستخدام `agentBuilder()` و `supervisorBuilder()`. -**تدفق العمل الشرطي (Conditional Workflow)** - التوجيه حسب الشروط لوكلاء متخصصين مختلفين. +**سير العمل الشرطي** - التوجيه بناءً على الشروط إلى وكلاء متخصصين مختلفين. -**الإنسان في الحلقة (Human-in-the-Loop)** - نمط تدفق عمل يضيف نقاط فحص بشرية للموافقة أو مراجعة المحتوى. +**البشر في الحلقة** - نمط سير عمل يضيف نقاط تحقق بشرية للموافقة أو مراجعة المحتوى. -**langchain4j-agentic** - تبعية Maven لبناء وكلاء تصريحيين (تجريبي). +**langchain4j-agentic** - تبعية Maven لبناء الوكلاء بالأسلوب الإعلاني (تجريبي). -**تدفق العمل التكراري (Loop Workflow)** - تكرار تنفيذ الوكيل حتى يتحقق شرط (مثلاً درجة جودة ≥ 0.8). +**سير عمل الحلقة** - تكرار تنفيذ الوكيل حتى تتحقق شرط (مثل درجة الجودة ≥ 0.8). -**outputKey** - معلمة توضيحية للوكيل تحدد مكان تخزين النتائج في النطاق الوكالي. +**outputKey** - معامل تعليمة الوكيل يحدد مكان تخزين النتائج في نطاق الوكيل. -**تدفق العمل الموازي (Parallel Workflow)** - تشغيل وكلاء متعددين في الوقت نفسه لمهام مستقلة. +**سير عمل متوازٍ** - تشغيل عدة وكلاء في الوقت ذاته لمهام مستقلة. -**استراتيجية الاستجابة (Response Strategy)** - كيف يشكل المشرف الإجابة النهائية: آخر، ملخص، أو مصنف. +**استراتيجية الاستجابة** - كيف يكوّن المشرف الإجابة النهائية: الأخير، الملخص، أو المُقيّم. -**تدفق العمل التسلسلي (Sequential Workflow)** - تنفيذ الوكلاء بالترتيب حيث تنتقل المخرجات للخطوة التالية. +**سير عمل تسلسلي** - تنفيذ الوكلاء بالتسلسل حيث يتدفق الناتج إلى الخطوة التالية. -**نمط المشرف الوكلي (Supervisor Agent Pattern)** - نمط وكالي متقدم حيث يقرر مشرف LLM ديناميكياً الوكلاء الفرعيين الذين سيتم استدعاؤهم. +**نمط وكيل المشرف** - نمط عميائي متقدم حيث يقرر مشرف LLM بشكل ديناميكي الوكلاء الفرعيين الذين يتم استدعاؤهم. -## بروتوكول سياق النموذج (MCP) - [الوحدة 05](../05-mcp/README.md) +## Model Context Protocol (MCP) - [الوحدة 05](../05-mcp/README.md) -**langchain4j-mcp** - تبعية Maven للتكامل مع MCP في LangChain4j. +**langchain4j-mcp** - تبعية Maven لتكامل MCP في LangChain4j. -**MCP** - بروتوكول سياق النموذج: معيار لربط تطبيقات الذكاء الاصطناعي بالأدوات الخارجية. بنِ مرّة، استخدم في كل مكان. +**MCP** - بروتوكول سياق النموذج: معيار لربط تطبيقات الذكاء الاصطناعي بالأدوات الخارجية. ابْنِ مرة واحدة، استخدم في كل مكان. -**عميل MCP (MCP Client)** - تطبيق يتصل بخوادم MCP لاكتشاف واستخدام الأدوات. +**عميل MCP** - تطبيق يتصل بخوادم MCP لاكتشاف الأدوات واستخدامها. -**خادم MCP (MCP Server)** - خدمة تعرض الأدوات عبر MCP مع أوصاف واضحة ومخططات المعاملات. +**خادم MCP** - خدمة تعرض الأدوات عبر MCP مع أوصاف واضحة ومخططات المعلمات. -**McpToolProvider** - مكون LangChain4j يغلف أدوات MCP للاستخدام في خدمات الذكاء الاصطناعي والوكلاء. +**McpToolProvider** - مكون LangChain4j يغلّف أدوات MCP للاستخدام في خدمات الذكاء الاصطناعي والوكلاء. -**McpTransport** - واجهة للاتصال بـ MCP. التنفيذا تشمل Stdio وHTTP. +**McpTransport** - واجهة للتواصل عبر MCP. من تطبيقاتها Stdio و HTTP. -**نقل Stdio (Stdio Transport)** - نقل عملية محلية عبر stdin/stdout. مفيد للوصول إلى نظام الملفات أو أدوات سطر الأوامر. +**نقل Stdio** - نقل عملية محلية عبر stdin/stdout. مفيد للوصول إلى نظام الملفات أو أدوات سطر الأوامر. -**StdioMcpTransport** - تنفيذ LangChain4j لإنشاء خادم MCP كناتج فرعي. +**StdioMcpTransport** - تنفيذ LangChain4j يشغل خادم MCP كعملية فرعية. -**اكتشاف الأدوات (Tool Discovery)** - العميل يستعلم الخادم عن الأدوات المتاحة مع الأوصاف والمخططات. +**اكتشاف الأدوات** - العميل يستعلم الخادم عن الأدوات المتاحة مع الأوصاف والمخططات. -## خدمات Azure - [الوحدة 01](../01-introduction/README.md) +## Azure Services - [الوحدة 01](../01-introduction/README.md) -**بحث Azure AI** - بحث سحابي مع قدرات المتجهات. [الوحدة 03](../03-rag/README.md) +**Azure AI Search** - بحث سحابي مع قدرات المتجهات. [الوحدة 03](../03-rag/README.md) -**أداة Azure Developer CLI (azd)** - تنشر موارد Azure. +**أداة تطوير Azure CLI (azd)** - تنشر موارد Azure. -**Azure OpenAI** - خدمة الذكاء الاصطناعي المؤسسية لمايكروسوفت. +**Azure OpenAI** - خدمة الذكاء الاصطناعي المؤسسية من مايكروسوفت. -**Bicep** - لغة البنية التحتية ككود لـ Azure. [دليل البنية التحتية](../01-introduction/infra/README.md) +**Bicep** - لغة البنية التحتية كرمز لـ Azure. [دليل البنية التحتية](../01-introduction/infra/README.md) **اسم النشر** - اسم لنشر النموذج في Azure. **GPT-5.2** - أحدث نموذج OpenAI مع تحكم في الاستدلال. [الوحدة 02](../02-prompt-engineering/README.md) -## الاختبار والتطوير - [دليل الاختبار](TESTING.md) +## Testing and Development - [دليل الاختبار](TESTING.md) -**Dev Container** - بيئة تطوير معزولة بالحاويات. [التكوين](../../../.devcontainer/devcontainer.json) +**حاوية التطوير** - بيئة تطوير محاكاة بالحاويات. [التكوين](../../../.devcontainer/devcontainer.json) -**نماذج GitHub** - ساحة نماذج ذكاء اصطناعي مجانية. [الوحدة 00](../00-quick-start/README.md) +**الاختبار في الذاكرة** - اختبار مع التخزين في الذاكرة. -**الاختبار في الذاكرة** - اختبار باستخدام التخزين في الذاكرة. +**الاختبار المتكامل** - اختبار مع البنية التحتية الحقيقية. -**الاختبار التكاملي** - اختبار باستخدام البنية التحتية الحقيقية. - -**Maven** - أداة أتمتة البناء لجافا. +**Maven** - أداة أتمتة بناء جافا. **Mockito** - إطار عمل لمحاكاة جافا. -**Spring Boot** - إطار عمل تطبيقات جافا. [الوحدة 01](../01-introduction/README.md) +**Spring Boot** - إطار تطبيقات جافا. [الوحدة 01](../01-introduction/README.md) --- -**إخلاء مسؤولية**: -تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). بالرغم من حرصنا على الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار النسخة الأصلية من المستند بلغتها الأصلية المصدر الموثوق. للمعلومات الهامة، يُنصح بالترجمة المهنية البشرية. نحن غير مسؤولين عن أي سوء فهم أو تفسيرات خاطئة ناتجة عن استخدام هذه الترجمة. +**تنويه**: +تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة. \ No newline at end of file diff --git a/translations/ar/docs/TESTING.md b/translations/ar/docs/TESTING.md index 40069fe35..8580ef382 100644 --- a/translations/ar/docs/TESTING.md +++ b/translations/ar/docs/TESTING.md @@ -2,17 +2,17 @@ ## جدول المحتويات -- [بدء سريع](../../../docs) -- [ما تغطيه الاختبارات](../../../docs) -- [تشغيل الاختبارات](../../../docs) -- [تشغيل الاختبارات في VS Code](../../../docs) -- [أنماط الاختبار](../../../docs) -- [فلسفة الاختبار](../../../docs) -- [الخطوات التالية](../../../docs) +- [البدء السريع](#البدء-السريع) +- [ما تغطيه الاختبارات](#ما-تغطيه-الاختبارات) +- [تشغيل الاختبارات](#تشغيل-الاختبارات) +- [تشغيل الاختبارات في VS Code](#تشغيل-الاختبارات-في-vs-code) +- [أنماط الاختبار](#أنماط-الاختبار) +- [فلسفة الاختبار](#فلسفة-الاختبار) +- [الخطوات التالية](#الخطوات-التالية) -توجهك هذه الدليل خلال الاختبارات التي توضح كيفية اختبار تطبيقات الذكاء الاصطناعي دون الحاجة إلى مفاتيح API أو خدمات خارجية. +هذا الدليل يشرح لك الاختبارات التي توضح كيفية اختبار تطبيقات الذكاء الاصطناعي دون الحاجة إلى مفاتيح API أو خدمات خارجية. -## بدء سريع +## البدء السريع شغّل جميع الاختبارات بأمر واحد: @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -عندما تجتاز جميع الاختبارات، ينبغي أن ترى مخرجات مشابهة للصورة أدناه — تم تشغيل الاختبارات بدون أي إخفاقات. +عند نجاح جميع الاختبارات، يجب أن ترى مخرجات تشبه لقطة الشاشة أدناه — الاختبارات تُشغّل بدون أي فشل. -نتائج الاختبار الناجحة +Successful Test Results -*تنفيذ اختبار ناجح يظهر جميع الاختبارات تجتاز بدون أي إخفاقات* +*تنفيذ اختبار ناجح يعرض اجتياز جميع الاختبارات دون أخطاء* ## ما تغطيه الاختبارات -يركز هذا المقرر على **اختبارات الوحدة** التي تُشغل محليًا. كل اختبار يوضح مفهومًا معينًا من LangChain4j بشكل منعزل. هرم الاختبار أدناه يبين مكان اختبارات الوحدة — تشكل الأساس السريع والموثوق الذي يبني عليه باقي استراتيجيتك للاختبار. +يركز هذا المقرر على **اختبارات الوحدة** التي تُشغل محليًا. كل اختبار يعرض مفهومًا محددًا من LangChain4j بشكل معزول. تعرض الهرمية الاختبارية أدناه مكان اختبارات الوحدة — فهي تشكل الأساس السريع والموثوق الذي يبني عليه بقية استراتيجية الاختبار الخاصة بك. -هرم الاختبار +Testing Pyramid -*هرم الاختبار يوضح التوازن بين اختبارات الوحدة (سريعة، معزولة)، اختبارات التكامل (مكونات حقيقية)، واختبارات من النهاية إلى النهاية. هذا التدريب يغطي اختبار الوحدة.* +*هرمية الاختبار توضح التوازن بين اختبارات الوحدة (سريعة، معزولة)، اختبارات التكامل (مكونات حقيقية)، والاختبارات الشاملة. هذا التدريب يغطي اختبار الوحدة.* | الوحدة | الاختبارات | التركيز | الملفات الرئيسية | -|--------|-------|-------|-----------| -| **00 - بدء سريع** | 6 | قوالب المطالبات واستبدال المتغيرات | `SimpleQuickStartTest.java` | -| **01 - مقدمة** | 8 | ذاكرة المحادثة والدردشة القائمة على الحالة | `SimpleConversationTest.java` | -| **02 - هندسة المطالبات** | 12 | أنماط GPT-5.2، مستويات الحماس، المخرجات المهيكلة | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | استيعاب الوثائق، التضمينات، البحث التشابهي | `DocumentServiceTest.java` | -| **04 - الأدوات** | 12 | استدعاء الدوال وربط الأدوات | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | بروتوكول سياق النموذج مع نقل stdio | `SimpleMcpTest.java` | +|--------|------------|---------|------------------| +| **01 - المقدمة** | 8 | ذاكرة المحادثة والدردشة بحالة مستمرة | `SimpleConversationTest.java` | +| **02 - هندسة الموجهات** | 12 | أنماط GPT-5.2، مستويات الحماس، المخرجات المهيكلة | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | إدخال المستندات، التضمين، البحث في التشابه | `DocumentServiceTest.java` | +| **04 - الأدوات** | 12 | استدعاء الدوال وتسلسل الأدوات | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | بروتوكول سياق النموذج باستخدام نقل stdio | `SimpleMcpTest.java` | ## تشغيل الاختبارات -**شغّل جميع الاختبارات من الجذر:** +**شغل جميع الاختبارات من الجذر:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**شغّل اختبارات لوحدة محددة:** +**شغل اختبارات وحدة معينة:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**شغّل فئة اختبار واحدة:** +**شغل فئة اختبار واحدة:** **Bash:** ```bash @@ -91,7 +90,7 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**شغّل طريقة اختبار محددة:** +**شغل طريقة اختبار معينة:** **Bash:** ```bash @@ -100,36 +99,36 @@ mvn test -Dtest=SimpleConversationTest#يجب_الحفاظ_على_تاريخ_ا **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#يجب_الحفاظ_على_سجل_المحادثة +mvn --% test -Dtest=SimpleConversationTest#يجب_الحفاظ_على_تاريخ_المحادثة ``` ## تشغيل الاختبارات في VS Code إذا كنت تستخدم Visual Studio Code، يوفر مستكشف الاختبارات واجهة رسومية لتشغيل وتصحيح الاختبارات. -مستكشف اختبار VS Code +VS Code Test Explorer -*مستكشف اختبار VS Code يعرض شجرة الاختبار مع جميع فئات اختبار جافا وأساليب الاختبار الفردية* +*مستكشف اختبار VS Code يعرض شجرة الاختبارات مع جميع فئات اختبار Java والطرق الفردية* **لتشغيل الاختبارات في VS Code:** -1. افتح مستكشف الاختبارات بالنقر على أيقونة القارورة في شريط النشاط -2. وسّع شجرة الاختبارات لرؤية جميع الوحدات وفئات الاختبار +1. افتح مستكشف الاختبارات بالنقر على أيقونة الإناء في شريط النشاط +2. وسع شجرة الاختبارات لرؤية جميع الوحدات وفئات الاختبار 3. انقر على زر التشغيل بجانب أي اختبار لتشغيله بشكل فردي -4. انقر على "تشغيل جميع الاختبارات" لتنفيذ المجموعة كاملة -5. انقر بزر الفأرة الأيمن على أي اختبار واختر "تصحيح الاختبار" لتعيين نقاط توقف والتنقل خلال الكود +4. انقر على "Run All Tests" لتشغيل المجموعة كاملة +5. انقر بزر الماوس الأيمن على أي اختبار واختر "Debug Test" لتهيئة نقاط التوقف والتنقل خلال الكود -يعرض مستكشف الاختبارات علامات تحقق خضراء للاختبارات التي اجتازت ويقدم رسائل تفصيلية عند الفشل. +يظهر مستكشف الاختبارات علامات تحقق خضراء للاختبارات الناجحة ويوفر رسائل فشل مفصلة عند فشل الاختبارات. ## أنماط الاختبار -### النمط 1: اختبار قوالب المطالبات +### النمط 1: اختبار قوالب الموجهات -أبسط نمط يختبر قوالب المطالبات دون استدعاء أي نموذج ذكاء اصطناعي. تتحقق من أن استبدال المتغيرات يعمل بشكل صحيح وأن المطالبات منسقة كما هو متوقع. +أبسط نمط يختبر قوالب الموجهات دون استدعاء أي نموذج ذكاء اصطناعي. تتحقق من أن استبدال المتغيرات يعمل بشكل صحيح وأن الموجهات منسقة كما هو متوقع. -اختبار قالب المطالبة +Prompt Template Testing -*اختبار قوالب المطالبات يعرض تدفق استبدال المتغيرات: القالب مع عناصر نائب → تطبيق القيم → التحقق من المخرجات المنسقة* +*اختبار قوالب الموجهات يبين تدفق استبدال المتغيرات: القالب مع أماكن الحجز → تطبيق القيم → التحقق من المخرجات المنسقة* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -يُوجد هذا الاختبار في `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +هذا النمط يتحقق من أن استبدال المتغير يعمل بشكل صحيح وأن الموجهات منسقة كما هو متوقع — دون الحاجة إلى مفتاح API أو استدعاء نموذج. -**شغّله:** +### النمط 2: تمثيل نماذج اللغة المزيفة -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#اختبار_تنسيق_نموذج_المطالبة -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#اختبار تنسيق قالب الطلب -``` - -### النمط 2: تمويه نماذج اللغة - -عند اختبار منطق المحادثة، استخدم Mockito لإنشاء نماذج وهمية تعيد ردودًا محددة مسبقًا. هذا يجعل الاختبارات سريعة، مجانية، وحتمية. +عند اختبار منطق المحادثة، استخدم Mockito لإنشاء نماذج مزيفة تعيد استجابات محددة مسبقًا. هذا يجعل الاختبارات سريعة ومجانية وحتمية. -مقارنة تمويه مقابل API حقيقي +Mock vs Real API Comparison -*مقارنة توضح لماذا يُفضل استخدام التمويه للاختبار: إنها سريعة، مجانية، حتمية، ولا تتطلب مفاتيح API* +*مقارنة توضح لماذا يُفضّل استخدام النماذج المزيفة للاختبار: فهي سريعة، مجانية، حتمية، ولا تتطلب مفاتيح API* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 رسائل من المستخدم + 3 رسائل من الذكاء الاصطناعي + assertThat(history).hasSize(6); // ٣ رسائل من المستخدم + ٣ رسائل من الذكاء الاصطناعي } } ``` -يظهر هذا النمط في `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. يضمن التمويه سلوكًا متسقًا حتى تتمكن من التحقق من أن إدارة الذاكرة تعمل بشكل صحيح. +هذا النمط يظهر في `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. النموذج المزيف يضمن سلوكًا متسقًا لكي تتحقق من أن إدارة الذاكرة تعمل بشكل صحيح. ### النمط 3: اختبار عزل المحادثة -يجب على ذاكرة المحادثة أن تحافظ على فصل المستخدمين المتعددين. يتحقق هذا الاختبار من أن المحادثات لا تخلط بين السياقات. +يجب أن تحافظ ذاكرة المحادثة على فصل المستخدمين المتعددين. هذا الاختبار يتحقق من أن المحادثات لا تخلط السياقات. -عزل المحادثة +Conversation Isolation -*اختبار عزل المحادثة يظهر تخزين ذاكرة منفصلة لمستخدمين مختلفين لمنع اختلاط السياقات* +*اختبار عزل المحادثة يظهر تخزينات ذاكرة منفصلة لمستخدمين مختلفين لمنع خلط السياق* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -تحافظ كل محادثة على تاريخها الخاص المستقل. في الأنظمة الإنتاجية، هذا العزل ضروري لتطبيقات المستخدمين المتعددين. +تحافظ كل محادثة على سجل مستقل خاص بها. في أنظمة الإنتاج، هذا العزل مهم جدًا لتطبيقات متعددة المستخدمين. ### النمط 4: اختبار الأدوات بشكل مستقل -الأدوات هي دوال يمكن للذكاء الاصطناعي استدعاؤها. اختبرها مباشرة للتأكد من أنها تعمل بشكل صحيح بغض النظر عن قرارات الذكاء الاصطناعي. +الأدوات هي دوال يمكن للذكاء الاصطناعي استدعاؤها. اختبرها مباشرة للتأكد من أنها تعمل بشكل صحيح بغض النظر عن قرارات AI. -اختبار الأدوات +Tools Testing -*اختبار الأدوات بشكل مستقل يعرض تنفيذ أداة وهمية بدون استدعاءات الذكاء الاصطناعي للتحقق من منطق الأعمال* +*اختبار الأدوات بشكل مستقل يوضح تنفيذ الأداة المزيفة دون استدعاء AI للتحقق من منطق العمل* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -تحقق هذه الاختبارات من `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` من منطق الأدوات بدون تداخل الذكاء الاصطناعي. يظهر مثال الربط كيف يمر مخرج أداة إلى مدخل أخرى. +هذه الاختبارات من `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` تتحقق من منطق الأدوات دون تدخل AI. يظهر مثال التسلسل كيف تُستخدم مخرجات أداة كمدخل لأخرى. ### النمط 5: اختبار RAG في الذاكرة -تتطلب أنظمة RAG تقليديًا قواعد بيانات متجهية وخدمات تضمين. يتيح نمط الذاكرة اختبار الخطوط كاملة دون الاعتماد على خدمات خارجية. +تتطلب أنظمة RAG تقليديًا قواعد بيانات متجه وتضمين خدمات التضمين. يسمح نمط الذاكرة باختبار كامل الخط بدون تبعيات خارجية. -اختبار RAG في الذاكرة +In-Memory RAG Testing -*تدفق عمل اختبار RAG في الذاكرة يظهر تحليل الوثائق، تخزين التضمينات، والبحث التشابهي دون الحاجة لقاعدة بيانات* +*سير عمل اختبار RAG داخل الذاكرة يوضح تحليل المستندات، تخزين التضمين، والبحث في التشابه دون الحاجة لقاعدة بيانات* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -يخلق هذا الاختبار من `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` مستندًا في الذاكرة ويتحقق من تجزئة المحتوى والتعامل مع البيانات الوصفية. +هذا الاختبار من `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` ينشئ مستندًا في الذاكرة ويتحقق من التقطيع والتعامل مع البيانات الوصفية. ### النمط 6: اختبار تكامل MCP -اختبار وحدة MCP يختبر تكامل بروتوكول سياق النموذج باستخدام نقل stdio. تتحقق هذه الاختبارات من أن تطبيقك يمكنه تشغيل والتواصل مع خوادم MCP كعمليات فرعية. +تختبر وحدة MCP تكامل بروتوكول سياق النموذج باستخدام نقل stdio. تتحقق هذه الاختبارات من أن تطبيقك يمكنه تشغيل خوادم MCP والتواصل معها كعمليات فرعية. تتحقق الاختبارات في `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` من سلوك عميل MCP. -**شغّلها:** +**شغلها:** **Bash:** ```bash @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## فلسفة الاختبار -اختبر كودك، لا اختبر الذكاء الاصطناعي. يجب أن تتحقق اختباراتك من الكود الذي تكتبه عبر فحص كيفية بناء المطالبات، كيفية إدارة الذاكرة، وكيف تنفذ الأدوات. ردود الذكاء الاصطناعي متغيرة ولا يجب أن تكون جزءًا من تأكيدات الاختبار. اسأل نفسك ما إذا كانت قالب مطالبتك يستبدل المتغيرات بشكل صحيح، وليس ما إذا كان الذكاء الاصطناعي يعطي الإجابة الصحيحة. +اختبر الكود الخاص بك، وليس الذكاء الاصطناعي. يجب أن تتحقق اختباراتك من الكود الذي تكتبه بفحص كيفية بناء الموجهات، وإدارة الذاكرة، وتنفيذ الأدوات. استجابات AI متغيرة ولا ينبغي أن تكون جزءًا من تأكيدات الاختبار. اسأل نفسك هل قالب الموجه يستبدل المتغيرات بالشكل الصحيح، وليس ما إذا كان AI يعطي الإجابة الصحيحة. -استخدم التمويه لنماذج اللغة. إنها تبعيات خارجية بطيئة، مكلفة، وغير حتمية. يجعل التمويه الاختبارات سريعة بالوحدات المللي ثانية بدل الثواني، مجانية بدون تكاليف API، وحتمية دائمًا تعطي نفس النتيجة. +استخدم النماذج المزيفة لنماذج اللغة. فهي تبعيات خارجية بطيئة، مكلفة، وغير حتمية. يجعل التمثيل المزيف الاختبارات سريعة بآلاف الأضعاف، مجانية دون تكاليف API، وحتمية بذات النتيجة في كل مرة. -حافظ على استقلالية الاختبارات. يجب أن يهيئ كل اختبار بياناته الخاصة، لا يعتمد على اختبارات أخرى، وينظف بعد نفسه. يجب أن تجتاز الاختبارات بغض النظر عن ترتيب التنفيذ. +اجعل الاختبارات مستقلة. يجب أن يُعد كل اختبار بياناته الخاصة، ولا يعتمد على اختبارات أخرى، وينظف بعد نفسه. يجب أن تنجح الاختبارات بغض النظر عن ترتيب التنفيذ. -اختبر الحالات الحدية بما يتجاوز المسار السعيد. جرّب المدخلات الفارغة، المدخلات الكبيرة جدًا، الأحرف الخاصة، المعلمات غير الصالحة، والشروط الحدية. غالبًا ما تكشف هذه عن عيوب لا يظهرها الاستخدام الطبيعي. +اختبر الحالات الحدية خارج المسار السعيد. جرّب مدخلات فارغة، مدخلات كبيرة جدًا، حروف خاصة، معلمات غير صالحة، وظروف الحدود. غالبًا ما تكشف هذه عن أخطاء لا يكشفها الاستخدام العادي. -استخدم أسماء وصفية. قارن بين `shouldMaintainConversationHistoryAcrossMultipleMessages()` و`test1()`. الأولى تخبرك بالضبط ما الذي يُختبر، مما يجعل تصحيح الأخطاء أسهل بكثير. +استخدم أسماء وصفية. قارن بين `shouldMaintainConversationHistoryAcrossMultipleMessages()` و `test1()`. يوضح الأول بالضبط ما الذي يُختبر، مما يسهل تتبع الأخطاء كثيرًا. ## الخطوات التالية -الآن بعد أن فهمت أنماط الاختبار، تعمّق أكثر في كل وحدة: +الآن بعد أن فهمت أنماط الاختبار، تعمق أكثر في كل وحدة: -- **[00 - بدء سريع](../00-quick-start/README.md)** - ابدأ بأساسيات قوالب المطالبات -- **[01 - مقدمة](../01-introduction/README.md)** - تعلّم إدارة ذاكرة المحادثة -- **[02 - هندسة المطالبات](../02-prompt-engineering/README.md)** - أتقن أنماط GPT-5.2 للمطالبات -- **[03 - RAG](../03-rag/README.md)** - ابنِ أنظمة التوليد المعززة بالاسترجاع -- **[04 - الأدوات](../04-tools/README.md)** - نفّذ استدعاء الدوال وربط الأدوات +- **[01 - المقدمة](../01-introduction/README.md)** - تعلّم إدارة ذاكرة المحادثة +- **[02 - هندسة الموجهات](../02-prompt-engineering/README.md)** - اتقن أنماط توجيه GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - بناء أنظمة توليد معززة بالاسترجاع +- **[04 - الأدوات](../04-tools/README.md)** - تنفيذ استدعاء الدوال وتسلسل الأدوات - **[05 - MCP](../05-mcp/README.md)** - دمج بروتوكول سياق النموذج -يوفر ملف README في كل وحدة شروحات مفصلة للمفاهيم التي تم اختبارها هنا. +كل ملف README للوحدة يقدم شروحات مفصلة للمفاهيم التي تم اختبارها هنا. --- -**التنقل:** [← العودة إلى الرئيسي](../README.md) +**التنقل:** [← العودة للرئيسية](../README.md) --- -**إخلاء المسؤولية**: -تمت ترجمة هذا المستند باستخدام خدمة الترجمة الآلية [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للحفاظ على الدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية هو المصدر المعتمد والرسمي. للمعلومات الحرجة، يُوصى بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة. +**تنويه**: +تمت ترجمة هذا المستند باستخدام خدمة الترجمة بالذكاء الاصطناعي [Co-op Translator](https://github.com/Azure/co-op-translator). بينما نسعى للدقة، يرجى العلم أن الترجمات الآلية قد تحتوي على أخطاء أو عدم دقة. يجب اعتبار المستند الأصلي بلغته الأصلية المصدر الرسمي والمعتمد. للمعلومات الهامة، يُنصح بالاستعانة بترجمة بشرية محترفة. نحن غير مسؤولين عن أي سوء فهم أو تفسير ناتج عن استخدام هذه الترجمة. \ No newline at end of file diff --git a/translations/bg/.co-op-translator.json b/translations/bg/.co-op-translator.json index abf2dd7ba..dbd19a8df 100644 --- a/translations/bg/.co-op-translator.json +++ b/translations/bg/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "bg" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T00:00:47+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T11:06:58+00:00", "source_file": "01-introduction/README.md", "language_code": "bg" }, @@ -18,20 +18,20 @@ "language_code": "bg" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T00:03:23+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T11:02:15+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "bg" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T00:04:59+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T11:06:06+00:00", "source_file": "03-rag/README.md", "language_code": "bg" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:34:22+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T11:04:43+00:00", "source_file": "04-tools/README.md", "language_code": "bg" }, @@ -54,8 +54,8 @@ "language_code": "bg" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:01:11+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T11:00:51+00:00", "source_file": "README.md", "language_code": "bg" }, @@ -72,14 +72,14 @@ "language_code": "bg" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T00:08:28+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T11:02:52+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "bg" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T00:09:12+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T11:03:28+00:00", "source_file": "docs/TESTING.md", "language_code": "bg" } diff --git a/translations/bg/00-quick-start/README.md b/translations/bg/00-quick-start/README.md deleted file mode 100644 index 4773be6ef..000000000 --- a/translations/bg/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Бърз старт - -## Съдържание - -- [Въведение](../../../00-quick-start) -- [Какво е LangChain4j?](../../../00-quick-start) -- [Зависимости на LangChain4j](../../../00-quick-start) -- [Предпоставки](../../../00-quick-start) -- [Настройка](../../../00-quick-start) - - [1. Вземете своя GitHub токен](../../../00-quick-start) - - [2. Задайте своя токен](../../../00-quick-start) -- [Стартиране на примерите](../../../00-quick-start) - - [1. Основен чат](../../../00-quick-start) - - [2. Шаблони за подсказки](../../../00-quick-start) - - [3. Извикване на функции](../../../00-quick-start) - - [4. Въпроси и отговори за документи (Easy RAG)](../../../00-quick-start) - - [5. Отговорен AI](../../../00-quick-start) -- [Какво показва всеки пример](../../../00-quick-start) -- [Следващи стъпки](../../../00-quick-start) -- [Отстраняване на проблеми](../../../00-quick-start) - -## Въведение - -Този бърз старт има за цел да ви помогне да започнете да работите с LangChain4j възможно най-бързо. Той обхваща абсолютните основи на изграждането на AI приложения с LangChain4j и GitHub модели. В следващите модули ще преминете към Azure OpenAI и GPT-5.2 и ще навлезете по-дълбоко във всеки концепт. - -## Какво е LangChain4j? - -LangChain4j е Java библиотека, която улеснява изграждането на AI-задвижвани приложения. Вместо да се занимавате с HTTP клиенти и парсване на JSON, работите с чисти Java API-та. - -„Верига“ в LangChain означава свързване на множество компоненти заедно – например можете да свържете подсказка към модел към парсър, или да свържете няколко AI повиквания, където един изход се подава като вход на следващото. Този бърз старт се фокусира върху основите, преди да разгледа по-сложни вериги. - -LangChain4j Chaining Concept - -*Свързване на компоненти в LangChain4j – основни блокове, които се свързват, за да създадат мощни AI работни потоци* - -Ще използваме три основни компонента: - -**ChatModel** – интерфейс за взаимодействие с AI модели. Извиквате `model.chat("prompt")` и получавате отговор като низ. Използваме `OpenAiOfficialChatModel`, който работи с OpenAI-съвместими крайни точки като GitHub модели. - -**AiServices** – създава типобезопасни AI интерфейси за услуги. Дефинирате методи, анотирате ги с `@Tool` и LangChain4j управлява оркестрацията. AI автоматично извиква вашите Java методи когато е необходимо. - -**MessageWindowChatMemory** – поддържа историята на разговора. Без това всяка заявка е независима. С него AI помни предишните съобщения и поддържа контекст през няколко цикъла. - -LangChain4j Architecture - -*Архитектура на LangChain4j – основни компоненти, които работят заедно, за да задвижат вашите AI приложения* - -## Зависимости на LangChain4j - -Този бърз старт използва три Maven зависимости в [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Модулът `langchain4j-open-ai-official` предоставя класа `OpenAiOfficialChatModel`, който се свързва с OpenAI-съвместими API-та. GitHub модели използват същия API формат, така че не е необходим специален адаптер – просто насочете основния URL към `https://models.github.ai/inference`. - -Модулът `langchain4j-easy-rag` предоставя автоматично разделяне на документи, вграждане и извличане, така че да може да изградите RAG приложения без да конфигурирате всеки етап ръчно. - -## Предпоставки - -**Използвате Dev Container?** Java и Maven вече са инсталирани. Нужно е само да имате GitHub Personal Access Token. - -**Локална разработка:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (инструкции по-долу) - -> **Важно:** Този модул използва `gpt-4.1-nano` от GitHub модели. Не променяйте името на модела в кода – той е конфигуриран да работи с наличните модели на GitHub. - -## Настройка - -### 1. Вземете своя GitHub токен - -1. Отидете на [GitHub Настройки → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Кликнете „Generate new token“ -3. Задайте описателно име (например „LangChain4j Demo“) -4. Изберете срок на валидност (препоръчително 7 дни) -5. Под „Account permissions“ намерете „Models“ и задайте на „Read-only“ -6. Кликнете „Generate token“ -7. Копирайте и запазете токена си – няма да го видите отново - -### 2. Задайте своя токен - -**Опция 1: Използване на VS Code (Препоръчително)** - -Ако използвате VS Code, добавете токена в `.env` файла в корена на проекта: - -Ако файлът `.env` не съществува, копирайте `.env.example` до `.env` или създайте нов `.env` файл в корена на проекта. - -**Примерен `.env` файл:** -```bash -# В /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -След това просто кликнете с десния бутон върху който и да е демонстрационен файл (например `BasicChatDemo.java`) в Explorer и изберете **„Run Java“** или използвайте конфигурациите за стартиране от панела Run and Debug. - -**Опция 2: С помощта на терминал** - -Задайте токена като променлива на средата: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Стартиране на примерите - -**С VS Code:** Просто кликнете с десен бутон върху който и да е демонстрационен файл в Explorer и изберете **„Run Java“**, или използвайте конфигурациите за стартиране от панела Run and Debug (преди това трябва да сте добавили токена в `.env` файла). - -**С Maven:** Алтернативно, можете да стартирате от командния ред: - -### 1. Основен чат - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Шаблони за подсказки - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Показва zero-shot, few-shot, chain-of-thought и подсказки на база роли. - -### 3. Извикване на функции - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI автоматично извиква вашите Java методи когато е нужно. - -### 4. Въпроси и отговори за документи (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Задавайте въпроси за вашите документи, използвайки Easy RAG с автоматично вграждане и извличане. - -### 5. Отговорен AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Вижте как филтрите за безопасност на AI блокират вредно съдържание. - -## Какво показва всеки пример - -**Основен чат** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Започнете тук, за да видите LangChain4j в най-простия му вид. Ще създадете `OpenAiOfficialChatModel`, ще изпратите подсказка с `.chat()` и ще получите отговор. Това демонстрира основата: как да инициализирате модели с персонализирани крайни точки и API ключове. След като разберете този модел, всичко останало се изгражда върху него. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) и попитайте: -> - „Как да премина от GitHub Models към Azure OpenAI в този код?“ -> - „Какви други параметри мога да конфигурирам в OpenAiOfficialChatModel.builder()?“ -> - „Как да добавя стрийминг на отговорите вместо да чакам цялостния отговор?“ - -**Инженерство на подсказки** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Сега, когато знаете как да говорите с модел, нека разгледаме какво му казвате. Този демонстрационен пример използва същата настройка на модела, но показва пет различни шаблона за подсказки. Опитайте zero-shot подсказки за директни инструкции, few-shot подсказки, които се учат от примери, chain-of-thought подсказки, които разкриват стъпки на разсъждение, и подсказки на база роли, които задават контекст. Ще видите как един и същ модел дава драматично различни резултати в зависимост от това как формулирате заявката си. - -Демонстрацията също показва шаблони за подсказки, които са мощен начин за създаване на многократно използваеми подсказки с променливи. -Долният пример показва подсказка, използваща `PromptTemplate` на LangChain4j за попълване на променливи. AI ще отговори въз основа на посочената дестинация и дейност. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) и попитайте: -> - „Каква е разликата между zero-shot и few-shot подсказките, и кога да използвам коя?“ -> - „Как параметърът temperature влияе на отговорите на модела?“ -> - „Какви са някои техники за предотвратяване на атаки с вкарване на подсказки в продукция?“ -> - „Как да създам многократно използваеми обекти PromptTemplate за често срещани шаблони?“ - -**Интеграция на инструменти** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Тук LangChain4j става мощен. Ще използвате `AiServices`, за да създадете AI асистент, който може да извиква вашите Java методи. Просто анотирайте методите с `@Tool("описание")` и LangChain4j се грижи за останалото – AI автоматично решава кога да използва всеки инструмент според това, което потребителят пита. Това демонстрира извикване на функции – ключова техника за изграждане на AI, който може да предприема действия, а не само да отговаря на въпроси. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) и попитайте: -> - „Как работи анотацията @Tool и какво прави LangChain4j с нея зад кулисите?“ -> - „Може ли AI да извика няколко инструмента последователно, за да реши сложни проблеми?“ -> - „Какво се случва, ако инструмент хвърли изключение – как да обработвам грешки?“ -> - „Как бих интегрирал истинско API вместо този пример с калкулатор?“ - -**Въпроси и отговори за документи (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Тук ще видите RAG (генериране с извличане) с подхода "Easy RAG" на LangChain4j. Документите се зареждат, автоматично се разделят и вграждат в паметта, след което съдържателен извличач доставя релевантни части към AI по време на запитване. AI отговаря въз основа на вашите документи, а не на общото си знание. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) и попитайте: -> - „Как RAG предотвратява халюцинациите на AI в сравнение с използването на тренировъчните данни на модела?“ -> - „Каква е разликата между този лесен подход и персонализиран RAG пайплайн?“ -> - „Как бих мащабирал това, за да обхване множество документи или по-големи бази знания?“ - -**Отговорен AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Изградете безопасност на AI с многослойни защити. Този демо пример показва два слоя защита, работещи заедно: - -**Част 1: LangChain4j Input Guardrails** – блокира опасни подсказки преди да достигнат до LLM. Създавайте персонализирани guardrails, които проверяват за забранени ключови думи или шаблони. Те се изпълняват във вашия код, така че са бързи и безплатни. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Част 2: Филтри за безопасност на доставчика** – GitHub модели имат вградени филтри, които хващат това, което вашите guardrails могат да пропуснат. Ще видите твърди блокировки (HTTP 400 грешки) при сериозни нарушения и меки откази, при които AI учтиво отказва. - -> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) и попитайте: -> - „Какво представлява InputGuardrail и как да създам свой собствен?“ -> - „Каква е разликата между твърд блок и мек отказ?“ -> - „Защо да използвам и guardrails, и филтри на доставчика заедно?“ - -## Следващи стъпки - -**Следващ модул:** [01-introduction - Запознаване с LangChain4j](../01-introduction/README.md) - ---- - -**Навигация:** [← Обратно към основното](../README.md) | [Напред: Модул 01 - Въведение →](../01-introduction/README.md) - ---- - -## Отстраняване на проблеми - -### Първа компилация с Maven - -**Проблем:** Първоначалното `mvn clean compile` или `mvn package` отнема дълго (10–15 минути) - -**Причина:** Maven трябва да изтегли всички зависимости на проекта (Spring Boot, LangChain4j библиотеки, Azure SDK и др.) при първата компилация. - -**Решение:** Това е нормално поведение. Следващите компилации ще бъдат значително по-бързи, тъй като зависимостите са кеширани локално. Времето за изтегляне зависи от скоростта на вашата мрежа. - -### Синтаксис на Maven команди в PowerShell - -**Проблем:** Maven командите се провалят с грешка `Unknown lifecycle phase ".mainClass=..."` -**Причина**: PowerShell тълкува `=` като оператор за присвояване на променлива, което разваля синтаксиса на Maven свойството - -**Решение**: Използвайте операторa за спиране на парсване `--%` преди Maven командата: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Операторът `--%` казва на PowerShell да предаде всички останали аргументи буквално на Maven без тълкуване. - -### Показване на емоджита в Windows PowerShell - -**Проблем**: Отговорите от AI показват неразбираеми символи (напр. `????` или `â??`) вместо емоджита в PowerShell - -**Причина**: По подразбиране енкодингът на PowerShell не поддържа UTF-8 емоджита - -**Решение**: Изпълнете тази команда преди стартирането на Java приложения: -```cmd -chcp 65001 -``` - -Това принуждава използването на UTF-8 енкодинг в терминала. Като алтернатива, използвайте Windows Terminal, който има по-добра поддръжка на Unicode. - -### Отстраняване на грешки при API повиквания - -**Проблем**: Грешки при удостоверяване, ограничения на заявките или неочаквани отговори от AI модела - -**Решение**: Примерите включват `.logRequests(true)` и `.logResponses(true)` за показване на API повикванията в конзолата. Това помага при отстраняване на грешки с удостоверяването, ограниченията на броя на заявките или неочаквани отговори. Премахнете тези флагове в продукция, за да намалите шума в логовете. - ---- - - -**Отказ от отговорност**: -Този документ е преведен с помощта на AI преводаческа услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на своя роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. - \ No newline at end of file diff --git a/translations/bg/01-introduction/README.md b/translations/bg/01-introduction/README.md index 8b24a2f0b..ec0bd7a25 100644 --- a/translations/bg/01-introduction/README.md +++ b/translations/bg/01-introduction/README.md @@ -2,39 +2,39 @@ ## Съдържание -- [Видео преглед](../../../01-introduction) -- [Какво ще научите](../../../01-introduction) -- [Изисквания](../../../01-introduction) -- [Разбиране на основния проблем](../../../01-introduction) -- [Разбиране на токените](../../../01-introduction) -- [Как работи паметта](../../../01-introduction) -- [Как това използва LangChain4j](../../../01-introduction) -- [Деплойване на Azure OpenAI инфраструктура](../../../01-introduction) -- [Стартиране на приложението локално](../../../01-introduction) -- [Използване на приложението](../../../01-introduction) - - [Безсъстоянен чат (ляв панел)](../../../01-introduction) - - [Състоянен чат (десен панел)](../../../01-introduction) -- [Следващи стъпки](../../../01-introduction) - -## Видео преглед - -Гледайте тази жива сесия, която обяснява как да започнете с този модул: +- [Видео обхождане](#видео-обхождане) +- [Какво ще научите](#какво-ще-научите) +- [Предварителни изисквания](#предварителни-изисквания) +- [Разбиране на основния проблем](#разбиране-на-основния-проблем) +- [Разбиране на токените](#разбиране-на-токените) +- [Как работи паметта](#как-работи-паметта) +- [Как това използва LangChain4j](#как-това-използва-langchain4j) +- [Деплойване на Azure OpenAI инфраструктура](#деплойване-на-azure-openai-инфраструктура) +- [Стартиране на приложението локално](#стартиране-на-приложението-локално) +- [Използване на приложението](#използване-на-приложението) + - [Чат без състояние (ляв панел)](#чат-без-състояние-ляв-панел) + - [Чат със състояние (десен панел)](#чат-със-състояние-десен-панел) +- [Следващи стъпки](#следващи-стъпки) + +## Видео обхождане + +Гледайте тази сесия на живо, която обяснява как да започнете с този модул: Getting Started with LangChain4j - Live Session ## Какво ще научите -В бързия старт използвахте GitHub Models за изпращане на заявки, повикване на инструменти, изграждане на RAG pipeline и тестване на защитни механизми. Тези демонстрации показаха възможностите — сега преминаваме към Azure OpenAI и GPT-5.2 и започваме да изграждаме приложения със стил на продукция. Този модул се фокусира върху разговорния AI, който запомня контекст и поддържа състояние — понятия, които бързите стартиращи демонстрации използваха зад кулисите, но не обясняваха. +Това е вашата начална точка с LangChain4j и Azure OpenAI. Започваме с основите и започваме да изграждаме приложения в стил продукция. Този модул се фокусира върху разговорен ИИ, който помни контекста и поддържа състояние — основните концепции, върху които стъпва всеки следващ модул. -Ще използваме Azure OpenAI с GPT-5.2 през цялото ръководство, защото неговите усъвършенствани способности за разсъждение правят поведението на различните модели по-ясно. Когато добавите памет, ще видите ясно разликата. Това улеснява разбирането на ролята на всяка съставна част във вашето приложение. +Ще използваме Azure OpenAI GPT-5.2 през цялото ръководство, защото неговите усъвършенствани възможности за разсъждение правят поведението на различните модели по-ясно. Когато добавите памет, разликата се вижда ясно. Това улеснява разбирането какво всяка част носи на вашето приложение. Ще изградите едно приложение, което демонстрира и двата модела: -**Безсъстоянен чат** – Всяка заявка е независима. Моделът няма памет за предишни съобщения. Това е моделът, който използвахте в бързия старт. +**Чат без състояние** - Всяка заявка е независима. Моделът няма памет за предишни съобщения. Това е най-простото начало. -**Състоянен разговор** – Всяка заявка включва история на разговора. Моделът поддържа контекст през няколко стъпки на взаимодействие. Това е необходимо за приложения в продукция. +**Чат със състояние** - Всяка заявка включва история на разговора. Моделът поддържа контекст през няколко реплики. Това е необходимо за продукционни приложения. -## Изисквания +## Предварителни изисквания - Абонамент за Azure с достъп до Azure OpenAI - Java 21, Maven 3.9+ @@ -47,41 +47,41 @@ ## Разбиране на основния проблем -Езиковите модели са безсъстояни. Всяко API повикване е независимо. Ако изпратите "Казвам се Джон" и после попитате "Как се казвам?", моделът няма идея, че току-що сте се представили. Той обработва всяка заявка сякаш е първият ви разговор. +Езиковите модели са без състояние. Всяко API обаждане е независимо. Ако изпратите „Казвам се Джон“ и след това попитате „Как се казвам?“, моделът няма представа, че току-що сте се представили. Той третира всяка заявка сякаш е първият ви разговор. -Това е приемливо за прости въпроси и отговори, но е безполезно за истински приложения. Ботовете за обслужване на клиенти трябва да помнят какво сте им казали. Личните асистенти имат нужда от контекст. Всеки разговор с няколко хода изисква памет. +Това е приемливо за прости въпроси и отговори, но не е полезно за реални приложения. Ботовете за обслужване на клиенти трябва да помнят какво сте им казали. Личните асистенти се нуждаят от контекст. Всеки многоходов разговор изисква памет. -Следната диаграма сравнява двата подхода — вляво е безсъстояното повикване, което забравя името ви; вдясно е състояното повикване, подпомогнато от ChatMemory, което го помни. +Следната диаграма противопоставя двата подхода — от ляво, разговор без състояние, който забравя името ви; от дясно, разговор със състояние подкрепен от ChatMemory, който го помни. Stateless vs Stateful Conversations -*Разликата между безсъстояни (независими повиквания) и състояни (осъзнати за контекста) разговори* +*Разликата между разговорите без състояние (независими обаждания) и със състояние (запознати с контекста)* ## Разбиране на токените -Преди да преминем към разговорите, е важно да разберем токените - основните текстови единици, които езиковите модели обработват: +Преди да се потопите в разговори, важно е да разберете токените - основните единици текст, които езиковите модели обработват: Token Explanation -*Пример как текстът се разбива на токени – "I love AI!" се превръща в 4 отделни единици за обработка* +*Пример за това как текстът се разбива на токени - "Обичам ИИ!" става 4 отделни единици за обработка* -Токените са как AI моделите измерват и обработват текста. Думи, пунктуация и дори интервали могат да са токени. Вашият модел има ограничение за колко токени може да обработи наведнъж (400 000 за GPT-5.2, с до 272 000 входни токена и 128 000 изходни токена). Разбирането на токените помага да управлявате дължината на разговора и разходите. +Токените са начинът, по който ИИ моделите измерват и обработват текст. Думи, пунктуация и дори интервали могат да бъдат токени. Вашият модел има лимит за колко токени може да обработва наведнъж (400 000 за GPT-5.2, с до 272 000 входни токена и 128 000 изходни токена). Разбирането на токените помага да управлявате дължината на разговора и разходите. ## Как работи паметта -Разговорната памет решава безсъстояния проблем, като поддържа история на разговора. Преди да изпратите заявката си към модела, рамката предшества с релевантни предишни съобщения. Когато попитате "Как се казвам?", системата всъщност изпраща цялата история на разговора, позволявайки на модела да види, че преди сте казали "Казвам се Джон." +Чат паметта решава проблема без състояние, като поддържа историята на разговора. Преди да изпратите заявката към модела, фреймуъркът прибавя релевантни предишни съобщения. Когато питате „Как се казвам?“, системата всъщност изпраща цялата история на разговора, позволявайки на модела да види, че преди сте казали „Казвам се Джон“. -LangChain4j предоставя реализации на памет, които се грижат за това автоматично. Вие избирате колко съобщения да се съхраняват, а рамката управлява контекстния прозорец. Диаграмата по-долу показва как MessageWindowChatMemory поддържа плъзгащ се прозорец на последните съобщения. +LangChain4j предоставя имплементации на паметта, които го правят автоматично. Вие избирате колко съобщения да съхранявате и фреймуъркът управлява прозореца на контекста. Диаграмата по-долу показва как MessageWindowChatMemory поддържа приплъзващ се прозорец от последните съобщения. Memory Window Concept -*MessageWindowChatMemory поддържа плъзгащ се прозорец от последни съобщения, като автоматично премахва старите* +*MessageWindowChatMemory поддържа приплъзващ се прозорец от последните съобщения, автоматично премахвайки старите* ## Как това използва LangChain4j -Този модул разширява бързия старт, като интегрира Spring Boot и добавя памет за разговори. Ето как парчетата се свързват: +Този модул интегрира Spring Boot и добавя памет за разговори. Ето как частите се съчетават: -**Зависимости** – Добавете две библиотеки LangChain4j: +**Зависимости** - Добавете два LangChain4j библиотеки: ```xml @@ -94,7 +94,7 @@ LangChain4j предоставя реализации на памет, коит ``` -**Модел за чат** – Конфигурирайте Azure OpenAI като Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Чат модел** - Конфигурирайте Azure OpenAI като Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Билдърът чете идентификационните данни от променливи на средата, зададени от `azd up`. Задаването на `baseUrl` към вашия Azure крайна точка кара OpenAI клиента да работи с Azure OpenAI. +Билдърът чете креденшъли от променливи на средата, зададени от `azd up`. Задаването на `baseUrl` към вашия Azure endpoint прави OpenAI клиента да работи с Azure OpenAI. -**Памет за разговори** – Следете историята на чата с MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Памет за разговор** - Следете историята на чата с MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Създайте памет с `withMaxMessages(10)`, за да запазите последните 10 съобщения. Добавяйте потребителски и AI съобщения с типизирани обвивки: `UserMessage.from(text)` и `AiMessage.from(text)`. Вземете история с `memory.messages()` и я изпратете към модела. Сервисът съхранява отделни екземпляри на памет за всеки ID на разговор, позволявайки множество потребители да чатят едновременно. +Създайте памет с `withMaxMessages(10)`, за да запазите последните 10 съобщения. Добавят се съобщения от потребител и ИИ с типовете обвивки: `UserMessage.from(text)` и `AiMessage.from(text)`. Историята се извлича с `memory.messages()` и се изпраща на модела. Сървисът съхранява отделни екземпляри памет по ID на разговора, което позволява множество потребители да чатят едновременно. > **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) и питайте: -> - "Как MessageWindowChatMemory решава кои съобщения да премахне, когато прозорецът е пълен?" -> - "Мога ли да имплементирам персонализирано съхранение на памет, използвайки база данни вместо в паметта?" +> - "Как MessageWindowChatMemory решава кои съобщения да отпаднат, когато прозорецът е пълен?" +> - "Мога ли да имплементирам собствено съхранение на паметта, използвайки база данни вместо памет в RAM?" > - "Как бих добавил обобщение за компресиране на старата история на разговора?" -Крайната точка на безсъстояния чат пропуска паметта напълно - просто `chatModel.chat(prompt)`, както в бързия старт. Крайната точка на състояния чат добавя съобщения към паметта, извлича история и включва този контекст към всяка заявка. Същата конфигурация на модела, различни модели. +Чат без състояние изцяло пропуска паметта - просто `chatModel.chat(prompt)`, както при бързия старт. Чат със състояние добавя съобщения към паметта, извлича история и включва този контекст при всяка заявка. Същата конфигурация на модела, различни модели на взаимодействие. ## Деплойване на Azure OpenAI инфраструктура @@ -144,23 +144,23 @@ azd up # Изберете абонамент и местоположение ( **PowerShell:** ```powershell cd 01-introduction -azd up # Изберете абонамент и местоположение (препоръчва се eastus2) +azd up # Изберете абонамент и локация (препоръчително eastus2) ``` -> **Забележка:** Ако срещнете грешка за таймаут (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), просто стартирайте `azd up` отново. Ресурсите на Azure може още да се подготвят на заден план и повторното опитване позволява завършване на деплоймента, когато ресурсите достигнат краен статус. +> **Забележка:** Ако получите грешка за timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), просто стартирайте `azd up` отново. Възможно е Azure ресурсите все още да се подготвят във фонов режим, а повторното стартиране позволява деплойването да завърши, когато ресурсите достигнат крайнo състояние. Това ще: 1. Деплойне Azure OpenAI ресурс с GPT-5.2 и модели text-embedding-3-small -2. Автоматично генерира `.env` файл в корена на проекта с идентификационни данни -3. Настрой всички необходими променливи на средата +2. Автоматично генерира `.env` файл в главната папка на проекта с креденшъли +3. Настрои всички необходими променливи на средата -**Имате проблеми с деплоймента?** Вижте [Infrastructure README](infra/README.md) за подробни инструкции за отстраняване на проблеми, включително конфликти със субдомейн, ръчно деплойване през Azure Portal и указания за конфигурация на модели. +**Имате проблеми с деплойването?** Вижте [README за инфраструктура](infra/README.md) за подробна помощ при отстраняване на конфликти с имена на подпапки, ръчни стъпки през Azure Portal и насоки за конфигурация на модела. -**Проверете дали деплойментът е успешен:** +**Потвърдете успешното деплойване:** **Bash:** ```bash -cat ../.env # Трябва да показва AZURE_OPENAI_ENDPOINT, API_KEY и други. +cat ../.env # Трябва да покаже AZURE_OPENAI_ENDPOINT, API_KEY и т.н. ``` **PowerShell:** @@ -168,7 +168,7 @@ cat ../.env # Трябва да показва AZURE_OPENAI_ENDPOINT, API_KEY Get-Content ..\.env # Трябва да показва AZURE_OPENAI_ENDPOINT, API_KEY и др. ``` -> **Забележка:** Командата `azd up` автоматично генерира `.env` файла. Ако трябва да го обновите по-късно, можете или да редактирате `.env` файла ръчно, или да го регенерирате чрез: +> **Забележка:** Командата `azd up` автоматично генерира `.env` файла. Ако искате да го актуализирате по-късно, може да го редактирате ръчно или да го регенерирате като изпълните: > > **Bash:** > ```bash @@ -184,9 +184,9 @@ Get-Content ..\.env # Трябва да показва AZURE_OPENAI_ENDPOINT, A ## Стартиране на приложението локално -**Проверете деплоймента:** +**Потвърдете деплойването:** -Уверете се, че `.env` файлът съществува в кореновата директория с Azure идентификационни данни. Стартирайте това от директорията на модула (`01-introduction/`): +Уверете се, че файлът `.env` съществува в главната директория и съдържа Azure креденшъли. Стартирайте това от директорията на модула (`01-introduction/`): **Bash:** ```bash @@ -198,31 +198,31 @@ cat ../.env # Трябва да показва AZURE_OPENAI_ENDPOINT, API_KEY, Get-Content ..\.env # Трябва да показва AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Стартиране на приложенията:** +**Стартирайте приложенията:** -**Вариант 1: Използване на Spring Boot Dashboard (препоръчително за потребители на VS Code)** +**Опция 1: Използване на Spring Boot Dashboard (Препоръчва се за потребители на VS Code)** -Dev контейнерът включва разширението Spring Boot Dashboard, което предоставя визуален интерфейс за управление на всички Spring Boot приложения. Можете да го намерите в Activity Bar в лявата част на VS Code (потърсете иконата на Spring Boot). +Dev контейнерът включва разширението Spring Boot Dashboard, което предоставя визуален интерфейс за управление на всички Spring Boot приложения. Можете да го намерите в Activity Bar отляво във VS Code (погледнете за иконата на Spring Boot). -От Spring Boot Dashboard можете да: -- Видите всички достъпни Spring Boot приложения в работната среда -- Стартирате/спирате приложения с един клик -- Преглеждате логове в реално време -- Мониторинг на статус на приложенията +От Spring Boot Dashboard можете: +- Да видите всички налични Spring Boot приложения в работното пространство +- Да стартирате/спирате приложения с един клик +- Да виждате логовете на приложенията в реално време +- Да наблюдавате състоянието на приложенията -Просто кликнете бутонът за пускане до "introduction", за да стартирате този модул, или стартирайте всички модули наведнъж. +Просто натиснете бутона за пускане до „introduction“, за да стартирате този модул, или стартирайте всички модули наведнъж. Spring Boot Dashboard *Spring Boot Dashboard във VS Code — стартирайте, спирайте и наблюдавайте всички модули от едно място* -**Вариант 2: Използване на shell скриптове** +**Опция 2: Използване на shell скриптове** Стартирайте всички уеб приложения (модули 01-04): **Bash:** ```bash -cd .. # От коренната директория +cd .. # От главната директория ./start-all.sh ``` @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -И двата скрипта автоматично зареждат променливи на средата от кореновия `.env` файл и ще изградят JAR файловете, ако не съществуват. +И двата скрипта автоматично зареждат променливите на средата от файла `.env` в главната папка и ще компилират JAR файловете, ако ги няма. -> **Забележка:** Ако предпочитате да изградите всички модули ръчно преди стартиране: +> **Забележка:** Ако предпочитате да компилирате всички модули ръчно преди стартиране: > > **Bash:** > ```bash @@ -264,7 +264,7 @@ cd 01-introduction Отворете http://localhost:8080 в браузъра си. -**За спиране:** +**За да спрете:** **Bash:** ```bash @@ -282,41 +282,41 @@ cd ..; .\stop-all.ps1 # Всички модули ## Използване на приложението -Приложението предоставя уеб интерфейс с две реализации на чат един до друг. +Приложението предоставя уеб интерфейс с две имплементации на чат, разположени една до друга. Application Home Screen -*Табло, показващо опции за Simple Chat (безсъстоянен) и Conversational Chat (състоянен)* +*Табло, показващо както Simple Chat (без състояние), така и Conversational Chat (със състояние)* -### Безсъстоянен чат (ляв панел) +### Чат без състояние (ляв панел) -Опитайте първо това. Попитайте "Казвам се Джон" и веднага след това "Как се казвам?" Моделът няма да запомни, защото всяко съобщение е независимо. Това демонстрира основния проблем при базовата интеграция на езиков модел – липса на контекст на разговора. +Опитайте първо това. Попитайте "Казвам се Джон" и веднага след това "Как се казвам?" Моделът няма да запомни, тъй като всяко съобщение е независимо. Това демонстрира основния проблем при базовата интеграция на езиков модел - липса на контекст в разговора. Stateless Chat Demo -*AI не помни името ви от предишното съобщение* +*ИИ не помни името ви от предишното съобщение* -### Състоянен чат (десен панел) +### Чат със състояние (десен панел) -Сега опитайте същата последователност тук. Попитайте "Казвам се Джон" и после "Как се казвам?" Този път помни. Разликата е MessageWindowChatMemory - той поддържа историята на разговора и я включва при всяка заявка. Така работи разговорният AI в продукция. +Сега опитайте същата последователност тук. Попитайте "Казвам се Джон" и после "Как се казвам?" Този път моделът помни. Разликата е MessageWindowChatMemory - той поддържа историята на разговора и я включва във всяка заявка. Така работи продукционният разговорен ИИ. Stateful Chat Demo -*AI помни името ви от по-рано в разговора* +*ИИ помни името ви от по-рано в разговора* -И двата панела използват същия GPT-5.2 модел. Единствената разлика е паметта. Това ясно показва какво носи паметта на вашето приложение и защо е необходима за реални използвания. +Двата панела използват един и същ модел GPT-5.2. Единствената разлика е паметта. Това ясно показва какво носи паметта на вашето приложение и защо е критична за реални случаи. ## Следващи стъпки -**Следващ модул:** [02-prompt-engineering - Създаване на заявки с GPT-5.2](../02-prompt-engineering/README.md) +**Следващ модул:** [02-prompt-engineering - Проектиране на подсказки с GPT-5.2](../02-prompt-engineering/README.md) --- -**Навигация:** [← Предишен: Модул 00 - Бърз старт](../00-quick-start/README.md) | [Обратно към начало](../README.md) | [Напред: Модул 02 - Създаване на заявки →](../02-prompt-engineering/README.md) +**Навигация:** [← Обратно към Началото](../README.md) | [Напред: Модул 02 - Проектиране на подсказки →](../02-prompt-engineering/README.md) --- **Отказ от отговорност**: -Този документ е преведен с помощта на AI преводаческа услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален превод от човешки преводач. Не носим отговорност за каквито и да било недоразумения или неправилни тълкувания, произтичащи от използването на този превод. +Този документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. \ No newline at end of file diff --git a/translations/bg/02-prompt-engineering/README.md b/translations/bg/02-prompt-engineering/README.md index 5cefc7534..b9fed6329 100644 --- a/translations/bg/02-prompt-engineering/README.md +++ b/translations/bg/02-prompt-engineering/README.md @@ -1,32 +1,32 @@ -# Модул 02: Инженеринг на Подсказки с GPT-5.2 +# Модул 02: Инженерство на подсказки с GPT-5.2 ## Съдържание -- [Видео Обяснение](../../../02-prompt-engineering) -- [Какво ще научите](../../../02-prompt-engineering) -- [Предварителни изисквания](../../../02-prompt-engineering) -- [Разбиране на инженеринг на подсказки](../../../02-prompt-engineering) -- [Основи на инженеринг на подсказки](../../../02-prompt-engineering) - - [Подсказване без примери (Zero-Shot Prompting)](../../../02-prompt-engineering) - - [Подсказване с малко примери (Few-Shot Prompting)](../../../02-prompt-engineering) - - [Верига на мислене (Chain of Thought)](../../../02-prompt-engineering) - - [Подсказване на базата на роля (Role-Based Prompting)](../../../02-prompt-engineering) - - [Шаблони за подсказки (Prompt Templates)](../../../02-prompt-engineering) -- [Разширени модели](../../../02-prompt-engineering) -- [Стартиране на приложението](../../../02-prompt-engineering) -- [Екранни снимки на приложението](../../../02-prompt-engineering) -- [Разглеждане на моделите](../../../02-prompt-engineering) - - [Ниско срещу високо ентусиазирано поведение](../../../02-prompt-engineering) - - [Изпълнение на задачи (предговори за инструменти)](../../../02-prompt-engineering) - - [Саморефлектиращ се код](../../../02-prompt-engineering) - - [Структуриран анализ](../../../02-prompt-engineering) - - [Многоходов чат](../../../02-prompt-engineering) - - [Мислене стъпка по стъпка](../../../02-prompt-engineering) - - [Ограничен изход](../../../02-prompt-engineering) -- [Какво наистина научавате](../../../02-prompt-engineering) -- [Следващи стъпки](../../../02-prompt-engineering) - -## Видео Обяснение +- [Видеопреглед](#видеопреглед) +- [Какво ще научите](#какво-ще-научите) +- [Изисквания](#изисквания) +- [Разбиране на инженерството на подсказки](#разбиране-на-инженерството-на-подсказки) +- [Основи на инженерството на подсказки](#основи-на-инженерството-на-подсказки) + - [Подсказване с нулев опит](#подсказване-с-нулев-опит) + - [Подсказване с няколко примера](#подсказване-с-няколко-примера) + - [Верига на мисълта](#верига-на-мисълта) + - [Подсказване на база роля](#подсказване-на-база-роля) + - [Шаблони за подсказки](#шаблони-за-подсказки) +- [Разширени модели](#разширени-модели) +- [Стартиране на приложението](#стартирайте-приложението) +- [Екранни снимки на приложението](#скриншотове-на-приложението) +- [Изследване на моделите](#изследване-на-шаблоните) + - [Ниско срещу високо желание](#ниска-срещу-висока-активност-eagerness) + - [Изпълнение на задачи (първоначални съобщения за инструменти)](#изпълнение-на-задачи-въведение-на-инструменти) + - [Саморефлектиращ код](#саморефлектиращ-се-код) + - [Структуриран анализ](#структуриран-анализ) + - [Многоходов чат](#разговор-с-много-ходове) + - [Разсъждение стъпка по стъпка](#разсъждение-стъпка-по-стъпка) + - [Ограничен изход](#ограничен-изход) +- [Какво всъщност научавате](#какво-всъщност-учите) +- [Следващи стъпки](#следващи-стъпки) + +## Видеопреглед Гледайте тази сесия на живо, която обяснява как да започнете с този модул: @@ -34,68 +34,68 @@ ## Какво ще научите -Следната диаграма предоставя преглед на ключовите теми и умения, които ще развиете в този модул — от техники за прецизиране на подсказки до стъпковия работен процес, който ще следвате. +Следната диаграма предоставя преглед на ключовите теми и умения, които ще развиете в този модул — от техники за усъвършенстване на подсказките до стъпковия работен процес, който ще следвате. Какво ще научите -В предишните модули изследвахте базови взаимодействия на LangChain4j с GitHub модели и видяхте как паметта позволява разговорен AI с Azure OpenAI. Сега ще се фокусираме върху начина, по който задавате въпроси — самите подсказки — използвайки Azure OpenAI GPT-5.2. Начинът, по който структурирате подсказките си, драстично влияе върху качеството на отговорите, които получавате. Започваме с преглед на основните техники за подсказване, след което преминаваме към осем разширени модела, които използват пълноценно възможностите на GPT-5.2. +В предишния модул видяхте как паметта позволява разговорния AI с Azure OpenAI. Сега ще се фокусираме върху начина, по който задавате въпроси — самите подсказки — използвайки GPT-5.2 на Azure OpenAI. Начинът, по който структурирате подсказките си, драстично влияе върху качеството на отговорите, които получавате. Започваме с преглед на основните техники за подсказване, след което преминаваме към осем разширени модела, които използват пълноценно възможностите на GPT-5.2. -Ще използваме GPT-5.2, защото той въвежда контрол върху разсъжденията – можете да инструктирате модела колко да мисли преди да отговори. Това прави различните стратегии за подсказване по-ясни и помага да разберете кога да използвате всяка от тях. Ще се възползваме и от по-ниските ограничения за честота на заявките за GPT-5.2 в Azure в сравнение с моделите на GitHub. +Ще използваме GPT-5.2, защото той въвежда контрол на разсъжденията - можете да указвате на модела колко мислене да направи преди отговора. Това прави различните стратегии за подсказване по-ясни и ви помага да разберете кога да използвате кой подход. -## Предварителни изисквания +## Изисквания -- Завършен Модул 01 (разгърнати Azure OpenAI ресурси) -- Файл `.env` в основната директория с Azure идентификационни данни (създаден с `azd up` в Модул 01) +- Завършен Модул 01 (разположени ресурси на Azure OpenAI) +- Файл `.env` в основната директория с Azure идентификационни данни (създаден чрез `azd up` в Модул 01) -> **Забележка:** Ако все още не сте завършили Модул 01, първо следвайте инструкциите за разгръщане там. +> **Забележка:** Ако не сте завършили Модул 01, следвайте първо инструкциите за разполагане там. -## Разбиране на инженеринг на подсказки +## Разбиране на инженерството на подсказки -В същността си инженерингът на подсказки е разликата между неясни и прецизни инструкции, както илюстрира сравнението по-долу. +В основата си, инженерството на подсказки е разликата между неясни и точни инструкции, както илюстрира следното сравнение. -Какво е инженеринг на подсказки? +Какво е инженерство на подсказки? -Инженерингът на подсказки е проектиране на входен текст, който постоянно ви осигурява необходимите резултати. Това не е само задаване на въпроси – а структуриране на заявки, така че моделът да разбира точно какво искате и как да го осигури. +Инженерството на подсказки е за проектиране на входен текст, който постоянно ви дава нужните резултати. Не става въпрос само за задаване на въпроси - става дума за структуриране на заявки така, че моделът да разбере точно какво искате и как да го достави. -Мислете за това като за даване на инструкции на колега. "Поправи бъга" е неясно. "Поправи null pointer exception в UserService.java ред 45, като добавиш проверка за null" е специфично. Езиковите модели работят по същия начин – специфичността и структурата имат значение. +Представете си, че давате инструкции на колега. „Поправи бъга“ е неясно. „Поправи изключението null pointer в UserService.java ред 45 чрез добавяне на проверка за null“ е конкретно. Езиковите модели работят по същия начин - специфичността и структурата имат значение. -Диаграмата по-долу показва как LangChain4j се вписва в тази картина — свързвайки вашите шаблони за подсказки с модела чрез изграждащи блокове SystemMessage и UserMessage. +Диаграмата по-долу показва как LangChain4j се вписва в тази картина — свързвайки вашите шаблони за подсказки с модела чрез блоковете SystemMessage и UserMessage. -Как LangChain4j се вписва +Как LangChain4j пасва -LangChain4j осигурява инфраструктурата — връзки с моделите, памет и видове съобщения — докато моделите на подсказки са просто внимателно структурирани текстове, които изпращате през тази инфраструктура. Основните изграждащи блокове са `SystemMessage` (който задава поведението и ролята на ИИ) и `UserMessage` (който носи вашата реална заявка). +LangChain4j осигурява инфраструктурата — връзки с модел, памет и типове съобщения — докато шаблоните за подсказки са просто внимателно структурирани текстове, които изпращате през тази инфраструктура. Ключовите градивни елементи са `SystemMessage` (който задава поведението и ролята на AI) и `UserMessage` (който носи вашата актуална заявка). -## Основи на инженеринг на подсказки +## Основи на инженерството на подсказки -Петте основни техники, показани по-долу, формират основата на ефективния инженеринг на подсказки. Всяка една от тях адресира различен аспект от начина, по който комуникирате с езиковите модели. +Петте основни техники, показани по-долу, формират базата на ефективното инженерство на подсказки. Всяка от тях адресира различен аспект на това как комуникирате с езиковите модели. -Преглед на петте модела за инженеринг на подсказки +Преглед на пет основни модела за инженерство на подсказки -Преди да навлезем в разширените модели в този модул, нека прегледаме пет основни техники за подсказване. Те са градивните елементи, които всеки инженер на подсказки трябва да знае. Ако вече сте преминали [модула за бърз старт](../00-quick-start/README.md#2-prompt-patterns), вече сте ги виждали на практика — ето концептуалната рамка зад тях. +Преди да преминем към разширените модели в този модул, нека прегледаме пет основни техники за подсказване. Те са градивните блокове, които всеки инженер на подсказки трябва да знае. -### Подсказване без примери (Zero-Shot Prompting) +### Подсказване с нулев опит -Най-простият подход: даваш на модела директна инструкция без примери. Моделът разчита изцяло на обучението си, за да разбере и изпълни задачата. Това работи добре за прости заявки, където очакваното поведение е очевидно. +Най-простият подход: дайте на модела директна инструкция без примери. Моделът разчита изцяло на обучението си, за да разбере и изпълни задачата. Това работи добре за прости заявки, където очакваното поведение е очевидно. -Подсказване без примери +Подсказване с нулев опит -*Директна инструкция без примери — моделът извлича задачата само от инструкцията* +*Директна инструкция без примери — моделът извежда задачата само от инструкцията* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// Отговор: "Положителен" +// Отговор: "Позитивно" ``` -**Кога да се използва:** Прости класификации, директни въпроси, преводи или всяка задача, която моделът може да изпълни без допълнителни указания. +**Кога се използва:** Прости класификации, директни въпроси, преводи или всяка задача, която моделът може да изпълни без допълнителни насоки. -### Подсказване с малко примери (Few-Shot Prompting) +### Подсказване с няколко примера -Предоставят се примери, които демонстрират шаблона, който искате моделът да следва. Моделът научава очаквания входно-изходен формат от вашите примери и го прилага към нови въвходове. Това значително подобрява последователността при задачи, където желаният формат или поведение не е ясно. +Предоставете примери, които демонстрират модела да следва желания шаблон. Моделът научава очаквания вход-изход формат от вашите примери и го прилага към нови входове. Това значително подобрява последователността при задачи, където желаният формат или поведение не е явен. -Подсказване с малко примери +Подсказване с няколко примера -*Учене по примери — моделът идентифицира шаблона и го прилага към нови входни данни* +*Обучаване от примери — моделът идентифицира шаблона и го прилага към нови входове* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Кога да се използва:** Персонализирани класификации, последователно форматиране, задачи в специфични области, или когато резултатите от zero-shot са непоследователни. +**Кога се използва:** Персонализирани класификации, последователно форматиране, задачи в специфични области или когато резултатите с нулев опит са непоследователни. -### Верига на мислене (Chain of Thought) +### Верига на мисълта -Поискайте от модела да покаже своите разсъждения стъпка по стъпка. Вместо да скочи директно към отговор, моделът разбива проблема на части и работи върху всяка една от тях експлицитно. Това подобрява точността при задачи с математика, логика и многостепенни разсъждения. +Помолете модела да покаже мисловния си процес стъпка по стъпка. Вместо да скача направо към отговор, моделът разгражда проблема и преминава през всяка част експлицитно. Това подобрява точността при задачи, свързани с математика, логика и многостъпкови разсъждения. -Верига на мислене +Верига на мисълта -*Мислене стъпка по стъпка — разбиване на сложни проблеми в явни логически стъпки* +*Разсъждение стъпка по стъпка — разделяне на сложни проблеми на явни логични стъпки* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Моделът показва: 15 - 8 = 7, после 7 + 12 = 19 ябълки +// Моделът показва: 15 - 8 = 7, след това 7 + 12 = 19 ябълки ``` -**Кога да се използва:** Математически задачи, логически пъзели, отстраняване на грешки или всяка задача, при която показването на процеса на разсъждение подобрява точността и доверието. +**Кога се използва:** Математически задачи, логически пъзели, дебъгване или каквато и да е задача, при която показването на процеса на мислене подобрява точността и доверието. -### Подсказване на базата на роля (Role-Based Prompting) +### Подсказване на база роля -Задайте персона или роля на ИИ преди да зададете въпроса си. Това осигурява контекст, който оформя тона, дълбочината и фокуса на отговора. "Софтуерен архитект" дава различни съвети от "младши разработчик" или "одитор по сигурността". +Задайте персона или роля на AI преди да зададете въпроса си. Това осигурява контекст, който оформя тона, дълбочината и фокуса на отговора. „Софтуерен архитект“ дава различни съвети от „младши разработчик“ или „одитор по сигурността“. -Подсказване на базата на роля +Подсказване на база роля -*Задаване на контекст и персона — същият въпрос получава различен отговор в зависимост от зададената роля* +*Задаване на контекст и персона — един и същ въпрос получава различен отговор в зависимост от присвоената роля* ```java String prompt = """ @@ -157,11 +157,11 @@ String prompt = """ String response = model.chat(prompt); ``` -**Кога да се използва:** Преглед на код, обучение, анализ в специфични области или когато имате нужда от отговори, съобразени с определено ниво на експертиза или перспектива. +**Кога се използва:** Прегледи на код, обучение, анализ в специфични области или когато ви трябват отговори, пригодени за определено ниво на експертиза или перспектива. -### Шаблони за подсказки (Prompt Templates) +### Шаблони за подсказки -Създавайте многократно използваеми подсказки с променливи плейсхолдъри. Вместо да пишете нова подсказка всеки път, дефинирайте шаблон веднъж и попълвайте различни стойности. Класът `PromptTemplate` на LangChain4j го прави лесно с синтаксис `{{variable}}`. +Създавайте многократно използваеми подсказки с променливи плейсхолдъри. Вместо да пишете нова подсказка всеки път, дефинирайте шаблон веднъж и попълвайте различни стойности. Класът `PromptTemplate` на LangChain4j улеснява това с синтаксис `{{variable}}`. Шаблони за подсказки @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Кога да се използва:** Повтарящи се заявки с различни входни данни, пакетна обработка, изграждане на многократно използваеми AI работни процеси, или всякакъв сценарий, където структурата на подсказката остава същата, но данните се променят. +**Кога се използва:** Повтарящи се заявки с различни входове, пакетна обработка, изграждане на многократно използваеми AI работни потоци или всякакъв сценарий, в който структурата на подсказката остава същата, но данните се променят. --- -Тези пет основни техники ви дават здрава основа за повечето задачи за подсказване. Останалата част от този модул надгражда върху тях с **осем разширени модела**, които използват контрола на разсъжденията на GPT-5.2, самостоятелна оценка и възможности за структуриран изход. +Тези пет основи ви осигуряват здрава база за повечето задачи с подсказки. Останалата част от този модул ги разширява с **осем разширени модела**, които използват контрола на разсъжденията, самостоятелната оценка и възможностите за структурирани изходни данни на GPT-5.2. ## Разширени модели -След като покрихме основите, нека преминем към осемте разширени модела, които правят този модул уникален. Не всички проблеми изискват един и същ подход. Някои въпроси се нуждаят от бързи отговори, други от дълбоко мислене. Някои се нуждаят от видими разсъждения, други само от резултати. Всеки модел по-долу е оптимизиран за различен сценарий — а контролът на разсъжденията на GPT-5.2 прави разликите още по-очевидни. +С покрити основи, нека преминем към осемте разширени модела, които правят този модул уникален. Не всички проблеми изискват един и същи подход. Някои въпроси се нуждаят от бързи отговори, други от дълбоко обмисляне. Някои изискват видими разсъждения, други само резултати. Всеки модел по-долу е оптимизиран за различен сценарий — и контролът на разсъжденията на GPT-5.2 прави различията още по-очевидни. Осем модела за подсказване -*Преглед на осемте модела за инженеринг на подсказки и техните случаи на употреба* +*Преглед на осемте модела за инженерство на подсказки и техните приложения* -GPT-5.2 добавя още едно измерение към тези модели: *контрол на разсъжденията*. С плъзгача по-долу можете да регулирате мисловните усилия на модела — от бързи, директни отговори до дълбок, подробен анализ. +GPT-5.2 добавя още едно измерение към тези модели: *контрол на разсъжденията*. Плъзгачът по-долу показва как можете да регулирате усилието на мислене на модела — от бързи, директни отговори до дълбок, щателен анализ. -Контрол на разсъждения с GPT-5.2 +Контрол на разсъжденията с GPT-5.2 -*Контролът на разсъжденията на GPT-5.2 ви позволява да зададете колко да мисли моделът — от бързи директни отговори до дълбоко проучване* +*Контролът на разсъжденията в GPT-5.2 ви позволява да укажете колко мислене трябва да направи моделът — от бързи директни отговори до дълбоко изследване* -**Ниско ентусиазирано поведение (бързо и фокусирано)** - За прости въпроси, при които искате бързи, директни отговори. Моделът извършва минимално разсъждение - максимум 2 стъпки. Използвайте го за изчисления, справки или прости въпроси. +**Ниско желание (бързо и фокусирано)** - За прости въпроси, където искате бързи, директни отговори. Моделът прави минимални разсъждения - максимум 2 стъпки. Използвайте това за изчисления, справки или прости въпроси. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Проучете с GitHub Copilot:** Отворете [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) и попитайте: -> - "Каква е разликата между ниско и високо ентусиазирани модели на подсказване?" -> - "Как XML таговете в подсказките помагат за структуриране на отговора на ИИ?" -> - "Кога да използвам модели за саморефлексия и кога директна инструкция?" +> 💡 **Изследвайте с GitHub Copilot:** Отворете [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) и попитайте: +> - "Каква е разликата между ниско и високо желание в моделите за подсказване?" +> - "Как XML таговете в подсказките помагат за структуриране на отговора на AI?" +> - "Кога трябва да използвам модели за саморефлексия срещу директна инструкция?" -**Високо ентусиазирано поведение (дълбоко и подробно)** - За сложни проблеми, при които искате изчерпателен анализ. Моделът изследва подробно и показва детайлни разсъждения. Използвайте го за системен дизайн, архитектурни решения или сложни изследвания. +**Високо желание (дълбоко и щателно)** - За сложни проблеми, където искате всеобхватен анализ. Моделът изследва задълбочено и показва подробни разсъждения. Използвайте това за системен дизайн, архитектурни решения или сложни изследвания. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Изпълнение на задачи (прогрес стъпка по стъпка)** - За многостепенни работни процеси. Моделът предоставя план предварително, описва всяка стъпка докато работи, после дава резюме. Използвайте го за миграции, реализации или всеки многостепенен процес. +**Изпълнение на задача (стъпка по стъпка напредък)** - За многостъпкови работни потоци. Моделът предоставя предварителен план, разказва всяка стъпка докато я изпълнява, след което дава резюме. Използвайте това за миграции, реализации или всеки многостъпков процес. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Подсказването с верига на мисленето изрично иска от модела да покаже процеса на разсъждение, подобрявайки точността при сложни задачи. Стъпковото разбиване помага както на хората, така и на ИИ да разберат логиката. +Подсказването във веригата на мисълта изрично изисква от модела да покаже процеса на разсъждение, което подобрява точността при сложни задачи. Разбивката стъпка по стъпка помага както на хората, така и на AI да разберат логиката. -> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Попитайте за този модел: -> - "Как бих адаптирал модела за изпълнение на задачи при дълготрайни операции?" -> - "Какви са най-добрите практики за структурирането на предговори към инструменти в продукционни приложения?" -> - "Как мога да заснема и визуализирам междинни актуализации на прогреса в UI?" +> **🤖 Опитайте с чат на [GitHub Copilot](https://github.com/features/copilot):** Попитайте за този модел: +> - "Как бих адаптирал модела за изпълнение на задача за дългосрочни операции?" +> - "Кои са добрите практики за структуриране на първоначални съобщения за инструменти в продукционни приложения?" +> - "Как мога да улавям и показвам междинни актуализации за напредък в UI?" -Диаграмата по-долу илюстрира този работен поток План → Изпълнение → Обобщение. +Диаграмата по-долу илюстрира тази последователност План → Изпълнение → Обобщение. -Модел за изпълнение на задачи +Модел за изпълнение на задача -*Работен поток План → Изпълнение → Обобщение за многостоеви задачи* +*Работен процес План → Изпълнение → Обобщение за многостъпкови задачи* -**Саморефлектиращ се код** - За генериране на код с продукционно качество. Моделът генерира код според продукционните стандарти с подходящо управление на грешки. Използвайте го при изграждане на нови функционалности или услуги. +**Саморефлектиращ код** - За генериране на код с качество за продукция. Моделът генерира код според продукционни стандарти с правилно обработване на грешки. Използвайте това при разработването на нови функции или услуги. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Диаграмата по-долу показва този итеративен цикъл за подобрение — генериране, оценка, идентифициране на слабости и усъвършенстване, докато кодът отговаря на продукционните стандарти. +Диаграмата по-долу показва този итеративен цикъл на подобрение — генериране, оценка, идентифициране на слабости и усъвършенстване докато кодът отговаря на продукционните стандарти. Цикъл на саморефлексия -*Итеративен цикъл за подобрение - генериране, оценка, идентифициране на проблеми, подобрение, повтаряне* +*Итеративен цикъл на подобрение - генериране, оценка, идентифициране на проблеми, усъвършенстване, повторение* -**Структуриран анализ** - За последователна оценка. Моделът преглежда кода чрез фиксирана рамка (правилност, практики, производителност, сигурност, поддръжка). Използвайте го за прегледи на код или оценки на качеството. +**Структуриран анализ** - За последователна оценка. Моделът преглежда кода, използвайки фиксирана рамка (коректност, практики, производителност, сигурност, поддържливост). Използвайте това за прегледи на код или оценки на качеството. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Попитайте за структуриран анализ: -> - "Как мога да персонализирам рамката за анализ за различни видове прегледи на код?" -> - "Кой е най-добрият начин да парсирам и програмирам действия въз основа на структуриран изход?" -> - "Как да гарантирам постоянство на нивата на сериозност в различни сесии на преглед?" +> **🤖 Опитайте с чат на [GitHub Copilot](https://github.com/features/copilot):** Попитайте за структурирания анализ: +> - "Как мога да персонализирам рамката за анализ за различни типове прегледи на код?" +> - "Кой е най-добрият начин да парсна и обработя структурирания изход програмно?" +> - "Как да осигуря последователни нива на тежест в различните сесии за преглед?" -Следната диаграма показва как тази структурирана рамка организира преглед на код в последователни категории с нива на сериозност. +Следната диаграма показва как тази структурирана рамка организира прегледа на код в последователни категории с нива на тежест. Модел за структуриран анализ -*Рамка за последователни прегледи на код с нива на сериозност* +*Рамка за последователни прегледи на код с нива на тежест* -**Многоходов чат** - За разговори, които се нуждаят от контекст. Моделът помни предишни съобщения и надгражда върху тях. Използвайте го за интерактивни сесии за помощ или сложни въпроси и отговори. +**Многоходов чат** - За разговори, които се нуждаят от контекст. Моделът помни предишни съобщения и надгражда върху тях. Използвайте това за интерактивни сесии за помощ или сложни въпроси и отговори. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Диаграмата по-долу визуализира как контекстът на разговора се натрупва с всяка обрата и как това се отнася до лимита на токени на модела. +Диаграмата по-долу визуализира как контекстът на разговора се акумулира с всяка стъпка и как се отнася към лимита на токени на модела. -Памет на контекст +Памет за контекст -*Как контекстът на разговора се натрупва с множество обрати до достигане на лимита на токени* -**Стъпка по стъпка обосновка** - За задачи, изискващи видима логика. Моделът показва явна обосновка за всяка стъпка. Използвайте това за математически задачи, логически пъзели или когато трябва да разберете мисловния процес. +*Как контекстът на разговора се натрупва през множество ходове до достигане на лимита на токени* + +**Разсъждение стъпка по стъпка** - За проблеми, изискващи видима логика. Моделът показва явни разсъждения за всяка стъпка. Използвайте това за математически задачи, логически пъзели или когато трябва да разберете процеса на мислене. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Диаграмата по-долу илюстрира как моделът разбива задачите на явни, номерирани логически стъпки. - -Step-by-Step Pattern +Диаграмата по-долу илюстрира как моделът разбива проблемите на явни, номерирани логични стъпки. -*Разбиване на задачи на явни логически стъпки* +Модел стъпка по стъпка +*Разчленяване на проблемите на явни логически стъпки* -**Ограничен изход** - За отговори с конкретни изисквания за формат. Моделът строго спазва правилата за формат и дължина. Използвайте това за обобщения или когато ви трябва точна структура на изхода. +**Ограничен изход** - За отговори със специфични изисквания за формат. Моделът стриктно спазва правилата за формат и дължина. Използвайте това за резюмета или когато имате нужда от прецизна структура на изхода. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Следващата диаграма показва как ограниченията насочват модела да създава изход, който строго се придържа към вашите изисквания за формат и дължина. +Следната диаграма показва как ограниченията насочват модела да произвежда изход, който строго се придържа към вашите изисквания за формат и дължина. Constrained Output Pattern -*Налагане на конкретни изисквания за формат, дължина и структура* +*Прилагане на специфични изисквания за формат, дължина и структура* -## Стартиране на приложението +## Стартирайте приложението -**Проверете разполагането:** +**Проверете разгръщането:** -Уверете се, че файлът `.env` съществува в кореновата директория с Azure данни за достъп (създаден по време на Модул 01). Стартирайте това от директорията на модула (`02-prompt-engineering/`): +Уверете се, че файлът `.env` съществува в кореновата директория с Azure идентификационни данни (създаден по време на Модул 01). Стартирайте това от директорията на модула (`02-prompt-engineering/`): **Bash:** ```bash @@ -442,27 +442,27 @@ cat ../.env # Трябва да показва AZURE_OPENAI_ENDPOINT, API_KEY, Get-Content ..\.env # Трябва да показва AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Стартиране на приложението:** +**Стартирайте приложението:** -> **Забележка:** Ако вече сте стартирали всички приложения с `./start-all.sh` от кореновата директория (както е описано в Модул 01), този модул вече работи на порт 8083. Можете да пропуснете командите за стартиране по-долу и да отидете директно на http://localhost:8083. +> **Забележка:** Ако вече стартирахте всички приложения с `./start-all.sh` от кореновата директория (както е описано в Модул 01), този модул вече работи на порт 8083. Можете да пропуснете командите за стартиране по-долу и директно да отидете на http://localhost:8083. -**Опция 1: Използване на Spring Boot Dashboard (Препоръчително за потребители на VS Code)** +**Вариант 1: Използване на Spring Boot Dashboard (Препоръчително за потребители на VS Code)** -Dev контейнерът включва разширението Spring Boot Dashboard, което предоставя визуален интерфейс за управление на всички Spring Boot приложения. Можете да го намерите в лентата с активности от лявата страна на VS Code (потърсете иконата на Spring Boot). +Разработващият контейнер включва разширението Spring Boot Dashboard, което осигурява визуален интерфейс за управление на всички Spring Boot приложения. Можете да го намерите в лентата с инструменти вляво във VS Code (потърсете иконата на Spring Boot). От Spring Boot Dashboard можете: -- Да видите всички налични Spring Boot приложения в пространството за работа -- Да стартирате/спирате приложения с един клик -- Да наблюдавате логовете на приложението в реално време -- Да следите статуса на приложението +- Да видите всички налични Spring Boot приложения в работната област +- Да стартирате/спирате приложения с едно кликване +- Да разглеждате логовете на приложението в реално време +- Да наблюдавате статусa на приложението -Просто кликнете върху бутона за пускане до "prompt-engineering", за да стартирате този модул, или стартирайте всички модули наведнъж. +Просто кликнете бутона за пускане до "prompt-engineering", за да стартирате този модул, или стартирайте всички модули наведнъж. Spring Boot Dashboard -*Spring Boot Dashboard във VS Code — стартиране, спиране и наблюдение на всички модули от едно място* +*Spring Boot Dashboard във VS Code — стартирайте, спирайте и наблюдавайте всички модули от едно място* -**Опция 2: Използване на shell скриптове** +**Вариант 2: Използване на shell скриптове** Стартирайте всички уеб приложения (модули 01-04): @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Двата скрипта автоматично зареждат променливи на средата от кореновия `.env` файл и ще компилират JAR файловете, ако не съществуват. +И двата скрипта автоматично зареждат променливи на средата от кореновия файл `.env` и ще изградят JAR файловете, ако те не съществуват. -> **Забележка:** Ако предпочитате да компилирате всички модули ръчно преди стартиране: +> **Забележка:** Ако предпочитате да изградите всички модули ръчно преди стартиране: > > **Bash:** > ```bash @@ -508,7 +508,7 @@ cd 02-prompt-engineering > mvn clean package -DskipTests > ``` -Отворете http://localhost:8083 във вашия браузър. +Отворете http://localhost:8083 в браузъра си. **За спиране:** @@ -526,7 +526,7 @@ cd .. && ./stop-all.sh # Всички модули cd ..; .\stop-all.ps1 # Всички модули ``` -## Снимки на приложението +## Скриншотове на приложението Ето основният интерфейс на модула за prompt engineering, където можете да експериментирате с всички осем шаблона един до друг. @@ -536,61 +536,61 @@ cd ..; .\stop-all.ps1 # Всички модули ## Изследване на шаблоните -Уеб интерфейсът ви позволява да експериментирате с различни стратегии за задаване на подсказки. Всеки шаблон решава различни проблеми - пробвайте ги, за да видите кога кой подход е най-добър. +Уеб интерфейсът ви позволява да експериментирате с различни стратегии за подаване на заявки. Всеки шаблон решава различни проблеми – пробвайте ги, за да видите кога кой подход блести. -> **Забележка: Поточно предаване срещу непоточно** — Във всяка страница на шаблона има два бутона: **🔴 Поточно предаване на отговора (в реално време)** и опция **Без поточно предаване**. Поточното предаване използва събития, изпращани от сървъра (SSE), за да показва токените в реално време, докато моделът ги генерира, така че веднага виждате напредъка. Опцията без поточно предаване изчаква целия отговор преди да го изведе. При подсказки, които изискват дълбоко разсъждение (например, Висока настойчивост, Саморефлектиращ код), непоточното извикване може да отнеме много време – понякога минути – без видима обратна връзка. **Използвайте поточно предаване при експерименти с комплексни подсказки**, за да виждате работата на модела и да избегнете впечатлението за изтичане на времето. +> **Забележка: Поточно предаване срещу без поточно предаване** — Всяка страница на шаблона предлага два бутона: **🔴 Stream Response (Live)** и опция за **Не потоково предаване**. Поточното предаване използва Server-Sent Events (SSE), за да показва токени в реално време, докато моделът ги генерира, така че виждате напредъка веднага. Опцията за не потоково предаване изчаква цялата отговор преди да я покаже. За заявки, които изискват дълбоко разсъждение (например High Eagerness, Self-Reflecting Code), не потоковото извикване може да отнеме много време – понякога минути – без видима обратна връзка. **Използвайте поточното при експерименти с комплексни заявки**, за да видите модела в действие и да избегнете впечатлението, че заявката е изтекла. > -> **Забележка: Изисквания за браузъра** — Функцията за поточно предаване използва Fetch Streams API (`response.body.getReader()`), което изисква пълен браузър (Chrome, Edge, Firefox, Safari). Тя **не работи** във вградения Simple Browser на VS Code, тъй като неговият webview не поддържа ReadableStream API. Ако използвате Simple Browser, бутоните без поточно предаване ще работят нормално – засегнати са само бутоните за поточно предаване. Отворете `http://localhost:8083` в външен браузър за пълно изживяване. +> **Забележка: Изискване за браузър** — Функцията за поточно предаване използва Fetch Streams API (`response.body.getReader()`), който изисква пълен браузър (Chrome, Edge, Firefox, Safari). Той **не работи** в Simple Browser на VS Code, тъй като неговият webview не поддържа ReadableStream API. Ако използвате Simple Browser, бутоните за не потоково ще работят нормално — засегнати са само бутоните за поточно предаване. Отворете `http://localhost:8083` в външен браузър за пълен опит. -### Ниска срещу висока настойчивост +### Ниска срещу висока активност (Eagerness) -Задайте прост въпрос като "Колко е 15% от 200?" с Ниска настойчивост. Ще получите мигновен, директен отговор. Сега задайте нещо сложно като "Проектиране на кешираща стратегия за API с висок трафик" с Висока настойчивост. Натиснете **🔴 Поточно предаване (в реално време)** и наблюдавайте детайлното разсъждение на модела, появяващо се токен по токен. Същият модел, същата структура на въпроса – но подсказката му казва колко да мисли. +Задайте прост въпрос като "Какво е 15% от 200?" с Ниска активност. Ще получите мигновен, директен отговор. Сега задайте нещо сложно като "Проектирайте стратегия за кеширане за API с голям трафик" с Висока активност. Кликнете **🔴 Stream Response (Live)** и наблюдавайте подробните разсъждения на модела, изписани токен по токен. Същият модел, същата структура на въпроса - но подканата указва колко мислене да използва. -### Изпълнение на задачи (въвеждащи текстове за инструменти) +### Изпълнение на задачи (въведение на инструменти) -Многостъпковите работни потоци се възползват от предварително планиране и разказване на напредъка. Моделът описва какво ще направи, разказва всяка стъпка, след което обобщава резултатите. +Работните потоци с много стъпки печелят от предварително планиране и разказ за напредъка. Моделът очертава какво ще прави, разказва за всяка стъпка, след което обобщава резултатите. -### Саморефлектиращ код +### Саморефлектиращ се код -Опитайте „Създай услуга за валидация на имейл“. Вместо просто да генерира код и да спре, моделът генерира, оценява според критерии за качество, идентифицира слабости и подобрява кода. Ще видите итерации, докато кодът достигне производствен стандарт. +Опитайте "Създайте услуга за валидация на имейл". Вместо просто да генерира код и да спре, моделът създава, оценява по критерии за качество, идентифицира слабости и подобрява. Ще видите итерации докато кодът отговаря на производствените стандарти. ### Структуриран анализ -Прегледите на код изискват последователни рамки за оценка. Моделът анализира кода, използвайки фиксирани категории (коректност, практики, производителност, сигурност) със степени на тежест. +Прегледите на код изискват последователни критерии за оценка. Моделът анализира кода с фиксирани категории (коректност, практики, производителност, сигурност) с нива на тежест. -### Многоходов чат +### Разговор с много ходове -Попитайте „Какво е Spring Boot?“, после веднага продължете с „Покажи ми пример“. Моделът помни първия въпрос и ви дава конкретен пример със Spring Boot. Без памет, този втори въпрос би бил твърде общ. +Попитайте "Какво е Spring Boot?" и веднага след това "Покажи ми пример". Моделът помни първия ви въпрос и дава пример за Spring Boot специално за вас. Без памет вторият въпрос щеше да е твърде общ. -### Стъпка по стъпка обосновка +### Разсъждение стъпка по стъпка -Изберете математическа задача и я опитайте както с „Стъпка по стъпка“, така и с Ниска настойчивост. Ниската настойчивост ви дава само отговор – бързо, но неясно. Стъпка по стъпка ви показва всяко изчисление и решение. +Изберете математическа задача и опитайте както с Разсъждение стъпка по стъпка, така и с Ниска активност. Ниската активност просто ви дава отговор - бързо, но неясно. Разсъждението стъпка по стъпка показва всяко изчисление и решение. ### Ограничен изход -Когато ви трябват конкретни формати или брой думи, този шаблон налага строго спазване. Опитайте да генерирате обобщение с точно 100 думи в списъчен формат. +Когато имате нужда от специфични формати или брой думи, този шаблон налага строго спазване. Опитайте да генерирате резюме с точно 100 думи във формат на точки. -## Това, което наистина учите +## Какво всъщност учите -**Разсъждението променя всичко** +**Усилието в разсъждението променя всичко** -GPT-5.2 ви позволява да контролирате изчислителните усилия чрез вашите подсказки. Ниското усилие означава бързи отговори с минимално изследване. Високото усилие означава, че моделът отделя време за дълбоко мислене. Учите се да съобразявате усилията с комплексността на задачата – не пропилявайте време на прости въпроси, но и не бързайте с комплексните решения. +GPT-5.2 ви позволява да контролирате изчислителното усилие чрез вашите заявки. Ниско усилие означава бързи отговори с минимално изследване. Високото усилие означава, че моделът отделя време за дълбоко мислене. Вие се учите да съчетавате усилието с комплексността на задачата – не губете време с лесни въпроси, но не бързайте и с комплексни решения. **Структурата насочва поведението** -Забелязахте ли XML таговете в подсказките? Те не са декоративни. Моделите следват структурирани инструкции по-надеждно от свободен текст. Когато ви трябват многостъпкови процеси или сложна логика, структурата помага на модела да проследява къде се намира и какво следва. Диаграмата по-долу разбива добре структурирана подсказка, показвайки как тагове като ``, ``, ``, ``, и `` организират инструкциите ви в ясни секции. +Забелязвате XML таговете в заявките? Те не са декоративни. Моделите следват структурирани инструкции по-надеждно от свободен текст. Когато имате нужда от многостъпкови процеси или сложна логика, структурата помага на модела да следи къде е и какво следва. Диаграмата по-долу разглобява добре структуриран запрос, показвайки как тагове като ``, ``, ``, `` и `` организират вашите инструкции в ясни секции. Prompt Structure -*Анатомия на добре структурирана подсказка с ясни секции и XML-стил организация* +*Анатомия на добре структуриран запрос с ясни раздели и XML стил организация* **Качество чрез самооценка** -Шаблоните за саморефлексия работят чрез явни критерии за качество. Вместо да се надявате моделът „да го направи правилно“, вие му кажете точно какво означава „правилно“: коректна логика, обработка на грешки, производителност, сигурност. Моделът може да оцени собствените си резултати и да се подобри. Така превръщате генерирането на код от лотария в процес. +Шаблоните за саморефлексия работят като правят критериите за качество явни. Вместо да се надявате, че моделът "прави правилно", вие му казвате точно какво означава "правилно": коректна логика, обработка на грешки, производителност, сигурност. След това моделът може да оцени собствения си изход и да го подобри. Така генерацията на код става процес, а не лотария. **Контекстът е ограничен** -Многоходовите разговори се реализират чрез включване на история на съобщенията във всяка заявка. Но има лимит – всеки модел има максимален брой токени. С разрастването на разговорите трябва да използвате стратегии за съхранение на релевантен контекст, без да достигате лимита. Този модул показва как работи паметта; по-късно ще научите кога да обобщавате, кога да забравяте и кога да извличате. +Разговорите с много ходове работят, като включват история на съобщенията с всяка заявка. Но има лимит – всеки модел има максимален брой токени. С нарастването на разговорите ще трябва да разработвате стратегии за поддържане на релевантен контекст без да достигате тавана. Този модул показва как работи паметта; по-късно ще научите кога да обобщавате, кога да забравяте и кога да извличате. ## Следващи стъпки @@ -598,11 +598,11 @@ GPT-5.2 ви позволява да контролирате изчислите --- -**Навигация:** [← Предишен: Модул 01 - Въведение](../01-introduction/README.md) | [Обратно към Началото](../README.md) | [Следващ: Модул 03 - RAG →](../03-rag/README.md) +**Навигация:** [← Предишен: Модул 01 - Въведение](../01-introduction/README.md) | [Обратно към началната страница](../README.md) | [Следващ: Модул 03 - RAG →](../03-rag/README.md) --- -**Отказ от отговорност**: -Този документ е преведен с помощта на AI преводаческа услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. +**Отказ от отговорност**: +Този документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. \ No newline at end of file diff --git a/translations/bg/03-rag/README.md b/translations/bg/03-rag/README.md index 0ca0577cf..d2dcb079b 100644 --- a/translations/bg/03-rag/README.md +++ b/translations/bg/03-rag/README.md @@ -1,144 +1,143 @@ -# Модул 03: RAG (Извличане с Подобрено Генериране) +# Модул 03: RAG (Генериране с подобряване чрез извличане) ## Съдържание -- [Видео обяснение](../../../03-rag) -- [Какво ще научите](../../../03-rag) -- [Предварителни условия](../../../03-rag) -- [Разбиране на RAG](../../../03-rag) - - [Кой RAG подход използва този урок?](../../../03-rag) -- [Как работи](../../../03-rag) - - [Обработка на документи](../../../03-rag) - - [Създаване на вграждания](../../../03-rag) - - [Семантично търсене](../../../03-rag) - - [Генериране на отговори](../../../03-rag) -- [Стартирайте приложението](../../../03-rag) -- [Използване на приложението](../../../03-rag) - - [Качване на документ](../../../03-rag) - - [Задаване на въпроси](../../../03-rag) - - [Проверка на източниците](../../../03-rag) - - [Експериментиране с въпроси](../../../03-rag) -- [Ключови концепции](../../../03-rag) - - [Стратегия за раздробяване](../../../03-rag) - - [Оценки за сходство](../../../03-rag) - - [Съхранение в памет](../../../03-rag) - - [Управление на контекстното пространство](../../../03-rag) -- [Кога RAG е важен](../../../03-rag) -- [Следващи стъпки](../../../03-rag) - -## Видео обяснение - -Гледайте тази жива сесия, която обяснява как да започнете с този модул: - -RAG с LangChain4j - Жива сесия +- [Видео ръководство](#видео-ръководство) +- [Какво ще научите](#какво-ще-научите) +- [Предварителни изисквания](#предварителни-изисквания) +- [Разбиране на RAG](#разбиране-на-rag) + - [Кой RAG подход използва това ръководство?](#кой-rag-подход-използва-това-ръководство) +- [Как работи](#как-работи) + - [Обработка на документи](#обработка-на-документи) + - [Създаване на вложения](#създаване-на-вложения) + - [Семантично търсене](#семантично-търсене) + - [Генериране на отговори](#генериране-на-отговор) +- [Стартиране на приложението](#стартиране-на-приложението) +- [Използване на приложението](#използване-на-приложението) + - [Качване на документ](#качване-на-документ) + - [Задаване на въпроси](#задаване-на-въпроси) + - [Проверка на източниците](#проверка-на-изходните-препратки) + - [Експериментиране с въпроси](#експериментирайте-с-въпроси) +- [Ключови концепции](#ключови-понятия) + - [Стратегия за разбиване на части](#стратегия-за-разделяне-на-части) + - [Оценки за подобие](#оценки-за-прилика) + - [Съхранение в паметта](#съхранение-в-памет) + - [Управление на контекстния прозорец](#управление-на-контекстния-прозорец) +- [Кога RAG е важен](#кога-rag-има-значение) +- [Следващи стъпки](#следващи-стъпки) + +## Видео ръководство + +Гледайте тази сесия наживо, която обяснява как да започнете с този модул: + +RAG with LangChain4j - Live Session ## Какво ще научите -В предишните модули научихте как да водите разговори с AI и как ефективно да структурирате своите подкани. Но има основно ограничение: езиковите модели знаят само това, което са научили по време на обучението. Те не могат да отговарят на въпроси за политиките на вашата компания, вашата проектна документация или за каквато и да е информация, на която не са били обучени. +В предишните модули научихте как да водите разговори с AI и как ефективно да структурирате заявките си. Но има основно ограничение: езиковите модели знаят само това, което са научили по време на обучението си. Те не могат да отговарят на въпроси за политиките на вашата компания, документацията на проекта или друга информация, която не е била включена в тяхното обучение. -RAG (Извличане с Подобрено Генериране) решава този проблем. Вместо да се опитвате да "научите" модела на вашата информация (което е скъпо и непрактично), вие му давате възможността да търси в документите ви. Когато някой зададе въпрос, системата намира релевантна информация и я включва в подкана. След това моделът отговаря на базата на този извлечен контекст. +RAG (Генериране с подобряване чрез извличане) решава този проблем. Вместо да се опитвате да научите модела на вашата информация (което е скъпо и непрактично), вие му давате възможността да търси във вашите документи. Когато някой зададе въпрос, системата намира релевантна информация и я включва в заявката. След това моделът отговаря въз основа на този извлечен контекст. -Мислете за RAG като за предоставяне на модела на референтна библиотека. Когато зададете въпрос, системата: +Мислете за RAG като за предоставяне на модела на справочна библиотека. Когато зададете въпрос, системата прави следното: -1. **Потребителски въпрос** - Вие задавате въпрос -2. **Вграждане** - Преобразува въпроса ви във вектор -3. **Векторно търсене** - Намира сходни части от документи -4. **Сглобяване на контекста** - Добавя релевантните части в подкана -5. **Отговор** - LLM генерира отговор въз основа на контекста +1. **Потребителски въпрос** – Вие задавате въпрос +2. **Вложение** – Преобразува въпроса в вектор +3. **Векторно търсене** – Намира подобни части от документи +4. **Събиране на контекст** – Добавя релевантни части към заявката +5. **Отговор** – LLM генерира отговор въз основа на контекста -Това основава отговорите на модела на вашите реални данни, вместо да разчита само на знанията от обучението си или да измисля отговори. +Това оснoва отговорите на модела на вашите действителни данни, вместо да разчита само на обучителната си информация или да измисля отговори. -## Предварителни условия +## Предварителни изисквания -- Завършен [Модул 00 - Бърз старт](../00-quick-start/README.md) (за примера Easy RAG, използван по-нататък в този модул) -- Завършен [Модул 01 - Въведение](../01-introduction/README.md) (пуснати в експлоатация Azure OpenAI ресурси, включително embedding модела `text-embedding-3-small`) -- `.env` файл в кореновата директория с Azure креденшъли (създаден чрез `azd up` в Модул 01) +- Завършен [Модул 01 - Въведение](../01-introduction/README.md) (разположени Azure OpenAI ресурси, включително модел за вложение `text-embedding-3-small`) +- Файл `.env` в главната директория с Azure данни за достъп (създаден от `azd up` в Модул 01) -> **Забележка:** Ако не сте завършили Модул 01, първо следвайте инструкциите за разгръщане там. Командата `azd up` разгръща както GPT чат модела, така и embedding модела, използвани в този модул. +> **Бележка:** Ако не сте завършили Модул 01, първо следвайте инструкциите за разполагане там. Командата `azd up` разполага както GPT чат модела, така и модела за вложения, използван в този модул. ## Разбиране на RAG -Диаграмата по-долу илюстрира основната идея: вместо да разчита само на обучителните данни на модела, RAG му дава библиотека с вашите документи, които да консултира преди да генерира всеки отговор. +Диаграмата по-долу илюстрира основната концепция: вместо да разчита само на данните от обучението на модела, RAG му предоставя справочната библиотека с вашите документи, които да преглежда преди да генерира всеки отговор. -Какво е RAG +What is RAG -*Тази диаграма показва разликата между стандартен LLM (който гадае от обучителните данни) и LLM, подобрен с RAG (който първо проверява вашите документи).* +*Тази диаграма показва разликата между стандартен LLM (който гадае от обучителни данни) и LLM с RAG подобрение (който първо преглежда вашите документи).* -Ето как се свързват частите от начало до край. Въпросът на потребителя преминава през четири етапа — вграждане, векторно търсене, сглобяване на контекста и генериране на отговора — като всеки следващ се изгражда върху предишния: +Ето как частите се свързват от край до край. Въпросът на потребителя преминава през четири етапа — вграждане, векторно търсене, събиране на контекст и генериране на отговор — като всеки етап надгражда предишния: -Архитектура на RAG +RAG Architecture -*Тази диаграма показва пълния RAG поток — потребителският въпрос преминава през вграждане, векторно търсене, сглобяване на контекста и генериране на отговор.* +*Тази диаграма показва край до край RAG процеса — въпросът на потребителя преминава през вграждане, векторно търсене, събиране на контекст и генериране на отговор.* -Останалата част от този модул разглежда всеки етап в детайли, с код за стартиране и модификация. +Останалата част от този модул разглежда всеки етап подробно, с код, който можете да стартирате и модифицирате. -### Кой RAG подход използва този урок? +### Кой RAG подход използва това ръководство? -LangChain4j предлага три начина за имплементиране на RAG, всеки с различно ниво на абстракция. По-долу е диаграма, която ги сравнява: +LangChain4j предлага три начина за реализиране на RAG, всеки с различно ниво на абстракция. Диаграмата по-долу ги сравнява един до друг: -Три подхода за RAG в LangChain4j +Three RAG Approaches in LangChain4j -*Тази диаграма сравнява трите подхода за RAG в LangChain4j — Easy, Native и Advanced — показвайки ключовите им компоненти и кога да се използва всеки.* +*Тази диаграма сравнява трите подхода RAG в LangChain4j — Easy, Native и Advanced — показвайки ключовите им компоненти и кога да се използват.* | Подход | Какво прави | Компромис | |---|---|---| -| **Easy RAG** | Свързва всичко автоматично чрез `AiServices` и `ContentRetriever`. Аннотирате интерфейс, прикачвате извличач и LangChain4j се грижи за вграждането, търсенето и сглобяването на подкани зад кулисите. | Минимален код, но не виждате какво се случва на всеки етап. | -| **Native RAG** | Вие извиквате embedding модела, търсите в хранилището, изграждате подкана и генерирате отговора сами — една явна стъпка наведнъж. | Повече код, но всеки етап е видим и модифицируем. | -| **Advanced RAG** | Използва рамката `RetrievalAugmentor` с плъгини за трансформатори на заявки, маршрутизатори, преподреждачи и инжектори на съдържание за производствени потоци. | Максимална гъвкавост, но значително по-сложен код. | +| **Easy RAG** | Свързва всичко автоматично чрез `AiServices` и `ContentRetriever`. Аннотирате интерфейс, прикачвате търсачка, а LangChain4j се грижи за вграждане, търсене и събиране на заявка на заден план. | Минимален код, но не виждате какво се случва на всеки етап. | +| **Native RAG** | Вие извиквате модела за вграждане, търсите в хранилището, изграждате заявката и генерирате отговора сами — една изрична стъпка наведнъж. | Повече код, но всеки етап е видим и модифицируем. | +| **Advanced RAG** | Използва `RetrievalAugmentor` рамка с плъгин трансформъри на заявки, маршрутизатори, пренареждачи и инжектори на съдържание за продукционни решения. | Максимална гъвкавост, но значително по-сложна. | -**Този урок използва Native подхода.** Всеки етап от RAG потока — вграждането на заявката, търсенето в векторното хранилище, сглобяването на контекста и генерирането на отговора — е изрично изписан в [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Това е умишлено: като образователен ресурс е по-важно да виждате и разбирате всеки етап, отколкото да има минимален код. Когато вече сте наясно с това как се свързват частите, може да преминете към Easy RAG за бързи прототипи или Advanced RAG за производствени системи. +**Това ръководство използва Native подхода.** Всеки етап от RAG процеса — вложение на заявката, търсене в векторното хранилище, събиране на контекста и генериране на отговор — е изрично написан в [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Това е умишлено: като учебен ресурс е по-важно да виждате и разбирате всеки етап, отколкото кодът да е максимално съкратен. Когато се почувствате уверени как работят частите, можете да преминете към Easy RAG за бързи прототипи или Advanced RAG за продукционни системи. -> **💡 Вече виждали Easy RAG в действие?** Модулът [Бърз старт](../00-quick-start/README.md) включва пример за Въпроси и Отговори с Документ ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), който използва Easy RAG подхода — LangChain4j автоматично обработва вграждането, търсенето и сглобяването на подкана. Този модул прави следващата крачка, като отваря този поток така, че да видите и управлявате всеки етап сами. +> **💡 Любопитни за Easy RAG?** LangChain4j също предлага *Easy RAG* подход, при който `AiServices` и `ContentRetriever` автоматично се грижат за вграждането, търсенето и събирането на заявка. Този модул тръгва по по-изричния път — разкъсва този процес така, че да виждате и контролирате всеки етап сами. -Диаграмата по-долу показва Easy RAG потока от този пример в Бърз старт. Забележете как `AiServices` и `EmbeddingStoreContentRetriever` скриват цялата сложност — зареждате документ, прикачвате извличач и получавате отговори. Native подходът в този модул разкрива всеки скрит етап: +Диаграмата по-долу показва Easy RAG процеса. Забележете как `AiServices` и `EmbeddingStoreContentRetriever` скриват цялата сложност — зареждате документ, прикачвате търсачка и получавате отговори. Native подходът в този модул разкрива всички тези скрити стъпки: -Easy RAG потока - LangChain4j +Easy RAG Pipeline - LangChain4j -*Тази диаграма показва Easy RAG потока от `SimpleReaderDemo.java`. Сравнете го с Native подхода в този модул: Easy RAG скрива вграждането, търсенето и сглобяването на подкана зад `AiServices` и `ContentRetriever` — зареждате документ, прикачвате извличач и получавате отговори. Native подходът в този модул изважда тези етапи навън, така че вие да извиквате всеки (вграждане, търсене, сглобяване на контекст, генериране) сами, давайки ви пълна видимост и контрол.* +*Тази диаграма показва Easy RAG процеса. Сравнете го с Native подхода, използван в този модул: Easy RAG скрива вграждането, извличането и събирането на заявка зад `AiServices` и `ContentRetriever` — зареждате документ, прикачвате търсачка и получавате отговори. Native подходът в този модул разкрива този процес, така че сами да извиквате всеки етап (вграждане, търсене, събиране на контекст, генериране) и да имате пълен контрол и видимост.* ## Как работи -RAG потока в този модул се разбива на четири етапа, които се изпълняват последователно всеки път, когато потребител зададе въпрос. Първо, каченият документ се **парсира и раздробява** на управляеми части. Тези парчета след това се преобразуват в **векторни вграждания** и се съхраняват, за да могат да бъдат сравнявани математически. Когато пристигне заявка, системата извършва **семантично търсене**, за да намери най-релевантните части, и накрая ги подава като контекст към LLM за **генериране на отговор**. По-долу са разгледани всеки от етапите с реален код и диаграми. Нека започнем от първата стъпка. +RAG процесът в този модул се разбива на четири етапа, които се изпълняват последователно всеки път, когато потребител зададе въпрос. Първо, каченият документ се **парсира и разбива на части** по размер, удобен за модела. Тези части се преобразуват в **векторни вграждания** и се съхраняват, за да могат да се сравняват математически. Когато пристигне заявка, системата извършва **семантично търсене**, за да намери най-релевантните части, и накрая ги подава като контекст към LLM за **генериране на отговор**. По-долу разглеждаме всеки етап с код и диаграми. Нека започнем с първата стъпка. ### Обработка на документи [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Когато качите документ, системата го парсира (PDF или обикновен текст), прикачва метаданни като името на файла и след това го разбива на части — по-малки сегменти, които удобно се побират в контекстното пространство на модела. Тези части леко се припокриват, за да не се губи контекст на границите. +Когато качите документ, системата го парсира (PDF или обикновен текст), прикачва метаданни като име на файл и след това го разбива на части — по-малки сегменти, които се побират удобно в контекстния прозорец на модела. Тези части се припокриват леко, за да не се загуби контекст на границите. ```java -// Анализирайте качения файл и го опаковайте в LangChain4j документ +// Анализирайте качения файл и го опаковайте в LangChain4j Документ Document document = Document.from(content, metadata); -// Разделете на блокове от 300 токена с припокриване от 30 токена +// Разделете на парчета от 300 токена с припокриване от 30 токена DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` + +Диаграмата по-долу показва как това работи визуално. Забележете как всяка част споделя някои токени със съседните — припокриването от 30 токена гарантира, че няма да се загуби важна информация между частите: -Диаграмата по-долу показва това визуално. Забележете как всяка част споделя някои токени със съседните — 30 токена припокриване гарантират, че няма важен контекст, който да попадне между пукнатините: +Document Chunking -Раздробяване на документ +*Тази диаграма показва разбиване на документ на 300-токенови части с припокриване от 30 токена, което запазва контекста на границите между частите.* -*Тази диаграма показва как документ се разделя на 300-токенни парчета с припокриване от 30 токена, запазвайки контекста на границите.* +> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) и задайте: +> - "Как LangChain4j разбива документи на части и защо припокриването е важно?" +> - "Какъв е оптималният размер на частите за различни типове документи и защо?" +> - "Как да обработвам документи на различни езици или със специално форматиране?" -> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) и попитайте: -> - "Как LangChain4j разделя документи на парчета и защо припокритието е важно?" -> - "Кой е оптималният размер на парчетата за различни видове документи и защо?" -> - "Как да се справя с документи на няколко езика или със специално форматиране?" - -### Създаване на вграждания +### Създаване на вложения [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Всяко парче се превръща в числова репрезентация, наречена embedding — по същество конвертор от значение към числа. Embedding моделът не е "умен" като чат модел; той не може да следва инструкции, да разсъждава или да отговаря на въпроси. Това, което може, е да преобразува текст в математическо пространство, където сходните значения се намират близо едно до друго — "кола" близо до "автомобил", "политика за връщане" близо до "върнете ми парите". Мислете за чат модела като за човек, с когото може да разговаряте; embedding моделът е изключително добър файлова система. +Всяка част се преобразува в числово представяне, наречено вложение — същността на конвертор от значение в числа. Моделът за вграждане не е "умен" по начина, по който е чат моделът; той не следва инструкции, не разсъждава и не отговаря на въпроси. Това, което може да направи, е да превърне текст в математическо пространство, където сходните значения се групират близо едно до друго — "кола" близо до "автомобил," "политика за възстановяване" близо до "върнете ми парите." Мислете за чат модела като за човек, с когото можете да разговаряте; моделът за вграждане е ненадмината система за подреждане на файлове. -Диаграмата по-долу визуализира тази концепция — текст влиза, числови вектори излизат, а подобни значения произвеждат сходни вектори: +Диаграмата по-долу визуализира тази концепция — текстът влиза, излизат числови вектори, а сходните значения създават близки вектори: -Концепция за embedding модел +Embedding Model Concept -*Тази диаграма показва как embedding модел преобразува текст в числови вектори, като поставя сходни значения — например "кола" и "автомобил" — близо един до друг във векторното пространство.* +*Тази диаграма показва как моделът за вграждане преобразува текст в числови вектори, като поставя сходни значения — като "кола" и "автомобил" — близо в пространството на векторите.* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` + +Диаграмата на класовете по-долу показва двата отделни потока в RAG процеса и класовете на LangChain4j, които ги реализират. **Потокът на вграждане** (изпълнява се веднъж при качване) разбива документа, вгражда частите и ги съхранява чрез `.addAll()`. **Потокът на заявка** (изпълнява се всеки път, когато потребител зададе въпрос) вгражда въпроса, търси в хранилището чрез `.search()`, и предава съответния контекст към чат модела. Двата потока се срещат в споделения интерфейс `EmbeddingStore`: -Класовата диаграма по-долу показва двата отделни потока в RAG pipeline и LangChain4j класовете, които ги имплементират. **Потокът на вмъкване** (върши се веднъж при качване) раздробява документа, вгражда парчетата и ги съхранява чрез `.addAll()`. **Потокът на заявки** (върши се всеки път при въпрос) вгражда въпроса, търси в хранилището чрез `.search()` и подава съвпадналия контекст към чат модела. И двата потока се срещат в споделения интерфейс `EmbeddingStore`: - -Класове на LangChain4j за RAG +LangChain4j RAG Classes -*Тази диаграма показва двата потока в RAG pipeline — вмъкване и заявки — и как те се свързват чрез общия EmbeddingStore.* +*Тази диаграма показва двата потока в RAG процеса — вграждане и заявка — и как те се свързват през споделен EmbeddingStore.* -След като embedding-ите се съхранят, сходното съдържание естествено се групира заедно във векторното пространство. Визуализацията по-долу показва как документи по свързани теми се разполагат като близки точки, което прави semантичното търсене възможно: +След като вградените части се съхранят, сходното съдържание естествено се групира заедно в векторното пространство. Визуализацията по-долу показва как документи с близки теми се групират като съседни точки, което прави възможно семантичното търсене: -Пространство на векторни embedding-и +Vector Embeddings Space -*Тази визуализация показва как свързани документи се групират заедно в 3D векторно пространство, като теми като Техническа документация, Правила за бизнес и Често задавани въпроси образуват различни групи.* +*Тази визуализация показва как свързаните документи се групират заедно в 3D векторното пространство, като теми като Техническа документация, Бизнес правила и Често задавани въпроси формират отделни групи.* -Когато потребител търси, системата следва четири стъпки: вмъква документите веднъж, вмъква заявката при всяко търсене, сравнява векторите на заявката с всички съхранени вектори чрез косинусова прилика и връща топ-K най-високонаблюдавани парчета. Диаграмата по-долу преминава през всяка стъпка и участващите LangChain4j класове: +Когато потребител търси, системата следва четири стъпки: вгражда документите веднъж, вгражда заявката при всяко търсене, сравнява вектора на заявката с всички съхранени вектори чрез косинусна прилика, и връща топ-K частите с най-висок резултат. Диаграмата по-долу преминава през всяка стъпка и свързаните LangChain4j класове: -Стъпки при embedding търсене +Embedding Search Steps -*Тази диаграма показва четиристъпковия процес на embedding търсене: вмъкване на документи, вмъкване на заявка, сравняване на вектори с косинусова прилика и връщане на топ-K резултати.* +*Тази диаграма показва четиристъпковия процес на вграждане за търсене: вграждане на документи, вграждане на заявка, сравнение на вектори чрез косинусна прилика и връщане на топ-K резултати.* ### Семантично търсене [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Когато зададете въпрос, той също се превръща във вграждане. Системата сравнява embedding-а на въпроса ви с embedding-ите на всички парчета от документи. Намира парчетата с най-сходни значения - не просто съвпадение на ключови думи, а реална семантична прилика. +Когато зададете въпрос, той също се преобразува във векторна форма. Системата сравнява вграждането на вашия въпрос с тези на всички части от документите. Намира частите със сходно значение - не само съвпадащи ключови думи, а реална семантична прилика. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` + +Диаграмата по-долу противопоставя семантичното търсене на традиционното търсене по ключови думи. Търсенето по ключова дума за "превозно средство" пропуска част за "коли и камиони", но семантичното търсене разбира, че те значат едно и също нещо и го връща като високорейтингов резултат: -Диаграмата по-долу контрастира семантичното търсене с традиционно търсене по ключови думи. Търсене по ключова дума "превозно средство" пропуска парче за "коли и камиони", но семантичното търсене разбира, че това значи едно и също и връща този резултат с висока оценка: +Semantic Search -Семантично търсене +*Тази диаграма сравнява търсенето по ключови думи със семантичното търсене, показвайки как семантичното извлича концептуално свързано съдържание, дори когато точните ключови думи се различават.* -*Тази диаграма сравнява търсене по ключови думи със семантично търсене, показвайки как семантичното търсене връща концептуално свързано съдържание, дори когато точните ключови думи са различни.* -Под капака, сходството се измерва чрез косинусова близост — по същество питаме "дали тези две стрелки сочат в една и съща посока?" Два откъса могат да използват напълно различни думи, но ако означават едно и също нещо, техните вектори сочат по един и същи начин и резултатът е близо до 1.0: +Под капака приличието се измерва чрез косинусна прилика — основно, питаме се дали "две стрелки сочат в една и съща посока?" Две части могат да използват напълно различни думи, но ако значат едно и също, техните вектори сочат в същата посока и оценката им е близка до 1.0: Cosine Similarity +*Тази диаграма илюстрира косинусната прилика като ъгъл между векторите на вградените представяния — по-успоредни вектори имат резултат, по-близък до 1.0, което показва по-висока семантична прилика.* -*Тази диаграма илюстрира косинусовата близост като ъгъл между векторите на вграждането — по-прилежащите вектори получават резултат, близък до 1.0, което показва по-високо семантично сходство.* - -> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) и задайте: -> - "Как работи търсенето на сходство с embeddings и какво определя резултата?" -> - "Какъв праг за сходство да използвам и как той влияе на резултатите?" -> - "Как да се справя с случаи, когато не са намерени релевантни документи?" +> **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) и попитайте: +> - "Как работи търсенето по прилика с вградени представяния и какво определя резултата?" +> - "Какъв праг за прилика трябва да използвам и как това влияе на резултатите?" +> - "Как да постъпя, когато не бъдат намерени релевантни документи?" ### Генериране на отговор [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Най-релевантните откъси се събират в структурирана команда, която включва явни инструкции, извлечения контекст и въпроса на потребителя. Моделът чете тези конкретни откъси и отговаря въз основа на тази информация — той може да използва само това, което е пред него, което предотвратява халюцинации. +Най-релевантните частички се събират в структуриран подкана, която включва явни инструкции, извлечения контекст и въпроса на потребителя. Моделът чете точно тези частички и отговаря въз основа на тази информация — може да използва само това, което е пред него, което предотвратява халюцинации. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Диаграмата по-долу показва този процес — откъсите с най-висок резултат от търсенето се вмъкват в шаблона на подканата, а `OpenAiOfficialChatModel` генерира базиран на контекста отговор: +Диаграмата по-долу показва този процес в действие — топ резултатните частички от стъпката на търсене се вмъкват в шаблона на подкана, а `OpenAiOfficialChatModel` генерира обоснован отговор: Context Assembly -*Тази диаграма показва как откъсите с най-високи резултати се събират в структурирана подканваща команда, позволявайки на модела да генерира обоснован отговор от вашите данни.* +*Тази диаграма показва как топ резултатните частички се събират в структуриран подкана, позволявайки на модела да генерира обоснован отговор от вашите данни.* ## Стартиране на приложението **Проверете разгръщането:** -Уверете се, че файлът `.env` съществува в коренната директория с Azure данни за достъп (създаден по време на Модул 01). Стартирайте това от директорията на модула (`03-rag/`): +Уверете се, че файлът `.env` съществува в основната директория с Azure креденшъли (създадени по време на Модул 01). Стартирайте това от директорията на модула (`03-rag/`): **Bash:** ```bash @@ -261,37 +260,37 @@ Get-Content ..\.env # Трябва да показва AZURE_OPENAI_ENDPOINT, A **Стартирайте приложението:** -> **Забележка:** Ако вече сте стартирали всички приложения чрез `./start-all.sh` от коренната директория (както е описано в Модул 01), този модул вече работи на порт 8081. Можете да пропуснете командите за стартиране по-долу и да отидете директно на http://localhost:8081. +> **Забележка:** Ако вече сте стартирали всички приложения чрез `./start-all.sh` от основната директория (както е описано в Модул 01), този модул вече работи на порт 8081. Можете да пропуснете долните команди за стартиране и директно да отворите http://localhost:8081. -**Опция 1: Използване на Spring Boot Dashboard (Препоръчително за потребители на VS Code)** +**Вариант 1: Използване на Spring Boot Dashboard (Препоръчително за потребители на VS Code)** -Dev контейнерът включва разширението Spring Boot Dashboard, което предоставя визуален интерфейс за управление на всички Spring Boot приложения. Можете да го намерите в Activity Bar от лявата страна на VS Code (потърсете иконата на Spring Boot). +Dev контейнерът включва разширение Spring Boot Dashboard, което осигурява визуален интерфейс за управление на всички Spring Boot приложения. Можете да го намерите в Activity Bar вляво на VS Code (потърсете иконата на Spring Boot). -От Spring Boot Dashboard можете: -- Да видите всички налични Spring Boot приложения в работната среда -- Да стартирате/спирате приложения с едно щракване -- Да разглеждате логовете на приложенията в реално време -- Да следите състоянието на приложенията +От Spring Boot Dashboard можете да: +- видите всички достъпни Spring Boot приложения в работното пространство +- стартирате/спирате приложения с едно кликване +- разглеждате логове на приложенията в реално време +- следите статус на приложенията -Просто кликнете бутона за пускане до "rag", за да стартирате този модул, или стартирайте всички модули наведнъж. +Просто натиснете бутона за пускане до "rag", за да стартирате този модул, или стартирайте всички модули наведнъж. Spring Boot Dashboard -*Този екран показва Spring Boot Dashboard във VS Code, където можете визуално да стартирате, спирате и наблюдавате приложения.* +*Този скрийншот показва Spring Boot Dashboard в VS Code, където можете визуално да стартирате, спирате и следите приложения.* -**Опция 2: Използване на shell скриптове** +**Вариант 2: Използване на shell скриптове** Стартирайте всички уеб приложения (модули 01-04): **Bash:** ```bash -cd .. # От главната директория +cd .. # От коренната директория ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # От главната директория +cd .. # От коренната директория .\start-all.ps1 ``` @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Двата скрипта автоматично зареждат променливите на средата от файла `.env` в корена и ще компилират JAR файловете, ако те не съществуват. +Двата скрипта автоматично зареждат променливи на средата от основния `.env` файл и ще компилират JAR файловете, ако не съществуват. -> **Забележка:** Ако предпочитате да компилирате всички модули ръчно преди стартиране: +> **Забележка:** Ако предпочитате да изградите всички модули ръчно преди стартиране: > > **Bash:** > ```bash @@ -325,7 +324,7 @@ cd 03-rag > mvn clean package -DskipTests > ``` -Отворете http://localhost:8081 в браузъра си. +Отворете http://localhost:8081 във вашия браузър. **За спиране:** @@ -353,73 +352,73 @@ cd ..; .\stop-all.ps1 # Всички модули ### Качване на документ -Започнете с качване на документ – TXT файловете работят най-добре за тестване. Тук е предоставен `sample-document.txt`, който съдържа информация за функциите на LangChain4j, реализирането на RAG и добри практики – перфектен за тестване на системата. +Започнете с качване на документ - най-добре работят TXT файлове за тестване. Предоставен е файл `sample-document.txt` в тази директория, който съдържа информация за функциите на LangChain4j, имплементацията на RAG и добри практики - идеален за тестване на системата. -Системата обработва вашия документ, разделя го на откъси и създава embedding-и за всеки откъс. Това става автоматично при качване. +Системата обработва документа, разбива го на части и създава вградени представяния за всяка част. Това се случва автоматично при качване. ### Задаване на въпроси -Сега задайте конкретни въпроси за съдържанието на документа. Опитайте нещо фактическо, което е ясно посочено в документа. Системата търси релевантни откъси, включва ги в подканата и генерира отговор. +Сега задайте конкретни въпроси относно съдържанието на документа. Опитайте с фактическа информация, която е ясно изразена в документа. Системата търси релевантни части, включва ги в подкана и генерира отговор. -### Проверка на източниците +### Проверка на изходните препратки -Забележете, че всеки отговор включва препратки към източници с оценки за сходство. Тези оценки (от 0 до 1) показват колко релевантен е всеки откъс спрямо вашия въпрос. По-високите оценки означават по-добро съвпадение. Това ви позволява да проверите отговора спрямо изходния материал. +Забележете, че всеки отговор включва изходни препратки с оценки за прилика. Тези оценки (от 0 до 1) показват колко релевантна е била всяка част към вашия въпрос. По-високите оценки означават по-добри съвпадения. Това ви позволява да проверите отговора спрямо изходния материал. RAG Query Results -*Този скрийншот показва резултатите от заявки с генерирания отговор, източници и оценки за релевантност за всеки извлечен откъс.* +*Този скрийншот показва резултатите от заявка с генерирания отговор, източниците и оценките за релевантност на всяка извлечена част.* -### Експериментиране с въпроси +### Експериментирайте с въпроси Опитайте различни типове въпроси: - Конкретни факти: "Каква е основната тема?" - Сравнения: "Каква е разликата между X и Y?" -- Обобщения: "Обобщете основните точки за Z" +- Резюмета: "Обобщете ключовите точки за Z" -Наблюдавайте как оценките за релевантност се променят според това колко добре вашият въпрос съответства на съдържанието на документа. +Наблюдавайте как се променят оценките за релевантност в зависимост от това колко добре въпросът ви съответства на съдържанието на документа. -## Ключови концепции +## Ключови понятия -### Стратегия за разделяне на откъси +### Стратегия за разделяне на части -Документите се разделят на откъси с по 300 токена и 30 токена припокриване. Този баланс гарантира, че всеки откъс има достатъчно контекст, за да е смислен, като същевременно остава достатъчно малък, за да се включат няколко откъса в една подканваща команда. +Документите се разделят на части по 300 токена с припокриване от 30 токена. Този баланс осигурява достатъчно контекст във всяка част, за да бъде смислена, като същевременно остава достатъчно малка, за да се включат няколко части в една подкана. -### Оценки за сходство +### Оценки за прилика -Всеки извлечен откъс идва с оценка за сходство между 0 и 1, която показва колко точно отговаря на въпроса на потребителя. Диаграмата по-долу визуализира диапазоните на оценките и как системата ги използва за филтриране на резултатите: +Всяка извлечена част идва с оценка за прилика между 0 и 1, която показва колко близо съответства на въпроса на потребителя. Диаграмата по-долу визуализира диапазоните на оценките и как системата ги използва за филтриране на резултатите: Similarity Scores -*Тази диаграма показва диапазоните от 0 до 1, с минимален праг 0.5, който филтрира нерелевантните откъси.* +*Тази диаграма показва диапазоните на оценките от 0 до 1, с минимален праг от 0.5, който филтрира нелевантните части.* -Оценките варират от 0 до 1: -- 0.7-1.0: Много релевантен, точно съвпадение -- 0.5-0.7: Релевантен, добър контекст -- Под 0.5: Филтриран, твърде разликован +Оценките са в диапазон от 0 до 1: +- 0.7-1.0: Много релевантно, точно съвпадение +- 0.5-0.7: Релевантно, добър контекст +- Под 0.5: Филтрирано, твърде различно -Системата извлича само откъси над минималния праг за гарантиране на качество. +Системата извлича само части над минималния праг, за да осигури качество. -Embedding-ите работят добре, когато значението се групира ясно, но имат слаби места. Диаграмата по-долу показва честите видове грешки — твърде големи откъси водят до замъглени вектори, прекалено малки откъси нямат контекст, двусмислени термини сочат към много групи, а точните търсения (като ID-та, сериен номер) изобщо не работят с embedding-и: +Вградените представяния работят добре, когато смисълът се кластеризира ясно, но имат слепи зони. Диаграмата по-долу показва често срещани случаи на неуспех — части, които са твърде големи, създават неясни вектори, части, които са твърде малки, нямат контекст, многозначни термини сочат към множество групи, а точните търсения по идентификатори (№ на части и др.) не работят със вградени представяния изобщо: Embedding Failure Modes -*Тази диаграма показва често срещаните грешки при embedding-и: откъси твърде големи, откъси твърде малки, двусмислени термини, и търсения за точно съвпадение като ID.* +*Тази диаграма показва често срещани случаи на неуспех при вградените представяния: части твърде големи, части твърде малки, двусмислени термини, сочещи към няколко групи, и точни търсения като по идентификатори.* -### Съхранение в паметта +### Съхранение в памет -Този модул използва съхранение в паметта за опростяване. При рестарт на приложението, качените документи се губят. Производствените системи използват персистентни векторни бази данни като Qdrant или Azure AI Search. +Този модул използва съхранение в памет за простота. При рестарт на приложението качените документи се губят. Продукционните системи използват постоянни векторни бази данни като Qdrant или Azure AI Search. ### Управление на контекстния прозорец -Всеки модел има максимален контекстен прозорец. Не можете да включите всички откъси от голям документ. Системата извлича най-релевантните N откъса (по подразбиране 5), за да остане в лимитите и същевременно да осигури достатъчен контекст за точни отговори. +Всяка модел има максимален контекстен прозорец. Не можете да включите всички части от голям документ. Системата извлича топ N най-релевантни части (по подразбиране 5), за да се вмести в ограниченията, като осигурява достатъчно контекст за точни отговори. ## Кога RAG има значение -RAG не винаги е правилният подход. Следващото ръководство за решения помага да прецените кога RAG добавя стойност и кога по-прости подходи — като включване на съдържанието директно в подканата или разчитаща на вътрешните знания на модела — са достатъчни: +RAG не винаги е правилният подход. Наръчникът за решения по-долу ви помага да определите кога RAG добавя стойност и кога по-прости подходи — като включване на съдържание директно в подкана или разчитане на вградените знания на модела — са достатъчни: When to Use RAG -*Тази диаграма показва ръководство за решения кога RAG добавя стойност и кога по-простите подходи са достатъчни.* +*Тази диаграма показва наръчник за решения кога RAG добавя стойност и кога по-простите подходи са достатъчни.* ## Следващи стъпки @@ -427,11 +426,11 @@ RAG не винаги е правилният подход. Следващото --- -**Навигация:** [← Предишен: Модул 02 - Проектиране на подканви](../02-prompt-engineering/README.md) | [Обратно към Основното](../README.md) | [Следващ: Модул 04 - Инструменти →](../04-tools/README.md) +**Навигация:** [← Предишен: Модул 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Обратно към Основното](../README.md) | [Следващ: Модул 04 - Инструменти →](../04-tools/README.md) --- **Отказ от отговорност**: -Този документ е преведен с помощта на AI преводаческа услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия оригинален език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален превод от човешки преводач. Ние не носим отговорност за каквито и да е неразбирателства или неправилни тълкувания, произтичащи от използването на този превод. +Този документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. \ No newline at end of file diff --git a/translations/bg/04-tools/README.md b/translations/bg/04-tools/README.md index 63e49c933..41bdc2bf0 100644 --- a/translations/bg/04-tools/README.md +++ b/translations/bg/04-tools/README.md @@ -2,83 +2,83 @@ ## Съдържание -- [Видео урок](../../../04-tools) -- [Какво ще научите](../../../04-tools) -- [Предварителни изисквания](../../../04-tools) -- [Разбиране на AI агенти с инструменти](../../../04-tools) -- [Как работи повикването на инструменти](../../../04-tools) - - [Дефиниции на инструменти](../../../04-tools) - - [Вземане на решения](../../../04-tools) - - [Изпълнение](../../../04-tools) - - [Генериране на отговор](../../../04-tools) - - [Архитектура: Spring Boot автоматично свързване](../../../04-tools) -- [Верижно използване на инструменти](../../../04-tools) -- [Стартиране на приложението](../../../04-tools) -- [Използване на приложението](../../../04-tools) - - [Опитайте просто използване на инструмент](../../../04-tools) - - [Тествайте верижно използване на инструменти](../../../04-tools) - - [Вижте потока на разговора](../../../04-tools) - - [Експериментирайте с различни заявки](../../../04-tools) -- [Ключови концепции](../../../04-tools) - - [ReAct модел (Разсъждение и действие)](../../../04-tools) - - [Значение на описанията на инструментите](../../../04-tools) - - [Управление на сесията](../../../04-tools) - - [Обработка на грешки](../../../04-tools) -- [Налични инструменти](../../../04-tools) -- [Кога да използваме агенти с инструменти](../../../04-tools) -- [Инструменти срещу RAG](../../../04-tools) -- [Следващи стъпки](../../../04-tools) +- [Видео урок](#видео-урок) +- [Какво ще научите](#какво-ще-научите) +- [Предварителни изисквания](#предварителни-изисквания) +- [Разбиране на AI агенти с инструменти](#разбиране-на-ai-агенти-с-инструменти) +- [Как работи извикването на инструменти](#как-работи-извикването-на-инструменти) + - [Дефиниции на инструменти](#дефиниции-на-инструменти) + - [Вземане на решения](#вземане-на-решения) + - [Изпълнение](#изпълнение) + - [Генериране на отговор](#генериране-на-отговор) + - [Архитектура: Spring Boot автосвързване](#архитектура-spring-boot-автосвързване) +- [Свързване на инструменти](#свързване-на-инструменти) +- [Стартиране на приложението](#стартиране-на-приложението) +- [Използване на приложението](#използване-на-приложението) + - [Опитайте просто използване на инструмент](#изпробвайте-просто-използване-на-инструменти) + - [Тествайте свързване на инструменти](#тествайте-веригата-от-инструменти) + - [Вижте потока на разговора](#вижте-хода-на-разговора) + - [Експериментирайте с различни заявки](#експериментирайте-с-различни-заявки) +- [Ключови концепции](#основни-понятия) + - [ReAct модел (Разсъждаване и действие)](#react-модел-разсъждение-и-действие) + - [Значение на описанията на инструментите](#описанията-на-инструментите-са-важни) + - [Управление на сесии](#управление-на-сесии) + - [Обработка на грешки](#обработка-на-грешки) +- [Налични инструменти](#налични-инструменти) +- [Кога да използваме агенти с инструменти](#кога-да-използваме-агенти-с-инструменти) +- [Инструменти срещу RAG](#инструменти-срещу-rag) +- [Следващи стъпки](#следващи-стъпки) ## Видео урок -Гледайте този жив урок, който обяснява как да започнете с този модул: +Гледайте тази жива сесия, която обяснява как да започнете с този модул: -AI Agents with Tools and MCP - Live Session +AI агенти с инструменти и MCP - жива сесия ## Какво ще научите -Дотук научихте как да водите разговори с AI, как да структурирате ефективно подсказки и как да обвържете отговорите си с документи. Но има основно ограничение: езиковите модели могат само да генерират текст. Те не могат да проверят времето, да извършват изчисления, да правят заявки към бази данни или да взаимодействат с външни системи. +До момента научихте как да водите разговори с AI, как да структурирате подканите ефективно и как да обвързвате отговорите с вашите документи. Но все още има основно ограничение: езиковите модели могат само да генерират текст. Те не могат да проверяват времето, да извършват изчисления, да правят заявки към бази данни или да взаимодействат с външни системи. -Инструментите променят това. Като дадете на модела достъп до функции, които може да извика, вие го превръщате от генератор на текст в агент, който може да предприема действия. Моделът решава кога му трябва инструмент, кой инструмент да използва и какви параметри да подаде. Вашият код изпълнява функцията и връща резултата. Моделът включва този резултат в своя отговор. +Инструментите променят това. Като дадете на модела достъп до функции, които може да извиква, го превръщате от генератор на текст в агент, който може да предприема действия. Моделът решава кога му трябва инструмент, кой инструмент да използва и какви параметри да подаде. Вашият код изпълнява функцията и връща резултата. Моделът включва този резултат в своя отговор. ## Предварителни изисквания -- Завършен [Модул 01 - Въведение](../01-introduction/README.md) (разположени ресурси Azure OpenAI) -- Препоръчително завършени предишни модули (този модул реферира към [RAG концепции от Модул 03](../03-rag/README.md) в сравнение между Инструменти и RAG) -- Файл `.env` в главната директория с креденциали за Azure (създаден чрез `azd up` в Модул 01) +- Изпълнен [Модул 01 - Въведение](../01-introduction/README.md) (разположени Azure OpenAI ресурси) +- Препоръчително да сте преминали предишните модули (този модул препраща към [RAG концепции от Модул 03](../03-rag/README.md) в сравнение с Инструменти срещу RAG) +- Файл `.env` в коренната директория с Azure идентификационни данни (създаден чрез `azd up` в Модул 01) -> **Забележка:** Ако не сте завършили Модул 01, първо следвайте инструкциите за разгръщане там. +> **Забележка:** Ако не сте изпълнили Модул 01, първо следвайте инструкциите за разполагане там. ## Разбиране на AI агенти с инструменти -> **📝 Забележка:** Терминът „агенти“ в този модул се отнася до AI асистенти, подобрени с възможности за повикване на инструменти. Това е различно от **Agentic AI** моделите (автономни агенти с планиране, памет и многократно разсъждение), които ще разгледаме в [Модул 05: MCP](../05-mcp/README.md). +> **📝 Забележка:** Терминът „агенти“ в този модул се отнася до AI асистенти, подобрени с възможности за извикване на инструменти. Това е различно от **Agentic AI** патерните (автономни агенти с планиране, памет и многократно разсъждение), които ще разгледаме в [Модул 05: MCP](../05-mcp/README.md). -Без инструменти, езиков модел може само да генерира текст от тренировъчните си данни. Попитайте го за сегашното време и той трябва да гадае. Дайте му инструменти и може да извика API за времето, да извърши изчисления или да направи заявка към база данни — след което да преплете тези реални резултати в своя отговор. +Без инструменти езиков модел може само да генерира текст от обучаващите данни. Попитайте го за текущото време и ще трябва да гадае. Дайте му инструменти и той може да извика API за времето, да извърши изчисления или да направи заявка към база данни — след което да вплете тези реални резултати в отговора си. -Без инструменти срещу Инструменти +Без инструменти срещу с инструменти -*Без инструменти моделът само гадае — с инструменти може да извиква API-та, да извършва изчисления и да връща данни в реално време.* +*Без инструменти моделът само гадае — с инструменти може да извиква API-та, да извършва изчисления и връща данни в реално време.* -AI агентът с инструменти следва модел **Разсъждение и действие (ReAct)**. Моделът не просто отговаря — той мисли какво му трябва, действа като извиква инструмент, наблюдава резултата и след това решава дали да действа отново или да даде финалния отговор: +AI агент с инструменти следва модел **Разсъждаване и действие (ReAct)**. Моделът не просто отговаря — той мисли какво му трябва, действа чрез извикване на инструмент, наблюдава резултата и решава дали да действа отново или да предостави крайния отговор: 1. **Разсъждава** — агентът анализира въпроса на потребителя и определя каква информация му трябва -2. **Действа** — агентът избира подходящия инструмент, генерира правилните параметри и го извиква -3. **Наблюдава** — агентът получава резултата от инструмента и го оценява -4. **Повтаря или отговаря** — ако са нужни повече данни, агентът се връща обратно; иначе съставя отговор на естествен език +2. **Действа** — агентът избира правилния инструмент, генерира правилните параметри и го извиква +3. **Наблюдава** — агентът получава изхода на инструмента и оценява резултата +4. **Повтаря или Отговаря** — ако са нужни още данни, агентът се връща обратно; иначе съставя отговор на естествен език ReAct модел -*Цикълът ReAct — агентът разсъждава какво да направи, действа чрез повикване на инструмент, наблюдава резултата и циклира докато предостави финален отговор.* +*Цикълът ReAct — агентът разсъждава какво да направи, действа чрез извикване на инструмент, наблюдава резултата и повтаря, докато може да предостави финалния отговор.* -Това се случва автоматично. Вие дефинирате инструментите и техните описания. Моделът взема решения кога и как да ги използва. +Това се случва автоматично. Вие дефинирате инструментите и техните описания. Моделът управлява взимането на решения кога и как да ги използва. -## Как работи повикването на инструменти +## Как работи извикването на инструменти ### Дефиниции на инструменти [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Дефинирате функции с ясни описания и спецификации на параметрите. Моделът вижда тези описания във вашето системно подсказване и разбира какво прави всеки инструмент. +Вие дефинирате функции с ясни описания и спецификации на параметрите. Моделът вижда тези описания в своята системна подсказка и разбира какво прави всеки инструмент. ```java @Component @@ -97,134 +97,134 @@ public interface Assistant { } // Асистентът е автоматично свързан от Spring Boot с: -// - ChatModel обект +// - ChatModel bean // - Всички @Tool методи от @Component класове // - ChatMemoryProvider за управление на сесии ``` + +Диаграмата по-долу разглежда всяка анотация и показва как всяка част помага на AI да разбере кога да извика инструмента и какви аргументи да подаде: -Диаграмата по-долу обяснява всяка анотация и показва как всяка част помага на AI да разбере кога да извика инструмента и какви аргументи да подаде: +Анатомия на дефиниции на инструменти -Анатомия на дефиниция на инструмент - -*Анатомия на дефиниция на инструмент — @Tool казва на AI кога да го използва, @P описва всеки параметър, а @AiService свързва всичко при стартиране.* +*Анатомия на дефиниция на инструмент — @Tool казва на AI кога да го използва, @P описва всеки параметър, а @AiService свързва всичко заедно при стартиране.* > **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) и попитайте: -> - "Как бих интегрирал реално weather API, като OpenWeatherMap, вместо мок данни?" -> - "Какво прави едно добро описание на инструмент, което помага на AI правилно да го използва?" -> - "Как да обработвам грешки и ограничения на API в имплементациите на инструментите?" +> - "Как бих интегрирал реално API за времето като OpenWeatherMap вместо тестови данни?" +> - "Какво прави едно описание на инструмент добро и помага на AI да го използва правилно?" +> - "Как да управлявам грешки и ограничения на скоростта в реализацията на инструментите?" ### Вземане на решения -Когато потребител пита „Какво е времето в Сиатъл?“, моделът не избира произволно инструмент. Той сравнява намерението на потребителя с всяко описание на инструмент, които има достъп, оценява всяко по релевантност и избира най-подходящото. След това генерира структурирано повикване на функция с правилните параметри — в случая задава `location` на `"Seattle"`. +Когато потребителят пита „Какво е времето в Сиатъл?“, моделът не избира произволно инструмент. Той сравнява намерението на потребителя спрямо описанията на всички инструменти, които има достъп, оценява тяхната релевантност и избира най-подходящия. След това генерира структуриран извикване на функция с правилните параметри — в този случай задава `location` на `"Seattle"`. -Ако няма инструмент, който да съответства на заявката на потребителя, моделът отговаря от собствените си знания. Ако има няколко подходящи инструмента, избира най-конкретния. +Ако няма инструмент, който съвпада с желанията на потребителя, моделът отговаря с базирана на знанието си информация. Ако няколко инструмента съвпадат, избира най-специфичния. Как AI решава кой инструмент да използва -*Моделът оценява всеки наличен инструмент спрямо намерението на потребителя и избира най-добрия — затова е важно да се пишат ясни, конкретни описания на инструментите.* +*Моделът оценява всеки наличен инструмент спрямо намерението на потребителя и избира най-подходящия — затова е важно да пишете ясни и конкретни описания на инструментите.* ### Изпълнение [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot автоматично свързва декларативния интерфейс `@AiService` с всички регистрирани инструменти и LangChain4j изпълнява повикванията към инструментите автоматично. Зад кулисите, едно пълно повикване на инструмент минава през шест етапа — от въпроса на потребителя на естествен език до отговора на естествен език: +Spring Boot автоматично свързва декларативния интерфейс `@AiService` с всички регистрирани инструменти, а LangChain4j автоматично изпълнява извикванията на инструменти. Зад кулисите, пълното извикване на инструмент преминава през шест етапа — от въпроса на потребителя на естествен език до отговора на естествен език: -Поток на повикване на инструмент +Поток на извикване на инструменти -*Пълният поток — потребителят задава въпрос, моделът избира инструмент, LangChain4j го изпълнява, а моделът включва резултата в естествения отговор.* +*Цялостният процес — потребителят задава въпрос, моделът избира инструмент, LangChain4j го изпълнява и моделът вплита резултата в естествен отговор.* -Ако сте стартирали [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) в Модул 00, вече сте видели този модел в действие — инструментите `Calculator` се извикват по същия начин. Диаграмата за последователност по-долу показва точно какво се случи зад кулисите по време на този демонстрационен пример: +Зад кулисите, `AiServices` изпълнява същия цикъл на извикване на инструменти за всеки инструмент — тук илюстрирано с прост `Calculator`. Диаграмата на последователността по-долу показва точно какво се случва под капака: -Диаграма за последователност на повикване на инструмент +Диаграма на последователността за извикване на инструменти -*Цикъл на повикване на инструмент от демото Quick Start — `AiServices` изпраща съобщението и схемите на инструментите към LLM, LLM отговаря с повикване на функция като `add(42, 58)`, LangChain4j изпълнява метода `Calculator` локално и връща резултата за финален отговор.* +*Цикълът на извикване на инструмент — `AiServices` изпраща вашето съобщение и схеми на инструменти към LLM, LLM отговаря с извикване на функция като `add(42, 58)`, LangChain4j локално изпълнява метода `Calculator` и връща резултата за окончателния отговор.* > **🤖 Опитайте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворете [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) и попитайте: > - "Как работи моделът ReAct и защо е ефективен за AI агенти?" > - "Как агентът решава кой инструмент да използва и в какъв ред?" -> - "Какво се случва ако изпълнението на инструмент се провали — как да обработя грешките надеждно?" +> - "Какво се случва, ако изпълнението на инструмент се провали - как да управлявам грешки надеждно?" ### Генериране на отговор Моделът получава данните за времето и ги форматира в отговор на естествен език за потребителя. -### Архитектура: Spring Boot автоматично свързване +### Архитектура: Spring Boot автосвързване -Този модул използва интеграция на LangChain4j със Spring Boot с декларативни интерфейси `@AiService`. При стартиране Spring Boot открива всеки `@Component`, съдържащ методи с `@Tool`, вашия `ChatModel` bean и `ChatMemoryProvider` — след което ги свързва всички в един интерфейс `Assistant` без нужда от излишен код. +Този модул използва интеграцията на LangChain4j със Spring Boot и декларативни интерфейси `@AiService`. При стартиране Spring Boot открива всеки `@Component`, който съдържа методи с `@Tool`, вашия ChatModel bean и ChatMemoryProvider — след което ги свързва всички в един интерфейс Assistant без излишен шаблонен код. -Архитектура на Spring Boot автоматично свързване +Архитектура на Spring Boot автосвързване -*Интерфейсът @AiService свързва ChatModel, компонентите на инструментите и доставчика на памет — Spring Boot управлява цялото свързване автоматично.* +*Интерфейсът @AiService свързва заедно ChatModel, компонентите на инструментите и доставчика на памет — Spring Boot управлява всичко за вас автоматично.* -Ето пълния жизнен цикъл на заявката като диаграма за последователност — от HTTP заявката през контролера, сервиза и автоматично свързаното прокси, чак до изпълнението на инструмента и връщането назад: +Ето целия жизнен цикъл на заявката като диаграма на последователността — от HTTP заявката през контролера, услугата и авто-свързания прокси, чак до изпълнението на инструмента и връщане обратно: -Последователност за повикване на инструменти в Spring Boot +Диаграма на последователността за извикване на инструменти в Spring Boot -*Пълният жизнен цикъл на заявка в Spring Boot — HTTP заявката преминава през контролера и сервиза до автоматично свързаното прокси Assistant, което автоматично организира повикванията към LLM и инструментите.* +*Пълният жизнен цикъл на заявката в Spring Boot — HTTP заявката преминава през контролер и услуга до авто-свързания Assistant прокси, който управлява LLM и извикванията на инструменти автоматично.* -Основни предимства на този подход: +Ключови предимства на този подход: -- **Автоматично свързване в Spring Boot** — ChatModel и инструментите се инжектират автоматично +- **Spring Boot автосвързване** — ChatModel и инструментите се инжектират автоматично - **Патерн @MemoryId** — Автоматично управление на паметта на базата на сесии -- **Единствен инстанс** — Assistant се създава веднъж и се използва повторно за по-добра производителност -- **Безопасно по типове изпълнение** — Java методи се извикват директно с преобразуване на типове -- **Оркестрация на многократни обрати** — Автоматично управлява верижното използване на инструменти -- **Нулев излишен код** — Без ръчни извиквания на `AiServices.builder()` или ръчно управление на HashMap памет +- **Единствен екземпляр** — Assistant се създава веднъж и се използва многократно за по-добра производителност +- **Изпълнение тип-безопасно** — Java методите се извикват директно с преобразуване на типове +- **Управление на множество стъпки** — Автоматично обслужва свързване на инструменти +- **Без излишен шаблонен код** — Няма нужда от ръчни `AiServices.builder()` извиквания или работа с паметен HashMap -Алтернативните подходи (ръчно `AiServices.builder()`) изискват повече код и не предлагат предимствата на интеграцията със Spring Boot. +Алтернативните подходи (ръчни `AiServices.builder()`) изискват повече код и не използват предимствата на Spring Boot интеграцията. -## Верижно използване на инструменти +## Свързване на инструменти -**Веригване на инструменти** — Истинската сила на агенти с инструменти се проявява когато един въпрос изисква използване на няколко инструмента. Попитайте „Какво е времето в Сиатъл по Фаренхайт?“ и агентът автоматично верижира два инструмента: първо извиква `getCurrentWeather` за температурата в Целзий, после предава тази стойност на `celsiusToFahrenheit` за конверсия — всичко в един разговорен ред. +**Свързване на инструменти** — Истинската сила на агентите с инструменти се проявява, когато един въпрос изисква използването на множество инструменти. Попитайте "Какво е времето в Сиатъл във Фаренхайт?" и агентът автоматично свързва два инструмента: първо извиква `getCurrentWeather`, за да получи температурата в Целзий, след това подава тази стойност на `celsiusToFahrenheit` за преобразуване — всичко в един разговорен ход. -Пример за верижно използване на инструменти +Пример за свързване на инструменти -*Верижно използване на инструменти в действие — агентът първо извиква getCurrentWeather, после подава резултата в celsiusToFahrenheit и връща комбиниран отговор.* +*Свързване на инструменти в действие — агентът първо извиква getCurrentWeather, след това подава резултата в Целзий на celsiusToFahrenheit и връща комбиниран отговор.* -**Гладко справяне с грешки** — Ако поискате времето в град, който липсва в мок данните, инструментът връща съобщение за грешка, а AI обяснява, че не може да помогне, вместо да се срине. Инструментите падат безопасно. Диаграмата по-долу сравнява двата подхода — с правилна обработка на грешки агентът улавя изключението и отговаря полезно, а без нея цялото приложение се срива: +**Грациозни повреди** — Попитайте за времето в град, който не е в тестовите данни. Инструментът връща съобщение за грешка, а AI обяснява, че не може да помогне, вместо да се срине. Инструментите се провалят безопасно. Диаграмата по-долу противопоставя двата подхода — с правилна обработка на грешки агентът хваща изключението и отговаря полезно, а без нея цялото приложение спира да работи: Поток на обработка на грешки -*Когато инструмент се провали, агентът улавя грешката и отговаря с полезно обяснение вместо да спре.* +*Когато инструмент се провали, агентът хваща грешката и отговаря с полезно обяснение, вместо да се срине.* -Това става в един разговорен ред. Агентът автономно оркестрира множество повиквания на инструменти. +Това се случва в един разговорен ход. Агентът управлява множество извиквания на инструменти автономно. ## Стартиране на приложението -**Проверете разгръщането:** +**Проверете разполагането:** -Уверете се, че файлът `.env` е наличен в главната директория с креденциали за Azure (създаден по време на Модул 01). Изпълнете това от директорията на модула (`04-tools/`): +Осигурете, че файл `.env` съществува в коренната директория с Azure идентификационни данни (създаден по време на Модул 01). Стартирайте това от директорията на модула (`04-tools/`): **Bash:** ```bash cat ../.env # Трябва да показва AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **PowerShell:** ```powershell Get-Content ..\.env # Трябва да показва AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Стартирайте приложението:** -> **Забележка:** Ако вече сте стартирали всички приложения с `./start-all.sh` от главната директория (както е описано в Модул 01), този модул вече работи на порт 8084. Можете да пропуснете командите за стартиране и директно да отидете на http://localhost:8084. +> **Забележка:** Ако вече сте стартирали всички приложения чрез `./start-all.sh` от коренната директория (както е описано в Модул 01), този модул вече работи на порт 8084. Можете да прескочите командите за стартиране по-долу и да отидете директно на http://localhost:8084. **Опция 1: Използване на Spring Boot Dashboard (Препоръчително за потребители на VS Code)** -В контейнера за разработка е включено разширението Spring Boot Dashboard, което предоставя визуален интерфейс за управление на всички Spring Boot приложения. Можете да го намерите в лентата с дейности вляво във VS Code (потърсете иконата на Spring Boot). +Разработчическият контейнер включва разширение Spring Boot Dashboard, което предоставя визуален интерфейс за управление на всички Spring Boot приложения. Можете да го намерите в лентата с активности вляво на VS Code (потърсете иконата на Spring Boot). От Spring Boot Dashboard можете: -- Да видите всички налични Spring Boot приложения в работната област +- Да видите всички налични Spring Boot приложения в работната среда - Да стартирате/спирате приложения с един клик -- Да разглеждате логовете на приложението в реално време -- Да следите статуса на приложението -Просто кликнете върху бутона за възпроизвеждане до "tools", за да стартирате този модул, или стартирайте всички модули наведнъж. +- Да преглеждате логове на приложенията в реално време +- Да наблюдавате състоянието на приложенията -Ето как изглежда Spring Boot Dashboard във VS Code: +Просто кликнете върху бутона за пускане до „tools“, за да стартирате този модул, или стартирайте всички модули наведнъж. +Ето как изглежда Spring Boot Dashboard в VS Code: Spring Boot Dashboard -*Spring Boot Dashboard във VS Code — стартиране, спиране и наблюдение на всички модули от едно място* +*Таблото за управление Spring Boot в VS Code — стартирайте, спирайте и наблюдавайте всички модули от едно място* **Опция 2: Използване на shell скриптове** @@ -232,13 +232,13 @@ Get-Content ..\.env # Трябва да показва AZURE_OPENAI_ENDPOINT, A **Bash:** ```bash -cd .. # От кореновата директория +cd .. # От коренната директория ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # От кореновата директория +cd .. # От главната директория .\start-all.ps1 ``` @@ -256,7 +256,7 @@ cd 04-tools .\start.ps1 ``` -И двата скрипта автоматично зареждат променливи на средата от `.env` файла в корена и ще компилират JAR файловете, ако не съществуват. +И двата скрипта автоматично зареждат променливите на средата от основния `.env` файл и ще компилират JAR файловете, ако те не съществуват. > **Забележка:** Ако предпочитате да компилирате всички модули ръчно преди стартиране: > @@ -292,84 +292,84 @@ cd ..; .\stop-all.ps1 # Всички модули ## Използване на приложението -Приложението предоставя уеб интерфейс, където можете да взаимодействате с AI агент, който има достъп до инструменти за прогноза за времето и преобразуване на температури. Ето как изглежда интерфейсът — включва бързи примери и чат панел за изпращане на заявки: +Приложението предоставя уеб интерфейс, където можете да взаимодействате с AI агент, който има достъп до инструменти за прогноза за времето и конвертиране на температура. Ето как изглежда интерфейсът — включва бързи примери и панел за чат за изпращане на заявки: AI Agent Tools Interface -*Интерфейс на AI Agent Tools - бързи примери и чат интерфейс за взаимодействие с инструменти* +*Интерфейсът на AI Agent Tools - бързи примери и чат интерфейс за взаимодействие с инструментите* -### Изпробвайте проста употреба на инструменти +### Изпробвайте просто използване на инструменти -Започнете с проста заявка: "Convert 100 degrees Fahrenheit to Celsius". Агентът разбира, че трябва да използва инструмента за преобразуване на температурата, извиква го с правилните параметри и връща резултата. Забележете колко естествено изглежда — не сте указали кой инструмент да се използва или как да го извика. +Започнете с една ясна заявка: "Convert 100 degrees Fahrenheit to Celsius" (Конвертирай 100 градуса по Фаренхайт в Целзий). Агентът разпознава, че му е необходим инструмент за конвертиране на температура, извиква го с правилните параметри и връща резултата. Забележете колко естествено изглежда това – не сте указали кой инструмент да използва или как да го извика. -### Тествайте свързване на инструменти +### Тествайте веригата от инструменти -Сега опитайте нещо по-сложно: "What's the weather in Seattle and convert it to Fahrenheit?" Наблюдавайте как агентът преминава през стъпките. Първо получава прогноза за времето (която връща по Целзий), разбира, че трябва да преобразува във Фаренхайт, извиква инструмента за конвертиране и комбинира двата резултата в един отговор. +Сега опитайте нещо по-сложно: "What's the weather in Seattle and convert it to Fahrenheit?" (Какво е времето в Сиатъл и го конвертирай във Фаренхайт?) Вижте как агентът преминава през стъпките. Първо получава прогнозата (която връща по Целзий), разпознава, че трябва да конвертира във Фаренхайт, извиква инструмента за конверсия и комбинира двата резултата в един отговор. -### Вижте потока на разговор +### Вижте хода на разговора -Чат интерфейсът съхранява историята на разговора, позволявайки ви да провеждате многократни взаимодействия. Можете да видите всички предишни въпроси и отговори, което улеснява проследяването на разговора и разбирането как агентът изгражда контекст през няколко обмена. +Чат интерфейсът запазва историята на разговора, позволявайки ви да водите многоповторни взаимодействия. Можете да видите всички предишни заявки и отговори, което прави лесно проследяването на разговора и разбирането как агентът изгражда контекст през няколко обмена. Conversation with Multiple Tool Calls -*Многократен разговор, показващ прости преобразувания, търсения на времето и свързване на инструменти* +*Многоповторен разговор показващ прости конверсии, проверка на времето и вериги от инструменти* ### Експериментирайте с различни заявки Опитайте различни комбинации: -- Търсения на времето: "What's the weather in Tokyo?" -- Преобразувания на температури: "What is 25°C in Kelvin?" -- Комбинирани заявки: "Check the weather in Paris and tell me if it's above 20°C" +- Проверка на времето: "What's the weather in Tokyo?" (Какво е времето в Токио?) +- Конверсии на температура: "What is 25°C in Kelvin?" (Колко е 25°C в Келвин?) +- Комбинирани заявки: "Check the weather in Paris and tell me if it's above 20°C" (Провери времето в Париж и ми кажи дали е над 20°C) -Забележете как агентът интерпретира естествения език и го преобразува в съответните извиквания на инструменти. +Забележете как агентът интерпретира естествения език и го съпоставя с подходящи извиквания на инструменти. ## Основни понятия -### Патерн ReAct (Разсъждение и Действие) +### ReAct модел (Разсъждение и Действие) -Агентът редува между разсъждение (решаване какво да направи) и действие (използване на инструменти). Този модел позволява автономно решаване на проблеми, а не просто отговори на инструкции. +Агентът редува разсъждение (решаване какво да прави) и действие (използване на инструменти). Този модел позволява автономно решаване на проблеми, а не само отговор на инструкции. -### Описанията на инструментите имат значение +### Описанията на инструментите са важни -Качеството на описанията на вашите инструменти пряко влияе върху това колко добре агентът ги използва. Ясните, конкретни описания помагат на модела да разбере кога и как да извика всеки инструмент. +Качеството на описанията на вашите инструменти влияе директно колко добре агентът ги използва. Ясните и конкретни описания помагат на модела да разбира кога и как да извика всеки инструмент. ### Управление на сесии -Анотацията `@MemoryId` позволява автоматично управление на паметта на базата на сесии. Всеки идентификатор на сесия получава собствен екземпляр `ChatMemory`, управляван от `ChatMemoryProvider` bean, така че множество потребители могат да взаимодействат с агента едновременно без разговорите им да се смесват. Следната диаграма показва как множество потребители се насочват към изолирани хранилища на памет, базирани на техните ID на сесия: +Анотацията `@MemoryId` позволява автоматично управление на памет на базата на сесия. Всеки идентификатор на сесия получава свой собствен инстанс на `ChatMemory`, управляван от bean-а `ChatMemoryProvider`, така че множество потребители могат да взаимодействат с агента едновременно без да се смесват разговорите им. Следната диаграма показва как множество потребители се насочват към изолирани паметови хранилища на базата на своите идентификатори на сесия: Session Management with @MemoryId -*Всеки ID на сесия съответства на изолирана история на разговора — потребителите никога не виждат съобщенията един на друг.* +*Всеки идентификатор на сесия съответства на изолирана история на разговора — потребителите никога не виждат съобщенията на другите.* ### Обработка на грешки -Инструментите могат да се повредят — API могат да изтекат, параметрите да са невалидни, външни услуги да спрат. Продуктовите агенти имат нужда от обработка на грешки, за да може моделът да обяснява проблемите или да опитва алтернативи, вместо да срива цялото приложение. Когато инструмент хвърли изключение, LangChain4j го прихваща и предава съобщението за грешка обратно към модела, който може да обясни проблема на естествен език. +Инструментите могат да се провалят — API-тата могат да изтекат, параметрите да са невалидни, външни услуги да спрат. Производствените агенти се нуждаят от обработка на грешки, така че моделът да може да обяснява проблемите или да пробва алтернативи, вместо приложението да се срива. Когато инструмент хвърли изключение, LangChain4j го улавя и предава съобщението за грешка обратно на модела, който после може да обясни проблема на естествен език. ## Налични инструменти -Диаграмата по-долу показва широката екосистема от инструменти, които можете да създавате. Този модул демонстрира инструменти за времето и температурата, но същият патерн `@Tool` работи за всякакъв Java метод — от заявки към бази данни до обработка на плащания. +Диаграмата по-долу показва широката екосистема от инструменти, които можете да изградите. Този модул демонстрира инструменти за времето и температурата, но същият `@Tool` модел работи за всеки Java метод — от заявки към база данни до обработка на плащания. Tool Ecosystem -*Всеки Java метод, анотиран с @Tool, става достъпен за AI — този патерн се разпростира върху бази данни, API, имейли, файлови операции и още.* +*Всеки Java метод, анотиран с @Tool, става достъпен за AI — моделът се разширява към бази данни, API, имейл, файлови операции и други.* -## Кога да използвате агенти, базирани на инструменти +## Кога да използваме агенти с инструменти -Не всяка заявка изисква инструменти. Решението зависи от това дали AI трябва да взаимодейства с външни системи или може да отговори въз основа на собствените си знания. Следното ръководство обобщава кога инструментите добавят стойност и кога са излишни: +Не всяка заявка се нуждае от инструменти. Решението зависи от това дали AI трябва да взаимодейства с външни системи или може да отговори от собствените си знания. Следващото ръководство обобщава кога инструментите добавят стойност и кога не са необходими: When to Use Tools -*Бързо ръководство за решения — инструментите са за реалновременни данни, изчисления и действия; общи знания и творчески задачи не се нуждаят от тях.* +*Бързо ръководство за решение — инструментите са за данни в реално време, изчисления и действия; общите знания и творческите задачи не ги изискват.* -## Инструменти спрямо RAG +## Инструменти срещу RAG -Модулите 03 и 04 и двата разширяват възможностите на AI, но по съществени различни начини. RAG предоставя на модела достъп до **знания** чрез извличане на документи. Инструментите дават на модела възможност да извършва **действия** чрез извикване на функции. Диаграмата по-долу сравнява тези два подхода един до друг — от начина, по който работи всеки поток, до компромисите между тях: +Модулите 03 и 04 разширяват възможностите на AI, но по съществено различни начини. RAG дава на модела достъп до **знания** чрез извличане на документи. Инструментите дават на модела способността да извършва **действия** чрез извикване на функции. Диаграмата по-долу сравнява тези два подхода един до друг — от начина на работа на всеки процес до компромисите между тях: Tools vs RAG Comparison -*RAG извлича информация от статични документи — Инструментите изпълняват действия и доставят динамични, актуални данни. Много продуктови системи комбинират и двата подхода.* +*RAG извлича информация от статични документи — Инструментите изпълняват действия и взимат динамични, в реално време данни. Много производствени системи комбинират и двата подхода.* -На практика, много продуктови системи съчетават двата подхода: RAG за обосноваване на отговорите с вашата документация и Инструменти за достъп до живи данни или изпълнение на операции. +На практика много производствени системи комбинират двата подхода: RAG за основа на отговорите в документацията ви и Инструменти за взимане на живи данни или изпълнение на операции. ## Следващи стъпки @@ -377,11 +377,11 @@ cd ..; .\stop-all.ps1 # Всички модули --- -**Навигация:** [← Предишен: Модул 03 - RAG](../03-rag/README.md) | [Обратно към Главната](../README.md) | [Следващ: Модул 05 - MCP →](../05-mcp/README.md) +**Навигация:** [← Предишен: Модул 03 - RAG](../03-rag/README.md) | [Обратно към началото](../README.md) | [Следващ: Модул 05 - MCP →](../05-mcp/README.md) --- **Отказ от отговорност**: -Този документ е преведен с помощта на AI преводаческа услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален превод от човек. Не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. +Този документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. \ No newline at end of file diff --git a/translations/bg/README.md b/translations/bg/README.md index 4b6a6da97..18a737f86 100644 --- a/translations/bg/README.md +++ b/translations/bg/README.md @@ -2,18 +2,18 @@ # LangChain4j за начинаещи -Курс за изграждане на AI приложения с LangChain4j и Azure OpenAI GPT-5.2, от базов чат до AI агенти. +Курс за разработване на AI приложения с LangChain4j и Azure OpenAI GPT-5.2, от основен чат до AI агенти. -### 🌐 Поддръжка на много езици +### 🌐 Многоезична поддръжка #### Поддържа се чрез GitHub Action (автоматизирано и винаги актуално) -[Арабски](../ar/README.md) | [Бенгалски](../bn/README.md) | [Български](./README.md) | [Бирмански (Мианмар)](../my/README.md) | [Китайски (опростен)](../zh-CN/README.md) | [Китайски (традиционен, Хонконг)](../zh-HK/README.md) | [Китайски (традиционен, Макао)](../zh-MO/README.md) | [Китайски (традиционен, Тайван)](../zh-TW/README.md) | [Хърватски](../hr/README.md) | [Чешки](../cs/README.md) | [Датски](../da/README.md) | [Нидерландски](../nl/README.md) | [Естонски](../et/README.md) | [Фински](../fi/README.md) | [Френски](../fr/README.md) | [Немски](../de/README.md) | [Гръцки](../el/README.md) | [Иврит](../he/README.md) | [Хинди](../hi/README.md) | [Унгарски](../hu/README.md) | [Индонезийски](../id/README.md) | [Италиански](../it/README.md) | [Японски](../ja/README.md) | [Каннада](../kn/README.md) | [Кмерски](../km/README.md) | [Корейски](../ko/README.md) | [Литовски](../lt/README.md) | [Малайски](../ms/README.md) | [Малаялам](../ml/README.md) | [Марати](../mr/README.md) | [Непалски](../ne/README.md) | [Нигерийски Пиджин](../pcm/README.md) | [Норвежки](../no/README.md) | [Персийски (Фарси)](../fa/README.md) | [Полски](../pl/README.md) | [Португалски (Бразилия)](../pt-BR/README.md) | [Португалски (Португалия)](../pt-PT/README.md) | [Пенджаби (Гурмукхи)](../pa/README.md) | [Румънски](../ro/README.md) | [Руски](../ru/README.md) | [Сръбски (кирилица)](../sr/README.md) | [Словашки](../sk/README.md) | [Словенски](../sl/README.md) | [Испански](../es/README.md) | [Суахили](../sw/README.md) | [Шведски](../sv/README.md) | [Тагалог (Филипински)](../tl/README.md) | [Тамилски](../ta/README.md) | [Телугу](../te/README.md) | [Тайландски](../th/README.md) | [Турски](../tr/README.md) | [Украински](../uk/README.md) | [Урду](../ur/README.md) | [Виетнамски](../vi/README.md) +[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](./README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) > **Предпочитате да клонирате локално?** > -> Този хранилище включва над 50 езикови превода, което значително увеличава размера на изтеглянето. За да клонирате без преводи, използвайте sparse checkout: +> Това хранилище включва над 50 езикови превода, което значително увеличава размера на изтеглянето. За да клонирате без преводи, използвайте sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,60 +29,61 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Това ви дава всичко необходимо за завършване на курса с много по-бързо изтегляне. +> Това ви осигурява всичко необходимо за завършване на курса с много по-бързо изтегляне. ## Съдържание -1. [Бърз старт](00-quick-start/README.md) - Започнете с LangChain4j -2. [Въведение](01-introduction/README.md) - Научете основите на LangChain4j -3. [Проектиране на подсказки](02-prompt-engineering/README.md) - Усъвършенствайте ефективно проектиране на подсказки -4. [RAG (Генерация с достъп до база знания)](03-rag/README.md) - Изградете интелигентни системи, базирани на знания -5. [Инструменти](04-tools/README.md) - Интегриране на външни инструменти и прости асистенти -6. [MCP (Протокол за контекст на модела)](05-mcp/README.md) - Работа с Протокола за контекст на модела (MCP) и агенти +1. [Въведение](01-introduction/README.md) - Научете основите на LangChain4j +2. [Създаване на заявки (Prompt Engineering)](02-prompt-engineering/README.md) - Овладейте ефективни техники за създаване на заявки +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Създавайте интелигентни системи, базирани на знания +4. [Инструменти](04-tools/README.md) - Интегрирайте външни инструменти и прости асистенти +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Работете с Model Context Protocol (MCP) и агентски модули -### Видео ръководства +### Видео уроци -Всеки модул има придружаваща сесия на живо, в която разглеждаме концепциите и кода стъпка по стъпка. +Всеки модул има съпътстваща жива сесия, в която преминаваме през концепциите и кода стъпка по стъпка. | Модул | Видео | |--------|-------| | 01 - Въведение | [Започване с LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Проектиране на подсказки | [Проектиране на подсказки с LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 02 - Създаване на заявки | [Създаване на заявки с LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG с LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Инструменти & 05 - MCP | [AI агенти с инструменти и MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Обучителен път +## Учебен път -**Нови сте в LangChain4j?** Разгледайте [Глосария](docs/GLOSSARY.md) за определения на ключови термини и концепции. +**Ново в LangChain4j?** Разгледайте [Глосария](docs/GLOSSARY.md) за определения на ключови термини и концепции. > **Бърз старт** 1. Форкнете това хранилище в своя GitHub акаунт -2. Натиснете **Code** → раздела **Codespaces** → **...** → **New with options...** -3. Използвайте стандартните настройки – те ще изберат контейнера за разработка, създаден за курса -4. Натиснете **Create codespace** -5. Изчакайте 5-10 минути, докато средата се подготви -6. Започнете директно от [Бърз старт](./00-quick-start/README.md)! +2. Кликнете **Code** → раздел **Codespaces** → **...** → **New with options...** +3. Използвайте подразбиращите се настройки – това ще избере development контейнера, създаден за този курс +4. Кликнете **Create codespace** +5. Изчакайте 5-10 минути докато средата се подготви +6. Отидете директно на [Въведение](./01-introduction/README.md) и започнете! -След завършване на модулите, разгледайте [Ръководството за тестване](docs/TESTING.md), за да видите концепциите на тестване в LangChain4j на практика. +След като завършите модулите, разгледайте [Ръководството за тестване](docs/TESTING.md), за да видите в действие концепциите за тестване в LangChain4j. + +> **Забележка:** Тази тренировка използва Azure OpenAI. Започнете с [БЕЗПЛАТЕН Azure акаунт](https://aka.ms/azure-free-account), ако нямате такъв. -> **Забележка:** Тренирането използва както GitHub модели, така и Azure OpenAI. Модулът [Бърз старт](00-quick-start/README.md) използва GitHub модели (не се изисква Azure абонамент), докато модулите 1-5 използват Azure OpenAI. Започнете с [БЕЗПЛАТЕН Azure акаунт](https://aka.ms/azure-free-account), ако нямате. ## Обучение с GitHub Copilot -За да започнете бързо да пишете код, отворете този проект в GitHub Codespace или в локалната си IDE със предоставения devcontainer. Devcontainer-ът, използван в курса, идва предварително конфигуриран с GitHub Copilot за AI съвместно програмиране. +За бързо започване на кодирането, отворете този проект в GitHub Codespace или във вашето локално IDE с осигурения devcontainer. Devcontainer-ът, използван в този курс, идва предварително конфигуриран с GitHub Copilot за AI програмиране в екип. + +Всеки примерен код включва предложени въпроси, които можете да зададете на GitHub Copilot, за да задълбочите разбирането си. Потърсете подсказките 💡/🤖 в: -Всеки кодов пример включва предложени въпроси, които можете да зададете на GitHub Copilot, за да задълбочите разбирането си. Потърсете подсказките 💡/🤖 в: +- **Java файлови хедъри** - Въпроси, специфични за всеки пример +- **Модулни README файлове** - Подсказки за изследване след примерите с код -- **Хедъри на Java файлове** - Въпроси специфични за всеки пример -- **READMEs на модулите** - Подсказки за изследване след примерите с код +**Как да използвате:** Отворете всеки кодов файл и задайте предложените въпроси на Copilot. Той има пълен контекст за кода и може да обяснява, разширява и предлага алтернативи. -**Как да използвате:** Отворете всеки кодов файл и задайте предложените въпроси на Copilot. Той има пълен контекст на кода и може да обяснява, разширява и предлага алтернативи. +Искате да научите повече? Разгледайте [Copilot за AI програмиране в екип](https://aka.ms/GitHubCopilotAI). -Искате да научите повече? Разгледайте [Copilot за AI съвместно програмиране](https://aka.ms/GitHubCopilotAI). ## Допълнителни ресурси @@ -97,7 +98,7 @@ [![AZD за начинаещи](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) [![Edge AI за начинаещи](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) [![MCP за начинаещи](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Агенти за начинаещи](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI агенти за начинаещи](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- @@ -111,28 +112,28 @@ ### Основно обучение [![ML за начинаещи](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Данни науки за начинаещи](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![Наука за данните за начинаещи](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI за начинаещи](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Киберсигурност за начинаещи](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Уеб разработка за начинаещи](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT за начинаещи](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR разработка за начинаещи](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Серия Copilot -[![Copilot за AI програмиране в екип](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot за C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot приключения](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Получаване на помощ -Ако се затрудните или имате въпроси относно изграждането на AI приложения, присъединете се към: +Ако срещнете трудности или имате въпроси относно изграждането на AI приложения, присъединете се към: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Ако имате обратна връзка за продукта или грешки при изграждането, посетете: +Ако имате обратна връзка за продукта или грешки при създаване, посетете: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) @@ -143,6 +144,6 @@ --- -**Дисклеймър**: -Този документ е преведен с помощта на AI услуга за превод [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален превод от човек. Ние не носим отговорност за каквито и да е неразбирателства или неправилни тълкувания, произтичащи от използването на този превод. +**Отказ от отговорност**: +Този документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. \ No newline at end of file diff --git a/translations/bg/docs/GLOSSARY.md b/translations/bg/docs/GLOSSARY.md index d13876671..286e0a6ad 100644 --- a/translations/bg/docs/GLOSSARY.md +++ b/translations/bg/docs/GLOSSARY.md @@ -1,50 +1,50 @@ -# LangChain4j Речник +# Речник на LangChain4j ## Съдържание -- [Основни понятия](../../../docs) -- [Компоненти на LangChain4j](../../../docs) -- [AI/ML понятия](../../../docs) -- [Гардрейли](../../../docs) -- [Примерно инженерство](../../../docs) -- [RAG (Генерация с подсилено извличане)](../../../docs) -- [Агенти и Инструменти](../../../docs) -- [Агентски модул](../../../docs) -- [Протокол за контекст на модела (MCP)](../../../docs) -- [Azure услуги](../../../docs) -- [Тестване и разработка](../../../docs) +- [Основни понятия](#основни-понятия) +- [Компоненти на LangChain4j](#компоненти-на-langchain4j) +- [Понятия в AI/ML](#понятия-в-aiml) +- [Защитни механизми](#защитни-механизми) +- [Инженерство на подсказки](#prompt-engineering---module-02) +- [RAG (Генериране с извличане)](#rag-retrieval-augmented-generation---module-03) +- [Агенти и инструменти](#agents-and-tools---module-04) +- [Agentic модул](#agentic-module---module-05) +- [Протокол за контекст на модела (MCP)](#model-context-protocol-mcp---module-05) +- [Azure услуги](#azure-services---module-01) +- [Тестване и разработка](#testing-and-development---testing-guide) Бърза справка за термини и понятия, използвани в целия курс. ## Основни понятия -**AI агент** - Система, която използва AI за разсъждение и автономно действие. [Модул 04](../04-tools/README.md) +**AI агент** - Система, която използва AI за автономно разсъждение и действие. [Модул 04](../04-tools/README.md) -**Верига** - Последователност от операции, където изходът подава информация към следващата стъпка. +**Верига** - Последователност от операции, където изходът на една стъпка е вход за следващата. -**Разбиване на части** - Разделяне на документи на по-малки парчета. Обичайно: 300-500 токена с припокриване. [Модул 03](../03-rag/README.md) +**Разделяне на части** - Разбиване на документи на по-малки парчета. Обичайно: 300-500 токена с припокриване. [Модул 03](../03-rag/README.md) -**Контекст прозорец** - Максимален брой токени, които модел може да обработи. GPT-5.2: 400К токена (до 272К вход, 128К изход). +**Контекстно окно** - Максимален брой токени, които моделът може да обработи. GPT-5.2: 400К токена (до 272К вход, 128К изход). -**Вграждания** - Числови вектори, представящи значението на текста. [Модул 03](../03-rag/README.md) +**Вграждания** - Числени вектори, които представят значението на текста. [Модул 03](../03-rag/README.md) -**Извикване на функции** - Модел генерира структурирани заявки за извикване на външни функции. [Модул 04](../04-tools/README.md) +**Извикване на функции** - Моделът генерира структуриран заявки за извикване на външни функции. [Модул 04](../04-tools/README.md) -**Халюцинация** - Когато моделите генерират неверни, но правдоподобни информации. +**Халюцинация** - Когато моделите генерират неправилна, но правдоподобна информация. -**Подканване** - Текстов вход към езиков модел. [Модул 02](../02-prompt-engineering/README.md) +**Подсказка** - Текстов вход за езиков модел. [Модул 02](../02-prompt-engineering/README.md) **Семантично търсене** - Търсене по значение, използвайки вграждания, не ключови думи. [Модул 03](../03-rag/README.md) -**Състояние със и без съхранение** - Без съхранение: без памет. Съхранение: поддържа история на разговора. [Модул 01](../01-introduction/README.md) +**Състояние с/без памет** - Без памет: няма история. С памет: пази история на разговора. [Модул 01](../01-introduction/README.md) -**Токени** - Основни текстови единици, които моделите обработват. Влияят на разходи и ограничения. [Модул 01](../01-introduction/README.md) +**Токени** - Основни текстови единици, които моделите обработват. Влияят върху разходи и лимити. [Модул 01](../01-introduction/README.md) -**Верига от инструменти** - Последователно изпълнение на инструменти, където изходът информира следващото извикване. [Модул 04](../04-tools/README.md) +**Верижно използване на инструменти** - Последователно изпълнение на инструменти, където изходът информира следващото извикване. [Модул 04](../04-tools/README.md) ## Компоненти на LangChain4j -**AiServices** - Създава тип-безопасни AI интерфейси за услуги. +**AiServices** - Създава типово защитени интерфейси за AI услуги. **OpenAiOfficialChatModel** - Унифициран клиент за модели на OpenAI и Azure OpenAI. @@ -54,17 +54,17 @@ **ChatMemory** - Поддържа история на разговора. -**ContentRetriever** - Намира релевантни парчета документи за RAG. +**ContentRetriever** - Намира релевантни части от документи за RAG. -**DocumentSplitter** - Разделя документи на парчета. +**DocumentSplitter** - Разбива документи на части. -**EmbeddingModel** - Преобразува текст в числови вектори. +**EmbeddingModel** - Преобразува текст в числени вектори. **EmbeddingStore** - Съхранява и извлича вграждания. -**MessageWindowChatMemory** - Поддържа плъзгащ прозорец с последни съобщения. +**MessageWindowChatMemory** - Поддържа плъзгащо окно с последните съобщения. -**PromptTemplate** - Създава многократно използваеми подканвания с `{{variable}}` плейсхолдъри. +**PromptTemplate** - Създава използваеми подсказки с плейсхолдъри `{{variable}}`. **TextSegment** - Текстов сегмент с метаданни. Използва се в RAG. @@ -72,161 +72,159 @@ **UserMessage / AiMessage / SystemMessage** - Типове съобщения в разговор. -## AI/ML понятия +## Понятия в AI/ML -**Обучение с малко примери (Few-Shot Learning)** - Даване на примери в подканите. [Модул 02](../02-prompt-engineering/README.md) +**Обучение с малко примери** - Даване на примери в подсказките. [Модул 02](../02-prompt-engineering/README.md) -**Голям езиков модел (LLM)** - AI модели, обучени върху огромно количество текстови данни. +**Голям езиков модел (LLM)** - AI модели, обучени на големи обеми текст. **Усилие за разсъждение** - Параметър на GPT-5.2, контролиращ дълбочината на мислене. [Модул 02](../02-prompt-engineering/README.md) -**Температура** - Контролира случайността на изхода. Ниска=детерминистичен, висока=креативен. +**Температура** - Контролира случайност на изхода. Ниска=детерминирана, висока=креативна. **Векторна база данни** - Специализирана база данни за вграждания. [Модул 03](../03-rag/README.md) -**Обучение без примери (Zero-Shot Learning)** - Изпълнение на задачи без примери. [Модул 02](../02-prompt-engineering/README.md) +**Обучение без примери** - Изпълнение на задачи без примери. [Модул 02](../02-prompt-engineering/README.md) -## Гардрейли - [Модул 00](../00-quick-start/README.md) +## Защитни механизми -**Защита на множество нива** - Многостепенен подход към сигурността, комбиниращ гардрейли на приложенско ниво с филтри за безопасност на доставчика. +**Защита на дълбочина** - Многослоен подход за сигурност, комбиниращ защитни механизми на приложението с филтри на доставчиците. -**Твърдо блокиране** - Доставчикът връща грешка HTTP 400 при тежки нарушения на съдържанието. +**Жестко блокиране** - Доставчик връща HTTP 400 грешка при тежки нарушения на съдържанието. -**InputGuardrail** - Интерфейс в LangChain4j за валидиране на входа от потребителя преди да достигне LLM. Спестява разходи и латентност като блокира вредните подканвания рано. +**InputGuardrail** - LangChain4j интерфейс за валидиране на входни данни от потребителя преди достигане до LLM. Пести разходи и забавяне, като спира вредни подсказки рано. -**InputGuardrailResult** - Тип на връщана стойност при валидация на гардрейл: `success()` или `fatal("причина")`. +**InputGuardrailResult** - Тип връщане за валидация: `success()` или `fatal("причина")`. -**OutputGuardrail** - Интерфейс за валидиране на AI отговори преди връщането им към потребителите. +**OutputGuardrail** - Интерфейс за валидиране на AI отговори преди връщане към потребители. -**Филтри за безопасност на доставчика** - Вградени филтри за съдържание от AI доставчици (например GitHub Models), които хващат нарушения на API ниво. +**Филтри за безопасност на доставчика** - Вградени филтри за съдържание от доставчици на AI (например Azure OpenAI), които засичат нарушения на ниво API. -**Меко отказване** - Моделът любезно отказва да отговори без да хвърля грешка. +**Меко отказване** - Моделът учтиво отказва да отговори без да връща грешка. -## Примерно инженерство - [Модул 02](../02-prompt-engineering/README.md) +## Инженерство на подсказки - [Модул 02](../02-prompt-engineering/README.md) -**Верига на мисълта** - Стъпка по стъпка разсъждение за по-добра точност. +**Веригата на мисълта** - Стъпка по стъпка разсъждение за по-добра точност. -**Ограничен изход** - Налагане на специфичен формат или структура. +**Ограничен изход** - Налагане на конкретен формат или структура. -**Висока амбиция** - Шаблон на GPT-5.2 за задълбочено разсъждение. +**Висока настойчивост** - Модел на GPT-5.2 за задълбочено разсъждение. -**Ниска амбиция** - Шаблон на GPT-5.2 за бързи отговори. +**Ниска настойчивост** - Модел на GPT-5.2 за бързи отговори. -**Многоходов разговор** - Поддържане на контекста през обмените. +**Разговор с множество ходове** - Поддържане на контекст през обмените. -**Ролево подканване** - Настройване на персонажа на модела чрез системни съобщения. +**Подсказване според ролята** - Задаване на персонаж на модела чрез системни съобщения. **Саморефлексия** - Моделът оценява и подобрява своя изход. -**Структурен анализ** - Фиксирана рамка за оценка. +**Структуриран анализ** - Фиксирана рамка за оценяване. -**Шаблон за изпълнение на задача** - Планиране → Изпълнение → Обобщаване. +**Модел за изпълнение на задачи** - Планиране → Изпълнение → Обобщаване. -## RAG (Генерация с подсилено извличане) - [Модул 03](../03-rag/README.md) +## RAG (Генериране с извличане) - [Модул 03](../03-rag/README.md) **Пайплайн за обработка на документи** - Зареждане → разделяне → вграждане → съхранение. -**Вграждане в паметта** - Непостоянно съхранение за тестване. +**In-Memory Embedding Store** - Неперсистентно хранилище за тестване. -**RAG** - Комбинира извличането с генерация за по-задържани отговори. +**RAG** - Комбинира извличане и генериране за обосновани отговори. **Оценка за сходство** - Мярка (0-1) за семантична прилика. **Източник на референция** - Метаданни за извлечено съдържание. -## Агенти и Инструменти - [Модул 04](../04-tools/README.md) +## Агенти и инструменти - [Модул 04](../04-tools/README.md) -**@Tool анотация** - Маркира Java методи като AI-извиквани инструменти. +**@Tool Аннотация** - Маркира Java методи като AI-инструменти. -**ReAct шаблон** - Разсъждение → Действие → Наблюдение → Повторение. +**ReAct модел** - Разсъждение → Действие → Наблюдение → Повторение. **Управление на сесии** - Отделни контексти за различни потребители. **Инструмент** - Функция, която AI агент може да извика. -**Описание на инструмента** - Документация на предназначението и параметрите. +**Описание на инструмент** - Документация за цел и параметри на инструмента. -## Агентски модул - [Модул 05](../05-mcp/README.md) +## Agentic модул - [Модул 05](../05-mcp/README.md) -**@Agent анотация** - Маркира интерфейси като AI агенти с декларативно определение на поведението. +**@Agent Аннотация** - Маркира интерфейси като AI агенти с декларативно дефиниране на поведение. -**Agent Listener** - Захват за наблюдение на изпълнението на агента чрез `beforeAgentInvocation()` и `afterAgentInvocation()`. +**Agent Listener** - Прикачване за наблюдение на изпълнението на агента чрез `beforeAgentInvocation()` и `afterAgentInvocation()`. -**Agentic обхват** - Споделена памет, където агентите съхраняват изходи с `outputKey` за консуматори. +**Agentic Scope** - Споделена памет, където агентите съхраняват изходите с `outputKey`, които други агенти използват. **AgenticServices** - Фабрика за създаване на агенти чрез `agentBuilder()` и `supervisorBuilder()`. -**Условен поток на работа** - Маршрутизиране по условия към различни специализирани агенти. +**Условен работен поток** - Рутинг към различни специализирани агенти според условия. -**Човек във веригата** - Шаблон на работа с добавяне на човешки контролни точки за одобрение или преглед на съдържанието. +**Човек в цикъла** - Модел за работен поток, добавящ човешки проверки за одобрение или преглед на съдържание. -**langchain4j-agentic** - Maven зависимост за декларативно изграждане на агенти (експериментален). +**langchain4j-agentic** - Maven зависимост за декларативно изграждане на агенти (експериментална). -**Цикличен поток на работа** - Итеративно изпълнение на агент до постигане на условие (например оценка за качество ≥ 0.8). +**Цикличен работен поток** - Итеративно изпълнение на агент докато условие не е изпълнено (напр. оценка ≥ 0.8). -**outputKey** - Параметър в анотация на агент, указващ къде се съхраняват резултатите в Agentic обхвата. +**outputKey** - Параметър на анотация Agent, указващ къде се съхраняват резултатите в Agentic Scope. -**Паралелен поток на работа** - Изпълнение на няколко агента паралелно за независими задачи. +**Паралелен работен поток** - Пуска няколко агента едновременно за независими задачи. -**Стратегия за отговор** - Как супервайзор формулира крайния отговор: ПОСЛЕДЕН, ОБОБЩЕНИЕ или ОЦЕНЕН. +**Стратегия за отговор** - Как супервайзорът формулира окончателния отговор: LAST, SUMMARY или SCORED. -**Последователен поток на работа** - Изпълнение на агенти подред, където изхода тече към следващата стъпка. +**Последователен работен поток** - Изпълнение на агенти последователно, с подаване на изхода към следващия. -**Шаблон за супервизионен агент** - Напреднал агентски шаблон, при който супервайзор LLM динамично решава кои подагенти да извика. +**Supervisor Agent Pattern** - Разширен патърн, при който супервайзор LLM динамично решава кои подагенти да извика. ## Протокол за контекст на модела (MCP) - [Модул 05](../05-mcp/README.md) **langchain4j-mcp** - Maven зависимост за интеграция на MCP в LangChain4j. -**MCP** - Протокол за контекст на модела: стандарт за свързване на AI приложения с външни инструменти. Сглоби веднъж, използвай навсякъде. +**MCP** - Протокол за контекст на модела: стандарт за свързване на AI приложения с външни инструменти. Изграждаш веднъж, ползваш навсякъде. -**MCP клиент** - Приложение, което се свързва с MCP сървъри за да открива и използва инструменти. +**MCP клиент** - Приложение, което се свързва към MCP сървъри за откриване и използване на инструменти. -**MCP сървър** - Услуга, която излага инструменти чрез MCP с ясни описания и схеми на параметрите. +**MCP сървър** - Услуга, която предлага инструменти през MCP с ясни описания и параметърни схеми. **McpToolProvider** - Компонент на LangChain4j, който опакова MCP инструменти за използване в AI услуги и агенти. -**McpTransport** - Интерфейс за MCP комуникация. Имплементации включват Stdio и HTTP. +**McpTransport** - Интерфейс за комуникация по MCP. Изпълнения: Stdio и HTTP. -**Stdio Транспорт** - Локален транспорт през stdin/stdout. Полезен за достъп до файловата система или командни инструменти. +**Stdio транспорт** - Локален процесен транспорт през stdin/stdout. Полезно за достъп до файлова система или командни инструменти. -**StdioMcpTransport** - Имплементация в LangChain4j, която стартира MCP сървър като подпроцес. +**StdioMcpTransport** - LangChain4j изпълнение, което стартира MCP сървър като подпроцес. -**Откриване на инструменти** - Клиентът пита сървъра за наличните инструменти с описания и схеми. +**Откриване на инструменти** - Клиентската заявка към сървъра за налични инструменти с описания и схеми. ## Azure услуги - [Модул 01](../01-introduction/README.md) **Azure AI Search** - Облачна търсачка с векторни възможности. [Модул 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Разгръща Azure ресурси. +**Azure Developer CLI (azd)** - Инструмент за разгръщане на Azure ресурси. -**Azure OpenAI** - Предприятен AI сервис на Microsoft. +**Azure OpenAI** - Предприятелска AI услуга на Microsoft. -**Bicep** - Език за инфраструктура като код в Azure. [Ръководство за инфраструктура](../01-introduction/infra/README.md) +**Bicep** - Език за инфраструктура като код на Azure. [Инфраструктурно ръководство](../01-introduction/infra/README.md) **Име на разгръщане** - Име за разгръщане на модел в Azure. -**GPT-5.2** - Най-нов модел на OpenAI с контрол на разсъждението. [Модул 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Най-нов модел на OpenAI с контрол на разсъжденията. [Модул 02](../02-prompt-engineering/README.md) ## Тестване и разработка - [Ръководство за тестване](TESTING.md) **Dev Container** - Контейнеризирана среда за разработка. [Конфигурация](../../../.devcontainer/devcontainer.json) -**GitHub модели** - Безплатен AI модел за експериментиране. [Модул 00](../00-quick-start/README.md) - -**Тестване в паметта** - Тестване с използване на памет за съхранение. +**Тестване с памет в процеса** - Тестване с in-memory сторидж. **Интеграционно тестване** - Тестване с реална инфраструктура. -**Maven** - Инструмент за автоматизация на компилация на Java. +**Maven** - Инструмент за автоматизация на Java сборки. -**Mockito** - Фреймуърк за мокване в Java. +**Mockito** - Java framework за мока. -**Spring Boot** - Фреймуърк за Java приложения. [Модул 01](../01-introduction/README.md) +**Spring Boot** - Java платформа за приложения. [Модул 01](../01-introduction/README.md) --- **Отказ от отговорност**: -Този документ е преведен с помощта на AI преводаческа услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. +Този документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. \ No newline at end of file diff --git a/translations/bg/docs/TESTING.md b/translations/bg/docs/TESTING.md index f09611510..0c800bbea 100644 --- a/translations/bg/docs/TESTING.md +++ b/translations/bg/docs/TESTING.md @@ -1,16 +1,16 @@ -# Тестове на приложения LangChain4j +# Тестване на приложения LangChain4j ## Съдържание -- [Бърз старт](../../../docs) -- [Какво покриват тестовете](../../../docs) -- [Изпълнение на тестовете](../../../docs) -- [Изпълнение на тестове в VS Code](../../../docs) -- [Тестови модели](../../../docs) -- [Философия на тестване](../../../docs) -- [Следващи стъпки](../../../docs) +- [Бърз старт](#бърз-старт) +- [Какво покриват тестовете](#какво-покриват-тестовете) +- [Стартиране на тестовете](#стартиране-на-тестовете) +- [Стартиране на тестове в VS Code](#стартиране-на-тестове-в-vs-code) +- [Патерни за тестване](#патерни-за-тестване) +- [Философия на тестването](#философия-на-тестването) +- [Следващи стъпки](#следващи-стъпки) -Това ръководство ви показва тестовете, които демонстрират как да тествате AI приложения без нужда от API ключове или външни услуги. +Този наръчник ви води през тестовете, които демонстрират как да тествате AI приложения без нужда от API ключове или външни услуги. ## Бърз старт @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Когато всички тестове преминат, трябва да видите изход като този на екрана по-долу — тестовете стартират без нито една грешка. +Когато всички тестове преминат, трябва да видите изход подобен на екрана по-долу – тестовете се изпълняват без грешки. Successful Test Results -*Успешно изпълнение на тестове, показващо всички тестове с нулеви грешки* +*Успешно изпълнение на тестовете показва всички тестове с нулеви грешки* ## Какво покриват тестовете -Този курс се фокусира върху **униктестове**, които се изпълняват локално. Всеки тест демонстрира конкретна концепция на LangChain4j поотделно. Тестовата пирамида по-долу показва къде се вписват униктестовете — те формират бързата, надеждна основа, върху която се градят останалите тестови стратегии. +Този курс се фокусира върху **юнит тестове**, които се изпълняват локално. Всеки тест демонстрира конкретна концепция на LangChain4j изолирано. Пирамидата на тестване по-долу показва къде се вписват юнит тестовете — те образуват бързата и надеждна основа, върху която се гради останалата част от стратегията за тестване. Testing Pyramid -*Тестова пирамида, показваща баланса между униктестове (бързи, изолирани), интеграционни тестове (реални компоненти) и end-to-end тестове. Това обучение обхваща униктестове.* +*Пирамида на тестването показва баланса между юнит тестове (бързи, изолирани), интеграционни тестове (реални компоненти) и end-to-end тестове. Това обучение покрива юнит тестване.* -| Модул | Тестове | Фокус | Основни файлове | +| Модул | Тестове | Фокус | Ключови файлове | |--------|-------|-------|-----------| -| **00 - Бърз старт** | 6 | Шаблони на подканите и заместване на променливи | `SimpleQuickStartTest.java` | -| **01 - Въведение** | 8 | Памет за разговори и потребителски чат със състояние | `SimpleConversationTest.java` | -| **02 - Проектиране на подканите** | 12 | Модели GPT-5.2, нива на ентусиазъм, структурирана изходна информация | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Въвеждане на документи, ембединг, търсене по сходство | `DocumentServiceTest.java` | +| **01 - Въведение** | 8 | Памет за разговор и състояние на чат | `SimpleConversationTest.java` | +| **02 - Проектиране на подсказки** | 12 | GPT-5.2 патерни, нива на желаност, структурирано изходно съдържание | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Въвеждане на документи, embeddings, търсене по сходство | `DocumentServiceTest.java` | | **04 - Инструменти** | 12 | Извикване на функции и свързване на инструменти | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Протокол за моделния контекст с stdio транспорт | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | Протокол за контекст на модел с Stdio транспорт | `SimpleMcpTest.java` | -## Изпълнение на тестовете +## Стартиране на тестовете -**Стартирайте всички тестове от корена:** +**Стартирайте всички тестове от основната директория:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Стартиране само на един тестов клас:** +**Стартиране на единичен тестов клас:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Стартиране само на определен тестов метод:** +**Стартиране на конкретен тестов метод:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#трябва да се поддържа история на разговора +mvn test -Dtest=SimpleConversationTest#трябваДаСеПоддържаИсторияНаРазговорите ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#трябва да се запази историята на разговора +mvn --% test -Dtest=SimpleConversationTest#трябва да се поддържа история на разговора ``` -## Изпълнение на тестове в VS Code +## Стартиране на тестове в VS Code -Ако използвате Visual Studio Code, Test Explorer осигурява графичен интерфейс за стартиране и дебъгване на тестове. +Ако използвате Visual Studio Code, Test Explorer предоставя графичен интерфейс за стартиране и отстраняване на грешки в тестовете. VS Code Test Explorer -*VS Code Test Explorer, показващ дървото с всички Java тестови класове и отделните тестови методи* +*Test Explorer на VS Code показва дървото на тестовете с всички Java тестови класове и индивидуални тестови методи* **За да стартирате тестове в VS Code:** -1. Отворете Test Explorer, като кликнете върху иконата с епруветка в лентата с активности -2. Разгънете тестовото дърво, за да видите всички модули и тестови класове -3. Натиснете бутона за пускане до всеки тест, за да го стартирате поотделно -4. Натиснете "Run All Tests", за да изпълните целия комплект -5. Кликнете с десен бутон върху тест и изберете "Debug Test", за да зададете точки на прекъсване и стъпите през кода +1. Отворете Test Explorer, като кликнете върху иконата на химикалка в лентата с активности +2. Разгънете дървото с тестове, за да видите всички модули и тестови класове +3. Кликнете бутона за пускане до всеки тест, за да го стартирате индивидуално +4. Кликнете "Run All Tests", за да изпълните всички тестове +5. Щракнете с десен бутон върху тест и изберете "Debug Test", за да зададете прекъсвания и да стъпвате през кода -Test Explorer показва зелени отметки за успешни тестове и предоставя подробни съобщения при неуспех. +Test Explorer показва зелени отметки за преминали тестове и дава подробни съобщения за грешки при неуспешни тестове. -## Тестови модели +## Патерни за тестване -### Модел 1: Тестване на шаблони за подканите +### Патерн 1: Тестване на шаблони за подсказки -Най-простият модел тества шаблони за подканите без извикване на AI модел. Проверявате дали заместването на променливите работи правилно и дали подканите са форматирани както се очаква. +Най-простият патерн тества шаблони за подсказки, без да извиква AI модел. Потвърждавате, че заместването на променливи работи правилно и подсказките са форматирани както се очаква. Prompt Template Testing -*Тестване на шаблони за подканите, показващо процеса на заместване на променливите: шаблон с плейсхолдъри → прилагане на стойности → проверка на форматирания изход* +*Тестване на шаблони за подсказки показва поток на заместване на променливи: шаблон с плейсхолдъри → приложени стойности → проверен форматиран изход* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Този тест е в `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Този патерн потвърждава, че заместването на променливи работи правилно и подсказките са форматирани както се очаква — не се изисква API ключ или извикване на модел. -**Стартирайте го:** +### Патерн 2: Мокване на езикови модели -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#форматиране на тестов шаблон за подкана -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#тестване на форматирането на шаблона на подканата -``` - -### Модел 2: Симулиране на езикови модели - -При тестване на логиката на разговор използвайте Mockito за създаване на фалшиви модели, които връщат предварително определени отговори. Това прави тестовете бързи, безплатни и детерминирани. +При тестване на логиката на разговор използвайте Mockito за създаване на фалшиви модели, които връщат предварително зададени отговори. Това прави тестовете бързи, безплатни и детерминистични. Mock vs Real API Comparison -*Сравнение, което показва защо симулациите са предпочитани за тестване: те са бързи, безплатни, детерминирани и не изискват API ключове* +*Сравнение показва защо моковете са предпочитани за тестване: те са бързи, безплатни, детерминистични и не изискват API ключове* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 съобщения от потребител + 3 съобщения от изкуствен интелект + assertThat(history).hasSize(6); // 3 съобщения от потребител + 3 съобщения от AI } } ``` -Този модел се използва в `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Симулаторът гарантира последователно поведение, така че да може да проверите дали управлението на паметта работи правилно. +Този патерн се среща в `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Мокът гарантира последователно поведение, за да може да проверите, че управлението на паметта работи правилно. -### Модел 3: Тестване на изолацията на разговори +### Патерн 3: Тестване на изолацията на разговора -Паметта за разговори трябва да държи потребителите отделно. Този тест проверява, че разговорите не смесват контексти. +Паметта за разговор трябва да поддържа отделни масиви за множество потребители. Този тест потвърждава, че разговорите не смесват контексти. Conversation Isolation -*Тестване на изолацията на разговори, показващо отделни хранилища за памет за различни потребители, за да се предотврати смесването на контексти* +*Тестване на изолацията на разговора показва отделни хранилища за памет за различни потребители, за да се предотврати смесването на контексти* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Всеки разговор поддържа своя самостоятелна история. В производствени системи тази изолация е критична за приложения с много потребители. +Всеки разговор поддържа собствена независима история. В производствени системи тази изолация е критична за многопотребителски приложения. -### Модел 4: Тестване на инструменти поотделно +### Патерн 4: Самостоятелно тестване на инструменти -Инструментите са функции, които AI може да извиква. Тествайте ги директно, за да се уверите, че работят правилно независимо от решенията на AI. +Инструментите са функции, които AI може да извика. Тествайте ги директно, за да сте сигурни, че работят правилно независимо от решенията на AI. Tools Testing -*Тестване на инструменти поотделно, показващо изпълнението на симулирани инструменти без извиквания към AI за проверка на бизнес логиката* +*Самостоятелно тестване на инструменти показва изпълнение на мок инструменти без AI извиквания, за да се валидира бизнес логиката* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Тези тестове от `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` валидират логиката на инструментите без участие на AI. Примерът с веригата показва как изходът на един инструмент се използва като вход за друг. +Тези тестове от `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` валидират логиката на инструментите без AI включване. Примерът с веригата показва как изходът на един инструмент се подава като вход на друг. -### Модел 5: Тестване на RAG в паметта +### Патерн 5: Тестване на RAG в паметта -RAG системите традиционно изискват векторни бази данни и embedding услуги. Моделът в паметта ви позволява да тествате цялата конвейерна линия без външни зависимости. +Системите RAG обикновено изискват векторни бази данни и embedding услуги. Патернът в паметта ви позволява да тествате цялата верига без външни зависимости. In-Memory RAG Testing -*Техника за тестване на RAG в паметта, показваща парсване на документи, съхранение на ембединг и търсене по сходство без необходимост от база данни* +*Работен процес на тестване на RAG в паметта, показващ парсване на документи, съхранение на embeddings и търсене по сходство без нужда от база данни* ```java @Test @@ -306,11 +293,11 @@ void testProcessTextDocument() { } ``` -Този тест от `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` създава документ в паметта и проверява раздробяването му и обработката на метаданни. +Този тест от `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` създава документ в паметта и проверява разбиването на части и обработката на метаданни. -### Модел 6: Интеграционно тестване на MCP +### Патерн 6: Интеграционно тестване на MCP -MCP модулът тества интеграцията на Model Context Protocol с използване на stdio транспорт. Тези тестове проверяват дали вашето приложение може да стартира и комуникира с MCP сървъри като подпроцеси. +Модулът MCP тества интеграцията на Протокола за контекст на модел с помощта на stdio транспорт. Тези тестове потвърждават, че вашето приложение може да стартира и комуникира с MCP сървъри като подпроцеси. Тестовете в `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` валидират поведението на MCP клиента. @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## Философия на тестване +## Философия на тестването -Тествайте вашия код, а не AI-то. Вашите тестове трябва да валидират кода, който пишете, чрез проверка как са построени подканите, как се управлява паметта и как се изпълняват инструментите. Отговорите на AI варират и не трябва да са част от твърденията на тестовете. Запитайте се дали вашият шаблон за подканата правилно замества променливите, а не дали AI-то дава правилен отговор. +Тествайте вашия код, не AI. Вашите тестове трябва да валидират кода, който пишете, като проверяват как са конструирани подсказките, как се управлява паметта и как се изпълняват инструментите. Отговорите на AI варират и не трябва да бъдат част от твърденията в тестовете. Попитайте се дали вашият шаблон за подсказка правилно замества променливите, а не дали AI дава правилния отговор. -Използвайте симулатори за езикови модели. Те са външни зависимости, които са бавни, скъпи и недетерминирани. Симулирането прави тестовете бързи с милисекунди вместо секунди, безплатни с нулеви API разходи и детерминирани с един и същ резултат всеки път. +Използвайте мокове за езиковите модели. Те са външни зависимости, които са бавни, скъпи и недетерминистични. Мокването прави тестовете бързи с милисекунди вместо секунди, безплатни без разходи за API и детерминистични с един и същ резултат всеки път. -Дръжте тестовете независими. Всеки тест трябва да създава собствените си данни, да не разчита на други тестове и да се почиства след себе си. Тестовете трябва да преминават независимо от реда на изпълнение. +Дръжте тестовете независими. Всеки тест трябва да създава собствените си данни, да не разчита на други тестове и да се почиства след себе си. Тестовете трябва да минават независимо от реда на изпълнение. -Тествайте краените случаи извън щастливия път. Опитайте с празни входове, много големи входове, специални символи, невалидни параметри и гранични условия. Те често разкриват бъгове, които не се появяват при нормално ползване. +Тествайте крайни случаи извън успешния път. Пробвайте празни входове, много големи входове, специални символи, невалидни параметри и гранични условия. Те често разкриват бъгове, които нормалната употреба не показва. -Използвайте описателни имена. Сравнете `shouldMaintainConversationHistoryAcrossMultipleMessages()` с `test1()`. Първото казва точно какво се тества, което улеснява намирането на грешки. +Използвайте описателни имена. Сравнете `shouldMaintainConversationHistoryAcrossMultipleMessages()` с `test1()`. Първото ви казва точно какво се тества, което прави отстраняването на грешки много по-лесно. ## Следващи стъпки -Сега, когато разбирате тестовите модели, потопете се по-дълбоко във всеки модул: +Сега, когато разбирате патерните за тестване, навлезте по-дълбоко във всеки модул: -- **[00 - Бърз старт](../00-quick-start/README.md)** - Започнете с основите на шаблоните за подканите -- **[01 - Въведение](../01-introduction/README.md)** - Научете управлението на паметта за разговори -- **[02 - Проектиране на подканите](../02/prompt-engineering/README.md)** - Овладейте моделите за подканите на GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Изградете системи за генерация с повишаване чрез извличане +- **[01 - Въведение](../01-introduction/README.md)** - Научете управление на паметта за разговори +- **[02 - Проектиране на подсказки](../02/prompt-engineering/README.md)** - Овладейте патерните за подсказки на GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Строите системи за генериране с помощта на извличане - **[04 - Инструменти](../04-tools/README.md)** - Имплементирайте извикване на функции и вериги от инструменти -- **[05 - MCP](../05-mcp/README.md)** - Интегрирайте Model Context Protocol +- **[05 - MCP](../05-mcp/README.md)** - Интегрирайте Протокола за контекст на модел -README файловете на всеки модул съдържат подробни обяснения на концепциите, тествани тук. +README файловете на всеки модул предоставят подробни обяснения на концепциите, тестващи се тук. --- -**Навигация:** [← Обратно към главната](../README.md) +**Навигация:** [← Обратно към Основната страница](../README.md) --- -**Отказ от отговорност**: -Този документ е преведен с помощта на AI преводаческа услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за никакви недоразумения или погрешни тълкувания, произтичащи от използването на този превод. +**Отказ от отговорност**: +Този документ е преведен с помощта на AI преводачески услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод. \ No newline at end of file diff --git a/translations/bn/.co-op-translator.json b/translations/bn/.co-op-translator.json index 4c832b8dc..e720d36c3 100644 --- a/translations/bn/.co-op-translator.json +++ b/translations/bn/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "bn" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T20:55:07+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T13:09:37+00:00", "source_file": "01-introduction/README.md", "language_code": "bn" }, @@ -18,20 +18,20 @@ "language_code": "bn" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T20:59:44+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T13:03:54+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "bn" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T21:01:50+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T13:08:29+00:00", "source_file": "03-rag/README.md", "language_code": "bn" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:56:13+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T13:06:47+00:00", "source_file": "04-tools/README.md", "language_code": "bn" }, @@ -54,8 +54,8 @@ "language_code": "bn" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:46:48+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T13:02:08+00:00", "source_file": "README.md", "language_code": "bn" }, @@ -72,14 +72,14 @@ "language_code": "bn" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T21:06:36+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T13:04:33+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "bn" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T21:07:35+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T13:05:13+00:00", "source_file": "docs/TESTING.md", "language_code": "bn" } diff --git a/translations/bn/00-quick-start/README.md b/translations/bn/00-quick-start/README.md deleted file mode 100644 index bbbd944ad..000000000 --- a/translations/bn/00-quick-start/README.md +++ /dev/null @@ -1,388 +0,0 @@ -# মডিউল ০০: দ্রুত শুরু - -## বিষয়সূচি - -- [পরিচিতি](#পরিচিতি) -- [LangChain4j কী?](#langchain4j-কী) -- [LangChain4j নির্ভরশীলতা](#langchain4j-নির্ভরশীলতা) -- [প্রয়োজনীয়তা](#প্রয়োজনীয়তা) -- [সেটআপ](#সেটআপ) - - [১. আপনার GitHub টোকেন পান](#১-আপনার-github-টোকেন-পান) - - [২. আপনার টোকেন সেট করুন](#২-আপনার-টোকেন-সেট-করুন) -- [উদাহরণ চালান](#উদাহরণ-চালান) - - [১. বেসিক চ্যাট](#১-বেসিক-চ্যাট) - - [২. প্রম্পট প্যাটার্ন](#২-প্রম্পট-প্যাটার্ন) - - [৩. ফাংশন কলিং](#৩-ফাংশন-কলিং) - - [৪. ডকুমেন্ট প্রশ্নোত্তর (সহজ RAG)](#৪-ডকুমেন্ট-প্রশ্নোত্তর-সহজ-rag) - - [৫. দায়িত্বশীল AI](#৫-দায়িত্বশীল-ai) -- [প্রতিটি উদাহরণ কী দেখায়](#প্রতিটি-উদাহরণ-কী-দেখায়) -- [পরবর্তী ধাপ](#পরবর্তী-ধাপ) -- [সমস্যা সমাধান](#সমস্যা-সমাধান) - -## পরিচিতি - -এই দ্রুতশুরুর উদ্দেশ্য হল LangChain4j দিয়ে যত দ্রুত সম্ভব শুরু করতে সাহায্য করা। এটি LangChain4j এবং GitHub মডেল ব্যবহার করে AI অ্যাপ্লিকেশন তৈরির মৌলিক বিষয়গুলো কভার করে। পরবর্তী মডিউলগুলোতে আপনি Azure OpenAI এবং GPT-5.2 এ বদল করবেন এবং প্রতিটি ধারণায় আরও গভীরভাবে প্রবেশ করবেন। - -## LangChain4j কী? - -LangChain4j একটি জাভা লাইব্রেরি যা AI চালিত অ্যাপ্লিকেশন তৈরি করা সহজ করে তোলে। HTTP ক্লায়েন্ট এবং JSON পার্সিং নিয়ে কাজ করার পরিবর্তে আপনি পরিষ্কার জাভা API ব্যবহার করেন। - -LangChain এ "চেইন" বলতে একাধিক কম্পোনেন্ট একসাথে যুক্ত করা বোঝায় - আপনি একটি প্রম্পটকে একটি মডেল বা পার্সারের সাথে চেইন করতে পারেন, অথবা একাধিক AI কল একত্র করে একটির আউটপুট অন্যটির ইনপুট হিসেবে ব্যবহার করতে পারেন। এই দ্রুতশুরু মৌলিক বিষয়গুলোর উপর গুরুত্ব দেয়, জটিল চেইনগুলো অনুসন্ধানের আগে। - -LangChain4j Chaining Concept - -*LangChain4j-এর কম্পোনেন্ট চেইনিং - ব্লকগুলো যুক্ত হয়ে শক্তিশালী AI ওয়ার্কফ্লো নির্মাণ করে* - -আমরা তিনটি প্রধান কম্পোনেন্ট ব্যবহার করব: - -**ChatModel** - AI মডেল ইন্টারঅ্যাকশনের ইন্টারফেস। `model.chat("prompt")` কল করুন এবং একটি রেসপন্স স্ট্রিং পান। আমরা `OpenAiOfficialChatModel` ব্যবহার করি যা OpenAI-সঙ্গতিপূর্ণ এন্ডপয়েন্ট যেমন GitHub মডেলগুলোর সাথে কাজ করে। - -**AiServices** - টাইপ-সেফ AI সার্ভিস ইন্টারফেস তৈরি করে। মেথডগুলো ডিফাইন করুন, `@Tool` দিয়ে অ্যানোটেট করুন, LangChain4j সংগঠন পরিচালনা করে। AI প্রয়োজন হলে আপনার জাভা মেথডগুলো স্বয়ংক্রিয়ভাবে কল করে। - -**MessageWindowChatMemory** - কথোপকথনের ইতিহাস সংরক্ষণ করে। এটা না থাকলে প্রতিটি অনুরোধ স্বতন্ত্র থাকে। এটা থাকলে AI পূর্ববর্তী মেসেজ মনে রাখে এবং একাধিক রাউন্ডের মধ্যে প্রসঙ্গ বজায় রাখে। - -LangChain4j Architecture - -*LangChain4j আর্কিটেকচার - মূল কম্পোনেন্টগুলো একসাথে কাজ করে আপনার AI অ্যাপ্লিকেশন চালায়* - -## LangChain4j নির্ভরশীলতা - -এই দ্রুতশুরুতে তিনটি Maven নির্ভরশীলতা ব্যবহার করা হয়েছে [`pom.xml`](../../../00-quick-start/pom.xml) এ: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` মডিউলটি `OpenAiOfficialChatModel` ক্লাস সরবরাহ করে যা OpenAI-সঙ্গতিপূর্ণ API-তে সংযোগ করে। GitHub মডেল একই API ফরম্যাট ব্যবহার করে, তাই কোনো বিশেষ অ্যাডাপ্টারের দরকার নেই - শুধু বেস URL `https://models.github.ai/inference` এ পয়েন্ট করুন। - -`langchain4j-easy-rag` মডিউলটি স্বয়ংক্রিয় ডকুমেন্ট বিভাজন, এমবেডিং এবং অনুসন্ধান সরবরাহ করে যাতে আপনি ম্যানুয়ালি প্রতিটি ধাপ কনফিগার না করেই RAG অ্যাপ্লিকেশন তৈরি করতে পারেন। - -## প্রয়োজনীয়তা - -**ডেভ কন্টেনার ব্যবহার করছেন?** Java এবং Maven আগ থেকেই ইনস্টল করা আছে। শুধু একটি GitHub পার্সোনাল অ্যাক্সেস টোকেনের দরকার। - -**লোকাল ডেভেলপমেন্ট:** -- Java 21+, Maven 3.9+ -- GitHub পার্সোনাল অ্যাক্সেস টোকেন (নির্দেশনা নিচে) - -> **বি:দ্রঃ** এই মডিউল GitHub মডেলের `gpt-4.1-nano` ব্যবহার করে। কোডে মডেল নাম পরিবর্তন করবেন না - এটি GitHub-এর উপলব্ধ মডেলের সাথে কাজ করার জন্য কনফিগার করা হয়েছে। - -## সেটআপ - -### ১. আপনার GitHub টোকেন পান - -1. যান [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. "Generate new token" ক্লিক করুন -3. বর্ণনামূলক নাম দিন (যেমন, "LangChain4j Demo") -4. মেয়াদ নির্ধারণ করুন (৭ দিন সুপারিশ করা হয়) -5. "Account permissions" এর নিচে "Models" খুঁজে সেট করুন "Read-only" -6. "Generate token" ক্লিক করুন -7. আপনার টোকেন কপি করে সংরক্ষণ করুন - এটি আবার দেখা যাবে না - -### ২. আপনার টোকেন সেট করুন - -**অপশন ১: VS Code ব্যবহার (সর্বোত্তম)** - -আপনি যদি VS Code ব্যবহার করেন, তাহলে প্রকল্পের মূল ফোল্ডারে `.env` ফাইলে আপনার টোকেন যোগ করুন: - -যদি `.env` ফাইল না থাকে, `.env.example` থেকে কপি করে `.env` তৈরি করুন অথবা নতুন `.env` ফাইল তৈরি করুন। - -**উদাহরণ `.env` ফাইল:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env এ -GITHUB_TOKEN=your_token_here -``` - -এরপর ব্যবসেব হালকা ডেমো ফাইল (যেমন `BasicChatDemo.java`) এর উপর রাইট-ক্লিক করে **"Run Java"** নির্বাচন করুন অথবা Run and Debug প্যানেল থেকে লঞ্চ কনফিগারেশন ব্যবহার করুন। - -**অপশন ২: টার্মিনাল ব্যবহার করুন** - -টোকেনকে পরিবেশ ভেরিয়েবল হিসেবে সেট করুন: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## উদাহরণ চালান - -**VS Code ব্যবহার:** ব্যবসেব হালকা ডেমো ফাইলের ওপর রাইট-ক্লিক করে **"Run Java"** নির্বাচন করুন অথবা Run and Debug প্যানেল থেকে লঞ্চ কনফিগারেশন ব্যবহার করুন (আদ্যপর্যন্ত আপনার টোকেন `.env` ফাইলে যোগ করা রয়েছে কিনা নিশ্চিত করুন)। - -**Maven ব্যবহার:** বিকল্প হিসেবে, কমান্ড লাইন থেকে চালাতে পারেন: - -### ১. বেসিক চ্যাট - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### ২. প্রম্পট প্যাটার্ন - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -জিরো-শট, ফিউ-শট, চেইন-অফ-থট এবং রোল-ভিত্তিক প্রম্পটিং দেখানো হয়েছে। - -### ৩. ফাংশন কলিং - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI যেকোনো সময় আপনার জাভা মেথডগুলো স্বয়ংক্রিয়ভাবে কল করে। - -### ৪. ডকুমেন্ট প্রশ্নোত্তর (সহজ RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -সহজ RAG ব্যবহার করে স্বয়ংক্রিয় এমবেডিং এবং পুনরুদ্ধারের মাধ্যমে আপনার ডকুমেন্ট সম্পর্কে প্রশ্ন করুন। - -### ৫. দায়িত্বশীল AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -কীভাবে AI নিরাপত্তা ফিল্টার ক্ষতিকর সামগ্রী ব্লক করে দেখুন। - -## প্রতিটি উদাহরণ কী দেখায় - -**বেসিক চ্যাট** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -এখান থেকেই LangChain4j এর সবচেয়ে সহজ রূপ দেখুন। আপনি `OpenAiOfficialChatModel` তৈরি করবেন, `.chat()` দিয়ে একটি প্রম্পট পাঠাবেন, এবং উত্তর পাবেন। এটি দেখায় কিভাবে কাস্টম এন্ডপয়েন্ট এবং API কী দিয়ে মডেল ইনিশিয়ালাইজ করবেন। যখন আপনি এই প্যাটার্ন বুঝবেন, তখন বাকিটা সহজ। - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 GitHub Copilot-এর সাথে চেষ্টা করুন:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) খুলুন এবং জিজ্ঞাসা করুন: -> - "এই কোডে GitHub মডেল থেকে Azure OpenAI কিভাবে সুইচ করবো?" -> - "OpenAiOfficialChatModel.builder() এ আর কোন প্যারামিটার কনফিগার করা যায়?" -> - "কিভাবে সম্পূর্ণ রেসপন্সের অপেক্ষায় না থেকে স্ট্রিমিং রেসপন্স যোগ করব?" - -**প্রম্পট ইঞ্জিনিয়ারিং** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -এখন আপনি জানেন কিভাবে মডেলের সাথে কথা বলতে হয়, দেখা যাক কীভাবে প্রম্পট দিন। এই ডেমো একই মডেল সেটআপ ব্যবহার করে কিন্তু পাঁচটি ভিন্ন প্রম্পট প্যাটার্ন দেখায়। জিরো-শট সরাসরি নির্দেশনার জন্য, কয়েকটি উদাহরণ থেকে শেখার জন্য ফিউ-শট, যুক্তি-ধারা প্রকাশ করার জন্য চেইন-অফ-থট, এবং প্রসঙ্গ নির্ধারণের জন্য রোল-ভিত্তিক প্রম্পট ব্যবহার করুন। একই মডেল কীভাবে প্রম্পট ফ্রেমিং অনুসারে আলাদা ফলাফল দেয় আপনি দেখবেন। - -ডেমোটিতে প্রম্পট টেমপ্লেটও দেখানো হয়েছে, যা ভ্যারিয়েবলসহ পুনঃব্যবহারযোগ্য প্রম্পট তৈরির শক্তিশালী উপায়। - -নিচের উদাহরণে LangChain4j `PromptTemplate` ব্যবহার করে ভ্যারিয়েবল পূরণ করা হয়েছে। AI প্রদত্ত গন্তব্য এবং কার্যক্রমের ভিত্তিতে উত্তর দেবে। - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 GitHub Copilot-এর সাথে চেষ্টা করুন:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) খুলুন এবং জিজ্ঞাসা করুন: -> - "জিরো-শট এবং ফিউ-শট প্রম্পটের পার্থক্য কী, এবং কখন কোনটি ব্যবহার করব?" -> - "মডেলের রেসপন্সে তাপমাত্রা প্যারামিটার কীভাবে প্রভাব ফেলে?" -> - "প্রম্পট ইনজেকশন আক্রমণ প্রতিরোধে কী কী প্রযুক্তি প্রয়োগ করা যায়?" -> - "সাধারণ প্যাটার্নের জন্য কিভাবে পুনঃব্যবহারযোগ্য PromptTemplate অবজেক্ট তৈরি করবো?" - -**টুল ইন্টিগ্রেশন** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -এখানেই LangChain4j শক্তিশালী হয়। আপনি `AiServices` ব্যবহার করে একটি AI সহকারী তৈরি করবেন যা আপনার জাভা মেথডগুলো কল করতে পারে। মেথডগুলোকে `@Tool("description")` দিয়ে অ্যানোটেট করুন এবং বাকিটা LangChain4j পরিচালনা করবে - AI স্বয়ংক্রিয়ভাবে সিদ্ধান্ত নেবে কখন কোন টুল ব্যবহার করতে হবে। এটি ফাংশন কলিং এর প্রমাণ, যা AI কে শুধু প্রশ্নের উত্তর দেয়ার পাশাপাশি কাজ করার জন্য সক্ষম করে। - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 GitHub Copilot-এর সাথে চেষ্টা করুন:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) খুলুন এবং জিজ্ঞাসা করুন: -> - "@Tool অ্যানোটেশন কিভাবে কাজ করে এবং LangChain4j এর ভিতরে এই বিষয়টি কিভাবে পরিচালিত হয়?" -> - "AI কি জটিল সমস্যার সমাধানে একাধিক টুল ক্রমশ কল করতে পারে?" -> - "যদি কোনো টুল এক্সসেপশন দেয়, তাহলে কীভাবে এরর হ্যান্ডেল করবো?" -> - "এই ক্যালকুলেটর উদাহরণের পরিবর্তে কিভাবে বাস্তব API ইন্টিগ্রেট করবো?" - -**ডকুমেন্ট প্রশ্নোত্তর (সহজ RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -এখানে LangChain4j-এর "সহজ RAG" পদ্ধতি ব্যবহার করে RAG (রিট্রিভাল-অগমেন্টেড জেনারেশন) দেখতে পারবেন। ডকুমেন্টগুলো লোড হয়, স্বয়ংক্রিয়ভাবে বিভক্ত ও এমবেড করে ইন-মেমোরি স্টোরে রাখা হয়, তারপর একটি কনটেন্ট রিট্রিভার AI-কে প্রশ্নের সময় উপযুক্ত অংশ সরবরাহ করে। AI আপনার ডকুমেন্টের ভিত্তিতে উত্তর দেয়, তার সাধারণ জ্ঞানের ভিত্তিতে নয়। - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 GitHub Copilot-এর সাথে চেষ্টা করুন:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) খুলুন এবং জিজ্ঞাসা করুন: -> - "RAG কিভাবে AI হলুসিনেশনের প্রতিরোধ করে মডেলের প্রশিক্ষণ ডেটার তুলনায়?" -> - "এই সহজ পদ্ধতি আর একটি কাস্টম RAG পাইপলাইনের মধ্যে পার্থক্য কী?" -> - "কিভাবে আমি একাধিক ডকুমেন্ট বা বড় জ্ঞানভিত্তি পরিচালনা করতে এটি স্কেল করবো?" - -**দায়িত্বশীল AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -গভীর ডিফেন্স নিয়ে AI নিরাপত্তা তৈরি করুন। এই ডেমো দুটি পর্যায়ের সুরক্ষা একসাথে কাজ করে দেখায়: - -**অংশ ১: LangChain4j ইনপুট গার্ডরেলস** - LLM-এ পৌঁছানোর আগে বিপজ্জনক প্রম্পট ব্লক করে। নিজের কাস্টম গার্ডরেলস তৈরি করুন যা নিষিদ্ধ কীওয়ার্ড বা প্যাটার্ন পরীক্ষা করে। এগুলো আপনার কোডে চলে, তাই দ্রুত এবং বিনামূল্যে। - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**অংশ ২: প্রদানকারী নিরাপত্তা ফিল্টার** - GitHub মডেল বিল্ট-ইন ফিল্টার আছে যা আপনার গার্ডরেলস মিস করতে পারে এমন বিষয়গুলো খোঁজে। কঠোর ব্লক (HTTP 400 এরর) ও মৃদু প্রত্যাখ্যান যেখানে AI ভদ্রভাবে প্রত্যাখ্যান করে, উভয়ই দেখবেন। - -> **🤖 GitHub Copilot-এর সাথে চেষ্টা করুন:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) খুলুন এবং জিজ্ঞাসা করুন: -> - "InputGuardrail কী এবং নিজস্ব কিভাবে তৈরি করব?" -> - "কঠোর ব্লক আর মৃদু প্রত্যাখ্যানের পার্থক্য কী?" -> - "কেন গার্ডরেলস ও প্রদানকারী ফিল্টার একসঙ্গে ব্যবহার করা উচিৎ?" - -## পরবর্তী ধাপ - -**পরবর্তী মডিউল:** [০১-পরিচিতি - LangChain4j ব্যবহার শুরু করা](../01-introduction/README.md) - ---- - -**নেভিগেশন:** [← প্রধান পৃষ্ঠায় ফিরে যান](../README.md) | [পরবর্তী: মডিউল ০১ - পরিচিতি →](../01-introduction/README.md) - ---- - -## সমস্যা সমাধান - -### প্রথমবার Maven বিল্ড - -**সমস্যা:** প্রথমবারের `mvn clean compile` বা `mvn package` অনেক সময় নেয় (১০-১৫ মিনিট) - -**কারণ:** Maven প্রথম বিল্ডে সমস্ত প্রজেক্ট নির্ভরশীলতা (Spring Boot, LangChain4j লাইব্রেরি, Azure SDK ইত্যাদি) ডাউনলোড করে। - -**সমাধান:** এটি স্বাভাবিক। পরবর্তী বিল্ডগুলি দ্রুত হবে কারণ নির্ভরশীলতাগুলো লোকাল ক্যাশে থাকে। ডাউনলোডের সময় আপনার নেটওয়ার্ক স্পিডের ওপর নির্ভর করে। - -### PowerShell Maven কমান্ড সিনট্যাক্স - -**সমস্যা:** Maven কমান্ডে `Unknown lifecycle phase ".mainClass=..."` এরর আসে। -**কারণ**: PowerShell `=` কে ভেরিয়েবল এসাইনমেন্ট অপারেটর হিসাবে ব্যাখ্যা করে, যা Maven প্রপার্টি সিনট্যাক্স ভঙ্গ করে - -**সমাধান**: Maven কমান্ডের আগে স্টপ-পার্সিং অপারেটর `--%` ব্যবহার করুন: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` অপারেটর PowerShell কে নির্দেশ দেয় বাকি সমস্ত আর্গুমেন্ট গুলো Maven এ লিটারালি পাঠাতে, ব্যাখ্যা না করেই। - -### Windows PowerShell Emoji প্রদর্শন - -**সমস্যা**: PowerShell এ AI রেসপন্সে ইমোজির পরিবর্তে কোলাহল চরিত্র (যেমন `????` বা `â??`) দেখানো হয় - -**কারণ**: PowerShell এর ডিফল্ট এনকোডিং UTF-8 ইমোজি সমর্থন করে না - -**সমাধান**: Java অ্যাপ্লিকেশন চালানোর আগে এই কমান্ডটি রান করুন: -```cmd -chcp 65001 -``` - -এটি টার্মিনালে UTF-8 এনকোডিং বাধ্যতামূলক করে। বিকল্পভাবে, Windows Terminal ব্যবহার করুন যেটি উন্নত ইউনিকোড সমর্থন করে। - -### API কল ডিবাগিং - -**সমস্যা**: অথেনটিকেশন ত্রুটি, রেট লিমিট, বা AI মডেল থেকে অনাকাঙ্ক্ষিত রেসপন্স - -**সমাধান**: উদাহরণগুলোতে `.logRequests(true)` এবং `.logResponses(true)` রয়েছে যা কনসোলে API কলগুলো প্রদর্শন করে। এটি অথেনটিকেশন ত্রুটি, রেট লিমিট, বা অনাকাঙ্ক্ষিত রেসপন্স ডিবাগ করতে সহায়তা করে। লগ জট কমানোর জন্য প্রোডাকশনে এই ফ্ল্যাগগুলো সরিয়ে ফেলুন। - ---- - - -**অস্বীকৃতি**: -এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা শুদ্ধতার জন্য চেষ্টা করি, অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার স্বভাষায় কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে প্রয়োজনীয় ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই। - \ No newline at end of file diff --git a/translations/bn/01-introduction/README.md b/translations/bn/01-introduction/README.md index 6fab7fcd9..f8ba70f38 100644 --- a/translations/bn/01-introduction/README.md +++ b/translations/bn/01-introduction/README.md @@ -1,38 +1,38 @@ # মডিউল ০১: LangChain4j দিয়ে শুরু করা -## বিষয়বস্তু - -- [ভিডিও ওয়াকথ্রু](../../../01-introduction) -- [আপনি যা শিখবেন](../../../01-introduction) -- [প্রয়োজনীয়তা](../../../01-introduction) -- [মূল সমস্যা বোঝা](../../../01-introduction) -- [টোকেন বোঝা](../../../01-introduction) -- [মেমোরি কীভাবে কাজ করে](../../../01-introduction) -- [LangChain4j কীভাবে ব্যবহার করে](../../../01-introduction) -- [Azure OpenAI পরিকাঠামো ডেপ্লয় করুন](../../../01-introduction) -- [অ্যাপ্লিকেশন লোকালি চালান](../../../01-introduction) -- [অ্যাপ্লিকেশন ব্যবহার](../../../01-introduction) - - [স্টেটলেস চ্যাট (বাম প্যানেল)](../../../01-introduction) - - [স্টেটফুল চ্যাট (ডান প্যানেল)](../../../01-introduction) -- [পরবর্তী ধাপ](../../../01-introduction) +## বিষয়সূচি + +- [ভিডিও ওয়াকথ্রু](#ভিডিও-ওয়াকথ্রু) +- [আপনি কী শিখবেন](#আপনি-কী-শিখবেন) +- [প্রয়োজনীয়তা](#প্রয়োজনীয়তা) +- [মূল সমস্যা বোঝা](#মূল-সমস্যা-বোঝা) +- [টোকেন বোঝা](#টোকেন-বোঝা) +- [মেমোরি কীভাবে কাজ করে](#মেমোরি-কীভাবে-কাজ-করে) +- [এটি কীভাবে LangChain4j ব্যবহার করে](#এটি-কীভাবে-langchain4j-ব্যবহার-করে) +- [Azure OpenAI ইনফ্রাস্ট্রাকচার ডিপ্লয় করুন](#azure-openai-ইনফ্রাস্ট্রাকচার-ডিপ্লয়-করুন) +- [অ্যাপ্লিকেশন লোকালি চালান](#অ্যাপ্লিকেশন-লোকালি-চালান) +- [অ্যাপ্লিকেশন ব্যবহার করা](#অ্যাপ্লিকেশন-ব্যবহার-করা) + - [স্টেটলেস চ্যাট (বাম প্যানেল)](#স্টেটলেস-চ্যাট-বাম-প্যানেল) + - [স্টেটফুল চ্যাট (ডান প্যানেল)](#স্টেটফুল-চ্যাট-ডান-প্যানেল) +- [পরবর্তী ধাপসমূহ](#পরবর্তী-ধাপসমূহ) ## ভিডিও ওয়াকথ্রু -এই লাইভ সেশনটি দেখুন যা এই মডিউল দিয়ে শুরু করার পদ্ধতি ব্যাখ্যা করে: +এই লাইভ সেশনটি দেখুন যা কিভাবে এই মডিউল দিয়ে শুরু করবেন তা ব্যাখ্যা করে: Getting Started with LangChain4j - Live Session -## আপনি যা শিখবেন +## আপনি কী শিখবেন -কুইক স্টার্টে, আপনি GitHub মডেলগুলি ব্যবহার করে প্রম্পট পাঠিয়েছেন, টুল কল করেছেন, একটি RAG পাইপলাইন তৈরি করেছেন এবং গার্ডরেইলস পরীক্ষা করেছেন। সেই ডেমোগুলো দেখিয়েছিল কি সম্ভব — এখন আমরা Azure OpenAI এবং GPT-5.2-তে সুইচ করি এবং প্রোডাকশন-স্টাইল অ্যাপ্লিকেশন তৈরি শুরু করি। এই মডিউলটি এমন কথোপকথন AI-এর উপর ফোকাস করে যা প্রসঙ্গ স্মরণ করে এবং স্টেট রক্ষা করে — যা কুইক স্টার্ট ডেমোগুলোর পেছনে ছিল কিন্তু ব্যাখ্যা করা হয়নি। +এটি আপনার LangChain4j এবং Azure OpenAI দিয়ে শুরু করার পয়েন্ট। আমরা মৌলিক বিষয়গুলি দিয়ে শুরু করব এবং প্রোডাকশন-স্টাইল অ্যাপ্লিকেশন তৈরি শুরু করব। এই মডিউলটি কথোপকথনমূলক AI-তে ফোকাস করে যা প্রসঙ্গ মনে রাখে এবং স্টেট বজায় রাখে — এগুলো মৌলিক ধারণা যেগুলোর উপর পরবর্তী প্রতিটি মডিউল গড়ে উঠবে। -পুরো গাইডে আমরা Azure OpenAI-এর GPT-5.2 ব্যবহার করব কারণ এর উন্নত যুক্তিবিচার ক্ষমতা বিভিন্ন প্যাটার্নের আচরণ স্পষ্ট করে দেয়। যখন আপনি মেমোরি যোগ করবেন, আপনি স্পষ্টভাবে পার্থক্য দেখতে পাবেন। এটি প্রতিটি কম্পোনেন্ট আপনার অ্যাপ্লিকেশনে কী নিয়ে আসে বুঝতে সহজ করে। +আমরা এই গাইড জুড়ে Azure OpenAI-এর GPT-5.2 ব্যবহার করবো কারণ এর উন্নত যুক্তি ক্ষমতাগুলি বিভিন্ন প্যাটার্নের আচরণ আরও স্পষ্ট করে তোলে। যখন আপনি মেমোরি যোগ করবেন, তখন আপনি স্পষ্টভাবে পার্থক্য দেখতে পাবেন। এটি সহজ করে তোলে বুঝতে যে প্রতিটি উপাদান আপনার অ্যাপ্লিকেশনে কী নিয়ে আসে। -আপনি একটি অ্যাপ্লিকেশন তৈরি করবেন যা দুটি প্যাটার্নই দেখাবে: +আপনি একটি অ্যাপ্লিকেশন তৈরি করবেন যা দুটি প্যাটার্নই প্রদর্শন করে: -**স্টেটলেস চ্যাট** - প্রতিটি অনুরোধ পৃথক। মডেলের আগের বার্তার কোনো স্মৃতি নেই। এটি কুইক স্টার্টে ব্যবহৃত প্যাটার্ন। +**স্টেটলেস চ্যাট** - প্রতিটি অনুরোধ স্বাধীন। মডেলের পূর্বের বার্তার কোনো স্মৃতি নেই। এটি সবচেয়ে সহজ শুরু। -**স্টেটফুল কথোপকথন** - প্রতিটি অনুরোধে কথোপকথনের ইতিহাস অন্তর্ভুক্ত থাকে। মডেল একাধিক টার্ন জুড়ে প্রসঙ্গ বজায় রাখে। এটি প্রোডাকশন অ্যাপ্লিকেশনগুলোর জন্য প্রয়োজন। +**স্টেটফুল কথোপকথন** - প্রতিটি অনুরোধে কথোপকথনের ইতিহাস থাকে। মডেল একাধিক ধাপে প্রসঙ্গ বজায় রাখে। প্রোডাকশন অ্যাপ্লিকেশনগুলির জন্য এটি দরকার। ## প্রয়োজনীয়তা @@ -41,45 +41,45 @@ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **নোট:** Java, Maven, Azure CLI এবং Azure Developer CLI (azd) প্রদত্ত devcontainer-এ আগেই ইনস্টল করা আছে। +> **দ্রষ্টব্য:** Java, Maven, Azure CLI এবং Azure Developer CLI (azd) প্রদান করা devcontainer-এ আগেই ইনস্টল করা আছে। -> **নোট:** এই মডিউল Azure OpenAI তে GPT-5.2 ব্যবহার করে। ডিপ্লয়মেন্ট স্বয়ংক্রিয়ভাবে `azd up` দিয়ে কনফিগার করা হয় - কোডে মডেলের নাম পরিবর্তন করবেন না। +> **দ্রষ্টব্য:** এই মডিউল Azure OpenAI-র GPT-5.2 ব্যবহার করে। ডিপ্লয়মেন্ট স্বয়ংক্রিয়ভাবে `azd up` দ্বারা কনফিগার করা হয় — কোডে মডেল নাম পরিবর্তন করবেন না। ## মূল সমস্যা বোঝা -ভাষার মডেলগুলি স্টেটলেস। প্রতিটি API কল স্বতন্ত্র। আপনি যদি "আমার নাম জন" পাঠান এবং পরে জিজ্ঞেস করেন "আমার নাম কী?", মডেল জানে না আপনি মাত্রই পরিচয় দিয়েছেন। এটি প্রতিটি অনুরোধকে প্রথম কথোপকথনের মতো আচরণ করে। +ভাষা মডেলগুলো স্টেটলেস। প্রতিটি API কল স্বাধীন। আপনি যদি "আমার নাম জন" লেখেন এবং পরে জিজ্ঞেস করেন "আমার নাম কী?", মডেলটির কোন ধারণা নেই যে আপনি আপনার পরিচয় দিয়েছেন। এটি প্রতিটি অনুরোধ প্রথম কথোপকথনের মতো বিবেচনা করে। -এটি সহজ প্রশ্নোত্তরের জন্য ঠিক আছে কিন্তু বাস্তব অ্যাপ্লিকেশনের জন্য অকার্যকর। কাস্টমার সার্ভিস বটদের আপনাকে যা বলেছিলেন তা মনে রাখতে হয়। পার্সোনাল অ্যাসিস্ট্যান্টদের প্রসঙ্গ প্রয়োজন। যেকোনো বহু-টর্ণ কথোপকথনের জন্য মেমোরি দরকার। +এটি সাধারণ প্রশ্নোত্তরের জন্য ঠিক আছে কিন্তু বাস্তব অ্যাপ্লিকেশন জন্য অকার্যকর। কাস্টমার সার্ভিস বটকে আপনাকে যা বলেছিলেন তা মনে রাখতে হবে। ব্যক্তিগত সহকারীকে প্রসঙ্গ দরকার। যে কোনো বহু-ধাপে কথোপকথনের জন্য মেমোরি প্রয়োজন। -নিচের চিত্রটি দুটি পন্থার তুলনা করে — বামে একটি স্টেটলেস কল যা আপনার নাম ভুলে যায়; ডানে ChatMemory দ্বারা ব্যাকড স্টেটফুল কল যা তা মনে রাখে। +নিম্নলিখিত ডায়াগ্রামটি দুই পদ্ধতির পার্থক্য দেখায় — বামে, একটি স্টেটলেস কল যা আপনার নাম ভুলে যায়; ডানে, ChatMemory দ্বারা সমর্থিত স্টেটফুল কল যা নাম মনে রাখে। Stateless vs Stateful Conversations -*স্টেটলেস (স্বাধীন কল) এবং স্টেটফুল (প্রসঙ্গ-সচেতন) কথোপকথনের মধ্যে পার্থক্য* +*স্টেটলেস (স্বাধীন কল) এবং স্টেটফুল (প্রসঙ্গ-বিবেচনাযুক্ত) কথোপকথনের পার্থক্য* ## টোকেন বোঝা -কথোপকথনে যাওয়ার আগে, টোকেন বোঝা গুরুত্বপূর্ণ - টোকেন হল মৌলিক নিয়ামক যেগুলো ভাষার মডেল প্রক্রিয়াজাত করে: +কথোপকথনে প্রবেশ করার আগে, টোকেন বোঝা গুরুত্বপূর্ণ — টোকেন হলো মৌলিক লেখ্য একক যা ভাষা মডেল প্রক্রিয়া করে: Token Explanation -*কীভাবে টেক্সট টোকেনে বিভক্ত হয় তার উদাহরণ - "I love AI!" হয়ে গেছে ৪টি পৃথক প্রক্রিয়াকরণ ইউনিট* +*কিভাবে লেখা টোকেনে ভাগ হয় - "I love AI!" চারটি পৃথক প্রসেসিং ইউনিটে পরিণত হয়* -টোকেন হল কিভাবে AI মডেলগুলি টেক্সট পরিমাপ ও প্রক্রিয়া করে। শব্দ, বিরামচিহ্ন, এমনকি ফাঁকা স্থানও টোকেন হতে পারে। আপনার মডেলের একটি সীমা আছে কত টোকেন একবারে প্রক্রিয়া করতে পারে (GPT-5.2-এর জন্য ৪০০,০০০, যার মধ্যে সর্বোচ্চ ২৭২,০০০ ইনপুট টোকেন এবং ১২৮,০০০ আউটপুট টোকেন)। টোকেন বোঝা কথোপকথনের দৈর্ঘ্য এবং খরচ নিয়ন্ত্রণে সাহায্য করে। +টোকেন হল কিভাবে AI মডেল টেক্সট পরিমাপ এবং প্রক্রিয়া করে। শব্দ, বিরামচিহ্ন, এমনকি স্পেসও টোকেন হতে পারে। আপনার মডেলের একটি সীমা আছে কতটি টোকেন একবারে প্রক্রিয়া করা যায় (GPT-5.2-র জন্য ৪০০,০০০, যেখানে ইনপুট টোকেন সর্বোচ্চ ২৭২,০০০ এবং আউটপুট ১২৮,০০০)। টোকেন বুঝলে কথোপকথনের দৈর্ঘ্য এবং খরচ নিয়ন্ত্রণ সহজ হয়। ## মেমোরি কীভাবে কাজ করে -চ্যাট মেমোরি স্টেটলেস সমস্যার সমাধান করে কথোপকথনের ইতিহাস বজায় রেখে। মডেলে অনুরোধ পাঠানোর আগে ফ্রেমওয়ার্ক প্রাসঙ্গিক পূর্বের বার্তাগুলো যোগ করে। যখন আপনি "আমার নাম কী?" জিজ্ঞেস করেন, সিস্টেম আসলে পুরো কথোপকথনের ইতিহাস পাঠায়, যার ফলে মডেল দেখে আপনি আগে "আমার নাম জন" বলেছিলেন। +চ্যাট মেমোরি স্টেটলেস সমস্যার সমাধান করে কথোপকথনের ইতিহাস রক্ষা করে। মডেলে আপনার অনুরোধ পাঠানোর আগে ফ্রেমওয়ার্ক পূর্বের প্রাসঙ্গিক বার্তাগুলো যুক্ত করে। যখন আপনি জিজ্ঞেস করেন "আমার নাম কী?", সিস্টেম পুরো কথোপকথনের ইতিহাস মডেলে পাঠায়, যাতে মডেল দেখতে পারে আপনি আগে বলেছেন "আমার নাম জন।" -LangChain4j মেমোরি ইমপ্লিমেন্টেশনগুলো প্রদান করে যা এটি স্বয়ংক্রিয়ভাবে পরিচালনা করে। আপনি কতগুলি বার্তা রাখতে চান তা নির্বাচন করেন এবং ফ্রেমওয়ার্ক প্রসঙ্গ উইন্ডো পরিচালনা করে। নিচের ছবি দেখায় কীভাবে MessageWindowChatMemory সাম্প্রতিক বার্তাগুলোর একটি স্লাইডিং উইন্ডো বজায় রাখে। +LangChain4j মেমোরি বাস্তবায়ন সরবরাহ করে যা এটি স্বয়ংক্রিয়ভাবে পরিচালনা করে। আপনি কতজন বার্তা রাখা হবে বেছে নেন এবং ফ্রেমওয়ার্ক প্রসঙ্গ উইন্ডো ম্যানেজ করে। নিচের ডায়াগ্রামটি দেখায় কিভাবে MessageWindowChatMemory সাম্প্রতিক বার্তাগুলোর স্লাইডিং উইন্ডো বজায় রাখে। Memory Window Concept -*MessageWindowChatMemory সাম্প্রতিক বার্তাগুলোর একটি স্লাইডিং উইন্ডো বজায় রাখে, পুরনোগুলো স্বয়ংক্রিয়ভাবে ফেলে দেয়* +*MessageWindowChatMemory সাম্প্রতিক বার্তাগুলোর স্লাইডিং উইন্ডো বজায় রাখে, পুরানো বার্তাগুলো স্বয়ংক্রিয়ভাবে ফেলে দেয়* -## LangChain4j কীভাবে ব্যবহার করে +## এটি কীভাবে LangChain4j ব্যবহার করে -এই মডিউলটি কুইক স্টার্টকে বাড়িয়ে স্প্রিং বুট একত্রিত করে এবং কথোপকথন মেমোরি যোগ করে। উপাদানগুলি কিভাবে মেলানো হয় দেখুন: +এই মডিউলটি Spring Boot-কে একত্রিত করে এবং কথোপকথন মেমোরি যোগ করে। এখানে উপাদানগুলি কীভাবে একসাথে কাজ করে: **ডিপেন্ডেন্সি** - দুটি LangChain4j লাইব্রেরি যোগ করুন: @@ -94,7 +94,7 @@ LangChain4j মেমোরি ইমপ্লিমেন্টেশনগু ``` -**চ্যাট মডেল** - Azure OpenAI স্প্রিং বিন হিসেবে কনফিগার করুন ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**চ্যাট মডেল** - Azure OpenAI কে Spring bean হিসেবে কনফিগার করুন ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -বিল্ডার `azd up` দ্বারা সেট করা পরিবেশ ভেরিয়েবল থেকে ক্রেডেনশিয়াল পড়ে। `baseUrl` আপনার Azure এন্ডপয়েন্টে সেট করলে OpenAI ক্লায়েন্ট Azure OpenAI এর সাথে কাজ করে। +বিল্ডারটি পরিবেশ ভেরিয়েবল থেকে `azd up` দ্বারা সেট করা ক্রেডেনশিয়াল পড়ে। আপনার Azure এন্ডপয়েন্ট দিয়ে `baseUrl` সেট করলে OpenAI ক্লায়েন্ট Azure OpenAI-এর সাথে কাজ করে। -**কথোপকথনের মেমোরি** - MessageWindowChatMemory দিয়ে চ্যাট ইতিহাস ট্র্যাক করুন ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**কথোপকথন মেমোরি** - MessageWindowChatMemory দিয়ে চ্যাট ইতিহাস ট্র্যাক করুন ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,21 +124,21 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` দিয়ে মেমোরি তৈরি করুন, যা শেষ ১০টি বার্তা রাখবে। ইউজার এবং AI বার্তা যোগ করুন টাইপ্ড র‍্যাপার দিয়ে: `UserMessage.from(text)` এবং `AiMessage.from(text)`। ইতিহাস পুনরুদ্ধার করতে `memory.messages()` ব্যবহার করুন এবং মডেলে পাঠান। সার্ভিস প্রতিটি কথোপকথনের জন্য আলাদা মেমোরি ইন্সট্যান্স রাখে, যা একাধিক ব্যবহারকারীকে একযোগে চ্যাট করতে দেয়। +`withMaxMessages(10)` দিয়ে মেমোরি তৈরি করুন যাতে শেষ ১০ টা বার্তা থাকে। ব্যবহারকারী এবং AI বার্তাগুলো typed wrappers দিয়ে যোগ করুন: `UserMessage.from(text)` এবং `AiMessage.from(text)`। ইতিহাস পাওয়ার জন্য `memory.messages()` ব্যবহার করুন এবং এটি মডেলে পাঠান। সার্ভিস পৃথক কথোপকথন আইডি অনুসারে পৃথক মেমোরি ইনস্ট্যান্স সংরক্ষণ করে, ফলে অনেক ব্যবহারকারী একই সাথে চ্যাট করতে পারে। -> **🤖 GitHub Copilot চ্যাট ব্যবহার করে চেষ্টা করুন:** খুলুন [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) এবং জিজ্ঞেস করুন: -> - "MessageWindowChatMemory উইন্ডো পূর্ণ হলে কোন বার্তাগুলো ফেলে দেয় কিভাবে সিদ্ধান্ত নেয়?" -> - "আমি কি ইন-মেমোরির বদলে ডাটাবেস ব্যবহার করে কাস্টম মেমোরি স্টোরেজ বাস্তবায়ন করতে পারি?" -> - "পুরানো কথোপকথনের সারসংক্ষেপ যোগ করতে আমি কিভাবে করতে পারি?" +> **🤖 GitHub Copilot [চ্যাট](https://github.com/features/copilot) এর সাথে চেষ্টা করুন:** খুলুন [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) এবং জিজ্ঞাসা করুন: +> - "MessageWindowChatMemory উইন্ডো পূর্ণ হলে কোন বার্তাগুলো ফেলে দেওয়ার সিদ্ধান্ত কীভাবে নেয়?" +> - "আমি কি মেমোরির জন্য ইন-মেমোরির পরিবর্তে ডাটাবেজ ব্যবহার করে কাস্টম স্টোরেজ তৈরি করতে পারি?" +> - "পুরানো কথোপকথনের সারাংশ সংকলন যোগ করার জন্য কীভাবে কাজ করব?" -স্টেটলেস চ্যাট এন্ডপয়েন্ট পুরোপুরি মেমোরি এড়িয়ে চলে — সরাসরি `chatModel.chat(prompt)` ব্যবহার, কুইক স্টার্টের মতো। স্টেটফুল এন্ডপয়েন্ট মেমোরিতে বার্তা যোগ করে, ইতিহাস রিট্রিভ করে এবং প্রতিটি অনুরোধের সাথে প্রসঙ্গ অন্তর্ভুক্ত করে। একই মডেল কনফিগারেশন, ভিন্ন প্যাটার্ন। +স্টেটলেস চ্যাট এন্ডপয়েন্ট সম্পূর্ণ মেমোরি এড়িয়ে চলে — যেমন দ্রুত শুরুতে `chatModel.chat(prompt)`। স্টেটফুল এন্ডপয়েন্ট বার্তাগুলো মেমোরিতে যোগ করে, ইতিহাস রিট্রিভ করে এবং প্রতিটি অনুরোধে প্রসঙ্গ সহ পাঠায়। একই মডেল কনফিগারেশন, ভিন্ন প্যাটার্ন। -## Azure OpenAI পরিকাঠামো ডেপ্লয় করুন +## Azure OpenAI ইনফ্রাস্ট্রাকচার ডিপ্লয় করুন **Bash:** ```bash cd 01-introduction -azd up # সাবস্ক্রিপশন এবং অবস্থান নির্বাচন করুন (eastus2 সুপারিশ করা হয়েছে) +azd up # সাবস্ক্রিপশন এবং অবস্থান নির্বাচন করুন (eastus2 পরামর্শ দেওয়া হয়) ``` **PowerShell:** @@ -147,20 +147,20 @@ cd 01-introduction azd up # সাবস্ক্রিপশন এবং অবস্থান নির্বাচন করুন (eastus2 প্রস্তাবিত) ``` -> **নোট:** যদি আপনি টাইমআউট ত্রুটি পান (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), শুধু পুনরায় `azd up` চালান। Azure রিসোর্স এখনো ব্যাকগ্রাউন্ডে provisioning-এ থাকতে পারে, পুনরায় চেষ্টা করলে রিসোর্স সম্পূর্ণ হলে ডেপ্লয়মেন্ট সম্পন্ন হয়। +> **দ্রষ্টব্য:** যদি টাইমআউট ত্রুটি (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) পাওয়া যায়, তবে আবার `azd up` চালান। Azure রিসোর্সগুলি পেছনে এখনও প্রস্তুত হচ্ছে, পুনরায় চেষ্টা করলে রিসোর্সসমূহ চূড়ান্ত অবস্থায় পৌঁছালে ডিপ্লয়মেন্ট সম্পন্ন হবে। এটি করবে: -1. GPT-5.2 এবং text-embedding-3-small মডেল সহ Azure OpenAI রিসোর্স ডেপ্লয়। -2. প্রজেক্ট রুটে স্বয়ংক্রিয়ভাবে `.env` ফাইল তৈরি যেটিতে ক্রেডেনশিয়াল থাকবে। -3. প্রয়োজনীয় সব পরিবেশ ভেরিয়েবল সেটআপ। +1. GPT-5.2 এবং text-embedding-3-small মডেলসহ Azure OpenAI রিসোর্স ডিপ্লয় করবে +2. প্রকল্প মূল ডিরেক্টরিতে স্বয়ংক্রিয় `.env` ফাইল জেনারেট করবে ক্রেডেনশিয়ালসহ +3. সমস্ত প্রয়োজনীয় পরিবেশ ভেরিয়েবল সেট করবে -**ডেপ্লয়মেন্ট সমস্যার সম্মুখীন?** বিস্তারিত ট্রাবলশুটিং এর জন্য [Infrastructure README](infra/README.md) দেখুন, যেখানে সাবডোমেইন নাম দ্বন্দ্ব, ম্যানুয়াল Azure Portal ডেপ্লয়মেন্ট ধাপ এবং মডেল কনফিগারেশন গাইডেন্স রয়েছে। +**ডিপ্লয়মেন্টে সমস্যা হচ্ছে?** বিস্তারিত সমস্যার সমাধানের জন্য [Infrastructure README](infra/README.md) দেখুন — সাবডোমেইন নাম দ্বন্দ্ব, ম্যানুয়াল Azure Portal ডিপ্লয়মেন্ট পদক্ষেপ, এবং মডেল কনফিগারেশন নির্দেশিকা সহ। -**ডেপ্লয়মেন্ট সফল হয়েছে কিনা যাচাই করুন:** +**ডিপ্লয়মেন্ট সফল হয়েছে কী না যাচাই করুন:** **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY ইত্যাদি দেখানো উচিত। +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, ইত্যাদি দেখানো উচিত। ``` **PowerShell:** @@ -168,30 +168,29 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY ইত্যাদি দেখা Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, ইত্যাদি দেখানো উচিত। ``` -> **নোট:** `azd up` স্বয়ংক্রিয় `.env` ফাইল তৈরি করে। পরে যদি আপডেট প্রয়োজন হয়, আপনি ম্যানুয়ালি `.env` ফাইল এডিট করতে পারেন অথবা পুনরায় জেনারেট করতে পারেন: +> **দ্রষ্টব্য:** `azd up` কমান্ড স্বয়ংক্রিয়ভাবে `.env` ফাইল তৈরি করে। পরে আপডেট করতে চাইলে `.env` ফাইল ম্যানুয়ালি সম্পাদনা করুন অথবা পুনরায় তৈরি করতে চালান: > > **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` - +> > **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` - ## অ্যাপ্লিকেশন লোকালি চালান -**ডেপ্লয়মেন্ট যাচাই করুন:** +**ডিপ্লয়মেন্ট যাচাই করুন:** -রুট ডিরেক্টরিতে `.env` ফাইল আছে কিনা এবং এর মধ্যে Azure ক্রেডেনশিয়াল সঠিক আছে নিশ্চিত করুন। মডিউল ডিরেক্টরি থেকে চালান (`01-introduction/`): +মূল ডিরেক্টরিতে `.env` ফাইল আছে এবং Azure ক্রেডেনশিয়াল সেট আছে নিশ্চিত করুন। মডিউল ডিরেক্টরিতে (`01-introduction/`) থেকে এটি চালান: **Bash:** ```bash -cat ../.env # দেখাতে হবে AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT দেখানো উচিত ``` **PowerShell:** @@ -199,31 +198,31 @@ cat ../.env # দেখাতে হবে AZURE_OPENAI_ENDPOINT, API_KEY, DEPL Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT দেখানো উচিত ``` -**অ্যাপ্লিকেশনগুলি শুরু করুন:** +**অ্যাপ্লিকেশন শুরু করুন:** -**বিকল্প ১: স্প্রিং বুট ড্যাশবোর্ড ব্যবহার (VS Code ব্যবহারকারীদের জন্য সুপারিশকৃত)** +**অপশন ১: Spring Boot ড্যাশবোর্ড ব্যবহার (VS Code ব্যবহারকারীদের জন্য সুপারিশ)** -ডেভ কন্টেইনারে স্প্রিং বুট ড্যাশবোয়ার্ড এক্সটেনশন অন্তর্ভুক্ত, যা সব স্প্রিং বুট অ্যাপ্লিকেশন পরিচালনার ভিজ্যুয়াল ইন্টারফেস দেয়। এটি VS Code এর বামে Activity Bar-এ (স্প্রিং বুট আইকন দেখুন) পাওয়া যাবে। +devcontainer-এ Spring Boot ড্যাশবোর্ড এক্সটেনশন অন্তর্ভুক্ত আছে, যা সব Spring Boot অ্যাপ্লিকেশন ম্যানেজ করার ভিজ্যুয়াল ইন্টারফেস দেয়। VS Code-এর বামে Activity Bar-এ Spring Boot আইকন দেখতে পাবেন। -স্প্রিং বুট ড্যাশবোর্ড থেকে: -- ওয়ার্কস্পেসের সব স্প্রিং বুট অ্যাপ্লিকেশন দেখুন -- এক ক্লিকে অ্যাপ্লিকেশন শুরু/বন্ধ করুন -- রিয়েল-টাইম অ্যাপ্লিকেশন লগ দেখুন -- অ্যাপ্লিকেশন স্ট্যাটাস মনিটর করুন +Spring Boot ড্যাশবোর্ড থেকে আপনি: +- ওয়ার্কস্পেসের সব Spring Boot অ্যাপ্লিকেশন দেখতে পারেন +- এক ক্লিকে অ্যাপ্লিকেশন শুরু/বন্ধ করতে পারেন +- রিয়েল-টাইমে অ্যাপ্লিকেশন লগ দেখতে পারেন +- অ্যাপ্লিকেশন স্থিতি পর্যবেক্ষণ করতে পারেন -"introduction" এর পাশে থাকা প্লে বাটনে ক্লিক করে এই মডিউল শুরু করুন, অথবা সব মডিউল একসাথে চালু করুন। +শুধুমাত্র "introduction" পাশে প্লে বাটনে ক্লিক করে এই মডিউল শুরু করুন, অথবা একবারে সব মডিউল শুরু করুন। Spring Boot Dashboard -*VS Code-এ স্প্রিং বুট ড্যাশবোর্ড — সব মডিউল এক জায়গা থেকে চালু, বন্ধ এবং মনিটর করুন* +*VS Code-এ Spring Boot ড্যাশবোর্ড — এক জায়গা থেকে সব মডিউল শুরু, বন্ধ, পর্যবেক্ষণ করুন* -**বিকল্প ২: শেল স্ক্রিপ্ট ব্যবহার** +**অপশন ২: শেল স্ক্রিপ্ট ব্যবহার** -সকল ওয়েব অ্যাপ্লিকেশন শুরু করুন (মডিউল ০১-০৪): +সব ওয়েব অ্যাপ্লিকেশন (মডিউল ০১-০৪) শুরু করুন: **Bash:** ```bash -cd .. # মূল ডিরেক্টরি থেকে +cd .. # রুট ডিরেক্টরি থেকে ./start-all.sh ``` @@ -233,7 +232,7 @@ cd .. # রুট ডিরেক্টরি থেকে .\start-all.ps1 ``` -অথবা শুধুমাত্র এই মডিউল চালান: +অথবা কেবল এই মডিউল শুরু করুন: **Bash:** ```bash @@ -247,79 +246,77 @@ cd 01-introduction .\start.ps1 ``` -উভয় স্ক্রিপ্ট স্বয়ংক্রিয়ভাবে রুট `.env` ফাইল থেকে পরিবেশ ভেরিয়েবল লোড করে এবং JAR তৈরি না থাকলে তৈরি করবে। +উভয় স্ক্রিপ্ট মূল `.env` ফাইল থেকে পরিবেশ ভেরিয়েবলগুলি স্বয়ংক্রিয়ভাবে লোড করে এবং JAR না থাকলে এটি তৈরি করবে। -> **নোট:** যদি আপনি ম্যানুয়ালি সব মডিউল বিল্ড করতে চান শুরু করার আগে: +> **দ্রষ্টব্য:** আপনি যদি হাতে হাতে সব মডিউল তৈরি করতে চান তারপর শুরু করতে চান: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` +আপনার ব্রাউজারে http://localhost:8080 খুলুন। -ব্রাউজারে http://localhost:8080 খুলুন। - -**বন্ধ করার জন্য:** +**বন্ধ করতে:** **Bash:** ```bash ./stop.sh # এই মডিউল শুধুমাত্র # অথবা -cd .. && ./stop-all.sh # সব মডিউলগুলি +cd .. && ./stop-all.sh # সমস্ত মডিউলগুলি ``` **PowerShell:** ```powershell .\stop.ps1 # শুধুমাত্র এই মডিউল # অথবা -cd ..; .\stop-all.ps1 # সকল মডিউল +cd ..; .\stop-all.ps1 # সমস্ত মডিউল ``` +## অ্যাপ্লিকেশন ব্যবহার করা -## অ্যাপ্লিকেশন ব্যবহার - -অ্যাপ্লিকেশনটি একটি ওয়েব ইন্টারফেস সরবরাহ করে যেখানে দুটো চ্যাট ইমপ্লিমেন্টেশন পাশে পাশে থাকে। +অ্যাপ্লিকেশনটি দুইটি পার্শ্বের পাশে পার্শ্ববর্তী দুটি চ্যাট ইমপ্লিমেন্টেশনসহ একটি ওয়েব ইন্টারফেস দেয়। Application Home Screen -*ড্যাশবোর্ডে Simple Chat (স্টেটলেস) এবং Conversational Chat (স্টেটফুল) অপশন উভয় জনপ্রিয়* +*ড্যাশবোর্ড যা Simple Chat (স্টেটলেস) এবং Conversational Chat (স্টেটফুল) অপশন উভয় দেখায়* ### স্টেটলেস চ্যাট (বাম প্যানেল) -প্রথমে এটা চেষ্টা করুন। বলুন "আমার নাম জন" তারপর সাথে সাথে জিজ্ঞেস করুন "আমার নাম কী?" মডেল মনে রাখবে না কারণ প্রতিটি বার্তা স্বাধীন। এটি ভাষা মডেলের মৌলিক ইন্টিগ্রেশনের মূল সমস্যা প্রদর্শন করে — কোনো কথোপকথন প্রসঙ্গ নেই। +প্রথমে এটি চেষ্টা করুন। বলুন "আমার নাম জন" এবং তাৎক্ষণিক "আমার নাম কী?" জিজ্ঞাসা করুন। মডেল মনে রাখবে না কারণ প্রতিটি বার্তা স্বাধীন। এটি মৌলিক ভাষা মডেল সংযুক্তির মূল সমস্যাটি দেখায় — কোনো কথোপকথন প্রসঙ্গ নেই। Stateless Chat Demo -*AI আপনার নাম পূর্বের বার্তা থেকে মনে রাখে না* +*AI আপনার আগের বার্তা থেকে নাম মনে রাখে না* ### স্টেটফুল চ্যাট (ডান প্যানেল) -এখন একই ক্রম এখানে চেষ্টা করুন। বলুন "আমার নাম জন" তারপর "আমার নাম কী?" এবার এটি মনে রাখে। পার্থক্য হল MessageWindowChatMemory — এটি কথোপকথনের ইতিহাস সংরক্ষণ করে এবং প্রতিটি অনুরোধের সাথে অন্তর্ভুক্ত করে। এভাবে প্রোডাকশন কথোপকথন AI কাজ করে। +এখন একই সিকোয়েন্স এখানে চেষ্টা করুন। বলুন "আমার নাম জন" এবং পরে "আমার নাম কী?" এইবার এটি স্মরণ রাখে। পার্থক্য হল MessageWindowChatMemory - এটি কথোপকথন ইতিহাস বজায় রাখে এবং প্রতিটি অনুরোধে এটি অন্তর্ভুক্ত করে। এভাবেই প্রোডাকশন কথোপকথনমূলক AI কাজ করে। Stateful Chat Demo -*AI কথোপকথনের শুরু থেকে আপনার নাম স্মরণ করে* +*AI কথোপকথনের আগে আপনার নাম মনে রাখে* -উভয় প্যানেলে একই GPT-5.2 মডেল ব্যবহার হয়। একমাত্র পার্থক্য মেমোরি। এটি স্পষ্ট করে দেয় মেমোরি আপনার অ্যাপ্লিকেশনকে কী দেয় এবং বাস্তব ব্যবহারে কেন এটি অপরিহার্য। +উভয় প্যানেল একই GPT-5.2 মডেল ব্যবহার করে। একমাত্র পার্থক্য হলো মেমোরি। এটি স্পষ্ট করে তোলে মেমোরি কীভাবে আপনার অ্যাপ্লিকেশনকে উপকৃত করে এবং কেন বাস্তব ব্যবহারের জন্য এটি অপরিহার্য। -## পরবর্তী ধাপ +## পরবর্তী ধাপসমূহ -**পরবর্তী মডিউল:** [০২-প্রম্পট ইঞ্জিনিয়ারিং - GPT-5.2 নিয়ে প্রম্পট ইঞ্জিনিয়ারিং](../02-prompt-engineering/README.md) +**পরবর্তী মডিউল:** [০২-প্রম্পট ইঞ্জিনিয়ারিং - GPT-5.2 দিয়ে প্রম্পট ইঞ্জিনিয়ারিং](../02-prompt-engineering/README.md) --- -**নেভিগেশন:** [← পূর্বের: মডিউল ০০ - কুইক স্টার্ট](../00-quick-start/README.md) | [মেইনে ফিরে যান](../README.md) | [পরবর্তী: মডিউল ০২ - প্রম্পট ইঞ্জিনিয়ারিং →](../02-prompt-engineering/README.md) +**নেভিগেশন:** [← মূল পৃষ্ঠায় ফিরে যান](../README.md) | [পরবর্তী: মডিউল ০২ - প্রম্পট ইঞ্জিনিয়ারিং →](../02-prompt-engineering/README.md) --- -**তৈরি ঘোষণা**: -এই নথিটি [Co-op Translator](https://github.com/Azure/co-op-translator) নামক AI অনুবাদ পরিষেবা ব্যবহার করে অনূদিত হয়েছে। আমরা যথাসাধ্য সঠিকতার চেষ্টা করি, তবে অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদগুলিতে ভুল বা অপরিষ্কৃততা থাকতে পারে। মূল ভাষায় থাকা নথিটিই কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুনিশ্চিত করা উচিৎ। এই অনুবাদের ব্যবহারে যে কোনো ভুল বোঝাবুঝি বা ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই। +**অস্বীকৃতি**: +এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা শুদ্ধতার জন্য চেষ্টা করি, অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার স্বভাষায় কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে প্রয়োজনীয় ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই। \ No newline at end of file diff --git a/translations/bn/02-prompt-engineering/README.md b/translations/bn/02-prompt-engineering/README.md index a9ad6b1cf..00e55cb29 100644 --- a/translations/bn/02-prompt-engineering/README.md +++ b/translations/bn/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ # মডিউল ০২: GPT-5.2 সহ প্রম্পট ইঞ্জিনিয়ারিং -## বিষয়বস্তু সূচি - -- [ভিডিও ওয়াকথ্রু](../../../02-prompt-engineering) -- [আপনি যা শিখবেন](../../../02-prompt-engineering) -- [পূর্বশর্ত](../../../02-prompt-engineering) -- [প্রম্পট ইঞ্জিনিয়ারিং বোঝা](../../../02-prompt-engineering) -- [প্রম্পট ইঞ্জিনিয়ারিং মৌলিক বিষয়াবলী](../../../02-prompt-engineering) - - [জিরো-শট প্রম্পটিং](../../../02-prompt-engineering) - - [ফিউ-শট প্রম্পটিং](../../../02-prompt-engineering) - - [চেইন অফ থট](../../../02-prompt-engineering) - - [রোল-ভিত্তিক প্রম্পটিং](../../../02-prompt-engineering) - - [প্রম্পট টেমপ্লেটস](../../../02-prompt-engineering) -- [উন্নত প্যাটার্নস](../../../02-prompt-engineering) -- [অ্যাপ্লিকেশন চালান](../../../02-prompt-engineering) -- [অ্যাপ্লিকেশন স্ক্রীনশটস](../../../02-prompt-engineering) -- [প্যাটার্নস অন্বেষণ](../../../02-prompt-engineering) - - [লো বনাম হাই ইগারনেস](../../../02-prompt-engineering) - - [টাস্ক এক্সিকিউশন (টুল প্রিম্বলস)](../../../02-prompt-engineering) - - [সেলফ-রিফ্লেক্টিং কোড](../../../02-prompt-engineering) - - [স্ট্রাকচার্ড অ্যানালাইসিস](../../../02-prompt-engineering) - - [মাল্টি-টার্ন চ্যাট](../../../02-prompt-engineering) - - [পর্বক্রমে যুক্তি](../../../02-prompt-engineering) - - [নিয়ন্ত্রিত আউটপুট](../../../02-prompt-engineering) -- [আপনি আসলেই যা শিখছেন](../../../02-prompt-engineering) -- [পরবর্তী ধাপ](../../../02-prompt-engineering) +## বিষয়বস্তু তালিকা + +- [ভিডিও ওয়াকথ্রু](#ভিডিও-ওয়াকথ্রু) +- [আপনি যা শিখবেন](#আপনি-যা-শিখবেন) +- [পূর্বশর্তাবলী](#পূর্বশর্তাবলী) +- [প্রম্পট ইঞ্জিনিয়ারিং বুঝুন](#প্রম্পট-ইঞ্জিনিয়ারিং-বুঝুন) +- [প্রম্পট ইঞ্জিনিয়ারিংয়ের মৌলিক বিষয়াবলী](#প্রম্পট-ইঞ্জিনিয়ারিংয়ের-মৌলিক-বিষয়াবলী) + - [জিরো-শট প্রম্পটিং](#জিরো-শট-প্রম্পটিং) + - [ফিউ-শট প্রম্পটিং](#ফিউ-শট-প্রম্পটিং) + - [চেইন অফ থট্](#চেইন-অফ-থট) + - [রোল-ভিত্তিক প্রম্পটিং](#রোল-ভিত্তিক-প্রম্পটিং) + - [প্রম্পট টেমপ্লেটস](#প্রম্পট-টেমপ্লেটস) +- [অগ্রগামী প্যাটার্নস](#অগ্রগামী-প্যাটার্নস) +- [অ্যাপ্লিকেশন চালান](#অ্যাপ্লিকেশন-চালান) +- [অ্যাপ্লিকেশনের স্ক্রীনশট](#অ্যাপ্লিকেশন-স্ক্রিনশট) +- [প্যাটার্নস অন্বেষণ](#প্যাটার্নগুলি-পরীক্ষা-করা) + - [কম বনাম বেশি উৎসাহ](#low-বনাম-high-eagerness) + - [টাস্ক এক্সিকিউশন (টুল প্রিম্বলস)](#টাস্ক-এক্সেকিউশন-টুল-প্রিমেবলস) + - [সেলফ-রিফ্লেক্টিং কোড](#সেলফ-রিফ্লেক্টিং-কোড) + - [স্ট্রাকচার্ড অ্যানালাইসিস](#স্ট্রাকচার্ড-অ্যানালাইসিস) + - [মাল্টি-টার্ন চ্যাট](#মাল্টি-টার্ন-চ্যাট) + - [ধাপে ধাপে যুক্তি](#ধাপে-ধাপে-যুক্তি) + - [সীমাবদ্ধ আউটপুট](#সংকীর্ণ-আউটপুট) +- [আপনি আসলে কী শিখছেন](#আপনি-আসলেই-কি-শিখছেন) +- [পরবর্তী ধাপ](#পরবর্তী-ধাপ) ## ভিডিও ওয়াকথ্রু -এই লাইভ সেশনটি দেখুন যা ব্যাখ্যা করে কীভাবে এই মডিউল দিয়ে শুরু করবেন: +এই লাইভ সেশনটি দেখুন যা এই মডিউল শুরু করার পদ্ধতি ব্যাখ্যা করে: Prompt Engineering with LangChain4j - Live Session ## আপনি যা শিখবেন -নিম্নলিখিত ডায়াগ্রামটি এই মডিউলে আপনি যে মূল বিষয় ও দক্ষতা অর্জন করবেন তার একটি ওভারভিউ প্রদান করে — প্রম্পট পরিমার্জন কৌশল থেকে শুরু করে আপনি যে পর্বক্রমভিত্তিক কাজের ধারা অনুসরণ করবেন তা পর্যন্ত। +নিম্নলিখিত চিত্রটি এই মডিউলে আপনি যা শিখবেন তার মূল বিষয় এবং দক্ষতার একটি সংক্ষিপ্ত বিবরণ প্রদান করে — প্রম্পট রিফাইনমেন্ট কৌশলগুলি থেকে শুরু করে আপনি অনুসরণ করবেন এমন পর্যায়ক্রমিক ওয়ার্কফ্লো পর্যন্ত। What You'll Learn -পূর্ববর্তী মডিউলগুলিতে, আপনি GitHub মডেলগুলির সাথে LangChain4j বেসিক ইন্টারঅ্যাকশন অন্বেষণ করেছেন এবং দেখেছেন কিভাবে মেমোরি Azure OpenAI-র সাথে কথোপকথনের AI সক্ষম করে। এখন আমরা ফোকাস করব প্রশ্ন করার পদ্ধতি — অর্থাৎ প্রম্পট নিজেই — Azure OpenAI-এর GPT-5.2 ব্যবহার করে। আপনার প্রম্পট গঠন করার ধরণ আপনার যে প্রতিক্রিয়া পাবেন তার গুণমানকে নাটকীয়ভাবে প্রভাবিত করে। আমরা মৌলিক প্রম্পটিং কৌশলগুলি পর্যালোচনা দিয়ে শুরু করব, তারপর আটটি উন্নত প্যাটার্নে যাব যা GPT-5.2-এর ক্ষমতাগুলি পুরোপুরি কাজে লাগায়। +পূর্ববর্তী মডিউলে, আপনি দেখেছেন কিভাবে মেমোরি Azure OpenAI সহ কথোপকথন ইউআই সক্ষম করে। এখন আমরা ফোকাস করব কিভাবে আপনি প্রশ্ন করবেন — অর্থাৎ প্রম্পট নিজেই — Azure OpenAI এর GPT-5.2 ব্যবহার করে। আপনি যেভাবে প্রম্পটগুলো গঠন করবেন তা প্রাপ্ত উত্তরগুলির গুণগত মানে ব্যাপক প্রভাব ফেলে। আমরা শুরু করব মৌলিক প্রম্পটিং কৌশলগুলোর পর্যালোচনা দিয়ে, তারপর এগিয়ে যাব আটটি উন্নত প্যাটার্নের দিকে যা GPT-5.2 এর সক্ষমতাগুলোর পূর্ণ ব্যবহার করে। -আমরা GPT-5.2 ব্যবহার করব কারণ এটি যুক্তি নিয়ন্ত্রণ পরিচয় করায় - আপনি মডেলকে বলতে পারেন কতটা চিন্তা করতে হবে উত্তর দেওয়ার আগে। এটি বিভিন্ন প্রম্পটিং কৌশল আরও স্পষ্ট করে এবং আপনাকে বুঝতে সাহায্য করে কখন কোন পদ্ধতি ব্যবহার করবেন। আরও, GitHub মডেলগুলোর তুলনায় GPT-5.2-এর জন্য Azure-এর কম রেট লিমিট সুবিধাও পাব। +আমরা GPT-5.2 ব্যবহার করব কারণ এটি যুক্তি নিয়ন্ত্রণ পরিচয় করায় — আপনি মডেলকে বলতে পারবেন উত্তর দেবার আগে কতটুকু চিন্তা করতে হবে। এটি বিভিন্ন প্রম্পটিং স্ট্র্যাটেজি আরও স্পষ্ট করে তোলে এবং আপনাকে বুঝতে সাহায্য করে কখন কোন পদ্ধতি ব্যবহার করবেন। -## পূর্বশর্ত +## পূর্বশর্তাবলী -- মডিউল ০১ সম্পন্ন (Azure OpenAI রিসোর্স মোতায়েন) -- রুট ডিরেক্টরিতে `.env` ফাইল Azure শংসাপত্র সহ (মডিউল ০১-এ `azd up` দ্বারা তৈরি) +- মডিউল ০১ সম্পন্ন হয়েছে (Azure OpenAI রিসোর্স মোতায়েন করা হয়েছে) +- রুট ডিরেক্টরিতে `.env` ফাইল আছে Azure ক্রেডেনশিয়ালসহ (মডিউল ০১ এ `azd up` দ্বারা তৈরি) -> **ট্রিক:** আপনি যদি মডিউল ০১ শেষ না করে থাকেন, প্রথমে সেখানে দেয়া ডিপ্লয়মেন্ট নির্দেশাবলী অনুসরণ করুন। +> **দ্রষ্টব্য:** যদি আপনি মডিউল ০১ সম্পন্ন না করে থাকেন, তাহলে আগে সেখানে ডিপ্লয়মেন্টের নির্দেশাবলী অনুসরণ করুন। -## প্রম্পট ইঞ্জিনিয়ারিং বোঝা +## প্রম্পট ইঞ্জিনিয়ারিং বুঝুন -মূলত, প্রম্পট ইঞ্জিনিয়ারিং হল অস্পষ্ট নির্দেশনা এবং সুনির্দিষ্ট নির্দেশনার মধ্যে পার্থক্য, নিচের তুলনাটি তা দেখায়। +মূলত, প্রম্পট ইঞ্জিনিয়ারিং হল অস্পষ্ট নির্দেশনা এবং নির্ভুল নির্দেশনার মধ্যে পার্থক্য, নিচের তুলনাটি দেখিয়েছে তা। What is Prompt Engineering? -প্রম্পট ইঞ্জিনিয়ারিং মানে এমন ইনপুট টেক্সট ডিজাইন করা যা নিয়মিতভাবে আপনাকে আপনার প্রয়োজনীয় ফলাফল দেয়। এটি শুধুমাত্র প্রশ্ন করার ব্যাপার নয়—এটি এমনভাবে অনুরোধ সাজানোর ব্যাপার যাতে মডেল স্পষ্টভাবে বুঝতে পারে আপনি কী চান এবং কিভাবে তা সরবরাহ করতে হবে। +প্রম্পট ইঞ্জিনিয়ারিং হচ্ছে এমন ইনপুট টেক্সট ডিজাইন করা যা ধারাবাহিকভাবে আপনাকে প্রয়োজনীয় ফলাফল দেয়। এটি শুধু প্রশ্ন করার কথা নয় — এটি এমনভাবে অনুরোধগুলো রচনা করা যাতে মডেল স্পষ্টভাবে বুঝতে পারে আপনি ঠিক কী চান এবং কীভাবে তা সরবরাহ করা উচিত। -এটি ভাবুন আপনার সহকর্মীকে নির্দেশ দেওয়ার মত। "বাগ ঠিক করো" অস্পষ্ট। "UserService.java ফাইলে ৪৫ নম্বর লাইনে null পয়েন্টার এক্সসেপশন ঠিক করো null চেক যোগ করে" সুনির্দিষ্ট। ভাষার মডেলও একই রকম কাজ করে—বিশেষত্ব এবং গঠন গুরুত্বপূর্ণ। +একজন সহকর্মীকে নির্দেশ দেওয়ার মত চিন্তা করুন। "বাগ ফিক্স করুন" অস্পষ্ট। "UserService.java লাইনের ৪৫-এ নাল পয়েন্টার একসেপশন ফিক্স করতে নাল চেক যোগ করুন" স্পষ্ট। ভাষার মডেলগুলো একই রকম কাজ করে — নির্দিষ্টতা এবং গঠন গুরুত্বপূর্ণ। -নিচের ডায়াগ্রামটি দেখায় কীভাবে LangChain4j এই ছবি টেপে প্রম্পট প্যাটার্নগুলিকে মডেলের সাথে সংযুক্ত করে SystemMessage এবং UserMessage ব্লকগুলোর মাধ্যমে। +নিচের চিত্রটি দেখায় কিভাবে LangChain4j এই চিত্রে ফিট করে — SystemMessage এবং UserMessage নির্মাণ ব্লকে আপনার প্রম্পট প্যাটার্নগুলো মডেলের সাথে সংযুক্ত করে। How LangChain4j Fits -LangChain4j অবকাঠামো সরবরাহ করে — মডেল সংযোগ, মেমোরি, ও মেসেজ টাইপ — আর প্রম্পট প্যাটার্ন হল সাবধানে গঠিত পাঠ্য যা আপনি ওই অবকাঠামোর মধ্যে পাঠান। মূল ব্লক হল `SystemMessage` (যা AI এর আচরণ ও ভূমিকা নির্ধারণ করে) এবং `UserMessage` (যা আপনার প্রকৃত অনুরোধ বহন করে)। +LangChain4j প্রদান করে অবকাঠামো — মডেল সংযোগ, মেমোরি, এবং মেসেজ প্রকার — যখন প্রম্পট প্যাটার্নগুলো শুধু সাবধানে গঠিত টেক্সট যা আপনি ঐ অবকাঠামোর মাধ্যমে পাঠান। মূল নির্মাণ ব্লক হল `SystemMessage` (যা AI এর আচরণ এবং ভূমিকা সেট করে) এবং `UserMessage` (যা আপনার প্রকৃত অনুরোধ বহন করে)। -## প্রম্পট ইঞ্জিনিয়ারিং মৌলিক বিষয়াবলী +## প্রম্পট ইঞ্জিনিয়ারিংয়ের মৌলিক বিষয়াবলী -নিম্নলিখিত পাঁচটি মূল কৌশল কার্যকর প্রম্পট ইঞ্জিনিয়ারিংয়ের ভিত্তি গঠন করে। প্রত্যেকটি ভাষার মডেলের সাথে আপনার যোগাযোগের একটি ভিন্ন দিক নজর দেয়। +নিম্নলিখিত পাঁচটি মূল কৌশল কার্যকর প্রম্পট ইঞ্জিনিয়ারিংয়ের ভিত্তি গঠন করে। প্রতিটি ভাষার মডেলগুলোর সাথে আপনার যোগাযোগের একটি ভিন্ন দিক সম্বোধন করে। Five Prompt Engineering Patterns Overview -এই মডিউলের উন্নত প্যাটার্নগুলিতে প্রবেশ করার আগে, চলুন পাঁচটি মৌলিক প্রম্পটিং কৌশল পর্যালোচনা করি। এগুলো হল সেই নির্মাণ ব্লক যা প্রতিটি প্রম্পট ইঞ্জিনিয়ারকে জানা উচিত। আপনি যদি ইতিমধ্যে [Quick Start মডিউল](../00-quick-start/README.md#2-prompt-patterns) অনুসরণ করে থাকেন, তাহলে এগুলো দেখতে পেয়েছেন — এগুলোর পেছনের ধারনামূলক কাঠামো এখানে আছে। +এই মডিউলে উন্নত প্যাটার্নগুলিতে প্রবেশ করার আগে, আসুন পাঁচটি মৌলিক প্রম্পটিং কৌশল পুনরালোচনা করি। এগুলো হল সেই নির্মাণ ব্লক যা প্রতিটি প্রম্পট ইঞ্জিনিয়ারকে জানা উচিত। ### জিরো-শট প্রম্পটিং -সবচেয়ে সোজা পদ্ধতি: মডেলকে কোনো উদাহরণ ছাড়াই সরাসরি নির্দেশ দিন। মডেল সম্পূর্ণরূপে তার প্রশিক্ষণের ওপর নির্ভর করে কাজ বুঝে এবং সম্পাদন করে। এটি সোজা অনুরোধের ক্ষেত্রে ভালো কাজ করে যেখানে প্রত্যাশিত আচরণ স্পষ্ট। +সবচেয়ে সহজ পদ্ধতি: মডেলকে সরাসরি কোনো উদাহরণ ছাড়াই নির্দেশ দেওয়া। মডেল সম্পূর্ণরূপে তার প্রশিক্ষণের ওপর নির্ভর করে কাজটি বোঝে এবং সম্পাদন করে। এটি সহজ রকমের অনুরোধের জন্য ভালো কাজ করে যেখানে প্রত্যাশিত আচরণ স্পষ্ট। Zero-Shot Prompting -*উদাহরণ ছাড়া সরাসরি নির্দেশ — মডেল শুধু নির্দেশ থেকে টাস্ক বুজে নেয়* +*উদাহরণ ছাড়া সরাসরি নির্দেশনা — মডেল শুধুমাত্র নির্দেশ থেকে কাজটি অনুমান করে* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // প্রতিক্রিয়া: "ইতিবাচক" ``` -**কখন ব্যবহার করবেন:** সরল শ্রেণীবিভাগ, সরাসরি প্রশ্ন, অনুবাদ, অথবা এমন কোনো টাস্ক যেখানে অতিরিক্ত নির্দেশনার প্রয়োজন নেই। +**কখন ব্যবহার করবেন:** সাধারণ শ্রেণিবিন্যাস, সরাসরি প্রশ্ন, অনুবাদ বা এমন কোনো কাজ যা মডেল অতিরিক্ত নির্দেশনা ছাড়া পরিচালনা করতে পারে। ### ফিউ-শট প্রম্পটিং -উদাহরণ দিন যা মডেলকে আপনি যে প্যাটার্ন অনুসরণ করতে চান তা প্রদর্শন করে। মডেল আপনার উদাহরণ থেকে প্রত্যাশিত ইনপুট-আউটপুট ফর্ম্যাট শিখে নতুন ইনপুটের ওপর প্রয়োগ করে। এটি উন্নত সামঞ্জস্যতা দেয় যখন কাঙ্ক্ষিত ফর্ম্যাট বা আচরণ অপ্রচলিত। +আপনার কাঙ্ক্ষিত প্যাটার্নটি মডেলকে শেখানোর জন্য উদাহরণ প্রদান করুন। মডেল আপনার উদাহরণ থেকে প্রত্যাশিত ইনপুট-আউটপুট ফরম্যাট শিখে এবং নতুন ইনপুটে তা প্রয়োগ করে। এটি এমন কাজের জন্য ধারাবাহিকতা উল্লেখযোগ্যভাবে বাড়ায় যেখানে কাঙ্ক্ষিত ফরম্যাট বা আচরণ স্পষ্ট নয়। Few-Shot Prompting -*উদাহরণ থেকে শেখা — মডেল প্যাটার্ন চিনে নতুন ইনপুটে প্রয়োগ করে* +*উদাহরণের মাধ্যমে শেখা — মডেল প্যাটার্ন চিনে নতুন ইনপুটে প্রয়োগ করে* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**কখন ব্যবহার করবেন:** কাস্টম শ্রেণীবিভাগ, সঙ্গতিপূর্ণ ফরম্যাটিং, ডোমেইন-নির্দিষ্ট কাজ, অথবা যখন জিরো-শট ফলাফল অনিয়মিত হয়। +**কখন ব্যবহার করবেন:** কাস্টম শ্রেণিবিন্যাস, ধারাবাহিক ফরম্যাটিং, ডোমেইন-নির্দিষ্ট কাজ অথবা যখন জিরো-শট ফলাফল অসম্ভাব্য বা অসঙ্গত হয়। ### চেইন অফ থট -মডেলকে তার যুক্তি পর্বক্রমে দেখাতে বলুন। সরাসরি উত্তর দেওয়ার পরিবর্তে মডেল সমস্যা ভেঙে প্রতিটি অংশ স্পষ্টভাবে ব্যাখ্যা করে। এটি গণিত, লজিক, ও বহু-পর্ব যুক্তি কার্যক্রমে নির্ভুলতা বাড়ায়। +মডেলকে ধাপে ধাপে তার যুক্তি প্রদর্শন করতে বলেছেন। সরাসরি উত্তর দেয়ার পরিবর্তে, মডেল সমস্যাটি ভেঙে প্রতিটি অংশ স্পষ্টভাবে আলোচনা করে কাজ করে। এটি গণিত, যুক্তি ও বহু-পর্যায় যুক্তি সম্পাদনে নির্ভুলতা বাড়ায়। Chain of Thought Prompting -*পর্বক্রমে যুক্তি — জটিল সমস্যাকে স্পষ্ট যৌক্তিক ধাপে ভাঙা* +*ধাপে ধাপে যুক্তি — জটিল সমস্যাগুলো স্পষ্ট যুক্তিসমূহে ভাঙা* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// মডেলটি প্রদর্শন করে: ১৫ - ৮ = ৭, তারপর ৭ + ১২ = ১৯ আপেল +// মডেলটি দেখায়: ১৫ - ৮ = ৭, তারপর ৭ + ১২ = ১৯ আপেল ``` -**কখন ব্যবহার করবেন:** গাণিতিক সমস্যাগুলি, যুক্তি পাজল, ডিবাগিং, অথবা এমন টাস্ক যেখানে যুক্তি প্রক্রিয়া প্রদর্শন সঠিকতা ও বিশ্বাসযোগ্যতা বাড়ায়। +**কখন ব্যবহার করবেন:** গণিত সমস্যা, যুক্তি ধাঁধা, ডিবাগিং বা এমন কোনো কাজ যেখানে যুক্তি প্রক্রিয়া দেখানো নির্ভুলতা ও বিশ্বাসযোগ্যতা বাড়ায়। ### রোল-ভিত্তিক প্রম্পটিং -প্রশ্ন করার আগে AI-এর জন্য একটি ব্যক্তিত্ব বা ভূমিকা নির্ধারণ করুন। এটি প্রসঙ্গ দেয় যা প্রতিক্রিয়ার সুর, গভীরতা, ও ফোকাস গঠন করে। একজন "সফটওয়্যার আর্কিটেক্ট" এর পরামর্শ "জুনিয়র ডেভেলপার" বা "সিকিউরিটি অডিটর" থেকে আলাদা। +প্রশ্ন করার আগে AI এর জন্য একটি persona বা ভূমিকা সেট করুন। এটি প্রসঙ্গ প্রদান করে যা উত্তরের টোন, গভীরতা এবং ফোকাস নির্ধারণ করে। যেমন "সফটওয়্যার আর্কিটেক্ট" একটি আলাদা পরামর্শ দেয় "জুনিয়র ডেভেলপার" বা "সিকিউরিটি অডিটর" থেকে। Role-Based Prompting -*প্রসঙ্গ ও ব্যক্তিত্ব নির্ধারণ — একই প্রশ্ন ভিন্ন ভূমিকার ওপর ভিত্তি করে ভিন্ন উত্তর পায়* +*প্রসঙ্গ এবং persona নির্ধারণ — একই প্রশ্ন ভূমিকা অনুযায়ী ভিন্ন উত্তর পায়* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**কখন ব্যবহার করবেন:** কোড রিভিউ, টিউটরিং, ডোমেইন-নির্দিষ্ট বিশ্লেষণ, অথবা নির্দিষ্ট দক্ষতা স্তর বা দৃষ্টিভঙ্গির উপযোগী উত্তর চাইলে। +**কখন ব্যবহার করবেন:** কোড রিভিউ, টিউটোরিয়াল, ডোমেইন-নির্দিষ্ট বিশ্লেষণ অথবা যখন নির্দিষ্ট দক্ষতা বা উৎস থেকে প্রাসঙ্গিক উত্তর প্রয়োজন। ### প্রম্পট টেমপ্লেটস -ভারি প্লেসহোল্ডার সহ পুনঃব্যবহারযোগ্য প্রম্পট তৈরি করুন। প্রতি বার নতুন প্রম্পট লেখার পরিবর্তে একবার টেমপ্লেট ডিফাইন করুন এবং বিভিন্ন মান পূরণ করুন। LangChain4j-এর `PromptTemplate` ক্লাস `{{variable}}` সিনট্যাক্স দিয়ে এটিকে সহজ করে তোলে। +ভেরিয়েবল প্লেসহোল্ডার সহ পুনঃব্যবহারযোগ্য প্রম্পট তৈরি করুন। প্রতি বার নতুন প্রম্পট লেখার পরিবর্তে, একবার একটি টেমপ্লেট সংজ্ঞায়িত করুন এবং ভিন্ন মান দিয়ে পূরণ করুন। LangChain4j এর `PromptTemplate` ক্লাস এটি সহজ করে `{{variable}}` সিনট্যাক্স সহ। Prompt Templates -*পুনঃব্যবহারযোগ্য প্রম্পটস সহ প্লেসহোল্ডার — এক টেমপ্লেট, অনেক ব্যবহার* +*প্লেসহোল্ডারসহ পুনঃব্যবহারযোগ্য প্রম্পট — একটি টেমপ্লেট, বহুবিধ ব্যবহার* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**কখন ব্যবহার করবেন:** বিভিন্ন ইনপুটসহ পুনরাবৃত্ত প্রশ্ন, ব্যাচ প্রোসেসিং, পুনঃব্যবহারযোগ্য AI ওয়ার্কফ্লো তৈরি, অথবা যেখানে প্রম্পট কাঠামো একই থাকে কিন্তু ডেটা পরিবর্তিত হয়। +**কখন ব্যবহার করবেন:** বিভিন্ন ইনপুটের জন্য পুনরাবৃত্ত প্রশ্ন, ব্যাচ প্রসেসিং, পুনঃব্যবহারযোগ্য AI ওয়ার্কফ্লো তৈরি, বা যেকোনো পরিস্থিতি যেখানে প্রম্পটের কাঠামো একই থাকে কিন্তু ডেটা পরিবর্তিত হয়। --- -এই পাঁচটি মৌলিক বিষয় আপনার জন্য একটি শক্তিশালী সরঞ্জাম প্যাকেজ দেয় অধিকাংশ প্রম্পটিং কাজের জন্য। বাকিটা এই মডিউল জুড়ে আপনাকে আটটি উন্নত প্যাটার্ন শেখাবে যা GPT-5.2-এর যুক্তি নিয়ন্ত্রণ, আত্ম-মূল্যায়ন, এবং কাঠামোবদ্ধ আউটপুট সক্ষমতা ব্যবহার করে। +এই পাঁচটি মৌলিক বিষয় আপনাকে অধিকাংশ প্রম্পটিং কাজের জন্য একটি শক্তিশালী সরঞ্জাম প্রদান করে। এই মডিউলের বাকিটা এগিয়ে নিয়ে যাবে **আটটি উন্নত প্যাটার্নের মাধ্যমে** যা GPT-5.2 এর যুক্তি নিয়ন্ত্রণ, স্ব-মূল্যায়ন এবং স্ট্রাকচার্ড আউটপুট ক্ষমতাগুলো কাজে লাগায়। -## উন্নত প্যাটার্নস +## অগ্রগামী প্যাটার্নস -মৌলিক বিষয়গুলি আচ্ছাদিত হলে, চলুন শুরু করি আটটি উন্নত প্যাটার্ন দিয়ে যা এই মডিউলকে অনন্য করে তোলে। সব সমস্যার জন্য একই পদ্ধতি প্রয়োজন হয় না। কিছু প্রশ্ন দ্রুত উত্তর চাই, অন্যগুলি গভীর চিন্তা। কিছু দৃশ্যমান যুক্তি চাই, কিছু শুধু ফলাফল। নিচের প্রতিটি প্যাটার্ন ভিন্ন পরিস্থিতির জন্য অপ্টিমাইজড — আর GPT-5.2-এর যুক্তি নিয়ন্ত্রণ পার্থক্যগুলো আরও স্পষ্ট করে তোলে। +মৌলিক বিষয়গুলো আচ্ছাদিত করার পর, চলুন এগিয়ে যাই আটটি উন্নত প্যাটার্নের দিকে যা এই মডিউলটিকে অনন্য করে তোলে। সব সমস্যার জন্য একই পদ্ধতি প্রয়োজন হয় না। কিছু প্রশ্ন দ্রুত উত্তর প্রয়োজন, কিছু গভীর চিন্তা প্রয়োজন। কিছুতে দৃশ্যমান যুক্তি দরকার, আবার কিছুতে শুধু ফলাফলই যথেষ্ট। নিচের প্রতিটি প্যাটার্ন ভিন্ন প্রেক্ষাপটের জন্য অপ্টিমাইজড — এবং GPT-5.2 এর যুক্তি নিয়ন্ত্রণ পার্থক্যগুলো আরো স্পষ্ট করে। Eight Prompting Patterns -*আটটি প্রম্পট ইঞ্জিনিয়ারিং প্যাটার্ন এবং তাদের ব্যবহারের ক্ষেত্রে ওভারভিউ* +*আটটি প্রম্পট ইঞ্জিনিয়ারিং প্যাটার্ন এবং তাদের ব্যবহার ক্ষেত্রের সারাংশ* -GPT-5.2 এই প্যাটার্নগুলিতে আরেকটি মাত্রা যোগ করে: *যুক্তি নিয়ন্ত্রণ*। নিচের স্লাইডার দেখায় কিভাবে আপনি মডেলের চিন্তার মাত্রা সামঞ্জস্য করতে পারেন — দ্রুত, সরাসরি উত্তর থেকে শুরু করে গভীর ও বিস্তৃত বিশ্লেষণ পর্যন্ত। +GPT-5.2 যোগ করেছে আরেকটি মাত্রা: *যুক্তি নিয়ন্ত্রণ*। নিচের স্লাইডারটি দেখায় কিভাবে আপনি মডেলের চিন্তা চেষ্টাকে সামঞ্জস্য করতে পারেন — দ্রুত, সরাসরি উত্তর থেকে গভীর, বিস্তৃত বিশ্লেষণ পর্যন্ত। Reasoning Control with GPT-5.2 -*GPT-5.2-এর যুক্তি নিয়ন্ত্রণ আপনাকে নির্দিষ্ট করতে দেয় মডেল কতটা চিন্তা করবে — দ্রুত সরাসরি উত্তর থেকে গভীর অনুসন্ধান পর্যন্ত* +*GPT-5.2 এর যুক্তি নিয়ন্ত্রণ আপনাকে মডেল কতটা চিন্তা করবে তা নির্ধারণ করতে দেয় — দ্রুত সরাসরি উত্তর থেকে গভীর অনুসন্ধান পর্যন্ত* -**লো ইগারনেস (দ্রুত ও ফোকাসড)** - সরল প্রশ্নের জন্য যেখানে আপনি দ্রুত, সরাসরি উত্তর চান। মডেল সর্বোচ্চ ২ ধাপ চিন্তা করে। গণনা, লুকআপ, বা সরল প্রশ্নের জন্য ব্যবহার করুন। +**কম উৎসাহ (দ্রুত ও কেন্দ্রিত)** - সরল প্রশ্নের জন্য যেখানে দ্রুত, সরাসরি উত্তর চান। মডেল সর্বাধিক ২ ধাপ যুক্তি করে। এটি ব্যবহার করুন গণনায়, লুকআপে বা সহজ প্রশ্নের জন্য। ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **GitHub Copilot দিয়ে এক্সপ্লোর করুন:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) খুলে জিজ্ঞাসা করুন: -> - "লো ইগারনেস এবং হাই ইগারনেস প্রম্পটিং প্যাটার্নগুলোর মধ্যে পার্থক্য কী?" -> - "প্রম্পটে XML ট্যাগগুলো কীভাবে AI-এর প্রতিক্রিয়া গঠন করতে সাহায্য করে?" -> - "সেলফ-রিফ্লেকশন প্যাটার্ন কখন আর সরাসরি নির্দেশ কখন ব্যবহার করব?" +> 💡 **GitHub Copilot দিয়ে পরীক্ষা করুন:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) খুলুন এবং জিজ্ঞাসা করুন: +> - "কম উৎসাহ এবং বেশি উৎসাহ প্রম্পট প্যাটার্নের মধ্যে পার্থক্য কী?" +> - "প্রম্পটে XML ট্যাগগুলি কিভাবে AI এর প্রতিক্রিয়া গঠন করতে সাহায্য করে?" +> - "সেলফ-রিফ্লেকশন প্যাটার্ন কখন ব্যবহার করব বনাম সরাসরি নির্দেশ?" -**হাই ইগারনেস (গভীর ও বিস্তৃত)** - জটিল সমস্যার জন্য যেখানে আপনি ব্যাপক বিশ্লেষণ চান। মডেল বিস্তারিতভাবে তদন্ত করে যুক্তি প্রদর্শন করে। সিস্টেম ডিজাইন, আর্কিটেকচার সিদ্ধান্ত, বা জটিল গবেষণার জন্য ব্যবহার করুন। +**বেশি উৎসাহ (গভীর ও বিস্তারিত)** - জটিল সমস্যার জন্য যেখানে বিস্তৃত বিশ্লেষণ প্রয়োজন। মডেল গভীরভাবে অনুসন্ধান করে এবং বিস্তারিত যুক্তি প্রদর্শন করে। এটি ব্যবহার করুন সিস্টেম ডিজাইন, আর্কিটেকচার সিদ্ধান্ত, বা জটিল গবেষণার জন্য। ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**টাস্ক এক্সিকিউশন (পর্বক্রমে অগ্রগতি)** - বহু পর্যায়ের ওয়ার্কফ্লো জন্য। মডেল প্রথমে প্ল্যান দেয়, কাজের সময় প্রতিটি ধাপ বর্ণনা করে, তারপর সারাংশ দেয়। মাইগ্রেশন, বাস্তবায়ন বা যেকোনো বহু-পর্বের কাজের জন্য ব্যবহার করুন। +**টাস্ক এক্সিকিউশন (ধাপে ধাপে অগ্রগতি)** - বহু-ধাপীয় ওয়ার্কফ্লোর জন্য। মডেল একটি প্রাথমিক পরিকল্পনা দেয়, কাজ করার সময় প্রতিটি ধাপ বর্ণনা করে, তারপর একটি সারসংক্ষেপ দেয়। এটি ব্যবহার করুন মাইগ্রেশন, বাস্তবায়ন বা যেকোনো বহু-পর্যায় প্রক্রিয়ার জন্য। ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -চেইন-অফ-থট প্রম্পটিং মডেলকে স্পষ্টভাবে তার যুক্তি প্রক্রিয়া দেখাতে বলে, যা জটিল কাজের নির্ভুলতা বাড়ায়। পর্বক্রমে যুক্তি মানুষের পাশাপাশি AI-কে লজিক বুঝতে সাহায্য করে। +চেইন-অফ-থট প্রম্পটিং স্পষ্টভাবে মডেলকে তার যুক্তি প্রক্রিয়া দেখানোর অনুরোধ করে, যা জটিল কাজের জন্য নির্ভুলতা বাড়ায়। ধাপে ধাপে ভাঙ্গা মানব এবং AI উভয়ের জন্য যুক্তি বোঝা সহজ করে। -> **🤖 [GitHub Copilot](https://github.com/features/copilot) চ্যাটের সাথে চেষ্টা করুন:** এই প্যাটার্ন নিয়ে জিজ্ঞাসা করুন: -> - "দীর্ঘকাল চলমান অপারেশনের জন্য টাস্ক এক্সিকিউশন প্যাটার্ন কিভাবে অভিযোজিত হবে?" -> - "প্রোডাকশনে টুল প্রিম্বল গঠন করার সেরা পদ্ধতিগুলো কী?" -> - "UI তে মধ্যবর্তী অগ্রগতি আপডেট ধরার এবং প্রদর্শনের উপায় কী?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) চ্যাট দিয়ে চেষ্টা করুন:** এই প্যাটার্ন সম্পর্কে প্রশ্ন করুন: +> - "দীর্ঘমেয়াদি কার্যক্রমের জন্য টাস্ক এক্সিকিউশন প্যাটার্ন কিভাবে অভিযোজিত করব?" +> - "প্রোডাকশন অ্যাপ্লিকেশনে টুল প্রিম্বলস structuring এর সেরা অনুশীলন কী?" +> - "কি করে UI তে অন্তর্বর্তী অগ্রগতি আপডেট ক্যাপচার এবং প্রদর্শন করব?" -নিচের ডায়াগ্রামটি দেখায় এই Plan → Execute → Summarize ওয়ার্কফ্লো। +নিচের চিত্রটি এই Plan → Execute → Summarize ওয়ার্কফ্লোটি প্রদর্শন করে। Task Execution Pattern -*পর্বক্রমে টাস্কের জন্য Plan → Execute → Summarize ওয়ার্কফ্লো* +*বহু-ধাপীয় কাজের জন্য Plan → Execute → Summarize ওয়ার্কফ্লো* -**সেলফ-রিফ্লেক্টিং কোড** - প্রোডাকশন মানের কোড তৈরি করার জন্য। মডেল উৎপাদন মান অনুসরণ করে কোড জেনারেট করে যা সঠিক ত্রুটি হ্যান্ডলিং সহ। নতুন ফিচার বা সার্ভিস নির্মাণের জন্য ব্যবহার করুন। +**সেলফ-রিফ্লেক্টিং কোড** - প্রোডাকশন-মানের কোড তৈরির জন্য। মডেল প্রোডাকশন মানদণ্ড অনুসারে কোড তৈরি করে যথাযথ ত্রুটি পরিচালনার সাথে। এটি ব্যবহার করুন নতুন ফিচার বা সার্ভিস তৈরি করার সময়। ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -নিচের ডায়াগ্রামটি দেখায় এই পুনরাবৃত্তিমূলক উন্নতি চক্র — জেনারেট, মূল্যায়ন, দুর্বলতা চিহ্নিতকরণ, ও পরিমার্জন যতক্ষণ না কোড প্রোডাকশন মান পূরণ করে। +নিচের চিত্রটি দেখায় এই পুনরাবৃত্তিমূলক উন্নয়ন চক্র — তৈরি, মূল্যায়ন, দুর্বলতা নিরূপণ, এবং পরিমার্জন যতক্ষণ না কোড প্রোডাকশন মান পূরণ করে। Self-Reflection Cycle -*পুনরাবৃত্তিমূলক উন্নতি চক্র - তৈরি করুন, মূল্যায়ন করুন, সমস্যা ধরুন, উন্নত করুন, পুনরাবৃত্তি করুন* +*পুনরাবৃত্তিমূলক উন্নয়ন চক্র - তৈরি, মূল্যায়ন, সমস্যা চিহ্নিতকরণ, উন্নয়ন, পুনরাবৃত্তি* -**স্ট্রাকচার্ড অ্যানালাইসিস** - সচ্ছল মূল্যায়নের জন্য। মডেল কোড পর্যালোচনা করে একটি নির্দিষ্ট কাঠামো অনুসারে (সঠিকতা, অনুশীলন, কর্মক্ষমতা, নিরাপত্তা, রক্ষণাবেক্ষণযোগ্যতা)। কোড রিভিউ বা গুণমান নিরূপণের জন্য ব্যবহার করুন। +**স্ট্রাকচার্ড অ্যানালাইসিস** - ধারাবাহিক মূল্যায়নের জন্য। মডেল একটি নির্দিষ্ট কাঠামো (সঠিকতা, অনুশীলন, কর্মক্ষমতা, নিরাপত্তা, রক্ষণাবেক্ষণযোগ্যতা) অনুসারে কোড পর্যালোচনা করে। এটি ব্যবহার করুন কোড রিভিউ বা গুণমান যাচাইয়ের জন্য। ```java String prompt = """ @@ -355,17 +355,17 @@ String response = chatModel.chat(prompt); ``` > **🤖 [GitHub Copilot](https://github.com/features/copilot) চ্যাট দিয়ে চেষ্টা করুন:** স্ট্রাকচার্ড অ্যানালাইসিস সম্পর্কে জিজ্ঞাসা করুন: -> - "বিভিন্ন ধরনের কোড রিভিউ জন্য আমি কিভাবে বিশ্লেষণ কাঠামো কাস্টমাইজ করব?" -> - "স্ট্রাকচার্ড আউটপুট প্রোগ্রাম্যাটিকভাবে পার্স এবং প্রয়োগের সেরা উপায় কী?" -> - "কিভাবে নিশ্চিত করব বিভিন্ন রিভিউ সেশনে ধারাবাহিক গুরুতর স্তর থাকবে?" +> - "বিভিন্ন ধরনের কোড রিভিউয়ের জন্য অ্যানালাইসিস ফ্রেমওয়ার্ক কিভাবে কাস্টমাইজ করব?" +> - "স্ট্রাকচার্ড আউটপুট প্রোগ্রাম্যাটিক্যালি পার্স ও অ্যাক্ট করা সেরা উপায় কী?" +> - "কিভাবে বিভিন্ন রিভিউ সেশনে ধারাবাহিক সেবার স্তর নিশ্চিত করব?" -নিম্নলিখিত ডায়াগ্রাম দেখায় কিভাবে এই কাঠামো একটি কোড রিভিউকে ধারাবাহিক বিভাগে গুরুতর স্তরসহ সংগঠিত করে। +নিচের চিত্রটি দেখায় কীভাবে এই কাঠামো কোড রিভিউকে ধারাবাহিক বিভাগ ও সেবার স্তরে সংগঠিত করে। Structured Analysis Pattern -*গুরুত্ব স্তরের সাথে ধারাবাহিক কোড রিভিউয়ের ফ্রেমওয়ার্ক* +*সেবার স্তর সহ ধারাবাহিক কোড রিভিউর কাঠামো* -**মাল্টি-টার্ন চ্যাট** - প্রসঙ্গ প্রয়োজন এমন কথোপকথনের জন্য। মডেল পূর্বের বার্তাগুলো মনে রাখে এবং তার ওপর ভিত্তি করে তৈরি করে। ইন্টারেক্টিভ সাহায্য সেশন বা জটিল প্রশ্নোত্তরের জন্য ব্যবহার করুন। +**মাল্টি-টার্ন চ্যাট** - প্রসঙ্গ যে কথোপকথন সম্পর্কিত। মডেল পূর্ববর্তী বার্তাগুলো মনে রাখে এবং সেগুলোর উপর ভিত্তি করে নির্মাণ করে। এটি ব্যবহার করুন ইন্টারঅ্যাকটিভ হেল্প সেশন বা জটিল প্রশ্নোত্তর জন্য। ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -নিচের ডায়াগ্রামটি দেখায় কিভাবে কথোপকথনের প্রসঙ্গ প্রতি টার্নে জমা হয় এবং তা মডেলের টোকেন সীমার সাথে সম্পর্কিত। +নিচের চিত্রটিতে দেখানো হয়েছে কিভাবে কথোপকথনের প্রসঙ্গ একাধিক টার্নের মাধ্যমে জমা হয় এবং মডেলের টোকেন সীমার সাথে সম্পর্কিত হয়। Context Memory -*কথোপকথনের প্রসঙ্গ কিভাবে একাধিক পর্যায়ে জমা হয় যতক্ষণ না টোকেন সীমায় পৌঁছে* -**ধাপে ধাপে যুক্তি** - স্পষ্ট যুক্তি প্রয়োজন এমন সমস্যার জন্য। মডেল প্রতিটি ধাপের জন্য স্পষ্ট যুক্তি প্রদর্শন করে। গণিত সমস্যা, যুক্তি ধাঁধা, অথবা যখন আপনি চিন্তার প্রক্রিয়া বুঝতে চান তখন এটি ব্যবহার করুন। +*কথোপকথন প্রসঙ্গ কিভাবে টার্নগুলোর মাধ্যমে জমা হয় যতক্ষণ না টোকেন সীমা পৌঁছায়* + +**ধাপে ধাপে যুক্তি** - দৃশ্যমান লজিকের প্রয়োজন এমন সমস্যা জন্য। মডেল প্রতিটি ধাপে স্পষ্ট যুক্তি প্রদর্শন করে। ব্যবহার করুন গণিত সমস্যা, যুক্তি ধাঁধা বা যখন চিন্তার প্রক্রিয়া বোঝা প্রয়োজন। ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -নিচের ছবিটি দেখায় কীভাবে মডেল সমস্যা স্পষ্ট, নম্বরকৃত যুক্তির ধাপে ধাপে বিভক্ত করে। +নিচের চিত্রটি দেখায় কিভাবে মডেল সমস্যাগুলো স্পষ্ট, নম্বরযুক্ত যুক্তিসম্পন্ন ধাপে ভেঙে তোলে। Step-by-Step Pattern +*স্পষ্ট যৌক্তিক ধাপে সমস্যার বিশ্লেষণ* -*সমস্যাগুলোকে স্পষ্ট যুক্তির ধাপে বিভক্ত করা হচ্ছে* - -**সীমাবদ্ধ আউটপুট** - নির্দিষ্ট ফরম্যাটের প্রয়োজন এমন প্রতিক্রিয়ার জন্য। মডেল ফরম্যাট এবং দৈর্ঘ্যের নিয়ম কঠোরভাবে অনুসরণ করে। সারাংশ বা নির্দিষ্ট আউটপুট কাঠামো প্রয়োজন হলে ব্যবহার করুন। +**সংকীর্ণ আউটপুট** - নির্দিষ্ট ফরম্যাটের প্রয়োজন অনুযায়ী প্রতিক্রিয়ার জন্য। মডেল কঠোরভাবে ফরম্যাট এবং দৈর্ঘ্যের নিয়ম অনুসরণ করে। সারাংশের জন্য বা যখন আপনাকে নির্দিষ্ট আউটপুট কাঠামো দরকার তখন এটি ব্যবহার করুন। ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -নিম্নের চিত্রটি দেখায় কীভাবে সীমাবদ্ধতা মডেলকে আপনার ফরম্যাট এবং দৈর্ঘ্যের নিয়ম কঠোরভাবে মেনে আউটপুট তৈরি করতে নির্দেশ দেয়। +নিম্নলিখিত চিত্রটি দেখায় কিভাবে সীমাবদ্ধতা মডেলকে আপনার ফরম্যাট এবং দৈর্ঘ্যের শর্তাবলী কঠোরভাবে অনুসরণ করে আউটপুট উৎপাদনে নির্দেশনা দেয়। Constrained Output Pattern -*নির্দিষ্ট ফরম্যাট, দৈর্ঘ্য, এবং কাঠামো প্রয়োগ করা হচ্ছে* +*নির্দিষ্ট ফরম্যাট, দৈর্ঘ্য এবং কাঠামো শর্তাবলী প্রয়োগ করা* ## অ্যাপ্লিকেশন চালান -**ডিপ্লয়মেন্ট যাচাই করুন:** +**ডিপ্লয়মেন্ট নিশ্চিত করুন:** -রুট ডিরেক্টরিতে `.env` ফাইলটি নিশ্চিত করুন যা Azure সার্টিফিকেট (Module 01 চলাকালীন তৈরি) সহ রয়েছে। এটি মডিউল ডিরেক্টরি (`02-prompt-engineering/`) থেকে চালান: +রুট ডিরেক্টরিতে `.env` ফাইলটি থাকতে হবে যা Azure ক্রেডেনশিয়াল ধারণ করে (মডিউল 01 চলাকালীন তৈরি হয়)। এটি মডিউল ডিরেক্টরি থেকে চালান (`02-prompt-engineering/`): **Bash:** ```bash @@ -439,32 +439,32 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT দেখানো উ **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT দেখানো উচিত +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT দেখান উচিত ``` **অ্যাপ্লিকেশন শুরু করুন:** -> **বিঃদ্রঃ:** যদি আপনি ইতোমধ্যে রুট ডিরেক্টরি থেকে `./start-all.sh` ব্যবহার করে সব অ্যাপ্লিকেশন চালু করে থাকেন (যেমন Module 01 এ বর্ণিত), তবে এই মডিউল ইতোমধ্যে পোর্ট 8083 এ চলছে। নিচের শুরু কমান্ডগুলো এড়িয়ে সরাসরি http://localhost:8083 এ যেতে পারেন। +> **নোট:** যদি আপনি ইতিমধ্যে রুট ডিরেক্টরি থেকে `./start-all.sh` ব্যবহার করে সব অ্যাপ্লিকেশন চালু করে থাকেন (মডিউল 01 এর বর্ণনা অনুসারে), তবে এই মডিউল 8083 পোর্টে চলছে। নিচের স্টার্ট কমান্ডগুলি এড়িয়ে সরাসরি http://localhost:8083 তে যেতে পারেন। -**বিকল্প ১: Spring Boot ড্যাশবোর্ড ব্যবহার (VS Code ব্যবহারকারীদের জন্য সুপারিশ)** +**বিকল্প ১: Spring Boot Dashboard ব্যবহার করে (VS Code ব্যবহারকারীদের জন্য সুপারিশকৃত)** -ডেভ কন্টেইনারে Spring Boot ড্যাশবোর্ড এক্সটেনশন অন্তর্ভুক্ত রয়েছে, যা সব Spring Boot অ্যাপ্লিকেশন পরিচালনার জন্য ভিজ্যুয়াল ইন্টারফেস প্রদান করে। এটি VS Code এর বাম পাশের Activity Bar এ পাওয়া যাবে (Spring Boot আইকন খুঁজুন)। +ডেভ কন্টেইনারে Spring Boot Dashboard এক্সটেনশন অন্তর্ভুক্ত, যা সব Spring Boot অ্যাপ্লিকেশন পরিচালনার জন্য ভিজ্যুয়াল ইন্টারফেস প্রদান করে। এটি VS Code এর বাম পাশে অ্যাক্টিভিটি বারে পাওয়া যাবে (Spring Boot আইকন খুঁজুন)। -Spring Boot ড্যাশবোর্ড থেকে আপনি: -- ওয়ার্কস্পেসের সব উপলব্ধ Spring Boot অ্যাপ্লিকেশন দেখতে পাবেন -- এক ক্লিকে অ্যাপ্লিকেশন চালু/বন্ধ করতে পারবেন -- রিয়েল-টাইমে অ্যাপ্লিকেশন লগ দেখতে পারবেন -- অ্যাপ্লিকেশন স্থিতি পর্যবেক্ষণ করতে পারবেন +Spring Boot Dashboard থেকে আপনি: +- ওয়ার্কস্পেসের সব উপলব্ধ Spring Boot অ্যাপ্লিকেশন দেখতে পারবেন +- একটি ক্লিকে অ্যাপ্লিকেশন শুরু বা বন্ধ করতে পারবেন +- অ্যাপ্লিকেশন লগস রিয়েল-টাইমে দেখতে পারবেন +- অ্যাপ্লিকেশন স্ট্যাটাস মনিটর করতে পারবেন -সরাসরি "prompt-engineering" এর পাশে প্লে বোতামে ক্লিক করে এই মডিউল চালু করুন, অথবা সকল মডিউল একসাথে শুরু করুন। +শুধুমাত্র "prompt-engineering" এর পাশের প্লে বোতামে ক্লিক করে এই মডিউল শুরু করুন, অথবা সব মডিউল একবারে চালু করুন। Spring Boot Dashboard -*VS Code এর Spring Boot ড্যাশবোর্ড — এক স্থান থেকে সব মডিউল শুরু, বন্ধ ও পর্যবেক্ষণ করুন* +*VS Code এ Spring Boot Dashboard — এক জায়গা থেকে সব মডিউল শুরু, বন্ধ ও মনিটর করুন* -**বিকল্প ২: শেল স্ক্রিপ্ট ব্যবহার** +**বিকল্প ২: শেল স্ক্রিপ্ট ব্যবহার করে** -সব ওয়েব অ্যাপ্লিকেশন চালু করুন (মডিউল 01-04): +সব ওয়েব অ্যাপ্লিকেশন (মডিউল 01-04) শুরু করুন: **Bash:** ```bash @@ -474,11 +474,11 @@ cd .. # রুট ডিরেক্টরি থেকে **PowerShell:** ```powershell -cd .. # মূল ডিরেক্টরি থেকে +cd .. # রুট ডিরেক্টরি থেকে .\start-all.ps1 ``` -অথবা শুধু এই মডিউল শুরু করুন: +অথবা শুধুমাত্র এই মডিউল চালু করুন: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -উভয় স্ক্রিপ্ট স্বয়ংক্রিয়ভাবে রুট `.env` ফাইল থেকে পরিবেশ ভেরিয়েবল লোড করে এবং JAR ফাইলগুলি তৈরি করবে যদি সেগুলি না থাকে। +দুটি স্ক্রিপ্টই স্বয়ংক্রিয়ভাবে রুট `.env` ফাইল থেকে পরিবেশ ভেরিয়েবল লোড করে এবং যদি JAR ফাইল না থাকে তবে তৈরি করবে। -> **বিঃদ্রঃ:** যদি আপনি শুরু করার আগে সব মডিউল নিজে নিজে তৈরি করতে চান: +> **নোট:** যদি আপনি সমস্ত মডিউল ম্যানুয়ালি তৈরি করতে চান চালানোর আগে: > > **Bash:** > ```bash @@ -510,87 +510,87 @@ cd 02-prompt-engineering আপনার ব্রাউজারে http://localhost:8083 খুলুন। -**বন্ধ করতে:** +**থামাতে:** **Bash:** ```bash -./stop.sh # শুধুমাত্র এই মডিউল +./stop.sh # কেবল এই মডিউল # অথবা -cd .. && ./stop-all.sh # সমস্ত মডিউলগুলি +cd .. && ./stop-all.sh # সমস্ত মডিউলসমূহ ``` **PowerShell:** ```powershell -.\stop.ps1 # শুধুমাত্র এই মডিউল +.\stop.ps1 # শুধু এই মডিউল # অথবা -cd ..; .\stop-all.ps1 # সমস্ত মডিউল +cd ..; .\stop-all.ps1 # সব মডিউল ``` ## অ্যাপ্লিকেশন স্ক্রিনশট -এখানে প্রম্পট ইঞ্জিনিয়ারিং মডিউলের প্রধান ইন্টারফেস, যেখানে আপনি সব আটটি প্যাটার্ন পাশে পাশে পরীক্ষা করতে পারবেন। +এখানে প্রম্পট ইঞ্জিনিয়ারিং মডিউলের প্রধান ইন্টারফেস, যেখানে আপনি পাশে পাশে আটটি প্যাটার্ন পরীক্ষা করতে পারেন। Dashboard Home -*মূল ড্যাশবোর্ড যেখানে সব ৮টি প্রম্পট ইঞ্জিনিয়ারিং প্যাটার্ন তাদের স্বকীয়তা ও ব্যবহার ক্ষেত্রসহ দেখানো হয়েছে* +*প্রধান ড্যাশবোর্ড যেখানে সব ৮টি প্রম্পট ইঞ্জিনিয়ারিং প্যাটার্ন তাদের বৈশিষ্ট্য ও ব্যবহারের ক্ষেত্রে প্রদর্শিত হয়েছে* -## প্যাটার্নগুলি আবিষ্কার করা +## প্যাটার্নগুলি পরীক্ষা করা -ওয়েব ইন্টারফেসে আপনি বিভিন্ন প্রম্পটিং কৌশল পরীক্ষা করতে পারেন। প্রতিটি প্যাটার্ন বিভিন্ন সমস্যা সমাধান করে – দেখে নিন কোন পদ্ধতি কখন কার্যকর। +ওয়েব ইন্টারফেসটি আপনাকে বিভিন্ন প্রম্পটিং স্ট্র্যাটেজি নিয়ে পরীক্ষা করতে দেয়। প্রতিটি প্যাটার্ন বিভিন্ন সমস্যা সমাধান করে — দেখে নিন কখন কোন পদ্ধতি কার্যকর। -> **বিঃদ্রঃ: স্ট্রিমিং বনাম নন-স্ট্রিমিং** — প্রতিটি প্যাটার্ন পৃষ্ঠায় দুইটি বোতাম আছে: **🔴 Stream Response (Live)** এবং একটি **Non-streaming** বিকল্প। স্ট্রিমিং Server-Sent Events (SSE) ব্যবহার করে মডেল তৈরি করা টোকেনগুলো রিয়েল-টাইমে দেখায়, তাই আপনি প্রগতি তৎক্ষণাৎ দেখতে পাবেন। নন-স্ট্রিমিং বিকল্প পুরো উত্তর আসার জন্য অপেক্ষা করে তারপর প্রদর্শন করে। গভীর যুক্তি প্রয়োজন এমন প্রম্পটের জন্য (যেমন High Eagerness, Self-Reflecting Code), নন-স্ট্রিমিং অনেক সময় নিতে পারে — কখনও কখনও মিনিটের পর মিনিট — কিন্তু কোনো দৃশ্যমান প্রতিক্রিয়া থাকে না। **জটিল প্রম্পট পরীক্ষা করার সময় স্ট্রিমিং ব্যবহার করুন** যাতে আপনি মডেল কাজ করছে দেখতে পারেন এবং মনে না হয় অনুরোধ সময়সীমা পেরিয়েছে। +> **নোট: স্ট্রিমিং বনাম নন-স্ট্রিমিং** — প্রতিটি প্যাটার্ন পৃষ্ঠায় দুইটি বোতাম রয়েছে: **🔴 স্ট্রিম রেসপন্স (লাইভ)** এবং একটি **নন-স্ট্রিমিং** বিকল্প। স্ট্রিমিং সার্ভার-সেন্ট ইভেন্টস (SSE) ব্যবহার করে মডেল যখন টোকেন তৈরি করে তখন তা রিয়েল-টাইমে প্রদর্শন করে, আপনি অগ্রগতি তৎক্ষণাৎ দেখতে পারেন। নন-স্ট্রিমিং বিকল্প পুরো উত্তর পাওয়ার পর দেখায়। গভীর যুক্তি বিলম্বিত প্রম্পটগুলিতে (যেমন, High Eagerness, Self-Reflecting Code), নন-স্ট্রিমিং কল অনেকক্ষন লাগতে পারে — কখনো কখনো মিনিট পর্যন্ত — কোন দৃশ্যমান ফিডব্যাক ছাড়াই। **জটিল প্রম্পটের পরীক্ষায় স্ট্রিমিং ব্যবহার করুন** যাতে মডেল কাজ করছে দেখতে পারেন এবং মনে না হয় অনুরোধ টাইমআউট হয়েছে। > -> **ব্রাউজার প্রয়োজনীয়তা** — স্ট্রিমিং ফিচার Fetch Streams API (`response.body.getReader()`) ব্যবহার করে, যা পূর্ণ ব্রাউজার (Chrome, Edge, Firefox, Safari) এ কাজ করে। VS Code এর বিল্ট-ইন Simple Browser এ কাজ করে না, কারণ তার webview ReadableStream API সমর্থন করে না। Simple Browser ব্যবহার করলে নন-স্ট্রিমিং বোতামগুলি স্বাভাবিক কাজ করবে — শুধু স্ট্রিমিং বোতামগুলো প্রভাবিত হবে। পূর্ণ অভিজ্ঞতার জন্য http://localhost:8083 একটি বাহ্যিক ব্রাউজারে খুলুন। +> **নোট: ব্রাউজার প্রয়োজনীয়তা** — স্ট্রিমিং বৈশিষ্ট্য Fetch Streams API (`response.body.getReader()`) ব্যবহার করে যা একটি সম্পূর্ণ ব্রাউজার (Chrome, Edge, Firefox, Safari) প্রয়োজন। VS Code এর বিল্ট-ইন Simple Browser কাজ করেনা কারণ তার ওয়েবভিউ ReadableStream API সমর্থন করে না। Simple Browser ব্যবহার করলে নন-স্ট্রিমিং বোতামগুলি স্বাভাবিকভাবে কাজ করবে — কেবল স্ট্রিমিং বোতামগুলি প্রভাবিত হবে। পূর্ণ অভিজ্ঞতার জন্য `http://localhost:8083` একটি বাহ্যিক ব্রাউজারে খুলুন। -### কম বনাম উচ্চ আগ্রহ +### Low বনাম High Eagerness -সহজ প্রশ্ন জিজ্ঞাসা করুন, যেমন "200 এর 15% কত?" কম আগ্রহ ব্যবহার করে। আপনি দ্রুত, সরাসরি উত্তর পাবেন। এখন জটিল কিছু জিজ্ঞাসা করুন, যেমন "একটি উচ্চ-ট্রাফিক API এর জন্য কীভাবে ক্যাশিং কৌশল ডিজাইন করবেন" উচ্চ আগ্রহ ব্যবহার করে। **🔴 Stream Response (Live)** এ ক্লিক করুন এবং মডেলের বিস্তারিত যুক্তি টোকেন অনুযায়ী আসতে দেখুন। একই মডেল, একই প্রশ্ন কাঠামো - তবে প্রম্পট তাকে কতটা চিন্তা করতে হবে বলে নির্দেশ দেয়। +সহজ প্রশ্ন করুন যেমন "What is 15% of 200?" লো ইগারনেস দিয়ে। আপনি সঙ্গে সঙ্গেই সরাসরি উত্তর পাবেন। এখন জটিল কিছু জিজ্ঞাসা করুন যেমন "Design a caching strategy for a high-traffic API" হাই ইগারনেসে। ক্লিক করুন **🔴 স্ট্রিম রেসপন্স (লাইভ)** এবং মডেলের বিস্তারিত যুক্তি প্রতিটি টোকেনের মাধ্যমে দেখতে পাবেন। একই মডেল, একই প্রশ্ন কাঠামো — কিন্তু প্রম্পট বলে কতটা চিন্তা করতে হবে। -### টাস্ক এক্সিকিউশন (টুল প্রিম্বলস) +### টাস্ক এক্সেকিউশন (টুল প্রিমেবলস) -মাল্টি-স্টেপ ওয়ার্কফ্লো সাধনায় প্রথমে পরিকল্পনা ও প্রগতি বর্ণনা উপকারী হয়। মডেল বলে দেয় কি করবে, প্রতিটি ধাপ বর্ণনা করে, তারপর ফলাফল সারাংশ দেয়। +বহু ধাপের কর্মপ্রবাহ আগাম পরিকল্পনা এবং অগ্রগতি বর্ণনা থেকে লাভবান হয়। মডেল বলবে কি করবে, প্রতিটি ধাপ বর্ণনা করবে, তারপর ফলাফল সংক্ষেপ করবে। ### সেলফ-রিফ্লেক্টিং কোড -"একটি ইমেইল বৈধতা সেবা তৈরি করুন" চেষ্টা করুন। শুধু কোড তৈরি করে থেমে না, মডেল কোড তৈরি করে, গুণগত মান যাচাই করে, দুর্বলতা সনাক্ত করে এবং উন্নত করে। আপনি দেখবেন এটি কতক্ষণ পুনরাবৃত্তি করে যতক্ষণ কোড প্রোডাকশন মান পূরণ করে। +"Create an email validation service" চেষ্টা করুন। শুধু কোড তৈরি করে বন্ধ না করে, মডেল কোড তৈরি, গুণগত মান যাচাই, দুর্বলতা চিহ্নিতকরণ এবং উন্নতি করে। আপনি দেখবেন এটি পুনরাবৃত্তি করছে যতক্ষণ না কোড উৎপাদন মান পূরণ করে। -### স্ট্রাকচারড অ্যানালিসিস +### স্ট্রাকচার্ড অ্যানালাইসিস -কোড রিভিউ এর জন্য নির্দিষ্ট মূল্যায়ন ফ্রেমওয়ার্ক দরকার। মডেল কোড বিশ্লেষণ করে নির্দিষ্ট বিভাগে (সঠিকতা, চর্চা, কর্মক্ষমতা, সুরক্ষা) এবং গাম্ভীর্যের স্তর নির্ধারণ করে। +কোড রিভিউগুলি জন্য ধারাবাহিক মূল্যায়ন কাঠামো প্রয়োজন। মডেল নির্দিষ্ট বিভাগে (সঠিকতা, প্রাকটিস, পারফরম্যান্স, সিকিউরিটি) কোড পর্যালোচনা করে এবং তীব্রতা মাত্রা দেয়। ### মাল্টি-টার্ন চ্যাট -"Spring Boot কী?" জিজ্ঞাসা করুন, তারপর তৎক্ষণাৎ "আমাকে একটি উদাহরণ দেখাও" বলুন। মডেল আপনার প্রথম প্রশ্ন স্মরণ রাখে এবং স্পেসিফিক একটি Spring Boot উদাহরণ দেয়। স্মৃতি না থাকলে দ্বিতীয় প্রশ্নটি খুব অস্পষ্ট হত। +"Spring Boot কি?" জিজ্ঞাসা করুন, তারপর সঙ্গে সঙ্গে "Show me an example" বলুন। মডেল আপনার প্রথম প্রশ্ন মনে রাখে এবং আপনাকে Spring Boot এ উদাহরণ দেয়। স্মৃতি ছাড়া দ্বিতীয় প্রশ্ন অস্পষ্ট হত। ### ধাপে ধাপে যুক্তি -কোনো গণিত সমস্যার কাজ নিয়ে দেখুন ধাপে ধাপে যুক্তি এবং কম আগ্রহ দিয়ে। কম আগ্রহ দ্রুত উত্তর দেয় - দ্রুত কিন্তু অস্বচ্ছ। ধাপে ধাপে প্রতিটি হিসাব ও সিদ্ধান্ত দেখায়। +কোনো গণিত সমস্যা নিন এবং এটি Step-by-Step Reasoning এবং Low Eagerness দিয়ে চেষ্টা করুন। লো ইগারনেস দ্রুত কিন্তু অস্পষ্ট উত্তর দেয়। ধাপে ধাপে গণনা ও সিদ্ধান্ত দেখায়। -### সীমাবদ্ধ আউটপুট +### সংকীর্ণ আউটপুট -যখন নির্দিষ্ট ফরম্যাট বা শব্দ সংখ্যা দরকার, এই প্যাটার্ন কঠোরভাবে অনুসরণ করে। উদাহরণস্বরূপ ঠিক ১০০ শব্দের বুলেট পয়েন্ট সারসংক্ষেপ তৈরি করুন। +যখন নির্দিষ্ট ফরম্যাট বা শব্দসংকোচন প্রয়োজন, এই প্যাটার্ন কঠোরভাবে তা নিশ্চিত করে। ঠিক ১০০ শব্দের সারসংক্ষেপ বিন্দু আকারে তৈরি করার চেষ্টা করুন। ## আপনি আসলেই কি শিখছেন **যুক্তি প্রচেষ্টা সবকিছু পরিবর্তন করে** -GPT-5.2 আপনাকে আপনার প্রম্পটের মাধ্যমে কম্পিউটেশনাল প্রচেষ্টা নিয়ন্ত্রণ করতে দেয়। কম প্রচেষ্টা মানে দ্রুত সাড়া, সীমিত অনুসন্ধান। উচ্চ প্রচেষ্টা মানে মডেল গভীরভাবে চিন্তা করে। আপনি শিখছেন কিভাবে কাজের জটিলতার সাথে প্রচেষ্টা মিলিয়ে নিতে হয় - সহজ প্রশ্নে সময় নষ্ট করবেন না, কিন্তু জটিল সিদ্ধান্তও তাড়াহুড়ো করবেন না। +GPT-5.2 আপনাকে প্রম্পটের মাধ্যমে গাণিতিক প্রচেষ্টা নিয়ন্ত্রণ করতে দেয়। কম প্রচেষ্টা মানে দ্রুত উত্তর ও কম অনুসন্ধান। বেশি প্রচেষ্টায় মডেল গভীর চিন্তা করে। আপনি শিখছেন কাজের জটিলতার সাথে প্রচেষ্টা মিলিয়ে নিতে — সহজ প্রশ্নে সময় নষ্ট করবেন না, কিন্তু জটিল সিদ্ধান্ত তাড়াহুড়ো করবেন না। -**কাঠামো আচরণ নির্দেশ করে** +**কাঠামো আচরণ পরিচালনা করে** -প্রম্পটে দেখতে XML ট্যাগ আছে? সেগুলো সাজসরঞ্জাম নয়। মডেলগুলো গঠনভিত্তিক নির্দেশ ভালভাবে অনুসরণ করে। যখন মাল্টি-স্টেপ প্রক্রিয়া বা জটিল যুক্তি দরকার, কাঠামো মডেলকে ঠিক কতদূর গিয়েছে এবং পরবর্তী ধাপ কি তা বুঝতে সাহায্য করে। নিচের চিত্রটি একটি সুসংগঠিত প্রম্পটের গঠন দেখায়, যেখানে ``, ``, ``, ``, এবং `` ট্যাগগুলো স্পষ্ট বিভাগে আপনার নির্দেশ দেয়। +প্রম্পটে XML ট্যাগ লক্ষ্য করেছেন? এগুলো সাজানোর জন্য। মডেল গঠনযুক্ত নির্দেশনা বেশি নির্ভরযোগ্যভাবে অনুসরণ করে। অনেক ধাপ প্রক্রিয়া বা জটিল যুক্তি দরকার হলে কাঠামো মডেলকে সাহায্য করে কোথায় আছে এবং পরবর্তী কী জানার। নিচের চিত্রে দেখুন কীভাবে ``, ``, ``, ``, এবং `` ট্যাগগুলি স্পষ্ট বিভাগে আপনার নির্দেশ সমন্বয় করে। Prompt Structure -*পরিষ্কার বিভাগের সাথে সুসংগঠিত প্রম্পটের অ্যানাটমি এবং XML-ধাঁচের সংগঠন* +*ভালভাবে গঠিত প্রম্পটের গঠন এবং XML-ধাঁচের সংগঠন* -**গুণগত মান স্ব-মূল্যায়নের মাধ্যমে** +**স্ব-মূল্যায়নের মাধ্যমে গুণগত মান** -সেলফ-রিফ্লেক্টিং প্যাটার্নগুলো গুণগত মান স্পষ্ট করে দেয়। মডেল "ঠিক কাজ করেছে" আশা না করে আপনি ঠিক কি "ঠিক" তা বলেন: সঠিক যুক্তি, ত্রুটি হ্যান্ডলিং, কর্মক্ষমতা, নিরাপত্তা। এরপর মডেল নিজের আউটপুট মূল্যায়ন করে উন্নতি করতে পারে। এটি কোড তৈরি প্রক্রিয়াকে লটারি থেকে পদ্ধতিতে পরিণত করে। +সেলফ-রিফ্লেক্টিং প্যাটার্নগুলি গুণগত মান স্পষ্ট করে দেয়। মডেল "সঠিক" করার আশা না রেখে আপনি বলেন ঠিক কি "সঠিক": সঠিক যুক্তি, ত্রুটি হ্যান্ডলিং, পারফরম্যান্স, সিকিউরিটি। মডেল তার আউটপুট নিজে মূল্যায়ন করে উন্নত করতে পারে। কোড তৈরি প্রক্রিয়াটিকে পুরষ্কার এর বদলে একটি ধারাবাহিক প্রক্রিয়ায় পরিণত করে। **প্রসঙ্গ সীমিত** -মাল্টি-টার্ন কথোপকথন প্রতিটি অনুরোধের সাথে মেসেজ ইতিহাস রাখার মাধ্যমে কাজ করে। কিন্তু একটি সীমা আছে - প্রতিটি মডেলের সর্বোচ্চ টোকেন সংখ্যা। কথোপকথন বাড়ার সাথে সাথে আপনাকে কৌশল পান যাতে প্রাসঙ্গিক প্রসঙ্গ বজায় থাকে ছাড়াই সীমা ছাড়িয়ে না যায়। এই মডিউলটি আপনাকে স্মৃতি কিভাবে কাজ করে দেখায়; পরে আপনি শিখবেন কখন সারসংক্ষেপ করতে হয়, কখন ভুলে যেতে হয়, এবং কখন পুনরুদ্ধার করতে হয়। +মাল্টি-টার্ন কথোপকথন কাজ করে প্রতিটি অনুরোধের সাথে মেসেজ ইতিহাস অন্তর্ভুক্ত করে। কিন্তু এক সীমা আছে—প্রতিটি মডেলের সর্বোচ্চ টোকেন সংখ্যা। কথোপকথন বাড়ার সাথে আপনাকে প্রাসঙ্গিক প্রসঙ্গ ধরে রাখার কৌশল শিখতে হবে যাতে সীমা ছাড়িয়ে না যায়। এই মডিউলে দেখানো হয়েছে স্মৃতি কীভাবে কাজ করে; পরে শিখবেন কখন সারাংশ দিতে, কখন ভুলতে, এবং কখন পুনরুদ্ধার করতে। ## পরবর্তী ধাপ @@ -603,6 +603,6 @@ GPT-5.2 আপনাকে আপনার প্রম্পটের মাধ --- -**দায়ভার বিবৃতি**: -এই ডকুমেন্টটি AI অনুবাদ সেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। আমরা সঠিকতার জন্য চেষ্টা করি, তবে স্বয়ংচালিত অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল ডকুমেন্টের নিজস্ব ভাষা হলো কর্তৃত্বপূর্ণ উত্স হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানুষ দ্বারা অনুবাদ করানোই সুপারিশ করা হয়। এই অনুবাদ ব্যবহারের ফলে কোন ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়ী নই। +**অস্বীকৃতি**: +এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা শুদ্ধতার জন্য চেষ্টা করি, অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার স্বভাষায় কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে প্রয়োজনীয় ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই। \ No newline at end of file diff --git a/translations/bn/03-rag/README.md b/translations/bn/03-rag/README.md index 77b4e64f9..4e08c45cb 100644 --- a/translations/bn/03-rag/README.md +++ b/translations/bn/03-rag/README.md @@ -1,146 +1,143 @@ -# Module 03: RAG (রিট্রিভাল-অগমেন্টেড জেনারেশন) +# Module 03: RAG (রিট্রিভ্যাল-অগমেন্টেড জেনারেশন) ## Table of Contents -- [Video Walkthrough](../../../03-rag) -- [What You'll Learn](../../../03-rag) -- [Prerequisites](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Does This Tutorial Use?](../../../03-rag) -- [How It Works](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload a Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matters](../../../03-rag) -- [Next Steps](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding RAG](#understanding-rag) + - [Which RAG Approach Does This Tutorial Use?](#which-rag-approach-does-this-tutorial-use) +- [How It Works](#how-it-works) + - [Document Processing](#document-processing) + - [Creating Embeddings](#creating-embeddings) + - [Semantic Search](#semantic-search) + - [Answer Generation](#উত্তর-প্রজন্ম) +- [Run the Application](#অ্যাপ্লিকেশন-চালানো) +- [Using the Application](#অ্যাপ্লিকেশন-ব্যবহার) + - [Upload a Document](#ডকুমেন্ট-আপলোড-করুন) + - [Ask Questions](#প্রশ্ন-করুন) + - [Check Source References](#উত্স-রেফারেন্স-যাচাই-করুন) + - [Experiment with Questions](#প্রশ্ন-নিয়ে-পরীক্ষা-করুন) +- [Key Concepts](#মূল-ধারণাসমূহ) + - [Chunking Strategy](#অংশকরণ-কৌশল) + - [Similarity Scores](#সাদৃশ্য-স্কোর) + - [In-Memory Storage](#ইন-মেমরি-স্টোরেজ) + - [Context Window Management](#প্রসঙ্গ-উইন্ডো-ব্যবস্থাপনা) +- [When RAG Matters](#কখন-rag-গুরুত্বপূর্ণ) +- [Next Steps](#পরবর্তী-ধাপ) ## Video Walkthrough -এই লাইভ সেশনটি দেখুন যা এই মডিউল শুরু করার পদ্ধতি ব্যাখ্যা করে: +এই লাইভ সেশনটি দেখুন যা এই মডিউলটি শুরু করার উপায় ব্যাখ্যা করে: RAG with LangChain4j - Live Session ## What You'll Learn -পূর্বের মডিউলগুলোতে, আপনি শিখেছেন কীভাবে AI-এর সাথে কথোপকথন করতে হয় এবং কীভাবে আপনার প্রম্পটগুলো কার্যকরভাবে সাজাতে হয়। কিন্তু এখানে একটি মৌলিক সীমাবদ্ধতা আছে: ভাষার মডেলগুলি কেবলমাত্র প্রশিক্ষণের সময় যা শিখেছে সেটাই জানে। তারা আপনার কোম্পানির নীতি, আপনার প্রকল্পের ডকুমেন্টেশন বা যেকোনো তথ্যের বিষয়ে উত্তর দিতে পারবে না যা তাদের প্রশিক্ষণে ছিল না। +পূর্ববর্তী মডিউলগুলিতে, আপনি শিখেছেন কিভাবে AI এর সাথে কথোপকথন চালাবেন এবং কীভাবে আপনার প্রম্পটগুলো কার্যকরভাবে গঠন করবেন। কিন্তু একটি মৌলিক সীমাবদ্ধতা আছে: ভাষা মডেলগুলো শুধুমাত্র তারা প্রশিক্ষণের সময় যা শিখেছে তা জানে। তারা আপনার কোম্পানির নীতি, আপনার প্রকল্প ডকুমেন্টেশন বা যেকোনো তথ্য যা তারা প্রশিক্ষিত হয়নি সে সম্পর্কে প্রশ্নের উত্তর দিতে পারে না। -RAG (রিট্রিভাল-অগমেন্টেড জেনারেশন) এই সমস্যার সমাধান করে। মডেলকে আপনার তথ্য শেখানোর পরিবর্তে (যা ব্যয়বহুল এবং ব্যবহারিক নয়), আপনি এটিকে আপনার ডকুমেন্টগুলোর মধ্যে অনুসন্ধান করার ক্ষমতা দেন। কেউ যখন প্রশ্ন করে, সিস্টেম প্রাসঙ্গিক তথ্য খুঁজে বের করে এবং প্রম্পটে অন্তর্ভুক্ত করে। মডেল তারপর সেই প্রাপ্ত প্রসঙ্গের ভিত্তিতে উত্তর দেয়। +RAG (রিট্রিভ্যাল-অগমেন্টেড জেনারেশন) এই সমস্যার সমাধান করে। মডেলটিকে আপনার তথ্য শেখানোর চেষ্টা করার পরিবর্তে (যা ব্যয়বহুল এবং অকার্যকর), আপনি তাকে আপনার ডকুমেন্টগুলো থেকে অনুসন্ধান করার দক্ষতা দেন। যখন কেউ প্রশ্ন করে, সিস্টেম প্রাসঙ্গিক তথ্য খুঁজে বের করে এবং সেটি প্রম্পটের সাথে অন্তর্ভুক্ত করে। মডেল তখন সে প্রাপ্ত প্রসঙ্গের ভিত্তিতে উত্তর দেয়। -RAG কে এমন ভাবুন যেন মডেলকে একটি রেফারেন্স লাইব্রেরি দেওয়া হয়েছে। যখন আপনি একটি প্রশ্ন করবেন, সিস্টেম: +RAG কে ভাবুন মডেলটিকে একটি রেফারেন্স লাইব্রেরি দেওয়ার মতো। আপনি যখন প্রশ্ন করবেন, সিস্টেম: -1. **ব্যবহারকারীর প্রশ্ন** - আপনি একটি প্রশ্ন করবেন -2. **এম্বেডিং** - আপনার প্রশ্নকে এক ভেক্টরে রূপান্তরিত করে -3. **ভেক্টর অনুসন্ধান** - সাদৃশ্যপূর্ণ ডকুমেন্ট চাঙ্ক খুঁজে পায় -4. **প্রসঙ্গ সমন্বয়** - প্রম্পটে প্রাসঙ্গিক চাঙ্ক যোগ করে -5. **উত্তর প্রদান** - প্রাপ্ত প্রসঙ্গের উপর ভিত্তি করে LLM উত্তর তৈরি করে +1. **ব্যবহারকারী প্রশ্ন** - আপনি প্রশ্ন করেন +2. **এম্বেডিং** - আপনার প্রশ্নকে একটি ভেক্টরে রূপান্তরিত করা হয় +3. **ভেক্টর সার্চ** - অনুরূপ ডকুমেন্ট অংশ খুঁজে পাওয়া হয় +4. **প্রসঙ্গ একত্রিতকরণ** - প্রম্পটে প্রাসঙ্গিক অংশ যোগ করা হয় +5. **প্রতিক্রিয়া** - LLM প্রসঙ্গ অনুযায়ী উত্তর তৈরি করে -এটি মডেলের উত্তরকে আপনার বাস্তব ডেটার উপর ভিত্তি করে স্থির করে, যাতে এটি তার প্রশিক্ষণের জ্ঞানের ওপর নির্ভর না করে বা উত্তর বানিয়ে না দেয়। +এটি মডেলের উত্তরগুলিকে তার প্রশিক্ষণের জ্ঞানের উপর নির্ভর করার পরিবর্তে আপনার প্রকৃত ডেটার উপর ভিত্তি স্থাপন করে। ## Prerequisites -- [Module 00 - Quick Start](../00-quick-start/README.md) সম্পন্ন (এই মডিউলে পরে উল্লেখ করা Easy RAG উদাহরণের জন্য) -- [Module 01 - Introduction](../01-introduction/README.md) সম্পন্ন (Azure OpenAI রিসোর্সসমূহ স্থাপনকৃত, যার মধ্যে রয়েছে `text-embedding-3-small` এম্বেডিং মডেল) -- রুট ডিরেক্টরিতে `.env` ফাইল, যার মধ্যে Azure এর ক্রেডেনশিয়ালস রয়েছে (মডিউল 01-এ `azd up` দিয়ে তৈরি) +- সম্পন্ন [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI সম্পদগুলি স্থাপিত রয়েছে, যার মধ্যে রয়েছে `text-embedding-3-small` এম্বেডিং মডেল) +- রুট ডিরেক্টরিতে `.env` ফাইল যা Azure ক্রেডেনশিয়াল ধারণ করে (Module 01-এ `azd up` দ্বারা তৈরি) -> **Note:** আপনি যদি Module 01 সম্পন্ন না করে থাকেন, প্রথমে সেখানে দেওয়া ডিপ্লয়মেন্ট নির্দেশনা অনুসরণ করুন। `azd up` কমান্ড GPT চ্যাট মডেল এবং এই মডিউলে ব্যবহৃত এম্বেডিং মডেল উভয়ই ডিপ্লয় করে। +> **Note:** যদি আপনি Module 01 সম্পন্ন না করে থাকেন, প্রথমে সেখানে দেওয়া ডিপ্লয়মেন্ট নির্দেশনা অনুসরণ করুন। `azd up` কমান্ড GPT চ্যাট মডেল এবং এই মডিউলে ব্যবহৃত এম্বেডিং মডেল উভয়কেই ডিপ্লয় করে। ## Understanding RAG -নিচের ডায়াগ্রামটি মূল ধারণাটি দেখায়: কেবল মডেলের প্রশিক্ষণের ডেটার ওপর নির্ভর না করে, RAG তাকে আপনার ডকুমেন্টের একটি রেফারেন্স লাইব্রেরি দেয় যা সে প্রতিটি উত্তর তৈরি করার আগে পরামর্শ করতে পারে। +নীচের চিত্রটি মূল ধারণাটি দেখায়: মডেলের প্রশিক্ষণ তথ্যের ওপর নির্ভর করার পরিবর্তে, RAG এর মাধ্যমে প্রতিটি উত্তরের আগে এটি আপনার ডকুমেন্টের একটি রেফারেন্স লাইব্রেরি পরামর্শ করে। What is RAG -*এই ডায়াগ্রামটি দেখায় একটি সাধারণ LLM (যা প্রশিক্ষণ তথ্য থেকে অনুমান করে) এবং RAG-সক্ষম LLM (যা প্রথমে আপনার ডকুমেন্টগুলো পরামর্শ করে) এর মধ্যে পার্থক্য।* +*এই চিত্রটি একটি সাধারণ LLM (যে প্রশিক্ষণ তথ্য থেকে অনুমান করে) এবং একটি RAG-বর্ধিত LLM (যে প্রথমে আপনার ডকুমেন্ট পরামর্শ করে) এর মধ্যে পার্থক্য দেখায়।* -এটি হলো শেষ পর্যন্ত পিসিগুলোর সংযোগের ধারা। এক ব্যবহারকারীর প্রশ্ন চারটি পর্যায় দিয়ে প্রবাহিত হয় — এম্বেডিং, ভেক্টর অনুসন্ধান, প্রসঙ্গ সমন্বয়, এবং উত্তর তৈরি — প্রতিটি একটি পূর্ববর্তী ধাপের ওপর ভিত্তি করে: +এখানে পুরো প্রক্রিয়াটি বুঝুন যেখানে ব্যবহারকারীর প্রশ্ন চারটি ধাপের মধ্য দিয়ে চলে — এম্বেডিং, ভেক্টর সার্চ, প্রসঙ্গ একত্রিতকরণ এবং উত্তর উত্পাদন — প্রতিটি আগেরটির ওপর ভিত্তি করে: RAG Architecture -*এই ডায়াগ্রামটি দেখায় সমগ্র RAG পাইপলাইন — একজন ব্যবহারকারীর প্রশ্ন এম্বেডিং, ভেক্টর অনুসন্ধান, প্রসঙ্গ সমন্বয়, এবং উত্তর জেনারেশনের মাধ্যমে প্রবাহিত হয়।* +*এই চিত্রটি শেষ পর্যন্ত RAG পাইপলাইন দেখায় — ব্যবহারকারীর প্রশ্ন এম্বেডিং, ভেক্টর সার্চ, প্রসঙ্গ একত্রিতকরণ, এবং উত্তর উত্পাদনের মধ্য দিয়ে যায়।* -এরপরের অংশে প্রতিটি ধাপ বিস্তারিতভাবে ধাপে ধাপে বর্ণনা করা হয়েছে, কোডসহ যা আপনি রান ও পরিবর্তন করতে পারেন। +এই মডিউলের বাকি অংশে প্রতিটি ধাপে বিস্তারিত ব্যাখ্যা দেওয়া হয়েছে, কোডসহ যা আপনি চালাতে এবং পরিবর্তন করতে পারেন। ### Which RAG Approach Does This Tutorial Use? -LangChain4j RAG বাস্তবায়নের জন্য তিনটি পদ্ধতি প্রদান করে, প্রতিটি ভিন্ন স্তরের বিমূর্ততার। নিচের ডায়াগ্রামটি সেগুলো পার্শ্ব-পার্শ্ব তুলনা করে: +LangChain4j তিনটি RAG প্রয়োগ পদ্ধতি অফার করে, যার প্রত্যেকটি বিভিন্ন মাত্রার অবজেক্টিভ ও কাস্টমাইজেশন প্রদান করে। নিচের চিত্রে তাদের পারস্পরিক তুলনা করা হয়েছে: Three RAG Approaches in LangChain4j -*এই ডায়াগ্রামটি LangChain4j এর তিনটি RAG পদ্ধতির তুলনা করে — Easy, Native, এবং Advanced — তাদের মূল উপাদান এবং ব্যবহারের সময় দেখানো হয়েছে।* +*এই চিত্রটি LangChain4j এর তিনটি RAG পদ্ধতি — Easy, Native, এবং Advanced — তাদের প্রধান উপাদান এবং কখন কোনটি ব্যবহার করবেন তা প্রদর্শন করে।* -| পদ্ধতি | কি করে | ট্রেড-অফ | +| পদ্ধতি | এটি কী করে | ট্রেড-অফ | |---|---|---| -| **Easy RAG** | সমস্ত কিছু স্বয়ংক্রিয়ভাবে `AiServices` এবং `ContentRetriever` এর মাধ্যমে যুক্ত করে। আপনি একটি ইন্টারফেস অ্যানোটেট করেন, রিট্রিভার যুক্ত করেন, আর LangChain4j এম্বেডিং, অনুসন্ধান, এবং প্রম্পট সমন্বয় পরিচালনা করে। | কোড কম, কিন্তু প্রতিটি ধাপে কি হচ্ছে তা দেখেন না। | -| **Native RAG** | আপনি এম্বেডিং মডেল কল করেন, স্টোরে অনুসন্ধান করেন, প্রম্পট তৈরি করেন, এবং নিজে উত্তর তৈরি করেন — এক ধাপে এক ধাপে স্পষ্টভাবে। | বেশি কোড লাগে, কিন্তু প্রতিটি স্তর দৃশ্যমান এবং পরিবর্তনযোগ্য। | -| **Advanced RAG** | `RetrievalAugmentor` ফ্রেমওয়ার্ক ব্যবহার করে প্লাগেবল কুয়েরি ট্রান্সফরমার, রাউটার, রেঙ্কার, এবং কনটেন্ট ইনজেক্টর দিয়ে প্রোডাকশন-গ্রেড পায়পলাইন তৈরি করে। | সর্বোচ্চ নমনীয়তা, কিন্তু জটিলতাও অনেক। | +| **Easy RAG** | সবকিছু স্বয়ংক্রিয়ভাবে `AiServices` এবং `ContentRetriever` এর মাধ্যমে সংযুক্ত করে। আপনি একটি ইন্টারফেস অ্যানোটেট করেন, একটি রিট্রিভার যুক্ত করেন, এবং LangChain4j এম্বেডিং, অনুসন্ধান, এবং প্রম্পট বানানো পিছনে সামলায়। | কোড কম, কিন্তু প্রতিটি ধাপের অন্তর্গত প্রক্রিয়া দেখা যায় না। | +| **Native RAG** | আপনি নিজে এম্বেডিং মডেল কল করেন, স্টোর সার্চ করেন, প্রম্পট তৈরি করেন, এবং উত্তর তৈরি করেন — প্রতিটি ধাপ স্পষ্ট একটি করে। | কোড বেশি, কিন্তু প্রতিটি ধাপ স্পষ্ট এবং পরিবর্তনযোগ্য। | +| **Advanced RAG** | `RetrievalAugmentor` ফ্রেমওয়ার্ক ব্যবহার করে, যা প্লাগযোগ্য কুয়েরি ট্রান্সফর্মার, রাউটার, রি-র্যাঙ্কার, এবং কনটেন্ট ইনজেক্টর সহ প্রোডাকশন-গ্রেড পাইপলাইন তৈরি করে। | সর্বোচ্চ নমনীয়তা, কিন্তু উল্লেখযোগ্যভাবে জটিল। | -**এই টিউটোরিয়ালে Native পদ্ধতিটি ব্যবহৃত হয়েছে।** RAG পাইপলাইনের প্রতিটি ধাপ — কুয়েরি এম্বেড করা, ভেক্টর স্টোরে অনুসন্ধান, প্রসঙ্গ সমন্বয়, এবং উত্তর জেনারেশন — [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ফাইলে স্পষ্টভাবে লেখা হয়েছে। এটি ইচ্ছাকৃত: শেখার জন্য, প্রতিটি ধাপ আপনি দেখতে ও বুঝতে পারেন তা বেশি গুরুত্বপূর্ণ, কোড কম হওয়া নয়। একবার আপনি সহজে বুঝে গেলে, দ্রুত প্রোটোটাইপের জন্য Easy RAG-এ যেতে পারেন অথবা প্রোডাকশনের জন্য Advanced RAG ব্যবহার করতে পারেন। +**এই টিউটোরিয়ালটি Native পদ্ধতি ব্যবহার করে।** RAG পাইপলাইনের প্রতিটি ধাপ — প্রশ্নের এম্বেডিং, ভেক্টর স্টোরে অনুসন্ধান, প্রসঙ্গ একত্রিতকরণ, এবং উত্তর উৎপাদন — স্পষ্টভাবে লেখা হয়েছে [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ফাইলে। এটি ইচ্ছাকৃত: একটি শেখার সম্পদ হিসেবে, প্রতিটি ধাপ দেখা ও বোঝা বেশি গুরুত্বপূর্ণ, কোড কমিয়ে ফেলা নয়। একবার আপনি বুঝে গেলে, দ্রুত প্রোটোটাইপের জন্য Easy RAG বা production সিস্টেমের জন্য Advanced RAG এ যেতে পারেন। -> **💡 ইতিমধ্যে Easy RAG দেখেছেন?** [Quick Start মডিউল](../00-quick-start/README.md) এ একটি ডকুমেন্ট Q&A উদাহরণ ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) আছে যা Easy RAG ব্যবহার করে — LangChain4j এম্বেডিং, অনুসন্ধান, এবং প্রম্পট সমন্বয় স্বয়ংক্রিয়ভাবে পরিচালনা করে। এই মডিউলটি পরবর্তী ধাপ যেখানে পাইপলাইনটি খুলে প্রতিটি ধাপ আপনি নিজে দেখতে এবং নিয়ন্ত্রণ করতে পারবেন। +> **💡 Easy RAG সম্পর্কে কৌতূহলী?** LangChain4j একটি *Easy RAG* পদ্ধতিও অফার করে যেখানে `AiServices` ও `ContentRetriever` স্বয়ংক্রিয়ভাবে এম্বেডিং, অনুসন্ধান এবং প্রম্পট সমন্বয় করে। এই মডিউলটি একটু বেশি স্পষ্ট পথ অনুসরণ করে — সুতরাং আপনি প্রতিটি ধাপ নিজেই দেখতে এবং নিয়ন্ত্রণ করতে পারেন। -নিচের ডায়াগ্রামে Quick Start উদাহরণের Easy RAG পাইপলাইন দেখানো হয়েছে। লক্ষ্য করুন `AiServices` এবং `EmbeddingStoreContentRetriever` কীভাবে জটিলতা ঢেকে রাখে — আপনি একটি ডকুমেন্ট লোড করেন, রিট্রিভার যুক্ত করেন, এবং উত্তর পান। এই মডিউলের Native পদ্ধতি প্রতিটি লুকানো ধাপ খুলে দেয়: +নীচের চিত্রটি Easy RAG পাইপলাইন দেখায়। লক্ষ্য করুন কিভাবে `AiServices` এবং `EmbeddingStoreContentRetriever` সমস্ত জটিলতা লুকিয়ে রাখে — আপনি একটি ডকুমেন্ট লোড করেন, রিট্রিভার সংযুক্ত করেন, এবং উত্তর পান। এই মডিউলটি Native পদ্ধতির মাধ্যমে ঐসব লুকানো ধাপ খুলে দেয়: Easy RAG Pipeline - LangChain4j -*এই ডায়াগ্রামটি `SimpleReaderDemo.java` এর Easy RAG পাইপলাইন দেখায়। এর সাথে এই মডিউলের Native পদ্ধতির তুলনা করুন: Easy RAG এম্বেডিং, রিট্রিভাল এবং প্রম্পট সমন্বয় `AiServices` এবং `ContentRetriever` এর পেছনে লুকিয়ে রাখে — আপনি শুধু ডকুমেন্ট লোড করেন, রিট্রিভার যুক্ত করেন, এবং উত্তর পেয়ে যান। Native পদ্ধতিতে প্রত্যেক ধাপ নিজে কল করতে হয় (এম্বেড, সার্চ, প্রসঙ্গ তৈরি, জেনারেট), যা সম্পূর্ণ নিয়ন্ত্রণ এবং দৃশ্যমানতা দেয়।* +*এই চিত্রটি Easy RAG পাইপলাইন দেখায়। Native পদ্ধতির সাথে তুলনা করুন যা এই মডিউলে ব্যবহৃত হয়েছে: Easy RAG `AiServices` এবং `ContentRetriever` এর পিছনে এম্বেডিং, রিট্রিভাল, এবং প্রম্পট সমন্বয় লুকায় — আপনি একটি ডকুমেন্ট লোড করেন, রিট্রিভার সংযুক্ত করেন, এবং উত্তর পান। এই মডিউলের Native পদ্ধতিটি ঐ পাইপলাইন খুলে দেয় যাতে আপনি নিজেই প্রতিটি ধাপ (এম্বেড, সার্চ, প্রসঙ্গ একত্রিতকরণ, উত্তর তৈরি) কল করতে পারেন, সম্পূর্ণ দৃশ্যমানতা এবং নিয়ন্ত্রণের জন্য।* ## How It Works -এই মডিউলের RAG পাইপলাইন চারটি ধাপে বিভক্ত যা ব্যবহারকারী প্রতি প্রশ্ন করলে ধারাবাহিকভাবে চলে। প্রথমেই, একটি আপলোড করা ডকুমেন্ট **পার্স এবং চাঙ্ক করা হয়** — এমন ছোট অংশে ভাগ করা হয় যা মডেলের প্রসঙ্গ উইন্ডোতে আরামদায়ক ফিট হয়। এই চাঙ্কগুলো একটু overlapped থাকে যাতে সীমান্তে প্রসঙ্গ হারানো না হয়। - -তারপর ঐ চাঙ্কগুলোকে **ভেক্টর এম্বেডিংয়ে রূপান্তরিত** করা হয় এবং সঞ্চয় করা হয় যাতে গণিতীয় তুলনা করা যায়। যখন একটি প্রশ্ন আসে, সিস্টেম একটি **সেমান্টিক সার্চ** চালায় যাতে সবচেয়ে প্রাসঙ্গিক চাঙ্ক পাওয়া যায়, এবং অবশেষে তাদের প্রসঙ্গ হিসেবে LLM-এ পাঠানো হয় **উত্তর তৈরি** এর জন্য। নিচের অংশগুলো প্রতিটি ধাপ কোড এবং ডায়াগ্রামসহ দেখায়। প্রথম ধাপ দেখা যাক। +এই মডিউলের RAG পাইপলাইন চারটি ধাপে বিভক্ত যা প্রতিবার ব্যবহারকারী প্রশ্ন করলে সিকোয়েন্সিয়ালি চলে। প্রথমে, আপলোড করা ডকুমেন্টটি **পার্স এবং চাঙ্ক** করা হয় ব্যবস্থাপনায়যোগ্য অংশে। সেগুলো পরে **ভেক্টর এম্বেডিং** এ রূপান্তরিত হয় এবং সংরক্ষণ করা হয় যাতে সেগুলো গাণিতিকভাবে তুলনা করা যায়। যখন একটি প্রশ্ন আসে, সিস্টেম একটি **সেমান্টিক সার্চ** সম্পাদন করে সবচেয়ে প্রাসঙ্গিক চাঙ্ক খুঁজে, এবং অবশেষে সেগুলোকে প্রসঙ্গ হিসেবে LLM-এ দেয় **উত্তর উত্পাদনের জন্য**। নিচের বিভাগগুলি প্রতিটি ধাপ কোড ও ছবিসহ বর্ণনা করে। প্রথম ধাপটি দেখি। ### Document Processing [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -আপনি যখন একটি ডকুমেন্ট আপলোড করেন, সিস্টেম সেটি পার্স করে (PDF বা সাধারণ টেক্সট), ফাইলনামের মতো মেটাডেটা সংযুক্ত করে, এবং চাঙ্কে ভাগ করে — ছোট ছোট অংশ যা মডেলের প্রসঙ্গ উইন্ডোর মধ্যে ফিট করে। এই চাঙ্কগুলো সামান্য overlapped থাকে যাতে সীমান্তে প্রসঙ্গ হারিয়ে না যায়। +যখন আপনি একটি ডকুমেন্ট আপলোড করেন, সিস্টেম এটি পার্স করে (PDF বা প্লেইন টেক্সট), ফাইলনামসহ মেটাডেটা সংযুক্ত করে, এবং তারপর সেটি ছোট ছোট চাঙ্কে বিভক্ত করে — এমন ছোট অংশ যা মডেলের প্রসঙ্গ উইন্ডোতে আরামদায়কভাবে ফিট করে। এই চাঙ্কগুলো কিছুটা ওভারল্যাপ করে যাতে সীমান্তে প্রসঙ্গ হারানো না যায়। ```java -// আপলোড করা ফাইলটি বিশ্লেষণ করুন এবং এটিকে একটি LangChain4j ডকুমেন্ট হিসেবে মোড়ান +// আপলোড করা ফাইলটি বিশ্লেষণ করুন এবং এটি LangChain4j ডকুমেন্টে মোড়ানো করুন Document document = Document.from(content, metadata); -// ৩০ টোকেন ওভারল্যাপ সহ ৩০০-টোকেনের অংশে বিভক্ত করুন +// ৩০০-টোকেন অংশে বিভক্ত করুন ৩০-টোকেন ওভারল্যাপ সহ DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -নিচের ডায়াগ্রামটি কিভাবে এটি ভিজ্যুয়ালি কাজ করে দেখায়। লক্ষ্য করুন প্রতিটি চাঙ্কের কিছু টোকেন প্রতিবেশীদের সাথে ভাগাভাগি করে — ৩০ টোকেন ওভারল্যাপ নিশ্চিত করে যে গুরুত্বপূর্ণ প্রসঙ্গ ফাঁক ফোকর হবেনা: +নীচের চিত্রটি এটি ভিজ্যুয়ালি কিভাবে কাজ করে দেখায়। লক্ষ্য করুন প্রতিটি চাঙ্ক তার প্রতিবেশীদের সাথে কিছু টোকেন শেয়ার করে — ৩০ টোকেন ওভারল্যাপ নিশ্চিত করে কোন গুরুত্বপূর্ণ প্রসঙ্গ ফেটে যাচ্ছে না: Document Chunking -*এই ডায়াগ্রামটি দেখায় কীভাবে একটি ডকুমেন্ট ৩০ টোকেন ওভারল্যাপ সহ ৩০০ টোকেন দীর্ঘ চাঙ্কে বিভক্ত হয়, চাঙ্ক সীমান্তে প্রসঙ্গ সংরক্ষণ করে।* +*এই চিত্রটি দেখায় কিভাবে একটি ডকুমেন্ট ৩০০ টোকেনের চাঙ্কে ভাগ করা হয় ৩০ টোকেন ওভারল্যাপ দিয়ে, যাতে চাঙ্ক সীমান্তে প্রসঙ্গ সংরক্ষিত থাকে।* -> **🤖 GitHub Copilot Chat দিয়ে চেষ্টা করুন:** খুলুন [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) এবং জিজ্ঞাসা করুন: -> - "LangChain4j কীভাবে ডকুমেন্টগুলো চাঙ্কে বিভক্ত করে এবং ওভারল্যাপ কেন গুরুত্বপূর্ণ?" -> - "বিভিন্ন ধরণের ডকুমেন্টে আদর্শ চাঙ্ক আকার কী এবং কেন?" -> - "কিভাবে একাধিক ভাষার ডকুমেন্ট বা বিশেষ ফরম্যাটিং থাকা ডকুমেন্ট হ্যান্ডেল করবেন?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat দিয়ে চেষ্টা করুন:** খুলুন [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) এবং জিজ্ঞাসা করুন: +> - "LangChain4j কিভাবে ডকুমেন্টগুলো চাঙ্কে ভাগ করে এবং কেন ওভারল্যাপ গুরুত্বপূর্ণ?" +> - "বিভিন্ন ডকুমেন্ট ধরণের জন্য সর্বোত্তম চাঙ্ক সাইজ কি এবং কেন?" +> - "আমি কিভাবে বিভিন্ন ভাষার ডকুমেন্ট অথবা বিশেষ ফরম্যাটিং সহ ডকুমেন্টগুলি হ্যান্ডেল করব?" ### Creating Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -প্রতিটি চাঙ্ককে একটি সংখ্যাগত উপস্থাপনায় রূপান্তরিত করা হয় যাকে এম্বেডিং বলা হয় — সহজভাবে বলতে গেলে মানে থেকে সংখ্যা তৈরি করার একটি কনভার্টার। এম্বেডিং মডেলটি "ইন্টেলিজেন্ট" নয়, যেমন একটি চ্যাট মডেল; এটি নির্দেশ মেনে চলে না, যুক্তি তৈরি করে না বা প্রশ্নের উত্তর দেয় না। যা করে তা হলো টেক্সটকে একটি গণিতীয় স্থানতে রূপান্তর করা যেখানে সাদৃশ্যপূর্ণ মানে কাছাকাছি থাকে — "গাড়ি" "অটোমোবাইল"-এর নিকটে, "রিফান্ড নীতি" "আমার টাকা ফেরত" এর কাছে। ভাবুন চ্যাট মডেল যেন একজন মানুষ যার সঙ্গে আপনি কথা বলতে পারেন; এম্বেডিং মডেল হল একটি খুব ভালো ফাইলিং সিস্টেম। +প্রতিটি চাঙ্ক একটি সংখ্যাসূচক প্রতিনিধিত্বে রূপান্তরিত করা হয়, যাকে এম্বেডিং বলা হয় — মূলত একটি অর্থ থেকে সংখ্যায় রূপান্তরকারী। এম্বেডিং মডেলটির "ইন্টেলিজেন্স" চ্যাট মডেলের মত নয়; এটি নির্দেশ মেনে চলে না, যুক্তি দেয় না বা প্রশ্নের উত্তর দেয় না। তবে এটি টেক্সটকে এমন একটি গাণিতিক স্থানে ম্যাপ করে যেখানে অনুরূপ অর্থের ভেক্টরগুলো একদম কাছে থাকে — যেমন "গাড়ি" এবং "অটোমোবাইল", "রিফান্ড পলিসি" এবং "আমার টাকা ফেরত"। চ্যাট মডেলকে ভাবুন একজন মানুষের মতো যাকে আপনি কথা বলতে পারেন; এম্বেডিং মডেল হলো অত্যন্ত ভাল একটি ফাইলিং সিস্টেম। -নিচের ডায়াগ্রামটি এই ধারণাটি দৃশ্যমান করে তোলে — টেক্সট ইনপুট হয়, সংখ্যাগত ভেক্টর আউটপুট হয়, আর সাদৃশ্যপূর্ণ মানে পরিচিত ভেক্টরগুলো একসঙ্গে থাকে: +নীচের চিত্রটি এই ধারণা ভিজ্যুয়াল করে — টেক্সট ঢুকে, সংখ্যাসূচক ভেক্টর বের হয়, এবং অনুরূপ অর্থ নিকটবর্তী ভেক্টরে থাকে: Embedding Model Concept -*এই ডায়াগ্রামটি দেখায় কীভাবে একটি এম্বেডিং মডেল টেক্সটকে সংখ্যাগত ভেক্টরে রূপান্তর করে এবং সাদৃশ্যপূর্ণ মানে — যেমন "গাড়ি" ও "অটোমোবাইল" — ভেক্টর স্থানে একসঙ্গে রাখে।* +*এই চিত্রটি দেখায় কিভাবে একটি এম্বেডিং মডেল টেক্সটকে সংখ্যাসূচক ভেক্টরে রূপান্তরিত করে, এবং অনুরূপ অর্থ — যেমন "গাড়ি" ও "অটোমোবাইল" — ভেক্টর স্পেসে একসাথে থাকে।* ```java @Bean @@ -156,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -নীচের ক্লাস ডায়াগ্রামটি RAG পাইপলাইনের দুইটি পৃথক প্রবাহ এবং LangChain4j ক্লাসগুলো দেখায় যা এগুলো বাস্তবায়ন করে। **ingestion flow** (আপলোডের সময় একবার চলবে) ডকুমেন্ট বিভক্ত করে, চাঙ্ক এম্বেড করে, এবং `.addAll()` এর মাধ্যমে সঞ্চয় করে। **query flow** (প্রতিবার ব্যবহারকারী প্রশ্ন করলে চলে) প্রশ্ন এম্বেড করে, `.search()` দিয়ে স্টোরে অনুসন্ধান করে, এবং ম্যাচ হওয়া প্রসঙ্গ চ্যাট মডেলে পাঠায়। উভয় প্রবাহ মিলিত হয় শেয়ার করা `EmbeddingStore` ইন্টারফেসে: +নীচের ক্লাস ডায়াগ্রামটি RAG পাইপলাইনের দুটি পৃথক প্রবাহ এবং LangChain4j ক্লাসগুলি দেখায় যা সেগুলো বাস্তবায়ন করে। **ইনজেশন ফ্লো** (আপলোডের সময় একবার চলে) ডকুমেন্ট বিভক্ত করে, চাঙ্ক এম্বেড করে, এবং `.addAll()` এর মাধ্যমে সংরক্ষণ করে। **কুয়েরি ফ্লো** (প্রতিবার প্রশ্ন করার সময়) প্রশ্ন এম্বেড করে, `.search()` এর মাধ্যমে স্টোরে সার্চ করে, এবং ম্যাচ করা প্রসঙ্গ চ্যাট মডেলে পাঠায়। উভয় ফ্লো একটি ভাগ করা `EmbeddingStore` ইন্টারফেসে মিলিত হয়: LangChain4j RAG Classes -*ডায়াগ্রামটি RAG পাইপলাইনের দুইটি প্রবাহ — ingestion এবং query — দেখায় এবং তারা কিভাবে শেয়ার করা EmbeddingStore-এর মাধ্যমে যুক্ত।* +*এই চিত্রটি RAG পাইপলাইনের দুটি প্রবাহ — ইনজেশন এবং কুয়েরি — এবং সেগুলো কীভাবে একটি ভাগ করা EmbeddingStore এর মাধ্যমে সংযুক্ত হয় দেখায়।* - এম্বেডিংগুলি সঞ্চয় করার পর, সাদৃশ্যপূর্ণ বিষয়বস্তু স্বাভাবিকভাবেই ভেক্টর স্থানে ক্লাস্টার হয়। নিচের ভিজ্যুয়ালাইজেশনটি দেখায় কীভাবে সম্পর্কিত বিষয়ের ডকুমেন্টস কাছাকাছি পয়েন্টে থাকে, যা সেমান্টিক সার্চ সম্ভব করে তোলে: +একবার এম্বেডিংগুলো সংরক্ষিত হলে, অনুরূপ কন্টেন্ট স্বাভাবিকভাবেই ভেক্টর স্পেসে ঘন হয়ে যায়। নিচের ভিজ্যুয়ালাইজেশনটি দেখায় কিভাবে সম্পর্কিত বিষয়ক ডকুমেন্টগুলো একসাথে গুচ্ছবদ্ধ হয়, যা সেমান্টিক সার্চকে সম্ভব করে তোলে: Vector Embeddings Space -*এই ভিজ্যুয়ালাইজেশনটি দেখায় কীভাবে সম্পর্কিত ডকুমেন্টগুলো ৩ডি ভেক্টর স্থানে ক্লাস্টার করে, যেখানে টেকনিক্যাল ডকস, বিজনেস রুলস, এবং FQA-এর মত বিষয়গুলো আলাদা আলাদা গ্রুপ তৈরি করে।* +*এই ভিজ্যুয়ালাইজেশন দেখায় কিভাবে সম্পর্কিত ডকুমেন্টগুলো ৩ডি ভেক্টর স্পেসে ক্লাস্টারায়, যেমন টেকনিক্যাল ডকস, বিজনেস রুলস, এবং FAQ আলাদা আলাদা গ্রুপ তৈরি করে।* -যখন ব্যবহারকারী অনুসন্ধান করে, সিস্টেম চারটি ধাপ অনুসরণ করে: ডকুমেন্টগুলো একবার এম্বেড করে, প্রতিবার সার্চ করার সময় প্রশ্ন এম্বেড করে, প্রশ্ন ভেক্টরকে সঞ্চিত সমস্ত ভেক্টরের সঙ্গে কসাইন সাদৃশ্য মাপ দিয়ে তুলনা করে, এবং সর্বোচ্চ স্কোরধারী টপ-কে চাঙ্কগুলো ফিরিয়ে দেয়। নিচের ডায়াগ্রামটি প্রতিটি ধাপ এবং LangChain4j ক্লাসগুলো দেখায়: +যখন ব্যবহারকারী সার্চ করে, সিস্টেম চারটি ধাপ অনুসরণ করে: ডকুমেন্ট একবার এম্বেড করা, প্রতিবার সার্চে প্রশ্ন এম্বেড করা, কজাইন সিমিলারিটি ব্যবহার করে সব ভেক্টরের বিপরীতে প্রশ্নের ভেক্টর তুলনা করা, এবং শীর্ষ-K নম্বরের সর্বোচ্চ স্কোর প্রাপ্ত চাঙ্ক ফেরত দেয়া। নিচের চিত্রটি প্রতিটি ধাপ এবং LangChain4j ক্লাসগুলি দেখায়: Embedding Search Steps -*এই ডায়াগ্রামটি চার ধাপের এম্বেডিং সার্চ প্রক্রিয়া দেখায়: ডকুমেন্ট এম্বেড করা, প্রশ্ন এম্বেড করা, ভেক্টর কসাইন সাদৃশ্য দিয়ে তুলনা, এবং টপ-কে ফলাফল ফেরত দেওয়া।* +*এই চিত্রটি চার ধাপের এম্বেডিং সার্চ প্রক্রিয়া দেখায়: ডকুমেন্ট এম্বেড করা, প্রশ্ন এম্বেড করা, কজাইন সিমিলারিটি দিয়ে ভেক্টর তুলনা, এবং শীর্ষ-ক ফলাফল ফেরত দেওয়া।* ### Semantic Search [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -আপনি যখন একটি প্রশ্ন করেন, আপনার প্রশ্নও একটি এম্বেডিংয়ে রূপান্তরিত হয়। সিস্টেম আপনার প্রশ্নের এম্বেডিং তুলনা করে সমস্ত ডকুমেন্ট চাঙ্কের এম্বেডিংয়ের সঙ্গে। এটি সবচেয়ে সাদৃশ্যপূর্ণ মানের চাঙ্কগুলো খুঁজে পায় - শুধু মিল থাকা কীওয়ার্ড নয়, প্রকৃত সেমান্টিক সাদৃশ্য। +আপনি যখন প্রশ্ন করেন, আপনার প্রশ্নও একটি এম্বেডিং হয়। সিস্টেম আপনার প্রশ্নের এম্বেডিংকে সব ডকুমেন্ট চাঙ্কের এম্বেডিংয়ের সঙ্গে তুলনা করে। এটি এমন চাঙ্ক খুঁজে পায় যার অর্থ সবচেয়ে অনুরূপ — শুধু ম্যাচিং কীওয়ার্ড নয়, বরং প্রকৃত সেমান্টিক সামঞ্জস্য। ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -198,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -নিচের ডায়াগ্রামটি সেমান্টিক সার্চ এবং প্রচলিত কীওয়ার্ড সার্চের পার্থক্য তুলে ধরে। "vehicle" কীওয়ার্ড সার্চ "cars and trucks" সম্পর্কে একটি চাঙ্ক মিস করে, কিন্তু সেমান্টিক সার্চ বোঝে তারা একই অর্থ বহন করে এবং তাকে উচ্চ মানের মিল হিসেবে ফেরত দেয়: +নীচের চিত্রটি সেমান্টিক সার্চ এবং প্রচলিত কীওয়ার্ড সার্চের পার্থক্য দেখায়। "vehicle" শব্দটির জন্য কীওয়ার্ড সার্চ "cars and trucks" সম্পর্কিত চাঙ্ক হারিয়ে ফেলে, কিন্তু সেমান্টিক সার্চ বুঝতে পারে এরা একই অর্থ বহন করে এবং সেটি উচ্চ স্কোরিং হিসেবে ফেরত দেয়: Semantic Search -*এই ডায়াগ্রামটি কীওয়ার্ড-বেসড সার্চ ও সেমান্টিক সার্চ তুলনা করে, দেখাচ্ছে কীভাবে সেমান্টিক সার্চ খুঁজে পায় ধারণাগতভাবে সম্পর্কিত বিষয়বস্তু এমনকি যখন সঠিক কীওয়ার্ড ভিন্ন হয়।* -অবজেক্টিভলি, সাদৃশ্য পরিমাপ করা হয় কসমাইন সাদৃশ্য ব্যবহার করে — মূলত প্রশ্ন করা হয় "এই দুই তীর একই দিকেই নির্দেশ করছে কি?" দুইটি অংশ সম্পূর্ণ ভিন্ন শব্দ ব্যবহার করতে পারে, কিন্তু যদি তারা একই অর্থ বহন করে তাহলে তাদের ভেক্টর একই দিকে নির্দেশ করে এবং স্কোর ১.০ এর কাছাকাছি হয়: +*এই চিত্রটি কীওয়ার্ড ভিত্তিক সার্চ এবং সেমান্টিক সার্চের তুলনা, দেখায় কিভাবে সেমান্টিক সার্চ ধারণাগতভাবে সম্পর্কিত কন্টেন্টকে পুনরুদ্ধার করে যদিও সঠিক কীওয়ার্ড ভিন্ন হয়।* -Cosine Similarity +অন্তর্দৃষ্টিতে, সামঞ্জস্য কজাইন সিমিলারিটি ব্যবহার করে পরিমাপ করা হয় — অর্থাৎ "এই দুইটি তীর একই দিকে ইঙ্গিত করছে?" দুইটি চাঙ্ক সম্পূর্ণ ভিন্ন শব্দ ব্যবহার করতে পারে, কিন্তু যদি তাদের অর্থ একই হয় তাহলে তাদের ভেক্টর একই দিকে ইঙ্গিত করে এবং স্কোর 1.0 এর কাছাকাছি হয়: -*এই চিত্রটি কসমাইন সাদৃশ্যকে এম্বেডিং ভেক্টরগুলোর মধ্যে কোণ হিসাবে বর্ণনা করে — বেশি সামঞ্জস্যপূর্ণ ভেক্টরগুলো ১.০ এর কাছাকাছি স্কোর পায়, যা উচ্চতর অর্থগত সাদৃশ্য নির্দেশ করে।* +Cosine Similarity +*এই চিত্রটি এমবেডিং ভেক্টরের মধ্যে কোসাইন সাদৃশ্য ধারণাকে কোণ হিসেবে দেখায় — বেশি সামঞ্জস্যপূর্ণ ভেক্টরগুলি ১.০ এর কাছাকাছি স্কোর পায়, যা উচ্চতর অর্থগত সাদৃশ্য নির্দেশ করে।* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat এর সাথে চেষ্টা করুন:** খুলুন [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) এবং প্রশ্ন করুন: -> - "এম্বেডিংসের সাথে সাদৃশ্য অনুসন্ধান কিভাবে কাজ করে এবং স্কোর নির্ধারণ করে কী?" -> - "কোন সাদৃশ্য সীমা ব্যবহার করা উচিত এবং এটি ফলাফলের উপর কী প্রভাব ফেলে?" -> - "যখন কোন প্রাসঙ্গিক ডকুমেন্ট পাওয়া যায় না তখন আমি কীভাবে হ্যান্ডল করব?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) চ্যাট দিয়ে চেষ্টা করুন:** খোলুন [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) এবং জিজ্ঞাসা করুন: +> - "এম্বেডিং এর মাধ্যমে সাদৃশ্য অনুসন্ধান কীভাবে কাজ করে এবং স্কোর নির্ধারণ করে কী?" +> - "আমি কোন সাদৃশ্য পরিমাণ সীমা ব্যবহার করব এবং এটি ফলাফলের উপরে কিভাবে প্রভাব ফেলে?" +> - "যখন কোনো প্রাসঙ্গিক ডকুমেন্ট পাওয়া যায় না তখন আমি কী করব?" -### উত্তর তৈরি +### উত্তর প্রজন্ম [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -সবচেয়ে প্রাসঙ্গিক অংশগুলো একত্রিত করে একটি গঠনমূলক প্রম্পটে রূপান্তর করা হয় যা স্পষ্ট নির্দেশাবলী, প্রাপ্ত প্রাসঙ্গিক বিষয়বস্তু, এবং ব্যবহারকারীর প্রশ্ন অন্তর্ভুক্ত করে। মডেল ওই নির্দিষ্ট অংশগুলো পড়ে এবং তথ্যের ভিত্তিতে উত্তর দেয় — এটি শুধুমাত্র সামনে থাকা তথ্য ব্যবহার করতে পারে, যেটা হ্যালুসিনেশন প্রতিরোধ করে। +সর্বাধিক প্রাসঙ্গিক অংশগুলোকে একত্রিত করে একটি কাঠামোবদ্ধ প্রম্পট তৈরি করা হয়, যা স্পষ্ট নির্দেশাবলী, প্রাপ্ত প্রসঙ্গ এবং ব্যবহারকারীর প্রশ্ন অন্তর্ভুক্ত করে। মডেল সে নির্দিষ্ট অংশগুলো পড়ে এবং সেই তথ্যের ভিত্তিতে উত্তর দেয় — এটি কেবল সামনে যা রয়েছে তা ব্যবহার করতে পারে, যা ভুল ধারণাকে প্রতিরোধ করে। ```java String context = matches.stream() @@ -239,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -নীচের চিত্রটি এই সংকলন প্রক্রিয়া প্রদর্শন করে — অনুসন্ধান ধাপ থেকে শীর্ষ স্কোরিং অংশগুলো প্রম্পট টেমপ্লেটে ইনজেক্ট করা হয়, এবং `OpenAiOfficialChatModel` একটি ভিত্তিপ্রাপ্ত উত্তর তৈরি করে: +নীচের চিত্রটি এই সংকলন প্রক্রিয়াটি দেখায় — অনুসন্ধান ধাপ থেকে সর্বোচ্চ স্কোরপ্রাপ্ত অংশগুলো প্রম্পট টেমপ্লেটে সংযুক্ত করা হয়, এবং `OpenAiOfficialChatModel` একটি ভিত্তিপ্রাপ্ত উত্তর তৈরি করে: Context Assembly -*এই চিত্রটি দেখায় কীভাবে শীর্ষ স্কোরিং অংশগুলো গঠনমূলক প্রম্পটে সংকলিত হয়, যা মডেলকে আপনার তথ্য থেকে ভিত্তিপ্রাপ্ত উত্তর তৈরি করতে সাহায্য করে।* +*এই চিত্রটি দেখায় কীভাবে সর্বোচ্চ স্কোরপ্রাপ্ত অংশগুলোকে কাঠামোবদ্ধ প্রম্পটে সংযুক্ত করা হয়, যা মডেলকে আপনার ডেটা থেকে একটি ভিত্তিপ্রাপ্ত উত্তর তৈরি করতে সক্ষম করে।* -## অ্যাপ্লিকেশন চালু করুন +## অ্যাপ্লিকেশন চালানো -**বিন্যাস যাচাই করুন:** +**ডিপ্লয়মেন্ট যাচাই করুন:** -রুট ডিরেক্টরিতে `.env` ফাইলটি আছে কিনা নিশ্চিত করুন, যার মধ্যে Azure ক্রেডেনশিয়াল রয়েছে (মডিউল ০১ এর সময় তৈরি)। মডিউল ডিরেক্টরি থেকে এটি চালান (`03-rag/`): +রুট ডিরেক্টরিতে `.env` ফাইলটি আছে কিনা নিশ্চিত করুন যাতে Azure সনদপত্র থাকে (মডিউল ০১ এ তৈরি)। এটি মডিউল ডিরেক্টরি (`03-rag/`) থেকে চালান: **Bash:** ```bash @@ -263,27 +260,27 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT দেখা **অ্যাপ্লিকেশন শুরু করুন:** -> **দ্রষ্টব্য:** যদি আপনি ইতিমধ্যেই সব অ্যাপ্লিকেশন `./start-all.sh` ব্যবহার করে রুট ডিরেক্টরি থেকে চালু করে থাকেন (যেমন মডিউল ০১ এ বর্ণিত), এই মডিউল ইতিমধ্যেই পোর্ট ৮০৮১ এ চলছে। তাই নিচের স্টার্ট কমান্ডগুলো এড়িয়ে সরাসরি http://localhost:8081 এ যেতে পারেন। +> **বিঃদ্রঃ:** যদি আপনি ইতোমধ্যে রুট ডিরেক্টরির থেকে `./start-all.sh` ব্যবহার করে সব অ্যাপ্লিকেশন চালু করে থাকেন (যেমন মডিউল ০১ এ বর্ণিত), তবে এই মডিউলটি ইতোমধ্যে পোর্ট ৮০৮১ এ চলছে। আপনি নিচের শুরু কমান্ডগুলো এড়িয়ে সরাসরি http://localhost:8081 এ যেতে পারেন। -**বিকল্প ১: Spring Boot Dashboard ব্যবহার করে (VS Code ব্যবহারকারীদের জন্য সুপারিশকৃত)** +**বিকল্প ১: স্প্রিং বুট ড্যাশবোর্ড ব্যবহার (VS Code ব্যবহারকারীদের জন্য সুপারিশকৃত)** -ডেভেলপমেন্ট কন্টেইনারে Spring Boot Dashboard এক্সটেনশন অন্তর্ভুক্ত, যা সব Spring Boot অ্যাপ্লিকেশন পরিচালনার জন্য একটি ভিজ্যুয়াল ইন্টারফেস প্রদান করে। আপনি VS Code এর বাম পাশে Activity Bar এ এটি পাবেন (Spring Boot আইকন খুঁজুন)। +ডেভ কনটেইনারটিতে স্প্রিং বুট ড্যাশবোর্ড এক্সটেনশন অন্তর্ভুক্ত, যা সব স্প্রিং বুট অ্যাপ্লিকেশন দেখাশোনা করার ভিজ্যুয়াল ইন্টারফেস দেয়। এটি VS Code এর বাম পাশে অ্যাকটিভিটি বারে পাওয়া যাবে (স্প্রিং বুট আইকন দেখুন)। -Spring Boot Dashboard থেকে আপনি: -- ওয়ার্কস্পেসে থাকা সব Spring Boot অ্যাপ্লিকেশন দেখতে পারবেন -- এক ক্লিকেই অ্যাপ্লিকেশন শুরু/বন্দ করতে পারবেন -- রিয়েল-টাইমে অ্যাপ্লিকেশন লগ দেখতে পারবেন -- অ্যাপ্লিকেশন স্ট্যাটাস মনিটর করতে পারবেন +স্প্রিং বুট ড্যাশবোর্ড থেকে আপনি: +- ওয়ার্কস্পেসে সব উপলব্ধ স্প্রিং বুট অ্যাপ্লিকেশন দেখতে পারেন +- একটি ক্লিকে অ্যাপ্লিকেশন শুরু/বন্ধ করতে পারেন +- অ্যাপ্লিকেশন লগ রিয়েল-টাইমে দেখতে পারেন +- অ্যাপ্লিকেশন অবস্থান পর্যবেক্ষণ করতে পারেন -শুধুমাত্র "rag" এর পাশে থাকা প্লে বোতামে ক্লিক করে এই মডিউল চালু করুন, অথবা একযোগে সব মডিউল শুরু করুন। +শুধুমাত্র "rag" এর পাশে প্লে বাটনে ক্লিক করে এই মডিউল চালু করুন, অথবা একবারে সব মডিউল শুরু করুন। Spring Boot Dashboard -*এই স্ক্রিনশটে দেখানো হয়েছে VS Code এ Spring Boot Dashboard, যেখানে আপনি অ্যাপ্লিকেশন গুলো শুরু, বন্ধ এবং পর্যবেক্ষণ করতে পারেন।* +*এই স্ক্রিনশটে VS Code এ স্প্রিং বুট ড্যাশবোর্ড প্রদর্শিত হয়েছে, যেখানে আপনি অ্যাপ্লিকেশনগুলি চালু, বন্ধ এবং মনিটর করতে পারেন ভিজ্যুয়ালি।* -**বিকল্প ২: শেল স্ক্রিপ্ট ব্যবহার করে** +**বিকল্প ২: শেল স্ক্রিপ্ট ব্যবহার** -সব ওয়েব অ্যাপ্লিকেশন (মডিউল ০১-০৪) শুরু করুন: +সব ওয়েব অ্যাপ্লিকেশন (মডিউল ০১-০৪) শুরু করুন: **Bash:** ```bash @@ -297,7 +294,7 @@ cd .. # রুট ডিরেক্টরি থেকে .\start-all.ps1 ``` -অথবা শুধুমাত্র এই মডিউলটি শুরু করুন: +অথবা কেবল এই মডিউল শুরু করুন: **Bash:** ```bash @@ -311,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -উভয় স্ক্রিপ্ট স্বয়ংক্রিয়ভাবে রুট `.env` ফাইল থেকে পরিবেশ ভেরিয়েবল লোড করবে এবং জারা (JAR) ফাইল না থাকলে তৈরি করবে। +উভয় স্ক্রিপ্ট স্বয়ংক্রিয়ভাবে রুট `.env` ফাইল থেকে পরিবেশ ভেরিয়েবল লোড করে এবং যদি JAR ফাইল না থাকে তবে নির্মাণ করে। -> **দ্রষ্টব্য:** যদি আপনি শুরু করার আগে সব মডিউল ম্যানুয়ালি তৈরি করতে চান: +> **বিঃদ্রঃ:** যদি আপনি শুরু করার আগে সব মডিউল ম্যানুয়ালি তৈরি করতে চান: > > **Bash:** > ```bash @@ -335,93 +332,93 @@ cd 03-rag ```bash ./stop.sh # শুধুমাত্র এই মডিউল # অথবা -cd .. && ./stop-all.sh # সব মডিউলসমূহ +cd .. && ./stop-all.sh # সব মডিউলগুলি ``` **PowerShell:** ```powershell -.\stop.ps1 # এই মডিউল শুধুমাত্র +.\stop.ps1 # শুধুমাত্র এই মডিউল # অথবা cd ..; .\stop-all.ps1 # সব মডিউলগুলি ``` ## অ্যাপ্লিকেশন ব্যবহার -অ্যাপ্লিকেশনটি ডকুমেন্ট আপলোড ও প্রশ্ন করার জন্য একটি ওয়েব ইন্টারফেস প্রদান করে। +অ্যাপ্লিকেশনটি ডকুমেন্ট আপলোড এবং প্রশ্ন করার জন্য একটি ওয়েব ইন্টারফেস প্রদান করে। RAG Application Interface -*এই স্ক্রিনশটে RAG অ্যাপ্লিকেশন ইন্টারফেস দেখানো হয়েছে যেখানে আপনি ডকুমেন্ট আপলোড এবং প্রশ্ন করতে পারেন।* +*এই স্ক্রিনশটে RAG অ্যাপ্লিকেশন ইন্টারফেস দেখানো হয়েছে যেখানে আপনি ডকুমেন্ট আপলোড করে প্রশ্ন করতে পারেন।* ### ডকুমেন্ট আপলোড করুন -প্রথমে একটি ডকুমেন্ট আপলোড করুন - TXT ফাইল পরীক্ষা করার জন্য সেরা। এই ডিরেক্টরিতে একটি `sample-document.txt` আছে যা LangChain4j ফিচার, RAG বাস্তবায়ন এবং সেরা অভ্যাস সম্পর্কিত তথ্য ধারণ করে - সিস্টেম টেস্টের জন্য উপযুক্ত। +একটি ডকুমেন্ট আপলোড দিয়ে শুরু করুন - টেক্সট ফাইল পরীক্ষা করার জন্য সবচেয়ে ভালো। এই ডিরেক্টরিতে একটি `sample-document.txt` দেওয়া আছে যেটিতে LangChain4j বৈশিষ্ট্য, RAG বাস্তবায়ন এবং শ্রেষ্ঠ অনুশীলন সম্পর্কিত তথ্য রয়েছে - সিস্টেম পরীক্ষা করার জন্য উপযুক্ত। -সিস্টেম আপনার ডকুমেন্ট প্রক্রিয়াকরণ করে, সেটিকে অংশে ভাগ করে এবং প্রতিটি অংশের জন্য এম্বেডিং তৈরি করে। এটি স্বয়ংক্রিয়ভাবে আপলোডের সময় ঘটে। +সিস্টেম আপনার ডকুমেন্ট প্রক্রিয়াকরণ করে, তা ভাগ করে এবং প্রতি অংশের জন্য এমবেডিং তৈরি করে। এটি স্বয়ংক্রিয়ভাবে ঘটে যখন আপনি আপলোড করেন। ### প্রশ্ন করুন -এখন ডকুমেন্টের বিষয়বস্তু সম্পর্কে নির্দিষ্ট প্রশ্ন করুন। এমন কিছু চেষ্টা করুন যা ডকুমেন্টে স্পষ্টভাবে উল্লেখ আছে। সিস্টেম প্রাসঙ্গিক অংশগুলি খুঁজে বের করে, সেগুলো প্রম্পটে অন্তর্ভুক্ত করে এবং উত্তর তৈরি করে। +এখন ডকুমেন্টের বিষয়বস্তু সম্পর্কে নির্দিষ্ট প্রশ্ন করুন। এমন কিছু প্রশ্ন করুন যা স্পষ্টভাবে ডকুমেন্টে উল্লেখিত আছে। সিস্টেম প্রাসঙ্গিক অংশ অনুসন্ধান করে, সেগুলোকে প্রম্পটে অন্তর্ভুক্ত করে এবং উত্তর তৈরি করে। -### উৎস রেফারেন্স চেক করুন +### উত্স রেফারেন্স যাচাই করুন -প্রতিটি উত্তরের সাথে উৎস রেফারেন্স ও সাদৃশ্য স্কোর দেখানো হয়। এই স্কোরগুলো (০ থেকে ১) দেখায় প্রতিটি অংশ কতটা আপনার প্রশ্নের সাথে প্রাসঙ্গিক ছিল। বেশি স্কোর মানে ভাল মিল। এটি আপনাকে উৎস উপাদানের সাথে উত্তর যাচাই করতে সাহায্য করে। +প্রতিটি উত্তরে উত্স রেফারেন্স এবং সাদৃশ্য স্কোর অন্তর্ভুক্ত থাকে লক্ষ্য করুন। এই স্কোর (০ থেকে ১) দেখায় আপনার প্রশ্নের সাথে প্রতিটি অংশ কতটা প্রাসঙ্গিক ছিল। উচ্চ স্কোর মানে ভালো মিল। এটি আপনাকে উত্তরের সাথে উৎস উপাদানের মিল যাচাই করতে সাহায্য করে। RAG Query Results -*এই স্ক্রিনশটে প্রশ্নের ফলাফল, তৈরি উত্তর, উৎস রেফারেন্স, এবং প্রতিটি প্রাপ্ত অংশের প্রাসঙ্গিকতা স্কোর দেখানো হয়েছে।* +*এই স্ক্রিনশটে প্রশ্ন ফলাফল দেখানো হয়েছে যেখানে উৎপন্ন উত্তর, উত্স রেফারেন্স এবং প্রাসঙ্গিকতার স্কোরগুলি প্রতিটি উদ্ধার করা অংশের জন্য প্রদর্শিত হয়েছে।* -### প্রশ্নের সাথে পরীক্ষা-নিরীক্ষা করুন +### প্রশ্ন নিয়ে পরীক্ষা করুন বিভিন্ন ধরনের প্রশ্ন চেষ্টা করুন: -- নির্দিষ্ট তথ্য: "মূল বিষয় কী?" +- নির্দিষ্ট তথ্য: "প্রধান বিষয় কী?" - তুলনা: "X এবং Y এর মধ্যে পার্থক্য কী?" -- সারাংশ: "Z সম্পর্কে মূল পয়েন্টগুলো সারসংক্ষেপ করুন" +- সারাংশ: "Z সম্পর্কিত মূল পয়েন্টগুলো সারাংশ করুন" -দেখুন কীভাবে আপনার প্রশ্নের মিল ডকুমেন্টের বিষয়বস্তুর উপর ভিত্তি করে প্রাসঙ্গিকতার স্কোর পরিবর্তন হয়। +দেখুন কীভাবে প্রাসঙ্গিকতার স্কোর পরিবর্তিত হয় আপনার প্রশ্ন ডকুমেন্ট বিষয়বস্তুর সাথে কতটা মেলে তার উপর ভিত্তি করে। -## মূল ধারনা +## মূল ধারণাসমূহ -### অংশে ভাগ করার কৌশল +### অংশকরণ কৌশল -ডকুমেন্টগুলো ৩০ টোকেন ওভারল্যাপ সহ ৩০০ টোকেনের অংশে ভাগ করা হয়। এই ভারসাম্য নিশ্চিত করে প্রতিটি অংশ যথেষ্ট প্রসঙ্গ সহ অর্থবহ থাকে এবং পর্যাপ্ত ছোট থাকে যাতে একাধিক অংশ প্রম্পটে দেওয়া যায়। +ডকুমেন্টগুলো ৩০০ টোকেন আকারের অংশে ভাগ করা হয় যেখানে ৩০ টোকেন ওভারল্যাপে থাকে। এই ভারসাম্য নিশ্চিত করে প্রতিটি অংশে যথেষ্ট প্রসঙ্গ থাকে তা অর্থপূর্ণ করার জন্য পাশাপাশি অংশগুলো ছোট থাকার কারণে একাধিক অংশ প্রম্পটে অন্তর্ভুক্ত করা যায়। ### সাদৃশ্য স্কোর -প্রত্যেক প্রাপ্ত অংশের সাথে একটি সাদৃশ্য স্কোর থাকে ০ থেকে ১ এর মধ্যে, যা নির্দেশ করে অংশটি ব্যবহারকারীর প্রশ্নের সাথে কতটা মিলেছে। নিচের চিত্রে স্কোর পরিসর এবং সিস্টেম কীভাবে সেগুলো ব্যবহার করে ফলাফল ফিল্টার করে দেখানো হয়েছে: +প্রত্যেক উদ্ধারকৃত অংশের সাথে একটি সাদৃশ্য স্কোর থাকে ০ থেকে ১ এর মধ্যে যা নির্দেশ করে এটি ব্যবহারকারীর প্রশ্নের সাথে কতটা মিল রয়েছে। নিচের চিত্রটি এই স্কোরের পরিসর এবং সিস্টেম কীভাবে তা ব্যবহার করে ফলাফল ছাঁকছে তা দেখায়: Similarity Scores -*এই চিত্রটি ০ থেকে ১ এর স্কোর পরিসর দেখায়, যেখানে ০.৫ একটি ন্যূনতম সীমা যা অপ্রাসঙ্গিক অংশগুলো ফিল্টার করে।* +*এই চিত্রটি ০ থেকে ১ পর্যন্ত স্কোর পরিসর দেখায়, যার ন্যূনতম সীমা ০.৫ যা প্রাসঙ্গিক নয় এমন অংশগুলি ফিল্টার করে।* -স্কোর পরিসর: -- ০.৭-১.০: অত্যন্ত প্রাসঙ্গিক, সঠিক মিল +স্কোরের পরিসর: +- ০.৭-১.০: অত্যন্ত প্রাসঙ্গিক, নির্দিষ্ট মিল - ০.৫-০.৭: প্রাসঙ্গিক, ভালো প্রসঙ্গ -- ০.৫ এর নিচে: ফিল্টার করা হয়েছে, খুব অপ্রাসঙ্গিক +- ০.৫ এর নিচে: ফিল্টার করা হয়েছে, খুব আলাদা -গুণগত মান নিশ্চিত করতে সিস্টেম শুধুমাত্র ন্যূনতম সীমা ছাপিয়ে অংশগুলোই পুনরুদ্ধার করে। +গুণগতমান নিশ্চিত করার জন্য সিস্টেম ন্যূনতম সীমার নিচের অংশগুলি উদ্ধার করে না। -এম্বেডিংস ভাল কাজ করে যখন অর্থ স্পষ্টভাবে ক্লাস্টার হয়, কিন্তু কিছু দুর্বলতা থাকে। নিচের চিত্রটি সাধারণ ব্যর্থতার কারণগুলো দেখায় — খুব বড় অংশগুলো মটমটানো ভেক্টর তৈরি করে, খুব ছোট অংশগুলোতে প্রসঙ্গ নেই, অস্পষ্ট শব্দগুলো একাধিক ক্লাস্টার নির্দেশ করে, এবং সঠিক-মিল লুকআপ (আইডি, পার্ট নম্বর) এম্বেডিংসের সাথে কাজ করে না: +এম্বেডিং গুলো অর্থ স্পষ্টভাবে গুচ্ছভুক্ত হলে ভাল কাজ করে, তবে এর কিছু সীমাবদ্ধতা আছে। নিচের চিত্রটি প্রচলিত ব্যর্থতার ধরণ দেখায় — অনেক বড় অংশ অস্পষ্ট ভেক্টর তৈরি করে, ছোট অংশে প্রসঙ্গ কম থাকে, অসম্পূর্ণ শব্দ একাধিক গুচ্ছের দিকে নির্দেশ করে, এবং সঠিক ম্যাচ লুকআপ (আইডি, পার্ট নং) এমবেডিং এর সাথে কাজ করে না: Embedding Failure Modes -*এই চিত্রটি সাধারণ এম্বেডিং ব্যর্থতার কারণগুলো দেখায়: খুব বড় অংশ, খুব ছোট অংশ, অস্পষ্ট শব্দ যা একাধিক ক্লাস্টার নির্দেশ করে, এবং সঠিক-মিল লুকআপ যেমন আইডি।* +*এই চিত্রটি প্রচলিত এমবেডিং ব্যর্থতার ধরন দেখায়: খুব বড় অংশ, খুব ছোট অংশ, অস্পষ্ট শব্দ যা একাধিক গুচ্ছের দিকে নির্দেশ করে, এবং সঠিক ম্যাচ লুকআপ (আইডি ইত্যাদি)।* -### ইন-মেমোরি স্টোরেজ +### ইন-মেমরি স্টোরেজ -এই মডিউলটি সরলতার জন্য ইন-মেমোরি স্টোরেজ ব্যবহার করে। যখন আপনি অ্যাপ্লিকেশন পুনরায় চালু করবেন, তখন আপলোড করা ডকুমেন্টগুলো হারিয়ে যাবে। প্রোডাকশন সিস্টেম স্থায়ী ভেক্টর ডাটাবেস যেমন Qdrant বা Azure AI Search ব্যবহার করে। +সহজতার জন্য এই মডিউল ইন-মেমরি স্টোরেজ ব্যবহার করে। অ্যাপ্লিকেশন পুনরায় চালু করলে আপলোড করা ডকুমেন্ট হারানো যায়। উৎপাদন সিস্টেমে Qdrant বা Azure AI Search এর মত স্থায়ী ভেক্টর ডাটাবেস ব্যবহৃত হয়। ### প্রসঙ্গ উইন্ডো ব্যবস্থাপনা -প্রত্যেক মডেলের একটি সর্বোচ্চ প্রসঙ্গ উইন্ডো থাকে। বড় ডকুমেন্টের সব অংশ প্রম্পটে অন্তর্ভুক্ত করা সম্ভব নয়। সিস্টেম সর্বোচ্চ N টি প্রাসঙ্গিক অংশ (ডিফল্ট ৫) পুনরুদ্ধার করে যাতে সীমাবদ্ধতা বজায় থাকে এবং যথাযথ প্রসঙ্গ দিয়ে সঠিক উত্তর দেওয়া যায়। +প্রতিটি মডেলের একটি সর্বোচ্চ প্রসঙ্গ উইন্ডো থাকে। বড় ডকুমেন্ট থেকে প্রতিটি অংশ অন্তর্ভুক্ত করা সম্ভব নয়। সিস্টেম সর্বোচ্চ N প্রাসঙ্গিক অংশ (ডিফল্ট ৫) উদ্ধার করে যাতে সীমার মধ্যে থেকে যথেষ্ট প্রসঙ্গ দিয়ে সঠিক উত্তর দেয়া যায়। -## যখন RAG গুরুত্বপূর্ণ +## কখন RAG গুরুত্বপূর্ণ -RAG সবসময় সঠিক পন্থা নয়। নিচের সিদ্ধান্ত গাইডটি আপনাকে সাহায্য করবে বুঝতে কখন RAG মূল্য সংযোজন করে এবং কখন সরল পন্থা — যেমন সরাসরি প্রম্পটে বিষয়বস্তু অন্তর্ভুক্ত করা বা মডেলের অভ্যন্তরীণ জ্ঞানের উপর নির্ভর করা — যথেষ্ট: +RAG সবসময় সঠিক পন্থা নয়। নিচের সিদ্ধান্ত নির্দেশিকা আপনাকে সাহায্য করবে জানার জন্য কখন RAG মূল্যায়ন যোগ করে এবং কখন সরল পদ্ধতি — যেমন সরাসরি প্রম্পটে বিষয় বস্তু অন্তর্ভুক্ত করা বা মডেলের নিজস্ব জ্ঞান নির্ভর করা — যথেষ্ট: When to Use RAG -*এই চিত্রটি সিদ্ধান্ত গাইড দেখায় যাতে বোঝা যায় কখন RAG মূল্য সংযোজন করে এবং কখন সরল পন্থাগুলো যথেষ্ট।* +*এই চিত্রটি একটি সিদ্ধান্ত নির্দেশিকা দেখায় যে কখন RAG মূল্যায়ন যোগ করে এবং কখন সরল পদ্ধতি যথেষ্ট।* ## পরবর্তী ধাপ @@ -434,6 +431,6 @@ RAG সবসময় সঠিক পন্থা নয়। নিচের --- -**দ্রষ্টব্য**: -এই নথিটি AI অনুবাদ সেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। আমরা যথাসাধ্য সঠিকতার চেষ্টা করি, তবে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অনিশ্চয়তা থাকতে পারে দয়া করে খেয়াল রাখুন। মূল নথিটি তার মূল ভাষায়ই কর্তৃত্বপূর্ণ উৎস হিসাবে বিবেচনা করা উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদের পরামর্শ দেওয়া হয়। এই অনুবাদের ব্যবহারে সৃষ্ট কোন ভুল-বুঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়ী নই। +**অস্বীকৃতি**: +এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা শুদ্ধতার জন্য চেষ্টা করি, অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার স্বভাষায় কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে প্রয়োজনীয় ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই। \ No newline at end of file diff --git a/translations/bn/04-tools/README.md b/translations/bn/04-tools/README.md index 2527e7756..dbcdc40f8 100644 --- a/translations/bn/04-tools/README.md +++ b/translations/bn/04-tools/README.md @@ -1,84 +1,84 @@ -# মডিউল ০৪: টুলস সহ AI এজেন্টস +# মডিউল ০৪: টুলসসহ AI এজেন্টস ## বিষয়বস্তু তালিকা -- [ভিডিও ওয়াকথ্রু](../../../04-tools) -- [আপনি যা শিখবেন](../../../04-tools) -- [প্রয়োজনীয়তা](../../../04-tools) -- [টুলস সহ AI এজেন্টস বোঝা](../../../04-tools) -- [কিভাবে টুল কল হয়](../../../04-tools) - - [টুল সংজ্ঞাগুলি](../../../04-tools) - - [সিদ্ধান্ত গ্রহণ](../../../04-tools) - - [নির্বাহ](../../../04-tools) - - [প্রতিক্রিয়া তৈরি](../../../04-tools) - - [স্থাপত্য: স্প্রিং বুট অটো-ওয়্যারিং](../../../04-tools) -- [টুল চেইনিং](../../../04-tools) -- [অ্যাপ্লিকেশন চালান](../../../04-tools) -- [অ্যাপ্লিকেশন ব্যবহার](../../../04-tools) - - [সরল টুল ব্যবহার চেষ্টা করুন](../../../04-tools) - - [টুল চেইনিং পরীক্ষা করুন](../../../04-tools) - - [আলাপচারিতা প্রবাহ দেখুন](../../../04-tools) - - [বিভিন্ন অনুরোধ নিয়ে পরীক্ষা করুন](../../../04-tools) -- [মূল ধারণা](../../../04-tools) - - [রি-অ্যাক্ট প্যাটার্ন (যুক্তি ও কার্য)](../../../04-tools) - - [টুল বর্ণনা গুরুত্বপূর্ণ](../../../04-tools) - - [সেশন ম্যানেজমেন্ট](../../../04-tools) - - [ত্রুটি পরিচালনা](../../../04-tools) -- [উপলভ্য টুলস](../../../04-tools) -- [টুল-ভিত্তিক এজেন্ট কখন ব্যবহার করবেন](../../../04-tools) -- [টুলস বনাম RAG](../../../04-tools) -- [পরবর্তী ধাপ](../../../04-tools) +- [ভিডিও ওয়াকথ্রু](#ভিডিও-ওয়াকথ্রু) +- [আপনি কি শিখবেন](#আপনি-কি-শিখবেন) +- [প্রাক-শর্ত](#প্রাক-শর্ত) +- [টুলসসহ AI এজেন্টস বোঝা](#টুলসসহ-ai-এজেন্টস-বোঝা) +- [কিভাবে টুল কলিং কাজ করে](#কিভাবে-টুল-কলিং-কাজ-করে) + - [টুল সংজ্ঞা](#টুল-সংজ্ঞা) + - [সিদ্ধান্ত গ্রহণ](#সিদ্ধান্ত-গ্রহণ) + - [কার্যকরী اجرا](#কার্যকরী-اجرا) + - [প্রতিক্রিয়া প্রস্তুতি](#প্রতিক্রিয়া-প্রস্তুতি) + - [স্থাপত্য: স্প্রিং বুট অটো-ওয়্যারিং](#স্থাপত্য-স্প্রিং-বুট-অটো-ওয়্যারিং) +- [টুল চেইনিং](#টুল-চেইনিং) +- [অ্যাপ্লিকেশন চালান](#অ্যাপ্লিকেশন-চালান) +- [অ্যাপ্লিকেশন ব্যবহার](#অ্যাপ্লিকেশন-ব্যবহার) + - [সহজ টুল ব্যবহার চেষ্টা করুন](#সহজ-টুল-ব্যবহার-চেষ্টা-করুন) + - [টুল চেইনিং পরীক্ষা করুন](#টুল-চেইনিং-পরীক্ষা-করুন) + - [আলোচনা প্রবাহ দেখুন](#কথোপকথনের-প্রবাহ-দেখুন) + - [বিভিন্ন অনুরোধ নিয়ে পরীক্ষা করুন](#বিভিন্ন-অনুরোধ-নিয়ে-পরীক্ষা-করুন) +- [মূল ধারণা](#মূল-ধারণাসমূহ) + - [ReAct প্যাটার্ন (যুক্তিবিদ্যা ও কার্যক্রম)](#react-প্যাটার্ন-যুক্তি-ও-কর্ম) + - [টুল বর্ণনা গুরুত্বপূর্ণ](#টুল-বর্ণনা-গুরুত্বপূর্ণ) + - [সেশন ব্যবস্থাপনা](#সেশন-ম্যানেজমেন্ট) + - [ত্রুটি পরিচালনা](#ত্রুটি-হ্যান্ডলিং) +- [উপলব্ধ টুলস](#উপলব্ধ-টুলস) +- [কখন টুল-ভিত্তিক এজেন্ট ব্যবহার করবেন](#কখন-টুল-ভিত্তিক-এজেন্ট-ব্যবহার-করবেন) +- [টুলস বনাম RAG](#টুলস-বনাম-rag) +- [পরবর্তী ধাপ](#পরবর্তী-ধাপ) ## ভিডিও ওয়াকথ্রু -এই লাইভ সেশনটি দেখুন যা ব্যাখ্যা করে কিভাবে এই মডিউল থেকে শুরু করবেন: +এই লাইভ সেশনটি দেখুন যা এই মডিউল শুরু করার পদ্ধতি ব্যাখ্যা করে: -টুলস সহ AI এজেন্টস এবং MCP - লাইভ সেশন +AI Agents with Tools and MCP - Live Session -## আপনি যা শিখবেন +## আপনি কি শিখবেন -এখন পর্যন্ত, আপনি শিখেছেন কিভাবে AI এর সাথে আলাপচারিতা করবেন, কার্যকরী প্রম্পট গঠন করবেন এবং আপনার ডকুমেন্টে ভিত্তি করে উত্তর দেবেন। কিন্তু একটি মৌলিক সীমাবদ্ধতা আছে: ভাষা মডেল শুধু টেক্সট তৈরি করতে পারে। এটি আবহাওয়া পরীক্ষা করতে পারেনা, হিসাব করতে পারেনা, ডাটাবেস অনুসন্ধান করতে পারেনা, অথবা বাইরের সিস্টেমের সাথে ইন্টারঅ্যাক্ট করতে পারেনা। +এখন পর্যন্ত, আপনি শিখেছেন কিভাবে AI-এর সাথে কথোপকথন করবেন, প্রম্পটগুলো কার্যকরভাবে গঠন করবেন, এবং আপনার ডকুমেন্টে প্রতিক্রিয়া ভিত্তি করবেন। কিন্তু এখনো একটি মৌলিক সীমাবদ্ধতা রয়ে গেছে: ভাষার মডেল শুধুমাত্র টেক্সট তৈরি করতে পারে। এটি আবহাওয়া চেক করতে, গণনা করতে, ডেটাবেজ প্রশ্ন করতে বা বাইরের সিস্টেমের সাথে ইন্টারঅ্যাক্ট করতে পারবে না। -টুলস এই সীমাবদ্ধতাকে বদলে দেয়। মডেলকে যে ফাংশনগুলো কল করতে পারে তা দিয়ে, আপনি এটিকে একটি টেক্সট জেনারেটর থেকে এমন একটি এজেন্টে রূপান্তর করেন যা কাজ করতে সক্ষম। মডেল সিদ্ধান্ত নেয় কখন টুল প্রয়োজন, কোন টুল ব্যবহার করতে হবে, এবং কী পরামিতি পাঠাতে হবে। আপনার কোড ফাংশনটি সম্পাদন করে ফলাফল ফেরত দেয়। মডেল সে ফলাফলকে তার উত্তরে অন্তর্ভুক্ত করে। +টুলস এটা পরিবর্তন করে। মডেলকে কল করতে পারার জন্য ফাংশনের প্রবেশাধিকার দিয়ে, আপনি এটিকে টেক্সট জেনারেটর থেকে এমন একটি এজেন্টে পরিণত করেন যা পদক্ষেপ নিতে পারে। মডেল সিদ্ধান্ত নেয় কখন একটি টুল দরকার, কোন টুল ব্যবহার করবে এবং কি প্যারামিটার পাঠাবে। আপনার কোড ফাংশনটি চালায় এবং ফলাফল ফেরত দেয়। মডেল ঐ ফলাফলকে তার প্রতিক্রিয়ায় অন্তর্ভুক্ত করে। -## প্রয়োজনীয়তা +## প্রাক-শর্ত -- সম্পন্ন [মডিউল ০১ – পরিচিতি](../01-introduction/README.md) (Azure OpenAI রিসোর্স ডিপ্লয় করা হয়েছে) -- পূর্ববর্তী মডিউলগুলি সম্পন্ন করা সুপারিশকৃত (এই মডিউল [মডিউল ০৩ এর RAG ধারণা](../03-rag/README.md) উল্লেখ করে Tools vs RAG তুলনায়) -- রুট ডিরেক্টরিতে `.env` ফাইল সহ Azure ক্রেডেনশিয়ালস (মডিউল ০১ এ `azd up` দ্বারা তৈরি) +- সম্পন্ন [মডিউল ০১ - পরিচিতি](../01-introduction/README.md) (Azure OpenAI রিসোর্স ডিপ্লয় করা হয়েছে) +- পূর্ববর্তী মডিউলগুলি সম্পন্ন করা সুপারিশ করা হয়েছে (এই মডিউল [মডিউল ০৩ এর RAG ধারণা](../03-rag/README.md) উল্লেখ করে টুলস বনাম RAG তুলনায়) +- `.env` ফাইল মূল ডিরেক্টরিতে Azure প্রমাণপত্রাদি সহ (মডিউল ০১-এ `azd up` দ্বারা তৈরি) -> **নোট:** যদি আপনি মডিউল ০১ সম্পন্ন না করে থাকেন, প্রথমে সেখানে ডিপ্লয়মেন্ট নির্দেশনা অনুসরণ করুন। +> **বিঃদ্রঃ:** যদি আপনি মডিউল ০১ সম্পন্ন না করে থাকেন, আগে সেখানে ডিপ্লয়মেন্ট নির্দেশনাগুলো অনুসরণ করুন। -## টুলস সহ AI এজেন্টস বোঝা +## টুলসসহ AI এজেন্টস বোঝা -> **📝 নোট:** এই মডিউলে “এজেন্টস” শব্দটি টুল-কলিং ক্ষমতাসম্পন্ন AI সহকারী বোঝায়। এটি আলাদা **Agentic AI** প্যাটার্ন থেকে (স্বায়ত্তশাসিত এজেন্ট যাদের প্ল্যানিং, মেমোরি এবং বহু-ধাপ যুক্তি আছে) যা আমরা [মডিউল ০৫: MCP](../05-mcp/README.md) এ আলোচনা করব। +> **📝 নোট:** এই মডিউলে "এজেন্টস" শব্দটি টুল কলিং সক্ষমতা সহ উন্নত AI সহকারী বোঝায়। এটি ভিন্ন একটি বিষয় হলো **Agentic AI** প্যাটার্নস (স্বয়ংক্রিয় এজেন্টস যাদের পরিকল্পনা, স্মৃতি, ও বহু-পর্ব যুক্তি থাকে) যা আমরা [মডিউল ০৫: MCP](../05-mcp/README.md)-এ আলোচনা করব। -টুল ছাড়া, একটি ভাষা মডেল তার প্রশিক্ষণ ডেটা থেকে কেবলমাত্র টেক্সট তৈরি করতে পারে। এটি বর্তমান আবহাওয়া জানতে চাইলে, এটি অনুমান করবে। টুল দিলে, এটি আবহাওয়ার API কল করতে পারে, হিসাব করতে পারে, অথবা ডাটাবেস অনুসন্ধান করতে পারে — তারপর ওই বাস্তব ফলাফল উত্তরে বুনতে পারে। +টুল ছাড়া, একটি ভাষার মডেল কেবল তার প্রশিক্ষণ ডেটা থেকে টেক্সট তৈরি করতে পারে। বর্তমান আবহাওয়া জানতে চাইলে, এটি অনুমান করতে হবে। টুল দিলে, এটি একটি আবহাওয়া API কল করতে পারে, গণনা করতে পারে বা ডেটাবেজ প্রশ্ন করতে পারে — তারপর ঐ বাস্তব ফলাফলগুলোকে তার প্রতিক্রিয়ায় নিয়ে আসতে পারে। -টুল ছাড়া বনাম টুল সহ +Without Tools vs With Tools -*টুল ছাড়া মডেল কেবল অনুমান করে — টুলসহ এটি API কল করে, হিসাব চালায় এবং রিয়েল-টাইম তথ্য প্রদান করে।* +*বিনা টুলে মডেল অনুমান করে — টুলসহ এটি API কল করতে পারে, গণনা চালাতে পারে, এবং রিয়েল-টাইম ডেটা ফেরত দিতে পারে।* -টুলস সহ একটি AI এজেন্ট একটি **রি-অ্যাক্ট (যুক্তি ও কার্য)** প্যাটার্ন অনুসরণ করে। মডেল শুধু উত্তর দেয় না — এটি চিন্তা করে কি দরকার, টুল কল করে কাজ করে, ফলাফল পর্যবেক্ষণ করে, এবং সিদ্ধান্ত নেয় আবার কাজ করবে কি না অথবা চূড়ান্ত উত্তর দেবে: +একটি টুলসহ AI এজেন্ট অনুসরণ করে **যুক্তিবিদ্যা ও কার্যক্রম (ReAct)** প্যাটার্ন। মডেল শুধু সাড়া দেয় না — এটি চিন্তা করে কি দরকার, টুল কল করে কাজ করে, ফলাফল দেখে, এবং সিদ্ধান্ত নেয় আবার কাজ করবে কিনা বা চূড়ান্ত উত্তর দেবে: -১. **যুক্তি** — এজেন্ট ব্যবহারকারীর প্রশ্ন বিশ্লেষণ করে এবং দরকারি তথ্য নির্ধারণ করে -২. **কার্য** — সঠিক টুল নির্বাচন করে, সঠিক পরামিতি তৈরি করে এবং কল করে -৩. **পর্যবেক্ষণ** — টুলের আউটপুট গ্রহণ করে এবং ফলাফল মূল্যায়ন করে -৪. **পুনরাবৃত্তি বা প্রতিক্রিয়া** — অতিরিক্ত তথ্য প্রয়োজনে লুপ করে; না হলে ভাষাগত উত্তর তৈরি করে +১. **যুক্তি করো** — এজেন্ট ব্যবহারকারীর প্রশ্ন বিশ্লেষণ করে কি তথ্য দরকার দিচ্ছে নির্ধারণ করে +২. **কার্যকরী হও** — এজেন্ট সঠিক টুল নির্বাচন করে, সঠিক প্যারামিটার জেনারেট করে, এবং কল করে +৩. **পর্যবেক্ষণ করো** — এজেন্ট টুলের আউটপুট পায় এবং ফলাফল মূল্যায়ন করে +৪. **পুনরাবৃত্তি বা প্রতিক্রিয়া প্রদান করো** — যদি বেশি তথ্য দরকার, এজেন্ট পুনরায় লুপ করে; নয়তো প্রাকৃতিক ভাষায় উত্তর রচনা করে -রি-অ্যাক্ট প্যাটার্ন +ReAct Pattern -*রি-অ্যাক্ট চক্র — এজেন্ট কী করতে হবে ভাববে, টুল কল করে কাজ করবে, ফলাফল দেখবে এবং যতক্ষণ দরকার লুপ করবে, তারপর চূড়ান্ত উত্তর দেবে।* +*ReAct চক্র — এজেন্ট কি করব তা ভাবছে, টুল কল করে কাজ করছে, ফলাফল পর্যবেক্ষণ করছে, এবং লুপ করে যতক্ষণ না চূড়ান্ত উত্তর দিতে পারে।* -এটি স্বয়ংক্রিয়ভাবে ঘটে। আপনি টুলসমূহ এবং তাদের বর্ণনা নির্ধারণ করেন। মডেল সিদ্ধান্ত নেয় কখন ও কিভাবে এগুলো ব্যবহার করতে হবে। +এটি স্বয়ংক্রিয়ভাবে ঘটে। আপনি টুলগুলি ও তাদের বর্ণনা নির্ধারণ করেন। মডেল সিদ্ধান্ত নেয় কখন এবং কিভাবে সেগুলো ব্যবহার করবে। -## কিভাবে টুল কল হয় +## কিভাবে টুল কলিং কাজ করে -### টুল সংজ্ঞাগুলি +### টুল সংজ্ঞা [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -আপনি পরিষ্কার বর্ণনা ও প্যারামিটার স্পেসিফিকেশন সহ ফাংশনগুলো সংজ্ঞায়িত করেন। মডেল সিস্টেম প্রম্পটে এই বর্ণনাগুলো দেখে এবং বোঝে প্রতিটি টুল কি করে। +আপনি ফাংশনগুলো স্পষ্ট বর্ণনা এবং প্যারামিটার স্পেসিফিকেশনের সাথে সংজ্ঞায়িত করেন। মডেল এই বর্ণনাগুলো তার সিস্টেম প্রম্পটে দেখে এবং বুঝতে পারে প্রতিটি টুল কি করে। ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // আপনার আবহাওয়া অনুসন্ধান লজিক + // আপনার আবহাওয়ার অনুসন্ধান লজিক return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,139 +96,139 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// সহকারী স্বয়ংক্রিয়ভাবে স্প্রিং বুট দ্বারা সংযুক্ত: -// - ChatModel বিন -// - @Component ক্লাস থেকে সব @Tool পদ্ধতি -// - সেশন ব্যবস্থাপনার জন্য ChatMemoryProvider +// Spring Boot স্বয়ংক্রিয়ভাবে সহকারীকে যুক্ত করে নিচের সাথে: +// - ChatModel বীন +// - @Component ক্লাস থেকে সকল @Tool পদ্ধতি +// - সেশন পরিচালনার জন্য ChatMemoryProvider ``` -নিম্নলিখিত আর্কচিত্র প্রতিটি অ্যানোটেশন বিশ্লেষণ করে এবং দেখায় কিভাবে প্রতিটি অংশ AI কে টুল কল করার সময় এবং কোন আর্গুমেন্ট পাঠাতে হবে বুঝতে সাহায্য করে: +নীচের ডায়াগ্রাম প্রতিটি অ্যানোটেশন ভাঙ্গে এবং দেখায় কিভাবে প্রতিটা অংশ AI-কে সাহায্য করে কখন টুল কল করতে হবে এবং কি আর্গুমেন্ট পাঠাতে হবে: -টুল সংজ্ঞার গঠন +Anatomy of Tool Definitions -*টুল সংজ্ঞার গঠন — @Tool AI কে বলে কখন এটি ব্যবহার করতে হবে, @P প্রতিটি প্যারামিটার বর্ণনা করে, এবং @AiService স্টার্টআপে সবকিছুকে সংযোগ করে।* +*একটি টুল সংজ্ঞার কাঠামো — @Tool AI-কে বলে কখন এটি ব্যবহার করতে, @P প্রতিটি প্যারামিটার বর্ণনা করে, এবং @AiService স্টার্টআপে সবকিছু সংযুক্ত করে।* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat দিয়ে চেষ্টা করুন:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) খুলুন এবং জিজ্ঞাসা করুন: -> - "কিভাবে আমি আসল আবহাওয়ার API যেমন OpenWeatherMap ইন্টিগ্রেট করব mock ডাটা এর পরিবর্তে?" -> - "কীসেখানে একটি ভাল টুল বর্ণনা যা AI কে সঠিকভাবে ব্যবহার করতে সাহায্য করে?" -> - "কিভাবে API এর ত্রুটি ও রেট লিমিট মোকাবিলা করব টুল ইমপ্লিমেন্টেশনে?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) চ্যাট দিয়ে চেষ্টা করুন:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) খুলুন এবং জিজ্ঞাসা করুন: +> - "কিভাবে বাস্তব আবহাওয়া API যেমন OpenWeatherMap ইন্টিগ্রেট করব মক ডেটার পরিবর্তে?" +> - "কী ভালো টুল বর্ণনা তৈরি করে যা AI-কে সঠিক ব্যবহার করতে সাহায্য করে?" +> - "API এরর এবং রেট লিমিট কিভাবে হ্যান্ডেল করব টুল ইমপ্লিমেন্টেশনে?" ### সিদ্ধান্ত গ্রহণ -যখন কেউ জিজ্ঞাসা করে "সিয়াটলে আবহাওয়া কেমন?", মডেল এলোমেলোভাবে টুল পালন করে না। এটি ব্যবহারকারীর উদ্দেশ্যের সাথে প্রতিটি টুল বর্ণনা মিলিয়ে দেখে, প্রাসঙ্গিকতার স্কোর দেয়, এবং শ্রেষ্ঠ ম্যাচ নির্বাচন করে। এরপর সঠিক প্যারামিটার সহ একটি গঠনমূলক ফাংশন কল তৈরি করে — এই ক্ষেত্রে `location` সেট করে `"Seattle"`। +যখন ব্যবহারকারী জিজ্ঞাসা করে "সিয়াটেলের আবহাওয়া কেমন?", মডেল যেকোনো টুল এলোমেলোভাবে বেছে নেয় না। এটি ব্যবহারকারীর উদ্দেশ্য প্রতিটি টুলের বর্ণনার সাথে তুলনা করে, প্রাসঙ্গিকতার জন্য স্কোর করে, এবং সেরা মিল নির্বাচন করে। পরে সঠিক প্যারামিটার সহ একটি কাঠামোবদ্ধ ফাংশন কল তৈরি করে — এখানে, `location` কে `"Seattle"` সেট করে। -যদি কোনো টুল ব্যবহারকারীর অনুরোধের সাথে মেলে না, মডেল তার নিজস্ব জ্ঞান থেকে উত্তর দেয়। যদি একাধিক টুল মেলে, তবে সবচেয়ে নির্দিষ্টটি পছন্দ করে। +যদি কোনো টুল ব্যবহারকারীর অনুরোধ মেলাতে না পারে, মডেল তার নিজের জ্ঞান থেকে উত্তর দেয়। যদি একাধিক টুল মেলে তবে সবচেয়ে নির্দিষ্টটি বেছে নেয়। -কিভাবে AI সিদ্ধান্ত নেয় কোন টুল ব্যবহার করবে +How the AI Decides Which Tool to Use -*মডেল ব্যবহারকারীর উদ্দেশ্যের সাথে উপলব্ধ প্রতিটি টুল মূল্যায়ন করে এবং শ্রেষ্ঠটি নির্বাচন করে — এজন্য পরিষ্কার, নির্দিষ্ট টুল বর্ণনা লেখা গুরুত্বপূর্ণ।* +*মডেল ব্যবহারকারীর উদ্দেশ্যের বিরুদ্ধে প্রতিটি টুল মূল্যায়ন করে এবং সেরা মিল নির্বাচন করে — এ জন্য স্পষ্ট, নির্দিষ্ট টুল বর্ণনা লেখা গুরুত্বপূর্ণ।* -### নির্বাহ +### কার্যকরী اجرا [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -স্প্রিং বুট সমস্ত নিবন্ধিত টুলস সহ `@AiService` ইন্টারফেস অটো-ওয়্যার করে এবং LangChain4j স্বয়ংক্রিয়ভাবে টুল কল চালায়। দৃশ্যের পেছনে, সম্পূর্ণ টুল কল ছয় পর্যায়ে প্রবাহিত হয় — ব্যবহারকারীর ভাষাগত প্রশ্ন থেকে শুরু করে ভাষাগত উত্তরে ফেরত যাওয়া পর্যন্ত: +স্প্রিং বুট ডিক্লারেটিভ `@AiService` ইন্টারফেসটির সাথে সমস্ত নিবন্ধিত টুলস অটো-ওয়্যার করে, এবং LangChain4j স্বয়ংক্রিয়ভাবে টুল কল চালায়। পিছনের দৃশ্যে, একটি পূর্ণাঙ্গ টুল কল ছয় ধাপে প্রবাহিত হয় — ব্যবহারকারীর প্রাকৃতিক ভাষার প্রশ্ন থেকে শুরু করে পুনরায় প্রাকৃতিক ভাষার উত্তর পর্যন্ত: -টুল কল ফ্লো +Tool Calling Flow -*পূর্ণ-চক্র প্রবাহ — ব্যবহারকারী প্রশ্ন করে, মডেল একটি টুল নির্বাচন করে, LangChain4j এটি কার্যকর করে, এবং মডেল ফলাফল স্বাভাবিক ভাষায় বুনে দেয়।* +*শেষ থেকে শেষ পর্যন্ত প্রবাহ — ব্যবহারকারী প্রশ্ন করে, মডেল একটি টুল বেছে নেয়, LangChain4j সেটি চালায়, এবং মডেল ফলাফলকে একটি প্রাকৃতিক প্রতিক্রিয়ায় বুনে দেয়।* -আপনি যদি মডিউল ০০ তে [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) চলিয়েথাকেন, আপনি ইতিমধ্যেই এই প্যাটার্ন দেখেছেন — `Calculator` টুলগুলো একইভাবে কল হয়েছিল। নিচের সিকোয়েন্স ডায়াগ্রামটি দেখায় ডেমোর পেছনের ঘটনার সঠিক ধারাবাহিকতা: +পিছনের দৃশ্যে, `AiServices` যেকোনো টুলের জন্য টুল-কলিং লুপ চালায় — এখানে একটি সাধারণ `Calculator` দিয়ে উদাহরণ দেওয়া হয়েছে। নিচের সিকুয়েন্স ডায়াগ্রামটি ঠিক কি ঘটে তা দেখায়: -টুল কল সিকোয়েন্স ডায়াগ্রাম +Tool Calling Sequence Diagram -*কুইক স্টার্ট ডেমোর টুল-কলিং লুপ — `AiServices` আপনার মেসেজ ও টুল স্কিমা LLM-এ পাঠায়, LLM `add(42, 58)` এর মত ফাংশন কল দেয়, LangChain4j লোকালি `Calculator` মেথড চালায়, এবং ফলাফল ফাইনাল উত্তরের জন্য ফেরত পাঠায়।* +*টুল-কলিং লুপ — `AiServices` আপনার বার্তা ও টুল স্কিমাস LLM-এ পাঠায়, LLM `add(42, 58)` মত ফাংশন কল দিয়ে উত্তর দেয়, LangChain4j লোকালি `Calculator` মেথড চালায়, এবং ফলাফল চূড়ান্ত উত্তরের জন্য ফেরত দেয়।* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat দিয়ে চেষ্টা করুন:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) খুলুন এবং জিজ্ঞাসা করুন: -> - "কি রকম রি-অ্যাক্ট প্যাটার্ন কাজ করে এবং কেন এটি AI এজেন্টের জন্য কার্যকর?" -> - "এজেন্ট কিভাবে সিদ্ধান্ত নেয় কোন টুল ব্যবহার করবে এবং কোন ক্রমে?" -> - "যদি টুল পরিচালনা ব্যর্থ হয় - আমি কীভাবে ত্রুটি মজবুতভাবে পরিচালনা করব?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) চ্যাট দিয়ে চেষ্টা করুন:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) খুলুন এবং জিজ্ঞাসা করুন: +> - "ReAct প্যাটার্ন কিভাবে কাজ করে এবং AI এজেন্টসের জন্য কেন কার্যকর?" +> - "এজেন্ট কিভাবে সিদ্ধান্ত নেয় কোন টুল ব্যবহার করতে এবং কি ক্রমে?" +> - "যদি কোনো টুল কার্যকরী করা ব্যর্থ হয় — শক্তভাবে ত্রুটি কীভাবে হ্যান্ডেল করব?" -### প্রতিক্রিয়া তৈরি +### প্রতিক্রিয়া প্রস্তুতি -মডেল আবহাওয়ার তথ্য গ্রহণ করে এবং ব্যবহারকারীর জন্য স্বাভাবিক ভাষার মত একটি উত্তর ফর্ম্যাট করে। +মডেল আবহাওয়ার তথ্য পায় এবং এটি ব্যবহারকারীর জন্য প্রাকৃতিক ভাষায় প্রতিক্রিয়া তৈরি করে। ### স্থাপত্য: স্প্রিং বুট অটো-ওয়্যারিং -এই মডিউল LangChain4j এর স্প্রিং বুট ইন্টিগ্রেশন ব্যবহার করে যেখানে `@AiService` ডেক্লারেটিভ ইন্টারফেস থাকে। স্টার্টআপে স্প্রিং বুট সমস্ত `@Component` যা `@Tool` মেথড থাকে, আপনার `ChatModel` বিন এবং `ChatMemoryProvider` আবিষ্কার করে — এবং সবকিছু একক `Assistant` ইন্টারফেসে বায়ারিং করে, কোন বয়লারপ্লেট ছাড়াই। +এই মডিউলটি LangChain4j এর স্প্রিং বুট ইন্টিগ্রেশনের সাথে ডিক্লারেটিভ `@AiService` ইন্টারফেস ব্যবহার করে। স্টার্টআপে স্প্রিং বুট প্রতিটি `@Component` খুঁজে পায় যা `@Tool` মেথড ধারণ করে, আপনার `ChatModel` বিন এবং `ChatMemoryProvider` — তারপর এগুলো একটি একক `Assistant` ইন্টারফেসে একত্রিত করে শূন্য বয়লারপ্লেট দিয়ে। -স্প্রিং বুট অটো-ওয়্যারিং স্থাপত্য +Spring Boot Auto-Wiring Architecture -*The @AiService ইন্টারফেস ChatModel, টুল কম্পোনেন্ট এবং মেমোরি প্রোভাইডার একত্র করে — স্প্রিং বুট সব ওয়্যারিং স্বয়ংক্রিয়ভাবে পরিচালনা করে।* +*@AiService ইন্টারফেস ChatModel, টুল উপাদান, এবং মেমোরি প্রোভাইডারকে একত্রিত করে — স্প্রিং বুট সব ওয়্যারিং স্বয়ংক্রিয়ভাবে করে।* -ফুল অনুরোধ জীবনী নিচের সিকোয়েন্স ডায়াগ্রামে দেখানো হয়েছে — HTTP অনুরোধ থেকে কন্ট্রোলার, সার্ভিস, এবং অটো-ওয়্যার্ড প্রক্সির মাধ্যমে টুল নির্বাহ পর্যন্ত: +এখানে সম্পূর্ণ অনুরোধ জীবনচক্র একটি সিকুয়েন্স ডায়াগ্রামে — HTTP অনুরোধ থেকে শুরু করে কন্ট্রোলার, সার্ভিস, অটো-ওয়্যারড প্রোঅক্সি পর্যন্ত, এবং টুল কার্যকরী করতে ফিরে যাওয়া: -স্প্রিং বুট টুল কল সিকোয়েন্স +Spring Boot Tool Calling Sequence -*সম্পূর্ণ স্প্রিং বুট অনুরোধ জীবনী — HTTP অনুরোধ কন্ট্রোলার ও সার্ভিসের মাধ্যমে প্রবাহিত হয়, তারপর অটো-ওয়্যার্ড Assistant প্রক্সি LLM এবং টুল কল স্বয়ংক্রিয়ভাবে পরিচালনা করে।* +*সম্পূর্ণ স্প্রিং বুট অনুরোধ জীবনচক্র — HTTP অনুরোধ কন্ট্রোলার ও সার্ভিস হয়ে অটো-ওয়্যারড Assistant প্রোঅক্সিতে যায়, যা স্বয়ংক্রিয়ভাবে LLM ও টুল কলসমূহ সমন্বয় করে।* এই পদ্ধতির প্রধান সুবিধাসমূহ: -- **স্প্রিং বুট অটো-ওয়্যারিং** — ChatModel ও টুলস স্বয়ংক্রিয় ইনজেকশন -- **@MemoryId প্যাটার্ন** — স্বয়ংক্রিয় সেশনভিত্তিক মেমোরি ম্যানেজমেন্ট -- **একক ইনস্ট্যান্স** — Assistant একবার তৈরি করে পুনঃব্যবহারযোগ্য -- **টাইপ-সেফ নির্বাহ** — সরাসরি জাভা মেথড কল টাইপ রূপান্তরের সাথে -- **বহুপর্যায়িক সমন্বয়** — টুল চেইনিং স্বয়ংক্রিয়ভাবে পরিচালনা -- **শূন্য বয়লারপ্লেট** — কোন ম্যানুয়াল `AiServices.builder()` কল বা মেমোরি হ্যাশম্যাপ নেই +- **স্প্রিং বুট অটো-ওয়্যারিং** — ChatModel এবং টুলস স্বয়ংক্রিয় ইনজেকশন +- **@MemoryId প্যাটার্ন** — স্বয়ংক্রিয় সেশন-ভিত্তিক মেমোরি ব্যবস্থাপনা +- **একক ইনস্ট্যান্স** — অ্যাসিস্ট্যান্ট একবার তৈরি করে উন্নত পারফরমেন্সের জন্য পুনর্ব্যবহার +- **টাইপ-সেফ কার্যকরী اجرا** — জাভা মেথড সরাসরি টাইপ রূপান্তরের মাধ্যমে কল করা +- **মাল্টি-টার্ন অর্কেস্ট্রেশন** — স্বয়ংক্রিয় টুল চেইনিং পরিচালনা +- **শূন্য বয়লারপ্লেট** — কোনো ম্যানুয়াল `AiServices.builder()` কল বা মেমোরি HashMap নেই -বিকল্প পদ্ধতি (ম্যানুয়াল `AiServices.builder()`) আরো কোড দাবি করে এবং স্প্রিং বুট ইন্টিগ্রেশনের সুবিধা মিস করে। +বিকল্প পদ্ধতিগুলি (ম্যানুয়াল `AiServices.builder()`) অনেক কোড প্রয়োজন এবং স্প্রিং বুট ইন্টিগ্রেশনের সুবিধাগুলো মিস করে। ## টুল চেইনিং -**টুল চেইনিং** — টুল-ভিত্তিক এজেন্টের প্রকৃত ক্ষমতা প্রকাশ পায় যখন একক প্রশ্নের জন্য একাধিক টুল লাগে। উদাহরণ: "সিয়াটলে ফারেনহাইটে আবহাওয়া কেমন?" — এজেন্ট স্বয়ংক্রিয়ভাবে দুইটি টুল চেইন করে: প্রথমে `getCurrentWeather` কল করে সেলসিয়াসে তাপমাত্রা পায়, তারপর সেটি `celsiusToFahrenheit` এ পাঠিয়ে রূপান্তর করে — সবকিছু একক আলাপচারিতা পর্যায়ে। +**টুল চেইনিং** — টুল-ভিত্তিক এজেন্টের প্রকৃত শক্তি তখন প্রকাশ পায় যখন একটি প্রশ্নে একাধিক টুল দরকার হয়। বলুন "সিয়াটেলের আবহাওয়া ফারেনহাইটে কেমন?" এবং এজেন্ট স্বয়ংক্রিয়ভাবে দুইটি টুল চেইন করে: প্রথমে `getCurrentWeather` কল করে সেলসিয়াসে তাপমাত্রা পায়, তারপর সেটি `celsiusToFahrenheit`-এ পাঠিয়ে রূপান্তর করে — সব এক কথোপকথন পর্বে। -টুল চেইনিং উদাহরণ +Tool Chaining Example -*টুল চেইনিং বাস্তবে — এজেন্ট প্রথমে getCurrentWeather কল করে, সেলসিয়াস ফলাফল celsiusToFahrenheit তে পাঠায়, এবং একত্রিত উত্তর দেয়।* +*টুল চেইনিং কাজে — এজেন্ট প্রথমে getCurrentWeather কল করে, তারপর সেলসিয়াস ফলাফলকে celsiusToFahrenheit-এ পাঠায়, এবং মিলিত উত্তর দেয়।* -**সুন্দর ব্যর্থতা** — mock ডাটাতে না থাকা শহরের আবহাওয়া চাইলে টুল একটি ত্রুটি বার্তা দেয়, এবং AI ব্যাখ্যা করে সাহায্য করতে পারছে না, ক্র্যাশ না করে। টুলগুলো সুরক্ষিতভাবে ব্যর্থ হয়। নিচের আর্কচিত্রে দুই ধরনের পদ্ধতি তুলনা করা হয়েছে — যথাযথ ত্রুটি পরিচালনায় এজেন্ট ব্যতিক্রম টেনে বুঝিয়ে দেয়, অন্যথায় পুরো অ্যাপ্লিকেশন ক্র্যাশ হয়ে যায়: +**সুশৃঙ্খল ব্যর্থতা** — এমন শহরের আবহাওয়া জিজ্ঞাসা করুন যা মক ডেটায় নেই। টুল ত্রুটি বার্তা দেয়, এবং AI ব্যাখ্যা করে তা সাহায্য করতে পারে না, পুরো অ্যাপ্লিকেশন ক্র্যাশ করে না। টুলস নিরাপদে ব্যর্থ হয়। নিচের ডায়াগ্রাম দুটি পদ্ধতির তুলনা করে — সঠিক ত্রুটি পরিচালনায় এজেন্ট ব্যতিক্রম ধরে সাহায্যপূর্ণ উত্তর দেয়, অন্যদিকে ত্রুটি না হলে পুরো অ্যাপ্লিকেশন ক্র্যাশ করে: -ত্রুটি পরিচালনা প্রবাহ +Error Handling Flow -*যখন একটি টুল ব্যর্থ হয়, এজেন্ট ত্রুটি ধরে সাহায্যকারী ব্যাখ্যা দেয় ক্র্যাশ করার পরিবর্তে।* +*যখন কোনো টুল ব্যর্থ হয়, এজেন্ট ত্রুটি ধরে সাহায্যপূর্ণ ব্যাখ্যা সহ সাড়া দেয় ক্র্যাশ না করে।* -এটি একক আলাপটার্নে ঘটে। এজেন্ট স্বতন্ত্রভাবে একাধিক টুল কল পরিচালনা করে। +এটি এক কথোপকথন পর্বে ঘটে। এজেন্ট স্বয়ংক্রিয়ভাবে একাধিক টুল কল সমন্বয় করে। ## অ্যাপ্লিকেশন চালান -**ডিপ্লয়মেন্ট যাচাই করুন:** +**ডিপ্লয়মেন্ট যাচাই:** -রুট ডিরেক্টরিতে `.env` ফাইলটি নিশ্চিত করুন Azure ক্রেডেনশিয়ালস সহ (মডিউল ০১ চলাকালে তৈরি)। মডিউল ডিরেক্টরি (`04-tools/`) থেকে এটি চালান: +নিশ্চিত করুন মূল ডিরেক্টরিতে `.env` ফাইল আছে Azure প্রমাণপত্রাদি সহ (মডিউল ০১ চলাকালীন তৈরি)। এই মডিউল ডিরেক্টরি থেকে চালান (`04-tools/`): -**Bash:** +**Bash:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT দেখানো উচিত ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT দেখানো উচিত +Get-Content ..\.env # প্রদর্শন করা উচিত AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **অ্যাপ্লিকেশন শুরু করুন:** -> **নোট:** যদি আপনি ইতোমধ্যে রুট ডিরেক্টরি থেকে `./start-all.sh` ব্যবহার করে সব অ্যাপ্লিকেশন শুরু করে থাকেন (যেমন মডিউল ০১ এ উল্লেখ করা হয়েছে), তাহলে এই মডিউল ইতোমধ্যেই ৮০৮৪ পোর্টে চলছে। নিচের শুরু কমান্ডগুলি এড়িয়ে সরাসরি http://localhost:8084 এ যান। +> **বিঃদ্রঃ:** যদি আপনি ইতোমধ্যে সব অ্যাপ্লিকেশন চালু করে থাকেন `./start-all.sh` দিয়ে মূল ডিরেক্টরি থেকে (মডিউল ০১ এ বর্ণিত), এই মডিউলটি ইতোমধ্যে ৮০৮৪ পোর্টে চলছে। আপনি নিচের শুরু কমান্ড বাদ দিতে পারেন এবং সরাসরি http://localhost:8084 এ যেতে পারেন। -**অপশন ১: স্প্রিং বুট ড্যাশবোর্ড ব্যবহার (VS Code ব্যবহারকারীদের জন্য সুপারিশকৃত)** +**বিকল্প ১: স্প্রিং বুট ড্যাশবোর্ড ব্যবহার (VS কোড ব্যবহারকারীদের জন্য সুপারিশকৃত)** -ডেভ কন্টেইনারে স্প্রিং বুট ড্যাশবোর্ড এক্সটেনশন অন্তর্ভুক্ত আছে, যা সব স্প্রিং বুট অ্যাপ্লিকেশন পরিচালনার জন্য ভিজ্যুয়াল ইন্টারফেস দেয়। আপনি VS Code এর Activity Bar এর বামে স্প্রিং বুট আইকন থেকে এটি পাবেন। +ডেভ কন্টেইনারে স্প্রিং বুট ড্যাশবোর্ড এক্সটেনশন রয়েছে, যা সমস্ত স্প্রিং বুট অ্যাপ্লিকেশন পরিচালনার জন্য ভিজ্যুয়াল ইন্টারফেস দেয়। আপনি এটি VS কোডের বাম পাশের অ্যাক্টিভিটি বারে (স্প্রিং বুট আইকন দেখুন) পাবেন। স্প্রিং বুট ড্যাশবোর্ড থেকে আপনি: -- ওয়ার্কস্পেসের সব স্প্রিং বুট অ্যাপ্লিকেশন দেখতে পারবেন -- এক ক্লিকে অ্যাপ্লিকেশন শুরু/বন্ধ করতে পারবেন -- রিয়েল-টাইম লগস দেখতে পারবেন -- অ্যাপ্লিকেশনের অবস্থা মনিটর করতে পারবেন -শুধুমাত্র "tools" এর পাশের প্লে বাটনে ক্লিক করুন এই মডিউলটি শুরু করার জন্য, অথবা সব মডিউল একসাথেই শুরু করুন। +- ওয়ার্কস্পেসের সব স্প্রিং বুট অ্যাপ্লিকেশন দেখতে পারেন +- এক ক্লিকে অ্যাপ্লিকেশন শুরু/বন্ধ করতে পারেন +- বাস্তব সময় লগ দেখতে পারেন +- অ্যাপ্লিকেশনের অবস্থা পর্যবেক্ষণ করতে পারেন -এখন দেখুন VS Code-এ Spring Boot Dashboard এর মতো দেখতে: +শুধুমাত্র "tools" এর পাশে প্লে বোতাম ক্লিক করে এই মডিউল শুরু করুন, অথবা সব মডিউল একসাথে চালু করুন। -Spring Boot Dashboard +স্প্রিং বুট ড্যাশবোর্ড VS কোডে কেমন দেখায়, তা হলো: +Spring Boot ড্যাশবোর্ড -*VS Code-এ Spring Boot Dashboard — এক জায়গা থেকে সব মডিউল শুরু, বন্ধ এবং মনিটর করুন* +*VS কোডে Spring Boot ড্যাশবোর্ড — এক জায়গা থেকে সব মডিউল শুরু, বন্ধ এবং পর্যবেক্ষণ করুন* -**বিকল্প ২: শেল স্ক্রিপ্ট ব্যবহার করে** +**বিকল্প ২: শেল স্ক্রিপ্ট ব্যবহার** -সব ওয়েব অ্যাপ্লিকেশন (মডিউল ০১-০৪) শুরু করুন: +সব ওয়েব অ্যাপ্লিকেশন (মডিউল ০১-০৪) শুরু করুন: **Bash:** ```bash @@ -242,7 +242,7 @@ cd .. # রুট ডিরেক্টরি থেকে .\start-all.ps1 ``` -অথবা শুধু এই মডিউলটি শুরু করুন: +অথবা শুধুমাত্র এই মডিউল শুরু করুন: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -দুই স্ক্রিপ্টই স্বয়ংক্রিয়ভাবে রুট `.env` ফাইল থেকে পরিবেশ ভেরিয়েবল লোড করে এবং যদি JAR ফাইল না থাকে তাহলে তা তৈরি করবে। +উভয় স্ক্রিপ্ট স্বয়ংক্রিয়ভাবে রুট `.env` ফাইল থেকে পরিবেশ ভেরিয়েবল লোড করবে এবং যদি JAR ফাইল না থাকে তবে তা তৈরি করবে। -> **[!NOTE]** আপনি যদি সব মডিউল ম্যানুয়ালি বিল্ড করতে চান শুরু করার আগে: +> **দ্রষ্টব্য:** আপনি যদি শুরু করার আগে সব মডিউল ম্যানুয়ালি তৈরি করতে চান: > > **Bash:** > ```bash @@ -274,114 +274,114 @@ cd 04-tools আপনার ব্রাউজারে http://localhost:8084 খুলুন। -**বন্ধ করার জন্য:** +**বন্ধ করতে:** **Bash:** ```bash ./stop.sh # শুধুমাত্র এই মডিউল # অথবা -cd .. && ./stop-all.sh # সমস্ত মডিউলসমূহ +cd .. && ./stop-all.sh # সব মডিউলগুলি ``` **PowerShell:** ```powershell .\stop.ps1 # শুধুমাত্র এই মডিউল # অথবা -cd ..; .\stop-all.ps1 # সমস্ত মডিউলসমূহ +cd ..; .\stop-all.ps1 # সমস্ত মডিউল ``` ## অ্যাপ্লিকেশন ব্যবহার -অ্যাপ্লিকেশনটি একটি ওয়েব ইন্টারফেস প্রদান করে যেখানে আপনি একটি AI এজেন্টের সাথে ইন্টারঅ্যাক্ট করতে পারেন যার কাছে আবহাওয়া এবং তাপমাত্রা রূপান্তর সরঞ্জামের অ্যাক্সেস রয়েছে। ইন্টারফেসটি দেখতে কেমন তার একটি উদাহরণ এখানে — এতে দ্রুত শুরু করার উদাহরণ এবং অনুরোধ পাঠানোর জন্য একটি চ্যাট প্যানেল রয়েছে: +অ্যাপ্লিকেশনটি একটি ওয়েব ইন্টারফেস প্রদান করে যেখানে আপনি এমন একটি AI এজেন্টের সাথে যোগাযোগ করতে পারেন যার হাতে আবহাওয়া এবং তাপমাত্রা রূপান্তর সরঞ্জাম রয়েছে। ইন্টারফেসটি দেখতে কেমন — এতে দ্রুত শুরু করার উদাহরণ এবং অনুরোধ পাঠানোর জন্য একটি চ্যাট প্যানেল অন্তর্ভুক্ত: -AI Agent Tools Interface +AI এজেন্ট টুলস ইন্টারফেস -*AI Agent Tools ইন্টারফেস — সরঞ্জামগুলো নিয়ে দ্রুত উদাহরণ এবং চ্যাট ইন্টারফেস* +*AI এজেন্ট টুলস ইন্টারফেস - দ্রুত উদাহরণ এবং টুলসের সাথে যোগাযোগের জন্য চ্যাট ইন্টারফেস* -### সহজ সরঞ্জাম ব্যবহার পরীক্ষা করুন +### সহজ টুল ব্যবহার চেষ্টা করুন -একটি সরল অনুরোধ দিয়ে শুরু করুন: "100 ডিগ্রি ফ্যারেনহাইট থেকে সেলসিয়াসে রূপান্তর করুন"। এজেন্ট বুঝবে যে তাকে তাপমাত্রার রূপান্তর সরঞ্জামটি ব্যবহার করতে হবে, সঠিক প্যারামিটার সহ কল করে ফলাফল দিবে। লক্ষ্য করুন কতটা স্বাভাবিক লাগছে - আপনি কোন সরঞ্জাম ব্যবহার করবেন বা কিভাবে কল করবেন তা উল্লেখ করেননি। +সরল অনুরোধ দিয়ে শুরু করুন: "100 ডিগ্রি ফারেনহাইট কে সেলসিয়াসে রূপান্তর করুন"। এজেন্ট বুঝতে পারছে এটি তাপমাত্রা রূপান্তরের টুল ব্যবহার করবে, সঠিক প্যারামিটার সহ টুলকে কল করে এবং ফলাফল ফিরিয়ে দেয়। লক্ষ্য করুন এটা কতটা স্বাভাবিক — আপনি নির্দিষ্ট করেননি কোন টুল ব্যবহার করবেন বা কীভাবে কল করবেন। ### টুল চেইনিং পরীক্ষা করুন -এবার একটু জটিল কিছু চেষ্টা করুন: "সিয়াটলের আবহাওয়া কী ও তাকে ফ্যারেনহাইটে রূপান্তর করুন?" দেখুন এজেন্ট কীভাবে ধাপে ধাপে কাজ করে। প্রথমে আবহাওয়া নেয় (যা সেলসিয়াসে দেয়), বুঝতে পারে যে ফ্যারেনহাইটে রূপান্তর করতে হবে, রূপান্তর সরঞ্জাম কল করে এবং উভয় ফলাফলকে একত্রিত করে একটি উত্তর দেয়। +এখন কিছু বেশি জটিল চেষ্টা করুন: "সিয়াটলের আবহাওয়া কেমন এবং এটা ফারেনহাইটে রূপান্তর করুন?" ধাপে ধাপে এজেন্ট এই কাজ করছে। প্রথমে আবহাওয়া নিয়ে আসে (যা সেলসিয়াসে ফলাফল দেয়), বুঝতে পারে ফারেনহাইটে রূপান্তর করতে হবে, রূপান্তর টুল কল করে, এবং উভয় ফলাফল একত্র করে একটি উত্তর তৈরি করে। ### কথোপকথনের প্রবাহ দেখুন -চ্যাট ইন্টারফেস কথোপকথনের ইতিহাস রাখে, যা আপনাকে বহুবারের আলাপচারিতা করার সুযোগ দেয়। আপনি সব আগের প্রশ্ন ও উত্তর দেখতে পারেন, ফলে কথোপকথন ট্র্যাক করা এবং কিভাবে এজেন্ট একাধিক বিনিময়ে প্রসঙ্গ তৈরি করছে বোঝা সহজ হয়। +চ্যাট ইন্টারফেস কথোপকথনের ইতিহাস সংরক্ষণ করে, যা আপনাকে একাধিক দফায় যোগাযোগ করার সুযোগ দেয়। আপনি আগের সব প্রশ্ন এবং উত্তর দেখতে পারেন, যা কথোপকথন ট্র্যাক এবং কিভাবে এজেন্ট একাধিক বিনিময়ে প্রসঙ্গ গড়ে তোলে বুঝতে সহজ করে। -Conversation with Multiple Tool Calls +একাধিক টুল কলের সাথে কথোপকথন -*সহজ রূপান্তর, আবহাওয়া অনুসন্ধান, ও টুল চেইনিং দেখানো বহুবারের কথোপকথন* +*সহজ রূপান্তর, আবহাওয়া খোঁজ ও টুল চেইনিং দেখানো একাধিক দফার কথোপকথন* -### বিভিন্ন অনুরোধ দিয়ে পরীক্ষা করুন +### বিভিন্ন অনুরোধ নিয়ে পরীক্ষা করুন -বিভিন্ন মিলিয়ে দেখুন: -- আবহাওয়া অনুসন্ধান: "টোকিওর আবহাওয়া কেমন?" +বিভিন্ন কম্বিনেশন চেষ্টা করুন: +- আবহাওয়া খোঁজ: "টোকিওর আবহাওয়া কেমন?" - তাপমাত্রা রূপান্তর: "২৫°C কত কেলভিন?" -- মিলিত প্রশ্ন: "প্যারিসের আবহাওয়া দেখাও এবং বলো ২০°C এর বেশি কিনা" +- মিশ্র অনুরোধ: "প্যারিসের আবহাওয়া পরীক্ষা করুন এবং বলুন এটি ২০°C এর উপরে কি না" -দ্রষ্টব্য করুন কিভাবে এজেন্ট প্রাকৃতিক ভাষা ব্যাখ্যা করে এবং উপযুক্ত টুল কলের সাথে ম্যাচ করে। +লক্ষ্য করুন এজেন্ট কিভাবে প্রাকৃতিক ভাষা বোঝে এবং যথোপযুক্ত টুল কলস এ ম্যাপ করে। -## মূল ধারণা +## মূল ধারণাসমূহ ### ReAct প্যাটার্ন (যুক্তি ও কর্ম) -এজেন্ট যুক্তি চিন্তা করা (কি করতে হবে) এবং কার্যকর করা (সরঞ্জাম ব্যবহার করা) এর মধ্যে পাল্টায়। এই প্যাটার্ন স্বায়ত্তশাসিত সমস্যা সমাধান সক্ষম করে, শুধু নির্দেশ অনুসরণ করার চেয়ে। +এজেন্ট যুক্তি করার (কী করতে হবে সিদ্ধান্ত নেওয়া) এবং কর্ম (টুল ব্যবহারের) মধ্যে পাল্টা কাজ করে। এই প্যাটার্ন স্বয়ংক্রিয় সমস্যা সমাধান সক্ষম করে, শুধু নির্দেশনা অনুসরণের বদলে। ### টুল বর্ণনা গুরুত্বপূর্ণ -আপনার টুলের বর্ণনার গুণগত মান সরাসরি প্রভাব ফেলে এজেন্ট কীভাবে সেগুলো ব্যবহার করে। স্পষ্ট, নির্দিষ্ট বর্ণনা মডেলকে নির্দেশ দেয় কখন এবং কিভাবে প্রতিটি টুল কল করতে হবে। +আপনার টুলের বর্ণনার গুণাগুণ সরাসরি নির্ধারণ করে এজেন্ট টুলগুলো কত ভাল ব্যবহার করে। পরিষ্কার, স্পষ্ট বর্ণনা মডেলকে সাহায্য করে কখন এবং কিভাবে টুল কল করতে হবে বুঝতে। ### সেশন ম্যানেজমেন্ট -`@MemoryId` অ্যানোটেশন স্বয়ংক্রিয় সেশনভিত্তিক মেমোরি ব্যবস্থাপনা সক্ষম করে। প্রতিটি সেশন আইডির জন্য একটি নিজস্ব `ChatMemory` ইনস্ট্যান্স `ChatMemoryProvider` বিন দ্বারা পরিচালিত হয়, ফলে একাধিক ব্যবহারকারী একই সময়ে এজেন্টের সাথে আলাপচারিতা করতে পারে কোনো কথোপকথন মিশ্রিত না হয়। নিচের চিত্র দেখায় কিভাবে একাধিক ব্যবহারকারী তাদের সেশন আইডির ভিত্তিতে পৃথক মেমোরি স্টোরে রুট করা হয়: +`@MemoryId` এনোটেশন স্বয়ংক্রিয় সেশন-ভিত্তিক মেমোরি ব্যবস্থাপনা সক্ষম করে। প্রতিটি সেশন আইডি আলাদা `ChatMemory` ইনস্ট্যান্স পায় যা `ChatMemoryProvider` বিন দ্বারা পরিচালিত হয়, ফলে একাধিক ব্যবহারকারী একই সাথে এজেন্টের সাথে কথা বলতে পারে তাদের কথোপকথন মিশে না। নিচের চিত্রটি দেখায় কীভাবে একাধিক ব্যবহারকারী তাদের সেশন আইডি অনুযায়ী পৃথক মেমোরি স্টোরে রাউট হয়: -Session Management with @MemoryId +সেশন ম্যানেজমেন্ট @MemoryId এর সাথে -*প্রতিটি সেশন আইডি আলাদা কথোপকথনের ইতিহাস তৈরি করে — ব্যবহারকারীরা একে অপরের বার্তা কখনই দেখতে পায় না।* +*প্রতিটি সেশন আইডি পৃথক কথোপকথন ইতিহাসে ম্যাপ হয় — ব্যবহারকারীরা একে অপরের বার্তা দেখে না।* -### ত্রুটি পরিচালনা +### ত্রুটি হ্যান্ডলিং -টুলগুলো ব্যর্থ হতে পারে — API টাইমআউট, ভুল প্যারামিটার, বহিরাগত সার্ভিস বন্ধ হয়ে যাওয়া। প্রোডাকশন এজেন্টগুলোতে ত্রুটি পরিচালনা থাকা জরুরি যাতে মডেল সমস্যা ব্যাখ্যা করতে পারে অথবা বিকল্প চেষ্টা করে, পুরো অ্যাপ্লিকেশন ক্র্যাশ না করে। যখন টুলে কোনো এক্সসেপশন ঘটে, LangChain4j তা ধরা দেয় এবং ত্রুটির বার্তা মডেলে ফেরত দেয়, যা স্বাভাবিক ভাষায় সমস্যা ব্যাখ্যা করতে পারে। +টুলস ব্যর্থ হতে পারে — API টাইমআউট, প্যারামিটার ভুল হতে পারে, বাহ্যিক সার্ভিস বন্ধ হতে পারে। প্রডাকশন এজেন্টে ত্রুটি হ্যান্ডলিং থাকা উচিত যাতে মডেল সমস্যা ব্যাখ্যা করতে পারে বা বিকল্প চেষ্টা করতে পারে, পুরো অ্যাপ্লিকেশন ক্র্যাশ না করে। যখন একটি টুল এক্সেপশন ছুড়ে ফেলে, LangChain4j তা ধরে নেয় এবং ত্রুটি বার্তাটি মডেলে ফেরত দেয়, যা তখন প্রাকৃতিক ভাষায় সমস্যা ব্যাখ্যা করতে পারে। -## উপলব্ধ সরঞ্জামসমূহ +## উপলব্ধ টুলস -নিচের চিত্রে দেখানো হয়েছে আপনি যে বিস্তৃত সরঞ্জাম সমন্বয় তৈরি করতে পারেন তার চিত্র। এই মডিউল আবহাওয়া এবং তাপমাত্রা সরঞ্জাম দেখায়, কিন্তু একই `@Tool` প্যাটার্ন যেকোনো জাভা মেথডের জন্য কাজ করে — ডাটাবেস কোয়েরি থেকে পেমেন্ট প্রসেসিং পর্যন্ত। +নিচের চিত্রটি দেখায় আপনি যে বিস্তৃত টুল ইকোসিস্টেম তৈরি করতে পারেন। এই মডিউল আবহাওয়া এবং তাপমাত্রার টুলস প্রদর্শন করে, তবে একই `@Tool` প্যাটার্ন যেকোনো জাভা মেথডের জন্য কাজ করে — ডাটাবেস কোয়েরি থেকে পেমেন্ট প্রসেসিং পর্যন্ত। -Tool Ecosystem +টুল ইকোসিস্টেম -*যে কোনো জাভা মেথড @Tool দিয়ে অ্যানোটেট করলে তা AI-র কাছে উপলব্ধ হয় — প্যাটার্নটি ডাটাবেস, API, ইমেইল, ফাইল অপারেশন এবং আরও অনেক ক্ষেত্রে প্রসারিত হয়।* +*@Tool দিয়ে এনোটেট করা যেকোনো জাভা মেথড AI’র জন্য উপলব্ধ হয় — প্যাটার্নটি ডাটাবেস, API, ইমেইল, ফাইল অপারেশনসহ আরও প্রসারিত।* -## কখন টুল ভিত্তিক এজেন্ট ব্যবহার করবেন +## কখন টুল-ভিত্তিক এজেন্ট ব্যবহার করবেন -প্রতিটি অনুরোধে টুল দরকার হয় না। সিদ্ধান্ত আসে AI-কে বাহ্যিক সিস্টেমের সাথে ইন্টারঅ্যাক্ট করতে হবে কিনা বা নিজের জ্ঞানের ওপর থেকে উত্তর দিতে পারবে কিনা। নিচের গাইড সংক্ষেপে বলে কখন টুল মূল্যবান এবং কখন তা প্রয়োজন নেই: +প্রতিটি অনুরোধে টুল প্রয়োজন হয় না। সিদ্ধান্ত হয় AI বাহ্যিক সিস্টেমের সাথে যোগাযোগ করবে কিনা বা নিজের জ্ঞান থেকে উত্তর দেবে কিনা। নিচের গাইডটি সংক্ষেপে বলে কখন টুল দরকার এবং কখন অপ্রয়োজনীয়: -When to Use Tools +কখন টুল ব্যবহার করবেন -*দ্রুত সিদ্ধান্ত নেয়ার জন্য গাইড — টুল দরকার রিয়েল-টাইম ডেটা, হিসাব, এবং ক্রিয়াকলাপের জন্য; সাধারণ জ্ঞানের প্রশ্ন এবং সৃজনশীল কাজের জন্য দরকার হয় না।* +*দ্রুত সিদ্ধান্ত নেওয়ার গাইড — টুলস বাস্তবসময় ডেটা, হিসাব ও কার্যকলাপের জন্য; সাধারণ জ্ঞান ও সৃজনশীল কাজের জন্য দরকার হয় না।* -## টুল বনাম RAG +## টুলস বনাম RAG -মডিউল ০৩ এবং ০৪ দুটোই AI-র ক্ষমতা বাড়ায়, কিন্তু মৌলিকভাবে ভিন্ন পথে। RAG মডেলকে **জ্ঞান** দেয় ডকুমেন্ট রিট্রিভ করে। টুলস মডেলকে **কর্ম** করার ক্ষমতা দেয় ফাংশন কল করে। নিচের চিত্রে এই দুই পদ্ধতির তুলনা করা হয়েছে — প্রতিটি ওয়ার্কফ্লো কার্যপ্রণালী থেকে শুরু করে তাদের সুবিধা ও অসুবিধা পর্যন্ত: +মডিউল ০৩ এবং ০৪ দুটোই AI-কে আরও যোগ্য করে তবে মৌলিকভাবে ভিন্নভাবে। RAG মডেলকে **জ্ঞান** অ্যাক্সেস করায় ডকুমেন্ট রিট্রিভ করে। টুলস মডেলকে **কার্য** করতে দেয় ফাংশন কল করে। নিচের চিত্রটি সাইড বাই সাইড তুলনা করে — প্রতিটি কর্মপ্রবাহ কিভাবে কাজ করে এবং তাদের ট্রেড-অফ রয়েছে: -Tools vs RAG Comparison +টুলস বনাম RAG তুলনা -*RAG স্থির ডকুমেন্ট থেকে তথ্য নেয় — টুলস কর্ম সম্পাদন করে এবং গতিশীল, রিয়েল-টাইম ডেটা আনে। অনেক প্রোডাকশন সিস্টেম উভয়কে একত্র করে।* +*RAG স্থির ডকুমেন্ট থেকে তথ্য আনয়নে, টুলস কার্য সম্পাদন ও বাস্তবসময় ডেটা আনয়নে ব্যবহৃত হয়। অনেক প্রডাকশন সিস্টেম উভয়ই ব্যবহার করে।* -বাস্তবে, অনেক প্রোডাকশন সিস্টেম উভয় পদ্ধতি ব্যবহার করে: RAG দিয়ে আপনার ডকুমেন্টেশনে ভিত্তি স্থাপন এবং টুলস দিয়ে লাইভ ডেটা আনা বা অপারেশন সম্পাদন করা। +অ্যাকচুয়ালি, অনেক প্রডাকশন সিস্টেম উভয় পদ্ধতির সমন্বয় করে: RAG আপনার ডকুমেন্টেশনে ভিত্তি স্থাপন করতে, আর টুলস লایভ ডেটা আনতে বা অপারেশন চালাতে। ## পরবর্তী ধাপ -**পরবর্তী মডিউল:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**পরবর্তী মডিউল:** [05-mcp - মডেল কনটেক্সট প্রোটোকল (MCP)](../05-mcp/README.md) --- -**নেভিগেশন:** [← আগের: মডিউল ০৩ - RAG](../03-rag/README.md) | [প্রধান পৃষ্ঠায় ফিরে যান](../README.md) | [পরবর্তী: মডিউল ০৫ - MCP →](../05-mcp/README.md) +**নেভিগেশন:** [← পূর্ববর্তী: মডিউল ০৩ - RAG](../03-rag/README.md) | [মূল পৃষ্ঠায় ফিরে যান](../README.md) | [পরবর্তী: মডিউল ০৫ - MCP →](../05-mcp/README.md) --- -**অস্বীকারোক্তি**: -এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। আমরা যথাসাধ্য সঠিকতার দিকে লক্ষ্য রাখি, তবে স্বয়ংক্রিয় অনুবাদে ভুল বা ত্রুটি থাকতে পারে এমনটি দয়া করে বিবেচনা করুন। যেখানে মূল নথিটি তার স্থানীয় ভাষায় রয়েছে তা কর্তৃপক্ষস্বরূপ বিবেচনা করা উচিত। গুরুত্বপূর্ণ তথ্যের জন্য, পেশাদার মানব অনুবাদ করা সুপারিশ করা হয়। এই অনুবাদ ব্যবহারে সৃষ্ট কোনো ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়ী নই। +**অস্বীকৃতি**: +এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা শুদ্ধতার জন্য চেষ্টা করি, অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার স্বভাষায় কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে প্রয়োজনীয় ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই। \ No newline at end of file diff --git a/translations/bn/README.md b/translations/bn/README.md index 833903eec..878b1bf0e 100644 --- a/translations/bn/README.md +++ b/translations/bn/README.md @@ -1,19 +1,19 @@ LangChain4j -# নবীনদের জন্য LangChain4j +# LangChain4j শিক্ষানবিসদের জন্য -LangChain4j এবং Azure OpenAI GPT-5.2 দিয়ে AI অ্যাপ্লিকেশন তৈরি করার একটি কোর্স, প্রাথমিক চ্যাট থেকে AI এজেন্ট পর্যন্ত। +LangChain4j এবং Azure OpenAI GPT-5.2 দিয়ে এআই অ্যাপ্লিকেশন তৈরি করার জন্য একটি কোর্স, যা মৌলিক চ্যাট থেকে শুরু করে AI এজেন্ট পর্যন্ত। -### 🌐 বহু-ভাষা সমর্থন +### 🌐 বহুভাষিক সমর্থন -#### GitHub Action এর মাধ্যমে সমর্থিত (স্বয়ংক্রিয় ও সর্বদা আপ-টু-ডেট) +#### GitHub Action দ্বারা সমর্থিত (স্বয়ংক্রিয় এবং সর্বদা আপ-টু-ডেট) [Arabic](../ar/README.md) | [Bengali](./README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **লোকালি ক্লোন করতে চান?** +> **স্থানীয়ভাবে ক্লোন করতে চান?** > -> এই রিপোজিটরিতে ৫০+ ভাষার অনুবাদ রয়েছে যা ডাউনলোড সাইজ অনেক বড় করে তোলে। অনুবাদ ছাড়া ক্লোন করতে, sparse checkout ব্যবহার করুন: +> এই রেপোজিটরিটিতে ৫০+ ভাষার অনুবাদ রয়েছে যা ডাউনলোডের আকার অনেক বাড়ায়। অনুবাদ ছাড়া ক্লোন করতে sparse checkout ব্যবহার করুন: > > **Bash / macOS / Linux:** > ```bash @@ -29,62 +29,60 @@ LangChain4j এবং Azure OpenAI GPT-5.2 দিয়ে AI অ্যাপ্ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> এটি আপনাকে কোর্সটি সম্পন্ন করতে প্রয়োজনীয় সমস্ত কিছু দ্রুত ডাউনলোড করতে দেয়। +> এভাবে আপনি দ্রুত ডাউনলোড সহ কোর্স সম্পূর্ণ করতে সবকিছু পাবেন। -## বিষয়বস্তু সূচি +## বিষয়বস্তু তালিকা -1. [দ্রুত শুরু](00-quick-start/README.md) - LangChain4j দিয়ে শুরু করুন -2. [পরিচিতি](01-introduction/README.md) - LangChain4j এর মূল বিষয় শিখুন -3. [প্রম্পট ইঞ্জিনিয়ারিং](02-prompt-engineering/README.md) - কার্যকর প্রম্পট ডিজাইন মাস্টার করুন -4. [RAG (রিট্রিভাল-অগমেন্টেড জেনারেশন)](03-rag/README.md) - বুদ্ধিমান জ্ঞানভিত্তিক ব্যবস্থা তৈরি করুন -5. [টুলস](04-tools/README.md) - বাহ্যিক টুলস এবং সরল সহকারী সংহত করুন -6. [MCP (মডেল কনটেক্সট প্রোটোকল)](05-mcp/README.md) - মডেল কনটেক্সট প্রোটোকল (MCP) এবং এজেন্টিক মডিউল নিয়ে কাজ করুন +1. [পরিচিতি](01-introduction/README.md) - LangChain4j এর মূল বিষয়গুলো শেখা +2. [প্রম্পট ইঞ্জিনিয়ারিং](02-prompt-engineering/README.md) - কার্যকর প্রম্পট ডিজাইনে দক্ষতা অর্জন +3. [RAG (রিট্রিভাল-অগমেন্টেড জেনারেশন)](03-rag/README.md) - বুদ্ধিমান জ্ঞানে ভিত্তিক সিস্টেম তৈরি করুন +4. [উপকরণ](04-tools/README.md) - বাইরের উপকরণ এবং সহজ সহকারী একত্রিত করা +5. [MCP (মডেল কনটেক্সট প্রোটোকল)](05-mcp/README.md) - Model Context Protocol (MCP) এবং Agentic মডিউলের সঙ্গে কাজ করা ### ভিডিও ওয়াকথ্রু -প্রতিটি মডিউলের সাথে একটি সঙ্গী লাইভ সেশন থাকে যেখানে আমরা ধাপে ধাপে ধারণা এবং কোড একত্রে প্রদর্শন করি। +প্রতিটি মডিউলের একটি সংযুক্ত লাইভ সেশন রয়েছে যেখানে আমরা ধাপে ধাপে ধারণা এবং কোড ব্যাখ্যা করি। | মডিউল | ভিডিও | |--------|-------| -| ০১ - পরিচিতি | [LangChain4j দিয়ে শুরু করা](https://www.youtube.com/live/nl_troDm8rQ) | -| ০২ - প্রম্পট ইঞ্জিনিয়ারিং | [LangChain4j সাথে প্রম্পট ইঞ্জিনিয়ারিং](https://www.youtube.com/live/PJ6aBaE6bog) | -| ০৩ - RAG | [LangChain4j এর মাধ্যমে RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| ০৪ - টুলস ও ০৫ - MCP | [টুলস এবং MCP সহ AI এজেন্ট](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 01 - পরিচিতি | [LangChain4j দিয়ে শুরু করা](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - প্রম্পট ইঞ্জিনিয়ারিং | [LangChain4j দিয়ে প্রম্পট ইঞ্জিনিয়ারিং](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [LangChain4j দিয়ে RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 04 - টুলস এবং 05 - MCP | [টুলস এবং MCP দিয়ে AI এজেন্ট](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## শিক্ষার পথ +## শেখার পথ -**LangChain4j তে নতুন?** মূল শব্দ এবং ধারণার সংজ্ঞার জন্য [Glossary](docs/GLOSSARY.md) দেখুন। +**LangChain4j এ নতুন?** মূল টার্ম এবং ধারণার সংজ্ঞাগুলির জন্য [Glossary](docs/GLOSSARY.md) দেখুন। > **দ্রুত শুরু** -১. এই রিপোজিটরিটি আপনার GitHub অ্যাকাউন্টে fork করুন -২. **Code** → **Codespaces** ট্যাবে ক্লিক করুন → **...** → **নতুন অপশনসহ...** নির্বাচন করুন -৩. ডিফল্ট ব্যবহার করুন – এটি এই কোর্সের জন্য তৈরি ডেভেলপমেন্ট কনটেইনার বেছে নেবে -৪. **Create codespace** ক্লিক করুন -৫. পরিবেশ প্রস্তুত হতে ৫-১০ মিনিট অপেক্ষা করুন -৬. সরাসরি [দ্রুত শুরু](./00-quick-start/README.md) এ যান শুরু করার জন্য! +1. আপনার GitHub অ্যাকাউন্টে এই রেপোজিটরি ফর্ক করুন +2. **Code** → **Codespaces** ট্যাব → **...** → **New with options...** এ ক্লিক করুন +3. ডিফল্ট ব্যবহার করুন – এটি এই কোর্সের জন্য তৈরি Development container নির্বাচন করবে +4. **Create codespace** ক্লিক করুন +5. পরিবেশ প্রস্তুত হতে ৫-১০ মিনিট অপেক্ষা করুন +6. শুরুতেই [পরিচিতি](./01-introduction/README.md) এ যান! -মডিউলগুলি সম্পন্ন করার পরে, LangChain4j টেস্টিং ধারণা বাস্তবায়নের জন্য [Testing Guide](docs/TESTING.md) দেখুন। +মডিউল সমাপ্তির পরে, LangChain4j পরীক্ষার ধারণাগুলো দেখতে [Testing Guide](docs/TESTING.md) অনুসন্ধান করুন। -> **দ্রষ্টব্য:** এই প্রশিক্ষণে GitHub মডেল এবং Azure OpenAI উভয়ই ব্যবহার করা হয়। [দ্রুত শুরু](00-quick-start/README.md) মডিউল GitHub মডেল ব্যবহার করে (Azure সাবস্ক্রিপশন প্রয়োজন নেই), যখন মডিউল ১-৫ Azure OpenAI ব্যবহার করে। যদি আপনার না থাকে তবে [FREE Azure অ্যাকাউন্ট](https://aka.ms/azure-free-account) দিয়ে শুরু করুন। +> **দ্রষ্টব্য:** এই প্রশিক্ষণটি Azure OpenAI ব্যবহার করে। যদি আপনি আগে থেকে না থাকেন তবে একটি [FREE Azure account](https://aka.ms/azure-free-account) নিয়ে শুরু করুন। -## GitHub Copilot এর সাথে শিক্ষালাভ +## GitHub Copilot এর মাধ্যমে শেখা -দ্রুত কোডিং শুরু করতে, GitHub Codespace বা আপনার স্থানীয় IDE-তে এই প্রকল্পটি devcontainer সহ খুলুন। এই কোর্সের devcontainer ইতোমধ্যে GitHub Copilot নিয়ে AI পেয়ার প্রোগ্রামিং এর জন্য প্রস্তুত করা হয়েছে। +দ্রুত কোডিং শুরু করতে, এই প্রোজেক্টটি GitHub Codespace অথবা আপনার স্থানীয় IDE তে devcontainer ব্যবহার করে খুলুন। এই কোর্সে ব্যবহৃত devcontainer পূর্বে GitHub Copilot দ্বারা AI জোড়া প্রোগ্রামিং এর জন্য কনফিগার করা আছে। -প্রতিটি কোড উদাহরণে GitHub Copilot কে জিজ্ঞাসা করার জন্য প্রস্তাবিত প্রশ্ন অন্তর্ভুক্ত আছে যা আপনার বোঝাপড়া গভীর করবে। 💡/🤖 প্রবণতা জন্য খুঁজুন: +প্রতিটি কোড উদাহরণ সহ প্রস্তাবিত প্রশ্নগুলিও থাকে যেগুলো GitHub Copilot কে জিজ্ঞাসা করে আপনার বোধগম্যতা গভীর করতে পারেন। 💡/🤖 প্রম্পটগুলোর জন্য খুঁজুন: -- **জাভা ফাইল হেডার** - প্রতিটি উদাহরণের জন্য নির্দিষ্ট প্রশ্ন -- **মডিউল README** - কোড উদাহরণের পরে অনুসন্ধানের প্রশ্ন +- **জাভা ফাইল হেডার** - প্রতিটি উদাহরণের নির্দিষ্ট প্রশ্ন +- **মডিউল README গুলো** - কোড উদাহরণের পরে অনুসন্ধান প্রম্পট -**কিভাবে ব্যবহার করবেন:** যেকোন কোড ফাইল খুলুন এবং Copilot কে প্রস্তাবিত প্রশ্ন করুন। এটি সম্পূর্ণ কোডবেসের প্রেক্ষাপট ধরে রেখেছে এবং ব্যাখ্যা, সম্প্রসারণ এবং বিকল্প প্রস্তাব করতে পারে। - -আরও জানতে চান? [কোপাইলট ফর AI পেয়ার প্রোগ্রামিং](https://aka.ms/GitHubCopilotAI) দেখুন। +**কিভাবে ব্যবহার করবেন:** যেকোনো কোড ফাইল খুলুন এবং প্রস্তাবিত প্রশ্নগুলো Copilot কে জিজ্ঞাসা করুন। এটি পুরো কোডবেসের প্রসঙ্গ জানে এবং ব্যাখ্যা, সম্প্রসারণ ও বিকল্প পরামর্শ দিতে সক্ষম। +আরও জানতে চান? দেখুন [AI Paired Programming এর জন্য Copilot](https://aka.ms/GitHubCopilotAI)। ## অতিরিক্ত সম্পদ @@ -115,36 +113,37 @@ LangChain4j এবং Azure OpenAI GPT-5.2 দিয়ে AI অ্যাপ্ [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![শুরুকারীদের জন্য সাইবারসিকিউরিটি](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![শুরুকারীদের জন্য ওয়েব ডেভেলপমেন্ট](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![শুরুকারীদের জন্য ইওটি](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![শুরুকারীদের জন্য এক্সআর ডেভেলপমেন্ট](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) ---- +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) -### কোপাইলট সিরিজ -[![কোপাইলট ফর এআই-পেয়ার্ড প্রোগ্রামিং](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![কোপাইলট ফর C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![কোপাইলট অ্যাডভেঞ্চার](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +--- + +### কপাইলট সিরিজ +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## সাহায্য গ্রহণ +## সাহায্য পাওয়া -যদি আপনি আটকে যান বা AI অ্যাপ নির্মাণ সম্পর্কে কোন প্রশ্ন থাকে, তাহলে যোগ দিন: +যদি আপনি আটকে যান বা AI অ্যাপ তৈরি করার বিষয়ে কোনও প্রশ্ন থাকে, যোগ দিন: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -যদি আপনি প্রোডাক্ট ফিডব্যাক বা ত্রুটি সম্পর্কে জানাতে চান, তাহলে যান: +যদি আপনার পণ্য প্রতিক্রিয়া বা ত্রুটি থাকে, নির্মাণ করার সময় এখানে যান: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## লাইসেন্স -MIT লাইসেন্স - বিস্তারিত জানতে দেখুন [LICENSE](../../LICENSE) ফাইল। +MIT লাইসেন্স - বিস্তারিত দেখতে [LICENSE](../../LICENSE) ফাইল দেখুন। --- -**অস্বীকৃতি**: -এই নথি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। আমরা সঠিকতার জন্য চেষ্টা করি, তবে অনুগ্রহ করে জানুন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। প্রকৃত নথিটি তার নিজ ভাষায় প্রাধান্যপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য, পেশাদার মানুষের দ্বারা করা অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে সৃষ্ট কোনো ভুল ধারণা বা ভুল ব্যাখ্যার জন্য আমরা দায়ী নই। +**অস্বীকৃতি**: +এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা শুদ্ধতার জন্য চেষ্টা করি, অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার স্বভাষায় কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে প্রয়োজনীয় ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই। \ No newline at end of file diff --git a/translations/bn/docs/GLOSSARY.md b/translations/bn/docs/GLOSSARY.md index ac59c4f91..8cf40fa9d 100644 --- a/translations/bn/docs/GLOSSARY.md +++ b/translations/bn/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j টার্ম সংজ্ঞা +# LangChain4j শব্দকোষ -## বিষয়সূচি +## সূচিপত্র -- [মূল ধারণাসমূহ](../../../docs) -- [LangChain4j উপাদানসমূহ](../../../docs) -- [AI/ML ধারণা](../../../docs) -- [গার্ডরেইলস](../../../docs) -- [প্রম্পট ইঞ্জিনিয়ারিং](../../../docs) -- [RAG (রিটারিভাল-অগমেন্টেড জেনারেশন)](../../../docs) -- [এজেন্ট এবং টুলস](../../../docs) -- [এজেন্টিক মডিউল](../../../docs) -- [মডেল কনটেক্সট প্রোটোকল (MCP)](../../../docs) -- [আজুর সার্ভিসসমূহ](../../../docs) -- [পরীক্ষা এবং উন্নয়ন](../../../docs) +- [কোর ধারণা](#কোর-ধারণা) +- [LangChain4j উপাদানসমূহ](#langchain4j-উপাদানসমূহ) +- [AI/ML ধারণা](#aiml-ধারণা) +- [গার্ডরেলস](#গার্ডরেলস) +- [প্রম্পট ইঞ্জিনিয়ারিং](#prompt-engineering---module-02) +- [RAG (রিট্রিভাল-অগমেন্টেড জেনারেশন)](#rag-retrieval-augmented-generation---module-03) +- [এজেন্ট এবং সরঞ্জামসমূহ](#agents-and-tools---module-04) +- [এজেন্টিক মডিউল](#agentic-module---module-05) +- [মডেল কনটেক্সট প্রোটোকল (MCP)](#model-context-protocol-mcp---module-05) +- [আজুর সেবা](#azure-services---module-01) +- [পরীক্ষা ও উন্নয়ন](#testing-and-development---testing-guide) -কোর্স জুড়ে ব্যবহৃত শব্দ ও ধারণার জন্য দ্রুত রেফারেন্স। +কোর্স জুড়ে ব্যবহৃত শব্দ এবং ধারণাগুলির দ্রুত রেফারেন্স। -## মূল ধারণাসমূহ +## কোর ধারণা -**AI Agent** - এমন সিস্টেম যা AI ব্যবহার করে স্বয়ংক্রিয়ভাবে যুক্তি প্রয়োগ ও কাজ করে। [মডিউল 04](../04-tools/README.md) +**AI Agent** - এমন সিস্টেম যা AI ব্যবহার করে যুক্তি করে এবং স্বায়ত্তশাসিতভাবে কাজ করে। [Module 04](../04-tools/README.md) -**Chain** - অপারেশনের ধারাবাহিকতা যেখানে আউটপুট পরবর্তী ধাপে প্রবাহিত হয়। +**Chain** - অপারেশনগুলোর ক্রম যেখানে আউটপুট পরবর্তী ধাপে ইনপুট হিসাবে ব্যবহৃত হয়। -**Chunking** - ডকুমেন্টকে ছোট ছোট অংশে ভাগ করা। সাধারণত: ৩০০-৫০০ টোকেন ওভারল্যাপ সহ। [মডিউল 03](../03-rag/README.md) +**Chunking** - ডকুমেন্টগুলোকে ছোট ছোট অংশে ভাগ করা। সাধারণত: ৩০০-৫০০ টোকেন ওভারল্যাপের সাথে। [Module 03](../03-rag/README.md) -**Context Window** - মডেল সর্বোচ্চ কতটোকেন প্রক্রিয়াজাত করতে পারে। GPT-5.2: ৪০০কে টোকেন (২৭২কে ইনপুট পর্যন্ত, ১২৮কে আউটপুট)। +**Context Window** - সর্বাধিক টোকেন যা একটি মডেল প্রসেস করতে পারে। GPT-5.2: ৪০০কে টোকেন (২৭২কে ইনপুট পর্যন্ত, ১২৮কে আউটপুট)। -**Embeddings** - টেক্সটের অর্থকে সংখ্যা রূপে উপস্থাপন করে ভেক্টর। [মডিউল 03](../03-rag/README.md) +**Embeddings** - টেক্সটের অর্থ প্রকাশকারী সংখ্যাসূচক ভেক্টর। [Module 03](../03-rag/README.md) -**Function Calling** - মডেল বাহ্যিক ফাংশন কল করার জন্য গঠনকৃত অনুরোধ তৈরি করে। [মডিউল 04](../04-tools/README.md) +**Function Calling** - মডেল কাঠামোবদ্ধ অনুরোধ তৈরি করে বাহ্যিক ফাংশন কল করার জন্য। [Module 04](../04-tools/README.md) -**Hallucination** - যখন মডেল ভুল কিন্তু বিশ্বাসযোগ্য তথ্য তৈরি করে। +**Hallucination** - মডেলগুলি যখন ভুল কিন্তু বিশ্বাসযোগ্য তথ্য তৈরি করে। -**Prompt** - ভাষা মডেলে ইনপুট টেক্সট। [মডিউল 02](../02-prompt-engineering/README.md) +**Prompt** - ভাষা মডেলের ইনপুট টেক্সট। [Module 02](../02-prompt-engineering/README.md) -**Semantic Search** - এমবেডিং ব্যবহার করে অর্থ অনুসারে অনুসন্ধান, কীওয়ার্ড নয়। [মডিউল 03](../03-rag/README.md) +**Semantic Search** - অর্থ অনুযায়ী অনুসন্ধান যা কীওয়ার্ড নয়, এমবেডিং ব্যবহার করে। [Module 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: স্মৃতি নেই। Stateful: কথোপকথনের ইতিহাস রক্ষা করে। [মডিউল 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: কোনো মেমোরি নেই। Stateful: কথোপকথনের ইতিহাস সংরক্ষণ করে। [Module 01](../01-introduction/README.md) -**Tokens** - মডেল প্রক্রিয়াজাত করার মৌলিক টেক্সট ইউনিট। খরচ ও সীমা প্রভাবিত করে। [মডিউল 01](../01-introduction/README.md) +**Tokens** - মডেলগুলো যেসব মৌলিক টেক্সট ইউনিট প্রক্রিয়া করে। খরচ এবং সীমাতে প্রভাব ফেলে। [Module 01](../01-introduction/README.md) -**Tool Chaining** - ধারাবাহিক টুল কার্যক্রম যেখানে আউটপুট পরবর্তী কলের জন্য তথ্য দেয়। [মডিউল 04](../04-tools/README.md) +**Tool Chaining** - ধারাবাহিক সরঞ্জাম কার্যক্রম যেখানে আউটপুট পরবর্তী কলের তথ্য দেয়। [Module 04](../04-tools/README.md) ## LangChain4j উপাদানসমূহ **AiServices** - টাইপ-সেফ AI সেবা ইন্টারফেস তৈরি করে। -**OpenAiOfficialChatModel** - OpenAI এবং Azure OpenAI মডেলের একটি একীভূত ক্লায়েন্ট। +**OpenAiOfficialChatModel** - OpenAI এবং Azure OpenAI মডেলগুলোর জন্য একীকৃত ক্লায়েন্ট। -**OpenAiOfficialEmbeddingModel** - OpenAI Official ক্লায়েন্ট ব্যবহার করে এমবেডিং তৈরি করে (OpenAI ও Azure OpenAI উভয় সমর্থন করে)। +**OpenAiOfficialEmbeddingModel** - OpenAI অফিসিয়াল ক্লায়েন্ট ব্যবহার করে এমবেডিং তৈরি করে (OpenAI এবং Azure OpenAI উভয় সমর্থিত)। -**ChatModel** - ভাষা মডেলের মুখ্য ইন্টারফেস। +**ChatModel** - ভাষা মডেলগুলোর জন্য মূল ইন্টারফেস। **ChatMemory** - কথোপকথনের ইতিহাস সংরক্ষণ করে। -**ContentRetriever** - RAG এর জন্য প্রাসঙ্গিক ডকুমেন্ট টুকরা খুঁজে বের করে। +**ContentRetriever** - RAG এর জন্য প্রাসঙ্গিক ডকুমেন্ট চাঙ্ক খুঁজে বের করে। -**DocumentSplitter** - ডকুমেন্ট টুকরা ভাগ করে। +**DocumentSplitter** - ডকুমেন্টগুলোকে চাঙ্কে ভাগ করে। -**EmbeddingModel** - টেক্সটকে সংখ্যাগত ভেক্টরে রূপান্তর করে। +**EmbeddingModel** - টেক্সটকে সংখ্যাসূচক ভেক্টরে রূপান্তর করে। **EmbeddingStore** - এমবেডিং সংরক্ষণ ও পুনরুদ্ধার করে। -**MessageWindowChatMemory** - সাম্প্রতিক বার্তার একটি স্লাইডিং উইন্ডো রক্ষা করে। +**MessageWindowChatMemory** - সাম্প্রতিক বার্তাগুলোর স্লাইডিং উইন্ডো বজায় রাখে। -**PromptTemplate** - `{{variable}}` প্লেসহোল্ডার সহ পুনর্ব্যবহারযোগ্য প্রম্পট তৈরি করে। +**PromptTemplate** - `{{variable}}` প্লেসহোল্ডারসহ পুনরায় ব্যবহারযোগ্য প্রম্পট তৈরি করে। -**TextSegment** - মেটাডেটাসহ টেক্সট টুকরা। RAG এ ব্যবহৃত। +**TextSegment** - মেটাডেটাসহ টেক্সট অংশ। RAG এ ব্যবহৃত। -**ToolExecutionRequest** - টুল নির্বাহের অনুরোধ উপস্থাপন করে। +**ToolExecutionRequest** - সরঞ্জাম কার্যকলাপের অনুরোধ উপস্থাপন করে। -**UserMessage / AiMessage / SystemMessage** - কথোপকথন বার্তার ধরণ। +**UserMessage / AiMessage / SystemMessage** - কথোপকথনের বার্তার ধরন। ## AI/ML ধারণা -**Few-Shot Learning** - প্রম্পটে উদাহরণ প্রদান। [মডিউল 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - প্রম্পটে উদাহরণ দেয়া। [Module 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - বিশাল টেক্সট ডেটাসেটে প্রশিক্ষিত AI মডেল। +**Large Language Model (LLM)** - বিশাল টেক্সট ডেটাতে প্রশিক্ষিত AI মডেল। -**Reasoning Effort** - GPT-5.2 এর এমন একটি প্যারামিটার যা চিন্তার গভীরতা নিয়ন্ত্রণ করে। [মডিউল 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - GPT-5.2 প্যারামিটার যা চিন্তার গভীরতা নিয়ন্ত্রণ করে। [Module 02](../02-prompt-engineering/README.md) -**Temperature** - আউটপুটের এলোমেলো পরিমাণ নিয়ন্ত্রণ করে। কম=নির্ধারিত, বেশি=সৃজনশীল। +**Temperature** - আউটপুটের র‍্যান্ডমনেস নিয়ন্ত্রণ করে। কম=নির্ধারিত, বেশি=সৃষ্টিশীল। -**Vector Database** - এমবেডিং সংরক্ষণের জন্য বিশেষায়িত ডাটাবেস। [মডিউল 03](../03-rag/README.md) +**Vector Database** - এমবেডিংয়ের জন্য বিশেষায়িত ডেটাবেজ। [Module 03](../03-rag/README.md) -**Zero-Shot Learning** - উদাহরণ ছাড়া কাজ করা। [মডিউল 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - উদাহরণ ছাড়াই কাজ করা। [Module 02](../02-prompt-engineering/README.md) -## গার্ডরেইলস - [মডিউল 00](../00-quick-start/README.md) +## গার্ডরেলস -**Defense in Depth** - একাধিক স্তরের নিরাপত্তা পদ্ধতি, যেটি অ্যাপ্লিকেশন-স্তরের গার্ডরেইলস ও প্রোভাইডার সেফটি ফিল্টার একত্র করে। +**Defense in Depth** - মাল্টি-লেয়ার সিকিউরিটি অ্যাপ্রোচ যা অ্যাপ্লিকেশন-স্তরের গার্ডরেলস ও প্রোভাইডার সুরক্ষা ফিল্টার মিলায়। -**Hard Block** - গুরুতর বিষয়বস্তুর লঙ্ঘনের জন্য প্রোভাইডার HTTP ৪০০ ত্রুটি দেয়। +**Hard Block** - গুরুতর কনটেন্ট লঙ্ঘনের জন্য প্রোভাইডার HTTP 400 ত্রুটি ফেলে। -**InputGuardrail** - LLM এর কাছে পৌঁছানোর আগে ব্যবহারকারীর ইনপুট যাচাইয়ের LangChain4j ইন্টারফেস। ক্ষতিকারক প্রম্পট আগেই ব্লক করে খরচ ও বিলম্ব সাশ্রয় করে। +**InputGuardrail** - LangChain4j ইন্টারফেস যা ব্যবহারকারীর ইনপুট যাচাই করে LLM পৌঁছানোর আগে। ক্ষতিকারক প্রম্পট অগ্রিম বন্ধ করে খরচ ও বিলম্ব বাঁচায়। -**InputGuardrailResult** - গার্ডরেইল যাচাইয়ের রিটার্ন টাইপ: `success()` বা `fatal("reason")`। +**InputGuardrailResult** - গার্ডরেল যাচাইয়ের রিটার্ন টাইপ: `success()` অথবা `fatal("reason")`। -**OutputGuardrail** - AI উত্তর ফিরে দেওয়ার আগে যাচাইয়ের ইন্টারফেস। +**OutputGuardrail** - AI উত্তর যাচাই করে ব্যবহারকারীর কাছে ফেরত দেওয়ার আগে। -**Provider Safety Filters** - AI প্রোভাইডার (যেমন GitHub Models) দ্বারা নির্মিত কন্টেন্ট ফিল্টার যা API স্তরে লঙ্ঘন সনাক্ত করে। +**Provider Safety Filters** - AI প্রোভাইডার (যেমন Azure OpenAI) থেকে বিল্ট-ইন কনটেন্ট ফিল্টার যা API স্তরে লঙ্ঘন আটকায়। -**Soft Refusal** - মডেল বিনা ত্রুটি দেখিয়ে নম্রভাবে উওর দিতে অস্বীকৃতি জানায়। +**Soft Refusal** - মডেল বিনীতভাবে উত্তর দিতে অস্বীকার করে ত্রুটি ছাড়াই। -## প্রম্পট ইঞ্জিনিয়ারিং - [মডিউল 02](../02-prompt-engineering/README.md) +## প্রম্পট ইঞ্জিনিয়ারিং - [Module 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - ধাপে ধাপে যুক্তি প্রয়োগ করে উন্নত নির্ভুলতা। +**Chain-of-Thought** - ধাপে ধাপে যুক্তি যা সঠিকতা বাড়ায়। -**Constrained Output** - নির্দিষ্ট ফর্ম্যাট বা গঠন বাধ্যতামূলক করা। +**Constrained Output** - নির্দিষ্ট ফরম্যাট বা কাঠামো বলবৎ রাখা। -**High Eagerness** - GPT-5.2 এর প্রচুর যুক্তি প্রয়োগের প্যাটার্ন। +**High Eagerness** - GPT-5.2 প্যাটার্ন যা গভীর যুক্তি তৈরি করে। -**Low Eagerness** - GPT-5.2 এর দ্রুত উত্তর প্রদানের প্যাটার্ন। +**Low Eagerness** - GPT-5.2 প্যাটার্ন যা দ্রুত উত্তর দেয়। -**Multi-Turn Conversation** - একাধিক পালার মধ্যে প্রাসঙ্গিকতা বজায় রাখা। +**Multi-Turn Conversation** - কথোপকথনের প্রসঙ্গ রক্ষা। -**Role-Based Prompting** - সিস্টেম মেসেজের মাধ্যমে মডেলের চরিত্র নির্ধারণ। +**Role-Based Prompting** - সিস্টেম মেসেজের মাধ্যমে মডেল ব্যক্তিত্ব সেট করা। -**Self-Reflection** - মডেল তার আউটপুট মূল্যায়ন ও উন্নত করে। +**Self-Reflection** - মডেল নিজের আউটপুট মূল্যায়ন ও উন্নতি করে। -**Structured Analysis** - সুনির্দিষ্ট মূল্যায়ন কাঠামো। +**Structured Analysis** - নির্দিষ্ট মূল্যায়ন কাঠামো। -**Task Execution Pattern** - পরিকল্পনা → প্রয়োগ → সারাংশ। +**Task Execution Pattern** - পরিকল্পনা → সম্পাদন → সারসংক্ষেপ। -## RAG (রিটারিভাল-অগমেন্টেড জেনারেশন) - [মডিউল 03](../03-rag/README.md) +## RAG (রিট্রিভাল-অগমেন্টেড জেনারেশন) - [Module 03](../03-rag/README.md) -**Document Processing Pipeline** - লোড → টুকরা → এমবেড → সংরক্ষণ। +**Document Processing Pipeline** - লোড → চাঙ্ক → এমবেড → সংরক্ষণ। -**In-Memory Embedding Store** - পরীক্ষা করার জন্য অস্থায়ী সংরক্ষণ। +**In-Memory Embedding Store** - পরীক্ষার জন্য অস্থায়ী স্টোরেজ। -**RAG** - রিটারিভালকে জেনারেশনের সাথে মিলিয়ে উত্তর ভিত্তিক করে। +**RAG** - রিট্রিভাল ও জেনারেশন একত্রে ব্যবহার করে উত্তর ভিত্তি গড়ে তোলে। -**Similarity Score** - অর্থগত সাদৃশ্যের পরিমাপ (০-১)। +**Similarity Score** - সেমান্টিক সাদৃশ্যের পরিমাপ (০-১)। -**Source Reference** - সংগৃহীত বিষয়বস্তু সম্পর্কিত মেটাডেটা। +**Source Reference** - পুনরুদ্ধারকৃত বিষয়বস্তুর মেটাডেটা। -## এজেন্ট এবং টুলস - [মডিউল 04](../04-tools/README.md) +## এজেন্ট এবং সরঞ্জামসমূহ - [Module 04](../04-tools/README.md) -**@Tool Annotation** - জাভা মেথডকে AI-কলেবল টুল হিসেবে মার্ক করে। +**@Tool Annotation** - Java মেথডকে AI-কলে সক্ষম সরঞ্জাম হিসেবে চিহ্নিত করে। -**ReAct Pattern** - যুক্তি → কাজ → পর্যবেক্ষণ → পুনরাবৃত্তি। +**ReAct Pattern** - যুক্তি → কর্ম → পর্যবেক্ষণ → পুনরাবৃত্তি। -**Session Management** - বিভিন্ন ব্যবহারকারীর জন্য আলাদা প্রসঙ্গ। +**Session Management** - বিভিন্ন ব্যবহারকারীর জন্য পৃথক প্রসঙ্গ। -**Tool** - এমন একটি ফাংশন যা AI এজেন্ট কল করতে পারে। +**Tool** - একটি ফাংশন যা AI এজেন্ট কল করতে পারে। -**Tool Description** - টুলের উদ্দেশ্য ও প্যারামিটার ডকুমেন্টেশন। +**Tool Description** - সরঞ্জামের উদ্দেশ্য ও প্যারামিটারসমূহের দলিল। -## এজেন্টিক মডিউল - [মডিউল 05](../05-mcp/README.md) +## এজেন্টিক মডিউল - [Module 05](../05-mcp/README.md) -**@Agent Annotation** - ইন্টারফেসকে এজেন্ট হিসেবে মার্ক করে যার মধ্যে আচরণের ঘোষণা থাকে। +**@Agent Annotation** - AI এজেন্ট হিসাবে ইন্টারফেস চিহ্নিত করে ডিক্লারেটিভ বিহেভিয়ার সংজ্ঞা সহ। -**Agent Listener** - `beforeAgentInvocation()` ও `afterAgentInvocation()` মাধ্যমে এজেন্ট কার্যক্রম পর্যবেক্ষণের হুক। +**Agent Listener** - এজেন্ট কার্যক্রম পর্যবেক্ষণের জন্য হুক `beforeAgentInvocation()` এবং `afterAgentInvocation()` এর মাধ্যমে। -**Agentic Scope** - শেয়ারড মেমোরি যেখানে এজেন্টরা আউটপুট সংরক্ষণ করে যা পরবর্তী এজেন্ট ব্যবহার করে। +**Agentic Scope** - শেয়ার করা মেমোরি যেখানে এজেন্টগণ আউটপুট সংরক্ষণ করে `outputKey` ব্যবহার করে পরবর্তী এজেন্টদের জন্য। -**AgenticServices** - `agentBuilder()` ও `supervisorBuilder()` ব্যবহার করে এজেন্ট তৈরি করার ফ্যাক্টরি। +**AgenticServices** - `agentBuilder()` এবং `supervisorBuilder()` ব্যবহার করে এজেন্ট তৈরি করার ফ্যাক্টরি। -**Conditional Workflow** - শর্ত অনুসারে আলাদা বিশেষজ্ঞ এজেন্টে রুট নির্ধারণ। +**Conditional Workflow** - শর্ত অনুযায়ী আলাদা বিশেষজ্ঞ এজেন্টদের মধ্যে রুট নির্ধারণ। -**Human-in-the-Loop** - অনুমোদন বা বিষয়বস্তু পর্যালোচনার জন্য মানুষের চেকপয়েন্ট যুক্ত ওয়ার্কফ্লো প্যাটার্ন। +**Human-in-the-Loop** - মানব যাচাইকরণ বা বিষয়বস্তু পর্যালোচনার জন্য চেকপয়েন্টসহ ওয়ার্কফ্লো প্যাটার্ন। -**langchain4j-agentic** - ঘোষণামূলক এজেন্ট নির্মাণের জন্য মাভেন ডিপেনডেন্সি (প্রায়োগিক)। +**langchain4j-agentic** - ডিক্লারেটিভ এজেন্ট বিল্ডিংয়ের জন্য মেভেন ডিপেন্ডেন্সি (প্রায়োগিক)। -**Loop Workflow** - কখনও একটি শর্ত পূরণ না হওয়া পর্যন্ত এজেন্ট পুনরাবৃত্তি (যেমন: গুণগত মান স্কোর ≥ ০.৮)। +**Loop Workflow** - একটি শর্ত পূরণ না হওয়া পর্যন্ত এজেন্ট কার্যক্রম পুনরাবৃত্তি করা (যেমন গুণমান স্কোর ≥ 0.৮)। -**outputKey** - Agentic Scope এ আউটপুট কোথায় সংরক্ষিত হবে তা নির্ধারণকারী এজেন্ট এনোটেশন প্যারামিটার। +**outputKey** - এজেন্ট নোটেশন প্যারামিটার যা Agentic Scope-এ ফলাফল সংরক্ষণের জায়গা নির্ধারণ করে। -**Parallel Workflow** - স্বাধীন কাজের জন্য একসাথে একাধিক এজেন্ট চালানো। +**Parallel Workflow** - স্বাধীন কাজের জন্য একাধিক এজেন্ট একসাথে চালানো। -**Response Strategy** - সুপারভাইজার চূড়ান্ত উত্তর গঠনের পদ্ধতি: LAST, SUMMARY, অথবা SCORED। +**Response Strategy** - সুপারভাইজার কিভাবে চূড়ান্ত উত্তর গঠন করে: LAST, SUMMARY, অথবা SCORED। -**Sequential Workflow** - ধারাবাহিকভাবে এজেন্ট কার্যকর করা যেখানে আউটপুট পরবর্তী ধাপে প্রবাহিত হয়। +**Sequential Workflow** - এজেন্টগুলোকে ক্রম অনুসারে চালানো যেখানে আউটপুট পরবর্তী ধাপে প্রবাহিত হয়। -**Supervisor Agent Pattern** - উন্নত এজেন্টিক প্যাটার্ন যেখানে সুপারভাইজার LLM নিদিষ্ট করে কোন সাব-এজেন্টকে কল করতে হবে। +**Supervisor Agent Pattern** - উন্নত এজেন্টিক প্যাটার্ন যেখানে সুপারভাইজার LLM চলবে কোন সাব-এজেন্ট কল করবে তা গতিশীলভাবে নির্ধারণ করে। -## মডেল কনটেক্সট প্রোটোকল (MCP) - [মডিউল 05](../05-mcp/README.md) +## মডেল কনটেক্সট প্রোটোকল (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j এ MCP ইন্টিগ্রেশনের জন্য মাভেন ডিপেনডেন্সি। +**langchain4j-mcp** - LangChain4j-এ MCP ইন্টিগ্রেশনের জন্য মেভেন ডিপেন্ডেন্সি। -**MCP** - মডেল কনটেক্সট প্রোটোকল: AI অ্যাপগুলোকে বাহ্যিক টুলের সাথে সংযুক্ত করার মান। একবার তৈরি, সর্বত্র ব্যবহার। +**MCP** - Model Context Protocol: AI অ্যাপসকে বাহ্যিক সরঞ্জামের সাথে সংযুক্ত করার স্ট্যান্ডার্ড। একবার তৈরি করুন, সর্বত্র ব্যবহার করুন। -**MCP Client** - MCP সার্ভারে সংযুক্ত হয়ে টুল আবিষ্কার ও ব্যবহারের অ্যাপ্লিকেশন। +**MCP Client** - MCP সার্ভারে সংযোগ স্থাপন করে সরঞ্জাম আবিষ্কার ও ব্যবহার করে এমন অ্যাপ্লিকেশন। -**MCP Server** - MCP ব্যবহার করে পরিষ্কার বর্ণনা এবং প্যারামিটার স্কিমাসহ টুল প্রদর্শন সেবা। +**MCP Server** - MCP ব্যবহার করে স্পষ্ট বর্ণনা ও প্যারামিটার স্কিমাসহ সরঞ্জাম এক্সপোজ করে এমন সেবা। -**McpToolProvider** - LangChain4j উপাদান যা MCP টুলগুলোকে AI সেবা ও এজেন্টে ব্যবহারের জন্য কম্পোজ করে। +**McpToolProvider** - LangChain4j উপাদান যা MCP সরঞ্জামগুলোকে AI সেবা ও এজেন্টে ব্যবহারের জন্য র‍্যাপ করে। -**McpTransport** - MCP যোগাযোগের জন্য ইন্টারফেস। বাস্তবায়নসমূহ: Stdio এবং HTTP। +**McpTransport** - MCP যোগাযোগের ইন্টারফেস। বাস্তবায়নের মধ্যে রয়েছে Stdio ও HTTP। -**Stdio Transport** - স্থানীয় প্রসেসের জন্য stdin/stdout ট্রান্সপোর্ট। ফাইল সিস্টেম অ্যাক্সেস বা CLI টুলসের জন্য উপযুক্ত। +**Stdio Transport** - স্থানীয় প্রসেস পরিবহন stdin/stdout মাধ্যমে। ফাইল সিস্টেম অ্যাক্সেস বা কমান্ড-লাইন সরঞ্জামের জন্য কার্যকর। -**StdioMcpTransport** - LangChain4j বাস্তবায়ন যা সাবপ্রসেস হিসেবে MCP সার্ভার চালায়। +**StdioMcpTransport** - LangChain4j বাস্তবায়ন যা সাবপ্রসেস হিসেবে MCP সার্ভার চালায়। -**Tool Discovery** - ক্লায়েন্ট টুলের বর্ণনা ও স্কিমাসহ সার্ভারে কুয়েরি করে উপলব্ধ টুল জানতে পারে। +**Tool Discovery** - ক্লায়েন্ট সার্ভারকে প্রশ্ন করে উপলব্ধ সরঞ্জামের বিবরণ ও স্কিমাস নেয়। -## আজুর সার্ভিসসমূহ - [মডিউল 01](../01-introduction/README.md) +## আজুর সেবা - [Module 01](../01-introduction/README.md) -**Azure AI Search** - ভেক্টর সক্ষমতা সম্বলিত ক্লাউড অনুসন্ধান। [মডিউল 03](../03-rag/README.md) +**Azure AI Search** - ভেক্টর সক্ষমতা সহ ক্লাউড অনুসন্ধান। [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - আজুর সম্পদ মোতায়েন করে। +**Azure Developer CLI (azd)** - আজুর রিসোর্স ডিপ্লয় করে। **Azure OpenAI** - মাইক্রোসফটের এন্টারপ্রাইজ AI সেবা। -**Bicep** - আজুর অবকাঠামো-অ্যাস-কোড ভাষা। [অবকাঠামো গাইড](../01-introduction/infra/README.md) +**Bicep** - আজুর ইনফ্রাস্ট্রাকচার-অ্যাজ-কোড ভাষা। [Infrastructure Guide](../01-introduction/infra/README.md) -**Deployment Name** - আজুরে মডেল মোতায়েনের নাম। +**Deployment Name** - আজুরে মডেল ডিপ্লয়মেন্টের নাম। -**GPT-5.2** - সর্বশেষ OpenAI মডেল যার মধ্যে যুক্তি নিয়ন্ত্রণ আছে। [মডিউল 02](../02-prompt-engineering/README.md) +**GPT-5.2** - reasoning নিয়ন্ত্রণযোগ্য সর্বশেষ OpenAI মডেল। [Module 02](../02-prompt-engineering/README.md) -## পরীক্ষা এবং উন্নয়ন - [পরীক্ষা গাইড](TESTING.md) +## পরীক্ষা ও উন্নয়ন - [Testing Guide](TESTING.md) -**Dev Container** - কনটেইনারভিত্তিক উন্নয়ন পরিবেশ। [কনফিগারেশন](../../../.devcontainer/devcontainer.json) +**Dev Container** - কন্টেইনার ভিত্তিক উন্নয়ন পরিবেশ। [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - বিনামূল্যের AI মডেল প্লে গ্রাউন্ড। [মডিউল 00](../00-quick-start/README.md) +**In-Memory Testing** - মেমোরি-ভিত্তিক স্টোরেজে পরীক্ষা। -**In-Memory Testing** - ইন-মেমোরি স্টোরেজ ব্যবহার করে পরীক্ষা। +**Integration Testing** - বাস্তব অবকাঠামোর সাথে পরীক্ষা। -**Integration Testing** - বাস্তব অবকাঠামো ব্যবহার করে পরীক্ষা। +**Maven** - Java বিল্ড অটোমেশন টুল। -**Maven** - জাভা বিল্ড অটোমেশন টুল। +**Mockito** - Java মকিং ফ্রেমওয়ার্ক। -**Mockito** - জাভা মকিং ফ্রেমওয়ার্ক। - -**Spring Boot** - জাভা অ্যাপ্লিকেশন ফ্রেমওয়ার্ক। [মডিউল 01](../01-introduction/README.md) +**Spring Boot** - Java অ্যাপ্লিকেশন ফ্রেমওয়ার্ক। [Module 01](../01-introduction/README.md) --- -**দ্রষ্টব্য**: -এই নথিটি AI অনুবাদ সেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহারের মাধ্যমে অনূদিত হয়েছে। আমরা যথাসাধ্য সঠিকতার জন্য চেষ্টা করি, তবে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসত্যতার সম্ভবনা থাকতে পারে। মূল নথি তার স্থানীয় ভাষায়েই সর্বোচ্চ কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচনা করা উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ গ্রহণ করার পরামর্শ দেওয়া হয়। এই অনুবাদের ব্যবহারে সৃষ্ট কোনো ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়ী নয়। +**অস্বীকৃতি**: +এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা শুদ্ধতার জন্য চেষ্টা করি, অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার স্বভাষায় কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে প্রয়োজনীয় ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই। \ No newline at end of file diff --git a/translations/bn/docs/TESTING.md b/translations/bn/docs/TESTING.md index 49d2afc84..16c9d02c3 100644 --- a/translations/bn/docs/TESTING.md +++ b/translations/bn/docs/TESTING.md @@ -1,20 +1,20 @@ -# LangChain4j অ্যাপ্লিকেশন টেস্টিং +# LangChain4j অ্যাপ্লিকেশনগুলি পরীক্ষা করা -## বিষয়বস্তু +## বিষয়বস্তু সূচি -- [দ্রুত শুরু](../../../docs) -- [টেস্টগুলো কি ঢেকে রাখে](../../../docs) -- [টেস্ট চালানো](../../../docs) -- [VS কোডে টেস্ট চালানো](../../../docs) -- [টেস্টিং প্যাটার্নস](../../../docs) -- [টেস্টিং দর্শন](../../../docs) -- [পরবর্তী ধাপসমূহ](../../../docs) +- [দ্রুত শুরু](#দ্রুত-শুরু) +- [পরীক্ষাগুলো কি অন্তর্ভুক্ত করে](#পরীক্ষাগুলো-কি-অন্তর্ভুক্ত-করে) +- [পরীক্ষাগুলো চালানো](#পরীক্ষাগুলো-চালানো) +- [VS Code-এ পরীক্ষাগুলো চালানো](#vs-code-এ-পরীক্ষাগুলো-চালানো) +- [পরীক্ষার প্যাটার্নসমূহ](#পরীক্ষার-প্যাটার্নসমূহ) +- [পরীক্ষার দর্শন](#পরীক্ষার-দর্শন) +- [পরবর্তী ধাপসমূহ](#পরবর্তী-ধাপসমূহ) -এই গাইডটি আপনাকে এমন টেস্টগুলোর মাধ্যমে চালনা করে যা দেখায় কিভাবে API কী বা বাহ্যিক সার্ভিস ছাড়াই AI অ্যাপ্লিকেশনগুলো টেস্ট করতে হয়। +এই গাইডটি আপনাকে এমন পরীক্ষাগুলো দেখাবে যা API কী বা বাহ্যিক সার্ভিস ছাড়াই AI অ্যাপ্লিকেশনগুলি কিভাবে পরীক্ষা করতে হয় তা প্রদর্শন করে। ## দ্রুত শুরু -একটি কমান্ডে সব টেস্ট চালান: +একটি কমান্ড দিয়ে সকল পরীক্ষা চালান: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -যখন সব টেস্ট সফল হয়, আপনি নিচের স্ক্রিনশটের মতো আউটপুট দেখতে পাবেন — কোনো ব্যর্থতা ছাড়াই টেস্ট চলছে। +যখন সব পরীক্ষার ফলাফল পাস হয়, নিচের স্ক্রিনশটের মতো আউটপুট দেখতে পাবেন — পরীক্ষাগুলো শূন্য ত্রুটির সাথে চলছে। Successful Test Results -*সফল টেস্ট কার্যকরী হওয়া দেখাচ্ছে সবগুলো টেস্ট শূন্য ব্যর্থতা সহ পাস করছে* +*সফল পরীক্ষা চালানোর ফলাফল যেখানে সব পরীক্ষা শূন্য ত্রুটি নিয়ে সফল হয়েছে* -## টেস্টগুলো কি ঢেকে রাখে +## পরীক্ষাগুলো কি অন্তর্ভুক্ত করে -এই কোর্সটি ফোকাস করে **ইউনিট টেস্টস**-এ যা লোকালি চলে। প্রতিটি টেস্ট একটি নির্দিষ্ট LangChain4j ধারণাকে আলাদা করে প্রদর্শন করে। নিচের টেস্টিং পিরামিড দেখায় ইউনিট টেস্ট কোথায় ফিট হয় — এগুলো দ্রুত, নির্ভরযোগ্য ভিত্তি গঠন করে, যার উপর আপনার বাকি টেস্ট কৌশল তৈরি হয়। +এই কোর্সটি **একক ইউনিট পরীক্ষার** উপর ফোকাস করে যা স্থানীয়ভাবে চলে। প্রতিটি পরীক্ষা একটি LangChain4j ধারণা আলাদাভাবে প্রদর্শন করে। নিচের পরীক্ষার পিরামিড দেখায় যে ইউনিট পরীক্ষা কোথায় ফিট করে — এগুলো দ্রুত, নির্ভরযোগ্য ভিত্তি, যার উপর আপনার বাকি পরীক্ষা কৌশল গড়ে ওঠে। Testing Pyramid -*টেস্টিং পিরামিড ইউনিট টেস্ট (দ্রুত, পৃথক), ইন্টিগ্রেশন টেস্ট (বাস্তব কম্পোনেন্ট), এবং এন্ড-টু-এন্ড টেস্টের মধ্যে সামঞ্জস্য দেখাচ্ছে। এই প্রশিক্ষণে ইউনিট টেস্টিং অন্তর্ভুক্ত।* +*পরীক্ষার পিরামিড যা ইউনিট পরীক্ষা (দ্রুত, স্বতন্ত্র), ইন্টিগ্রেশন পরীক্ষা (বাস্তব উপাদান), এবং এন্ড-টু-এন্ড পরীক্ষা এর মধ্যে ভারসাম্য প্রদর্শন করে। এই প্রশিক্ষণ ইউনিট টেস্টিং আচ্ছাদন করে।* -| মডিউল | টেস্ট সংখ্যা | ফোকাস | প্রধান ফাইল | -|--------|-------|-------|-----------| -| **00 - দ্রুত শুরু** | 6 | প্রম্পট টেমপ্লেট এবং ভ্যারিয়েবল প্রতিস্থাপন | `SimpleQuickStartTest.java` | -| **01 - পরিচিতি** | 8 | কথোপকথন স্মৃতি ও স্টেটফুল চ্যাট | `SimpleConversationTest.java` | -| **02 - প্রম্পট ইঞ্জিনিয়ারিং** | 12 | GPT-5.2 প্যাটার্ন, আগ্রহের স্তর, কাঠামোগত আউটপুট | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | ডকুমেন্ট ইনজেশন, এম্বেডিংস, সাদৃশ্য অনুসন্ধান | `DocumentServiceTest.java` | -| **04 - টুলস** | 12 | ফাংশন কলিং এবং টুল চেইনিং | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | মডেল কনটেক্সট প্রটোকল উইথ স্টডিও ট্রান্সপোর্ট | `SimpleMcpTest.java` | +| মডিউল | পরীক্ষা সংখ্যা | ফোকাস | মূল ফাইলসমূহ | +|--------|---------------|--------|--------------| +| **01 - পরিচিতি** | ৮ | কথোপকথন স্মৃতি ও অবস্থা সম্পন্ন চ্যাট | `SimpleConversationTest.java` | +| **02 - প্রম্পট ইঞ্জিনিয়ারিং** | ১২ | GPT-5.2 প্যাটার্ন, আগ্রহ স্তর, গঠনমূলক আউটপুট | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | ১০ | ডকুমেন্ট ইনজেশন, এম্বেডিং, সাদৃশ্য অনুসন্ধান | `DocumentServiceTest.java` | +| **04 - টুলস** | ১২ | ফাংশন কলিং ও টুল চেইনিং | `SimpleToolsTest.java` | +| **05 - MCP** | ৮ | স্টডিও ট্রান্সপোর্টসহ মডেল কনটেক্সট প্রোটোকল | `SimpleMcpTest.java` | -## টেস্ট চালানো +## পরীক্ষাগুলো চালানো -**রুট থেকে সব টেস্ট চালান:** +**রুট থেকে সব পরীক্ষা চালান:** **Bash:** ```bash @@ -63,19 +62,19 @@ mvn test mvn --% test ``` -**নির্দিষ্ট মডিউলের টেস্ট চালান:** +**নির্দিষ্ট মডিউলের পরীক্ষাগুলো চালান:** **Bash:** ```bash cd 01-introduction && mvn test -# অথবা রুট থেকে +# বা রুট থেকে mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# অথবা মূল থেকে +# অথবা রুট থেকে mvn --% test -pl 01-introduction ``` @@ -91,7 +90,7 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**নির্দিষ্ট টেস্ট মেথড চালান:** +**নির্দিষ্ট একটি টেস্ট মেথড চালান:** **Bash:** ```bash @@ -100,37 +99,36 @@ mvn test -Dtest=SimpleConversationTest#কথোপকথনের ইতিহ **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#আলাপন ইতিহাস বজায় রাখা উচিত +mvn --% test -Dtest=SimpleConversationTest#কথোপকথন ইতিহাস বজায় রাখা উচিত ``` +## VS Code-এ পরীক্ষাগুলো চালানো -## VS কোডে টেস্ট চালানো - -যদি আপনি Visual Studio Code ব্যবহার করেন, Test Explorer আপনাকে একটি গ্রাফিক্যাল ইন্টারফেস দেয় টেস্ট চালানো এবং ডিবাগ করার জন্য। +আপনি যদি Visual Studio Code ব্যবহার করেন, তাহলে Test Explorer গ্রাফিকাল ইন্টারফেস প্রদান করে পরীক্ষাগুলো চালানো এবং ডিবাগ করার জন্য। VS Code Test Explorer -*VS কোড টেস্ট এক্সপ্লোরার দেখাচ্ছে সব জাভা টেস্ট ক্লাস এবং পৃথক টেস্ট মেথডের টেস্ট গাছ* +*VS Code Test Explorer যা সব Java টেস্ট ক্লাস এবং পৃথক টেস্ট মেথডের টেস্ট ট্রি দেখাচ্ছে* -**VS কোডে টেস্ট চালানোর জন্য:** +**VS Code-এ পরীক্ষাগুলো চালানোর জন্য:** -1. অ্যাক্টিভিটি বারে বিটার আইকনে ক্লিক করে Test Explorer খুলুন -2. টেস্ট গাছ বাড়ান সব মডিউল এবং টেস্ট ক্লাস দেখতে -3. যেকোনো টেস্টের পাশে প্লে বাটনে ক্লিক করুন পৃথকভাবে চালানোর জন্য -4. "Run All Tests" এ ক্লিক করে সম্পূর্ণ স্যুট চালান -5. যেকোনো টেস্টে রাইট-ক্লিক করে "Debug Test" নির্বাচন করুন ব্রেকপয়েন্ট সেট করতে এবং কোড ধাপে ধাপে দেখতে +1. Activity Bar-এ বীকার আইকনে ক্লিক করে Test Explorer খুলুন +2. টেস্ট ট্রি এক্সপ্যান্ড করে সব মডিউল ও টেস্ট ক্লাস দেখুন +3. কোন একটি টেস্টের পাশে প্লে বাটনে ক্লিক করে ব্যক্তিগতভাবে চালান +4. "Run All Tests" ক্লিক করে পুরো স্যুট চালান +5. কোন টেস্টে রাইট-ক্লিক করে "Debug Test" নির্বাচন করে ব্রেকপয়েন্ট বসিয়ে কোড স্টেপ করুন -Test Explorer সব পাস করা টেস্টের জন্য সবুজ চেকমার্ক দেখায় এবং ব্যর্থ হলে বিস্তারিত ত্রুটি বার্তা প্রদান করে। +টেস্ট এক্সপ্লোরার পাস করা টেস্টের জন্য সবুজ চেকমার্ক দেখায় এবং ব্যর্থ হলে বিস্তারিত ত্রুটি বার্তা দেয়। -## টেস্টিং প্যাটার্নস +## পরীক্ষার প্যাটার্নসমূহ -### প্যাটার্ন ১: প্রম্পট টেমপ্লেট টেস্টিং +### প্যাটার্ন ১: প্রম্পট টেমপ্লেট পরীক্ষা -সবচেয়ে সহজ প্যাটার্ন হল AI মডেল কল না করে প্রম্পট টেমপ্লেট টেস্ট করা। আপনি যাচাই করেন যে ভ্যারিয়েবল প্রতিস্থাপন সঠিকভাবে কাজ করে এবং প্রম্পট সঠিকভাবে ফর্ম্যাট হয়েছে। +সবচেয়ে সহজ প্যাটার্ন হলো প্রম্পট টেমপ্লেট পরীক্ষা যা কোনো AI মডেল কল করে না। আপনি যাচাই করেন ভেরিয়েবল স্থাপন সঠিক হচ্ছে এবং প্রম্পটগুলো প্রত্যাশিত ফরম্যাটে আসে। Prompt Template Testing -*প্রম্পট টেমপ্লেট টেস্টিং দেখাচ্ছে ভ্যারিয়েবল প্রতিস্থাপনের ফ্লো: প্লেসবোল্ডারসহ টেমপ্লেট → মান প্রয়োগ → ফর্ম্যাটেড আউটপুট যাচাই* +*প্রম্পট টেমপ্লেট পরীক্ষা যা ভেরিয়েবল স্থাপনের ফ্লো দেখায়: প্লেসহোল্ডারসহ টেমপ্লেট → মান প্রয়োগ → যাচাইকৃত ফরম্যাটেড আউটপুট* ```java @Test @@ -149,28 +147,15 @@ void testPromptTemplateFormatting() { } ``` -এই টেস্টটি অবস্থিত `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`। - -**চালান:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#টেস্টপ্রম্পটটেমপ্লেটফরম্যাটিং -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#টেস্টপ্রোম্পটটেমপ্লেটফরম্যাটিং -``` - +এই প্যাটার্ন নিশ্চিত করে যে ভেরিয়েবল স্থাপন সঠিক এবং প্রম্পটগুলো প্রত্যাশিত রূপে ফরম্যাটেড — কোনো API কী বা মডেল কলের প্রয়োজন নেই। ### প্যাটার্ন ২: ভাষা মডেল মকিং -কথোপকথন লজিক টেস্ট করার সময়, Mockito ব্যবহার করুন নকল মডেল তৈরি করতে যা নির্ধারিত রেসপন্স দেয়। এতে টেস্ট দ্রুত, ফ্রি এবং ডিটারমিনিস্টিক হয়। +কথোপকথনের লজিক পরীক্ষা করার সময়, Mockito ব্যবহার করে কৃত্রিম মডেল তৈরি করুন যা পূর্বনির্ধারিত উত্তর দেয়। এভাবে পরীক্ষা দ্রুত, বিনামূল্যে এবং নিশ্চিত হয়। Mock vs Real API Comparison -*তুলনা দেখাচ্ছে কেন টেস্টিংয়ের জন্য মক পছন্দসই: এগুলো দ্রুত, ফ্রি, ডিটারমিনিস্টিক এবং কোনো API কী লাগে না* +*তুলনা দেখায় কেন পরীক্ষার জন্য মক পছন্দনীয়: দ্রুত, বিনামূল্যে, নিশ্চিত, এবং API কী প্রয়োজন হয় না* ```java @ExtendWith(MockitoExtension.class) @@ -220,15 +205,15 @@ class SimpleConversationTest { } ``` -এই প্যাটার্নটি `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`-তে আছে। মক নিশ্চিত করে consistent আচরণ যাতে স্মৃতি ব্যবস্থাপনা সঠিক কাজ করে তা যাচাই করা যায়। +এই প্যাটার্ন `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` এ আছে। মক নিশ্চিত করে যে আচরণ সঙ্গতিপূর্ণ, যাতে আপনি যাচাই করতে পারেন স্মৃতি পরিচালনা সঠিক হচ্ছে। -### প্যাটার্ন ৩: কথোপকথন বিচ্ছিন্নতা টেস্টিং +### প্যাটার্ন ৩: কথোপকথন বিচ্ছিন্নতা পরীক্ষা -কথোপকথন স্মৃতি একাধিক ব্যবহারকারীকে আলাদা রাখতে হবে। এই টেস্ট যাচাই করে যে কথোপকথনগুলি প্রসঙ্গ মেশানো হয় না। +কথোপকথনের স্মৃতি একাধিক ব্যবহারকারীর আলাদা রাখতে হবে। এই পরীক্ষা যাচাই করে যে কথোপকথনগুলি ভিন্ন ভিন্ন প্রসঙ্গ মিশ্রিত হয় না। Conversation Isolation -*কথোপকথন বিচ্ছিন্নতা টেস্টিং দেখাচ্ছে আলাদা ব্যবহারকারীর জন্য আলাদা স্মৃতি স্টোর যা প্রসঙ্গ মেশানো প্রতিরোধ করে* +*কথোপকথন বিচ্ছিন্নতা পরীক্ষা যা আলাদা ব্যবহারকারীর স্মৃতি স্টোর আলাদা রাখে যেন প্রসঙ্গ না মিশ্রিত হয়* ```java @Test @@ -252,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -প্রত্যেক কথোপকথন তার স্বাধীন ইতিহাস বজায় রাখে। প্রকৃত সিস্টেমে, এই বিচ্ছিন্নতা মাল্টি-ইউজার অ্যাপ্লিকেশনগুলোর জন্য অত্যাবশ্যক। +প্রতিটি কথোপকথন তার স্বাধীন ইতিহাস সংরক্ষণ করে। উৎপাদন সিস্টেমে, বহুব্যবহারকারী অ্যাপ্লিকেশনের জন্য এই বিচ্ছিন্নতা অত্যাবশ্যক। -### প্যাটার্ন ৪: টুলস স্বাধীনভাবে টেস্ট করা +### প্যাটার্ন ৪: টুলস স্বাধীনভাবে পরীক্ষা -টুলস হল ফাংশন যেগুলো AI কল করতে পারে। সরাসরি টুলগুলো টেস্ট করুন নিশ্চিত করতে কাজ ঠিকঠাক করে, AI-র সিদ্ধান্ত নির্বিশেষে। +টুলস এমন ফাংশন যা AI কল করতে পারে। AI সিদ্ধান্তের বাইরেই সরাসরি টুলগুলো পরীক্ষা করুন যেন তারা সঠিক কাজ করে। Tools Testing -*স্বতন্ত্রভাবে টুলস টেস্টিং দেখাচ্ছে মক টুল এক্সিকিউশন AI কল ছাড়াই ব্যবসায়িক লজিক যাচাই করার জন্য* +*টুলস স্বাধীনভাবে পরীক্ষা, AI কল ছাড়াই ব্যবসায়িক লজিক যাচাই করার জন্য* ```java @Test @@ -283,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -এসব টেস্ট `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` থেকে এসেছে যা নিশ্চিত করে টুল লজিক AI জড়িত ছাড়াই কাজ করে। চেইনিং উদাহরণ দেখায় কিভাবে একটি টুলের আউটপুট অন্যটির ইনপুট ফিড হয়। +`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` থেকে এই পরীক্ষাগুলো AI সম্পৃক্ততা ছাড়া টুল লজিক নিশ্চিত করে। চেইনিং উদাহরণে একটি টুলের আউটপুট অন্যটির ইনপুটে ফিড হয়। -### প্যাটার্ন ৫: ইন-মেমোরি RAG টেস্টিং +### প্যাটার্ন ৫: ইন-মেমরি RAG পরীক্ষা -RAG সিস্টেম সাধারণত ভেক্টর ডাটাবেস এবং এম্বেডিং সার্ভিস প্রয়োজন। ইন-মেমোরি প্যাটার্ন এ নিয়ে আসে পুরো পাইপলাইন টেস্ট করার সুযোগ বাহ্যিক নির্ভরতা ছাড়াই। +RAG সিস্টেম সাধারণত ভেক্টর ডাটাবেস এবং এম্বেডিং সার্ভিসের প্রয়োজন হয়। ইন-মেমরি প্যাটার্নটি আপনাকে সম্পূর্ণ পাইপলাইন পরীক্ষা করতে দেয় বাহ্যিক নির্ভরতা ছাড়াই। In-Memory RAG Testing -*ইন-মেমোরি RAG টেস্টিং ওয়ার্কফ্লো দেখাচ্ছে ডকুমেন্ট পার্সিং, এম্বেডিং সংরক্ষণ, এবং সাদৃশ্য অনুসন্ধান ডাটাবেস ছাড়াই* +*ইন-মেমরি RAG পরীক্ষা ওয়ার্কফ্লো যা ডকুমেন্ট পার্সিং, এম্বেডিং সংরক্ষণ, এবং সাদৃশ্য অনুসন্ধান দেখায় ডাটাবেসের প্রয়োজন ছাড়াই* ```java @Test @@ -308,13 +293,13 @@ void testProcessTextDocument() { } ``` -এই টেস্টটি `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` থেকে, যেটা ইন-মেমোরি ডকুমেন্ট তৈরি করে এবং চাংকিং ও মেটাডাটা হ্যান্ডলিং যাচাই করে। +`03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` থেকে এই পরীক্ষা ইন-মেমরিতে একটি ডকুমেন্ট তৈরি করে এবং চাংকিং ও মেটাডাটা পরিচালনা যাচাই করে। -### প্যাটার্ন ৬: MCP ইন্টিগ্রেশন টেস্টিং +### প্যাটার্ন ৬: MCP ইন্টিগ্রেশন পরীক্ষা -MCP মডিউল মডেল কনটেক্সট প্রটোকল ইন্টিগ্রেশন পরীক্ষা করে stdio ট্রান্সপোর্ট ব্যবহার করে। এই টেস্টগুলি যাচাই করে আপনার অ্যাপ MCP সার্ভারগুলোকে সাবপ্রসেস হিসেবে স্পন এবং কমিউনিকেট করতে পারে। +MCP মডিউল মডেল কনটেক্সট প্রোটোকল ইন্টিগ্রেশন পরীক্ষা করে stdio ট্রান্সপোর্ট ব্যবহার করে। এই পরীক্ষাগুলো যাচাই করে যে আপনার অ্যাপ MCP সার্ভার সাব-প্রসেস হিসেবে স্পন এবং যোগাযোগ করতে পারে। -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java`-এর টেস্টগুলো MCP ক্লায়েন্ট আচরণ নিশ্চিত করে। +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` এ পরীক্ষাগুলো MCP ক্লায়েন্ট আচরণ যাচাই করে। **চালান:** @@ -328,39 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` +## পরীক্ষার দর্শন -## টেস্টিং দর্শন - -আপনার কোড টেস্ট করুন, AI নয়। আপনার টেস্টগুলো যাচাই করবে আপনি যেই কোড লিখেছেন সেটা কতটা সঠিক যেমন প্রম্পট কিভাবে তৈরি হচ্ছে, স্মৃতি কিভাবে ব্যবস্থাপিত হচ্ছে, এবং টুল কিভাবে নির্বাহ হচ্ছে। AI রেসপন্স ভিন্ন হতে পারে এবং তা টেস্টের অংশ হওয়া উচিত নয়। নিজেকে জিজ্ঞাসা করুন আপনার প্রম্পট টেমপ্লেট ভ্যারিয়েবল সঠিক প্রতিস্থাপন করছে কি না, AI সঠিক উত্তর দিচ্ছে কি না নয়। +আপনার কোড পরীক্ষা করুন, AI নয়। আপনার পরীক্ষাগুলো লিখিত কোড যাচাই করবে যেমন প্রম্পট কিভাবে গঠিত হচ্ছে, স্মৃতি কিভাবে পরিচালিত হচ্ছে, এবং টুলস কিভাবে কার্যকর হচ্ছে তা দেখে। AI প্রতিক্রিয়া পরিবর্তনশীল এবং পরীক্ষার দাবিতে থাকা উচিত নয়। নিজেকে প্রশ্ন করুন যে আপনার প্রম্পট টেমপ্লেট ভেরিয়েবল সঠিকভাবে প্রতিস্থাপন করছে কিনা, AI সঠিক উত্তর দিচ্ছে কিনা নয়। -ভাষা মডেলের জন্য মক ব্যবহার করুন। এগুলো বাহ্যিক নির্ভরতা যেগুলো ধীর, ব্যয়বহুল, এবং অনির্ধারিত। মকিং করে টেস্ট দ্রুত হয় মিলিসেকেন্ডে না যে সেকেন্ডে, ফ্রি হয় কোনো API খরচ ছাড়াই, এবং ডিটারমিনিস্টিক হয় প্রতিবার একই ফলাফল দিয়ে। +ভাষা মডেলের জন্য মক ব্যবহার করুন। এগুলো বাহ্যিক নির্ভরতা, যা ধীর, খরচবহুল এবং অনির্ধারিত। মকিং পরীক্ষাকে দ্রুত করে, মিলিসেকেন্ডে সেকেন্ডের বদলে, বিনামূল্যে করে, এবং নিশ্চিত করে প্রত্যেক বার একই ফলাফল দেয়। -টেস্টগুলো স্বাধীন রাখুন। প্র প্রতিটি টেস্ট নিজস্ব ডেটা সেট আপ করবে, অন্য টেস্টের উপর নির্ভর করবে না, এবং নিজেই ক্লিন আপ করবে। টেস্টগুলো চালানোর ক্রম অনুসারে পাস না হওয়া উচিত। +পরীক্ষাগুলো স্বাধীন রাখুন। প্রতিটি পরীক্ষা নিজস্ব ডাটা তৈরি করবে, অন্য পরীক্ষার ওপর নির্ভর করবে না, এবং নিজের পরিছন্নতা করবে। পরীক্ষা সঞ্চালনের ক্রম নির্বিশেষে পাস করা উচিত। -হ্যাপি পাথ ছাড়াও এজ কেস টেস্ট করুন। খালি ইনপুট, খুব বড় ইনপুট, বিশেষ অক্ষর, অবৈধ প্যারামিটার, এবং সীমানা শর্ত পরীক্ষা করুন। এগুলো প্রায়শই এমন বাগ খুঁজে বের করে যা সাধারণ ব্যবহার ফাঁকি দেয়। +সুখী পথের বাইরে প্রান্তিক ক্ষেত্রে পরীক্ষা করুন। খালি ইনপুট, অত্যন্ত বড় ইনপুট, বিশেষ অক্ষর, অবৈধ প্যারামিটার, এবং সীমান্ত অবস্থান চেষ্টা করুন। এগুলো প্রায়ই এমন বাগ উদঘাটন করে যা সাধারণ ব্যবহার দেখায় না। -বর্ণনামূলক নাম ব্যবহার করুন। `shouldMaintainConversationHistoryAcrossMultipleMessages()` এর সাথে তুলনা করুন `test1()` এর। প্রথমটি আপনি কী টেস্ট করছেন ঠিকই বলে দেয়, যা ব্যর্থতা ডিবাগ সহজ করে। +বর্ণনামূলক নাম ব্যবহার করুন। `shouldMaintainConversationHistoryAcrossMultipleMessages()` এবং `test1()` তুলনা করুন। প্রথমটি ঠিক কী পরীক্ষা হচ্ছে তা বলে, ব্যর্থতা ডিবাগ করা সহজ করে। ## পরবর্তী ধাপসমূহ -এখন যেহেতু আপনি টেস্টিং প্যাটার্নগুলো বুঝে গেছেন, প্রতিটি মডিউলে গভীরভাবে প্রবেশ করুন: +এখন যখন আপনি পরীক্ষার প্যাটার্নগুলো বুঝে গেছেন, প্রতিটি মডিউলে গভীরতর যান: -- **[00 - দ্রুত শুরু](../00-quick-start/README.md)** - প্রম্পট টেমপ্লেট বেসিক দিয়ে শুরু করুন -- **[01 - পরিচিতি](../01-introduction/README.md)** - কথোপকথন স্মৃতি ব্যবস্থাপনা শিখুন -- **[02 - প্রম্পট ইঞ্জিনিয়ারিং](../02-prompt-engineering/README.md)** - GPT-5.2 প্রম্পটিং প্যাটার্ন মাস্টার করুন -- **[03 - RAG](../03-rag/README.md)** - রিট্রিভাল-অগমেন্টেড জেনারেশন সিস্টেম তৈরি করুন -- **[04 - টুলস](../04-tools/README.md)** - ফাংশন কলিং এবং টুল চেইন বাস্তবায়ন করুন -- **[05 - MCP](../05-mcp/README.md)** - মডেল কনটেক্সট প্রটোকল ইন্টিগ্রেট করুন +- **[01 - পরিচিতি](../01-introduction/README.md)** - কথোপকথন স্মৃতি ব্যবস্থাপনা শিখুন +- **[02 - প্রম্পট ইঞ্জিনিয়ারিং](../02-prompt-engineering/README.md)** - GPT-5.2 প্রম্পটিং প্যাটার্ন মাস্টার করুন +- **[03 - RAG](../03-rag/README.md)** - রিট্রিভাল-অগমেন্টেড জেনারেশন সিস্টেম তৈরি করুন +- **[04 - টুলস](../04-tools/README.md)** - ফাংশন কলিং এবং টুল চেইন বাস্তবায়ন করুন +- **[05 - MCP](../05-mcp/README.md)** - মডেল কনটেক্সট প্রোটোকল ইন্টিগ্রেট করুন -প্রতিটি মডিউলের README-তে এখানে টেস্ট হওয়া ধারণাগুলোর বিস্তারিত ব্যাখ্যা আছে। +প্রতিটি মডিউলের README এখানে পরীক্ষিত ধারণাগুলোর বিস্তারিত ব্যাখ্যা প্রদান করে। --- -**নেভিগেশন:** [← মেইনে ফিরে যান](../README.md) +**নেভিগেশন:** [← প্রধান পৃষ্ঠায় ফিরে যান](../README.md) --- -**ইনকার্জনোটঃ** -এই নথিটি AI অনুবাদ সেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা সঠিকতার জন্য চেষ্টা করি, স্বয়ংক্রিয় অনুবাদে ভুল বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার নিজ ভাষাতেই কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচনা করা উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদের পরামর্শ দেওয়া হয়। এই অনুবাদের ব্যবহারে কোনো ভুল বোঝাবুঝি বা বিভ্রাটের জন্য আমরা দায়িত্বশীল নই। +**অস্বীকৃতি**: +এই নথিটি AI অনুবাদ পরিষেবা [Co-op Translator](https://github.com/Azure/co-op-translator) ব্যবহার করে অনূদিত হয়েছে। যদিও আমরা শুদ্ধতার জন্য চেষ্টা করি, অনুগ্রহ করে মনে রাখবেন যে স্বয়ংক্রিয় অনুবাদে ত্রুটি বা অসঙ্গতি থাকতে পারে। মূল নথিটি তার স্বভাষায় কর্তৃত্বপূর্ণ উৎস হিসেবে বিবেচিত হওয়া উচিত। গুরুত্বপূর্ণ তথ্যের জন্য পেশাদার মানব অনুবাদ সুপারিশ করা হয়। এই অনুবাদের ব্যবহারে প্রয়োজনীয় ভুল বোঝাবুঝি বা ভুল ব্যাখ্যার জন্য আমরা দায়বদ্ধ নই। \ No newline at end of file diff --git a/translations/cs/.co-op-translator.json b/translations/cs/.co-op-translator.json index 4b4a3e7ad..4c1d2e4cd 100644 --- a/translations/cs/.co-op-translator.json +++ b/translations/cs/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "cs" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T02:56:06+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T09:00:33+00:00", "source_file": "01-introduction/README.md", "language_code": "cs" }, @@ -18,20 +18,20 @@ "language_code": "cs" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T02:58:39+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T08:55:48+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "cs" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T03:00:04+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T08:59:41+00:00", "source_file": "03-rag/README.md", "language_code": "cs" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:17:58+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T08:58:15+00:00", "source_file": "04-tools/README.md", "language_code": "cs" }, @@ -54,8 +54,8 @@ "language_code": "cs" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:52:49+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T08:54:23+00:00", "source_file": "README.md", "language_code": "cs" }, @@ -72,14 +72,14 @@ "language_code": "cs" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T03:03:41+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T08:56:19+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "cs" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T03:04:28+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T08:56:59+00:00", "source_file": "docs/TESTING.md", "language_code": "cs" } diff --git a/translations/cs/00-quick-start/README.md b/translations/cs/00-quick-start/README.md deleted file mode 100644 index 4b9c5d01b..000000000 --- a/translations/cs/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modul 00: Rychlý start - -## Obsah - -- [Úvod](../../../00-quick-start) -- [Co je LangChain4j?](../../../00-quick-start) -- [Závislosti LangChain4j](../../../00-quick-start) -- [Požadavky](../../../00-quick-start) -- [Nastavení](../../../00-quick-start) - - [1. Získejte svůj GitHub token](../../../00-quick-start) - - [2. Nastavte svůj token](../../../00-quick-start) -- [Spuštění příkladů](../../../00-quick-start) - - [1. Základní chat](../../../00-quick-start) - - [2. Vzory pro promptování](../../../00-quick-start) - - [3. Volání funkcí](../../../00-quick-start) - - [4. Dotazy k dokumentům (Easy RAG)](../../../00-quick-start) - - [5. Odpovědná AI](../../../00-quick-start) -- [Co každý příklad ukazuje](../../../00-quick-start) -- [Další kroky](../../../00-quick-start) -- [Řešení problémů](../../../00-quick-start) - -## Úvod - -Tento rychlý start je určen k tomu, abyste co nejrychleji začali pracovat s LangChain4j. Pokrývá absolutní základy vytváření AI aplikací s LangChain4j a GitHub Models. V dalších modulech přejdete na Azure OpenAI a GPT-5.2 a hlouběji se ponoříte do jednotlivých konceptů. - -## Co je LangChain4j? - -LangChain4j je knihovna pro Javu, která zjednodušuje vytváření aplikací poháněných AI. Místo práce s HTTP klienty a parsováním JSON pracujete s čistými Java API. - -„Řetězení“ (chain) v LangChain znamená propojení více komponent – můžete propojit prompt s modelem a následujícím parsrem, nebo několik AI volání, kde výstup jednoho se stane vstupem dalšího. Tento rychlý start se zaměřuje na základy před tím, než se pustíte do složitějších řetězců. - -LangChain4j Chaining Concept - -*Řetězení komponent v LangChain4j – stavební bloky se spojují a vytvářejí silné AI workflow* - -Použijeme tři základní komponenty: - -**ChatModel** – rozhraní pro interakce s AI modelem. Zavolejte `model.chat("prompt")` a získejte odpověď jako řetězec. Používáme `OpenAiOfficialChatModel`, který pracuje s OpenAI kompatibilními endpointy, jako jsou GitHub Models. - -**AiServices** – vytváří typově bezpečná rozhraní AI služeb. Definujte metody, označte je `@Tool` a LangChain4j se postará o orchestraci. AI automaticky volá vaše Java metody, když je to potřeba. - -**MessageWindowChatMemory** – uchovává historii konverzace. Bez ní je každý požadavek nezávislý. S ní si AI pamatuje předchozí zprávy a udržuje kontext napříč několika výměnami. - -LangChain4j Architecture - -*Architektura LangChain4j – základní komponenty spolupracují, aby poháněly vaše AI aplikace* - -## Závislosti LangChain4j - -Tento rychlý start používá tři závislosti Maven v [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modul `langchain4j-open-ai-official` poskytuje třídu `OpenAiOfficialChatModel`, která se připojuje k OpenAI kompatibilním API. GitHub Models používá stejný formát API, takže není potřeba žádný speciální adaptér – stačí nastavit základní URL na `https://models.github.ai/inference`. - -Modul `langchain4j-easy-rag` zajišťuje automatické dělení dokumentů, vytváření embeddingů a vyhledávání, takže můžete tvořit RAG aplikace bez manuální konfigurace každého kroku. - -## Požadavky - -**Používáte Dev Container?** Java a Maven jsou už nainstalované. Potřebujete jen GitHub Personal Access Token. - -**Lokální vývoj:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (návod níže) - -> **Poznámka:** Tento modul používá `gpt-4.1-nano` z GitHub Models. Neměňte název modelu v kódu – je nastaven pro práci s dostupnými modely na GitHubu. - -## Nastavení - -### 1. Získejte svůj GitHub token - -1. Přejděte na [GitHub Nastavení → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Klikněte na „Generate new token“ (vygenerovat nový token) -3. Zadejte popisný název (např. "LangChain4j Demo") -4. Nastavte expiraci (doporučeno 7 dní) -5. V sekci „Account permissions“ najděte „Models“ a nastavte na „Read-only“ -6. Klikněte na „Generate token“ -7. Zkopírujte a uložte váš token – znovu ho neuvidíte - -### 2. Nastavte svůj token - -**Možnost 1: Použití VS Code (doporučeno)** - -Pokud používáte VS Code, přidejte svůj token do souboru `.env` v kořenovém adresáři projektu: - -Pokud soubor `.env` neexistuje, zkopírujte `.env.example` do `.env` nebo vytvořte nový `.env` v kořenové složce projektu. - -**Příklad souboru `.env`:** -```bash -# V /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Pak můžete jednoduše kliknout pravým tlačítkem na jakýkoliv demo soubor (např. `BasicChatDemo.java`) v Průzkumníku a vybrat **„Run Java”** nebo použít konfigurační profily v panelu Run and Debug. - -**Možnost 2: Použití terminálu** - -Nastavte token jako proměnnou prostředí: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Spuštění příkladů - -**Ve VS Code:** Stačí kliknout pravým tlačítkem na libovolný demo soubor v Průzkumníku a zvolit **„Run Java”**, nebo použít spouštěcí konfigurace v panelu Run and Debug (nejprve musíte přidat token do `.env`). - -**Pomocí Maven:** Alternativně spusťte z příkazové řádky: - -### 1. Základní chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Vzory pro promptování - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Ukažte zero-shot, few-shot, chain-of-thought a role-based promptování. - -### 3. Volání funkcí - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI automaticky volá vaše Java metody, když je to potřeba. - -### 4. Dotazy k dokumentům (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Pokládejte dotazy k dokumentům pomocí Easy RAG s automatickým embeddingem a vyhledáváním. - -### 5. Odpovědná AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Ukažte, jak AI bezpečnostní filtry blokují škodlivý obsah. - -## Co každý příklad ukazuje - -**Základní chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Začněte zde, abyste viděli LangChain4j v jeho nejjednodušší podobě. Vytvoříte `OpenAiOfficialChatModel`, odešlete prompt s `.chat()` a získáte odpověď. Tento příklad ukazuje základy: jak inicializovat modely s vlastním endpointem a API klíčem. Jakmile tuto šablonu pochopíte, vše ostatní na ní staví. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) a zeptejte se: -> - „Jak přepnu z GitHub Models na Azure OpenAI v tomto kódu?“ -> - „Jaké další parametry mohu konfigurovat v OpenAiOfficialChatModel.builder()?“ -> - „Jak přidám streamingové odpovědi místo čekání na kompletní odpověď?“ - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Nyní, když víte, jak s modelem mluvit, prozkoumejme, co mu říkáte. Toto demo používá stejnou konfiguraci modelu, ale ukazuje pět různých vzorů promptování. Vyzkoušejte zero-shot prompty pro přímé instrukce, few-shot prompty, které se učí z příkladů, chain-of-thought prompty odkrývající kroky uvažování, a role-based prompty, které nastavují kontext. Uvidíte, jak stejný model poskytuje dramaticky odlišné výsledky podle toho, jak si formulujete dotaz. - -Demo také ukazuje prompt šablony, což je mocný způsob, jak tvořit znovupoužitelné prompty s proměnnými. -Níže uvedený příklad ukazuje prompt využívající LangChain4j `PromptTemplate` pro vyplnění proměnných. AI odpoví podle dané destinace a aktivity. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) a zeptejte se: -> - „Jaký je rozdíl mezi zero-shot a few-shot promptováním a kdy každý z nich použít?“ -> - „Jak parametr temperature ovlivňuje odpovědi modelu?“ -> - „Jaké jsou techniky prevence prompt injection útoků v produkci?“ -> - „Jak mohu vytvořit znovupoužitelné PromptTemplate objekty pro běžné vzory?“ - -**Integrace nástrojů** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Zde LangChain4j ukazuje svoji sílu. Použijete `AiServices` k vytvoření AI asistenta, který může volat vaše Java metody. Stačí označit metody `@Tool("popis")` a LangChain4j se postará o zbytek – AI automaticky rozhodne, kdy použít který nástroj podle dotazu uživatele. Toto ukazuje volání funkcí, klíčovou techniku pro budování AI, která umí nejen odpovídat, ale také provádět akce. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) a zeptejte se: -> - „Jak funguje anotace @Tool a co s ní LangChain4j dělá na pozadí?“ -> - „Může AI volat více nástrojů za sebou, aby vyřešila složité problémy?“ -> - „Co když nástroj vyhodí výjimku – jak mám chytat chyby?“ -> - „Jak bych integroval reálné API místo tohoto příkladu kalkulačky?“ - -**Dotazy k dokumentům (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Zde uvidíte RAG (retrieval-augmented generation) pomocí „Easy RAG“ přístupu LangChain4j. Dokumenty se načítají, automaticky se dělí a embedují do paměťové databáze, poté obsahový vyhledávač dodá relevantní části AI v době dotazu. AI odpovídá na základě vašich dokumentů, ne jen obecné znalosti. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) a zeptejte se: -> - „Jak RAG zabraňuje halucinacím AI ve srovnání s využitím tréninkových dat modelu?“ -> - „Jaký je rozdíl mezi tímto jednoduchým přístupem a vlastním RAG pipeline?“ -> - „Jak bych škáloval tento přístup pro více dokumentů nebo větší znalostní báze?“ - -**Odpovědná AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Budujte bezpečnost AI s obranou do hloubky. Toto demo ukazuje dvě vrstvy ochrany, které spolupracují: - -**Část 1: LangChain4j Input Guardrails** – Blokují nebezpečné prompty dřív, než dorazí k LLM. Vytvářejte vlastní strážní pravidla, která kontrolují zakázaná klíčová slova nebo vzory. Běží ve vašem kódu, takže jsou rychlá a zdarma. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Část 2: Bezpečnostní filtry poskytovatele** – GitHub Models má zabudované filtry, které zachytí to, co vaše guardrails mohou přehlédnout. Uvidíte tvrdé blokace (chyby HTTP 400) u vážných porušení i měkká odmítnutí, kde AI zdvořile odmítá. - -> **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) a zeptejte se: -> - „Co je InputGuardrail a jak vytvořit vlastní?“ -> - „Jaký je rozdíl mezi tvrdým blokem a měkkým odmítnutím?“ -> - „Proč používat guardrails i filtry poskytovatele společně?“ - -## Další kroky - -**Další modul:** [01-introduction - Začínáme s LangChain4j](../01-introduction/README.md) - ---- - -**Navigace:** [← Zpět na hlavní stránku](../README.md) | [Další: Modul 01 - Úvod →](../01-introduction/README.md) - ---- - -## Řešení problémů - -### První sestavení pomocí Maven - -**Problém**: První `mvn clean compile` nebo `mvn package` trvá dlouho (10-15 minut) - -**Příčina**: Maven si při prvním sestavení stáhne všechny závislosti projektu (Spring Boot, knihovny LangChain4j, Azure SDK atd.). - -**Řešení**: Je to normální. Následující sestavení budou výrazně rychlejší, protože závislosti jsou uloženy v mezipaměti lokálně. Doba stahování závisí na rychlosti vašeho připojení. - -### Syntaxe příkazů Maven v PowerShell - -**Problém**: Maven příkazy končí chybou `Unknown lifecycle phase ".mainClass=..."` -**Příčina**: PowerShell interpretuje `=` jako operátor přiřazení proměnné, což narušuje syntaxi vlastností Maven - -**Řešení**: Použijte před příkaz Maven operátor ukončení parsování `--%`: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operátor `--%` říká PowerShellu, aby předal všechny následující argumenty doslovně do Maven bez interpretace. - -### Zobrazování emoji ve Windows PowerShell - -**Problém**: Odpovědi AI zobrazují v PowerShellu nesmyslné znaky (např. `????` nebo `â??`) místo emoji - -**Příčina**: Výchozí kódování PowerShellu nepodporuje UTF-8 emoji - -**Řešení**: Spusťte tento příkaz před spuštěním Java aplikací: -```cmd -chcp 65001 -``` - -Tím se v terminálu vynutí kódování UTF-8. Alternativně použijte Windows Terminal, který má lepší podporu Unicode. - -### Ladění volání API - -**Problém**: Chybové hlášky autentizace, limity volání nebo neočekávané odpovědi od modelu AI - -**Řešení**: Příklady obsahují `.logRequests(true)` a `.logResponses(true)`, které zobrazují volání API v konzoli. To pomáhá při řešení chyb autentizace, limitů volání nebo neočekávaných odpovědí. V produkci tyto příznaky odstraňte, aby byla konzole méně zahlcená. - ---- - - -**Prohlášení o omezení odpovědnosti**: -Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o přesnost, mějte prosím na paměti, že automatické překlady mohou obsahovat chyby či nepřesnosti. Původní dokument v jeho mateřském jazyce by měl být považován za závazný zdroj. Pro kritické informace doporučujeme profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění či mylné výklady vyplývající z použití tohoto překladu. - \ No newline at end of file diff --git a/translations/cs/01-introduction/README.md b/translations/cs/01-introduction/README.md index 6d19f24d4..1048d1450 100644 --- a/translations/cs/01-introduction/README.md +++ b/translations/cs/01-introduction/README.md @@ -2,84 +2,84 @@ ## Obsah -- [Video průvodce](../../../01-introduction) -- [Co se naučíte](../../../01-introduction) -- [Požadavky](../../../01-introduction) -- [Pochopení základního problému](../../../01-introduction) -- [Pochopení tokenů](../../../01-introduction) -- [Jak funguje paměť](../../../01-introduction) -- [Jak to používá LangChain4j](../../../01-introduction) -- [Nasazení infrastruktury Azure OpenAI](../../../01-introduction) -- [Spuštění aplikace lokálně](../../../01-introduction) -- [Používání aplikace](../../../01-introduction) - - [Bezstavový chat (levý panel)](../../../01-introduction) - - [Stavový chat (pravý panel)](../../../01-introduction) -- [Další kroky](../../../01-introduction) +- [Video průvodce](#video-průvodce) +- [Co se naučíte](#co-se-naučíte) +- [Předpoklady](#předpoklady) +- [Porozumění hlavnímu problému](#porozumění-hlavnímu-problému) +- [Porozumění tokenům](#porozumění-tokenům) +- [Jak funguje paměť](#jak-funguje-paměť) +- [Jak to používá LangChain4j](#jak-to-používá-langchain4j) +- [Nasazení infrastruktury Azure OpenAI](#nasazení-infrastruktury-azure-openai) +- [Spuštění aplikace lokálně](#spuštění-aplikace-lokálně) +- [Použití aplikace](#použití-aplikace) + - [Bezstavový chat (levý panel)](#bezstavový-chat-levý-panel) + - [Stavový chat (pravý panel)](#stavový-chat-pravý-panel) +- [Další kroky](#další-kroky) ## Video průvodce -Podívejte se na tuto živou relaci, která vysvětluje, jak začít s tímto modulem: +Sledujte tuto živou session, která vysvětluje, jak začít s tímto modulem: Getting Started with LangChain4j - Live Session ## Co se naučíte -V rychlém startu jste použili GitHub Modely k odesílání promptů, volání nástrojů, sestavení RAG pipeline a testování ochranných mechanismů. Tyto ukázky předvedly, co je možné — nyní přecházíme k Azure OpenAI a GPT-5.2 a začínáme stavět aplikace pro produkční použití. Tento modul se zaměřuje na konverzační AI, která si pamatuje kontext a udržuje stav — koncepty, které ty rychlé starty používaly za scénou, ale nevysvětlily. +Toto je váš výchozí bod s LangChain4j a Azure OpenAI. Začínáme se základy a postupně stavíme produkční aplikace. Tento modul se soustředí na konverzační AI, která si pamatuje kontext a udržuje stav — základní koncepty, na kterých staví všechny následující moduly. -Budeme používat Azure OpenAI GPT-5.2 po celou dobu tohoto průvodce, protože jeho pokročilé schopnosti rozumění umožňují lépe vidět rozdíly v chování různých vzorů. Když přidáte paměť, jasně uvidíte rozdíl. To usnadňuje pochopení toho, co každá komponenta přináší do vaší aplikace. +Použijeme Azure OpenAI GPT-5.2 během celé této příručky, protože jeho pokročilé schopnosti dedukce činí chování různých vzorů jasněji viditelným. Když přidáte paměť, uvidíte rozdíl jasně. To usnadňuje porozumění tomu, co každý komponent přináší vaší aplikaci. -Postavíte jednu aplikaci, která demonstruje oba vzory: +Vytvoříte jednu aplikaci, která ukazuje oba vzory: -**Bezstavový chat** - Každý požadavek je nezávislý. Model si nepamatuje předchozí zprávy. Toto je vzor použitý v rychlém startu. +**Bezstavový chat** - Každý požadavek je nezávislý. Model si nepamatuje předchozí zprávy. Je to nejjednodušší výchozí bod. -**Stavová konverzace** - Každý požadavek zahrnuje historii konverzace. Model udržuje kontext napříč více koly komunikace. Toto vyžadují produkční aplikace. +**Stavová konverzace** - Každý požadavek obsahuje historii konverzace. Model udržuje kontext přes více zpráv. To je požadavek v produkčních aplikacích. -## Požadavky +## Předpoklady - Azure předplatné s přístupem k Azure OpenAI -- Java 21, Maven 3.9+ +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Poznámka:** Java, Maven, Azure CLI a Azure Developer CLI (azd) jsou předinstalované v dodaném devcontaineru. +> **Poznámka:** Java, Maven, Azure CLI a Azure Developer CLI (azd) jsou předinstalované v poskytnutém devcontaineru. -> **Poznámka:** Tento modul používá GPT-5.2 na Azure OpenAI. Nasazení je automaticky nakonfigurováno pomocí `azd up` - neupravujte název modelu v kódu. +> **Poznámka:** Tento modul používá GPT-5.2 na Azure OpenAI. Nasazení je automaticky nakonfigurováno pomocí `azd up` - neměňte název modelu v kódu. -## Pochopení základního problému +## Porozumění hlavnímu problému -Jazykové modely jsou bezstavové. Každé API volání je nezávislé. Pokud pošlete "Jmenuji se John" a pak se zeptáte "Jak se jmenuji?", model nemá ponětí, že jste se právě představili. Zachází s každým požadavkem, jako by to byla první konverzace, kterou jste s ním kdy měli. +Jazykové modely jsou bezstavové. Každé API volání je nezávislé. Pokud pošlete "Jmenuji se John" a pak se zeptáte "Jak se jmenuji?", model nemá tušení, že jste se právě představil. Každý požadavek považuje za první konverzaci, kterou jste kdy vedli. -To je v pořádku pro jednoduché otázky a odpovědi, ale k ničemu pro skutečné aplikace. Chatboti zákaznické podpory si musí pamatovat, co jste jim řekli. Osobní asistenti potřebují kontext. Každá vícekroková konverzace vyžaduje paměť. +To je v pořádku pro jednoduché otázky a odpovědi, ale pro skutečné aplikace to je k ničemu. Chatboti zákaznické podpory si musí pamatovat, co jste jim řekli. Osobní asistenti potřebují kontext. Každá konverzace s více zprávami vyžaduje paměť. -Následující diagram kontrastuje oba přístupy — vlevo bezstavové volání, které zapomíná vaše jméno; vpravo stavové volání podporované ChatMemory, která si jméno pamatuje. +Následující diagram kontrastuje dva přístupy — vlevo bezstavové volání, které zapomene vaše jméno; vpravo stavové volání podporované ChatMemory, které si jméno pamatuje. Stateless vs Stateful Conversations -*Rozdíl mezi bezstavovými (nezávislými voláními) a stavovými (uvědomělými o kontextu) konverzacemi* +*Rozdíl mezi bezstavovými (nezávislými voláními) a stavovými (kontextově uvědomělými) konverzacemi* -## Pochopení tokenů +## Porozumění tokenům -Než se ponoříme do konverzací, je důležité pochopit tokeny - základní jednotky textu, které jazykové modely zpracovávají: +Než se pustíte do konverzací, je důležité pochopit tokeny - základní jednotky textu, které jazykové modely zpracovávají: Token Explanation -*Příklad jak je text rozdělen do tokenů - "Miluji AI!" se stává 4 samostatné jednotky zpracování* +*Příklad, jak se text rozdělí na tokeny - "I love AI!" se stane 4 samostatnými jednotkami pro zpracování* -Tokeny jsou měřítkem a jednotkami zpracování u AI modelů. Slova, interpunkce a dokonce mezery mohou být tokeny. Váš model má limit, kolik tokenů může zpracovat najednou (400 000 u GPT-5.2, s až 272 000 vstupními a 128 000 výstupními tokeny). Pochopení tokenů pomáhá řídit délku konverzace a náklady. +Tokeny jsou způsob, jakým AI modely měří a zpracovávají text. Slova, interpunkce a dokonce i mezery mohou být tokeny. Váš model má limit, kolik tokenů může zpracovat najednou (400 000 pro GPT-5.2, se až 272 000 vstupními tokeny a 128 000 výstupními tokeny). Porozumění tokenům vám pomůže řídit délku konverzace a náklady. ## Jak funguje paměť -Paměť chatu řeší bezstavový problém tím, že udržuje historii konverzace. Před odesláním vašeho požadavku modelu framework předřadí relevantní předchozí zprávy. Když se zeptáte "Jak se jmenuji?", systém ve skutečnosti pošle celou historii konverzace, což umožní modelu vidět, že jste dříve řekli "Jmenuji se John." +Paměť chatu řeší problém bezstavovosti tím, že uchovává historii konverzace. Před odesláním požadavku modelu framework přidá relevantní předchozí zprávy. Když se zeptáte "Jak se jmenuji?", systém ve skutečnosti pošle celou historii konverzace, což umožní modelu vidět, že jste předtím řekl "Jmenuji se John." -LangChain4j poskytuje implementace paměti, které toto automaticky zvládají. Vy si vyberete, kolik zpráv chcete uchovat, a framework spravuje kontextové okno. Níže je diagram, který ukazuje, jak MessageWindowChatMemory udržuje posuvné okno posledních zpráv. +LangChain4j poskytuje implementace paměti, které to automaticky řeší. Vy si vyberete, kolik zpráv chcete uchovat, a framework spravuje kontextové okno. Níže uvedený diagram ukazuje, jak MessageWindowChatMemory udržuje posuvné okno nedávných zpráv. Memory Window Concept -*MessageWindowChatMemory udržuje posuvné okno posledních zpráv, automaticky odhazuje staré* +*MessageWindowChatMemory udržuje posuvné okno nedávných zpráv a automaticky odstraňuje staré* ## Jak to používá LangChain4j -Tento modul rozšiřuje rychlý start integrací Spring Boot a přidáním paměti konverzace. Tady je, jak k sobě části zapadají: +Tento modul integruje Spring Boot a přidává paměť konverzace. Takto do sebe části zapadají: **Závislosti** - Přidejte dvě knihovny LangChain4j: @@ -94,7 +94,7 @@ Tento modul rozšiřuje rychlý start integrací Spring Boot a přidáním pamě ``` -**Chatovací model** - Nakonfigurujte Azure OpenAI jako Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chat model** - Nakonfigurujte Azure OpenAI jako Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder načítá přihlašovací údaje z proměnných prostředí nastavených `azd up`. Nastavení `baseUrl` na váš Azure endpoint umožňuje klientu OpenAI pracovat s Azure OpenAI. +Builder čte přihlašovací údaje z proměnných prostředí nastavených pomocí `azd up`. Nastavení `baseUrl` na váš Azure endpoint umožňuje klientovi OpenAI fungovat s Azure OpenAI. **Paměť konverzace** - Sledujte historii chatu s MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Vytvořte paměť pomocí `withMaxMessages(10)` pro uchování posledních 10 zpráv. Přidejte uživatelské a AI zprávy s typovanými wrappery: `UserMessage.from(text)` a `AiMessage.from(text)`. Historii získáte voláním `memory.messages()` a tu pošlete modelu. Servis uchovává oddělené instance paměti podle ID konverzace, což umožňuje více uživatelům simultánně chatovat. +Vytvořte paměť s `withMaxMessages(10)`, aby se uchovalo posledních 10 zpráv. Přidejte uživatelské a AI zprávy s typovými obaly: `UserMessage.from(text)` a `AiMessage.from(text)`. Získejte historii s `memory.messages()` a pošlete ji modelu. Služba uchovává samostatné instance paměti pro každý ID konverzace, což umožňuje více uživatelům chatovat současně. -> **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chatem:** Otevřete [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) a zeptejte se: +> **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) a zeptejte se: > - "Jak MessageWindowChatMemory rozhoduje, které zprávy zahodit, když je okno plné?" > - "Mohu implementovat vlastní úložiště paměti pomocí databáze místo paměti v RAM?" -> - "Jak bych přidal shrnutí (sumarizaci) pro kompresi staré historie konverzace?" +> - "Jak bych přidal shrnutí pro kompresi staré historie konverzace?" -Bezstavový chat endpoint paměť zcela přeskočí - pouze `chatModel.chat(prompt)`, jako v rychlém startu. Stavový endpoint přidává zprávy do paměti, získává historii a zahrnuje tento kontext do každého požadavku. Stejné nastavení modelu, různé vzory. +Bezstavový chat endpoint paměť zcela vynechává - pouze `chatModel.chat(prompt)` jako rychlý start. Stavový endpoint přidává zprávy do paměti, získává historii a zahrnuje tento kontext s každým požadavkem. Stejná konfigurace modelu, různé vzory. ## Nasazení infrastruktury Azure OpenAI @@ -147,16 +147,16 @@ cd 01-introduction azd up # Vyberte předplatné a umístění (doporučeno eastus2) ``` -> **Poznámka:** Pokud narazíte na chybu timeoutu (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), jednoduše spusťte `azd up` znovu. Azure zdroje mohou být stále v procesu provisioning na pozadí a opakování umožní dokončení nasazení, jakmile dosáhnou konečného stavu. +> **Poznámka:** Pokud narazíte na chybu timeoutu (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), jednoduše spusťte znovu `azd up`. Azure zdroje mohou stále probíhat na pozadí a opakování umožní dokončení nasazení, jakmile zdroje dosáhnou konečného stavu. Toto provede: -1. Nasazení Azure OpenAI s GPT-5.2 a modely text-embedding-3-small -2. Automatické vytvoření `.env` souboru v kořenu projektu s přihlašovacími údaji -3. Nastavení všech požadovaných proměnných prostředí +1. Nasazení zdroje Azure OpenAI s GPT-5.2 a modely text-embedding-3-small +2. Automatické vygenerování souboru `.env` v kořenovém adresáři projektu s přihlašovacími údaji +3. Nastavení všech potřebných proměnných prostředí -**Máte problémy s nasazením?** Podívejte se do [Infrastructure README](infra/README.md) na podrobné řešení problémů, včetně konfliktů názvů poddomén, manuálních kroků nasazení přes Azure Portal a návodu na konfiguraci modelů. +**Máte problémy s nasazením?** Viz [Infrastructure README](infra/README.md) pro podrobné návody k řešení problémů včetně konfliktů názvů subdomén, ručního nasazení přes Azure Portal a návodů k konfiguraci modelu. -**Ověřte úspěšnost nasazení:** +**Ověření úspěšnosti nasazení:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Mělo by zobrazit AZURE_OPENAI_ENDPOINT, API_KEY atd. Get-Content ..\.env # Mělo by zobrazit AZURE_OPENAI_ENDPOINT, API_KEY, atd. ``` -> **Poznámka:** Příkaz `azd up` automaticky generuje `.env` soubor. Pokud ho budete chtít později upravit, můžete buď `.env` soubor editovat ručně, nebo jej znovu vygenerovat spuštěním: +> **Poznámka:** Příkaz `azd up` automaticky generuje `.env` soubor. Pokud ho budete potřebovat později aktualizovat, můžete buď upravit `.env` soubor ručně, nebo ho znovu vygenerovat spuštěním: > > **Bash:** > ```bash @@ -182,12 +182,11 @@ Get-Content ..\.env # Mělo by zobrazit AZURE_OPENAI_ENDPOINT, API_KEY, atd. > .\.azd-env.ps1 > ``` - ## Spuštění aplikace lokálně -**Ověřte nasazení:** +**Ověření nasazení:** -Ujistěte se, že `.env` soubor existuje v kořenovém adresáři s Azure přihlašovacími údaji. Spusťte to z adresáře modulu (`01-introduction/`): +Ujistěte se, že soubor `.env` existuje v kořenovém adresáři s údaji pro Azure. Spusťte to z adresáře modulu (`01-introduction/`): **Bash:** ```bash @@ -201,21 +200,21 @@ Get-Content ..\.env # Mělo by zobrazit AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Spuštění aplikací:** -**Možnost 1: Použití Spring Boot Dashboard (doporučeno pro uživatele VS Code)** +**Možnost 1: Použití Spring Boot Dashboard (doporučeno pro uživatele VS Code)** -Dev kontejner obsahuje rozšíření Spring Boot Dashboard, které poskytuje vizuální rozhraní pro správu všech Spring Boot aplikací. Najdete ho v liště aktivit vlevo ve VS Code (ikona Spring Boot). +Dev container obsahuje rozšíření Spring Boot Dashboard, které poskytuje vizuální rozhraní pro správu všech Spring Boot aplikací. Najdete ho v Activity Bar na levé straně VS Code (ikona Spring Boot). -Ve Spring Boot Dashboard můžete: -- Vidět všechny dostupné Spring Boot aplikace v workspace -- Spouštět/ukončovat aplikace jedním kliknutím -- Sledovat logy aplikací v reálném čase -- Monitorovat stav aplikací +Ze Spring Boot Dashboard můžete: +- Vidět všechny dostupné Spring Boot aplikace v pracovním prostoru +- Spustit/zastavit aplikace jedním kliknutím +- Zobrazit logy aplikací v reálném čase +- Monitorovat stav aplikace -Jednoduše klikněte na tlačítko přehrávání vedle „introduction“ pro spuštění tohoto modulu, nebo spusťte všechny moduly najednou. +Stačí kliknout na tlačítko play vedle "introduction" pro spuštění tohoto modulu, nebo spustit všechny moduly najednou. Spring Boot Dashboard -*Spring Boot Dashboard ve VS Code — spouštějte, ukončujte a sledujte všechny moduly na jednom místě* +*Spring Boot Dashboard ve VS Code — spusťte, zastavte a monitorujte všechny moduly z jednoho místa* **Možnost 2: Použití shell skriptů** @@ -223,7 +222,7 @@ Spusťte všechny webové aplikace (moduly 01-04): **Bash:** ```bash -cd .. # Ze kořenového adresáře +cd .. # Z kořenového adresáře ./start-all.sh ``` @@ -233,7 +232,7 @@ cd .. # Z kořenového adresáře .\start-all.ps1 ``` -Nebo spusťte jen tento modul: +Nebo spusťte pouze tento modul: **Bash:** ```bash @@ -247,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Oba skripty automaticky načtou proměnné prostředí z kořenového `.env` souboru a vytvoří JARy, pokud neexistují. +Oba skripty automaticky načtou proměnné prostředí ze souboru `.env` v kořenovém adresáři a postaví JARy, pokud neexistují. -> **Poznámka:** Pokud chcete všechny moduly nejdříve sestavit ručně před spuštěním: +> **Poznámka:** Pokud chcete nejprve ručně postavit všechny moduly před spuštěním: > > **Bash:** > ```bash @@ -263,13 +262,13 @@ Oba skripty automaticky načtou proměnné prostředí z kořenového `.env` sou > mvn clean package -DskipTests > ``` -Otevřete ve svém prohlížeči http://localhost:8080. +Otevřete v prohlížeči http://localhost:8080. -**Pro zastavení:** +**Zastavení aplikace:** **Bash:** ```bash -./stop.sh # Tento modul pouze +./stop.sh # Pouze tento modul # Nebo cd .. && ./stop-all.sh # Všechny moduly ``` @@ -281,18 +280,17 @@ cd .. && ./stop-all.sh # Všechny moduly cd ..; .\stop-all.ps1 # Všechny moduly ``` - -## Používání aplikace +## Použití aplikace Aplikace poskytuje webové rozhraní se dvěma implementacemi chatu vedle sebe. Application Home Screen -*Přehledová obrazovka ukazující jak Jednoduchý chat (bezstavový), tak Konverzační chat (stavový)* +*Dashboard zobrazuje možnosti Simple Chat (bezstavový) a Conversational Chat (stavový)* ### Bezstavový chat (levý panel) -Vyzkoušejte nejdříve toto. Řekněte „Jmenuji se John“ a hned poté „Jak se jmenuji?“ Model si nebude pamatovat, protože každá zpráva je nezávislá. To demonstruje základní problém integrace jazykového modelu – žádný kontext konverzace. +Vyzkoušejte to jako první. Zeptejte se "Jmenuji se John" a pak okamžitě "Jak se jmenuji?". Model si to nepamatuje, protože každá zpráva je nezávislá. To ukazuje hlavní problém základní integrace jazykového modelu - žádný kontext konverzace. Stateless Chat Demo @@ -300,25 +298,25 @@ Vyzkoušejte nejdříve toto. Řekněte „Jmenuji se John“ a hned poté „Ja ### Stavový chat (pravý panel) -Nyní vyzkoušejte stejnou sekvenci zde. Řekněte „Jmenuji se John“ a pak „Jak se jmenuji?“ Tentokrát si to pamatuje. Rozdíl je MessageWindowChatMemory - udržuje historii konverzace a zahrnuje ji v každém požadavku. Takto funguje produkční konverzační AI. +Nyní vyzkoušejte stejnou sekvenci zde. Zeptejte se "Jmenuji se John" a pak "Jak se jmenuji?". Tentokrát si to pamatuje. Rozdíl je v MessageWindowChatMemory - udržuje historii konverzace a zahrnuje ji s každým požadavkem. Takto funguje produkční konverzační AI. Stateful Chat Demo -*AI si pamatuje vaše jméno z dřívější konverzace* +*AI si pamatuje vaše jméno z předchozí části konverzace* -Oba panely používají stejný GPT-5.2 model. Jediný rozdíl je paměť. To jasně ukazuje, co paměť přináší vaší aplikaci a proč je nezbytná pro skutečné užití. +Oba panely používají stejný model GPT-5.2. Jediný rozdíl je paměť. To jasně ukazuje, co paměť přináší vaší aplikaci a proč je nezbytná pro skutečné použití. ## Další kroky -**Další modul:** [02-prompt-engineering - Návrh promptů s GPT-5.2](../02-prompt-engineering/README.md) +**Další modul:** [02-prompt-engineering - Prompt Engineering s GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigace:** [← Předcházející: Modul 00 - Rychlý start](../00-quick-start/README.md) | [Zpět na hlavní stránku](../README.md) | [Další: Modul 02 - Návrh promptů →](../02-prompt-engineering/README.md) +**Navigace:** [← Zpět na hlavní](../README.md) | [Další: Modul 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- -**Prohlášení o vyloučení odpovědnosti**: -Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho rodném jazyce by měl být považován za závazný zdroj. Pro důležité informace se doporučuje profesionální lidský překlad. Nejsme odpovědni za jakékoli nedorozumění nebo mylné výklady vyplývající z použití tohoto překladu. +**Prohlášení o omezení odpovědnosti**: +Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu. \ No newline at end of file diff --git a/translations/cs/02-prompt-engineering/README.md b/translations/cs/02-prompt-engineering/README.md index e9032124f..25a7b9b06 100644 --- a/translations/cs/02-prompt-engineering/README.md +++ b/translations/cs/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ -# Modul 02: Inženýrství promptů s GPT-5.2 +# Modul 02: Prompt engineering s GPT-5.2 ## Obsah -- [Video procházka](../../../02-prompt-engineering) -- [Co se naučíte](../../../02-prompt-engineering) -- [Požadavky](../../../02-prompt-engineering) -- [Pochopení inženýrství promptů](../../../02-prompt-engineering) -- [Základy inženýrství promptů](../../../02-prompt-engineering) - - [Zero-Shot prompting](../../../02-prompt-engineering) - - [Few-Shot prompting](../../../02-prompt-engineering) - - [Řetězec myšlenek](../../../02-prompt-engineering) - - [Promptování na základě role](../../../02-prompt-engineering) - - [Šablony promptů](../../../02-prompt-engineering) -- [Pokročilé vzory](../../../02-prompt-engineering) -- [Spuštění aplikace](../../../02-prompt-engineering) -- [Snímky obrazovky aplikace](../../../02-prompt-engineering) -- [Prozkoumání vzorů](../../../02-prompt-engineering) - - [Nízká vs vysoká ochota](../../../02-prompt-engineering) - - [Provedení úkolu (Úvodní nástroje)](../../../02-prompt-engineering) - - [Sebereflexivní kód](../../../02-prompt-engineering) - - [Strukturovaná analýza](../../../02-prompt-engineering) - - [Vícekolová konverzace](../../../02-prompt-engineering) - - [Postupné odůvodňování](../../../02-prompt-engineering) - - [Omezený výstup](../../../02-prompt-engineering) -- [Co se skutečně učíte](../../../02-prompt-engineering) -- [Další kroky](../../../02-prompt-engineering) - -## Video procházka - -Podívejte se na tuto živou relaci, která vysvětluje, jak začít s tímto modulem: +- [Video průvodce](#video-průvodce) +- [Co se naučíte](#co-se-naučíte) +- [Požadavky](#požadavky) +- [Pochopení prompt engineeringu](#pochopení-prompt-engineeringu) +- [Základy prompt engineeringu](#základy-prompt-engineeringu) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Promptové šablony](#promptové-šablony) +- [Pokročilé vzory](#pokročilé-vzory) +- [Spuštění aplikace](#spuštění-aplikace) +- [Snímky obrazovky aplikace](#snímky-aplikace) +- [Prozkoumání vzorů](#prozkoumání-vzorů) + - [Nízká vs vysoká ochota](#nízká-vs-vysoká-ochota) + - [Provedení úkolu (tool preambule)](#vykonávání-úkolu-preambuly-nástrojů) + - [Sebereflexivní kód](#sebereflektující-kód) + - [Strukturovaná analýza](#strukturovaná-analýza) + - [Vícekolová konverzace](#vícekrokový-rozhovor) + - [Krok za krokem uvažování](#krok-za-krokem-uvažování) + - [Omezený výstup](#omezený-výstup) +- [Co se skutečně učíte](#co-se-skutečně-učíte) +- [Další kroky](#další-kroky) + +## Video průvodce + +Sledujte tuto živou relaci, která vysvětluje, jak začít s tímto modulem: Prompt Engineering with LangChain4j - Live Session ## Co se naučíte -Následující diagram poskytuje přehled klíčových témat a dovedností, které v tomto modulu rozvinete — od technik zdokonalování promptů po postupný pracovní postup, který budete používat. +Následující diagram poskytuje přehled klíčových témat a dovedností, které v tomto modulu získáte — od technik zdokonalování promptů až po krok za krokem pracovní postup, který budete následovat. Co se naučíte -V předchozích modulech jste prozkoumali základní interakce LangChain4j s GitHub Models a viděli, jak paměť umožňuje konverzační AI s Azure OpenAI. Nyní se zaměříme na to, jak klást otázky — tedy samotné prompty — pomocí GPT-5.2 od Azure OpenAI. Způsob, jakým strukturalizujete své prompty, dramaticky ovlivňuje kvalitu odpovědí, které obdržíte. Začneme přehledem základních technik prompting, poté přejdeme k osmi pokročilým vzorům, které plně využívají možnosti GPT-5.2. +V předchozím modulu jste viděli, jak paměť umožňuje konverzační AI s Azure OpenAI. Nyní se zaměříme na to, jak pokládat otázky — tedy samotné prompty — s použitím Azure OpenAI GPT-5.2. Způsob, jak prompt strukturalizujete, dramaticky ovlivňuje kvalitu odpovědí, které získáte. Začneme přehledem základních technik promptování, poté přejdeme k osmi pokročilým vzorům, které plně využívají schopnosti GPT-5.2. -Použijeme GPT-5.2, protože zavádí kontrolu odůvodnění — můžete modelu říci, kolik přemýšlení má před odpovědí provést. To dělá různé strategie prompting zřetelnějšími a pomáhá vám pochopit, kdy použít každý přístup. Také využijeme méně restriktivní limity Azure pro GPT-5.2 ve srovnání s GitHub Models. +Použijeme GPT-5.2, protože zavádí kontrolu uvažování — můžete modelu říct, kolik uvažování má před odpovědí provést. To jinak přístupy k promptování výrazně odlišuje a pomáhá vám pochopit, kdy použít který způsob. ## Požadavky -- Dokončen Modul 01 (nasazené Azure OpenAI zdroje) -- `.env` soubor v kořenovém adresáři s přihlašovacími údaji Azure (vytvořený pomocí `azd up` v Modulu 01) +- Dokončen Modul 01 (nasazení zdrojů Azure OpenAI) +- Soubor `.env` v kořenovém adresáři s přihlašovacími údaji Azure (vytvořený příkazem `azd up` v Modulu 01) -> **Poznámka:** Pokud jste Modulu 01 nedokončili, nejprve postupujte podle tamních pokynů k nasazení. +> **Poznámka:** Pokud jste Modul 01 nedokončili, nejprve postupujte podle pokynů k nasazení tam. -## Pochopení inženýrství promptů +## Pochopení prompt engineeringu -Inženýrství promptů je v jádru rozdílem mezi vágními a přesnými instrukcemi, jak ukazuje následující srovnání. +V jádru je prompt engineering rozdíl mezi vágními a přesnými instrukcemi, jak ukazuje následující srovnání. -Co je inženýrství promptů? +Co je prompt engineering? -Inženýrství promptů znamená navrhování vstupního textu, který vám konzistentně přinese požadované výsledky. Nejde jen o kladení otázek — jde o strukturování požadavků tak, aby model přesně pochopil, co chcete, a jak to má dodat. +Prompt engineering znamená navrhování vstupního textu, který vám konzistentně přinese požadované výsledky. Nejde jen o pokládání otázek — jde o strukturování požadavků tak, aby model přesně pochopil, co chcete, a jak to má dodat. -Představte si to jako dávaní instrukcí kolegovi. „Oprav chybu“ je vágní. „Oprav výjimku null pointer v UserService.java na řádku 45 přidáním kontroly na null“ je specifické. Jazykové modely fungují stejným způsobem — záleží na přesnosti a struktuře. +Představte si to jako dávání instrukcí kolegovi. "Oprav chybu" je vágní. "Oprav nulový ukazatel výjimky v UserService.java řádek 45 přidáním kontroly na null" je konkrétní. Jazykové modely fungují stejně — specifita a struktura jsou důležité. -Diagram níže ukazuje, jak do tohoto obrazu zapadá LangChain4j — spojuje vaše vzory promptů s modelem pomocí stavebních bloků SystemMessage a UserMessage. +Níže je diagram, který ukazuje, jak LangChain4j sedí do tohoto obrazu — propojuje vzory promptů s modelem pomocí komponent SystemMessage a UserMessage. Jak LangChain4j zapadá -LangChain4j poskytuje infrastrukturu — připojení k modelu, paměť a typy zpráv — zatímco vzory promptů jsou pouze pečlivě strukturovaný text, který touto infrastrukturou posíláte. Klíčovými stavebními bloky jsou `SystemMessage` (který nastavuje chování a roli AI) a `UserMessage` (který nese váš skutečný požadavek). +LangChain4j poskytuje infrastrukturu — připojení k modelu, paměť a typy zpráv — zatímco vzory promptů jsou jen pečlivě strukturovaný text, který touto infrastrukturou posíláte. Klíčové stavební bloky jsou `SystemMessage` (který nastavuje chování a roli AI) a `UserMessage` (který nese váš skutečný požadavek). -## Základy inženýrství promptů +## Základy prompt engineeringu -Pět základních technik uvedených níže tvoří základ efektivního inženýrství promptů. Každá řeší jiný aspekt komunikace s jazykovými modely. +Pět základních technik níže tvoří základ efektivního prompt engineeringu. Každá řeší jiný aspekt, jak komunikovat s jazykovými modely. -Přehled pěti vzorů inženýrství promptů +Přehled pěti vzorů prompt engineeringu -Než se pustíme do pokročilých vzorů v tomto modulu, připomeňme si pět základních technik promptování. Tyto jsou stavebními kameny, které by měl znát každý prompt inženýr. Pokud jste již prošli [Rychlý start modul](../00-quick-start/README.md#2-prompt-patterns), viděli jste je v akci — zde je konceptuální rámec za nimi. +Než se ponoříme do pokročilých vzorů v tomto modulu, připomeňme si pět základních technik promptování. Jsou to stavební kameny, které by měl znát každý prompt engineer. -### Zero-Shot prompting +### Zero-Shot Prompting -Nejjednodušší přístup: dejte modelu přímý pokyn bez příkladů. Model se zcela spoléhá na své tréninkové znalosti, aby pochopil a vykonal úkol. Funguje to dobře pro přímočaré požadavky, kde je očekávané chování zřejmé. +Nejjednodušší přístup: dejte modelu přímý příkaz bez příkladů. Model se spoléhá zcela na své tréninkové znalosti, aby úkol pochopil a vykonal. Funguje to dobře u přímočarých požadavků, kde je očekávané chování zřejmé. -Zero-Shot prompting +Zero-Shot Prompting -*Přímý pokyn bez příkladů — model vyvozuje úkol pouze z pokynu* +*Přímá instrukce bez příkladů — model odvozuje úkol pouze z instrukce* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Odpověď: "Pozitivní" ``` -**Kdy použít:** Jednoduché klasifikace, přímé otázky, překlady nebo jakýkoli úkol, který model zvládne bez dalšího vedení. +**Kdy použít:** Jednoduché klasifikace, přímé otázky, překlady nebo jakýkoliv úkol, který model zvládá bez dalšího vedení. -### Few-Shot prompting +### Few-Shot Prompting -Poskytněte příklady, které ukazují vzor, podle kterého má model postupovat. Model se z vašich příkladů naučí očekávaný vstupně-výstupní formát a aplikuje ho na nové vstupy. To výrazně zlepšuje konzistenci u úkolů, kde požadovaný formát nebo chování není zřejmé. +Dejte příklady, které demonstrují vzor, podle kterého má model postupovat. Model se naučí očekávaný vstupně-výstupní formát z vašich příkladů a aplikuje ho na nové vstupy. To výrazně zlepšuje konzistenci u úkolů, kde požadovaný formát nebo chování není zřejmé. -Few-Shot prompting +Few-Shot Prompting -*Učení z příkladů — model rozpoznává vzor a aplikuje ho na nové vstupy* +*Učení z příkladů — model identifikuje vzor a aplikuje ho na nové vstupy* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kdy použít:** Vlastní klasifikace, konzistentní formátování, úkoly specifické pro doménu nebo pokud jsou výsledky zero-shot nekonzistentní. +**Kdy použít:** Vlastní klasifikace, konzistentní formátování, úkoly z konkrétních domén nebo když jsou výsledky zero-shot nekonzistentní. -### Řetězec myšlenek +### Chain of Thought -Požádejte model, aby ukázal své odůvodnění krok za krokem. Místo aby skočil rovnou k odpovědi, model rozdělí problém a explicitně projde každý krok. To zlepšuje přesnost u matematických, logických a vícekrokových úkolů. +Požádejte model, aby ukázal své uvažování krok za krokem. Místo skoku rovnou k odpovědi rozebírá problém a postupně prochází každou část explicitně. To zlepšuje přesnost u matematických, logických a vícestupňových úloh. -Řetězec myšlenek +Chain of Thought Prompting -*Postupné odůvodňování — rozdělení složitých problémů do explicitních logických kroků* +*Krok za krokem uvažování — rozklad složitých problémů na explicitní logické kroky* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Model ukazuje: 15 - 8 = 7, pak 7 + 12 = 19 jablek ``` -**Kdy použít:** Matematické úlohy, logické hádanky, ladění nebo jakýkoli úkol, kde zobrazení procesu odůvodnění zvyšuje přesnost a důvěru. +**Kdy použít:** Matematické problémy, logické hádanky, ladění chyb nebo jakýkoliv úkol, kde zobrazení uvažovacího procesu zlepšuje přesnost a důvěru. -### Promptování na základě role +### Role-Based Prompting -Než položíte otázku, nastavte AI osobnost nebo roli. To poskytuje kontext, který formuje tón, hloubku a zaměření odpovědi. „Softwarový architekt“ poskytne jiné rady než „junior vývojář“ nebo „auditor bezpečnosti“. +Nastavte AI personu nebo roli předtím, než položíte otázku. To poskytuje kontext, který formuje tón, hloubku a zaměření odpovědi. „Softwarový architekt“ dá jiné rady než „junior programátor“ nebo „auditor bezpečnosti“. -Promptování na základě role +Role-Based Prompting -*Nastavení kontextu a osobnosti — stejná otázka dostane jinou odpověď podle přiřazené role* +*Nastavení kontextu a persony — stejná otázka dostane různou odpověď podle přiřazené role* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kdy použít:** Kontroly kódu, doučování, doménové analýzy nebo když potřebujete odpovědi přizpůsobené určité úrovni odbornosti či perspektivě. +**Kdy použít:** Revize kódu, doučování, analýzy specifické domény nebo když potřebujete odpovědi přizpůsobené určité úrovni odbornosti nebo perspektivě. -### Šablony promptů +### Promptové šablony -Vytvářejte znovupoužitelné prompty s proměnnými zástupci. Místo psaní nového promptu pokaždé definujte šablonu jednou a plňte ji různými hodnotami. Třída `PromptTemplate` v LangChain4j to usnadňuje pomocí syntaxe `{{variable}}`. +Vytvářejte znovupoužitelné prompty s proměnnými zástupnými znaky. Místo psaní nového promptu pokaždé definujte šablonu jednou a vyplňte různými hodnotami. Třída `PromptTemplate` z LangChain4j to usnadňuje syntaxí `{{variable}}`. -Šablony promptů +Prompt Templates -*Znovupoužitelné prompty s proměnnými zástupci — jedna šablona, mnoho použití* +*Znovupoužitelné prompty s proměnnými zástupnými znaky — jedna šablona, mnoho použití* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Kdy použít:** Opakované dotazy s různými vstupy, dávkové zpracování, budování znovupoužitelných AI workflow, nebo kdekoliv, kde struktura promptu zůstává stejná, ale data se mění. +**Kdy použít:** Opakované dotazy s různými vstupy, hromadné zpracování, budování znovupoužitelných AI pracovních postupů nebo jakákoli situace, kde struktura promptu zůstává stejná, ale data se mění. --- -Těchto pět základů vám dává pevný arzenál pro většinu promptingových úkolů. Zbytek tohoto modulu na nich staví pomocí **osmi pokročilých vzorů**, které využívají kontrolu odůvodnění GPT-5.2, sebehodnocení a schopnosti strukturovaného výstupu. +Těchto pět základů vám dá pevnou sadu nástrojů pro většinu promptovacích úkolů. Zbytek tohoto modulu na ně staví s **osmi pokročilými vzory**, které využívají řízení uvažování GPT-5.2, sebehodnocení a schopnosti strukturovaného výstupu. ## Pokročilé vzory -Po pokrytí základů přejděme k osmi pokročilým vzorům, které činí tento modul unikátním. Ne každý problém vyžaduje stejný přístup. Některé otázky chtějí rychlé odpovědi, jiné hluboké přemýšlení. Některé potřebují viditelné odůvodnění, jiné jen výsledky. Každý níže uvedený vzor je optimalizován pro jiný scénář — a kontrola odůvodnění GPT-5.2 rozdíly ještě více zdůrazňuje. +Po pokrytí základů přejděme k osmi pokročilým vzorům, které tento modul činí výjimečným. Ne všechny problémy vyžadují stejný přístup. Některé otázky potřebují rychlé odpovědi, jiné hluboké zamyšlení. Některé potřebují viditelné uvažování, jiné jen výsledky. Každý vzor níže je optimalizován pro jiný scénář — a řízení uvažování GPT-5.2 dělá rozdíly ještě zřetelnější. Osm vzorů promptování -*Přehled osmi vzorů inženýrství promptů a jejich užití* +*Přehled osmi vzorů prompt engineeringu a jejich použití* -GPT-5.2 přidává další dimenzi k těmto vzorům: *kontrolu odůvodnění*. Posuvník níže ukazuje, jak můžete upravit úsilí modelu o myšlení — od rychlých přímých odpovědí po hlubokou a důkladnou analýzu. +GPT-5.2 přidává dalším rozměrem k těmto vzorům: *řízení uvažování*. Posuvník níže ukazuje, jak můžete upravit množství myšlení modelu — od rychlých, přímých odpovědí po hlubokou, důkladnou analýzu. -Kontrola odůvodnění s GPT-5.2 +Řízení uvažování s GPT-5.2 -*Kontrola odůvodnění GPT-5.2 vám umožňuje určit, kolik přemýšlení má model udělat — od rychlých přímých odpovědí po hluboké zkoumání* +*Řízení uvažování GPT-5.2 vám umožňuje určit, kolik uvažování má model provést — od rychlých přímých odpovědí po hluboké zkoumání* -**Nízká ochota (rychlé a cílené)** - Pro jednoduché otázky, kde chcete rychlé, přímé odpovědi. Model dělá minimální odůvodnění - maximálně 2 kroky. Použijte to pro výpočty, vyhledávání nebo přímočaré otázky. +**Nízká ochota (rychlé a zaměřené)** - Pro jednoduché otázky, kde chcete rychlé, přímé odpovědi. Model provádí minimální uvažování - maximálně 2 kroky. Použijte pro výpočty, vyhledávání nebo přímočaré otázky. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Prozkoumejte s GitHub Copilot:** Otevřete [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) a zeptejte se: -> - „Jaký je rozdíl mezi nízkou a vysokou ochotou ve vzorech prompting?“ -> - „Jak pomáhají XML tagy v promptech strukturovat odpověď AI?“ -> - „Kdy mám použít vzory sebereflexe vs přímé instrukce?“ +> - "Jaký je rozdíl mezi nízkou a vysokou ochotou u vzorů promptování?" +> - "Jak XML tagy v promptech pomáhají strukturovat odpověď AI?" +> - "Kdy použít sebereflexivní vzory versus přímé instrukce?" -**Vysoká ochota (hluboké a důkladné)** - Pro složité problémy, kde chcete komplexní analýzu. Model důkladně zkoumá a ukazuje podrobné odůvodnění. Použijte to pro návrh systému, architektonická rozhodnutí nebo složitý výzkum. +**Vysoká ochota (hluboké a důkladné)** - Pro složité problémy, kde chcete komplexní analýzu. Model zkoumá důkladně a ukazuje podrobné uvažování. Použijte pro návrhy systémů, architektonická rozhodnutí nebo složitý výzkum. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Provedení úkolu (postupný pokrok)** - Pro vícekrokové pracovní postupy. Model předem poskytne plán, narraci každého kroku během práce a nakonec shrnutí. Použijte to pro migrace, implementace nebo jakýkoli vícekrokový proces. +**Provedení úkolu (postup krok za krokem)** - Pro vícestupňové pracovní postupy. Model poskytne úvodní plán, průběžně vysvětluje každý krok a pak dá shrnutí. Použijte pro migrace, implementace nebo jakýkoliv vícestupňový proces. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Řetězcové prompting explicitně žádá model, aby ukázal proces svého odůvodnění, což zlepšuje přesnost u složitých úkolů. Postupné rozklady pomáhají lidem i AI pochopit logiku. +Chain-of-Thought promptování explicitně žádá model, aby ukázal svůj uvažovací proces, což zvyšuje přesnost u složitých úloh. Postupné rozebrání pomáhá lidem i AI chápat logiku. > **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Zeptejte se na tento vzor: -> - „Jak bych přizpůsobil vzor provedení úkolu pro dlouhotrvající operace?“ -> - „Jaké jsou nejlepší postupy pro strukturování úvodních nástrojů v produkčních aplikacích?“ -> - „Jak mohu zachytit a zobrazit průběžné aktualizace pokroku v UI?“ +> - "Jak bych přizpůsobil vzor provedení úkolu pro dlouhodobé operace?" +> - "Jaké jsou nejlepší praktiky pro strukturování tool preambulí v produkčních aplikacích?" +> - "Jak zachytit a zobrazit průběžné aktualizace průběhu v uživatelském rozhraní?" -Diagram níže ilustruje tento pracovní postup Plán → Provedení → Shrnutí. +Níže je diagram, který ilustruje tento pracovní postup Plán → Provedení → Shrnutí. Vzor provedení úkolu -*Pracovní postup Plán → Provedení → Shrnutí pro vícekrokové úkoly* +*Pracovní postup Plán → Provedení → Shrnutí pro vícestupňové úkoly* -**Sebereflexivní kód** - Pro generování produkčního kódu. Model generuje kód podle produkčních standardů s patřičnou obsluhou chyb. Používejte to při budování nových funkcí nebo služeb. +**Sebereflexivní kód** - Pro generování kódu kvality pro produkci. Model generuje kód podle produkčních standardů s řádným ošetřením chyb. Použijte při budování nových funkcí nebo služeb. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagram níže ukazuje tento iterativní cyklus vylepšování — generování, hodnocení, identifikace slabých míst a zdokonalování, dokud kód neodpovídá produkčním standardům. +Níže je diagram této iterativní smyčky zdokonalování — generuj, vyhodnoť, identifikuj slabiny a zdokonaluj, dokud kód nesplní produkční požadavky. Cyklus sebereflexe -*Iterativní smyčka zlepšování - generuj, hodnot, identifikuj problémy, zlepšuj, opakuj* +*Iterativní smyčka zdokonalování - generuj, vyhodnoť, identifikuj problémy, zlepšuj, opakuj* -**Strukturovaná analýza** - Pro konzistentní hodnocení. Model kontroluje kód pomocí pevného rámce (správnost, postupy, výkon, bezpečnost, udržovatelnost). Použijte to pro kontroly kódu nebo hodnocení kvality. +**Strukturovaná analýza** - Pro konzistentní hodnocení. Model přezkoumá kód podle pevného rámce (správnost, praktiky, výkon, bezpečnost, udržovatelnost). Použijte při revizích kódu nebo hodnocení kvality. ```java String prompt = """ @@ -355,17 +355,17 @@ String response = chatModel.chat(prompt); ``` > **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Zeptejte se na strukturovanou analýzu: -> - „Jak mohu přizpůsobit rámec analýzy pro různé typy kontrol kódu?“ -> - „Jak nejlépe zpracovat a programově reagovat na strukturovaný výstup?“ -> - „Jak zajistím konzistentní úrovně závažnosti v různých recenzních sezeních?“ +> - "Jak přizpůsobit rámec analýzy pro různé typy revizí kódu?" +> - "Jak nejlépe zpracovat a programově reagovat na strukturovaný výstup?" +> - "Jak zajistit konzistentní úrovně závažnosti napříč různými revizními sezeními?" -Následující diagram ukazuje, jak tento strukturovaný rámec organizuje kontrolu kódu do konzistentních kategorií s úrovněmi závažnosti. +Následující diagram ukazuje, jak tento strukturovaný rámec organizuje revizi kódu do konzistentních kategorií se závažnostmi. Vzor strukturované analýzy -*Rámec pro konzistentní kontroly kódu s úrovněmi závažnosti* +*Rámec pro konzistentní revize kódu se závažnostmi* -**Vícekolová konverzace** - Pro konverzace, které vyžadují kontext. Model si pamatuje předchozí zprávy a staví na nich. Použijte to pro interaktivní pomoc nebo komplexní otázky a odpovědi. +**Vícekolová konverzace** - Pro konverzace, které potřebují kontext. Model si pamatuje předchozí zprávy a staví na nich. Použijte pro interaktivní podpůrné relace nebo složité otázky a odpovědi. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Diagram níže vizualizuje, jak se konverzační kontext hromadí s každým kolem a jak souvisí s limitem tokenů modelu. +Níže vizualizace ukazuje, jak se konverzační kontext hromadí s každým kolem a jak to souvisí s limitem tokenů modelu. Paměť kontextu -*Jak se konverzační kontext hromadí přes více kol až do dosažení limitu tokenů* -**Krok za krokem zdůvodnění** – Pro problémy vyžadující viditelnou logiku. Model ukazuje explicitní zdůvodnění pro každý krok. Použijte to pro matematické problémy, logické hádanky nebo když potřebujete pochopit myšlenkový proces. +*Jak se konverzační kontext hromadí během více kol až do dosažení limitu tokenů* + +**Krok za krokem uvažování** - Pro problémy vyžadující viditelnou logiku. Model zobrazuje explicitní uvažování pro každý krok. Použijte pro matematické problémy, logické hádanky nebo kdy potřebujete pochopit myšlenkový proces. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Níže uvedený diagram ilustruje, jak model rozděluje problémy na explicitní, číslované logické kroky. - -Step-by-Step Pattern +Níže je diagram, který ilustruje, jak model rozděluje problémy na explicitní, číslované logické kroky. +Vzor krok za krokem *Rozklad problémů na explicitní logické kroky* -**Omezený výstup** – Pro odpovědi s konkrétními požadavky na formát. Model přísně dodržuje pravidla formátu a délky. Použijte to pro shrnutí nebo pokud potřebujete přesnou strukturu výstupu. +**Omezený výstup** - Pro odpovědi s konkrétními požadavky na formát. Model přesně dodržuje pravidla formátu a délky. Použijte to pro souhrny nebo když potřebujete přesnou strukturu výstupu. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Následující diagram ukazuje, jak omezení vedou model k tomu, aby produkoval výstup, který striktně dodržuje vaše požadavky na formát a délku. +Následující diagram ukazuje, jak omezení vedou model k produkci výstupu, který přesně vyhovuje vašim požadavkům na formát a délku. -Constrained Output Pattern +Vzor omezeného výstupu -*Prosazování konkrétních požadavků na formát, délku a strukturu* +*Vynucení specifických požadavků na formát, délku a strukturu* ## Spuštění aplikace **Ověření nasazení:** -Ujistěte se, že soubor `.env` existuje v kořenovém adresáři s přihlašovacími údaji Azure (vytvořen během modulu 01). Spusťte to z adresáře modulu (`02-prompt-engineering/`): +Ujistěte se, že soubor `.env` existuje v kořenovém adresáři a obsahuje Azure přihlašovací údaje (vytvořené během modulu 01). Spusťte to z adresáře modulu (`02-prompt-engineering/`): **Bash:** ```bash @@ -444,31 +444,31 @@ Get-Content ..\.env # Mělo by zobrazovat AZURE_OPENAI_ENDPOINT, API_KEY, DEPLO **Spuštění aplikace:** -> **Poznámka:** Pokud jste již spustili všechny aplikace pomocí `./start-all.sh` z kořenového adresáře (jak je popsáno v modulu 01), tento modul už běží na portu 8083. Můžete přeskočit příkazy pro spuštění níže a jít přímo na http://localhost:8083. +> **Poznámka:** Pokud jste již spustili všechny aplikace pomocí `./start-all.sh` z kořenového adresáře (jak je popsáno v modulu 01), tento modul již běží na portu 8083. Můžete tedy přeskočit níže uvedené spouštěcí příkazy a přejít přímo na http://localhost:8083. **Možnost 1: Použití Spring Boot Dashboard (doporučeno pro uživatele VS Code)** -Vývojové prostředí obsahuje rozšíření Spring Boot Dashboard, které poskytuje vizuální rozhraní pro správu všech Spring Boot aplikací. Najdete ho v Activity Bar na levé straně VS Code (hledejte ikonu Spring Boot). +Vývojový kontejner obsahuje rozšíření Spring Boot Dashboard, které poskytuje vizuální rozhraní pro správu všech Spring Boot aplikací. Najdete ho v panelu aktivit vlevo ve VS Code (hledejte ikonu Spring Boot). -Z Spring Boot Dashboard můžete: -- Vidět všechny dostupné Spring Boot aplikace v pracovním prostoru -- Spustit/zastavit aplikace jedním kliknutím -- Zobrazit logy aplikací v reálném čase +Ze Spring Boot Dashboard můžete: +- Vidět všechny dostupné Spring Boot aplikace v pracovní ploše +- Jedním kliknutím spustit/zastavit aplikace +- Sledovat logy aplikace v reálném čase - Monitorovat stav aplikace -Jednoduše klikněte na tlačítko přehrávání vedle "prompt-engineering" pro spuštění tohoto modulu, nebo spusťte všechny moduly najednou. +Jednoduše klikněte na tlačítko „play“ vedle „prompt-engineering“ pro spuštění tohoto modulu, nebo spusťte všechny moduly současně. Spring Boot Dashboard -*Spring Boot Dashboard ve VS Code — spouštění, zastavování a monitorování všech modulů z jednoho místa* +*Spring Boot Dashboard ve VS Code — spuštění, zastavení a sledování všech modulů na jednom místě* **Možnost 2: Použití shell skriptů** -Spusťte všechny webové aplikace (moduly 01-04): +Spusťte všechny webové aplikace (moduly 01–04): **Bash:** ```bash -cd .. # Ze základního adresáře +cd .. # Z kořenového adresáře ./start-all.sh ``` @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Oba skripty automaticky načtou proměnné prostředí z kořenového souboru `.env` a sestaví JARy, pokud neexistují. +Oba skripty automaticky načítají proměnné prostředí ze souboru `.env` v kořenovém adresáři a postaví JARy, pokud neexistují. -> **Poznámka:** Pokud chcete před spuštěním ručně sestavit všechny moduly: +> **Poznámka:** Pokud dáváte přednost manuálnímu sestavení všech modulů před spuštěním: > > **Bash:** > ```bash @@ -508,7 +508,7 @@ Oba skripty automaticky načtou proměnné prostředí z kořenového souboru `. > mvn clean package -DskipTests > ``` -Otevřete v prohlížeči http://localhost:8083. +Otevřete http://localhost:8083 ve svém prohlížeči. **Pro zastavení:** @@ -526,83 +526,83 @@ cd .. && ./stop-all.sh # Všechny moduly cd ..; .\stop-all.ps1 # Všechny moduly ``` -## Snímky obrazovek aplikace +## Snímky aplikace -Zde je hlavní rozhraní modulu prompt engineering, kde můžete experimentovat se všemi osmi vzory vedle sebe. +Zde je hlavní rozhraní modulu pro prompt engineering, kde můžete experimentovat se všemi osmi vzory vedle sebe. -Dashboard Home +Hlavní panel -*Hlavní panel zobrazující všech 8 vzorů prompt engineeringu s jejich charakteristikami a případy použití* +*Hlavní panel zobrazuje všech 8 vzorů prompt engineeringu s jejich charakteristikami a použitím* ## Prozkoumání vzorů -Webové rozhraní umožňuje experimentovat s různými strategiemi promptování. Každý vzor řeší jiné problémy – vyzkoušejte je a uvidíte, kdy který přístup vyniká. +Webové rozhraní umožňuje experimentovat s různými strategiemi zadávání. Každý vzor řeší jiné problémy – vyzkoušejte je a zjistěte, kdy který přístup exceluje. -> **Poznámka: Streamování vs Nestreamování** — Každá stránka vzoru nabízí dvě tlačítka: **🔴 Stream Response (živě)** a možnost **Nestreamování**. Streamování používá Server-Sent Events (SSE) k zobrazování tokenů v reálném čase, jak je model generuje, takže okamžitě vidíte pokrok. Nestreamová volba čeká na celou odpověď, než ji zobrazí. U promptů, které spouštějí hluboké zdůvodňování (např. High Eagerness, Self-Reflecting Code), může volání bez streamování trvat velmi dlouho – někdy minuty – bez viditelné zpětné vazby. **Při experimentování s komplexními promptami používejte streamování**, abyste viděli model pracovat a vyhnuli se dojmu, že požadavek časově vypršel. +> **Poznámka: Streamování vs Nestreamování** — Každá stránka vzoru nabízí dvě tlačítka: **🔴 Stream Response (Live)** a možnost **Nestreamování**. Streamování používá Server-Sent Events (SSE), aby zobrazilo tokeny v reálném čase, jak je model generuje, takže okamžitě vidíte postup. Nestreamovaná volba čeká na celou odpověď, než ji zobrazí. U promptů, které vyvolávají hluboké uvažování (např. High Eagerness, Self-Reflecting Code), může nestreamované volání trvat velmi dlouho – někdy minuty – bez viditelné zpětné vazby. **Při experimentování s komplexními prompty používejte streamování**, abyste viděli, jak model pracuje, a předešli dojmu, že požadavek vypršel. > -> **Poznámka: Požadavek na prohlížeč** — Streamovací funkce používá Fetch Streams API (`response.body.getReader()`), které vyžaduje plnohodnotný prohlížeč (Chrome, Edge, Firefox, Safari). NEfunguje ve vestavěném Simple Browseru VS Code, protože jeho webview nepodporuje ReadableStream API. Pokud používáte Simple Browser, tlačítka pro nestreamování budou fungovat normálně — problém se týká pouze streamovacích tlačítek. Pro plný zážitek otevřete `http://localhost:8083` v externím prohlížeči. +> **Poznámka: Požadavky na prohlížeč** — Funkce streamování používá Fetch Streams API (`response.body.getReader()`), které vyžaduje plnohodnotný prohlížeč (Chrome, Edge, Firefox, Safari). Nepracuje v integrovaném Simple Browseru VS Code, protože jeho webview nepodporuje API ReadableStream. Pokud používáte Simple Browser, nestreamovaná tlačítka fungují normálně – pouze streamovaná tlačítka jsou ovlivněna. Pro plný zážitek otevřete `http://localhost:8083` v externím prohlížeči. -### Nízká vs Vysoká zaujatost +### Nízká vs vysoká ochota -Zeptejte se jednoduchou otázku jako „Co je 15 % ze 200?“ pomocí Nízké zaujatosti. Dostanete okamžitou, přímou odpověď. Nyní se zeptejte na něco složitého jako „Navrhni caching strategii pro API s vysokým provozem“ pomocí Vysoké zaujatosti. Klikněte na **🔴 Stream Response (živě)** a sledujte detailní zdůvodnění modelu token po tokenu. Stejný model, stejná struktura otázky – ale prompt mu říká, kolik přemýšlení má věnovat. +Zeptejte se jednoduché otázky jako „Co je 15 % ze 200?“ s nízkou ochotou. Dostanete okamžitou, přímočaře danou odpověď. Teď položte něco složitého, například „Navrhni caching strategii pro vysoce zatížené API“ s vysokou ochotou. Klikněte na **🔴 Stream Response (Live)** a sledujte, jak se modelovo podrobné uvažování objevuje token po tokenu. Stejný model, stejná struktura otázky – ale prompt mu říká, kolik má přemýšlet. -### Provádění úkolů (úvodní nástroje) +### Vykonávání úkolu (preambuly nástrojů) -Vícekrokové pracovní postupy těží z předběžného plánování a komentáře průběhu. Model popisuje, co udělá, komentuje každý krok a poté shrnuje výsledky. +Vícekrokové pracovní postupy těží z předběžného plánování a popisu průběhu. Model popíše, co udělá, komentuje každý krok a nakonec shrne výsledky. -### Sebereflexivní kód +### Sebereflektující kód -Zkuste „Vytvoř službu validace e-mailu“. Místo toho, aby model jen vygeneroval kód a zastavil se, generuje, hodnotí podle kritérií kvality, identifikuje slabá místa a vylepšuje. Uvidíte, jak kód opakovaně upravuje, dokud nevyhoví produkčním standardům. +Vyzkoušejte „Vytvoř službu pro validaci e-mailů“. Místo toho, aby jen vytvořil kód a skončil, model generuje, hodnotí vůči kvalitativním kritériím, identifikuje slabiny a zlepšuje ho. Uvidíte ho iterovat, dokud kód nesplní produkční standardy. ### Strukturovaná analýza -Revize kódu potřebují konzistentní hodnotící rámce. Model analyzuje kód podle pevných kategorií (správnost, postupy, výkon, bezpečnost) s úrovněmi závažnosti. +Kontroly kódu vyžadují konzistentní hodnoticí rámce. Model analyzuje kód podle pevně daných kategorií (správnost, postupy, výkon, bezpečnost) s úrovněmi závažnosti. -### Vícekolový chat +### Vícekrokový rozhovor -Zeptejte se „Co je Spring Boot?“ a hned pak pokračujte s „Ukaž mi příklad“. Model si pamatuje vaši první otázku a dává vám konkrétní příklad Spring Bootu. Bez paměti by druhá otázka byla moc vágní. +Zeptejte se „Co je Spring Boot?“ a hned potom „Ukaž mi příklad“. Model si pamatuje první otázku a poskytne vám konkrétní příklad spring bootu. Bez paměti by druhá otázka byla příliš vágní. -### Krok za krokem zdůvodnění +### Krok za krokem uvažování -Vyberte matematický problém a vyzkoušejte jej s Krok za krokem zdůvodněním i Nízkou zaujatostí. Nízká zaujatost jen dá odpověď – rychle, ale neprůhledně. Krok za krokem vám ukáže každý výpočet a rozhodnutí. +Vyberte si matematický problém a vyzkoušejte ho s krokovým uvažováním i s nízkou ochotou. Nízká ochota vám dá jen odpověď – rychle, ale nejasně. Krok za krokem ukazuje každý výpočet a rozhodnutí. ### Omezený výstup -Když potřebujete konkrétní formáty nebo počet slov, tento vzor striktně dodržuje pravidla. Vyzkoušejte generovat shrnutí s přesně 100 slovy v odrážkách. +Když potřebujete specifické formáty nebo délku textu, tento vzor vynucuje přísné dodržení. Zkuste vytvořit souhrn přesně o 100 slovech v bodech. -## Co se opravdu učíte +## Co se skutečně učíte -**Úsilí o zdůvodnění mění vše** +**Úsilí o uvažování mění všechno** -GPT-5.2 vám umožňuje ovládat výpočetní úsilí přes vaše prompty. Nízké úsilí znamená rychlé odpovědi s minimálním průzkumem. Vysoké úsilí znamená, že model věnuje čas hlubokému přemýšlení. Učíte se přizpůsobovat úsilí složitosti úkolu – neztrácejte čas na jednoduché otázky, ale nespěchejte ani u složitých rozhodnutí. +GPT-5.2 vám umožňuje ovládat výpočetní úsilí skrze vaše prompty. Nízké úsilí znamená rychlé odpovědi s minimálním zkoumáním. Vysoké úsilí znamená, že model si dává načas a hluboce přemýšlí. Učíte se přizpůsobovat úsilí složitosti úkolu – neztrácejte čas s jednoduchými otázkami, ale ani nespěchejte u složitých rozhodnutí. **Struktura vede chování** -Všimli jste si XML značek v promptech? Nejsou dekorativní. Modely spolehlivěji sledují strukturované instrukce než volný text. Když potřebujete vícekrokové procesy nebo složitou logiku, struktura pomáhá modelu sledovat, kde je a co přijde dál. Níže uvedený diagram rozkládá dobře strukturovaný prompt a ukazuje, jak značky jako ``, ``, ``, ``, a `` organizují vaše instrukce do jasných sekcí. +Všimli jste si XML tagů v prompty? Nejsou jen dekorativní. Modely spolehlivěji dodržují strukturované instrukce než volný text. Když potřebujete vícekrokové procesy nebo složitou logiku, struktura pomáhá modelu sledovat, kde je a co přijde dál. Níže uvedený diagram rozebírá dobře strukturovaný prompt a ukazuje, jak tagy jako ``, ``, ``, `` a `` organizují vaše pokyny do přehledných sekcí. -Prompt Structure +Struktura promptu *Anatomie dobře strukturovaného promptu s jasnými sekcemi a organizací ve stylu XML* -**Kvalita díky sebehodnocení** +**Kvalita prostřednictvím sebehodnocení** -Sebereflexivní vzory fungují tak, že dělají kritéria kvality explicitní. Místo toho, aby se model jen doufal, že „to udělá správně“, přesně mu říkáte, co znamená „správně“: správná logika, ošetření chyb, výkon, bezpečnost. Model pak může vyhodnotit svůj vlastní výstup a zlepšit se. To proměňuje generování kódu z loterie na proces. +Sebereflektující vzory fungují tak, že zpřesňují kritéria kvality. Místo doufání, že model „to udělá správně“, mu přesně říkáte, co znamená „správně“: správná logika, ošetření chyb, výkon, bezpečnost. Model pak může vlastní výstup vyhodnotit a vylepšit. To proměňuje generování kódu z loterie na proces. **Kontext je omezený** -Vícekolové konverzace fungují tak, že každému požadavku se přidává historie zpráv. Ale existuje limit – každý model má maximální počet tokenů. Jak konverzace roste, budete potřebovat strategie, jak udržet relevantní kontext, aniž byste překročili tento limit. Tento modul vám ukazuje, jak paměť funguje; později se naučíte, kdy shrnovat, kdy zapomenout a kdy vyhledávat. +Vícekolové konverzace fungují tak, že ke každému požadavku přikládají historii zpráv. Ale je tu limit – každý model má maximální počet tokenů. Jak konverzace roste, budete potřebovat strategie, jak udržet relevantní kontext, aniž byste ho překročili. Tento modul vám ukáže, jak paměť funguje; později se naučíte, kdy shrnovat, kdy zapomínat a kdy znovu získávat. ## Další kroky -**Další modul:** [03-rag - RAG (Generování s rozšířením o vyhledávání)](../03-rag/README.md) +**Další modul:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigace:** [← Předchozí: Modul 01 - Úvod](../01-introduction/README.md) | [Zpět na hlavní stránku](../README.md) | [Další: Modul 03 - RAG →](../03-rag/README.md) +**Navigace:** [← Předchozí: Modul 01 - Úvod](../01-introduction/README.md) | [Zpět na hlavní](../README.md) | [Další: Modul 03 - RAG →](../03-rag/README.md) --- -**Prohlášení o omezení odpovědnosti**: -Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro důležité informace se doporučuje využít profesionální lidský překlad. Nejsme odpovědní za žádná nedorozumění nebo mylné výklady vyplývající z použití tohoto překladu. +**Prohlášení o omezení odpovědnosti**: +Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu. \ No newline at end of file diff --git a/translations/cs/03-rag/README.md b/translations/cs/03-rag/README.md index 324d54598..327cd0626 100644 --- a/translations/cs/03-rag/README.md +++ b/translations/cs/03-rag/README.md @@ -1,30 +1,30 @@ -# Modul 03: RAG (Generování rozšířené vyhledáváním) +# Modul 03: RAG (Generování s využitím vyhledávání informací) ## Obsah -- [Video průvodce](../../../03-rag) -- [Co se naučíte](../../../03-rag) -- [Předpoklady](../../../03-rag) -- [Porozumění RAG](../../../03-rag) - - [Který přístup RAG tento tutoriál používá?](../../../03-rag) -- [Jak to funguje](../../../03-rag) - - [Zpracování dokumentu](../../../03-rag) - - [Vytváření embeddingů](../../../03-rag) - - [Sémantické vyhledávání](../../../03-rag) - - [Generování odpovědí](../../../03-rag) -- [Spuštění aplikace](../../../03-rag) -- [Používání aplikace](../../../03-rag) - - [Nahrání dokumentu](../../../03-rag) - - [Pokládání otázek](../../../03-rag) - - [Kontrola zdrojových odkazů](../../../03-rag) - - [Experimentování s otázkami](../../../03-rag) -- [Klíčové koncepty](../../../03-rag) - - [Strategie dělení na části](../../../03-rag) - - [Skóre podobnosti](../../../03-rag) - - [Ukládání v paměti](../../../03-rag) - - [Správa okna kontextu](../../../03-rag) -- [Kdy je RAG důležitý](../../../03-rag) -- [Další kroky](../../../03-rag) +- [Video průvodce](#video-průvodce) +- [Co se naučíte](#co-se-naučíte) +- [Požadavky](#požadavky) +- [Pochopení RAG](#pochopení-rag) + - [Který přístup RAG tento tutoriál používá?](#který-přístup-rag-tento-tutoriál-používá) +- [Jak to funguje](#jak-to-funguje) + - [Zpracování dokumentu](#zpracování-dokumentu) + - [Vytváření embeddingů](#vytváření-embeddingů) + - [Sémantické vyhledávání](#sémantické-vyhledávání) + - [Generování odpovědi](#generování-odpovědí) +- [Spuštění aplikace](#spuštění-aplikace) +- [Používání aplikace](#použití-aplikace) + - [Nahrání dokumentu](#nahrání-dokumentu) + - [Pokládání otázek](#pokládejte-otázky) + - [Kontrola zdrojových referencí](#kontrola-zdrojových-odkazů) + - [Experimentování s otázkami](#experimentujte-s-otázkami) +- [Klíčové koncepty](#klíčové-pojmy) + - [Strategie dělení na části](#strategie-rozdělení-na-části) + - [Skóre podobnosti](#skóre-podobnosti) + - [Ukládání v paměti](#paměťové-uložení) + - [Správa kontextového okna](#správa-kontextového-okna) +- [Kdy je RAG důležité](#kdy-má-rag-smysl) +- [Další kroky](#další-kroky) ## Video průvodce @@ -34,111 +34,110 @@ Sledujte tuto živou relaci, která vysvětluje, jak začít s tímto modulem: ## Co se naučíte -V předchozích modulech jste se naučili, jak vést konverzace s AI a efektivně strukturovat své dotazy. Ale existuje zásadní omezení: jazykové modely vědí pouze to, co se naučily během tréninku. Nemohou odpovídat na otázky týkající se politik vaší firmy, dokumentace vašeho projektu nebo jakýchkoli informací, na kterých nebyly trénovány. +V předchozích modulech jste se naučili, jak vést rozhovory s AI a efektivně strukturovat vaše výzvy (prompty). Existuje však základní omezení: jazykové modely znají jen to, co se naučily během tréninku. Nemohou odpovídat na otázky týkající se politiky vaší společnosti, dokumentace vašich projektů ani jakýchkoli informací, na kterých nebyly trénovány. -RAG (Generování rozšířené vyhledáváním) tento problém řeší. Místo toho, abyste se model snažili naučit vaše informace (což je nákladné a nepraktické), dáte mu možnost vyhledávat ve vašich dokumentech. Když někdo položí otázku, systém najde relevantní informace a zahrne je do dotazu. Model pak na základě tohoto kontextu odpoví. +RAG (Generování s využitím vyhledávání informací) tento problém řeší. Místo toho, aby model učil vaše informace (což je nákladné a nepraktické), dáváte mu možnost prohledávat vaše dokumenty. Když někdo položí otázku, systém najde relevantní informace a zahrne je do výzvy. Model pak odpovídá na základě tohoto získaného kontextu. Představte si RAG jako poskytnutí referenční knihovny modelu. Když položíte otázku, systém: -1. **Dotaz uživatele** – Vy položíte otázku -2. **Embedding** – Převod otázky do vektoru -3. **Vektorové vyhledávání** – Nalezení podobných částí dokumentu -4. **Sestavení kontextu** – Přidání relevantních částí do dotazu -5. **Odpověď** – LLM vygeneruje odpověď na základě kontextu +1. **Uživatelský dotaz** – Položíte otázku +2. **Embedding** – Převádí vaši otázku na vektor +3. **Vektorové hledání** – Najde podobné části dokumentů +4. **Sestavení kontextu** – Přidá relevantní části do výzvy +5. **Odpověď** – LLM generuje odpověď na základě kontextu -Tím se modelovy odpovědi opírají o vaše skutečná data namísto spolehání se na znalosti z tréninku nebo vymýšlení odpovědí. +Tímto způsobem jsou odpovědi modelu ukotvené ve vašich skutečných datech, místo aby se spoléhal pouze na znalosti ze svého tréninku nebo vymýšlel odpovědi. -## Předpoklady +## Požadavky -- Dokončený [Modul 00 - Rychlý start](../00-quick-start/README.md) (pro příklad Easy RAG zmíněný později v tomto modulu) -- Dokončený [Modul 01 - Úvod](../01-introduction/README.md) (nasazeny zdroje Azure OpenAI včetně embeddingového modelu `text-embedding-3-small`) -- `.env` soubor v kořenovém adresáři s Azure přihlašovacími údaji (vytvořený příkazem `azd up` v Modulu 01) +- Dokončený [Modul 01 - Úvod](../01-introduction/README.md) (nasazené Azure OpenAI zdroje, včetně modelu embeddingu `text-embedding-3-small`) +- `.env` soubor v kořenovém adresáři s Azure přihlašovacími údaji (vytvořený příkazem `azd up` v modulu 01) -> **Poznámka:** Pokud jste neabsolvovali Modul 01, nejdříve postupujte podle tamních instrukcí nasazení. Příkaz `azd up` nasadí jak GPT chat model, tak embedding model používaný tímto modulem. +> **Poznámka:** Pokud jste modul 01 nedokončili, nejprve postupujte podle jeho instalačních pokynů. Příkaz `azd up` nasazuje jak GPT chatovací model, tak embeddingový model, který tento modul používá. -## Porozumění RAG +## Pochopení RAG -Níže uvedený diagram ilustruje hlavní koncept: místo spoléhání se pouze na tréninková data modelu dává RAG modelu referenční knihovnu vašich dokumentů, které si může před generováním odpovědi konzultovat. +Následující diagram ilustruje základní koncept: místo spoléhání se pouze na tréninková data modelu dává RAG modelu referenční knihovnu vašich dokumentů, které konzultuje před tím, než vygeneruje každou odpověď. Co je RAG -*Tento diagram ukazuje rozdíl mezi standardním LLM (který odhaduje na základě tréninkových dat) a LLM rozšířeným o RAG (který se nejprve konzultuje s vašimi dokumenty).* +*Tento diagram ukazuje rozdíl mezi standardním LLM (který tipuje podle tréninkových dat) a RAG vylepšeným LLM (který předem konzultuje vaše dokumenty).* -Zde je zakončení celého propojení. Uživatelská otázka prochází čtyřmi fázemi — embeddingem, vektorovým vyhledáváním, sestavením kontextu a generováním odpovědi — přičemž každá staví na předchozí: +Takto jsou jednotlivé části propojeny koncový na konec. Uživatelská otázka prochází čtyřmi fázemi — embedding, vektorové hledání, sestavení kontextu a generování odpovědi — přičemž každá staví na předchozí: Architektura RAG -*Tento diagram zobrazuje end-to-end pipeline RAG — uživatelský dotaz prochází embeddingem, vektorovým vyhledáváním, sestavováním kontextu a generováním odpovědi.* +*Tento diagram ukazuje koncový RAG pipeline — uživatelský dotaz prochází embeddingem, vektorovým hledáním, sestavením kontextu a generováním odpovědi.* -Zbytek tohoto modulu detailně prochází každou fázi s kódem, který můžete spustit a upravovat. +Zbytek tohoto modulu podrobně popisuje každou fázi s kódem, který můžete spustit a upravit. ### Který přístup RAG tento tutoriál používá? -LangChain4j nabízí tři způsoby implementace RAG, každý s jinou úrovní abstrakce. Diagram níže je porovnává vedle sebe: +LangChain4j nabízí tři způsoby implementace RAG, každý s jinou úrovní abstrakce. Následující diagram je porovnává vedle sebe: Tři přístupy RAG v LangChain4j -*Tento diagram porovnává tři LangChain4j RAG přístupy — Easy, Native a Advanced — ukazující jejich klíčové komponenty a kdy který použít.* +*Tento diagram porovnává tři LangChain4j přístupy RAG — Easy, Native a Advanced — ukazující jejich klíčové komponenty a kdy který použít.* | Přístup | Co dělá | Kompromis | |---|---|---| -| **Easy RAG** | Automaticky propojí vše přes `AiServices` a `ContentRetriever`. Anotujete rozhraní, připojíte retriever a LangChain4j za scénou řeší embedding, vyhledávání a sestavování promptu. | Minimální kód, ale nevidíte co se děje v jednotlivých krocích. | -| **Native RAG** | Voláte embedding model, vyhledáváte ve skladu, sestavujete prompt a generujete odpověď sami — krok po kroku explicitně. | Více kódu, ale každá fáze je viditelná a upravitelná. | -| **Advanced RAG** | Používá framework `RetrievalAugmentor` s připojitelnými transformátory dotazů, směrovači, přeskupovači a injektory obsahu pro produkční pipeline. | Maximální flexibilita, ale výrazně větší složitost. | +| **Easy RAG** | Automaticky propojuje vše přes `AiServices` a `ContentRetriever`. Anotujete rozhraní, připojíte retriever a LangChain4j za scénou řeší embedding, hledání a sestavení výzvy. | Minimální kód, ale nevidíte, co se děje v každém kroku. | +| **Native RAG** | Zavoláte embedding model, hledáte ve skladu, sestavíte výzvu a sami vygenerujete odpověď – krok po kroku explicitně. | Více kódu, ale každá fáze je viditelná a upravitelná. | +| **Advanced RAG** | Používá framework `RetrievalAugmentor` s pluggables pro transformery dotazů, routery, přeřazovače a injektory obsahu pro produkční pipeline. | Maximální flexibilita, ale podstatně větší složitost. | -**Tento tutoriál používá Native přístup.** Každý krok pipeline RAG — embedding dotazu, vyhledávání vektorů, sestavení kontextu a generování odpovědi — je explicitně napsán v [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Toto je záměrné: jako učební materiál je důležitější, aby jste každou fázi viděli a pochopili, než aby byl kód minimalizován. Jakmile budete rozumět jak jednotlivé díly zapadají do sebe, můžete přejít na Easy RAG pro rychlé prototypy nebo Advanced RAG pro produkční systémy. +**Tento tutoriál používá Native přístup.** Každý krok RAG pipeline — embedování dotazu, vyhledávání ve vektorovém skladu, sestavení kontextu a generování odpovědi — je explicitně napsán v [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Toto je záměrné: jako výukový materiál je důležitější, abyste viděli a rozuměli každé fázi, než aby byl kód zkrácený. Jakmile pochopíte, jak jsou části propojeny, můžete přejít na Easy RAG pro rychlé prototypy nebo Advanced RAG pro produkční systémy. -> **💡 Už jste viděli Easy RAG v akci?** Modul [Rychlý start](../00-quick-start/README.md) obsahuje příklad Dokument Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), který používá Easy RAG — LangChain4j automaticky řeší embedding, vyhledávání a sestavování promptu. Tento modul jde o krok dál a rozebírá tu pipeline tak, aby jste mohli každou fázi vidět a ovládat sami. +> **💡 Zajímá vás Easy RAG?** LangChain4j také nabízí *Easy RAG* přístup, kde `AiServices` a `ContentRetriever` automaticky řeší embedding, vyhledávání a sestavení výzvy. Tento modul jde explicitnější cestou – rozbírá tu pipeline, abyste mohli vidět a řídit každou fázi. -Diagram níže ukazuje Easy RAG pipeline z tohoto příkladu Rychlého startu. Všimněte si, jak `AiServices` a `EmbeddingStoreContentRetriever` skrývají veškerou složitost — načtete dokument, připojíte retriever a získáte odpovědi. Native přístup v tomto modulu tyto skryté kroky otevírá: +Níže vidíte Easy RAG pipeline. Všimněte si, jak `AiServices` a `EmbeddingStoreContentRetriever` skrývají veškerou složitost — načtete dokument, připojíte retriever a dostanete odpovědi. Native přístup v tomto modulu rozbírá tyto skryté kroky: -Easy RAG pipeline - LangChain4j +Easy RAG Pipeline - LangChain4j -*Tento diagram ukazuje Easy RAG pipeline z `SimpleReaderDemo.java`. Porovnejte to s Native přístupem použitým v tomto modulu: Easy RAG skrývá embedding, vyhledávání a sestavování promptu za `AiServices` a `ContentRetriever` — načtete dokument, připojíte retriever a dostanete odpovědi. Native přístup v tomto modulu tu pipeline otevírá, takže si sami voláte každou fázi (embed, search, assemble context, generate) a máte plnou kontrolu.* +*Tento diagram ukazuje Easy RAG pipeline. Porovnejte s Native přístupem v tomto modulu: Easy RAG skrývá embedding, vyhledávání a sestavení výzvy za `AiServices` a `ContentRetriever` — načtete dokument, připojíte retriever a získáte odpovědi. Native přístup tento pipeline rozbírá, takže vy voláte každý krok (embed, hledání, sestavení kontextu, generování) sami, což vám dává plnou viditelnost a kontrolu.* ## Jak to funguje -Pipeline RAG v tomto modulu se dělí na čtyři fáze, které běží v pořadí při každé uživatelově otázce. Nejprve je nahraný dokument **parsován a rozdělen na kousky** vhodné velikosti. Tyto kousky jsou pak převedeny na **vektorové embeddingy** a uloženy tak, aby je bylo možné matematicky porovnávat. Když přijde dotaz, systém provede **sémantické vyhledávání**, aby našel nejrelevantnější kousky, a nakonec je použije jako kontext pro LLM při **generování odpovědi**. Níže jsou jednotlivé fáze podrobně popsány s kódem a diagramy. Začneme prvním krokem. +RAG pipeline v tomto modulu se skládá ze čtyř fází, které běží v pořadí pokaždé, když uživatel položí otázku. Nejprve je nahraný dokument **parsován a rozdělen na části** o rozumné velikosti. Tyto části se pak převedou na **vektorové embeddingy** a uloží tak, aby je bylo možné matematicky porovnávat. Když přijde dotaz, systém provede **sémantické vyhledávání** nejrelevantnějších částí a nakonec je předá jako kontext LLM pro **generování odpovědi**. Níže uvedené sekce popisují každou fázi s konkrétním kódem a diagramy. Pojďme se podívat na první krok. ### Zpracování dokumentu [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Když nahrajete dokument, systém ho parsuje (PDF nebo prostý text), připojí metadata jako název souboru a pak ho rozlomí na kousky — menší části, které pohodlně pasují do kontextového okna modelu. Tyto kousky se mírně překrývají, aby nedošlo ke ztrátě kontextu na hranicích. +Když nahrajete dokument, systém jej parsuje (PDF nebo prostý text), přidá metadata jako název souboru a pak jej rozbije na části — menší segmenty, které pohodlně pasují do kontextového okna modelu. Tyto části se mírně překrývají, aby se neztratil kontext na hranicích. ```java // Analyzujte nahraný soubor a zabalte jej do dokumentu LangChain4j Document document = Document.from(content, metadata); -// Rozdělte na úseky o 300 tokenech s překrytím 30 tokenů +// Rozdělte na části po 300 tokenech s přesahem 30 tokenů DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Níže uvedený diagram ukazuje, jak to vizuálně funguje. Všimněte si, že každý kousek sdílí několik tokenů se sousedy — překrytí 30 tokenů zajišťuje, že žádný důležitý kontext nepropadne mezi díly: +Níže uvedený diagram ukazuje, jak to vizuálně funguje. Každá část sdílí některé tokeny se sousedy — překrytí 30 tokeny zajišťuje, že žádný důležitý kontext nezmizí mezi částmi: Dělení dokumentu na části -*Tento diagram ukazuje dokument rozdělený na 300-tokenové části s 30-tokenovým překrytím, zachovávající kontext na hranicích částí.* +*Tento diagram ukazuje dokument rozdělený na části o 300 tokenech s překrytím 30 tokenů, čímž se uchovává kontext na hranicích částí.* -> **🤖 Zkuste s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) a zeptejte se: -> - "Jak LangChain4j dělí dokumenty do částí a proč je překrytí důležité?" +> **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) a zeptejte se: +> - "Jak LangChain4j dělí dokumenty na části a proč je překrývání důležité?" > - "Jaká je optimální velikost části pro různé typy dokumentů a proč?" -> - "Jak řešit dokumenty ve vícejazyčných verzích nebo se speciálním formátováním?" +> - "Jak zacházet s dokumenty v několika jazycích nebo se speciálním formátováním?" ### Vytváření embeddingů [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Každý kousek se převede na číselnou reprezentaci zvanou embedding — v podstatě převod významu na čísla. Embeddingový model není „inteligentní“ jako chat model; nemůže následovat instrukce, uvažovat ani odpovídat na otázky. Co ale dělá, je namapovat text do matematického prostoru, kde podobné významy jsou blízko sebe — „auto“ poblíž „automobil“, „politika vrácení peněz“ poblíž „vrátit peníze“. Představte si chat model jako člověka, se kterým můžete mluvit; embedding model je ultra dobrý souborový systém. +Každá část se převede na číselnou reprezentaci nazývanou embedding — v podstatě převod významu na čísla. Embeddingový model není „inteligentní“ jako chatovací model; nedokáže plnit instrukce, uvažovat ani odpovídat na otázky. Co umí, je namapovat text do matematického prostoru, kde podobné významy leží blízko sebe — „auto“ blízko „automobil“, „vrácení peněz“ blízko „návrat mého dluhu“. Můžeme tedy chatovací model přirovnat k člověku, se kterým mluvíte, zatímco embeddingový model je velmi dobrý třídicí systém. -Diagram níže vizualizuje tento koncept — text jde dovnitř, číselné vektory vycházejí ven a podobné významy produkují blízké vektory: +Následující diagram vizualizuje tento koncept — text vstupuje, vycházejí číselné vektory, a podobné významy vedou k sousedním vektorům: Koncept embeddingového modelu -*Tento diagram ukazuje, jak embeddingový model převádí text na číselné vektory, přičemž podobné významy — jako „auto“ a „automobil“ — jsou blízko sebe ve vektorovém prostoru.* +*Tento diagram ukazuje, jak embeddingový model převádí text na číselné vektory, umisťující podobné významy — jako „auto“ a „automobil“ — blízko sebe ve vektorovém prostoru.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Třídní diagram níže ukazuje dva samostatné toky pipeline RAG a třídy LangChain4j, které je implementují. **Ingestion tok** (běží jednou při nahrání) rozděluje dokument, embeduje kousky a ukládá je přes `.addAll()`. **Query tok** (běží při každé otázce) embeduje otázku, vyhledává ve skladu přes `.search()` a předává odpovídající kontext chat modelu. Oba toky se spojují přes sdílené rozhraní `EmbeddingStore`: +Níže uvedený diagram tříd ukazuje dva samostatné toky v RAG pipeline a třídy LangChain4j, které je implementují. **Tok importu** (běží jednou při nahrání) rozděluje dokument, embeduje části a ukládá je pomocí `.addAll()`. **Tok dotazu** (běží při každé otázce uživatele) embeduje otázku, hledá ve skladu přes `.search()` a předává odpovídající kontext chatovacímu modelu. Oba toky se setkávají na sdíleném rozhraní `EmbeddingStore`: -Třídy RAG LangChain4j +RAG třídy LangChain4j -*Tento diagram ukazuje dva toky v pipeline RAG — ingestion a query — a jak se propojují přes sdílený EmbeddingStore.* +*Tento diagram ukazuje dva toky v RAG pipeline — import a dotaz — a jak se propojují přes sdílený EmbeddingStore.* -Jakmile jsou embeddingy uloženy, podobný obsah se přirozeně sdružuje ve vektorovém prostoru. Vizualizace níže ukazuje, jak dokumenty o příbuzných tématech skončí jako sousední body, což umožňuje sémantické vyhledávání: +Jakmile jsou embeddingy uloženy, podobný obsah se přirozeně shlukuje ve vektorovém prostoru. Vizualizace níže ukazuje, jak související dokumenty končí jako blízké body, což umožňuje sémantické vyhledávání: -Vektorový prostor embeddingů +Prostor vektorových embeddingů -*Vizualizace ukazuje, jak se příbuzné dokumenty sdružují v 3D vektorovém prostoru, s tématy jako Technická dokumentace, Obchodní pravidla a FAQ tvořící oddělené skupiny.* +*Tato vizualizace ukazuje, jak se související dokumenty shlukují ve 3D vektorovém prostoru, přičemž témata jako technická dokumentace, obchodní pravidla a FAQ tvoří samostatné skupiny.* -Když uživatel vyhledává, systém následuje čtyři kroky: jednou embeduje dokumenty, při každém vyhledávání embeduje dotaz, porovnává vektor dotazu se všemi uloženými vektory pomocí kosinové podobnosti a vrací top-K nejlépe hodnocených částí. Diagram níže ukazuje každý krok a třídy LangChain4j zapojené do procesu: +Při vyhledávání systém následuje čtyři kroky: embeduje dokumenty jednou, embeduje dotaz při každém hledání, porovnává vektor dotazu se všemi uloženými vektory pomocí kosinové podobnosti a vrací top-K nejvýše hodnocené části. Níže uvedený diagram prochází každý krok a příslušné třídy LangChain4j: -Kroky vyhledávání embeddingů +Kroky vyhledávání pomocí embeddingu -*Tento diagram ukazuje čtyřkrokový proces vyhledávání embeddingů: embedování dokumentů, embedování dotazu, porovnávání vektorů pomocí kosinové podobnosti a vracení top-K výsledků.* +*Tento diagram ukazuje čtyřkrokový proces vyhledávání embeddingu: embedování dokumentů, embedování dotazu, porovnávání vektorů kosinovou podobností a vrácení top-K výsledků.* ### Sémantické vyhledávání [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Když položíte otázku, vaše otázka se také převede do embeddingu. Systém porovná embedding vaší otázky se všemi embeddingy částí dokumentu. Najde části s nejpodobnějšími významy — nejen shoda klíčových slov, ale skutečná sémantická podobnost. +Když položíte otázku, také se z ní vytvoří embedding. Systém pak porovná embedding vaší otázky se všemi embeddingy částí dokumentů. Najde části s nejpodobnějším významem - nejen s odpovídajícími klíčovými slovy, ale skutečnou sémantickou podobností. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Diagram níže porovnává sémantické vyhledávání s tradičním vyhledáváním podle klíčových slov. Vyhledávání podle klíčového slova „vehicle“ minulo část „cars and trucks“, ale sémantické vyhledávání chápe, že to znamená totéž, a vrátí ji jako vysoce hodnocenou shodu: +Níže uvedený diagram porovnává sémantické vyhledávání s tradičním hledáním podle klíčových slov. Hledání podle klíčového slova „vozidlo“ může přeskočit část o „auty a náklaďáky“, ale sémantické vyhledávání chápe, že to znamená to samé, a vrátí ji jako vysoké skórující shodu: Sémantické vyhledávání -*Tento diagram porovnává vyhledávání založené na klíčových slovech se sémantickým vyhledáváním, ukazující, jak sémantické vyhledávání získává konceptuálně související obsah i když se přesná klíčová slova liší.* -Pod kapotou je podobnost měřena pomocí kosinové podobnosti — v podstatě se ptáme „ukazují tyto dvě šipky stejným směrem?“ Dva textové úseky mohou používat zcela odlišná slova, ale pokud znamenají totéž, jejich vektory ukazují stejným směrem a skórují blízko 1.0: +*Tento diagram porovnává vyhledávání na základě klíčových slov a sémantické vyhledávání, ukazující, jak sémantické vyhledávání vrací konceptuálně související obsah i tehdy, když se přesná klíčová slova liší.* -Cosine Similarity +Pod kapotou se podobnost měří pomocí kosinové podobnosti — v podstatě se ptáme „ukazují tyto dva šipky stejným směrem?“ Dvě části mohou mít zcela odlišná slova, ale pokud významově souhlasí, jejich vektory ukazují stejným směrem a skórují blízko 1,0: -*Tento diagram ilustruje kosinovou podobnost jako úhel mezi embeddingovými vektory — více zarovnané vektory dosahují skóre blížícího se 1.0, což znamená vyšší sémantickou podobnost.* +Kosinová podobnost +*Tento diagram ilustruje kosinovou podobnost jako úhel mezi vektorovými vloženími — více zarovnané vektory dosahují skóre blíže k 1,0, což značí vyšší sémantickou podobnost.* > **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) a zeptejte se: -> - „Jak funguje vyhledávání podobnosti s embeddingy a co určuje skóre?“ -> - „Jaký práh podobnosti bych měl použít a jak to ovlivňuje výsledky?“ -> - „Jak řešit situace, kdy nejsou nalezeny žádné relevantní dokumenty?“ +> - "Jak funguje vyhledávání podobnosti s vloženími a co určuje skóre?" +> - "Jaký práh podobnosti bych měl použít a jak ovlivňuje výsledky?" +> - "Jak zacházet s případy, kdy nejsou nalezeny žádné relevantní dokumenty?" ### Generování odpovědí [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Nejrelevantnější úseky jsou sestaveny do strukturovaného promptu, který obsahuje explicitní instrukce, získaný kontext a otázku uživatele. Model čte tyto konkrétní úseky a odpovídá na základě těchto informací — může použít pouze to, co má před sebou, což zabraňuje halucinacím. +Nejrelevantnější části jsou sestaveny do strukturované výzvy, která obsahuje explicitní instrukce, získaný kontext a uživatelovu otázku. Model čte právě tyto konkrétní části a odpovídá na základě těchto informací — může použít pouze to, co má před sebou, což zabraňuje halucinacím. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Následující diagram ukazuje tuto sestavu v akci — nejlépe hodnocené úseky z vyhledávací fáze jsou vloženy do šablony promptu a `OpenAiOfficialChatModel` generuje podloženou odpověď: +Níže uvedený diagram ukazuje tento proces sestavení — části s nejvyšším skóre z kroku vyhledávání jsou vloženy do šablony výzvy a `OpenAiOfficialChatModel` generuje podloženou odpověď: -Context Assembly +Sestavení kontextu -*Tento diagram ukazuje, jak jsou nejlépe hodnocené úseky sestaveny do strukturovaného promptu, což umožňuje modelu generovat podloženou odpověď z vašich dat.* +*Tento diagram ukazuje, jak jsou části s nejvyšším skóre sestaveny do strukturované výzvy, což umožňuje modelu generovat podloženou odpověď z vašich dat.* ## Spuštění aplikace **Ověření nasazení:** -Ujistěte se, že v kořenovém adresáři existuje soubor `.env` s přihlašovacími údaji Azure (vytvořeno během Modulu 01). Spusťte tento příkaz z adresáře modulu (`03-rag/`): +Ujistěte se, že soubor `.env` existuje v kořenovém adresáři s přihlašovacími údaji Azure (vytvořeno během modulu 01). Spusťte to z adresáře modulu (`03-rag/`): **Bash:** ```bash @@ -259,25 +258,25 @@ cat ../.env # Mělo by zobrazit AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Mělo by zobrazit AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Spuštění aplikace:** +**Spusťte aplikaci:** -> **Poznámka:** Pokud jste již spustili všechny aplikace pomocí `./start-all.sh` z kořenového adresáře (jak je popsáno v Modulu 01), tento modul už běží na portu 8081. Můžete přeskočit níže uvedené příkazy a rovnou přejít na http://localhost:8081. +> **Poznámka:** Pokud jste již spustili všechny aplikace pomocí `./start-all.sh` z kořenového adresáře (jak je popsáno v modulu 01), tento modul už běží na portu 8081. Můžete přeskočit níže uvedené příkazy pro spuštění a jít přímo na http://localhost:8081. **Možnost 1: Použití Spring Boot Dashboard (doporučeno pro uživatele VS Code)** -Vývojové prostředí obsahuje rozšíření Spring Boot Dashboard, které poskytuje vizuální rozhraní pro správu všech Spring Boot aplikací. Najdete ho na panelu aktivit vlevo ve VS Code (vyhledejte ikonu Spring Boot). +Vývojářský kontejner obsahuje rozšíření Spring Boot Dashboard, které poskytuje vizuální rozhraní pro správu všech aplikací Spring Boot. Najdete jej v postranním panelu vlevo ve VS Code (hledejte ikonu Spring Boot). Ze Spring Boot Dashboard můžete: -- Vidět všechny dostupné Spring Boot aplikace v pracovním prostoru -- Spouštět/zastavovat aplikace jedním kliknutím -- Zobrazovat protokoly aplikace v reálném čase -- Monitorovat stav aplikace +- Vidět všechny dostupné aplikace Spring Boot v pracovním prostoru +- Spouštět/ukončovat aplikace jedním kliknutím +- Zobrazovat logy aplikací v reálném čase +- Monitorovat stav aplikací -Stačí kliknout na tlačítko play vedle „rag“ pro spuštění tohoto modulu, nebo spustit všechny moduly najednou. +Jednoduše klikněte na tlačítko spuštění vedle "rag" pro spuštění tohoto modulu, nebo spusťte všechny moduly najednou. Spring Boot Dashboard -*Tento screenshot zobrazuje Spring Boot Dashboard ve VS Code, kde můžete vizuálně spouštět, zastavovat a sledovat aplikace.* +*Tento snímek obrazovky ukazuje Spring Boot Dashboard ve VS Code, kde můžete vizuálně spouštět, zastavovat a sledovat aplikace.* **Možnost 2: Použití shell skriptů** @@ -291,11 +290,11 @@ cd .. # Z kořenového adresáře **PowerShell:** ```powershell -cd .. # Ze základního adresáře +cd .. # Z kořenového adresáře .\start-all.ps1 ``` -Nebo spusťte pouze tento modul: +Nebo spusťte jen tento modul: **Bash:** ```bash @@ -309,16 +308,16 @@ cd 03-rag .\start.ps1 ``` -Oba skripty automaticky načtou proměnné prostředí ze souboru `.env` v kořenovém adresáři a postaví JAR soubory, pokud neexistují. +Oba skripty automaticky načítají proměnné prostředí z kořenového souboru `.env` a sestaví JARy, pokud ještě neexistují. -> **Poznámka:** Pokud chcete před spuštěním stavět všechny moduly ručně: +> **Poznámka:** Pokud preferujete sestavení všech modulů ručně před spuštěním: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -331,7 +330,7 @@ Otevřete v prohlížeči http://localhost:8081. **Bash:** ```bash -./stop.sh # Pouze tento modul +./stop.sh # Tento modul pouze # Nebo cd .. && ./stop-all.sh # Všechny moduly ``` @@ -345,81 +344,81 @@ cd ..; .\stop-all.ps1 # Všechny moduly ## Použití aplikace -Aplikace nabízí webové rozhraní pro nahrávání dokumentů a kladení otázek. +Aplikace poskytuje webové rozhraní pro nahrávání dokumentů a kladení otázek. -RAG Application Interface +Rozhraní aplikace RAG -*Tento screenshot ukazuje rozhraní RAG aplikace, kde můžete nahrávat dokumenty a klást otázky.* +*Tento snímek obrazovky ukazuje rozhraní aplikace RAG, kde nahráváte dokumenty a kladete otázky.* ### Nahrání dokumentu -Začněte nahráním dokumentu — nejlépe fungují TXT soubory pro testování. V tomto adresáři je k dispozici `sample-document.txt`, který obsahuje informace o funkcích LangChain4j, implementaci RAG a osvědčených postupech — ideální pro testování systému. +Začněte nahráním dokumentu - pro testování nejlépe fungují soubory TXT. V tomto adresáři je k dispozici `sample-document.txt`, který obsahuje informace o funkcích LangChain4j, implementaci RAG a osvědčené postupy — ideální pro testování systému. -Systém váš dokument zpracuje, rozdělí na úseky a pro každý úsek vytvoří embeddingy. To probíhá automaticky při nahrání. +Systém váš dokument zpracuje, rozlomí na části a vytvoří vložení pro každou část. To se děje automaticky při nahrání. ### Pokládejte otázky -Teď se můžete zeptat na konkrétní otázky týkající se obsahu dokumentu. Zkuste něco faktického, co je jasně uvedeno v dokumentu. Systém vyhledá relevantní úseky, zahrne je do promptu a vygeneruje odpověď. +Nyní položte konkrétní otázky týkající se obsahu dokumentu. Zkuste něco faktického, co je v dokumentu jasně uvedeno. Systém vyhledá relevantní části, zahrne je do výzvy a vygeneruje odpověď. ### Kontrola zdrojových odkazů -Všimněte si, že každá odpověď obsahuje odkazy na zdroje spolu s hodnotami podobnosti. Tyto skóre (od 0 do 1) ukazují, jak relevantní každý úsek byl pro vaši otázku. Vyšší skóre znamená lepší shodu. To vám umožňuje ověřit odpověď oproti zdrojovému materiálu. +Všimněte si, že každá odpověď obsahuje odkazy na zdroje s hodnotami podobnosti. Tyto hodnoty (0 až 1) ukazují, jak relevantní byla každá část vůči vaší otázce. Vyšší skóre znamená lepší shodu. To vám umožní ověřit odpověď vůči zdrojovému materiálu. -RAG Query Results +Výsledky dotazů RAG -*Tento screenshot ukazuje výsledky dotazu s vygenerovanou odpovědí, odkazy na zdroje a skóre relevance každého nalezeného úseku.* +*Tento snímek obrazovky ukazuje výsledky dotazu s vygenerovanou odpovědí, zdrojovými odkazy a skóre relevance pro každou získanou část.* ### Experimentujte s otázkami -Vyzkoušejte různé druhy otázek: -- Konkrétní fakta: „Jaké je hlavní téma?“ -- Porovnání: „Jaký je rozdíl mezi X a Y?“ -- Shrnutí: „Shrňte klíčové body o Z“ +Vyzkoušejte různé typy otázek: +- Konkrétní fakta: "Jaké je hlavní téma?" +- Porovnání: "Jaký je rozdíl mezi X a Y?" +- Shrnutí: "Shrňte klíčové body o Z" Sledujte, jak se skóre relevance mění podle toho, jak dobře vaše otázka odpovídá obsahu dokumentu. -## Klíčové koncepty +## Klíčové pojmy -### Strategie rozdělení do úseků +### Strategie rozdělení na části -Dokumenty jsou rozděleny na úseky o 300 tokenech s překrytím 30 tokenů. Tento kompromis zajišťuje, že každý úsek má dostatek kontextu, aby byl smysluplný, ale zároveň jsou úseky dostatečně malé, aby jich bylo možné do promptu vložit více. +Dokumenty se rozdělují na části o 300 znacích s překryvem 30 znaků. Tento kompromis zajišťuje, že každá část má dostatek kontextu, aby byla smysluplná, ale zároveň je dostatečně malá, aby se do výzvy vešlo více částí. ### Skóre podobnosti -Každý nalezený úsek má skóre podobnosti mezi 0 a 1, které ukazuje, jak úzce odpovídá uživatelově otázce. Níže uvedený diagram vizualizuje rozsahy skóre a jak systém tyto hodnoty využívá k filtrování výsledků: +Každá získaná část má skóre podobnosti mezi 0 a 1, které ukazuje, jak přesně odpovídá uživatelově otázce. Níže uvedený diagram vizualizuje rozsahy skóre a jak systém používá tato skóre k filtrování výsledků: -Similarity Scores +Skóre podobnosti -*Tento diagram ukazuje rozsahy skóre od 0 do 1, s minimálním prahem 0,5, který filtruje irelevantní úseky.* +*Tento diagram ukazuje rozsahy skóre od 0 do 1 s minimálním prahem 0,5, který filtruje nerelevantní části.* Skóre se pohybují od 0 do 1: -- 0,7–1,0: Vysoce relevantní, přesná shoda -- 0,5–0,7: Relevantní, dobrý kontext -- Pod 0,5: Odfiltrováno, příliš odlišné +- 0,7-1,0: Vysoce relevantní, přesná shoda +- 0,5-0,7: Relevantní, dobrý kontext +- Pod 0,5: Odfiltrováno, příliš rozdílné -Systém získává pouze úseky nad minimálním prahem, aby zajistil kvalitu. +Systém získává pouze části nad minimálním prahem, aby zajistil kvalitu. -Embeddingy fungují dobře, když se význam jasno shlukuje, ale mají své slabiny. Níže uvedený diagram ukazuje běžné způsoby selhání — příliš velké úseky vytvářejí rozmazané vektory, příliš malé úseky postrádají kontext, nejednoznačné termíny směřují do více shluků a přesné vyhledávání (ID, výrobní čísla) s embeddingy vůbec nefunguje: +Vložení fungují dobře, když se významové shluky vyčistí, ale mají slepá místa. Níže uvedený diagram ukazuje běžné režimy selhání — části, které jsou příliš velké, produkují nejasné vektory, části, které jsou příliš malé, postrádají kontext, nejednoznačné termíny směřují k více shlukům a přesné vyhledávání (ID, čísla dílů) ve vkládáních vůbec nefunguje: -Embedding Failure Modes +Režimy selhání vložení -*Tento diagram ukazuje běžné způsoby selhání embeddingů: úseky příliš velké, úseky příliš malé, nejednoznačné termíny směřující do více shluků a přesné vyhledávání jako ID.* +*Tento diagram ukazuje běžné režimy selhání vložení: části příliš velké, části příliš malé, nejednoznačné termíny vedoucí k více shlukům a přesné vyhledávání jako ID.* -### Uchovávání v paměti +### Paměťové uložení -Tento modul používá jednoduché uchovávání v paměti. Po restartu aplikace jsou nahrané dokumenty ztraceny. Produkční systémy používají perzistentní vektorové databáze jako Qdrant nebo Azure AI Search. +Tento modul používá pro jednoduchost paměťové uložení. Po restartu aplikace se nahrané dokumenty ztratí. Produkční systémy používají perzistentní vektorové databáze jako Qdrant nebo Azure AI Search. -### Řízení kontextového okna +### Správa kontextového okna -Každý model má maximální kontextové okno. Nemůžete zahrnout všechny úseky z velkého dokumentu. Systém získává top N nejrelevantnějších úseků (výchozí hodnota 5), aby se vešel do limitů a zároveň poskytl dostatek kontextu pro přesné odpovědi. +Každý model má maximální velikost kontextového okna. Nemůžete zahrnout všechny části z velkého dokumentu. Systém získává prvních N nejrelevantnějších částí (ve výchozím nastavení 5), aby zůstal v limitech a zároveň poskytl dostatek kontextu pro přesné odpovědi. -## Kdy je RAG důležitý +## Kdy má RAG smysl -RAG není vždy správný přístup. Následující průvodce rozhodnutím vám pomůže určit, kdy RAG přináší hodnotu a kdy jsou vhodnější jednodušší přístupy — jako je zahrnutí obsahu přímo do promptu nebo spoléhání na vestavěné znalosti modelu: +RAG není vždy správný přístup. Níže uvedený průvodce rozhodnutím vám pomůže určit, kdy RAG přidává hodnotu a kdy stačí jednodušší přístupy — jako přímé zahrnutí obsahu do výzvy nebo spoléhání na vestavěné znalosti modelu: -When to Use RAG +Kdy použít RAG -*Tento diagram ukazuje rozhodovací průvodce, kdy RAG přidává hodnotu a kdy stačí jednodušší přístupy.* +*Tento diagram ukazuje průvodce rozhodnutím, kdy RAG přidává hodnotu versus kdy postačí jednodušší přístupy.* ## Další kroky @@ -427,11 +426,11 @@ RAG není vždy správný přístup. Následující průvodce rozhodnutím vám --- -**Navigace:** [← Předchozí: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Zpět na hlavní stránku](../README.md) | [Další: Modul 04 - Nástroje →](../04-tools/README.md) +**Navigace:** [← Předchozí: Modul 02 - Tvorba výzev](../02-prompt-engineering/README.md) | [Zpět na hlavní stránku](../README.md) | [Další: Modul 04 - Nástroje →](../04-tools/README.md) --- -**Prohlášení o vyloučení odpovědnosti**: -Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o přesnost, mějte prosím na paměti, že automatické překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho mateřském jazyce by měl být považován za závazný zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědni za žádné nedorozumění nebo chybné výklady vzniklé použitím tohoto překladu. +**Prohlášení o omezení odpovědnosti**: +Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu. \ No newline at end of file diff --git a/translations/cs/04-tools/README.md b/translations/cs/04-tools/README.md index 98511cf90..0278c1001 100644 --- a/translations/cs/04-tools/README.md +++ b/translations/cs/04-tools/README.md @@ -2,75 +2,75 @@ ## Obsah -- [Video průvodce](../../../04-tools) -- [Co se naučíte](../../../04-tools) -- [Předpoklady](../../../04-tools) -- [Porozumění AI agentům s nástroji](../../../04-tools) -- [Jak funguje volání nástrojů](../../../04-tools) - - [Definice nástrojů](../../../04-tools) - - [Rozhodování](../../../04-tools) - - [Vykonání](../../../04-tools) - - [Generování odpovědi](../../../04-tools) - - [Architektura: Spring Boot automatické propojení](../../../04-tools) -- [Řetězení nástrojů](../../../04-tools) -- [Spuštění aplikace](../../../04-tools) -- [Používání aplikace](../../../04-tools) - - [Vyzkoušejte jednoduché použití nástroje](../../../04-tools) - - [Testování řetězení nástrojů](../../../04-tools) - - [Zobrazení průběhu konverzace](../../../04-tools) - - [Experimentování s různými požadavky](../../../04-tools) -- [Klíčové koncepty](../../../04-tools) - - [Vzor ReAct (Reasoning and Acting)](../../../04-tools) - - [Popisy nástrojů mají význam](../../../04-tools) - - [Správa relace](../../../04-tools) - - [Zpracování chyb](../../../04-tools) -- [Dostupné nástroje](../../../04-tools) -- [Kdy používat agenty založené na nástrojích](../../../04-tools) -- [Nástroje vs RAG](../../../04-tools) -- [Další kroky](../../../04-tools) +- [Video průvodce](#video-průvodce) +- [Co se naučíte](#co-se-naučíte) +- [Předpoklady](#předpoklady) +- [Pochopení AI agentů s nástroji](#pochopení-ai-agentů-s-nástroji) +- [Jak funguje volání nástrojů](#jak-funguje-volání-nástrojů) + - [Definice nástrojů](#definice-nástrojů) + - [Rozhodování](#rozhodování) + - [Provedení](#provedení) + - [Generování odpovědi](#generování-odpovědi) + - [Architektura: Spring Boot Auto-Wiring](#architektura-spring-boot-auto-wiring) +- [Řetězení nástrojů](#řetězení-nástrojů) +- [Spuštění aplikace](#spuštění-aplikace) +- [Používání aplikace](#použití-aplikace) + - [Vyzkoušejte jednoduché použití nástroje](#vyzkoušejte-jednoduché-použití-nástroje) + - [Testujte řetězení nástrojů](#otestujte-řetězení-nástrojů) + - [Sledujte průběh konverzace](#sledujte-tok-konverzace) + - [Experimentujte s různými požadavky](#experimentujte-s-různými-požadavky) +- [Klíčové koncepty](#klíčové-koncepty) + - [Vzor ReAct (Reasoning and Acting)](#vzor-react-rozumování-a-jednání) + - [Popisy nástrojů jsou důležité](#popisy-nástrojů-jsou-důležité) + - [Správa relace](#správa-relací) + - [Zpracování chyb](#zpracování-chyb) +- [Dostupné nástroje](#dostupné-nástroje) +- [Kdy používat agenty založené na nástrojích](#kdy-používat-agenty-založené-na-nástrojích) +- [Nástroje vs RAG](#nástroje-vs-rag) +- [Další kroky](#další-kroky) ## Video průvodce -Podívejte se na živou relaci, která vysvětluje, jak začít s tímto modulem: +Sledujte tuto živou relaci, která vysvětluje, jak začít s tímto modulem: AI Agents with Tools and MCP - Live Session ## Co se naučíte -Dosud jste se naučili, jak vést rozhovory s AI, efektivně strukturovat výzvy a zakládat odpovědi na vašich dokumentech. Přesto existuje základní omezení: jazykové modely umí pouze generovat text. Nemohou zkontrolovat počasí, provádět výpočty, dotazovat se do databází nebo komunikovat s externími systémy. +Doposud jste se naučili vést konverzace s AI, efektivně strukturovat výzvy a zakládat odpovědi na vašich dokumentech. Přesto existuje základní omezení: jazykové modely mohou generovat pouze text. Nemohou kontrolovat počasí, počítat, dotazovat se do databází ani komunikovat s externími systémy. -Nástroje to mění. Poskytnutím modelu přístupu k funkcím, které může volat, ho proměníte z generátoru textu na agenta, který může podnikat akce. Model rozhoduje, kdy potřebuje nástroj, který nástroj použít a jaké parametry předat. Váš kód vykoná funkci a vrátí výsledek. Model tento výsledek zakomponuje do své odpovědi. +Nástroje to mění. Tím, že modelu dáte přístup k funkcím, které může volat, transformujete ho z generátoru textu na agenta, který může konat. Model rozhoduje, kdy potřebuje nástroj, který nástroj použít a jaké parametry předat. Vaše kód provede funkci a vrátí výsledek. Model pak výsledek začlení do své odpovědi. ## Předpoklady -- Dokončen [Modul 01 - Úvod](../01-introduction/README.md) (nasazené Azure OpenAI zdroje) -- Doporučeno dokončit předchozí moduly (tento modul odkazuje na [RAG koncepty z Modulu 03](../03-rag/README.md) v porovnání Nástroje vs RAG) -- `.env` soubor v kořenovém adresáři s Azure přihlašovacími údaji (vytvořeno pomocí `azd up` v Modulu 01) +- Dokončen [Modul 01 - Úvod](../01-introduction/README.md) (nasazené zdroje Azure OpenAI) +- Doporučeno dokončit předchozí moduly (tento modul odkazuje na [koncepty RAG z Modulu 03](../03-rag/README.md) v porovnání Nástroje vs RAG) +- Soubor `.env` v kořenovém adresáři s přihlašovacími údaji Azure (vytvořený pomocí `azd up` v Modulu 01) -> **Poznámka:** Pokud jste ještě nedokončili Modul 01, nejdříve postupujte podle jeho nasazovacích pokynů. +> **Poznámka:** Pokud jste nedokončili Modul 01, nejprve postupujte podle instalačních pokynů tam. -## Porozumění AI agentům s nástroji +## Pochopení AI agentů s nástroji -> **📝 Poznámka:** Termín „agenti“ v tomto modulu označuje AI asistenty rozšířené o schopnost volání nástrojů. To se liší od vzorů **Agentic AI** (autonomní agenti s plánováním, pamětí a vícekrokovým uvažováním), které budeme probírat v [Modulu 05: MCP](../05-mcp/README.md). +> **📝 Poznámka:** Termín „agenti“ v tomto modulu označuje AI asistenty vylepšené schopností volání nástrojů. To se liší od **Agentic AI** vzorů (autonomní agenti s plánováním, pamětí a vícekrokovým odvozováním), které probereme v [Modulu 05: MCP](../05-mcp/README.md). -Bez nástrojů může jazykový model generovat pouze text založený na svých tréninkových datech. Zeptejte se ho na aktuální počasí a musí odhadovat. Dejte mu nástroje a může zavolat API počasí, provést výpočty nebo dotazovat databázi — a pak tyto skutečné výsledky zapracovat do své odpovědi. +Bez nástrojů může jazykový model generovat pouze text ze svých tréninkových dat. Zeptáte-li se na aktuální počasí, musí hádat. Když mu dáte nástroje, může volat API počasí, provádět výpočty nebo dotazovat databázi — a tyto skutečné výsledky začlenit do odpovědi. -Without Tools vs With Tools +Bez nástrojů vs s nástroji -*Bez nástrojů model jen hádá — s nástroji může volat API, provádět výpočty a vracet aktuální data.* +*Bez nástrojů model jen hádá – s nástroji může volat API, provádět výpočty a vracet aktuální data.* -AI agent s nástroji používá vzor **Reasoning and Acting (ReAct)**. Model nejen odpovídá — přemýšlí o tom, co potřebuje, jedná voláním nástroje, pozoruje výsledek a pak rozhodne, zda znovu jednat nebo podat konečnou odpověď: +AI agent s nástroji následuje vzor **Reasoning and Acting (ReAct)**. Model nejen odpovídá — přemýšlí o tom, co potřebuje, jedná voláním nástroje, sleduje výsledek a rozhoduje, zda jednat znovu nebo poskytnout finální odpověď: -1. **Reason (Přemýšlí)** — Agent analyzuje uživatelskou otázku a určí, jaké informace potřebuje -2. **Act (Jde k činu)** — Agent vybere správný nástroj, vytvoří správné parametry a zavolá ho -3. **Observe (Sleduje)** — Agent přijme výstup nástroje a vyhodnotí ho -4. **Repeat or Respond (Opakuje nebo odpovídá)** — Pokud je potřeba více dat, agent se vrací zpět; jinak vytváří odpověď v přirozeném jazyce +1. **Rozumí** — agent analyzuje otázku uživatele a určuje, jaké informace potřebuje +2. **Jedná** — agent vybere správný nástroj, vytvoří správné parametry a zavolá ho +3. **Sleduje** — agent přijme výstup nástroje a vyhodnotí výsledek +4. **Opakuje nebo odpoví** — pokud je potřeba více dat, agent se vrátí k prvnímu kroku; jinak sestaví odpověď v přirozeném jazyce -ReAct Pattern +ReAct Vzor -*Cyklický ReAct vzor — agent uvažuje, co dělat, jedná voláním nástroje, sleduje výsledek a pokračuje, dokud nemůže podat konečnou odpověď.* +*Cyklus ReAct — agent přemýšlí, jak jednat, provádí volání nástroje, sleduje výsledek a opakuje, dokud nemůže poskytnout finální odpověď.* -To se děje automaticky. Definujete nástroje a jejich popisy. Model rozhoduje, kdy a jak je používat. +Tento proces probíhá automaticky. Definujete nástroje a jejich popisy. Model se postará o rozhodování, kdy a jak je použít. ## Jak funguje volání nástrojů @@ -78,7 +78,7 @@ To se děje automaticky. Definujete nástroje a jejich popisy. Model rozhoduje, [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Definujete funkce s jasnými popisy a specifikacemi parametrů. Model vidí tyto popisy ve svém systémovém promptu a chápe, k čemu každý nástroj slouží. +Definujete funkce s jasnými popisy a specifikacemi parametrů. Model tyto popisy vidí ve svém systémovém promptu a rozumí, k čemu každý nástroj slouží. ```java @Component @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Asistent je automaticky propojen Spring Bootem s: +// Asistent je automaticky propojen pomocí Spring Boot s: // - ChatModel bean // - Všechny metody @Tool z tříd označených @Component // - ChatMemoryProvider pro správu relací ``` -Diagram níže rozebírá každou anotaci a ukazuje, jak každý prvek pomáhá AI pochopit, kdy nástroj zavolat a jaké argumenty předat: +Níže uvedený diagram rozebírá každou anotaci a ukazuje, jak každý prvek pomáhá AI pochopit, kdy nástroj volat a jaké argumenty předat: -Anatomy of Tool Definitions +Anatomie definic nástrojů -*Anatomie definice nástroje — @Tool říká AI, kdy jej použít, @P popisuje každý parametr a @AiService vše při startu propojí.* +*Anatomie definice nástroje — @Tool řekne AI, kdy ho použít, @P popisuje každý parametr a @AiService vše při spuštění propojí.* > **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) a zeptejte se: -> - „Jak bych integroval skutečné API počasí, třeba OpenWeatherMap, místo testovacích dat?“ -> - „Co dělá dobrý popis nástroje, který pomáhá AI správně jej používat?“ -> - „Jak řešit chyby API a limity rychlosti v implementaci nástrojů?“ +> - "Jak bych integroval reálné API počasí jako OpenWeatherMap místo simulovaných dat?" +> - "Co tvoří dobrý popis nástroje, který pomůže AI použít ho správně?" +> - "Jak řešit chyby API a limity volání v implementaci nástrojů?" ### Rozhodování -Když uživatel položí otázku „Jaké je počasí v Seattlu?“, model si náhodně nevybere nástroj. Porovnává uživatelův záměr s popisy všech dostupných nástrojů, každému přiřazuje skóre relevanci a vybere nejlepší shodu. Pak vygeneruje strukturovaný volací příkaz s odpovídajícími parametry — v tomto případě nastaví `location` na `"Seattle"`. +Když uživatel položí otázku „Jaké je počasí v Seattlu?“, model náhodně nenabízí nástroj. Porovnává uživatelův záměr s popisy všech nástrojů, které má k dispozici, hodnotí každý podle relevance a vybere nejlepší shodu. Poté vygeneruje strukturované volání funkce s odpovídajícími parametry – v tomto případě nastaví `location` na `"Seattle"`. -Pokud žádný nástroj nesedí na uživatelův požadavek, model odpoví z vlastní znalosti. Pokud sedí více nástrojů, vybere ten nejpřesnější. +Pokud žádný nástroj neodpovídá požadavku uživatele, model odpovídá ze svých znalostí. Pokud jich odpovídá více, vybere ten nejkonkrétnější. -How the AI Decides Which Tool to Use +Jak AI rozhoduje, který nástroj použít -*Model porovnává každý dostupný nástroj s uživatelovým záměrem a vybírá nejlepší shodu — proto je důležité psát jasné a konkrétní popisy nástrojů.* +*Model hodnotí každý dostupný nástroj vzhledem k záměru uživatele a vybírá nejlepší shodu — proto je důležité psát jasné, konkrétní popisy nástrojů.* -### Vykonání +### Provedení [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot automaticky propojí deklarativní rozhraní `@AiService` se všemi registrovanými nástroji a LangChain4j volání nástrojů provádí automaticky. V pozadí probíhá kompletní volání nástroje přes šest fází — od uživatelovy otázky v přirozeném jazyce až zpět k odpovědi v přirozeném jazyce: +Spring Boot automaticky propojí deklarativní rozhraní `@AiService` se všemi registrovanými nástroji a LangChain4j provádí volání nástrojů automaticky. Za scénou prochází celé volání nástroje šesti fázemi – od uživatelovy otázky v přirozeném jazyce až po odpověď také v přirozeném jazyce: -Tool Calling Flow +Tok volání nástroje -*Celý průběh — uživatel položí otázku, model vybere nástroj, LangChain4j ho vykoná a model začleňuje výsledek do přirozené odpovědi.* +*Konečný tok — uživatel položí otázku, model vybere nástroj, LangChain4j ho spustí a model výsledek začlení do odpovědi.* -Pokud jste spustili [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) v Modulu 00, už jste viděli tento vzor v akci — nástroje `Calculator` se volaly stejným způsobem. Následující sekvenční diagram ukazuje přesně, co se během té ukázky dělo pod pokličkou: +Pod kapotou `AiServices` provádí stejnou smyčku volání nástrojů pro libovolný nástroj — zde znázorněno na jednoduchém `Calculator`. Níže uvedený sekvenční diagram ukazuje přesně, co se děje: -Tool Calling Sequence Diagram +Sekvenční diagram volání nástroje -*Cyklus volání nástroje z ukázky Quick Start — `AiServices` posílá vaši zprávu a schéma nástroje do LLM, LLM odpoví voláním funkce jako `add(42, 58)`, LangChain4j místně vykoná metodu `Calculator` a vrátí výsledek pro konečnou odpověď.* +*Smyčka volání nástrojů — `AiServices` posílá vaši zprávu a schémata nástrojů do LLM, LLM odpoví voláním funkce jako `add(42, 58)`, LangChain4j provede metodu `Calculator` lokálně a výsledek vrací zpět pro konečnou odpověď.* > **🤖 Vyzkoušejte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otevřete [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) a zeptejte se: -> - „Jak funguje vzor ReAct a proč je efektivní pro AI agenty?“ -> - „Jak agent rozhoduje, který nástroj použít a v jakém pořadí?“ -> - „Co se stane, pokud vykonání nástroje selže - jak řešit chyby robustně?“ +> - "Jak funguje vzor ReAct a proč je efektivní pro AI agenty?" +> - "Jak agent rozhoduje, který nástroj použít a v jakém pořadí?" +> - "Co se stane, pokud se provedení nástroje nezdaří – jak robustně řešit chyby?" ### Generování odpovědi -Model obdrží data o počasí a formátuje je do přirozené jazykové odpovědi uživateli. +Model obdrží data o počasí a formátuje je do odpovědi v přirozeném jazyce pro uživatele. -### Architektura: Spring Boot automatické propojení +### Architektura: Spring Boot Auto-Wiring -Tento modul používá integraci LangChain4j se Spring Bootem s deklarativními rozhraními `@AiService`. Při startu Spring Boot automaticky najde každý `@Component`, který obsahuje metody s `@Tool`, váš bean `ChatModel` a `ChatMemoryProvider` — a všechny je propojí do jednoho rozhraní `Assistant` bez potřeby boilerplate kódu. +Tento modul používá integraci LangChain4j se Spring Bootem s deklarativními rozhraními `@AiService`. Při spuštění Spring Boot detekuje všechny `@Component` obsahující metody s `@Tool`, váš `ChatModel` bean a `ChatMemoryProvider` — a pak je všechny propojí do jediného rozhraní `Assistant` bez potřeby boilterplate kódu. -Spring Boot Auto-Wiring Architecture +Architektura Spring Boot Auto-Wiring -*Rozhraní @AiService spojuje ChatModel, komponenty nástrojů a poskytovatele paměti — Spring Boot automaticky zajišťuje jejich propojení.* +*Rozhraní @AiService spojuje ChatModel, komponenty nástrojů a poskytovatele paměti — Spring Boot vše propojuje automaticky.* -Zde je celý životní cyklus požadavku jako sekvenční diagram — od HTTP požadavku přes controller, service a automaticky propojený proxy až k vykonání nástroje a zpět: +Zde je celý životní cyklus požadavku jako sekvenční diagram — od HTTP požadavku přes controller, službu a auto-vázaný proxy až po provedení nástroje a zpět: -Spring Boot Tool Calling Sequence +Sekvence volání nástroje ve Spring Bootu -*Kompletní životní cyklus požadavku Spring Boot — HTTP požadavek prochází přes controller a service k automaticky propojenému proxy `Assistant`, které automaticky zajišťuje orchestraci LLM a volání nástrojů.* +*Kompletní životní cyklus požadavku ve Spring Bootu — HTTP požadavek prochází přes controller a službu k auto-vázanému proxy Asistenta, který automaticky koordinuje LLM a volání nástrojů.* Klíčové výhody tohoto přístupu: -- **Spring Boot automatické propojení** — ChatModel a nástroje automaticky injektovány -- **Vzor @MemoryId** — Automatická správa paměti založená na relacích -- **Jediná instance** — Assistant vytvořen jednou a znovu použít pro lepší výkon -- **Typově bezpečné vykonání** — Java metody volány přímo s konverzí typů -- **Vícekroková orchestrací** — Automaticky řeší řetězení nástrojů -- **Nulový boilerplate** — Žádné manuální volání `AiServices.builder()` nebo paměťových HashMap +- **Spring Boot auto-wiring** — ChatModel a nástroje jsou automaticky vloženy +- **vzor @MemoryId** — Automatická správa paměti na bázi relace +- **Jedna instance** — Assistant je vytvořen jednou a opakovaně použit pro lepší výkon +- **Bezpečné typy** — Metody Javy jsou volány přímo s konverzí typů +- **Více kroků orchestrace** — Automaticky zvládá řetězení nástrojů +- **Žádný boilerplate** — Žádné ruční volání `AiServices.builder()` nebo paměťové HashMapy -Alternativní přístupy (manuální `AiServices.builder()`) vyžadují více kódu a postrádají výhody integrace se Spring Bootem. +Alternativní přístupy (ruční `AiServices.builder()`) vyžadují více kódu a postrádají výhody integrace se Spring Bootem. ## Řetězení nástrojů -**Řetězení nástrojů** — Skutečná síla agentů založených na nástrojích se ukazuje, když jedna otázka vyžaduje použití více nástrojů. Zeptejte se na „Jaké je počasí v Seattlu ve Fahrenheitech?“ a agent automaticky řetězí dva nástroje: nejprve zavolá `getCurrentWeather` pro získání teploty ve stupních Celsia, pak tuto hodnotu předá do `celsiusToFahrenheit` pro převod — vše v jediném kole konverzace. +**Řetězení nástrojů** — Skutečná síla agentů založených na nástrojích se ukáže, když jedna otázka vyžaduje více nástrojů. Zeptejte se „Jaké je počasí v Seattlu ve Fahrenheit?“ a agent automaticky řetězí dva nástroje: nejprve zavolá `getCurrentWeather` pro získání teploty v Celsiích, potom předá tuto hodnotu do `celsiusToFahrenheit` pro převod — to vše v jednom kole konverzace. -Tool Chaining Example +Příklad řetězení nástrojů -*Řetězení nástrojů v akci — agent nejdříve zavolá getCurrentWeather, výsledek v Celsiích předá do celsiusToFahrenheit a poskytne kombinovanou odpověď.* +*Řetězení nástrojů v akci — agent nejprve volá getCurrentWeather, pak předává výsledek ve Celsiích do celsiusToFahrenheit a poskytne kombinovanou odpověď.* -**Hladké selhání** — Zeptejte se na počasí ve městě, které není v testovacích datech. Nástroj vrátí chybovou zprávu a AI vysvětlí, že nedokáže pomoci, místo aby spadl. Nástroje selhávají bezpečně. Diagram níže ukazuje dva přístupy — při správném zpracování chyb agent chybu zachytí a odpoví nápomocně, zatímco bez něj aplikace spadne: +**Elegantní selhání** — Zeptejte se na počasí ve městě, které není v simulovaných datech. Nástroj vrátí chybovou zprávu a AI vysvětlí, že nemůže pomoci, místo aby spadl program. Nástroje selhávají bezpečně. Níže uvedený diagram porovnává oba přístupy — s řádnou obsluhou chyb agent chybu zachytí a odpoví nápomocně, bez ní celá aplikace spadne: -Error Handling Flow +Tok zpracování chyb -*Když nástroj selže, agent chybu zachytí a odpoví s užitečným vysvětlením místo pádu.* +*Když nástroj selže, agent zachytí chybu a odpoví s užitečným vysvětlením místo pádu aplikace.* -To se děje v rámci jediného kola konverzace. Agent samostatně orchestruje více volání nástrojů. +To probíhá v jednom kole konverzace. Agent autonomně orchestruje vícenásobná volání nástrojů. ## Spuštění aplikace **Ověření nasazení:** -Ujistěte se, že `.env` soubor existuje v kořenovém adresáři s Azure přihlašovacími údaji (vytvořené během Modulu 01). Spusťte z adresáře modulu (`04-tools/`): +Zkontrolujte, že v kořenovém adresáři existuje soubor `.env` s přihlašovacími údaji Azure (vytvořen během Modulu 01). Spusťte toto z adresáře modulu (`04-tools/`): **Bash:** ```bash @@ -205,34 +205,34 @@ cat ../.env # Mělo by zobrazit AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Mělo by zobrazit AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Spusťte aplikaci:** +**Spuštění aplikace:** -> **Poznámka:** Pokud jste již spustili všechny aplikace pomocí `./start-all.sh` z kořenového adresáře (jak popisuje Modul 01), tento modul je již spuštěný na portu 8084. Můžete přeskočit příkazy spuštění níže a přejít přímo na http://localhost:8084. +> **Poznámka:** Pokud jste už spustili všechny aplikace pomocí `./start-all.sh` z kořenového adresáře (jak je popsáno v Modulu 01), tento modul už běží na portu 8084. Můžete přeskočit příkazy ke spuštění níže a jít přímo na http://localhost:8084. **Možnost 1: Použití Spring Boot Dashboard (doporučeno pro uživatele VS Code)** -Vývojový kontejner obsahuje rozšíření Spring Boot Dashboard, které poskytuje vizuální rozhraní pro správu všech Spring Boot aplikací. Najdete ho v liště aktivit na levé straně VS Code (hledáte ikonu Spring Boot). +Vývojový kontejner obsahuje rozšíření Spring Boot Dashboard, které poskytuje vizuální rozhraní pro správu všech Spring Boot aplikací. Najdete ho v postranním panelu vlevo ve VS Code (ikona Spring Boot). -V Spring Boot Dashboard můžete: +Ve Spring Boot Dashboard můžete: - Vidět všechny dostupné Spring Boot aplikace v pracovním prostoru -- Spouštět/zastavovat aplikace jedním kliknutím -- Prohlížet si logy aplikace v reálném čase -- Monitorovat stav aplikace -Jednoduše klikněte na tlačítko přehrát vedle "tools" pro spuštění tohoto modulu, nebo spusťte všechny moduly najednou. +- Spustit/zastavit aplikace jedním kliknutím +- Zobrazit logy aplikací v reálném čase +- Monitorovat stav aplikací -Takto vypadá Spring Boot Dashboard ve VS Code: +Jednoduše klikněte na tlačítko přehrávání vedle „tools“ pro spuštění tohoto modulu nebo spusťte všechny moduly najednou. +Takto vypadá Spring Boot Dashboard ve VS Code: Spring Boot Dashboard -*Spring Boot Dashboard ve VS Code — spuštění, zastavení a sledování všech modulů z jednoho místa* +*Spring Boot Dashboard ve VS Code — spuštění, zastavení a monitorování všech modulů na jednom místě* -**Varianta 2: Použití shell skriptů** +**Možnost 2: Použití shell skriptů** Spusťte všechny webové aplikace (moduly 01-04): **Bash:** ```bash -cd .. # Ze základního adresáře +cd .. # Z kořenového adresáře ./start-all.sh ``` @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Oba skripty automaticky načítají proměnné prostředí ze souboru `.env` v kořenovém adresáři a pokud JAR soubory neexistují, vytvoří je. +Oba skripty automaticky načítají proměnné prostředí z kořenového souboru `.env` a vytvoří JARy, pokud neexistují. -> **Poznámka:** Pokud chcete všechny moduly nejdříve manuálně sestavit před spuštěním: +> **Poznámka:** Pokud preferujete ruční sestavení všech modulů před spuštěním: > > **Bash:** > ```bash @@ -272,7 +272,7 @@ Oba skripty automaticky načítají proměnné prostředí ze souboru `.env` v k > mvn clean package -DskipTests > ``` -Otevřete v prohlížeči http://localhost:8084. +Otevřete http://localhost:8084 ve svém prohlížeči. **Pro zastavení:** @@ -292,84 +292,84 @@ cd ..; .\stop-all.ps1 # Všechny moduly ## Použití aplikace -Aplikace poskytuje webové rozhraní, kde můžete komunikovat s AI agentem, který má přístup k nástrojům pro počasí a převody teplot. Takto vypadá rozhraní — obsahuje rychlé startovací příklady a chatovací panel pro odesílání požadavků: +Aplikace poskytuje webové rozhraní, kde můžete komunikovat s AI agentem, který má přístup k nástrojům pro počasí a převod teplot. Takto rozhraní vypadá — zahrnuje rychlé příklady a chatovací panel pro odesílání požadavků: AI Agent Tools Interface -*Rozhraní AI Agent Tools - rychlé příklady a chat pro interakci s nástroji* +*Rozhraní AI Agent Tools – rychlé příklady a chatovací rozhraní pro interakci s nástroji* ### Vyzkoušejte jednoduché použití nástroje -Začněte jednoduchým požadavkem: "Převést 100 stupňů Fahrenheita na Celsia". Agent rozpozná, že potřebuje nástroj pro převod teplot, zavolá ho s potřebnými parametry a vrátí výsledek. Všimněte si, jak to působí přirozeně - nemuseli jste uvádět, který nástroj použít nebo jak ho zavolat. +Začněte jednoduchým požadavkem: „Převést 100 stupňů Fahrenheita na Celsia“. Agent rozpozná, že potřebuje nástroj pro převod teplot, zavolá ho s správnými parametry a vrátí výsledek. Všimněte si, jak přirozené to působí – neurčili jste, který nástroj použít nebo jak ho vyvolat. ### Otestujte řetězení nástrojů -Teď zkuste něco složitějšího: "Jaké je počasí v Seattlu a převeď ho na Fahrenheity?" Sledujte, jak agent postupuje krok za krokem. Nejprve zjistí počasí (vrací se v Celsiích), pak pozná, že je potřeba převést na Fahrenheity, zavolá nástroj pro převod a oba výsledky spojí do jedné odpovědi. +Nyní zkuste složitější požadavek: „Jaké je počasí v Seattlu a převeď to na Fahrenheit?“ Sledujte, jak agent postupuje krok za krokem. Nejprve získá počasí (které vrací v Celsiích), rozpozná potřebu převodu na Fahrenheit, zavolá převodní nástroj a oba výsledky zkombinuje do jedné odpovědi. ### Sledujte tok konverzace -Chatovací rozhraní uchovává historii konverzací, což umožňuje vícekolové interakce. Vidíte všechny předchozí dotazy a odpovědi, což usnadňuje sledování konverzace a pochopení, jak agent vytváří kontext přes více výměn. +Chatovací rozhraní uchovává historii konverzace, což umožňuje vícetahové interakce. Můžete vidět všechny předchozí dotazy a odpovědi, což usnadňuje sledování konverzace a pochopení, jak agent buduje kontext během více výměn. Conversation with Multiple Tool Calls -*Vícekroková konverzace ukazující jednoduché převody, vyhledávání počasí a řetězení nástrojů* +*Vícetahová konverzace ukazující jednoduché převody, vyhledávání počasí a řetězení nástrojů* ### Experimentujte s různými požadavky Vyzkoušejte různé kombinace: -- Vyhledávání počasí: "Jaké je počasí v Tokiu?" -- Převody teplot: "Kolik je 25 °C v Kelvinech?" -- Kombinované dotazy: "Zkontroluj počasí v Paříži a řekni mi, jestli je nad 20 °C" +- Vyhledávání počasí: „Jaké je počasí v Tokiu?“ +- Převody teplot: „Kolik je 25 °C v Kelvinech?“ +- Kombinované dotazy: „Zkontroluj počasí v Paříži a řekni mi, jestli je nad 20 °C“ -Všimněte si, jak agent interpretuje přirozený jazyk a mapuje ho na odpovídající volání nástrojů. +Všimněte si, jak agent interpretuje přirozený jazyk a mapuje ho na vhodné volání nástrojů. -## Klíčové pojmy +## Klíčové koncepty -### ReAct vzor (Reasoning and Acting) +### Vzor ReAct (Rozumování a jednání) -Agent střídá rozvažování (rozhodování, co udělat) a jednání (používání nástrojů). Tento vzor umožňuje autonomní řešení problémů místo pouhého reagování na instrukce. +Agent střídá fáze rozumování (rozhodování, co dělat) a jednání (použití nástrojů). Tento vzor umožňuje autonomní řešení problémů místo pouhého reagování na pokyny. ### Popisy nástrojů jsou důležité -Kvalita popisů nástrojů přímo ovlivňuje, jak dobře je agent používá. Jasné a specifické popisy pomáhají modelu pochopit, kdy a jak každý nástroj zavolat. +Kvalita popisů vašich nástrojů přímo ovlivňuje, jak je agent využívá. Jasné, konkrétní popisy pomáhají modelu pochopit, kdy a jak každý nástroj zavolat. ### Správa relací -Anotace `@MemoryId` umožňuje automatickou správu paměti na základě relace. Každé ID relace dostane vlastní instanci `ChatMemory`, kterou spravuje bean `ChatMemoryProvider`, takže více uživatelů může interagovat s agentem současně, aniž by se jejich konverzace proplétaly. Následující diagram ukazuje, jak jsou uživatelé směrováni na izolované paměťové úložiště na základě jejich ID relace: +Anotace `@MemoryId` umožňuje automatickou správu paměti na základě relací. Každé ID relace má vlastní instanci `ChatMemory`, kterou spravuje bean `ChatMemoryProvider`, takže více uživatelů může komunikovat s agentem současně bez prolínání konverzací. Následující diagram ukazuje, jak jsou uživatelé směrováni do izolovaných pamětí podle ID relací: Session Management with @MemoryId -*Každé ID relace odpovídá izolované historii konverzace — uživatelé nikdy nevidí zprávy jiných.* +*Každé ID relace odpovídá izolované historii konverzace — uživatelé nikdy nevidí zprávy ostatních.* ### Zpracování chyb -Nástroje mohou selhat — API může vypršet časový limit, parametry mohou být neplatné, externí služby mohou vypadnout. Produkční agenti potřebují zpracování chyb, aby model mohl vysvětlit problémy nebo zkusit alternativy místo pádu celé aplikace. Když nástroj vyhodí výjimku, LangChain4j ji zachytí a pošle chybovou zprávu zpět modelu, který pak problém vysvětlí přirozeným jazykem. +Nástroje mohou selhat — API může vypršet čas, parametry mohou být neplatné, externí služby mohou být nedostupné. Produkční agenti potřebují zpracování chyb, aby model mohl vysvětlit problémy nebo zkusit alternativy namísto zhroucení celé aplikace. Když nástroj vyhodí výjimku, LangChain4j ji zachytí a předá chybovou zprávu zpět modelu, který pak může problém vysvětlit přirozeným jazykem. ## Dostupné nástroje -Níže uvedený diagram ukazuje široký ekosystém nástrojů, které můžete vytvářet. Tento modul demonstruje nástroje pro počasí a teplotu, ale stejný vzor `@Tool` funguje pro jakoukoliv Java metodu — od databázových dotazů až po zpracování plateb. +Diagram níže ukazuje široký ekosystém nástrojů, které můžete vytvářet. Tento modul demonstruje nástroje pro počasí a teploty, ale stejný vzor `@Tool` funguje pro jakoukoli metodu v Javě — od databázových dotazů po zpracování plateb. Tool Ecosystem -*Jakákoliv Java metoda anotovaná `@Tool` je dostupná AI — tento vzor se rozšiřuje na databáze, API, e-maily, operace se soubory a další.* +*Každá Java metoda anotovaná `@Tool` se stává dostupnou AI — vzor se rozšiřuje na databáze, API, e-maily, souborové operace a další.* ## Kdy používat agenty založené na nástrojích -Ne každý požadavek potřebuje nástroje. Rozhodnutí závisí na tom, zda AI potřebuje komunikovat s externími systémy, nebo může odpovědět ze svých znalostí. Následující průvodce shrnuje, kdy nástroje přidávají hodnotu a kdy nejsou potřeba: +Ne každý požadavek vyžaduje nástroje. Rozhodnutí závisí na tom, zda AI potřebuje interagovat s externími systémy, nebo zda může odpovědět ze svých znalostí. Následující průvodce shrnuje, kdy nástroje přidávají hodnotu a kdy jsou zbytečné: When to Use Tools -*Rychlý průvodce rozhodováním — nástroje jsou pro data v reálném čase, výpočty a akce; obecné znalosti a kreativní úkoly je nepotřebují.* +*Rychlý rozhodovací průvodce — nástroje jsou pro data v reálném čase, výpočty a akce; obecné znalosti a kreativní úkoly je nepotřebují.* ## Nástroje vs RAG -Moduly 03 a 04 oba rozšiřují, co může AI dělat, ale zásadně odlišnými způsoby. RAG poskytuje modelu přístup ke **znalostem** načítáním dokumentů. Nástroje dávají modelu schopnost provádět **akce** voláním funkcí. Následující diagram porovnává tyto dva přístupy vedle sebe — od toho, jak každý pracovní postup funguje, až po kompromisy mezi nimi: +Moduly 03 a 04 rozšiřují schopnosti AI, ale zcela odlišnými způsoby. RAG poskytuje modelu přístup ke **znalostem** vyhledáváním dokumentů. Nástroje dávají modelu schopnost podnikat **akce** zavoláním funkcí. Níže je porovnání těchto dvou přístupů vedle sebe — od fungování workflow až po kompromisy mezi nimi: Tools vs RAG Comparison -*RAG vyhledává informace ve statických dokumentech — nástroje vykonávají akce a získávají dynamická, aktuální data. Mnoho produkčních systémů kombinuje oba.* +*RAG vyhledává informace ve statických dokumentech — nástroje vykonávají akce a získávají dynamická, aktuální data. Mnoho produkčních systémů kombinuje obojí.* -V praxi mnoho produkčních systémů kombinuje oba přístupy: RAG pro zakotvení odpovědí ve vaší dokumentaci a Nástroje pro získávání živých dat nebo provádění operací. +V praxi mnoho produkčních systémů kombinuje oba přístupy: RAG pro zakotvení odpovědí v dokumentaci a nástroje pro získávání živých dat nebo provádění operací. ## Další kroky @@ -382,6 +382,6 @@ V praxi mnoho produkčních systémů kombinuje oba přístupy: RAG pro zakotven --- -**Prohlášení o vyloučení odpovědnosti**: -Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). I když usilujeme o přesnost, mějte prosím na paměti, že automatické překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho mateřském jazyce by měl být považován za závazný zdroj. Pro důležité informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoliv nedorozumění nebo mylné interpretace vzniklé použitím tohoto překladu. +**Prohlášení o omezení odpovědnosti**: +Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu. \ No newline at end of file diff --git a/translations/cs/README.md b/translations/cs/README.md index 1a68ae916..0cfa4a6e4 100644 --- a/translations/cs/README.md +++ b/translations/cs/README.md @@ -9,11 +9,11 @@ Kurz pro vytváření AI aplikací s LangChain4j a Azure OpenAI GPT-5.2, od zák #### Podporováno přes GitHub Action (automatizováno a vždy aktuální) -[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](./README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) +[Arabština](../ar/README.md) | [Bengálština](../bn/README.md) | [Bulharština](../bg/README.md) | [Barmština (Myanmar)](../my/README.md) | [Čínština (zjednodušená)](../zh-CN/README.md) | [Čínština (tradiční, Hong Kong)](../zh-HK/README.md) | [Čínština (tradiční, Macau)](../zh-MO/README.md) | [Čínština (tradiční, Taiwan)](../zh-TW/README.md) | [Chorvatština](../hr/README.md) | [Čeština](./README.md) | [Dánština](../da/README.md) | [Nizozemština](../nl/README.md) | [Estonština](../et/README.md) | [Finština](../fi/README.md) | [Francouzština](../fr/README.md) | [Němčina](../de/README.md) | [Řečtina](../el/README.md) | [Hebrejština](../he/README.md) | [Hindština](../hi/README.md) | [Maďarština](../hu/README.md) | [Indonéština](../id/README.md) | [Italština](../it/README.md) | [ japonština](../ja/README.md) | [Kannadština](../kn/README.md) | [Khmérština](../km/README.md) | [Korejština](../ko/README.md) | [Litevština](../lt/README.md) | [Malajština](../ms/README.md) | [Malayalam](../ml/README.md) | [Maráthština](../mr/README.md) | [Nepálština](../ne/README.md) | [Nigerijská pidžinština](../pcm/README.md) | [Norština](../no/README.md) | [Perština (Farsi)](../fa/README.md) | [Polština](../pl/README.md) | [Portugalština (Brazílie)](../pt-BR/README.md) | [Portugalština (Portugalsko)](../pt-PT/README.md) | [Paňdžábština (Gurmukhí)](../pa/README.md) | [Rumunština](../ro/README.md) | [Ruština](../ru/README.md) | [Srbština (cyrilice)](../sr/README.md) | [Slovenština](../sk/README.md) | [Slovinština](../sl/README.md) | [Španělština](../es/README.md) | [Svahilština](../sw/README.md) | [Švédština](../sv/README.md) | [Tagalog (Filipínština)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugština](../te/README.md) | [Thajština](../th/README.md) | [Turečtina](../tr/README.md) | [Ukrajinština](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamština](../vi/README.md) -> **Dáváte přednost lokálnímu klonování?** +> **Raději klonovat lokálně?** > -> Tento repozitář obsahuje více než 50 jazykových překladů, což výrazně zvětšuje velikost stahování. Pro klonování bez překladů použijte sparse checkout: +> Toto úložiště obsahuje více než 50 překladů jazyků, což výrazně zvyšuje velikost stahování. Pokud chcete klonovat bez překladů, použijte sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -34,16 +34,15 @@ Kurz pro vytváření AI aplikací s LangChain4j a Azure OpenAI GPT-5.2, od zák ## Obsah -1. [Rychlý start](00-quick-start/README.md) - Začínáme s LangChain4j -2. [Úvod](01-introduction/README.md) - Naučte se základy LangChain4j -3. [Prompt Engineering](02-prompt-engineering/README.md) - Ovládněte efektivní návrh promptů -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Vytvořte inteligentní znalostní systémy -5. [Nástroje](04-tools/README.md) - Integrujte externí nástroje a jednoduché asistenty -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Práce s protokolem Model Context Protocol (MCP) a agentními moduly +1. [Úvod](01-introduction/README.md) - Naučte se základy LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Ovládněte efektivní návrh promptů +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Vytvářejte inteligentní systémy založené na znalostech +4. [Nástroje](04-tools/README.md) - Integrace externích nástrojů a jednoduchých asistentů +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Práce s protokolem Model Context Protocol (MCP) a Agentickými moduly -### Video návody +### Video průvodci -Každý modul má doprovodné živé vysílání, kde krok za krokem probíráme koncepty a kód. +Každý modul má doprovodnou živou relaci, kde krok za krokem procházíme koncepty a kód. | Modul | Video | |--------|-------| @@ -54,33 +53,33 @@ Každý modul má doprovodné živé vysílání, kde krok za krokem probíráme --- -## Učební cesta +## Výuková cesta -**Jste v LangChain4j nováček?** Podívejte se na [glosář](docs/GLOSSARY.md) pro definice klíčových pojmů a konceptů. +**Nový v LangChain4j?** Podívejte se na [Glosář](docs/GLOSSARY.md) pro definice klíčových pojmů a konceptů. > **Rychlý start** -1. Forkněte tento repozitář na svůj GitHub účet -2. Klikněte na **Code** → záložka **Codespaces** → **...** → **Nový s možnostmi...** -3. Použijte výchozí nastavení – tím se vybere vývojové kontejner vytvořený pro tento kurz -4. Klikněte na **Vytvořit codespace** +1. Forkněte toto úložiště na svůj GitHub účet +2. Klikněte na **Code** → záložka **Codespaces** → **...** → **New with options...** +3. Použijte výchozí nastavení – tím vyberete vývojový kontejner vytvořený pro tento kurz +4. Klikněte na **Create codespace** 5. Počkejte 5-10 minut na připravení prostředí -6. Přejděte přímo na [Rychlý start](./00-quick-start/README.md) a začněte! +6. Přejděte přímo na [Úvod](./01-introduction/README.md) a začněte! -Po dokončení modulů prozkoumejte [Průvodce testováním](docs/TESTING.md) a uvidíte testovací koncepty LangChain4j v praxi. +Po dokončení modulů prozkoumejte [Testovací průvodce](docs/TESTING.md) a uvidíte praktické použití testování LangChain4j. -> **Poznámka:** Tento kurz používá jak GitHub Models, tak Azure OpenAI. Modul [Rychlý start](00-quick-start/README.md) využívá GitHub Models (není potřeba předplatné Azure), zatímco moduly 1-5 používají Azure OpenAI. Pokud ještě nemáte, založte si [ZDARMA Azure účet](https://aka.ms/azure-free-account). +> **Poznámka:** Toto školení používá Azure OpenAI. Pokud ještě nemáte účet, začněte s [ZDARMA Azure účtem](https://aka.ms/azure-free-account). -## Učení s GitHub Copilot +## Výuka s GitHub Copilot -Pro rychlý start s kódováním otevřete tento projekt v GitHub Codespace nebo ve svém lokálním IDE s poskytnutým devcontainerem. Devcontainer použitý v tomto kurzu je předkonfigurovaný s GitHub Copilot pro AI párové programování. +Pro rychlý start kódování otevřete tento projekt v GitHub Codespace nebo ve svém lokálním IDE s poskytnutým devcontainerem. Devcontainer použitý v tomto kurzu je předkonfigurován s GitHub Copilot pro AI párové programování. -Každý příklad kódu obsahuje navrhované otázky, které můžete GitHub Copilot položit pro lepší pochopení. Hledejte výzvy 💡/🤖 v: +Každý příklad kódu obsahuje navržené otázky, které můžete položit GitHub Copilotovi, abyste prohloubili své znalosti. Hledejte značky 💡/🤖 v: -- **Hlavičkách Java souborů** – otázky specifické pro každý příklad -- **README modulů** – průzkumné otázky po příkladech kódu +- **Hlavičkách Java souborů** - otázky specifické pro každý příklad +- **README modulů** - průzkumné otázky po příkladech kódu -**Jak používat:** Otevřete libovolný soubor s kódem a zeptejte se Copilota na navrhované otázky. Má plný kontext kódu a umí vysvětlovat, rozšiřovat a navrhovat alternativy. +**Jak používat:** Otevřete jakýkoli kódový soubor a zeptejte se Copilota na navržené otázky. Má plný kontext kódu a může vysvětlit, rozšířit a navrhnout alternativy. Chcete se dozvědět více? Podívejte se na [Copilot pro AI párové programování](https://aka.ms/GitHubCopilotAI). @@ -88,61 +87,61 @@ Chcete se dozvědět více? Podívejte se na [Copilot pro AI párové programov ### LangChain -[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j pro začátečníky](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js pro začátečníky](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain pro začátečníky](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents -[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Agent +[![AZD pro začátečníky](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI pro začátečníky](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP pro začátečníky](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI agenti pro začátečníky](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Série generativní AI -[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +### Série Generative AI +[![Generative AI pro začátečníky](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) [![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Základní učení -[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +### Core Learning +[![ML pro začátečníky](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science pro začátečníky](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI pro začátečníky](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Kybernetická bezpečnost pro začátečníky](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Webový vývoj pro začátečníky](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT pro začátečníky](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR vývoj pro začátečníky](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Řada Copilot -[![Copilot pro AI párové programování](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot pro C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot dobrodružství](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +### Série Copilot +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Získání pomoci -Pokud narazíte na problém nebo máte jakékoli otázky ohledně tvorby AI aplikací, přidejte se: +Pokud se zaseknete nebo máte jakékoliv otázky ohledně vytváření AI aplikací, připojte se: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Máte-li zpětnou vazbu k produktu nebo chyby při tvorbě, navštivte: +Pokud máte zpětnou vazbu k produktu nebo narazíte na chyby při vývoji, navštivte: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licence -Licence MIT - Detaily naleznete v souboru [LICENSE](../../LICENSE). +Licence MIT - Viz soubor [LICENSE](../../LICENSE) pro podrobnosti. --- -**Disclaimer**: -Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o přesnost, mějte prosím na paměti, že automatické překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho rodném jazyce by měl být považován za závazný zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoliv nedorozumění nebo nesprávné výklady vyplývající z použití tohoto překladu. +**Prohlášení o omezení odpovědnosti**: +Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu. \ No newline at end of file diff --git a/translations/cs/docs/GLOSSARY.md b/translations/cs/docs/GLOSSARY.md index 5bfb61639..ff45b6b18 100644 --- a/translations/cs/docs/GLOSSARY.md +++ b/translations/cs/docs/GLOSSARY.md @@ -1,70 +1,70 @@ -# LangChain4j Slovník pojmů +# Slovník LangChain4j ## Obsah -- [Jádrové pojmy](../../../docs) -- [Komponenty LangChain4j](../../../docs) -- [AI/ML pojmy](../../../docs) -- [Ochranné mechanismy](../../../docs) -- [Řízení příkazů (prompt engineering)](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agenti a nástroje](../../../docs) -- [Agentický modul](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure služby](../../../docs) -- [Testování a vývoj](../../../docs) +- [Základní pojmy](#základní-pojmy) +- [Komponenty LangChain4j](#komponenty-langchain4j) +- [Koncepty AI/ML](#koncepty-aiml) +- [Bezpečnostní opatření](#bezpečnostní-opatření) +- [Tvorba promptů](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agentové a nástroje](#agents-and-tools---module-04) +- [Agentní modul](#agentic-module---module-05) +- [Modelový kontextový protokol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure služby](#azure-services---module-01) +- [Testování a vývoj](#testing-and-development---testing-guide) Rychlá reference pojmů a konceptů používaných v celém kurzu. -## Jádrové pojmy +## Základní pojmy -**AI Agent** - Systém používající AI k autonomnímu uvažování a jednání. [Modul 04](../04-tools/README.md) +**AI Agent** - Systém, který používá AI k autonomnímu uvažování a jednání. [Modul 04](../04-tools/README.md) -**Řetězec (Chain)** - Sekvence operací, kde výstup je vstupem do dalšího kroku. +**Chain** - Sekvence operací, kde výstup jde jako vstup do dalšího kroku. -**Chunking** - Rozdělování dokumentů na menší části. Typicky 300-500 tokenů s překrytím. [Modul 03](../03-rag/README.md) +**Chunking** - Rozdělování dokumentů na menší části. Typicky: 300-500 tokenů s překryvem. [Modul 03](../03-rag/README.md) -**Context Window** - Maximální počet tokenů, které model dokáže zpracovat. GPT-5.2: 400K tokenů (až 272K vstup, 128K výstup). +**Context Window** - Maximální počet tokenů, které model může zpracovat. GPT-5.2: 400 tisíc tokenů (až 272 tisíc vstup, 128 tisíc výstup). -**Embeddings** - Číselné vektory představující význam textu. [Modul 03](../03-rag/README.md) +**Embeddings** - Číselné vektory reprezentující význam textu. [Modul 03](../03-rag/README.md) -**Volání funkce (Function Calling)** - Model generuje strukturované požadavky k vyvolání externích funkcí. [Modul 04](../04-tools/README.md) +**Function Calling** - Model generuje strukturované požadavky na volání externích funkcí. [Modul 04](../04-tools/README.md) **Halucinace** - Když modely generují nesprávné, ale věrohodné informace. **Prompt** - Textový vstup do jazykového modelu. [Modul 02](../02-prompt-engineering/README.md) -**Sémantické vyhledávání** - Vyhledávání podle významu pomocí embeddings, nikoli klíčových slov. [Modul 03](../03-rag/README.md) +**Sémantické vyhledávání** - Vyhledávání podle významu pomocí embeddings, ne podle klíčových slov. [Modul 03](../03-rag/README.md) -**Stavový vs Bezustavový (Stateful vs Stateless)** - Bezustavový: bez paměti. Stavový: uchovává historii konverzace. [Modul 01](../01-introduction/README.md) +**Stavový vs Bezstavový** - Bezstavový: bez paměti. Stavový: udržuje historii konverzace. [Modul 01](../01-introduction/README.md) -**Tokeny** - Základní textové jednotky zpracovávané modely. Ovlivňují náklady a limity. [Modul 01](../01-introduction/README.md) +**Tokeny** - Základní textové jednotky, které modely zpracovávají. Ovlivňují náklady a limity. [Modul 01](../01-introduction/README.md) -**Řetězení nástrojů (Tool Chaining)** - Sekvenční spouštění nástrojů, kde výstup informuje další volání. [Modul 04](../04-tools/README.md) +**Tool Chaining** - Sekvenční spouštění nástrojů, kde výstup ovlivňuje další volání. [Modul 04](../04-tools/README.md) ## Komponenty LangChain4j -**AiServices** - Vytváří typově bezpečné rozhraní AI služeb. +**AiServices** - Vytváří typově bezpečné AI rozhraní služeb. -**OpenAiOfficialChatModel** - Jednotný klient pro modely OpenAI a Azure OpenAI. +**OpenAiOfficialChatModel** - Jednotný klient pro OpenAI a Azure OpenAI modely. -**OpenAiOfficialEmbeddingModel** - Vytváří embeddings pomocí klienta OpenAI Official (podporuje OpenAI i Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Vytváří embeddings pomocí oficiálního klienta OpenAI (podporuje OpenAI i Azure OpenAI). -**ChatModel** - Jádrové rozhraní pro jazykové modely. +**ChatModel** - Základní rozhraní pro jazykové modely. -**ChatMemory** - Uchovává historii konverzace. +**ChatMemory** - Udržuje historii konverzace. -**ContentRetriever** - Vyhledává relevantní části dokumentů pro RAG. +**ContentRetriever** - Vyhledává relevantní kusy dokumentů pro RAG. -**DocumentSplitter** - Rozděluje dokumenty na kousky. +**DocumentSplitter** - Rozděluje dokumenty na části. **EmbeddingModel** - Převádí text na číselné vektory. **EmbeddingStore** - Ukládá a načítá embeddings. -**MessageWindowChatMemory** - Uchovává posuvné okno nedávných zpráv. +**MessageWindowChatMemory** - Udržuje posuvné okno nedávných zpráv. -**PromptTemplate** - Vytváří znovupoužitelné prompty s `{{variable}}` zástupci. +**PromptTemplate** - Vytváří znovupoužitelné prompty s `{{variable}}` zástupnými symboly. **TextSegment** - Textový segment s metadaty. Používá se v RAG. @@ -72,161 +72,159 @@ Rychlá reference pojmů a konceptů používaných v celém kurzu. **UserMessage / AiMessage / SystemMessage** - Typy zpráv v konverzaci. -## AI/ML pojmy +## Koncepty AI/ML -**Učení s několika příklady (Few-Shot Learning)** - Zadávání příkladů v promptech. [Modul 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Poskytování příkladů v promptech. [Modul 02](../02-prompt-engineering/README.md) -**Velký jazykový model (LLM)** - AI modely trénované na obrovských datových sadách textu. +**Velký jazykový model (LLM)** - AI modely trénované na rozsáhlých textových datech. -**Úroveň úvahy (Reasoning Effort)** - Parametr GPT-5.2 ovládající hloubku uvažování. [Modul 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - Parametr GPT-5.2 ovlivňující hloubku uvažování. [Modul 02](../02-prompt-engineering/README.md) -**Teplota (Temperature)** - Řídí náhodnost výstupu. Nízká=deterministické, vysoká=tvůrčí. +**Teplota (Temperature)** - Řídí náhodnost výstupu. Nízká=deterministická, vysoká=tvůrčí. **Vektorová databáze** - Specializovaná databáze pro embeddings. [Modul 03](../03-rag/README.md) -**Učení bez příkladů (Zero-Shot Learning)** - Provádění úkolů bez příkladů. [Modul 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Plnění úloh bez příkladů. [Modul 02](../02-prompt-engineering/README.md) -## Ochranné mechanismy - [Modul 00](../00-quick-start/README.md) +## Bezpečnostní opatření -**Defense in Depth** - Vícevrstvá bezpečnostní metoda kombinující aplikační ochranné mechanismy s filtry poskytovatelů. +**Defense in Depth** - Vícevrstvý bezpečnostní přístup kombinující aplikační bezpečnostní opatření s bezpečnostními filtry poskytovatele. -**Hard Block** - Poskytovatel vrací HTTP 400 chybu při závažném porušení obsahu. +**Hard Block** - Poskytovatel vrací chybu HTTP 400 při závažném porušení obsahu. -**InputGuardrail** - Rozhraní LangChain4j pro ověřování vstupů uživatele před dosažením LLM. Šetří náklady a zpoždění tím, že brání škodlivým promptům včas. +**InputGuardrail** - Rozhraní LangChain4j pro validaci uživatelského vstupu před jeho zpracováním LLM. Šetří náklady a latenci tím, že blokuje škodlivé prompty včas. -**InputGuardrailResult** - Návratový typ pro ověření vstupního guardrailu: `success()` nebo `fatal("důvod")`. +**InputGuardrailResult** - Návratový typ validace guardrail: `success()` nebo `fatal("důvod")`. -**OutputGuardrail** - Rozhraní pro ověřování AI odpovědí před jejich vrácením uživatelům. +**OutputGuardrail** - Rozhraní pro validaci AI odpovědí před jejich předáním uživatelům. -**Provider Safety Filters** - Vestavěné obsahové filtry AI poskytovatelů (např. GitHub Models), které zachytí porušení na úrovni API. +**Bezpečnostní filtry poskytovatele** - Vestavěné filtry obsahu od AI poskytovatelů (např. Azure OpenAI), které zachytávají porušení na úrovni API. -**Soft Refusal** - Model zdvořile odmítne odpovědět bez vyvolání chyby. +**Soft Refusal** - Model zdvořile odmítne odpovědět, aniž by vyhodil chybu. -## Řízení příkazů (prompt engineering) - [Modul 02](../02-prompt-engineering/README.md) +## Tvorba promptů - [Modul 02](../02-prompt-engineering/README.md) -**Řetězení myšlenek (Chain-of-Thought)** - Krok za krokem uvažování pro lepší přesnost. +**Chain-of-Thought** - Krok za krokem odůvodňování pro lepší přesnost. -**Omezený výstup (Constrained Output)** - Vynucení specifického formátu nebo struktury. +**Omezený výstup** - Vynucení specifického formátu nebo struktury. -**Vysoká snaha (High Eagerness)** - Vzor GPT-5.2 pro důkladné uvažování. +**High Eagerness** - Vzor GPT-5.2 pro důkladné uvažování. -**Nízká snaha (Low Eagerness)** - Vzor GPT-5.2 pro rychlé odpovědi. +**Low Eagerness** - Vzor GPT-5.2 pro rychlé odpovědi. -**Vícekolová konverzace (Multi-Turn Conversation)** - Uchovávání kontextu napříč výměnami. +**Vícekolová konverzace** - Udržování kontextu přes výměny. -**Role-Based Prompting** - Nastavení persony modelu pomocí systémových zpráv. +**Role-Based Prompting** - Nastavení modelové persóny pomocí systémových zpráv. -**Sebe-reflexe (Self-Reflection)** - Model posuzuje a zlepšuje svůj výstup. +**Sebereflexe** - Model hodnotí a vylepšuje svůj výstup. -**Strukturovaná analýza (Structured Analysis)** - Pevný hodnotící rámec. +**Strukturovaná analýza** - Fixní rámec hodnocení. -**Vzor vykonávání úkolu (Task Execution Pattern)** - Plánuj → Vykonej → Shrň. +**Vzor vykonání úkolu** - Plánuj → Vykonej → Shrň. ## RAG (Retrieval-Augmented Generation) - [Modul 03](../03-rag/README.md) -**Pipeline zpracování dokumentů** - Načíst → rozdělit → vložit do embedů → uložit. +**Pipeline zpracování dokumentů** - Načti → rozděluj → embeduj → ulož. -**In-memory embedding store** - Nepersistentní úložiště pro testování. +**In-Memory Embedding Store** - Nepersistentní úložiště pro testování. -**RAG** - Kombinuje vyhledávání s generováním pro zakotvení odpovědí. +**RAG** - Kombinuje vyhledávání a generování pro ověřené odpovědi. -**Skóre podobnosti (Similarity Score)** - Míra (0-1) sémantické podobnosti. +**Podobnostní skóre** - Míra (0-1) sémantické podobnosti. -**Zdrojová reference (Source Reference)** - Metadata o vyhledaném obsahu. +**Reference zdroje** - Metadata o načteném obsahu. -## Agenti a nástroje - [Modul 04](../04-tools/README.md) +## Agentové a nástroje - [Modul 04](../04-tools/README.md) -**@Tool anotace** - Označuje metody v Javě jako nástroje volatelné AI. +**@Tool Annotation** - Označuje Java metody jako AI-volatelné nástroje. -**ReAct pattern** - Uvažuj → jednej → pozoruj → opakuj. +**ReAct Pattern** - Uvažuj → jednej → pozoruj → opakuj. -**Správa relací (Session Management)** - Oddělené kontexty pro různé uživatele. +**Správa sezení** - Oddělené kontexty pro různé uživatele. **Nástroj (Tool)** - Funkce, kterou může AI agent volat. -**Popis nástroje (Tool Description)** - Dokumentace účelu a parametrů nástroje. +**Popis nástroje** - Dokumentace účelu nástroje a parametrů. -## Agentický modul - [Modul 05](../05-mcp/README.md) +## Agentní modul - [Modul 05](../05-mcp/README.md) -**@Agent anotace** - Označuje rozhraní jako AI agenty s deklarativní definicí chování. +**@Agent Annotation** - Označuje rozhraní jako AI agenty s deklarativní definicí chování. -**Agent Listener** - Háček pro sledování běhu agentů přes `beforeAgentInvocation()` a `afterAgentInvocation()`. +**Agent Listener** - Háček pro monitorování spuštění agenta přes `beforeAgentInvocation()` a `afterAgentInvocation()`. -**Agentický rozsah (Agentic Scope)** - Sdílená paměť, kam agenti ukládají výstupy s klíčem `outputKey` pro konzumaci dalšími agenty. +**Agentic Scope** - Sdílená paměť, kam agenti ukládají výsledky pomocí `outputKey` pro další agenty. -**AgenticServices** - Továrna pro tvorbu agentů pomocí `agentBuilder()` a `supervisorBuilder()`. +**AgenticServices** - Továrna pro vytváření agentů použitím `agentBuilder()` a `supervisorBuilder()`. -**Podmíněný workflow (Conditional Workflow)** - Směrování na různé specialisty podle podmínek. +**Podmíněný workflow** - Směrování na základě podmínek k různým specializovaným agentům. -**Human-in-the-Loop** - Vzorec workflow přidávající lidské kontrolní body pro schválení nebo revizi obsahu. +**Human-in-the-Loop** - Vzorec workflow přidávající lidské kontroly pro schválení nebo revizi obsahu. **langchain4j-agentic** - Maven závislost pro deklarativní tvorbu agentů (experimentální). -**Smyčkový workflow (Loop Workflow)** - Iterace opakovaného běhu agenta do splnění podmínky (např. skóre kvality ≥ 0.8). +**Loop Workflow** - Iterace vykonávání agenta dokud není splněna podmínka (např. skóre kvality ≥ 0.8). -**outputKey** - Parametr anotace agenta určující, kam se ukládají výsledky v Agentic Scope. +**outputKey** - Parametr anotace agenta určující, kde jsou výsledky ukládány v Agentic Scope. -**Paralelní workflow (Parallel Workflow)** - Současný běh více agentů na nezávislých úkolech. +**Paralelní workflow** - Současné spuštění více agentů pro nezávislé úkoly. -**Strategie odpovědí (Response Strategy)** - Jak dozor formulujefinální odpověď: POSLEDNÍ, SOUHRN nebo OHODNOCENÁ. +**Strategie odpovědi** - Jak supervisor formuluje finální odpověď: POSLEDNÍ, SHRNUTÍ nebo SKÓROVANÉ. -**Sekvenční workflow (Sequential Workflow)** - Postupné spouštění agentů, kde výstup plyne do dalšího kroku. +**Sekvenční workflow** - Spouštění agentů za sebou, kde výstup jde do dalšího kroku. -**Vzorec dozorčího agenta (Supervisor Agent Pattern)** - Pokročilý agentický vzorec, kde dozorčí LLM dynamicky rozhoduje o volání podagentů. +**Supervisor Agent Pattern** - Pokročilý agentní vzorec, kde supervisorský LLM dynamicky rozhoduje, které pod-agenty zavolat. -## Model Context Protocol (MCP) - [Modul 05](../05-mcp/README.md) +## Modelový kontextový protokol (MCP) - [Modul 05](../05-mcp/README.md) **langchain4j-mcp** - Maven závislost pro integraci MCP v LangChain4j. -**MCP** - Model Context Protocol: standard pro propojení AI aplikací s externími nástroji. Postav jednou, použij všude. +**MCP** - Model Context Protocol: standard pro připojení AI aplikací k externím nástrojům. Napiš jednou, používej všude. -**MCP Client** - Aplikace, která se připojuje k MCP serverům pro objevování a používání nástrojů. +**MCP Client** - Aplikace, která se připojuje k MCP serverům, aby objevovala a používala nástroje. -**MCP Server** - Služba vystavující nástroje přes MCP s popisy a schématy parametrů. +**MCP Server** - Služba zpřístupňující nástroje přes MCP s jasnými popisy a schématy parametrů. **McpToolProvider** - Komponenta LangChain4j, která obaluje MCP nástroje pro použití v AI službách a agentech. **McpTransport** - Rozhraní pro MCP komunikaci. Implementace zahrnují Stdio a HTTP. -**Stdio Transport** - Lokální procesní transport přes stdin/stdout. Vhodné pro přístup k souborům nebo příkazové nástroje. +**Stdio Transport** - Lokální procesní transport přes stdin/stdout. Vhodné pro přístup k souborovému systému nebo příkazové nástroje. -**StdioMcpTransport** - Implementace LangChain4j, která spouští MCP server jako podproces. +**StdioMcpTransport** - Implementace LangChain4j spouštějící MCP server jako podproces. -**Objevování nástrojů (Tool Discovery)** - Klient dotazuje server na dostupné nástroje s popisy a schématy. +**Objevování nástrojů** - Klient dotazuje server na dostupné nástroje s popisy a schématy. ## Azure služby - [Modul 01](../01-introduction/README.md) -**Azure AI Search** - Cloudové vyhledávání s vektorovou podporou. [Modul 03](../03-rag/README.md) +**Azure AI Search** - Cloudové vyhledávání s vektorovými schopnostmi. [Modul 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Nástroj pro nasazení Azure zdrojů. +**Azure Developer CLI (azd)** - Nasazování Azure zdrojů. -**Azure OpenAI** - Podniková AI služba Microsoftu. +**Azure OpenAI** - Enterprise AI služba Microsoftu. -**Bicep** - Jazyk pro infrastrukturu jako kód v Azure. [Příručka infrastruktury](../01-introduction/infra/README.md) +**Bicep** - Jazyk pro infrastrukturu jako kód na Azure. [Průvodce infrastrukturou](../01-introduction/infra/README.md) -**Název nasazení** - Název nasazení modelu v Azure. +**Název nasazení** - Název pro nasazení modelu v Azure. **GPT-5.2** - Nejnovější model OpenAI s řízením uvažování. [Modul 02](../02-prompt-engineering/README.md) -## Testování a vývoj - [Testovací příručka](TESTING.md) +## Testování a vývoj - [Průvodce testováním](TESTING.md) -**Dev Container** - Kontejnerizované vývojové prostředí. [Konfigurace](../../../.devcontainer/devcontainer.json) +**Vývojový kontejner** - Kontejnerizované vývojové prostředí. [Konfigurace](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Volné AI modelové hřiště. [Modul 00](../00-quick-start/README.md) +**Testování v paměti** - Testování s paměťovým úložištěm. -**Testování v paměti (In-Memory Testing)** - Testování s úložištěm v paměti. +**Integrační testování** - Testování s reálnou infrastrukturou. -**Integrační testování (Integration Testing)** - Testování s reálnou infrastrukturou. - -**Maven** - Nástroj pro automatizaci sestavení v Javě. +**Maven** - Nástroj pro automatizaci buildů v Javě. **Mockito** - Java framework pro mockování. -**Spring Boot** - Java aplikační rámec. [Modul 01](../01-introduction/README.md) +**Spring Boot** - Java aplikační framework. [Modul 01](../01-introduction/README.md) --- -**Prohlášení o vyloučení odpovědnosti**: -Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). I když usilujeme o přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za žádná nedorozumění nebo nesprávné výklady vzniklé z užití tohoto překladu. +**Prohlášení o omezení odpovědnosti**: +Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu. \ No newline at end of file diff --git a/translations/cs/docs/TESTING.md b/translations/cs/docs/TESTING.md index c71eb37a0..d717772e1 100644 --- a/translations/cs/docs/TESTING.md +++ b/translations/cs/docs/TESTING.md @@ -2,110 +2,105 @@ ## Obsah -- [Rychlý start](../../../docs) -- [Co testy pokrývají](../../../docs) -- [Spouštění testů](../../../docs) -- [Spouštění testů ve VS Code](../../../docs) -- [Testovací vzory](../../../docs) -- [Filozofie testování](../../../docs) -- [Další kroky](../../../docs) +- [Rychlý start](#rychlý-start) +- [Co testy pokrývají](#co-testy-pokrývají) +- [Spouštění testů](#spouštění-testů) +- [Spouštění testů ve VS Code](#spouštění-testů-ve-vs-code) +- [Testovací vzory](#testovací-vzory) +- [Filozofie testování](#filozofie-testování) +- [Další kroky](#další-kroky) -Tato příručka vás provede testy, které ukazují, jak testovat AI aplikace bez potřeby API klíčů nebo externích služeb. +Tento průvodce vás provede testy, které ukazují, jak testovat AI aplikace bez potřeby API klíčů nebo externích služeb. ## Rychlý start Spusťte všechny testy jediným příkazem: -**Bash:** +**Bash:** ```bash mvn test ``` - -**PowerShell:** + +**PowerShell:** ```powershell mvn --% test ``` - -Když všechny testy projdou, měli byste vidět výstup podobný následujícímu screenshotu — testy proběhnou bez chyb. -Successful Test Results +Když všechny testy projdou, měla by se zobrazit výstup podobný níže uvedené obrazovce — testy proběhnou bez chyb. + +Úspěšné výsledky testů -*Úspěšné spuštění testů, kde všechny testy prošly bez chyb* +*Úspěšné spuštění testů ukazující všechny testy projít bez chyb* ## Co testy pokrývají -Tento kurz se zaměřuje na **jednotkové testy**, které běží lokálně. Každý test ukazuje konkrétní koncept LangChain4j izolovaně. Níže uvedená testovací pyramida ukazuje, kam jednotkové testy zapadají — tvoří rychlý, spolehlivý základ, na kterém je postavena zbytek vaší testovací strategie. +Tento kurz se zaměřuje na **jednotkové testy**, které běží lokálně. Každý test demonstruje konkrétní koncept LangChain4j izolovaně. Níže uvedená pyramida testování ukazuje, kde jednotkové testy zapadají — tvoří rychlý a spolehlivý základ, na kterém je postaven zbytek vaší testovací strategie. -Testing Pyramid +Testovací pyramida -*Testovací pyramida ukazující vyváženost mezi jednotkovými testy (rychlé, izolované), integračními testy (reálné komponenty) a end-to-end testy. Tento kurz pokrývá jednotkové testování.* +*Testovací pyramida ukazující rovnováhu mezi jednotkovými testy (rychlé, izolované), integračními testy (reálné komponenty) a end-to-end testy. Toto školení pokrývá jednotkové testování.* | Modul | Testy | Zaměření | Klíčové soubory | |--------|-------|----------|-----------------| -| **00 - Rychlý start** | 6 | Šablony promptů a substituce proměnných | `SimpleQuickStartTest.java` | | **01 - Úvod** | 8 | Paměť konverzace a stavový chat | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | Vzory GPT-5.2, úrovně ochoty, strukturovaný výstup | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Zpracování dokumentů, embeddingy, vyhledávání podobnosti | `DocumentServiceTest.java` | -| **04 - Nástroje** | 12 | Vytváření funkcí a řetězení nástrojů | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Protokol modelového kontextu s stdio transportem | `SimpleMcpTest.java` | +| **02 - Tvorba promptů** | 12 | Vzory GPT-5.2, úrovně ochoty, strukturovaný výstup | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Ingest dokumentů, embeddingy, vyhledávání podobnosti | `DocumentServiceTest.java` | +| **04 - Nástroje** | 12 | Volání funkcí a řetězení nástrojů | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Protokol Model Context s použitím stdio transportu | `SimpleMcpTest.java` | ## Spouštění testů -**Spustit všechny testy z kořenové složky:** +**Spusťte všechny testy ze složky root:** -**Bash:** +**Bash:** ```bash mvn test ``` - -**PowerShell:** + +**PowerShell:** ```powershell mvn --% test ``` - -**Spustit testy pro konkrétní modul:** +**Spusťte testy konkrétního modulu:** -**Bash:** +**Bash:** ```bash cd 01-introduction && mvn test # Nebo z kořene mvn test -pl 01-introduction ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 01-introduction; mvn --% test # Nebo z kořene mvn --% test -pl 01-introduction ``` +**Spusťte jednotlivou třídu testů:** -**Spustit jednu testovací třídu:** - -**Bash:** +**Bash:** ```bash mvn test -Dtest=SimpleConversationTest ``` - -**PowerShell:** + +**PowerShell:** ```powershell mvn --% test -Dtest=SimpleConversationTest ``` - -**Spustit konkrétní testovací metodu:** +**Spusťte konkrétní testovací metodu:** -**Bash:** +**Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#měl by udržovat historii konverzace +mvn test -Dtest=SimpleConversationTest#měla by udržovat historii konverzace ``` - -**PowerShell:** + +**PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#měl by udržovat historii konverzace +mvn --% test -Dtest=SimpleConversationTest#měli byste udržovat historii konverzace ``` - ## Spouštění testů ve VS Code @@ -113,27 +108,27 @@ Pokud používáte Visual Studio Code, Test Explorer poskytuje grafické rozhran VS Code Test Explorer -*Test Explorer ve VS Code ukazuje strom testů se všemi Java testovacími třídami a jednotlivými testovacími metodami* +*VS Code Test Explorer ukazující strom testů se všemi Java testovacími třídami a jednotlivými testovacími metodami* -**Pro spuštění testů ve VS Code:** +**Jak spustit testy ve VS Code:** -1. Otevřete Test Explorer kliknutím na ikonu zkumavky v aktivitním panelu -2. Rozbalte strom testů, abyste viděli všechny moduly a testovací třídy -3. Klikněte na tlačítko pro přehrání vedle libovolného testu pro jeho individuální spuštění -4. Klikněte na "Run All Tests" pro spuštění celé sady -5. Pravým klikem na test vyberte "Debug Test" pro nastavení breakpointů a krokování kódem +1. Otevřete Test Explorer kliknutím na ikonu kádinky v panelu aktivit +2. Rozbalte strom testů, abyste viděli všechny moduly a testovací třídy +3. Klikněte na tlačítko přehrávání vedle kterékoli testu pro individuální spuštění +4. Klikněte na „Run All Tests“ pro spuštění celé sady +5. Klikněte pravým tlačítkem na test a vyberte „Debug Test“ pro nastavení breakpointů a krokování kódem -Test Explorer zobrazuje zelené fajfky u úspěšných testů a poskytuje podrobné zprávy o chybách, jsou-li testy neúspěšné. +Test Explorer zobrazuje zelené zatržítka pro úspěšné testy a poskytuje podrobné chybové zprávy při selhání testů. ## Testovací vzory ### Vzor 1: Testování šablon promptů -Nejjednodušší vzor testuje šablony promptů bez volání AI modelu. Ověřujete, že substituce proměnných funguje správně a prompt je formátován očekávaným způsobem. +Nejjednodušší vzor testuje šablony promptů bez volání AI modelu. Ověřujete, že nahrazení proměnných funguje správně a prompty jsou formátovány dle očekávání. -Prompt Template Testing +Testování šablony promptu -*Testování šablon promptů, ukazující průtok substituce hodnot: šablona s místy pro vložení hodnot → aplikovaná hodnota → ověřený formátovaný výstup* +*Testování šablon promptů ukazující tok nahrazování proměnných: šablona s místy pro hodnoty → aplikované hodnoty → ověřený formátovaný výstup* ```java @Test @@ -151,29 +146,16 @@ void testPromptTemplateFormatting() { assertThat(prompt.text()).isEqualTo("Best time to visit Paris for sightseeing?"); } ``` - -Tento test je v souboru `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. -**Spuštění:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testFormátováníŠablonyVýzvy -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testováníFormátováníŠablonyVýzvy -``` - +Tento vzor ověřuje, že nahrazení proměnných funguje správně a prompty jsou formátovány, jak se očekává — není potřeba API klíč ani volání modelu. ### Vzor 2: Mockování jazykových modelů -Při testování logiky konverzace použijte Mockito k vytvoření falešných modelů, které vrací předem dané odpovědi. Díky tomu jsou testy rychlé, zdarma a deterministické. +Při testování logiky konverzace použijte Mockito k vytvoření falešných modelů, které vracejí předem dané odpovědi. Díky tomu jsou testy rychlé, zdarma a deterministické. -Mock vs Real API Comparison +Srovnání mock vs skutečné API -*Porovnání ukazující, proč jsou mockety preferovány při testování: jsou rychlé, zdarma, deterministické a nevyžadují API klíče* +*Srovnání ukazující, proč jsou misky preferované pro testování: jsou rychlé, zdarma, deterministické a nevyžadují API klíče* ```java @ExtendWith(MockitoExtension.class) @@ -218,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 zprávy uživatele + 3 zprávy AI + assertThat(history).hasSize(6); // 3 uživatelské + 3 AI zprávy } } ``` - -Tento vzor je použit v `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock zajišťuje konzistentní chování, takže lze ověřit správné řízení paměti. + +Tento vzor je použit v `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock zajistí konzistentní chování pro ověření správného fungování správy paměti. ### Vzor 3: Testování izolace konverzace -Paměť konverzace musí udržovat uživatele oddělené. Tento test ověřuje, že se konverzace nekombinují. +Paměť konverzace musí udržovat uživatele odděleně. Tento test ověřuje, že se konverzace navzájem nekontextují. -Conversation Isolation +Izolace konverzace -*Testování izolace konverzace ukazuje oddělené úložiště paměti pro různé uživatele, aby nedocházelo ke křížení kontextů* +*Testování izolace konverzace ukazující oddělené paměťové úložiště pro různé uživatele, aby nedocházelo ke smíchání kontextů* ```java @Test @@ -254,16 +236,16 @@ void shouldIsolateConversationsByid() { assertThat(history2).hasSize(2); } ``` - -Každá konverzace si udržuje vlastní nezávislou historii. V produkčních systémech je tato izolace kritická pro multi-uživatelské aplikace. -### Vzor 4: Testování nástrojů nezávisle +Každá konverzace má vlastní nezávislou historii. V produkčních systémech je tato izolace kritická pro víceuživatelské aplikace. -Nástroje jsou funkce, které AI může volat. Testujte je přímo, abyste zajistili správnost bez ohledu na rozhodnutí AI. +### Vzor 4: Testování nástrojů samostatně -Tools Testing +Nástroje jsou funkce, které může AI volat. Otestujte je přímo, aby bylo zajištěno, že fungují správně bez ohledu na rozhodnutí AI. -*Testování nástrojů samostatně ukazující provádění mock nástrojů bez volání AI pro ověření obchodní logiky* +Testování nástrojů + +*Testování nástrojů samostatně ukazující simulované spuštění nástrojů bez volání AI pro ověření podnikové logiky* ```java @Test @@ -285,16 +267,16 @@ void shouldDemonstrateToolChaining() { assertThat(conversionResult).containsPattern("71[.,]6°F"); } ``` - -Tyto testy z `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ověřují logiku nástrojů bez zapojení AI. Příklad řetězení ukazuje, jak výstup jednoho nástroje jde jako vstup do dalšího. + +Tyto testy z `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ověřují logiku nástrojů bez zapojení AI. Příklad řetězení ukazuje, jak výstup jednoho nástroje slouží jako vstup do druhého. ### Vzor 5: Testování RAG v paměti -RAG systémy tradičně vyžadují vektorové databáze a embedding služby. Vzor v paměti vám umožňuje testovat celý proces bez externích závislostí. +RAG systémy tradičně vyžadují vektorové databáze a embeddingové služby. Vzor v paměti umožňuje testovat celý proces bez externích závislostí. -In-Memory RAG Testing +Testování RAG v paměti -*Testovací workflow RAG v paměti ukazující parsování dokumentu, ukládání embeddingů a vyhledávání podle podobnosti bez potřeby databáze* +*Průběh testování RAG v paměti ukazující zpracování dokumentu, ukládání embeddingů a vyhledávání podobnosti bez potřeby databáze* ```java @Test @@ -310,52 +292,50 @@ void testProcessTextDocument() { assertEquals("test.txt", result.segments().get(0).metadata().getString("filename")); } ``` - -Tento test z `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` vytvoří dokument v paměti a ověřuje rozdělování na části a zpracování metadat. + +Tento test z `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` vytváří dokument v paměti a ověřuje rozdělení na části a zpracování metadat. ### Vzor 6: Integrační testování MCP -Modul MCP testuje integraci Model Context Protokolu pomocí stdio transportu. Tyto testy ověřují, že vaše aplikace může spouštět MCP servery jako podprocesy a komunikovat s nimi. +Modul MCP testuje integraci Model Context Protocol s použitím stdio transportu. Tyto testy ověřují, že vaše aplikace může spouštět a komunikovat s MCP servery jako podprocesy. -Testy v `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validují chování klienta MCP. +Testy v `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` ověřují chování MCP klienta. -**Spuštění:** +**Spusťte je:** -**Bash:** +**Bash:** ```bash cd 05-mcp && mvn test ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 05-mcp; mvn --% test ``` - ## Filozofie testování -Testujte svůj kód, ne AI. Vaše testy by měly ověřovat kód, který píšete, kontrolovat, jak jsou prompt šablony konstruovány, jak je řízena paměť a jak se vykonávají nástroje. Odpovědi AI se liší a neměly by být součástí testovacích ověření. Ptejte se, zda vaše šablona správně nahrazuje proměnné, ne jestli AI dává správnou odpověď. +Testujte svůj kód, ne AI. Vaše testy by měly ověřovat kód, který píšete, tím že kontrolují, jak jsou prompt šablony sestavené, jak se spravuje paměť a jak se spouštějí nástroje. AI odpovědi jsou různorodé a neměly by být součástí testovacích tvrzení. Ptejte se, zda vaše šablona promptu správně nahrazuje proměnné, ne zda AI poskytuje správnou odpověď. -Používejte mocky pro jazykové modely. Jsou to externí závislosti, které jsou pomalé, drahé a nedeterministické. Mockování dělá testy rychlými na milisekundy místo sekund, zdarma bez nákladů na API a deterministickými se stejným výsledkem pokaždé. +Používejte mocks pro jazykové modely. Jsou to externí závislosti, které jsou pomalé, drahé a nedeterministické. Mockování dělá testy rychlé (v milisekundách místo sekund), zdarma (bez nákladů na API) a deterministické (stejný výsledek pokaždé). -Udržujte testy nezávislé. Každý test by měl nastavit vlastní data, nespoléhat na jiné testy a sám si po sobě uklidit. Testy by měly projít bez ohledu na pořadí spouštění. +Udržujte testy nezávislé. Každý test by měl nastavit vlastní data, nespoléhat na jiné testy a uklidit po sobě. Testy by měly projít bez ohledu na pořadí spuštění. -Testujte okrajové případy nad rámec šťastné cesty. Zkoušejte prázdné vstupy, velmi velké vstupy, speciální znaky, neplatné parametry a hranice. Tyto často odhalí chyby, které běžné použití nevykáže. +Testujte hraniční případy mimo běžnou cestu. Zkoušejte prázdné vstupy, velmi velké vstupy, speciální znaky, neplatné parametry a okrajové podmínky. Ty často odhalují chyby, které normální použití neodhalí. -Používejte popisná jména. Porovnejte `shouldMaintainConversationHistoryAcrossMultipleMessages()` a `test1()`. První přesně říká, co se testuje, což usnadňuje ladění chyb. +Používejte popisné názvy. Porovnejte `shouldMaintainConversationHistoryAcrossMultipleMessages()` s `test1()`. První přesně popisuje, co se testuje, což zjednodušuje ladění chyb. ## Další kroky -Nyní, když rozumíte testovacím vzorům, ponořte se hlouběji do každého modulu: +Nyní, když rozumíte testovacím vzorům, ponořte se hlouběji do jednotlivých modulů: -- **[00 - Rychlý start](../00-quick-start/README.md)** - Začněte se základy šablon promptů -- **[01 - Úvod](../01-introduction/README.md)** - Naučte se řízení paměti konverzace -- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Ovládněte vzory pro GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Vytvářejte retrieval-augmented generation systémy -- **[04 - Nástroje](../04-tools/README.md)** - Implementujte volání funkcí a řetězce nástrojů -- **[05 - MCP](../05-mcp/README.md)** - Integrujte Model Context Protocol +- **[01 - Úvod](../01-introduction/README.md)** - Naučte se správu paměti konverzace +- **[02 - Tvorba promptů](../02-prompt-engineering/README.md)** - Ovládněte vzory promptů GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Vytvořte systémy pro generování se získáváním informací +- **[04 - Nástroje](../04-tools/README.md)** - Implementujte volání funkcí a řetězení nástrojů +- **[05 - MCP](../05-mcp/README.md)** - Integrujte Model Context Protocol -Každý modul má svůj README s podrobnými vysvětleními konceptů, které zde byly testovány. +README každého modulu nabízí podrobné vysvětlení testovaných konceptů. --- @@ -364,6 +344,6 @@ Každý modul má svůj README s podrobnými vysvětleními konceptů, které zd --- -**Prohlášení o vyloučení odpovědnosti**: -Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). I když usilujeme o přesnost, mějte prosím na paměti, že automatické překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho mateřském jazyce by měl být považován za závazný zdroj. Pro důležité informace se doporučuje profesionální lidský překlad. Neručíme za jakékoli nedorozumění nebo nesprávné výklady vzniklé použitím tohoto překladu. +**Prohlášení o omezení odpovědnosti**: +Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). Přestože usilujeme o co největší přesnost, mějte prosím na paměti, že automatizované překlady mohou obsahovat chyby nebo nepřesnosti. Originální dokument v jeho mateřském jazyce by měl být považován za autoritativní zdroj. Pro kritické informace se doporučuje profesionální lidský překlad. Nejsme odpovědní za jakékoli nedorozumění nebo nesprávné interpretace vzniklé použitím tohoto překladu. \ No newline at end of file diff --git a/translations/da/.co-op-translator.json b/translations/da/.co-op-translator.json index 831c8e401..39b13bfcf 100644 --- a/translations/da/.co-op-translator.json +++ b/translations/da/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "da" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T23:19:41+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T12:09:03+00:00", "source_file": "01-introduction/README.md", "language_code": "da" }, @@ -18,20 +18,20 @@ "language_code": "da" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T23:21:45+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T12:04:44+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "da" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T23:22:58+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T12:08:15+00:00", "source_file": "03-rag/README.md", "language_code": "da" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:14:00+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T12:07:02+00:00", "source_file": "04-tools/README.md", "language_code": "da" }, @@ -54,8 +54,8 @@ "language_code": "da" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:06:38+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T12:03:29+00:00", "source_file": "README.md", "language_code": "da" }, @@ -72,14 +72,14 @@ "language_code": "da" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T23:25:41+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T12:05:13+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "da" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T23:26:19+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T12:05:48+00:00", "source_file": "docs/TESTING.md", "language_code": "da" } diff --git a/translations/da/00-quick-start/README.md b/translations/da/00-quick-start/README.md deleted file mode 100644 index 09b00f170..000000000 --- a/translations/da/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modul 00: Hurtig Start - -## Indholdsfortegnelse - -- [Introduktion](../../../00-quick-start) -- [Hvad er LangChain4j?](../../../00-quick-start) -- [LangChain4j Afhængigheder](../../../00-quick-start) -- [Forudsætninger](../../../00-quick-start) -- [Opsætning](../../../00-quick-start) - - [1. Få dit GitHub-token](../../../00-quick-start) - - [2. Angiv dit token](../../../00-quick-start) -- [Kør eksemplerne](../../../00-quick-start) - - [1. Grundlæggende Chat](../../../00-quick-start) - - [2. Promptmønstre](../../../00-quick-start) - - [3. Funktionsopkald](../../../00-quick-start) - - [4. Dokument Q&A (Easy RAG)](../../../00-quick-start) - - [5. Ansvarlig AI](../../../00-quick-start) -- [Hvad Hver Eksempel Viser](../../../00-quick-start) -- [Næste Trin](../../../00-quick-start) -- [Fejlfinding](../../../00-quick-start) - -## Introduktion - -Denne hurtigstart er ment til at få dig i gang med LangChain4j så hurtigt som muligt. Den dækker det absolutte grundlag for at bygge AI-applikationer med LangChain4j og GitHub Models. I de næste moduler skifter du til Azure OpenAI og GPT-5.2 og dykker dybere ned i hvert koncept. - -## Hvad er LangChain4j? - -LangChain4j er et Java-bibliotek, der forenkler opbygningen af AI-drevne applikationer. I stedet for at håndtere HTTP-klienter og JSON-parsing arbejder du med rene Java-API'er. - -"Chain" i LangChain refererer til at kæde flere komponenter sammen – du kan kæde en prompt til en model til en parser, eller kæde flere AI-opkald, hvor én output fødes videre som input til det næste. Denne hurtigstart fokuserer på grundlæggende før vi udforsker mere komplekse kæder. - -LangChain4j Chaining Concept - -*Kædning af komponenter i LangChain4j – byggeklodser forbindes for at skabe kraftfulde AI-workflows* - -Vi bruger tre kernekomponenter: - -**ChatModel** – Interfacet for AI-modelinteraktioner. Kald `model.chat("prompt")` og få en respons som streng. Vi bruger `OpenAiOfficialChatModel`, som virker med OpenAI-kompatible endpoints som GitHub Models. - -**AiServices** – Opretter typesikre AI service interfaces. Definer metoder, annoter dem med `@Tool`, og LangChain4j håndterer orkestreringen. AI’en kalder automatisk dine Java-metoder når nødvendigt. - -**MessageWindowChatMemory** – Vedligeholder samtalehistorik. Uden denne er hver anmodning uafhængig. Med den husker AI tidligere beskeder og bevarer kontekst på tværs af flere runder. - -LangChain4j Architecture - -*LangChain4j arkitektur – kernekomponenter arbejder sammen for at drive dine AI-applikationer* - -## LangChain4j Afhængigheder - -Denne hurtigstart bruger tre Maven-afhængigheder i [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modulet `langchain4j-open-ai-official` leverer klassen `OpenAiOfficialChatModel`, der forbinder til OpenAI-kompatible API’er. GitHub Models bruger samme API-format, så der behøves ingen særlig adapter – blot peg base-URL’en til `https://models.github.ai/inference`. - -Modulet `langchain4j-easy-rag` leverer automatisk dokumentsplitning, embedding og retrieval, så du kan bygge RAG-applikationer uden manuelt at konfigurere hvert trin. - -## Forudsætninger - -**Bruger du Dev Container?** Java og Maven er allerede installeret. Du skal kun bruge et GitHub Personal Access Token. - -**Lokal Udvikling:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (instruktioner nedenfor) - -> **Bemærk:** Dette modul bruger `gpt-4.1-nano` fra GitHub Models. Ændr ikke modelnavnet i koden – det er konfigureret til at fungere med GitHubs tilgængelige modeller. - -## Opsætning - -### 1. Få dit GitHub-token - -1. Gå til [GitHub Indstillinger → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Klik på "Generate new token" -3. Sæt et beskrivende navn (f.eks. "LangChain4j Demo") -4. Sæt udløbstid (7 dage anbefalet) -5. Under "Account permissions", find "Models" og sæt til "Read-only" -6. Klik "Generate token" -7. Kopiér og gem dit token – du vil ikke se det igen - -### 2. Angiv dit token - -**Mulighed 1: Brug af VS Code (Anbefalet)** - -Hvis du bruger VS Code, tilføj dit token til `.env` filen i projektroden: - -Hvis `.env` filen ikke findes, kopier `.env.example` til `.env` eller opret en ny `.env` fil i projektroden. - -**Eksempel på `.env` fil:** -```bash -# I /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Så kan du blot højreklikke på en hvilken som helst demo-fil (f.eks. `BasicChatDemo.java`) i Explorer og vælge **"Run Java"** eller bruge launch-konfigurationerne i Run and Debug-panelet. - -**Mulighed 2: Brug af Terminal** - -Sæt token som en miljøvariabel: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Kør eksemplerne - -**Med VS Code:** Højreklik på enhver demo-fil i Explorer og vælg **"Run Java"**, eller brug launch-konfigurationerne i Run and Debug-panelet (sørg for at du først har tilføjet dit token til `.env` filen). - -**Med Maven:** Alternativt kan du køre fra kommandolinjen: - -### 1. Grundlæggende Chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Promptmønstre - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Viser zero-shot, few-shot, kæde-af-tanke og rollebaseret prompting. - -### 3. Funktionsopkald - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI kalder automatisk dine Java-metoder når nødvendigt. - -### 4. Dokument Q&A (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Stil spørgsmål om dine dokumenter ved hjælp af Easy RAG med automatisk embedding og retrieval. - -### 5. Ansvarlig AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Se hvordan AI-sikkerhedsfiltre blokerer skadeligt indhold. - -## Hvad Hver Eksempel Viser - -**Grundlæggende Chat** – [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Start her for at se LangChain4j på dets enkleste. Du opretter en `OpenAiOfficialChatModel`, sender en prompt med `.chat()`, og får tilbage et svar. Dette demonstrerer fundamentet: hvordan man initialiserer modeller med brugerdefinerede endpoints og API-nøgler. Når du forstår dette mønster, bygger alt andet på det. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) og spørg: -> - "Hvordan skifter jeg fra GitHub Models til Azure OpenAI i denne kode?" -> - "Hvilke andre parametre kan jeg konfigurere i OpenAiOfficialChatModel.builder()?" -> - "Hvordan tilføjer jeg streaming-svar i stedet for at vente på hele svaret?" - -**Prompt Engineering** – [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Nu hvor du ved, hvordan du taler til en model, lad os udforske hvad du siger til den. Denne demo bruger samme modelopsætning, men viser fem forskellige prompt-mønstre. Prøv zero-shot prompts for direkte instruktioner, few-shot prompts der lærer af eksempler, chain-of-thought prompts der afslører ræsonnementstrin, og rollebaserede prompts der sætter kontekst. Du vil se, hvordan samme model giver dramatisk forskellige resultater baseret på hvordan du rammer din anmodning ind. - -Demoen demonstrerer også prompt-skabeloner, som er en kraftfuld måde at lave genanvendelige prompts med variabler. -Nedenstående eksempel viser en prompt ved hjælp af LangChain4j `PromptTemplate` til at udfylde variabler. AI’en svarer baseret på den angivne destination og aktivitet. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) og spørg: -> - "Hvad er forskellen på zero-shot og few-shot prompting, og hvornår skal jeg bruge hver?" -> - "Hvordan påvirker temperatur-parameteren modellens svar?" -> - "Hvilke teknikker kan forhindre prompt injection angreb i produktion?" -> - "Hvordan kan jeg lave genanvendelige PromptTemplate-objekter til almindelige mønstre?" - -**Tool Integration** – [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Her bliver LangChain4j virkelig kraftfuld. Du bruger `AiServices` til at oprette en AI-assistent, som kan kalde dine Java-metoder. Bare annoter metoder med `@Tool("beskrivelse")`, og LangChain4j klarer resten – AI’en beslutter automatisk, hvornår hvert værktøj skal bruges baseret på hvad brugeren spørger om. Dette demonstrerer funktionsopkald, en nøglemetode til at bygge AI, der kan handle, ikke bare svare på spørgsmål. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) og spørg: -> - "Hvordan virker @Tool-annotationen, og hvad gør LangChain4j med den bag scenen?" -> - "Kan AI kalde flere værktøjer i rækkefølge for at løse komplekse problemer?" -> - "Hvad sker der, hvis et værktøj kaster en undtagelse – hvordan håndterer jeg fejl?" -> - "Hvordan integrerer jeg en rigtig API i stedet for dette lommeregner-eksempel?" - -**Dokument Q&A (Easy RAG)** – [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Her ser du RAG (retrieval-augmented generation) ved hjælp af LangChain4j’s "Easy RAG" tilgang. Dokumenter indlæses, deles automatisk op og embeddes i en in-memory store, hvorefter en indholdsretriever leverer relevante bidder til AI’en ved forespørgselstidspunktet. AI’en svarer baseret på dine dokumenter, ikke sin generelle viden. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) og spørg: -> - "Hvordan forhindrer RAG AI-hallucinationer sammenlignet med at bruge modellens træningsdata?" -> - "Hvad er forskellen på denne nemme tilgang og en tilpasset RAG pipeline?" -> - "Hvordan ville jeg skalere dette til at håndtere flere dokumenter eller større vidensbaser?" - -**Ansvarlig AI** – [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Byg AI-sikkerhed med forsvar i dybden. Denne demo viser to beskyttelseslag, der arbejder sammen: - -**Del 1: LangChain4j Input Guardrails** – Bloker farlige prompts før de når LLM. Opret tilpassede guardrails, der tjekker for forbudte nøgleord eller mønstre. De kører i din kode, så de er hurtige og gratis. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Del 2: Udbyderens Sikkerhedsfiltre** – GitHub Models har indbyggede filtre, der fanger hvad dine guardrails måske misser. Du vil se hårde blokeringer (HTTP 400 fejl) for alvorlige overtrædelser og bløde afslag, hvor AI’en høfligt nægter. - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) og spørg: -> - "Hvad er InputGuardrail, og hvordan laver jeg mine egne?" -> - "Hvad er forskellen mellem en hård blokering og et blødt afslag?" -> - "Hvorfor bruge både guardrails og udbyderfiltre sammen?" - -## Næste Trin - -**Næste Modul:** [01-introduction - Kom godt i gang med LangChain4j](../01-introduction/README.md) - ---- - -**Navigation:** [← Tilbage til Hoved](../README.md) | [Næste: Modul 01 - Introduktion →](../01-introduction/README.md) - ---- - -## Fejlfinding - -### Første Maven Build - -**Problem**: Første `mvn clean compile` eller `mvn package` tager lang tid (10-15 minutter) - -**Årsag**: Maven skal downloade alle projektets afhængigheder (Spring Boot, LangChain4j biblioteker, Azure SDK’er osv.) ved første build. - -**Løsning**: Dette er normal opførsel. Efterfølgende builds bliver meget hurtigere, da afhængigheder caches lokalt. Downloadtiden afhænger af din netværkshastighed. - -### PowerShell Maven Kommando-syntaks - -**Problem**: Maven kommandoer fejler med fejl `Unknown lifecycle phase ".mainClass=..."` -**Årsag**: PowerShell fortolker `=` som en variabel-assigneringsoperator, hvilket ødelægger Maven-egenskabssyntaksen - -**Løsning**: Brug stop-parsing operatoren `--%` før Maven-kommandoen: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operatoren `--%` fortæller PowerShell at sende alle resterende argumenter bogstaveligt til Maven uden fortolkning. - -### Windows PowerShell Emoji-visning - -**Problem**: AI-svar viser uforståelige tegn (f.eks. `????` eller `â??`) i stedet for emojis i PowerShell - -**Årsag**: PowerShells standardkodning understøtter ikke UTF-8 emojis - -**Løsning**: Kør denne kommando før du kører Java-applikationer: -```cmd -chcp 65001 -``` - -Dette tvinger UTF-8 kodning i terminalen. Alternativt kan du bruge Windows Terminal, der har bedre Unicode-understøttelse. - -### Fejlfinding af API-kald - -**Problem**: Autentificeringsfejl, raterestriktioner eller uventede svar fra AI-modellen - -**Løsning**: Eksemplerne inkluderer `.logRequests(true)` og `.logResponses(true)` for at vise API-kald i konsollen. Dette hjælper med at fejlfinde autentificeringsfejl, raterestriktioner eller uventede svar. Fjern disse flags i produktion for at reducere logstøj. - ---- - - -**Ansvarsfraskrivelse**: -Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det oprindelige dokument på dets modersmål bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. - \ No newline at end of file diff --git a/translations/da/01-introduction/README.md b/translations/da/01-introduction/README.md index 37cb2b396..d06d5e35f 100644 --- a/translations/da/01-introduction/README.md +++ b/translations/da/01-introduction/README.md @@ -1,85 +1,85 @@ -# Modul 01: Kom godt i gang med LangChain4j +# Module 01: Kom godt i gang med LangChain4j ## Indholdsfortegnelse -- [Video Gennemgang](../../../01-introduction) -- [Hvad du vil lære](../../../01-introduction) -- [Forudsætninger](../../../01-introduction) -- [Forståelse af det centrale problem](../../../01-introduction) -- [Forståelse af tokens](../../../01-introduction) -- [Hvordan hukommelse fungerer](../../../01-introduction) -- [Hvordan dette bruger LangChain4j](../../../01-introduction) -- [Deploy Azure OpenAI infrastruktur](../../../01-introduction) -- [Kør applikationen lokalt](../../../01-introduction) -- [Brug af applikationen](../../../01-introduction) - - [Stateless chat (venstre panel)](../../../01-introduction) - - [Stateful chat (højre panel)](../../../01-introduction) -- [Næste skridt](../../../01-introduction) +- [Videogennemgang](#videogennemgang) +- [Det du vil lære](#det-du-vil-lære) +- [Forudsætninger](#forudsætninger) +- [Forståelse af kernproblemet](#forståelse-af-kernproblemet) +- [Forståelse af tokens](#forståelse-af-tokens) +- [Hvordan hukommelse fungerer](#hvordan-hukommelse-fungerer) +- [Hvordan dette bruger LangChain4j](#hvordan-dette-bruger-langchain4j) +- [Udrul Azure OpenAI infrastruktur](#udrul-azure-openai-infrastruktur) +- [Kør applikationen lokalt](#kør-applikationen-lokalt) +- [Brug af applikationen](#brug-af-applikationen) + - [Stateless chat (venstre panel)](#stateless-chat-venstre-panel) + - [Stateful chat (højre panel)](#stateful-chat-højre-panel) +- [Næste skridt](#næste-skridt) -## Video Gennemgang +## Videogennemgang -Se denne live session, som forklarer, hvordan du kommer i gang med dette modul: +Se denne live session, der forklarer, hvordan du kommer i gang med dette modul: -Kom godt i gang med LangChain4j - Live Session +Kom godt i gang med LangChain4j - Live session -## Hvad du vil lære +## Det du vil lære -I quick start brugte du GitHub-modeller til at sende prompts, kalde værktøjer, bygge en RAG pipeline og teste sikkerhedsgitre. De demos viste, hvad der er muligt — nu skifter vi til Azure OpenAI og GPT-5.2 og begynder at bygge produktionsagtige applikationer. Dette modul fokuserer på samtale-AI, som husker kontekst og bevarer tilstand — de koncepter som quick start demos brugte i baggrunden men ikke forklarede. +Dette er dit udgangspunkt med LangChain4j og Azure OpenAI. Vi starter med grundlæggende ting og begynder at bygge produktionsparat applikationer. Dette modul fokuserer på konversations-AI, der husker kontekst og bevarer tilstand — de grundlæggende koncepter som alle senere moduler bygger videre på. -Vi bruger Azure OpenAI's GPT-5.2 gennem hele guiden, fordi dens avancerede ræsonneringsmuligheder gør adfærden i forskellige mønstre mere tydelig. Når du tilføjer hukommelse, kan du klart se forskellen. Det gør det lettere at forstå, hvad hver komponent bidrager med til din applikation. +Vi bruger Azure OpenAIs GPT-5.2 gennem hele denne guide, fordi dens avancerede ræsonneringsevner gør adfærden i de forskellige mønstre mere tydelig. Når du tilføjer hukommelse, vil du klart kunne se forskellen. Det gør det lettere at forstå, hvad hver komponent bidrager med til din applikation. -Du vil bygge en applikation, som demonstrerer begge mønstre: +Du vil bygge en applikation, der demonstrerer begge mønstre: -**Stateless Chat** - Hver anmodning er uafhængig. Modellen har ingen hukommelse om tidligere beskeder. Dette er mønstret, du brugte i quick start. +**Stateless Chat** - Hver forespørgsel er uafhængig. Modellen har ingen hukommelse om tidligere beskeder. Dette er det simpleste startpunkt. -**Stateful Conversation** - Hver anmodning inkluderer samtalehistorik. Modellen bevarer kontekst over flere interaktioner. Dette kræves i produktionsapplikationer. +**Stateful Conversation** - Hver forespørgsel inkluderer samtalehistorik. Modellen bevarer kontekst på tværs af flere runder. Dette er hvad produktionsapplikationer kræver. ## Forudsætninger -- Azure abonnement med adgang til Azure OpenAI +- Azure-abonnement med adgang til Azure OpenAI - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Note:** Java, Maven, Azure CLI og Azure Developer CLI (azd) er forhåndsinstalleret i den medfølgende devcontainer. +> **Note:** Java, Maven, Azure CLI og Azure Developer CLI (azd) er forudinstalleret i den medfølgende devcontainer. -> **Note:** Dette modul bruger GPT-5.2 på Azure OpenAI. Deployeringen konfigureres automatisk via `azd up` - ændr ikke modelnavnet i koden. +> **Note:** Dette modul bruger GPT-5.2 på Azure OpenAI. Udrulningen konfigureres automatisk via `azd up` - ændr ikke modelnavnet i koden. -## Forståelse af det centrale problem +## Forståelse af kernproblemet -Sprogbaserede modeller er stateless. Hver API-anmodning er uafhængig. Hvis du sender "Mit navn er John" og derefter spørger "Hvad er mit navn?", har modellen ingen idé om, at du lige har præsenteret dig. Den behandler hver forespørgsel, som om det er den første samtale, du nogensinde har haft. +Sprogmodeller er stateless. Hver API-kald er uafhængigt. Hvis du sender "Mit navn er John" og derefter spørger "Hvad er mit navn?", så har modellen ingen idé om, at du lige har præsenteret dig. Den behandler hver forespørgsel som om, det er den første samtale, du nogensinde har haft. -Det fungerer fint til simple Q&A, men er ubrugeligt til rigtige applikationer. Kundeservice-bots skal huske, hvad du fortalte dem. Personlige assistenter har brug for kontekst. Enhver samtale med flere omgange kræver hukommelse. +Det fungerer fint til simpel spørgsmål-og-svar, men er ubrugeligt til rigtige applikationer. Kundeservice-bots skal kunne huske, hvad du har fortalt dem. Personlige assistenter har brug for kontekst. Enhver samtale med flere runder kræver hukommelse. -Diagrammet nedenfor kontrasterer de to tilgange — til venstre, et stateless kald, som glemmer dit navn; til højre, et stateful kald med ChatMemory, der husker det. +Følgende diagram viser kontrasten mellem de to tilgange — til venstre et stateless kald, der glemmer dit navn; til højre et stateful kald understøttet af ChatMemory, der husker det. Stateless vs Stateful Conversations -*Forskellen mellem stateless (uafhængige kald) og stateful (kontekstbevidste) samtaler* +*Forskellen mellem stateless (uafhængige kald) og stateful (kontekst-aware) samtaler* ## Forståelse af tokens -Før vi dykker ned i samtaler, er det vigtigt at forstå tokens - de grundlæggende enheder af tekst som sprogmodeller behandler: +Før vi dykker ned i samtaler, er det vigtigt at forstå tokens - de grundlæggende enheder af tekst, som sprogmodeller behandler: Token Explanation -*Eksempel på hvordan tekst brydes i tokens - "I love AI!" bliver til 4 separate behandlingsenheder* +*Eksempel på, hvordan tekst opdeles i tokens - "I love AI!" bliver til 4 separate behandlingsenheder* -Tokens er, hvordan AI-modeller måler og behandler tekst. Ord, tegnsætning og endda mellemrum kan være tokens. Din model har en grænse for, hvor mange tokens den kan behandle ad gangen (400.000 for GPT-5.2, med op til 272.000 input-tokens og 128.000 output-tokens). At forstå tokens hjælper dig med at styre samtalens længde og omkostninger. +Tokens er, hvordan AI-modeller måler og behandler tekst. Ord, tegnsætning og endda mellemrum kan være tokens. Din model har et maksimum for, hvor mange tokens den kan behandle på en gang (400.000 for GPT-5.2, med op til 272.000 input tokens og 128.000 output tokens). Forståelsen af tokens hjælper dig med at håndtere samtalens længde og omkostninger. ## Hvordan hukommelse fungerer -Chat memory løser det stateless problem ved at bevare samtalehistorik. Inden du sender din forespørgsel til modellen, tilføjer frameworket relevante tidligere beskeder forrest. Når du spørger "Hvad er mit navn?", sender systemet faktisk hele samtalehistorikken, så modellen kan se, at du tidligere sagde "Mit navn er John." +Chat hukommelse løser det stateless problem ved at bevare samtalehistorik. Før du sender din forespørgsel til modellen, tilføjer frameworket relevante tidligere beskeder forrest. Når du spørger "Hvad er mit navn?", sender systemet faktisk hele samtalehistorikken, så modellen kan se, at du tidligere sagde "Mit navn er John." -LangChain4j leverer hukommelsesimplementeringer, som håndterer dette automatisk. Du vælger, hvor mange beskeder der skal bevares, og frameworket styrer kontekstvinduet. Diagrammet nedenfor viser, hvordan MessageWindowChatMemory opretholder et glidende vindue med nylige beskeder. +LangChain4j tilbyder hukommelsesimplementationer, der håndterer dette automatisk. Du vælger, hvor mange beskeder, der skal gemmes, og frameworket styrer kontekstvinduet. Diagrammet nedenfor viser, hvordan MessageWindowChatMemory bevarer et glidende vindue over nylige beskeder. Memory Window Concept -*MessageWindowChatMemory opretholder et glidende vindue af nylige beskeder, og fjerner automatisk gamle* +*MessageWindowChatMemory bevarer et glidende vindue over nylige beskeder og fjerner automatisk gamle* ## Hvordan dette bruger LangChain4j -Dette modul udvider quick start med integration af Spring Boot og tilføjelse af samtalehukommelse. Sådan passer delene sammen: +Dette modul integrerer Spring Boot og tilføjer samtalehukommelse. Sådan passer brikkerne sammen: **Afhængigheder** - Tilføj to LangChain4j biblioteker: @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builderen læser legitimationsoplysninger fra miljøvariabler sat af `azd up`. Ved at sætte `baseUrl` til din Azure-endpoint får OpenAI-klienten til at fungere med Azure OpenAI. +Builderen læser legitimationsoplysninger fra miljøvariabler sat af `azd up`. Ved at sætte `baseUrl` til dit Azure-endpoint får OpenAI klienten til at arbejde med Azure OpenAI. **Samtalehukommelse** - Spor chat historik med MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,21 +124,21 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Opret hukommelse med `withMaxMessages(10)` for at beholde de sidste 10 beskeder. Tilføj bruger- og AI-beskeder med typede wrappers: `UserMessage.from(text)` og `AiMessage.from(text)`. Hent historik med `memory.messages()` og send den til modellen. Servicen lagrer separate hukommelsesinstanser pr. samtale-ID, så flere brugere kan chatte samtidigt. +Opret hukommelse med `withMaxMessages(10)` for at beholde de sidste 10 beskeder. Tilføj bruger- og AI-beskeder med typede wrapper: `UserMessage.from(text)` og `AiMessage.from(text)`. Hent historik med `memory.messages()` og send den til modellen. Servicen gemmer separate hukommelsesinstanser per samtale-id, så flere brugere kan chatte samtidigt. > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) og spørg: -> - "Hvordan beslutter MessageWindowChatMemory, hvilke beskeder der skal droppes, når vinduet er fuldt?" -> - "Kan jeg implementere tilpasset hukommelseslagring ved brug af en database i stedet for in-memory?" -> - "Hvordan kan jeg tilføje opsummering for at komprimere gammel samtalehistorik?" +> - "Hvordan beslutter MessageWindowChatMemory, hvilke beskeder der droppes, når vinduet er fuldt?" +> - "Kan jeg implementere brugerdefineret hukommelseslagring ved hjælp af en database i stedet for i hukommelsen?" +> - "Hvordan ville jeg tilføje opsummering for at komprimere gammel samtalehistorik?" -Den stateless chat endpoint springer hukommelsen helt over - bare `chatModel.chat(prompt)` som i quick start. Den stateful endpoint tilføjer beskeder til hukommelsen, henter historik og medtager den kontekst med hver anmodning. Samme modelkonfiguration, forskellige mønstre. +Den stateless chat endepunkt springer hukommelse over - bare `chatModel.chat(prompt)` som i hurtigstarten. Det stateful endepunkt tilføjer beskeder til hukommelse, henter historik og inkluderer denne kontekst med hver forespørgsel. Samme modelkonfiguration, forskellige mønstre. -## Deploy Azure OpenAI infrastruktur +## Udrul Azure OpenAI infrastruktur **Bash:** ```bash cd 01-introduction -azd up # Vælg abonnement og placering (anbefales eastus2) +azd up # Vælg abonnement og placering (eastus2 anbefales) ``` **PowerShell:** @@ -147,16 +147,16 @@ cd 01-introduction azd up # Vælg abonnement og placering (eastus2 anbefales) ``` -> **Note:** Hvis du støder på timeout-fejl (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), så kør blot `azd up` igen. Azure-ressourcer kan stadig være under provisionering i baggrunden, og et genkald tillader deployeringen at fuldføres, når ressourcerne når en terminal tilstand. +> **Note:** Hvis du støder på en timeout-fejl (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), så kør blot `azd up` igen. Azure-ressourcer kan stadig provisioneres i baggrunden, og et genforsøg tillader, at udrulningen fuldføres, når ressourcerne når en terminal tilstand. Dette vil: -1. Deployere Azure OpenAI-ressource med GPT-5.2 og text-embedding-3-small modeller -2. Automatisk generere `.env` fil i projektets rod med legitimationsoplysninger -3. Sætte alle nødvendige miljøvariabler op +1. Udrulle Azure OpenAI-ressource med GPT-5.2 og text-embedding-3-small modeller +2. Automatisk generere `.env`-fil i projektroden med legitimationsoplysninger +3. Opsætte alle nødvendige miljøvariabler -**Har du problemer med deployment?** Se [Infrastructure README](infra/README.md) for detaljeret fejlfinding inklusive subdomænenavnkonflikter, manuelle Azure Portal deploy-trin og modelkonfigurationsvejledning. +**Problemer med udrulning?** Se [Infrastructure README](infra/README.md) for detaljeret fejlfinding inklusive konflikter i subdomænenavne, manuelle Azure Portal udrulningstrin og vejledning i modelkonfiguration. -**Bekræft at deployment lykkedes:** +**Bekræft at udrulningen lykkedes:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY osv. Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY osv. ``` -> **Note:** `azd up` kommandoen genererer automatisk `.env` filen. Hvis du har brug for at opdatere den senere, kan du enten redigere `.env` filen manuelt eller regenerere den ved at køre: +> **Note:** `azd up`-kommandoen genererer automatisk `.env`-filen. Hvis du skal opdatere den senere, kan du enten redigere `.env`-filen manuelt eller regenerere den ved at køre: > > **Bash:** > ```bash @@ -184,9 +184,9 @@ Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY osv. ## Kør applikationen lokalt -**Bekræft deployment:** +**Bekræft udrulning:** -Sørg for at `.env` filen findes i rodmappen med Azure legitimationsoplysninger. Kør dette fra modulets bibliotek (`01-introduction/`): +Sørg for, at `.env`-filen findes i roddirektoret med Azure-legitimationsoplysninger. Kør dette fra modulets mappe (`01-introduction/`): **Bash:** ```bash @@ -200,35 +200,35 @@ Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Start applikationerne:** -**Mulighed 1: Brug Spring Boot Dashboard (Anbefalet til VS Code brugere)** +**Valgmulighed 1: Brug Spring Boot Dashboard (anbefales til VS Code brugere)** -Dev containeren inkluderer Spring Boot Dashboard extension, som giver et visuelt interface til at styre alle Spring Boot applikationer. Du finder det i Aktivitetspanelet til venstre i VS Code (se efter Spring Boot-ikonet). +Dev containeren inkluderer Spring Boot Dashboard-udvidelsen, som giver en visuel grænseflade til at styre alle Spring Boot applikationer. Du finder den i aktivitetslinjen til venstre i VS Code (se efter Spring Boot-ikonet). Fra Spring Boot Dashboard kan du: - Se alle tilgængelige Spring Boot applikationer i workspace - Starte/stoppe applikationer med et enkelt klik -- Se applikationslogs i realtid -- Overvåge applikationens status +- Se applikationslogfiler i realtid +- Overvåge applikationers status -Klik blot på play-knappen ved siden af "introduction" for at starte dette modul, eller start alle moduler på én gang. +Klik blot på play-knappen ved siden af "introduction" for at starte dette modul, eller start alle moduler samlet. Spring Boot Dashboard *Spring Boot Dashboard i VS Code — start, stop og overvåg alle moduler fra ét sted* -**Mulighed 2: Brug shell scripts** +**Valgmulighed 2: Brug shell scripts** Start alle webapplikationer (moduler 01-04): **Bash:** ```bash -cd .. # Fra roddirektoriet +cd .. # Fra rodmappen ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Fra roddirectory +cd .. # Fra rodmappen .\start-all.ps1 ``` @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Begge scripts indlæser automatisk miljøvariabler fra rodens `.env` fil og bygger JAR-filerne, hvis de ikke findes. +Begge scripts indlæser automatisk miljøvariabler fra roden `.env`-filen og bygger JAR-filerne, hvis de ikke findes. -> **Note:** Foretrækker du at bygge alle moduler manuelt før start: +> **Note:** Hvis du foretrækker at bygge alle moduler manuelt inden start: > > **Bash:** > ```bash @@ -282,29 +282,29 @@ cd ..; .\stop-all.ps1 # Alle moduler ## Brug af applikationen -Applikationen tilbyder et webinterface med to chat-implementeringer side om side. +Applikationen tilbyder en webgrænseflade med to chat-implementeringer side om side. Application Home Screen -*Dashboard, der viser både Simple Chat (stateless) og Conversational Chat (stateful) muligheder* +*Dashboard der viser både Simple Chat (stateless) og Conversational Chat (stateful) muligheder* -### Stateless chat (venstre panel) +### Stateless Chat (venstre panel) -Prøv dette først. Spørg "Mit navn er John" og spørg så straks "Hvad er mit navn?" Modellen vil ikke huske, fordi hver besked er uafhængig. Dette demonstrerer det centrale problem med grundlæggende sprogmodel-integration - ingen samtalekontekst. +Prøv dette først. Sig "Mit navn er John" og spørg så straks "Hvad er mit navn?" Modellen vil ikke huske det, fordi hver besked er uafhængig. Dette demonstrerer kernproblemet med basal sprogmodelintegration - ingen kontekst i samtalen. Stateless Chat Demo -*AI husker ikke dit navn fra den forrige besked* +*AI husker ikke dit navn fra den foregående besked* -### Stateful chat (højre panel) +### Stateful Chat (højre panel) -Prøv nu samme sekvens her. Spørg "Mit navn er John" og dernæst "Hvad er mit navn?" Denne gang husker den. Forskellen er MessageWindowChatMemory - den bevarer samtalehistorik og inkluderer den med hver anmodning. Det er sådan produktionssamtale-AI fungerer. +Prøv samme sekvens her. Sig "Mit navn er John" og spørg derefter "Hvad er mit navn?" Denne gang husker den det. Forskellen er MessageWindowChatMemory - den bevarer samtalehistorik og inkluderer den med hver forespørgsel. Sådan fungerer produktionsklar konversations-AI. Stateful Chat Demo *AI husker dit navn fra tidligere i samtalen* -Begge paneler bruger samme GPT-5.2 model. Den eneste forskel er hukommelsen. Det gør det klart, hvad hukommelse bringer til din applikation, og hvorfor det er essentielt til virkelige brugssager. +Begge paneler bruger samme GPT-5.2 model. Den eneste forskel er hukommelse. Det gør det tydeligt, hvad hukommelsen tilfører din applikation, og hvorfor det er essentielt til rigtige brugssituationer. ## Næste skridt @@ -312,11 +312,11 @@ Begge paneler bruger samme GPT-5.2 model. Den eneste forskel er hukommelsen. Det --- -**Navigation:** [← Forrige: Modul 00 - Quick Start](../00-quick-start/README.md) | [Tilbage til hovedmenu](../README.md) | [Næste: Modul 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigation:** [← Tilbage til hoved](../README.md) | [Næste: Modul 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **Ansvarsfraskrivelse**: -Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi stræber efter nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det oprindelige dokument på dets modersmål bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os ikke ansvar for misforståelser eller fejltolkninger, der opstår ved brug af denne oversættelse. +Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. \ No newline at end of file diff --git a/translations/da/02-prompt-engineering/README.md b/translations/da/02-prompt-engineering/README.md index 8b4040ca2..02893550e 100644 --- a/translations/da/02-prompt-engineering/README.md +++ b/translations/da/02-prompt-engineering/README.md @@ -2,84 +2,84 @@ ## Indholdsfortegnelse -- [Video Gennemgang](../../../02-prompt-engineering) -- [Det Du Vil Lære](../../../02-prompt-engineering) -- [Forudsætninger](../../../02-prompt-engineering) -- [Forståelse af Prompt Engineering](../../../02-prompt-engineering) -- [Grundlæggende Prompt Engineering](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Skabeloner](../../../02-prompt-engineering) -- [Avancerede Mønstre](../../../02-prompt-engineering) -- [Kør Applikationen](../../../02-prompt-engineering) -- [Applikationsskærmbilleder](../../../02-prompt-engineering) -- [Udforskning af Mønstrene](../../../02-prompt-engineering) - - [Lav vs Høj Iver](../../../02-prompt-engineering) - - [Opgaveudførelse (Tool Preambles)](../../../02-prompt-engineering) - - [Selvreflekterende Kode](../../../02-prompt-engineering) - - [Struktureret Analyse](../../../02-prompt-engineering) - - [Multi-Turn Chat](../../../02-prompt-engineering) - - [Trin-for-Trin Resonnering](../../../02-prompt-engineering) - - [Begrænset Output](../../../02-prompt-engineering) -- [Hvad Du Virkelig Lærer](../../../02-prompt-engineering) -- [Næste Skridt](../../../02-prompt-engineering) +- [Video Gennemgang](#video-gennemgang) +- [Hvad Du Vil Lære](#hvad-du-vil-lære) +- [Forudsætninger](#forudsætninger) +- [Forståelse af Prompt Engineering](#forståelse-af-prompt-engineering) +- [Grundlæggende om Prompt Engineering](#grundlæggende-om-prompt-engineering) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Skabeloner](#prompt-skabeloner) +- [Avancerede Mønstre](#avancerede-mønstre) +- [Kør Applikationen](#kør-applikationen) +- [Skærmbilleder fra Applikationen](#applikationsskærmbilleder) +- [Udforskning af Mønstrene](#undersøgelse-af-mønstrene) + - [Lav vs Høj Iver](#lav-vs-høj-eagerness) + - [Opgaveudførelse (Værktøjspreambler)](#opgaveudførelse-værktøjsappel) + - [Selvreflekterende Kode](#selvreflekterende-kode) + - [Struktureret Analyse](#struktureret-analyse) + - [Multi-Turn Chat](#multi-turn-chat) + - [Trin-for-Trin Resonnement](#trin-for-trin-ræsonnement) + - [Begrænset Output](#begrænset-output) +- [Hvad Du Virkelig Lærer](#hvad-du-virkelig-lærer) +- [Næste Skridt](#næste-skridt) ## Video Gennemgang -Se denne live-session, der forklarer, hvordan du kommer i gang med dette modul: +Se denne live session, der forklarer, hvordan du kommer i gang med dette modul: Prompt Engineering with LangChain4j - Live Session -## Det Du Vil Lære +## Hvad Du Vil Lære -Følgende diagram giver et overblik over de nøgleemner og færdigheder, du vil udvikle i dette modul — fra promptforfiningsteknikker til den trin-for-trin arbejdsgang, du vil følge. +Følgende diagram giver en oversigt over de nøgleemner og færdigheder, du vil udvikle i dette modul — fra teknikker til forfining af prompts til den trin-for-trin arbejdsproces, du skal følge. What You'll Learn -I de tidligere moduler undersøgte du grundlæggende LangChain4j-interaktioner med GitHub-modeller og så, hvordan hukommelse muliggør konversationel AI med Azure OpenAI. Nu vil vi fokusere på, hvordan du stiller spørgsmål — selve promptene — ved brug af Azure OpenAI's GPT-5.2. Den måde, du strukturerer dine prompts på, påvirker dramatisk kvaliteten af de svar, du får. Vi starter med en gennemgang af de fundamentale prompting-teknikker og går derefter videre til otte avancerede mønstre, der udnytter GPT-5.2's kapaciteter fuldt ud. +I det forrige modul så du, hvordan hukommelse muliggør konverserende AI med Azure OpenAI. Nu fokuserer vi på, hvordan du stiller spørgsmål — selve prompts — ved brug af Azure OpenAI's GPT-5.2. Måden, du strukturerer dine prompts på, har stor betydning for kvaliteten af de svar, du får. Vi starter med en gennemgang af de grundlæggende promptingsteknikker og bevæger os derefter videre til otte avancerede mønstre, der udnytter GPT-5.2's muligheder fuldt ud. -Vi bruger GPT-5.2, fordi den introducerer kontrol over ræsonnement - du kan fortælle modellen, hvor meget tænkning der skal foretages, før den svarer. Dette gør forskellige prompting-strategier mere tydelige og hjælper dig med at forstå, hvornår hver tilgang skal anvendes. Vi vil også drage fordel af Azures færre hastighedsbegrænsninger for GPT-5.2 sammenlignet med GitHub models. +Vi bruger GPT-5.2, fordi den introducerer styring af resonnement - du kan fortælle modellen, hvor meget den skal tænke, før den svarer. Det gør forskellige promptingstrategier mere tydelige og hjælper dig med at forstå, hvornår du skal bruge hvilken tilgang. ## Forudsætninger -- Gennemført Modul 01 (Azure OpenAI ressourcer implementeret) +- Afsluttet Modul 01 (Azure OpenAI-ressourcer deployeret) - `.env` fil i rodmappen med Azure legitimationsoplysninger (oprettet via `azd up` i Modul 01) -> **Note:** Hvis du ikke har gennemført Modul 01, følg først implementeringsinstruktionerne der. +> **Note:** Hvis du ikke har gennemført Modul 01, følg først deployeringsinstruktionerne der. ## Forståelse af Prompt Engineering -I sin kerne er prompt engineering forskellen mellem vage instruktioner og præcise, som sammenligningen nedenfor illustrerer. +I sin kerne er prompt engineering forskellen mellem vage instruktioner og præcise instruktioner, som sammenligningen nedenfor illustrerer. What is Prompt Engineering? -Prompt engineering handler om at designe inputtekst, der konsekvent giver dig de resultater, du har brug for. Det handler ikke kun om at stille spørgsmål - det handler om at strukturere forespørgsler, så modellen forstår præcis, hvad du vil, og hvordan det skal leveres. +Prompt engineering handler om at designe inputtekst, der konsekvent giver dig de resultater, du har brug for. Det handler ikke kun om at stille spørgsmål - det handler om at strukturere anmodninger, så modellen præcist forstår, hvad du vil, og hvordan det skal leveres. -Tænk på det som at give instruktioner til en kollega. "Fix fejlen" er vag. "Fix null-pointer exception i UserService.java linje 45 ved at tilføje en null-tjek" er specifik. Sprogmodeller fungerer på samme måde - specificitet og struktur betyder noget. +Tænk på det som at give instruktioner til en kollega. "Fix fejlen" er vagt. "Ret null pointer exception i UserService.java linje 45 ved at tilføje en nul-tjek" er specifikt. Sprogmodeller fungerer på samme måde - specificitet og struktur er vigtigt. -Diagrammet nedenfor viser, hvordan LangChain4j passer ind i dette billede — ved at forbinde dine promptmønstre til modellen gennem SystemMessage og UserMessage byggesten. +Diagrammet nedenfor viser, hvordan LangChain4j passer ind i dette billede — ved at forbinde dine prompt-mønstre til modellen gennem SystemMessage og UserMessage byggeklodser. How LangChain4j Fits -LangChain4j leverer infrastrukturen — modelforbindelser, hukommelse og meddelelsestyper — mens promptmønstre blot er nøje struktureret tekst, du sender gennem infrastrukturen. De nøglebyggesten er `SystemMessage` (som sætter AI’ens adfærd og rolle) og `UserMessage` (som indeholder din faktiske forespørgsel). +LangChain4j leverer infrastrukturen — modelforbindelser, hukommelse og beskedtyper — mens promptmønstre blot er omhyggeligt struktureret tekst, du sender gennem denne infrastruktur. De vigtigste byggeklodser er `SystemMessage` (som sætter AI'ens adfærd og rolle) og `UserMessage` (som bærer din faktiske anmodning). -## Grundlæggende Prompt Engineering +## Grundlæggende om Prompt Engineering -De fem kerne-teknikker vist nedenfor udgør fundamentet for effektiv prompt engineering. Hver adresserer en anden del af, hvordan du kommunikerer med sprogmodeller. +De fem kerne-teknikker vist nedenfor udgør fundamentet for effektiv prompt engineering. Hver af dem adresserer en forskellig del af, hvordan du kommunikerer med sprogmodeller. Five Prompt Engineering Patterns Overview -Før vi dykker ned i de avancerede mønstre i dette modul, lad os gennemgå fem grundlæggende prompting-teknikker. Disse er byggesten, som enhver promptingeniør bør kende. Hvis du allerede har arbejdet med [Quick Start modulet](../00-quick-start/README.md#2-prompt-patterns), har du set dem i praksis — her er det konceptuelle grundlag bag dem. +Før vi dykker ned i de avancerede mønstre i dette modul, lad os gennemgå fem grundlæggende promptingsteknikker. Det er byggeklodser, som enhver prompt engineer bør kende. ### Zero-Shot Prompting -Den simpleste tilgang: giv modellen en direkte instruktion uden eksempler. Modellen baserer sig udelukkende på sin træning for at forstå og udføre opgaven. Dette fungerer godt for ligetil forespørgsler, hvor den forventede adfærd er åbenlys. +Den simpleste tilgang: giv modellen en direkte instruktion uden eksempler. Modellen stoler fuldstændigt på sin træning for at forstå og udføre opgaven. Dette fungerer godt for direkte anmodninger, hvor forventet adfærd er åbenlys. Zero-Shot Prompting -*Direkte instruktion uden eksempler — modellen tolker opgaven ud fra instruktionen alene* +*Direkte instruktion uden eksempler — modellen udleder opgaven alene ud fra instruktionen* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Svar: "Positiv" ``` -**Hvornår man skal bruge:** Enkle klassifikationer, direkte spørgsmål, oversættelser eller enhver opgave, modellen kan håndtere uden yderligere vejledning. +**Hvornår man skal bruge:** Enkle klassifikationer, direkte spørgsmål, oversættelser eller enhver opgave, som modellen kan håndtere uden yderligere vejledning. ### Few-Shot Prompting -Giv eksempler, der demonstrerer det mønster, du vil have modellen til at følge. Modellen lærer det forventede input-output-format fra dine eksempler og anvender det på nye input. Dette forbedrer dramatisk konsistensen for opgaver, hvor det ønskede format eller adfærd ikke er åbenlys. +Giv eksempler, der demonstrerer det mønster, du vil have modellen til at følge. Modellen lærer det forventede input-output format fra dine eksempler og anvender det på nye inputs. Dette forbedrer markant konsistensen for opgaver, hvor det ønskede format eller adfærd ikke er åbenlyst. Few-Shot Prompting -*Læring fra eksempler — modellen identificerer mønsteret og anvender det på nye input* +*Læring fra eksempler — modellen identificerer mønsteret og anvender det på nye inputs* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Hvornår man skal bruge:** Tilpassede klassifikationer, konsistent formatering, domænespecifikke opgaver eller når zero-shot resultater er inkonsistente. +**Hvornår man skal bruge:** Tilpassede klassifikationer, konsekvent formatering, domænespecifikke opgaver eller når zero-shot resultater er inkonsistente. ### Chain of Thought -Bed modellen om at vise sin ræsonnering trin-for-trin. I stedet for at springe direkte til et svar, nedbryder modellen problemet og arbejder gennem hver del eksplicit. Dette forbedrer nøjagtigheden på matematik, logik og komplekse ræsonnement-opgaver. +Bed modellen om at vise sit resonnement trin-for-trin. I stedet for at hoppe direkte til et svar, bryder modellen problemet ned og arbejder gennem hver del eksplicit. Dette øger nøjagtigheden på matematiske, logiske og flerstegs resoneringsopgaver. Chain of Thought Prompting -*Trinvis ræsonnering — nedbrydning af komplekse problemer i eksplicitte logiske trin* +*Trin-for-trin resonnement — opdeling af komplekse problemer i eksplicitte logiske trin* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Modellen viser: 15 - 8 = 7, derefter 7 + 12 = 19 æbler ``` -**Hvornår man skal bruge:** Matematikopgaver, logikpuslespil, fejlfinding eller enhver opgave, hvor det at vise ræsonnementet forbedrer nøjagtigheden og tilliden. +**Hvornår man skal bruge:** Matematikopgaver, logikpuslespil, fejlfinding eller enhver opgave, hvor visning af resonnementet forbedrer nøjagtighed og tillid. ### Role-Based Prompting -Sæt en persona eller rolle på AI’en, før du stiller dit spørgsmål. Dette giver kontekst, som former tonen, dybden og fokus i svaret. En "softwarearkitekt" giver anderledes rådgivning end en "juniorudvikler" eller en "sikkerhedsauditor". +Opsæt en persona eller rolle for AI'en, før du stiller dit spørgsmål. Dette giver kontekst, som former tone, dybde og fokus i svaret. En "softwarearkitekt" giver andre råd end en "juniorudvikler" eller en "sikkerhedsrevisor". Role-Based Prompting -*Sætter kontekst og persona — det samme spørgsmål får et forskelligt svar afhængigt af den tildelte rolle* +*Opsætning af kontekst og persona — det samme spørgsmål får forskellige svar afhængigt af den tildelte rolle* ```java String prompt = """ @@ -157,11 +157,11 @@ String prompt = """ String response = model.chat(prompt); ``` -**Hvornår man skal bruge:** Code reviews, vejledning, domænespecifik analyse eller når du har brug for svar tilpasset en bestemt ekspertisegrad eller perspektiv. +**Hvornår man skal bruge:** Kodegennemgange, undervisning, domænespecifik analyse eller når du har brug for svar, der er tilpasset et bestemt ekspertiseniveau eller perspektiv. ### Prompt Skabeloner -Lav genanvendelige prompts med variable pladsholdere. I stedet for at skrive en ny prompt hver gang, definer én skabelon og udfyld forskellige værdier. LangChain4j's `PromptTemplate` klasse gør dette nemt med `{{variable}}` syntaks. +Opret genanvendelige prompts med variable pladsholdere. I stedet for at skrive en ny prompt hver gang, definer en skabelon én gang og udfyld forskellige værdier. LangChain4j's `PromptTemplate` klasse gør dette nemt med `{{variable}}` syntaks. Prompt Templates @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Hvornår man skal bruge:** Gentagne forespørgsler med forskellige input, batch-behandling, opbygning af genanvendelige AI-arbejdsgange eller enhver situation, hvor promptstrukturen forbliver den samme, men dataene ændres. +**Hvornår man skal bruge:** Gentagne forespørgsler med forskellige inputs, batch behandling, opbygning af genanvendelige AI-arbejdsprocesser eller enhver situation, hvor promptens struktur forbliver den samme, men dataene ændres. --- -Disse fem grundprincipper giver dig et solidt værktøjssæt til de fleste prompting-opgaver. Resten af dette modul bygger videre på dem med **otte avancerede mønstre**, der udnytter GPT-5.2's kontrol over ræsonnement, selvevaluering og struktureret output. +Disse fem grundlæggende teknikker giver dig et solidt værktøjssæt til de fleste prompting-opgaver. Resten af dette modul bygger videre på dem med **otte avancerede mønstre**, der udnytter GPT-5.2's evne til resonnementstyring, selvevaluering og struktureret output. ## Avancerede Mønstre -Med grundprincipperne dækket, lad os gå over til de otte avancerede mønstre, der gør dette modul unikt. Ikke alle problemer kræver den samme tilgang. Nogle spørgsmål kræver hurtige svar, andre dyb tænkning. Nogle kræver synligt ræsonnement, andre blot resultater. Hvert mønster nedenfor er optimeret til en forskellig situation — og GPT-5.2's ræsonnementskontrol gør forskellene endnu mere tydelige. +Med grundlaget på plads, lad os gå til de otte avancerede mønstre, der gør dette modul unikt. Ikke alle problemer kræver den samme tilgang. Nogle spørgsmål kræver hurtige svar, andre dyb tænkning. Nogle behøver synligt resonnement, andre kun resultater. Hvert mønster nedenfor er optimeret til et forskelligt scenarie — og GPT-5.2's resonnementstyring gør forskellene endnu mere markante. Eight Prompting Patterns -*Oversigt over de otte prompt engineering mønstre og deres brugsscenarier* +*Oversigt over de otte prompt engineering mønstre og deres anvendelsestilfælde* -GPT-5.2 tilføjer dimensionen *ræsonnementskontrol* til disse mønstre. Slideren nedenfor viser, hvordan du kan justere modellens tænkearbejde — fra hurtige, direkte svar til dyb, grundig analyse. +GPT-5.2 tilføjer en ekstra dimension til disse mønstre: *resonnementstyring*. Skyderen nedenfor viser, hvordan du kan justere modellens tænkeindsats — fra hurtige, direkte svar til dyb, grundig analyse. Reasoning Control with GPT-5.2 -*GPT-5.2's ræsonnementskontrol lader dig specificere, hvor meget tænkning modellen skal gøre — fra hurtige, direkte svar til dyb udforskning* +*GPT-5.2's resonnementstyring lader dig specificere, hvor meget modellen skal tænke — fra hurtige direkte svar til dyb udforskning* -**Lav Iver (Hurtigt & Fokuseret)** - Til simple spørgsmål, hvor du ønsker hurtige, direkte svar. Modellen udfører minimal ræsonnering - maks 2 trin. Brug dette til beregninger, opslag eller ligetil spørgsmål. +**Lav Iver (Hurtigt & Fokuseret)** - Til simple spørgsmål, hvor du ønsker hurtige, direkte svar. Modellen foretager minimal resonnement - maksimalt 2 trin. Brug dette til beregninger, opslag eller ligetil spørgsmål. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Udforsk med GitHub Copilot:** Åbn [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) og spørg: -> - "Hvad er forskellen på lav og høj iver i prompting-mønstre?" -> - "Hvordan hjælper XML-tags i prompts med at strukturere AI’ens svar?" -> - "Hvornår skal jeg bruge selvrefleksion fremfor direkte instruktion?" +> - "Hvad er forskellen på lav iver og høj iver prompting mønstre?" +> - "Hvordan hjælper XML-tags i prompts med at strukturere AI'ens svar?" +> - "Hvornår skal jeg bruge selvrefleksion vs direkte instruktion?" -**Høj Iver (Dyb & Grundig)** - Til komplekse problemer, hvor du ønsker dybdegående analyse. Modellen udforsker grundigt og viser detaljeret ræsonnering. Brug dette til systemdesign, arkitekturvalg eller kompleks forskning. +**Høj Iver (Dyb & Grundig)** - Til komplekse problemer, hvor du ønsker grundig analyse. Modellen udforsker grundigt og viser detaljeret resonnement. Brug dette til systemdesign, arkitekturvalg eller kompleks forskning. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Opgaveudførelse (Trin-for-Trin Fremdrift)** - Til multi-trins arbejdsgange. Modellen giver en forudgående plan, fortæller om hvert trin undervejs, og afslutter med en opsummering. Brug dette til migreringer, implementeringer eller enhver fler-trins proces. +**Opgaveudførelse (Trin-for-Trin Fremdrift)** - Til flerstegs arbejdsprocesser. Modellen giver en plan på forhånd, fortæller om hvert trin under arbejdet, og giver en opsummering til sidst. Brug dette til migrationer, implementeringer eller enhver flerstegsprocedure. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Chain-of-Thought prompting beder eksplicit modellen om at vise sin ræsonneringsproces, hvilket forbedrer nøjagtigheden ved komplekse opgaver. Den trin-for-trin nedbrydning hjælper både mennesker og AI med at forstå logikken. +Chain-of-Thought prompting beder eksplicit modellen om at vise sit resonnement, hvilket forbedrer nøjagtigheden for komplekse opgaver. Opdeling trin-for-trin hjælper både mennesker og AI til at forstå logikken. -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Spørg ind til dette mønster: -> - "Hvordan kan jeg tilpasse opgaveudførelsesmønstret til langvarige operationer?" -> - "Hvad er bedste praksis til at strukturere tool preambles i produktionsapplikationer?" -> - "Hvordan kan jeg fange og vise mellemliggende fremdriftsopdateringer i en UI?" +> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Spørg om dette mønster: +> - "Hvordan kan jeg tilpasse opgaveudførelsesmønsteret til langvarige operationer?" +> - "Hvad er bedste praksis for strukturering af værktøjspreambler i produktionsapplikationer?" +> - "Hvordan kan jeg fange og vise mellemstatus-opdateringer i et UI?" -Diagrammet nedenfor illustrerer denne Plan → Udfør → Opsummer arbejdsgang. +Diagrammet nedenfor illustrerer denne Planlæg → Udfør → Opsummer arbejdsproces. Task Execution Pattern -*Plan → Udfør → Opsummer arbejdsgang for fler-trins opgaver* +*Planlæg → Udfør → Opsummer arbejdsproces for flerstegsopgaver* -**Selvreflekterende Kode** - Til generering af produktionsklar kode. Modellen genererer kode, der følger produktionsstandarder med korrekt fejlhåndtering. Brug dette når du bygger nye funktioner eller services. +**Selvreflekterende Kode** - Til generering af produktionsklar kode. Modellen genererer kode efter produktionsstandarder med korrekt fejlhåndtering. Brug dette ved opbygning af nye funktioner eller services. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagrammet nedenfor viser denne iterative forbedrings-cyklus — generer, evaluer, identificer svagheder og forfin indtil koden lever op til produktionsstandarderne. +Diagrammet nedenfor viser denne iterative forbedringscyklus — generer, evaluer, identificer svagheder og forfin indtil koden opfylder produktionsstandarder. Self-Reflection Cycle *Iterativ forbedringscyklus - generer, evaluer, identificer problemer, forbedr, gentag* -**Struktureret Analyse** - Til konsistent evaluering. Modellen gennemgår kode med en fast ramme (korrekthed, praksis, ydeevne, sikkerhed, vedligeholdelsesvenlighed). Brug dette til code reviews eller kvalitetsvurderinger. +**Struktureret Analyse** - Til konsistent evaluering. Modellen gennemgår kode ved hjælp af et fast framework (korrekthed, praksis, ydeevne, sikkerhed, vedligeholdelse). Brug dette til kodegennemgange eller kvalitetsvurderinger. ```java String prompt = """ @@ -355,17 +355,17 @@ String response = chatModel.chat(prompt); ``` > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Spørg om struktureret analyse: -> - "Hvordan kan jeg tilpasse analyse-rammen til forskellige typer kodegennemgange?" -> - "Hvad er den bedste måde at programmere en fortolkning og handling på struktureret output?" -> - "Hvordan sikrer jeg konsistente alvorlighedsniveauer på tværs af forskellige anmeldelsessessioner?" +> - "Hvordan kan jeg tilpasse analyseframeworket til forskellige typer kodegennemgange?" +> - "Hvad er den bedste måde at parse og handle på struktureret output programmatisk?" +> - "Hvordan sikrer jeg konsistente sværhedsgrader på tværs af forskellige gennemgangssessioner?" -Følgende diagram viser, hvordan denne strukturerede ramme organiserer en code review i konsistente kategorier med alvorlighedsniveauer. +Følgende diagram viser, hvordan dette strukturerede framework organiserer en kodegennemgang i konsistente kategorier med sværhedsgrader. Structured Analysis Pattern -*Ramme for konsistente code reviews med alvorlighedsniveauer* +*Framework til konsistente kodegennemgange med sværhedsgrader* -**Multi-Turn Chat** - Til samtaler, der har brug for kontekst. Modellen husker tidligere beskeder og bygger videre på dem. Brug dette til interaktive hjælpesessioner eller komplekse spørgsmål og svar. +**Multi-Turn Chat** - Til samtaler, der har brug for kontekst. Modellen husker tidligere beskeder og bygger videre på dem. Brug dette til interaktive hjælpesessioner eller komplekse Q&A. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Diagrammet nedenfor visualiserer, hvordan samtalens kontekst akkumuleres for hvert svar og hvordan det relaterer til modellens token-grænse. +Diagrammet nedenfor visualiserer, hvordan samtalekontekst akkumulere med hvert spørgsmål og hvordan det relaterer til modellens token-limit. Context Memory -*Hvordan samtalens kontekst ophobes gennem flere runder indtil token-grænsen nås* -**Trin-for-trin ræsonnering** - Til problemer, der kræver synlig logik. Modellen viser eksplicit ræsonnering for hvert trin. Brug dette til matematiske problemer, logikpuslespil eller når du skal forstå tankeprocessen. +*Hvordan samtalekontekst akkumuleres over flere ture indtil token-grænsen nås* + +**Trin-for-Trin Resonnement** - Til problemer, der kræver synlig logik. Modellen viser eksplicit resonnement for hvert trin. Brug dette til matematikopgaver, logikpuslespil eller når du har brug for at forstå tankeprocessen. ```java String prompt = """ @@ -401,10 +402,9 @@ String response = chatModel.chat(prompt); Diagrammet nedenfor illustrerer, hvordan modellen opdeler problemer i eksplicitte, nummererede logiske trin. Step-by-Step Pattern +*At opdele problemer i eksplicitte logiske trin* -*Nedbrydning af problemer i eksplicitte logiske trin* - -**Begrænset output** - Til svar med specifikke formatkrav. Modellen følger streng format- og længderegler. Brug dette til sammendrag eller når du har brug for præcist outputformat. +**Begrænset output** - Til svar med specifikke formatkrav. Modellen følger strikt format- og længdekrav. Brug dette til opsummeringer eller når du har brug for præcis outputstruktur. ```java String prompt = """ @@ -420,9 +420,9 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Følgende diagram viser, hvordan begrænsninger guider modellen til at producere output, der strikt overholder dine format- og længdekrav. +Følgende diagram viser, hvordan begrænsninger guider modellen til at producere output, der strengt overholder dine format- og længdekrav. -Constrained Output Pattern +Begrænset outputmønster *Håndhævelse af specifikke format-, længde- og strukturkrav* @@ -430,7 +430,7 @@ Følgende diagram viser, hvordan begrænsninger guider modellen til at producere **Bekræft udrulning:** -Sørg for, at `.env`-filen findes i rodmappen med Azure-legitimationsoplysninger (oprettet under Modul 01). Kør dette fra modulets mappe (`02-prompt-engineering/`): +Sørg for, at `.env`-filen findes i rodkataloget med Azure-legitimationsoplysninger (oprettet under Modul 01). Kør dette fra modulets bibliotek (`02-prompt-engineering/`): **Bash:** ```bash @@ -444,37 +444,37 @@ Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Start applikationen:** -> **Bemærk:** Hvis du allerede har startet alle applikationer med `./start-all.sh` fra rodmappen (som beskrevet i Modul 01), kører dette modul allerede på port 8083. Du kan springe start-kommandoerne nedenfor over og gå direkte til http://localhost:8083. +> **Bemærk:** Hvis du allerede har startet alle applikationer med `./start-all.sh` fra rodkataloget (som beskrevet i Modul 01), kører dette modul allerede på port 8083. Du kan springe startkommandoerne herunder over og gå direkte til http://localhost:8083. -**Mulighed 1: Brug Spring Boot Dashboard (anbefalet til VS Code brugere)** +**Mulighed 1: Brug af Spring Boot Dashboard (anbefalet for VS Code-brugere)** -Dev containeren inkluderer Spring Boot Dashboard udvidelsen, som giver et visuelt interface til at administrere alle Spring Boot applikationer. Du finder den i Aktivitetslinjen til venstre i VS Code (se efter Spring Boot ikonet). +Dev-containeren inkluderer Spring Boot Dashboard-udvidelsen, som giver en visuel grænseflade til at administrere alle Spring Boot-applikationer. Du finder den i aktivitetslinjen til venstre i VS Code (se efter Spring Boot-ikonet). Fra Spring Boot Dashboard kan du: -- Se alle tilgængelige Spring Boot applikationer i workspace -- Starte/stoppe applikationer med ét klik +- Se alle tilgængelige Spring Boot-applikationer i arbejdsmiljøet +- Starte/stoppe applikationer med et enkelt klik - Se applikationslogfiler i realtid -- Overvåge applikationsstatus +- Overvåge applikationens status -Klik blot på afspilningsknappen ud for "prompt-engineering" for at starte dette modul, eller start alle moduler på én gang. +Klik blot på afspilningsknappen ved siden af "prompt-engineering" for at starte dette modul, eller start alle moduler på én gang. Spring Boot Dashboard *Spring Boot Dashboard i VS Code — start, stop og overvåg alle moduler fra ét sted* -**Mulighed 2: Brug shell scripts** +**Mulighed 2: Brug af shell-scripts** Start alle webapplikationer (moduler 01-04): **Bash:** ```bash -cd .. # Fra rodkataloget +cd .. # Fra rodmappen ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Fra rodmappen +cd .. # Fra roddirectory .\start-all.ps1 ``` @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Begge scripts indlæser automatisk miljøvariabler fra rodens `.env`-fil og bygger JAR-filerne, hvis de ikke findes. +Begge scripts indlæser automatisk miljøvariabler fra rodkatalogets `.env`-fil og bygger JAR-filerne, hvis de ikke findes. -> **Bemærk:** Hvis du foretrækker at bygge alle moduler manuelt før start: +> **Bemærk:** Hvis du foretrækker at bygge alle moduler manuelt, før du starter: > > **Bash:** > ```bash @@ -528,69 +528,69 @@ cd ..; .\stop-all.ps1 # Alle moduler ## Applikationsskærmbilleder -Her er hovedgrænsefladen for prompt engineering modulet, hvor du kan eksperimentere med alle otte mønstre side om side. +Her er hovedgrænsefladen for prompt engineering-modulet, hvor du kan eksperimentere med alle otte mønstre side om side. -Dashboard Home +Dashboard Startside -*Hoveddashboard, der viser alle 8 prompt engineering mønstre med deres karakteristika og anvendelsestilfælde* +*Hoveddashboard med alle 8 prompt engineering-mønstre med deres karakteristika og anvendelsestilfælde* -## Udforskning af mønstrene +## Undersøgelse af mønstrene -Webgrænsefladen lader dig eksperimentere med forskellige prompting strategier. Hvert mønster løser forskellige problemer – prøv dem for at se, hvornår hver tilgang fungerer bedst. +Webgrænsefladen lader dig eksperimentere med forskellige prompt-strategier. Hvert mønster løser forskellige problemer - prøv dem for at se, hvornår hver tilgang fungerer bedst. -> **Bemærk: Streaming vs Ikke-streaming** — Hver mønsterside tilbyder to knapper: **🔴 Stream Response (Live)** og en **Ikke-streaming** mulighed. Streaming bruger Server-Sent Events (SSE) til at vise tokens i realtid, mens modellen genererer dem, så du ser fremdrift med det samme. Ikke-streaming venter på hele svaret, før det vises. For prompts, der udløser dyb ræsonnering (f.eks. High Eagerness, Self-Reflecting Code), kan ikke-streaming kald tage meget lang tid – nogle gange flere minutter – uden synlig feedback. **Brug streaming når du eksperimenterer med komplekse prompts**, så du kan se modellen arbejde og undgå indtryk af timeout. +> **Bemærk: Streaming vs Ikke-streaming** — Hver mønsterside tilbyder to knapper: **🔴 Stream Respons (Live)** og en **Ikke-streaming** mulighed. Streaming bruger Server-Sent Events (SSE) til at vise tokens i realtid, mens modellen genererer dem, så du straks kan følge fremskridtet. Ikke-streaming venter på hele svaret, før det vises. For prompt, der udløser dyb refleksion (fx High Eagerness, Self-Reflecting Code), kan ikke-streaming kald tage meget lang tid – nogle gange minutter – uden synlig respons. **Brug streaming ved eksperimenter med komplekse prompts** for at se modellen arbejde og undgå indtryk af timeout. > -> **Bemærk: Browserkrav** — Streaming-funktionen bruger Fetch Streams API (`response.body.getReader()`), som kræver en fuld browser (Chrome, Edge, Firefox, Safari). Det virker **ikke** i VS Codes indbyggede Simple Browser, da dens webview ikke understøtter ReadableStream API’en. Hvis du bruger Simple Browser, fungerer ikke-streaming knapperne stadig normalt — kun streaming knapperne påvirkes. Åbn `http://localhost:8083` i en ekstern browser for fuld oplevelse. +> **Bemærk: Browserkrav** — Streaming-funktionen bruger Fetch Streams API (`response.body.getReader()`), som kræver en komplet browser (Chrome, Edge, Firefox, Safari). Det virker **ikke** i VS Codes indbyggede Simple Browser, da dens webview ikke understøtter ReadableStream API. Ved brug af Simple Browser fungerer ikke-streaming knapperne normalt – kun streaming-knapperne påvirkes. Åbn `http://localhost:8083` i en ekstern browser for fuld funktionalitet. -### Lav vs Høj entusiasme +### Lav vs Høj Eagerness -Stil et simpelt spørgsmål som "Hvad er 15% af 200?" med Lav entusiasme. Du får et øjeblikkeligt, direkte svar. Stil nu noget komplekst som "Design en caching strategi for en højt trafikeret API" med Høj entusiasme. Klik **🔴 Stream Response (Live)** og se modellens detaljerede ræsonnering komme frem token for token. Samme model, samme spørgsmål — men prompten fortæller hvor meget tænkning, der skal til. +Stil et simpelt spørgsmål som "Hvad er 15% af 200?" med Lav Eagerness. Du får et hurtigt, direkte svar. Stil nu noget komplekst som "Design en cachingstrategi for et API med højt trafikomfang" med Høj Eagerness. Klik på **🔴 Stream Respons (Live)** og følg modellens detaljerede ræsonnement token-for-token. Samme model, samme spørgestruktur – men prompten fortæller, hvor meget tænkning der skal til. -### Opgaveudførelse (Tool Preambles) +### Opgaveudførelse (Værktøjsappel) -Workflow med flere trin profiterer af forudgående planlægning og statusfortælling. Modellen skitserer hvad den vil gøre, fortæller om hvert trin og opsummerer så resultater. +Workflow med flere trin drager fordel af forudgående planlægning og fortløbende fortælling. Modellen skitserer hvad den vil gøre, fortæller om hvert trin og opsummerer resultater. ### Selvreflekterende kode -Prøv "Lav en email valideringstjeneste". I stedet for bare at generere kode og stoppe, genererer modellen, evaluerer ift. kvalitetskriterier, identificerer svagheder og forbedrer. Du ser iterationer, indtil koden opfylder produktionsstandarder. +Prøv "Lav en e-mail valideringstjeneste". I stedet for blot at generere kode og stoppe, genererer modellen, vurderer den i forhold til kvalitetskriterier, identificerer svagheder og forbedrer den. Du ser, hvordan den itererer, indtil koden opfylder produktionsstandarder. ### Struktureret analyse -Kodegennemgange kræver konsekvente evalueringsrammer. Modellen analyserer kode med faste kategorier (korrekthed, praksis, ydeevne, sikkerhed) med alvorlighedsniveauer. +Kodegennemgang kræver konsistente vurderingsrammer. Modellen analyserer kode efter faste kategorier (korrekthed, praksis, ydelse, sikkerhed) med alvorlighedsniveauer. -### Multi-turn chat +### Multi-Turn Chat -Spørg "Hvad er Spring Boot?" og følg straks op med "Vis mig et eksempel". Modellen husker dit første spørgsmål og giver et Spring Boot eksempel specifikt til dig. Uden hukommelse ville det andet spørgsmål være for vagt. +Spørg "Hvad er Spring Boot?" og følg straks op med "Vis mig et eksempel". Modellen husker dit første spørgsmål og giver et specifikt Spring Boot-eksempel. Uden hukommelse ville det andet spørgsmål være for åbent. -### Trin-for-trin ræsonnering +### Trin-for-trin ræsonnement -Vælg et matematisk problem og prøv det med både Trin-for-trin ræsonnering og Lav entusiasme. Lav entusiasme giver bare svaret – hurtigt men uigennemsigtigt. Trin for trin viser hver udregning og beslutning. +Vælg et matematikproblem og prøv det med både Trin-for-trin ræsonnement og Lav Eagerness. Lav eagerness giver kun svaret - hurtigt, men uigennemsigtigt. Trin-for-trin viser hver beregning og beslutning. ### Begrænset output -Når du har brug for specifikke formater eller ordantal, sikrer dette mønster streng overholdelse. Prøv at generere et sammendrag med præcis 100 ord i punktopstilling. +Når du har behov for specifikke formater eller ordantal, håndhæver dette mønster streng overholdelse. Prøv at generere en opsummering med præcis 100 ord i punktform. ## Hvad du virkelig lærer -**Ræsonneringsindsats ændrer alt** +**Ræsonnementets indsats ændrer alt** -GPT-5.2 lader dig styre den beregningsmæssige indsats via dine prompts. Lav indsats betyder hurtige svar med minimal udforskning. Høj indsats betyder, at modellen tager sig tid til at tænke grundigt. Du lærer at matche indsatsen med opgavens kompleksitet – spild ikke tid på simple spørgsmål, men skynd dig ikke også komplekse beslutninger. +GPT-5.2 lader dig styre den beregningsmæssige indsats via dine prompts. Lav indsats betyder hurtige svar med minimal udforskning. Høj indsats betyder, at modellen tager tid til dyb refleksion. Du lærer at matche indsats til opgavens kompleksitet – spild ikke tid på simple spørgsmål, men skynd dig heller ikke med komplekse beslutninger. -**Struktur guider adfærd** +**Struktur styrer adfærd** -Bemærk XML-tags i promptene? De er ikke dekorative. Modeller følger strukturerede instruktioner mere pålideligt end frit formuleret tekst. Når du har brug for multi-trins processer eller kompleks logik, hjælper struktur modellen med at holde styr på, hvor den er, og hvad der kommer næste. Diagrammet nedenfor opdeler en veldesignet prompt og viser hvordan tags som ``, ``, ``, ``, og `` organiserer dine instruktioner i klare sektioner. +Læg mærke til XML-tags i promptene? De er ikke bare pynt. Modeller følger strukturerede instruktioner mere pålideligt end frit tekstinput. Når du har brug for flertrinsprocesser eller kompleks logik, hjælper strukturen modellen med at holde styr på hvor den er og hvad der kommer næste. Diagrammet nedenfor nedbryder en veldesignet prompt, der viser, hvordan tags som ``, ``, ``, ``, og `` organiserer dine instruktioner i klare sektioner. -Prompt Structure +Promptstruktur *Anatomi af en veldesignet prompt med klare sektioner og XML-lignende organisering* **Kvalitet gennem selvevaluering** -De selvreflekterende mønstre virker ved at gøre kvalitetskriterier eksplicitte. I stedet for at håbe på, at modellen "gør det rigtigt", fortæller du præcis hvad "rigtigt" betyder: korrekt logik, fejlhåndtering, ydeevne, sikkerhed. Modellen kan så evaluere sit eget output og forbedre det. Det gør kodegenerering til en proces i stedet for lotteri. +De selvreflekterende mønstre fungerer ved at gøre kvalitetskriterier eksplicitte. I stedet for at håbe på, at modellen "gør det rigtigt", fortæller du den præcist, hvad "rigtigt" betyder: korrekt logik, fejlbehandling, ydelse, sikkerhed. Modellen kan derefter evaluere sit eget output og forbedre det. Det gør kodegenerering til en proces fremfor et lotteri. **Kontekst er begrænset** -Multi-turn samtaler virker ved at inkludere meddelelseshistorik ved hvert kald. Men der er en grænse – hver model har et maksimum token antal. Når samtaler bliver længere, skal du bruge strategier for at holde relevant kontekst uden at ramme loftet. Dette modul viser hvordan hukommelse fungerer; senere lærer du hvornår du skal opsummere, glemme og hente. +Multi-turn samtaler fungerer ved at inkludere beskedhistorik i hver anmodning. Men der er en grænse – hver model har et maksimum antal tokens. Efterhånden som samtaler vokser, skal du bruge strategier til at bevare relevant kontekst uden at ramme loftet. Dette modul viser dig, hvordan hukommelse virker; senere lærer du, hvornår du skal opsummere, glemme og hente. ## Næste skridt @@ -598,11 +598,11 @@ Multi-turn samtaler virker ved at inkludere meddelelseshistorik ved hvert kald. --- -**Navigation:** [← Forrige: Modul 01 - Introduktion](../01-introduction/README.md) | [Tilbage til hovedmenu](../README.md) | [Næste: Modul 03 - RAG →](../03-rag/README.md) +**Navigation:** [← Forrige: Modul 01 - Introduktion](../01-introduction/README.md) | [Tilbage til hoved](../README.md) | [Næste: Modul 03 - RAG →](../03-rag/README.md) --- **Ansvarsfraskrivelse**: -Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi stræber efter nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det oprindelige dokument på dets modersmål bør anses for at være den autoritative kilde. For vigtig information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for eventuelle misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. +Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. \ No newline at end of file diff --git a/translations/da/03-rag/README.md b/translations/da/03-rag/README.md index c3b24eba7..850c7ef2b 100644 --- a/translations/da/03-rag/README.md +++ b/translations/da/03-rag/README.md @@ -2,143 +2,143 @@ ## Indholdsfortegnelse -- [Video-gennemgang](../../../03-rag) -- [Hvad du vil lære](../../../03-rag) -- [Forudsætninger](../../../03-rag) -- [Forstå RAG](../../../03-rag) - - [Hvilken RAG-tilgang bruger denne tutorial?](../../../03-rag) -- [Hvordan det fungerer](../../../03-rag) - - [Dokumentbehandling](../../../03-rag) - - [Oprettelse af embeddings](../../../03-rag) - - [Semantisk søgning](../../../03-rag) - - [Svar-generering](../../../03-rag) -- [Kør applikationen](../../../03-rag) -- [Brug applikationen](../../../03-rag) - - [Upload et dokument](../../../03-rag) - - [Stil spørgsmål](../../../03-rag) - - [Tjek kildehenvisninger](../../../03-rag) - - [Eksperimentér med spørgsmål](../../../03-rag) -- [Nøglebegreber](../../../03-rag) - - [Chunking-strategi](../../../03-rag) - - [Lighedsscores](../../../03-rag) - - [I hukommelseslagring](../../../03-rag) - - [Håndtering af kontekstvindue](../../../03-rag) -- [Hvornår RAG er vigtigt](../../../03-rag) -- [Næste skridt](../../../03-rag) - -## Video-gennemgang - -Se denne live-session, der forklarer, hvordan du kommer i gang med dette modul: +- [Video Gennemgang](#video-gennemgang) +- [Det Vil Du Lære](#det-vil-du-lære) +- [Forudsætninger](#forudsætninger) +- [Forståelse af RAG](#forståelse-af-rag) + - [Hvilken RAG-Tilgang Bruger Denne Tutorial?](#hvilken-rag-tilgang-bruger-denne-tutorial) +- [Hvordan Det Virker](#hvordan-det-virker) + - [Dokumentbehandling](#dokumentbehandling) + - [Oprettelse af Embeddings](#oprettelse-af-embeddings) + - [Semantisk Søgning](#semantisk-søgning) + - [Svar Generering](#svar-generering) +- [Kør Applikationen](#kør-applikationen) +- [Brug af Applikationen](#brug-af-applikationen) + - [Upload et Dokument](#upload-et-dokument) + - [Stil Spørgsmål](#stil-spørgsmål) + - [Tjek Kildehenvisninger](#tjek-kildehenvisninger) + - [Eksperimenter med Spørgsmål](#eksperimenter-med-spørgsmål) +- [Nøglebegreber](#nøglebegreber) + - [Chunking Strategi](#opdelingsstrategi) + - [Lighedsscorer](#lighedsscores) + - [In-Memory Lagring](#in-memory-lagring) + - [Styring af Kontekstvindue](#håndtering-af-kontekstvindue) +- [Hvornår RAG Er Vigtigt](#når-rag-betyr-noget) +- [Næste Skridt](#næste-skridt) + +## Video Gennemgang + +Se denne live session, der forklarer, hvordan du kommer i gang med dette modul: RAG with LangChain4j - Live Session -## Hvad du vil lære +## Det Vil Du Lære -I de tidligere moduler lærte du, hvordan du kan have samtaler med AI og strukturere dine prompts effektivt. Men der er en grundlæggende begrænsning: sprogmodeller ved kun, hvad de lærte under træning. De kan ikke svare på spørgsmål om din virksomheds politikker, din projektdokumentation eller anden information, de ikke blev trænet på. +I de tidligere moduler lærte du, hvordan du fører samtaler med AI og strukturerer dine prompts effektivt. Men der er en grundlæggende begrænsning: sprogmodeller ved kun, det de lærte under træningen. De kan ikke besvare spørgsmål om din virksomheds politikker, din projektdokumentation eller information, de ikke er blevet trænet på. -RAG (Retrieval-Augmented Generation) løser dette problem. I stedet for at forsøge at lære modellen din information (hvilket er dyrt og upraktisk), giver du den mulighed for at søge igennem dine dokumenter. Når nogen stiller et spørgsmål, finder systemet relevant information og inkluderer det i prompten. Modellen svarer derefter baseret på den hentede kontekst. +RAG (Retrieval-Augmented Generation) løser dette problem. I stedet for at prøve at lære modellen dine informationer (hvilket er dyrt og upraktisk), giver du den mulighed for at søge i dine dokumenter. Når nogen stiller et spørgsmål, finder systemet relevant information og inkluderer den i prompten. Modellen svarer så baseret på den hentede kontekst. -Tænk på RAG som at give modellen et referencebibliotek. Når du stiller et spørgsmål, gør systemet følgende: +Tænk på RAG som at give modellen et referencelager. Når du stiller et spørgsmål, gør systemet: 1. **Brugerforespørgsel** - Du stiller et spørgsmål -2. **Embedding** - Konverterer dit spørgsmål til en vektor -3. **Vektorsøgning** - Finder lignende dokument-bidder -4. **Kontekstsammensætning** - Tilføjer relevante bidder til prompten -5. **Svar** - LLM genererer et svar baseret på konteksten +2. **Embedding** - Omformer dit spørgsmål til en vektor +3. **Vektorsøgning** - Finder lignende dokument-chunks +4. **Kontekstsammensætning** - Tilføjer relevante chunks til prompten +5. **Respons** - LLM genererer svar baseret på konteksten Dette forankrer modellens svar i dine faktiske data i stedet for at stole på dens træningsviden eller finde på svar. ## Forudsætninger -- Færdiggjort [Modul 00 - Quick Start](../00-quick-start/README.md) (til det Easy RAG-eksempel, der refereres til senere i dette modul) -- Færdiggjort [Modul 01 - Introduktion](../01-introduction/README.md) (Azure OpenAI-ressourcer implementeret, inklusiv `text-embedding-3-small` embedding-modellen) -- `.env`-fil i rodmappen med Azure-legitimationsoplysninger (oprettet af `azd up` i Modul 01) +- Gennemført [Modul 01 - Introduktion](../01-introduction/README.md) (Azure OpenAI-ressourcer deployeret, inklusive `text-embedding-3-small` embedding-modellen) +- `.env` fil i rodmappen med Azure legitimationsoplysninger (oprettet via `azd up` i Modul 01) -> **Bemærk:** Hvis du ikke har gennemført Modul 01, følg implementeringsinstruktionerne der først. Kommandoen `azd up` implementerer både GPT chatmodellen og embedding-modellen, der bruges i dette modul. +> **Note:** Hvis du ikke har gennemført Modul 01, følg først deploymentsinstruktionerne der. `azd up` kommandoen deployerer både GPT chatmodellen og embeddingmodellen, der bruges i dette modul. -## Forstå RAG +## Forståelse af RAG -Diagrammet nedenfor illustrerer kernetanken: i stedet for kun at stole på modellens træningsdata, giver RAG den et referencebibliotek af dine dokumenter at konsultere, før den genererer hvert svar. +Diagrammet nedenfor illustrerer kernekonceptet: i stedet for kun at stole på modellens træningsdata, giver RAG den et referencelager af dine dokumenter, som den kan konsultere, før hvert svar genereres. -What is RAG +Hvad er RAG -*Dette diagram viser forskellen mellem en standard LLM (der gætter ud fra træningsdata) og en RAG-forbedret LLM (som først konsulterer dine dokumenter).* +*Dette diagram viser forskellen mellem en standard LLM (som gætter ud fra træningsdata) og en RAG-forstærket LLM (som først konsulterer dine dokumenter).* -Sådan hænger delene sammen fra ende til anden. En brugers spørgsmål gennemløber fire trin — embedding, vektorsøgning, kontekstsammensætning og svar-generering — hvor hver bygger på den forrige: +Sådan hænger delene sammen fra ende til anden. En brugers spørgsmål går gennem fire stadier — embedding, vektorsøgning, kontekstsammensætning og svar generering — hver bygget ovenpå det foregående: -RAG Architecture +RAG Arkitektur -*Dette diagram viser RAG-pipelinen fra ende til anden — en brugerforespørgsel går gennem embedding, vektorsøgning, kontekstsammensætning og svar-generering.* +*Dette diagram viser RAG pipeline fra ende til ende — en brugerforespørgsel går gennem embedding, vektorsøgning, kontekstsammensætning og svar generering.* -Resten af dette modul gennemgår hvert trin i detaljer med kode, du kan køre og ændre. +Resten af dette modul gennemgår hvert trin i detaljer, med kode du kan køre og ændre. -### Hvilken RAG-tilgang bruger denne tutorial? +### Hvilken RAG-Tilgang Bruger Denne Tutorial? -LangChain4j tilbyder tre måder at implementere RAG på, hver med et forskelligt abstraktionsniveau. Diagrammet nedenfor viser dem side om side: +LangChain4j tilbyder tre måder at implementere RAG på, hver med et forskelligt abstraktionsniveau. Diagrammet nedenfor sammenligner dem side om side: -Three RAG Approaches in LangChain4j +Tre RAG Tilgange i LangChain4j -*Dette diagram sammenligner de tre LangChain4j RAG-tilgange — Easy, Native og Advanced — med deres nøglekomponenter og hvornår hver skal bruges.* +*Dette diagram sammenligner de tre LangChain4j RAG-tilgange — Easy, Native og Advanced — og viser deres nøglekomponenter og hvornår de skal bruges.* -| Tilgang | Hvad den gør | Afvejning | +| Tilgang | Hvad Den Gør | Afvejning | |---|---|---| -| **Easy RAG** | Kobler det hele automatisk via `AiServices` og `ContentRetriever`. Du annoterer et interface, tilknytter en retriever, og LangChain4j håndterer embedding, søgning og prompt-sammensætning bag kulisserne. | Minimal kode, men du ser ikke hvad der sker i hvert trin. | +| **Easy RAG** | Kobler alt automatisk sammen gennem `AiServices` og `ContentRetriever`. Du annoterer et interface, tilknytter en retriever, og LangChain4j håndterer embedding, søgning og prompt-sammensætning bag scenen. | Minimal kode, men du ser ikke hvad der sker i hvert trin. | | **Native RAG** | Du kalder embedding-modellen, søger i butikken, bygger prompten og genererer svaret selv — ét eksplicit trin ad gangen. | Mere kode, men hvert trin er synligt og kan ændres. | -| **Advanced RAG** | Bruger `RetrievalAugmentor`-rammeværket med udskiftelige forespørgsels-transformere, routere, re-rankere og indholdsindsprøjtere til produktionsklare pipelines. | Maksimal fleksibilitet, men betydeligt mere kompleksitet. | +| **Advanced RAG** | Bruger `RetrievalAugmentor`-framework med plug-in query-transformers, routers, re-rankers og content injectors for produktionsklare pipelines. | Maksimal fleksibilitet men også betydeligt mere kompleksitet. | -**Denne tutorial bruger Native-tilgangen.** Hvert trin i RAG-pipelinen — embedding af forespørgslen, søgning i vektor-butikken, sammensætning af kontekst og generering af svar — er skrevet eksplicit i [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Det er med vilje: som læringsressource er det vigtigere, at du ser og forstår hvert trin, end at koden er minimeret. Når du er fortrolig med, hvordan brikkerne passer sammen, kan du gå videre til Easy RAG for hurtige prototyper eller Advanced RAG til produktionssystemer. +**Denne tutorial bruger Native-tilgangen.** Hvert trin i RAG-pipelinen — embed forespørgslen, søg i vektor-lageret, saml konteksten, og generer svaret — er eksplicit skrevet i [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Det er bevidst: som læringsressource er det vigtigere, at du ser og forstår hvert trin fremfor minimal kode. Når du er komfortabel med hvordan delene passer sammen, kan du gå videre til Easy RAG for hurtige prototyper eller Advanced RAG til produktionssystemer. -> **💡 Har du allerede set Easy RAG i aktion?** [Quick Start-modulet](../00-quick-start/README.md) indeholder et eksempel med Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), der bruger Easy RAG-tilgangen — LangChain4j håndterer embedding, søgning og prompt-sammensætning automatisk. Dette modul tager næste skridt ved at åbne op for den pipeline, så du kan se og kontrollere hvert trin selv. +> **💡 Nysgerrig på Easy RAG?** LangChain4j tilbyder også en *Easy RAG* tilgang, hvor `AiServices` og en `ContentRetriever` automatisk håndterer embedding, søgning, og prompt-sammensætning. Dette modul følger den mere eksplicitte vej — bryder pipelinen op, så du kan se og styre hvert trin selv. -Diagrammet nedenfor viser Easy RAG-pipelinen fra det Quick Start-eksempel. Bemærk, hvordan `AiServices` og `EmbeddingStoreContentRetriever` skjuler al kompleksitet — du indlæser et dokument, tilknytter en retriever og får svar. Native-tilgangen i dette modul åbner hvert af disse skjulte trin: +Diagrammet nedenfor viser Easy RAG pipelinen. Bemærk hvordan `AiServices` og `EmbeddingStoreContentRetriever` skjuler al kompleksitet — du loader et dokument, tilknytter en retriever og får svar. Native-tilgangen i dette modul åbner hvert skjult trin: Easy RAG Pipeline - LangChain4j -*Dette diagram viser Easy RAG-pipelinen fra `SimpleReaderDemo.java`. Sammenlign dette med Native-tilgangen, der bruges i dette modul: Easy RAG skjuler embedding, retrieval og prompt-sammensætning bag `AiServices` og `ContentRetriever` — du indlæser et dokument, tilknytter en retriever og får svar. Native-tilgangen i dette modul åbner den pipeline, så du selv kalder hvert trin (embed, søg, saml kontekst, generer), hvilket giver dig fuld synlighed og kontrol.* +*Dette diagram viser Easy RAG pipelinen. Sammenlign med Native-tilgangen i dette modul: Easy RAG skjuler embedding, søgning og prompt-sammensætning bag `AiServices` og `ContentRetriever` — du loader et dokument, tilknytter en retriever og får svar. Native-tilgangen bryder denne pipeline op, så du selv kalder hvert trin (embed, søg, saml kontekst, generer), hvilket giver fuld synlighed og kontrol.* -## Hvordan det fungerer +## Hvordan Det Virker -RAG-pipelinen i dette modul opdeles i fire trin, som kører i rækkefølge hver gang en bruger stiller et spørgsmål. Først bliver et uploadet dokument **parset og opdelt i bidder** i håndterbare stykker. Disse bidder konverteres derefter til **vektor-embeddings** og gemmes, så de kan sammenlignes matematisk. Når en forespørgsel kommer, udfører systemet en **semantisk søgning** for at finde de mest relevante bidder og sender dem endelig som kontekst til LLM for **svar-generering**. Sektionerne nedenfor gennemgår hvert trin med den faktiske kode og diagrammer. Lad os se på det første trin. +RAG-pipelinen i dette modul opdeles i fire stadier, der kører i rækkefølge hver gang en bruger stiller et spørgsmål. Først bliver et uploadet dokument **parset og opdelt i chunks** i håndterbare stykker. Disse chunks konverteres derefter til **vektor-embeddings** og lagres, så de kan sammenlignes matematisk. Når en forespørgsel kommer, udfører systemet en **semantisk søgning** for at finde de mest relevante chunks, og til sidst sendes de som kontekst til LLM’en for **svar generering**. Afsnittene nedenfor gennemgår hvert trin med kode og diagrammer. Lad os se på det første trin. ### Dokumentbehandling [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Når du uploader et dokument, parser systemet det (PDF eller almindelig tekst), tilknytter metadata såsom filnavn og bryder det så op i bidder — mindre stykker, der passer komfortabelt i modellens kontekstvindue. Disse bidder overlapper lidt, så du ikke mister kontekst ved grænserne. +Når du uploader et dokument, parser systemet det (PDF eller tekst), vedhæfter metadata som filnavn, og deler det derefter op i chunks — mindre stykker der passer komfortabelt i modellens kontekstvindue. Disse chunks overlapper let, så du ikke mister kontekst ved grænserne. ```java -// Analyser den uploadede fil og pak den ind i et LangChain4j-dokument +// Analyser den uploadede fil og indpak den i et LangChain4j-dokument Document document = Document.from(content, metadata); -// Del op i 300-token segmenter med 30-token overlap +// Del op i 300-token stykker med 30-token overlapning DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -Diagrammet nedenfor viser, hvordan dette fungerer visuelt. Bemærk hvordan hver bid deler nogle tokens med sine naboer — 30-token overlap sikrer, at ingen vigtig kontekst falder mellem sprækkerne: -Document Chunking -*Dette diagram viser et dokument, der deles op i 300-token bidder med 30-token overlap, hvilket bevarer kontekst ved bid-grænser.* +Diagrammet nedenfor viser, hvordan dette fungerer visuelt. Bemærk hvordan hver chunk deler nogle tokens med sine naboer — det 30-token overlap sikrer, at vigtig kontekst ikke falder mellem sprækkerne: + +Dokument Chunking + +*Dette diagram viser et dokument opdelt i 300-token chunks med 30-token overlap, som bevarer konteksten ved chunk-grænser.* > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) og spørg: -> - "Hvordan splitter LangChain4j dokumenter i bidder og hvorfor er overlap vigtigt?" -> - "Hvad er den optimale bid-størrelse for forskellige dokumenttyper og hvorfor?" -> - "Hvordan håndterer jeg dokumenter på flere sprog eller med særlig formatering?" +> - "Hvordan splitter LangChain4j dokumenter i chunks, og hvorfor er overlap vigtigt?" +> - "Hvad er den optimale chunk-størrelse for forskellige dokumenttyper og hvorfor?" +> - "Hvordan håndterer jeg dokumenter på flere sprog eller med speciel formatering?" -### Oprettelse af embeddings +### Oprettelse af Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Hver bid konverteres til en numerisk repræsentation kaldet en embedding — i bund og grund en mening-til-tal-konverter. Embedding-modellen er ikke "intelligent" som en chatmodel; den kan ikke følge instruktioner, ræsonnere eller svare på spørgsmål. Den kan til gengæld kortlægge tekst til et matematisk rum, hvor lignende betydninger lander tæt på hinanden — "bil" tæt på "automobil", "refusionspolitik" tæt på "returner mine penge". Tænk på en chatmodel som en person, du kan tale med; en embedding-model er et ultragodt arkivsystem. +Hver chunk konverteres til en numerisk repræsentation kaldet en embedding — essentielt en betydnings-til-tal-omformer. Embedding-modellen er ikke "intelligent" på samme måde som en chatmodel; den kan ikke følge instruktioner, ræsonnere eller besvare spørgsmål. Det den kan, er at kortlægge tekst til et matematisk rum, hvor lignende betydninger lander tæt på hinanden — "bil" tæt på "automobil," "refunderingspolitik" tæt på "tilbagebetaling." Tænk på en chatmodel som en person du kan tale med; en embeddingmodel er et ultra-godt arkivsystem. -Diagrammet nedenfor visualiserer dette koncept — tekst går ind, numeriske vektorer kommer ud, og lignende betydninger producerer nærliggende vektorer: +Diagrammet nedenfor visualiserer dette koncept — tekst går ind, numeriske vektorer kommer ud, og lignende betydninger skaber nærliggende vektorer: -Embedding Model Concept +Embedding Model Koncept -*Dette diagram viser, hvordan en embedding-model konverterer tekst til numeriske vektorer, hvor lignende betydninger — som "bil" og "automobil" — placeres tæt på hinanden i vektor-rummet.* +*Dette diagram viser, hvordan en embeddingmodel konverterer tekst til numeriske vektorer og placerer lignende betydninger — som "bil" og "automobil" — tæt på hinanden i vektorrummet.* ```java @Bean @@ -153,30 +153,31 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -Klassediagrammet nedenfor viser de to separate flows i en RAG-pipeline og de LangChain4j-klasser, der implementerer dem. **Indtagsflowet** (kører én gang ved upload) splitter dokumentet, embedded bidderne og gemmer dem via `.addAll()`. **Forespørgselsflowet** (kører hver gang en bruger spørger) embedded spørgsmålet, søger i butikken via `.search()`, og sender den matchede kontekst til chatmodellen. Begge flows mødes i det delte interface `EmbeddingStore`: -LangChain4j RAG Classes -*Dette diagram viser de to flows i en RAG-pipeline — indtag og forespørgsel — og hvordan de forbindes gennem en delt EmbeddingStore.* +Klassediagrammet nedenfor viser de to separate flows i en RAG pipeline og de LangChain4j klasser, der implementerer dem. **Indslusningsflowet** (kører én gang ved upload) splitter dokumentet, embedder chunks og lagrer dem via `.addAll()`. **Forespørgselsflowet** (kører hver gang en bruger spørger) embedder spørgsmålet, søger i butikken via `.search()` og sender den matchede kontekst til chatmodellen. Begge flows mødes i det delte `EmbeddingStore` interface: + +LangChain4j RAG Klasser -Når embeddings er gemt, samler lignende indhold sig naturligt i vektor-rummet. Visualiseringen nedenfor viser, hvordan dokumenter om beslægtede emner ender som nærliggende punkter, hvilket muliggør semantisk søgning: +*Dette diagram viser de to flows i en RAG pipeline — ingestion og query — og hvordan de forbindes gennem et fælles EmbeddingStore.* -Vector Embeddings Space +Når embeddings er lagret, samles lignende indhold naturligt i klynger i vektorrummet. Visualiseringen nedenfor viser, hvordan dokumenter om beslægtede emner ender som nærliggende punkter, hvilket gør semantisk søgning mulig: -*Denne visualisering viser, hvordan relaterede dokumenter samler sig i 3D-vektor-rummet, med emner som Teknisk Docs, Forretningsregler og FAQs, der danner tydelige klynger.* +Vektor-Embeddings Rum -Når en bruger søger, følger systemet fire trin: embed dokumenterne én gang, embed forespørgslen ved hver søgning, sammenlign forespørgselsvektoren med alle gemte vektorer ved hjælp af cosinus-lighed, og returner de top-K højest scorende bidder. Diagrammet nedenfor gennemgår hvert trin og de involverede LangChain4j-klasser: +*Denne visualisering viser, hvordan beslægtede dokumenter klumper sig sammen i 3D vektorrum med emner som Tekniske Docs, Forretningsregler og FAQs som klare grupper.* -Embedding Search Steps +Når en bruger søger, følger systemet fire trin: embed dokumenterne én gang, embed forespørgslen ved hver søgning, sammenlign forespørgsels-vektor med alle lagrede vektorer vha. cosinus-lighed, og returner de top-K højst scorende chunks. Diagrammet nedenfor går igennem hvert trin og de LangChain4j klasser, der er involveret: -*Dette diagram viser den firetrins embedding-søgeproces: embed dokumenter, embed forespørgslen, sammenlign vektorer med cosinus-lighed, og returner top-K resultater.* +Embedding Søgetrin -### Semantisk søgning +*Dette diagram viser de fire trin i embedding-søgningen: embed dokumenter, embed forespørgsel, sammenlign vektorer med cosinuslighed, og returner top-K resultater.* + +### Semantisk Søgning [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Når du stiller et spørgsmål, bliver dit spørgsmål også til en embedding. Systemet sammenligner din spørgsmåls embedding med alle dokumentbidders embeddings. Det finder de bidder med mest lignende betydning — ikke bare matchende nøgleord, men faktisk semantisk lighed. +Når du stiller et spørgsmål, bliver dit spørgsmål også embeddet. Systemet sammenligner dit spørgsmåls embedding med alle dokument-chunks embeddings. Det finder chunks med mest lignende betydning — ikke bare nøgleord, men faktisk semantisk lighed. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +196,29 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -Diagrammet nedenfor kontrasterer semantisk søgning med traditionel nøgleordssøgning. En nøgleordssøgning på "køretøj" overser en bid om "biler og lastbiler," men semantisk søgning forstår, at de betyder det samme og returnerer den som et højt scorende match: -Semantic Search -*Dette diagram sammenligner nøgleordsbaseret søgning med semantisk søgning, der viser, hvordan semantisk søgning henter konceptuelt relateret indhold, selv når præcise nøgleord adskiller sig.* -Under overfladen måles lighed ved hjælp af cosinuslighed — i bund og grund spørgsmålet "peger disse to pile i samme retning?" To tekststykker kan bruge helt forskellige ord, men hvis de betyder det samme, peger deres vektorer i samme retning og scorer tæt på 1,0: +Diagrammet nedenfor kontrasterer semantisk søgning med traditionel nøgleordssøgning. En nøgleordssøgning på "køretøj" overser en chunk om "biler og lastbiler," men semantisk søgning forstår, at de betyder det samme og returnerer det som et topscorende match: + +Semantisk Søgning + +*Dette diagram sammenligner nøgleordsbaseret søgning med semantisk søgning og viser, hvordan semantisk søgning henter konceptuelt beslægtet indhold selv når de præcise nøgleord er forskellige.* -Cosine Similarity +Under motorhjelmen måles lighed med cosinus-lighed — essentielt spørger man "peger disse to pile i samme retning?" To chunks kan bruge helt forskellige ord, men hvis de betyder det samme, peger deres vektorer i samme retning og scorer tæt på 1,0: -*Dette diagram illustrerer cosinuslighed som vinklen mellem embeddingsvektorer — jo bedre justerede vektorerne er, desto tættere scorer de på 1,0, hvilket indikerer højere semantisk lighed.* +Cosinus Lighed +*Dette diagram illustrerer cosinuslighed som vinklen mellem indlejringsvektorer — mere justerede vektorer scorer tættere på 1,0, hvilket indikerer højere semantisk lighed.* > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) og spørg: -> - "Hvordan fungerer søgning efter lighed med embeddings, og hvad bestemmer scoren?" +> - "Hvordan fungerer lighedssøgning med indlejringer, og hvad bestemmer scoren?" > - "Hvilken lighedstærskel skal jeg bruge, og hvordan påvirker det resultaterne?" -> - "Hvordan håndterer jeg situationer, hvor der ikke findes relevante dokumenter?" +> - "Hvordan håndterer jeg tilfælde, hvor der ikke findes relevante dokumenter?" ### Svar Generering [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -De mest relevante tekststykker samles i en struktureret prompt, der inkluderer eksplicitte instruktioner, den hentede kontekst og brugerens spørgsmål. Modellen læser disse specifikke tekststykker og svarer baseret på denne information — den kan kun bruge det, der er foran den, hvilket forhindrer hallucination. +De mest relevante bidder samles i en struktureret prompt, der inkluderer eksplicitte instruktioner, den hentede kontekst og brugerens spørgsmål. Modellen læser disse specifikke bidder og svarer baseret på den information — den kan kun bruge det, der er foran den, hvilket forhindrer hallucination. ```java String context = matches.stream() @@ -237,17 +239,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Diagrammet nedenfor viser denne samling i praksis — de højest scorende tekststykker fra søgningstrinnet indsættes i promptskabelonen, og `OpenAiOfficialChatModel` genererer et funderet svar: +Diagrammet nedenfor viser denne samling i praksis — de højest scorende bidder fra søgetrinnet indsættes i prompt-skabelonen, og `OpenAiOfficialChatModel` genererer et funderet svar: Context Assembly -*Dette diagram viser, hvordan de højest scorende tekststykker samles i en struktureret prompt, så modellen kan generere et funderet svar fra dine data.* +*Dette diagram viser, hvordan de højest scorende bidder samles i en struktureret prompt, hvilket tillader modellen at generere et funderet svar fra dine data.* ## Kør Applikationen -**Bekræft deployment:** +**Bekræft implementering:** -Sørg for, at `.env` filen findes i rodmappen med Azure-legitimationsoplysninger (oprettet under Modul 01). Kør dette fra modulets mappe (`03-rag/`): +Sørg for, at `.env`-filen findes i rodmappen med Azure legitimationsoplysninger (oprettet under Modul 01). Kør dette fra modulkataloget (`03-rag/`): **Bash:** ```bash @@ -261,37 +263,37 @@ Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Start applikationen:** -> **Note:** Hvis du allerede har startet alle applikationer ved at bruge `./start-all.sh` fra rodmappen (som beskrevet i Modul 01), kører dette modul allerede på port 8081. Du kan springe startkommandoerne over nedenfor og gå direkte til http://localhost:8081. +> **Note:** Hvis du allerede har startet alle applikationer med `./start-all.sh` fra rodmappen (som beskrevet i Modul 01), kører dette modul allerede på port 8081. Du kan springe startkommandoerne over nedenfor og gå direkte til http://localhost:8081. **Mulighed 1: Brug Spring Boot Dashboard (Anbefalet til VS Code-brugere)** -Dev-containeren inkluderer Spring Boot Dashboard-udvidelsen, som giver et visuelt interface til at administrere alle Spring Boot-applikationer. Du finder det i Activity Bar til venstre i VS Code (søg efter Spring Boot-ikonet). +Dev-containeren inkluderer Spring Boot Dashboard-udvidelsen, som giver en visuel grænseflade til at håndtere alle Spring Boot-applikationer. Du finder den i Aktivitetsbjælken på venstre side af VS Code (se efter Spring Boot-ikonet). Fra Spring Boot Dashboard kan du: - Se alle tilgængelige Spring Boot-applikationer i arbejdsområdet - Starte/stoppe applikationer med et enkelt klik -- Se applikationslogs i realtid -- Overvåge applikationers status +- Se applikationslogfiler i realtid +- Overvåge applikationens status -Klik blot på play-knappen ud for "rag" for at starte dette modul, eller start alle moduler på én gang. +Klik blot på afspilningsknappen ved siden af "rag" for at starte dette modul, eller start alle moduler på én gang. Spring Boot Dashboard *Dette screenshot viser Spring Boot Dashboard i VS Code, hvor du visuelt kan starte, stoppe og overvåge applikationer.* -**Mulighed 2: Brug shell scripts** +**Mulighed 2: Brug shell-scripts** Start alle webapplikationer (moduler 01-04): **Bash:** ```bash -cd .. # Fra rodmappen +cd .. # Fra rodbiblioteket ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Fra rodmappen +cd .. # Fra rodkatalog .\start-all.ps1 ``` @@ -309,7 +311,7 @@ cd 03-rag .\start.ps1 ``` -Begge scripts indlæser automatisk miljøvariabler fra rodens `.env` fil og bygger JAR-filerne, hvis de ikke findes. +Begge scripts indlæser automatisk miljøvariabler fra root `.env`-filen og vil bygge JAR-filerne, hvis de ikke findes. > **Note:** Hvis du foretrækker at bygge alle moduler manuelt før start: > @@ -331,107 +333,107 @@ Begge scripts indlæser automatisk miljøvariabler fra rodens `.env` fil og bygg **Bash:** ```bash -./stop.sh # Dette modul kun +./stop.sh # Kun denne modul # Eller cd .. && ./stop-all.sh # Alle moduler ``` **PowerShell:** ```powershell -.\stop.ps1 # Dette modul kun +.\stop.ps1 # Kun denne modul # Eller cd ..; .\stop-all.ps1 # Alle moduler ``` ## Brug af Applikationen -Applikationen tilbyder et webinterface til dokumentupload og spørgsmål. +Applikationen tilbyder en webgrænseflade til dokumentupload og spørgsmål. RAG Application Interface -*Dette screenshot viser RAG-applikationens interface, hvor du uploader dokumenter og stiller spørgsmål.* +*Dette screenshot viser RAG-applikationsgrænsefladen, hvor du uploader dokumenter og stiller spørgsmål.* ### Upload et Dokument -Start med at uploade et dokument – TXT-filer virker bedst til test. En `sample-document.txt` er inkluderet i denne mappe, som indeholder information om LangChain4j-funktioner, RAG-implementering og bedste praksis – perfekt til test af systemet. +Start med at uploade et dokument – TXT-filer fungerer bedst til test. Et `sample-document.txt` er tilgængeligt i denne mappe, som indeholder information om LangChain4j-funktioner, RAG-implementering og best practices - perfekt til at teste systemet. -Systemet behandler dit dokument, splitter det op i tekststykker og skaber embeddings for hvert stykke. Dette sker automatisk ved upload. +Systemet behandler dit dokument, opdeler det i bidder og skaber indlejringer for hver bid. Dette sker automatisk, når du uploader. ### Stil Spørgsmål -Nu kan du stille specifikke spørgsmål om dokumentets indhold. Prøv noget faktuelt, der klart står i dokumentet. Systemet søger efter relevante tekststykker, inkluderer dem i prompten og genererer et svar. +Stil nu specifikke spørgsmål om dokumentindholdet. Prøv noget faktuelt, der klart fremgår af dokumentet. Systemet søger efter relevante bidder, inkluderer dem i prompten og genererer et svar. ### Tjek Kildehenvisninger -Bemærk, at hvert svar inkluderer kildehenvisninger med lighedsscores. Disse scores (fra 0 til 1) viser, hvor relevant hvert tekststykke var ift. dit spørgsmål. Højere scores betyder bedre matches. Det giver dig mulighed for at efterprøve svaret mod kildematerialet. +Bemærk, at hvert svar inkluderer kildehenvisninger med lighedsscoringer. Disse scorer (0 til 1) viser, hvor relevante bidder var for dit spørgsmål. Højere scorer betyder bedre match. Dette lader dig verificere svaret mod kildematerialet. RAG Query Results -*Dette screenshot viser forespørgselsresultater med det genererede svar, kildehenvisninger og relevansscores for hvert hentet tekststykke.* +*Dette screenshot viser forespørgselsresultater med det genererede svar, kildehenvisninger og relevansscores for hver hentet bid.* -### Eksperimentér med Spørgsmål +### Eksperimenter med Spørgsmål Prøv forskellige typer spørgsmål: - Specifikke fakta: "Hvad er hovedemnet?" - Sammenligninger: "Hvad er forskellen mellem X og Y?" -- Opsummeringer: "Opsummer hovedpunkterne om Z" +- Resuméer: "Opsummer hovedpunkterne om Z" -Se, hvordan relevansscores ændrer sig baseret på, hvor godt dit spørgsmål matcher dokumentindholdet. +Se hvordan relevansscore ændres afhængigt af, hvor godt dit spørgsmål matcher dokumentindholdet. ## Nøglebegreber -### Chunking-strategi +### Opdelingsstrategi -Dokumenter deles op i 300-token tekststykker med 30 tokens overlap. Denne balance sikrer, at hvert stykke har nok kontekst til at være meningsfuldt, samtidig med at stykkerne er små nok til at inkludere flere i en prompt. +Dokumenter opdeles i bidder på 300 tokens med 30 tokens overlap. Denne balance sikrer, at hver bid har nok kontekst til at være meningsfuld, samtidig med at de er små nok til at inkludere flere bidder i en prompt. -### Similarity Scores +### Lighedsscores -Hvert hentet tekststykke kommer med en lighedsscore mellem 0 og 1, der angiver, hvor tæt det matcher brugerens spørgsmål. Diagrammet nedenfor visualiserer score-intervallerne og hvordan systemet bruger dem til at filtrere resultater: +Hver hentet bid har en lighedsscore mellem 0 og 1, der angiver, hvor tæt den matcher brugerens spørgsmål. Diagrammet nedenfor visualiserer scoreintervallerne og hvordan systemet bruger dem til at filtrere resultater: Similarity Scores -*Dette diagram viser score-intervaller fra 0 til 1 med en minimumstærskel på 0,5, som filtrerer irrelevante tekststykker fra.* +*Dette diagram viser scoreintervaller fra 0 til 1, med en minimumsterskel på 0,5, der filtrerer irrelevante bidder.* -Scores varierer fra 0 til 1: -- 0,7-1,0: Meget relevant, eksakt match +Score spænder fra 0 til 1: +- 0,7-1,0: Meget relevant, præcis match - 0,5-0,7: Relevant, god kontekst -- Under 0,5: Filtreret fra, for forskelligt +- Under 0,5: Filtreret fra, for forskellig -Systemet henter kun tekststykker over minimumstærsklen for at sikre kvalitet. +Systemet henter kun bidder over minimumstersklen for at sikre kvalitet. -Embeddings fungerer godt, når betydninger danner klare klynger, men har blinde vinkler. Diagrammet nedenfor viser almindelige fejlsituationer — tekststykker, der er for store, skaber upræcise vektorer, tekststykker, der er for små, mangler kontekst, tvetydige termer peger på flere klynger, og eksakte opslag (ID’er, reservedelsnumre) virker ikke med embeddings overhovedet: +Indlejringer fungerer godt, når betydninger klumper sig rent, men har blinde vinkler. Diagrammet nedenfor viser de almindelige fejltilstande — bidder der er for store producerer uklare vektorer, bidder der er for små mangler kontekst, tvetydige termer peger på flere klynger, og præcise opslag (ID'er, reservedelsnumre) fungerer slet ikke med indlejringer: Embedding Failure Modes -*Dette diagram viser almindelige embeddings-fejlsituationer: tekststykker for store, tekststykker for små, tvetydige termer, der peger på flere klynger, og eksakte opslag som ID’er.* +*Dette diagram viser almindelige fejltilstande ved indlejringer: bidder for store, bidder for små, tvetydige termer der peger på flere klynger, og præcise opslag som ID'er.* -### In-Memory Storage +### In-Memory Lagring -Dette modul bruger hukommelsesbaseret lagring for enkelheds skyld. Ved genstart af applikationen mistes uploadede dokumenter. Produktionssystemer anvender persistente vektordatabaser som Qdrant eller Azure AI Search. +Dette modul anvender in-memory lagring for enkelhedens skyld. Når du genstarter applikationen, mistes uploadede dokumenter. Produksjonssystemer bruger vedvarende vektordatabaser som Qdrant eller Azure AI Search. -### Context Window Management +### Håndtering af Kontekstvindue -Hver model har et maksimum for kontekstvindet. Du kan ikke inkludere alle tekststykker fra et stort dokument. Systemet henter de top N mest relevante tekststykker (standard 5) for at holde sig inden for grænserne og samtidig give nok kontekst til præcise svar. +Hver model har et maksimalt kontekstvindue. Du kan ikke inkludere alle bidder fra et stort dokument. Systemet henter de N mest relevante bidder (standard 5) for at holde sig inden for grænserne samtidig med at der gives nok kontekst til præcise svar. -## Hvornår RAG er vigtigt +## Når RAG Betyr Noget -RAG er ikke altid den rigtige løsning. Beslutningsguiden nedenfor hjælper dig med at afgøre, hvornår RAG tilfører værdi versus hvornår enklere tilgange — som at inkludere indhold direkte i prompten eller stole på modellens indbyggede viden — er tilstrækkelige: +RAG er ikke altid den rette tilgang. Beslutningsguiden nedenfor hjælper dig med at afgøre, hvornår RAG tilfører værdi kontra hvornår enklere tilgange — som at inkludere indhold direkte i prompten eller stole på modellens indbyggede viden — er tilstrækkelige: When to Use RAG -*Dette diagram viser en beslutningsguide for, hvornår RAG tilfører værdi, og hvornår enklere tilgange er tilstrækkelige.* +*Dette diagram viser en beslutningsguide for, hvornår RAG tilfører værdi kontra hvornår enklere tilgange er tilstrækkelige.* -## Næste skridt +## Næste Skridt -**Næste Modul:** [04-tools - AI-agenter med værktøjer](../04-tools/README.md) +**Næste Modul:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**Navigation:** [← Forrige: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Tilbage til start](../README.md) | [Næste: Modul 04 - Værktøjer →](../04-tools/README.md) +**Navigation:** [← Forrige: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Tilbage til Hovedmenu](../README.md) | [Næste: Modul 04 - Tools →](../04-tools/README.md) --- **Ansvarsfraskrivelse**: -Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi stræber efter nøjagtighed, skal du være opmærksom på, at automatiske oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritiske oplysninger anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for eventuelle misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. +Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. \ No newline at end of file diff --git a/translations/da/04-tools/README.md b/translations/da/04-tools/README.md index d673e1ee3..99103d1ce 100644 --- a/translations/da/04-tools/README.md +++ b/translations/da/04-tools/README.md @@ -2,75 +2,75 @@ ## Indholdsfortegnelse -- [Videogennemgang](../../../04-tools) -- [Det vil du lære](../../../04-tools) -- [Forudsætninger](../../../04-tools) -- [Forståelse af AI-agenter med værktøjer](../../../04-tools) -- [Hvordan værktøjskald fungerer](../../../04-tools) - - [Værktøjsdefinitioner](../../../04-tools) - - [Beslutningstagning](../../../04-tools) - - [Udførelse](../../../04-tools) - - [Generering af svar](../../../04-tools) - - [Arkitektur: Spring Boot Auto-Wiring](../../../04-tools) -- [Kædning af værktøjer](../../../04-tools) -- [Kør applikationen](../../../04-tools) -- [Brug af applikationen](../../../04-tools) - - [Prøv enkel værktøjsbrug](../../../04-tools) - - [Test kædning af værktøjer](../../../04-tools) - - [Se samtaleflow](../../../04-tools) - - [Eksperimenter med forskellige forespørgsler](../../../04-tools) -- [Nøglebegreber](../../../04-tools) - - [ReAct-mønsteret (Reasoning and Acting)](../../../04-tools) - - [Værktøjsbeskrivelser betyder noget](../../../04-tools) - - [Sessionsstyring](../../../04-tools) - - [Fejlhåndtering](../../../04-tools) -- [Tilgængelige værktøjer](../../../04-tools) -- [Hvornår man skal bruge værktøjsbaserede agenter](../../../04-tools) -- [Værktøjer vs RAG](../../../04-tools) -- [Næste skridt](../../../04-tools) - -## Videogennemgang - -Se denne live-session, som forklarer, hvordan du kommer i gang med dette modul: +- [Video Gennemgang](#video-gennemgang) +- [Hvad Du Vil Lære](#hvad-du-vil-lære) +- [Forudsætninger](#forudsætninger) +- [Forståelse af AI-agenter med værktøjer](#forståelse-af-ai-agenter-med-værktøjer) +- [Hvordan værktøjskald fungerer](#hvordan-værktøjskald-fungerer) + - [Værktøjsdefinitioner](#værktøjsdefinitioner) + - [Beslutningstagning](#beslutningstagning) + - [Eksekvering](#eksekvering) + - [Svargenerering](#svargenerering) + - [Arkitektur: Spring Boot Auto-Wiring](#arkitektur-spring-boot-auto-wiring) +- [Værktøjskædning](#værktøjskædning) +- [Kør applikationen](#kør-applikationen) +- [Brug af applikationen](#brug-af-applikationen) + - [Prøv simpel værktøjsbrug](#prøv-simpel-værktøjsbrug) + - [Test værktøjskædning](#test-værktøjskædning) + - [Se samtaleflow](#se-samtaleflow) + - [Eksperimenter med forskellige forespørgsler](#eksperimenter-med-forskellige-forespørgsler) +- [Nøglebegreber](#nøglebegreber) + - [ReAct-mønster (Tænkning og Handling)](#react-mønster-tænkning-og-handling) + - [Værktøjsbeskrivelser betyder noget](#værktøjsbeskrivelser-betyder-noget) + - [Sessionsstyring](#sessionsstyring) + - [Fejlhåndtering](#fejlhåndtering) +- [Tilgængelige værktøjer](#tilgængelige-værktøjer) +- [Hvornår man skal bruge værktøjsbaserede agenter](#hvornår-man-skal-bruge-værktøjsbaserede-agenter) +- [Værktøjer vs RAG](#værktøjer-vs-rag) +- [Næste skridt](#næste-skridt) + +## Video Gennemgang + +Se denne live session, som forklarer, hvordan man kommer i gang med dette modul: AI Agents with Tools and MCP - Live Session -## Det vil du lære +## Hvad Du Vil Lære -Indtil videre har du lært, hvordan man har samtaler med AI, strukturerer prompts effektivt og forankrer svar i dine dokumenter. Men der er stadig en grundlæggende begrænsning: sprogmodeller kan kun generere tekst. De kan ikke tjekke vejret, udføre beregninger, forespørge databaser eller interagere med eksterne systemer. +Indtil videre har du lært, hvordan man har samtaler med AI, strukturerer prompts effektivt og forankrer svar i dine dokumenter. Men der er stadig en grundlæggende begrænsning: sprogmodeller kan kun generere tekst. De kan ikke tjekke vejret, udføre beregninger, spørge databaser eller interagere med eksterne systemer. -Værktøjer ændrer dette. Ved at give modellen adgang til funktioner, den kan kalde, forvandler du den fra en tekstgenerator til en agent, som kan handle. Modellen beslutter, hvornår den har brug for et værktøj, hvilket værktøj den skal bruge, og hvilke parametre den skal sende. Din kode udfører funktionen og returnerer resultatet. Modellen indarbejder dette resultat i sit svar. +Værktøjer ændrer dette. Ved at give modellen adgang til funktioner, den kan kalde, forvandler du den fra en tekstgenerator til en agent, der kan udføre handlinger. Modellen beslutter, hvornår den har brug for et værktøj, hvilket værktøj den skal bruge, og hvilke parametre den skal sende. Din kode eksekverer funktionen og returnerer resultatet. Modellen indarbejder det resultat i sit svar. ## Forudsætninger -- Fuldført [Modul 01 - Introduktion](../01-introduction/README.md) (Azure OpenAI-ressourcer er implementeret) -- Fuldførte tidligere moduler anbefales (dette modul refererer til [RAG-koncepter fra Modul 03](../03-rag/README.md) i sammenligningen mellem Værktøjer og RAG) -- `.env`-fil i rodkatalog med Azure-legitimationsoplysninger (oprettet af `azd up` i Modul 01) +- Færdiggjort [Modul 01 - Introduktion](../01-introduction/README.md) (Azure OpenAI ressourcer deployeret) +- Tidligere moduler anbefales færdiggjort (dette modul refererer til [RAG-konceptet fra Modul 03](../03-rag/README.md) i sammenligningen Værktøjer vs RAG) +- `.env` fil i rodkataloget med Azure legitimationsoplysninger (oprettet af `azd up` i Modul 01) -> **Note:** Hvis du ikke har fuldført Modul 01, skal du følge implementeringsvejledningen der først. +> **Note:** Hvis du ikke har færdiggjort Modul 01, så følg først deploymentsinstruktionerne der. ## Forståelse af AI-agenter med værktøjer -> **📝 Note:** Udtrykket "agenter" i dette modul henviser til AI-assistenter, der er udvidet med evnen til at kalde værktøjer. Dette er forskelligt fra **Agentic AI**-mønstrene (autonome agenter med planlægning, hukommelse og flertrinsresonnement), som vi vil dække i [Modul 05: MCP](../05-mcp/README.md). +> **📝 Note:** Udtrykket "agenter" i dette modul henviser til AI-assistenter, som er forbedret med evnen til at kalde værktøjer. Dette adskiller sig fra **Agentic AI** mønstrene (autonome agenter med planlægning, hukommelse og flerstegs ræsonnering), som vi vil dække i [Modul 05: MCP](../05-mcp/README.md). -Uden værktøjer kan en sprogmodel kun generere tekst ud fra sine træningsdata. Spørg den om det nuværende vejr, og den må gætte. Giv den værktøjer, og den kan kalde en vejr-API, udføre beregninger eller forespørge en database — og så væve disse faktiske resultater ind i sit svar. +Uden værktøjer kan en sprogmodel kun generere tekst ud fra sine træningsdata. Spørger du om vejret, må den gætte. Giv den værktøjer, og den kan kalde en vejrudsigts-API, udføre beregninger eller spørge en database — og derefter flette de faktiske resultater ind i sit svar. Without Tools vs With Tools -*Uden værktøjer kan modellen kun gætte — med værktøjer kan den kalde API’er, køre beregninger og returnere realtime data.* +*Uden værktøjer kan modellen kun gætte — med værktøjer kan den kalde API’er, udføre beregninger og returnere realtidsdata.* -En AI-agent med værktøjer følger et **Reasoning and Acting (ReAct)** mønster. Modellen reagerer ikke bare — den tænker over, hvad den har brug for, handler ved at kalde et værktøj, observerer resultatet og beslutter så, om den skal handle igen eller give det endelige svar: +En AI-agent med værktøjer følger et **Reasoning and Acting (ReAct)** mønster. Modellen responderer ikke bare — den tænker over, hvad den har brug for, handler ved at kalde et værktøj, observerer resultatet, og beslutter så, om den skal handle igen eller levere det endelige svar: -1. **Resonér** — Agenten analyserer brugerens spørgsmål og fastslår, hvilken information den har brug for -2. **Handl** — Agenten vælger det rette værktøj, genererer de korrekte parametre og kalder værktøjet -3. **Observer** — Agenten modtager værktøjets output og evaluerer resultatet -4. **Gentag eller svar** — Hvis der er brug for mere data, gentager agenten processen; ellers udformer den et naturligt sprog-svar +1. **Ræsonnere** — Agenten analyserer brugerens spørgsmål og bestemmer, hvilken information den har brug for +2. **Handle** — Agenten vælger det rigtige værktøj, genererer de korrekte parametre og kalder det +3. **Observere** — Agenten modtager værktøjets output og evaluerer resultatet +4. **Gentage eller svare** — Hvis der er brug for mere data, gentager agenten; ellers formulerer den et naturligt sprog svar ReAct Pattern -*ReAct-cyklussen — agenten overvejer handling, handler ved at kalde et værktøj, observerer resultatet, og gentager til det kan levere et endeligt svar.* +*ReAct-cyklussen — agenten ræsonnerer om, hvad den skal gøre, handler ved at kalde et værktøj, observerer resultatet, og gentager indtil det kan levere det endelige svar.* -Dette sker automatisk. Du definerer værktøjerne og deres beskrivelser. Modellen håndterer beslutningstagningen om, hvornår og hvordan de skal bruges. +Dette sker automatisk. Du definerer værktøjerne og deres beskrivelser. Modellen håndterer beslutningen om, hvornår og hvordan de skal bruges. ## Hvordan værktøjskald fungerer @@ -78,7 +78,7 @@ Dette sker automatisk. Du definerer værktøjerne og deres beskrivelser. Modelle [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Du definerer funktioner med klare beskrivelser og parameterspecifikationer. Modellen ser disse beskrivelser i sit systemprompt og forstår, hvad hvert værktøj gør. +Du definerer funktioner med klare beskrivelser og parametrespecifikationer. Modellen ser disse beskrivelser i sit system-prompt og forstår, hvad hvert værktøj gør. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Din vejropslagslogik + // Din logik til vejropslag return "Weather in " + location + ": 22°C, cloudy"; } } @@ -99,101 +99,101 @@ public interface Assistant { // Assistenten er automatisk forbundet af Spring Boot med: // - ChatModel bean // - Alle @Tool metoder fra @Component klasser -// - ChatMemoryProvider til sessionshåndtering +// - ChatMemoryProvider til sessionhåndtering ``` -Diagrammet nedenfor gennemgår hver annotation og viser, hvordan hver del hjælper AI med at forstå, hvornår værktøjet skal kaldes, og hvilke argumenter der skal sendes: +Diagrammet nedenfor gennemgår hver annotation og viser, hvordan hver del hjælper AI med at forstå, hvornår den skal kalde værktøjet, og hvilke argumenter den skal sende: Anatomy of Tool Definitions -*Anatomi af en værktøjsdefinition — @Tool fortæller AI, hvornår det skal bruges, @P beskriver hver parameter, og @AiService forbinder det hele ved opstart.* +*Anatomi af en værktøjsdefinition — @Tool fortæller AI, hvornår den skal bruge det, @P beskriver hver parameter, og @AiService samler det hele ved opstart.* > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) og spørg: -> - "Hvordan integrerer jeg en ægte vejr-API som OpenWeatherMap i stedet for mock-data?" -> - "Hvad gør en god værktøjsbeskrivelse, der hjælper AI med at bruge det korrekt?" +> - "Hvordan integrerer jeg en rigtig vejrudsigts-API som OpenWeatherMap i stedet for mock-data?" +> - "Hvad gør en god værktøjsbeskrivelse, som hjælper AI med at bruge det korrekt?" > - "Hvordan håndterer jeg API-fejl og rate limits i værktøjsimplementeringer?" ### Beslutningstagning -Når en bruger spørger "Hvordan er vejret i Seattle?", vælger modellen ikke tilfældigt et værktøj. Den sammenligner brugerens hensigt med alle værktøjsbeskrivelser, den har adgang til, vurderer relevansen for hver og vælger det bedste match. Den genererer derefter et struktureret funktionskald med de rette parametre — i dette tilfælde ved at sætte `location` til `"Seattle"`. +Når en bruger spørger "Hvordan er vejret i Seattle?", vælger modellen ikke tilfældigt et værktøj. Den sammenligner brugerens intention med hver værktøjsbeskrivelse, den har adgang til, vurderer relevansen af hver, og vælger det bedste match. Den genererer derefter et struktureret funktionskald med de rigtige parametre — i dette tilfælde `location` sat til `"Seattle"`. -Hvis intet værktøj matcher brugerens forespørgsel, falder modellen tilbage til at svare ud fra sin egen viden. Hvis flere værktøjer matcher, vælger den det mest specifikke. +Hvis intet værktøj matcher brugerens forespørgsel, falder modellen tilbage og svarer ud fra sin egen viden. Hvis flere værktøjer matcher, vælger den det mest specifikke. How the AI Decides Which Tool to Use -*Modellen evaluerer hvert tilgængeligt værktøj i forhold til brugerens hensigt og vælger det bedste match — derfor er klare, specifikke værktøjsbeskrivelser vigtige.* +*Modellen evaluerer hvert tilgængeligt værktøj mod brugerens intention og vælger det bedste match — derfor er klare og specifikke værktøjsbeskrivelser vigtige.* -### Udførelse +### Eksekvering [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot auto-forbinder det deklarative `@AiService` interface med alle registrerede værktøjer, og LangChain4j udfører værktøjskald automatisk. Bag kulisserne har et komplet værktøjskald seks faser — fra brugerens spørgsmål i naturligt sprog helt tilbage til et svar i naturligt sprog: +Spring Boot auto-wirer det deklarative `@AiService` interface med alle registrerede værktøjer, og LangChain4j eksekverer værktøjskald automatisk. Bag scenen flyder en komplet værktøjskaldproces gennem seks faser — fra brugerens spørgsmål i naturligt sprog hele vejen tilbage til et naturligt sprog svar: Tool Calling Flow -*Den komplette end-to-end flow — brugeren stiller et spørgsmål, modellen vælger et værktøj, LangChain4j udfører det, og modellen fletter resultatet ind i et naturligt svar.* +*Den end-to-end flow — brugeren stiller et spørgsmål, modellen vælger et værktøj, LangChain4j udfører det, og modellen fletter resultatet ind i et naturligt svar.* -Hvis du kørte [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) i Modul 00, har du allerede set dette mønster i aktion — `Calculator`-værktøjerne blev kaldt på samme måde. Sekvensdiagrammet nedenfor viser præcis, hvad der skete under overfladen under den demo: +Bag scenen kører `AiServices` den samme værktøjskaldsløkke for ethvert værktøj — her illustreret med en simpel `Calculator`. Sekvensdiagrammet nedenfor viser præcis, hvad der sker under motorhjelmen: Tool Calling Sequence Diagram -*Værktøjskaldsløkken fra Quick Start-demoen — `AiServices` sender din besked og værktøjsskemaer til LLM, LLM svarer med et funktionskald som `add(42, 58)`, LangChain4j kører `Calculator`-metoden lokalt, og sender resultatet tilbage til det endelige svar.* +*Værktøjskaldsløkken — `AiServices` sender din besked og værktøjsskemaer til LLM, LLM svarer med et funktionskald som `add(42, 58)`, LangChain4j udfører `Calculator` metoden lokalt, og sender resultatet tilbage til det endelige svar.* > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åbn [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) og spørg: -> - "Hvordan fungerer ReAct-mønsteret, og hvorfor er det effektivt for AI-agenter?" +> - "Hvordan fungerer ReAct-mønsteret og hvorfor er det effektivt for AI-agenter?" > - "Hvordan beslutter agenten, hvilket værktøj der skal bruges og i hvilken rækkefølge?" -> - "Hvad sker der, hvis en værktøjsudførelse fejler - hvordan håndterer jeg fejl robust?" +> - "Hvad sker der, hvis et værktøjseksekvering fejler - hvordan håndterer jeg fejl robust?" -### Generering af svar +### Svargenerering -Modellen modtager vejrinformationerne og formaterer dem til et svar i naturligt sprog til brugeren. +Modellen modtager vejrudsigtsdataene og formaterer det til et svar i naturligt sprog til brugeren. ### Arkitektur: Spring Boot Auto-Wiring -Dette modul bruger LangChain4js Spring Boot-integration med deklarative `@AiService` interfaces. Ved opstart opdager Spring Boot alle `@Component` med `@Tool`-metoder, din `ChatModel` bean og `ChatMemoryProvider` — og binder dem alle sammen i et enkelt `Assistant` interface uden boilerplate. +Dette modul bruger LangChain4j’s Spring Boot integration med deklarative `@AiService` interfaces. Ved opstart opdager Spring Boot alle `@Component` der indeholder `@Tool` metoder, din `ChatModel` bean og `ChatMemoryProvider` — og kobler dem alle sammen i et enkelt `Assistant` interface uden nogen form for boilerplate. Spring Boot Auto-Wiring Architecture -*@AiService-interfacet binder ChatModel, værktøjskomponenter og hukommelsesudbyder sammen — Spring Boot håndterer alle bindinger automatisk.* +*@AiService interfacet samler ChatModel, værktøjskomponenter og hukommelsesprovider — Spring Boot håndterer al wiring automatisk.* -Her er hele anmodningens livscyklus som et sekvensdiagram — fra HTTP-anmodningen gennem controller, service og auto-forbundet proxy, helt til værktøjets udførelse og tilbage: +Her er hele forespørgselslivscyklussen som sekvensdiagram — fra HTTP-forespørgslen via controller, service og auto-wired proxy, hele vejen til værktøjseksekvering og tilbage: Spring Boot Tool Calling Sequence -*Den komplette Spring Boot-anmodnings livscyklus — HTTP-anmodningen går gennem controlleren og servicen til den auto-forbundne Assistant proxy, som orkestrerer LLM og værktøjskald automatisk.* +*Den komplette Spring Boot forespørgselslivscyklus — HTTP-forespørgslen flyder gennem controller og service til den auto-wired Assistant proxy, som orkestrerer LLM og værktøjskald automatisk.* Vigtige fordele ved denne tilgang: - **Spring Boot auto-wiring** — ChatModel og værktøjer injiceres automatisk -- **@MemoryId-mønster** — Automatisk sessionsbaseret hukommelsesstyring -- **Én enkelt instans** — Assistant oprettes én gang og genbruges for bedre ydeevne -- **Typesikker udførelse** — Java-metoder kaldes direkte med typekonvertering -- **Multi-turn orkestrering** — Håndterer automatisk kædning af værktøjer -- **Ingen boilerplate** — Ingen manuelle kald til `AiServices.builder()` eller hukommelses-HashMap +- **@MemoryId mønster** — Automatisk sessionsbaseret hukommelsesstyring +- **Enkelt instans** — Assistant oprettes én gang og genbruges for bedre ydeevne +- **Typesikker eksekvering** — Java-metoder kaldes direkte med typekonvertering +- **Multi-turn orkestrering** — Håndterer værktøjskædning automatisk +- **Ingen boilerplate** — Ingen manuelle `AiServices.builder()` kald eller hukommelses HashMap -Alternative tilgange (manuelt `AiServices.builder()`) kræver mere kode og mangler Spring Boot integrationsfordele. +Alternative tilgange (manuelt `AiServices.builder()`) kræver mere kode og mangler Spring Boot integrationsfordelene. -## Kædning af værktøjer +## Værktøjskædning -**Kædning af værktøjer** — Den virkelige styrke ved værktøjsbaserede agenter viser sig, når et enkelt spørgsmål kræver flere værktøjer. Spørg "Hvordan er vejret i Seattle i Fahrenheit?" og agenten kæder automatisk to værktøjer sammen: først kalder den `getCurrentWeather` for at få temperaturen i Celsius, derefter sender den den værdi til `celsiusToFahrenheit` for konvertering — alt sammen i én samtalerunde. +**Værktøjskædning** — Den reelle styrke ved værktøjsbaserede agenter viser sig, når et enkelt spørgsmål kræver flere værktøjer. Spørg "Hvordan er vejret i Seattle i Fahrenheit?" og agenten kæder automatisk to værktøjer sammen: først kaldes `getCurrentWeather` for at hente temperaturen i Celsius, derefter sendes den værdi til `celsiusToFahrenheit` for konvertering — alt i én samtalerunde. Tool Chaining Example -*Kædning af værktøjer i aktion — agenten kalder først getCurrentWeather, sender så Celsius-resultatet videre til celsiusToFahrenheit, og leverer et samlet svar.* +*Værktøjskædning i praksis — agenten kalder først getCurrentWeather, sender derefter Celsius-resultatet til celsiusToFahrenheit og leverer et kombineret svar.* -**Elegant fejlhåndtering** — Spørg efter vejret i en by, der ikke findes i mock-dataene. Værktøjet returnerer en fejlmeddelelse, og AI forklarer, at den ikke kan hjælpe i stedet for at crashe. Værktøjer fejler sikkert. Diagrammet nedenfor sammenligner de to tilgange — med korrekt fejlhåndtering fanger agenten undtagelsen og svarer hjælpsomt, mens uden den crasher hele applikationen: +**Gracieuze fejl** — Spørg efter vejret i en by der ikke findes i mock-dataene. Værktøjet returnerer en fejlmeddelelse, og AI forklarer, at det ikke kan hjælpe fremfor at crashe. Værktøjer fejler sikkert. Diagrammet nedenfor kontrasterer de to tilgange — med korrekt fejlhåndtering fanger agenten undtagelsen og svarer hjælpsomt, uden fejlhåndtering crasher hele applikationen: Error Handling Flow *Når et værktøj fejler, fanger agenten fejlen og svarer med en hjælpsom forklaring i stedet for at crashe.* -Dette sker i én samtalerunde. Agenten orkestrerer flere værktøjskald autonomt. +Dette sker i en enkelt samtalerunde. Agenten orkestrerer flere værktøjskald autonomt. ## Kør applikationen -**Bekræft implementering:** +**Verificer deployment:** -Sørg for, at `.env`-filen findes i rodkataloget med Azure-legitimationsoplysninger (oprettet under Modul 01). Kør dette fra modulets bibliotek (`04-tools/`): +Sørg for, at `.env` filen findes i rodkataloget med Azure legitimationsoplysninger (oprettet under Modul 01). Kør dette fra modulkataloget (`04-tools/`): **Bash:** ```bash @@ -207,42 +207,42 @@ Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Start applikationen:** -> **Note:** Hvis du allerede har startet alle applikationer med `./start-all.sh` fra rodkataloget (som beskrevet i Modul 01), kører dette modul allerede på port 8084. Du kan springe startkommandoerne over og gå direkte til http://localhost:8084. +> **Note:** Hvis du allerede har startet alle applikationer med `./start-all.sh` fra rodkataloget (som beskrevet i Modul 01), kører dette modul allerede på port 8084. Du kan springe startkommandoerne nedenfor over og gå direkte til http://localhost:8084. -**Mulighed 1: Brug af Spring Boot Dashboard (Anbefales til VS Code-brugere)** +**Mulighed 1: Brug Spring Boot Dashboard (anbefales til VS Code-brugere)** -Dev-containeren inkluderer Spring Boot Dashboard-udvidelsen, som giver en visuel grænseflade til at administrere alle Spring Boot-applikationer. Du kan finde den i aktivitetsbjælken til venstre i VS Code (se efter Spring Boot-ikonet). +Dev containeren inkluderer Spring Boot Dashboard udvidelsen, som giver en visuel brugerflade til at styre alle Spring Boot applikationer. Du kan finde den i Aktivitetslinjen til venstre i VS Code (se efter Spring Boot ikonet). Fra Spring Boot Dashboard kan du: -- Se alle tilgængelige Spring Boot-applikationer i arbejdsområdet -- Starte/stoppe applikationer med et enkelt klik +- Se alle tilgængelige Spring Boot applikationer i workspace +- Starte/stoppe applikationer med ét klik - Se applikationslogs i realtid - Overvåge applikationens status + Klik blot på afspilningsknappen ved siden af "tools" for at starte dette modul, eller start alle moduler på én gang. Sådan ser Spring Boot Dashboard ud i VS Code: - Spring Boot Dashboard -*Spring Boot Dashboard i VS Code — start, stop og overvåg alle moduler fra ét sted* +*Spring Boot-dashboardet i VS Code — start, stop og overvåg alle moduler ét sted* -**Mulighed 2: Brug af shell scripts** +**Mulighed 2: Brug af shell-scripts** Start alle webapplikationer (moduler 01-04): **Bash:** ```bash -cd .. # Fra rodmappen +cd .. # Fra rodkatalog ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Fra rodmappe +cd .. # Fra rodmappen .\start-all.ps1 ``` -Eller start kun dette modul: +Eller start kun denne modul: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Begge scripts indlæser automatisk miljøvariabler fra roden `.env`-filen og vil bygge JAR-filerne, hvis de ikke findes. +Begge scripts indlæser automatisk miljøvariable fra rod-`.env`-filen og vil bygge JAR-filerne, hvis de ikke findes. -> **Bemærk:** Hvis du foretrækker at bygge alle moduler manuelt inden start: +> **Note:** Hvis du foretrækker at bygge alle moduler manuelt før start: > > **Bash:** > ```bash @@ -290,72 +290,72 @@ cd .. && ./stop-all.sh # Alle moduler cd ..; .\stop-all.ps1 # Alle moduler ``` -## Brug af Applikationen +## Brug af applikationen -Applikationen giver en webgrænseflade, hvor du kan interagere med en AI-agent, der har adgang til vejr- og temperaturkonverteringsværktøjer. Sådan ser grænsefladen ud — den indeholder hurtigstart-eksempler og en chatpanel til at sende forespørgsler: +Applikationen tilbyder en webgrænseflade, hvor du kan interagere med en AI-agent, der har adgang til vejr- og temperaturkonverteringsværktøjer. Sådan ser grænsefladen ud — den inkluderer hurtigstart-eksempler og en chatpanel til at sende forespørgsler: AI Agent Tools Interface -*AI Agent Tools-grænsefladen – hurtige eksempler og chatinterface til interaktion med værktøjer* +*AI Agent Tools-grænsefladen - hurtige eksempler og chatinterface til interaktion med værktøjer* -### Prøv Enkel Brug af Værktøjer +### Prøv simpel brug af værktøjer -Start med en simpel forespørgsel: "Konverter 100 grader Fahrenheit til Celsius". Agenten genkender, at den skal bruge temperaturkonverteringsværktøjet, kalder det med de rette parametre og returnerer resultatet. Bemærk, hvor naturligt det føles – du specificerede ikke, hvilket værktøj der skulle bruges eller hvordan det skulle kaldes. +Start med en enkel forespørgsel: "Konvertér 100 grader Fahrenheit til Celsius". Agenten genkender, at den skal bruge temperaturkonverteringsværktøjet, kalder det med de rette parametre og returnerer resultatet. Bemærk, hvor naturligt det føles – du specificerede ikke hvilket værktøj, der skulle bruges, eller hvordan det skulle kaldes. -### Test Kædning af Værktøjer +### Test værktøjskædning -Prøv nu noget mere komplekst: "Hvad er vejret i Seattle og konverter det til Fahrenheit?" Se hvordan agenten arbejder trin for trin. Den henter først vejret (som returnerer Celsius), genkender behovet for at konvertere til Fahrenheit, kalder konverteringsværktøjet og kombinerer begge resultater i et svar. +Prøv nu noget mere komplekst: "Hvordan er vejret i Seattle, og konvertér det til Fahrenheit?" Se agenten arbejde i trin. Den henter først vejret (som returnerer Celsius), genkender, at den skal konvertere til Fahrenheit, kalder konverteringsværktøjet og kombinerer begge resultater til ét svar. -### Se Samtale Flow +### Se samtaleflow -Chatinterfacet bevarer samtalehistorikken, så du kan have flertrins-interaktioner. Du kan se alle tidligere forespørgsler og svar, hvilket gør det nemt at følge samtalen og forstå, hvordan agenten bygger kontekst over flere udvekslinger. +Chatinterfacet gemmer samtalehistorik, så du kan have flertrinsinteraktioner. Du kan se alle tidligere forespørgsler og svar, hvilket gør det let at følge samtalen og forstå, hvordan agenten opbygger kontekst gennem flere udvekslinger. Conversation with Multiple Tool Calls -*Flertrins-samtale, der viser simple konverteringer, vejropslag og kædning af værktøjer* +*Flertrins-samtale som viser simple konverteringer, vejropslag og værktøjskædning* -### Eksperimentér med Forskellige Forespørgsler +### Eksperimenter med forskellige forespørgsler Prøv forskellige kombinationer: - Vejropslag: "Hvordan er vejret i Tokyo?" - Temperaturkonverteringer: "Hvad er 25°C i Kelvin?" -- Kombinerede forespørgsler: "Tjek vejret i Paris og fortæl om det er over 20°C" +- Kombinerede forespørgsler: "Tjek vejret i Paris og fortæl mig, om det er over 20°C" -Bemærk, hvordan agenten fortolker naturligt sprog og oversætter det til relevante værktøjskald. +Bemærk, hvordan agenten fortolker naturligt sprog og omformer det til passende værktøjskald. -## Centrale Begreber +## Nøglebegreber -### ReAct Mønster (Resonering og Handling) +### ReAct-mønster (Resonnering og Handling) -Agenten skifter mellem at ræsonnere (beslutte hvad der skal gøres) og handle (bruge værktøjer). Dette mønster muliggør autonom problemløsning i stedet for bare at svare på instruktioner. +Agenten skifter mellem resonnering (beslutte hvad der skal gøres) og handling (bruge værktøjer). Dette mønster muliggør autonom problemløsning i stedet for blot at svare på instruktioner. -### Værktøjsbeskrivelser Betyr +### Værktøjsbeskrivelser er vigtige -Kvaliteten af dine værktøjsbeskrivelser påvirker direkte, hvor godt agenten bruger dem. Klare, specifikke beskrivelser hjælper modellen med at forstå hvornår og hvordan hvert værktøj skal kaldes. +Kvaliteten af dine værktøjsbeskrivelser påvirker direkte, hvor godt agenten bruger dem. Klare og præcise beskrivelser hjælper modellen med at forstå, hvornår og hvordan hvert værktøj skal kaldes. ### Sessionsstyring -`@MemoryId`-annotationen muliggør automatisk sessionsbaseret hukommelsesstyring. Hver session-ID får sin egen `ChatMemory`-instans styret af `ChatMemoryProvider`-bean, så flere brugere kan interagere samtidigt uden at deres samtaler blandes. Følgende diagram viser, hvordan flere brugere rutes til isolerede hukommelseslagre baseret på deres session-ID’er: +`@MemoryId`-annoteringen muliggør automatisk sessionbaseret hukommelsesstyring. Hvert sessions-ID får sin egen `ChatMemory`-instans, der håndteres af `ChatMemoryProvider`-bean'en, så flere brugere kan interagere med agenten samtidigt uden at deres samtaler blandes sammen. Følgende diagram viser, hvordan flere brugere dirigeres til isolerede hukommelseslager baseret på deres sessions-ID'er: Session Management with @MemoryId -*Hver session-ID svarer til en isoleret samtalehistorik — brugerne ser aldrig hinandens beskeder.* +*Hvert sessions-ID svarer til en isoleret samtalehistorik — brugere ser aldrig hinandens beskeder.* ### Fejlhåndtering -Værktøjer kan fejle — API’er timeout, parametre kan være ugyldige, eksterne tjenester går ned. Produktionsagenter har brug for fejlhåndtering, så modellen kan forklare problemer eller prøve alternativer i stedet for at få hele applikationen til at gå ned. Når et værktøj kaster en undtagelse, fanger LangChain4j den og sender fejlbeskeden tilbage til modellen, som kan forklare problemet i naturligt sprog. +Værktøjer kan fejle — API'er kan timeout'e, parametre kan være ugyldige, eksterne tjenester kan gå ned. Produktionsagenter har brug for fejlhåndtering, så modellen kan forklare problemer eller prøve alternativer i stedet for at få hele applikationen til at crashe. Når et værktøj kaster en undtagelse, fanger LangChain4j den og sender fejlbeskeden tilbage til modellen, som så kan forklare problemet i naturligt sprog. -## Tilgængelige Værktøjer +## Tilgængelige værktøjer -Diagrammet nedenfor viser det brede økosystem af værktøjer, du kan bygge. Dette modul demonstrerer vejr- og temperaturværktøjer, men det samme `@Tool`-mønster fungerer for enhver Java-metode — fra databaseforespørgsler til betalingsbehandling. +Diagrammet nedenfor viser det brede økosystem af værktøjer, du kan bygge. Denne modul demonstrerer vejrudsigts- og temperaturværktøjer, men det samme `@Tool`-mønster fungerer for enhver Java-metode — fra databaseforespørgsler til betalingsbehandling. Tool Ecosystem -*Enhver Java-metode annoteret med @Tool bliver tilgængelig for AI’en — mønstret gælder også for databaser, API’er, e-mail, filoperationer og mere.* +*Enhver Java-metode annoteret med @Tool bliver tilgængelig for AI — mønsteret rækker til databaser, API'er, e-mail, filoperationer og meget mere.* -## Hvornår Skal Man Bruge Værktøjsbaserede Agenter +## Hvornår skal man bruge værktøjsbaserede agenter -Ikke alle forespørgsler behøver værktøjer. Beslutningen handler om, hvorvidt AI’en skal interagere med eksterne systemer, eller om den kan svare ud fra sin egen viden. Følgende guide opsummerer, hvornår værktøjer tilfører værdi, og hvornår de er unødvendige: +Ikke alle forespørgsler kræver værktøjer. Beslutningen afhænger af, om AI'en skal interagere med eksterne systemer eller kan svare ud fra sin egen viden. Følgende guide opsummerer, hvornår værktøjer tilfører værdi, og hvornår de ikke er nødvendige: When to Use Tools @@ -363,25 +363,25 @@ Ikke alle forespørgsler behøver værktøjer. Beslutningen handler om, hvorvidt ## Værktøjer vs RAG -Modulerne 03 og 04 udvider begge, hvad AI’en kan, men på fundamentalt forskellige måder. RAG giver modellen adgang til **viden** ved at hente dokumenter. Værktøjer giver modellen evnen til at tage **handlinger** ved at kalde funktioner. Diagrammet nedenfor sammenligner de to tilgange side om side — fra hvordan hvert workflow fungerer til kompromiserne mellem dem: +Moduler 03 og 04 udvider begge AI'ens kapacitet, men på fundamentalt forskellige måder. RAG giver modellen adgang til **viden** ved at hente dokumenter. Værktøjer giver modellen mulighed for at udføre **handlinger** ved at kalde funktioner. Diagrammet nedenfor sammenligner disse to tilgange side om side — fra hvordan hver workflow fungerer til afvejningerne mellem dem: Tools vs RAG Comparison *RAG henter information fra statiske dokumenter — Værktøjer udfører handlinger og henter dynamiske, realtidsdata. Mange produktionssystemer kombinerer begge.* -I praksis kombinerer mange produktionssystemer begge tilgange: RAG til at forankre svar i din dokumentation, og Værktøjer til at hente live data eller udføre operationer. +I praksis kombinerer mange produktionssystemer begge tilgange: RAG til at forankre svar i din dokumentation og Værktøjer til at hente live-data eller udføre operationer. -## Næste Skridt +## Næste skridt -**Næste Modul:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Næste modul:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**Navigation:** [← Forrige: Modul 03 - RAG](../03-rag/README.md) | [Tilbage til Hovedmenu](../README.md) | [Næste: Modul 05 - MCP →](../05-mcp/README.md) +**Navigation:** [← Forrige: Modul 03 - RAG](../03-rag/README.md) | [Tilbage til hoved](../README.md) | [Næste: Modul 05 - MCP →](../05-mcp/README.md) --- **Ansvarsfraskrivelse**: -Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, bedes du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det oprindelige dokument på originalsproget bør betragtes som den autoritative kilde. For vigtig information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. +Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. \ No newline at end of file diff --git a/translations/da/README.md b/translations/da/README.md index 052682888..5a378e389 100644 --- a/translations/da/README.md +++ b/translations/da/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j for begyndere +# LangChain4j for Begyndere Et kursus til at bygge AI-applikationer med LangChain4j og Azure OpenAI GPT-5.2, fra grundlæggende chat til AI-agenter. -### 🌐 Understøttelse af flere sprog +### 🌐 Fler-sprog understøttelse #### Understøttet via GitHub Action (Automatiseret & Altid Opdateret) -[Arabisk](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarsk](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Kinesisk (Forenklet)](../zh-CN/README.md) | [Kinesisk (Traditionelt, Hong Kong)](../zh-HK/README.md) | [Kinesisk (Traditionelt, Macau)](../zh-MO/README.md) | [Kinesisk (Traditionelt, Taiwan)](../zh-TW/README.md) | [Kroatisk](../hr/README.md) | [Tjekkisk](../cs/README.md) | [Dansk](./README.md) | [Hollandsk](../nl/README.md) | [Estisk](../et/README.md) | [Finsk](../fi/README.md) | [Fransk](../fr/README.md) | [Tysk](../de/README.md) | [Græsk](../el/README.md) | [Hebraisk](../he/README.md) | [Hindi](../hi/README.md) | [Ungarsk](../hu/README.md) | [Indonesisk](../id/README.md) | [Italiensk](../it/README.md) | [Japansk](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Koreansk](../ko/README.md) | [Litauisk](../lt/README.md) | [Malayisk](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalesisk](../ne/README.md) | [Nigeriansk Pidgin](../pcm/README.md) | [Norsk](../no/README.md) | [Persisk (Farsi)](../fa/README.md) | [Polsk](../pl/README.md) | [Portugisisk (Brasilien)](../pt-BR/README.md) | [Portugisisk (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Rumænsk](../ro/README.md) | [Russisk](../ru/README.md) | [Serbisk (Kyrillisk)](../sr/README.md) | [Slovakisk](../sk/README.md) | [Slovensk](../sl/README.md) | [Spansk](../es/README.md) | [Swahili](../sw/README.md) | [Svensk](../sv/README.md) | [Tagalog (Filippinsk)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Tyrkisk](../tr/README.md) | [Ukrainsk](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamesisk](../vi/README.md) +[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](./README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) > **Foretrækker du at klone lokalt?** > -> Dette repository indeholder over 50 sprogoversættelser, hvilket væsentligt øger downloadstørrelsen. For at klone uden oversættelser, brug sparse checkout: +> Dette repository inkluderer 50+ sprogoversættelser, hvilket markant øger downloadstørrelsen. For at klone uden oversættelser skal du bruge sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,64 +29,63 @@ Et kursus til at bygge AI-applikationer med LangChain4j og Azure OpenAI GPT-5.2, > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Dette giver dig alt hvad du behøver for at gennemføre kurset med en meget hurtigere download. +> Dette giver dig alt, hvad du behøver for at gennemføre kurset med en meget hurtigere download. ## Indholdsfortegnelse -1. [Hurtig Start](00-quick-start/README.md) - Kom i gang med LangChain4j -2. [Introduktion](01-introduction/README.md) - Lær de grundlæggende principper for LangChain4j -3. [Prompt Engineering](02-prompt-engineering/README.md) - Mestring af effektiv promptdesign -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Byg intelligente vidensbaserede systemer -5. [Værktøjer](04-tools/README.md) - Integrer eksterne værktøjer og simple assistenter -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Arbejd med Model Context Protocol (MCP) og Agentic moduler +1. [Introduktion](01-introduction/README.md) - Lær grundlæggende om LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Mestre effektiv promptdesign +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Byg intelligente vidensbaserede systemer +4. [Værktøjer](04-tools/README.md) - Integrer eksterne værktøjer og simple assistenter +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Arbejd med Model Context Protocol (MCP) og Agentiske moduler -### Video Gennemgange +### Videogenveje -Hvert modul har en ledsagende live-session, hvor vi gennemgår koncepter og kode trin for trin. +Hvert modul har en ledsagende live session, hvor vi gennemgår koncepterne og koden trin for trin. | Modul | Video | |--------|-------| | 01 - Introduktion | [Kom godt i gang med LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - Prompt Engineering | [Prompt Engineering med LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG med LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Værktøjer & 05 - MCP | [AI Agenter med værktøjer og MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Værktøjer & 05 - MCP | [AI-agenter med værktøjer og MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Læringsvej +## Læringssti -**Ny til LangChain4j?** Tjek [Glossaret](docs/GLOSSARY.md) for definitioner af nøgleord og begreber. +**Ny til LangChain4j?** Se [Glossaret](docs/GLOSSARY.md) for definitioner af nøglebegreber og koncepter. -> **Hurtig Start** +> **Hurtig start** 1. Fork dette repository til din GitHub-konto -2. Klik på **Code** → fanen **Codespaces** → **...** → **New with options...** -3. Brug standardindstillingerne – dette vælger udviklingscontaineren oprettet for dette kursus -4. Klik på **Create codespace** -5. Vent 5-10 minutter på, at miljøet er klar -6. Spring direkte til [Hurtig Start](./00-quick-start/README.md) for at komme i gang! +2. Klik **Code** → fanen **Codespaces** → **...** → **New with options...** +3. Brug standardindstillingerne – dette vælger Development containeren, der er oprettet til dette kursus +4. Klik **Create codespace** +5. Vent 5-10 minutter, indtil miljøet er klar +6. Gå direkte til [Introduktion](./01-introduction/README.md) for at komme i gang! -Efter gennemførelse af modulerne, udforsk [Testvejledningen](docs/TESTING.md) for at se LangChain4j testkoncepter i praksis. +Efter at have gennemført modulerne, kan du udforske [Testningsguide](docs/TESTING.md) for at se LangChain4j testkoncepter i praksis. -> **Bemærk:** Denne træning bruger både GitHub Models og Azure OpenAI. [Hurtig Start](00-quick-start/README.md) modulet bruger GitHub Models (ingen Azure-abonnement kræves), mens moduler 1-5 bruger Azure OpenAI. Kom i gang med en [GRATIS Azure-konto](https://aka.ms/azure-free-account), hvis du ikke har en. +> **Bemærk:** Denne træning bruger Azure OpenAI. Kom i gang med en [GRATIS Azure-konto](https://aka.ms/azure-free-account), hvis du ikke har en. ## Læring med GitHub Copilot -For hurtigt at komme i gang med at kode, åbn dette projekt i en GitHub Codespace eller dit lokale IDE med den medfølgende devcontainer. Devcontaineren brugt i dette kursus kommer forudkonfigureret med GitHub Copilot til AI parprogrammering. +For hurtigt at komme i gang med kodning, åbn dette projekt i en GitHub Codespace eller din lokale IDE med den leverede devcontainer. Devcontaineren brugt i dette kursus kommer forudkonfigureret med GitHub Copilot til AI-parprogrammering. -Hvert kodeeksempel indeholder foreslåede spørgsmål, du kan stille GitHub Copilot for at uddybe din forståelse. Kig efter 💡/🤖 prompts i: +Hvert kodeeksempel inkluderer foreslåede spørgsmål, du kan stille GitHub Copilot for at uddybe din forståelse. Hold øje med 💡/🤖 prompts i: -- **Java-filoverskrifter** - Spørgsmål specifikt til hvert eksempel -- **Modul READMEs** - Udforskningsforslag efter kodeeksempler +- **Java-filoverskrifter** - Spørgsmål specifikke for hvert eksempel +- **Modul-README'er** - Udforskningsprompter efter kodeeksempler -**Sådan bruger du det:** Åbn en hvilken som helst kodefil og stil Copilot de foreslåede spørgsmål. Den har fuld kontekst af kodebasen og kan forklare, udvide og foreslå alternativer. +**Hvordan bruges det:** Åbn en hvilken som helst kodefil og stil Copilot de foreslåede spørgsmål. Den har fuld kontekst af kodebasen og kan forklare, udvide og foreslå alternativer. -Vil du lære mere? Se [Copilot for AI Paired Programming](https://aka.ms/GitHubCopilotAI). +Vil du lære mere? Se [Copilot for AI Parprogrammering](https://aka.ms/GitHubCopilotAI). -## Yderligere ressourcer +## Yderligere Ressourcer ### LangChain @@ -111,18 +110,19 @@ Vil du lære mere? Se [Copilot for AI Paired Programming](https://aka.ms/GitHubC --- -### Kerneuddannelse +### Kerne Læring [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Copilot-serien +### Copilot-serie [![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) @@ -130,11 +130,11 @@ Vil du lære mere? Se [Copilot for AI Paired Programming](https://aka.ms/GitHubC ## Få hjælp -Hvis du går i stå eller har spørgsmål om at bygge AI-apps, så tilmeld dig: +Hvis du sidder fast eller har spørgsmål om at bygge AI-apps, så deltag: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Hvis du har produktfeedback eller fejl under bygning, så besøg: +Hvis du har feedback på produktet eller oplever fejl under opbygning, besøg: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) @@ -145,6 +145,6 @@ MIT-licens - Se [LICENSE](../../LICENSE) filen for detaljer. --- -**Ansvarsfraskrivelse**: -Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, bedes du være opmærksom på, at automatiske oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritiske oplysninger anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. +**Ansvarsfraskrivelse**: +Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. \ No newline at end of file diff --git a/translations/da/docs/GLOSSARY.md b/translations/da/docs/GLOSSARY.md index 2449d702f..4fd2435b0 100644 --- a/translations/da/docs/GLOSSARY.md +++ b/translations/da/docs/GLOSSARY.md @@ -1,44 +1,44 @@ -# LangChain4j Ordliste +# LangChain4j Ordlist ## Indholdsfortegnelse -- [Kernekoncepter](../../../docs) -- [LangChain4j Komponenter](../../../docs) -- [AI/ML Koncepter](../../../docs) -- [Guardrails](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agenter og Værktøjer](../../../docs) -- [Agentic Modul](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure Services](../../../docs) -- [Testning og Udvikling](../../../docs) +- [Kernebegreber](#kernebegreber) +- [LangChain4j Komponenter](#langchain4j-komponenter) +- [AI/ML Begreber](#aiml-begreber) +- [Sikkerhedsspærrer](#sikkerhedsspærrer) +- [Prompt Engineering](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agenter og Værktøjer](#agents-and-tools---module-04) +- [Agentisk Modul](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure Tjenester](#azure-services---module-01) +- [Test og Udvikling](#testing-and-development---testing-guide) -Hurtig reference for termer og koncepter brugt gennem kurset. +Hurtig reference for termer og begreber brugt gennem hele kurset. -## Kernekoncepter +## Kernebegreber -**AI Agent** - System, der bruger AI til at resonnere og handle autonomt. [Modul 04](../04-tools/README.md) +**AI Agent** - System der bruger AI til at ræsonnere og handle autonomt. [Modul 04](../04-tools/README.md) -**Chain** - Sekvens af operationer hvor output føres videre til næste trin. +**Chain** - Sekvens af operationer hvor output føres ind i næste trin. -**Chunking** - At opdele dokumenter i mindre stykker. Typisk: 300-500 tokens med overlap. [Modul 03](../03-rag/README.md) +**Chunking** - Opdeling af dokumenter i mindre stykker. Typisk: 300-500 tokens med overlap. [Modul 03](../03-rag/README.md) -**Context Window** - Maksimalt antal tokens et model kan behandle. GPT-5.2: 400K tokens (op til 272K input, 128K output). +**Context Window** - Maksimalt antal tokens en model kan behandle. GPT-5.2: 400K tokens (op til 272K input, 128K output). **Embeddings** - Numeriske vektorer der repræsenterer teksts betydning. [Modul 03](../03-rag/README.md) -**Function Calling** - Model genererer strukturerede forespørgsler for at kalde eksterne funktioner. [Modul 04](../04-tools/README.md) +**Function Calling** - Model genererer strukturerede forespørgsler til at kalde eksterne funktioner. [Modul 04](../04-tools/README.md) -**Hallucination** - Når modeller genererer ukorrekte men plausible oplysninger. +**Hallucination** - Når modeller genererer ukorrekt, men plausibel information. **Prompt** - Tekstinput til en sprogmodel. [Modul 02](../02-prompt-engineering/README.md) -**Semantic Search** - Søgning baseret på mening ved hjælp af embeddings, ikke nøgleord. [Modul 03](../03-rag/README.md) +**Semantic Search** - Søgning efter betydning vha. embeddings, ikke nøgleord. [Modul 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: ingen hukommelse. Stateful: bevarer samtalehistorik. [Modul 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: ingen hukommelse. Stateful: opretholder samtalehistorik. [Modul 01](../01-introduction/README.md) -**Tokens** - Grundlæggende tekstenheder modeller behandler. Påvirker omkostninger og begrænsninger. [Modul 01](../01-introduction/README.md) +**Tokens** - Grundlæggende tekst-enheder modeller behandler. Påvirker omkostninger og begrænsninger. [Modul 01](../01-introduction/README.md) **Tool Chaining** - Sekventiel udførelse af værktøjer hvor output informerer næste kald. [Modul 04](../04-tools/README.md) @@ -46,91 +46,91 @@ Hurtig reference for termer og koncepter brugt gennem kurset. **AiServices** - Opretter type-sikre AI service interfaces. -**OpenAiOfficialChatModel** - Fælles klient til OpenAI og Azure OpenAI modeller. +**OpenAiOfficialChatModel** - Unified klient til OpenAI og Azure OpenAI modeller. -**OpenAiOfficialEmbeddingModel** - Opretter embeddings ved brug af OpenAI Official klient (understøtter både OpenAI og Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Opretter embeddings med OpenAI Official klient (understøtter både OpenAI og Azure OpenAI). -**ChatModel** - Kerneinterface til sprogmodeller. +**ChatModel** - Kerneinterface for sprogmodeller. -**ChatMemory** - Bevarer samtalehistorik. +**ChatMemory** - Opretholder samtalehistorik. -**ContentRetriever** - Finder relevante dokumentstykker til RAG. +**ContentRetriever** - Finder relevante dokumentudsnit til RAG. **DocumentSplitter** - Opdeler dokumenter i stykker. -**EmbeddingModel** - Omformer tekst til numeriske vektorer. +**EmbeddingModel** - Konverterer tekst til numeriske vektorer. **EmbeddingStore** - Gemmer og henter embeddings. -**MessageWindowChatMemory** - Bevarer glidende vindue af nylige beskeder. +**MessageWindowChatMemory** - Opretholder glidende vindue af seneste beskeder. **PromptTemplate** - Opretter genanvendelige prompts med `{{variable}}` pladsholdere. **TextSegment** - Tekststykke med metadata. Bruges i RAG. -**ToolExecutionRequest** - Repræsenterer anmodning om udførelse af værktøj. +**ToolExecutionRequest** - Repræsenterer værktøjsudførelsesanmodning. -**UserMessage / AiMessage / SystemMessage** - Samtaletypemeddelelser. +**UserMessage / AiMessage / SystemMessage** - Samtale beskedtyper. -## AI/ML Koncepter +## AI/ML Begreber -**Few-Shot Learning** - At give eksempler i prompts. [Modul 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Tilvejebringer eksempler i prompts. [Modul 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - AI modeller trænet på store mængder tekstdata. +**Large Language Model (LLM)** - AI modeller trænet på enorm tekstdata. **Reasoning Effort** - GPT-5.2 parameter der styrer tænkedybde. [Modul 02](../02-prompt-engineering/README.md) -**Temperature** - Styrer outputtilfældighed. Lav=deterministisk, høj=kreativ. +**Temperature** - Styrer output-tilfældighed. Lav=deterministisk, høj=kreativ. **Vector Database** - Specialiseret database til embeddings. [Modul 03](../03-rag/README.md) -**Zero-Shot Learning** - Udfør opgaver uden eksempler. [Modul 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Udfører opgaver uden eksempler. [Modul 02](../02-prompt-engineering/README.md) -## Guardrails - [Modul 00](../00-quick-start/README.md) +## Sikkerhedsspærrer -**Defense in Depth** - Flerlags sikkerhedstilgang der kombinerer applikationsniveau guardrails med safety-filtre fra udbyder. +**Defense in Depth** - Flerlags sikkerhedstilgang der kombinerer applikationsniveau sikkerhedsspærrer med providersikkerhedsfiltre. -**Hard Block** - Udbyder returnerer HTTP 400 fejl for alvorlige indholdsbrud. +**Hard Block** - Provider kaster HTTP 400 fejl ved alvorlige indholdsbrud. -**InputGuardrail** - LangChain4j interface til validering af brugerinput, før det når LLM. Sparrer omkostninger og latenstid ved at blokere skadelige prompts tidligt. +**InputGuardrail** - LangChain4j interface til validering af brugerinput før det når LLM. Sparrer omkostninger og latenstid ved tidligt at blokere skadelige prompts. -**InputGuardrailResult** - Returtype for guardrail validering: `success()` eller `fatal("årsag")`. +**InputGuardrailResult** - Returneringstype for sikkerhedsspærrevalidering: `success()` eller `fatal("grund")`. -**OutputGuardrail** - Interface til validering af AI-svar før de returneres til brugere. +**OutputGuardrail** - Interface til validering af AI-svar før returnering til brugere. -**Provider Safety Filters** - Indbyggede indholdsfiltre fra AI-udbydere (f.eks. GitHub Models) der fanger overtrædelser på API-niveau. +**Provider Safety Filters** - Indbyggede indholdsfiltre fra AI-udbydere (fx Azure OpenAI) der fanger overtrædelser på API-niveau. **Soft Refusal** - Model afviser høfligt at svare uden at kaste fejl. ## Prompt Engineering - [Modul 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Trinvis tankegang for bedre præcision. +**Chain-of-Thought** - Trinvis ræsonnering for bedre nøjagtighed. **Constrained Output** - Håndhæver specifikt format eller struktur. -**High Eagerness** - GPT-5.2 mønster for grundig tænkning. +**High Eagerness** - GPT-5.2 mønster til grundig ræsonnering. -**Low Eagerness** - GPT-5.2 mønster for hurtige svar. +**Low Eagerness** - GPT-5.2 mønster til hurtige svar. -**Multi-Turn Conversation** - Bevarer kontekst på tværs af udvekslinger. +**Multi-Turn Conversation** - Opretholder kontekst på tværs af udvekslinger. -**Role-Based Prompting** - Indstiller modelperson via systembeskeder. +**Role-Based Prompting** - Indstiller modelpersona via systembeskeder. **Self-Reflection** - Model evaluerer og forbedrer sit output. -**Structured Analysis** - Fast evalueringsramme. +**Structured Analysis** - Fastsat evalueringsramme. -**Task Execution Pattern** - Planlæg → Udfør → Opsummér. +**Task Execution Pattern** - Plan → Udfør → Opsummer. ## RAG (Retrieval-Augmented Generation) - [Modul 03](../03-rag/README.md) -**Document Processing Pipeline** - Indlæs → del i stykker → embed → gem. +**Document Processing Pipeline** - Indlæs → opdel → embed → gem. -**In-Memory Embedding Store** - Ikke-persistent lager til test. +**In-Memory Embedding Store** - Ikke-permanent lagring til test. -**RAG** - Kombinerer genfinding med generering for at underbygge svar. +**RAG** - Kombinerer søgning med generering for at forankre svar. -**Similarity Score** - Mål (0-1) for semantisk lighed. +**Similarity Score** - Mål (0-1) af semantisk lighed. **Source Reference** - Metadata om hentet indhold. @@ -138,95 +138,93 @@ Hurtig reference for termer og koncepter brugt gennem kurset. **@Tool Annotation** - Marker Java metoder som AI-kaldbare værktøjer. -**ReAct Pattern** - Resonner → Handl → Observer → Gentag. +**ReAct Pattern** - Tænk → Handle → Observer → Gentag. -**Session Management** - Separate kontekster til forskellige brugere. +**Session Management** - Separate kontekster for forskellige brugere. -**Tool** - Funktion som en AI agent kan kalde. +**Tool** - Funktion en AI-agent kan kalde. **Tool Description** - Dokumentation af værktøjets formål og parametre. -## Agentic Modul - [Modul 05](../05-mcp/README.md) +## Agentisk Modul - [Modul 05](../05-mcp/README.md) -**@Agent Annotation** - Marker interfaces som AI agenter med deklarativ adfærdsdefinition. +**@Agent Annotation** - Marker interfaces som AI-agenter med deklarativ adfærdsdefinition. -**Agent Listener** - Hook til overvågning af agentudførelse via `beforeAgentInvocation()` og `afterAgentInvocation()`. +**Agent Listener** - Krog til overvågning af agentudførelse via `beforeAgentInvocation()` og `afterAgentInvocation()`. -**Agentic Scope** - Delt hukommelse hvor agenter gemmer output med `outputKey` til videre forbrug af andre agenter. +**Agentic Scope** - Delt hukommelse hvor agenter gemmer output med `outputKey` til efterfølgende agenter. -**AgenticServices** - Fabrik til oprettelse af agenter via `agentBuilder()` og `supervisorBuilder()`. +**AgenticServices** - Fabrik til at skabe agenter via `agentBuilder()` og `supervisorBuilder()`. **Conditional Workflow** - Rute baseret på betingelser til forskellige specialistagenter. -**Human-in-the-Loop** - Arbejdsgangsmønster der tilføjer menneskelige kontrolpunkter til godkendelse eller indholdsrevision. +**Human-in-the-Loop** - Arbejdsgangsmønster der tilføjer menneskelige tjekpunkter til godkendelse eller indholdsrevision. -**langchain4j-agentic** - Maven afhængighed for deklarativ agentopbygning (eksperimentel). +**langchain4j-agentic** - Maven-afhængighed til deklarativ agentbygning (eksperimentel). -**Loop Workflow** - Iterer agentudførelse indtil en betingelse er opfyldt (f.eks. kvalitets score ≥ 0.8). +**Loop Workflow** - Iterér agentudførelse indtil en betingelse er opfyldt (fx kvalitetsscore ≥ 0.8). -**outputKey** - Agent annotation parameter der angiver hvor resultater gemmes i Agentic Scope. +**outputKey** - Agentannoteringsparameter der angiver hvor resultater gemmes i Agentic Scope. **Parallel Workflow** - Kør flere agenter samtidigt til uafhængige opgaver. -**Response Strategy** - Hvordan supervisor formulerer endeligt svar: LAST, SUMMARY, eller SCORED. +**Response Strategy** - Hvordan supervisor formulerer endeligt svar: LAST, SUMMARY eller SCORED. **Sequential Workflow** - Udfør agenter i rækkefølge hvor output flyder til næste trin. -**Supervisor Agent Pattern** - Avanceret agentmønster hvor en supervisor LLM dynamisk beslutter hvilke sub-agenter der skal påkaldes. +**Supervisor Agent Pattern** - Avanceret agentisk mønster hvor en supervisor LLM dynamisk beslutter hvilke underagenter der skal kaldes. ## Model Context Protocol (MCP) - [Modul 05](../05-mcp/README.md) -**langchain4j-mcp** - Maven afhængighed til MCP integration i LangChain4j. +**langchain4j-mcp** - Maven-afhængighed til MCP integration i LangChain4j. -**MCP** - Model Context Protocol: standard for tilslutning af AI-apps til eksterne værktøjer. Byg én gang, brug alle steder. +**MCP** - Model Context Protocol: standard for at forbinde AI apps til eksterne værktøjer. Byg én gang, brug overalt. -**MCP Client** - Applikation der forbinder til MCP servere for at finde og bruge værktøjer. +**MCP Client** - Applikation der forbinder til MCP servere for at opdage og bruge værktøjer. -**MCP Server** - Tjeneste der eksponerer værktøjer via MCP med klare beskrivelser og parameterskemaer. +**MCP Server** - Service der eksponerer værktøjer via MCP med klare beskrivelser og parameterskemaer. -**McpToolProvider** - LangChain4j komponent der indpakker MCP værktøjer til brug i AI services og agenter. +**McpToolProvider** - LangChain4j komponent der indkapsler MCP værktøjer til brug i AI tjenester og agenter. **McpTransport** - Interface til MCP kommunikation. Implementeringer inkluderer Stdio og HTTP. -**Stdio Transport** - Lokal proces transport via stdin/stdout. Brugbar til filsystemadgang eller kommandolinjeværktøjer. +**Stdio Transport** - Lokal procestransport via stdin/stdout. Nyttig til filsystemadgang eller kommandolinjeværktøjer. -**StdioMcpTransport** - LangChain4j implementering der starter MCP server som subprocess. +**StdioMcpTransport** - LangChain4j implementering der starter MCP server som underproces. -**Tool Discovery** - Klient spørger server efter tilgængelige værktøjer med beskrivelser og skemaer. +**Tool Discovery** - Client spørger server om tilgængelige værktøjer med beskrivelser og skemaer. -## Azure Services - [Modul 01](../01-introduction/README.md) +## Azure Tjenester - [Modul 01](../01-introduction/README.md) -**Azure AI Search** - Cloud søgning med vektor kapabiliteter. [Modul 03](../03-rag/README.md) +**Azure AI Search** - Cloud-søgning med vektor kapabiliteter. [Modul 03](../03-rag/README.md) **Azure Developer CLI (azd)** - Udruller Azure ressourcer. **Azure OpenAI** - Microsofts enterprise AI service. -**Bicep** - Azure infrastruktur-som-kode sprog. [Infrastructure Guide](../01-introduction/infra/README.md) +**Bicep** - Azure infra-as-code sprog. [Infrastructure Guide](../01-introduction/infra/README.md) -**Deployment Name** - Navn for modeludrulning i Azure. +**Deployment Name** - Navn til modeludrulning i Azure. -**GPT-5.2** - Nyeste OpenAI model med styring af ræsonnering. [Modul 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Seneste OpenAI model med ræsonneringskontrol. [Modul 02](../02-prompt-engineering/README.md) -## Testning og Udvikling - [Testguide](TESTING.md) +## Test og Udvikling - [Testing Guide](TESTING.md) **Dev Container** - Containeriseret udviklingsmiljø. [Konfiguration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Gratis AI model legeplads. [Modul 00](../00-quick-start/README.md) +**In-Memory Testing** - Test med in-memory lagring. -**In-Memory Testing** - Test med hukommelseslager. +**Integration Testing** - Test med ægte infrastruktur. -**Integration Testing** - Test med rigtig infrastruktur. - -**Maven** - Java build automatiseringsværktøj. +**Maven** - Java byggeautomatiseringsværktøj. **Mockito** - Java mocking framework. -**Spring Boot** - Java applikationsramme. [Modul 01](../01-introduction/README.md) +**Spring Boot** - Java applikationsframework. [Modul 01](../01-introduction/README.md) --- -**Ansvarsfraskrivelse**: -Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, bedes du være opmærksom på, at automatiske oversættelser kan indeholde fejl eller unøjagtigheder. Det oprindelige dokument på dets modersmål skal betragtes som den autoritative kilde. For kritiske oplysninger anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for eventuelle misforståelser eller fejltolkninger som følge af brugen af denne oversættelse. +**Ansvarsfraskrivelse**: +Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. \ No newline at end of file diff --git a/translations/da/docs/TESTING.md b/translations/da/docs/TESTING.md index 694e598ae..33d49bbd7 100644 --- a/translations/da/docs/TESTING.md +++ b/translations/da/docs/TESTING.md @@ -2,17 +2,17 @@ ## Indholdsfortegnelse -- [Hurtig start](../../../docs) -- [Hvad testene dækker](../../../docs) -- [Kørsel af testene](../../../docs) -- [Kørsel af tests i VS Code](../../../docs) -- [Testmønstre](../../../docs) -- [Testfilosofi](../../../docs) -- [Næste skridt](../../../docs) +- [Kom godt i gang](#kom-godt-i-gang) +- [Hvad testene dækker](#hvad-testene-dækker) +- [Kørsel af testene](#kørsel-af-testene) +- [Kørsel af tests i VS Code](#kørsel-af-tests-i-vs-code) +- [Testmønstre](#testmønstre) +- [Testfilosofi](#testfilosofi) +- [Næste skridt](#næste-skridt) -Denne vejledning gennemgår testene, som demonstrerer, hvordan man tester AI-applikationer uden at kræve API-nøgler eller eksterne tjenester. +Denne vejledning guider dig igennem de tests, der viser, hvordan man tester AI-applikationer uden at skulle bruge API-nøgler eller eksterne tjenester. -## Hurtig start +## Kom godt i gang Kør alle test med en enkelt kommando: @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Når alle test er bestået, bør du se output som skærmbilledet nedenfor — testene kører med nul fejl. +Når alle tests er bestået, skulle du se output som skærmbilledet herunder — test kørt uden fejl. Successful Test Results -*Vellykket testkørsel, der viser alle test bestået med nul fejl* +*Succesfuld testkørsel, der viser alle tests bestået uden fejl* ## Hvad testene dækker -Dette kursus fokuserer på **unittest** der kører lokalt. Hver test demonstrerer et specifikt LangChain4j-koncept isoleret. Testpyramiden nedenfor viser, hvor unittest passer ind — de udgør det hurtige, pålidelige fundament, som resten af din teststrategi bygger på. +Dette kursus fokuserer på **unittest**, der køres lokalt. Hver test demonstrerer et specifikt LangChain4j-koncept isoleret. Testpyramiden nedenfor viser, hvor unittest passer ind — de udgør det hurtige, pålidelige fundament, som resten af din teststrategi bygger på. Testing Pyramid -*Testpyramide, der viser balancen mellem unittest (hurtig, isoleret), integrationstest (rigtige komponenter) og end-to-end test. Denne træning dækker unittest.* +*Testpyramide, der viser balancen mellem unittest (hurtige, isolerede), integrationstests (reelle komponenter) og end-to-end tests. Denne træning dækker unittest.* -| Modul | Tests | Fokus | Nøglefiler | +| Modul | Tests | Fokus | Vigtige filer | |--------|-------|-------|-----------| -| **00 - Hurtig start** | 6 | Prompt-skabeloner og variabeludskiftning | `SimpleQuickStartTest.java` | -| **01 - Introduktion** | 8 | Samtalehukommelse og stateful chat | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | GPT-5.2 mønstre, iver-niveauer, struktureret output | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Dokumentindtag, embeddings, lighedssøgning | `DocumentServiceTest.java` | -| **04 - Værktøjer** | 12 | Funktionskald og værktøjskæder | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol med Stdio transport | `SimpleMcpTest.java` | +| **01 - Introduktion** | 8 | Samtalehukommelse og tilstandsbaseret chat | `SimpleConversationTest.java` | +| **02 - Prompt Engineering** | 12 | GPT-5.2 mønstre, ivrighedsniveauer, struktureret output | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Dokumentindtagelse, embedding, lighedssøgning | `DocumentServiceTest.java` | +| **04 - Værktøjer** | 12 | Funktionsopkald og kædning af værktøjer | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol med Stdio-transport | `SimpleMcpTest.java` | ## Kørsel af testene -**Kør alle test fra rodmappen:** +**Kør alle tests fra rodmappen:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Kør test for et specifikt modul:** +**Kør tests for et specifikt modul:** **Bash:** ```bash @@ -75,7 +74,7 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Eller fra roden +# Eller fra rod mvn --% test -pl 01-introduction ``` @@ -95,7 +94,7 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#skalVedligeholdeSamtaleHistorik +mvn test -Dtest=SimpleConversationTest#børBevareSamtaleHistorik ``` **PowerShell:** @@ -105,31 +104,31 @@ mvn --% test -Dtest=SimpleConversationTest#skalBevareSamtalehistorik ## Kørsel af tests i VS Code -Hvis du bruger Visual Studio Code, tilbyder Test Explorer en grafisk grænseflade til at køre og debugge test. +Hvis du bruger Visual Studio Code, giver Test Explorer en grafisk brugerflade til at køre og debugge tests. VS Code Test Explorer *VS Code Test Explorer, der viser testtræet med alle Java testklasser og individuelle testmetoder* -**Sådan kører du test i VS Code:** +**For at køre tests i VS Code:** -1. Åbn Test Explorer ved at klikke på bægerikonet i aktivitetsbjælken +1. Åbn Test Explorer ved at klikke på kolbeikonet i aktivitetsbjælken 2. Udvid testtræet for at se alle moduler og testklasser -3. Klik på afspilningsknappen ved siden af en test for at køre den enkeltvist -4. Klik "Run All Tests" for at køre hele sæt -5. Højreklik på en test og vælg "Debug Test" for at sætte breakpoint og køre trinvis gennem koden +3. Klik på afspilningsknappen ved siden af en test for at køre den individuelt +4. Klik på "Run All Tests" for at køre hele pakken +5. Højreklik på en test og vælg "Debug Test" for at sætte breakpoints og køre trinvis -Test Explorer viser grønne flueben for beståede test og giver detaljerede fejlmeddelelser, når test fejler. +Test Explorer viser grønne flueben for beståede tests og giver detaljerede fejlmeddelelser ved fejl. ## Testmønstre -### Mønster 1: Test af prompt-skabeloner +### Mønster 1: Test af promptskabeloner -Det simpleste mønster tester prompt-skabeloner uden at kalde et AI-model. Du verificerer, at variabeludskiftning fungerer korrekt, og at prompts formatteres som forventet. +Det simpleste mønster tester promptskabeloner uden at kalde nogen AI-model. Du verificerer, at variabeludskiftning fungerer korrekt, og at prompts er formateret som forventet. Prompt Template Testing -*Test af prompt-skabeloner, der viser flowet: skabelon med pladsholdere → værdier anvendt → formatteret output verificeret* +*Test af promptskabeloner, der viser variabelsubstitutionsflow: skabelon med pladsholdere → værdier anvendt → formateret output verificeret* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Denne test findes i `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Kør den:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testPromptSkabelonFormatering -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptSkabelonFormatering -``` +Dette mønster bekræfter, at variabeludskiftning fungerer korrekt, og at prompts er formateret som forventet — uden brug af API-nøgle eller modelkald. ### Mønster 2: Mocking af sprogmodeller -Når du tester samtale-logik, brug Mockito til at lave falske modeller, der returnerer forudbestemte svar. Det gør test hurtige, gratis og deterministiske. +Når du tester samtalelogik, brug Mockito til at skabe falske modeller, der returnerer forudbestemte svar. Det gør testene hurtige, gratis og deterministiske. Mock vs Real API Comparison -*Sammenligning der viser, hvorfor mocks foretrækkes til test: de er hurtige, gratis, deterministiske og kræver ingen API-nøgler* +*Sammenligning, der viser hvorfor mocks foretrækkes til test: de er hurtige, gratis, deterministiske og kræver ingen API-nøgler* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Dette mønster findes i `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock'en sikrer ensartet adfærd, så du kan verificere, at hukommelsesstyringen fungerer korrekt. +Dette mønster findes i `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mocket sikrer konsistent opførsel, så du kan verificere, at hukommelsesadministration fungerer korrekt. -### Mønster 3: Test af samtale-isolation +### Mønster 3: Test af samtaleisolation -Samtalehukommelse skal holde flere brugere adskilt. Denne test verificerer, at samtaler ikke blander kontekster. +Samtalehukommelsen må holde flere brugere adskilt. Denne test verificerer, at samtaler ikke blander kontekster. Conversation Isolation -*Test af samtale-isolation, der viser separate hukommelsesenheder for forskellige brugere for at forhindre kontekstblanding* +*Test af samtaleisolation, der viser separate hukommelseslagre for forskellige brugere for at forhindre kontekstblanding* ```java @Test @@ -250,7 +237,7 @@ void shouldIsolateConversationsByid() { } ``` -Hver samtale opretholder sin egen uafhængige historik. I produktionssystemer er denne isolation kritisk for multi-bruger applikationer. +Hver samtale opretholder sin egen uafhængige historik. I produktionssystemer er denne isolation afgørende for multi-bruger applikationer. ### Mønster 4: Test af værktøjer uafhængigt @@ -258,7 +245,7 @@ Værktøjer er funktioner, som AI kan kalde. Test dem direkte for at sikre, at d Tools Testing -*Test af værktøjer uafhængigt, der viser mock-kørsel af værktøj uden AI-kald for at verificere forretningslogik* +*Test af værktøjer uafhængigt, der viser mock-værktøjseksekvering uden AI-kald for at verificere forretningslogik* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Disse test fra `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validerer værktøjslogik uden AI-involvering. Kædningseksemplet viser, hvordan output fra ét værktøj føres som input til et andet. +Disse tests fra `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validerer værktøjslogik uden AI-involvering. Eksemplet med kædning viser, hvordan output fra ét værktøj føres videre som input til et andet. -### Mønster 5: In-Memory RAG-test +### Mønster 5: In-Memory RAG test -RAG-systemer kræver traditionelt vektordatabaser og embedding-tjenester. In-memory mønsteret lader dig teste hele pipeline uden eksterne afhængigheder. +RAG-systemer kræver traditionelt vektor-databaser og embeddingtjenester. In-memory-mønsteret lader dig teste hele pipeline uden eksterne afhængigheder. In-Memory RAG Testing -*In-memory RAG-testarbejdsgang, der viser dokument-parsing, embedningslagring, og lighedssøgning uden krav om database* +*In-memory RAG test workflow, der viser dokumentparsing, embedding-lagring og lighedssøgning uden krav om database* ```java @Test @@ -306,11 +293,11 @@ void testProcessTextDocument() { } ``` -Denne test fra `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` opretter et dokument i hukommelsen og verificerer chunking og håndtering af metadata. +Denne test fra `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` opretter et dokument i hukommelsen og verificerer chunking og metadatahåndtering. -### Mønster 6: MCP integrations-test +### Mønster 6: MCP Integrationstest -MCP-modulet tester Model Context Protocol integration ved brug af stdio-transport. Disse test verificerer, at din applikation kan starte og kommunikere med MCP-servere som subprocesser. +MCP-modulet tester Model Context Protocol-integration via stdio-transport. Disse tests verificerer, at din applikation kan starte og kommunikere med MCP-servere som underprocesser. Testene i `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validerer MCP-klientadfærd. @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## Testfilosofi -Test din kode, ikke AI'en. Dine test bør validere den kode, du skriver, ved at tjekke, hvordan prompts konstrueres, hvordan hukommelse håndteres, og hvordan værktøjer eksekveres. AI-svar varierer og bør ikke være en del af testcase-assertioner. Spørg dig selv, om din prompt-skabelon korrekt erstatter variabler, ikke om AI giver det rigtige svar. +Test din kode, ikke AI’en. Dine tests skal validere den kode, du skriver ved at undersøge, hvordan prompts konstrueres, hvordan hukommelse håndteres, og hvordan værktøjer eksekveres. AI-svar varierer og bør ikke være en del af testpåstande. Spørg dig selv, om din promptskabelon korrekt substituerer variabler, ikke om AI giver det rigtige svar. -Brug mocks til sprogmodeller. De er eksterne afhængigheder, som er langsomme, dyre og ikke-deterministiske. Mocking gør test hurtige i millisekunder i stedet for sekunder, gratis uden API-omkostninger og deterministiske med samme resultat hver gang. +Brug mocks til sprogmodeller. De er eksterne afhængigheder, som er langsomme, dyre og ikke-deterministiske. Mocking gør tests hurtige med millisekunder i stedet for sekunder, gratis uden API-omkostninger, og deterministiske med samme resultat hver gang. -Hold test uafhængige. Hver test bør opsætte sine egne data, ikke afhænge af andre tests, og rydde op efter sig selv. Test bør bestå uanset rækkefølge af udførelse. +Hold tests uafhængige. Hver test bør opsætte sine egne data, ikke være afhængig af andre tests og rydde op efter sig selv. Tests bør bestå uanset kørselsrækkefølge. -Test kanttilfælde ud over den gode vej. Prøv tomme input, meget store input, specialtegn, ugyldige parametre og grænsebetingelser. Disse afslører ofte fejl, som normal brug ikke afdækker. +Test kanttilfælde ud over den lykkelige vej. Prøv tomme inputs, meget store inputs, specialtegn, ugyldige parametre og grænsetilstande. Disse afslører ofte fejl, som normal brug ikke udsætter. -Brug beskrivende navne. Sammenlign `shouldMaintainConversationHistoryAcrossMultipleMessages()` med `test1()`. Det første fortæller dig præcis, hvad der testes, hvilket gør fejlfinding meget nemmere. +Brug beskrivende navne. Sammenlign `shouldMaintainConversationHistoryAcrossMultipleMessages()` med `test1()`. Det første fortæller dig præcist, hvad der testes, hvilket gør fejlretning meget nemmere. ## Næste skridt -Nu hvor du forstår testmønstrene, dyk dybere ned i hvert modul: +Nu hvor du forstår testmønstrene, kan du dykke dybere ned i hvert modul: -- **[00 - Hurtig start](../00-quick-start/README.md)** - Begynd med prompt-skabelon grundlæggende -- **[01 - Introduktion](../01-introduction/README.md)** - Lær samtalehukommelsesstyring -- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Mestre GPT-5.2 promptmønstre -- **[03 - RAG](../03-rag/README.md)** - Byg retrieval-augmented generation systemer +- **[01 - Introduktion](../01-introduction/README.md)** - Lær styring af samtalehukommelse +- **[02 - Prompt Engineering](../02/prompt-engineering/README.md)** - Mestre GPT-5.2 promptmønstre +- **[03 - RAG](../03-rag/README.md)** - Byg retrival-augmented generation systemer - **[04 - Værktøjer](../04-tools/README.md)** - Implementér funktionskald og værktøjskæder - **[05 - MCP](../05-mcp/README.md)** - Integrer Model Context Protocol -Hvert moduls README giver detaljerede forklaringer på de koncepter, der testes her. +Hvert moduls README giver detaljerede forklaringer af de koncepter, der testes her. --- @@ -359,5 +345,5 @@ Hvert moduls README giver detaljerede forklaringer på de koncepter, der testes **Ansvarsfraskrivelse**: -Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det oprindelige dokument på originalsproget skal betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for eventuelle misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. +Dette dokument er blevet oversat ved hjælp af AI-oversættelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selvom vi bestræber os på nøjagtighed, skal du være opmærksom på, at automatiserede oversættelser kan indeholde fejl eller unøjagtigheder. Det originale dokument på dets oprindelige sprog bør betragtes som den autoritative kilde. For kritisk information anbefales professionel menneskelig oversættelse. Vi påtager os intet ansvar for misforståelser eller fejltolkninger, der opstår som følge af brugen af denne oversættelse. \ No newline at end of file diff --git a/translations/de/.co-op-translator.json b/translations/de/.co-op-translator.json index 0610432e2..6b3d5c9fc 100644 --- a/translations/de/.co-op-translator.json +++ b/translations/de/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "de" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T00:10:58+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T08:01:59+00:00", "source_file": "01-introduction/README.md", "language_code": "de" }, @@ -18,20 +18,20 @@ "language_code": "de" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T00:12:48+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T07:57:37+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "de" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T00:13:59+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T08:01:05+00:00", "source_file": "03-rag/README.md", "language_code": "de" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T12:02:53+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T07:59:48+00:00", "source_file": "04-tools/README.md", "language_code": "de" }, @@ -54,8 +54,8 @@ "language_code": "de" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:54:58+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T07:56:17+00:00", "source_file": "README.md", "language_code": "de" }, @@ -72,14 +72,14 @@ "language_code": "de" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T00:16:32+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T07:58:05+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "de" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T00:17:09+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T07:58:36+00:00", "source_file": "docs/TESTING.md", "language_code": "de" } diff --git a/translations/de/00-quick-start/README.md b/translations/de/00-quick-start/README.md deleted file mode 100644 index 92020cd39..000000000 --- a/translations/de/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modul 00: Schnellstart - -## Inhaltsverzeichnis - -- [Einführung](../../../00-quick-start) -- [Was ist LangChain4j?](../../../00-quick-start) -- [LangChain4j Abhängigkeiten](../../../00-quick-start) -- [Voraussetzungen](../../../00-quick-start) -- [Einrichtung](../../../00-quick-start) - - [1. Holen Sie sich Ihren GitHub-Token](../../../00-quick-start) - - [2. Setzen Sie Ihren Token](../../../00-quick-start) -- [Führen Sie die Beispiele aus](../../../00-quick-start) - - [1. Basic Chat](../../../00-quick-start) - - [2. Prompt-Muster](../../../00-quick-start) - - [3. Funktionsaufruf](../../../00-quick-start) - - [4. Dokumenten Q&A (Easy RAG)](../../../00-quick-start) - - [5. Verantwortungsbewusste KI](../../../00-quick-start) -- [Was jedes Beispiel zeigt](../../../00-quick-start) -- [Nächste Schritte](../../../00-quick-start) -- [Fehlerbehebung](../../../00-quick-start) - -## Einführung - -Dieser Schnellstart soll Ihnen helfen, LangChain4j so schnell wie möglich zum Laufen zu bringen. Er behandelt die absoluten Grundlagen des Aufbaus von KI-Anwendungen mit LangChain4j und GitHub Models. In den nächsten Modulen wechseln Sie zu Azure OpenAI und GPT-5.2 und gehen tiefer auf jedes Konzept ein. - -## Was ist LangChain4j? - -LangChain4j ist eine Java-Bibliothek, die das Erstellen von KI-gestützten Anwendungen vereinfacht. Anstatt mit HTTP-Clients und JSON-Parsing zu arbeiten, verwenden Sie reine Java-APIs. - -Die „Chain“ in LangChain bezieht sich darauf, mehrere Komponenten zu verketten – Sie können zum Beispiel eine Eingabeaufforderung mit einem Modell und einem Parser verbinden oder mehrere KI-Aufrufe aneinanderreihen, bei denen eine Ausgabe als Eingabe für den nächsten Schritt dient. Dieser Schnellstart konzentriert sich auf die Grundlagen, bevor komplexere Ketten erkundet werden. - -LangChain4j Verkettungskonzept - -*Verkettung von Komponenten in LangChain4j – Bausteine verbinden sich, um leistungsstarke KI-Workflows zu erstellen* - -Wir verwenden drei Kernkomponenten: - -**ChatModel** – Die Schnittstelle für KI-Modell-Interaktionen. Rufen Sie `model.chat("prompt")` auf und erhalten Sie eine Antwort als String. Wir verwenden `OpenAiOfficialChatModel`, das mit OpenAI-kompatiblen Endpunkten wie GitHub Models funktioniert. - -**AiServices** – Erstellt typsichere KI-Service-Schnittstellen. Definieren Sie Methoden, annotieren Sie sie mit `@Tool` und LangChain4j übernimmt die Orchestrierung. Die KI ruft Ihre Java-Methoden automatisch auf, wenn nötig. - -**MessageWindowChatMemory** – Hält den Gesprächsverlauf aufrecht. Ohne dies ist jede Anfrage unabhängig. Damit erinnert sich die KI an vorherige Nachrichten und behält den Kontext über mehrere Runden. - -LangChain4j Architektur - -*LangChain4j Architektur – Kernkomponenten arbeiten zusammen, um Ihre KI-Anwendungen anzutreiben* - -## LangChain4j Abhängigkeiten - -Dieser Schnellstart verwendet drei Maven-Abhängigkeiten in der [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Das `langchain4j-open-ai-official`-Modul stellt die Klasse `OpenAiOfficialChatModel` bereit, die mit OpenAI-kompatiblen APIs kommuniziert. GitHub Models verwendet dasselbe API-Format, daher ist kein spezieller Adapter erforderlich – Sie müssen nur die Basis-URL auf `https://models.github.ai/inference` setzen. - -Das `langchain4j-easy-rag`-Modul bietet automatisches Dokumenten-Splitting, Einbettung und Recherche, sodass Sie RAG-Anwendungen bauen können, ohne jeden Schritt manuell konfigurieren zu müssen. - -## Voraussetzungen - -**Verwenden Sie den Dev Container?** Java und Maven sind bereits installiert. Sie benötigen nur einen persönlichen GitHub Access Token. - -**Lokale Entwicklung:** -- Java 21+, Maven 3.9+ -- Persönlicher GitHub Access Token (Anleitung unten) - -> **Hinweis:** Dieses Modul verwendet `gpt-4.1-nano` von GitHub Models. Ändern Sie den Modellnamen im Code nicht – er ist konfiguriert für die verfügbaren GitHub-Modelle. - -## Einrichtung - -### 1. Holen Sie sich Ihren GitHub-Token - -1. Gehen Sie zu [GitHub Einstellungen → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Klicken Sie auf „Generate new token“ -3. Geben Sie einen beschreibenden Namen ein (z. B. „LangChain4j Demo“) -4. Legen Sie ein Ablaufdatum fest (7 Tage empfohlen) -5. Unter „Account permissions“ suchen Sie „Models“ und setzen es auf „Read-only“ -6. Klicken Sie auf „Generate token“ -7. Kopieren und speichern Sie Ihren Token – Sie sehen ihn nicht wieder - -### 2. Setzen Sie Ihren Token - -**Option 1: Verwendung von VS Code (Empfohlen)** - -Wenn Sie VS Code verwenden, fügen Sie Ihren Token zur `.env`-Datei im Projektstammverzeichnis hinzu: - -Falls die `.env`-Datei nicht existiert, kopieren Sie `.env.example` nach `.env` oder erstellen Sie eine neue `.env`-Datei im Projektstammverzeichnis. - -**Beispiel `.env`-Datei:** -```bash -# In /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Danach können Sie einfach mit der rechten Maustaste auf eine beliebige Demo-Datei (z. B. `BasicChatDemo.java`) im Explorer klicken und **„Run Java“** auswählen oder die Startkonfigurationen aus dem Ausführen- und Debug-Panel verwenden. - -**Option 2: Verwendung des Terminals** - -Setzen Sie den Token als Umgebungsvariable: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Führen Sie die Beispiele aus - -**Verwendung von VS Code:** Klicken Sie einfach mit der rechten Maustaste auf eine beliebige Demo-Datei im Explorer und wählen Sie **„Run Java“** oder verwenden Sie die Startkonfigurationen im Ausführen- und Debug-Panel (stellen Sie sicher, dass Sie Ihren Token zuerst in die `.env`-Datei eingetragen haben). - -**Verwendung von Maven:** Alternativ können Sie die Beispiele auch über die Kommandozeile ausführen: - -### 1. Basic Chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Prompt-Muster - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Zeigt zero-shot, few-shot, Chain-of-thought und rollenbasierte Aufforderungen. - -### 3. Funktionsaufruf - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -Die KI ruft Ihre Java-Methoden automatisch auf, wenn notwendig. - -### 4. Dokumenten Q&A (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Stellen Sie Fragen zu Ihren Dokumenten mit Easy RAG, inklusive automatischer Einbettung und Recherche. - -### 5. Verantwortungsbewusste KI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Sehen Sie, wie KI-Sicherheitsfilter schädliche Inhalte blockieren. - -## Was jedes Beispiel zeigt - -**Basic Chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Beginnen Sie hier, um LangChain4j in seiner einfachsten Form zu sehen. Sie erstellen ein `OpenAiOfficialChatModel`, senden eine Eingabeaufforderung mit `.chat()` und erhalten eine Antwort. Dies demonstriert die Grundlage: wie man Modelle mit benutzerdefinierten Endpunkten und API-Schlüsseln initialisiert. Sobald Sie dieses Muster verstanden haben, baut alles Weitere darauf auf. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) und fragen Sie: -> - „Wie wechsle ich in diesem Code von GitHub Models zu Azure OpenAI?“ -> - „Welche weiteren Parameter kann ich in OpenAiOfficialChatModel.builder() konfigurieren?“ -> - „Wie füge ich Streaming-Antworten hinzu, anstatt auf die vollständige Antwort zu warten?“ - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Jetzt, da Sie wissen, wie Sie mit einem Modell sprechen, sehen wir uns an, was Sie ihm sagen. Diese Demo verwendet dieselbe Modellkonfiguration, zeigt aber fünf verschiedene Prompt-Muster. Probieren Sie Zero-Shot-Prompts für direkte Anweisungen, Few-Shot-Prompts, die aus Beispielen lernen, Chain-of-Thought-Prompts, die den Denkprozess offenlegen, und rollenbasierte Prompts, die den Kontext setzen. Sie sehen, wie dasselbe Modell dramatisch unterschiedliche Ergebnisse liefert, je nachdem, wie Sie Ihre Anfrage formulieren. - -Die Demo zeigt auch Prompt-Templates, ein kraftvolles Werkzeug, um wiederverwendbare Prompts mit Variablen zu erstellen. -Das folgende Beispiel zeigt ein Prompt unter Verwendung der LangChain4j `PromptTemplate`, um Variablen auszufüllen. Die KI antwortet basierend auf dem angegebenen Reiseziel und der Aktivität. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) und fragen Sie: -> - „Was ist der Unterschied zwischen Zero-Shot und Few-Shot Prompting, und wann verwende ich welches?“ -> - „Wie beeinflusst der Temperaturparameter die Antworten des Modells?“ -> - „Welche Techniken gibt es, um Prompt Injection Angriffe in der Produktion zu verhindern?“ -> - „Wie erstelle ich wiederverwendbare PromptTemplate-Objekte für gängige Muster?“ - -**Tool Integration** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Hier wird LangChain4j mächtig. Sie verwenden `AiServices`, um einen KI-Assistenten zu erstellen, der Ihre Java-Methoden aufrufen kann. Annotieren Sie Methoden einfach mit `@Tool("Beschreibung")` und LangChain4j übernimmt den Rest – die KI entscheidet automatisch, welches Tool wann genutzt wird, basierend auf der Nutzeranfrage. Das demonstriert Funktionsaufrufe, eine Schlüsseltechnik zum Aufbau von KI, die handeln kann, nicht nur Fragen beantwortet. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) und fragen Sie: -> - „Wie funktioniert die @Tool-Annotation und was macht LangChain4j damit hinter den Kulissen?“ -> - „Kann die KI mehrere Tools nacheinander aufrufen, um komplexe Probleme zu lösen?“ -> - „Was passiert, wenn ein Tool eine Ausnahme wirft – wie sollte ich Fehler behandeln?“ -> - „Wie würde ich eine echte API anstelle dieses Taschenrechner-Beispiels integrieren?“ - -**Dokumenten Q&A (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Hier sehen Sie RAG (retrieval-augmented generation) mit LangChain4js "Easy RAG" Ansatz. Dokumente werden geladen, automatisch aufgeteilt und in einem In-Memory-Speicher eingebettet, dann liefert ein Content-Retriever relevante Ausschnitte zur Anfragezeit an die KI. Die KI antwortet basierend auf Ihren Dokumenten, nicht auf ihrem allgemeinen Wissen. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) und fragen Sie: -> - „Wie verhindert RAG KI-Halluzinationen im Vergleich zur Nutzung der Trainingsdaten des Modells?“ -> - „Was ist der Unterschied zwischen diesem einfachen Ansatz und einer benutzerdefinierten RAG-Pipeline?“ -> - „Wie würde ich das skalieren, um mehrere Dokumente oder größere Wissensbasen zu handhaben?“ - -**Verantwortungsbewusste KI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Bauen Sie KI-Sicherheit mit einem mehrschichtigen Ansatz. Diese Demo zeigt zwei Schutzebenen, die zusammenarbeiten: - -**Teil 1: LangChain4j Input Guardrails** – Blockieren gefährlicher Prompts, bevor sie das LLM erreichen. Erstellen Sie eigene Guardrails, die auf verbotene Schlüsselwörter oder Muster prüfen. Diese laufen in Ihrem Code, sind also schnell und kostenlos. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Teil 2: Provider Safety Filters** – GitHub Models verfügt über integrierte Filter, die Dinge abfangen, die Ihre Guardrails eventuell übersehen. Sie sehen harte Blockaden (HTTP 400 Fehler) für schwere Verstöße und sanfte Ablehnungen, wenn die KI höflich ablehnt. - -> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) und fragen Sie: -> - „Was ist InputGuardrail und wie erstelle ich meine eigenen?“ -> - „Was ist der Unterschied zwischen einer harten Blockade und einer sanften Ablehnung?“ -> - „Warum verwendet man Guardrails und Provider-Filter zusammen?“ - -## Nächste Schritte - -**Nächstes Modul:** [01-introduction - Erste Schritte mit LangChain4j](../01-introduction/README.md) - ---- - -**Navigation:** [← Zurück zur Hauptseite](../README.md) | [Weiter: Modul 01 - Einführung →](../01-introduction/README.md) - ---- - -## Fehlerbehebung - -### Erster Maven-Build - -**Problem**: Erster `mvn clean compile` oder `mvn package` dauert lange (10-15 Minuten) - -**Ursache**: Maven muss alle Projektabhängigkeiten (Spring Boot, LangChain4j-Bibliotheken, Azure SDKs usw.) beim ersten Build herunterladen. - -**Lösung**: Das ist normales Verhalten. Nachfolgende Builds sind deutlich schneller, da die Abhängigkeiten lokal zwischengespeichert werden. Die Downloadzeit hängt von Ihrer Netzwerkgeschwindigkeit ab. - -### PowerShell Maven-Befehls-Syntax - -**Problem**: Maven-Befehle schlagen fehl mit dem Fehler `Unknown lifecycle phase ".mainClass=..."` -**Ursache**: PowerShell interpretiert `=` als Zuweisungsoperator, wodurch die Maven-Eigenschaftssyntax unterbrochen wird - -**Lösung**: Verwenden Sie den Stop-Parsing-Operator `--%` vor dem Maven-Befehl: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Der Operator `--%` weist PowerShell an, alle verbleibenden Argumente wörtlich an Maven weiterzugeben, ohne sie zu interpretieren. - -### Emoji-Anzeige in Windows PowerShell - -**Problem**: KI-Antworten zeigen unlesbare Zeichen (z.B. `????` oder `â??`) anstelle von Emojis in PowerShell - -**Ursache**: Die Standardcodierung von PowerShell unterstützt keine UTF-8 Emojis - -**Lösung**: Führen Sie diesen Befehl vor dem Ausführen von Java-Anwendungen aus: -```cmd -chcp 65001 -``` - -Dies erzwingt die UTF-8-Codierung im Terminal. Alternativ können Sie Windows Terminal verwenden, das eine bessere Unicode-Unterstützung bietet. - -### Debugging von API-Aufrufen - -**Problem**: Authentifizierungsfehler, Ratenbegrenzungen oder unerwartete Antworten vom KI-Modell - -**Lösung**: Die Beispiele enthalten `.logRequests(true)` und `.logResponses(true)`, um API-Aufrufe in der Konsole anzuzeigen. Dies hilft, Authentifizierungsfehler, Ratenbegrenzungen oder unerwartete Antworten zu diagnostizieren. Entfernen Sie diese Flags in der Produktion, um die Protokollierung zu reduzieren. - ---- - - -**Haftungsausschluss**: -Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir um Genauigkeit bemüht sind, kann diese automatisierte Übersetzung Fehler oder Ungenauigkeiten enthalten. Das Originaldokument in seiner Originalsprache ist als maßgebliche Quelle anzusehen. Für kritische Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Nutzung dieser Übersetzung entstehen. - \ No newline at end of file diff --git a/translations/de/01-introduction/README.md b/translations/de/01-introduction/README.md index 4e05334ad..3bc0a3c2d 100644 --- a/translations/de/01-introduction/README.md +++ b/translations/de/01-introduction/README.md @@ -1,43 +1,43 @@ -# Modul 01: Einstieg mit LangChain4j +# Modul 01: Einstieg in LangChain4j ## Inhaltsverzeichnis -- [Video-Durchgang](../../../01-introduction) -- [Was Sie lernen werden](../../../01-introduction) -- [Voraussetzungen](../../../01-introduction) -- [Das Kernproblem verstehen](../../../01-introduction) -- [Tokens verstehen](../../../01-introduction) -- [Wie Speicher funktioniert](../../../01-introduction) -- [Wie dies LangChain4j verwendet](../../../01-introduction) -- [Azure OpenAI-Infrastruktur bereitstellen](../../../01-introduction) -- [Anwendung lokal ausführen](../../../01-introduction) -- [Die Anwendung verwenden](../../../01-introduction) - - [Zustandsloser Chat (linkes Panel)](../../../01-introduction) - - [Zustandsbehafteter Chat (rechtes Panel)](../../../01-introduction) -- [Nächste Schritte](../../../01-introduction) +- [Video-Durchgang](#video-durchgang) +- [Was Sie lernen werden](#was-sie-lernen-werden) +- [Voraussetzungen](#voraussetzungen) +- [Verständnis des Kernproblems](#verständnis-des-kernproblems) +- [Verständnis von Tokens](#verständnis-von-tokens) +- [Wie Speicher funktioniert](#wie-speicher-funktioniert) +- [Wie dies LangChain4j nutzt](#wie-dies-langchain4j-nutzt) +- [Bereitstellen der Azure OpenAI Infrastruktur](#bereitstellen-der-azure-openai-infrastruktur) +- [Anwendung lokal ausführen](#anwendung-lokal-ausführen) +- [Verwendung der Anwendung](#verwendung-der-anwendung) + - [Zustandsloser Chat (linkes Panel)](#zustandsloser-chat-linkes-panel) + - [Zustandsbehafteter Chat (rechtes Panel)](#zustandsbehafteter-chat-rechtes-panel) +- [Nächste Schritte](#nächste-schritte) ## Video-Durchgang Sehen Sie sich diese Live-Session an, die erklärt, wie Sie mit diesem Modul starten: -Einstieg mit LangChain4j - Live-Session +Einstieg in LangChain4j - Live-Session ## Was Sie lernen werden -Im Quickstart haben Sie GitHub-Modelle verwendet, um Prompts zu senden, Werkzeuge aufzurufen, eine RAG-Pipeline zu bauen und Guardrails zu testen. Diese Demos zeigten, was möglich ist – jetzt wechseln wir zu Azure OpenAI und GPT-5.2 und beginnen damit, produktionsähnliche Anwendungen zu entwickeln. Dieses Modul konzentriert sich auf konversationelle KI, die Kontext behält und Zustände verwaltet – die Konzepte, die in den Quickstart-Demos hinter den Kulissen genutzt, aber nicht erklärt wurden. +Dies ist Ihr Einstiegspunkt mit LangChain4j und Azure OpenAI. Wir beginnen mit den Grundlagen und bauen produktionsähnliche Anwendungen. Dieses Modul konzentriert sich auf konversationelle KI, die den Kontext merkt und den Zustand beibehält – die grundlegenden Konzepte, auf denen alle späteren Module aufbauen. -Wir verwenden während dieses Leitfadens Azure OpenAIs GPT-5.2, da seine fortgeschrittenen Fähigkeiten im logischen Denken das Verhalten der verschiedenen Muster deutlicher machen. Wenn Sie Speicher hinzufügen, sehen Sie den Unterschied klar. Das erleichtert das Verständnis dessen, was jede Komponente Ihrer Anwendung bringt. +Wir verwenden im gesamten Leitfaden Azure OpenAI's GPT-5.2, da dessen fortschrittliche Analysefähigkeiten das Verhalten verschiedener Muster besser sichtbar machen. Wenn Sie Speicher hinzufügen, sehen Sie den Unterschied deutlich. So verstehen Sie leichter, was jede Komponente zu Ihrer Anwendung beiträgt. -Sie werden eine Anwendung bauen, die beide Muster demonstriert: +Sie erstellen eine Anwendung, die beide Muster demonstriert: -**Zustandsloser Chat** - Jede Anfrage ist unabhängig. Das Modell hat kein Gedächtnis für vorherige Nachrichten. Dies ist das Muster, das Sie im Quickstart verwendet haben. +**Zustandsloser Chat** – Jede Anfrage ist unabhängig. Das Modell hat kein Gedächtnis vorheriger Nachrichten. Dies ist der einfachste Einstiegspunkt. -**Zustandsbehaftete Konversation** - Jede Anfrage beinhaltet die Gesprächshistorie. Das Modell behält den Kontext über mehrere Interaktionen hinweg. Dies ist das, was produktive Anwendungen benötigen. +**Zustandsbehaftete Unterhaltung** – Jede Anfrage beinhaltet Konversationsverlauf. Das Modell behält Kontext über mehrere Gesprächsrunden. Dies ist für produktionsreife Anwendungen notwendig. ## Voraussetzungen -- Azure-Abonnement mit Azure OpenAI-Zugriff -- Java 21, Maven 3.9+ +- Azure-Abonnement mit Azure OpenAI Zugriff +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) @@ -45,41 +45,41 @@ Sie werden eine Anwendung bauen, die beide Muster demonstriert: > **Hinweis:** Dieses Modul verwendet GPT-5.2 auf Azure OpenAI. Die Bereitstellung wird automatisch über `azd up` konfiguriert – ändern Sie den Modellnamen im Code nicht. -## Das Kernproblem verstehen +## Verständnis des Kernproblems -Sprachmodelle sind zustandslos. Jeder API-Aufruf ist unabhängig. Wenn Sie „Mein Name ist John“ senden und dann fragen „Wie heißt mein Name?“, hat das Modell keine Ahnung, dass Sie sich gerade vorgestellt haben. Es behandelt jede Anfrage, als wäre es das erste Gespräch, das Sie je geführt haben. +Sprachmodelle sind zustandslos. Jeder API-Aufruf ist unabhängig. Wenn Sie "Mein Name ist John" schicken und dann fragen "Wie heißt mein Name?", hat das Modell keine Ahnung, dass Sie sich gerade vorgestellt haben. Es behandelt jede Anfrage, als sei es das erste Gespräch, das Sie je geführt haben. -Das ist für einfache Q&A okay, aber für echte Anwendungen unbrauchbar. Kundendienstbots müssen sich merken, was Sie ihnen gesagt haben. Persönliche Assistenten brauchen Kontext. Jede mehrstufige Konversation erfordert Speicher. +Das ist für einfache Q&A okay, aber nutzlos für echte Anwendungen. Kundenservice-Bots müssen sich erinnern, was Sie ihnen gesagt haben. Persönliche Assistenten brauchen Kontext. Jede Unterhaltung mit mehreren Runden erfordert Speicher. -Die folgende Grafik stellt die beiden Ansätze gegenüber – links ein zustandsloser Aufruf, der Ihren Namen vergisst; rechts ein zustandsbehafteter Aufruf, unterstützt von ChatMemory, der ihn sich merkt. +Das folgende Diagramm vergleicht die beiden Ansätze – links ein zustandsloser Aufruf, der Ihren Namen vergisst; rechts ein zustandsbehafteter Aufruf mit ChatMemory, das sich daran erinnert. -Zustandslose vs. Zustandsbehaftete Konversationen +Zustandslose versus zustandsbehaftete Unterhaltungen -*Der Unterschied zwischen zustandslosen (unabhängigen Anfragen) und zustandsbehafteten (kontextbewussten) Konversationen* +*Der Unterschied zwischen zustandslosen (unabhängigen Aufrufen) und zustandsbehafteten (kontextbewussten) Unterhaltungen* -## Tokens verstehen +## Verständnis von Tokens -Bevor wir in Konversationen eintauchen, ist es wichtig, Tokens zu verstehen – die Grundeinheiten des Textes, die Sprachmodelle verarbeiten: +Bevor wir in Unterhaltungen eintauchen, ist es wichtig, Tokens zu verstehen – die grundlegenden Einheiten von Text, die Sprachmodelle verarbeiten: Token-Erklärung *Beispiel, wie Text in Tokens zerlegt wird – „I love AI!“ wird zu 4 separaten Verarbeitungseinheiten* -Tokens sind die Maßeinheiten, mit denen KI-Modelle Text messen und verarbeiten. Wörter, Satzzeichen und sogar Leerzeichen können Tokens sein. Ihr Modell hat ein Limit, wie viele Tokens es auf einmal verarbeiten kann (400.000 bei GPT-5.2, mit bis zu 272.000 Eingabe-Tokens und 128.000 Ausgabe-Tokens). Tokens zu verstehen hilft Ihnen, Gesprächslänge und Kosten zu verwalten. +Tokens sind die Maßeinheit, mit der KI-Modelle Text messen und verarbeiten. Wörter, Satzzeichen und sogar Leerzeichen können Tokens sein. Ihr Modell hat ein Limit, wie viele Tokens es gleichzeitig verarbeiten kann (400.000 bei GPT-5.2, mit bis zu 272.000 Eingabe- und 128.000 Ausgabe-Tokens). Das Verständnis der Tokens hilft, die Gesprächslänge und Kosten zu steuern. ## Wie Speicher funktioniert -Chat-Speicher löst das Zustandslosigkeitsproblem, indem er die Gesprächshistorie erhält. Bevor Ihre Anfrage an das Modell gesendet wird, fügt das Framework relevante vorherige Nachrichten hinzu. Wenn Sie fragen „Wie heißt mein Name?“, sendet das System tatsächlich die gesamte Gesprächshistorie, sodass das Modell sieht, dass Sie zuvor sagten „Mein Name ist John.“ +Chat-Speicher löst das Problem der Zustandslosigkeit, indem er den Gesprächsverlauf speichert. Bevor Ihre Anfrage an das Modell geschickt wird, fügt das Framework relevante vorherige Nachrichten voran. Wenn Sie fragen „Wie heißt mein Name?“, sendet das System tatsächlich die gesamte Gesprächshistorie, sodass das Modell sehen kann, dass Sie zuvor „Mein Name ist John“ gesagt haben. -LangChain4j bietet Speicherimplementierungen, die dies automatisch übernehmen. Sie wählen aus, wie viele Nachrichten behalten werden, und das Framework verwaltet das Kontextfenster. Die folgende Grafik zeigt, wie MessageWindowChatMemory ein gleitendes Fenster der letzten Nachrichten erhält. +LangChain4j stellt Speicherimplementierungen bereit, die das automatisch erledigen. Sie wählen, wie viele Nachrichten gespeichert werden sollen, und das Framework verwaltet das Kontextfenster. Das folgende Diagramm zeigt, wie MessageWindowChatMemory ein gleitendes Fenster der neuesten Nachrichten verwaltet. Speicherfenster-Konzept -*MessageWindowChatMemory erhält ein gleitendes Fenster mit neuesten Nachrichten und entfernt automatisch alte* +*MessageWindowChatMemory verwaltet ein gleitendes Fenster der letzten Nachrichten und entfernt automatisch ältere* -## Wie dies LangChain4j verwendet +## Wie dies LangChain4j nutzt -Dieses Modul erweitert den Quickstart durch die Integration von Spring Boot und das Hinzufügen von Gesprächsspeicher. So fügen sich die Teile zusammen: +Dieses Modul integriert Spring Boot und fügt Gesprächsspeicher hinzu. So fügen sich die Teile zusammen: **Abhängigkeiten** – Fügen Sie zwei LangChain4j-Bibliotheken hinzu: @@ -94,7 +94,7 @@ Dieses Modul erweitert den Quickstart durch die Integration von Spring Boot und ``` -**Chat-Modell** – Konfigurieren Sie Azure OpenAI als Spring-Bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chat-Modell** – Konfigurieren Sie Azure OpenAI als Spring Bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Der Builder liest Zugangsdaten aus Umgebungsvariablen, die von `azd up` gesetzt wurden. Das Setzen von `baseUrl` auf Ihren Azure-Endpunkt macht den OpenAI-Client kompatibel mit Azure OpenAI. +Der Builder liest Anmeldeinformationen aus Umgebungsvariablen, die von `azd up` gesetzt werden. Mit `baseUrl` auf Ihren Azure-Endpunkt funktioniert der OpenAI-Client mit Azure OpenAI. **Gesprächsspeicher** – Verfolgen Sie den Chat-Verlauf mit MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,39 +124,39 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Erstellen Sie Speicher mit `withMaxMessages(10)`, um die letzten 10 Nachrichten zu behalten. Fügen Sie Benutzer- und KI-Nachrichten mit typisierten Wrappern hinzu: `UserMessage.from(text)` und `AiMessage.from(text)`. Holen Sie den Verlauf mit `memory.messages()` ab und senden Sie ihn ans Modell. Der Service speichert separate Speicherinstanzen pro Gesprächs-ID, sodass mehrere Nutzer gleichzeitig chatten können. +Erstellen Sie Speicher mit `withMaxMessages(10)`, um die letzten 10 Nachrichten zu behalten. Fügen Sie Nachrichten von Nutzer und KI mit typisierten Wrappern hinzu: `UserMessage.from(text)` und `AiMessage.from(text)`. Rufen Sie den Verlauf mit `memory.messages()` ab und schicken Sie ihn ans Modell. Der Service speichert separate Speicherinstanzen pro Konversations-ID, sodass mehrere Nutzer gleichzeitig chatten können. -> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat aus:** Öffnen Sie [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) und fragen Sie: -> - „Wie entscheidet MessageWindowChatMemory, welche Nachrichten fallen gelassen werden, wenn das Fenster voll ist?“ -> - „Kann ich kundenspezifischen Speicher mittels Datenbank statt im Arbeitsspeicher implementieren?“ -> - „Wie würde ich eine Zusammenfassung hinzufügen, um alte Gesprächshistorie zu komprimieren?“ +> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) und fragen Sie: +> - „Wie entscheidet MessageWindowChatMemory, welche Nachrichten verworfen werden, wenn das Fenster voll ist?“ +> - „Kann ich eine benutzerdefinierte Speicherlösung mit Datenbank anstelle von In-Memory implementieren?“ +> - „Wie füge ich eine Zusammenfassung hinzu, um alten Gesprächsverlauf zu komprimieren?“ -Der zustandslose Chat-Endpunkt überspringt den Speicher komplett – einfach `chatModel.chat(prompt)` wie im Quickstart. Der zustandsbehaftete Endpunkt fügt Nachrichten zum Speicher hinzu, ruft den Verlauf ab und inkludiert diesen Kontext bei jeder Anfrage. Gleiche Modellkonfiguration, unterschiedliche Muster. +Der zustandslose Chat-Endpunkt überspringt Speicher völlig – einfach `chatModel.chat(prompt)` wie im Schnellstart. Der zustandsbehaftete Endpunkt fügt Nachrichten zum Speicher hinzu, ruft Verlauf ab und sendet diesen Kontext mit jeder Anfrage. Gleiche Modellkonfiguration, unterschiedliche Muster. -## Azure OpenAI-Infrastruktur bereitstellen +## Bereitstellen der Azure OpenAI Infrastruktur **Bash:** ```bash cd 01-introduction -azd up # Wählen Sie das Abonnement und den Standort aus (empfohlen wird eastus2) +azd up # Wählen Sie das Abonnement und den Standort aus (eastus2 empfohlen) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Wählen Sie das Abonnement und den Standort (eastus2 empfohlen) +azd up # Wählen Sie Abonnement und Standort (eastus2 empfohlen) ``` -> **Hinweis:** Wenn Sie einen Timeout-Fehler (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) erhalten, führen Sie einfach `azd up` erneut aus. Azure-Ressourcen sind möglicherweise noch in Bereitstellung, und ein erneuter Versuch erlaubt der Bereitstellung, abzuschließen, sobald die Ressourcen einen Endzustand erreichen. +> **Hinweis:** Wenn Sie einen Timeout-Fehler (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) erhalten, führen Sie einfach erneut `azd up` aus. Azure-Ressourcen können noch im Bereitstellungsprozess sein, und ein erneutes Ausführen ermöglicht den Abschluss, sobald sich die Ressourcen in einem Endzustand befinden. -Dies führt aus: -1. Bereitstellung der Azure OpenAI-Ressource mit GPT-5.2 und text-embedding-3-small Modellen -2. Automatische Erstellung einer `.env`-Datei im Projektstamm mit Zugangsdaten -3. Einrichtung aller erforderlichen Umgebungsvariablen +Dies wird: +1. Eine Azure OpenAI-Ressource mit GPT-5.2 und text-embedding-3-small Modellen bereitstellen +2. Automatisch eine `.env`-Datei im Projektstamm mit Zugangsdaten erzeugen +3. Alle erforderlichen Umgebungsvariablen einrichten -**Legen Sie bei Bereitstellungsproblemen los?** Lesen Sie die [Infrastructure README](infra/README.md) für detaillierte Fehlerbehebung, einschließlich Konflikten bei Subdomain-Namen, manuellen Azure Portal-Bereitstellungsschritten und Modellkonfigurationshinweisen. +**Probleme bei der Bereitstellung?** Siehe das [Infrastructure README](infra/README.md) für detaillierte Fehlerbehebung, einschließlich Konflikten mit Subdomain-Namen, manueller Azure-Portal-Bereitstellung und Modellkonfigurationshinweisen. -**Bestätigen Sie, dass die Bereitstellung erfolgreich war:** +**Überprüfen, ob die Bereitstellung erfolgreich war:** **Bash:** ```bash @@ -168,25 +168,26 @@ cat ../.env # Sollte AZURE_OPENAI_ENDPOINT, API_KEY usw. anzeigen. Get-Content ..\.env # Sollte AZURE_OPENAI_ENDPOINT, API_KEY usw. anzeigen. ``` -> **Hinweis:** Der Befehl `azd up` erzeugt automatisch die `.env`-Datei. Wenn Sie diese später aktualisieren wollen, können Sie entweder die `.env`-Datei manuell bearbeiten oder sie durch Ausführen der folgenden Befehle neu generieren: +> **Hinweis:** Der `azd up`-Befehl erzeugt die `.env`-Datei automatisch. Falls Sie diese später aktualisieren müssen, können Sie entweder die `.env`-Datei manuell bearbeiten oder sie durch Ausführen folgender Befehle neu generieren: > > **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` - +> > **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` + ## Anwendung lokal ausführen **Bereitstellung überprüfen:** -Stellen Sie sicher, dass die `.env`-Datei mit Azure-Zugangsdaten im Stammverzeichnis vorhanden ist. Führen Sie dies im Modulverzeichnis (`01-introduction/`) aus: +Stellen Sie sicher, dass die `.env`-Datei mit Azure-Zugangsdaten im Stammverzeichnis vorhanden ist. Führen Sie dies aus dem Modulverzeichnis (`01-introduction/`) aus: **Bash:** ```bash @@ -198,25 +199,26 @@ cat ../.env # Sollte AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT anzeigen Get-Content ..\.env # Sollte AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT anzeigen ``` + **Starten Sie die Anwendungen:** -**Option 1: Spring Boot Dashboard verwenden (empfohlen für VS Code Nutzer)** +**Option 1: Verwendung des Spring Boot Dashboards (empfohlen für VS Code-Nutzer)** -Der Devcontainer enthält die Spring Boot Dashboard-Erweiterung, die eine visuelle Oberfläche bietet, um alle Spring Boot-Anwendungen zu verwalten. Sie finden sie in der Aktivitätsleiste links in VS Code (Suchen Sie das Spring Boot-Symbol). +Der Devcontainer enthält die Spring Boot Dashboard-Erweiterung, die eine visuelle Schnittstelle zum Verwalten aller Spring Boot-Anwendungen bietet. Sie finden es in der Aktivitätsleiste links in VS Code (achten Sie auf das Spring Boot-Symbol). -Vom Spring Boot Dashboard aus können Sie: +Über das Spring Boot Dashboard können Sie: - Alle verfügbaren Spring Boot-Anwendungen im Workspace sehen - Anwendungen mit einem Klick starten/stoppen -- Anwendungsprotokolle in Echtzeit anzeigen -- Anwendungsstatus überwachen +- Echtzeit-Logs der Anwendungen ansehen +- Den Anwendungsstatus überwachen -Starten Sie dieses Modul einfach mit dem Play-Button neben „introduction“ oder starten Sie alle Module gleichzeitig. +Klicken Sie einfach auf den Start-Button neben „introduction“, um dieses Modul zu starten, oder starten Sie alle Module gleichzeitig. Spring Boot Dashboard -*Das Spring Boot Dashboard in VS Code – starten, stoppen und überwachen Sie alle Module an einem Ort* +*Das Spring Boot Dashboard in VS Code — starten, stoppen und überwachen Sie alle Module an einem Ort* -**Option 2: Shell-Skripte verwenden** +**Option 2: Verwendung von Shell-Skripten** Starten Sie alle Webanwendungen (Module 01-04): @@ -246,23 +248,25 @@ cd 01-introduction .\start.ps1 ``` -Beide Skripte laden automatisch Umgebungsvariablen aus der Root-`.env`-Datei und bauen die JARs, falls diese nicht existieren. -> **Hinweis:** Wenn Sie alle Module manuell vor dem Start bauen möchten: +Beide Skripte laden automatisch Umgebungsvariablen aus der `.env`-Datei im Stammverzeichnis und bauen die JARs, falls diese nicht vorhanden sind. + +> **Hinweis:** Wenn Sie lieber alle Module manuell bauen möchten, bevor Sie starten: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Öffnen Sie http://localhost:8080 im Browser. + +Öffnen Sie http://localhost:8080 in Ihrem Browser. **Zum Stoppen:** @@ -280,43 +284,44 @@ cd .. && ./stop-all.sh # Alle Module cd ..; .\stop-all.ps1 # Alle Module ``` -## Die Anwendung verwenden + +## Verwendung der Anwendung Die Anwendung bietet eine Weboberfläche mit zwei Chat-Implementierungen nebeneinander. -Startseite der Anwendung +Startbildschirm der Anwendung -*Dashboard zeigt die Optionen Einfacher Chat (zustandslos) und Konversationeller Chat (zustandsbehaftet)* +*Dashboard zeigt sowohl Simple Chat (zustandslos) als auch Conversational Chat (zustandsbehaftet)* ### Zustandsloser Chat (linkes Panel) -Probieren Sie dies zuerst aus. Fragen Sie „Mein Name ist John“ und fragen Sie dann sofort „Wie heißt mein Name?“ Das Modell wird sich nicht erinnern, weil jede Nachricht unabhängig ist. Das zeigt das Kernproblem der einfachen Sprachmodell-Integration – kein Gesprächskontext. +Probieren Sie das zuerst. Fragen Sie „Mein Name ist John“ und dann sofort „Wie heißt mein Name?“ Das Modell wird sich nicht erinnern, weil jede Nachricht unabhängig ist. Dies zeigt das Kernproblem der Grundintegration von Sprachmodellen – kein Gesprächskontext. Demo zustandsloser Chat -*KI erinnert sich nicht an Ihren Namen aus der vorherigen Nachricht* +*KI merkt sich den Namen aus der vorherigen Nachricht nicht* ### Zustandsbehafteter Chat (rechtes Panel) -Probieren Sie jetzt dieselbe Folge hier aus. Fragen Sie „Mein Name ist John“ und dann „Wie heißt mein Name?“ Diesmal erinnert es sich. Der Unterschied ist MessageWindowChatMemory – dieser erhält die Gesprächshistorie und inkludiert sie bei jeder Anfrage. So funktioniert produktive konversationelle KI. +Versuchen Sie hier dieselbe Abfolge. Fragen Sie „Mein Name ist John“ und dann „Wie heißt mein Name?“ Diesmal erinnert das Modell sich. Der Unterschied ist MessageWindowChatMemory – es hält den Gesprächsverlauf und fügt ihn mit jeder Anfrage hinzu. So funktionieren produktive konversationelle KI-Anwendungen. Demo zustandsbehafteter Chat *KI erinnert sich an Ihren Namen aus dem früheren Gespräch* -Beide Panels verwenden dasselbe GPT-5.2 Modell. Der einzige Unterschied ist der Speicher. Das macht klar, welchen Mehrwert Speicher für Ihre Anwendung bringt und warum er für reale Anwendungsfälle essenziell ist. +Beide Panels verwenden dasselbe GPT-5.2-Modell. Der einzige Unterschied ist der Speicher. Das macht deutlich, was Speicher Ihrer Anwendung bringt und warum er für echte Anwendungsfälle unverzichtbar ist. ## Nächste Schritte -**Nächstes Modul:** [02-prompt-engineering – Prompt Engineering mit GPT-5.2](../02-prompt-engineering/README.md) +**Nächstes Modul:** [02-prompt-engineering - Prompt Engineering mit GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigation:** [← Vorheriges: Modul 00 – Quick Start](../00-quick-start/README.md) | [Zurück zum Hauptmenü](../README.md) | [Nächstes: Modul 02 – Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigation:** [← Zurück zur Hauptseite](../README.md) | [Weiter: Modul 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- -**Haftungsausschluss**: -Dieses Dokument wurde mithilfe des KI-Übersetzungsdienstes [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, weisen wir darauf hin, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache ist als maßgebliche Quelle zu betrachten. Für wichtige Informationen wird eine professionelle, menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die durch die Nutzung dieser Übersetzung entstehen. +**Haftungsausschluss**: +Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Bei kritischen Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen. \ No newline at end of file diff --git a/translations/de/02-prompt-engineering/README.md b/translations/de/02-prompt-engineering/README.md index 91118cb64..fc8df596a 100644 --- a/translations/de/02-prompt-engineering/README.md +++ b/translations/de/02-prompt-engineering/README.md @@ -2,52 +2,52 @@ ## Inhaltsverzeichnis -- [Video Walkthrough](../../../02-prompt-engineering) -- [Was Sie lernen werden](../../../02-prompt-engineering) -- [Voraussetzungen](../../../02-prompt-engineering) -- [Verständnis von Prompt Engineering](../../../02-prompt-engineering) -- [Grundlagen des Prompt Engineerings](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Rollenbasiertes Prompting](../../../02-prompt-engineering) - - [Prompt-Vorlagen](../../../02-prompt-engineering) -- [Fortgeschrittene Muster](../../../02-prompt-engineering) -- [Anwendung starten](../../../02-prompt-engineering) -- [Screenshots der Anwendung](../../../02-prompt-engineering) -- [Erkundung der Muster](../../../02-prompt-engineering) - - [Niedrige vs. hohe Bereitschaft](../../../02-prompt-engineering) - - [Aufgabenausführung (Werkzeug-Preambles)](../../../02-prompt-engineering) - - [Selbstreflektierender Code](../../../02-prompt-engineering) - - [Strukturierte Analyse](../../../02-prompt-engineering) - - [Mehrstufiger Chat](../../../02-prompt-engineering) - - [Schritt-für-Schritt-Argumentation](../../../02-prompt-engineering) - - [Eingeschränkte Ausgabe](../../../02-prompt-engineering) -- [Was Sie wirklich lernen](../../../02-prompt-engineering) -- [Nächste Schritte](../../../02-prompt-engineering) - -## Video Walkthrough - -Sehen Sie sich diese Live-Session an, die erklärt, wie Sie mit diesem Modul starten: - -Prompt Engineering mit LangChain4j - Live Session +- [Video-Durchgang](#video-durchgang) +- [Was Sie lernen werden](#was-sie-lernen-werden) +- [Voraussetzungen](#voraussetzungen) +- [Verständnis von Prompt Engineering](#verständnis-von-prompt-engineering) +- [Grundlagen des Prompt Engineering](#grundlagen-des-prompt-engineering) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Rollenbasiertes Prompting](#rollenbasiertes-prompting) + - [Prompt-Vorlagen](#prompt-vorlagen) +- [Erweiterte Muster](#erweiterte-muster) +- [Anwendung ausführen](#anwendung-starten) +- [Anwendungsscreenshots](#anwendungsscreenshots) +- [Muster erkunden](#die-muster-erkunden) + - [Niedrige vs hohe Eifer](#niedrige-vs-hohe-eagerness) + - [Aufgabenausführung (Tool-Preambles)](#aufgabenausführung-werkzeugpräambeln) + - [Selbstreflektierender Code](#selbstreflektierender-code) + - [Strukturierte Analyse](#strukturierte-analyse) + - [Mehrstufiger Chat](#mehrstufiger-chat) + - [Schritt-für-Schritt-Schlussfolgerung](#schritt-für-schritt-argumentation) + - [Beschränkte Ausgabe](#eingeschränkte-ausgabe) +- [Was Sie wirklich lernen](#was-sie-wirklich-lernen) +- [Nächste Schritte](#nächste-schritte) + +## Video-Durchgang + +Sehen Sie sich diese Live-Sitzung an, die erklärt, wie Sie mit diesem Modul beginnen: + +Prompt Engineering mit LangChain4j - Live-Sitzung ## Was Sie lernen werden -Das folgende Diagramm gibt einen Überblick über die wichtigsten Themen und Fähigkeiten, die Sie in diesem Modul entwickeln werden — von Techniken zur Verfeinerung von Prompts bis zum schrittweisen Workflow, dem Sie folgen. +Das folgende Diagramm bietet einen Überblick über die wichtigsten Themen und Fähigkeiten, die Sie in diesem Modul entwickeln werden – von Techniken zur Verfeinerung von Prompts bis zum Schritt-für-Schritt-Workflow, dem Sie folgen werden. Was Sie lernen werden -In den vorherigen Modulen haben Sie grundlegende Interaktionen mit LangChain4j und GitHub-Modellen erforscht und gesehen, wie Speicher konversationelle KI mit Azure OpenAI ermöglicht. Jetzt konzentrieren wir uns darauf, wie Sie Fragen stellen — also die Prompts selbst — mit Azure OpenAI's GPT-5.2. Die Art und Weise, wie Sie Ihre Prompts strukturieren, beeinflusst dramatisch die Qualität der Antworten, die Sie erhalten. Wir beginnen mit einer Übersicht der grundlegenden Prompting-Techniken und gehen dann zu acht fortgeschrittenen Mustern über, die die Möglichkeiten von GPT-5.2 voll ausschöpfen. +Im vorherigen Modul haben Sie gesehen, wie Speicher Konversations-KI mit Azure OpenAI ermöglicht. Jetzt konzentrieren wir uns darauf, wie Sie Fragen stellen – also die Prompts selbst – unter Verwendung von Azure OpenAI's GPT-5.2. Die Art, wie Sie Ihre Prompts strukturieren, beeinflusst maßgeblich die Qualität der Antworten, die Sie erhalten. Wir beginnen mit einer Überprüfung der grundlegenden Prompting-Techniken und gehen dann zu acht erweiterten Mustern über, die die Fähigkeiten von GPT-5.2 voll ausnutzen. -Wir verwenden GPT-5.2, weil es eine Steuerung des Denkens einführt – Sie können dem Modell sagen, wie viel Nachdenken vor der Antwort erfolgen soll. Das macht verschiedene Prompting-Strategien deutlicher sichtbar und hilft Ihnen zu verstehen, welche Ansätze wann zu verwenden sind. Außerdem profitieren wir von Azure's geringeren Ratenbegrenzungen für GPT-5.2 im Vergleich zu GitHub-Modellen. +Wir verwenden GPT-5.2, weil es eine Steuerung des Denkprozesses einführt – Sie können dem Modell sagen, wie viel nachzudenken ist, bevor es antwortet. Das macht verschiedene Prompting-Strategien deutlicher und hilft Ihnen zu verstehen, wann Sie welche Methode einsetzen sollten. ## Voraussetzungen - Abgeschlossenes Modul 01 (Azure OpenAI-Ressourcen bereitgestellt) -- `.env` Datei im Hauptverzeichnis mit Azure-Anmeldedaten (erstellt durch `azd up` im Modul 01) +- `.env`-Datei im Stammverzeichnis mit Azure-Anmeldeinformationen (erstellt durch `azd up` in Modul 01) -> **Hinweis:** Falls Sie Modul 01 noch nicht abgeschlossen haben, folgen Sie bitte zuerst den dortigen Bereitstellungsanweisungen. +> **Hinweis:** Wenn Sie Modul 01 noch nicht abgeschlossen haben, folgen Sie dort zuerst den Bereitstellungsanweisungen. ## Verständnis von Prompt Engineering @@ -55,47 +55,47 @@ Im Kern ist Prompt Engineering der Unterschied zwischen vagen und präzisen Anwe Was ist Prompt Engineering? -Prompt Engineering bedeutet, Texteingaben so zu gestalten, dass sie konsistent die gewünschten Ergebnisse liefern. Es geht nicht nur ums Fragenstellen – sondern darum, Anfragen so zu strukturieren, dass das Modell genau versteht, was Sie wollen und wie es geliefert werden soll. +Prompt Engineering bedeutet, Eingabetext so zu gestalten, dass Sie konsistent die Ergebnisse erhalten, die Sie benötigen. Es geht nicht nur darum, Fragen zu stellen – es geht darum, Anfragen so zu strukturieren, dass das Modell genau versteht, was Sie wollen und wie es geliefert werden soll. -Denken Sie daran wie an eine Anweisung an einen Kollegen. „Behebe den Fehler“ ist vage. „Behebe die NullPointerException in UserService.java Zeile 45 durch Hinzufügen einer Nullprüfung“ ist spezifisch. Sprachmodelle funktionieren genauso – Spezifität und Struktur zählen. +Denken Sie daran wie an eine Anweisung an einen Kollegen. „Behebe den Fehler“ ist vage. „Behebe den NullPointerException in UserService.java Zeile 45 durch Hinzufügen einer Nullprüfung“ ist spezifisch. Sprachmodelle funktionieren genauso – Spezifität und Struktur sind entscheidend. -Das folgende Diagramm zeigt, wie LangChain4j in dieses Bild passt — es verbindet Ihre Prompt-Muster mit dem Modell über die Bausteine `SystemMessage` und `UserMessage`. +Das folgende Diagramm zeigt, wie LangChain4j in dieses Bild passt – indem es Ihre Prompt-Muster über SystemMessage und UserMessage Bausteine mit dem Modell verbindet. Wie LangChain4j passt -LangChain4j stellt die Infrastruktur bereit — Modellverbindungen, Speicher und Nachrichtentypen — während Prompt-Muster einfach sorgfältig strukturierte Texte sind, die Sie durch diese Infrastruktur senden. Die Schlüsselbausteine sind `SystemMessage` (setzt das Verhalten und die Rolle der KI) und `UserMessage` (enthält Ihre eigentliche Anfrage). +LangChain4j stellt die Infrastruktur bereit – Modellverbindungen, Speicher und Nachrichtentypen – während Prompt-Muster nur sorgfältig strukturierter Text sind, den Sie durch diese Infrastruktur senden. Die wichtigsten Bausteine sind `SystemMessage` (die das Verhalten und die Rolle der KI festlegt) und `UserMessage` (die Ihre eigentliche Anfrage trägt). -## Grundlagen des Prompt Engineerings +## Grundlagen des Prompt Engineering -Die fünf Kerntechniken, die unten gezeigt sind, bilden die Grundlage für effektives Prompt Engineering. Jede behandelt einen anderen Aspekt, wie Sie mit Sprachmodellen kommunizieren. +Die fünf Kerntechniken unten bilden die Grundlage für effektives Prompt Engineering. Jede behandelt einen anderen Aspekt, wie Sie mit Sprachmodellen kommunizieren. -Übersicht der fünf Muster des Prompt Engineerings +Übersicht der fünf Prompt-Engineering-Muster -Bevor wir in diesem Modul zu den fortgeschrittenen Mustern übergehen, sehen wir uns fünf grundlegende Prompting-Techniken an. Diese sind die Bausteine, die jeder Prompt-Ingenieur kennen sollte. Wenn Sie bereits das [Quick Start Modul](../00-quick-start/README.md#2-prompt-patterns) durchgearbeitet haben, kennen Sie diese bereits in der Praxis — hier ist das konzeptuelle Grundgerüst dahinter. +Bevor wir zu den erweiterten Mustern dieses Moduls übergehen, sehen wir uns fünf grundlegende Prompting-Techniken an. Diese sind die Bausteine, die jeder Prompt Engineer kennen sollte. ### Zero-Shot Prompting -Der einfachste Ansatz: Geben Sie dem Modell eine direkte Anweisung ohne Beispiele. Das Modell verlässt sich vollständig auf sein Training, um die Aufgabe zu verstehen und auszuführen. Das funktioniert gut bei einfachen Anforderungen, wo das erwartete Verhalten offensichtlich ist. +Der einfachste Ansatz: Geben Sie dem Modell eine direkte Anweisung ohne Beispiele. Das Modell verlässt sich vollständig auf sein Training, um die Aufgabe zu verstehen und auszuführen. Das funktioniert gut bei einfachen Anfragen, bei denen das erwartete Verhalten offensichtlich ist. Zero-Shot Prompting -*Direkte Anweisung ohne Beispiele — das Modell leitet die Aufgabe allein aus der Anweisung ab* +*Direkte Anweisung ohne Beispiele – das Modell leitet die Aufgabe allein aus der Anweisung ab* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); // Antwort: "Positiv" ``` - -**Wann verwenden:** Für einfache Klassifikationen, direkte Fragen, Übersetzungen oder Aufgaben, die das Modell ohne zusätzliche Anleitung bewältigen kann. + +**Wann zu verwenden:** Einfache Klassifikationen, direkte Fragen, Übersetzungen oder jede Aufgabe, die das Modell ohne zusätzliche Anleitung bewältigen kann. ### Few-Shot Prompting -Geben Sie Beispiele an, die das Muster zeigen, dem das Modell folgen soll. Das Modell lernt von Ihren Beispielen das erwartete Eingabe-Ausgabe-Format und wendet es auf neue Eingaben an. Das verbessert die Konsistenz bei Aufgaben, wo Format oder Verhalten nicht offensichtlich sind. +Geben Sie Beispiele, die das Muster zeigen, dem das Modell folgen soll. Das Modell lernt das erwartete Eingabe-Ausgabe-Format anhand Ihrer Beispiele und wendet es auf neue Eingaben an. Das verbessert die Konsistenz stark bei Aufgaben, bei denen das gewünschte Format oder Verhalten nicht offensichtlich ist. Few-Shot Prompting -*Lernen anhand von Beispielen — das Modell erkennt das Muster und wendet es auf neue Eingaben an* +*Lernen von Beispielen – das Modell erkennt das Muster und überträgt es auf neue Eingaben* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**Wann verwenden:** Für kundenspezifische Klassifikationen, konsistente Formatierung, domänenspezifische Aufgaben oder wenn Zero-Shot-Ergebnisse inkonsistent sind. + +**Wann zu verwenden:** Maßgeschneiderte Klassifikationen, konsistente Formatierung, domänenspezifische Aufgaben oder wenn Zero-Shot-Ergebnisse inkonsistent sind. ### Chain of Thought -Bitten Sie das Modell, seine Argumentation Schritt für Schritt zu zeigen. Statt direkt zur Antwort zu springen, zerlegt das Modell das Problem und arbeitet jeden Teil explizit durch. Das verbessert die Genauigkeit bei Mathematik, Logik und mehrstufigen Denkaufgaben. +Fordern Sie das Modell auf, seinen Denkprozess Schritt für Schritt zu zeigen. Statt sofort eine Antwort zu geben, zerlegt das Modell das Problem und arbeitet jede Teilaufgabe explizit ab. Das erhöht die Genauigkeit bei mathematischen, logischen und mehrstufigen Denkaufgaben. Chain of Thought Prompting -*Schrittweise Argumentation — komplexe Probleme in explizite logische Schritte zerlegen* +*Schritt-für-Schritt-Schlussfolgerung – komplexe Probleme in explizite logische Schritte zerlegen* ```java String prompt = """ @@ -132,8 +132,8 @@ String prompt = """ String response = model.chat(prompt); // Das Modell zeigt: 15 - 8 = 7, dann 7 + 12 = 19 Äpfel ``` - -**Wann verwenden:** Für Mathematikaufgaben, Logikrätsel, Debugging oder Aufgaben, bei denen das Zeigen des Denkprozesses Genauigkeit und Vertrauen verbessert. + +**Wann zu verwenden:** Mathematische Probleme, Logikrätsel, Debugging oder jede Aufgabe, bei der das Zeigen des Denkprozesses Genauigkeit und Vertrauen erhöht. ### Rollenbasiertes Prompting @@ -141,7 +141,7 @@ Weisen Sie der KI vor der Fragestellung eine Persona oder Rolle zu. Das liefert Rollenbasiertes Prompting -*Kontext und Persona setzen — dieselbe Frage erhält je nach zugewiesener Rolle unterschiedliche Antworten* +*Festlegung von Kontext und Persona – dieselbe Frage erhält je nach zugewiesener Rolle unterschiedliche Antworten* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**Wann verwenden:** Für Code-Reviews, Nachhilfe, domänenspezifische Analysen oder wenn Sie Antworten benötigen, die an ein bestimmtes Fachwissen oder eine Perspektive angepasst sind. + +**Wann zu verwenden:** Code-Reviews, Nachhilfe, domänenspezifische Analysen oder wenn Sie Antworten brauchen, die auf ein bestimmtes Fachwissen oder eine Perspektive zugeschnitten sind. ### Prompt-Vorlagen -Erstellen Sie wiederverwendbare Prompts mit variablen Platzhaltern. Statt jedes Mal einen neuen Prompt zu schreiben, definieren Sie eine Vorlage einmal und füllen verschiedene Werte ein. Die `PromptTemplate` Klasse von LangChain4j macht das mit `{{variable}}` Syntax einfach. +Erstellen Sie wiederverwendbare Prompts mit variablen Platzhaltern. Anstatt jedes Mal einen neuen Prompt zu schreiben, definieren Sie einmal eine Vorlage und füllen verschiedene Werte ein. Die `PromptTemplate` Klasse von LangChain4j macht das mit der Syntax `{{variable}}` einfach. Prompt-Vorlagen -*Wiederverwendbare Prompts mit variablen Platzhaltern — eine Vorlage, viele Verwendungen* +*Wiederverwendbare Prompts mit variablen Platzhaltern – eine Vorlage, viele Anwendungen* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**Wann verwenden:** Für wiederholte Anfragen mit unterschiedlichen Eingaben, Stapelverarbeitung, Aufbau wiederverwendbarer KI-Workflows oder beliebige Szenarien, bei denen die Prompt-Struktur gleich bleibt, aber die Daten sich ändern. + +**Wann zu verwenden:** Wiederholte Abfragen mit unterschiedlichen Eingaben, Batch-Verarbeitung, Aufbau wiederverwendbarer KI-Workflows oder jede Situation, in der die Prompt-Struktur gleich bleibt, sich aber die Daten ändern. --- -Diese fünf Grundlagen geben Ihnen ein solides Werkzeugset für die meisten Prompting-Aufgaben. Der Rest dieses Moduls baut darauf mit **acht fortgeschrittenen Mustern** auf, die GPT-5.2s Steuerung von Denkprozessen, Selbstbewertung und strukturierte Ausgabe-Fähigkeiten ausnutzen. +Diese fünf Grundlagen geben Ihnen einen soliden Werkzeugkasten für die meisten Prompting-Aufgaben. Der Rest dieses Moduls baut darauf mit **acht erweiterten Mustern** auf, die GPT-5.2s Steuerung des Denkprozesses, Selbstevaluation und strukturierte Ausgaben nutzen. -## Fortgeschrittene Muster +## Erweiterte Muster -Mit den Grundlagen abgedeckt, wenden wir uns den acht fortgeschrittenen Mustern zu, die dieses Modul einzigartig machen. Nicht alle Probleme brauchen den gleichen Ansatz. Manche Fragen verlangen schnelle Antworten, andere tiefgründiges Nachdenken. Manche brauchen sichtbare Argumentation, andere nur Ergebnisse. Jedes Muster unten ist auf ein anderes Szenario optimiert — und GPT-5.2s Steuerung des Denkens macht die Unterschiede noch deutlicher. +Nachdem die Grundlagen abgedeckt sind, kommen wir zu den acht erweiterten Mustern, die dieses Modul einzigartig machen. Nicht alle Probleme benötigen den gleichen Ansatz. Manche Fragen brauchen schnelle Antworten, andere tiefes Nachdenken. Einige brauchen sichtbare Überlegungen, andere nur Ergebnisse. Jedes Muster unten ist für ein anderes Szenario optimiert – und GPT-5.2s Steuerung der Denkprozesse macht die Unterschiede noch deutlicher. -Acht Muster für Prompt Engineering +Acht Prompting-Muster -*Überblick über die acht Muster des Prompt Engineerings und deren Anwendungsfälle* +*Übersicht der acht Prompt-Engineering-Muster und deren Anwendungsfälle* -GPT-5.2 fügt den Mustern eine weitere Dimension hinzu: *Steuerung des Denkens*. Der Schieberegler unten zeigt, wie Sie den Denkaufwand des Modells anpassen können — von schnellen, direkten Antworten bis hin zu tiefgründiger, gründlicher Analyse. +GPT-5.2 fügt diesen Mustern noch eine Dimension hinzu: *Steuerung des Denkprozesses*. Der Slider unten zeigt, wie Sie den Denkaufwand des Modells anpassen können – von schnellen direkten Antworten bis zu tiefgehender Analyse. -Steuerung des Denkens mit GPT-5.2 +Steuerung des Denkprozesses mit GPT-5.2 -*Die Steuerung des Denkens bei GPT-5.2 lässt Sie festlegen, wie viel das Modell nachdenken soll — von schnellen direkten Antworten bis zu tiefgründiger Erforschung* +*Mit der Steuerung des Denkprozesses von GPT-5.2 können Sie festlegen, wie viel das Modell denken soll – von schnellen direkten Antworten bis zur tiefgehenden Erkundung* -**Niedrige Bereitschaft (Schnell & Fokussiert)** - Für einfache Fragen, bei denen Sie schnelle, direkte Antworten wollen. Das Modell denkt minimal — maximal 2 Schritte. Nutzen Sie das für Berechnungen, Nachschlagen oder einfache Fragen. +**Niedriger Eifer (Schnell & Fokussiert)** – Für einfache Fragen, bei denen Sie schnelle, direkte Antworten wollen. Das Modell denkt minimal – maximal 2 Schritte. Nutzen Sie das für Berechnungen, Abfragen oder einfache Fragen. ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> 💡 **Mit GitHub Copilot erkunden:** Öffnen Sie [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) und fragen Sie: +> - „Was ist der Unterschied zwischen low eagerness und high eagerness Prompting-Mustern?“ +> - „Wie helfen XML-Tags in Prompts, die Antwort der KI zu strukturieren?“ +> - „Wann sollte ich Selbstreflexionsmuster statt direkter Anweisungen verwenden?“ -> 💡 **Entdecken Sie mit GitHub Copilot:** Öffnen Sie [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) und fragen Sie: -> - „Was ist der Unterschied zwischen niedriger und hoher Bereitschaft bei Prompt-Mustern?“ -> - „Wie helfen die XML-Tags in Prompts, die Antwort der KI zu strukturieren?“ -> - „Wann sollte ich Selbstreflexionsmuster vs. direkte Anweisungen verwenden?“ - -**Hohe Bereitschaft (Tief & Gründlich)** - Für komplexe Probleme, bei denen Sie umfassende Analysen wollen. Das Modell erforscht gründlich und zeigt detaillierte Argumentationen. Nutzen Sie das für Systemdesign, Architekturentscheidungen oder komplexe Recherche. +**Hoher Eifer (Tief & Gründlich)** – Für komplexe Probleme, bei denen Sie eine umfassende Analyse möchten. Das Modell arbeitet gründlich, zeigt detailliertes Nachdenken. Verwenden Sie das für Systemdesign, Architekturentscheidungen oder komplexe Forschungsarbeiten. ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**Aufgabenausführung (Schrittweiser Fortschritt)** - Für mehrschrittige Arbeitsabläufe. Das Modell liefert einen Plan vorab, berichtet jeden Schritt beim Arbeiten und gibt dann eine Zusammenfassung. Verwenden Sie dies für Migrationen, Implementierungen oder jegliche mehrstufigen Prozesse. + +**Aufgabenausführung (Fortschritt Schritt für Schritt)** – Für mehrstufige Workflows. Das Modell gibt einen Plan im Voraus, beschreibt jeden Schritt beim Arbeiten und liefert dann eine Zusammenfassung. Nutzen Sie das für Migrationen, Implementierungen oder jeden mehrstufigen Prozess. ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +Chain-of-Thought Prompting fordert das Modell explizit auf, seinen Denkprozess zu zeigen, was die Genauigkeit bei komplexen Aufgaben verbessert. Die Schritt-für-Schritt-Zerlegung hilft sowohl Menschen als auch KI, die Logik zu verstehen. -Chain-of-Thought Prompting fordert das Modell explizit auf, seinen Denkprozess zu zeigen, was die Genauigkeit bei komplexen Aufgaben verbessert. Die schrittweise Zerlegung hilft sowohl Menschen als auch KI, die Logik zu verstehen. - -> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Fragen Sie zu diesem Muster: -> - „Wie passe ich das Aufgabenausführungsmuster für langlaufende Operationen an?“ -> - „Was sind bewährte Methoden für die Strukturierung von Werkzeug-Preambles in Produktionsanwendungen?“ -> - „Wie erfasse und zeige ich Zwischenfortschritte in einer Benutzeroberfläche an?“ +> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Fragen Sie zu diesem Muster: +> - „Wie würde ich das Aufgabenausführungsmuster für lang laufende Operationen anpassen?“ +> - „Was sind Best Practices zur Strukturierung von Tool-Preambles in produktiven Anwendungen?“ +> - „Wie kann ich Zwischenfortschrittsupdates in einer UI erfassen und anzeigen?“ -Das folgende Diagramm illustriert diesen Plan → Ausführen → Zusammenfassen Workflow. +Das folgende Diagramm veranschaulicht diesen Plan → Ausführen → Zusammenfassen-Workflow. Muster für Aufgabenausführung -*Plan → Ausführen → Zusammenfassen Arbeitsablauf für mehrstufige Aufgaben* +*Plan → Ausführen → Zusammenfassen-Workflow für mehrstufige Aufgaben* -**Selbstreflektierender Code** - Für die Erzeugung von Produktionscode. Das Modell generiert Code nach Produktionsstandards mit ordentlicher Fehlerbehandlung. Nutzen Sie das, wenn Sie neue Features oder Services entwickeln. +**Selbstreflektierender Code** – Für die Generierung von produktionsreifem Code. Das Modell erzeugt Code gemäß Produktionsstandards mit ordentlicher Fehlerbehandlung. Verwenden Sie das bei der Erstellung neuer Features oder Dienste. ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +Das folgende Diagramm zeigt die iterative Verbesserungsschleife – generieren, bewerten, Schwachstellen identifizieren und verfeinern, bis der Code Produktionsstandards erfüllt. -Das folgende Diagramm zeigt diese iterative Verbesserungsschleife — generieren, bewerten, Schwachstellen erkennen, verfeinern bis der Code Produktionsstandards erfüllt. - -Selbstreflexionszyklus +Selbstreflexions-Zyklus -*Iterative Verbesserungsschleife - generieren, bewerten, Probleme identifizieren, verbessern, wiederholen* +*Iterative Verbesserungsschleife – generieren, bewerten, Probleme identifizieren, verbessern, wiederholen* -**Strukturierte Analyse** - Für konsistente Bewertungen. Das Modell prüft Code anhand eines festen Rahmens (Korrektheit, Praktiken, Leistung, Sicherheit, Wartbarkeit). Nutzen Sie das für Code-Reviews oder Qualitätsbewertungen. +**Strukturierte Analyse** – Für konsistente Bewertungen. Das Modell überprüft Code anhand eines festen Rahmens (Korrektheit, Praktiken, Leistung, Sicherheit, Wartbarkeit). Verwenden Sie das für Code-Reviews oder Qualitätsbewertungen. ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Fragen Sie zur strukturierten Analyse: +> - „Wie kann ich das Analyse-Framework für verschiedene Arten von Code-Reviews anpassen?“ +> - „Wie ist der beste Weg, um strukturierte Ausgaben programmatisch zu parsen und zu verarbeiten?“ +> - „Wie stelle ich konsistente Schweregrade über unterschiedliche Review-Sitzungen sicher?“ -> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Fragen Sie zur strukturierten Analyse: -> - „Wie kann ich den Analyse-Rahmen für verschiedene Arten von Code-Reviews anpassen?“ -> - „Wie kann ich strukturierte Ausgaben programmatisch parsen und verwenden?“ -> - „Wie stelle ich konsistente Schweregrade über verschiedene Review-Sitzungen sicher?“ - -Das folgende Diagramm zeigt, wie dieser strukturierte Rahmen ein Code-Review in konsistente Kategorien mit Schweregraden unterteilt. +Das folgende Diagramm zeigt, wie dieses strukturierte Framework eine Code-Review in konsistente Kategorien mit Schweregraden gliedert. Muster für strukturierte Analyse -*Rahmenwerk für konsistente Code-Reviews mit Schweregraden* +*Framework für konsistente Code-Reviews mit Schweregrad-Leveln* -**Mehrstufiger Chat** - Für Konversationen, die Kontext brauchen. Das Modell erinnert sich an vorherige Nachrichten und baut darauf auf. Nutzen Sie das für interaktive Hilfesitzungen oder komplexe Q&A. +**Mehrstufiger Chat** – Für Unterhaltungen, die Kontext brauchen. Das Modell erinnert sich an frühere Nachrichten und baut darauf auf. Verwenden Sie das für interaktive Hilfesitzungen oder komplexes Q&A. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` + +Das folgende Diagramm visualisiert, wie sich der Gesprächskontext über mehrere Runden ansammelt und wie das mit dem Token-Limit des Modells zusammenhängt. -Das folgende Diagramm visualisiert, wie Kontext in der Unterhaltung mit jedem Schritt wächst und wie das im Verhältnis zum Token-Limit des Modells steht. +Kontextspeicher -Kontext-Speicher +*Wie sich der Gesprächskontext über mehrere Runden ansammelt, bis das Token-Limit erreicht ist* -*Wie sich der Gesprächskontext über mehrere Schritte ansammelt, bis das Token-Limit erreicht wird* -**Schritt-für-Schritt-Begründung** – Für Probleme, die sichtbare Logik erfordern. Das Modell zeigt eine explizite Begründung für jeden Schritt. Verwenden Sie dies für Mathematikaufgaben, Logikrätsel oder wenn Sie den Denkprozess nachvollziehen müssen. +**Schritt-für-Schritt-Schlussfolgerung** – Für Probleme, die sichtbare Logik erfordern. Das Modell zeigt für jeden Schritt explizite Überlegungen. Verwenden Sie das für mathematische Probleme, Logikrätsel oder wenn Sie den Denkprozess verstehen möchten. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Das untenstehende Diagramm veranschaulicht, wie das Modell Probleme in explizite, nummerierte logische Schritte unterteilt. +Das folgende Diagramm zeigt, wie das Modell Probleme in explizite, nummerierte logische Schritte zerlegt. Schritt-für-Schritt-Muster - *Probleme in explizite logische Schritte zerlegen* -**Eingeschränkte Ausgabe** – Für Antworten mit spezifischen Formatvorgaben. Das Modell hält sich strikt an Format- und Längenregeln. Verwenden Sie dies für Zusammenfassungen oder wenn Sie eine präzise Ausgabe benötigen. +**Eingeschränkte Ausgabe** – Für Antworten mit spezifischen Formatvorgaben. Das Modell hält sich strikt an Format- und Längenregeln. Verwenden Sie dies für Zusammenfassungen oder wenn Sie eine präzise Ausgabestruktur benötigen. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Das folgende Diagramm zeigt, wie Einschränkungen das Modell anleiten, eine Ausgabe zu erzeugen, die streng den Format- und Längenanforderungen entspricht. +Das folgende Diagramm zeigt, wie Einschränkungen das Modell anleiten, Ausgaben zu erzeugen, die genau Ihren Format- und Längenvorgaben entsprechen. -Muster für eingeschränkte Ausgabe +Constrained Output Pattern -*Durchsetzung spezifischer Format-, Längen- und Strukturvorgaben* +*Spezifische Format-, Längen- und Strukturvorgaben erzwingen* ## Anwendung starten **Bereitstellung überprüfen:** -Stellen Sie sicher, dass die `.env`-Datei im Stammverzeichnis mit Azure-Anmeldedaten existiert (wurde während Modul 01 erstellt). Führen Sie dies aus dem Modulverzeichnis (`02-prompt-engineering/`) aus: +Stellen Sie sicher, dass die `.env`-Datei im Stammverzeichnis mit Azure-Anmeldedaten vorhanden ist (erstellt während Modul 01). Führen Sie dies aus dem Modulverzeichnis (`02-prompt-engineering/`) aus: **Bash:** ```bash @@ -442,33 +442,33 @@ cat ../.env # Sollte AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT anzeigen Get-Content ..\.env # Sollte AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT anzeigen ``` -**Starten der Anwendung:** +**Starten Sie die Anwendung:** -> **Hinweis:** Wenn Sie bereits alle Anwendungen mit `./start-all.sh` aus dem Stammverzeichnis gestartet haben (wie in Modul 01 beschrieben), läuft dieses Modul bereits auf Port 8083. Sie können die Startbefehle unten überspringen und direkt zu http://localhost:8083 gehen. +> **Hinweis:** Wenn Sie bereits alle Anwendungen mit `./start-all.sh` aus dem Stammverzeichnis gestartet haben (wie in Modul 01 beschrieben), läuft dieses Modul bereits auf Port 8083. Sie können die untenstehenden Startbefehle überspringen und direkt zu http://localhost:8083 gehen. -**Option 1: Verwendung des Spring Boot Dashboards (empfohlen für VS Code-Nutzer)** +**Option 1: Nutzung des Spring Boot Dashboards (Empfohlen für VS Code Nutzer)** -Der Dev-Container enthält die Erweiterung Spring Boot Dashboard, die eine visuelle Oberfläche zur Verwaltung aller Spring Boot-Anwendungen bietet. Sie finden sie in der Aktivitätsleiste links in VS Code (suchen Sie nach dem Spring Boot Symbol). +Der Dev-Container enthält die Spring Boot Dashboard-Erweiterung, die eine visuelle Schnittstelle zum Verwalten aller Spring Boot Anwendungen bietet. Sie finden sie in der Aktivitätsleiste auf der linken Seite von VS Code (suchen Sie nach dem Spring Boot Symbol). -Vom Spring Boot Dashboard aus können Sie: -- Alle verfügbaren Spring Boot-Anwendungen im Workspace sehen -- Anwendungen mit einem Klick starten/stoppen -- Anwendungsprotokolle in Echtzeit ansehen -- Anwendungsstatus überwachen +Im Spring Boot Dashboard können Sie: +- Alle verfügbaren Spring Boot Anwendungen im Workspace sehen +- Anwendungen mit einem Klick starten oder stoppen +- Anwendungsprotokolle in Echtzeit ansehen +- Den Anwendungsstatus überwachen -Klicken Sie einfach auf die Wiedergabetaste neben „prompt-engineering“, um dieses Modul zu starten, oder starten Sie alle Module auf einmal. +Klicken Sie einfach auf die Wiedergabetaste neben "prompt-engineering", um dieses Modul zu starten, oder starten Sie alle Module gleichzeitig. Spring Boot Dashboard -*Das Spring Boot Dashboard in VS Code — Starte, stoppe und überwache alle Module an einem Ort* +*Das Spring Boot Dashboard in VS Code – starten, stoppen und überwachen Sie alle Module von einem Ort aus* -**Option 2: Verwendung von Shell-Skripten** +**Option 2: Nutzung von Shell-Skripten** -Alle Webanwendungen starten (Module 01-04): +Starten Sie alle Webanwendungen (Module 01-04): **Bash:** ```bash -cd .. # Aus dem Stammverzeichnis +cd .. # Vom Stammverzeichnis ./start-all.sh ``` @@ -478,7 +478,7 @@ cd .. # Vom Stammverzeichnis .\start-all.ps1 ``` -Oder nur dieses Modul starten: +Oder starten Sie nur dieses Modul: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Beide Skripte laden automatisch Umgebungsvariablen aus der `.env`-Datei im Stammverzeichnis und bauen die JARs, falls diese noch nicht existieren. +Beide Skripte laden automatisch Umgebungsvariablen aus der `.env`-Datei im Stammverzeichnis und bauen die JAR-Dateien, falls sie nicht existieren. -> **Hinweis:** Wenn Sie alle Module manuell vor dem Start bauen möchten: +> **Hinweis:** Wenn Sie alle Module lieber manuell bauen möchten, bevor Sie starten: > > **Bash:** > ```bash @@ -526,71 +526,71 @@ cd .. && ./stop-all.sh # Alle Module cd ..; .\stop-all.ps1 # Alle Module ``` -## Anwendungs-Screenshots +## Anwendungsscreenshots -Hier sehen Sie die Hauptoberfläche des Prompt Engineering Moduls, wo Sie alle acht Muster nebeneinander ausprobieren können. +Hier sehen Sie die Hauptoberfläche des Prompt Engineering Moduls, in dem Sie alle acht Muster nebeneinander ausprobieren können. -Dashboard Startseite +Dashboard Home -*Das Haupt-Dashboard zeigt alle 8 Prompt-Engineering-Muster mit ihren Eigenschaften und Anwendungsfällen* +*Das Hauptdashboard zeigt alle 8 Prompt Engineering Muster mit deren Merkmalen und Anwendungsfällen* ## Die Muster erkunden -Die Weboberfläche ermöglicht es Ihnen, verschiedene Prompting-Strategien auszuprobieren. Jedes Muster löst unterschiedliche Probleme – probieren Sie es aus, um zu sehen, wann welche Methode glänzt. +Die Weboberfläche ermöglicht Ihnen das Experimentieren mit verschiedenen Prompt-Strategien. Jedes Muster löst unterschiedliche Probleme – probieren Sie aus, wann welcher Ansatz glänzt. -> **Hinweis: Streaming vs. Nicht-Streaming** — Jede Muster-Seite bietet zwei Buttons: **🔴 Stream Response (Live)** und eine **Nicht-Streaming**-Option. Streaming verwendet Server-Sent Events (SSE), um Tokens in Echtzeit anzuzeigen, während das Modell sie generiert, sodass Sie den Fortschritt sofort sehen. Die Nicht-Streaming-Option wartet, bis die gesamte Antwort fertig ist, bevor sie angezeigt wird. Bei Prompts, die tiefes Nachdenken erfordern (z. B. hohe Eifrigkeit, selbstreflektierender Code), kann der Nicht-Streaming-Aufruf sehr lange dauern – manchmal Minuten – ohne sichtbares Feedback. **Verwenden Sie Streaming beim Experimentieren mit komplexen Prompts**, damit Sie sehen, wie das Modell arbeitet, und nicht den Eindruck bekommen, die Anfrage sei abgelaufen. +> **Hinweis: Streaming vs. Nicht-Streaming** – Auf jeder Musterseite gibt es zwei Buttons: **🔴 Stream Response (Live)** und eine **Nicht-Streaming**-Option. Streaming nutzt Server-Sent Events (SSE), um Token in Echtzeit anzuzeigen, während das Modell sie generiert, sodass Sie den Fortschritt sofort sehen. Die Nicht-Streaming-Option wartet auf die vollständige Antwort, bevor sie angezeigt wird. Für Prompts, die tiefgründiges Denken erfordern (z.B. High Eagerness, Self-Reflecting Code), kann der Nicht-Streaming-Aufruf sehr lange dauern – manchmal Minuten – ohne sichtbares Feedback. **Verwenden Sie Streaming beim Experimentieren mit komplexen Prompts**, damit Sie das Modell arbeiten sehen und den Eindruck eines Timeouts vermeiden. > -> **Hinweis: Browser-Anforderung** — Die Streaming-Funktion nutzt die Fetch Streams API (`response.body.getReader()`), die einen vollständigen Browser (Chrome, Edge, Firefox, Safari) erfordert. Sie funktioniert **nicht** im integrierten Simple Browser von VS Code, da dessen Webview die ReadableStream API nicht unterstützt. Im Simple Browser funktionieren die Nicht-Streaming Buttons weiterhin normal – nur die Streaming Buttons sind betroffen. Öffnen Sie `http://localhost:8083` in einem externen Browser für das volle Erlebnis. +> **Hinweis: Browseranforderung** – Die Streaming-Funktion nutzt die Fetch Streams API (`response.body.getReader()`), die einen vollständigen Browser erfordert (Chrome, Edge, Firefox, Safari). Sie funktioniert **nicht** im eingebauten Simple Browser von VS Code, da dessen Webview die ReadableStream API nicht unterstützt. Im Simple Browser funktionieren die Nicht-Streaming-Buttons normal – nur die Streaming-Buttons sind betroffen. Öffnen Sie http://localhost:8083 in einem externen Browser für das volle Erlebnis. -### Niedrige vs. hohe Eifrigkeit +### Niedrige vs. hohe Eagerness -Stellen Sie eine einfache Frage wie „Was sind 15 % von 200?“ mit niedriger Eifrigkeit. Sie erhalten eine sofortige, direkte Antwort. Stellen Sie nun eine komplexe Frage wie „Entwerfe eine Caching-Strategie für eine stark frequentierte API“ mit hoher Eifrigkeit. Klicken Sie auf **🔴 Stream Response (Live)** und beobachten Sie, wie die detaillierte Begründung des Modells Token für Token erscheint. Dasselbe Modell, dieselbe Frage – nur der Prompt steuert, wie intensiv nachgedacht wird. +Stellen Sie eine einfache Frage wie „Was sind 15 % von 200?“ mit niedriger Eagerness. Sie erhalten eine sofortige, direkte Antwort. Nun fragen Sie etwas Komplexes wie „Entwerfen Sie eine Caching-Strategie für eine stark frequentierte API“ mit hoher Eagerness. Klicken Sie auf **🔴 Stream Response (Live)** und beobachten Sie, wie das Modell detaillierte Überlegungen Token für Token anzeigt. Dasselbe Modell, dieselbe Fragenstruktur – aber der Prompt sagt ihm, wie viel Denken es anstellen soll. -### Aufgaben-Ausführung (Tool-Preambels) +### Aufgabenausführung (Werkzeugpräambeln) -Mehrstufige Arbeitsabläufe profitieren von einer vorherigen Planung und Fortschrittskommentierung. Das Modell skizziert, was es tun wird, erläutert jeden Schritt und fasst die Ergebnisse zusammen. +Mehrstufige Workflows profitieren von einer vorausgehenden Planung und Fortschrittserzählung. Das Modell skizziert, was es tun wird, erläutert jeden Schritt und fasst das Ergebnis zusammen. ### Selbstreflektierender Code -Probieren Sie „Erstelle einen E-Mail-Validierungsdienst“. Anstatt nur Code zu generieren und zu stoppen, erzeugt das Modell, bewertet ihn anhand von Qualitätskriterien, erkennt Schwächen und verbessert den Code. Sie sehen, wie es iteriert, bis der Code den Produktionsstandards entspricht. +Probieren Sie „Erstelle einen Service zur E-Mail-Validierung“. Anstatt nur Code zu erzeugen und zu stoppen, generiert das Modell, bewertet ihn anhand von Qualitätskriterien, identifiziert Schwachstellen und verbessert ihn. Sie sehen, wie es iteriert, bis der Code Produktionsstandards erfüllt. ### Strukturierte Analyse -Code Reviews brauchen konsistente Bewertungsrahmen. Das Modell analysiert den Code anhand fester Kategorien (Korrektheit, Praktiken, Leistung, Sicherheit) mit Schweregraden. +Code Reviews benötigen konsistente Bewertungsrahmen. Das Modell analysiert Code nach festen Kategorien (Korrektheit, Praktiken, Performance, Sicherheit) mit Schweregraden. -### Multi-Turn Chat +### Mehrstufiger Chat -Fragen Sie „Was ist Spring Boot?“ und folgen Sie direkt mit „Zeig mir ein Beispiel“. Das Modell erinnert sich an Ihre erste Frage und gibt Ihnen ein spezielles Spring Boot-Beispiel. Ohne Gedächtnis wäre die zweite Frage zu vage. +Fragen Sie „Was ist Spring Boot?“ und anschließend „Zeig mir ein Beispiel“. Das Modell erinnert sich an Ihre erste Frage und liefert ein spezielles Spring Boot-Beispiel. Ohne Gedächtnis wäre die zweite Frage zu vage. -### Schritt-für-Schritt-Begründung +### Schritt-für-Schritt-Argumentation -Wählen Sie ein Mathematikproblem und probieren Sie es mit Schritt-für-Schritt-Begründung und niedriger Eifrigkeit. Niedrige Eifrigkeit gibt nur die Antwort – schnell, aber undurchsichtig. Schritt-für-Schritt zeigt jeden Rechenschritt und jede Entscheidung. +Wählen Sie ein Matheproblem und probieren Sie es mit Schritt-für-Schritt-Argumentation und niedriger Eagerness. Niedrige Eagerness gibt die Antwort schnell, aber undurchsichtig. Schritt-für-Schritt zeigt jede Berechnung und Entscheidung. ### Eingeschränkte Ausgabe -Wenn Sie bestimmte Formate oder Wortzahlen benötigen, erzwingt dieses Muster eine strikte Einhaltung. Versuchen Sie, eine Zusammenfassung mit exakt 100 Wörtern im Stichpunktformat zu generieren. +Wenn Sie spezifische Formate oder Wortzahlen benötigen, sorgt dieses Muster für strikte Einhaltung. Versuchen Sie, eine Zusammenfassung mit genau 100 Wörtern in Aufzählungsformat zu erzeugen. ## Was Sie wirklich lernen -**Der Denkaufwand verändert alles** +**Argumentationsaufwand ändert alles** -GPT-5.2 lässt Sie den Rechenaufwand über Ihre Prompts steuern. Niedriger Aufwand bedeutet schnelle Antworten mit minimaler Exploration. Hoher Aufwand bedeutet, das Modell nimmt sich Zeit zum tiefen Nachdenken. Sie lernen, den Aufwand an die Komplexität der Aufgabe anzupassen – verschwenden Sie keine Zeit bei einfachen Fragen, hetzen Sie aber auch komplexe Entscheidungen nicht durch. +GPT-5.2 ermöglicht es Ihnen, den Rechenaufwand über Ihre Prompts zu steuern. Niedriger Aufwand bedeutet schnelle Antworten mit minimaler Exploration. Hoher Aufwand bedeutet, dass das Modell sich Zeit nimmt, tief zu denken. Sie lernen, den Aufwand an die Komplexität der Aufgabe anzupassen – verschwenden Sie keine Zeit mit einfachen Fragen, aber überstürzen Sie auch keine komplexen Entscheidungen. **Struktur steuert Verhalten** -Fallen Ihnen die XML-Tags in den Prompts auf? Sie sind keine Dekoration. Modelle folgen strukturierten Anweisungen zuverlässiger als freien Text. Wenn Sie mehrschrittige Prozesse oder komplexe Logik benötigen, hilft Struktur dem Modell, zu verfolgen, wo es ist und was als Nächstes kommt. Das folgende Diagramm zerlegt einen gut strukturierten Prompt und zeigt, wie Tags wie ``, ``, ``, `` und `` Ihre Anweisungen in eindeutige Abschnitte gliedern. +Fallen Ihnen die XML-Tags in den Prompts auf? Sie sind nicht dekorativ. Modelle folgen strukturierten Anweisungen zuverlässiger als Freitext. Wenn Sie mehrstufige Prozesse oder komplexe Logik benötigen, hilft Struktur dem Modell, den aktuellen Schritt und das Kommende zu verfolgen. Das folgende Diagramm zerlegt einen gut strukturierten Prompt und zeigt, wie Tags wie ``, ``, ``, `` und `` Ihre Anweisungen in klare Abschnitte gliedern. -Prompt-Struktur +Prompt Structure -*Aufbau eines gut strukturierten Prompts mit klaren Abschnitten und XML-artiger Organisation* +*Anatomie eines gut strukturierten Prompts mit klaren Abschnitten und XML-ähnlicher Organisation* **Qualität durch Selbstevaluation** -Die selbstreflektierenden Muster arbeiten, indem Qualitätskriterien explizit gemacht werden. Anstatt zu hoffen, dass das Modell „richtig macht“, sagen Sie ihm genau, was „richtig“ bedeutet: korrekte Logik, Fehlerbehandlung, Leistung, Sicherheit. Das Modell kann dann seine eigene Ausgabe bewerten und verbessern. So wird das Code-Generieren vom Glücksspiel zu einem Prozess. +Die selbstreflektierenden Muster arbeiten, indem Qualitätskriterien explizit gemacht werden. Statt zu hoffen, dass das Modell „es richtig macht“, sagen Sie ihm genau, was „richtig“ bedeutet: korrekte Logik, Fehlerbehandlung, Performance, Sicherheit. Das Modell kann dann seine eigene Ausgabe bewerten und verbessern. Das verwandelt Codeerstellung von einem Glücksspiel in einen Prozess. **Kontext ist begrenzt** -Mehrstufige Gespräche arbeiten, indem sie den Nachrichtenverlauf mit jeder Anfrage einbinden. Aber es gibt ein Limit – jedes Modell hat eine maximale Token-Anzahl. Wenn Gespräche wachsen, brauchen Sie Strategien, um relevanten Kontext zu bewahren, ohne diese Grenze zu überschreiten. Dieses Modul zeigt Ihnen, wie Gedächtnis funktioniert; später lernen Sie, wann Sie zusammenfassen, vergessen und abrufen sollten. +Mehrstufige Gespräche funktionieren, indem Sie den Nachrichtenverlauf jeder Anfrage mitsenden. Aber es gibt eine Grenze – jedes Modell hat eine maximale Tokenanzahl. Wenn Gespräche wachsen, brauchen Sie Strategien, um relevanten Kontext zu behalten, ohne die Grenze zu überschreiten. Dieses Modul zeigt, wie Gedächtnis funktioniert; später lernen Sie, wann Sie zusammenfassen, vergessen oder abrufen sollen. ## Nächste Schritte @@ -598,11 +598,11 @@ Mehrstufige Gespräche arbeiten, indem sie den Nachrichtenverlauf mit jeder Anfr --- -**Navigation:** [← Zurück: Modul 01 - Einführung](../01-introduction/README.md) | [Zurück zum Hauptmenü](../README.md) | [Weiter: Modul 03 - RAG →](../03-rag/README.md) +**Navigation:** [← Vorheriges: Modul 01 – Einführung](../01-introduction/README.md) | [Zurück zum Hauptbereich](../README.md) | [Nächstes: Modul 03 – RAG →](../03-rag/README.md) --- -**Haftungsausschluss**: -Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, kann es bei automatisierten Übersetzungen zu Fehlern oder Ungenauigkeiten kommen. Das ursprüngliche Dokument in seiner Originalsprache gilt als maßgebliche Quelle. Für wichtige Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Nutzung dieser Übersetzung entstehen. +**Haftungsausschluss**: +Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Bei kritischen Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen. \ No newline at end of file diff --git a/translations/de/03-rag/README.md b/translations/de/03-rag/README.md index 2b624be6c..001e1bfd4 100644 --- a/translations/de/03-rag/README.md +++ b/translations/de/03-rag/README.md @@ -2,31 +2,31 @@ ## Inhaltsverzeichnis -- [Video Walkthrough](../../../03-rag) -- [Was Sie lernen werden](../../../03-rag) -- [Voraussetzungen](../../../03-rag) -- [Verständnis von RAG](../../../03-rag) - - [Welchen RAG-Ansatz verwendet dieses Tutorial?](../../../03-rag) -- [Wie es funktioniert](../../../03-rag) - - [Dokumentenverarbeitung](../../../03-rag) - - [Erstellung von Embeddings](../../../03-rag) - - [Semantische Suche](../../../03-rag) - - [Antwortgenerierung](../../../03-rag) -- [Anwendung ausführen](../../../03-rag) -- [Anwendung verwenden](../../../03-rag) - - [Dokument hochladen](../../../03-rag) - - [Fragen stellen](../../../03-rag) - - [Quellen überprüfen](../../../03-rag) - - [Experimente mit Fragen](../../../03-rag) -- [Wichtige Konzepte](../../../03-rag) - - [Chunking-Strategie](../../../03-rag) - - [Ähnlichkeitsscores](../../../03-rag) - - [In-Memory-Speicherung](../../../03-rag) - - [Verwaltung des Kontextfensters](../../../03-rag) -- [Wann RAG wichtig ist](../../../03-rag) -- [Nächste Schritte](../../../03-rag) - -## Video Walkthrough +- [Video-Durchlauf](#video-durchlauf) +- [Was Sie lernen werden](#was-sie-lernen-werden) +- [Voraussetzungen](#voraussetzungen) +- [Verstehen von RAG](#verstehen-von-rag) + - [Welchen RAG-Ansatz verwendet dieses Tutorial?](#welchen-rag-ansatz-verwendet-dieses-tutorial) +- [Wie es funktioniert](#wie-es-funktioniert) + - [Dokumentenverarbeitung](#dokumentenverarbeitung) + - [Erstellen von Embeddings](#erstellen-von-embeddings) + - [Semantische Suche](#semantische-suche) + - [Antwortgenerierung](#antwortgenerierung) +- [Anwendung ausführen](#anwendung-starten) +- [Verwendung der Anwendung](#nutzung-der-anwendung) + - [Dokument hochladen](#dokument-hochladen) + - [Fragen stellen](#fragen-stellen) + - [Quellen nachprüfen](#quellverweise-prüfen) + - [Mit Fragen experimentieren](#mit-fragen-experimentieren) +- [Schlüsselkonzepte](#schlüsselkonzepte) + - [Chunking-Strategie](#chunking-strategie) + - [Ähnlichkeitswerte](#ähnlichkeitsscores) + - [In-Memory-Speicherung](#speicher-im-arbeitsspeicher) + - [Management des Kontextfensters](#verwaltung-des-kontextfensters) +- [Wann RAG wichtig ist](#wann-rag-relevant-ist) +- [Nächste Schritte](#nächste-schritte) + +## Video-Durchlauf Sehen Sie sich diese Live-Session an, die erklärt, wie Sie mit diesem Modul starten: @@ -34,111 +34,110 @@ Sehen Sie sich diese Live-Session an, die erklärt, wie Sie mit diesem Modul sta ## Was Sie lernen werden -In den vorherigen Modulen haben Sie gelernt, wie Sie Gespräche mit KI führen und Ihre Prompts effektiv strukturieren. Aber es gibt eine grundlegende Einschränkung: Sprachmodelle kennen nur das, was sie während des Trainings gelernt haben. Sie können keine Fragen zu den Unternehmensrichtlinien, Ihrer Projektdokumentation oder Informationen beantworten, zu denen sie nicht trainiert wurden. +In den vorherigen Modulen haben Sie gelernt, wie man Gespräche mit KI führt und Prompts effektiv strukturiert. Aber es gibt eine grundlegende Einschränkung: Sprachmodelle kennen nur das, was sie während des Trainings gelernt haben. Sie können keine Fragen zu den Richtlinien Ihres Unternehmens, Ihrer Projektdokumentation oder zu Informationen beantworten, die sie nicht trainiert wurden. -RAG (Retrieval-Augmented Generation) löst dieses Problem. Anstatt dem Modell Ihre Informationen beizubringen (was teuer und unpraktisch ist), geben Sie ihm die Fähigkeit, in Ihren Dokumenten zu suchen. Wenn jemand eine Frage stellt, findet das System relevante Informationen und fügt diese in den Prompt ein. Das Modell antwortet dann auf Grundlage dieses abgerufenen Kontexts. +RAG (Retrieval-Augmented Generation) löst dieses Problem. Anstatt zu versuchen, dem Modell Ihre Informationen beizubringen (was teuer und unpraktisch ist), geben Sie ihm die Fähigkeit, Ihre Dokumente zu durchsuchen. Wenn jemand eine Frage stellt, findet das System relevante Informationen und fügt sie dem Prompt hinzu. Das Modell antwortet dann basierend auf diesem abgerufenen Kontext. -Stellen Sie sich RAG vor wie eine Referenzbibliothek für das Modell. Wenn Sie eine Frage stellen, erledigt das System: +Denken Sie bei RAG daran, dem Modell eine Referenzbibliothek zu geben. Wenn Sie eine Frage stellen, tut das System Folgendes: 1. **Benutzeranfrage** – Sie stellen eine Frage 2. **Embedding** – Wandelt Ihre Frage in einen Vektor um -3. **Vektorsuche** – Findet ähnliche Dokumentenabschnitte -4. **Kontextaufbau** – Fügt relevante Abschnitte zum Prompt hinzu -5. **Antwort** – Das LLM generiert eine Antwort basierend auf dem Kontext +3. **Vektorsuche** – Findet ähnliche Dokumentabschnitte +4. **Kontextzusammenstellung** – Fügt relevante Abschnitte dem Prompt hinzu +5. **Antwort** – LLM generiert basierend auf dem Kontext eine Antwort -Dies verankert die Antworten des Modells in Ihren tatsächlichen Daten, anstatt sich auf sein Trainingswissen zu verlassen oder Antworten zu erfinden. +Das verankert die Antworten des Modells in Ihren tatsächlichen Daten, statt sich auf Trainingswissen zu verlassen oder Antworten zu erfinden. ## Voraussetzungen -- Abgeschlossenes [Modul 00 - Quick Start](../00-quick-start/README.md) (für das Easy RAG-Beispiel, das später in diesem Modul genannt wird) -- Abgeschlossenes [Modul 01 - Einführung](../01-introduction/README.md) (Azure OpenAI Ressourcen bereitgestellt, einschließlich des `text-embedding-3-small` Embedding-Modells) -- `.env`-Datei im Stammverzeichnis mit Azure-Anmeldeinformationen (erstellt durch `azd up` in Modul 01) +- Abgeschlossenes [Modul 01 – Einführung](../01-introduction/README.md) (Azure OpenAI-Ressourcen bereitgestellt, einschließlich des Embedding-Modells `text-embedding-3-small`) +- `.env`-Datei im Stammverzeichnis mit Azure-Zugangsdaten (erstellt durch `azd up` in Modul 01) -> **Hinweis:** Wenn Sie Modul 01 nicht abgeschlossen haben, folgen Sie zunächst dort den Bereitstellungsanweisungen. Der Befehl `azd up` stellt sowohl das GPT-Chat-Modell als auch das Embedding-Modell bereit, das in diesem Modul verwendet wird. +> **Hinweis:** Wenn Sie Modul 01 nicht abgeschlossen haben, folgen Sie zunächst den dortigen Bereitstellungsanweisungen. Der Befehl `azd up` stellt sowohl das GPT-Chatmodell als auch das Embedding-Modell bereit, das in diesem Modul verwendet wird. -## Verständnis von RAG +## Verstehen von RAG -Die folgende Grafik illustriert das Kernkonzept: Anstatt sich nur auf die Trainingsdaten des Modells zu verlassen, erhält RAG eine Referenzbibliothek Ihrer Dokumente, die vor der Antwortgenerierung konsultiert wird. +Das untenstehende Diagramm veranschaulicht das Kernkonzept: Anstatt sich nur auf das Trainingsmaterial des Modells zu verlassen, gibt RAG ihm eine Referenzbibliothek Ihrer Dokumente, die es vor jeder Antwort abruft. Was ist RAG -*Dieses Diagramm zeigt den Unterschied zwischen einem Standard-LLM (das auf Trainingsdaten schätzt) und einem RAG-verbesserten LLM (das zuerst Ihre Dokumente konsultiert).* +*Dieses Diagramm zeigt den Unterschied zwischen einem Standard-LLM (das aus Trainingsdaten rät) und einem RAG-verbesserten LLM (das zunächst Ihre Dokumente konsultiert).* -So verbinden sich die Teile von Anfang bis Ende. Die Frage eines Benutzers durchläuft vier Phasen – Embedding, Vektorsuche, Kontextaufbau und Antwortgenerierung – die jeweils auf der vorherigen aufbauen: +So sind die Bausteine Ende-zu-Ende verbunden. Die Benutzerfrage durchläuft vier Stufen: Embedding, Vektorsuche, Kontextzusammenstellung und Antwortgenerierung – wobei jede auf der vorherigen aufbaut: RAG Architektur -*Dieses Diagramm zeigt die End-to-End RAG-Pipeline – eine Benutzeranfrage durchläuft Embedding, Vektorsuche, Kontextaufbau und Antwortgenerierung.* +*Dieses Diagramm zeigt die Ende-zu-Ende RAG-Pipeline — eine Benutzeranfrage durchläuft Embedding, Vektorsuche, Kontextzusammenstellung und Antwortgenerierung.* -Der Rest dieses Moduls führt Sie durch jede Phase im Detail, mit Code, den Sie ausführen und anpassen können. +Der Rest dieses Moduls führt Sie detailliert durch jede Stufe mit ausführbarem und modifizierbarem Code. ### Welchen RAG-Ansatz verwendet dieses Tutorial? -LangChain4j bietet drei Möglichkeiten, RAG zu implementieren, jeweils mit unterschiedlicher Abstraktionsebene. Das Diagramm unten vergleicht sie nebeneinander: +LangChain4j bietet drei Wege, RAG umzusetzen, jeweils mit unterschiedlicher Abstraktionsebene. Das folgende Diagramm vergleicht sie nebeneinander: Drei RAG-Ansätze in LangChain4j -*Dieses Diagramm vergleicht die drei LangChain4j RAG-Ansätze – Easy, Native und Advanced – zeigt deren Hauptkomponenten und wann man sie einsetzt.* +*Dieses Diagramm vergleicht die drei LangChain4j RAG-Ansätze – Easy, Native und Advanced – zeigt deren Hauptkomponenten und wann man welchen nutzt.* | Ansatz | Was er tut | Kompromiss | |---|---|---| -| **Easy RAG** | Verkabelt alles automatisch über `AiServices` und `ContentRetriever`. Sie annotieren ein Interface, hängen einen Retriever an, und LangChain4j kümmert sich hinter den Kulissen um Embedding, Suche und Prompt-Erstellung. | Minimaler Code, aber Sie sehen nicht, was in jedem Schritt passiert. | -| **Native RAG** | Sie rufen das Embedding-Modell auf, durchsuchen den Speicher, bauen den Prompt zusammen und generieren die Antwort – Schritt für Schritt explizit. | Mehr Code, aber jede Phase ist sichtbar und änderbar. | -| **Advanced RAG** | Verwendet das `RetrievalAugmentor` Framework mit einsteckbaren Query-Transformern, Routern, Neu-Rankern und Content-Injectoren für produktionsreife Pipelines. | Maximale Flexibilität, aber deutlich komplexer. | +| **Easy RAG** | Verbindet alles automatisch über `AiServices` und `ContentRetriever`. Sie annotieren ein Interface, hängen einen Retriever an, und LangChain4j übernimmt Einbettung, Suche und Prompt-Erstellung im Hintergrund. | Minimale Codezeilen, aber Sie sehen nicht, was intern passiert. | +| **Native RAG** | Sie rufen das Embedding-Modell, durchsuchen den Speicher, bauen den Prompt und generieren die Antwort explizit selbst – Schritt für Schritt. | Mehr Code, aber jede Stufe ist sichtbar und anpassbar. | +| **Advanced RAG** | Nutzt das `RetrievalAugmentor`-Framework mit modularen Query-Transformern, Routern, Re-Rankern und Content-Injectoren für produktionsreife Pipelines. | Maximale Flexibilität, aber deutlich komplexer. | -**Dieses Tutorial verwendet den Native-Ansatz.** Jeder Schritt der RAG-Pipeline – das Einbetten der Anfrage, das Durchsuchen des Vektorspeichers, das Zusammenstellen des Kontexts und das Generieren der Antwort – ist explizit in [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) beschrieben. Dies ist bewusst so: als Lernressource ist es wichtiger, dass Sie jede Phase sehen und verstehen, als dass der Code minimal gehalten wird. Sobald Sie sich mit dem Zusammenspiel der Teile sicher fühlen, können Sie für schnelle Prototypen zu Easy RAG wechseln oder für Produktivsysteme Advanced RAG nutzen. +**Dieses Tutorial verwendet den Native-Ansatz.** Jeder Schritt der RAG-Pipeline – Einbettung der Anfrage, Durchsuchung des Vektorspeichers, Kontextzusammenstellung und Antwortgenerierung – wird explizit in [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) beschrieben. Das ist bewusst gewählt: Als Lernressource ist es wichtiger, jede Phase zu sehen und zu verstehen, als minimalen Code zu schreiben. Sobald Sie komfortabel sind mit den Abläufen, können Sie auf Easy RAG für schnelle Prototypen oder Advanced RAG für Produktivsysteme umsteigen. -> **💡 Easy RAG schon gesehen?** Das [Quick Start-Modul](../00-quick-start/README.md) enthält ein Beispiel für Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), das Easy RAG nutzt – LangChain4j übernimmt automatisch Embedding, Suche und Prompt-Erstellung. Dieses Modul geht einen Schritt weiter und öffnet diese Pipeline, sodass Sie jede Phase selbst sehen und steuern können. +> **💡 Neugierig auf Easy RAG?** LangChain4j bietet auch einen *Easy RAG* Ansatz, bei dem `AiServices` und ein `ContentRetriever` Einbettung, Suche und Prompt-Erstellung automatisch übernehmen. Dieses Modul nimmt den expliziten Weg — es öffnet die Pipeline, damit Sie jede Stufe selbst sehen und steuern können. -Das folgende Diagramm zeigt die Easy RAG-Pipeline aus dem Quick Start-Beispiel. Beachten Sie, wie `AiServices` und `EmbeddingStoreContentRetriever` alle Komplexität verbergen – Sie laden ein Dokument, hängen einen Retriever an und erhalten Antworten. Der Native-Ansatz in diesem Modul öffnet jeden dieser versteckten Schritte: +Das folgende Diagramm zeigt die Easy RAG-Pipeline. Beachten Sie, wie `AiServices` und `EmbeddingStoreContentRetriever` die ganze Komplexität verstecken — Sie laden ein Dokument, hängen einen Retriever an und erhalten Antworten. Der Native-Ansatz dieses Moduls öffnet jede dieser verborgenen Stufen: Easy RAG Pipeline - LangChain4j -*Dieses Diagramm zeigt die Easy RAG-Pipeline aus `SimpleReaderDemo.java`. Vergleichen Sie dies mit dem Native-Ansatz in diesem Modul: Easy RAG verbirgt Embedding, Retrieval und Prompt-Erstellung hinter `AiServices` und `ContentRetriever` – Sie laden ein Dokument, hängen einen Retriever an und erhalten Antworten. Der Native-Ansatz in diesem Modul öffnet diese Pipeline, sodass Sie jede Phase (einbetten, suchen, Kontext zusammenstellen, generieren) selbst aufrufen und volle Transparenz und Kontrolle haben.* +*Dieses Diagramm zeigt die Easy RAG-Pipeline. Vergleichen Sie dies mit dem Native-Ansatz aus diesem Modul: Easy RAG versteckt Einbettung, Abruf und Prompt-Erstellung hinter `AiServices` und `ContentRetriever` — Sie laden ein Dokument, hängen einen Retriever an und erhalten Antworten. Der Native-Ansatz hier öffnet diese Pipeline, so dass Sie jede Stufe (Einbetten, Suchen, Kontext zusammenstellen, generieren) selbst aufrufen und so volle Kontrolle und Sichtbarkeit erhalten.* ## Wie es funktioniert -Die RAG-Pipeline in diesem Modul gliedert sich in vier Phasen, die nacheinander ablaufen, sobald ein Benutzer eine Frage stellt. Zuerst wird ein hochgeladenes Dokument **geparst und in Chunks zerlegt** – handhabbare Stücke. Diese Chunks werden dann in **Vektor-Embeddings** umgewandelt und gespeichert, damit sie mathematisch verglichen werden können. Wenn eine Anfrage eintrifft, führt das System eine **semantische Suche** durch, um die relevantesten Chunks zu finden, und übergibt diese schließlich als Kontext an das LLM für die **Antwortgenerierung**. Die folgenden Abschnitte erläutern jede Phase mit tatsächlichem Code und Diagrammen. Sehen wir uns den ersten Schritt genauer an. +Die RAG-Pipeline in diesem Modul zerfällt in vier Stufen, die bei jeder Benutzerfrage nacheinander ausgeführt werden. Zuerst wird ein hochgeladenes Dokument **geparst und in Chunks zerlegt**. Diese Chunks werden dann in **Vektor-Embeddings** umgewandelt und gespeichert, damit sie mathematisch verglichen werden können. Sobald eine Anfrage eintrifft, führt das System eine **semantische Suche** durch, um die relevantesten Chunks zu finden, und übergibt diese schließlich als Kontext an das LLM zur **Antwortgenerierung**. Die folgenden Abschnitte erläutern jede Stufe mit echtem Code und Diagrammen. Fangen wir mit dem ersten Schritt an. ### Dokumentenverarbeitung [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Wenn Sie ein Dokument hochladen, wird es geparst (PDF oder reiner Text), mit Metadaten wie Dateiname versehen und anschließend in Chunks zerlegt – kleinere Abschnitte, die gut in das Kontextfenster des Modells passen. Diese Chunks überlappen leicht, damit an den Grenzen kein Kontext verloren geht. +Wenn Sie ein Dokument hochladen, parst das System es (PDF oder Klartext), hängt Metadaten wie den Dateinamen an und zerlegt es danach in Chunks — kleinere Stücke, die bequem in das Kontextfenster des Modells passen. Diese Chunks überlappen leicht, damit kein Kontext an den Grenzen verloren geht. ```java // Analysiere die hochgeladene Datei und verpacke sie in ein LangChain4j-Dokument Document document = Document.from(content, metadata); -// Teile es in 300-Token-Stücke mit 30-Token-Überlappung auf +// Teile in 300-Token-Segmente mit 30-Token-Überlappung auf DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Das folgende Diagramm zeigt, wie das visuell funktioniert. Beachten Sie, wie jeder Chunk einige Tokens mit den Nachbarn teilt – die 30-Token-Überlappung stellt sicher, dass kein wichtiger Kontext durch die Lappen geht: +Das folgende Diagramm zeigt diesen Vorgang visuell. Beachten Sie, dass jeder Chunk einige Tokens mit seinen Nachbarn teilt — die 30-Token-Überlappung stellt sicher, dass kein wichtiger Kontext verloren geht: -Dokumenten-Chucking +Dokumenten-Zerlegung -*Dieses Diagramm zeigt ein Dokument, aufgeteilt in 300-Token-Chunks mit 30-Token-Überlappung, um Kontext an den Chunk-Grenzen zu bewahren.* +*Dieses Diagramm zeigt ein Dokument, das in 300-Token-Chunks mit 30-Token-Überlappung zerlegt wird, um Kontext an Chunk-Grenzen zu erhalten.* > **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) und fragen Sie: -> - „Wie zerlegt LangChain4j Dokumente in Chunks und warum ist Überlappung wichtig?“ -> - „Was ist die optimale Chunk-Größe für verschiedene Dokumenttypen und warum?“ -> - „Wie gehe ich mit mehrsprachigen Dokumenten oder spezieller Formatierung um?“ +> - "Wie zerlegt LangChain4j Dokumente in Chunks und warum ist Überlappung wichtig?" +> - "Was ist die optimale Chunk-Größe für verschiedene Dokumenttypen und warum?" +> - "Wie gehe ich mit Dokumenten in mehreren Sprachen oder mit spezieller Formatierung um?" -### Erstellung von Embeddings +### Erstellen von Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Jeder Chunk wird in eine numerische Darstellung umgewandelt, die als Embedding bezeichnet wird – im Grunde ein Bedeutungs-zu-Zahlen-Wandler. Das Embedding-Modell ist nicht „intelligent“ wie ein Chat-Modell; es kann keine Anweisungen befolgen, nicht vernunftbasiert antworten oder Fragen beantworten. Es ordnet Text lediglich in einem mathematischen Raum an, in dem ähnliche Bedeutungen nah beieinander liegen – „Auto“ nahe „Automobil“, „Rückgaberichtlinie“ nahe „Geld zurück“. Man kann sich ein Chat-Modell als eine Person vorstellen, mit der man sprechen kann; ein Embedding-Modell ist ein hochleistungsfähiges Ablagesystem. +Jeder Chunk wird in eine numerische Repräsentation umgewandelt, die als Embedding bezeichnet wird — im Grunde ein Bedeutungs-in-Zahlen-Konverter. Das Embedding-Modell ist nicht "intelligent" wie ein Chatmodell; es kann keine Anweisungen folgen, nicht vernünftig argumentieren und keine Fragen beantworten. Was es kann, ist Text in einen mathematischen Raum zu mappen, in dem ähnliche Bedeutungen nahe beieinander liegen — „Auto“ nahe „Kraftfahrzeug“, „Rückerstattungsrichtlinie“ nahe „Geld zurück“. Man kann sich ein Chatmodell als eine Person vorstellen, mit der man sprechen kann; ein Embedding-Modell ist ein ultraschlaues Ablagesystem. -Das folgende Diagramm visualisiert dieses Konzept – Text geht rein, numerische Vektoren kommen raus, und ähnliche Bedeutungen erzeugen benachbarte Vektoren: +Das folgende Diagramm visualisiert dieses Konzept — Text geht rein, numerische Vektoren kommen raus, und ähnliche Bedeutungen erzeugen benachbarte Vektoren: -Embedding-Modell Konzept +Embedding-Modell-Konzept -*Dieses Diagramm zeigt, wie ein Embedding-Modell Text in numerische Vektoren umwandelt und ähnliche Bedeutungen – wie „Auto“ und „Automobil“ – im Vektorraum nahe beieinander platziert.* +*Dieses Diagramm zeigt, wie ein Embedding-Modell Text in numerische Vektoren umwandelt, die ähnliche Bedeutungen – wie „Auto“ und „Kraftfahrzeug“ – im Vektorraum nahe beieinander platzieren.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Das Klassendiagramm unten zeigt die zwei getrennten Abläufe in einer RAG-Pipeline und die LangChain4j-Klassen, die sie implementieren. Der **Ingestion-Flow** (läuft einmal beim Upload) zerlegt das Dokument, bettet die Chunks ein und speichert sie via `.addAll()`. Der **Query-Flow** (läuft bei jeder Benutzeranfrage) bettet die Frage ein, durchsucht den Speicher via `.search()` und übergibt den passenden Kontext an das Chat-Modell. Beide Flows treffen sich an der gemeinsamen Schnittstelle `EmbeddingStore`: +Das Klassendiagramm unten zeigt die zwei getrennten Abläufe in einer RAG-Pipeline und die LangChain4j-Klassen, die sie implementieren. Der **Ingestions-Flow** (läuft einmal beim Hochladen) zerlegt das Dokument, erzeugt Embeddings der Chunks und speichert sie über `.addAll()`. Der **Query-Flow** (läuft bei jeder Benutzeranfrage) erzeugt ein Embedding der Frage, durchsucht den Speicher via `.search()` und übergibt den passenden Kontext ans Chatmodell. Beide Flows treffen auf das gemeinsame Interface `EmbeddingStore`: -LangChain4j RAG Klassen +LangChain4j RAG-Klassen -*Dieses Diagramm zeigt die zwei Abläufe in einer RAG-Pipeline – Ingestion und Query – und wie sie über einen gemeinsamen EmbeddingStore verbunden sind.* +*Dieses Diagramm zeigt die zwei Abläufe in einer RAG-Pipeline – Ingestion und Query – und wie sie über ein gemeinsames EmbeddingStore verbunden sind.* -Sobald Embeddings gespeichert sind, clustern sich ähnliche Inhalte automatisch im Vektorraum. Die folgende Visualisierung zeigt, wie Dokumente zu verwandten Themen als nahe beieinander liegende Punkte erscheinen, was die semantische Suche ermöglicht: +Sobald die Embeddings gespeichert sind, clustert ähnlicher Inhalt natürlich im Vektorraum. Die Visualisierung unten zeigt, wie Dokumente zu verwandten Themen als nahe Punkte enden, was semantische Suche möglich macht: -Vektor-Embeddings Raum +Vektor-Embeddings-Raum -*Diese Visualisierung zeigt, wie verwandte Dokumente im 3D-Vektorraum clustern, mit Themen wie technische Dokumentation, Geschäftsregeln und FAQs, die jeweils eigene Gruppen bilden.* +*Diese Visualisierung zeigt, wie verwandte Dokumente im 3D-Vektorraum clustern, wobei Themen wie technische Dokumente, Geschäftsregeln und FAQs eigene Gruppen bilden.* -Wenn ein Benutzer eine Suche startet, folgen vier Schritte: Dokumente einmal einbetten, die Anfrage bei jeder Suche einbetten, den Anfragevektor mit allen gespeicherten Vektoren per Kosinusähnlichkeit vergleichen und die top-K höchstbewerteten Chunks zurückgeben. Das folgende Diagramm zeigt jeden Schritt und die beteiligten LangChain4j-Klassen: +Wenn ein Nutzer sucht, führt das System vier Schritte aus: Dokumente einmal einbetten, die Anfrage bei jeder Suche einbetten, den Anfragevektor mit allen gespeicherten Vektoren anhand des Kosinus-Ähnlichkeitsmaßes vergleichen und die besten K-Chunk-Ergebnisse zurückgeben. Das folgende Diagramm erläutert jeden Schritt sowie die beteiligten LangChain4j-Klassen: -Embedding-Suchschritte +Schritte der Embedding-Suche -*Dieses Diagramm zeigt den vierstufigen Embedding-Suchprozess: Dokumente einbetten, Anfrage einbetten, Vektoren per Kosinusähnlichkeit vergleichen und die Top-K-Ergebnisse zurückgeben.* +*Dieses Diagramm zeigt den vierstufigen Suchprozess mit Embeddings: Dokumente einbetten, Anfrage einbetten, Vektoren mit Kosinus-Ähnlichkeit vergleichen und die Top-K-Ergebnisse zurückgeben.* ### Semantische Suche [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Wenn Sie eine Frage stellen, wird auch Ihre Frage zu einem Embedding. Das System vergleicht das Embedding Ihrer Frage mit allen Embeddings der Dokumenten-Chunks. Es findet die Chunks mit den ähnlichsten Bedeutungen – nicht nur passende Schlüsselwörter, sondern tatsächliche semantische Ähnlichkeit. +Wenn Sie eine Frage stellen, wird auch Ihre Frage eingebettet. Das System vergleicht das Embedding Ihrer Frage mit allen Embeddings der Dokumentenchunks. Es findet die Chunks mit der semantisch ähnlichsten Bedeutung – nicht nur mit passenden Schlüsselwörtern, sondern tatsächlicher semantischer Übereinstimmung. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Das folgende Diagramm stellt semantische Suche einer traditionellen Keyword-Suche gegenüber. Eine Keyword-Suche nach „Fahrzeug“ übersieht einen Chunk über „Autos und Lastwagen“, aber die semantische Suche versteht, dass sie dasselbe meinen, und gibt ihn als hoch bewertetes Ergebnis zurück: +Das folgende Diagramm stellt semantische Suche der traditionellen Schlüsselwortsuche gegenüber. Eine Schlüsselwortsuche nach „Fahrzeug“ verpasst einen Chunk über „Autos und Lastwagen“, während die semantische Suche versteht, dass das dasselbe bedeutet, und ihn als hoch-relevantes Ergebnis zurückgibt: Semantische Suche -*Dieses Diagramm vergleicht die schlüsselwortbasierte Suche mit der semantischen Suche und zeigt, wie die semantische Suche konzeptionell verwandte Inhalte abruft, auch wenn die exakten Keywords unterschiedlich sind.* -Unter der Haube wird Ähnlichkeit mit Kosinusähnlichkeit gemessen – im Wesentlichen wird gefragt: "Zeigen diese beiden Pfeile in dieselbe Richtung?" Zwei Abschnitte können völlig unterschiedliche Wörter verwenden, aber wenn sie dasselbe bedeuten, zeigen ihre Vektoren in dieselbe Richtung und erreichen einen Wert nahe 1,0: +*Dieses Diagramm vergleicht schlüsselwortbasierte Suche mit semantischer Suche und zeigt, wie semantische Suche konzeptuell verwandte Inhalte abruft, auch wenn exakte Schlüsselwörter unterschiedlich sind.* -Kosinusähnlichkeit +Im Hintergrund wird Ähnlichkeit mittels Kosinus-Ähnlichkeit gemessen – im Grunde die Frage „zeigen diese zwei Pfeile in dieselbe Richtung?“ Zwei Chunks können völlig unterschiedliche Wörter verwenden, aber wenn sie dasselbe bedeuten, zeigen ihre Vektoren in dieselbe Richtung und erreichen einen Wert nahe 1.0: -*Dieses Diagramm veranschaulicht die Kosinusähnlichkeit als den Winkel zwischen Einbettungsvektoren – besser ausgerichtete Vektoren erreichen Werte näher an 1,0, was auf eine höhere semantische Ähnlichkeit hinweist.* +Kosinus-Ähnlichkeit +*Dieses Diagramm veranschaulicht die Kosinusähnlichkeit als den Winkel zwischen Einbettungsvektoren — stärker ausgerichtete Vektoren erzielen Werte näher bei 1,0, was auf eine höhere semantische Ähnlichkeit hinweist.* -> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) und fragen Sie: -> - "Wie funktioniert die Ähnlichkeitssuche mit Einbettungen und was bestimmt den Wert?" -> - "Welchen Ähnlichkeitsschwellenwert sollte ich verwenden und wie wirkt sich das auf die Ergebnisse aus?" -> - "Wie gehe ich mit Fällen um, in denen keine relevanten Dokumente gefunden werden?" +> **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat aus:** Öffnen Sie [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) und fragen Sie: +> - „Wie funktioniert die Ähnlichkeitssuche mit Einbettungen und was bestimmt den Score?“ +> - „Welchen Ähnlichkeitsschwellenwert sollte ich verwenden und wie beeinflusst er die Ergebnisse?“ +> - „Wie gehe ich mit Fällen um, in denen keine relevanten Dokumente gefunden werden?“ ### Antwortgenerierung [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Die relevantesten Abschnitte werden zu einem strukturierten Prompt zusammengefügt, der explizite Anweisungen, den abgerufenen Kontext und die Frage des Benutzers enthält. Das Modell liest diese spezifischen Abschnitte und antwortet basierend auf diesen Informationen – es kann nur das verwenden, was ihm gerade vorliegt, was Halluzinationen verhindert. +Die relevantesten Chunks werden zu einem strukturierten Prompt zusammengefügt, der explizite Anweisungen, den abgerufenen Kontext und die Frage des Nutzers enthält. Das Modell liest diese spezifischen Chunks und antwortet basierend auf diesen Informationen — es kann nur das verwenden, was ihm vorliegt, was Halluzinationen verhindert. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Das folgende Diagramm zeigt diese Zusammenstellung in Aktion – die höchstbewerteten Abschnitte aus dem Suchschritt werden in die Prompt-Vorlage eingefügt, und das `OpenAiOfficialChatModel` erzeugt eine fundierte Antwort: +Das folgende Diagramm zeigt diese Zusammenstellung in Aktion — die bestbewerteten Chunks aus dem Suchschritt werden in die Prompt-Vorlage eingespeist, und das `OpenAiOfficialChatModel` generiert eine fundierte Antwort: -Kontextzusammenstellung +Kontext-Zusammenstellung -*Dieses Diagramm zeigt, wie die höchstbewerteten Abschnitte in einen strukturierten Prompt zusammengefügt werden, wodurch das Modell eine fundierte Antwort aus Ihren Daten generieren kann.* +*Dieses Diagramm zeigt, wie die bestbewerteten Chunks zu einem strukturierten Prompt zusammengesetzt werden, damit das Modell eine fundierte Antwort aus Ihren Daten generieren kann.* ## Anwendung starten -**Bereitstellung prüfen:** +**Bereitstellung überprüfen:** -Stellen Sie sicher, dass die `.env`-Datei mit Azure-Anmeldedaten im Stammverzeichnis vorhanden ist (wurde im Modul 01 erstellt). Führen Sie dies aus dem Modulverzeichnis (`03-rag/`) aus: +Stellen Sie sicher, dass die `.env`-Datei im Stammverzeichnis mit Azure-Anmeldeinformationen vorhanden ist (wurde im Modul 01 erstellt). Führen Sie diesen Befehl im Modulverzeichnis (`03-rag/`) aus: **Bash:** ```bash @@ -261,19 +260,19 @@ Get-Content ..\.env # Sollte AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT anzeige **Starten Sie die Anwendung:** -> **Hinweis:** Wenn Sie alle Anwendungen bereits mit `./start-all.sh` aus dem Stammverzeichnis gestartet haben (wie in Modul 01 beschrieben), läuft dieses Modul bereits auf Port 8081. Sie können die Startbefehle unten überspringen und direkt zu http://localhost:8081 gehen. +> **Hinweis:** Wenn Sie bereits alle Anwendungen mit `./start-all.sh` vom Stammverzeichnis aus gestartet haben (wie im Modul 01 beschrieben), läuft dieses Modul bereits auf Port 8081. Sie können die Startbefehle unten überspringen und direkt http://localhost:8081 aufrufen. **Option 1: Verwendung des Spring Boot Dashboards (Empfohlen für VS Code Benutzer)** -Der Dev-Container enthält die Erweiterung Spring Boot Dashboard, die eine visuelle Oberfläche zur Verwaltung aller Spring Boot Anwendungen bietet. Sie finden sie in der Aktivitätsleiste auf der linken Seite von VS Code (Achten Sie auf das Spring Boot Symbol). +Der Dev-Container enthält die Spring Boot Dashboard-Erweiterung, die eine visuelle Oberfläche zur Verwaltung aller Spring Boot-Anwendungen bietet. Sie finden sie in der Aktivitätsleiste links in VS Code (suchen Sie das Spring Boot-Symbol). -Im Spring Boot Dashboard können Sie: -- Alle verfügbaren Spring Boot Anwendungen im Workspace sehen -- Anwendungen mit einem Klick starten/stoppen -- Echtzeit-Logs der Anwendungen einsehen -- Den Anwendungsstatus überwachen +Über das Spring Boot Dashboard können Sie: +- Alle verfügbaren Spring Boot-Anwendungen im Arbeitsbereich sehen +- Anwendungen mit einem einzigen Klick starten/stoppen +- Anwendungsprotokolle in Echtzeit anzeigen +- Anwendungsstatus überwachen -Klicken Sie einfach auf den Play-Button neben „rag“, um dieses Modul zu starten, oder starten Sie alle Module auf einmal. +Klicken Sie einfach auf die Wiedergabetaste neben „rag“, um dieses Modul zu starten, oder starten Sie alle Module auf einmal. Spring Boot Dashboard @@ -309,16 +308,16 @@ cd 03-rag .\start.ps1 ``` -Beide Skripte laden automatisch die Umgebungsvariablen aus der `.env`-Datei im Stammverzeichnis und erzeugen die JARs, falls sie noch nicht existieren. +Beide Skripte laden automatisch Umgebungsvariablen aus der `.env`-Datei im Stammverzeichnis und bauen die JARs, falls diese noch nicht existieren. -> **Hinweis:** Wenn Sie alle Module lieber manuell bauen möchten, bevor Sie starten: +> **Hinweis:** Wenn Sie alle Module lieber manuell vor dem Start bauen möchten: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -343,9 +342,9 @@ cd .. && ./stop-all.sh # Alle Module cd ..; .\stop-all.ps1 # Alle Module ``` -## Anwendung benutzen +## Nutzung der Anwendung -Die Anwendung bietet eine Weboberfläche zum Hochladen von Dokumenten und zur Fragestellung. +Die Anwendung bietet eine Web-Oberfläche zum Hochladen von Dokumenten und zum Stellen von Fragen. RAG-Anwendungsoberfläche @@ -353,69 +352,69 @@ Die Anwendung bietet eine Weboberfläche zum Hochladen von Dokumenten und zur Fr ### Dokument hochladen -Beginnen Sie mit dem Hochladen eines Dokuments – am besten eignen sich TXT-Dateien für Tests. In diesem Verzeichnis liegt eine Datei `sample-document.txt`, die Informationen über LangChain4j-Funktionen, RAG-Implementierung und Best Practices enthält – perfekt zum Testen des Systems. +Beginnen Sie mit dem Hochladen eines Dokuments – TXT-Dateien eignen sich zum Testen am besten. Eine `sample-document.txt` liegt in diesem Verzeichnis vor, die Informationen über LangChain4j-Funktionen, RAG-Implementierung und Best Practices enthält – perfekt zum Testen des Systems. -Das System verarbeitet Ihr Dokument, teilt es in Abschnitte auf und erstellt Einbettungen für jeden Abschnitt. Dies geschieht automatisch beim Hochladen. +Das System verarbeitet Ihr Dokument, zerlegt es in Chunks und erstellt für jeden Chunk Einbettungen. Dies geschieht automatisch beim Hochladen. ### Fragen stellen -Stellen Sie jetzt spezifische Fragen zum Dokumentinhalt. Versuchen Sie etwas Faktisches, das klar im Dokument steht. Das System sucht nach relevanten Abschnitten, fügt diese in den Prompt ein und generiert eine Antwort. +Stellen Sie nun spezifische Fragen zum Dokumentinhalt. Probieren Sie etwas Faktisches, das im Dokument klar angegeben ist. Das System sucht nach relevanten Chunks, bindet diese in den Prompt ein und generiert eine Antwort. -### Quellen prüfen +### Quellverweise prüfen -Beachten Sie, dass jede Antwort Quellenverweise mit Ähnlichkeitspunkten enthält. Diese Werte (0 bis 1) zeigen, wie relevant jeder Abschnitt für Ihre Frage war. Höhere Werte bedeuten bessere Übereinstimmungen. So können Sie die Antwort mit dem Quellmaterial abgleichen. +Jede Antwort enthält Quellverweise mit Ähnlichkeitsscores. Diese Scores (0 bis 1) zeigen an, wie relevant jeder Chunk für Ihre Frage war. Höhere Scores bedeuten bessere Übereinstimmungen. So können Sie die Antwort gegen die Originalquelle überprüfen. -RAG-Abfrageergebnisse +RAG Abfrageergebnisse -*Dieser Screenshot zeigt Abfrageergebnisse mit generierter Antwort, Quellenhinweisen und Relevanzwerten für jeden abgerufenen Abschnitt.* +*Dieser Screenshot zeigt Abfrageergebnisse mit der generierten Antwort, Quellenhinweisen und Relevanzwerten für jeden abgerufenen Chunk.* -### Experimentieren mit Fragen +### Mit Fragen experimentieren -Probieren Sie verschiedene Fragetypen aus: -- Konkrete Fakten: „Was ist das Hauptthema?“ +Probieren Sie verschiedene Fragetypen: +- Spezifische Fakten: „Was ist das Hauptthema?“ - Vergleiche: „Was ist der Unterschied zwischen X und Y?“ - Zusammenfassungen: „Fassen Sie die wichtigsten Punkte zu Z zusammen“ -Beobachten Sie, wie sich die Relevanzwerte ändern, je nachdem, wie gut Ihre Frage mit dem Dokumentinhalt übereinstimmt. +Beobachten Sie, wie sich die Relevanzwerte ändern, je nachdem, wie gut Ihre Frage zum Dokumentinhalt passt. -## Wichtige Konzepte +## Schlüsselkonzepte -### Abschnittsstrategie +### Chunking-Strategie -Dokumente werden in 300-Token-Abschnitte mit 30 Token Überlappung aufgeteilt. Dieses Gleichgewicht stellt sicher, dass jeder Abschnitt genügend Kontext enthält, um aussagekräftig zu sein, aber klein genug bleibt, um mehrere Abschnitte in einem Prompt unterzubringen. +Dokumente werden in 300-Token-Chunks mit 30 Tokens Überlappung aufgeteilt. Dieses Gleichgewicht stellt sicher, dass jeder Chunk genug Kontext für Bedeutung enthält und gleichzeitig klein genug bleibt, um mehrere Chunks in einem Prompt unterzubringen. -### Ähnlichkeitswerte +### Ähnlichkeitsscores -Jeder abgerufene Abschnitt hat einen Ähnlichkeitswert zwischen 0 und 1, der zeigt, wie eng er zur Frage des Benutzers passt. Das folgende Diagramm visualisiert die Wertbereiche und wie das System sie zur Filterung der Ergebnisse nutzt: +Jeder abgerufene Chunk hat einen Ähnlichkeitsscore zwischen 0 und 1, der angibt, wie gut er zur Frage des Nutzers passt. Das folgende Diagramm visualisiert die Score-Bereiche und wie das System diese verwendet, um Ergebnisse zu filtern: -Ähnlichkeitswerte +Ähnlichkeitsscores -*Dieses Diagramm zeigt Wertbereiche von 0 bis 1 mit einem Mindestschwellenwert von 0,5, der irrelevante Abschnitte herausfiltert.* +*Dieses Diagramm zeigt Score-Bereiche von 0 bis 1, mit einem Mindestschwellenwert von 0,5, der irrelevante Chunks herausfiltert.* -Die Werte reichen von 0 bis 1: +Scores reichen von 0 bis 1: - 0,7–1,0: Hoch relevant, exakte Übereinstimmung - 0,5–0,7: Relevant, guter Kontext -- Unter 0,5: Herausgefiltert, zu unterschiedlich +- Unter 0,5: Gefiltert, zu unterschiedlich -Das System ruft nur Abschnitte oberhalb des Mindestschwellenwerts ab, um Qualität sicherzustellen. +Das System ruft nur Chunks ab, die über dem Mindestschwellenwert liegen, um Qualität zu gewährleisten. -Einbettungen funktionieren gut, wenn Bedeutungen klar gruppiert sind, aber sie haben Schwachstellen. Das folgende Diagramm zeigt häufige Fehlerfälle – zu große Abschnitte produzieren unscharfe Vektoren, zu kleine Abschnitte fehlen Kontext, mehrdeutige Begriffe zeigen auf mehrere Cluster, und exakte Nachschlagen (IDs, Teilenummern) funktionieren mit Einbettungen überhaupt nicht: +Einbettungen funktionieren gut, wenn Bedeutungen klar gruppiert sind, haben aber auch Schwachstellen. Das folgende Diagramm zeigt häufige Fehlerfälle — zu große Chunks erzeugen unscharfe Vektoren, zu kleine Chunks haben zu wenig Kontext, mehrdeutige Begriffe verweisen auf mehrere Gruppen, und exakte Übereinstimmungen (IDs, Teilenummern) funktionieren mit Einbettungen gar nicht: -Fehlermodi bei Einbettungen +Fehlerarten bei Einbettungen -*Dieses Diagramm zeigt gängige Fehlerfälle bei Einbettungen: zu große Abschnitte, zu kleine Abschnitte, mehrdeutige Begriffe, die auf mehrere Cluster zeigen, und exakte Nachschlageoperationen wie IDs.* +*Dieses Diagramm zeigt typische Fehlerquellen bei Einbettungen: zu große Chunks, zu kleine Chunks, mehrdeutige Begriffe mit mehreren Zuordnungen und exakte Suchanfragen wie IDs.* -### In-Memory-Speicherung +### Speicher im Arbeitsspeicher -Dieses Modul verwendet der Einfachheit halber eine In-Memory-Speicherung. Beim Neustart der Anwendung gehen hochgeladene Dokumente verloren. Produktionssysteme verwenden persistente Vektor-Datenbanken wie Qdrant oder Azure AI Search. +Dieses Modul verwendet Speichern im Arbeitsspeicher aus Einfachheitsgründen. Beim Neustart der Anwendung gehen hochgeladene Dokumente verloren. Produktionssysteme verwenden persistente Vektordatenbanken wie Qdrant oder Azure AI Search. -### Kontextfenstermanagement +### Verwaltung des Kontextfensters -Jedes Modell hat ein maximales Kontextfenster. Sie können nicht jeden Abschnitt eines großen Dokuments einbeziehen. Das System ruft die N relevantesten Abschnitte (Standard 5) ab, um innerhalb der Grenzen zu bleiben und dennoch genügend Kontext für genaue Antworten zu bieten. +Jedes Modell hat ein maximales Kontextfenster. Sie können nicht jeden Chunk eines großen Dokuments einbeziehen. Das System ruft die Top-N relevantesten Chunks ab (Standard 5), um innerhalb der Grenzen zu bleiben und gleichzeitig genug Kontext für genaue Antworten zu bieten. -## Wann RAG wichtig ist +## Wann RAG relevant ist -RAG ist nicht immer der richtige Ansatz. Die folgende Entscheidungshilfe hilft Ihnen zu bestimmen, wann RAG Mehrwert bietet und wann einfachere Ansätze – wie Inhalte direkt im Prompt einzubinden oder sich auf das Modellwissen zu verlassen – ausreichen: +RAG ist nicht immer die richtige Methode. Die folgende Entscheidungshilfe hilft Ihnen zu bestimmen, wann RAG Mehrwert bringt und wann einfachere Ansätze — wie das direkte Einfügen von Inhalten in den Prompt oder die Nutzung des eingelernten Wissens des Modells — ausreichen: Wann RAG verwenden @@ -427,11 +426,11 @@ RAG ist nicht immer der richtige Ansatz. Die folgende Entscheidungshilfe hilft I --- -**Navigation:** [← Vorheriges: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Zurück zum Hauptverzeichnis](../README.md) | [Nächstes: Modul 04 - Tools →](../04-tools/README.md) +**Navigation:** [← Vorheriges: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Zurück zur Übersicht](../README.md) | [Nächstes: Modul 04 - Tools →](../04-tools/README.md) --- **Haftungsausschluss**: -Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, können automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Für wichtige Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen. +Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Bei kritischen Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen. \ No newline at end of file diff --git a/translations/de/04-tools/README.md b/translations/de/04-tools/README.md index 62c93023f..83a166c95 100644 --- a/translations/de/04-tools/README.md +++ b/translations/de/04-tools/README.md @@ -2,75 +2,75 @@ ## Inhaltsverzeichnis -- [Video-Durchgang](../../../04-tools) -- [Was Sie lernen werden](../../../04-tools) -- [Voraussetzungen](../../../04-tools) -- [KI-Agenten mit Tools verstehen](../../../04-tools) -- [Wie Tool-Aufrufe funktionieren](../../../04-tools) - - [Tool-Definitionen](../../../04-tools) - - [Entscheidungsfindung](../../../04-tools) - - [Ausführung](../../../04-tools) - - [Antwortgenerierung](../../../04-tools) - - [Architektur: Spring Boot Auto-Wiring](../../../04-tools) -- [Tool-Verkettung](../../../04-tools) -- [Anwendung ausführen](../../../04-tools) -- [Anwendung verwenden](../../../04-tools) - - [Einfache Tool-Nutzung ausprobieren](../../../04-tools) - - [Tool-Verkettung testen](../../../04-tools) - - [Gesprächsverlauf ansehen](../../../04-tools) - - [Mit verschiedenen Anfragen experimentieren](../../../04-tools) -- [Wichtige Konzepte](../../../04-tools) - - [ReAct-Muster (Reasoning and Acting)](../../../04-tools) - - [Tool-Beschreibungen sind wichtig](../../../04-tools) - - [Sitzungsverwaltung](../../../04-tools) - - [Fehlerbehandlung](../../../04-tools) -- [Verfügbare Tools](../../../04-tools) -- [Wann man tool-basierte Agenten verwendet](../../../04-tools) -- [Tools vs RAG](../../../04-tools) -- [Nächste Schritte](../../../04-tools) +- [Video-Durchgang](#video-durchgang) +- [Was Sie lernen werden](#was-sie-lernen-werden) +- [Voraussetzungen](#voraussetzungen) +- [Verständnis von KI-Agenten mit Tools](#verständnis-von-ki-agenten-mit-tools) +- [Wie Tool-Aufrufe funktionieren](#wie-tool-aufrufe-funktionieren) + - [Tool-Definitionen](#tool-definitionen) + - [Entscheidungsfindung](#entscheidungsfindung) + - [Ausführung](#ausführung) + - [Antwortgenerierung](#antwortgenerierung) + - [Architektur: Spring Boot Auto-Wiring](#architektur-spring-boot-auto-wiring) +- [Tool-Verkettung](#tool-verkettung) +- [Anwendung starten](#anwendung-starten) +- [Die Anwendung verwenden](#verwendung-der-anwendung) + - [Einfaches Tool ausprobieren](#probiere-einfache-tool-anwendungen-aus) + - [Tool-Verkettung testen](#teste-tool-verkettung) + - [Gesprächsablauf ansehen](#sieh-dir-den-gesprächsverlauf-an) + - [Mit verschiedenen Anfragen experimentieren](#experimentiere-mit-verschiedenen-anfragen) +- [Wichtige Konzepte](#zentrale-konzepte) + - [ReAct-Muster (Reasoning and Acting)](#react-muster-reasoning-and-acting) + - [Tool-Beschreibungen sind wichtig](#tool-beschreibungen-sind-wichtig) + - [Sitzungsverwaltung](#sitzungsmanagement) + - [Fehlerbehandlung](#fehlerbehandlung) +- [Verfügbare Tools](#verfügbare-tools) +- [Wann man tool-basierte Agenten verwendet](#wann-man-tool-basierte-agenten-verwendet) +- [Tools vs RAG](#tools-vs-rag) +- [Nächste Schritte](#nächste-schritte) ## Video-Durchgang -Sehen Sie sich diese Live-Session an, die erklärt, wie Sie mit diesem Modul starten: +Sehen Sie sich diese Live-Sitzung an, die erklärt, wie Sie mit diesem Modul starten: -KI-Agenten mit Tools und MCP – Live-Session +KI-Agenten mit Tools und MCP - Live-Sitzung ## Was Sie lernen werden -Bis jetzt haben Sie gelernt, wie man Gespräche mit KI führt, Eingabeaufforderungen effektiv strukturiert und Antworten in Ihren Dokumenten verankert. Aber es gibt immer noch eine grundlegende Einschränkung: Sprachmodelle können nur Text generieren. Sie können nicht das Wetter prüfen, Berechnungen durchführen, Datenbanken abfragen oder mit externen Systemen interagieren. +Bisher haben Sie gelernt, wie man Gespräche mit KI führt, Prompts effektiv strukturiert und Antworten an Ihre Dokumente anbindet. Aber es gibt noch eine grundlegende Einschränkung: Sprachmodelle können nur Text erzeugen. Sie können das Wetter nicht nachschlagen, keine Berechnungen durchführen, keine Datenbanken abfragen oder mit externen Systemen interagieren. -Tools verändern das. Indem Sie dem Modell Zugriff auf Funktionen geben, die es aufrufen kann, verwandeln Sie es von einem Textgenerator in einen Agenten, der handeln kann. Das Modell entscheidet, wann es ein Tool benötigt, welches Tool es nutzt und welche Parameter es übergibt. Ihr Code führt die Funktion aus und liefert das Ergebnis zurück. Das Modell integriert dieses Ergebnis in seine Antwort. +Tools ändern das. Indem Sie dem Modell Zugriff auf Funktionen geben, die es aufrufen kann, verwandeln Sie es von einem Textgenerator in einen Agenten, der Aktionen durchführen kann. Das Modell entscheidet, wann es ein Tool braucht, welches Tool es verwendet und welche Parameter es übergibt. Ihr Code führt die Funktion aus und liefert das Ergebnis zurück. Das Modell integriert dieses Ergebnis in seine Antwort. ## Voraussetzungen -- Abgeschlossenes [Modul 01 – Einführung](../01-introduction/README.md) (Azure OpenAI Ressourcen bereitgestellt) -- Empfohlen, vorherige Module abgeschlossen zu haben (dieses Modul verweist auf [RAG-Konzepte aus Modul 03](../03-rag/README.md) im Vergleich Tools vs. RAG) -- `.env`-Datei im Stammverzeichnis mit Azure-Anmeldedaten (erstellt durch `azd up` in Modul 01) +- Abgeschlossenes [Modul 01 - Einführung](../01-introduction/README.md) (Azure OpenAI Ressourcen bereitgestellt) +- Empfohlene vorherige Module abgeschlossen (dieses Modul bezieht sich in der Tools-vs-RAG-Vergleich auf [RAG-Konzepte aus Modul 03](../03-rag/README.md)) +- `.env` Datei im Stammverzeichnis mit Azure-Zugangsdaten (erstellt durch `azd up` in Modul 01) -> **Hinweis:** Wenn Sie Modul 01 noch nicht abgeschlossen haben, folgen Sie zuerst den dortigen Bereitstellungsanweisungen. +> **Hinweis:** Wenn Sie Modul 01 noch nicht abgeschlossen haben, folgen Sie zunächst den dortigen Bereitstellungsanweisungen. -## KI-Agenten mit Tools verstehen +## Verständnis von KI-Agenten mit Tools -> **📝 Hinweis:** Der Begriff „Agenten“ in diesem Modul bezieht sich auf KI-Assistenten mit Tool-Aufruf-Fähigkeiten. Dies unterscheidet sich von den **Agentic AI** Mustern (autonome Agenten mit Planung, Gedächtnis und mehrstufigem Schlussfolgern), die wir in [Modul 05: MCP](../05-mcp/README.md) behandeln. +> **📝 Hinweis:** Der Begriff „Agenten“ in diesem Modul bezieht sich auf KI-Assistenten, die um Tool-Aufruf-Fähigkeiten erweitert sind. Dies unterscheidet sich von den **Agentic AI**-Mustern (autonome Agenten mit Planung, Gedächtnis und mehrstufigem Schlussfolgern), die wir in [Modul 05: MCP](../05-mcp/README.md) behandeln. -Ohne Tools kann ein Sprachmodell nur Text aus seinen Trainingsdaten generieren. Fragen Sie es nach dem aktuellen Wetter, muss es raten. Geben Sie ihm Tools, kann es eine Wetter-API aufrufen, Berechnungen durchführen oder eine Datenbank abfragen – und diese echten Ergebnisse in seine Antwort einfließen lassen. +Ohne Tools kann ein Sprachmodell nur Text basierend auf seinen Trainingsdaten generieren. Fragt man es nach dem aktuellen Wetter, muss es raten. Mit Tools kann es eine Wetter-API aufrufen, Berechnungen durchführen oder eine Datenbank abfragen — und diese Echtzeit-Ergebnisse in seine Antwort einfließen lassen. Ohne Tools vs Mit Tools -*Ohne Tools kann das Modell nur raten – mit Tools kann es APIs aufrufen, Berechnungen durchführen und Echtzeitdaten liefern.* +*Ohne Tools kann das Modell nur raten – mit Tools kann es APIs aufrufen, Berechnungen ausführen und Echtzeitdaten zurückgeben.* -Ein KI-Agent mit Tools folgt dem **Reasoning and Acting (ReAct)** Muster. Das Modell antwortet nicht einfach – es denkt darüber nach, was es braucht, handelt durch Tool-Aufrufe, beobachtet das Ergebnis und entscheidet dann, ob es erneut handeln oder die finale Antwort liefern soll: +Ein KI-Agent mit Tools folgt einem **Reasoning and Acting (ReAct)**-Muster. Das Modell reagiert nicht nur – es überlegt, was es braucht, handelt durch Aufruf eines Tools, beobachtet das Ergebnis und entscheidet dann, ob es erneut handeln oder die endgültige Antwort liefern soll: -1. **Nachdenken** — Der Agent analysiert die Frage des Nutzers und bestimmt, welche Informationen er benötigt -2. **Handeln** — Der Agent wählt das richtige Tool aus, erzeugt die passenden Parameter und ruft es auf -3. **Beobachten** — Der Agent empfängt die Ausgabe des Tools und bewertet das Ergebnis -4. **Wiederholen oder Antworten** — Wenn weitere Daten nötig sind, wiederholt der Agent den Zyklus; sonst formuliert er eine natürliche Antwort +1. **Überlegen** — Der Agent analysiert die Frage des Nutzers und bestimmt, welche Informationen er benötigt +2. **Handeln** — Der Agent wählt das richtige Tool aus, erstellt die korrekten Parameter und ruft es auf +3. **Beobachten** — Der Agent erhält die Ausgabe des Tools und bewertet das Ergebnis +4. **Wiederholen oder Antworten** — Wenn weitere Daten benötigt werden, wird die Schleife wiederholt; andernfalls wird eine natürliche Antwort formuliert -ReAct Muster +ReAct-Muster -*Der ReAct-Zyklus – der Agent denkt darüber nach, was zu tun ist, handelt durch Tool-Aufrufe, beobachtet das Ergebnis und wiederholt dies, bis eine Endantwort vorliegt.* +*Der ReAct-Zyklus — der Agent überlegt, was zu tun ist, handelt durch Tool-Aufruf, beobachtet das Ergebnis und wiederholt dies, bis er die endgültige Antwort geben kann.* -Dies geschieht automatisch. Sie definieren die Tools und deren Beschreibungen. Das Modell übernimmt die Entscheidungsfindung, wann und wie sie genutzt werden. +Dies geschieht automatisch. Sie definieren die Tools und deren Beschreibungen. Das Modell übernimmt die Entscheidungsfindung, wann und wie sie eingesetzt werden. ## Wie Tool-Aufrufe funktionieren @@ -78,7 +78,7 @@ Dies geschieht automatisch. Sie definieren die Tools und deren Beschreibungen. D [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Sie definieren Funktionen mit klaren Beschreibungen und Parameterspezifikationen. Das Modell sieht diese Beschreibungen in seinem System-Prompt und versteht, was jedes Tool macht. +Sie definieren Funktionen mit klaren Beschreibungen und Parameterspezifikationen. Das Modell sieht diese Beschreibungen im System-Prompt und versteht, wofür jedes Tool dient. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Ihre Wetterabfrage-Logik + // Ihre Logik zur Wetterabfrage return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,139 +96,139 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Assistant wird automatisch von Spring Boot verbunden mit: +// Der Assistent wird automatisch von Spring Boot verbunden mit: // - ChatModel-Bean // - Alle @Tool-Methoden aus @Component-Klassen -// - ChatMemoryProvider für Sitzungsverwaltung +// - ChatMemoryProvider für Sitzungsmanagement ``` - -Das folgende Diagramm zerlegt jede Annotation und zeigt, wie jedes Element der KI hilft zu verstehen, wann das Tool aufzurufen ist und welche Argumente übergeben werden sollen: -Anatomie von Tool-Definitionen +Das folgende Diagramm erklärt jede Annotation und zeigt, wie jeder Teil der KI hilft zu verstehen, wann das Tool aufgerufen wird und welche Argumente übergeben werden: -*Anatomie einer Tool-Definition – @Tool sagt der KI, wann sie verwendet wird, @P beschreibt jeden Parameter und @AiService verknüpft alles beim Start.* +Anatomie der Tool-Definitionen + +*Anatomie einer Tool-Definition — @Tool sagt der KI, wann sie das Tool nutzen soll, @P beschreibt jeden Parameter, und @AiService verbindet alles beim Start.* > **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) und fragen Sie: > - „Wie integriere ich eine echte Wetter-API wie OpenWeatherMap anstelle von Mock-Daten?“ -> - „Was macht eine gute Tool-Beschreibung aus, die der KI hilft, sie korrekt zu verwenden?“ -> - „Wie handle ich API-Fehler und Rate Limits in Tool-Implementierungen?“ +> - „Was macht eine gute Tool-Beschreibung aus, die der KI hilft, sie richtig zu nutzen?“ +> - „Wie gehe ich mit API-Fehlern und Rate-Limits in Tool-Implementierungen um?“ ### Entscheidungsfindung -Wenn ein Nutzer fragt „Wie ist das Wetter in Seattle?“, wählt das Modell nicht zufällig ein Tool aus. Es vergleicht die Absicht des Nutzers mit jeder verfügbaren Tool-Beschreibung, bewertet deren Relevanz und wählt die beste Übereinstimmung aus. Dann generiert es einen strukturierten Funktionsaufruf mit den richtigen Parametern – hier `location` auf `"Seattle"` gesetzt. +Wenn ein Nutzer fragt „Wie ist das Wetter in Seattle?“, wählt das Modell nicht zufällig ein Tool aus. Es vergleicht die Absicht des Nutzers mit jeder Tool-Beschreibung, die ihm zur Verfügung steht, bewertet jede auf Relevanz und wählt die beste Übereinstimmung. Anschließend erzeugt es einen strukturierten Funktionsaufruf mit den richtigen Parametern – in diesem Fall mit `location` auf `"Seattle"` gesetzt. -Wenn kein Tool zur Benutzeranfrage passt, fällt das Modell auf Antworten aus seinem eigenen Wissen zurück. Bei mehreren passenden Tools wählt es das speziellste. +Wenn kein Tool zur Anfrage passt, fällt das Modell auf seine eigenen Wissensbestände zurück. Wenn mehrere Tools passen, wählt es das spezifischste aus. -Wie die KI entscheidet, welches Tool verwendet wird +Wie die KI entscheidet, welches Tool zu verwenden ist -*Das Modell bewertet jedes verfügbare Tool im Hinblick auf die Nutzerabsicht und wählt das beste – deswegen sind klare, spezifische Tool-Beschreibungen wichtig.* +*Das Modell bewertet alle verfügbaren Tools anhand der Nutzerabsicht und wählt die beste Übereinstimmung aus – deshalb sind klare, präzise Tool-Beschreibungen so wichtig.* ### Ausführung [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot verdrahtet die deklarative `@AiService` Schnittstelle mit allen registrierten Tools automatisch, und LangChain4j führt Tool-Aufrufe selbstständig aus. Im Hintergrund durchläuft ein Tool-Aufruf sechs Stufen – von der nativen Nutzerspracheingabe bis zur natürlichen Antwort: +Spring Boot verbindet automatisch das deklarative `@AiService`-Interface mit allen registrierten Tools, und LangChain4j führt Tool-Aufrufe automatisch aus. Im Hintergrund durchläuft ein Tool-Aufruf sechs Phasen — von der natürlichen Spracheingabe des Nutzers bis zur Antwort in natürlicher Sprache: -Tool-Aufruf Ablauf +Ablauf eines Tool-Aufrufs -*End-to-End Ablauf – der Nutzer stellt eine Frage, das Modell wählt ein Tool aus, LangChain4j führt es aus, und das Modell integriert das Ergebnis in die natürliche Antwort.* +*Der End-to-End-Ablauf — der Nutzer stellt eine Frage, das Modell wählt ein Tool aus, LangChain4j führt es aus und das Modell verwebt das Ergebnis in eine natürliche Antwort.* -Wenn Sie die [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) aus Modul 00 ausgeführt haben, haben Sie dieses Muster schon gesehen – die `Calculator`-Tools wurden genauso aufgerufen. Das folgende Sequenzdiagramm zeigt genau, was während dieser Demo unter der Haube geschah: +Im Hintergrund läuft `AiServices` dieselbe Tool-Aufruf-Schleife für jedes Tool – hier mit einem einfachen `Calculator` als Beispiel. Das folgende Sequenzdiagramm zeigt genau, was unter der Haube passiert: Sequenzdiagramm Tool-Aufruf -*Die Tool-Aufruf-Schleife aus der Quick Start Demo – `AiServices` schickt Ihre Nachricht und Tool-Schemata an das LLM, das LLM antwortet mit einem Funktionsaufruf wie `add(42, 58)`, LangChain4j führt die `Calculator` Methode lokal aus und gibt das Ergebnis für die finale Antwort zurück.* +*Die Tool-Aufruf-Schleife — `AiServices` sendet Ihre Nachricht und das Toolschema an das LLM, das LLM antwortet mit einem Funktionsaufruf wie `add(42, 58)`, LangChain4j führt die `Calculator`-Methode lokal aus und gibt das Ergebnis für die finale Antwort zurück.* > **🤖 Probieren Sie es mit [GitHub Copilot](https://github.com/features/copilot) Chat:** Öffnen Sie [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) und fragen Sie: -> - „Wie funktioniert das ReAct-Muster und warum ist es für KI-Agenten effektiv?“ -> - „Wie entscheidet der Agent, welches Tool er wann nutzt?“ -> - „Was passiert, wenn die Ausführung eines Tools fehlschlägt – wie behandle ich Fehler robust?“ +> - „Wie funktioniert das ReAct-Muster und warum ist es effektiv für KI-Agenten?“ +> - „Wie entscheidet der Agent, welches Tool er in welcher Reihenfolge nutzt?“ +> - „Was passiert, wenn die Ausführung eines Tools fehlschlägt – wie sollte ich Fehler robust handhaben?“ ### Antwortgenerierung -Das Modell erhält die Wetterdaten und formatiert sie als eine natürliche Antwort für den Nutzer. +Das Modell erhält die Wetterdaten und formatiert sie zu einer natürlichen Antwort für den Nutzer. ### Architektur: Spring Boot Auto-Wiring -Dieses Modul verwendet LangChain4j’s Spring Boot Integration mit deklarativen `@AiService` Schnittstellen. Beim Start entdeckt Spring Boot jede `@Component`, die `@Tool` Methoden enthält, ihre `ChatModel` Bean und den `ChatMemoryProvider` – und verdrahtet sie alle in eine einzige `Assistant` Schnittstelle ohne Boilerplate. +Dieses Modul verwendet LangChain4js Spring Boot-Integration mit deklarativen `@AiService`-Interfaces. Beim Start entdeckt Spring Boot alle `@Component`s, die `@Tool`-Methoden enthalten, Ihre `ChatModel`-Bean und den `ChatMemoryProvider` – und verknüpft alles zu einem einzelnen `Assistant`-Interface ganz ohne Boilerplate-Code. Spring Boot Auto-Wiring Architektur -*Die @AiService Schnittstelle verbindet ChatModel, Tool-Komponenten und Memory Provider – Spring Boot übernimmt die komplette Verkabelung automatisch.* +*Das @AiService-Interface verbindet ChatModel, Tool-Komponenten und Memory-Provider – Spring Boot übernimmt das Verkabeln automatisch.* -Hier sehen Sie den kompletten Anforderungslebenszyklus als Sequenzdiagramm – von der HTTP-Anfrage über Controller, Service und verdrahteten Proxy bis zur Tool-Ausführung und zurück: +Hier der komplette Anforderungszyklus als Sequenzdiagramm – von der HTTP-Anfrage über Controller, Service und auto-verkabelten Proxy bis zur Tool-Ausführung und zurück: -Spring Boot Tool-Aufruf Sequenz +Sequenzdiagramm Spring Boot Tool-Aufruf -*Der vollständige Spring Boot Anforderungszyklus – HTTP-Anfrage fließt durch Controller und Service zum verdrahteten Assistant Proxy, der LLM und Tool-Aufrufe automatisch orchestriert.* +*Der komplette Spring Boot-Anforderungszyklus — HTTP-Anfrage fließt über Controller und Service zum auto-verkabelten Assistant-Proxy, der LLM- und Tool-Aufrufe orchestriert.* -Wichtige Vorteile dieses Ansatzes: +Wesentliche Vorteile dieses Ansatzes: -- **Spring Boot Auto-Wiring** – ChatModel und Tools werden automatisch injiziert -- **@MemoryId Muster** – Automatisches memory-basiertes Sitzungsmanagement -- **Einzelne Instanz** – Assistant wird einmalig erstellt und für bessere Performance wiederverwendet -- **Typsichere Ausführung** – Java-Methoden werden direkt mit Typumwandlung aufgerufen -- **Multi-Turn Orchestrierung** – Unterstützt automatische Tool-Verkettung -- **Zero Boilerplate** – Keine manuellen `AiServices.builder()` Aufrufe oder Memory HashMap +- **Spring Boot Auto-Wiring** — ChatModel und Tools werden automatisch injiziert +- **@MemoryId-Muster** — Automatisches Sitzungs-basiertes Speichermanagement +- **Einzelinstanz** — Assistant wird einmal erstellt und zur Leistungssteigerung wiederverwendet +- **Typensichere Ausführung** — Java-Methoden werden direkt mit Typkonvertierung aufgerufen +- **Mehrstufige Orchestrierung** — Handhabt Tool-Verkettung automatisch +- **Kein Boilerplate** — Keine manuellen `AiServices.builder()`-Aufrufe oder Memory-HashMaps -Alternative Ansätze (manuelles `AiServices.builder()`) erfordern mehr Code und verzichten auf Spring Boot Integrationsvorteile. +Alternative Ansätze (manuelles `AiServices.builder()`) erfordern mehr Code und bieten nicht die Vorteile der Spring Boot-Integration. ## Tool-Verkettung -**Tool-Verkettung** – Die tatsächliche Stärke von tool-basierten Agenten zeigt sich, wenn eine einzelne Frage mehrere Tools erfordert. Fragen Sie „Wie ist das Wetter in Seattle in Fahrenheit?“ und der Agent verknüpft automatisch zwei Tools: zuerst ruft er `getCurrentWeather` auf, um die Temperatur in Celsius zu erhalten, dann übergibt er diesen Wert an `celsiusToFahrenheit` für die Umrechnung – alles in einem einzigen Gesprächsturn. +**Tool-Verkettung** — Die wahre Stärke tool-basierter Agenten zeigt sich, wenn eine einzige Frage mehrere Tools benötigt. Fragt man „Wie ist das Wetter in Seattle in Fahrenheit?“, verkettet der Agent automatisch zwei Tools: Zuerst ruft er `getCurrentWeather` auf, um die Temperatur in Celsius zu erhalten, dann übergibt er diesen Wert an `celsiusToFahrenheit` zur Umrechnung – alles in einer einzigen Gesprächsrunde. -Tool-Verkettungsbeispiel +Beispiel Tool-Verkettung -*Tool-Verkettung in Aktion – der Agent ruft zuerst getCurrentWeather auf, leitet das Celsius-Ergebnis an celsiusToFahrenheit weiter und liefert eine kombinierte Antwort.* +*Tool-Verkettung in Aktion — der Agent ruft zuerst getCurrentWeather auf, leitet das Celsius-Ergebnis an celsiusToFahrenheit weiter und liefert eine kombinierte Antwort.* -**Abschwächung von Fehlern** – Fragen Sie nach dem Wetter in einer Stadt, die nicht in den Mock-Daten ist. Das Tool gibt eine Fehlermeldung zurück, und die KI erklärt, dass sie nicht helfen kann, anstatt abzustürzen. Tools fallen sicher aus. Das folgende Diagramm zeigt den Unterschied zwischen den beiden Ansätzen – mit ordentlicher Fehlerbehandlung fängt der Agent die Ausnahme auf und antwortet hilfreich, ohne sie stürzt die gesamte Anwendung ab: +**Fehlereskalation vermeiden** — Fragt man das Wetter in einer Stadt, die nicht in den Mock-Daten ist, gibt das Tool eine Fehlermeldung zurück, und die KI erklärt, dass sie nicht helfen kann, anstatt abzustürzen. Tools versagen sicher. Das folgende Diagramm vergleicht beide Ansätze — mit ordentlicher Fehlerbehandlung fängt der Agent die Ausnahme ab und antwortet hilfreich, andernfalls stürzt die ganze Anwendung ab: -Fehlerbehandlungsablauf +Fehlerbehandlungs-Fluss -*Wenn ein Tool fehlschlägt, fängt der Agent den Fehler ab und antwortet mit einer hilfreichen Erklärung, statt dass es zum Absturz kommt.* +*Wenn ein Tool fehlschlägt, fängt der Agent den Fehler ab und gibt eine hilfreiche Erklärung, anstatt abzustürzen.* -Dies geschieht in einem einzigen Gesprächsschritt. Der Agent orchestriert mehrere Tool-Aufrufe autonom. +Dies geschieht in einer einzigen Gesprächsrunde. Der Agent orchestriert mehrere Tool-Aufrufe autonom. -## Anwendung ausführen +## Anwendung starten **Bereitstellung überprüfen:** -Stellen Sie sicher, dass die `.env`-Datei im Stammverzeichnis mit Azure-Zugangsdaten vorhanden ist (erstellt während Modul 01). Führen Sie dies im Modulsverzeichnis (`04-tools/`) aus: +Stellen Sie sicher, dass die `.env` Datei im Stammverzeichnis mit Azure-Zugangsdaten existiert (erstellt während Modul 01). Führen Sie dies im Modul-Verzeichnis (`04-tools/`) aus: -**Bash:** +**Bash:** ```bash -cat ../.env # Sollte AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT anzeigen +cat ../.env # Soll AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT anzeigen ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Sollte AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT anzeigen ``` - -**Starten der Anwendung:** -> **Hinweis:** Falls Sie bereits alle Anwendungen mit `./start-all.sh` aus dem Stammverzeichnis gestartet haben (wie in Modul 01 beschrieben), läuft dieses Modul bereits auf Port 8084. Sie können die Startbefehle unten überspringen und direkt http://localhost:8084 aufrufen. +**Anwendung starten:** -**Option 1: Verwendung des Spring Boot Dashboards (Empfohlen für VS Code Nutzer)** +> **Hinweis:** Wenn Sie bereits alle Anwendungen mit `./start-all.sh` vom Stammverzeichnis aus gestartet haben (wie in Modul 01 beschrieben), läuft dieses Modul bereits auf Port 8084. Sie können die Startbefehle unten überspringen und direkt http://localhost:8084 aufrufen. -Der Dev Container enthält die Erweiterung Spring Boot Dashboard, welche eine visuelle Oberfläche zur Verwaltung aller Spring Boot Anwendungen bereitstellt. Sie finden sie in der Aktivitätsleiste links in VS Code (suchen Sie das Spring Boot Symbol). +**Option 1: Nutzung des Spring Boot Dashboards (empfohlen für VS Code Nutzer)** -Im Spring Boot Dashboard können Sie: -- Alle verfügbaren Spring Boot Anwendungen im Workspace sehen -- Anwendungen mit einem Klick starten/stoppen -- Echtzeit-Protokolle anzeigen -- Den Anwendungsstatus überwachen -Klicken Sie einfach auf die Wiedergabetaste neben „tools“, um dieses Modul zu starten, oder starten Sie alle Module auf einmal. +Der Dev-Container enthält die Erweiterung Spring Boot Dashboard, die eine visuelle Oberfläche zur Verwaltung aller Spring Boot-Anwendungen bereitstellt. Sie finden sie in der Aktivitätsleiste links in VS Code (suchen Sie das Spring Boot-Symbol). -So sieht das Spring Boot Dashboard in VS Code aus: +Im Spring Boot Dashboard können Sie: +- Alle verfügbaren Spring Boot-Anwendungen im Workspace sehen +- Anwendungen mit einem Klick starten/stoppen +- Anwendungsprotokolle in Echtzeit ansehen +- Anwendungsstatus überwachen + +Klicken Sie einfach auf den Play-Button neben „tools“, um dieses Modul zu starten, oder starten Sie alle Module auf einmal. +So sieht das Spring Boot Dashboard in VS Code aus: Spring Boot Dashboard -*Das Spring Boot Dashboard in VS Code — alle Module von einem Ort aus starten, stoppen und überwachen* +*Das Spring Boot Dashboard in VS Code — starte, stoppe und überwache alle Module an einem Ort* **Option 2: Verwendung von Shell-Skripten** -Starten Sie alle Webanwendungen (Module 01-04): +Starte alle Webanwendungen (Module 01-04): **Bash:** ```bash @@ -238,11 +238,11 @@ cd .. # Vom Stammverzeichnis **PowerShell:** ```powershell -cd .. # Vom Stammverzeichnis +cd .. # Aus dem Stammverzeichnis .\start-all.ps1 ``` -Oder starten Sie nur dieses Modul: +Oder starte nur dieses Modul: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Beide Skripte laden automatisch Umgebungsvariablen aus der Root-`.env`-Datei und bauen die JARs, falls sie noch nicht existieren. +Beide Skripte laden automatisch Umgebungsvariablen aus der Root-`.env`-Datei und bauen die JARs, falls diese noch nicht existieren. -> **Hinweis:** Wenn Sie alle Module manuell vor dem Start bauen möchten: +> **Hinweis:** Falls du alle Module manuell bauen möchtest, bevor du sie startest: > > **Bash:** > ```bash @@ -272,13 +272,13 @@ Beide Skripte laden automatisch Umgebungsvariablen aus der Root-`.env`-Datei und > mvn clean package -DskipTests > ``` -Öffnen Sie http://localhost:8084 in Ihrem Browser. +Öffne http://localhost:8084 in deinem Browser. **Zum Stoppen:** **Bash:** ```bash -./stop.sh # Nur dieses Modul +./stop.sh # Dieses Modul nur # Oder cd .. && ./stop-all.sh # Alle Module ``` @@ -292,84 +292,84 @@ cd ..; .\stop-all.ps1 # Alle Module ## Verwendung der Anwendung -Die Anwendung bietet eine Weboberfläche, über die Sie mit einem KI-Agenten interagieren können, der Zugriff auf Wetter- und Temperaturumrechner-Tools hat. So sieht die Oberfläche aus — sie enthält Schnellstart-Beispiele und ein Chatfenster zum Senden von Anfragen: +Die Anwendung bietet eine Weboberfläche, über die du mit einem KI-Agenten interagieren kannst, der Zugriff auf Wetter- und Temperaturumrechnungstools hat. So sieht die Oberfläche aus — sie enthält Schnellstart-Beispiele und ein Chat-Panel zum Senden von Anfragen: AI Agent Tools Interface -*Die AI Agent Tools-Oberfläche – Schnellbeispiele und Chat-Interface zur Interaktion mit Tools* +*Die Oberfläche der AI Agent Tools - schnelle Beispiele und Chat-Interface zur Interaktion mit Tools* -### Einfachen Tool-Einsatz ausprobieren +### Probiere einfache Tool-Anwendungen aus -Starten Sie mit einer einfachen Anfrage: „Convert 100 degrees Fahrenheit to Celsius“. Der Agent erkennt, dass er das Temperaturumrechnungstool benötigt, ruft es mit den richtigen Parametern auf und liefert das Ergebnis zurück. Beachten Sie, wie natürlich sich das anfühlt – Sie haben nicht angegeben, welches Tool zu verwenden ist oder wie es aufgerufen wird. +Beginne mit einer einfachen Anfrage: „Wandle 100 Grad Fahrenheit in Celsius um“. Der Agent erkennt, dass das Temperaturumrechnungstool benötigt wird, ruft es mit den richtigen Parametern auf und liefert das Ergebnis zurück. Beachte, wie natürlich das wirkt – du hast nicht angegeben, welches Tool genutzt oder wie es aufgerufen werden soll. -### Tool-Verkettung testen +### Teste Tool-Verkettung -Versuchen Sie nun etwas Komplexeres: „What’s the weather in Seattle and convert it to Fahrenheit?“ Sehen Sie, wie der Agent dies in Schritten abarbeitet. Zuerst holt er die Wetterdaten (die in Celsius zurückgegeben werden), erkennt, dass eine Umrechnung zu Fahrenheit nötig ist, ruft das Umrechnungstool auf und kombiniert beide Ergebnisse zu einer Antwort. +Probiere nun etwas Komplexeres: „Wie ist das Wetter in Seattle und wandle es in Fahrenheit um?“ Beobachte, wie der Agent das in Schritten abarbeitet. Zuerst holt er das Wetter (das in Celsius zurückgegeben wird), erkennt, dass eine Umrechnung nach Fahrenheit nötig ist, ruft das Umrechnungstool auf und kombiniert beide Ergebnisse in einer Antwort. -### Gesprächsverlauf ansehen +### Sieh dir den Gesprächsverlauf an -Die Chat-Oberfläche speichert den Gesprächsverlauf, sodass Sie mehrstufige Interaktionen führen können. Sie können alle vorherigen Anfragen und Antworten sehen, was es einfach macht, das Gespräch nachzuvollziehen und zu verstehen, wie der Agent Kontext über mehrere Austausche aufbaut. +Das Chat-Interface speichert die Gesprächshistorie, sodass du mehrstufige Interaktionen führen kannst. Du kannst alle vorherigen Anfragen und Antworten sehen, was das Nachverfolgen des Gesprächs und das Verständnis erleichtert, wie der Agent Kontext über mehrere Austausche aufbaut. Conversation with Multiple Tool Calls -*Mehrstufiges Gespräch mit einfachen Umrechnungen, Wetterabfragen und Tool-Verkettung* +*Mehrstufige Konversation mit einfachen Umrechnungen, Wetterabfragen und Tool-Verkettung* -### Verschiedene Anfragen ausprobieren +### Experimentiere mit verschiedenen Anfragen -Testen Sie verschiedene Kombinationen: -- Wetterabfragen: „What’s the weather in Tokyo?“ -- Temperaturumrechnungen: „What is 25°C in Kelvin?“ -- Kombinierte Anfragen: „Check the weather in Paris and tell me if it’s above 20°C“ +Teste verschiedene Kombinationen: +- Wetterabfragen: „Wie ist das Wetter in Tokio?“ +- Temperaturumrechnungen: „Was sind 25 °C in Kelvin?“ +- Kombinierte Anfragen: „Prüfe das Wetter in Paris und sag mir, ob es über 20 °C ist“ -Beachten Sie, wie der Agent natürliche Sprache interpretiert und in passende Tool-Aufrufe übersetzt. +Beachte, wie der Agent natürliche Sprache interpretiert und passende Tool-Aufrufe daraus ableitet. -## Wichtige Konzepte +## Zentrale Konzepte ### ReAct-Muster (Reasoning and Acting) -Der Agent wechselt zwischen Überlegung (was zu tun ist) und Ausführung (Einsatz von Tools). Dieses Muster ermöglicht eigenständige Problemlösung anstatt nur auf Anweisungen zu reagieren. +Der Agent wechselt zwischen Nachdenken (Entscheiden, was zu tun ist) und Handeln (Tools verwenden). Dieses Muster ermöglicht autonome Problemlösung anstatt nur bloßer Reaktion auf Anweisungen. -### Tool-Beschreibungen sind entscheidend +### Tool-Beschreibungen sind wichtig -Die Qualität Ihrer Tool-Beschreibungen beeinflusst direkt, wie gut der Agent sie nutzt. Klare, spezifische Beschreibungen helfen dem Modell zu verstehen, wann und wie jedes Tool aufgerufen wird. +Die Qualität deiner Tool-Beschreibungen beeinflusst direkt, wie gut der Agent sie nutzt. Klare, spezifische Beschreibungen helfen dem Modell zu verstehen, wann und wie jedes Tool aufzurufen ist. -### Sitzungsverwaltung +### Sitzungsmanagement -Die `@MemoryId`-Annotation ermöglicht automatische sessionsbasierte Speicherverwaltung. Jede Sitzungs-ID erhält eine eigene `ChatMemory`-Instanz, die vom `ChatMemoryProvider`-Bean verwaltet wird, sodass mehrere Benutzer gleichzeitig mit dem Agenten interagieren können, ohne dass sich ihre Gespräche vermischen. Das folgende Diagramm zeigt, wie mehrere Benutzer anhand ihrer Sitzungs-IDs zu isolierten Speicherbereichen geleitet werden: +Die Annotation `@MemoryId` ermöglicht eine automatische speicherbasierte Sitzungsverwaltung. Jede Sitzungs-ID erhält eine eigene `ChatMemory`-Instanz, die vom `ChatMemoryProvider` verwaltet wird, sodass mehrere Nutzer gleichzeitig mit dem Agenten interagieren können, ohne dass sich ihre Gespräche vermischen. Die folgende Grafik zeigt, wie Nutzer anhand ihrer Sitzungs-IDs zu isolierten Speichern geleitet werden: Session Management with @MemoryId -*Jede Sitzungs-ID führt zu einem isolierten Gesprächsverlauf – Benutzer sehen niemals die Nachrichten anderer.* +*Jede Sitzungs-ID führt zu einer getrennten Gesprächshistorie — Nutzer sehen niemals die Nachrichten anderer.* ### Fehlerbehandlung -Tools können fehlschlagen – APIs laufen zeitüberschreitend ab, Parameter können ungültig sein, externe Dienste ausfallen. Produktionsagenten benötigen Fehlerbehandlung, damit das Modell Probleme erklären oder Alternativen versuchen kann statt die gesamte Anwendung abstürzen zu lassen. Wenn ein Tool eine Ausnahme wirft, fängt LangChain4j diese ab und gibt die Fehlermeldung an das Modell zurück, das dann das Problem in natürlicher Sprache erklären kann. +Tools können ausfallen — APIs timeouten, Parameter könnten ungültig sein, externe Dienste fallen aus. Produktive Agenten brauchen Fehlerbehandlung, damit das Modell Probleme erklären oder Alternativen versuchen kann, anstatt die ganze Anwendung abstürzen zu lassen. Wenn ein Tool eine Ausnahme wirft, fängt LangChain4j diese ab und gibt die Fehlermeldung zurück an das Modell, welches dann das Problem in natürlicher Sprache erklären kann. ## Verfügbare Tools -Das folgende Diagramm zeigt das breite Ökosystem an Tools, die Sie bauen können. Dieses Modul zeigt Wetter- und Temperatur-Tools, aber dasselbe `@Tool`-Muster funktioniert für jede Java-Methode — von Datenbankabfragen bis hin zur Zahlungsabwicklung. +Die folgende Grafik zeigt das breite Ökosystem an Tools, die du bauen kannst. Dieses Modul demonstriert Wetter- und Temperaturtools, aber das gleiche `@Tool`-Muster funktioniert für jede Java-Methode — von Datenbankabfragen bis hin zu Zahlungsabwicklung. Tool Ecosystem -*Jede mit @Tool annotierte Java-Methode steht der KI zur Verfügung — das Muster lässt sich auf Datenbanken, APIs, E-Mail, Dateioperationen und mehr erweitern.* +*Jede Java-Methode, die mit @Tool annotiert ist, wird für die KI verfügbar — das Muster erstreckt sich auf Datenbanken, APIs, E-Mail, Dateioperationen und mehr.* -## Wann man toolbasierte Agenten einsetzt +## Wann man Tool-basierte Agenten verwendet -Nicht jede Anfrage benötigt Tools. Die Entscheidung hängt davon ab, ob die KI mit externen Systemen interagieren muss oder aus eigenem Wissen antworten kann. Der folgende Leitfaden fasst zusammen, wann Tools sinnvoll sind und wann nicht: +Nicht jede Anfrage benötigt Tools. Die Entscheidung hängt davon ab, ob die KI mit externen Systemen interagieren muss oder aus ihrem eigenen Wissen antworten kann. Der folgende Leitfaden fasst zusammen, wann Tools Mehrwert bieten und wann sie überflüssig sind: When to Use Tools -*Kurzer Entscheidungsleitfaden – Tools sind für Echtzeitdaten, Berechnungen und Aktionen; allgemeines Wissen und kreative Aufgaben benötigen sie nicht.* +*Eine schnelle Entscheidungshilfe — Tools sind für Echtzeitdaten, Berechnungen und Aktionen; allgemeines Wissen und kreative Aufgaben brauchen sie nicht.* ## Tools vs RAG -Die Module 03 und 04 erweitern beide die Fähigkeiten der KI, aber auf grundlegend unterschiedliche Weise. RAG gibt dem Modell Zugriff auf **Wissen** durch das Abrufen von Dokumenten. Tools geben dem Modell die Möglichkeit, **Aktionen** durch Funktionsaufrufe auszuführen. Das folgende Diagramm vergleicht diese beiden Ansätze nebeneinander – vom jeweiligen Ablauf bis zu den Kompromissen zwischen ihnen: +Module 03 und 04 erweitern beide die Fähigkeiten der KI, aber auf grundverschiedene Weise. RAG gibt dem Modell Zugriff auf **Wissen**, indem Dokumente abgerufen werden. Tools geben dem Modell die Fähigkeit, **Aktionen** auszuführen, indem Funktionen aufgerufen werden. Die folgende Grafik vergleicht beide Ansätze nebeneinander — vom Ablauf jedes Workflows bis zu den jeweiligen Vor- und Nachteilen: Tools vs RAG Comparison -*RAG ruft Informationen aus statischen Dokumenten ab – Tools führen Aktionen aus und holen dynamische, Echtzeit-Daten. Viele produktive Systeme kombinieren beide.* +*RAG holt Informationen aus statischen Dokumenten — Tools führen Aktionen aus und holen dynamische, Echtzeitdaten. Viele produktive Systeme kombinieren beides.* -In der Praxis kombinieren viele produktive Systeme beide Ansätze: RAG, um Antworten auf Basis Ihrer Dokumentation zu verankern, und Tools, um Live-Daten abzurufen oder Operationen durchzuführen. +In der Praxis kombinieren viele produktive Systeme beide Ansätze: RAG für das Verankern von Antworten in deiner Dokumentation, und Tools für das Abrufen von Live-Daten oder das Ausführen von Operationen. ## Nächste Schritte @@ -377,11 +377,11 @@ In der Praxis kombinieren viele produktive Systeme beide Ansätze: RAG, um Antwo --- -**Navigation:** [← Zurück: Modul 03 - RAG](../03-rag/README.md) | [Zurück zum Hauptmenü](../README.md) | [Weiter: Modul 05 - MCP →](../05-mcp/README.md) +**Navigation:** [← Vorheriges: Modul 03 - RAG](../03-rag/README.md) | [Zurück zum Hauptmenü](../README.md) | [Weiter: Modul 05 - MCP →](../05-mcp/README.md) --- -**Haftungsausschluss**: -Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir auf Genauigkeit achten, können automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten. Das Originaldokument in seiner Ursprungssprache ist als maßgebliche Quelle zu betrachten. Für kritische Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Nutzung dieser Übersetzung entstehen. +**Haftungsausschluss**: +Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Bei kritischen Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen. \ No newline at end of file diff --git a/translations/de/README.md b/translations/de/README.md index f222ce6c3..68dd9e1f4 100644 --- a/translations/de/README.md +++ b/translations/de/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j für Einsteiger +# LangChain4j für Anfänger -Ein Kurs zum Erstellen von KI-Anwendungen mit LangChain4j und Azure OpenAI GPT-5.2, von einfachem Chat bis hin zu KI-Agenten. +Ein Kurs zum Erstellen von KI-Anwendungen mit LangChain4j und Azure OpenAI GPT-5.2, vom einfachen Chat bis zu KI-Agenten. ### 🌐 Mehrsprachige Unterstützung -#### Unterstützt durch GitHub Action (Automatisiert & Immer Aktuell) +#### Unterstützt über GitHub Action (Automatisiert & Immer Aktuell) -[Arabisch](../ar/README.md) | [Bengalisch](../bn/README.md) | [Bulgarisch](../bg/README.md) | [Birmanisch (Myanmar)](../my/README.md) | [Chinesisch (Vereinfacht)](../zh-CN/README.md) | [Chinesisch (Traditionell, Hongkong)](../zh-HK/README.md) | [Chinesisch (Traditionell, Macau)](../zh-MO/README.md) | [Chinesisch (Traditionell, Taiwan)](../zh-TW/README.md) | [Kroatisch](../hr/README.md) | [Tschechisch](../cs/README.md) | [Dänisch](../da/README.md) | [Niederländisch](../nl/README.md) | [Estnisch](../et/README.md) | [Finnisch](../fi/README.md) | [Französisch](../fr/README.md) | [Deutsch](./README.md) | [Griechisch](../el/README.md) | [Hebräisch](../he/README.md) | [Hindi](../hi/README.md) | [Ungarisch](../hu/README.md) | [Indonesisch](../id/README.md) | [Italienisch](../it/README.md) | [Japanisch](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Koreanisch](../ko/README.md) | [Litauisch](../lt/README.md) | [Malaiisch](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalesisch](../ne/README.md) | [Nigerianisches Pidgin](../pcm/README.md) | [Norwegisch](../no/README.md) | [Persisch (Farsi)](../fa/README.md) | [Polnisch](../pl/README.md) | [Portugiesisch (Brasilien)](../pt-BR/README.md) | [Portugiesisch (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Rumänisch](../ro/README.md) | [Russisch](../ru/README.md) | [Serbisch (Kyrillisch)](../sr/README.md) | [Slowakisch](../sk/README.md) | [Slowenisch](../sl/README.md) | [Spanisch](../es/README.md) | [Suaheli](../sw/README.md) | [Schwedisch](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thailändisch](../th/README.md) | [Türkisch](../tr/README.md) | [Ukrainisch](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamesisch](../vi/README.md) +[Arabisch](../ar/README.md) | [Bengalisch](../bn/README.md) | [Bulgarisch](../bg/README.md) | [Birma (Myanmar)](../my/README.md) | [Chinesisch (Vereinfacht)](../zh-CN/README.md) | [Chinesisch (Traditionell, Hongkong)](../zh-HK/README.md) | [Chinesisch (Traditionell, Macau)](../zh-MO/README.md) | [Chinesisch (Traditionell, Taiwan)](../zh-TW/README.md) | [Kroatisch](../hr/README.md) | [Tschechisch](../cs/README.md) | [Dänisch](../da/README.md) | [Niederländisch](../nl/README.md) | [Estnisch](../et/README.md) | [Finnisch](../fi/README.md) | [Französisch](../fr/README.md) | [Deutsch](./README.md) | [Griechisch](../el/README.md) | [Hebräisch](../he/README.md) | [Hindi](../hi/README.md) | [Ungarisch](../hu/README.md) | [Indonesisch](../id/README.md) | [Italienisch](../it/README.md) | [Japanisch](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Koreanisch](../ko/README.md) | [Litauisch](../lt/README.md) | [Malaiisch](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalesisch](../ne/README.md) | [Nigerianisches Pidgin](../pcm/README.md) | [Norwegisch](../no/README.md) | [Persisch (Farsi)](../fa/README.md) | [Polnisch](../pl/README.md) | [Portugiesisch (Brasilien)](../pt-BR/README.md) | [Portugiesisch (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Rumänisch](../ro/README.md) | [Russisch](../ru/README.md) | [Serbisch (Kyrillisch)](../sr/README.md) | [Slowakisch](../sk/README.md) | [Slowenisch](../sl/README.md) | [Spanisch](../es/README.md) | [Suaheli](../sw/README.md) | [Schwedisch](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thailändisch](../th/README.md) | [Türkisch](../tr/README.md) | [Ukrainisch](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamesisch](../vi/README.md) -> **Lieber lokal klonen?** +> **Bevorzugen Sie das lokale Klonen?** > -> Dieses Repository enthält mehr als 50 Sprachübersetzungen, was die Downloadgröße erheblich erhöht. Um ohne Übersetzungen zu klonen, verwenden Sie Sparse Checkout: +> Dieses Repository enthält über 50 Sprachübersetzungen, die die Download-Größe erheblich erhöhen. Um ohne Übersetzungen zu klonen, verwenden Sie Sparse Checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,17 +29,16 @@ Ein Kurs zum Erstellen von KI-Anwendungen mit LangChain4j und Azure OpenAI GPT-5 > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> So erhalten Sie alles, was Sie brauchen, um den Kurs mit deutlich schnellerem Download abzuschließen. +> Dies gibt Ihnen alles, was Sie benötigen, um den Kurs mit einem viel schnelleren Download abzuschließen. ## Inhaltsverzeichnis -1. [Schnellstart](00-quick-start/README.md) - Einstieg in LangChain4j -2. [Einführung](01-introduction/README.md) - Erlernen der Grundlagen von LangChain4j -3. [Prompt Engineering](02-prompt-engineering/README.md) - Meistere effektives Prompt-Design -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Aufbau intelligenter wissensbasierter Systeme -5. [Werkzeuge](04-tools/README.md) - Integration externer Tools und einfacher Assistenten -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Arbeiten mit dem Model Context Protocol (MCP) und Agentenmodulen +1. [Einführung](01-introduction/README.md) - Lernen Sie die Grundlagen von LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Meistern Sie effektives Prompt-Design +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Erstellen Sie intelligente wissensbasierte Systeme +4. [Werkzeuge](04-tools/README.md) - Integrieren Sie externe Werkzeuge und einfache Assistenten +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Arbeiten Sie mit dem Model Context Protocol (MCP) und agentischen Modulen ### Video-Durchgänge @@ -56,55 +55,55 @@ Jedes Modul hat eine begleitende Live-Session, in der wir die Konzepte und den C ## Lernpfad -**Neu bei LangChain4j?** Schau dir das [Glossar](docs/GLOSSARY.md) für Definitionen wichtiger Begriffe und Konzepte an. +**Neu bei LangChain4j?** Sehen Sie sich das [Glossar](docs/GLOSSARY.md) für Definitionen wichtiger Begriffe und Konzepte an. > **Schnellstart** -1. Forke dieses Repository auf dein GitHub-Konto -2. Klicke auf **Code** → Tab **Codespaces** → **...** → **Neu mit Optionen...** -3. Verwende die Standardeinstellungen – damit wird der für diesen Kurs erstellte Entwicklungscontainer ausgewählt -4. Klicke auf **Codespace erstellen** -5. Warte 5-10 Minuten, bis die Umgebung bereit ist -6. Springe direkt zu [Schnellstart](./00-quick-start/README.md), um loszulegen! +1. Forken Sie dieses Repository in Ihrem GitHub-Konto +2. Klicken Sie auf **Code** → **Codespaces** Tab → **...** → **Neu mit Optionen...** +3. Verwenden Sie die Standardwerte – dies wählt den für diesen Kurs erstellten Entwicklungscontainer aus +4. Klicken Sie auf **Codespace erstellen** +5. Warten Sie 5-10 Minuten, bis die Umgebung bereit ist +6. Gehen Sie direkt zur [Einführung](./01-introduction/README.md), um zu starten! -Nach Abschluss der Module erkunde den [Testleitfaden](docs/TESTING.md), um LangChain4j-Testkonzepte in Aktion zu sehen. +Nach Abschluss der Module erkunden Sie den [Testleitfaden](docs/TESTING.md), um LangChain4j-Testkonzepte in Aktion zu sehen. -> **Hinweis:** Dieses Training verwendet sowohl GitHub-Modelle als auch Azure OpenAI. Das Modul [Schnellstart](00-quick-start/README.md) verwendet GitHub-Modelle (kein Azure-Abonnement erforderlich), während die Module 1–5 Azure OpenAI nutzen. Erstelle ein [KOSTENLOSES Azure-Konto](https://aka.ms/azure-free-account), falls du noch keines hast. +> **Hinweis:** Diese Schulung verwendet Azure OpenAI. Starten Sie mit einem [KOSTENLOSEN Azure-Konto](https://aka.ms/azure-free-account), wenn Sie noch keines haben. ## Lernen mit GitHub Copilot -Um schnell mit dem Codieren zu beginnen, öffne dieses Projekt in einem GitHub Codespace oder deiner lokalen IDE mit dem bereitgestellten Devcontainer. Der in diesem Kurs verwendete Devcontainer ist vorkonfiguriert mit GitHub Copilot für KI-gestütztes Paarprogrammieren. +Um schnell mit dem Programmieren zu beginnen, öffnen Sie dieses Projekt in einem GitHub Codespace oder in Ihrer lokalen IDE mit dem bereitgestellten Devcontainer. Der in diesem Kurs verwendete Devcontainer ist vorkonfiguriert mit GitHub Copilot für AI-Paarprogrammierung. -Jedes Codebeispiel enthält vorgeschlagene Fragen, die du GitHub Copilot stellen kannst, um dein Verständnis zu vertiefen. Achte auf die 💡/🤖-Hinweise in: +Jedes Codebeispiel enthält vorgeschlagene Fragen, die Sie GitHub Copilot stellen können, um Ihr Verständnis zu vertiefen. Achten Sie auf die 💡/🤖 Hinweise in: -- **Java-Dateikopfzeilen** – Fragen speziell zu jedem Beispiel -- **Modul-READMEs** – Erkundungsfragen nach Codebeispielen +- **Java-Dateiköpfen** - Fragen, die spezifisch für jedes Beispiel sind +- **Modul-READMEs** - Erkundungsaufforderungen nach Codebeispielen -**So nutzt du es:** Öffne eine beliebige Code-Datei und stelle Copilot die vorgeschlagenen Fragen. Er hat den vollständigen Kontext des Codes und kann erklären, erweitern und Alternativen vorschlagen. +**Wie man es verwendet:** Öffnen Sie eine beliebige Code-Datei und stellen Sie Copilot die vorgeschlagenen Fragen. Es hat vollen Kontext des Codes und kann erklären, erweitern und Alternativen vorschlagen. -Möchtest du mehr lernen? Schau dir [Copilot für KI-Paarprogrammierung](https://aka.ms/GitHubCopilotAI) an. +Möchten Sie mehr lernen? Sehen Sie sich [Copilot für AI-Paarprogrammierung](https://aka.ms/GitHubCopilotAI) an. ## Zusätzliche Ressourcen ### LangChain -[![LangChain4j für Einsteiger](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js für Einsteiger](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain für Einsteiger](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j für Anfänger](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js für Anfänger](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain für Anfänger](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- ### Azure / Edge / MCP / Agenten -[![AZD für Einsteiger](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI für Einsteiger](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP für Einsteiger](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![KI-Agenten für Einsteiger](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AZD für Anfänger](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI für Anfänger](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP für Anfänger](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![KI-Agenten für Anfänger](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Generative KI-Serie -[![Generative KI für Einsteiger](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generative KI für Anfänger](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generative KI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generative KI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) [![Generative KI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) @@ -112,39 +111,40 @@ Möchtest du mehr lernen? Schau dir [Copilot für KI-Paarprogrammierung](https:/ --- ### Kernlernen -[![ML für Einsteiger](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Datenwissenschaft für Einsteiger](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![KI für Einsteiger](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![ML für Anfänger](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Datenwissenschaft für Anfänger](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![KI für Anfänger](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Cybersecurity für Anfänger](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Webentwicklung für Anfänger](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT für Anfänger](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR-Entwicklung für Anfänger](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Copilot-Serie -[![Copilot für KI-Paarprogrammierung](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot für C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot-Abenteuer](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +### Copilot Serie +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Hilfe erhalten -Wenn Sie nicht weiterkommen oder Fragen zur Entwicklung von KI-Anwendungen haben, treten Sie bei: +Wenn Sie nicht weiterkommen oder Fragen zum Erstellen von KI-Apps haben, treten Sie bei: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Wenn Sie Produktfeedback oder Fehler beim Entwickeln haben, besuchen Sie: +Wenn Sie Produktfeedback oder Fehler beim Erstellen haben, besuchen Sie: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Lizenz -MIT-Lizenz – Details finden Sie in der [LICENSE](../../LICENSE)-Datei. +MIT-Lizenz – Details siehe [LICENSE](../../LICENSE) Datei. --- -**Haftungsausschluss**: -Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, sollten Sie beachten, dass automatische Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Für wichtige Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die durch die Verwendung dieser Übersetzung entstehen. +**Haftungsausschluss**: +Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Bei kritischen Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen. \ No newline at end of file diff --git a/translations/de/docs/GLOSSARY.md b/translations/de/docs/GLOSSARY.md index 86c090c2e..ee4d770a8 100644 --- a/translations/de/docs/GLOSSARY.md +++ b/translations/de/docs/GLOSSARY.md @@ -2,175 +2,175 @@ ## Inhaltsverzeichnis -- [Kernkonzepte](../../../docs) -- [LangChain4j-Komponenten](../../../docs) -- [KI/ML-Konzepte](../../../docs) -- [Guardrails](../../../docs) -- [Prompt-Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agenten und Tools](../../../docs) -- [Agentisches Modul](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure-Dienste](../../../docs) -- [Testen und Entwicklung](../../../docs) - -Schnelle Referenz für Begriffe und Konzepte, die im gesamten Kurs verwendet werden. +- [Kernkonzepte](#kernkonzepte) +- [LangChain4j-Komponenten](#langchain4j-komponenten) +- [KI/ML-Konzepte](#kiml-konzepte) +- [Schutzmaßnahmen](#schutzmaßnahmen) +- [Prompt Engineering](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agenten und Werkzeuge](#agents-and-tools---module-04) +- [Agentisches Modul](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure-Dienste](#azure-services---module-01) +- [Testen und Entwicklung](#testing-and-development---testing-guide) + +Kurze Referenz für Begriffe und Konzepte, die im gesamten Kurs verwendet werden. ## Kernkonzepte -**KI-Agent** – System, das KI verwendet, um autonom zu denken und zu handeln. [Modul 04](../04-tools/README.md) +**KI-Agent** – System, das KI nutzt, um autonom zu denken und zu handeln. [Modul 04](../04-tools/README.md) -**Chain** – Abfolge von Operationen, bei der die Ausgabe in den nächsten Schritt eingeht. +**Kette** – Abfolge von Operationen, bei denen die Ausgabe in den nächsten Schritt fließt. -**Chunking** – Aufteilen von Dokumenten in kleinere Stücke. Typisch: 300–500 Tokens mit Überlappung. [Modul 03](../03-rag/README.md) +**Chunking** – Aufteilen von Dokumenten in kleinere Stücke. Typisch: 300-500 Tokens mit Überlappung. [Modul 03](../03-rag/README.md) **Kontextfenster** – Maximale Tokens, die ein Modell verarbeiten kann. GPT-5.2: 400K Tokens (bis zu 272K Eingabe, 128K Ausgabe). -**Embeddings** – Numerische Vektoren, die die Bedeutung von Text repräsentieren. [Modul 03](../03-rag/README.md) +**Embeddings** – Numerische Vektoren, die die Bedeutung von Text darstellen. [Modul 03](../03-rag/README.md) -**Funktionsaufruf** – Modell erzeugt strukturierte Anfragen, um externe Funktionen aufzurufen. [Modul 04](../04-tools/README.md) +**Funktionsaufruf** – Modell generiert strukturierte Anfragen, um externe Funktionen aufzurufen. [Modul 04](../04-tools/README.md) -**Halluzination** – Wenn Modelle falsche, aber plausible Informationen generieren. +**Halluzination** – Wenn Modelle falsche, aber plausible Informationen erzeugen. **Prompt** – Texteingabe an ein Sprachmodell. [Modul 02](../02-prompt-engineering/README.md) -**Semantische Suche** – Suche nach Bedeutung mittels Embeddings, nicht Schlüsselwörtern. [Modul 03](../03-rag/README.md) +**Semantische Suche** – Suche nach Bedeutung mit Embeddings, nicht mit Schlüsselwörtern. [Modul 03](../03-rag/README.md) -**Zustandsbehaftet vs. zustandslos** – Zustandslos: kein Gedächtnis. Zustandsbehaftet: speichert Gesprächshistorie. [Modul 01](../01-introduction/README.md) +**Zustandsbehaftet vs. Zustandslos** – Zustandslos: kein Gedächtnis. Zustandsbehaftet: speichert Gesprächshistorie. [Modul 01](../01-introduction/README.md) -**Tokens** – Grundlegende Textbausteine, die Modelle verarbeiten. Beeinflussen Kosten und Limits. [Modul 01](../01-introduction/README.md) +**Tokens** – Basiseinheiten von Text, die Modelle verarbeiten. Beeinflussen Kosten und Limits. [Modul 01](../01-introduction/README.md) -**Tool Chaining** – Sequenzielle Ausführung von Tools, wobei Ausgabe den nächsten Aufruf informiert. [Modul 04](../04-tools/README.md) +**Tool Chaining** – Sequenzielle Ausführung von Werkzeugen, bei der die Ausgabe den nächsten Aufruf informiert. [Modul 04](../04-tools/README.md) ## LangChain4j-Komponenten -**AiServices** – Erstellt typsichere KI-Service-Interfaces. +**AiServices** – Erstellt typsichere KI-Service-Schnittstellen. -**OpenAiOfficialChatModel** – Einheitlicher Client für OpenAI- und Azure OpenAI-Modelle. +**OpenAiOfficialChatModel** – Vereinheitlichter Client für OpenAI und Azure OpenAI Modelle. -**OpenAiOfficialEmbeddingModel** – Erzeugt Embeddings mit OpenAI Official Client (unterstützt OpenAI und Azure OpenAI). +**OpenAiOfficialEmbeddingModel** – Erstellt Embeddings mittels OpenAI Official Client (unterstützt sowohl OpenAI als auch Azure OpenAI). -**ChatModel** – Kerninterface für Sprachmodelle. +**ChatModel** – Kernschnittstelle für Sprachmodelle. -**ChatMemory** – Speichert Gesprächshistorie. +**ChatMemory** – Speichert die Gesprächshistorie. -**ContentRetriever** – Findet relevante Dokumentabschnitte für RAG. +**ContentRetriever** – Findet relevante Dokumentausschnitte für RAG. -**DocumentSplitter** – Teilt Dokumente in Abschnitte auf. +**DocumentSplitter** – Teilt Dokumente in Stücke. **EmbeddingModel** – Wandelt Text in numerische Vektoren um. **EmbeddingStore** – Speichert und ruft Embeddings ab. -**MessageWindowChatMemory** – Pflegt ein gleitendes Fenster der letzten Nachrichten. +**MessageWindowChatMemory** – Speichert einen gleitenden Fensterbereich der letzten Nachrichten. -**PromptTemplate** – Erstellt wiederverwendbare Prompts mit `{{variable}}`-Platzhaltern. +**PromptTemplate** – Erzeugt wiederverwendbare Prompts mit `{{variable}}` Platzhaltern. -**TextSegment** – Textabschnitt mit Metadaten. Verwendet in RAG. +**TextSegment** – Textabschnitt mit Metadaten. Wird in RAG verwendet. -**ToolExecutionRequest** – Repräsentiert eine Tool-Ausführungsanfrage. +**ToolExecutionRequest** – Stellt eine Anfrage zur Tool-Ausführung dar. -**UserMessage / AiMessage / SystemMessage** – Nachrichtentypen im Gespräch. +**UserMessage / AiMessage / SystemMessage** – Nachrichtentypen in Gesprächen. ## KI/ML-Konzepte -**Few-Shot Learning** – Beispiele in Prompts bereitstellen. [Modul 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** – Beispiele in Prompts geben. [Modul 02](../02-prompt-engineering/README.md) -**Großes Sprachmodell (LLM)** – KI-Modelle, die auf umfangreichen Textdaten trainiert sind. +**Großes Sprachmodell (LLM)** – KI-Modelle, die auf großen Textmengen trainiert sind. -**Reasoning Effort** – GPT-5.2-Parameter zur Steuerung der Denktiefe. [Modul 02](../02-prompt-engineering/README.md) +**Reasoning Effort** – GPT-5.2 Parameter zur Steuerung der Denkintensität. [Modul 02](../02-prompt-engineering/README.md) -**Temperatur** – Steuert Zufälligkeit der Ausgabe. Niedrig=deterministisch, hoch=kreativ. +**Temperatur** – Steuert die Zufälligkeit der Ausgabe. Niedrig=deterministisch, hoch=kreativ. -**Vektordatenbank** – Spezialisierte Datenbank für Embeddings. [Modul 03](../03-rag/README.md) +**Vektor-Datenbank** – Spezialisierte Datenbank für Embeddings. [Modul 03](../03-rag/README.md) **Zero-Shot Learning** – Aufgaben ohne Beispiele ausführen. [Modul 02](../02-prompt-engineering/README.md) -## Guardrails - [Modul 00](../00-quick-start/README.md) +## Schutzmaßnahmen -**Defense in Depth** – Mehrschichtiger Sicherheitsansatz, der Anwendungsebene-Guardrails mit Sicherheitfiltern des Anbieters kombiniert. +**Verteidigung in der Tiefe** – Mehrschichtiger Sicherheitsansatz, der Anwendungsschutz mit Anbietersicherheitsfiltern kombiniert. -**Hard Block** – Anbieter wirft HTTP-400-Fehler bei schweren Inhaltsverstößen. +**Hard Block** – Provider wirft HTTP 400 Fehler bei schweren Inhaltsverstößen. -**InputGuardrail** – LangChain4j-Interface zur Validierung von Benutzereingaben vor dem Erreichen des LLM. Spart Kosten und Latenz durch frühes Sperren schädlicher Prompts. +**InputGuardrail** – LangChain4j-Schnittstelle zur Validierung der Benutzereingabe vor Übergabe an das LLM. Spart Kosten und Latenz, indem schädliche Prompts früh blockiert werden. -**InputGuardrailResult** – Rückgabetyp für Guardrail-Validierung: `success()` oder `fatal("reason")`. +**InputGuardrailResult** – Rückgabetyp für Guardrail-Validierung: `success()` oder `fatal("Grund")`. -**OutputGuardrail** – Interface zur Validierung von KI-Antworten vor der Rückgabe an Nutzer. +**OutputGuardrail** – Schnittstelle zur Validierung von KI-Antworten, bevor sie an Benutzer zurückgegeben werden. -**Sicherheitsfilter des Anbieters** – Eingebaute Inhaltsfilter von KI-Anbietern (z.B. GitHub Models), die Verstöße auf API-Ebene erfassen. +**Provider Safety Filters** – Eingebaute Inhaltsfilter der KI-Anbieter (z. B. Azure OpenAI), die Verstöße auf API-Ebene erkennen. -**Soft Refusal** – Modell lehnt höflich ab, ohne Fehler zu werfen. +**Soft Refusal** – Modell lehnt höflich ab zu antworten, ohne einen Fehler auszulösen. -## Prompt-Engineering - [Modul 02](../02-prompt-engineering/README.md) +## Prompt Engineering - [Modul 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** – Schrittweises Denken für bessere Genauigkeit. +**Chain-of-Thought** – Schritt-für-Schritt-Denken für höhere Genauigkeit. -**Eingeschränkte Ausgabe** – Erzwingung eines bestimmten Formats oder einer Struktur. +**Eingeschränkte Ausgabe** – Erzwingt bestimmtes Format oder Struktur. -**Hohe Nachdrücklichkeit** – GPT-5.2-Muster für gründliches Denken. +**Hohe Eiferbereitschaft** – GPT-5.2 Muster für gründliches Nachdenken. -**Niedrige Nachdrücklichkeit** – GPT-5.2-Muster für schnelle Antworten. +**Niedrige Eiferbereitschaft** – GPT-5.2 Muster für schnelle Antworten. -**Multi-Turn-Konversation** – Kontext über mehrere Austausch hinweg aufrechterhalten. +**Multi-Turn Conversation** – Kontext über mehrere Austausche beibehalten. -**Rollenspezifisches Prompting** – Modellpersona über Systemnachrichten festlegen. +**Rollenbasiertes Prompting** – Modell-Persona durch Systemnachrichten festlegen. **Selbstreflexion** – Modell bewertet und verbessert seine Ausgabe. -**Strukturierte Analyse** – Festes Bewertungsframework. +**Strukturierte Analyse** – Fester Bewertungsrahmen. -**Task Execution Pattern** – Planen → Ausführen → Zusammenfassen. +**Aufgaben-Ausführungsmuster** – Planen → Ausführen → Zusammenfassen. ## RAG (Retrieval-Augmented Generation) - [Modul 03](../03-rag/README.md) -**Dokumentenverarbeitungspipeline** – Laden → Aufteilen → Einbetten → Speichern. +**Dokumentenverarbeitungspipeline** – Laden → chunking → embedding → speichern. -**In-Memory Embedding Store** – Nicht persistenter Speicher zum Testen. +**In-Memory Embedding Store** – Nicht persistenter Speicher für Tests. -**RAG** – Kombination aus Abruf und Generierung zur Fundierung von Antworten. +**RAG** – Kombiniert Abruf mit Generierung, um Antworten zu belegen. -**Ähnlichkeitsscore** – Maß (0–1) für semantische Ähnlichkeit. +**Ähnlichkeitsscore** – Maß (0-1) für semantische Ähnlichkeit. -**Quellenverweis** – Metadaten zu abgerufenen Inhalten. +**Quellenreferenz** – Metadaten über abgerufene Inhalte. -## Agenten und Tools - [Modul 04](../04-tools/README.md) +## Agenten und Werkzeuge - [Modul 04](../04-tools/README.md) -**@Tool Annotation** – Kennzeichnet Java-Methoden als KI-aufrufbare Tools. +**@Tool Annotation** – Markiert Java-Methoden als von KI aufrufbare Werkzeuge. -**ReAct Pattern** – Reason → Act → Observe → Repeat. +**ReAct Muster** – Überlegen → Handeln → Beobachten → Wiederholen. -**Sitzungsverwaltung** – Separate Kontexte für verschiedene Nutzer. +**Sitzungsmanagement** – Getrennte Kontexte für verschiedene Benutzer. -**Tool** – Funktion, die ein KI-Agent aufrufen kann. +**Werkzeug** – Funktion, die ein KI-Agent aufrufen kann. -**Toolbeschreibung** – Dokumentation von Zweck und Parametern eines Tools. +**Werkzeugbeschreibung** – Dokumentation von Zweck und Parametern. ## Agentisches Modul - [Modul 05](../05-mcp/README.md) -**@Agent Annotation** – Kennzeichnet Interfaces als KI-Agenten mit deklarativer Verhaltensdefinition. +**@Agent Annotation** – Markiert Schnittstellen als KI-Agenten mit deklarativer Verhaltensdefinition. -**Agent Listener** – Hook zur Überwachung der Agentenausführung via `beforeAgentInvocation()` und `afterAgentInvocation()`. +**Agent Listener** – Hook zur Überwachung der Agentausführung via `beforeAgentInvocation()` und `afterAgentInvocation()`. -**Agentic Scope** – Gemeinsamer Speicher, in dem Agenten Ausgaben mit `outputKey` speichern, damit nachfolgende Agenten sie konsumieren können. +**Agentic Scope** – Gemeinsamer Speicher, in dem Agenten Ergebnisse unter `outputKey` ablegen, damit nachfolgende Agenten sie verwenden können. -**AgenticServices** – Fabrik zur Erstellung von Agenten mittels `agentBuilder()` und `supervisorBuilder()`. +**AgenticServices** – Fabrik für das Erstellen von Agenten über `agentBuilder()` und `supervisorBuilder()`. -**Conditional Workflow** – Route basierend auf Bedingungen zu verschiedenen Spezialagenten. +**Conditional Workflow** – Weiterleitung basierend auf Bedingungen zu verschiedenen Spezial-Agenten. -**Human-in-the-Loop** – Workflow-Muster mit menschlichen Kontrollpunkten zur Genehmigung oder Inhaltsprüfung. +**Human-in-the-Loop** – Workflow-Muster mit menschlichen Kontrollpunkten für Freigabe oder Inhaltsprüfung. -**langchain4j-agentic** – Maven-Abhängigkeit für deklarativen Agentenbau (experimentell). +**langchain4j-agentic** – Maven-Abhängigkeit für deklaratives Agentenbauen (experimentell). -**Loop Workflow** – Wiederholte Agentenausführung, bis eine Bedingung erfüllt ist (z.B. Qualitätswert ≥ 0,8). +**Loop Workflow** – Wiederholte Agentenausführung bis eine Bedingung erfüllt ist (z. B. Qualitätswert ≥ 0.8). -**outputKey** – Agenten-Annotierungsparameter, der angibt, wo Ergebnisse im Agentic Scope gespeichert werden. +**outputKey** – Agentenannotation-Parameter, der angibt, wo Ergebnisse im Agentic Scope gespeichert werden. **Parallel Workflow** – Gleichzeitiges Ausführen mehrerer Agenten für unabhängige Aufgaben. **Response Strategy** – Wie der Supervisor die finale Antwort formuliert: LAST, SUMMARY oder SCORED. -**Sequential Workflow** – Agenten in Reihenfolge ausführen, bei der Ausgabe zum nächsten Schritt fließt. +**Sequential Workflow** – Agenten nacheinander ausführen, wobei die Ausgabe zum nächsten Schritt fließt. **Supervisor Agent Pattern** – Fortgeschrittenes agentisches Muster, bei dem ein Supervisor-LLM dynamisch entscheidet, welche Unteragenten aufgerufen werden. @@ -178,47 +178,45 @@ Schnelle Referenz für Begriffe und Konzepte, die im gesamten Kurs verwendet wer **langchain4j-mcp** – Maven-Abhängigkeit für MCP-Integration in LangChain4j. -**MCP** – Model Context Protocol: Standard für die Verbindung von KI-Apps mit externen Tools. Einmal bauen, überall verwenden. +**MCP** – Model Context Protocol: Standard zur Verbindung von KI-Anwendungen mit externen Werkzeugen. Einmal bauen, überall verwenden. -**MCP Client** – Anwendung, die sich mit MCP-Servern verbindet, um Tools zu entdecken und zu nutzen. +**MCP Client** – Anwendung, die sich mit MCP-Servern verbindet, um Werkzeuge zu entdecken und zu nutzen. -**MCP Server** – Dienst, der Tools über MCP mit klaren Beschreibungen und Parameterschemata bereitstellt. +**MCP Server** – Dienst, der Werkzeuge via MCP mit klaren Beschreibungen und Parameterschemata bereitstellt. -**McpToolProvider** – LangChain4j-Komponente, die MCP-Tools für KI-Dienste und Agenten einbindet. +**McpToolProvider** – LangChain4j-Komponente, die MCP-Werkzeuge für KI-Services und Agenten einbindet. -**McpTransport** – Interface für MCP-Kommunikation. Implementierungen umfassen Stdio und HTTP. +**McpTransport** – Schnittstelle für MCP-Kommunikation. Implementierungen umfassen Stdio und HTTP. -**Stdio Transport** – Lokaler Prozess-Transport via stdin/stdout. Nützlich für Dateisystemzugriff oder Kommandozeilentools. +**Stdio Transport** – Lokaler Prozess-Transport über stdin/stdout. Nützlich für Dateisystemzugriff oder Kommandozeilenwerkzeuge. -**StdioMcpTransport** – LangChain4j-Implementation, die MCP-Server als Nebenprozess startet. +**StdioMcpTransport** – LangChain4j-Implementierung, die den MCP-Server als Unterprozess startet. -**Tool Discovery** – Client fragt Server nach verfügbaren Tools mit Beschreibungen und Schemata ab. +**Werkzeugentdeckung** – Client fragt Server nach verfügbaren Werkzeugen mit Beschreibungen und Schemata ab. ## Azure-Dienste - [Modul 01](../01-introduction/README.md) -**Azure AI Search** – Cloud-Suche mit Vektorfähigkeiten. [Modul 03](../03-rag/README.md) +**Azure AI Search** – Cloudsuche mit Vektorfähigkeiten. [Modul 03](../03-rag/README.md) **Azure Developer CLI (azd)** – Stellt Azure-Ressourcen bereit. -**Azure OpenAI** – Microsofts Unternehmens-KI-Dienst. +**Azure OpenAI** – Microsofts KI-Enterprise-Dienst. -**Bicep** – Azure-Infrastructure-as-Code-Sprache. [Infrastructure Guide](../01-introduction/infra/README.md) +**Bicep** – Infrastructure-as-Code-Sprache für Azure. [Infrastruktur-Anleitung](../01-introduction/infra/README.md) -**Deployment-Name** – Name für Modellausrollung in Azure. +**Bereitstellungsname** – Name für Modellbereitstellung in Azure. -**GPT-5.2** – Neuestes OpenAI-Modell mit Steuerung der Denkprozesse. [Modul 02](../02-prompt-engineering/README.md) +**GPT-5.2** – Neuestes OpenAI-Modell mit Steuerung der Denkweise. [Modul 02](../02-prompt-engineering/README.md) ## Testen und Entwicklung - [Testing Guide](TESTING.md) **Dev Container** – Containerisierte Entwicklungsumgebung. [Konfiguration](../../../.devcontainer/devcontainer.json) -**GitHub Models** – Kostenlose KI-Modellspielwiese. [Modul 00](../00-quick-start/README.md) +**In-Memory Testing** – Testen mit im Speicher gehaltenen Daten. -**In-Memory Testing** – Testen mit In-Memory-Speicher. +**Integration Testing** – Testen mit echter Infrastruktur. -**Integration Testing** – Testen mit realer Infrastruktur. - -**Maven** – Java-Build-Automatisierungswerkzeug. +**Maven** – Java-Build-Automatisierungstool. **Mockito** – Java-Mocking-Framework. @@ -227,6 +225,6 @@ Schnelle Referenz für Begriffe und Konzepte, die im gesamten Kurs verwendet wer --- -**Haftungsausschluss**: -Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, kann es bei automatischen Übersetzungen zu Fehlern oder Ungenauigkeiten kommen. Das Originaldokument in seiner Ursprungssprache ist als maßgebliche Quelle anzusehen. Für wichtige Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen. +**Haftungsausschluss**: +Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Bei kritischen Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen. \ No newline at end of file diff --git a/translations/de/docs/TESTING.md b/translations/de/docs/TESTING.md index 5cefed7f7..6801ea3e9 100644 --- a/translations/de/docs/TESTING.md +++ b/translations/de/docs/TESTING.md @@ -2,15 +2,15 @@ ## Inhaltsverzeichnis -- [Schnellstart](../../../docs) -- [Was die Tests abdecken](../../../docs) -- [Tests ausführen](../../../docs) -- [Tests in VS Code ausführen](../../../docs) -- [Testmuster](../../../docs) -- [Testphilosophie](../../../docs) -- [Nächste Schritte](../../../docs) +- [Schnellstart](#schnellstart) +- [Was die Tests abdecken](#was-die-tests-abdecken) +- [Tests ausführen](#tests-ausführen) +- [Tests in VS Code ausführen](#tests-in-vs-code-ausführen) +- [Testmuster](#testmuster) +- [Testphilosophie](#testphilosophie) +- [Nächste Schritte](#nächste-schritte) -Diese Anleitung führt Sie durch die Tests, die zeigen, wie man KI-Anwendungen testet, ohne API-Schlüssel oder externe Dienste zu benötigen. +Dieser Leitfaden führt Sie durch die Tests, die zeigen, wie man KI-Anwendungen testet, ohne API-Schlüssel oder externe Dienste zu benötigen. ## Schnellstart @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Wenn alle Tests bestanden sind, sollten Sie eine Ausgabe wie im folgenden Screenshot sehen – die Tests laufen ohne Fehler durch. +Wenn alle Tests bestehen, sollten Sie eine Ausgabe wie im Screenshot unten sehen — Tests werden fehlerfrei ausgeführt. -Erfolgreiche Testergebnisse +Successful Test Results *Erfolgreiche Testausführung, die zeigt, dass alle Tests ohne Fehler bestanden wurden* ## Was die Tests abdecken -Dieser Kurs konzentriert sich auf **Unit-Tests**, die lokal ausgeführt werden. Jeder Test zeigt ein bestimmtes LangChain4j-Konzept isoliert. Die untenstehende Testpyramide zeigt, wo Unit-Tests stehen – sie bilden die schnelle und zuverlässige Grundlage, auf der der Rest Ihrer Teststrategie aufbaut. +Dieser Kurs konzentriert sich auf **Unit-Tests**, die lokal ausgeführt werden. Jeder Test demonstriert ein spezifisches LangChain4j-Konzept isoliert. Die untenstehende Testpyramide zeigt, wo Unit-Tests passen — sie bilden die schnelle, zuverlässige Grundlage, auf der Ihre restliche Teststrategie aufbaut. -Testpyramide +Testing Pyramid -*Testpyramide, die das Verhältnis zwischen Unit-Tests (schnell, isoliert), Integrationstests (echte Komponenten) und End-to-End-Tests zeigt. Dieses Training behandelt Unit-Tests.* +*Testpyramide, die das Gleichgewicht zwischen Unit-Tests (schnell, isoliert), Integrationstests (echte Komponenten) und End-to-End-Tests zeigt. Dieses Training behandelt Unit-Tests.* | Modul | Tests | Fokus | Wichtige Dateien | -|--------|-------|-------|-----------| -| **00 - Schnellstart** | 6 | Prompt-Vorlagen und Variablensubstitution | `SimpleQuickStartTest.java` | -| **01 - Einführung** | 8 | Gesprächsspeicher und zustandsbehafteter Chat | `SimpleConversationTest.java` | -| **02 - Prompt-Engineering** | 12 | GPT-5.2-Muster, Eifer-Level, strukturierte Ausgabe | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Dokumentenintegration, Einbettungen, Ähnlichkeitssuche | `DocumentServiceTest.java` | -| **04 - Werkzeuge** | 12 | Funktionsaufruf und Werkzeugverkettung | `SimpleToolsTest.java` | +|--------|-------|-------|------------------| +| **01 - Einführung** | 8 | Gesprächsspeicher und zustandsorientierter Chat | `SimpleConversationTest.java` | +| **02 - Prompt Engineering** | 12 | GPT-5.2-Muster, Bereitschaftsgrade, strukturierte Ausgabe | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Dokumentenaufnahme, Einbettungen, Ähnlichkeitssuche | `DocumentServiceTest.java` | +| **04 - Tools** | 12 | Funktionsaufrufe und Werkzeugverkettung | `SimpleToolsTest.java` | | **05 - MCP** | 8 | Model Context Protocol mit Stdio-Transport | `SimpleMcpTest.java` | ## Tests ausführen -**Führen Sie alle Tests aus dem Root-Verzeichnis aus:** +**Alle Tests im Root-Verzeichnis ausführen:** **Bash:** ```bash @@ -63,23 +62,23 @@ mvn test mvn --% test ``` -**Führen Sie Tests für ein bestimmtes Modul aus:** +**Tests für ein bestimmtes Modul ausführen:** **Bash:** ```bash cd 01-introduction && mvn test -# Oder vom Wurzelverzeichnis aus +# Oder vom Stammverzeichnis mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Oder vom Stammverzeichnis aus +# Oder vom Stamm mvn --% test -pl 01-introduction ``` -**Führen Sie eine einzelne Testklasse aus:** +**Eine einzelne Testklasse ausführen:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Führen Sie eine bestimmte Testmethode aus:** +**Eine spezifische Testmethode ausführen:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#Gesprächsverlauf beibehalten +mvn test -Dtest=SimpleConversationTest#Soll die Gesprächshistorie beibehalten werden ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#Unterhaltungshistorie beibehalten +mvn --% test -Dtest=SimpleConversationTest#sollte die Konversationshistorie beibehalten ``` ## Tests in VS Code ausführen Wenn Sie Visual Studio Code verwenden, bietet der Test-Explorer eine grafische Oberfläche zum Ausführen und Debuggen von Tests. -VS Code Test-Explorer +VS Code Test Explorer -*VS Code Test-Explorer zeigt den Testbaum mit allen Java-Testklassen und einzelnen Testmethoden* +*VS Code Test Explorer zeigt den Testbaum mit allen Java-Testklassen und einzelnen Testmethoden* -**So führen Sie Tests in VS Code aus:** +**Um Tests in VS Code auszuführen:** -1. Öffnen Sie den Test-Explorer, indem Sie auf das Reagenzglas-Symbol in der Aktivitätsleiste klicken. -2. Erweitern Sie den Testbaum, um alle Module und Testklassen zu sehen. -3. Klicken Sie auf die Wiedergabetaste neben einem Test, um ihn einzeln auszuführen. -4. Klicken Sie auf „Alle Tests ausführen“, um die gesamte Suite zu starten. -5. Klicken Sie mit der rechten Maustaste auf einen Test und wählen Sie „Test debuggen“, um Haltepunkte zu setzen und den Code schrittweise durchzugehen. +1. Öffnen Sie den Test-Explorer, indem Sie auf das Reagenzglas-Symbol in der Aktivitätsleiste klicken +2. Erweitern Sie den Testbaum, um alle Module und Testklassen zu sehen +3. Klicken Sie neben einem Test auf die Wiedergabetaste, um ihn einzeln auszuführen +4. Klicken Sie auf "Alle Tests ausführen", um die gesamte Suite zu starten +5. Rechtsklicken Sie auf einen Test und wählen Sie "Test debuggen", um Breakpoints zu setzen und den Code schrittweise zu durchlaufen -Der Test-Explorer zeigt grüne Häkchen für bestandene Tests und gibt bei Fehlern detaillierte Fehlermeldungen aus. +Der Test-Explorer zeigt grüne Häkchen bei bestandenen Tests und liefert detaillierte Fehlermeldungen, wenn Tests fehlschlagen. ## Testmuster -### Muster 1: Testen von Promptvorlagen +### Muster 1: Testen von Prompt-Vorlagen -Das einfachste Muster testet Promptvorlagen ohne Aufruf eines KI-Modells. Sie überprüfen, ob die Variablensubstitution korrekt funktioniert und Prompts wie erwartet formatiert werden. +Das einfachste Muster testet Prompt-Vorlagen, ohne ein KI-Modell aufzurufen. Sie überprüfen, dass die Variablenersetzung korrekt funktioniert und Prompts wie erwartet formatiert sind. -Promptvorlagen-Test +Prompt Template Testing -*Testing von Promptvorlagen, das den Fluss der Variablensubstitution zeigt: Vorlage mit Platzhaltern → angewendete Werte → überprüfte formatierte Ausgabe* +*Testen von Prompt-Vorlagen, das den Ablauf der Variablenersetzung zeigt: Vorlage mit Platzhaltern → Werte angewendet → formatierte Ausgabe geprüft* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Dieser Test befindet sich in `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Ausführen:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatierung -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatierung -``` +Dieses Muster verifiziert, dass die Variablenersetzung korrekt funktioniert und Prompts wie erwartet formatiert sind — kein API-Schlüssel oder Modellaufruf erforderlich. ### Muster 2: Mocking von Sprachmodellen -Beim Testen der Gesprächslogik verwenden Sie Mockito, um gefälschte Modelle zu erstellen, die vorab festgelegte Antworten liefern. Das macht Tests schnell, kostenfrei und deterministisch. +Beim Testen der Gesprächslogik verwenden Sie Mockito, um gefälschte Modelle zu erstellen, die vorgegebene Antworten zurückgeben. Das macht Tests schnell, kostenlos und deterministisch. -Vergleich Mock vs. echte API +Mock vs Real API Comparison -*Vergleich, warum Mocks beim Testen bevorzugt werden: sie sind schnell, kostenlos, deterministisch und benötigen keine API-Schlüssel* +*Vergleich, der zeigt, warum Mocks fürs Testen bevorzugt werden: Sie sind schnell, kostenlos, deterministisch und benötigen keine API-Schlüssel* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Dieses Muster erscheint in `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Der Mock sorgt für konsistentes Verhalten, sodass Sie überprüfen können, ob das Speichermanagement korrekt funktioniert. +Dieses Muster erscheint in `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Das Mock sorgt für konsistentes Verhalten, damit Sie prüfen können, ob das Speicher-Management korrekt funktioniert. ### Muster 3: Testen der Gesprächs-Isolation -Der Gesprächsspeicher muss mehrere Benutzer getrennt halten. Dieser Test prüft, dass sich Gespräche nicht vermischen. +Das Gesprächsspeicher muss mehrere Nutzer trennen. Dieser Test prüft, dass Gespräche keine Kontexte vermischen. -Gesprächs-Isolation +Conversation Isolation -*Testen der Gesprächs-Isolation, das separate Speicherbereiche für verschiedene Benutzer zeigt, um Kontextverwechslungen zu vermeiden* +*Testen der Gesprächs-Isolation zeigt separate Speicher für verschiedene Nutzer, um Kontextvermischung zu verhindern* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Jedes Gespräch führt seine eigene unabhängige Historie. In Produktionssystemen ist diese Isolation für Multi-User-Anwendungen entscheidend. +Jedes Gespräch führt seinen eigenen unabhängigen Verlauf. In produktiven Systemen ist diese Isolation entscheidend für Mehrbenutzer-Anwendungen. -### Muster 4: Werkzeuge unabhängig testen +### Muster 4: Unabhängiges Testen von Tools -Werkzeuge sind Funktionen, die die KI aufrufen kann. Testen Sie sie direkt, um sicherzustellen, dass sie korrekt funktionieren, unabhängig von KI-Entscheidungen. +Tools sind Funktionen, die die KI aufrufen kann. Testen Sie sie direkt, um sicherzustellen, dass sie unabhängig von KI-Entscheidungen korrekt funktionieren. -Werkzeug-Test +Tools Testing -*Unabhängiges Testen von Werkzeugen, das die Ausführung eines Mock-Werkzeugs ohne KI-Aufrufe zeigt, um die Geschäftslogik zu überprüfen* +*Unabhängiges Testen von Tools zeigt Mock-Tool-Ausführung ohne KI-Aufrufe zur Überprüfung der Geschäftslogik* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Diese Tests aus `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validieren die Werkzeuglogik ohne KI-Beteiligung. Das Verkettungsbeispiel zeigt, wie die Ausgabe eines Werkzeugs in die Eingabe eines anderen fließt. +Diese Tests aus `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validieren die Logik von Tools ohne KI-Beteiligung. Das Verkettungsbeispiel zeigt, wie die Ausgabe eines Tools in den Eingabewert eines anderen fließt. -### Muster 5: In-Memory RAG-Test +### Muster 5: In-Memory RAG Testing -RAG-Systeme benötigen traditionell Vektordatenbanken und Einbettungsdienste. Das In-Memory-Muster lässt Sie die gesamte Pipeline ohne externe Abhängigkeiten testen. +RAG-Systeme erfordern traditionell Vektordatenbanken und Einbettungsdienste. Das In-Memory-Muster erlaubt das Testen der gesamten Pipeline ohne externe Abhängigkeiten. -In-Memory RAG-Test +In-Memory RAG Testing -*In-Memory RAG-Testablauf zeigt Dokumentenparsing, Einbettungsspeicherung und Ähnlichkeitssuche ohne Datenbankbedarf* +*In-Memory-RAG-Test-Workflow zeigt Dokumentenanalyse, Einbettungsspeicherung und Ähnlichkeitssuche ohne Datenbankbedarf* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -Dieser Test aus `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` erstellt ein Dokument im Speicher und überprüft Chunking und Metadatenbehandlung. +Dieser Test aus `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` erstellt ein Dokument im Speicher und prüft Chunking und Metadatenverarbeitung. ### Muster 6: MCP-Integrationstest -Das MCP-Modul testet die Integration des Model Context Protocol mit stdio-Transport. Diese Tests prüfen, dass Ihre Anwendung MCP-Server als Unterprozesse starten und mit ihnen kommunizieren kann. +Das MCP-Modul testet die Integration des Model Context Protocols mit stdio-Transport. Diese Tests verifizieren, dass Ihre Anwendung MCP-Server als Unterprozesse starten und kommunizieren kann. Die Tests in `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validieren das Verhalten des MCP-Clients. -**Ausführen:** +**Führen Sie sie aus:** **Bash:** ```bash @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## Testphilosophie -Testen Sie Ihren Code, nicht die KI. Ihre Tests sollten den von Ihnen geschriebenen Code validieren, indem sie prüfen, wie Prompts konstruiert, wie der Speicher verwaltet und wie Werkzeuge ausgeführt werden. KI-Antworten variieren und sollten nicht Teil der Testannahmen sein. Fragen Sie sich, ob Ihre Promptvorlage Variablen korrekt ersetzt, nicht ob die KI die richtige Antwort gibt. +Testen Sie Ihren Code, nicht die KI. Ihre Tests sollten den von Ihnen geschriebenen Code validieren, indem sie prüfen, wie Prompts erstellt, wie Speicher verwaltet und wie Tools ausgeführt werden. KI-Antworten variieren und sollten nicht Teil von Testbehauptungen sein. Fragen Sie sich, ob Ihre Prompt-Vorlage Variablen korrekt ersetzt, nicht ob die KI die richtige Antwort gibt. -Nutzen Sie Mocks für Sprachmodelle. Diese sind externe Abhängigkeiten, die langsam, teuer und nicht deterministisch sind. Mocking macht Tests schnell mit Millisekunden statt Sekunden, kostenfrei ohne API-Kosten und deterministisch mit immer gleichem Ergebnis. +Verwenden Sie Mocks für Sprachmodelle. Diese sind externe Abhängigkeiten, die langsam, teuer und nicht deterministisch sind. Mocking macht Tests schnell mit Millisekunden statt Sekunden, kostenlos ohne API-Kosten und deterministisch mit dem gleichen Ergebnis jedes Mal. -Halten Sie Tests unabhängig. Jeder Test sollte seine eigenen Daten einrichten, sich nicht auf andere Tests verlassen und nach sich selbst aufräumen. Tests sollten unabhängig von der Ausführungsreihenfolge bestehen. +Halten Sie Tests unabhängig. Jeder Test sollte seine eigenen Daten einrichten, sich nicht auf andere Tests verlassen und nach sich aufräumen. Tests sollten unabhängig von der Ausführungsreihenfolge bestehen. -Testen Sie auch Grenzfälle über den Happy Path hinaus. Testen Sie leere Eingaben, sehr große Eingaben, Sonderzeichen, ungültige Parameter und Randbedingungen. Diese offenbaren oft Fehler, die im normalen Gebrauch nicht auftreten. +Testen Sie auch Grenzfälle außerhalb des normalen Ablaufs. Probieren Sie leere Eingaben, sehr große Eingaben, Sonderzeichen, ungültige Parameter und Randbedingungen. Diese decken oft Fehler auf, die bei normaler Verwendung nicht sichtbar sind. -Verwenden Sie beschreibende Namen. Vergleichen Sie `shouldMaintainConversationHistoryAcrossMultipleMessages()` mit `test1()`. Der erste Name sagt genau, was getestet wird, und erleichtert das Debuggen bei Fehlern erheblich. +Verwenden Sie aussagekräftige Namen. Vergleichen Sie `shouldMaintainConversationHistoryAcrossMultipleMessages()` mit `test1()`. Der erste Name sagt genau, was getestet wird, was die Fehlersuche erheblich erleichtert. ## Nächste Schritte -Jetzt, wo Sie die Testmuster kennen, vertiefen Sie sich in jedes Modul: +Da Sie nun die Testmuster verstehen, tauchen Sie tiefer in jedes Modul ein: -- **[00 - Schnellstart](../00-quick-start/README.md)** - Beginnen Sie mit den Grundlagen der Promptvorlagen -- **[01 - Einführung](../01-introduction/README.md)** - Lernen Sie das Management des Gesprächsspeichers -- **[02 - Prompt-Engineering](../02-prompt-engineering/README.md)** - Meistern Sie GPT-5.2-Prompting-Muster -- **[03 - RAG](../03-rag/README.md)** - Erstellen Sie retrieval-gestützte Generierungssysteme -- **[04 - Werkzeuge](../04-tools/README.md)** - Implementieren Sie Funktionsaufrufe und Werkzeugketten +- **[01 - Einführung](../01-introduction/README.md)** - Lernen Sie das Gesprächsspeicher-Management kennen +- **[02 - Prompt Engineering](../02/prompt-engineering/README.md)** - Meistern Sie GPT-5.2-Prompting-Muster +- **[03 - RAG](../03-rag/README.md)** - Bauen Sie Retrieval-Augmented Generation-Systeme +- **[04 - Tools](../04-tools/README.md)** - Implementieren Sie Funktionsaufrufe und Werkzeugketten - **[05 - MCP](../05-mcp/README.md)** - Integrieren Sie das Model Context Protocol -Das README jedes Moduls bietet detaillierte Erklärungen zu den hier getesteten Konzepten. +Das README jedes Moduls bietet ausführliche Erklärungen zu den hier getesteten Konzepten. --- @@ -358,6 +344,6 @@ Das README jedes Moduls bietet detaillierte Erklärungen zu den hier getesteten --- -**Haftungsausschluss**: -Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir um Genauigkeit bemüht sind, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner ursprünglichen Sprache gilt als maßgebliche Quelle. Für wichtige Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Nutzung dieser Übersetzung entstehen. +**Haftungsausschluss**: +Dieses Dokument wurde mit dem KI-Übersetzungsdienst [Co-op Translator](https://github.com/Azure/co-op-translator) übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Bei kritischen Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen. \ No newline at end of file diff --git a/translations/el/.co-op-translator.json b/translations/el/.co-op-translator.json index 622484c26..e616bfd8a 100644 --- a/translations/el/.co-op-translator.json +++ b/translations/el/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "el" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T00:35:13+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T09:49:18+00:00", "source_file": "01-introduction/README.md", "language_code": "el" }, @@ -18,20 +18,20 @@ "language_code": "el" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T00:38:40+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T09:31:06+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "el" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T00:40:44+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T09:46:52+00:00", "source_file": "03-rag/README.md", "language_code": "el" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:26:27+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T09:41:34+00:00", "source_file": "04-tools/README.md", "language_code": "el" }, @@ -54,8 +54,8 @@ "language_code": "el" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:07:38+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T09:25:23+00:00", "source_file": "README.md", "language_code": "el" }, @@ -72,14 +72,14 @@ "language_code": "el" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T00:45:24+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T09:33:50+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "el" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T00:46:33+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T09:36:22+00:00", "source_file": "docs/TESTING.md", "language_code": "el" } diff --git a/translations/el/00-quick-start/README.md b/translations/el/00-quick-start/README.md deleted file mode 100644 index 1b2cbb65d..000000000 --- a/translations/el/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Γρήγορη Έναρξη - -## Table of Contents - -- [Εισαγωγή](../../../00-quick-start) -- [Τι είναι το LangChain4j;](../../../00-quick-start) -- [Εξαρτήσεις LangChain4j](../../../00-quick-start) -- [Προαπαιτούμενα](../../../00-quick-start) -- [Ρύθμιση](../../../00-quick-start) - - [1. Αποκτήστε το GitHub Token σας](../../../00-quick-start) - - [2. Ορίστε το Token σας](../../../00-quick-start) -- [Εκτέλεση Παραδειγμάτων](../../../00-quick-start) - - [1. Βασική Συνομιλία](../../../00-quick-start) - - [2. Πρότυπα Υπόδειξης](../../../00-quick-start) - - [3. Κλήση Συναρτήσεων](../../../00-quick-start) - - [4. Ερωτήσεις & Απαντήσεις Εγγράφων (Easy RAG)](../../../00-quick-start) - - [5. Υπεύθυνη Τεχνητή Νοημοσύνη](../../../00-quick-start) -- [Τι Δείχνει Κάθε Παράδειγμα](../../../00-quick-start) -- [Επόμενα Βήματα](../../../00-quick-start) -- [Αντιμετώπιση Προβλημάτων](../../../00-quick-start) - -## Introduction - -Αυτή η γρήγορη εκκίνηση έχει σκοπό να σας βάλει σε λειτουργία με το LangChain4j το ταχύτερο δυνατό. Καλύπτει τα απολύτως βασικά για την κατασκευή εφαρμογών AI με LangChain4j και GitHub Models. Στα επόμενα modules θα μεταβείτε σε Azure OpenAI και GPT-5.2 και θα εμβαθύνετε σε κάθε έννοια. - -## What is LangChain4j? - -Το LangChain4j είναι μια βιβλιοθήκη Java που απλοποιεί την κατασκευή εφαρμογών με τεχνητή νοημοσύνη. Αντί να ασχολείστε με HTTP clients και ανάλυση JSON, δουλεύετε με καθαρές Java APIs. - -Η "αλυσίδα" στο LangChain αναφέρεται στην αλυσίδωση πολλαπλών συστατικών - μπορεί να αλυσιδωθεί ένα prompt σε ένα μοντέλο σε ένα parser, ή να αλυσιδωθούν πολλές κλήσεις AI όπου η έξοδος της μίας τροφοδοτεί την είσοδο της επόμενης. Αυτή η γρήγορη εκκίνηση εστιάζει στα βασικά πριν εξερευνήσει πιο σύνθετες αλυσίδες. - -LangChain4j Chaining Concept - -*Αλυσιδωτά συστατικά στο LangChain4j - οικοδομικά στοιχεία που συνδέονται για να δημιουργήσουν ισχυρές ροές εργασίας AI* - -Θα χρησιμοποιήσουμε τρία βασικά συστατικά: - -**ChatModel** - Η διεπαφή για αλληλεπιδράσεις με το μοντέλο AI. Καλείτε `model.chat("prompt")` και λαμβάνετε μια απάντηση ως string. Χρησιμοποιούμε το `OpenAiOfficialChatModel` που λειτουργεί με endpoints συμβατά με OpenAI όπως τα GitHub Models. - -**AiServices** - Δημιουργεί type-safe διεπαφές υπηρεσιών AI. Ορίζετε μεθόδους, τις σχολιάζετε με `@Tool`, και το LangChain4j αναλαμβάνει τον συντονισμό. Το AI καλεί αυτόματα τις Java μεθόδους σας όταν χρειάζεται. - -**MessageWindowChatMemory** - Διατηρεί το ιστορικό συνομιλίας. Χωρίς αυτό, κάθε αίτημα είναι ανεξάρτητο. Με αυτό, το AI θυμάται προηγούμενα μηνύματα και διατηρεί το πλαίσιο σε πολλούς γύρους. - -LangChain4j Architecture - -*Αρχιτεκτονική LangChain4j - βασικά συστατικά που συνεργάζονται για να τροφοδοτήσουν τις εφαρμογές AI σας* - -## LangChain4j Dependencies - -Αυτή η γρήγορη εκκίνηση χρησιμοποιεί τρεις εξαρτήσεις Maven στο [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Το module `langchain4j-open-ai-official` παρέχει την κλάση `OpenAiOfficialChatModel` που συνδέεται με APIs συμβατά με το OpenAI. Τα GitHub Models χρησιμοποιούν την ίδια μορφή API, οπότε δεν χρειάζεται ειδικός προσαρμογέας - απλά δείξτε τη βάση URL στο `https://models.github.ai/inference`. - -Το module `langchain4j-easy-rag` παρέχει αυτόματη διαίρεση εγγράφων, ενσωμάτωση και ανάκτηση ώστε να μπορείτε να χτίσετε εφαρμογές RAG χωρίς χειροκίνητη ρύθμιση κάθε βήματος. - -## Προαπαιτούμενα - -**Χρησιμοποιείτε το Dev Container;** Java και Maven είναι ήδη εγκατεστημένα. Χρειάζεστε μόνο ένα Personal Access Token του GitHub. - -**Τοπική Ανάπτυξη:** -- Java 21+, Maven 3.9+ -- Personal Access Token από GitHub (οδηγίες παρακάτω) - -> **Σημείωση:** Αυτό το module χρησιμοποιεί το `gpt-4.1-nano` από GitHub Models. Μην τροποποιείτε το όνομα μοντέλου στον κώδικα - έχει ρυθμιστεί να λειτουργεί με τα διαθέσιμα μοντέλα του GitHub. - -## Ρύθμιση - -### 1. Αποκτήστε το GitHub Token σας - -1. Μεταβείτε στο [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Πατήστε "Generate new token" -3. Ορίστε ένα περιγραφικό όνομα (π.χ. "LangChain4j Demo") -4. Ορίστε διάρκεια (συνιστώνται 7 ημέρες) -5. Στο "Account permissions", βρείτε το "Models" και ορίστε σε "Read-only" -6. Πατήστε "Generate token" -7. Αντιγράψτε και αποθηκεύστε το token σας - δεν θα το δείτε ξανά - -### 2. Ορίστε το Token σας - -**Επιλογή 1: Χρήση VS Code (Συνιστάται)** - -Αν χρησιμοποιείτε το VS Code, προσθέστε το token στο αρχείο `.env` στη ρίζα του project: - -Αν το αρχείο `.env` δεν υπάρχει, αντιγράψτε το `.env.example` σε `.env` ή δημιουργήστε νέο `.env` στη ρίζα του project. - -**Παράδειγμα αρχείου `.env`:** -```bash -# Στο /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Στη συνέχεια μπορείτε απλά να κάνετε δεξί κλικ σε οποιοδήποτε demo αρχείο (π.χ. `BasicChatDemo.java`) στον Explorer και να επιλέξετε **"Run Java"** ή να χρησιμοποιήσετε τις ρυθμίσεις εκκίνησης από το πάνελ Run and Debug. - -**Επιλογή 2: Χρήση Τερματικού** - -Ορίστε το token ως μεταβλητή περιβάλλοντος: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Εκτέλεση Παραδειγμάτων - -**Χρήση VS Code:** Κάντε δεξί κλικ σε οποιοδήποτε demo αρχείο στον Explorer και επιλέξτε **"Run Java"**, ή χρησιμοποιήστε τις ρυθμίσεις εκκίνησης από το πάνελ Run and Debug (βεβαιωθείτε πρώτα ότι έχετε προσθέσει το token στο `.env`). - -**Χρήση Maven:** Εναλλακτικά, μπορείτε να τρέξετε από τη γραμμή εντολών: - -### 1. Βασική Συνομιλία - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Πρότυπα Υπόδειξης - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Δείχνει zero-shot, few-shot, chain-of-thought και role-based prompting. - -### 3. Κλήση Συναρτήσεων - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -Το AI καλεί αυτόματα τις Java μεθόδους σας όταν χρειάζεται. - -### 4. Ερωτήσεις & Απαντήσεις Εγγράφων (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Κάντε ερωτήσεις σχετικά με τα έγγραφά σας χρησιμοποιώντας Easy RAG με αυτόματη ενσωμάτωση και ανάκτηση. - -### 5. Υπεύθυνη Τεχνητή Νοημοσύνη - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Δείτε πώς τα φίλτρα ασφάλειας AI αποκλείουν επιβλαβές περιεχόμενο. - -## Τι Δείχνει Κάθε Παράδειγμα - -**Βασική Συνομιλία** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Ξεκινήστε εδώ για να δείτε το LangChain4j στην πιο απλή μορφή του. Θα δημιουργήσετε ένα `OpenAiOfficialChatModel`, θα στείλετε ένα prompt με `.chat()` και θα λάβετε απάντηση. Αυτό δείχνει τα θεμέλια: πώς να αρχικοποιείτε μοντέλα με προσαρμοσμένα endpoints και κλειδιά API. Μόλις κατανοήσετε αυτό το μοτίβο, όλα τα υπόλοιπα χτίζονται πάνω του. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Δοκιμάστε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) και ρωτήστε: -> - "Πώς θα άλλαζα από GitHub Models σε Azure OpenAI σε αυτόν τον κώδικα;" -> - "Ποιοι άλλοι παράμετροι μπορώ να ρυθμίσω στο OpenAiOfficialChatModel.builder();" -> - "Πώς προσθέτω streaming απαντήσεις αντί να περιμένω την πλήρη απάντηση;" - -**Μηχανική Υποδείξεων (Prompt Engineering)** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Τώρα που ξέρετε πώς να μιλάτε σε ένα μοντέλο, ας εξερευνήσουμε τι του λέτε. Αυτό το demo χρησιμοποιεί την ίδια ρύθμιση μοντέλου αλλά δείχνει πέντε διαφορετικά πρότυπα υποδείξεων. Δοκιμάστε zero-shot prompts για άμεσες οδηγίες, few-shot prompts που μαθαίνουν από παραδείγματα, chain-of-thought prompts που αποκαλύπτουν βήματα συλλογισμού, και role-based prompts που θέτουν το πλαίσιο. Θα δείτε πώς το ίδιο μοντέλο δίνει ριζικά διαφορετικά αποτελέσματα ανάλογα με το πώς πλαισιώνετε το αίτημά σας. - -Το demo επίσης δείχνει prompt templates, μια ισχυρή μέθοδο για δημιουργία επαναχρησιμοποιούμενων prompts με μεταβλητές. -Το παρακάτω παράδειγμα δείχνει ένα prompt που χρησιμοποιεί το LangChain4j `PromptTemplate` για να γεμίσει μεταβλητές. Το AI απαντά με βάση τον προορισμό και τη δραστηριότητα που παρέχονται. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Δοκιμάστε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) και ρωτήστε: -> - "Ποια είναι η διαφορά μεταξύ zero-shot και few-shot prompting, και πότε πρέπει να χρησιμοποιώ το καθένα;" -> - "Πώς επηρεάζει η παράμετρος θερμοκρασίας τις απαντήσεις του μοντέλου;" -> - "Ποιες τεχνικές υπάρχουν για να αποτρέψω επιθέσεις prompt injection σε παραγωγή;" -> - "Πώς δημιουργώ επαναχρησιμοποιούμενα PromptTemplate αντικείμενα για κοινά πρότυπα;" - -**Ένταξη Εργαλείων (Tool Integration)** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Εδώ γίνεται δυναμικό το LangChain4j. Θα χρησιμοποιήσετε το `AiServices` για να δημιουργήσετε έναν βοηθό AI που μπορεί να καλεί τις Java μεθόδους σας. Απλά σχολιάστε τις μεθόδους σας με `@Tool("περιγραφή")` και το LangChain4j κάνει τα υπόλοιπα - το AI αποφασίζει αυτόματα πότε να χρησιμοποιήσει κάθε εργαλείο ανάλογα με το τι ρωτά ο χρήστης. Αυτό δείχνει την κλήση συναρτήσεων, μια βασική τεχνική για την κατασκευή AI που μπορεί να εκτελεί ενέργειες και όχι μόνο να απαντά σε ερωτήσεις. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Δοκιμάστε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) και ρωτήστε: -> - "Πώς λειτουργεί το annotation @Tool και τι κάνει το LangChain4j με αυτό πίσω από τις σκηνές;" -> - "Μπορεί το AI να καλέσει πολλαπλά εργαλεία στη σειρά για να λύσει πολύπλοκα προβλήματα;" -> - "Τι συμβαίνει αν ένα εργαλείο ρίξει εξαίρεση - πώς πρέπει να διαχειριστώ τα σφάλματα;" -> - "Πώς θα ενσωμάτωνα ένα πραγματικό API αντί για αυτό το παράδειγμα υπολογιστή;" - -**Ερωτήσεις & Απαντήσεις Εγγράφων (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Εδώ θα δείτε το RAG (retrieval-augmented generation) χρησιμοποιώντας την προσέγγιση "Easy RAG" του LangChain4j. Τα έγγραφα φορτώνονται, χωρίζονται αυτόματα και ενσωματώνονται σε μια ενήμερη μνήμη, μετά ένας ανακτών περιεχομένου παρέχει σχετικά κομμάτια στο AI κατά το χρόνο ερώτησης. Το AI απαντά βάσει των εγγράφων σας, όχι της γενικής του γνώσης. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Δοκιμάστε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) και ρωτήστε: -> - "Πώς το RAG αποτρέπει τις ψευδαισθήσεις AI συγκριτικά με τη χρήση δεδομένων εκπαίδευσης του μοντέλου;" -> - "Ποια είναι η διαφορά μεταξύ αυτής της εύκολης προσέγγισης και μιας προσαρμοσμένης RAG pipeline;" -> - "Πώς θα κλιμακώσω αυτό για να χειριστώ πολλαπλά έγγραφα ή μεγαλύτερες βάσεις γνώσης;" - -**Υπεύθυνη Τεχνητή Νοημοσύνη** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Χτίστε ασφάλεια AI με πολλαπλά επίπεδα προστασίας. Αυτό το demo δείχνει δύο στρώματα προστασίας που συνεργάζονται: - -**Μέρος 1: LangChain4j Input Guardrails** - Αποκλείστε επικίνδυνα prompts πριν φτάσουν στο LLM. Δημιουργήστε προσαρμοσμένα guardrails που ελέγχουν για απαγορευμένες λέξεις-κλειδιά ή πρότυπα. Εκτελούνται στον κώδικά σας, άρα είναι γρήγορα και δωρεάν. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Μέρος 2: Provider Safety Filters** - Τα GitHub Models έχουν ενσωματωμένα φίλτρα που πιάνουν ό,τι τα guardrails σας ίσως χάσουν. Θα δείτε σκληρούς αποκλεισμούς (HTTP 400 σφάλματα) για σοβαρές παραβάσεις και μαλακές απορρίψεις όπου το AI αρνείται ευγενικά. - -> **🤖 Δοκιμάστε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) και ρωτήστε: -> - "Τι είναι το InputGuardrail και πώς φτιάχνω δικό μου;" -> - "Ποια είναι η διαφορά μεταξύ σκληρού αποκλεισμού και ήπιας απόρριψης;" -> - "Γιατί να χρησιμοποιώ και guardrails και φίλτρα παρόχου μαζί;" - -## Επόμενα Βήματα - -**Επόμενο Module:** [01-introduction - Ξεκινώντας με το LangChain4j](../01-introduction/README.md) - ---- - -**Πλοήγηση:** [← Πίσω στην Κεντρική](../README.md) | [Επόμενο: Module 01 - Εισαγωγή →](../01-introduction/README.md) - ---- - -## Αντιμετώπιση Προβλημάτων - -### Πρώτη Κατασκευή Maven - -**Πρόβλημα:** Αρχικό `mvn clean compile` ή `mvn package` διαρκεί πολύ (10-15 λεπτά) - -**Αιτία:** Το Maven πρέπει να κατεβάσει όλες τις εξαρτήσεις του project (Spring Boot, βιβλιοθήκες LangChain4j, Azure SDKs, κ.ά.) στην πρώτη κατασκευή. - -**Λύση:** Αυτό είναι φυσιολογικό. Οι επόμενες κατασκευές θα είναι πολύ πιο γρήγορες καθώς οι εξαρτήσεις έχουν cache τοπικά. Ο χρόνος λήψης εξαρτάται από την ταχύτητα του δικτύου σας. - -### Σύνταξη Εντολών Maven σε PowerShell - -**Πρόβλημα:** Οι εντολές Maven αποτυγχάνουν με σφάλμα `Unknown lifecycle phase ".mainClass=..."` -**Αιτία**: Το PowerShell ερμηνεύει το `=` ως τελεστή ανάθεσης μεταβλητής, διακόπτοντας τη σύνταξη ιδιοτήτων του Maven - -**Λύση**: Χρησιμοποιήστε τον τελεστή διακοπής ανάλυσης `--%` πριν από την εντολή Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Ο τελεστής `--%` λέει στο PowerShell να περάσει όλα τα επόμενα ορίσματα κυριολεκτικά στο Maven χωρίς ερμηνεία. - -### Εμφάνιση Emoji στα Windows PowerShell - -**Πρόβλημα**: Οι απαντήσεις AI εμφανίζουν άχρηστους χαρακτήρες (π.χ., `????` ή `â??`) αντί για emoji στο PowerShell - -**Αιτία**: Η προεπιλεγμένη κωδικοποίηση του PowerShell δεν υποστηρίζει τα emoji UTF-8 - -**Λύση**: Εκτελέστε αυτή την εντολή πριν από την εκτέλεση εφαρμογών Java: -```cmd -chcp 65001 -``` - -Αυτό αναγκάζει την κωδικοποίηση UTF-8 στο τερματικό. Εναλλακτικά, χρησιμοποιήστε το Windows Terminal που έχει καλύτερη υποστήριξη Unicode. - -### Αποσφαλμάτωση Κλήσεων API - -**Πρόβλημα**: Σφάλματα ταυτοποίησης, όρια ρυθμού ή μη αναμενόμενες απαντήσεις από το μοντέλο AI - -**Λύση**: Τα παραδείγματα περιλαμβάνουν `.logRequests(true)` και `.logResponses(true)` για να εμφανίζουν τις κλήσεις API στην κονσόλα. Αυτό βοηθά στην επίλυση σφαλμάτων ταυτοποίησης, ορίων ρυθμού ή μη αναμενόμενων απαντήσεων. Αφαιρέστε αυτές τις σημαίες στην παραγωγή για μείωση του θορύβου στα αρχεία καταγραφής. - ---- - - -**Αποποίηση ευθυνών**: -Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης AI [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που επιδιώκουμε ακρίβεια, παρακαλούμε να σημειώσετε ότι οι αυτοματοποιημένες μεταφράσεις μπορεί να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη γλώσσα του αποτελεί την έγκυρη πηγή. Για κρίσιμες πληροφορίες συνιστάται η επαγγελματική μετάφραση από ανθρώπινο μεταφραστή. Δεν φέρουμε καμία ευθύνη για τυχόν παρεξηγήσεις ή εσφαλμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. - \ No newline at end of file diff --git a/translations/el/01-introduction/README.md b/translations/el/01-introduction/README.md index c7daec14d..dbc310bd7 100644 --- a/translations/el/01-introduction/README.md +++ b/translations/el/01-introduction/README.md @@ -2,84 +2,84 @@ ## Περιεχόμενα -- [Οδηγός Βίντεο](../../../01-introduction) -- [Τι θα μάθετε](../../../01-introduction) -- [Προαπαιτούμενα](../../../01-introduction) -- [Κατανόηση του Κεντρικού Προβλήματος](../../../01-introduction) -- [Κατανόηση των Tokens](../../../01-introduction) -- [Πώς Λειτουργεί η Μνήμη](../../../01-introduction) -- [Πώς Χρησιμοποιεί Αυτό το LangChain4j](../../../01-introduction) -- [Ανάπτυξη Υποδομής Azure OpenAI](../../../01-introduction) -- [Εκτέλεση της Εφαρμογής Τοπικά](../../../01-introduction) -- [Χρήση της Εφαρμογής](../../../01-introduction) - - [Chat χωρίς Κατάσταση (Αριστερό Πάνελ)](../../../01-introduction) - - [Chat με Κατάσταση (Δεξί Πάνελ)](../../../01-introduction) -- [Επόμενα Βήματα](../../../01-introduction) - -## Οδηγός Βίντεο +- [Περιήγηση σε Βίντεο](#περιήγηση-σε-βίντεο) +- [Τι θα Μάθετε](#τι-θα-μάθετε) +- [Απαιτήσεις](#απαιτήσεις) +- [Κατανόηση του Βασικού Προβλήματος](#κατανόηση-του-βασικού-προβλήματος) +- [Κατανόηση των Tokens](#κατανόηση-των-tokens) +- [Πώς Λειτουργεί η Μνήμη](#πώς-λειτουργεί-η-μνήμη) +- [Πώς Χρησιμοποιείται το LangChain4j](#πώς-χρησιμοποιείται-το-langchain4j) +- [Ανάπτυξη Υποδομής Azure OpenAI](#ανάπτυξη-υποδομής-azure-openai) +- [Εκτέλεση της Εφαρμογής Τοπικά](#εκτέλεση-της-εφαρμογής-τοπικά) +- [Χρήση της Εφαρμογής](#χρήση-της-εφαρμογής) + - [Άνευ Κατάστασης Συνομιλία (Αριστερό Πάνελ)](#άνευ-κατάστασης-συνομιλία-αριστερό-πάνελ) + - [Κατάστασης Συνομιλία (Δεξί Πάνελ)](#κατάστασης-συνομιλία-δεξί-πάνελ) +- [Επόμενα Βήματα](#επόμενα-βήματα) + +## Περιήγηση σε Βίντεο Παρακολουθήστε αυτή τη ζωντανή παρουσίαση που εξηγεί πώς να ξεκινήσετε με αυτό το module: -Getting Started with LangChain4j - Live Session +Ξεκινώντας με το LangChain4j - Ζωντανή Συνεδρία -## Τι θα μάθετε +## Τι θα Μάθετε -Στο γρήγορο ξεκίνημα, χρησιμοποιήσατε τα GitHub Models για να στέλνετε προτροπές, να καλείτε εργαλεία, να δημιουργείτε ένα RAG pipeline και να δοκιμάζετε τους κανόνες ασφαλείας. Αυτά τα demos έδειξαν τι είναι δυνατό — τώρα μεταβαίνουμε στο Azure OpenAI και GPT-5.2 και αρχίζουμε να χτίζουμε εφαρμογές παραγωγικού τύπου. Αυτό το module εστιάζει σε συστήματα συνομιλίας AI που θυμούνται το πλαίσιο και διατηρούν κατάσταση — τις έννοιες που τα demos στο γρήγορο ξεκίνημα χρησιμοποιούσαν παρασκηνιακά αλλά δεν εξήγησαν. +Αυτή είναι η αφετηρία σας με το LangChain4j και το Azure OpenAI. Ξεκινάμε με τα βασικά και αρχίζουμε να κατασκευάζουμε εφαρμογές παραγωγικού επιπέδου. Αυτό το module εστιάζει στην συνομιλητική AI που θυμάται το πλαίσιο και διατηρεί κατάσταση — τις θεμελιώδεις έννοιες πάνω στις οποίες βασίζονται όλα τα μετέπειτα modules. -Θα χρησιμοποιήσουμε το GPT-5.2 της Azure OpenAI σε όλο τον οδηγό επειδή οι προηγμένες δυνατότητες λογικής του κάνουν πιο εμφανή τη συμπεριφορά των διαφορετικών προτύπων. Όταν προσθέσετε μνήμη, θα δείτε καθαρά τη διαφορά. Αυτό καθιστά πιο εύκολο να κατανοήσετε τι φέρνει το κάθε συστατικό στην εφαρμογή σας. +Θα χρησιμοποιήσουμε το GPT-5.2 του Azure OpenAI σε όλο τον οδηγό επειδή οι προηγμένες ικανότητες λογικής του καθιστούν τη συμπεριφορά διαφορετικών προτύπων πιο εμφανή. Όταν προσθέσετε μνήμη, θα δείτε καθαρά τη διαφορά. Αυτό καθιστά πιο εύκολη την κατανόηση τι φέρνει κάθε συνιστώσα στην εφαρμογή σας. -Θα δημιουργήσετε μία εφαρμογή που επιδεικνύει και τα δύο πρότυπα: +Θα δημιουργήσετε μία εφαρμογή που δείχνει και τα δύο πρότυπα: -**Chat χωρίς Κατάσταση** - Κάθε αίτημα είναι ανεξάρτητο. Το μοντέλο δεν θυμάται προηγούμενα μηνύματα. Αυτό είναι το πρότυπο που χρησιμοποιήσατε στο γρήγορο ξεκίνημα. +**Άνευ Κατάστασης Συνομιλία** - Κάθε αίτημα είναι ανεξάρτητο. Το μοντέλο δεν θυμάται προηγούμενα μηνύματα. Αυτό είναι το απλούστερο σημείο εκκίνησης. -**Chat με Κατάσταση** - Κάθε αίτημα περιλαμβάνει το ιστορικό συνομιλίας. Το μοντέλο διατηρεί το πλαίσιο σε πολλαπλούς γύρους συνομιλίας. Αυτό είναι που απαιτούν οι παραγωγικές εφαρμογές. +**Κατάστασης Συνομιλία** - Κάθε αίτημα περιλαμβάνει το ιστορικό συνομιλίας. Το μοντέλο διατηρεί το πλαίσιο σε πολλαπλές ανταλλαγές. Αυτό απαιτούν οι παραγωγικές εφαρμογές. -## Προαπαιτούμενα +## Απαιτήσεις - Συνδρομή Azure με πρόσβαση στο Azure OpenAI - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Σημείωση:** Το Java, Maven, Azure CLI και Azure Developer CLI (azd) είναι προεγκατεστημένα στο παρεχόμενο devcontainer. +> **Σημείωση:** Java, Maven, Azure CLI και Azure Developer CLI (azd) είναι προεγκατεστημένα στο παρεχόμενο devcontainer. -> **Σημείωση:** Αυτό το module χρησιμοποιεί το GPT-5.2 στο Azure OpenAI. Η ανάπτυξη διαμορφώνεται αυτόματα μέσω του `azd up` - μην τροποποιείτε το όνομα του μοντέλου στον κώδικα. +> **Σημείωση:** Αυτό το module χρησιμοποιεί το GPT-5.2 στο Azure OpenAI. Η ανάπτυξη ρυθμίζεται αυτόματα μέσω `azd up` - μην τροποποιήσετε το όνομα του μοντέλου στον κώδικα. -## Κατανόηση του Κεντρικού Προβλήματος +## Κατανόηση του Βασικού Προβλήματος -Τα γλωσσικά μοντέλα είναι χωρίς κατάσταση. Κάθε κλήση API είναι ανεξάρτητη. Αν στείλετε "Το όνομά μου είναι Ιωάννης" και μετά ρωτήσετε "Ποιο είναι το όνομά μου;", το μοντέλο δεν έχει ιδέα ότι μόλις συστηθήκατε. Αντιμετωπίζει κάθε αίτημα σαν να είναι η πρώτη συνομιλία που έχετε ποτέ. +Τα μοντέλα γλώσσας είναι άνευ κατάστασης. Κάθε κλήση API είναι ανεξάρτητη. Αν στείλετε "Το όνομά μου είναι Γιάννης" και μετά ρωτήσετε "Ποιο είναι το όνομά μου;", το μοντέλο δεν έχει ιδέα ότι μόλις συστήσατε τον εαυτό σας. Θεωρεί κάθε αίτημα σαν να είναι η πρώτη συνομιλία που είχατε ποτέ. -Αυτό είναι εντάξει για απλές ερωτήσεις-απαντήσεις αλλά άχρηστο για πραγματικές εφαρμογές. Τα bots υποστήριξης πελατών πρέπει να θυμούνται τι τους είπατε. Οι προσωπικοί βοηθοί χρειάζονται πλαίσιο. Κάθε συνομιλία με πολλούς γύρους απαιτεί μνήμη. +Αυτό είναι επαρκές για απλές ερωτήσεις-απαντήσεις αλλά άχρηστο για πραγματικές εφαρμογές. Τα bots υποστήριξης πελατών χρειάζεται να θυμούνται τι τους είπατε. Οι προσωπικοί βοηθοί χρειάζονται πλαίσιο. Κάθε συνομιλία πολλαπλών βημάτων απαιτεί μνήμη. -Το παρακάτω διάγραμμα αντιπαραβάλλει τις δύο προσεγγίσεις — αριστερά, μια κλήση χωρίς κατάσταση που ξεχνά το όνομά σας· δεξιά, μια κλήση με κατάσταση υποστηριζόμενη από το ChatMemory που το θυμάται. +Το παρακάτω διάγραμμα αντιπαραβάλλει τις δύο προσεγγίσεις — αριστερά, μια κλήση άνευ κατάστασης που ξεχνά το όνομά σας· δεξιά, μια κλήση με κατάσταση υποστηριζόμενη από ChatMemory που το θυμάται. -Stateless vs Stateful Conversations +Συνομιλίες Άνευ Κατάστασης vs Κατάστασης -*Η διαφορά μεταξύ συνομιλιών χωρίς κατάσταση (ανεξάρτητες κλήσεις) και με κατάσταση (με επίγνωση πλαισίου)* +*Η διαφορά μεταξύ άνευ κατάστασης (ανεξάρτητες κλήσεις) και κατάστασης (επικείμενη στο πλαίσιο) συνομιλίες* ## Κατανόηση των Tokens -Πριν βουτήξετε σε συνομιλίες, είναι σημαντικό να κατανοήσετε τα tokens - τις βασικές μονάδες κειμένου που επεξεργάζονται τα γλωσσικά μοντέλα: +Πριν βουτήξετε στις συνομιλίες, είναι σημαντικό να κατανοήσετε τα tokens - τις βασικές μονάδες κειμένου που επεξεργάζονται τα μοντέλα γλώσσας: -Token Explanation +Εξήγηση Token -*Παράδειγμα πώς το κείμενο χωρίζεται σε tokens - "I love AI!" γίνεται 4 ξεχωριστές μονάδες επεξεργασίας* +*Παράδειγμα πώς το κείμενο διασπάται σε tokens - "I love AI!" γίνεται 4 ξεχωριστές μονάδες επεξεργασίας* -Τα tokens είναι ο τρόπος με τον οποίο τα μοντέλα AI μετρούν και επεξεργάζονται το κείμενο. Λέξεις, σημεία στίξης και ακόμη και κενά μπορεί να είναι tokens. Το μοντέλο σας έχει όριο στο πόσα tokens μπορεί να επεξεργαστεί ταυτόχρονα (400.000 για το GPT-5.2, με έως 272.000 tokens εισόδου και 128.000 tokens εξόδου). Η κατανόηση των tokens βοηθάει στη διαχείριση του μήκους της συνομιλίας και των κόστους. +Τα tokens είναι το πώς τα μοντέλα AI μετρούν και επεξεργάζονται το κείμενο. Λέξεις, σημεία στίξης και ακόμα και κενά μπορεί να είναι tokens. Το μοντέλο σας έχει όριο πόσα tokens μπορεί να επεξεργαστεί ταυτόχρονα (400,000 για το GPT-5.2, με έως 272,000 εισοδικά tokens και 128,000 εξοδικά tokens). Η κατανόηση των tokens βοηθάει στη διαχείριση του μήκους της συνομιλίας και των κοστών. ## Πώς Λειτουργεί η Μνήμη -Η μνήμη συνομιλίας επιλύει το πρόβλημα χωρίς κατάσταση διατηρώντας το ιστορικό της συνομιλίας. Πριν στείλετε το αίτημά σας στο μοντέλο, το πλαίσιο προσθέτει τα σχετικά προηγούμενα μηνύματα. Όταν ρωτάτε "Ποιο είναι το όνομά μου;", το σύστημα στέλνει όλο το ιστορικό συνομιλίας, επιτρέποντας στο μοντέλο να δει ότι είπατε προηγουμένως "Το όνομά μου είναι Ιωάννης." +Η μνήμη συνομιλίας λύνει το πρόβλημα της άνευ κατάστασης φύσης διατηρώντας το ιστορικό της συνομιλίας. Πριν στείλετε το αίτημά σας στο μοντέλο, το πλαίσιο προθέτει σχετικά προηγούμενα μηνύματα. Όταν ρωτήσετε "Ποιο είναι το όνομά μου;", το σύστημα στέλνει στην πραγματικότητα ολόκληρο το ιστορικό συνομιλίας, επιτρέποντας στο μοντέλο να δει ότι είπατε προηγουμένως "Το όνομά μου είναι Γιάννης." -Το LangChain4j παρέχει υλοποιήσεις μνήμης που χειρίζονται αυτό αυτόματα. Επιλέγετε πόσα μηνύματα θέλετε να κρατάτε και το πλαίσιο διαχειρίζεται το παράθυρο πλαισίου. Το παρακάτω διάγραμμα δείχνει πώς το MessageWindowChatMemory διατηρεί ένα ολισθαίνων παράθυρο πρόσφατων μηνυμάτων. +Το LangChain4j παρέχει υλοποιήσεις μνήμης που διαχειρίζονται αυτό αυτόματα. Επιλέγετε πόσα μηνύματα θα διατηρήσετε και το πλαίσιο διαχειρίζεται το παράθυρο πλαισίου (context window). Το διάγραμμα παρακάτω δείχνει πώς το MessageWindowChatMemory διατηρεί ένα κυλιόμενο παράθυρο πρόσφατων μηνυμάτων. -Memory Window Concept +Έννοια Παραθύρου Μνήμης -*Το MessageWindowChatMemory διατηρεί ένα ολισθαίνων παράθυρο πρόσφατων μηνυμάτων, απομακρύνοντας αυτόματα τα παλιά* +*Το MessageWindowChatMemory διατηρεί ένα κυλιόμενο παράθυρο πρόσφατων μηνυμάτων, απορρίπτοντας αυτόματα τα παλιά* -## Πώς Χρησιμοποιεί Αυτό το LangChain4j +## Πώς Χρησιμοποιείται το LangChain4j -Αυτό το module επεκτείνει το γρήγορο ξεκίνημα ενσωματώνοντας το Spring Boot και προσθέτοντας μνήμη συνομιλίας. Δείτε πώς συνδέονται τα κομμάτια: +Αυτό το module ενσωματώνει το Spring Boot και προσθέτει μνήμη συνομιλίας. Δείτε πώς συνδέονται τα κομμάτια: **Εξαρτήσεις** - Προσθέστε δύο βιβλιοθήκες LangChain4j: @@ -94,7 +94,7 @@ ``` -**Chat Model** - Διαμορφώστε το Azure OpenAI ως Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Μοντέλο Συνομιλίας** - Διαμορφώστε το Azure OpenAI ως Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Ο builder διαβάζει τα διαπιστευτήρια από μεταβλητές περιβάλλοντος που ρυθμίζονται από το `azd up`. Η ρύθμιση `baseUrl` στο endpoint του Azure κάνει τον OpenAI client να λειτουργεί με το Azure OpenAI. +Ο builder διαβάζει πιστοποιητικά από μεταβλητές περιβάλλοντος που ορίζει το `azd up`. Η ρύθμιση `baseUrl` στο τέλος του Azure endpoint σας κάνει τον OpenAI client να λειτουργεί με το Azure OpenAI. **Μνήμη Συνομιλίας** - Παρακολουθήστε το ιστορικό συνομιλίας με MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,48 +124,48 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Δημιουργήστε τη μνήμη με `withMaxMessages(10)` για να κρατήσει τα τελευταία 10 μηνύματα. Προσθέστε μηνύματα χρήστη και AI με typed wrappers: `UserMessage.from(text)` και `AiMessage.from(text)`. Ανακτήστε το ιστορικό με `memory.messages()` και στείλτε το στο μοντέλο. Η υπηρεσία αποθηκεύει ξεχωριστές εμφανίσεις μνήμης ανά ID συνομιλίας, επιτρέποντας σε πολλούς χρήστες να συνομιλούν ταυτόχρονα. +Δημιουργήστε μνήμη με το `withMaxMessages(10)` για να διατηρήσετε τα τελευταία 10 μηνύματα. Προσθέστε μηνύματα χρήστη και AI με τυποποιημένους wrappers: `UserMessage.from(text)` και `AiMessage.from(text)`. Ανακτήστε το ιστορικό με `memory.messages()` και στείλτε το στο μοντέλο. Η υπηρεσία αποθηκεύει ξεχωριστές στιγμές μνήμης ανά αναγνωριστικό συνομιλίας, επιτρέποντας σε πολλούς χρήστες να συνομιλούν ταυτόχρονα. > **🤖 Δοκιμάστε με το [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) και ρωτήστε: -> - "Πώς αποφασίζει το MessageWindowChatMemory ποια μηνύματα θα απορρίψει όταν το παράθυρο είναι γεμάτο;" -> - "Μπορώ να υλοποιήσω αποθήκευση μνήμης με βάση δεδομένων αντί για μνήμη RAM;" -> - "Πώς θα πρόσθετα περίληψη για συμπίεση του παλιού ιστορικού συνομιλίας;" +> - "Πώς αποφασίζει το MessageWindowChatMemory ποια μηνύματα να απορρίψει όταν το παράθυρο είναι γεμάτο;" +> - "Μπορώ να υλοποιήσω προσαρμοσμένη αποθήκευση μνήμης χρησιμοποιώντας μια βάση δεδομένων αντί για in-memory;" +> - "Πώς θα πρόσθετα σύνοψη για συμπίεση παλαιάς ιστορίας συνομιλίας;" -Το endpoint του chat χωρίς κατάσταση παραλείπει τη μνήμη εντελώς - απλά `chatModel.chat(prompt)` όπως στο γρήγορο ξεκίνημα. Το endpoint με κατάσταση προσθέτει τα μηνύματα στη μνήμη, ανακτά το ιστορικό και συμπεριλαμβάνει αυτό το πλαίσιο με κάθε αίτημα. Ίδια διαμόρφωση μοντέλου, διαφορετικά πρότυπα. +Το endpoint άνευ κατάστασης παραλείπει τελείως τη μνήμη - απλά `chatModel.chat(prompt)` όπως στην γρήγορη εκκίνηση. Το endpoint κατάστασης προσθέτει μηνύματα στη μνήμη, ανακτά το ιστορικό και συμπεριλαμβάνει το πλαίσιο σε κάθε αίτημα. Ίδια διαμόρφωση μοντέλου, διαφορετικά πρότυπα. ## Ανάπτυξη Υποδομής Azure OpenAI **Bash:** ```bash cd 01-introduction -azd up # Επιλέξτε συνδρομή και τοποθεσία (προτείνεται eastus2) +azd up # Επιλέξτε συνδρομή και τοποθεσία (συνιστάται eastus2) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Επιλέξτε συνδρομή και τοποθεσία (προτείνεται eastus2) +azd up # Επιλέξτε συνδρομή και τοποθεσία (προτεινόμενο το eastus2) ``` -> **Σημείωση:** Αν αντιμετωπίσετε σφάλμα χρονικού ορίου (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), απλά εκτελέστε ξανά `azd up`. Οι πόροι Azure μπορεί να εξακολουθούν να αναπτύσσονται στο παρασκήνιο και η επανάληψη επιτρέπει την ολοκλήρωση της ανάπτυξης μόλις οι πόροι φτάσουν σε τελικό στάδιο. +> **Σημείωση:** Αν αντιμετωπίσετε σφάλμα χρονικού ορίου (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), απλώς εκτελέστε ξανά `azd up`. Οι πόροι Azure μπορεί να αναπτύσσονται ακόμα στο παρασκήνιο, και η επανάληψη επιτρέπει την ολοκλήρωση ανάπτυξης όταν οι πόροι φτάσουν σε τελικό στάδιο. Αυτό θα: -1. Αναπτύξει πόρο Azure OpenAI με τα μοντέλα GPT-5.2 και text-embedding-3-small -2. Δημιουργήσει αυτόματα το αρχείο `.env` στη ρίζα του project με διαπιστευτήρια +1. Αναπτύξει πόρο Azure OpenAI με μοντέλα GPT-5.2 και text-embedding-3-small +2. Δημιουργήσει αυτόματα το αρχείο `.env` στη ρίζα του project με πιστοποιητικά 3. Ρυθμίσει όλες τις απαιτούμενες μεταβλητές περιβάλλοντος -**Έχετε προβλήματα ανάπτυξης;** Δείτε το [Infrastructure README](infra/README.md) για λεπτομερή αντιμετώπιση προβλημάτων, περιλαμβάνοντας συγκρούσεις ονομάτων υποτομέα, βήματα χειροκίνητης ανάπτυξης στο Azure Portal, και οδηγίες διαμόρφωσης μοντέλων. +**Έχετε προβλήματα στην ανάπτυξη;** Δείτε το [README Υποδομής](infra/README.md) για λεπτομερή αντιμετώπιση προβλημάτων, συμπεριλαμβανομένων συγκρούσεων ονομάτων υποτομέων, χειροκίνητων βημάτων ανάπτυξης στο Azure Portal και οδηγιών διαμόρφωσης μοντέλου. -**Επαληθεύστε ότι η ανάπτυξη πέτυχε:** +**Επιβεβαίωση επιτυχούς ανάπτυξης:** **Bash:** ```bash -cat ../.env # Πρέπει να εμφανίζει AZURE_OPENAI_ENDPOINT, API_KEY, κ.λπ. +cat ../.env # Θα πρέπει να εμφανίζει AZURE_OPENAI_ENDPOINT, API_KEY, κ.λπ. ``` **PowerShell:** ```powershell -Get-Content ..\.env # Πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, το API_KEY, κ.λπ. +Get-Content ..\.env # Θα πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, το API_KEY, κ.λπ. ``` > **Σημείωση:** Η εντολή `azd up` δημιουργεί αυτόματα το αρχείο `.env`. Αν χρειαστεί να το ενημερώσετε αργότερα, μπορείτε είτε να επεξεργαστείτε το `.env` χειροκίνητα είτε να το αναδημιουργήσετε εκτελώντας: @@ -175,7 +175,7 @@ Get-Content ..\.env # Πρέπει να εμφανίζει το AZURE_OPENAI_EN > cd .. > bash .azd-env.sh > ``` - +> > **PowerShell:** > ```powershell > cd .. @@ -184,41 +184,41 @@ Get-Content ..\.env # Πρέπει να εμφανίζει το AZURE_OPENAI_EN ## Εκτέλεση της Εφαρμογής Τοπικά -**Επαληθεύστε την ανάπτυξη:** +**Επιβεβαίωση ανάπτυξης:** -Βεβαιωθείτε ότι το αρχείο `.env` υπάρχει στη ρίζα με τα διαπιστευτήρια Azure. Εκτελέστε αυτό από τον φάκελο του module (`01-introduction/`): +Βεβαιωθείτε ότι το αρχείο `.env` υπάρχει στον ριζικό κατάλογο με τα πιστοποιητικά Azure. Εκτελέστε αυτό από τον κατάλογο του module (`01-introduction/`): **Bash:** ```bash -cat ../.env # Πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, το API_KEY, το DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Πρέπει να εμφανίζει AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Εκκίνηση των εφαρμογών:** -**Επιλογή 1: Χρήση του Spring Boot Dashboard (Συνιστάται για χρήστες VS Code)** +**Επιλογή 1: Χρήση Spring Boot Dashboard (Προτεινόμενο για χρήστες VS Code)** -Το dev container περιλαμβάνει την επέκταση Spring Boot Dashboard, που παρέχει οπτικό περιβάλλον διαχείρισης όλων των εφαρμογών Spring Boot. Μπορείτε να τη βρείτε στη Λωρίδα Εργασιών αριστερά στο VS Code (αντιστοιχεί στο εικονίδιο Spring Boot). +Το dev container περιλαμβάνει την επέκταση Spring Boot Dashboard, που παρέχει οπτική διεπαφή για διαχείριση όλων των εφαρμογών Spring Boot. Μπορείτε να τη βρείτε στη γραμμή δραστηριοτήτων στην αριστερή πλευρά του VS Code (αναζητήστε το εικονίδιο Spring Boot). Από το Spring Boot Dashboard μπορείτε να: -- δείτε όλες τις διαθέσιμες εφαρμογές Spring Boot στο workspace -- ξεκινήσετε/σταματήσετε εφαρμογές με ένα κλικ -- δείτε logs εφαρμογών σε πραγματικό χρόνο -- παρακολουθήσετε την κατάσταση των εφαρμογών +- Δείτε όλες τις διαθέσιμες εφαρμογές Spring Boot στο χώρο εργασίας +- Ξεκινήσετε/σταματήσετε εφαρμογές με ένα κλικ +- Δείτε logs εφαρμογών σε πραγματικό χρόνο +- Παρακολουθήσετε κατάσταση εφαρμογών -Απλά πατήστε το κουμπί play δίπλα στο "introduction" για να ξεκινήσετε αυτό το module, ή εκκινήστε όλα τα modules ταυτόχρονα. +Απλά κάντε κλικ στο κουμπί αναπαραγωγής δίπλα στο "introduction" για να ξεκινήσετε αυτό το module ή ξεκινήστε όλα τα modules μαζί. Spring Boot Dashboard -*Το Spring Boot Dashboard στο VS Code — ξεκινήστε, σταματήστε και παρακολουθήστε όλα τα modules από ένα μέρος* +*Το Spring Boot Dashboard στο VS Code — εκκινήστε, σταματήστε και παρακολουθήστε όλα τα modules από ένα σημείο* **Επιλογή 2: Χρήση shell scripts** -Ξεκινήστε όλες τις web εφαρμογές (modules 01-04): +Ξεκινήστε όλες τις διαδικτυακές εφαρμογές (modules 01-04): **Bash:** ```bash @@ -246,31 +246,31 @@ cd 01-introduction .\start.ps1 ``` -Και τα δύο scripts φορτώνουν αυτόματα τις μεταβλητές περιβάλλοντος από το αρχείο `.env` στη ρίζα και θα χτίσουν τα JARs αν δεν υπάρχουν. +Και τα δύο scripts φορτώνουν αυτόματα τις μεταβλητές περιβάλλοντος από το ριζικό αρχείο `.env` και θα χτίσουν τα JAR αν δεν υπάρχουν. -> **Σημείωση:** Αν προτιμάτε να χτίσετε όλα τα modules χειροκίνητα πριν την εκκίνηση: +> **Σημείωση:** Αν προτιμάτε να χτίσετε όλα τα modules χειροκίνητα πριν την εκτέλεση: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Ανοίξτε http://localhost:8080 στον περιηγητή σας. +Ανοίξτε το http://localhost:8080 στον περιηγητή σας. **Για να σταματήσετε:** **Bash:** ```bash -./stop.sh # Μόνο αυτό το μοντέλο +./stop.sh # Μόνο αυτό το μονάδα # Ή -cd .. && ./stop-all.sh # Όλα τα μοντέλα +cd .. && ./stop-all.sh # Όλες οι μονάδες ``` **PowerShell:** @@ -282,41 +282,41 @@ cd ..; .\stop-all.ps1 # Όλα τα μοντέλα ## Χρήση της Εφαρμογής -Η εφαρμογή παρέχει μια web διεπαφή με δύο υλοποιήσεις chat δίπλα-δίπλα. +Η εφαρμογή παρέχει διεπαφή ιστού με δύο υλοποιήσεις συνομιλίας παράλληλα. -Application Home Screen +Αρχική Οθόνη της Εφαρμογής -*Πίνακας ελέγχου που δείχνει τις επιλογές Simple Chat (χωρίς κατάσταση) και Conversational Chat (με κατάσταση)* +*Πίνακας επιλογών που δείχνει και τις δύο επιλογές: Απλή Συνομιλία (άνευ κατάστασης) και Συνομιλία (με κατάσταση)* -### Chat χωρίς Κατάσταση (Αριστερό Πάνελ) +### Άνευ Κατάστασης Συνομιλία (Αριστερό Πάνελ) -Δοκιμάστε πρώτα αυτό. Πείτε "Το όνομά μου είναι Ιωάννης" και έπειτα αμέσως ρωτήστε "Ποιο είναι το όνομά μου;" Το μοντέλο δεν θα θυμάται γιατί κάθε μήνυμα είναι ανεξάρτητο. Αυτό επιδεικνύει το βασικό πρόβλημα με την ενσωμάτωση γλωσσικών μοντέλων — κανένα πλαίσιο συνομιλίας. +Δοκιμάστε πρώτα αυτό. Πείτε "Το όνομά μου είναι Γιάννης" και αμέσως μετά ρωτήστε "Ποιο είναι το όνομά μου;". Το μοντέλο δεν θα το θυμάται γιατί κάθε μήνυμα είναι ανεξάρτητο. Αυτό δείχνει το βασικό πρόβλημα της απλής ενσωμάτωσης μοντέλων γλώσσας - έλλειψη πλαισίου συνομιλίας. -Stateless Chat Demo +Δοκιμή Άνευ Κατάστασης Συνομιλίας -*Το AI δεν θυμάται το όνομά σας από το προηγούμενο μήνυμα* +*Η AI δεν θυμάται το όνομά σας από το προηγούμενο μήνυμα* -### Chat με Κατάσταση (Δεξί Πάνελ) +### Κατάστασης Συνομιλία (Δεξί Πάνελ) -Τώρα δοκιμάστε την ίδια αλληλουχία εδώ. Πείτε "Το όνομά μου είναι Ιωάννης" και μετά "Ποιο είναι το όνομά μου;" Αυτή τη φορά θυμάται. Η διαφορά είναι το MessageWindowChatMemory - διατηρεί το ιστορικό συνομιλίας και το συμπεριλαμβάνει σε κάθε αίτημα. Έτσι δουλεύει η παραγωγική AI συνομιλίας. +Τώρα δοκιμάστε την ίδια ακολουθία εδώ. Πείτε "Το όνομά μου είναι Γιάννης" και μετά "Ποιο είναι το όνομά μου;". Αυτή τη φορά το θυμάται. Η διαφορά είναι το MessageWindowChatMemory - διατηρεί το ιστορικό συνομιλίας και το περιλαμβάνει σε κάθε αίτημα. Αυτός είναι ο τρόπος που λειτουργεί η παραγωγική συνομιλητική AI. -Stateful Chat Demo +Δοκιμή Κατάστασης Συνομιλίας -*Το AI θυμάται το όνομά σας από νωρίτερα στη συνομιλία* +*Η AI θυμάται το όνομά σας από νωρίτερα στη συνομιλία* -Και τα δύο πάνελ χρησιμοποιούν το ίδιο μοντέλο GPT-5.2. Η μόνη διαφορά είναι η μνήμη. Αυτό καθιστά σαφές τι φέρνει η μνήμη στην εφαρμογή σας και γιατί είναι απαραίτητη για πραγματικές περιπτώσεις χρήσης. +Και τα δύο πάνελ χρησιμοποιούν το ίδιο μοντέλο GPT-5.2. Η μόνη διαφορά είναι η μνήμη. Αυτό κάνει σαφές τι προσθέτει η μνήμη στην εφαρμογή σας και γιατί είναι απαραίτητη για πραγματικές περιπτώσεις χρήσης. ## Επόμενα Βήματα -**Επόμενο Module:** [02-prompt-engineering - Μηχανική Προτροπών με GPT-5.2](../02-prompt-engineering/README.md) +**Επόμενο Module:** [02-prompt-engineering - Μηχανική Προτροπής με GPT-5.2](../02-prompt-engineering/README.md) --- -**Πλοήγηση:** [← Προηγούμενο: Module 00 - Γρήγορο Ξεκίνημα](../00-quick-start/README.md) | [Πίσω στην κεντρική σελίδα](../README.md) | [Επόμενο: Module 02 - Μηχανική Προτροπών →](../02-prompt-engineering/README.md) +**Πλοήγηση:** [← Πίσω στην Κεντρική σελίδα](../README.md) | [Επόμενο: Module 02 - Μηχανική Προτροπής →](../02-prompt-engineering/README.md) --- -**Αποποίηση ευθυνών**: -Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που καταβάλλουμε προσπάθειες για ακρίβεια, παρακαλούμε να λάβετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη γλώσσα του πρέπει να θεωρείται ως η αυθεντική πηγή. Για σημαντικές πληροφορίες συνιστάται επαγγελματική μετάφραση από ανθρώπινο μεταφραστή. Δεν φέρουμε ευθύνη για τυχόν παρανοήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. +**Αποποίηση ευθυνών**: +Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. \ No newline at end of file diff --git a/translations/el/02-prompt-engineering/README.md b/translations/el/02-prompt-engineering/README.md index 85d307444..d19ad39a2 100644 --- a/translations/el/02-prompt-engineering/README.md +++ b/translations/el/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Ενότητα 02: Μηχανική Προτροπών με GPT-5.2 +# Ενότητα 02: Μηχανική Προτροπής με GPT-5.2 ## Περιεχόμενα -- [Περίπατος Βίντεο](../../../02-prompt-engineering) -- [Τι Θα Μάθετε](../../../02-prompt-engineering) -- [Προαπαιτούμενα](../../../02-prompt-engineering) -- [Κατανόηση της Μηχανικής Προτροπών](../../../02-prompt-engineering) -- [Βασικά της Μηχανικής Προτροπών](../../../02-prompt-engineering) - - [Zero-Shot Προτροπή](../../../02-prompt-engineering) - - [Few-Shot Προτροπή](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Ρόλος-Βασισμένη Προτροπή](../../../02-prompt-engineering) - - [Πρότυπα Προτροπών](../../../02-prompt-engineering) -- [Προχωρημένα Πρότυπα](../../../02-prompt-engineering) -- [Εκτέλεση της Εφαρμογής](../../../02-prompt-engineering) -- [Στιγμιότυπα Εφαρμογής](../../../02-prompt-engineering) -- [Εξερεύνηση των Προτύπων](../../../02-prompt-engineering) - - [Χαμηλός vs Υψηλός Ενθουσιασμός](../../../02-prompt-engineering) - - [Εκτέλεση Εργασίας (Εισαγωγές Εργαλείων)](../../../02-prompt-engineering) - - [Κώδικας Αυτοαντανάκλασης](../../../02-prompt-engineering) - - [Δομημένη Ανάλυση](../../../02-prompt-engineering) - - [Συζήτηση με Πολλούς Γύρους](../../../02-prompt-engineering) - - [Λογισμός Βήμα-Βήμα](../../../02-prompt-engineering) - - [Περιορισμένη Έξοδος](../../../02-prompt-engineering) -- [Τι Πραγματικά Μαθαίνετε](../../../02-prompt-engineering) -- [Επόμενα Βήματα](../../../02-prompt-engineering) - -## Περίπατος Βίντεο +- [Οδηγός Βίντεο](#οδηγός-βίντεο) +- [Τι Θα Μάθετε](#τι-θα-μάθετε) +- [Προαπαιτούμενα](#προαπαιτούμενα) +- [Κατανόηση της Μηχανικής Προτροπής](#κατανόηση-της-μηχανικής-προτροπής) +- [Βασικά της Μηχανικής Προτροπής](#βασικά-της-μηχανικής-προτροπής) + - [Μηδενική-Πρότυπη Προτροπή](#μηδενική-πρότυπη-προτροπή) + - [Μερική-Πρότυπη Προτροπή](#μερική-πρότυπη-προτροπή) + - [Αλυσιδωτή Σκέψη](#αλυσιδωτή-σκέψη) + - [Προτροπή με Βάση Ρόλο](#προτροπή-με-βάση-ρόλο) + - [Πρότυπα Προτροπών](#πρότυπα-προτροπών) +- [Προηγμένα Πρότυπα](#προηγμένα-πρότυπα) +- [Εκτέλεση της Εφαρμογής](#εκτέλεση-της-εφαρμογής) +- [Στιγμιότυπα Εφαρμογής](#στιγμιότυπα-εφαρμογής) +- [Εξερεύνηση των Προτύπων](#εξερεύνηση-των-μοτίβων) + - [Χαμηλός έναντι Υψηλού Ζήλου](#χαμηλή-vs-υψηλή-προθυμία) + - [Εκτέλεση Εργασίας (Προλόγοι Εργαλείων)](#εκτέλεση-εργασιών-εισαγωγικά-εργαλείων) + - [Αυτο-Ανακλαστικός Κώδικας](#αυτοαξιολογούμενος-κώδικας) + - [Δομημένη Ανάλυση](#δομημένη-ανάλυση) + - [Πολλαπλός Γύρος Συνομιλίας](#πολυγλωσσική-συζήτηση) + - [Βήμα-Βήμα Συλλογισμός](#συλλογιστική-βήμα-βήμα) + - [Περιορισμένη Έξοδος](#περιορισμένη-έξοδος) +- [Τι Μαθαίνετε Πραγματικά](#τι-μάθετε-πραγματικά) +- [Επόμενα Βήματα](#επόμενα-βήματα) + +## Οδηγός Βίντεο Παρακολουθήστε αυτήν την ζωντανή συνεδρία που εξηγεί πώς να ξεκινήσετε με αυτήν την ενότητα: -Μηχανική Προτροπών με LangChain4j - Ζωντανή Συνεδρία +Μηχανική Προτροπής με LangChain4j - Ζωντανή Συνεδρία ## Τι Θα Μάθετε -Το παρακάτω διάγραμμα παρέχει μια επισκόπηση των βασικών θεμάτων και δεξιοτήτων που θα αναπτύξετε σε αυτήν την ενότητα — από τις τεχνικές βελτίωσης προτροπών μέχρι τη ροή εργασίας βήμα-βήμα που θα ακολουθήσετε. +Το παρακάτω διάγραμμα παρέχει μια επισκόπηση των βασικών θεμάτων και δεξιοτήτων που θα αναπτύξετε σε αυτήν την ενότητα — από τεχνικές βελτίωσης προτροπών έως τη βήμα-βήμα ροή εργασίας που θα ακολουθήσετε. Τι Θα Μάθετε -Στις προηγούμενες ενότητες, εξερευνήσατε βασικές αλληλεπιδράσεις LangChain4j με Μοντέλα GitHub και είδατε πώς η μνήμη επιτρέπει τη συνομιλιακή AI με το Azure OpenAI. Τώρα θα εστιάσουμε στο πώς κάνετε ερωτήσεις — τις προτροπές αυτές καθαυτές — χρησιμοποιώντας το GPT-5.2 του Azure OpenAI. Ο τρόπος που δομείτε τις προτροπές σας επηρεάζει δραστικά την ποιότητα των απαντήσεων που λαμβάνετε. Ξεκινάμε με μια ανασκόπηση των βασικών τεχνικών προτροπών και μετά προχωράμε σε οκτώ προχωρημένα πρότυπα που εκμεταλλεύονται πλήρως τις δυνατότητες του GPT-5.2. +Στην προηγούμενη ενότητα είδατε πώς η μνήμη επιτρέπει τη συνομιλιακή ΤΝ με το Azure OpenAI. Τώρα θα επικεντρωθούμε στο πώς κάνετε ερωτήσεις — τις ίδιες τις προτροπές — χρησιμοποιώντας το GPT-5.2 του Azure OpenAI. Ο τρόπος που δομείτε τις προτροπές σας επηρεάζει δραματικά την ποιότητα των απαντήσεων που λαμβάνετε. Ξεκινάμε με μια επισκόπηση των βασικών τεχνικών προτροπών και στη συνέχεια προχωράμε σε οκτώ προχωρημένα πρότυπα που αξιοποιούν πλήρως τις δυνατότητες του GPT-5.2. -Θα χρησιμοποιήσουμε το GPT-5.2 επειδή εισάγει τον έλεγχο λογισμού - μπορείτε να πείτε στο μοντέλο πόση σκέψη να κάνει πριν απαντήσει. Αυτό κάνει τις διάφορες στρατηγικές προτροπών πιο εμφανείς και σας βοηθά να καταλάβετε πότε να χρησιμοποιήσετε κάθε προσέγγιση. Θα επωφεληθούμε επίσης από τα λιγότερα όρια χρήσης του Azure για το GPT-5.2 σε σχέση με τα Μοντέλα GitHub. +Θα χρησιμοποιήσουμε το GPT-5.2 γιατί εισάγει έλεγχο συλλογισμού - μπορείτε να πείτε στο μοντέλο πόση σκέψη να κάνει πριν απαντήσει. Αυτό καθιστά τις διάφορες στρατηγικές προτροπής πιο εμφανείς και σας βοηθά να κατανοήσετε πότε να χρησιμοποιείτε κάθε προσέγγιση. ## Προαπαιτούμενα -- Ολοκληρωμένη Ενότητα 01 (έχουν αναπτυχθεί πόροι Azure OpenAI) -- Αρχείο `.env` στον ριζικό κατάλογο με διαπιστευτήρια Azure (δημιουργήθηκε από `azd up` στην Ενότητα 01) +- Ολοκληρωμένη Ενότητα 01 (αναπτυγμένοι πόροι Azure OpenAI) +- Αρχείο `.env` στον ριζικό κατάλογο με τα διαπιστευτήρια Azure (δημιουργημένο με `azd up` στην Ενότητα 01) -> **Σημείωση:** Αν δεν έχετε ολοκληρώσει την Ενότητα 01, ακολουθήστε πρώτα τις οδηγίες ανάπτυξης εκεί. +> **Σημείωση:** Αν δεν έχετε ολοκληρώσει την Ενότητα 01, ακολουθήστε τις οδηγίες ανάπτυξης εκεί πρώτα. -## Κατανόηση της Μηχανικής Προτροπών +## Κατανόηση της Μηχανικής Προτροπής -Στην ουσία, η μηχανική προτροπών είναι η διαφορά μεταξύ ασαφών οδηγιών και ακριβών, όπως δείχνει η παρακάτω σύγκριση. +Στον πυρήνα της, η μηχανική προτροπής είναι η διαφορά μεταξύ ασαφών και ακριβών οδηγιών, όπως δείχνει η παρακάτω σύγκριση. -Τι είναι η Μηχανική Προτροπών; +Τι είναι η Μηχανική Προτροπής; -Η μηχανική προτροπών αφορά στο σχεδιασμό του κειμένου εισόδου που επιτυγχάνει σταθερά τα αποτελέσματα που χρειάζεστε. Δεν είναι απλώς θέμα να κάνετε ερωτήσεις - πρόκειται για τη δομή των αιτημάτων ώστε το μοντέλο να κατανοεί ακριβώς τι θέλετε και πώς να το παραδώσει. +Η μηχανική προτροπής αφορά το σχεδιασμό του κειμένου εισόδου που σας παρέχει σταθερά τα αποτελέσματα που χρειάζεστε. Δεν πρόκειται απλά για τη διατύπωση ερωτήσεων - πρόκειται για τη δομή αιτημάτων ώστε το μοντέλο να κατανοεί ακριβώς τι θέλετε και πώς να το παραδώσει. -Σκεφτείτε το σαν να δίνετε οδηγίες σε έναν συνάδελφο. «Διόρθωσε το σφάλμα» είναι ασαφές. «Διόρθωσε την εξαίρεση null pointer στο UserService.java γραμμή 45 προσθέτοντας έλεγχο null» είναι συγκεκριμένο. Τα γλωσσικά μοντέλα λειτουργούν με τον ίδιο τρόπο - η εξειδίκευση και η δομή έχουν σημασία. +Σκεφτείτε το σαν να δίνετε οδηγίες σε έναν συνάδελφο. «Διόρθωσε το σφάλμα» είναι ασαφές. «Διόρθωσε την εξαίρεση null pointer στο UserService.java γραμμή 45 προσθέτοντας έναν έλεγχο null» είναι συγκεκριμένο. Τα μοντέλα γλώσσας λειτουργούν με τον ίδιο τρόπο - η ακρίβεια και η δομή έχουν σημασία. -Το παρακάτω διάγραμμα δείχνει πώς το LangChain4j εντάσσεται σε αυτήν την εικόνα — συνδέοντας τα πρότυπα προτροπών σας με το μοντέλο μέσω των δομικών μπλοκ SystemMessage και UserMessage. +Το παρακάτω διάγραμμα δείχνει πώς το LangChain4j εντάσσεται σε αυτήν την εικόνα — συνδέοντας τα πρότυπα προτροπών σας με το μοντέλο μέσω των δομικών στοιχείων SystemMessage και UserMessage. -Πώς Εντάσσεται το LangChain4j +Πώς το LangChain4j Ταιριάζει -Το LangChain4j παρέχει τη δομή — συνδέσεις μοντέλου, μνήμη και τύπους μηνυμάτων — ενώ τα πρότυπα προτροπών είναι απλώς προσεκτικά δομημένο κείμενο που στέλνετε μέσω αυτής της δομής. Τα βασικά δομικά στοιχεία είναι το `SystemMessage` (που ορίζει τη συμπεριφορά και το ρόλο του AI) και το `UserMessage` (που μεταφέρει το πραγματικό σας αίτημα). +Το LangChain4j παρέχει την υποδομή — συνδέσεις μοντέλου, μνήμη και τύπους μηνυμάτων — ενώ τα πρότυπα προτροπών είναι απλώς προσεκτικά δομημένα κείμενα που στέλνετε μέσα από αυτή την υποδομή. Τα βασικά δομικά στοιχεία είναι το `SystemMessage` (που ορίζει τη συμπεριφορά και το ρόλο της ΤΝ) και το `UserMessage` (που μεταφέρει το πραγματικό σας αίτημα). -## Βασικά της Μηχανικής Προτροπών +## Βασικά της Μηχανικής Προτροπής -Οι πέντε βασικές τεχνικές που φαίνονται παρακάτω σχηματίζουν το θεμέλιο της αποτελεσματικής μηχανικής προτροπών. Καθεμία απευθύνεται σε διαφορετική πτυχή του πώς επικοινωνείτε με τα γλωσσικά μοντέλα. +Οι πέντε βασικές τεχνικές που εμφανίζονται παρακάτω αποτελούν τη βάση της αποτελεσματικής μηχανικής προτροπής. Η κάθε μία αντιμετωπίζει μια διαφορετική πτυχή της επικοινωνίας σας με τα μοντέλα γλώσσας. -Επισκόπηση Πέντε Προτύπων Μηχανικής Προτροπών +Επισκόπηση Πέντε Προτύπων Μηχανικής Προτροπής -Πριν βουτήξουμε στα προχωρημένα πρότυπα αυτής της ενότητας, ας ανασκοπήσουμε πέντε θεμελιώδεις τεχνικές προτροπών. Αυτά είναι τα δομικά στοιχεία που κάθε μηχανικός προτροπών πρέπει να γνωρίζει. Αν έχετε ήδη δουλέψει στην [Ενότητα Γρήγορης Έναρξης](../00-quick-start/README.md#2-prompt-patterns), τα έχετε δει στην πράξη — εδώ είναι το εννοιολογικό πλαίσιο πίσω από αυτά. +Πριν εμβαθύνετε στα προχωρημένα πρότυπα αυτής της ενότητας, ας δούμε πέντε θεμελιώδεις τεχνικές προτροπής. Αυτές είναι τα δομικά στοιχεία που κάθε μηχανικός προτροπών πρέπει να γνωρίζει. -### Zero-Shot Προτροπή +### Μηδενική-Πρότυπη Προτροπή -Η πιο απλή προσέγγιση: δώστε στο μοντέλο μια απευθείας οδηγία χωρίς παραδείγματα. Το μοντέλο βασίζεται εξ ολοκλήρου στην εκπαίδευσή του για να καταλάβει και να εκτελέσει την εργασία. Αυτό λειτουργεί καλά για απλά αιτήματα όπου η αναμενόμενη συμπεριφορά είναι προφανής. +Η απλούστερη προσέγγιση: δώστε στο μοντέλο μια άμεση οδηγία χωρίς παραδείγματα. Το μοντέλο βασίζεται αποκλειστικά στην εκπαίδευσή του για να κατανοήσει και να εκτελέσει την εργασία. Λειτουργεί καλά για απλά αιτήματα όπου η αναμενόμενη συμπεριφορά είναι προφανής. -Zero-Shot Προτροπή +Μηδενική-Πρότυπη Προτροπή -*Άμεση οδηγία χωρίς παραδείγματα — το μοντέλο συμπεραίνει την εργασία από την οδηγία μόνο* +*Άμεση οδηγία χωρίς παραδείγματα — το μοντέλο συμπεραίνει την εργασία μόνο από την οδηγία* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// Απάντηση: "Θετική" +// Απόκριση: "Θετικό" ``` -**Πότε να τη χρησιμοποιήσετε:** Απλές ταξινομήσεις, άμεσες ερωτήσεις, μεταφράσεις ή οποιαδήποτε εργασία το μοντέλο μπορεί να χειριστεί χωρίς περαιτέρω καθοδήγηση. +**Πότε να χρησιμοποιείται:** Απλές ταξινομήσεις, άμεσες ερωτήσεις, μεταφράσεις ή οποιαδήποτε εργασία που το μοντέλο μπορεί να χειριστεί χωρίς πρόσθετη καθοδήγηση. -### Few-Shot Προτροπή +### Μερική-Πρότυπη Προτροπή -Παρέχετε παραδείγματα που δείχνουν το μοτίβο που θέλετε να ακολουθήσει το μοντέλο. Το μοντέλο μαθαίνει το αναμενόμενο πρότυπο εισόδου-εξόδου από τα παραδείγματά σας και το εφαρμόζει σε νέα δεδομένα. Αυτό βελτιώνει δραστικά τη συνέπεια για εργασίες όπου η επιθυμητή μορφή ή συμπεριφορά δεν είναι προφανής. +Παρέχετε παραδείγματα που δείχνουν το πρότυπο που θέλετε να ακολουθήσει το μοντέλο. Το μοντέλο μαθαίνει το αναμενόμενο μορφότυπο εισόδου-εξόδου από τα παραδείγματα και το εφαρμόζει σε νέες εισόδους. Αυτό βελτιώνει δραματικά τη συνέπεια σε εργασίες όπου η επιθυμητή μορφή ή συμπεριφορά δεν είναι προφανής. -Few-Shot Προτροπή +Μερική-Πρότυπη Προτροπή -*Μάθηση από παραδείγματα — το μοντέλο αναγνωρίζει το μοτίβο και το εφαρμόζει σε νέα δεδομένα* +*Μάθηση από παραδείγματα — το μοντέλο αναγνωρίζει το πρότυπο και το εφαρμόζει σε νέες εισόδους* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Πότε να τη χρησιμοποιήσετε:** Προσαρμοσμένες ταξινομήσεις, συνεπής μορφοποίηση, εργασίες ειδικού τομέα, ή όταν τα αποτελέσματα zero-shot είναι ασυνεπή. +**Πότε να χρησιμοποιείται:** Προσαρμοσμένες ταξινομήσεις, συνεπής μορφοποίηση, εργασίες ειδικού τομέα ή όταν τα αποτελέσματα μηδενικής-πρότυπης προτροπής είναι ασυνεπή. -### Chain of Thought +### Αλυσιδωτή Σκέψη -Ζητήστε από το μοντέλο να δείξει το συλλογισμό του βήμα-βήμα. Αντί να πηδήξει κατευθείαν σε απάντηση, το μοντέλο αναλύει το πρόβλημα και δουλεύει κάθε μέρος ρητά. Αυτό βελτιώνει την ακρίβεια σε μαθηματικά, λογική και σύνθετες εργασίες συλλογισμού. +Ζητήστε από το μοντέλο να δείξει τη λογική του βήμα-βήμα. Αντί να πηδήξει απευθείας σε μια απάντηση, το μοντέλο αναλύει το πρόβλημα και προχωρά σε κάθε μέρος ρητά. Αυτό βελτιώνει την ακρίβεια σε μαθηματικά, λογική και πολύ-βηματικές εργασίες συλλογισμού. -Chain of Thought Προτροπή +Προτροπή Αλυσιδωτής Σκέψης -*Λογισμός βήμα-βήμα — ανάλυση σύνθετων προβλημάτων σε ρητά λογικά βήματα* +*Βήμα-βήμα συλλογισμός — διάσπαση σύνθετων προβλημάτων σε ρητές λογικές ενότητες* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Το μοντέλο δείχνει: 15 - 8 = 7, στη συνέχεια 7 + 12 = 19 μήλα ``` -**Πότε να τη χρησιμοποιήσετε:** Μαθηματικά προβλήματα, λογικά παζλ, αποσφαλμάτωση ή οποιαδήποτε εργασία όπου η εμφάνιση της διαδικασίας συλλογισμού βελτιώνει την ακρίβεια και την εμπιστοσύνη. +**Πότε να χρησιμοποιείται:** Μαθηματικά προβλήματα, λογικά παζλ, αποσφαλμάτωση ή οποιαδήποτε εργασία όπου η εμφάνιση της διαδικασίας συλλογισμού βελτιώνει την ακρίβεια και την αξιοπιστία. -### Ρόλος-Βασισμένη Προτροπή +### Προτροπή με Βάση Ρόλο -Ορίστε μια περσόνα ή ρόλο για το AI πριν κάνετε την ερώτησή σας. Αυτό παρέχει πλαίσιο που διαμορφώνει τον τόνο, το βάθος και την εστίαση της απάντησης. Ένας «αρχιτέκτονας λογισμικού» δίνει διαφορετικές συμβουλές από έναν «νεότερο προγραμματιστή» ή έναν «ελεγκτή ασφαλείας». +Ορίστε μια περσόνα ή ρόλο για την ΤΝ πριν κάνετε την ερώτησή σας. Αυτό παρέχει πλαίσιο που διαμορφώνει τον τόνο, το βάθος και την εστίαση της απάντησης. Ένας «αρχιτέκτονας λογισμικού» δίνει διαφορετικές συμβουλές από έναν «νεότερο προγραμματιστή» ή έναν «ελεγκτή ασφαλείας». -Ρόλος-Βασισμένη Προτροπή +Προτροπή με Βάση Ρόλο -*Ορισμός πλαισίου και περσόνας — η ίδια ερώτηση παίρνει διαφορετική απάντηση ανάλογα με τον ανατεθειμένο ρόλο* +*Ορισμός πλαισίου και περσόνας — η ίδια ερώτηση λαμβάνει διαφορετική απάντηση ανάλογα με τον ορισμένο ρόλο* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Πότε να τη χρησιμοποιήσετε:** Ανασκοπήσεις κώδικα, διδασκαλία, ανάλυση ειδικού τομέα ή όταν χρειάζεστε απαντήσεις προσαρμοσμένες σε συγκεκριμένο επίπεδο εμπειρογνωμοσύνης ή οπτική γωνία. +**Πότε να χρησιμοποιείται:** Αναθεώρηση κώδικα, διδασκαλία, ανάλυση ειδικού τομέα ή όταν χρειάζεστε απαντήσεις προσαρμοσμένες σε συγκεκριμένο επίπεδο τεχνογνωσίας ή προοπτική. ### Πρότυπα Προτροπών -Δημιουργήστε επαναχρησιμοποιήσιμες προτροπές με μεταβλητές θέσεις. Αντί να γράφετε μια νέα προτροπή κάθε φορά, ορίστε ένα πρότυπο μία φορά και γεμίστε με διαφορετικές τιμές. Η κλάση `PromptTemplate` του LangChain4j το καθιστά εύκολο με τη σύνταξη `{{variable}}`. +Δημιουργήστε επαναχρησιμοποιήσιμες προτροπές με μεταβλητές θέσεις. Αντί να γράφετε μια νέα προτροπή κάθε φορά, ορίστε ένα πρότυπο μία φορά και συμπληρώστε διαφορετικές τιμές. Η κλάση `PromptTemplate` του LangChain4j το καθιστά εύκολο με τη σύνταξη `{{variable}}`. Πρότυπα Προτροπών -*Επαναχρησιμοποιήσιμες προτροπές με μεταβλητές θέσεις — ένα πρότυπο, πολλές χρήσεις* +*Επαναχρησιμοποιήσιμες προτροπές με μεταβλητές — ένα πρότυπο, πολλές χρήσεις* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Πότε να τη χρησιμοποιήσετε:** Επαναλαμβανόμενα ερωτήματα με διαφορετικές εισόδους, μαζική επεξεργασία, δημιουργία επαναχρησιμοποιήσιμων ροών εργασίας AI ή οποιοδήποτε σενάριο όπου η δομή της προτροπής παραμένει ίδια αλλά αλλάζουν τα δεδομένα. +**Πότε να χρησιμοποιείται:** Επανάληψη ερωτημάτων με διαφορετικές εισόδους, επεξεργασία παρτίδων, κατασκευή επαναχρησιμοποιήσιμων ροών εργασίας ΤΝ ή οποιοδήποτε σενάριο όπου η δομή της προτροπής παραμένει ίδια αλλά τα δεδομένα αλλάζουν. --- -Αυτά τα πέντε θεμελιώδη σας δίνουν ένα σταθερό εργαλείο για τις περισσότερες εργασίες προτροπών. Το υπόλοιπο αυτής της ενότητας βασίζεται σε αυτά με **οκτώ προχωρημένα πρότυπα** που εκμεταλλεύονται τον έλεγχο λογισμού, την αυτοαξιολόγηση και τις ικανότητες δομημένης εξόδου του GPT-5.2. +Αυτά τα πέντε βασικά στοιχεία σας παρέχουν ένα στιβαρό σύνολο εργαλείων για τις περισσότερες εργασίες προτροπής. Το υπόλοιπο της ενότητας βασίζεται σε αυτά με **οκτώ προχωρημένα πρότυπα** που αξιοποιούν τον έλεγχο συλλογισμού, την αυτο-αξιολόγηση και τις δομημένες δυνατότητες εξόδου του GPT-5.2. -## Προχωρημένα Πρότυπα +## Προηγμένα Πρότυπα -Με τα βασικά καλυμμένα, ας περάσουμε στα οκτώ προχωρημένα πρότυπα που κάνουν αυτήν την ενότητα μοναδική. Δεν χρειάζεται κάθε πρόβλημα την ίδια προσέγγιση. Κάποιες ερωτήσεις χρειάζονται γρήγορες απαντήσεις, άλλες βαθιά σκέψη. Κάποιες χρειάζονται ορατό λογισμό, άλλες μόνο αποτελέσματα. Κάθε πρότυπο παρακάτω είναι βελτιστοποιημένο για διαφορετικό σενάριο — και ο έλεγχος λογισμού του GPT-5.2 κάνει τις διαφορές ακόμα πιο εμφανείς. +Με τα βασικά καλυμμένα, ας περάσουμε στα οκτώ προχωρημένα πρότυπα που καθιστούν αυτήν την ενότητα μοναδική. Όχι όλα τα προβλήματα χρειάζονται την ίδια προσέγγιση. Κάποιες ερωτήσεις θέλουν γρήγορες απαντήσεις, άλλες βαθιά σκέψη. Κάποιες απαιτούν ορατό συλλογισμό, άλλες μόνο αποτελέσματα. Κάθε πρότυπο παρακάτω είναι βελτιστοποιημένο για διαφορετικό σενάριο — και ο έλεγχος συλλογισμού του GPT-5.2 καθιστά τις διαφορές ακόμα πιο έντονες. -Οκτώ Πρότυπα Προτροπών +Οκτώ Πρότυπα Προτροπής -*Επισκόπηση των οκτώ προτύπων μηχανικής προτροπών και των περιπτώσεων χρήσης τους* +*Επισκόπηση των οκτώ προτύπων μηχανικής προτροπής και των περιπτώσεων χρήσης τους* -Το GPT-5.2 προσθέτει μια ακόμα διάσταση σε αυτά τα πρότυπα: *έλεγχο λογισμού*. Η γραμμή κύλισης παρακάτω δείχνει πόσο μπορείτε να προσαρμόσετε την προσπάθεια σκέψης του μοντέλου — από γρήγορες, άμεσες απαντήσεις σε βαθιά, λεπτομερή ανάλυση. +Το GPT-5.2 προσθέτει μια επιπλέον διάσταση σε αυτά τα πρότυπα: *έλεγχο συλλογισμού*. Ο παρακάτω ρυθμιστής δείχνει πώς μπορείτε να ρυθμίσετε την προσπάθεια σκέψης του μοντέλου — από γρήγορες, άμεσες απαντήσεις έως βαθιά, ολοκληρωμένη ανάλυση. -Έλεγχος Λογισμού με GPT-5.2 +Έλεγχος Συλλογισμού με GPT-5.2 -*Ο έλεγχος λογισμού του GPT-5.2 σάς επιτρέπει να καθορίσετε πόση σκέψη πρέπει να κάνει το μοντέλο — από γρήγορες άμεσες απαντήσεις έως βαθιά διερεύνηση* +*Ο έλεγχος συλλογισμού του GPT-5.2 σας επιτρέπει να καθορίσετε πόση σκέψη πρέπει να κάνει το μοντέλο — από γρήγορες απαντήσεις έως βαθιά εξερεύνηση* -**Χαμηλός Ενθουσιασμός (Γρήγορο & Εστιασμένο)** - Για απλές ερωτήσεις όπου θέλετε γρήγορες, άμεσες απαντήσεις. Το μοντέλο κάνει ελάχιστο λογισμό - μέγιστο 2 βήματα. Χρησιμοποιήστε το για υπολογισμούς, αναζητήσεις ή απλές ερωτήσεις. +**Χαμηλός Ζήλος (Γρήγορο & Εστιασμένο)** - Για απλές ερωτήσεις όπου θέλετε γρήγορες, άμεσες απαντήσεις. Το μοντέλο κάνει ελάχιστο συλλογισμό - το πολύ 2 βήματα. Χρησιμοποιήστε το για υπολογισμούς, αναζητήσεις ή απλές ερωτήσεις. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Διερευνήστε με GitHub Copilot:** Ανοίξτε το [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) και ρωτήστε: -> - "Ποια είναι η διαφορά μεταξύ προτύπων προτροπής χαμηλού και υψηλού ενθουσιασμού;" -> - "Πώς βοηθούν τα XML tags στις προτροπές στη δομή της απάντησης του AI;" -> - "Πότε πρέπει να χρησιμοποιώ πρότυπα αυτοαντανάκλασης αντί για άμεσες οδηγίες;" +> 💡 **Εξερευνήστε με το GitHub Copilot:** Ανοίξτε το [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) και ρωτήστε: +> - "Ποια είναι η διαφορά ανάμεσα σε πρότυπα χαμηλού και υψηλού ζήλου;" +> - "Πώς βοηθούν τα XML tags στη δομή της απάντησης της ΤΝ;" +> - "Πότε να χρησιμοποιώ πρότυπα αυτο-ανασκόπησης έναντι άμεσης οδηγίας;" -**Υψηλός Ενθουσιασμός (Βαθύς & Λεπτομερής)** - Για σύνθετα προβλήματα όπου θέλετε ολοκληρωμένη ανάλυση. Το μοντέλο εξερευνά εκτενώς και δείχνει λεπτομερή συλλογισμό. Χρησιμοποιήστε το για σχεδιασμό συστημάτων, αποφάσεις αρχιτεκτονικής ή σύνθετη έρευνα. +**Υψηλός Ζήλος (Βαθιά & Αναλυτικό)** - Για σύνθετα προβλήματα όπου θέλετε ολοκληρωμένη ανάλυση. Το μοντέλο εξερευνά διεξοδικά και δείχνει λεπτομερή συλλογισμό. Χρησιμοποιήστε το για σχεδιασμό συστήματος, αρχιτεκτονικές αποφάσεις ή πολύπλοκη έρευνα. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Εκτέλεση Εργασίας (Πρόοδος Βήμα-Βήμα)** - Για ροές εργασίας με πολλαπλά βήματα. Το μοντέλο παρέχει ένα αρχικό πλάνο, αφηγείται κάθε βήμα καθώς εργάζεται, και μετά δίνει μια περίληψη. Χρησιμοποιήστε το για μεταφορές, υλοποιήσεις ή οποιαδήποτε διαδικασία με πολλά βήματα. +**Εκτέλεση Εργασίας (Πρόοδος Βήμα-Βήμα)** - Για ροές εργασίας με πολλά βήματα. Το μοντέλο παρέχει αρχικό σχεδιασμό, αφηγείται κάθε βήμα καθώς εργάζεται και στη συνέχεια δίνει περίληψη. Χρησιμοποιήστε το για μετακινήσεις, υλοποιήσεις ή οποιαδήποτε διαδικασία πολλαπλών βημάτων. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Η προτροπή Chain-of-Thought ζητά ρητά από το μοντέλο να δείξει τη διαδικασία συλλογισμού του, βελτιώνοντας την ακρίβεια για σύνθετες εργασίες. Η ανάλυση βήμα-βήμα βοηθά τόσο τους ανθρώπους όσο και το AI να κατανοήσουν τη λογική. +Η προτροπή αλυσιδωτής σκέψης ζητά ρητά από το μοντέλο να δείξει τη διαδικασία συλλογισμού του, βελτιώνοντας την ακρίβεια για σύνθετες εργασίες. Η διάσπαση βήμα-βήμα βοηθά ανθρώπους και ΤΝ να κατανοήσουν τη λογική. -> **🤖 Δοκιμάστε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Ρωτήστε για αυτό το πρότυπο: +> **🤖 Δοκιμάστε με συνομιλία [GitHub Copilot](https://github.com/features/copilot):** Ρωτήστε για αυτό το πρότυπο: > - "Πώς θα προσαρμόσω το πρότυπο εκτέλεσης εργασίας για μακροχρόνιες λειτουργίες;" -> - "Ποιες είναι οι βέλτιστες πρακτικές για τη δομή εισαγωγών εργαλείων σε εφαρμογές παραγωγής;" -> - "Πώς μπορώ να καταγράψω και να εμφανίσω τις ενδιάμεσες ενημερώσεις προόδου σε UI;" +> - "Ποιες είναι οι βέλτιστες πρακτικές για δομή προλόγων εργαλείων σε παραγωγικές εφαρμογές;" +> - "Πώς μπορώ να καταγράψω και να εμφανίσω ενδιάμεσα ενημερώσεις προόδου σε UI;" -Το παρακάτω διάγραμμα απεικονίζει αυτήν τη ροή εργασίας Σχεδίαση → Εκτέλεση → Περίληψη. +Το παρακάτω διάγραμμα απεικονίζει αυτή τη ροή εργασίας Σχεδιασμός → Εκτέλεση → Περίληψη. Πρότυπο Εκτέλεσης Εργασίας -*Ροή εργασίας Σχεδίαση → Εκτέλεση → Περίληψη για εργασίες με πολλά βήματα* +*Ροή εργασίας Σχεδιασμός → Εκτέλεση → Περίληψη για εργασίες πολλαπλών βημάτων* -**Κώδικας Αυτοαντανάκλασης** - Για παραγωγή κώδικα ποιότητας παραγωγής. Το μοντέλο παράγει κώδικα που ακολουθεί πρότυπα παραγωγής με σωστή διαχείριση σφαλμάτων. Χρησιμοποιήστε το όταν δημιουργείτε νέες λειτουργίες ή υπηρεσίες. +**Αυτο-Ανακλαστικός Κώδικας** - Για παραγωγή κώδικα ποιότητας παραγωγής. Το μοντέλο παράγει κώδικα που ακολουθεί πρότυπα παραγωγής με σωστή διαχείριση σφαλμάτων. Χρησιμοποιήστε το όταν δημιουργείτε νέες λειτουργίες ή υπηρεσίες. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Το παρακάτω διάγραμμα δείχνει αυτόν τον επαναληπτικό κύκλο βελτίωσης — παράγει, αξιολογεί, εντοπίζει αδυναμίες και βελτιώνει μέχρι ο κώδικας να πληροί τα πρότυπα παραγωγής. +Το παρακάτω διάγραμμα δείχνει αυτόν τον επαναληπτικό βρόχο βελτίωσης — παραγωγή, αξιολόγηση, εντοπισμός αδυναμιών και βελτίωση μέχρι ο κώδικας να ανταποκρίνεται στα πρότυπα παραγωγής. -Κύκλος Αυτοαντανάκλασης +Κύκλος Αυτο-Ανασκόπησης -*Επαναληπτικός κύκλος βελτίωσης - παραγωγή, αξιολόγηση, εντοπισμός προβλημάτων, βελτίωση, επανάληψη* +*Επαναληπτικός βρόχος βελτίωσης - παραγωγή, αξιολόγηση, εντοπισμός θεμάτων, βελτίωση, επανάληψη* -**Δομημένη Ανάλυση** - Για συνεπή αξιολόγηση. Το μοντέλο ελέγχει τον κώδικα χρησιμοποιώντας ένα σταθερό πλαίσιο (ορθότητα, πρακτικές, επιδόσεις, ασφάλεια, διαχειρισιμότητα). Χρησιμοποιήστε το για ανασκοπήσεις κώδικα ή αξιολογήσεις ποιότητας. +**Δομημένη Ανάλυση** - Για συνεπή αξιολόγηση. Το μοντέλο αναθεωρεί κώδικα χρησιμοποιώντας ένα σταθερό πλαίσιο (σωστότητα, πρακτικές, απόδοση, ασφάλεια, διατηρησιμότητα). Χρησιμοποιήστε το για αναθεωρήσεις κώδικα ή αξιολογήσεις ποιότητας. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Δοκιμάστε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Ρωτήστε για δομημένη ανάλυση: -> - "Πώς μπορώ να προσαρμόσω το πλαίσιο ανάλυσης για διαφορετικούς τύπους ανασκοπήσεων κώδικα;" -> - "Ποιος είναι ο καλύτερος τρόπος να αναλύσω και να ενεργήσω σε δομημένη έξοδο προγραμματιστικά;" -> - "Πώς διασφαλίζω συνεπή επίπεδα σοβαρότητας σε διαφορετικές συνεδρίες ανασκόπησης;" +> **🤖 Δοκιμάστε με συνομιλία [GitHub Copilot](https://github.com/features/copilot):** Ρωτήστε για δομημένη ανάλυση: +> - "Πώς μπορώ να προσωποποιήσω το πλαίσιο ανάλυσης για διαφορετικούς τύπους αναθεωρήσεων κώδικα;" +> - "Ποιος είναι ο καλύτερος τρόπος για να αναλύσω και να ενεργήσω σε δομημένη έξοδο προγραμματιστικά;" +> - "Πώς εξασφαλίζω συνεπή επίπεδα σοβαρότητας σε διαφορετικές συνεδρίες αναθεώρησης;" -Το παρακάτω διάγραμμα δείχνει πώς αυτό το δομημένο πλαίσιο οργανώνει μια ανασκόπηση κώδικα σε συνεπείς κατηγορίες με επίπεδα σοβαρότητας. +Το παρακάτω διάγραμμα δείχνει πώς αυτό το δομημένο πλαίσιο οργανώνει μια αναθεώρηση κώδικα σε συνεπείς κατηγορίες με επίπεδα σοβαρότητας. Πρότυπο Δομημένης Ανάλυσης -*Πλαίσιο για συνεπείς ανασκοπήσεις κώδικα με επίπεδα σοβαρότητας* +*Πλαίσιο για συνεπείς αναθεωρήσεις κώδικα με επίπεδα σοβαρότητας* -**Συζήτηση με Πολλούς Γύρους** - Για συνομιλίες που χρειάζονται πλαίσιο. Το μοντέλο θυμάται προηγούμενα μηνύματα και χτίζει πάνω σε αυτά. Χρησιμοποιήστε το για διαδραστικές συνεδρίες βοήθειας ή σύνθετες ερωτήσεις και απαντήσεις. +**Πολλαπλός Γύρος Συνομιλίας** - Για συνομιλίες που χρειάζονται πλαίσιο. Το μοντέλο θυμάται προηγούμενα μηνύματα και χτίζει πάνω σε αυτά. Χρησιμοποιήστε το για διαδραστικές συνεδρίες βοήθειας ή σύνθετες ερωτήσεις-απαντήσεις. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Το διάγραμμα παρακάτω οπτικοποιεί το πώς το πλαίσιο της συνομιλίας συσσωρεύεται με κάθε γύρο και πώς σχετίζεται με το όριο token του μοντέλου. +Το παρακάτω διάγραμμα απεικονίζει πώς συσσωρεύεται το πλαίσιο συνομιλίας με κάθε γύρο και πώς σχετίζεται με το όριο token του μοντέλου. -Μνήμη Πλαισίου Συνομιλίας +Μνήμη Πλαισίου -*Πώς συσσωρεύεται το πλαίσιο συνομιλίας μέσω πολλαπλών γύρων μέχρι να φτάσει το όριο token* -**Βήμα-Βήμα Λογισμός** - Για προβλήματα που απαιτούν ορατή λογική. Το μοντέλο δείχνει ρητό συλλογισμό για κάθε βήμα. Χρησιμοποιήστε το αυτό για μαθηματικά προβλήματα, γρίφους λογικής ή όταν χρειάζεται να κατανοήσετε τη διαδικασία σκέψης. +*Πώς συσσωρεύεται το πλαίσιο συνομιλίας σε πολλούς γύρους μέχρι να φτάσει το όριο token* + +**Βήμα-Βήμα Συλλογισμός** - Για προβλήματα που απαιτούν ορατή λογική. Το μοντέλο δείχνει ρητή λογική για κάθε βήμα. Χρησιμοποιήστε το για μαθηματικά προβλήματα, λογικά παζλ ή όταν χρειάζεστε να κατανοήσετε τη διαδικασία σκέψης. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Το παρακάτω διάγραμμα απεικονίζει πώς το μοντέλο διασπά τα προβλήματα σε ρητά, αριθμημένα λογικά βήματα. +Το παρακάτω διάγραμμα απεικονίζει πώς το μοντέλο διασπά προβλήματα σε ρητά, αριθμημένα λογικά βήματα. Πρότυπο Βήμα-Βήμα +*Αποσύνθεση προβλημάτων σε ρητά λογικά βήματα* -*Διάσπαση προβλημάτων σε ρητά λογικά βήματα* - -**Περιορισμένη Έξοδος** - Για απαντήσεις με συγκεκριμένες απαιτήσεις μορφής. Το μοντέλο ακολουθεί αυστηρά τους κανόνες μορφής και μήκους. Χρησιμοποιήστε αυτό για περιλήψεις ή όταν χρειάζεστε ακριβή δομή εξόδου. +**Περιορισμένη Έξοδος** - Για απαντήσεις με συγκεκριμένες απαιτήσεις μορφοποίησης. Το μοντέλο ακολουθεί αυστηρά τους κανόνες μορφής και μήκους. Χρησιμοποιήστε το για περιλήψεις ή όταν χρειάζεστε ακριβή δομή εξόδου. ```java String prompt = """ @@ -420,9 +420,9 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Το παρακάτω διάγραμμα δείχνει πώς οι περιορισμοί καθοδηγούν το μοντέλο να παράγει έξοδο που ακολουθεί αυστηρά τις απαιτήσεις σας για μορφή και μήκος. +Το παρακάτω διάγραμμα δείχνει πώς οι περιορισμοί καθοδηγούν το μοντέλο να παράγει έξοδο που συμμορφώνεται αυστηρά με τις απαιτήσεις μορφής και μήκους σας. -Πρότυπο Περιορισμένης Εξόδου +Μοτίβο Περιορισμένης Εξόδου *Επιβολή συγκεκριμένων απαιτήσεων μορφής, μήκους και δομής* @@ -430,7 +430,7 @@ String response = chatModel.chat(prompt); **Επαλήθευση ανάπτυξης:** -Βεβαιωθείτε ότι το αρχείο `.env` υπάρχει στον κύριο φάκελο με τα διαπιστευτήρια Azure (δημιουργήθηκε κατά το Module 01). Εκτελέστε από το φάκελο του module (`02-prompt-engineering/`): +Βεβαιωθείτε ότι το αρχείο `.env` υπάρχει στον κεντρικό κατάλογο με τα διαπιστευτήρια Azure (δημιουργήθηκε κατά το Module 01). Τρέξτε αυτό από τον κατάλογο του module (`02-prompt-engineering/`): **Bash:** ```bash @@ -439,32 +439,32 @@ cat ../.env # Θα πρέπει να εμφανίζει AZURE_OPENAI_ENDPOINT, **PowerShell:** ```powershell -Get-Content ..\.env # Πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, το API_KEY, το DEPLOYMENT +Get-Content ..\.env # Πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Εκκίνηση της εφαρμογής:** -> **Σημείωση:** Αν έχετε ήδη εκκινήσει όλες τις εφαρμογές χρησιμοποιώντας `./start-all.sh` από τον κύριο φάκελο (όπως περιγράφεται στο Module 01), αυτό το module ήδη τρέχει στην θύρα 8083. Μπορείτε να παραλείψετε τις εντολές εκκίνησης παρακάτω και να πάτε απευθείας στο http://localhost:8083. +> **Σημείωση:** Αν έχετε ήδη ξεκινήσει όλες τις εφαρμογές χρησιμοποιώντας το `./start-all.sh` από τον κεντρικό κατάλογο (όπως περιγράφεται στο Module 01), αυτό το module τρέχει ήδη στην πόρτα 8083. Μπορείτε να παραλείψετε τις εντολές εκκίνησης παρακάτω και να πάτε απευθείας στο http://localhost:8083. **Επιλογή 1: Χρήση του Spring Boot Dashboard (Συνιστάται για χρήστες VS Code)** -Το περιβάλλον ανάπτυξης περιλαμβάνει την επέκταση Spring Boot Dashboard, η οποία παρέχει οπτική διεπαφή για τη διαχείριση όλων των εφαρμογών Spring Boot. Μπορείτε να τη βρείτε στη γραμμή δραστηριοτήτων αριστερά στο VS Code (αναζητήστε το εικονίδιο Spring Boot). +Το περιβάλλον ανάπτυξης περιλαμβάνει την επέκταση Spring Boot Dashboard, η οποία προσφέρει οπτική διεπαφή για τη διαχείριση όλων των εφαρμογών Spring Boot. Μπορείτε να το βρείτε στη Γραμμή Δραστηριοτήτων αριστερά στο VS Code (αναζητήστε το εικονίδιο Spring Boot). Από το Spring Boot Dashboard, μπορείτε να: -- Δείτε όλες τις διαθέσιμες εφαρμογές Spring Boot στο χώρο εργασίας -- Εκκινήσετε/σταματήσετε εφαρμογές με ένα κλικ -- Παρακολουθήσετε τα αρχεία καταγραφής εφαρμογών σε πραγματικό χρόνο -- Επιβλέψετε την κατάσταση των εφαρμογών +- Δείτε όλες τις διαθέσιμες εφαρμογές Spring Boot στον χώρο εργασίας +- Ξεκινήσετε/σταματήσετε εφαρμογές με ένα κλικ +- Προβάλετε τα αρχεία καταγραφής εφαρμογών σε πραγματικό χρόνο +- Παρακολουθείτε την κατάσταση της εφαρμογής Απλά κάντε κλικ στο κουμπί αναπαραγωγής δίπλα στο "prompt-engineering" για να ξεκινήσετε αυτό το module, ή ξεκινήστε όλα τα modules ταυτόχρονα. -Πίνακας Ελέγχου Spring Boot +Spring Boot Dashboard -*Το Spring Boot Dashboard στο VS Code — εκκίνηση, διακοπή και παρακολούθηση όλων των modules από ένα μέρος* +*Το Spring Boot Dashboard στο VS Code — ξεκινήστε, σταματήστε και παρακολουθήστε όλα τα modules από ένα σημείο* **Επιλογή 2: Χρήση scripts κελύφους** -Εκκινήστε όλες τις web εφαρμογές (modules 01-04): +Ξεκινήστε όλες τις web εφαρμογές (modules 01-04): **Bash:** ```bash @@ -478,7 +478,7 @@ cd .. # Από τον ριζικό κατάλογο .\start-all.ps1 ``` -Ή εκκινήστε μόνο αυτό το module: +Ή ξεκινήστε μόνο αυτό το module: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Και τα δύο scripts φορτώνουν αυτόματα μεταβλητές περιβάλλοντος από το αρχείο `.env` στον κύριο φάκελο και θα χτίσουν τα JAR αν δεν υπάρχουν. +Και τα δύο scripts φορτώνουν αυτόματα μεταβλητές περιβάλλοντος από το κεντρικό `.env` αρχείο και θα κατασκευάσουν τα JAR αν δεν υπάρχουν. -> **Σημείωση:** Αν προτιμάτε να χτίσετε όλα τα modules χειροκίνητα πριν ξεκινήσετε: +> **Σημείωση:** Αν προτιμάτε να χτίσετε όλα τα modules χειροκίνητα πριν την εκκίνηση: > > **Bash:** > ```bash @@ -521,88 +521,88 @@ cd .. && ./stop-all.sh # Όλα τα modules **PowerShell:** ```powershell -.\stop.ps1 # Μόνο αυτό το μονάδα +.\stop.ps1 # Μόνο αυτό το module # Ή -cd ..; .\stop-all.ps1 # Όλες οι μονάδες +cd ..; .\stop-all.ps1 # Όλα τα module ``` -## Στιγμιότυπα οθόνης της εφαρμογής +## Στιγμιότυπα Εφαρμογής -Ακολουθεί η κύρια διεπαφή του module prompt engineering, όπου μπορείτε να πειραματιστείτε με όλα τα οκτώ πρότυπα δίπλα-δίπλα. +Εδώ είναι η κύρια διεπαφή του module μηχανικής προτροπών, όπου μπορείτε να πειραματιστείτε με και τα οκτώ μοτίβα δίπλα-δίπλα. -Κεντρικός Πίνακας Ελέγχου +Αρχική Οθόνη Πίνακα -*Ο κεντρικός πίνακας ελέγχου που δείχνει όλα τα 8 πρότυπα prompt engineering με τα χαρακτηριστικά και τις χρήσεις τους* +*Ο κύριος πίνακας που εμφανίζει και τα 8 μοτίβα μηχανικής προτροπής με τα χαρακτηριστικά και τις χρήσεις τους* -## Εξερευνώντας τα Πρότυπα +## Εξερεύνηση των Μοτίβων -Η διαδικτυακή διεπαφή σας επιτρέπει να πειραματιστείτε με διαφορετικές στρατηγικές prompt. Κάθε πρότυπο λύνει διαφορετικά προβλήματα - δοκιμάστε τα για να δείτε πότε λάμπει η κάθε προσέγγιση. +Η web διεπαφή σας επιτρέπει να πειραματιστείτε με διαφορετικές στρατηγικές προτροπής. Κάθε μοτίβο λύνει διαφορετικά προβλήματα - δοκιμάστε τα για να δείτε πότε λάμπει η κάθε προσέγγιση. -> **Σημείωση: Streaming vs Μη-Streaming** — Κάθε σελίδα προτύπου προσφέρει δύο κουμπιά: **🔴 Stream Response (Live)** και μια επιλογή **Μη-Streaming**. Το streaming χρησιμοποιεί Server-Sent Events (SSE) για να εμφανίζει tokens σε πραγματικό χρόνο καθώς το μοντέλο τα παράγει, οπότε βλέπετε την πρόοδο αμέσως. Η μη-Streaming επιλογή περιμένει ολόκληρη την απάντηση πριν την εμφανίσει. Για prompts που προκαλούν βαθύ συλλογισμό (π.χ. High Eagerness, Self-Reflecting Code), η κλήση μη-Streaming μπορεί να πάρει πολύ χρόνο — μερικές φορές λεπτά — χωρίς ορατή ανατροφοδότηση. **Χρησιμοποιήστε streaming όταν πειραματίζεστε με σύνθετα prompts** ώστε να δείτε το μοντέλο να λειτουργεί και να αποφύγετε την εντύπωση ότι το αίτημα έχει λήξει. +> **Σημείωση: Streaming vs Μη Streaming** — Κάθε σελίδα μοτίβου προσφέρει δύο κουμπιά: **🔴 Stream Response (Live)** και μία επιλογή **Μη-Streaming**. Το streaming χρησιμοποιεί Server-Sent Events (SSE) για να εμφανίζει tokens σε πραγματικό χρόνο καθώς το μοντέλο τα παράγει, ώστε να βλέπετε την πρόοδο αμέσως. Η μη-streaming επιλογή περιμένει ολόκληρη την απάντηση πριν την εμφανίσει. Για προτροπές που απαιτούν βαθύ συλλογισμό (π.χ., High Eagerness, Self-Reflecting Code), η μη-streaming κλήση μπορεί να διαρκέσει πολύ — μερικές φορές λεπτά — χωρίς ορατή ανατροφοδότηση. **Χρησιμοποιήστε streaming όταν πειραματίζεστε με σύνθετες προτροπές** ώστε να βλέπετε το μοντέλο να δουλεύει και να αποφύγετε την εντύπωση ότι η αίτηση έχει λήξει. > -> **Σημείωση: Απαίτηση Περιηγητή** — Η λειτουργία streaming χρησιμοποιεί το Fetch Streams API (`response.body.getReader()`) που απαιτεί πλήρη περιηγητή (Chrome, Edge, Firefox, Safari). Δεν λειτουργεί στον ενσωματωμένο Simple Browser του VS Code, επειδή το webview του δεν υποστηρίζει το API ReadableStream. Αν χρησιμοποιείτε τον Simple Browser, τα κουμπιά μη-Streaming λειτουργούν κανονικά — μόνο τα κουμπιά streaming επηρεάζονται. Ανοίξτε το `http://localhost:8083` σε εξωτερικό περιηγητή για την πλήρη εμπειρία. +> **Σημείωση: Απαιτήσεις Περιηγητή** — Η λειτουργία streaming χρησιμοποιεί το Fetch Streams API (`response.body.getReader()`) που απαιτεί πλήρη περιηγητή (Chrome, Edge, Firefox, Safari). Δεν λειτουργεί στον ενσωματωμένο Simple Browser του VS Code, καθώς το webview του δεν υποστηρίζει το ReadableStream API. Αν χρησιμοποιείτε τον Simple Browser, τα κουμπιά μη-streaming δουλεύουν κανονικά — μόνο τα κουμπιά streaming επηρεάζονται. Ανοίξτε `http://localhost:8083` σε εξωτερικό περιηγητή για την πλήρη εμπειρία. ### Χαμηλή vs Υψηλή Προθυμία -Κάντε μια απλή ερώτηση όπως "Τι είναι το 15% του 200;" χρησιμοποιώντας Χαμηλή Προθυμία. Θα λάβετε άμεση, απευθείας απάντηση. Τώρα ρωτήστε κάτι σύνθετο όπως "Σχεδίασε μια στρατηγική caching για ένα API υψηλής κυκλοφορίας" χρησιμοποιώντας Υψηλή Προθυμία. Πατήστε **🔴 Stream Response (Live)** και παρακολουθήστε τον λεπτομερή συλλογισμό του μοντέλου να εμφανίζεται token-προς-token. Ίδιο μοντέλο, ίδια δομή ερώτησης - αλλά το prompt του λέει πόση σκέψη να κάνει. +Κάντε μια απλή ερώτηση όπως "Ποιο είναι το 15% του 200;" χρησιμοποιώντας Χαμηλή Προθυμία. Θα λάβετε άμεση, απευθείας απάντηση. Τώρα ρωτήστε κάτι σύνθετο όπως "Σχεδίασε μια στρατηγική caching για ένα API με υψηλή επισκεψιμότητα" χρησιμοποιώντας Υψηλή Προθυμία. Κάντε κλικ στο **🔴 Stream Response (Live)** και δείτε τη λεπτομερή συλλογιστική του μοντέλου να εμφανίζεται token-το-token. Ίδιο μοντέλο, ίδια δομή ερώτησης - αλλά η προτροπή του λέει πόσο να σκεφτεί. -### Εκτέλεση Εργασίας (Εισαγωγές Εργαλείων) +### Εκτέλεση Εργασιών (Εισαγωγικά Εργαλείων) -Τα πολυβηματικά workflows ωφελούνται από τον προ-σχεδιασμό και την αφήγηση της προόδου. Το μοντέλο περιγράφει τι θα κάνει, αφηγείται κάθε βήμα και στη συνέχεια συνοψίζει τα αποτελέσματα. +Πολυβηματικές ροές εργασίας ωφελούνται από προμελέτη και αφήγηση προόδου. Το μοντέλο περιγράφει τι θα κάνει, ανακοινώνει κάθε βήμα, έπειτα συνοψίζει τα αποτελέσματα. -### Αυτό-Αναστοχαστικός Κώδικας +### Αυτοαξιολογούμενος Κώδικας -Δοκιμάστε "Δημιουργήστε μια υπηρεσία επικύρωσης email". Αντί απλά να παράγει κώδικα και να σταματά, το μοντέλο παράγει, αξιολογεί με βάση κριτήρια ποιότητας, εντοπίζει αδυναμίες και βελτιώνει. Θα δείτε να επαναλαμβάνει μέχρι ο κώδικας να πληροί τα πρότυπα παραγωγής. +Δοκιμάστε "Δημιούργησε υπηρεσία επαλήθευσης email". Αντί απλά να παράγει κώδικα και να σταματά, το μοντέλο παράγει, αξιολογεί με κριτήρια ποιότητας, εντοπίζει αδυναμίες και βελτιώνει. Θα δείτε να επαναλαμβάνει μέχρι ο κώδικας να πληροί τα πρότυπα παραγωγής. ### Δομημένη Ανάλυση -Οι ανασκοπήσεις κώδικα χρειάζονται σταθερά πλαίσια αξιολόγησης. Το μοντέλο αναλύει τον κώδικα χρησιμοποιώντας σταθερές κατηγορίες (ορθότητα, πρακτικές, απόδοση, ασφάλεια) με επίπεδα σοβαρότητας. +Οι επανεξετάσεις κώδικα απαιτούν σταθερά πλαίσια αξιολόγησης. Το μοντέλο αναλύει κώδικα με προκαθορισμένες κατηγορίες (ορθότητα, πρακτικές, απόδοση, ασφάλεια) με επίπεδα σοβαρότητας. -### Συνομιλία Πολλαπλών Γύρων +### Πολυγλωσσική Συζήτηση -Ρωτήστε "Τι είναι το Spring Boot;" και συνεχίστε αμέσως με "Δείξε μου ένα παράδειγμα". Το μοντέλο θυμάται την πρώτη ερώτηση και σας δίνει συγκεκριμένο παράδειγμα Spring Boot. Χωρίς μνήμη, η δεύτερη ερώτηση θα ήταν πολύ γενική. +Ρωτήστε "Τι είναι το Spring Boot;" και αμέσως συνεχίστε με "Δείξε μου ένα παράδειγμα". Το μοντέλο θυμάται την πρώτη σας ερώτηση και δίνει συγκεκριμένο παράδειγμα Spring Boot. Χωρίς μνήμη, η δεύτερη ερώτηση θα ήταν αόριστη. -### Βήμα-Βήμα Λογισμός +### Συλλογιστική Βήμα-Βήμα -Επιλέξτε ένα μαθηματικό πρόβλημα και δοκιμάστε το με Βήμα-Βήμα Λογισμό και Χαμηλή Προθυμία. Η χαμηλή προθυμία απλώς δίνει την απάντηση - γρήγορα αλλά αδιαφανώς. Το βήμα-βήμα δείχνει κάθε υπολογισμό και απόφαση. +Επιλέξτε ένα μαθηματικό πρόβλημα και δοκιμάστε το τόσο με τη Συλλογιστική Βήμα-Βήμα όσο και με τη Χαμηλή Προθυμία. Η χαμηλή προθυμία δίνει απλώς την απάντηση — γρήγορα αλλά αδιαφανώς. Το βήμα-βήμα σας δείχνει κάθε υπολογισμό και απόφαση. ### Περιορισμένη Έξοδος -Όταν χρειάζεστε συγκεκριμένες μορφές ή αριθμό λέξεων, αυτό το πρότυπο επιβάλλει αυστηρή συμμόρφωση. Δοκιμάστε να δημιουργήσετε μια περίληψη με ακριβώς 100 λέξεις σε μορφή κουκίδων. +Όταν χρειάζεστε συγκεκριμένες μορφές ή αριθμό λέξεων, αυτό το μοτίβο επιβάλλει αυστηρή συμμόρφωση. Δοκιμάστε να δημιουργήσετε μια περίληψη με ακριβώς 100 λέξεις σε μορφή κουκκίδων. -## Τι Μαθαίνετε Πραγματικά +## Τι Μάθετε Πραγματικά -**Η Προσπάθεια Λογισμού Αλλάζει Τα Πάντα** +**Η Προσπάθεια Συλλογισμού Αλλάζει τα Πάντα** -Το GPT-5.2 σας επιτρέπει να ελέγξετε την υπολογιστική προσπάθεια μέσω των prompts σας. Η χαμηλή προσπάθεια σημαίνει γρήγορες απαντήσεις με ελάχιστη εξερεύνηση. Η υψηλή προσπάθεια σημαίνει ότι το μοντέλο παίρνει χρόνο να σκεφτεί βαθιά. Μαθαίνετε να ταιριάζετε την προσπάθεια με την πολυπλοκότητα του έργου - μη σπαταλάτε χρόνο σε απλές ερωτήσεις αλλά μη βιάζεστε σε σύνθετες αποφάσεις. +Το GPT-5.2 σας επιτρέπει να ελέγχετε τον υπολογιστικό κόπο μέσω των προτροπών σας. Η χαμηλή προσπάθεια σημαίνει γρήγορες απαντήσεις με ελάχιστη διερεύνηση. Η υψηλή προσπάθεια σημαίνει ότι το μοντέλο αφιερώνει χρόνο σε βαθύ συλλογισμό. Μαθαίνετε να ταιριάζετε την προσπάθεια με την πολυπλοκότητα της εργασίας — μην χάνετε χρόνο σε απλές ερωτήσεις, αλλά μην βιάζεστε να πάρετε αποφάσεις σε σύνθετα ζητήματα. **Η Δομή Καθοδηγεί τη Συμπεριφορά** -Παρατηρήστε τις ετικέτες XML στα prompts; Δεν είναι διακοσμητικές. Τα μοντέλα ακολουθούν δομημένες οδηγίες πιο αξιόπιστα από ελεύθερο κείμενο. Όταν χρειάζεστε πολυ-βηματικές διαδικασίες ή σύνθετη λογική, η δομή βοηθά το μοντέλο να καταλάβει πού βρίσκεται και τι ακολουθεί. Το παρακάτω διάγραμμα αναλύει ένα καλά δομημένο prompt, δείχνοντας πώς ετικέτες όπως ``, ``, ``, ``, και `` οργανώνουν τις οδηγίες σας σε σαφή τμήματα. +Παρατηρήσατε τις ετικέτες XML στις προτροπές; Δεν είναι διακοσμητικές. Τα μοντέλα ακολουθούν δομημένες οδηγίες πιο αξιόπιστα απ’ ό,τι ελεύθερο κείμενο. Όταν χρειάζεστε πολύβημες διαδικασίες ή πολύπλοκη λογική, η δομή βοηθά το μοντέλο να παρακολουθεί πού βρίσκεται και τι ακολουθεί. Το παρακάτω διάγραμμα διασπά μια καλά δομημένη προτροπή, δείχνοντας πώς οι ετικέτες όπως ``, ``, ``, ``, και `` οργανώνουν τις οδηγίες σας σε σαφείς ενότητες. -Δομή Prompt +Δομή Προτροπής -*Ανατομία ενός καλά δομημένου prompt με σαφή τμήματα και οργάνωση τύπου XML* +*Ανατομία μιας καλά δομημένης προτροπής με σαφείς ενότητες και δομή τύπου XML* -**Ποιότητα Μέσω Αυτο-Αξιολόγησης** +**Ποιότητα Μέσω Αυτοαξιολόγησης** -Τα αυτο-αναστοχαστικά πρότυπα δουλεύουν κάνοντας ρητά τα κριτήρια ποιότητας. Αντί να ελπίζετε ότι το μοντέλο "το κάνει σωστά", του λέτε ακριβώς τι σημαίνει "σωστά": ορθή λογική, χειρισμός σφαλμάτων, απόδοση, ασφάλεια. Το μοντέλο μπορεί τότε να αξιολογήσει τη δική του έξοδο και να βελτιωθεί. Αυτό μετατρέπει τη δημιουργία κώδικα από λαχείο σε διαδικασία. +Τα μοτίβα αυτοαξιολόγησης δουλεύουν κάνοντας ρητά τα κριτήρια ποιότητας. Αντί να ελπίζετε ότι το μοντέλο "το κάνει σωστά", του λέτε ακριβώς τι σημαίνει "σωστά": σωστή λογική, διαχείριση σφαλμάτων, απόδοση, ασφάλεια. Έπειτα το μοντέλο μπορεί να αξιολογήσει τη δική του έξοδο και να βελτιωθεί. Αυτό μετατρέπει τη δημιουργία κώδικα από λαχείο σε διαδικασία. -**Το Περιεχόμενο Είναι Πεπερασμένο** +**Το Πλαίσιο Είναι Πεπερασμένο** -Οι συνομιλίες πολλαπλών γύρων δουλεύουν με το να περιλαμβάνουν το ιστορικό μηνυμάτων σε κάθε αίτηση. Αλλά υπάρχει όριο - κάθε μοντέλο έχει μέγιστο αριθμό tokens. Καθώς οι συνομιλίες μεγαλώνουν, θα χρειαστείτε στρατηγικές για να κρατάτε σχετικό το περιεχόμενο χωρίς να χτυπάτε το όριο. Αυτό το module σας δείχνει πώς λειτουργεί η μνήμη· αργότερα θα μάθετε πότε να συνοψίζετε, πότε να ξεχνάτε και πότε να ανακτάτε. +Οι πολυγλωσσικές συνομιλίες λειτουργούν συμπεριλαμβάνοντας το ιστορικό μηνυμάτων με κάθε αίτηση. Αλλά υπάρχει όριο - κάθε μοντέλο έχει μέγιστο αριθμό tokens. Καθώς οι συνομιλίες μεγαλώνουν, θα χρειαστείτε στρατηγικές για να διατηρείτε σχετικό πλαίσιο χωρίς να υπερβαίνετε το όριο. Αυτό το module σας δείχνει πώς λειτουργεί η μνήμη· αργότερα θα μάθετε πότε να συνοψίζετε, πότε να ξεχνάτε και πότε να ανακτάτε. ## Επόμενα Βήματα -**Επόμενο Module:** [03-rag - RAG (Ανάκτηση-Ενισχυμένη Γενιά)](../03-rag/README.md) +**Επόμενο Module:** [03-rag - RAG (Αναζήτηση Αυξημένη Γεννήτρια)](../03-rag/README.md) --- -**Πλοήγηση:** [← Προηγούμενο: Module 01 - Εισαγωγή](../01-introduction/README.md) | [Πίσω στην Αρχική](../README.md) | [Επόμενο: Module 03 - RAG →](../03-rag/README.md) +**Πλοήγηση:** [← Προηγούμενο: Module 01 - Εισαγωγή](../01-introduction/README.md) | [Επιστροφή στην Αρχική](../README.md) | [Επόμενο: Module 03 - RAG →](../03-rag/README.md) --- -**Αποποίηση ευθυνών**: -Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που επιδιώκουμε ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις μπορεί να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη γλώσσα του θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική μετάφραση από ανθρώπινο μεταφραστή. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. +**Αποποίηση ευθυνών**: +Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. \ No newline at end of file diff --git a/translations/el/03-rag/README.md b/translations/el/03-rag/README.md index 9d816c587..56d724a12 100644 --- a/translations/el/03-rag/README.md +++ b/translations/el/03-rag/README.md @@ -1,144 +1,143 @@ -# Module 03: RAG (Ανάκτηση-Ενισχυμένη Γεννήτρια) +# Module 03: RAG (Γενετική με Ενισχυμένη Ανάκτηση) -## Περιεχόμενα +## Table of Contents -- [Βίντεο Παρουσίασης](../../../03-rag) -- [Τι Θα Μάθετε](../../../03-rag) -- [Προαπαιτούμενα](../../../03-rag) -- [Κατανόηση του RAG](../../../03-rag) - - [Ποια Προσέγγιση RAG Χρησιμοποιεί Αυτό το Σεμινάριο;](../../../03-rag) -- [Πώς Λειτουργεί](../../../03-rag) - - [Επεξεργασία Εγγράφων](../../../03-rag) - - [Δημιουργία Ενσωματώσεων](../../../03-rag) - - [Σημασιολογική Αναζήτηση](../../../03-rag) - - [Δημιουργία Απαντήσεων](../../../03-rag) -- [Εκτέλεση της Εφαρμογής](../../../03-rag) -- [Χρήση της Εφαρμογής](../../../03-rag) - - [Ανέβασμα Εγγράφου](../../../03-rag) - - [Κάντε Ερωτήσεις](../../../03-rag) - - [Έλεγχος Πηγών Αναφορών](../../../03-rag) - - [Πειραματισμός με Ερωτήσεις](../../../03-rag) -- [Βασικές Έννοιες](../../../03-rag) - - [Στρατηγική Τμηματοποίησης](../../../03-rag) - - [Βαθμολογίες Ομοιότητας](../../../03-rag) - - [Αποθήκευση Μνήμης](../../../03-rag) - - [Διαχείριση Παραθύρου Πλαισίου](../../../03-rag) -- [Πότε το RAG Είναι Σημαντικό](../../../03-rag) -- [Επόμενα Βήματα](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding RAG](#understanding-rag) + - [Which RAG Approach Does This Tutorial Use?](#which-rag-approach-does-this-tutorial-use) +- [How It Works](#how-it-works) + - [Document Processing](#document-processing) + - [Creating Embeddings](#creating-embeddings) + - [Semantic Search](#semantic-search) + - [Answer Generation](#δημιουργία-απάντησης) +- [Run the Application](#εκτέλεση-της-εφαρμογής) +- [Using the Application](#χρήση-της-εφαρμογής) + - [Upload a Document](#ανέβασμα-εγγράφου) + - [Ask Questions](#κάντε-ερωτήσεις) + - [Check Source References](#ελέγξτε-τις-πηγές-αναφορών) + - [Experiment with Questions](#πειραματιστείτε-με-ερωτήσεις) +- [Key Concepts](#κύριες-έννοιες) + - [Chunking Strategy](#στρατηγική-τμηματοποίησης) + - [Similarity Scores](#βαθμολογίες-ομοιότητας) + - [In-Memory Storage](#αποθήκευση-στο-μνήμης) + - [Context Window Management](#διαχείριση-παραθύρου-πλαισίου) +- [When RAG Matters](#πότε-έχει-σημασία-η-rag) +- [Next Steps](#επόμενα-βήματα) -## Βίντεο Παρουσίασης +## Video Walkthrough -Παρακολουθήστε αυτήν τη ζωντανή συνεδρίαση που εξηγεί πώς να ξεκινήσετε με αυτό το module: +Παρακολουθήστε αυτήν τη ζωντανή παρουσίαση που εξηγεί πώς να ξεκινήσετε με αυτό το module: -RAG με LangChain4j - Ζωντανή Συνεδρία +RAG with LangChain4j - Live Session -## Τι Θα Μάθετε +## What You'll Learn -Στα προηγούμενα modules, μάθατε πώς να κάνετε συνομιλίες με το AI και να δομείτε αποτελεσματικά τις εντολές σας. Αλλά υπάρχει ένας θεμελιώδης περιορισμός: τα μοντέλα γλώσσας γνωρίζουν μόνο όσα έμαθαν κατά τη διάρκεια της εκπαίδευσής τους. Δεν μπορούν να απαντήσουν σε ερωτήσεις σχετικά με τις πολιτικές της εταιρείας σας, την τεκμηρίωση του έργου σας ή οποιεσδήποτε πληροφορίες δεν εκπαιδεύτηκαν. +Στα προηγούμενα modules, μάθατε πώς να έχετε συνομιλίες με ΤΝ και να δομείτε αποτελεσματικά τις ερωτήσεις σας. Αλλά υπάρχει ένας θεμελιώδης περιορισμός: τα γλωσσικά μοντέλα γνωρίζουν μόνο ό,τι έχουν μάθει κατά την εκπαίδευση. Δεν μπορούν να απαντήσουν σε ερωτήσεις σχετικά με τις πολιτικές της εταιρείας σας, την τεκμηρίωση του έργου σας ή οποιαδήποτε πληροφορία δεν έχουν εκπαιδευτεί. -Το RAG (Ανάκτηση-Ενισχυμένη Γεννήτρια) λύνει αυτό το πρόβλημα. Αντί να προσπαθείτε να διδάξετε στο μοντέλο τις πληροφορίες σας (το οποίο είναι ακριβό και μη πρακτικό), του δίνετε τη δυνατότητα να αναζητά μέσα στα έγγραφά σας. Όταν κάποιος θέτει μια ερώτηση, το σύστημα βρίσκει σχετικές πληροφορίες και τις συμπεριλαμβάνει στην εντολή. Το μοντέλο απαντάει βάσει αυτού του ανακτημένου πλαισίου. +Το RAG (Γενετική με Ενισχυμένη Ανάκτηση) λύνει αυτό το πρόβλημα. Αντί να προσπαθείτε να διδάξετε στο μοντέλο τις πληροφορίες σας (που είναι ακριβό και ανέφικτο), του δίνετε τη δυνατότητα να αναζητήσει τα έγγραφά σας. Όταν κάποιος κάνει μια ερώτηση, το σύστημα βρίσκει σχετικές πληροφορίες και τις ενσωματώνει στο prompt. Το μοντέλο απαντά βάσει αυτού του ανακτημένου πλαισίου. -Σκεφτείτε το RAG σαν να δίνετε στο μοντέλο μια βιβλιοθήκη αναφορών. Όταν κάνετε μια ερώτηση, το σύστημα: +Σκεφτείτε το RAG σαν να δίνετε στο μοντέλο μια βιβλιοθήκη αναφοράς. Όταν κάνετε μια ερώτηση, το σύστημα: -1. **Ερώτηση Χρήστη** - Κάνετε μια ερώτηση -2. **Ενσωμάτωση** - Μετατρέπει την ερώτησή σας σε διάνυσμα -3. **Αναζήτηση Διανύσματος** - Βρίσκει παρόμοια τμήματα εγγράφων -4. **Συναρμολόγηση Πλαισίου** - Προσθέτει σχετικά τμήματα στην εντολή -5. **Απάντηση** - Το LLM παράγει απάντηση βάσει του πλαισίου +1. **Ερώτηση Χρήστη** - Κάνετε μια ερώτηση +2. **Ενσωμάτωση** - Μετατρέπει την ερώτησή σας σε διάνυσμα +3. **Αναζήτηση Διανυσμάτων** - Βρίσκει παρόμοια τμήματα εγγράφων +4. **Σύνθεση Πλαισίου** - Προσθέτει σχετικά τμήματα στο prompt +5. **Απάντηση** - Το LLM παράγει απάντηση βάσει του πλαισίου -Αυτό στηρίζει τις απαντήσεις του μοντέλου στα πραγματικά σας δεδομένα αντί να βασίζεται μόνο στη γνώση της εκπαίδευσης ή να επινοεί απαντήσεις. +Αυτό στηρίζει τις απαντήσεις του μοντέλου στα πραγματικά σας δεδομένα αντί να βασίζεται μόνο στη γνώση εκπαίδευσής του ή να εφεύρει απαντήσεις. -## Προαπαιτούμενα +## Prerequisites -- Ολοκληρωμένο [Module 00 - Γρήγορη Εκκίνηση](../00-quick-start/README.md) (για το παράδειγμα Easy RAG που αναφέρεται αργότερα σε αυτό το module) -- Ολοκληρωμένο [Module 01 - Εισαγωγή](../01-introduction/README.md) (πόροι Azure OpenAI αναπτυγμένοι, συμπεριλαμβανομένου του μοντέλου ενσωμάτωσης `text-embedding-3-small`) -- Αρχείο `.env` στον ριζικό φάκελο με διαπιστευτήρια Azure (δημιουργημένο από την εντολή `azd up` στο Module 01) +- Ολοκληρωμένο [Module 01 - Εισαγωγή](../01-introduction/README.md) (αναπτύχθηκαν πόροι Azure OpenAI, συμπεριλαμβανομένου του μοντέλου ενσωμάτωσης `text-embedding-3-small`) +- Αρχείο `.env` στον ριζικό φάκελο με στοιχεία Azure (δημιουργημένο από `azd up` στο Module 01) -> **Σημείωση:** Αν δεν έχετε ολοκληρώσει το Module 01, ακολουθήστε πρώτα τις οδηγίες ανάπτυξης εκεί. Η εντολή `azd up` αναπτύσσει τόσο το μοντέλο συνομιλίας GPT όσο και το μοντέλο ενσωμάτωσης που χρησιμοποιεί αυτό το module. +> **Σημείωση:** Εάν δεν έχετε ολοκληρώσει το Module 01, ακολουθήστε πρώτα τις οδηγίες ανάπτυξης εκεί. Η εντολή `azd up` αναπτύσσει τόσο το μοντέλο chat GPT όσο και το μοντέλο ενσωμάτωσης που χρησιμοποιείται σε αυτό το module. -## Κατανόηση του RAG +## Understanding RAG -Το παρακάτω διάγραμμα απεικονίζει την βασική ιδέα: αντί να βασίζεται μόνο στα δεδομένα εκπαίδευσης του μοντέλου, το RAG του παρέχει μια βιβλιοθήκη αναφοράς από τα έγγραφά σας για συμβουλευτικό έλεγχο πριν από την παραγωγή κάθε απάντησης. +Το παρακάτω διάγραμμα δείχνει τον βασικό πυρήνα: αντί να βασίζεται μόνο στα δεδομένα εκπαίδευσης του μοντέλου, το RAG του παρέχει μια βιβλιοθήκη αναφοράς των εγγράφων σας για να συμβουλευτεί πριν δημιουργήσει κάθε απάντηση. Τι είναι το RAG -*Αυτό το διάγραμμα δείχνει τη διαφορά μεταξύ ενός τυπικού LLM (που μαντεύει από τα δεδομένα εκπαίδευσης) και ενός LLM ενισχυμένου με RAG (που συμβουλεύεται πρώτα τα έγγραφά σας).* +*Αυτό το διάγραμμα δείχνει τη διαφορά μεταξύ ενός τυπικού LLM (που μαντεύει από τα δεδομένα εκπαίδευσης) και ενός LLM με ενίσχυση RAG (που συμβουλεύεται πρώτα τα έγγραφά σας).* -Δείτε πώς συνδέονται τα μέρη από άκρη σε άκρη. Η ερώτηση ενός χρήστη περνά μέσα από τέσσερα στάδια — ενσωμάτωση, αναζήτηση διανύσματος, συναρμολόγηση πλαισίου, και δημιουργία απάντησης — καθένα χτίζοντας πάνω στο προηγούμενο: +Ορίστε πώς συνδέονται όλα τα κομμάτια από άκρη σε άκρη. Η ερώτηση ενός χρήστη περνά μέσα από τέσσερα στάδια — ενσωμάτωση, αναζήτηση διανυσμάτων, σύνθεση πλαισίου και παραγωγή απάντησης — το καθένα βασισμένο στο προηγούμενο: Αρχιτεκτονική RAG -*Αυτό το διάγραμμα δείχνει την ολοκληρωμένη ροή RAG — μια ερώτηση χρήστη περνά μέσα από ενσωμάτωση, αναζήτηση διανύσματος, συναρμολόγηση πλαισίου, και παραγωγή απάντησης.* +*Αυτό το διάγραμμα δείχνει τη ροή RAG από άκρη σε άκρη — μια ερώτηση χρήστη περνά μέσα από ενσωμάτωση, αναζήτηση διανυσμάτων, σύνθεση πλαισίου και παραγωγή απάντησης.* -Το υπόλοιπο αυτού του module εξηγεί κάθε στάδιο λεπτομερώς, με κώδικα τον οποίο μπορείτε να εκτελέσετε και να τροποποιήσετε. +Το υπόλοιπο του module περνά αναλυτικά από κάθε στάδιο, με κώδικα που μπορείτε να τρέξετε και να τροποποιήσετε. -### Ποια Προσέγγιση RAG Χρησιμοποιεί Αυτό το Σεμινάριο; +### Which RAG Approach Does This Tutorial Use? -Το LangChain4j προσφέρει τρεις τρόπους για να υλοποιήσετε το RAG, κάθε ένας με διαφορετικό επίπεδο αφαίρεσης. Το παρακάτω διάγραμμα τα συγκρίνει πλάι-πλάι: +Το LangChain4j προσφέρει τρεις τρόπους υλοποίησης του RAG, ο καθένας με διαφορετικό επίπεδο αφαίρεσης. Το παρακάτω διάγραμμα τους συγκρίνει δίπλα-δίπλα: Τρεις Προσεγγίσεις RAG στο LangChain4j -*Αυτό το διάγραμμα συγκρίνει τις τρεις προσεγγίσεις RAG του LangChain4j — Easy, Native, και Advanced — δείχνοντας τα βασικά τους συστατικά και πότε να χρησιμοποιήσετε κάθε μία.* +*Αυτό το διάγραμμα συγκρίνει τις τρεις προσεγγίσεις RAG του LangChain4j — Easy, Native, και Advanced — δείχνοντας τα βασικά τους στοιχεία και πότε να χρησιμοποιεί κανείς καθεμία.* -| Προσέγγιση | Τι Κάνει | Αντισταθμιστικό Όφελος | +| Προσέγγιση | Τι Κάνει | Ανταλλαγή | |---|---|---| -| **Easy RAG** | Συνδέει τα πάντα αυτόματα μέσω `AiServices` και `ContentRetriever`. Αντιστοιχίζετε ένα interface, προσθέτετε έναν retriever, και το LangChain4j αναλαμβάνει την ενσωμάτωση, αναζήτηση και σύνθεση εντολών κρυφά. | Ελάχιστος κώδικας, αλλά δεν βλέπετε τι συμβαίνει σε κάθε βήμα. | -| **Native RAG** | Καλείτε εσείς το μοντέλο ενσωμάτωσης, αναζητάτε στην αποθήκη, φτιάχνετε την εντολή και παράγετε την απάντηση — βήμα-βήμα και ρητά. | Περισσότερος κώδικας, αλλά κάθε στάδιο είναι ορατό και τροποποιήσιμο. | -| **Advanced RAG** | Χρησιμοποιεί το πλαίσιο `RetrievalAugmentor` με pluggable μετασχηματιστές ερωτήσεων, δρομολογητές, επαναταξινομητές και ενισχυτές περιεχομένου για παραγωγικές ροές εργασίας. | Μέγιστη ευελιξία, αλλά σημαντικά περισσότερη πολυπλοκότητα. | +| **Easy RAG** | Συνδέει τα πάντα αυτόματα μέσω `AiServices` και `ContentRetriever`. Σημειώνετε ένα interface, συνδέετε έναν retriever, και το LangChain4j διαχειρίζεται την ενσωμάτωση, αναζήτηση και σύνθεση prompt πίσω από τις σκηνές. | Ελάχιστος κώδικας, αλλά δεν βλέπετε τι συμβαίνει σε κάθε βήμα. | +| **Native RAG** | Καλείτε το μοντέλο ενσωμάτωσης, ψάχνετε στην αποθήκη, φτιάχνετε το prompt και παράγετε την απάντηση μόνοι σας — ένα ρητό βήμα τη φορά. | Περισσότερος κώδικας, αλλά κάθε στάδιο είναι ορατό και τροποποιήσιμο. | +| **Advanced RAG** | Χρησιμοποιεί το πλαίσιο `RetrievalAugmentor` με ρυθμιζόμενους μετατροπείς ερωτήσεων, διανομείς, επαναταξινομητές και ενσωματωτές περιεχομένου για παραγωγικές ροές. | Μέγιστη ευελιξία, αλλά σημαντικά μεγαλύτερη πολυπλοκότητα. | -**Αυτό το σεμινάριο χρησιμοποιεί την Native προσέγγιση.** Κάθε βήμα της ροής RAG — ενσωμάτωση της ερώτησης, αναζήτηση στην αποθήκη διανυσμάτων, συναρμολόγηση πλαισίου και παραγωγή απάντησης — είναι γραμμένο ρητά στο [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Αυτό είναι εκ προθέσεως: ως εκπαιδευτικό υλικό, είναι πιο σημαντικό να βλέπετε και να κατανοείτε κάθε στάδιο παρά να ελαχιστοποιείται ο κώδικας. Μόλις νιώσετε άνετα με το πώς τα μέρη συνδέονται, μπορείτε να προχωρήσετε στο Easy RAG για γρήγορα πρωτότυπα ή στο Advanced RAG για παραγωγικά συστήματα. +**Αυτό το tutorial χρησιμοποιεί την προσέγγιση Native.** Κάθε βήμα της ροής RAG — ενσωμάτωση της ερώτησης, αναζήτηση στη βάση διανυσμάτων, σύνθεση του πλαισίου και παραγωγή απάντησης — γράφεται ρητά στο [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Αυτό είναι σκόπιμο: ως εκπαιδευτικό υλικό, είναι πιο σημαντικό να βλέπετε και να κατανοείτε κάθε στάδιο παρά να ελαχιστοποιείται ο κώδικας. Μόλις νιώσετε άνετα με τη λειτουργία των κομματιών, μπορείτε να περάσετε σε Easy RAG για γρήγορα πρωτότυπα ή Advanced RAG για συστήματα παραγωγής. -> **💡 Έχετε ήδη δει το Easy RAG σε δράση;** Το [Quick Start module](../00-quick-start/README.md) περιλαμβάνει ένα παράδειγμα ερωταπαντήσεων εγγράφων ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) που χρησιμοποιεί το Easy RAG — το LangChain4j αναλαμβάνει ενσωμάτωση, αναζήτηση και σύνθεση εντολών αυτόματα. Αυτό το module προχωρά ένα βήμα παραπέρα, ανοίγοντας αυτή τη ροή ώστε να βλέπετε και να ελέγχετε κάθε στάδιο εσείς οι ίδιοι. +> **💡 Σας ενδιαφέρει το Easy RAG;** Το LangChain4j προσφέρει επίσης μια *Easy RAG* προσέγγιση όπου τα `AiServices` και ένας `ContentRetriever` διαχειρίζονται αυτόματα την ενσωμάτωση, την αναζήτηση και τη σύνθεση του prompt. Αυτό το module ακολουθεί μια πιο ρητή διαδρομή — σπάνε το σωλήνωση ώστε να βλέπετε και να ελέγχετε κάθε στάδιο μόνοι σας. -Το παρακάτω διάγραμμα δείχνει τη ροή Easy RAG από το παράδειγμα Quick Start. Παρατηρήστε πώς τα `AiServices` και `EmbeddingStoreContentRetriever` κρύβουν όλη την πολυπλοκότητα — φορτώνετε ένα έγγραφο, προσθέτετε έναν retriever, και παίρνετε απαντήσεις. Η Native προσέγγιση σε αυτό το module ανοίγει όλα εκείνα τα κρυφά βήματα: +Το παρακάτω διάγραμμα δείχνει τη ροή Easy RAG. Παρατηρήστε πώς τα `AiServices` και `EmbeddingStoreContentRetriever` κρύβουν όλη την πολυπλοκότητα — φορτώνετε ένα έγγραφο, προσθέτετε έναν retriever και παίρνετε απαντήσεις. Η Native προσέγγιση σε αυτό το module ανοίγει κάθε κρυμμένο βήμα: Ροή Easy RAG - LangChain4j -*Αυτό το διάγραμμα δείχνει τη ροή Easy RAG από το `SimpleReaderDemo.java`. Συγκρίνετέ το με την Native προσέγγιση που χρησιμοποιείται σε αυτό το module: το Easy RAG κρύβει την ενσωμάτωση, την ανάκτηση και τη σύνθεση εντολών πίσω από τα `AiServices` και `ContentRetriever` — φορτώνετε ένα έγγραφο, προσθέτετε retriever, και λαμβάνετε απαντήσεις. Η Native προσέγγιση εδώ ανοίγει αυτή τη ροή ώστε να καλείτε κάθε στάδιο (ενσωμάτωση, αναζήτηση, συναρμολόγηση πλαισίου, παραγωγή) μόνοι σας, δίνοντάς σας πλήρη ορατότητα και έλεγχο.* +*Αυτό το διάγραμμα δείχνει τη ροή Easy RAG. Συγκρίνετε το με την Native προσέγγιση που χρησιμοποιείται σε αυτό το module: το Easy RAG κρύβει την ενσωμάτωση, την ανάκτηση και τη σύνθεση του prompt πίσω από τα `AiServices` και `ContentRetriever` — φόρτωνετε έγγραφο, προσθέτετε retriever και λαμβάνετε απαντήσεις. Η Native προσέγγιση σε αυτό το module ανοίγει τη ροή ώστε να καλείτε εσείς κάθε στάδιο (ενσωμάτωση, αναζήτηση, σύνθεση πλαισίου, παραγωγή) μόνοι σας, δίνοντάς σας πλήρη ορατότητα και έλεγχο.* -## Πώς Λειτουργεί +## How It Works -Η ροή RAG σε αυτό το module χωρίζεται σε τέσσερα στάδια που εκτελούνται διαδοχικά κάθε φορά που ένας χρήστης θέτει μια ερώτηση. Πρώτα, ένα ανεβασμένο έγγραφο **αναλύεται και διαχωρίζεται σε τμήματα** εύχρηστου μεγέθους. Αυτά τα τμήματα στη συνέχεια μετατρέπονται σε **ενσωματώσεις διανυσμάτων** και αποθηκεύονται ώστε να μπορούν να συσχετιστούν μαθηματικά. Όταν έρχεται μια ερώτηση, το σύστημα πραγματοποιεί μια **σημασιολογική αναζήτηση** για να βρει τα πιο σχετικά τμήματα και τελικά τα περνά ως πλαίσιο στο LLM για **παραγωγή απάντησης**. Οι παρακάτω ενότητες εξετάζουν κάθε στάδιο με τον πραγματικό κώδικα και διαγράμματα. Ας δούμε το πρώτο βήμα. +Η ροή RAG σε αυτό το module διασπάται σε τέσσερα στάδια που εκτελούνται διαδοχικά κάθε φορά που ένας χρήστης κάνει ερώτηση. Πρώτα, το ανέβασμα ενός εγγράφου **αναλύεται και χωρίζεται σε τμήματα** που είναι εύκολα στη διαχείριση. Αυτά τα τμήματα μετατρέπονται σε **ενσωματώσεις διανυσμάτων** και αποθηκεύονται ώστε να μπορούν να συγκριθούν μαθηματικά. Όταν φτάνει μια ερώτηση, το σύστημα εκτελεί μια **σημασιολογική αναζήτηση** για να βρει τα πιο σχετικά τμήματα και τελικά τα περνά ως πλαίσιο στο LLM για **παραγωγή απάντησης**. Οι ακόλουθες ενότητες αναλύουν κάθε στάδιο με πραγματικό κώδικα και διαγράμματα. Ας δούμε το πρώτο βήμα. -### Επεξεργασία Εγγράφων +### Document Processing [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Όταν ανεβάζετε ένα έγγραφο, το σύστημα το αναλύει (PDF ή απλό κείμενο), προσθέτει μεταδεδομένα όπως το όνομα αρχείου, και στη συνέχεια το χωρίζει σε τμήματα — μικρότερα κομμάτια που χωρούν άνετα στο πλαίσιο του μοντέλου. Αυτά τα τμήματα επικαλύπτονται ελαφρώς ώστε να μην χάνεται το πλαίσιο στα όρια. +Όταν ανεβάζετε ένα έγγραφο, το σύστημα το αναλύει (PDF ή απλό κείμενο), συνδέει μεταδεδομένα όπως το όνομα αρχείου και στη συνέχεια το χωρίζει σε τμήματα — μικρότερα κομμάτια που χωράνε άνετα στο παράθυρο πλαισίου του μοντέλου. Αυτά τα τμήματα επικαλύπτονται ελαφρώς ώστε να μην χάνεται πλαίσιο στα όρια. ```java -// Αναλύστε το ανεβασμένο αρχείο και τυλίξτε το σε ένα Έγγραφο LangChain4j +// Αναλύστε το ανεβασμένο αρχείο και τυλίξτε το σε ένα έγγραφο LangChain4j Document document = Document.from(content, metadata); -// Χωρίστε σε κομμάτια των 300 τοκεν με επικάλυψη 30 τοκεν +// Διαχωρίστε σε κομμάτια των 300 συμβόλων με επικάλυψη 30 συμβόλων DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` + +Το παρακάτω διάγραμμα δείχνει πώς λειτουργεί αυτό οπτικά. Παρατηρήστε πώς κάθε τμήμα μοιράζεται κάποιους tokens με τους γείτονές του — η επικάλυψη 30 tokens διασφαλίζει ότι κανένα σημαντικό πλαίσιο δεν χάνεται ανάμεσα: -Το παρακάτω διάγραμμα δείχνει πώς δουλεύει αυτό οπτικά. Παρατηρήστε πώς κάθε τμήμα μοιράζεται μερικά tokens με τα γειτονικά του — η επικάλυψη 30 token διασφαλίζει ότι δεν χάνεται σημαντικό πλαίσιο ανάμεσα στα κομμάτια: +Χωρισμός Εγγράφου σε Τμήματα -Τμηματοποίηση Εγγράφων +*Αυτό το διάγραμμα δείχνει ένα έγγραφο να χωρίζεται σε τμήματα των 300 tokens με επικάλυψη 30 tokens, διατηρώντας το πλαίσιο στα όρια των τμημάτων.* -*Αυτό το διάγραμμα δείχνει ένα έγγραφο που χωρίζεται σε τμήματα των 300 token με επικάλυψη 30 token, διατηρώντας το πλαίσιο στα όρια των τμημάτων.* +> **🤖 Δοκιμάστε με το [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) και ρωτήστε: +> - "Πώς χωρίζει το LangChain4j τα έγγραφα σε τμήματα και γιατί είναι σημαντική η επικάλυψη;" +> - "Ποιο είναι το βέλτιστο μέγεθος τμήματος για διαφορετικούς τύπους εγγράφων και γιατί;" +> - "Πώς διαχειρίζομαι έγγραφα σε πολλές γλώσσες ή με ειδική μορφοποίηση;" -> **🤖 Δοκιμάστε με το [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) και ρωτήστε: -> - "Πώς χωρίζει το LangChain4j τα έγγραφα σε τμήματα και γιατί η επικάλυψη είναι σημαντική;" -> - "Ποιο είναι το βέλτιστο μέγεθος τμήματος για διαφορετικούς τύπους εγγράφων και γιατί;" -> - "Πώς χειρίζομαι έγγραφα σε πολλές γλώσσες ή με ειδική μορφοποίηση;" - -### Δημιουργία Ενσωματώσεων +### Creating Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Κάθε τμήμα μετατρέπεται σε έναν αριθμητικό αναπαριστώντας, που ονομάζεται ενσωμάτωση — ουσιαστικά ένας μετατροπέας από νόημα σε αριθμούς. Το μοντέλο ενσωμάτωσης δεν είναι "έξυπνο" όπως ένα μοντέλο συνομιλίας· δεν μπορεί να ακολουθεί εντολές, να συλλογίζεται ή να απαντά σε ερωτήσεις. Αυτό που κάνει είναι να χαρτογραφεί το κείμενο σε έναν μαθηματικό χώρο όπου παρόμοια νοήματα βρίσκονται κοντά το ένα στο άλλο — "αυτοκίνητο" κοντά σε "όχημα", "πολιτική επιστροφής" κοντά σε "επιστροφή χρημάτων". Σκεφτείτε το μοντέλο συνομιλίας ως ένα άτομο με το οποίο μπορείτε να μιλήσετε· το μοντέλο ενσωμάτωσης είναι ένα εξαιρετικό σύστημα αρχειοθέτησης. +Κάθε τμήμα μετατρέπεται σε μια αριθμητική αναπαράσταση που ονομάζεται ενσωμάτωση — ουσιαστικά ένας μετατροπέας νοήματος σε αριθμούς. Το μοντέλο ενσωμάτωσης δεν είναι "έξυπνο" όπως ένα μοντέλο chat· δεν μπορεί να ακολουθεί οδηγίες, να λογικοποιεί ή να απαντά σε ερωτήσεις. Αυτό που κάνει είναι να χαρτογραφεί το κείμενο σε έναν μαθηματικό χώρο όπου παρόμοια νοήματα βρίσκονται κοντά — "αυτοκίνητο" κοντά σε "όχημα," "πολιτική επιστροφών" κοντά σε "επιστροφή χρημάτων." Σκεφτείτε ένα μοντέλο chat ως άτομο με το οποίο μπορείτε να μιλήσετε· ένα μοντέλο ενσωμάτωσης είναι ένα εξαιρετικό σύστημα αρχειοθέτησης. -Το παρακάτω διάγραμμα οπτικοποιεί αυτή την ιδέα — το κείμενο μπαίνει, βγαίνουν αριθμητικά διανύσματα, και παρόμοια νοήματα τοποθετούνται κοντά: +Το παρακάτω διάγραμμα απεικονίζει αυτήν την έννοια — το κείμενο μπαίνει, βγαίνουν αριθμητικά διανύσματα, και παρόμοια νοήματα παράγουν κοντινά διανύσματα: Έννοια Μοντέλου Ενσωμάτωσης -*Αυτό το διάγραμμα δείχνει πώς ένα μοντέλο ενσωμάτωσης μετατρέπει το κείμενο σε αριθμητικά διανύσματα, τοποθετώντας παρόμοια νοήματα — όπως "αυτοκίνητο" και "όχημα" — κοντά το ένα στο άλλο στο διανυσματικό χώρο.* +*Αυτό το διάγραμμα δείχνει πώς ένα μοντέλο ενσωμάτωσης μετατρέπει κείμενο σε αριθμητικά διανύσματα, τοποθετώντας παρόμοια νοήματα — όπως "αυτοκίνητο" και "όχημα" — κοντά το ένα στο άλλο στον χώρο των διανυσμάτων.* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` + +Το παρακάτω διάγραμμα κλάσεων δείχνει τις δύο ξεχωριστές ροές σε μια ροή RAG και τις κλάσεις LangChain4j που τις υλοποιούν. Η **ροή εισαγωγής** (τρέχει μία φορά κατά το ανέβασμα) χωρίζει το έγγραφο, ενσωματώνει τα τμήματα και τα αποθηκεύει μέσω `.addAll()`. Η **ροή ερώτησης** (τρέχει κάθε φορά που ο χρήστης ρωτά) ενσωματώνει την ερώτηση, ψάχνει στην αποθήκη μέσω `.search()` και περνά το σχετικό πλαίσιο στο μοντέλο chat. Και οι δύο ροές συναντώνται στο κοινό interface `EmbeddingStore`: -Το παρακάτω διάγραμμα κλάσεων δείχνει τις δύο ξεχωριστές ροές σε μια ροή εργασίας RAG και τις κλάσεις LangChain4j που τις υλοποιούν. Η **ροή απορρόφησης** (τρέχει μία φορά κατά το ανέβασμα) χωρίζει το έγγραφο, ενσωματώνει τα τμήματα και τα αποθηκεύει μέσω της `.addAll()`. Η **ροή ερωτήσεων** (τρέχει κάθε φορά που ένας χρήστης ρωτά) ενσωματώνει την ερώτηση, αναζητά στην αποθήκη μέσω της `.search()`, και περνά το ταιριαστό πλαίσιο στο μοντέλο συνομιλίας. Και οι δύο ροές συναντώνται στη κοινή διεπαφή `EmbeddingStore`: - -Κλάσεις LangChain4j RAG +Κλάσεις RAG του LangChain4j -*Αυτό το διάγραμμα δείχνει τις δύο ροές σε μια ροή RAG — απορρόφηση και ερώτηση — και πώς συνδέονται μέσω της κοινής EmbeddingStore.* +*Αυτό το διάγραμμα δείχνει τις δύο ροές σε μια ροή RAG — εισαγωγής και ερώτησης — και πώς συνδέονται μέσω ενός κοινόχρηστου EmbeddingStore.* -Μόλις αποθηκευτούν οι ενσωματώσεις, το παρόμοιο περιεχόμενο φυσικά ομαδοποιείται στον διανυσματικό χώρο. Η οπτικοποίηση παρακάτω δείχνει πώς έγγραφα σχετικά με συναφή θέματα καταλήγουν σε γειτονικά σημεία, καθιστώντας δυνατή τη σημασιολογική αναζήτηση: +Μόλις αποθηκευτούν οι ενσωματώσεις, το παρόμοιο περιεχόμενο συγκεντρώνεται φυσικά στον χώρο των διανυσμάτων. Η παρακάτω οπτικοποίηση δείχνει πώς έγγραφα για σχετικά θέματα καταλήγουν κοντά το ένα στο άλλο, πράγμα που κάνει δυνατή τη σημασιολογική αναζήτηση: -Χώρος Ενσωματώσεων Διανυσμάτων +Χώρος Ενσωμάτωσης Διανυσμάτων -*Αυτή η οπτικοποίηση δείχνει πώς σχετικά έγγραφα ομαδοποιούνται στον 3D διανυσματικό χώρο, με θέματα όπως Τεχνικά Έγγραφα, Εμπορικοί Κανόνες, και Συχνές Ερωτήσεις να σχηματίζουν διακεκριμένες ομάδες.* +*Αυτή η οπτικοποίηση δείχνει πώς σχετικά έγγραφα συσσωρεύονται μαζί σε τρισδιάστατο χώρο διανυσμάτων, με θέματα όπως Τεχνικά Έγγραφα, Επιχειρηματικοί Κανόνες και FAQ να σχηματίζουν διακριτές ομάδες.* -Όταν ένας χρήστης αναζητά, το σύστημα ακολουθεί τέσσερα βήματα: ενσωματώνει τα έγγραφα μία φορά, ενσωματώνει την ερώτηση σε κάθε αναζήτηση, συγκρίνει το διάνυσμα της ερώτησης με όλα τα αποθηκευμένα διανύσματα χρησιμοποιώντας την ομοιότητα του συνημιτόνου, και επιστρέφει τα κορυφαία-K τμήματα με τις υψηλότερες βαθμολογίες. Το διάγραμμα παρακάτω περιγράφει κάθε βήμα και τις σχετικές κλάσεις LangChain4j: +Όταν ένας χρήστης ψάχνει, το σύστημα ακολουθεί τέσσερα βήματα: ενσωματώνει τα έγγραφα μία φορά, ενσωματώνει την ερώτηση σε κάθε αναζήτηση, συγκρίνει το διάνυσμα της ερώτησης με όλα τα αποθηκευμένα διανύσματα με χρήση της ομοιότητας συνημίτονου, και επιστρέφει τα τμήματα με την υψηλότερη βαθμολογία Top-K. Το παρακάτω διάγραμμα περνά κάθε βήμα και τις αντίστοιχες κλάσεις LangChain4j: -Βήματα Αναζήτησης με Ενσωμάτωση +Βήματα Αναζήτησης Ενσωμάτωσης -*Αυτό το διάγραμμα δείχνει τη διαδικασία αναζήτησης τεσσάρων βημάτων με ενσωμάτωση: ενσωμάτωση εγγράφων, ενσωμάτωση ερώτησης, σύγκριση διανυσμάτων με ομοιότητα συνημιτόνου, και επιστροφή των κορυφαίων αποτελεσμάτων.* +*Αυτό το διάγραμμα δείχνει τη διαδικασία αναζήτησης ενσωμάτωσης σε τέσσερα βήματα: ενσωμάτωση εγγράφων, ενσωμάτωση ερώτησης, σύγκριση διανυσμάτων με ομοιότητα συνημίτονου και επιστροφή των κορυφαίων αποτελεσμάτων.* -### Σημασιολογική Αναζήτηση +### Semantic Search [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Όταν κάνετε μια ερώτηση, και η ερώτησή σας μετατρέπεται σε ενσωμάτωση. Το σύστημα συγκρίνει την ενσωμάτωση της ερώτησής σας με όλες τις ενσωματώσεις των τμημάτων εγγράφων. Βρίσκει τα τμήματα με τα πιο παρόμοια νοήματα — όχι απλώς μείωση λέξεων-κλειδιών, αλλά πραγματική σημασιολογική ομοιότητα. +Όταν κάνετε μια ερώτηση, και αυτή η ερώτηση γίνεται επίσης μια ενσωμάτωση. Το σύστημα συγκρίνει την ενσωμάτωση της ερώτησής σας με όλες τις ενσωματώσεις των τμημάτων εγγράφων. Βρίσκει τα τμήματα με τα πιο παρόμοια νοήματα — όχι απλώς μετρήσεις λέξεων-κλειδιών, αλλά πραγματική σημασιολογική ομοιότητα. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -Το παρακάτω διάγραμμα αντιπαραβάλλει τη σημασιολογική αναζήτηση με την παραδοσιακή αναζήτηση με λέξεις-κλειδιά. Μια αναζήτηση με λέξη-κλειδί για "όχημα" χάνει ένα τμήμα για "αυτοκίνητα και φορτηγά", αλλά η σημασιολογική αναζήτηση καταλαβαίνει ότι σημαίνουν το ίδιο και το επιστρέφει ως υψηλοβάθμο αποτέλεσμα: + +Το διάγραμμα παρακάτω αντιπαραβάλλει τη σημασιολογική αναζήτηση με την παραδοσιακή αναζήτηση λέξεων-κλειδιών. Μια αναζήτηση λέξεων-κλειδιών για "όχημα" χάνει ένα τμήμα για "αυτοκίνητα και φορτηγά," αλλά η σημασιολογική αναζήτηση καταλαβαίνει ότι σημαίνουν το ίδιο πράγμα και το επιστρέφει ως υψηλής βαθμολογίας ταίρι: Σημασιολογική Αναζήτηση -*Αυτό το διάγραμμα συγκρίνει την αναζήτηση με βάση λέξεις-κλειδιά με τη σημασιολογική αναζήτηση, δείχνοντας πώς η σημασιολογική αναζήτηση αναζητά περιεχόμενο σχετικό εννοιολογικά ακόμη και όταν διαφέρουν οι ακριβείς λέξεις-κλειδιά.* -Κάτω από την επιφάνεια, η ομοιότητα μετριέται χρησιμοποιώντας την συνημίτονα ομοιότητα — ουσιαστικά ρωτώντας "δεικνύουν αυτά τα δύο βέλη προς την ίδια κατεύθυνση;" Δύο τμήματα μπορούν να χρησιμοποιούν εντελώς διαφορετικές λέξεις, αλλά αν σημαίνουν το ίδιο πράγμα, τα διανύσματά τους δείχνουν στην ίδια κατεύθυνση και η βαθμολογία είναι κοντά στο 1.0: +*Αυτό το διάγραμμα συγκρίνει την αναζήτηση με βάση λέξεις-κλειδιά με τη σημασιολογική αναζήτηση, δείχνοντας πώς η σημασιολογική αναζήτηση ανακτά περιεχόμενο που σχετίζεται εννοιολογικά ακόμα και όταν οι ακριβείς λέξεις-κλειδιά διαφέρουν.* -Cosine Similarity +Στο εσωτερικό, η ομοιότητα μετριέται χρησιμοποιώντας την ομοιότητα συνημίτονου — που ρωτά ουσιαστικά "δείχνουν αυτά τα δύο βέλη στην ίδια κατεύθυνση;" Δύο τμήματα μπορεί να χρησιμοποιούν εντελώς διαφορετικές λέξεις, αλλά αν σημαίνουν το ίδιο, τα διανύσματά τους δείχνουν προς την ίδια κατεύθυνση και έχουν βαθμολογία κοντά στο 1.0: -*Αυτό το διάγραμμα απεικονίζει τη συνημίτονα ομοιότητα ως τη γωνία μεταξύ των διανυσμάτων ενσωμάτωσης — όσο πιο ευθυγραμμισμένα είναι τα διανύσματα, τόσο πιο κοντά στο 1.0 είναι η βαθμολογία, υποδεικνύοντας μεγαλύτερη σημασιολογική ομοιότητα.* +Ομοιότητα Συνημίτονου +*Αυτό το διάγραμμα απεικονίζει την ομοιότητα συνημιτόνου ως τη γωνία μεταξύ των διανυσμάτων ενσωμάτωσης — τα πιο ευθυγραμμισμένα διανύσματα έχουν βαθμολογία πιο κοντά στο 1.0, υποδηλώνοντας υψηλότερη σημασιολογική ομοιότητα.* -> **🤖 Δοκίμασε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Άνοιξε το [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) και ρώτα: +> **🤖 Δοκιμάστε με το [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) και ρωτήστε: > - "Πώς λειτουργεί η αναζήτηση ομοιότητας με τις ενσωματώσεις και τι καθορίζει τη βαθμολογία;" > - "Ποιο όριο ομοιότητας πρέπει να χρησιμοποιήσω και πώς επηρεάζει τα αποτελέσματα;" -> - "Πώς διαχειρίζομαι περιπτώσεις όπου δεν βρέθηκαν σχετικά έγγραφα;" +> - "Πώς χειρίζομαι περιπτώσεις όπου δεν βρέθηκαν σχετικά έγγραφα;" ### Δημιουργία Απάντησης [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Τα πιο σχετικά τμήματα συγκεντρώνονται σε μια δομημένη υπόδειξη που περιλαμβάνει ρητές οδηγίες, το ανακτηθέν πλαίσιο και την ερώτηση του χρήστη. Το μοντέλο διαβάζει αυτά τα συγκεκριμένα τμήματα και απαντά βάσει αυτών των πληροφοριών — μπορεί να χρησιμοποιήσει μόνο ό,τι έχει μπροστά του, κάτι που αποτρέπει την παραγωγή ψευδών απαντήσεων. +Τα πιο σχετικά τμήματα συντίθενται σε μια δομημένη προτροπή που περιλαμβάνει ρητές οδηγίες, το ανακτηθέν περιεχόμενο και την ερώτηση του χρήστη. Το μοντέλο διαβάζει αυτά τα συγκεκριμένα τμήματα και απαντά βάσει αυτών των πληροφοριών — μπορεί να χρησιμοποιήσει μόνο ό,τι έχει μπροστά του, κάτι που αποτρέπει την παρερμηνεία. ```java String context = matches.stream() @@ -237,55 +236,55 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Το διάγραμμα παρακάτω δείχνει αυτή τη συναρμολόγηση σε δράση — τα τμήματα με την υψηλότερη βαθμολογία από το βήμα αναζήτησης εισάγονται στο πρότυπο υπόδειξης, και το `OpenAiOfficialChatModel` παράγει μια βασισμένη απάντηση: +Το παρακάτω διάγραμμα δείχνει αυτή τη σύνθεση σε δράση — τα κορυφαία τμήματα με τη μεγαλύτερη βαθμολογία από το βήμα αναζήτησης εισάγονται στο πρότυπο προτροπής, και το `OpenAiOfficialChatModel` παράγει μια τεκμηριωμένη απάντηση: Context Assembly -*Αυτό το διάγραμμα δείχνει πώς τα τμήματα με την υψηλότερη βαθμολογία συγκεντρώνονται σε μια δομημένη υπόδειξη, επιτρέποντας στο μοντέλο να παράγει μια βασισμένη απάντηση από τα δεδομένα σας.* +*Αυτό το διάγραμμα δείχνει πώς τα κορυφαία σε βαθμολογία τμήματα συναρμολογούνται σε μια δομημένη προτροπή, επιτρέποντας στο μοντέλο να παράγει μια τεκμηριωμένη απάντηση από τα δεδομένα σας.* ## Εκτέλεση της Εφαρμογής -**Επαλήθευση ανάπτυξης:** +**Επιβεβαίωση ανάπτυξης:** -Βεβαιωθείτε ότι το αρχείο `.env` υπάρχει στον ριζικό φάκελο με τα διαπιστευτήρια Azure (δημιουργήθηκε κατά τη διάρκεια του Μονάδα 01). Εκτελέστε το από τον φάκελο της μονάδας (`03-rag/`): +Βεβαιωθείτε ότι το αρχείο `.env` υπάρχει στον ριζικό κατάλογο με διαπιστευτήρια Azure (δημιουργήθηκε κατά τη διάρκεια του Module 01). Εκτελέστε αυτό από το φάκελο του module (`03-rag/`): **Bash:** ```bash -cat ../.env # Θα πρέπει να εμφανίζει AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Θα πρέπει να εμφανίζει τα AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Πρέπει να εμφανίζει AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Θα πρέπει να εμφανίζει AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Εκκίνηση της εφαρμογής:** +**Εκκινήστε την εφαρμογή:** -> **Σημείωση:** Αν έχετε ήδη ξεκινήσει όλες τις εφαρμογές χρησιμοποιώντας το `./start-all.sh` από τον ριζικό φάκελο (όπως περιγράφεται στο Μονάδα 01), αυτή η μονάδα τρέχει ήδη στην θύρα 8081. Μπορείτε να παραλείψετε τις παρακάτω εντολές εκκίνησης και να μεταβείτε απευθείας στο http://localhost:8081. +> **Σημείωση:** Εάν έχετε ήδη ξεκινήσει όλες τις εφαρμογές χρησιμοποιώντας το `./start-all.sh` από τον ριζικό κατάλογο (όπως περιγράφεται στο Module 01), αυτό το module ήδη τρέχει στην θύρα 8081. Μπορείτε να παραλείψετε τις εντολές εκκίνησης παρακάτω και να πάτε απευθείας στο http://localhost:8081. -**Επιλογή 1: Χρήση του Spring Boot Dashboard (Συνιστάται για χρήστες VS Code)** +**Επιλογή 1: Χρήση του Spring Boot Dashboard (Προτεινόμενο για χρήστες VS Code)** -Το dev container περιλαμβάνει την επέκταση Spring Boot Dashboard, που παρέχει οπτικό περιβάλλον για τη διαχείριση όλων των εφαρμογών Spring Boot. Μπορείτε να το βρείτε στη μπάρα δραστηριότητας στα αριστερά του VS Code (αναζητήστε το εικονίδιο του Spring Boot). +Το περιβάλλον ανάπτυξης περιλαμβάνει την επέκταση Spring Boot Dashboard, που παρέχει ένα οπτικό περιβάλλον για τη διαχείριση όλων των εφαρμογών Spring Boot. Μπορείτε να το βρείτε στη γραμμή δραστηριοτήτων στα αριστερά του VS Code (αναζητήστε το εικονίδιο Spring Boot). -Από το Spring Boot Dashboard μπορείτε να: +Από το Spring Boot Dashboard, μπορείτε να: - Δείτε όλες τις διαθέσιμες εφαρμογές Spring Boot στο χώρο εργασίας - Ξεκινήσετε/σταματήσετε εφαρμογές με ένα κλικ -- Προβάλετε αρχεία καταγραφής εφαρμογών σε πραγματικό χρόνο -- Παρακολουθείτε την κατάσταση των εφαρμογών +- Προβάλετε τα αρχεία καταγραφής εφαρμογών σε πραγματικό χρόνο +- Παρακολουθήσετε την κατάσταση της εφαρμογής -Απλά κάντε κλικ στο κουμπί εκκίνησης δίπλα στο "rag" για να ξεκινήσετε αυτή τη μονάδα, ή ξεκινήστε όλες τις μονάδες μαζί. +Απλά κάντε κλικ στο κουμπί play δίπλα στο "rag" για να ξεκινήσετε αυτό το module, ή ξεκινήστε όλα τα modules μαζί. Spring Boot Dashboard -*Αυτή η εικόνα οθόνης δείχνει το Spring Boot Dashboard στο VS Code, όπου μπορείτε να ξεκινήσετε, να σταματήσετε και να παρακολουθήσετε εφαρμογές οπτικά.* +*Αυτή η οθόνη δείχνει το Spring Boot Dashboard στο VS Code, όπου μπορείτε να ξεκινήσετε, να σταματήσετε και να παρακολουθήσετε τις εφαρμογές οπτικά.* **Επιλογή 2: Χρήση shell scripts** -Εκκινήστε όλες τις web εφαρμογές (μονάδες 01-04): +Ξεκινήστε όλες τις web εφαρμογές (modules 01-04): **Bash:** ```bash -cd .. # Από τον ριζικό φάκελο +cd .. # Από τον ριζικό κατάλογο ./start-all.sh ``` @@ -295,7 +294,7 @@ cd .. # Από τον ριζικό κατάλογο .\start-all.ps1 ``` -Ή εκκινήστε μόνο αυτή τη μονάδα: +Ή ξεκινήστε μόνο αυτό το module: **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Και τα δύο scripts φορτώνουν αυτόματα μεταβλητές περιβάλλοντος από το αρχείο `.env` του ριζικού φακέλου και θα δημιουργήσουν τα JAR αν δεν υπάρχουν. +Και τα δύο scripts φορτώνουν αυτόματα τις μεταβλητές περιβάλλοντος από το ριζικό αρχείο `.env` και θα κατασκευάσουν τα JAR εάν δεν υπάρχουν. -> **Σημείωση:** Αν προτιμάτε να κατασκευάσετε όλες τις μονάδες χειροκίνητα πριν την εκκίνηση: +> **Σημείωση:** Εάν προτιμάτε να κατασκευάσετε όλα τα modules χειροκίνητα πριν από την εκκίνηση: > > **Bash:** > ```bash @@ -325,7 +324,7 @@ cd 03-rag > mvn clean package -DskipTests > ``` -Ανοίξτε το http://localhost:8081 στο πρόγραμμα περιήγησής σας. +Ανοίξτε το http://localhost:8081 στον φυλλομετρητή σας. **Για να σταματήσετε:** @@ -345,93 +344,93 @@ cd ..; .\stop-all.ps1 # Όλα τα modules ## Χρήση της Εφαρμογής -Η εφαρμογή παρέχει μια διαδικτυακή διεπαφή για την φόρτωση εγγράφων και την υποβολή ερωτήσεων. +Η εφαρμογή παρέχει ένα διαδικτυακό περιβάλλον για ανέβασμα εγγράφων και ερωτήσεις. RAG Application Interface -*Αυτή η εικόνα οθόνης δείχνει τη διεπαφή της εφαρμογής RAG όπου ανεβάζετε έγγραφα και κάνετε ερωτήσεις.* +*Αυτή η εικόνα οθόνης δείχνει το περιβάλλον της εφαρμογής RAG όπου ανεβάζετε έγγραφα και κάνετε ερωτήσεις.* ### Ανέβασμα Εγγράφου -Ξεκινήστε ανεβάζοντας ένα έγγραφο - τα αρχεία TXT είναι ιδανικά για δοκιμές. Ένα `sample-document.txt` παρέχεται σε αυτόν τον φάκελο που περιέχει πληροφορίες για τις λειτουργίες του LangChain4j, την υλοποίηση RAG και βέλτιστες πρακτικές - τέλειο για δοκιμή του συστήματος. +Ξεκινήστε ανεβάζοντας ένα έγγραφο — τα αρχεία TXT λειτουργούν καλύτερα για δοκιμές. Ένα `sample-document.txt` παρέχεται σε αυτόν τον κατάλογο που περιέχει πληροφορίες για τις λειτουργίες του LangChain4j, την υλοποίηση RAG και τις βέλτιστες πρακτικές — ιδανικό για δοκιμή του συστήματος. -Το σύστημα επεξεργάζεται το έγγραφό σας, το διασπά σε τμήματα και δημιουργεί ενσωματώσεις για κάθε τμήμα. Αυτό γίνεται αυτόματα όταν ανεβάζετε. +Το σύστημα επεξεργάζεται το έγγραφο, το σπάει σε τμήματα και δημιουργεί ενσωματώσεις για κάθε τμήμα. Αυτό συμβαίνει αυτόματα κατά το ανέβασμα. -### Υποβολή Ερωτήσεων +### Κάντε Ερωτήσεις -Τώρα κάντε συγκεκριμένες ερωτήσεις σχετικά με το περιεχόμενο του εγγράφου. Δοκιμάστε κάτι πραγματικό που δηλώνεται σαφώς στο έγγραφο. Το σύστημα αναζητά σχετικά τμήματα, τα συμπεριλαμβάνει στην υπόδειξη και παράγει μια απάντηση. +Τώρα κάντε συγκεκριμένες ερωτήσεις σχετικά με το περιεχόμενο του εγγράφου. Δοκιμάστε κάτι γεγονότα που αναφέρονται ρητά στο έγγραφο. Το σύστημα αναζητά σχετικά τμήματα, τα περιλαμβάνει στην προτροπή και παράγει μια απάντηση. -### Έλεγχος Αναφορών Πηγών +### Ελέγξτε τις Πηγές Αναφορών -Παρατηρήστε ότι κάθε απάντηση περιλαμβάνει αναφορές πηγών με βαθμολογίες ομοιότητας. Αυτές οι βαθμολογίες (0 έως 1) δείχνουν πόσο σχετικό ήταν κάθε τμήμα με την ερώτησή σας. Υψηλότερες βαθμολογίες σημαίνουν καλύτερες αντιστοιχίες. Αυτό σας επιτρέπει να επαληθεύσετε την απάντηση με βάση το πρωτότυπο υλικό. +Παρατηρήστε ότι κάθε απάντηση περιλαμβάνει αναφορές πηγών με βαθμολογίες ομοιότητας. Αυτές οι βαθμολογίες (από 0 έως 1) δείχνουν πόσο σχετικό ήταν κάθε τμήμα με την ερώτησή σας. Οι υψηλότερες βαθμολογίες σημαίνουν καλύτερες αντιστοιχίες. Αυτό σας επιτρέπει να επαληθεύσετε την απάντηση με βάση το πρωτογενές υλικό. RAG Query Results -*Αυτή η εικόνα οθόνης δείχνει τα αποτελέσματα ερωτήσεων με την παραγόμενη απάντηση, τις αναφορές πηγών και τις βαθμολογίες σχετικότητας για κάθε ανακτηθέν τμήμα.* +*Αυτή η εικόνα οθόνης δείχνει τα αποτελέσματα ερωτημάτων με την παραγόμενη απάντηση, τις αναφορές πηγών και τις βαθμολογίες σχετικότητας για κάθε ανακτηθέν τμήμα.* ### Πειραματιστείτε με Ερωτήσεις -Δοκιμάστε διαφορετικούς τύπους ερωτήσεων: +Δοκιμάστε διαφορετικά είδη ερωτήσεων: - Συγκεκριμένα γεγονότα: "Ποιο είναι το κύριο θέμα;" - Συγκρίσεις: "Ποια είναι η διαφορά μεταξύ X και Y;" -- Περίληψη: "Περίληψη των βασικών σημείων για το Z" +- Περίληψη: "Συνοψίστε τα βασικά σημεία σχετικά με το Z" -Παρακολουθήστε πώς αλλάζουν οι βαθμολογίες σχετικότητας ανάλογα με το πόσο καλά η ερώτησή σας ταιριάζει με το περιεχόμενο του εγγράφου. +Παρατηρήστε πώς αλλάζουν οι βαθμολογίες σχετικότητας βάσει το πόσο καλά ταιριάζει η ερώτησή σας με το περιεχόμενο του εγγράφου. -## Βασικές Έννοιες +## Κύριες Έννοιες -### Στρατηγική Κατατμήσεων +### Στρατηγική Τμηματοποίησης -Τα έγγραφα διασπώνται σε τμήματα 300 tokens με 30 tokens επικάλυψη. Αυτή η ισορροπία διασφαλίζει ότι κάθε τμήμα έχει αρκετό πλαίσιο για να είναι ουσιαστικό ενώ παραμένει αρκετά μικρό ώστε να χωρούν πολλά τμήματα σε μια υπόδειξη. +Τα έγγραφα χωρίζονται σε τμήματα 300 tokens με 30 tokens επικάλυψη. Αυτό το ισοζύγιο διασφαλίζει ότι κάθε τμήμα έχει αρκετό περιεχόμενο για να είναι ουσιαστικό, ενώ παραμένει ικανό να περιλάβει πολλαπλά τμήματα σε μια προτροπή. ### Βαθμολογίες Ομοιότητας -Κάθε ανακτηθέν τμήμα συνοδεύεται από μια βαθμολογία ομοιότητας μεταξύ 0 και 1 που δείχνει πόσο στενά ταιριάζει με την ερώτηση του χρήστη. Το διάγραμμα παρακάτω οπτικοποιεί τα εύρη βαθμολογιών και πώς το σύστημα τα χρησιμοποιεί για τη φιλτραρίσματος αποτελεσμάτων: +Κάθε ανακτηθέν τμήμα συνοδεύεται από βαθμολογία ομοιότητας μεταξύ 0 και 1 που δείχνει πόσο στενά ταιριάζει με την ερώτηση του χρήστη. Το παρακάτω διάγραμμα απεικονίζει τα εύρη βαθμολογίας και πώς το σύστημα τα χρησιμοποιεί για να φιλτράρει τα αποτελέσματα: Similarity Scores -*Αυτό το διάγραμμα δείχνει εύρη βαθμολογιών από 0 έως 1, με κατώτερο όριο 0.5 που φιλτράρει τα μη σχετικά τμήματα.* +*Αυτό το διάγραμμα δείχνει τα εύρη βαθμολογίας από 0 έως 1, με ένα ελάχιστο όριο 0.5 που φιλτράρει τα άσχετα τμήματα.* Οι βαθμολογίες κυμαίνονται από 0 έως 1: -- 0.7-1.0: Πολύ σχετικό, ακριβής αντιστοιχία -- 0.5-0.7: Σχετικό, καλό πλαίσιο -- Κάτω από 0.5: Φιλτραρισμένο, πολύ ανομοιόμορφο +- 0.7-1.0: Πολύ σχετικά, ακριβής αντιστοιχία +- 0.5-0.7: Σχετικά, καλό πλαίσιο +- Κάτω από 0.5: Φιλτράρεται, πολύ διαφορετικό -Το σύστημα ανακτά μόνο τμήματα πάνω από το ελάχιστο όριο για να διασφαλίσει την ποιότητα. +Το σύστημα ανακτά μόνο τμήματα πάνω από το ελάχιστο όριο για να εξασφαλίσει ποιότητα. -Οι ενσωματώσεις λειτουργούν καλά όταν οι έννοιες συσσωρεύονται καθαρά, αλλά έχουν και αδύναμα σημεία. Το διάγραμμα παρακάτω δείχνει συνήθεις τρόπους αποτυχίας — τμήματα πολύ μεγάλα παράγουν θολά διανύσματα, τμήματα πολύ μικρά στερούνται πλαισίου, ασαφείς όροι σκιάζουν πολλαπλές ομάδες, και οι ακριβείς αναζητήσεις (IDs, αριθμοί μερών) δεν λειτουργούν καθόλου με ενσωματώσεις: +Οι ενσωματώσεις δουλεύουν καλά όταν οι έννοιες συγκεντρώνονται καθαρά, αλλά έχουν αδύνατα σημεία. Το παρακάτω διάγραμμα δείχνει τις συνηθισμένες αποτυχίες — τμήματα που είναι πολύ μεγάλα παράγουν θολά διανύσματα, τμήματα πολύ μικρά στερούνται πλαισίου, αμβλυμμένες έννοιες δείχνουν σε πολλαπλές ομάδες, και αναζητήσεις ακριβούς αντιστοιχίας (IDs, αριθμοί ανταλλακτικών) δεν δουλεύουν καθόλου με τις ενσωματώσεις: Embedding Failure Modes -*Αυτό το διάγραμμα δείχνει συνήθεις τρόπους αποτυχίας ενσωμάτωσης: τμήματα πολύ μεγάλα, τμήματα πολύ μικρά, ασαφείς όροι που δείχνουν σε πολλαπλές ομάδες, και ακριβείς αναζητήσεις όπως IDs.* +*Αυτό το διάγραμμα δείχνει κοινές αποτυχίες ενσωμάτωσης: τμήματα πολύ μεγάλα, τμήματα πολύ μικρά, ασαφείς όροι που δείχνουν σε πολλαπλές ομάδες, και αναζητήσεις ακριβούς αντιστοιχίας όπως ID.* -### Αποθήκευση στη Μνήμη +### Αποθήκευση Στο Μνήμης -Αυτή η μονάδα χρησιμοποιεί αποθήκευση στη μνήμη για απλότητα. Όταν επανεκκινείτε την εφαρμογή, τα ανεβασμένα έγγραφα χάνονται. Συστήματα παραγωγής χρησιμοποιούν επίμονες βάσεις δεδομένων διανυσμάτων όπως το Qdrant ή το Azure AI Search. +Αυτό το module χρησιμοποιεί αποθήκευση στη μνήμη για απλότητα. Όταν επανεκκινήσετε την εφαρμογή, τα ανεβασμένα έγγραφα χάνονται. Συστήματα παραγωγής χρησιμοποιούν επίμονες βάσεις δεδομένων διανυσμάτων όπως οι Qdrant ή Azure AI Search. ### Διαχείριση Παραθύρου Πλαισίου -Κάθε μοντέλο έχει μέγιστο παράθυρο πλαισίου. Δεν μπορείτε να συμπεριλάβετε κάθε τμήμα από ένα μεγάλο έγγραφο. Το σύστημα ανακτά τα N πιο σχετικά τμήματα (προεπιλογή 5) για να παραμείνει εντός ορίων ενώ παρέχει αρκετό πλαίσιο για ακριβείς απαντήσεις. +Κάθε μοντέλο έχει ένα μέγιστο παράθυρο πλαισίου. Δεν μπορείτε να συμπεριλάβετε κάθε τμήμα από ένα μεγάλο έγγραφο. Το σύστημα ανακτά τα κορυφαία Ν πιο σχετικά τμήματα (εξ ορισμού 5) για να παραμένει εντός ορίων ενώ παρέχει αρκετό πλαίσιο για ακριβείς απαντήσεις. -## Πότε έχει Σημασία το RAG +## Πότε Έχει Σημασία η RAG -Το RAG δεν είναι πάντα η κατάλληλη προσέγγιση. Ο παρακάτω οδηγός απόφασης σας βοηθά να αποφασίσετε πότε το RAG προσθέτει αξία έναντι απλούστερων προσεγγίσεων — όπως η άμεση ενσωμάτωση περιεχομένου στην υπόδειξη ή η χρήση της ενσωματωμένης γνώσης του μοντέλου: +Η RAG δεν είναι πάντα η κατάλληλη προσέγγιση. Ο παρακάτω οδηγός απόφασης σας βοηθά να αποφασίσετε πότε η RAG προσθέτει αξία αντί πότε απλούστερες προσεγγίσεις — όπως η απευθείας συμπερίληψη περιεχομένου στην προτροπή ή η βασιζόμενη στη γνώση του μοντέλου — επαρκούν: When to Use RAG -*Αυτό το διάγραμμα δείχνει έναν οδηγό απόφασης για το πότε το RAG προσθέτει αξία και πότε οι απλούστερες προσεγγίσεις είναι επαρκείς.* +*Αυτό το διάγραμμα δείχνει έναν οδηγό απόφασης για το πότε η RAG προσθέτει αξία σε σχέση με το πότε αρκούν απλούστερες προσεγγίσεις.* ## Επόμενα Βήματα -**Επόμενη Μονάδα:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Επόμενο Module:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**Πλοήγηση:** [← Προηγούμενο: Μονάδα 02 - Μηχανική Υποδείξεων](../02-prompt-engineering/README.md) | [Πίσω στην Αρχική](../README.md) | [Επόμενο: Μονάδα 04 - Εργαλεία →](../04-tools/README.md) +**Πλοήγηση:** [← Προηγούμενο: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Πίσω στην Αρχική](../README.md) | [Επόμενο: Module 04 - Tools →](../04-tools/README.md) --- -**Αποποίηση ευθυνών**: -Αυτή η εγγραφή έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης AI [Co-op Translator](https://github.com/Azure/co-op-translator). Παρά τις προσπάθειές μας για ακρίβεια, παρακαλούμε να λάβετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη γλωσσική του μορφή πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται η επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. +**Αποποίηση ευθυνών**: +Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. \ No newline at end of file diff --git a/translations/el/04-tools/README.md b/translations/el/04-tools/README.md index 7d4c50003..a525d782c 100644 --- a/translations/el/04-tools/README.md +++ b/translations/el/04-tools/README.md @@ -1,76 +1,76 @@ -# Module 04: Πράκτορες Τεχνητής Νοημοσύνης με Εργαλεία +# Ενότητα 04: AI Πράκτορες με Εργαλεία ## Πίνακας Περιεχομένων -- [Περιήγηση στο Βίντεο](../../../04-tools) -- [Τι Θα Μάθετε](../../../04-tools) -- [Προαπαιτούμενα](../../../04-tools) -- [Κατανόηση των Πρακτόρων Τεχνητής Νοημοσύνης με Εργαλεία](../../../04-tools) -- [Πώς Λειτουργεί η Κλήση Εργαλείων](../../../04-tools) - - [Ορισμοί Εργαλείων](../../../04-tools) - - [Λήψη Αποφάσεων](../../../04-tools) - - [Εκτέλεση](../../../04-tools) - - [Δημιουργία Απάντησης](../../../04-tools) - - [Αρχιτεκτονική: Αυτόματη Δέσμευση στο Spring Boot](../../../04-tools) -- [Αλυσιδωτή Χρήση Εργαλείων](../../../04-tools) -- [Εκτέλεση της Εφαρμογής](../../../04-tools) -- [Χρήση της Εφαρμογής](../../../04-tools) - - [Δοκιμάστε Απλή Χρήση Εργαλείου](../../../04-tools) - - [Δοκιμή Αλυσιδωτής Χρήσης Εργαλείων](../../../04-tools) - - [Δείτε τη Ροή της Συνομιλίας](../../../04-tools) - - [Πειραματιστείτε με Διάφορα Αιτήματα](../../../04-tools) -- [Βασικές Έννοιες](../../../04-tools) - - [Πρότυπο ReAct (Σκέψη και Δράση)](../../../04-tools) - - [Η Περιγραφή των Εργαλείων Μετράει](../../../04-tools) - - [Διαχείριση Συνεδρίας](../../../04-tools) - - [Διαχείριση Σφαλμάτων](../../../04-tools) -- [Διαθέσιμα Εργαλεία](../../../04-tools) -- [Πότε να Χρησιμοποιήσετε Πράκτορες με Βάση τα Εργαλεία](../../../04-tools) -- [Εργαλεία έναντι RAG](../../../04-tools) -- [Επόμενα Βήματα](../../../04-tools) - -## Περιήγηση στο Βίντεο - -Παρακολουθήστε αυτή τη ζωντανή συνεδρία που εξηγεί πώς να ξεκινήσετε με αυτό το module: - -Πράκτορες Τεχνητής Νοημοσύνης με Εργαλεία και MCP - Ζωντανή Συνεδρία +- [Περιήγηση σε Βίντεο](#περιήγηση-σε-βίντεο) +- [Τι Θα Μάθετε](#τι-θα-μάθετε) +- [Προαπαιτούμενα](#προαπαιτούμενα) +- [Κατανόηση των AI Πρακτόρων με Εργαλεία](#κατανόηση-των-ai-πρακτόρων-με-εργαλεία) +- [Πώς Λειτουργεί η Κλήση Εργαλείων](#πώς-λειτουργεί-η-κλήση-εργαλείων) + - [Ορισμοί Εργαλείων](#ορισμοί-εργαλείων) + - [Λήψη Αποφάσεων](#λήψη-αποφάσεων) + - [Εκτέλεση](#εκτέλεση) + - [Δημιουργία Απάντησης](#δημιουργία-απάντησης) + - [Αρχιτεκτονική: Αυτόματη Δρομολόγηση Spring Boot](#αρχιτεκτονική-αυτόματη-δρομολόγηση-spring-boot) +- [Αλυσιδωτή Χρήση Εργαλείων](#αλυσιδωτή-χρήση-εργαλείων) +- [Εκτέλεση της Εφαρμογής](#εκτέλεση-της-εφαρμογής) +- [Χρήση της Εφαρμογής](#χρήση-της-εφαρμογής) + - [Δοκιμή Απλής Χρήσης Εργαλείου](#δοκιμάστε-απλή-χρήση-εργαλείου) + - [Δοκιμή Αλυσιδωτής Χρήσης Εργαλείων](#δοκιμάστε-αλυσιδωτή-χρήση-εργαλείων) + - [Δείτε τη Ροή της Συνομιλίας](#δείτε-τη-ροή-της-συνομιλίας) + - [Πειραματιστείτε με Διάφορα Αιτήματα](#πειραματιστείτε-με-διάφορα-αιτήματα) +- [Βασικές Έννοιες](#κύριες-έννοιες) + - [Πρότυπο ReAct (Λογική και Δράση)](#πρότυπο-react-σκέψη-και-δράση) + - [Σημασία Περιγραφών Εργαλείων](#σημασία-περιγραφών-εργαλείων) + - [Διαχείριση Συνεδρίας](#διαχείριση-συνεδρίας) + - [Διαχείριση Σφαλμάτων](#διαχείριση-σφαλμάτων) +- [Διαθέσιμα Εργαλεία](#διαθέσιμα-εργαλεία) +- [Πότε να Χρησιμοποιείτε Πράκτορες Βασισμένους σε Εργαλεία](#πότε-να-χρησιμοποιείτε-πράκτορες-με-βάση-τα-εργαλεία) +- [Εργαλεία έναντι RAG](#εργαλεία-vs-rag) +- [Επόμενα Βήματα](#επόμενα-βήματα) + +## Περιήγηση σε Βίντεο + +Παρακολουθήστε αυτήν τη ζωντανή συνεδρία που εξηγεί πώς να ξεκινήσετε με αυτή την ενότητα: + +AI Agents with Tools and MCP - Live Session ## Τι Θα Μάθετε -Μέχρι στιγμής, έχετε μάθει πώς να έχετε συνομιλίες με AI, να δομείτε αποτελεσματικά οδηγίες (prompts) και να βασίζετε τις απαντήσεις σας σε έγγραφα. Αλλά υπάρχει ακόμα ένας θεμελιώδης περιορισμός: τα γλωσσικά μοντέλα μπορούν να παράγουν μόνο κείμενο. Δεν μπορούν να ελέγξουν τον καιρό, να κάνουν υπολογισμούς, να αναζητήσουν σε βάσεις δεδομένων ή να αλληλεπιδράσουν με εξωτερικά συστήματα. +Μέχρι τώρα, έχετε μάθει πώς να έχετε συνομιλίες με AI, να δομείτε αποτελεσματικά τις εντολές, και να εδραιώνετε τις απαντήσεις σας στα έγγραφά σας. Αλλά υπάρχει ακόμα ένας βασικός περιορισμός: τα γλωσσικά μοντέλα μπορούν μόνο να παράγουν κείμενο. Δεν μπορούν να ελέγξουν τον καιρό, να κάνουν υπολογισμούς, να ερωτήσουν βάσεις δεδομένων ή να αλληλεπιδράσουν με εξωτερικά συστήματα. -Τα εργαλεία αλλάζουν αυτό. Δίνοντας στο μοντέλο πρόσβαση σε λειτουργίες που μπορεί να καλεί, το μετατρέπετε από γεννήτρια κειμένου σε πράκτορα που μπορεί να αναλαμβάνει δράσεις. Το μοντέλο αποφασίζει πότε χρειάζεται ένα εργαλείο, ποιο εργαλείο θα χρησιμοποιήσει και ποια ορίσματα θα περάσει. Ο κώδικάς σας εκτελεί τη λειτουργία και επιστρέφει το αποτέλεσμα. Το μοντέλο ενσωματώνει το αποτέλεσμα στην απάντησή του. +Τα εργαλεία αλλάζουν αυτό. Δίνοντας στο μοντέλο πρόσβαση σε λειτουργίες που μπορεί να καλέσει, το μετατρέπετε από ένα εργαλείο παραγωγής κειμένου σε έναν πράκτορα που μπορεί να αναλαμβάνει δράσεις. Το μοντέλο αποφασίζει πότε χρειάζεται ένα εργαλείο, ποιο εργαλείο να χρησιμοποιήσει και ποια παραμέτρους να περάσει. Ο κώδικάς σας εκτελεί τη λειτουργία και επιστρέφει το αποτέλεσμα. Το μοντέλο ενσωματώνει αυτό το αποτέλεσμα στην απάντησή του. ## Προαπαιτούμενα -- Ολοκληρωμένο [Module 01 - Εισαγωγή](../01-introduction/README.md) (αναπτυγμένοι πόροι Azure OpenAI) -- Συνιστώμενα προηγούμενα modules (αυτό το module αναφέρεται σε [έννοιες RAG από το Module 03](../03-rag/README.md) στη σύγκριση Εργαλείων vs RAG) -- Αρχείο `.env` στον ριζικό φάκελο με διαπιστευτήρια Azure (δημιουργήθηκε από `azd up` στο Module 01) +- Ολοκληρωμένη [Ενότητα 01 - Εισαγωγή](../01-introduction/README.md) (αναπτύχθηκαν πόροι Azure OpenAI) +- Συνιστάται να έχετε ολοκληρώσει τις προηγούμενες ενότητες (αυτή η ενότητα αναφέρεται σε [έννοιες RAG από την Ενότητα 03](../03-rag/README.md) στην σύγκριση Εργαλείων vs RAG) +- Αρχείο `.env` στον βασικό κατάλογο με διαπιστευτήρια Azure (δημιουργήθηκε από `azd up` στην Ενότητα 01) -> **Σημείωση:** Αν δεν έχετε ολοκληρώσει το Module 01, ακολουθήστε πρώτα τις οδηγίες ανάπτυξης εκεί. +> **Σημείωση:** Αν δεν έχετε ολοκληρώσει την Ενότητα 01, ακολουθήστε πρώτα τις οδηγίες ανάπτυξης εκεί. -## Κατανόηση των Πρακτόρων Τεχνητής Νοημοσύνης με Εργαλεία +## Κατανόηση των AI Πρακτόρων με Εργαλεία -> **📝 Σημείωση:** Ο όρος "πράκτορες" σε αυτό το module αναφέρεται σε βοηθούς AI με δυνατότητες κλήσης εργαλείων. Αυτό διαφέρει από τα πρότυπα **Agentic AI** (αυτόνομοι πράκτορες με σχεδιασμό, μνήμη και πολυβηματική λογική) που θα καλύψουμε στο [Module 05: MCP](../05-mcp/README.md). +> **📝 Σημείωση:** Ο όρος "πράκτορες" σε αυτή την ενότητα αναφέρεται σε βοηθούς AI ενισχυμένους με δυνατότητες κλήσης εργαλείων. Αυτό διαφέρει από τα πρότυπα **Agentic AI** (αυτόνομοι πράκτορες με σχεδιασμό, μνήμη και λογική πολλαπλών βημάτων) που θα καλυφθούν στην [Ενότητα 05: MCP](../05-mcp/README.md). -Χωρίς εργαλεία, ένα γλωσσικό μοντέλο μπορεί μόνο να παράγει κείμενο από τα δεδομένα εκπαίδευσής του. Ρωτήστε το για τον τρέχοντα καιρό, και απλά κάνει μια εικασία. Δώστε του εργαλεία, και μπορεί να καλέσει έναν API πρόγνωσης καιρού, να εκτελέσει υπολογισμούς ή να κάνει αναζητήσεις σε βάση δεδομένων — και στη συνέχεια να ενσωματώσει αυτά τα πραγματικά αποτελέσματα στην απάντησή του. +Χωρίς εργαλεία, ένα γλωσσικό μοντέλο μπορεί μόνο να παράγει κείμενο από τα εκπαιδευτικά του δεδομένα. Ζητήστε του πληροφορίες για τον τρέχοντα καιρό, και πρέπει να μαντέψει. Δώστε του εργαλεία και μπορεί να καλέσει ένα API καιρού, να εκτελέσει υπολογισμούς, ή να ρωτήσει μια βάση δεδομένων — και μετά να ενσωματώσει αυτά τα πραγματικά αποτελέσματα στην απάντησή του. -Χωρίς Εργαλεία έναντι Με Εργαλεία +Χωρίς Εργαλεία vs Με Εργαλεία -*Χωρίς εργαλεία, το μοντέλο μπορεί μόνο να εικάσει — με εργαλεία μπορεί να καλέσει APIs, να τρέξει υπολογισμούς και να επιστρέψει δεδομένα σε πραγματικό χρόνο.* +*Χωρίς εργαλεία το μοντέλο μπορεί μόνο να μαντέψει — με εργαλεία μπορεί να καλέσει APIs, να κάνει υπολογισμούς και να επιστρέψει δεδομένα σε πραγματικό χρόνο.* -Ένας πράκτορας AI με εργαλεία ακολουθεί το πρότυπο **Σκέψης και Δράσης (ReAct)**. Το μοντέλο δεν απαντά απλά — σκέφτεται τι χρειάζεται, δρα καλώντας ένα εργαλείο, παρατηρεί το αποτέλεσμα και στη συνέχεια αποφασίζει αν θα ενεργήσει ξανά ή θα δώσει την τελική απάντηση: +Ένας πράκτορας AI με εργαλεία ακολουθεί ένα πρότυπο **Λογικής και Δράσης (ReAct)**. Το μοντέλο δεν απλώς απαντά — σκέφτεται τι χρειάζεται, ενεργεί καλώντας ένα εργαλείο, παρατηρεί το αποτέλεσμα, και μετά αποφασίζει αν θα δράσει ξανά ή θα δώσει την τελική απάντηση: -1. **Σκέφτεται** — Ο πράκτορας αναλύει την ερώτηση του χρήστη και καθορίζει τις πληροφορίες που χρειάζεται -2. **Δράση** — Ο πράκτορας επιλέγει το κατάλληλο εργαλείο, δημιουργεί σωστά τα ορίσματα και το καλεί -3. **Παρατήρηση** — Ο πράκτορας λαμβάνει το αποτέλεσμα του εργαλείου και το αξιολογεί -4. **Επανάληψη ή Απάντηση** — Αν χρειάζονται περισσότερα δεδομένα, ο πράκτορας επαναλαμβάνει τη διαδικασία, αλλιώς συνθέτει μια φυσική γλώσσα απάντηση +1. **Λογική** — Ο πράκτορας αναλύει την ερώτηση του χρήστη και καθορίζει ποια πληροφορία χρειάζεται +2. **Δράση** — Ο πράκτορας επιλέγει το σωστό εργαλείο, δημιουργεί τις σωστές παραμέτρους και το καλεί +3. **Παρατήρηση** — Ο πράκτορας λαμβάνει το αποτέλεσμα του εργαλείου και αξιολογεί την έκβαση +4. **Επανάληψη ή Απάντηση** — Αν χρειάζονται περισσότερα δεδομένα, ο πράκτορας επιστρέφει στην αρχή· αλλιώς συντάσσει μια απάντηση σε φυσική γλώσσα Πρότυπο ReAct -*Ο κύκλος ReAct — ο πράκτορας σκέφτεται τι να κάνει, δρα καλώντας εργαλείο, παρατηρεί το αποτέλεσμα και επαναλαμβάνει μέχρι να δώσει την τελική απάντηση.* +*Ο κύκλος ReAct — ο πράκτορας σκέφτεται τι πρέπει να κάνει, ενεργεί καλώντας ένα εργαλείο, παρατηρεί το αποτέλεσμα και επαναλαμβάνει μέχρι να δώσει την τελική απάντηση.* -Αυτό γίνεται αυτόματα. Εσείς ορίζετε τα εργαλεία και τις περιγραφές τους. Το μοντέλο αναλαμβάνει τη λήψη αποφάσεων για το πότε και πώς να τα χρησιμοποιήσει. +Αυτό συμβαίνει αυτόματα. Ορίζετε τα εργαλεία και τις περιγραφές τους. Το μοντέλο αναλαμβάνει τη λήψη αποφάσεων για το πότε και πώς θα τα χρησιμοποιήσει. ## Πώς Λειτουργεί η Κλήση Εργαλείων @@ -78,7 +78,7 @@ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Ορίζετε συναρτήσεις με σαφείς περιγραφές και προδιαγραφές παραμέτρων. Το μοντέλο βλέπει αυτές τις περιγραφές στην προτροπή συστήματος και κατανοεί τι κάνει κάθε εργαλείο. +Ορίζετε συναρτήσεις με σαφείς περιγραφές και προδιαγραφές παραμέτρων. Το μοντέλο βλέπει αυτές τις περιγραφές στο prompt συστήματος και κατανοεί τι κάνει κάθε εργαλείο. ```java @Component @@ -96,139 +96,139 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Ο βοηθός συνδέεται αυτόματα από το Spring Boot με: -// - Bean του ChatModel -// - Όλες οι μέθοδοι @Tool από τις κλάσεις @Component -// - Παροχέας ChatMemory για διαχείριση συνεδρίας +// Ο Βοηθός συνδέεται αυτόματα από το Spring Boot με: +// - Bean ChatModel +// - Όλες οι μέθοδοι @Tool από κλάσεις @Component +// - ChatMemoryProvider για διαχείριση συνεδρίας ``` -Το διάγραμμα παρακάτω αναλύει κάθε σχολιασμό και δείχνει πώς κάθε κομμάτι βοηθά το AI να καταλάβει πότε να καλέσει το εργαλείο και ποια ορίσματα να περάσει: +Το παρακάτω διάγραμμα αναλύει κάθε σημείωση και δείχνει πώς κάθε μέρος βοηθά το AI να καταλάβει πότε να καλέσει το εργαλείο και ποια ορίσματα να περάσει: -Ανατομία Ορισμών Εργαλείων +Ανατομία Ορισμού Εργαλείων -*Ανατομία ενός ορισμού εργαλείου — το @Tool λέει στο AI πότε να το χρησιμοποιήσει, το @P περιγράφει κάθε παράμετρο, και το @AiService συνδέει τα πάντα κατά την εκκίνηση.* +*Ανατομία ορισμού εργαλείου — το @Tool λέει στο AI πότε να το χρησιμοποιήσει, το @P περιγράφει κάθε παράμετρο, και το @AiService συνδέει τα πάντα κατά την εκκίνηση.* -> **🤖 Δοκιμάστε με το [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) και ρωτήστε: -> - "Πώς θα ενσωμάτωνα έναν πραγματικό API καιρού όπως το OpenWeatherMap αντί για δεδομένα προσομοίωσης;" -> - "Τι κάνει μια καλή περιγραφή εργαλείου που βοηθά το AI να το χρησιμοποιήσει σωστά;" -> - "Πώς διαχειρίζομαι σφάλματα API και όρια κλήσεων στις υλοποιήσεις εργαλείων;" +> **🤖 Δοκιμάστε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) και ρωτήστε: +> - "Πώς θα ενσωμάτωνα ένα πραγματικό API καιρού όπως το OpenWeatherMap αντί για ψεύτικα δεδομένα;" +> - "Τι κάνει μια καλή περιγραφή εργαλείου που βοηθά το AI να το χρησιμοποιεί σωστά;" +> - "Πώς χειρίζομαι σφάλματα API και όρια ρυθμού στις υλοποιήσεις εργαλείων;" ### Λήψη Αποφάσεων -Όταν ένας χρήστης ρωτά "Ποιος είναι ο καιρός στο Seattle;", το μοντέλο δεν διαλέγει τυχαία ένα εργαλείο. Συγκρίνει την πρόθεση του χρήστη με κάθε περιγραφή εργαλείου που έχει πρόσβαση, βαθμολογεί κάθε ένα για σχετικότητα και επιλέγει τον καλύτερο συνδυασμό. Έπειτα δημιουργεί μια δομημένη κλήση λειτουργίας με τα σωστά ορίσματα — σε αυτή την περίπτωση, ορίζοντας `location` σε `"Seattle"`. +Όταν ένας χρήστης ρωτά "Ποιος είναι ο καιρός στο Σιάτλ;", το μοντέλο δεν διαλέγει τυχαία ένα εργαλείο. Συγκρίνει την πρόθεση του χρήστη με κάθε περιγραφή εργαλείου που έχει στη διάθεσή του, βαθμολογεί το καθένα για συνάφεια, και επιλέγει την καλύτερη αντιστοίχιση. Μετά παράγει μια δομημένη κλήση λειτουργίας με τις σωστές παραμέτρους — σε αυτή την περίπτωση, ορίζοντας το `location` σε `"Seattle"`. -Αν κανένα εργαλείο δεν ταιριάζει στο αίτημα, το μοντέλο επιστρέφει απάντηση από τη δική του γνώση. Αν ταιριάζουν πολλά εργαλεία, επιλέγει το πιο συγκεκριμένο. +Αν κανένα εργαλείο δεν ταιριάζει στο αίτημα του χρήστη, το μοντέλο επιστρέφει απάντηση από τη δική του γνώση. Αν ταιριάζουν πολλά εργαλεία, επιλέγει το πιο συγκεκριμένο. -Πώς το AI Αποφασίζει Ποιο Εργαλείο να Χρησιμοποιήσει +Πώς Αποφασίζει το AI Ποιο Εργαλείο να Χρησιμοποιήσει -*Το μοντέλο αξιολογεί κάθε διαθέσιμο εργαλείο βάσει της πρόθεσης του χρήστη και επιλέγει το καλύτερο — γι' αυτό είναι σημαντικό να γράφετε σαφείς, συγκεκριμένες περιγραφές εργαλείων.* +*Το μοντέλο αξιολογεί κάθε διαθέσιμο εργαλείο με βάση την πρόθεση του χρήστη και επιλέγει την καλύτερη αντιστοίχιση — γι’ αυτό είναι σημαντικό να γράφετε σαφείς, συγκεκριμένες περιγραφές εργαλείων.* ### Εκτέλεση [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Το Spring Boot αυτόματα δένει τη δηλωτική διεπαφή `@AiService` με όλα τα καταχωρημένα εργαλεία, και το LangChain4j εκτελεί τις κλήσεις εργαλείων αυτόματα. Πίσω από τις σκηνές, μια πλήρης κλήση εργαλείου περνάει από έξι στάδια — από την ερώτηση του χρήστη σε φυσική γλώσσα μέχρι την τελική απάντηση σε φυσική γλώσσα: +Το Spring Boot δρομολογεί αυτόματα τη δηλωτική διεπαφή `@AiService` με όλα τα εγγεγραμμένα εργαλεία, και το LangChain4j εκτελεί τις κλήσεις εργαλείων αυτόματα. Στο παρασκήνιο, μια ολοκληρωμένη κλήση εργαλείου περνάει από έξι στάδια — από την ερώτηση του χρήστη σε φυσική γλώσσα έως την απάντηση σε φυσική γλώσσα: Ροή Κλήσης Εργαλείου -*Η πλήρης ροή — ο χρήστης κάνει μια ερώτηση, το μοντέλο επιλέγει ένα εργαλείο, το LangChain4j το εκτελεί, και το μοντέλο ενσωματώνει το αποτέλεσμα σε φυσική απάντηση.* +*Η πλήρης ροή — ο χρήστης κάνει μια ερώτηση, το μοντέλο επιλέγει ένα εργαλείο, το LangChain4j το εκτελεί και το μοντέλο ενσωματώνει το αποτέλεσμα σε φυσική απάντηση.* -Αν τρέξατε το [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) στο Module 00, ήδη είδατε αυτό το πρότυπο σε δράση — τα εργαλεία `Calculator` καλούνταν με τον ίδιο τρόπο. Το παρακάτω διάγραμμα ακολουθίας δείχνει ακριβώς τι συνέβη κατά τη διάρκεια εκείνης της επίδειξης: +Στο παρασκήνιο, το `AiServices` τρέχει τον ίδιο βρόχο κλήσης εργαλείων για κάθε εργαλείο — εδώ απεικονίζεται με έναν απλό `Calculator`. Το παρακάτω διάγραμμα ακολουθίας δείχνει ακριβώς τι συμβαίνει: Διάγραμμα Ακολουθίας Κλήσης Εργαλείου -*Ο βρόχος κλήσης εργαλείου από το Quick Start demo — τα `AiServices` στέλνουν το μήνυμά σας και τα σχήματα εργαλείων στο LLM, το LLM απαντά με μια κλήση λειτουργίας όπως `add(42, 58)`, το LangChain4j εκτελεί τοπικά τη μέθοδο του `Calculator` και τροφοδοτεί το αποτέλεσμα πίσω για την τελική απάντηση.* +*Ο βρόχος κλήσης εργαλείου — το `AiServices` στέλνει το μήνυμά σας και το σχήμα εργαλείων στο LLM, το LLM απαντά με κλήση λειτουργίας όπως `add(42, 58)`, το LangChain4j εκτελεί τη μέθοδο `Calculator` τοπικά και επιστρέφει το αποτέλεσμα για την τελική απάντηση.* -> **🤖 Δοκιμάστε με το [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) και ρωτήστε: -> - "Πώς λειτουργεί το πρότυπο ReAct και γιατί είναι αποτελεσματικό για πράκτορες AI;" +> **🤖 Δοκιμάστε με [GitHub Copilot](https://github.com/features/copilot) Chat:** Ανοίξτε το [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) και ρωτήστε: +> - "Πώς δουλεύει το πρότυπο ReAct και γιατί είναι αποτελεσματικό για πράκτορες AI;" > - "Πώς αποφασίζει ο πράκτορας ποιο εργαλείο να χρησιμοποιήσει και με ποια σειρά;" -> - "Τι συμβαίνει αν αποτύχει η εκτέλεση εργαλείου - πώς πρέπει να χειριστώ τα σφάλματα αναλυτικά;" +> - "Τι γίνεται αν αποτύχει μια εκτέλεση εργαλείου - πώς να χειριστώ τα σφάλματα σωστά;" ### Δημιουργία Απάντησης -Το μοντέλο λαμβάνει τα δεδομένα καιρού και τα διαμορφώνει σε απάντηση φυσικής γλώσσας για τον χρήστη. +Το μοντέλο λαμβάνει τα δεδομένα καιρού και τα μορφοποιεί σε μια απάντηση σε φυσική γλώσσα για τον χρήστη. -### Αρχιτεκτονική: Αυτόματη Δέσμευση στο Spring Boot +### Αρχιτεκτονική: Αυτόματη Δρομολόγηση Spring Boot -Αυτό το module χρησιμοποιεί την ενσωμάτωση του LangChain4j με το Spring Boot μέσω δηλωτικών διεπαφών `@AiService`. Κατά την εκκίνηση, το Spring Boot ανακαλύπτει κάθε `@Component` που περιέχει μεθόδους `@Tool`, το bean του `ChatModel` και τον `ChatMemoryProvider` — και τα συνδέει όλα σε μια μοναδική διεπαφή `Assistant` με μηδενικό μπούσουλα (boilerplate). +Αυτή η ενότητα χρησιμοποιεί την ενσωμάτωση LangChain4j με το Spring Boot και τις δηλωτικές διεπαφές `@AiService`. Κατά την εκκίνηση το Spring Boot εντοπίζει κάθε `@Component` που περιέχει μεθόδους `@Tool`, το bean `ChatModel`, και τον `ChatMemoryProvider` — και τα δρομολογεί όλα σε μια ενιαία διεπαφή `Assistant` χωρίς παραλληλισμούς κώδικα. -Αρχιτεκτονική Αυτόματης Δέσμευσης Spring Boot +Αρχιτεκτονική Αυτόματης Δρομολόγησης Spring Boot -*Η διεπαφή @AiService συνδέει το ChatModel, τα συστατικά εργαλείων και τον πάροχο μνήμης — το Spring Boot διαχειρίζεται αυτόματα τη δέσμευση.* +*Η διεπαφή @AiService δένει μαζί το ChatModel, τα συστατικά εργαλείων και τον πάροχο μνήμης — το Spring Boot χειρίζεται όλη τη δρομολόγηση αυτόματα.* -Εδώ είναι ο πλήρης κύκλος ζωής του αιτήματος ως διάγραμμα ακολουθίας — από το HTTP request μέσω του controller, του service και του auto-wired proxy, έως την εκτέλεση του εργαλείου και την επιστροφή: +Εδώ είναι ο πλήρης κύκλος ζωής του αιτήματος ως διάγραμμα ακολουθίας — από το HTTP αίτημα, μέσα από τον controller, την υπηρεσία και τον αυτόματα δρομολογημένο proxy, μέχρι την εκτέλεση του εργαλείου και πίσω: -Διάγραμμα Ακολουθίας Κλήσης Εργαλείου στο Spring Boot +Διάγραμμα Ακολουθίας Κλήσης Εργαλείου Spring Boot -*Ο πλήρης κύκλος ζωής του αιτήματος στο Spring Boot — το HTTP request περνάει από τον controller και το service στον auto-wired proxy του Assistant, που ενορχηστρώνει το LLM και τις κλήσεις εργαλείων αυτόματα.* +*Ο πλήρης κύκλος ζωής αιτήματος Spring Boot — το αίτημα HTTP περνά μέσα από τον controller και την υπηρεσία προς τον αυτόματα δρομολογημένο proxy Assistant, που οργανώνει το LLM και τις κλήσεις εργαλειών αυτόματα.* Κύρια οφέλη αυτής της προσέγγισης: -- **Αυτόματη δέσμευση του Spring Boot** — Το ChatModel και τα εργαλεία εγχέονται αυτόματα +- **Αυτόματη δρομολόγηση Spring Boot** — ChatModel και εργαλεία εγχέονται αυτόματα - **Πρότυπο @MemoryId** — Αυτόματη διαχείριση μνήμης βάσει συνεδρίας -- **Μοναδικό στιγμιότυπο** — Ο Assistant δημιουργείται μία φορά και επαναχρησιμοποιείται για καλύτερη απόδοση -- **Εκτέλεση με ασφάλεια τύπων** — Κλήση Java μεθόδων απευθείας με μετατροπή τύπων -- **Πολυβηματική ορχήστρωση** — Διαχειρίζεται αλυσιδωτή χρήση εργαλείων αυτόματα -- **Μηδενικό μπούσουλα** — Χωρίς χειροκίνητες κλήσεις `AiServices.builder()` ή μνήμη HashMap +- **Μοναδική περίπτωση** — Ο Assistant δημιουργείται μία φορά και επαναχρησιμοποιείται για καλύτερη απόδοση +- **Εκτέλεση με τύπους ασφαλείς** — Κλήση Java μεθόδων απευθείας με μετατροπή τύπων +- **Διαχείριση πολλαπλών βημάτων** — Αντιμετωπίζει αυτόματα την αλυσιδωτή χρήση εργαλείων +- **Μηδενικός παραλληλισμός** — Δεν απαιτούνται χειροκίνητες κλήσεις `AiServices.builder()` ή memory HashMap -Εναλλακτικές προσεγγίσεις (χειροκίνητο `AiServices.builder()`) απαιτούν περισσότερο κώδικα και στερούνται τα πλεονεκτήματα ενσωμάτωσης με το Spring Boot. +Εναλλακτικές προσεγγίσεις (χειροκίνητο `AiServices.builder()`) απαιτούν περισσότερο κώδικα και χάνουν τα οφέλη της ενσωμάτωσης Spring Boot. ## Αλυσιδωτή Χρήση Εργαλείων -**Αλυσιδωτή Χρήση Εργαλείων** — Η πραγματική δύναμη των πρακτόρων με εργαλεία δείχνει όταν μια ερώτηση απαιτεί πολλαπλά εργαλεία. Ρωτήστε "Ποιος είναι ο καιρός στο Seattle σε βαθμούς Φαρενάιτ;" και ο πράκτορας αλυσιδώνει αυτόματα δύο εργαλεία: πρώτα καλεί το `getCurrentWeather` για να πάρει τη θερμοκρασία σε Κελσίου, και μετά περνάει αυτό το αποτέλεσμα στο `celsiusToFahrenheit` για μετατροπή — όλα σε μία μόνο στροφή συνομιλίας. +**Αλυσιδωτή Χρήση Εργαλείων** — Η πραγματική δύναμη των πράκτορων βασισμένων σε εργαλεία φαίνεται όταν μια ερώτηση απαιτεί πολλά εργαλεία. Ρωτήστε "Ποιος είναι ο καιρός στο Σιάτλ σε Φαρενάιτ;" και ο πράκτορας αλυσιδωτά συνδυάζει δύο εργαλεία: πρώτα καλεί το `getCurrentWeather` για να πάρει τη θερμοκρασία σε Κελσίου, μετά περνά αυτή την τιμή στο `celsiusToFahrenheit` για μετατροπή — όλα σε μια συνομιλία. Παράδειγμα Αλυσιδωτής Χρήσης Εργαλείων -*Αλυσιδωτή χρήση εργαλείων σε δράση — ο πράκτορας καλεί πρώτα το getCurrentWeather, μετά διοχετεύει το αποτέλεσμα σε Κελσίου στο celsiusToFahrenheit, και δίνει μια συνδυασμένη απάντηση.* +*Αλυσιδωτή χρήση εργαλείων σε δράση — ο πράκτορας πρώτα καλεί το getCurrentWeather, μετά περνά το αποτέλεσμα σε Κελσίου στο celsiusToFahrenheit και δίνει συνδυασμένη απάντηση.* -**Ομαλές Αποτυχίες** — Ζητήστε καιρό σε μια πόλη που δεν υπάρχει στα δεδομένα προσομοίωσης. Το εργαλείο επιστρέφει μήνυμα σφάλματος, και το AI εξηγεί ότι δεν μπορεί να βοηθήσει αντί να καταρρεύσει. Τα εργαλεία αποτυγχάνουν με ασφάλεια. Το διάγραμμα παρακάτω συγκρίνει τις δύο προσεγγίσεις — με σωστή διαχείριση σφαλμάτων, ο πράκτορας καταφέρνει την εξαίρεση και απαντά βοηθητικά, ενώ χωρίς αυτήν η εφαρμογή καταρρέει εντελώς: +**Απαλά Σφάλματα** — Ζητήστε τον καιρό σε μια πόλη που δεν υπάρχει στα ψεύτικα δεδομένα. Το εργαλείο επιστρέφει μήνυμα σφάλματος και το AI εξηγεί ότι δεν μπορεί να βοηθήσει αντί να καταρρεύσει η εφαρμογή. Τα εργαλεία αποτυγχάνουν με ασφάλεια. Το παρακάτω διάγραμμα συγκρίνει τις δύο προσεγγίσεις — με σωστή διαχείριση σφαλμάτων, ο πράκτορας πιάνει την εξαίρεση και απαντά χρήσιμα, ενώ χωρίς αυτή η εφαρμογή καταρρέει: Ροή Διαχείρισης Σφαλμάτων -*Όταν ένα εργαλείο αποτυγχάνει, ο πράκτορας πιάνει το σφάλμα και απαντά με μια χρήσιμη εξήγηση αντί να καταρρεύσει.* +*Όταν αποτυγχάνει ένα εργαλείο, ο πράκτορας πιάνει το σφάλμα και απαντά με χρήσιμη εξήγηση αντί να καταρρεύσει.* -Αυτό γίνεται σε μία μόνο στροφή συνομιλίας. Ο πράκτορας ενορχηστρώνει αυτόνομα πολλαπλές κλήσεις εργαλείων. +Αυτό συμβαίνει σε μια μόνο συνομιλία. Ο πράκτορας οργανώνει αυτόνομα πολλαπλές κλήσεις εργαλείων. ## Εκτέλεση της Εφαρμογής -**Επαλήθευση ανάπτυξης:** +**Επιβεβαίωση ανάπτυξης:** -Εξασφαλίστε ότι το αρχείο `.env` υπάρχει στον ριζικό φάκελο με διαπιστευτήρια Azure (δημιουργήθηκε κατά το Module 01). Εκτελέστε αυτό από τον φάκελο του module (`04-tools/`): +Βεβαιωθείτε ότι το αρχείο `.env` υπάρχει στον αρχικό φάκελο με διαπιστευτήρια Azure (δημιουργήθηκε κατά την Ενότητα 01). Εκτελέστε από το φάκελο της ενότητας (`04-tools/`): **Bash:** ```bash -cat ../.env # Θα πρέπει να εμφανιστεί το AZURE_OPENAI_ENDPOINT, το API_KEY, το DEPLOYMENT +cat ../.env # Θα πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, το API_KEY, το DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, το API_KEY, το DEPLOYMENT +Get-Content ..\.env # Πρέπει να εμφανίζει το AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Εκκινήστε την εφαρμογή:** +**Εκκίνηση της εφαρμογής:** -> **Σημείωση:** Αν έχετε ήδη εκκινήσει όλες τις εφαρμογές χρησιμοποιώντας `./start-all.sh` από τον ριζικό φάκελο (όπως περιγράφεται στο Module 01), αυτό το module τρέχει ήδη στη θύρα 8084. Μπορείτε να παραλείψετε τις παρακάτω εντολές εκκίνησης και να μεταβείτε απευθείας στο http://localhost:8084. +> **Σημείωση:** Αν έχετε ήδη ξεκινήσει όλες τις εφαρμογές χρησιμοποιώντας το `./start-all.sh` από τον αρχικό φάκελο (όπως περιγράφεται στην Ενότητα 01), αυτή η ενότητα ήδη τρέχει στη θύρα 8084. Μπορείτε να παραλείψετε τις εντολές εκκίνησης παρακάτω και να μεταβείτε απευθείας στο http://localhost:8084. **Επιλογή 1: Χρήση του Spring Boot Dashboard (Συνιστάται για χρήστες VS Code)** -Το container ανάπτυξης περιλαμβάνει την επέκταση Spring Boot Dashboard, που παρέχει οπτική διεπαφή για τη διαχείριση όλων των εφαρμογών Spring Boot. Μπορείτε να τη βρείτε στο Activity Bar στο αριστερό μέρος του VS Code (αναζητήστε το εικονίδιο Spring Boot). +Το περιβάλλον ανάπτυξης περιλαμβάνει την επέκταση Spring Boot Dashboard, που παρέχει οπτικό περιβάλλον για τη διαχείριση όλων των εφαρμογών Spring Boot. Μπορείτε να τη βρείτε στη γραμμή δραστηριότητας αριστερά στο VS Code (αναζητήστε το εικονίδιο Spring Boot). Από το Spring Boot Dashboard, μπορείτε: -- Να δείτε όλες τις διαθέσιμες εφαρμογές Spring Boot στο workspace +- Να δείτε όλες τις διαθέσιμες εφαρμογές Spring Boot στον χώρο εργασίας - Να ξεκινήσετε/σταματήσετε εφαρμογές με ένα κλικ - Να δείτε logs εφαρμογών σε πραγματικό χρόνο - Να παρακολουθείτε την κατάσταση των εφαρμογών -Απλώς κάντε κλικ στο κουμπί αναπαραγωγής δίπλα στο "εργαλεία" για να ξεκινήσετε αυτό το module ή ξεκινήστε όλα τα modules ταυτόχρονα. -Ακολουθεί πώς φαίνεται το Spring Boot Dashboard στο VS Code: +Απλώς κάντε κλικ στο κουμπί αναπαραγωγής δίπλα στο "tools" για να ξεκινήσει αυτή η ενότητα, ή να ξεκινήσετε όλες τις ενότητες μαζί. +Δείτε πώς εμφανίζεται το Spring Boot Dashboard στο VS Code: Πίνακας Ελέγχου Spring Boot -*Ο Πίνακας Ελέγχου Spring Boot στο VS Code — εκκίνηση, διακοπή και παρακολούθηση όλων των modules από ένα σημείο* +*Ο Πίνακας Ελέγχου Spring Boot στο VS Code — εκκίνηση, διακοπή και παρακολούθηση όλων των μονάδων από ένα μέρος* **Επιλογή 2: Χρήση shell scripts** -Ξεκινήστε όλες τις διαδικτυακές εφαρμογές (modules 01-04): +Εκκίνηση όλων των web εφαρμογών (μονάδες 01-04): **Bash:** ```bash @@ -242,7 +242,7 @@ cd .. # Από τον ριζικό κατάλογο .\start-all.ps1 ``` -Ή ξεκινήστε μόνο αυτό το module: +Ή εκκίνηση μόνο αυτής της μονάδας: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Και τα δύο scripts φορτώνουν αυτόματα μεταβλητές περιβάλλοντος από το κεντρικό αρχείο `.env` και θα δημιουργήσουν τα JARs αν δεν υπάρχουν. +Και τα δύο scripts φορτώνουν αυτόματα τις μεταβλητές περιβάλλοντος από το αρχείο root `.env` και θα δημιουργήσουν τα JARs αν δεν υπάρχουν. -> **Σημείωση:** Αν προτιμάτε να δημιουργήσετε χειροκίνητα όλα τα modules πριν την εκκίνηση: +> **Σημείωση:** Αν προτιμάτε να δημιουργήσετε όλες τις μονάδες χειροκίνητα πριν την εκκίνηση: > > **Bash:** > ```bash @@ -272,116 +272,116 @@ cd 04-tools > mvn clean package -DskipTests > ``` -Ανοίξτε το http://localhost:8084 στον περιηγητή σας. +Ανοίξτε http://localhost:8084 στον περιηγητή σας. **Για διακοπή:** **Bash:** ```bash -./stop.sh # Μόνο αυτό το module +./stop.sh # Μόνο αυτό το μοντέλο # Ή -cd .. && ./stop-all.sh # Όλα τα modules +cd .. && ./stop-all.sh # Όλα τα μοντέλα ``` **PowerShell:** ```powershell -.\stop.ps1 # Μόνο αυτό το module +.\stop.ps1 # Μόνο αυτό το μονάδα # Ή -cd ..; .\stop-all.ps1 # Όλα τα modules +cd ..; .\stop-all.ps1 # Όλες οι μονάδες ``` ## Χρήση της Εφαρμογής -Η εφαρμογή παρέχει διεπαφή ιστού όπου μπορείτε να αλληλεπιδράσετε με έναν πράκτορα AI που έχει πρόσβαση σε εργαλεία καιρού και μετατροπής θερμοκρασίας. Δείτε πώς φαίνεται η διεπαφή — περιλαμβάνει παραδείγματα γρήγορης εκκίνησης και πάνελ συνομιλίας για αποστολή αιτημάτων: +Η εφαρμογή παρέχει μια web διεπαφή όπου μπορείτε να αλληλεπιδράσετε με έναν AI πράκτορα που έχει πρόσβαση σε εργαλεία καιρού και μετατροπής θερμοκρασίας. Δείτε πώς φαίνεται η διεπαφή — περιλαμβάνει παραδείγματα γρήγορης εκκίνησης και πλαίσιο συνομιλίας για αποστολή αιτημάτων: -Διεπαφή Εργαλείων Πράκτορα AI +Διεπαφή Εργαλείων AI Πράκτορα -*Η διεπαφή εργαλείων Πράκτορα AI - γρήγορα παραδείγματα και συνομιλιακή διεπαφή για αλληλεπίδραση με εργαλεία* +*Η διεπαφή Εργαλείων AI Πράκτορα - γρήγορα παραδείγματα και πλαίσιο συνομιλίας για αλληλεπίδραση με τα εργαλεία* ### Δοκιμάστε Απλή Χρήση Εργαλείου -Ξεκινήστε με ένα απλό αίτημα: "Μετατρέψτε 100 βαθμούς Fahrenheit σε Κελσίου". Ο πράκτορας αναγνωρίζει ότι χρειάζεται το εργαλείο μετατροπής θερμοκρασίας, το καλεί με τις σωστές παραμέτρους και επιστρέφει το αποτέλεσμα. Παρατηρήστε πόσο φυσικό φαίνεται — δεν υποδείξατε ποιο εργαλείο να χρησιμοποιήσει ή πώς να το καλέσει. +Ξεκινήστε με ένα απλό αίτημα: "Μετατρέψτε 100 βαθμούς Φαρενάιτ σε Κελσίου". Ο πράκτορας αναγνωρίζει ότι χρειάζεται το εργαλείο μετατροπής θερμοκρασίας, το καλεί με τις σωστές παραμέτρους και επιστρέφει το αποτέλεσμα. Παρατηρήστε πόσο φυσικό φαίνεται — δεν ορίσατε ποιο εργαλείο να χρησιμοποιηθεί ή πώς να το καλέσετε. -### Δοκιμάστε Αλυσίδωση Εργαλείων +### Δοκιμάστε Αλυσιδωτή Χρήση Εργαλείων -Τώρα δοκιμάστε κάτι πιο πολύπλοκο: "Ποιος είναι ο καιρός στο Σιάτλ και μετατρέψτε τον σε Fahrenheit;" Παρακολουθήστε τον πράκτορα να το εκτελεί σε βήματα. Πρώτα παίρνει τον καιρό (που επιστρέφει σε Κελσίου), αναγνωρίζει ότι πρέπει να τον μετατρέψει σε Fahrenheit, καλεί το εργαλείο μετατροπής και συνδυάζει τα αποτελέσματα σε μία απάντηση. +Τώρα δοκιμάστε κάτι πιο περίπλοκο: "Ποιος είναι ο καιρός στο Σιάτλ και μετατρέψτε τον σε Φαρενάιτ;" Παρακολουθήστε τον πράκτορα να εργάζεται βήμα-βήμα. Πρώτα παίρνει τον καιρό (που επιστρέφει σε Κελσίου), αναγνωρίζει ότι χρειάζεται να μετατρέψει σε Φαρενάιτ, καλεί το εργαλείο μετατροπής και συνδυάζει τα δύο αποτελέσματα σε μία απάντηση. ### Δείτε τη Ροή της Συνομιλίας -Η διεπαφή συνομιλίας διατηρεί το ιστορικό της συνομιλίας, επιτρέποντάς σας να έχετε αλληλεπιδράσεις πολλών γύρων. Μπορείτε να δείτε όλα τα προηγούμενα ερωτήματα και απαντήσεις, καθιστώντας εύκολο να παρακολουθείτε τη συνομιλία και να κατανοήσετε πώς ο πράκτορας χτίζει το πλαίσιο μέσα από πολλαπλές ανταλλαγές. +Η διεπαφή συνομιλίας διατηρεί το ιστορικό της συνομιλίας, επιτρέποντάς σας να έχετε αλληλεπιδράσεις πολλών γύρων. Μπορείτε να δείτε όλα τα προηγούμενα ερωτήματα και απαντήσεις, κάνοντας εύκολο το να παρακολουθείτε τη συνομιλία και να κατανοείτε πώς ο πράκτορας χτίζει το πλαίσιο μέσα από πολλαπλές ανταλλαγές. Συνομιλία με Πολλαπλές Κλήσεις Εργαλείων -*Πολλαπλής γύρου συνομιλία που δείχνει απλές μετατροπές, αναζητήσεις καιρού και αλυσίδωση εργαλείων* +*Συνομιλία πολλών γύρων που δείχνει απλές μετατροπές, αναζητήσεις καιρού και αλυσιδωτή χρήση εργαλείων* -### Πειραματιστείτε με Διάφορα Αίτήματα +### Πειραματιστείτε με Διάφορα Αιτήματα Δοκιμάστε διάφορους συνδυασμούς: - Αναζητήσεις καιρού: "Ποιος είναι ο καιρός στο Τόκιο;" - Μετατροπές θερμοκρασίας: "Πόσο είναι 25°C σε Κέλβιν;" - Συνδυασμένα ερωτήματα: "Ελέγξτε τον καιρό στο Παρίσι και πείτε μου αν είναι πάνω από 20°C" -Παρατηρήστε πώς ο πράκτορας ερμηνεύει τη φυσική γλώσσα και τη μεταφράζει σε κατάλληλες κλήσεις εργαλείων. +Παρατηρήστε πώς ο πράκτορας ερμηνεύει τη φυσική γλώσσα και τη χαρτογραφεί σε κατάλληλες κλήσεις εργαλείων. -## Βασικές Έννοιες +## Κύριες Έννοιες -### Πρότυπο ReAct (Λογισμός και Δράση) +### Πρότυπο ReAct (Σκέψη και Δράση) -Ο πράκτορας εναλλάσσεται μεταξύ λογισμού (αποφασίζοντας τι να κάνει) και δράσης (χρησιμοποιώντας εργαλεία). Αυτό το πρότυπο επιτρέπει αυτόνομη επίλυση προβλημάτων αντί απλώς ανταπόκριση σε εντολές. +Ο πράκτορας εναλλάσσεται μεταξύ σκέψης (αποφασίζοντας τι να κάνει) και δράσης (χρησιμοποιώντας εργαλεία). Αυτό το πρότυπο επιτρέπει αυτόνομη επίλυση προβλημάτων αντί απλώς να ανταποκρίνεται σε οδηγίες. ### Σημασία Περιγραφών Εργαλείων -Η ποιότητα των περιγραφών των εργαλείων επηρεάζει άμεσα το πόσο καλά τα χρησιμοποιεί ο πράκτορας. Καθαρές, συγκεκριμένες περιγραφές βοηθούν το μοντέλο να κατανοεί πότε και πώς να καλεί κάθε εργαλείο. +Η ποιότητα των περιγραφών των εργαλείων σας επηρεάζει άμεσα το πόσο καλά τα χρησιμοποιεί ο πράκτορας. Καθαρές, συγκεκριμένες περιγραφές βοηθούν το μοντέλο να κατανοεί πότε και πώς να καλεί κάθε εργαλείο. ### Διαχείριση Συνεδρίας -Η ανάλωση `@MemoryId` επιτρέπει αυτόματη διαχείριση μνήμης βάσει συνεδριών. Κάθε αναγνωριστικό συνεδρίας λαμβάνει τη δική του `ChatMemory` instance που διαχειρίζεται το bean `ChatMemoryProvider`, ώστε πολλοί χρήστες να μπορούν να αλληλεπιδρούν με τον πράκτορα ταυτόχρονα χωρίς να αναμιγνύονται οι συνομιλίες τους. Το παρακάτω διάγραμμα δείχνει πώς πολλοί χρήστες δρομολογούνται σε απομονωμένες αποθήκες μνήμης με βάση τα IDs συνεδρίας τους: +Η `@MemoryId` ανάρτηση επιτρέπει αυτόματη διαχείριση μνήμης βάσει συνεδρίας. Κάθε αναγνωριστικό συνεδρίας λαμβάνει δική του `ChatMemory` παρουσία που διαχειρίζεται το bean `ChatMemoryProvider`, έτσι πολλοί χρήστες μπορούν να αλληλεπιδράσουν με τον πράκτορα ταυτόχρονα χωρίς να αναμειγνύονται οι συνομιλίες τους. Το παρακάτω διάγραμμα δείχνει πώς πολλοί χρήστες κατευθύνονται σε απομονωμένα καταστήματα μνήμης βάσει των αναγνωριστικών συνεδρίας τους: -Διαχείριση Συνεδριών με @MemoryId +Διαχείριση Συνεδρίας με @MemoryId -*Κάθε αναγνωριστικό συνεδρίας χαρτογραφείται σε απομονωμένο ιστορικό συνομιλίας — οι χρήστες δεν βλέπουν ποτέ τα μηνύματα άλλων.* +*Κάθε αναγνωριστικό συνεδρίας αντιστοιχίζεται σε απομονωμένο ιστορικό συνομιλίας — οι χρήστες δεν βλέπουν ποτέ τα μηνύματα ο ένας του άλλου.* ### Διαχείριση Σφαλμάτων -Τα εργαλεία μπορεί να αποτύχουν — χρόνοι λήξης API, άκυρες παράμετροι, αποτυχίες εξωτερικών υπηρεσιών. Οι πράκτορες παραγωγής χρειάζονται διαχείριση σφαλμάτων ώστε το μοντέλο να εξηγεί προβλήματα ή να δοκιμάζει εναλλακτικές χωρίς την κατάρρευση ολόκληρης εφαρμογής. Όταν ένα εργαλείο ρίχνει εξαίρεση, το LangChain4j τη συλλαμβάνει και τροφοδοτεί το μήνυμα λάθους πίσω στο μοντέλο, το οποίο μπορεί τότε να εξηγήσει το πρόβλημα σε φυσική γλώσσα. +Τα εργαλεία μπορεί να αποτύχουν — οι API έχουν χρονικό όριο, παράμετροι μπορεί να είναι άκυρες, εξωτερικές υπηρεσίες να πέσουν. Οι παραγωγικοί πράκτορες χρειάζονται χειρισμό σφαλμάτων ώστε το μοντέλο να μπορεί να εξηγεί προβλήματα ή να προσπαθεί εναλλακτικές αντί να καταρρέει ολόκληρη η εφαρμογή. Όταν ένα εργαλείο πετάει εξαίρεση, το LangChain4j την πιάνει και τροφοδοτεί το μήνυμα σφάλματος πίσω στο μοντέλο, που τότε μπορεί να εξηγήσει το πρόβλημα σε φυσική γλώσσα. ## Διαθέσιμα Εργαλεία -Το παρακάτω διάγραμμα δείχνει το ευρύ οικοσύστημα εργαλείων που μπορείτε να δημιουργήσετε. Αυτό το module δείχνει εργαλεία καιρού και θερμοκρασίας, αλλά το ίδιο πρότυπο `@Tool` λειτουργεί για οποιαδήποτε μέθοδο Java — από ερωτήματα βάσεων δεδομένων μέχρι επεξεργασία πληρωμών. +Το παρακάτω διάγραμμα δείχνει το εκτενές οικοσύστημα εργαλείων που μπορείτε να δημιουργήσετε. Αυτή η μονάδα παρουσιάζει εργαλεία καιρού και θερμοκρασίας, αλλά το ίδιο πρότυπο `@Tool` λειτουργεί για οποιαδήποτε μέθοδο Java — από ερωτήματα βάσεων δεδομένων μέχρι επεξεργασία πληρωμών. Οικοσύστημα Εργαλείων -*Οποιαδήποτε μέθοδος Java σημειωμένη με @Tool γίνεται διαθέσιμη στην AI — το πρότυπο επεκτείνεται σε βάσεις δεδομένων, API, email, λειτουργίες αρχείων και άλλα.* +*Οποιαδήποτε μέθοδος Java με την ανάρτηση @Tool γίνεται διαθέσιμη για τον AI — το πρότυπο επεκτείνεται σε βάσεις δεδομένων, APIs, email, λειτουργίες αρχείων και άλλα.* -## Πότε να Χρησιμοποιήσετε Πράκτορες με Εργαλεία +## Πότε να Χρησιμοποιείτε Πράκτορες με Βάση τα Εργαλεία -Δεν χρειάζονται όλα τα αιτήματα εργαλεία. Η απόφαση εξαρτάται από το αν η AI πρέπει να αλληλεπιδράσει με εξωτερικά συστήματα ή μπορεί να απαντήσει από τις δικές της γνώσεις. Ο παρακάτω οδηγός συνοψίζει πότε τα εργαλεία προσθέτουν αξία και πότε είναι περιττά: +Όχι κάθε αίτημα χρειάζεται εργαλεία. Η απόφαση εξαρτάται από το αν ο AI χρειάζεται να αλληλεπιδράσει με εξωτερικά συστήματα ή μπορεί να απαντήσει από τη δική του γνώση. Ο παρακάτω οδηγός συνοψίζει πότε τα εργαλεία προσθέτουν αξία και πότε δεν είναι απαραίτητα: -Πότε να Χρησιμοποιήσετε Εργαλεία +Πότε να Χρησιμοποιείτε Εργαλεία -*Γρήγορος οδηγός απόφασης — τα εργαλεία είναι για δεδομένα σε πραγματικό χρόνο, υπολογισμούς και δράσεις· οι γενικές γνώσεις και οι δημιουργικές εργασίες δεν τα χρειάζονται.* +*Ένας γρήγορος οδηγός απόφασης — τα εργαλεία είναι για δεδομένα σε πραγματικό χρόνο, υπολογισμούς και ενέργειες· η γενική γνώση και δημιουργικές εργασίες δεν τα χρειάζονται.* ## Εργαλεία vs RAG -Τα modules 03 και 04 επεκτείνουν την ικανότητα της AI με διαφορετικούς τρόπους. Το RAG δίνει στο μοντέλο πρόσβαση σε **γνώση** ανακτώντας έγγραφα. Τα Εργαλεία δίνουν στο μοντέλο την ικανότητα να αναλαμβάνει **δράσεις** καλώντας λειτουργίες. Το παρακάτω διάγραμμα συγκρίνει τις δύο προσεγγίσεις πλευρά προς πλευρά — από τον τρόπο λειτουργίας κάθε ροής εργασίας μέχρι τα ανταλλάγματα μεταξύ τους: +Οι μονάδες 03 και 04 επεκτείνουν ό,τι μπορεί να κάνει ο AI, αλλά με θεμελιωδώς διαφορετικούς τρόπους. Το RAG δίνει στο μοντέλο πρόσβαση σε **γνώση** ανακτώντας έγγραφα. Τα εργαλεία δίνουν στο μοντέλο τη δυνατότητα να κάνει **ενέργειες** καλώντας λειτουργίες. Το παρακάτω διάγραμμα συγκρίνει αυτές τις δύο προσεγγίσεις παράλληλα — από τον τρόπο λειτουργίας της κάθε ροής εργασίας μέχρι τα ανταλλάγματα μεταξύ τους: -Σύγκριση Εργαλείων με RAG +Σύγκριση Εργαλείων vs RAG -*Το RAG ανακτά πληροφορίες από στατικά έγγραφα — τα Εργαλεία εκτελούν ενέργειες και φέρνουν δυναμικά, ζωντανά δεδομένα. Πολλά συστήματα παραγωγής συνδυάζουν και τα δύο.* +*Το RAG ανακτά πληροφορίες από στατικά έγγραφα — τα Εργαλεία εκτελούν ενέργειες και φέρνουν δυναμικά, ζωντανά δεδομένα. Πολλά παραγωγικά συστήματα συνδυάζουν και τα δύο.* -Στην πράξη, πολλά συστήματα παραγωγής συνδυάζουν τις δύο προσεγγίσεις: RAG για θεμελίωση απαντήσεων στην τεκμηρίωσή σας και Εργαλεία για άντληση ζωντανών δεδομένων ή εκτέλεση λειτουργιών. +Στην πράξη, πολλά παραγωγικά συστήματα συνδυάζουν και τις δύο προσεγγίσεις: RAG για να στηρίξουν απαντήσεις στην τεκμηρίωσή σας, και Εργαλεία για να φέρνουν ζωντανά δεδομένα ή να εκτελούν λειτουργίες. ## Επόμενα Βήματα -**Επόμενο Module:** [05-mcp - Πρωτόκολλο Πλαισίου Μοντέλου (MCP)](../05-mcp/README.md) +**Επόμενη Μονάδα:** [05-mcp - Πρωτόκολλο Συμφραζόμενου Μοντέλου (MCP)](../05-mcp/README.md) --- -**Πλοήγηση:** [← Προηγούμενο: Module 03 - RAG](../03-rag/README.md) | [Επιστροφή στην Αρχική](../README.md) | [Επόμενο: Module 05 - MCP →](../05-mcp/README.md) +**Πλοήγηση:** [← Προηγούμενο: Μονάδα 03 - RAG](../03-rag/README.md) | [Πίσω στην Αρχική](../README.md) | [Επόμενο: Μονάδα 05 - MCP →](../05-mcp/README.md) --- -**Αποποίηση ευθυνών**: -Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης AI [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που επιδιώκουμε την ακρίβεια, παρακαλούμε να λάβετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη γλώσσα του θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες συνιστάται επαγγελματική μετάφραση από ανθρώπους. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. +**Αποποίηση ευθυνών**: +Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. \ No newline at end of file diff --git a/translations/el/README.md b/translations/el/README.md index b92cd3855..6ac972525 100644 --- a/translations/el/README.md +++ b/translations/el/README.md @@ -6,14 +6,14 @@ ### 🌐 Υποστήριξη Πολλών Γλωσσών -#### Υποστηρίζεται μέσω GitHub Action (Αυτοματοποιημένα & Πάντα Ενημερωμένο) +#### Υποστηρίζεται μέσω GitHub Action (Αυτόματη & Πάντα Ενημερωμένη) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](./README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Προτιμάτε να κάνετε κλωνοποίηση τοπικά;** +> **Προτιμάτε τοπική κλωνοποίηση;** > -> Αυτό το αποθετήριο περιλαμβάνει πάνω από 50 μεταφράσεις γλωσσών που αυξάνουν σημαντικά το μέγεθος λήψης. Για να κλωνοποιήσετε χωρίς μεταφράσεις, χρησιμοποιήστε sparse checkout: +> Αποθετήριο περιλαμβάνει πάνω από 50 μεταφράσεις γλωσσών που αυξάνουν σημαντικά το μέγεθος λήψης. Για κλωνοποίηση χωρίς μεταφράσεις, χρησιμοποιήστε sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -34,55 +34,56 @@ ## Πίνακας Περιεχομένων -1. [Γρήγορη Εκκίνηση](00-quick-start/README.md) - Ξεκινήστε με το LangChain4j -2. [Εισαγωγή](01-introduction/README.md) - Μάθετε τα βασικά του LangChain4j -3. [Σχεδιασμός Εντολών (Prompt Engineering)](02-prompt-engineering/README.md) - Κατακτήστε τον αποτελεσματικό σχεδιασμό εντολών -4. [RAG (Αναγεννημένη Παραγωγή μέσω Ανάκτησης)](03-rag/README.md) - Δημιουργήστε έξυπνα συστήματα βάσει γνώσης -5. [Εργαλεία](04-tools/README.md) - Ενσωματώστε εξωτερικά εργαλεία και απλούς βοηθούς -6. [MCP (Πρωτόκολλο Πλαισίου Μοντέλου)](05-mcp/README.md) - Εργαστείτε με το Πρωτόκολλο Πλαισίου Μοντέλου (MCP) και μονάδες Agentic +1. [Εισαγωγή](01-introduction/README.md) - Μάθετε τα βασικά του LangChain4j +2. [Μηχανική Προτροπών](02-prompt-engineering/README.md) - Κατακτήστε τον αποτελεσματικό σχεδιασμό προτροπών +3. [RAG (Γεννήτρια Αναζήτησης)](03-rag/README.md) - Δημιουργήστε ευφυή συστήματα γνώσης +4. [Εργαλεία](04-tools/README.md) - Ενσωματώστε εξωτερικά εργαλεία και απλούς βοηθούς +5. [MCP (Πρωτόκολλο Πλαισίου Μοντέλου)](05-mcp/README.md) - Εργαστείτε με το Πρωτόκολλο Πλαισίου Μοντέλου (MCP) και τα μονάδα Πρακτόρων -### Βίντεο Οδηγίες +### Βίντεο Καθοδήγησης -Κάθε ενότητα έχει μια συνοδευτική ζωντανή συνεδρία όπου περνάμε βήμα-βήμα τις έννοιες και τον κώδικα. +Κάθε ενότητα έχει μια συνοδευτική ζωντανή συνεδρία όπου περιηγούμαστε βήμα προς βήμα τις έννοιες και τον κώδικα. | Ενότητα | Βίντεο | |--------|-------| | 01 - Εισαγωγή | [Ξεκινώντας με το LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Σχεδιασμός Εντολών | [Σχεδιασμός Εντολών με LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 02 - Μηχανική Προτροπών | [Μηχανική Προτροπών με LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG με LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Εργαλεία & 05 - MCP | [Πράκτορες AI με Εργαλεία και MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Μονοπάτι Μάθησης +## Μαθησιακή Διαδρομή -**Νέος στο LangChain4j;** Ρίξτε μια ματιά στο [Γλωσσάρι](docs/GLOSSARY.md) για ορισμούς βασικών όρων και εννοιών. +**Νέος στο LangChain4j;** Δείτε το [Λεξιλόγιο](docs/GLOSSARY.md) για ορισμούς βασικών όρων και εννοιών. > **Γρήγορη Εκκίνηση** -1. Κάντε fork αυτό το αποθετήριο στο λογαριασμό GitHub σας -2. Επιλέξτε **Code** → καρτέλα **Codespaces** → **...** → **Νέο με επιλογές...** -3. Χρησιμοποιήστε τις προεπιλογές – αυτό θα επιλέξει το container ανάπτυξης που δημιουργήθηκε για αυτό το μάθημα -4. Κάντε κλικ στο **Create codespace** -5. Περιμένετε 5-10 λεπτά για να είναι έτοιμο το περιβάλλον -6. Πηδήξτε απευθείας στο [Γρήγορη Εκκίνηση](./00-quick-start/README.md) για να ξεκινήσετε! +1. Κάντε fork αυτό το αποθετήριο στον λογαριασμό σας στο GitHub +2. Κάντε κλικ **Code** → καρτέλα **Codespaces** → **...** → **Νέο με επιλογές...** +3. Χρησιμοποιήστε τις προεπιλογές – αυτό θα επιλέξει το Development container που δημιουργήθηκε για αυτό το μάθημα +4. Κάντε κλικ **Δημιουργία codespace** +5. Περιμένετε 5-10 λεπτά για να ετοιμαστεί το περιβάλλον +6. Μεταβείτε κατευθείαν στην [Εισαγωγή](./01-introduction/README.md) για να ξεκινήσετε! -Μετά την ολοκλήρωση των ενοτήτων, εξερευνήστε τον [Οδηγό Δοκιμών](docs/TESTING.md) για να δείτε τις έννοιες δοκιμών του LangChain4j σε δράση. +Μετά την ολοκλήρωση των ενοτήτων, εξερευνήστε τον [Οδηγό Δοκιμών](docs/TESTING.md) για να δείτε τις έννοιες δοκιμών LangChain4j εν δράσει. -> **Σημείωση:** Αυτή η εκπαίδευση χρησιμοποιεί τόσο τα GitHub Models όσο και Azure OpenAI. Η ενότητα [Γρήγορη Εκκίνηση](00-quick-start/README.md) χρησιμοποιεί GitHub Models (δεν απαιτείται συνδρομή Azure), ενώ οι ενότητες 1-5 χρησιμοποιούν Azure OpenAI. Ξεκινήστε με έναν [ΔΩΡΕΑΝ λογαριασμό Azure](https://aka.ms/azure-free-account) αν δεν έχετε. +> **Σημείωση:** Αυτή η εκπαίδευση χρησιμοποιεί Azure OpenAI. Ξεκινήστε με έναν [ΔΩΡΕΑΝ λογαριασμό Azure](https://aka.ms/azure-free-account) αν δεν έχετε ήδη. -## Μάθηση με το GitHub Copilot -Για να ξεκινήσετε γρήγορα την κωδικοποίηση, ανοίξτε αυτό το έργο σε έναν GitHub Codespace ή στο τοπικό IDE σας με το παρεχόμενο devcontainer. Το devcontainer που χρησιμοποιείται σε αυτό το μάθημα είναι προεγκατεστημένο με GitHub Copilot για προγραμματισμό σε ζευγάρι με AI. +## Μάθηση με GitHub Copilot -Κάθε παράδειγμα κώδικα περιλαμβάνει προτεινόμενες ερωτήσεις που μπορείτε να ρωτήσετε το GitHub Copilot για να εμβαθύνετε την κατανόησή σας. Ψάξτε για τις υποδείξεις 💡/🤖 στα: +Για να ξεκινήσετε γρήγορα τον προγραμματισμό, ανοίξτε αυτό το έργο σε GitHub Codespace ή στον τοπικό IDE σας με το παρεχόμενο devcontainer. Το devcontainer που χρησιμοποιείται σε αυτό το μάθημα έρχεται προ-διαμορφωμένο με GitHub Copilot για προγραμματισμό AI σε ζευγάρι. -- **Κεφαλίδες αρχείων Java** – Ερωτήσεις συγκεκριμένες για κάθε παράδειγμα -- **README των ενοτήτων** – Εξερευνητικά ερωτήματα μετά τα παραδείγματα κώδικα +Κάθε παράδειγμα κώδικα περιλαμβάνει προτεινόμενες ερωτήσεις που μπορείτε να κάνετε στον GitHub Copilot για να εμβαθύνετε την κατανόησή σας. Αναζητήστε τα εικονίδια 💡/🤖 στα: -**Πώς να χρησιμοποιήσετε:** Ανοίξτε οποιοδήποτε αρχείο κώδικα και ρωτήστε το Copilot τις προτεινόμενες ερωτήσεις. Έχει πλήρες πλαίσιο του κώδικα και μπορεί να εξηγεί, να επεκτείνει και να προτείνει εναλλακτικές. +- **Κεφαλίδες αρχείων Java** - Ερωτήσεις ειδικές για κάθε παράδειγμα +- **README των ενοτήτων** - Εξερευνητικές προτροπές μετά από παραδείγματα κώδικα + +**Πώς να χρησιμοποιήσετε:** Ανοίξτε οποιοδήποτε αρχείο κώδικα και κάντε στον Copilot τις προτεινόμενες ερωτήσεις. Διαθέτει πλήρες πλαίσιο για τον κώδικα και μπορεί να εξηγήσει, να επεκτείνει και να προτείνει εναλλακτικές λύσεις. + +Θέλετε να μάθετε περισσότερα; Δείτε το [Copilot για προγραμματισμό AI σε ζευγάρι](https://aka.ms/GitHubCopilotAI). -Θέλετε να μάθετε περισσότερα; Δείτε το [Copilot για Προγραμματισμό AI σε Ζεύγη](https://aka.ms/GitHubCopilotAI). ## Πρόσθετοι Πόροι @@ -102,18 +103,18 @@ --- ### Σειρά Γενετικής Τεχνητής Νοημοσύνης -[![Γενετική Τεχνητή Νοημοσύνη για Αρχάριους](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Γενετική Τεχνητή Νοημοσύνη (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Γενετική Τεχνητή Νοημοσύνη (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Γενετική Τεχνητή Νοημοσύνη (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +[![Γενετική AI για Αρχάριους](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Γενετική AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Γενετική AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Γενετική AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- ### Βασική Μάθηση -[![Μηχανική Μάθηση για Αρχάριους](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![ML για Αρχάριους](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Επιστήμη Δεδομένων για Αρχάριους](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![Τεχνητή Νοημοσύνη για Αρχάριους](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Ασφάλεια στον Κυβερνοχώρο για Αρχάριους](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![AI για Αρχάριους](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![Κυβερνοασφάλεια για Αρχάριους](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) [![Ανάπτυξη Ιστού για Αρχάριους](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT για Αρχάριους](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![Ανάπτυξη XR για Αρχάριους](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -121,14 +122,14 @@ --- ### Σειρά Copilot -[![Copilot για Προγραμματισμό σε Ζεύγη με Τεχνητή Νοημοσύνη](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot για Προγραμματισμό με Συνεργασία AI](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![Copilot για C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![Περιπέτεια Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Λήψη Βοήθειας -Εάν κολλήσετε ή έχετε οποιεσδήποτε ερωτήσεις σχετικά με τη δημιουργία εφαρμογών AI, συμμετάσχετε: +Εάν κολλήσετε ή έχετε ερωτήσεις σχετικά με την ανάπτυξη εφαρμογών AI, εγγραφείτε: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) @@ -143,6 +144,6 @@ --- -**Αποποίηση ευθύνης**: -Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης AI [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που επιδιώκουμε ακρίβεια, παρακαλούμε να γνωρίζετε ότι οι αυτόματες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στην μητρική του γλώσσα πρέπει να θεωρείται η έγκυρη πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για οποιεσδήποτε παρεξηγήσεις ή λανθασμένες ερμηνείες προκύψουν από τη χρήση αυτής της μετάφρασης. +**Αποποίηση ευθυνών**: +Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. \ No newline at end of file diff --git a/translations/el/docs/GLOSSARY.md b/translations/el/docs/GLOSSARY.md index 1130c6463..91f50e0cc 100644 --- a/translations/el/docs/GLOSSARY.md +++ b/translations/el/docs/GLOSSARY.md @@ -1,58 +1,58 @@ -# Ορολογικός Λεξιλόγος LangChain4j +# Λεξικό LangChain4j ## Περιεχόμενα -- [Βασικές Έννοιες](../../../docs) -- [Συστατικά LangChain4j](../../../docs) -- [Έννοιες AI/ML](../../../docs) -- [Φράγματα Ασφαλείας](../../../docs) -- [Μηχανική Προτροπής](../../../docs) -- [RAG (Ανάκτηση-Ενισχυμένη Γενιά)](../../../docs) -- [Πράκτορες και Εργαλεία](../../../docs) -- [Agentic Module](../../../docs) -- [Πρωτόκολλο Πλαισίου Μοντέλου (MCP)](../../../docs) -- [Υπηρεσίες Azure](../../../docs) -- [Δοκιμές και Ανάπτυξη](../../../docs) +- [Βασικές Έννοιες](#βασικές-έννοιες) +- [Συστατικά LangChain4j](#συστατικά-langchain4j) +- [Έννοιες AI/ML](#έννοιες-aiml) +- [Προστατευτικά Μέτρα](#προστατευτικά-μέτρα) +- [Σχεδίαση Προτροπών](#prompt-engineering---module-02) +- [RAG (Ανάκτηση-Ενισχυμένη Γενιά)](#rag-retrieval-augmented-generation---module-03) +- [Πράκτορες και Εργαλεία](#agents-and-tools---module-04) +- [Agentic Module](#agentic-module---module-05) +- [Πρωτόκολλο Πλαισίου Μοντέλου (MCP)](#model-context-protocol-mcp---module-05) +- [Υπηρεσίες Azure](#azure-services---module-01) +- [Δοκιμές και Ανάπτυξη](#testing-and-development---testing-guide) -Γρήγορη αναφορά για όρους και έννοιες που χρησιμοποιούνται σε όλο το μάθημα. +Γρήγορη αναφορά για όρους και έννοιες που χρησιμοποιούνται καθ’ όλη τη διάρκεια του μαθήματος. ## Βασικές Έννοιες -**AI Agent** - Σύστημα που χρησιμοποιεί AI για να συλλογιστεί και να ενεργεί αυτόνομα. [Module 04](../04-tools/README.md) +**AI Agent** - Σύστημα που χρησιμοποιεί ΤΝ για να συλλογιστεί και να δράσει αυτόνομα. [Module 04](../04-tools/README.md) **Chain** - Ακολουθία λειτουργιών όπου η έξοδος τροφοδοτεί το επόμενο βήμα. -**Chunking** - Διαχωρισμός εγγράφων σε μικρότερα κομμάτια. Τυπικά: 300-500 tokens με επικάλυψη. [Module 03](../03-rag/README.md) +**Chunking** - Διαχωρισμός εγγράφων σε μικρότερα τμήματα. Τυπικά: 300-500 tokens με επικάλυψη. [Module 03](../03-rag/README.md) -**Context Window** - Μέγιστος αριθμός tokens που μπορεί να επεξεργαστεί ένα μοντέλο. GPT-5.2: 400K tokens (έως 272K εισόδου, 128K εξόδου). +**Context Window** - Μέγιστος αριθμός token που ένα μοντέλο μπορεί να επεξεργαστεί. GPT-5.2: 400Κ tokens (έως 272Κ εισόδου, 128Κ εξόδου). -**Embeddings** - Αριθμητικοί διανύσματα που αντιπροσωπεύουν το νόημα του κειμένου. [Module 03](../03-rag/README.md) +**Embeddings** - Αριθμητικοί διανύσματα που αναπαριστούν το νόημα του κειμένου. [Module 03](../03-rag/README.md) -**Function Calling** - Το μοντέλο δημιουργεί δομημένα αιτήματα για κλήση εξωτερικών λειτουργιών. [Module 04](../04-tools/README.md) +**Function Calling** - Το μοντέλο δημιουργεί δομημένα αιτήματα για κλήση εξωτερικών συναρτήσεων. [Module 04](../04-tools/README.md) **Hallucination** - Όταν τα μοντέλα παράγουν λανθασμένες αλλά πιθανές πληροφορίες. -**Prompt** - Είσοδος κειμένου σε γλωσσικό μοντέλο. [Module 02](../02-prompt-engineering/README.md) +**Prompt** - Κείμενο εισόδου σε ένα γλωσσικό μοντέλο. [Module 02](../02-prompt-engineering/README.md) **Semantic Search** - Αναζήτηση με βάση το νόημα χρησιμοποιώντας embeddings, όχι λέξεις-κλειδιά. [Module 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: χωρίς μνήμη. Stateful: διατηρεί το ιστορικό συνομιλίας. [Module 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: χωρίς μνήμη. Stateful: διατηρεί ιστορικό συνομιλίας. [Module 01](../01-introduction/README.md) -**Tokens** - Βασικές μονάδες κειμένου που επεξεργάζονται τα μοντέλα. Επηρεάζουν κόστη και περιορισμούς. [Module 01](../01-introduction/README.md) +**Tokens** - Βασικές μονάδες κειμένου που τα μοντέλα επεξεργάζονται. Επηρεάζουν κόστος και όρια. [Module 01](../01-introduction/README.md) -**Tool Chaining** - Διαδοχική εκτέλεση εργαλείων όπου η έξοδος πληροφορεί την επόμενη κλήση. [Module 04](../04-tools/README.md) +**Tool Chaining** - Αλληλουχία εκτέλεσης εργαλείων όπου η έξοδος ενημερώνει την επόμενη κλήση. [Module 04](../04-tools/README.md) ## Συστατικά LangChain4j -**AiServices** - Δημιουργεί τύπου ασφαλή interfaces για AI υπηρεσίες. +**AiServices** - Δημιουργεί τύπος-ασφαλείς διεπαφές υπηρεσιών ΤΝ. **OpenAiOfficialChatModel** - Ενοποιημένος πελάτης για μοντέλα OpenAI και Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Δημιουργεί embeddings χρησιμοποιώντας τον επίσημο πελάτη OpenAI (υποστηρίζει και OpenAI και Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Δημιουργεί embeddings χρησιμοποιώντας τον επίσημο πελάτη OpenAI (υποστηρίζει OpenAI και Azure OpenAI). -**ChatModel** - Βασικό interface για γλωσσικά μοντέλα. +**ChatModel** - Βασική διεπαφή για γλωσσικά μοντέλα. -**ChatMemory** - Διατηρεί το ιστορικό συνομιλίας. +**ChatMemory** - Διατηρεί ιστορικό συνομιλίας. **ContentRetriever** - Βρίσκει σχετικά κομμάτια εγγράφων για RAG. @@ -62,171 +62,169 @@ **EmbeddingStore** - Αποθηκεύει και ανακτά embeddings. -**MessageWindowChatMemory** - Διατηρεί παράθυρο ολίσθησης με πρόσφατα μηνύματα. +**MessageWindowChatMemory** - Διατηρεί κυλιόμενο παράθυρο πρόσφατων μηνυμάτων. -**PromptTemplate** - Δημιουργεί επαναχρησιμοποιήσιμες προτροπές με θέσεις `{{variable}}`. +**PromptTemplate** - Δημιουργεί επαναχρησιμοποιήσιμες προτροπές με placeholders `{{variable}}`. -**TextSegment** - Κομμάτι κειμένου με μεταδεδομένα. Χρησιμοποιείται σε RAG. +**TextSegment** - Τμήμα κειμένου με μεταδεδομένα. Χρησιμοποιείται στο RAG. -**ToolExecutionRequest** - Αντιπροσωπεύει αίτημα εκτέλεσης εργαλείου. +**ToolExecutionRequest** - Αναπαριστά αίτημα εκτέλεσης εργαλείου. **UserMessage / AiMessage / SystemMessage** - Τύποι μηνυμάτων συνομιλίας. ## Έννοιες AI/ML -**Few-Shot Learning** - Παροχή παραδειγμάτων στις προτροπές. [Module 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Παροχή παραδειγμάτων σε προτροπές. [Module 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - Μοντέλα AI εκπαιδευμένα σε τεράστιες ποσότητες κειμένου. +**Large Language Model (LLM)** - Μοντέλα ΤΝ εκπαιδευμένα σε τεράστιο όγκο κειμένων. -**Reasoning Effort** - Παράμετρος GPT-5.2 που ελέγχει το βάθος της σκέψης. [Module 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - Παράμετρος GPT-5.2 που ελέγχει το βάθος σκέψης. [Module 02](../02-prompt-engineering/README.md) -**Temperature** - Ελέγχει την τυχαιότητα στην έξοδο. Χαμηλό=ντετερμινιστικό, υψηλό=δημιουργικό. +**Temperature** - Ελέγχει το βαθμό τυχαιότητας της εξόδου. Χαμηλό=ντετερμινιστικό, υψηλό=δημιουργικό. **Vector Database** - Εξειδικευμένη βάση δεδομένων για embeddings. [Module 03](../03-rag/README.md) **Zero-Shot Learning** - Εκτέλεση εργασιών χωρίς παραδείγματα. [Module 02](../02-prompt-engineering/README.md) -## Φράγματα Ασφαλείας - [Module 00](../00-quick-start/README.md) +## Προστατευτικά Μέτρα -**Defense in Depth** - Πολλαπλό επίπεδο ασφαλείας που συνδυάζει φράγματα στο επίπεδο εφαρμογής με φίλτρα ασφαλείας παρόχου. +**Defense in Depth** - Πολυεπίπεδη προσέγγιση ασφάλειας που συνδυάζει προστατευτικά σε επίπεδο εφαρμογής με φίλτρα ασφαλείας του παρόχου. **Hard Block** - Ο πάροχος επιστρέφει σφάλμα HTTP 400 για σοβαρές παραβιάσεις περιεχομένου. -**InputGuardrail** - Interface LangChain4j για επικύρωση εισόδου χρήστη πριν φτάσει στο LLM. Εξοικονομεί κόστος και καθυστέρηση μπλοκάροντας επιβλαβείς προτροπές νωρίς. +**InputGuardrail** - Διεπαφή LangChain4j για επικύρωση εισόδου χρήστη πριν φτάσει στο LLM. Εξοικονομεί κόστος και καθυστέρηση εμποδίζοντας επιβλαβείς προτροπές νωρίς. -**InputGuardrailResult** - Τύπος επιστροφής για επικύρωση φράγματος: `success()` ή `fatal("reason")`. +**InputGuardrailResult** - Τύπος επιστροφής για επικύρωση guardrail: `success()` ή `fatal("reason")`. -**OutputGuardrail** - Interface για επικύρωση απαντήσεων AI πριν επιστραφούν στους χρήστες. +**OutputGuardrail** - Διεπαφή για επικύρωση απαντήσεων ΤΝ πριν επιστραφούν στον χρήστη. -**Provider Safety Filters** - Ενσωματωμένα φίλτρα περιεχομένου από παρόχους AI (π.χ. GitHub Models) που ανιχνεύουν παραβιάσεις στο επίπεδο API. +**Provider Safety Filters** - Ενσωματωμένα φίλτρα περιεχομένου από παρόχους ΤΝ (π.χ. Azure OpenAI) που ανιχνεύουν παραβάσεις σε επίπεδο API. -**Soft Refusal** - Το μοντέλο αρνείται κόσμια να απαντήσει χωρίς να επιστρέψει σφάλμα. +**Soft Refusal** - Το μοντέλο αρνείται ευγενικά να απαντήσει χωρίς να επιστρέφει σφάλμα. -## Μηχανική Προτροπής - [Module 02](../02-prompt-engineering/README.md) +## Σχεδίαση Προτροπών - [Module 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Σταδιακή επιχειρηματολογία για καλύτερη ακρίβεια. +**Chain-of-Thought** - Βήμα-βήμα συλλογιστική για καλύτερη ακρίβεια. -**Constrained Output** - Επιβολή συγκεκριμένης μορφής ή δομής. +**Constrained Output** - Εφαρμογή συγκεκριμένης μορφής ή δομής. -**High Eagerness** - Πρότυπο GPT-5.2 για σχολαστική συλλογιστική. +**High Eagerness** - Πρότυπο GPT-5.2 για προσεκτική συλλογιστική. **Low Eagerness** - Πρότυπο GPT-5.2 για γρήγορες απαντήσεις. -**Multi-Turn Conversation** - Διατήρηση πλαισίου σε πολλαπλές ανταλλαγές. +**Multi-Turn Conversation** - Διατήρηση πλαισίου κατά τη διάρκεια πολλαπλών ανταλλαγών. -**Role-Based Prompting** - Ορισμός χαρακτήρα μοντέλου μέσω συστημικών μηνυμάτων. +**Role-Based Prompting** - Ορισμός προσωπικότητας μοντέλου μέσω συστημικών μηνυμάτων. -**Self-Reflection** - Το μοντέλο αξιολογεί και βελτιώνει την έξοδο του. +**Self-Reflection** - Το μοντέλο αξιολογεί και βελτιώνει το αποτέλεσμα του. **Structured Analysis** - Σταθερό πλαίσιο αξιολόγησης. -**Task Execution Pattern** - Σχεδίαση → Εκτέλεση → Περίληψη. +**Task Execution Pattern** - Σχεδιάζει → Εκτελεί → Συνοψίζει. ## RAG (Ανάκτηση-Ενισχυμένη Γενιά) - [Module 03](../03-rag/README.md) **Document Processing Pipeline** - Φόρτωση → διαχωρισμός → ενσωμάτωση → αποθήκευση. -**In-Memory Embedding Store** - Μη επίμονος αποθηκευτικός χώρος για δοκιμές. +**In-Memory Embedding Store** - Μη μόνιμη αποθήκευση για δοκιμές. -**RAG** - Συνδυάζει ανάκτηση με παραγωγή για εδραίωση απαντήσεων. +**RAG** - Συνδυάζει ανάκτηση με γενιά για τεκμηρίωση απαντήσεων. -**Similarity Score** - Μέτρο (0-1) σημασιολογικής ομοιότητας. +**Similarity Score** - Μέτρηση (0-1) σημασιολογικής ομοιότητας. -**Source Reference** - Μεταδεδομένα για ανακτημένο περιεχόμενο. +**Source Reference** - Μεταδεδομένα για το ανακτηθέν περιεχόμενο. ## Πράκτορες και Εργαλεία - [Module 04](../04-tools/README.md) -**@Tool Annotation** - Σημειώνει μεθόδους Java ως εργαλεία προσβάσιμα από AI. +**@Tool Annotation** - Σημαδεύει μεθόδους Java ως εργαλεία κλήσιμα από ΤΝ. -**ReAct Pattern** - Συλλογισμός → Δράση → Παρατήρηση → Επανάληψη. +**ReAct Pattern** - Σκέψη → Δράση → Παρατήρηση → Επανάληψη. **Session Management** - Ξεχωριστά πλαίσια για διαφορετικούς χρήστες. -**Tool** - Συνάρτηση που μπορεί να καλέσει ένας AI πράκτορας. +**Tool** - Συνάρτηση που μπορεί να καλέσει ένας πράκτορας ΤΝ. **Tool Description** - Τεκμηρίωση σκοπού και παραμέτρων εργαλείου. ## Agentic Module - [Module 05](../05-mcp/README.md) -**@Agent Annotation** - Σημειώνει interfaces ως AI πράκτορες με δηλωτικό ορισμό συμπεριφοράς. +**@Agent Annotation** - Σηματοδοτεί διεπαφές ως πράκτορες ΤΝ με δηλωτικό ορισμό συμπεριφοράς. -**Agent Listener** - Hook για παρακολούθηση εκτέλεσης πράκτορα μέσω `beforeAgentInvocation()` και `afterAgentInvocation()`. +**Agent Listener** - Γάντζος για παρακολούθηση εκτέλεσης πράκτορα μέσω `beforeAgentInvocation()` και `afterAgentInvocation()`. -**Agentic Scope** - Κοινή μνήμη όπου οι πράκτορες αποθηκεύουν εξόδους χρησιμοποιώντας `outputKey` για κατανάλωση από κατωτέρους πράκτορες. +**Agentic Scope** - Κοινόχρηστη μνήμη όπου οι πράκτορες αποθηκεύουν αποτελέσματα με `outputKey` για να τα χρησιμοποιήσουν επόμενοι πράκτορες. **AgenticServices** - Εργοστάσιο δημιουργίας πρακτόρων με `agentBuilder()` και `supervisorBuilder()`. -**Conditional Workflow** - Διαδρομή βάσει συνθηκών προς διαφορετικούς ειδικούς πράκτορες. +**Conditional Workflow** - Διαδρομή βάσει συνθηκών σε διαφορετικούς ειδικούς πράκτορες. -**Human-in-the-Loop** - Μοτίβο ροής εργασίας με ανθρώπινους ελέγχους για έγκριση ή ανασκόπηση περιεχομένου. +**Human-in-the-Loop** - Πρότυπο ροής εργασίας με ανθρώπινους σταθμούς ελέγχου για έγκριση ή αναθεώρηση περιεχομένου. -**langchain4j-agentic** - Εξάρτηση Maven για δηλωτική κατασκευή πρακτόρων (πειραματικό). +**langchain4j-agentic** - Εξάρτηση Maven για δηλωτική δημιουργία πρακτόρων (πειραματική). -**Loop Workflow** - Επανάληψη εκτέλεσης πράκτορα μέχρι να πληρωθεί συνθήκη (π.χ. βαθμολογία ποιότητας ≥ 0.8). +**Loop Workflow** - Επανάληψη εκτέλεσης πράκτορα μέχρι να πληρωθεί συνθήκη (π.χ. σκορ ποιότητας ≥ 0.8). -**outputKey** - Παράμετρος annotation πράκτορα που καθορίζει πού αποθηκεύονται τα αποτελέσματα στο Agentic Scope. +**outputKey** - Παράμετρος σχολιασμού πράκτορα που καθορίζει πού αποθηκεύονται τα αποτελέσματα στο Agentic Scope. **Parallel Workflow** - Εκτέλεση πολλαπλών πρακτόρων ταυτόχρονα για ανεξάρτητες εργασίες. **Response Strategy** - Πώς ο επιβλέπων διαμορφώνει την τελική απάντηση: LAST, SUMMARY ή SCORED. -**Sequential Workflow** - Εκτέλεση πρακτόρων με σειρά όπου η έξοδος διοχετεύεται στο επόμενο βήμα. +**Sequential Workflow** - Εκτέλεση πρακτόρων με σειρά όπου η έξοδος ρέει στο επόμενο βήμα. -**Supervisor Agent Pattern** - Προχωρημένο μοτίβο agentic όπου ένας επιβλέπων LLM αποφασίζει δυναμικά ποιον υποπράκτορα να καλέσει. +**Supervisor Agent Pattern** - Προχωρημένο agentic πρότυπο όπου ένας επιβλέπων LLM αποφασίζει δυναμικά ποιους υπο-πράκτορες να καλέσει. ## Πρωτόκολλο Πλαισίου Μοντέλου (MCP) - [Module 05](../05-mcp/README.md) **langchain4j-mcp** - Εξάρτηση Maven για ενσωμάτωση MCP στο LangChain4j. -**MCP** - Πρωτόκολλο Πλαισίου Μοντέλου: πρότυπο για σύνδεση εφαρμογών AI με εξωτερικά εργαλεία. Φτιάξτε μια φορά, χρησιμοποιήστε παντού. +**MCP** - Πρωτόκολλο Πλαισίου Μοντέλου: πρότυπο για σύνδεση εφαρμογών ΤΝ με εξωτερικά εργαλεία. Φτιάχνεις μία φορά, χρησιμοποιείς παντού. -**MCP Client** - Εφαρμογή που συνδέεται με MCP servers για ανακάλυψη και χρήση εργαλείων. +**MCP Client** - Εφαρμογή που συνδέεται με διακομιστές MCP για ανακάλυψη και χρήση εργαλείων. **MCP Server** - Υπηρεσία που εκθέτει εργαλεία μέσω MCP με σαφείς περιγραφές και σχήματα παραμέτρων. -**McpToolProvider** - Συστατικό LangChain4j που περιτυλίγει εργαλεία MCP για χρήση σε AI υπηρεσίες και πράκτορες. +**McpToolProvider** - Συστατικό LangChain4j που υλοποιεί MCP εργαλεία για χρήση σε υπηρεσίες ΤΝ και πράκτορες. -**McpTransport** - Interface για επικοινωνία MCP. Υλοποιήσεις περιλαμβάνουν Stdio και HTTP. +**McpTransport** - Διεπαφή για επικοινωνία MCP. Υλοποιήσεις περιλαμβάνουν Stdio και HTTP. -**Stdio Transport** - Τοπική μεταφορά διεργασίας μέσω stdin/stdout. Χρήσιμο για πρόσβαση σε σύστημα αρχείων ή εργαλεία γραμμής εντολών. +**Stdio Transport** - Τοπικός μεταφορέας διαδικασιών μέσω stdin/stdout. Χρήσιμος για πρόσβαση σε σύστημα αρχείων ή εργαλεία γραμμής εντολών. -**StdioMcpTransport** - Υλοποίηση LangChain4j που δημιουργεί MCP server ως subprocess. +**StdioMcpTransport** - Υλοποίηση LangChain4j που εκκινεί MCP server ως υποδιαδικασία. -**Tool Discovery** - Ο πελάτης ρωτά τον server για διαθέσιμα εργαλεία με περιγραφές και σχήματα. +**Tool Discovery** - Ο πελάτης ζητά από το διακομιστή διαθέσιμα εργαλεία με περιγραφές και σχήματα. ## Υπηρεσίες Azure - [Module 01](../01-introduction/README.md) -**Azure AI Search** - Νέφος αναζήτησης με δυνατότητες vector. [Module 03](../03-rag/README.md) +**Azure AI Search** - Cloud αναζήτηση με δυνατότητες διανυσμάτων. [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Αναπτύσσει πόρους Azure. +**Azure Developer CLI (azd)** - Ανάπτυξη πόρων Azure. -**Azure OpenAI** - Επιχειρησιακή υπηρεσία AI της Microsoft. +**Azure OpenAI** - Επιχειρησιακή υπηρεσία ΤΝ της Microsoft. -**Bicep** - Γλώσσα υποδομής ως κώδικας στο Azure. [Infrastructure Guide](../01-introduction/infra/README.md) +**Bicep** - Γλώσσα υποδομής ως κώδικας Azure. [Infrastructure Guide](../01-introduction/infra/README.md) **Deployment Name** - Όνομα ανάπτυξης μοντέλου στο Azure. -**GPT-5.2** - Τελευταίο μοντέλο OpenAI με έλεγχο συλλογισμού. [Module 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Τελευταίο μοντέλο OpenAI με έλεγχο συλλογιστικής. [Module 02](../02-prompt-engineering/README.md) ## Δοκιμές και Ανάπτυξη - [Testing Guide](TESTING.md) -**Dev Container** - Περιβάλλον ανάπτυξης σε κοντέινερ. [Configuration](../../../.devcontainer/devcontainer.json) +**Dev Container** - Περιβάλλον ανάπτυξης με κοντέινερ. [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Δωρεάν πλατφόρμα μοντέλων AI. [Module 00](../00-quick-start/README.md) +**In-Memory Testing** - Δοκιμή με αποθήκευση στη μνήμη. -**In-Memory Testing** - Δοκιμές με αποθήκευση στην μνήμη. +**Integration Testing** - Δοκιμή με πραγματική υποδομή. -**Integration Testing** - Δοκιμές με πραγματική υποδομή. +**Maven** - Εργαλείο αυτοματισμού κατασκευής Java. -**Maven** - Εργαλείο αυτοματοποίησης κατασκευής Java. +**Mockito** - Πλαίσιο mocking για Java. -**Mockito** - Πλαίσιο για mock αντικείμενα σε Java. - -**Spring Boot** - Πλαίσιο εφαρμογών Java. [Module 01](../01-introduction/README.md) +**Spring Boot** - Πλαίσιο εφαρμογής Java. [Module 01](../01-introduction/README.md) --- -**Αποποίηση ευθυνών**: -Αυτό το έγγραφο έχει μεταφραστεί με τη χρήση της υπηρεσίας αυτόματης μετάφρασης AI [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που προσπαθούμε για ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτόματες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη γλώσσα του θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες συνιστάται επαγγελματική μετάφραση από ανθρώπους. Δεν φέρουμε ευθύνη για τυχόν παρανοήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. +**Αποποίηση ευθυνών**: +Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. \ No newline at end of file diff --git a/translations/el/docs/TESTING.md b/translations/el/docs/TESTING.md index 1780b5d2b..3b4a071da 100644 --- a/translations/el/docs/TESTING.md +++ b/translations/el/docs/TESTING.md @@ -2,19 +2,19 @@ ## Πίνακας Περιεχομένων -- [Γρήγορη Έναρξη](../../../docs) -- [Τι Καλύπτουν οι Δοκιμές](../../../docs) -- [Εκτέλεση των Δοκιμών](../../../docs) -- [Εκτέλεση Δοκιμών στο VS Code](../../../docs) -- [Πρότυπα Δοκιμών](../../../docs) -- [Φιλοσοφία των Δοκιμών](../../../docs) -- [Επόμενα Βήματα](../../../docs) +- [Γρήγορη Εκκίνηση](#γρήγορη-εκκίνηση) +- [Τι Καλύπτουν οι Δοκιμές](#τι-καλύπτουν-οι-δοκιμές) +- [Εκτέλεση των Δοκιμών](#εκτέλεση-των-δοκιμών) +- [Εκτέλεση Δοκιμών στο VS Code](#εκτέλεση-δοκιμών-στο-vs-code) +- [Μοτίβα Δοκιμών](#μοτίβα-δοκιμών) +- [Φιλοσοφία Δοκιμών](#φιλοσοφία-δοκιμών) +- [Επόμενα Βήματα](#επόμενα-βήματα) -Αυτός ο οδηγός σας καθοδηγεί μέσα από τις δοκιμές που δείχνουν πώς να δοκιμάσετε εφαρμογές Τεχνητής Νοημοσύνης χωρίς να απαιτούνται API κλειδιά ή εξωτερικές υπηρεσίες. +Αυτός ο οδηγός σας καθοδηγεί μέσα από τις δοκιμές που δείχνουν πώς να δοκιμάσετε εφαρμογές AI χωρίς να απαιτούνται κλειδιά API ή εξωτερικές υπηρεσίες. -## Γρήγορη Έναρξη +## Γρήγορη Εκκίνηση -Τρέξτε όλες τις δοκιμές με μία εντολή: +Εκτελέστε όλες τις δοκιμές με μία εντολή: **Bash:** ```bash @@ -26,28 +26,27 @@ mvn test mvn --% test ``` -Όταν όλες οι δοκιμές περάσουν, θα δείτε έξοδο όπως στην παρακάτω οθόνη — οι δοκιμές εκτελούνται χωρίς αποτυχίες. +Όταν όλες οι δοκιμές περάσουν, θα πρέπει να δείτε έξοδο όπως το στιγμιότυπο παρακάτω — οι δοκιμές εκτελούνται χωρίς αποτυχίες. -Αποτελέσματα Επιτυχούς Δοκιμής +Επιτυχημένα Αποτελέσματα Δοκιμών *Επιτυχής εκτέλεση δοκιμών που δείχνει όλες τις δοκιμές να περνούν χωρίς αποτυχίες* ## Τι Καλύπτουν οι Δοκιμές -Αυτή η ενότητα εστιάζει σε **μοναδιαίες δοκιμές** που τρέχουν τοπικά. Κάθε δοκιμή παρουσιάζει μια συγκεκριμένη έννοια του LangChain4j απομονωμένα. Η πυραμίδα δοκιμών παρακάτω δείχνει πού εντάσσονται οι μοναδιαίες δοκιμές — αποτελούν το γρήγορο, αξιόπιστο θεμέλιο πάνω στο οποίο χτίζεται η υπόλοιπη στρατηγική δοκιμών σας. +Αυτό το μάθημα εστιάζει σε **μονάδες δοκιμών** που εκτελούνται τοπικά. Κάθε δοκιμή παρουσιάζει μια συγκεκριμένη έννοια LangChain4j απομονωμένη. Η πυραμίδα δοκιμών παρακάτω δείχνει πού εντάσσονται οι μονάδες δοκιμών — αποτελούν τη γρήγορη, αξιόπιστη βάση πάνω στην οποία χτίζεται η υπόλοιπη στρατηγική δοκιμών σας. Πυραμίδα Δοκιμών -*Πυραμίδα δοκιμών που δείχνει την ισορροπία μεταξύ μοναδιαίων δοκιμών (γρήγορες, απομονωμένες), δοκιμών ενσωμάτωσης (πραγματικά συστατικά) και δοκιμών από άκρο σε άκρο. Αυτή η εκπαίδευση καλύπτει μοναδιαίες δοκιμές.* +*Πυραμίδα δοκιμών που δείχνει την ισορροπία μεταξύ μονάδων δοκιμών (γρήγορες, απομονωμένες), δοκιμών ολοκλήρωσης (πραγματικά στοιχεία) και δοκιμών end-to-end. Αυτή η εκπαίδευση καλύπτει τη μονάδα δοκιμών.* | Ενότητα | Δοκιμές | Εστίαση | Κύρια Αρχεία | |--------|-------|-------|-----------| -| **00 - Γρήγορη Έναρξη** | 6 | Πρότυπα prompt και αντικατάσταση μεταβλητών | `SimpleQuickStartTest.java` | -| **01 - Εισαγωγή** | 8 | Μνήμη συνομιλίας και κατάσταση συνομιλίας | `SimpleConversationTest.java` | -| **02 - Μηχανική Prompt** | 12 | Πρότυπα GPT-5.2, επίπεδα προθυμίας, δομημένη έξοδος | `SimpleGpt5PromptTest.java` | +| **01 - Εισαγωγή** | 8 | Μνήμη συνομιλίας και συνομιλία με κατάσταση | `SimpleConversationTest.java` | +| **02 - Μηχανική Prompt** | 12 | Πρότυπα GPT-5.2, επίπεδα ενθουσιασμού, δομημένη έξοδος | `SimpleGpt5PromptTest.java` | | **03 - RAG** | 10 | Εισαγωγή εγγράφων, ενσωματώσεις, αναζήτηση ομοιότητας | `DocumentServiceTest.java` | -| **04 - Εργαλεία** | 12 | Κλήση λειτουργιών και αλυσίδες εργαλείων | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Πρωτόκολλο Πλαισίου Μοντέλου με μεταφορά stdio | `SimpleMcpTest.java` | +| **04 - Εργαλεία** | 12 | Κλήση λειτουργιών και αλυσιδωτές λειτουργίες εργαλείων | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Πρωτόκολλο Πλαισίου Μοντέλου με μεταφορά Stdio | `SimpleMcpTest.java` | ## Εκτέλεση των Δοκιμών @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Εκτελέστε δοκιμές για συγκεκριμένο module:** +**Εκτέλεση δοκιμών για συγκεκριμένη ενότητα:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Εκτελέστε μια μόνο κλάση δοκιμής:** +**Εκτέλεση μιας μόνο κλάσης δοκιμής:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Εκτελέστε συγκεκριμένη μέθοδο δοκιμής:** +**Εκτέλεση συγκεκριμένης μεθόδου δοκιμής:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#πρέπει να διατηρεί το ιστορικό συνομιλίας +mvn test -Dtest=SimpleConversationTest#θα πρέπει να διατηρεί το ιστορικό συνομιλίας ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#πρέπει να διατηρεί το ιστορικό συνομιλιών +mvn --% test -Dtest=SimpleConversationTest#θα πρέπει να διατηρεί το ιστορικό συνομιλίας ``` ## Εκτέλεση Δοκιμών στο VS Code -Αν χρησιμοποιείτε το Visual Studio Code, ο Εξερευνητής Δοκιμών παρέχει γραφικό περιβάλλον για την εκτέλεση και αποσφαλμάτωση δοκιμών. +Αν χρησιμοποιείτε το Visual Studio Code, ο Test Explorer προσφέρει γραφική διεπαφή για την εκτέλεση και αποσφαλμάτωση των δοκιμών. -VS Code Εξερευνητής Δοκιμών +Εξερευνητής Δοκιμών VS Code -*VS Code Εξερευνητής Δοκιμών που δείχνει το δέντρο δοκιμών με όλες τις κλάσεις δοκιμών Java και μεμονωμένες μεθόδους δοκιμών* +*Ο Εξερευνητής Δοκιμών του VS Code δείχνει το δέντρο δοκιμών με όλες τις κλάσεις δοκιμής Java και τις μεμονωμένες μεθόδους δοκιμών* -**Για να τρέξετε δοκιμές στο VS Code:** +**Για να εκτελέσετε δοκιμές στο VS Code:** -1. Ανοίξτε τον Εξερευνητή Δοκιμών κάνοντας κλικ στο εικονίδιο του δοκιμαστικού σωλήνα στη γραμμή δραστηριότητας -2. Διευρύνετε το δέντρο δοκιμών για να δείτε όλα τα modules και τις κλάσεις δοκιμών -3. Κάντε κλικ στο κουμπί αναπαραγωγής δίπλα σε οποιαδήποτε δοκιμή για να τη τρέξετε μεμονωμένα +1. Ανοίξτε τον Εξερευνητή Δοκιμών κάνοντας κλικ στο εικονίδιο δοκιμαστικού σωλήνα στη γραμμή δραστηριότητας +2. Αναπτύξτε το δέντρο δοκιμών για να δείτε όλες τις ενότητες και τις κλάσεις δοκιμών +3. Κάντε κλικ στο κουμπί αναπαραγωγής δίπλα σε οποιαδήποτε δοκιμή για να την τρέξετε μεμονωμένα 4. Κάντε κλικ στο "Run All Tests" για να εκτελέσετε ολόκληρο το σύνολο -5. Κάντε δεξί κλικ σε οποιαδήποτε δοκιμή και επιλέξτε "Debug Test" για να ορίσετε σημεία διακοπής και να βήμα-βήμα μέσα στον κώδικα +5. Δεξί κλικ σε οποιαδήποτε δοκιμή και επιλέξτε "Debug Test" για να ορίσετε σημεία διακοπής και να εκτελέσετε βήμα προς βήμα τον κώδικα -Ο Εξερευνητής Δοκιμών δείχνει πράσινα σημάδια για τις επιτυχημένες δοκιμές και παρέχει λεπτομερή μηνύματα αποτυχίας όταν οι δοκιμές αποτυγχάνουν. +Ο Εξερευνητής Δοκιμών εμφανίζει πράσινες επιβεβαιώσεις για τις περασμένες δοκιμές και παρέχει λεπτομερή μηνύματα αποτυχίας όταν οι δοκιμές αποτυγχάνουν. -## Πρότυπα Δοκιμών +## Μοτίβα Δοκιμών -### Πρότυπο 1: Δοκιμή Προτύπων Prompt +### Μοτίβο 1: Δοκιμή Προτύπων Prompt -Το απλούστερο πρότυπο δοκιμάζει πρότυπα prompt χωρίς να καλεί κανένα μοντέλο AI. Επαληθεύετε ότι η αντικατάσταση των μεταβλητών λειτουργεί σωστά και τα prompts μορφοποιούνται όπως αναμένεται. +Το απλούστερο μοτίβο δοκιμάζει πρότυπα prompt χωρίς να καλεί κανένα μοντέλο AI. Επαληθεύετε ότι η αντικατάσταση μεταβλητών λειτουργεί σωστά και ότι τα prompts μορφοποιούνται όπως αναμένεται. Δοκιμή Προτύπου Prompt -*Δοκιμή πρότυπων prompt που δείχνει τη ροή αντικατάστασης μεταβλητών: πρότυπο με θέσεις κρατήματος → εφαρμόζονται τιμές → επιβεβαιώνεται η μορφοποιημένη έξοδος* +*Δοκιμή προτύπων prompt που δείχνει ροή αντικατάστασης μεταβλητών: πρότυπο με θέσεις κράτησης → εφαρμόζονται τιμές → επαληθεύεται η μορφοποιημένη έξοδος* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Αυτή η δοκιμή βρίσκεται στο `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Αυτό το μοτίβο επαληθεύει ότι η αντικατάσταση μεταβλητών λειτουργεί σωστά και τα prompts μορφοποιούνται όπως αναμένεται — χωρίς απαίτηση κλειδιού API ή κλήσης μοντέλου. -**Τρέξτε την:** +### Μοτίβο 2: Προσομοίωση Μοντέλων Γλώσσας -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#μορφοποίησηΠροτύπουΠροτροπήςΔοκιμής -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#δοκιμήΜορφοποίησηςΠροτύπουΠροτροπής -``` - -### Πρότυπο 2: Mocking Μοντέλων Γλώσσας - -Όταν δοκιμάζετε τη λογική συνομιλίας, χρησιμοποιήστε το Mockito για να δημιουργήσετε ψεύτικα μοντέλα που επιστρέφουν προκαθορισμένες απαντήσεις. Αυτό κάνει τις δοκιμές γρήγορες, δωρεάν και ντετερμινιστικές. +Κατά τη δοκιμή της λογικής συνομιλίας, χρησιμοποιήστε Mockito για να δημιουργήσετε ψεύτικα μοντέλα που επιστρέφουν προκαθορισμένες απαντήσεις. Αυτό κάνει τις δοκιμές γρήγορες, δωρεάν και ντετερμινιστικές. -Σύγκριση Mock vs Πραγματικό API +Σύγκριση Mock vs Πραγματικού API -*Σύγκριση που δείχνει γιατί προτιμώνται τα mocks για δοκιμές: είναι γρήγορα, δωρεάν, ντετερμινιστικά και δεν απαιτούν API κλειδιά* +*Σύγκριση που δείχνει γιατί προτιμώνται τα mocks για δοκιμές: είναι γρήγορα, δωρεάν, ντετερμινιστικά και δεν απαιτούν κλειδιά API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Αυτό το πρότυπο εμφανίζεται στο `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Το mock διασφαλίζει συνεπή συμπεριφορά ώστε να μπορείτε να επαληθεύσετε ότι η διαχείριση μνήμης λειτουργεί σωστά. +Αυτό το μοτίβο εμφανίζεται στο `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Το mock εξασφαλίζει σταθερή συμπεριφορά ώστε να επαληθεύσετε ότι η διαχείριση μνήμης λειτουργεί σωστά. -### Πρότυπο 3: Δοκιμή Απομόνωσης Συνομιλίας +### Μοτίβο 3: Δοκιμή Απομόνωσης Συνομιλίας -Η μνήμη συνομιλίας πρέπει να κρατά τους πολλαπλούς χρήστες απομονωμένους. Αυτή η δοκιμή επαληθεύει ότι οι συνομιλίες δεν αναμειγνύουν συμφραζόμενα. +Η μνήμη συνομιλίας πρέπει να κρατά τους χρήστες ξεχωριστούς. Αυτή η δοκιμή επαληθεύει ότι οι συνομιλίες δεν αναμιγνύουν τα συμφραζόμενα. Απομόνωση Συνομιλίας -*Δοκιμή απομόνωσης συνομιλίας που δείχνει ξεχωριστές αποθήκες μνήμης για διαφορετικούς χρήστες για να αποτρέπει το ανακάτεμα συμφραζομένων* +*Δοκιμή απομόνωσης συνομιλίας που δείχνει ξεχωριστά καταστήματα μνήμης για διαφορετικούς χρήστες για να αποτραπεί η ανάμειξη συμφραζομένων* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Κάθε συνομιλία διατηρεί το δικό της ανεξάρτητο ιστορικό. Σε παραγωγικά συστήματα, αυτή η απομόνωση είναι κρίσιμη για εφαρμογές πολλαπλών χρηστών. +Κάθε συνομιλία διατηρεί το δικό της ανεξάρτητο ιστορικό. Σε συστήματα παραγωγής, αυτή η απομόνωση είναι κρίσιμη για εφαρμογές πολλαπλών χρηστών. -### Πρότυπο 4: Δοκιμή Εργαλείων Ανεξάρτητα +### Μοτίβο 4: Δοκιμή Εργαλείων Ανεξάρτητα -Τα εργαλεία είναι λειτουργίες που το AI μπορεί να καλέσει. Δοκιμάστε τα απευθείας για να βεβαιωθείτε ότι λειτουργούν σωστά ανεξάρτητα από τις αποφάσεις του AI. +Τα εργαλεία είναι λειτουργίες που μπορεί να καλέσει το AI. Δοκιμάστε τα απευθείας για να εξασφαλίσετε ότι λειτουργούν σωστά ανεξάρτητα από τις αποφάσεις του AI. Δοκιμή Εργαλείων -*Δοκιμή εργαλείων ανεξάρτητα που δείχνει εκτέλεση ψεύτικου εργαλείου χωρίς κλήσεις AI για επαλήθευση επιχειρηματικής λογικής* +*Δοκιμή εργαλείων ανεξάρτητα που δείχνει εκτέλεση mock εργαλείου χωρίς κλήσεις AI για να επαληθευτεί η επιχειρησιακή λογική* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Αυτές οι δοκιμές από το `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` επαληθεύουν τη λογική των εργαλείων χωρίς την εμπλοκή του AI. Το παράδειγμα σύνδεσης δείχνει πώς η έξοδος ενός εργαλείου τροφοδοτεί την είσοδο άλλου. +Αυτές οι δοκιμές από το `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` επαληθεύουν τη λογική εργαλείων χωρίς εμπλοκή AI. Το παράδειγμα αλυσιδωτής λειτουργίας δείχνει πώς η έξοδος ενός εργαλείου τροφοδοτεί την είσοδο ενός άλλου. -### Πρότυπο 5: Δοκιμή RAG Μέσω Μνήμης +### Μοτίβο 5: Δοκιμή RAG Εντός Μνήμης -Τα συστήματα RAG παραδοσιακά απαιτούν διανυσματικές βάσεις δεδομένων και υπηρεσίες ενσωμάτωσης. Το πρότυπο μέσω μνήμης σας επιτρέπει να δοκιμάσετε ολόκληρη τη ροή χωρίς εξωτερικές εξαρτήσεις. +Τα συστήματα RAG παραδοσιακά απαιτούν βάσεις δεδομένων διανυσμάτων και υπηρεσίες ενσωμάτωσης. Το μοτίβο εντός μνήμης σας επιτρέπει να δοκιμάσετε όλη την αλυσίδα χωρίς εξαρτήσεις. -Δοκιμή RAG Μέσω Μνήμης +Δοκιμή RAG Εντός Μνήμης -*Ροή εργασίας δοκιμής RAG μέσω μνήμης που δείχνει ανάλυση εγγράφων, αποθήκευση ενσωματώσεων και αναζήτηση ομοιότητας χωρίς να απαιτείται βάση δεδομένων* +*Ροή εργασίας δοκιμών RAG εντός μνήμης που δείχνει ανάλυση εγγράφου, αποθήκευση ενσωματώσεων και αναζήτηση ομοιότητας χωρίς απαίτηση βάσης δεδομένων* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -Αυτή η δοκιμή από το `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` δημιουργεί ένα έγγραφο στη μνήμη και επαληθεύει το διαχωρισμό σε κομμάτια και τη διαχείριση μεταδεδομένων. +Αυτή η δοκιμή από το `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` δημιουργεί ένα έγγραφο στη μνήμη και επαληθεύει το κομμάτιασμα και τη διαχείριση μεταδεδομένων. -### Πρότυπο 6: Δοκιμή Ενσωμάτωσης MCP +### Μοτίβο 6: Δοκιμή Ενσωμάτωσης MCP -Το module MCP δοκιμάζει την ενσωμάτωση Πρωτοκόλλου Πλαισίου Μοντέλου χρησιμοποιώντας μεταφορά stdio. Αυτές οι δοκιμές επιβεβαιώνουν ότι η εφαρμογή σας μπορεί να ξεκινήσει και να επικοινωνήσει με MCP servers ως υπο-διαδικασίες. +Η ενότητα MCP δοκιμάζει την ενσωμάτωση του Πρωτοκόλλου Πλαισίου Μοντέλου χρησιμοποιώντας τη μεταφορά stdio. Αυτές οι δοκιμές επαληθεύουν ότι η εφαρμογή σας μπορεί να δημιουργήσει και να επικοινωνήσει με MCP διακομιστές ως υποδιαδικασίες. Οι δοκιμές στο `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` επαληθεύουν τη συμπεριφορά πελάτη MCP. -**Τρέξτε τις:** +**Εκτελέστε τις:** **Bash:** ```bash @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## Φιλοσοφία των Δοκιμών +## Φιλοσοφία Δοκιμών -Δοκιμάστε τον κώδικά σας, όχι το AI. Οι δοκιμές σας πρέπει να επικυρώνουν τον κώδικα που γράφετε ελέγχοντας πώς κατασκευάζονται τα prompts, πώς διαχειρίζεται η μνήμη και πώς εκτελούνται τα εργαλεία. Οι απαντήσεις AI διαφέρουν και δεν θα πρέπει να αποτελούν μέρος των ελέγχων. Ρωτήστε τον εαυτό σας αν το πρότυπο prompt αντικαθιστά σωστά τις μεταβλητές, όχι αν το AI δίνει τη σωστή απάντηση. +Δοκιμάστε τον κώδικά σας, όχι το AI. Οι δοκιμές σας πρέπει να επαληθεύουν τον κώδικα που γράφετε ελέγχοντας πώς κατασκευάζονται τα prompts, πώς διαχειρίζεται η μνήμη και πώς εκτελούνται τα εργαλεία. Οι απαντήσεις AI διαφέρουν και δεν θα πρέπει να περιλαμβάνονται στις δηλώσεις των δοκιμών. Αναρωτηθείτε αν το πρότυπο prompt σας αντικαθιστά σωστά τις μεταβλητές, όχι αν το AI δίνει τη σωστή απάντηση. -Χρησιμοποιήστε mocks για τα μοντέλα γλώσσας. Είναι εξωτερικές εξαρτήσεις που είναι αργές, ακριβές και μη ντετερμινιστικές. Το mocking κάνει τις δοκιμές γρήγορες με χιλιοστά του δευτερολέπτου αντί για δευτερόλεπτα, δωρεάν χωρίς κόστος API, και ντετερμινιστικές με το ίδιο αποτέλεσμα κάθε φορά. +Χρησιμοποιήστε mocks για μοντέλα γλώσσας. Αποτελούν εξωτερικές εξαρτήσεις που είναι αργές, ακριβές και μη ντετερμινιστικές. Η προσομοίωση κάνει τις δοκιμές γρήγορες με χιλιοστά του δευτερολέπτου αντί για δευτερόλεπτα, δωρεάν χωρίς κόστος API και ντετερμινιστικές με το ίδιο αποτέλεσμα κάθε φορά. -Διατηρήστε τις δοκιμές ανεξάρτητες. Κάθε δοκιμή πρέπει να ετοιμάζει τα δικά της δεδομένα, να μην εξαρτάται από άλλες δοκιμές και να καθαρίζει μετά τη ολοκλήρωση. Οι δοκιμές πρέπει να περνούν ανεξάρτητα από τη σειρά εκτέλεσης. +Διατηρήστε τις δοκιμές ανεξάρτητες. Κάθε δοκιμή θα πρέπει να ρυθμίζει τα δικά της δεδομένα, να μην εξαρτάται από άλλες δοκιμές και να καθαρίζει μετά τον εαυτό της. Οι δοκιμές πρέπει να περνούν ανεξαρτήτως της σειράς εκτέλεσης. -Δοκιμάστε ακραίες περιπτώσεις πέρα από το ευτυχές μονοπάτι. Δοκιμάστε άδειες εισόδους, πολύ μεγάλες εισόδους, ειδικούς χαρακτήρες, μη έγκυρες παραμέτρους και οριακές συνθήκες. Αυτά συχνά αποκαλύπτουν σφάλματα που η φυσιολογική χρήση δεν εκθέτει. +Δοκιμάστε άκρες περιπτώσεων πέρα από το συνηθισμένο μονοπάτι. Δοκιμάστε κενές εισόδους, πολύ μεγάλες εισόδους, ειδικούς χαρακτήρες, άκυρες παραμέτρους και οριακές συνθήκες. Αυτά συχνά αποκαλύπτουν σφάλματα που η κανονική χρήση δεν αποκαλύπτει. -Χρησιμοποιήστε περιγραφικά ονόματα. Συγκρίνετε το `shouldMaintainConversationHistoryAcrossMultipleMessages()` με το `test1()`. Το πρώτο σας λέει ακριβώς τι ελέγχεται, καθιστώντας την αποσφαλμάτωση των αποτυχιών πολύ πιο εύκολη. +Χρησιμοποιήστε περιγραφικά ονόματα. Συγκρίνετε το `shouldMaintainConversationHistoryAcrossMultipleMessages()` με το `test1()`. Το πρώτο σας λέει ακριβώς τι δοκιμάζεται, κάνοντας την αποσφαλμάτωση αποτυχιών πολύ πιο εύκολη. ## Επόμενα Βήματα -Τώρα που κατανοείτε τα πρότυπα δοκιμών, εμβαθύνετε σε κάθε module: +Τώρα που κατανοείτε τα μοτίβα δοκιμών, εξερευνήστε πιο βαθιά κάθε ενότητα: -- **[00 - Γρήγορη Έναρξη](../00-quick-start/README.md)** - Ξεκινήστε με τα βασικά των προτύπων prompt - **[01 - Εισαγωγή](../01-introduction/README.md)** - Μάθετε διαχείριση μνήμης συνομιλίας -- **[02 - Μηχανική Prompt](../02-prompt-engineering/README.md)** - Κατακτήστε πρότυπα prompting GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Δημιουργήστε συστήματα ανάκτησης-ενισχυμένης δημιουργίας -- **[04 - Εργαλεία](../04-tools/README.md)** - Εφαρμόστε κλήσεις λειτουργιών και αλυσίδες εργαλείων +- **[02 - Μηχανική Prompt](../02-prompt-engineering/README.md)** - Εξοικειωθείτε με τα μοτίβα prompt GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Δημιουργήστε συστήματα ανάκτησης ενισχυμένης γεννήτριας +- **[04 - Εργαλεία](../04-tools/README.md)** - Υλοποιήστε κλήση λειτουργιών και αλυσίδες εργαλείων - **[05 - MCP](../05-mcp/README.md)** - Ενσωματώστε το Πρωτόκολλο Πλαισίου Μοντέλου -Το README κάθε module παρέχει λεπτομερείς εξηγήσεις για τις έννοιες που δοκιμάζονται εδώ. +Το README κάθε ενότητας παρέχει λεπτομερείς εξηγήσεις των εννοιών που δοκιμάζονται εδώ. --- -**Πλοήγηση:** [← Επιστροφή στην Κύρια Σελίδα](../README.md) +**Πλοήγηση:** [← Επιστροφή στην Αρχική](../README.md) --- -**Αποποίηση ευθυνών**: -Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία αυτόματης μετάφρασης AI [Co-op Translator](https://github.com/Azure/co-op-translator). Παρόλο που προσπαθούμε για ακρίβεια, παρακαλούμε να γνωρίζετε ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική μετάφραση από ανθρώπους. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. +**Αποποίηση ευθυνών**: +Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη [Co-op Translator](https://github.com/Azure/co-op-translator). Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης. \ No newline at end of file diff --git a/translations/en/.co-op-translator.json b/translations/en/.co-op-translator.json index b1ac8e6d7..5a4506315 100644 --- a/translations/en/.co-op-translator.json +++ b/translations/en/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "en" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T18:16:47+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T06:55:24+00:00", "source_file": "01-introduction/README.md", "language_code": "en" }, @@ -18,20 +18,20 @@ "language_code": "en" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T18:18:55+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T06:51:52+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "en" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T18:20:12+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T06:54:40+00:00", "source_file": "03-rag/README.md", "language_code": "en" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:12:29+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T06:53:41+00:00", "source_file": "04-tools/README.md", "language_code": "en" }, @@ -54,8 +54,8 @@ "language_code": "en" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:30:07+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T06:50:46+00:00", "source_file": "README.md", "language_code": "en" }, @@ -72,14 +72,14 @@ "language_code": "en" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T18:22:55+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T06:52:15+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "en" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T18:23:40+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T06:52:44+00:00", "source_file": "docs/TESTING.md", "language_code": "en" } diff --git a/translations/en/00-quick-start/README.md b/translations/en/00-quick-start/README.md deleted file mode 100644 index 9e4cc9bc6..000000000 --- a/translations/en/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Quick Start - -## Table of Contents - -- [Introduction](../../../00-quick-start) -- [What is LangChain4j?](../../../00-quick-start) -- [LangChain4j Dependencies](../../../00-quick-start) -- [Prerequisites](../../../00-quick-start) -- [Setup](../../../00-quick-start) - - [1. Get Your GitHub Token](../../../00-quick-start) - - [2. Set Your Token](../../../00-quick-start) -- [Run the Examples](../../../00-quick-start) - - [1. Basic Chat](../../../00-quick-start) - - [2. Prompt Patterns](../../../00-quick-start) - - [3. Function Calling](../../../00-quick-start) - - [4. Document Q&A (Easy RAG)](../../../00-quick-start) - - [5. Responsible AI](../../../00-quick-start) -- [What Each Example Shows](../../../00-quick-start) -- [Next Steps](../../../00-quick-start) -- [Troubleshooting](../../../00-quick-start) - -## Introduction - -This quickstart is meant to get you up and running with LangChain4j as quickly as possible. It covers the absolute basics of building AI applications with LangChain4j and GitHub Models. In the next modules you'll switch to Azure OpenAI and GPT-5.2 and dive deeper into each concept. - -## What is LangChain4j? - -LangChain4j is a Java library that simplifies building AI-powered applications. Instead of dealing with HTTP clients and JSON parsing, you work with clean Java APIs. - -The "chain" in LangChain refers to chaining together multiple components - you might chain a prompt to a model to a parser, or chain multiple AI calls together where one output feeds into the next input. This quick start focuses on the fundamentals before exploring more complex chains. - -LangChain4j Chaining Concept - -*Chaining components in LangChain4j - building blocks connect to create powerful AI workflows* - -We'll use three core components: - -**ChatModel** - The interface for AI model interactions. Call `model.chat("prompt")` and get a response string. We use `OpenAiOfficialChatModel` which works with OpenAI-compatible endpoints like GitHub Models. - -**AiServices** - Creates type-safe AI service interfaces. Define methods, annotate them with `@Tool`, and LangChain4j handles the orchestration. The AI automatically calls your Java methods when needed. - -**MessageWindowChatMemory** - Maintains conversation history. Without this, each request is independent. With it, the AI remembers previous messages and maintains context across multiple turns. - -LangChain4j Architecture - -*LangChain4j architecture - core components working together to power your AI applications* - -## LangChain4j Dependencies - -This quick start uses three Maven dependencies in the [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -The `langchain4j-open-ai-official` module provides the `OpenAiOfficialChatModel` class that connects to OpenAI-compatible APIs. GitHub Models uses the same API format, so no special adapter is needed - just point the base URL to `https://models.github.ai/inference`. - -The `langchain4j-easy-rag` module provides automatic document splitting, embedding, and retrieval so you can build RAG applications without manually configuring each step. - -## Prerequisites - -**Using the Dev Container?** Java and Maven are already installed. You only need a GitHub Personal Access Token. - -**Local Development:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (instructions below) - -> **Note:** This module uses `gpt-4.1-nano` from GitHub Models. Do not modify the model name in the code - it's configured to work with GitHub's available models. - -## Setup - -### 1. Get Your GitHub Token - -1. Go to [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Click "Generate new token" -3. Set a descriptive name (e.g., "LangChain4j Demo") -4. Set expiration (7 days recommended) -5. Under "Account permissions", find "Models" and set to "Read-only" -6. Click "Generate token" -7. Copy and save your token - you won't see it again - -### 2. Set Your Token - -**Option 1: Using VS Code (Recommended)** - -If you're using VS Code, add your token to the `.env` file in the project root: - -If the `.env` file does not exist, copy `.env.example` to `.env` or create a new `.env` file in the project root. - -**Example `.env` file:** -```bash -# In /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Then you can simply right-click on any demo file (e.g., `BasicChatDemo.java`) in the Explorer and select **"Run Java"** or use the launch configurations from the Run and Debug panel. - -**Option 2: Using Terminal** - -Set the token as an environment variable: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Run the Examples - -**Using VS Code:** Simply right-click on any demo file in the Explorer and select **"Run Java"**, or use the launch configurations from the Run and Debug panel (make sure you've added your token to the `.env` file first). - -**Using Maven:** Alternatively, you can run from the command line: - -### 1. Basic Chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Prompt Patterns - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Shows zero-shot, few-shot, chain-of-thought, and role-based prompting. - -### 3. Function Calling - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI automatically calls your Java methods when needed. - -### 4. Document Q&A (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Ask questions about your documents using Easy RAG with automatic embedding and retrieval. - -### 5. Responsible AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -See how AI safety filters block harmful content. - -## What Each Example Shows - -**Basic Chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Start here to see LangChain4j at its simplest. You'll create an `OpenAiOfficialChatModel`, send a prompt with `.chat()`, and get back a response. This demonstrates the foundation: how to initialize models with custom endpoints and API keys. Once you understand this pattern, everything else builds on it. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) and ask: -> - "How would I switch from GitHub Models to Azure OpenAI in this code?" -> - "What other parameters can I configure in OpenAiOfficialChatModel.builder()?" -> - "How do I add streaming responses instead of waiting for the complete response?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Now that you know how to talk to a model, let's explore what you say to it. This demo uses the same model setup but shows five different prompting patterns. Try zero-shot prompts for direct instructions, few-shot prompts that learn from examples, chain-of-thought prompts that reveal reasoning steps, and role-based prompts that set context. You'll see how the same model gives dramatically different results based on how you frame your request. - -The demo also demonstrates prompt templates, which are a powerful way to create reusable prompts with variables. -The below example shows a prompt using the LangChain4j `PromptTemplate` to fill in variables. The AI will answer based on the provided destination and activity. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) and ask: -> - "What's the difference between zero-shot and few-shot prompting, and when should I use each?" -> - "How does the temperature parameter affect the model's responses?" -> - "What are some techniques to prevent prompt injection attacks in production?" -> - "How can I create reusable PromptTemplate objects for common patterns?" - -**Tool Integration** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -This is where LangChain4j gets powerful. You'll use `AiServices` to create an AI assistant that can call your Java methods. Just annotate methods with `@Tool("description")` and LangChain4j handles the rest - the AI automatically decides when to use each tool based on what the user asks. This demonstrates function calling, a key technique for building AI that can take actions, not just answer questions. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) and ask: -> - "How does the @Tool annotation work and what does LangChain4j do with it behind the scenes?" -> - "Can the AI call multiple tools in sequence to solve complex problems?" -> - "What happens if a tool throws an exception - how should I handle errors?" -> - "How would I integrate a real API instead of this calculator example?" - -**Document Q&A (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Here you'll see RAG (retrieval-augmented generation) using LangChain4j's "Easy RAG" approach. Documents are loaded, automatically split and embedded into an in-memory store, then a content retriever supplies relevant chunks to the AI at query time. The AI answers based on your documents, not its general knowledge. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) and ask: -> - "How does RAG prevent AI hallucinations compared to using the model's training data?" -> - "What's the difference between this easy approach and a custom RAG pipeline?" -> - "How would I scale this to handle multiple documents or larger knowledge bases?" - -**Responsible AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Build AI safety with defense in depth. This demo shows two layers of protection working together: - -**Part 1: LangChain4j Input Guardrails** - Block dangerous prompts before they reach the LLM. Create custom guardrails that check for prohibited keywords or patterns. These run in your code, so they're fast and free. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Part 2: Provider Safety Filters** - GitHub Models has built-in filters that catch what your guardrails might miss. You'll see hard blocks (HTTP 400 errors) for severe violations and soft refusals where the AI politely declines. - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) and ask: -> - "What is InputGuardrail and how do I create my own?" -> - "What is the difference between a hard block and a soft refusal?" -> - "Why use both guardrails and provider filters together?" - -## Next Steps - -**Next Module:** [01-introduction - Getting Started with LangChain4j](../01-introduction/README.md) - ---- - -**Navigation:** [← Back to Main](../README.md) | [Next: Module 01 - Introduction →](../01-introduction/README.md) - ---- - -## Troubleshooting - -### First-Time Maven Build - -**Issue**: Initial `mvn clean compile` or `mvn package` takes a long time (10-15 minutes) - -**Cause**: Maven needs to download all project dependencies (Spring Boot, LangChain4j libraries, Azure SDKs, etc.) on the first build. - -**Solution**: This is normal behavior. Subsequent builds will be much faster as dependencies are cached locally. Download time depends on your network speed. - -### PowerShell Maven Command Syntax - -**Issue**: Maven commands fail with error `Unknown lifecycle phase ".mainClass=..."` -**Cause**: PowerShell interprets `=` as a variable assignment operator, breaking Maven property syntax - -**Solution**: Use the stop-parsing operator `--%` before the Maven command: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -The `--%` operator tells PowerShell to pass all remaining arguments literally to Maven without interpretation. - -### Windows PowerShell Emoji Display - -**Issue**: AI responses show garbage characters (e.g., `????` or `â??`) instead of emojis in PowerShell - -**Cause**: PowerShell's default encoding doesn't support UTF-8 emojis - -**Solution**: Run this command before executing Java applications: -```cmd -chcp 65001 -``` - -This forces UTF-8 encoding in the terminal. Alternatively, use Windows Terminal which has better Unicode support. - -### Debugging API Calls - -**Issue**: Authentication errors, rate limits, or unexpected responses from the AI model - -**Solution**: The examples include `.logRequests(true)` and `.logResponses(true)` to show API calls in the console. This helps troubleshoot authentication errors, rate limits, or unexpected responses. Remove these flags in production to reduce log noise. - ---- - - -**Disclaimer**: -This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. - \ No newline at end of file diff --git a/translations/en/01-introduction/README.md b/translations/en/01-introduction/README.md index 6b6e276a4..3631f1265 100644 --- a/translations/en/01-introduction/README.md +++ b/translations/en/01-introduction/README.md @@ -2,19 +2,19 @@ ## Table of Contents -- [Video Walkthrough](../../../01-introduction) -- [What You'll Learn](../../../01-introduction) -- [Prerequisites](../../../01-introduction) -- [Understanding the Core Problem](../../../01-introduction) -- [Understanding Tokens](../../../01-introduction) -- [How Memory Works](../../../01-introduction) -- [How This Uses LangChain4j](../../../01-introduction) -- [Deploy Azure OpenAI Infrastructure](../../../01-introduction) -- [Run the Application Locally](../../../01-introduction) -- [Using the Application](../../../01-introduction) - - [Stateless Chat (Left Panel)](../../../01-introduction) - - [Stateful Chat (Right Panel)](../../../01-introduction) -- [Next Steps](../../../01-introduction) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding the Core Problem](#understanding-the-core-problem) +- [Understanding Tokens](#understanding-tokens) +- [How Memory Works](#how-memory-works) +- [How This Uses LangChain4j](#how-this-uses-langchain4j) +- [Deploy Azure OpenAI Infrastructure](#deploy-azure-openai-infrastructure) +- [Run the Application Locally](#run-the-application-locally) +- [Using the Application](#using-the-application) + - [Stateless Chat (Left Panel)](#stateless-chat-left-panel) + - [Stateful Chat (Right Panel)](#stateful-chat-right-panel) +- [Next Steps](#next-steps) ## Video Walkthrough @@ -24,13 +24,13 @@ Watch this live session that explains how to get started with this module: ## What You'll Learn -In the quick start, you used GitHub Models to send prompts, call tools, build a RAG pipeline, and test guardrails. Those demos showed what's possible — now we switch to Azure OpenAI and GPT-5.2 and start building production-style applications. This module focuses on conversational AI that remembers context and maintains state — the concepts those quick start demos used behind the scenes but didn't explain. +This is your starting point with LangChain4j and Azure OpenAI. We begin with the fundamentals and start building production-style applications. This module focuses on conversational AI that remembers context and maintains state — the foundational concepts every later module builds on. We'll use Azure OpenAI's GPT-5.2 throughout this guide because its advanced reasoning capabilities make the behavior of different patterns more apparent. When you add memory, you'll clearly see the difference. This makes it easier to understand what each component brings to your application. You'll build one application that demonstrates both patterns: -**Stateless Chat** - Each request is independent. The model has no memory of previous messages. This is the pattern you used in the quick start. +**Stateless Chat** - Each request is independent. The model has no memory of previous messages. This is the simplest starting point. **Stateful Conversation** - Each request includes conversation history. The model maintains context across multiple turns. This is what production applications require. @@ -79,7 +79,7 @@ LangChain4j provides memory implementations that handle this automatically. You ## How This Uses LangChain4j -This module extends the quick start by integrating Spring Boot and adding conversation memory. Here's how the pieces fit together: +This module integrates Spring Boot and adds conversation memory. Here's how the pieces fit together: **Dependencies** - Add two LangChain4j libraries: @@ -312,11 +312,11 @@ Both panels use the same GPT-5.2 model. The only difference is memory. This make --- -**Navigation:** [← Previous: Module 00 - Quick Start](../00-quick-start/README.md) | [Back to Main](../README.md) | [Next: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigation:** [← Back to Main](../README.md) | [Next: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **Disclaimer**: -This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. +This document has been translated using AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. \ No newline at end of file diff --git a/translations/en/02-prompt-engineering/README.md b/translations/en/02-prompt-engineering/README.md index d37ada054..5e083ed6c 100644 --- a/translations/en/02-prompt-engineering/README.md +++ b/translations/en/02-prompt-engineering/README.md @@ -2,29 +2,29 @@ ## Table of Contents -- [Video Walkthrough](../../../02-prompt-engineering) -- [What You'll Learn](../../../02-prompt-engineering) -- [Prerequisites](../../../02-prompt-engineering) -- [Understanding Prompt Engineering](../../../02-prompt-engineering) -- [Prompt Engineering Fundamentals](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Templates](../../../02-prompt-engineering) -- [Advanced Patterns](../../../02-prompt-engineering) -- [Run the Application](../../../02-prompt-engineering) -- [Application Screenshots](../../../02-prompt-engineering) -- [Exploring the Patterns](../../../02-prompt-engineering) - - [Low vs High Eagerness](../../../02-prompt-engineering) - - [Task Execution (Tool Preambles)](../../../02-prompt-engineering) - - [Self-Reflecting Code](../../../02-prompt-engineering) - - [Structured Analysis](../../../02-prompt-engineering) - - [Multi-Turn Chat](../../../02-prompt-engineering) - - [Step-by-Step Reasoning](../../../02-prompt-engineering) - - [Constrained Output](../../../02-prompt-engineering) -- [What You're Really Learning](../../../02-prompt-engineering) -- [Next Steps](../../../02-prompt-engineering) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding Prompt Engineering](#understanding-prompt-engineering) +- [Prompt Engineering Fundamentals](#prompt-engineering-fundamentals) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Advanced Patterns](#advanced-patterns) +- [Run the Application](#run-the-application) +- [Application Screenshots](#application-screenshots) +- [Exploring the Patterns](#exploring-the-patterns) + - [Low vs High Eagerness](#low-vs-high-eagerness) + - [Task Execution (Tool Preambles)](#task-execution-tool-preambles) + - [Self-Reflecting Code](#self-reflecting-code) + - [Structured Analysis](#structured-analysis) + - [Multi-Turn Chat](#multi-turn-chat) + - [Step-by-Step Reasoning](#step-by-step-reasoning) + - [Constrained Output](#constrained-output) +- [What You're Really Learning](#what-youre-really-learning) +- [Next Steps](#next-steps) ## Video Walkthrough @@ -38,9 +38,9 @@ The following diagram provides an overview of the key topics and skills you'll d What You'll Learn -In the previous modules, you explored basic LangChain4j interactions with GitHub Models and saw how memory enables conversational AI with Azure OpenAI. Now we'll focus on how you ask questions — the prompts themselves — using Azure OpenAI's GPT-5.2. The way you structure your prompts dramatically affects the quality of responses you get. We start with a review of the fundamental prompting techniques, then move into eight advanced patterns that take full advantage of GPT-5.2's capabilities. +In the previous module, you saw how memory enables conversational AI with Azure OpenAI. Now we'll focus on how you ask questions — the prompts themselves — using Azure OpenAI's GPT-5.2. The way you structure your prompts dramatically affects the quality of responses you get. We start with a review of the fundamental prompting techniques, then move into eight advanced patterns that take full advantage of GPT-5.2's capabilities. -We'll use GPT-5.2 because it introduces reasoning control - you can tell the model how much thinking to do before answering. This makes different prompting strategies more apparent and helps you understand when to use each approach. We'll also benefit from Azure's fewer rate limits for GPT-5.2 compared to GitHub Models. +We'll use GPT-5.2 because it introduces reasoning control - you can tell the model how much thinking to do before answering. This makes different prompting strategies more apparent and helps you understand when to use each approach. ## Prerequisites @@ -71,7 +71,7 @@ The five core techniques shown below form the foundation of effective prompt eng Five Prompt Engineering Patterns Overview -Before diving into the advanced patterns in this module, let's review five foundational prompting techniques. These are the building blocks that every prompt engineer should know. If you've already worked through the [Quick Start module](../00-quick-start/README.md#2-prompt-patterns), you've seen these in action — here's the conceptual framework behind them. +Before diving into the advanced patterns in this module, let's review five foundational prompting techniques. These are the building blocks that every prompt engineer should know. ### Zero-Shot Prompting @@ -384,6 +384,7 @@ The diagram below visualizes how conversation context accumulates with each turn Context Memory *How conversation context accumulates over multiple turns until reaching the token limit* + **Step-by-Step Reasoning** - For problems requiring visible logic. The model shows explicit reasoning for each step. Use this for math problems, logic puzzles, or when you need to understand the thinking process. ```java @@ -401,7 +402,6 @@ String response = chatModel.chat(prompt); The diagram below illustrates how the model breaks problems into explicit, numbered logical steps. Step-by-Step Pattern - *Breaking down problems into explicit logical steps* **Constrained Output** - For responses with specific format requirements. The model strictly follows format and length rules. Use this for summaries or when you need precise output structure. @@ -604,5 +604,5 @@ Multi-turn conversations work by including message history with each request. Bu **Disclaimer**: -This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. +This document has been translated using AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. \ No newline at end of file diff --git a/translations/en/03-rag/README.md b/translations/en/03-rag/README.md index 45cfcd01f..850fecb32 100644 --- a/translations/en/03-rag/README.md +++ b/translations/en/03-rag/README.md @@ -2,29 +2,29 @@ ## Table of Contents -- [Video Walkthrough](../../../03-rag) -- [What You'll Learn](../../../03-rag) -- [Prerequisites](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Does This Tutorial Use?](../../../03-rag) -- [How It Works](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload a Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matters](../../../03-rag) -- [Next Steps](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding RAG](#understanding-rag) + - [Which RAG Approach Does This Tutorial Use?](#which-rag-approach-does-this-tutorial-use) +- [How It Works](#how-it-works) + - [Document Processing](#document-processing) + - [Creating Embeddings](#creating-embeddings) + - [Semantic Search](#semantic-search) + - [Answer Generation](#answer-generation) +- [Run the Application](#run-the-application) +- [Using the Application](#using-the-application) + - [Upload a Document](#upload-a-document) + - [Ask Questions](#ask-questions) + - [Check Source References](#check-source-references) + - [Experiment with Questions](#experiment-with-questions) +- [Key Concepts](#key-concepts) + - [Chunking Strategy](#chunking-strategy) + - [Similarity Scores](#similarity-scores) + - [In-Memory Storage](#in-memory-storage) + - [Context Window Management](#context-window-management) +- [When RAG Matters](#when-rag-matters) +- [Next Steps](#next-steps) ## Video Walkthrough @@ -40,18 +40,17 @@ RAG (Retrieval-Augmented Generation) solves this problem. Instead of trying to t Think of RAG as giving the model a reference library. When you ask a question, the system: -1. **User Query** - You ask a question -2. **Embedding** - Converts your question to a vector -3. **Vector Search** - Finds similar document chunks -4. **Context Assembly** - Adds relevant chunks to the prompt +1. **User Query** - You ask a question +2. **Embedding** - Converts your question to a vector +3. **Vector Search** - Finds similar document chunks +4. **Context Assembly** - Adds relevant chunks to the prompt 5. **Response** - LLM generates an answer based on the context This grounds the model's responses in your actual data instead of relying on its training knowledge or making up answers. ## Prerequisites -- Completed [Module 00 - Quick Start](../00-quick-start/README.md) (for the Easy RAG example referenced later in this module) -- Completed [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI resources deployed, including the `text-embedding-3-small` embedding model) +- Completed [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI resources deployed, including the `text-embedding-3-small` embedding model) - `.env` file in root directory with Azure credentials (created by `azd up` in Module 01) > **Note:** If you haven't completed Module 01, follow the deployment instructions there first. The `azd up` command deploys both the GPT chat model and the embedding model used by this module. @@ -80,21 +79,21 @@ LangChain4j offers three ways to implement RAG, each with a different level of a *This diagram compares the three LangChain4j RAG approaches — Easy, Native, and Advanced — showing their key components and when to use each one.* -| Approach | What It Does | Trade-off | -|---|---|---| -| **Easy RAG** | Wires everything automatically through `AiServices` and `ContentRetriever`. You annotate an interface, attach a retriever, and LangChain4j handles embedding, searching, and prompt assembly behind the scenes. | Minimal code, but you don't see what's happening at each step. | -| **Native RAG** | You call the embedding model, search the store, build the prompt, and generate the answer yourself — one explicit step at a time. | More code, but every stage is visible and modifiable. | -| **Advanced RAG** | Uses the `RetrievalAugmentor` framework with pluggable query transformers, routers, re-rankers, and content injectors for production-grade pipelines. | Maximum flexibility, but significantly more complexity. | +| Approach | What It Does | Trade-off | +|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| +| **Easy RAG** | Wires everything automatically through `AiServices` and `ContentRetriever`. You annotate an interface, attach a retriever, and LangChain4j handles embedding, searching, and prompt assembly behind the scenes. | Minimal code, but you don't see what's happening at each step. | +| **Native RAG** | You call the embedding model, search the store, build the prompt, and generate the answer yourself — one explicit step at a time. | More code, but every stage is visible and modifiable. | +| **Advanced RAG** | Uses the `RetrievalAugmentor` framework with pluggable query transformers, routers, re-rankers, and content injectors for production-grade pipelines. | Maximum flexibility, but significantly more complexity. | **This tutorial uses the Native approach.** Each step of the RAG pipeline — embedding the query, searching the vector store, assembling the context, and generating the answer — is written out explicitly in [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). This is intentional: as a learning resource, it's more important that you see and understand every stage than that the code is minimized. Once you're comfortable with how the pieces fit together, you can graduate to Easy RAG for quick prototypes or Advanced RAG for production systems. -> **💡 Already seen Easy RAG in action?** The [Quick Start module](../00-quick-start/README.md) includes a Document Q&A example ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) that uses the Easy RAG approach — LangChain4j handles embedding, searching, and prompt assembly automatically. This module takes the next step by breaking open that pipeline so you can see and control each stage yourself. +> **💡 Curious about Easy RAG?** LangChain4j also offers an *Easy RAG* approach where `AiServices` and a `ContentRetriever` handle embedding, searching, and prompt assembly automatically. This module takes the more explicit path — breaking open that pipeline so you can see and control each stage yourself. -The diagram below shows the Easy RAG pipeline from that Quick Start example. Notice how `AiServices` and `EmbeddingStoreContentRetriever` hide all the complexity — you load a document, attach a retriever, and get answers. The Native approach in this module breaks each of those hidden steps open: +The diagram below shows the Easy RAG pipeline. Notice how `AiServices` and `EmbeddingStoreContentRetriever` hide all the complexity — you load a document, attach a retriever, and get answers. The Native approach in this module breaks each of those hidden steps open: Easy RAG Pipeline - LangChain4j -*This diagram shows the Easy RAG pipeline from `SimpleReaderDemo.java`. Compare this with the Native approach used in this module: Easy RAG hides the embedding, retrieval, and prompt assembly behind `AiServices` and `ContentRetriever` — you load a document, attach a retriever, and get answers. The Native approach in this module breaks that pipeline open so you call each stage (embed, search, assemble context, generate) yourself, giving you full visibility and control.* +*This diagram shows the Easy RAG pipeline. Compare this with the Native approach used in this module: Easy RAG hides the embedding, retrieval, and prompt assembly behind `AiServices` and `ContentRetriever` — you load a document, attach a retriever, and get answers. The Native approach in this module breaks that pipeline open so you call each stage (embed, search, assemble context, generate) yourself, giving you full visibility and control.* ## How It Works @@ -123,9 +122,9 @@ The diagram below shows how this works visually. Notice how each chunk shares so *This diagram shows a document being split into 300-token chunks with 30-token overlap, preserving context at chunk boundaries.* -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) and ask: -> - "How does LangChain4j split documents into chunks and why is overlap important?" -> - "What's the optimal chunk size for different document types and why?" +> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) and ask: +> - "How does LangChain4j split documents into chunks and why is overlap important?" +> - "What's the optimal chunk size for different document types and why?" > - "How do I handle documents in multiple languages or with special formatting?" ### Creating Embeddings @@ -201,10 +200,10 @@ The diagram below contrasts semantic search with traditional keyword search. A k Semantic Search *This diagram compares keyword-based search with semantic search, showing how semantic search retrieves conceptually related content even when exact keywords differ.* + Under the hood, similarity is measured using cosine similarity — essentially asking "are these two arrows pointing in the same direction?" Two chunks can use completely different words, but if they mean the same thing their vectors point the same way and score close to 1.0: Cosine Similarity - *This diagram illustrates cosine similarity as the angle between embedding vectors — more aligned vectors score closer to 1.0, indicating higher semantic similarity.* > **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) and ask: @@ -433,5 +432,5 @@ RAG isn't always the right approach. The decision guide below helps you determin **Disclaimer**: -This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. +This document has been translated using AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. \ No newline at end of file diff --git a/translations/en/04-tools/README.md b/translations/en/04-tools/README.md index 4f2d11d4c..310543bd9 100644 --- a/translations/en/04-tools/README.md +++ b/translations/en/04-tools/README.md @@ -2,32 +2,32 @@ ## Table of Contents -- [Video Walkthrough](../../../04-tools) -- [What You'll Learn](../../../04-tools) -- [Prerequisites](../../../04-tools) -- [Understanding AI Agents with Tools](../../../04-tools) -- [How Tool Calling Works](../../../04-tools) - - [Tool Definitions](../../../04-tools) - - [Decision Making](../../../04-tools) - - [Execution](../../../04-tools) - - [Response Generation](../../../04-tools) - - [Architecture: Spring Boot Auto-Wiring](../../../04-tools) -- [Tool Chaining](../../../04-tools) -- [Run the Application](../../../04-tools) -- [Using the Application](../../../04-tools) - - [Try Simple Tool Usage](../../../04-tools) - - [Test Tool Chaining](../../../04-tools) - - [See Conversation Flow](../../../04-tools) - - [Experiment with Different Requests](../../../04-tools) -- [Key Concepts](../../../04-tools) - - [ReAct Pattern (Reasoning and Acting)](../../../04-tools) - - [Tool Descriptions Matter](../../../04-tools) - - [Session Management](../../../04-tools) - - [Error Handling](../../../04-tools) -- [Available Tools](../../../04-tools) -- [When to Use Tool-Based Agents](../../../04-tools) -- [Tools vs RAG](../../../04-tools) -- [Next Steps](../../../04-tools) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding AI Agents with Tools](#understanding-ai-agents-with-tools) +- [How Tool Calling Works](#how-tool-calling-works) + - [Tool Definitions](#tool-definitions) + - [Decision Making](#decision-making) + - [Execution](#execution) + - [Response Generation](#response-generation) + - [Architecture: Spring Boot Auto-Wiring](#architecture-spring-boot-auto-wiring) +- [Tool Chaining](#tool-chaining) +- [Run the Application](#run-the-application) +- [Using the Application](#using-the-application) + - [Try Simple Tool Usage](#try-simple-tool-usage) + - [Test Tool Chaining](#test-tool-chaining) + - [See Conversation Flow](#see-conversation-flow) + - [Experiment with Different Requests](#experiment-with-different-requests) +- [Key Concepts](#key-concepts) + - [ReAct Pattern (Reasoning and Acting)](#react-pattern-reasoning-and-acting) + - [Tool Descriptions Matter](#tool-descriptions-matter) + - [Session Management](#session-management) + - [Error Handling](#error-handling) +- [Available Tools](#available-tools) +- [When to Use Tool-Based Agents](#when-to-use-tool-based-agents) +- [Tools vs RAG](#tools-vs-rag) +- [Next Steps](#next-steps) ## Video Walkthrough @@ -133,11 +133,11 @@ Spring Boot auto-wires the declarative `@AiService` interface with all registere *The end-to-end flow — the user asks a question, the model selects a tool, LangChain4j executes it, and the model weaves the result into a natural response.* -If you ran the [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) in Module 00, you already saw this pattern in action — the `Calculator` tools were called the same way. The sequence diagram below shows exactly what happened under the hood during that demo: +Behind the scenes, `AiServices` runs the same tool-calling loop for any tool — here illustrated with a simple `Calculator`. The sequence diagram below shows exactly what happens under the hood: Tool Calling Sequence Diagram -*The tool-calling loop from the Quick Start demo — `AiServices` sends your message and tool schemas to the LLM, the LLM replies with a function call like `add(42, 58)`, LangChain4j executes the `Calculator` method locally, and feeds the result back for the final answer.* +*The tool-calling loop — `AiServices` sends your message and tool schemas to the LLM, the LLM replies with a function call like `add(42, 58)`, LangChain4j executes the `Calculator` method locally, and feeds the result back for the final answer.* > **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) and ask: > - "How does the ReAct pattern work and why is it effective for AI agents?" @@ -218,10 +218,10 @@ From the Spring Boot Dashboard, you can: - Start/stop applications with a single click - View application logs in real-time - Monitor application status + Simply click the play button next to "tools" to start this module, or start all modules at once. Here's what the Spring Boot Dashboard looks like in VS Code: - Spring Boot Dashboard *The Spring Boot Dashboard in VS Code — start, stop, and monitor all modules from one place* diff --git a/translations/en/README.md b/translations/en/README.md index 6113a3b1d..97ba4c068 100644 --- a/translations/en/README.md +++ b/translations/en/README.md @@ -34,12 +34,11 @@ A course for building AI applications with LangChain4j and Azure OpenAI GPT-5.2, ## Table of Contents -1. [Quick Start](00-quick-start/README.md) - Get started with LangChain4j -2. [Introduction](01-introduction/README.md) - Learn the fundamentals of LangChain4j -3. [Prompt Engineering](02-prompt-engineering/README.md) - Master effective prompt design -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Build intelligent knowledge-based systems -5. [Tools](04-tools/README.md) - Integrate external tools and simple assistants -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Work with the Model Context Protocol (MCP) and Agentic modules +1. [Introduction](01-introduction/README.md) - Learn the fundamentals of LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Master effective prompt design +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Build intelligent knowledge-based systems +4. [Tools](04-tools/README.md) - Integrate external tools and simple assistants +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Work with the Model Context Protocol (MCP) and Agentic modules ### Video Walkthroughs @@ -65,11 +64,11 @@ Each module has a companion live session where we walk through the concepts and 3. Use the defaults – this will select the Development container created for this course 4. Click **Create codespace** 5. Wait 5-10 minutes for the environment to be ready -6. Jump straight to [Quick Start](./00-quick-start/README.md) to get started! +6. Jump straight to [Introduction](./01-introduction/README.md) to get started! After completing the modules, explore the [Testing Guide](docs/TESTING.md) to see LangChain4j testing concepts in action. -> **Note:** This training uses both GitHub Models and Azure OpenAI. The [Quick Start](00-quick-start/README.md) module uses GitHub Models (no Azure subscription required), while modules 1-5 use Azure OpenAI. Get started with a [FREE Azure account](https://aka.ms/azure-free-account) if you don't have one. +> **Note:** This training uses Azure OpenAI. Get started with a [FREE Azure account](https://aka.ms/azure-free-account) if you don't have one. ## Learning with GitHub Copilot @@ -145,6 +144,6 @@ MIT License - See [LICENSE](../../LICENSE) file for details. --- -**Disclaimer**: -This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. +**Disclaimer**: +This document has been translated using AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. \ No newline at end of file diff --git a/translations/en/docs/GLOSSARY.md b/translations/en/docs/GLOSSARY.md index a2cd503a9..4ec51ece8 100644 --- a/translations/en/docs/GLOSSARY.md +++ b/translations/en/docs/GLOSSARY.md @@ -2,17 +2,17 @@ ## Table of Contents -- [Core Concepts](../../../docs) -- [LangChain4j Components](../../../docs) -- [AI/ML Concepts](../../../docs) -- [Guardrails](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agents and Tools](../../../docs) -- [Agentic Module](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure Services](../../../docs) -- [Testing and Development](../../../docs) +- [Core Concepts](#core-concepts) +- [LangChain4j Components](#langchain4j-components) +- [AI/ML Concepts](#aiml-concepts) +- [Guardrails](#guardrails) +- [Prompt Engineering](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agents and Tools](#agents-and-tools---module-04) +- [Agentic Module](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure Services](#azure-services---module-01) +- [Testing and Development](#testing-and-development---testing-guide) Quick reference for terms and concepts used throughout the course. @@ -86,7 +86,7 @@ Quick reference for terms and concepts used throughout the course. **Zero-Shot Learning** - Performing tasks without examples. [Module 02](../02-prompt-engineering/README.md) -## Guardrails - [Module 00](../00-quick-start/README.md) +## Guardrails **Defense in Depth** - Multi-layer security approach combining application-level guardrails with provider safety filters. @@ -98,7 +98,7 @@ Quick reference for terms and concepts used throughout the course. **OutputGuardrail** - Interface for validating AI responses before returning to users. -**Provider Safety Filters** - Built-in content filters from AI providers (e.g., GitHub Models) that catch violations at the API level. +**Provider Safety Filters** - Built-in content filters from AI providers (e.g., Azure OpenAI) that catch violations at the API level. **Soft Refusal** - Model politely declines to answer without throwing an error. @@ -212,8 +212,6 @@ Quick reference for terms and concepts used throughout the course. **Dev Container** - Containerized development environment. [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Free AI model playground. [Module 00](../00-quick-start/README.md) - **In-Memory Testing** - Testing with in-memory storage. **Integration Testing** - Testing with real infrastructure. @@ -228,5 +226,5 @@ Quick reference for terms and concepts used throughout the course. **Disclaimer**: -This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. +This document has been translated using AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. \ No newline at end of file diff --git a/translations/en/docs/TESTING.md b/translations/en/docs/TESTING.md index 1b4a36fe0..a9cf78739 100644 --- a/translations/en/docs/TESTING.md +++ b/translations/en/docs/TESTING.md @@ -2,13 +2,13 @@ ## Table of Contents -- [Quick Start](../../../docs) -- [What the Tests Cover](../../../docs) -- [Running the Tests](../../../docs) -- [Running Tests in VS Code](../../../docs) -- [Testing Patterns](../../../docs) -- [Testing Philosophy](../../../docs) -- [Next Steps](../../../docs) +- [Quick Start](#quick-start) +- [What the Tests Cover](#what-the-tests-cover) +- [Running the Tests](#running-the-tests) +- [Running Tests in VS Code](#running-tests-in-vs-code) +- [Testing Patterns](#testing-patterns) +- [Testing Philosophy](#testing-philosophy) +- [Next Steps](#next-steps) This guide walks you through the tests that demonstrate how to test AI applications without requiring API keys or external services. @@ -42,7 +42,6 @@ This course focuses on **unit tests** that run locally. Each test demonstrates a | Module | Tests | Focus | Key Files | |--------|-------|-------|-----------| -| **00 - Quick Start** | 6 | Prompt templates and variable substitution | `SimpleQuickStartTest.java` | | **01 - Introduction** | 8 | Conversation memory and stateful chat | `SimpleConversationTest.java` | | **02 - Prompt Engineering** | 12 | GPT-5.2 patterns, eagerness levels, structured output | `SimpleGpt5PromptTest.java` | | **03 - RAG** | 10 | Document ingestion, embeddings, similarity search | `DocumentServiceTest.java` | @@ -100,7 +99,7 @@ mvn test -Dtest=SimpleConversationTest#shouldMaintainConversationHistory **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#should maintain conversation history +mvn --% test -Dtest=SimpleConversationTest#shouldMaintainConversationHistory ``` ## Running Tests in VS Code @@ -148,19 +147,7 @@ void testPromptTemplateFormatting() { } ``` -This test lives in `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Run it:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatting -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatting -``` +This pattern verifies that variable substitution works correctly and prompts are formatted as expected — no API key or model call required. ### Pattern 2: Mocking Language Models @@ -342,7 +329,6 @@ Use descriptive names. Compare `shouldMaintainConversationHistoryAcrossMultipleM Now that you understand the testing patterns, dive deeper into each module: -- **[00 - Quick Start](../00-quick-start/README.md)** - Start with prompt template basics - **[01 - Introduction](../01-introduction/README.md)** - Learn conversation memory management - **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Master GPT-5.2 prompting patterns - **[03 - RAG](../03-rag/README.md)** - Build retrieval-augmented generation systems @@ -359,5 +345,5 @@ Each module's README provides detailed explanations of the concepts tested here. **Disclaimer**: -This document has been translated using the AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. +This document has been translated using AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). While we strive for accuracy, please be aware that automated translations may contain errors or inaccuracies. The original document in its native language should be considered the authoritative source. For critical information, professional human translation is recommended. We are not liable for any misunderstandings or misinterpretations arising from the use of this translation. \ No newline at end of file diff --git a/translations/es/.co-op-translator.json b/translations/es/.co-op-translator.json index 2d161a933..60bab8ec1 100644 --- a/translations/es/.co-op-translator.json +++ b/translations/es/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "es" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T18:33:45+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T07:10:17+00:00", "source_file": "01-introduction/README.md", "language_code": "es" }, @@ -18,20 +18,20 @@ "language_code": "es" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T18:36:23+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T07:05:13+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "es" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T18:38:06+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T07:09:25+00:00", "source_file": "03-rag/README.md", "language_code": "es" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:19:56+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T07:08:09+00:00", "source_file": "04-tools/README.md", "language_code": "es" }, @@ -54,8 +54,8 @@ "language_code": "es" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:32:13+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T07:03:18+00:00", "source_file": "README.md", "language_code": "es" }, @@ -72,14 +72,14 @@ "language_code": "es" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T18:41:35+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T07:05:48+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "es" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T18:42:26+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T07:06:23+00:00", "source_file": "docs/TESTING.md", "language_code": "es" } diff --git a/translations/es/00-quick-start/README.md b/translations/es/00-quick-start/README.md deleted file mode 100644 index 8cb9548cd..000000000 --- a/translations/es/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Inicio rápido - -## Tabla de contenidos - -- [Introducción](../../../00-quick-start) -- [¿Qué es LangChain4j?](../../../00-quick-start) -- [Dependencias de LangChain4j](../../../00-quick-start) -- [Requisitos previos](../../../00-quick-start) -- [Configuración](../../../00-quick-start) - - [1. Obtén tu token de GitHub](../../../00-quick-start) - - [2. Configura tu token](../../../00-quick-start) -- [Ejecuta los ejemplos](../../../00-quick-start) - - [1. Chat básico](../../../00-quick-start) - - [2. Patrones de solicitud](../../../00-quick-start) - - [3. Llamada a funciones](../../../00-quick-start) - - [4. Preguntas y respuestas sobre documentos (Easy RAG)](../../../00-quick-start) - - [5. IA responsable](../../../00-quick-start) -- [Qué muestra cada ejemplo](../../../00-quick-start) -- [Próximos pasos](../../../00-quick-start) -- [Solución de problemas](../../../00-quick-start) - -## Introducción - -Este inicio rápido está diseñado para que puedas comenzar a trabajar con LangChain4j lo más rápido posible. Cubre lo básico absoluto para construir aplicaciones de IA con LangChain4j y GitHub Models. En los próximos módulos cambiarás a Azure OpenAI y GPT-5.2 y profundizarás en cada concepto. - -## ¿Qué es LangChain4j? - -LangChain4j es una biblioteca Java que simplifica la creación de aplicaciones impulsadas por IA. En lugar de lidiar con clientes HTTP y análisis de JSON, trabajas con APIs Java limpias. - -La "cadena" en LangChain se refiere a encadenar múltiples componentes: podrías encadenar un prompt a un modelo, luego a un parser, o encadenar múltiples llamadas de IA donde la salida de una alimenta la entrada siguiente. Este inicio rápido se enfoca en los fundamentos antes de explorar cadenas más complejas. - -Concepto de encadenamiento de LangChain4j - -*Encadenar componentes en LangChain4j: bloques de construcción que se conectan para crear flujos de trabajo de IA potentes* - -Usaremos tres componentes principales: - -**ChatModel** - La interfaz para interacciones con modelos de IA. Llama a `model.chat("prompt")` y recibe una respuesta como cadena. Usamos `OpenAiOfficialChatModel` que funciona con endpoints compatibles con OpenAI como GitHub Models. - -**AiServices** - Crea interfaces de servicio AI con tipado seguro. Define métodos, anótalos con `@Tool` y LangChain4j maneja la orquestación. La IA llama automáticamente a tus métodos Java cuando es necesario. - -**MessageWindowChatMemory** - Mantiene el historial de conversación. Sin esto, cada petición es independiente. Con él, la IA recuerda mensajes previos y mantiene el contexto a través de múltiples intervenciones. - -Arquitectura de LangChain4j - -*Arquitectura de LangChain4j: componentes principales que trabajan juntos para potenciar tus aplicaciones de IA* - -## Dependencias de LangChain4j - -Este inicio rápido usa tres dependencias Maven en el [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -El módulo `langchain4j-open-ai-official` provee la clase `OpenAiOfficialChatModel` que conecta con APIs compatibles con OpenAI. GitHub Models usa el mismo formato de API, por lo que no se necesita un adaptador especial — solo apunta la URL base a `https://models.github.ai/inference`. - -El módulo `langchain4j-easy-rag` provee división automática de documentos, generación de embeddings y recuperación para que puedas construir aplicaciones RAG sin configurar cada paso manualmente. - -## Requisitos previos - -**¿Usando el contenedor Dev?** Java y Maven ya están instalados. Solo necesitas un Token de Acceso Personal de GitHub. - -**Desarrollo local:** -- Java 21+, Maven 3.9+ -- Token de Acceso Personal de GitHub (instrucciones abajo) - -> **Nota:** Este módulo usa `gpt-4.1-nano` de GitHub Models. No modifiques el nombre del modelo en el código — está configurado para funcionar con los modelos disponibles de GitHub. - -## Configuración - -### 1. Obtén tu token de GitHub - -1. Ve a [Configuración de GitHub → Tokens de acceso personal](https://github.com/settings/personal-access-tokens) -2. Haz clic en "Generate new token" (Generar nuevo token) -3. Asigna un nombre descriptivo (p. ej., "Demo LangChain4j") -4. Configura la expiración (7 días recomendado) -5. En "Permisos de la cuenta", busca "Models" y ponlo en "Solo lectura" -6. Haz clic en "Generate token" (Generar token) -7. Copia y guarda tu token — no lo verás de nuevo - -### 2. Configura tu token - -**Opción 1: Usando VS Code (Recomendado)** - -Si usas VS Code, agrega tu token al archivo `.env` en la raíz del proyecto: - -Si el archivo `.env` no existe, copia `.env.example` a `.env` o crea un archivo `.env` nuevo en la raíz del proyecto. - -**Ejemplo de archivo `.env`:** -```bash -# En /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Luego simplemente haz clic derecho en cualquier archivo demo (p. ej., `BasicChatDemo.java`) en el Explorador y selecciona **"Run Java"** o usa las configuraciones de ejecución desde el panel Ejecutar y Depurar. - -**Opción 2: Usando Terminal** - -Configura el token como variable de entorno: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Ejecuta los ejemplos - -**Usando VS Code:** Simplemente haz clic derecho en cualquier archivo demo en el Explorador y selecciona **"Run Java"**, o usa las configuraciones desde el panel Ejecutar y Depurar (asegúrate de haber agregado tu token al archivo `.env` primero). - -**Usando Maven:** Alternativamente, puedes ejecutar desde línea de comandos: - -### 1. Chat básico - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Patrones de solicitud - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Muestra zero-shot, few-shot, cadena de pensamiento y solicitudes basadas en roles. - -### 3. Llamada a funciones - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -La IA llama automáticamente a tus métodos Java cuando es necesario. - -### 4. Preguntas y respuestas sobre documentos (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Haz preguntas sobre tus documentos usando Easy RAG con embedding y recuperación automáticos. - -### 5. IA responsable - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Ve cómo los filtros de seguridad de IA bloquean contenido dañino. - -## Qué muestra cada ejemplo - -**Chat básico** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Comienza aquí para ver LangChain4j en su forma más simple. Crearás un `OpenAiOfficialChatModel`, enviarás un prompt con `.chat()` y recibirás una respuesta. Esto demuestra la base: cómo inicializar modelos con endpoints y claves API personalizadas. Una vez entiendas este patrón, todo lo demás se construye sobre él. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) y pregunta: -> - "¿Cómo cambiaría de GitHub Models a Azure OpenAI en este código?" -> - "¿Qué otros parámetros puedo configurar en OpenAiOfficialChatModel.builder()?" -> - "¿Cómo agrego respuestas en streaming en lugar de esperar la respuesta completa?" - -**Ingeniería de prompts** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Ahora que sabes cómo hablar con un modelo, exploremos qué le dices. Esta demo usa la misma configuración de modelo pero muestra cinco patrones de prompt diferentes. Prueba prompts zero-shot para instrucciones directas, few-shot que aprenden de ejemplos, cadena de pensamiento que revela pasos de razonamiento y prompts basados en roles que establecen contexto. Verás cómo el mismo modelo da resultados muy distintos según cómo plantees la petición. - -La demo también muestra plantillas de prompt, que son una forma poderosa de crear prompts reutilizables con variables. -El siguiente ejemplo muestra un prompt usando la `PromptTemplate` de LangChain4j para rellenar variables. La IA responderá basado en el destino y la actividad proporcionados. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) y pregunta: -> - "¿Cuál es la diferencia entre zero-shot y few-shot prompting, y cuándo debería usar cada uno?" -> - "¿Cómo afecta el parámetro temperature las respuestas del modelo?" -> - "¿Cuáles son algunas técnicas para prevenir ataques de inyección de prompt en producción?" -> - "¿Cómo puedo crear objetos PromptTemplate reutilizables para patrones comunes?" - -**Integración de herramientas** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Aquí es donde LangChain4j se vuelve potente. Usarás `AiServices` para crear un asistente de IA capaz de llamar a tus métodos Java. Solo anota los métodos con `@Tool("descripción")` y LangChain4j hace el resto — la IA decide automáticamente cuándo usar cada herramienta según lo que el usuario pida. Esto demuestra la llamada a funciones, una técnica clave para construir IA que puede tomar acciones, no solo responder preguntas. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) y pregunta: -> - "¿Cómo funciona la anotación @Tool y qué hace LangChain4j con ella detrás de escena?" -> - "¿Puede la IA llamar a múltiples herramientas en secuencia para resolver problemas complejos?" -> - "¿Qué pasa si una herramienta lanza una excepción - cómo debo manejar errores?" -> - "¿Cómo integraría una API real en lugar de este ejemplo calculadora?" - -**Preguntas y respuestas sobre documentos (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Aquí verás RAG (generación aumentada por recuperación) usando el enfoque "Easy RAG" de LangChain4j. Se cargan documentos, se dividen y embeben automáticamente en un almacén en memoria, luego un recuperador de contenido suministra fragmentos relevantes a la IA al consultar. La IA responde basado en tus documentos, no en su conocimiento general. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) y pregunta: -> - "¿Cómo previene RAG las alucinaciones de IA en comparación con usar los datos de entrenamiento del modelo?" -> - "¿Cuál es la diferencia entre este enfoque fácil y una tubería RAG personalizada?" -> - "¿Cómo escalaría esto para manejar múltiples documentos o bases de conocimiento más grandes?" - -**IA responsable** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Construye seguridad en IA con defensa en profundidad. Esta demo muestra dos capas de protección trabajando juntas: - -**Parte 1: LangChain4j Input Guardrails** - Bloquea prompts peligrosos antes de que lleguen al LLM. Crea guardrails personalizados que revisen palabras clave o patrones prohibidos. Estos corren en tu código, son rápidos y gratuitos. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Parte 2: Filtros de seguridad del proveedor** - GitHub Models tiene filtros integrados que atrapan lo que tus guardrails podrían pasar por alto. Verás bloqueos duros (errores HTTP 400) por violaciones severas y rechazos suaves donde la IA se niega cortésmente. - -> **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) y pregunta: -> - "¿Qué es InputGuardrail y cómo creo el mío?" -> - "¿Cuál es la diferencia entre un bloqueo duro y un rechazo suave?" -> - "¿Por qué usar guardrails y filtros del proveedor juntos?" - -## Próximos pasos - -**Siguiente módulo:** [01-introduction - Comenzando con LangChain4j](../01-introduction/README.md) - ---- - -**Navegación:** [← Volver al principal](../README.md) | [Siguiente: Módulo 01 - Introducción →](../01-introduction/README.md) - ---- - -## Solución de problemas - -### Primera compilación Maven - -**Problema**: El comando inicial `mvn clean compile` o `mvn package` tarda mucho (10-15 minutos) - -**Causa**: Maven necesita descargar todas las dependencias del proyecto (Spring Boot, librerías LangChain4j, SDKs de Azure, etc.) en la primera compilación. - -**Solución**: Este comportamiento es normal. Las compilaciones posteriores serán mucho más rápidas porque las dependencias se almacenan en caché localmente. El tiempo de descarga depende de la velocidad de tu red. - -### Sintaxis del comando Maven en PowerShell - -**Problema**: Los comandos Maven fallan con el error `Unknown lifecycle phase ".mainClass=..."` -**Causa**: PowerShell interpreta `=` como un operador de asignación de variable, rompiendo la sintaxis de propiedades de Maven - -**Solución**: Use el operador de parada de análisis `--%` antes del comando Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -El operador `--%` indica a PowerShell que pase todos los argumentos restantes literalmente a Maven sin interpretarlos. - -### Visualización de emojis en Windows PowerShell - -**Problema**: Las respuestas de IA muestran caracteres basura (por ejemplo, `????` o `â??`) en lugar de emojis en PowerShell - -**Causa**: La codificación predeterminada de PowerShell no soporta emojis UTF-8 - -**Solución**: Ejecute este comando antes de ejecutar aplicaciones Java: -```cmd -chcp 65001 -``` - -Esto fuerza la codificación UTF-8 en la terminal. Alternativamente, use Windows Terminal que tiene mejor soporte para Unicode. - -### Depuración de llamadas a la API - -**Problema**: Errores de autenticación, límites de tasa o respuestas inesperadas del modelo de IA - -**Solución**: Los ejemplos incluyen `.logRequests(true)` y `.logResponses(true)` para mostrar llamadas a la API en la consola. Esto ayuda a solucionar errores de autenticación, límites de tasa o respuestas inesperadas. Elimine estas banderas en producción para reducir el ruido del registro. - ---- - - -**Aviso Legal**: -Este documento ha sido traducido utilizando el servicio de traducción AI [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la exactitud, tenga en cuenta que las traducciones automáticas pueden contener errores o imprecisiones. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional realizada por humanos. No nos hacemos responsables de malentendidos o interpretaciones erróneas derivadas del uso de esta traducción. - \ No newline at end of file diff --git a/translations/es/01-introduction/README.md b/translations/es/01-introduction/README.md index 17204615c..a92c693e2 100644 --- a/translations/es/01-introduction/README.md +++ b/translations/es/01-introduction/README.md @@ -1,87 +1,87 @@ -# Módulo 01: Comenzando con LangChain4j +# Módulo 01: Introducción a LangChain4j ## Tabla de Contenidos -- [Recorrido en Video](../../../01-introduction) -- [Lo Que Aprenderás](../../../01-introduction) -- [Prerrequisitos](../../../01-introduction) -- [Entendiendo el Problema Central](../../../01-introduction) -- [Entendiendo los Tokens](../../../01-introduction) -- [Cómo Funciona la Memoria](../../../01-introduction) -- [Cómo Esto Usa LangChain4j](../../../01-introduction) -- [Implementar Infraestructura Azure OpenAI](../../../01-introduction) -- [Ejecutar la Aplicación Localmente](../../../01-introduction) -- [Usando la Aplicación](../../../01-introduction) - - [Chat Sin Estado (Panel Izquierdo)](../../../01-introduction) - - [Chat con Estado (Panel Derecho)](../../../01-introduction) -- [Próximos Pasos](../../../01-introduction) - -## Recorrido en Video +- [Video Tutorial](#video-tutorial) +- [Lo que Aprenderás](#lo-que-aprenderás) +- [Requisitos Previos](#requisitos-previos) +- [Comprendiendo el Problema Central](#comprendiendo-el-problema-central) +- [Comprendiendo los Tokens](#comprendiendo-los-tokens) +- [Cómo Funciona la Memoria](#cómo-funciona-la-memoria) +- [Cómo Esto Usa LangChain4j](#cómo-esto-usa-langchain4j) +- [Desplegar Infraestructura Azure OpenAI](#desplegar-infraestructura-azure-openai) +- [Ejecutar la Aplicación Localmente](#ejecutar-la-aplicación-localmente) +- [Usando la Aplicación](#usando-la-aplicación) + - [Chat Sin Estado (Panel Izquierdo)](#chat-sin-estado-panel-izquierdo) + - [Chat Con Estado (Panel Derecho)](#chat-con-estado-panel-derecho) +- [Próximos Pasos](#próximos-pasos) + +## Video Tutorial Mira esta sesión en vivo que explica cómo comenzar con este módulo: Comenzando con LangChain4j - Sesión en Vivo -## Lo Que Aprenderás +## Lo que Aprenderás -En el inicio rápido, usaste Modelos de GitHub para enviar indicaciones, llamar herramientas, construir una tubería RAG y probar límites de seguridad. Esas demostraciones mostraron lo que es posible — ahora cambiamos a Azure OpenAI y GPT-5.2 para comenzar a construir aplicaciones al estilo producción. Este módulo se enfoca en IA conversacional que recuerda contexto y mantiene estado — los conceptos que esos demos de inicio rápido usaron detrás de escena pero no explicaron. +Este es tu punto de partida con LangChain4j y Azure OpenAI. Comenzamos con los fundamentos y empezamos a construir aplicaciones de estilo producción. Este módulo se centra en IA conversacional que recuerda el contexto y mantiene el estado — los conceptos fundamentales sobre los que se construyen todos los módulos posteriores. Usaremos GPT-5.2 de Azure OpenAI a lo largo de esta guía porque sus capacidades avanzadas de razonamiento hacen que el comportamiento de diferentes patrones sea más evidente. Cuando agregas memoria, verás claramente la diferencia. Esto facilita entender qué aporta cada componente a tu aplicación. Construirás una aplicación que demuestra ambos patrones: -**Chat Sin Estado** - Cada solicitud es independiente. El modelo no recuerda mensajes previos. Este es el patrón que usaste en el inicio rápido. +**Chat Sin Estado** - Cada solicitud es independiente. El modelo no tiene memoria de mensajes anteriores. Este es el punto de partida más simple. -**Conversación con Estado** - Cada solicitud incluye el historial de la conversación. El modelo mantiene el contexto a través de múltiples interacciones. Esto es lo que requieren las aplicaciones en producción. +**Conversación Con Estado** - Cada solicitud incluye el historial de la conversación. El modelo mantiene el contexto a través de múltiples intercambios. Esto es lo que requieren las aplicaciones de producción. -## Prerrequisitos +## Requisitos Previos -- Suscripción de Azure con acceso a Azure OpenAI -- Java 21, Maven 3.9+ +- Suscripción Azure con acceso a Azure OpenAI +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) > **Nota:** Java, Maven, Azure CLI y Azure Developer CLI (azd) están preinstalados en el devcontainer proporcionado. -> **Nota:** Este módulo usa GPT-5.2 en Azure OpenAI. La implementación se configura automáticamente vía `azd up` - no modifiques el nombre del modelo en el código. +> **Nota:** Este módulo usa GPT-5.2 en Azure OpenAI. El despliegue se configura automáticamente mediante `azd up` - no modifiques el nombre del modelo en el código. -## Entendiendo el Problema Central +## Comprendiendo el Problema Central -Los modelos de lenguaje no mantienen estado. Cada llamada a la API es independiente. Si envías "Me llamo Juan" y luego preguntas "¿Cómo me llamo?", el modelo no sabe que acabas de presentarte. Trata cada solicitud como si fuera la primera conversación que tienes. +Los modelos de lenguaje son sin estado. Cada llamada a la API es independiente. Si envías "Mi nombre es John" y luego preguntas "¿Cuál es mi nombre?", el modelo no tiene idea de que acabas de presentarte. Trata cada solicitud como si fuera la primera conversación que tienes. -Esto está bien para preguntas y respuestas simples pero no sirve para aplicaciones reales. Los bots de atención al cliente necesitan recordar lo que les dijiste. Los asistentes personales necesitan contexto. Cualquier conversación de múltiples turnos requiere memoria. +Esto está bien para preguntas y respuestas simples, pero es inútil para aplicaciones reales. Los bots de atención al cliente necesitan recordar lo que les dijiste. Los asistentes personales necesitan contexto. Cualquier conversación con múltiples intercambios requiere memoria. El siguiente diagrama contrasta los dos enfoques — a la izquierda, una llamada sin estado que olvida tu nombre; a la derecha, una llamada con estado respaldada por ChatMemory que lo recuerda. -Conversaciones sin estado vs con estado +Conversaciones Sin Estado vs Con Estado -*La diferencia entre conversaciones sin estado (llamadas independientes) y con estado (con consciencia de contexto)* +*La diferencia entre conversaciones sin estado (llamadas independientes) y con estado (con conocimiento del contexto)* -## Entendiendo los Tokens +## Comprendiendo los Tokens -Antes de adentrarnos en las conversaciones, es importante entender los tokens - las unidades básicas de texto que procesan los modelos de lenguaje: +Antes de profundizar en las conversaciones, es importante entender los tokens - las unidades básicas de texto que procesan los modelos de lenguaje: Explicación de Tokens -*Ejemplo de cómo el texto se divide en tokens - "I love AI!" se convierte en 4 unidades separadas para procesamiento* +*Ejemplo de cómo el texto se descompone en tokens - "¡Me encanta la IA!" se convierte en 4 unidades de procesamiento separadas* -Los tokens son cómo los modelos de IA miden y procesan texto. Palabras, puntuación e incluso espacios pueden ser tokens. Tu modelo tiene un límite de cuántos tokens puede procesar a la vez (400,000 para GPT-5.2, con hasta 272,000 tokens de entrada y 128,000 de salida). Entender los tokens te ayuda a manejar la longitud de la conversación y los costos. +Los tokens son cómo los modelos de IA miden y procesan texto. Las palabras, la puntuación e incluso los espacios pueden ser tokens. Tu modelo tiene un límite de cuántos tokens puede procesar a la vez (400,000 para GPT-5.2, con hasta 272,000 tokens de entrada y 128,000 tokens de salida). Entender los tokens te ayuda a manejar la longitud de la conversación y los costos. ## Cómo Funciona la Memoria -La memoria de chat resuelve el problema de no mantener estado al conservar el historial de la conversación. Antes de enviar tu solicitud al modelo, el framework antepone mensajes previos relevantes. Cuando preguntas "¿Cómo me llamo?", el sistema en realidad envía todo el historial de la conversación, permitiendo al modelo ver que previamente dijiste "Me llamo Juan." +La memoria de chat resuelve el problema sin estado manteniendo el historial de la conversación. Antes de enviar tu solicitud al modelo, el framework antepone los mensajes previos relevantes. Cuando preguntas "¿Cuál es mi nombre?", el sistema envía en realidad todo el historial de la conversación, permitiendo que el modelo vea que previamente dijiste "Mi nombre es John." -LangChain4j provee implementaciones de memoria que manejan esto automáticamente. Tú eliges cuántos mensajes conservar y el framework administra la ventana de contexto. El siguiente diagrama muestra cómo MessageWindowChatMemory mantiene una ventana deslizante de mensajes recientes. +LangChain4j provee implementaciones de memoria que manejan esto automáticamente. Tú eliges cuántos mensajes conservar y el framework gestiona la ventana de contexto. El diagrama a continuación muestra cómo MessageWindowChatMemory mantiene una ventana deslizante de mensajes recientes. Concepto de Ventana de Memoria -*MessageWindowChatMemory mantiene una ventana deslizante de mensajes recientes, descartando automáticamente los más antiguos* +*MessageWindowChatMemory mantiene una ventana deslizante de mensajes recientes, descartando automáticamente los antiguos* ## Cómo Esto Usa LangChain4j -Este módulo extiende el inicio rápido integrando Spring Boot y añadiendo memoria a la conversación. Así es como encajan las piezas: +Este módulo integra Spring Boot y añade memoria de conversación. Así es como encajan las piezas: -**Dependencias** - Añade dos librerías de LangChain4j: +**Dependencias** - Agrega dos librerías de LangChain4j: ```xml @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -El constructor lee credenciales de variables de entorno establecidas por `azd up`. Configurar `baseUrl` a tu endpoint de Azure hace que el cliente OpenAI funcione con Azure OpenAI. +El builder lee las credenciales de variables de ambiente establecidas por `azd up`. Configurar `baseUrl` con tu endpoint de Azure hace que el cliente OpenAI funcione con Azure OpenAI. **Memoria de Conversación** - Rastrea el historial del chat con MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,16 +124,16 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Crea la memoria con `withMaxMessages(10)` para conservar los últimos 10 mensajes. Añade mensajes de usuario e IA con los envoltorios tipados: `UserMessage.from(text)` y `AiMessage.from(text)`. Recupera el historial con `memory.messages()` y envíalo al modelo. El servicio almacena instancias de memoria separadas por ID de conversación, permitiendo que múltiples usuarios chateen simultáneamente. +Crea la memoria con `withMaxMessages(10)` para conservar los últimos 10 mensajes. Añade mensajes de usuario y AI con wrappers tipados: `UserMessage.from(text)` y `AiMessage.from(text)`. Recupera el historial con `memory.messages()` y envíalo al modelo. El servicio almacena instancias de memoria separadas por ID de conversación, permitiendo que múltiples usuarios chateen simultáneamente. > **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) y pregunta: -> - "¿Cómo decide MessageWindowChatMemory qué mensajes eliminar cuando la ventana está llena?" +> - "¿Cómo decide MessageWindowChatMemory qué mensajes descartar cuando la ventana está llena?" > - "¿Puedo implementar almacenamiento de memoria personalizado usando una base de datos en lugar de memoria en RAM?" -> - "¿Cómo agregaría una función de resumen para comprimir históricamente conversaciones antiguas?" +> - "¿Cómo añadiría resumen para comprimir el historial antiguo de la conversación?" -El endpoint de chat sin estado omite la memoria por completo - solo `chatModel.chat(prompt)` como en el inicio rápido. El endpoint con estado añade mensajes a la memoria, recupera el historial e incluye ese contexto con cada solicitud. Misma configuración del modelo, diferentes patrones. +El endpoint de chat sin estado omite la memoria por completo - sólo `chatModel.chat(prompt)` como en el inicio rápido. El endpoint con estado añade mensajes a la memoria, recupera el historial e incluye ese contexto en cada solicitud. Mismo modelo, diferentes patrones. -## Implementar Infraestructura Azure OpenAI +## Desplegar Infraestructura Azure OpenAI **Bash:** ```bash @@ -147,16 +147,16 @@ cd 01-introduction azd up # Seleccione la suscripción y la ubicación (se recomienda eastus2) ``` -> **Nota:** Si encuentras un error de tiempo de espera (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), simplemente ejecuta `azd up` nuevamente. Los recursos de Azure aún podrían estar aprovisionándose en segundo plano, y reintentar permite que la implementación se complete una vez que los recursos alcancen un estado final. +> **Nota:** Si encuentras un error de timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), simplemente ejecuta `azd up` nuevamente. Los recursos de Azure pueden estar todavía en provisión en segundo plano, y reintentar permite que el despliegue se complete una vez que los recursos alcanzan un estado terminal. Esto hará: -1. Desplegar el recurso Azure OpenAI con modelos GPT-5.2 y text-embedding-3-small -2. Generar automáticamente el archivo `.env` en la raíz del proyecto con credenciales -3. Configurar todas las variables de entorno requeridas +1. Desplegar el recurso Azure OpenAI con los modelos GPT-5.2 y text-embedding-3-small +2. Generar automáticamente el archivo `.env` en la raíz del proyecto con las credenciales +3. Configurar todas las variables de entorno necesarias -**¿Problemas con la implementación?** Consulta el [README de Infraestructura](infra/README.md) para resolver problemas detallados incluyendo conflictos de nombres de subdominios, pasos de implementación manual en Azure Portal y guías para configuración de modelos. +**¿Tienes problemas con el despliegue?** Revisa el [README de Infraestructura](infra/README.md) para resolución detallada de conflictos con nombres de subdominios, pasos manuales para despliegue en Azure Portal y guía de configuración de modelos. -**Verifica que la implementación haya sido exitosa:** +**Verifica que el despliegue haya sido exitoso:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, etc. Get-Content ..\.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, etc. ``` -> **Nota:** El comando `azd up` genera automáticamente el archivo `.env`. Si necesitas actualizarlo después, puedes editar el archivo manualmente o regenerarlo ejecutando: +> **Nota:** El comando `azd up` genera automáticamente el archivo `.env`. Si necesitas actualizarlo más tarde, puedes editar el archivo `.env` manualmente o regenerarlo ejecutando: > > **Bash:** > ```bash @@ -184,9 +184,9 @@ Get-Content ..\.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, etc. ## Ejecutar la Aplicación Localmente -**Verificar implementación:** +**Verifica el despliegue:** -Asegúrate que el archivo `.env` exista en el directorio raíz con las credenciales de Azure. Ejecuta esto desde el directorio del módulo (`01-introduction/`): +Asegúrate de que el archivo `.env` exista en el directorio raíz con las credenciales de Azure. Ejecuta esto desde el directorio del módulo (`01-introduction/`): **Bash:** ```bash @@ -198,25 +198,25 @@ cat ../.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Iniciar las aplicaciones:** +**Inicia las aplicaciones:** **Opción 1: Usando Spring Boot Dashboard (Recomendado para usuarios de VS Code)** -El contenedor de desarrollo incluye la extensión Spring Boot Dashboard, que ofrece una interfaz visual para gestionar todas las aplicaciones Spring Boot. Puedes encontrarla en la Barra de Actividades a la izquierda de VS Code (busca el ícono de Spring Boot). +El contenedor de desarrollo incluye la extensión Spring Boot Dashboard, que provee una interfaz visual para manejar todas las aplicaciones Spring Boot. Puedes encontrarlo en la Barra de Actividad al lado izquierdo de VS Code (busca el ícono de Spring Boot). -Desde el Spring Boot Dashboard, puedes: +Desde Spring Boot Dashboard puedes: - Ver todas las aplicaciones Spring Boot disponibles en el espacio de trabajo -- Iniciar/detener aplicaciones con un solo clic -- Ver los registros de la aplicación en tiempo real +- Iniciar/detener aplicaciones con un clic +- Ver logs de aplicación en tiempo real - Monitorear el estado de la aplicación -Simplemente haz clic en el botón de reproducir junto a "introduction" para iniciar este módulo o inicia todos los módulos a la vez. +Simplemente haz clic en el botón de play al lado de "introduction" para iniciar este módulo, o inicia todos los módulos a la vez. -Panel de Spring Boot +Panel de Control de Spring Boot *El Spring Boot Dashboard en VS Code — inicia, detén y monitorea todos los módulos desde un solo lugar* -**Opción 2: Usar scripts de shell** +**Opción 2: Usando scripts shell** Inicia todas las aplicaciones web (módulos 01-04): @@ -232,7 +232,7 @@ cd .. # Desde el directorio raíz .\start-all.ps1 ``` -O inicia solo este módulo: +O inicia sólo este módulo: **Bash:** ```bash @@ -246,7 +246,7 @@ cd 01-introduction .\start.ps1 ``` -Ambos scripts cargan automáticamente variables de entorno del archivo `.env` raíz y construirán los JARs si no existen. +Ambos scripts cargan automáticamente variables de entorno desde el archivo `.env` raíz y construirán los JARs si no existen. > **Nota:** Si prefieres construir todos los módulos manualmente antes de iniciar: > @@ -264,7 +264,7 @@ Ambos scripts cargan automáticamente variables de entorno del archivo `.env` ra Abre http://localhost:8080 en tu navegador. -**Para detener:** +**Para detener la aplicación:** **Bash:** ```bash @@ -286,25 +286,25 @@ La aplicación provee una interfaz web con dos implementaciones de chat lado a l Pantalla Principal de la Aplicación -*Panel mostrando opciones para Chat Simple (sin estado) y Chat Conversacional (con estado)* +*Panel que muestra opciones de Chat Simple (sin estado) y Chat Conversacional (con estado)* ### Chat Sin Estado (Panel Izquierdo) -Prueba primero aquí. Di "Me llamo Juan" y luego inmediatamente pregunta "¿Cómo me llamo?" El modelo no recordará porque cada mensaje es independiente. Esto demuestra el problema central con la integración básica de modelos de lenguaje - no hay contexto de conversación. +Prueba esto primero. Di "Mi nombre es John" y luego inmediatamente pregunta "¿Cuál es mi nombre?" El modelo no lo recordará porque cada mensaje es independiente. Esto demuestra el problema central con la integración básica de modelos de lenguaje - sin contexto de conversación. Demostración de Chat Sin Estado *La IA no recuerda tu nombre del mensaje anterior* -### Chat con Estado (Panel Derecho) +### Chat Con Estado (Panel Derecho) -Ahora prueba la misma secuencia aquí. Di "Me llamo Juan" y luego "¿Cómo me llamo?" Esta vez lo recuerda. La diferencia es MessageWindowChatMemory - mantiene el historial de la conversación e incluye ese contexto con cada solicitud. Así funciona la IA conversacional en producción. +Ahora intenta la misma secuencia aquí. Di "Mi nombre es John" y luego "¿Cuál es mi nombre?" Esta vez lo recuerda. La diferencia es MessageWindowChatMemory - mantiene el historial de la conversación e incluye ese contexto en cada solicitud. Así funciona la IA conversacional en producción. -Demostración de Chat con Estado +Demostración de Chat Con Estado -*La IA recuerda tu nombre desde el inicio de la conversación* +*La IA recuerda tu nombre de la conversación anterior* -Ambos paneles usan el mismo modelo GPT-5.2. La única diferencia es la memoria. Esto deja claro qué aporta la memoria a tu aplicación y por qué es esencial para casos reales. +Ambos paneles usan el mismo modelo GPT-5.2. La única diferencia es la memoria. Esto hace claro qué aporta la memoria a tu aplicación y por qué es esencial para casos de uso reales. ## Próximos Pasos @@ -312,11 +312,11 @@ Ambos paneles usan el mismo modelo GPT-5.2. La única diferencia es la memoria. --- -**Navegación:** [← Anterior: Módulo 00 - Inicio Rápido](../00-quick-start/README.md) | [Volver al Inicio](../README.md) | [Siguiente: Módulo 02 - Ingeniería de Prompts →](../02-prompt-engineering/README.md) +**Navegación:** [← Volver al Principal](../README.md) | [Siguiente: Módulo 02 - Ingeniería de Prompts →](../02-prompt-engineering/README.md) --- -**Descargo de responsabilidad**: -Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por lograr precisión, tenga en cuenta que las traducciones automáticas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional realizada por un humano. No nos hacemos responsables de malentendidos o interpretaciones erróneas derivadas del uso de esta traducción. +**Descargo de responsabilidad**: +Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción. \ No newline at end of file diff --git a/translations/es/02-prompt-engineering/README.md b/translations/es/02-prompt-engineering/README.md index 15e396900..1b4a39b89 100644 --- a/translations/es/02-prompt-engineering/README.md +++ b/translations/es/02-prompt-engineering/README.md @@ -2,29 +2,29 @@ ## Tabla de Contenidos -- [Recorrido en Video](../../../02-prompt-engineering) -- [Qué Aprenderás](../../../02-prompt-engineering) -- [Prerequisitos](../../../02-prompt-engineering) -- [Comprendiendo la Ingeniería de Prompts](../../../02-prompt-engineering) -- [Fundamentos de la Ingeniería de Prompts](../../../02-prompt-engineering) - - [Prompting Zero-Shot](../../../02-prompt-engineering) - - [Prompting Few-Shot](../../../02-prompt-engineering) - - [Cadena de Pensamiento](../../../02-prompt-engineering) - - [Prompting Basado en Roles](../../../02-prompt-engineering) - - [Plantillas de Prompts](../../../02-prompt-engineering) -- [Patrones Avanzados](../../../02-prompt-engineering) -- [Ejecutar la Aplicación](../../../02-prompt-engineering) -- [Capturas de Pantalla de la Aplicación](../../../02-prompt-engineering) -- [Explorando los Patrones](../../../02-prompt-engineering) - - [Baja vs Alta Entusiasmo](../../../02-prompt-engineering) - - [Ejecución de Tareas (Preambulos de Herramientas)](../../../02-prompt-engineering) - - [Código Auto-Reflexivo](../../../02-prompt-engineering) - - [Análisis Estructurado](../../../02-prompt-engineering) - - [Chat de Múltiples Turnos](../../../02-prompt-engineering) - - [Razonamiento Paso a Paso](../../../02-prompt-engineering) - - [Salida Restringida](../../../02-prompt-engineering) -- [Qué Estás Realmente Aprendiendo](../../../02-prompt-engineering) -- [Próximos Pasos](../../../02-prompt-engineering) +- [Recorrido en Video](#recorrido-en-video) +- [Lo Que Aprenderás](#lo-que-aprenderás) +- [Prerequisitos](#prerequisitos) +- [Comprendiendo la Ingeniería de Prompts](#comprendiendo-la-ingeniería-de-prompts) +- [Fundamentos de la Ingeniería de Prompts](#fundamentos-de-la-ingeniería-de-prompts) + - [Prompting Zero-Shot](#prompting-zero-shot) + - [Prompting Few-Shot](#prompting-few-shot) + - [Cadena de Pensamiento](#cadena-de-pensamiento) + - [Prompting Basado en Roles](#prompting-basado-en-roles) + - [Plantillas de Prompts](#plantillas-de-prompts) +- [Patrones Avanzados](#patrones-avanzados) +- [Ejecutar la Aplicación](#ejecutar-la-aplicación) +- [Capturas de Pantalla de la Aplicación](#capturas-de-pantalla-de-la-aplicación) +- [Explorando los Patrones](#explorando-los-patrones) + - [Baja vs Alta Entusiasmo](#baja-vs-alta-dedicación) + - [Ejecución de Tareas (Preámbulos de Herramientas)](#ejecución-de-tareas-preámbulos-de-herramientas) + - [Código Autorreflexivo](#código-auto-reflexivo) + - [Análisis Estructurado](#análisis-estructurado) + - [Chat Multivuelta](#chat-multinivel) + - [Razonamiento Paso a Paso](#razonamiento-paso-a-paso) + - [Salida Restringida](#salida-restringida) +- [Lo que Realmente Estás Aprendiendo](#lo-que-realmente-estás-aprendiendo) +- [Próximos Pasos](#próximos-pasos) ## Recorrido en Video @@ -32,54 +32,54 @@ Mira esta sesión en vivo que explica cómo comenzar con este módulo: Ingeniería de Prompts con LangChain4j - Sesión en Vivo -## Qué Aprenderás +## Lo Que Aprenderás -El siguiente diagrama ofrece una visión general de los temas clave y habilidades que desarrollarás en este módulo — desde técnicas de refinamiento de prompts hasta el flujo de trabajo paso a paso que seguirás. +El siguiente diagrama ofrece una vista general de los temas y habilidades clave que desarrollarás en este módulo, desde técnicas de refinamiento de prompts hasta el flujo de trabajo paso a paso que seguirás. -Qué Aprenderás +Lo Que Aprenderás -En los módulos anteriores, exploraste interacciones básicas de LangChain4j con modelos de GitHub y viste cómo la memoria habilita la IA conversacional con Azure OpenAI. Ahora nos enfocaremos en cómo haces preguntas — los prompts en sí — usando GPT-5.2 de Azure OpenAI. La manera en que estructuras tus prompts afecta dramáticamente la calidad de las respuestas que obtienes. Comenzamos con una revisión de las técnicas fundamentales de prompting, luego avanzamos a ocho patrones avanzados que aprovechan al máximo las capacidades de GPT-5.2. +En el módulo anterior viste cómo la memoria habilita IA conversacional con Azure OpenAI. Ahora nos centraremos en cómo haces preguntas — los propios prompts — usando GPT-5.2 de Azure OpenAI. La forma en que estructuras tus prompts afecta drásticamente la calidad de las respuestas que obtienes. Comenzamos revisando las técnicas fundamentales de prompting, luego pasamos a ocho patrones avanzados que aprovechan al máximo las capacidades de GPT-5.2. -Usaremos GPT-5.2 porque introduce control de razonamiento: puedes indicarle al modelo cuánto debe pensar antes de responder. Esto hace que las diferentes estrategias de prompting sean más evidentes y te ayuda a entender cuándo usar cada enfoque. También nos beneficiaremos de los menores límites de tasa de Azure para GPT-5.2 comparado con los modelos GitHub. +Usaremos GPT-5.2 porque introduce control del razonamiento - puedes indicarle al modelo cuánto pensamiento hacer antes de responder. Esto hace que diferentes estrategias de prompting sean más evidentes y te ayuda a entender cuándo usar cada enfoque. ## Prerequisitos - Haber completado el Módulo 01 (recursos de Azure OpenAI desplegados) - Archivo `.env` en el directorio raíz con credenciales de Azure (creado por `azd up` en el Módulo 01) -> **Nota:** Si no has completado el Módulo 01, sigue primero las instrucciones de despliegue allí. +> **Nota:** Si no has completado el Módulo 01, sigue las instrucciones de despliegue ahí primero. ## Comprendiendo la Ingeniería de Prompts -En su esencia, la ingeniería de prompts es la diferencia entre instrucciones vagas e instrucciones precisas, como ilustra la comparación abajo. +En su esencia, la ingeniería de prompts es la diferencia entre instrucciones vagas y precisas, como ilustra la comparación siguiente. ¿Qué es la Ingeniería de Prompts? -La ingeniería de prompts trata sobre diseñar texto de entrada que consistentemente te da los resultados que necesitas. No es solo hacer preguntas, es estructurar las solicitudes para que el modelo entienda exactamente qué quieres y cómo entregarlo. +La ingeniería de prompts se trata de diseñar texto de entrada que consistentemente te dé los resultados que necesitas. No es solo hacer preguntas, sino estructurar solicitudes para que el modelo entienda exactamente qué quieres y cómo entregarlo. -Piénsalo como dar instrucciones a un colega. "Arregla el bug" es vago. "Arregla la excepción de puntero nulo en UserService.java línea 45 añadiendo una comprobación de nulo" es específico. Los modelos de lenguaje funcionan igual: la especificidad y estructura importan. +Piénsalo como dar instrucciones a un colega. "Arregla el bug" es vago. "Arregla la excepción de puntero nulo en UserService.java línea 45 añadiendo una comprobación de nulos" es específico. Los modelos de lenguaje funcionan igual — la especificidad y estructura importan. -El diagrama de abajo muestra cómo LangChain4j encaja en este panorama — conectando tus patrones de prompt con el modelo a través de bloques constructores `SystemMessage` y `UserMessage`. +El diagrama de abajo muestra cómo LangChain4j encaja en esta imagen — conectando tus patrones de prompt con el modelo mediante los bloques constructores SystemMessage y UserMessage. -Cómo encaja LangChain4j +Cómo Encaja LangChain4j -LangChain4j provee la infraestructura — conexiones al modelo, memoria y tipos de mensaje — mientras que los patrones de prompt son solo texto cuidadosamente estructurado que envías a través de esa infraestructura. Los bloques clave son `SystemMessage` (que establece el comportamiento y rol de la IA) y `UserMessage` (que lleva tu petición real). +LangChain4j provee la infraestructura — conexiones al modelo, memoria y tipos de mensajes — mientras que los patrones de prompt son solo texto cuidadosamente estructurado que envías a través de esa infraestructura. Los bloques clave son `SystemMessage` (que establece el comportamiento y rol de la IA) y `UserMessage` (que lleva tu solicitud real). ## Fundamentos de la Ingeniería de Prompts -Las cinco técnicas principales que se muestran a continuación forman la base de una ingeniería de prompts efectiva. Cada una aborda un aspecto diferente de cómo te comunicas con modelos de lenguaje. +Las cinco técnicas centrales que se muestran a continuación forman la base de una ingeniería de prompts efectiva. Cada una aborda un aspecto diferente de cómo te comunicas con modelos de lenguaje. -Resumen de Cinco Patrones de Ingeniería de Prompts +Visión General de Cinco Patrones de Ingeniería de Prompts -Antes de sumergirnos en los patrones avanzados de este módulo, revisemos cinco técnicas fundamentales de prompting. Estos son los bloques básicos que todo ingeniero de prompts debe conocer. Si ya trabajaste con el [módulo de inicio rápido](../00-quick-start/README.md#2-prompt-patterns), los has visto en acción — aquí está el marco conceptual detrás de ellos. +Antes de profundizar en los patrones avanzados de este módulo, repasemos cinco técnicas básicas de prompting. Estos son los bloques constructores que todo ingeniero de prompts debe conocer. ### Prompting Zero-Shot -El enfoque más simple: darle al modelo una instrucción directa sin ejemplos. El modelo se basa totalmente en su entrenamiento para entender y ejecutar la tarea. Funciona bien para solicitudes directas donde el comportamiento esperado es obvio. +El enfoque más simple: darle al modelo una instrucción directa sin ejemplos. El modelo se basa completamente en su entrenamiento para entender y ejecutar la tarea. Esto funciona bien para solicitudes directas donde el comportamiento esperado es obvio. Prompting Zero-Shot -*Instrucción directa sin ejemplos — el modelo infiere la tarea solo a partir de la instrucción* +*Instrucción directa sin ejemplos — el modelo infiere la tarea solo con la instrucción* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Respuesta: "Positivo" ``` -**Cuándo usarlo:** Clasificaciones simples, preguntas directas, traducciones o cualquier tarea que el modelo pueda manejar sin orientación adicional. +**Cuándo usarlo:** Clasificaciones simples, preguntas directas, traducciones o cualquier tarea que el modelo pueda manejar sin guía adicional. ### Prompting Few-Shot -Proporciona ejemplos que demuestran el patrón que quieres que el modelo siga. El modelo aprende el formato input-output esperado de tus ejemplos y lo aplica a nuevas entradas. Esto mejora drásticamente la consistencia para tareas donde el formato o comportamiento deseado no es obvio. +Proporciona ejemplos que demuestren el patrón que quieres que el modelo siga. El modelo aprende el formato esperado de entrada-salida a partir de tus ejemplos y lo aplica a nuevas entradas. Esto mejora dramáticamente la consistencia para tareas donde el formato o comportamiento deseado no es obvio. Prompting Few-Shot -*Aprender de ejemplos — el modelo identifica el patrón y lo aplica a nuevos inputs* +*Aprender de ejemplos — el modelo identifica el patrón y lo aplica a nuevas entradas* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Cuándo usarlo:** Clasificaciones personalizadas, formato consistente, tareas específicas de dominio o cuando los resultados zero-shot son inconsistentes. +**Cuándo usarlo:** Clasificaciones personalizadas, formateo consistente, tareas específicas de dominio o cuando los resultados zero-shot son inconsistentes. ### Cadena de Pensamiento -Pídele al modelo que muestre su razonamiento paso a paso. En lugar de saltar directo a una respuesta, el modelo descompone el problema y trabaja cada parte explícitamente. Esto mejora la precisión en matemáticas, lógica y tareas de razonamiento en múltiples pasos. +Pide al modelo que muestre su razonamiento paso a paso. En lugar de saltar directamente a una respuesta, el modelo descompone el problema y trabaja cada parte explícitamente. Esto mejora la precisión en matemáticas, lógica y razonamiento multi-paso. -Cadena de Pensamiento +Prompting Cadena de Pensamiento -*Razonamiento paso a paso — desglosar problemas complejos en pasos lógicos explícitos* +*Razonamiento paso a paso — descomponiendo problemas complejos en pasos lógicos explícitos* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // El modelo muestra: 15 - 8 = 7, luego 7 + 12 = 19 manzanas ``` -**Cuándo usarlo:** Problemas matemáticos, acertijos lógicos, depuración o cualquier tarea donde mostrar el proceso de razonamiento mejora precisión y confianza. +**Cuándo usarlo:** Problemas matemáticos, acertijos lógicos, depuración o cualquier tarea donde mostrar el proceso de razonamiento improve la precisión y confianza. ### Prompting Basado en Roles -Establece una persona o rol para la IA antes de hacer tu pregunta. Esto proporciona contexto que moldea el tono, profundidad y enfoque de la respuesta. Un “arquitecto de software” da consejos diferentes a un “desarrollador junior” o un “auditor de seguridad”. +Define una persona o rol para la IA antes de hacer la pregunta. Esto provee contexto que moldea el tono, profundidad y foco de la respuesta. Un "arquitecto de software" ofrece consejos diferentes a un "desarrollador junior" o un "auditor de seguridad". Prompting Basado en Roles -*Establecer contexto y persona — la misma pregunta recibe respuestas diferentes según el rol asignado* +*Estableciendo contexto y persona — la misma pregunta recibe respuestas diferentes según el rol asignado* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Cuándo usarlo:** Revisiones de código, tutorías, análisis específicos de dominio o cuando necesitas respuestas adaptadas a un nivel o perspectiva expertas. +**Cuándo usarlo:** Revisiones de código, tutoría, análisis específico de dominio o cuando necesitas respuestas adaptadas a un nivel de experiencia o perspectiva particular. ### Plantillas de Prompts -Crea prompts reutilizables con marcadores de posición variables. En lugar de escribir un prompt nuevo cada vez, defines una plantilla una vez y rellenas con diferentes valores. La clase `PromptTemplate` de LangChain4j facilita esto con la sintaxis `{{variable}}`. +Crea prompts reutilizables con espacios variables. En lugar de escribir un prompt nuevo cada vez, define una plantilla una vez y llena valores diferentes. La clase `PromptTemplate` de LangChain4j facilita esto con la sintaxis `{{variable}}`. Plantillas de Prompts -*Prompts reutilizables con marcadores variables — una plantilla, muchos usos* +*Prompts reutilizables con espacios variables — una plantilla, muchos usos* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Cuándo usarlo:** Consultas repetidas con diferentes inputs, procesamiento por lotes, creación de flujos de trabajo AI reutilizables o cualquier escenario donde la estructura del prompt permanece pero los datos cambian. +**Cuándo usarlo:** Consultas repetidas con diferentes entradas, procesamiento por lotes, construcción de flujos de trabajo AI reutilizables o cualquier escenario donde la estructura del prompt es la misma pero cambian los datos. --- -Estos cinco fundamentos te dan un conjunto sólido para la mayoría de tareas de prompting. El resto de este módulo se basa en ellos con **ocho patrones avanzados** que aprovechan el control de razonamiento, autoevaluación y capacidades de salida estructurada de GPT-5.2. +Estos cinco fundamentos te brindan un conjunto sólido de herramientas para la mayoría de las tareas de prompting. El resto de este módulo se basa en ellos con **ocho patrones avanzados** que aprovechan el control de razonamiento, autoevaluación y la capacidad de salida estructurada de GPT-5.2. ## Patrones Avanzados -Con los fundamentos cubiertos, vamos a los ocho patrones avanzados que hacen único este módulo. No todos los problemas necesitan el mismo enfoque. Algunas preguntas requieren respuestas rápidas, otras pensamiento profundo. Algunas necesitan razonamiento visible, otras solo resultados. Cada patrón abajo está optimizado para un escenario diferente — y el control de razonamiento de GPT-5.2 hace que las diferencias sean aún más notorias. +Con los fundamentos cubiertos, pasemos a los ocho patrones avanzados que hacen único este módulo. No todos los problemas requieren el mismo enfoque. Algunas preguntas necesitan respuestas rápidas, otras pensamiento profundo. Algunas requieren razonamiento visible, otras solo resultados. Cada patrón abajo está optimizado para un escenario diferente — y el control del razonamiento de GPT-5.2 hace que las diferencias sean aún más pronunciadas. Ocho Patrones de Prompting -*Resumen de los ocho patrones de ingeniería de prompts y sus casos de uso* +*Visión general de los ocho patrones de ingeniería de prompts y sus casos de uso* -GPT-5.2 añade otra dimensión a estos patrones: *control de razonamiento*. El deslizador abajo muestra cómo puedes ajustar el esfuerzo de pensar del modelo — desde respuestas rápidas y directas hasta análisis profundos y exhaustivos. +GPT-5.2 añade otra dimensión a estos patrones: *control de razonamiento*. El control deslizante abajo muestra cómo puedes ajustar el esfuerzo de pensamiento del modelo — desde respuestas rápidas y directas hasta análisis profundo y exhaustivo. Control de Razonamiento con GPT-5.2 -*El control de razonamiento de GPT-5.2 te permite especificar cuánto debe pensar el modelo — desde respuestas rápidas hasta exploración profunda* +*El control de razonamiento de GPT-5.2 te permite especificar cuánto debe pensar el modelo — desde respuestas rápidas directas hasta exploración profunda* -**Bajo Entusiasmo (Rápido y Enfocado)** - Para preguntas simples donde quieres respuestas rápidas y directas. El modelo realiza razonamiento mínimo - máximo 2 pasos. Úsalo para cálculos, consultas o preguntas directas. +**Bajo Entusiasmo (Rápido y Enfocado)** - Para preguntas simples donde quieres respuestas rápidas y directas. El modelo hace razonamiento mínimo - máximo 2 pasos. Úsalo para cálculos, consultas o preguntas directas. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Explora con GitHub Copilot:** Abre [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) y pregunta: -> - "¿Cuál es la diferencia entre patrones de prompting de bajo entusiasmo y alto entusiasmo?" +> - "¿Cuál es la diferencia entre los patrones de prompting de bajo entusiasmo y alto entusiasmo?" > - "¿Cómo ayudan las etiquetas XML en los prompts a estructurar la respuesta de la IA?" -> - "¿Cuándo debo usar patrones de autorreflexión vs instrucciones directas?" +> - "¿Cuándo debería usar patrones de autorreflexión vs instrucción directa?" -**Alto Entusiasmo (Profundo y Minucioso)** - Para problemas complejos donde quieres análisis exhaustivo. El modelo explora a fondo y muestra razonamiento detallado. Úsalo para diseño de sistemas, decisiones arquitectónicas o investigación compleja. +**Alto Entusiasmo (Profundo y Exhaustivo)** - Para problemas complejos donde quieres un análisis completo. El modelo explora a fondo y muestra un razonamiento detallado. Úsalo para diseño de sistemas, decisiones arquitectónicas o investigación compleja. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Ejecución de Tareas (Progreso Paso a Paso)** - Para flujos de trabajo en múltiples pasos. El modelo proporciona un plan inicial, narra cada paso mientras trabaja, luego da un resumen. Úsalo para migraciones, implementaciones o cualquier proceso de varios pasos. +**Ejecución de Tareas (Progreso Paso a Paso)** - Para flujos de trabajo multi-paso. El modelo provee un plan adelantado, narra cada paso conforme avanza y luego da un resumen. Úsalo para migraciones, implementaciones o cualquier proceso multi-paso. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -El prompting de Cadena de Pensamiento le pide explícitamente al modelo que muestre su proceso de razonamiento, mejorando la precisión en tareas complejas. El desglose paso a paso ayuda tanto a humanos como a la IA a entender la lógica. +El prompting Cadena de Pensamiento explícitamente pide al modelo mostrar su proceso de razonamiento, mejorando la precisión para tareas complejas. La descomposición paso a paso ayuda tanto a humanos como a la IA a entender la lógica. > **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Pregunta sobre este patrón: > - "¿Cómo adaptaría el patrón de ejecución de tareas para operaciones de larga duración?" -> - "¿Cuáles son las mejores prácticas para estructurar preámbulos de herramientas en aplicaciones de producción?" -> - "¿Cómo puedo capturar y mostrar actualizaciones de progreso intermedias en una UI?" +> - "¿Cuáles son las mejores prácticas para estructurar los preámbulos de herramientas en aplicaciones de producción?" +> - "¿Cómo puedo capturar y mostrar actualizaciones de progreso intermedias en una interfaz de usuario?" El diagrama abajo ilustra este flujo Planificar → Ejecutar → Resumir. Patrón de Ejecución de Tareas -*Flujo Planificar → Ejecutar → Resumir para tareas en múltiples pasos* +*Flujo Planificar → Ejecutar → Resumir para tareas multi-paso* -**Código Auto-Reflexivo** - Para generar código de calidad producción. El modelo genera código siguiendo estándares de producción con manejo adecuado de errores. Úsalo al construir nuevas funciones o servicios. +**Código Autorreflexivo** - Para generar código con calidad de producción. El modelo genera código siguiendo estándares de producción con manejo adecuado de errores. Úsalo cuando construyas nuevas funcionalidades o servicios. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -El diagrama abajo muestra este ciclo iterativo de mejora — generar, evaluar, identificar debilidades y refinar hasta que el código cumpla estándares de producción. +El diagrama a continuación muestra este ciclo iterativo de mejora — generar, evaluar, identificar debilidades y refinar hasta que el código cumpla estándares de producción. -Ciclo de Auto-Reflexión +Ciclo de Autorreflexión *Ciclo iterativo de mejora - generar, evaluar, identificar problemas, mejorar, repetir* -**Análisis Estructurado** - Para evaluación consistente. El modelo revisa código usando un marco fijo (corrección, prácticas, rendimiento, seguridad, mantenibilidad). Úsalo para revisiones de código o evaluaciones de calidad. +**Análisis Estructurado** - Para evaluaciones consistentes. El modelo revisa código usando un marco fijo (corrección, prácticas, rendimiento, seguridad, mantenibilidad). Úsalo para revisiones de código o evaluaciones de calidad. ```java String prompt = """ @@ -356,8 +356,8 @@ String response = chatModel.chat(prompt); > **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Pregunta sobre análisis estructurado: > - "¿Cómo puedo personalizar el marco de análisis para diferentes tipos de revisiones de código?" -> - "¿Cuál es la mejor manera de analizar y actuar sobre salidas estructuradas programáticamente?" -> - "¿Cómo aseguro niveles de severidad consistentes entre diferentes sesiones de revisión?" +> - "¿Cuál es la mejor forma de parsear y actuar programáticamente sobre salidas estructuradas?" +> - "¿Cómo garantizo niveles de severidad consistentes en diferentes sesiones de revisión?" El siguiente diagrama muestra cómo este marco estructurado organiza una revisión de código en categorías consistentes con niveles de severidad. @@ -365,7 +365,7 @@ El siguiente diagrama muestra cómo este marco estructurado organiza una revisi *Marco para revisiones de código consistentes con niveles de severidad* -**Chat de Múltiples Turnos** - Para conversaciones que necesitan contexto. El modelo recuerda mensajes previos y construye sobre ellos. Úsalo para sesiones de ayuda interactivas o preguntas y respuestas complejas. +**Chat Multivuelta** - Para conversaciones que necesitan contexto. El modelo recuerda mensajes previos y construye sobre ellos. Úsalo para sesiones interactivas de ayuda o Q&A complejos. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -El diagrama siguiente visualiza cómo el contexto de la conversación se acumula con cada turno y cómo se relaciona con el límite de tokens del modelo. +El diagrama abajo visualiza cómo el contexto de la conversación se acumula con cada turno y cómo se relaciona con el límite de tokens del modelo. Memoria de Contexto -*Cómo el contexto de la conversación se acumula durante múltiples turnos hasta alcanzar el límite de tokens* -**Razonamiento Paso a Paso** - Para problemas que requieren lógica visible. El modelo muestra un razonamiento explícito para cada paso. Usa esto para problemas matemáticos, acertijos lógicos o cuando necesitas entender el proceso de pensamiento. +*Cómo el contexto conversacional se acumula a través de múltiples turnos hasta alcanzar el límite de tokens* + +**Razonamiento Paso a Paso** - Para problemas que requieren lógica visible. El modelo muestra razonamiento explícito para cada paso. Úsalo para problemas matemáticos, acertijos lógicos o cuando necesitas entender el proceso de pensamiento. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -El diagrama a continuación ilustra cómo el modelo descompone los problemas en pasos lógicos numerados y explícitos. +El diagrama a continuación ilustra cómo el modelo descompone problemas en pasos lógicos explícitos y numerados. Patrón Paso a Paso +*Dividiendo problemas en pasos lógicos explícitos* -*Desglosando problemas en pasos lógicos explícitos* - -**Salida Restringida** - Para respuestas con requisitos específicos de formato. El modelo sigue estrictamente las reglas de formato y longitud. Usa esto para resúmenes o cuando necesitas una estructura de salida precisa. +**Salida Restringida** - Para respuestas con requisitos específicos de formato. El modelo sigue estrictamente las reglas de formato y longitud. Úsalo para resúmenes o cuando necesites una estructura de salida precisa. ```java String prompt = """ @@ -420,13 +420,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -El siguiente diagrama muestra cómo las restricciones guían al modelo para producir una salida que cumple estrictamente con tus requisitos de formato y longitud. +El siguiente diagrama muestra cómo las restricciones guían al modelo para producir una salida que se adhiera estrictamente a tus requisitos de formato y longitud. -Patrón de Salida Restringida +Patrón de salida restringida -*Imponiendo requisitos específicos de formato, longitud y estructura* +*Aplicando requisitos específicos de formato, longitud y estructura* -## Ejecutar la Aplicación +## Ejecutar la aplicación **Verificar despliegue:** @@ -434,7 +434,7 @@ Asegúrate de que el archivo `.env` exista en el directorio raíz con las creden **Bash:** ```bash -cat ../.env # Debería mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -444,13 +444,13 @@ Get-Content ..\.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Iniciar la aplicación:** -> **Nota:** Si ya iniciaste todas las aplicaciones usando `./start-all.sh` desde el directorio raíz (como se describe en el Módulo 01), este módulo ya está corriendo en el puerto 8083. Puedes omitir los comandos de inicio a continuación y acceder directamente a http://localhost:8083. +> **Nota:** Si ya iniciaste todas las aplicaciones usando `./start-all.sh` desde el directorio raíz (como se describió en el Módulo 01), este módulo ya está ejecutándose en el puerto 8083. Puedes omitir los comandos de inicio a continuación e ir directamente a http://localhost:8083. **Opción 1: Usando Spring Boot Dashboard (Recomendado para usuarios de VS Code)** -El contenedor de desarrollo incluye la extensión Spring Boot Dashboard, que proporciona una interfaz visual para gestionar todas las aplicaciones Spring Boot. Puedes encontrarla en la Barra de Actividad a la izquierda en VS Code (busca el ícono de Spring Boot). +El contenedor de desarrollo incluye la extensión Spring Boot Dashboard, que ofrece una interfaz visual para administrar todas las aplicaciones Spring Boot. Puedes encontrarla en la Barra de Actividad al lado izquierdo de VS Code (busca el ícono de Spring Boot). -Desde el Spring Boot Dashboard puedes: +Desde Spring Boot Dashboard, puedes: - Ver todas las aplicaciones Spring Boot disponibles en el espacio de trabajo - Iniciar/detener aplicaciones con un solo clic - Ver los registros de la aplicación en tiempo real @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Ambos scripts cargan automáticamente las variables de entorno desde el archivo `.env` raíz y construirán los JARs si no existen. +Ambos scripts cargan automáticamente las variables de entorno del archivo `.env` raíz y construirán los JAR si no existen. -> **Nota:** Si prefieres compilar todos los módulos manualmente antes de iniciar: +> **Nota:** Si prefieres construir todos los módulos manualmente antes de iniciar: > > **Bash:** > ```bash @@ -526,83 +526,83 @@ cd .. && ./stop-all.sh # Todos los módulos cd ..; .\stop-all.ps1 # Todos los módulos ``` -## Capturas de Pantalla de la Aplicación +## Capturas de pantalla de la aplicación Aquí está la interfaz principal del módulo de ingeniería de prompts, donde puedes experimentar con los ocho patrones uno al lado del otro. -Pantalla principal del Dashboard +Pantalla principal del panel -*El panel principal muestra los 8 patrones de ingeniería de prompts con sus características y casos de uso* +*El panel principal mostrando los 8 patrones de ingeniería de prompts con sus características y casos de uso* -## Explorando los Patrones +## Explorando los patrones -La interfaz web te permite experimentar con diferentes estrategias de prompting. Cada patrón resuelve diferentes problemas - pruébalos para ver cuándo brilla cada enfoque. +La interfaz web te permite experimentar con diferentes estrategias de prompting. Cada patrón resuelve problemas diferentes; pruébalos para ver cuándo destaca cada enfoque. -> **Nota: Streaming vs No Streaming** — Cada página de patrón ofrece dos botones: **🔴 Stream Response (Live)** y una opción **No streaming**. Streaming usa Eventos Enviados por el Servidor (SSE) para mostrar los tokens en tiempo real conforme el modelo los genera, por lo que ves el progreso inmediatamente. La opción no streaming espera toda la respuesta antes de mostrarla. Para prompts que desencadenan razonamientos profundos (por ejemplo, Alta Disposición, Código Auto-Reflexivo), la llamada no streaming puede tardar mucho — a veces minutos — sin retroalimentación visible. **Usa streaming cuando experimentes con prompts complejos** para que puedas ver el modelo trabajando y evitar la impresión de que la solicitud ha expirado. +> **Nota: Transmisión vs No transmisión** — Cada página de patrón ofrece dos botones: **🔴 Transmitir respuesta (en vivo)** y una opción **No transmisión**. La transmisión utiliza Server-Sent Events (SSE) para mostrar tokens en tiempo real mientras el modelo los genera, así ves el progreso de inmediato. La opción no transmisión espera a que la respuesta completa esté lista para mostrarla. Para prompts que desencadenan razonamientos profundos (ej., Alta Dedicación, Código Auto-Reflexivo), la llamada no transmisión puede tardar mucho tiempo — a veces minutos — sin retroalimentación visible. **Usa la transmisión al experimentar con prompts complejos** para ver cómo trabaja el modelo y evitar la impresión de que la solicitud falló. > -> **Nota: Requisito del Navegador** — La función streaming usa la API Fetch Streams (`response.body.getReader()`) que requiere un navegador completo (Chrome, Edge, Firefox, Safari). No funciona en el Navegador Simple incorporado de VS Code, ya que su vista web no soporta la API ReadableStream. Si usas el Navegador Simple, los botones no streaming funcionarán normalmente — solo los botones streaming se ven afectados. Abre `http://localhost:8083` en un navegador externo para una experiencia completa. +> **Nota: Requisito de navegador** — La función de transmisión usa Fetch Streams API (`response.body.getReader()`) que requiere un navegador completo (Chrome, Edge, Firefox, Safari). **No** funciona en el Navegador Simple incorporado de VS Code, ya que su vista web no soporta la API ReadableStream. Si usas el Navegador Simple, los botones de no transmisión seguirán funcionando con normalidad; solo los botones de transmisión se ven afectados. Abre `http://localhost:8083` en un navegador externo para la experiencia completa. -### Baja vs Alta Disposición +### Baja vs Alta Dedicación -Haz una pregunta simple como "¿Cuál es el 15% de 200?" usando Baja Disposición. Obtendrás una respuesta directa e instantánea. Ahora haz algo complejo como "Diseña una estrategia de caché para una API con alto tráfico" usando Alta Disposición. Haz clic en **🔴 Stream Response (Live)** y observa el razonamiento detallado del modelo aparecer token por token. Mismo modelo, misma estructura de pregunta - pero el prompt le indica cuánto debe pensar. +Haz una pregunta sencilla como "¿Cuál es el 15% de 200?" usando Baja Dedicación. Obtendrás una respuesta directa e instantánea. Ahora pregunta algo complejo como "Diseña una estrategia de caché para una API de alto tráfico" con Alta Dedicación. Haz clic en **🔴 Transmitir respuesta (en vivo)** y observa cómo el modelo va mostrando su razonamiento detallado token por token. Mismo modelo, misma estructura de pregunta, pero el prompt le indica cuánto debe pensar. -### Ejecución de Tareas (Preámbulos de Herramientas) +### Ejecución de tareas (Preámbulos de herramientas) -Los flujos de trabajo con múltiples pasos se benefician de una planificación previa y narración del progreso. El modelo describe lo que hará, narra cada paso y luego resume los resultados. +Los flujos de trabajo multi-paso se benefician de una planificación previa y narración del progreso. El modelo describe qué hará, narra cada paso y luego resume los resultados. -### Código Auto-Reflectivo +### Código Auto-Reflexivo -Prueba con "Crear un servicio de validación de email". En lugar de solo generar código y detenerse, el modelo genera, evalúa contra criterios de calidad, identifica debilidades y mejora. Verás que itera hasta que el código cumple los estándares de producción. +Prueba "Crear un servicio de validación de email". En lugar de solo generar código y detenerse, el modelo genera, evalúa contra criterios de calidad, identifica debilidades y mejora. Verás cómo itera hasta que el código cumple con los estándares de producción. -### Análisis Estructurado +### Análisis estructurado -Las revisiones de código necesitan marcos de evaluación consistentes. El modelo analiza código usando categorías fijas (correctitud, prácticas, rendimiento, seguridad) con niveles de severidad. +Las revisiones de código necesitan marcos de evaluación consistentes. El modelo analiza el código usando categorías fijas (corrección, prácticas, rendimiento, seguridad) con niveles de severidad. -### Chat Multiturno +### Chat multinivel -Pregunta "¿Qué es Spring Boot?" luego inmediatamente sigue con "Muéstrame un ejemplo". El modelo recuerda tu primera pregunta y te da un ejemplo específico de Spring Boot. Sin memoria, esa segunda pregunta sería demasiado vaga. +Pregunta "¿Qué es Spring Boot?" y luego continúa inmediatamente con "Muéstrame un ejemplo". El modelo recuerda tu primera pregunta y te da un ejemplo específico de Spring Boot. Sin memoria, la segunda pregunta sería demasiado vaga. -### Razonamiento Paso a Paso +### Razonamiento paso a paso -Elige un problema matemático y pruébalo con Razonamiento Paso a Paso y Baja Disposición. La baja disposición solo te da la respuesta - rápido pero opaco. Paso a paso te muestra cada cálculo y decisión. +Elige un problema matemático y pruébalo con Razonamiento paso a paso y con Baja Dedicación. Baja dedicación solo te da la respuesta — rápido pero opaco. Paso a paso te muestra cada cálculo y decisión. -### Salida Restringida +### Salida restringida -Cuando necesitas formatos específicos o conteos exactos de palabras, este patrón fuerza estricto cumplimiento. Prueba generando un resumen con exactamente 100 palabras en formato de viñetas. +Cuando necesitas formatos o conteos de palabras específicos, este patrón impone una estricta adherencia. Prueba generando un resumen con exactamente 100 palabras en formato de lista. -## Lo que Realmente Estás Aprendiendo +## Lo que realmente estás aprendiendo -**El Esfuerzo de Razonamiento Cambia Todo** +**El esfuerzo de razonamiento lo cambia todo** -GPT-5.2 te permite controlar el esfuerzo computacional mediante tus prompts. Bajo esfuerzo significa respuestas rápidas con exploración mínima. Alto esfuerzo significa que el modelo se toma tiempo para pensar profundamente. Estás aprendiendo a ajustar el esfuerzo a la complejidad de la tarea - no pierdas tiempo en preguntas simples, pero tampoco apresures decisiones complejas. +GPT-5.2 te permite controlar el esfuerzo computacional por medio de tus prompts. Bajo esfuerzo significa respuestas rápidas con exploración mínima. Alto esfuerzo significa que el modelo toma tiempo para pensar profundamente. Estás aprendiendo a empatar el esfuerzo con la complejidad de la tarea — no malgastes tiempo en preguntas simples, pero tampoco apresures decisiones complejas. -**La Estructura Guía el Comportamiento** +**La estructura guía el comportamiento** -¿Notas las etiquetas XML en los prompts? No son decorativas. Los modelos siguen instrucciones estructuradas de manera más confiable que texto libre. Cuando necesitas procesos multietapas o lógica compleja, la estructura ayuda al modelo a rastrear en qué punto está y qué sigue. El diagrama abajo desglosa un prompt bien estructurado, mostrando cómo etiquetas como ``, ``, ``, ``, y `` organizan tus instrucciones en secciones claras. +¿Notas las etiquetas XML en los prompts? No son decorativas. Los modelos siguen instrucciones estructuradas más confiablemente que texto libre. Cuando necesitas procesos de múltiples pasos o lógica compleja, la estructura ayuda al modelo a saber dónde está y qué sigue. El diagrama abajo desglosa un prompt bien estructurado, mostrando cómo las etiquetas como ``, ``, ``, ``, y `` organizan tus instrucciones en secciones claras. -Estructura del Prompt +Estructura del prompt *Anatomía de un prompt bien estructurado con secciones claras y organización estilo XML* -**Calidad a Través de la Autoevaluación** +**Calidad mediante autoevaluación** -Los patrones auto-reflexivos funcionan haciendo explícitos los criterios de calidad. En lugar de esperar que el modelo "lo haga bien", le dices exactamente qué significa "bien": lógica correcta, manejo de errores, rendimiento, seguridad. Entonces el modelo puede evaluar su propia salida y mejorar. Esto convierte la generación de código de una lotería en un proceso. +Los patrones auto-reflexivos funcionan haciendo explícitos los criterios de calidad. En lugar de esperar que el modelo "lo haga bien", le dices exactamente qué significa "bien": lógica correcta, manejo de errores, rendimiento, seguridad. El modelo puede luego evaluar su propia salida y mejorarla. Esto convierte la generación de código de una lotería en un proceso. -**El Contexto es Finito** +**El contexto es finito** -Las conversaciones multiturno funcionan incluyendo el historial de mensajes con cada solicitud. Pero hay un límite - cada modelo tiene un conteo máximo de tokens. A medida que crecen las conversaciones, necesitarás estrategias para mantener el contexto relevante sin alcanzar ese límite. Este módulo muestra cómo funciona la memoria; más adelante aprenderás cuándo resumir, cuándo olvidar y cuándo recuperar. +Las conversaciones multinivel funcionan incluyendo el historial de mensajes con cada solicitud. Pero hay un límite — cada modelo tiene un máximo de tokens. A medida que crecen las conversaciones, necesitarás estrategias para mantener contexto relevante sin pasar ese límite. Este módulo te muestra cómo funciona la memoria; más adelante aprenderás cuándo resumir, cuándo olvidar y cuándo recuperar. -## Próximos Pasos +## Próximos pasos -**Próximo Módulo:** [03-rag - RAG (Generación Aumentada por Recuperación)](../03-rag/README.md) +**Siguiente módulo:** [03-rag - RAG (Generación aumentada por recuperación)](../03-rag/README.md) --- -**Navegación:** [← Anterior: Módulo 01 - Introducción](../01-introduction/README.md) | [Volver al Inicio](../README.md) | [Siguiente: Módulo 03 - RAG →](../03-rag/README.md) +**Navegación:** [← Anterior: Módulo 01 - Introducción](../01-introduction/README.md) | [Volver al inicio](../README.md) | [Siguiente: Módulo 03 - RAG →](../03-rag/README.md) --- -**Aviso Legal**: -Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por lograr precisión, tenga en cuenta que las traducciones automáticas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional realizada por humanos. No nos hacemos responsables de malentendidos o interpretaciones erróneas derivadas del uso de esta traducción. +**Descargo de responsabilidad**: +Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción. \ No newline at end of file diff --git a/translations/es/03-rag/README.md b/translations/es/03-rag/README.md index e39e7708f..14ed8e87c 100644 --- a/translations/es/03-rag/README.md +++ b/translations/es/03-rag/README.md @@ -2,29 +2,29 @@ ## Tabla de Contenidos -- [Video Explicativo](../../../03-rag) -- [Lo Que Aprenderás](../../../03-rag) -- [Requisitos Previos](../../../03-rag) -- [Entendiendo RAG](../../../03-rag) - - [¿Qué Enfoque RAG Usa Este Tutorial?](../../../03-rag) -- [Cómo Funciona](../../../03-rag) - - [Procesamiento de Documentos](../../../03-rag) - - [Creación de Embeddings](../../../03-rag) - - [Búsqueda Semántica](../../../03-rag) - - [Generación de Respuestas](../../../03-rag) -- [Ejecutar la Aplicación](../../../03-rag) -- [Uso de la Aplicación](../../../03-rag) - - [Subir un Documento](../../../03-rag) - - [Hacer Preguntas](../../../03-rag) - - [Verificar Referencias de Origen](../../../03-rag) - - [Experimentar con Preguntas](../../../03-rag) -- [Conceptos Clave](../../../03-rag) - - [Estrategia de Segmentación](../../../03-rag) - - [Puntajes de Similitud](../../../03-rag) - - [Almacenamiento en Memoria](../../../03-rag) - - [Gestión de la Ventana de Contexto](../../../03-rag) -- [Cuándo Importa RAG](../../../03-rag) -- [Próximos Pasos](../../../03-rag) +- [Video Explicativo](#video-explicativo) +- [Lo Que Aprenderás](#lo-que-aprenderás) +- [Requisitos Previos](#requisitos-previos) +- [Entendiendo RAG](#entendiendo-rag) + - [¿Qué Enfoque RAG Usa Este Tutorial?](#qué-enfoque-rag-usa-este-tutorial) +- [Cómo Funciona](#cómo-funciona) + - [Procesamiento de Documentos](#procesamiento-de-documentos) + - [Creación de Embeddings](#creación-de-embeddings) + - [Búsqueda Semántica](#búsqueda-semántica) + - [Generación de Respuestas](#generación-de-respuestas) +- [Ejecutar la Aplicación](#ejecutar-la-aplicación) +- [Usando la Aplicación](#uso-de-la-aplicación) + - [Subir un Documento](#subir-un-documento) + - [Hacer Preguntas](#hacer-preguntas) + - [Consultar Referencias de la Fuente](#revisar-referencias-de-fuente) + - [Experimentar con Preguntas](#experimenta-con-preguntas) +- [Conceptos Clave](#conceptos-clave) + - [Estrategia de División en Fragmentos](#estrategia-de-fragmentación) + - [Puntajes de Similitud](#puntuaciones-de-similitud) + - [Almacenamiento en Memoria](#almacenamiento-en-memoria) + - [Gestión de la Ventana de Contexto](#gestión-de-ventana-de-contexto) +- [Cuándo Importa RAG](#cuándo-importa-rag) +- [Próximos Pasos](#próximos-pasos) ## Video Explicativo @@ -34,80 +34,79 @@ Mira esta sesión en vivo que explica cómo comenzar con este módulo: ## Lo Que Aprenderás -En los módulos anteriores, aprendiste a tener conversaciones con IA y a estructurar tus indicaciones de forma efectiva. Pero hay una limitación fundamental: los modelos de lenguaje solo saben lo que aprendieron durante el entrenamiento. No pueden responder preguntas sobre las políticas de tu empresa, la documentación de tu proyecto, o cualquier información que no hayan visto durante el entrenamiento. +En los módulos anteriores, aprendiste a tener conversaciones con IA y a estructurar tus prompts de manera efectiva. Pero hay una limitación fundamental: los modelos de lenguaje solo saben lo que aprendieron durante el entrenamiento. No pueden responder preguntas sobre las políticas de tu empresa, la documentación de tu proyecto o cualquier información con la que no fueron entrenados. -RAG (Generación Aumentada por Recuperación) resuelve este problema. En lugar de intentar enseñar al modelo tu información (lo cual es costoso e impráctico), le das la capacidad de buscar en tus documentos. Cuando alguien hace una pregunta, el sistema encuentra información relevante y la incluye en la indicación. El modelo entonces responde basándose en ese contexto recuperado. +RAG (Generación Aumentada por Recuperación) resuelve este problema. En lugar de intentar enseñar al modelo tu información (lo cual es costoso e impráctico), le das la capacidad de buscar en tus documentos. Cuando alguien hace una pregunta, el sistema encuentra la información relevante y la incluye en el prompt. El modelo entonces responde basándose en ese contexto recuperado. Piensa en RAG como darle al modelo una biblioteca de referencia. Cuando haces una pregunta, el sistema: -1. **Consulta del Usuario** - Haces una pregunta +1. **Consulta del usuario** - Haces una pregunta 2. **Embedding** - Convierte tu pregunta en un vector -3. **Búsqueda Vectorial** - Encuentra fragmentos de documentos similares -4. **Ensamblaje del Contexto** - Añade fragmentos relevantes a la indicación +3. **Búsqueda vectorial** - Encuentra fragmentos de documentos similares +4. **Montaje del contexto** - Añade fragmentos relevantes al prompt 5. **Respuesta** - El LLM genera una respuesta basada en el contexto -Esto fundamenta las respuestas del modelo en tus datos reales en lugar de depender solo de su conocimiento de entrenamiento o inventar respuestas. +Esto fundamenta las respuestas del modelo en tus datos reales en lugar de depender solo en su conocimiento de entrenamiento o inventar respuestas. ## Requisitos Previos -- Haber completado [Módulo 00 - Inicio Rápido](../00-quick-start/README.md) (para el ejemplo Easy RAG referenciado más adelante en este módulo) -- Haber completado [Módulo 01 - Introducción](../01-introduction/README.md) (recursos Azure OpenAI desplegados, incluyendo el modelo de embedding `text-embedding-3-small`) -- Archivo `.env` en el directorio raíz con credenciales Azure (creado por `azd up` en Módulo 01) +- Haber completado [Módulo 01 - Introducción](../01-introduction/README.md) (recursos Azure OpenAI desplegados, incluyendo el modelo embedding `text-embedding-3-small`) +- Archivo `.env` en el directorio raíz con credenciales de Azure (creado por `azd up` en el Módulo 01) -> **Nota:** Si no has completado el Módulo 01, sigue primero las instrucciones de despliegue ahí. El comando `azd up` despliega tanto el modelo de chat GPT como el modelo de embedding usado por este módulo. +> **Nota:** Si no has completado el Módulo 01, sigue primero las instrucciones de despliegue allí. El comando `azd up` despliega tanto el modelo de chat GPT como el modelo embedding usado por este módulo. ## Entendiendo RAG -El diagrama a continuación ilustra el concepto central: en lugar de depender solo de los datos de entrenamiento del modelo, RAG le da una biblioteca de referencia con tus documentos para consultar antes de generar cada respuesta. +El diagrama a continuación ilustra el concepto central: en lugar de depender solo en los datos de entrenamiento del modelo, RAG le da una biblioteca de referencia con tus documentos para consultar antes de generar cada respuesta. Qué es RAG -*Este diagrama muestra la diferencia entre un LLM estándar (que adivina a partir de datos de entrenamiento) y un LLM mejorado con RAG (que consulta primero tus documentos).* +*Este diagrama muestra la diferencia entre un LLM estándar (que adivina basado en datos de entrenamiento) y un LLM mejorado con RAG (que consulta primero tus documentos).* -Aquí se muestra cómo se conectan las piezas de principio a fin. La pregunta de un usuario pasa por cuatro etapas: embedding, búsqueda vectorial, ensamblaje del contexto y generación de respuesta — cada una construyendo sobre la anterior: +Así es como las piezas se conectan de extremo a extremo. La pregunta de un usuario pasa por cuatro etapas: embedding, búsqueda vectorial, montaje del contexto y generación de respuestas — cada una construyendo sobre la anterior: Arquitectura RAG -*Este diagrama muestra la pipeline completa de RAG — la consulta del usuario pasa por embedding, búsqueda vectorial, ensamblaje del contexto y generación de respuesta.* +*Este diagrama muestra la canalización RAG de extremo a extremo — una consulta de usuario pasa por embedding, búsqueda vectorial, montaje del contexto y generación de respuesta.* -El resto de este módulo recorre cada etapa en detalle, con código que puedes ejecutar y modificar. +El resto de este módulo recorre cada etapa con detalle, con código que puedes ejecutar y modificar. ### ¿Qué Enfoque RAG Usa Este Tutorial? -LangChain4j ofrece tres maneras de implementar RAG, cada una con un nivel diferente de abstracción. El diagrama a continuación los compara lado a lado: +LangChain4j ofrece tres formas de implementar RAG, cada una con un nivel diferente de abstracción. El diagrama a continuación las compara lado a lado: Tres Enfoques RAG en LangChain4j *Este diagrama compara los tres enfoques RAG de LangChain4j — Fácil, Nativo y Avanzado — mostrando sus componentes clave y cuándo usar cada uno.* -| Enfoque | Qué Hace | Compromiso | +| Enfoque | Qué Hace | Compensación | |---|---|---| -| **Easy RAG** | Conecta todo automáticamente mediante `AiServices` y `ContentRetriever`. Anotas una interfaz, adjuntas un recuperador, y LangChain4j maneja embedding, búsqueda y ensamblaje del prompt detrás de escena. | Menor código, pero no ves lo que sucede en cada paso. | -| **Native RAG** | Llamas tú mismo al modelo de embedding, buscas en el almacén, construyes el prompt y generas la respuesta — paso explícito por paso. | Más código, pero cada etapa es visible y modificable. | -| **Advanced RAG** | Usa el framework `RetrievalAugmentor` con transformadores de consulta enchufables, enrutadores, reordenadores e inyectores de contenido para pipelines de producción. | Máxima flexibilidad, pero con mucha más complejidad. | +| **Easy RAG** | Conecta todo automáticamente a través de `AiServices` y `ContentRetriever`. Anotas una interfaz, adjuntas un recuperador, y LangChain4j maneja embedding, búsqueda y ensamblaje del prompt detrás de escena. | Código mínimo, pero no ves lo que pasa en cada paso. | +| **Native RAG** | Llamas al modelo embedding, buscas en la tienda, construyes el prompt y generas la respuesta tú mismo — un paso explícito a la vez. | Más código, pero cada etapa es visible y modificable. | +| **Advanced RAG** | Usa el framework `RetrievalAugmentor` con transformadores de consulta plug-ins, rutadores, reordenadores y inyectores de contenido para canalizaciones de grado producción. | Máxima flexibilidad, pero mucha más complejidad. | -**Este tutorial usa el enfoque Nativo.** Cada paso del pipeline RAG — embedding de la consulta, búsqueda en el almacén vectorial, ensamblaje del contexto, y generación de la respuesta — está explícitamente escrito en [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Esto es intencional: como recurso de aprendizaje, es más importante que veas y entiendas cada etapa que minimizar el código. Una vez que te sientas cómodo con cómo encajan las piezas, puedes avanzar al Easy RAG para prototipos rápidos o al Advanced RAG para sistemas en producción. +**Este tutorial usa el enfoque Nativo.** Cada paso de la canalización RAG — embedding de la consulta, búsqueda en la tienda vectorial, montaje del contexto y generación de la respuesta — está explicitado en [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Esto es intencionado: como recurso didáctico, es más importante que veas y entiendas cada etapa que minimizar el código. Una vez cómodo con cómo encajan las piezas, puedes pasar a Easy RAG para prototipos rápidos o Advanced RAG para sistemas de producción. -> **💡 ¿Ya viste Easy RAG en acción?** El [módulo de Inicio Rápido](../00-quick-start/README.md) incluye un ejemplo de Preguntas y Respuestas de Documentos ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) que usa el enfoque Easy RAG — LangChain4j maneja automáticamente embedding, búsqueda y ensamblaje del prompt. Este módulo da el siguiente paso al abrir ese pipeline para que puedas ver y controlar cada etapa tú mismo. +> **💡 ¿Curioso sobre Easy RAG?** LangChain4j también ofrece un enfoque *Easy RAG* donde `AiServices` y un `ContentRetriever` manejan automáticamente embedding, búsqueda y ensamblaje del prompt. Este módulo toma la ruta más explícita — desarmando esa canalización para que veas y controles cada etapa. -El diagrama a continuación muestra el pipeline Easy RAG de ese ejemplo de Inicio Rápido. Nota cómo `AiServices` y `EmbeddingStoreContentRetriever` ocultan toda la complejidad — cargas un documento, adjuntas un recuperador y obtienes respuestas. El enfoque Nativo en este módulo desglosa cada uno de esos pasos ocultos: +El diagrama a continuación muestra la canalización Easy RAG. Observa cómo `AiServices` y `EmbeddingStoreContentRetriever` ocultan toda la complejidad — cargas un documento, adjuntas un recuperador y obtienes respuestas. El enfoque Nativo de este módulo abre cada uno de esos pasos ocultos: -Pipeline Easy RAG - LangChain4j +Canalización Easy RAG - LangChain4j -*Este diagrama muestra el pipeline Easy RAG de `SimpleReaderDemo.java`. Compara esto con el enfoque Nativo usado en este módulo: Easy RAG oculta embedding, recuperación y ensamblaje del prompt detrás de `AiServices` y `ContentRetriever` — cargas un documento, adjuntas un recuperador y obtienes respuestas. El enfoque Nativo en este módulo descompone ese pipeline para que llames cada etapa (embedding, búsqueda, ensamblaje del contexto, generación) tú mismo, proporcionándote plena visibilidad y control.* +*Este diagrama muestra la canalización Easy RAG. Compárala con el enfoque Nativo usado en este módulo: Easy RAG oculta embedding, recuperación y ensamblaje del prompt detrás de `AiServices` y `ContentRetriever` — cargas un documento, adjuntas un recuperador y obtienes respuestas. El enfoque Nativo de este módulo desarma esa canalización para que llames cada etapa (embed, buscar, ensamblar contexto, generar) tú mismo, dándote visibilidad y control completos.* ## Cómo Funciona -El pipeline RAG en este módulo se divide en cuatro etapas que se ejecutan en secuencia cada vez que un usuario hace una pregunta. Primero, un documento subido es **analizado y segmentado** en partes manejables. Esos fragmentos se convierten en **embeddings vectoriales** y se almacenan para poder compararse matemáticamente. Cuando llega una consulta, el sistema realiza una **búsqueda semántica** para encontrar los fragmentos más relevantes, y finalmente los pasa como contexto al LLM para **generar la respuesta**. Las secciones siguientes recorren cada etapa con el código real y diagramas. Veamos el primer paso. +La canalización RAG en este módulo se divide en cuatro etapas que se ejecutan secuencialmente cada vez que un usuario hace una pregunta. Primero, un documento subido es **analizado y dividido en fragmentos** manejables. Esos fragmentos luego se convierten en **embeddings vectoriales** y se almacenan para que puedan compararse matemáticamente. Cuando llega una consulta, el sistema realiza una **búsqueda semántica** para encontrar los fragmentos más relevantes, y finalmente los pasa como contexto al LLM para la **generación de la respuesta**. Las secciones a continuación describen cada etapa con código y diagramas. Comencemos con el primer paso. ### Procesamiento de Documentos [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Cuando subes un documento, el sistema lo analiza (PDF o texto plano), le adjunta metadatos como el nombre del archivo, y luego lo divide en fragmentos — piezas más pequeñas que caben cómodamente en la ventana de contexto del modelo. Estos fragmentos se superponen ligeramente para que no se pierda contexto en los límites. +Cuando subes un documento, el sistema lo analiza (PDF o texto plano), adjunta metadatos como el nombre del archivo, y luego lo divide en fragmentos — piezas más pequeñas que caben cómodamente en la ventana de contexto del modelo. Estos fragmentos se solapan ligeramente para no perder contexto en los límites. ```java -// Analizar el archivo cargado y envolverlo en un Documento LangChain4j +// Analizar el archivo subido y envolverlo en un Documento de LangChain4j Document document = Document.from(content, metadata); // Dividir en fragmentos de 300 tokens con una superposición de 30 tokens @@ -117,28 +116,28 @@ DocumentSplitter splitter = DocumentSplitters List segments = splitter.split(document); ``` -El diagrama a continuación muestra cómo funciona esto visualmente. Observa cómo cada fragmento comparte algunos tokens con sus vecinos — la superposición de 30 tokens asegura que no se pierda contexto importante entre los cortes: +El diagrama a continuación muestra cómo funciona visualmente. Observa cómo cada fragmento comparte algunos tokens con sus vecinos — el solapamiento de 30 tokens asegura que no se pierda contexto importante entre los fragmentos: -Segmentación de Documento +División de Documentos en Fragmentos -*Este diagrama muestra un documento dividido en fragmentos de 300 tokens con superposición de 30 tokens, preservando el contexto en los límites del fragmento.* +*Este diagrama muestra un documento dividiéndose en fragmentos de 300 tokens con un solapamiento de 30 tokens, preservando el contexto en los límites de los fragmentos.* > **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) y pregunta: -> - "¿Cómo divide LangChain4j los documentos en fragmentos y por qué es importante la superposición?" +> - "¿Cómo divide LangChain4j documentos en fragmentos y por qué es importante el solapamiento?" > - "¿Cuál es el tamaño óptimo de fragmento para diferentes tipos de documentos y por qué?" -> - "¿Cómo manejo documentos en varios idiomas o con formato especial?" +> - "¿Cómo manejo documentos en múltiples idiomas o con formato especial?" ### Creación de Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Cada fragmento se convierte en una representación numérica llamada embedding — esencialmente un convertidor de significado a números. El modelo de embedding no es "inteligente" como un modelo de chat; no puede seguir instrucciones, razonar o responder preguntas. Lo que puede hacer es mapear texto a un espacio matemático donde significados similares quedan cerca unos de otros — “coche” cerca de “automóvil”, “política de reembolso” cerca de “devuélveme el dinero.” Piensa en un modelo de chat como una persona con quien puedes hablar; un modelo de embedding es un sistema de archivo ultra-eficiente. +Cada fragmento se convierte en una representación numérica llamada embedding — esencialmente un convertidor de significado a números. El modelo embedding no es "inteligente" como un modelo de chat; no puede seguir instrucciones, razonar ni responder preguntas. Lo que sí puede hacer es mapear el texto en un espacio matemático donde significados similares quedan cerca — "auto" cerca de "automóvil," "política de reembolso" cerca de "devolver mi dinero." Piensa en un modelo de chat como una persona con quien puedes hablar; un modelo embedding es un sistema de archivo ultra eficiente. -El diagrama a continuación visualiza este concepto — entra texto, salen vectores numéricos, y significados similares producen vectores cercanos: +El diagrama a continuación visualiza este concepto — el texto entra, vectores numéricos salen, y significados similares producen vectores cercanos: -Concepto de Modelo de Embedding +Concepto de Modelo Embedding -*Este diagrama muestra cómo un modelo de embedding convierte texto en vectores numéricos, ubicando significados similares — como “coche” y “automóvil” — cerca uno del otro en el espacio vectorial.* +*Este diagrama muestra cómo un modelo embedding convierte texto en vectores numéricos, colocando significados similares — como "auto" y "automóvil" — cerca uno del otro en el espacio vectorial.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -El diagrama de clases a continuación muestra los dos flujos separados en un pipeline RAG y las clases LangChain4j que los implementan. El **flujo de ingestión** (se ejecuta una vez al subir) divide el documento, embebe los fragmentos, y los almacena vía `.addAll()`. El **flujo de consulta** (se ejecuta cada vez que un usuario pregunta) embebe la pregunta, busca en el almacén vía `.search()`, y pasa el contexto encontrado al modelo de chat. Ambos flujos se conectan por la interfaz compartida `EmbeddingStore`: +El diagrama de clases muestra los dos flujos separados en una canalización RAG y las clases LangChain4j que los implementan. El **flujo de ingestión** (se ejecuta una vez al subir) divide el documento, embebe los fragmentos y los almacena vía `.addAll()`. El **flujo de consulta** (se ejecuta cada vez que un usuario pregunta) embebe la pregunta, busca en la tienda vía `.search()` y pasa el contexto coincidente al modelo chat. Ambos flujos convergen en la interfaz compartida `EmbeddingStore`: Clases RAG de LangChain4j -*Este diagrama muestra los dos flujos en un pipeline RAG — ingestión y consulta — y cómo se conectan a través de un EmbeddingStore compartido.* +*Este diagrama muestra los dos flujos en una canalización RAG — ingestión y consulta — y cómo se conectan a través de un EmbeddingStore compartido.* -Una vez que los embeddings están almacenados, el contenido similar naturalmente se agrupa en el espacio vectorial. La visualización a continuación muestra cómo documentos sobre temas relacionados terminan como puntos cercanos, lo que hace posible la búsqueda semántica: +Una vez almacenados los embeddings, el contenido similar naturalmente se agrupa en el espacio vectorial. La visualización a continuación muestra cómo documentos sobre temas relacionados terminan como puntos cercanos, lo que hace posible la búsqueda semántica: Espacio de Embeddings Vectoriales -*Esta visualización muestra cómo documentos relacionados se agrupan juntos en espacio vectorial 3D, con temas como Documentación Técnica, Reglas de Negocio y Preguntas Frecuentes formando grupos distintos.* +*Esta visualización muestra cómo documentos relacionados se agrupan en 3D en el espacio vectorial, con temas como Documentos Técnicos, Reglas de Negocio y FAQs formando grupos distintos.* -Cuando un usuario realiza una búsqueda, el sistema sigue cuatro pasos: embebe los documentos una vez, embebe la consulta en cada búsqueda, compara el vector de la consulta contra todos los vectores almacenados usando similitud coseno, y devuelve los fragmentos con los puntajes más altos (top-K). El diagrama a continuación describe cada paso y las clases LangChain4j involucradas: +Cuando un usuario busca, el sistema sigue cuatro pasos: embeddear los documentos una vez, embeddear la consulta en cada búsqueda, comparar el vector de la consulta contra todos los vectores almacenados usando similitud coseno, y devolver los fragmentos con las mejores puntuaciones top-K. El diagrama a continuación describe cada paso y las clases LangChain4j involucradas: -Pasos de Búsqueda por Embedding +Pasos de Búsqueda Embedding -*Este diagrama muestra el proceso de búsqueda por embedding en cuatro pasos: embedear documentos, embedear la consulta, comparar vectores con similitud coseno, y devolver los mejores resultados.* +*Este diagrama muestra el proceso de búsqueda embedding en cuatro pasos: embeddear documentos, embeddear la consulta, comparar vectores con similitud coseno, y devolver los mejores resultados top-K.* ### Búsqueda Semántica [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Cuando haces una pregunta, tu consulta también se convierte en un embedding. El sistema compara el embedding de tu pregunta contra los embeddings de todos los fragmentos. Encuentra los fragmentos con los significados más similares — no solo coincidencias de palabras clave, sino similitud semántica real. +Cuando haces una pregunta, tu pregunta también se convierte en embedding. El sistema compara el embedding de tu pregunta con todos los embeddings de los fragmentos de documento. Encuentra los fragmentos con los significados más similares — no solo palabras clave coincidentes, sino similitud semántica real. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -El diagrama a continuación contrasta la búsqueda semántica con la búsqueda tradicional por palabras clave. Una búsqueda por palabra clave de “vehículo” no encuentra un fragmento sobre “coches y camiones,” pero la búsqueda semántica entiende que significan lo mismo y lo devuelve como resultado con alta puntuación: +El diagrama a continuación compara la búsqueda semántica con la búsqueda tradicional por palabras clave. Una búsqueda por palabra clave de "vehículo" no encuentra un fragmento sobre "autos y camiones," pero la búsqueda semántica entiende que significan lo mismo y lo devuelve con alta puntuación: Búsqueda Semántica *Este diagrama compara la búsqueda basada en palabras clave con la búsqueda semántica, mostrando cómo la búsqueda semántica recupera contenido conceptualmente relacionado incluso cuando las palabras clave exactas difieren.* -Bajo el capó, la similitud se mide usando la similitud coseno: básicamente preguntando "¿están estas dos flechas apuntando en la misma dirección?" Dos fragmentos pueden usar palabras completamente diferentes, pero si significan lo mismo sus vectores apuntan en la misma dirección y obtienen una puntuación cercana a 1.0: -Similitud Coseno +Internamente, la similitud se mide usando similitud coseno — esencialmente preguntando "¿apuntan estas dos flechas en la misma dirección?" Dos fragmentos pueden usar palabras completamente diferentes, pero si significan lo mismo sus vectores apuntan en la misma dirección y la puntuación es cercana a 1.0: -*Este diagrama ilustra la similitud coseno como el ángulo entre vectores de incrustaciones — vectores más alineados obtienen puntuaciones más cercanas a 1.0, indicando mayor similitud semántica.* +Similitud Coseno +*Este diagrama ilustra la similitud del coseno como el ángulo entre vectores de incrustación: los vectores más alineados obtienen una puntuación más cercana a 1.0, lo que indica una mayor similitud semántica.* > **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) y pregunta: > - "¿Cómo funciona la búsqueda por similitud con embeddings y qué determina la puntuación?" -> - "¿Qué umbral de similitud debería usar y cómo afecta los resultados?" +> - "¿Qué umbral de similitud debo usar y cómo afecta los resultados?" > - "¿Cómo manejo casos donde no se encuentran documentos relevantes?" ### Generación de Respuestas [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Los fragmentos más relevantes se ensamblan en un prompt estructurado que incluye instrucciones explícitas, el contexto recuperado y la pregunta del usuario. El modelo lee esos fragmentos específicos y responde basado en esa información — solo puede usar lo que tiene frente a sí, lo que previene alucinaciones. +Los fragmentos más relevantes se ensamblan en un prompt estructurado que incluye instrucciones explícitas, el contexto recuperado y la pregunta del usuario. El modelo lee esos fragmentos específicos y responde basándose en esa información: solo puede usar lo que tiene delante, lo que previene la alucinación. ```java String context = matches.stream() @@ -237,15 +236,15 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -El diagrama a continuación muestra este ensamblaje en acción — los fragmentos con la puntuación más alta del paso de búsqueda se inyectan en la plantilla de prompt, y el `OpenAiOfficialChatModel` genera una respuesta fundamentada: +El diagrama a continuación muestra este ensamblaje en acción: los fragmentos con mayor puntuación del paso de búsqueda se inyectan en la plantilla del prompt, y el `OpenAiOfficialChatModel` genera una respuesta fundamentada: -Ensamblaje de Contexto +Montaje de Contexto *Este diagrama muestra cómo los fragmentos con mayor puntuación se ensamblan en un prompt estructurado, permitiendo que el modelo genere una respuesta fundamentada a partir de tus datos.* ## Ejecutar la Aplicación -**Verificar despliegue:** +**Verificar el despliegue:** Asegúrate de que el archivo `.env` exista en el directorio raíz con las credenciales de Azure (creado durante el Módulo 01). Ejecuta esto desde el directorio del módulo (`03-rag/`): @@ -256,30 +255,30 @@ cat ../.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **PowerShell:** ```powershell -Get-Content ..\.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Debería mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Iniciar la aplicación:** -> **Nota:** Si ya iniciaste todas las aplicaciones usando `./start-all.sh` desde el directorio raíz (como se describe en el Módulo 01), este módulo ya está corriendo en el puerto 8081. Puedes omitir los comandos de inicio a continuación e ir directamente a http://localhost:8081. +> **Nota:** Si ya iniciaste todas las aplicaciones usando `./start-all.sh` desde el directorio raíz (como se describe en el Módulo 01), este módulo ya está ejecutándose en el puerto 8081. Puedes omitir los comandos de inicio a continuación e ir directamente a http://localhost:8081. -**Opción 1: Usando Spring Boot Dashboard (Recomendado para usuarios de VS Code)** +**Opción 1: Usar Spring Boot Dashboard (Recomendado para usuarios de VS Code)** -El contenedor de desarrollo incluye la extensión Spring Boot Dashboard, que ofrece una interfaz visual para administrar todas las aplicaciones Spring Boot. Puedes encontrarla en la Barra de Actividad al lado izquierdo de VS Code (busca el ícono de Spring Boot). +El contenedor de desarrollo incluye la extensión Spring Boot Dashboard, que proporciona una interfaz visual para gestionar todas las aplicaciones Spring Boot. Puedes encontrarlo en la Barra de Actividades al lado izquierdo de VS Code (busca el ícono de Spring Boot). -Desde Spring Boot Dashboard, puedes: +Desde el Spring Boot Dashboard, puedes: - Ver todas las aplicaciones Spring Boot disponibles en el espacio de trabajo - Iniciar/detener aplicaciones con un solo clic -- Ver los logs de la aplicación en tiempo real +- Ver los registros de la aplicación en tiempo real - Monitorear el estado de la aplicación -Simplemente haz clic en el botón de reproducir junto a "rag" para iniciar este módulo, o inicia todos los módulos a la vez. +Simplemente haz clic en el botón de reproducir al lado de "rag" para iniciar este módulo, o inicia todos los módulos a la vez. -Panel de Control Spring Boot +Spring Boot Dashboard -*Esta captura de pantalla muestra el panel de control Spring Boot en VS Code, donde puedes iniciar, detener y monitorear aplicaciones visualmente.* +*Esta captura de pantalla muestra el Spring Boot Dashboard en VS Code, donde puedes iniciar, detener y monitorear aplicaciones visualmente.* -**Opción 2: Usando scripts shell** +**Opción 2: Usar scripts de shell** Inicia todas las aplicaciones web (módulos 01-04): @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Ambos scripts cargan automáticamente las variables de entorno del archivo `.env` raíz y construirán los JAR si no existen. +Ambos scripts cargan automáticamente variables de entorno desde el archivo `.env` raíz y construirán los JAR si no existen. -> **Nota:** Si prefieres construir todos los módulos manualmente antes de iniciar: +> **Nota:** Si prefieres compilar todos los módulos manualmente antes de iniciar: > > **Bash:** > ```bash @@ -331,7 +330,7 @@ Abre http://localhost:8081 en tu navegador. **Bash:** ```bash -./stop.sh # Solo este módulo +./stop.sh # Este módulo solamente # O cd .. && ./stop-all.sh # Todos los módulos ``` @@ -345,29 +344,29 @@ cd ..; .\stop-all.ps1 # Todos los módulos ## Uso de la Aplicación -La aplicación proporciona una interfaz web para subir documentos y hacer preguntas. +La aplicación ofrece una interfaz web para subir documentos y hacer preguntas. -Interfaz de la Aplicación RAG +Interfaz de Aplicación RAG -*Esta captura de pantalla muestra la interfaz de la aplicación RAG donde subes documentos y haces preguntas.* +*Esta captura de pantalla muestra la interfaz de la aplicación RAG donde cargas documentos y haces preguntas.* ### Subir un Documento -Comienza subiendo un documento - los archivos TXT funcionan mejor para pruebas. Se proporciona un `sample-document.txt` en este directorio que contiene información sobre características de LangChain4j, implementación RAG y mejores prácticas - perfecto para probar el sistema. +Comienza subiendo un documento: los archivos TXT funcionan mejor para pruebas. Se ofrece un `sample-document.txt` en este directorio que contiene información sobre características de LangChain4j, implementación de RAG y mejores prácticas, ideal para probar el sistema. -El sistema procesa tu documento, lo divide en fragmentos y crea embeddings para cada fragmento. Esto sucede automáticamente cuando subes el archivo. +El sistema procesa tu documento, lo divide en fragmentos y crea embeddings para cada fragmento. Esto ocurre automáticamente al subirlo. ### Hacer Preguntas -Ahora formula preguntas específicas sobre el contenido del documento. Intenta algo factual que esté claramente indicado en el documento. El sistema busca fragmentos relevantes, los incluye en el prompt y genera una respuesta. +Ahora formula preguntas específicas sobre el contenido del documento. Prueba con algo factual que esté claramente indicado en el documento. El sistema busca fragmentos relevantes, los incluye en el prompt y genera una respuesta. -### Verificar Referencias de Fuente +### Revisar Referencias de Fuente -Nota que cada respuesta incluye referencias de fuente con puntuaciones de similitud. Estas puntuaciones (de 0 a 1) muestran qué tan relevante fue cada fragmento para tu pregunta. Puntuaciones más altas significan mejores coincidencias. Esto te permite verificar la respuesta contra el material fuente. +Observa que cada respuesta incluye referencias a las fuentes con puntuaciones de similitud. Estas puntuaciones (de 0 a 1) muestran qué tan relevante fue cada fragmento para tu pregunta. Las puntuaciones más altas significan mejores coincidencias. Esto te permite verificar la respuesta con el material fuente. Resultados de Consulta RAG -*Esta captura de pantalla muestra los resultados de la consulta con la respuesta generada, referencias de fuente y puntuaciones de relevancia para cada fragmento recuperado.* +*Esta captura de pantalla muestra resultados de consulta con la respuesta generada, referencias a fuentes y puntuaciones de relevancia para cada fragmento recuperado.* ### Experimenta con Preguntas @@ -376,17 +375,17 @@ Prueba diferentes tipos de preguntas: - Comparaciones: "¿Cuál es la diferencia entre X y Y?" - Resúmenes: "Resume los puntos clave sobre Z" -Observa cómo cambian las puntuaciones de relevancia según qué tan bien tu pregunta coincide con el contenido del documento. +Observa cómo cambian las puntuaciones de relevancia según qué tan bien tu pregunta coincida con el contenido del documento. ## Conceptos Clave ### Estrategia de Fragmentación -Los documentos se dividen en fragmentos de 300 tokens con 30 tokens de solapamiento. Este equilibrio asegura que cada fragmento tenga suficiente contexto para ser significativo mientras permanece lo suficientemente pequeño para incluir varios fragmentos en un prompt. +Los documentos se dividen en fragmentos de 300 tokens con 30 tokens de solapamiento. Este equilibrio asegura que cada fragmento tenga suficiente contexto para ser significativo mientras se mantiene lo suficientemente pequeño para incluir múltiples fragmentos en un prompt. ### Puntuaciones de Similitud -Cada fragmento recuperado viene con una puntuación de similitud entre 0 y 1 que indica qué tan cerca coincide con la pregunta del usuario. El diagrama a continuación visualiza los rangos de puntuación y cómo el sistema los usa para filtrar resultados: +Cada fragmento recuperado viene con una puntuación de similitud entre 0 y 1 que indica qué tan de cerca coincide con la pregunta del usuario. El diagrama a continuación visualiza los rangos de puntuación y cómo el sistema los usa para filtrar resultados: Puntuaciones de Similitud @@ -395,43 +394,43 @@ Cada fragmento recuperado viene con una puntuación de similitud entre 0 y 1 que Las puntuaciones van de 0 a 1: - 0.7-1.0: Altamente relevante, coincidencia exacta - 0.5-0.7: Relevante, buen contexto -- Por debajo de 0.5: Filtrado, demasiado disímil +- Por debajo de 0.5: Filtrado, demasiado diferente El sistema solo recupera fragmentos por encima del umbral mínimo para garantizar calidad. -Los embeddings funcionan bien cuando el significado se agrupa claramente, pero tienen puntos ciegos. El diagrama a continuación muestra los modos comunes de falla: fragmentos demasiado grandes producen vectores imprecisos, fragmentos muy pequeños carecen de contexto, términos ambiguos apuntan a múltiples grupos, y las búsquedas de coincidencia exacta (IDs, números de parte) no funcionan con embeddings en absoluto: +Los embeddings funcionan bien cuando el significado está claramente agrupado, pero tienen puntos ciegos. El diagrama a continuación muestra los modos comunes de fallo: fragmentos demasiado grandes producen vectores confusos, fragmentos demasiado pequeños carecen de contexto, términos ambiguos apuntan a múltiples grupos, y las búsquedas de coincidencia exacta (IDs, números de parte) no funcionan con embeddings en absoluto: Modos de Falla de Embeddings -*Este diagrama muestra modos comunes de falla de embeddings: fragmentos demasiado grandes, fragmentos demasiado pequeños, términos ambiguos que apuntan a múltiples grupos, y búsquedas de coincidencia exacta como IDs.* +*Este diagrama muestra modos comunes de falla de embeddings: fragmentos demasiado grandes, fragmentos demasiado pequeños, términos ambiguos que apuntan a múltiples grupos y búsquedas de coincidencia exacta como IDs.* ### Almacenamiento en Memoria -Este módulo usa almacenamiento en memoria para simplicidad. Cuando reinicias la aplicación, los documentos subidos se pierden. Los sistemas en producción usan bases de datos vectoriales persistentes como Qdrant o Azure AI Search. +Este módulo usa almacenamiento en memoria para simplificar. Cuando reinicias la aplicación, se pierden los documentos subidos. Los sistemas en producción usan bases de datos de vectores persistentes como Qdrant o Azure AI Search. -### Gestión de la Ventana de Contexto +### Gestión de Ventana de Contexto -Cada modelo tiene una ventana máxima de contexto. No puedes incluir todos los fragmentos de un documento grande. El sistema recupera los N fragmentos más relevantes (por defecto 5) para mantenerse dentro de los límites mientras proporciona suficiente contexto para respuestas precisas. +Cada modelo tiene una ventana máxima de contexto. No puedes incluir cada fragmento de un documento grande. El sistema recupera los N fragmentos más relevantes (por defecto 5) para mantenerse dentro de los límites y proveer suficiente contexto para respuestas precisas. ## Cuándo Importa RAG -RAG no siempre es el enfoque correcto. La guía de decisiones a continuación te ayuda a determinar cuándo RAG agrega valor frente a cuándo enfoques más simples — como incluir contenido directamente en el prompt o confiar en el conocimiento incorporado del modelo — son suficientes: +RAG no siempre es el enfoque adecuado. La guía de decisión abajo te ayuda a determinar cuándo RAG aporta valor frente a cuándo enfoques más simples —como incluir contenido directamente en el prompt o confiar en el conocimiento interno del modelo— son suficientes: Cuándo Usar RAG -*Este diagrama muestra una guía de decisión para cuándo RAG agrega valor versus cuándo enfoques más simples son suficientes.* +*Este diagrama muestra una guía de decisión para cuándo RAG aporta valor frente a cuándo enfoques más simples son suficientes.* ## Próximos Pasos -**Próximo Módulo:** [04-tools - Agentes de IA con Herramientas](../04-tools/README.md) +**Siguiente Módulo:** [04-tools - Agentes de IA con Herramientas](../04-tools/README.md) --- -**Navegación:** [← Anterior: Módulo 02 - Ingeniería de Prompts](../02-prompt-engineering/README.md) | [Volver al Inicio](../README.md) | [Siguiente: Módulo 04 - Herramientas →](../04-tools/README.md) +**Navegación:** [← Prev: Módulo 02 - Ingeniería de Prompts](../02-prompt-engineering/README.md) | [Volver al Inicio](../README.md) | [Siguiente: Módulo 04 - Herramientas →](../04-tools/README.md) --- -**Aviso Legal**: -Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda la traducción profesional realizada por un humano. No somos responsables de ningún malentendido o interpretación errónea derivada del uso de esta traducción. +**Descargo de responsabilidad**: +Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción. \ No newline at end of file diff --git a/translations/es/04-tools/README.md b/translations/es/04-tools/README.md index 149ff6d82..b7006b734 100644 --- a/translations/es/04-tools/README.md +++ b/translations/es/04-tools/README.md @@ -2,75 +2,75 @@ ## Tabla de Contenidos -- [Recorrido en Video](../../../04-tools) -- [Lo que Aprenderás](../../../04-tools) -- [Prerrequisitos](../../../04-tools) -- [Entendiendo los Agentes de IA con Herramientas](../../../04-tools) -- [Cómo Funciona la Llamada a Herramientas](../../../04-tools) - - [Definiciones de Herramientas](../../../04-tools) - - [Toma de Decisiones](../../../04-tools) - - [Ejecución](../../../04-tools) - - [Generación de Respuestas](../../../04-tools) - - [Arquitectura: Auto-Conexión en Spring Boot](../../../04-tools) -- [Encadenamiento de Herramientas](../../../04-tools) -- [Ejecutar la Aplicación](../../../04-tools) -- [Uso de la Aplicación](../../../04-tools) - - [Prueba de Uso Simple de Herramientas](../../../04-tools) - - [Prueba de Encadenamiento de Herramientas](../../../04-tools) - - [Ver Flujo de Conversación](../../../04-tools) - - [Experimentar con Diferentes Solicitudes](../../../04-tools) -- [Conceptos Clave](../../../04-tools) - - [Patrón ReAct (Razonar y Actuar)](../../../04-tools) - - [Importancia de las Descripciones de las Herramientas](../../../04-tools) - - [Gestión de Sesiones](../../../04-tools) - - [Manejo de Errores](../../../04-tools) -- [Herramientas Disponibles](../../../04-tools) -- [Cuándo Usar Agentes Basados en Herramientas](../../../04-tools) -- [Herramientas vs RAG](../../../04-tools) -- [Próximos Pasos](../../../04-tools) - -## Recorrido en Video +- [Video Tutorial](#video-tutorial) +- [Lo Que Aprenderás](#lo-que-aprenderás) +- [Prerequisitos](#prerequisitos) +- [Entendiendo Agentes de IA con Herramientas](#entendiendo-agentes-de-ia-con-herramientas) +- [Cómo Funciona la Llamada a Herramientas](#cómo-funciona-la-llamada-a-herramientas) + - [Definiciones de Herramientas](#definiciones-de-herramientas) + - [Toma de Decisiones](#toma-de-decisiones) + - [Ejecución](#ejecución) + - [Generación de la Respuesta](#generación-de-la-respuesta) + - [Arquitectura: Auto-conexión con Spring Boot](#arquitectura-auto-conexión-con-spring-boot) +- [Encadenamiento de Herramientas](#encadenamiento-de-herramientas) +- [Ejecutar la Aplicación](#ejecutar-la-aplicación) +- [Usar la Aplicación](#uso-de-la-aplicación) + - [Prueba de Uso Simple de Herramientas](#prueba-el-uso-simple-de-herramientas) + - [Prueba el Encadenamiento de Herramientas](#prueba-la-cadena-de-herramientas) + - [Ver Flujo de Conversación](#observa-el-flujo-de-conversación) + - [Experimenta con Diferentes Solicitudes](#experimenta-con-diferentes-solicitudes) +- [Conceptos Clave](#conceptos-clave) + - [Patrón ReAct (Razonar y Actuar)](#patrón-react-razonar-y-actuar) + - [Las Descripciones de las Herramientas Importan](#las-descripciones-de-herramientas-importan) + - [Gestión de Sesiones](#gestión-de-sesiones) + - [Manejo de Errores](#manejo-de-errores) +- [Herramientas Disponibles](#herramientas-disponibles) +- [Cuándo Usar Agentes Basados en Herramientas](#cuándo-usar-agentes-basados-en-herramientas) +- [Herramientas vs RAG](#herramientas-vs-rag) +- [Próximos Pasos](#próximos-pasos) + +## Video Tutorial Mira esta sesión en vivo que explica cómo comenzar con este módulo: Agentes de IA con Herramientas y MCP - Sesión en Vivo -## Lo que Aprenderás +## Lo Que Aprenderás -Hasta ahora, has aprendido a mantener conversaciones con IA, estructurar indicaciones de manera efectiva y fundamentar respuestas en tus documentos. Pero todavía hay una limitación fundamental: los modelos de lenguaje solo pueden generar texto. No pueden consultar el clima, realizar cálculos, consultar bases de datos o interactuar con sistemas externos. +Hasta ahora, has aprendido cómo mantener conversaciones con IA, estructurar prompts de manera efectiva y fundamentar respuestas en tus documentos. Pero todavía hay una limitación fundamental: los modelos de lenguaje solo pueden generar texto. No pueden consultar el clima, realizar cálculos, consultar bases de datos ni interactuar con sistemas externos. -Las herramientas cambian esto. Al darle al modelo acceso a funciones que puede llamar, lo transformas de un generador de texto a un agente que puede tomar acciones. El modelo decide cuándo necesita una herramienta, cuál usar y qué parámetros pasar. Tu código ejecuta la función y devuelve el resultado. El modelo incorpora ese resultado en su respuesta. +Las herramientas cambian esto. Al darle al modelo acceso a funciones que puede llamar, lo transformas de un generador de texto a un agente que puede tomar acciones. El modelo decide cuándo necesita una herramienta, qué herramienta usar y qué parámetros pasar. Tu código ejecuta la función y devuelve el resultado. El modelo incorpora ese resultado en su respuesta. -## Prerrequisitos +## Prerequisitos -- Completar [Módulo 01 - Introducción](../01-introduction/README.md) (recursos Azure OpenAI desplegados) -- Se recomiendan los módulos previos completados (este módulo refiere a [conceptos de RAG del Módulo 03](../03-rag/README.md) en la comparación Herramientas vs RAG) -- Archivo `.env` en el directorio raíz con credenciales de Azure (creado con `azd up` en el Módulo 01) +- Haber completado [Módulo 01 - Introducción](../01-introduction/README.md) (recursos Azure OpenAI desplegados) +- Se recomiendan módulos previos completados (este módulo refiere a [conceptos de RAG del Módulo 03](../03-rag/README.md) en la comparación Herramientas vs RAG) +- Archivo `.env` en el directorio raíz con credenciales Azure (creado por `azd up` en el Módulo 01) -> **Nota:** Si no has completado el Módulo 01, sigue primero las instrucciones de despliegue allí. +> **Nota:** Si no has completado el Módulo 01, sigue primero las instrucciones de despliegue ahí. -## Entendiendo los Agentes de IA con Herramientas +## Entendiendo Agentes de IA con Herramientas -> **📝 Nota:** El término "agentes" en este módulo se refiere a asistentes de IA mejorados con capacidades de llamada a herramientas. Esto es diferente de los patrones **Agentic AI** (agentes autónomos con planificación, memoria y razonamiento en múltiples pasos) que abordaremos en [Módulo 05: MCP](../05-mcp/README.md). +> **📝 Nota:** El término "agentes" en este módulo se refiere a asistentes de IA mejorados con capacidad de llamada a herramientas. Esto es diferente a los patrones de **Agentes Autónomos** (agentes autónomos con planificación, memoria y razonamiento multietapa) que cubriremos en [Módulo 05: MCP](../05-mcp/README.md). -Sin herramientas, un modelo de lenguaje solo puede generar texto basado en sus datos de entrenamiento. Pregúntale el clima actual y tiene que adivinar. Dale herramientas, y puede llamar a una API del clima, realizar cálculos o consultar una base de datos — luego entretejer esos resultados reales en su respuesta. +Sin herramientas, un modelo de lenguaje solo puede generar texto de sus datos de entrenamiento. Pregúntale por el clima actual, y debe adivinar. Dale herramientas, y puede llamar a una API del clima, realizar cálculos o consultar una base de datos — luego teje esos resultados reales en su respuesta. Sin Herramientas vs Con Herramientas -*Sin herramientas, el modelo solo puede adivinar — con herramientas puede llamar APIs, realizar cálculos y devolver datos en tiempo real.* +*Sin herramientas el modelo solo puede adivinar — con herramientas puede llamar APIs, hacer cálculos y devolver datos en tiempo real.* -Un agente de IA con herramientas sigue un patrón de **Razonamiento y Acción (ReAct)**. El modelo no solo responde — piensa en lo que necesita, actúa llamando a una herramienta, observa el resultado y luego decide si actúa nuevamente o entrega la respuesta final: +Un agente de IA con herramientas sigue un patrón de **Razonar y Actuar (ReAct)**. El modelo no solo responde — piensa en lo que necesita, actúa llamando a una herramienta, observa el resultado, y luego decide si actuar de nuevo o entregar la respuesta final: 1. **Razonar** — El agente analiza la pregunta del usuario y determina qué información necesita 2. **Actuar** — El agente selecciona la herramienta correcta, genera los parámetros adecuados y la llama -3. **Observar** — El agente recibe la salida de la herramienta y evalúa el resultado -4. **Repetir o Responder** — Si se necesita más datos, el agente repite; si no, compone una respuesta en lenguaje natural +3. **Observar** — El agente recibe el resultado de la herramienta y evalúa +4. **Repetir o Responder** — Si necesita más datos, vuelve al paso 1; si no, compone una respuesta en lenguaje natural Patrón ReAct -*El ciclo ReAct — el agente razona sobre qué hacer, actúa llamando a una herramienta, observa el resultado y repite hasta poder entregar la respuesta final.* +*El ciclo ReAct — el agente razona qué hacer, actúa llamando una herramienta, observa el resultado y repite hasta entregar la respuesta final.* -Esto ocurre automáticamente. Definís las herramientas y sus descripciones. El modelo maneja la toma de decisión sobre cuándo y cómo usarlas. +Esto sucede automáticamente. Definiste las herramientas y sus descripciones. El modelo maneja la toma de decisiones sobre cuándo y cómo usarlas. ## Cómo Funciona la Llamada a Herramientas @@ -78,7 +78,7 @@ Esto ocurre automáticamente. Definís las herramientas y sus descripciones. El [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Defines funciones con descripciones claras y especificaciones de parámetros. El modelo ve esas descripciones en su prompt de sistema y comprende lo que hace cada herramienta. +Defines funciones con descripciones claras y especificaciones de parámetros. El modelo ve estas descripciones en su prompt de sistema y entiende qué hace cada herramienta. ```java @Component @@ -96,7 +96,7 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// El asistente está conectado automáticamente por Spring Boot con: +// El asistente está automáticamente conectado por Spring Boot con: // - Bean ChatModel // - Todos los métodos @Tool de las clases @Component // - ChatMemoryProvider para la gestión de sesiones @@ -106,129 +106,129 @@ El diagrama a continuación desglosa cada anotación y muestra cómo cada parte Anatomía de Definiciones de Herramientas -*Anatomía de una definición de herramienta — @Tool indica a la IA cuándo usarla, @P describe cada parámetro, y @AiService conecta todo al inicio.* +*Anatomía de una definición de herramienta — @Tool le dice a la IA cuándo usarla, @P describe cada parámetro, y @AiService conecta todo junto al iniciar.* > **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) y pregunta: > - "¿Cómo integraría una API real del clima como OpenWeatherMap en lugar de datos simulados?" -> - "¿Qué hace que una buena descripción de herramienta ayude a la IA a usarla correctamente?" -> - "¿Cómo manejo errores de API y límites de tasa en implementaciones de herramientas?" +> - "¿Qué hace una buena descripción de herramienta que ayuda a la IA a usarla correctamente?" +> - "¿Cómo manejo errores de API y límites de tasa en la implementación de herramientas?" ### Toma de Decisiones -Cuando un usuario pregunta "¿Cuál es el clima en Seattle?", el modelo no elige una herramienta al azar. Compara la intención del usuario con cada descripción de herramienta a la que tiene acceso, puntúa cada una por relevancia y selecciona la mejor coincidencia. Luego genera una llamada de función estructurada con los parámetros correctos — en este caso, fijando `location` a `"Seattle"`. +Cuando un usuario pregunta "¿Cuál es el clima en Seattle?", el modelo no elige una herramienta al azar. Compara la intención del usuario con todas las descripciones de herramientas a las que tiene acceso, califica cada una en relevancia y selecciona la mejor. Luego genera una llamada de función estructurada con los parámetros correctos — en este caso, ajustando `location` a `"Seattle"`. -Si ninguna herramienta coincide con la solicitud del usuario, el modelo recurre a responder con su propio conocimiento. Si varias herramientas coinciden, elige la más específica. +Si ninguna herramienta coincide con la solicitud del usuario, el modelo responde con base en su propio conocimiento. Si múltiples herramientas coinciden, elige la más específica. Cómo la IA Decide Qué Herramienta Usar -*El modelo evalúa todas las herramientas disponibles contra la intención del usuario y selecciona la mejor coincidencia — por eso es importante escribir descripciones claras y específicas.* +*El modelo evalúa cada herramienta disponible contra la intención del usuario y selecciona la mejor coincidencia — por eso es importante escribir descripciones claras y específicas de herramientas.* ### Ejecución [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot conecta automáticamente la interfaz declarativa `@AiService` con todas las herramientas registradas, y LangChain4j ejecuta las llamadas a herramientas automáticamente. Detrás de escena, una llamada completa a herramienta fluye a través de seis etapas — desde la pregunta en lenguaje natural del usuario hasta la respuesta final en lenguaje natural: +Spring Boot conecta automáticamente la interfaz declarativa `@AiService` con todas las herramientas registradas, y LangChain4j ejecuta las llamadas a herramientas automáticamente. Detrás de escena, una llamada completa a herramienta atraviesa seis etapas — desde la pregunta en lenguaje natural del usuario hasta la respuesta también en lenguaje natural: Flujo de Llamada a Herramientas -*El flujo de punta a punta — el usuario hace una pregunta, el modelo selecciona una herramienta, LangChain4j la ejecuta y el modelo integra el resultado en una respuesta natural.* +*El flujo de extremo a extremo — el usuario hace una pregunta, el modelo selecciona una herramienta, LangChain4j la ejecuta y el modelo integra el resultado en una respuesta natural.* -Si ejecutaste el [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) en el Módulo 00, ya viste este patrón en acción — las herramientas `Calculator` eran llamadas de la misma forma. El diagrama de secuencia abajo muestra exactamente qué pasó internamente durante esa demo: +Por detrás, `AiServices` ejecuta el mismo ciclo de llamada a herramientas para cualquier herramienta — aquí ilustrado con un simple `Calculator`. El diagrama de secuencia a continuación muestra exactamente qué sucede internamente: Diagrama de Secuencia de Llamada a Herramientas -*El ciclo de llamada a herramientas desde la demo de Inicio Rápido — `AiServices` envía tu mensaje y esquemas de herramientas al LLM, el LLM responde con una llamada función como `add(42, 58)`, LangChain4j ejecuta el método `Calculator` localmente y devuelve el resultado para la respuesta final.* +*El ciclo de llamada a herramientas — `AiServices` envía tu mensaje y esquemas de herramientas al LLM, el LLM responde con una llamada de función como `add(42, 58)`, LangChain4j ejecuta el método `Calculator` localmente y envía el resultado para la respuesta final.* > **🤖 Prueba con [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) y pregunta: > - "¿Cómo funciona el patrón ReAct y por qué es efectivo para agentes de IA?" > - "¿Cómo decide el agente qué herramienta usar y en qué orden?" -> - "¿Qué sucede si falla la ejecución de una herramienta? ¿Cómo debo manejar errores de forma robusta?" +> - "¿Qué pasa si falla la ejecución de una herramienta — cómo manejar errores de forma robusta?" -### Generación de Respuesta +### Generación de la Respuesta El modelo recibe los datos del clima y los formatea en una respuesta en lenguaje natural para el usuario. -### Arquitectura: Auto-Conexión en Spring Boot +### Arquitectura: Auto-conexión con Spring Boot -Este módulo usa la integración de LangChain4j con Spring Boot mediante interfaces declarativas `@AiService`. Al iniciar, Spring Boot descubre cada `@Component` que contiene métodos con `@Tool`, tu bean `ChatModel` y el `ChatMemoryProvider` — luego los conecta todos en una sola interfaz `Assistant` sin código repetitivo. +Este módulo usa la integración de LangChain4j con Spring Boot mediante interfaces declarativas `@AiService`. Al iniciar, Spring Boot descubre cada `@Component` que contiene métodos `@Tool`, tu bean `ChatModel` y el `ChatMemoryProvider` — luego los conecta todos en una sola interfaz `Assistant` sin código repetitivo. -Arquitectura de Auto-Conexión en Spring Boot +Arquitectura de Auto-Conexión con Spring Boot -*La interfaz @AiService une el ChatModel, los componentes de herramientas y el proveedor de memoria — Spring Boot gestiona toda la conexión automáticamente.* +*La interfaz @AiService une el ChatModel, componentes de herramientas y el proveedor de memoria — Spring Boot maneja toda la conexión automáticamente.* -Aquí está el ciclo completo de la solicitud en un diagrama de secuencia — desde la solicitud HTTP a través del controlador, servicio y proxy auto-conectado, hasta la ejecución de la herramienta y la respuesta: +Aquí está el ciclo completo de la solicitud como diagrama de secuencia — desde la petición HTTP pasando por el controlador, servicio y proxy auto-conectado, hasta la ejecución de la herramienta y regreso: -Secuencia de Llamada a Herramientas en Spring Boot +Diagrama de Secuencia de Llamada de Herramientas en Spring Boot -*El ciclo completo de solicitud en Spring Boot — la solicitud HTTP fluye a través del controlador y servicio al proxy Assistant auto-conectado, que orquesta el LLM y las llamadas a herramientas automáticamente.* +*Ciclo completo de solicitud Spring Boot — la petición HTTP pasa por el controlador y servicio al proxy Assistant auto-conectado, que orquesta el LLM y llamadas a herramientas automáticamente.* Beneficios clave de este enfoque: -- **Auto-conexión de Spring Boot** — ChatModel y herramientas inyectados automáticamente -- **Patrón @MemoryId** — Gestión automática de memoria basada en sesión +- **Auto-conexión en Spring Boot** — ChatModel y herramientas inyectadas automáticamente +- **Patrón @MemoryId** — Gestión automática de memoria por sesión - **Instancia única** — Assistant creado una vez y reutilizado para mejor rendimiento -- **Ejecución segura de tipo** — Métodos Java llamados directamente con conversión de tipos -- **Orquestación de múltiples turnos** — Maneja encadenamiento de herramientas automáticamente -- **Cero código repetitivo** — Sin llamadas manuales a `AiServices.builder()` ni mapas de memoria +- **Ejecución segura en tipos** — Métodos Java llamados directamente con conversión de tipos +- **Orquestación multivuelta** — Maneja encadenamiento de herramientas automáticamente +- **Cero boilerplate** — Sin llamadas manuales a `AiServices.builder()` ni mapas de memoria -Enfoques alternativos (manual `AiServices.builder()`) requieren más código y pierden los beneficios de integración con Spring Boot. +Enfoques alternativos (manual `AiServices.builder()`) requieren más código y pierden beneficios de integración con Spring Boot. ## Encadenamiento de Herramientas -**Encadenamiento de Herramientas** — El verdadero poder de los agentes basados en herramientas aparece cuando una sola pregunta requiere múltiples herramientas. Pregunta "¿Cuál es el clima en Seattle en Fahrenheit?" y el agente encadena automáticamente dos herramientas: primero llama a `getCurrentWeather` para obtener la temperatura en Celsius, luego pasa ese valor a `celsiusToFahrenheit` para la conversión — todo en un solo turno de conversación. +**Encadenamiento de Herramientas** — El poder real de agentes basados en herramientas se muestra cuando una sola pregunta requiere múltiples herramientas. Pregunta "¿Cuál es el clima en Seattle en Fahrenheit?" y el agente encadena automáticamente dos herramientas: primero llama a `getCurrentWeather` para obtener la temperatura en Celsius, luego pasa ese valor a `celsiusToFahrenheit` para convertirlo — todo en una sola vuelta de conversación. Ejemplo de Encadenamiento de Herramientas -*Encadenamiento de herramientas en acción — el agente llama primero a getCurrentWeather, luego pasa el resultado en Celsius a celsiusToFahrenheit y entrega una respuesta combinada.* +*Encadenamiento de herramientas en acción — el agente llama primero getCurrentWeather, luego pasa el resultado en Celsius a celsiusToFahrenheit y entrega una respuesta combinada.* -**Fallos Graceful** — Pide el clima en una ciudad que no está en los datos simulados. La herramienta devuelve un mensaje de error y la IA explica que no puede ayudar en lugar de fallar. Las herramientas fallan de forma segura. El diagrama a continuación contrasta ambos enfoques — con manejo adecuado de errores, el agente captura la excepción y responde amablemente, mientras sin él la aplicación entera colapsa: +**Fallas Graceful** — Pide el clima en una ciudad que no está en los datos simulados. La herramienta devuelve un mensaje de error, y la IA explica que no puede ayudar en lugar de fallar. Las herramientas fallan de forma segura. El diagrama a continuación contrasta los dos enfoques — con manejo adecuado de errores, el agente captura la excepción y responde con ayuda, mientras que sin él la aplicación entera falla: Flujo de Manejo de Errores -*Cuando una herramienta falla, el agente captura el error y responde con una explicación útil en lugar de fallar.* +*Cuando una herramienta falla, el agente atrapa el error y responde con una explicación útil en lugar de fallar.* -Esto sucede en un solo turno de conversación. El agente orquesta múltiples llamadas a herramientas de forma autónoma. +Esto ocurre en una sola vuelta de conversación. El agente orquesta múltiples llamadas a herramientas autónomamente. ## Ejecutar la Aplicación -**Verificar despliegue:** +**Verifica el despliegue:** -Asegúrate de que el archivo `.env` exista en el directorio raíz con las credenciales de Azure (creado durante el Módulo 01). Ejecuta esto desde el directorio del módulo (`04-tools/`): +Asegúrate de que el archivo `.env` exista en el directorio raíz con credenciales Azure (creado durante el Módulo 01). Ejecuta esto desde el directorio del módulo (`04-tools/`): **Bash:** ```bash -cat ../.env # Debería mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Debería mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Debe mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Iniciar la aplicación:** +**Inicia la aplicación:** -> **Nota:** Si ya iniciaste todas las aplicaciones usando `./start-all.sh` desde el directorio raíz (como se describió en el Módulo 01), este módulo ya está ejecutándose en el puerto 8084. Puedes omitir los comandos de inicio abajo y acceder directamente a http://localhost:8084. +> **Nota:** Si ya iniciaste todas las aplicaciones usando `./start-all.sh` desde el directorio raíz (como se describió en el Módulo 01), este módulo ya está corriendo en el puerto 8084. Puedes saltarte los comandos de inicio y abrir directamente http://localhost:8084. -**Opción 1: Usando el Spring Boot Dashboard (Recomendado para usuarios de VS Code)** +**Opción 1: Usar el Spring Boot Dashboard (Recomendado para usuarios de VS Code)** -El contenedor de desarrollo incluye la extensión Spring Boot Dashboard, que proporciona una interfaz visual para administrar todas las aplicaciones Spring Boot. La encontrarás en la Barra de Actividad al lado izquierdo de VS Code (busca el ícono de Spring Boot). +El contenedor de desarrollo incluye la extensión Spring Boot Dashboard, que ofrece una interfaz visual para manejar todas las aplicaciones Spring Boot. Puedes encontrarla en la Barra de Actividades al lado izquierdo de VS Code (busca el ícono de Spring Boot). -Desde el Spring Boot Dashboard, puedes: -- Ver todas las aplicaciones Spring Boot disponibles en el espacio de trabajo -- Iniciar/detener aplicaciones con un solo clic -- Ver logs de aplicaciones en tiempo real +Desde Spring Boot Dashboard puedes: +- Ver todas las aplicaciones Spring Boot disponibles en el área de trabajo +- Iniciar/detener aplicaciones con un solo click +- Ver logs de la aplicación en tiempo real - Monitorear el estado de las aplicaciones -Simplemente haga clic en el botón de reproducir junto a "tools" para comenzar este módulo, o inicie todos los módulos a la vez. -Así es como se ve el Spring Boot Dashboard en VS Code: +Solo haz clic en el botón de reproducir junto a "tools" para iniciar este módulo, o inicia todos los módulos a la vez. -Spring Boot Dashboard +Así se ve Spring Boot Dashboard en VS Code: +Panel de Spring Boot -*El Spring Boot Dashboard en VS Code — iniciar, detener y monitorear todos los módulos desde un solo lugar* +*El Panel de Spring Boot en VS Code: inicia, detén y monitorea todos los módulos desde un solo lugar* -**Opción 2: Usando scripts de shell** +**Opción 2: Usando scripts shell** -Inicie todas las aplicaciones web (módulos 01-04): +Inicia todas las aplicaciones web (módulos 01-04): **Bash:** ```bash @@ -242,7 +242,7 @@ cd .. # Desde el directorio raíz .\start-all.ps1 ``` -O inicie solo este módulo: +O inicia solo este módulo: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Ambos scripts cargan automáticamente las variables de entorno desde el archivo `.env` raíz y construirán los JARs si no existen. +Ambos scripts cargan automáticamente las variables de entorno desde el archivo `.env` raíz y compilarán los JAR si no existen. -> **Nota:** Si prefiere compilar todos los módulos manualmente antes de iniciar: +> **Nota:** Si prefieres compilar todos los módulos manualmente antes de iniciar: > > **Bash:** > ```bash @@ -272,7 +272,7 @@ Ambos scripts cargan automáticamente las variables de entorno desde el archivo > mvn clean package -DskipTests > ``` -Abra http://localhost:8084 en su navegador. +Abre http://localhost:8084 en tu navegador. **Para detener:** @@ -292,88 +292,88 @@ cd ..; .\stop-all.ps1 # Todos los módulos ## Uso de la Aplicación -La aplicación ofrece una interfaz web donde puedes interactuar con un agente de IA que tiene acceso a herramientas de clima y conversión de temperatura. Así es como se ve la interfaz — incluye ejemplos rápidos y un panel de chat para enviar solicitudes: +La aplicación ofrece una interfaz web donde puedes interactuar con un agente de IA que tiene acceso a herramientas de clima y conversión de temperatura. Así es como se ve la interfaz: incluye ejemplos de inicio rápido y un panel de chat para enviar solicitudes: -AI Agent Tools Interface +Interfaz de Herramientas del Agente IA -*La interfaz de Herramientas del Agente de IA: ejemplos rápidos e interfaz de chat para interactuar con herramientas* +*La interfaz de Herramientas del Agente IA - ejemplos rápidos e interfaz de chat para interactuar con las herramientas* -### Pruebe un Uso Simple de Herramientas +### Prueba el Uso Simple de Herramientas -Comience con una solicitud sencilla: "Convertir 100 grados Fahrenheit a Celsius". El agente reconoce que necesita la herramienta de conversión de temperatura, la llama con los parámetros correctos y devuelve el resultado. Note lo natural que se siente — no especificó qué herramienta usar ni cómo llamarla. +Comienza con una solicitud sencilla: "Convierte 100 grados Fahrenheit a Celsius". El agente reconoce que necesita la herramienta de conversión de temperatura, la usa con los parámetros correctos y devuelve el resultado. Observa lo natural que se siente: no especificaste qué herramienta usar ni cómo llamarla. -### Pruebe la Cadena de Herramientas +### Prueba la Cadena de Herramientas -Ahora intente algo más complejo: "¿Cuál es el clima en Seattle y conviértalo a Fahrenheit?" Observe cómo el agente procesa esto en pasos. Primero obtiene el clima (que devuelve Celsius), reconoce que debe convertir a Fahrenheit, llama a la herramienta de conversión y combina ambos resultados en una sola respuesta. +Ahora intenta algo más complejo: "¿Cuál es el clima en Seattle y conviértelo a Fahrenheit?" Mira cómo el agente trabaja paso a paso. Primero obtiene el clima (que devuelve en Celsius), reconoce que debe convertir a Fahrenheit, llama a la herramienta de conversión y combina ambos resultados en una sola respuesta. -### Vea el Flujo de la Conversación +### Observa el Flujo de Conversación -La interfaz de chat mantiene el historial de la conversación, permitiendo interacciones multi-turno. Puede ver todas las consultas y respuestas anteriores, facilitando seguir la conversación y entender cómo el agente construye el contexto a lo largo de múltiples intercambios. +La interfaz de chat mantiene el historial de la conversación, permitiéndote tener interacciones de varios turnos. Puedes ver todas las consultas y respuestas anteriores, facilitando seguir la conversación y entender cómo el agente construye contexto a través de múltiples intercambios. -Conversation with Multiple Tool Calls +Conversación con Múltiples Llamadas a Herramientas -*Conversación multi-turno mostrando conversiones simples, consultas meteorológicas y encadenamiento de herramientas* +*Conversación de múltiples turnos mostrando conversiones simples, consultas del clima y encadenamiento de herramientas* -### Experimente con Diferentes Solicitudes +### Experimenta con Diferentes Solicitudes -Pruebe varias combinaciones: -- Consultas meteorológicas: "¿Cuál es el clima en Tokio?" -- Conversiones de temperatura: "¿Cuánto es 25 °C en Kelvin?" -- Consultas combinadas: "Revisa el clima en París y dime si está por encima de 20 °C" +Prueba varias combinaciones: +- Consultas del clima: "¿Cuál es el clima en Tokio?" +- Conversiones de temperatura: "¿Cuánto es 25°C en Kelvin?" +- Consultas combinadas: "Consulta el clima en París y dime si está arriba de 20°C" -Observe cómo el agente interpreta el lenguaje natural y lo mapea a llamadas apropiadas a herramientas. +Observa cómo el agente interpreta el lenguaje natural y lo mapea a llamadas apropiadas a herramientas. ## Conceptos Clave -### Patrón ReAct (Razonamiento y Acción) +### Patrón ReAct (Razonar y Actuar) -El agente alterna entre razonar (decidir qué hacer) y actuar (usar herramientas). Este patrón permite la resolución autónoma de problemas en lugar de solo responder a instrucciones. +El agente alterna entre razonar (decidir qué hacer) y actuar (usar herramientas). Este patrón permite resolver problemas de forma autónoma en lugar de solo responder instrucciones. -### Las Descripciones de las Herramientas Importan +### Las Descripciones de Herramientas Importan -La calidad de las descripciones de tus herramientas afecta directamente qué tan bien el agente las utiliza. Descripciones claras y específicas ayudan al modelo a entender cuándo y cómo llamar a cada herramienta. +La calidad de las descripciones de tus herramientas afecta directamente qué tan bien el agente las usa. Descripciones claras y específicas ayudan al modelo a entender cuándo y cómo llamar cada herramienta. ### Gestión de Sesiones -La anotación `@MemoryId` habilita la gestión automática de memoria basada en sesiones. Cada ID de sesión obtiene su propia instancia `ChatMemory` gestionada por el bean `ChatMemoryProvider`, de modo que múltiples usuarios pueden interactuar con el agente simultáneamente sin que sus conversaciones se mezclen. El siguiente diagrama muestra cómo múltiples usuarios se dirigen a almacenes de memoria aislados según sus IDs de sesión: +La anotación `@MemoryId` permite la gestión automática de memoria basada en sesiones. Cada ID de sesión obtiene su propia instancia de `ChatMemory` gestionada por el bean `ChatMemoryProvider`, por lo que múltiples usuarios pueden interactuar con el agente simultáneamente sin mezclar sus conversaciones. El siguiente diagrama muestra cómo múltiples usuarios son dirigidos a almacenes de memoria aislados según sus IDs de sesión: -Session Management with @MemoryId +Gestión de Sesiones con @MemoryId -*Cada ID de sesión se asigna a un historial de conversación aislado — los usuarios nunca ven los mensajes de otros.* +*Cada ID de sesión se mapea a un historial de conversación aislado — los usuarios nunca ven los mensajes de los demás.* ### Manejo de Errores -Las herramientas pueden fallar — las API pueden agotar tiempo, los parámetros pueden ser inválidos, los servicios externos pueden caer. Los agentes en producción necesitan manejo de errores para que el modelo pueda explicar problemas o intentar alternativas en lugar de colapsar toda la aplicación. Cuando una herramienta lanza una excepción, LangChain4j la captura y envía el mensaje de error al modelo, que entonces puede explicar el problema en lenguaje natural. +Las herramientas pueden fallar — las APIs pueden tener tiempo de espera, parámetros podrían ser inválidos, servicios externos pueden caerse. Los agentes en producción necesitan manejo de errores para que el modelo pueda explicar problemas o intentar alternativas en vez de que toda la aplicación falle. Cuando una herramienta lanza una excepción, LangChain4j la captura y envía el mensaje de error de vuelta al modelo, el cual puede explicar el problema en lenguaje natural. ## Herramientas Disponibles El diagrama a continuación muestra el amplio ecosistema de herramientas que puedes construir. Este módulo demuestra herramientas de clima y temperatura, pero el mismo patrón `@Tool` funciona para cualquier método Java — desde consultas a bases de datos hasta procesamiento de pagos. -Tool Ecosystem +Ecosistema de Herramientas -*Cada método Java anotado con @Tool queda disponible para la IA — el patrón se extiende a bases de datos, APIs, correo electrónico, operaciones de archivos y más.* +*Cualquier método Java anotado con @Tool está disponible para la IA — el patrón se extiende a bases de datos, APIs, correo, operaciones de archivos y más.* ## Cuándo Usar Agentes Basados en Herramientas -No todas las solicitudes necesitan herramientas. La decisión depende de si la IA necesita interactuar con sistemas externos o puede responder con su propio conocimiento. La siguiente guía resume cuándo las herramientas añaden valor y cuándo no son necesarias: +No todas las solicitudes necesitan herramientas. La decisión depende de si la IA necesita interactuar con sistemas externos o puede responder desde su propio conocimiento. La guía siguiente resume cuándo las herramientas agregan valor y cuándo no son necesarias: -When to Use Tools +Cuándo Usar Herramientas -*Una guía rápida para decidir — las herramientas son para datos en tiempo real, cálculos y acciones; el conocimiento general y tareas creativas no las necesitan.* +*Guía rápida de decisión: las herramientas son para datos en tiempo real, cálculos y acciones; el conocimiento general y tareas creativas no las necesitan.* ## Herramientas vs RAG -Los módulos 03 y 04 amplían lo que la IA puede hacer, pero de formas fundamentalmente diferentes. RAG le da al modelo acceso a **conocimiento** recuperando documentos. Las Herramientas le dan al modelo la capacidad de tomar **acciones** llamando funciones. El diagrama a continuación compara estos dos enfoques lado a lado — desde cómo opera cada flujo de trabajo hasta las compensaciones entre ellos: +Los módulos 03 y 04 amplían lo que la IA puede hacer, pero de formas fundamentalmente diferentes. RAG le da al modelo acceso a **conocimiento** recuperando documentos. Las herramientas le dan la capacidad de tomar **acciones** llamando funciones. El diagrama a continuación compara estos dos enfoques lado a lado — desde cómo funciona cada flujo de trabajo hasta sus compromisos: -Tools vs RAG Comparison +Comparación Herramientas vs RAG -*RAG recupera información de documentos estáticos — Las Herramientas ejecutan acciones y obtienen datos dinámicos en tiempo real. Muchos sistemas de producción combinan ambos.* +*RAG recupera información de documentos estáticos — Herramientas ejecutan acciones y obtienen datos dinámicos en tiempo real. Muchos sistemas en producción combinan ambos.* -En la práctica, muchos sistemas de producción combinan ambos enfoques: RAG para fundamentar respuestas en tu documentación y Herramientas para obtener datos en vivo o realizar operaciones. +En la práctica, muchos sistemas de producción combinan ambos enfoques: RAG para fundamentar respuestas en tu documentación, y Herramientas para obtener datos en vivo o realizar operaciones. ## Próximos Pasos -**Próximo Módulo:** [05-mcp - Protocolo de Contexto del Modelo (MCP)](../05-mcp/README.md) +**Siguiente módulo:** [05-mcp - Protocolo de Contexto de Modelo (MCP)](../05-mcp/README.md) --- @@ -383,5 +383,5 @@ En la práctica, muchos sistemas de producción combinan ambos enfoques: RAG par **Descargo de responsabilidad**: -Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automáticas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional realizada por humanos. No nos responsabilizamos por malentendidos o interpretaciones erróneas derivadas del uso de esta traducción. +Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción. \ No newline at end of file diff --git a/translations/es/README.md b/translations/es/README.md index 218092738..aad61a237 100644 --- a/translations/es/README.md +++ b/translations/es/README.md @@ -9,11 +9,11 @@ Un curso para construir aplicaciones de IA con LangChain4j y Azure OpenAI GPT-5. #### Soportado vía GitHub Action (Automatizado y Siempre Actualizado) -[Árabe](../ar/README.md) | [Bengalí](../bn/README.md) | [Búlgaro](../bg/README.md) | [Birmano (Myanmar)](../my/README.md) | [Chino (Simplificado)](../zh-CN/README.md) | [Chino (Tradicional, Hong Kong)](../zh-HK/README.md) | [Chino (Tradicional, Macao)](../zh-MO/README.md) | [Chino (Tradicional, Taiwán)](../zh-TW/README.md) | [Croata](../hr/README.md) | [Checo](../cs/README.md) | [Danés](../da/README.md) | [Neerlandés](../nl/README.md) | [Estonio](../et/README.md) | [Finés](../fi/README.md) | [Francés](../fr/README.md) | [Alemán](../de/README.md) | [Griego](../el/README.md) | [Hebreo](../he/README.md) | [Hindi](../hi/README.md) | [Húngaro](../hu/README.md) | [Indonesio](../id/README.md) | [Italiano](../it/README.md) | [Japonés](../ja/README.md) | [Kannada](../kn/README.md) | [Jemer](../km/README.md) | [Coreano](../ko/README.md) | [Lituano](../lt/README.md) | [Malayo](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalí](../ne/README.md) | [Pidgin Nigeriano](../pcm/README.md) | [Noruego](../no/README.md) | [Persa (Farsi)](../fa/README.md) | [Polaco](../pl/README.md) | [Portugués (Brasil)](../pt-BR/README.md) | [Portugués (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Rumano](../ro/README.md) | [Ruso](../ru/README.md) | [Serbio (Cirílico)](../sr/README.md) | [Eslovaco](../sk/README.md) | [Esloveno](../sl/README.md) | [Español](./README.md) | [Suajili](../sw/README.md) | [Sueco](../sv/README.md) | [Tagalo (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Tailandés](../th/README.md) | [Turco](../tr/README.md) | [Ucraniano](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamita](../vi/README.md) +[Árabe](../ar/README.md) | [Bengalí](../bn/README.md) | [Búlgaro](../bg/README.md) | [Birmano (Myanmar)](../my/README.md) | [Chino (Simplificado)](../zh-CN/README.md) | [Chino (Tradicional, Hong Kong)](../zh-HK/README.md) | [Chino (Tradicional, Macao)](../zh-MO/README.md) | [Chino (Tradicional, Taiwán)](../zh-TW/README.md) | [Croata](../hr/README.md) | [Checo](../cs/README.md) | [Danés](../da/README.md) | [Holandés](../nl/README.md) | [Estonio](../et/README.md) | [Finlandés](../fi/README.md) | [Francés](../fr/README.md) | [Alemán](../de/README.md) | [Griego](../el/README.md) | [Hebreo](../he/README.md) | [Hindi](../hi/README.md) | [Húngaro](../hu/README.md) | [Indonesio](../id/README.md) | [Italiano](../it/README.md) | [Japonés](../ja/README.md) | [Canarés](../kn/README.md) | [Jemer](../km/README.md) | [Coreano](../ko/README.md) | [Lituano](../lt/README.md) | [Malayo](../ms/README.md) | [Malayalam](../ml/README.md) | [Maratí](../mr/README.md) | [Nepalí](../ne/README.md) | [Pidgin Nigeriano](../pcm/README.md) | [Noruego](../no/README.md) | [Persa (Farsi)](../fa/README.md) | [Polaco](../pl/README.md) | [Portugués (Brasil)](../pt-BR/README.md) | [Portugués (Portugal)](../pt-PT/README.md) | [Panyabí (Gurmukhi)](../pa/README.md) | [Rumano](../ro/README.md) | [Ruso](../ru/README.md) | [Serbio (Cirílico)](../sr/README.md) | [Eslovaco](../sk/README.md) | [Esloveno](../sl/README.md) | [Español](./README.md) | [Swahili](../sw/README.md) | [Sueco](../sv/README.md) | [Tagalo (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Tailandés](../th/README.md) | [Turco](../tr/README.md) | [Ucraniano](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamita](../vi/README.md) > **¿Prefieres Clonar Localmente?** > -> Este repositorio incluye más de 50 traducciones de idiomas que aumentan significativamente el tamaño de la descarga. Para clonar sin traducciones, usa la extracción parcial: +> Este repositorio incluye traducciones en más de 50 idiomas, lo que aumenta significativamente el tamaño de la descarga. Para clonar sin traducciones, usa la extracción parcial: > > **Bash / macOS / Linux:** > ```bash @@ -29,21 +29,20 @@ Un curso para construir aplicaciones de IA con LangChain4j y Azure OpenAI GPT-5. > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Esto te da todo lo necesario para completar el curso con una descarga mucho más rápida. +> Esto te proporciona todo lo necesario para completar el curso con una descarga mucho más rápida. ## Tabla de Contenidos -1. [Inicio Rápido](00-quick-start/README.md) - Comienza con LangChain4j -2. [Introducción](01-introduction/README.md) - Aprende los fundamentos de LangChain4j -3. [Ingeniería de Prompts](02-prompt-engineering/README.md) - Domina el diseño efectivo de prompts -4. [RAG (Generación Aumentada con Recuperación)](03-rag/README.md) - Construye sistemas inteligentes basados en conocimiento -5. [Herramientas](04-tools/README.md) - Integra herramientas externas y asistentes simples -6. [MCP (Protocolo de Contexto de Modelo)](05-mcp/README.md) - Trabaja con el Protocolo de Contexto de Modelo (MCP) y módulos agentes +1. [Introducción](01-introduction/README.md) - Aprende los fundamentos de LangChain4j +2. [Ingeniería de Prompts](02-prompt-engineering/README.md) - Domina el diseño efectivo de prompts +3. [RAG (Generación Aumentada por Recuperación)](03-rag/README.md) - Construye sistemas inteligentes basados en conocimiento +4. [Herramientas](04-tools/README.md) - Integra herramientas externas y asistentes simples +5. [MCP (Protocolo de Contexto del Modelo)](05-mcp/README.md) - Trabaja con el Protocolo de Contexto del Modelo (MCP) y módulos Agénticos -### Recorridos en Video +### Videos Explicativos -Cada módulo tiene una sesión en vivo complementaria donde exploramos los conceptos y el código paso a paso. +Cada módulo tiene una sesión en vivo acompañante donde repasamos los conceptos y el código paso a paso. | Módulo | Video | |--------|-------| @@ -54,34 +53,34 @@ Cada módulo tiene una sesión en vivo complementaria donde exploramos los conce --- -## Ruta de Aprendizaje +## Ruta de Aprendizaje **¿Nuevo en LangChain4j?** Consulta el [Glosario](docs/GLOSSARY.md) para definiciones de términos y conceptos clave. > **Inicio Rápido** -1. Haz un fork de este repositorio en tu cuenta de GitHub +1. Haz un fork de este repositorio a tu cuenta de GitHub 2. Haz clic en **Code** → pestaña **Codespaces** → **...** → **Nuevo con opciones...** 3. Usa los valores predeterminados – esto seleccionará el contenedor de Desarrollo creado para este curso 4. Haz clic en **Crear codespace** 5. Espera 5-10 minutos para que el entorno esté listo -6. Ve directamente a [Inicio Rápido](./00-quick-start/README.md) para comenzar! +6. Ve directamente a [Introducción](./01-introduction/README.md) para comenzar -Después de completar los módulos, explora la [Guía de Pruebas](docs/TESTING.md) para ver conceptos de prueba de LangChain4j en acción. +Después de completar los módulos, explora la [Guía de Testing](docs/TESTING.md) para ver los conceptos de testing de LangChain4j en acción. -> **Nota:** Esta capacitación utiliza tanto GitHub Models como Azure OpenAI. El módulo [Inicio Rápido](00-quick-start/README.md) usa GitHub Models (no se requiere suscripción a Azure), mientras que los módulos 1-5 usan Azure OpenAI. Comienza con una [cuenta gratuita de Azure](https://aka.ms/azure-free-account) si no tienes una. +> **Nota:** Esta capacitación usa Azure OpenAI. Comienza con una [cuenta Azure GRATIS](https://aka.ms/azure-free-account) si no tienes una. -## Aprendiendo con GitHub Copilot +## Aprendizaje con GitHub Copilot -Para empezar a programar rápido, abre este proyecto en un GitHub Codespace o en tu IDE local con el devcontainer provisto. El devcontainer usado en este curso viene preconfigurado con GitHub Copilot para programación asistida por IA. +Para comenzar a programar rápidamente, abre este proyecto en un GitHub Codespace o en tu IDE local con el devcontainer proporcionado. El devcontainer usado en este curso viene preconfigurado con GitHub Copilot para programación asistida por IA. -Cada ejemplo de código incluye preguntas sugeridas que puedes hacerle a GitHub Copilot para profundizar en tu comprensión. Busca los prompt 💡/🤖 en: +Cada ejemplo de código incluye preguntas sugeridas que puedes hacerle a GitHub Copilot para profundizar tu comprensión. Busca los prompts 💡/🤖 en: - **Encabezados de archivos Java** - Preguntas específicas para cada ejemplo -- **README de los módulos** - Preguntas para explorar tras los ejemplos de código +- **READMEs de los módulos** - Prompts de exploración después de ejemplos de código -**Cómo usarlo:** Abre cualquier archivo de código y haz a Copilot las preguntas sugeridas. Tiene contexto completo del código y puede explicar, extender y sugerir alternativas. +**Cómo usar:** Abre cualquier archivo de código y hazle a Copilot las preguntas sugeridas. Tiene contexto completo del código y puede explicar, extender y sugerir alternativas. ¿Quieres aprender más? Consulta [Copilot para Programación Asistida por IA](https://aka.ms/GitHubCopilotAI). @@ -111,32 +110,33 @@ Cada ejemplo de código incluye preguntas sugeridas que puedes hacerle a GitHub --- -### Aprendizaje Central +### Aprendizaje Básico [![ML para Principiantes](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Ciencia de Datos para Principiantes](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![IA para Principiantes](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Ciberseguridad para Principiantes](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Desarrollo Web para Principiantes](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT para Principiantes](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![Desarrollo XR para Principiantes](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Serie Copilot -[![Copilot para Programación en Pareja con IA](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot para C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Aventura Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## Obtener Ayuda +## Obtener ayuda Si te quedas atascado o tienes alguna pregunta sobre cómo crear aplicaciones de IA, únete a: -[![Discord de Microsoft Foundry](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) +[![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Si tienes comentarios sobre el producto o errores mientras desarrollas, visita: +Si tienes comentarios sobre el producto o errores mientras construyes, visita: -[![Foro de Desarrolladores de Microsoft Foundry](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) +[![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licencia @@ -145,6 +145,6 @@ Licencia MIT - Consulta el archivo [LICENSE](../../LICENSE) para más detalles. --- -**Descargo de responsabilidad**: -Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automáticas pueden contener errores o imprecisiones. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda la traducción profesional realizada por humanos. No nos hacemos responsables de ningún malentendido o interpretación errónea derivada del uso de esta traducción. +**Descargo de responsabilidad**: +Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción. \ No newline at end of file diff --git a/translations/es/docs/GLOSSARY.md b/translations/es/docs/GLOSSARY.md index 0889093be..4d5a85dee 100644 --- a/translations/es/docs/GLOSSARY.md +++ b/translations/es/docs/GLOSSARY.md @@ -1,44 +1,44 @@ -# Glosario de LangChain4j +# Glosario LangChain4j ## Tabla de Contenidos -- [Conceptos Básicos](../../../docs) -- [Componentes de LangChain4j](../../../docs) -- [Conceptos de IA/ML](../../../docs) -- [Guardrails](../../../docs) -- [Ingeniería de Prompts](../../../docs) -- [RAG (Generación Aumentada con Recuperación)](../../../docs) -- [Agentes y Herramientas](../../../docs) -- [Módulo Agente](../../../docs) -- [Protocolo de Contexto de Modelo (MCP)](../../../docs) -- [Servicios de Azure](../../../docs) -- [Pruebas y Desarrollo](../../../docs) +- [Conceptos Fundamentales](#conceptos-fundamentales) +- [Componentes de LangChain4j](#componentes-de-langchain4j) +- [Conceptos de IA/ML](#conceptos-de-iaml) +- [Guardarraíles](#guardarraíles) +- [Ingeniería de Prompts](#prompt-engineering---module-02) +- [RAG (Generación Aumentada por Recuperación)](#rag-retrieval-augmented-generation---module-03) +- [Agentes y Herramientas](#agents-and-tools---module-04) +- [Módulo Agéntico](#agentic-module---module-05) +- [Protocolo de Contexto de Modelo (MCP)](#model-context-protocol-mcp---module-05) +- [Servicios de Azure](#azure-services---module-01) +- [Pruebas y Desarrollo](#testing-and-development---testing-guide) -Referencia rápida de términos y conceptos utilizados en todo el curso. +Referencia rápida para términos y conceptos usados a lo largo del curso. -## Conceptos Básicos +## Conceptos Fundamentales **Agente de IA** - Sistema que usa IA para razonar y actuar de forma autónoma. [Módulo 04](../04-tools/README.md) **Cadena** - Secuencia de operaciones donde la salida alimenta el siguiente paso. -**Fragmentación** - Dividir documentos en partes más pequeñas. Típico: 300-500 tokens con solapamiento. [Módulo 03](../03-rag/README.md) +**Segmentación** - Dividir documentos en partes más pequeñas. Típico: 300-500 tokens con superposición. [Módulo 03](../03-rag/README.md) -**Ventana de Contexto** - Máximo de tokens que un modelo puede procesar. GPT-5.2: 400K tokens (hasta 272K entrada, 128K salida). +**Ventana de Contexto** - Máximo de tokens que un modelo puede procesar. GPT-5.2: 400K tokens (hasta 272K de entrada, 128K de salida). **Embeddings** - Vectores numéricos que representan el significado del texto. [Módulo 03](../03-rag/README.md) -**Llamada de Función** - Modelo genera solicitudes estructuradas para llamar a funciones externas. [Módulo 04](../04-tools/README.md) +**Llamada a Función** - El modelo genera solicitudes estructuradas para llamar funciones externas. [Módulo 04](../04-tools/README.md) **Alucinación** - Cuando los modelos generan información incorrecta pero plausible. -**Prompt** - Entrada de texto para un modelo de lenguaje. [Módulo 02](../02-prompt-engineering/README.md) +**Prompt** - Texto de entrada para un modelo de lenguaje. [Módulo 02](../02-prompt-engineering/README.md) -**Búsqueda Semántica** - Búsqueda por significado usando embeddings, no por palabras clave. [Módulo 03](../03-rag/README.md) +**Búsqueda Semántica** - Búsqueda por significado usando embeddings, no palabras clave. [Módulo 03](../03-rag/README.md) -**Con estado vs Sin estado** - Sin estado: sin memoria. Con estado: mantiene historial de conversación. [Módulo 01](../01-introduction/README.md) +**Con Estado vs Sin Estado** - Sin estado: sin memoria. Con estado: mantiene historial de conversación. [Módulo 01](../01-introduction/README.md) -**Tokens** - Unidades básicas de texto que los modelos procesan. Afecta costos y límites. [Módulo 01](../01-introduction/README.md) +**Tokens** - Unidades básicas de texto que procesan los modelos. Afecta costos y límites. [Módulo 01](../01-introduction/README.md) **Encadenamiento de Herramientas** - Ejecución secuencial de herramientas donde la salida informa la siguiente llamada. [Módulo 04](../04-tools/README.md) @@ -48,13 +48,13 @@ Referencia rápida de términos y conceptos utilizados en todo el curso. **OpenAiOfficialChatModel** - Cliente unificado para modelos OpenAI y Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Crea embeddings usando el cliente oficial de OpenAI (soporta OpenAI y Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Crea embeddings usando el cliente Oficial OpenAI (compatible con OpenAI y Azure OpenAI). **ChatModel** - Interfaz principal para modelos de lenguaje. -**ChatMemory** - Mantiene el historial de conversación. +**ChatMemory** - Mantiene historial de conversación. -**ContentRetriever** - Encuentra fragmentos relevantes de documentos para RAG. +**ContentRetriever** - Encuentra fragmentos de documentos relevantes para RAG. **DocumentSplitter** - Divide documentos en fragmentos. @@ -62,67 +62,67 @@ Referencia rápida de términos y conceptos utilizados en todo el curso. **EmbeddingStore** - Almacena y recupera embeddings. -**MessageWindowChatMemory** - Mantiene ventana deslizante de mensajes recientes. +**MessageWindowChatMemory** - Mantiene ventana móvil de mensajes recientes. -**PromptTemplate** - Crea prompts reutilizables con marcadores `{{variable}}`. +**PromptTemplate** - Crea prompts reutilizables con marcadores de posición `{{variable}}`. **TextSegment** - Fragmento de texto con metadatos. Usado en RAG. -**ToolExecutionRequest** - Representa la solicitud de ejecución de una herramienta. +**ToolExecutionRequest** - Representa solicitud de ejecución de herramienta. -**UserMessage / AiMessage / SystemMessage** - Tipos de mensajes en conversación. +**UserMessage / AiMessage / SystemMessage** - Tipos de mensajes de conversación. ## Conceptos de IA/ML -**Aprendizaje con pocos ejemplos** - Proveer ejemplos en los prompts. [Módulo 02](../02-prompt-engineering/README.md) +**Aprendizaje con Pocos Ejemplos** - Proveer ejemplos en los prompts. [Módulo 02](../02-prompt-engineering/README.md) -**Modelo de Lenguaje Grande (LLM)** - Modelos AI entrenados con grandes cantidades de texto. +**Modelo de Lenguaje Grande (LLM)** - Modelos IA entrenados con grandes conjuntos de texto. -**Esfuerzo de Razonamiento** - Parámetro GPT-5.2 que controla la profundidad del razonamiento. [Módulo 02](../02-prompt-engineering/README.md) +**Esfuerzo de Razonamiento** - Parámetro GPT-5.2 que controla la profundidad del pensamiento. [Módulo 02](../02-prompt-engineering/README.md) **Temperatura** - Controla la aleatoriedad de la salida. Bajo=determinista, alto=creativo. **Base de Datos Vectorial** - Base de datos especializada para embeddings. [Módulo 03](../03-rag/README.md) -**Aprendizaje sin ejemplos** - Realizar tareas sin ejemplos previos. [Módulo 02](../02-prompt-engineering/README.md) +**Aprendizaje Zero-Shot** - Ejecutar tareas sin ejemplos. [Módulo 02](../02-prompt-engineering/README.md) -## Guardrails - [Módulo 00](../00-quick-start/README.md) +## Guardarraíles -**Defensa en Profundidad** - Enfoque de seguridad multicapa que combina guardrails a nivel de aplicación con filtros de seguridad del proveedor. +**Defensa en Profundidad** - Enfoque de seguridad por capas que combina guardarraíles a nivel de aplicación con filtros de seguridad del proveedor. -**Bloqueo Duro** - El proveedor lanza error HTTP 400 por violaciones graves de contenido. +**Bloqueo Estricto** - El proveedor lanza error HTTP 400 para violaciones severas de contenido. -**InputGuardrail** - Interfaz de LangChain4j para validar la entrada del usuario antes de que llegue al LLM. Ahorra costo y latencia bloqueando prompts dañinos de forma temprana. +**InputGuardrail** - Interfaz LangChain4j para validar entrada del usuario antes de llegar al LLM. Ahorra costo y latencia bloqueando prompts dañinos temprano. -**InputGuardrailResult** - Tipo de retorno para validación guardrail: `success()` o `fatal("razón")`. +**InputGuardrailResult** - Tipo de retorno para validación de guardarraíl: `success()` o `fatal("razón")`. -**OutputGuardrail** - Interfaz para validar respuestas AI antes de devolverlas a usuarios. +**OutputGuardrail** - Interfaz para validar respuestas de IA antes de devolverlas a usuarios. -**Filtros de Seguridad del Proveedor** - Filtros de contenido incorporados de proveedores AI (p. ej., GitHub Models) que detectan violaciones a nivel API. +**Filtros de Seguridad del Proveedor** - Filtros integrados de contenido de proveedores IA (ej. Azure OpenAI) que detectan violaciones en el nivel API. -**Rechazo Suave** - El modelo se niega educadamente a responder sin lanzar error. +**Rechazo Suave** - El modelo se niega cortésmente a responder sin generar error. ## Ingeniería de Prompts - [Módulo 02](../02-prompt-engineering/README.md) -**Cadena de Pensamiento** - Razonamiento paso a paso para mejor precisión. +**Cadena de Pensamiento** - Razonamiento paso a paso para mayor precisión. -**Salida Restringida** - Imposición de formato o estructura específica. +**Salida Restringida** - Imponer formato o estructura específica. -**Alta Disposición** - Patrón GPT-5.2 para razonamiento minucioso. +**Alta Motivación** - Patrón GPT-5.2 para razonamiento profundo. -**Baja Disposición** - Patrón GPT-5.2 para respuestas rápidas. +**Baja Motivación** - Patrón GPT-5.2 para respuestas rápidas. -**Conversación Multi-Turno** - Mantener contexto a lo largo de intercambios. +**Conversación Multi-Turno** - Mantener contexto en intercambios sucesivos. -**Prompts Basados en Rol** - Establecer persona del modelo vía mensajes del sistema. +**Prompt basado en Roles** - Configurar la persona del modelo via mensajes del sistema. -**Autorreflexión** - El modelo evalúa y mejora su propia salida. +**Autorreflexión** - El modelo evalúa y mejora su salida. **Análisis Estructurado** - Marco fijo de evaluación. -**Patrón de Ejecución de Tareas** - Planificar → Ejecutar → Resumir. +**Patrón de Ejecución de Tarea** - Planificar → Ejecutar → Resumir. -## RAG (Generación Aumentada con Recuperación) - [Módulo 03](../03-rag/README.md) +## RAG (Generación Aumentada por Recuperación) - [Módulo 03](../03-rag/README.md) **Pipeline de Procesamiento de Documentos** - Cargar → fragmentar → embeber → almacenar. @@ -130,65 +130,65 @@ Referencia rápida de términos y conceptos utilizados en todo el curso. **RAG** - Combina recuperación con generación para fundamentar respuestas. -**Puntuación de Similitud** - Medida (0-1) de similitud semántica. +**Puntaje de Similaridad** - Medida (0-1) de similitud semántica. **Referencia de Fuente** - Metadatos sobre contenido recuperado. ## Agentes y Herramientas - [Módulo 04](../04-tools/README.md) -**Anotación @Tool** - Marca métodos Java como herramientas accesibles para IA. +**Anotación @Tool** - Marca métodos Java como herramientas invocables por IA. **Patrón ReAct** - Razonar → Actuar → Observar → Repetir. -**Gestión de Sesiones** - Contextos separados para usuarios diferentes. +**Gestión de Sesiones** - Contextos separados para diferentes usuarios. -**Herramienta** - Función que un agente de IA puede llamar. +**Herramienta** - Función que un agente IA puede invocar. -**Descripción de Herramienta** - Documentación del propósito y parámetros de la herramienta. +**Descripción de Herramienta** - Documentación del propósito y parámetros de herramienta. -## Módulo Agente - [Módulo 05](../05-mcp/README.md) +## Módulo Agéntico - [Módulo 05](../05-mcp/README.md) -**Anotación @Agent** - Marca interfaces como agentes AI con definición declarativa de comportamiento. +**Anotación @Agent** - Marca interfaces como agentes IA con definición declarativa de comportamiento. -**Agent Listener** - Hook para monitorear ejecución del agente vía `beforeAgentInvocation()` y `afterAgentInvocation()`. +**Agent Listener** - Gancho para monitorear ejecución de agente vía `beforeAgentInvocation()` y `afterAgentInvocation()`. -**Alcance Agente** - Memoria compartida donde agentes almacenan salidas usando `outputKey` para que otros agentes las consuman. +**Alcance Agéntico** - Memoria compartida donde agentes almacenan salidas usando `outputKey` para que agentes posteriores consuman. -**AgenticServices** - Factoría para crear agentes usando `agentBuilder()` y `supervisorBuilder()`. +**AgenticServices** - Fábrica para crear agentes usando `agentBuilder()` y `supervisorBuilder()`. -**Flujo Condicional** - Ruta basada en condiciones hacia diferentes agentes especialistas. +**Flujo Condicional** - Ruta basada en condiciones hacia distintos agentes especialistas. -**Humano en el Bucle** - Patrón de flujo que añade puntos de aprobación o revisión de contenido humana. +**Humano en el Bucle** - Patrón de flujo añadiendo puntos de control humanos para aprobación o revisión de contenido. **langchain4j-agentic** - Dependencia Maven para construcción declarativa de agentes (experimental). -**Flujo en Bucle** - Iterar ejecución de agente hasta que se cumpla condición (p. ej., puntuación de calidad ≥ 0.8). +**Flujo en Bucle** - Iterar ejecución de agente hasta que se cumpla condición (ej. puntaje de calidad ≥ 0.8). -**outputKey** - Parámetro de anotación de agente que especifica dónde se guardan resultados en Alcance Agente. +**outputKey** - Parámetro de anotación de agente que especifica dónde se almacenan resultados en Alcance Agéntico. **Flujo Paralelo** - Ejecutar múltiples agentes simultáneamente para tareas independientes. -**Estrategia de Respuesta** - Cómo el supervisor formula la respuesta final: LAST, SUMMARY o SCORED. +**Estrategia de Respuesta** - Cómo el supervisor formula la respuesta final: ÚLTIMA, RESUMEN, o CON PUNTAJE. **Flujo Secuencial** - Ejecutar agentes en orden donde la salida fluye al siguiente paso. -**Patrón de Agente Supervisor** - Patrón agente avanzado donde un LLM supervisor decide dinámicamente qué sub-agentes invocar. +**Patrón Agente Supervisor** - Patrón agéntico avanzado donde un supervisor LLM decide dinámicamente qué subagentes invocar. ## Protocolo de Contexto de Modelo (MCP) - [Módulo 05](../05-mcp/README.md) **langchain4j-mcp** - Dependencia Maven para integración MCP en LangChain4j. -**MCP** - Protocolo de Contexto de Modelo: estándar para conectar apps AI con herramientas externas. Construir una vez, usar en todas partes. +**MCP** - Protocolo de Contexto de Modelo: estándar para conectar apps IA a herramientas externas. Crear una vez, usar en todas partes. **Cliente MCP** - Aplicación que se conecta a servidores MCP para descubrir y usar herramientas. **Servidor MCP** - Servicio que expone herramientas vía MCP con descripciones claras y esquemas de parámetros. -**McpToolProvider** - Componente LangChain4j que envuelve herramientas MCP para uso en servicios AI y agentes. +**McpToolProvider** - Componente LangChain4j que envuelve herramientas MCP para usar en servicios AI y agentes. **McpTransport** - Interfaz para comunicación MCP. Implementaciones incluyen Stdio y HTTP. -**Transporte Stdio** - Transporte de proceso local vía stdin/stdout. Útil para acceso a sistema de archivos o herramientas línea de comandos. +**Transporte Stdio** - Transporte por proceso local vía stdin/stdout. Útil para acceso a sistema de archivos o herramientas de línea de comandos. **StdioMcpTransport** - Implementación LangChain4j que lanza servidor MCP como subproceso. @@ -198,35 +198,33 @@ Referencia rápida de términos y conceptos utilizados en todo el curso. **Azure AI Search** - Búsqueda en la nube con capacidades vectoriales. [Módulo 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Despliega recursos de Azure. +**Azure Developer CLI (azd)** - Despliega recursos Azure. -**Azure OpenAI** - Servicio AI empresarial de Microsoft. +**Azure OpenAI** - Servicio de IA empresarial de Microsoft. **Bicep** - Lenguaje de infraestructura como código para Azure. [Guía de Infraestructura](../01-introduction/infra/README.md) -**Nombre de Despliegue** - Nombre para despliegue de modelo en Azure. +**Nombre de Despliegue** - Nombre para el despliegue del modelo en Azure. **GPT-5.2** - Último modelo OpenAI con control de razonamiento. [Módulo 02](../02-prompt-engineering/README.md) ## Pruebas y Desarrollo - [Guía de Pruebas](TESTING.md) -**Dev Container** - Entorno de desarrollo conteinerizado. [Configuración](../../../.devcontainer/devcontainer.json) - -**GitHub Models** - Área de pruebas AI gratuita. [Módulo 00](../00-quick-start/README.md) +**Contenedor Dev** - Entorno de desarrollo en contenedor. [Configuración](../../../.devcontainer/devcontainer.json) **Pruebas en Memoria** - Pruebas con almacenamiento en memoria. **Pruebas de Integración** - Pruebas con infraestructura real. -**Maven** - Herramienta de automatización de construcción Java. +**Maven** - Herramienta de automatización de compilación para Java. -**Mockito** - Framework Java para mocks. +**Mockito** - Framework de simulación para Java. **Spring Boot** - Framework de aplicaciones Java. [Módulo 01](../01-introduction/README.md) --- -**Aviso legal**: -Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automáticas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda la traducción profesional realizada por humanos. No nos hacemos responsables de cualquier malentendido o interpretación errónea derivada del uso de esta traducción. +**Descargo de responsabilidad**: +Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción. \ No newline at end of file diff --git a/translations/es/docs/TESTING.md b/translations/es/docs/TESTING.md index 83b2804f7..0f4188ed7 100644 --- a/translations/es/docs/TESTING.md +++ b/translations/es/docs/TESTING.md @@ -2,15 +2,15 @@ ## Tabla de Contenidos -- [Inicio Rápido](../../../docs) -- [Qué Cubren las Pruebas](../../../docs) -- [Ejecutar las Pruebas](../../../docs) -- [Ejecutar Pruebas en VS Code](../../../docs) -- [Patrones de Prueba](../../../docs) -- [Filosofía de Pruebas](../../../docs) -- [Próximos Pasos](../../../docs) +- [Inicio Rápido](#inicio-rápido) +- [Qué Cubren las Pruebas](#qué-cubren-las-pruebas) +- [Ejecutando las Pruebas](#ejecutando-las-pruebas) +- [Ejecutando Pruebas en VS Code](#ejecutando-pruebas-en-vs-code) +- [Patrones de Prueba](#patrones-de-prueba) +- [Filosofía de Pruebas](#filosofía-de-pruebas) +- [Próximos Pasos](#próximos-pasos) -Esta guía te lleva a través de las pruebas que demuestran cómo probar aplicaciones de IA sin requerir claves API ni servicios externos. +Esta guía te lleva a través de las pruebas que demuestran cómo probar aplicaciones de IA sin requerir claves de API o servicios externos. ## Inicio Rápido @@ -26,11 +26,11 @@ mvn test mvn --% test ``` -Cuando todas las pruebas pasen, deberías ver una salida como la captura de pantalla a continuación — pruebas ejecutadas con cero fallos. +Cuando todas las pruebas pasen, deberías ver una salida como la captura de pantalla a continuación — pruebas ejecutadas sin fallos. -Resultados Exitosos de Pruebas +Resultados Exitosos de la Prueba -*Ejecución exitosa de pruebas mostrando todas las pruebas pasando sin fallos* +*Ejecución exitosa de pruebas mostrando todas las pruebas aprobadas sin fallos* ## Qué Cubren las Pruebas @@ -38,20 +38,19 @@ Este curso se enfoca en **pruebas unitarias** que se ejecutan localmente. Cada p Pirámide de Pruebas -*Pirámide de pruebas mostrando el balance entre pruebas unitarias (rápidas, aisladas), pruebas de integración (componentes reales) y pruebas end-to-end. Esta capacitación cubre pruebas unitarias.* +*Pirámide de pruebas mostrando el equilibrio entre pruebas unitarias (rápidas, aisladas), pruebas de integración (componentes reales) y pruebas de extremo a extremo. Esta capacitación cubre pruebas unitarias.* | Módulo | Pruebas | Enfoque | Archivos Clave | |--------|---------|---------|----------------| -| **00 - Inicio Rápido** | 6 | Plantillas de prompts y sustitución de variables | `SimpleQuickStartTest.java` | | **01 - Introducción** | 8 | Memoria de conversación y chat con estado | `SimpleConversationTest.java` | -| **02 - Ingeniería de Prompts** | 12 | Patrones GPT-5.2, niveles de eagerness, salida estructurada | `SimpleGpt5PromptTest.java` | +| **02 - Ingeniería de Prompts** | 12 | Patrones GPT-5.2, niveles de entusiasmo, salida estructurada | `SimpleGpt5PromptTest.java` | | **03 - RAG** | 10 | Ingesta de documentos, embeddings, búsqueda por similitud | `DocumentServiceTest.java` | | **04 - Herramientas** | 12 | Llamado de funciones y encadenamiento de herramientas | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Protocolo de Contexto de Modelo con transporte stdio | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | Protocolo de Contexto de Modelo con transporte Stdio | `SimpleMcpTest.java` | -## Ejecutar las Pruebas +## Ejecutando las Pruebas -**Ejecutar todas las pruebas desde la raíz:** +**Ejecuta todas las pruebas desde la raíz:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Ejecutar pruebas para un módulo específico:** +**Ejecuta pruebas para un módulo específico:** **Bash:** ```bash @@ -75,11 +74,11 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# O desde raíz +# O desde la raíz mvn --% test -pl 01-introduction ``` -**Ejecutar una sola clase de prueba:** +**Ejecuta una clase de prueba individual:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Ejecutar un método de prueba específico:** +**Ejecuta un método de prueba específico:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#deberíaMantenerHistorialDeConversación +mvn test -Dtest=SimpleConversationTest#deberíaMantenerElHistorialDeConversación ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#deberíaMantenerHistorialDeConversación +mvn --% test -Dtest=SimpleConversationTest#deberíaMantenerElHistorialDeConversación ``` -## Ejecutar Pruebas en VS Code +## Ejecutando Pruebas en VS Code -Si usas Visual Studio Code, el Explorador de Pruebas ofrece una interfaz gráfica para ejecutar y depurar pruebas. +Si usas Visual Studio Code, el Explorador de Pruebas proporciona una interfaz gráfica para ejecutar y depurar pruebas. -Explorador de Pruebas VS Code +Explorador de Pruebas de VS Code -*Explorador de Pruebas de VS Code mostrando el árbol de pruebas con todas las clases de prueba Java y métodos individuales de prueba* +*Explorador de Pruebas de VS Code mostrando el árbol de pruebas con todas las clases Java y métodos de prueba individuales* **Para ejecutar pruebas en VS Code:** -1. Abre el Explorador de Pruebas haciendo clic en el ícono de matraz en la Barra de Actividades -2. Expande el árbol de pruebas para ver todos los módulos y clases de prueba -3. Haz clic en el botón de reproducir junto a cualquier prueba para ejecutarla individualmente -4. Haz clic en "Run All Tests" para ejecutar todo el conjunto -5. Haz clic derecho en cualquier prueba y selecciona "Debug Test" para establecer puntos de ruptura y depurar el código +1. Abre el Explorador de Pruebas haciendo clic en el icono de matraz en la Barra de Actividades +2. Expande el árbol de pruebas para ver todos los módulos y clases de prueba +3. Haz clic en el botón de reproducir junto a cualquier prueba para ejecutarla individualmente +4. Haz clic en "Ejecutar Todas las Pruebas" para ejecutar toda la suite +5. Haz clic derecho en cualquier prueba y selecciona "Depurar Prueba" para establecer puntos de interrupción y avanzar por el código -El Explorador de Pruebas muestra marcas verdes para las pruebas que pasan y provee mensajes detallados de fallo cuando las pruebas fallan. +El Explorador de Pruebas muestra marcas verdes para las pruebas exitosas y proporciona mensajes detallados de fallos cuando las pruebas fallan. ## Patrones de Prueba -### Patrón 1: Prueba de Plantillas de Prompt +### Patrón 1: Probar Plantillas de Prompt -El patrón más simple prueba plantillas de prompts sin llamar a ningún modelo de IA. Verificas que la sustitución de variables funcione correctamente y que los prompts estén formateados como se espera. +El patrón más simple prueba plantillas de prompt sin llamar a ningún modelo de IA. Verificas que la sustitución de variables funcione correctamente y que los prompts estén formateados como se espera. -Prueba de Plantilla de Prompt +Prueba de Plantillas de Prompt -*Pruebas de plantillas de prompt mostrando el flujo de sustitución de variables: plantilla con marcadores → valores aplicados → salida formateada verificada* +*Pruebas de plantillas de prompt mostrando flujo de sustitución de variables: plantilla con marcadores → se aplican valores → salida formateada verificada* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Esta prueba vive en `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Ejecutarla:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#formatoDePlantillaDeSolicitudDePrueba -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#pruebaDeFormatoDePlantillaDeSolicitud -``` +Este patrón verifica que la sustitución de variables funcione correctamente y que los prompts estén formateados como se espera — no se requiere clave API ni llamada al modelo. -### Patrón 2: Mocking de Modelos de Lenguaje +### Patrón 2: Simulación de Modelos de Lenguaje Al probar la lógica de conversación, usa Mockito para crear modelos falsos que devuelven respuestas predeterminadas. Esto hace que las pruebas sean rápidas, gratuitas y deterministas. Comparación Mock vs API Real -*Comparación mostrando por qué se prefieren mocks para pruebas: son rápidos, gratuitos, deterministas y no requieren claves API* +*Comparación que muestra por qué se prefieren las simulaciones para pruebas: son rápidas, gratuitas, deterministas y no requieren claves API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Este patrón aparece en `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. El mock asegura un comportamiento consistente para que puedas verificar que la gestión de memoria funcione correctamente. +Este patrón aparece en `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. El mock asegura un comportamiento consistente para que puedas verificar que la gestión de la memoria funcione correctamente. ### Patrón 3: Prueba de Aislamiento de Conversación -La memoria de conversación debe mantener usuarios múltiples separados. Esta prueba verifica que las conversaciones no mezclen contextos. +La memoria de conversación debe mantener separados a múltiples usuarios. Esta prueba verifica que las conversaciones no mezclen contextos. Aislamiento de Conversación -*Prueba de aislamiento de conversación mostrando almacenes de memoria separados para diferentes usuarios para evitar mezcla de contexto* +*Prueba de aislamiento de conversación mostrando memorias separadas para diferentes usuarios para evitar mezcla de contextos* ```java @Test @@ -252,13 +239,13 @@ void shouldIsolateConversationsByid() { Cada conversación mantiene su propio historial independiente. En sistemas de producción, este aislamiento es crítico para aplicaciones multiusuario. -### Patrón 4: Prueba Independiente de Herramientas +### Patrón 4: Probar Herramientas Independientemente -Las herramientas son funciones que la IA puede llamar. Pruébalas directamente para asegurar que funcionen correctamente independientemente de las decisiones de la IA. +Las herramientas son funciones que la IA puede llamar. Prúebalas directamente para asegurar que funcionen correctamente independientemente de las decisiones de la IA. Pruebas de Herramientas -*Pruebas independientes de herramientas mostrando ejecución de herramienta mock sin llamadas a IA para verificar lógica de negocio* +*Pruebas de herramientas independientemente mostrando ejecución simulado de herramientas sin llamadas a IA para verificar la lógica empresarial* ```java @Test @@ -285,7 +272,7 @@ Estas pruebas de `04-tools/src/test/java/com/example/langchain4j/agents/tools/Si ### Patrón 5: Prueba RAG en Memoria -Los sistemas RAG tradicionalmente requieren bases de datos vectoriales y servicios de embedding. El patrón en memoria te permite probar toda la tubería sin dependencias externas. +Los sistemas RAG tradicionalmente requieren bases de datos vectoriales y servicios de embeddings. El patrón en memoria te permite probar todo el pipeline sin dependencias externas. Prueba RAG en Memoria @@ -306,7 +293,7 @@ void testProcessTextDocument() { } ``` -Esta prueba de `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` crea un documento en memoria y verifica la fragmentación y manejo de metadatos. +Esta prueba de `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` crea un documento en memoria y verifica la segmentación y manejo de metadatos. ### Patrón 6: Pruebas de Integración MCP @@ -314,7 +301,7 @@ El módulo MCP prueba la integración del Protocolo de Contexto de Modelo usando Las pruebas en `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validan el comportamiento del cliente MCP. -**Ejecutarlas:** +**Ejecuta las pruebas:** **Bash:** ```bash @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Filosofía de Pruebas -Prueba tu código, no la IA. Tus pruebas deben validar el código que escribes verificando cómo se construyen los prompts, cómo se maneja la memoria y cómo se ejecutan las herramientas. Las respuestas de IA varían y no deberían formar parte de las aserciones de las pruebas. Pregúntate si tu plantilla de prompt sustituye variables correctamente, no si la IA da la respuesta correcta. +Prueba tu código, no la IA. Tus pruebas deberían validar el código que escribes verificando cómo se construyen los prompts, cómo se gestiona la memoria y cómo se ejecutan las herramientas. Las respuestas de IA varían y no deberían formar parte de las aserciones de prueba. Pregúntate si tu plantilla de prompt sustituye variables correctamente, no si la IA da la respuesta correcta. -Usa mocks para los modelos de lenguaje. Son dependencias externas que son lentas, costosas y no deterministas. Mockear hace las pruebas rápidas con milisegundos en lugar de segundos, gratuitas sin costos de API y deterministas con el mismo resultado cada vez. +Usa mocks para los modelos de lenguaje. Son dependencias externas lentas, costosas y no deterministas. Simularlas hace que las pruebas sean rápidas con tiempos en milisegundos en lugar de segundos, gratuitas sin costos de API y deterministas con el mismo resultado cada vez. -Mantén las pruebas independientes. Cada prueba debe configurar sus propios datos, no depender de otras pruebas y limpiarse a sí misma. Las pruebas deben pasar sin importar el orden de ejecución. +Mantén las pruebas independientes. Cada prueba debe configurar sus propios datos, no depender de otras pruebas y limpiar después de sí misma. Las pruebas deben pasar sin importar el orden de ejecución. -Prueba casos límite más allá del camino feliz. Prueba entradas vacías, entradas muy grandes, caracteres especiales, parámetros inválidos y condiciones de límite. Estos a menudo revelan errores que el uso normal no expone. +Prueba casos límite más allá del camino feliz. Intenta entradas vacías, entradas muy grandes, caracteres especiales, parámetros inválidos y condiciones de frontera. Estos casos a menudo revelan errores que el uso normal no expone. -Usa nombres descriptivos. Compara `shouldMaintainConversationHistoryAcrossMultipleMessages()` con `test1()`. El primero te dice exactamente qué se está probando, haciendo que depurar fallos sea mucho más fácil. +Usa nombres descriptivos. Compara `shouldMaintainConversationHistoryAcrossMultipleMessages()` con `test1()`. El primero te dice exactamente qué se está probando, haciendo la depuración mucho más sencilla. ## Próximos Pasos Ahora que entiendes los patrones de prueba, profundiza en cada módulo: -- **[00 - Inicio Rápido](../00-quick-start/README.md)** - Comienza con lo básico de plantillas de prompt -- **[01 - Introducción](../01-introduction/README.md)** - Aprende gestión de memoria de conversación -- **[02 - Ingeniería de Prompts](../02-prompt-engineering/README.md)** - Domina patrones de prompting GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Construye sistemas de generación aumentada por recuperación -- **[04 - Herramientas](../04-tools/README.md)** - Implementa llamadas a funciones y cadenas de herramientas -- **[05 - MCP](../05-mcp/README.md)** - Integra Protocolo de Contexto de Modelo +- **[01 - Introducción](../01-introduction/README.md)** - Aprende gestión de memoria de conversación +- **[02 - Ingeniería de Prompts](../02-prompt-engineering/README.md)** - Domina los patrones de prompting GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Construye sistemas de generación aumentada con recuperación +- **[04 - Herramientas](../04-tools/README.md)** - Implementa llamadas a funciones y cadenas de herramientas +- **[05 - MCP](../05-mcp/README.md)** - Integra el Protocolo de Contexto de Modelo -Los README de cada módulo proveen explicaciones detalladas de los conceptos aquí probados. +El README de cada módulo ofrece explicaciones detalladas de los conceptos probados aquí. --- -**Navegación:** [← Volver al Principal](../README.md) +**Navegación:** [← Volver al Inicio](../README.md) --- -**Aviso legal**: -Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la exactitud, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda la traducción profesional realizada por humanos. No nos hacemos responsables de ningún malentendido o interpretación errónea que surja del uso de esta traducción. +**Descargo de responsabilidad**: +Este documento ha sido traducido utilizando el servicio de traducción automática [Co-op Translator](https://github.com/Azure/co-op-translator). Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción. \ No newline at end of file diff --git a/translations/et/.co-op-translator.json b/translations/et/.co-op-translator.json index 644fb7114..16fca6d41 100644 --- a/translations/et/.co-op-translator.json +++ b/translations/et/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "et" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T22:07:03+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T09:15:44+00:00", "source_file": "01-introduction/README.md", "language_code": "et" }, @@ -18,20 +18,20 @@ "language_code": "et" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T22:09:08+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T09:11:18+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "et" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T22:10:29+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T09:14:49+00:00", "source_file": "03-rag/README.md", "language_code": "et" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:28:29+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T09:13:35+00:00", "source_file": "04-tools/README.md", "language_code": "et" }, @@ -54,8 +54,8 @@ "language_code": "et" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:59:40+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T09:09:52+00:00", "source_file": "README.md", "language_code": "et" }, @@ -72,14 +72,14 @@ "language_code": "et" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T22:13:35+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T09:11:52+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "et" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T22:14:17+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T09:12:26+00:00", "source_file": "docs/TESTING.md", "language_code": "et" } diff --git a/translations/et/00-quick-start/README.md b/translations/et/00-quick-start/README.md deleted file mode 100644 index 8a0d0a3e4..000000000 --- a/translations/et/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Moodul 00: Kiire algus - -## Sisukord - -- [Sissejuhatus](../../../00-quick-start) -- [Mis on LangChain4j?](../../../00-quick-start) -- [LangChain4j sõltuvused](../../../00-quick-start) -- [Eeltingimused](../../../00-quick-start) -- [Seadistamine](../../../00-quick-start) - - [1. Hangi oma GitHubi token](../../../00-quick-start) - - [2. Määra oma token](../../../00-quick-start) -- [Näidete käivitamine](../../../00-quick-start) - - [1. Põhiline vestlus](../../../00-quick-start) - - [2. Käskude mustrid](../../../00-quick-start) - - [3. Funktsioonikõned](../../../00-quick-start) - - [4. Dokumentide küsimused ja vastused (Lihtne RAG)](../../../00-quick-start) - - [5. Vastutustundlik tehisintellekt](../../../00-quick-start) -- [Mida iga näide näitab](../../../00-quick-start) -- [Järgmised sammud](../../../00-quick-start) -- [Probleemide lahendamine](../../../00-quick-start) - -## Sissejuhatus - -See kiire algus on mõeldud selleks, et saaksid LangChain4j-ga võimalikult kiiresti tööd alustada. See käsitleb AI-rakenduste ehitamise absoluutseid põhialuseid LangChain4j ja GitHubi mudelitega. Järgmistes moodulites lähed üle Azure OpenAI ja GPT-5.2 kasutamisele ning süüvid iga kontseptsiooni sügavamalt. - -## Mis on LangChain4j? - -LangChain4j on Java teek, mis lihtsustab AI-põhiste rakenduste loomist. HTTP klientide ja JSON parsimisega tegelemise asemel töötad puhaste Java API-dega. - -"Chain" LangChainis viitab mitme komponendi aheldamisele – võid näiteks ühendada käsku mudeliga, seejärel parseriga või ühendada mitmeid AI-kõnesid, kus üks väljund on järgmise sisend. See kiire algus keskendub aluspõhimõtetele, enne kui uurida keerukamaid ahelaid. - -LangChain4j Chaining Concept - -*Ahelate ühendamine LangChain4j-s – ehitusplokid ühenduvad võimsate AI töövoogude loomiseks* - -Kasutame kolme põhikomponenti: - -**ChatModel** – Liides AI mudeliga suhtlemiseks. Kutsu `model.chat("prompt")` ja saa vastuseks tekst. Kasutame `OpenAiOfficialChatModel`-i, mis töötab OpenAI-ga ühilduvate lõpp-punktidega nagu GitHub Models. - -**AiServices** – Loob tüübiturvalisi AI teenuste liideseid. Määra meetodid, märgista neid `@Tool`-iga ja LangChain4j korraldab ülejäänu. AI kutsub automaatselt vajadusel sinu Java meetodeid. - -**MessageWindowChatMemory** – Säilitab vestlusajaloo. Ilma selleta on iga päring iseseisev, sellega mäletab AI eelnevaid sõnumeid ja hoiab konteksti mitme pöörde vältel. - -LangChain4j Architecture - -*LangChain4j arhitektuur – põhikomponendid töötavad koos, et võimendada sinu AI-rakendusi* - -## LangChain4j sõltuvused - -See kiire algus kasutab kolme Maven sõltuvust failis [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` moodul pakub `OpenAiOfficialChatModel` klassi, mis ühendub OpenAI-ga ühilduvate API-dega. GitHub Models kasutab sama API vormingut, nii et eraldi adapterit ei ole vaja — piisas suunamisest baas-URL-iga `https://models.github.ai/inference`. - -`langchain4j-easy-rag` moodul pakub automaatset dokumentide jagamist, sisestamist ja päringut, et saaksid ehitada RAG-rakendusi ilma iga sammu käsitsi seadistamiseta. - -## Eeltingimused - -**Kas kasutad arenduscontainerit?** Java ja Maven on juba installitud. Sul on vaja vaid GitHubi isiklikku juurdepääsutokenit. - -**Kohalik arendus:** -- Java 21 või uuem, Maven 3.9 või uuem -- GitHubi isiklik juurdepääsutoken (juhised allpool) - -> **Märkus:** See moodul kasutab GitHub Models-ist mudelit `gpt-4.1-nano`. Ära muuda koodis mudelinime – see on seadistatud töötama GitHubi saadaolevate mudelitega. - -## Seadistamine - -### 1. Hangi oma GitHubi token - -1. Mine lehele [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Vali "Generate new token" -3. Sea kirjeldav nimi (nt "LangChain4j Demo") -4. Sea aegumine (soovitavalt 7 päeva) -5. "Account permissions" alt leia "Models" ja sea "Read-only" -6. Kliki "Generate token" -7. Kopeeri ja salvesta oma token – seda enam ei kuvata - -### 2. Määra oma token - -**Variant 1: Kasutades VS Code'i (Soovitatav)** - -Kui kasutad VS Code'i, lisa oma token projekti juurkataloogi faili `.env`: - -Kui `.env` faili pole, kopeeri `.env.example` failist `.env` või loo uus `.env` fail projekti juurkausta. - -**Näide `.env` failist:** -```bash -# Kaustas /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Seejärel võid lihtsalt paremklõpsata mis tahes demo failil (nt `BasicChatDemo.java`) Exploreris ja valida **"Run Java"** või kasutada Run and Debug paneeli käivitustingimusi. - -**Variant 2: Kasutades terminali** - -Sea token keskkonnamuutujana: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Näidete käivitamine - -**Kui kasutad VS Code'i:** Paremklõpsa lihtsalt mis tahes demo failil Exploreris ja vali **"Run Java"** või kasuta Run and Debug paneeli käivitustingimusi (veendu, et token on esmalt lisatud `.env` faili). - -**Kui kasutad Mavenit:** Võid kasutada ka käsurida: - -### 1. Põhiline vestlus - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Käskude mustrid - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Näitab zero-shot, few-shot, chain-of-thought ja rollipõhiseid käske. - -### 3. Funktsioonikõned - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI kutsub automaatselt sinu Java meetodeid vajadusel. - -### 4. Dokumentide küsimused ja vastused (Lihtne RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Esita dokumentide kohta küsimusi, kasutades Easy RAG-i automaatse sisestuse ja otsinguga. - -### 5. Vastutustundlik tehisintellekt - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Vaata, kuidas AI turvafiltrid blokeerivad kahjuliku sisu. - -## Mida iga näide näitab - -**Põhiline vestlus** – [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Alusta siit, et näha LangChain4j lihtsaimat kasutust. Lood `OpenAiOfficialChatModel`-i, saadad päringu `.chat()` meetodi kaudu ja saad vastuse. See näitab alustalasid: kuidas algatada mudeleid kohandatud lõpp-punktide ja API võtmetega. Kui sellest mustrist aru saad, ehitub kõik muu sellele peale. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat abil:** Ava [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) ja küsi: -> - "Kuidas ma selle koodiga GitHub Models-ist Azure OpenAI-le üle läheksin?" -> - "Milliseid muid parameetreid saan seadistada OpenAiOfficialChatModel.builder() meetodis?" -> - "Kuidas lisada voogedastusega vastuseid selle asemel, et oodata täielikku vastust?" - -**Käskude inseneritöö** – [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Nüüd kui tead, kuidas mudeliga rääkida, uurime, mida talle öelda. See demo kasutab sama mudeli seadistust, kuid näitab viit erinevat käskude mustrit. Proovi zero-shot käske otseste juhistena, few-shot skeeme näidete põhjal õppimiseks, chain-of-thought mustrit, mis paljastab mõttekäigu samme, ja rollipõhiseid käske, mis määravad konteksti. Näed, kuidas sama mudel annab väga erinevaid tulemusi, olenevalt sellest, kuidas päringu vormistad. - -Demo demonstreerib ka käskude malle (prompt templates), mis on võimas viis korduvkasutatavate käsu mallide loomiseks muutujatega. -Alljärgnev näide kasutab LangChain4j `PromptTemplate`-d muutujate täitmiseks. AI vastab sihtkoha ja tegevuse põhjal. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat abil:** Ava [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) ja küsi: -> - "Mis vahe on zero-shot ja few-shot käsustamisel, millal kumbagi kasutada?" -> - "Kuidas mõjutab mudeli vastuseid temperatuuriparameeter?" -> - "Milliseid võtteid kasutada, et vältida käskude süstimist tootmises?" -> - "Kuidas luua korduvkasutatavaid PromptTemplate objekte tavaliste mustrite jaoks?" - -**Tööriistade integratsioon** – [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Siin muutub LangChain4j võimsaks. Kasutad `AiServices`-t AI assistendi loomiseks, mis kutsub sinu Java meetodeid. Märgista meetodid `@Tool("kirjeldus")` annotatsiooniga ja LangChain4j korraldab ülejäänu – AI otsustab automaatselt, millal ja millist tööriista kasutada vastavalt kasutaja päringule. See demonstreerib funktsioonikõnesid, mis on võtmetehnika AI jaoks, mis suudab tegutseda, mitte ainult vastata. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat abil:** Ava [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ja küsi: -> - "Kuidas @Tool annotatsioon töötab ja mida LangChain4j sellega taga teeb?" -> - "Kas AI saab mitut tööriista järjest kutsuda keerukate probleemide lahendamiseks?" -> - "Mis juhtub, kui tööriist viskab vea – kuidas peaksin vead käsitlema?" -> - "Kuidas integreerida päris API selle kalkulaatori näite asemel?" - -**Dokumentide küsimused ja vastused (Lihtne RAG)** – [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Siin näed RAG-i (otsingupõhine generaator) kasutamist LangChain4j “Easy RAG” lähenemisega. Dokumendid laaditakse, automaatselt jagatakse ja sisestatakse mällu, seejärel päringut tegeva AI jaoks tarnitakse asjakohased tükid küsimuse ajal. AI vastab dokumentide põhjal, mitte oma üldise teadmiste põhjal. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat abil:** Ava [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) ja küsi: -> - "Kuidas RAG hoiab ära AI hallutsinatsioone võrreldes mudeli treeningandmete kasutamisega?" -> - "Mis vahe on selle lihtsa lähenemise ja kohandatud RAG torustiku vahel?" -> - "Kuidas skaleerida seda mitme dokumendi või suurema teadmistebaasi jaoks?" - -**Vastutustundlik tehisintellekt** – [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Ehita AI turvalisus mitme kaitsetasemega. See demo näitab kahte kaitsest kihti, mis töötavad koos: - -**Osa 1: LangChain4j sisendi kontroll** – Blokeerib ohtlikud käsud enne LLM-ile jõudmist. Loo kohandatud reeglid, mis otsivad keelatud märksõnu või mustreid. Need töötavad koodis kiirelt ja tasuta. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Osa 2: Teenusepakkuja turvafiltrid** – GitHub Models-il on sisseehitatud filtrid, mis püüavad kinni, mida su kontrollid võivad vahele jätta. Näed ranget blokeerimist (HTTP 400 vead) tõsiste rikkumiste korral ja pehmet keeldumist, kus AI viisakalt keelduv vastus annab. - -> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat abil:** Ava [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) ja küsi: -> - "Mis on InputGuardrail ja kuidas luua oma?" -> - "Mis vahe on rangel blokeerimisel ja pehmel keelamisel?" -> - "Miks kasutada korraga nii reegleid kui teenusepakkuja filtreid?" - -## Järgmised sammud - -**Järgmine moodul:** [01-introduction - LangChain4j kasutuselevõtt](../01-introduction/README.md) - ---- - -**Navigeerimine:** [← Tagasi peamisele](../README.md) | [Järgmine: Moodul 01 - Sissejuhatus →](../01-introduction/README.md) - ---- - -## Probleemide lahendamine - -### Esimene Maven ehitus - -**Tõrge:** Esimene `mvn clean compile` või `mvn package` võtab kaua aega (10-15 minutit) - -**Põhjus:** Maven peab laadima alla kõik projekti sõltuvused (Spring Boot, LangChain4j teegid, Azure SDK-d jne) esimesel ehitusel. - -**Lahendus:** See on normaalne käitumine. Järgmised ehitused on palju kiirem, kuna sõltuvused on lokaalselt vahemällu salvestatud. Allalaadimise aeg sõltub teie võrgu kiirusest. - -### PowerShelli Maven käsu sünktaks - -**Tõrge:** Maven käsk ebaõnnestub veaga `Unknown lifecycle phase ".mainClass=..."` -**Põhjus**: PowerShell tõlgendab `=` kui muutuja määramise operaatorit, mis rikub Maven omaduste süntaksit - -**Lahendus**: Kasuta peatamis-parsimise operaatorit `--%` enne Maven käsku: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operaator `--%` käsib PowerShellil edastada kõik järelejäänud argumendid Mavenile kirjapandult, tõlgendamata neid. - -### Windows PowerShell emojide kuvamine - -**Probleem**: AI vastused kuvavad PowerShellis emotikonide asemel segasemaid märke (nt `????` või `â??`) - -**Põhjus**: PowerShelli vaikimisi kodeering ei toeta UTF-8 emotikone - -**Lahendus**: Käivita see käsk enne Java rakenduste käivitamist: -```cmd -chcp 65001 -``` - -See sunnib terminali kasutama UTF-8 kodeeringut. Alternatiivina kasuta Windows Terminali, mis toetab paremini Unicode'i. - -### API kutsete silumine - -**Probleem**: Autentimisvead, kiirusepiirangud või ootamatud vastused AI mudelilt - -**Lahendus**: Näidetes on `.logRequests(true)` ja `.logResponses(true)`, et kuvada API kutseid konsoolis. See aitab lahendada autentimisvigu, kiirusepiiranguid või ootamatuid vastuseid. Eemalda need lipud tootmiskeskkonnas, et vähendada logi müra. - ---- - - -**Sissetõmbumine**: -See dokument on tõlgitud kasutades tehisintellektil põhinevat tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi me püüame täpsust tagada, tuleb arvestada, et automaatsed tõlked võivad sisaldada vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Tähtsa teabe korral soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlke kasutamisest tekkivate arusaamatuste või valemonumuste eest. - \ No newline at end of file diff --git a/translations/et/01-introduction/README.md b/translations/et/01-introduction/README.md index 49b505178..423880d4f 100644 --- a/translations/et/01-introduction/README.md +++ b/translations/et/01-introduction/README.md @@ -2,86 +2,86 @@ ## Sisukord -- [Video juhendamine](../../../01-introduction) -- [Mida sa õpid](../../../01-introduction) -- [Eeltingimused](../../../01-introduction) -- [Põhiprobleemi mõistmine](../../../01-introduction) -- [Tokonite mõistmine](../../../01-introduction) -- [Kuidas mälu töötab](../../../01-introduction) -- [Kuidas see kasutab LangChain4j](../../../01-introduction) -- [Deploy Azure OpenAI infrastruktuur](../../../01-introduction) -- [Rakenduse käivitamine lokaalselt](../../../01-introduction) -- [Rakenduse kasutamine](../../../01-introduction) - - [Seisunditu vestlus (vasak paneel)](../../../01-introduction) - - [Seisundiga vestlus (parem paneel)](../../../01-introduction) -- [Järgmised sammud](../../../01-introduction) +- [Video juhendamine](#video-juhendamine) +- [Mida sa õpid](#mida-sa-õpid) +- [Eeltingimused](#eltingimused) +- [Tuumaprobleemi mõistmine](#tuumaprobleemi-mõistmine) +- [Tokenite mõistmine](#tokenite-mõistmine) +- [Kuidas mälu töötab](#kuidas-mälu-tööt) +- [Kuidas see kasutab LangChain4j](#kuidas-see-kasutab-langchain4j) +- [Azure OpenAI infrastruktuuri juurutamine](#azure-openai-infrastruktuuri-juurutamine) +- [Rakenduse lokaalne käitamine](#rakenduse-lokaalne-käitamine) +- [Rakenduse kasutamine](#rakenduse-kasutamine) + - [Stateless vestlus (vasak paneel)](#stateless-vestlus-vasak-paneel) + - [Stateful vestlus (parem paneel)](#stateful-vestlus-parem-paneel) +- [Järgmised sammud](#järgmised-sammud) ## Video juhendamine -Vaata seda otseülekande salvestust, mis selgitab, kuidas selle mooduliga alustada: +Vaata seda otseülekannet, mis selgitab, kuidas selle mooduliga alustada: Getting Started with LangChain4j - Live Session ## Mida sa õpid -Kiirlahenduses kasutasid GitHubi mudeleid, et saata päringuid, kutsuda tööriistu, ehitada RAG-torustikku ja testida turvameetmeid. Need demo'd näitasid, mis on võimalik — nüüd liigume üle Azure OpenAI ja GPT-5.2 peale ning hakkame ehitama tootmistasemel rakendusi. See moodul keskendub dialoogipõhisele tehisintellektile, mis mäletab konteksti ja hoiab seisundit — need on mõisted, mida kiirlahenduse demo'd taustal kasutasid, kuid ei selgitanud. +See on sinu lähtepunkt LangChain4j ja Azure OpenAI kasutamiseks. Alustame põhialustest ja hakkame looma tootmistasemel rakendusi. See moodul keskendub vestluslikule tehisintellektile, mis mäletab konteksti ja hoiab olekut — need on põhikontseptsioonid, millele kõik hilisemad moodulid tuginevad. -Kogu juhendis kasutame Azure OpenAI GPT-5.2 mudelit, kuna selle täiustatud mõtlemisvõime teeb erinevate mustrite käitumise paremini nähtavaks. Mälu lisamisel näed selgelt erinevust. See muudab lihtsamaks mõista, mida iga komponent sinu rakendusele lisab. +Selles juhendis kasutame kogu aeg Azure OpenAI GPT-5.2, sest selle arenenud mõtlemisvõimed muudavad erinevate mustrite käitumise selgemaks. Kui lisad mälu, näed vahet selgelt. See lihtsustab mõistmist, mida iga komponent sinu rakendusele annab. Sa ehitad ühe rakenduse, mis demonstreerib mõlemat mustrit: -**Seisunditu vestlus** - Iga päring on iseseisev. Mudelil puudub mälu eelnevate sõnumite kohta. See on see mustrilahendus, mida kasutasid kiirlahenduses. +**Stateless vestlus** – iga päring on iseseisev. Mudelil puudub mälu varasemate sõnumite kohta. See on kõige lihtsam lähtepunkt. -**Seisundiga vestlus** - Iga päring sisaldab vestluse ajalugu. Mudel hoiab konteksti mitme vahetuse ulatuses. Selle nõuavad tootmisrakendused. +**Stateful vestlus** – iga päring sisaldab vestluse ajalugu. Mudel hoiab konteksti mitme vahetuse vältel. Seda nõuavad tootmisrakendused. ## Eeltingimused - Azure tellimus koos Azure OpenAI ligipääsuga -- Java 21, Maven 3.9+ +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Märkus:** Java, Maven, Azure CLI ja Azure Developer CLI (azd) on eelinstalleeritud pakutud devcontaineris. +> **Märkus:** Java, Maven, Azure CLI ja Azure Developer CLI (azd) on kaasas eeltöödeldud arendus konteineris. -> **Märkus:** See moodul kasutab GPT-5.2 Azure OpenAI-st. Deploy konfiguratsioon toimub automaatselt `azd up` kaudu — ära muuda mudeli nime koodis. +> **Märkus:** See moodul kasutab GPT-5.2 Azure OpenAI platvormil. Juurutamine on automaatselt konfigureeritud `azd up` käsuga — ärge muutke mudeli nime koodis. -## Põhiprobleemi mõistmine +## Tuumaprobleemi mõistmine -Keelemudelid on seisunditud. Iga API kõne on iseseisev. Kui sa saadad "Minu nimi on John" ja siis küsid "Mis on minu nimi?", mudelil pole aimugi, et sa just end tutvustasid. Ta käsitleb iga päringut nagu esimese vestlusena, mis sul kunagi olnud on. +Keelemudelid on olekuta. Iga API-päring on iseseisev. Kui sa saadad "Minu nimi on John" ja seejärel küsid "Mis mu nimi on?", siis mudel ei tea, et sa just ennast tutvustasid. Ta käsitleb iga päringut, nagu see oleks sinu esimene vestlus üldse. -See sobib lihtsatele küsimustele ja vastustele, kuid on päris rakendustes kasutuskõlbmatu. Klienditeenindusbotid peavad mäletama, mida neile öeldi. Isiklikud assistendid vajavad konteksti. Igas mitme vahetusega vestluses on mälu vajalik. +See sobib lihtsate küsimuste-vastuste jaoks, aga pole kasulik pärisrakendusteks. Klienditeeninduse botid peavad meeles pidama, mida sa neile rääkisid. Isiklikud assistendid vajavad konteksti. Iga mitmevahetuseline vestlus nõuab mälu. -Järgnev diagramm võrdleb kahte lähenemist — vasakul seisunditu kõne, kes unustab su nime; paremal seisundiga kõne, mida toetab ChatMemory ja mis mäletab seda. +Järgmine diagramm näitab kahte lähenemist – vasakul olekuta kõne, mis unustab su nime; paremal olekuga kõne ChatMemory taustal, mis su nime mäletab. Stateless vs Stateful Conversations -*Vahe seisunditu (iseseisvad kõned) ja seisundiga (kontekstiteadlikud) vestluste vahel* +*Vahe olekuteta (iseseisvad kõned) ja olekuga (konteksti tundvad) vestluste vahel* -## Tokonite mõistmine +## Tokenite mõistmine -Enne vestlustesse süvenemist on oluline mõista tokeneid – põhilisi tekstiplokke, mida keelemudelid töötlevad: +Enne vestlustesse sukeldumist on oluline mõista tokeneid – põhielemendid tekstist, mida keelemudelid töötlevad: Token Explanation -*Näide, kuidas tekst lagundatakse tokeniteks – "I love AI!" jaguneb neljaks eraldi töötlemise ühikuks* +*Näide, kuidas tekst jaotatakse tokeniteks – "I love AI!" muutub neljaks eraldi töötlemisühikuks* -Tokendid on see, kuidas tehisintellekt mudelid mõõdavad ja töötlevad teksti. Sõnad, kirjavahemärgid ja isegi tühikud võivad olla token'iteks. Sinu mudelil on piir, kui palju tokeneid ta korraga suudab töödelda (GPT-5.2 puhul 400 000, seesama jaotatuna kuni 272 000 sisendtokeniks ja 128 000 väljundtokeniks). Tokonite mõistmine aitab sul hallata vestluse pikkust ja kulusid. +Tokenid on see, kuidas tehisintellekt mudelid mõõdavad ja töötlevad teksti. Sõnad, kirjavahemärgid ja isegi tühikud võivad olla tokenid. Sinu mudelil on piirates, mitu tokenit ta korraga suudab töödelda (400 000 GPT-5.2 puhul, kuni 272 000 sisendtokenit ja 128 000 väljundtokenit). Tokenite mõistmine aitab vestluse pikkust ja kulusid paremini hallata. ## Kuidas mälu töötab -Vestluse mälu lahendab seisunditu probleemi, säilitades vestluse ajaloo. Enne, kui päring mudelile saadetakse, lisab raamistik ette asjakohased varasemad sõnumid. Kui sa küsid "Mis on mu nimi?", saadab süsteem tegelikult kogu vestluse ajaloo, mis võimaldab mudelil näha, et sa eespool ütlesid "Minu nimi on John". +Vestluse mälu lahendab olekuta probleemi, hoides vestluse ajaloo meeles. Enne kui saadad mudelile päringu, lisab raamistik vastavad varasemad sõnumid ette. Kui sa küsid "Mis mu nimi on?", saadab süsteem kogu vestluse ajaloo, mis võimaldab mudelil näha, et sa ütlesid "Minu nimi on John". -LangChain4j pakub mälu teostusi, mis teevad seda automaatselt. Sa valid, kui palju sõnumeid säilitada, ja raamistik haldab konteksti akent. Allolev diagramm näitab, kuidas MessageWindowChatMemory haldab liugakent viimaste sõnumite jaoks. +LangChain4j pakub mälulahendusi, mis teevad seda automaatselt. Sa valid, mitu sõnumit hoida ja raamistik haldab konteksti akent. Allolev diagramm näitab, kuidas MessageWindowChatMemory hoiab libisevat akent viimaste sõnumite jaoks. Memory Window Concept -*MessageWindowChatMemory hoiab liugakent viimaste sõnumite jaoks, automaatselt vanu välja visates* +*MessageWindowChatMemory hoiab libisevat akent viimaste sõnumite jaoks ja viskab automaatselt välja vanad* ## Kuidas see kasutab LangChain4j -See moodul laiendab kiirlahendust, integreerides Spring Boot'i ja lisades vestluse mälu. Siin on kuidas komponendid kokku sobivad: +See moodul integreerib Spring Booti ja lisab vestlusmälusüsteemi. Nii sobituvad komponendid kokku: -**Sõltuvused** - Lisa kaks LangChain4j teeki: +**Sõltuvused** – lisa kaks LangChain4j teeki: ```xml @@ -94,7 +94,7 @@ See moodul laiendab kiirlahendust, integreerides Spring Boot'i ja lisades vestlu ``` -**Vestlusmudel** - Konfigureeri Azure OpenAI Spring bean'ina ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Vestlusmudel** – konfigureeri Azure OpenAI Spring bean-ina ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder loeb tõestust andmed keskkonnamuutujatest, mida seab `azd up`. `baseUrl` seadmine sinu Azure lõpp-punktile muudab OpenAI kliendi töövõimeliseks Azure OpenAI-ga. +Builder loeb mandaadid keskkonnamuutujatest, mis on seadistatud `azd up` poolt. `baseUrl` seadmine oma Azure lõpp-punkti suunab OpenAI kliendi Azure OpenAI teenusele. -**Vestluse mälu** - Jälgi vestluse ajalugu MessageWindowChatMemory abil ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Vestluse mälu** – hoia vestluse ajalugu MessageWindowChatMemory abil ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,16 +124,16 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Loo mälu `withMaxMessages(10)` abil, et hoida viimased 10 sõnumit. Lisa kasutaja ja AI sõnumid tüübitud mähistega: `UserMessage.from(text)` ja `AiMessage.from(text)`. Ajalugu taasta `memory.messages()` abil ja saada mudelile. Teenus salvestab eraldi mälu eksemplarid iga vestluse ID jaoks, võimaldades mitmel kasutajal korraga vestelda. +Loo mälu `withMaxMessages(10)`-ga, et hoida viimast 10 sõnumit. Lisa kasutaja ja AI sõnumid tüübitud wrapperitega: `UserMessage.from(text)` ja `AiMessage.from(text)`. Tõmba ajalugu `memory.messages()` abil ja saada see mudelile. Teenus salvestab iga vestluse ID kohta eraldi mälukopsu, võimaldades mitmel kasutajal vestelda samaaegselt. -> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat'iga:** Ava [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ja küsi: -> - "Kuidas MessageWindowChatMemory otsustab, millised sõnumid akna täitumisel välja visata?" -> - "Kas ma saan rakendada kohandatud mälu salvestamist, kasutades andmebaasi mälus hoidmise asemel?" -> - "Kuidas ma lisaksin vanade vestluste ajaloo kokkuvõtmise?" +> **🤖 Proovi koos [GitHub Copilot](https://github.com/features/copilot) vestlusega:** Ava [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ja küsi: +> - "Kuidas otsustab MessageWindowChatMemory, milliseid sõnumeid eemaldada, kui aken on täis?" +> - "Kas ma saan implementerida kohandatud mälusalvestust andmebaasi abil, mitte ainult mälus?" +> - "Kuidas lisada kokkuvõtete tegemist vana vestluse ajaloo tihendamiseks?" -Seisunditu vestluse lõpp-punkt jätab mälu täielikult vahele — lihtne `chatModel.chat(prompt)` nagu kiirlahenduses. Seisundiga lõpp-punkt lisab sõnumid mällu, taasesitab ajaloo ja kaasab selle konteksti iga päringuga. Sama mudeli seadistus, erinevad mustrid. +Stateless vestluse lõpp-punkt jätab mälusüsteemi vahele — lihtsalt `chatModel.chat(prompt)` nagu kiire algus. Stateful lõpp-punkt lisab sõnumid mällu, tõmbab ajaloo ja lisab selle konteksti iga päringu juurde. Sama mudeli konfiguratsioon, erinevad mustrid. -## Deploy Azure OpenAI infrastruktuur +## Azure OpenAI infrastruktuuri juurutamine **Bash:** ```bash @@ -147,28 +147,28 @@ cd 01-introduction azd up # Valige tellimus ja asukoht (soovitatav on eastus2) ``` -> **Märkus:** Kui kohtad ajapiirangu tõrget (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), käivita lihtsalt uuesti `azd up`. Azure ressursid võivad taustal hetkel seadistamisel olla ja korduskatse võimaldab deploy lõpule viia, kui ressursid jõuavad lõplikku olekusse. +> **Märkus:** Kui saad veateate aja ületamise kohta (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), lihtsalt käivita uuesti `azd up`. Azure ressursid võivad veel taustal juurutamisel olla ja taaskäivitamine lubab juurutusel lõpule jõuda, kui ressursid jõuavad lõppseisundisse. -See sooritab: -1. Deploy Azure OpenAI ressurss GPT-5.2 ja text-embedding-3-small mudelitega -2. Automaatse `.env` faili genereerimise projekti juurkausta koos tõestust andmetega -3. Kõik vajalike keskkonnamuutujate seadistamise +See teeb järgmist: +1. Juurutab Azure OpenAI ressursi koos GPT-5.2 ja text-embedding-3-small mudelitega +2. Genereerib automaatselt projekti juurkausta `.env` faili mandaadiga +3. Seadistab kõik vajalikud keskkonnamuutujad -**Kui esineb deploy probleeme?** Vaata [Infrastructure README](infra/README.md), kus on põhjalik tõrkeotsing, sealhulgas alamdomeeni nime konfliktid, käsitsi Azure Portali deploy sammud ja mudeli seadistamise juhised. +**Kas on probleeme juurutamisega?** Loe [Infrastruktuuri README-st](infra/README.md), kus on detailne tõrkeotsing, sealhulgas alamdomeeni nime konfliktid, käsitsi Azure Portaali juurutamise juhised ja mudeli konfigureerimine. -**Veendu, et deploy õnnestus:** +**Kontrolli, kas juurutamine õnnestus:** **Bash:** ```bash -cat ../.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY jms. +cat ../.env # Peaks kuvama AZURE_OPENAI_ENDPOINT, API_KEY jms. ``` **PowerShell:** ```powershell -Get-Content ..\.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY jms. +Get-Content ..\.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY jt. ``` -> **Märkus:** `azd up` käsu käivitamine genereerib automaatselt `.env` faili. Kui vajad hiljem uuendamist, võid kas käsitsi `.env` faili muuta või uuesti genereerida, käivitades: +> **Märkus:** `azd up` käsk genereerib `.env` faili automaatselt. Kui vajad hiljem selle uuendamist, võid kas muuta `.env` faili käsitsi või genereerida selle uuesti käivitades: > > **Bash:** > ```bash @@ -182,15 +182,15 @@ Get-Content ..\.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY jms. > .\.azd-env.ps1 > ``` -## Rakenduse lokaal käivitamine +## Rakenduse lokaalne käitamine -**Veendu deploy õnnestumises:** +**Kontrolli juurutamist:** -Veendu, et `.env` fail asub juurkaustas koos Azure tõestust andmetega. Käivita see mooduli kaustast (`01-introduction/`): +Veendu, et `.env` fail on olemas juurkataloogis koos Azure mandaadiga. Käivita see mooduli kataloogist (`01-introduction/`): **Bash:** ```bash -cat ../.env # Tuleks näidata AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -198,37 +198,37 @@ cat ../.env # Tuleks näidata AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Alusta rakendusi:** +**Käivita rakendused:** -**Variant 1: Kasutades Spring Boot Dashboardi (Soovitatav VS Code kasutajatele)** +**Variant 1: Spring Boot Dashboardi kasutamine (soovitatav VS Code kasutajatele)** -Dev container sisaldab Spring Boot Dashboard laiendust, mis pakub visuaalset liidest, et hallata kõiki Spring Boot rakendusi. Leiad selle VS Code vasakpoolsest Activity Bar-ist (otsi Spring Boot ikooni). +Arenduskonteiner sisaldab Spring Boot Dashboard laiendust, mis pakub visuaalset liidest kõigi Spring Boot rakenduste haldamiseks. Selle leiad vasaku külje tegevusribalt VS Code's (otsi Spring Boot ikooni). -Spring Boot Dashboardilt saad: -- Näha kõiki saadaval olevaid Spring Boot rakendusi töökohas -- Alustada/peatada rakendusi ühe klikiga +Spring Boot Dashboardist saad: +- Näha kõiki tööalal olevaid Spring Boot rakendusi +- Käivitada/peatada rakendusi ühe klikiga - Vaadata rakenduse logisid reaalajas - Jälgida rakenduse olekut -Lihtsalt kliki "introduction" kõrval mängimise nupule, et käivitada see moodul või käivita kõik korraga. +Lihtsalt vajuta mängunuppu "introduction" kõrval, et see moodul käivitada, või alusta korraga kõiki mooduleid. Spring Boot Dashboard -*Spring Boot Dashboard VS Code's — käivita, peata ja jälgi kõiki mooduleid ühest kohast* +*Spring Boot Dashboard VS Code's — alusta, peata ja jälgi kõiki mooduleid ühest kohast* -**Variant 2: Kasutades shell skripte** +**Variant 2: Käsurea skriptide kasutamine** Käivita kõik veebirakendused (moodulid 01-04): **Bash:** ```bash -cd .. # Juurest kataloogist +cd .. # Juurekataloogist ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Juura kataloogist +cd .. # Juure kataloogist .\start-all.ps1 ``` @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurkaustas `.env` failist ja ehitavad JAR failid, kui neid veel pole. +Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurest `.env` failist ja ehitavad JAR-failid, kui need puuduvad. -> **Märkus:** Kui tahad ehitada kõik moodulid käsitsi enne käivitamist: +> **Märkus:** Kui soovid kõik moodulid käsitsi enne käivitamist ehitada: > > **Bash:** > ```bash @@ -262,7 +262,7 @@ Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurkaustas `.env` fai > mvn clean package -DskipTests > ``` -Ava oma brauseris http://localhost:8080. +Ava oma brauseris http://localhost:8080 **Peatamiseks:** @@ -282,41 +282,41 @@ cd ..; .\stop-all.ps1 # Kõik moodulid ## Rakenduse kasutamine -Rakendus pakub veebipõhist liidest kahe vestluslahendusega kõrvuti. +Rakendus pakub veebiliidest kahe kõnelogi rakendusega kõrvuti. Application Home Screen -*Armatuurlaud, mis kuvab nii lihtsa vestluse (seisunditu) kui ka dialoogipõhise vestluse (seisundiga) valikud* +*Armatuurlaud, mis näitab nii lihtsat vestlust (stateless) kui ka vestlussessiooni (stateful) valikud* -### Seisunditu vestlus (vasak paneel) +### Stateless vestlus (vasak paneel) -Proovi esmalt seda. Küsi "Minu nimi on John" ja siis kohe "Mis on mu nimi?" Mudel ei mäleta, sest iga sõnum on iseseisev. See demonstreerib põhiprobleemi keelemudelite tavaintegratsioonis – puudub vestluse kontekst. +Proovi esmalt. Küsi "Minu nimi on John" ja seejärel kohe "Mis mu nimi on?". Mudel ei mäleta, sest iga sõnum on iseseisev. See demonstreerib baaskeelemudeli integratsiooni tuumaprobleemi - puudub vestluse kontekst. Stateless Chat Demo -*Tehisintellekt ei mäleta su nime eelmisest sõnumist* +*Tehisintellekt ei mäleta eelmistest sõnumitest sinu nime* -### Seisundiga vestlus (parem paneel) +### Stateful vestlus (parem paneel) -Nüüd proovi sama jada siin. Küsi "Minu nimi on John" ja seejärel "Mis on mu nimi?" Seekord mäletab. Erinevus on MessageWindowChatMemory - see hoiab vestluse ajaloo ja lisab selle iga päringuga kaasa. Nii töötab tootmisvestluse tehisintellekt. +Proovi nüüd sama järjestust siin. Küsi "Minu nimi on John" ja siis "Mis mu nimi on?" Sel korral mäletab. Erinevus on MessageWindowChatMemory - see hoiab vestluse ajaloo ja lisab selle iga päringu juurde. Nii toimib tootmise vestluslik tehisintellekt. Stateful Chat Demo -*Tehisintellekt mäletab su nime varasemast vestlusest* +*Tehisintellekt mäletab varasemat vestlust ja sinu nime* -Mõlemad paneelid kasutavad sama GPT-5.2 mudelit. Erinevus on ainult mälus. See teeb selgeks, mida mälu rakendusele annab ja miks see on tegelikes kasutusjuhtudes oluline. +Mõlemad paneelid kasutavad sama GPT-5.2 mudelit. Ainuke erinevus on mälu olemasolu. See teeb selgeks, mida mälu sinu rakendusele lisab ja miks see on tõeliste kasutusjuhtude puhul oluline. ## Järgmised sammud -**Järgmine moodul:** [02-prompt-engineering - Prompt Engineering GPT-5.2-ga](../02-prompt-engineering/README.md) +**Järgmine moodul:** [02-prompt-engineering - Päringu inseneriteadus GPT-5.2-ga](../02-prompt-engineering/README.md) --- -**Navigatsioon:** [← Eelmine: Moodul 00 – Kiirlahendus](../00-quick-start/README.md) | [Tagasi avalehele](../README.md) | [Järgmine: Moodul 02 – Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigeerimine:** [← Tagasi põhiosasse](../README.md) | [Järgmine: Moodul 02 - Päringu inseneriteadus →](../02-prompt-engineering/README.md) --- -**Vastutusest loobumine**: -See dokument on tõlgitud tehisintellekti tõlketeenuse [Co-op Translator](https://github.com/Azure/co-op-translator) abil. Kuigi püüame tagada täpsust, tuleks arvestada, et automaatsed tõlked võivad sisaldada vigu või ebatäpsusi. Originaaldokument selle algkeeles tuleks pidada autoriteetseks allikaks. Tähtsa teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei võta vastutust mis tahes arusaamatuste või vale tõlgenduste eest, mis tulenevad selle tõlke kasutamisest. +**Lahtiütlus**: +See dokument on tõlgitud kasutades AI tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest. \ No newline at end of file diff --git a/translations/et/02-prompt-engineering/README.md b/translations/et/02-prompt-engineering/README.md index f10200e05..7afb847c4 100644 --- a/translations/et/02-prompt-engineering/README.md +++ b/translations/et/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ -# Moodul 02: Päringu inseneriteadus GPT-5.2-ga +# Moodul 02: Promptide inseneriteadus GPT-5.2-ga ## Sisukord -- [Video juhend](../../../02-prompt-engineering) -- [Mida sa õpid](../../../02-prompt-engineering) -- [Eeltingimused](../../../02-prompt-engineering) -- [Mõistmine, mis on päringu inseneriteadus](../../../02-prompt-engineering) -- [Päringu inseneriteaduse alused](../../../02-prompt-engineering) - - [Nullnäitega päring](../../../02-prompt-engineering) - - [Mõne näitega päring](../../../02-prompt-engineering) - - [Mõttekäigu ahel](../../../02-prompt-engineering) - - [Rollipõhine päring](../../../02-prompt-engineering) - - [Päringumallid](../../../02-prompt-engineering) -- [Täiustatud mustrid](../../../02-prompt-engineering) -- [Rakenduse käivitamine](../../../02-prompt-engineering) -- [Rakenduse ekraanipildid](../../../02-prompt-engineering) -- [Mustrid lahti seletatuna](../../../02-prompt-engineering) - - [Madal vs kõrge innukus](../../../02-prompt-engineering) - - [Ülesande täitmine (tööriista sissejuhatused)](../../../02-prompt-engineering) - - [Enda peegeldav kood](../../../02-prompt-engineering) - - [Struktureeritud analüüs](../../../02-prompt-engineering) - - [Mitme vooru vestlus](../../../02-prompt-engineering) - - [Samm-sammult mõtlemine](../../../02-prompt-engineering) - - [Piiratud väljund](../../../02-prompt-engineering) -- [Mida sa tegelikult õpid](../../../02-prompt-engineering) -- [Järgmised sammud](../../../02-prompt-engineering) +- [Videojuhend](#videojuhend) +- [Mida Sa Õpid](#mida-sa-õpid) +- [Eeldused](#eeldused) +- [Promptide inseneriteaduse mõistmine](#promptide-inseneriteaduse-mõistmine) +- [Promptide inseneriteaduse alused](#promptide-inseneriteaduse-alused) + - [Null-kohaline promptimine](#null-kohaline-promptimine) + - [Mõned näited promptimine](#mõned-näited-promptimine) + - [Mõtte ahel](#mõtte-ahel) + - [Rollipõhine promptimine](#rollipõhine-promptimine) + - [Promptide mallid](#promptide-mallid) +- [Täiustatud mustrid](#täiustatud-mustrid) +- [Rakenduse käivitamine](#rakenduse-käivitamine) +- [Rakenduse ekraanipildid](#rakenduse-ekraanipildid) +- [Mustrid lähemalt](#musterite-uurimine) + - [Madal vs Kõrge innukus](#madal-vs-kõrge-innukus) + - [Tööülesannete täitmine (tööriistade eeltekstid)](#ülesande-täitmine-tööriistapromptid) + - [Isekriitiline kood](#enesepeegeldav-kood) + - [Struktureeritud analüüs](#struktureeritud-analüüs) + - [Mitme vooruga vestlus](#mitme-käiguline-vestlus) + - [Samm-sammuline põhjendus](#samm-sammuline-põhjendus) + - [Piiratud väljund](#piiratud-väljund) +- [Mida Sa Tõeliselt Õpid](#mida-te-tegelikult-õpite) +- [Järgmised sammud](#järgmised-sammud) -## Video juhend +## Videojuhend -Vaata seda otseülekannet, mis selgitab, kuidas selle mooduliga alustada: +Vaata seda otseülekannet, mis selgitab, kuidas käivitada see moodul: -Päringu inseneriteadus LangChain4j-ga – otseülekanne +Prompt Engineering with LangChain4j - Live Session -## Mida sa õpid +## Mida Sa Õpid -Järgnev diagramm annab ülevaate peamistest teemadest ja oskustest, mida selles moodulis arendad — alates päringu täpsustamise tehnikatest kuni samm-sammulise töövooni, mida järgid. +Järgnev diagramm annab ülevaate olulisematest teemadest ja oskustest, mida selles moodulis arendad — alates promptide lihvimise tehnikatest kuni samm-sammulise töövoo järgimiseni. -Mida sa õpid +Mida Sa Õpid -Eelmistes moodulites uurisid LangChain4j põhilisi käitumisi GitHubi mudelitega ja nägid, kuidas mälu võimaldab vestluslikku tehisintellekti Azure OpenAI abil. Nüüd keskendume sellele, kuidas sa küsimusi esitad — päringutele endile — kasutades Azure OpenAI GPT-5.2. Viis, kuidas sa oma päringud struktureerid, mõjutab oluliselt vastuste kvaliteeti. Alustame põhitehnikate ülevaatega ja liigume edasi kaheksasse täiustatud mustrisse, mis kasutavad täielikult GPT-5.2 võimeid. +Eelnevas moodulis nägid, kuidas mälu võimaldab vestlus-AI-d Azure OpenAI abil. Nüüd keskendume sellele, kuidas sa esitad küsimusi — promptidele endile — kasutades Azure OpenAI GPT-5.2. Sinu promptide ülesehitus mõjutab oluliselt saadud vastuste kvaliteeti. Alustame põhitehnikate ülevaatega ja liigume edasi kaheksa täiustatud mustrini, mis võtavad GPT-5.2 võimekuse täielikult kasutusele. -Kasutame GPT-5.2, sest see lisab mõtlemise juhtimise - saad mudelile öelda, kui palju ta peaks enne vastamist mõtlema. See muudab erinevad päringustrateegiad selgemaks ja aitab mõista, millal iga lähenemist kasutada. Samuti on GPT-5.2-l Azure keskkonnas vähem kiiruspiiranguid võrreldes GitHubi mudelitega. +Kasutame GPT-5.2, sest see tutvustab põhjendusjuhtimist – sa saad mudelile öelda, kui palju mõtlemist enne vastamist teha tuleb. See muudab erinevad promptimise strateegiad selgemaks ja aitab mõista, millal iga lähenemist kasutada. -## Eeltingimused +## Eeldused -- Lõpetatud Moodul 01 (Azure OpenAI ressursid juurutatud) -- Juurekataloogis `.env` fail koos Azure mandaatidega (tehtud `azd up` käsklusega Moodul 01-s) +- Läbitud Moodul 01 (Azure OpenAI ressursid paigaldatud) +- Juurekataloogis `.env` fail Azure volitustega (loodud käsuga `azd up` Moodulis 01) -> **Märkus:** Kui sa pole Moodulit 01 lõpetanud, järgi sealset juurutusjuhendit esmalt. +> **Märkus:** Kui pole lõpetanud Moodulit 01, järgi esmalt sealset paigaldamisjuhendit. -## Mõistmine, mis on päringu inseneriteadus +## Promptide inseneriteaduse mõistmine -Päringu inseneriteadus seisneb olemuselt erinevuses ebaselgete ja täpsete juhiste vahel, nagu allolev võrdlus näitab. +Promptide inseneriteadus seisneb peamiselt selles, et juhised on kas ebamäärased või täpsed – järgnev võrdlus seda illustreerib. -Mis on päringu inseneriteadus? +Mis on promptide inseneriteadus? -Päringu inseneriteadus tähendab sisendi teksti disainimist nii, et see annab järjepidevalt soovitud tulemuse. See ei seisne ainult küsimuste esitamises — vaid päringute struktuuris, nii et mudel mõistab täpselt, mida sa soovid ja kuidas seda toimetada. +Promptide inseneriteadus tähendab sisendi kavandamist nii, et see tagab sulle alati soovitud tulemused. See ei seisne ainult küsimuste esitamisel, vaid selleks, et päringud oleksid selliselt üles ehitatud, et mudel mõistaks täpselt, mida sa tahad ja kuidas seda esitada. -Mõtle sellele kui kolleegile juhiste andmisele. „Paranda viga“ on ebamäärane. „Paranda nullviite erind UserService.java faili 45. real, lisades nullkontrolli“ on konkreetne. Keelemudelid töötavad samal viisil — täpsus ja struktuur on olulised. +Mõtle sellele nagu juhiste andmine kolleegile. "Paranda viga" on ebamäärane. "Paranda UserService.java faili rea 45 tühiväärtusepaanika, lisades nulli kontrolli" on konkreetne. Keelemudelid töötavad samamoodi – tähtis on täpsus ja ülesehitus. -Järgnev diagramm näitab, kuidas LangChain4j seda pilti täiendab — ühendades su päringumustrid mudeliga läbi SystemMessage ja UserMessage ehituskivide. +Järgnev diagramm näitab, kuidas LangChain4j sinna sobitub — ühendades su promptimustrid mudeliga läbi SystemMessage ja UserMessage ehitusplokkide. Kuidas LangChain4j sobitub -LangChain4j pakub infrastruktuuri — mudeliühendused, mälu ja sõnumite tüübid — samas kui päringumustrid on lihtsalt hoolikalt struktureeritud tekst, mida sa selle infrastruktuuri kaudu saadad. Peamised ehituskivid on `SystemMessage` (mis määrab tehisintellekti käitumise ja rolli) ning `UserMessage` (mis kannab sinu tegelikku päringut). +LangChain4j tagab infrastruktuuri — mudeliga ühendused, mälu ja sõnumsiseste tüübid — samal ajal kui promptimustrid on lihtsalt hoolikalt üles ehitatud tekst, mida selle infrastruktuuri kaudu saadad. Peamised ehitusplokid on `SystemMessage` (mis määrab AI käitumise ja rolli) ja `UserMessage` (mis kannab su tegeliku päringu). -## Päringu inseneriteaduse alused +## Promptide inseneriteaduse alused -Viis põhilist tehnikat, mis allpool näidatud, moodustavad tõhusa päringu inseneriteaduse vundamendi. Igaüks neist käsitleb erinevat aspekti, kuidas keelega mudelitega suhelda. +Viis põhitehnikat, mis on allpool näidatud, moodustavad tõhusa promptimise aluse. Igaüks neist käsitleb erinevat aspekti keeletega suhtlemisest. -Viie päringu insenerteaduse mustri ülevaade +Viie promptide insenerimustri ülevaade -Enne kui sukelduda selle mooduli täiustatud mustritesse, vaatleme üle viis alustehnikat. Need on ehituskivid, mida iga päringu insener peaks teadma. Kui oled juba läbinud [Kiirstardi mooduli](../00-quick-start/README.md#2-prompt-patterns), oled neid juba näinud — siin on nende kontseptuaalne raamistik. +Enne selle mooduli täiustatud mustrite juurde asumist vaatame üle viis fundamentaalset promptimise tehnikat. Need on ehitusplokid, mida iga promptide insener peaks teadma. -### Nullnäitega päring +### Null-kohaline promptimine -Lihtsaim lähenemine: anna mudelile otsene juhis ilma näideteta. Mudel tugineb üksnes oma treeningandmetele, et mõista ja täita ülesanne. See toimib hästi lihtsate päringute puhul, kus oodatav käitumine on ilmne. +Kõige lihtsam lähenemine: anna mudelile otsene juhis ilma näideteta. Mudel tugineb täielikult oma treeningule, et mõista ja täita ülesannet. See töötab hästi lihtsate päringute puhul, kus ootuspärane käitumine on ilmne. -Nullnäitega päring +Null-kohaline promptimine -*Otsene juhis ilma näideteta — mudel tuletab ülesande ainult juhisest* +*Otsene juhis ilma näideteta — mudel järeldab ülesande ainult juhise põhjal* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Vastus: "Positiivne" ``` -**Millal kasutada:** Lihtsad klassifikatsioonid, otsesed küsimused, tõlked või igasugune ülesanne, mida mudel suudab täita ilma täiendava juhiseta. +**Millal kasutada:** Lihtsad klassifikatsioonid, otsesed küsimused, tõlkimised või mis tahes ülesanne, mida mudel suudab täita ilma täiendava juhendamiseta. -### Mõne näitega päring +### Mõned näited promptimine -Anna näited, mis demonstreerivad mustrit, mida mudel peaks järgima. Mudel õpib näidetest sisendi-väljundi formaadi ja rakendab seda uutele sisenditele. See parandab järjepidevust ülesannetes, kus soovitud formaat või käitumine pole ilmselge. +Too näited, mis näitavad mustrit, mida mudel peaks järgima. Mudel õpib sinu näidetest oodatud sisendi-väljundi formaadi ja rakendab seda uutele sisenditele. See parandab oluliselt järjepidevust ülesannetes, kus soovitud formaat või käitumine ei ole ilmne. -Mõne näitega päring +Mõned näited promptimine -*Näidetest õppimine — mudel tuvastab mustri ja rakendab seda uutele sisenditele* +*Õppimine näidete kaudu — mudel tuvastab mustri ja rakendab seda uutele sisenditele* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Millal kasutada:** Kohandatud klassifikatsioonid, järjepidev vormindus, domeenispetsiifilised ülesanded või olukorrad, kus nullnäitega tulemused on ebajärjekindlad. +**Millal kasutada:** Kohandatud klassifikatsioonid, järjepidev vormistus, domeenispetsiifilised ülesanded või kui null-kohaliste tulemused on ebajärjekindlad. -### Mõttekäigu ahel +### Mõtte ahel -Paluge mudelil näidata oma mõtlemist samm-sammult. Selle asemel, et kohe vastusele jõuda, lahendab mudel probleemi ja töötab läbi iga osa selgelt. See parandab täpsust matemaatika, loogika ja mitmeastmeliste ülesannete puhul. +Paluge mudelil näidata oma põhjendust samm-sammult. Selle asemel, et kohe vastust anda, jagab mudel probleemi osadeks ja lahendab need ükshaaval selgelt välja tuues. See parandab täpsust matemaatikas, loogikas ja mitmesammulistes põhjendusülesannetes. -Mõttekäigu ahela päring +Mõtte ahel promptimine -*Samm-sammuline mõtlemine — keeruliste probleemide jagamine loogilisteks sammudeks* +*Samm-sammuline põhjendus — keerukate probleemide lagundamine loogilisteks sammudeks* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Mudel näitab: 15 - 8 = 7, siis 7 + 12 = 19 õuna ``` -**Millal kasutada:** Matemaatikaprobleemid, loogikapusled, silumine või igasugune ülesanne, kus mõtlemisprotsessi näitamine parandab täpsust ja usaldusväärsust. +**Millal kasutada:** Matemaatikaülesanded, loogikamõistatused, silumine või mis tahes ülesanne, kus põhjendusprotsessi näitamine parandab täpsust ja usaldusväärsust. -### Rollipõhine päring +### Rollipõhine promptimine -Sea AI-le persona või roll enne küsimust. See annab konteksti, mis määrab vastuse tooni, sügavuse ja fookuse. „Tarkvaraarhitekt“ annab erinevat nõu kui „noorem arendaja“ või „turbeauditor“. +Sea AI-le enne küsimuse esitamist isiksus või roll. See annab konteksti, mis kujundab vastuse toonust, sügavust ja fookust. Näiteks "tarkvara arhitekt" annab teistsuguseid nõuandeid kui "noorem arendaja" või "turvaauditor". -Rollipõhine päring +Rollipõhine promptimine -*Konteksti ja persona kehtestamine — sama küsimus saab erineva vastuse vastavalt määratud rollile* +*Konteksti ja isiksuse määramine — sama küsimuse puhul võib vastus sõltuda määratud rollist* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Millal kasutada:** Koodiülevaated, juhendamine, domeenispetsiifiline analüüs või kui vajad vastuseid, mis on kohandatud konkreetse pädevustaseme või vaatenurga järgi. +**Millal kasutada:** Koodikontrolle, juhendamist, domeenispetsiifilist analüüsi või kui vajad vastuseid, mis on kohandatud konkreetsele teadmiste tasemele või vaatenurgale. -### Päringumallid +### Promptide mallid -Loo taaskasutatavad päringud muutujate kohatäitjatega. Selle asemel, et iga kord uut päringut kirjutada, defineeri mall üks kord ja täida erinevad väärtused. LangChain4j `PromptTemplate` klass teeb selle lihtsaks `{{muutuja}}` süntaksiga. +Loo korduvkasutatavad promptid muutujaplaanidega. Selle asemel, et kirjutada iga kord uus prompt, defineeri mall üks kord ja täida see erinevate väärtustega. LangChain4j `PromptTemplate` klass teeb seda lihtsaks `{{variable}}` süntaksiga. -Päringumallid +Promptide mallid -*Taaskasutatavad päringud muutujate kohatäitjatega — üks mall, palju kasutuskordi* +*Korduvkasutatavad promptid muutuja asendustega — üks mall, palju kasutusi* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Millal kasutada:** Korduvad päringud erinevate sisenditega, partiitöötlus, taaskasutatavate AI töövoogude loomine või igasugune olukord, kus päringu struktuur jääb samaks, kuid andmed muutuvad. +**Millal kasutada:** Korduvate päringute puhul erinevate sisenditega, hulgitöötluses, korduvkasutatavate AI töövoogude ehitamisel või igas olukorras, kus prompti struktuur jääb samaks, kuid andmed muutuvad. --- -Need viis alusteadust annavad sulle tugeva tööriistakomplekti enamikele päringutöödele. Ülejäänud moodul ehitab nendele põhinevalt kaheksale täiustatud mustrile, mis kasutavad GPT-5.2 mõtlemise juhtimist, enesehinnangut ja struktureeritud väljundi võimeid. +Need viis alust loovad tugeva tööriistakomplekti enamike promptimise ülesannete jaoks. Selle mooduli ülejäänud osa põhineb neil ning sisaldab **kaheksat täiustatud mustrit**, mis kasutavad GPT-5.2 põhjendusjuhtimise, enesehindamise ja struktureeritud väljundi võimalusi. ## Täiustatud mustrid -Pärast alustehnikate katmist liigume kaheksasse täiustatud mustrisse, mis teevad selle mooduli unikaalseks. Mitte kõik probleemid ei vaja sama lähenemist. Mõned küsimused vajavad kiireid vastuseid, teised põhjalikku mõtlemist. Mõned vajavad nähtavat järeldust, teised vajavad lihtsalt tulemusi. Iga alljärgnev muster on optimeeritud erineva stsenaariumi jaoks — ja GPT-5.2 mõtlemise juhtimine teeb need erinevused veelgi selgemaks. +Kui alused on kaetud, liigume kaheksa täiustatud mustri juurde, mis teevad selle mooduli ainulaadseks. Mitte kõik probleemid ei vaja sama lähenemist. Mõned küsimused vajavad kiireid vastuseid, teised sügavat mõtlemist. Mõned vajavad nähtavat põhjendust, teised lihtsalt tulemusi. Iga alljärgnev muster on optimeeritud erinevaks stsenaariumiks — ning GPT-5.2 põhjendusjuhtimine muudab erinevused veelgi selgemaks. -Kaheksa päringu insenerteaduse mustrit +Kaheksa promptimise mustrit -*Kaheksa päringu insenerteaduse mustri ülevaade ja nende kasutusjuhud* +*Kaheksa promptide insenerimustri ülevaade ja nende kasutusjuhud* -GPT-5.2 lisab neile mustritele veel ühe mõõtme: *mõtlemise juhtimise*. Allolev liugur näitab, kuidas saad mudeli mõtlemise pingutust reguleerida — alates kiiretest otsestest vastustest kuni sügava ja põhjaliku analüüsini. +GPT-5.2 lisab nendele mustritele veel ühe mõõtme: *põhjendusjuhtimise*. Liugur allpool näitab, kuidas saad mudeli mõtlemise pingutust reguleerida — kiiretest otsevastustest kuni põhjaliku süvaanalüüsini. -Mõtlemise juhtimine GPT-5.2-ga +Põhjendusjuhtimine GPT-5.2-ga -*GPT-5.2 mõtlemise juhtimine võimaldab määrata, kui palju mudel peaks mõtlema — alates kiiretest otsestest vastustest kuni sügava uurimiseni* +*GPT-5.2 põhjendusjuhtimine lubab määrata, kui palju mudel peab mõtlema — alates kiiretest otsestest vastustest kuni põhjaliku uurimiseni* -**Madal innukus (kiire ja fokusseeritud)** – lihtsate küsimuste jaoks, kus vajad kiireid ja otseseid vastuseid. Mudel teeb minimaalset mõtlemist – maksimaalselt 2 sammu. Kasuta seda arvutusteks, otsinguteks või lihtsateks küsimusteks. +**Madal innukus (Kiire & Fookustatud)** - Lihtsate küsimuste puhul, kus tahad kiireid ja otseseid vastuseid. Mudel teeb minimaalset põhjendust - maksimaalselt 2 sammu. Kasuta seda arvutuste, päringute või sirgjooneliste küsimuste jaoks. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Uuri GitHub Copilotiga:** Ava [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ja küsi: -> - "Mis vahe on madala ja kõrge innukusega päringu mustritel?" -> - "Kuidas XML sildid päringutes aitavad AI vastust struktureerida?" -> - "Millal peaksin kasutama enesepeegeldamise mustreid ja millal otseseid juhiseid?" +> - "Mis vahe on madala ja kõrge innukusega promptimustritel?" +> - "Kuidas XML sildid promptides aitavad AI vastuseid struktureerida?" +> - "Millal peaksin kasutama eneserefleksiooni mustreid vs otseseid juhiseid?" -**Kõrge innukus (põhjalik ja põhjalik)** – keerukate probleemide jaoks, kus vajad laiaulatuslikku analüüsi. Mudel uurib põhjalikult ja näitab detailset mõtlemist. Kasuta seda süsteemide disaini, arhitektuuriotsuste või keeruka uurimuse jaoks. +**Kõrge innukus (Sügav & Põhjalik)** - Komplekssete probleemide puhul, kus soovid põhjalikku analüüsi. Mudel uurib põhjalikult ja näitab detailset põhjendust. Kasuta seda süsteemide disaini, arhitektuuriliste otsuste või keerukate uurimistööde jaoks. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Ülesande täitmine (samm-sammuline edenemine)** – mitmeastmeliste töövoogude jaoks. Mudel annab alguses plaani, kirjeldab iga toimingut töö käigus ja annab seejärel kokkuvõtte. Kasuta seda migratsioonide, juurutuste või mistahes mitmeastmelise protsessi jaoks. +**Tööülesannete täitmine (samm-sammuline edenemine)** - Mitmesammuliste töövoogude jaoks. Mudel annab etteplaani, jutustab iga sammu töötlemise ajal ja annab kokkuvõtte. Kasuta migreerimiste, rakenduste või mõne muu mitmesammulise protsessi jaoks. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Mõttekäigu ahela päring palub mudelil selgelt näidata järeldusprotsessi, parandades keerukate ülesannete täpsust. Samm-sammuline jaotus aitab nii inimestel kui tehisintellektil loogikat mõista. +Mõtte ahela promptimine palub mudelil selgelt näidata oma põhjendusprotsessi, parandades täpsust komplekssete ülesannete puhul. Samm-sammult lagundamine aitab nii inimestel kui AI-l loogikat mõista. -> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat'iga:** Küsi selle mustri kohta: -> - "Kuidas kohandada ülesande täitmise mustrit pikkadeks operatsioonideks?" -> - "Millised on parimad tavad tööriista sissejuhatuste struktuuri jaoks tootmises?" -> - "Kuidas püüda ja kuvada vahepealseid edenemisteateid kasutajaliideses?" +> **🤖 Proovi [GitHub Copiloti](https://github.com/features/copilot) Chat'iga:** Küsi selle mustri kohta: +> - "Kuidas kohandada tööülesande täitmise mustrit pikaajaliste operatsioonide jaoks?" +> - "Millised on parimad praktikad tööriistade eeltekstid rakendustes?" +> - "Kuidas tabada ja kuvada vahe-edenemise uuendusi kasutajaliideses?" -Järgnev diagramm illustreerib seda Plaani → Täida → Kokkuvõtte töövoogu. +Järgnev diagramm illustreerib seda Plaan → Täida → Kokkuvõte töövoogu. -Ülesande täitmise muster +Tööülesannete täitmise muster -*Plaani → Täida → Kokkuvõtte töövoog mitmeastmeliste ülesannete jaoks* +*Plaan → Täida → Kokkuvõte töövoog mitmesammuliste ülesannete jaoks* -**Enda peegeldav kood** – tootmiskvaliteediga koodi genereerimiseks. Mudel genereerib koodi, järgides tootmistandardeid ja korralikku veahaldust. Kasuta seda uute funktsioonide või teenuste loomisel. +**Isekriitiline kood** - Toodangukvaliteediga koodi genereerimiseks. Mudel loob koodi vastavalt tootmisstandarditele, sh nõuetekohase veakäsitlusega. Kasuta seda uute funktsioonide või teenuste arendamisel. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Allolev diagramm näitab iteratiivset täiustamisringi — genereeri, hinda, tuvasta nõrkused ja täiusta, kuni kood vastab tootmisnõuetele. +Järgnev diagramm näitab seda iteratiivse täiustamise tsüklit — genereeri, hinda, tuvastu puudujäägid ja paranda, kuni kood vastab tootmisstandarditele. -Enesepeegeldamise tsükkel +Isekriitilise tsükli diagramm -*Iteratiivne täiustamisring – genereeri, hinda, tuvastamisprobleemid, paranda, korda* +*Iteratiivne täiustamise tsükkel – genereeri, hinda, leia puudused, paranda, korda* -**Struktureeritud analüüs** – järjepidevaks hindamiseks. Mudel vaatab koodi üle fikseeritud raamistikus (õigsus, tavad, jõudlus, turvalisus, hooldatavus). Kasuta seda koodiülevaadete või kvaliteedi hindamise puhul. +**Struktureeritud analüüs** - Järjekindla hindamise jaoks. Mudel vaatab koodi üle fikseeritud raamistikus (õigsus, praktika, jõudlus, turvalisus, hooldatavus). Kasuta seda koodikontrollide või kvaliteedihindamiste jaoks. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat'iga:** Küsi struktureeritud analüüsi kohta: -> - "Kuidas kohandada analüüsiraamistikku erinevate tüüpi koodiülevaadete jaoks?" -> - "Mis on parim viis struktureeritud väljundi lugemiseks ja tegevuse võtmiseks programmeeritult?" -> - "Kuidas tagada järjepidev raskusastmete tase erinevate ülevaatesessioonide vahel?" +> **🤖 Proovi [GitHub Copiloti](https://github.com/features/copilot) Chat'iga:** Küsi struktureeritud analüüsi kohta: +> - "Kuidas kohandada analüüsiraamistikku erinevate koodikontrollitüüpide jaoks?" +> - "Mis on parim viis struktureeritud väljundi programmiliseks töötlemiseks ja tegutsemiseks?" +> - "Kuidas tagada järjekindel raskusastmete määramine erinevates läbivaatuse sessioonides?" -Järgmine diagramm näitab, kuidas see struktureeritud raamistik korraldab koodiülevaate järjekindlatesse kategooriatesse raskusastmega. +Järgnev diagramm näitab, kuidas see raamistik organiseerib koodikontrolli järjekindlatesse kategooriatesse koos raskusastmetega. Struktureeritud analüüsi muster -*Järjepidevate koodiülevaadete raamistik raskusastmetega* +*Järjekindlate koodikontrollide raamistik raskusastmetega* -**Mitme vooru vestlus** – vestluste jaoks, mis vajavad konteksti. Mudel mäletab varasemaid sõnumeid ja arendab neid edasi. Kasuta seda interaktiivsetes abisessioonides või keerukates Q&A-stseenides. +**Mitme vooruga vestlus** - Vestluste jaoks, mis vajavad konteksti. Mudel mäletab varasemaid sõnumeid ja ehitab neile juurde. Kasuta seda interaktiivsete abiseansside või keerukate küsimuste ja vastuste jaoks. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Järgmine diagramm visualiseerib, kuidas vestluse kontekst akumuleerub iga vooruga ja kuidas see on seotud mudeli tokeni piiranguga. +Järgnev diagramm visualiseerib, kuidas vestluse kontekst koguneb mitme vooru jooksul ja kuidas see seostub mudeli tokeni piiriga. -Vestluse konteksti mälu +Konteksti mälu -*Kuidas vestluse kontekst akumuleerub mitme vooru jooksul kuni tokeni piirini* -**Samm-sammult põhjendus** – Probleemide puhul, mis vajavad nähtavat loogikat. Mudel näitab iga sammu jaoks selget põhjendust. Kasuta seda matemaatikaülesannete, loogikapuslede või siis, kui vajad arusaamist mõtlemisprotsessist. +*Kuidas vestluse kontekst koguneb mitme vooruga kuni tokeni piirini* + +**Samm-sammuline põhjendus** - Probleemide jaoks, mis vajavad nähtavat loogikat. Mudel näitab selget põhjendust iga sammu kohta. Kasuta seda matemaatikaülesannete, loogikamõistatuste või siis, kui vajad mõtlemisprotsessi mõistmist. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Järgmine joonis illustreerib, kuidas mudel jaotab probleeme selgeteks, nummerdatud loogilisteks sammudeks. - -Samm-sammult muster +Järgnev diagramm näitab, kuidas mudel jagab probleemid konkreetseteks, nummerdatud loogilisteks sammudeks. -*Probleemide jaotamine selgeteks loogilisteks sammudeks* +Samm-sammuline muster +*Probleemide jagamine selgeteks loogilisteks sammudeks* -**Piiratud väljund** – Vastuste puhul, millel on konkreetse formaadi nõuded. Mudel järgib rangelt formaadi ja pikkuse reegleid. Kasuta seda kokkuvõtete tegemiseks või kui vajad täpset väljundi struktuuri. +**Piiratud väljund** – vastuste puhul, millel on konkreetsed vormingu nõuded. Mudel järgib rangelt vormingu ja pikkuse reegleid. Kasutatakse kokkuvõtete jaoks või kui on vaja täpset väljundi struktuuri. ```java String prompt = """ @@ -420,51 +420,51 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Järgmine joonis näitab, kuidas piirangud juhivad mudelit genereerima väljundit, mis striktse järgib sinu formaadi ja pikkuse nõudeid. +Järgnev diagramm näitab, kuidas piirangud juhivad mudelit väljundi loomisel, mis rangelt vastab teie vormingu ja pikkuse nõuetele. Piiratud väljundi muster -*Konkreetsed formaadi, pikkuse ja struktuuri nõuded* +*Konkreetsed vormingu, pikkuse ja struktuuri nõueteks järgimine* -## Käivita rakendus +## Rakenduse käivitamine -**Kontrolli juurutust:** +**Paigaldamise kontrollimine:** -Veendu, et `.env` fail eksisteerib juurkataloogis koos Azure'i volitustega (loodud moodulis 01). Käivita see mooduli kataloogist (`02-prompt-engineering/`): +Veenduge, et `.env` fail eksisteerib juurkaustas koos Azure volitustega (loodud moodulis 01). Käivitage see mooduli kaustast (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Peab näitama AZURE_OPENAI_ENDPOINTi, API_KEYd, DEPLOYMENTi ``` **PowerShell:** ```powershell -Get-Content ..\.env # Peaks kuvama AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Tuleks näidata AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Alusta rakendust:** +**Rakenduse käivitamine:** -> **Märkus:** Kui oled juba kõik rakendused käivitanud käsuga `./start-all.sh` juurkataloogist (nagu kirjeldatud moodulis 01), siis see moodul töötab juba pordil 8083. Võid järgmised käivituskäsud vahele jätta ja minna otse aadressile http://localhost:8083. +> **Märkus:** Kui olete juba käivitanud kõik rakendused, kasutades `./start-all.sh` juurkaustast (nagu kirjeldatud moodulis 01), siis see moodul töötab juba pordil 8083. Võite alljärgnevad käivitamiskäsud vahele jätta ja minna otse aadressile http://localhost:8083. -**Valik 1: Kasutades Spring Boot Dashboard’i (Soovitatav VS Code kasutajatele)** +**Variant 1: Spring Boot'i juhtpaneeli kasutamine (Soovitatav VS Code kasutajatele)** -Arendus konteiner sisaldab Spring Boot Dashboard laiendust, mis pakub visuaalset kasutajaliidest kõigi Spring Boot rakenduste haldamiseks. Leiad selle VS Code vasaku külje Activity Bar’ist (otsa otsi Spring Boot ikooni). +Dev konteiner sisaldab Spring Boot Dashboard laiendust, mis pakub visuaalset liidest kõigi Spring Boot rakenduste haldamiseks. Leidke see VS Code ühelt vasakult küljelt tegevusribalt (otsige Spring Boot ikooni). -Spring Boot Dashboard’ist saad: -- Näha kõiki tööruumis saadaolevaid Spring Boot rakendusi -- Alustada/peatada rakendusi ühe klikiga -- Vaadata rakenduste logisid reaalajas +Spring Boot Dashboard'ist võite: +- Näha kõiki tööruumi saadaolevaid Spring Boot rakendusi +- Alustada/peatada rakendusi ühe klõpsuga +- Vaadata rakenduse logisid reaalajas - Jälgida rakenduse olekut -Lihtsalt klõpsa mängunupule "prompt-engineering" kõrval, et alustada seda moodulit või käivita korraga kõik moodulid. +Klõpsake lihtsalt "prompt-engineering" kõrval olevat esitamise nuppu, et seda moodulit käivitada või käivitage korraga kõik moodulid. -Spring Boot Dashboard +Spring Boot'i juhtpaneel -*Spring Boot Dashboard VS Code’is — alusta, peata ja jälgi kõiki mooduleid ühest kohast* +*Spring Boot Dashboard VS Code'is — alustage, peatage ja jälgige kõiki mooduleid ühest kohast* -**Valik 2: Kasutades shell skripte** +**Variant 2: Shell skriptide kasutamine** -Käivita kõik veebirakendused (moodulid 01–04): +Käivitage kõik veebirakendused (moodulid 01-04): **Bash:** ```bash @@ -474,11 +474,11 @@ cd .. # Juurekataloogist **PowerShell:** ```powershell -cd .. # Juure kataloogist +cd .. # Juurekataloogist .\start-all.ps1 ``` -Või alusta ainult seda moodulit: +Või käivitage ainult see moodul: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurest `.env` failist ja koostavad JAR-failid, kui neid pole olemas. +Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurekaustus asuvast `.env` failist ning ehitavad JAR-failid, kui neid ei eksisteeri. -> **Märkus:** Kui soovid kõik moodulid käsitsi enne käivitamist kompileerida: +> **Märkus:** Kui eelistate kõik moodulid enne käivitamist käsitsi kokku panna: > > **Bash:** > ```bash @@ -508,7 +508,7 @@ Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurest `.env` failist > mvn clean package -DskipTests > ``` -Ava oma brauseris aadress http://localhost:8083. +Avage oma brauseris http://localhost:8083. **Peatamiseks:** @@ -528,81 +528,81 @@ cd ..; .\stop-all.ps1 # Kõik moodulid ## Rakenduse ekraanipildid -Siin on prompt engineering mooduli põhiliides, kus saad katsetada kõiki kaheksat mustrit kõrvuti. +Siin on prompt-insenerimise mooduli põhiline liides, kus saate kõiki kaheksat mustrit kõrvuti katsetada. -Dashboard Avaleht +Juhtpaneeli avaleht -*Põhidiagramm, mis kuvab kõiki 8 prompt engineering mustrit nende omaduste ja kasutusjuhtumitega* +*Peamine juhtpaneel, kus kuvatakse kõik 8 prompt-insenerimise mustrit koos nende omaduste ja kasutusjuhtudega* ## Musterite uurimine -Veebiliides võimaldab sul katsetada erinevaid promptimise strateegiaid. Iga muster lahendab erinevaid probleeme – proovi neid, et näha, millal milline lähenemine töötab kõige paremini. +Veebiliides võimaldab teil katsetada erinevaid promptimise strateegiaid. Iga muster lahendab erinevaid probleeme – proovige neid, et näha, millal iga lähenemine sobib. -> **Märkus: Voogedastus vs Mittevoogedastus** — Iga mustri lehel on kaks nuppu: **🔴 Voogvastus (Live)** ja **Mittevoogedastus** valik. Voogedastus kasutab Server-Sent Events (SSE), et kuvada mudelei genereeritavaid silte reaalajas, nii näed edenemist kohe. Mittevoogedastus ootab kogu vastust ära enne kuvamist. Sügava põhjenduse korral (nt High Eagerness, Self-Reflecting Code) võib mittevoogedastus võtta väga kaua aega — mõnikord minuteid — ilma nähtava tagasisideta. **Kasuta voogedastust keerukate promptidega katsetamisel**, et näha mudeli tööd ja vältida arusaama, et päring on aegunud. +> **Märkus: voogedastus vs mittevoogedastus** — Iga mustri lehel on kaks nuppu: **🔴 Stream Response (Live)** ja **mittevoogedastus** variant. Voogedastus kasutab serverist saadetavaid sündmusi (SSE), et näidata märksõnu reaalajas, kui mudel neid genereerib, nii et saate kohe edenemist näha. Mittevoogedastus ootab kogu vastuse saamist enne kuvamist. Sügavat mõtlemist nõudvate promptide (nt High Eagerness, Self-Reflecting Code) puhul võib mittevoogedastus võtta väga kaua aega — mõnikord minutit — ilma nähtava tagasisideta. **Kasutage voogedastust keerukate promptide puhul**, et näha mudeli tööd ja vältida muljet, et päring on aegunud. > -> **Märkus: Brauseri nõuded** — Voogedastuse funktsioon kasutab Fetch Streams API-d (`response.body.getReader()`), mis nõuab täielikku brauserit (Chrome, Edge, Firefox, Safari). See **ei tööta** VS Code'i sisseehitatud Simple Browser'is, kuna selle veebivaade ei toeta ReadableStream API-d. Kui kasutad Simple Browser’i, siis mittevoogedastusnupud töötavad tavalise kujul – ainult voogedastusnupud on mõjutatud. Ava täielikuks kogemuseks `http://localhost:8083` välises brauseris. +> **Märkus: brauseri nõue** — Voogedastusfunktsioon kasutab Fetch Streams API-d (`response.body.getReader()`), mis vajab täisväärtuslikku brauserit (Chrome, Edge, Firefox, Safari). See ei tööta VS Code'i sisseehitatud Simple Browser-is, kuna selle veebivaade ei toeta ReadableStream API-d. Kui kasutate Simple Browserit, töötavad mittevoogedastuse nupud normaalselt – ainult voogedastuse nupud on piiratud. Avage täiskogemuse saamiseks `http://localhost:8083` välist brauserit. -### Madal vs Kõrge Janunevus +### Madal vs kõrge innukus -Esita lihtne küsimus nagu "Mis on 15% arvust 200?" kasutades Madalat Janunevust. Saad kohese, otsese vastuse. Nüüd esita keerukam küsimus nagu "Töötle välja kõrge koormusega API vahemälustrateegia" kasutades Kõrget Janunevust. Vajuta **🔴 Voogvastus (Live)** ja vaata, kuidas mudeli detailne põhjendus ilmub sümboli kaupa. Sama mudel, sama küsimuse struktuur – aga prompt ütleb, kui palju mõelda. +Esitage lihtne küsimus nagu "Mis on 15% 200-st?" kasutades Madalat Innukust. Saate kohe otsese vastuse. Nüüd küsige midagi keerulisemat nagu "Disainige vahemällu salvestamise strateegia suure liiklusega API jaoks" kasutades Kõrget Innukust. Klõpsake **🔴 Stream Response (Live)** ja vaadake, kuidas mudeli detailne põhjendus ilmub ühikute kaupa. Sama mudel, sama küsimuse struktuur – kuid prompt räägib, kui palju mõtlemist teha. -### Ülesande täitmine (Tööriistade eelsõnad) +### Ülesande täitmine (Tööriistapromptid) -Mitmesammulised töövood saavad kasu eelplaneerimisest ja protsessi jutustamisest. Mudel kirjeldab, mida teeb, kirjeldab iga sammu ja seejärel võtab tulemused kokku. +Mitmeastmelised töövood saavad kasu etteplaneerimisest ja edenemise jutustamisest. Mudel kirjeldab, mida teeb, jutustab iga sammu ja seejärel võtab tulemused kokku. ### Enesepeegeldav kood -Proovi "Loo e-posti valideerimise teenus". Selle asemel, et lihtsalt koodi genereerida ja peatuda, genereerib mudel, hindab seda kvaliteedikriteeriumite järgi, tuvastab nõrkused ja täiustab. Näed, kuidas see iteratsioonivalt töötab, kuni kood vastab tootmisstandarditele. +Proovige "Loo e-posti valideerimise teenus". Selle asemel, et lihtsalt koodi genereerida ja lõpetada, genereerib mudel, hindab kvaliteedikriteeriumite alusel, tuvastab nõrkused ja parandab. Näete, kuidas ta kordab kuni kood vastab tootmisstandarditele. ### Struktureeritud analüüs -Koodikontrollid vajavad järjepidevaid hindamisraamistikke. Mudel analüüsib koodi fikseeritud kategooriate alusel (õigsus, praktikad, jõudlus, turvalisus) koos tõsidustasemega. +Koodi ülevaated vajavad järjepidevaid hindamisraamistikke. Mudel analüüsib koodi fikseeritud kategooriate kaupa (õigsus, toimingud, jõudlus, turvalisus) koos tõsidustasemega. -### Mitmesammuline vestlus +### Mitme-käiguline vestlus -Küsi "Mis on Spring Boot?" ja seejärel kohe "Näita mulle näidet". Mudel mäletab sinu esimest küsimust ja annab just selle põhjal Spring Boot näite. Ilma mäluta oleks teine küsimus liiga ebamäärane. +Küsige "Mis on Spring Boot?" ja seejärel kohe "Näita mulle näidet". Mudel mäletab teie esimest küsimust ja annab teile Spring Booti näite spetsiaalselt. Ilma mäluta oleks teine küsimus liiga ebamäärane. -### Samm-sammult põhjendus +### Samm-sammuline põhjendus -Vali mõni matemaatikaülesanne ja proovi seda nii Samm-sammult põhjendusega kui ka Madala Janunevusega. Madal janunevus annab lihtsalt vastuse – kiire, aga mustri mõttes ebaselge. Samm-sammult näitab kõiki arvutusi ja otsuseid. +Valige matemaatikaülesanne ja proovige seda nii samm-sammulise põhjenduse kui ka madala innukusega. Madal innukus annab lihtsalt vastuse – kiiresti, kuid varjatud. Samm-sammuline näitab kõiki arvutusi ja otsuseid. ### Piiratud väljund -Kui vajad teatud formaate või sõnade arvu, tagab see muster rangelt nõuete järgimise. Proovi genereerida kokkuvõte, mis sisaldab täpselt 100 sõna märkepunktides. +Kui vajate konkreetseid vorminguid või sõnade arvu, kehtestab see muster rangeid reegleid. Proovige genereerida kokkuvõte, millel on täpselt 100 sõna ja mis on punktidena esitatud. -## Mida sa tegelikult õpid +## Mida te tegelikult õpite -**Põhjenduse pingutus muudab kõik** +**Põhjendusjõud muudab kõik** -GPT-5.2 võimaldab sul juhtida arvutuspingutust läbi promptide. Madal pingutus tähendab kiireid vastuseid minimaalse uurimisega. Kõrge pingutus tähendab, et mudel võtab aega sügavaks mõtlemiseks. Õpid sejama pingutuse ülesande keerukusega – ära raiska aega lihtsatele küsimustele, aga ära kiirusta keeruliste otsuste tegemisega. +GPT-5.2 võimaldab teil juhtida arvutusjõudu oma promptide kaudu. Madal jõud tähendab kiireid vastuseid vähese uurimisega. Kõrge jõud tähendab, et mudel võtab aega sügavalt mõtlemiseks. Õpite sobitama jõudu ülesande keerukusega – ärge raisake aega lihtsate küsimuste peale, kuid ärge ka kiirustage keerukate otsustega. **Struktuur juhib käitumist** -Kui märkad promptis XML-tähiseid? Need ei ole lihtsalt kaunistuseks. Mudelid järgivad struktureeritud juhiseid usaldusväärsemalt kui vabateksti. Kui vajad mitmesammulisi protsesse või keerulist loogikat, aitab struktuur mudelil jälgida, kus ta parasjagu on ja mis järgmine samm on. Järgmine joonis jagab hästi struktureeritud prompti, näidates, kuidas sildid nagu ``, ``, ``, ``, ja `` organiseerivad juhised selgeteks sektsioonideks. +Kas olete märganud promptide XML-silte? Need ei ole kaunistuseks. Mudelid järgivad struktureeritud juhiseid usaldusväärsemalt kui vabateksti. Kui vajate mitmeastmelisi protsesse või keerukat loogikat, aitab struktuur mudelil jälgida, kus ta on ja mis tuleb järgmiseks. Järgmine diagramm lagundab hästi struktureeritud prompti, näidates, kuidas sildid ``, ``, ``, `` ja `` organiseerivad teie juhised selgeteks osadeks. Prompti struktuur -*Hästi struktureeritud prompti anatoomia selgete sektsioonide ja XML-laadse korraldusega* +*Hästi struktureeritud prompti anatoomia selgete osade ja XML-laadse korraldusega* **Kvaliteet läbi enesehindamise** -Enesepeegeldamise mustrid töötavad, tehes kvaliteedikriteeriumid eksplitsiitseks. Selle asemel, et loota, et mudel "teeb õigesti", ütled täpselt, mida tähendab "õige": korrektne loogika, veakäsitlus, jõudlus, turvalisus. Seejärel saab mudel enda väljundit hinnata ja paremaks muuta. See muudab koodigeneratsiooni loteriist protsessiks. +Enesepeegeldavad mustrid töötavad nii, et teevad kvaliteedikriteeriumid selgelt nähtavaks. Selle asemel, et loota mudeli „õigele tegutsemisele“, ütlete talle täpselt, mida „õige“ tähendab: õige loogika, veahaldus, jõudlus, turvalisus. Mudel saab seejärel hinnata oma väljundit ja parandada seda. See muudab koodi genereerimise loteriist protsessiks. **Kontekst on piiratud** -Mitmesammulised vestlused toimivad, kaasates iga päringu juurde sõnumi ajaloo. Kuid on piir – iga mudeli tokenite arv on maksimaalne. Vestluse kasvades vajad strateegiaid, et hoida asjakohane kontekst ilma selle piirmäära ületamata. See moodul näitab sulle, kuidas mälu töötab; hiljem õpid, millal võtta kokku, millal unustada ja millal taastada. +Mitme-käigulised vestlused töötavad, lisades igale päringule sõnumite ajaloo. Kuid on piir – igal mudelil on maksimaalne tokenite arv. Vestluste kasvades peate leidma strateegiaid, kuidas hoida asjakohast konteksti ilma selle lakini jõudmata. See moodul näitab teile, kuidas mälu töötab; hiljem õpite, millal kokkuvõtteid teha, millal unustada ja millal pärida. ## Järgmised sammud -**Järgmine moodul:** [03-rag - RAG (teadmistepõhine genereerimine)](../03-rag/README.md) +**Järgmine moodul:** [03-rag - RAG (otsingupõhine suurendatud genereerimine)](../03-rag/README.md) --- -**Navigeerimine:** [← Eelmine: Moodul 01 - Sissejuhatus](../01-introduction/README.md) | [Tagasi põhilehele](../README.md) | [Järgmine: Moodul 03 - RAG →](../03-rag/README.md) +**Navigeerimine:** [← Eelmine: Moodul 01 - Sissejuhatus](../01-introduction/README.md) | [Tagasi avalehele](../README.md) | [Järgmine: Moodul 03 - RAG →](../03-rag/README.md) --- -**Vastutusest loobumine**: -See dokument on tõlgitud kasutades tehisintellektil põhinevat tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi püüdleme täpsuse poole, palume arvestada, et automatiseeritud tõlked võivad sisaldada vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul on soovitatav kasutada professionaalseid inimtõlkeid. Me ei vastuta selle tõlke kasutamisest tulenevate arusaamatuste või valesti mõistmiste eest. +**Lahtiütlus**: +See dokument on tõlgitud kasutades AI tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest. \ No newline at end of file diff --git a/translations/et/03-rag/README.md b/translations/et/03-rag/README.md index b32f41fde..1a5601fb2 100644 --- a/translations/et/03-rag/README.md +++ b/translations/et/03-rag/README.md @@ -1,146 +1,143 @@ -# Moodul 03: RAG (taastepõhine loomine) +# Moodul 03: RAG (otsingupõhine genereerimine) ## Sisukord -- [Video juhendamine](../../../03-rag) -- [Mida sa õpid](../../../03-rag) -- [Eeldused](../../../03-rag) -- [RAG mõistmine](../../../03-rag) - - [Millist RAG lähenemist see juhend kasutab?](../../../03-rag) -- [Kuidas see töötab](../../../03-rag) - - [Dokumendi töötlemine](../../../03-rag) - - [Manuste loomine](../../../03-rag) - - [Semantiline otsing](../../../03-rag) - - [Vastuste genereerimine](../../../03-rag) -- [Rakenduse käivitamine](../../../03-rag) -- [Rakenduse kasutamine](../../../03-rag) - - [Dokumendi üleslaadimine](../../../03-rag) - - [Küsimuste esitamine](../../../03-rag) - - [Allikaviidete kontrollimine](../../../03-rag) - - [Katsetamine küsimustega](../../../03-rag) -- [Põhikontseptsioonid](../../../03-rag) - - [Tükeldamisstrateegia](../../../03-rag) - - [Sarnasuskoefitsiendid](../../../03-rag) - - [Mälusalvestus](../../../03-rag) - - [Kontekstivälja haldamine](../../../03-rag) -- [Millal RAG on oluline](../../../03-rag) -- [Järgmised sammud](../../../03-rag) - -## Video juhendamine - -Vaata seda otseülekannet, mis selgitab, kuidas selle mooduliga alustada: +- [Videojuhend](#videojuhend) +- [Mida Sa Õpid](#mida-sa-õpid) +- [Eelnõuded](#eelnõuded) +- [RAG mõistmine](#rag-mõistmine) + - [Millist RAG lähenemist see juhend kasutab?](#millist-rag-lähenemist-see-juhend-kasutab) +- [Kuidas see töötab](#kuidas-see-töötab) + - [Dokumendi töötlemine](#dokumendi-töötlemine) + - [Sissejuhatuste loomine](#sissejuhatuste-loomine) + - [Semantiline otsing](#semantiline-otsing) + - [Vastuse genereerimine](#vastuse-loomine) +- [Rakenduse käivitamine](#rakenduse-käivitamine) +- [Rakenduse kasutamine](#rakenduse-kasutamine) + - [Dokumendi üleslaadimine](#dokumendi-üleslaadimine) + - [Küsimuste esitamne](#küsi-küsimusi) + - [Allikaviidete kontrollimine](#kontrolli-allikaviiteid) + - [Katsetamine küsimustega](#katseta-küsimustega) +- [Põhikontseptsioonid](#olulised-mõisted) + - [Tükkideks jagamise strateegia](#lõikude-strateegia) + - [Sarnasuse skoorid](#sarnasusskoorid) + - [Mälusalvestus](#mälupõhine-salvestus) + - [Kontekstiakna haldamine](#konteksti-akna-haldamine) +- [Millal RAG on oluline](#millal-rag-on-oluline) +- [Järgmised sammud](#järgmised-sammud) + +## Videojuhend + +Vaata seda reaalajas sessiooni, mis selgitab, kuidas selle mooduli alustamiseks: RAG with LangChain4j - Live Session -## Mida sa õpid +## Mida Sa Õpid -Eelnevates moodulites õppisid, kuidas vestelda tehisintellektiga ja oma päringuid efektiivselt struktureerida. Kuid on üks põhipiirang: keelemudelid teavad ainult seda, mida neile treeningu ajal õpetati. Nad ei saa vastata küsimustele sinu ettevõtte poliitikate, projektdokumentatsiooni või muu info kohta, mida neile ei ole õpetatud. +Eelnevates moodulites õppisid, kuidas suhelda tehisintellektiga ja struktureerida oma juhiseid efektiivselt. Kuid on üks põhimõtteline piirang: keelemudelid teavad vaid seda, mida nad treeningu ajal õppisid. Nad ei saa vastata küsimustele sinu ettevõtte poliitikate, projekti dokumentatsiooni või muu teabe kohta, mida neile treenimisel ei sisestatud. -RAG (taastepõhine loomine) lahendab selle probleemi. Selle asemel, et pead mudelit sinu infole õpetama (mis on kallis ja ebaefektiivne), annad mudelile võimaluse otsida sinu dokumentidest. Kui keegi esitab küsimuse, leiab süsteem asjakohase info ja lisab selle päringusse. Mudel vastab siis selle taasesitatud konteksti põhjal. +RAG (otsingupõhine genereerimine) lahendab selle probleemi. Selle asemel, et püüda mudelile sinu infot õpetada (mis on kallis ja ebaratsionaalne), annad talle võime otsida sinu dokumentidest. Kui keegi esitab mingi küsimuse, leiab süsteem asjakohase info ja lisab selle juhise hulka. Seejärel mudel vastab selle toomise baasil. -Mõtle RAG-le kui viitetuumale mudeli jaoks. Kui sa küsid küsimust, teeb süsteem: +Mõtle RAG-ile kui viidete raamatukogule mudelile. Kui esitad küsimuse, teeb süsteem järgmised sammud: -1. **Kasutaja päring** – sa esitad küsimuse -2. **Embedimine** – teisendab sinu küsimuse vektoriks -3. **Vektoripäring** – leiab sarnased dokumendi tükid -4. **Konteksti kokku panemine** – lisab vastavad tükid päringusse -5. **Vastus** – LLM genereerib vastuse põhinedes kontekstile +1. **Kasutaja päring** - Sa esitad küsimuse +2. **Embedding** - Konverteerib sinu küsimuse vektoriks +3. **Vektorotsing** - Leiab sarnase dokumendi tükid +4. **Konteksti kokkupanek** - Lisab asjakohased tükid juhisesse +5. **Vastus** - LLM genereerib vastuse konteksti põhjal -See seab mudeli vastused sinu tegelikele andmetele, mitte ei sõltu ainult treeningteadmistest või ei leiuta vastuseid ise. +See annab mudeli vastustele kindla baasi sinu tegelikest andmetest, mitte ei tugine üksnes treeningteadmistel ega improviseeri vastuseid. -## Eeldused +## Eelnõuded -- Läbitud [Moodul 00 - Kiire algus](../00-quick-start/README.md) (lihtsa RAG näite jaoks, mida selles moodulis hiljem käsitletakse) -- Läbitud [Moodul 01 - Sissejuhatus](../01-introduction/README.md) (kinnitatud Azure OpenAI ressursid, sh `text-embedding-3-small` manustumudel) -- Juurekaustas olemas `.env` fail Azure mandaadiga (loodud `azd up` käsklusega Moodulis 01) +- Lõpetatud [Moodul 01 - Sissejuhatus](../01-introduction/README.md) (Azure OpenAI ressursid paigaldatud, sh `text-embedding-3-small` embedimismudel) +- `.env` fail juurkataloogis koos Azure volitustega (loodud käsuga `azd up` Moodulis 01) -> **Märkus:** Kui sa ei ole veel Moodulit 01 lõpetanud, järgi esmalt seal olevaid paigaldusjuhiseid. Käsk `azd up` käivitab nii GPT vestlusmudeli kui ka manustumudeli, mida see moodul kasutab. +> **Märkus:** Kui sa ei ole lõpetanud Moodulit 01, järgi sealset paigaldusjuhendit esmalt. Käsk `azd up` paigaldab nii GPT vestlusmudeli kui ka selle mooduli embedimismudeli. ## RAG mõistmine -Järgmine diagramm illustreerib põhimõtet: selle asemel, et toetuda ainult mudeli treeningandmetele, annab RAG mudelile viiteraamatu sinu dokumentidest, mida ta saab enne vastuse genereerimist kasutada. +Joonis allpool illustreerib põhikontseptsiooni: RAG ei tugine üksnes mudeli treeningandmetele, vaid annab talle ligipääsu sinu dokumentide raamatukogule enne iga vastuse genereerimist. Mis on RAG -*See diagramm näitab erinevust tavapärase LLM-i (mis juhindub treeningandmetest) ning RAG-toega LLM-i vahel (mis esmalt otsib sinu dokumente).* +*Selles joonises näidatakse erinevust tavalise LLM vahel (mis oletab treeningandmete põhjal) ja RAG-ga tugevdatu vahel (mis esmalt kontrollib ära sinu dokumendid).* -Nii on tükid omavahel seotud. Kasutaja päring läbib neli sammu — manustamine, vektoripäring, konteksti kokku panemine ja vastuse genereerimine — igaüks toetub eelnevale: +Siin on sammud ükshaaval lõpp-punktini. Kasutaja küsimus liigub läbi nelja etapi — embedding, vektorotsingu, konteksti kokkupaneku ja vastuse genereerimise — igaüks tugineb eelnevale: RAG arhitektuur -*See diagramm näitab RAG täielikku torujuhtme — kasutaja päring läbib manustamise, vektoripäringu, konteksti kokkupaneku ja vastuse genereerimise.* +*Selles joonises on RAG töövool lõpp-punktini — kasutaja päring läbib embeddingu, vektorotsingu, konteksti kokku paneku ja vastuse genereerimise.* -Ülejäänud moodul kirjeldab iga etappi detailsemalt, koos koodinäidete ja diagrammidega. +Järgmised sektsioonid käivad läbi iga etapi, koos koodiga, mida saad käivitada ja muuta. ### Millist RAG lähenemist see juhend kasutab? -LangChain4j pakub kolme võimalust RAG-i rakendamiseks, igaühel erinev abstraktsioonitase. Allolev diagramm võrdleb neid kõrvuti: +LangChain4j pakub kolme RAG rakendamist, igaüks erineval abstraktsioonitasemel. Joonis allpool võrdleb neid kõrvuti: Kolm RAG lähenemist LangChain4j-s -*See diagramm võrdleb kolme LangChain4j RAG lähenemist — Lihtne, Natiivne ja Täiustatud — näidates nende peamisi komponente ja kasutusolukordi.* +*Selles joonises on kolm LangChain4j RAG lähenemist — Easy, Native ja Advanced — ning näidatakse nende põhikomponente ja kasutamise olukordi.* -| Lähenemine | Mida see teeb | Kompromiss | +| Lähenemine | Mida See Teeb | Kompromiss | |---|---|---| -| **Lihtne RAG** | Seob kõik automaatselt `AiServices` ja `ContentRetriever` kaudu. Sa märgid liidese, lisad taastele, ja LangChain4j haldab manustamist, otsingut ja päringu kokkupanekut tagaplaanil. | Vähe koodi, aga sa ei näe täpselt, mis igas etapis toimub. | -| **Natiivne RAG** | Sa kutsud ise manustusmudelit, otsid andmestikus, ehitad päringu ja genereerid vastuse — sammhaaval ja selgelt. | Rohkem koodi, aga iga etapp on nähtav ja kohandatav. | -| **Täiustatud RAG** | Kasutab `RetrievalAugmentor` raamistikku, kus on võimalik lisada päringumuundureid, marsruutereid, järjestajaid ja konteksti lisajaid tootmisklassi torujuhtmeks. | Kõrgeim paindlikkus, kuid ka märkimisväärne keerukus. | +| **Easy RAG** | Sidub kõik automaatselt läbi `AiServices` ja `ContentRetriever`. Sa märgistad liidese, lisad retriiveri ning LangChain4j haldab embedimist, otsingut ja käsu koostamist taga. | Vähe koodi, kuid sa ei näe, mis toimub igas sammus. | +| **Native RAG** | Sa kutsud embedimismudeli, otsid andmebaasist, koostad käsu ja genereerid vastuse ise — samm-sammult. | Rohkem koodi, kuid iga etapp on nähtav ja muudetav. | +| **Advanced RAG** | Kasutab `RetrievalAugmentor` raamistikku koos vahetatavate päringu muundurite, marsruuterite, ümberhinnangute ja sisendite lisajatega tootmiskvaliteediga torujuhtmete jaoks. | Maksimaalne paindlikkus, kuid palju keerulisem. | -**See juhend kasutab Natiivset lähenemist.** Iga RAG torujuhtme samm — päringu manustamine, vektoripäringu tegemine, konteksti koostamine ja vastuse genereerimine — on selgelt kirjas [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) failis. See on teadlik valik: õppematerjalina on tähtsam, et näeksid ja mõistaksid iga etappi, kui et kood oleks vähendatud. Kui oled senise tööga mugav, võid kiirete prototüüpide jaoks minna Lihtsa RAG juurde või tootmisprojektide jaoks Täiustatud RAG-i. +**See juhend kasutab Native lähenemist.** Iga RAG torujuhtme samm — päringu embedimine, vektoripoest otsimine, konteksti kogumine ja vastuse genereerimine — on selgelt lahti kirjutatud [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). See on teadlik valik: õppematerjalina on olulisem, et sa näeksid ja mõistaksid iga etappi, kui et kood oleks minimaalselt kirjutatud. Kui oled igas etapis mugav, võid üle minna Easy RAG-le kiireteks prototüüpideks või Advanced RAG-le tootmissüsteemide jaoks. -> **💡 Oled Lihtsat RAG-i juba näinud?** [Kiire alguse moodul](../00-quick-start/README.md) sisaldab dokumendi küsimuste ja vastuste näidet ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), mis kasutab Lihtsat RAG-i — LangChain4j haldab manustamist, otsingut ja päringu kokkupanekut automaatselt. See moodul võtab järgmise sammu, avades selle torujuhtme nii, et sa näed ja juhid iga etappi ise. +> **💡 Huvitatud Easy RAG-st?** LangChain4j pakub ka *Easy RAG* lähenemist, kus `AiServices` ja `ContentRetriever` haldavad embedimist, otsingut ja käsu koostamist automaatselt. See moodul kasutab selgemat teed — avab selle torujuhtme iga etapi, et sa näeksid ja kontrolliksid seda ise. -Allolev diagramm näitab Lihtsa RAG torujuhet eelmainitud Kiire alguse näitest. Märka, kuidas `AiServices` ja `EmbeddingStoreContentRetriever` peidavad kogu keerukuse — laed dokumendi, lisad taastaja ja saad vastused. Selle mooduli Natiivne lähenemine avab neid peidetud samme: +Joonis allpool näitab Easy RAG torujuhet. Märka, kuidas `AiServices` ja `EmbeddingStoreContentRetriever` varjavad kogu keerukust — sa laed dokumendi, lisad retriiveri ja saad vastused. Native lähenemine selles moodulis avab kõik need varjatud sammud: -Lihtne RAG torujuhe - LangChain4j +Easy RAG torujuht - LangChain4j -*See diagramm näitab Lihtsa RAG torujuhet `SimpleReaderDemo.java` failist. Võrdle seda Natiivse lähenemisega selles moodulis: Lihtne RAG peidab manustamise, taaste ja päringu kokkupaneku `AiServices` ja `ContentRetriever` taha — laed dokumendi, lisad taastaja ja saad vastused. Selle mooduli Natiivne lähenemine avab selle torujuhtme, nii et sa kutsud iga etappi (manusta, otsi, kogu kontekst, genereeri) ise, saades täieliku ülevaate ja kontrolli.* +*Selles joonises on Easy RAG torujuht. Võrdle seda Native lähenemisega selles moodulis: Easy RAG varjab embedimist, otsingut ja käsu koostamist `AiServices` ja `ContentRetriever` taga — sa laed dokumendi, lülitad retriiveri sisse ja saad vastused. Native lähenemine selles moodulis avab kogu torujuhtme, nii et sa kutsud iga etappi ise (embed, otsing, konteksti koostamine, genereerimine), pakkudes täisvaatlust ja kontrolli.* ## Kuidas see töötab -Selles moodulis jaguneb RAG torujuhe neljaks sammuks, mis toimuvad järjest iga kord, kui kasutaja esitab küsimuse. Esiteks analüüsitakse üleslaaditud dokument, mis jagatakse haldamiseks sobivateks tükkideks. Need tükid teisendatakse vektoriteks (manustusteks) ja salvestatakse, et neid saaks matemaatiliselt võrrelda. Päringu korral teeb süsteem semantilise otsingu, et leida kõige asjakohasemad tükid, ning edastab need kontekstina LLM-ile vastuse genereerimiseks. Järgnevad osad selgitavad iga sammu koos koodiga. - -Vaatame esmalt dokumendi töötlemist. +Selles moodulis jaguneb RAG torujuhe neljaks etapiks, mis käivad kasutaja iga küsimuse korral järjestikku läbi. Esmalt eelnevalt üles laetud dokument on **parsitakse ja tükkideks jagatud**, väiksemateks osadeks, mis mahuvad mugavalt mudeli kontekstiaknasse. Need tükid teisendatakse **vektoriteks** ehk embedimisteks ja säilitatakse, et neid saab matemaatiliselt võrrelda. Kui päring jõuab kohale, toimub **semantiline otsing**, et leida kõige asjakohasemad tükid. Lõpuks antakse need kontekstina LLM-ile vastuse genereerimiseks. Järgnevad osad selgitavad iga etappi koos reaalse koodi ja joonistega. Vaatame esimese sammu. ### Dokumendi töötlemine [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Kui sa dokumenti üles laed, süsteem analüüsib selle (PDF või lihttekst), lisab metainfot nagu failinimi ja seejärel jagab selle osadeks — väiksemateks tükkideks, mis mahuvad mudeli kontekstiväljale mugavalt. Need tükid kattuvad veidi, et piiril ei kaoks oluline kontekst. +Kui sa laed dokumendi üles, süsteem parsib selle (PDF või tavatekst), lisab metadata nagu failinimi ja jagab selle tükkideks — väiksemateks osadeks, mis mahuvad mudeli konteksti aknasse. Need tükid kattuvad osaliselt, et sa ei kaotaks konteksti servades. ```java -// Analüüsi üleslaaditud faili ja mässi see LangChain4j dokumendi sisse +// Töötle üleslaaditud fail ja paki see LangChain4j dokumendiks Document document = Document.from(content, metadata); -// Jaga 300-tokenilisteks tükkideks, millel on 30-tokeniline kattuvus +// Jaga 300 tokeni kaupa tükkideks, mis kattuvad 30 tokeniga DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -Allolev diagramm illustreerib seda visuaalselt. Märka, kuidas iga tükk jagab mõningaid tokeneid naaber tükkidega — 30-tokeni kattuvus tagab, et oluline kontekst ei jää vahele: + +Joonis allpool näitab seda visuaalselt. Märka, kuidas iga tükk jagab mõningaid tokeneid oma naabritega — 30-tokeniline kattumine tagab, et oluline kontekst ei kaotsi: Dokumendi tükeldamine -*See diagramm näitab dokumenti, mis on jagatud 300 tokeni suurusteks tükkideks, kus on 30-tokeniline kattuvus, säilitades konteksti tükkide piiridel.* +*Selles joonises näidatakse dokumenti, mis on jagatud 300 tokeni pikkusteks tükikesteks 30 tokeni kattumisega, säilitades konteksti tükkide servades.* -> **🤖 Proovi koos [GitHub Copilot](https://github.com/features/copilot) Chat’iga:** Ava [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ja küsi: -> - "Kuidas LangChain4j jagab dokumente tükkideks ja miks on kattuvus oluline?" -> - "Mis on optimaalne tüki suurus erinevate dokumentide jaoks ja miks?" +> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chati abil:** Ava [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ja küsi: +> - "Kuidas LangChain4j jagab dokumendid tükkideks ja miks kattumine on oluline?" +> - "Mis on optimaalne tüki suurus erinevate dokumentide jaoks ja miks?" > - "Kuidas käsitleda dokumente mitmes keeles või erilise vormindusega?" -### Manuste loomine +### Sissejuhatuste loomine [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Iga tükk teisendatakse numbriliseks kujutiseks, nn manustuseks — tähenduse teisendaja arvudeks. Manustumudel ise ei ole „tark“ nagu vestlusmudel; ta ei suuda juhiseid järgida, loogiliselt põhjendada ega küsimustele vastata. Mida ta teeb, on tekstikildude asukoha määramine matemaatilises ruumis, kus lähedased tähendused paiknevad üksteisele lähedal — „auto“ on lähedal „autole“, „tagasimakse poliitika“ lähedal „raha tagastamisele“. Mõtle vestlusmudelile kui inimesele, kellega rääkida; manustumudel on tõhus ja hea süsteem asjade sortimiseks. +Iga tükk teisendatakse numbriliseks esinduseks, mida nimetatakse embeddinguks — sisuliselt tähenduse ja numbrite konvertoriks. Embedimismudel pole "intelligentne" nagu vestlusmudel; ta ei suuda järgida juhiseid, arutleda ega vastata küsimustele. Mida ta teeb, on tekstide kaardistamine matemaatilisse ruumi, kus sarnased tähendused paiknevad üksteisele lähedal — näiteks "auto" ja "sõiduauto" on lähestikku, "tagasimakse poliitika" on lähedane "raha tagastamisele". Mõtle vestlusmudelit kui sõpra, kellega saab rääkida; embedimismudel on väga hea arhiveerimissüsteem. -Allolev diagramm illustreerib seda mõistet — tekst läheb sisse, numbrilised vektorid tulevad välja, ning sarnased tähendused tähistatakse vektoriruumi lähedal: +Joonis allpool visualiseerib seda kontseptsiooni — tekst sisse, numbrilised vektorid välja, ja sarnased tähendused tekitavad lähedalolevad vektorid: -Manustumudeli kontseptsioon +Embedimismudeli kontseptsioon -*See diagramm näitab, kuidas manustumudel teisendab teksti numbriliseks vektoriks, pannes sarnased tähendused — nagu „auto“ ja „automaat“ — üksteisele lähedale vektoriruumis.* +*Selles joonises on näidatud, kuidas embedimismudel konverteerib teksti numbrilisteks vektoriteks, pannes sarnased tähendused nagu "auto" ja "sõiduauto" vektoriruumis lähedale.* ```java @Bean @@ -155,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -Järgmine klassidiagramm näitab kahte sõltumatut voogu RAG torujuhtmes ja LangChain4j klasse, mis neid realiseerivad. **Sisseimemise voog** (käib ühe korra üleslaadimisel) jagab dokumendi tükkideks, manustab need ja salvestab `.addAll()` kaudu. **Päringuvoog** (igakordse kasutajapäringu ajal) manustab küsimuse, otsib salvestusest `.search()` kaudu ja edastab sobitatud konteksti vestlusmudelile. Mõlemad vood kohtuvad jagatud `EmbeddingStore` liidesel: + +Järgmine klassidiagramm näitab kahte eraldi töövoogu RAG torujuhtmes ja LangChain4j klasse, mis neid katavad. **Sisendvoog** (käivitatakse üleslaadimisel) jagab dokumendi, teeb tükkidele embeddingud ja salvestab need `.addAll()` meetodiga. **Päringuvoog** (käivitatakse iga kord, kui kasutaja esitab küsimuse) teeb päringust embeddingu, otsib poe kaudu `.search()` meetodiga ja annab leitud konteksti vestlusmudelile. Mõlemad vood kohtuvad jagatud `EmbeddingStore` liidese juures: LangChain4j RAG klassid -*See diagramm näitab kahte RAG voogu — sisseimemist ja päringut — ja nende ühendust ühise EmbeddingStore kaudu.* +*Selles joonises on RAG torujuhtme kaks voogu — sisend ja päring — ning nende ühendus ühise EmbeddingStore´i kaudu.* -Kui manused on salvestatud, koonduvad sarnased sisud loogiliselt vektoriruumi lähedale. Allolev visualisatsioon näitab, kuidas seotud teemad paistavad 3D-ruumis klastritena, mis teeb semantilise otsingu võimalikuks: +Kui embeddingud on salvestatud, koonduvad sarnased dokumendid loomulikult vektoriruumis kokku. Järgmine visualisatsioon näitab, kuidas seotud teemad koonduvad lähestikku punktidesse, mis võimaldab semantilist otsingut: -Vektormanuste ruum +Vektorite embeddingute ruum -*See visualisatsioon näitab, kuidas seotud dokumendid rühmituvad 3D vektoriruumi, moodustades erinevad grupid nagu tehnilised dokumendid, ärireeglid ja korduma kippuvad küsimused.* +*See visualisatsioon näitab seotud dokumentide koondumist 3D vektoriruumis, kus on eristuvad grupid nagu Tehnilised dokumendid, Ärieeskirjad ja KKK.* -Kui kasutaja otsib, järgib süsteem nelja sammu: manustab dokumendid kord, manustab päringu iga otsingu ajal, võrdleb päringu vektorit kõigi salvestatud vektoritega kosiinussarnasuse järgi ja tagastab tipp-K kõrgeima skooriga tükid. Allolev diagramm kirjeldab iga sammu ja kaasatud LangChain4j klasse: +Kui kasutaja otsib, toimib süsteem neljas etapis: embedib dokumendid ühekordselt, embedib iga otsingu päringu eraldi, võrdleb päringu vektorit kõigi salvestatud vektoritega koosiin sarnasuse alusel ja tagastab parima K skooriga tükid. Joonis allpool demonstreerib iga sammu koos vastavate LangChain4j klassidega: -Manustamise otsingu sammud +Embedimise otsingu sammud -*See diagramm näitab nelja sammu manustamise otsimusprotsessis: manusta dokumendid, manusta päring, võrdle vektoreid kosiinussarnasuse alusel ja tagasta tipp-K tulemid.* +*Selles joonises on neljaastmeline embedimise otsingu protsess: embedid dokumendid, embedid päringu, võrdled vektoreid koosiin sarnasuse alusel ja tagastad tipp-K tulemused.* ### Semantiline otsing [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Kui küsid küsimust, teisendatakse sinu küsimus samuti manustuseks. Süsteem võrdleb sinu päringu manustust kõigi dokumendi tükkide manustustega. Ta leiab kõige sarnasema tähendusega tükid — mitte ainult märksõnade kattuvuse põhjal, vaid tõelise semantilise sarnasuse alusel. +Kui sa esitad küsimuse, muutub ka sinu küsimus embeddinguks. Süsteem võrdleb sinu päringu embeddingut kõigi dokumenditükkide embeddingutega. Ta leiab tükid, mille tähendused on sarnasemad — mitte ainult märksõnade kattumised, vaid tegelik semantiline sarnasus. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -197,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -Allolev diagramm võrdleb semantilist otsingut tavapärase märksõnapõhise otsinguga. Märksõnapõhine „sõiduk“ otsing jätab leidmata tüki „autod ja veoautod“, kuid semantiline otsing mõistab, et need tähendavad sama asja ja tagastab selle kõrge skooriga tulemusena: + +Joonis allpool võrdleb semantilist otsingut traditsioonilise märksõnapõhise otsinguga. Märksõnapõhine otsing päringuga "sõiduk" jätab vahele mõned tükid teemal "autod ja veoautod", kuid semantiline otsing mõistab, et need tähendavad sama asja ja tagastab selle kõrge skooriga vasteidena: Semantiline otsing -*See diagramm võrdleb märksõnapõhist otsingut semantilise otsinguga, näidates kuidas viimane leiab mõistepõhiseid seotud sisusid ka siis, kui täpsed märksõnad ei lange kokku.* -Masinapõhiselt mõõdetakse sarnasust kasutades kosinussarnasust — sisuliselt küsides „Kas need kaks noolt osutavad sama suunda?“ Kaks lõiku võivad kasutada täiesti erinevaid sõnu, kuid kui nende tähendus on sama, osutavad nende vektorid samasse suunda ja skoorivad ligikaudu 1.0: +*Selles joonises võrreldakse märksõnapõhist otsingut semantilise otsinguga, mis leiab mõistepõhist seotud sisu ka siis, kui märksõnad erinevad.* -Kosinussarnasus +Tegelikult mõõdetakse sarnasust koosiiniga — küsimusega "kas need kaks noolt osutavad samasse suunda?" Kahe tükki sõnad võivad olla täiesti erinevad, kuid kui tähendused kattuvad, osutavad vektorid samasse suunda ja skoor on ligi 1.0: -*See diagramm illustreerib kosinussarnasust kui nurka manustatud vektorite vahel — rohkem joondunud vektorid skoorivad lähemale 1.0-le, mis näitab suuremat semantilist sarnasust.* +Koosiini sarnasus +*Selles diagrammis on kujutatud kosini sarnasust manustatud vektorite vahelise nurga kaudu — rohkem ühtlustatud vektorid saavad skoori lähemale 1,0-le, mis näitab kõrgemat semantilist sarnasust.* -> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chatiga:** Ava faili [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ja küsi: -> - "Kuidas töötab sarnasuse otsing manustega ja mis määrab skoori?" -> - "Millist sarnasuse läve peaksin kasutama ja kuidas see tulemusi mõjutab?" -> - "Kuidas käituda juhtudel, kui asjakohaseid dokumente ei leita?" +> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat'iga:** Ava [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ja küsi: +> - "Kuidas töötab sarnasusotsing manustustega ja mis määrab skoori?" +> - "Millist sarnasuse lävendit peaksin kasutama ja kuidas see tulemusi mõjutab?" +> - "Kuidas ma käsitlen olukordi, kus sobivaid dokumente ei leita?" -### Vastuse Genereerimine +### Vastuse loomine [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Kõige asjakohasemad lõigud koostatakse struktureeritud küsimuseks, mis sisaldab selgeid juhiseid, päringukonteksti ja kasutaja küsimust. Mudel loeb neid konkreetseid lõike ja vastab selle info põhjal — ta saab kasutada ainult seda, mis tal ees on, mis takistab hallutsinatsioone. +Kõige asjakohasemad lõigud koostatakse struktureeritud päringuks, mis sisaldab selgeid juhiseid, päringu konteksti ja kasutaja küsimust. Mudel loeb need konkreetsed lõigud ja vastab nende põhjal — ta saab kasutada ainult seda, mis on ees, mis takistab hallutsinatsiooni. ```java String context = matches.stream() @@ -239,65 +236,65 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Allolev diagramm näitab seda kokkupanekut tegevuses — otsingust saadud kõige paremini skoorivad lõigud süstitakse küsimuse malli ja `OpenAiOfficialChatModel` genereerib kinnitatud vastuse: +Allolev diagramm näitab seda kokkupanekut tegevuses — otsingust parima skooriga lõigud sisestatakse päringumalli ja `OpenAiOfficialChatModel` genereerib põhjaliku vastuse: -Konteksti Kokkupanek +Context Assembly -*See diagramm näitab, kuidas kõrgeima skooriga lõigud koostatakse struktureeritud küsimuseks, võimaldades mudelil genereerida kinnitatud vastuse teie andmetest.* +*Selles diagrammis näidatakse, kuidas parima skooriga lõigud kogutakse struktureeritud päringusse, mis võimaldab mudelil teie andmetest põhjendatud vastust genereerida.* -## Rakenduse Käivitamine +## Rakenduse käivitamine -**Kontrolli deployd:** +**Kontrolli paigaldust:** -Veendu, et `.env` fail asub juurkataloogis Azure'i mandaatidega (loodud moodulis 01). Käivita see mooduli kataloogist (`03-rag/`): +Veendu, et juurkataloogis oleks olemas `.env` fail koos Azure volitustega (loodud moodulis 01). Käivita see mooduli kataloogist (`03-rag/`): **Bash:** ```bash -cat ../.env # Peaks näitama AZURE_OPENAI_ENDPOINT-i, API_KEY-d, DEPLOYMENT-i +cat ../.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Tuleks näidata AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Alusta rakendust:** -> **Märkus:** Kui alustasid juba kõigi rakendustega `./start-all.sh` abil juurkataloogist (nagu kirjeldatud moodulis 01), töötab see moodul juba pordil 8081. Võid alltoodud käsud vahele jätta ja minna otse http://localhost:8081. +> **Märkus:** Kui oled juba käivitanud kõik rakendused käsuga `./start-all.sh` juurkataloogist (nagu moodulis 01 kirjeldatud), töötab see moodul juba pordil 8081. Võid allolevad käivitamiskäsud vahele jätta ja minna otse aadressile http://localhost:8081. -**Valik 1: Spring Boot Dashboardi kasutamine (Soovitatav VS Code kasutajatele)** +**Variant 1: Kasutades Spring Boot Dashboardi (Soovitatav VS Code kasutajatele)** -Arenduscontainer sisaldab Spring Boot Dashboard laiendust, mis pakub visuaalset kasutajaliidest kõigi Spring Boot rakenduste haldamiseks. Leiad selle aktiivsusribalt VS Code vasakul pool (otsige Spring Boot ikooni). +Arendus konteiner sisaldab Spring Boot Dashboard laiendust, mis pakub visuaalset liidest kõigi Spring Boot rakenduste haldamiseks. Selle leiad VS Code vasakult küljeribalt (otsi Spring Boot ikooni). -Spring Boot Dashboardilt saad: +Spring Boot Dashboardist saad: - Näha kõiki tööruumis olevaid Spring Boot rakendusi - Käivitada/peatada rakendusi ühe klikiga - Vaadata rakenduse logisid reaalajas -- Jälgida rakenduse olekut +- Jälgida rakenduste olekut -Lihtsalt kliki "rag" kõrval olevale play-nupule selle mooduli käivitamiseks või alusta korraga kõiki mudeleid. +Lihtsalt klõpsa nupule "rag" kõrval, et käivitada see moodul või alusta korraga kõiki mooduleid. Spring Boot Dashboard -*See kuvatõmmis näitab Spring Boot Dashboardi VS Codes, kus saad visuaalselt rakendusi käivitada, peatada ja jälgida.* +*Sellel ekraanipildil on näha Spring Boot Dashboard VS Codes, kus saad rakendusi visuaalselt käivitada, peatada ja jälgida.* -**Valik 2: Shell skriptide kasutamine** +**Variant 2: Kasutades käsurea skripte** Käivita kõik veebirakendused (moodulid 01-04): **Bash:** ```bash -cd .. # Juure kataloogist +cd .. # Juurekataloogist ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Juurekataloogist +cd .. # Juure kataloogist .\start-all.ps1 ``` -Või alusta ainult seda moodulit: +Või käivita vaid see moodul: **Bash:** ```bash @@ -311,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Mõlemad skriptid laadivad automaatselt keskkonnamuutujaid juurpõhjast `.env` failist ja ehitavad JAR-id, kui need puuduvad. +Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurkataloogist `.env` failist ning ehitavad JARid, kui neid pole veel olemas. -> **Märkus:** Kui soovid enne käivitust kõik moodulid käsitsi ehitada: +> **Märkus:** Kui soovid ehitada kõik moodulid käsitsi enne käivitamist: > > **Bash:** > ```bash @@ -345,95 +342,95 @@ cd .. && ./stop-all.sh # Kõik moodulid cd ..; .\stop-all.ps1 # Kõik moodulid ``` -## Rakenduse Kasutamine +## Rakenduse kasutamine -Rakendus pakub veebiliidest dokumentide üleslaadimiseks ja küsimiseks. +Rakendus pakub veebiliidest dokumentide üleslaadimiseks ja küsimuste esitamiseks. -RAG rakenduse kasutajaliides +RAG Application Interface -*See kuvatõmmis näitab RAG rakenduse kasutajaliidest, kus saad üles laadida dokumente ja esitada küsimusi.* +*Sellel ekraanipildil on näha RAG rakenduse liides, kus saad dokumente üles laadida ja küsimusi esitada.* ### Dokumendi üleslaadimine -Alusta dokumendi üleslaadimisest – testimisel sobivad kõige paremini TXT failid. Selle kataloogi on lisatud `sample-document.txt`, mis sisaldab infot LangChain4j omaduste, RAG implementatsiooni ja parimate tavade kohta – ideaalne süsteemi testimiseks. +Alusta dokumendi üleslaadimisega — testimiseks sobivad kõige paremini TXT-failid. Selles kataloogis on olemas `sample-document.txt`, mis sisaldab infot LangChain4j omaduste, RAG rakenduse ja parimate tavade kohta — ideaalne süsteemi testimiseks. -Süsteem töötleb su dokumendi, jagab selle lõikudeks ja loob iga lõigu jaoks manused. See toimub automaatselt kohe peale üleslaadimist. +Süsteem töötleb sinu dokumendi, jagab selle lõikudeks ja loob igale lõigule manustused. See toimub automaatselt pärast üleslaadimist. -### Küsimuste Esitamine +### Küsi küsimusi -Nüüd esita konkreetseid küsimusi dokumenti sisu kohta. Proovi faktilisi küsimusi, mis on dokumendis selgelt välja toodud. Süsteem otsib asjakohased lõigud, lisab need küsimuse konteksti ja genereerib vastuse. +Esita nüüd dokumendi sisu kohta konkreetseid küsimusi. Proovi midagi faktilist, mis on dokumendis selgelt välja toodud. Süsteem otsib asjakohaseid lõike, lisab need päringusse ja genereerib vastuse. -### Allika Viidete Kontrollimine +### Kontrolli allikaviiteid -Pange tähele, et iga vastus sisaldab allika viiteid koos sarnasuse skooridega. Need skoorid (0 kuni 1) näitavad, kui asjakohane iga lõik sinu küsimusega oli. Kõrgemad skoorid tähendavad paremaid vasteid. Sellega saad vastuse kontrollida allikmaterjali vastu. +Pane tähele, et iga vastus sisaldab allikaviiteid koos sarnasusskooridega. Need skoorid (0 kuni 1) näitavad, kui asjakohane iga lõik oli sinu küsimusele. Kõrgemad skoorid tähendavad paremaid vasteid. See võimaldab sul vastuse võrrelda algallikaga. -RAG päringu tulemused +RAG Query Results -*See kuvatõmmis näitab päringu tulemusi koos genereeritud vastuse, allika viidete ja iga leitud lõigu asjakohasuse skooriga.* +*Sellel ekraanipildil on näha päringu tulemused koos genereeritud vastuse, allikaviidete ja iga leitud lõigu asjakohasuskoori.* -### Küsitlusega Katsetamine +### Katseta küsimustega Proovi erinevat tüüpi küsimusi: -- Konkreetsed faktid: "Mis on peamine teema?" +- Konkreetsed faktid: "Mis on põhiteema?" - Võrdlused: "Mis vahe on X ja Y vahel?" -- Kokkuvõtted: "Kokkuvõtke Z põhiteemad" +- Kokkuvõtted: "Kokkuvõtte põhikohad Z kohta" -Jälgi, kuidas asjakohasuse skoorid muutuvad vastavalt sellele, kui hästi su küsimus dokumenti sobib. +Vaata, kuidas muutuvad asjakohasus skoorid vastavalt sellele, kui hästi sinu küsimus dokumendi sisuga sobib. -## Põhimõisted +## Olulised mõisted -### Lõikude Jagamise Strateegia +### Lõikude strateegia -Dokumendid jagatakse 300 märgiga lõikudeks, millel on 30 märgiline kattuvus. See tasakaal tagab, et iga lõik sisaldab piisavalt konteksti, et olla tähenduslik, samas jäädes piisavalt väikeseks, et mahutada mitut lõiku ühte küsimusse. +Dokumendid jagatakse 300-token'ilise pikkusega lõikudeks, kus on 30 tokeni kattuvust. See tasakaal tagab, et igal lõigul on piisavalt konteksti, et olla tähenduslik, kuid samas piisavalt väike, et mahtuda päringusse mitu lõiku. -### Sarnasuse Skoorid +### Sarnasusskoorid -Iga leitud lõikuga tuleb kaasas sarnasuse skoor 0 kuni 1, mis näitab, kui lähedalt see kasutaja küsimusele vastab. Alljärgnev diagramm visualiseerib skooride vahemikke ja seda, kuidas süsteem neid tulemuste filtreerimiseks kasutab: +Iga leitud lõik on varustatud sarnasusskooriga vahemikus 0 kuni 1, mis näitab kui hästi see kasutaja küsimusega vastab. Järgmine diagramm visualiseerib skooride vahemikke ja kuidas süsteem neid tulemuste filtreerimiseks kasutab: -Sarnasuse Skoorid +Similarity Scores -*See diagramm näitab skooride vahemikke 0 kuni 1, kus minimaalne lävi on 0.5, mis filtreerib välja asjakohatud lõigud.* +*Selles diagrammis on näha skooride vahemikud 0 kuni 1, kus minimaalseks lävendiks on 0,5, mis filtreerib välja ebasobivad lõigud.* -Skoorid jäävad vahemikku 0 kuni 1: -- 0.7-1.0: Väga asjakohane, täpne vaste -- 0.5-0.7: Asjakohane, hea kontekst -- Alla 0.5: Filtreeritud välja, liiga erinev +Skoorid on vahemikus 0 kuni 1: +- 0,7–1,0: Väga asjakohane, täpne vaste +- 0,5–0,7: Asjakohane, hea kontekst +- Alla 0,5: Filtreeritud välja, liiga erinev -Süsteem tagastab ainult lõigud, mis ületavad miinimalläve, et tagada kvaliteet. +Süsteem otsib ainult lõikeid, mis ületavad minimaalse lävendi, kvaliteedi tagamiseks. -Manused töötavad hästi, kui tähendused klastrites selged on, kuid neil on ka pimedad kohad. Järgnev diagramm näitab levinud ebaõnnestumise viise — liiga suured lõigud annavad ebaselged vektorid, liiga väikesed lõigud on kontekstist vaesed, mitmetähenduslikud terminid viitavad mitmele klastrile ja täpse vaste otsingud (ID-d, osanumber) ei tööta manustega sugugi: +Manustused töötavad hästi selgete tähenduste rühmitamisel, kuid neil on ka kitsaskohad. Järgmine diagramm näitab levinud veaolukordi — liiga suured lõigud annavad uduseid vektoreid, liiga väikesed lõigud puuduvad konteksti, mitmetähenduslikud terminid viitavad mitmele rühmale ja täpsed otsingud (ID-d, osanumbrids) ei tööta manustustega üldse: -Manuse ebaõnnestumise režiimid +Embedding Failure Modes -*See diagramm näitab levinud manustamise ebaõnnestumise vorme: liiga suured lõigud, liiga väikesed lõigud, mitmetähenduslikud terminid, mis viitavad mitmele klastrile, ning täpsed vasteotsingud nagu ID-d.* +*Selles diagrammis on näha levinumaid manustamise veaolukordi: liiga suured lõigud, liiga väikesed lõigud, mitmetähenduslikud terminid, mis viitavad mitmele rühmale, ja täpsed otsingud nagu ID-d.* -### Mälu Põhine Andmesalvestus +### Mälupõhine salvestus -See moodul kasutab lihtsuse huvides mälusalvestust. Rakenduse taaskäivitamisel kaovad üles laaditud dokumendid. Tootmiskeskkonnas kasutatakse püsivaid vektorandmebaase nagu Qdrant või Azure AI Search. +See moodul kasutab lihtsuse huvides mälus hoidmist. Rakenduse taaskäivitamisel kaovad üleslaaditud dokumendid. Tootmiskeskkonnas kasutatakse püsivaid vektorandmebaase nagu Qdrant või Azure AI Search. -### Konteksti Akna Halduse +### Konteksti akna haldamine -Igal mudelil on maksimaalne konteksti aken. Sa ei saa lisada kõiki lõike väga suurest dokumendist. Süsteem tagastab kõige asjakohasemad N lõiku (vaikimisi 5), et jääda piiridesse, kuid pakkuda piisavalt konteksti täpsete vastuste jaoks. +Igal mudelil on maksimaalne konteksti akna suurus. Suurtest dokumentidest ei saa kõiki lõike korraga lisada. Süsteem otsib üles parima N asjakohased lõigud (vaikimisi 5), et jääda piiridesse, pakkudes samas piisavalt konteksti täpsete vastuste andmiseks. -## Millal RAG Loeb +## Millal RAG on oluline -RAG ei ole alati õige lahendus. Järgmine otsustusjuhend aitab sul otsustada, millal RAG lisab väärtust võrreldes lihtsamate lähenemisviisidega — nagu sisu otse küsimusse lisamine või mudeli sisseehitatud teadmiste kasutamine: +RAG ei ole alati parim lahendus. Järgmine otsusjuht aitab määrata, millal RAG lisab väärtust ja millal lihtsamad lahendused — nagu sisu otse päringusse lisamine või mudeli sisseehitatud teadmiste kasutamine — on piisavad: -Millal kasutada RAG'i +When to Use RAG -*See diagramm näitab otsustusjuhendit, millal RAG lisab väärtust ja millal piisavad lihtsamad lähenemised.* +*Selles diagrammis on otsustustugi, mis näitab, millal RAG lisab väärtust ja millal lihtsamad lahendused on piisavad.* -## Järgmised Sammud +## Järgmised sammud -**Järgmine moodul:** [04-tools - Tehisintellekti agendid tööriistadega](../04-tools/README.md) +**Järgmine moodul:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**Navigeerimine:** [← Eelmine: Moodul 02 - Küsitluste inseneritöö](../02-prompt-engineering/README.md) | [Tagasi Avalehile](../README.md) | [Järgmine: Moodul 04 - Tööriistad →](../04-tools/README.md) +**Navigeerimine:** [← Eelmine: Moodul 02 - Päringute konstrueerimine](../02-prompt-engineering/README.md) | [Tagasi avalehele](../README.md) | [Järgmine: Moodul 04 - Tööriistad →](../04-tools/README.md) --- -**Vastutusest loobumine**: -See dokument on tõlgitud kasutades tehisintellektil põhinevat tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi püüdleme täpsuse poole, palun pange tähele, et automaatsed tõlked võivad sisaldada vigu või ebatäpsusi. Algset dokumenti selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalse inimtõlke teenust. Me ei vastuta selle tõlke kasutamisest tulenevate arusaamatuste või väärinterpreteerimiste eest. +**Lahtiütlus**: +See dokument on tõlgitud kasutades AI tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest. \ No newline at end of file diff --git a/translations/et/04-tools/README.md b/translations/et/04-tools/README.md index 19e482e3f..c31c7d945 100644 --- a/translations/et/04-tools/README.md +++ b/translations/et/04-tools/README.md @@ -1,84 +1,84 @@ -# Moodul 04: Tehisintellekti agendid tööriistadega +# Moodul 04: AI Agendid tööriistadega ## Sisukord -- [Video juhend](../../../04-tools) -- [Mida õpite](../../../04-tools) -- [Eeldused](../../../04-tools) -- [Tehisintellekti agentide mõistmine tööriistadega](../../../04-tools) -- [Kuidas tööriistakutse töötab](../../../04-tools) - - [Tööriistade definitsioonid](../../../04-tools) - - [Otsuste tegemine](../../../04-tools) - - [Täideviimine](../../../04-tools) - - [Vastusvõime genereerimine](../../../04-tools) - - [Arhitektuur: Spring Boot automaatühendus](../../../04-tools) -- [Tööriistade aheldamine](../../../04-tools) -- [Rakenduse käivitamine](../../../04-tools) -- [Rakenduse kasutamine](../../../04-tools) - - [Proovi lihtsat tööriista kasutust](../../../04-tools) - - [Testi tööriistade aheldamist](../../../04-tools) - - [Vaata vestluse kulgu](../../../04-tools) - - [Katseta erinevate päringutega](../../../04-tools) -- [Põhikontseptsioonid](../../../04-tools) - - [ReAct muster (põhjendamine ja tegutsemine)](../../../04-tools) - - [Tööriistade kirjeldused on olulised](../../../04-tools) - - [Seansi haldus](../../../04-tools) - - [Veadega toimetulek](../../../04-tools) -- [Saadaval olevad tööriistad](../../../04-tools) -- [Millal kasutada tööriistapõhiseid agente](../../../04-tools) -- [Tööriistad vs RAG](../../../04-tools) -- [Järgmised sammud](../../../04-tools) - -## Video juhend - -Vaadake seda otseülekannet, mis selgitab, kuidas selle mooduliga alustada: +- [Video Juhend](#video-juhend) +- [Mida Sa Õpid](#mida-sa-õpid) +- [Eeltingimused](#eeltingimused) +- [AI Agentide Mõistmine Tööriistadega](#ai-agentide-mõistmine-tööriistadega) +- [Kuidas Tööriista Kutsumine Töötab](#kuidas-tööriista-kutsumine-töötab) + - [Tööriistade Definitsioonid](#tööriistade-definitsioonid) + - [Otsuste Tegemine](#otsuste-tegemine) + - [Täideviimine](#täideviimine) + - [Vastuse Genereerimine](#vastuse-genereerimine) + - [Arhitektuur: Spring Boot Automaatühendus](#arhitektuur-spring-boot-automaatühendus) +- [Tööriistade Järgnevus](#tööriistade-järgnevus) +- [Rakenduse Käivitamine](#rakenduse-käivitamine) +- [Rakenduse Kasutamine](#rakenduse-kasutamine) + - [Proovi Lihtsat Tööriista Kasutust](#proovi-lihtsat-tööriista-kasutust) + - [Testi Tööriistade Järgnevust](#testi-tööriistade-ahelat) + - [Vaata Vestluse Voogu](#vaata-vestluse-voogu) + - [Katseta Erinevate Päringutega](#katseta-erinevate-päringutega) +- [Olulised Mõisted](#peamised-kontseptsioonid) + - [ReAct Muster (Põhjendamine ja Tegutsemine)](#react-muster-põhjus-ja-tegutsemine) + - [Tööriistade Kirjeldused on Tähtsad](#tööriistade-kirjeldused-on-tähtsad) + - [Sessioonihaldus](#sessiooni-haldus) + - [Vigade Käitlemine](#veahaldus) +- [Saadaval Tööriistad](#saadaval-olevad-tööriistad) +- [Millal Kasutada Tööriistapõhiseid Agente](#millal-kasutada-tööriistapõhiseid-agente) +- [Tööriistad vs RAG](#tööriistad-vs-rag) +- [Järgmised Sammud](#järgmised-sammud) + +## Video Juhend + +Vaata seda otseülekannet, mis selgitab, kuidas selle mooduliga alustada: AI Agents with Tools and MCP - Live Session -## Mida õpite +## Mida Sa Õpid -Seni olete õppinud, kuidas tehisintellektiga vestelda, vormistada päringuid efektiivselt ning siduda vastuseid oma dokumentidega. Kuid on olemas põhiepitsus: keelemudelid suudavad genereerida ainult teksti. Nad ei saa ilma abiliste ja tööriistadeta ilmaennustust kontrollida, arvutusi teha, andmebaase pärida ega välissüsteemidega suhelda. +Nii kaugele oled õppinud, kuidas pidada vestlusi AI-ga, struktureerida tõhusaid prompt’e ja põhendada vastuseid oma dokumentides. Kuid on endiselt põhimõtteline piirang: keelemudelid saavad vaid teksti genereerida. Nad ei saa ilmaennustust teha, arvutusi lahendada, andmebaase pärida ega suhelda väliste süsteemidega. -Tööriistad muudavad selle. Kui mudelile anda võimalus kutsuda funktsioone, muudate temast tekstigeneraatori asemel agendi, kes saab tegutseda. Mudel otsustab, millal tal tööriista vaja on, millist tööriista kasutada ja milliseid parameetreid edasi anda. Teie kood täidab funktsiooni ja tagastab tulemuse. Mudel integreerib selle tulemuse oma vastusesse. +Tööriistad muudavad selle. Anda mudelile juurdepääs funktsioonidele, mida ta saab kutsuda, muudab selle tekstigeneraatorist agendiks, kes suudab tegutseda. Mudel otsustab, millal tal on vaja tööriista, millist tööriista kasutada ja milliseid parameetreid edastada. Sinu kood täidab funktsiooni ja tagastab tulemuse. Mudel kasutab seda tulemust oma vastuses. -## Eeldused +## Eeltingimused -- On läbitud [Moodul 01 - Sissejuhatus](../01-introduction/README.md) (Azure OpenAI ressursid paigaldatud) -- Soovitatavalt on läbitud varasemad moodulid (see moodul viitab [RAG kontseptsioonidele Moodulis 03](../03-rag/README.md) tööriistade ja RAG võrdluses) -- Juurkausta `.env` fail Azure volitustega (loodud `azd up` käsuga Moodul 01 jooksul) +- Läbitud [Moodul 01 - Sissejuhatus](../01-introduction/README.md) (Azure OpenAI ressursid juurutatud) +- Soovitatavalt läbitud varasemad moodulid (see moodul viitab [RAG kontseptsioonidele Moodulis 03](../03-rag/README.md) Tööriistade vs RAG võrdluses) +- Juurekataloogis asuv `.env` fail Azure volitustega (loodud `azd up` abil Moodulis 01) -> **Märkus:** Kui te pole Moodulit 01 läbinud, järgige esmalt seal olevaid juurutusjuhiseid. +> **Märkus:** Kui sa pole veel Moodulit 01 läbinud, järgi esmalt seal olevaid juurutusjuhiseid. -## Tehisintellekti agentide mõistmine tööriistadega +## AI Agentide Mõistmine Tööriistadega -> **📝 Märkus:** Selles moodulis tähendab "agentide" all tehisintellektipõhiseid abistajaid, kellel on tööriistakutsete võimekus. See erineb **Agentic AI** mustritest (iseseisvad agendid planeerimise, mälu ja mitmeastmelise mõtlemisega), mida käsitleme [Moodulis 05: MCP](../05-mcp/README.md). +> **📝 Märkus:** Selles moodulis viitab mõiste "agendid" AI assistentidele, millel on tööriista kutsumise võimekus. See erineb **Agentic AI** mustritest (autonoomsed agendid planeerimise, mälu ja mitmeastmelise põhjendamisega), mida käsitleme [Moodulis 05: MCP](../05-mcp/README.md). -Ilma tööriistadeta suudab keelemudel genereerida teksti ainult oma treeningandmete põhjal. Küsi temalt ilmateadet ja ta peab arvama. Kui anda tööriistad, saab ta kutsuda ilma API-t, teha arvutusi või pärida andmebaasi — ning neid tegelikke tulemusi oma vastusesse kanda. +Ilma tööriistadeta saab keelemudel ainult oma treeningandmetest teksti genereerida. Küsi ilmakaarti ja ta peab aimama. Anna talle tööriistad ja ta saab kutsuda ilma API, teha arvutusi või andmebaasi päringuid — ning põimida need reaalsete tulemused oma vastusesse. -Ilma tööriistadeta vs tööriistadega +Ilma Tööriistadeta vs Tööriistadega -*Ilma tööriistadeta mudel ainult arvab — tööriistadega saab ta kutsuda API-sid, teha arvutusi ja tagastada reaalajas andmeid.* +*Ilma tööriistadeta saab mudel ainult oletada — tööriistadega saab ta kutsuda API-sid, teha arvutusi ja tagastada reaalajas andmeid.* -Tehisintellekti agent tööriistadega järgib **Reasoning and Acting (ReAct)** mustrit. Mudel ei vastagi lihtsalt — ta mõtleb, mida vajab, kutsub tööriista, jälgib tulemust ning otsustab siis, kas tegutseda edasi või anda lõplik vastus: +AI agent tööriistadega järgib **Põhjendamise ja Tegutsemise (ReAct)** mustrit. Mudel ei vasta lihtsalt — ta mõtleb, mida vajab, tegutseb tööriista kutsumisega, jälgib tulemust ja otsustab, kas tegutseda uuesti või anda lõplik vastus: -1. **Põhjenda** — Agent analüüsib kasutaja küsimust ja tuvastab vajaliku info -2. **Tegu** — Agent valib õige tööriista, genereerib korrektseid parameetreid ja kutsub selle -3. **Jälgi** — Agent saab tööriista väljundi ja hindab tulemust -4. **Korda või vasta** — Kui vaja on rohkem andmeid, kordab agent tsüklit; vastasel juhul koostab loomuliku keele vastuse +1. **Põhjenda** — Agent analüüsib kasutaja küsimust ja määrab vajaliku info +2. **Tegutse** — Agent valib sobiva tööriista, genereerib õiged parameetrid ja kutsub selle +3. **Vaatle** — Agent saab tööriista väljundi ja hindab tulemust +4. **Korda või Vasta** — Kui vaja rohkem andmeid, kordab agent tsüklit; muidu koostab loomuliku keele vastuse -ReAct muster +ReAct Muster -*ReAct tsükkel — agent põhjendab, mida teha, kutsub tööriista, jälgib tulemust ja kordab, kuni suudab anda lõpliku vastuse.* +*ReAct tsükkel — agent põhjendab, mida teha, tegutseb tööriista kutsumisega, vaatleb tulemust ja kordab kuni lõpliku vastuse esitamiseni.* -See toimub automaatselt. Te ise määratlete tööriistad ja nende kirjeldused. Mudel teeb otsuse, millal ja kuidas neid kasutada. +See toimub automaatselt. Sa defineerid tööriistad ja nende kirjeldused. Mudel haldab otsustamist, millal ja kuidas neid kasutada. -## Kuidas tööriistakutse töötab +## Kuidas Tööriista Kutsumine Töötab -### Tööriistade definitsioonid +### Tööriistade Definitsioonid [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Te määratlete funktsioonid selgete kirjelduste ja parameetrispetsifikatsioonidega. Mudel näeb neid kirjeldusi oma süsteemi promptis ja mõistab, mida iga tööriist teeb. +Sa defineerid funktsioonid selgete kirjelduste ja parameetrite spetsifikatsioonidega. Mudel näeb neid kirjeldusi oma süsteemipromptis ja mõistab, mida iga tööriist teeb. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Teie ilmaotsingu loogika + // Teie ilmainfo päringu loogika return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,153 +96,153 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Assistent on Spring Booti poolt automaatselt ühendatud järgmistega: -// - ChatModel komponent +// Abi on Spring Booti poolt automaatselt ühendatud järgmistega: +// - ChatModel bean // - Kõik @Tool meetodid @Component klassidest -// - ChatMemoryProvider sessioonihalduseks +// - ChatMemoryProvider sessiooni haldamiseks ``` -Järgmine diagramm lahtiseletab iga annotatsiooni ja näitab, kuidas iga osa aitab tehisintellektil mõista, millal tööriista kutsuda ja milliseid argumente edasi anda: +Järgmine skeem lahti seletab iga annotatsiooni ja näitab, kuidas iga osa aitab tehisintellektil mõista, millal tööriista kutsuda ja milliseid argumente edastada: -Tööriista definitsiooni anatoomia +Tööriista Definitsioonide Anatoomia -*Tööriista definitsiooni anatoomia — @Tool ütleb AI-le, millal seda kasutada, @P kirjeldab iga parameetrit ning @AiService ühendab kõik käivitamisel.* +*Tööriistade definitsiooni anatoomia — @Tool ütleb tehisintellektile, millal seda kasutada, @P kirjeldab iga parameetrit ja @AiService ühendab kõik käivitamisel.* -> **🤖 Proovi koos [GitHub Copilot](https://github.com/features/copilot) Chatiga:** Ava [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ja küsi: -> - "Kuidas integreerida päris ilma API nagu OpenWeatherMap, mitte tehisandmeid?" -> - "Mis on hea tööriistakirjelduse omadused, mis aitavad AI-l seda korrektselt kasutada?" -> - "Kuidas käidelda API-vigu ja piiranguid tööriistade rakendamisel?" +> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat’iga:** Ava [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ja küsi: +> - "Kuidas integreerida päris ilma API nagu OpenWeatherMap simuleeritud andmete asemel?" +> - "Mis teeb tööriista kirjelduse heaks ja aitab AI kasutamisel seda õigesti kasutada?" +> - "Kuidas käsitleda API vigu ja päringu piire tööriista rakendustes?" -### Otsuste tegemine +### Otsuste Tegemine -Kui kasutaja küsib: "Milline on ilm Seattle'is?", ei vali mudel tööriista juhuslikult. Ta võrdleb kasutaja kavatsust iga tööriista kirjeldusega, hindab iga relevantsust ja valib parima vaste. Ta genereerib struktureeritud funktsioonikutse õigetel parameetritel — antud juhul seatakse `location` väärtuseks `"Seattle"`. +Kui kasutaja küsib "Milline on ilm Seattle’is?", ei vali mudel tööriista juhuslikult. Ta võrdleb kasutaja tahet kõigi tema käsutuses olevate tööriistade kirjeldustega, hinde igaüht asjakohasuse põhjal ja valib parima vaste. Seejärel genereerib struktureeritud funktsiooni kutsumise õigete parameetritega — antud juhul seab `location` väärtuseks `"Seattle"`. -Kui ükski tööriist ei sobi kasutaja päringuga, vastab mudel oma teadmiste põhjal. Kui sobivaid tööriistu on mitu, valib kõige spetsiifilisema. +Kui ükski tööriist ei vasta kasutaja päringule, vastab mudel oma teadmiste põhjal. Kui sobivaid tööriistu on mitu, valib kõige spetsiifilisema. -Kuidas AI otsustab, millist tööriista kasutada +Kuidas AI Otsustab, Millist Tööriista Kasutada -*Mudel hindab iga saadavaloleva tööriista kasutaja kavatsuse vastu ja valib parima sobivuse — seepärast on oluline kirjutada selge ja konkreetne tööriistakirjeldus.* +*Mudel hindab kõiki olemasolevaid tööriistu kasutaja eesmärgiga ja valib parima sobivuse — sellepärast on selgete ja spetsiifiliste tööriistakirjelduste kirjutamine oluline.* ### Täideviimine [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot ühendab automaatselt deklaratiivse `@AiService` liidese kõigi registreeritud tööriistadega ning LangChain4j täidab tööriistakutsed automaatselt. Tagatipuks voolab komplektne tööriistakutse kuue etapi kaudu — kasutaja loomulikust keeles küsimusest tagasi loomuliku keele vastuseni: +Spring Boot ühendab deklaratiivse `@AiService` liidese kõigi registreeritud tööriistadega automaatselt ning LangChain4j täidab tööriistakutsed ise. Tagaplaanil kulgeb täiesti tööriistakutse kuue faasiga — kasutaja loomuliku keele küsimusest loodusesse vastuseni tagasi: -Tööriistakutse voog +Tööriistakutse Voog -*Täielik voog — kasutaja esitab küsimuse, mudel valib tööriista, LangChain4j täidab selle ja mudel lõimib tulemuse loomulikuks vastuseks.* +*Algusest lõpuni voog — kasutaja esitab küsimuse, mudel valib tööriista, LangChain4j täidab selle ja mudel põimib tulemuse loomulikku vastusesse.* -Kui käivitasite [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) Moodulis 00, nägite seda mustrit töös — `Calculator` tööriistad kutsuti täpselt samamoodi. Järgmine järjestusdiagramm näitab täpselt, mis sel ajal toimus: +Tagaplaanil käivitab `AiServices` sama tööriistakutsete tsükli iga tööriista jaoks — siin lihtsustatud `Calculatori` näitel. Allolev järjestusdiagramm näitab täpselt, mis toimub allapoole vooludes: -Tööriistakutsede järjestusdiagramm +Tööriistakutse Järjestusdiagramm -*Tööriistakutse tsükkel Quick Start demos — `AiServices` saadab teie sõnumi ja tööriistade skeemid LLM-ile, LLM vastab funktsioonikutsega nagu `add(42, 58)`, LangChain4j täidab kohapeal `Calculator` meetodi ja tagastab tulemuse lõplikuks vastuseks.* +*Tööriistakutse tsükkel — `AiServices` saadab su sõnumi ja tööriistaskemad LLM-ile, LLM vastab funktsioonikutsena nagu `add(42, 58)`, LangChain4j täidab kohalikult `Calculator` meetodi ja tagastab tulemuse lõpliku vastuse jaoks.* -> **🤖 Proovi koos [GitHub Copilot](https://github.com/features/copilot) Chatiga:** Ava [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ja küsi: -> - "Kuidas ReAct muster toimib ja miks on see tehisintellekti agentidele efektiivne?" -> - "Kuidas agent otsustab, millist tööriista kasutada ja millises järjekorras?" -> - "Mis juhtub, kui tööriista täideviimine ebaõnnestub - kuidas vigadega kindlalt toime tulla?" +> **🤖 Proovi [GitHub Copilot](https://github.com/features/copilot) Chat’iga:** Ava [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ja küsi: +> - "Kuidas töötab ReAct muster ja miks see on AI agentide puhul tõhus?" +> - "Kuidas agent otsustab, millist tööriista kasutada ja mis järjekorras?" +> - "Mis juhtub, kui tööriista täideviimine ebaõnnestub - kuidas käsitleda vigu kindlalt?" -### Vastuse genereerimine +### Vastuse Genereerimine -Mudel saab ilmateabe ja vormindab selle kasutajale loomulikus keeles vastuseks. +Mudel saab ilmaandmed ja vormistab need loomulikus keeles vastuseks kasutajale. -### Arhitektuur: Spring Boot automaatühendus +### Arhitektuur: Spring Boot Automaatühendus -See moodul kasutab LangChain4j Spring Boot integreerimist deklaratiivsete `@AiService` liidestega. Käivitamisel leiab Spring Boot kõik `@Component`-id, mis sisaldavad `@Tool` meetodeid, teie `ChatModel` beani ja `ChatMemoryProvider` — ning ühendab need kõik ühte `Assistant` liidesesse ilma täiendava koodita. +Selles moodulis kasutatakse LangChain4j Spring Boot integratsiooni deklaratiivsete `@AiService` liidestega. Käivitamisel avastab Spring Boot iga `@Component`, mis sisaldab `@Tool` meetodeid, sinu `ChatModel` bean’i ja `ChatMemoryProvider` — ning ühendab kõik üheks `Assistant` liideseks nullkoodita. -Spring Boot automaatühenduse arhitektuur +Spring Boot Automaatühenduse Arhitektuur -*@AiService liides ühendab ChatModeli, tööriista komponendid ja mälupakkuja — Spring Boot haldab automaatselt kogu ühenduse.* +*@AiService liides ühendab kokku ChatModel’i, tööriistakomponendid ja mälu pakkuja — Spring Boot haldab kogu ühenduse automaatselt.* -Järgnevalt on kogu päringu elutsükkel järjestusdiagrammina — HTTP päringust kontrolleri, teenuse ja automaatselt ühendatud proksi kaudu tööriistakutse täideviimiseni ja tagasi: +Siin on kogu päringu elutsükkel järjestusdiagrammina — HTTP päringust kontrolleri, teenuse ja automaatühendatud proksi kaudu tööriistakutseni ja tagasi: -Spring Boot tööriistakutsete järjestus +Spring Boot Tööriistakutsete Järjestus -*Täielik Spring Boot päringu elutsükkel — HTTP päring voolab läbi kontrolleri ja teenuse automaatselt ühendatud Assistant proksisse, kes orkestreerib LLM-i ja tööriistakutsed iseseisvalt.* +*Täielik Spring Boot päringu elutsükkel — HTTP päring voolab läbi kontrolleri ja teenuse automaatselt ühendatud Assistant proksi juurde, mis korraldab LLM ja tööriistakutsed iseseisvalt.* Selle lähenemise peamised eelised: - **Spring Boot automaatühendus** — ChatModel ja tööriistad süstitakse automaatselt -- **@MemoryId muster** — Automaatne seansipõhine mälu haldus -- **Üks instants** — Assistant luuakse korra ja kasutatakse uuesti parema jõudluse jaoks -- **Tüübiturvaline täideviimine** — Java meetodid kutsutakse otse tüübi teisendusega -- **Mitme sammuga orkestreerimine** — Haldbab tööriistade aheldamist automaatselt -- **Null täiendavat koodi** — Ei ole vaja käsitsi kutsuda `AiServices.builder()` või mälu HashMapi +- **@MemoryId muster** — Automaatne sessioonipõhine mäluhaldus +- **Üks eksemplar** — Assistant loodud korra ja korduvkasutatud paremaks jõudluseks +- **Tüübikindel täideviimine** — Java meetodid kutsutakse otse koos tüübi konverteerimisega +- **Mitme sammuga korraldus** — Haldab tööriistade ühendamist automaatselt +- **Nullkood** — Ei ole vaja käsitsi `AiServices.builder()` kutsumisi ega mäluhaldus HashMap’i -Alternatiivsed lähenemised (käsitsi `AiServices.builder()`) vajavad rohkem koodi ja jäävad ilma Spring Boot integratsiooni eelistest. +Alternatiivsed käsitletavad lähenemised (käsitsi `AiServices.builder()`) vajavad rohkem koodi ja jäävad ilma Spring Boot integratsiooni eelistest. -## Tööriistade aheldamine +## Tööriistade Järgnevus -**Tööriistade aheldamine** — Tööriistapõhiste agentide tõeline võimsus tuleb ilmsiks siis, kui üks küsimus vajab mitut tööriista. Küsi: "Milline on Seattle'i ilm Fahrenheitides?" ja agent aheldab automaatselt kaks tööriista: esmalt kutsub `getCurrentWeather`, et saada temperatuur Celsiuses, seejärel edastab selle väärtuse `celsiusToFahrenheit` konverteerimiseks — kõik ühe vestluse jooksul. +**Tööriistade Järgnevus** — Tööriistapõhiste agentide tõeline jõud avaldub siis, kui üks küsimus nõuab mitut tööriista. Küsi "Milline on ilm Seattle’is Fahrenheitides?" ja agent ühendab automaatselt kaks tööriista: esmalt kutsub `getCurrentWeather`, et saada temperatuur Celsiuses, seejärel annab selle tulemuse `celsiusToFahrenheit`-ile ümberarvestamiseks — kõik ühes vestluse sammus. -Tööriistade aheldamise näide +Tööriistade Järgnevuse Näide -*Tööriistade aheldamine töös — agent kutsub esmalt getCurrentWeather, seejärel suunab Celsiuse tulemuse celsiusToFahrenheit-i ja annab kokkuvõtva vastuse.* +*Tööriistade järgnevus tegevuses — agent kutsub esmalt getCurrentWeather, siis suunab Celsiuse tulemuse celsiusToFahrenheit-i ja annab kokkuvõtliku vastuse.* -**Viisakas vigade käsitlemine** — Küsi ilma linna kohta, mis ei ole tehisandmetes. Tööriist tagastab veateate ning tehisintellekt seletab, et ei saa aidata, selle asemel et kokku jooksu teha. Tööriistad ebaõnnestuvad turvaliselt. Järgmine diagramm võrdleb kahte lähenemist — korraliku vigade käitlemisega agent tabab erandi ja vastab abivalmilt, ilma selleta kukub kogu rakendus kokku: +**Vigade Maaratlus** — Küsi ilma kohta linnast, mis pole simulatsioonandmetes. Tööriist tagastab veateate ja AI selgitab, et ei saa aidata, selle asemel et rike tekiks. Tööriistad ebaõnnestuvad turvaliselt. Järgmine skeem võrdleb kahte lähenemist — korraliku veahaldusega püüab agent vea kinni ja vastab abistavalt, ilma selleta kukub kogu rakendus kokku: -Vigade käsitlemise voog +Veakäsitluse Voog -*Kui tööriist ebaõnnestub, tabab agent vea ja vastab abivalmilt, selle asemel et rakendus kokku jookseks.* +*Kui tööriist ebaõnnestub, püüab agent vea kinni ja vastab kasuliku selgitusega selle asemel, et kokku kukkuda.* -See juhtub ühe vestlusvooru jooksul. Agent orkestreerib automaatselt mitut tööriistakutset. +See kõik toimub ühes vestluse sammus. Agent korraldab mitmeid tööriistakutseid iseseisvalt. -## Rakenduse käivitamine +## Rakenduse Käivitamine -**Kontrollige juurutust:** +**Kontrolli juurutust:** -Veenduge, et juurkaustas on olemas `.env` fail Azure volitustega (loodud Moodulis 01). Käivitage see mooduli kaustast (`04-tools/`): +Veendu, et juurekataloogis on `.env` fail Azure volitustega (loodud Moodulis 01). Käivita see moodulikaustast (`04-tools/`): -**Bash:** +**Bash:** ```bash cat ../.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Peaks näitama AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Rakenduse käivitamine:** -> **Märkus:** Kui olete juba käivitanud kõik rakendused käsuga `./start-all.sh` juurkaustast (nagu kirjeldatud Moodulis 01), töötab see moodul porti 8084. Võite käivituskäsklused vahele jätta ja minna otse aadressile http://localhost:8084. +> **Märkus:** Kui sa oled juba käivitanud kõik rakendused käsuga `./start-all.sh` juurest (nagu kirjeldatud Moodulis 01), siis see moodul juba töötab pordil 8084. Võid käivitamiskäsud vahele jätta ja minna otse aadressile http://localhost:8084. -**Variant 1: Spring Boot Dashboardi kasutamine (soovitatav VS Code kasutajatele)** +**Variant 1: Kasutades Spring Boot Dashboard’i (Soovitatav VS Code kasutajatele)** -Arenduskonteiner sisaldab Spring Boot Dashboard laiendust, mis pakub visuaalset liidest kõigi Spring Boot rakenduste haldamiseks. Leiate selle VS Code’i vasakpoolse tööriistariba ikoonilt, otsides Spring Boot ikooni. +Arenduskonteiner sisaldab Spring Boot Dashboard laiendust, mis pakub visuaalset liidest kõigi Spring Boot rakenduste haldamiseks. Sa leiad selle VS Code vasakpoolsest Activity Bar’ist (otsi Spring Boot ikooni). -Spring Boot Dashboardi kaudu saate: -- Näha kõiki tööruumis olevaid Spring Boot rakendusi -- Käivitada/peatada rakendusi ühe klõpsuga -- Vaadata rakenduste logisid reaalajas +Spring Boot Dashboard’i abil saad: +- Näha kõiki töölaua Spring Boot rakendusi +- Käivitada/peatada rakendusi ühe klikiga +- Vaadata rakenduse logisid reaalajas - Jälgida rakenduse olekut -Lihtsalt klõpsake selle mooduli käivitamiseks nupu "tools" kõrval olevat esitamisnuppu või käivitage kõik moodulid korraga. -Siin on, kuidas Spring Boot Dashboard VS Code'is välja näeb: +Lihtsalt klõpsa "tools" kõrval olevat play nuppu, et käivitada see moodul, või alusta korraga kõiki mooduleid. -Spring Boot Dashboard +Siin on, kuidas Spring Boot Dashboard VS Code’is välja näeb: +Spring Boot Tööriistalaud -*Spring Boot Dashboard VS Code'is — käivitage, peatage ja jälgige kõiki mooduleid ühest kohast* +*Spring Boot Tööriistalaud VS Code’is — alusta, peata ja jälgi kõiki mooduleid ühest kohast* -**Valik 2: Shell-skriptide kasutamine** +**Variant 2: Shell-i skriptide kasutamine** -Käivitage kõik veebirakendused (moodulid 01-04): +Alusta kõiki veebirakendusi (moodulid 01-04): **Bash:** ```bash -cd .. # Juurekataloogist +cd .. # Juurkaustast ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Juurestikust +cd .. # Põhijuurkataloogist .\start-all.ps1 ``` -Või käivitage ainult see moodul: +Või alusta ainult seda moodulit: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurkataloogis asuvast `.env` failist ning ehitavad JAR-id, kui neid ei eksisteeri. +Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurest `.env` failist ja ehitavad JAR-id, kui neid veel ei ole. -> **Märkus:** Kui soovite enne käivitamist kõik moodulid käsitsi ehitada: +> **Märkus:** Kui soovid enne käivitamist kõik moodulid käsitsi ehitada: > > **Bash:** > ```bash @@ -272,7 +272,7 @@ Mõlemad skriptid laadivad automaatselt keskkonnamuutujad juurkataloogis asuvast > mvn clean package -DskipTests > ``` -Avage oma brauseris aadress . +Ava oma brauseris aadress http://localhost:8084. **Peatamiseks:** @@ -292,96 +292,96 @@ cd ..; .\stop-all.ps1 # Kõik moodulid ## Rakenduse kasutamine -Rakendus pakub veebiliidest, kus saate suhelda AI agendiga, kellel on juurdepääs ilma- ja temperatuuri teisendamise tööriistadele. Siin on liides — sisaldab kiire algusega näiteid ja vestluspaneeli päringute saatmiseks: +Rakendus pakub veebiliidest, kus saad suhelda AI-agentiga, kellel on ligipääs ilma- ja temperatuuri teisendamise tööriistadele. Näiteks näeb kasutajaliides välja selline — sisaldab kiirstart näiteid ja vestluse paneeli päringute saatmiseks: -AI Agent Tools Interface +AI Agendi Tööriistade Liides -*AI Agent Tools liides – kiireid näiteid ja vestlusliides tööriistadega suhtlemiseks* +*AI Agendi Tööriistade liides - kiirnäited ja vestlusliides tööriistadega suhtlemiseks* ### Proovi lihtsat tööriista kasutust -Alusta lihtsast päringust: "Convert 100 degrees Fahrenheit to Celsius". Agent tuvastab, et tal on vaja temperatuuri teisendamise tööriista, kutsub selle õige parameetritega ja tagastab tulemuse. Märka, kui loomulik see on – sa ei pidanud täpsustama, millist tööriista kasutada või kuidas seda kutsuda. +Alusta lihtsast päringust: "Teisenda 100 kraadi Fahrenheitist Celsiuseks". Agent mõistab, et tal on vaja temperatuuri teisendamise tööriista, kutsub seda õigete parameetritega ja tagastab tulemuse. Pane tähele, kui loomulik see on - sa ei pidanud täpsustama, millist tööriista kasutada või kuidas seda kutsuda. ### Testi tööriistade ahelat -Proovi nüüd keerulisemat: "What's the weather in Seattle and convert it to Fahrenheit?" Vaata, kuidas agent samm-sammult töötab. Esiteks hangib ta ilma (mis tagastab Celsius), tunneb ära vajaduse teisendada Fahrenheitiks, kutsub teisendusvahendi ja ühendab mõlemad tulemused ühe vastusena. +Proovi midagi keerukamat: "Milline on ilm Seattle’is ja teisenda see Fahrenheitiks?" Vaatle, kuidas agent samm-sammult töötab. Ta võtab esmalt ilmateate (mis tagastab Celsiuse kraadid), mõistab, et peab teisendama Fahrenheitiks, kutsub teisendustööriista ja ühendab mõlemad tulemused ühte vastusesse. -### Vaata vestluse kulgu +### Vaata vestluse voogu -Vestlusliides säilitab vestluse ajaloo, võimaldades mitmevoorulist suhtlust. Näed kõiki varasemaid päringuid ja vastuseid, mis hõlbustab vestluse jälgimist ja mõistmist, kuidas agent ehitab konteksti mitme vahetuse jooksul. +Vestlusliides hoiab vestluste ajalugu, võimaldades mitmetoalisi dialooge. Sa näed kõiki eelnevaid päringuid ja vastuseid, mis teeb kergeks vestluse jälgimise ja mõistmise, kuidas agent konteksti mitme vahetusega üles ehitab. -Conversation with Multiple Tool Calls +Vestlus mitme tööriistikutsega -*Mitmevooruline vestlus, mis näitab lihtsaid teisendusi, ilmapäringuid ja tööriistade ahelat* +*Mitme vooruga vestlus, mis näitab lihtsaid teisendusi, ilmateateid ja tööriistade ahelat* -### Katseta erinevaid päringuid +### Katseta erinevate päringutega Proovi erinevaid kombinatsioone: -- Ilmapäringud: "What's the weather in Tokyo?" -- Temperatuuri teisendused: "What is 25°C in Kelvin?" -- Ühispäringud: "Check the weather in Paris and tell me if it's above 20°C" +- Ilmateated: "Milline on ilm Tokyos?" +- Temperatuuri teisendused: "Mis on 25°C kelvinites?" +- Ühendatud päringud: "Kontrolli Pariisi ilma ja ütle, kas temperatuur on üle 20°C" -Märka, kuidas agent tõlgendab loomulikku keelt ja kaardistab selle sobivateks tööriistakutseteks. +Pane tähele, kuidas agent tõlgendab loomulikku keelt ja seob selle sobivate tööriistakutsetega. -## Põhimõisted +## Peamised kontseptsioonid -### ReAct muster (Põhjendamine ja Tegutsemine) +### ReAct muster (Põhjus ja Tegutsemine) -Agent vaheldub põhjendamise (otsustamine, mida teha) ja tegutsemise (tööriistade kasutamine) vahel. See muster võimaldab autonoomset probleemilahendust, mitte ainult juhiste täitmist. +Agent vaheldumisi põhjendab (otsustab, mida teha) ja tegutseb (kasutab tööriistu). See muster võimaldab autonoomset probleemilahendust, mitte ainult juhiste täitmist. -### Tööriistade kirjeldusel on tähtsus +### Tööriistade kirjeldused on tähtsad -Tööriistakirjelduse kvaliteet mõjutab otseselt, kui hästi agent neid kasutab. Selged, spetsiifilised kirjeldused aitavad mudelil mõista, millal ja kuidas iga tööriista kutsuda. +Tööriistade kirjelduste kvaliteet määrab otse, kui hästi agent neid kasutab. Selged ja spetsiifilised kirjeldused aitavad mudelil mõista, millal ja kuidas iga tööriista kutsuda. -### Sessioonihaldus +### Sessiooni haldus -`@MemoryId` annotatsioon võimaldab automaatset sessioonipõhist mäluhaldust. Iga sessiooni ID jaoks luuakse oma `ChatMemory` instants, mida haldab `ChatMemoryProvider` bean, nii et mitmed kasutajad saavad korraga agendiga suhelda ilma, et nende vestlused seguneksid. Järgnev diagramm näitab, kuidas mitu kasutajat suunatakse eraldatud mälupoodidesse vastavalt nende sessiooni ID-dele: +`@MemoryId` annotatsioon lubab automaatset sessioonipõhist mälu haldust. Iga sessiooni ID-le luuakse oma `ChatMemory` instants, mida haldab `ChatMemoryProvider` bean, nii et mitmed kasutajad saavad samaaegselt agentidega suhelda ilma, et vestlused seguneksid. Järgmine diagramm näitab, kuidas mitmed kasutajad suunatakse eraldatud vestlusmäludele vastavalt nende sessiooni ID-dele: -Session Management with @MemoryId +Sessiooni haldus koos @MemoryId-ga -*Iga sessiooni ID vastab eraldatud vestluse ajalool — kasutajad ei näe kunagi teiste sõnumeid.* +*Iga sessiooni ID vastab isoleeritud vestluse ajaloole — kasutajad ei näe kunagi teiste sõnumeid.* -### Vea käsitlemine +### Veahaldus -Tööriistad võivad ebaõnnestuda — API-d aeguvad, parameetrid võivad olla vigased, välisteenused ei tööta. Tootmisagentidele on vajalik veahaldus, et mudel suudaks probleemi selgitada või alternatiive proovida, mitte et terve rakendus kokku jookseks. Kui tööriist viskab erindi, püüab LangChain4j selle kinni ja edastab veateate mudelile, mis võib seejärel probleemi loomulikus keeles selgitada. +Tööriistad võivad ebaõnnestuda — API-d aeguvad, parameetrid võivad olla valed, välised teenused võivad olla maas. Tootmisagentidel on vaja veahaldust, et mudel saaks probleeme selgitada või proovida alternatiive, mitte et kogu rakendus kokku jookseks. Kui tööriist viskab erandi, tabab LangChain4j selle ja suunab veateate mudelile tagasi, kes saab probleemi selgitada loomulikus keeles. -## Saadavalolevad tööriistad +## Saadaval olevad tööriistad -Järgmine diagramm näitab laia tööriistade ökosüsteemi, mida saate ehitada. See moodul demonstreerib ilma- ja temperatuuri tööriistu, kuid sama `@Tool` muster toimib mistahes Java meetodi puhul — alates andmebaasipäringutest kuni maksete töötlemiseni. +Järgmine diagramm näitab laia tööriistade ökosüsteemi, mida saad ehitada. See moodul demonstreerib ilma- ja temperatuuritööriistu, kuid sama `@Tool` muster töötab mis tahes Java meetodi puhul — alates andmebaasi päringutest kuni maksete töötlemiseni. -Tool Ecosystem +Tööriistade ökosüsteem -*Mitte ükski Java meetod, mida annotatsiooniga @Tool märgistatakse, ei muutuks saadavaks AI-le — mustrit saab laiendada andmebaaside, API-de, e-posti, failitöötluse ja muu puhul.* +*Iga Java meetod, mis on märgistatud @Tool-iga, saab AI-le kättesaadavaks — muster laieneb andmebaasidele, API-dele, e-postile, failitöötlusele ja muule.* ## Millal kasutada tööriistapõhiseid agente -Mitte iga päring ei vaja tööriistu. Otsus sõltub sellest, kas AI-l on vaja suhelda välissüsteemidega või saab vastata oma teadmiste põhjal. Järgmine juhend võtab kokku, millal tööriistad väärtust lisavad ja millal neid pole vaja: +Mitte iga päring ei vaja tööriistu. Otsus sõltub sellest, kas AI-l on vaja suhelda väliste süsteemidega või saab ta vastata oma teadmiste põhjal. Järgmine juhend koondab, millal tööriistad on kasulikud ja millal tarbetud: -When to Use Tools +Millal tööriistu kasutada -*Kiire otsustusjuhend — tööriistad on mõeldud reaalajas andmete, arvutuste ja toimingute jaoks; üldteadmised ja loomingulised ülesanded neid ei vaja.* +*Kiire otsustusjuhend — tööriistad on reaalajas andmete, arvutuste ja toimingute jaoks; üldised teadmised ja loomingulised ülesanded ei vaja neid.* ## Tööriistad vs RAG -Moodulid 03 ja 04 laiendavad mõlemad, mida AI suudab teha, kuid põhjalikult erineval moel. RAG annab mudelile juurdepääsu **teadmistele** dokumentide abil. Tööriistad annavad mudelile võime **toimingute** tegemiseks funktsioone kutsuda. Järgnev diagramm võrdleb neid kahte lähenemist kõrvuti — alates tööprotsesside toimimisest kuni kompromissideni: +Moodulid 03 ja 04 laiendavad AI võimekust, aga põhimõtteliselt erinevalt. RAG annab mudelile ligipääsu **teadmistele** dokumentide toomise kaudu. Tööriistad annavad mudelile võime **teha toiminguid** funktsioonide kutsumise kaudu. Järgmine diagramm võrdleb neid kahte lähenemist kõrvuti — alates sellest, kuidas töövood toimivad kuni nende vaheliste kompromissideni: -Tools vs RAG Comparison +Tööriistade ja RAG võrdlus -*RAG hangib infot staatilistest dokumentidest — tööriistad täidavad toiminguid ja hangivad dünaamilisi, reaalajas andmeid. Paljud tootmissüsteemid kombineerivad mõlemat.* +*RAG toob infot staatilistest dokumentidest — Tööriistad täidavad toiminguid ja hangivad dünaamilisi, reaalajas andmeid. Paljud tootmissüsteemid kasutavad mõlemat kombineeritult.* -Praktikas kasutavad paljud tootmissüsteemid mõlemat lähenemist: RAG kinnitab vastused teie dokumentatsioonile ja tööriistad hangivad elusaid andmeid või teevad toiminguid. +Praktikas kasutavad paljud tootmissüsteemid mõlemaid lähenemisi: RAG dokumentatsiooni toetamiseks ja Tööriistad elavate andmete hankimiseks või toimingute tegemiseks. ## Järgmised sammud -**Järgmine moodul:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Järgmine moodul:** [05-mcp - Mudeli konteksti protokoll (MCP)](../05-mcp/README.md) --- -**Navigeerimine:** [← Eelmine: Moodul 03 - RAG](../03-rag/README.md) | [Tagasi Pealehele](../README.md) | [Järgmine: Moodul 05 - MCP →](../05-mcp/README.md) +**Navigeerimine:** [← Eelmine: Moodul 03 - RAG](../03-rag/README.md) | [Tagasi avalehele](../README.md) | [Järgmine: Moodul 05 - MCP →](../05-mcp/README.md) --- -**Vastutusest loobumine**: -See dokument on tõlgitud AI tõlketeenuse [Co-op Translator](https://github.com/Azure/co-op-translator) abil. Kuigi püüame tagada täpsust, palun arvestage, et automaatses tõlkes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse professionaalset inimtõlget. Me ei vastuta selle tõlke kasutamisest tingitud arusaamatuste või valesti mõistmiste eest. +**Lahtiütlus**: +See dokument on tõlgitud kasutades AI tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest. \ No newline at end of file diff --git a/translations/et/README.md b/translations/et/README.md index 891ad7338..b9cabd1df 100644 --- a/translations/et/README.md +++ b/translations/et/README.md @@ -2,18 +2,18 @@ # LangChain4j algajatele -Kursus AI rakenduste loomiseks LangChain4j ja Azure OpenAI GPT-5.2 abil, alates lihtsast vestlusest kuni AI agentideni. +Kursus AI rakenduste ehitamiseks kasutades LangChain4j ja Azure OpenAI GPT-5.2, alates lihtsast vestlusest kuni AI agentideni. ### 🌐 Mitmekeelne tugi -#### Toetatud GitHub Actioni kaudu (automatiseeritud ja alati ajakohane) +#### Toetatud GitHub Actioni kaudu (Automaatne ja alati ajakohane) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](./README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Eelistate kloonida kohapeal?** +> **Eelistad kloonimist lokaalselt?** > -> See hoidla sisaldab üle 50 keele tõlkeid, mis suurendab allalaadimise mahtu märkimisväärselt. Kui soovite kloonida ilma tõlgeteta, kasutage hõredat checkouti: +> See hoidla sisaldab üle 50 keele tõlget, mis suurendab allalaaditava faili suurust märkimisväärselt. Tõlgeteta kloonimiseks kasuta sparsed checkouti: > > **Bash / macOS / Linux:** > ```bash @@ -29,64 +29,63 @@ Kursus AI rakenduste loomiseks LangChain4j ja Azure OpenAI GPT-5.2 abil, alates > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> See annab teile kõik vajaliku kursuse lõpetamiseks märksa kiirema allalaadimisega. +> See annab sulle kõik vajaliku kursuse läbimiseks palju kiirema allalaadimisega. ## Sisukord -1. [Kiire alustamine](00-quick-start/README.md) - LangChain4j-ga alustamine -2. [Sissejuhatus](01-introduction/README.md) - Õppige LangChain4j põhialuseid -3. [Päästiku inseneriteadus](02-prompt-engineering/README.md) - Saavutage tulemuslik päästiku kujundamine -4. [RAG (otsingupõhine genereerimine)](03-rag/README.md) - Looge nutikaid teadmistepõhiseid süsteeme -5. [Tööriistad](04-tools/README.md) - Integreerige väliseid tööriistu ja lihtsaid assistente -6. [MCP (mudelikonteksti protokoll)](05-mcp/README.md) - Töötage MCP ja agentidel põhinevate moodulitega +1. [Sissejuhatus](01-introduction/README.md) - Õpi LangChain4j põhialuseid +2. [Promptide loomine](02-prompt-engineering/README.md) - Õpi tõhusaid promptide disainimise tehnikaid +3. [RAG (otsingupõhine genereerimine)](03-rag/README.md) - Ehita nutikaid teadmistepõhiseid süsteeme +4. [Tööriistad](04-tools/README.md) - Integreeri väliseid tööriistu ja lihtsaid assistente +5. [MCP (Mudeli konteksti protokoll)](05-mcp/README.md) - Tööta Model Context Protocoli (MCP) ja agentide moodulitega ### Video juhendid -Igal moodulil on kaasas otseülekande sessioon, kus käsitleme kontsepte ja koodi samm-sammult. +Iga mooduli juurde kuulub otseülekandes juhend, kus samm-sammult käime läbi kontseptsioonid ja koodi. | Moodul | Video | |--------|-------| -| 01 - Sissejuhatus | [Alustamine LangChain4j-ga](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Päästiku inseneriteadus | [Päästiku inseneriteadus LangChain4j-ga](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [RAG LangChain4j-ga](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 01 - Sissejuhatus | [LangChain4j kasutuselevõtt](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Promptide loomine | [Promptide loomine LangChain4j-ga](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [RAG koos LangChain4j-ga](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Tööriistad & 05 - MCP | [AI agentide loomine tööriistade ja MCP-ga](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## Õppeteekond -**Oled LangChain4j-s uus?** Tutvu [Sõnastikuga](docs/GLOSSARY.md), et mõista võtmetermineid ja kontseptsioone. +**Oled uus LangChain4j juures?** Vaata [Sõnastikku](docs/GLOSSARY.md), kus selgitatakse võtmetermineid ja kontseptsioone. -> **Kiire alustamine** +> **Kiirstart** -1. Tehke failide koopia (fork) sellest hoidlast oma GitHub kontole -2. Klõpsake **Code** → **Codespaces** vahekaart → **...** → **New with options...** -3. Kasutage vaikeväärtusi – see valib selle kursuse jaoks loodud arenduskonteineri +1. Looge selle hoidla fork oma GitHubi kontole +2. Klõpsake **Code** → **Codespaces** sakk → **...** → **New with options...** +3. Kasutage vaikeseadeid – see valib kursuse jaoks loodud arendus konteineri 4. Klõpsake **Create codespace** -5. Oodake 5-10 minutit, kuni keskkond on valmis -6. Hüppa otse [Kiire alustamise](./00-quick-start/README.md) juurde, et alustada! +5. Oodake 5–10 minutit, kuni keskkond on valmis +6. Alustage otse [sissejuhatusest](./01-introduction/README.md)! -Moodulite läbimisel uurige ka [Testimisjuhendit](docs/TESTING.md), et näha LangChain4j testimise kontseptsioone praktikas. +Pärast moodulite läbimist uurige [Testimise juhendit](docs/TESTING.md), et näha LangChain4j testimise kontseptsioone praktikas. -> **Märkus:** See koolitus kasutab nii GitHubi mudeleid kui ka Azure OpenAI-d. [Kiire alustamise](00-quick-start/README.md) moodul kasutab GitHubi mudeleid (Azure tellimust pole vaja), samas kui moodulid 1–5 kasutavad Azure OpenAI-d. Kui teil veel pole, alustage [TASUTA Azure kontoga](https://aka.ms/azure-free-account). +> **Märkus:** See koolitus kasutab Azure OpenAI. Kui sul pole veel kontot, alusta [TASUTA Azure konto](https://aka.ms/azure-free-account) loomisega. ## Õppimine GitHub Copilotiga -Kiireks kodeerimiseks avage see projekt GitHub Codespaces või oma kohaliku IDE-s antud devcontaineriga. Kursuses kasutatav devcontainer on eelkonfigureeritud GitHub Copilotiga AI paarprogrammeerimiseks. +Selleks, et kiiresti kodeerima hakata, ava see projekt GitHub Codespaces või oma lokaalses IDEs koos antud devcontaineriga. Kursuses kasutatav devcontainer on eelseadistatud GitHub Copilotiga AI paarisprogrammeerimiseks. -Iga koodinäite juures on soovitatavad küsimused, mida võite GitHub Copilotile esitada, et oma arusaamist süvendada. Otsige 💡/🤖 viiteid: +Iga koodinäite juures on soovituslikud küsimused, mida võid Copilotilt küsida, et oma arusaamist süvendada. Otsi 💡/🤖 märgendit: -- **Java failide päistes** – näidete spetsiifilised küsimused +- **Java failide päistes** – iga näite kohta spetsiifilised küsimused - **Mooduli README-d** – uurimisküsimused pärast koodinäiteid -**Kuidas kasutada:** Avage ükskõik milline koodifail ja küsige Copilotilt soovitatud küsimusi. Tal on kogu koodibaasi kontekst ja ta suudab selgitada, laiendada ja pakkuda alternatiive. +**Kuidas kasutada:** Ava ükskõik milline koodifail ja küsi soovitatud küsimusi Copilotilt. Tal on kogu koodibaasi kontekst olemas, ta saab seletada, laiendada ja soovitada alternatiive. -Tahate rohkem teada? Vaadake [Copilot AI paarprogrammeerimiseks](https://aka.ms/GitHubCopilotAI). +Tahad rohkem teada? Vaata [Copilot AI paarisprogrammeerimiseks](https://aka.ms/GitHubCopilotAI). -## Lisamaterjalid +## Täiendavad ressursid ### LangChain @@ -99,7 +98,7 @@ Tahate rohkem teada? Vaadake [Copilot AI paarprogrammeerimiseks](https://aka.ms/ [![AZD algajatele](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) [![Edge AI algajatele](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) [![MCP algajatele](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI agentid algajatele](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI agendid algajatele](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- @@ -111,40 +110,41 @@ Tahate rohkem teada? Vaadake [Copilot AI paarprogrammeerimiseks](https://aka.ms/ --- -### Põhioskused -[![ML algajatele](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +### Põhiõpe +[![Masinõpe algajatele](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Andmeteadus algajatele](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI algajatele](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Kyberturvalisus algajatele](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Küberkaitse algajatele](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + [![Veebiarendus algajatele](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT algajatele](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![Asjade Internet algajatele](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR arendus algajatele](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Copiloti sari +### Copilot seeria [![Copilot tehisintellekti paarisprogrammeerimiseks](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot C#/.NET jaoks](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copiloti seiklus](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot C#/.NET arendamiseks](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot seiklus](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Abi saamine -Kui takerdu või sul on küsimusi tehisintellekti rakenduste loomisel, liitu: +Kui takerdud või sul on küsimusi AI-rakenduste loomise kohta, liitu: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Kui sul on toodet puudutav tagasiside või ehitamise ajal ilmnevad vead, külasta: +Kui sul on toodete tagasisidet või ehitusprotsessis ilmneb vigu, külasta: -[![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) +[![Microsoft Foundry arendajate foorum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Litsents -MIT litsents - täpsemate üksikasjade jaoks vt [LICENSE](../../LICENSE) faili. +MIT litsents - vaata üksikasju [LICENSE](../../LICENSE) failist. --- -**Vastutusest loobumine**: -See dokument on tõlgitud kasutades tehisintellekti tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi püüame täpsust, palun arvestage, et automaatsed tõlked võivad sisaldada vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise info puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta tõlke kasutamisest tingitud arusaamatuste või väärtõlgenduste eest. +**Lahtiütlus**: +See dokument on tõlgitud kasutades AI tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest. \ No newline at end of file diff --git a/translations/et/docs/GLOSSARY.md b/translations/et/docs/GLOSSARY.md index b67270f09..5549880e0 100644 --- a/translations/et/docs/GLOSSARY.md +++ b/translations/et/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## Sisukord -- [Põhikontseptsioonid](../../../docs) -- [LangChain4j komponendid](../../../docs) -- [AI/ML kontseptsioonid](../../../docs) -- [Guardrails](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agentid ja Tööriistad](../../../docs) -- [Agentic Moodul](../../../docs) -- [Mudeli Konteksti Protokoll (MCP)](../../../docs) -- [Azure Teenused](../../../docs) -- [Testimine ja Arendus](../../../docs) +- [Põhikontseptsioonid](#põhikontseptsioonid) +- [LangChain4j Komponendid](#langchain4j-komponendid) +- [AI/ML Kontseptsioonid](#aiml-kontseptsioonid) +- [Kaitsemehhanismid](#kaitsemehhanismid) +- [Promptide Loomine](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agendid ja Tööriistad](#agents-and-tools---module-04) +- [Agentne Moodul](#agentic-module---module-05) +- [Mudeli Konteksti Protokoll (MCP)](#model-context-protocol-mcp---module-05) +- [Azure Teenused](#azure-services---module-01) +- [Testimine ja Arendus](#testing-and-development---testing-guide) Kiire viide kursuse jooksul kasutatud terminitele ja kontseptsioonidele. ## Põhikontseptsioonid -**AI Agent** - Süsteem, mis kasutab tehisintellekti autonoomseks mõtlemiseks ja tegutsemiseks. [Moodul 04](../04-tools/README.md) +**AI Agent** - Süsteem, mis kasutab tehisintellekti mõtlemiseks ja autonoomseks tegutsemiseks. [Moodul 04](../04-tools/README.md) -**Chain** - Operatsioonide jada, kus väljund läheb järgmisse sammu. +**Kett (Chain)** - Tegevuste jada, kus väljund läheb järgmise sammu sisendiks. -**Chunking** - Dokumentide jagamine väiksemateks osadeks. Tüüpiline: 300-500 tokenit koos kattuvusega. [Moodul 03](../03-rag/README.md) +**Tükeldamine (Chunking)** - Dokumentide jaotamine väiksemateks osadeks. Tavaliselt 300-500 märki ülekattega. [Moodul 03](../03-rag/README.md) -**Context Window** - Maksimaalne tokenite arv, mida mudel suudab töödelda. GPT-5.2: 400K tokenit (kuni 272K sisend, 128K väljund). +**Kontekstiakna suurus** - Maksimaalne märgiste arv, mida mudel saab töödelda. GPT-5.2: 400K märki (kuni 272K sisend, 128K väljund). -**Embeddings** - Teksti tähendust esindavad numbrilised vektorid. [Moodul 03](../03-rag/README.md) +**Koodvektorid (Embeddings)** - Numbrilised vektorid, mis esindavad teksti tähendust. [Moodul 03](../03-rag/README.md) -**Function Calling** - Mudel genereerib struktureeritud päringuid väliste funktsioonide kutsumiseks. [Moodul 04](../04-tools/README.md) +**Funktsiooni Kutsumine** - Mudel genereerib struktureeritud päringuid väliste funktsioonide kutsumiseks. [Moodul 04](../04-tools/README.md) -**Hallucination** - Kui mudelid genereerivad vale, aga usutavat infot. +**Hallutsinatsioon** - Kui mudelid genereerivad vale, kuid usutavat infot. **Prompt** - Tekstisisend keelemudelile. [Moodul 02](../02-prompt-engineering/README.md) -**Semantic Search** - Otsing tähenduse järgi, kasutades embeddings'e, mitte märksõnu. [Moodul 03](../03-rag/README.md) +**Semantiline Otsing** - Otsing tähenduse järgi, kasutades koodvektoreid, mitte märksõnu. [Moodul 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: mäluta. Stateful: hoiab vestluse ajalugu. [Moodul 01](../01-introduction/README.md) +**Riigipõhine vs Riigivaba (Stateful vs Stateless)** - Riigivaba: pole mälulugu. Riigipõhine: säilitab vestluse ajaloo. [Moodul 01](../01-introduction/README.md) -**Tokens** - Teksti põhiüksused, mida mudelid töötlevad. Mõjutab kulusid ja piiranguid. [Moodul 01](../01-introduction/README.md) +**Märgid (Tokens)** - Mudelite töödeldavad põhiühikud. Mõjutab kulusid ja piiranguid. [Moodul 01](../01-introduction/README.md) -**Tool Chaining** - Tööriistade järjestikune täitmine, kus väljund juhib järgmist kutset. [Moodul 04](../04-tools/README.md) +**Tööriistade Kettimine** - Tööriistade järjestikune käivitamine, kus väljund suunab järgmist funktsioonikõnet. [Moodul 04](../04-tools/README.md) -## LangChain4j komponendid +## LangChain4j Komponendid -**AiServices** - Loob tüübiturvalisi tehisintellekti teenuste liideseid. +**AiServices** - Loob tüübikindlaid AI teenuste liideseid. **OpenAiOfficialChatModel** - Ühtne klient OpenAI ja Azure OpenAI mudelitele. -**OpenAiOfficialEmbeddingModel** - Loob embeddings'e OpenAI ametliku kliendi abil (toetab nii OpenAI kui Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Loob koodvektoreid OpenAI ametliku kliendi abil (toetab nii OpenAI kui Azure OpenAI). -**ChatModel** - Keelemudelite põhiliides. +**ChatModel** - Keelemudelite põhiline liides. -**ChatMemory** - Säilitab vestluse ajaloo. +**ChatMemory** - Hoiab vestluse ajalugu. -**ContentRetriever** - Leiab RAG jaoks asjakohaseid dokumentide tükke. +**ContentRetriever** - Leiab olulised dokumenditükid RAG jaoks. **DocumentSplitter** - Jagab dokumendid osadeks. -**EmbeddingModel** - Konkreetsete võtmesõnade teisendamine numbrilisteks vektoriteks. +**EmbeddingModel** - Muudab teksti numbrilisteks vektoriteks. -**EmbeddingStore** - Salvestab ja hangib embeddings'e. +**EmbeddingStore** - Salvestab ja hangib koodvektoreid. -**MessageWindowChatMemory** - Hoiab liikuva akna hiljutiste sõnumite jaoks. +**MessageWindowChatMemory** - Hoiab järjepidevalt viimaste sõnumite liugakent. -**PromptTemplate** - Loob taaskasutatavaid prompt-malle koos `{{variable}}` kohatäiteks. +**PromptTemplate** - Loob taaskasutatavaid prompte koos `{{variable}}` asendustega. -**TextSegment** - Tekstitükk metainfoga. Kasutatakse RAG koosseisus. +**TextSegment** - Tekstitükk koos metainfo ja kasutatakse RAGis. -**ToolExecutionRequest** - Tööriista täitmise taotluse esitlus. +**ToolExecutionRequest** - Esindab tööriista täitmise päringut. -**UserMessage / AiMessage / SystemMessage** - Vestlusakna sõnumitüübid. +**UserMessage / AiMessage / SystemMessage** - Vestluse sõnumitüübid. -## AI/ML kontseptsioonid +## AI/ML Kontseptsioonid -**Few-Shot Learning** - Selgitavate näidete esitamine promptides. [Moodul 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Näidete pakkumine promptides. [Moodul 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - Suurekeelne mudel, mida on treenitud tohutul hulgal tekstidel. +**Suur Keelemudel (LLM)** - AI mudelid, mis on treenitud suurte tekstikorpuste peal. -**Reasoning Effort** - GPT-5.2 parameeter, mis juhib mõtlemise sügavust. [Moodul 02](../02-prompt-engineering/README.md) +**Loogiline Pingutus (Reasoning Effort)** - GPT-5.2 parameeter, mis kontrollib mõtlemise sügavust. [Moodul 02](../02-prompt-engineering/README.md) -**Temperature** - Juhtib väljundi juhuslikkust. Madal=deterministlik, kõrge=loov. +**Temperatuur** - Juhtib väljundi juhuslikkust. Madal=deterministlik, kõrge=loov. -**Vector Database** - Spetsiaalne andmebaas embeddings'ite jaoks. [Moodul 03](../03-rag/README.md) +**Vektorandmebaas** - Spetsiaalne andmebaas koodvektorite jaoks. [Moodul 03](../03-rag/README.md) -**Zero-Shot Learning** - Ülesannete täitmine ilma näideteta. [Moodul 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Ülesannete sooritamine ilma näideteta. [Moodul 02](../02-prompt-engineering/README.md) -## Guardrails - [Moodul 00](../00-quick-start/README.md) +## Kaitsemehhanismid -**Defense in Depth** - Mitmetasandiline turvalahendus, mis kombineerib rakenduse tasandi piire ja pakkuja turvafiltreid. +**Kaitsekihid (Defense in Depth)** - Turvalisuse mitmetasandiline lähenemine, mis ühendab rakenduse tasandi kaitsed pakkuja turvafiltritega. -**Hard Block** - Pakkuja viskab HTTP 400 vea tõsiste sisurikete korral. +**Tõsine Blokeerimine (Hard Block)** - Pakkuja tõstab HTTP 400 vea tõsiste sisurikkumiste korral. -**InputGuardrail** - LangChain4j liides kasutaja sisendi valideerimiseks enne LLM-i jõudmist. Säästab kulusid ja viivitusi, blokeerides kahjulikud promptid varakult. +**InputGuardrail** - LangChain4j liides kasutaja sisendi valideerimiseks enne LLMi jõudmist. Säästab kulusid ja latentsust, blokeerides kahjulikud promptid varakult. -**InputGuardrailResult** - Tagastustüüp guardrali valideerimisel: `success()` või `fatal("põhjus")`. +**InputGuardrailResult** - Tagastustüüp kaitse valideerimiseks: `success()` või `fatal("põhjus")`. -**OutputGuardrail** - Liides AI-väljundi valideerimiseks enne kasutajale tagastamist. +**OutputGuardrail** - Liides AI vastuste valideerimiseks enne kasutajale tagastamist. -**Provider Safety Filters** - AI pakkujate (nt GitHub Models) sisseehitatud sisufiltrid, mis tabavad rikkumisi API tasemel. +**Pakkuja Turvafiltrid** - AI pakkujate (nt Azure OpenAI) sisseehitatud sisufiltrid, mis tabavad rikkumisi API tasandil. -**Soft Refusal** - Mudel keeldub viisakalt vastamast, ilma vea viskamata. +**Pehme Keeldumine (Soft Refusal)** - Mudel keeldub viisakalt vastamast vigade tekitamiseta. -## Prompt Engineering - [Moodul 02](../02-prompt-engineering/README.md) +## Promptide Loomine - [Moodul 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Samm-sammuline põhjendamine parema täpsuse saavutamiseks. +**Chain-of-Thought** - Järkjärguline loogika parema täpsuse saavutamiseks. -**Constrained Output** - Spetsiifilise vormingu või struktuuri nõudmine. +**Piiratud Väljund (Constrained Output)** - Sundida kindlat formaati või struktuuri. -**High Eagerness** - GPT-5.2 muster põhjalikuks põhjendamiseks. +**Suur Pühendumus (High Eagerness)** - GPT-5.2 muster põhjalikuks mõtlemiseks. -**Low Eagerness** - GPT-5.2 muster kiireteks vastusteks. +**Madal Pühendumus (Low Eagerness)** - GPT-5.2 muster kiireteks vastusteks. -**Multi-Turn Conversation** - Konteksti hoidmine mitme vahetuse jooksul. +**Mitme-Korra Vestlus (Multi-Turn Conversation)** - Mõtteviisi säilitamine vestluse jooksul. -**Role-Based Prompting** - Mudeli isikupära seadmine süsteemisõnumite kaudu. +**Rollipõhine Promptimine** - Mudeli persona määramine süsteemsete sõnumite kaudu. -**Self-Reflection** - Mudel hindab ja parandab oma väljundit. +**Eneseanalüüs (Self-Reflection)** - Mudel hindab ja täiustab oma väljundit. -**Structured Analysis** - Fikseeritud hindamisraamistik. +**Struktureeritud Analüüs** - Kindel hindamismeetod. -**Task Execution Pattern** - Planeeri → Täida → Kokkuvõtte. +**Ülesande Täitmise Muster** - Plaan → Täida → Kokkuvõtte tee. ## RAG (Retrieval-Augmented Generation) - [Moodul 03](../03-rag/README.md) -**Document Processing Pipeline** - Lae → tükelda → embedding → salvestus. +**Dokumenditöötlusvoog** - Lae → tükelda → kodeeri → salvesta. -**In-Memory Embedding Store** - Mitte-püsiv salvestus testimiseks. +**Mälupõhine Koodvektoripood** - Ajutine hoidla testimiseks. -**RAG** - Kombineerib otsingu ja generatsiooni vastuste täpsustamiseks. +**RAG** - Ühendab info hankimise ja genereerimise, et vastused oleksid põhjendatud. -**Similarity Score** - Semantilise sarnasuse mõõt (0-1). +**Sarnasuse Hinne** - Semantilise sarnasuse mõõt (0-1). -**Source Reference** - Metainfo otsitud sisu kohta. +**Allika Viide** - Metaandmed hangitud sisu kohta. -## Agentid ja Tööriistad - [Moodul 04](../04-tools/README.md) +## Agendid ja Tööriistad - [Moodul 04](../04-tools/README.md) -**@Tool Annotation** - Märgib Java meetodid AI-ga kutsutavateks tööriistadeks. +**@Tool Märgend** - Märgistab Java meetodid AI-kõlbulikeks tööriistadeks. -**ReAct Pattern** - Mõtle → Tegutse → Vaata → Korda. +**ReAct Muster** - Mõtle → Tegutse → Vaata → Korda. -**Session Management** - Eraldab erinevate kasutajate kontekstid. +**Sessiooni Halduse** - Erinevad kontekstid kasutajate jaoks. -**Tool** - Funktsioon, mida AI agent saab kutsuda. +**Tööriist** - Funktsioon, mida AI agent saab kutsuda. -**Tool Description** - Tööriista eesmärgi ja parameetrite dokumentatsioon. +**Tööriista Kirjeldus** - Dokumentatsioon tööriista eesmärgi ja parameetrite kohta. -## Agentic Moodul - [Moodul 05](../05-mcp/README.md) +## Agentne Moodul - [Moodul 05](../05-mcp/README.md) -**@Agent Annotation** - Märgib liidesed AI agentideks koos deklaratiivse käitumise määratlusega. +**@Agent Märgend** - Märgistab liidesed AI agentideks deklaratiivse käitumise kirjeldamiseks. -**Agent Listener** - Konks agentide täitmise jälgimiseks meetodite `beforeAgentInvocation()` ja `afterAgentInvocation()` kaudu. +**Agendi Kuulaja (Agent Listener)** - Konks agentide täitmise jälgimiseks meetoditega `beforeAgentInvocation()` ja `afterAgentInvocation()`. -**Agentic Scope** - Jagatud mälu, kus agentide väljundid talletatakse ja mida järgmised agentid tarbivad. +**Agentne Ulatus (Agentic Scope)** - Jagatud mälu, kuhu agentide tulemused salvestatakse, et teised agentid saaksid neid kasutada. -**AgenticServices** - Agentide loomiseks mõeldud tehas kasutades `agentBuilder()` ja `supervisorBuilder()`. +**AgenticServices** - Tehas agentide loomiseks kasutades `agentBuilder()` ja `supervisorBuilder()`. -**Conditional Workflow** - Tingimuslik marsruutimine erinevate spetsialist-agentide juurde. +**Tingimuslik Töövoog** - Tähtis marsruut tingimuse põhjal erinevatele spetsialistagentidele. -**Human-in-the-Loop** - Töötlemismuster, mis lisab inimkontrollpunktid kinnituseks või sisukontrolliks. +**Inimene Ahelas (Human-in-the-Loop)** - Töövoo muster, mis lisab inimsektsioonid heakskiiduks või sisukontrolliks. -**langchain4j-agentic** - Maven sõltuvus deklaratiivseks agentide ehitamiseks (eksperimentaalne). +**langchain4j-agentic** - Maven sõltuvus deklaratiivseks agentide loomiseks (katsefaasis). -**Loop Workflow** - Agentide täitmine kordub, kuni tingimus on täidetud (nt kvaliteediskoor ≥ 0.8). +**Tsükliline Töövoog (Loop Workflow)** - Iteratiivne agentide täitmine kuni tingimus täitub (nt kvaliteediskoor ≥ 0.8). -**outputKey** - Agendi annotatsiooni parameeter, mis määrab, kuhu tulemused Agentic Scope'is salvestatakse. +**outputKey** - Agendi märgendiparameeter, mis määrab, kuhu Agentse Ulatuses tulemused salvestatakse. -**Parallel Workflow** - Mitme agendi samaaegne käivitamine iseseisvate ülesannete jaoks. +**Paralleeltöövoog (Parallel Workflow)** - Mitme agendi samaaegne täitmine iseseisvate ülesannete jaoks. -**Response Strategy** - Kuidas juhendaja koostab lõpliku vastuse: LAST, SUMMARY või SCORED. +**Vastustrateegia** - Kuidas juhendaja vormistab lõpliku vastuse: VIIMANE, KOKKUVÕTE või SKOORITUD. -**Sequential Workflow** - Agentide järjekordne täitmine, kus väljund voolab järgmisesse sammu. +**Järjestikune Töövoog (Sequential Workflow)** - Agentide järjestikune täitmine, kus väljund liigub järgmisesse sammu. -**Supervisor Agent Pattern** - Täiustatud agentide muster, kus juhendaja LLM otsustab dünaamiliselt, milliseid sub-agente kutsuda. +**Juhendaja Agendi Muster (Supervisor Agent Pattern)** - Täiustatud agentne muster, kus juhendaja LLM otsustab dünaamiliselt, milliseid alamagente kutsuda. ## Mudeli Konteksti Protokoll (MCP) - [Moodul 05](../05-mcp/README.md) -**langchain4j-mcp** - Maven sõltuvus MCP integreerimiseks LangChain4j'sse. +**langchain4j-mcp** - Maven sõltuvus MCP integreerimiseks LangChain4j-s. -**MCP** - Mudeli konteksti protokoll: standard AI rakenduste ühendamiseks väliste tööriistadega. Tee kord ja kasuta kõikjal. +**MCP** - Mudeli Konteksti Protokoll: standard AI rakenduste ühendamiseks väliste tööriistadega. Ehita üks kord, kasuta kõikjal. -**MCP Client** - Rakendus, mis ühendub MCP serveritega tööriistade leidmiseks ja kasutamiseks. +**MCP Klient** - Rakendus, mis ühendub MCP serveritega tööriistade avastamiseks ja kasutamiseks. -**MCP Server** - Teenus, mis eksponeerib tööriistu MCP kaudu koos selgete kirjelduste ja parameetrite skeemidega. +**MCP Server** - Teenus, mis pakub tööriistu MCP kaudu selgete kirjelduste ja parameetrite skeemidega. -**McpToolProvider** - LangChain4j komponent, mis pakib MCP tööriistad AI teenuste ja agentide kasutamiseks. +**McpToolProvider** - LangChain4j komponent, mis pakendab MCP tööriistad kasutamiseks AI teenustes ja agentides. -**McpTransport** - Liides MCP side jaoks. Rakendused: Stdio ja HTTP. +**McpTransport** - Liides MCP kommunikatsiooni jaoks. Implementatsioonid sisaldavad Stdio ja HTTP. -**Stdio Transport** - Kohalik protsessi transport läbi stdin/stdout. Kasulik failisüsteemi juurdepääsuks või käsurea tööriistadele. +**Stdio Transport** - Kohalik protsessi transport läbi stdin/stdout. Kasulik failisüsteemi ligipääsu või käsureatööriistade jaoks. -**StdioMcpTransport** - LangChain4j rakendus, mis käivitab MCP serveri alamprotsessina. +**StdioMcpTransport** - LangChain4j implementatsioon, mis käivitab MCP serveri alamprotsessina. -**Tool Discovery** - Klient küsib serverilt saadaval olevate tööriistade kirjeldusi ja skeeme. +**Tööriistade Avastamine** - Klient pärib serverilt saadaolevad tööriistad koos kirjelduste ja skeemidega. ## Azure Teenused - [Moodul 01](../01-introduction/README.md) -**Azure AI Search** - Pilvepõhine otsing koos vektorite võimetega. [Moodul 03](../03-rag/README.md) +**Azure AI Otsing** - Pilveotsing vektorvõimalustega. [Moodul 03](../03-rag/README.md) **Azure Developer CLI (azd)** - Azure ressursside juurutamine. -**Azure OpenAI** - Microsofti ettevõtete tehisintellekti teenus. +**Azure OpenAI** - Microsofti ettevõtte AI teenus. -**Bicep** - Azure infrastruktuuri koodikeel. [Infrastruktuuri juhend](../01-introduction/infra/README.md) +**Bicep** - Azure infrastruktuuri kui koodi keel. [Infrastruktuuri juhend](../01-introduction/infra/README.md) -**Deployment Name** - Nimi mudeli juurutamiseks Azure'is. +**Juurutuse Nimi** - Mudeli juurutuse nimi Azure'is. -**GPT-5.2** - Viimane OpenAI mudel mõtlemise juhtimisega. [Moodul 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Viimane OpenAI mudel mõtlemise kontrolliga. [Moodul 02](../02-prompt-engineering/README.md) -## Testimine ja Arendus - [Testimise juhend](TESTING.md) +## Testimine ja Arendus - [Testimise Juhend](TESTING.md) -**Dev Container** - Konteinerpõhine arenduskeskkond. [Seadistus](../../../.devcontainer/devcontainer.json) +**Dev Container** - Konteineriseeritud arenduskeskkond. [Konfiguratsioon](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Tasuta AI mudelite mänguväljak. [Moodul 00](../00-quick-start/README.md) +**Mälupõhine Testimine** - Testimine mälusalvestusega. -**In-Memory Testimine** - Testimine mälu baasil salvestusega. +**Integreerimistestimine** - Testimine reaalse infrastruktuuriga. -**Integration Testing** - Testimine päris infrastruktuuriga. +**Maven** - Java ehitamise automatiseerimise tööriist. -**Maven** - Java ehitustööriist. +**Mockito** - Java teema jäljendamise raamistik. -**Mockito** - Java testimise raamistik. - -**Spring Boot** - Java rakendusraamistik. [Moodul 01](../01-introduction/README.md) +**Spring Boot** - Java rakenduse raamistik. [Moodul 01](../01-introduction/README.md) --- -**Vastutusest loobumine**: -See dokument on tõlgitud kasutades tehisintellekti tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi püüame täpsust, tuleb arvestada, et automatiseeritud tõlkes võivad esineda vead või ebatäpsused. Originaaldokument oma emakeeles tuleks pidada autoriteetseks allikaks. Kriitilise informatsiooni puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud arusaamatuste ega valesti tõlgendamise eest. +**Lahtiütlus**: +See dokument on tõlgitud kasutades AI tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest. \ No newline at end of file diff --git a/translations/et/docs/TESTING.md b/translations/et/docs/TESTING.md index e3cf8e34b..2226a2101 100644 --- a/translations/et/docs/TESTING.md +++ b/translations/et/docs/TESTING.md @@ -2,19 +2,19 @@ ## Sisukord -- [Kiire algus](../../../docs) -- [Mida testid katavad](../../../docs) -- [Testide käivitamine](../../../docs) -- [Testide käivitamine VS Code'is](../../../docs) -- [Testimismustrid](../../../docs) -- [Testimise filosoofia](../../../docs) -- [Järgmised sammud](../../../docs) +- [Kiire algus](#kiire-algus) +- [Mida testid sisaldavad](#mida-testid-sisaldavad) +- [Testide käivitamine](#testide-käivitamine) +- [Testide käivitamine VS Code'is](#testide-käivitamine-vs-codeis) +- [Testimismustrid](#testimismustrid) +- [Testimise filosoofia](#testimise-filosoofia) +- [Järgmised sammud](#järgmised-sammud) -See juhend juhendab sind läbi testide, mis näitavad, kuidas testida tehisintellekti rakendusi ilma API võtmete või väliste teenusteta. +See juhend viib teid läbi testide, mis näitavad, kuidas testida AI rakendusi ilma API-võtmeteta või välist teenust kasutamata. ## Kiire algus -Käivita kõik testid ühe käsuga: +Käivitage kõik testid ühe käsuga: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Kui kõik testid läbivad, peaksid nägema väljundit nagu alloleval ekraanipildil — testid jooksid ilma ühegi veata. +Kui kõik testid läbivad, peaksite nägema väljundit nagu alloleval ekraanipildil — testid jooksevad ilma ühegi veata. -Edukas testide tulemus +Õnnestunud testi tulemused -*Edasijõudnud testide käivitamine, kus kõik testid läbisid ilma vigadeta* +*Õnnestunud testi täitmine, kus kõik testid läbivad ilma vigadeta* -## Mida testid katavad +## Mida testid sisaldavad -See kursus keskendub **ühikutestidele**, mis jooksevad lokaalselt. Iga test demonstreerib konkreetset LangChain4j kontseptsiooni isoleeritult. Allolev testimise püramiid näitab, kus ühikutestid sobituvad — need moodustavad kiire ja usaldusväärse aluse, millele ülejäänud testistrateegia tugineb. +See kursus keskendub **ühiktestidele**, mis jooksevad lokaalselt. Iga test demonstreerib konkreetset LangChain4j kontseptsiooni isolatsioonis. Allpool olev testimise püramiid näitab, kuhu ühiktestid mahuvad — need moodustavad kiiruse ja usaldusväärsuse aluse, millele teie ülejäänud testistrateegia toetub. Testimise püramiid -*Testimise püramiid näitab tasakaalu ühikutestide (kiired, isoleeritud), integratsioonitestide (päris komponendid) ja lõpuni-testide vahel. See koolitus käsitleb ühikutestimist.* +*Testimise püramiid näitab tasakaalu ühiktestide (kiired, isoleeritud), integratsioonitestide (päris komponendid) ja lõppastme testide vahel. See koolitus katab ühiketste.* | Moodul | Testid | Fookus | Olulised failid | |--------|--------|--------|-----------------| -| **00 - Kiire algus** | 6 | Käsu mallid ja muutujate asendamine | `SimpleQuickStartTest.java` | -| **01 - Sissejuhatus** | 8 | Vestlusmälu ja olekupõhine vestlus | `SimpleConversationTest.java` | -| **02 - Käsu inseneriteadus** | 12 | GPT-5.2 mustrid, innukuse tasemed, struktureeritud väljund | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Dokumendi importimine, vektorid, sarnasuse otsing | `DocumentServiceTest.java` | -| **04 - Tööriistad** | 12 | Funktsioonikutsed ja tööriistade kettimine | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Mudeli konteksti protokoll StdIO transpordiga | `SimpleMcpTest.java` | +| **01 - Sissejuhatus** | 8 | Vestluse mälu ja oleku säilitamine | `SimpleConversationTest.java` | +| **02 - Promptide inseneritöö** | 12 | GPT-5.2 mustrid, ootuse tasemed, struktureeritud väljund | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Dokumendi sisestamine, embeddingud, sarnasuse otsing | `DocumentServiceTest.java` | +| **04 - Tööriistad** | 12 | Funktsioonide kutsumine ja tööriistade ahelad | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol stdio transpordiga | `SimpleMcpTest.java` | ## Testide käivitamine -**Käivita kõik testid juurkataloogist:** +**Käivitage kõik testid juurest:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Käivita testid konkreetse mooduli jaoks:** +**Käivitage testid kindla mooduli jaoks:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Käivita üks testiklass:** +**Käivitage üks testiklass:** **Bash:** ```bash @@ -91,7 +90,7 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Käivita konkreetne testimeetod:** +**Käivitage konkreetne testimeetod:** **Bash:** ```bash @@ -105,31 +104,31 @@ mvn --% test -Dtest=SimpleConversationTest#peaks säilitama vestluse ajaloo ## Testide käivitamine VS Code'is -Kui kasutad Visual Studio Code'i, pakub Test Explorer graafilise liidese testide käivitamiseks ja silumiseks. +Kui kasutate Visual Studio Code'i, annab Test Explorer graafilise kasutajaliidese testide käivitamiseks ja silumiseks. VS Code Test Exploreri vaade -*VS Code Test Explorer näitab testipuu kõigi Java testiklasside ja üksikute testimeetoditega* +*VS Code Test Exploreri testipuu, kus on kõik Java testiklassid ja üksikud testimeetodid* **Testide käivitamiseks VS Code'is:** -1. Ava Test Explorer, klõpsates tegevusriba klaasikese ikoonile -2. Laienda testipuu, et näha kõiki mooduleid ja testiklasse -3. Klõpsa käivitusnupul mistahes testi kõrval, et seda üksikult käivitada -4. Klõpsa "Run All Tests", et käivitada kõik testid korraga -5. Paremklõpsa mistahes testil ja vali "Debug Test", et seada murdepunkte ja sammuda koodi läbi +1. Avage Test Explorer, klõpsates Activity Baril olevat mõõteriista ikooni +2. Laiendage testipuu, et näha kõiki mooduleid ja testiklasse +3. Klõpsake mängu ikoonil mis tahes testi kõrval, et seda individuaalselt käivitada +4. Klõpsake nuppu "Run All Tests", et käivitada kogu komplekt +5. Paremklõpsake mis tahes testi ja valige "Debug Test", et panna murdepunkte ja läbida koodi sammhaaval -Test Explorer näitab rohelisi linnukesi läbitud testide juures ja kuvab detailseid tõrketeateid vigade korral. +Test Explorer kuvab rohelisi linnukesi läbinud testide juures ja annab üksikasjalikud veateated, kui testid ebaõnnestuvad. ## Testimismustrid -### Muster 1: Käsu mallide testimine +### Muster 1: Promptide mallide testimine -Lihtsaim muster testib käsu malli ilma, et kutsutakse AI mudelit. Kontrollid, et muutujate asendamine toimib korrektselt ja käsud formeeritakse ootuspäraselt. +Kõige lihtsam muster testib promptide malle ilma AI mudelit kutsumata. Kontrollite, et muutujate asendamine toimiks õigesti ja promptid oleksid ootuspäraselt vormindatud. -Käsu malli testimine +Promptimalli testimine -*Käsu mallide testimine näitab muutujate asenduse protsessi: mall koos kohatäidetega → väärtused rakendatud → vormindatud väljund kontrollitud* +*Promptide mallide testimine, mis näitab muutujate asendamise voogu: mall kohatäitega → väärtuste rakendamine → vormindatud väljundi kontroll* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -See test asub failis `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +See muster kontrollib, et muutujate asendamine toimib õigesti ja promptid vormindatakse ootuspäraselt — API võtit ega mudelikõnet ei ole vaja. -**Käivita see:** +### Muster 2: Keelemudelite katmine -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testiPromptMallimiseVormindamine -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testiPromptMallideFormaatimine -``` - -### Muster 2: Keelemudelite nõelimine (mockimine) - -Vestlusloogika testimisel kasuta Mockito’t võltsmudelite loomiseks, mis tagastavad etteantud vastuseid. See teeb testid kiired, tasuta ja määratletavad. +Vestlusloogika testimisel kasutage Mockito, et luua võltsmudeleid, mis tagastavad eelnevalt määratud vastuseid. See teeb testid kiireks, tasuta ja deterministlikuks. -Mock vs Reaalne API võrdlus +Võltse ja päris API võrdlus -*Võrdlus, miks testimiseks eelistatakse mocke: need on kiired, tasuta, määratletavad ja ei vaja API võtmeid* +*Võrdlus, mis näitab, miks testimisel eelistatakse võltse: need on kiired, tasuta, deterministlikud ja EI vaja API võtmeid* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -See muster ilmub failis `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock tagab järjepideva käitumise, et kontrollida mälu haldamist korrektselt. +See muster ilmub failis `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Võlts tagab järjepideva käitumise, et kontrollida mälu haldust õigesti toimivat. ### Muster 3: Vestluse isoleerimise testimine -Vestlusmälul peab olema võime hoida erinevate kasutajate andmed eraldi. See test kontrollib, et vestlused ei sega kontekste omavahel. +Vestluse mälu peab kasutajaid eristama. See test kontrollib, et vestlused ei segaks kontekste. Vestluse isoleerimine -*Vestluse isoleerimise testimine, näidates eraldi mäluhoidlaid erinevate kasutajate jaoks, et vältida kontekstide juhtumist* +*Vestluse isoleerimise testimine näitab eraldi mäluhoidlaid eri kasutajate jaoks konteksti segamise vältimiseks* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Iga vestlus säilitab oma sõltumatu ajaloo. Tootmissüsteemides on see isoleeritus kriitiline mitme kasutajaga rakenduste jaoks. +Iga vestlus hoiab enda sõltumatut ajalugu. Tootmissüsteemides on see isoleeritus oluline mitmekasutajarakenduste jaoks. -### Muster 4: Tööriistade sõltumatu testimine +### Muster 4: Tööriistade eraldiseisev testimine -Tööriistad on AI poolt kutsutavad funktsioonid. Testi neid otse, et tagada nende korrektsus sõltumata AI otsustest. +Tööriistad on funktsioonid, mida AI saab kutsuda. Testige neid otse, et veenduda, et need töötavad õigesti, sõltumata AI otsustest. Tööriistade testimine -*Tööriistade sõltumatu testimine, kus mock-tööriistad töötavad ilma AI kutseta, kontrollimaks äri loogikat* +*Tööriistade eraldiseisev testimine näitab võltsimise tööriista käivitamist ilma AI kutsumata äriloogika kontrollimiseks* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Need testid failis `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` valideerivad tööriistade loogikat ilma AI kaasamiseta. Kettimise näide näitab, kuidas ühe tööriista väljund suunatakse teise sisendiks. +Need testid failist `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` valideerivad tööriistade loogikat ilma AI kaasamiseta. Ahela näide näitab, kuidas ühe tööriista väljund läheb teise sisendiks. -### Muster 5: Mälu-põhise RAG testimine +### Muster 5: Mälu-põhine RAG testimine -RAG süsteemid vajavad tavaliselt vektorandmebaase ja manustusteenuseid. Mälu-põhine muster lubab testida kogu töövoogu ilma väliste sõltuvusteta. +RAG süsteemid kasutavad tavaliselt vektordatabaase ja embedimis-teenuseid. Mälu-põhine muster võimaldab testida kogu torujuhet ilma väliste sõltuvusteta. Mälu-põhine RAG testimine -*Mälu-põhise RAG testimise töövoog, kus toimub dokumendi analüüs, manuste salvestus ja sarnasuse otsing ilma andmebaasi nõudmata* +*Mälu-põhise RAG testimisläbivaade, mis kuvab dokumendi töötlemist, embedimiste salvestamist ja sarnasuse otsingut ilma andmebaasi nõudmata* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -See test failist `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` loob dokumendi mälus ja kontrollib tükkideks jaotust ja metaandmete töötlemist. +See test failist `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` loob dokumendi mällu ja kontrollib tükkide tegemist ning metaandmete käitlemist. ### Muster 6: MCP integratsioonitestimine -MCP moodul testib Mudeli konteksti protokolli (Model Context Protocol) integreerimist stdio transpordi abil. Need testid kinnitavad, et sinu rakendus suudab käivitada ning suhelda MCP serveritega alamprotsessidena. +MCP moodul testib Model Context Protocol integreerimist stdio transpordi kaudu. Need testid kontrollivad, et teie rakendus saab käivitada ja suhelda MCP serveritega alamprotsessidena. Testid failis `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` valideerivad MCP kliendi käitumist. -**Käivita need:** +**Käivitage need:** **Bash:** ```bash @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Testimise filosoofia -Testeeri oma koodi, mitte AI-d. Sinu testid peaksid valideerima kirjutatud koodi kontrollides, kuidas käske konstrueeritakse, kuidas mälu hallatakse ja kuidas tööriistad täidetakse. AI vastused varieeruvad ega tohiks olla testide väidetes osa. Küsi endalt, kas sinu käsu mall asendab muutujad õigesti, mitte kas AI annab õige vastuse. +Testige oma koodi, mitte AI-d. Testid peaksid valideerima kirjutatud koodi, kontrollides, kuidas promptid konstrueeritakse, kuidas mälu hallatakse ja kuidas tööriistad täidetakse. AI vastused varieeruvad ega tohiks olla testi kinnituses osa. Küsige endalt, kas teie prompti mall asendab muutujaid õigesti, mitte seda, kas AI annab õige vastuse. -Kasuta mocks’i keelemudelite jaoks. Need on välised sõltuvused, mis on aeglased, kulukad ja määratlematud. Mockimine teeb testid kiired (millisekunditega sekundite asemel), tasuta ilma API kuludeta ja määratletavad iga kord sama tulemusega. +Kasutage keelemudelite puhul valemänge. Need on välised sõltuvused, mis on aeglased, kallid ja mitte-deterministlikud. Valemängud muudavad testid kiiremaks (millisekundites, mitte sekundites), tasuta (ilma API kuludeta) ja deterministlikuks (iga kord sama tulemus). -Hoidke testid sõltumatud. Iga test peaks seadistama oma andmed, mitte lootma teistele testidele ja pärast oma tööd koristama. Testid peaksid läbima sõltumata käivitamise järjekorrast. +Hoia testid iseseisvad. Iga test peaks seadistama oma andmed, mitte sõltuma teistest testidest ja puhastama enda järel. Testid peaksid läbima sõltumata käivitamise järjekorrast. -Testeeri äärejuhtumeid üle normaalse kasutuse. Proovi tühje sisendeid, väga suuri sisendeid, erimärke, sobimatuid parameetreid ja piirtingimusi. Need paljastavad sageli vigu, mida tavaline kasutus ei näita. +Testige äärmusjuhtumeid peale õnne tee. Katsetage tühjade sisenditega, väga suurte sisenditega, erimärkidega, vigaste parameetrite ja piiritingimustega. Need paljastavad tihti vead, mida tavakasutus ei näita. -Kasuta kirjeldavaid nimesid. Võrdle `shouldMaintainConversationHistoryAcrossMultipleMessages()` ja `test1()`. Esimene ütleb täpselt, mida testitakse, tehnikavigade parandamine on palju lihtsam. +Kasutage kirjeldavaid nimesid. Võrrelge `shouldMaintainConversationHistoryAcrossMultipleMessages()` ja `test1()`. Esimene ütleb täpselt, mida testitakse, muutes rikete silumise palju lihtsamaks. ## Järgmised sammud -Nüüd, kui sa mõistad testimismustreid, süüvi iga mooduli põhjalikumalt: +Nüüd, kui mõistate testimismustreid, sukeldage end sügavamale iga mooduli juurde: -- **[00 - Kiire algus](../00-quick-start/README.md)** - Alusta käsu mallide alustest -- **[01 - Sissejuhatus](../01-introduction/README.md)** - Õpi vestlusmälu haldust -- **[02 - Käsu inseneriteadus](../02/prompt-engineering/README.md)** - Master GPT-5.2 käsu mustrid -- **[03 - RAG](../03-rag/README.md)** - Ehita väljatoomisvõimendusega generaatorisüsteeme -- **[04 - Tööriistad](../04-tools/README.md)** - Rakenda funktsioonikutsed ja tööriistade kettimine -- **[05 - MCP](../05-mcp/README.md)** - Integreeri Model Context Protocol +- **[01 - Sissejuhatus](../01-introduction/README.md)** - Õppige vestluse mälu haldamist +- **[02 - Promptide inseneritöö](../02-prompt-engineering/README.md)** - Valdage GPT-5.2 promptide mustreid +- **[03 - RAG](../03-rag/README.md)** - Looge päringutega täiustatud generaatori süsteeme +- **[04 - Tööriistad](../04-tools/README.md)** - Rakendage funktsioonide kutsumist ja tööriistade ahelaid +- **[05 - MCP](../05-mcp/README.md)** - Integreerige Model Context Protocol -Iga mooduli README annab üksikasjaliku selgituse siin testitavate kontseptsioonide kohta. +Iga mooduli README annab üksikasjalikke seletusi siin testitud kontseptsioonide kohta. --- -**Navigeerimine:** [← Tagasi avalehele](../README.md) +**Navigeerimine:** [← Tagasi peamenüüsse](../README.md) --- -**Vastutusest loobumine**: -See dokument on tõlgitud kasutades tehisintellekti tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi püüame täpsust, palun pange tähele, et automaatsed tõlked võivad sisaldada vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlke kasutamisest tingitud võimalikest arusaamatustest või väärarusaamadest. +**Lahtiütlus**: +See dokument on tõlgitud kasutades AI tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest. \ No newline at end of file diff --git a/translations/fa/.co-op-translator.json b/translations/fa/.co-op-translator.json index 13c6ea7e5..f05263a1d 100644 --- a/translations/fa/.co-op-translator.json +++ b/translations/fa/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "fa" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T22:25:05+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T07:19:20+00:00", "source_file": "01-introduction/README.md", "language_code": "fa" }, @@ -18,20 +18,20 @@ "language_code": "fa" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T22:27:41+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T07:14:01+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "fa" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T22:29:20+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T07:18:25+00:00", "source_file": "03-rag/README.md", "language_code": "fa" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T12:17:22+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T07:16:53+00:00", "source_file": "04-tools/README.md", "language_code": "fa" }, @@ -54,8 +54,8 @@ "language_code": "fa" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:34:31+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T07:12:27+00:00", "source_file": "README.md", "language_code": "fa" }, @@ -72,14 +72,14 @@ "language_code": "fa" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T22:33:17+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T07:14:31+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "fa" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T22:34:03+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T07:15:21+00:00", "source_file": "docs/TESTING.md", "language_code": "fa" } diff --git a/translations/fa/00-quick-start/README.md b/translations/fa/00-quick-start/README.md deleted file mode 100644 index 7e5be0891..000000000 --- a/translations/fa/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# ماژول ۰۰: شروع سریع - -## فهرست مطالب - -- [مقدمه](../../../00-quick-start) -- [LangChain4j چیست؟](../../../00-quick-start) -- [وابستگی‌های LangChain4j](../../../00-quick-start) -- [پیش‌نیازها](../../../00-quick-start) -- [راه‌اندازی](../../../00-quick-start) - - [۱. دریافت توکن گیت‌هاب](../../../00-quick-start) - - [۲. تنظیم توکن خود](../../../00-quick-start) -- [اجرای نمونه‌ها](../../../00-quick-start) - - [۱. چت پایه](../../../00-quick-start) - - [۲. الگوهای پرامپت](../../../00-quick-start) - - [۳. فراخوانی تابع](../../../00-quick-start) - - [۴. پرسش و پاسخ اسناد (Easy RAG)](../../../00-quick-start) - - [۵. هوش مصنوعی مسئولانه](../../../00-quick-start) -- [هر مثال چه چیزی نشان می‌دهد](../../../00-quick-start) -- [گام‌های بعدی](../../../00-quick-start) -- [عیب‌یابی](../../../00-quick-start) - -## مقدمه - -این شروع سریع برای این است که شما را سریع‌تر با LangChain4j راه‌اندازی کند. این راهنما اصول اولیه ساخت برنامه‌های هوش مصنوعی با LangChain4j و مدل‌های گیت‌هاب را پوشش می‌دهد. در ماژول‌های بعدی به Azure OpenAI و GPT-5.2 سوئیچ خواهید کرد و هر مفهوم را عمیق‌تر بررسی می‌کنید. - -## LangChain4j چیست؟ - -LangChain4j یک کتابخانه جاوا است که ساخت برنامه‌های هوش مصنوعی را ساده می‌کند. به جای کار با کلاینت‌های HTTP و پارس کردن JSON، با APIهای تمیز جاوا کار می‌کنید. - -«زنجیره» در LangChain به معنی زنجیر کردن چندین مولفه است - ممکن است یک پرامپت را به یک مدل و سپس به یک پارسر متصل کنید، یا چند فراخوانی AI را به هم زنجیر کنید که خروجی یکی به ورودی بعدی می‌رود. این شروع سریع روی اصول اولیه متمرکز است پیش از آنکه زنجیره‌های پیچیده‌تر را بررسی کنیم. - -LangChain4j Chaining Concept - -*زنجیر کردن مولفه‌ها در LangChain4j - بلوک‌های سازنده متصل می‌شوند تا گردش‌کارهای قدرتمند هوش مصنوعی ایجاد کنند* - -ما از سه مولفه اصلی استفاده می‌کنیم: - -**ChatModel** - رابط تعامل با مدل هوش مصنوعی. تابع `model.chat("prompt")` را فراخوانی کنید و یک رشته پاسخ دریافت کنید. ما از `OpenAiOfficialChatModel` استفاده می‌کنیم که با نقطه‌های پایانی سازگار با OpenAI مانند مدل‌های GitHub کار می‌کند. - -**AiServices** - رابط‌های سرویس هوش مصنوعی با نوع ایمن ایجاد می‌کند. متدها را تعریف کنید، آن‌ها را با `@Tool` حاشیه‌نویسی کنید و LangChain4j هماهنگی را مدیریت می‌کند. هوش مصنوعی به طور خودکار هنگام نیاز متدهای جاوای شما را فراخوانی می‌کند. - -**MessageWindowChatMemory** - تاریخچه گفتگو را نگهداری می‌کند. بدون آن، هر درخواست مستقل است. با آن، هوش مصنوعی پیام‌های قبلی را به خاطر می‌سپارد و در چند نوبت زمینه را حفظ می‌کند. - -LangChain4j Architecture - -*معماری LangChain4j - مولفه‌های اصلی که با هم کار می‌کنند تا برنامه‌های هوش مصنوعی شما را توانمند کنند* - -## وابستگی‌های LangChain4j - -این شروع سریع از سه وابستگی Maven در [`pom.xml`](../../../00-quick-start/pom.xml) استفاده می‌کند: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -ماژول `langchain4j-open-ai-official` کلاس `OpenAiOfficialChatModel` را فراهم می‌کند که به APIهای سازگار با OpenAI متصل می‌شود. مدل‌های GitHub از همان قالب API استفاده می‌کنند، بنابراین نیاز به آداپتور خاصی نیست – کافی است آدرس پایه را به `https://models.github.ai/inference` تنظیم کنید. - -ماژول `langchain4j-easy-rag` جداسازی خودکار اسناد، جاسازی و بازیابی را فراهم می‌کند تا بتوانید برنامه‌های RAG بسازید بدون اینکه هر مرحله را دستی پیکربندی کنید. - -## پیش‌نیازها - -**از Dev Container استفاده می‌کنید؟** جاوا و Maven قبلاً نصب شده‌اند. فقط به توکن دسترسی شخصی گیت‌هاب نیاز دارید. - -**توسعه محلی:** -- جاوا ۲۱ یا بالاتر، Maven 3.9 یا بالاتر -- توکن دسترسی شخصی گیت‌هاب (دستورالعمل‌ها در پایین) - -> **توجه:** این ماژول از مدل `gpt-4.1-nano` از مدل‌های GitHub استفاده می‌کند. نام مدل را در کد تغییر ندهید – این نام برای کار با مدل‌های در دسترس GitHub تنظیم شده است. - -## راه‌اندازی - -### ۱. دریافت توکن گیت‌هاب - -۱. به [تنظیمات گیت‌هاب → توکن‌های دسترسی شخصی](https://github.com/settings/personal-access-tokens) بروید -۲. روی «Generate new token» کلیک کنید -۳. یک نام توصیفی تنظیم کنید (مثلاً «LangChain4j Demo») -۴. تاریخ انقضا را تنظیم کنید (۷ روز توصیه می‌شود) -۵. زیر «دسترسی‌های حساب»، بخش «Models» را پیدا کنید و روی «فقط خواندنی» تنظیم کنید -۶. روی «Generate token» کلیک کنید -۷. توکن را کپی و ذخیره کنید – دوباره نمایش داده نخواهد شد - -### ۲. تنظیم توکن خود - -**گزینه ۱: استفاده از VS Code (توصیه شده)** - -اگر از VS Code استفاده می‌کنید، توکن خود را به فایل `.env` در ریشه پروژه اضافه کنید: - -اگر فایل `.env` وجود ندارد، فایل `.env.example` را به `.env` کپی کنید یا یک فایل `.env` جدید در ریشه پروژه بسازید. - -**مثال فایل `.env`:** -```bash -# در /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -سپس می‌توانید به سادگی روی هر فایل دمو (مثلاً `BasicChatDemo.java`) در اکسپلورر راست‌کلیک کرده و **«Run Java»** را انتخاب کنید یا از پیکربندی‌های اجرا در پنل Run and Debug استفاده کنید. - -**گزینه ۲: استفاده از ترمینال** - -توکن را به عنوان متغیر محیطی تنظیم کنید: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## اجرای نمونه‌ها - -**استفاده از VS Code:** فقط روی هر فایل دمو در اکسپلورر راست‌کلیک کرده و **«Run Java»** را انتخاب کنید، یا از پیکربندی‌های اجرا در پنل Run and Debug استفاده کنید (اطمینان حاصل کنید که اول توکن را به فایل `.env` اضافه کرده‌اید). - -**استفاده از Maven:** به طور متناوب، می‌توانید از خط فرمان اجرا کنید: - -### ۱. چت پایه - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### ۲. الگوهای پرامپت - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -الگوهای zero-shot، few-shot، chain-of-thought و مبتنی بر نقش را نشان می‌دهد. - -### ۳. فراخوانی تابع - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -هوش مصنوعی به طور خودکار هنگام نیاز متدهای جاوای شما را فراخوانی می‌کند. - -### ۴. پرسش و پاسخ اسناد (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -سوالاتی در مورد اسناد خود با استفاده از Easy RAG با جاسازی و بازیابی خودکار بپرسید. - -### ۵. هوش مصنوعی مسئولانه - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -ببینید چگونه فیلترهای ایمنی هوش مصنوعی محتوای مضر را مسدود می‌کنند. - -## هر مثال چه چیزی نشان می‌دهد - -**چت پایه** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -از این‌جا شروع کنید تا LangChain4j را در ساده‌ترین حالت خودش ببینید. یک `OpenAiOfficialChatModel` می‌سازید، یک پرامپت با `.chat()` می‌فرستید و پاسخ را دریافت می‌کنید. این پایه را نشان می‌دهد: چگونه مدل‌ها را با نقاط پایانی سفارشی و کلید API مقداردهی اولیه کنید. وقتی این الگو را فهمیدید، بقیه‌ چیزها بر اساس آن ساخته می‌شوند. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 امتحان با چت [GitHub Copilot](https://github.com/features/copilot):** فایل [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) را باز کنید و بپرسید: -> - "چگونه در این کد از مدل‌های GitHub به Azure OpenAI سوئیچ کنم؟" -> - "چه پارامترهای دیگری را می‌توانم در OpenAiOfficialChatModel.builder() تنظیم کنم؟" -> - "چگونه می‌توانم به جای انتظار برای پاسخ کامل، پاسخ‌های استریم شده اضافه کنم؟" - -**مهندسی پرامپت** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -حالا که می‌دانید چگونه با مدل صحبت کنید، بیایید ببینیم چه چیزی به آن می‌گویید. این دمو از همان تنظیم مدل استفاده می‌کند اما پنج الگوی پرامپت مختلف را نشان می‌دهد. پرامپت‌های zero-shot برای دستورهای مستقیم، few-shot که از مثال‌ها یاد می‌گیرند، chain-of-thought که مراحل استدلال را نشان می‌دهد و پرامپت‌های مبتنی بر نقش که زمینه را تنظیم می‌کنند را امتحان کنید. خواهید دید همان مدل بسته به چارچوب بندی درخواست شما چطور پاسخ‌های بسیار متفاوتی می‌دهد. - -این دمو همچنین الگوهای پرامپت را نشان می‌دهد که روشی قدرتمند برای ایجاد پرامپت‌های قابل استفاده مجدد با متغیرها هستند. -مثال زیر پرامپتی را با استفاده از `PromptTemplate` در LangChain4j برای پر کردن متغیرها نشان می‌دهد. هوش مصنوعی بر اساس مقصد و فعالیت داده شده پاسخ خواهد داد. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 امتحان با چت [GitHub Copilot](https://github.com/features/copilot):** فایل [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) را باز کنید و بپرسید: -> - "تفاوت پرامپت zero-shot و few-shot چیست و چه زمانی هرکدام را باید استفاده کنم؟" -> - "پارامتر دما چگونه روی پاسخ‌های مدل تاثیر می‌گذارد؟" -> - "چند تکنیک برای جلوگیری از حملات تزریق پرامپت در تولید چیست؟" -> - "چگونه می‌توانم اشیاء PromptTemplate قابل استفاده مجدد برای الگوهای رایج بسازم؟" - -**ادغام ابزار** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -این‌جا LangChain4j قدرتمند می‌شود. شما از `AiServices` استفاده می‌کنید تا دستیار هوش مصنوعی بسازید که بتواند متدهای جاوای شما را فراخوانی کند. کافی است متدها را با `@Tool("توضیح")` حاشیه‌نویسی کنید و LangChain4j بقیه کارها را انجام می‌دهد – هوش مصنوعی به طور خودکار تصمیم می‌گیرد کی از هر ابزار استفاده کند بر اساس درخواست کاربر. این تکنیک فراخوانی تابع را نشان می‌دهد که کلید ساخت هوش مصنوعی است که می‌تواند اقدام انجام دهد نه فقط پاسخ دهد. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 امتحان با چت [GitHub Copilot](https://github.com/features/copilot):** فایل [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) را باز کنید و بپرسید: -> - "برچسب @Tool چگونه کار می‌کند و LangChain4j پشت صحنه با آن چه می‌کند؟" -> - "آیا هوش مصنوعی می‌تواند چند ابزار را به ترتیب برای حل مسائل پیچیده فراخوانی کند؟" -> - "اگر یک ابزار استثنا بیندازد چه اتفاقی می‌افتد – چطور باید خطاها را مدیریت کنم؟" -> - "چگونه یک API واقعی را به جای این مثال ماشین حساب یکپارچه کنم؟" - -**پرسش و پاسخ اسناد (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -اینجا RAG (تولید تقویت‌شده با بازیابی) با روش «Easy RAG» در LangChain4j را می‌بینید. اسناد بارگذاری، به صورت خودکار تقسیم و در یک حافظه درجا جاسازی می‌شوند، سپس بازیاب محتوا بخش‌های مرتبط را در زمان پرسش به هوش مصنوعی می‌دهد. هوش مصنوعی بر اساس اسناد شما پاسخ می‌دهد نه دانش عمومی خود. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 امتحان با چت [GitHub Copilot](https://github.com/features/copilot):** فایل [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) را باز کنید و بپرسید: -> - "چگونه RAG از هذیان‌های هوش مصنوعی جلوگیری می‌کند در مقایسه با استفاده از داده‌های آموزش مدل؟" -> - "تفاوت این روش آسان با یک خط لوله RAG سفارشی چیست؟" -> - "چگونه این را مقیاس‌پذیر کنم تا چندین سند یا پایگاه دانش بزرگ‌تر را اداره کند؟" - -**هوش مصنوعی مسئولانه** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -ساخت ایمنی هوش مصنوعی با محافظت چندلایه. این دمو دو لایه حفاظت که با هم کار می‌کنند را نشان می‌دهد: - -**بخش ۱: محافظ پایش ورودی LangChain4j** - پرامپت‌های خطرناک را قبل از رسیدن به مدل بزرگ زبان مسدود می‌کند. محافظ‌های سفارشی بسازید که کلمات یا الگوهای ممنوعه را بررسی کنند. این‌ها در کد شما اجرا می‌شوند، پس سریع و رایگان‌اند. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**بخش ۲: فیلترهای ایمنی ارائه‌دهنده** - مدل‌های GitHub دارای فیلترهای داخلی هستند که مواردی را که محافظ‌های شما ممکن است از دست بدهند، می‌گیرند. بلوک‌های سخت (خطای HTTP 400) برای تخلفات شدید و ردهای نرم که هوش مصنوعی مودبانه امتناع می‌کند را می‌بینید. - -> **🤖 امتحان با چت [GitHub Copilot](https://github.com/features/copilot):** فایل [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) را باز کنید و بپرسید: -> - "InputGuardrail چیست و چگونه می‌توانم محافظ خودم را بسازم؟" -> - "تفاوت بلوک سخت و رد نرم چیست؟" -> - "چرا باید هم محافظ‌ها و هم فیلترهای ارائه‌دهنده را با هم استفاده کرد؟" - -## گام‌های بعدی - -**ماژول بعدی:** [۰۱-مقدمه - شروع کار با LangChain4j](../01-introduction/README.md) - ---- - -**ناوبری:** [← بازگشت به اصلی](../README.md) | [بعدی: ماژول ۰۱ - مقدمه →](../01-introduction/README.md) - ---- - -## عیب‌یابی - -### ساخت نخستین‌بار Maven - -**مشکل:** اجرای اولیه `mvn clean compile` یا `mvn package` زمان زیادی می‌برد (۱۰-۱۵ دقیقه) - -**علت:** Maven نیاز دارد تمام وابستگی‌های پروژه (Spring Boot، کتابخانه‌های LangChain4j، SDKهای Azure و غیره) را برای اولین ساخت دانلود کند. - -**راه حل:** این رفتار عادی است. ساخت‌های بعدی بسیار سریع‌تر خواهند بود چون وابستگی‌ها به صورت محلی کش می‌شوند. زمان دانلود بستگی به سرعت شبکه شما دارد. - -### نحو دستورات Maven در PowerShell - -**مشکل:** دستورات Maven با خطای `Unknown lifecycle phase ".mainClass=..."` شکست می‌خورند -**علت**: پاورشل `=` را به عنوان عملگر انتساب متغیر تفسیر می‌کند که باعث خراب شدن نحو خاصیت Maven می‌شود - -**راه‌حل**: از عملگر توقف پارس `--%` قبل از فرمان Maven استفاده کنید: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -عملگر `--%` به پاورشل می‌گوید که تمام آرگومان‌های باقی‌مانده را بدون تفسیر به صورت دقیق به Maven ارسال کند. - -### نمایش شکلک در Windows PowerShell - -**مشکل**: پاسخ‌های AI به جای شکلک‌ها کاراکترهای نامفهوم (مثل `????` یا `â??`) را نمایش می‌دهند در پاورشل - -**علت**: رمزگذاری پیش‌فرض پاورشل از شکلک‌های UTF-8 پشتیبانی نمی‌کند - -**راه‌حل**: این دستور را قبل از اجرای برنامه‌های Java اجرا کنید: -```cmd -chcp 65001 -``` - -این باعث اجبار رمزگذاری UTF-8 در ترمینال می‌شود. همچنین می‌توانید از Windows Terminal که پشتیبانی بهتری از یونیکد دارد استفاده کنید. - -### اشکال‌زدایی تماس‌های API - -**مشکل**: خطاهای احراز هویت، محدودیت‌های نرخ، یا پاسخ‌های غیرمنتظره از مدل AI - -**راه‌حل**: مثال‌ها شامل `.logRequests(true)` و `.logResponses(true)` هستند تا تماس‌های API را در کنسول نشان دهند. این کمک می‌کند تا خطاهای احراز هویت، محدودیت‌های نرخ، یا پاسخ‌های غیرمنتظره را عیب‌یابی کنید. این گزینه‌ها را در محیط تولید حذف کنید تا حجم لاگ کاهش یابد. - ---- - - -**سلب مسئولیت**: -این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در پی دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است حاوی خطاها یا نادقتی‌هایی باشند. سند اصلی به زبان بومی خود باید به‌عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، استفاده از ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئول هیچ گونه سوءتفاهم یا تفسیر نادرستی که از کاربرد این ترجمه ناشی شود، نمی‌باشیم. - \ No newline at end of file diff --git a/translations/fa/01-introduction/README.md b/translations/fa/01-introduction/README.md index c3c4de20f..1bf290e25 100644 --- a/translations/fa/01-introduction/README.md +++ b/translations/fa/01-introduction/README.md @@ -2,86 +2,86 @@ ## فهرست مطالب -- [نمایش ویدئویی](../../../01-introduction) -- [آنچه یاد خواهید گرفت](../../../01-introduction) -- [پیش‌نیازها](../../../01-introduction) -- [درک مشکل اصلی](../../../01-introduction) -- [درک توکن‌ها](../../../01-introduction) -- [نحوه عملکرد حافظه](../../../01-introduction) -- [نحوه استفاده از LangChain4j](../../../01-introduction) -- [استقرار زیرساخت Azure OpenAI](../../../01-introduction) -- [اجرای برنامه به‌صورت محلی](../../../01-introduction) -- [استفاده از برنامه](../../../01-introduction) - - [چت ایستا (پنل چپ)](../../../01-introduction) - - [چت دارای وضعیت (پنل راست)](../../../01-introduction) -- [گام‌های بعدی](../../../01-introduction) - -## نمایش ویدئویی +- [بررسی ویدئویی](#بررسی-ویدئویی) +- [آنچه خواهید آموخت](#آنچه-خواهید-آموخت) +- [پیش‌نیازها](#پیش‌نیازها) +- [درک مشکل اصلی](#درک-مشکل-اصلی) +- [درک توکن‌ها](#درک-توکن‌ها) +- [چگونگی کارکرد حافظه](#چگونگی-کارکرد-حافظه) +- [نحوه استفاده از LangChain4j در این پروژه](#نحوه-استفاده-از-langchain4j-در-این-پروژه) +- [استقرار زیرساخت Azure OpenAI](#استقرار-زیرساخت-azure-openai) +- [اجرای برنامه به صورت محلی](#اجرای-برنامه-به-صورت-محلی) +- [استفاده از برنامه](#استفاده-از-برنامه) + - [چت بدون وضعیت (پنل سمت چپ)](#چت-بدون-وضعیت-پنل-سمت-چپ) + - [چت دارای وضعیت (پنل سمت راست)](#چت-دارای-وضعیت-پنل-سمت-راست) +- [گام‌های بعدی](#گام‌های-بعدی) + +## بررسی ویدئویی این جلسه زنده را تماشا کنید که توضیح می‌دهد چگونه با این ماژول شروع کنید: شروع کار با LangChain4j - جلسه زنده -## آنچه یاد خواهید گرفت +## آنچه خواهید آموخت -در شروع سریع، از مدل‌های GitHub برای ارسال درخواست‌ها، فراخوانی ابزارها، ساخت خط لوله RAG و آزمایش محافظ‌ها استفاده کردید. آن دموها نشان دادند چه چیزی ممکن است — اکنون به Azure OpenAI و GPT-5.2 سوئیچ می‌کنیم و شروع به ساخت برنامه‌های تولیدی می‌کنیم. این ماژول بر هوش مصنوعی مکالمه‌ای که زمینه را به خاطر می‌سپارد و وضعیت را حفظ می‌کند تمرکز دارد — مفاهیمی که آن دموهای شروع سریع در پشت صحنه استفاده کردند اما توضیح ندادند. +این نقطه شروع شما با LangChain4j و Azure OpenAI است. ما با اصول پایه شروع کرده و به ساخت برنامه‌های سبک تولید می‌پردازیم. این ماژول بر روی هوش مصنوعی مکالمه‌ای متمرکز است که زمینه را به خاطر می‌سپارد و وضعیت را حفظ می‌کند — مفاهیم پایه‌ای که هر ماژول بعدی بر اساس آن‌ها ساخته می‌شود. -در تمام این راهنما از GPT-5.2 Azure OpenAI استفاده خواهیم کرد چون قابلیت‌های پیشرفته استدلال آن رفتار الگوهای مختلف را واضح‌تر می‌کند. وقتی حافظه اضافه کنید، تفاوت را به روشنی خواهید دید. این کار فهمیدن اینکه هر مؤلفه چه چیزی به برنامه شما می‌آورد را آسان‌تر می‌کند. +در سراسر راهنما از GPT-5.2 شرکت Azure OpenAI استفاده خواهیم کرد چون قابلیت‌های استدلال پیشرفته آن رفتار الگوهای مختلف را مشهودتر می‌کند. وقتی حافظه اضافه می‌کنید، تفاوت به وضوح قابل مشاهده است. این درک آسان‌تری از نقش هر مؤلفه در برنامه شما ایجاد می‌کند. شما یک برنامه خواهید ساخت که هر دو الگو را نشان می‌دهد: -**چت ایستا** - هر درخواست مستقل است. مدل هیچ حافظه‌ای از پیام‌های قبلی ندارد. این همان الگویی است که در شروع سریع استفاده کردید. +**چت بدون وضعیت** – هر درخواست مستقل است. مدل هیچ‌گونه حافظه‌ای از پیام‌های قبلی ندارد. این ساده‌ترین نقطه شروع است. -**مکالمه دارای وضعیت** - هر درخواست شامل تاریخچه مکالمه است. مدل زمینه را در طول چندین نوبت حفظ می‌کند. این چیزی است که برنامه‌های تولیدی نیاز دارند. +**گفتگوی دارای وضعیت** – هر درخواست شامل تاریخچه گفتگو است. مدل در چندین دور مکالمه زمینه را حفظ می‌کند. این چیزی است که برنامه‌های تولیدی نیاز دارند. ## پیش‌نیازها -- اشتراک Azure با دسترسی Azure OpenAI +- اشتراک Azure با دسترسی به Azure OpenAI - Java 21، Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **توجه:** Java، Maven، Azure CLI و Azure Developer CLI (azd) در devcontainer ارائه شده از قبل نصب شده‌اند. +> **توجه:** Java، Maven، Azure CLI و Azure Developer CLI (azd) از پیش در کانتینر توسعه ارائه شده نصب هستند. -> **توجه:** این ماژول از GPT-5.2 روی Azure OpenAI استفاده می‌کند. استقرار به صورت خودکار از طریق `azd up` تنظیم می‌شود - نام مدل را در کد تغییر ندهید. +> **توجه:** این ماژول از GPT-5.2 روی Azure OpenAI استفاده می‌کند. استقرار به صورت خودکار از طریق `azd up` پیکربندی می‌شود - نام مدل در کد را تغییر ندهید. ## درک مشکل اصلی -مدل‌های زبانی ایستا هستند. هر فراخوان API مستقل است. اگر بگویید «اسم من جان است» و سپس بپرسید «اسم من چیست؟» مدل نمی‌داند که شما همین الان خودتان را معرفی کردید. هر درخواست را انگار اولین مکالمه‌ای است که تا به حال داشته‌اید، می‌داند. +مدل‌های زبان بدون وضعیت هستند. هر تماس API مستقل است. اگر بگویید «اسم من جان است» و سپس بپرسید «اسم من چیست؟»، مدل هیچ ایده‌ای ندارد که شما همین الان خودتان را معرفی کرده‌اید. هر درخواست را گویی اولین مکالمه شماست می‌پندارد. -این برای پرسش و پاسخ ساده خوب است اما برای برنامه‌های واقعی بی‌فایده است. ربات‌های خدمات مشتری باید به یاد داشته باشند چه گفته‌اید. دستیارهای شخصی نیاز به زمینه دارند. هر مکالمه چند مرحله‌ای به حافظه نیاز دارد. +این برای پرسش و پاسخ‌های ساده مناسب است ولی برای برنامه‌های واقعی بی‌فایده است. ربات‌های خدمات مشتری باید آنچه به آن‌ها گفته‌اید را به خاطر بسپارند. دستیارهای شخصی نیاز به زمینه دارند. هر مکالمه چند دوری نیازمند حافظه است. -نمودار زیر دو رویکرد را مقایسه می‌کند — در سمت چپ، یک فراخوان ایستا که نام شما را فراموش می‌کند؛ در سمت راست، یک فراخوان دارای وضعیت پشتیبانی شده توسط ChatMemory که آن را به یاد می‌آورد. +نمودار زیر دو رویکرد را مقایسه می‌کند — در سمت چپ، تماس بدون وضعیت که اسم شما را فراموش می‌کند؛ در سمت راست، تماس دارای وضعیت با پشتیبانی ChatMemory که آن را به یاد می‌آورد. -مکالمات ایستا در مقابل دارای وضعیت +گفتگوهای بدون وضعیت در مقابل با وضعیت -*تفاوت بین مکالمات ایستا (فراخوان‌های مستقل) و دارای وضعیت (آگاه به زمینه)* +*تفاوت بین گفتگوهای بدون وضعیت (تماس‌های مستقل) و دارای وضعیت (آگاه به زمینه)* ## درک توکن‌ها -قبل از شروع مکالمات، مهم است که توکن‌ها را بفهمیم - واحدهای پایه متن که مدل‌های زبانی پردازش می‌کنند: +قبل از ورود به مکالمات، مهم است که توکن‌ها را بفهمید - واحدهای پایه متن که مدل‌های زبان پردازش می‌کنند: توضیح توکن -*نمونه‌ای از چگونگی تقسیم متن به توکن‌ها - "I love AI!" به ۴ واحد پردازش جداگانه تبدیل می‌شود* +*مثال نحوه تجزیه متن به توکن‌ها - «I love AI!» به ۴ واحد پردازشی جداگانه تبدیل می‌شود* -توکن‌ها راهی هستند که مدل‌های هوش مصنوعی متن را اندازه‌گیری و پردازش می‌کنند. کلمات، نشانه‌گذاری و حتی فاصله‌ها می‌توانند توکن باشند. مدل شما محدودیت تعداد توکن‌هایی که می‌تواند یکجا پردازش کند را دارد (۴۰۰,۰۰۰ برای GPT-5.2، شامل حداکثر ۲۷۲,۰۰۰ توکن ورودی و ۱۲۸,۰۰۰ توکن خروجی). فهمیدن توکن‌ها به مدیریت طول مکالمه و هزینه‌ها کمک می‌کند. +توکن‌ها واحد اندازه‌گیری و پردازش متن از سوی مدل‌های هوش مصنوعی هستند. کلمات، نشانه‌گذاری و حتی فواصل ممکن است توکن باشند. مدل شما محدودیتی در تعداد توکن‌هایی که می‌تواند همزمان پردازش کند دارد (۴۰۰,۰۰۰ برای GPT-5.2، با حداکثر ۲۷۲,۰۰۰ توکن ورودی و ۱۲۸,۰۰۰ توکن خروجی). آگاهی از توکن‌ها به مدیریت طول مکالمه و هزینه‌ها کمک می‌کند. -## نحوه عملکرد حافظه +## چگونگی کارکرد حافظه -حافظه چت مشکل ایستا بودن را با حفظ تاریخچه مکالمه حل می‌کند. پیش از ارسال درخواست به مدل، چارچوب پیام‌های قبلی مرتبط را اضافه می‌کند. وقتی می‌پرسید «اسم من چیست؟»، سیستم در واقع تمام تاریخچه مکالمه را ارسال می‌کند تا مدل ببیند که پیش‌تر گفته بودید «اسم من جان است.» +حافظه چت مشکل بدون وضعیت بودن را با حفظ تاریخچه مکالمه حل می‌کند. قبل از ارسال درخواست به مدل، فریمورک پیام‌های مرتبط قبلی را در ابتدا قرار می‌دهد. وقتی می‌پرسید «اسم من چیست؟»، سیستم در واقع کل تاریخچه مکالمه را ارسال می‌کند تا مدل ببیند قبلاً گفتید «اسم من جان است.» -LangChain4j پیاده‌سازی‌هایی از حافظه ارائه می‌دهد که این کار را به صورت خودکار انجام می‌دهند. شما تعیین می‌کنید چند پیام نگهداری شود و چارچوب پنجره زمینه را مدیریت می‌کند. نمودار زیر نشان می‌دهد چگونه MessageWindowChatMemory پنجره‌ای لغزنده از پیام‌های اخیر را حفظ می‌کند. +LangChain4j پیاده‌سازی‌های حافظه را ارائه می‌دهد که این کار را به صورت خودکار مدیریت می‌کنند. شما تعیین می‌کنید که چند پیام حفظ شود و فریمورک پنجره زمینه را مدیریت می‌کند. نمودار زیر نشان می‌دهد چگونه MessageWindowChatMemory یک پنجره لغزشی از پیام‌های اخیر را حفظ می‌کند. مفهوم پنجره حافظه -*MessageWindowChatMemory پنجره لغزنده‌ای از پیام‌های اخیر نگه می‌دارد و پیام‌های قدیمی‌تر را به صورت خودکار حذف می‌کند* +*MessageWindowChatMemory یک پنجره لغزشی از پیام‌های اخیر حفظ می‌کند و به صورت خودکار پیام‌های قدیمی را حذف می‌کند* -## نحوه استفاده از LangChain4j +## نحوه استفاده از LangChain4j در این پروژه -این ماژول شروع سریع را با ادغام Spring Boot و افزودن حافظه مکالمه گسترش می‌دهد. اینجا چگونگی کنار هم قرار گرفتن بخش‌ها آمده است: +این ماژول Spring Boot را یکپارچه کرده و حافظه مکالمه را اضافه می‌کند. اجزا به این صورت کنار هم قرار می‌گیرند: -**وابستگی‌ها** - دو کتابخانه LangChain4j اضافه کنید: +**وابستگی‌ها** – افزودن دو کتابخانه LangChain4j: ```xml @@ -94,7 +94,7 @@ LangChain4j پیاده‌سازی‌هایی از حافظه ارائه می‌ ``` -**مدل چت** - Azure OpenAI را به‌عنوان یک bean در Spring پیکربندی کنید ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**مدل چت** – پیکربندی Azure OpenAI به عنوان یک bean در Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -سازنده اعتبارنامه‌ها را از متغیرهای محیطی که توسط `azd up` تنظیم شده‌اند می‌خواند. تنظیم `baseUrl` به نقطه پایان Azure شما باعث می‌شود کلاینت OpenAI با Azure OpenAI کار کند. +سازنده اطلاعات کاربری را از متغیرهای محیطی که توسط `azd up` تنظیم شده‌اند می‌خواند. تنظیم `baseUrl` به نقطه پایانی Azure شما باعث می‌شود کلاینت OpenAI با Azure OpenAI کار کند. -**حافظه مکالمه** - تاریخچه چت را با MessageWindowChatMemory پیگیری کنید ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**حافظه مکالمه** – پیگیری تاریخچه چت با MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,18 +124,18 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -حافظه را با `withMaxMessages(10)` ایجاد کنید تا ۱۰ پیام آخر را نگه دارد. پیام‌های کاربر و هوش مصنوعی را با پوشش‌های تایپ شده `UserMessage.from(text)` و `AiMessage.from(text)` اضافه کنید. تاریخچه را با `memory.messages()` بازیابی کنید و به مدل ارسال کنید. این سرویس نمونه‌های حافظه جداگانه به ازای هر شناسه مکالمه ذخیره می‌کند، که به چند کاربر اجازه می‌دهد به طور همزمان گفتگو کنند. +با `withMaxMessages(10)` حافظه را می‌سازید تا ۱۰ پیام اخیر را حفظ کند. پیام‌های کاربر و هوش مصنوعی را با کپسول‌های نوعی شده می‌افزایید: `UserMessage.from(text)` و `AiMessage.from(text)`. تاریخچه را با `memory.messages()` دریافت کرده و به مدل ارسال می‌کنید. سرویس نمونه‌های حافظه جداگانه برای هر شناسه مکالمه نگه می‌دارد تا چندین کاربر بتوانند همزمان گفتگو کنند. -> **🤖 امتحان کنید با گفتگوی [GitHub Copilot](https://github.com/features/copilot):** فایل [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) را باز کنید و بپرسید: -> - «MessageWindowChatMemory چگونه تصمیم می‌گیرد کدام پیام‌ها را وقتی پنجره پر است حذف کند؟» -> - «آیا می‌توانم ذخیره‌سازی حافظه سفارشی با استفاده از پایگاه داده به جای حافظه درون‌برنامه‌ای پیاده کنم؟» -> - «چگونه می‌توانم خلاصه‌سازی برای فشرده‌سازی تاریخچه قدیمی مکالمه اضافه کنم؟» +> **🤖 امتحان با چت [GitHub Copilot](https://github.com/features/copilot):** فایل [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) را باز کرده و بپرسید: +> - "MessageWindowChatMemory چگونه تصمیم می‌گیرد وقتی پنجره پر است کدام پیام‌ها را حذف کند؟" +> - "آیا می‌توانم حافظه سفارشی را با استفاده از پایگاه داده به جای درون‌حافظه‌ای پیاده‌سازی کنم؟" +> - "چگونه می‌توانم خلاصه‌سازی برای فشرده‌سازی تاریخچه قدیمی مکالمه اضافه کنم؟" -نقطه پایان چت ایستا حافظه را به کلی رد می‌کند — فقط `chatModel.chat(prompt)` مانند شروع سریع. نقطه پایان دارای وضعیت پیام‌ها را به حافظه اضافه می‌کند، تاریخچه را بازیابی می‌کند و آن زمینه را با هر درخواست می‌فرستد. همان پیکربندی مدل، الگوهای متفاوت. +نقطه پایان چت بدون وضعیت کاملاً حافظه را نادیده می‌گیرد - به سادگی `chatModel.chat(prompt)` مانند راه‌اندازی سریع. نقطه پایان دارای وضعیت پیام‌ها را به حافظه اضافه می‌کند، تاریخچه را بازیابی کرده و آن زمینه را با هر درخواست می‌فرستد. پیکربندی مدل یکسان است، ولی الگوها متفاوتند. ## استقرار زیرساخت Azure OpenAI -**Bash:** +**بش:** ```bash cd 01-introduction azd up # اشتراک و مکان را انتخاب کنید (eastus2 توصیه می‌شود) @@ -144,21 +144,21 @@ azd up # اشتراک و مکان را انتخاب کنید (eastus2 توصی **PowerShell:** ```powershell cd 01-introduction -azd up # اشتراک و موقعیت را انتخاب کنید (پیشنهاد شده: eastus2) +azd up # اشتراک و مکان را انتخاب کنید (eastus2 توصیه می‌شود) ``` -> **توجه:** اگر با خطای زمان انتظار (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) مواجه شدید، کافی است دوباره `azd up` را اجرا کنید. منابع Azure ممکن است هنوز در پس‌زمینه در حال آماده‌سازی باشند و تلاش مجدد اجازه می‌دهد استقرار پس از رسیدن منابع به حالت نهایی کامل شود. +> **توجه:** اگر خطای زمان‌تمامی (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) دریافت کردید، کافیست دوباره `azd up` را اجرا کنید. منابع Azure ممکن است هنوز در حال استقرار باشند و تکرار باعث می‌شود استقرار وقتی منابع به حالت نهایی می‌رسند تکمیل شود. -این کارها را انجام خواهد داد: +این کار موارد زیر را انجام می‌دهد: 1. استقرار منبع Azure OpenAI با مدل‌های GPT-5.2 و text-embedding-3-small -2. تولید خودکار فایل `.env` در روت پروژه با اعتبارنامه‌ها -3. تنظیم تمام متغیرهای محیطی لازم +2. ایجاد خودکار فایل `.env` در ریشه پروژه با مدارک +3. تنظیم همه متغیرهای محیطی مورد نیاز -**مشکل در استقرار دارید؟** راهنمای عیب‌یابی دقیق شامل تعارض نام دامنه فرعی، مراحل استقرار دستی در Azure Portal، و راهنمای پیکربندی مدل را در [Infrastructure README](infra/README.md) ببینید. +**در صورت بروز مشکل در استقرار:** راهنمای [README زیرساخت](infra/README.md) را ببینید شامل رفع تعارض نام زیردامنه، مراحل استقرار دستی در Azure Portal و راهنمای پیکربندی مدل. -**بررسی موفقیت استقرار:** +**تأیید موفقیت استقرار:** -**Bash:** +**بش:** ```bash cat ../.env # باید AZURE_OPENAI_ENDPOINT، API_KEY و غیره را نشان دهد. ``` @@ -168,9 +168,9 @@ cat ../.env # باید AZURE_OPENAI_ENDPOINT، API_KEY و غیره را نشا Get-Content ..\.env # باید AZURE_OPENAI_ENDPOINT، API_KEY و غیره را نشان دهد. ``` -> **توجه:** دستور `azd up` به صورت خودکار فایل `.env` را ایجاد می‌کند. اگر بعداً نیاز به به‌روزرسانی دارید، می‌توانید یا فایل `.env` را به صورت دستی ویرایش کنید یا آن را با اجرای: +> **توجه:** دستور `azd up` به طور خودکار فایل `.env` را ایجاد می‌کند. اگر بعداً نیاز به به‌روزرسانی داشتید، می‌توانید یا به صورت دستی آن را ویرایش کنید یا با اجرای: > -> **Bash:** +> **بش:** > ```bash > cd .. > bash .azd-env.sh @@ -182,15 +182,15 @@ Get-Content ..\.env # باید AZURE_OPENAI_ENDPOINT، API_KEY و غیره را > .\.azd-env.ps1 > ``` -## اجرای برنامه به‌صورت محلی +## اجرای برنامه به صورت محلی -**بررسی استقرار:** +**تأیید استقرار:** -اطمینان حاصل کنید فایل `.env` در دایرکتوری ریشه با اعتبارنامه‌های Azure موجود است. این را از دایرکتوری ماژول (`01-introduction/`) اجرا کنید: +مطمئن شوید فایل `.env` با مدارک Azure در شاخه ریشه وجود دارد. این فرمان را از پوشه ماژول (`01-introduction/`) اجرا کنید: -**Bash:** +**بش:** ```bash -cat ../.env # باید AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT را نمایش دهد +cat ../.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نشان دهد ``` **PowerShell:** @@ -200,27 +200,27 @@ Get-Content ..\.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT ر **شروع برنامه‌ها:** -**گزینه ۱: استفاده از Spring Boot Dashboard (توصیه شده برای کاربران VS Code)** +**گزینه ۱: استفاده از داشبورد Spring Boot (توصیه شده برای کاربران VS Code)** -dev container شامل افزونه Spring Boot Dashboard است که رابطی بصری برای مدیریت همه برنامه‌های Spring Boot فراهم می‌کند. می‌توانید آن را در Activity Bar در سمت چپ VS Code پیدا کنید (آیکون Spring Boot را ببینید). +کانتینر توسعه دارای افزونه Spring Boot Dashboard است که رابط بصری برای مدیریت همه برنامه‌های Spring Boot فراهم می‌کند. می‌توانید آن را در نوار فعالیت سمت چپ VS Code ببینید (آیکون Spring Boot). -از Spring Boot Dashboard می‌توانید: +از داشبورد Spring Boot می‌توانید: - همه برنامه‌های Spring Boot موجود در فضای کاری را ببینید -- با یک کلیک برنامه‌ها را شروع یا متوقف کنید +- برنامه‌ها را با یک کلیک شروع/توقف کنید - لاگ‌های برنامه را به صورت زنده مشاهده کنید -- وضعیت برنامه‌ها را نظارت کنید +- وضعیت برنامه را نظارت کنید -فقط روی دکمه پلی کنار "introduction" کلیک کنید تا این ماژول شروع شود، یا همه ماژول‌ها را یک‌جا اجرا کنید. +کافیست روی دکمه پخش کنار "introduction" کلیک کنید تا این ماژول شروع شود، یا همه ماژول‌ها را همزمان اجرا کنید. -Spring Boot Dashboard +داشبورد Spring Boot *داشبورد Spring Boot در VS Code — شروع، توقف و نظارت بر همه ماژول‌ها از یک مکان* **گزینه ۲: استفاده از اسکریپت‌های شل** -تمام برنامه‌های وب (ماژول‌های ۰۱ تا ۰۴) را اجرا کنید: +تمام برنامه‌های وب (ماژول‌های ۰۱ تا ۰۴) را شروع کنید: -**Bash:** +**بش:** ```bash cd .. # از دایرکتوری ریشه ./start-all.sh @@ -228,13 +228,13 @@ cd .. # از دایرکتوری ریشه **PowerShell:** ```powershell -cd .. # از فهرست ریشه +cd .. # از دایرکتوری ریشه .\start-all.ps1 ``` -یا فقط این ماژول را اجرا کنید: +یا فقط همین ماژول را اجرا کنید: -**Bash:** +**بش:** ```bash cd 01-introduction ./start.sh @@ -246,11 +246,11 @@ cd 01-introduction .\start.ps1 ``` -هر دو اسکریپت به صورت خودکار متغیرهای محیطی را از فایل `.env` ریشه بارگذاری می‌کنند و در صورت نبود، فایل‌های JAR را می‌سازند. +هر دو اسکریپت به صورت خودکار متغیرهای محیطی را از فایل `.env` ریشه بارگذاری می‌کنند و در صورت عدم وجود، فایل‌های JAR را می‌سازند. -> **توجه:** اگر ترجیح می‌دهید همه ماژول‌ها را دستی قبل از شروع بسازید: +> **توجه:** اگر می‌خواهید همه ماژول‌ها را به صورت دستی بسازید قبل از شروع: > -> **Bash:** +> **بش:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests @@ -262,11 +262,11 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -مرورگر خود را باز کرده و http://localhost:8080 را مشاهده کنید. +در مرورگر خود http://localhost:8080 را باز کنید. **برای توقف:** -**Bash:** +**بش:** ```bash ./stop.sh # فقط این ماژول # یا @@ -277,46 +277,46 @@ cd .. && ./stop-all.sh # همه ماژول‌ها ```powershell .\stop.ps1 # فقط این ماژول # یا -cd ..; .\stop-all.ps1 # همه ماژول‌ها +cd ..; .\stop-all.ps1 # تمام ماژول‌ها ``` ## استفاده از برنامه -این برنامه یک رابط وب با دو پیاده‌سازی چت کنار هم فراهم می‌کند. +برنامه رابط وب با دو پیاده‌سازی چت را به صورت کنار هم ارائه می‌دهد. صفحه اصلی برنامه -*داشبورد نشان‌دهنده گزینه‌های چت ساده (ایستا) و چت مکالمه‌ای (دارای وضعیت)* +*داشبورد نمایش‌دهنده هر دو گزینه چت ساده (بدون وضعیت) و چت مکالمه‌ای (دارای وضعیت)* -### چت ایستا (پنل چپ) +### چت بدون وضعیت (پنل سمت چپ) -ابتدا این را امتحان کنید. بگویید «اسم من جان است» و سپس فوراً بپرسید «اسم من چیست؟» مدل به یاد نمی‌آورد چون هر پیام مستقل است. این نشان‌دهنده مشکل اصلی ادغام ساده مدل‌های زبانی — نبود زمینه مکالمه — است. +اول این را امتحان کنید. بگویید «اسم من جان است» و بلافاصله بعد بپرسید «اسم من چیست؟» مدل به خاطر نمی‌آورد چون هر پیام مستقل است. این مشکل اصلی ادغام اولیه مدل زبان است — بدون زمینه مکالمه. -دموی چت ایستا +دموی چت بدون وضعیت -*هوش مصنوعی نام شما را از پیام قبلی به یاد نمی‌آورد* +*هوش مصنوعی اسم شما را از پیام قبلی به خاطر نمی‌آورد* -### چت دارای وضعیت (پنل راست) +### چت دارای وضعیت (پنل سمت راست) -اکنون همان دنباله را اینجا امتحان کنید. بگویید «اسم من جان است» و سپس بپرسید «اسم من چیست؟» این بار به یاد دارد. تفاوت MessageWindowChatMemory است — تاریخچه مکالمه را حفظ می‌کند و با هر درخواست آن را ارسال می‌کند. این همان کاری است که هوش مصنوعی مکالمه‌ای در تولید انجام می‌دهد. +حالا همین دنباله را اینجا امتحان کنید. «اسم من جان است» و سپس «اسم من چیست؟» این بار مدل به خاطر می‌آورد. تفاوت پیام‌ها توسط MessageWindowChatMemory است - که تاریخچه مکالمه را حفظ کرده و با هر درخواست می‌فرستد. این همان طریقه کار هوش مصنوعی مکالمه‌ای تولیدی است. دموی چت دارای وضعیت -*هوش مصنوعی نام شما را از ابتدای مکالمه به یاد می‌آورد* +*هوش مصنوعی اسم شما را از ابتدای مکالمه به یاد دارد* -هر دو پنل از همان مدل GPT-5.2 استفاده می‌کنند. تنها تفاوت حافظه است. این واضح می‌کند که حافظه چه چیزی به برنامه شما می‌آورد و چرا برای موارد واقعی ضروری است. +هر دو پنل از مدل GPT-5.2 یکسان استفاده می‌کنند. تنها تفاوت حافظه است. این به وضوح نشان می‌دهد حافظه چه مزیتی به برنامه شما می‌دهد و چرا برای موارد واقعی ضروری است. ## گام‌های بعدی -**ماژول بعدی:** [۰۲-مهندسی_پرومپت - مهندسی پرومپت با GPT-5.2](../02-prompt-engineering/README.md) +**ماژول بعدی:** [۰۲-مهندسی پرامپت - مهندسی پرامپت با GPT-5.2](../02-prompt-engineering/README.md) --- -**ناوبری:** [← قبلی: ماژول ۰۰ - شروع سریع](../00-quick-start/README.md) | [بازگشت به اصلی](../README.md) | [بعدی: ماژول ۰۲ - مهندسی پرومپت →](../02-prompt-engineering/README.md) +**ناوبری:** [← بازگشت به اصلی](../README.md) | [بعدی: ماژول ۰۲ - مهندسی پرامپت →](../02-prompt-engineering/README.md) --- -**توضیح مهم**: -این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نواقصی باشد. سند اصلی به زبان بومی خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، استفاده از ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئول هیچ گونه سوء تفاهم یا تفسیر نادرستی که از استفاده این ترجمه ناشی شود، نیستیم. +**سلب مسئولیت**: +این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم. \ No newline at end of file diff --git a/translations/fa/02-prompt-engineering/README.md b/translations/fa/02-prompt-engineering/README.md index f5ff7b882..6f05f5786 100644 --- a/translations/fa/02-prompt-engineering/README.md +++ b/translations/fa/02-prompt-engineering/README.md @@ -2,100 +2,100 @@ ## فهرست مطالب -- [مرور ویدیو](../../../02-prompt-engineering) -- [آنچه خواهید آموخت](../../../02-prompt-engineering) -- [پیش‌نیازها](../../../02-prompt-engineering) -- [درک مهندسی پرامپت](../../../02-prompt-engineering) -- [مبانی مهندسی پرامپت](../../../02-prompt-engineering) - - [پرامپت بدون نمونه (Zero-Shot)](../../../02-prompt-engineering) - - [پرامپت با نمونه‌های محدود (Few-Shot)](../../../02-prompt-engineering) - - [زنجیره فکری (Chain of Thought)](../../../02-prompt-engineering) - - [پرامپت مبتنی بر نقش](../../../02-prompt-engineering) - - [قالب‌های پرامپت](../../../02-prompt-engineering) -- [الگوهای پیشرفته](../../../02-prompt-engineering) -- [اجرای برنامه](../../../02-prompt-engineering) -- [اسکرین‌شات‌های برنامه](../../../02-prompt-engineering) -- [کاوش الگوها](../../../02-prompt-engineering) - - [تمایل کم در مقابل تمایل زیاد](../../../02-prompt-engineering) - - [اجرای کار (پیش‌گفتارهای ابزار)](../../../02-prompt-engineering) - - [کد خودبازتابی](../../../02-prompt-engineering) - - [تحلیل ساخت‌یافته](../../../02-prompt-engineering) - - [چت چندمرحله‌ای](../../../02-prompt-engineering) - - [استدلال گام‌به‌گام](../../../02-prompt-engineering) - - [خروجی محدود شده](../../../02-prompt-engineering) -- [آنچه واقعاً می‌آموزید](../../../02-prompt-engineering) -- [مرحله بعدی](../../../02-prompt-engineering) - -## مرور ویدیو +- [نمایش ویدئو](#نمایش-ویدئو) +- [چیزهایی که یاد می‌گیرید](#چیزهایی-که-یاد-می‌گیرید) +- [پیش‌نیازها](#پیش‌نیازها) +- [درک مهندسی پرامپت](#درک-مهندسی-پرامپت) +- [اصول مهندسی پرامپت](#اصول-مهندسی-پرامپت) + - [پرامپت صفر-شات](#پرامپت-صفر-شات) + - [پرامپت چند-شات](#پرامپت-چند-شات) + - [زنجیره تفکر](#زنجیره-تفکر) + - [پرامپت بر اساس نقش](#پرامپت-بر-اساس-نقش) + - [قالب‌های پرامپت](#قالب‌های-پرامپت) +- [الگوهای پیشرفته](#الگوهای-پیشرفته) +- [اجرای برنامه](#اجرای-برنامه) +- [تصاویر برنامه](#تصاویر-برنامه) +- [کاوش در الگوها](#بررسی-الگوها) + - [انگیزه کم در مقابل انگیزه زیاد](#اشتیاق-کم-در-مقابل-اشتیاق-زیاد) + - [اجرای وظیفه (مقدمه‌های ابزار)](#اجرای-کار-پیش‌نویس-ابزارها) + - [کد خودبازتابی](#کد-خودبازتابی) + - [تحلیل ساختاریافته](#تحلیل-ساختاریافته) + - [چت چند مرحله‌ای](#چت-چندمرحله‌ای) + - [استدلال مرحله به مرحله](#استدلال-گام‌به‌گام) + - [خروجی محدود شده](#خروجی-محدودشده) +- [آنچه واقعاً یاد می‌گیرید](#آنچه-واقعاً-یاد-می‌گیرید) +- [گام‌های بعدی](#مراحل-بعدی) + +## نمایش ویدئو این جلسه زنده را تماشا کنید که توضیح می‌دهد چگونه با این ماژول شروع کنید: مهندسی پرامپت با LangChain4j - جلسه زنده -## آنچه خواهید آموخت +## چیزهایی که یاد می‌گیرید -نمودار زیر نمای کلی از موضوعات و مهارت‌های کلیدی که در این ماژول توسعه خواهید داد را نشان می‌دهد — از تکنیک‌های بهبود پرامپت تا جریان کاری گام‌به‌گام که دنبال خواهید کرد. +نمودار زیر نمای کلی از موضوعات و مهارت‌های کلیدی را که در این ماژول توسعه خواهید داد ارائه می‌دهد — از تکنیک‌های اصلاح پرامپت گرفته تا جریان کاری مرحله به مرحله‌ای که دنبال خواهید کرد. -آنچه خواهید آموخت +چیزهایی که یاد می‌گیرید -در ماژول‌های قبلی، تعاملات پایه LangChain4j با مدل‌های GitHub را بررسی کردید و دیدید که چگونه حافظه AI گفتگو محور با Azure OpenAI را امکان‌پذیر می‌کند. حالا تمرکز ما روی نحوه پرسیدن سوالات — خود پرامپت‌ها — با استفاده از GPT-5.2 Azure OpenAI است. نحوه ساختاردهی پرامپت‌ها تأثیر چشمگیری بر کیفیت پاسخ‌هایی که دریافت می‌کنید دارد. ابتدا تکنیک‌های بنیادی پرامپت را مرور می‌کنیم، سپس به هشت الگوی پیشرفته می‌پردازیم که از قابلیت‌های GPT-5.2 به‌طور کامل بهره‌مند می‌شوند. +در ماژول قبلی، دیدید که چگونه حافظه به هوش مصنوعی مکالمه‌ای با Azure OpenAI امکان می‌دهد. حالا تمرکز ما روی نحوه پرسیدن سوالات است — خود پرامپت‌ها — با استفاده از GPT-5.2 در Azure OpenAI. نحوه ساختاردهی پرامپت‌ها تأثیر چشمگیری بر کیفیت پاسخ‌هایی که می‌گیرید دارد. ما با مرور تکنیک‌های بنیادی پرامپت شروع می‌کنیم، سپس به هشت الگوی پیشرفته می‌پردازیم که از تمام قابلیت‌های GPT-5.2 بهره می‌برند. -ما از GPT-5.2 استفاده می‌کنیم چون کنترل استدلال را معرفی می‌کند - می‌توانید به مدل بگویید چقدر باید قبل از پاسخ فکر کند. این باعث می‌شود استراتژی‌های مختلف پرامپت واضح‌تر شده و به شما کمک می‌کند بفهمید کِی و چگونه از هر روش استفاده کنید. همچنین از محدودیت نرخ کمتر Azure برای GPT-5.2 نسبت به مدل‌های GitHub بهره‌مند می‌شویم. +ما از GPT-5.2 استفاده می‌کنیم زیرا کنترل استدلال را معرفی می‌کند - می‌توانید به مدل بگویید چقدر باید قبل از پاسخ تفکر کند. این باعث می‌شود استراتژی‌های مختلف پرامپت واضح‌تر شود و به شما کمک می‌کند بفهمید چه موقع از هر روش استفاده کنید. ## پیش‌نیازها - تکمیل ماژول ۰۱ (منابع Azure OpenAI مستقر شده) -- فایل `.env` در شاخه ریشه با اعتبارنامه‌های Azure (ساخته شده توسط دستور `azd up` در ماژول ۰۱) +- فایل `.env` در ریشه دایرکتوری با مدارک Azure (ایجاد شده توسط `azd up` در ماژول ۰۱) > **توجه:** اگر ماژول ۰۱ را تکمیل نکرده‌اید، ابتدا دستورالعمل‌های استقرار آن را دنبال کنید. ## درک مهندسی پرامپت -در اصل، مهندسی پرامپت تفاوت بین دستورهای مبهم و دقیق است، همان‌طور که مقایسه زیر نشان می‌دهد. +در اصل، مهندسی پرامپت تفاوت بین دستورالعمل‌های مبهم و دستورالعمل‌های دقیق است، همانطور که مقایسه زیر نشان می‌دهد. مهندسی پرامپت چیست؟ -مهندسی پرامپت مربوط به طراحی متنی است که به طور مداوم نتایجی را که نیاز دارید به شما بدهد. فقط پرسیدن سوال نیست — بلکه ساختار دادن درخواست‌هاست به طوری که مدل دقیقاً بفهمد چه می‌خواهید و چگونه آن را ارائه دهد. +مهندسی پرامپت درباره طراحی متن ورودی است که به طور مداوم نتایجی را که نیاز دارید به شما می‌دهد. فقط پرسیدن سوال نیست - بلکه ساختاربندی درخواست‌هاست تا مدل دقیقاً بفهمد چه می‌خواهید و چگونه آن را ارائه دهد. -این را مانند دادن دستور به یک همکار در نظر بگیرید. "رفع اشکال کن" گنگ است. "رفع خطای null pointer در UserService.java خط ۴۵ با افزودن بررسی null" دقیق است. مدل‌های زبانی نیز همین‌طور کار می‌کنند — دقت و ساختار اهمیت دارد. +به آن مثل دادن دستورالعمل به یک همکار فکر کنید. "اشکال را رفع کن" مبهم است. "رفع خطای اشاره‌گر null در UserService.java خط ۴۵ با افزودن بررسی null" دقیق است. مدل‌های زبانی نیز به همین صورت کار می‌کنند - دقت و ساختار اهمیت دارد. -نمودار زیر نشان می‌دهد که چگونه LangChain4j در این تصویر جای می‌گیرد — الگوهای پرامپت شما را از طریق واحدهای ساختاری SystemMessage و UserMessage به مدل متصل می‌کند. +نمودار زیر نشان می‌دهد چگونه LangChain4j در این تصویر قرار می‌گیرد — الگوهای پرامپت شما را از طریق بلوک‌های ساختاری SystemMessage و UserMessage به مدل متصل می‌کند. -چگونگی جایگیری LangChain4j +چگونه LangChain4j قرار می‌گیرد -LangChain4j زیرساخت‌ها را فراهم می‌کند — اتصال به مدل‌ها، حافظه، و انواع پیام‌ها — در حالی که الگوهای پرامپت صرفاً متن‌های ساختارمندی هستند که از طریق این زیرساخت ارسال می‌شوند. واحد‌های سازنده کلیدی `SystemMessage` (که رفتار و نقش AI را مشخص می‌کند) و `UserMessage` (که درخواست واقعی شما را حمل می‌کند) هستند. +LangChain4j زیرساخت‌ها را فراهم می‌کند — ارتباطات مدل، حافظه، و انواع پیام — در حالی که الگوهای پرامپت فقط متون ساختاربندی شده‌ای هستند که از طریق این زیرساخت ارسال می‌کنید. بلوک‌های کلیدی `SystemMessage` (که رفتار و نقش AI را تعیین می‌کند) و `UserMessage` (که درخواست واقعی شما را حمل می‌کند) هستند. -## مبانی مهندسی پرامپت +## اصول مهندسی پرامپت -پنج تکنیک اصلی زیر پایه‌های مهندسی پرامپت مؤثر را تشکیل می‌دهند. هر یک جنبه‌ای متفاوت از چگونگی ارتباط شما با مدل‌های زبانی را پوشش می‌دهند. +پنج تکنیک اصلی زیر اساس مهندسی پرامپت موثر را تشکیل می‌دهند. هر کدام جنبه متفاوتی از نحوه ارتباط شما با مدل‌های زبانی را پوشش می‌دهند. -مرور پنج الگوی مهندسی پرامپت +نمای کلی پنج الگوی مهندسی پرامپت -قبل از پرداختن به الگوهای پیشرفته در این ماژول، بیایید پنج تکنیک بنیادی پرامپت را مرور کنیم. این‌ها بلوک‌های ساختاری هستند که هر مهندس پرامپت باید بشناسد. اگر قبلاً ماژول [شروع سریع](../00-quick-start/README.md#2-prompt-patterns) را کار کرده‌اید، این‌ها را در عمل دیده‌اید — در اینجا چارچوب مفهومی پشت آن‌ها آورده شده است. +قبل از پرداختن به الگوهای پیشرفته در این ماژول، بیایید پنج تکنیک بنیادی پرامپت را مرور کنیم. اینها بلوک‌های ساختمانی هستند که هر مهندس پرامپت باید بداند. -### پرامپت بدون نمونه (Zero-Shot Prompting) +### پرامپت صفر-شات -ساده‌ترین روش: به مدل دستوری مستقیم بدون هیچ مثالی بدهید. مدل به طور کامل بر آموزش خود تکیه می‌کند تا وظیفه را بفهمد و اجرا کند. این برای درخواست‌های ساده که رفتار مورد انتظار واضح است، خوب کار می‌کند. +ساده‌ترین رویکرد: به مدل یک دستور مستقیم بدون هیچ مثالی بدهید. مدل کاملاً بر اساس آموزش خود متکی است تا کار را بفهمد و اجرا کند. این برای درخواست‌های ساده که رفتار مورد انتظار واضح است به خوبی کار می‌کند. -پرامپت بدون نمونه +پرامپت صفر-شات -*دستور مستقیم بدون نمونه — مدل تنها از دستور، وظیفه را استنتاج می‌کند* +*دستور مستقیم بدون مثال — مدل فقط از روی دستور کار را استنباط می‌کند* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// پاسخ: «مثبت» +// پاسخ: "مثبت" ``` + +**زمان استفاده:** دسته‌بندی‌های ساده، سوالات مستقیم، ترجمه‌ها، یا هر کار که مدل می‌تواند بدون راهنمایی اضافی انجام دهد. -**زمان استفاده:** طبقه‌بندی‌های ساده، سوالات مستقیم، ترجمه‌ها یا هر وظیفه‌ای که مدل بدون راهنمایی بیشتر می‌تواند انجام دهد. +### پرامپت چند-شات -### پرامپت با نمونه‌های محدود (Few-Shot Prompting) +مثال‌هایی ارائه دهید که الگوی مورد نظر را به مدل نشان می‌دهد. مدل فرمت ورودی-خروجی مورد انتظار را از نمونه‌ها یاد می‌گیرد و آن را به ورودی‌های جدید اعمال می‌کند. این به طور قابل توجهی انسجام را برای کارهایی که فرمت یا رفتار دلخواه واضح نیست، افزایش می‌دهد. -نمونه‌هایی ارائه دهید که الگویی که می‌خواهید مدل دنبال کند را نشان می‌دهد. مدل قالب ورودی-خروجی مورد انتظار را از نمونه‌های شما یاد می‌گیرد و آن را روی ورودی‌های جدید اعمال می‌کند. این باعث افزایش ثبات در وظایفی می‌شود که قالب یا رفتار مطلوب واضح نیست. +پرامپت چند-شات -پرامپت با نمونه محدود - -*یادگیری از نمونه‌ها — مدل الگو را تشخیص داده و روی ورودی‌های جدید اعمال می‌کند* +*یادگیری از مثال‌ها — مدل الگو را شناسایی کرده و برای ورودی‌های جدید اعمال می‌کند* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` + +**زمان استفاده:** دسته‌بندی‌های سفارشی، قالب‌بندی سازگار، کارهای حوزه خاص، یا زمانی که نتایج صفر-شات ناپایدار است. -**زمان استفاده:** طبقه‌بندی‌های سفارشی، قالب‌دهی یکنواخت، وظایف حوزه‌-محور یا هنگامی که نتایج zero-shot ناپایدار هستند. - -### زنجیره فکری (Chain of Thought) +### زنجیره تفکر -از مدل بخواهید که استدلال خود را گام‌به‌گام نشان دهد. به جای پریدن مستقیم به پاسخ، مدل مسئله را تفکیک کرده و هر بخش را به صورت صریح بررسی می‌کند. این دقت در مسائل ریاضی، منطق، و استدلال چندمرحله‌ای را ارتقا می‌دهد. +از مدل بخواهید استدلال خود را قدم به قدم نشان دهد. به جای رفتن مستقیم به پاسخ، مدل مسئله را تقسیم کرده و هر قسمت را به صورت صریح پیش می‌برد. این دقت را در مسائل ریاضی، منطق و استدلال چند مرحله‌ای بهبود می‌بخشد. -پرامپت با زنجیره فکری +پرامپت زنجیره تفکر -*استدلال گام‌به‌گام — تقسیم مسائل پیچیده به مراحل منطقی صریح* +*استدلال مرحله به مرحله — تقسیم مسائل پیچیده به گام‌های منطقی صریح* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// مدل نشان می‌دهد: ۷ = ۸ - ۱۵، سپس ۱۹ = ۱۲ + ۷ سیب‌ها +// مدل نشان می‌دهد: ۱۵ - ۸ = ۷، سپس ۷ + ۱۲ = ۱۹ سیب ``` + +**زمان استفاده:** مسائل ریاضی، معماهای منطقی، رفع اشکال، یا هر کاری که نشان دادن فرآیند استدلال دقت و اعتماد را بالا می‌برد. -**زمان استفاده:** مسائل ریاضی، معماهای منطقی، اشکال‌زدایی، یا هر وظیفه‌ای که نشان دادن روند استدلال دقت و اعتماد را بهبود می‌بخشد. +### پرامپت بر اساس نقش -### پرامپت مبتنی بر نقش +قبل از پرسیدن سوال، شخصیتی یا نقشی برای AI تعیین کنید. این زمینه‌ای فراهم می‌کند که لحن، عمق، و تمرکز پاسخ را شکل می‌دهد. یک "معمار نرم‌افزار" مشاوره متفاوتی نسبت به "توسعه‌دهنده مبتدی" یا "ممیزی امنیتی" می‌دهد. -قبل از پرسیدن سوال، شخصیتی یا نقشی برای AI تعریف کنید. این زمینه‌ای فراهم می‌کند که لحن، عمق، و تمرکز پاسخ را شکل می‌دهد. «معمار نرم‌افزار» مشاوره متفاوتی نسبت به «توسعه‌دهنده تازه‌کار» یا «بازرس امنیت» می‌دهد. +پرامپت بر اساس نقش -پرامپت مبتنی بر نقش - -*تنظیم زمینه و نقش — همان سوال با توجه به نقش تعیین‌شده پاسخ متفاوت می‌گیرد* +*تعیین زمینه و شخصیت — همان سوال پاسخ متفاوتی بسته به نقش تعیین شده می‌گیرد* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**زمان استفاده:** بررسی کدها، آموزش، تحلیل‌های حوزه‌محور یا زمانی که به پاسخ‌های متناسب با سطح تخصص یا دیدگاه خاص نیاز دارید. + +**زمان استفاده:** بازبینی کد، تدریس، تحلیل حوزه خاص، یا هر زمانی که نیاز به پاسخ‌های متناسب با سطح تخصص یا دیدگاه خاص باشد. ### قالب‌های پرامپت -پرامپت‌های قابل استفاده مجدد با جایگزین‌هایی برای متغیرها بسازید. به جای نوشتن پرامپت جدید هر بار، یک قالب یک‌بار تعریف کنید و مقادیر متفاوت پر کنید. کلاس `PromptTemplate` در LangChain4j این کار را با نحو `{{variable}}` آسان می‌کند. +پرامپت‌های قابل استفاده مجدد با جایگزین‌های متغیر بسازید. به جای نوشتن پرامپت جدید هر بار، یک قالب تعریف کنید و مقادیر مختلف را پر کنید. کلاس `PromptTemplate` در LangChain4j این کار را با نحو `{{variable}}` آسان می‌کند. قالب‌های پرامپت -*پرامپت‌های قابل استفاده مجدد با جایگزین‌های متغیر — یک قالب، چندین کاربرد* +*پرامپت‌های قابل استفاده مجدد با جایگزین‌های متغیر — یک قالب، استفاده‌های متعدد* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**زمان استفاده:** پرسش‌های تکراری با ورودی‌های متفاوت، پردازش دسته‌ای، ساخت جریان‌های کاری AI قابل استفاده مجدد، یا هر موقعیتی که ساختار پرامپت ثابت و داده‌ها متغیر باشند. + +**زمان استفاده:** پرسش‌های تکراری با ورودی‌های مختلف، پردازش دسته‌ای، ساخت جریان‌های کاری AI قابل استفاده مجدد، یا هر موقعیتی که ساختار پرامپت یکسان می‌ماند ولی داده‌ها تغییر می‌کنند. --- -این پنج مبنا ابزار قابل اعتمادی را برای اکثر وظایف پرامپت در اختیار شما می‌گذارند. بقیه این ماژول بر اساس آن‌ها هشت الگوی پیشرفته را ارائه می‌دهد که کنترل استدلال، خودارزیابی، و قابلیت‌های خروجی ساخت‌یافته GPT-5.2 را به کار می‌گیرند. +این پنج اصل یک جعبه ابزار محکم برای اکثر کارهای پرامپت به شما می‌دهد. بقیه این ماژول بر اساس آنها با **هشت الگوی پیشرفته** ساخته شده است که کنترل استدلال، خودارزیابی، و قابلیت‌های خروجی ساختاریافته GPT-5.2 را به کار می‌گیرند. ## الگوهای پیشرفته -پس از پوشش مبانی، به هشت الگوی پیشرفته می‌رسیم که این ماژول را منحصر به فرد می‌کنند. همه مشکلات نیاز به همان روش ندارند. برخی سوالات پاسخ‌های سریع می‌خواهند، برخی دیگر تفکر عمیق. برخی نیاز به نمایش استدلال دارند، برخی فقط به نتایج نیازمندند. هر الگو برای سناریوی متفاوتی بهینه شده — و کنترل استدلال GPT-5.2 تفاوت‌ها را برجسته‌تر می‌کند. +پس از پوشش اصول، بیایید به هشت الگوی پیشرفته بپردازیم که این ماژول را منحصر به فرد می‌کند. همه مسائل به یک روش نیاز ندارند. برخی سوالات نیاز به پاسخ سریع دارند، برخی به تفکر عمیق. بعضی به استدلال قابل مشاهده نیاز دارند، برخی فقط نتایج. هر الگو به سناریویی متفاوت بهینه شده است — و کنترل استدلال GPT-5.2 این تفاوت‌ها را بیش از پیش نمایان می‌کند. -هشت الگوی مهندسی پرامپت +هشت الگوی پرامپت -*مروری بر هشت الگوی مهندسی پرامپت و کاربردهای آن‌ها* +*نمای کلی هشت الگوی مهندسی پرامپت و موارد استفاده آنها* -GPT-5.2 بعد جدیدی به این الگوها اضافه می‌کند: *کنترل استدلال*. اسلایدر زیر نشان می‌دهد چطور می‌توانید میزان تلاش فکری مدل را تنظیم کنید — از پاسخ‌های سریع و مستقیم تا تحلیل عمیق و کامل. +GPT-5.2 بعد دیگری به این الگوها اضافه می‌کند: *کنترل استدلال*. لغزنده زیر نشان می‌دهد چگونه می‌توانید میزان تفکر مدل را تنظیم کنید — از پاسخ‌های سریع و مستقیم تا تحلیل عمیق و دقیق. کنترل استدلال با GPT-5.2 -*کنترل استدلال GPT-5.2 به شما اجازه می‌دهد تعیین کنید مدل چقدر باید فکر کند — از پاسخ‌های سریع و مستقیم تا کاوش عمیق* +*کنترل استدلال GPT-5.2 اجازه می‌دهد مشخص کنید مدل چقدر باید فکر کند — از پاسخ‌های سریع تا کاوش عمیق* -**تمایل کم (سریع و متمرکز)** - برای سوالات ساده که می‌خواهید پاسخ‌های سریع و مستقیم بگیرید. مدل حداقل استدلال می‌کند - حداکثر ۲ مرحله. این را برای محاسبات، جستجوها، یا سوالات ساده استفاده کنید. +**انگیزه کم (سریع و متمرکز)** - برای سوالات ساده که پاسخ‌های سریع و مستقیم می‌خواهید. مدل حداقل استدلال می‌کند - حداکثر ۲ مرحله. این را برای محاسبات، جستجوها، یا سوالات ساده به کار ببرید. ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> 💡 **کشف با GitHub Copilot:** فایل [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) را باز کنید و بپرسید: +> - "تفاوت الگوهای پرامپت انگیزه کم و انگیزه زیاد چیست؟" +> - "چطور تگ‌های XML در پرامپت‌ها به ساختاردهی پاسخ AI کمک می‌کنند؟" +> - "کی باید از الگوهای خودبازتابی استفاده کنم و کی از دستور مستقیم؟" -> 💡 **با GitHub Copilot کاوش کنید:** فایل [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) را باز کنید و بپرسید: -> - "فرق الگوهای تمایل کم و تمایل زیاد در پرامپت چیست؟" -> - "چگونه برچسب‌های XML در پرامپت به ساختار پاسخ AI کمک می‌کنند؟" -> - "چه زمانی باید از الگوهای خودبازتابی استفاده کنم و چه زمانی از دستور مستقیم؟" - -**تمایل زیاد (عمیق و دقیق)** - برای مشکلات پیچیده که نیاز به تحلیل جامع دارید. مدل عمیق کاوش کرده و استدلال دقیق نشان می‌دهد. این را برای طراحی سیستم، تصمیمات معماری، یا تحقیقات پیچیده استفاده کنید. +**انگیزه زیاد (عمیق و دقیق)** - برای مسائل پیچیده که تحلیل جامعی می‌خواهید. مدل به طور کامل کاوش می‌کند و استدلال دقیق نشان می‌دهد. این را برای طراحی سیستم، تصمیمات معماری، یا پژوهش پیچیده استفاده کنید. ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**اجرای کار (پیشرفت گام‌به‌گام)** - برای جریان‌های کاری چندمرحله‌ای. مدل یک برنامه اولیه ارائه می‌دهد، هر گام را هنگام اجرا روایت می‌کند، سپس خلاصه‌ای می‌دهد. این را برای مهاجرت‌ها، پیاده‌سازی‌ها، یا هر فرایند چندمرحله‌ای استفاده کنید. + +**اجرای وظیفه (پیشرفت مرحله به مرحله)** - برای جریان‌های کاری چند مرحله‌ای. مدل برنامه‌ای مقدماتی می‌دهد، هر مرحله را در حین کار روایت می‌کند، سپس خلاصه ارائه می‌دهد. این را برای مهاجرت‌ها، پیاده‌سازی‌ها، یا هر فرایند چند مرحله‌ای استفاده کنید. ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +پرامپت زنجیره تفکر به صراحت از مدل می‌خواهد فرآیند استدلال خود را نشان دهد، که دقت را در کارهای پیچیده افزایش می‌دهد. تقسیم‌بندی مرحله به مرحله به انسان و AI کمک می‌کند منطق را بفهمند. -پرامپت زنجیره فکری از مدل می‌خواهد روند استدلال خود را آشکار کند که دقت را برای وظایف پیچیده افزایش می‌دهد. تقسیم‌بندی گام‌به‌گام باعث می‌شود هم انسان‌ها و هم AI منطق را بهتر درک کنند. - -> **🤖 با چت [GitHub Copilot](https://github.com/features/copilot) امتحان کنید:** درباره این الگو بپرسید: -> - "چگونه الگوی اجرای کار را برای عملیات طولانی‌مدت سازگار کنم؟" -> - "بهترین روش ساختاردهی پیش‌گفتارهای ابزار در برنامه‌های تولیدی چیست؟" -> - "چگونه پیشرفت میانی را در UI ضبط و نمایش دهم؟" +> **🤖 با چت [GitHub Copilot](https://github.com/features/copilot) امتحان کنید:** درباره این الگو سوال کنید: +> - "چگونه الگوی اجرای وظیفه را برای عملیات طولانی‌مدت تطبیق دهم؟" +> - "بهترین روش‌ها برای ساختاردهی مقدمه‌های ابزار در برنامه‌های تولیدی چیست؟" +> - "چطور می‌توانم به‌روزرسانی‌های پیشرفت میانی را در یک رابط کاربری ضبط و نمایش دهم؟" -نمودار زیر جریان کار برنامه‌ریزی → اجرا → خلاصه را نشان می‌دهد. +نمودار زیر این جریان کاری برنامه‌ریزی → اجرا → خلاصه‌سازی را نشان می‌دهد. -الگوی اجرای کار +الگوی اجرای وظیفه -*جریان برنامه‌ریزی → اجرا → خلاصه برای وظایف چندمرحله‌ای* +*جریان کاری برنامه‌ریزی → اجرا → خلاصه‌سازی برای کارهای چند مرحله‌ای* -**کد خودبازتابی** - برای تولید کد با کیفیت تولید. مدل کدی تولید می‌کند که استانداردهای تولید، از جمله مدیریت خطا، را رعایت می‌کند. هنگام ساخت ویژگی‌ها یا سرویس‌های جدید از این استفاده کنید. +**کد خودبازتابی** - برای تولید کد با کیفیت تولید. مدل کدی می‌سازد که استانداردهای تولید را دنبال می‌کند با مدیریت خطای مناسب. این را هنگام ساخت ویژگی‌ها یا سرویس‌های جدید استفاده کنید. ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -نمودار زیر این چرخه بهبود تکراری را نمایش می‌دهد — تولید کد، ارزیابی، شناسایی ضعف‌ها، و اصلاح تا زمانی که کد به استاندارد تولید برسد. + +نمودار زیر این حلقه بهبود تکراری را نشان می‌دهد — تولید، ارزیابی، شناسایی ضعف‌ها، و بازبینی تا کد به استانداردهای تولید برسد. چرخه خودبازتابی -*چرخه بهبود تکراری - تولید، ارزیابی، شناسایی مشکلات، بهبود، تکرار* +*حلقه بهبود تکراری - تولید، ارزیابی، شناسایی مشکلات، بهبود، تکرار* -**تحلیل ساخت‌یافته** - برای ارزیابی یکنواخت. مدل کد را با چارچوبی ثابت بررسی می‌کند (درستی، شیوه‌ها، عملکرد، امنیت، قابلیت نگهداری). این را برای بررسی کد یا ارزیابی کیفیت استفاده کنید. +**تحلیل ساختاریافته** - برای ارزیابی سازگار. مدل کد را با استفاده از چارچوبی ثابت (درستی، شیوه‌ها، عملکرد، امنیت، نگهداری) بررسی می‌کند. این را برای بازبینی کد یا ارزیابی کیفیت استفاده کنید. ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> **🤖 با چت [GitHub Copilot](https://github.com/features/copilot) امتحان کنید:** درباره تحلیل ساختاریافته سوال کنید: +> - "چگونه می‌توانم چارچوب تحلیل را برای انواع مختلف بازبینی کد سفارشی کنم؟" +> - "بهترین روش برای پردازش و اعمال خروجی ساختاریافته به صورت برنامه‌نویسی چیست؟" +> - "چگونه می‌توانم اطمینان حاصل کنم سطوح شدت در جلسات بازبینی مختلف سازگار است؟" -> **🤖 با چت [GitHub Copilot](https://github.com/features/copilot) امتحان کنید:** درباره تحلیل ساخت‌یافته بپرسید: -> - "چگونه چارچوب تحلیل را برای انواع بررسی کد متفاوت سفارشی کنم؟" -> - "بهترین روش برای تجزیه و استفاده از خروجی ساختاریافته به صورت برنامه‌نویسی چیست؟" -> - "چگونه سطوح شدت را در جلسات بررسی مختلف به طور یکنواخت تضمین کنم؟" - -نمودار زیر نشان می‌دهد چگونه این چارچوب ساخت‌یافته یک بررسی کد را به دسته‌های سازگار با سطوح شدت تقسیم می‌کند. +نمودار زیر نشان می‌دهد چگونه این چارچوب ساختاریافته، بازبینی کد را به دسته‌بندی‌های سازگار با سطوح شدت سازماندهی می‌کند. -الگوی تحلیل ساخت‌یافته +الگوی تحلیل ساختاریافته -*چارچوب برای بررسی کد یکنواخت با سطوح شدت* +*چارچوب بازبینی کد سازگار با سطوح شدت* -**چت چندمرحله‌ای** - برای گفتگوهایی که نیاز به زمینه دارند. مدل پیام‌های قبلی را به یاد می‌آورد و بر آن‌ها بنا می‌کند. این را برای جلسات کمک تعاملی یا پرسش و پاسخ‌های پیچیده استفاده کنید. +**چت چند مرحله‌ای** - برای گفتگوهایی که نیاز به محتوا دارند. مدل پیام‌های قبلی را به خاطر می‌سپارد و بر اساس آنها می‌سازد. این را برای جلسات کمک تعاملی یا پرسش و پاسخ پیچیده به کار ببرید. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -نمودار زیر نشان می‌دهد چگونه زمینه گفتگو با هر نوبت جمع می‌شود و چطور با محدودیت توکن مدل مرتبط است. + +نمودار زیر نشان می‌دهد چگونه زمینه مکالمه با هر مرحله جمع می‌شود و چگونه به محدودیت توکن مدل مرتبط است. حافظه زمینه -*چگونه زمینه گفتگو در چند نوبت تجمع می‌یابد تا به حد توکن برسد* -**دلیل‌یابی مرحله‌به‌مرحله** - برای مسائلی که منطق قابل مشاهده نیاز دارند. مدل برای هر مرحله دلیل‌یابی صریح ارائه می‌دهد. از این برای مسائل ریاضی، معماهای منطقی یا زمانی که نیاز به درک فرآیند فکری دارید استفاده کنید. +*چگونه زمینه مکالمه در چندین مرحله تجمع می‌یابد تا به محدودیت توکن برسد* + +**استدلال مرحله به مرحله** - برای مسائلی که نیاز به منطق قابل مشاهده دارند. مدل استدلال صریح برای هر مرحله را نشان می‌دهد. این را برای مسائل ریاضی، معماهای منطقی، یا زمانی که باید فرآیند تفکر را درک کنید استفاده کنید. ```java String prompt = """ @@ -397,14 +398,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +نمودار زیر نشان می‌دهد چگونه مدل مسائل را به گام‌های منطقی شماره‌گذاری شده و صریح تقسیم می‌کند. -نمودار زیر نشان می‌دهد چگونه مدل مسائل را به مراحل منطقی شماره‌گذاری‌شده و صریح تقسیم می‌کند. +الگوی مرحله به مرحله +*شکستن مسائل به گام‌های منطقی صریح* -الگوی مرحله‌به‌مرحله - -*تقسیم مسائل به مراحل منطقی صریح* - -**خروجی محدود شده** - برای پاسخ‌هایی با الزامات قالب‌بندی خاص. مدل به‌دقت قوانین قالب و طول را رعایت می‌کند. از این برای خلاصه‌ها یا زمانی که به ساختار دقیق خروجی نیاز دارید استفاده کنید. +**خروجی محدودشده** - برای پاسخ‌هایی با الزامات قالب‌بندی خاص. مدل دقیقاً از قوانین قالب و طول پیروی می‌کند. این حالت را برای خلاصه‌ها یا وقتی نیاز به ساختار دقیق خروجی دارید، استفاده کنید. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -نمودار زیر نشان می‌دهد چگونه محدودیت‌ها مدل را هدایت می‌کنند تا خروجی مطابق با قالب و الزامات طول ارائه دهد. +نمودار زیر نشان می‌دهد چگونه محدودیت‌ها مدل را هدایت می‌کنند تا خروجی دقیقاً مطابق با الزامات قالب و طول شما تولید کند. -الگوی خروجی محدود شده +الگوی خروجی محدودشده -*اجرای الزامات خاص قالب، طول و ساختار* +*اجرای الزامات قالب، طول و ساختار خاص* ## اجرای برنامه **بررسی استقرار:** -اطمینان حاصل کنید فایل `.env` در شاخه ریشه با اطلاعات اعتبارنامه Azure وجود دارد (ایجاد شده در طول ماژول ۰۱). این را از دایرکتوری ماژول (`02-prompt-engineering/`) اجرا کنید: +اطمینان حاصل کنید فایل `.env` در ریشه پروژه وجود دارد و دارای مجوزهای Azure است (که در ماژول ۰۱ ایجاد شده است). این دستور را از دایرکتوری ماژول (`02-prompt-engineering/`) اجرا کنید: **Bash:** ```bash @@ -442,29 +442,29 @@ cat ../.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نما Get-Content ..\.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نشان دهد ``` -**راه‌اندازی برنامه:** +**شروع برنامه:** -> **توجه:** اگر قبلاً همه برنامه‌ها را با استفاده از `./start-all.sh` از دایرکتوری ریشه (همانطور که در ماژول ۰۱ توضیح داده شده) شروع کرده‌اید، این ماژول قبلاً روی پورت ۸۰۸۳ در حال اجرا است. می‌توانید دستورات شروع زیر را رد کنید و مستقیماً به http://localhost:8083 بروید. +> **توجه:** اگر از قبل همه برنامه‌ها را با دستور `./start-all.sh` از ریشه (مطابق با ماژول ۰۱) اجرا کرده‌اید، این ماژول روی پورت 8083 در حال اجراست. می‌توانید اجرای دستورات شروع زیر را رد کنید و مستقیماً به http://localhost:8083 بروید. -**گزینه ۱: استفاده از Spring Boot Dashboard (توصیه شده برای کاربران VS Code)** +**گزینه ۱: استفاده از Spring Boot Dashboard (مورد پیشنهاد کاربران VS Code)** -کانتینر توسعه شامل افزونه Spring Boot Dashboard است که رابط کاربری بصری برای مدیریت همه برنامه‌های Spring Boot فراهم می‌کند. می‌توانید آن را در نوار فعالیت در سمت چپ VS Code (به دنبال آیکون Spring Boot) پیدا کنید. +کانتینر توسعه شامل افزونه Spring Boot Dashboard است که یک رابط بصری برای مدیریت همه برنامه‌های Spring Boot فراهم می‌کند. این افزونه را در نوار فعالیت در سمت چپ VS Code می‌توانید بیابید (آیکون Spring Boot را جستجو کنید). -از طریق Spring Boot Dashboard می‌توانید: -- همه برنامه‌های Spring Boot موجود در فضای کاری را مشاهده کنید -- برنامه‌ها را با یک کلیک شروع/توقف کنید -- لاگ‌های برنامه را به‌صورت زنده ببینید +از Spring Boot Dashboard می‌توانید: +- تمام برنامه‌های Spring Boot موجود در فضای کاری را ببینید +- برنامه‌ها را فقط با یک کلیک شروع/توقف کنید +- لاگ‌های برنامه را به صورت زنده مشاهده کنید - وضعیت برنامه را مانیتور کنید -فقط روی دکمه پخش کنار "prompt-engineering" کلیک کنید تا این ماژول شروع شود، یا همه ماژول‌ها را یکجا شروع کنید. +فقط روی دکمه پخش کنار «prompt-engineering» کلیک کنید تا این ماژول شروع شود، یا همه ماژول‌ها را هم‌زمان اجرا کنید. -Spring Boot Dashboard +داشبورد Spring Boot -*داشبورد Spring Boot در VS Code — شروع، توقف و مدیریت همه ماژول‌ها از یک محل* +*داشبورد Spring Boot در VS Code — شروع، توقف و نظارت بر همه ماژول‌ها از یک محل* **گزینه ۲: استفاده از اسکریپت‌های شل** -تمام برنامه‌های وب (ماژول‌های ۰۱ تا ۰۴) را شروع کنید: +همه برنامه‌های وب (ماژول‌های ۰۱ تا ۰۴) را شروع کنید: **Bash:** ```bash @@ -474,11 +474,11 @@ cd .. # از دایرکتوری ریشه **PowerShell:** ```powershell -cd .. # از دایرکتوری ریشه +cd .. # از فهرست اصلی .\start-all.ps1 ``` -یا فقط این ماژول را شروع کنید: +یا فقط این ماژول را اجرا کنید: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -هر دو اسکریپت به‌طور خودکار متغیرهای محیطی را از فایل `.env` ریشه بارگذاری می‌کنند و در صورت عدم وجود JAR ها را می‌سازند. +هر دو اسکریپت به صورت خودکار متغیرهای محیطی را از فایل `.env` ریشه بارگذاری می‌کنند و در صورت عدم وجود، فایل‌های JAR را می‌سازند. -> **توجه:** اگر می‌خواهید قبل از شروع همه ماژول‌ها را دستی بسازید: +> **توجه:** اگر ترجیح می‌دهید قبل از شروع، همه ماژول‌ها را به صورت دستی بسازید: > > **Bash:** > ```bash @@ -508,9 +508,9 @@ cd 02-prompt-engineering > mvn clean package -DskipTests > ``` -مرورگر خود را باز کرده و به http://localhost:8083 بروید. +در مرورگر خود http://localhost:8083 را باز کنید. -**برای توقف برنامه:** +**برای توقف:** **Bash:** ```bash @@ -526,83 +526,83 @@ cd .. && ./stop-all.sh # همه ماژول‌ها cd ..; .\stop-all.ps1 # همه ماژول‌ها ``` -## اسکرین‌شات‌های برنامه +## تصاویر برنامه -در اینجا رابط اصلی ماژول prompt engineering است که می‌توانید همزمان با هر هشت الگو آزمایش کنید. +در اینجا رابط اصلی ماژول مهندسی پرامپت نمایش داده شده است، جایی که می‌توانید با همه هشت الگو کنار هم آزمایش کنید. -داشبورد اصلی +صفحه اصلی داشبورد -*داشبورد اصلی که هر ۸ الگوی مهندسی درخواست را با ویژگی‌ها و موارد کاربرد آن‌ها نشان می‌دهد* +*داشبورد اصلی نشان‌دهنده هر ۸ الگوی مهندسی پرامپت به همراه ویژگی‌ها و موارد استفاده‌شان* -## کاوش الگوها +## بررسی الگوها -رابط وب به شما اجازه می‌دهد تا با استراتژی‌های مختلف درخواست آزمایش کنید. هر الگو مسائل متفاوتی را حل می‌کند — آن‌ها را امتحان کنید تا ببینید هر رویکرد چه زمانی اثر می‌کند. +رابط وب به شما اجازه می‌دهد با استراتژی‌های مختلف پرامپت آزمایش کنید. هر الگو مسائل متفاوتی را حل می‌کند - آنها را امتحان کنید و ببینید هر کدام چه زمانی بهترین عملکرد را دارند. -> **توجه: پخش زنده در مقایسه با غیرپخش زنده** — هر صفحه الگو دو دکمه دارد: **🔴 پاسخ زنده (Stream Response)** و گزینه **غیرپخش زنده**. پخش زنده از Server-Sent Events (SSE) برای نمایش لحظه‌ای توکن‌ها همزمان با تولید مدل استفاده می‌کند، بنابراین پیشرفت بلافاصله قابل مشاهده است. گزینه غیرپخش زنده منتظر می‌ماند تا پاسخ کامل تولید شود قبل از نمایش. برای درخواست‌هایی که استدلال عمیق لازم دارند (مثل High Eagerness، Self-Reflecting Code)، تماس غیرپخش زنده ممکن است بسیار طولانی شود — گاهی حتی دقیقه‌ها — بدون بازخورد بصری. **هنگام آزمایش با درخواست‌های پیچیده از پخش زنده استفاده کنید** تا مدل را در حال کار ببینید و از تصور تایم‌اوت درخواست جلوگیری کنید. +> **توجه: پخش زنده در مقابل غیر زنده** — هر صفحه الگو دو دکمه دارد: **🔴 پخش پاسخ (زنده)** و گزینه‌ای برای حالت **غیر زنده**. پخش زنده از رویدادهای ارسالی سرور (SSE) برای نمایش توکن‌ها به صورت زنده استفاده می‌کند، بنابراین شما پیشرفت را بلافاصله می‌بینید. حالت غیرزنده کل پاسخ را منتظر می‌ماند تا نمایش دهد. برای پرامپت‌هایی که به استدلال عمیق نیاز دارند (مثلاً High Eagerness، Self-Reflecting Code) تماس غیرزنده ممکن است بسیار طول بکشد — گاهی دقیقه‌ها — بدون اینکه بازخوردی ظاهر شود. **هنگام آزمایش پرامپت‌های پیچیده از پخش زنده استفاده کنید** تا مدل را در حال کار ببینید و از فرض اتمام زمان درخواست جلوگیری کنید. > -> **توجه: نیازمندی مرورگر** — ویژگی پخش زنده از Fetch Streams API (`response.body.getReader()`) استفاده می‌کند که نیاز به مرورگر کامل (Chrome, Edge, Firefox, Safari) دارد. این در Simple Browser داخلی VS Code کار نمی‌کند زیرا وب‌ویو آن از ReadableStream API پشتیبانی نمی‌کند. اگر از Simple Browser استفاده کنید، دکمه‌های غیرپخش زنده به‌طور معمول کار می‌کنند — فقط دکمه‌های پخش زنده تحت تاثیر هستند. برای تجربه کامل `http://localhost:8083` را در مرورگر خارجی باز کنید. +> **توجه: نیاز مرورگر** — قابلیت پخش زنده از Fetch Streams API (`response.body.getReader()`) استفاده می‌کند که به مرورگر کامل (Chrome, Edge, Firefox, Safari) نیاز دارد. این قابلیت در Simple Browser تعبیه شده در VS Code کار نمی‌کند، زیرا وب‌ویو آن API ReadableStream را پشتیبانی نمی‌کند. اگر از Simple Browser استفاده می‌کنید، دکمه‌های غیرزنده به طور عادی کار می‌کنند — فقط دکمه‌های پخش زنده تحت‌تأثیر هستند. برای تجربه کامل، `http://localhost:8083` را در یک مرورگر خارجی باز کنید. -### Eagerness کم در مقابل زیاد +### اشتیاق کم در مقابل اشتیاق زیاد -یک سوال ساده مثل "۱۵٪ از ۲۰۰ چقدر است؟" با Eagerness کم بپرسید. پاسخ فوری و مستقیم دریافت می‌کنید. حالا یک سوال پیچیده مانند "طراحی استراتژی کشینگ برای یک API پرترافیک" با Eagerness زیاد بپرسید. روی **🔴 پاسخ زنده (Stream Response)** کلیک کنید و مشاهدۀ دلیل‌یابی دقیق مدل را توکن‌به‌توکن ببینید. مدل همان است، ساختار سوال همان است — اما درخواست نشان می‌دهد چقدر باید فکر کند. +سؤال ساده‌ای مثل «۱۵٪ از ۲۰۰ چقدر است؟» را با اشتیاق کم بپرسید. پاسخ سریع و مستقیم دریافت می‌کنید. اکنون یک سؤال پیچیده مثل «یک استراتژی کشینگ برای یک API پر ترافیک طراحی کن» را با اشتیاق زیاد بپرسید. روی **🔴 پخش پاسخ (زنده)** کلیک کنید و شاهد استدلال دقیق مدل به صورت توکن به توکن خواهید بود. مدل یکسان، ساختار سؤال یکسان — اما پرامپت مشخص می‌کند چقدر فکر کند. -### اجرای وظایف (پیش‌گفتار ابزار) +### اجرای کار (پیش‌نویس ابزارها) -گردش‌های کار چندمرحله‌ای از برنامه‌ریزی اولیه و روایت پیشرفت بهره می‌برند. مدل توضیح می‌دهد چه می‌کند، هر مرحله را روایت می‌کند و سپس نتایج را خلاصه می‌کند. +فرآیندهای چندمرحله‌ای از برنامه‌ریزی مقدماتی و روایت پیشرفت بهره می‌برند. مدل توضیح می‌دهد چه کاری خواهد کرد، هر گام را شرح می‌دهد و سپس نتایج را خلاصه می‌کند. ### کد خودبازتابی -مثلاً "ایجاد سرویس اعتبارسنجی ایمیل" را امتحان کنید. به جای فقط تولید کد و توقف، مدل کد را تولید، بر اساس معیارهای کیفیت ارزیابی، نقاط ضعف را شناسایی و بهبود می‌دهد. می‌بینید که تا رسیدن به استانداردهای تولید چندین بار تکرار می‌کند. +«یک سرویس اعتبارسنجی ایمیل بساز» را امتحان کنید. مدل فقط به تولید کد اکتفا نمی‌کند بلکه آن را ارزیابی می‌کند، نقاط ضعف را شناسایی و بهبود می‌بخشد. می‌بینید که تا رسیدن کد به سطح کیفیت تولید تکرار می‌شود. ### تحلیل ساختاریافته -بازبینی کد به چارچوب‌های ارزیابی ثابت نیاز دارد. مدل کد را با استفاده از دسته‌بندی‌های ثابت (درستی، روش‌ها، عملکرد، امنیت) با سطوح شدت تحلیل می‌کند. +نقد کد نیاز به چارچوب‌های ارزیابی ثابت دارد. مدل کد را با دسته‌بندی‌های مشخص (درستی، شیوه‌ها، عملکرد، امنیت) و با درج سطوح شدت تحلیل می‌کند. ### چت چندمرحله‌ای -سوال "Spring Boot چیست؟" را بپرسید، سپس بلافاصله ادامه دهید با "یک مثال نشان بده". مدل سوال اول شما را به خاطر می‌سپارد و یک مثال Spring Boot خاص ارائه می‌دهد. بدون حافظه، سوال دوم خیلی مبهم بود. +سؤال «Spring Boot چیست؟» را بپرسید و بلافاصله دنبال آن «مثالی نشان بده» را بپرسید. مدل سؤال اول را به خاطر می‌سپارد و مثال مربوط به Spring Boot را می‌دهد. بدون حافظه، سؤال دوم بسیار مبهم بود. -### دلیل‌یابی مرحله‌به‌مرحله +### استدلال گام‌به‌گام -یک مسئله ریاضی انتخاب کنید و آن را هم با دلیل‌یابی مرحله به مرحله و هم با Eagerness کم امتحان کنید. Eagerness کم فقط پاسخ را می‌دهد — سریع اما مبهم. حالت مرحله به مرحله هر محاسبه و تصمیم را نشان می‌دهد. +یک مسئله ریاضی انتخاب کنید و آن را با استدلال گام‌به‌گام و اشتیاق کم امتحان کنید. اشتیاق کم فقط پاسخ را سریع می‌دهد — سریع اما مبهم؛ استدلال گام‌به‌گام هر محاسبه و تصمیم را نشان می‌دهد. -### خروجی محدود شده +### خروجی محدودشده -وقتی به فرمت خاص یا تعداد دقیق کلمات نیاز دارید، این الگو پیروی دقیق را تضمین می‌کند. مثلا تولید خلاصه‌ای با دقیقاً ۱۰۰ کلمه در قالب فهرست‌وار. +وقتی به فرمت یا تعداد کلمات خاص نیاز دارید، این الگو رعایت دقیق آن را اجباری می‌کند. مثلاً تولید خلاصه‌ای دقیقاً با ۱۰۰ کلمه به صورت نقطه‌گذاری شده. -## چیزی که واقعاً یاد می‌گیرید +## آنچه واقعاً یاد می‌گیرید **تلاش استدلال همه چیز را تغییر می‌دهد** -GPT-5.2 به شما امکان کنترل تلاش محاسباتی را از طریق درخواست‌های خود می‌دهد. تلاش کم به پاسخ‌های سریع با حداقل بررسی منجر می‌شود. تلاش زیاد یعنی مدل زمان می‌گذارد تا عمیق فکر کند. شما یاد می‌گیرید میزان تلاش را متناسب با پیچیدگی وظیفه تطبیق دهید — زمان خود را برای سوالات ساده تلف نکنید، اما تصمیم‌های پیچیده را نیز شتابزده نگیرید. +GPT-5.2 به شما اجازه می‌دهد از طریق پرامپت‌ها کنترل تلاش محاسباتی را به دست بگیرید. تلاش کم یعنی پاسخ‌های سریع با حداقل بررسی. تلاش زیاد یعنی مدل زمان صرف تفکر عمیق می‌کند. شما یاد می‌گیرید تلاش را با پیچیدگی کارها تطبیق دهید — برای پرسش‌های ساده وقت تلف نکنید اما در تصمیمات پیچیده عجله نکنید. **ساختار رفتار را هدایت می‌کند** -توجه کنید به تگ‌های XML در درخواست‌ها؟ آن‌ها فقط تزئینی نیستند. مدل‌ها دستورالعمل‌های ساختاریافته را پایدارتر از متن آزاد دنبال می‌کنند. وقتی به فرآیندهای چندمرحله‌ای یا منطق پیچیده نیاز دارید، ساختار به مدل کمک می‌کند جایگاه خود را پیگیری کند و بداند مرحله بعدی چیست. نمودار زیر یک درخواست ساختاریافته را باز می‌کند و نشان می‌دهد چگونه تگ‌هایی مانند ``, ``, ``, ``, و `` دستورالعمل‌ها را به بخش‌های واضح تقسیم می‌کنند. +متوجه تگ‌های XML در پرامپت‌ها شده‌اید؟ این‌ها تزئینی نیستند. مدل‌ها دستورالعمل‌های ساختاریافته را بهتر از متن آزاد دنبال می‌کنند. وقتی به فرآیندهای چندمرحله‌ای یا منطق پیچیده نیاز دارید، ساختار کمک می‌کند مدل بداند کجاست و بعد چه باید بکند. نمودار زیر یک پرامپت خوب ساختار یافته را نشان می‌دهد که چگونه تگ‌هایی مانند ``, ``, ``, ``, و `` دستورالعمل‌ها را به بخش‌های واضح تقسیم می‌کند. -ساختار درخواست +ساختار پرامپت -*آناتومی یک درخواست خوب ساختار یافته با بخش‌های واضح و سازمان‌دهی به سبک XML* +*آناتومی یک پرامپت ساختارمند با بخش‌های واضح و سازماندهی به سبک XML* **کیفیت از طریق خودارزیابی** -الگوهای خودبازتابی با بیان صریح معیارهای کیفیت کار می‌کنند. به جای امید به درست انجام دادن مدل، به آن دقیقاً می‌گویید “درست” یعنی چه: منطق صحیح، مدیریت خطا، عملکرد، امنیت. سپس مدل می‌تواند خروجی خود را ارزیابی و بهبود دهد. این تولید کد را از شانس به یک فرایند تبدیل می‌کند. +الگوهای خودبازتابی با صراحت معیارهای کیفیت را بیان می‌کنند. به جای اینکه امیدوار باشید مدل «درست انجام دهد»، به آن دقیقاً می‌گویید «درست» یعنی چه: منطق صحیح، مدیریت خطا، عملکرد، امنیت. مدل سپس می‌تواند خروجی خود را ارزیابی و بهبود دهد. این باعث می‌شود تولید کد به جای قرعه‌کشی، به یک فرآیند تبدیل شود. -**زمینه محدود است** +**متن محدود است** -گفتگوهای چندمرحله‌ای با افزودن تاریخچه پیام‌ها به هر درخواست کار می‌کنند. اما محدودیت وجود دارد — هر مدل حداکثر تعداد توکن دارد. با رشد گفتگوها، شما به استراتژی‌هایی نیاز دارید که زمینه مرتبط را نگه دارند بدون اینکه به آن سقف برسند. این ماژول به شما نشان می‌دهد حافظه چگونه کار می‌کند؛ بعداً خواهید آموخت چه زمانی خلاصه کنید، چه زمانی فراموش کنید و چه زمانی بازیابی کنید. +گفتگوهای چندمرحله‌ای با قرار دادن تاریخچه پیام‌ها در هر درخواست کار می‌کنند. اما یک حدی دارد — هر مدل تعداد توکن‌های محدودی دارد. با رشد مکالمه، باید راهکارهایی برای حفظ زمینه مرتبط بدون عبور از حد پیدا کنید. این ماژول نحوه کار حافظه را نشان می‌دهد؛ بعداً خواهید آموخت کی خلاصه کنید، کی فراموش کنید و کی بازیابی کنید. -## گام‌های بعدی +## مراحل بعدی -**ماژول بعدی:** [03-rag - RAG (تولید افزوده شده بازیابی)](../03-rag/README.md) +**ماژول بعدی:** [03-rag - تولید تکمیلی به کمک جستجو (RAG)](../03-rag/README.md) --- -**ناوبری:** [← قبلی: ماژول ۰۱ - مقدمه](../01-introduction/README.md) | [بازگشت به اصلی](../README.md) | [بعدی: ماژول ۰۳ - RAG →](../03-rag/README.md) +**ناوبری:** [← قبلی: ماژول ۰۱ - معرفی](../01-introduction/README.md) | [بازگشت به اصلی](../README.md) | [بعدی: ماژول ۰۳ - RAG →](../03-rag/README.md) --- **سلب مسئولیت**: -این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است حاوی اشکالات یا نادرستی‌هایی باشند. سند اصلی به زبان بومی خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، توصیه می‌شود از ترجمه حرفه‌ای انسانی استفاده شود. ما در قبال هرگونه سوءتفاهم یا برداشت غلط ناشی از استفاده از این ترجمه مسئولیتی نمی‌پذیریم. +این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم. \ No newline at end of file diff --git a/translations/fa/03-rag/README.md b/translations/fa/03-rag/README.md index ce26a6e0b..23c0e813c 100644 --- a/translations/fa/03-rag/README.md +++ b/translations/fa/03-rag/README.md @@ -1,110 +1,109 @@ -# ماژول ۰۳: RAG (تولید افزوده‌شده با بازیابی) +# ماژول ۰۳: RAG (تولید تقویت‌شده با بازیابی) ## فهرست مطالب -- [نمایش ویدئویی](../../../03-rag) -- [آنچه خواهید آموخت](../../../03-rag) -- [پیش‌نیازها](../../../03-rag) -- [درک RAG](../../../03-rag) - - [کدام رویکرد RAG در این آموزش استفاده می‌شود؟](../../../03-rag) -- [نحوه کار](../../../03-rag) - - [پردازش اسناد](../../../03-rag) - - [ایجاد جاسازی‌ها](../../../03-rag) - - [جستجوی معنایی](../../../03-rag) - - [تولید پاسخ](../../../03-rag) -- [اجرای برنامه](../../../03-rag) -- [استفاده از برنامه](../../../03-rag) - - [بارگذاری یک سند](../../../03-rag) - - [پرسیدن سوالات](../../../03-rag) - - [بررسی مراجع منبع](../../../03-rag) - - [آزمایش با سوالات](../../../03-rag) -- [مفاهیم کلیدی](../../../03-rag) - - [استراتژی قطعه‌بندی](../../../03-rag) - - [امتیازهای شباهت](../../../03-rag) - - [ذخیره‌سازی در حافظه](../../../03-rag) - - [مدیریت پنجره زمینه](../../../03-rag) -- [زمانی که RAG اهمیت دارد](../../../03-rag) -- [گام‌های بعدی](../../../03-rag) - -## نمایش ویدئویی - -این جلسه زنده را تماشا کنید که توضیح می‌دهد چگونه با این ماژول شروع کنید: +- [تماشای ویدیو](#تماشای-ویدیو) +- [آنچه یاد خواهید گرفت](#آنچه-یاد-خواهید-گرفت) +- [پیش‌نیازها](#پیش‌نیازها) +- [درک RAG](#درک-rag) + - [کدام رویکرد RAG در این آموزش استفاده می‌شود؟](#کدام-رویکرد-rag-در-این-آموزش-استفاده-می‌شود؟) +- [نحوه کارکرد](#نحوه-کارکرد) + - [پردازش سند](#پردازش-سند) + - [ایجاد تعبیه‌ها](#ایجاد-تعبیه‌ها) + - [جستجوی معنایی](#جستجوی-معنایی) + - [تولید پاسخ](#تولید-پاسخ) +- [اجرای برنامه](#اجرای-برنامه) +- [استفاده از برنامه](#استفاده-از-برنامه) + - [بارگذاری سند](#بارگذاری-سند) + - [پرسیدن سوال](#پرسیدن-سوالات) + - [بررسی منابع](#بررسی-مراجع-منبع) + - [آزمایش با سوالات](#آزمایش-با-سوالات-مختلف) +- [مفاهیم کلیدی](#مفاهیم-کلیدی) + - [استراتژی تکه‌بندی](#استراتژی-تقسیم-بخش‌ها) + - [امتیازهای شباهت](#امتیازهای-شباهت) + - [ذخیره‌سازی در حافظه](#ذخیره‌سازی-در-حافظه) + - [مدیریت پنجره متن](#مدیریت-پنجره-زمینه) +- [زمان اهمیت RAG](#کی-rag-اهمیت-دارد) +- [گام‌های بعدی](#مراحل-بعدی) + +## تماشای ویدیو + +این جلسه زنده را ببینید که توضیح می‌دهد چگونه با این ماژول شروع به کار کنید: RAG with LangChain4j - Live Session -## آنچه خواهید آموخت +## آنچه یاد خواهید گرفت -در ماژول‌های قبلی، یاد گرفته‌اید چگونه با هوش مصنوعی گفتگو کنید و ساختار درخواست‌های خود را به‌طور مؤثر تنظیم کنید. اما یک محدودیت اساسی وجود دارد: مدل‌های زبانی فقط آنچه در طی آموزش یاد گرفته‌اند را می‌دانند. آن‌ها نمی‌توانند به سوالات مربوط به سیاست‌های شرکت شما، مستندات پروژه‌تان یا هر اطلاعاتی که آموزش ندیده‌اند پاسخ دهند. +در ماژول‌های قبلی یاد گرفتید چگونه با هوش مصنوعی گفتگو کنید و پرامپت‌های خود را به‌طور مؤثر ساختاربندی کنید. اما یک محدودیت بنیادی وجود دارد: مدل‌های زبانی فقط آنچه را در حین آموزش یاد گرفته‌اند می‌دانند. آن‌ها نمی‌توانند به سوالاتی درباره سیاست‌های شرکت شما، مستندات پروژه‌تان، یا هر اطلاعاتی که روی آن آموزش ندیده‌اند پاسخ دهند. -RAG (تولید افزوده‌شده با بازیابی) این مشکل را حل می‌کند. به جای تلاش برای آموزش اطلاعات شما به مدل (که پرهزینه و غیرعملی است)، به مدل توانایی جستجو در اسناد شما داده می‌شود. وقتی کسی سوالی می‌پرسد، سیستم اطلاعات مرتبط را پیدا کرده و در درخواست وارد می‌کند. مدل سپس بر اساس آن زمینه بازیابی شده پاسخ می‌دهد. +RAG (تولید تقویت‌شده با بازیابی) این مشکل را حل می‌کند. به جای اینکه بخواهید مدل را با اطلاعات خود آموزش دهید (که هزینه‌بر و غیرعملی است)، به آن توانایی جستجو در اسناد خود را می‌دهید. وقتی کسی سوالی می‌پرسد، سیستم اطلاعات مرتبط را پیدا کرده و در پرامپت وارد می‌کند. سپس مدل بر اساس آن زمینه بازیابی‌شده پاسخ می‌دهد. -به RAG مانند ایجاد یک کتابخانه مرجع برای مدل فکر کنید. وقتی سوالی می‌پرسید، سیستم: +RAG را مانند دادن یک کتابخانه مرجع به مدل در نظر بگیرید. وقتی سوال می‌پرسید، سیستم: -1. **سوال کاربر** - شما سوالی می‌پرسید -2. **جاسازی** - سوال شما را به بردار تبدیل می‌کند -3. **جستجوی برداری** - قطعات اسناد مشابه را پیدا می‌کند -4. **ترکیب زمینه** - قطعات مرتبط را به درخواست اضافه می‌کند -5. **پاسخ** - مدل زبانی پاسخ را بر اساس زمینه تولید می‌کند +1. **پرسش کاربر** - شما سوال می‌پرسید +2. **تعبیه‌سازی** - سوال شما به بردار تبدیل می‌شود +3. **جستجوی برداری** - بخش‌های مشابه سند پیدا می‌شوند +4. **گردآوری متن زمینه** - بخش‌های مرتبط به پرامپت اضافه می‌شود +5. **پاسخ** - مدل زبانی بزرگ پاسخ را بر اساس متن زمینه ایجاد می‌کند -این کار پاسخ‌های مدل را مبتنی بر داده‌های واقعی شما می‌کند به جای تکیه بر دانش آموزش دیده یا تخیل پاسخ‌ها. +این باعث می‌شود پاسخ‌های مدل بر اساس داده‌های واقعی شما باشد، نه فقط دانسته‌های آموزشی یا حدس‌های غیرواقعی. ## پیش‌نیازها -- اتمام [ماژول ۰۰ - شروع سریع](../00-quick-start/README.md) (برای مثال Easy RAG که بعداً در این ماژول به آن اشاره شده است) -- اتمام [ماژول ۰۱ - مقدمه](../01-introduction/README.md) (منابع Azure OpenAI مستقر شده، شامل مدل جاسازی `text-embedding-3-small`) -- فایل `.env` در دایرکتوری ریشه با اعتبارنامه‌های Azure (ایجاد شده توسط فرمان `azd up` در ماژول ۰۱) +- اتمام [ماژول ۰۱ - معرفی](../01-introduction/README.md) (استقرار منابع Azure OpenAI، شامل مدل تعبیه‌سازی `text-embedding-3-small`) +- فایل `.env` در شاخه اصلی با اطلاعات Azure (ایجاد شده توسط دستور `azd up` در ماژول ۰۱) -> **توجه:** اگر ماژول ۰۱ را کامل نکرده‌اید، ابتدا دستورالعمل‌های استقرار آن را دنبال کنید. فرمان `azd up` مدل گپ GPT و مدل جاسازی استفاده‌شده در این ماژول را مستقر می‌کند. +> **توجه:** اگر ماژول ۰۱ را کامل نکرده‌اید، ابتدا دستورالعمل‌های استقرار آن را دنبال کنید. دستور `azd up` هر دو مدل گفتگو GPT و مدل تعبیه‌سازی مورد استفاده این ماژول را مستقر می‌کند. ## درک RAG -شکل زیر مفهوم اصلی را نشان می‌دهد: به جای تکیه صرف بر داده‌های آموزشی مدل، RAG یک کتابخانه مرجع از اسناد شما به آن می‌دهد تا قبل از تولید هر پاسخ، مشورت کند. +نمودار زیر مفهوم اصلی را نشان می‌دهد: به جای تکیه صرف بر داده‌های آموزشی مدل، RAG به آن یک کتابخانه مرجع از اسناد شما می‌دهد تا قبل از ایجاد هر پاسخ، به آن مراجعه کند. What is RAG -*این نمودار تفاوت بین مدل زبانی استاندارد (که از داده‌های آموزشی حدس می‌زند) و مدل زبانی تقویت‌شده با RAG (که ابتدا اسناد شما را مرور می‌کند) را نشان می‌دهد.* +*این نمودار تفاوت بین یک مدل زبانی استاندارد (که از داده‌های آموزشی حدس می‌زند) و یک مدل زبانی تقویت‌شده RAG (که ابتدا به اسناد شما مراجعه می‌کند) را نشان می‌دهد.* -در اینجا نحوه اتصال اجزا به صورت انتها به انتها آورده شده است. سوال کاربر از چهار مرحله عبور می‌کند — جاسازی، جستجوی برداری، ترکیب زمینه، و تولید پاسخ — که هر کدام بر مرحله قبلی بنا شده‌اند: +اتصالات قطعات سیستم از ابتدا تا انتها به این صورت است. سوال کاربر از چهار مرحله می‌گذرد — تعبیه‌سازی، جستجوی برداری، جمع‌آوری متن زمینه، و تولید پاسخ — که هر مرحله بر مرحله قبل بنا شده است: RAG Architecture -*این نمودار خط لوله RAG انتها به انتها را نشان می‌دهد — سوال کاربر از جاسازی، جستجوی برداری، ترکیب زمینه و تولید پاسخ عبور می‌کند.* +*این نمودار خط لوله انتها به انتهای RAG را نشان می‌دهد — پرسش کاربر از مراحل تعبیه‌سازی، جستجوی برداری، جمع‌آوری متن زمینه و تولید پاسخ عبور می‌کند.* -بقیه این ماژول هر مرحله را با جزئیات طی می‌کند، همراه با کدهایی که می‌توانید اجرا و تغییر دهید. +باقی ماژول هر مرحله را با جزئیات، همراه با کد قابل اجرا و قابل تغییر، بررسی می‌کند. ### کدام رویکرد RAG در این آموزش استفاده می‌شود؟ -LangChain4j سه راه برای پیاده‌سازی RAG ارائه می‌دهد، هر کدام با سطح انتزاعی متفاوت. نمودار زیر آن‌ها را کنار هم مقایسه می‌کند: +LangChain4j سه روش برای پیاده‌سازی RAG ارائه می‌دهد، هرکدام با سطح انتزاع متفاوت. نمودار زیر آن‌ها را کنار هم مقایسه می‌کند: Three RAG Approaches in LangChain4j -*این نمودار سه رویکرد RAG در LangChain4j — آسان، بومی و پیشرفته — را با اجزای کلیدی آن‌ها و زمان مناسب استفاده نشان می‌دهد.* +*این نمودار سه رویکرد RAG در LangChain4j — آسان، بومی و پیشرفته — را نشان می‌دهد، بخش‌های کلیدی و زمان استفاده از هرکدام را توضیح می‌دهد.* -| رویکرد | کاری که انجام می‌دهد | معایب | +| رویکرد | چه کاری انجام می‌دهد | مصالحه | |---|---|---| -| **Easy RAG** | همه چیز را خودکار با `AiServices` و `ContentRetriever` لینک می‌کند. شما یک اینترفیس حاشیه‌نویسی می‌کنید، یک بازیابی‌کننده اضافه می‌کنید و LangChain4j جاسازی، جستجو و ترکیب زمینه را پشت صحنه مدیریت می‌کند. | حداقل کد، اما نمی‌بینید در هر مرحله چه اتفاقی می‌افتد. | -| **Native RAG** | مدل جاسازی را صدا می‌زنید، در فروشگاه جستجو می‌کنید، درخواست را می‌سازید و پاسخ را خودتان تولید می‌کنید — هر مرحله به صورت صریح و جداگانه. | کد بیشتر، ولی هر مرحله قابل مشاهده و قابل تغییر است. | -| **Advanced RAG** | از چارچوب `RetrievalAugmentor` با تبدیل‌کننده‌های پرس‌وجو، روتورها، رتبه‌بندی مجدد و تزریق‌کننده‌های محتوا برای خط لوله‌های تولید استفاده می‌کند. | حداکثر انعطاف‌پذیری، اما پیچیدگی بسیار بیشتر. | +| **Easy RAG** | همه چیز را به صورت خودکار از طریق `AiServices` و `ContentRetriever` سیم‌کشی می‌کند. شما یک رابط را توضیح می‌دهید، یک بازیاب متصل می‌کنید و LangChain4j تعبیه‌سازی، جستجو و جمع‌آوری پرامپت را پشت صحنه مدیریت می‌کند. | کمترین کد، اما شما دقیقاً نمی‌بینید در هر مرحله چه اتفاقی می‌افتد. | +| **Native RAG** | خودتان مدل تعبیه‌سازی را صدا می‌زنید، فروشگاه را جستجو می‌کنید، پرامپت را می‌سازید و پاسخ را تولید می‌کنید — هر مرحله آشکار و جداگانه. | کد بیشتر، اما هر مرحله قابل مشاهده و تغییر است. | +| **Advanced RAG** | از چارچوب `RetrievalAugmentor` با تبدیل‌کننده‌های پرسش، مسیریاب‌ها، دوباره رتبه‌بند‌ها و تزریق‌کننده‌های محتوا برای خط‌لوله‌های سطح تولید استفاده می‌کند. | حداکثر انعطاف‌پذیری، اما به مراتب پیچیده‌تر. | -**این آموزش رویکرد Native را به کار می‌برد.** هر مرحله از خط لوله RAG — جاسازی پرس‌وجو، جستجوی فروشگاه برداری، ترکیب زمینه و تولید پاسخ — به صورت واضح در [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) نوشته شده است. این کار عمدی است: به عنوان یک منبع یادگیری، مهم‌تر است که هر مرحله را ببینید و بفهمید تا کد کمترین اندازه ممکن باشد. زمانی که با نحوه اتصال اجزا آشنا شدید، می‌توانید به Easy RAG برای نمونه‌سازی سریع یا Advanced RAG برای سیستم‌های تولید منتقل شوید. +**این آموزش رویکرد Native را به کار می‌برد.** هر مرحله از خط لوله RAG — تعبیه‌سازی پرسش، جستجوی فروشگاه بردار، جمع‌آوری متن زمینه، و تولید پاسخ — به‌طور صریح در [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) نوشته شده است. این کار عمدی است: به عنوان منبع آموزشی، مهم‌تر است که شما هر مرحله را ببینید و درک کنید تا اینکه کد به حداقل برسد. وقتی راحت شدید که قطعات چگونه کنار هم می‌نشینند، می‌توانید به Easy RAG برای نمونه‌های سریع یا Advanced RAG برای سیستم‌های تولیدی منتقل شوید. -> **💡 قبلاً Easy RAG را دیده‌اید؟** ماژول [شروع سریع](../00-quick-start/README.md) شامل مثال پرسش و پاسخ اسناد ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) است که رویکرد Easy RAG را استفاده می‌کند — LangChain4j به صورت خودکار جاسازی، جستجو و ترکیب زمینه را مدیریت می‌کند. این ماژول گام بعدی را برداشته و آن خط لوله را باز می‌کند تا شما هر مرحله را ببینید و کنترل کنید. +> **💡 کنجکاو درباره Easy RAG؟** LangChain4j همچنین رویکرد *Easy RAG* را ارائه می‌دهد که در آن `AiServices` و `ContentRetriever` تعبیه‌سازی، جستجو و جمع‌آوری پرامپت را به طور خودکار انجام می‌دهند. این ماژول مسیر واضح‌تری را می‌پیماید تا بتوانید هر مرحله را خودتان ببینید و کنترل کنید. -نمودار زیر خط لوله Easy RAG از آن مثال شروع سریع را نشان می‌دهد. دقت کنید چگونه `AiServices` و `EmbeddingStoreContentRetriever` همه پیچیدگی‌ها را پنهان می‌کنند — یک سند بارگذاری می‌کنید، بازیابی‌کننده اضافه می‌کنید، و پاسخ می‌گیرید. رویکرد بومی در این ماژول هر یک از قدم‌های پنهان را باز می‌کند: +نمودار زیر خط لوله Easy RAG را نشان می‌دهد. توجه کنید که چگونه `AiServices` و `EmbeddingStoreContentRetriever` همه پیچیدگی‌ها را پنهان می‌کنند — شما یک سند بارگذاری می‌کنید، یک بازیاب متصل می‌کنید و پاسخ می‌گیرید. رویکرد بومی در این ماژول هر یک از آن مراحل پنهان‌شده را باز می‌کند: Easy RAG Pipeline - LangChain4j -*این نمودار خط لوله Easy RAG از `SimpleReaderDemo.java` را نشان می‌دهد. آن را با رویکرد بومی این ماژول مقایسه کنید: Easy RAG جاسازی، بازیابی و ترکیب زمینه را پشت `AiServices` و `ContentRetriever` پنهان می‌کند — شما یک سند بارگذاری می‌کنید، بازیابی‌کننده می‌زنید و پاسخ می‌گیرید. رویکرد بومی این ماژول آن خط لوله را باز می‌کند تا شما خود هر مرحله (جاسازی، جستجو، ترکیب زمینه، تولید) را فراخوانی کنید، از این رو دید و کنترل کامل دارید.* +*این نمودار خط لوله Easy RAG را نشان می‌دهد. آن را با رویکرد بومی این ماژول مقایسه کنید: Easy RAG تعبیه‌سازی، بازیابی و ساخت پرامپت را پشت `AiServices` و `ContentRetriever` مخفی می‌کند — شما سندی بارگذاری می‌کنید، بازیابی‌کننده‌ای متصل می‌کنید و پاسخ می‌گیرید. رویکرد بومی در این ماژول آن خط لوله را باز می‌کند تا شما هر مرحله (تعبیه‌سازی، جستجو، جمع‌آوری متن، تولید) را خودتان صدا بزنید، که دید و کنترل کاملی به شما می‌دهد.* -## نحوه کار +## نحوه کارکرد -خط لوله RAG در این ماژول به چهار مرحله تقسیم می‌شود که هر بار کاربر سوالی می‌پرسد به ترتیب اجرا می‌شوند. ابتدا یک سند بارگذاری شده، **تجزیه و به قطعات قابل مدیریت تقسیم می‌شود (chunked)**. سپس این قطعات به **جاسازی‌های برداری** تبدیل شده و ذخیره می‌شوند تا بتوان آن‌ها را به صورت ریاضی مقایسه کرد. وقتی یک پرس‌وجو می‌رسد، سیستم یک **جستجوی معنایی** انجام می‌دهد تا مرتبط‌ترین قطعات را پیدا کند، و در نهایت آن‌ها را به عنوان زمینه به مدل زبانی برای **تولید پاسخ** می‌دهد. بخش‌های زیر هر مرحله را با کد و نمودار واقعی توضیح می‌دهند. ابتدا به مرحله اول می‌پردازیم. +خط لوله RAG در این ماژول به چهار مرحله تقسیم می‌شود که هر بار یک کاربر سوال می‌پرسد به ترتیب اجرا می‌شوند. ابتدا سند بارگذاری‌شده **تجزیه و به تکه‌های قابل مدیریت تقسیم می‌شود**. سپس این تکه‌ها به **بردارهای تعبیه تبدیل** و ذخیره می‌شوند تا بتوان آن‌ها را به صورت ریاضی مقایسه کرد. وقتی پرسش می‌رسد، سیستم برای یافتن مرتبط‌ترین تکه‌ها **جستجوی معنایی** انجام می‌دهد و در نهایت آن‌ها را به عنوان متن زمینه به مدل زبانی بزرگ برای **تولید پاسخ** می‌فرستد. بخش‌های زیر هر مرحله را با کد واقعی و نمودارها بررسی می‌کنند. ابتدا گام اول را ببینیم. -### پردازش اسناد +### پردازش سند [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -وقتی سندی بارگذاری می‌کنید، سیستم آن را (PDF یا متن ساده) تجزیه می‌کند، فراداده‌ای مانند نام فایل به آن اضافه می‌کند و سپس آن را به قطعات تقسیم می‌کند — قطعات کوچکتری که به راحتی در پنجره زمینه مدل جا می‌گیرند. این قطعات کمی همپوشانی دارند تا در مرزها زمینه از بین نرود. +وقتی سندی بارگذاری می‌کنید، سیستم آن را (PDF یا متن ساده) تجزیه می‌کند، متادیتا مانند نام فایل را اضافه می‌کند و سپس آن را به تکه‌هایی تقسیم می‌کند — قطعات کوچکتری که به راحتی در پنجره متن مدل جای بگیرند. این تکه‌ها کمی هم‌پوشانی دارند تا زمینه در مرزها از دست نرود. ```java // فایل بارگذاری شده را تجزیه کرده و در یک سند LangChain4j قرار دهید @@ -116,30 +115,29 @@ DocumentSplitter splitter = DocumentSplitters List segments = splitter.split(document); ``` - - -نمودار زیر نشان می‌دهد این کار چگونه به صورت بصری انجام می‌شود. توجه کنید هر قطعه چند توکن با همسایه‌هایش در آمیخته است — همپوشانی ۳۰ توکنی اطمینان می‌دهد هیچ زمینه مهمی بین شکاف‌ها از دست نرود: + +نمودار زیر نحوه کار را به صورت تصویری نشان می‌دهد. ببینید هر تکه چگونه با همسایگانش برخی توکن‌ها را به اشتراک می‌گذارد — هم‌پوشانی ۳۰ توکن تضمین می‌کند که هیچ زمینه مهمی در شکاف‌ها از دست نرود: Document Chunking -*این نمودار سندی را نشان می‌دهد که به قطعات ۳۰۰ توکنی با ۳۰ توکن همپوشانی تقسیم شده است، و زمینه مرز قطعات حفظ شده است.* +*این نمودار نشان می‌دهد چگونه یک سند به تکه‌های ۳۰۰ توکنی با هم‌پوشانی ۳۰ توکنی تقسیم می‌شود، و زمینه در مرز تکه‌ها حفظ می‌شود.* -> **🤖 امتحان کنید با مکالمه [GitHub Copilot](https://github.com/features/copilot):** فایل [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) را باز کنید و بپرسید: -> - "چگونه LangChain4j اسناد را به قطعات تقسیم می‌کند و چرا همپوشانی مهم است؟" -> - "اندازه بهینه قطعات برای انواع مختلف اسناد چیست و چرا؟" -> - "چگونه اسناد چندزبانه یا با فرمت خاص را مدیریت کنم؟" +> **🤖 با [گیت‌هاب کاپایلوت](https://github.com/features/copilot) گفتگو کنید:** فایل [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) را باز کنید و بپرسید: +> - "LangChain4j چطور اسناد را به تکه‌هایی تقسیم می‌کند و چرا هم‌پوشانی مهم است؟" +> - "اندازه بهینه تکه برای انواع مختلف اسناد چیست و چرا؟" +> - "چطور با اسناد چندزبانه یا با قالب‌بندی ویژه برخورد کنیم؟" -### ایجاد جاسازی‌ها +### ایجاد تعبیه‌ها [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -هر قطعه به یک نمایش عددی به نام جاسازی تبدیل می‌شود — در واقع تبدیل معانی به اعداد. مدل جاسازی مانند یک مدل گفتگو "هوشمند" نیست؛ نمی‌تواند دستورالعمل بگیرد، استدلال کند یا پاسخ سوال دهد. کاری که می‌کند این است که متن را به فضایی ریاضی نقشه می‌کند که معانی مشابه در کنار هم قرار می‌گیرند — "ماشین" کنار "اتومبیل"، "سیاست بازپرداخت" کنار "پس گرفتن پولم". مدل گفتگو مانند یک فردی است که با او صحبت می‌کنید؛ مدل جاسازی سیستم بایگانی بسیار خوبی است. +هر تکه به یک نمایش عددی به نام تعبیه تبدیل می‌شود — اساساً یک تبدیل معنا به اعداد. مدل تعبیه‌سازی هوشمند نیست مانند مدل گفتگویی؛ نمی‌تواند دستورالعمل‌ها را دنبال کند، استدلال کند یا به سوالات پاسخ دهد. کاری که انجام می‌دهد این است که متن را به فضایی ریاضی نگاشت می‌کند که معانی مشابه نزدیک هم قرار می‌گیرند — "car" نزدیک "automobile"، "refund policy" نزدیک "return my money". مدل گفتگویی مانند فردی است که می‌توانید با او صحبت کنید؛ مدل تعبیه‌سازی مانند یک سامانه بایگانی بسیار خوب است. -نمودار زیر این مفهوم را به تصویر می‌کشد — متن وارد می‌شود، بردارهای عددی بیرون می‌آیند، و معانی مشابه بردارهای نزدیک به هم تولید می‌کنند: +نمودار زیر این مفهوم را نمایش می‌دهد — متن وارد می‌شود، بردارهای عددی بیرون می‌آیند و معانی مشابه بردارهای نزدیکی تولید می‌کنند: Embedding Model Concept -*این نمودار نشان می‌دهد چگونه مدل جاسازی متن را به بردارهای عددی تبدیل می‌کند، معانی مشابه مثل "ماشین" و "اتومبیل" را در فضای برداری نزدیک به هم قرار می‌دهد.* +*این نمودار نشان می‌دهد که یک مدل تعبیه‌سازی چگونه متن را به بردارهای عددی تبدیل می‌کند، و معانی مشابه مانند "car" و "automobile" را در فضای بردار نزدیک به هم قرار می‌دهد.* ```java @Bean @@ -154,31 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - - -نمودار کلاسی زیر دو جریان جداگانه در خط لوله RAG و کلاس‌های LangChain4j که آن‌ها را پیاده‌سازی می‌کنند، نشان می‌دهد. جریان **ورودی** (یک بار هنگام بارگذاری) سند را تقسیم می‌کند، قطعات را جاسازی می‌کند و از طریق `.addAll()` ذخیره می‌کند. جریان **پرس‌وجو** (هر بار که کاربر سوال می‌پرسد) سوال را جاسازی می‌کند، فروشگاه را با `.search()` جستجو می‌کند، و زمینه‌های یافته شده را به مدل مکالمه می‌فرستد. هر دو جریان به رابط مشترک `EmbeddingStore` می‌رسند: + +نمودار کلاس زیر دو جریان جداگانه در خط لوله RAG و کلاس‌های LangChain4j را که آن‌ها را پیاده‌سازی می‌کنند نشان می‌دهد. جریان **ورودی** (یکبار در زمان بارگذاری اجرا می‌شود) سند را تقسیم، تکه‌ها را تعبیه‌سازی و با `.addAll()` ذخیره می‌کند. جریان **پرسش** (هر بار که کاربر سوال می‌پرسد اجرا می‌شود) سوال را تعبیه‌سازی، فروشگاه را با `.search()` جستجو و متن مرتبط را به مدل گفتگویی می‌فرستد. هر دو جریان به رابط مشترک `EmbeddingStore` می‌رسند: LangChain4j RAG Classes -*این نمودار دو جریان در خط لوله RAG — ورودی و پرس‌وجو — و اتصال آن‌ها از طریق EmbeddingStore مشترک را نشان می‌دهد.* +*این نمودار دو جریان در خط لوله RAG — ورودی و پرسش — و نحوه اتصال آن‌ها از طریق EmbeddingStore مشترک را نشان می‌دهد.* -پس از ذخیره جاسازی‌ها، محتوای مشابه به طور طبیعی در فضای برداری در خوشه‌های نزدیک قرار می‌گیرند. تصویر زیر نشان می‌دهد چگونه اسناد مربوط به موضوعات مرتبط به صورت نقاط نزدیک کنار هم قرار می‌گیرند که امکان جستجوی معنایی را فراهم می‌کند: +وقتی تعبیه‌ها ذخیره شدند، محتوای مشابه به طور طبیعی در فضای بردار کنار هم خوشه‌بندی می‌شوند. تصویر زیر نشان می‌دهد چگونه اسناد مرتبط در نزدیکی یکدیگر به صورت نقاطی کنار هم قرار می‌گیرند، که امکان جستجوی معنایی را فراهم می‌کند: Vector Embeddings Space -*این تصویر نشان می‌دهد چگونه اسناد مرتبط در فضای برداری سه‌بعدی گرد هم می‌آیند و موضوعاتی مانند مستندات فنی، قوانین کسب‌وکار و سوالات متداول گروه‌های متمایز تشکیل می‌دهند.* +*این تصویر خوشه‌بندی اسناد مرتبط را در فضای سه‌بعدی بردار نشان می‌دهد، با موضوعاتی مانند اسناد فنی، قوانین کسب‌وکار و سوالات متداول که گروه‌های متمایزی تشکیل می‌دهند.* -وقتی کاربری جستجو می‌کند، سیستم چهار مرحله را دنبال می‌کند: یک بار اسناد را جاسازی می‌کند، هر بار پرس‌وجو را جاسازی می‌کند، بردار پرس‌وجو را با همه بردارهای ذخیره‌شده با شباهت کسینوسی مقایسه می‌کند، و بهترین K قطعه با امتیاز بالا را بازمی‌گرداند. نمودار زیر هر مرحله و کلاس‌های LangChain4j مرتبط را نشان می‌دهد: +وقتی کاربر جستجو می‌کند، سیستم چهار گام را طی می‌کند: اسناد یک‌بار تعبیه می‌شوند، پرسش در هر جستجو تعبیه می‌شود، بردار پرسش با همه بردارهای ذخیره‌شده با شباهت کسینوسی مقایسه می‌شود، و بخش‌های برتر نتیجه بازگردانده می‌شوند. نمودار زیر هر گام و کلاس‌های LangChain4j مربوط را نشان می‌دهد: Embedding Search Steps -*این نمودار فرایند جستجوی چهار مرحله‌ای جاسازی را نشان می‌دهد: جاسازی اسناد، جاسازی پرس‌وجو، مقایسه بردارها با شباهت کسینوسی، و بازگرداندن نتایج برتر.* +*این نمودار فرایند جستجوی تعبیه در چهار گام را نشان می‌دهد: تعبیه اسناد، تعبیه پرسش، مقایسه بردارها با شباهت کسینوسی، و بازگرداندن نتایج برتر.* ### جستجوی معنایی [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -وقتی سوالی می‌پرسید، سوال شما نیز به یک جاسازی تبدیل می‌شود. سیستم جاسازی سوال شما را با جاسازی همه قطعات سند مقایسه می‌کند. قطعاتی که بیشترین معنای مشابه دارند را پیدا می‌کند - نه فقط کلمات کلیدی که مطابقت دارند، بلکه شباهت معنایی واقعی. +وقتی سوال می‌پرسید، خود سوال نیز به تعبیه تبدیل می‌شود. سیستم تعبیه سوال را با همه تعبیه‌های تکه‌های سند مقایسه می‌کند. تکه‌هایی با معانی مشابه را می‌یابد — نه فقط مطابقت کلمات کلیدی، بلکه شباهت معنایی واقعی. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -197,29 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - - -نمودار زیر جستجوی معنایی را در مقابل جستجوی سنتی کلمات کلیدی مقایسه می‌کند. جستجوی کلمه کلیدی برای " وسیله نقلیه" یک قطعه مربوط به "ماشین‌ها و کامیون‌ها" را از دست می‌دهد، ولی جستجوی معنایی می‌فهمد آن‌ها یک معنی دارند و آن را به عنوان یک نتیجه با امتیاز بالا بازمی‌گرداند: + +نمودار زیر جستجوی معنایی را با جستجوی سنتی کلمات کلیدی مقایسه می‌کند. جستجوی کلمه کلیدی "vehicle" یک تکه درباره "cars and trucks" را از دست می‌دهد، ولی جستجوی معنایی می‌فهمد که آن‌ها یکی هستند و آن را به عنوان نتیجه با امتیاز بالا برمی‌گرداند: Semantic Search -*این نمودار جستجوی مبتنی بر کلمه کلیدی را با جستجوی معنایی مقایسه می‌کند، نشان می‌دهد چگونه جستجوی معنایی حتی زمانی که کلمات کلیدی دقیق متفاوتند محتواهای مرتبط مفهومی را بازیابی می‌کند.* -در پشت صحنه، شباهت با استفاده از تشابه کسینوس اندازه‌گیری می‌شود — اساساً پرسشی مشابه «آیا این دو پیکان به یک جهت اشاره می‌کنند؟» دو بخش می‌توانند کاملاً از کلمات متفاوتی استفاده کنند، اما اگر معنایشان یکی باشد، بردارهایشان به یک سمت اشاره می‌کنند و نمره نزدیک به ۱.۰ می‌گیرند: +*این نمودار جستجوی مبتنی بر کلمات کلیدی را با جستجوی معنایی مقایسه می‌کند و نشان می‌دهد چگونه جستجوی معنایی حتی وقتی کلمات کلیدی دقیق متفاوت هستند، محتوای مرتبط مفهومی را بازیابی می‌کند.* -تشابه کسینوس +در پس‌زمینه، شباهت با استفاده از شباهت کسینوسی اندازه‌گیری می‌شود — اساساً سوال می‌شود "آیا این دو پیکان به یک جهت اشاره می‌کنند؟" دو تکه می‌توانند کلمات کاملاً متفاوتی داشته باشند، ولی اگر معنی یکسانی داشته باشند بردارهایشان به یک سمت اشاره کرده و امتیاز نزدیک ۱.۰ می‌گیرند: -*این نمودار تشابه کسینوس را به عنوان زاویه بین بردارهای جاسازی نشان می‌دهد — بردارهای هم‌راستا نمره‌ای نزدیک به ۱.۰ کسب می‌کنند که نشان‌دهنده شباهت معنایی بالاتر است.* +Cosine Similarity +*این نمودار نشان‌دهنده شباهت کسینوس به‌عنوان زاویه بین بردارهای جاسازی است — بردارهای هم‌راستا امتیاز نزدیک‌تر به ۱.۰ می‌گیرند که نشان‌دهنده شباهت معنایی بالاتر است.* -> **🤖 امتحان با [GitHub Copilot](https://github.com/features/copilot) Chat:** فایل [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) را باز کنید و بپرسید: -> - "جستجوی شباهت چگونه با جاسازی‌ها کار می‌کند و چه چیزی نمره را تعیین می‌کند؟" -> - "چه آستانه شباهتی باید استفاده کنم و چگونه روی نتایج تأثیر می‌گذارد؟" -> - "چگونه مواردی که اسناد مرتبط پیدا نمی‌شوند را مدیریت کنم؟" +> **🤖 امتحان کنید با [GitHub Copilot](https://github.com/features/copilot) Chat:** فایل [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) را باز کنید و بپرسید: +> - "جستجوی شباهت چگونه با جاسازی‌ها کار می‌کند و چه چیزی امتیاز را تعیین می‌کند؟" +> - "چه حد آستانه شباهتی باید استفاده کنم و چگونه بر نتایج تأثیر می‌گذارد؟" +> - "چگونه مواردی که هیچ مدارک مرتبطی یافت نمی‌شود را مدیریت کنم؟" ### تولید پاسخ [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -مهم‌ترین بخش‌ها در قالب یک پرامپت ساختاریافته که شامل دستورالعمل‌های صریح، زمینه بازیابی‌شده و سؤال کاربر است، گردآوری می‌شوند. مدل این بخش‌های مشخص را می‌خواند و بر اساس آن اطلاعات پاسخ می‌دهد — فقط می‌تواند از اطلاعات موجود استفاده کند که از ایجاد توهم جلوگیری می‌کند. +مرتبط‌ترین بخش‌ها به یک پرامپت ساختاریافته جمع‌آوری می‌شوند که شامل دستورالعمل‌های صریح، زمینه بازیابی‌شده و سؤال کاربر است. مدل آن بخش‌های خاص را می‌خواند و بر اساس آن اطلاعات پاسخ می‌دهد — فقط می‌تواند از آنچه در مقابلش است استفاده کند، که از ایجاد توهم جلوگیری می‌کند. ```java String context = matches.stream() @@ -239,194 +235,194 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` + +نمودار زیر این گردآوری را به نمایش می‌گذارد — بخش‌های با بالاترین امتیاز از مرحله جستجو وارد قالب پرامپت می‌شوند و `OpenAiOfficialChatModel` پاسخ مبتنی بر داده تولید می‌کند: -نمودار زیر این فرایند گردآوری را در عمل نشان می‌دهد — بخش‌های با بالاترین امتیاز از مرحله جستجو وارد قالب پرامپت می‌شوند و `OpenAiOfficialChatModel` پاسخ مبتنی بر داده تولید می‌کند: +Context Assembly -ترکیب زمینه - -*این نمودار نشان می‌دهد چگونه بخش‌های با بالاترین امتیاز در یک پرامپت ساختاریافته جمع‌آوری می‌شوند و به مدل اجازه می‌دهد پاسخی مبتنی بر داده‌های شما تولید کند.* +*این نمودار نشان می‌دهد که چگونه بخش‌های با بالاترین امتیاز به یک پرامپت ساختاریافته تبدیل می‌شوند تا مدل پاسخ مبتنی بر داده‌های شما را تولید کند.* ## اجرای برنامه -**تأیید استقرار:** +**بررسی استقرار:** -اطمینان حاصل کنید فایل `.env` در دایرکتوری ریشه با اعتبارنامه‌های Azure وجود دارد (که در ماژول ۰۱ ایجاد شده است). این دستور را از دایرکتوری ماژول (`03-rag/`) اجرا کنید: +اطمینان حاصل کنید فایل `.env` در دایرکتوری ریشه با اعتبارات Azure موجود است (ساخته شده در طول ماژول ۰۱). این دستور را از دایرکتوری ماژول (`03-rag/`) اجرا کنید: -**Bash:** +**Bash:** ```bash cat ../.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نشان دهد ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نشان دهد +Get-Content ..\.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نمایش دهد ``` + +**راه‌اندازی برنامه:** -**اجرای برنامه:** - -> **توجه:** اگر قبلاً همه برنامه‌ها را با دستور `./start-all.sh` از ریشه (طبق توضیحات ماژول ۰۱) اجرا کرده باشید، این ماژول هم اکنون روی پورت ۸۰۸۱ در حال اجرا است. می‌توانید دستورات شروع زیر را رد کنید و مستقیم به http://localhost:8081 بروید. +> **توجه:** اگر قبلاً همه برنامه‌ها را با استفاده از `./start-all.sh` از دایرکتوری ریشه (مطابق شرح در ماژول ۰۱) شروع کرده‌اید، این ماژول هم اکنون روی پورت ۸۰۸۱ اجرا می‌شود. می‌توانید دستورات شروع زیر را رد کرده و مستقیماً به http://localhost:8081 بروید. **گزینه ۱: استفاده از Spring Boot Dashboard (توصیه شده برای کاربران VS Code)** -کانتینر توسعه شامل افزونه Spring Boot Dashboard است که رابط کاربری تصویری برای مدیریت همه برنامه‌های Spring Boot فراهم می‌کند. آن را در نوار فعالیت سمت چپ VS Code بیابید (آیکون Spring Boot را نگاه کنید). +کانتینر توسعه شامل افزونه Spring Boot Dashboard است که رابط بصری برای مدیریت همه برنامه‌های Spring Boot فراهم می‌کند. در نوار فعالیت سمت چپ VS Code آن را پیدا کنید (نماد Spring Boot را جستجو کنید). -از طریق Spring Boot Dashboard می‌توانید: -- همه برنامه‌های Spring Boot موجود در محیط کاری را ببینید -- برنامه‌ها را با یک کلیک راه‌اندازی/متوقف کنید -- لاگ‌های برنامه را به صورت زنده مشاهده کنید -- وضعیت برنامه‌ها را پایش کنید +از Spring Boot Dashboard می‌توانید: +- همه برنامه‌های Spring Boot موجود در محیط کاری را ببینید +- برنامه‌ها را با یک کلیک شروع/توقف کنید +- لاگ‌های برنامه را به صورت زنده مشاهده کنید +- وضعیت برنامه را نظارت کنید -فقط روی دکمه پخش کنار "rag" کلیک کنید تا این ماژول شروع شود، یا همه ماژول‌ها را همزمان راه‌اندازی نمایید. +فقط روی دکمه پخش کنار "rag" کلیک کنید تا این ماژول اجرا شود، یا همه ماژول‌ها را همزمان شروع کنید. -داشبورد Spring Boot +Spring Boot Dashboard -*این تصویر اسکرین‌شات داشبورد Spring Boot در VS Code را نشان می‌دهد که از طریق آن می‌توانید برنامه‌ها را به صورت تصویری اجرا، متوقف و پایش کنید.* +*این اسکرین‌شات نمای Spring Boot Dashboard در VS Code را نشان می‌دهد، جایی که می‌توانید به صورت بصری برنامه‌ها را شروع، متوقف و نظارت کنید.* -**گزینه ۲: استفاده از اسکریپت‌های شل** +**گزینه ۲: استفاده از اسکریپت‌های خط فرمان** -همه برنامه‌های وب (ماژول‌های ۰۱-۰۴) را اجرا کنید: +همه برنامه‌های وب (ماژول‌های ۰۱ تا ۰۴) را اجرا کنید: -**Bash:** +**Bash:** ```bash cd .. # از دایرکتوری ریشه ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd .. # از دایرکتوری ریشه .\start-all.ps1 ``` + +یا فقط این ماژول را اجرا کنید: -یا فقط همین ماژول را اجرا کنید: - -**Bash:** +**Bash:** ```bash cd 03-rag ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 03-rag .\start.ps1 ``` + +هر دو اسکریپت متغیرهای محیطی را به‌طور خودکار از فایل `.env` ریشه بارگذاری می‌کنند و در صورت عدم وجود JARها آنها را می‌سازند. -هر دو اسکریپت به‌طور خودکار متغیرهای محیطی را از فایل `.env` ریشه بارگذاری می‌کنند و در صورتی که فایل JAR وجود نداشته باشد آن را می‌سازند. - -> **توجه:** اگر ترجیح می‌دهید قبل از شروع همه ماژول‌ها را به صورت دستی بسازید: -> -> **Bash:** +> **توجه:** اگر می‌خواهید قبل از اجرای آن‌ها همه ماژول‌ها را به صورت دستی بسازید: +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> -> **PowerShell:** + +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -آدرس http://localhost:8081 را در مرورگر خود باز کنید. + +مرورگر خود را باز کرده و به http://localhost:8081 بروید. **برای توقف:** -**Bash:** +**Bash:** ```bash ./stop.sh # فقط این ماژول # یا cd .. && ./stop-all.sh # همه ماژول‌ها ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # فقط این ماژول # یا cd ..; .\stop-all.ps1 # همه ماژول‌ها ``` - + ## استفاده از برنامه -برنامه یک رابط وب برای بارگذاری اسناد و پرسش‌وپاسخ فراهم می‌کند. +برنامه رابط وبی برای بارگذاری سند و پرسیدن سوال فراهم می‌کند. -رابط برنامه RAG +RAG Application Interface -*این تصویر اسکرین‌شات رابط برنامه RAG را نشان می‌دهد جایی که می‌توانید اسناد بارگذاری کرده و سؤال بپرسید.* +*این اسکرین‌شات رابط برنامه RAG را نشان می‌دهد که در آن می‌توانید اسناد را بارگذاری کرده و سوال بپرسید.* ### بارگذاری سند -با بارگذاری یک سند شروع کنید — فایل‌های TXT برای آزمایش بهترین هستند. یک فایل `sample-document.txt` در این دایرکتوری موجود است که شامل اطلاعاتی درباره ویژگی‌های LangChain4j، پیاده‌سازی RAG و بهترین شیوه‌ها است — مناسب برای آزمایش سیستم. +با بارگذاری یک سند شروع کنید — فایل‌های TXT برای آزمایش بهترین عملکرد را دارند. در این پوشه یک فایل `sample-document.txt` موجود است که شامل اطلاعات درباره ویژگی‌های LangChain4j، پیاده‌سازی RAG و بهترین روش‌ها است — مناسب برای تست سیستم. -سیستم سند شما را پردازش می‌کند، آن را به بخش‌هایی تقسیم می‌کند و جاسازی (embedding) برای هر بخش می‌سازد. این کار به طور خودکار هنگام بارگذاری انجام می‌شود. +سیستم سند شما را پردازش می‌کند، آن را به بخش‌هایی تقسیم کرده و برای هر بخش جاسازی ایجاد می‌کند. این فرآیند هنگام بارگذاری به‌طور خودکار انجام می‌شود. -### پرسش سؤال‌ها +### پرسیدن سوالات -اکنون سؤال‌های مشخص درباره محتوای سند بپرسید. سؤالاتی را امتحان کنید که پاسخ قاطع و مشخصی در سند دارند. سیستم بخش‌های مرتبط را جستجو می‌کند، آنها را در پرامپت وارد می‌کند و پاسخ تولید می‌نماید. +حالا سوالات مشخصی درباره محتوای سند بپرسید. چیزی واقعی و آشکار در سند باشد. سیستم بخش‌های مرتبط را جستجو می‌کند، آن‌ها را در پرامپت می‌گنجاند و پاسخ تولید می‌کند. -### بررسی مراجع منابع +### بررسی مراجع منبع -متوجه باشید هر پاسخ شامل مراجع منبع به همراه نمرات شباهت است. این نمرات (از ۰ تا ۱) نشان می‌دهد هر بخش چقدر به سؤال شما مرتبط بوده است. نمرات بالاتر یعنی تطابق بهتر. این امکان را به شما می‌دهد پاسخ را با محتوای منبع بررسی کنید. +توجه داشته باشید هر پاسخ شامل مراجع منبع با امتیازهای شباهت است. این امتیازها (از ۰ تا ۱) نشان می‌دهند هر بخش چقدر به سوال شما مرتبط بوده است. امتیازهای بالاتر به معنای تطابق بهتر است. این به شما امکان می‌دهد پاسخ را با منبع اصلی بررسی کنید. -نتایج جستجوی RAG +RAG Query Results -*این تصویر اسکرین‌شات نتایج جستجو را نشان می‌دهد که پاسخ تولید شده، مراجع منبع و نمرات ارتباط برای هر بخش بازیابی شده را نمایش می‌دهد.* +*این اسکرین‌شات نتایج پرس‌وجو را با پاسخ تولید شده، مراجع منبع و امتیازهای مرتبط برای هر بخش بازیابی شده نشان می‌دهد.* -### آزمایش سؤال‌ها +### آزمایش با سوالات مختلف -انواع مختلف سؤال را امتحان کنید: -- حقایق مشخص: «موضوع اصلی چیست؟» -- مقایسه‌ها: «تفاوت X و Y چیست؟» -- خلاصه‌ها: «نکات کلیدی درباره Z را خلاصه کن» +انواع سوالات مختلف را امتحان کنید: +- حقایق مشخص: "موضوع اصلی چیست؟" +- مقایسه‌ها: "تفاوت بین X و Y چیست؟" +- خلاصه‌ها: "نکات کلیدی درباره Z را خلاصه کن" -مشاهده کنید چگونه نمرات ارتباط بسته به میزان تطابق سؤال شما با محتوای سند تغییر می‌کند. +تغییر امتیازهای مرتبط را بر اساس تطابق سوال با محتوای سند مشاهده کنید. ## مفاهیم کلیدی -### استراتژی بخش‌بندی +### استراتژی تقسیم بخش‌ها -اسناد به بخش‌های ۳۰۰ توکنی با ۳۰ توکن همپوشانی تقسیم می‌شوند. این تعادل اطمینان می‌دهد که هر بخش زمینه کافی برای معنا دارد در حالی که به اندازه کافی کوچک است تا چندین بخش را در یک پرامپت قرار دهد. +اسناد به بخش‌های ۳۰۰ توکنی با ۳۰ توکن هم‌پوشانی تقسیم می‌شوند. این تعادل اجازه می‌دهد هر بخش زمینه کافی برای معنا داشتن داشته باشد و در عین حال کوچک باشد تا چندین بخش در یک پرامپت جا شوند. -### نمرات شباهت +### امتیازهای شباهت -هر بخش بازیابی شده همراه با نمره شباهتی بین ۰ و ۱ است که نشان می‌دهد چقدر به سؤال کاربر مرتبط است. نمودار زیر بازه‌های نمره و نحوه استفاده سیستم برای فیلتر کردن نتایج را نشان می‌دهد: +هر بخش بازیابی شده همراه با امتیاز شباهتی بین ۰ تا ۱ است که نشان می‌دهد چقدر به سوال کاربر نزدیک است. نمودار زیر بازه‌های امتیاز و نحوه استفاده سیستم از آن‌ها برای فیلتر کردن نتایج را نشان می‌دهد: -نمرات شباهت +Similarity Scores -*این نمودار بازه نمرات از ۰ تا ۱ را نشان می‌دهد، با آستانه حداقل ۰.۵ که بخش‌های نامرتبط را فیلتر می‌کند.* +*این نمودار بازه امتیازها از ۰ تا ۱ را نشان می‌دهد، با حداقل آستانه ۰.۵ که بخش‌های نامرتبط را فیلتر می‌کند.* -نمرات از ۰ تا ۱ به شرح زیر هستند: -- ۰.۷-۱.۰: بسیار مرتبط، تطابق دقیق -- ۰.۵-۰.۷: مرتبط، زمینه خوب -- کمتر از ۰.۵: فیلتر شده، خیلی متفاوت +امتیازها بازه ۰ تا ۱ دارند: +- ۰.۷-۱.۰: خیلی مرتبط، تطابق دقیق +- ۰.۵-۰.۷: مرتبط، زمینه خوب +- کمتر از ۰.۵: فیلتر شده، خیلی نامرتبط -سیستم فقط بخش‌هایی را بازیابی می‌کند که بالای آستانه حداقل باشند تا کیفیت حفظ شود. +سیستم فقط بخش‌هایی را بازیابی می‌کند که بالاتر از حداقل آستانه باشند تا کیفیت حفظ شود. -جاسازی‌ها زمانی که خوشه‌بندی معنایی واضح باشد خوب عمل می‌کنند، اما نقاط کور دارند. نمودار زیر حالت‌های شکست رایج را نشان می‌دهد — بخش‌هایی که خیلی بزرگ هستند بردارهای مبهم تولید می‌کنند، بخش‌های خیلی کوچک زمینه ندارند، اصطلاحات مبهم به چند خوشه اشاره می‌کنند، و جستجوهای تطابق دقیق (کدها، شماره قطعات) اصلاً با جاسازی‌ها کار نمی‌کنند: +جاسازی‌ها زمانی خوب عمل می‌کنند که معانی به وضوح خوشه‌بندی شوند، اما نقاط کور دارند. نمودار زیر حالت‌های رایج شکست را نشان می‌دهد — بخش‌های خیلی بزرگ بردارهای مبهم ایجاد می‌کنند، بخش‌های خیلی کوچک فاقد زمینه هستند، اصطلاحات مبهم به چندین خوشه اشاره می‌کنند و جستجوهای تطابق دقیق (شناسه‌ها، شماره قطعات) کاملاً با جاسازی‌ها کار نمی‌کند: -حالات شکست جاسازی +Embedding Failure Modes -*این نمودار حالت‌های شکست رایج جاسازی را نشان می‌دهد: بخش‌های خیلی بزرگ، بخش‌های خیلی کوچک، اصطلاحات مبهم که به چند خوشه اشاره دارند، و جستجوهای تطابق دقیق مانند شناسه‌ها.* +*این نمودار حالت‌های رایج شکست جاسازی را نشان می‌دهد: بخش‌های خیلی بزرگ، بخش‌های خیلی کوچک، اصطلاحات مبهم که به چندین خوشه اشاره می‌کنند، و جستجوهای تطابق دقیق مانند شناسه‌ها.* -### ذخیره‌سازی در حافظه موقت +### ذخیره‌سازی در حافظه -این ماژول برای سادگی از ذخیره‌سازی در حافظه موقت استفاده می‌کند. وقتی برنامه را دوباره راه‌اندازی کنید، اسناد بارگذاری شده از دست می‌روند. سیستم‌های تولیدی از پایگاه داده‌های برداری پایدار مانند Qdrant یا Azure AI Search استفاده می‌کنند. +این ماژول برای سادگی از ذخیره‌سازی در حافظه استفاده می‌کند. هنگام راه‌اندازی مجدد برنامه، اسناد بارگذاری شده از دست می‌روند. سیستم‌های تولیدی از پایگاه داده‌های برداری دائمی مانند Qdrant یا Azure AI Search بهره می‌برند. ### مدیریت پنجره زمینه -هر مدل یک پنجره زمینه حداکثر دارد. نمی‌توان همه بخش‌های یک سند بزرگ را در آن گنجاند. سیستم فقط N بخش مرتبط برتر را بازیابی می‌کند (پیش‌فرض ۵) تا در محدوده ظرفیت بماند و همزمان زمینه کافی برای پاسخ‌های دقیق فراهم کند. +هر مدل یک پنجره زمینه حداکثری دارد. نمی‌توانید هر بخش از یک سند بزرگ را وارد کنید. سیستم بالاترین N بخش مرتبط را بازیابی می‌کند (پیش‌فرض ۵) تا در محدودیت‌ها بماند و در عین حال زمینه کافی برای پاسخ‌های دقیق فراهم گردد. -## وقتی RAG اهمیت دارد +## کی RAG اهمیت دارد -روش RAG همیشه بهترین گزینه نیست. راهنمای تصمیم‌گیری زیر کمک می‌کند تشخیص دهید چه زمانی RAG ارزش می‌افزاید و چه زمانی روش‌های ساده‌تر — مانند وارد کردن محتوا مستقیماً در پرامپت یا تکیه بر دانش داخلی مدل — کافی است: +RAG همیشه رویکرد مناسب نیست. راهنمای تصمیم زیر به شما کمک می‌کند تعیین کنید چه زمانی RAG ارزش افزوده دارد و چه زمانی روش‌های ساده‌تر — مانند قرار دادن محتوا مستقیماً در پرامپت یا اعتماد به دانش داخلی مدل — کافی هستند: -چه زمانی از RAG استفاده کنیم +When to Use RAG -*این نمودار راهنمای تصمیم‌گیری درباره زمان‌هایی که RAG ارزش افزوده ایجاد می‌کند و زمان‌هایی که روش‌های ساده‌تر کافی‌اند را نشان می‌دهد.* +*این نمودار راهنمای تصمیم‌گیری برای زمان استفاده از RAG در مقابل زمان کافی بودن روش‌های ساده‌تر را نشان می‌دهد.* -## گام‌های بعدی +## مراحل بعدی -**ماژول بعدی:** [04-tools - عوامل هوش مصنوعی با ابزارها](../04-tools/README.md) +**ماژول بعدی:** [04-tools - عامل‌های هوش مصنوعی با ابزارها](../04-tools/README.md) --- @@ -435,6 +431,6 @@ cd ..; .\stop-all.ps1 # همه ماژول‌ها --- -**سلب مسئولیت**: -این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما برای دقت تلاش می‌کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است دارای خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود، باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، استفاده از ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئول هیچ‌گونه سوءتفاهم یا تفسیر نادرست ناشی از استفاده از این ترجمه نیستیم. +**سلب مسئولیت**: +این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم. \ No newline at end of file diff --git a/translations/fa/04-tools/README.md b/translations/fa/04-tools/README.md index 9d0b31137..fedcbda2c 100644 --- a/translations/fa/04-tools/README.md +++ b/translations/fa/04-tools/README.md @@ -1,84 +1,84 @@ -# ماژول ۰۴: عامل‌های هوش مصنوعی با ابزارها +# ماژول ۰۴: عوامل هوش مصنوعی با ابزارها ## فهرست مطالب -- [مرور ویدئویی](../../../04-tools) -- [چه چیزهایی یاد خواهید گرفت](../../../04-tools) -- [پیش‌نیازها](../../../04-tools) -- [درک عامل‌های هوش مصنوعی با ابزارها](../../../04-tools) -- [نحوه عملکرد فراخوانی ابزار](../../../04-tools) - - [تعاریف ابزار](../../../04-tools) - - [تصمیم‌گیری](../../../04-tools) - - [اجرا](../../../04-tools) - - [تولید پاسخ](../../../04-tools) - - [معماری: اتصال خودکار در Spring Boot](../../../04-tools) -- [زنجیره‌سازی ابزار](../../../04-tools) -- [اجرای برنامه](../../../04-tools) -- [استفاده از برنامه](../../../04-tools) - - [تست استفاده ساده از ابزار](../../../04-tools) - - [آزمایش زنجیره‌سازی ابزار](../../../04-tools) - - [مشاهده جریان گفتگو](../../../04-tools) - - [آزمایش درخواست‌های مختلف](../../../04-tools) -- [مفاهیم کلیدی](../../../04-tools) - - [الگوی ReAct (استدلال و عمل)](../../../04-tools) - - [اهمیت توضیحات ابزار](../../../04-tools) - - [مدیریت جلسه](../../../04-tools) - - [مدیریت خطا](../../../04-tools) -- [ابزارهای موجود](../../../04-tools) -- [چه زمانی باید از عامل‌های مبتنی بر ابزار استفاده کرد](../../../04-tools) -- [ابزارها در مقابل RAG](../../../04-tools) -- [گام‌های بعدی](../../../04-tools) - -## مرور ویدئویی +- [راهنمای ویدئویی](#راهنمای-ویدئویی) +- [آنچه یاد خواهید گرفت](#آنچه-یاد-خواهید-گرفت) +- [پیش‌نیازها](#پیش‌نیازها) +- [درک عوامل هوش مصنوعی با ابزارها](#درک-عوامل-هوش-مصنوعی-با-ابزارها) +- [نحوه کارکرد فراخوانی ابزار](#نحوه-کارکرد-فراخوانی-ابزار) + - [تعاریف ابزار](#تعاریف-ابزار) + - [تصمیم‌گیری](#تصمیم‌گیری) + - [اجرا](#اجرا) + - [تولید پاسخ](#تولید-پاسخ) + - [معماری: اتصال خودکار Spring Boot](#معماری-اتصال-خودکار-spring-boot) +- [زنجیره‌سازی ابزارها](#زنجیره‌سازی-ابزارها) +- [اجرای برنامه](#اجرای-برنامه) +- [استفاده از برنامه](#استفاده-از-برنامه) + - [امتحان استفاده ساده از ابزار](#آزمایش-استفاده-ساده-از-ابزار) + - [آزمایش زنجیره‌سازی ابزار](#آزمایش-زنجیره‌سازی-ابزار) + - [مشاهده جریان مکالمه](#مشاهده-جریان-مکالمه) + - [آزمایش درخواست‌های مختلف](#آزمایش-درخواست‌های-مختلف) +- [مفاهیم کلیدی](#مفاهیم-کلیدی) + - [الگوی ReAct (استدلال و عمل)](#الگوی-react-استدلال-و-عمل) + - [اهمیت توضیحات ابزار](#توضیحات-ابزار-مهم-است) + - [مدیریت جلسه](#مدیریت-نشست) + - [مدیریت خطا](#مدیریت-خطا) +- [ابزارهای در دسترس](#ابزارهای-در-دسترس) +- [زمان استفاده از عوامل مبتنی بر ابزار](#چه-زمانی-از-عامل‌های-مبتنی-بر-ابزار-استفاده-کنیم) +- [ابزارها در مقابل RAG](#ابزارها-در-مقابل-rag) +- [گام‌های بعدی](#مراحل-بعدی) + +## راهنمای ویدئویی این جلسه زنده را تماشا کنید که توضیح می‌دهد چگونه با این ماژول شروع کنید: -عامل‌های هوش مصنوعی با ابزارها و MCP - جلسه زنده +عوامل هوش مصنوعی با ابزارها و MCP - جلسه زنده -## چه چیزهایی یاد خواهید گرفت +## آنچه یاد خواهید گرفت -تا کنون یاد گرفته‌اید چگونه با هوش مصنوعی گفتگو کنید، درخواست‌ها را به‌طور مؤثر ساختاربندی کنید و پاسخ‌ها را بر اساس اسناد خود پایه‌گذاری نمایید. اما هنوز یک محدودیت اساسی وجود دارد: مدل‌های زبان تنها می‌توانند متن تولید کنند. آنها نمی‌توانند وضعیت آب و هوا را بررسی کنند، محاسبات انجام دهند، پایگاه‌های داده را جستجو کنند یا با سیستم‌های خارجی تعامل داشته باشند. +تا کنون یاد گرفته‌اید چگونه با هوش مصنوعی گفتگو کنید، پرامپت‌ها را به طور مؤثر ساختاربندی کنید و پاسخ‌ها را در اسناد خود مستند کنید. اما هنوز یک محدودیت بنیادی وجود دارد: مدل‌های زبانی فقط می‌توانند متن تولید کنند. آن‌ها نمی‌توانند وضعیت آب و هوا را بررسی کنند، محاسبات انجام دهند، پایگاه داده‌ها را جستجو کنند یا با سیستم‌های خارجی تعامل داشته باشند. -ابزارها این محدودیت را تغییر می‌دهند. با دادن دسترسی به مدل برای فراخوانی توابع، آن را از یک تولیدکننده متن به عاملی که می‌تواند اقدامات انجام دهد تبدیل می‌کنید. مدل تصمیم می‌گیرد چه زمانی به ابزار نیاز دارد، کدام ابزار را استفاده کند و چه پارامترهایی ارسال کند. کد شما تابع را اجرا کرده و نتیجه را باز می‌گرداند. مدل آن نتیجه را در پاسخ خود جای می‌دهد. +ابزارها این وضعیت را تغییر می‌دهند. با دادن دسترسی به مدل به عملکردهایی که می‌تواند آنها را فراخوانی کند، آن را از تولیدکننده متن به عاملی تبدیل می‌کنید که می‌تواند عمل کند. مدل تصمیم می‌گیرد که کی به یک ابزار نیاز دارد، کدام ابزار را استفاده کند و چه پارامترهایی را ارسال نماید. کد شما عملکرد را اجرا کرده و نتیجه را بازمی‌گرداند. مدل آن نتیجه را در پاسخ خود وارد می‌کند. ## پیش‌نیازها -- تکمیل [ماژول ۰۱ - مقدمه](../01-introduction/README.md) (منابع Azure OpenAI مستقر شده‌اند) -- توصیه می‌شود ماژول‌های قبلی تکمیل شده باشند (این ماژول به [مفاهیم RAG از ماژول ۰۳](../03-rag/README.md) در مقایسه ابزارها در مقابل RAG اشاره دارد) -- فایل `.env` در دایرکتوری ریشه با اعتبارنامه‌های Azure (ایجاد شده توسط `azd up` در ماژول ۰۱) +- تکمیل شده [ماژول ۰۱ - مقدمه](../01-introduction/README.md) (منابع Azure OpenAI مستقر شده) +- تکمیل ماژول‌های قبلی توصیه شده (این ماژول به [مفاهیم RAG از ماژول ۰۳](../03-rag/README.md) در مقایسه ابزارها با RAG اشاره دارد) +- فایل `.env` در دایرکتوری ریشه با اعتبارنامه‌های Azure (ایجاد شده با `azd up` در ماژول ۰۱) -> **توجه:** اگر ماژول ۰۱ را تکمیل نکردید، ابتدا دستورالعمل‌های استقرار آنجا را دنبال کنید. +> **توجه:** اگر ماژول ۰۱ را تکمیل نکرده‌اید، ابتدا از دستورالعمل‌های استقرار آن پیروی کنید. -## درک عامل‌های هوش مصنوعی با ابزارها +## درک عوامل هوش مصنوعی با ابزارها -> **📝 توجه:** در این ماژول اصطلاح «عامل‌ها» به دستیاران هوش مصنوعی مجهز به قابلیت فراخوانی ابزار اشاره دارد. این با الگوهای **Agentic AI** (عامل‌های خودکار با برنامه‌ریزی، حافظه و استدلال چندمرحله‌ای) که در [ماژول ۰۵: MCP](../05-mcp/README.md) پوشش داده خواهد شد، متفاوت است. +> **📝 توجه:** اصطلاح «عوامل» در این ماژول به دستیاران هوش مصنوعی اشاره دارد که با قابلیت‌های فراخوانی ابزار تقویت شده‌اند. این با الگوهای **Agentic AI** (عوامل مستقل با برنامه‌ریزی، حافظه و استدلال چندمرحله‌ای) که در [ماژول ۰۵: MCP](../05-mcp/README.md) پوشش داده می‌شوند، متفاوت است. -بدون ابزار، یک مدل زبان فقط می‌تواند متن تولید کند که بر اساس داده‌های آموزشی خودش است. از آن درباره آب و هوای فعلی سؤال کنید، باید حدس بزند. اگر ابزار بدهید، می‌تواند یک API هواشناسی فراخوانی کند، محاسبات انجام دهد یا پایگاه داده‌ای را جستجو کند — سپس آن نتایج واقعی را در پاسخ خود بگنجاند. +بدون ابزار، یک مدل زبانی فقط می‌تواند متن را از داده‌های آموزشی خود تولید کند. از آن بخواهید وضعیت آب و هوا را بگوید، باید حدس بزند. به آن ابزار بدهید و می‌تواند API وضعیت هوا را فراخوانی کند، محاسبات انجام دهد یا پایگاه داده را جستجو کند — سپس آن نتایج واقعی را در پاسخ خود بگنجاند. بدون ابزار در مقابل با ابزار -*بدون ابزار مدل فقط حدس می‌زند — با ابزار می‌تواند APIها، محاسبات را اجرا کند و داده‌های زمان واقعی بازگرداند.* +*بدون ابزار مدل فقط حدس می‌زند — با ابزارها می‌تواند APIها را فراخوانی کند، محاسبه انجام دهد و داده‌های لحظه‌ای را بازگرداند.* -یک عامل هوش مصنوعی با ابزارها از الگوی **استدلال و عمل (ReAct)** پیروی می‌کند. مدل فقط پاسخ نمی‌دهد — درباره آنچه نیاز دارد فکر می‌کند، با فراخوانی یک ابزار عمل می‌کند، نتیجه را مشاهده می‌کند و سپس تصمیم می‌گیرد که دوباره عمل کند یا پاسخ نهایی را ارائه دهد: +یک عامل هوش مصنوعی با ابزارها از الگوی **استدلال و عمل (ReAct)** پیروی می‌کند. مدل فقط پاسخ نمی‌دهد — تفکر می‌کند که چه نیاز دارد، با فراخوانی ابزار عمل می‌کند، نتیجه را مشاهده می‌کند و سپس تصمیم می‌گیرد که دوباره عمل کند یا پاسخ نهایی را ارائه دهد: -۱. **استدلال** — عامل سؤال کاربر را تجزیه و تحلیل می‌کند و تعیین می‌کند چه اطلاعاتی نیاز دارد -۲. **عمل** — عامل ابزار مناسب را انتخاب کرده، پارامترهای درست را تولید می‌کند و آن را فرا می‌خواند -۳. **مشاهده** — عامل خروجی ابزار را دریافت کرده و ارزیابی می‌کند -۴. **تکرار یا پاسخ** — اگر داده بیشتری لازم باشد، حلقه تکرار می‌شود؛ در غیر این صورت پاسخ نهایی به زبان طبیعی تنظیم می‌شود +1. **استدلال** — عامل سؤال کاربر را تحلیل و مشخص می‌کند چه اطلاعاتی نیاز دارد +2. **عمل** — عامل ابزار مناسب را انتخاب، پارامترهای صحیح را تولید و آن را فراخوانی می‌کند +3. **مشاهده** — عامل خروجی ابزار را دریافت و نتیجه را ارزیابی می‌کند +4. **تکرار یا پاسخ** — اگر داده‌ی بیشتری نیاز باشد، عامل به مرحله اول برمی‌گردد؛ در غیر این صورت پاسخ نهایی را به زبان طبیعی می‌سازد الگوی ReAct -*چرخه ReAct — عامل درباره آنچه باید انجام دهد استدلال می‌کند، با فراخوانی ابزار عمل می‌کند، نتیجه را مشاهده می‌کند و تا رسیدن به پاسخ نهایی حلقه می‌زند.* +*چرخه ReAct — عامل در مورد اینکه چه کاری انجام دهد استدلال می‌کند، با فراخوانی ابزار عمل می‌کند، نتیجه را مشاهده می‌کند و تا زمانی که بتواند پاسخ نهایی را ارائه دهد، تکرار می‌کند.* -این روند به‌طور خودکار انجام می‌شود. شما ابزارها و توضیحات آنها را تعریف می‌کنید. مدل تصمیم‌گیری درباره زمان و نحوه استفاده آنها را بر عهده می‌گیرد. +این فرایند به طور خودکار انجام می‌شود. شما ابزارها و توضیحاتشان را تعریف می‌کنید. مدل تصمیم‌گیری درباره زمان و نحوه استفاده از آن‌ها را بر عهده دارد. -## نحوه عملکرد فراخوانی ابزار +## نحوه کارکرد فراخوانی ابزار ### تعاریف ابزار [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -شما توابعی با توضیحات واضح و مشخصات پارامتر تعریف می‌کنید. مدل این توضیحات را در درخواست سیستم خود مشاهده کرده و می‌فهمد هر ابزار چه کاری انجام می‌دهد. +شما توابعی با توضیح واضح و مشخصات پارامترها تعریف می‌کنید. مدل این توضیحات را در پرامپت سیستمی خود می‌بیند و درک می‌کند هر ابزار چه کاری انجام می‌دهد. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // منطق جستجوی آب و هوای شما + // منطق جستجوی هوای شما return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,141 +96,139 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// دستیار به طور خودکار توسط Spring Boot متصل شده است به: -// - بین ChatModel -// - تمام روش‌های @Tool از کلاس‌های @Component -// - ChatMemoryProvider برای مدیریت جلسه +// دستیار به طور خودکار توسط Spring Boot متصل شده است با: +// - Bean مدل چت +// - همه متدهای @Tool از کلاس‌های @Component +// - ارائه‌دهنده حافظه چت برای مدیریت نشست‌ها ``` - -نمودار زیر هر نکته را تجزیه کرده و نشان می‌دهد چگونه هر قطعه به هوش مصنوعی کمک می‌کند زمان فراخوانی ابزار و آرگومان‌های پاس داده شده را بفهمد: +نمودار زیر هر توضیح را تجزیه کرده و نشان می‌دهد هر بخش چگونه به AI کمک می‌کند زمان فراخوانی ابزار و پارامترهایی که باید ارسال شود را بفهمد: آناتومی تعاریف ابزار -*آناتومی تعریف یک ابزار — @Tool به هوش مصنوعی می‌گوید چه زمانی از آن استفاده کند، @P هر پارامتر را توصیف می‌کند، و @AiService در زمان راه‌اندازی همه چیز را متصل می‌کند.* +*آناتومی تعریف یک ابزار — @Tool به AI می‌گوید کی از آن استفاده کند، @P هر پارامتر را توصیف می‌کند و @AiService همه چیز را هنگام راه‌اندازی متصل می‌کند.* -> **🤖 با [GitHub Copilot](https://github.com/features/copilot) چت کنید:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) را باز کنید و بپرسید: -> - "چگونه یک API واقعی هواشناسی مثل OpenWeatherMap را به جای داده‌های شبیه‌سازی شده ادغام کنم؟" -> - "یک توضیح خوب برای ابزار چگونه است که به هوش مصنوعی در استفاده صحیح کمک می‌کند؟" -> - "چگونه خطاها و محدودیت‌های نرخ API را در پیاده‌سازی ابزار مدیریت کنم؟" +> **🤖 امتحان کنید با چت [GitHub Copilot](https://github.com/features/copilot):** فایل [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) را باز کنید و بپرسید: +> - "چگونه می‌توانم یک API واقعی وضعیت هوا مانند OpenWeatherMap را به جای داده‌های شبیه‌سازی شده یکپارچه کنم؟" +> - "یک توضیح ابزار خوب که به AI کمک کند به درستی از آن استفاده کند، چگونه است؟" +> - "چگونه خطاهای API و محدودیت‌های نرخ را در پیاده‌سازی ابزار مدیریت کنم؟" ### تصمیم‌گیری -وقتی کاربر می‌پرسد «آب و هوای سیاتل چگونه است؟»، مدل به‌طور تصادفی ابزار انتخاب نمی‌کند. هدف کاربر را با تمام توضیحات ابزارهایی که به آنها دسترسی دارد مقایسه می‌کند، برای هر کدام نمره‌ای از نظر ارتباط می‌دهد و بهترین تطابق را انتخاب می‌کند. سپس یک فراخوانی تابع ساختاریافته با پارامترهای صحیح تولید می‌کند — در این مورد مقدار `location` را `"Seattle"` تنظیم می‌کند. +وقتی کاربر می‌پرسد «وضعیت هوا در سیاتل چیست؟»، مدل تصادفی یک ابزار انتخاب نمی‌کند. مدل قصد کاربر را با هر توضیح ابزاری که دسترسی دارد مقایسه می‌کند، هرکدام را بر اساس مرتبط بودن امتیاز می‌دهد و بهترین تطبیق را انتخاب می‌کند. سپس فراخوانی تابع ساختار یافته‌ای با پارامترهای صحیح تولید می‌کند — در این مورد، تنظیم `location` به `"Seattle"`. -اگر هیچ ابزاری با درخواست کاربر تطابق نداشته باشد، مدل به پاسخ دادن از دانش خود بازمی‌گردد. اگر چندین ابزار تطبیق داشتند، دقیق‌ترین ابزار انتخاب می‌شود. +اگر هیچ ابزاری با درخواست کاربر مطابقت نداشته باشد، مدل از دانش خودش پاسخ می‌دهد. اگر چند ابزار مطابقت داشتند، دقیق‌ترین را انتخاب می‌کند. -چگونه هوش مصنوعی تصمیم می‌گیرد از کدام ابزار استفاده کند +چگونه AI انتخاب می‌کند کدام ابزار را استفاده کند -*مدل هر ابزار موجود را نسبت به هدف کاربر ارزیابی کرده و بهترین تطابق را انتخاب می‌کند — به همین دلیل نوشتن توضیحات واضح و مشخص ابزار مهم است.* +*مدل همه ابزارهای موجود را بر اساس قصد کاربر ارزیابی می‌کند و بهترین تطبیق را انتخاب می‌کند — به همین دلیل نوشتن توضیحات ابزار واضح و خاص اهمیت دارد.* ### اجرا [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot رابط `@AiService` اعلامی را با تمام ابزارهای ثبت‌شده به‌صورت خودکار متصل می‌کند و LangChain4j فراخوانی ابزارها را به‌طور خودکار اجرا می‌کند. پشت صحنه، یک فراخوانی کامل ابزار از شش مرحله عبور می‌کند — از سؤال زبان طبیعی کاربر تا پاسخ زبان طبیعی نهایی: +Spring Boot رابط اعلانی `@AiService` را با همه ابزارهای ثبت شده خودکار متصل می‌کند و LangChain4j فراخوانی ابزارها را به صورت خودکار اجرا می‌کند. پشت صحنه، یک فراخوانی کامل ابزار از شش مرحله عبور می‌کند — از سؤال زبان طبیعی کاربر تا پاسخ به زبان طبیعی: -روند فراخوانی ابزار +جریان فراخوانی ابزار -*روند انتها به انتها — کاربر سؤال می‌کند، مدل یک ابزار انتخاب می‌کند، LangChain4j آن را اجرا می‌کند و مدل نتیجه را در پاسخ طبیعی جای می‌دهد.* +*جریان انتها به انتها — کاربر سؤال می‌پرسد، مدل یک ابزار انتخاب می‌کند، LangChain4j آن را اجرا می‌کند و مدل نتیجه را در یک پاسخ طبیعی می‌بافد.* -اگر [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) را در ماژول ۰۰ اجرا کرده باشید، قبلاً این الگو را دیده‌اید — ابزارهای `Calculator` به همین صورت فراخوانی شدند. نمودار توالی زیر دقیقاً نشان می‌دهد در آن دمو چه اتفاقی افتاد: +پشت صحنه، `AiServices` همان حلقه فراخوانی ابزار را برای هر ابزاری اجرا می‌کند — اینجا با یک `Calculator` ساده نشان داده شده است. نمودار دنباله زیر دقیقاً نشان می‌دهد چه مواردی در پس‌زمینه اتفاق می‌افتد: نمودار توالی فراخوانی ابزار -*حلقه فراخوانی ابزار از دمو Quick Start — `AiServices` پیام و طرحواره‌های ابزار شما را به LLM می‌فرستد، LLM با یک فراخوانی تابع مانند `add(42, 58)` پاسخ می‌دهد، LangChain4j روش `Calculator` را به‌صورت محلی اجرا می‌کند و نتیجه را برای پاسخ نهایی بازمی‌گرداند.* +*حلقه فراخوانی ابزار — `AiServices` پیام و اسکیماهای ابزار شما را به LLM ارسال می‌کند، LLM پاسخ می‌دهد با یک فراخوانی تابع مانند `add(42, 58)`, LangChain4j روش `Calculator` را به صورت محلی اجرا می‌کند و نتیجه را برای پاسخ نهایی بازمی‌گرداند.* -> **🤖 با [GitHub Copilot](https://github.com/features/copilot) چت کنید:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) را باز کنید و بپرسید: -> - "الگوی ReAct چگونه کار می‌کند و چرا برای عامل‌های هوش مصنوعی مؤثر است؟" -> - "عامل چگونه تصمیم می‌گیرد کدام ابزار را به چه ترتیبی استفاده کند؟" -> - "اگر اجرای یک ابزار شکست خورد چه اتفاقی می‌افتد — چگونه باید خطاها را به‌طور قابل اعتماد مدیریت کنم؟" +> **🤖 امتحان کنید با چت [GitHub Copilot](https://github.com/features/copilot):** فایل [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) را باز کنید و بپرسید: +> - "الگوی ReAct چگونه کار می‌کند و چرا برای عوامل هوش مصنوعی مؤثر است؟" +> - "عامل چگونه تصمیم می‌گیرد از کدام ابزار استفاده کند و به چه ترتیبی؟" +> - "اگر اجرای یک ابزار شکست خورد چه می‌شود - چگونه باید خطاها را به‌طور مقاوم مدیریت کنم؟" ### تولید پاسخ -مدل داده‌های آب و هوا را دریافت کرده و آن را به یک پاسخ زبان طبیعی برای کاربر فرمت می‌کند. +مدل داده‌های هواشناسی را دریافت کرده و آن را به یک پاسخ با زبان طبیعی برای کاربر قالب‌بندی می‌کند. -### معماری: اتصال خودکار در Spring Boot +### معماری: اتصال خودکار Spring Boot -این ماژول از ادغام LangChain4j با Spring Boot با رابط‌های اعلامی `@AiService` استفاده می‌کند. در زمان راه‌اندازی، Spring Boot هر `@Component` که شامل متدهای `@Tool` است، bean مدل چت شما و `ChatMemoryProvider` را پیدا کرده، و همه را در یک رابط `Assistant` بدون کد اضافی متصل می‌کند. +این ماژول از ادغام LangChain4j با Spring Boot با رابط‌های اعلانی `@AiService` استفاده می‌کند. هنگام راه‌اندازی، Spring Boot هر `@Component` که حاوی متدهای `@Tool` است، bean مدل گفتگو و `ChatMemoryProvider` را کشف می‌کند — سپس همه آنها را در یک رابط `Assistant` با صفر کد تکراری متصل می‌کند. معماری اتصال خودکار Spring Boot -*رابط `@AiService` مدل چت، مؤلفه‌های ابزار و ارائه‌دهنده حافظه را به هم متصل می‌کند — Spring Boot همه اتصال‌ها را به‌طور خودکار مدیریت می‌کند.* +*رابط @AiService مدل گفتگو، کامپوننت‌های ابزار و ارائه‌دهنده حافظه را به هم پیوند می‌دهد — Spring Boot همه اتصال‌ها را خودکار انجام می‌دهد.* -روند کامل چرخه درخواست به‌صورت نمودار توالی — از درخواست HTTP تا کنترلر، سرویس و پراکسی متصل خودکار، و تا اجرای ابزار و بازگشت پاسخ: +در اینجا چرخه کامل درخواست به صورت نمودار توالی — از درخواست HTTP از طریق کنترلر، سرویس و پراکسی متصل خودکار تا اجرای ابزار و بازگشت نمایش داده شده است: -نمودار توالی فراخوانی ابزار در Spring Boot +نمودار توالی فراخوانی ابزار Spring Boot -*چرخه کامل درخواست در Spring Boot — درخواست HTTP از کنترلر و سرویس عبور می‌کند تا به پراکسی `Assistant` متصل خودکار برسد که LLM و فراخوانی‌های ابزار را به‌طور خودکار مدیریت می‌کند.* +*چرخه کامل درخواست Spring Boot — درخواست HTTP از کنترلر و سرویس تا پراکسی Assistant متصل خودکار عبور می‌کند که هماهنگی LLM و فراخوانی ابزارها را خودکار انجام می‌دهد.* -مزایای کلیدی این روش: +مزایای کلیدی این رویکرد: -- **اتصال خودکار Spring Boot** — مدل چت و ابزارها به‌صورت خودکار تزریق می‌شوند -- **الگوی @MemoryId** — مدیریت حافظه مبتنی بر جلسه به‌طور خودکار -- **یک نمونه واحد** — ساخته شدن یک بار Assistant و استفاده مجدد برای عملکرد بهتر -- **اجرای نوع امن** — متدهای جاوا مستقیماً با تبدیل نوع فراخوانی می‌شوند -- **هماهنگی چندمرحله‌ای** — زنجیره‌سازی ابزار را به‌طور خودکار مدیریت می‌کند -- **کد اضافی صفر** — بدون نیاز به فراخوانی دستی `AiServices.builder()` یا نگهداری HashMap حافظه +- **اتصال خودکار Spring Boot** — مدل گفتگو و ابزارها به صورت خودکار تزریق می‌شوند +- **الگوی @MemoryId** — مدیریت خودکار حافظه مبتنی بر جلسه +- **یک نمونه واحد** — Assistant یک بار ساخته شده و برای عملکرد بهتر مجدداً استفاده می‌شود +- **اجرای نوع امن** — متدهای جاوا به صورت مستقیم با تبدیل نوع فراخوانی می‌شوند +- **هماهنگی چندمرحله‌ای** — زنجیره‌سازی ابزارها را به صورت خودکار مدیریت می‌کند +- **صفر کد تکراری** — بدون فراخوانی‌های دستی `AiServices.builder()` یا هش‌مپ حافظه -روش‌های جایگزین (فراخوانی دستی `AiServices.builder()`) کد بیشتری می‌طلبند و از مزایای ادغام Spring Boot محروم‌اند. +رویکردهای جایگزین (دستی با `AiServices.builder()`) نیازمند کد بیشتر و فاقد مزایای ادغام Spring Boot هستند. -## زنجیره‌سازی ابزار +## زنجیره‌سازی ابزارها -**زنجیره‌سازی ابزار** — قدرت واقعی عامل‌های مبتنی بر ابزار وقتی ظاهر می‌شود که یک سؤال واحد به چندین ابزار نیاز داشته باشد. از عامل بپرسید «آب و هوای سیاتل به فارنهایت چقدر است؟» و عامل به طور خودکار دو ابزار را زنجیره می‌کند: ابتدا `getCurrentWeather` را برای دریافت دما به سلسیوس فراخوانی می‌کند، سپس مقدار را به `celsiusToFahrenheit` برای تبدیل می‌فرستد — همه در یک دور گفتگو. +**زنجیره‌سازی ابزارها** — قدرت واقعی عوامل مبتنی بر ابزار زمانی ظاهر می‌شود که یک سؤال واحد به چند ابزار نیاز داشته باشد. بپرسید «وضعیت هوا در سیاتل به فارنهایت چیست؟» و عامل به صورت خودکار دو ابزار را زنجیره می‌کند: ابتدا `getCurrentWeather` را برای گرفتن دما به سانتی‌گراد فراخوانی می‌کند، سپس آن مقدار را به `celsiusToFahrenheit` برای تبدیل می‌فرستد — همه در یک نوبت مکالمه. مثال زنجیره‌سازی ابزار -*زنجیره‌سازی ابزار در عمل — عامل ابتدا getCurrentWeather را فراخوانی می‌کند، سپس نتیجه سلسیوس را به celsiusToFahrenheit می‌دهد و پاسخ ترکیبی ارائه می‌دهد.* +*زنجیره‌سازی ابزار در عمل — عامل ابتدا getCurrentWeather را فراخوانی می‌کند، سپس نتیجه سانتی‌گراد را به celsiusToFahrenheit می‌فرستد و پاسخ ترکیبی ارائه می‌دهد.* -**شکست‌های آرام** — از ابزار درباره آب و هوا در شهری که در داده‌های شبیه‌سازی وجود ندارد بپرسید. ابزار پیام خطا بازمی‌گرداند و هوش مصنوعی به جای خراب شدن برنامه توضیح می‌دهد نمی‌تواند کمک کند. ابزارها به‌طور ایمن خطا می‌دهند. نمودار زیر دو رویکرد را نشان می‌دهد — با مدیریت خطای مناسب، عامل استثنا را گرفته و پاسخ مفیدی می‌دهد، در حالی که بدون آن کل برنامه کرش می‌کند: +**خطاهای بی‌دردسر** — برای هوای شهری که در داده‌های شبیه‌سازی نیست درخواست کنید. ابزار پیام خطا بازمی‌گرداند و هوش مصنوعی توضیح می‌دهد که نمی‌تواند کمک کند به جای اینکه برنامه کرش کند. ابزارها به طور ایمن خطا می‌دهند. نمودار زیر دو رویکرد را مقایسه می‌کند — با مدیریت صحیح خطا، عامل استثنا را گرفته و پاسخ کمک‌کننده می‌دهد، در حالی که بدون آن کل برنامه کرش می‌کند: -روند مدیریت خطا +جریان مدیریت خطا -*وقتی ابزار شکست می‌خورد، عامل خطا را گرفته و به جای کرش کردن، با توضیح مفید پاسخ می‌دهد.* +*وقتی ابزار شکست می‌خورد، عامل خطا را می‌گیرد و به جای کرش کردن، با توضیح مفید پاسخ می‌دهد.* -این اتفاق در یک دور گفتگو رخ می‌دهد. عامل به طور مستقل چندین فراخوانی ابزار را هماهنگ می‌کند. +این در یک نوبت مکالمه انجام می‌شود. عامل با خودکارسازی چند فراخوانی ابزار را هماهنگ می‌کند. ## اجرای برنامه -**تأیید استقرار:** +**اطمینان از استقرار:** -اطمینان حاصل کنید که فایل `.env` در دایرکتوری ریشه با اعتبارنامه‌های Azure وجود دارد (در ماژول ۰۱ ایجاد شده است). این دستور را از پوشه ماژول (`04-tools/`) اجرا کنید: +مطمئن شوید فایل `.env` در شاخه ریشه با اعتبارنامه‌های Azure وجود دارد (ایجاد شده در ماژول ۰۱). از دایرکتوری ماژول (`04-tools/`) این دستورات را اجرا کنید: -**Bash:** +**Bash:** ```bash -cat ../.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نمایش دهد +cat ../.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نشان دهد ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # باید AZURE_OPENAI_ENDPOINT ، API_KEY ، DEPLOYMENT را نمایش دهد +Get-Content ..\.env # باید AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT را نمایش دهد ``` - -**شروع برنامه:** +**راه‌اندازی برنامه:** -> **توجه:** اگر قبلاً همه برنامه‌ها را با استفاده از `./start-all.sh` از دایرکتوری ریشه (طبق ماژول ۰۱) اجرا کرده‌اید، این ماژول در پورت ۸۰۸۴ در حال اجراست. می‌توانید دستورات شروع را رد کرده و مستقیماً به http://localhost:8084 بروید. +> **توجه:** اگر قبلاً همه برنامه‌ها را با استفاده از `./start-all.sh` از ریشه (طبق ماژول ۰۱) راه‌اندازی کرده‌اید، این ماژول در حال حاضر بر روی پورت 8084 اجرا می‌شود. می‌توانید دستورهای شروع زیر را رد کنید و مستقیماً به http://localhost:8084 بروید. -**گزینه ۱: استفاده از داشبورد Spring Boot (توصیه شده برای کاربران VS Code)** +**گزینه ۱: استفاده از Spring Boot Dashboard (توصیه برای کاربران VS Code)** -کانتینر توسعه شامل افزونه داشبورد Spring Boot است که رابط بصری برای مدیریت همه برنامه‌های Spring Boot ارائه می‌دهد. این را در نوار فعالیت در سمت چپ VS Code (آیکون Spring Boot) پیدا کنید. +کانتینر توسعه شامل افزونه Spring Boot Dashboard است که رابط بصری برای مدیریت همه برنامه‌های Spring Boot فراهم می‌کند. می‌توانید آن را در نوار فعالیت سمت چپ VS Code (آیکون Spring Boot) پیدا کنید. -از داشبورد Spring Boot می‌توانید: -- همه برنامه‌های Spring Boot موجود در فضای کاری را ببینید -- برنامه‌ها را با یک کلیک شروع/توقف کنید -- لاگ‌های برنامه را به‌صورت زنده مشاهده کنید -- وضعیت برنامه را رصد کنید -به‌سادگی روی دکمه پخش کنار "ابزارها" کلیک کنید تا این ماژول شروع شود، یا همه ماژول‌ها را همزمان اجرا کنید. +از طریق Spring Boot Dashboard می‌توانید: +- همه برنامه‌های Spring Boot موجود در محیط کاری را ببینید +- برنامه‌ها را با یک کلیک شروع/توقف کنید +- لاگ‌های برنامه را به صورت زنده ببینید +- وضعیت برنامه را نظارت کنید -نمای داشبورد Spring Boot در VS Code به این صورت است: +به سادگی روی دکمه پخش کنار "tools" کلیک کنید تا این ماژول شروع شود، یا همه ماژول‌ها را همزمان اجرا کنید. -Spring Boot Dashboard +نمایی که داشبورد Spring Boot در VS Code دارد به شکل زیر است: +داشبورد Spring Boot -*داشبورد Spring Boot در VS Code — شروع، توقف و نظارت بر همه ماژول‌ها از یک محل* +*داشبورد Spring Boot در VS Code — شروع، توقف و نظارت روی همه ماژول‌ها از یک مکان* -**گزینه ۲: استفاده از اسکریپت‌های شل** +**گزینه ۲: استفاده از اسکریپت‌های شِل** -شروع همه برنامه‌های تحت وب (ماژول‌های ۰۱-۰۴): +همه برنامه‌های وب (ماژول‌های ۰۱-۰۴) را شروع کنید: **Bash:** ```bash @@ -244,7 +242,7 @@ cd .. # از دایرکتوری ریشه .\start-all.ps1 ``` -یا فقط همین ماژول را شروع کنید: +یا فقط این ماژول را شروع کنید: **Bash:** ```bash @@ -258,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -هر دو اسکریپت به صورت خودکار متغیرهای محیطی را از فایل ریشه `.env` بارگیری می‌کنند و در صورتی که فایل‌های JAR وجود نداشته باشند آن‌ها را می‌سازند. +هر دو اسکریپت به صورت خودکار متغیرهای محیطی را از فایل ریشه `.env` بارگذاری می‌کنند و در صورتی که فایل‌های JAR وجود نداشته باشند، آن‌ها را می‌سازند. -> **توجه:** اگر ترجیح می‌دهید همه ماژول‌ها را پیش از شروع به صورت دستی بسازید: +> **نکته:** اگر ترجیح می‌دهید قبل از شروع همه ماژول‌ها را به صورت دستی بسازید: > > **Bash:** > ```bash @@ -274,13 +272,13 @@ cd 04-tools > mvn clean package -DskipTests > ``` -در مرورگر خود به آدرس http://localhost:8084 بروید. +در مرورگر خود به آدرس http://localhost:8084 مراجعه کنید. **برای توقف:** **Bash:** ```bash -./stop.sh # فقط این ماژول +./stop.sh # این ماژول فقط # یا cd .. && ./stop-all.sh # همه ماژول‌ها ``` @@ -294,88 +292,88 @@ cd ..; .\stop-all.ps1 # همه ماژول‌ها ## استفاده از برنامه -این برنامه یک رابط وب فراهم می‌کند که می‌توانید با یک عامل هوش مصنوعی که به ابزارهای هواشناسی و تبدیل دما دسترسی دارد تعامل کنید. نمای رابط به این صورت است — که شامل مثال‌های شروع سریع و یک پنل چت برای ارسال درخواست‌ها است: +این برنامه یک رابط وب فراهم می‌کند که می‌توانید با یک عامل هوش مصنوعی که به ابزارهای آب‌وهوا و تبدیل دما دسترسی دارد، تعامل برقرار کنید. نمایی از رابط اینجا آمده است — شامل مثال‌های شروع سریع و پنل چت برای ارسال درخواست‌ها: -AI Agent Tools Interface +رابط ابزارهای عامل هوش مصنوعی *رابط ابزارهای عامل هوش مصنوعی - مثال‌های سریع و رابط چت برای تعامل با ابزارها* -### امتحان استفاده ساده از ابزار +### آزمایش استفاده ساده از ابزار -با یک درخواست ساده شروع کنید: "تبدیل ۱۰۰ درجه فارنهایت به سلسیوس". عامل تشخیص می‌دهد که باید از ابزار تبدیل دما استفاده کند، آن را با پارامترهای درست فراخوانی می‌کند و نتیجه را برمی‌گرداند. توجه کنید چقدر این کار طبیعی به نظر می‌رسد — مشخص نکردید از کدام ابزار استفاده کنید یا چطور آن را فراخوانی کنید. +با یک درخواست ساده شروع کنید: «100 درجه فارنهایت را به سلسیوس تبدیل کن». عامل تشخیص می‌دهد که باید از ابزار تبدیل دما استفاده کند، آن را با پارامترهای درست فراخوانی می‌کند و نتیجه را برمی‌گرداند. ببینید چقدر طبیعی است — شما مشخص نکردید کدام ابزار را استفاده کند یا چگونه آن را فراخوانی کنید. -### آزمایش زنجیر کردن ابزارها +### آزمایش زنجیره‌سازی ابزار -حالا چیزی پیچیده‌تر را امتحان کنید: "هوا در سیاتل چطور است و آن را به فارنهایت تبدیل کن؟" ببینید عامل چگونه این کار را مرحله به مرحله انجام می‌دهد. ابتدا هواشناسی را دریافت می‌کند (که دما را به سلسیوس برمی‌گرداند)، تشخیص می‌دهد باید آن را به فارنهایت تبدیل کند، ابزار تبدیل را فراخوانی می‌کند و سپس هر دو نتیجه را در یک پاسخ می‌آمیزد. +حالا یک درخواست پیچیده‌تر را امتحان کنید: «آب‌وهوا در سیاتل چطور است و آن را به فارنهایت تبدیل کن؟» مشاهده کنید که عامل به صورت مرحله به مرحله کار را انجام می‌دهد. ابتدا آب‌وهوا را دریافت می‌کند (که به سلسیوس است)، تشخیص می‌دهد که باید به فارنهایت تبدیل کند، ابزار تبدیل را فراخوانی می‌کند و هر دو نتیجه را در یک پاسخ ترکیب می‌کند. -### مشاهده جریان گفتگو +### مشاهده جریان مکالمه -رابط چت سابقه گفتگو را حفظ می‌کند و امکان تعامل چند مرحله‌ای را فراهم می‌آورد. می‌توانید تمام سوالات و پاسخ‌های قبلی را ببینید که پیگیری گفتگو و درک نحوه ساخت زمینه توسط عامل در چندین تبادل را آسان می‌کند. +رابط چت تاریخچه مکالمات را حفظ می‌کند و به شما اجازه می‌دهد تعامل‌های چندمرحله‌ای داشته باشید. می‌توانید تمام پرسش‌ها و پاسخ‌های قبلی را ببینید و دنبال کردن مکالمه و درک نحوه ساخت زمینه توسط عامل را ساده می‌کند. -Conversation with Multiple Tool Calls +مکالمه با چندین فراخوانی ابزار -*گفتگوی چند مرحله‌ای که تبدیل‌های ساده، جستجوی هوا و زنجیر کردن ابزارها را نشان می‌دهد* +*مکالمه چندمرحله‌ای شامل تبدیل‌های ساده، جستجوی آب‌وهوا و زنجیره‌سازی ابزار* ### آزمایش درخواست‌های مختلف -ترکیب‌های مختلف را امتحان کنید: -- جستجوی هوا: "هوا در توکیو چطور است؟" -- تبدیل دما: "۲۵ درجه سلسیوس چقدر در کلوین است؟" -- پرسش‌های ترکیبی: "هوا در پاریس را بررسی کن و بگو آیا بالای ۲۰ درجه سلسیوس است یا نه" +ترکیبات مختلف را امتحان کنید: +- جستجوی آب‌وهوا: «آب‌وهوا در توکیو چطور است؟» +- تبدیل دما: «25 درجه سلسیوس چند کلوین است؟» +- پرسش‌های ترکیبی: «آب‌وهوا در پاریس را بررسی کن و بگو اگر بالای 20 درجه سلسیوس است» -توجه کنید که عامل چگونه زبان طبیعی را تفسیر می‌کند و آن را به فراخوانی‌های مناسب ابزار نگاشت می‌کند. +توجه کنید که عامل چگونه زبان طبیعی را تعبیر می‌کند و آن را به فراخوانی‌های مناسب ابزار نگاشت می‌کند. ## مفاهیم کلیدی -### الگوی ReAct (استدلال و اقدام) +### الگوی ReAct (استدلال و عمل) -عامل بین استدلال (تصمیم‌گیری درباره کار بعدی) و اقدام (استفاده از ابزارها) تناوب دارد. این الگو امکان حل مستقل مسئله را فراهم می‌کند نه فقط پاسخ به دستورات. +عامل بین استدلال (تصمیم‌گیری در مورد کار بعدی) و عمل (استفاده از ابزارها) جابجا می‌شود. این الگو امکان حل خودکار مسئله را فراهم می‌کند، نه فقط پاسخ به دستورها. -### اهمیت توضیحات ابزارها +### توضیحات ابزار مهم است -کیفیت توضیحات ابزار شما مستقیماً بر نحوه استفاده عامل از آن‌ها تأثیر می‌گذارد. توضیح‌های واضح و مشخص به مدل کمک می‌کند بفهمد چه زمانی و چگونه باید هر ابزار را فراخوانی کند. +کیفیت توضیحات ابزار مستقیم روی نحوه استفاده بهتر عامل تأثیر می‌گذارد. توضیحات واضح و مشخص به مدل کمک می‌کند که چه موقع و چگونه هر ابزار را فراخوانی کند. -### مدیریت جلسه +### مدیریت نشست -حاشیه‌نویسی `@MemoryId` امکان مدیریت خودکار حافظه مبتنی بر جلسه را فعال می‌کند. هر شناسه جلسه یک نمونه `ChatMemory` مخصوص به خود را دارد که توسط مولفه `ChatMemoryProvider` مدیریت می‌شود، پس چندین کاربر می‌توانند همزمان با عامل تعامل داشته باشند بدون اینکه گفتگوهایشان با هم مخلوط شوند. نمودار زیر نشان می‌دهد چگونه چند کاربر به حافظه‌های مجزا بر اساس شناسه‌های جلسه ارجاع داده می‌شوند: +حاشیه‌نویسی `@MemoryId` امکان مدیریت حافظه مبتنی بر نشست را به صورت خودکار فراهم می‌کند. هر شناسه نشست یک نمونه `ChatMemory` منحصر به فرد دریافت می‌کند که توسط Bean `ChatMemoryProvider` مدیریت می‌شود، بنابراین چندین کاربر می‌توانند به طور همزمان با عامل تعامل داشته باشند بدون اینکه مکالماتشان با یکدیگر مخلوط شود. نمودار زیر نشان می‌دهد که چگونه چندین کاربر به فروشگاه‌های حافظه جداگانه بر اساس شناسه‌های نشستشان هدایت می‌شوند: -Session Management with @MemoryId +مدیریت نشست با @MemoryId -*هر شناسه جلسه به یک سابقه گفتگو ایزوله شده نگاشت می‌شود — کاربران هرگز پیام‌های همدیگر را نمی‌بینند.* +*هر شناسه نشست به یک تاریخچه مکالمه جداگانه نگاشت می‌شود — کاربران هرگز پیام‌های یکدیگر را نمی‌بینند.* ### مدیریت خطا -ابزارها ممکن است دچار خطا شوند — APIها تایم‌اوت کنند، پارامترها نامعتبر باشند، سرویس‌های خارجی قطع شوند. عوامل تولیدی به مدیریت خطا نیاز دارند تا مدل بتواند مشکلات را توضیح دهد یا جایگزین‌هایی را امتحان کند به جای اینکه کل برنامه خراب شود. وقتی ابزاری استثنا پرتاب می‌کند، LangChain4j آن را می‌گیرد و پیام خطا را به مدل برمی‌گرداند، که سپس می‌تواند مشکل را به زبان طبیعی توضیح دهد. +ابزارها ممکن است دچار خطا شوند — APIها ممکن است زمان‌تأخیر داشته باشند، پارامترها نادرست باشند، سرویس‌های خارجی ممکن است از کار بیفتند. عامل‌های تولید باید خطاها را مدیریت کنند تا مدل بتواند مشکلات را توضیح دهد یا جایگزین‌هایی امتحان کند، به جای اینکه کل برنامه کرش کند. وقتی یک ابزار استثنا پرتاب می‌کند، LangChain4j آن را گرفته و پیام خطا را به مدل بازمی‌گرداند که سپس می‌تواند مشکل را به زبان طبیعی توضیح دهد. -## ابزارهای موجود +## ابزارهای در دسترس -نمودار زیر اکوسیستم گسترده‌ای از ابزارها را که می‌توانید بسازید نشان می‌دهد. این ماژول ابزارهای هواشناسی و دمایی را نشان می‌دهد، اما همان الگوی `@Tool` برای هر متد جاوا قابل استفاده است — از پرس‌وجوهای پایگاه داده تا پردازش پرداخت. +نمودار زیر اکوسیستم گسترده ابزارهایی که می‌توانید بسازید را نشان می‌دهد. این ماژول ابزارهای آب‌وهوا و دما را نشان می‌دهد، اما همان الگوی `@Tool` برای هر متد جاوا کار می‌کند — از پرس‌وجوی دیتابیس تا پردازش پرداخت. -Tool Ecosystem +اکوسیستم ابزار -*هر متد جاوایی که با @Tool نشانه‌گذاری شود برای هوش مصنوعی در دسترس قرار می‌گیرد — این الگو شامل پایگاه داده‌ها، APIها، ایمیل، عملیات فایل و بیشتر می‌شود.* +*هر متد جاوا که با @Tool نشانه‌گذاری شده باشد برای هوش مصنوعی در دسترس قرار می‌گیرد — الگو به دیتابیس‌ها، APIها، ایمیل، عملیات فایل و بیشتر گسترش می‌یابد.* -## کی از عوامل مبتنی بر ابزار استفاده کنیم +## چه زمانی از عامل‌های مبتنی بر ابزار استفاده کنیم -هر درخواستی به ابزار نیاز ندارد. تصمیم‌گیری بستگی دارد به اینکه آیا هوش مصنوعی باید با سیستم‌های خارجی تعامل کند یا می‌تواند از دانش خود پاسخ دهد. راهنمای زیر خلاصه می‌کند چه مواقعی ابزارها ارزش افزوده دارند و چه مواقعی غیرضروری‌اند: +هر درخواستی به ابزار نیاز ندارد. تصمیم به این بستگی دارد که آیا AI باید با سیستم‌های خارجی تعامل داشته باشد یا بتواند از دانش خودش پاسخ دهد. راهنمای زیر خلاصه می‌کند که چه زمانی ابزارها ارزش افزوده دارند و چه زمانی ضروری نیستند: -When to Use Tools +چه زمانی از ابزارها استفاده کنیم -*راهنمای سریع تصمیم‌گیری — ابزارها برای داده‌های لحظه‌ای، محاسبات و کارها هستند؛ دانش عمومی و وظایف خلاقانه نیازی به آن‌ها ندارند.* +*راهنمای تصمیم‌گیری سریع — ابزارها برای داده‌های بلادرنگ، محاسبات و عملیات؛ دانش عمومی و کارهای خلاقانه نیاز به آن‌ها ندارند.* ## ابزارها در مقابل RAG -ماژول‌های ۰۳ و ۰۴ هر دو قابلیت‌های هوش مصنوعی را گسترش می‌دهند ولی به صورت بنیادی متفاوت. RAG به مدل دسترسی به **دانش** می‌دهد با بازیابی اسناد. ابزارها به مدل امکان انجام **عملیات** با فراخوانی توابع را می‌دهند. نمودار زیر این دو رویکرد را کنار هم مقایسه می‌کند — از نحوه عملکرد هر گردش کار تا مزایا و معایب آن‌ها: +ماژول‌های ۰۳ و ۰۴ هر دو قابلیت‌های AI را افزایش می‌دهند، اما به طور بنیادی متفاوت. RAG به مدل دسترسی به **دانش** را می‌دهد با بازخوانی اسناد. ابزارها به مدل امکان انجام **عملکردها** را با فراخوانی توابع می‌دهند. نمودار زیر این دو رویکرد را در کنار هم مقایسه می‌کند — از نحوه عملکرد هر جریان کاری تا مزایا و معایب آن‌ها: -Tools vs RAG Comparison +مقایسه ابزارها و RAG -*RAG اطلاعات را از اسناد ایستا بازیابی می‌کند — ابزارها عملیات اجرا و داده‌های پویا و لحظه‌ای را واکشی می‌کنند. بسیاری از سیستم‌های تولیدی هر دو را ترکیب می‌کنند.* +*RAG اطلاعات را از اسناد ایستا بازیابی می‌کند — ابزارها عملیات را انجام می‌دهند و داده‌های پویا و بلادرنگ را واکشی می‌کنند. بسیاری از سیستم‌های تولیدی هر دو را با هم ترکیب می‌کنند.* -در عمل، بسیاری از سیستم‌های تولیدی هر دو رویکرد را ترکیب می‌کنند: RAG برای پایه‌گذاری پاسخ‌ها در مستندات شما، و ابزارها برای واکشی داده‌های زنده یا انجام عملیات. +در عمل، بسیاری از سیستم‌های تولیدی هر دو رویکرد را ترکیب می‌کنند: RAG برای پایه‌گذاری پاسخ‌ها بر مستندات شما، و ابزارها برای واکشی داده‌های زنده یا انجام عملیات. -## گام‌های بعدی +## مراحل بعدی -**ماژول بعدی:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**ماژول بعدی:** [05-mcp - پروتکل زمینه مدل (MCP)](../05-mcp/README.md) --- @@ -384,6 +382,6 @@ cd ..; .\stop-all.ps1 # همه ماژول‌ها --- -**سلب مسئولیت**: -این سند با استفاده از خدمات ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است حاوی خطاها یا نواقصی باشند. سند اصلی به زبان بومی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئول هیچ گونه سوءتفاهم یا تفسیر نادرست ناشی از استفاده از این ترجمه نیستیم. +**سلب مسئولیت**: +این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم. \ No newline at end of file diff --git a/translations/fa/README.md b/translations/fa/README.md index 22fef4002..f9ff7b6de 100644 --- a/translations/fa/README.md +++ b/translations/fa/README.md @@ -2,18 +2,18 @@ # LangChain4j برای مبتدیان -یک دوره برای ساخت برنامه‌های هوش مصنوعی با LangChain4j و Azure OpenAI GPT-5.2، از چت پایه تا عامل‌های هوش مصنوعی. +دوره‌ای برای ساخت برنامه‌های هوش مصنوعی با LangChain4j و Azure OpenAI GPT-5.2، از چت پایه تا عوامل هوش مصنوعی. ### 🌐 پشتیبانی چندزبانه -#### پشتیبانی شده از طریق GitHub Action (خودکار و همیشه به‌روز) +#### پشتیبانی از طریق GitHub Action (خودکار و همیشه به‌روز) -[عربی](../ar/README.md) | [بنگالی](../bn/README.md) | [بلغاری](../bg/README.md) | [برمه‌ای (میانمار)](../my/README.md) | [چینی (ساده‌شده)](../zh-CN/README.md) | [چینی (سنتی، هنگ‌کنگ)](../zh-HK/README.md) | [چینی (سنتی، ماکائو)](../zh-MO/README.md) | [چینی (سنتی، تایوان)](../zh-TW/README.md) | [کرواسی](../hr/README.md) | [چک](../cs/README.md) | [دانمارکی](../da/README.md) | [هلندی](../nl/README.md) | [استونیایی](../et/README.md) | [فنلاندی](../fi/README.md) | [فرانسوی](../fr/README.md) | [آلمانی](../de/README.md) | [یونانی](../el/README.md) | [عبری](../he/README.md) | [هندی](../hi/README.md) | [مجارستانی](../hu/README.md) | [اندونزیایی](../id/README.md) | [ایتالیایی](../it/README.md) | [ژاپنی](../ja/README.md) | [کاننادا](../kn/README.md) | [خمر](../km/README.md) | [کره‌ای](../ko/README.md) | [لیتوانیایی](../lt/README.md) | [مالایی](../ms/README.md) | [مالایالام](../ml/README.md) | [مراتی](../mr/README.md) | [نپالی](../ne/README.md) | [پیجین نیجریه‌ای](../pcm/README.md) | [نروژی](../no/README.md) | [فارسی (Farsi)](./README.md) | [لهستانی](../pl/README.md) | [پرتغالی (برزیل)](../pt-BR/README.md) | [پرتغالی (پرتغال)](../pt-PT/README.md) | [پنجابی (Gurmukhi)](../pa/README.md) | [رومانیایی](../ro/README.md) | [روسی](../ru/README.md) | [صربی (سیریلیک)](../sr/README.md) | [اسلواکی](../sk/README.md) | [اسلوونی](../sl/README.md) | [اسپانیایی](../es/README.md) | [سواهدی](../sw/README.md) | [سوئدی](../sv/README.md) | [تاگالوگ (فیلیپینی)](../tl/README.md) | [تامیل](../ta/README.md) | [تلوگو](../te/README.md) | [تایلندی](../th/README.md) | [ترکی](../tr/README.md) | [اوکراینی](../uk/README.md) | [اردو](../ur/README.md) | [ویتنامی](../vi/README.md) +[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](./README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **ترجیح می‌دهید محلی کلون کنید؟** +> **ترجیح می‌دهید به صورت محلی کلون کنید؟** > -> این مخزن بیش از ۵۰ ترجمه زبان را شامل می‌شود که اندازه دانلود را به طور قابل توجهی افزایش می‌دهد. برای کلون کردن بدون ترجمه‌ها، از sparse checkout استفاده کنید: +> این مخزن شامل بیش از ۵۰ ترجمه زبانی است که حجم دانلود را به طور قابل توجهی افزایش می‌دهد. برای کلون بدون ترجمه‌ها، از sparse checkout استفاده کنید: > > **Bash / macOS / Linux:** > ```bash @@ -22,71 +22,70 @@ > git sparse-checkout set --no-cone '/*' '!translations' '!translated_images' > ``` > -> **CMD (ویندوز):** +> **CMD (Windows):** > ```cmd > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> این به شما همه چیز لازم برای تکمیل دوره را با سرعت دانلود بسیار بالاتر می‌دهد. +> این به شما همه چیز را می‌دهد تا دوره را با سرعت دانلود بسیار سریع‌تر به پایان برسانید. ## فهرست مطالب -1. [شروع سریع](00-quick-start/README.md) - شروع کار با LangChain4j -2. [مقدمه](01-introduction/README.md) - یادگیری اصول اولیه LangChain4j -3. [مهندسی پرامپت](02-prompt-engineering/README.md) - تسلط بر طراحی مؤثر پرامپت -4. [RAG (تولید تقویت‌شده با بازیابی)](03-rag/README.md) - ساخت سیستم‌های هوشمند مبتنی بر دانش -5. [ابزارها](04-tools/README.md) - یکپارچه‌سازی ابزارهای خارجی و دستیارهای ساده -6. [MCP (پروتکل زمینه مدل)](05-mcp/README.md) - کار با پروتکل زمینه مدل (MCP) و ماژول‌های عاملی +1. [مقدمه](01-introduction/README.md) - اصول اولیه LangChain4j را بیاموزید +2. [مهندسی پرامپت](02-prompt-engineering/README.md) - طراحی مؤثر پرامپت را فرا بگیرید +3. [RAG (تولید تکمیل‌شده با بازیابی)](03-rag/README.md) - ساخت سیستم‌های هوشمند مبتنی بر دانش +4. [ابزارها](04-tools/README.md) - ادغام ابزارهای خارجی و دستیارهای ساده +5. [MCP (پروتکل زمینه مدل)](05-mcp/README.md) - کار با پروتکل زمینه مدل (MCP) و ماژول‌های عامل -### مرورهای ویدیویی +### آموزش‌های ویدیویی -هر ماژول یک جلسه زنده همراه دارد که در آن مفاهیم و کد را گام به گام مرور می‌کنیم. +هر ماژول یک جلسه زنده همراه دارد که در آن مفاهیم و کد گام به گام آموزش داده می‌شود. -| ماژول | ویدئو | +| ماژول | ویدیو | |--------|-------| -| ۰۱ - مقدمه | [شروع با LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| ۰۱ - مقدمه | [شروع کار با LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | | ۰۲ - مهندسی پرامپت | [مهندسی پرامپت با LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | ۰۳ - RAG | [RAG با LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| ۰۴ - ابزارها و ۰۵ - MCP | [عامل‌های AI با ابزارها و MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| ۰۴ - ابزارها و ۰۵ - MCP | [عوامل هوش مصنوعی با ابزارها و MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## مسیر یادگیری -**جدید در LangChain4j؟** برای تعریف اصطلاحات و مفاهیم کلیدی به [واژه‌نامه](docs/GLOSSARY.md) مراجعه کنید. +**تازه‌کار در LangChain4j؟** برای تعریف اصطلاحات و مفاهیم کلیدی به [واژه‌نامه](docs/GLOSSARY.md) مراجعه کنید. > **شروع سریع** -1. این مخزن را به حساب گیت‌هاب خود فورک کنید -2. روی **Code** → تب **Codespaces** → روی **...** کلیک کنید → **New with options...** -3. پیش‌فرض‌ها را انتخاب کنید – این کانتینر توسعه ساخته شده برای این دوره را انتخاب می‌کند +1. این مخزن را به حساب GitHub خود فورک کنید +2. روی **Code** → برگه **Codespaces** → **...** → **New with options...** کلیک کنید +3. از تنظیمات پیش‌فرض استفاده کنید – این گزینه کانتینر توسعه ایجاد شده برای این دوره را انتخاب می‌کند 4. روی **Create codespace** کلیک کنید -5. ۵-۱۰ دقیقه صبر کنید تا محیط آماده شود -6. مستقیماً به [شروع سریع](./00-quick-start/README.md) بروید تا شروع کنید! +5. ۵ تا ۱۰ دقیقه منتظر بمانید تا محیط آماده شود +6. مستقیم به [مقدمه](./01-introduction/README.md) بروید و شروع کنید! -پس از تکمیل ماژول‌ها، راهنمای [تست](docs/TESTING.md) را بررسی کنید تا مفاهیم تست LangChain4j را در عمل ببینید. +پس از تکمیل ماژول‌ها، به [راهنمای تست](docs/TESTING.md) مراجعه کنید تا مفاهیم تست LangChain4j را در عمل مشاهده کنید. -> **توجه:** این آموزش هم از GitHub Models و هم Azure OpenAI استفاده می‌کند. ماژول [شروع سریع](00-quick-start/README.md) از GitHub Models استفاده می‌کند (نیازی به اشتراک Azure ندارد)، در حالی که ماژول‌های ۱ تا ۵ از Azure OpenAI بهره می‌برند. اگر حساب Azure ندارید، با [یک حساب رایگان Azure](https://aka.ms/azure-free-account) شروع کنید. +> **توجه:** این آموزش از Azure OpenAI استفاده می‌کند. اگر حساب Azure رایگان ندارید، با یک [حساب رایگان Azure](https://aka.ms/azure-free-account) شروع کنید. ## یادگیری با GitHub Copilot -برای شروع سریع کدنویسی، این پروژه را در GitHub Codespace یا IDE محلی خود با devcontainer ارائه شده باز کنید. devcontainer استفاده شده در این دوره به صورت پیش‌فرض با GitHub Copilot برای برنامه‌نویسی جفت هوش مصنوعی پیکربندی شده است. +برای شروع سریع برنامه‌نویسی، این پروژه را در GitHub Codespace یا IDE محلی خود با devcontainer ارائه شده باز کنید. devcontainer استفاده شده در این دوره از قبل با GitHub Copilot برای برنامه‌نویسی هوش مصنوعی همراه پیکربندی شده است. -هر نمونه کد شامل سؤالات پیشنهادی است که می‌توانید از GitHub Copilot بپرسید تا درک خود را عمیق‌تر کنید. به دنبال نشانه‌های 💡/🤖 در: +هر مثال کد شامل پرسش‌هایی است که می‌توانید از GitHub Copilot بپرسید تا فهم خود را عمیق‌تر کنید. به دنبال علامت‌های 💡/🤖 در: -- **سرفصل فایل‌های جاوا** - سؤال‌های خاص هر نمونه -- **README ماژول‌ها** - پیشنهادهای کاوش پس از نمونه‌های کد +- **سرصفحه فایل‌های جاوا** - سوالات خاص هر مثال +- **README ماژول‌ها** - پیشنهادهای کشف پس از مثال‌های کد -**نحوه استفاده:** هر فایل کد را باز کرده و سؤال‌های پیشنهادی را از Copilot بپرسید. او کاملاً از کد اطلاع دارد و می‌تواند توضیح دهد، گسترش دهد و جایگزین‌ها را پیشنهاد کند. +**نحوه استفاده:** هر فایل کد را باز کنید و سوالات پیشنهادی را از Copilot بپرسید. او کاملاً با کد آشنا است و می‌تواند توضیح دهد، گسترش دهد و پیشنهادهایی بدهد. -می‌خواهید بیشتر یاد بگیرید؟ به [Copilot برای برنامه‌نویسی جفت هوش مصنوعی](https://aka.ms/GitHubCopilotAI) مراجعه کنید. +می‌خواهید بیشتر یاد بگیرید؟ به [Copilot برای برنامه‌نویسی هوش مصنوعی همراه](https://aka.ms/GitHubCopilotAI) مراجعه کنید. -## منابع بیشتر +## منابع اضافی ### LangChain @@ -95,19 +94,19 @@ [![LangChain برای مبتدیان](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / عامل‌ها +### Azure / Edge / MCP / Agents [![AZD برای مبتدیان](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) [![Edge AI برای مبتدیان](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) [![MCP برای مبتدیان](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![عامل‌های AI برای مبتدیان](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI Agents برای مبتدیان](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### سری هوش تولیدی -[![هوش تولیدی برای مبتدیان](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![هوش تولیدی (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![هوش تولیدی (جاوا)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![هوش تولیدی (جاوااسکریپت)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### سری هوش مصنوعی مولد +[![هوش مصنوعی مولد برای مبتدیان](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![هوش مصنوعی مولد (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![هوش مصنوعی مولد (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![هوش مصنوعی مولد (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- @@ -117,34 +116,34 @@ [![هوش مصنوعی برای مبتدیان](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![امنیت سایبری برای مبتدیان](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) [![توسعه وب برای مبتدیان](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![اینترنت اشیاء برای مبتدیان](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![اینترنت اشیا برای مبتدیان](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![توسعه XR برای مبتدیان](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- - -### سری کوپایلوت -[![کوپایلوت برای برنامه‌نویسی جفتی هوش مصنوعی](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![کوپایلوت برای C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![ماجراجویی کوپایلوت](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) + +### مجموعه Copilot +[![کاپایلوت برای برنامه‌نویسی جفتی هوش مصنوعی](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![کاپایلوت برای C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![ماجراجویی کاپایلوت](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## دریافت کمک -اگر گیر افتادید یا سوالی درباره ساخت برنامه‌های هوش مصنوعی داشتید، بپیوندید به: +اگر به مشکلی برخوردید یا سوالی درباره ساخت برنامه‌های هوش مصنوعی داشتید، بپیوندید به: -[![دیسکورد Microsoft Foundry](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) +[![Discord انجمن Microsoft Foundry](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -اگر بازخورد یا خطایی در حین ساخت محصول داشتید، مراجعه کنید به: +اگر بازخورد محصول یا خطاهایی هنگام ساخت داشتید، مراجعه کنید به: -[![فروم توسعه‌دهندگان Microsoft Foundry](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) +[![انجمن توسعه‌دهندگان Microsoft Foundry GitHub](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## مجوز -مجوز MIT - برای جزئیات به فایل [LICENSE](../../LICENSE) مراجعه کنید. +مجوز MIT - جزئیات را در فایل [LICENSE](../../LICENSE) ببینید. --- -**سلب مسئولیت**: -این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما به دقت تلاش می‌کنیم، لطفاً آگاه باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. نسخه اصلی سند به زبان مادری آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما مسئول هیچ گونه سوءتفاهم یا برداشت نادرستی که از استفاده این ترجمه ناشی شود، نیستیم. +**سلب مسئولیت**: +این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم. \ No newline at end of file diff --git a/translations/fa/docs/GLOSSARY.md b/translations/fa/docs/GLOSSARY.md index c68d5404c..b48af3933 100644 --- a/translations/fa/docs/GLOSSARY.md +++ b/translations/fa/docs/GLOSSARY.md @@ -2,57 +2,57 @@ ## فهرست مطالب -- [مفاهیم اصلی](../../../docs) -- [اجزای LangChain4j](../../../docs) -- [مفاهیم هوش مصنوعی/یادگیری ماشینی](../../../docs) -- [Guardrails](../../../docs) -- [مهندسی درخواست](../../../docs) -- [RAG (تولید افزوده شده بازیابی)](../../../docs) -- [عامل‌ها و ابزارها](../../../docs) -- [ماژول عاملی](../../../docs) -- [پروتکل زمینه مدل (MCP)](../../../docs) -- [خدمات Azure](../../../docs) -- [آزمایش و توسعه](../../../docs) - -مرجع سریع برای اصطلاحات و مفاهیم استفاده شده در طول دوره. +- [مفاهیم اصلی](#مفاهیم-اصلی) +- [اجزای LangChain4j](#اجزای-langchain4j) +- [مفاهیم AI/ML](#مفاهیم-aiml) +- [محافظ‌ها](#محافظ‌ها) +- [مهندسی پرامپت](#prompt-engineering---module-02) +- [RAG (تولید افزوده شده با بازیابی)](#rag-retrieval-augmented-generation---module-03) +- [عامل‌ها و ابزارها](#agents-and-tools---module-04) +- [مدول عامل‌محور](#agentic-module---module-05) +- [پروتکل زمینه مدل (MCP)](#model-context-protocol-mcp---module-05) +- [خدمات Azure](#azure-services---module-01) +- [آزمایش و توسعه](#testing-and-development---testing-guide) + +مرجع سریع برای اصطلاحات و مفاهیم مورد استفاده در کل دوره. ## مفاهیم اصلی -**عامل هوش مصنوعی (AI Agent)** - سیستمی که از هوش مصنوعی برای استدلال و عمل به صورت خودمختار استفاده می‌کند. [ماژول 04](../04-tools/README.md) +**عامل هوش مصنوعی** - سیستمی که از هوش مصنوعی برای استدلال و عمل خودکار استفاده می‌کند. [ماژول ۰۴](../04-tools/README.md) -**زنجیره (Chain)** - دنباله‌ای از عملیات که خروجی مرحله قبلی ورودی مرحله بعدی است. +**زنجیره** - دنباله‌ای از عملیات که خروجی به مرحله بعدی منتقل می‌شود. -**تکه‌تکه کردن (Chunking)** - تقسیم اسناد به قطعات کوچکتر. معمولاً: ۳۰۰-۵۰۰ توکن با همپوشانی. [ماژول 03](../03-rag/README.md) +**تکه‌بندی** - تقسیم اسناد به قطعات کوچکتر. معمولاً: ۳۰۰-۵۰۰ توکن با همپوشانی. [ماژول ۰۳](../03-rag/README.md) -**پنجره زمینه (Context Window)** - حداکثر توکن‌هایی که مدل می‌تواند پردازش کند. GPT-5.2: ۴۰۰K توکن (تا ۲۷۲K ورودی، ۱۲۸K خروجی). +**پنجره زمینه** - حداکثر توکنی که مدل می‌تواند پردازش کند. GPT-5.2: ۴۰۰ هزار توکن (تا ۲۷۲ هزار ورودی، ۱۲۸ هزار خروجی). -**بردارها (Embeddings)** - بردارهای عددی که معنای متن را نمایش می‌دهند. [ماژول 03](../03-rag/README.md) +**بردارهای تعبیه** - بردارهای عددی که معنای متن را نشان می‌دهند. [ماژول ۰۳](../03-rag/README.md) -**فراخوانی تابع (Function Calling)** - مدلی که درخواست‌های ساختاریافته برای فراخوانی توابع خارجی تولید می‌کند. [ماژول 04](../04-tools/README.md) +**فراخوانی تابع** - مدل درخواست‌های ساختار یافته برای فراخوانی توابع خارجی تولید می‌کند. [ماژول ۰۴](../04-tools/README.md) -**توهم (Hallucination)** - زمانی که مدل‌ها اطلاعات نادرست اما محتمل تولید می‌کنند. +**توهم** - زمانی که مدل‌ها اطلاعات نادرست اما قابل قبول تولید می‌کنند. -**درخواست (Prompt)** - ورودی متنی به مدل زبانی. [ماژول 02](../02-prompt-engineering/README.md) +**پرامپت** - ورودی متنی به مدل زبانی. [ماژول ۰۲](../02-prompt-engineering/README.md) -**جستجوی معنایی (Semantic Search)** - جستجو بر اساس معنا با استفاده از بردارها، نه کلیدواژه‌ها. [ماژول 03](../03-rag/README.md) +**جستجوی معنایی** - جستجو بر اساس معنا با استفاده از بردارهای تعبیه، نه کلمات کلیدی. [ماژول ۰۳](../03-rag/README.md) -**حالت‌مند در مقابل بدون حالت (Stateful vs Stateless)** - بدون حالت: بدون حافظه. حالت‌مند: نگهداری تاریخچه مکالمه. [ماژول 01](../01-introduction/README.md) +**حالت بدون حفظ وضعیت در مقابل حفظ وضعیت** - بدون حفظ وضعیت: بدون حافظه. حفظ وضعیت: تاریخچه مکالمه را نگه می‌دارد. [ماژول ۰۱](../01-introduction/README.md) -**توکن‌ها (Tokens)** - واحدهای پایه متنی که مدل‌ها پردازش می‌کنند. تاثیرگذار بر هزینه‌ها و محدودیت‌ها. [ماژول 01](../01-introduction/README.md) +**توکن‌ها** - واحدهای متنی پایه که مدل‌ها پردازش می‌کنند. بر هزینه‌ها و محدودیت‌ها تأثیر می‌گذارد. [ماژول ۰۱](../01-introduction/README.md) -**زنجیره ابزار (Tool Chaining)** - اجرای متوالی ابزارها که خروجی مرحله قبلی به تماس بعدی اطلاع می‌دهد. [ماژول 04](../04-tools/README.md) +**زنجیره ابزار** - اجرای متوالی ابزارها که خروجی مرحله قبلی را برای مرحله بعدی استفاده می‌کند. [ماژول ۰۴](../04-tools/README.md) ## اجزای LangChain4j -**AiServices** - ایجاد رابط‌های خدمات هوش مصنوعی با نوع ایمن. +**AiServices** - ایجاد رابط‌های خدمات AI نوع ایمن. -**OpenAiOfficialChatModel** - کلاینت یکپارچه برای مدل‌های OpenAI و Azure OpenAI. +**OpenAiOfficialChatModel** - مشتری یکپارچه برای مدل‌های OpenAI و Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - ایجاد بردارها با استفاده از کلاینت رسمی OpenAI (پشتیبانی از هر دو OpenAI و Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - ایجاد بردارهای تعبیه با استفاده از مشتری رسمی OpenAI (پشتیبانی از OpenAI و Azure OpenAI). **ChatModel** - رابط اصلی برای مدل‌های زبانی. -**ChatMemory** - نگهداری تاریخچه مکالمه. +**ChatMemory** - حفظ تاریخچه مکالمه. **ContentRetriever** - یافتن قطعات مرتبط سند برای RAG. @@ -60,173 +60,171 @@ **EmbeddingModel** - تبدیل متن به بردارهای عددی. -**EmbeddingStore** - ذخیره و بازیابی بردارها. +**EmbeddingStore** - ذخیره و بازیابی بردارهای تعبیه. -**MessageWindowChatMemory** - نگهداری پنجره متحرک پیام‌های اخیر. +**MessageWindowChatMemory** - حفظ پنجره لغزنده‌ای از پیام‌های اخیر. -**PromptTemplate** - ایجاد درخواست‌های قابل استفاده مجدد با جایگزین‌های `{{variable}}`. +**PromptTemplate** - ایجاد پرامپت‌های قابل استفاده مجدد با جایگزین‌های `{{variable}}`. -**TextSegment** - قطعه متنی همراه با متادیتا. استفاده شده در RAG. +**TextSegment** - قطعه متنی با فراداده. در RAG استفاده می‌شود. -**ToolExecutionRequest** - نمایش درخواست اجرای ابزار. +**ToolExecutionRequest** - نمایانگر درخواست اجرای ابزار. -**UserMessage / AiMessage / SystemMessage** - انواع پیام‌های مکالمه. +**UserMessage / AiMessage / SystemMessage** - انواع پیام مکالمه. -## مفاهیم هوش مصنوعی/یادگیری ماشینی +## مفاهیم AI/ML -**یادگیری با نمونه‌های اندک (Few-Shot Learning)** - ارائه مثال‌ها در درخواست‌ها. [ماژول 02](../02-prompt-engineering/README.md) +**یادگیری با نمونه کم (Few-Shot Learning)** - ارائه نمونه‌ها در پرامپت‌ها. [ماژول ۰۲](../02-prompt-engineering/README.md) -**مدل زبانی بزرگ (LLM)** - مدل‌های هوش مصنوعی آموزش دیده روی داده‌های متنی بسیار زیاد. +**مدل زبانی بزرگ (LLM)** - مدل‌های AI آموزش دیده روی حجم زیادی از داده‌های متنی. -**تلاش استدلالی (Reasoning Effort)** - پارامتر GPT-5.2 برای کنترل عمق تفکر. [ماژول 02](../02-prompt-engineering/README.md) +**تلاش استدلالی** - پارامتری در GPT-5.2 که عمق تفکر را کنترل می‌کند. [ماژول ۰۲](../02-prompt-engineering/README.md) -**دمای خروجی (Temperature)** - کنترل تصادفی بودن خروجی. پایین=قابل پیش‌بینی، بالا=خلاقانه. +**دما (Temperature)** - کنترل تصادفی بودن خروجی. پایین = قطعی، بالا = خلاقانه. -**پایگاه داده برداری (Vector Database)** - پایگاه داده تخصصی برای بردارها. [ماژول 03](../03-rag/README.md) +**پایگاه داده برداری** - پایگاه داده تخصصی برای بردارهای تعبیه. [ماژول ۰۳](../03-rag/README.md) -**یادگیری بدون نمونه (Zero-Shot Learning)** - انجام کارها بدون ارائه مثال. [ماژول 02](../02-prompt-engineering/README.md) +**یادگیری بدون نمونه (Zero-Shot Learning)** - انجام وظایف بدون نمونه. [ماژول ۰۲](../02-prompt-engineering/README.md) -## Guardrails - [ماژول 00](../00-quick-start/README.md) +## محافظ‌ها -**دفاع چندلایه (Defense in Depth)** - رویکرد امنیتی با چند لایه که guardrails در سطح برنامه را با فیلترهای ایمنی ارائه دهنده ترکیب می‌کند. +**دفاع در عمق** - رویکرد امنیتی چندلایه که محافظ‌های در سطح برنامه را با فیلترهای ایمنی ارائه‌دهنده ترکیب می‌کند. -**بلاک سخت (Hard Block)** - ارائه دهنده در صورت تخلفات شدید محتوایی خطای HTTP 400 می‌دهد. +**مسدودسازی سخت** - ارائه‌دهنده خطای HTTP 400 برای نقض‌های جدی محتوا صادر می‌کند. -**InputGuardrail** - رابط LangChain4j برای اعتبارسنجی ورودی کاربر قبل از رسیدن به LLM. صرفه‌جویی در هزینه و تاخیر با مسدود کردن درخواست‌های مضر در مراحل اولیه. +**محافظ ورودی** - رابط LangChain4j برای اعتبارسنجی ورودی کاربر قبل از رسیدن به LLM. با مسدود کردن زودهنگام پرامپت‌های مضر، هزینه و تأخیر را کاهش می‌دهد. -**InputGuardrailResult** - نوع بازگشتی برای اعتبارسنجی guardrail: `success()` یا `fatal("reason")`. +**نتیجه محافظ ورودی** - نوع بازگشتی برای اعتبارسنجی محافظ: `success()` یا `fatal("reason")`. -**OutputGuardrail** - رابط برای اعتبارسنجی پاسخ‌های هوش مصنوعی پیش از بازگشت به کاربران. +**محافظ خروجی** - رابط برای اعتبارسنجی پاسخ‌های AI قبل از بازگشت به کاربران. -**فیلترهای ایمنی ارائه‌دهنده (Provider Safety Filters)** - فیلترهای محتوای درون‌ساخت ارائه‌دهندگان هوش مصنوعی (مانند GitHub Models) که تخلفات را در سطح API تشخیص می‌دهند. +**فیلترهای ایمنی ارائه‌دهنده** - فیلترهای محتوای داخلی از ارائه‌دهندگان هوش مصنوعی (مثلاً Azure OpenAI) که نقض‌ها را در سطح API می‌گیرند. -**رد خارج از چارچوب نرم (Soft Refusal)** - مدل با احترام از پاسخ دادن امتناع می‌کند بدون اینکه خطا دهد. +**رد نرم** - مدل به طور مودبانه از پاسخ دادن امتناع می‌کند بدون اینکه خطا بدهد. -## مهندسی درخواست - [ماژول 02](../02-prompt-engineering/README.md) +## مهندسی پرامپت - [ماژول ۰۲](../02-prompt-engineering/README.md) -**زنجیره تفکر (Chain-of-Thought)** - استدلال گام‌به‌گام برای دقت بهتر. +**زنجیره تفکر** - استدلال گام به گام برای دقت بهتر. -**خروجی محدود (Constrained Output)** - اعمال قالب یا ساختار مشخص. +**خروجی محدود شده** - اجبار به فرمت یا ساختار خاص. -**اشتیاق بالا (High Eagerness)** - الگوی GPT-5.2 برای استدلال کامل. +**اشتیاق زیاد** - الگوی GPT-5.2 برای استدلال کامل. -**اشتیاق پایین (Low Eagerness)** - الگوی GPT-5.2 برای پاسخ سریع. +**اشتیاق پایین** - الگوی GPT-5.2 برای پاسخ‌های سریع. -**مکالمه چند مرحله‌ای (Multi-Turn Conversation)** - حفظ زمینه در تبادل‌های متعدد. +**مکالمه چندنوبتی** - حفظ زمینه در تبادلات مختلف. -**درخواست با نقش (Role-Based Prompting)** - تعیین شخصیت مدل از طریق پیام‌های سیستمی. +**پرامپت نقش‌محور** - تنظیم شخصیت مدل از طریق پیام‌های سیستمی. -**خودبازبینی (Self-Reflection)** - مدل خروجی خود را ارزیابی و بهبود می‌بخشد. +**بازتاب خود** - مدل خروجی خود را ارزیابی و بهبود می‌بخشد. -**تحلیل ساختاری (Structured Analysis)** - چارچوب ارزیابی مشخص. +**تحلیل ساختاریافته** - چارچوب ارزیابی ثابت. -**الگوی اجرای وظیفه (Task Execution Pattern)** - برنامه‌ریزی → اجرا → خلاصه‌سازی. +**الگوی اجرای وظیفه** - برنامه‌ریزی → اجرا → خلاصه‌سازی. -## RAG (تولید افزوده شده بازیابی) - [ماژول 03](../03-rag/README.md) +## RAG (تولید افزوده شده با بازیابی) - [ماژول ۰۳](../03-rag/README.md) -**خط پردازش سند (Document Processing Pipeline)** - بارگیری → تکه تکه کردن → تعبیه → ذخیره. +**خط لوله پردازش سند** - بارگذاری → تکه‌بندی → تعبیه سازی → ذخیره. -**انبار بردار در حافظه (In-Memory Embedding Store)** - ذخیره‌سازی غیرپایدار برای آزمایش. +**ذخیره‌سازی تعبیه در حافظه** - ذخیره‌سازی غیر پایدار برای آزمایش. -**RAG** - ترکیب بازیابی با تولید برای اساس دادن پاسخ‌ها. +**RAG** - ترکیب بازیابی با تولید برای پاسخ‌های منطبق بر مستندات. -**امتیاز شباهت (Similarity Score)** - اندازه‌گیری (۰-۱) شباهت معنایی. +**امتیاز شباهت** - اندازه‌گیری (۰ تا ۱) شباهت معنایی. -**مرجع منبع (Source Reference)** - متادیتا درباره محتوای بازیابی شده. +**ارجاع منبع** - فراداده درباره محتوای بازیابی شده. -## عامل‌ها و ابزارها - [ماژول 04](../04-tools/README.md) +## عامل‌ها و ابزارها - [ماژول ۰۴](../04-tools/README.md) -**حاشیه‌نویسی @Tool** - علامت‌گذاری متدهای جاوا به عنوان ابزارهای قابل فراخوانی توسط هوش مصنوعی. +**@Tool Annotation** - علامت‌گذاری متدهای جاوا به عنوان ابزارهای قابل فراخوانی توسط AI. **الگوی ReAct** - استدلال → عمل → مشاهده → تکرار. -**مدیریت جلسه (Session Management)** - زمینه‌های جداگانه برای کاربران مختلف. +**مدیریت جلسه** - زمینه‌های جداگانه برای کاربران مختلف. -**ابزار (Tool)** - تابعی که یک عامل هوش مصنوعی می‌تواند آن را فراخوانی کند. +**ابزار** - تابعی که عامل AI می‌تواند فراخوانی کند. -**توضیح ابزار (Tool Description)** - مستندسازی هدف و پارامترهای ابزار. +**توضیح ابزار** - مستندسازی هدف و پارامترهای ابزار. -## ماژول عاملی - [ماژول 05](../05-mcp/README.md) +## مدول عامل‌محور - [ماژول ۰۵](../05-mcp/README.md) -**حاشیه‌نویسی @Agent** - علامت‌گذاری رابط‌ها به عنوان عوامل هوش مصنوعی با تعریف رفتار اظهاری. +**@Agent Annotation** - علامت‌گذاری رابط‌ها به عنوان عوامل AI با تعریف رفتاری اظهاری. -**شنونده عامل (Agent Listener)** - قلابی برای مانیتورینگ اجرای عامل via `beforeAgentInvocation()` و `afterAgentInvocation()`. +**شنونده عامل** - هوک برای نظارت بر اجرای عامل از طریق `beforeAgentInvocation()` و `afterAgentInvocation()`. -**حوزه عاملی (Agentic Scope)** - حافظه مشترکی که عوامل نتایج را با استفاده از `outputKey` ذخیره می‌کنند تا عوامل پایین‌دستی مصرف کنند. +**دامنه عاملی** - حافظه مشترکی که عوامل خروجی‌ها را با استفاده از `outputKey` ذخیره می‌کنند تا عوامل پایین‌دستی مصرف کنند. -**AgenticServices** - کارخانه‌ای برای ایجاد عوامل با استفاده از `agentBuilder()` و `supervisorBuilder()`. +**AgenticServices** - کارخانه برای ساخت عوامل با استفاده از `agentBuilder()` و `supervisorBuilder()`. -**جریان کاری شرطی (Conditional Workflow)** - مسیریابی بر اساس شرایط به عوامل متخصص مختلف. +**گردش کار شرطی** - مسیر دهی به عوامل متخصص مختلف بر اساس شرایط. -**انسان در حلقه (Human-in-the-Loop)** - الگوی جریان کاری افزودن نقاط کنترل انسانی برای تایید یا بازبینی محتوا. +**انسان در حلقه** - الگوی گردش کار که نقاط بررسی انسانی برای تایید یا بازبینی محتوا اضافه می‌کند. -**langchain4j-agentic** - وابستگی Maven برای ساخت عامل اظهاری (آزمایشی). +**langchain4j-agentic** - وابستگی مِیون برای ساخت عامل‌های اظهاری (آزمایشی). -**جریان کاری حلقه‌ای (Loop Workflow)** - تکرار اجرای عامل تا زمانی که شرطی برآورده شود (مثلاً امتیاز کیفیت ≥ ۰.۸). +**گردش کار حلقه‌ای** - اجرای مکرر عامل تا رسیدن به یک شرط (مثلاً امتیاز کیفیت ≥ ۰.۸). -**outputKey** - پارامتر حاشیه‌نویسی عامل که مشخص می‌کند نتایج کجا در حوزه عاملی ذخیره شوند. +**outputKey** - پارامتر علامت‌گذاری عامل که مشخص می‌کند نتایج کجا در دامنه عاملی ذخیره شوند. -**جریان کاری موازی (Parallel Workflow)** - اجرای همزمان چند عامل برای وظایف مستقل. +**گردش کار موازی** - اجرای چند عامل به طور همزمان برای وظایف مستقل. -**استراتژی پاسخ (Response Strategy)** - نحوه فرموله کردن پاسخ نهایی توسط سرپرست: LAST، SUMMARY یا SCORED. +**استراتژی پاسخ** - چگونگی فرمولاسیون پاسخ نهایی توسط ناظر: آخرین، خلاصه یا امتیازدهی شده. -**جریان کاری ترتیبی (Sequential Workflow)** - اجرای عوامل به ترتیبی که خروجی به مرحله بعدی منتقل شود. +**گردش کار ترتیبی** - اجرای عوامل به ترتیب که خروجی به مرحله بعدی انتقال می‌یابد. -**الگوی عامل سرپرست (Supervisor Agent Pattern)** - الگوی پیشرفته عاملی که در آن یک LLM سرپرست به صورت پویا تصمیم می‌گیرد کدام عوامل زیرمجموعه را فراخوانی کند. +**الگوی عامل ناظر** - الگوی پیشرفته عاملی که در آن یک LLM ناظر به طور پویا تصمیم می‌گیرد کدام زیرعامل‌ها را فراخوانی کند. -## پروتکل زمینه مدل (MCP) - [ماژول 05](../05-mcp/README.md) +## پروتکل زمینه مدل (MCP) - [ماژول ۰۵](../05-mcp/README.md) -**langchain4j-mcp** - وابستگی Maven برای ادغام MCP در LangChain4j. +**langchain4j-mcp** - وابستگی مِیون برای ادغام MCP در LangChain4j. -**MCP** - پروتکل زمینه مدل: استاندارد اتصال برنامه‌های هوش مصنوعی به ابزارهای خارجی. یک بار بساز، همه‌جا استفاده کن. +**MCP** - پروتکل زمینه مدل: استانداردی برای اتصال برنامه‌های AI به ابزارهای خارجی. یک بار بسازید، همه جا استفاده کنید. -**مشتری MCP (MCP Client)** - برنامه‌ای که به سرورهای MCP متصل می‌شود تا ابزارها را کشف و استفاده کند. +**مشتری MCP** - برنامه‌ای که به سرورهای MCP متصل می‌شود تا ابزارها را کشف و استفاده کند. -**سرور MCP (MCP Server)** - سرویس ارائه‌دهنده ابزارها از طریق MCP با توصیفات و اسکیمای پارامترهای شفاف. +**سرور MCP** - خدماتی که ابزارها را از طریق MCP با شرح‌های واضح و ساختار پارامترها ارائه می‌دهد. -**McpToolProvider** - جزء LangChain4j که ابزارهای MCP را برای استفاده در خدمات و عوامل هوش مصنوعی بسته‌بندی می‌کند. +**McpToolProvider** - جزء LangChain4j که ابزارهای MCP را برای استفاده در خدمات AI و عامل‌ها بسته‌بندی می‌کند. -**McpTransport** - رابط ارتباط MCP. پیاده‌سازی‌ها شامل Stdio و HTTP. +**McpTransport** - رابط برای ارتباط MCP. پیاده‌سازی‌ها شامل Stdio و HTTP است. -**انتقال Stdio** - انتقال محلی از طریق stdin/stdout. برای دسترسی به فایل‌سیستم یا ابزارهای خط فرمان مفید است. +**ترابری Stdio** - ترابری فرآیند محلی از طریق stdin/stdout. برای دسترسی به سیستم فایل یا ابزارهای خط فرمان مفید است. -**StdioMcpTransport** - پیاده‌سازی LangChain4j که سرور MCP را به صورت فرایند فرعی اجرا می‌کند. +**StdioMcpTransport** - پیاده‌سازی LangChain4j که سرور MCP را به عنوان زیرفرآیند اجرا می‌کند. -**کشف ابزار (Tool Discovery)** - مشتری از سرور درخواست فهرست ابزارهای موجود با توصیفات و اسکیمای پارامترها می‌کند. +**کشف ابزار** - مشتری از سرور درباره ابزارهای موجود با شرح‌ها و ساختارها پرس‌وجو می‌کند. -## خدمات Azure - [ماژول 01](../01-introduction/README.md) +## خدمات Azure - [ماژول ۰۱](../01-introduction/README.md) -**Azure AI Search** - جستجوی ابری با قابلیت‌های برداری. [ماژول 03](../03-rag/README.md) +**Azure AI Search** - جستجوی ابری با قابلیت‌های برداری. [ماژول ۰۳](../03-rag/README.md) -**Azure Developer CLI (azd)** - استقرار منابع Azure. +**Azure Developer CLI (azd)** - مستقرسازی منابع Azure. **Azure OpenAI** - سرویس هوش مصنوعی سازمانی مایکروسافت. -**Bicep** - زبان Infrastructure as Code برای Azure. [راهنمای زیرساخت](../01-introduction/infra/README.md) +**Bicep** - زبان زیرساخت به عنوان کد Azure. [راهنمای زیرساخت](../01-introduction/infra/README.md) -**نام استقرار (Deployment Name)** - نام برای استقرار مدل در Azure. +**نام مستقرسازی** - نام برای استقرار مدل در Azure. -**GPT-5.2** - جدیدترین مدل OpenAI با کنترل استدلال. [ماژول 02](../02-prompt-engineering/README.md) +**GPT-5.2** - جدیدترین مدل OpenAI با کنترل استدلالی. [ماژول ۰۲](../02-prompt-engineering/README.md) ## آزمایش و توسعه - [راهنمای آزمایش](TESTING.md) -**Dev Container** - محیط توسعه کانتینر شده. [پیکربندی](../../../.devcontainer/devcontainer.json) +**محیط توسعه کانتینری (Dev Container)** - محیط توسعه کانتینری. [پیکربندی](../../../.devcontainer/devcontainer.json) -**GitHub Models** - زمین بازی رایگان مدل‌های هوش مصنوعی. [ماژول 00](../00-quick-start/README.md) +**آزمایش در حافظه** - آزمایش با ذخیره‌سازی در حافظه. -**آزمایش در حافظه (In-Memory Testing)** - آزمایش با ذخیره‌سازی در حافظه. +**آزمایش یکپارچگی** - آزمایش با زیرساخت واقعی. -**آزمایش یکپارچه‌سازی (Integration Testing)** - آزمایش با زیرساخت واقعی. +**Maven** - ابزار ساخت اتوماتیک جاوا. -**Maven** - ابزار ساخت اتوماسیون جاوا. +**Mockito** - چارچوب ساخت اشیاء آزمایشی جاوا. -**Mockito** - چارچوب ماکینگ جاوا. - -**Spring Boot** - چارچوب برنامه‌نویسی جاوا. [ماژول 01](../01-introduction/README.md) +**Spring Boot** - چارچوب برنامه‌نویسی جاوا. [ماژول ۰۱](../01-introduction/README.md) --- -**سلب مسئولیت**: -این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما برای دقت تلاش می‌کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نا دقت‌هایی باشند. سند اصلی به زبان بومی خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا تفسیر نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم. +**سلب مسئولیت**: +این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم. \ No newline at end of file diff --git a/translations/fa/docs/TESTING.md b/translations/fa/docs/TESTING.md index 68c0fb4f8..553d51dfd 100644 --- a/translations/fa/docs/TESTING.md +++ b/translations/fa/docs/TESTING.md @@ -1,20 +1,20 @@ -# تست برنامه‌های LangChain4j +# آزمایش برنامه‌های LangChain4j ## فهرست مطالب -- [شروع سریع](../../../docs) -- [موضوعات پوشش داده شده در تست‌ها](../../../docs) -- [اجرای تست‌ها](../../../docs) -- [اجرای تست‌ها در VS Code](../../../docs) -- [الگوهای تست](../../../docs) -- [فلسفه تست](../../../docs) -- [گام‌های بعدی](../../../docs) +- [شروع سریع](#شروع-سریع) +- [محتوای آزمون‌ها](#محتوای-آزمون‌ها) +- [اجرای آزمون‌ها](#اجرای-آزمون‌ها) +- [اجرای آزمون‌ها در VS Code](#اجرای-آزمون‌ها-در-vs-code) +- [الگوهای آزمایشی](#الگوهای-آزمایشی) +- [فلسفه آزمایش](#فلسفه-آزمایش) +- [گام‌های بعدی](#گام‌های-بعدی) -این راهنما شما را با تست‌هایی آشنا می‌کند که نشان می‌دهند چگونه برنامه‌های هوش مصنوعی را بدون نیاز به کلیدهای API یا سرویس‌های خارجی تست کنید. +این راهنما شما را از طریق آزمون‌هایی که نشان می‌دهند چگونه برنامه‌های هوش مصنوعی را بدون نیاز به کلیدهای API یا سرویس‌های خارجی آزمایش کنید راهنمایی می‌کند. ## شروع سریع -تمام تست‌ها را با یک دستور اجرا کنید: +تمام آزمون‌ها را با یک دستور اجرا کنید: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -وقتی همه تست‌ها با موفقیت اجرا شدند، باید خروجی مانند تصویر زیر ببینید — تست‌ها بدون خطا اجرا شده‌اند. +وقتی همه آزمون‌ها با موفقیت گذشتند، باید خروجی شبیه به تصویر زیر ببینید — آزمون‌ها بدون هیچ شکست اجرا می‌شوند. -Successful Test Results +نتایج موفق آزمایش -*اجرای موفق تست‌ها که همه تست‌ها را بدون خطا نشان می‌دهد* +*اجرای موفقیت‌آمیز آزمون‌ها که نشان می‌دهد همه آزمون‌ها بدون شکست گذشتند* -## موضوعات پوشش داده شده در تست‌ها +## محتوای آزمون‌ها -این دوره بر **تست‌های واحد** که به صورت محلی اجرا می‌شوند تمرکز دارد. هر تست یک مفهوم خاص از LangChain4j را به صورت جداگانه نشان می‌دهد. هرم تست زیر محل قرارگیری تست‌های واحد را نشان می‌دهد — آنها پایه‌ای سریع و قابل اعتماد هستند که بقیه استراتژی تست شما بر اساس آن ساخته می‌شود. +این دوره بر روی **آزمون‌های واحد** که به صورت محلی اجرا می‌شوند تمرکز دارد. هر آزمون یک مفهوم خاص از LangChain4j را به طور مجزا نشان می‌دهد. هرم آزمایش زیر نشان می‌دهد که آزمون‌های واحد در کجا قرار می‌گیرند — آنها پایه سریع و قابل اعتمادی تشکیل می‌دهند که باقی استراتژی آزمون شما بر آن بنا می‌شود. -Testing Pyramid +هرم آزمایش -*هرم تست که تعادل بین تست‌های واحد (سریع، جداگانه)، تست‌های یکپارچه‌سازی (کامپوننت‌های واقعی) و تست‌های انتها-به-انتها را نشان می‌دهد. این آموزش بر تست واحد متمرکز است.* +*هرم آزمایش که تعادل بین آزمون‌های واحد (سریع، جدا شده)، آزمون‌های یکپارچه‌سازی (کامپوننت‌های واقعی) و آزمون‌های انتها به انتها را نشان می‌دهد. این آموزش پوشش‌دهنده آزمون واحد است.* -| ماژول | تست‌ها | محور تمرکز | فایل‌های کلیدی | +| ماژول | آزمون‌ها | تمرکز | فایل‌های کلیدی | |--------|-------|-------|-----------| -| **00 - شروع سریع** | 6 | قالب‌های پرسش و جایگزینی متغیرها | `SimpleQuickStartTest.java` | -| **01 - معرفی** | 8 | حافظه مکالمه و چت حالت‌مند | `SimpleConversationTest.java` | -| **02 - مهندسی پرسش** | 12 | الگوهای GPT-5.2، سطوح اشتیاق، خروجی ساختاریافته | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | دریافت اسناد، تعبیه‌ها، جستجوی مشابهت | `DocumentServiceTest.java` | -| **04 - ابزارها** | 12 | فراخوانی تابع و زنجیره‌سازی ابزارها | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | پروتکل زمینه مدل با انتقال stdio | `SimpleMcpTest.java` | +| **۰۱ - مقدمه** | ۸ | حافظه مکالمه و چت حالت‌دار | `SimpleConversationTest.java` | +| **۰۲ - مهندسی پرس‌وجو** | ۱۲ | الگوهای GPT-5.2، سطوح اشتیاق، خروجی ساخت‌یافته | `SimpleGpt5PromptTest.java` | +| **۰۳ - RAG** | ۱۰ | وارد کردن سند، جاسازی‌ها، جستجوی مشابهت | `DocumentServiceTest.java` | +| **۰۴ - ابزارها** | ۱۲ | فراخوانی توابع و زنجیره ابزارها | `SimpleToolsTest.java` | +| **۰۵ - MCP** | ۸ | پروتکل زمینه مدل با انتقال stdio | `SimpleMcpTest.java` | -## اجرای تست‌ها +## اجرای آزمون‌ها -**اجرای همه تست‌ها از ریشه:** +**اجرای همه آزمون‌ها از ریشه پروژه:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**اجرای تست‌های یک ماژول خاص:** +**اجرای آزمون‌ها برای یک ماژول خاص:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**اجرای یک کلاس تست خاص:** +**اجرای یک کلاس آزمون واحد:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**اجرای یک متد تست مشخص:** +**اجرای یک متد آزمون مشخص:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#باید سابقه مکالمه را حفظ کند +mvn test -Dtest=SimpleConversationTest#باید تاریخچه‌ی گفتگو حفظ شود ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#آیا باید سابقه گفتگو حفظ شود؟ +mvn --% test -Dtest=SimpleConversationTest#باید تاریخچه مکالمه حفظ شود ``` -## اجرای تست‌ها در VS Code +## اجرای آزمون‌ها در VS Code -اگر از Visual Studio Code استفاده می‌کنید، Test Explorer یک رابط گرافیکی برای اجرای تست‌ها و اشکال‌زدایی ارائه می‌دهد. +اگر از Visual Studio Code استفاده می‌کنید، Test Explorer یک رابط گرافیکی برای اجرای و دیباگ کردن آزمون‌ها فراهم می‌کند. -VS Code Test Explorer +کاوشگر آزمون VS Code -*Test Explorer در VS Code درخت تست‌ها را با همه کلاس‌های تست جاوا و متدهای تست جداگانه نشان می‌دهد* +*کاوشگر آزمون VS Code که درخت آزمون را با تمام کلاس‌های آزمون جاوا و متدهای آزمون فردی نشان می‌دهد* -**برای اجرای تست‌ها در VS Code:** +**برای اجرای آزمون‌ها در VS Code:** -1. تست اکسپلورر را با کلیک بر روی آیکون ارلن آزمایش در نوار فعالیت باز کنید -2. درخت تست را گسترش دهید تا همه ماژول‌ها و کلاس‌های تست را ببینید -3. روی دکمه پخش کنار هر تست کلیک کنید تا به صورت جداگانه اجرا شود +1. با کلیک روی آیکون ارلنما در نوار فعالیت (Activity Bar) کاوشگر آزمون را باز کنید +2. درخت آزمون را باز کنید تا همه ماژول‌ها و کلاس‌های آزمون را ببینید +3. روی دکمه پخش کنار هر آزمون کلیک کنید تا فقط آن را اجرا کنید 4. روی "Run All Tests" کلیک کنید تا کل مجموعه اجرا شود -5. روی هر تست راست‌کلیک کنید و "Debug Test" را انتخاب کنید تا نقاط قطع تنظیم و کد مرحله‌به‌مرحله اجرا شود +5. روی هر آزمون راست‌کلیک کرده و "Debug Test" را انتخاب کنید تا نقاط توقف تنظیم و مرحله‌ای کد را بررسی کنید -Test Explorer تیک‌های سبز برای تست‌های موفق نشان می‌دهد و پیام‌های خطای دقیق را در زمان شکست تست‌ها ارائه می‌دهد. +کاوشگر آزمون علامت‌های تیک سبز برای آزمون‌های موفق و پیام‌های شکست دقیق هنگام ناموفق بودن آزمون‌ها را نشان می‌دهد. -## الگوهای تست +## الگوهای آزمایشی -### الگو ۱: تست قالب پرسش‌ها +### الگو ۱: آزمایش قالب‌های پرس‌وجو -ساده‌ترین الگو قالب پرسش‌ها را بدون فراخوانی هیچ مدل هوش مصنوعی تست می‌کند. شما می‌سنجید که جایگزینی متغیرها به درستی انجام شده و قالب‌ها طبق انتظار فرمت شده‌اند. +ساده‌ترین الگو قالب‌های پرس‌وجو را بدون فراخوانی هیچ مدل هوش مصنوعی آزمایش می‌کند. شما صحت جایگزینی متغیرها را بررسی می‌کنید و اطمینان می‌یابید که قالب‌ها به درستی قالب‌بندی شده‌اند. -Prompt Template Testing +آزمایش قالب پرس‌وجو -*تست قالب‌های پرسش که جریان جایگزینی متغیرها را نشان می‌دهد: قالب با مکان‌نماها → مقادیر اعمال شده → خروجی فرمت شده تأیید شده* +*آزمایش قالب‌های پرس‌وجو که جریان جایگزینی متغیرها را نشان می‌دهد: قالب با مکان‌نماها → مقادیر اعمال شده → خروجی قالب‌بندی شده تأیید شده* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -این تست در `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` قرار دارد. +این الگو تأیید می‌کند که جایگزینی متغیرها به درستی انجام شده و قالب‌ها به شکل مورد انتظار قالب‌بندی شده‌اند — نیازی به کلید API یا فراخوانی مدل نیست. -**برای اجرا:** +### الگو ۲: ایجاد مدل‌های زبان جعلی (Mocking) -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#قالب‌بندی الگوی درخواست آزمایشی -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#قالب‌بندی آزمون الگوخواسته -``` - -### الگو ۲: شبیه‌سازی مدل‌های زبانی - -در تست منطق مکالمه، از Mockito برای ساخت مدل‌های جعلی استفاده کنید که پاسخ‌های از پیش تعیین‌شده برمی‌گردانند. این موجب سرعت، رایگان بودن و قطعی بودن تست‌ها می‌شود. +هنگام آزمایش منطق مکالمه، از Mockito برای ساخت مدل‌های جعلی استفاده کنید که پاسخ‌های از پیش تعیین شده را برمی‌گردانند. این باعث می‌شود آزمون‌ها سریع، رایگان و قطعی باشند. -Mock vs Real API Comparison +مقایسه جعلی و واقعی API -*مقایسه‌ای که نشان می‌دهد چرا شبیه‌سازی‌ها برای تست ترجیح داده می‌شوند: سریع، رایگان، قطعی و بدون نیاز به کلیدهای API هستند* +*مقایسه‌ای که چرا مدل‌های جعلی برای آزمایش ترجیح داده می‌شوند: سریع، رایگان، قطعی و بدون نیاز به کلید API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -این الگو در `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` ظاهر می‌شود. شبیه‌سازی رفتار یکسان را تضمین می‌کند تا بتوانید مدیریت حافظه را به درستی تأیید کنید. +این الگو در فایل `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` ظاهر می‌شود. مدل جعلی رفتار یکنواخت را تضمین می‌کند تا بتوانید مدیریت حافظه را به درستی بررسی کنید. -### الگو ۳: تست جداسازی مکالمه +### الگو ۳: آزمایش جداسازی مکالمه -حافظه مکالمه باید کاربران مختلف را جدا نگه دارد. این تست تأیید می‌کند که مکالمات زمینه‌ها را مخلوط نمی‌کنند. +حافظه مکالمه باید چندین کاربر را جدا نگه دارد. این آزمون تأیید می‌کند که مکالمات زمینه‌ها را مخلوط نمی‌کنند. -Conversation Isolation +جداسازی مکالمه -*تست جداسازی مکالمه که فروشگاه‌های حافظه جداگانه برای کاربران مختلف برای جلوگیری از مخلوط شدن زمینه‌ها را نشان می‌دهد* +*آزمایش جداسازی مکالمه که نشان‌دهنده نگهداری حافظه جداگانه برای کاربران مختلف برای جلوگیری از مخلوط شدن زمینه‌ها است* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -هر مکالمه تاریخچه مستقل خود را حفظ می‌کند. در سیستم‌های تولید، این جداسازی برای برنامه‌های چند کاربره حیاتی است. +هر مکالمه تاریخچه مستقل خود را حفظ می‌کند. در سیستم‌های تولید، این جداسازی برای برنامه‌های چندکاربره حیاتی است. -### الگو ۴: تست ابزارها به صورت مستقل +### الگو ۴: آزمایش مستقل ابزارها -ابزارها توابعی هستند که هوش مصنوعی می‌تواند فراخوانی کند. آنها را به صورت مستقیم تست کنید تا مطمئن شوید فارغ از تصمیمات هوش مصنوعی درست کار می‌کنند. +ابزارها توابعی هستند که هوش مصنوعی می‌تواند فراخوانی کند. آنها را مستقیماً آزمایش کنید تا اطمینان حاصل شود که بدون توجه به تصمیمات هوش مصنوعی به درستی کار می‌کنند. -Tools Testing +آزمایش ابزارها -*تست ابزارها به صورت مستقل که اجرای ابزارهای شبیه‌سازی‌شده بدون فراخوانی هوش مصنوعی را برای تأیید منطق کسب‌وکار نشان می‌دهد* +*آزمایش مستقل ابزارها که اجرای ابزارهای جعلی بدون فراخوانی هوش مصنوعی را نشان می‌دهد تا منطق کسب‌وکار تحقق یابد* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -این تست‌ها از `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` منطق ابزار را بدون دخالت هوش مصنوعی اعتبارسنجی می‌کنند. مثال زنجیره‌سازی نشان می‌دهد چگونه خروجی ابزار یک ورودی برای دیگری است. +این آزمایش‌ها از `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` منطق ابزار را بدون دخالت هوش مصنوعی اعتبارسنجی می‌کنند. نمونه زنجیره‌ای نشان می‌دهد چگونه خروجی یک ابزار به ورودی ابزار دیگر می‌رود. -### الگو ۵: تست RAG در حافظه +### الگو ۵: آزمایش RAG در حافظه -سیستم‌های RAG معمولاً به پایگاه داده‌های برداری و سرویس‌های تعبیه نیاز دارند. الگوی درون حافظه اجازه می‌دهد کل خط لوله بدون وابستگی‌های خارجی تست شود. +سیستم‌های RAG معمولاً به پایگاه داده‌های برداری و خدمات جاسازی نیاز دارند. الگوی درون حافظه اجازه می‌دهد کل زنجیره بدون وابستگی خارجی آزمایش شود. -In-Memory RAG Testing +آزمایش RAG در حافظه -*روند تست RAG در حافظه که تجزیه سند، ذخیره تعبیه‌ها و جستجوی مشابهت را بدون نیاز به پایگاه داده نشان می‌دهد* +*فرآیند آزمایشی RAG در حافظه که پارس کردن سند، ذخیره جاسازی و جستجوی مشابهت را بدون نیاز به پایگاه داده نشان می‌دهد* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -این تست از `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` سندی را در حافظه ایجاد می‌کند و تجزیه بخش‌بندی و مدیریت متادیتا را تأیید می‌کند. +این آزمون از `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` یک سند در حافظه ایجاد می‌کند و قطعه‌بندی و مدیریت متادیتا را بررسی می‌کند. -### الگو ۶: تست یکپارچه‌سازی MCP +### الگو ۶: آزمایش یکپارچه‌سازی MCP -ماژول MCP تست پروتکل زمینه مدل را با استفاده از انتقال stdio انجام می‌دهد. این تست‌ها اطمینان می‌دهند که برنامه شما می‌تواند سرورهای MCP را به عنوان زیرفرآیند اجرا و با آنها ارتباط برقرار کند. +ماژول MCP آزمایش یکپارچه‌سازی پروتکل زمینه مدل را با انتقال stdio انجام می‌دهد. این آزمایش‌ها اطمینان می‌دهند که برنامه شما می‌تواند سرورهای MCP را به صورت زیرفرآیند ایجاد و با آنها ارتباط برقرار کند. -تست‌ها در `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` رفتار کلاینت MCP را اعتبارسنجی می‌کنند. +آزمون‌ها در `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` رفتار کلاینت MCP را اعتبارسنجی می‌کنند. -**برای اجرا:** +**اجرایشان کنید:** **Bash:** ```bash @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## فلسفه تست +## فلسفه آزمایش -کد خود را تست کنید، نه هوش مصنوعی را. تست‌های شما باید کدی را که می‌نویسید با بررسی نحوه ساخت پرسش‌ها، مدیریت حافظه و اجرای ابزارها اعتبارسنجی کنند. پاسخ‌های هوش مصنوعی متفاوت هستند و نباید بخشی از تأییدیه‌های تست باشند. از خود بپرسید آیا قالب پرسش شما متغیرها را به درستی جایگزین می‌کند، نه اینکه آیا هوش مصنوعی پاسخ درست می‌دهد. +کد خود را آزمایش کنید، نه هوش مصنوعی را. آزمون‌های شما باید کدی که می‌نویسید را با بررسی نحوه ساخت پرس‌وجوها، مدیریت حافظه و اجرای ابزارها اعتبارسنجی کنند. پاسخ‌های هوش مصنوعی متغیر هستند و نباید جزو تأییدیه‌های آزمون باشند. از خود بپرسید آیا قالب پرس‌وجوی شما به درستی جایگزین متغیرها را انجام می‌دهد، نه اینکه آیا پاسخ هوش مصنوعی درست است. -از شبیه‌سازی‌ها برای مدل‌های زبانی استفاده کنید. آنها وابستگی‌های خارجی هستند که کند، گران و غیرقطعی هستند. شبیه‌سازی تست‌ها را سریع با میلی‌ثانیه به جای ثانیه، رایگان بدون هزینه API و قطعی با همان نتیجه در هر بار اجرا می‌کند. +از مدل‌های جعلی برای مدل‌های زبان استفاده کنید. آنها وابستگی‌های خارجی هستند که کند، پرهزینه و غیرقطعی‌اند. استفاده از جعلی‌ها باعث می‌شود آزمون‌ها سریع (با میلی‌ثانیه به جای ثانیه)، رایگان (بدون هزینه API) و قطعی (همیشه نتیجه یکسان) باشند. -تست‌ها را مستقل نگه دارید. هر تست باید داده‌های خودش را راه‌اندازی کند، به تست‌های دیگر وابسته نباشد و پس از اجرا پاکسازی کند. تست‌ها باید فارغ از ترتیب اجرا پذیرفته شوند. +آزمون‌ها را مستقل نگه دارید. هر آزمون باید داده‌های خود را تنظیم کند، به آزمون‌های دیگر وابسته نباشد و پس از اجرا پاک‌سازی کند. آزمون‌ها باید صرف‌نظر از ترتیب اجرا، موفق باشند. -موارد حاشیه‌ای فراتر از مسیر خوشحال را تست کنید. ورودی‌های خالی، خیلی بزرگ، کاراکترهای خاص، پارامترهای نامعتبر و شرایط مرزی را امتحان کنید. این موارد اغلب خطاهایی را نشان می‌دهند که استفاده عادی نشان نمی‌دهد. +موارد حاشیه‌ای را فراتر از مسیر خوش‌آیند آزمایش کنید. ورودی‌های خالی، ورودی‌های بسیار بزرگ، کاراکترهای خاص، پارامترهای نامعتبر و شرایط مرزی را امتحان کنید. این موارد اغلب باگ‌هایی را آشکار می‌کنند که استفاده معمولی نشان نمی‌دهد. -از نام‌های توصیفی استفاده کنید. مقایسه کنید `shouldMaintainConversationHistoryAcrossMultipleMessages()` با `test1()`. اولی دقیقا می‌گوید چه چیزی تست می‌شود و عیب‌یابی خطاها را بسیار آسان می‌کند. +از نام‌های توصیفی استفاده کنید. مقایسه کنید `shouldMaintainConversationHistoryAcrossMultipleMessages()` با `test1()` را. نام اول دقیقاً توضیح می‌دهد چه چیزی آزمایش می‌شود و اشکال‌زدایی شکست‌ها را بسیار آسان‌تر می‌کند. ## گام‌های بعدی -حالا که الگوهای تست را درک کردید، به صورت عمیق‌تر به هر ماژول بپردازید: +حال که الگوهای آزمایشی را فهمیده‌اید، عمیق‌تر به هر ماژول بپردازید: -- **[00 - شروع سریع](../00-quick-start/README.md)** - شروع با اصول قالب پرسش -- **[01 - معرفی](../01-introduction/README.md)** - یادگیری مدیریت حافظه مکالمه -- **[02 - مهندسی پرسش](../02/prompt-engineering/README.md)** - تسلط بر الگوهای GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - ساخت سیستم‌های تولید تکمیل شده با بازیابی -- **[04 - ابزارها](../04-tools/README.md)** - پیاده‌سازی فراخوانی توابع و زنجیره ابزارها -- **[05 - MCP](../05-mcp/README.md)** - یکپارچه‌سازی پروتکل زمینه مدل +- **[۰۱ - مقدمه](../01-introduction/README.md)** - یادگیری مدیریت حافظه مکالمه +- **[۰۲ - مهندسی پرس‌وجو](../02-prompt-engineering/README.md)** - تسلط بر الگوهای پرس‌وجوی GPT-5.2 +- **[۰۳ - RAG](../03-rag/README.md)** - ساخت سیستم‌های تولید افزوده بازیابی شده +- **[۰۴ - ابزارها](../04-tools/README.md)** - پیاده‌سازی فراخوانی توابع و زنجیره ابزارها +- **[۰۵ - MCP](../05-mcp/README.md)** - یکپارچه‌سازی پروتکل زمینه مدل -README هر ماژول توضیحات مفصل مفاهیم تست شده در اینجا را ارائه می‌دهد. +README هر ماژول توضیحات دقیقی از مفاهیم آزمون شده در اینجا ارائه می‌دهد. --- -**ناوبری:** [← بازگشت به اصلی](../README.md) +**گردش در سند:** [← بازگشت به اصلی](../README.md) --- -**توضیح مسئولیت**: -این سند با استفاده از سرویس ترجمه ماشینی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نواقصی باشند. سند اصلی به زبان مادری آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، ترجمه حرفه‌ای توسط انسان توصیه می‌شود. ما در قبال هر گونه سوءتفاهم یا تفسیر نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم. +**سلب مسئولیت**: +این سند با استفاده از سرویس ترجمه هوش مصنوعی [Co-op Translator](https://github.com/Azure/co-op-translator) ترجمه شده است. در حالی که ما در تلاش برای دقت هستیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌هایی باشند. سند اصلی به زبان مادری خود باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حیاتی، ترجمه حرفه‌ای انسانی توصیه می‌شود. ما در قبال هرگونه سوء تفاهم یا برداشت نادرست ناشی از استفاده از این ترجمه مسئولیتی نداریم. \ No newline at end of file diff --git a/translations/fi/.co-op-translator.json b/translations/fi/.co-op-translator.json index ff9ecc939..933f94346 100644 --- a/translations/fi/.co-op-translator.json +++ b/translations/fi/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "fi" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T23:35:27+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T12:23:30+00:00", "source_file": "01-introduction/README.md", "language_code": "fi" }, @@ -18,20 +18,20 @@ "language_code": "fi" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T23:37:47+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T12:18:23+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "fi" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T23:39:22+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T12:22:35+00:00", "source_file": "03-rag/README.md", "language_code": "fi" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:25:43+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T12:21:07+00:00", "source_file": "04-tools/README.md", "language_code": "fi" }, @@ -54,8 +54,8 @@ "language_code": "fi" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:08:42+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T12:16:45+00:00", "source_file": "README.md", "language_code": "fi" }, @@ -72,14 +72,14 @@ "language_code": "fi" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T23:42:46+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T12:19:01+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "fi" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T23:43:32+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T12:19:43+00:00", "source_file": "docs/TESTING.md", "language_code": "fi" } diff --git a/translations/fi/00-quick-start/README.md b/translations/fi/00-quick-start/README.md deleted file mode 100644 index 1b2d14cd0..000000000 --- a/translations/fi/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Quick Start - -## Table of Contents - -- [Introduction](../../../00-quick-start) -- [What is LangChain4j?](../../../00-quick-start) -- [LangChain4j Dependencies](../../../00-quick-start) -- [Prerequisites](../../../00-quick-start) -- [Setup](../../../00-quick-start) - - [1. Get Your GitHub Token](../../../00-quick-start) - - [2. Set Your Token](../../../00-quick-start) -- [Run the Examples](../../../00-quick-start) - - [1. Basic Chat](../../../00-quick-start) - - [2. Prompt Patterns](../../../00-quick-start) - - [3. Function Calling](../../../00-quick-start) - - [4. Document Q&A (Easy RAG)](../../../00-quick-start) - - [5. Responsible AI](../../../00-quick-start) -- [What Each Example Shows](../../../00-quick-start) -- [Next Steps](../../../00-quick-start) -- [Troubleshooting](../../../00-quick-start) - -## Introduction - -Tämä pikaopas on tarkoitettu saamaan sinut nopeasti käyntiin LangChain4j:n kanssa. Se kattaa AI-sovellusten rakentamisen aivan perusteet LangChain4j:n ja GitHub-mallien avulla. Seuraavissa moduuleissa siirryt Azure OpenAI:hin ja GPT-5.2:een ja sukellat syvemmälle jokaiseen käsitteeseen. - -## What is LangChain4j? - -LangChain4j on Java-kirjasto, joka yksinkertaistaa tekoälyllä varustettujen sovellusten rakentamista. HTTP-asiakkaiden ja JSON-jäsentämisen sijaan työskentelet puhtaiden Java-rajapintojen kanssa. - -LangChainin "ketju" tarkoittaa useiden komponenttien ketjuttamista yhteen – voit ketjuttaa esimerkiksi kehotteen malliin ja sieltä jäsentimeen, tai ketjuttaa useita tekoälykutsuja, joissa yksi lähtö syöttää seuraavaa syötettä. Tämä pikaopas keskittyy perusteisiin ennen monimutkaisempien ketjujen tutkimista. - -LangChain4j Chaining Concept - -*Komponenttien ketjuttaminen LangChain4j:ssä – rakennuspalikat yhdistyvät luoden tehokkaita tekoälytyönkulkuja* - -Käytämme kolmea ydinkomponenttia: - -**ChatModel** – Rajapinta tekoälymallien vuorovaikutukseen. Kutsu `model.chat("prompt")` ja saat vastausmerkkijonon. Käytämme `OpenAiOfficialChatModel`-luokkaa, joka toimii OpenAI-yhteensopivien rajapintojen kuten GitHub-mallien kanssa. - -**AiServices** – Luo tyyppiturvallisia tekoälypalvelunrajapintoja. Määrittele metodit, merkkaa ne `@Tool`-annotaatiolla, ja LangChain4j hoitaa orkestroinnin. Tekoäly kutsuu automaattisesti Java-menetelmiäsi tarpeen mukaan. - -**MessageWindowChatMemory** – Säilyttää keskusteluhistorian. Ilman tätä jokainen pyyntö on itsenäinen. Tämän kanssa tekoäly muistaa edelliset viestit ja ylläpitää kontekstia useiden vuorojen yli. - -LangChain4j Architecture - -*LangChain4j-arkkitehtuuri – ydinkomponentit toimivat yhdessä tehostaen tekoälysovelluksiasi* - -## LangChain4j Dependencies - -Tämä pikaopas käyttää kolmea Maven-riippuvuutta tiedostossa [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official`-moduuli tarjoaa `OpenAiOfficialChatModel`-luokan, joka yhdistää OpenAI-yhteensopiviin rajapintoihin. GitHub-mallit käyttävät samaa rajapintamuotoa, joten erityistä sovitinta ei tarvita – osoita vain perus-URL `https://models.github.ai/inference`. - -`langchain4j-easy-rag`-moduuli tarjoaa automaattisen asiakirjojen pilkkomisen, upotuksen ja haun, jotta voit rakentaa RAG-sovelluksia ilman manuaalista konfigurointia jokaiseen vaiheeseen. - -## Prerequisites - -**Käytätkö Dev Containeria?** Java ja Maven on jo asennettu. Tarvitset vain GitHubin henkilökohtaisen käyttöoikeustunnuksen. - -**Paikallinen kehitys:** -- Java 21+, Maven 3.9+ -- GitHubin henkilökohtainen käyttöoikeustunnus (ohjeet alla) - -> **Huom:** Tässä moduulissa käytetään `gpt-4.1-nano` GitHub-malleista. Älä muuta mallin nimeä koodissa – se on määritetty toimimaan GitHubin saatavilla olevien mallien kanssa. - -## Setup - -### 1. Get Your GitHub Token - -1. Mene osoitteeseen [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Klikkaa "Generate new token" -3. Anna kuvaava nimi (esim. "LangChain4j Demo") -4. Aseta vanhenemisaika (suositus 7 päivää) -5. "Account permissions" kohdassa etsi "Models" ja aseta "Read-only" -6. Klikkaa "Generate token" -7. Kopioi ja tallenna tunnuksesi – et näe sitä enää uudelleen - -### 2. Set Your Token - -**Vaihtoehto 1: VS Code (suositus)** - -Jos käytät VS Codea, lisää tunnuksesi `.env`-tiedostoon projektin juureen: - -Jos `.env`-tiedostoa ei ole, kopioi `.env.example` nimellä `.env` tai luo uusi `.env` projektiin. - -**Esimerkki `.env`-tiedostosta:** -```bash -# Tiedostossa /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Sitten voit yksinkertaisesti klikata hiiren oikealla mitä tahansa demotiedostoa (esim. `BasicChatDemo.java`) Explorerissa ja valita **"Run Java"** tai käyttää Run and Debug -paneelin käynnistyskonfiguraatioita. - -**Vaihtoehto 2: Terminaali** - -Aseta tunnus ympäristömuuttujaksi: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Run the Examples - -**VS Code:** Klikkaa hiiren oikealla mitä tahansa demotiedostoa Explorerissa ja valitse **"Run Java"**, tai käytä Run and Debug -paneelin käynnistyskonfiguraatioita (muista lisätä token ensin `.env`-tiedostoon). - -**Mavenilla:** Vaihtoehtoisesti voit ajaa komentoriviltä: - -### 1. Basic Chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Prompt Patterns - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Näyttää zero-shot, few-shot, chain-of-thought ja roolipohjaiset kehotteet. - -### 3. Function Calling - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -Tekoäly kutsuu automaattisesti Java-menetelmiäsi tarvittaessa. - -### 4. Document Q&A (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Kysy kysymyksiä dokumenteistasi Easy RAG:n avulla, jossa upotus ja haku tapahtuvat automaattisesti. - -### 5. Responsible AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Katso miten tekoälyn turvallisuussuodattimet estävät haitallista sisältöä. - -## What Each Example Shows - -**Basic Chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Aloita tästä nähdäksesi LangChain4j:n yksinkertaisimmillaan. Luo `OpenAiOfficialChatModel`, lähetä kehotteella `.chat()` ja saa vastaus. Tämä näyttää perustan: miten mallin alustus custom-päätepisteillä ja API-avaimilla tehdään. Kun ymmärrät tämän mallin, kaikki muu rakentuu sen varaan. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Kokeile [GitHub Copilotin](https://github.com/features/copilot) Chatilla:** Avaa [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) ja kysy: -> - "Miten vaihtaisin koodissa GitHub-malleista Azure OpenAI:hin?" -> - "Mitä muita parametreja voin määrittää OpenAiOfficialChatModel.builder()-metodissa?" -> - "Miten lisäisin streaming-vastaukset sen sijaan että odotan koko vastausta?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Nyt kun tiedät, miten puhut mallille, tutki mitä sanot sille. Tämä demo käyttää samaa mallikonfiguraatiota mutta näyttää viisi erilaista kehotemallia. Kokeile zero-shot-kehotteita suorille ohjeille, few-shot-kehotteita jotka oppivat esimerkeistä, chain-of-thought-kehotteita jotka paljastavat päättelyvaiheita ja roolipohjaisia kehotteita, jotka määrittävät kontekstin. Näet miten sama malli antaa dramaattisen erilaisia vastauksia kehotteen asettelun perusteella. - -Demo näyttää myös kehotepohjat, jotka ovat tehokas tapa luoda uudelleen käytettäviä kehotteita muuttujilla. -Alla oleva esimerkki näyttää kehotteen LangChain4j `PromptTemplate`-objektia käyttäen, jossa täytetään muuttujia. Tekoäly vastaa annetun kohteen ja aktiviteetin perusteella. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Kokeile [GitHub Copilotin](https://github.com/features/copilot) Chatilla:** Avaa [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) ja kysy: -> - "Mikä ero on zero-shot- ja few-shot-kehotteilla, ja milloin käytän kumpaakin?" -> - "Miten lämpötila-parametri vaikuttaa mallin vastauksiin?" -> - "Mitkä ovat tekniikoita estää kehotepohjien injektointihyökkäykset tuotannossa?" -> - "Miten luon uudelleenkäytettäviä PromptTemplate-objekteja yleisiin malleihin?" - -**Tool Integration** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Tässä LangChain4j muuttuu tehokkaaksi. Käytät `AiServices`-luokkaa tekoälyavustajan luomiseen, joka voi kutsua Java-metodejasi. Riittää, että merkitset metodit `@Tool("kuvaus")`-annotaatiolla ja LangChain4j hoitaa loput – tekoäly päättää automaattisesti, milloin käyttää mitäkin työkalua käyttäjän pyynnön mukaan. Tämä esittelee funktiokutsut, keskeisen tekniikan tekoälyn rakentamiseen, joka voi suorittaa toimintoja eikä vain vastata kysymyksiin. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Kokeile [GitHub Copilotin](https://github.com/features/copilot) Chatilla:** Avaa [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ja kysy: -> - "Miten @Tool-annotaatio toimii ja mitä LangChain4j tekee sillä taustalla?" -> - "Voiko tekoäly kutsua useita työkaluja peräkkäin ratkaistakseen monimutkaisia ongelmia?" -> - "Mitä tapahtuu, jos työkalu heittää poikkeuksen – miten virheet pitäisi käsitellä?" -> - "Miten integroisin oikean API:n tämän laskuesimerkin sijaan?" - -**Document Q&A (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Tässä näet RAG:n (retrieval-augmented generation) käyttäen LangChain4j:n "Easy RAG" -menetelmää. Asiakirjat ladataan, pilkotaan automaattisesti ja upotetaan muistiin, minkä jälkeen sisältöhaku toimittaa relevanteimmat palat tekoälylle kyselyhetkellä. Tekoäly vastaa asiakirjojesi perusteella, ei yleisen tietämyksensä. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Kokeile [GitHub Copilotin](https://github.com/features/copilot) Chatilla:** Avaa [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) ja kysy: -> - "Miten RAG estää tekoälyn harhaluulot verrattuna mallin koulutusdataan?" -> - "Mikä ero on tässä helpossa lähestymistavassa ja mukautetussa RAG-putkessa?" -> - "Miten skaalaisin tämän käsittelemään useita asiakirjoja tai isompia tietovarastoja?" - -**Responsible AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Rakenna tekoälyn turvallisuus kerrospintaisesti. Tämä demo näyttää kaksi suojaustasoa, jotka toimivat yhdessä: - -**Osa 1: LangChain4j Input Guardrails** – Estää vaaralliset kehotteet ennen niiden pääsyä LLM:ään. Luo omat suojakaiteet, jotka tarkistavat kielletyt avainsanat tai kaavat. Nämä toimivat koodissasi, joten ne ovat nopeita ja ilmaisia. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Osa 2: Tarjoajan turvafiltterit** – GitHub-malleissa on sisäänrakennetut suodattimet, jotka tarttuvat siihen, mitä suojakaiteesi voivat jäädä huomaamatta. Näet tiukat estot (HTTP 400 -virheet) vakavissa rikkomuksissa ja pehmeät kieltäytymiset, joissa tekoäly kohteliaasti kieltäytyy. - -> **🤖 Kokeile [GitHub Copilotin](https://github.com/features/copilot) Chatilla:** Avaa [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) ja kysy: -> - "Mikä on InputGuardrail ja miten luon oman?" -> - "Mikä ero on kovalla estolla ja pehmeällä kieltäytymisellä?" -> - "Miksi käyttää sekä suojakaiteita että tarjoajan suodattimia yhdessä?" - -## Next Steps - -**Seuraava moduuli:** [01-introduction - Getting Started with LangChain4j](../01-introduction/README.md) - ---- - -**Navigointi:** [← Takaisin pääsivulle](../README.md) | [Seuraava: Module 01 - Introduction →](../01-introduction/README.md) - ---- - -## Troubleshooting - -### First-Time Maven Build - -**Ongelma**: Ensimmäinen `mvn clean compile` tai `mvn package` kestää kauan (10–15 minuuttia) - -**Syy**: Mavenin täytyy ladata kaikki projektin riippuvuudet (Spring Boot, LangChain4j-kirjastot, Azure SDK:t jne.) ensimmäisellä kerralla. - -**Ratkaisu**: Tämä on normaalia käyttäytymistä. Seuraavat kerrat ovat paljon nopeampia, kun riippuvuudet on tallennettu paikallisesti. Latausaika riippuu verkkoyhteyden nopeudesta. - -### PowerShell Maven Command Syntax - -**Ongelma:** Maven-komennot epäonnistuvat virheellä `Unknown lifecycle phase ".mainClass=..."` -**Syy**: PowerShell tulkitsee `=` muuttujan määrittämisen operaattorina, mikä rikkoo Maven-ominaisuussyntaksin - -**Ratkaisu**: Käytä pysäytyksen jäsentämisoperaattoria `--%` ennen Maven-komentoa: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%`-operaattori kertoo PowerShellille, että kaikki jäljellä olevat argumentit annetaan kirjaimellisesti Mavenille ilman tulkintaa. - -### Windows PowerShellin emojeiden näyttö - -**Ongelma**: AI-vastauksissa näkyy roska merkkeinä (esim. `????` tai `â??`) PowerShellissä emojien sijaan - -**Syy**: PowerShellin oletuskoodaus ei tue UTF-8-emojia - -**Ratkaisu**: Suorita tämä komento ennen Java-sovellusten käynnistystä: -```cmd -chcp 65001 -``` - -Tämä pakottaa UTF-8-koodauksen terminaaliin. Vaihtoehtoisesti käytä Windows Terminalia, jossa on parempi Unicode-tuki. - -### API-pyyntöjen virheenkorjaus - -**Ongelma**: Todennusvirheitä, pyyntörajoituksia tai odottamattomia vastauksia AI-mallilta - -**Ratkaisu**: Esimerkeissä on `.logRequests(true)` ja `.logResponses(true)` näyttääksesi API-kutsut konsolissa. Tämä auttaa ratkaisemaan todennusvirheitä, pyyntörajoituksia tai odottamattomia vastauksia. Poista nämä liput tuotannossa vähentääksesi lokiääntä. - ---- - - -**Vastuuvapauslauseke**: -Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset voivat sisältää virheitä tai epätarkkuuksia. Alkuperäistä asiakirjaa sen alkuperäiskielellä tulisi pitää virallisena lähteenä. Tärkeiden tietojen osalta suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinkäsityksistä tai virhetulkinnoista. - \ No newline at end of file diff --git a/translations/fi/01-introduction/README.md b/translations/fi/01-introduction/README.md index fb4d13216..9dc7a8a62 100644 --- a/translations/fi/01-introduction/README.md +++ b/translations/fi/01-introduction/README.md @@ -1,85 +1,85 @@ -# Module 01: Aloittaminen LangChain4j:n kanssa +# Moduuli 01: LangChain4j:n perusteet ## Sisällysluettelo -- [Videoesittely](../../../01-introduction) -- [Mitä opit](../../../01-introduction) -- [Esivaatimukset](../../../01-introduction) -- [Ymmärtäminen ydinkysymyksestä](../../../01-introduction) -- [Tokenien ymmärtäminen](../../../01-introduction) -- [Miten muisti toimii](../../../01-introduction) -- [Miten tämä käyttää LangChain4j:ta](../../../01-introduction) -- [Ota Azure OpenAI -ympäristö käyttöön](../../../01-introduction) -- [Suorita sovellus paikallisesti](../../../01-introduction) -- [Sovelluksen käyttäminen](../../../01-introduction) - - [Stateless-chat (vasen paneeli)](../../../01-introduction) - - [Stateful-chat (oikea paneeli)](../../../01-introduction) -- [Seuraavat askeleet](../../../01-introduction) +- [Videokävely](#videokävely) +- [Mitä opit](#mitä-opit) +- [Esivaatimukset](#esivaatimukset) +- [Ymmärrä ydinkysymys](#ymmärrä-ydinkysymys) +- [Ymmärrä tokenit](#ymmärrä-tokenit) +- [Miten muisti toimii](#miten-muisti-toimii) +- [Miten tämä käyttää LangChain4j:ta](#miten-tämä-käyttää-langchain4jta) +- [Ota Azure OpenAI -infrastruktuuri käyttöön](#ota-azure-openai-infrastruktuuri-käyttöön) +- [Suorita sovellus paikallisesti](#suorita-sovellus-paikallisesti) +- [Sovelluksen käyttäminen](#sovelluksen-käyttäminen) + - [Stateless Chat (vasen paneeli)](#stateless-chat-vasen-paneeli) + - [Stateful Chat (oikea paneeli)](#stateful-chat-oikea-paneeli) +- [Seuraavat askeleet](#seuraavat-askeleet) -## Videoesittely +## Videokävely -Katso tämä live-sessio, joka selittää, miten aloitetaan tämän moduulin kanssa: +Katso tämä live-sessio, joka selittää, miten aloittaa tämän moduulin kanssa: Getting Started with LangChain4j - Live Session ## Mitä opit -Pika-alussa käytit GitHub-malleja lähettääksesi kehotteita, kutsuaksesi työkaluja, rakentaaksesi RAG-putken ja testataksesi suojauksia. Ne demot näyttivät, mitä on mahdollista — nyt siirrymme Azure OpenAI:n ja GPT-5.2:n käyttöön ja alamme rakentaa tuotantotason sovelluksia. Tämä moduuli keskittyy keskustelevaan tekoälyyn, joka muistaa kontekstin ja ylläpitää tilaa — käsitteet, joita nämä pika-alun demot käyttivät taustalla mutta eivät selittäneet. +Tämä on lähtökohtasi LangChain4j:n ja Azure OpenAI:n kanssa. Aloitamme perusteista ja alamme rakentaa tuotantotyyppisiä sovelluksia. Tämä moduuli keskittyy keskustelevaan tekoälyyn, joka muistaa kontekstin ja ylläpitää tilaa — perustavanlaatuiset käsitteet, joihin myöhemmät moduulit rakentuvat. -Käytämme tässä oppaassa Azure OpenAI:n GPT-5.2:ta, koska sen edistyneet päättelykyvyt tekevät eri mallien käyttäytymisen selkeämmäksi. Kun lisäät muistin, näet eron selvästi. Tämä helpottaa ymmärtämään, mitä kukin komponentti tuo sovellukseesi. +Käytämme koko oppaassa Azure OpenAI:n GPT-5.2:ta, koska sen kehittyneet päättelykyvyt tekevät erilaisten mallien käyttäytymisen selkeämmin näkyväksi. Kun lisäät muistin, näet eron selvästi. Tämä helpottaa ymmärtämään, mitä kukin komponentti tuo sovellukseesi. -Rakennat yhden sovelluksen, joka havainnollistaa molempia malleja: +Rakennat yhden sovelluksen, joka demonstroi molempia malleja: -**Stateless-chat** – Jokainen pyyntö on itsenäinen. Malli ei muista aiempia viestejä. Tämä on malli, jota käytit pika-alussa. +**Stateless Chat** – Jokainen pyyntö on itsenäinen. Mallilla ei ole muistia aiemmista viesteistä. Tämä on yksinkertaisin lähtökohta. -**Stateful-keskustelu** – Jokainen pyyntö sisältää keskusteluhistorian. Malli ylläpitää kontekstia useiden vuorojen ajan. Tätä tuotantosovellukset vaativat. +**Stateful Conversation** – Jokainen pyyntö sisältää keskusteluhistorian. Malli ylläpitää kontekstia useiden vuorojen ajan. Tätä tuotantosovellukset vaativat. ## Esivaatimukset - Azure-tilaus, jossa on Azure OpenAI -käyttöoikeus -- Java 21, Maven 3.9+ +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Huom:** Java, Maven, Azure CLI ja Azure Developer CLI (azd) on esiasennettu mukana toimitettuun devcontaineriin. +> **Huom:** Java, Maven, Azure CLI ja Azure Developer CLI (azd) on esiasennettu toimitettuun kehitysympäristöön. -> **Huom:** Tämä moduuli käyttää GPT-5.2:a Azure OpenAI:ssa. Käyttöönotto määritellään automaattisesti `azd up` -komennolla – älä muuta mallin nimeä koodissa. +> **Huom:** Tämä moduuli käyttää GPT-5.2:ta Azure OpenAI:ssa. Käyttöönotto määritetään automaattisesti komennolla `azd up` – älä muuta mallin nimeä koodissa. -## Ymmärtäminen ydinkysymyksestä +## Ymmärrä ydinkysymys -Kielimallit ovat tilattomia. Jokainen API-kutsu on itsenäinen. Jos lähetät "Nimeni on John" ja sitten kysyt "Mikä nimeni on?", malli ei tiedä, että juuri esittäydyit. Se käsittelee jokaisen pyynnön kuin se olisi ensimmäinen keskustelusi. +Kielimallit ovat tilattomia. Jokainen API-kutsu on itsenäinen. Jos lähettää "Minun nimeni on John" ja sitten kysyy "Mikä on nimeni?", malli ei tiedä, että juuri esittelit itsesi. Se käsittelee jokaisen pyynnön ikään kuin se olisi sinun ensimmäinen keskustelusi koskaan. -Tämä sopii yksinkertaisiin kyselyihin, mutta on hyödytöntä oikeissa sovelluksissa. Asiakaspalvelubottien pitää muistaa, mitä kerroit niille. Henkilökohtaisten avustajien tarvitsee saada konteksti. Kaikki monivuoroinen keskustelu vaatii muistia. +Tämä toimii yksinkertaisissa kysymys-vastaus-tilanteissa, mutta on käyttökelvoton oikeissa sovelluksissa. Asiakaspalvelubottien täytyy muistaa, mitä kerroit heille. Henkilökohtaiset avustajat tarvitsevat kontekstin. Kaikki monivuorovaikutteiset keskustelut vaativat muistia. -Seuraava kaavio vertaa kahta lähestymistapaa — vasemmalla tilaton kutsu, joka unohtaa nimesi; oikealla tilaava kutsu, jota tukee ChatMemory ja joka muistaa sen. +Seuraava kuvio vertaa kahta lähestymistapaa — vasemmalla tilaton kutsu, joka unohtaa nimesi; oikealla tilallinen kutsu, jota tukee ChatMemory, joka muistaa sen. Stateless vs Stateful Conversations -*Ero tilattoman (itsenäiset kutsut) ja tilaavan (kontekstia huomioivan) keskustelun välillä* +*Erot tilattoman (itsenäiset kutsut) ja tilallisen (kontekstia ymmärtävän) keskustelun välillä* -## Tokenien ymmärtäminen +## Ymmärrä tokenit -Ennen kuin sukellat keskusteluihin, on tärkeää ymmärtää tokenit – perusyksiköt tekstissä, joita kielimallit käsittelevät: +Ennen keskusteluihin sukeltamista on tärkeää ymmärtää tokenit – perusyksiköt tekstiä, joita kielimallit käsittelevät: Token Explanation -*Esimerkki siitä, miten teksti pilkotaan tokeneiksi – "I love AI!" muuttuu 4 erilliseksi käsittelyyksiköksi* +*Esimerkki siitä, miten teksti pilkotaan tokeneiksi – "I love AI!" muodostaa 4 erillistä käsittelyyksikköä* -Tokenit ovat mittayksikkö AI-malleille tekstin mittaamisessa ja käsittelyssä. Sanat, välimerkit ja jopa välilyönnit voivat olla tokeneita. Mallillasi on raja, kuinka monta tokenia se voi käsitellä kerralla (GPT-5.2:lle 400 000, josta enintään 272 000 syöttötokeneita ja 128 000 tulostokoneita). Tokenien ymmärtäminen auttaa hallitsemaan keskustelun pituutta ja kustannuksia. +Tokenit ovat tapa, jolla tekoälymallit mittaavat ja käsittelevät tekstiä. Sanat, välimerkit ja jopa välilyönnit voivat olla tokeneita. Mallillasi on raja, kuinka monta tokenia se voi käsitellä kerralla (GPT-5.2:lla 400 000, joista enintään 272 000 syöttötokeneita ja 128 000 tulostokoneita). Tokenien ymmärtäminen auttaa hallitsemaan keskustelun pituutta ja kustannuksia. ## Miten muisti toimii -Chat-muisti ratkaisee tilattomuuden ongelman ylläpitämällä keskusteluhistoriaa. Ennen kuin lähetät pyynnön mallille, kehys lisää mukaan aiemmin soveltuvia viestejä. Kun kysyt "Mikä nimeni on?", järjestelmä lähettää koko keskusteluhistorian, jolloin malli näkee, että sanoit aiemmin "Nimeni on John." +Chat-muisti ratkaisee tilattomuuden ongelman säilyttämällä keskusteluhistorian. Ennen malliin lähettämistä kehys lisää siihen relevantit aiemmat viestit. Kun kysyt "Mikä on nimeni?", järjestelmä lähettää koko keskusteluhistorian, jolloin malli näkee, että sanasit aiemmin "Minun nimeni on John." -LangChain4j tarjoaa muistiratkaisuja, jotka hoitavat tämän automaattisesti. Valitset, kuinka monta viestiä säilytät, ja kehys hallinnoi kontekstin ikkunaa. Alla olevassa kaaviossa näkyy, miten MessageWindowChatMemory ylläpitää liukuaakkkoa viimeisimmistä viesteistä. +LangChain4j tarjoaa muistien toteutuksia, jotka hoitavat tämän automaattisesti. Valitset, kuinka monta viestiä haluat säilyttää, ja kehys hallinnoi konteksti-ikkunaa. Alla oleva kuvio näyttää, miten MessageWindowChatMemory ylläpitää liukuvana ikkunana uusimpia viestejä. Memory Window Concept -*MessageWindowChatMemory ylläpitää liukuvaa ikkunaa viimeisimmistä viesteistä ja pudottaa automaattisesti vanhoja* +*MessageWindowChatMemory ylläpitää liukuvana ikkunana uusimpia viestejä, pudottaen automaattisesti vanhat* ## Miten tämä käyttää LangChain4j:ta -Tämä moduuli laajentaa pika-aloitusta integroimalla Spring Bootin ja lisäämällä keskustelumuistin. Näin osat toimivat yhdessä: +Tämä moduuli integroi Spring Bootin ja lisää keskustelumuistin. Näin osat nivoutuvat yhteen: **Riippuvuudet** – Lisää kaksi LangChain4j-kirjastoa: @@ -94,7 +94,7 @@ Tämä moduuli laajentaa pika-aloitusta integroimalla Spring Bootin ja lisääm ``` -**Chat-malli** – Määritä Azure OpenAI Spring beaniksi ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chat-malli** – Määritä Azure OpenAI Springin beanina ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder lukee käyttöoikeustiedot ympäristömuuttujista, jotka ovat asetettu `azd up`:lla. Määrittämällä `baseUrl` Azure-päätepisteellesi saat OpenAI-asiakkaan toimimaan Azure OpenAI:n kanssa. +Rakentaja lukee tunnistetiedot ympäristömuuttujista, jotka `azd up` asettaa. Määrittämällä `baseUrl` Azure-päätepisteeksi OpenAI-asiakas toimii Azure OpenAI:n kanssa. **Keskustelumuisti** – Seuraa chat-historiaa MessageWindowChatMemorylla ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,51 +124,51 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Luo muisti `withMaxMessages(10)` pitämään viimeiset 10 viestiä. Lisää käyttäjän ja tekoälyn viestit tyypeillä kääreillä: `UserMessage.from(text)` ja `AiMessage.from(text)`. Hae historia `memory.messages()`-metodilla ja lähetä se mallille. Palvelu tallentaa erilliset muisti-instanssit keskustelu-ID:lle, jolloin useat käyttäjät voivat keskustella samanaikaisesti. +Luo muisti komennolla `withMaxMessages(10)` jättäen viimeiset 10 viestiä talteen. Lisää käyttäjän ja tekoälyn viestit tyypitetyillä kääreillä: `UserMessage.from(text)` ja `AiMessage.from(text)`. Hae historia `memory.messages()`-metodilla ja lähetä se mallille. Palvelu tallentaa erilliset muistiyksiköt kutakin keskustelutunnusta varten, mahdollistaen useiden käyttäjien samanaikaisen chatin. -> **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chatin kanssa:** Avaa [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ja kysy: -> - "Miten MessageWindowChatMemory päättää, mitkä viestit pudottaa, kun ikkuna on täynnä?" -> - "Voinko toteuttaa oman muistivaraston käyttämällä tietokantaa muistin sijaan?" -> - "Miten lisäisin tiivistämisen vanhan keskusteluhistorian puristamiseksi?" +> **🤖 Kokeile GitHub Copilotin [Chatin](https://github.com/features/copilot) kanssa:** Avaa [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ja kysy: +> - "Miten MessageWindowChatMemory päättää, mitkä viestit pudotetaan, kun ikkuna on täysi?" +> - "Voinko toteuttaa oman muistivarastoinnin tietokannan avulla in-memoryn sijaan?" +> - "Miten lisäisin yhteenvetotoiminnon vanhan keskusteluhistorian tiivistämiseksi?" -Stateless-chatin päätepiste ohittaa muistin täysin – pelkkä `chatModel.chat(prompt)` kuten pika-alussa. Stateful-päätepiste lisää viestit muistiin, hakee historian ja sisältää kontekstin jokaisessa pyynnössä. Sama malli, eri mallit. +Tilaton chat-päätepiste jättää muistin kokonaan pois – vain `chatModel.chat(prompt)` kuten pika-alussa. Tilallinen päätepiste lisää viestit muistiin, hakee historian ja liittää kontekstin jokaiseen pyyntöön. Sama malliasetus, erilaiset toteutustyylit. -## Ota Azure OpenAI -ympäristö käyttöön +## Ota Azure OpenAI -infrastruktuuri käyttöön **Bash:** ```bash cd 01-introduction -azd up # Valitse tilaus ja sijainti (eastus2 suositeltu) +azd up # Valitse tilaus ja sijainti (suositeltu eastus2) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Valitse tilaus ja sijainti (suositellaan eastus2) +azd up # Valitse tilaus ja sijainti (eastus2 suositus) ``` -> **Huom:** Jos kohtaat aikakatkaisuvian (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), aja yksinkertaisesti `azd up` uudelleen. Azure-resurssit voivat olla vielä pystytystilassa taustalla, ja uudelleenyritys sallii käyttöönoton valmistumisen, kun resurssit saavuttavat lopullisen tilan. +> **Huom:** Jos kohtaat aikakatkaisuvirheen (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), suorita vain `azd up` uudelleen. Azure-resurssit saattavat olla vielä määrittelyvaiheessa taustalla, ja uudelleenyritys mahdollistaa käyttöönoton etenemisen, kun tilat saavuttavat loppuvaiheen. Tämä: -1. Ota Azure OpenAI -resurssi käyttöön GPT-5.2- ja text-embedding-3-small -malleilla -2. Luo automaattisesti `.env`-tiedoston projektin juureen käyttöoikeuksilla +1. Ottaa käyttöön Azure OpenAI -resurssin GPT-5.2:lla ja text-embedding-3-small -malleilla +2. Luo automaattisesti `.env`-tiedoston projektin juureen tunnistetiedoilla 3. Asettaa kaikki tarvittavat ympäristömuuttujat -**Onko käyttöönotossa ongelmia?** Katso [Infrastructure README](infra/README.md) -tiedosto vianmäärityksestä, mukaan lukien aliverkkotunnuskonfliktit, manuaaliset Azure Portal -asennusohjeet ja mallin konfigurointiohjeet. +**Onko käyttöönotossa ongelmia?** Katso [Infrastructure README](infra/README.md) saadaksesi yksityiskohtaisia ohjeita, mukaan lukien aliverkkotunnusten ristiriidat, manuaaliset Azure-portaalin käyttöönotto-ohjeet ja mallien konfigurointiohjeet. **Varmista, että käyttöönotto onnistui:** **Bash:** ```bash -cat ../.env # Tulisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY jne. +cat ../.env # Pitäisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, jne. ``` **PowerShell:** ```powershell -Get-Content ..\.env # Pitäisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, jne. +Get-Content ..\.env # Tulisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY jne. ``` -> **Huom:** `azd up` -komento luo `.env`-tiedoston automaattisesti. Jos sinun täytyy päivittää sitä myöhemmin, voit joko muokata `.env`-tiedostoa käsin tai luoda sen uudelleen suorittamalla: +> **Huom:** `azd up` -komento luo `.env`-tiedoston automaattisesti. Jos sinun täytyy päivittää sitä myöhemmin, voit joko muokata `.env`-tiedostoa manuaalisesti tai luoda sen uudelleen ajamalla: > > **Bash:** > ```bash @@ -184,41 +184,41 @@ Get-Content ..\.env # Pitäisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, jne. ## Suorita sovellus paikallisesti -**Varmista käyttöönotto:** +**Varmista käyttöönoton onnistuminen:** -Varmista, että `.env`-tiedosto on olemassa juurihakemistossa, sisältäen Azure-käyttäjätunnukset. Suorita tämä moduulikansiosta (`01-introduction/`): +Varmista, että `.env`-tiedosto on olemassa juurikansiossa Azure-tunnistetietoineen. Suorita tämä moduulikansiosta (`01-introduction/`): **Bash:** ```bash -cat ../.env # Pitäisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Tulisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Näyttää AZURE_OPENAI_ENDPOINTin, API_KEYn, DEPLOYMENTin +Get-Content ..\.env # Tulisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Käynnistä sovellukset:** **Vaihtoehto 1: Spring Boot Dashboardin käyttö (suositeltu VS Code -käyttäjille)** -Dev-container sisältää Spring Boot Dashboard -laajennuksen, joka tarjoaa visuaalisen käyttöliittymän kaikkien Spring Boot -sovellusten hallintaan. Löydät sen VS Coden vasemman reunan Aktiviteettipalkista (etsi Spring Boot -ikonia). +Kehitysympäristö sisältää Spring Boot Dashboard -laajennuksen, joka tarjoaa visuaalisen käyttöliittymän kaikkien Spring Boot -sovellusten hallintaan. Löydät sen VS Coden vasemman reunan Activity Barista (etsi Spring Boot -kuvake). Spring Boot Dashboardista voit: -- Nähdä kaikki käytettävissä olevat Spring Boot -sovellukset työtilassa +- Nähdä kaikki työtilan käytettävissä olevat Spring Boot -sovellukset - Käynnistää/pysäyttää sovellukset yhdellä napsautuksella -- Katsoa sovelluslokia reaaliajassa -- Valvoa sovellusten tilaa +- Tarkastella sovelluslokeja reaaliaikaisesti +- Valvoa sovelluksen tilaa -Napsauta toistopainiketta "introduction"-moduulin vieressä käynnistääksesi tämän moduulin, tai käynnistä kaikki moduulit kerralla. +Napsauta toistopainiketta kohdan "introduction" vieressä käynnistääksesi tämän moduulin, tai käynnistä kaikki moduulit kerralla. Spring Boot Dashboard -*Spring Boot Dashboard VS Codessa — käynnistä, pysäytä ja valvo kaikki moduulit yhdestä paikasta* +*Spring Boot Dashboard VS Codessa — käynnistä, pysäytä ja valvo kaikkia moduuleja yhdestä paikasta* -**Vaihtoehto 2: Kuoriskriptien käyttö** +**Vaihtoehto 2: Shell-skriptien käyttö** -Käynnistä kaikki web-sovellukset (moduulit 01–04): +Käynnistä kaikki web-sovellukset (moduulit 01-04): **Bash:** ```bash @@ -262,9 +262,9 @@ Molemmat skriptit lataavat automaattisesti ympäristömuuttujat juuren `.env`-ti > mvn clean package -DskipTests > ``` -Avaa http://localhost:8080 selaimessasi. +Avaa selaimessa http://localhost:8080. -**Pysäyttääksesi:** +**Sovelluksen pysäyttäminen:** **Bash:** ```bash @@ -282,41 +282,41 @@ cd ..; .\stop-all.ps1 # Kaikki moduulit ## Sovelluksen käyttäminen -Sovellus tarjoaa verkkokäyttöliittymän, jossa on kaksi viestien toteutusta rinnakkain. +Sovellus tarjoaa verkkokäyttöliittymän, jossa on kaksi chat-toteutusta vierekkäin. Application Home Screen -*Hallintapaneeli, joka näyttää sekä yksinkertaisen chatin (tilaton) että keskusteleva chat (tilallinen)* +*Etusivu, jossa näkyvissä sekä Simple Chat (stateless) että Conversational Chat (stateful) -vaihtoehdot* -### Stateless-chat (vasen paneeli) +### Stateless Chat (vasen paneeli) -Kokeile ensin tätä. Kysy "Nimeni on John" ja heti perään "Mikä nimeni on?" Malli ei muista, koska jokainen viesti on itsenäinen. Tämä havainnollistaa perustavanlaatuista ongelmaa peruskielimallin integraatiossa – ei keskustelukontekstia. +Kokeile ensin tätä. Kysy "Minun nimeni on John" ja heti perään "Mikä on nimeni?" Malli ei muista, koska kukin viesti on itsenäinen. Tämä havainnollistaa perusongelman peruskielimallien integroinnissa – ei keskustelukontekstia. Stateless Chat Demo *Tekoäly ei muista nimeäsi edellisestä viestistä* -### Stateful-chat (oikea paneeli) +### Stateful Chat (oikea paneeli) -Kokeile nyt samaa sarjaa täällä. Kysy "Nimeni on John" ja sitten "Mikä nimeni on?" Tällä kertaa se muistaa. Erona on MessageWindowChatMemory – se ylläpitää keskusteluhistoriaa ja sisällyttää sen jokaiseen pyyntöön. Näin tuotantokeskustelevat tekoälyt toimivat. +Kokeile nyt samaa sarjaa täällä. Kysy "Minun nimeni on John" ja sitten "Mikä on nimeni?" Tällä kertaa se muistaa. Erotuksena on MessageWindowChatMemory – se ylläpitää keskusteluhistoriaa ja lisää sen jokaiseen pyyntöön. Näin tuotantokeskusteleva tekoäly toimii. Stateful Chat Demo *Tekoäly muistaa nimesi aiemmasta keskustelusta* -Molemmissa paneeleissa käytetään samaa GPT-5.2-mallia. Ainoa ero on muisti. Tämä tekee selväksi, mitä muisti tuo sovellukseesi ja miksi se on olennaista todellisiin käyttötapauksiin. +Molemmat paneelit käyttävät samaa GPT-5.2-mallia. Erona on vain muisti. Tämä selkeyttää, mitä muisti tuo sovellukseesi ja miksi se on välttämätön oikeissa käyttötapauksissa. ## Seuraavat askeleet -**Seuraava moduuli:** [02-prompt-engineering - Kehoteinsinöörityö GPT-5.2:n kanssa](../02-prompt-engineering/README.md) +**Seuraava moduuli:** [02-prompt-engineering - Prompt Engineering GPT-5.2:n kanssa](../02-prompt-engineering/README.md) --- -**Navigointi:** [← Edellinen: Module 00 - Pika-aloitus](../00-quick-start/README.md) | [Takaisin pääsivulle](../README.md) | [Seuraava: Module 02 - Kehoteinsinöörityö →](../02-prompt-engineering/README.md) +**Navigointi:** [← Takaisin pääsivulle](../README.md) | [Seuraava: Moduuli 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **Vastuuvapauslauseke**: -Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, on hyvä huomioida, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäistä asiakirjaa sen alkuperäiskielellä tulee pitää määräävänä lähteenä. Tärkeissä tiedoissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinkäsityksistä tai virhetulkinnoista. +Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista. \ No newline at end of file diff --git a/translations/fi/02-prompt-engineering/README.md b/translations/fi/02-prompt-engineering/README.md index 02ef19c05..cccca5cf6 100644 --- a/translations/fi/02-prompt-engineering/README.md +++ b/translations/fi/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ -# Moduuli 02: Prompt Engineering GPT-5.2:n kanssa +# Moduuli 02: Prompt-suunnittelu GPT-5.2:n kanssa ## Sisällysluettelo -- [Videokävely](../../../02-prompt-engineering) -- [Mitkä asiat opit](../../../02-prompt-engineering) -- [Esivaatimukset](../../../02-prompt-engineering) -- [Prompt Engineeringin ymmärtäminen](../../../02-prompt-engineering) -- [Prompt Engineering -perusteet](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Templates](../../../02-prompt-engineering) -- [Edistyneet mallit](../../../02-prompt-engineering) -- [Sovelluksen ajaminen](../../../02-prompt-engineering) -- [Sovelluksen ruutukaappaukset](../../../02-prompt-engineering) -- [Mallien tutkiminen](../../../02-prompt-engineering) - - [Matalan ja korkean innokkuuden erot](../../../02-prompt-engineering) - - [Tehtävän suoritus (työkalujen alkutekstit)](../../../02-prompt-engineering) - - [Itseään peilaava koodi](../../../02-prompt-engineering) - - [Rakenteellinen analyysi](../../../02-prompt-engineering) - - [Monivaiheinen keskustelu](../../../02-prompt-engineering) - - [Askel askeleelta -päättely](../../../02-prompt-engineering) - - [Rajoitettu tulostus](../../../02-prompt-engineering) -- [Mitä todella opit](../../../02-prompt-engineering) -- [Seuraavat askeleet](../../../02-prompt-engineering) - -## Videokävely - -Katso tämä live-istunto, joka selittää, kuinka pääset alkuun tämän moduulin kanssa: +- [Videoesittely](#videoesittely) +- [Mitä opit](#mitä-opit) +- [Esivaatimukset](#esivaatimukset) +- [Ymmärtäminen prompt-suunnittelusta](#ymmärtäminen-prompt-suunnittelusta) +- [Prompt-suunnittelun perusteet](#prompt-suunnittelun-perusteet) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Edistyneet kuviot](#edistyneet-kuviot) +- [Sovelluksen käynnistäminen](#suorita-sovellus) +- [Sovelluksen kuvakaappauksia](#sovelluksen-kuvakaappaukset) +- [Kuvioiden tutkiminen](#mallien-tutkiminen) + - [Matala vs korkea innokkuus](#matala-vs-korkea-innokkuus) + - [Tehtävän suoritus (työkalujen esipuheet)](#tehtävän-suoritus-tool-preambles) + - [Itsereflektoiva koodi](#itsearvioiva-koodi) + - [Rakenteellinen analyysi](#rakenteellinen-analyysi) + - [Monikäyttökertakeskustelu](#monivaiheinen-keskustelu) + - [Askel askeleelta päättely](#vaiheittainen-päättely) + - [Rajoitettu tulostus](#rajoitettu-tulostus) +- [Mitä todella opit](#mitä-todellisuudessa-opit) +- [Seuraavat askeleet](#seuraavat-vaiheet) + +## Videoesittely + +Katso tämä live-sessio, joka selittää, miten aloittaa tämän moduulin kanssa: Prompt Engineering with LangChain4j - Live Session -## Mitkä asiat opit +## Mitä opit -Seuraava kaavio tarjoaa yleiskuvan keskeisistä aiheista ja taidoista, joita kehität tässä moduulissa — promptien hienosäätötekniikoista askel askeleelta -työnkulkuun, jota seuraat. +Seuraava kaavio antaa yleiskuvan moduulin keskeisistä aiheista ja taidoista — promptin hienosäätötekniikoista askel askeleelta etenevään työnkulkuun, jota seuraat. What You'll Learn -Edellisissä moduuleissa tutustuit perus LangChain4j -vuorovaikutuksiin GitHub-mallien kanssa ja näit, miten muisti mahdollistaa Azure OpenAI:n kanssa käydyn keskustelun tekoälyn. Nyt keskitymme siihen, miten esität kysymyksiä — itse prompteihin — käyttäen Azure OpenAI:n GPT-5.2:ta. Tapa, jolla rakentelet promptit, vaikuttaa dramaattisesti saamaasi vastauksen laatuun. Aloitamme perustekniikoiden kertaamisella, ja siirrymme sitten kahdeksaan edistyneeseen malliin, jotka hyödyntävät GPT-5.2:n ominaisuuksia täysimääräisesti. +Edellisessä moduulissa näit, miten muisti mahdollistaa keskustelevan tekoälyn Azure OpenAI:n kanssa. Nyt keskitymme siihen, miten esität kysymykset — eli itse promptit — käyttäen Azure OpenAI:n GPT-5.2:ta. Tapa, jolla rakennat promptisi, vaikuttaa merkittävästi saamiesi vastausten laatuun. Aloitamme perustekniikoiden katsauksella ja siirrymme sitten kahdeksaan edistyneeseen kuvioon, jotka hyödyntävät GPT-5.2:n kykyjä täydellisesti. -Käytämme GPT-5.2:ta, koska se tuo mukanaan päättelyohjauksen — voit kertoa mallille, kuinka paljon ajattelua sen tulisi tehdä ennen vastaamista. Tämä tekee eri promptaustaktiikoista selkeämpiä ja auttaa sinua ymmärtämään, milloin mitäkin lähestymistapaa kannattaa käyttää. Lisäksi hyödymme Azuren pienemmistä käyttörajoituksista GPT-5.2:lle verrattuna GitHub-malleihin. +Käytämme GPT-5.2:ta, koska se tuo mukanaan päättelyn hallinnan — voit kertoa mallille, kuinka paljon sen tulee ajatella ennen vastaamista. Tämä tuo eri promptausstrategiat selkeämmin esiin ja auttaa ymmärtämään, milloin käyttää kutakin lähestymistapaa. ## Esivaatimukset -- Moduuli 01 suoritettu (Azure OpenAI -resurssit otettu käyttöön) -- `.env`-tiedosto juurihakemistossa, jossa Azure-tunnukset (luotu moduulin 01 `azd up` -komennolla) +- Moduuli 01 suoritettuna (Azure OpenAI -resurssit otettu käyttöön) +- `.env`-tiedosto juurihakemistossa Azure-tunnuksilla (luotu `azd up` -komennolla Moduulissa 01) -> **Huom:** Jos et ole suorittanut moduulia 01, seuraa ensin siellä olevia käyttöönotto-ohjeita. +> **Huom:** Jos et ole suorittanut Moduulia 01, noudata ensin siellä annettuja käyttöönotto-ohjeita. -## Prompt Engineeringin ymmärtäminen +## Ymmärtäminen prompt-suunnittelusta -Prompt engineering on pohjimmiltaan ero epämääräisten ja tarkkojen ohjeiden välillä, kuten alla oleva vertailu havainnollistaa. +Ytimeltään prompt-suunnittelu on ero epämääräisten ohjeiden ja täsmällisten ohjeiden välillä, kuten alla oleva vertailu havainnollistaa. What is Prompt Engineering? -Prompt engineering tarkoittaa syötteen suunnittelua siten, että saat johdonmukaisesti tarvitsemiasi tuloksia. Kyse ei ole vain kysymysten esittämisestä — vaan pyynnön rakentamisesta niin, että malli ymmärtää tarkalleen, mitä haluat ja miten se toimitetaan. +Prompt-suunnittelu tarkoittaa syötteen muotoilua siten, että saat jatkuvasti tarvitsemasi tulokset. Kyse ei ole pelkästään kysymysten esittämisestä — vaan pyyntöjen rakenteistamisesta niin, että malli ymmärtää täsmälleen mitä haluat ja miten sen tulee vastata. -Ajattele sitä kuin annettaisit ohjeita kollegalle. "Korjaa virhe" on epämääräinen ohje. "Korjaa null pointer exception UserService.java:n rivillä 45 lisäämällä null-tarkistus" on tarkka. Kielimallit toimivat samalla tavalla — tarkkuus ja rakenne ratkaisevat. +Ajattele sitä kuin antaisit ohjeita kollegalle. "Korjaa bugi" on epämääräinen. "Korjaa UserService.java-tiedoston rivin 45 null-viittaus virhe lisäämällä null-tarkistus" on tarkka. Kielimallit toimivat samalla tavalla — täsmällisyys ja rakenne ovat tärkeitä. -Alla oleva kaavio näyttää, miten LangChain4j liittyy tähän kuvaan — se yhdistää promptimallit malliin SystemMessage- ja UserMessage-rakenteiden kautta. +Alla olevassa kaaviossa näkyy, miten LangChain4j liittyy tähän kuvaan — se yhdistää prompt-kuviot malliin SystemMessage- ja UserMessage-rakenteiden kautta. How LangChain4j Fits -LangChain4j tarjoaa infrastruktuurin — malliyhteydet, muistin ja viestityypit — kun taas promptimallit ovat vain huolellisesti rakennetun tekstin lähettämistä tämän infrastruktuurin läpi. Keskeiset rakennuspalikat ovat `SystemMessage` (joka määrittää tekoälyn käyttäytymisen ja roolin) ja `UserMessage` (joka kantaa varsinaisen pyynnön). +LangChain4j tarjoaa infrastruktuurin — malliyhteydet, muistin ja viestityypit — kun taas prompt-kuviot ovat huolellisesti rakenteistettua tekstiä, jota lähetät tämän infrastruktuurin läpi. Keskeiset rakennuspalikat ovat `SystemMessage` (joka määrittää tekoälyn toiminnan ja roolin) ja `UserMessage` (joka sisältää varsinaisen pyyntösi). -## Prompt Engineering -perusteet +## Prompt-suunnittelun perusteet -Alla esitetyt viisi ydintekniikkaa muodostavat tehokkaan prompt engineeringin perustan. Kukin käsittelee eri näkökulmaa siihen, miten kommunikoit kielimallien kanssa. +Alla esitetyt viisi perusmenetelmää muodostavat tehokkaan prompt-suunnittelun perustan. Kukin käsittelee eri puolta siitä, miten kommunikoit kielimallien kanssa. Five Prompt Engineering Patterns Overview -Ennen kuin sukellamme tämän moduulin edistyneisiin malleihin, kertaamme viisi perustekniikkaa. Nämä ovat rakennuspalikoita, jotka jokaisen prompt-insinöörin tulee tuntea. Jos olet jo käynyt läpi [Quick Start -moduulin](../00-quick-start/README.md#2-prompt-patterns), olet nähnyt niitä käytännössä — tässä on niiden konseptuaalinen kehys. +Ennen kuin sukellamme moduulin edistyneisiin kuvioihin, kerrataan viisi perustekniikkaa. Nämä ovat rakennuspalikoita, jotka jokaisen prompt-suunnittelijan tulisi tuntea. ### Zero-Shot Prompting -Yksinkertaisin tapa: anna mallille suora ohje ilman esimerkkejä. Malli luottaa täysin koulutukseensa ymmärtääkseen ja suorittaakseen tehtävän. Tämä toimii hyvin suoraviivaisissa pyynnöissä, joissa odotettu käyttäytyminen on ilmeistä. +Yksinkertaisin lähestymistapa: anna mallille suora ohje ilman esimerkkejä. Malli luottaa täysin koulutukseensa tehtävän ymmärtämiseksi ja suorittamiseksi. Tämä toimii hyvin suoraviivaisissa pyynnöissä, joissa odotettu käyttäytyminen on ilmeistä. Zero-Shot Prompting -*Suora ohje ilman esimerkkejä — malli päättelee tehtävän pelkästään ohjeesta* +*Suora ohje ilman esimerkkejä — malli päättelee tehtävän pelkästä ohjeesta* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Vastaus: "Positiivinen" ``` -**Milloin käyttää:** Yksinkertaiset luokitukset, suorat kysymykset, käännökset tai mikä tahansa tehtävä, jonka malli osaa hoitaa ilman lisäohjeita. +**Milloin käyttää:** Yksinkertaiset luokittelut, suoraviivaista kyselyt, käännökset tai tehtävät, jotka malli osaa hoitaa ilman lisäohjausta. ### Few-Shot Prompting -Anna esimerkkejä, jotka näyttävät mallille, mitä mallia haluat sen noudattavan. Malli oppii odotetun syöte-tuotos-muodon esimerkeistäsi ja soveltaa sitä uusiin syötteisiin. Tämä parantaa merkittävästi johdonmukaisuutta tehtävissä, joissa haluttu muoto tai käyttäytyminen ei ole ilmeistä. +Anna esimerkkejä, jotka osoittavat mallille seurattavan kaavan. Malli oppii odotetun syöte–tuloste-muodon esimerkeistä ja soveltaa sitä uusiin syötteisiin. Tämä parantaa merkittävästi johdonmukaisuutta tehtävissä, joissa haluttu muoto tai käyttäytyminen ei ole ilmeistä. Few-Shot Prompting -*Oppiminen esimerkeistä — malli tunnistaa mallin ja soveltaa sitä uusiin syötteisiin* +*Oppii esimerkkien kautta — malli tunnistaa kaavan ja soveltaa sitä uusiin syötteisiin* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Milloin käyttää:** Räätälöidyt luokitukset, johdonmukainen muotoilu, toimialakohtaiset tehtävät tai silloin kun zero-shot-tulokset ovat epäjohdonmukaisia. +**Milloin käyttää:** Mukautetut luokittelut, johdonmukainen muotoilu, tekemäkohtaiset tehtävät tai kun zero-shot-tulokset ovat epäjohdonmukaisia. ### Chain of Thought -Pyydä mallia näyttämään päättelynsä vaihe vaiheelta. Sen sijaan, että hyppäisi suoraan vastaukseen, malli pilkkoo ongelman ja käsittelee jokaisen osan erikseen. Tämä parantaa tarkkuutta matemaattisissa, loogisissa ja monivaiheisissa päättelytehtävissä. +Pyydä mallia näyttämään päättelynsä askel askeleelta. Sen sijaan, että se hyppääisi suoraan vastaukseen, malli hajottaa ongelman ja käsittelee jokaisen osan selkeästi. Tämä parantaa tarkkuutta matematiikassa, logiikassa ja monivaiheisessa päättelyssä. Chain of Thought Prompting -*Askel askeleelta -päättely — monimutkaisten ongelmien pilkkominen eksplisiittisiin loogisiin vaiheisiin* +*Askel askeleelta päättely — monimutkaisten ongelmien hajottaminen selkeiksi loogisiksi vaiheiksi* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Malli näyttää: 15 - 8 = 7, sitten 7 + 12 = 19 omenaa ``` -**Milloin käyttää:** Matematiikan ongelmat, loogiset pulmat, virheen etsintä tai mikä tahansa tehtävä, jossa päättelyprosessin näyttäminen parantaa tarkkuutta ja luottamusta. +**Milloin käyttää:** Matematiikan ongelmat, loogiset pulmat, virheenkorjaukset tai tehtävät, joissa päättelyprosessin näyttäminen parantaa tarkkuutta ja luottamusta. ### Role-Based Prompting -Aseta tekoälylle persoona tai rooli ennen kuin esität kysymyksen. Tämä antaa kontekstin, joka muokkaa vastauksen sävyä, syvyyttä ja painopistettä. "Ohjelmistoarkkitehti" antaa erilaista neuvontaa kuin "juniori-kehittäjä" tai "turvallisuustarkastaja". +Aseta tekoälylle rooli tai persoona ennen kysymyksen esittämistä. Tämä antaa kontekstin, joka muokkaa vastauksen sävyä, syvyyttä ja painotusta. "Ohjelmistoarkkitehti" antaa erilaisia neuvoja kuin "juniori-kehittäjä" tai "turvallisuusauditoija". Role-Based Prompting -*Kontekstin ja persoonan asettaminen — samaan kysymykseen saadaan eri vastauksia roolista riippuen* +*Kontekstin ja roolin asettaminen — sama kysymys saa eri vastauksen roolista riippuen* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Milloin käyttää:** Koodikatselmukset, opetus, toimialakohtainen analyysi tai silloin kun tarvitset vastauksia, jotka on räätälöity tietyn asiantuntemustason tai näkökulman mukaan. +**Milloin käyttää:** Koodikatselmukset, opastus, toimialakohtaiset analyysit tai kun tarvitset vastauksia, jotka on räätälöity tietylle asiantuntemustasolle tai näkökulmalle. ### Prompt Templates -Luo uudelleenkäytettäviä prompt-malleja muuttujapaikoilla. Sen sijaan, että kirjoittaisit uuden promptin joka kerta, määrittele mallipohja kerran ja täytä eri arvot. LangChain4j:n `PromptTemplate`-luokka tekee tämän helpoksi `{{variable}}`-syntaksilla. +Luo uudelleenkäytettäviä promptteja muuttuvilla paikkamerkeillä. Sen sijaan, että kirjoittaisit uuden promptin joka kerta, määrittele malli kerran ja täytä eri arvot. LangChain4j:n `PromptTemplate`-luokka tekee tämän helpoksi `{{muuttuja}}`-syntaksilla. Prompt Templates -*Uudelleenkäytettävät promptit muuttujapaikoilla — yksi malli, monta käyttötarkoitusta* +*Uudelleenkäytettävät promptit muuttuvilla paikkamerkeillä — yksi malli, monta käyttötapaa* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Milloin käyttää:** Toistuvat kyselyt eri syötteillä, eräkäsittely, uudelleenkäytettävien tekoälytyönkulkujen rakentaminen tai mikä tahansa tilanne, jossa promptin rakenne pysyy samana mutta data vaihtelee. +**Milloin käyttää:** Toistuvat kyselyt eri syötteillä, eräkäsittely, uudelleenkäytettävien tekoälytyönkulkujen rakentaminen tai kaikki tilanteet, joissa promptin rakenne pysyy samana, mutta data vaihtuu. --- -Nämä viisi perustekniikkaa tarjoavat vahvan työkalupakin useimpiin promptaustehtäviin. Loput tästä moduulista rakentuvat niiden päälle käyttäen **kahtatoista edistynyttä mallia**, jotka hyödyntävät GPT-5.2:n päättelyohjausta, itsearviointia ja rakenteellista tulostusta. +Nämä viisi perustekniikkaa antavat sinulle vahvan työkalupakin useimpiin promptaukseen liittyviin tehtäviin. Loput tästä moduulista rakentuvat niiden päälle käyttäen **kahdeksaa edistynyttä kuviota**, jotka hyödyntävät GPT-5.2:n päättelyn hallintaa, itsearviointia ja rakenteellista tulostusta. -## Edistyneet mallit +## Edistyneet kuviot -Kun perusteet on käyty läpi, siirrytään kahdeksaan edistyneeseen malliin, jotka tekevät tästä moduulista ainutlaatuisen. Kaikki ongelmat eivät vaadi samaa lähestymistapaa. Jotkut kysymykset tarvitsevat nopeita vastauksia, toiset syvällistä pohdintaa. Jotkin vaativat näkyvää päättelyä, toiset vain tuloksia. Jokainen alla oleva malli on optimoitu eri tilanteeseen — ja GPT-5.2:n päättelyohjaus korostaa näiden eroja entisestään. +Kun perustekniikat on käyty läpi, siirrytään kahdeksaan edistyneeseen kuvioon, jotka tekevät tästä moduulista ainutlaatuisen. Kaikki ongelmat eivät vaadi samaa lähestymistapaa. Jotkut kysymykset tarvitsevat nopeita vastauksia, toiset syvällistä pohdintaa. Jotkut vaativat näkyvää päättelyä, toiset pelkkää tulosta. Alla olevat kuviot on optimoitu eri tilanteisiin — ja GPT-5.2:n päättelyn hallinta tekee eroista vielä selkeämpiä. Eight Prompting Patterns -*Yleiskatsaus kahdeksaan prompt engineering -malliin ja niiden käyttötapauksiin* +*Yleiskuva kahdeksasta prompt-suunnittelukuvioista ja niiden käyttötapauksista* -GPT-5.2 lisää näihin malleihin uuden ulottuvuuden: *päättelyohjauksen*. Liukusäädin alla näyttää, kuinka voit säätää mallin ajatteluprosessin voimakkuuden — nopeista suoriin vastauksiin ja syvälliseen, perusteelliseen analyysiin. +GPT-5.2 tuo näihin kuvioihin uuden ulottuvuuden: *päättelyn hallinnan*. Alla oleva liukusäädin näyttää, miten voit säätää mallin ajattelun määrää — nopeista suorista vastauksista syvälliseen ja perusteelliseen analyysiin. Reasoning Control with GPT-5.2 -*GPT-5.2:n päättelyohjaus antaa sinun määrittää, kuinka paljon mallin tulee ajatella — nopeista suorista vastauksista syvälliseen tarkasteluun* +*GPT-5.2:n päättelyn hallinta antaa mahdollisuuden määrittää, kuinka paljon ajattelua mallin tulee tehdä — nopeista suorista vastauksista syvälliseen pohdintaan* -**Matalan innokkuuden tila (Nopea & Tämänhetkinen)** - Yksinkertaisiin kysymyksiin, joissa haluat nopeita, suoria vastauksia. Malli käyttää minimaalista päättelyä – enintään 2 askelta. Käytä tätä laskuihin, hakuun tai suoraviivaisiin kysymyksiin. +**Matala innokkuus (nopea & keskittynyt)** – Yksinkertaisiin kysymyksiin, joissa haluat nopeita ja suoria vastauksia. Malli käyttää vähäistä päättelyä — enintään 2 askelta. Käytä tätä laskuihin, hakuihin tai suoraviivaisiin kysymyksiin. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Tutki GitHub Copilotin kanssa:** Avaa [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ja kysy: -> - "Mikä on ero matalan ja korkean innokkuuden promptausmallien välillä?" -> - "Miten XML-tunnisteet prompteissa auttavat muotoilemaan tekoälyn vastauksen?" -> - "Milloin käytän itsearviointimalleja verrattuna suoriin ohjeisiin?" +> 💡 **Tutustu GitHub Copilotilla:** Avaa [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ja kysy: +> - "Mikä on ero matalan ja korkean innokkuuden prompt-kuvioiden välillä?" +> - "Miten XML-tunnisteet promptissa auttavat AI:n vastauksen jäsentelyssä?" +> - "Milloin käytän itsereflektoivia kuvioita verrattuna suoriin ohjeisiin?" -**Korkean innokkuuden tila (Syvällinen & Perusteellinen)** - Monimutkaisiin ongelmiin, joissa haluat kattavan analyysin. Malli tutkii aihetta perusteellisesti ja näyttää yksityiskohtaisen päättelyn. Käytä tätä järjestelmäsuunnittelussa, arkkitehtuuripäätöksissä tai monimutkaisessa tutkimuksessa. +**Korkea innokkuus (syvällinen & perusteellinen)** – Monimutkaisiin ongelmiin, joihin haluat kattavan analyysin. Malli tutkii perusteellisesti ja näyttää yksityiskohtaista päättelyä. Käytä tätä järjestelmäsuunnittelussa, arkkitehtuuripäätöksissä tai monimutkaisessa tutkimuksessa. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Tehtävän suoritus (askel askeleelta etenevä prosessi)** - Monivaiheisiin työnkulkuihin. Malli antaa etukäteen suunnitelman, kuvailee kunkin vaiheen työskentelyn aikana, ja lopuksi esittää yhteenvedon. Käytä tätä migraatioissa, toteutuksissa tai missä tahansa monivaiheisessa prosessissa. +**Tehtävän suoritus (askel askeleelta eteneminen)** – Monivaiheisiin työnkulkuihin. Malli antaa aluksi suunnitelman, kertoo jokaisesta työvaiheesta työn edetessä ja lopuksi koosteen. Käytä tätä migraatioissa, toteutuksissa tai muissa monivaiheisissa prosesseissa. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Chain-of-Thought -promptaus pyytää mallia erittäin selkeästi näyttämään päättelyprosessinsa, mikä parantaa tarkkuutta monimutkaisissa tehtävissä. Askel askeleelta -erittely auttaa sekä ihmisiä että tekoälyä ymmärtämään logiikan. +Chain-of-Thought -promptaus pyytää mallia näyttämään päättelyprosessinsa eksplisiittisesti, mikä parantaa tarkkuutta monimutkaisissa tehtävissä. Askel askeleelta eteneminen auttaa sekä ihmisiä että tekoälyä ymmärtämään logiikan. -> **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chatin kanssa:** Kysy tästä mallista: -> - "Miten mukauttaisin tehtävän suoritusmallin pitkäkestoisia operaatioita varten?" -> - "Mitkä ovat parhaat käytännöt työkalujen aloitustekstien järjestämisessä tuotantosovelluksissa?" -> - "Miten voin kaapata ja näyttää välivaiheen etenemispäivityksiä käyttöliittymässä?" +> **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chat:issa:** Kysy tästä kuviosta: +> - "Miten muutan tehtävän suorituskuviota pitkään kestävien operaatioiden yhteydessä?" +> - "Mitkä ovat parhaat käytännöt työkalujen esipuheiden rakenteistamiseen tuotantosovelluksissa?" +> - "Miten voin tallentaa ja näyttää väliaikaiset etenemispäivitykset käyttöliittymässä?" -Alla oleva kaavio havainnollistaa tätä Suunnittelu → Suoritus → Yhteenveto -työnkulkua. +Alla oleva kaavio havainnollistaa tätä Suunnittele → Suorita → Yhteenveto -työnkulkua. Task Execution Pattern -*Suunnittelu → Suoritus → Yhteenveto -työnkulku monivaiheisissa tehtävissä* +*Suunnittele → Suorita → Yhteenveto -työnkulku monivaiheisiin tehtäviin* -**Itseään peilaava koodi** – Tuotantokelpoisen koodin generointiin. Malli luo koodia noudattaen tuotantostandardeja ja huolella virheenkäsittelyä. Käytä tätä rakentaessasi uusia ominaisuuksia tai palveluita. +**Itsereflektoiva koodi** – Tuotantotasoisen koodin generointiin. Malli generoi koodia tuotantostandardien mukaan asianmukaisella virheenkäsittelyllä. Käytä tätä rakennettaessa uusia ominaisuuksia tai palveluita. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Alla oleva kaavio näyttää tämän iteratiivisen parannuskierron — generoi, arvioi, tunnista heikkoudet ja hienosäädä kunnes koodi täyttää tuotantovaatimukset. +Alla oleva kaavio kuvaa tämän iteratiivisen parantamisen kierteen — generoi, arvioi, tunnista heikkoudet ja hienosäädä, kunnes koodi täyttää tuotantovaatimukset. Self-Reflection Cycle -*Iteratiivinen parannuskierto - generointi, arviointi, ongelmien tunnistus, parannus, toisto* +*Iteratiivinen parantamiskierre — generoi, arvioi, tunnista ongelmat, paranna, toista* -**Rakenteellinen analyysi** — Johdonmukaiseen arviointiin. Malli tarkastelee koodia kiinteän kehyksen mukaisesti (oikeellisuus, käytännöt, suorituskyky, turvallisuus, ylläpidettävyys). Käytä tätä koodikatselmuksissa tai laadunarvioinneissa. +**Rakenteellinen analyysi** – Johdonmukaiseen arviointiin. Malli tarkastaa koodin kiinteän kehyksen mukaan (oikeellisuus, käytännöt, suorituskyky, turvallisuus, ylläpidettävyys). Käytä tätä koodikatselmuksiin tai laadun arviointiin. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chatin kanssa:** Kysy rakenteellisesta analyysista: -> - "Miten räätälöin analyysikehyksen eri tyyppisiin koodikatselmuksiin?" -> - "Mikä on paras tapa jäsentää ja hyödyntää rakenteellista tulostetta ohjelmallisesti?" -> - "Miten varmistan johdonmukaiset vakavuustasot eri katselmusistunnoissa?" +> **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chat:issa:** Kysy rakenteellisesta analyysistä: +> - "Miten voin räätälöidä analyysikehystä eri tyyppisille koodikatselmuksille?" +> - "Mikä on paras tapa jäsentää ja käsitellä rakenteellista tulostetta ohjelmallisesti?" +> - "Miten varmistaa johdonmukaiset vakavuustasot eri katselmussessioissa?" -Seuraava kaavio näyttää, miten tämä rakenne jäsentää koodikatselmuksen johdonmukaisiin kategorioihin vakavuustasojen kanssa. +Seuraava kaavio näyttää, miten tämä rakenteellinen kehys jäsentää koodikatselmuksen johdonmukaisiin kategorioihin vakavuustasoineen. Structured Analysis Pattern -*Kehys johdonmukaisiin koodikatselmuksiin vakavuustasoineen* +*Kehys johdonmukaisiin koodikatselmuksiin vakavuustasojen kanssa* -**Monivaiheinen keskustelu** — Keskusteluihin, joissa tarvitaan kontekstia. Malli muistaa aiemmat viestit ja rakentaa niistä eteenpäin. Käytä tätä vuorovaikutteisissa tukisessioissa tai monimutkaisessa kysymys-vastaus -toiminnassa. +**Monikäyttökertakeskustelu** – Keskusteluihin, jotka tarvitsevat kontekstia. Malli muistaa aiemmat viestit ja rakentaa niiden varaan. Käytä tätä interaktiivisiin tukisessioihin tai monimutkaisiin kysymys–vastaus-tilanteisiin. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Alla oleva kaavio havainnollistaa, miten keskustelukonteksti karttuu kierrosten myötä ja miten se liittyy mallin token-rajoitukseen. +Alla oleva kaavio havainnollistaa, miten keskustelukonteksti kertyy kunkin vaiheen myötä ja miten se liittyy mallin token-rajoitukseen. Context Memory -*Kuinka keskustelukonteksti karttuu useiden vaihtojen aikana token-rajan saavuttamiseen saakka* -**Vaiheittainen päättely** – Ongelmissa, jotka vaativat näkyvää logiikkaa. Malli näyttää selkeän päättelyn jokaiselle vaiheelle. Käytä tätä matemaattisissa ongelmissa, logiikkapähkinöissä tai kun haluat ymmärtää ajatteluprosessin. +*Kuinka keskustelukonteksti kertyy useiden käänteiden aikana token-rajalle saakka* + +**Askel askeleelta päättely** – Ongelmissa, jotka vaativat näkyvää logiikkaa. Malli näyttää eksplisiittisen päättelyn jokaiselle askeleelle. Käytä tätä matematiikan ongelmiin, loogisiin pulmisiin tai kun tarvitset ymmärrystä ajatteluprosessista. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Alla oleva kaavio havainnollistaa, miten malli jakaa ongelmat selkeiksi, numeroiduiksi loogisiksi vaiheiksi. - -Vaiheittainen malli +Alla oleva kaavio havainnollistaa, miten malli jakaa ongelmat eksplisiittisiin, numeroituihin loogisiin vaiheisiin. -*Ongelmien jakaminen selkeisiin loogisiin vaiheisiin* +Step-by-Step Pattern +*Ongelmien purkaminen eksplisiittisiksi loogisiksi vaiheiksi* -**Rajoitettu tuloste** – Vastauksissa, joissa vaaditaan tiettyä muotoa. Malli noudattaa tiukasti muoto- ja pituussääntöjä. Käytä tätä yhteenvetoihin tai silloin, kun tarvitset tarkan tulosteen rakenteen. +**Rajoitettu tulostus** – Vastauksissa, joissa on erityisiä formaatti- ja pituusvaatimuksia. Malli noudattaa tarkasti formaatti- ja pituussääntöjä. Käytä tätä yhteenvetoihin tai kun tarvitset täsmällistä tulosten rakennetta. ```java String prompt = """ @@ -419,190 +419,190 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +Seuraava kaavio näyttää, kuinka rajoitukset ohjaavat mallia tuottamaan vastauksen, joka noudattaa tiukasti antamiasi formaatti- ja pituusvaatimuksia. -Seuraava kaavio näyttää, miten rajoitukset ohjaavat mallia tuottamaan vastauksia, jotka noudattavat täsmällisesti vaatimuksia muodon ja pituuden suhteen. +Constrained Output Pattern -Rajoitetun tulosteen malli - -*Tarkasti määritettyjen muoto-, pituus- ja rakennevaatimusten noudattaminen* +*Erityisten formaatti-, pituus- ja rakennevaatimusten noudattaminen* ## Suorita sovellus -**Vahvista käyttöönotto:** +**Varmista käyttöönotto:** -Varmista, että `.env`-tiedosto on juurihakemistossa ja sisältää Azure-tunnistetiedot (luotu moduulissa 01). Aja tämä moduulihakemistosta (`02-prompt-engineering/`): +Varmista, että `.env`-tiedosto on olemassa juurikansiossa Azure-tunnuksilla (luotu moduulin 01 aikana). Suorita tämä moduulihakemistosta (`02-prompt-engineering/`): -**Bash:** +**Bash:** ```bash cat ../.env # Tulisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # Tulisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Tulis näyttää AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Käynnistä sovellus:** -> **Huom:** Jos olet jo käynnistänyt kaikki sovellukset komennolla `./start-all.sh` juurihakemistosta (kuten moduulissa 01 kuvattiin), tämä moduuli on jo käynnissä portissa 8083. Voit ohittaa alla olevat käynnistyskomennot ja mennä suoraan osoitteeseen http://localhost:8083. +> **Huom:** Jos olet jo käynnistänyt kaikki sovellukset käyttämällä `./start-all.sh` juurikansiosta (kuten kuvattiin moduulissa 01), tämä moduuli on jo käynnissä portissa 8083. Voit ohittaa käynnistyskomennot alla ja siirtyä suoraan osoitteeseen http://localhost:8083. -**Vaihtoehto 1: Spring Boot Dashboardin käyttö (suositellaan VS Code -käyttäjille)** +**Vaihtoehto 1: Spring Boot Dashboardin käyttö (suositeltava VS Code -käyttäjille)** -Kehityssäilö sisältää Spring Boot Dashboard -laajennuksen, joka tarjoaa visuaalisen käyttöliittymän kaikkien Spring Boot -sovellusten hallintaan. Löydät sen VS Coden vasemmanpuoleisesta Activity Barista (etsi Spring Boot -kuvake). +Dev-containere sisältää Spring Boot Dashboard -laajennuksen, joka tarjoaa visuaalisen käyttöliittymän kaikkien Spring Boot -sovellusten hallintaan. Löydät sen VS Code:n vasemman laidan Activity Barista (etsi Spring Boot -kuvaketta). -Spring Boot Dashboardista voit: -- Näyttää kaikki käytettävissä olevat Spring Boot -sovellukset työtilassa -- Käynnistää/pysäyttää sovellukset yhdellä napsautuksella -- Tarkastella sovelluksen lokeja reaaliajassa -- Valvoa sovellusten tilannetta +Spring Boot Dashboardista voit: +- Nähdä kaikki käytettävissä olevat Spring Boot -sovellukset työtilassa +- Käynnistää/lopettaa sovelluksia yhdellä napsautuksella +- Tarkastella sovelluslokeja reaaliajassa +- Valvoa sovellusten tilaa -Klikkaa yksinkertaisesti toistopainiketta "prompt-engineering" -kohdan vieressä käynnistääksesi tämän moduulin, tai käynnistä kaikki moduulit kerralla. +Napsauta yksinkertaisesti toistopainiketta "prompt-engineering" -kohdan vieressä käynnistääksesi tämän moduulin, tai käynnistä kaikki moduulit kerralla. Spring Boot Dashboard -*Spring Boot Dashboard VS Codessa – käynnistä, pysäytä ja valvo kaikki moduulit yhdestä paikasta* +*Spring Boot Dashboard VS Code:ssa – käynnistä, pysäytä ja valvo kaikkia moduuleja yhdestä paikasta* **Vaihtoehto 2: Shell-skriptien käyttö** -Käynnistä kaikki web-sovellukset (moduulit 01-04): +Käynnistä kaikki verkkosovellukset (moduulit 01-04): -**Bash:** +**Bash:** ```bash cd .. # Juurihakemistosta ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell -cd .. # Juurihakemistosta +cd .. # Juurikansiosta .\start-all.ps1 ``` - + Tai käynnistä vain tämä moduuli: -**Bash:** +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` + +Molemmat skriptit lataavat automaattisesti ympäristömuuttujat juurihakemistossa olevasta `.env`-tiedostosta ja rakentavat JAR-tiedostot, jos niitä ei vielä ole. -Kummatkin skriptit lataavat automaattisesti ympäristömuuttujat juurihakemiston `.env`-tiedostosta ja rakentavat JAR-tiedostot, jos niitä ei ole olemassa. - -> **Huom:** Jos haluat rakentaa kaikki moduulit manuaalisesti ennen käynnistystä: -> -> **Bash:** +> **Huom:** Jos haluat rakentaa kaikki moduulit manuaalisesti ennen käynnistystä: +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> -> **PowerShell:** + +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` + +Avaa http://localhost:8083 selaimessasi. -Avaa selaimessa http://localhost:8083. +**Pysäyttääksesi:** -**Pysäytä sovellus:** - -**Bash:** +**Bash:** ```bash -./stop.sh # Tämä moduuli vain +./stop.sh # Vain tämä moduuli # Tai cd .. && ./stop-all.sh # Kaikki moduulit ``` - -**PowerShell:** + +**PowerShell:** ```powershell -.\stop.ps1 # Tämä moduuli vain +.\stop.ps1 # Vain tämä moduuli # Tai cd ..; .\stop-all.ps1 # Kaikki moduulit ``` - + ## Sovelluksen kuvakaappaukset Tässä on prompt engineering -moduulin pääkäyttöliittymä, jossa voit kokeilla kaikkia kahdeksaa mallia rinnakkain. -Hallintapaneelin etusivu +Dashboard Home -*Päähallintapaneeli näyttää kaikki 8 prompt engineering -mallia niiden ominaisuuksineen ja käyttötapauksineen* +*Pääkojelauta, jossa näkyy kaikki 8 prompt engineering -mallia niiden ominaisuuksineen ja käyttötapauksineen* ## Mallien tutkiminen -Verkkokäyttöliittymä antaa kokeilla eri ohjausstrategioita. Jokainen malli ratkaisee eri ongelmia – kokeile niitä nähdäksesi, milloin kukin lähestymistapa toimii parhaiten. +Verkkokäyttöliittymä mahdollistaa erilaisten ohjausstrategioiden kokeilun. Jokainen malli ratkaisee erilaisia ongelmia – kokeile niitä nähdäksesi, milloin kukin lähestymistapa toimii parhaiten. -> **Huom: Virtautus vs Ei-virtautus** — Jokaisella mallisivulla on kaksi painiketta: **🔴 Virtauta vastaus (reaaliaikainen)** ja **Ei-virtautus** -vaihtoehto. Virtautus käyttää Server-Sent Events (SSE) -tekniikkaa näyttäen tokeneita reaaliajassa, kun malli tuottaa niitä, joten näet edistymisen heti. Ei-virtautus-vaihtoehto odottaa koko vastauksen valmiiksi ennen näyttämistä. Syvällistä päättelyä vaativissa kehotteissa (esim. High Eagerness, Self-Reflecting Code) ei-virtautus-kutsu voi kestää hyvin kauan – joskus minuutteja – eikä anna näkyvää palautetta. **Käytä virtausta monimutkaisissa kokeiluissa**, jotta näet mallin toiminnan ja vältät vaikutelman aikakatkaisusta. -> -> **Huom: Selaimen vaatimukset** — Virtausominaisuus käyttää Fetch Streams -API:a (`response.body.getReader()`), joka vaatii täysimittaisen selaimen (Chrome, Edge, Firefox, Safari). Se EI toimi VS Coden sisäänrakennetussa Simple Browserissa, koska sen webview ei tue ReadableStream API:a. Jos käytät Simple Browseria, ei-virtautus-painikkeet toimivat normaalisti – virtauspainikkeet ovat ainoastaan rajoitettuja. Avaa `http://localhost:8083` ulkoisessa selaimessa saadaksesi täyden kokemuksen. +> **Huom: Streaming vs ei-streaming** — Jokaisella mallin sivulla on kaksi painiketta: **🔴 Stream Response (Live)** ja **Ei-streamaava** vaihtoehto. Striimaus käyttää Server-Sent Events (SSE) -tekniikkaa näyttämään tokenit reaaliajassa mallin generoimisen yhteydessä, joten näet etenemisen heti. Ei-streamaava vaihtoehto odottaa koko vastauksen valmistumista ennen näyttämistä. Syvällistä päättelyä vaativissa kysymyksissä (esim. High Eagerness, Self-Reflecting Code) ei-streamaava kutsu voi kestää hyvin kauan – jopa minuutteja – ilman näkyvää palautetta. **Käytä striimausta monimutkaisten kyselyiden kanssa**, jotta näet mallin toiminnassa ja vältyt vaikutelmalta, että pyyntö aikakatkaistiin. +> +> **Huom: Selainvaatimus** — Striimausominaisuus käyttää Fetch Streams APIa (`response.body.getReader()`), joka vaatii täyden selaimen (Chrome, Edge, Firefox, Safari). Se ei toimi VS Code:n sisäänrakennetussa Simple Browserissa, koska sen webview ei tue ReadableStream APIa. Jos käytät Simple Browseria, ei-streamaavat painikkeet toimivat normaalisti – vain striimauspainikkeet eivät. Avaa `http://localhost:8083` ulkoisessa selaimessa parhaan käyttökokemuksen saamiseksi. -### Matala vs Korkea innokkuus +### Matala vs korkea innokkuus -Kysy yksinkertainen kysymys kuten "Mikä on 15 % luvusta 200?" käyttäen Matala innokkuus -tapaa. Saat välittömän, suoraviivaisen vastauksen. Kysy sitten jotain monimutkaista, esimerkiksi "Suunnittele välimuististrategia suurliikenteiselle API:lle", käyttäen Korkea innokkuus -tapaa. Klikkaa **🔴 Virtauta vastaus (reaaliaikainen)** ja katso, kuinka mallin yksityiskohtainen päättely ilmestyy token tokenilta. Sama malli, sama kysymysrakenne – mutta kehotus määrää, kuinka paljon sen tulee ajatella. +Kysy yksinkertainen kysymys kuten "Mikä on 15% luvusta 200?" käyttäen Low Eagernessia. Saat välittömän ja suoran vastauksen. Nyt kysy monimutkaisempi kysymys kuten "Suunnittele välimuististrategia korkealiikenteiselle API:lle" käyttäen High Eagernessia. Klikkaa **🔴 Stream Response (Live)** ja seuraa, kuinka mallin yksityiskohtainen päättely ilmestyy token tokenilta. Sama malli, sama kysymysrakenne – mutta pyyntö ohjaa mallia kuinka paljon ajattelua tehdä. -### Tehtävän suoritus (Työkalujen esilauseet) +### Tehtävän suoritus (Tool Preambles) -Monivaiheiset työnkulut hyötyvät etukäteissuunnittelusta ja etenemisen artikkeloinnista. Malli hahmottelee, mitä se aikoo tehdä, kuvailee kunkin vaiheen ja tiivistää tulokset. +Monivaiheiset työnkulut hyötyvät suunnittelusta ja etenemisen kerronnasta etukäteen. Malli hahmottelee, mitä aikoo tehdä, selostaa jokaisen vaiheen ja tiivistää lopputulokset. ### Itsearvioiva koodi -Kokeile "Luo sähköpostin validointipalvelu". Sen sijaan, että malli vain generoi koodin ja pysähtyy, se luo, arvioi laatukriteerien mukaan, tunnistaa heikkoudet ja parantaa. Näet, kuinka se toistaa, kunnes koodi täyttää tuotantovaatimukset. +Kokeile "Luo sähköpostin validointipalvelu". Sen sijaan, että malli vain generoisi koodin ja pysähtyisi, se luo, arvioi laatukriteerien perusteella, tunnistaa heikkoudet ja parantaa. Näet, kuinka se käy koodia läpi kunnes se täyttää tuotantostandardit. -### Jäsennelty analyysi +### Rakenteellinen analyysi -Koodikatselmukset tarvitsevat yhdenmukaiset arviointikehykset. Malli analysoi koodia kiinteiden kategorioiden (oikeellisuus, käytännöt, suorituskyky, turvallisuus) mukaan vakavuustasoilla. +Koodikatselmukset tarvitsevat johdonmukaiset arviointikehykset. Malli analysoi koodia kiinteillä kategorioilla (oikeellisuus, käytännöt, suorituskyky, turvallisuus) vakavuustasoineen. ### Monivaiheinen keskustelu -Kysy "Mikä on Spring Boot?" ja seuraa heti kysymällä "Näytä esimerkki". Malli muistaa ensimmäisen kysymyksen ja antaa juuri sinulle sopivan Spring Boot -esimerkin. Ilman muistia toinen kysymys olisi liian epämääräinen. +Kysy "Mikä on Spring Boot?" ja heti sen jälkeen "Näytä esimerkki". Malli muistaa ensimmäisen kysymyksesi ja antaa sinulle juuri Spring Boot -esimerkin. Ilman muistia tuo toinen kysymys olisi liian epämääräinen. ### Vaiheittainen päättely -Valitse matemaattinen tehtävä ja kokeile sekä Vaiheittaisella päättelyllä että Matala innokkuus -tavalla. Matala innokkuus antaa vain vastauksen – nopeasti mutta läpinäkymättömästi. Vaiheittainen näyttää jokaisen laskelman ja päätöksen. +Valitse matemaattinen tehtävä ja kokeile sitä sekä Step-by-Step Reasoningilla että Low Eagernessilla. Matala innokkuus antaa vain vastauksen – nopeasti mutta vaillinaisesti. Vaiheittainen päättely näyttää jokaisen laskelman ja päätöksen. -### Rajoitettu tuloste +### Rajoitettu tulostus -Kun tarvitset tiettyjä muotoja tai sanamääriä, tämä malli varmistaa tarkkojen vaatimusten noudattamisen. Kokeile tuottaa yhteenveto, jossa on täsmälleen 100 sanaa bullet point -muodossa. +Kun tarvitset tarkkoja formaatteja tai sanamääriä, tämä malli varmistaa tiukan noudattamisen. Kokeile luoda yhteenveto, jossa on täsmälleen 100 sanaa bullet point -muodossa. -## Mitä todella opit +## Mitä todellisuudessa opit -**Päättelyn vaivannäkö muuttaa kaiken** +**Päättelypanos muuttaa kaiken** -GPT-5.2 antaa sinun hallita laskennallista vaivannäköä kehotteidesi kautta. Matala vaivannäkö tarkoittaa nopeita vastauksia vähäisellä etsinnällä. Korkea vaivannäkö tarkoittaa, että malli käyttää aikaa syvälliseen ajatteluun. Opit sovittamaan vaivannäön tehtävän monimutkaisuuteen – älä käytä aikaa yksinkertaisiin kysymyksiin, mutta älä myöskään kiirehdi monimutkaisia päätöksiä. +GPT-5.2 antaa sinun hallita laskentatehoa pyyntöjen kautta. Matala panos tarkoittaa nopeita vastauksia, joissa on vähän tutkiskelua. Korkea panos tarkoittaa, että malli käyttää aikaa syvälliseen ajatteluun. Opit sovittamaan panoksen tehtävän monimutkaisuuteen – älä tuhlaa aikaa yksinkertaisiin kysymyksiin, mutta älä myöskään kiirehdi monimutkaisia päätöksiä. -**Rakenne ohjaa käyttäytymistä** +**Rakenne ohjaa toimintaa** -Huomaatko kehotteiden XML-tunnisteet? Ne eivät ole koristeita. Mallit seuraavat rakenteellisia ohjeistuksia luotettavammin kuin vapaata tekstiä. Kun tarvitset monivaiheisia prosesseja tai monimutkaista logiikkaa, rakenne auttaa mallia seuraamaan, missä se on ja mitä seuraavaksi tehdään. Alla oleva kaavio purkaa hyvin jäsennellyn kehotteen näyttämällä, miten tunnisteet kuten ``, ``, ``, `` ja `` järjestävät ohjeet selkeisiin osiin. +Huomaatko XML-tunnisteet pyytämisissä? Ne eivät ole koristeita. Mallit noudattavat rakenteellisia ohjeita luotettavammin kuin vapaamuotoista tekstiä. Kun tarvitset monivaiheisia prosesseja tai monimutkaista logiikkaa, rakenne auttaa mallia seuraamaan, missä se on ja mitä seuraavaksi tapahtuu. Alla oleva kaavio purkaa hyvin rakennetun kehotteen, joka näyttää kuinka tunnisteet kuten ``, ``, ``, `` ja `` järjestävät ohjeesi selkeisiin osioihin. -Kehotteen rakenne +Prompt Structure -*Hyvin jäsennellyn kehotteen anatomia, jossa selkeät osiot ja XML-tyylinen järjestely* +*Hyvin rakennetun kehotteen anatomia selkeine osioineen ja XML-tyylisine järjestelyineen* -**Laatu itsearvioinnilla** +**Laatu itsearvioinnin kautta** -Itsearvioiviin malleihin sisältyy laatukriteerien selkeä määrittely. Sen sijaan, että toivoisit mallin "tekevän oikein", kerrot sille täsmälleen, mitä "oikein" tarkoittaa: oikea logiikka, virheenkäsittely, suorituskyky, turvallisuus. Malli voi sitten arvioida omaa tuotostaan ja parantaa sitä. Tämä muuttaa koodin generoinnin arpajaisista prosessiksi. +Itsearvioivissa malleissa laatukriteerit tuodaan eksplisiittisesti esiin. Sen sijaan, että toivotaan mallin "tekevän oikein", kerrot sille tarkasti, mitä "oikein" tarkoittaa: oikea logiikka, virheenkäsittely, suorituskyky, turvallisuus. Malli voi sitten arvioida omaa tuotostaan ja parantaa sitä. Tämä muuttaa koodin generoinnin arpajaisesta hallituksi prosessiksi. **Konteksti on rajallinen** -Monivaiheiset keskustelut toimivat sisällyttämällä viestihistorian jokaiseen pyyntöön. Mutta on olemassa raja – jokaisella mallilla on enimmäistokenien määrä. Kun keskustelut kasvavat, tarvitset strategioita pitää olennaiset tiedot ilman, että ylität tämän rajan. Tämä moduuli näyttää, miten muisti toimii; myöhemmin opit, milloin tiivistää, milloin unohtaa ja milloin hakea uudelleen. +Monivaiheiset keskustelut toimivat sisällyttämällä viestihistorian jokaiseen pyyntöön. Mutta on olemassa raja – jokaisella mallilla on maksimimäärä tokeneita. Keskustelujen kasvaessa tarvitset strategioita merkityksellisen kontekstin ylläpitämiseksi ilman rajan ylittymistä. Tämä moduuli näyttää, kuinka muisti toimii; myöhemmin opit, milloin tiivistää, milloin unohtaa ja milloin hakea tietoa uudelleen. -## Seuraavat askeleet +## Seuraavat vaiheet -**Seuraava moduuli:** [03-rag - RAG (Hakua täydentävä generointi)](../03-rag/README.md) +**Seuraava moduuli:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigointi:** [← Edellinen: Moduuli 01 - Johdanto](../01-introduction/README.md) | [Takaisin pääsivulle](../README.md) | [Seuraava: Moduuli 03 - RAG →](../03-rag/README.md) +**Navigointi:** [← Edellinen: Module 01 - Johdanto](../01-introduction/README.md) | [Takaisin pääsivulle](../README.md) | [Seuraava: Module 03 - RAG →](../03-rag/README.md) --- **Vastuuvapauslauseke**: -Tämä asiakirja on käännetty käyttäen tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, tulee huomioida, että automaattikäännöksissä saattaa esiintyä virheitä tai epätarkkuuksia. Alkuperäinen asiakirja omalla kielellään on virallinen lähde. Tärkeissä tiedoissa suositellaan ammattilaisen tekemää ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä johtuvista väärinymmärryksistä tai tulkinnoista. +Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista. \ No newline at end of file diff --git a/translations/fi/03-rag/README.md b/translations/fi/03-rag/README.md index 9cb32541c..b342a2d2e 100644 --- a/translations/fi/03-rag/README.md +++ b/translations/fi/03-rag/README.md @@ -1,144 +1,143 @@ -# Moduuli 03: RAG (Hakua laajentava generointi) +# Moduuli 03: RAG (Retrieval-Augmented Generation) ## Sisällysluettelo -- [Video läpikäynti](../../../03-rag) -- [Mitä opit](../../../03-rag) -- [Esivaatimukset](../../../03-rag) -- [RAG:n ymmärtäminen](../../../03-rag) - - [Mikä RAG-lähestymistapa tätä opetusohjelmaa käyttää?](../../../03-rag) -- [Miten se toimii](../../../03-rag) - - [Dokumentin käsittely](../../../03-rag) - - [Embeddingsien luominen](../../../03-rag) - - [Semanttinen haku](../../../03-rag) - - [Vastauksen generointi](../../../03-rag) -- [Sovelluksen suorittaminen](../../../03-rag) -- [Sovelluksen käyttö](../../../03-rag) - - [Dokumentin lataaminen](../../../03-rag) - - [Kysymysten esittäminen](../../../03-rag) - - [Lähdeviitteiden tarkistaminen](../../../03-rag) - - [Kokeile kysymyksiä](../../../03-rag) -- [Keskeiset käsitteet](../../../03-rag) - - [Paloittelustrategia](../../../03-rag) - - [Samankaltaisuuspisteet](../../../03-rag) - - [Muistissa säilytys](../../../03-rag) - - [Kontekstin hallinta](../../../03-rag) -- [Milloin RAG on tärkeä](../../../03-rag) -- [Seuraavat askeleet](../../../03-rag) - -## Video läpikäynti - -Katso tämä live-sessio, joka selittää, miten alkaa työskennellä tämän moduulin kanssa: +- [Videoesittely](#videoesittely) +- [Mitä opit](#mitä-opit) +- [Esivaatimukset](#esivaatimukset) +- [RAG:n ymmärtäminen](#ragn-ymmärtäminen) + - [Minkä RAG-lähestymistavan tämä opas käyttää?](#minkä-rag-lähestymistavan-tämä-opas-käyttää) +- [Miten se toimii](#miten-se-toimii) + - [Dokumentin käsittely](#dokumentin-käsittely) + - [Upotusten luominen](#upotusten-luominen) + - [Semanttinen haku](#semanttinen-haku) + - [Vastauksen luominen](#vastauksen-generointi) +- [Sovelluksen suorittaminen](#sovelluksen-käynnistäminen) +- [Sovelluksen käyttö](#sovelluksen-käyttö) + - [Dokumentin lataaminen](#dokumentin-lataaminen) + - [Kysymysten esittäminen](#kysymysten-esittäminen) + - [Lähdeviitteiden tarkistaminen](#lähdeviitteiden-tarkistus) + - [Kokeile kysymyksiä](#kokeile-erilaisia-kysymyksiä) +- [Keskeiset käsitteet](#keskeiset-käsitteet) + - [Pilkkomisstrategia](#kappaleiden-jako) + - [Samanlaisuuspisteet](#samankaltaisuuspisteet) + - [Muistivarasto](#muistiin-tallennus) + - [Kontekstin ikkunan hallinta](#konteksti-ikkunan-hallinta) +- [Milloin RAG on tärkeä](#milloin-rag-on-tärkeä) +- [Seuraavat askeleet](#seuraavat-askeleet) + +## Videoesittely + +Katso tämä live-istunto, joka selittää kuinka pääset alkuun tämän moduulin kanssa: RAG with LangChain4j - Live Session ## Mitä opit -Edellisissä moduuleissa opit, kuinka käydä keskusteluja tekoälyn kanssa ja järjestää kehotteet tehokkaasti. Mutta on olemassa perustavanlaatuinen rajoitus: kielimallit tietävät vain sen, mitä ne oppivat harjoittelun aikana. Ne eivät voi vastata kysymyksiin yrityksesi käytännöistä, projektidokumentaatiosta tai muista tiedoista, joihin niitä ei ole koulutettu. +Aiemmissa moduuleissa opit keskustelemaan tekoälyn kanssa ja jäsentämään pyyntöjäsi tehokkaasti. Mutta on olemassa perustavanlaatuinen rajoitus: kielimallit tietävät vain sen, mitä ne oppivat harjoittelun aikana. Ne eivät voi vastata kysymyksiin yrityksesi käytännöistä, projektidokumentaatiostasi tai mistään tiedosta, jota niiden koulutuksessa ei ole ollut. -RAG (Retrieval-Augmented Generation) ratkaisee tämän ongelman. Sen sijaan, että yritettäisiin opettaa mallille tietosi (mikä on kallista ja epäkäytännöllistä), annat mallille kyvyn hakea tietoa dokumenteistasi. Kun joku esittää kysymyksen, järjestelmä löytää relevanttia tietoa ja lisää sen kehotteeseen. Malli vastaa sitten haetun kontekstin perusteella. +RAG (Retrieval-Augmented Generation) ratkaisee tämän ongelman. Sen sijaan, että yrittäisit opettaa mallille tietosi (mikä on kallista ja epäkäytännöllistä), annat mallille mahdollisuuden hakea dokumenteistasi. Kun joku esittää kysymyksen, järjestelmä löytää asiaankuuluvat tiedot ja liittää ne pyyntöön. Malli vastaa sitten haetun kontekstin pohjalta. -Ajattele RAG:ia kuin mallille annettavaa viitelähdekirjastoa. Kun kysyt kysymyksen, järjestelmä: +Ajattele RAG:ia mallin viitetietokirjastona. Kun esität kysymyksen, järjestelmä: -1. **Käyttäjän kysely** - Esität kysymyksen -2. **Embedding** - Muuntaa kysymyksen vektoriksi -3. **Vektorihaku** - Löytää samankaltaiset dokumenttipalat -4. **Kontekstin kokoaminen** - Lisää merkitykselliset palat kehotteeseen -5. **Vastaus** - LLM luo vastauksen kontekstin perusteella +1. **Käyttäjän kysely** – Sinä esität kysymyksen +2. **Upotus** – Muuntaa kysymyksesi vektoriksi +3. **Vektorihaku** – Löytää samankaltaiset dokumenttipalat +4. **Kontekstin koostaminen** – Lisää asiaankuuluvat palat pyyntöön +5. **Vastaus** – Suuri kielimalli luo vastauksen kontekstin perusteella -Näin mallin vastaukset perustuvat todelliseen dataasi sen sijaan, että ne vain nojaisivat koulutustietoonsa tai keksisivät vastauksia. +Tämä perustaa mallin vastaukset todellisiin tietoihisi sen sijaan, että se luottaisi vain harjoittelutietoihin tai keksisi vastauksia. ## Esivaatimukset -- Suoritettu [Moduuli 00 - Nopeasti alkuun](../00-quick-start/README.md) (Easy RAG -esimerkin käyttöönottoa varten, jota viitataan tässä moduulissa) -- Suoritettu [Moduuli 01 - Johdanto](../01-introduction/README.md) (Azure OpenAI -resurssit käyttöön otettuna, mukaan lukien `text-embedding-3-small` embedding-malli) -- `.env`-tiedosto juurihakemistossa Azure-tunnuksilla (luotu `azd up` komennolla Moduulissa 01) +- Valmis [Moduuli 01 - Johdanto](../01-introduction/README.md) (Azure OpenAI -resurssit käyttöön otettuna, mukaan lukien `text-embedding-3-small` -upotusmalli) +- `.env`-tiedosto juurihakemistossa Azure-tunnuksillasi (luotu `azd up` -komennolla moduulissa 01) -> **Huom:** Jos et ole suorittanut Moduulia 01, seuraa ensin siellä annettuja käyttöönotto-ohjeita. `azd up` -komento ottaa käyttöön sekä GPT-chat-mallin että tämän moduulin käyttämän embedding-mallin. +> **Huom:** Jos et ole vielä suorittanut moduulia 01, noudata ensin siellä annettuja käyttöönotto-ohjeita. `azd up` -komento ottaa käyttöön sekä GPT-chat-mallin että tämän moduulin käyttämän upotusmallin. ## RAG:n ymmärtäminen -Alla oleva kaavio havainnollistaa ydinkäsitettä: sen sijaan, että luotettaisiin ainoastaan mallin koulutusdataan, RAG antaa mallille viitelähdekirjaston dokumenteistasi, joita se voi käyttää ennen kunkin vastauksen generointia. +Alla oleva kaavio havainnollistaa ydinkonseptin: RAG ei perustu pelkästään mallin koulutusdataan, vaan antaa mallille viitetietokirjaston dokumenteistasi, joita se voi käyttää ennen jokaisen vastauksen luomista. -Mikä on RAG +What is RAG -*Tämä kaavio näyttää eron perinteisen LLM:n (joka arvaa koulutusdatan pohjalta) ja RAG-laajennetun LLM:n välillä (joka konsultoi ensin dokumenttejasi).* +*Tämä kaavio näyttää eron tavallisen LLM:n (joka arvaa koulutusdatan pohjalta) ja RAG-parannetun LLM:n (joka käyttää ensin dokumenttejasi) välillä.* -Näin prosessin osat liittyvät toisiinsa päästä päähän. Käyttäjän kysymys kulkee neljän vaiheen läpi — embedding, vektorihaku, kontekstin kokoaminen ja vastauksen generointi — jokainen rakentuu edellisen päälle: +Tässä on miten osat kytkeytyvät päästä päähän. Käyttäjän kysymys kulkee neljän vaiheen läpi — upotus, vektorihaku, kontekstin koostaminen ja vastauksen luominen — kukin rakentuu edellisen päälle: -RAG-arkkitehtuuri +RAG Architecture -*Tämä kaavio näyttää RAG-putken päästä päähän — käyttäjän kysely kulkee embeddingin, vektorihakujen, kontekstin kokoamisen ja vastauksen generoinnin läpi.* +*Tämä kaavio näyttää RAG-putken päästä päähän — käyttäjän kysely kulkee upotuksen, vektorihakemiston, kontekstin kokoamisen ja vastauksen luomisen kautta.* -Tämän moduulin loput osat käyvät läpi kukin vaiheen yksityiskohtaisesti, sisältäen koodin jota voit ajaa ja muokata. +Tämän moduulin loput osat käyvät jokaisen vaiheen läpi yksityiskohtaisesti, sisältäen koodin jota voit suorittaa ja muokata. -### Mikä RAG-lähestymistapa tätä opetusohjelmaa käyttää? +### Minkä RAG-lähestymistavan tämä opas käyttää? -LangChain4j tarjoaa kolme tapaa toteuttaa RAG, joista jokainen tarjoaa eri tason abstraktiota. Alla oleva kaavio vertailee niitä rinnakkain: +LangChain4j tarjoaa kolme tapaa toteuttaa RAG, kukin eri abstraktiotason kanssa. Alla oleva kaavio vertaa niitä rinnakkain: -Kolme RAG-lähestymistapaa LangChain4j:ssa +Three RAG Approaches in LangChain4j -*Tämä kaavio vertailee LangChain4j:n kolmea RAG-lähestymistapaa — Easy, Native ja Advanced — ja näyttää niiden keskeiset osat sekä käyttötarkoitukset.* +*Tämä kaavio vertailee LangChain4j:n kolmea RAG-lähestymistapaa — Easy, Native ja Advanced — näyttäen niiden keskeiset komponentit ja milloin niitä käytetään.* -| Lähestymistapa | Mitä se tekee | Kompromissi | +| Lähestymistapa | Mitä se tekee | Vaihtoehto | |---|---|---| -| **Easy RAG** | Kytkee kaiken automaattisesti `AiServices` ja `ContentRetriever` kautta. Määrittelet rajapinnan, liität haun, ja LangChain4j hoitaa taustalla dosenttien upotuksen, haun ja kehotteen kokoonpanon. | Vähiten koodia, mutta et näe mitä kukin vaihe tarkalleen tekee. | -| **Native RAG** | Kutsut upotusmallia, haet tallennuspaikasta, rakennat kehotteen ja generoit vastauksen – yksi näkyvä vaihe kerrallaan. | Enemmän koodia, mutta jokainen vaihe näkyvissä ja muokattavissa. | -| **Advanced RAG** | Käyttää `RetrievalAugmentor`-kehystä, jossa on plugarit kyselymuuntajille, reitittimille, uudelleenjärjestäjille ja sisällön injektoreille tuotantotason putkissa. | Maksimaalinen joustavuus, mutta merkittävästi monimutkaisempi. | +| **Easy RAG** | Kytkee kaiken automaattisesti `AiServices`- ja `ContentRetriever`-luokkien kautta. Merkitset rajapinnan, liität hakutoiminnon, ja LangChain4j hoitaa upotuksen, haun ja pyyntöjen kokoamisen taustalla. | Vähäinen koodimäärä, mutta et näe mitä kussakin vaiheessa tapahtuu. | +| **Native RAG** | Kutsut upotusmallin, haet tietovarastosta, rakennat pyynnön ja luot vastauksen itse — yksi selkeä vaihe kerrallaan. | Enemmän koodia, mutta jokainen vaihe on näkyvissä ja muokattavissa. | +| **Advanced RAG** | Käyttää `RetrievalAugmentor`-kehystä, jossa on vaihdettavissa olevia kyselyn muuntajia, reitittimiä, uudelleenjärjestelijöitä ja sisällön syöttäjiä tuotantotason putkistoihin. | Maksimaalinen joustavuus, mutta huomattavasti monimutkaisempi. | -**Tämä opetusohjelma käyttää Native-lähestymistapaa.** RAG-putken jokainen vaihe — kyselyn upotus, vektorikaupan haku, kontekstin kokoaminen ja vastauksen generointi — on kirjoitettu selkeästi tiedostossa [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Tämä on tarkoituksellista: oppimateriaaliin on tärkeämpää, että näet ja ymmärrät jokaisen vaiheen kuin että koodi olisi minimoitu. Kun olet mukava sen kanssa miten osat sopivat yhteen, voit siirtyä Easy RAG:n pariin nopeisiin prototyyppeihin tai Advanced RAG:n tuotantojärjestelmiin. +**Tämä opas käyttää Native-lähestymistapaa.** Jokainen RAG-putken vaihe — kyselyn upotus, vektorivaraston haku, kontekstin kokoaminen ja vastauksen luominen — on kirjoitettu näkyvästi tiedostossa [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Tämä on tarkoituksellista: oppimateriaalina on tärkeämpää, että näet ja ymmärrät jokaisen vaiheen kuin että koodi olisi minimoitu. Kun tunnet, miten osat liittyvät toisiinsa, voit siirtyä Easy RAG:iin nopeita prototyyppejä varten tai Advanced RAG:iin tuotantojärjestelmiin. -> **💡 Oletko jo nähnyt Easy RAG:n toiminnassa?** [Nopeasti alkuun -moduuli](../00-quick-start/README.md) sisältää Document Q&A -esimerkin ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), joka käyttää Easy RAG -lähestymistapaa — LangChain4j hoitaa upotuksen, haun ja kehotteen kokoonpanon automaattisesti. Tämä moduuli vie sen seuraavalle tasolle avaamalla putken, jotta voit itse nähdä ja hallita jokaista vaihetta. +> **💡 Kiinnostunut Easy RAG:stä?** LangChain4j tarjoaa myös *Easy RAG* -lähestymistavan, jossa `AiServices` ja `ContentRetriever` hoitavat upotuksen, haun ja pyyntöjen kokoamisen automaattisesti. Tämä moduuli käyttää selkeämpää reittiä — se avaa putken vaihe vaiheelta, jotta näet ja hallitset jokaisen osan itse. -Alla oleva kaavio näyttää Easy RAG -putken tuosta Quick Start -esimerkistä. Huomaa, kuinka `AiServices` ja `EmbeddingStoreContentRetriever` piilottavat kaiken monimutkaisuuden — lataat dokumentin, liität hakijan ja saat vastaukset. Tämän moduulin Native-lähestymistapa avaa jokaisen kätketyn vaiheen: +Alla oleva kaavio näyttää Easy RAG -putken. Huomaa miten `AiServices` ja `EmbeddingStoreContentRetriever` piilottavat monimutkaisuuden — lataa dokumentti, liitä hakutoiminto ja saa vastauksia. Tämä moduulin Native-lähestymistapa avaa nuo piilotetut vaiheet: -Easy RAG -putki - LangChain4j +Easy RAG Pipeline - LangChain4j -*Tämä kaavio näyttää Easy RAG -putken tiedostosta `SimpleReaderDemo.java`. Vertaa sitä tämän moduulin Native-lähestymistapaan: Easy RAG piilottaa upotuksen, haun ja kehotteen kokoamisen `AiServices` ja `ContentRetriever` taakse — lataat dokumentin, liität hakijan ja saat vastaukset. Tämä moduulin Native-lähestymistapa avaa putken, jolloin kutsut jokaisen vaiheen (upota, hae, kokoa konteksti, generoi) itse, tarjoten täyden näkyvyyden ja kontrollin.* +*Tämä kaavio näyttää Easy RAG-putken. Verrattuna tähän Native-lähestymistapaa, jota käytetään tässä moduulissa: Easy RAG piilottaa upotuksen, haun ja pyyntöjen kokoamisen `AiServices`in ja `ContentRetriever`in taakse — lataat dokumentin, liität hakijan ja saat vastauksia. Tämä moduuli avaa kyseisen putken, jotta voit kutsua jokaista vaihetta (upotus, haku, kontekstin kokoaminen, vastaus) itse, tarjoten täydellisen näkyvyyden ja hallinnan.* ## Miten se toimii -Tässä moduulissa RAG-putki jakautuu neljään vaiheeseen, jotka suoritetaan peräkkäin joka kerta kun käyttäjä esittää kysymyksen. Ensin ladattu dokumentti **jäsennetään ja pilkotaan paloiksi** hallittavaan muotoon. Nämä palat muunnetaan sitten **vektorisijoituksiksi** ja tallennetaan, jotta niitä voidaan vertailla matemaattisesti. Kun kysely saapuu, järjestelmä suorittaa **semanttisen haun** löytääkseen merkityksellisimmät osat, ja lopuksi välittää ne kontekstiksi LLM:lle **vastauksen generointia** varten. Alla olevat osiot käyvät läpi jokaisen vaiheen koodin ja kaavioiden kanssa. Katsotaanpa ensin dokumentin käsittelyä. +Tämän moduulin RAG-putki jakautuu neljään vaiheeseen, jotka suoritetaan peräkkäin aina, kun käyttäjä esittää kysymyksen. Ensin ladattu dokumentti **jäsennetään ja pilkotaan** hallittaviksi paloiksi. Nämä palat muunnetaan sitten **vektoriedustuksiksi (upotuksiksi)** ja varastoidaan, jotta niitä voidaan vertailla matemaattisesti. Kun kysely saapuu, järjestelmä suorittaa **semanttisen haun** löytääkseen merkityksellisimmät palat, ja lopuksi välittää ne kontekstina LLM:lle **vastauksen luomiseksi**. Seuraavat osiot käyvät jokaisen vaiheen läpi konkreettisen koodin ja kaavioiden kera. Aloitetaan ensimmäisestä vaiheesta. ### Dokumentin käsittely [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Kun lataat dokumentin, järjestelmä jäsentää sen (PDF tai pelkkä teksti), liittää metatietoja kuten tiedostonimen, ja pilkkoo sen paloiksi — pienemmiksi osiksi, jotka mahtuvat mukavasti mallin kontekstin ikkunaan. Nämä palat limittyvät hieman, jotta rajapinnoissa ei menetetä kontekstia. +Kun lataat dokumentin, järjestelmä jäsentää sen (PDF tai tavallinen teksti), liittää metatiedot kuten tiedostonimen, ja pilkkoo sen paloiksi — pienemmiksi osiksi, jotka mahtuvat mukavasti mallin kontekstin ikkunaan. Nämä palat limittäytyvät hieman, jotta konteksti ei katoa rajapinnoissa. ```java -// Jäsennä ladattu tiedosto ja kääri se LangChain4j-dokumenttiin +// Jäsennä ladattu tiedosto ja kiedo se LangChain4j-dokumenttiin Document document = Document.from(content, metadata); -// Jaa 300-tokenin paloiksi, joissa on 30-tokenin päällekkäisyys +// Jaa 300-tokenin paloihin, joissa on 30-tokenin päällekkäisyys DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Alla oleva kaavio havainnollistaa tätä visuaalisesti. Huomaa, miten jokainen pala jakaa joitain tokeneita naapurinsa kanssa — 30 tokenin limitys varmistaa, että tärkeä konteksti ei putoa rakoihin: +Alla oleva kaavio näyttää tämän toiminnan visuaalisesti. Huomaa miten jokainen pala jakaa joitain tokeneita naapureidensa kanssa — 30 tokenin limitys varmistaa, ettei tärkeä konteksti katkea: -Dokumenttipalojen pilkkominen +Document Chunking -*Tämä kaavio näyttää dokumentin pilkkomisen 300 tokenin paloihin, 30 tokenin limityksellä, jolloin konteksti säilyy paloissa.* +*Tämä kaavio näyttää dokumentin jakamisen 300 tokenin paloiksi, joissa on 30 tokenin limitys, joka säilyttää kontekstin palojen rajapinnoilla.* -> **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chatissa:** Avaa [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ja kysy: -> - "Miten LangChain4j pilkkoo dokumentit paloihin ja miksi limitys on tärkeää?" -> - "Mikä on optimaalinen palakoko eri dokumenttityypeille ja miksi?" -> - "Miten käsittelen dokumentteja useilla kielillä tai erikoisformaatilla?" +> **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chat -työkalulla:** Avaa [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ja kysy: +> - "Miten LangChain4j pilkkoo dokumentit paloiksi ja miksi limitys on tärkeää?" +> - "Mikä on optimaalinen palakoko eri dokumenttityypeille ja miksi?" +> - "Miten käsitellä monikielisiä dokumentteja tai erikoismuotoiluja?" -### Embeddingsien luominen +### Upotusten luominen [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Jokainen pala muunnetaan numeeriseen esitykseen, jota kutsutaan embeddingiksi — käytännössä merkityksen muuttajaksi numeroiksi. Embedding-malli ei ole "älykäs" kuten chat-malli; se ei voi seurata ohjeita, järkeillä tai vastata kysymyksiin. Sen sijaan se muuntaa tekstin matemaattiseen tilaan, jossa samankaltaiset merkitykset sijoittuvat lähelle toisiaan — "car" lähelle "automobile", "refund policy" lähelle "return my money". Ajattele chat-mallia ihmisenä, jonka kanssa voit puhua; embedding-malli on erittäin hyvä arkistointijärjestelmä. +Jokainen pala muunnetaan numeeriseksi edustukseksi, jota kutsutaan upotukseksi — käytännössä merkityksen muuntaminen luvuiksi. Upotusmalli ei ole "älykäs" siinä mielessä kuin chat-malli; se ei seuraa ohjeita, päätttele tai vastaa kysymyksiin. Se osaa kuitenkin kuvata tekstin matemaattisessa tilassa, jossa samanlaiset merkitykset sijaitsevat lähellä toisiaan — "auto" lähellä "ajoneuvoa", "palautuskäytäntö" lähellä "rahan palautusta". Voit ajatella chat-mallia ihmisenä, jolle voi puhua; upotusmalli on erittäin tehokas arkistojärjestelmä. -Alla oleva kaavio visualisoi tämän käsitteen — teksti syötetään sisään, numeeriset vektorit tulevat ulos, ja samankaltaiset merkitykset tuottavat lähellä sijaitsevia vektoreita: +Alla oleva kaavio havainnollistaa tätä konseptia — teksti menee sisään, numeeriset vektorit tulevat ulos, ja samankaltaiset merkitykset tuottavat lähekkäin sijaitsevia vektoreita: -Embedding-mallin konsepti +Embedding Model Concept -*Tämä kaavio näyttää miten embedding-malli muuntaa tekstin numeerisiksi vektoreiksi, sijoittaen saman merkityksen sanat kuten "car" ja "automobile" lähelle toisiaan vektoritilassa.* +*Tämä kaavio näyttää miten upotusmalli muuntaa tekstin numeerisiksi vektoreiksi, sijoittaen samankaltaiset merkitykset — kuten "auto" ja "ajoneuvo" — lähelle toisiaan vektoritilassa.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Alla oleva luokkakaavio näyttää kaksi erillistä virtaa RAG-putkessa ja LangChain4j-luokat, jotka toteuttavat ne. **Ingestiovirta** (suoritetaan kerran latauksen yhteydessä) pilkkoo dokumentin, muuntaa palat upotuksiksi ja tallentaa ne `.addAll()` metodilla. **Kyselyvirta** (suoritetaan aina kun käyttäjä kysyy) upottaa kysymyksen, etsii tallennuspaikasta `.search()` metodilla ja välittää osuneet kontekstit chat-mallille. Molemmat virrat kohtaavat jaetun `EmbeddingStore`-rajapinnan kautta: +Alla oleva luokkakaavio näyttää kaksi erillistä virtaa RAG-putkessa ja LangChain4j-luokat, jotka niitä toteuttavat. **Sisäänottovaihe** (suoritetaan kerran lataushetkellä) pilkkoo dokumentin, upottaa palat ja tallentaa ne `.addAll()`-metodilla. **Kyselyvaihe** (suoritetaan joka kerta kun käyttäjä kysyy) upottaa kysymyksen, hakee varastosta `.search()`-metodilla ja välittää löydetyn kontekstin chat-mallille. Molemmat virrat kohtaavat yhteisessä `EmbeddingStore` -rajapinnassa: -LangChain4j RAG -luokat +LangChain4j RAG Classes -*Tämä kaavio näyttää kaksi virtaa RAG-putkessa — datajen syöttö ja kysely — ja miten ne yhdistyvät yhteisen EmbeddingStoren kautta.* +*Tämä kaavio näyttää kaksi RAG-putken virtaa — sisäänoton ja kyselyn — ja niiden kytkeytymisen yhteisen EmbeddingStore-rajapinnan kautta.* -Kun embeddings on tallennettu, samankaltaiset sisällöt ryhmittyvät luontaisesti vektoritilassa yhteen. Alla oleva visualisointi näyttää, miten aihepiirit kuten Tekninen dokumentaatio, Liiketoiminnan säännöt ja Usein kysytyt kysymykset muodostavat selkeitä ryhmiä, mikä mahdollistaa semanttisen haun: +Kun upotukset on tallennettu, samankaltaiset sisällöt ryhmittyvät luonnollisesti toistensa läheisyyteen vektoritilassa. Alla oleva visualisointi osoittaa, miten aihepiireittäin liittyvät dokumentit muodostavat lähellä toisiaan olevia pisteitä, mikä tekee semanttisesta hausta mahdollista: -Vektorien upotustila +Vector Embeddings Space -*Tämä visualisointi näyttää miten aihealueisiin liittyvät dokumentit ryhmittyvät 3D-vektoritilassa.* +*Tämä visualisointi näyttää miten aiheiltaan samankaltaiset dokumentit ryhmittyvät toistensa lähelle 3D-vektoritilassa, aiheina mm. tekniset dokumentit, liiketoimintasäännöt ja FAQit.* -Kun käyttäjä hakee, järjestelmä seuraa neljää vaihetta: dokumentit upotetaan kerran, kysely upotetaan jokaisella haulla, kyselyvektori verrataan kaikkiin tallennettuihin vektoreihin kosinisimilariteetin avulla, ja palautetaan top-K parhaat osumat. Alla oleva kaavio näyttää jokaisen vaiheen ja niihin liittyvät LangChain4j-luokat: +Kun käyttäjä hakee, järjestelmä suorittaa neljä vaihetta: upottaa dokumentit kerran, upottaa kyselyn jokaisella haulla, vertaa kyselyvektoria kaikkia tallennettuja vektoreita vastaan kosinisen samankaltaisuuden avulla, ja palauttaa kärki-K parasta osumaa. Alla olevassa kaaviossa käydään läpi jokainen vaihe ja LangChain4j:n luokat mukaan lukien: -Embedding-haun vaiheet +Embedding Search Steps -*Tämä kaavio näyttää neljä vaihetta embedding-haussa: dokumenttien upotus, kyselyn upotus, vektorien vertailu kosinisimilariteetilla, ja parhaiden K tulosten palautus.* +*Tämä kaavio näyttää nelivaiheisen upotushakuprosessin: upotetaan dokumentit, upotetaan kysely, verrataan vektoreita kosinisamankaltaisuudella, ja palautetaan kärki-K tulokset.* ### Semanttinen haku [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Kun esität kysymyksen, kysymyksestä muodostetaan myös embedding. Järjestelmä vertaa kysymyksesi embeddingiä kaikkiin dokumenttipalojen embeddingsiin. Se löytää ne palat, joiden merkitys on lähimpänä — ei pelkästään avainsanojen vastaavuuden perusteella, vaan todellisen semanttisen samankaltaisuuden. +Kun esität kysymyksen, kysymyksesi myös muunnetaan upotukseksi. Järjestelmä vertaa kysymyksesi upotusta kaikkien dokumenttipalojen upotuksiin. Se löytää ne palat, joilla on merkitykseltään lähimpänä - ei pelkästään avainsanojen täsmäystä, vaan todellinen semanttinen samankaltaisuus. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Alla oleva kaavio vertaa semanttista hakua perinteiseen avainsanahakuun. Avainsanahaku sanalla "vehicle" ohittaa palan, jossa puhutaan "autoista ja kuorma-autoista", mutta semanttinen haku ymmärtää, että ne tarkoittavat samaa asiaa ja palauttaa sen korkealla pistemäärällä: +Alla oleva kaavio vertaa semanttista hakua perinteiseen avainsanahakuun. Avainsanahaku sanalle "ajoneuvo" ohittaa palan, jossa puhutaan "autoista ja kuorma-autoista", mutta semanttinen haku ymmärtää niiden tarkoittavan samaa asiaa ja palauttaa sen korkeasti pisteytettynä osumana: -Semanttinen haku +Semantic Search -*Tämä kaavio vertailee avainsanapohjaista ja semanttista hakua, näyttäen miten semanttinen haku löytää käsitteellisesti liittyvää sisältöä, vaikka tarkat avainsanat eroavat.* -Alla olevassa arvossa samankaltaisuutta mitataan kosinisamankaltaisuuden avulla — käytännössä kysytään "osoittavatko nämä kaksi nuolta samaan suuntaan?" Kaksi tekstipalasta voivat käyttää täysin eri sanoja, mutta jos ne tarkoittavat samaa asiaa, niiden vektorit osoittavat samaan suuntaan ja pisteet ovat lähellä 1.0: +*Tämä kaavio vertaa avainsanapohjaista hakua semanttiseen hakuun, näyttäen miten semanttinen haku löytää käsitteellisesti liittyvää sisältöä vaikka tarkat avainsanat eroavat.* -Kosinisamankaltaisuus +Tietokoneen mittarina samankaltaisuudelle käytetään kosinista samankaltaisuutta — käytännössä kysyen "osoittavatko nämä kaksi nuolta samaan suuntaan?" Kaksi palaa voivat käyttää täysin erilaisia sanoja, mutta jos ne tarkoittavat samaa, niiden vektorit osoittavat samaan suuntaan ja arvo on lähellä 1.0: -*Tämä kaavio havainnollistaa kosinisamankaltaisuutta upotettujen vektoreiden välisenä kulmana — enemmän linjassa olevat vektorit saavat pisteet lähempänä 1.0, mikä osoittaa suurempaa semanttista samankaltaisuutta.* +Cosine Similarity +*Tämä kaavio havainnollistaa kosinissimilariteettia upotusvektorien välisenä kulmana — mitä paremmin kohdistuneet vektorit, sitä lähempänä pistemäärä on 1.0, mikä tarkoittaa suurempaa semanttista samankaltaisuutta.* -> **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chatilla:** Avaa [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ja kysy: +> **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chatin kanssa:** Avaa [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ja kysy: > - "Miten samankaltaisuushaku toimii upotusten kanssa ja mikä määrää pistemäärän?" -> - "Mitä samankaltaisuuskynnystä minun tulisi käyttää ja miten se vaikuttaa tuloksiin?" -> - "Miten käsittelen tilanteet, joissa ei löydy relevantteja dokumentteja?" +> - "Mikä samankaltaisuuskynnys minun pitäisi käyttää ja miten se vaikuttaa tuloksiin?" +> - "Miten käsittelen tapauksia, joissa ei löydy relevantteja dokumentteja?" -### Vastausten tuottaminen +### Vastauksen generointi [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Merkityksellisimmät tekstipalaset kootaan rakenteelliseksi kehotteeksi, joka sisältää selkeät ohjeet, haetun kontekstin ja käyttäjän kysymyksen. Malli lukee nämä tietyt palaset ja vastaa niiden perusteella — se voi käyttää vain sitä tietoa, mikä sillä on edessään, mikä estää harhan muodostumisen. +Osuvimmat kappaleet koottaan rakenteelliseksi kehotteeksi, joka sisältää selkeät ohjeet, haetun kontekstin ja käyttäjän kysymyksen. Malli lukee nämä tietyt kappaleet ja vastaa niiden pohjalta — se voi käyttää vain näkyvissä olevia tietoja, mikä estää hallusinaatiot. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Alla oleva kaavio näyttää tämän kokoamisen toiminnassa — haun vaiheessa parhaat pisteet saaneet tekstipalaset sijoitetaan kehotteen malliin, ja `OpenAiOfficialChatModel` tuottaa perustellun vastauksen: +Alla oleva kaavio näyttää tämän kokoonpanon toiminnassa — hakuvaiheen parhaiten pisteytetyt kappaleet upotetaan kehottepohjaan, ja `OpenAiOfficialChatModel` tuottaa perustellun vastauksen: -Kontekstin kokoaminen +Context Assembly -*Tässä kaaviossa näytetään, miten parhaiten pisteytetyt tekstipalaset kootaan rakenteelliseksi kehotteeksi, jolloin malli voi tuottaa perustellun vastauksen datastasi.* +*Tämä kaavio näyttää, miten parhaiten pisteytetyt kappaleet kootaan rakenteelliseksi kehotteeksi, jolloin malli voi luoda perustellun vastauksen datastasi.* ## Sovelluksen käynnistäminen -**Tarkista käyttöönotto:** +**Varmista käyttöönotto:** -Varmista, että juuri hakemistossa on `.env`-tiedosto, jossa on Azure-tunnukset (luotu moduulissa 01). Suorita tämä moduulin hakemistosta (`03-rag/`): +Varmista, että `.env`-tiedosto on juurikansiossa Azure-tunnistetiedoilla (luotu Modulissa 01). Suorita tämä moduulihakemistosta (`03-rag/`): **Bash:** ```bash @@ -261,27 +260,27 @@ Get-Content ..\.env # Tulisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Käynnistä sovellus:** -> **Huom:** Jos olet jo käynnistänyt kaikki sovellukset käyttämällä `./start-all.sh` juuri hakemistosta (kuten moduulissa 01 kuvattu), tämä moduuli on jo käynnissä portissa 8081. Voit ohittaa alla olevat käynnistyskomennot ja mennä suoraan osoitteeseen http://localhost:8081. +> **Huom:** Jos olet jo käynnistänyt kaikki sovellukset käyttämällä `./start-all.sh` juurikansiosta (kuten Modulissa 01 kuvattu), tämä moduuli on jo käynnissä portissa 8081. Voit ohittaa alla olevat käynnistyskomennot ja siirtyä suoraan osoitteeseen http://localhost:8081. **Vaihtoehto 1: Spring Boot Dashboardin käyttäminen (suositeltu VS Code -käyttäjille)** -Kehityssäiliö sisältää Spring Boot Dashboard -laajennuksen, joka tarjoaa visuaalisen käyttöliittymän kaikkien Spring Boot -sovellusten hallintaan. Löydät sen Activity Barista VS Codessa vasemmalta (etsi Spring Boot -kuvaketta). +Kehityssäiliö sisältää Spring Boot Dashboard -laajennuksen, joka tarjoaa visuaalisen käyttöliittymän kaikkien Spring Boot -sovellusten hallintaan. Löydät sen VS Coden vasemmasta sivupalkista (etsi Spring Boot -kuvake). Spring Boot Dashboardista voit: -- Nähdä kaikki käytettävissä olevat Spring Boot -sovellukset työtilassa -- Käynnistää/pysäyttää sovelluksia yhdellä napsautuksella +- Näyttää kaikki käytettävissä olevat Spring Boot -sovellukset työtilassa +- Käynnistää/lopettaa sovelluksia yhden napsautuksen avulla - Katsoa sovelluslokeja reaaliajassa -- Seurata sovellusten tilaa +- Valvoa sovellusten tilaa -Napsauta pelipainiketta "rag" vierestä käynnistääksesi tämän moduulin, tai käynnistä kaikki moduulit kerralla. +Klikkaa "rag"-moduulin vieressä olevaa toistopainiketta käynnistääksesi tämän moduulin, tai käynnistä kaikki moduulit kerralla. Spring Boot Dashboard -*Tässä kuvakaappauksessa näkyy Spring Boot Dashboard VS Codessa, jossa voit käynnistää, pysäyttää ja valvoa sovelluksia visuaalisesti.* +*Tämä kuvakaappaus näyttää Spring Boot Dashboardin VS Codessa, jossa voit käynnistää, pysäyttää ja valvoa sovelluksia visuaalisesti.* -**Vaihtoehto 2: Shell-skriptien käyttäminen** +**Vaihtoehto 2: Kuoriskriptien käyttäminen** -Käynnistä kaikki web-sovellukset (moduulit 01-04): +Käynnistä kaikki web-sovellukset (moduulit 01–04): **Bash:** ```bash @@ -309,7 +308,7 @@ cd 03-rag .\start.ps1 ``` -Molemmat skriptit lataavat automaattisesti ympäristömuuttujat juuren `.env`-tiedostosta ja rakentavat JAR-tiedostot tarvittaessa. +Molemmat skriptit lataavat automaattisesti ympäristömuuttujat juurikansion `.env`-tiedostosta ja kokoavat JAR-tiedostot, jos niitä ei vielä ole. > **Huom:** Jos haluat rakentaa kaikki moduulit manuaalisesti ennen käynnistystä: > @@ -318,16 +317,16 @@ Molemmat skriptit lataavat automaattisesti ympäristömuuttujat juuren `.env`-ti > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Avaa selain ja mene osoitteeseen http://localhost:8081. +Avaa selaimessasi osoite http://localhost:8081. -**Pysäytys:** +**Sovelluksen pysäyttäminen:** **Bash:** ```bash @@ -343,83 +342,83 @@ cd .. && ./stop-all.sh # Kaikki moduulit cd ..; .\stop-all.ps1 # Kaikki moduulit ``` -## Sovelluksen käyttäminen +## Sovelluksen käyttö -Sovellus tarjoaa verkkokäyttöliittymän dokumenttien lataamiseen ja kysymyksiin. +Sovellus tarjoaa web-käyttöliittymän dokumenttien lataamiseen ja kysymysten esittämiseen. -RAG-sovelluksen käyttöliittymä +RAG Application Interface -*Tämä kuvakaappaus näyttää RAG-sovelluksen käyttöliittymän, jossa voit ladata dokumentteja ja esittää kysymyksiä.* +*Tämä kuvakaappaus näyttää RAG-sovelluksen käyttöliittymän, jossa lataat dokumentteja ja esität kysymyksiä.* ### Dokumentin lataaminen -Aloita lataamalla dokumentti — TXT-tiedostot toimivat parhaiten testauksessa. Tässä hakemistossa on mukana `sample-document.txt`, joka sisältää tietoja LangChain4j:n ominaisuuksista, RAG:n toteutuksesta ja parhaista käytännöistä — täydellinen testausjärjestelmäksi. +Aloita lataamalla dokumentti – TXT-tiedostot sopivat testiä varten parhaiten. Tässä hakemistossa on mukana `sample-document.txt`, joka sisältää tietoa LangChain4j-ominaisuuksista, RAG-toteutuksesta ja parhaista käytännöistä – täydellinen järjestelmän testaamiseen. -Järjestelmä käsittelee dokumenttisi, pilkkoo sen tekstipalasiin ja luo upotukset jokaiselle palaselle. Tämä tapahtuu automaattisesti latauksen yhteydessä. +Järjestelmä käsittelee dokumenttisi, jakaa sen kappaleisiin ja luo kullekin kappaleelle upotukset. Tämä tapahtuu automaattisesti latauksen yhteydessä. -### Kysy kysymyksiä +### Kysymysten esittäminen -Esitä nyt konkreettisia kysymyksiä dokumentin sisällöstä. Kokeile jotain faktapohjaista, joka on selkeästi dokumentissa mainittu. Järjestelmä hakee relevantit palaset, liittää ne kehotteeseen ja tuottaa vastauksen. +Esitä nyt tarkkoja kysymyksiä dokumentin sisällöstä. Kokeile faktoja, jotka ovat selvästi mainittu dokumentissa. Järjestelmä hakee osuvat kappaleet, lisää ne kehotteeseen ja tuottaa vastauksen. -### Tarkista lähdemerkinnät +### Lähdeviitteiden tarkistus -Huomaa, että jokainen vastaus sisältää lähdeviitteitä samankaltaisuuspisteillä. Nämä pisteet (0–1) osoittavat, kuinka relevantti kukin pala oli kysymykseesi nähden. Korkeammat pisteet tarkoittavat parempia osumia. Näin voit varmistaa vastauksen vastaavuuden lähdemateriaaliin. +Huomaa, että jokainen vastaus sisältää lähdelähteet ja samankaltaisuuspisteet. Nämä pisteet (0–1) kertovat, kuinka relevantti kukin kappale oli kysymykseesi nähden. Korkeammat pisteet merkitsevät parempia osumia. Tämä auttaa sinua arvioimaan vastauksen luotettavuutta lähdemateriaalin perusteella. -RAG-kyselytulokset +RAG Query Results -*Tämä kuvakaappaus näyttää kyselytulokset, generoitu vastauksen, lähdemerkinnät ja merkityspisteet jokaiselle haetulle tekstipalalle.* +*Tässä kuvakaappauksessa näkyvät kyselytulokset, joissa ovat generoitu vastaus, lähdeviitteet ja kunkin haetun kappaleen merkityspisteet.* ### Kokeile erilaisia kysymyksiä Kokeile erilaisia kysymystyyppejä: - Tarkat faktat: "Mikä on pääaihe?" - Vertailut: "Mikä on ero X:n ja Y:n välillä?" -- Yhteenvedot: "Tiivistä tärkeimmät kohdat Z:stä" +- Yhteenveto: "Tiivistä tärkeimmät kohdat liittyen Z:ään" Seuraa, miten merkityspisteet muuttuvat sen mukaan, kuinka hyvin kysymyksesi vastaa dokumentin sisältöä. ## Keskeiset käsitteet -### Tekstipalojen muodostaminen +### Kappaleiden jako -Dokumentit jaetaan 300 tokenin tekstipalasiin, joissa on 30 tokenin päällekkäisyys. Tämä tasapaino varmistaa, että jokaisella palasella on riittävästi kontekstia ollakseen merkityksellinen, mutta ne pysyvät tarpeeksi pieniä, jotta useita palasia mahtuu kehotteeseen. +Dokumentit jaetaan 300 tokenin kappaleiksi, joissa on 30 tokenin päällekkäisyys. Tämä tasapaino takaa, että jokaisessa kappaleessa on riittävästi kontekstia ollakseen merkityksellinen, mutta kappaleet pysyvät tarpeeksi pieniä, jotta useita kappaleita voi sisällyttää kehotteeseen. ### Samankaltaisuuspisteet -Jokaisella haetulla tekstipalalla on samankaltaisuuspiste, jonka arvo on 0–1 ja joka osoittaa, kuinka tarkasti se vastaa käyttäjän kysymystä. Alla oleva kaavio visualisoi pistemäärien vaihtelut ja miten järjestelmä käyttää niitä tulosten suodattamiseen: +Jokainen haettu kappale sisältää samankaltaisuuspisteen välillä 0–1, joka ilmaisee, kuinka hyvin se vastaa käyttäjän kysymystä. Alla oleva kaavio havainnollistaa pistealueita ja miten järjestelmä käyttää niitä tulosten suodattamiseen: -Samankaltaisuuspisteet +Similarity Scores -*Tämä kaavio näyttää pistemääräalueet 0:sta 1:een, vähimmäiskynnyksen ollessa 0.5, joka suodattaa pois ei-relevantit tekstipalaset.* +*Tämä kaavio näyttää pistemäärien alueet 0–1, minimikynnyksen 0.5, joka suodattaa pois epäolennaiset kappaleet.* -Pisteet vaihtelevat välillä 0–1: -- 0.7–1.0: Erittäin relevantti, täsmää tarkasti +Pisteet vaihtelevat 0:sta 1:een: +- 0.7–1.0: Erittäin relevantti, täysi vastaavuus - 0.5–0.7: Relevantti, hyvä konteksti - Alle 0.5: Suodatettu pois, liian erilainen -Järjestelmä hakee vain vähimmäiskynnyksen ylittävät tekstipalaset laadun varmistamiseksi. +Järjestelmä hakee vain kappaleet, jotka ylittävät minimikynnyksen laadun varmistamiseksi. -Upotukset toimivat hyvin, kun merkitys ryhmittyy selkeästi, mutta niillä on sokeita pisteitä. Alla oleva kaavio näyttää yleisimmät virhetilanteet — liian isot tekstipalaset tuottavat epäselvät vektorit, liian pienillä paikoilla ei ole kontekstia, epämääräiset termit osoittavat useisiin ryhmiin, ja täsmähaku (tunnisteet, osanumerot) ei toimi lainkaan upotusten kanssa: +Upotukset toimivat hyvin, kun merkitykset ryhmittyvät selkeästi, mutta niillä on myös heikkouksia. Alla oleva kaavio näyttää yleiset epäonnistumistilanteet — liian suuret kappaleet tuottavat epämääräisiä vektoreita, liian pienet kappaleet eivät anna riittävästi kontekstia, monitulkintaiset termit ohjaavat useisiin ryhmiin, ja täsmähaku (ID:t, osanumero) ei toimi lainkaan upotusten kanssa: -Upotusvirheiden tyypit +Embedding Failure Modes -*Tämä kaavio näyttää yleisimmät upotusvirheiden tyypit: liian isot tai pienet tekstipalaset, epämääräiset termit, jotka osoittavat useisiin ryhmiin, sekä täsmähaku kuten tunnisteet.* +*Tämä kaavio näyttää yleiset upotusten epäonnistumistilat: liian isot kappaleet, liian pienet kappaleet, monitulkintaiset termit, ja täsmähaku kuten ID-tunnukset.* -### Muistissa oleva tallennus +### Muistiin tallennus -Tässä moduulissa käytetään yksinkertaisuuden vuoksi muistipohjaista tallennusta. Kun käynnistät sovelluksen uudelleen, ladatut dokumentit katoavat. Tuotantojärjestelmissä käytetään pysyviä vektoritietokantoja, kuten Qdrant tai Azure AI Search. +Tämä moduuli käyttää yksinkertaisuuden vuoksi muistipohjaista tallennusta. Kun käynnistät sovelluksen uudelleen, ladatut dokumentit katoavat. Tuotantojärjestelmissä käytetään pysyviä vektoripohjaisia tietokantoja kuten Qdrant tai Azure AI Search. -### Kontekstiikkunan hallinta +### Konteksti-ikkunan hallinta -Jokaisella mallilla on maksimi kontekstiikkunan koko. Et voi sisällyttää kaikkia tekstipaloja suurista dokumenteista. Järjestelmä hakee viisi parhaimmin relevanttia tekstipalasta (oletus 5) pitäen kontekstin koossa vastauksen tarkkuuden takaamiseksi. +Jokaisella mallilla on maksimikonteksti-ikkuna. Et voi sisällyttää jokaista kappaletta isosta dokumentista. Järjestelmä hakee tärkeimmät N relevanttia kappaletta (oletuksena 5) pysyäkseen rajoissa ja tarjotakseen riittävästi kontekstia tarkkojen vastausten tuottamiseen. -## Milloin RAG on olennaista +## Milloin RAG on tärkeä -RAG ei ole aina oikea lähestymistapa. Alla oleva päätöspuu auttaa sinua päättämään, milloin RAG tuo lisäarvoa, ja milloin yksinkertaisemmat lähestymistavat — kuten sisällön suora sisällyttäminen kehotteeseen tai mallin sisäisen tiedon hyödyntäminen — riittävät: +RAG ei aina ole oikea lähestymistapa. Alla oleva päätöksentekokaavio auttaa sinua arvioimaan, milloin RAG lisää arvoa ja milloin yksinkertaisemmat tavat — kuten sisällön suora lisääminen kehotteeseen tai mallin sisäänrakennetun tiedon käyttäminen — riittävät: -Milloin käyttää RAG:ia +When to Use RAG -*Tämä kaavio näyttää päätöspuun siitä, milloin RAG tuo lisäarvoa verrattuna yksinkertaisempiin menetelmiin.* +*Tämä kaavio näyttää päätöksenteko-ohjeen siitä, milloin RAG lisää arvoa ja milloin yksinkertaisemmat lähestymistavat riittävät.* ## Seuraavat askeleet @@ -427,11 +426,11 @@ RAG ei ole aina oikea lähestymistapa. Alla oleva päätöspuu auttaa sinua pä --- -**Navigointi:** [← Edellinen: Moduuli 02 - Kehoteinsinööri](../02-prompt-engineering/README.md) | [Takaisin pääsivulle](../README.md) | [Seuraava: Moduuli 04 - Työkalut →](../04-tools/README.md) +**Navigointi:** [← Edellinen: Moduuli 02 - Kehote-Engineerointi](../02-prompt-engineering/README.md) | [Takaisin pääsivulle](../README.md) | [Seuraava: Moduuli 04 - Työkalut →](../04-tools/README.md) --- **Vastuuvapauslauseke**: -Tämä asiakirja on käännetty tekoälykäännöspalvelulla [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, huomioithan, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäistä asiakirjaa sen alkuperäiskielellä tulee pitää virallisena lähteenä. Tärkeässä tiedossa suositellaan ammattilaisen tekemää ihmiskäännöstä. Emme ole vastuussa tästä käännöksestä aiheutuvista väärinymmärryksistä tai virhetulkinnoista. +Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista. \ No newline at end of file diff --git a/translations/fi/04-tools/README.md b/translations/fi/04-tools/README.md index 0c8d8222c..bc72acdc8 100644 --- a/translations/fi/04-tools/README.md +++ b/translations/fi/04-tools/README.md @@ -1,84 +1,84 @@ -# Moduuli 04: AI-agentit työkaluilla +# Moduuli 04: Tekoälyagentit työkalujen kanssa ## Sisällysluettelo -- [Videoesittely](../../../04-tools) -- [Mitä opit](../../../04-tools) -- [Esivaatimukset](../../../04-tools) -- [Ymmärtäminen: AI-agentit työkaluilla](../../../04-tools) -- [Kuinka työkalukutsut toimivat](../../../04-tools) - - [Työkalujen määrittelyt](../../../04-tools) - - [Päätöksenteko](../../../04-tools) - - [Suoritus](../../../04-tools) - - [Vastauksen luominen](../../../04-tools) - - [Arkkitehtuuri: Spring Boot automaattijohtaminen](../../../04-tools) -- [Työkaluketjutus](../../../04-tools) -- [Sovelluksen käynnistäminen](../../../04-tools) -- [Sovelluksen käyttö](../../../04-tools) - - [Kokeile yksinkertaista työkalun käyttöä](../../../04-tools) - - [Testaa työkaluketjutusta](../../../04-tools) - - [Katso keskustelun kulku](../../../04-tools) - - [Kokeile erilaisia pyyntöjä](../../../04-tools) -- [Keskeiset käsitteet](../../../04-tools) - - [ReAct-malli (järjestelmällinen ajattelu ja toiminta)](../../../04-tools) - - [Työkalujen kuvaukset ovat tärkeitä](../../../04-tools) - - [Istunnon hallinta](../../../04-tools) - - [Virheenkäsittely](../../../04-tools) -- [Saatavilla olevat työkalut](../../../04-tools) -- [Milloin käyttää työkalupohjaisia agenteja](../../../04-tools) -- [Työkalut vs RAG](../../../04-tools) -- [Seuraavat askeleet](../../../04-tools) - -## Videoesittely - -Katso tämä suora sessio, joka selittää, kuinka aloittaa tämän moduulin kanssa: - -AI Agents with Tools and MCP - Live Session +- [Videokävely](#videokävely) +- [Mitä opit](#mitä-opit) +- [Esivaatimukset](#esivaatimukset) +- [Tekoälyagenttien ymmärtäminen työkaluilla](#tekoälyagenttien-ymmärtäminen-työkaluilla) +- [Kuinka työkalukutsu toimii](#kuinka-työkalukutsu-toimii) + - [Työkalumääritelmät](#työkalumääritelmät) + - [Päätöksenteko](#päätöksenteko) + - [Suoritus](#suoritus) + - [Vastauksen generointi](#vastauksen-generointi) + - [Arkkitehtuuri: Spring Bootin automaattinen törmäys](#arkkitehtuuri-spring-bootin-automaattinen-törmäys) +- [Työkaluketjutus](#työkaluketjutus) +- [Sovelluksen suorittaminen](#sovelluksen-suorittaminen) +- [Sovelluksen käyttäminen](#sovelluksen-käyttö) + - [Kokeile yksinkertaista työkalun käyttöä](#kokeile-yksinkertaista-työkalun-käyttöä) + - [Testaa työkaluketjutusta](#testaa-työkaluketjutusta) + - [Näe keskustelun kulku](#katso-keskustelun-kulkua) + - [Kokeile erilaisia pyyntöjä](#kokeile-erilaisia-pyyntöjä) +- [Keskeiset käsitteet](#keskeiset-käsitteet) + - [ReAct-malli (Päättely ja toiminta)](#react-malli-päättely-ja-toiminta) + - [Työkalujen kuvaukset ovat tärkeitä](#tärkeitä-työkalukuvauksia) + - [Istunnon hallinta](#istunnon-hallinta) + - [Virheiden käsittely](#virheenkäsittely) +- [Saatavilla olevat työkalut](#saatavilla-olevat-työkalut) +- [Milloin käyttää työkalupohjaisia agentteja](#milloin-käyttää-työkalupohjaisia-agentteja) +- [Työkalut vs RAG](#työkalut-vs-rag) +- [Seuraavat askeleet](#seuraavat-askeleet) + +## Videokävely + +Katso tämä live-istunto, joka selittää miten aloittaa tämän moduulin kanssa: + +Tekoälyagentit työkaluilla ja MCP - Live-istunto ## Mitä opit -Tähän mennessä olet oppinut käymään keskusteluja tekoälyn kanssa, rakentamaan kehotteet tehokkaasti ja perustamaan vastaukset asiakirjoihisi. Mutta on vielä yksi perustavanlaatuinen rajoitus: kielimallit pystyvät tuottamaan vain tekstiä. Ne eivät voi tarkistaa säätä, suorittaa laskelmia, hakea tietokannoista tai olla vuorovaikutuksessa ulkoisten järjestelmien kanssa. +Tähän mennessä olet oppinut käymään keskusteluja tekoälyn kanssa, rakentamaan kehotteita tehokkaasti ja perustamaan vastauksia dokumentteihisi. Mutta on vielä yksi perusrajoitus: kielimallit voivat ainoastaan generoida tekstiä. Ne eivät voi tarkistaa säätä, suorittaa laskutoimituksia, kysyä tietokannoista tai olla vuorovaikutuksessa ulkoisten järjestelmien kanssa. -Työkalut muuttavat tämän. Antamalla mallille pääsyn funktioihin, joita se voi kutsua, muutat sen tekstintuottajasta agentiksi, joka voi toimia. Malli päättää, milloin se tarvitsee työkalua, mitä työkalua käyttää ja mitä parametreja antaa. Koodisi suorittaa funktion ja palauttaa tuloksen. Malli sisällyttää tämän tuloksen vastaukseensa. +Työkalut muuttavat tätä. Antamalla mallille pääsyn kutsuttaviin toimintoihin, muutat sen tekstigeneraattorista agentiksi, joka voi toimia. Malli päättää, milloin se tarvitsee työkalun, mitä työkalua käyttää ja mitä parametreja antaa. Koodisi suorittaa funktion ja palauttaa tuloksen. Malli sisällyttää tämän tuloksen vastaukseensa. ## Esivaatimukset - Suoritettu [Moduuli 01 - Johdanto](../01-introduction/README.md) (Azure OpenAI -resurssit otettu käyttöön) -- Suositellaan suoritettuja aiempia moduuleja (tässä moduulissa viitataan [RAG-käsitteisiin Moduulista 03](../03-rag/README.md) vertailussa Tools vs RAG) -- `.env`-tiedosto juurihakemistossa Azure-tunnuksilla (luotu `azd up` -komennolla Moduulissa 01) +- Edellisten moduulien suorittaminen on suositeltavaa (tämä moduuli viittaa [RAG-konsepteihin Moduulista 03](../03-rag/README.md) Työkalut vs RAG -vertailussa) +- `.env`-tiedosto juurihakemistossa Azure-tunnuksilla (luotu komennolla `azd up` Moduulissa 01) -> **Huom:** Jos et ole suorittanut Moduulia 01, seuraa siellä annettuja käyttöönotto-ohjeita ensin. +> **Huom:** Jos et ole suorittanut Moduulia 01, noudata ensin siellä annettuja asennusohjeita. -## Ymmärtäminen: AI-agentit työkaluilla +## Tekoälyagenttien ymmärtäminen työkaluilla -> **📝 Huom:** Tässä moduulissa termi "agentit" tarkoittaa työkaluja kutsuvilla ominaisuuksilla vahvistettuja tekoälyavustajia. Tämä eroaa **Agentic AI** -malleista (autonomiset agentit, joilla on suunnittelu, muisti ja monivaiheinen päättely), joita käsittelemme [Moduulissa 05: MCP](../05-mcp/README.md). +> **📝 Huom:** Tässä moduulissa termi "agentit" viittaa tekoälyavustajiin, jotka on parannettu työkalukutsutoiminnoilla. Tämä eroaa **Agentic AI** -malleista (autonomiset agentit, joilla on suunnittelu, muisti ja monivaiheinen päättely), joita käsittelemme [Moduulissa 05: MCP](../05-mcp/README.md). -Ilman työkaluja kielimalli voi luoda tekstiä vain koulutusdatastaan. Kysy säästä ja sen täytyy arvata. Anna työkalut, niin se voi kutsua sää-API:ta, tehdä laskutoimituksia tai hakea tietokannasta — ja kutoa nämä todelliset tulokset vastaukseensa. +Ilman työkaluja kielimalli voi ainoastaan generoida tekstiä koulutusdatastaan. Kysy siltä tämänhetkinen sää, niin sen pitää veikata. Anna sille työkaluja, niin se voi kutsua sää-API:a, suorittaa laskutoimituksia tai kysyä tietokannasta — ja kietoa nämä todelliset tulokset vastaukseensa. -Ilman työkaluja vs työkalujen kanssa +Ilman työkaluja vs Työkalujen kanssa -*Ilman työkaluja malli vain arvaa — työkaluilla se voi kutsua API:ita, suorittaa laskelmia ja palauttaa reaaliaikaista tietoa.* +*Ilman työkaluja malli vain veikkaa — työkaluilla se voi kutsua API:ita, suorittaa laskuja ja palauttaa reaaliaikaista dataa.* -AI-agentti työkaluilla noudattaa **ReAct** (Reasoning and Acting) -mallia. Malli ei vain vastaa — se miettii, mitä tarvitsee, toimii kutsumalla työkalua, havaitsee tuloksen ja päättää sitten, toimiiko uudestaan vai antaa lopullisen vastauksen: +Tekoälyagentti työkaluilla noudattaa **Päättely ja Toiminta (ReAct)** -mallia. Malli ei vain vastaa — se miettii, mitä se tarvitsee, toimii kutsumalla työkalua, tarkkailee tulosta ja päättää, toimiiko uudelleen vai antaa lopullisen vastauksen: -1. **Päättele** — Agentti analysoi käyttäjän kysymyksen ja määrittää tarvittavat tiedot -2. **Toimi** — Agentti valitsee oikean työkalun, luo oikeat parametrit ja kutsuu sitä -3. **Havaitse** — Agentti vastaanottaa työkalun tuloksen ja arvioi sen -4. **Toista tai Vastaa** — Jos tarvitaan lisää tietoa, agentti kiertää uudestaan; muuten muodostaa luonnollisen kielen vastauksen +1. **Päättele** — Agentti analysoi käyttäjän kysymyksen ja määrittää, mitä tietoa se tarvitsee +2. **Toimi** — Agentti valitsee sopivan työkalun, generoi oikeat parametrit ja kutsuu sitä +3. **Tarkkaile** — Agentti vastaanottaa työkalun tuloksen ja arvioi sen +4. **Toista tai vastaa** — Jos lisätietoa tarvitaan, agentti palaa aloitukseen; muuten se kokoaa luonnollisen kielen vastauksen -ReAct Pattern +ReAct-malli -*ReAct-sykli — agentti päättää mitä tehdä, toimii kutsumalla työkalua, havaitsee tuloksen ja toistaa kunnes voi antaa lopullisen vastauksen.* +*ReAct-sykli — agentti päättää mitä tehdä, toimii kutsumalla työkalua, tarkkailee tulosta ja toistaa kunnes se voi antaa lopullisen vastauksen.* -Tämä tapahtuu automaattisesti. Määrittelet työkalut ja niiden kuvaukset. Malli hoitaa päätöksenteon siitä, milloin ja miten niitä käyttää. +Tämä tapahtuu automaattisesti. Määrittelet työkalut ja niiden kuvaukset. Malli huolehtii päätöksenteosta siitä, milloin ja miten työkaluja käytetään. -## Kuinka työkalukutsut toimivat +## Kuinka työkalukutsu toimii -### Työkalujen määrittelyt +### Työkalumääritelmät [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Määrittelet funktiot selkeine kuvauksineen ja parametri-spesifikaatioineen. Malli näkee nämä kuvaukset järjestelmäkehotteessaan ja ymmärtää, mitä kukin työkalu tekee. +Määrittelet funktiot selkeillä kuvauksilla ja parametrien määrittelyillä. Malli näkee nämä kuvaukset järjestelmäkehotteessaan ja ymmärtää, mitä kukin työkalu tekee. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Säähautasi logiikka + // Säätietojen hakulogiikkasi return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,149 +96,149 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Avustaja kytketään automaattisesti Spring Bootin avulla: -// - ChatModel-palvelu -// - Kaikki @Tool-menetelmät @Component-luokista +// Avustaja on automaattisesti yhteydessä Spring Bootilla seuraaviin: +// - ChatModel bean +// - Kaikki @Tool-metodit @Component-luokista // - ChatMemoryProvider istunnon hallintaan ``` - -Alla oleva kaavio purkaa jokaisen annotaation ja näyttää, miten jokainen osa auttaa tekoälyä ymmärtämään, milloin kutsua työkalua ja mitä argumentteja antaa: -Työkalumäärittelyn rakenne +Alla oleva kaavio purkaa jokaiseen annotaatioon ja näyttää, miten kukin osa auttaa tekoälyä ymmärtämään, milloin työkalu kutsutaan ja mitä argumentteja annetaan: -*Työkalumäärittelyn rakenne — @Tool kertoo tekoälylle, milloin käyttää työkalua, @P kuvaa jokaisen parametrin ja @AiService kytkee kaiken yhteen käynnistyksen yhteydessä.* +Työkalumääritelmien anatomia + +*Työkalumääritelmän anatomia — @Tool kertoo tekoälylle, milloin käyttää työkalua, @P kuvaa jokaisen parametrin, ja @AiService kytkee kaiken käynnistyksessä.* > **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chatin kanssa:** Avaa [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ja kysy: -> - "Miten integroidaan oikea säähallinta-API, kuten OpenWeatherMap, testidatan sijaan?" -> - "Mikä tekee hyvästä työkalukuvauksesta, joka auttaa tekoälyä käyttämään työkalua oikein?" -> - "Miten käsitellään API-virheitä ja käyttörajoituksia työkalujen toteutuksissa?" +> - "Kuinka integroisin oikean sää-API:n kuten OpenWeatherMapin sen sijaan, että käyttäisin mallinnettua dataa?" +> - "Mikä tekee hyvästä työkalukuvauksesta, joka auttaa tekoälyä käyttämään sitä oikein?" +> - "Miten käsittelen API-virheitä ja rajapintojen käyttörajoituksia työkalujen toteutuksissa?" ### Päätöksenteko -Kun käyttäjä kysyy "Mikä on sää Seattlella?", malli ei valitse työkalua sattumalta. Se vertaa käyttäjän aikomusta jokaiseen käytettävissä olevaan työkalukuvauskseen, pisteyttää ne osuvuuden mukaan ja valitsee parhaan. Se luo sitten rakenteellisen funktiokutsun oikeilla parametreilla — tässä tapauksessa asettaa `location` arvoksi `"Seattle"`. +Kun käyttäjä kysyy "Mikä on sää Seattlella?", malli ei valitse työkalua satunnaisesti. Se vertaa käyttäjän aikomusta jokaiseen työkalukuvaan, arvioi ne merkityksellisyyden mukaan ja valitsee parhaan osuman. Se generoi rakenteellisen funktiokutsun oikeilla parametreilla — tässä tapauksessa asettaa `location` arvoksi `"Seattle"`. -Jos mikään työkalu ei vastaa käyttäjän pyyntöä, malli vastaa omien tietojensa perusteella. Jos useampi työkalu sopii, se valitsee tarkimman. +Jos mikään työkalu ei sovi käyttäjän pyyntöön, malli vastaa omasta tietämyksestään. Jos useampi työkalu sopii, se valitsee spesifisemmän. -Kuinka tekoäly päättää mitä työkalua käyttää +Kuinka tekoäly päättää käytettävän työkalun -*Malli arvioi jokaisen saatavilla olevan työkalun käyttäjän aikomukseen nähden ja valitsee parhaan — siksi selkeiden ja täsmällisten työkalukuvauksien kirjoittaminen on tärkeää.* +*Malli arvioi jokaisen käytettävissä olevan työkalun käyttäjän aikomusta vasten ja valitsee parhaan — siksi selkeiden ja tarkkojen työkalukuvauksien kirjoittaminen on tärkeää.* ### Suoritus [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot liittää automaattisesti `@AiService` -rajapinnan kaikkiin rekisteröityihin työkaluihin, ja LangChain4j suorittaa työkalukutsut automaattisesti. Taustalla täydellinen työkalukutsu kulkee kuuden vaiheen läpi — käyttäjän luonnollisen kielen kysymyksestä aina takaisin luonnollisen kielen vastaukseen: +Spring Boot kytkee deklaratiivisen `@AiService`-rajapinnan kaikkiin rekisteröityihin työkaluihin, ja LangChain4j suorittaa työkalukutsut automaattisesti. Kulissien takana täydellinen työkalukutsu kulkee kuuden vaiheen läpi — käyttäjän luonnollisen kielen kysymyksestä luonnollisen kielen vastaukseen: -Työkalukutsun kulku +Työkalukutsun suoritus -*Loppuun asti kulkeva prosessi — käyttäjä kysyy, malli valitsee työkalun, LangChain4j suorittaa sen ja malli kytkee tuloksen luonnolliseen vastaukseen.* +*Loppuun asti kulkeva virtaus — käyttäjä kysyy kysymyksen, malli valitsee työkalun, LangChain4j suorittaa sen ja malli liittää tuloksen luonnolliseen vastaukseen.* -Jos olet ajanut [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) Moduulissa 00, olet nähnyt saman mallin toiminnassa — `Calculator`-työkaluja kutsuttiin samalla tavalla. Alla oleva sekvenssikaavio näyttää tarkalleen, mitä demon aikana tapahtui: +Kulissien takana `AiServices` pyörittää samaa työkalukutsusilmukkaa mille tahansa työkalulle — tässä yksinkertaisen `Calculator`-esimerkin kautta. Seuraava sekvenssikaavio näyttää tarkalleen, mitä tapahtuu sisäisesti: Työkalukutsun sekvenssikaavio -*Työkalukutsun silmukka Quick Start -demosta — `AiServices` lähettää viestisi ja työkalujen skeemat LLM:lle, LLM vastaa funktiokutsulla kuten `add(42, 58)`, LangChain4j suorittaa `Calculator`-metodin paikallisesti ja syöttää tuloksen takaisin lopullista vastausta varten.* +*Työkalukutsusilmukka — `AiServices` lähettää viestin ja työkaluskeemat LLM:lle, LLM vastaa funktiokutsulla kuten `add(42, 58)`, LangChain4j suorittaa `Calculator`-metodin paikallisesti ja syöttää tuloksen lopulliseen vastaukseen.* > **🤖 Kokeile [GitHub Copilot](https://github.com/features/copilot) Chatin kanssa:** Avaa [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ja kysy: -> - "Miten ReAct-malli toimii ja miksi se on tehokas AI-agenteille?" +> - "Miten ReAct-malli toimii ja miksi se on tehokas tekoälyagenteille?" > - "Miten agentti päättää, mitä työkalua käyttää ja missä järjestyksessä?" -> - "Mitä tapahtuu, jos työkalun suoritus epäonnistuu — miten virheiden käsittely tulisi toteuttaa luotettavasti?" +> - "Mitä tapahtuu, jos työkalun suoritus epäonnistuu - miten virheet kannattaa käsitellä luotettavasti?" -### Vastauksen luominen +### Vastauksen generointi Malli vastaanottaa säädatan ja muotoilee siitä käyttäjälle luonnollisen kielen vastauksen. -### Arkkitehtuuri: Spring Boot automaattijohtaminen +### Arkkitehtuuri: Spring Bootin automaattinen törmäys -Tämä moduuli käyttää LangChain4j:n Spring Boot -integraatiota deklaratiivisten `@AiService` -rajapintojen kanssa. Käynnistyksen yhteydessä Spring Boot löytää kaikki `@Component`it, jotka sisältävät `@Tool`-metodeja, ChatModel-beanin ja ChatMemoryProviderin — ja liittää ne kaikki yhdeksi `Assistant`-rajapinnaksi ilman boilerplate-koodia. +Tämä moduuli käyttää LangChain4j:n Spring Boot -integraatiota deklaratiivisilla `@AiService`-rajapinnoilla. Käynnistyksessä Spring Boot löytää kaikki `@Component`-luokat, jotka sisältävät `@Tool`-metodeja, ChatModel-beanin ja ChatMemoryProviderin — ja kytkee ne kaikki yhdeksi `Assistant`-rajapinnaksi ilman boilerplate-koodia. -Spring Boot automaattijohtamisen arkkitehtuuri +Spring Bootin automaattisen törmäyksen arkkitehtuuri -*@AiService-rajapinta sitoo yhteen ChatModelin, työkalukomponentit ja muistinhallinnan — Spring Boot hoitaa kaiken liitännän automaattisesti.* +*@AiService-rajapinta yhdistää ChatModelin, työkalukomponentit ja muistin tarjoajan — Spring Boot huolehtii kaikesta automaattisesti.* -Tässä koko pyyntöjen elinkaari sekvenssikaaviona — HTTP-pyynnöstä ohjaimeen, palveluun, automaattijohtimeen, työkalukutsuun ja takaisin: +Tässä on koko pyyntöelinkaari sekvenssikaaviona — HTTP-pyynnöstä kontrollerin, palvelun ja automaattisesti kytketyn proxyn kautta työkalun suorittamiseen ja takaisin: -Spring Boot työkalukutsun sekvenssi +Spring Bootin työkalukutsun sekvenssi -*Koko Spring Boot -pyynnön elinkaari — HTTP-pyyntö kulkee ohjaimen ja palvelun kautta automaattijohtoisen Assistant-proxyn läpi, joka orkestroi LLM:n ja työkalukutsut automaattisesti.* +*Kokonainen Spring Boot -pyyntöelinkaari — HTTP-pyyntö kulkee kontrollerin ja palvelun kautta Assistant-proxylle, joka orkestroi LLM:n ja työkalukutsut automaattisesti.* -Tämän lähestymistavan keskeiset edut: +Tämän lähestymistavan tärkeimmät edut: -- **Spring Boot automaattijohtaminen** — ChatModel ja työkalut injektoidaan automaattisesti -- **@MemoryId-malli** — Istuntopohjainen automaattinen muistinhallinta -- **Yksi instanssi** — Assistant luodaan kerran ja käytetään uudestaan suorituskyvyn parantamiseksi -- **Tyyppiturvallinen suoritus** — Java-metodit kutsutaan suoraan tyypinmuunnoksella -- **Monivuoroinen orkestrointi** — Hallitsee työkaluketjutuksen automaattisesti -- **Ei boilerplate-koodia** — Ei käsin tehtäviä `AiServices.builder()` -kutsuja tai muistihashtabeja +- **Spring Boot automaattinen kytkentä** — ChatModel ja työkalut injektoidaan automaattisesti +- **@MemoryId-malli** — Automaattinen istuntopohjainen muistin hallinta +- **Yksi instanssi** — Assistant luodaan kerran ja uudelleenkäytetään paremman suorituskyvyn vuoksi +- **Tyyppiturvallinen suoritus** — Java-metodit kutsutaan suoraan tyypinmuunnoksella +- **Monivaiheinen orkestrointi** — Käsittelee työkaluketjutuksen automaattisesti +- **Ei boilerplatea** — Ei manuaalisia `AiServices.builder()` -kutsuja eikä muistihakemistoa -Vaihtoehtoiset lähestymistavat (käsin tehtävät `AiServices.builder()` -kutsut) vaativat enemmän koodia ja eivät hyödynnä Spring Boot -integraation etuja. +Vaihtoehtoiset käsitteet (manuaalinen `AiServices.builder()`) vaativat enemmän koodia ja jäävät ilman Spring Boot -integraation etuja. ## Työkaluketjutus -**Työkaluketjutus** — Työkalupohjaisten agenttien todellinen voima näkyy, kun yksittäinen kysymys vaatii useita työkaluja. Kysy "Mikä on Seattlelän sää fahrenheit-asteina?" ja agentti ketjuttaa automaattisesti kaksi työkalua: ensin se kutsuu `getCurrentWeather` saadakseen lämpötilan celsiusasteina, sitten siirtää arvon `celsiusToFahrenheit`-työkalulle muuntamista varten — kaikki yhdessä keskusteluvuorossa. +**Työkaluketjutus** — työkalupohjaisten agenttien todellinen voima näkyy, kun yksittäinen kysymys tarvitsee useita työkaluja. Kysy: "Mikä on sää Seattlella Fahrenheit-asteina?" ja agentti ketjuttaa automaattisesti kaksi työkalua: ensin se kutsuu `getCurrentWeather` saadakseen lämpötilan celsiusasteina, ja sitten antaa arvon `celsiusToFahrenheit`-työkalulle muuntamista varten — kaikki yhdessä keskustelukierrossa. Työkaluketjutuksen esimerkki -*Työkaluketjutus toiminnassa — agentti kutsuu ensin getCurrentWeather, sitten ohjaa celsius-tuloksen celsiusToFahrenheit-työkalulle ja tarjoaa yhdistetyn vastauksen.* +*Työkaluketjutus toiminnassa — agentti kutsuu ensin getCurrentWeatherin, syöttää sitten Celsius-tuloksen celsiusToFahrenheitille ja antaa yhdistetyn vastauksen.* -**Sulava virheiden käsittely** — Kysy sää jossain kaupungissa, jota ei ole testidatassa. Työkalu palauttaa virheilmoituksen ja tekoäly selittää, ettei voi auttaa sen sijaan, että kaatuisi. Työkalut käsittelevät virheensä turvallisesti. Alla oleva kaavio vertaa kahta lähestymistapaa — asianmukaisella virheenkäsittelyllä agentti sieppaa poikkeuksen ja vastaa avuliaasti, ilman sitä koko sovellus kaatuu: +**Hallittu virhetilanteet** — Kysy sää jostain kaupungista, joka ei ole määritellyssä mallidatassa. Työkalu palauttaa virheilmoituksen, ja tekoäly selittää, ettei pysty auttamaan sen sijaan, että kaatuisi. Työkalut eivät kaadu, vaan epäonnistuvat turvallisesti. Alla oleva kaavio vertaa kahta lähestymistapaa — asianmukaisella virheenkäsittelyllä agentti nappaa poikkeuksen ja vastaa auttavasti, ilman sitä koko sovellus kaatuu: -Virheenkäsittelyn kulku +Virheenkäsittelyn virtaus -*Kun työkalu epäonnistuu, agentti sieppaa virheen ja vastaa avuliaalla selityksellä kaatumisen sijaan.* +*Kun työkalu epäonnistuu, agentti tarttuu virheeseen ja vastaa hyödyllisellä selityksellä kaatumisen sijaan.* -Tämä tapahtuu yhdellä keskustelukierroksella. Agentti orkestroi useita työkalukutsuja itsenäisesti. +Tämä tapahtuu yhdellä keskustelukierroksella. Agentti orkestroi useita työkaluja itsenäisesti. -## Sovelluksen käynnistäminen +## Sovelluksen suorittaminen -**Tarkista käyttöönotto:** +**Varmista käyttöönotto:** -Varmista, että `.env`-tiedosto on juurihakemistossa ja sisältää Azure-tunnukset (luotu Moduulin 01 aikana). Aja komennot moduulihakemistosta (`04-tools/`): +Varmista, että `.env`-tiedosto on juurikansiossa Azure-tunnuksilla (luotu Moduulissa 01). Suorita tämä moduulihakemistosta (`04-tools/`): -**Bash:** +**Bash:** ```bash cat ../.env # Tulisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Tulisi näyttää AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**Käynnistä sovellus:** -> **Huom:** Jos olet jo käynnistänyt kaikki sovellukset `./start-all.sh` -skriptillä juurihakemistosta (kuten Moduulin 01 ohjeissa), tämä moduuli on jo käynnissä portissa 8084. Voit ohittaa alla olevat käynnistyskomennot ja mennä suoraan osoitteeseen http://localhost:8084. +**Aloita sovellus:** + +> **Huom:** Jos olet jo käynnistänyt kaikki sovellukset komennolla `./start-all.sh` juurihakemistosta (kuten Moduulissa 01 kuvattu), tämä moduuli on jo käynnissä portissa 8084. Voit jättää alla olevat käynnistyskomennot väliin ja mennä suoraan osoitteeseen http://localhost:8084. -**Vaihtoehto 1: Spring Boot Dashboardin käyttö (suositeltu VS Code -käyttäjille)** +**Vaihtoehto 1: Spring Boot Dashboardin käyttö (Suositeltu VS Code -käyttäjille)** -Kehityskontti sisältää Spring Boot Dashboard -laajennuksen, joka tarjoaa visuaalisen käyttöliittymän kaikkien Spring Boot -sovellusten hallintaan. Löydät sen VS Coden vasemman laidan Activity Bar -palkista (etsi Spring Boot -kuvake). +Kehityssäilössä on mukana Spring Boot Dashboard -laajennus, joka tarjoaa visuaalisen käyttöliittymän hallita kaikkia Spring Boot -sovelluksia. Löydät sen vasemman reunan Activity Barista (etsi Spring Boot -ikonia). -Spring Boot Dashboardista voit: +Spring Boot Dashboardista voit: - Näyttää kaikki käytettävissä olevat Spring Boot -sovellukset työtilassa -- Käynnistää/pysäyttää sovellukset yhdellä napsautuksella -- Katsoa sovelluslokeja reaaliaikaisesti -- Monitoroida sovelluksen tilaa -Aloita tämä moduuli yksinkertaisesti napsauttamalla "tools"-kohdan vieressä olevaa toistopainiketta tai käynnistä kaikki moduulit kerralla. +- Käynnistää/pysäyttää sovelluksia yhdellä klikkauksella +- Tarkastella sovelluslokeja reaaliajassa +- Valvoa sovelluksen tilaa -Tältä Spring Boot Dashboard näyttää VS Codessa: +Napsauta yksinkertaisesti soittonappia "tools" kohdalla käynnistääksesi tämän moduulin tai käynnistä kaikki moduulit kerralla. -Spring Boot Dashboard +Tältä Spring Boot Dashboard näyttää VS Codessa: +Spring Boot -kojelauta -*Spring Boot Dashboard VS Codessa — käynnistä, pysäytä ja valvo kaikkia moduuleja yhdestä paikasta* +*Spring Boot -kojelauta VS Codessa — käynnistä, pysäytä ja valvo kaikkia moduuleja yhdestä paikasta* -**Vaihtoehto 2: Shell-komentosarjojen käyttö** +**Vaihtoehto 2: Kuoriskriptien käyttö** Käynnistä kaikki web-sovellukset (moduulit 01-04): **Bash:** ```bash -cd .. # Juurihakemistosta +cd .. # Juurikansiosta ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Juurihakemistosta +cd .. # Juurikansiosta .\start-all.ps1 ``` @@ -256,7 +256,7 @@ cd 04-tools .\start.ps1 ``` -Molemmat skriptit lataavat automaattisesti ympäristömuuttujat juurikansion `.env`-tiedostosta ja rakentavat JAR-tiedostot, jos ne eivät ole olemassa. +Molemmat skriptit lataavat automaattisesti ympäristömuuttujat juuren `.env`-tiedostosta ja rakentavat JAR-tiedostot, jos niitä ei ole olemassa. > **Huom:** Jos haluat rakentaa kaikki moduulit manuaalisesti ennen käynnistämistä: > @@ -265,111 +265,111 @@ Molemmat skriptit lataavat automaattisesti ympäristömuuttujat juurikansion `.e > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Avaa selaimessa osoite http://localhost:8084. +Avaa selaimessasi http://localhost:8084. -**Pysäyttääksesi:** +**Pysäyttämiseksi:** **Bash:** ```bash -./stop.sh # Tämä moduuli vain +./stop.sh # Vain tämä moduuli # Tai cd .. && ./stop-all.sh # Kaikki moduulit ``` **PowerShell:** ```powershell -.\stop.ps1 # Tämä moduuli vain +.\stop.ps1 # Vain tämä moduuli # Tai cd ..; .\stop-all.ps1 # Kaikki moduulit ``` ## Sovelluksen käyttö -Sovellus tarjoaa selainkäyttöliittymän, jonka kautta voit olla vuorovaikutuksessa tekoälyagentin kanssa, jolla on pääsy sää- ja lämpötilamuuntotyökaluihin. Tältä käyttöliittymä näyttää — se sisältää pikaesimerkit ja chat-paneelin pyyntöjen lähettämiseen: +Sovellus tarjoaa web-käyttöliittymän, jossa voit olla vuorovaikutuksessa tekoälyagentin kanssa, jolla on pääsy sää- ja lämpötilamuunnostyökaluihin. Tässä miltä käyttöliittymä näyttää — se sisältää pikaesimerkkejä ja chat-paneelin pyynnöille: -AI Agent Tools Interface +Tekoälyagentin työkalujen käyttöliittymä -*AI Agent Tools -käyttöliittymä - pikaesimerkkejä ja chat-käyttöliittymä työkalujen käyttöön* +*Tekoälyagentin työkalujen käyttöliittymä – pikaesimerkkejä ja chat-käyttöliittymä työkalujen kanssa vuorovaikutukseen* ### Kokeile yksinkertaista työkalun käyttöä -Aloita suoraviivaisella pyynnöllä: "Muuta 100 astetta Fahrenheitista Celsiukseksi". Agentti tunnistaa, että tarvitsee lämpötilamuuntotyökalun, kutsuu sitä oikeilla parametreilla ja palauttaa tuloksen. Huomaa, kuinka luonnolliselta tämä tuntuu — et määritellyt, mitä työkalua käyttää tai miten sitä kutsutaan. +Aloita suoraviivaisella pyynnöllä: "Muunna 100 astetta Fahrenheitia Celsius-asteiksi". Agentti tunnistaa, että se tarvitsee lämpötilamuunnostyökalua, kutsuu sitä oikeilla parametreilla ja palauttaa tuloksen. Huomaa miten luonnolliselta tämä tuntuu – sinun ei tarvinnut määritellä, mitä työkalua tai miten sitä käyttää. -### Testaa työkalujen ketjutusta +### Testaa työkaluketjutusta -Kokeile nyt jotain monimutkaisempaa: "Mikä on sää Seattlessa ja muuta se Fahrenheit-asteiksi?" Katso, kuinka agentti toimii tämän läpi vaiheittain. Se hakee ensin sään (joka palauttaa Celsius-asteet), tunnistaa, että tarvitsee muuntaa Fahrenheitiksi, kutsuu muunnostyökalua ja yhdistää molemmat tulokset yhdeksi vastaukseksi. +Kokeile nyt monimutkaisempaa: "Mikä on sää Seattlessa ja muunna se Fahrenheit-asteiksi?" Katso, miten agentti toimii vaiheittain. Se ensin hakee sään (joka palauttaa Celsius-asteet), tunnistaa tarpeen muuntaa Fahrenheitiksi, kutsuu muunnostyökalua ja yhdistää molemmat tulokset yhdeksi vastaukseksi. -### Katso keskustelun kulku +### Katso keskustelun kulkua -Chat-käyttöliittymä säilyttää keskusteluhistorian, jolloin voit käydä monivuorovaikutteisia keskusteluja. Näet kaikki aiemmat kyselyt ja vastaukset, mikä helpottaa keskustelun seuraamista ja ymmärtämään, miten agentti rakentaa kontekstia useiden vaihdosten aikana. +Chat-käyttöliittymä ylläpitää keskusteluhistoriaa, jolloin voit käydä monivaiheisia vuorovaikutuksia. Näet kaikki aiemmat kyselyt ja vastaukset, mikä helpottaa keskustelun seuraamista ja ymmärtämään, miten agentti rakentaa kontekstia useiden vaihdosten aikana. -Conversation with Multiple Tool Calls +Keskustelu, jossa tehty useita työkalukutsuja -*Monivuoroinen keskustelu, jossa tehdään yksinkertaisia muunnoksia, säähaut ja työkaluketjutuksia* +*Monivaiheinen keskustelu, jossa näkyy yksinkertaisia muunnoksia, säähaut ja työkaluketjutus* ### Kokeile erilaisia pyyntöjä Kokeile erilaisia yhdistelmiä: -- Säätiedotukset: "Mikä on sää Tokiossa?" -- Lämpötilamuunnokset: "Mikä on 25°C Kelvineinä?" -- Yhdistetyt kyselyt: "Tarkista sää Pariisissa ja kerro, onko lämpötila yli 20°C" +- Säähaut: "Millainen sää on Tokiossa?" +- Lämpötilamuunnokset: "Mikä on 25°C Kelvineissä?" +- Yhdistelmätiedustelut: "Tarkista sään tila Pariisissa ja kerro, onko siellä yli 20°C" -Huomaa, kuinka agentti tulkitsee luonnollista kieltä ja mapittaa sen sopiviksi työkalukutsuiksi. +Huomaa, miten agentti tulkitsee luonnollista kieltä ja yhdistää sen sopiviin työkalukutsuihin. ## Keskeiset käsitteet -### ReAct-malli (Päättely ja toiminta) +### ReAct-malli (Päättely ja Toiminta) -Agentti vuorottelee päättelyn (päätös, mitä tehdä) ja toimimisen (työkalujen käyttö) välillä. Tämä malli mahdollistaa autonomisen ongelmanratkaisun pelkän ohjeiden seuraamisen sijaan. +Agentti vuorottelee päättelyn (päätösten tekemisen) ja toiminnan (työkalujen käytön) välillä. Tämä malli mahdollistaa itsenäisen ongelmanratkaisun pelkkien käskyihin vastaamisen sijaan. -### Työkalujen kuvauksilla on merkitystä +### Tärkeitä työkalukuvauksia -Työkalukuvauksesi laatu vaikuttaa suoraan siihen, kuinka hyvin agentti osaa käyttää niitä. Selkeät ja täsmälliset kuvaukset auttavat mallia ymmärtämään, milloin ja miten kutakin työkalua kutsutaan. +Työkalukuvauksiesi laatu vaikuttaa suoraan siihen, miten hyvin agentti käyttää työkaluja. Selkeät, täsmälliset kuvaukset auttavat mallia ymmärtämään, milloin ja miten kutakin työkalua kutsutaan. ### Istunnon hallinta -`@MemoryId`-annotaatio mahdollistaa automaattisen istuntokohtaisen muistinhallinnan. Jokainen istuntotunnus saa oman `ChatMemory`-instanssin, jota hallinnoi `ChatMemoryProvider`-bean, joten useat käyttäjät voivat olla vuorovaikutuksessa agentin kanssa samanaikaisesti ilman, että keskustelut sekoittuvat. Seuraava kaavio näyttää, miten useat käyttäjät ohjataan erillisiin muistivarastoihin istuntotunnustensa perusteella: +`@MemoryId`-annotaatio mahdollistaa automaattisen istuntokohtaisen muistinhallinnan. Jokainen istunto saa oman `ChatMemory`-instanssinsa, jota hallinnoi `ChatMemoryProvider`-bean, joten useat käyttäjät voivat olla vuorovaikutuksessa agentin kanssa samanaikaisesti ilman, että heidän keskustelunsa sekoittuvat. Seuraava kaavio näyttää, miten käyttäjät ohjataan eristyneisiin muistivarastoihin istunnon perusteella: -Session Management with @MemoryId +Istunnon hallinta @MemoryId:n kanssa -*Jokainen istuntotunnus vastaa erillistä keskusteluhistoriaa — käyttäjät eivät näe toistensa viestejä.* +*Jokainen istunto-ID ohjautuu erilliseen keskusteluhistoriaan — käyttäjät eivät näe toistensa viestejä.* ### Virheenkäsittely -Työkalut voivat epäonnistua — API:t aikakatkaisevat, parametrit voivat olla virheellisiä, ulkoiset palvelut voivat olla alas. Tuotantoagentit tarvitsevat virheenkäsittelyn, jotta malli voi selittää ongelmat tai yrittää vaihtoehtoja sen sijaan, että koko sovellus kaatuu. Kun työkalu heittää poikkeuksen, LangChain4j sieppaa sen ja välittää virheilmoituksen takaisin mallille, joka voi sitten selittää ongelman luonnollisella kielellä. +Työkalut voivat epäonnistua — API-yhteys voi aikakatketa, parametrit saattavat olla virheellisiä, ulkoiset palvelut voivat olla poissa käytöstä. Tuotantoagenttien tulee huolehtia virheistä, jotta malli voi selittää ongelmat tai kokeilla vaihtoehtoja sen sijaan, että koko sovellus kaatuisi. Kun työkalu heittää poikkeuksen, LangChain4j poimii sen ja syöttää virheilmoituksen takaisin mallille, joka osaa sitten selittää ongelman luonnollisella kielellä. ## Saatavilla olevat työkalut -Alla oleva kaavio näyttää laajan työkaluekosysteemin, jonka voit rakentaa. Tämä moduuli demonstroi sää- ja lämpötilatyökaluja, mutta sama `@Tool`-malli toimii minkä tahansa Java-metodin kanssa — tietokantakyselyistä maksuliikenteeseen. +Alla oleva kaavio esittelee laajan kokoelman työkaluja, joita voit rakentaa. Tämä moduuli esittelee sää- ja lämpötilatyökaluja, mutta sama `@Tool`-malli toimii minkä tahansa Java-metodin kanssa — oli kyse sitten tietokantakyselyistä tai maksun käsittelystä. -Tool Ecosystem +Työkalujen ekosysteemi -*Mikä tahansa `@Tool`-annotaatiolla varustettu Java-metodi tulee saataville tekoälylle — malli laajenee tietokantoihin, API:ihin, sähköposteihin, tiedostotoimintoihin ja muuhun.* +*Mikä tahansa Java-metodi, joka on merkitty @Toolilla, tulee käyttöön tekoälylle — malli laajenee tietokantoihin, rajapintoihin, sähköposteihin, tiedostotoimintoihin ja muuhun.* -## Milloin käyttää työkalupohjaisia agenteja +## Milloin käyttää työkalupohjaisia agentteja -Kaikki pyynnöt eivät tarvitse työkaluja. Päätös perustuu siihen, tarvitseeko tekoäly olla vuorovaikutuksessa ulkoisten järjestelmien kanssa vai voiko se vastata omasta tiedostaan. Seuraava opas tiivistää, milloin työkalut tuovat lisäarvoa ja milloin ne ovat tarpeettomia: +Kaikki pyynnöt eivät vaadi työkaluja. Päätös pohjautuu siihen, tarvitseeko tekoäly olla vuorovaikutuksessa ulkoisten järjestelmien kanssa vai pystyykö se vastaamaan omasta tiedostaan. Seuraava opas tiivistää, milloin työkalut tuovat lisäarvoa ja milloin ne ovat tarpeettomia: -When to Use Tools +Milloin käyttää työkaluja -*Nopea päätösopas — työkalut ovat reaaliaikaisiin tietoihin, laskelmiin ja toimintoihin; yleistä tietoa ja luovia tehtäviä varten niitä ei tarvita.* +*Nopea päätösopas — työkaluja käytetään reaaliaikaiseen dataan, laskentoihin ja toimenpiteisiin; yleinen tieto ja luovat tehtävät eivät niitä tarvitse.* ## Työkalut vs RAG -Moduulit 03 ja 04 laajentavat tekoälyn kykyjä, mutta pohjimmiltaan eri tavoin. RAG antaa mallille pääsyn **tietoon** hakemalla dokumentteja. Työkalut antavat mallille kyvyn suorittaa **toimintoja** kutsumalla funktioita. Alla oleva kaavio vertaa näitä kahta lähestymistapaa rinnakkain — miten kukin työnkulku toimii ja mitkä ovat niiden kompromissit: +Moduulit 03 ja 04 laajentavat tekoälyn kykyjä, mutta perustavanlaatuisesti eri tavalla. RAG antaa mallille pääsyn **tietoon** hakemalla dokumentteja. Työkalut antavat mallille kyvyn suorittaa **toimia** kutsumalla funktioita. Alla oleva kaavio vertaa näitä kahta lähestymistapaa rinnakkain — miten kummankin työnkulku toimii ja niiden välillä tehdyt kompromissit: -Tools vs RAG Comparison +Työkalut vs RAG -vertailu -*RAG hakee tietoa staattisista dokumenteista — Työkalut suorittavat toimia ja hakevat dynaamista, reaaliaikaista dataa. Monet tuotantojärjestelmät yhdistävät molemmat.* +*RAG hakee tietoa staattisista dokumenteista — Työkalut suorittavat toimintoja ja hakevat dynaamista, reaaliaikaista dataa. Monet tuotantojärjestelmät yhdistävät molemmat.* -Käytännössä monet tuotantojärjestelmät yhdistävät molemmat lähestymistavat: RAG vahvistamaan vastaukset dokumentaatiollasi ja Työkalut live-datan hakemiseen tai operaatioiden suorittamiseen. +Käytännössä monet tuotantojärjestelmät yhdistävät molemmat lähestymistavat: RAG vastauksille dokumentaatioon perustuen ja Työkalut live-datan hakemiseen tai toimintojen suorittamiseen. ## Seuraavat askeleet @@ -383,5 +383,5 @@ Käytännössä monet tuotantojärjestelmät yhdistävät molemmat lähestymista **Vastuuvapauslauseke**: -Tämä asiakirja on käännetty tekoälypohjaisella käännöspalvelulla [Co-op Translator](https://github.com/Azure/co-op-translator). Pyrimme tarkkuuteen, mutta ota huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen omalla kielellä tulee katsoa viralliseksi lähteeksi. Tärkeissä asioissa suositellaan ammattimaista ihmiskääntäjää. Emme ole vastuussa tämän käännöksen käytöstä johtuvista väärinymmärryksistä tai virhetulkintojen seurauksista. +Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista. \ No newline at end of file diff --git a/translations/fi/README.md b/translations/fi/README.md index a0e1c0e67..d71ccbb7b 100644 --- a/translations/fi/README.md +++ b/translations/fi/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j aloittelijoille +# LangChain4j Aloittelijoille Kurssi tekoälysovellusten rakentamiseen LangChain4j:llä ja Azure OpenAI GPT-5.2:lla, peruschatista tekoälyagentteihin. ### 🌐 Monikielinen tuki -#### Tuettu GitHub Actionin kautta (automaattinen ja aina ajan tasalla) +#### Tuettu GitHub Actionin kautta (Automaattinen ja aina ajan tasalla) -[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](./README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) +[Arabia](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgaria](../bg/README.md) | [Burma (Myanmar)](../my/README.md) | [Kiina (yksinkertaistettu)](../zh-CN/README.md) | [Kiina (perinteinen, Hong Kong)](../zh-HK/README.md) | [Kiina (perinteinen, Macao)](../zh-MO/README.md) | [Kiina (perinteinen, Taiwan)](../zh-TW/README.md) | [Kroatia](../hr/README.md) | [Tšekki](../cs/README.md) | [Tanska](../da/README.md) | [Hollanti](../nl/README.md) | [Viro](../et/README.md) | [Suomi](./README.md) | [Ranska](../fr/README.md) | [Saksa](../de/README.md) | [Kreikka](../el/README.md) | [Heprea](../he/README.md) | [Hindi](../hi/README.md) | [Unkari](../hu/README.md) | [Indonesia](../id/README.md) | [Italia](../it/README.md) | [Japani](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korea](../ko/README.md) | [Liettua](../lt/README.md) | [Malaiji](../ms/README.md) | [Malajalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norja](../no/README.md) | [Persia (Farsi)](../fa/README.md) | [Puola](../pl/README.md) | [Portugali (Brasilia)](../pt-BR/README.md) | [Portugali (Portugali)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romania](../ro/README.md) | [Venäjä](../ru/README.md) | [Serbia (kyrillinen)](../sr/README.md) | [Slovakki](../sk/README.md) | [Sloveeni](../sl/README.md) | [Espanja](../es/README.md) | [Swahili](../sw/README.md) | [Ruotsi](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamili](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkki](../tr/README.md) | [Ukraina](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnam](../vi/README.md) -> **Haluatko kloonata paikallisesti?** +> **Haluatko mieluummin kloonata paikallisesti?** > -> Tämä repositorio sisältää yli 50 kielen käännöksiä, mikä kasvattaa merkittävästi lataustiedostojen kokoa. Kun haluat kloonata ilman käännöksiä, käytä sparse checkout -toimintoa: +> Tämä arkisto sisältää yli 50 käännöstä, jotka lisäävät merkittävästi latauskokoa. Jos haluat kloonata ilman käännöksiä, käytä sparse checkout -toimintoa: > > **Bash / macOS / Linux:** > ```bash @@ -29,59 +29,58 @@ Kurssi tekoälysovellusten rakentamiseen LangChain4j:llä ja Azure OpenAI GPT-5. > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Näin saat kaiken tarvitsemasi kurssin suorittamiseen huomattavasti nopeammin. +> Näin saat kaiken tarvitsemasi kurssin suorittamiseen paljon nopeammalla latauksella. ## Sisällysluettelo -1. [Pika-aloitus](00-quick-start/README.md) - Aloita LangChain4j:n kanssa -2. [Johdanto](01-introduction/README.md) - Opiskele LangChain4j:n perusteet -3. [Prompt-tekniikat](02-prompt-engineering/README.md) - Hallitse tehokas promttien suunnittelu -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Rakenna älykkäitä tietopohjaisia järjestelmiä -5. [Työkalut](04-tools/README.md) - Integroi ulkoisia työkaluja ja yksinkertaisia avustajia -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Työskentele Model Context Protocolin (MCP) ja agenttimoduulien kanssa +1. [Johdanto](01-introduction/README.md) - Opi LangChain4j:n perusteet +2. [Prompt-suunnittelu](02-prompt-engineering/README.md) - Hallitse tehokas kehotteen suunnittelu +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Rakenna älykkäitä tietopohjaisia järjestelmiä +4. [Työkalut](04-tools/README.md) - Integroi ulkoiset työkalut ja yksinkertaiset avustajat +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Työskentele Model Context Protocolin (MCP) ja Agentic-moduulien kanssa -### Video-opastukset +### Videokävelyt läpi -Jokaisella moduulilla on mukana seurantaistunto, jossa käymme läpi käsitteet ja koodin vaihe vaiheelta. +Jokaisella moduulilla on mukana live-istunto, jossa käymme läpi käsitteet ja koodin askel askeleelta. | Moduuli | Video | |--------|-------| -| 01 - Johdanto | [Aloitus LangChain4j:n kanssa](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Prompt-tekniikat | [Prompt-tekniikat LangChain4j:llä](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - Johdanto | [LangChain4j:n aloittaminen](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Prompt-suunnittelu | [Prompt-suunnittelu LangChain4j:llä](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG LangChain4j:llä](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Työkalut & 05 - MCP | [Tekoälyagentit työkalujen ja MCP:n kanssa](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Työkalut & 05 - MCP | [Tekoälyagentit työkaluilla ja MCP:llä](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## Oppimispolku -**Uusi LangChain4j:ssä?** Tutustu [Sanastoon](docs/GLOSSARY.md) saadaksesi määritelmiä tärkeistä termeistä ja käsitteistä. +**Uusi LangChain4j:ssä?** Tutustu [Sanastoon](docs/GLOSSARY.md) avaintermeihin ja käsitteisiin. -> **Pika-aloitus** +> **Pikakäynnistys** -1. Tee fork tälle repositoriolle GitHub-tilillesi -2. Klikkaa **Code** → **Codespaces**-välilehti → **...** → **New with options...** -3. Käytä oletuksia – tämä valitsee tämän kurssin kehitysyhteisön konttiympäristön -4. Klikkaa **Create codespace** -5. Odota 5–10 minuuttia ympäristön valmistumiseen -6. Siirry suoraan kohtaan [Pika-aloitus](./00-quick-start/README.md) aloittaaksesi! +1. Forkkaa tämä arkisto GitHub-tilillesi +2. Klikkaa **Code** → **Codespaces** -välilehti → **...** → **Uusi vaihtoehdoilla...** +3. Käytä oletuksia – tämä valitsee tälle kurssille luodun kehityssäiliön +4. Klikkaa **Luo codespace** +5. Odota 5–10 minuuttia ympäristön valmistumista +6. Siirry suoraan [Johdantoon](./01-introduction/README.md) ja aloita! -Kun moduulit on suoritettu, tutustu [Testausoppaaseen](docs/TESTING.md) nähdäksesi LangChain4j:n testauskonseptit käytännössä. +Moduulien suorittamisen jälkeen tutustu [Testausoppaaseen](docs/TESTING.md) nähdäksesi LangChain4j:n testauskäsitteet käytännössä. -> **Huom:** Tämä koulutus käyttää sekä GitHub malleja että Azure OpenAI:ta. [Pika-aloitus](00-quick-start/README.md) moduuli käyttää GitHub malleja (ei tarvita Azure-tiliä), kun taas moduulit 1–5 käyttävät Azure OpenAI:ta. Aloita [MAKSUTTOMALLA Azure-tilillä](https://aka.ms/azure-free-account), jos sinulla ei vielä ole tiliä. +> **Huom:** Tämä koulutus käyttää Azure OpenAI:a. Aloita ilmaisella [Azure-tilillä](https://aka.ms/azure-free-account), jos sinulla ei vielä ole sellaista. ## Oppiminen GitHub Copilotin kanssa -Aloita koodaaminen nopeasti avaamalla tämä projekti GitHub Codespacessa tai paikallisessa IDE:ssä mukana tulevalla devcontainerilla. Tässä kurssissa käytetyssä devcontainerissa on esikonfiguroitu GitHub Copilot tekoälypohjaiseen pariohjelmointiin. +Pääset nopeasti koodauksen alkuun avaamalla tämän projektin GitHub Codespacessa tai paikallisessa IDE:ssä annetulla devcontainerilla. Tässä kurssissa käytetty devcontainer on valmiiksi konfiguroitu GitHub Copilotille tekoälypariohjelmointia varten. -Jokaisessa koodiesimerkissä on ehdotettuja kysymyksiä, joita voit esittää GitHub Copilotille syventääksesi ymmärrystäsi. Etsi 💡/🤖 kehotteita: +Jokainen koodiesimerkki sisältää ehdotettuja kysymyksiä, joita voit esittää GitHub Copilotille saadaksesi syvällisempää ymmärrystä. Etsi 💡/🤖 kehotteita: -- **Java-tiedostojen otsikoissa** - Esimerkkikohtaisia kysymyksiä -- **Moduulien README-tiedostoissa** - Tutkimuskysymyksiä koodiesimerkkien jälkeen +- **Java-tiedostojen ylätunnisteista** – jokaiselle esimerkkikoodille spesifisiä kysymyksiä +- **Moduulien README:stä** – tutkimuskysymyksiä koodiesimerkkien jälkeen -**Käyttöohje:** Avaa mikä tahansa kooditiedosto ja kysy Copilotilta ehdotettuja kysymyksiä. Se tuntee koko koodikannan, ja voi selittää, laajentaa ja ehdottaa vaihtoehtoja. +**Käyttöohje:** Avaa mikä tahansa kooditiedosto ja esitä Copilotille ehdotetut kysymykset. Se näkee koko koodipohjan ja voi selittää, laajentaa sekä ehdottaa vaihtoehtoja. Haluatko oppia lisää? Tutustu [Copilot tekoälypariohjelmointiin](https://aka.ms/GitHubCopilotAI). @@ -90,42 +89,43 @@ Haluatko oppia lisää? Tutustu [Copilot tekoälypariohjelmointiin](https://aka. ### LangChain -[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j Aloittelijoille](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js Aloittelijoille](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain Aloittelijoille](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents -[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Agentit +[![AZD Aloittelijoille](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI Aloittelijoille](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP Aloittelijoille](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Tekoälyagentit Aloittelijoille](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Generative AI Series -[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Generatiivinen tekoäly -sarja +[![Generatiivinen tekoäly Aloittelijoille](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generatiivinen tekoäly (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generatiivinen tekoäly (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generatiivinen tekoäly (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Keskeinen opiskelu -[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Kyberturvallisuus aloittelijoille](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Web-kehitys aloittelijoille](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT aloittelijoille](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR-kehitys aloittelijoille](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +### Keskeinen oppiminen +[![Koneoppiminen Aloittelijoille](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data-analytiikka Aloittelijoille](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![Tekoäly Aloittelijoille](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![Kyberturvallisuus Aloittelijoille](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Copilot-sarja -[![Copilot tekoälypariohjelmointiin](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot C#/.NET:lle](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot-seikkailu](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Apua @@ -134,17 +134,17 @@ Jos jäät jumiin tai sinulla on kysyttävää tekoälysovellusten rakentamisest [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Jos sinulla on tuotepalautetta tai kohtaat virheitä rakentamisen aikana, käy: +Jos sinulla on tuotepalautetta tai rakennusvirheitä, käy: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Lisenssi -MIT-lisenssi – Katso lisätietoja [LICENSE](../../LICENSE) tiedostosta. +MIT-lisenssi - Katso lisätiedot tiedostosta [LICENSE](../../LICENSE). --- -**Vastuuvapauslauseke**: -Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Pyrimme tarkkuuteen, mutta ota huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä tulee pitää auktoriteettisena lähteenä. Tärkeiden tietojen osalta suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinkäsityksistä tai virhetulkinnoista. +**Vastuuvapauslauseke**: +Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista. \ No newline at end of file diff --git a/translations/fi/docs/GLOSSARY.md b/translations/fi/docs/GLOSSARY.md index 742574d5c..cdfb95a98 100644 --- a/translations/fi/docs/GLOSSARY.md +++ b/translations/fi/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## Sisällysluettelo -- [Peruskäsitteet](../../../docs) -- [LangChain4j-komponentit](../../../docs) -- [AI/ML-käsitteet](../../../docs) -- [Suojausmekanismit](../../../docs) -- [Prompt-suunnittelu](../../../docs) -- [RAG (hakupohjainen generointi)](../../../docs) -- [Agentit ja työkalut](../../../docs) -- [Agenttimoduuli](../../../docs) -- [Mallin kontekstiprotokolla (MCP)](../../../docs) -- [Azure-palvelut](../../../docs) -- [Testaus ja kehitys](../../../docs) - -Nopea viite kursilla käytetyille termeille ja käsitteille. +- [Peruskäsitteet](#peruskäsitteet) +- [LangChain4j Komponentit](#langchain4j-komponentit) +- [AI/ML Käsitteet](#aiml-käsitteet) +- [Suojakaiteet](#suojakaiteet) +- [Prompt-suunnittelu](#prompt-engineering---module-02) +- [RAG (Hakua Tehostettu Generointi)](#rag-retrieval-augmented-generation---module-03) +- [Agentit ja Työkalut](#agents-and-tools---module-04) +- [Agenttien Moduuli](#agentic-module---module-05) +- [Mallin Kontekstiprotokolla (MCP)](#model-context-protocol-mcp---module-05) +- [Azure-palvelut](#azure-services---module-01) +- [Testaus ja Kehitys](#testing-and-development---testing-guide) + +Pikaviite kurssin aikana käytettyihin termeihin ja käsitteisiin. ## Peruskäsitteet -**AI Agentti** – Järjestelmä, joka käyttää tekoälyä järkeilyyn ja toimintaan itsenäisesti. [Moduuli 04](../04-tools/README.md) +**AI Agentti** - Järjestelmä, joka käyttää tekoälyä päättelemiseen ja toimimiseen itsenäisesti. [Moduuli 04](../04-tools/README.md) -**Ketju** – Toimintojen sarja, jossa tulos syötetään seuraavaan vaiheeseen. +**Ketju** - Toimintojen sarja, jossa yksi tuotanto syöttää seuraavaan vaiheeseen. -**Paloittelu (Chunking)** – Asiakirjojen pilkkominen pienempiin osiin. Tyypillisesti 300–500 tokenia päällekkäisyydellä. [Moduuli 03](../03-rag/README.md) +**Paloittelu** - Asiakirjojen jakaminen pienempiin osiin. Tyypillinen: 300–500 tokenia päällekkäin. [Moduuli 03](../03-rag/README.md) -**Kontekstin ikkuna** – Maksimi tokenien määrä, jonka malli voi käsitellä. GPT-5.2: 400K tokenia (enintään 272K syöte, 128K tuotos). +**Kontekstin Ikkuna** - Maksimimäärä tokeneita, joita malli voi käsitellä. GPT-5.2: 400K tokenia (jopa 272K syöte, 128K tuloste). -**Upotukset (Embeddings)** – Numeromuotoiset vektorit, jotka edustavat tekstin merkitystä. [Moduuli 03](../03-rag/README.md) +**Upotukset** - Numeromuotoisia vektoreita, jotka kuvaavat tekstin merkitystä. [Moduuli 03](../03-rag/README.md) -**Funktiokutsu** – Malli tuottaa jäsenneltyjä pyyntöjä kutsuakseen ulkoisia funktioita. [Moduuli 04](../04-tools/README.md) +**Funktiokutsut** - Malli tuottaa jäsenneltyjä pyyntöjä ulkoisten funktioiden kutsumiseksi. [Moduuli 04](../04-tools/README.md) -**Hallusinaatiot** – Kun mallit tuottavat virheellistä mutta uskottavaa tietoa. +**Hallusinaatio** - Tilanne, jossa mallit tuottavat virheellistä mutta uskottavaa tietoa. -**Promptti** – Tekstisyöte kielimallille. [Moduuli 02](../02-prompt-engineering/README.md) +**Prompt** - Tekstisyöte kielimallille. [Moduuli 02](../02-prompt-engineering/README.md) -**Semanttinen haku** – Haku merkityksen mukaan upotuksia hyödyntäen, ei avainsanoilla. [Moduuli 03](../03-rag/README.md) +**Semanttinen Haku** - Haku merkityksen mukaan upotuksia käyttäen, ei avainsanoilla. [Moduuli 03](../03-rag/README.md) -**Tilallinen vs. tilaton** – Tilaton: ei muistia. Tilallinen: ylläpitää keskusteluhistoriaa. [Moduuli 01](../01-introduction/README.md) +**Tilan säilyttäminen vs. tilaton** - Tilaton: ei muistia. Tilallinen: säilyttää keskusteluhistorian. [Moduuli 01](../01-introduction/README.md) -**Tokenit** – Perusyksiköt, joita mallit käyttävät. Vaikuttaa kustannuksiin ja rajoihin. [Moduuli 01](../01-introduction/README.md) +**Tokenit** - Perusyksiköt, joita mallit käsittelevät. Vaikuttavat kustannuksiin ja rajoihin. [Moduuli 01](../01-introduction/README.md) -**Työkaluketjutus** – Peräkkäinen työkalujen suoritus, jossa tulos ohjaa seuraavaa kutsua. [Moduuli 04](../04-tools/README.md) +**Työkaluketjutus** - Työkalujen peräkkäinen suoritus, jossa tuotanto ohjaa seuraavaa kutsua. [Moduuli 04](../04-tools/README.md) -## LangChain4j-komponentit +## LangChain4j Komponentit -**AiServices** – Luo tyyppiturvalliset tekoälypalvelu-rajapinnat. +**AiServices** - Luo tyyppiturvalliset AI-palvelurajapinnat. -**OpenAiOfficialChatModel** – Yhdistetty asiakas OpenAI:n ja Azure OpenAI:n malleille. +**OpenAiOfficialChatModel** - Yhtenäinen asiakas OpenAI:n ja Azure OpenAI:n malleille. -**OpenAiOfficialEmbeddingModel** – Luo upotuksia OpenAI Official -asiakasta käyttäen (tukee sekä OpenAI:ta että Azure OpenAI:ta). +**OpenAiOfficialEmbeddingModel** - Luo upotuksia OpenAI Official -asiakkaalla (tukee sekä OpenAI:ta että Azure OpenAI:ta). -**ChatModel** – Ydinkäyttöliittymä kielimalleille. +**ChatModel** - Kielimallien ydinrajapinta. -**ChatMemory** – Pitää yllä keskusteluhistoriaa. +**ChatMemory** - Säilyttää keskusteluhistorian. -**ContentRetriever** – Löytää relevantteja asiakirjan palasia RAG:ia varten. +**ContentRetriever** - Löytää olennaisia asiakirjapaloja RAG:ia varten. -**DocumentSplitter** – Pilkkoo asiakirjat paloiksi. +**DocumentSplitter** - Jakaa asiakirjat paloihin. -**EmbeddingModel** – Muuntaa tekstin numeerisiksi vektoreiksi. +**EmbeddingModel** - Muuntaa tekstin numeerisiksi vektoreiksi. -**EmbeddingStore** – Tallentaa ja hakee upotuksia. +**EmbeddingStore** - Tallentaa ja hakee upotuksia. -**MessageWindowChatMemory** – Pitää yllä liukuvaa ikkunaa viimeisimmistä viesteistä. +**MessageWindowChatMemory** - Säilyttää liukuvan ikkunan viimeisimmistä viesteistä. -**PromptTemplate** – Luo uudelleenkäytettäviä promptteja `{{variable}}`-paikkamerkkejä käyttäen. +**PromptTemplate** - Luo uudelleenkäytettäviä prompt-malleja `{{variable}}` paikkamerkeillä. -**TextSegment** – Tekstipala metatiedoilla. Käytetään RAG:ssa. +**TextSegment** - Tekstipala metatiedolla. Käytetään RAG:issa. -**ToolExecutionRequest** – Edustaa työkalun suorituspyyntöä. +**ToolExecutionRequest** - Edustaa työkalun suorituspyyntöä. -**UserMessage / AiMessage / SystemMessage** – Keskusteluviestityypit. +**UserMessage / AiMessage / SystemMessage** - Keskusteluviestityypit. -## AI/ML-käsitteet +## AI/ML Käsitteet -**Few-Shot-oppiminen** – Tarjoaa esimerkkejä promptissa. [Moduuli 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Esimerkkien antaminen promptissa. [Moduuli 02](../02-prompt-engineering/README.md) -**Suuri kielimalli (LLM)** – Suuret tekoälymallit, jotka on koulutettu valtavilla tekstidatoilla. +**Suuri Kielimalli (LLM)** - Tekoälymalleja, jotka on koulutettu laajalla tekstidatalla. -**Järkeilytyömäärä** – GPT-5.2:n parametri, joka ohjaa ajattelun syvyyttä. [Moduuli 02](../02-prompt-engineering/README.md) +**Päätelmätarkkuus** - GPT-5.2:n parametri, joka säätelee pohdinnan syvyyttä. [Moduuli 02](../02-prompt-engineering/README.md) -**Lämpötila** – Ohjaa tuotoksen satunnaisuutta. Matala=deterministinen, korkea=luova. +**Lämpötila** - Säätää tuotannon satunnaisuutta. Matala=deterministinen, korkea=luova. -**Vektoritietokanta** – Erityistietokanta upotuksille. [Moduuli 03](../03-rag/README.md) +**Vektoripohjainen Tietokanta** - Erikoistunut tietokanta upotuksille. [Moduuli 03](../03-rag/README.md) -**Zero-Shot-oppiminen** – Suorittaa tehtäviä ilman esimerkkejä. [Moduuli 02](../02-prompt-engineering/README.md) +**Nollakoeoppiminen** - Tehtävien suorittaminen ilman esimerkkejä. [Moduuli 02](../02-prompt-engineering/README.md) -## Suojausmekanismit - [Moduuli 00](../00-quick-start/README.md) +## Suojakaiteet -**Defense in Depth** – Monikerroksinen suojausmenetelmä, joka yhdistää sovellustason suojaukset ja palveluntarjoajan turvallisuussuodattimet. +**Monitasoinen Suojaus** - Usean kerroksen turvamenetelmä, joka yhdistää sovellustason suojakaiteet tarjoajan turvallisuussuodattimiin. -**Kova esto** – Palveluntarjoaja palauttaa HTTP 400 -virheen vakavista sisällön rikkomuksista. +**Hard Block** - Tarjoaja palauttaa HTTP 400 virheen vakavista sisältörikkomuksista. -**InputGuardrail** – LangChain4j-rajapinta käyttäjän syötteen validointiin ennen LLM:ää. Säästää kustannuksia ja viiveitä estämällä haitalliset promptit varhain. +**InputGuardrail** - LangChain4j-rajapinta käyttäjän syötteen validointiin ennen LLM:ää. Säästää kustannuksia ja viivettä blokkaamalla haitalliset promptit varhaisessa vaiheessa. -**InputGuardrailResult** – Palautustyyppi suojauksen validointiin: `success()` tai `fatal("syy")`. +**InputGuardrailResult** - Palautustyyppi suojakaiteen validoinnissa: `success()` tai `fatal("syy")`. -**OutputGuardrail** – Rajapinta AI-vastausten validointiin ennen niiden palaut tamista käyttäjille. +**OutputGuardrail** - Rajapinta AI-vastausten validointiin ennen palauttamista käyttäjälle. -**Palveluntarjoajan turvallisuussuodattimet** – AI-palveluntarjoajien sisäänrakennetut sisältösuodattimet (esim. GitHub Models), jotka pysäyttävät rikkomukset API-tasolla. +**Providerin Turvasuodattimet** - AI-palveluntarjoajien (esim. Azure OpenAI) sisäänrakennetut sisältösuodattimet, jotka havaitsevat rikkomukset API-tasolla. -**Pehmeä kieltäytyminen** – Malli kieltäytyy kohteliaasti vastaamasta ilman virheilmoitusta. +**Pehmeä Kieltäytyminen** - Malli kohteliaasti kieltäytyy vastaamasta ilman virhettä. ## Prompt-suunnittelu - [Moduuli 02](../02-prompt-engineering/README.md) -**Ketjureaaliajattelu** – Askel askeleelta järkeily parempaan tarkkuuteen. +**Ajatusketju** - Askel askeleelta -päätelmät paremman tarkkuuden saavuttamiseksi. -**Rajoitettu tuotos** – Määrätyn muodon tai rakenteen pakkokeino. +**Rajoitettu Tuotos** - Tietyn muodon tai rakenteen pakottaminen. -**Korkea innokkuus** – GPT-5.2 -kuvio perusteelliseen järkeilyyn. +**Korkea Innokkuus** - GPT-5.2 kuvio perusteelliseen päättelyyn. -**Matala innokkuus** – GPT-5.2 -kuvio nopeisiin vastauksiin. +**Matala Innokkuus** - GPT-5.2 kuvio nopeisiin vastauksiin. -**Monikertakeskustelu** – Kontextin ylläpito vaihdoissa. +**Monikierroksinen Keskustelu** - Kontekstin ylläpito vaihtojen välillä. -**Roolipohjainen prompttaus** – Mallin persoonan asettaminen järjestelmäviesteillä. +**Roolipohjainen Prompttaus** - Mallipersoonan asettaminen järjestelmäviestein. -**Itsearviointi** – Malli arvioi ja parantaa omaa tuotostaan. +**Itsetutkiskelu** - Malli arvioi ja parantaa omaa tuotostaan. -**Rakenteellinen analyysi** – Kiinteä arviointikehys. +**Rakenteellinen Analyysi** - Kiinteä arviointikehys. -**Tehtävän suorituksen malli** – Suunnittele → Suorita → Tiivistä. +**Tehtävän Suorituskuvio** - Suunnittele → Suorita → Yhteenveto. -## RAG (hakupohjainen generointi) - [Moduuli 03](../03-rag/README.md) +## RAG (Hakua Tehostettu Generointi) - [Moduuli 03](../03-rag/README.md) -**Asiakirjojen käsittelyputki** – Lataa → paloita → upota → tallenna. +**Asiakirjaprosessointiputki** - Lataa → paloita → upota → tallenna. -**Muistipohjainen upotustallennus** – Ei-pysyvä tallennustila testaukseen. +**Muistipohjainen Upotusvarasto** - Ei-pysyvä tallennus testaukseen. -**RAG** – Yhdistää haun ja generoinnin vastusten perustamiseksi. +**RAG** - Yhdistää tiedonhakua ja generointia vastauksen perustaksi. -**Samanlaisuuspisteet** – Semanttisen samankaltaisuuden mitta (0–1). +**Samanlaisuuspisteet** - Mitta (0-1) semanttisen samankaltaisuuden asteesta. -**Lähteiden viittaus** – Metatiedot haetusta sisällöstä. +**Lähdeviite** - Metatiedot haetusta sisällöstä. -## Agentit ja työkalut - [Moduuli 04](../04-tools/README.md) +## Agentit ja Työkalut - [Moduuli 04](../04-tools/README.md) -**@Tool-annotaatio** – Merkitsee Java-metodit tekoälyn kutsuttaviksi työkaluiksi. +**@Tool Annotaation** - Merkitsee Java-metodit tekoälyn kutsumiksi työkaluiksi. -**ReAct-kuvio** – Järkeile → Toimi → Havainnoi → Toista. +**ReAct Kuvio** - Pätee → Toimi → Havainnoi → Toista. -**Istunnon hallinta** – Eri käyttäjille erilliset kontekstit. +**Istunnon Hallinta** - Eri käyttäjille erilliset kontekstit. -**Työkalu** – Funktio, jota AI-agentti voi kutsua. +**Työkalu** - Toiminto, jonka tekoälyagentti voi kutsua. -**Työkalun kuvaus** – Dokumentaatio työkalun tarkoituksesta ja parametreista. +**Työkalun Kuvaus** - Dokumentaatio työkalun tarkoituksesta ja parametreista. -## Agenttimoduuli - [Moduuli 05](../05-mcp/README.md) +## Agenttien Moduuli - [Moduuli 05](../05-mcp/README.md) -**@Agent-annotaatio** – Merkitsee rajapinnat tekoälyagenteiksi, joilla on deklaratiivinen käyttäytymismäärittely. +**@Agent Annotaation** - Merkitsee rajapinnat tekoälyagenteiksi deklaratiivisella käyttäytymismäärittelyllä. -**Agent-kuuntelija** – Koukkupiste agentin suorituksen seurantaan `beforeAgentInvocation()` ja `afterAgentInvocation()` kautta. +**Agentin Kuuntelija** - Hook agentin suorituksen valvontaan `beforeAgentInvocation()` ja `afterAgentInvocation()` kautta. -**Agenttinen laajuus** – Jaettu muisti, johon agentit tallentavat tulokset `outputKey`-avaimella seuraaville agenteille käytettäväksi. +**Agenttien Muisti** - Jaettu muisti, johon agentit tallentavat tuotoksia `outputKey` avulla, jota alemmat agentit voivat käyttää. -**AgenticServices** – Tehdas agenttien luomiseen `agentBuilder()`- ja `supervisorBuilder()`-metodeilla. +**Agenttien Palvelut** - Tehdas agenttien luomiseen `agentBuilder()` ja `supervisorBuilder()` -menetelmillä. -**Ehdollinen työnkulku** – Reittaus ehtojen perusteella eri asiantuntija-agentteihin. +**Ehdollinen Työnkulku** - Reititys ehdon perusteella eri erikoisagentteihin. -**Ihmisen rooli prosessissa** – Työnkulku, joka lisää ihmisen tarkastus- tai hyväksyntävaiheita. +**Ihminen Silmukassa** - Työnkulku, jossa on ihmisen tarkastuspisteet hyväksynnälle tai sisällön tarkastukselle. -**langchain4j-agentic** – Maven-riippuvuus deklaratiiviseen agenttirakentamiseen (kokeellinen). +**langchain4j-agentic** - Maven-riippuvuus deklaratiiviseen agentinrakentamiseen (kokeellinen). -**Silmukkatyönkulku** – Agentin suorituksen toisto, kunnes ehto täyttyy (esim. laatupisteet ≥ 0.8). +**Silmukka Työnkulku** - Toistetaan agentin suoritus, kunnes ehto täyttyy (esim. laatuarvo ≥ 0.8). -**outputKey** – Agentti-annotaation parametri, joka määrittää missä tulokset tallennetaan Agenttiseen laajuuteen. +**outputKey** - Agenttiannotaation parametri, joka määrittää minne tulokset tallennetaan agenttien muistissa. -**Rinnakkainen työnkulku** – Useiden agenttien yhtäaikainen suoritus riippumattomille tehtäville. +**Rinnakkainen Työnkulku** - Usean agentin samanaikainen suoritus riippumattomille tehtäville. -**Vastausstrategia** – Kuinka valvoja muodostaa lopullisen vastauksen: VIIMEINEN, YHTEENVETO tai PISTETTY. +**Vastausstrategia** - Miten valvoja muotoilee lopullisen vastauksen: VIIMEINEN, YHTEENVETO tai ARVIOITU. -**Järjestelmällinen työnkulku** – Agenttien suoritus järjestyksessä, jossa tulokset siirtyvät seuraavaan vaiheeseen. +**Järjestyksellinen Työnkulku** - Suoritetaan agentit peräkkäin, jolloin tuotanto virtaa seuraavaan vaiheeseen. -**Valvoja-agenttikuva** – Edistynyt agenttipatteri, jossa valvoja-LLM päättää dynaamisesti alitehtävien kutsumisesta. +**Valvojan Agenttikuvio** - Edistynyt agenttikuva, jossa valvoja-LLM päättää dynaamisesti, mitä ala-agentteja kutsutaan. -## Mallin kontekstiprotokolla (MCP) - [Moduuli 05](../05-mcp/README.md) +## Mallin Kontekstiprotokolla (MCP) - [Moduuli 05](../05-mcp/README.md) -**langchain4j-mcp** – Maven-riippuvuus MCP-integraatioon LangChain4j:ssä. +**langchain4j-mcp** - Maven-riippuvuus MCP-integraatioon LangChain4j:ssä. -**MCP** – Model Context Protocol: standardi AI-sovellusten liittämiseen ulkoisiin työkaluihin. Rakennat kerran, käytät kaikkialla. +**MCP** - Model Context Protocol: standardi AI-sovellusten liittämiseksi ulkoisiin työkaluihin. Rakennetaan kerran, käytetään kaikkialla. -**MCP-asiakas** – Sovellus, joka yhdistää MCP-palvelimiin löytääkseen ja käyttääkseen työkaluja. +**MCP Client** - Sovellus, joka yhdistää MCP-palvelimiin työkalujen löytöä ja käyttöä varten. -**MCP-palvelin** – Palvelu, joka tarjoaa työkaluja MCP:n kautta selkeillä kuvauksilla ja parametrikaavoilla. +**MCP Server** - Palvelu, joka tarjoaa työkalut MCP:n kautta selkeine kuvauksineen ja parametriskaaloineen. -**McpToolProvider** – LangChain4j-komponentti, joka käärii MCP-työkalut käyttöön AI-palveluissa ja agenteissa. +**McpToolProvider** - LangChain4j-komponentti, joka käärii MCP-työkalut AI-palvelujen ja agenttien käyttöön. -**McpTransport** – Rajapinta MCP-kommunikaatioon. Toteutuksia ovat mm. Stdio ja HTTP. +**McpTransport** - Rajapinta MCP-viestintään. Toteutuksia ovat Stdio ja HTTP. -**Stdio-kuljetus** – Paikallinen prosessikuljetus stdin/stdoutin kautta. Hyödyllinen tiedostojärjestelmän tai komentorivityökalujen käyttöön. +**Stdio Transport** - Paikallinen prosessikuljetus stdin/stdoutin kautta. Kätevä tiedostojärjestelmän käyttöön tai komentorivityökaluihin. -**StdioMcpTransport** – LangChain4j:n toteutus, joka käynnistää MCP-palvelimen aliprosessina. +**StdioMcpTransport** - LangChain4j-toteutus, joka käynnistää MCP-palvelimen aliprosessina. -**Työkalujen löytäminen** – Asiakas kysyy palvelimelta saatavilla olevat työkalut kuvauksineen ja kaavoineen. +**Työkalujen Löytäminen** - Client kysyy palvelimelta saatavilla olevat työkalut kuvauksineen ja skeemoineen. ## Azure-palvelut - [Moduuli 01](../01-introduction/README.md) -**Azure AI Search** – Pilvipohjainen haku vektoritoiminnoilla. [Moduuli 03](../03-rag/README.md) +**Azure AI Search** - Pilvihakuratkaisu vektoritoiminnoilla. [Moduuli 03](../03-rag/README.md) -**Azure Developer CLI (azd)** – Azure-resurssien käyttöönotto. +**Azure Developer CLI (azd)** - Azure-resurssien käyttöönotto. -**Azure OpenAI** – Microsoftin yritystason tekoälypalvelu. +**Azure OpenAI** - Microsoftin yritystason tekoälypalvelu. -**Bicep** – Azure infrastruktuurin koodikieli. [Infrastruktuuriopas](../01-introduction/infra/README.md) +**Bicep** - Azure infrastruktuurikaavan kieli. [Infrastruktuuriohje](../01-introduction/infra/README.md) -**Käyttöönoton nimi** – Mallin käyttöönoton nimi Azuressa. +**Käyttöönoton Nimi** - Mallin käyttöönoton nimi Azure-palvelussa. -**GPT-5.2** – Uusin OpenAI-malli, jossa järkeilyn ohjaus. [Moduuli 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Uusin OpenAI:n malli, jossa on päätelmien ohjaus. [Moduuli 02](../02-prompt-engineering/README.md) -## Testaus ja kehitys - [Testausopas](TESTING.md) +## Testaus ja Kehitys - [Testausopas](TESTING.md) -**Dev Container** – Konttitoiminen kehitysympäristö. [Konfigurointi](../../../.devcontainer/devcontainer.json) +**Dev Container** - Kontitetty kehitysympäristö. [Konfiguraatio](../../../.devcontainer/devcontainer.json) -**GitHub Models** – Ilmainen tekoälymallien leikkikenttä. [Moduuli 00](../00-quick-start/README.md) +**Muistitestaus** - Testaus muistipohjaisen tallennuksen avulla. -**Muistipohjainen testaus** – Testaus muistipohjaisella tallennuksella. +**Integraatiotestaus** - Testaus todellisella infrastruktuurilla. -**Integraatiotestaus** – Testaus todellisella infrastruktuurilla. +**Maven** - Java build-automaatio työkalu. -**Maven** – Java-rakennusautomaatio. +**Mockito** - Java-kirjaston testauskirjasto. -**Mockito** – Java-kirjastojen mockaustyökalu. - -**Spring Boot** – Java-sovelluskehys. [Moduuli 01](../01-introduction/README.md) +**Spring Boot** - Java sovelluskehys. [Moduuli 01](../01-introduction/README.md) --- **Vastuuvapauslauseke**: -Tämä asiakirja on käännetty käyttäen tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, huomioithan, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja omalla kielellään on ensisijainen lähde. Tärkeissä tiedoissa suosittelemme ammattilaisen tekemää käännöstä. Emme ole vastuussa tämän käännöksen käytöstä johtuvista väärinkäsityksistä tai virhetulkinnoista. +Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista. \ No newline at end of file diff --git a/translations/fi/docs/TESTING.md b/translations/fi/docs/TESTING.md index d5d28f853..fbfddc138 100644 --- a/translations/fi/docs/TESTING.md +++ b/translations/fi/docs/TESTING.md @@ -2,17 +2,17 @@ ## Sisällysluettelo -- [Pikaopas](../../../docs) -- [Mitä testit kattavat](../../../docs) -- [Testien suorittaminen](../../../docs) -- [Testien suorittaminen VS Codessa](../../../docs) -- [Testausmallit](../../../docs) -- [Testausfilosofia](../../../docs) -- [Seuraavat askeleet](../../../docs) +- [Pika-aloitus](#pika-aloitus) +- [Mitä testit kattavat](#mitä-testit-kattavat) +- [Testien suorittaminen](#testien-suorittaminen) +- [Testien suorittaminen VS Codessa](#testien-suorittaminen-vs-codessa) +- [Testausmallit](#testausmallit) +- [Testausfilosofia](#testausfilosofia) +- [Seuraavat askeleet](#seuraavat-askelket) -Tämä opas kävelee sinut läpi testien, jotka osoittavat, kuinka testata tekoälysovelluksia ilman, että tarvitset API-avaimia tai ulkoisia palveluita. +Tämä opas ohjaa sinut testien läpi, jotka demonstroivat, kuinka testata tekoälysovelluksia ilman API-avaimia tai ulkoisia palveluita. -## Pikaopas +## Pika-aloitus Suorita kaikki testit yhdellä komennolla: @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Kun kaikki testit onnistuvat, näet alla olevan kuvakaappauksen kaltaisen lopputuloksen — testit suoritetaan ilman yhtään virhettä. +Kun kaikki testit läpäisevät, näet alla olevan kaltaisen tulosteen — testit suoritetaan ilman virheitä. -Onnistuneet testitulokset +Successful Test Results -*Onnistuneen testiajon tulos näyttää kaikki testit läpäistyinä ilman virheitä* +*Onnistuneen testin suoritus näyttää kaikki testit läpäistyinä ilman virheitä* ## Mitä testit kattavat -Tämä kurssi keskittyy **yksikkötesteihin**, jotka suoritetaan paikallisesti. Jokainen testi esittelee tietyn LangChain4j-konseptin erillään. Alla oleva testauspyramidi näyttää, mihin yksikkötestit sopivat — ne muodostavat nopean ja luotettavan perustan, jolle muu testausstrategiasi rakentuu. +Tämä kurssi keskittyy **yksikkötesteihin**, jotka suoritetaan paikallisesti. Jokainen testi demonstroi tiettyä LangChain4j-konseptia eristetysti. Alla oleva testauksen pyramidi näyttää, missä yksikkötestit sijoittuvat — ne muodostavat nopean, luotettavan perustan, jolle muu testausstrategiasi rakentuu. -Testauspyramidi +Testing Pyramid -*Testauspyramidi näyttää tasapainon yksikkötestien (nopeat, eristetyt), integraatiotestien (todelliset komponentit) ja loppukäyttäjätestien välillä. Tämä koulutus kattaa yksikkötestauksen.* +*Testauspyramidi näyttää tasapainon yksikkötestien (nopeat, eristetyt), integraatiotestien (todelliset komponentit) ja päätepisteestä päätepisteeseen tehtävien testien välillä. Tämä koulutus kattaa yksikkötestauksen.* -| Moduuli | Testit | Painopiste | Keskeiset tiedostot | +| Moduuli | Testit | Fokus | Avaintiedostot | |--------|-------|-------|-----------| -| **00 - Pikaopas** | 6 | Kehote-pohjat ja muuttujien korvaus | `SimpleQuickStartTest.java` | -| **01 - Johdanto** | 8 | Keskustelumuisti ja tilallinen keskustelu | `SimpleConversationTest.java` | -| **02 - Kehoteinsinöörityö** | 12 | GPT-5.2-kuviot, innokkuustasot, jäsennelty tuloste | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Asiakirjojen sisäänotto, upotukset, samankaltaisuushaku | `DocumentServiceTest.java` | +| **01 - Johdanto** | 8 | Keskustelumuisti ja tilalliset chatit | `SimpleConversationTest.java` | +| **02 - Prompt-engineering** | 12 | GPT-5.2-mallit, innokkuustasot, jäsennelty ulostulo | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Dokumenttien syöttö, upotukset, samankaltaisuushaku | `DocumentServiceTest.java` | | **04 - Työkalut** | 12 | Funktiokutsut ja työkaluketjut | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol stdio-siirrolla | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | Mallikontekstiprotokolla stdio-siirrolla | `SimpleMcpTest.java` | ## Testien suorittaminen -**Suorita kaikki testit juurihakemistosta:** +**Suorita kaikki testit juuresta:** **Bash:** ```bash @@ -63,19 +62,19 @@ mvn test mvn --% test ``` -**Suorita testit tietylle moduulille:** +**Suorita testit tietyssä moduulissa:** **Bash:** ```bash cd 01-introduction && mvn test -# Tai juurihakemistosta +# Tai juuresta mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Tai juurihakemistosta +# Tai juuresta mvn --% test -pl 01-introduction ``` @@ -95,41 +94,41 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#tulisiSäilyttääKeskusteluhistoria +mvn test -Dtest=SimpleConversationTest#pitäisi säilyttää keskusteluhistoria ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#tulisiko säilyttää keskusteluhistoria +mvn --% test -Dtest=SimpleConversationTest#tulisi säilyttää keskusteluhistoria ``` ## Testien suorittaminen VS Codessa -Jos käytät Visual Studio Codea, Test Explorer tarjoaa graafisen käyttöliittymän testien suorittamiseen ja virheenkorjaukseen. +Jos käytät Visual Studio Codea, Test Explorer tarjoaa graafisen käyttöliittymän testien ajamiseen ja virheiden etsintään. VS Code Test Explorer -*VS Code Test Explorer näyttää testipuuston, jossa kaikki Java-testiluokat ja yksittäiset testimetodit* +*VS Code Test Explorer näyttää testipuuhun kaikki Java-testiluokat ja yksittäiset testimetodit* **Testien suorittaminen VS Codessa:** -1. Avaa Test Explorer napsauttamalla reagenssipulloa Aktiviteettipalkissa +1. Avaa Test Explorer klikkaamalla lasipulloikonia Activity Barissa 2. Laajenna testipuuta nähdäksesi kaikki moduulit ja testiluokat -3. Napsauta esityspainiketta minkä tahansa testin vieressä suorittaaksesi sen yksittäin -4. Napsauta "Run All Tests" suorittaaksesi koko testipaketin -5. Oikeaklikkaa mitä tahansa testiä ja valitse "Debug Test" asettaaksesi taukopaikkoja ja astuaksesi koodiin +3. Klikkaa yksittäisen testin vieressä olevaa toistopainiketta ajaaksesi sen erikseen +4. Klikkaa "Run All Tests" suorittaaksesi kaikki testit +5. Klikkaa hiiren oikealla testin päällä ja valitse "Debug Test" asettaaksesi breakpointteja ja seurataksesi koodia askel askeleelta -Test Explorer näyttää vihreät valintamerkit läpäistyille testeille ja antaa yksityiskohtaiset virheilmoitukset, jos testit epäonnistuvat. +Test Explorer näyttää vihreät tägit läpäistyille testeille ja tarjoaa yksityiskohtaiset virheilmoitukset, kun testit epäonnistuvat. ## Testausmallit -### Kuvio 1: Kehote-mallipohjien testaus +### Malli 1: Prompt-mallien testaus -Yksinkertaisin kuvio testaa kehote-mallipohjia ilman, että kutsutaan mitään tekoälymallia. Varmistat, että muuttujien korvaus toimii oikein ja kehote on muotoiltu odotetusti. +Yksinkertaisin malli testaa prompt-malleja ilman, että kutsutaan mitään tekoälymallia. Varmistat, että muuttujien korvaus toimii oikein ja promptit muotoillaan odotetusti. -Kehote-mallipohjan testaus +Prompt Template Testing -*Kehote-mallipohjien testaus näyttää muuttujien korvausprosessin: pohja paikkamerkeillä → arvot sovelletaan → muotoiltu tuloste tarkistetaan* +*Prompt-mallien testaus, joka näyttää muuttujien korvausprosessin: malli paikkamerkkeineen → arvot sovelletaan → muotoiltu ulostulo tarkistetaan* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Tämä testi sijaitsee tiedostossa `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Tämä malli varmistaa, että muuttujien korvaus toimii oikein ja promptit muotoillaan odotetusti — ei tarvita API-avaimia tai mallikutsuja. -**Suorita:** +### Malli 2: Kielimallien peukalointi (Mocking) -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testaaKehyksenMuotoilua -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testaaKehyksenMuotoilua -``` - -### Kuvio 2: Kielen mallien mokkaus - -Keskustelulogiikan testaamiseen käytä Mockitoa luomaan väärennettyjä malleja, jotka palauttavat ennalta määritettyjä vastauksia. Näin testit ovat nopeita, ilmaisia ja määrätietoisia. +Kun testaat keskustelulogiikkaa, käytä Mockitoa luodaksesi väärennettyjä malleja, jotka palauttavat ennaltamäärättyjä vastauksia. Tämä tekee testeistä nopeita, ilmaisia ja määrämuotoisia. -Mokki vs Todellinen API -vertailu +Mock vs Real API Comparison -*Vertailu, miksi mokkeja suositaan testauksessa: ne ovat nopeita, ilmaisia, määrätietoisia eikä niihin tarvita API-avaimia* +*Vertailu, joka näyttää miksi mokkaukset ovat testauksessa parempia: ne ovat nopeita, ilmaisia, määrämukaisia ja eivät vaadi API-avaimia* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 käyttäjä- + 3 tekoälyviestiä + assertThat(history).hasSize(6); // 3 käyttäjä + 3 tekoälyviestiä } } ``` -Tämä kuvio esiintyy tiedostossa `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mokki varmistaa johdonmukaisen käyttäytymisen, jotta voit tarkistaa, että muistin hallinta toimii oikein. +Tämä malli esiintyy tiedostossa `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock varmistaa yhtenäisen käyttäytymisen, jotta voit tarkistaa muistinhallinnan oikeellisuuden. -### Kuvio 3: Keskustelun eristäminen +### Malli 3: Keskustelujen eristäminen testauksessa -Keskustelumuistin tulee pitää useat käyttäjät erillään. Tämä testi varmistaa, etteivät keskustelut sekoita konteksteja. +Keskustelumuistin on pidettävä useat käyttäjät erillään. Tämä testi varmistaa, ettei keskustelujen kontekstit sekoitu. -Keskustelun eristäminen +Conversation Isolation -*Keskustelun eristämisen testaus osoittaa erilliset muistikaupat eri käyttäjille kontekstin sekoittumisen estämiseksi* +*Keskustelujen eristämisen testaus, joka näyttää erilliset muistiyksiköt eri käyttäjille kontekstin sekoittumisen estämiseksi* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Jokaisella keskustelulla on oma itsenäinen historiansa. Tuotantojärjestelmissä tämä eristys on kriittinen monikäyttäjäsovelluksille. +Jokainen keskustelu ylläpitää omaa riippumatonta historiaansa. Tuotantojärjestelmissä tämä eristäminen on kriittistä monikäyttäjäisille sovelluksille. -### Kuvio 4: Työkalujen erillinen testaus +### Malli 4: Työkalujen itsenäinen testaus -Työkalut ovat toimintoja, joita tekoäly voi kutsua. Testaa niitä suoraan varmistaaksesi, että ne toimivat oikein riippumatta tekoälyn päätöksistä. +Työkalut ovat funktioita, joita tekoäly voi kutsua. Testaa niitä suoraan varmistaaksesi, että ne toimivat oikein riippumatta tekoälyn päätöksistä. -Työkalujen testaus +Tools Testing -*Työkalujen itsenäinen testaus näyttää moki-työkalun suorituksen ilman tekoälykutsuja liiketoimintalogiikan varmistamiseksi* +*Työkalujen itsenäinen testaus, joka näyttää peukaloidun työkalun suorituksen ilman tekoälykutsuja liiketoimintalogiikan tarkistamiseksi* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Nämä testit tiedostosta `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validoivat työkalulogiikan ilman tekoälyosallistumista. Ketjutusesimerkki näyttää, kuinka yhden työkalun tulos syötetään toisen syötteeksi. +Nämä testit tiedostosta `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validoivat työkalulogiikan ilman tekoälyn osallisuutta. Ketjutus-esimerkki näyttää, miten yhden työkalun ulostulo syötetään toisen työkalun syötteeksi. -### Kuvio 5: Muistiin perustuva RAG-testaus +### Malli 5: Muistissa tapahtuva RAG-testauksen malli -RAG-järjestelmät vaativat perinteisesti vektoripohjaiset tietokannat ja upotuspalvelut. Muistiin perustuva kuvio antaa sinun testata koko putkea ilman ulkoisia riippuvuuksia. +RAG-järjestelmät vaativat perinteisesti vektorikantoja ja upotusten palveluita. Muistissa tapahtuva malli antaa testata koko putkea ilman ulkoisia riippuvuuksia. -Muistiin perustuva RAG-testaus +In-Memory RAG Testing -*Muistiin perustuva RAG-testing työnkulku näyttää asiakirjan jäsentämisen, upotustallennuksen ja samankaltaisuushaun ilman tietokantaa* +*Muistissa tapahtuvan RAG-testauksen työnkulku, joka näyttää dokumentin jäsentämisen, upotusten tallennuksen ja samankaltaisuushaun ilman tietokantaa* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Tämä testi tiedostosta `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` luo asiakirjan muistiin ja varmistaa pilkkomisen ja metatietojen käsittelyn. +Tämä testi tiedostosta `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` luo dokumentin muistiin ja varmistaa paloittelun ja metadatan käsittelyn. -### Kuvio 6: MCP-integraatiotestaus +### Malli 6: MCP-integraatiotestaus -MCP-moduuli testaa Model Context Protocol -integraatiota stdio-siirron avulla. Nämä testit varmistavat, että sovelluksesi voi käynnistää ja kommunikoida MCP-palvelimien kanssa aliprosesseina. +MCP-moduuli testaa Model Context Protocol -integraatiota stdio-siirtoa käyttäen. Nämä testit varmistavat, että sovelluksesi pystyy käynnistämään MCP-palvelimen aliprosessina ja keskustelemaan sen kanssa. -Testit tiedostossa `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validoivat MCP-asiakkaan käyttäytymisen. +Testit tiedostossa `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validoivat MCP-asiakasohjelman käyttäytymisen. **Suorita ne:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Testausfilosofia -Testaa koodiasi, älä tekoälyä. Testiesi tulisi validoida kirjoittamasi koodi tarkistamalla, miten kehotteet rakentuvat, miten muistia hallitaan ja miten työkalut suoritetaan. Tekoälyn vastaukset vaihtelevat eikä niiden pitäisi olla osa testiväittämiä. Kysy itseltäsi, korvaako kehote-mallisi muuttujat oikein, älä sitä, antaako tekoäly oikean vastauksen. +Testaa omaa koodiasi, älä tekoälyä. Testiesi tulisi validoida kirjoittamasi koodi tarkistamalla, miten promptit rakennetaan, miten muisti hallitaan ja miten työkalut suoritetaan. Tekoälyn vastaukset vaihtelevat, eikä niitä pitäisi käyttää testien väitteissä. Kysy itseltäsi, korvaako prompttemplaatti muuttujat oikein, ei sitä, antako tekoäly oikean vastauksen. -Käytä mokkeja kielimalleille. Ne ovat ulkoisia riippuvuuksia, jotka ovat hitaita, kalliita ja epädeterministisiä. Mokkaus tekee testeistä nopeita, millisekunneissa sekuntien sijaan; ilmaisia ilman API-kustannuksia ja määrätietoisia samaan tulokseen joka kerta. +Käytä mokkeja kielimalleille. Ne ovat ulkoisia riippuvuuksia, jotka ovat hitaita, kalliita ja epädeterministisiä. Mokkaus tekee testeistä nopeita (millisekunneissa sekuntien sijaan), ilmaisia (ei API-kuluja) ja määrämukaisia (sama tulos aina). -Pidä testit itsenäisinä. Jokaisen testin tulisi luoda omat datansa, olla riippumatta muista testeistä ja siivota jälkensä. Testien tulee läpäistä ajosta riippumatta. +Pidä testit itsenäisinä. Jokaisen testin tulisi luoda omat datansa, olla riippumaton muista testeistä ja siivota jälkensä. Testien tulisi läpäistä riippumatta niiden suoritusjärjestyksestä. -Testaa reunatapauksia onnellisen polun ulkopuolella. Kokeile tyhjiä syötteitä, hyvin suuria syötteitä, erikoismerkkejä, virheellisiä parametreja ja raja-arvoja. Nämä paljastavat usein virheitä, joita normaali käyttö ei paljasta. +Testaa reunatapauksia onnellisten polkujen lisäksi. Kokeile tyhjiä syötteitä, hyvin suuria syötteitä, erikoismerkkejä, virheellisiä parametreja ja raja-arvoja. Nämä paljastavat usein virheitä, joita normaali käyttö ei löydä. -Käytä kuvaavia nimiä. Vertaa `shouldMaintainConversationHistoryAcrossMultipleMessages()` ja `test1()` -nimiä. Ensimmäinen kertoo tarkalleen, mitä testataan, jolloin virheenkorjaus on helpompaa. +Käytä kuvaavia nimiä. Vertaa `shouldMaintainConversationHistoryAcrossMultipleMessages()` nimitystä `test1()` kanssa. Ensimmäinen kertoo täsmälleen, mitä testataan, mikä helpottaa vikojen löytämistä. ## Seuraavat askeleet -Nyt kun ymmärrät testausmallit, sukella syvemmälle kuhunkin moduuliin: +Nyt kun ymmärrät testausmallit, sukeltaa syvemmälle kuhunkin moduuliin: -- **[00 - Pikaopas](../00-quick-start/README.md)** - Aloita kehote-mallipohjien perusteista -- **[01 - Johdanto](../01-introduction/README.md)** - Opi keskustelumuistin hallinta -- **[02 - Kehoteinsinöörityö](../02/prompt-engineering/README.md)** - Hallitse GPT-5.2-kehote-kuviot -- **[03 - RAG](../03-rag/README.md)** - Rakenna tiedonhakupohjaiset generointijärjestelmät -- **[04 - Työkalut](../04-tools/README.md)** - Toteuta funktiokutsut ja työkaluketjut -- **[05 - MCP](../05-mcp/README.md)** - Integroi Model Context Protocol +- **[01 - Johdanto](../01-introduction/README.md)** – Opi keskustelumuistin hallinta +- **[02 - Prompt-engineering](../02-prompt-engineering/README.md)** – Hallitse GPT-5.2-mallien käyttötavat +- **[03 - RAG](../03-rag/README.md)** – Rakenna hakua laajentavia generointijärjestelmiä +- **[04 - Työkalut](../04-tools/README.md)** – Toteuta funktiokutsut ja työkaluketjut +- **[05 - MCP](../05-mcp/README.md)** – Integroi Mallikontekstiprotokolla -Jokaisen moduulin README tarjoaa yksityiskohtaiset selitykset täällä testatuista konsepteista. +Jokaisen moduulin README sisältää yksityiskohtaiset selitykset täällä testatuista konsepteista. --- -**Navigointi:** [← Takaisin pääsivulle](../README.md) +**Navigointi:** [← Takaisin päähakemistoon](../README.md) --- **Vastuuvapauslauseke**: -Tämä asiakirja on käännetty AI-käännöspalvelulla [Co-op Translator](https://github.com/Azure/co-op-translator). Pyrimme tarkkuuteen, mutta ole hyvä ja huomioi, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäistä asiakirjaa sen omalla kielellä on pidettävä auktoritatiivisena lähteenä. Tärkeiden tietojen osalta suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai virheellisistä tulkinnoista. +Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, otathan huomioon, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai tulkinnoista. \ No newline at end of file diff --git a/translations/fr/.co-op-translator.json b/translations/fr/.co-op-translator.json index 1c3508550..c73a17c39 100644 --- a/translations/fr/.co-op-translator.json +++ b/translations/fr/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "fr" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T18:24:43+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T07:02:23+00:00", "source_file": "01-introduction/README.md", "language_code": "fr" }, @@ -18,20 +18,20 @@ "language_code": "fr" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T18:27:07+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T06:57:40+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "fr" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T18:28:33+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T07:01:24+00:00", "source_file": "03-rag/README.md", "language_code": "fr" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:16:02+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T06:59:55+00:00", "source_file": "04-tools/README.md", "language_code": "fr" }, @@ -54,8 +54,8 @@ "language_code": "fr" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:31:12+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T06:56:10+00:00", "source_file": "README.md", "language_code": "fr" }, @@ -72,14 +72,14 @@ "language_code": "fr" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T18:31:45+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T06:58:13+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "fr" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T18:32:34+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T06:58:48+00:00", "source_file": "docs/TESTING.md", "language_code": "fr" } diff --git a/translations/fr/00-quick-start/README.md b/translations/fr/00-quick-start/README.md deleted file mode 100644 index e976d73e4..000000000 --- a/translations/fr/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00 : Démarrage rapide - -## Table des matières - -- [Introduction](../../../00-quick-start) -- [Qu'est-ce que LangChain4j ?](../../../00-quick-start) -- [Dépendances LangChain4j](../../../00-quick-start) -- [Prérequis](../../../00-quick-start) -- [Installation](../../../00-quick-start) - - [1. Obtenez votre token GitHub](../../../00-quick-start) - - [2. Configurez votre token](../../../00-quick-start) -- [Exécuter les exemples](../../../00-quick-start) - - [1. Chat de base](../../../00-quick-start) - - [2. Modèles de prompt](../../../00-quick-start) - - [3. Appel de fonctions](../../../00-quick-start) - - [4. Questions/Réponses sur documents (Easy RAG)](../../../00-quick-start) - - [5. IA responsable](../../../00-quick-start) -- [Ce que chaque exemple montre](../../../00-quick-start) -- [Étapes suivantes](../../../00-quick-start) -- [Dépannage](../../../00-quick-start) - -## Introduction - -Ce démarrage rapide vise à vous mettre en route avec LangChain4j le plus rapidement possible. Il couvre les bases absolues de la création d’applications d’IA avec LangChain4j et GitHub Models. Dans les modules suivants, vous passerez à Azure OpenAI et GPT-5.2 et approfondirez chaque concept. - -## Qu'est-ce que LangChain4j ? - -LangChain4j est une bibliothèque Java qui simplifie la création d’applications alimentées par l’IA. Au lieu de gérer des clients HTTP et le parsing JSON, vous travaillez avec des API Java propres. - -Le terme « chaîne » dans LangChain fait référence au chaînage de plusieurs composants – vous pouvez enchaîner un prompt à un modèle puis à un parseur, ou enchaîner plusieurs appels IA où une sortie sert d’entrée au suivant. Ce démarrage rapide se concentre sur les fondamentaux avant d’explorer des chaînes plus complexes. - -Concept de chaînage LangChain4j - -*Chaînage des composants dans LangChain4j – les blocs de construction se connectent pour créer des workflows IA puissants* - -Nous utiliserons trois composants principaux : - -**ChatModel** – Interface pour les interactions avec les modèles IA. Appelez `model.chat("prompt")` et obtenez une chaîne de réponse. Nous utilisons `OpenAiOfficialChatModel` qui fonctionne avec les points d'entrée compatibles OpenAI comme GitHub Models. - -**AiServices** – Crée des interfaces de service IA typées. Définissez des méthodes, annotées avec `@Tool`, et LangChain4j gère l’orchestration. L’IA appelle automatiquement vos méthodes Java quand nécessaire. - -**MessageWindowChatMemory** – Maintient l’historique de conversation. Sans cela, chaque requête est indépendante. Avec, l’IA se souvient des messages précédents et maintient le contexte sur plusieurs tours. - -Architecture LangChain4j - -*Architecture LangChain4j – composants principaux travaillant ensemble pour alimenter vos applications IA* - -## Dépendances LangChain4j - -Ce démarrage rapide utilise trois dépendances Maven dans le [`pom.xml`](../../../00-quick-start/pom.xml) : - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Le module `langchain4j-open-ai-official` fournit la classe `OpenAiOfficialChatModel` qui se connecte aux API compatibles OpenAI. GitHub Models utilise le même format d’API, donc aucun adaptateur spécial n’est nécessaire – il suffit de pointer l’URL de base vers `https://models.github.ai/inference`. - -Le module `langchain4j-easy-rag` fournit la découpe automatique des documents, l’intégration et la recherche, vous permettant de construire des applications RAG sans configurer manuellement chaque étape. - -## Prérequis - -**Utilisez-vous le conteneur de développement ?** Java et Maven sont déjà installés. Vous avez seulement besoin d’un token d'accès personnel GitHub. - -**Développement local :** -- Java 21+, Maven 3.9+ -- Token d'accès personnel GitHub (instructions ci-dessous) - -> **Note :** Ce module utilise `gpt-4.1-nano` de GitHub Models. Ne modifiez pas le nom du modèle dans le code – il est configuré pour fonctionner avec les modèles disponibles chez GitHub. - -## Installation - -### 1. Obtenez votre token GitHub - -1. Allez sur [Paramètres GitHub → Tokens d’accès personnels](https://github.com/settings/personal-access-tokens) -2. Cliquez sur "Générer un nouveau token" -3. Donnez un nom descriptif (ex. « LangChain4j Démo ») -4. Choisissez une expiration (7 jours recommandé) -5. Sous « Permissions du compte », trouvez « Models » et mettez « Lecture seule » -6. Cliquez sur « Générer le token » -7. Copiez et enregistrez votre token – vous ne le reverrez pas - -### 2. Configurez votre token - -**Option 1 : Utiliser VS Code (recommandé)** - -Si vous utilisez VS Code, ajoutez votre token dans le fichier `.env` à la racine du projet : - -Si le fichier `.env` n’existe pas, copiez `.env.example` en `.env` ou créez un nouveau fichier `.env` à la racine du projet. - -**Exemple de fichier `.env` :** -```bash -# Dans /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Ensuite, vous pouvez simplement cliquer-droit sur n’importe quel fichier demo (ex. `BasicChatDemo.java`) dans l’explorateur et sélectionner **"Run Java"** ou utiliser les configurations de lancement dans le panneau Run and Debug. - -**Option 2 : Utiliser le terminal** - -Définissez le token comme variable d’environnement : - -**Bash :** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell :** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Exécuter les exemples - -**Avec VS Code :** Cliquez simplement-droit sur un fichier demo dans l’explorateur et sélectionnez **"Run Java"**, ou utilisez les configurations de lancement dans le panneau Run and Debug (en vous assurant d’avoir ajouté votre token dans le fichier `.env` au préalable). - -**Avec Maven :** Sinon, lancez depuis la ligne de commande : - -### 1. Chat de base - -**Bash :** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell :** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Modèles de prompt - -**Bash :** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell :** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Montre le zero-shot, few-shot, chain-of-thought et les prompts basés sur les rôles. - -### 3. Appel de fonctions - -**Bash :** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell :** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -L’IA appelle automatiquement vos méthodes Java lorsque nécessaire. - -### 4. Questions/Réponses sur documents (Easy RAG) - -**Bash :** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell :** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Posez des questions sur vos documents utilisant Easy RAG avec intégration et recherche automatiques. - -### 5. IA responsable - -**Bash :** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell :** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Voyez comment les filtres de sécurité IA bloquent les contenus nuisibles. - -## Ce que chaque exemple montre - -**Chat de base** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Commencez ici pour voir LangChain4j dans sa forme la plus simple. Vous créerez un `OpenAiOfficialChatModel`, enverrez un prompt avec `.chat()`, et obtiendrez une réponse. Cela montre les bases : comment initialiser les modèles avec des points d’entrée et clés API personnalisés. Une fois ce schéma compris, tout le reste s’appuie dessus. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) et demandez : -> - « Comment passer de GitHub Models à Azure OpenAI dans ce code ? » -> - « Quels autres paramètres puis-je configurer dans OpenAiOfficialChatModel.builder() ? » -> - « Comment ajouter des réponses en streaming au lieu d’attendre la réponse complète ? » - -**Ingénierie des prompts** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Maintenant que vous savez comment parler à un modèle, explorons ce que vous lui dites. Cette démo utilise la même configuration de modèle mais montre cinq modèles de prompt différents. Essayez les prompts zero-shot pour des instructions directes, few-shot qui apprennent à partir d’exemples, chain-of-thought qui révèlent les étapes de raisonnement, et les prompts basés sur les rôles qui définissent le contexte. Vous verrez comment le même modèle donne des résultats très différents selon la formulation de la demande. - -La démo montre aussi des templates de prompt, une façon puissante de créer des prompts réutilisables avec des variables. -L’exemple ci-dessous montre un prompt utilisant `PromptTemplate` LangChain4j pour remplir des variables. L’IA répondra en fonction de la destination et de l’activité indiquées. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) et demandez : -> - « Quelle est la différence entre les prompts zero-shot et few-shot, et quand utiliser chacun ? » -> - « Comment le paramètre temperature influence-t-il les réponses du modèle ? » -> - « Quelles sont les techniques pour prévenir les attaques d’injection de prompt en production ? » -> - « Comment créer des objets PromptTemplate réutilisables pour des modèles courants ? » - -**Intégration d’outils** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -C’est ici que LangChain4j devient puissant. Vous utiliserez `AiServices` pour créer un assistant IA qui peut appeler vos méthodes Java. Il suffit d’annoter les méthodes avec `@Tool("description")` et LangChain4j gère le reste – l’IA décide automatiquement quand utiliser chaque outil selon la demande de l’utilisateur. Cela illustre l’appel de fonction, une technique clé pour construire une IA capable d’agir, pas seulement répondre. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) et demandez : -> - « Comment fonctionne l’annotation @Tool et que fait LangChain4j en coulisses ? » -> - « L’IA peut-elle appeler plusieurs outils en séquence pour résoudre des problèmes complexes ? » -> - « Que se passe-t-il si un outil lance une exception – comment gérer les erreurs ? » -> - « Comment intégrer une vraie API au lieu de cet exemple de calculatrice ? » - -**Questions/Réponses sur documents (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Ici vous verrez RAG (retrieval-augmented generation) avec l’approche « Easy RAG » de LangChain4j. Les documents sont chargés, automatiquement découpés et intégrés dans un magasin en mémoire, puis un récupérateur de contenu fournit les morceaux pertinents à l’IA au moment de la requête. L’IA répond en fonction de vos documents, non de ses connaissances générales. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) et demandez : -> - « Comment RAG prévient-il les hallucinations IA comparé à l’utilisation des données d’entraînement du modèle ? » -> - « Quelle est la différence entre cette approche facile et un pipeline RAG personnalisé ? » -> - « Comment évoluer pour gérer plusieurs documents ou des bases de connaissances plus larges ? » - -**IA responsable** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Construisez la sécurité IA avec une défense en profondeur. Cette démo montre deux couches de protection fonctionnant ensemble : - -**Partie 1 : LangChain4j Input Guardrails** – Bloque les prompts dangereux avant qu’ils n’atteignent le LLM. Créez des garde-fous personnalisés qui vérifient la présence de mots-clés ou motifs interdits. Ils tournent dans votre code, donc rapides et gratuits. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Partie 2 : Filtres de sécurité du fournisseur** – GitHub Models dispose de filtres intégrés qui attrapent ce que vos garde-fous pourraient manquer. Vous verrez des blocages stricts (erreurs HTTP 400) pour violations graves et des refus doux où l’IA décline poliment. - -> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) et demandez : -> - « Qu’est-ce qu’InputGuardrail et comment en créer un ? » -> - « Quelle est la différence entre un blocage dur et un refus doux ? » -> - « Pourquoi utiliser à la fois garde-fous et filtres fournisseur ? » - -## Étapes suivantes - -**Module suivant :** [01-introduction – Premiers pas avec LangChain4j](../01-introduction/README.md) - ---- - -**Navigation :** [← Retour au principal](../README.md) | [Suivant : Module 01 – Introduction →](../01-introduction/README.md) - ---- - -## Dépannage - -### Première compilation Maven - -**Problème :** Le premier `mvn clean compile` ou `mvn package` prend beaucoup de temps (10-15 minutes) - -**Cause :** Maven doit télécharger toutes les dépendances du projet (Spring Boot, bibliothèques LangChain4j, SDK Azure, etc.) lors de la première compilation. - -**Solution :** C’est un comportement normal. Les compilations suivantes seront beaucoup plus rapides car les dépendances sont mises en cache localement. Le temps de téléchargement dépend de la vitesse de votre réseau. - -### Syntaxe des commandes Maven sous PowerShell - -**Problème :** Les commandes Maven échouent avec l’erreur `Unknown lifecycle phase ".mainClass=..."` -**Cause** : PowerShell interprète `=` comme un opérateur d'affectation de variable, ce qui casse la syntaxe des propriétés Maven - -**Solution** : Utilisez l'opérateur d'arrêt d'analyse `--%` avant la commande Maven : - -**PowerShell :** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash :** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -L'opérateur `--%` indique à PowerShell de passer tous les arguments restants littéralement à Maven sans interprétation. - -### Affichage des emojis dans Windows PowerShell - -**Problème** : Les réponses de l'IA affichent des caractères indésirables (par exemple, `????` ou `â??`) au lieu des emojis dans PowerShell - -**Cause** : L'encodage par défaut de PowerShell ne supporte pas les emojis UTF-8 - -**Solution** : Exécutez cette commande avant de lancer les applications Java : -```cmd -chcp 65001 -``` - -Cela force l'encodage UTF-8 dans le terminal. Sinon, utilisez Windows Terminal qui offre une meilleure prise en charge de l'Unicode. - -### Débogage des appels API - -**Problème** : Erreurs d'authentification, limites de taux ou réponses inattendues du modèle d'IA - -**Solution** : Les exemples incluent `.logRequests(true)` et `.logResponses(true)` pour afficher les appels API dans la console. Cela aide à dépanner les erreurs d'authentification, les limites de taux ou les réponses inattendues. Supprimez ces options en production pour réduire les logs. - ---- - - -**Avertissement** : -Ce document a été traduit à l’aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçons d’assurer l’exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue d’origine doit être considéré comme la source faisant foi. Pour les informations cruciales, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous déclinons toute responsabilité en cas de malentendus ou de mauvaises interprétations résultant de l’utilisation de cette traduction. - \ No newline at end of file diff --git a/translations/fr/01-introduction/README.md b/translations/fr/01-introduction/README.md index d7590965a..fd880bba3 100644 --- a/translations/fr/01-introduction/README.md +++ b/translations/fr/01-introduction/README.md @@ -1,22 +1,22 @@ -# Module 01 : Démarrage avec LangChain4j +# Module 01 : Premiers pas avec LangChain4j ## Table des matières -- [Présentation vidéo](../../../01-introduction) -- [Ce que vous apprendrez](../../../01-introduction) -- [Prérequis](../../../01-introduction) -- [Comprendre le problème central](../../../01-introduction) -- [Comprendre les tokens](../../../01-introduction) -- [Comment fonctionne la mémoire](../../../01-introduction) -- [Comment cela utilise LangChain4j](../../../01-introduction) -- [Déployer l'infrastructure Azure OpenAI](../../../01-introduction) -- [Exécuter l'application localement](../../../01-introduction) -- [Utiliser l'application](../../../01-introduction) - - [Chat sans état (panneau de gauche)](../../../01-introduction) - - [Conversation avec état (panneau de droite)](../../../01-introduction) -- [Étapes suivantes](../../../01-introduction) - -## Présentation vidéo +- [Présentation Vidéo](#présentation-vidéo) +- [Ce que vous apprendrez](#ce-que-vous-apprendrez) +- [Prérequis](#prérequis) +- [Comprendre le problème central](#comprendre-le-problème-central) +- [Comprendre les jetons](#comprendre-les-jetons) +- [Comment fonctionne la mémoire](#comment-fonctionne-la-mémoire) +- [Comment cela utilise LangChain4j](#comment-cela-utilise-langchain4j) +- [Déployer l'infrastructure Azure OpenAI](#déployer-linfrastructure-azure-openai) +- [Exécuter l'application localement](#exécuter-lapplication-localement) +- [Utiliser l'application](#utiliser-lapplication) + - [Chat sans état (panneau gauche)](#chat-sans-état-panneau-gauche) + - [Chat avec état (panneau droit)](#chat-avec-état-panneau-droit) +- [Étapes suivantes](#étapes-suivantes) + +## Présentation Vidéo Regardez cette session en direct qui explique comment commencer avec ce module : @@ -24,20 +24,20 @@ Regardez cette session en direct qui explique comment commencer avec ce module : ## Ce que vous apprendrez -Dans le démarrage rapide, vous avez utilisé GitHub Models pour envoyer des invites, appeler des outils, construire un pipeline RAG et tester des garde-fous. Ces démonstrations montraient ce qui est possible — maintenant nous passons à Azure OpenAI et GPT-5.2 pour commencer à construire des applications de style production. Ce module se concentre sur l'IA conversationnelle qui se souvient du contexte et maintient l'état — les concepts que ces démonstrations en démarrage rapide utilisaient en coulisses mais n'expliquaient pas. +C'est votre point de départ avec LangChain4j et Azure OpenAI. Nous commençons par les fondamentaux et commençons à construire des applications de type production. Ce module se concentre sur l'IA conversationnelle qui se souvient du contexte et maintient l'état — les concepts fondamentaux sur lesquels chaque module ultérieur se base. -Nous utiliserons Azure OpenAI GPT-5.2 tout au long de ce guide car ses capacités avancées de raisonnement rendent le comportement de différents modèles plus apparent. Lorsque vous ajoutez de la mémoire, vous verrez clairement la différence. Cela facilite la compréhension de ce que chaque composant apporte à votre application. +Nous utiliserons GPT-5.2 d'Azure OpenAI tout au long de ce guide car ses capacités de raisonnement avancées rendent le comportement des différents modèles plus évident. Lorsque vous ajoutez la mémoire, vous verrez clairement la différence. Cela facilite la compréhension de ce que chaque composant apporte à votre application. -Vous construirez une application démontrant les deux modèles : +Vous construirez une application qui démontre les deux modèles : -**Chat sans état** - Chaque requête est indépendante. Le modèle n'a aucun souvenir des messages précédents. C'est le modèle que vous avez utilisé dans le démarrage rapide. +**Chat sans état** – Chaque requête est indépendante. Le modèle ne se souvient pas des messages précédents. C’est le point de départ le plus simple. -**Conversation avec état** - Chaque requête inclut l'historique de la conversation. Le modèle maintient le contexte à travers plusieurs échanges. C'est ce que nécessitent les applications en production. +**Conversation avec état** – Chaque requête inclut l’historique de la conversation. Le modèle conserve le contexte sur plusieurs tours. C’est ce dont les applications en production ont besoin. ## Prérequis -- Abonnement Azure avec accès à Azure OpenAI -- Java 21, Maven 3.9+ +- Abonnement Azure avec accès Azure OpenAI +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) @@ -47,41 +47,41 @@ Vous construirez une application démontrant les deux modèles : ## Comprendre le problème central -Les modèles de langage sont sans état. Chaque appel API est indépendant. Si vous envoyez "Je m'appelle John" puis demandez "Comment je m'appelle ?", le modèle ne sait pas que vous venez de vous présenter. Il traite chaque requête comme si c'était la première conversation que vous avez jamais eue. +Les modèles de langage sont sans état. Chaque appel API est indépendant. Si vous envoyez « Je m’appelle John » puis demandez « Quel est mon nom ? », le modèle n’a aucune idée que vous venez de vous présenter. Il traite chaque requête comme si c'était la toute première conversation que vous avez jamais eue. -C'est suffisant pour des questions-réponses simples mais inutilisable pour de vraies applications. Les bots de service client doivent se souvenir de ce que vous leur avez dit. Les assistants personnels ont besoin de contexte. Toute conversation à plusieurs tours nécessite de la mémoire. +Cela fonctionne pour des questions-réponses simples mais est inutile pour de vraies applications. Les bots de service client doivent se souvenir de ce que vous leur avez dit. Les assistants personnels ont besoin de contexte. Toute conversation multi-tours nécessite une mémoire. -Le schéma suivant contraste les deux approches — à gauche, un appel sans état qui oublie votre nom ; à droite, un appel avec état soutenu par ChatMemory qui s'en souvient. +Le diagramme suivant contraste les deux approches — à gauche, un appel sans état qui oublie votre nom ; à droite, un appel avec état soutenu par ChatMemory qui s'en souvient. Stateless vs Stateful Conversations -*La différence entre les conversations sans état (appels indépendants) et avec état (contexte pris en compte)* +*La différence entre conversations sans état (appels indépendants) et avec état (contexte pris en compte)* -## Comprendre les tokens +## Comprendre les jetons -Avant d'entrer dans les conversations, il est important de comprendre les tokens - les unités de base de texte que les modèles de langage traitent : +Avant d’aller dans les conversations, il est important de comprendre les jetons - les unités de base du texte que les modèles de langage traitent : Token Explanation -*Exemple de comment un texte est découpé en tokens - "I love AI!" devient 4 unités de traitement distinctes* +*Exemple de découpage du texte en jetons - « I love AI ! » devient 4 unités de traitement distinctes* -Les tokens sont la manière dont les modèles d'IA mesurent et traitent le texte. Les mots, la ponctuation et même les espaces peuvent être des tokens. Votre modèle a une limite sur le nombre de tokens qu'il peut traiter à la fois (400 000 pour GPT-5.2, avec jusqu'à 272 000 tokens d'entrée et 128 000 tokens de sortie). Comprendre les tokens vous aide à gérer la longueur de la conversation et les coûts. +Les jetons sont la manière dont les modèles IA mesurent et traitent le texte. Les mots, la ponctuation, et même les espaces peuvent être des jetons. Votre modèle a une limite du nombre de jetons qu'il peut traiter en une fois (400 000 pour GPT-5.2, avec jusqu’à 272 000 jetons d’entrée et 128 000 jetons de sortie). Comprendre les jetons vous aide à gérer la longueur des conversations et les coûts. ## Comment fonctionne la mémoire -La mémoire de conversation résout le problème de l'absence d'état en maintenant l'historique des échanges. Avant d'envoyer votre requête au modèle, le cadre ajoute en préfixe les messages précédents pertinents. Quand vous demandez "Comment je m'appelle ?", le système envoie en réalité l’historique complet des messages, permettant au modèle de voir que vous avez précédemment dit "Je m'appelle John". +La mémoire de chat résout le problème sans état en maintenant l’historique de la conversation. Avant d’envoyer votre requête au modèle, le cadre préfixe les messages précédents pertinents. Quand vous demandez « Quel est mon nom ? », le système envoie en réalité tout l’historique de la conversation, permettant au modèle de voir que vous avez précédemment dit « Je m’appelle John ». -LangChain4j fournit des implémentations de mémoire qui gèrent cela automatiquement. Vous choisissez combien de messages conserver et le cadre gère la fenêtre de contexte. Le schéma ci-dessous montre comment MessageWindowChatMemory maintient une fenêtre coulissante des messages récents. +LangChain4j fournit des implémentations de mémoire qui gèrent cela automatiquement. Vous choisissez combien de messages conserver et le cadre gère la fenêtre contextuelle. Le schéma ci-dessous montre comment MessageWindowChatMemory maintient une fenêtre coulissante des messages récents. Memory Window Concept -*MessageWindowChatMemory maintient une fenêtre coulissante des messages récents, supprimant automatiquement les anciens* +*MessageWindowChatMemory maintient une fenêtre coulissante de messages récents, retirant automatiquement les anciens* ## Comment cela utilise LangChain4j -Ce module étend le démarrage rapide en intégrant Spring Boot et en ajoutant la mémoire de conversation. Voici comment les éléments s'assemblent : +Ce module intègre Spring Boot et ajoute la mémoire de conversation. Voici comment les pièces s’assemblent : -**Dépendances** — Ajoutez deux bibliothèques LangChain4j : +**Dépendances** – Ajoutez deux bibliothèques LangChain4j : ```xml @@ -94,7 +94,7 @@ Ce module étend le démarrage rapide en intégrant Spring Boot et en ajoutant l ``` -**Modèle de chat** — Configurez Azure OpenAI comme bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)) : +**Modèle de Chat** – Configurez Azure OpenAI comme un bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)) : ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Le builder lit les identifiants depuis les variables d’environnement définies par `azd up`. Le paramètre `baseUrl` pointant vers votre point de terminaison Azure permet au client OpenAI de fonctionner avec Azure OpenAI. +Le builder lit les identifiants depuis les variables d’environnement définies par `azd up`. Le paramètre `baseUrl` vers votre point d’accès Azure permet au client OpenAI de fonctionner avec Azure OpenAI. -**Mémoire de conversation** — Suivez l’historique du chat avec MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)) : +**Mémoire de conversation** – Suivez l’historique du chat avec MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)) : ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,39 +124,39 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Créez la mémoire avec `withMaxMessages(10)` pour conserver les 10 derniers messages. Ajoutez les messages utilisateur et IA avec des wrappers typés : `UserMessage.from(text)` et `AiMessage.from(text)`. Récupérez l’historique avec `memory.messages()` et envoyez-le au modèle. Le service stocke des instances de mémoire séparées par ID de conversation, permettant à plusieurs utilisateurs de discuter simultanément. +Créez la mémoire avec `withMaxMessages(10)` pour conserver les 10 derniers messages. Ajoutez les messages utilisateur et IA avec des wrappers typés : `UserMessage.from(text)` et `AiMessage.from(text)`. Récupérez l’historique avec `memory.messages()` et envoyez-le au modèle. Le service stocke des instances de mémoire distinctes par ID de conversation, permettant à plusieurs utilisateurs de discuter simultanément. > **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) et demandez : -> - « Comment MessageWindowChatMemory décide-t-il quels messages supprimer lorsque la fenêtre est pleine ? » -> - « Puis-je implémenter un stockage mémoire personnalisé utilisant une base de données au lieu de la mémoire en RAM ? » -> - « Comment ajouter un résumé pour compresser l'historique ancien des conversations ? » +> - "Comment MessageWindowChatMemory décide-t-il quels messages supprimer lorsque la fenêtre est pleine ?" +> - "Puis-je implémenter un stockage de mémoire personnalisé en utilisant une base de données plutôt que la mémoire in-memory ?" +> - "Comment ajouterais-je une synthèse pour compresser l’historique de la conversation ancienne ?" -Le point de terminaison de chat sans état ignore la mémoire — juste `chatModel.chat(prompt)` comme dans le démarrage rapide. Le point de terminaison avec état ajoute les messages à la mémoire, récupère l’historique et inclut ce contexte à chaque requête. Même configuration de modèle, modèles différents. +L’endpoint de chat sans état évite complètement la mémoire – juste `chatModel.chat(prompt)` comme le démarrage rapide. L’endpoint avec état ajoute les messages à la mémoire, récupère l’historique et inclut ce contexte à chaque requête. Même configuration du modèle, modèles différents. ## Déployer l'infrastructure Azure OpenAI **Bash :** ```bash cd 01-introduction -azd up # Sélectionnez l'abonnement et l'emplacement (eastus2 recommandé) +azd up # Sélectionnez l’abonnement et l’emplacement (eastus2 recommandé) ``` **PowerShell :** ```powershell cd 01-introduction -azd up # Sélectionnez l'abonnement et l'emplacement (estus2 recommandé) +azd up # Sélectionnez l'abonnement et l'emplacement (eastus2 recommandé) ``` -> **Note :** Si vous rencontrez une erreur de type timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), exécutez simplement `azd up` de nouveau. Les ressources Azure peuvent être encore en cours de provisionnement en arrière-plan, et réessayer permet au déploiement de se terminer une fois que les ressources sont dans un état terminal. +> **Note :** Si vous rencontrez une erreur de timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), lancez simplement `azd up` à nouveau. Les ressources Azure peuvent encore être en cours de provisionnement en arrière-plan, et retenter permet au déploiement de se terminer une fois les ressources à un état terminal. Cela va : 1. Déployer la ressource Azure OpenAI avec les modèles GPT-5.2 et text-embedding-3-small -2. Générer automatiquement le fichier `.env` à la racine du projet avec les identifiants +2. Générer automatiquement un fichier `.env` à la racine du projet avec les identifiants 3. Configurer toutes les variables d’environnement nécessaires -**Vous avez des problèmes de déploiement ?** Consultez le [README Infrastructure](infra/README.md) pour un dépannage détaillé incluant les conflits de noms de sous-domaines, les étapes manuelles via le portail Azure, et des conseils sur la configuration du modèle. +**Vous avez des problèmes de déploiement ?** Consultez le [README Infrastructure](infra/README.md) pour des conseils détaillés de dépannage incluant conflits de noms de sous-domaines, étapes manuelles de déploiement via le portail Azure, et guide de configuration des modèles. -**Vérifiez que le déploiement a réussi :** +**Vérifier que le déploiement a réussi :** **Bash :** ```bash @@ -168,7 +168,7 @@ cat ../.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, etc. Get-Content ..\.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, etc. ``` -> **Note :** La commande `azd up` génère automatiquement le fichier `.env`. Si vous devez le mettre à jour plus tard, vous pouvez soit éditer le fichier `.env` manuellement, soit le régénérer en exécutant : +> **Note :** La commande `azd up` génère automatiquement le fichier `.env`. Si vous avez besoin de le mettre à jour plus tard, vous pouvez soit éditer manuellement le fichier `.env`, soit le régénérer en lançant : > > **Bash :** > ```bash @@ -184,7 +184,7 @@ Get-Content ..\.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, etc. ## Exécuter l'application localement -**Vérifiez le déploiement :** +**Vérifier le déploiement :** Assurez-vous que le fichier `.env` existe à la racine avec les identifiants Azure. Exécutez ceci depuis le répertoire du module (`01-introduction/`) : @@ -200,21 +200,21 @@ Get-Content ..\.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYME **Démarrer les applications :** -**Option 1 : Utiliser le Spring Boot Dashboard (recommandé pour les utilisateurs de VS Code)** +**Option 1 : Utiliser Spring Boot Dashboard (recommandé pour les utilisateurs VS Code)** -Le conteneur de développement inclut l’extension Spring Boot Dashboard, qui fournit une interface visuelle pour gérer toutes les applications Spring Boot. Vous pouvez le trouver dans la barre d’activité à gauche de VS Code (recherchez l’icône Spring Boot). +Le conteneur de développement inclut l’extension Spring Boot Dashboard, qui fournit une interface visuelle pour gérer toutes les applications Spring Boot. Vous le trouverez dans la barre d’activités à gauche dans VS Code (cherchez l’icône Spring Boot). Depuis le Spring Boot Dashboard, vous pouvez : - Voir toutes les applications Spring Boot disponibles dans l’espace de travail -- Démarrer/arrêter les applications en un clic -- Voir les logs d’application en temps réel -- Surveiller l'état des applications +- Démarrer/arrêter les applications d’un simple clic +- Visualiser les logs des applications en temps réel +- Surveiller l’état des applications -Il suffit de cliquer sur le bouton play à côté de "introduction" pour démarrer ce module, ou de lancer tous les modules à la fois. +Cliquez simplement sur le bouton lecture à côté de « introduction » pour lancer ce module, ou démarrez tous les modules en une fois. Spring Boot Dashboard -*Le Spring Boot Dashboard dans VS Code — démarrez, arrêtez et surveillez tous les modules depuis un seul endroit* +*Le Spring Boot Dashboard dans VS Code — démarrer, arrêter et surveiller tous les modules depuis un seul endroit* **Option 2 : Utiliser des scripts shell** @@ -232,7 +232,7 @@ cd .. # Depuis le répertoire racine .\start-all.ps1 ``` -Ou démarrez juste ce module : +Ou démarrez seulement ce module : **Bash :** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Les deux scripts chargent automatiquement les variables d'environnement à partir du fichier `.env` à la racine et construiront les JARs s'ils n'existent pas. +Les deux scripts chargent automatiquement les variables d'environnement depuis le fichier `.env` à la racine et compileront les JAR si ceux-ci n’existent pas encore. -> **Note :** Si vous préférez construire manuellement tous les modules avant de démarrer : +> **Note :** Si vous préférez compiler tous les modules manuellement avant de démarrer : > > **Bash :** > ```bash @@ -268,55 +268,55 @@ Ouvrez http://localhost:8080 dans votre navigateur. **Bash :** ```bash -./stop.sh # Ce module uniquement +./stop.sh # Ce module seulement # Ou cd .. && ./stop-all.sh # Tous les modules ``` **PowerShell :** ```powershell -.\stop.ps1 # Ce module uniquement +.\stop.ps1 # Ce module seulement # Ou cd ..; .\stop-all.ps1 # Tous les modules ``` ## Utiliser l'application -L'application fournit une interface web avec deux implémentations de chat côte à côte. +L’application fournit une interface web avec deux implémentations de chat côte à côte. Application Home Screen -*Tableau de bord montrant à la fois Simple Chat (sans état) et Conversational Chat (avec état)* +*Tableau de bord montrant les options Chat Simple (sans état) et Chat Conversationnel (avec état)* -### Chat sans état (panneau de gauche) +### Chat sans état (panneau gauche) -Testez ceci en premier. Dites « Je m'appelle John » puis demandez immédiatement « Comment je m'appelle ? » Le modèle ne se souviendra pas car chaque message est indépendant. Cela démontre le problème central avec l’intégration basique des modèles de langage – absence de contexte de conversation. +Essayez d’abord celui-ci. Dites « Je m’appelle John » puis demandez immédiatement « Quel est mon nom ? » Le modèle ne s’en souviendra pas car chaque message est indépendant. Cela illustre le problème central de l’intégration simple du modèle de langue — aucun contexte de conversation. Stateless Chat Demo *L’IA ne se souvient pas de votre nom du message précédent* -### Conversation avec état (panneau de droite) +### Chat avec état (panneau droit) -Essayez maintenant la même séquence ici. Dites « Je m'appelle John » puis « Comment je m'appelle ? » Cette fois il s’en souvient. La différence est MessageWindowChatMemory – il maintient l’historique de la conversation et l’inclut dans chaque requête. C’est ainsi que fonctionne l’IA conversationnelle en production. +Essayez maintenant la même séquence ici. Dites « Je m’appelle John » puis « Quel est mon nom ? » Cette fois, elle s’en souvient. La différence vient de MessageWindowChatMemory – elle maintient l’historique de la conversation et l’inclut à chaque requête. C’est ainsi que fonctionne l’IA conversationnelle en production. Stateful Chat Demo -*L’IA se souvient de votre nom plus tôt dans la conversation* +*L’IA se souvient de votre nom depuis le début de la conversation* -Les deux panneaux utilisent le même modèle GPT-5.2. La seule différence est la mémoire. Cela montre clairement ce que la mémoire apporte à votre application et pourquoi elle est essentielle pour les cas d’utilisation réels. +Les deux panneaux utilisent le même modèle GPT-5.2. La seule différence est la mémoire. Cela montre clairement ce que la mémoire apporte à votre application et pourquoi elle est essentielle pour les cas d’usage réels. ## Étapes suivantes -**Module suivant :** [02-prompt-engineering - Création d'invites avec GPT-5.2](../02-prompt-engineering/README.md) +**Module suivant :** [02-prompt-engineering - Prompt Engineering avec GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigation :** [← Précédent : Module 00 - Démarrage rapide](../00-quick-start/README.md) | [Retour au principal](../README.md) | [Suivant : Module 02 - Création d'invites →](../02-prompt-engineering/README.md) +**Navigation :** [← Retour au principal](../README.md) | [Suivant : Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- -**Clause de non-responsabilité** : -Ce document a été traduit à l'aide du service de traduction automatisée [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçons d'assurer l'exactitude, veuillez noter que les traductions automatiques peuvent comporter des erreurs ou des inexactitudes. Le document original dans sa langue d'origine doit être considéré comme la source faisant autorité. Pour toute information critique, il est recommandé de faire appel à une traduction professionnelle réalisée par un humain. Nous ne saurions être tenus responsables des malentendus ou erreurs d'interprétation résultant de l'utilisation de cette traduction. +**Avertissement** : +Ce document a été traduit à l'aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçions d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue native doit être considéré comme la source faisant autorité. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous ne saurions être tenus responsables des malentendus ou erreurs d'interprétation découlant de l'utilisation de cette traduction. \ No newline at end of file diff --git a/translations/fr/02-prompt-engineering/README.md b/translations/fr/02-prompt-engineering/README.md index f76bfe742..a776b7e79 100644 --- a/translations/fr/02-prompt-engineering/README.md +++ b/translations/fr/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Module 02 : Ingénierie des prompts avec GPT-5.2 +# Module 02 : Ingénierie des invites avec GPT-5.2 ## Table des matières -- [Présentation vidéo](../../../02-prompt-engineering) -- [Ce que vous apprendrez](../../../02-prompt-engineering) -- [Prérequis](../../../02-prompt-engineering) -- [Comprendre l'ingénierie des prompts](../../../02-prompt-engineering) -- [Fondamentaux de l'ingénierie des prompts](../../../02-prompt-engineering) - - [Prompting Zero-Shot](../../../02-prompt-engineering) - - [Prompting Few-Shot](../../../02-prompt-engineering) - - [Chaîne de pensée](../../../02-prompt-engineering) - - [Prompting basé sur les rôles](../../../02-prompt-engineering) - - [Modèles de prompts](../../../02-prompt-engineering) -- [Schémas avancés](../../../02-prompt-engineering) -- [Exécuter l'application](../../../02-prompt-engineering) -- [Captures d'écran de l'application](../../../02-prompt-engineering) -- [Exploration des schémas](../../../02-prompt-engineering) - - [Faible vs Forte Empressement](../../../02-prompt-engineering) - - [Exécution de tâches (préambules d'outils)](../../../02-prompt-engineering) - - [Code auto-réfléchissant](../../../02-prompt-engineering) - - [Analyse structurée](../../../02-prompt-engineering) - - [Chat multi-tours](../../../02-prompt-engineering) - - [Raisonnement étape par étape](../../../02-prompt-engineering) - - [Sortie contrainte](../../../02-prompt-engineering) -- [Ce que vous apprenez vraiment](../../../02-prompt-engineering) -- [Étapes suivantes](../../../02-prompt-engineering) +- [Présentation vidéo](#présentation-vidéo) +- [Ce que vous allez apprendre](#ce-que-vous-allez-apprendre) +- [Prérequis](#prérequis) +- [Comprendre l'ingénierie des invites](#comprendre-lingénierie-des-invites) +- [Fondamentaux de l'ingénierie des invites](#fondamentaux-de-lingénierie-des-invites) + - [Invites zéro-coup](#invites-zéro-coup) + - [Invites à quelques exemples](#invites-à-quelques-exemples) + - [Chaîne de pensée](#chaîne-de-pensée) + - [Invites basées sur un rôle](#invites-basées-sur-un-rôle) + - [Modèles d'invites](#modèles-dinvites) +- [Modèles avancés](#modèles-avancés) +- [Exécuter l'application](#exécuter-l’application) +- [Captures d'écran de l'application](#captures-d’écran-de-l’application) +- [Explorer les modèles](#exploration-des-motifs) + - [Faible vs forte motivation](#faible-vs-forte-implication) + - [Exécution des tâches (préambules d’outils)](#exécution-de-tâches-préambules-d’outil) + - [Code auto-réfléchi](#code-auto-réfléchi) + - [Analyse structurée](#analyse-structurée) + - [Chat multi-interactions](#chat-multi-tour) + - [Raisonnement étape par étape](#raisonnement-étape-par-étape) + - [Sortie contrainte](#sortie-contraint) +- [Ce que vous apprenez réellement](#ce-que-vous-apprenez-vraiment) +- [Étapes suivantes](#étapes-suivantes) ## Présentation vidéo Regardez cette session en direct qui explique comment démarrer avec ce module : -Ingénierie des prompts avec LangChain4j - Session en direct +Ingénierie des invites avec LangChain4j - Session en direct -## Ce que vous apprendrez +## Ce que vous allez apprendre -Le diagramme suivant donne un aperçu des sujets clés et des compétences que vous développerez dans ce module — des techniques de raffinage des prompts au workflow étape par étape que vous suivrez. +Le diagramme suivant offre un aperçu des thèmes clés et des compétences que vous développerez dans ce module — des techniques de raffinement d’invites au flux de travail étape par étape que vous suivrez. -Ce que vous apprendrez +Ce que vous allez apprendre -Dans les modules précédents, vous avez exploré les interactions basiques de LangChain4j avec les modèles GitHub et vu comment la mémoire permet l'IA conversationnelle avec Azure OpenAI. Nous allons maintenant nous concentrer sur la manière dont vous posez des questions — les prompts eux-mêmes — en utilisant GPT-5.2 d'Azure OpenAI. La façon dont vous structurez vos prompts influence considérablement la qualité des réponses. Nous commençons par une revue des techniques fondamentales de prompting, puis passons à huit schémas avancés qui exploitent pleinement les capacités de GPT-5.2. +Dans le module précédent, vous avez vu comment la mémoire permet l’IA conversationnelle avec Azure OpenAI. Maintenant, nous allons nous concentrer sur la façon dont vous posez les questions — les invites elles-mêmes — en utilisant GPT-5.2 d’Azure OpenAI. La manière dont vous structurez vos invites influence fortement la qualité des réponses obtenues. Nous commençons par une revue des techniques fondamentales d’invite, puis passons à huit modèles avancés qui tirent pleinement parti des capacités de GPT-5.2. -Nous utiliserons GPT-5.2 car il introduit le contrôle du raisonnement — vous pouvez indiquer au modèle combien de réflexion effectuer avant de répondre. Cela rend les différentes stratégies de prompting plus apparentes et vous aide à comprendre quand utiliser chaque approche. Nous profiterons également des limites de taux plus souples d'Azure pour GPT-5.2 par rapport aux modèles GitHub. +Nous utilisons GPT-5.2 car il introduit un contrôle du raisonnement — vous pouvez indiquer au modèle combien de réflexion effectuer avant de répondre. Cela rend les différentes stratégies d’invite plus évidentes et vous aide à comprendre quand utiliser chaque approche. ## Prérequis -- Module 01 complété (ressources Azure OpenAI déployées) -- Fichier `.env` dans le répertoire racine avec les identifiants Azure (créé par `azd up` dans le Module 01) +- Module 01 terminé (ressources Azure OpenAI déployées) +- Fichier `.env` à la racine avec les identifiants Azure (créé par `azd up` dans le Module 01) -> **Note :** Si vous n'avez pas terminé le Module 01, suivez d'abord les instructions de déploiement là-bas. +> **Note :** Si vous n’avez pas terminé le Module 01, suivez d’abord les instructions de déploiement indiquées là-bas. -## Comprendre l'ingénierie des prompts +## Comprendre l'ingénierie des invites -Fondamentalement, l'ingénierie des prompts est la différence entre des consignes vagues et précises, comme l'illustre la comparaison ci-dessous. +Fondamentalement, l’ingénierie des invites est ce qui différencie des instructions vagues d’instructions précises, comme l’illustre la comparaison ci-dessous. -Qu'est-ce que l'ingénierie des prompts ? +Qu’est-ce que l’ingénierie des invites ? -L'ingénierie des prompts consiste à concevoir un texte d'entrée qui vous donne systématiquement les résultats dont vous avez besoin. Il ne s'agit pas seulement de poser des questions — il s'agit de structurer les requêtes pour que le modèle comprenne exactement ce que vous voulez et comment le fournir. +L’ingénierie des invites consiste à concevoir un texte d’entrée qui vous donne systématiquement les résultats souhaités. Ce n’est pas seulement poser des questions — c’est structurer les requêtes pour que le modèle comprenne exactement ce que vous voulez et comment le fournir. -Pensez-y comme donner des instructions à un collègue. « Corrige le bug » est vague. « Corrige l'exception de pointeur nul dans UserService.java ligne 45 en ajoutant une vérification de null » est précis. Les modèles de langage fonctionnent de la même manière — la précision et la structure comptent. +Pensez-y comme donner des instructions à un collègue. "Corrige le bug" est vague. "Corrige l’exception de pointeur nul dans UserService.java ligne 45 en ajoutant une vérification de null" est précis. Les modèles linguistiques fonctionnent de la même manière — la précision et la structure comptent. -Le diagramme ci-dessous montre comment LangChain4j s'intègre dans ce schéma — connectant vos modèles de prompt au modèle via les blocs `SystemMessage` et `UserMessage`. +Le diagramme ci-dessous montre comment LangChain4j s’intègre dans ce cadre — en connectant vos modèles d’invites au modèle via les blocs `SystemMessage` et `UserMessage`. -Comment LangChain4j s'intègre +Comment LangChain4j s’intègre -LangChain4j fournit l'infrastructure — connexions aux modèles, mémoire et types de messages — tandis que les schémas de prompt sont simplement du texte structuré que vous envoyez à travers cette infrastructure. Les blocs de construction clés sont `SystemMessage` (qui définit le comportement et le rôle de l'IA) et `UserMessage` (qui porte votre demande réelle). +LangChain4j fournit l’infrastructure — connexions au modèle, mémoire et types de messages — tandis que les modèles d’invites ne sont que des textes soigneusement structurés que vous envoyez via cette infrastructure. Les éléments clés sont `SystemMessage` (qui définit le comportement et le rôle de l’IA) et `UserMessage` (qui contient votre requête réelle). -## Fondamentaux de l'ingénierie des prompts +## Fondamentaux de l'ingénierie des invites -Les cinq techniques principales montrées ci-dessous forment la base d'une ingénierie des prompts efficace. Chacune aborde un aspect différent de la façon dont vous communiquez avec les modèles de langage. +Les cinq techniques principales ci-dessous forment la base d’une ingénierie des invites efficace. Chacune couvre un aspect différent de la communication avec les modèles linguistiques. -Vue d'ensemble des cinq schémas d'ingénierie des prompts +Vue d’ensemble des cinq modèles d’ingénierie des invites -Avant de plonger dans les schémas avancés de ce module, revoyons cinq techniques fondamentales de prompting. Ce sont les blocs de construction que tout ingénieur en prompts devrait connaître. Si vous avez déjà travaillé le [module de démarrage rapide](../00-quick-start/README.md#2-prompt-patterns), vous les avez vus en action — voici le cadre conceptuel derrière eux. +Avant d’aborder les modèles avancés de ce module, passons en revue cinq techniques fondamentales d’invite. Ce sont les blocs de construction que tout ingénieur d’invites doit connaître. -### Prompting Zero-Shot +### Invites zéro-coup -L'approche la plus simple : donnez au modèle une instruction directe sans exemples. Le modèle s'appuie entièrement sur son entraînement pour comprendre et exécuter la tâche. Cela fonctionne bien pour des demandes simples où le comportement attendu est évident. +L’approche la plus simple : donner une instruction directe au modèle sans exemples. Le modèle s’appuie entièrement sur son entraînement pour comprendre et exécuter la tâche. Cela fonctionne bien pour des requêtes simples où le comportement attendu est évident. -Prompting Zero-Shot +Invites zéro-coup -*Instruction directe sans exemples — le modèle déduit la tâche à partir de l'instruction seule* +*Instruction directe sans exemples — le modèle infère la tâche à partir de l’instruction seule* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// Réponse : "Positif" +// Réponse : « Positive » ``` -**Quand utiliser :** classifications simples, questions directes, traductions, ou toute tâche que le modèle peut gérer sans orientation supplémentaire. +**Quand utiliser :** Classifications simples, questions directes, traductions ou toute tâche que le modèle peut gérer sans guidance supplémentaire. -### Prompting Few-Shot +### Invites à quelques exemples -Fournissez des exemples qui montrent le modèle le schéma que vous voulez qu’il suive. Le modèle apprend le format entrée-sortie attendu à partir de vos exemples et l'applique aux nouvelles entrées. Cela améliore considérablement la cohérence pour des tâches où le format ou le comportement désiré n'est pas évident. +Fournissez des exemples qui montrent le modèle le modèle à suivre. Le modèle apprend le format attendu entrée-sortie à partir de vos exemples et l’applique aux nouvelles entrées. Cela améliore considérablement la cohérence pour les tâches où le format ou le comportement souhaité n’est pas évident. -Prompting Few-Shot +Invites à quelques exemples -*Apprentissage par exemples — le modèle identifie le schéma et l'applique aux nouvelles entrées* +*Apprentissage par exemples — le modèle identifie le modèle et l’applique à de nouvelles entrées* ```java String prompt = """ @@ -112,11 +112,11 @@ String prompt = """ String response = model.chat(prompt); ``` -**Quand utiliser :** classifications personnalisées, formatage cohérent, tâches spécifiques à un domaine, ou lorsque les résultats zero-shot sont incohérents. +**Quand utiliser :** Classifications personnalisées, formatage cohérent, tâches spécifiques au domaine, ou quand les résultats zéro-coup sont incohérents. ### Chaîne de pensée -Demandez au modèle de montrer son raisonnement étape par étape. Au lieu de sauter directement à une réponse, le modèle décompose le problème et travaille chaque partie explicitement. Cela améliore la précision pour les mathématiques, la logique et les raisonnements multi-étapes. +Demandez au modèle de montrer son raisonnement étape par étape. Au lieu de passer directement à une réponse, le modèle décompose le problème et traite chaque partie explicitement. Cela améliore la précision sur les tâches de mathématiques, logique et raisonnement en plusieurs étapes. Chaîne de pensée @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Le modèle montre : 15 - 8 = 7, puis 7 + 12 = 19 pommes ``` -**Quand utiliser :** problèmes mathématiques, énigmes logiques, débogage, ou toute tâche où montrer le raisonnement améliore l'exactitude et la confiance. +**Quand utiliser :** Problèmes mathématiques, casse-tête logiques, débogage, ou toute tâche où montrer le processus de raisonnement améliore la précision et la confiance. -### Prompting basé sur les rôles +### Invites basées sur un rôle -Définissez une persona ou un rôle pour l'IA avant de poser votre question. Cela fournit un contexte qui façonne le ton, la profondeur et le focus de la réponse. Un « architecte logiciel » donne des conseils différents d'un « développeur junior » ou d'un « auditeur sécurité ». +Attribuez un personnage ou un rôle à l’IA avant de poser votre question. Cela fournit un contexte qui façonne le ton, la profondeur et le focus de la réponse. Un « architecte logiciel » donne des conseils différents d’un « développeur junior » ou d’un « auditeur sécurité ». -Prompting basé sur les rôles +Invites basées sur un rôle -*Définir le contexte et la persona — la même question reçoit une réponse différente selon le rôle assigné* +*Définition du contexte et du personnage — une même question reçoit une réponse différente selon le rôle assigné* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Quand utiliser :** revues de code, tutorat, analyses spécifiques à un domaine, ou lorsque vous avez besoin de réponses adaptées à un niveau d’expertise ou une perspective particulière. +**Quand utiliser :** Revue de code, tutorat, analyse spécifique au domaine, ou quand vous avez besoin de réponses adaptées à un niveau d’expertise ou perspective particulière. -### Modèles de prompts +### Modèles d'invites -Créez des prompts réutilisables avec des espaces réservés variables. Au lieu d'écrire un nouveau prompt à chaque fois, définissez un modèle une fois et remplissez-le avec différentes valeurs. La classe `PromptTemplate` de LangChain4j rend cela simple avec la syntaxe `{{variable}}`. +Créez des invites réutilisables avec des espaces réservés variables. Au lieu d’écrire une nouvelle invite à chaque fois, définissez un modèle une fois et remplissez-le avec différentes valeurs. La classe `PromptTemplate` de LangChain4j facilite cela avec la syntaxe `{{variable}}`. -Modèles de prompts +Modèles d'invites -*Prompts réutilisables avec espaces réservés variables — un modèle, de nombreuses utilisations* +*Invites réutilisables avec espaces réservés variables — un modèle, de nombreuses utilisations* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Quand utiliser :** requêtes répétées avec différentes entrées, traitement par lots, création de workflows IA réutilisables, ou tout scénario où la structure du prompt reste la même mais les données changent. +**Quand utiliser :** Requêtes répétées avec différentes entrées, traitement par lots, construction de flux de travail IA réutilisables, ou tout scénario où la structure d’invite reste la même mais les données changent. --- -Ces cinq fondamentaux vous donnent un solide kit d’outils pour la plupart des tâches de prompting. Le reste de ce module s’appuie dessus avec **huit schémas avancés** qui tirent parti du contrôle du raisonnement, de l'auto-évaluation et des capacités de sortie structurée de GPT-5.2. +Ces cinq fondamentaux vous donnent une boîte à outils solide pour la plupart des tâches d’invite. Le reste de ce module s’appuie dessus avec **huit modèles avancés** qui exploitent le contrôle du raisonnement, l’auto-évaluation et les capacités de sortie structurée de GPT-5.2. -## Schémas avancés +## Modèles avancés -Avec les fondamentaux couverts, passons aux huit schémas avancés qui rendent ce module unique. Tous les problèmes n’ont pas besoin de la même approche. Certaines questions demandent des réponses rapides, d’autres une réflexion profonde. Certaines ont besoin d'un raisonnement visible, d’autres seulement des résultats. Chaque schéma ci-dessous est optimisé pour un scénario différent — et le contrôle du raisonnement de GPT-5.2 rend les différences encore plus marquées. +Avec les fondamentaux couverts, passons aux huit modèles avancés qui rendent ce module unique. Tous les problèmes ne nécessitent pas la même approche. Certaines questions requièrent des réponses rapides, d’autres une réflexion approfondie. Certaines ont besoin d’un raisonnement visible, d’autres seulement des résultats. Chaque modèle ci-dessous est optimisé pour un scénario différent — et le contrôle du raisonnement de GPT-5.2 accentue encore ces différences. -Huit schémas de prompting +Huit modèles d’ingénierie d’invites -*Vue d'ensemble des huit schémas d'ingénierie des prompts et leurs cas d'usage* +*Vue d’ensemble des huit modèles d’ingénierie des invites et leurs cas d’utilisation* -GPT-5.2 ajoute une autre dimension à ces schémas : *le contrôle du raisonnement*. Le curseur ci-dessous montre comment vous pouvez ajuster l’effort de réflexion du modèle — depuis des réponses rapides et directes jusqu’à une analyse profonde et minutieuse. +GPT-5.2 ajoute une dimension supplémentaire à ces modèles : *le contrôle du raisonnement*. Le curseur ci-dessous montre comment vous pouvez ajuster l’effort de réflexion du modèle — de réponses rapides et directes à une analyse profonde et minutieuse. Contrôle du raisonnement avec GPT-5.2 -*Le contrôle du raisonnement de GPT-5.2 vous permet de spécifier combien de réflexion le modèle doit faire — des réponses rapides aux explorations approfondies* +*Le contrôle du raisonnement de GPT-5.2 vous permet de spécifier combien de réflexion le modèle doit effectuer — des réponses rapides et directes à une exploration approfondie* -**Faible empressement (Rapide & ciblé)** - Pour des questions simples où vous voulez des réponses rapides et directes. Le modèle fait un raisonnement minimal - maximum 2 étapes. Utilisez cela pour des calculs, recherches, ou questions simples. +**Faible motivation (Rapide & ciblé)** – Pour les questions simples où vous souhaitez des réponses rapides et directes. Le modèle fait un minimum de raisonnement — maximum 2 étapes. Utilisez ceci pour des calculs, des consultations ou des questions simples. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Explorez avec GitHub Copilot :** Ouvrez [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) et demandez : -> - « Quelle est la différence entre les schémas de faible et fort empressement en prompting ? » -> - « Comment les balises XML dans les prompts aident-elles à structurer la réponse de l’IA ? » -> - « Quand devrais-je utiliser les schémas d'auto-réflexion vs l'instruction directe ? » +> - « Quelle est la différence entre les modèles d’invite à faible et haute motivation ? » +> - « Comment les balises XML dans les invites aident-elles à structurer la réponse de l’IA ? » +> - « Quand dois-je utiliser les modèles d’auto-réflexion vs l’instruction directe ? » -**Fort empressement (Profond & minutieux)** - Pour des problèmes complexes où vous voulez une analyse complète. Le modèle explore en profondeur et montre un raisonnement détaillé. Utilisez cela pour la conception de systèmes, décisions d’architecture, ou recherches complexes. +**Haute motivation (Profond & minutieux)** – Pour les problèmes complexes où vous souhaitez une analyse complète. Le modèle explore en profondeur et montre un raisonnement détaillé. Utilisez ceci pour la conception système, les décisions d’architecture ou la recherche complexe. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Exécution de tâches (progrès étape par étape)** - Pour des workflows multi-étapes. Le modèle fournit un plan initial, décrit chaque étape au fur et à mesure, puis donne un résumé. Utilisez cela pour des migrations, implémentations, ou tout processus multi-étapes. +**Exécution des tâches (Progression étape par étape)** – Pour les flux de travail en plusieurs étapes. Le modèle fournit un plan initial, raconte chaque étape pendant qu’il travaille, puis donne un résumé. Utilisez ceci pour les migrations, les implémentations ou tout processus en plusieurs étapes. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Le prompting en chaîne de pensée demande explicitement au modèle de montrer son raisonnement, améliorant la précision pour les tâches complexes. La décomposition étape par étape aide à la compréhension aussi bien pour les humains que pour l’IA. +L’invite chaîne de pensée demande explicitement au modèle de montrer son raisonnement, améliorant ainsi la précision sur les tâches complexes. La décomposition étape par étape aide aussi bien les humains que l’IA à comprendre la logique. -> **🤖 Essayez avec le chat [GitHub Copilot](https://github.com/features/copilot) :** Posez des questions sur ce schéma : -> - « Comment adapter le schéma d'exécution de tâches pour des opérations longues ? » -> - « Quelles sont les bonnes pratiques pour structurer les préambules d’outils dans les applications de production ? » -> - « Comment capturer et afficher les mises à jour de progrès intermédiaires dans une interface utilisateur ? » +> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Posez des questions sur ce modèle : +> - « Comment adapterais-je le modèle d’exécution des tâches pour les opérations de longue durée ? » +> - « Quelles sont les bonnes pratiques pour structurer les préambules d’outils dans des applications en production ? » +> - « Comment capturer et afficher les mises à jour de progression intermédiaires dans une interface utilisateur ? » -Le diagramme ci-dessous illustre ce workflow Plan → Exécution → Résumé. +Le schéma ci-dessous illustre ce flux Planifier → Exécuter → Résumer. -Schéma d'exécution de tâches +Modèle d’exécution des tâches -*Workflow Plan → Exécution → Résumé pour les tâches multi-étapes* +*Flux Planifier → Exécuter → Résumer pour les tâches en plusieurs étapes* -**Code auto-réfléchissant** - Pour générer du code de qualité production. Le modèle génère du code en suivant les standards de production avec une gestion appropriée des erreurs. Utilisez cela lors de la création de nouvelles fonctionnalités ou services. +**Code auto-réfléchi** – Pour générer du code de qualité production. Le modèle génère du code suivant les standards de production avec une gestion adéquate des erreurs. Utilisez ceci lors de la création de nouvelles fonctionnalités ou services. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Le diagramme ci-dessous montre cette boucle d'amélioration itérative — générer, évaluer, identifier les faiblesses, et affiner jusqu'à ce que le code respecte les standards de production. +Le diagramme ci-dessous montre cette boucle d’amélioration itérative — générer, évaluer, identifier les faiblesses, affiner jusqu’à ce que le code réponde aux standards de production. -Cycle d'auto-réflexion +Cycle d’auto-réflexion -*Boucle d'amélioration itérative - générer, évaluer, identifier les problèmes, améliorer, répéter* +*Boucle d’amélioration itérative - générer, évaluer, identifier les problèmes, améliorer, répéter* -**Analyse structurée** - Pour une évaluation cohérente. Le modèle révise le code avec un cadre fixe (exactitude, pratiques, performance, sécurité, maintenabilité). Utilisez cela pour des revues de code ou évaluations qualité. +**Analyse structurée** – Pour une évaluation cohérente. Le modèle passe en revue le code selon un cadre fixe (exactitude, bonnes pratiques, performance, sécurité, maintenabilité). Utilisez ceci pour les revues de code ou évaluations qualité. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Essayez avec le chat [GitHub Copilot](https://github.com/features/copilot) :** Posez des questions sur l’analyse structurée : +> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Posez des questions sur l’analyse structurée : > - « Comment personnaliser le cadre d’analyse pour différents types de revues de code ? » -> - « Quelle est la meilleure façon de parser et d’agir sur une sortie structurée de manière programmatique ? » -> - « Comment assurer une cohérence des niveaux de gravité à travers différentes sessions de revue ? » +> - « Quelle est la meilleure méthode pour analyser et agir sur une sortie structurée de manière programmatique ? » +> - « Comment garantir des niveaux de gravité cohérents à travers différentes sessions de revue ? » Le diagramme suivant montre comment ce cadre structuré organise une revue de code en catégories cohérentes avec des niveaux de gravité. -Schéma d'analyse structurée +Modèle d’analyse structurée *Cadre pour des revues de code cohérentes avec niveaux de gravité* -**Chat multi-tours** - Pour des conversations nécessitant du contexte. Le modèle se souvient des messages précédents et construit dessus. Utilisez cela pour des sessions d’aide interactives ou Q&A complexes. +**Chat multi-interactions** – Pour les conversations qui ont besoin de contexte. Le modèle se souvient des messages précédents et s’appuie dessus. Utilisez ceci pour des sessions d’aide interactives ou des questions-réponses complexes. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Le diagramme ci-dessous visualise comment le contexte de conversation s'accumule à chaque tour et comment il se rapporte à la limite de tokens du modèle. +Le diagramme ci-dessous visualise comment le contexte d’une conversation s’accumule à chaque tour et comment cela se rapporte à la limite de tokens du modèle. -Mémoire du contexte +Mémoire de contexte -*Comment le contexte de la conversation s'accumule sur plusieurs tours jusqu'à atteindre la limite de tokens* -**Raisonnement étape par étape** - Pour les problèmes nécessitant une logique visible. Le modèle montre un raisonnement explicite pour chaque étape. Utilisez ceci pour les problèmes de mathématiques, les puzzles logiques ou lorsque vous devez comprendre le processus de réflexion. +*Comment le contexte de la conversation s’accumule sur plusieurs échanges jusqu’à atteindre la limite de tokens* + +**Raisonnement étape par étape** – Pour les problèmes nécessitant une logique visible. Le modèle montre un raisonnement explicite à chaque étape. Utilisez ceci pour les problèmes mathématiques, puzzles logiques, ou quand vous devez comprendre le processus de réflexion. ```java String prompt = """ @@ -400,11 +401,10 @@ String response = chatModel.chat(prompt); Le diagramme ci-dessous illustre comment le modèle décompose les problèmes en étapes logiques explicites et numérotées. -Motif étape par étape - +Modèle étape par étape *Décomposer les problèmes en étapes logiques explicites* -**Sortie contrainte** - Pour les réponses avec des exigences spécifiques de format. Le modèle suit strictement les règles de format et de longueur. Utilisez ceci pour les résumés ou lorsque vous avez besoin d’une structure de sortie précise. +**Sortie contraint** - Pour les réponses avec des exigences spécifiques de format. Le modèle suit strictement les règles de format et de longueur. Utilisez ceci pour des résumés ou lorsque vous avez besoin d’une structure de sortie précise. ```java String prompt = """ @@ -424,13 +424,13 @@ Le diagramme suivant montre comment les contraintes guident le modèle pour prod Motif de sortie contrainte -*Application spécifique des exigences de format, longueur et structure* +*Application des exigences spécifiques de format, longueur et structure* -## Exécuter l'application +## Exécuter l’application **Vérifier le déploiement :** -Assurez-vous que le fichier `.env` existe dans le répertoire racine avec les identifiants Azure (créés lors du module 01). Exécutez ceci depuis le répertoire du module (`02-prompt-engineering/`) : +Assurez-vous que le fichier `.env` existe à la racine avec les identifiants Azure (créés pendant le Module 01). Lancez ceci depuis le répertoire du module (`02-prompt-engineering/`) : **Bash :** ```bash @@ -442,27 +442,27 @@ cat ../.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Démarrer l'application :** +**Démarrer l’application :** -> **Note :** Si vous avez déjà démarré toutes les applications en utilisant `./start-all.sh` depuis le répertoire racine (comme décrit dans le module 01), ce module fonctionne déjà sur le port 8083. Vous pouvez ignorer les commandes de démarrage ci-dessous et aller directement à http://localhost:8083. +> **Note :** Si vous avez déjà démarré toutes les applications avec `./start-all.sh` depuis la racine (comme décrit dans le Module 01), ce module est déjà en cours d’exécution sur le port 8083. Vous pouvez ignorer les commandes de démarrage ci-dessous et accéder directement à http://localhost:8083. -**Option 1 : Utiliser le Spring Boot Dashboard (recommandé pour les utilisateurs de VS Code)** +**Option 1 : Utilisation du Spring Boot Dashboard (recommandé pour les utilisateurs de VS Code)** -Le conteneur de développement inclut l’extension Spring Boot Dashboard, qui offre une interface visuelle pour gérer toutes les applications Spring Boot. Vous pouvez le trouver dans la barre d’activités à gauche dans VS Code (cherchez l’icône Spring Boot). +Le conteneur dev inclut l’extension Spring Boot Dashboard, qui fournit une interface visuelle pour gérer toutes les applications Spring Boot. Vous pouvez la trouver dans la barre d’activité à gauche de VS Code (cherchez l’icône Spring Boot). Depuis le Spring Boot Dashboard, vous pouvez : - Voir toutes les applications Spring Boot disponibles dans l’espace de travail -- Démarrer/arrêter les applications en un clic -- Visualiser les logs des applications en temps réel -- Surveiller le statut des applications +- Démarrer/arrêter les applications d’un simple clic +- Consulter les journaux des applications en temps réel +- Surveiller l’état des applications -Cliquez simplement sur le bouton lecture à côté de "prompt-engineering" pour démarrer ce module, ou démarrez tous les modules en une seule fois. +Cliquez simplement sur le bouton de lecture à côté de "prompt-engineering" pour démarrer ce module, ou démarrez tous les modules d’un coup. -Tableau de bord Spring Boot +Spring Boot Dashboard *Le Spring Boot Dashboard dans VS Code — démarrer, arrêter et surveiller tous les modules depuis un seul endroit* -**Option 2 : Utiliser des scripts shell** +**Option 2 : Utilisation des scripts shell** Démarrer toutes les applications web (modules 01-04) : @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Les deux scripts chargent automatiquement les variables d’environnement depuis le fichier `.env` racine et construiront les JAR si ils n’existent pas. +Les deux scripts chargent automatiquement les variables d’environnement depuis le fichier `.env` à la racine et construiront les JARs s’ils n’existent pas. -> **Note :** Si vous préférez construire tous les modules manuellement avant de démarrer : +> **Note :** Si vous préférez construire tous les modules manuellement avant de lancer : > > **Bash :** > ```bash @@ -514,7 +514,7 @@ Ouvrez http://localhost:8083 dans votre navigateur. **Bash :** ```bash -./stop.sh # Seulement ce module +./stop.sh # Ce module uniquement # Ou cd .. && ./stop-all.sh # Tous les modules ``` @@ -528,81 +528,81 @@ cd ..; .\stop-all.ps1 # Tous les modules ## Captures d’écran de l’application -Voici l’interface principale du module de prompt engineering, où vous pouvez expérimenter les huit motifs côte à côte. +Voici l’interface principale du module d’ingénierie des prompts, où vous pouvez expérimenter avec les huit motifs côte à côte. -Accueil du tableau de bord +Page d’accueil du tableau de bord -*Le tableau de bord principal montrant les 8 motifs de prompt engineering avec leurs caractéristiques et cas d’usage* +*Le tableau de bord principal affichant les 8 motifs d’ingénierie des prompts avec leurs caractéristiques et cas d’utilisation* -## Explorer les motifs +## Exploration des motifs -L’interface web vous permet d’expérimenter différentes stratégies de prompting. Chaque motif résout des problèmes différents — essayez-les pour voir quand chaque approche est pertinente. +L’interface web vous permet d’expérimenter différentes stratégies de prompt. Chaque motif résout des problèmes différents – essayez-les pour voir quand chaque approche brille. -> **Note : Streaming vs Non-Streaming** — Chaque page de motif offre deux boutons : **🔴 Diffuser la réponse (Live)** et une option **Non-streaming**. Le streaming utilise les Server-Sent Events (SSE) pour afficher les tokens en temps réel au fur et à mesure que le modèle les génère, vous voyez donc le progrès immédiatement. L’option non-streaming attend la réponse complète avant de l’afficher. Pour les prompts qui déclenchent un raisonnement approfondi (ex : Grande Implication, Code Auto-réflexif), l’appel non-streaming peut prendre très longtemps — parfois des minutes — sans retour visible. **Utilisez le streaming lors de l’expérimentation de prompts complexes** pour voir le modèle travailler et éviter l’impression que la requête a expiré. +> **Note : Streaming vs Non-Streaming** — Chaque page de motif offre deux boutons : **🔴 Diffuser la réponse (en direct)** et une option **Non-diffusion**. Le streaming utilise les Server-Sent Events (SSE) pour afficher les tokens en temps réel pendant que le modèle les génère, vous voyez donc la progression immédiatement. L’option non-diffusion attend la réponse complète avant de l’afficher. Pour les prompts qui déclenchent un raisonnement approfondi (ex. : Forte Implication, Code Auto-Réfléchi), l’appel non-diffusion peut prendre très longtemps – parfois des minutes – sans aucun retour visible. **Utilisez le streaming pour expérimenter avec des prompts complexes** afin de voir le modèle travailler et éviter l’impression que la requête a expiré. > -> **Note : Navigateur requis** — La fonction de streaming utilise l’API Fetch Streams (`response.body.getReader()`) qui nécessite un navigateur complet (Chrome, Edge, Firefox, Safari). Elle ne fonctionne **pas** dans le Simple Browser intégré de VS Code, car sa webview ne supporte pas l’API ReadableStream. Si vous utilisez le Simple Browser, les boutons non-streaming fonctionneront toujours normalement — seuls les boutons de streaming sont impactés. Ouvrez `http://localhost:8083` dans un navigateur externe pour une expérience complète. +> **Note : Exigence du navigateur** — La fonctionnalité de streaming utilise l’API Fetch Streams (`response.body.getReader()`) qui nécessite un navigateur complet (Chrome, Edge, Firefox, Safari). Elle **ne fonctionne pas** dans le navigateur Simple intégré de VS Code, car sa webview ne supporte pas l’API ReadableStream. Si vous utilisez le Simple Browser, les boutons non-diffusion fonctionneront normalement – seul le streaming est affecté. Ouvrez `http://localhost:8083` dans un navigateur externe pour une expérience complète. -### Faible vs Grande Implication +### Faible vs Forte Implication -Posez une question simple comme « Quel est 15 % de 200 ? » en mode Faible Implication. Vous obtenez une réponse instantanée et directe. Maintenant posez quelque chose de complexe comme « Concevez une stratégie de mise en cache pour une API à fort trafic » en mode Grande Implication. Cliquez sur **🔴 Diffuser la réponse (Live)** et regardez le raisonnement détaillé du modèle apparaître token après token. Même modèle, même structure de question — mais le prompt indique combien de réflexion faire. +Posez une question simple comme « Quel est 15 % de 200 ? » avec Faible Implication. Vous obtenez une réponse instantanée et directe. Maintenant posez quelque chose de complexe comme « Concevez une stratégie de cache pour une API à fort trafic » avec Forte Implication. Cliquez sur **🔴 Diffuser la réponse (en direct)** et regardez le raisonnement détaillé du modèle apparaître token par token. Même modèle, même structure de question – mais le prompt indique combien de réflexion effectuer. -### Exécution de tâches (Preambles Outils) +### Exécution de tâches (Préambules d’outil) -Les workflows en plusieurs étapes bénéficient d’une planification préalable et d’une narration des progrès. Le modèle décrit ce qu’il va faire, raconte chaque étape, puis résume les résultats. +Les workflows à étapes multiples bénéficient d’une planification préalable et d’une narration des progrès. Le modèle décrit ce qu’il va faire, narre chaque étape, puis résume les résultats. -### Code Auto-réflexif +### Code Auto-Réfléchi -Essayez « Crée un service de validation d’email ». Au lieu de simplement générer du code puis s’arrêter, le modèle génère, évalue selon des critères de qualité, identifie les faiblesses, puis améliore. Vous le voyez itérer jusqu’à ce que le code respecte les standards de production. +Essayez « Créez un service de validation d’email ». Au lieu de simplement générer du code et s’arrêter, le modèle génère, évalue selon des critères de qualité, identifie des faiblesses et améliore. Vous le verrez itérer jusqu’à ce que le code atteigne les standards de production. -### Analyse structurée +### Analyse Structurée -Les revues de code nécessitent des cadres d’évaluation cohérents. Le modèle analyse le code avec des catégories fixes (correction, bonnes pratiques, performance, sécurité) avec des niveaux de gravité. +Les revues de code nécessitent des cadres d’évaluation cohérents. Le modèle analyse le code en utilisant des catégories fixes (exactitude, pratiques, performance, sécurité) avec des niveaux de gravité. -### Chat multi-tours +### Chat Multi-Tour -Demandez « Qu’est-ce que Spring Boot ? » puis enchaînez immédiatement avec « Montre-moi un exemple ». Le modèle se souvient de votre première question et vous donne un exemple précis de Spring Boot. Sans mémoire, cette deuxième question serait trop vague. +Demandez « Qu’est-ce que Spring Boot ? » puis immédiatement « Montre-moi un exemple ». Le modèle se souvient de votre première question et vous donne un exemple Spring Boot spécifique. Sans mémoire, cette deuxième question serait trop vague. -### Raisonnement étape par étape +### Raisonnement Étape par Étape -Choisissez un problème mathématique et essayez-le à la fois avec Raisonnement étape par étape et Faible Implication. Faible implication vous donne juste la réponse — rapide mais opaque. Le raisonnement étape par étape vous montre chaque calcul et décision. +Choisissez un problème de math et essayez-le avec Raisonnement Étape par Étape et Faible Implication. La faible implication vous donne juste la réponse – rapide mais opaque. L’étape par étape vous montre chaque calcul et décision. -### Sortie contrainte +### Sortie Contraint -Quand vous avez besoin de formats spécifiques ou de nombres de mots précis, ce motif impose un respect strict. Essayez de générer un résumé avec exactement 100 mots au format liste à puces. +Quand vous avez besoin de formats spécifiques ou de comptes précis de mots, ce motif impose un respect strict. Essayez de générer un résumé avec exactement 100 mots en format liste à puces. ## Ce que vous apprenez vraiment **L’effort de raisonnement change tout** -GPT-5.2 vous permet de contrôler l’effort de calcul via vos prompts. Un faible effort signifie des réponses rapides avec peu d’exploration. Un effort élevé signifie que le modèle prend le temps de réfléchir profondément. Vous apprenez à adapter l’effort à la complexité de la tâche — ne perdez pas de temps sur des questions simples, mais ne précipitez pas les décisions complexes non plus. +GPT-5.2 vous permet de contrôler l’effort computationnel via vos prompts. Un faible effort signifie des réponses rapides avec exploration minimale. Un effort élevé signifie que le modèle prend le temps de réfléchir profondément. Vous apprenez à adapter l’effort à la complexité de la tâche – ne perdez pas de temps sur des questions simples, mais ne précipitez pas non plus les décisions complexes. **La structure guide le comportement** -Vous remarquez les balises XML dans les prompts ? Elles ne sont pas décoratives. Les modèles suivent des instructions structurées plus fiablement que du texte libre. Quand vous avez besoin de processus multi-étapes ou de logique complexe, la structure aide le modèle à savoir où il en est et ce qui vient après. Le diagramme ci-dessous décompose un prompt bien structuré, montrant comment les balises comme ``, ``, ``, `` et `` organisent vos instructions en sections claires. +Vous avez remarqué les balises XML dans les prompts ? Elles ne sont pas décoratives. Les modèles suivent les instructions structurées de façon plus fiable que du texte libre. Quand vous avez besoin de processus multi-étapes ou de logiques complexes, la structure aide le modèle à suivre où il en est et ce qui vient ensuite. Le diagramme ci-dessous décompose un prompt bien structuré, montrant comment les balises comme ``, ``, ``, ``, et `` organisent vos instructions en sections claires. Structure du prompt -*Anatomie d’un prompt bien structuré avec des sections claires et organisation de type XML* +*Anatomie d’un prompt bien structuré avec sections claires et organisation de style XML* **Qualité par auto-évaluation** -Les motifs auto-réflexifs fonctionnent en rendant explicites les critères de qualité. Au lieu d’espérer que le modèle « fasse bien », vous lui dites exactement ce que signifie « bien » : logique correcte, gestion des erreurs, performance, sécurité. Le modèle peut alors évaluer sa propre sortie et s’améliorer. Cela transforme la génération de code d’une loterie en un processus. +Les motifs auto-réfléchissants fonctionnent en rendant explicites les critères de qualité. Au lieu d’espérer que le modèle « fasse bien », vous lui dites précisément ce que signifie « bien » : logique correcte, gestion des erreurs, performance, sécurité. Le modèle peut alors évaluer sa propre sortie et s’améliorer. Cela transforme la génération de code d’une loterie en un processus. **Le contexte est fini** -Les conversations multi-tours fonctionnent en incluant l’historique des messages à chaque requête. Mais il y a une limite — chaque modèle a un nombre maximal de tokens. À mesure que les conversations s’allongent, vous aurez besoin de stratégies pour garder le contexte pertinent sans dépasser ce plafond. Ce module vous montre comment fonctionne la mémoire ; plus tard vous apprendrez quand résumer, quand oublier, et quand récupérer. +Les conversations multi-tours fonctionnent en incluant l’historique des messages avec chaque requête. Mais il y a une limite – chaque modèle a un compte maximal de tokens. À mesure que les conversations grandissent, vous aurez besoin de stratégies pour garder un contexte pertinent sans atteindre ce plafond. Ce module vous montre comment fonctionne la mémoire ; plus tard vous apprendrez quand résumer, quand oublier et quand récupérer. -## Prochaines étapes +## Étapes suivantes -**Module suivant :** [03-rag - RAG (Génération augmentée par recherche)](../03-rag/README.md) +**Module suivant :** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigation :** [← Précédent : Module 01 - Introduction](../01-introduction/README.md) | [Retour au début](../README.md) | [Suivant : Module 03 - RAG →](../03-rag/README.md) +**Navigation :** [← Précédent : Module 01 - Introduction](../01-introduction/README.md) | [Retour au principal](../README.md) | [Suivant : Module 03 - RAG →](../03-rag/README.md) --- -**Avis de non-responsabilité** : -Ce document a été traduit à l’aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforcions d’être précis, veuillez noter que les traductions automatiques peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue d’origine doit être considéré comme la source faisant foi. Pour toute information critique, une traduction professionnelle réalisée par un humain est recommandée. Nous déclinons toute responsabilité en cas de malentendus ou de mauvaises interprétations résultant de l’utilisation de cette traduction. +**Avertissement** : +Ce document a été traduit à l'aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçions d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue native doit être considéré comme la source faisant autorité. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous ne saurions être tenus responsables des malentendus ou erreurs d'interprétation découlant de l'utilisation de cette traduction. \ No newline at end of file diff --git a/translations/fr/03-rag/README.md b/translations/fr/03-rag/README.md index 9bd8cf011..eb10dfac9 100644 --- a/translations/fr/03-rag/README.md +++ b/translations/fr/03-rag/README.md @@ -2,31 +2,31 @@ ## Table des matières -- [Parcours vidéo](../../../03-rag) -- [Ce que vous apprendrez](../../../03-rag) -- [Prérequis](../../../03-rag) -- [Comprendre RAG](../../../03-rag) - - [Quelle approche RAG ce tutoriel utilise-t-il ?](../../../03-rag) -- [Comment ça fonctionne](../../../03-rag) - - [Traitement des documents](../../../03-rag) - - [Création des embeddings](../../../03-rag) - - [Recherche sémantique](../../../03-rag) - - [Génération de réponse](../../../03-rag) -- [Lancer l'application](../../../03-rag) -- [Utiliser l'application](../../../03-rag) - - [Télécharger un document](../../../03-rag) - - [Poser des questions](../../../03-rag) - - [Vérifier les références des sources](../../../03-rag) - - [Expérimenter avec les questions](../../../03-rag) -- [Concepts clés](../../../03-rag) - - [Stratégie de découpage](../../../03-rag) - - [Scores de similarité](../../../03-rag) - - [Stockage en mémoire](../../../03-rag) - - [Gestion de la fenêtre de contexte](../../../03-rag) -- [Quand RAG est important](../../../03-rag) -- [Prochaines étapes](../../../03-rag) - -## Parcours vidéo +- [Présentation vidéo](#présentation-vidéo) +- [Ce que vous apprendrez](#ce-que-vous-apprendrez) +- [Prérequis](#prérequis) +- [Comprendre RAG](#comprendre-rag) + - [Quelle approche RAG ce tutoriel utilise-t-il ?](#quelle-approche-rag-ce-tutoriel-utilise-t-il) +- [Comment ça fonctionne](#comment-ça-fonctionne) + - [Traitement des documents](#traitement-des-documents) + - [Création des embeddings](#création-des-embeddings) + - [Recherche sémantique](#recherche-sémantique) + - [Génération des réponses](#génération-de-réponse) +- [Exécuter l'application](#exécuter-lapplication) +- [Utiliser l'application](#utilisation-de-lapplication) + - [Télécharger un document](#téléversez-un-document) + - [Poser des questions](#posez-des-questions) + - [Vérifier les références sources](#vérifiez-les-références-sources) + - [Expérimenter avec les questions](#expérimentez-avec-les-questions) +- [Concepts clés](#concepts-clés) + - [Stratégie de découpage](#stratégie-de-découpage) + - [Scores de similarité](#scores-de-similarité) + - [Stockage en mémoire](#stockage-en-mémoire) + - [Gestion de la fenêtre de contexte](#gestion-de-la-fenêtre-de-contexte) +- [Quand RAG est important](#quand-rag-est-important) +- [Prochaines étapes](#étapes-suivantes) + +## Présentation vidéo Regardez cette session en direct qui explique comment démarrer avec ce module : @@ -34,111 +34,110 @@ Regardez cette session en direct qui explique comment démarrer avec ce module : ## Ce que vous apprendrez -Dans les modules précédents, vous avez appris à converser avec l'IA et à structurer vos invites de manière efficace. Mais il y a une limitation fondamentale : les modèles de langue ne connaissent que ce qu'ils ont appris lors de leur entraînement. Ils ne peuvent pas répondre à des questions sur les politiques de votre entreprise, votre documentation de projet, ou toute information sur laquelle ils n'ont pas été entraînés. +Dans les modules précédents, vous avez appris à avoir des conversations avec l'IA et à structurer efficacement vos prompts. Mais il existe une limitation fondamentale : les modèles de langage ne connaissent que ce qu’ils ont appris lors de l’entraînement. Ils ne peuvent pas répondre à des questions sur les politiques de votre entreprise, la documentation de vos projets, ou toute information sur laquelle ils n’ont pas été entraînés. -RAG (Génération Augmentée par Recherche) résout ce problème. Plutôt que d'essayer d'enseigner vos informations au modèle (ce qui est coûteux et peu pratique), vous lui donnez la capacité de chercher dans vos documents. Lorsqu'une question est posée, le système trouve des informations pertinentes et les inclut dans l'invite. Le modèle répond ensuite en se basant sur ce contexte récupéré. +RAG (Génération Augmentée par Recherche) résout ce problème. Plutôt que d’essayer d’enseigner au modèle vos informations (ce qui est coûteux et peu pratique), vous lui donnez la capacité de rechercher dans vos documents. Lorsqu’une question est posée, le système trouve les informations pertinentes et les inclut dans le prompt. Le modèle répond alors en se basant sur ce contexte récupéré. -Pensez à RAG comme donnant au modèle une bibliothèque de référence. Quand vous posez une question, le système : +Pensez à RAG comme si vous donniez au modèle une bibliothèque de référence. Lorsque vous posez une question, le système : -1. **Question utilisateur** – Vous posez une question -2. **Embedding** – Convertit votre question en vecteur -3. **Recherche vectorielle** – Trouve des morceaux de documents similaires -4. **Assemblage du contexte** – Ajoute les morceaux pertinents à l'invite -5. **Réponse** – Le LLM génère une réponse basée sur le contexte +1. **Question de l’utilisateur** - Vous posez une question +2. **Embedding** - Convertit votre question en vecteur +3. **Recherche vectorielle** - Trouve des morceaux de documents similaires +4. **Assemblage du contexte** - Ajoute les morceaux pertinents au prompt +5. **Réponse** - Le LLM génère une réponse basée sur le contexte -Cela ancre les réponses du modèle dans vos données réelles plutôt que de se fier à ses connaissances d'entraînement ou d'inventer des réponses. +Cela ancre les réponses du modèle dans vos données réelles au lieu de s’appuyer uniquement sur ses connaissances d’entraînement ou d’inventer des réponses. ## Prérequis -- Avoir terminé le [Module 00 - Démarrage rapide](../00-quick-start/README.md) (pour l'exemple Easy RAG mentionné plus tard dans ce module) -- Avoir terminé le [Module 01 - Introduction](../01-introduction/README.md) (ressources Azure OpenAI déployées, y compris le modèle d'embedding `text-embedding-3-small`) -- Fichier `.env` dans le répertoire racine avec les identifiants Azure (créé par `azd up` dans le Module 01) +- Module [01 - Introduction](../01-introduction/README.md) terminé (ressources Azure OpenAI déployées, incluant le modèle d’embedding `text-embedding-3-small`) +- Fichier `.env` dans le répertoire racine avec les identifiants Azure (créé par la commande `azd up` dans le Module 01) -> **Note :** Si vous n'avez pas terminé le Module 01, suivez d'abord les instructions de déploiement là-bas. La commande `azd up` déploie à la fois le modèle de chat GPT et le modèle d'embedding utilisé dans ce module. +> **Note :** Si vous n'avez pas terminé le Module 01, suivez d'abord les instructions de déploiement indiquées. La commande `azd up` déploie à la fois le modèle de chat GPT et le modèle d'embedding utilisé par ce module. ## Comprendre RAG -Le schéma ci-dessous illustre le concept clé : au lieu de s'appuyer uniquement sur les données d'entraînement du modèle, RAG lui fournit une bibliothèque de référence de vos documents à consulter avant de générer chaque réponse. +Le schéma ci-dessous illustre le concept central : au lieu de se fier uniquement aux données d'entraînement du modèle, RAG lui donne une bibliothèque de vos documents à consulter avant de générer chaque réponse. Qu'est-ce que RAG -*Ce schéma montre la différence entre un LLM standard (qui devine à partir des données d'entraînement) et un LLM amélioré par RAG (qui consulte d'abord vos documents).* +*Ce schéma montre la différence entre un LLM standard (qui devine à partir des données d’entraînement) et un LLM amélioré par RAG (qui consulte d’abord vos documents).* -Voici comment les éléments se connectent de bout en bout. La question d'un utilisateur passe par quatre étapes — embedding, recherche vectorielle, assemblage du contexte, et génération de réponse — chacune bâtie sur la précédente : +Voici comment les éléments se connectent de bout en bout. La question d’un utilisateur passe par quatre étapes — embedding, recherche vectorielle, assemblage du contexte et génération de réponse — chacune s’appuyant sur la précédente : Architecture RAG -*Ce schéma montre la chaîne complète du pipeline RAG — une question utilisateur passe par embedding, recherche vectorielle, assemblage du contexte et génération de réponse.* +*Ce schéma montre la chaîne complète RAG — une question utilisateur traverse les étapes d'embedding, recherche vectorielle, assemblage du contexte et génération de réponse.* -Le reste de ce module détaille chaque étape en détail, avec du code que vous pouvez exécuter et modifier. +Le reste de ce module détaille chaque étape, avec du code que vous pouvez exécuter et modifier. ### Quelle approche RAG ce tutoriel utilise-t-il ? -LangChain4j propose trois façons d'implémenter RAG, chacune avec un niveau d'abstraction différent. Le schéma ci-dessous les compare côte à côte : +LangChain4j propose trois façons d’implémenter RAG, chacune offrant un niveau d’abstraction différent. Le schéma ci-dessous les compare côte à côte : Trois approches RAG dans LangChain4j -*Ce schéma compare les trois approches LangChain4j RAG — Easy, Native, et Avancé — montrant leurs composants clés et quand les utiliser.* +*Ce schéma compare les trois approches RAG de LangChain4j — Facile, Native, et Avancée — montrant leurs composants clés et quand les utiliser.* -| Approche | Ce qu'elle fait | Compromis | +| Approche | Ce qu’elle fait | Compromis | |---|---|---| -| **Easy RAG** | Connecte automatiquement tout via `AiServices` et `ContentRetriever`. Vous annotez une interface, attachez un retriever, et LangChain4j gère l'embedding, la recherche, et l'assemblage d'invite en coulisses. | Code minimal, mais vous ne voyez pas ce qui se passe à chaque étape. | -| **Native RAG** | Vous appelez le modèle d'embedding, cherchez dans le magasin, construisez l'invite et générez la réponse vous-même — étape explicite par étape. | Plus de code, mais chaque étape est visible et modifiable. | -| **Advanced RAG** | Utilise le framework `RetrievalAugmentor` avec des transformeurs de requêtes, des routeurs, des re-classeurs, et des injecteurs de contenu modulaires pour des pipelines de production. | Flexibilité maximale, mais complexité nettement supérieure. | +| **Easy RAG** | Connecte automatiquement tout via `AiServices` et `ContentRetriever`. Vous annotez une interface, attachez un retriever, et LangChain4j gère en coulisses embedding, recherche et assemblage des prompts. | Code minimal, mais vous ne voyez pas ce qui se passe à chaque étape. | +| **Native RAG** | Vous appelez vous-même le modèle d’embedding, recherchez dans le magasin, assemblez le prompt et générez la réponse — une étape explicite à la fois. | Plus de code, mais chaque étape est visible et modifiable. | +| **Advanced RAG** | Utilise le cadre `RetrievalAugmentor` avec des transformateurs de requêtes, routeurs, re-classificateurs, et injecteurs de contenu modulaires pour des pipelines de production. | Flexibilité maximale, mais complexité nettement plus élevée. | -**Ce tutoriel utilise l'approche Native.** Chaque étape du pipeline RAG — embedding de la requête, recherche dans le magasin vectoriel, assemblage du contexte, et génération de réponse — est explicitement écrite dans [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). C'est intentionnel : en tant que ressource pédagogique, il est plus important que vous voyiez et compreniez chaque étape plutôt que le code soit minimisé. Une fois à l'aise avec les pièces, vous pouvez passer à Easy RAG pour des prototypes rapides ou Advanced RAG pour des systèmes en production. +**Ce tutoriel utilise l’approche Native.** Chaque étape de la chaîne RAG — embedding de la requête, recherche dans le magasin vectoriel, assemblage du contexte, et génération de la réponse — est explicitement écrite dans [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). C’est volontaire : en tant que ressource pédagogique, il est plus important que vous voyiez et compreniez chaque étape que de minimiser le code. Une fois à l’aise avec la chaîne, vous pourrez basculer sur Easy RAG pour des prototypes rapides ou Advanced RAG pour des systèmes en production. -> **💡 Vous avez déjà vu Easy RAG en action ?** Le [module Démarrage Rapide](../00-quick-start/README.md) inclut un exemple Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) qui utilise l'approche Easy RAG — LangChain4j gère automatiquement l'embedding, la recherche, et l'assemblage de l'invite. Ce module fait un pas de plus en ouvrant ce pipeline pour que vous puissiez voir et contrôler chaque étape vous-même. +> **💡 Curieux à propos de Easy RAG ?** LangChain4j offre aussi une approche *Easy RAG* où `AiServices` et un `ContentRetriever` gèrent automatiquement l'embedding, la recherche et l'assemblage des prompts. Ce module prend le chemin plus explicite — en ouvrant cette chaîne pour que vous puissiez voir et contrôler chaque étape. -Le schéma ci-dessous montre le pipeline Easy RAG de cet exemple Démarrage Rapide. Notez comment `AiServices` et `EmbeddingStoreContentRetriever` cachent toute la complexité — vous chargez un document, attachez un retriever, et obtenez des réponses. L'approche Native dans ce module ouvre chacune de ces étapes cachées : +Le schéma ci-dessous montre la pipeline Easy RAG. Notez comment `AiServices` et `EmbeddingStoreContentRetriever` cachent toute la complexité — vous chargez un document, vous attachez un retriever, et obtenez des réponses. L’approche Native dans ce module ouvre chacune de ces étapes cachées : Pipeline Easy RAG - LangChain4j -*Ce schéma montre le pipeline Easy RAG de `SimpleReaderDemo.java`. Comparez-le à l'approche Native utilisée ici : Easy RAG cache l'embedding, la récupération et l'assemblage de l'invite derrière `AiServices` et `ContentRetriever` — vous chargez un document, attachez un retriever, et obtenez des réponses. L'approche Native ouvre ce pipeline afin que vous appeliez chaque étape (embedder, chercher, assembler le contexte, générer) vous-même, vous donnant une visibilité et un contrôle complets.* +*Ce schéma montre la pipeline Easy RAG. Comparez avec l’approche Native utilisée dans ce module : Easy RAG cache embedding, récupération et assemblage du prompt derrière `AiServices` et `ContentRetriever` — vous chargez un document, attachez un retriever, et obtenez des réponses. L’approche Native ouvre cette pipeline pour que vous appeliez chaque étape (embedded, rechercher, assembler le contexte, générer) vous-même, offrant pleine visibilité et contrôle.* ## Comment ça fonctionne -Le pipeline RAG dans ce module est divisé en quatre étapes qui s'exécutent en séquence à chaque fois qu'un utilisateur pose une question. D'abord, un document chargé est **analysé et découpé en morceaux** exploitables. Ces morceaux sont ensuite convertis en **embeddings vecteurs** et stockés pour être comparés mathématiquement. Lorsqu'une requête arrive, le système effectue une **recherche sémantique** pour trouver les morceaux les plus pertinents, puis les passe en contexte au LLM pour la **génération de réponse**. Les sections suivantes parcourent chaque étape avec le code réel et des diagrammes. Regardons la première étape. +La pipeline RAG dans ce module se divise en quatre étapes séquentielles à chaque fois qu’un utilisateur pose une question. Premièrement, un document uploadé est **analysé et découpé en morceaux** gérables. Ces morceaux sont ensuite transformés en **embeddings vectoriels** et stockés pour pouvoir être comparés mathématiquement. Lorsqu’une requête arrive, le système effectue une **recherche sémantique** pour trouver les morceaux les plus pertinents, puis les passe comme contexte au LLM pour **génération de réponse**. Les sections ci-dessous expliquent chaque étape avec le code réel et des diagrammes. Regardons la première étape. ### Traitement des documents [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Lorsque vous téléchargez un document, le système l'analyse (PDF ou texte brut), attache des métadonnées telles que le nom de fichier, puis le découpe en morceaux — des segments plus petits qui tiennent confortablement dans la fenêtre de contexte du modèle. Ces morceaux se chevauchent légèrement pour éviter de perdre du contexte aux limites. +Quand vous chargez un document, le système l’analyse (PDF ou texte brut), y attache des métadonnées comme le nom de fichier, puis le décompose en morceaux — des parties plus petites qui tiennent confortablement dans la fenêtre de contexte du modèle. Ces morceaux se chevauchent légèrement pour ne pas perdre de contexte aux frontières. ```java -// Analyser le fichier téléchargé et l'encapsuler dans un Document LangChain4j +// Analyser le fichier téléchargé et l'encapsuler dans un document LangChain4j Document document = Document.from(content, metadata); -// Diviser en morceaux de 300 jetons avec un chevauchement de 30 jetons +// Diviser en morceaux de 300 tokens avec un chevauchement de 30 tokens DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Le schéma ci-dessous montre comment cela fonctionne visuellement. Notez que chaque morceau partage certains tokens avec ses voisins — le chevauchement de 30 tokens garantit qu'aucun contexte important ne se perd entre les morceaux : +Le schéma ci-dessous montre visuellement comment cela fonctionne. Notez comment chaque morceau partage certains tokens avec ses voisins — le chevauchement de 30 tokens garantit qu’aucun contexte important ne tombe entre les mailles du filet : -Découpage du document +Découpage de document -*Ce schéma montre un document découpé en morceaux de 300 tokens avec un chevauchement de 30 tokens, préservant le contexte aux frontières des morceaux.* +*Ce schéma montre un document découpé en morceaux de 300 tokens avec un chevauchement de 30 tokens, préservant le contexte aux limites des morceaux.* > **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) et demandez : -> - « Comment LangChain4j découpe-t-il les documents en morceaux et pourquoi le chevauchement est-il important ? » -> - « Quelle est la taille optimale des morceaux pour différents types de documents et pourquoi ? » -> - « Comment gérer des documents en plusieurs langues ou avec une mise en forme spéciale ? » +> - "Comment LangChain4j découpe-t-il les documents en morceaux et pourquoi le chevauchement est-il important ?" +> - "Quelle est la taille optimale des morceaux pour différents types de documents et pourquoi ?" +> - "Comment gérer les documents en plusieurs langues ou avec une mise en forme spéciale ?" ### Création des embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Chaque morceau est converti en une représentation numérique appelée embedding — essentiellement un convertisseur de sens en nombres. Le modèle d'embedding n'est pas "intelligent" comme un modèle de chat ; il ne peut pas suivre des instructions, raisonner ou répondre à des questions. Ce qu'il fait, c'est mapper le texte dans un espace mathématique où des sens similaires se retrouvent proches — « voiture » près de « automobile », « politique de remboursement » près de « retourner mon argent ». Pensez à un modèle de chat comme une personne à qui parler ; un modèle d'embedding est un système de classement ultra-efficace. +Chaque morceau est converti en une représentation numérique appelée embedding — essentiellement un convertisseur de sens en nombres. Le modèle d’embedding n’est pas « intelligent » comme un modèle de chat ; il ne suit pas d’instructions, ne raisonne pas et ne répond pas aux questions. Ce qu’il fait, c’est mapper le texte dans un espace mathématique où des significations similaires se regroupent — « voiture » proche de « automobile », « politique de remboursement » proche de « rendre mon argent ». Pensez à un modèle de chat comme une personne avec qui vous parlez ; un modèle d’embedding, c’est un système de classement ultra performant. -Le schéma ci-dessous visualise ce concept — du texte entre, des vecteurs numériques sortent, et des sens similaires produisent des vecteurs proches : +Le schéma ci-dessous illustre ce concept — du texte en entrée, des vecteurs numériques en sortie, et des significations proches produisent des vecteurs voisins : -Concept du modèle d'embedding +Concept de modèle d'embedding -*Ce schéma montre comment un modèle d'embedding convertit le texte en vecteurs numériques, plaçant des sens similaires — comme « voiture » et « automobile » — proches dans l'espace vectoriel.* +*Ce schéma montre comment un modèle d’embedding convertit le texte en vecteurs numériques, plaçant les significations similaires — comme « voiture » et « automobile » — proches dans l’espace vectoriel.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Le diagramme de classes ci-dessous montre les deux flux séparés dans un pipeline RAG et les classes LangChain4j qui les implémentent. Le **flux d'ingestion** (exécuté une fois au moment du chargement) découpe le document, embedde les morceaux, et les stocke via `.addAll()`. Le **flux de requête** (exécuté à chaque question utilisateur) embedde la question, cherche dans le magasin via `.search()`, et passe le contexte trouvé au modèle de chat. Les deux flux se rejoignent sur l'interface partagée `EmbeddingStore` : +Le diagramme de classes ci-dessous montre les deux flux séparés dans un pipeline RAG et les classes LangChain4j qui les mettent en œuvre. Le **flux d’ingestion** (exécuté une fois lors du téléchargement) découpe le document, embedde les morceaux, et les stocke via `.addAll()`. Le **flux de requête** (exécuté chaque fois qu’un utilisateur pose une question) embedde la question, recherche dans le magasin via `.search()`, et transmet le contexte correspondant au modèle de chat. Les deux flux se croisent sur l’interface partagée `EmbeddingStore` : -Classes LangChain4j RAG +Classes RAG LangChain4j -*Ce schéma montre les deux flux dans un pipeline RAG — ingestion et requête — et comment ils se connectent via un EmbeddingStore partagé.* +*Ce schéma montre les deux flux d’un pipeline RAG — ingestion et requête — et comment ils se connectent via un EmbeddingStore partagé.* -Une fois les embeddings stockés, les contenus similaires se regroupent naturellement dans l'espace vectoriel. La visualisation ci-dessous montre comment les documents sur des sujets liés forment des points proches, ce qui rend la recherche sémantique possible : +Une fois les embeddings stockés, les contenus similaires se regroupent naturellement dans l’espace vectoriel. La visualisation ci-dessous montre comment les documents sur des sujets liés forment des points proches, rendant la recherche sémantique possible : Espace des embeddings vectoriels -*Cette visualisation montre comment des documents liés se regroupent en 3D dans l'espace vectoriel, avec des sujets comme Documents Techniques, Règles d'Entreprise, et FAQ formant des regroupements distincts.* +*Cette visualisation montre comment les documents liés se regroupent dans un espace vectoriel 3D, avec des sujets comme Documentation Technique, Règles Métier, et FAQ formant des groupes distincts.* -Lorsqu'un utilisateur effectue une recherche, le système suit quatre étapes : embedder les documents une fois, embedder la requête à chaque recherche, comparer le vecteur de requête à tous les vecteurs stockés via la similarité cosinus, et retourner les meilleurs K morceaux. Le schéma ci-dessous parcourt chaque étape et les classes LangChain4j impliquées : +Lorsqu’un utilisateur effectue une recherche, le système suit quatre étapes : embedder les documents une fois, embedder la requête à chaque recherche, comparer le vecteur de la requête à tous les vecteurs stockés en utilisant la similarité cosinus, et retourner les K meilleurs morceaux. Le schéma ci-dessous présente chaque étape ainsi que les classes LangChain4j impliquées : -Étapes de recherche par embedding +Étapes de la recherche d'embedding -*Ce schéma montre le processus de recherche en quatre étapes : embedder les documents, embedder la requête, comparer les vecteurs avec la similarité cosinus, et retourner les meilleurs résultats.* +*Ce schéma montre les quatre étapes de la recherche par embedding : embedder les documents, embedder la requête, comparer les vecteurs avec la similarité cosinus, et retourner les meilleurs résultats.* ### Recherche sémantique [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Lorsque vous posez une question, votre question devient aussi un embedding. Le système compare l'embedding de votre question avec tous les embeddings des morceaux de documents. Il trouve les morceaux aux significations les plus similaires — pas seulement par correspondance de mots-clés, mais par similarité sémantique réelle. +Lorsque vous posez une question, celle-ci est également convertie en embedding. Le système compare l’embedding de votre question à tous les embeddings des morceaux du document. Il trouve les morceaux au sens le plus proche — pas seulement des mots-clés correspondants, mais une réelle similarité sémantique. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Le schéma ci-dessous contraste la recherche sémantique avec la recherche traditionnelle par mots-clés. Une recherche par mot-clé pour « véhicule » manque un morceau parlant de « voitures et camions », mais la recherche sémantique comprend qu'ils veulent dire la même chose et le retourne comme un résultat classé haut : +Le schéma ci-dessous illustre la différence entre la recherche sémantique et la recherche traditionnelle par mots-clés. Une recherche par mot-clé sur « véhicule » passe à côté d’un morceau parlant de « voitures et camions », alors que la recherche sémantique comprend qu’ils signifient la même chose et le retourne parmi les résultats les mieux notés : Recherche sémantique -*Ce schéma compare la recherche basée sur mots-clés à la recherche sémantique, montrant comment la recherche sémantique récupère un contenu conceptuellement lié même lorsque les mots exacts diffèrent.* -Sous le capot, la similarité est mesurée en utilisant la similarité cosinus — se demandant essentiellement « ces deux flèches pointent-elles dans la même direction ? » Deux segments peuvent utiliser des mots complètement différents, mais s'ils signifient la même chose, leurs vecteurs pointent dans la même direction et obtiennent un score proche de 1.0 : +*Ce schéma compare la recherche basée sur mots-clés avec la recherche sémantique, montrant comment la recherche sémantique récupère du contenu conceptuellement lié même lorsque les mots exacts diffèrent.* -Similarité Cosinus +Sous le capot, la similarité est mesurée via la similarité cosinus — une façon de demander « ces deux flèches pointent-elles dans la même direction ? » Deux morceaux peuvent utiliser des mots complètement différents, mais si leur sens est identique, leurs vecteurs pointent dans la même direction et obtiennent un score proche de 1,0 : -*Ce diagramme illustre la similarité cosinus comme l’angle entre les vecteurs d’embeddding — des vecteurs plus alignés obtiennent un score proche de 1.0, indiquant une plus grande similarité sémantique.* +Similarité cosinus +*Ce diagramme illustre la similarité cosinus comme l'angle entre les vecteurs d'incorporation — des vecteurs plus alignés obtiennent un score proche de 1.0, indiquant une similarité sémantique plus élevée.* > **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) et demandez : -> - « Comment fonctionne la recherche par similarité avec les embeddings et qu’est-ce qui détermine le score ? » -> - « Quel seuil de similarité dois-je utiliser et comment cela influence-t-il les résultats ? » -> - « Comment gérer les cas où aucun document pertinent n’est trouvé ? » +> - « Comment fonctionne la recherche de similarité avec les incorporations et qu'est-ce qui détermine le score ? » +> - « Quel seuil de similarité devrais-je utiliser et comment cela affecte-t-il les résultats ? » +> - « Comment gérer les cas où aucun document pertinent n'est trouvé ? » ### Génération de Réponse [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Les segments les plus pertinents sont assemblés dans un prompt structuré comprenant des instructions explicites, le contexte récupéré, et la question de l’utilisateur. Le modèle lit ces segments spécifiques et répond sur cette base — il ne peut utiliser que ce qui est devant lui, ce qui évite les hallucinations. +Les fragments les plus pertinents sont assemblés en une invite structurée qui comprend des instructions explicites, le contexte récupéré, et la question de l'utilisateur. Le modèle lit ces fragments spécifiques et répond sur la base de ces informations — il ne peut utiliser que ce qui se trouve devant lui, ce qui empêche les hallucinations. ```java String context = matches.stream() @@ -237,21 +236,21 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Le diagramme ci-dessous montre cette assemblée en action — les segments les mieux notés de l’étape de recherche sont injectés dans le modèle de prompt, et `OpenAiOfficialChatModel` génère une réponse fondée : +Le diagramme ci-dessous montre cet assemblage en action — les fragments les mieux notés de l'étape de recherche sont injectés dans le modèle d'invite, et le `OpenAiOfficialChatModel` génère une réponse fondée : -Assemblage du Contexte +Assemblage du contexte -*Ce diagramme montre comment les segments les mieux notés sont assemblés dans un prompt structuré, permettant au modèle de générer une réponse fondée à partir de vos données.* +*Ce diagramme montre comment les fragments les mieux notés sont assemblés en une invite structurée, permettant au modèle de générer une réponse fondée à partir de vos données.* -## Lancer l’Application +## Exécuter l'Application -**Vérifier le déploiement :** +**Vérifiez le déploiement :** -Assurez-vous que le fichier `.env` existe dans le répertoire racine avec les identifiants Azure (créés pendant le Module 01). Exécutez cette commande depuis le répertoire du module (`03-rag/`) : +Assurez-vous que le fichier `.env` existe dans le répertoire racine avec les identifiants Azure (créés lors du Module 01). Lancez ceci depuis le répertoire du module (`03-rag/`) : **Bash :** ```bash -cat ../.env # Doit afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell :** @@ -259,29 +258,29 @@ cat ../.env # Doit afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Démarrer l’application :** +**Démarrer l'application :** -> **Note :** Si vous avez déjà lancé toutes les applications avec `./start-all.sh` depuis le répertoire racine (comme décrit dans le Module 01), ce module est déjà en fonctionnement sur le port 8081. Vous pouvez sauter les commandes de démarrage ci-dessous et aller directement sur http://localhost:8081. +> **Note :** Si vous avez déjà démarré toutes les applications avec `./start-all.sh` depuis le répertoire racine (comme décrit dans le Module 01), ce module est déjà en cours d'exécution sur le port 8081. Vous pouvez ignorer les commandes de démarrage ci-dessous et aller directement à http://localhost:8081. -**Option 1 : Utiliser Spring Boot Dashboard (recommandé pour les utilisateurs de VS Code)** +**Option 1 : Utilisation du Spring Boot Dashboard (recommandé pour les utilisateurs de VS Code)** -Le conteneur de développement inclut l’extension Spring Boot Dashboard, qui fournit une interface visuelle pour gérer toutes les applications Spring Boot. Vous pouvez la trouver dans la barre d’activités à gauche dans VS Code (cherchez l’icône Spring Boot). +Le conteneur de développement inclut l'extension Spring Boot Dashboard, qui fournit une interface visuelle pour gérer toutes les applications Spring Boot. Vous la trouverez dans la barre d'activités à gauche de VS Code (cherchez l'icône Spring Boot). Depuis le Spring Boot Dashboard, vous pouvez : -- Voir toutes les applications Spring Boot disponibles dans l’espace de travail -- Démarrer/arrêter les applications d’un simple clic -- Consulter les journaux en temps réel -- Surveiller l’état des applications +- Voir toutes les applications Spring Boot disponibles dans l'espace de travail +- Démarrer/arrêter les applications d'un simple clic +- Voir les journaux des applications en temps réel +- Surveiller le statut des applications -Cliquez simplement sur le bouton lecture à côté de « rag » pour démarrer ce module, ou lancez tous les modules en une fois. +Cliquez simplement sur le bouton play à côté de « rag » pour démarrer ce module, ou démarrez tous les modules en une fois. Spring Boot Dashboard -*Cette capture d’écran montre le Spring Boot Dashboard dans VS Code, où vous pouvez démarrer, arrêter et surveiller visuellement les applications.* +*Cette capture d'écran montre le Spring Boot Dashboard dans VS Code, où vous pouvez démarrer, arrêter et surveiller visuellement les applications.* -**Option 2 : Utiliser les scripts shell** +**Option 2 : Utilisation de scripts shell** -Lancez toutes les applications web (modules 01-04) : +Démarrez toutes les applications web (modules 01-04) : **Bash :** ```bash @@ -295,7 +294,7 @@ cd .. # Depuis le répertoire racine .\start-all.ps1 ``` -Ou lancez uniquement ce module : +Ou démarrez uniquement ce module : **Bash :** ```bash @@ -309,16 +308,16 @@ cd 03-rag .\start.ps1 ``` -Les deux scripts chargent automatiquement les variables d’environnement depuis le fichier `.env` racine et construiront les JARs s’ils n’existent pas. +Les deux scripts chargent automatiquement les variables d'environnement depuis le fichier `.env` racine et construiront les JAR si ceux-ci n'existent pas. -> **Note :** Si vous préférez construire manuellement tous les modules avant de lancer : +> **Note :** Si vous préférez construire tous les modules manuellement avant de démarrer : > > **Bash :** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell :** > ```powershell > cd .. # Go to root directory @@ -331,107 +330,107 @@ Ouvrez http://localhost:8081 dans votre navigateur. **Bash :** ```bash -./stop.sh # Ce module seulement +./stop.sh # Ce module uniquement # Ou cd .. && ./stop-all.sh # Tous les modules ``` **PowerShell :** ```powershell -.\stop.ps1 # Ce module seulement +.\stop.ps1 # Ce module uniquement # Ou cd ..; .\stop-all.ps1 # Tous les modules ``` -## Utiliser l’Application +## Utilisation de l'Application -L’application fournit une interface web pour le téléversement de documents et la pose de questions. +L'application fournit une interface web pour le téléchargement de documents et la pose de questions. -Interface de l’Application RAG +Interface de l'application RAG -*Cette capture d’écran montre l’interface de l’application RAG où vous téléversez des documents et posez des questions.* +*Cette capture d'écran montre l'interface de l'application RAG où vous téléversez des documents et posez des questions.* -### Téléverser un Document +### Téléversez un Document -Commencez par téléverser un document - les fichiers TXT fonctionnent le mieux pour tester. Un `sample-document.txt` est fourni dans ce répertoire, contenant des informations sur les fonctionnalités de LangChain4j, la mise en œuvre RAG, et les bonnes pratiques — parfait pour tester le système. +Commencez par téléverser un document — les fichiers TXT fonctionnent le mieux pour les tests. Un fichier `sample-document.txt` est fourni dans ce répertoire, contenant des informations sur les fonctionnalités LangChain4j, l'implémentation RAG, et les bonnes pratiques — parfait pour tester le système. -Le système traite votre document, le divise en segments, et crée des embeddings pour chaque segment. Cela se fait automatiquement lors du téléversement. +Le système traite votre document, le découpe en fragments, et crée des incorporations pour chaque fragment. Cela se fait automatiquement dès que vous téléversez. -### Poser des Questions +### Posez des Questions -Posez maintenant des questions spécifiques sur le contenu du document. Essayez quelque chose de factuel et clairement indiqué dans le document. Le système recherche les segments pertinents, les inclut dans le prompt, et génère une réponse. +Posez maintenant des questions spécifiques sur le contenu du document. Essayez quelque chose de factuel clairement indiqué dans le document. Le système cherche les fragments pertinents, les inclut dans l'invite, et génère une réponse. -### Vérifier les Références Sources +### Vérifiez les Références Sources -Remarquez que chaque réponse inclut des références sources avec des scores de similarité. Ces scores (entre 0 et 1) montrent à quel point chaque segment était pertinent pour votre question. Des scores élevés signifient de meilleures correspondances. Cela vous permet de vérifier la réponse par rapport à la source. +Notez que chaque réponse inclut des références sources avec des scores de similarité. Ces scores (de 0 à 1) indiquent à quel point chaque fragment était pertinent pour votre question. Des scores plus élevés signifient de meilleures correspondances. Cela vous permet de vérifier la réponse par rapport au matériel source. -Résultats de Requête RAG +Résultats de requête RAG -*Cette capture d’écran montre les résultats d’une requête avec la réponse générée, les références sources, et les scores de pertinence pour chaque segment récupéré.* +*Cette capture d'écran montre les résultats d'une requête avec la réponse générée, les références sources, et les scores de pertinence pour chaque fragment récupéré.* ### Expérimentez avec les Questions Essayez différents types de questions : - Faits spécifiques : « Quel est le sujet principal ? » - Comparaisons : « Quelle est la différence entre X et Y ? » -- Résumés : « Résumez les points clés sur Z » +- Résumés : « Résumez les points clés concernant Z » -Observez comment les scores de pertinence changent selon la qualité de la correspondance entre votre question et le contenu du document. +Observez comment les scores de pertinence changent en fonction de la correspondance entre votre question et le contenu du document. ## Concepts Clés -### Stratégie de Chunking +### Stratégie de Découpage -Les documents sont découpés en segments de 300 tokens avec un chevauchement de 30 tokens. Ce compromis garantit que chaque segment contient suffisamment de contexte pour être significatif tout en restant suffisamment petit pour inclure plusieurs segments dans un prompt. +Les documents sont divisés en fragments de 300 jetons avec un chevauchement de 30 jetons. Cet équilibre garantit que chaque fragment contient assez de contexte pour être significatif tout en restant assez petit pour inclure plusieurs fragments dans une invite. ### Scores de Similarité -Chaque segment récupéré est accompagné d’un score de similarité entre 0 et 1 indiquant à quel point il correspond à la question de l’utilisateur. Le diagramme ci-dessous visualise les plages de score et la manière dont le système les utilise pour filtrer les résultats : +Chaque fragment récupéré est accompagné d'un score de similarité compris entre 0 et 1 indiquant sa proximité avec la question de l'utilisateur. Le diagramme ci-dessous visualise les plages de score et comment le système les utilise pour filtrer les résultats : Scores de Similarité -*Ce diagramme montre les plages de scores de 0 à 1, avec un seuil minimum de 0,5 qui filtre les segments non pertinents.* +*Ce diagramme montre les plages de score de 0 à 1, avec un seuil minimum de 0.5 qui filtre les fragments non pertinents.* -Les scores varient de 0 à 1 : -- 0,7-1,0 : Très pertinent, correspondance exacte -- 0,5-0,7 : Pertinent, bon contexte -- En dessous de 0,5 : Filtré, trop dissemblable +Les scores vont de 0 à 1 : +- 0.7-1.0 : Très pertinent, correspondance exacte +- 0.5-0.7 : Pertinent, bon contexte +- En dessous de 0.5 : Filtré, trop dissemblable -Le système ne récupère que les segments au-dessus du seuil minimal pour garantir la qualité. +Le système ne récupère que les fragments au-dessus du seuil minimum pour assurer la qualité. -Les embeddings fonctionnent bien lorsque le sens est clairement clusterisé, mais ont des angles morts. Le diagramme ci-dessous montre les modes d’échec courants — les segments trop grands produisent des vecteurs flous, les segments trop petits manquent de contexte, les termes ambigus pointent vers plusieurs clusters, et les recherches par correspondance exacte (IDs, numéros de pièces) ne fonctionnent pas du tout avec les embeddings : +Les incorporations fonctionnent bien lorsque le sens se regroupe clairement, mais elles ont des angles morts. Le diagramme ci-dessous montre les modes de défaillance courants — les fragments trop grands produisent des vecteurs flous, les fragments trop petits manquent de contexte, les termes ambigus pointent vers plusieurs groupes, et les recherches par correspondance exacte (ID, numéros de pièce) ne fonctionnent pas du tout avec les incorporations : -Modes d’Échec des Embeddings +Modes de défaillance des incorporations -*Ce diagramme montre les modes d’échec communs des embeddings : segments trop grands, segments trop petits, termes ambigus dirigés vers plusieurs clusters, et recherches par correspondance exacte comme les IDs.* +*Ce diagramme montre les modes de défaillance courants des incorporations : fragments trop grands, fragments trop petits, termes ambigus pointant vers plusieurs groupes, et recherches par correspondance exacte comme les IDs.* ### Stockage en Mémoire -Ce module utilise un stockage en mémoire pour la simplicité. Quand vous redémarrez l’application, les documents téléversés sont perdus. Les systèmes en production utilisent des bases de données vectorielles persistantes comme Qdrant ou Azure AI Search. +Ce module utilise un stockage en mémoire pour la simplicité. Lorsque vous redémarrez l'application, les documents téléversés sont perdus. Les systèmes en production utilisent des bases de données vectorielles persistantes comme Qdrant ou Azure AI Search. ### Gestion de la Fenêtre de Contexte -Chaque modèle a une fenêtre de contexte maximale. Vous ne pouvez pas inclure tous les segments d’un grand document. Le système récupère les N segments les plus pertinents (par défaut 5) pour rester dans les limites tout en fournissant suffisamment de contexte pour des réponses précises. +Chaque modèle a une fenêtre de contexte maximale. Vous ne pouvez pas inclure tous les fragments d'un grand document. Le système récupère les N fragments les plus pertinents (par défaut 5) pour rester dans les limites tout en fournissant assez de contexte pour des réponses précises. -## Quand le RAG est Important +## Quand RAG est Important -Le RAG n’est pas toujours la bonne approche. Le guide de décision ci-dessous vous aide à déterminer quand le RAG apporte une valeur ajoutée versus quand des approches plus simples — comme inclure le contenu directement dans le prompt ou s’appuyer sur les connaissances intégrées du modèle — suffisent : +RAG n'est pas toujours la meilleure approche. Le guide de décision ci-dessous vous aide à déterminer quand RAG apporte une valeur ajoutée versus quand des approches plus simples — comme inclure le contenu directement dans l'invite ou compter sur la connaissance intégrée du modèle — suffisent : -Quand Utiliser le RAG +Quand utiliser RAG -*Ce diagramme montre un guide décisionnel pour savoir quand le RAG ajoute de la valeur par rapport à des approches plus simples.* +*Ce diagramme montre un guide de décision pour savoir quand RAG apporte de la valeur par rapport aux approches plus simples.* ## Étapes Suivantes -**Module suivant :** [04-tools - Agents IA avec Outils](../04-tools/README.md) +**Module Suivant :** [04-tools - Agents IA avec Outils](../04-tools/README.md) --- -**Navigation :** [← Précédent : Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Retour à l’Accueil](../README.md) | [Suivant : Module 04 - Outils →](../04-tools/README.md) +**Navigation :** [← Précédent : Module 02 - Ingénierie de Prompt](../02-prompt-engineering/README.md) | [Retour au Principal](../README.md) | [Suivant : Module 04 - Outils →](../04-tools/README.md) --- -**Avertissement** : -Ce document a été traduit à l’aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforcions d’assurer l’exactitude, veuillez noter que les traductions automatiques peuvent contenir des erreurs ou des imprécisions. Le document original dans sa langue d’origine doit être considéré comme la source faisant foi. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle effectuée par un humain. Nous déclinons toute responsabilité en cas de malentendus ou de mauvaises interprétations résultant de l’utilisation de cette traduction. +**Avertissement** : +Ce document a été traduit à l'aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçions d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue native doit être considéré comme la source faisant autorité. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous ne saurions être tenus responsables des malentendus ou erreurs d'interprétation découlant de l'utilisation de cette traduction. \ No newline at end of file diff --git a/translations/fr/04-tools/README.md b/translations/fr/04-tools/README.md index 9e3db6fc8..4b00bd29d 100644 --- a/translations/fr/04-tools/README.md +++ b/translations/fr/04-tools/README.md @@ -1,80 +1,80 @@ -# Module 04 : Agents IA avec des Outils - -## Table des Matières - -- [Parcours Vidéo](../../../04-tools) -- [Ce que vous apprendrez](../../../04-tools) -- [Prérequis](../../../04-tools) -- [Comprendre les agents IA avec des outils](../../../04-tools) -- [Comment fonctionne l'appel d'outils](../../../04-tools) - - [Définitions d'outils](../../../04-tools) - - [Prise de décision](../../../04-tools) - - [Exécution](../../../04-tools) - - [Génération de la réponse](../../../04-tools) - - [Architecture : Auto-wiring Spring Boot](../../../04-tools) -- [Chaînage d'outils](../../../04-tools) -- [Lancer l'application](../../../04-tools) -- [Utilisation de l'application](../../../04-tools) - - [Essayer un usage simple d'un outil](../../../04-tools) - - [Tester le chaînage d'outils](../../../04-tools) - - [Voir le déroulement de la conversation](../../../04-tools) - - [Expérimenter avec différentes requêtes](../../../04-tools) -- [Concepts clés](../../../04-tools) - - [Pattern ReAct (Raisonnement et Action)](../../../04-tools) - - [Les descriptions d'outils comptent](../../../04-tools) - - [Gestion des sessions](../../../04-tools) - - [Gestion des erreurs](../../../04-tools) -- [Outils disponibles](../../../04-tools) -- [Quand utiliser des agents basés sur des outils](../../../04-tools) -- [Outils vs RAG](../../../04-tools) -- [Étapes suivantes](../../../04-tools) - -## Parcours Vidéo - -Regardez cette session en direct qui explique comment débuter avec ce module : - -Agents IA avec outils et MCP - Session en direct +# Module 04 : Agents IA avec Outils + +## Table des matières + +- [Présentation vidéo](#présentation-vidéo) +- [Ce que vous apprendrez](#ce-que-vous-apprendrez) +- [Prérequis](#prérequis) +- [Comprendre les agents IA avec outils](#comprendre-les-agents-ia-avec-outils) +- [Comment fonctionne l’appel d’outils](#comment-fonctionne-l’appel-d’outils) + - [Définitions des outils](#définitions-des-outils) + - [Prise de décision](#prise-de-décision) + - [Exécution](#exécution) + - [Génération de réponse](#génération-de-réponse) + - [Architecture : Auto-injection Spring Boot](#architecture-auto-injection-spring-boot) +- [Chaînage d’outils](#chaînage-d’outils) +- [Exécuter l’application](#exécuter-l’application) +- [Utilisation de l’application](#utilisation-de-l’application) + - [Essayez une utilisation simple des outils](#essayez-une-utilisation-simple-des-outils) + - [Tester le chaînage d’outils](#testez-le-chaînage-d’outils) + - [Voir le flux de conversation](#voyez-le-flux-de-conversation) + - [Expérimentez avec différentes requêtes](#expérimentez-avec-différentes-requêtes) +- [Concepts clés](#concepts-clés) + - [Pattern ReAct (Raisonnement et Action)](#modèle-react-raisonner-et-agir) + - [L’importance des descriptions d’outils](#les-descriptions-d’outils-comptent) + - [Gestion des sessions](#gestion-de-session) + - [Gestion des erreurs](#gestion-des-erreurs) +- [Outils disponibles](#outils-disponibles) +- [Quand utiliser des agents basés sur des outils](#quand-utiliser-des-agents-basés-sur-les-outils) +- [Outils vs RAG](#outils-vs-rag) +- [Étapes suivantes](#étapes-suivantes) + +## Présentation vidéo + +Regardez cette session en direct qui explique comment démarrer avec ce module : + +Agents IA avec Outils et MCP - Session en direct ## Ce que vous apprendrez -Jusqu'à présent, vous avez appris à converser avec une IA, à structurer efficacement des prompts, et à ancrer les réponses dans vos documents. Mais il existe toujours une limitation fondamentale : les modèles de langage ne peuvent générer que du texte. Ils ne peuvent pas consulter la météo, effectuer des calculs, interroger des bases de données ou interagir avec des systèmes externes. +Jusqu’à présent, vous avez appris à avoir des conversations avec l’IA, structurer efficacement les prompts et ancrer les réponses dans vos documents. Mais il reste une limitation fondamentale : les modèles de langage ne peuvent générer que du texte. Ils ne peuvent pas consulter la météo, effectuer des calculs, interroger des bases de données ou interagir avec des systèmes externes. -Les outils changent cela. En donnant au modèle accès à des fonctions qu’il peut appeler, vous le transformez d’un générateur de texte en un agent capable d’agir. Le modèle décide quand il a besoin d’un outil, quel outil utiliser, et quels paramètres transmettre. Votre code exécute la fonction et renvoie le résultat. Le modèle incorpore ce résultat dans sa réponse. +Les outils changent cela. En donnant au modèle accès à des fonctions qu’il peut appeler, vous le transformez d’un générateur de texte en un agent capable d’agir. Le modèle décide quand il a besoin d’un outil, quel outil utiliser et quels paramètres transmettre. Votre code exécute la fonction et retourne le résultat. Le modèle incorpore ce résultat dans sa réponse. ## Prérequis -- Avoir terminé le [Module 01 - Introduction](../01-introduction/README.md) (ressources Azure OpenAI déployées) -- Avoir terminé les modules précédents recommandés (ce module fait référence aux [concepts RAG du Module 03](../03-rag/README.md) dans la comparaison Outils vs RAG) +- Module [01 - Introduction](../01-introduction/README.md) complété (ressources Azure OpenAI déployées) +- Modules précédents recommandés (ce module fait référence aux [concepts RAG du Module 03](../03-rag/README.md) dans la comparaison Outils vs RAG) - Fichier `.env` dans le répertoire racine avec les identifiants Azure (créé par `azd up` dans le Module 01) -> **Note :** Si vous n'avez pas terminé le Module 01, suivez d'abord les instructions de déploiement indiquées. +> **Note :** Si vous n’avez pas encore terminé le Module 01, suivez d’abord les instructions de déploiement qui y figurent. -## Comprendre les agents IA avec des outils +## Comprendre les agents IA avec outils -> **📝 Note :** Le terme « agents » dans ce module désigne des assistants IA améliorés avec la capacité d’appeler des outils. Ceci est différent des modèles **Agentic AI** (agents autonomes avec planification, mémoire et raisonnement multi-étapes) que nous aborderons dans le [Module 05 : MCP](../05-mcp/README.md). +> **📝 Note :** Le terme « agents » dans ce module désigne des assistants IA enrichis de la capacité à appeler des outils. Cela diffère des patterns **Agentic AI** (agents autonomes avec planification, mémoire et raisonnement multi-étapes) que nous traiterons dans le [Module 05 : MCP](../05-mcp/README.md). -Sans outils, un modèle de langage peut uniquement générer du texte à partir de ses données d'entraînement. Demandez-lui la météo actuelle, il doit deviner. Donnez-lui des outils et il peut appeler une API météo, effectuer des calculs ou interroger une base de données — puis intégrer ces résultats réels dans sa réponse. +Sans outils, un modèle de langage ne peut générer que du texte issu de ses données d’entraînement. Demandez la météo actuelle, il doit deviner. Donnez-lui des outils, il peut appeler une API météo, effectuer des calculs ou interroger une base de données — puis intégrer ces résultats réels dans sa réponse. Sans outils vs Avec outils -*Sans outils, le modèle ne peut que deviner — avec des outils, il peut appeler des API, exécuter des calculs et retourner des données en temps réel.* +*Sans outils, le modèle ne peut que deviner — avec des outils, il peut appeler des API, faire des calculs et fournir des données en temps réel.* -Un agent IA avec des outils suit un pattern **Reasoning and Acting (ReAct)**. Le modèle ne se contente pas de répondre — il réfléchit à ce dont il a besoin, agit en appelant un outil, observe le résultat, puis décide s’il doit agir à nouveau ou livrer la réponse finale : +Un agent IA avec outils suit un pattern **Raisonnement et Action (ReAct)**. Le modèle ne se contente pas de répondre — il réfléchit à ce dont il a besoin, agit en appelant un outil, observe le résultat, puis décide s’il doit agir à nouveau ou fournir la réponse finale : -1. **Raisonner** — L’agent analyse la question de l’utilisateur et détermine quelles informations il lui faut -2. **Agir** — L’agent sélectionne l’outil approprié, génère les paramètres corrects, et l’appelle -3. **Observer** — L’agent reçoit la sortie de l’outil et évalue le résultat +1. **Raisonner** — L’agent analyse la question de l’utilisateur et détermine quelles informations sont nécessaires +2. **Agir** — L’agent sélectionne l’outil approprié, génère les bons paramètres, puis l’appelle +3. **Observer** — L’agent reçoit la sortie de l’outil et évalue le résultat 4. **Répéter ou Répondre** — Si plus de données sont nécessaires, l’agent recommence ; sinon, il compose une réponse en langage naturel Pattern ReAct -*Le cycle ReAct — l’agent raisonne sur ce qu’il doit faire, agit en appelant un outil, observe le résultat, et boucle jusqu’à pouvoir fournir la réponse finale.* +*Le cycle ReAct — l’agent raisonne sur ce qu’il doit faire, agit en appelant un outil, observe le résultat et boucle jusqu’à fournir la réponse finale.* -Cela se passe automatiquement. Vous définissez les outils et leurs descriptions. Le modèle gère la prise de décision pour savoir quand et comment les utiliser. +Ceci se passe automatiquement. Vous définissez les outils et leurs descriptions. Le modèle prend en charge la prise de décision sur quand et comment les utiliser. -## Comment fonctionne l'appel d'outils +## Comment fonctionne l’appel d’outils -### Définitions d'outils +### Définitions des outils [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) @@ -102,134 +102,131 @@ public interface Assistant { // - ChatMemoryProvider pour la gestion des sessions ``` +Le diagramme ci-dessous décompose chaque annotation et montre comment chaque élément aide l’IA à comprendre quand appeler l’outil et quels arguments transmettre : -Le schéma ci-dessous détaille chaque annotation et montre comment chaque élément aide l’IA à comprendre quand appeler l’outil et quels arguments transmettre : +Anatomie des définitions d’outils -Anatomie des définitions d'outils +*Anatomie d’une définition d’outil — @Tool indique à l’IA quand l’utiliser, @P décrit chaque paramètre, et @AiService connecte tout automatiquement au démarrage.* -*Anatomie d’une définition d’outil — @Tool indique à l’IA quand l’utiliser, @P décrit chaque paramètre, et @AiService connecte tout au démarrage.* - -> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) et demandez : -> - « Comment intégrerais-je une vraie API météo comme OpenWeatherMap au lieu de données factices ? » -> - « Qu’est-ce qui fait une bonne description d’outil qui aide l’IA à l’utiliser correctement ? » +> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) et demandez : +> - « Comment intégrer une vraie API météo comme OpenWeatherMap plutôt que des données simulées ? » +> - « Qu’est-ce qui fait une bonne description d’outil pour aider l’IA à l’utiliser correctement ? » > - « Comment gérer les erreurs d’API et les limites de requêtes dans l’implémentation des outils ? » ### Prise de décision -Lorsqu’un utilisateur demande « Quelle est la météo à Seattle ? », le modèle ne choisit pas un outil au hasard. Il compare l’intention de l’utilisateur à chaque description d’outil accessible, évalue leur pertinence, et sélectionne la meilleure correspondance. Il génère alors un appel de fonction structuré avec les bons paramètres — ici, en définissant `location` à `"Seattle"`. +Quand un utilisateur demande « Quelle est la météo à Seattle ? », le modèle ne choisit pas un outil au hasard. Il compare l’intention de l’utilisateur avec chaque description d’outil dont il dispose, attribue un score de pertinence à chacune, puis sélectionne la meilleure correspondance. Il génère ensuite un appel de fonction structuré avec les bons paramètres — ici, en définissant `location` à `"Seattle"`. -Si aucun outil ne correspond à la demande, le modèle répond depuis ses propres connaissances. Si plusieurs outils correspondent, il choisit le plus spécifique. +Si aucun outil ne correspond à la requête, le modèle répond depuis ses connaissances. Si plusieurs outils correspondent, il choisit le plus spécifique. -Comment l'IA décide quel outil utiliser +Comment l’IA choisit l’outil à utiliser -*Le modèle évalue chaque outil disponible par rapport à l’intention de l’utilisateur et sélectionne la meilleure correspondance — d’où l’importance d’écrire des descriptions d’outils claires et précises.* +*Le modèle évalue chaque outil disponible face à l’intention de l’utilisateur et sélectionne la meilleure correspondance — c’est pourquoi il est important de rédiger des descriptions d’outils claires et spécifiques.* ### Exécution [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot connecte automatiquement l’interface déclarative `@AiService` avec tous les outils enregistrés, et LangChain4j exécute les appels aux outils automatiquement. Dans les coulisses, un appel complet d’outil passe par six étapes — depuis la question en langage naturel posée par l'utilisateur jusqu’à la réponse finale en langage naturel : +Spring Boot injecte automatiquement l’interface déclarative `@AiService` avec tous les outils enregistrés, et LangChain4j exécute les appels d’outils automatiquement. En coulisses, un appel complet d’outil traverse six étapes — de la question en langage naturel de l’utilisateur jusqu’à la réponse en langage naturel : -Flux d'appel d'outils +Flux d’appel d’outil *Le flux de bout en bout — l’utilisateur pose une question, le modèle sélectionne un outil, LangChain4j l’exécute, et le modèle intègre le résultat dans une réponse naturelle.* -Si vous avez exécuté la [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) du Module 00, vous avez déjà vu ce pattern en action — les outils `Calculator` étaient appelés de la même manière. Le diagramme de séquence ci-dessous détaille exactement ce qui s’est passé sous le capot durant cette démo : +En coulisses, `AiServices` exécute la même boucle d’appel d’outil pour n’importe quel outil — ici illustré avec un simple `Calculator`. Le diagramme de séquence ci-dessous montre exactement ce qui se passe sous le capot : -Diagramme de séquence d'appel d'outils +Diagramme de séquence d’appel d’outil -*La boucle d’appel d’outils du démo Quick Start — `AiServices` envoie votre message et les schémas d’outils au LLM, le LLM répond par un appel de fonction comme `add(42, 58)`, LangChain4j exécute la méthode `Calculator` localement, et renvoie le résultat pour la réponse finale.* +*La boucle d’appel d’outil — `AiServices` envoie votre message et les schémas d’outils au LLM, le LLM répond avec un appel de fonction comme `add(42, 58)`, LangChain4j exécute localement la méthode du `Calculator`, puis renvoie le résultat pour la réponse finale.* -> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) et demandez : -> - « Comment fonctionne le pattern ReAct et pourquoi est-il efficace pour les agents IA ? » -> - « Comment l’agent décide quel outil utiliser et dans quel ordre ? » -> - « Que se passe-t-il si l’exécution d’un outil échoue - comment gérer les erreurs de manière robuste ? » +> **🤖 Essayez avec [GitHub Copilot](https://github.com/features/copilot) Chat :** Ouvrez [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) et demandez : +> - « Comment fonctionne le pattern ReAct et pourquoi est-il efficace pour les agents IA ? » +> - « Comment l’agent décide quel outil utiliser et dans quel ordre ? » +> - « Que se passe-t-il si l’exécution d’un outil échoue — comment gérer les erreurs de manière robuste ? » -### Génération de la réponse +### Génération de réponse Le modèle reçoit les données météo et les formate en une réponse en langage naturel pour l’utilisateur. -### Architecture : Auto-wiring Spring Boot +### Architecture : Auto-injection Spring Boot -Ce module utilise l’intégration LangChain4j avec Spring Boot via des interfaces déclaratives `@AiService`. Au démarrage, Spring Boot découvre chaque `@Component` contenant des méthodes `@Tool`, votre bean `ChatModel`, et le `ChatMemoryProvider` — puis les connecte tous dans une seule interface `Assistant` sans aucun code répétitif. +Ce module utilise l’intégration Spring Boot de LangChain4j avec des interfaces déclaratives `@AiService`. Au démarrage, Spring Boot découvre chaque `@Component` contenant des méthodes `@Tool`, votre bean `ChatModel` et le `ChatMemoryProvider` — puis les injecte tous dans une interface unique `Assistant` sans aucun code répétitif. -Architecture Auto-wiring Spring Boot +Architecture d’auto-injection Spring Boot -*L’interface @AiService relie le ChatModel, les composants outils, et le fournisseur mémoire — Spring Boot gère automatiquement tout le câblage.* +*L’interface @AiService relie le ChatModel, les composants d’outils et le fournisseur de mémoire — Spring Boot gère automatiquement toute l’injection.* -Voici le cycle complet d’une requête sous forme de diagramme de séquence — depuis la requête HTTP via le contrôleur, le service, le proxy auto-câblé, jusqu’à l’exécution de l’outil et le retour : +Voici le cycle complet d’une requête représenté en diagramme de séquence — de la requête HTTP au contrôleur, service et proxy auto-injecté, jusqu’à l’exécution de l’outil et retour : -Diagramme de séquence d'appel d'outil Spring Boot +Séquence d’appel d’outil Spring Boot -*Le cycle complet de la requête Spring Boot — la requête HTTP passe par le contrôleur et le service vers le proxy Assistant automonté, qui orchestre automatiquement le LLM et les appels aux outils.* +*Le cycle complet d’une requête Spring Boot — la requête HTTP transite par le contrôleur et le service vers le proxy Assistant auto-injecté, qui orchestre automatiquement le LLM et les appels d’outils.* Les avantages clés de cette approche : -- **Auto-wiring Spring Boot** — injection automatique du ChatModel et des outils -- **Pattern @MemoryId** — gestion automatique de la mémoire par session -- **Instance unique** — Assistant créé une fois pour une meilleure performance -- **Exécution typée** — méthodes Java appelées directement avec conversion de types -- **Orchestration multi-étapes** — gestion automatique du chaînage d’outils -- **Aucun code répétitif** — pas d’appel manuel à `AiServices.builder()` ni gestion explicite de HashMap mémoire +- **Auto-injection Spring Boot** — ChatModel et outils injectés automatiquement +- **Pattern @MemoryId** — Gestion automatique de la mémoire basée sur la session +- **Instance unique** — Assistant créé une fois et réutilisé pour de meilleures performances +- **Exécution typée** — Méthodes Java appelées directement avec conversion de types +- **Orchestration multi-tours** — Chaînage d’outils géré automatiquement +- **Zéro code répétitif** — Pas d’appels manuels à `AiServices.builder()` ou de HashMap mémoire -Les approches alternatives (manuelles via `AiServices.builder()`) nécessitent plus de code et ne profitent pas des avantages de Spring Boot. +Les approches alternatives (construction manuelle via `AiServices.builder()`) nécessitent plus de code et perdent les bénéfices de l’intégration Spring Boot. -## Chaînage d'outils +## Chaînage d’outils -**Chaînage d'outils** — La vraie puissance des agents basés sur des outils apparaît lorsqu’une seule question nécessite plusieurs outils. Demandez « Quelle est la météo à Seattle en Fahrenheit ? » et l’agent enchaîne automatiquement deux outils : d’abord il appelle `getCurrentWeather` pour obtenir la température en Celsius, puis il transmet cette valeur à `celsiusToFahrenheit` pour la conversion — tout cela en un seul tour de conversation. +**Chaînage d’outils** — La vraie puissance des agents basés sur outils se manifeste lorsqu’une seule question nécessite plusieurs outils. Demandez « Quelle est la météo à Seattle en Fahrenheit ? » et l’agent enchaîne automatiquement deux outils : il appelle d’abord `getCurrentWeather` pour obtenir la température en Celsius, puis transmet cette valeur à `celsiusToFahrenheit` pour la conversion — tout cela en un seul tour de conversation. -Exemple de chaînage d'outils +Exemple de chaînage d’outils -*Chaînage d’outils en action — l’agent appelle d’abord getCurrentWeather, puis passe le résultat en Celsius à celsiusToFahrenheit, et fournit une réponse combinée.* +*Chaînage d’outils en action — l’agent appelle d’abord getCurrentWeather, puis transmet le résultat en Celsius à celsiusToFahrenheit, et fournit une réponse combinée.* -**Gestion élégante des échecs** — Demandez la météo dans une ville qui n’est pas dans les données factices. L’outil renvoie un message d’erreur, et l’IA explique qu’elle ne peut pas aider au lieu de planter. Les outils échouent en toute sécurité. Le schéma ci-dessous contraste les deux approches — avec une gestion correcte des erreurs, l’agent intercepte l’exception et répond utilement, tandis que sans cela l’application entière plante : +**Échecs gracieux** — Demandez la météo dans une ville qui n’est pas dans les données simulées. L’outil renvoie un message d’erreur et l’IA explique qu’elle ne peut pas aider plutôt que de planter. Les outils échouent en toute sécurité. Le diagramme ci-dessous met en contraste les deux approches — avec une gestion correcte des erreurs, l’agent intercepte l’exception et répond utilement, tandis que sans elle l’application entière plante : -Flux de gestion des erreurs +Flux de gestion d’erreur -*Quand un outil échoue, l’agent attrape l’erreur et répond avec une explication utile au lieu de planter.* +*Quand un outil échoue, l’agent intercepte l’erreur et répond avec une explication utile au lieu de planter.* -Cela se déroule en un seul tour de conversation. L’agent orchestre les appels multiples aux outils de manière autonome. +Cela se passe en un seul tour de conversation. L’agent orchestre plusieurs appels d’outils de façon autonome. -## Lancer l'application +## Exécuter l’application **Vérifiez le déploiement :** -Assurez-vous que le fichier `.env` existe dans le répertoire racine avec les identifiants Azure (créé lors du Module 01). Lancez cette commande depuis le répertoire du module (`04-tools/`) : +Assurez-vous que le fichier `.env` existe dans le répertoire racine avec les identifiants Azure (créé pendant le Module 01). Exécutez ceci depuis le répertoire du module (`04-tools/`) : -**Bash :** +**Bash :** ```bash -cat ../.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Doit afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell :** +**PowerShell :** ```powershell -Get-Content ..\.env # Devrait afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Doit afficher AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` +**Démarrer l’application :** -**Démarrez l’application :** +> **Note :** Si vous avez déjà démarré toutes les applications via `./start-all.sh` depuis le répertoire racine (comme décrit dans le Module 01), ce module est déjà en cours d’exécution sur le port 8084. Vous pouvez sauter les commandes de démarrage ci-dessous et aller directement à http://localhost:8084. -> **Note :** Si vous avez déjà démarré toutes les applications avec `./start-all.sh` depuis le répertoire racine (comme décrit dans le Module 01), ce module tourne déjà sur le port 8084. Vous pouvez passer les commandes de démarrage ci-dessous et aller directement à http://localhost:8084. +**Option 1 : Utiliser le Spring Boot Dashboard (recommandé pour les utilisateurs de VS Code)** -**Option 1 : Utiliser le Spring Boot Dashboard (recommandé pour les utilisateurs VS Code)** +Le conteneur dev inclut l’extension Spring Boot Dashboard, qui offre une interface visuelle pour gérer toutes les applications Spring Boot. Vous pouvez la trouver dans la barre d’activités à gauche de VS Code (cherchez l’icône Spring Boot). -Le conteneur de développement inclut l’extension Spring Boot Dashboard, qui offre une interface visuelle pour gérer toutes les applications Spring Boot. Vous la trouverez dans la barre d’activités à gauche dans VS Code (cherchez l’icône Spring Boot). - -Depuis le Spring Boot Dashboard, vous pouvez : -- Voir toutes les applications Spring Boot disponibles dans l’espace de travail -- Démarrer/arrêter les applications en un clic -- Visualiser les logs des applications en temps réel +Depuis le Spring Boot Dashboard, vous pouvez : +- Voir toutes les applications Spring Boot disponibles dans l’espace de travail +- Démarrer/arrêter les applications d’un simple clic +- Consulter les logs applicatifs en temps réel - Surveiller le statut des applications -Il suffit de cliquer sur le bouton de lecture à côté de "tools" pour démarrer ce module, ou démarrer tous les modules en même temps. -Voici à quoi ressemble le Spring Boot Dashboard dans VS Code : +Cliquez simplement sur le bouton lecture à côté de "tools" pour démarrer ce module, ou lancez tous les modules en même temps. -Spring Boot Dashboard +Voici à quoi ressemble le Spring Boot Dashboard dans VS Code : +Tableau de bord Spring Boot -*Le Spring Boot Dashboard dans VS Code — démarrer, arrêter et surveiller tous les modules depuis un seul endroit* +*Le tableau de bord Spring Boot dans VS Code — démarrer, arrêter et surveiller tous les modules depuis un seul endroit* -**Option 2 : Utiliser des scripts shell** +**Option 2 : Utilisation de scripts shell** Démarrer toutes les applications web (modules 01-04) : @@ -259,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Les deux scripts chargent automatiquement les variables d’environnement à partir du fichier `.env` racine et construiront les JARs s’ils n’existent pas. +Les deux scripts chargent automatiquement les variables d'environnement depuis le fichier racine `.env` et construiront les JAR si ceux-ci n’existent pas. -> **Note :** Si vous préférez construire tous les modules manuellement avant de démarrer : +> **Note :** Si vous préférez construire manuellement tous les modules avant de démarrer : > > **Bash :** > ```bash @@ -281,7 +278,7 @@ Ouvrez http://localhost:8084 dans votre navigateur. **Bash :** ```bash -./stop.sh # Seulement ce module +./stop.sh # Ce module uniquement # Ou cd .. && ./stop-all.sh # Tous les modules ``` @@ -295,86 +292,86 @@ cd ..; .\stop-all.ps1 # Tous les modules ## Utilisation de l’Application -L’application fournit une interface web où vous pouvez interagir avec un agent IA qui a accès aux outils météo et de conversion de température. Voici à quoi ressemble l’interface — elle inclut des exemples rapides et un panneau de discussion pour envoyer des requêtes : +L’application fournit une interface web où vous pouvez interagir avec un agent IA ayant accès à des outils météo et de conversion de température. Voici à quoi ressemble l’interface — elle inclut des exemples de démarrage rapide et un panneau de chat pour envoyer des requêtes : -AI Agent Tools Interface +Interface des Outils de l’Agent IA -*L’interface des outils de l’agent IA - exemples rapides et interface de chat pour interagir avec les outils* +*L’interface des Outils de l’Agent IA - exemples rapides et interface de chat pour interagir avec les outils* -### Essayez l’utilisation simple d’un outil +### Essayez une Utilisation Simple des Outils -Commencez par une demande simple : « Convertir 100 degrés Fahrenheit en Celsius ». L’agent reconnaît qu’il a besoin de l’outil de conversion de température, l’appelle avec les bons paramètres et renvoie le résultat. Remarquez à quel point cela semble naturel — vous n’avez pas spécifié quel outil utiliser ni comment l’appeler. +Commencez par une requête simple : « Convertir 100 degrés Fahrenheit en Celsius ». L’agent reconnaît qu’il doit utiliser l’outil de conversion de température, l’appelle avec les bons paramètres et retourne le résultat. Notez à quel point c’est naturel — vous n’avez pas spécifié quel outil utiliser ni comment l’appeler. -### Testez la chaîne d’outils +### Testez le Chaînage d’Outils -Essayez maintenant quelque chose de plus complexe : « Quel temps fait-il à Seattle et convertis-le en Fahrenheit ? » Regardez l’agent traiter cela étape par étape. Il récupère d’abord la météo (qui renvoie en Celsius), reconnaît qu’il doit convertir en Fahrenheit, appelle l’outil de conversion, et combine les deux résultats en une seule réponse. +Essayez maintenant quelque chose de plus complexe : « Quel temps fait-il à Seattle et convertis-le en Fahrenheit ? » Regardez comment l’agent procède en étapes. Il récupère d’abord la météo (qui retourne en Celsius), reconnaît qu’il doit convertir en Fahrenheit, appelle l’outil de conversion, et combine les deux résultats en une seule réponse. -### Voir le déroulement de la conversation +### Voyez le Flux de Conversation -L’interface de chat garde l’historique des conversations, ce qui vous permet d’avoir des interactions à plusieurs tours. Vous pouvez voir toutes les requêtes et réponses précédentes, facilitant le suivi de la conversation et la compréhension de la manière dont l’agent construit le contexte au fil des échanges. +L’interface de chat conserve l’historique des conversations, vous permettant d’avoir des interactions multi-tours. Vous pouvez voir toutes les requêtes et réponses précédentes, ce qui facilite le suivi de la conversation et la compréhension de la manière dont l’agent construit le contexte au fil des échanges. -Conversation with Multiple Tool Calls +Conversation avec Appels Multiples d’Outils -*Conversation à plusieurs tours montrant des conversions simples, des recherches météo et des chaînes d’outils* +*Conversation multi-tours montrant des conversions simples, des recherches météo et le chaînage d’outils* -### Expérimentez avec différentes requêtes +### Expérimentez avec Différentes Requêtes -Essayez différentes combinaisons : +Essayez diverses combinaisons : - Recherches météo : « Quel temps fait-il à Tokyo ? » - Conversions de température : « Que vaut 25°C en Kelvin ? » -- Requêtes combinées : « Vérifie le temps à Paris et dis-moi s’il fait plus de 20°C » +- Requêtes combinées : « Vérifie la météo à Paris et dis-moi s’il fait plus de 20°C » -Observez comment l’agent interprète le langage naturel et le traduit en appels appropriés aux outils. +Notez comment l’agent interprète le langage naturel et le mappe à des appels appropriés aux outils. -## Concepts Clés +## Concepts clés -### Modèle ReAct (Raisonnement et Action) +### Modèle ReAct (Raisonner et Agir) -L’agent alterne entre le raisonnement (décider quoi faire) et l’action (utiliser les outils). Ce modèle permet une résolution autonome de problème plutôt que de simplement répondre à des instructions. +L’agent alterne entre raisonner (décider quoi faire) et agir (utiliser les outils). Ce modèle permet une résolution autonome de problèmes plutôt que de simplement répondre à des instructions. -### Les descriptions des outils comptent +### Les Descriptions d’Outils Comptent -La qualité de vos descriptions d’outils influence directement la qualité de leur utilisation par l’agent. Des descriptions claires et spécifiques aident le modèle à comprendre quand et comment appeler chaque outil. +La qualité des descriptions de vos outils influence directement la capacité de l’agent à les utiliser correctement. Des descriptions claires et spécifiques aident le modèle à comprendre quand et comment appeler chaque outil. -### Gestion de session +### Gestion de Session -L’annotation `@MemoryId` permet une gestion automatique de la mémoire basée sur la session. Chaque ID de session obtient sa propre instance de `ChatMemory` gérée par le bean `ChatMemoryProvider`, permettant à plusieurs utilisateurs d’interagir avec l’agent simultanément sans mélanger leurs conversations. Le schéma suivant montre comment plusieurs utilisateurs sont dirigés vers des mémoires isolées en fonction de leur ID de session : +L’annotation `@MemoryId` permet une gestion automatique de la mémoire basée sur la session. Chaque ID de session obtient sa propre instance `ChatMemory` gérée par le bean `ChatMemoryProvider`, permettant à plusieurs utilisateurs d’interagir simultanément avec l’agent sans mélange des conversations. Le diagramme suivant montre comment plusieurs utilisateurs sont dirigés vers des mémoires isolées basées sur leurs ID de session : -Session Management with @MemoryId +Gestion de session avec @MemoryId *Chaque ID de session correspond à un historique de conversation isolé — les utilisateurs ne voient jamais les messages des autres.* -### Gestion des erreurs +### Gestion des Erreurs -Les outils peuvent échouer — les API peuvent expirer, des paramètres peuvent être invalides, des services externes peuvent tomber en panne. Les agents en production ont besoin de gestion des erreurs pour que le modèle puisse expliquer les problèmes ou essayer des alternatives au lieu de faire planter toute l’application. Lorsqu’un outil lance une exception, LangChain4j la capte et renvoie le message d’erreur au modèle, qui peut alors expliquer le problème en langage naturel. +Les outils peuvent échouer — les API peuvent expirer, les paramètres être invalides, les services externes tomber en panne. Les agents de production ont besoin de gestion des erreurs pour que le modèle puisse expliquer les problèmes ou essayer des alternatives plutôt que de faire planter l’application entière. Lorsqu’un outil lance une exception, LangChain4j la capture et renvoie le message d’erreur au modèle, qui peut alors expliquer le problème en langage naturel. -## Outils Disponibles +## Outils disponibles -Le diagramme ci-dessous montre l’écosystème large d’outils que vous pouvez construire. Ce module démontre les outils météo et de température, mais le même modèle `@Tool` fonctionne pour n’importe quelle méthode Java — des requêtes de base de données au traitement des paiements. +Le diagramme ci-dessous montre l’écosystème étendu d’outils que vous pouvez construire. Ce module démontre des outils météo et de température, mais le même modèle `@Tool` fonctionne pour toute méthode Java — des requêtes de base de données au traitement des paiements. -Tool Ecosystem +Écosystème des Outils -*Toute méthode Java annotée avec @Tool devient disponible à l’IA — le modèle s’étend aux bases de données, APIs, e-mails, opérations sur fichiers, et plus.* +*Toute méthode Java annotée avec @Tool devient disponible pour l’IA — le modèle s’étend aux bases de données, APIs, e-mails, opérations de fichiers, et plus.* -## Quand utiliser des agents basés sur des outils +## Quand utiliser des agents basés sur les outils -Toutes les requêtes n’ont pas besoin d’outils. La décision dépend de si l’IA doit interagir avec des systèmes externes ou peut répondre avec ses propres connaissances. Le guide suivant résume quand les outils ajoutent de la valeur et quand ils sont inutiles : +Toutes les requêtes ne nécessitent pas d’outils. La décision dépend de si l’IA doit interagir avec des systèmes externes ou peut répondre à partir de sa propre connaissance. Le guide ci-dessous résume quand les outils apportent de la valeur et quand ils sont superflus : -When to Use Tools +Quand utiliser les outils -*Un guide de décision rapide — les outils servent aux données en temps réel, calculs et actions ; les connaissances générales et tâches créatives n’en ont pas besoin.* +*Un guide rapide de décision — les outils servent pour les données en temps réel, calculs et actions ; les connaissances générales et tâches créatives n’en ont pas besoin.* ## Outils vs RAG -Les modules 03 et 04 étendent tous deux ce que l’IA peut faire, mais de manière fondamentalement différente. RAG donne au modèle accès à la **connaissance** en récupérant des documents. Les outils permettent au modèle de prendre des **actions** en appelant des fonctions. Le diagramme ci-dessous compare ces deux approches côte à côte — du fonctionnement du workflow aux compromis entre elles : +Les modules 03 et 04 étendent tous deux les capacités de l’IA, mais de façons fondamentalement différentes. RAG donne au modèle accès à la **connaissance** en récupérant des documents. Les outils donnent au modèle la capacité de prendre des **actions** en appelant des fonctions. Le diagramme ci-dessous compare ces deux approches côte à côte — du fonctionnement des workflows aux compromis entre elles : -Tools vs RAG Comparison +Comparaison Outils vs RAG -*RAG récupère des informations à partir de documents statiques — Les outils exécutent des actions et récupèrent des données dynamiques en temps réel. Beaucoup de systèmes de production combinent les deux.* +*RAG récupère des informations depuis des documents statiques — les outils exécutent des actions et récupèrent des données dynamiques et en temps réel. Beaucoup de systèmes de production combinent les deux.* -En pratique, de nombreux systèmes de production combinent les deux approches : RAG pour ancrer les réponses dans votre documentation, et les outils pour récupérer des données en direct ou effectuer des opérations. +En pratique, nombreux sont les systèmes de production qui combinent les deux approches : RAG pour ancrer les réponses dans votre documentation, et Outils pour récupérer des données en direct ou réaliser des opérations. -## Étapes Suivantes +## Étapes suivantes **Module suivant :** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) @@ -385,6 +382,6 @@ En pratique, de nombreux systèmes de production combinent les deux approches : --- -**Avertissement** : -Ce document a été traduit à l’aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçons d’assurer l’exactitude, veuillez noter que les traductions automatiques peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue d’origine doit être considéré comme la source faisant foi. Pour des informations critiques, il est recommandé de recourir à une traduction humaine professionnelle. Nous déclinons toute responsabilité en cas de malentendus ou de mauvaises interprétations résultant de l’utilisation de cette traduction. +**Avertissement** : +Ce document a été traduit à l'aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçions d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue native doit être considéré comme la source faisant autorité. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous ne saurions être tenus responsables des malentendus ou erreurs d'interprétation découlant de l'utilisation de cette traduction. \ No newline at end of file diff --git a/translations/fr/README.md b/translations/fr/README.md index 3fe81f2ef..611729e00 100644 --- a/translations/fr/README.md +++ b/translations/fr/README.md @@ -2,7 +2,7 @@ # LangChain4j pour débutants -Un cours pour créer des applications IA avec LangChain4j et Azure OpenAI GPT-5.2, du chat basique aux agents IA. +Un cours pour construire des applications d'IA avec LangChain4j et Azure OpenAI GPT-5.2, du chat basique aux agents IA. ### 🌐 Support multilingue @@ -13,7 +13,7 @@ Un cours pour créer des applications IA avec LangChain4j et Azure OpenAI GPT-5. > **Préférez cloner localement ?** > -> Ce dépôt inclut plus de 50 traductions linguistiques ce qui augmente considérablement la taille du téléchargement. Pour cloner sans traductions, utilisez le sparse checkout : +> Ce dépôt comprend plus de 50 traductions de langues ce qui augmente significativement la taille du téléchargement. Pour cloner sans traductions, utilisez le sparse checkout : > > **Bash / macOS / Linux :** > ```bash @@ -29,26 +29,25 @@ Un cours pour créer des applications IA avec LangChain4j et Azure OpenAI GPT-5. > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Cela vous donne tout ce dont vous avez besoin pour compléter le cours avec un téléchargement bien plus rapide. +> Cela vous fournit tout ce dont vous avez besoin pour compléter le cours avec un téléchargement beaucoup plus rapide. ## Table des matières -1. [Démarrage rapide](00-quick-start/README.md) - Démarrez avec LangChain4j -2. [Introduction](01-introduction/README.md) - Apprenez les fondamentaux de LangChain4j -3. [Conception de prompt](02-prompt-engineering/README.md) - Maîtrisez la conception efficace de prompts -4. [RAG (Génération augmentée par récupération)](03-rag/README.md) - Créez des systèmes intelligents basés sur la connaissance -5. [Outils](04-tools/README.md) - Intégrez des outils externes et assistants simples -6. [MCP (Protocole de Contexte Modèle)](05-mcp/README.md) - Travaillez avec le Protocole de Contexte Modèle (MCP) et les modules Agentiques +1. [Introduction](01-introduction/README.md) - Apprenez les fondamentaux de LangChain4j +2. [Ingénierie de prompt](02-prompt-engineering/README.md) - Maîtrisez la conception efficace de prompt +3. [RAG (Récupération Augmentée par la Génération)](03-rag/README.md) - Construisez des systèmes intelligents basés sur la connaissance +4. [Outils](04-tools/README.md) - Intégrez des outils externes et assistants simples +5. [MCP (Protocole de Contexte de Modèle)](05-mcp/README.md) - Travaillez avec le Protocole de Contexte de Modèle (MCP) et les modules Agentic ### Vidéos explicatives -Chaque module est accompagné d'une session en direct où nous parcourons les concepts et le code étape par étape. +Chaque module a une session en direct associée où nous parcourons les concepts et le code pas à pas. | Module | Vidéo | |--------|-------| -| 01 - Introduction | [Premiers pas avec LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Conception de prompt | [Conception de prompt avec LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - Introduction | [Commencer avec LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Ingénierie de prompt | [Ingénierie de prompt avec LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG avec LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Outils & 05 - MCP | [Agents IA avec Outils et MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | @@ -60,29 +59,30 @@ Chaque module est accompagné d'une session en direct où nous parcourons les co > **Démarrage rapide** -1. Forkez ce dépôt vers votre compte GitHub -2. Cliquez sur **Code** → onglet **Codespaces** → **...** → **Nouveau avec options...** +1. Forkez ce dépôt sur votre compte GitHub +2. Cliquez sur **Code** → l’onglet **Codespaces** → **...** → **Nouveau avec options...** 3. Utilisez les paramètres par défaut – cela sélectionnera le conteneur de développement créé pour ce cours -4. Cliquez sur **Créer codespace** -5. Patientez 5-10 minutes que l'environnement soit prêt -6. Allez directement à [Démarrage rapide](./00-quick-start/README.md) pour commencer ! +4. Cliquez sur **Créer un codespace** +5. Attendez 5 à 10 minutes pour que l’environnement soit prêt +6. Passez directement à [Introduction](./01-introduction/README.md) pour commencer ! Après avoir complété les modules, explorez le [Guide de test](docs/TESTING.md) pour voir les concepts de test LangChain4j en action. -> **Note :** Cette formation utilise à la fois les modèles GitHub et Azure OpenAI. Le module [Démarrage rapide](00-quick-start/README.md) utilise les modèles GitHub (abonnement Azure non requis), tandis que les modules 1 à 5 utilisent Azure OpenAI. Commencez avec un [compte Azure GRATUIT](https://aka.ms/azure-free-account) si vous n'en avez pas. +> **Note :** Cette formation utilise Azure OpenAI. Commencez avec un [compte Azure GRATUIT](https://aka.ms/azure-free-account) si vous n’en avez pas. + ## Apprentissage avec GitHub Copilot -Pour coder rapidement, ouvrez ce projet dans un GitHub Codespace ou votre IDE local avec le devcontainer fourni. Le devcontainer utilisé dans ce cours est préconfiguré avec GitHub Copilot pour une programmation assistée IA en binôme. +Pour démarrer rapidement votre codage, ouvrez ce projet dans un GitHub Codespace ou votre IDE local avec le devcontainer fourni. Le devcontainer utilisé dans ce cours est préconfiguré avec GitHub Copilot pour la programmation assistée par IA. -Chaque exemple de code inclut des questions suggérées que vous pouvez poser à GitHub Copilot pour approfondir votre compréhension. Cherchez les invites 💡/🤖 dans : +Chaque exemple de code inclut des questions suggérées que vous pouvez poser à GitHub Copilot pour approfondir votre compréhension. Recherchez les invites 💡/🤖 dans : -- **En-têtes de fichiers Java** - Questions spécifiques à chaque exemple -- **README des modules** - Invites d'exploration après les exemples de code +- **En-têtes de fichiers Java** – Questions spécifiques à chaque exemple +- **README des modules** – Invites d’exploration après les exemples de code -**Comment utiliser :** Ouvrez n'importe quel fichier de code et posez à Copilot les questions suggérées. Il a le contexte complet du code et peut expliquer, étendre et suggérer des alternatives. +**Comment utiliser :** Ouvrez n’importe quel fichier de code et posez à Copilot les questions suggérées. Il a le contexte complet du code et peut expliquer, étendre et suggérer des alternatives. -Envie d'en savoir plus ? Découvrez [Copilot pour la programmation assistée IA](https://aka.ms/GitHubCopilotAI). +Vous souhaitez en savoir plus ? Consultez [Copilot pour la programmation assistée par IA](https://aka.ms/GitHubCopilotAI). ## Ressources supplémentaires @@ -110,19 +110,19 @@ Envie d'en savoir plus ? Découvrez [Copilot pour la programmation assistée IA] --- -### Apprentissages fondamentaux +### Apprentissage fondamental [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Cybersécurité pour débutants](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Développement Web pour débutants](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT pour débutants](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![Développement XR pour débutants](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Développement Web pour Débutants](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT pour Débutants](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![Développement XR pour Débutants](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Série Copilot -[![Copilot pour la programmation assistée par IA](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot pour Programmation Assistée par IA](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![Copilot pour C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![Aventure Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) @@ -133,7 +133,7 @@ Si vous êtes bloqué ou avez des questions sur la création d'applications IA, [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Si vous avez des retours produit ou des erreurs lors de la création, visitez : +Si vous avez des retours sur le produit ou des erreurs lors de la création, visitez : [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) @@ -144,6 +144,6 @@ Licence MIT - Voir le fichier [LICENSE](../../LICENSE) pour plus de détails. --- -**Avertissement** : -Ce document a été traduit à l’aide du service de traduction automatisée [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçions d’assurer l’exactitude, veuillez noter que les traductions automatiques peuvent contenir des erreurs ou des imprécisions. Le document original dans sa langue native doit être considéré comme la source faisant foi. Pour les informations critiques, une traduction professionnelle humaine est recommandée. Nous déclinons toute responsabilité en cas de malentendus ou de mauvaises interprétations résultant de l’utilisation de cette traduction. +**Avertissement** : +Ce document a été traduit à l'aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçions d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue native doit être considéré comme la source faisant autorité. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous ne saurions être tenus responsables des malentendus ou erreurs d'interprétation découlant de l'utilisation de cette traduction. \ No newline at end of file diff --git a/translations/fr/docs/GLOSSARY.md b/translations/fr/docs/GLOSSARY.md index 1fb902dc1..aa701735a 100644 --- a/translations/fr/docs/GLOSSARY.md +++ b/translations/fr/docs/GLOSSARY.md @@ -1,186 +1,186 @@ -# LangChain4j Glossaire +# Glossaire LangChain4j -## Table des Matières +## Table des matières -- [Concepts de Base](../../../docs) -- [Composants LangChain4j](../../../docs) -- [Concepts AI/ML](../../../docs) -- [Guardrails](../../../docs) -- [Ingénierie des Prompts](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agents et Outils](../../../docs) -- [Module Agentique](../../../docs) -- [Protocole de Contexte Modèle (MCP)](../../../docs) -- [Services Azure](../../../docs) -- [Tests et Développement](../../../docs) +- [Concepts de base](#concepts-de-base) +- [Composants LangChain4j](#composants-langchain4j) +- [Concepts IA/ML](#concepts-iaml) +- [Garde-fous](#garde-fous) +- [Ingénierie des prompts](#prompt-engineering---module-02) +- [RAG (Génération augmentée par récupération)](#rag-retrieval-augmented-generation---module-03) +- [Agents et Outils](#agents-and-tools---module-04) +- [Module Agentique](#agentic-module---module-05) +- [Protocole de Contexte de Modèle (MCP)](#model-context-protocol-mcp---module-05) +- [Services Azure](#azure-services---module-01) +- [Tests et Développement](#testing-and-development---testing-guide) -Référence rapide pour les termes et concepts utilisés tout au long du cours. +Référence rapide des termes et concepts utilisés tout au long du cours. -## Concepts de Base +## Concepts de base -**Agent IA** - Système utilisant l'IA pour raisonner et agir de manière autonome. [Module 04](../04-tools/README.md) +**Agent IA** - Système qui utilise l'IA pour raisonner et agir de manière autonome. [Module 04](../04-tools/README.md) **Chaîne** - Séquence d'opérations où la sortie alimente l'étape suivante. -**Découpage** - Fragmenter les documents en morceaux plus petits. Typiquement : 300-500 tokens avec chevauchement. [Module 03](../03-rag/README.md) +**Chunking** - Découpage des documents en morceaux plus petits. Typique : 300-500 tokens avec chevauchement. [Module 03](../03-rag/README.md) -**Fenêtre de Contexte** - Nombre maximal de tokens qu'un modèle peut traiter. GPT-5.2 : 400K tokens (jusqu'à 272K en entrée, 128K en sortie). +**Fenêtre de contexte** - Nombre maximal de tokens qu'un modèle peut traiter. GPT-5.2 : 400K tokens (jusqu'à 272K en entrée, 128K en sortie). -**Embeddings** - Vecteurs numériques représentant la signification du texte. [Module 03](../03-rag/README.md) +**Embeddings** - Vecteurs numériques représentant le sens du texte. [Module 03](../03-rag/README.md) -**Appel de Fonction** - Le modèle génère des requêtes structurées pour appeler des fonctions externes. [Module 04](../04-tools/README.md) +**Appel de fonction** - Le modèle génère des requêtes structurées pour appeler des fonctions externes. [Module 04](../04-tools/README.md) -**Hallucination** - Quand les modèles génèrent des informations incorrectes mais plausibles. +**Hallucination** - Lorsque les modèles génèrent des informations incorrectes mais plausibles. -**Prompt** - Texte d’entrée donné à un modèle de langage. [Module 02](../02-prompt-engineering/README.md) +**Prompt** - Texte d'entrée pour un modèle de langage. [Module 02](../02-prompt-engineering/README.md) -**Recherche Sémantique** - Recherche par signification utilisant des embeddings, pas des mots-clés. [Module 03](../03-rag/README.md) +**Recherche sémantique** - Recherche par sens utilisant des embeddings, pas des mots-clés. [Module 03](../03-rag/README.md) -**Avec état vs Sans état** - Sans état : pas de mémoire. Avec état : maintien de l’historique de la conversation. [Module 01](../01-introduction/README.md) +**Sans état vs avec état** - Sans état : pas de mémoire. Avec état : conserve l'historique de la conversation. [Module 01](../01-introduction/README.md) -**Tokens** - Unités de texte de base traitées par les modèles. Impacte les coûts et les limites. [Module 01](../01-introduction/README.md) +**Tokens** - Unités de texte de base que les modèles traitent. Impacte coûts et limites. [Module 01](../01-introduction/README.md) -**Chaînage d’Outils** - Exécution séquentielle d’outils où la sortie informe l’appel suivant. [Module 04](../04-tools/README.md) +**Chaînage d'outils** - Exécution séquentielle d'outils où la sortie informe l'appel suivant. [Module 04](../04-tools/README.md) ## Composants LangChain4j -**AiServices** - Crée des interfaces de services IA typées. +**AiServices** - Crée des interfaces de service IA typées. -**OpenAiOfficialChatModel** - Client unifié pour les modèles OpenAI et Azure OpenAI. +**OpenAiOfficialChatModel** - Client unifié pour modèles OpenAI et Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Crée des embeddings utilisant le client officiel OpenAI (supporte OpenAI et Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Crée des embeddings via le client officiel OpenAI (supporte OpenAI et Azure OpenAI). -**ChatModel** - Interface centrale pour les modèles de langage. +**ChatModel** - Interface principale pour les modèles de langage. -**ChatMemory** - Maintient l’historique des conversations. +**ChatMemory** - Conserve l'historique de la conversation. -**ContentRetriever** - Trouve des fragments documents pertinents pour RAG. +**ContentRetriever** - Trouve des morceaux de documents pertinents pour RAG. -**DocumentSplitter** - Divise les documents en fragments. +**DocumentSplitter** - Découpe les documents en chunks. **EmbeddingModel** - Convertit le texte en vecteurs numériques. -**EmbeddingStore** - Stocke et récupère des embeddings. +**EmbeddingStore** - Stocke et récupère les embeddings. **MessageWindowChatMemory** - Maintient une fenêtre glissante des messages récents. **PromptTemplate** - Crée des prompts réutilisables avec des espaces réservés `{{variable}}`. -**TextSegment** - Fragment de texte avec métadonnées. Utilisé en RAG. +**TextSegment** - Morceau de texte avec métadonnées. Utilisé dans RAG. -**ToolExecutionRequest** - Représente une requête d'exécution d'outil. +**ToolExecutionRequest** - Représente une requête d’exécution d’outil. **UserMessage / AiMessage / SystemMessage** - Types de messages de conversation. -## Concepts AI/ML +## Concepts IA/ML -**Apprentissage Few-Shot** - Fournir des exemples dans les prompts. [Module 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Fournir des exemples dans les prompts. [Module 02](../02-prompt-engineering/README.md) -**Grand Modèle de Langage (LLM)** - Modèles IA entraînés sur d’immenses volumes de texte. +**Large Language Model (LLM)** - Modèles IA entraînés sur de vastes données textuelles. -**Effort de Raisonnement** - Paramètre GPT-5.2 contrôlant la profondeur de la réflexion. [Module 02](../02-prompt-engineering/README.md) +**Effort de raisonnement** - Paramètre GPT-5.2 contrôlant la profondeur de réflexion. [Module 02](../02-prompt-engineering/README.md) -**Température** - Contrôle la variabilité des sorties. Faible = déterministe, élevé = créatif. +**Température** - Contrôle l’aléatoire des sorties. Faible = déterministe, élevé = créatif. -**Base de Données Vectorielle** - Base spécialisée pour les embeddings. [Module 03](../03-rag/README.md) +**Base de données vectorielle** - Base de données spécialisée pour les embeddings. [Module 03](../03-rag/README.md) -**Apprentissage Zero-Shot** - Effectuer des tâches sans exemples. [Module 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Réaliser des tâches sans exemples. [Module 02](../02-prompt-engineering/README.md) -## Guardrails - [Module 00](../00-quick-start/README.md) +## Garde-fous -**Défense en Profondeur** - Approche de sécurité multi-couches combinant guardrails applicatifs et filtres de sécurité fournisseur. +**Défense en profondeur** - Approche de sécurité multi-couches combinant garde-fous applicatifs et filtres de sécurité du fournisseur. -**Blocage Strict** - Le fournisseur retourne une erreur HTTP 400 pour violations graves de contenu. +**Blocage dur** - Le fournisseur renvoie une erreur HTTP 400 pour des violations sévères de contenu. -**InputGuardrail** - Interface LangChain4j pour valider la saisie utilisateur avant qu'elle n'atteigne le LLM. Économise coûts et latence en bloquant tôt les prompts nuisibles. +**InputGuardrail** - Interface LangChain4j pour valider les entrées utilisateurs avant qu'elles n’atteignent le LLM. Économise coûts et latence en bloquant tôt les prompts nuisibles. -**InputGuardrailResult** - Type de retour pour la validation guardrail : `success()` ou `fatal("raison")`. +**InputGuardrailResult** - Type de retour pour validation des garde-fous : `success()` ou `fatal("raison")`. -**OutputGuardrail** - Interface pour valider les réponses IA avant de les retourner aux utilisateurs. +**OutputGuardrail** - Interface pour valider les réponses IA avant de les renvoyer aux utilisateurs. -**Filtres de Sécurité Fournisseur** - Filtres intégrés fournis par les fournisseurs d’IA (ex. GitHub Models) qui détectent les violations au niveau API. +**Filtres de sécurité du fournisseur** - Filtres de contenu intégrés des fournisseurs d’IA (ex : Azure OpenAI) qui interceptent les violations au niveau de l’API. -**Refus Doux** - Le modèle refuse poliment de répondre sans générer d’erreur. +**Refus doux** - Le modèle décline poliment de répondre sans générer d’erreur. -## Ingénierie des Prompts - [Module 02](../02-prompt-engineering/README.md) +## Ingénierie des prompts - [Module 02](../02-prompt-engineering/README.md) -**Chaîne de Raisonnement** - Raisonnement étape par étape pour une meilleure précision. +**Chaîne de pensée (Chain-of-Thought)** - Raisonnement étape par étape pour plus de précision. -**Sortie Contraint** - Imposer un format ou une structure spécifique. +**Sortie contrainte** - Application d’un format ou structure spécifiques. -**Forte Volonté** - Patron GPT-5.2 pour un raisonnement approfondi. +**Forte motivation** - Modèle GPT-5.2 pour un raisonnement approfondi. -**Faible Volonté** - Patron GPT-5.2 pour des réponses rapides. +**Faible motivation** - Modèle GPT-5.2 pour des réponses rapides. -**Conversation Multi-Tours** - Maintien du contexte sur plusieurs échanges. +**Conversation multi-tours** - Maintien du contexte à travers les échanges. -**Prompting Basé sur les Rôles** - Définir la persona du modèle via des messages système. +**Prompting basé sur les rôles** - Définir la persona du modèle via des messages système. -**Autoréflexion** - Le modèle évalue et améliore ses propres sorties. +**Auto-réflexion** - Le modèle évalue et améliore sa sortie. -**Analyse Structurée** - Cadre d’évaluation fixe. +**Analyse structurée** - Cadre d’évaluation fixe. -**Patron d’Exécution de Tâche** - Planifier → Exécuter → Résumer. +**Modèle d’exécution de tâche** - Planifier → Exécuter → Résumer. -## RAG (Retrieval-Augmented Generation) - [Module 03](../03-rag/README.md) +## RAG (Génération augmentée par récupération) - [Module 03](../03-rag/README.md) -**Pipeline de Traitement de Document** - Charger → découper → encoder → stocker. +**Pipeline de traitement documentaire** - Charger → découper → créer embeddings → stocker. -**Magasin d’Embeddings en Mémoire** - Stockage non persistant pour les tests. +**Stockage d’embeddings en mémoire** - Stockage non persistant pour tests. -**RAG** - Combine la récupération avec la génération pour ancrer les réponses. +**RAG** - Combine récupération et génération pour ancrer les réponses. -**Score de Similarité** - Mesure (0-1) de similarité sémantique. +**Score de similarité** - Mesure (0-1) de similitude sémantique. -**Référence Source** - Métadonnées sur le contenu récupéré. +**Référence source** - Métadonnées sur le contenu récupéré. ## Agents et Outils - [Module 04](../04-tools/README.md) **Annotation @Tool** - Marque les méthodes Java comme outils appelables par l’IA. -**Patron ReAct** - Raisonner → Agir → Observer → Répéter. +**Modèle ReAct** - Raisonner → Agir → Observer → Répéter. -**Gestion de Session** - Contextes séparés pour différents utilisateurs. +**Gestion de session** - Contextes séparés pour différents utilisateurs. **Outil** - Fonction qu’un agent IA peut appeler. -**Description d’Outil** - Documentation sur l’usage et les paramètres de l’outil. +**Description d’outil** - Documentation sur la finalité et les paramètres de l’outil. ## Module Agentique - [Module 05](../05-mcp/README.md) -**Annotation @Agent** - Marque les interfaces comme agents IA avec définition de comportement déclarative. +**Annotation @Agent** - Marque les interfaces comme agents IA avec définition déclarative du comportement. -**Agent Listener** - Crochet pour surveiller l’exécution agent via `beforeAgentInvocation()` et `afterAgentInvocation()`. +**Agent Listener** - Hook pour surveiller l’exécution d’un agent via `beforeAgentInvocation()` et `afterAgentInvocation()`. -**Portée Agentique** - Mémoire partagée où les agents stockent leurs sorties sous `outputKey` pour consommation par d’autres agents. +**Portée agentique** - Mémoire partagée où les agents stockent des sorties avec `outputKey` pour consommation par d’autres agents. -**AgenticServices** - Fabrique pour créer des agents via `agentBuilder()` et `supervisorBuilder()`. +**AgenticServices** - Usine pour créer des agents avec `agentBuilder()` et `supervisorBuilder()`. -**Flux Conditionnel** - Dirige selon des conditions vers différents agents spécialistes. +**Workflow conditionnel** - Routage basé sur conditions vers différents agents spécialistes. -**Humain dans la Boucle** - Patron de flux ajoutant des points de contrôle humains pour approbation ou revue de contenu. +**Humain dans la boucle** - Pattern avec étapes humaines pour approbation ou revue de contenu. **langchain4j-agentic** - Dépendance Maven pour construction déclarative d’agents (expérimental). -**Boucle de Flux** - Itérer l’exécution de l’agent jusqu’à ce qu’une condition soit remplie (ex. score qualité ≥ 0.8). +**Workflow en boucle** - Itérer l’exécution d’un agent jusqu’à ce qu’une condition soit satisfaite (ex : score qualité ≥ 0.8). -**outputKey** - Paramètre d’annotation agent définissant où les résultats sont stockés dans la Portée Agentique. +**outputKey** - Paramètre d’annotation agent indiquant où stocker les résultats dans la portée agentique. -**Flux Parallèle** - Exécuter plusieurs agents simultanément pour des tâches indépendantes. +**Workflow parallèle** - Exécuter plusieurs agents simultanément pour tâches indépendantes. -**Stratégie de Réponse** - Façon dont le superviseur formule la réponse finale : LAST, SUMMARY, ou SCORED. +**Stratégie de réponse** - Manière dont le superviseur formule la réponse finale : LAST, SUMMARY, ou SCORED. -**Flux Séquentiel** - Exécuté agents en ordre où la sortie alimente l’étape suivante. +**Workflow séquentiel** - Exécuter les agents dans l’ordre où la sortie alimente l’étape suivante. -**Patron Agent Superviseur** - Patron agentique avancé où un LLM superviseur décide dynamiquement quels sous-agents invoquer. +**Modèle d’agent superviseur** - Pattern agentique avancé où un superviseur LLM décide dynamiquement quels sous-agents invoquer. -## Protocole de Contexte Modèle (MCP) - [Module 05](../05-mcp/README.md) +## Protocole de Contexte de Modèle (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - Dépendance Maven pour intégration MCP dans LangChain4j. +**langchain4j-mcp** - Dépendance Maven pour l’intégration MCP dans LangChain4j. -**MCP** - Protocole de Contexte Modèle : standard pour connecter les applis IA à des outils externes. Construire une fois, utiliser partout. +**MCP** - Protocole de Contexte de Modèle : standard pour connecter les applications IA à des outils externes. Construire une fois, utiliser partout. -**Client MCP** - Application qui se connecte aux serveurs MCP pour découvrir et utiliser les outils. +**Client MCP** - Application qui se connecte aux serveurs MCP pour découvrir et utiliser des outils. **Serveur MCP** - Service exposant des outils via MCP avec descriptions claires et schémas de paramètres. @@ -188,37 +188,35 @@ Référence rapide pour les termes et concepts utilisés tout au long du cours. **McpTransport** - Interface pour communication MCP. Implémentations incluent Stdio et HTTP. -**Transport Stdio** - Transport local par processus via stdin/stdout. Utile pour accès système de fichiers ou outils ligne de commande. +**Transport Stdio** - Transport de processus local via stdin/stdout. Utile pour accès système de fichiers ou outils en ligne de commande. **StdioMcpTransport** - Implémentation LangChain4j lançant le serveur MCP en sous-processus. -**Découverte d’Outils** - Client interroge le serveur pour les outils disponibles avec descriptions et schémas. +**Découverte d’outils** - Le client interroge le serveur pour les outils disponibles avec descriptions et schémas. ## Services Azure - [Module 01](../01-introduction/README.md) **Azure AI Search** - Recherche cloud avec capacités vectorielles. [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Déploie des ressources Azure. +**Azure Developer CLI (azd)** - Déploie les ressources Azure. -**Azure OpenAI** - Service IA entreprise de Microsoft. +**Azure OpenAI** - Service IA d’entreprise de Microsoft. -**Bicep** - Langage d’infrastructure Azure-as-code. [Guide Infrastructure](../01-introduction/infra/README.md) +**Bicep** - Langage infrastructure-as-code Azure. [Guide Infrastructure](../01-introduction/infra/README.md) -**Nom de Déploiement** - Nom du déploiement modèle dans Azure. +**Nom de déploiement** - Nom pour le déploiement du modèle dans Azure. **GPT-5.2** - Dernier modèle OpenAI avec contrôle du raisonnement. [Module 02](../02-prompt-engineering/README.md) -## Tests et Développement - [Guide de Tests](TESTING.md) +## Tests et Développement - [Guide de tests](TESTING.md) -**Dev Container** - Environnement de développement containerisé. [Configuration](../../../.devcontainer/devcontainer.json) +**Dev Container** - Environnement de développement conteneurisé. [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Terrain de jeu AI modèle gratuit. [Module 00](../00-quick-start/README.md) +**Tests en mémoire** - Tests avec stockage en mémoire. -**Test en Mémoire** - Tests avec stockage en mémoire. +**Tests d’intégration** - Tests avec infrastructure réelle. -**Tests d’Intégration** - Tests avec infrastructure réelle. - -**Maven** - Outil d’automatisation de construction Java. +**Maven** - Outil d’automatisation de build Java. **Mockito** - Framework de moquage Java. @@ -227,6 +225,6 @@ Référence rapide pour les termes et concepts utilisés tout au long du cours. --- -**Avis de non-responsabilité** : -Ce document a été traduit à l'aide du service de traduction par IA [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçons d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue native doit être considéré comme la source faisant foi. Pour les informations critiques, une traduction professionnelle réalisée par un humain est recommandée. Nous déclinons toute responsabilité en cas de malentendus ou de mauvaises interprétations résultant de l'utilisation de cette traduction. +**Avertissement** : +Ce document a été traduit à l'aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçions d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue native doit être considéré comme la source faisant autorité. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous ne saurions être tenus responsables des malentendus ou erreurs d'interprétation découlant de l'utilisation de cette traduction. \ No newline at end of file diff --git a/translations/fr/docs/TESTING.md b/translations/fr/docs/TESTING.md index 0e1e4f45e..99734fbc4 100644 --- a/translations/fr/docs/TESTING.md +++ b/translations/fr/docs/TESTING.md @@ -2,19 +2,19 @@ ## Table des matières -- [Démarrage rapide](../../../docs) -- [Ce que couvrent les tests](../../../docs) -- [Exécuter les tests](../../../docs) -- [Exécuter les tests dans VS Code](../../../docs) -- [Modèles de test](../../../docs) -- [Philosophie de test](../../../docs) -- [Étapes suivantes](../../../docs) +- [Démarrage rapide](#démarrage-rapide) +- [Ce que couvrent les tests](#ce-que-couvrent-les-tests) +- [Exécution des tests](#exécution-des-tests) +- [Exécution des tests dans VS Code](#exécution-des-tests-dans-vs-code) +- [Modèles de test](#modèles-de-test) +- [Philosophie de test](#philosophie-de-test) +- [Étapes suivantes](#étapes-suivantes) -Ce guide vous guide à travers les tests qui démontrent comment tester des applications d'IA sans nécessiter de clés API ou de services externes. +Ce guide vous accompagne à travers les tests qui démontrent comment tester des applications IA sans nécessiter de clés API ou de services externes. ## Démarrage rapide -Exécutez tous les tests avec une seule commande : +Exécutez tous les tests avec une seule commande : **Bash :** ```bash @@ -26,30 +26,29 @@ mvn test mvn --% test ``` -Lorsque tous les tests réussissent, vous devriez voir une sortie comme la capture d’écran ci-dessous — les tests s'exécutent sans aucune erreur. +Lorsque tous les tests réussissent, vous devriez voir une sortie similaire à la capture d'écran ci-dessous — les tests s'exécutent sans aucune erreur. -Résultats des tests réussis +Successful Test Results -*Exécution réussie des tests montrant que tous les tests passent sans aucune erreur* +*Exécution réussie des tests montrant que tous les tests sont passés sans aucune erreur* ## Ce que couvrent les tests -Ce cours se concentre sur les **tests unitaires** qui s'exécutent localement. Chaque test démontre un concept spécifique de LangChain4j isolément. La pyramide de test ci-dessous montre où s’insèrent les tests unitaires — ils forment la base rapide et fiable sur laquelle le reste de votre stratégie de test s’appuie. +Ce cours se concentre sur les **tests unitaires** qui s'exécutent localement. Chaque test démontre un concept spécifique de LangChain4j isolément. La pyramide de tests ci-dessous montre où s'inscrivent les tests unitaires — ils forment la base rapide et fiable sur laquelle le reste de votre stratégie de test se construit. -Pyramide de test +Testing Pyramid -*Pyramide de test montrant l’équilibre entre les tests unitaires (rapides, isolés), les tests d’intégration (composants réels) et les tests de bout en bout. Cette formation couvre les tests unitaires.* +*Pyramide de tests montrant l'équilibre entre tests unitaires (rapides, isolés), tests d'intégration (composants réels) et tests de bout en bout. Cette formation couvre les tests unitaires.* | Module | Tests | Focus | Fichiers clés | |--------|-------|-------|---------------| -| **00 - Démarrage rapide** | 6 | Modèles d'invite et substitution de variables | `SimpleQuickStartTest.java` | | **01 - Introduction** | 8 | Mémoire de conversation et chat avec état | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | Patterns GPT-5.2, niveaux d’empressement, sortie structurée | `SimpleGpt5PromptTest.java` | +| **02 - Prompt Engineering** | 12 | Modèles GPT-5.2, niveaux d'empressement, sortie structurée | `SimpleGpt5PromptTest.java` | | **03 - RAG** | 10 | Ingestion de documents, embeddings, recherche de similarité | `DocumentServiceTest.java` | -| **04 - Outils** | 12 | Appels de fonctions et chaînage d’outils | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Protocole Model Context avec transport Stdio | `SimpleMcpTest.java` | +| **04 - Outils** | 12 | Appels de fonctions et chaînage d'outils | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Protocole de contexte de modèle avec transport Stdio | `SimpleMcpTest.java` | -## Exécuter les tests +## Exécution des tests **Exécuter tous les tests depuis la racine :** @@ -95,41 +94,41 @@ mvn --% test -Dtest=SimpleConversationTest **Bash :** ```bash -mvn test -Dtest=SimpleConversationTest#doitMaintenirLHistoriqueDeLaConversation +mvn test -Dtest=SimpleConversationTest#devraitMaintenirLHistoriqueDeConversation ``` **PowerShell :** ```powershell -mvn --% test -Dtest=SimpleConversationTest#doitMaintenirLHistoriqueDeConversation +mvn --% test -Dtest=SimpleConversationTest#doitMaintenirLhistoriqueDeLaConversation ``` -## Exécuter les tests dans VS Code +## Exécution des tests dans VS Code -Si vous utilisez Visual Studio Code, l’Explorateur de tests fournit une interface graphique pour exécuter et déboguer les tests. +Si vous utilisez Visual Studio Code, l'Explorateur de tests offre une interface graphique pour exécuter et déboguer les tests. -Explorateur de tests VS Code +VS Code Test Explorer -*Explorateur de tests VS Code montrant l’arbre des tests avec toutes les classes de test Java et les méthodes de test individuelles* +*Explorateur de tests VS Code affichant l'arbre des tests avec toutes les classes de test Java et les méthodes de test individuelles* -**Pour exécuter les tests dans VS Code :** +**Pour exécuter les tests dans VS Code :** -1. Ouvrez l’Explorateur de tests en cliquant sur l’icône du bécher dans la barre d’activité -2. Développez l’arbre des tests pour voir tous les modules et classes de test -3. Cliquez sur le bouton de lecture à côté de n’importe quel test pour l’exécuter individuellement -4. Cliquez sur « Exécuter tous les tests » pour lancer l’ensemble de la suite -5. Faites un clic droit sur un test et sélectionnez « Déboguer le test » pour définir des points d’arrêt et parcourir le code +1. Ouvrez l'Explorateur de tests en cliquant sur l'icône du bécher dans la barre d'activité +2. Développez l'arbre des tests pour voir tous les modules et classes de test +3. Cliquez sur le bouton lecture à côté de n'importe quel test pour l'exécuter individuellement +4. Cliquez sur "Run All Tests" pour exécuter toute la suite +5. Faites un clic droit sur un test et sélectionnez "Debug Test" pour placer des points d'arrêt et avancer dans le code -L’Explorateur de tests affiche des coches vertes pour les tests réussis et fournit des messages d’échec détaillés lorsque les tests échouent. +L'Explorateur de tests affiche des coches vertes pour les tests réussis et fournit des messages d'erreur détaillés en cas d'échec. ## Modèles de test -### Modèle 1 : Tester les modèles d'invite +### Modèle 1 : Tester les modèles de prompts -Le modèle le plus simple teste les modèles d’invite sans appeler de modèle IA. Vous vérifiez que la substitution de variables fonctionne correctement et que les invites sont formatées comme prévu. +Le modèle le plus simple teste les modèles de prompts sans appeler de modèle IA. Vous vérifiez que la substitution des variables fonctionne correctement et que les prompts sont formatés comme prévu. -Test des modèles d'invite +Prompt Template Testing -*Test des modèles d’invite montrant le flux de substitution de variables : modèle avec espaces réservés → valeurs appliquées → sortie formatée vérifiée* +*Test des modèles de prompts montrant le flux de substitution des variables : modèle avec espaces réservés → valeurs appliquées → sortie formatée vérifiée* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Ce test se trouve dans `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Exécutez-le :** - -**Bash :** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testFormatageDuModèleDePrompt -``` - -**PowerShell :** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatting -``` +Ce modèle vérifie que la substitution des variables fonctionne correctement et que les prompts sont formatés comme prévu — aucune clé API ou appel au modèle requis. ### Modèle 2 : Simuler les modèles de langage -Lors des tests de logique de conversation, utilisez Mockito pour créer des modèles fictifs qui renvoient des réponses prédéterminées. Cela rend les tests rapides, gratuits et déterministes. +Lors du test de la logique de conversation, utilisez Mockito pour créer des modèles factices qui renvoient des réponses prédéterminées. Cela rend les tests rapides, gratuits et déterministes. -Comparaison maquette vs API réelle +Mock vs Real API Comparison -*Comparaison montrant pourquoi les simulations sont préférées pour les tests : elles sont rapides, gratuites, déterministes et ne nécessitent pas de clés API* +*Comparaison montrant pourquoi les mocks sont préférés pour les tests : ils sont rapides, gratuits, déterministes et ne nécessitent pas de clés API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Ce modèle apparaît dans `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. La maquette garantit un comportement cohérent pour vérifier que la gestion de la mémoire fonctionne correctement. +Ce modèle apparaît dans `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Le mock garantit un comportement cohérent afin que vous puissiez vérifier que la gestion de la mémoire fonctionne correctement. -### Modèle 3 : Tester l’isolation des conversations +### Modèle 3 : Tester l'isolation des conversations La mémoire de conversation doit garder plusieurs utilisateurs séparés. Ce test vérifie que les conversations ne mélangent pas les contextes. -Isolation des conversations +Conversation Isolation -*Test d’isolation des conversations montrant des magasins de mémoire distincts pour différents utilisateurs afin d’éviter le mélange des contextes* +*Test de l'isolation des conversations montrant des mémoires séparées pour différents utilisateurs afin d'éviter le mélange de contexte* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Chaque conversation maintient son propre historique indépendant. Dans les systèmes de production, cette isolation est cruciale pour les applications multi-utilisateurs. +Chaque conversation maintient son propre historique indépendant. Dans les systèmes en production, cette isolation est critique pour les applications multi-utilisateurs. ### Modèle 4 : Tester les outils indépendamment -Les outils sont des fonctions que l’IA peut appeler. Testez-les directement pour garantir qu’ils fonctionnent correctement indépendamment des décisions de l’IA. +Les outils sont des fonctions que l'IA peut appeler. Testez-les directement pour vous assurer qu'ils fonctionnent correctement indépendamment des décisions de l'IA. -Test des outils +Tools Testing -*Test des outils indépendamment montrant l’exécution d’outils simulés sans appels IA pour vérifier la logique métier* +*Test des outils indépendants montrant l'exécution simulée d'outils sans appels IA pour vérifier la logique métier* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Ces tests issus de `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` valident la logique des outils sans intervention d’IA. L’exemple de chaînage montre comment la sortie d’un outil alimente l’entrée d’un autre. +Ces tests issus de `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` valident la logique des outils sans intervention de l'IA. L'exemple de chaînage montre comment la sortie d'un outil alimente l'entrée d'un autre. -### Modèle 5 : Test RAG en mémoire +### Modèle 5 : Test de RAG en mémoire -Les systèmes RAG nécessitent traditionnellement des bases de données vectorielles et des services d’embeddding. Le modèle en mémoire vous permet de tester toute la chaîne sans dépendances externes. +Les systèmes RAG nécessitent traditionnellement des bases de données vectorielles et des services d'embedding. Le modèle en mémoire vous permet de tester toute la chaîne sans dépendances externes. -Test RAG en mémoire +In-Memory RAG Testing -*Flux de travail du test RAG en mémoire montrant l’analyse de documents, le stockage d’embedddings et la recherche de similarité sans base de données* +*Workflow de test RAG en mémoire montrant l'analyse de documents, le stockage d'embeddings et la recherche de similarité sans nécessiter de base de données* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -Ce test de `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` crée un document en mémoire et vérifie la segmentation et la gestion des métadonnées. +Ce test issu de `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` crée un document en mémoire et vérifie le découpage en morceaux et la gestion des métadonnées. -### Modèle 6 : Test d’intégration MCP +### Modèle 6 : Test d'intégration MCP -Le module MCP teste l’intégration du protocole Model Context via le transport stdio. Ces tests vérifient que votre application peut lancer et communiquer avec des serveurs MCP en tant que sous-processus. +Le module MCP teste l'intégration du Protocole de Contexte de Modèle utilisant le transport stdio. Ces tests vérifient que votre application peut lancer et communiquer avec des serveurs MCP en sous-processus. -Les tests de `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` valident le comportement du client MCP. +Les tests dans `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` valident le comportement du client MCP. -**Exécutez-les :** +**Exécutez-les :** **Bash :** ```bash @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Philosophie de test -Testez votre code, pas l’IA. Vos tests doivent valider le code que vous écrivez en vérifiant comment les invites sont construites, comment la mémoire est gérée, et comment les outils s’exécutent. Les réponses IA varient et ne devraient pas faire partie des assertions de test. Demandez-vous si votre modèle d’invite substitue correctement les variables, pas si l’IA donne la bonne réponse. +Testez votre code, pas l'IA. Vos tests doivent valider le code que vous écrivez en vérifiant comment les prompts sont construits, comment la mémoire est gérée et comment les outils s'exécutent. Les réponses IA varient et ne doivent pas faire partie des assertions de test. Demandez-vous si votre modèle de prompt substitue correctement les variables, pas si l'IA donne la bonne réponse. -Utilisez des simulations pour les modèles de langage. Ce sont des dépendances externes qui sont lentes, coûteuses et non déterministes. Simuler rend les tests rapides avec des millisecondes au lieu de secondes, gratuits sans coûts API, et déterministes avec le même résultat à chaque fois. +Utilisez des mocks pour les modèles de langage. Ce sont des dépendances externes lentes, coûteuses et non déterministes. Le mock rend les tests rapides avec des millisecondes au lieu de secondes, gratuits sans coûts API, et déterministes avec le même résultat à chaque fois. -Gardez les tests indépendants. Chaque test doit configurer ses propres données, ne pas dépendre d’autres tests, et nettoyer après lui-même. Les tests doivent passer indépendamment de l’ordre d’exécution. +Gardez les tests indépendants. Chaque test doit configurer ses propres données, ne pas dépendre d'autres tests, et nettoyer après lui-même. Les tests doivent réussir quel que soit l'ordre d'exécution. -Testez les cas limites au-delà du chemin heureux. Essayez des entrées vides, très volumineuses, des caractères spéciaux, des paramètres invalides et des conditions aux limites. Cela révèle souvent des bugs que l’utilisation normale n’expose pas. +Testez les cas limites au-delà du chemin heureux. Essayez des entrées vides, des entrées très grandes, des caractères spéciaux, des paramètres invalides et des conditions aux limites. Ceux-ci révèlent souvent des bugs que l'utilisation normale n'expose pas. -Utilisez des noms descriptifs. Comparez `shouldMaintainConversationHistoryAcrossMultipleMessages()` avec `test1()`. Le premier vous dit exactement ce qui est testé, facilitant grandement le débogage des échecs. +Utilisez des noms descriptifs. Comparez `shouldMaintainConversationHistoryAcrossMultipleMessages()` avec `test1()`. Le premier indique exactement ce qui est testé, facilitant grandement le débogage des échecs. ## Étapes suivantes Maintenant que vous comprenez les modèles de test, approfondissez chaque module : -- **[00 - Démarrage rapide](../00-quick-start/README.md)** - Commencez avec les bases des modèles d’invite - **[01 - Introduction](../01-introduction/README.md)** - Apprenez la gestion de la mémoire de conversation -- **[02 - Prompt Engineering](../02/prompt-engineering/README.md)** - Maîtrisez les patterns GPT-5.2 pour les invites +- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Maîtrisez les modèles de prompting GPT-5.2 - **[03 - RAG](../03-rag/README.md)** - Construisez des systèmes de génération augmentée par récupération -- **[04 - Outils](../04-tools/README.md)** - Implémentez l’appel de fonctions et les chaînes d’outils -- **[05 - MCP](../05-mcp/README.md)** - Intégrez le protocole Model Context +- **[04 - Outils](../04-tools/README.md)** - Implémentez les appels de fonctions et les chaînes d'outils +- **[05 - MCP](../05-mcp/README.md)** - Intégrez le Protocole de Contexte de Modèle Le README de chaque module fournit des explications détaillées des concepts testés ici. --- -**Navigation :** [← Retour à l’accueil](../README.md) +**Navigation :** [← Retour au principal](../README.md) --- -**Avis de non-responsabilité** : -Ce document a été traduit à l’aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforcions d’assurer la précision, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue d’origine doit être considéré comme la source faisant foi. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle par un traducteur humain. Nous déclinons toute responsabilité en cas de malentendus ou d’interprétations erronées résultant de l’utilisation de cette traduction. +**Avertissement** : +Ce document a été traduit à l'aide du service de traduction automatique [Co-op Translator](https://github.com/Azure/co-op-translator). Bien que nous nous efforçions d'assurer l'exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue native doit être considéré comme la source faisant autorité. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous ne saurions être tenus responsables des malentendus ou erreurs d'interprétation découlant de l'utilisation de cette traduction. \ No newline at end of file diff --git a/translations/he/.co-op-translator.json b/translations/he/.co-op-translator.json index 34705f489..16ea18879 100644 --- a/translations/he/.co-op-translator.json +++ b/translations/he/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "he" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T03:14:08+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T08:31:23+00:00", "source_file": "01-introduction/README.md", "language_code": "he" }, @@ -18,20 +18,20 @@ "language_code": "he" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T03:16:24+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T08:26:35+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "he" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T03:17:56+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T08:30:25+00:00", "source_file": "03-rag/README.md", "language_code": "he" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:58:18+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T08:29:06+00:00", "source_file": "04-tools/README.md", "language_code": "he" }, @@ -54,8 +54,8 @@ "language_code": "he" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:11:41+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T08:25:11+00:00", "source_file": "README.md", "language_code": "he" }, @@ -72,14 +72,14 @@ "language_code": "he" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T03:21:20+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T08:27:11+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "he" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T03:22:06+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T08:27:53+00:00", "source_file": "docs/TESTING.md", "language_code": "he" } diff --git a/translations/he/00-quick-start/README.md b/translations/he/00-quick-start/README.md deleted file mode 100644 index 3d9dbc5f0..000000000 --- a/translations/he/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# מודול 00: התחלה מהירה - -## תוכן העניינים - -- [הקדמה](../../../00-quick-start) -- [מה זה LangChain4j?](../../../00-quick-start) -- [תלויות LangChain4j](../../../00-quick-start) -- [דרישות מוקדמות](../../../00-quick-start) -- [התקנה](../../../00-quick-start) - - [1. קבל את אסימון ה-GitHub שלך](../../../00-quick-start) - - [2. הגדר את האסימון שלך](../../../00-quick-start) -- [הרץ את הדוגמאות](../../../00-quick-start) - - [1. שיחת בסיס](../../../00-quick-start) - - [2. תבניות פרומפט](../../../00-quick-start) - - [3. קריאת פונקציות](../../../00-quick-start) - - [4. שאלות ותשובות על מסמכים (Easy RAG)](../../../00-quick-start) - - [5. בינה מלאכותית אחראית](../../../00-quick-start) -- [מה כל דוגמה מציגה](../../../00-quick-start) -- [שלבים הבאים](../../../00-quick-start) -- [פתרון בעיות](../../../00-quick-start) - -## הקדמה - -ההתחלה המהירה הזו מיועדת לקבל אותך עובדים עם LangChain4j במהירות האפשרית. היא מכסה את הבסיס המוחלט בבניית יישומי בינה מלאכותית עם LangChain4j ודגמי GitHub. במודולים הבאים תעבור ל-Azure OpenAI ו-GPT-5.2 ותעמיק בכל מושג. - -## מה זה LangChain4j? - -LangChain4j היא ספריית Java שמפשטת את בניית היישומים המונעים בינה מלאכותית. במקום להתמודד עם לקוחות HTTP וניתוח JSON, אתה עובד עם ממשקי API נקיים של Java. - -המילה "chain" ב-LangChain מתייחסת לקישור של רכיבים מרובים יחד - ניתן לקשר פרומפט לדגם, לדפדפן, או לקשר קריאות AI מרובות יחד כאשר פלט אחד מזין את הקלט הבא. התחלת מהירה זו מתמקדת ביסודות לפני חקירת שרשראות מורכבות יותר. - -רעיונון השרשרת LangChain4j - -*שרשור רכיבים ב-LangChain4j - אבני בניין שמתחברים ליצירת זרימות עבודה עוצמתיות של בינה מלאכותית* - -נשתמש בשלושה רכיבים מרכזיים: - -**ChatModel** - הממשק לאינטראקציות עם מודל AI. קרא `model.chat("prompt")` וקבל מחרוזת תגובה. אנו משתמשים ב-`OpenAiOfficialChatModel` שעובד עם נקודות קצה תואמות OpenAI כמו דגמי GitHub. - -**AiServices** - יוצר ממשקי שירות AI בטוחים טיפוסית. הגדר שיטות, סמן אותן ב-`@Tool`, ו-LangChain4j מנהל את התזמור. ה-AI קורא אוטומטית את שיטות ה-Java שלך כשנדרש. - -**MessageWindowChatMemory** - שומר היסטוריית שיחה. בלעדיו, כל בקשה היא עצמאית. איתו, ה-AI זוכר הודעות קודמות ושומר הקשר במספר סבבים. - -ארכיטקטורת LangChain4j - -*ארכיטקטורת LangChain4j - רכיבים מרכזיים העובדים ביחד להנעת יישומי ה-AI שלך* - -## תלויות LangChain4j - -ההתחלה המהירה הזו משתמשת בשלוש תלויות של Maven בקובץ [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -מודול `langchain4j-open-ai-official` מספק את המחלקה `OpenAiOfficialChatModel` שמתחברת ל-APIs תואמי OpenAI. דגמי GitHub משתמשים באותו פורמט API, כך שאין צורך במתאם מיוחד - פשוט הצבע על כתובת הבסיס ל-`https://models.github.ai/inference`. - -מודול `langchain4j-easy-rag` מספק חלוקה, הטמעה ושליפה אוטומטית של מסמכים כך שתוכל לבנות יישומי RAG ללא הגדרה ידנית של כל שלב. - -## דרישות מוקדמות - -**משתמש ב-Dev Container?** Java ו-Maven מותקנים מראש. כל מה שצריך הוא אסימון גישה אישי ל-GitHub. - -**פיתוח מקומי:** -- Java 21+, Maven 3.9+ -- אסימון גישה אישי ל-GitHub (הוראות למטה) - -> **הערה:** מודול זה משתמש ב-`gpt-4.1-nano` מדגמי GitHub. אל תשנה את שם הדגם בקוד - הוא מוגדר לעבוד עם דגמי GitHub הזמינים. - -## התקנה - -### 1. קבל את אסימון ה-GitHub שלך - -1. עבור אל [הגדרות GitHub → אסימוני גישה אישית](https://github.com/settings/personal-access-tokens) -2. לחץ על "Generate new token" -3. קבע שם תיאורי (למשל, "LangChain4j Demo") -4. הגדר תוקף (מומלץ 7 ימים) -5. תחת "הרשאות חשבון", אתר "Models" והגדר לקריאה בלבד -6. לחץ על "Generate token" -7. העתק ושמור את האסימון - לא תראה אותו שוב - -### 2. הגדר את האסימון שלך - -**אפשרות 1: שימוש ב-VS Code (מומלץ)** - -אם אתה משתמש ב-VS Code, הוסף את האסימון שלך לקובץ `.env` בספריית הפרויקט: - -אם קובץ `.env` לא קיים, העתק את `.env.example` ל-`.env` או צור קובץ `.env` חדש בספריית הפרויקט. - -**קובץ `.env` לדוגמה:** -```bash -# בקובץ /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -אז תוכל פשוט ללחוץ קליק ימני על כל קובץ דמו (למשל `BasicChatDemo.java`) בסייר ולבחור **"Run Java"**, או להשתמש בהרצות מתוך לוח ההפעלה והניפוי. - -**אפשרות 2: שימוש בטרמינל** - -הגדר את האסימון כמשתנה סביבה: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## הרץ את הדוגמאות - -**שימוש ב-VS Code:** פשוט לחץ קליק ימני על כל קובץ דמו בסייר ובחר **"Run Java"**, או השתמש בהרצות מלוח ההפעלה והניפוי (ודא שהוספת את האסימון לקובץ `.env` קודם). - -**שימוש ב-Maven:** לחלופין, תוכל להריץ משורת הפקודה: - -### 1. שיחת בסיס - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. תבניות פרומפט - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -מציג אפס-שיט, כמה-שיט, שרשרת מחשבה, ופרומפטים מבוססי תפקיד. - -### 3. קריאת פונקציות - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -ה-AI קורא אוטומטית את שיטות ה-Java שלך כשנדרש. - -### 4. שאלות ותשובות על מסמכים (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -שאל שאלות על המסמכים שלך באמצעות Easy RAG עם הטמעה ושליפה אוטומטית. - -### 5. בינה מלאכותית אחראית - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -ראה כיצד מסנני בטיחות AI חוסמים תוכן מזיק. - -## מה כל דוגמה מציגה - -**שיחת בסיס** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -התחל כאן כדי לראות את LangChain4j בפשטותו. תיצור `OpenAiOfficialChatModel`, תשלח פרומפט עם `.chat()`, ותקבל תגובה בחזרה. זה מדגים את היסודות: איך לאתחל דגמים עם נקודות קצה מקוסטמות ומפתחות API. ברגע שתבין את התבנית הזו, כל השאר מתבסס עליה. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 נסה עם צ'אט [GitHub Copilot](https://github.com/features/copilot):** פתח את [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) ושאל: -> - "איך אני מעביר מדגמי GitHub ל-Azure OpenAI בקוד הזה?" -> - "אילו פרמטרים נוספים אני יכול להגדיר ב-OpenAiOfficialChatModel.builder()?" -> - "איך מוסיפים תגובות סטרימינג במקום לחכות לתגובה מלאה?" - -**הנדסת פרומפט** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -עכשיו כשאתה יודע איך לדבר עם דגם, בוא נחקור מה אתה אומר לו. הדמו הזה משתמש באותה הגדרת דגם אך מציג חמישה דפוסי פרומפט שונים. נסה פרומפטים אפס-שיט להוראות ישירות, כמה-שיט שלומדים מדוגמאות, שרשרת מחשבה שחושפת שלבי הסבר, ופרומפטים מבוססי תפקיד שמגדירים הקשר. תראה איך אותו דגם נותן תוצאות שונות מאוד לפי אופן ניסוח הבקשה. - -הדמו גם מציג תבניות פרומפט, דרך עוצמתית ליצור פרומפטים ברי שימוש חוזר עם משתנים. -הדוגמה למטה מראה פרומפט שמשתמש ב-PromptTemplate של LangChain4j למילוי משתנים. ה-AI יענה בהתבסס על היעד והפעילות שסופקו. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 נסה עם צ'אט [GitHub Copilot](https://github.com/features/copilot):** פתח את [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) ושאל: -> - "מה ההבדל בין אפס-שיט לכמה-שיט, ומתי כדאי להשתמש בכל אחד?" -> - "איך פרמטר הטמפרטורה משפיע על תגובות המודל?" -> - "אילו טכניקות קיימות למניעת התקפות הזרקת פרומפט בפרודקשן?" -> - "איך ליצור אובייקטים של PromptTemplate ברי שימוש חוזר לתבניות נפוצות?" - -**אינטגרציית כלים** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -כאן LangChain4j הופך לעוצמתי. תשתמש ב-`AiServices` כדי ליצור עוזר AI שיכול לקרוא לשיטות ה-Java שלך. פשוט סמן שיטות ב-`@Tool("תיאור")` ו-LangChain4j מטפל בשאר - ה-AI מחליט אוטומטית מתי להשתמש בכל כלי לפי מה שהמשתמש מבקש. זה מדגים קריאת פונקציות, טכניקה מרכזית לבניית AI שיכול לפעול, לא רק לענות על שאלות. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 נסה עם צ'אט [GitHub Copilot](https://github.com/features/copilot):** פתח את [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ושאל: -> - "איך באנוטציית @Tool עובדת ומה LangChain4j עושה איתה מאחורי הקלעים?" -> - "האם ה-AI יכול לקרוא לכלים מרובים ברצף לפתור בעיות מורכבות?" -> - "מה קורה אם כלי זורק חריגה - איך להתמודד עם שגיאות?" -> - "איך הייתי משלב API אמיתי במקום דוגמת המכונה המכפלה הזו?" - -**שאלות ותשובות על מסמכים (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -כאן תראה RAG (הפקה משודרגת בשליפה) באמצעות גישת "Easy RAG" של LangChain4j. מסמכים מועלים, מחולקים ומוטמעים אוטומטית בחנות זיכרון, ואז מחלץ תוכן מספק חתיכות רלוונטיות ל-AI בזמן השאילתה. ה-AI עונה על סמך המסמכים שלך, לא הידע הכללי שלו. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 נסה עם צ'אט [GitHub Copilot](https://github.com/features/copilot):** פתח את [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) ושאל: -> - "איך RAG מונע הזיות AI לעומת שימוש בנתוני אימון המודל?" -> - "מה ההבדל בין הגישה הפשוטה הזו לצינור RAG מותאם אישית?" -> - "איך הייתי מגדיל את זה לטפל במסמכים מרובים או בסיסי ידע גדולים יותר?" - -**בינה מלאכותית אחראית** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -בנה בטיחות AI עם הגנה לעומק. הדמו מציג שני שכבות הגנה שפועלות יחד: - -**חלק 1: משמר קלט LangChain4j** - חוסם פרומפטים מסוכנים לפני שישיגו את ה-LLM. צור משמרות קלט מותאמות שמאתרות מילים או דפוסים אסורים. אלו רצות בקוד שלך, כך שהן מהירות וללא עלות. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**חלק 2: מסנני בטיחות הספק** - לדגמי GitHub יש מסננים מובנים שתופסים מה שהמשמרות שלך עלולות לפספס. תראה חסימות קשות (שגיאות HTTP 400) להפרות חמורות וסירובים רכים שבהם ה-AI מסרב בנימוס. - -> **🤖 נסה עם צ'אט [GitHub Copilot](https://github.com/features/copilot):** פתח את [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) ושאל: -> - "מה זה InputGuardrail ואיך יוצרים משמר קלט משלך?" -> - "מה ההבדל בין חסימה קשה לסירוב רך?" -> - "למה להשתמש גם במשמרות קלט וגם במסנני ספקים יחד?" - -## שלבים הבאים - -**המודול הבא:** [01-introduction - התחלה עם LangChain4j](../01-introduction/README.md) - ---- - -**ניווט:** [← חזרה לעמוד ראשי](../README.md) | [הבא: מודול 01 - הקדמה →](../01-introduction/README.md) - ---- - -## פתרון בעיות - -### בניית Maven בפעם הראשונה - -**בעיה**: `mvn clean compile` או `mvn package` ראשוני אורך זמן רב (10-15 דקות) - -**סיבה**: Maven צריך להוריד את כל התלויות של הפרויקט (Spring Boot, ספריות LangChain4j, SDKים של Azure וכו') בבנייה הראשונה. - -**פתרון**: זה התנהגות תקינה. הבניות הבאות יהיו מהירות יותר כי התלויות נשמרות במטמון במחשב המקומי. זמן ההורדה תלוי במהירות החיבור שלך. - -### תחביר פקודת Maven ב-PowerShell - -**בעיה**: פקודות Maven נכשלות עם השגיאה `Unknown lifecycle phase ".mainClass=..."` -**סיבה**: PowerShell מפרש את `=` כאופרטור להקצאת משתנה, ובכך שובר את תחביר התכונות של Maven - -**פתרון**: השתמש באופרטור עצירת הניתוח `--%` לפני פקודת Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -האופרטור `--%` מורה ל-PowerShell להעביר את כל הפרמטרים הנותרים כמו שהם ל-Maven ללא פירוש. - -### הצגת אימוג'ים ב-Windows PowerShell - -**בעיה**: תגובות של AI מציגות תווים משובשים (למשל, `????` או `â??`) במקום אימוג'ים ב-PowerShell - -**סיבה**: הקידוד הברירת מחדל של PowerShell אינו תומך באימוג'ים ב-UTF-8 - -**פתרון**: הרץ את הפקודה הזו לפני ביצוע אפליקציות Java: -```cmd -chcp 65001 -``` - -זה מאלץ קידוד UTF-8 במסוף. לחלופין, השתמש ב-Windows Terminal שיש לו תמיכה טובה יותר ב-Unicode. - -### ניתוח שגיאות בקריאות API - -**בעיה**: שגיאות אימות, הגבלות על קצב, או תגובות בלתי צפויות מהמודל של ה-AI - -**פתרון**: הדוגמאות כוללות `.logRequests(true)` ו-`.logResponses(true)` להצגת קריאות API בקונסולה. זה עוזר לאתר שגיאות אימות, הגבלות קצב, או תגובות בלתי צפויות. הסר דגלים אלו בפרודקשן להפחתת רעש ברישומים. - ---- - - -**כתב ויתור**: -מסמך זה תורגם באמצעות שירות תרגום מבוסס בינה מלאכותית [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדייק, יש להיות מודעים לכך שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש לראות במסמך המקורי בשפה המקורית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אנושי. אנו לא נושאים באחריות על כל אי-הבנות או פירושים שגויים הנובעים משימוש בתרגום זה. - \ No newline at end of file diff --git a/translations/he/01-introduction/README.md b/translations/he/01-introduction/README.md index c033e8d0c..39d462be1 100644 --- a/translations/he/01-introduction/README.md +++ b/translations/he/01-introduction/README.md @@ -2,86 +2,86 @@ ## תוכן העניינים -- [מדריך וידאו](../../../01-introduction) -- [מה תלמדו](../../../01-introduction) -- [דרישות מוקדמות](../../../01-introduction) -- [הבנת הבעיה המרכזית](../../../01-introduction) -- [הבנת טוקנים](../../../01-introduction) -- [איך זיכרון עובד](../../../01-introduction) -- [איך זה משתמש ב-LangChain4j](../../../01-introduction) -- [פריסת תשתית Azure OpenAI](../../../01-introduction) -- [הרצת האפליקציה מקומית](../../../01-introduction) -- [שימוש באפליקציה](../../../01-introduction) - - [שיחת ללא זיכרון (לוח שמאלי)](../../../01-introduction) - - [שיחת עם זיכרון (לוח ימני)](../../../01-introduction) -- [השלבים הבאים](../../../01-introduction) - -## מדריך וידאו - -צפו במפגש חי שמסביר איך להתחיל עם מודול זה: +- [סיור וידאו](#סיור-וידאו) +- [מה תלמדו](#מה-תלמדו) +- [דרישות מוקדמות](#דרישות-מוקדמות) +- [הבנת הבעיה המרכזית](#הבנת-הבעיה-המרכזית) +- [הבנת טוקנים](#הבנת-טוקנים) +- [איך הזיכרון פועל](#איך-הזיכרון-פועל) +- [כיצד מודול זה משתמש ב-LangChain4j](#כיצד-מודול-זה-משתמש-ב-langchain4j) +- [פריסת תשתית Azure OpenAI](#פריסת-תשתית-azure-openai) +- [הרצת האפליקציה מקומית](#הרצת-האפליקציה-מקומית) +- [שימוש באפליקציה](#שימוש-באפליקציה) + - [צ'אט ללא מצב (פאנל שמאל)](#צאט-ללא-מצב-פאנל-שמאל) + - [צ'אט עם מצב (פאנל ימין)](#צאט-עם-מצב-פאנל-ימין) +- [שלבים הבאים](#שלבים-הבאים) + +## סיור וידאו + +צפו במפגש חי שמסביר כיצד להתחיל עם מודול זה: Getting Started with LangChain4j - Live Session ## מה תלמדו -בהתחלה המהירה השתמשתם במודלים של GitHub כדי לשלוח הנחיות, לקרוא כלים, לבנות צינור RAG ולבדוק כללי שמירה. הדמואים האלו הראו מה אפשרי — עכשיו נעבור ל-Azure OpenAI ו-GPT-5.2 ונתחיל לבנות אפליקציות בסגנון ייצור. מודול זה מתמקד בבינה מלאכותית שיחתית שזוכרת הקשר ומנהלת מצב — המושגים שהדמואים של ההתחלה המהירה השתמשו בהם מאחורי הקלעים אך לא הסבירו. +זהו נקודת ההתחלה שלכם עם LangChain4j ו-Azure OpenAI. נתחיל עם הבסיס ונבנה אפליקציות בסגנון ייצור. מודול זה מתמקד ב-AI שיחתי שזוכר הקשר ומתחזק מצב — המושגים היסודיים שכל מודול מאוחר יותר מתבסס עליהם. -נשתמש ב-GPT-5.2 של Azure OpenAI לאורך מדריך זה כי יכולות ההנמקה המתקדמות שלו ממחישות טוב יותר את התנהגותם של דפוסים שונים. כשמוסיפים זיכרון, רואים בבירור את ההבדל. זה מקל על ההבנה מה כל מרכיב מביא לאפליקציה שלכם. +נשתמש ב-GPT-5.2 של Azure OpenAI לאורך כל המדריך הזה כי יכולות ההסקה המתקדמות שלו מדגישות טוב יותר את ההבדלים בין דפוסים שונים. כשאתם מוסיפים זיכרון, ההבדל יהיה ברור יותר. זה מקל על ההבנה של מה שכל רכיב מביא לאפליקציה שלכם. תבנו אפליקציה אחת שמדגימה את שני הדפוסים: -**שיחת ללא זיכרון** - כל בקשה היא עצמאית. למודל אין זיכרון של הודעות קודמות. זהו הדפוס שבו השתמשתם בהתחלה המהירה. +**צ'אט ללא מצב** - כל בקשה עצמאית. למודל אין זיכרון של ההודעות הקודמות. זו הנקודת התחלה הפשוטה ביותר. -**שיחה עם זיכרון** - כל בקשה כוללת היסטוריית שיחה. המודל שומר הקשר על פני מספר סבבים. כך אפליקציות ייצור אמיתיות פועלות. +**שיחה עם מצב** - כל בקשה כוללת היסטוריית שיחה. המודל שומר הקשר לאורך מספר סבבים. זה מה שנדרש באפליקציות ייצור. ## דרישות מוקדמות -- מנוי Azure עם גישה ל-Azure OpenAI -- Java 21, Maven 3.9+ -- Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) +- חשבון Azure עם גישה ל-Azure OpenAI +- Java 21, Maven 3.9+ +- Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **הערה:** Java, Maven, Azure CLI ו-Azure Developer CLI (azd) מותקנים מראש ב-devcontainer המסופק. +> **הערה:** Java, Maven, Azure CLI ו-Azure Developer CLI (azd) מותקנים מראש בקונטיינר הפיתוח שסופק. -> **הערה:** מודול זה משתמש ב-GPT-5.2 על Azure OpenAI. הפריסה מוגדרת אוטומטית דרך `azd up` - אל תשנו את שם המודל בקוד. +> **הערה:** מודול זה משתמש ב-GPT-5.2 ב-Azure OpenAI. הפריסה מוגדרת אוטומטית דרך `azd up` - אל תשנו את שם המודל בקוד. ## הבנת הבעיה המרכזית -מודלי שפה הם ללא זיכרון. כל קריאת API היא עצמאית. אם אתה שולח "השם שלי הוא ג'ון" ואז שואל "מה השם שלי?", המודל אינו מודע לכך שהצגת את עצמך זה עתה. הוא מתייחס לכל בקשה כאילו זו השיחה הראשונה שהיתה לך אי פעם. +מודלים לשוניים הם חסרי-מצב. כל קריאת API היא עצמאית. אם תשלחו "שמי ג'ון" ואז תשאלו "מה השם שלי?", המודל אינו מודע לכך שהצגת את עצמך קודם לכן. הוא מתייחס לכל בקשה כאילו זו השיחה הראשונה שלכם אי פעם. -זה בסדר לשאלות ותשובות פשוטות אך חסר תועלת לאפליקציות אמיתיות. רובוטים של שירות לקוחות צריכים לזכור מה שסיפרת להם. עוזרים אישיים צריכים הקשר. כל שיחה רב-סבבית דורשת זיכרון. +זה בסדר לשאלות ותשובות פשוטות אך חסר ערך באפליקציות אמיתיות. רובוטי שירות לקוחות צריכים לזכור מה אמרתם להם. עוזרים אישיים זקוקים להקשר. כל שיחה רב-סיבובית מחייבת זיכרון. -הדיאגרמה הבאה משווה בין שתי הגישות — בצד שמאל קריאה ללא זיכרון ששוכחת את שמך; מצד ימין קריאה עם זיכרון מגובה ב-ChatMemory שזוכרת אותו. +התמונה הבאה מציגה השוואה בין הגישות — משמאל קריאה ללא מצב ששוכחת את שמך; מימין קריאה עם מצב הנתמכת ב-ChatMemory ששומרת זאת בזיכרון. Stateless vs Stateful Conversations -*ההבדל בין שיחות ללא זיכרון (קריאות עצמאיות) ושיחות עם זיכרון (מודעות להקשר)* +*ההבדל בין שיחות ללא מצב (קריאות עצמאיות) ושיחות עם מצב (מודעות להקשר)* ## הבנת טוקנים -לפני שנכנסים לשיחות, חשוב להבין טוקנים - יחידות הבסיס של טקסט שמודלי שפה מעבדים: +לפני שנצלול לשיחות, חשוב להבין טוקנים - יחידות היסוד של הטקסט שהמודלים הלשוניים מעבדים: Token Explanation -*דוגמה לאופן שבו טקסט מפורק לטוקנים - "I love AI!" הופך ל-4 יחידות עיבוד נפרדות* +*דוגמה לאופן בו הטקסט נשבר לטוקנים - "I love AI!" הופך ל-4 יחידות נפרדות לעיבוד* -טוקנים הם האופן שבו מודלי בינה מלאכותית מודדים ומעבדים טקסט. מילים, פיסוק ואפילו רווחים יכולים להיות טוקנים. למודל שלך יש מגבלה על כמות הטוקנים שהוא יכול לעבד בבת אחת (400,000 ל-GPT-5.2, עם עד 272,000 טוקנים קלט ו-128,000 טוקני פלט). הבנת הטוקנים עוזרת לך לנהל את אורך השיחות והעלויות. +טוקנים הם האופן שבו מודלי AI מודדים ומעבדים טקסט. מילים, סימני פיסוק ואפילו רווחים יכולים להיות טוקנים. למודל שלך יש מגבלה של כמה טוקנים הוא יכול לעבד בבת אחת (400,000 ל-GPT-5.2, כולל עד 272,000 טוקנים קלט ו-128,000 טוקני פלט). הבנת הטוקנים עוזרת לך לנהל אורך שיחה ועלויות. -## איך זיכרון עובד +## איך הזיכרון פועל -זיכרון שיחה פותר את בעיית היעדר הזיכרון באמצעות שמירת היסטוריית השיחה. לפני שליחת הבקשה למודל, המסגרת מוסיפה את ההודעות הרלוונטיות הקודמות. כשאתה שואל "מה השם שלי?", המערכת למעשה שולחת את כל ההיסטוריה של השיחה, ומאפשרת למודל לראות שאמרת קודם "השם שלי הוא ג'ון." +זיכרון הצ'אט פותר את בעיית חוסר-המצב על ידי שמירת היסטוריית השיחה. לפני שליחת הבקשה למודל, המסגרת מדביקה הודעות רלוונטיות קודמות. כשאתה שואל "מה השם שלי?", המערכת למעשה שולחת את כל היסטוריית השיחה, מה שמאפשר למודל לראות שאמרת לפני כן "שמי ג'ון". -LangChain4j מספק מימושי זיכרון שעושים זאת אוטומטית. אתה בוחר כמה הודעות לשמור והמסגרת מנהלת את חלון ההקשר. הדיאגרמה למטה מראה איך MessageWindowChatMemory שומר חלון מחליק של הודעות אחרונות. +LangChain4j מספק מימושים לזיכרון שמטפלים בזה באופן אוטומטי. אתה בוחר כמה הודעות לשמור והמסגרת מנהלת את חלון ההקשר. התרשים למטה מראה כיצד MessageWindowChatMemory שומר חלון מחליק של הודעות אחרונות. Memory Window Concept -*MessageWindowChatMemory שומר חלון מחליק של הודעות אחרונות, ומסיר אוטומטית הודעות ישנות* +*MessageWindowChatMemory שומר על חלון מחליק של הודעות אחרונות, משחרר אוטומטית הודעות ישנות* -## איך זה משתמש ב-LangChain4j +## כיצד מודול זה משתמש ב-LangChain4j -מודול זה מרחיב את ההתחלה המהירה באמצעות שילוב Spring Boot והוספת זיכרון שיחה. כך החלקים מתחברים יחד: +מודול זה משלב Spring Boot ומוסיף זיכרון שיחה. כך החלקים מתחברים יחד: -**תלויות** - הוסף שתי ספריות LangChain4j: +**תלויות** - הוסיפו שתי ספריות LangChain4j: ```xml @@ -94,7 +94,7 @@ LangChain4j מספק מימושי זיכרון שעושים זאת אוטומט ``` -**מודל שיחה** - הגדר את Azure OpenAI כבין של Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**מודל שיחה** - קבעו את Azure OpenAI כבין Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -הבונה קורא את האישורים ממשתני סביבה שהוגדרו על ידי `azd up`. הגדרת `baseUrl` לכתובת ה-endpoint של Azure שלך מאפשרת ללקוח OpenAI לעבוד עם Azure OpenAI. +הבונה קורא את אישורי הגישה ממשתני הסביבה שהוגדרו על ידי `azd up`. קביעת `baseUrl` לנקודת הקצה של Azure שלכם מאפשרת ללקוח OpenAI לעבוד עם Azure OpenAI. -**זיכרון שיחה** - עקוב אחרי היסטוריית השיחות באמצעות MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**זיכרון שיחה** - עקבו אחרי היסטוריית השיחה עם MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -צור זיכרון עם `withMaxMessages(10)` לשמירת 10 ההודעות האחרונות. הוסף הודעות משתמש ובינה מלאכותית בעטיפות טיפוסיות: `UserMessage.from(text)` ו-`AiMessage.from(text)`. שלוף היסטוריה עם `memory.messages()` ושלח אותה למודל. השירות שומר מופעי זיכרון נפרדים לכל מזהה שיחה, ומאפשר למספר משתמשים לנהל שיחות בו זמנית. +צרו זיכרון עם `withMaxMessages(10)` לשמירה של 10 ההודעות האחרונות. הוסיפו הודעות משתמש והודעות AI עם עטיפות טיפוסיות: `UserMessage.from(text)` ו-`AiMessage.from(text)`. שלפו היסטוריה עם `memory.messages()` ושלחו אותה למודל. השירות מאחסן מופעי זיכרון נפרדים לפי מזהה שיחה, ומאפשר למספר משתמשים לנהל שיחות במקביל. -> **🤖 נסה עם [GitHub Copilot](https://github.com/features/copilot) Chat:** פתח את [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ושאל: -> - "איך MessageWindowChatMemory מחליט אילו הודעות להסיר כשהחלון מלא?" -> - "האם אפשר לממש אחסון זיכרון מותאם אישית באמצעות מסד נתונים במקום בזיכרון פנימי?" -> - "איך הייתי מוסיף סיכום ללחוץ את היסטוריית השיחה הישנה?" +> **🤖 נסו עם [GitHub Copilot](https://github.com/features/copilot) Chat:** פתחו את [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ושאלו: +> - "כיצד MessageWindowChatMemory מחליט אילו הודעות לזרוק כשהחלון מלא?" +> - "האם אוכל ליישם אחסון זיכרון מותאם אישית באמצעות מסד נתונים במקום זיכרון פנימי?" +> - "איך אוכל להוסיף סיכום לדחיסת היסטוריית שיחה ישנה?" -נקודת הקצה של שיחת ללא זיכרון מדלגת על הזיכרון לגמרי - פשוט `chatModel.chat(prompt)` כמו בהתחלה המהירה. נקודת הקצה של שיחה עם זיכרון מוסיפה הודעות לזיכרון, מושכת היסטוריה ומכלילה את ההקשר בכל בקשה. אותה הגדרת מודל, דפוסים שונים. +נקודת הקצה של הצ'אט ללא מצב מדלגת על הזיכרון - פשוט `chatModel.chat(prompt)` כמו ההתחלה המהירה. נקודת הקצה עם מצב מוסיפה הודעות לזיכרון, שולפת היסטוריה וכוללת את ההקשר הזה בכל בקשה. אותה תצורת מודל, דפוסים שונים. ## פריסת תשתית Azure OpenAI @@ -147,82 +147,83 @@ cd 01-introduction azd up # בחר מנוי ומיקום (מומלץ eastus2) ``` -> **הערה:** אם אתה נתקל בשגיאת timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), פשוט הרץ `azd up` שוב. משאבי Azure עשויים להיות עדיין בתהליך פריסה ברקע, ונסיון חוזר מאפשר לפריסה להסתיים כשהמשאבים מגיעים למצב סופי. +> **הערה:** אם תקבלו שגיאת timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), פשוט הריצו שוב `azd up`. משאבי Azure עדיין עשויים להיות בתהליך פריסה ברקע, ונסיון חוזר מאפשר לפריסה להסתיים כשתנאי המשאבים יהיו סופיים. -זה י: -1. יפרוס משאב Azure OpenAI עם מודלים GPT-5.2 ו-text-embedding-3-small -2. ייצור אוטומטית קובץ `.env` בשורש הפרויקט עם האישורים -3. יקבע את כל משתני הסביבה הנדרשים +זה יקרה: +1. פריסת משאב Azure OpenAI עם מודלי GPT-5.2 ו-text-embedding-3-small +2. יצירת קובץ `.env` אוטומטית בשורש הפרויקט עם האישורים +3. הגדרת כל משתני הסביבה הנדרשים -**בעיות בפריסה?** ראה את [קובץ ההסבר התשתיתי](infra/README.md) לפתרון בעיות מפורט כולל התנגשויות בשמות תת-דומיין, שלבי פריסה ידנית ב-Azure Portal, והנחיות להגדרת מודלים. +**בעיות בפריסה?** עיינו ב-[README תשתית](infra/README.md) לפירוט פתרון בעיות כולל סכסוכי שמות תת-דומיין, שלבי פריסה ידנית בפורטל Azure והדרכה לתצורת מודל. -**אימות פריסה הצליחה:** +**וודאו שהפריסה הצליחה:** **Bash:** ```bash -cat ../.env # צריך להראות את AZURE_OPENAI_ENDPOINT, API_KEY וכו'. +cat ../.env # אמור להציג את AZURE_OPENAI_ENDPOINT, API_KEY, וכו'. ``` **PowerShell:** ```powershell -Get-Content ..\.env # צריך להציג AZURE_OPENAI_ENDPOINT, API_KEY, וכו'. +Get-Content ..\.env # צריך להציג את AZURE_OPENAI_ENDPOINT, API_KEY, וכו'. ``` -> **הערה:** פקודת `azd up` יוצרת אוטומטית את הקובץ `.env`. אם אתה צריך לעדכן אותו מאוחר יותר, אתה יכול לערוך את הקובץ `.env` ידנית או ליצור מחדש על ידי הרצת: +> **הערה:** הפקודה `azd up` יוצרת אוטומטית את קובץ `.env`. אם תצטרכו לעדכן אותו מאוחר יותר, תוכלו לערוך את הקובץ ידנית או ליצור אותו מחדש באמצעות: > > **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` -> + > **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` + ## הרצת האפליקציה מקומית -**אימות פריסה:** +**וודאו את הפריסה:** -ודא שקובץ `.env` קיים בספרייה הראשית עם אישורי Azure. הרץ זאת מספריית המודול (`01-introduction/`): +ודאו שקובץ `.env` קיים בשורש התיקייה עם האישורים של Azure. הריצו זאת מתיקיית המודול (`01-introduction/`): **Bash:** ```bash -cat ../.env # צריך להראות AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # צריך להציג את AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # צריך להציג את AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # אמור להציג AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**הפעל את האפליקציות:** +**התחילו את האפליקציות:** -**אפשרות 1: שימוש ב-Spring Boot Dashboard (מומלץ למשתמשי VS Code)** +**אפשרות 1: שימוש בלוח הבקרה של Spring Boot (מומלץ למשתמשי VS Code)** -מיכל הפיתוח כולל את הרחבת Spring Boot Dashboard, המספקת ממשק חזותי לניהול כל אפליקציות Spring Boot. ניתן למצוא אותה ב-Activity Bar בצד שמאל של VS Code (חפש את סמל Spring Boot). +קונטיינר הפיתוח כולל את תוסף לוח הבקרה של Spring Boot, שמספק ממשק חזותי לניהול כל אפליקציות Spring Boot. תוכלו למצוא אותו בסרגל הפעילות בצד שמאל של VS Code (סמל Spring Boot). -מ-Spring Boot Dashboard, אתה יכול: -- לראות את כל אפליקציות ה-Spring Boot הזמינות בסביבת העבודה -- להפעיל/להפסיק אפליקציות בלחיצה פשוטה -- לצפות בלוגים של האפליקציה בזמן אמת -- לנטר סטטוס האפליקציה +מלוח הבקרה של Spring Boot ניתן: +- לראות את כל אפליקציות Spring Boot הזמינות בסביבת העבודה +- להתחיל/להפסיק אפליקציות בלחיצה אחת +- לצפות ביומני האפליקציה בזמן אמת +- לנטר את מצב האפליקציה -פשוט לחץ על כפתור ההפעלה ליד "introduction" כדי להתחיל במודול הזה, או הפעל את כל המודולים בבת אחת. +פשוט לחצו על כפתור ההפעלה ליד "introduction" כדי להתחיל מודול זה, או התחילו את כל המודולים יחד. Spring Boot Dashboard -*הלוח של Spring Boot ב-VS Code — הפעלה, עצירה ומעקב אחר כל המודולים במקום אחד* +*לוח הבקרה של Spring Boot ב-VS Code — התחילו, עצרו ונטרו את כל המודולים במקום אחד* **אפשרות 2: שימוש בסקריפטים של shell** -הפעל את כל אפליקציות הווב (מודולים 01-04): +הפעילו את כל אפליקציות הרשת (מודולים 01-04): **Bash:** ```bash -cd .. # מספריית השורש +cd .. # מהספרייה הראשית ./start-all.sh ``` @@ -232,7 +233,7 @@ cd .. # מתיקיית השורש .\start-all.ps1 ``` -או הפעל רק את המודול הזה: +או התחילו רק את המודול הזה: **Bash:** ```bash @@ -246,25 +247,25 @@ cd 01-introduction .\start.ps1 ``` -שני הסקריפטים טוענים אוטומטית משתני סביבה מקובץ `.env` בשורש וייבנו את קבצי ה-JAR אם אינם קיימים. +שני הסקריפטים טוענים אוטומטית משתני סביבה מקובץ `.env` בשורש ויבנו את קובצי JAR אם הם לא קיימים. -> **הערה:** אם אתה מעדיף לבנות את כל המודולים ידנית לפני ההפעלה: +> **הערה:** אם אתם מעדיפים לבנות את כל המודולים ידנית לפני ההפעלה: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -פתח את http://localhost:8080 בדפדפן שלך. +פתחו בדפדפן http://localhost:8080. -**כדי לעצור:** +**לעצור:** **Bash:** ```bash @@ -280,43 +281,44 @@ cd .. && ./stop-all.sh # כל המודולים cd ..; .\stop-all.ps1 # כל המודולים ``` + ## שימוש באפליקציה -האפליקציה מספקת ממשק אינטרנט עם שתי יישומי שיחה לצד זה. +האפליקציה מספקת ממשק רשת עם שתי מימושי צ'אט זה לצד זה. Application Home Screen -*לוח המחוונים מציג את שתי אפשרויות השיחה: Simple Chat (ללא זיכרון) ו-Conversational Chat (עם זיכרון)* +*לוח מחוונים המראה הן צ'אט פשוט (ללא מצב) והן צ'אט שיחות (עם מצב)* -### שיחת ללא זיכרון (לוח שמאלי) +### צ'אט ללא מצב (פאנל שמאל) -נסו את זה קודם. שאלו "השם שלי הוא ג'ון" ואז מיד שאלו "מה השם שלי?" המודל לא יזכור כי כל הודעה עצמאית. זה מדגים את הבעיה המרכזית עם אינטגרציה בסיסית של מודל שפה - אין הקשר שיחה. +נסו קודם לכן. אמרו "שמי ג'ון" ואז מיד שאלו "מה השם שלי?" המודל לא יזכור כי כל הודעה עצמאית. זה מדגים את הבעיה המרכזית באינטגרציה בסיסית של מודל שפה — אין הקשר שיחה. Stateless Chat Demo -*ה-AI לא זוכר את שמך מהודעה קודמת* +*ה-AI לא זוכר את השם שלך מההודעה הקודמת* -### שיחת עם זיכרון (לוח ימני) +### צ'אט עם מצב (פאנל ימין) -עכשיו נסו את אותה הרצף כאן. שאלו "השם שלי הוא ג'ון" ואז "מה השם שלי?" הפעם הוא זוכר. ההבדל הוא MessageWindowChatMemory - שומר היסטוריית שיחה ומכליל אותה בכל בקשה. כך בינה מלאכותית שיחתית במצב ייצור פועלת. +עכשיו נסו את אותו רצף כאן. אמרו "שמי ג'ון" ואז "מה השם שלי?" הפעם הוא זוכר. ההבדל הוא MessageWindowChatMemory - הוא שומר היסטוריית שיחה וכולל אותו בכל בקשה. כך AI שיחות ייצור עובדות. Stateful Chat Demo -*ה-AI זוכר את שמך משלב קודם בשיחה* +*ה-AI זוכר את שמך מהשיחה הקודמת* -שני הלוחות משתמשים באותו מודל GPT-5.2. ההבדל היחיד הוא הזיכרון. זה מבהיר מה הזיכרון מביא לאפליקציה שלך ומדוע הוא חיוני לשימושים אמיתיים. +שני הפאנלים משתמשים באותו מודל GPT-5.2. ההבדל היחיד הוא בזיכרון. זה מבהיר מה הזיכרון מביא לאפליקציה שלך ולמה הוא חיוני לשימושים אמיתיים. -## השלבים הבאים +## שלבים הבאים -**מודול הבא:** [02-prompt-engineering - הנדסת פרומפט עם GPT-5.2](../02-prompt-engineering/README.md) +**מודול הבא:** [02-prompt-engineering - הנדסת פקודות עם GPT-5.2](../02-prompt-engineering/README.md) --- -**ניווט:** [← הקודם: מודול 00 - התחלה מהירה](../00-quick-start/README.md) | [חזרה לעמוד הראשי](../README.md) | [הבא: מודול 02 - הנדסת פרומפט →](../02-prompt-engineering/README.md) +**ניווט:** [← חזרה לעמוד הראשי](../README.md) | [הבא: מודול 02 - הנדסת פקודות →](../02-prompt-engineering/README.md) --- **כתב ויתור**: -מסמך זה תורגם באמצעות שירות תרגום מבוסס בינה מלאכותית [Co-op Translator](https://github.com/Azure/co-op-translator). על אף שאנו מתאמצים להשיג דיוק, יש להיזהר כי תרגומים אוטומטיים עשויים לכלול טעויות או אי דיוקים. המסמך המקורי בשפתו המקורית ייחשב כמקור הסמכות. למידע קריטי מומלץ להיעזר בתרגום מקצועי בידי מתרגם אנושי. אנו לא נושאים באחריות לכל אי הבנה או פרשנות שגויה הנובעות משימוש בתרגום זה. +מסמך זה תורגם באמצעות שירות תרגום אוטומטי [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש להחשיב את המסמך המקורי בשפתו הטבעית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אדם. אנו לא אחראים לכל אי-הבנה או פירוש שגוי הנובע מהשימוש בתרגום זה. \ No newline at end of file diff --git a/translations/he/02-prompt-engineering/README.md b/translations/he/02-prompt-engineering/README.md index 4ffeb039e..bd3a9ff16 100644 --- a/translations/he/02-prompt-engineering/README.md +++ b/translations/he/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ -# מודול 02: הנדסת פרומפטים עם GPT-5.2 +# מודול 02: הנדסת פקודות עם GPT-5.2 -## תוכן העניינים +## תוכן עניינים -- [הדרכה בוידאו](../../../02-prompt-engineering) -- [מה תלמד](../../../02-prompt-engineering) -- [דרישות מקדימות](../../../02-prompt-engineering) -- [הבנת הנדסת פרומפטים](../../../02-prompt-engineering) -- [יסודות הנדסת פרומפטים](../../../02-prompt-engineering) - - [פרומפטים ללא דוגמאות (Zero-Shot)](../../../02-prompt-engineering) - - [פרומפטים עם מספר דוגמאות (Few-Shot)](../../../02-prompt-engineering) - - [שרשרת חשיבה](../../../02-prompt-engineering) - - [פרומפטים מבוססי תפקיד](../../../02-prompt-engineering) - - [תבניות פרומפטים](../../../02-prompt-engineering) -- [תבניות מתקדמות](../../../02-prompt-engineering) -- [הרצת האפליקציה](../../../02-prompt-engineering) -- [צילום מסך של האפליקציה](../../../02-prompt-engineering) -- [חקירת התבניות](../../../02-prompt-engineering) - - [רצון נמוך מול גבוה](../../../02-prompt-engineering) - - [ביצוע משימות (הקדמות לכלים)](../../../02-prompt-engineering) - - [קוד תוך-השקפה עצמית](../../../02-prompt-engineering) - - [ניתוח מובנה](../../../02-prompt-engineering) - - [שיחות מרובות סבבים](../../../02-prompt-engineering) - - [הסקת מסקנות שלב אחר שלב](../../../02-prompt-engineering) - - [תפוקת פלט מוגבלת](../../../02-prompt-engineering) -- [מה אתה באמת לומד](../../../02-prompt-engineering) -- [השלבים הבאים](../../../02-prompt-engineering) +- [סקירת וידאו](#סקירת-וידאו) +- [מה תלמדו](#מה-תלמדו) +- [קדם תנאים](#קדם-תנאים) +- [הבנת הנדסת פקודות](#הבנת-הנדסת-פקודות) +- [יסודות הנדסת פקודות](#יסודות-הנדסת-פקודות) + - [איפוס ירי פקודות](#אפס-ירי-פקודות) + - [איפוס ירי עם מספר דוגמאות](#ירי-פקודות-עם-מספר-דוגמאות) + - [שרשרת מחשבה](#שרשרת-מחשבה) + - [איפוס מבוסס תפקיד](#איפוס-מבוסס-תפקיד) + - [תבניות פקודות](#תבניות-פקודות) +- [תבניות מתקדמות](#תבניות-מתקדמות) +- [הרצת היישום](#הרצת-היישום) +- [צילום מסך של היישום](#צילומי-מסך-של-היישום) +- [חקירת התבניות](#חקר-התבניות) + - [רצון נמוך לעומת גבוה](#eagerness-נמוכה-מול-גבוהה) + - [ביצוע משימה (הקדמות כלים)](#ביצוע-משימות-פתיחי-כלים) + - [קוד עם חשיבה עצמית](#קוד-המשתקף-מעצמו) + - [ניתוח מובנה](#ניתוח-מובנה) + - [שיחה מרובת סבבים](#שיחה-מרובת-סבבים) + - [היסק שלב אחר שלב](#נימוקים-שלב-אחר-שלב) + - [פלט מוגבל](#פלט-מוגבל) +- [מה שלמדתם באמת](#מה-שלמעשה-אתה-לומד) +- [השלבים הבאים](#צעדים-הבאים) -## הדרכה בוידאו +## סקירת וידאו -צפה במפגש חי זה המבהיר כיצד להתחיל עם המודול: +צפו במפגש החי הזה שמסביר כיצד להתחיל לעבוד עם מודול זה: -Prompt Engineering with LangChain4j - Live Session +הנדסת פקודות עם LangChain4j - מפגש חי -## מה תלמד +## מה תלמדו -הדיאגרמה הבאה מספקת סקירה של הנושאים המרכזיים והכישורים שתפתח במודול זה — מטכניקות שיפור הפרומפט ועד תהליך העבודה שלב אחר שלב שתעקוב אחריו. +הדיאגרמה הבאה מספקת סקירה כללית של הנושאים המרכזיים והכישורים שתפתחו במודול זה — מטכניקות שיפור פקודות ועד זרימת העבודה שלב אחר שלב שתעקבו אחריה. -מה תלמד +מה תלמדו -במודולים הקודמים חקרת אינטראקציות בסיסיות עם LangChain4j ו-GitHub Models וראית כיצד הזיכרון מאפשר AI שיחתי עם Azure OpenAI. כעת נתמקד כיצד אתה שואל שאלות — הפרומפטים עצמם — באמצעות GPT-5.2 של Azure OpenAI. האופן בו אתה מבנה את הפרומפטים שלך משפיע באופן דרמטי על איכות התגובות. נתחיל בסקירה של טכניקות הפרומפט הבסיסיות, ואז נעבור לשמונה תבניות מתקדמות שמנצלות באופן מלא את היכולות של GPT-5.2. +במודול הקודם ראיתם כיצד הזיכרון מאפשר בינה מלאכותית שיחה עם Azure OpenAI. כעת נתמקד כיצד אתם שואלים שאלות — כלומר הפקודות עצמן — באמצעות GPT-5.2 של Azure OpenAI. האופן בו אתם מבנים את הפקודות משפיע באופן דרמטי על איכות התגובות שתקבלו. נתחיל בסקירת טכניקות הפקודות הבסיסיות, ואז נעבור לשמונה תבניות מתקדמות המנצלות במלואן את יכולות GPT-5.2. -נשתמש ב-GPT-5.2 משום שהוא מציג שליטה בחשיבה - אתה יכול להגיד למודל כמה לחשוב לפני שהוא עונה. זה מדגיש אסטרטגיות פרומפט שונות ועוזר לך להבין מתי להשתמש בכל גישה. כמו כן, ניהנה מהמגבלות הקצב הטובות יותר של Azure ל-GPT-5.2 בהשוואה ל-GitHub Models. +נשתמש ב-GPT-5.2 מכיוון שהוא מציג שליטה בהיגיון - אתם יכולים להורות למודל כמה לחשוב לפני מענה. זה מבהיר אסטרטגיות פקודה שונות ועוזר לכם להבין מתי להשתמש בכל גישה. -## דרישות מקדימות +## קדם תנאים -- השלמת מודול 01 (משאבי Azure OpenAI מוגדרים) -- קובץ `.env` בספרייה הראשית עם אישורי Azure (נוצר על ידי `azd up` במודול 01) +- השלמת מודול 01 (משאבי Azure OpenAI מופעלים) +- קובץ `.env` בתיקיית השורש עם אישורי Azure (נוצר על ידי `azd up` במודול 01) -> **הערה:** אם לא השלמת את מודול 01, בצע תחילה את הוראות ההטמעה שם. +> **הערה:** אם לא השלמתם את מודול 01, יש לעקוב תחילה אחר הוראות הפריסה שם. -## הבנת הנדסת פרומפטים +## הבנת הנדסת פקודות -בסיס הנדסת הפרומפטים הוא ההבדל בין הוראות מעורפלות לבין מדויקות, כפי שמדגים ההשוואה למטה. +בבסיסו, הנדסת פקודות היא ההבדל בין הוראות לא מדויקות להוראות מדויקות, כפי שההשוואה למטה ממחישה. -מהי הנדסת פרומפטים? +מהי הנדסת פקודות? -הנדסת פרומפטים עוסקת בתכנון טקסט קלט שמקבל עמודות תוצאות בתצורה עקבית. זה לא רק לשאול שאלות – זה לבנות בקשות כך שהמודל יבין בדיוק מה אתה רוצה וכיצד להעניק זאת. +הנדסת פקודות עוסקת בעיצוב טקסט קלט שמביא איתם בתוצאות הרצויות בעקביות. זה לא רק לשאול שאלות - אלא לבנות בקשות כך שהמודל יבין בדיוק מה אתם רוצים ואיך לספק זאת. -תחשוב על זה כמו מתן הוראות לעמית לעבודה. "תקן את הבאג" היא הוראה מעורפלת. "תקן את החריגה null pointer ב-UserService.java שורה 45 על ידי הוספת בדיקת null" היא מדויקת. מודלי שפה פועלים באותו אופן - ספציפיות ומבנה הם חשובים. +תחשבו על זה כמו מתן הוראות לעמית לעבודה. "תקן את הבאג" זו הוראה מעורפלת. "תקן את חריגת הנקודה הריקה ב-UserService.java שורה 45 על ידי הוספת בדיקת null" היא מדויקת. מודלי השפה פועלים באותה צורה - פירוט ומבנה חשובים. -הדיאגרמה הבאה מציגה כיצד LangChain4j משתלב בתמונה — מחבר את דפוסי הפרומפט שלך למודל דרך רכיבי הבנייה SystemMessage ו-UserMessage. +הדיאגרמה למטה מראה כיצד LangChain4j משתלב בתמונה — מחבר את תבניות הפקודה שלכם למודל באמצעות בלוקי הבנייה SystemMessage ו-UserMessage. כיצד LangChain4j משתלב -LangChain4j מספק את התשתית — חיבורים למודלים, זיכרון, וסוגי הודעות — בעוד שדפוסי הפרומפט הם פשוט טקסט מובנה בקפידה שאתה שולח דרך התשתית הזו. אבני הבניין המרכזיות הן `SystemMessage` (שקובעת את התנהגות ותפקיד ה-AI) ו-`UserMessage` (שנושא את הבקשה הממשית שלך). +LangChain4j מספק את התשתית — חיבורי מודל, זיכרון וסוגי הודעות — בעוד שתבניות הפקודות הן רק טקסט מבנה בקפידה שאתם שולחים דרך התשתית הזו. אבני הבניין המרכזיות הן `SystemMessage` (שמצב את ההתנהגות והתפקיד של ה-AI) ו-`UserMessage` (שאוחז בבקשה העצמאית שלכם). -## יסודות הנדסת פרומפטים +## יסודות הנדסת פקודות -חמש טכניקות הליבה המוצגות למטה מהוות את הבסיס להנדסת פרומפטים יעילה. כל אחת מתמקדת בהיבט אחר של האופן בו אתה מתקשר עם מודלי שפה. +חמש הטכניקות העיקריות המופיעות למטה מהוות את הבסיס להנדסת פקודות אפקטיבית. כל אחת מתמקדת באספקט שונה של האינטראקציה שלכם עם מודלי שפה. -סקירת חמשת דפוסי הנדסת פרומפטים +סקירת חמש תבניות הנדסת פקודות -לפני שנצלול לתבניות המתקדמות במודול זה, נעבור על חמש טכניקות פרומפט בסיסיות. אלו אבני הבניין שכל מהנדס פרומפט צריך להכיר. אם כבר עבדת עם [מודול ההתחלה המהירה](../00-quick-start/README.md#2-prompt-patterns), ראית אותן בפועל — הנה המסגרת התיאורטית שמאחוריהן. +לפני שנצלול לתבניות המתקדמות במודול זה, נסקור חמש טכניקות פקודה בסיסיות. אלה אבני הבניין שכל מהנדס פקודות צריך להכיר. -### פרומפט ללא דוגמאות (Zero-Shot) +### אפס ירי פקודות -הגישה הפשוטה ביותר: תן למודל הוראה ישירה ללא דוגמאות. המודל מתבסס לחלוטין על האימון שלו כדי להבין ולבצע את המשימה. זה עובד היטב עבור בקשות פשוטות שבהן ההתנהגות המצופה ברורה. +הגישה הפשוטה ביותר: לתת למודל הוראה ישירה ללא דוגמאות. המודל מסתמך לחלוטין על האימון שלו כדי להבין ולבצע את המשימה. זה עובד טוב לבקשות פשוטות שבהן ההתנהגות הצפויה ברורה. -פרומפט ללא דוגמאות +איפוס ירי פקודות -*הוראה ישירה ללא דוגמאות — המודל מסיק את המשימה מההוראה בלבד* +*הוראה ישירה ללא דוגמאות — המודל מסיק את המשימה מהוראה בלבד* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // תגובה: "חיובי" ``` -**מתי להשתמש:** סיווגים פשוטים, שאלות ישירות, תרגומים, או כל משימה שהמודל יכול לטפל בה ללא הנחיות נוספות. +**מתי להשתמש:** סיווגים פשוטים, שאלות ישירות, תרגומים, או כל משימה שהמודל יכול להתמודד איתה בלי הדרכה נוספת. -### פרומפט עם מספר דוגמאות (Few-Shot) +### ירי פקודות עם מספר דוגמאות -ספק דוגמאות המדגימות את הדפוס שברצונך שהמודל יעקוב אחריו. המודל לומד את פורמט הקלט-פלט המצופה מהדוגמאות שלך ומיישם אותו על קלטים חדשים. זה משפר באופן דרמטי את העקביות במשימות שבהן הפורמט או ההתנהגות הרצויים אינם מובנים מאליהם. +מספקים דוגמאות המדגימות את התבנית שברצונכם שהמודל יעקוב אחריה. המודל לומד את פורמט הקלט-פלט המצופה מדוגמאותיכם ומיישם אותו על קלטים חדשים. זה משפר מאוד את העקביות למשימות שבהן פורמט או התנהגות רצויים אינם ברורים. -פרומפט עם מספר דוגמאות +ירי פקודות עם מספר דוגמאות -*לומד מדוגמאות — המודל מזהה את הדפוס ומחיל אותו על קלטים חדשים* +*לימוד מדוגמאות — המודל מזהה את התבנית ומיישם אותה על קלטים חדשים* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**מתי להשתמש:** סיווגים מותאמים אישית, עיצוב עקבי, משימות ספציפיות לתחום, או כאשר תוצאות ה-zero-shot אינן עקביות. +**מתי להשתמש:** סיווגים מותאמים אישית, עיצוב עקבי, משימות בתחום ספציפי, או כאשר תוצאות אפס ירי אינן עקביות. -### שרשרת חשיבה (Chain of Thought) +### שרשרת מחשבה -בקש מהמודל להראות את ההיגיון שלו שלב אחר שלב. במקום לקפוץ ישר לתשובה, המודל מפצל את הבעיה ועובד על כל חלק במפורש. זה משפר את הדיוק בבעיות מתמטיות, לוגיות, ובהסקת מסקנות מרובה שלבים. +בקשו מהמודל להראות את ההיגיון שלו צעד אחר צעד. במקום לקפוץ ישר לתשובה, המודל מפרק את הבעיה ועובר על כל חלק במפורש. זה משפר את הדיוק באלות מתמטיות, לוגיקה ומשימות היסק רב-שלבי. -פרומפט שרשרת חשיבה +שרשרת מחשבה -*היגיון שלב אחר שלב — מפצל בעיות מורכבות לשלבים לוגיים מפורשים* +*היסק שלב אחר שלב — שבירת בעיות מורכבות לצעדים לוגיים מפורשים* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// המודל מראה: 15 - 8 = 7, ואז 7 + 12 = 19 תפוחים +// הדגם מציג: 15 - 8 = 7, אז 7 + 12 = 19 תפוחים ``` -**מתי להשתמש:** בעיות מתמטיות, חידות לוגיות, איתור שגיאות, או כל משימה שבה הצגת תהליך ההיגיון משפרת דיוק ואמון. +**מתי להשתמש:** בעיות מתמטיות, חידות לוגיות, איתור באגים, או כל משימה שבה הצגת תהליך ההיגיון משפרת דיוק ואמון. -### פרומפטים מבוססי תפקיד (Role-Based Prompting) +### איפוס מבוסס תפקיד -הגדר אישיות או תפקיד ל-AI לפני ששואלים את שאלתך. זה מספק הקשר שמעצב את הטון, העומק, והפוקוס של התגובה. "ארכיטקט תוכנה" נותן עצות שונות מ"מתכנת צעיר" או "בודק אבטחה". +הגדירו פרסונה או תפקיד ל-AI לפני ששואלים את השאלה. זה מספק הקשר שמעצבת את הטון, העומק, והמיקוד של התשובה. "ארכיטקט תוכנה" נותן עצות שונות מ"מפתח זוטר" או "מבקר אבטחה". -פרומפט מבוסס תפקיד +איפוס מבוסס תפקיד -*קביעת הקשר ואישיות — אותה שאלה מקבלת תגובה שונה בהתאם לתפקיד שיוחס* +*הגדרת הקשר ופרסונה — אותה שאלה מקבלת תשובה שונה בהתאם לתפקיד שהוקצה* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**מתי להשתמש:** סקירות קוד, הדרכה, ניתוח תחום ספציפי, או כשאתה צריך תגובות המותאמות לרמת מומחיות או נקודת מבט מסוימת. +**מתי להשתמש:** סקירות קוד, הדרכה, ניתוחים בתחום ספציפי, או כאשר אתם צריכים תגובות מותאמות לרמת מומחיות או נקודת מבט מסוימת. -### תבניות פרומפטים (Prompt Templates) +### תבניות פקודות -צור פרומפטים לשימוש חוזר עם משתנים למילוי. במקום לכתוב פרומפט חדש בכל פעם, הגדר תבנית אחת ומלא בה ערכים שונים. מחלקת `PromptTemplate` של LangChain4j מקלה על כך בשימוש בתחביר `{{variable}}`. +צרו פקודות רב-פעמיות עם תבניות משתנים. במקום לכתוב פקודה חדשה בכל פעם, הגדירו תבנית פעם אחת ומלאו בערכים שונים. מחלקת `PromptTemplate` של LangChain4j מקלה על כך עם תחביר `{{variable}}`. -תבניות פרומפטים +תבניות פקודות -*פרומפטים לשימוש חוזר עם משתנים — תבנית אחת, שימושים רבים* +*פקודות רב-פעמיות עם משתנים — תבנית אחת, שימושים רבים* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**מתי להשתמש:** שאילתות חוזרות עם קלטים שונים, עיבוד באצוות, בניית תהליכי עבודה של AI לשימוש חוזר, או בכל מצב שבו מבנה הפרומפט נשאר זהה אך הנתונים משתנים. +**מתי להשתמש:** שאילתות חוזרות עם קלטים שונים, עיבוד באצווה, בניית זרימות עבודה של AI רב-שימושיות, או כל תרחיש שבו מבנה הפקודה נשאר קבוע אך הנתונים משתנים. --- -חמשת היסודות הללו מעניקים לך ערכת כלים איתנה לרוב משימות הפרומפט. שאר המודול ממשיך איתם עם **שמונה תבניות מתקדמות** המנצלות את בקרת החשיבה, ההערכה העצמית, ויכולות הפלט המובנה של GPT-5.2. +חמשת היסודות האלו נותנים לכם ערכת כלים איתנה לרוב משימות הפקודה. שאר המודול מתבסס עליהם עם **שמונה תבניות מתקדמות** שמנצלות את שליטת ההיגיון, ההערכה העצמית והפלט המובנה של GPT-5.2. ## תבניות מתקדמות -לאחר כיסוי היסודות, נמשיך לשמונה תבניות מתקדמות שמייחדות מודול זה. לא כל בעיה זקוקה לאותה גישה. חלק מהשאלות דורשות תשובות מהירות, אחרות דורשות חשיבה מעמיקה. חלק דורשות היגיון גלוי, אחרות רק תוצאות. כל תבנית למטה מותאמת לסיטואציה שונה — ובקרת החשיבה של GPT-5.2 מדגישה את ההבדלים עוד יותר. +עם היסודות הנלמדים, נעבור לשמונה התבניות המתקדמות שהופכות מודול זה לייחודי. לא כל הבעיות זקוקות לאותה גישה. חלק מהשאלות דורשות תשובות מהירות, אחרות דורשות חשיבה עמוקה. חלק דורשות היגיון גלוי, אחרות רק תוצאות. כל תבנית מטה אופטימלית לתרחיש אחר — ושליטה בהיגיון של GPT-5.2 מדגישה את ההבדלים. -שמונה דפוסי הנדסת פרומפטים +שמונה תבניות הנדסת פקודות -*סקירה של שמונת דפוסי הנדסת הפרומפט והשימושים שלהם* +*סקירה של שמונת תבניות הנדסת הפקודות והשימושים שלהן* -GPT-5.2 מוסיף מימד חדש לתבניות האלה: *בקרת חשיבה*. המחוון למטה מראה כיצד ניתן לכוון את מאמץ החשיבה של המודל — מתשובות מהירות וישירות ועד ניתוח עמוק ויסודי. +GPT-5.2 מוסיף מימד נוסף לתבניות האלו: *שליטה בהיגיון*. המחוון למטה מראה כיצד ניתן לכוונן את מאמץ החשיבה של המודל — מתשובות מהירות וישירות ועד לניתוח מעמיק ויסודי. -בקרת חשיבה עם GPT-5.2 +שליטה בהיגיון עם GPT-5.2 -*בקרת החשיבה של GPT-5.2 מאפשרת לך לציין כמה לחשוב המודל צריך — מתשובות מהירות ועד לחקירה מעמיקה* +*שליטה בהיגיון של GPT-5.2 מאפשרת לכם לציין כמה לחשוב המודל - מתשובות מהירות ועד חקירה מעמיקה* -**רצון נמוך (מהיר וממוקד)** - לשאלות פשוטות שבהן רוצים תשובות מהירות וישירות. המודל מבצע מינימום חשיבה - מקסימום 2 שלבים. השתמש בזה לחישובים, חיפושים, או שאלות פשוטות. +**רצון נמוך (מהיר וממוקד)** - לשאלות פשוטות שבהן אתם רוצים תשובות מהירות וישירות. המודל מבצע היגיון מינימלי - מקסימום 2 צעדים. השתמשו בזה עבור חישובים, חיפושים או שאלות ישירות. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **חקור עם GitHub Copilot:** פתח [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ושאל: -> - "מה ההבדל בין דפוסי פרומפט של רצון נמוך לעומת גבוה?" -> - "כיצד תגיות XML בפרומפטים עוזרות במבנה תגובת ה-AI?" -> - "מתי יש להשתמש בתבניות השיקוף העצמי מול הוראות ישירות?" +> 💡 **חקור עם GitHub Copilot:** פתח את [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ושאל: +> - "מה ההבדל בין דפוסי פקודה של רצון נמוך לעומת רצון גבוה?" +> - "כיצד תגי ה-XML בפקודות עוזרים לבנות את תגובת ה-AI?" +> - "מתי יש להשתמש בתבניות של חשיבה עצמית לעומת הוראה ישירה?" -**רצון גבוה (עמוק ויסודי)** - לבעיות מורכבות שבהן רוצים ניתוח מעמיק. המודל חוקר באופן יסודי ומציג היגיון מפורט. השתמש בזה לתכנון מערכות, החלטות ארכיטקטורה, או מחקר מורכב. +**רצון גבוה (עמוק ויסודי)** - לבעיות מורכבות שבהן אתם רוצים ניתוח מעמיק. המודל חוקר לעומק ומראה היגיון מפורט. השתמשו בזה לעיצוב מערכות, החלטות ארכיטקטוניות, או מחקר מורכב. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**ביצוע משימה (התקדמות שלב אחר שלב)** - עבור תהליכים מרובי שלבים. המודל מספק תוכנית מראש, מתאר כל שלב בזמן העבודה, ואז נותן סיכום. השתמש בזה להעברות, יישומים, או כל תהליך מרובה שלבים. +**ביצוע משימות (התקדמות שלב-אחר-שלב)** - לזרימות עבודה רב-שלביות. המודל מספק תוכנית מקדימה, מפרט כל שלב בעבודה ואז נותן סיכום. השתמשו בזה עבור מעבר נתונים, יישומים או כל תהליך רב שלבים. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -פרומפט שרשרת-חשיבה מבקש במפורש מהמודל להראות את תהליך ההיגיון שלו, ומשפר דיוק במשימות מורכבות. הפירוט שלב אחר שלב מסייע גם לבני אדם וגם ל-AI להבין את הלוגיקה. +איפוס שרשרת מחשבה מבקש במפורש מהמודל להראות את תהליך ההיגיון שלו, ומשפר את הדיוק במשימות מורכבות. הפירוק שלב אחר שלב עוזר גם לבני אדם וגם ל-AI להבין את הלוגיקה. -> **🤖 נסה עם צ'אט של [GitHub Copilot](https://github.com/features/copilot):** שאל על התבנית הזו: -> - "כיצד אתאים את דפוס ביצוע המשימה לפעולות ארוכות-טווח?" -> - "מהם ההרגלים הטובים ביותר למבני הקדמות לכלים באפליקציות פרודקשן?" -> - "כיצד אוכל לתפוס ולהציג עדכוני התקדמות ביניים בממשק משתמש?" +> **🤖 נסה עם צ’אט [GitHub Copilot](https://github.com/features/copilot):** שאל על התבנית הזו: +> - "איך אסתגל את דפוס ביצוע המשימות עבור פעולות ארוכות טווח?" +> - "מהן השיטות הטובות ביותר לבניית הקדמות כלים ביישומים פרודקשן?" +> - "כיצד אוכל לתעד ולהציג עדכוני התקדמות בינוניים בממשק משתמש?" -הדיאגרמה הבאה ממחישה את תהליך העבודה תכנון → ביצוע → סיכום. +הדיאגרמה למטה מדגימה את זרימת העבודה תכנון → ביצוע → סיכום. -דפוס ביצוע משימה +תבנית ביצוע משימה -*תהליך תכנון → ביצוע → סיכום למשימות מרובות שלבים* +*זרימת עבודה תכנון → ביצוע → סיכום למשימות רב-שלביות* -**קוד תוך-השקפה עצמית** - ליצירת קוד איכותי לפרודקשן. המודל מייצר קוד בהתאם לתקני פרודקשן עם טיפול נאות בשגיאות. השתמש בזה בעת בניית תכונות או שירותים חדשים. +**קוד עם חשיבה עצמית** - ליצירת קוד באיכות הפקה. המודל מייצר קוד העומד בסטנדרטים של הפקה עם טיפול שגיאות תקין. השתמשו בזה בבניית תכונות או שירותים חדשים. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -הדיאגרמה הבאה מראה את הלולאת השיפור החוזרת הזו — ייצור, הערכה, זיהוי חולשות, ושיפור עד שהקוד עומד בתקן הפרודקשן. +הדיאגרמה הבאה מציגה את מחזור השיפור החוזר הזה — ייצור, הערכה, זיהוי נקודות תורפה, ושיפור עד שהקוד עומד בסטנדרטים של הפקה. -לולאת השיקוף העצמי +מחזור חשיבה עצמית -*לולאת שיפור חוזרת - יצירה, הערכה, זיהוי בעיות, שיפור, חזרה* +*מחזור שיפור חוזר - הפקה, הערכה, איתור בעיות, שיפור, חזרה* -**ניתוח מובנה** - להערכה עקבית. המודל בודק קוד תוך שימוש במסגרת קבועה (נכונות, נהלים, ביצועים, אבטחה, תחזוקה). השתמש בזה לסקירות קוד או הערכות איכות. +**ניתוח מובנה** - להערכה עקבית. המודל סוקר קוד באמצעות מסגרת קבועה (נכונות, פרקטיקות, ביצועים, אבטחה, תחזוקה). השתמשו בזה לביקורות קוד או הערכות איכות. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 נסה עם צ'אט של [GitHub Copilot](https://github.com/features/copilot):** שאל על ניתוח מובנה: -> - "כיצד אוכל להתאים את מסגרת הניתוח לסוגים שונים של סקירות קוד?" -> - "מה הדרך הטובה ביותר לפרש ולהשתמש בפלט מובנה באופן תכנותי?" -> - "כיצד להבטיח רמות חומרה עקביות על פני סבבי סקירה שונים?" +> **🤖 נסה עם צ’אט [GitHub Copilot](https://github.com/features/copilot):** שאל על ניתוח מובנה: +> - "כיצד להתאים אישית את מסגרת הניתוח לסוגים שונים של ביקורות קוד?" +> - "מהו האופן הטוב ביותר לנתח ולפעול על פלט מובנה בתוכנה?" +> - "כיצד להבטיח רמות חומרה עקביות במפגשי ביקורת שונים?" -הדיאגרמה הבאה מראה כיצד המסגרת המובנית מארגנת סקירת קוד לקטגוריות עקביות עם רמות חומרה. +הדיאגרמה להלן מראה כיצד המסגרת המובנית מארגנת ביקורת קוד לקטגוריות עקביות עם רמות חומרה. -דפוס ניתוח מובנה +תבנית ניתוח מובנה -*מסגרת לסקירות קוד עקביות עם רמות חומרה* +*מסגרת לביקורות קוד עקביות עם רמות חומרה* -**שיחות מרובות סבבים** - לשיחות שדורשות הקשר. המודל זוכר הודעות קודמות ובונה על פיהן. השתמש בזה למפגשי עזרה אינטראקטיביים או שאלות ותשובות מורכבות. +**שיחה מרובת סבבים** - לשיחות שדורשות הקשר. המודל זוכר הודעות קודמות ובונה עליהן. השתמשו בזה למפגשי עזרה אינטראקטיביים או שאלות ותשובות מורכבות. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -הדיאגרמה הבאה ממחישה כיצד מצטבר הקשר השיח עם כל סבב וכיצד הוא משפיע על מגבלת הטוקנים של המודל. +הדיאגרמה הבאה ממחישה כיצד הקשר השיחה מצטבר בכל סבב ואיך זה מתקשר למגבלת הטוקנים של המודל. זיכרון הקשר -*כיצד מצטבר הקשר השיח על פני מספר סבבים עד להגעה למגבלת הטוקנים* -**הסבר צעד-אחר-צעד** - עבור בעיות הדורשות לוגיקה גלויה. המודל מציג הסבר מפורש עבור כל שלב. השתמש בזה עבור בעיות מתמטיות, חידות לוגיות, או כאשר אתה צריך להבין את תהליך החשיבה. +*כיצד מצטבר הקשר שיחה על פני סבבים רבים עד שמגיעים למגבלת הטוקנים* + +**היסק שלב אחר שלב** - לבעיות שדורשות לוגיקה גלויה. המודל מראה היגיון מפורש עבור כל שלב. השתמשו בזה לבעיות מתמטיות, חידות לוגיות, או כשאתם צריכים להבין את תהליך החשיבה. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -הדיאגרמה למטה ממחישה כיצד המודל מפרק בעיות לשלבים לוגיים מפורשים וממוספרים. - -תבנית צעד-אחר-צעד +הדיאגרמה למטה ממחישה כיצד המודל מפרק בעיות לצעדים לוגיים מפורשים וממוספרים. -*פירוק בעיות לשלבים לוגיים מפורשים* +תבנית שלב אחר שלב +*פירוק בעיות לצעדים לוגיים מפורשים* -**פלט מוגבל** - עבור תגובות עם דרישות פורמט ספציפיות. המודל עומד בקפדנות בחוקי הפורמט והאורך. השתמש בזה עבור סיכומים או כאשר אתה צריך מבנה פלט מדויק. +**פלט מוגבל** - לתשובות עם דרישות פורמט ספציפיות. המודל פועל בקפדנות לפי כללי הפורמט והאורך. השתמש בזה לסיכומים או כאשר נדרש מבנה פלט מדויק. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -הדיאגרמה הבאה מראה כיצד מגבלות מנחות את המודל לייצר פלט המתאים בקפדנות לדרישות הפורמט והאורך שלך. +הדיאגרמה הבאה ממחישה כיצד מגבלות מנחות את המודל לייצר פלט שמקפיד לשמור בקפדנות על דרישות הפורמט והאורך שלך. -תבנית פלט מוגבל +Constrained Output Pattern *אכיפת דרישות פורמט, אורך ומבנה ספציפיות* -## הפעלת היישום +## הרצת היישום **אימות פריסה:** -ודא שקובץ ה-`.env` קיים בתיקיית השורש עם האישורים של Azure (נוצר במהלך מודול 01). הפעל זאת מתיקיית המודול (`02-prompt-engineering/`): +ודא שקובץ ה-`.env` קיים בספריית השורש עם האישורים של Azure (נוצר במהלך מודול 01). הרץ זאת מספריית המודול (`02-prompt-engineering/`): **Bash:** ```bash @@ -439,32 +439,32 @@ cat ../.env # צריך להציג את AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYME **PowerShell:** ```powershell -Get-Content ..\.env # צריך להציג את AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # צריך להציג AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **הפעל את היישום:** -> **הערה:** אם כבר הפעלת את כל היישומים באמצעות `./start-all.sh` מתיקיית השורש (כמתואר במודול 01), מודול זה כבר רץ על פורט 8083. ניתן לדלג על פקודות ההפעלה למטה ולעבור ישירות ל-http://localhost:8083. +> **הערה:** אם כבר הפעלת את כל היישומים באמצעות `./start-all.sh` מספריית השורש (כמו שמתואר במודול 01), מודול זה כבר רץ בפורט 8083. ניתן לדלג על פקודות ההפעלה למטה ולעבור ישירות ל- http://localhost:8083. -**אפשרות 1: שימוש בלוח ניהול Spring Boot (מומלץ למשתמשי VS Code)** +**אפשרות 1: שימוש ב-Spring Boot Dashboard (מומלץ למשתמשי VS Code)** -מיכל הפיתוח כולל את התוסף Spring Boot Dashboard, המספק ממשק ויזואלי לניהול כל יישומי Spring Boot. ניתן למצוא אותו בסרגל הפעילות בצד השמאלי של VS Code (חפש את סמל Spring Boot). +מיכל המפתחים כולל את תוסף Spring Boot Dashboard, שנותן ממשק חזותי לניהול כל יישומי Spring Boot. ניתן למצוא אותו בסרגל הפעילות בצד שמאל של VS Code (חפש את סמל Spring Boot). -ממול לוח ניהול Spring Boot, ניתן: +מן ה-Spring Boot Dashboard ניתן: - לראות את כל יישומי Spring Boot הזמינים בסביבת העבודה - להפעיל/להפסיק יישומים בלחיצה אחת -- להציג לוגים של היישום בזמן אמת +- לצפות בלוגים של היישום בזמן אמת - לנטר את מצב היישום -פשוט לחץ על כפתור ההפעלה ליד "prompt-engineering" כדי להפעיל את המודול, או הפעל את כל המודולים ביחד. +פשוט לחץ על כפתור ההפעלה ליד "prompt-engineering" כדי להפעיל את המודול הזה, או הפעל את כל המודולים בבת אחת. -לוח ניהול Spring Boot +Spring Boot Dashboard -*לוח ניהול Spring Boot ב-VS Code — הפעלה, הפסקה ומעקב אחר כל המודולים ממקום אחד* +*לוח הבקרה של Spring Boot ב-VS Code — הפעל, עצור וצפה במעקב אחרי כל המודולים במקום אחד* -**אפשרות 2: שימוש בסקריפטים של shell** +**אפשרות 2: שימוש בסקריפטים ב-shell** -הפעל את כל יישומי הרשת (מודולים 01-04): +הפעל את כל יישומי האינטרנט (מודולים 01-04): **Bash:** ```bash @@ -478,7 +478,7 @@ cd .. # מספריית השורש .\start-all.ps1 ``` -או הפעל רק את המודול הזה: +או הפעל רק מודול זה: **Bash:** ```bash @@ -492,7 +492,7 @@ cd 02-prompt-engineering .\start.ps1 ``` -שני הסקריפטים טוענים אוטומטית משתני סביבה מקובץ ה-`.env` בשורש ויבנו את קבצי ה-JAR אם הם לא קיימים. +שני הסקריפטים טוענים אוטומטית משתני סביבה מקובץ ה-`.env` שבשורש ויבנו את קבצי ה-JAR במידה ואינם קיימים. > **הערה:** אם אתה מעדיף לבנות את כל המודולים ידנית לפני ההפעלה: > @@ -501,7 +501,7 @@ cd 02-prompt-engineering > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -510,87 +510,87 @@ cd 02-prompt-engineering פתח את http://localhost:8083 בדפדפן שלך. -**כדי לעצור:** +**להפסקה:** **Bash:** ```bash -./stop.sh # מודול זה בלבד +./stop.sh # רק מודול זה # או cd .. && ./stop-all.sh # כל המודולים ``` **PowerShell:** ```powershell -.\stop.ps1 # מודול זה בלבד +.\stop.ps1 # רק מודול זה # או cd ..; .\stop-all.ps1 # כל המודולים ``` ## צילומי מסך של היישום -הנה הממשק הראשי של מודול הנדסת הפרומפטים, שבו ניתן להתנסות בכל שמונת הדפוסים זה לצד זה. +הנה ממשק הראשי של מודול הנדסת הפרומפטים, בו אפשר להתנסות בכל שמונת התבניות זה לצד זה. -הממשק הראשי +Dashboard Home -*הלוח הראשי המציג את כל 8 דפוסי הנדסת פרומפט עם התכונות ומקרי השימוש שלהם* +*לוח הבקרה הראשי המציג את כל 8 תבניות הנדסת הפרומפטים עם המאפיינים ומקרי השימוש שלהן* -## חקר הדפוסים +## חקר התבניות -ממשק הרשת מאפשר לך להתנסות באסטרטגיות פרומפט שונות. כל דפוס פותר בעיות שונות - נסה אותם כדי לראות מתי כל גישה בולטת. +ממשק האינטרנט מאפשר לך להתנסות באסטרטגיות פרומפט שונות. כל תבנית פותרת בעיות שונות - נסה לראות מתי כל גישה בהירה יותר. -> **הערה: שידור מול לא-שידור** — בכל דף דפוס מוצעים שני כפתורים: **🔴 שידור תגובה (חי)** ואפשרות **לא-שידור**. שידור משתמש ב-Server-Sent Events (SSE) להצגת הטוקנים בזמן אמת כשהמודל מייצר אותם, כך שאתה רואה התקדמות מיידית. האופציה הלא-שידורית מחכה לתגובה המלאה לפני ההצגה. עבור פרומפטים המפעילים חשיבה מעמיקה (למשל, High Eagerness, קוד המשתקף עצמי), הקריאה הלא-שידורית יכולה לקחת זמן רב מאוד — לפעמים דקות — ללא משוב גלוי. **השתמש בשידור בעת התנסות עם פרומפטים מורכבים** כדי שתוכל לראות את המודל פועל ולהימנע מהתרשמות שהבקשה נתקעה. +> **הערה: סטרימינג מול אי-סטרימינג** — כל דף תבנית כולל שני כפתורים: **🔴 זרם תגובה (חי)** ואפשרות **לא סטרימינג**. סטרימינג משתמש ב-Server-Sent Events (SSE) כדי להציג את הטוקנים בזמן אמת כשהמודל מייצר אותם, כך שאתה רואה את ההתקדמות מיידית. האופציה הלא סטרימינג מחכה לתגובה המלאה לפני התצוגה. בפרומפטים שדורשים חשיבה עמוקה (כגון High Eagerness, קוד המשתקף מעצמו), הקריאה הלא סטרימינג יכולה לקחת זמן רב מאוד — לפעמים דקות — בלי משוב ויזואלי. **השתמש בסטרימינג כשאתה מתנסה בפרומפטים מורכבים** כדי לראות את המודל פועל ולהימנע מהרגשת כתובת בקשת זמן. > -> **הערת דפדפן** — תכונת השידור משתמשת ב-Fetch Streams API (`response.body.getReader()`) הדורש דפדפן מלא (Chrome, Edge, Firefox, Safari). היא **אינה עובדת** בדפדפן הפשוט המובנה של VS Code, שכן ה-webview שלו לא תומך ב-ReadableStream API. אם אתה משתמש בדפדפן הפשוט, הכפתורים הלא-שידוריים יעבדו כרגיל — רק כפתורי השידור מושפעים. פתח `http://localhost:8083` בדפדפן חיצוני לחוויה מלאה. +> **הערה: דרישת דפדפן** — תכונת הסטרימינג עושה שימוש ב-Fetch Streams API (`response.body.getReader()`) שדורש דפדפן מלא (Chrome, Edge, Firefox, Safari). זה **לא** עובד בדפדפן הפשוט המובנה ב-VS Code, שכן ה-webview שלו אינו תומך ב-ReadableStream API. אם אתה משתמש בשחקן הפשוט, כפתורי הלא סטרימינג יעבדו כסדרם — רק כפתורי הסטרימינג יושפעו. פתח את `http://localhost:8083` בדפדפן חיצוני לקבלת החוויה המלאה. -### נמוך מול גבוה בהתלהבות +### Eagerness נמוכה מול גבוהה -שאול שאלה פשוטה כמו "מה זה 15% מתוך 200?" באמצעות Low Eagerness. תקבל תשובה ישירה ומידית. עכשיו שאל שאלה מורכבת כמו "עצב אסטרטגיית מטמון ל-API בתעבורה גבוהה" באמצעות High Eagerness. לחץ **🔴 שידור תגובה (חי)** וצפה בהופעת ההסבר המפורט של המודל טוקן אחרי טוקן. אותו מודל, אותה שאלה – אבל הפרומפט מורה כמה לחשוב. +שאול שאלה פשוטה כמו "כמה זה 15% מ-200?" באמצעות Eagerness נמוכה. תקבל תשובה ישירה ומיידית. עכשיו שאול משהו מורכב כמו "עצב אסטרטגיית מטמון עבור API בעומס גבוה" עם Eagerness גבוהה. לחץ על **🔴 זרם תגובה (חי)** וצפה בנימוקים המפורטים של המודל מופיעים טוקן אחר טוקן. אותו מודל, אותו מבנה שאלה - אבל הפרומפט אומר לו כמה לחשוב. -### ביצוע משימה (קדימונים לכלים) +### ביצוע משימות (פתיחי כלים) -זרימות עבודה מרובות שלבים מרוויחות מתכנון מראש וסיפור התקדמות. המודל מפרט מה יעשה, מתאר כל שלב, ואז מסכם תוצאות. +זרימות עבודה מרובות שלבים מרוויחות מתכנון מראש ונרטיב התקדמות. המודל מפרט מה יעשה, מתאר כל שלב, ואז מסכם תוצאות. -### קוד המשתקף עצמי +### קוד המשתקף מעצמו -נסה "צור שירות לאימות דואר אלקטרוני". במקום רק להפיק קוד ולעצור, המודל מייצר, מעריך לפי קריטריוני איכות, מזהה חולשות ומשפר. תראה אותו חוזר על עצמו עד שהקוד עומד בסטנדרטים של ייצור. +נסה "צור שירות לאימות אימייל". במקום רק ליצור קוד ולעצור, המודל מייצר, מעריך לפי קריטריוני איכות, מזהה חולשות ומשפר. תראה אותו ממשיך עד שהקוד עומד בסטנדרטים לייצור. ### ניתוח מובנה -סקירות קוד דורשות מסגרות הערכה עקביות. המודל מנתח קוד לפי קטגוריות קבועות (נכונות, שיטות, ביצועים, אבטחה) עם רמות חומרה. +סקירות קוד צריכות מסגרות הערכה עקביות. המודל מנתח קוד לפי קטגוריות קבועות (נכונות, פרקטיקות, ביצועים, אבטחה) עם דרגות חומרה. ### שיחה מרובת סבבים -שאול "מה זה Spring Boot?" ואז מיד המשך עם "הראה לי דוגמה". המודל זוכר את השאלה הראשונה ונותן דוגמת Spring Boot ספציפית. בלי זיכרון, השאלה השנייה הייתה מעורפלת מדי. +שאול "מה זה Spring Boot?" ואז מיד המשך ב"הראה לי דוגמה". המודל זוכר את השאלה הראשונה ונותן דוגמת Spring Boot ספציפית. בלי זיכרון, השאלה השנייה הייתה כללית מדי. -### הסבר צעד-אחר-צעד +### נימוקים שלב-אחר-שלב -בחר בעיית מתמטיקה ונסה אותה הן עם הסבר צעד-אחר-צעד והן עם Low Eagerness. ההתלהבות הנמוכה נותנת רק את התשובה - מהיר אך לא שקוף. בהסבר צעד-אחר-צעד תראה כל חישוב והחלטה. +בחר בעיה מתמטית ונסה אותה עם נימוקים שלב-אחר-שלב ועם Eagerness נמוכה. Eagerness נמוכה נותן רק את התשובה — מהיר אבל לא מובן. נימוקים שלב-אחר-שלב מראים כל חישוב והחלטה. ### פלט מוגבל -כשהדרוש פורמטים מסוימים או ספירת מילים, דפוס זה מאכף עמידה מדויקת. נסה לייצר סיכום במדויק עם 100 מילים בפורמט נקודות. +כשנדרשים פורמטים ספציפיים או ספירת מילים, תבנית זו מכריחה שמירה קפדנית. נסה לייצר סיכום עם בדיוק 100 מילים בפורמט נקודות. -## מה שלומדים באמת +## מה שלמעשה אתה לומד -**מאמץ ההסבר משנה הכל** +**מאמץ נימוק משנה הכל** -GPT-5.2 מאפשר לך לשלוט במאמץ המחשובי דרך הפרומפטים שלך. מאמץ נמוך נותן תגובות מהירות עם חקירה מינימלית. מאמץ גבוה מביא את המודל להשקיע מחשבה עמוקה. אתה לומד להתאים את המאמץ למורכבות המשימה — אל תבזבז זמן על שאלות פשוטות, אבל אל תמהר בהחלטות מורכבות. +GPT-5.2 מאפשר לך לשלוט במאמץ החישובי דרך הפרומפטים שלך. מאמץ נמוך משמעותו תגובות מהירות עם חיפוש מינימלי. מאמץ גבוה אומר שהמודל משקיע זמן לחשוב לעומק. אתה לומד להתאים מאמץ למורכבות המשימה - אל תבזבז זמן על שאלות פשוטות, אבל גם אל למהר להחליט על דברים מורכבים. -**מבנה מנהל התנהגות** +**מבנה מכוון התנהגות** -שמתי לב לתגי XML בפרומפטים? הם לא רק לקישוט. מודלים עומדים בהוראות מובנות בצורה אמינה יותר מאשר טקסט חופשי. כשאתה צריך תהליכים רב-שלביים או לוגיקה מורכבת, המבנה עוזר למודל לעקוב מהיכן הוא ומה הבא. הדיאגרמה למטה מפרקת פרומפט ממוסגר היטב, ומראה כיצד תגיות כמו ``, ``, ``, ``, ו-`` מארגנות את ההוראות לחלקים ברורים. +שמעת את תגי ה-XML בפרומפטים? הם לא לקישוט. מודלים פועלים לפי הוראות מובנות בצורה מהימנה יותר מטקסט חופשי. כשצריך תהליכים מרובי שלבים או לוגיקה מורכבת, המבנה עוזר למודל לעקוב היכן הוא ומה הבא. הדיאגרמה למטה מפצלת פרומפט מובנה היטב, ומראה איך תגיות כמו ``, ``, ``, ``, ו-`` מארגנות את ההוראות שלך לסעיפים ברורים. -מבנה הפרומפט +Prompt Structure -*אנטומיה של פרומפט מובנה היטב עם חלקים ברורים וארגון בסגנון XML* +*אנטומיה של פרומפט מובנה היטב עם סעיפים ברורים וארגון בסגנון XML* **איכות דרך הערכה עצמית** -דפוסי ההשתקפות העצמית פועלים על ידי הפיכת קריטריוני האיכות למפורשים. במקום לקוות שהמודל "יעשה נכון", אתה אומר במדויק מה זה "נכון": לוגיקה נכונה, טיפול בשגיאות, ביצועים, אבטחה. המודל יכול להעריך את הפלט שלו ולשפר אותו. זה ממיר ייצור קוד מגלגל לוטו לתהליך מוגדר. +תבניות המשתקפות מעצמן פועלות על ידי הפיכת קריטריוני האיכות לברורים. במקום לקוות שהמודל "יעשה נכון", אתה אומר לו בדיוק מהי "נכונות": לוגיקה תקינה, טיפול בשגיאות, ביצועים, אבטחה. המודל יכול אז להעריך את הפלט שלו ולשפר. זה הופך יצירת קוד מהגרלה לתהליך מבוקר. -**הקשר הוא מוגבל** +**הקשר הוא סופי** -שיחות רב-סבביות פועלות על ידי הכללת היסטוריית ההודעות עם כל בקשה. אך יש גבול - לכל מודל יש מספר טוקנים מקסימלי. ככל שהשיחות מתארכות, תזדקק לאסטרטגיות לשמירה על ההקשר הרלוונטי מבלי להגיע לתקרה הזו. מודול זה מראה לך כיצד זיכרון עובד; מאוחר יותר תלמד מתי לסכם, מתי לשכוח ומתי לשלוף. +שיחות מרובות סבבים פועלות על ידי הכללת היסטוריית ההודעות בכל בקשה. אך יש גבול - לכל מודל יש מספר טוקנים מקסימלי. ככל שהשיחות מתקצרות, אתה תצטרך אסטרטגיות לשמור על הקשר רלוונטי מבלי לחרוג מהמקסימום. המודול הזה מראה לך איך הזיכרון עובד; אחרי זה תלמד מתי לסכם, מתי לשכוח ומתי לשלוף. ## צעדים הבאים @@ -598,11 +598,11 @@ GPT-5.2 מאפשר לך לשלוט במאמץ המחשובי דרך הפרומפ --- -**ניווט:** [← קודם: מודול 01 - מבוא](../01-introduction/README.md) | [חזרה לעיקרי](../README.md) | [הבא: מודול 03 - RAG →](../03-rag/README.md) +**ניווט:** [← קודם: מודול 01 - מבוא](../01-introduction/README.md) | [חזרה לעמוד הראשי](../README.md) | [הבא: מודול 03 - RAG →](../03-rag/README.md) --- -**הצהרת זכויות**: -מסמך זה תורגם באמצעות שירות תרגום מבוסס בינה מלאכותית [Co-op Translator](https://github.com/Azure/co-op-translator). על אף שאנו שואפים לדיוק, יש להביא בחשבון כי תרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. המסמך המקורי בשפתו המקורית ייחשב כמקור הסמכות. עבור מידע קריטי, מומלץ לתרגם על ידי מתרגם מקצועי אנושי. אנו אינם אחראים לכל אי הבנה או פרשנות שגויה הנובעים משימוש בתרגום זה. +**כתב ויתור**: +מסמך זה תורגם באמצעות שירות תרגום אוטומטי [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש להחשיב את המסמך המקורי בשפתו הטבעית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אדם. אנו לא אחראים לכל אי-הבנה או פירוש שגוי הנובע מהשימוש בתרגום זה. \ No newline at end of file diff --git a/translations/he/03-rag/README.md b/translations/he/03-rag/README.md index 91a63769d..96954c70a 100644 --- a/translations/he/03-rag/README.md +++ b/translations/he/03-rag/README.md @@ -1,144 +1,144 @@ -# מודול 03: RAG (הפקה עם חיפוש משולב) +# מודול 03: RAG (יצירה מוגברת באמצעות חיפוש) -## תוכן עניינים +## תוכן העניינים -- [סדרת וידאו](../../../03-rag) -- [מה תלמד](../../../03-rag) -- [דרישות מוקדמות](../../../03-rag) -- [הבנת RAG](../../../03-rag) - - [איזה גישת RAG השיעור הזה משתמש?](../../../03-rag) -- [איך זה עובד](../../../03-rag) - - [עיבוד מסמכים](../../../03-rag) - - [יצירת הטמעות](../../../03-rag) - - [חיפוש סמנטי](../../../03-rag) - - [יצירת תשובות](../../../03-rag) -- [הרץ את היישום](../../../03-rag) -- [שימוש ביישום](../../../03-rag) - - [העלה מסמך](../../../03-rag) - - [שאול שאלות](../../../03-rag) - - [בדוק הפניות מקור](../../../03-rag) - - [נסו ניסויים עם שאלות](../../../03-rag) -- [מונחים עיקריים](../../../03-rag) - - [אסטרטגיית חתיכות](../../../03-rag) - - [ציוני דמיון](../../../03-rag) - - [אחסון בזיכרון](../../../03-rag) - - [ניהול חלון הקשר](../../../03-rag) -- [מתי RAG חשוב](../../../03-rag) -- [השלבים הבאים](../../../03-rag) +- [סרטון הדרכה](#סרטון-הדרכה) +- [מה תלמדו](#מה-תלמדו) +- [דרישות מקדימות](#דרישות-מקדימות) +- [הבנת RAG](#הבנת-rag) + - [איזו גישת RAG מכסה המדריך הזה?](#איזו-גישת-rag-מכסה-המדריך-הזה) +- [איך זה עובד](#איך-זה-עובד) + - [עיבוד מסמכים](#עיבוד-מסמכים) + - [יצירת השתקפויות](#יצירת-השתקפויות) + - [חיפוש סמנטי](#חיפוש-סמנטי) + - [הפקת תשובות](#יצירת-תשובות) +- [הפעלת האפליקציה](#הפעלת-היישום) +- [שימוש באפליקציה](#שימוש-ביישום) + - [העלאת מסמך](#העלאת-מסמך) + - [שאילת שאלות](#שאל-שאלות) + - [בדיקת מקורות](#בדוק-הפניות-למקורות) + - [ניסויים עם שאלות](#נסה-שאלות-שונות) +- [מושגים מרכזיים](#מושגים-מרכזיים) + - [אסטרטגיית חלוקה לנתחים](#אסטרטגיית-חיתוך-לחתיכות) + - [דירוגי דמיון](#ציוני-דמיון) + - [אחסון בזיכרון](#אחסון-בזיכרון) + - [ניהול חלון הקשר](#ניהול-חלון-הקשר) +- [מתי RAG חשוב](#מתי-rag-חשוב) +- [שלבים הבאים](#השלבים-הבאים) -## סדרת וידאו +## סרטון הדרכה -צפו במפגש חי זה שמסביר כיצד להתחיל עם מודול זה: +צפו במפגש חי זה שמסביר איך להתחיל עם מודול זה: -RAG עם LangChain4j - מפגש חי +RAG with LangChain4j - Live Session -## מה תלמד +## מה תלמדו -במודולים הקודמים למדת כיצד לקיים שיחות עם AI ולבנות בפרומפטים באופן אפקטיבי. אך יש הגבלה בסיסית: דגמי שפה יודעים רק את מה שלמדו במהלך האימון. הם לא יכולים לענות על שאלות על מדיניות החברה שלך, תיעוד הפרויקט שלך, או כל מידע שלא אומנו עליו. +במודולים הקודמים, למדתם איך לנהל שיחות עם AI ולבנות פרומפטים בצורה יעילה. אך יש מגבלה יסודית: מודלים של שפה יודעים רק את מה שלמדו במהלך האימון. הם לא יכולים לענות על שאלות לגבי מדיניות החברה שלכם, תיעוד הפרויקט, או כל מידע שלא אומן עליהם. -RAG (הפקה עם חיפוש משולב) פותר את הבעיה הזו. במקום לנסות ללמד את המודל את המידע שלך (הדבר יקר ובלתי מעשי), אתה נותן לו את היכולת לחפש בתוך המסמכים שלך. כאשר מישהו שואל שאלה, המערכת מוצאת מידע רלוונטי ומכלילה אותו בפרומפט. המודל אז עונה על סמך ההקשר שנמצא. +RAG (יצירה מוגברת באמצעות חיפוש) פותר את הבעיה הזו. במקום לנסות ללמד את המודל את המידע שלכם (מה שעלול להיות יקר ובלתי מעשי), אתם נותנים לו את היכולת לחפש בתוך המסמכים שלכם. כשמישהו שואל שאלה, המערכת מוצאת מידע רלוונטי ומכנסת אותו בפרומפט. המודל עונה על סמך הקשר זה. -תחשוב על RAG כמתן ספריית התייחסות למודל. כשאתה שואל שאלה, המערכת: +תחשבו על RAG כעל מתן ספריית התייחסות למודל. כשאתם שואלים שאלה, המערכת: -1. **שאילתת משתמש** - אתה שואל שאלה -2. **הטמעה** - ממיר את השאלה שלך לווקטור -3. **חיפוש וקטורי** - מוצא חתיכות מסמך דומות -4. **הרכבת הקשר** - מוסיף חתיכות רלוונטיות לפרומפט -5. **תגובה** - דגם שפה גדול מייצר תשובה בהסתמך על ההקשר +1. **שאלת משתמש** - אתם שואלים שאלה +2. **השתקפות** - המרה של שאלתכם לווקטור +3. **חיפוש בווקטורים** - מציאת נתחי מסמכים דומים +4. **הרכבת הקשר** - הוספת נתחי מידע רלוונטיים לפרומפט +5. **תגובה** - מודל השפה הגדול מייצר תשובה על בסיס ההקשר -זה מייסד את התשובות של המודל על הנתונים האמיתיים שלך במקום להסתמך על ידע האימון שלו או על המצאה של תשובות. +זה מבסס את התגובות של המודל על הנתונים האמיתיים שלכם במקום להסתמך על הידע מהאימון או על יצירת תשובות בדויות. -## דרישות מוקדמות +## דרישות מקדימות -- השלמת [מודול 00 - התחלה מהירה](../00-quick-start/README.md) (לדוגמה של Easy RAG שמוזכר בהמשך במודול זה) -- השלמת [מודול 01 - מבוא](../01-introduction/README.md) (משאבי Azure OpenAI שהופעלו, כולל דגם הטמעה `text-embedding-3-small`) -- קובץ `.env` בתיקיית השורש עם אישורי Azure (נוצר ע"י `azd up` במודול 01) +- השלמת [מודול 01 - מבוא](../01-introduction/README.md) (פריסת משאבי Azure OpenAI, כולל מודל ההשתקפות `text-embedding-3-small`) +- קובץ `.env` בספריית השורש עם אישורי Azure (נוצר על ידי `azd up` במודול 01) -> **הערה:** אם לא השלמת את מודול 01, עקוב אחר הוראות ההפעלה שם תחילה. הפקודה `azd up` מפעילה גם את דגם השיחה GPT וגם את דגם ההטמעה שבו משתמש מודול זה. +> **הערה:** אם לא השלמתם את מודול 01, עקבו קודם אחרי הוראות הפריסה שם. הפקודה `azd up` מפעילה את מודל הצ'אט GPT ואת מודל ההשתקפות המשמש במודול זה. ## הבנת RAG -הדיאגרמה למטה ממחישה את הרעיון המרכזי: במקום להסתמך רק על נתוני האימון של המודל, RAG מעניק לו ספריית התייחסות למסמכים שלך ליעוץ לפני יצירת כל תשובה. +הדיאגרמה למטה ממחישה את הרעיון הראשי: במקום להסתמך רק על נתוני האימון של המודל, RAG נותן לו ספריית התייחסות של המסמכים שלכם להתייעצות לפני הפקת כל תשובה. -מה זה RAG +What is RAG -*דיאגרמה זו מראה את ההבדל בין מודל שפה רגיל (שמתבסס על ניחושים מנתוני האימון) לבין מודל RAG משופר (שפונה למסמכים שלך קודם).* +*דיאגרמה זו מציגה את ההבדל בין מודל שפה רגיל (המנחש על סמך נתוני האימון) לבין מודל שפה מוגבר ב-RAG (המשתמש קודם במסמכי החברה).* -כך החלקים מתחברים מקצה לקצה. שאלה של משתמש זורמת דרך ארבעה שלבים — הטמעה, חיפוש וקטורי, הרכבת הקשר, ויצירת תשובה — שכל אחד מהם בונה על הקודם: +כך כל החלקים מתחברים מקצה אל קצה. שאלה של משתמש עוברת ארבעה שלבים — השתקפות, חיפוש וקטורי, הרכבת הקשר, והפקת תשובה — שכל אחד בנוי על הקודם: -ארכיטקטורת RAG +RAG Architecture -*דיאגרמה זו מציגה את צינור ה-RAG מקצה לקצה — שאילתת משתמש זורמת דרך הטמעה, חיפוש וקטורי, הרכבת הקשר ויצירת תשובה.* +*דיאגרמה זו מציגה את תהליך ה-RAG מקצה אל קצה — שאילתא עוברת דרך השתקפות, חיפוש וקטורי, הרכבת הקשר, והפקת תשובה.* -שאר המודול מפורט כל שלב עם הקוד שאתה יכול להריץ ולשנות. +שאר המודול מסביר כל שלב בפירוט, עם קוד שניתן להריץ ולשנות. -### איזה גישת RAG השיעור הזה משתמש? +### איזו גישת RAG מכסה המדריך הזה? -LangChain4j מציע שלוש דרכים ליישם RAG, כל אחת עם רמת הפשטה שונה. הדיאגרמה למטה משווה ביניהן זו לצד זו: +LangChain4j מציע שלוש דרכים ליישום RAG, כל אחת ברמת הפשטה שונה. הדיאגרמה למטה משווה ביניהן זו לצד זו: -שלוש גישות RAG ב-LangChain4j +Three RAG Approaches in LangChain4j -*דיאגרמה זו משווה בין שלוש גישות RAG של LangChain4j — Easy, Native ו-Advanced — ומציגה את הרכיבים המרכזיים ומתי להשתמש בכל אחת.* +*דיאגרמה זו משווה את שלוש הגישות ל-RAG ב-LangChain4j — Easy, Native, ו-Advanced — ומציגה את הרכיבים המרכזיים ומתי להשתמש בכל אחת.* -| גישה | מה היא עושה | תשלום / פשרה | +| גישה | מה היא עושה | פשרה | |---|---|---| -| **Easy RAG** | מחבר הכל אוטומטית דרך `AiServices` ו-`ContentRetriever`. אתה מגדיר ממשק, מצרף מחפש, ו-LangChain4j מנהל את ההטמעה, החיפוש והרכבת הפרומפט מאחורי הקלעים. | קוד מינימלי, אבל אינך רואה מה קורה בכל שלב. | -| **Native RAG** | אתה קורא ישירות לדגם ההטמעה, מחפש במאגר, בונה את הפרומפט, ומייצר את התשובה בעצמך — שלב מפורש בכל פעם. | יותר קוד, אבל כל שלב נראה וניתן לשינוי. | -| **Advanced RAG** | משתמש במסגרת `RetrievalAugmentor` עם מעבדים, מנתבים, מסדרים מחדש ומזריקים תוכן להתקנות צינורות הפקה. | גמישות מקסימלית, אבל מורכבות גבוהה מאוד. | +| **Easy RAG** | מחברת אוטומטית הכל דרך `AiServices` ו-`ContentRetriever`. אתם מגדירים ממשק, מחברים מחפש, ו-LangChain4j מטפל בהשתקפות, חיפוש והרכבת הפרומפט מאחורי הקלעים. | מינימום קוד, אך אינכם רואים מה קורה בכל שלב. | +| **Native RAG** | אתם קוראים למודל ההשתקפות, מחפשים במאגר, בונים את הפרומפט ומפיקים את התשובה בעצמכם — שלב אחר שלב במפורש. | יותר קוד, אך כל שלב גלוי וניתן לשינוי. | +| **Advanced RAG** | משתמש במסגרת `RetrievalAugmentor` עם ממירי שאלות, מפנים, מסדרים מחדש ומזריקים תוכן הניתנים להתאמה לצנרת ייצור. | גמישות מקסימלית, אך עם מורכבות גבוהה יותר. | -**השיעור הזה משתמש בגישת Native.** כל שלב בצינור RAG — הטמעת השאלה, חיפוש במאגר הווקטורי, הרכבת ההקשר ויצירת התשובה — כתוב במפורש ב-[`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). זה מכוון: כחומר לימוד, חשוב יותר שתראה ותבין כל שלב מאשר שהקוד יהיה מקוצר. ברגע שאתה מרגיש נוח עם איך הדברים מתחברים, תוכל להתקדם ל-Easy RAG לפרוטוטייפים או ל-Advanced RAG למערכות ייצור. +**המדריך הזה משתמש בגישת Native.** כל שלב בצנרת RAG — השתקפות השאלה, חיפוש במאגר הווקטורים, הרכבת ההקשר, והפקת התשובה — כתוב בפירוש ב־[`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). זה מכוון: כמקור ללמידה, חשוב לראות ולהבין כל שלב לעומת קוד מקוצר. כשתרגישו נוח עם רצף השלבים, תוכלו לעבור ל-Easy RAG לפרוטוטייפים מהירים או ל-Advanced RAG למערכות ייצור. -> **💡 כבר ראית את Easy RAG בפעולה?** מודול [Quick Start](../00-quick-start/README.md) כולל דוגמת שאלות ותשובות על מסמכים ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) שמשתמשת בגישת Easy RAG — LangChain4j מטפל בהטמעה, חיפוש והרכבת הפרומפט באופן אוטומטי. מודול זה לוקח את הצעד הבא על ידי פירוק הצינור כך שתוכל לראות ולשלוט בכל שלב בעצמך. +> **💡 סקרנים לגבי Easy RAG?** LangChain4j גם מציע גישת *Easy RAG* בה "AiServices" ו-"ContentRetriever" מטפלות בהשתקפות, חיפוש והרכבת הפרומפט אוטומטית. מודול זה לוקח את הדרך הברורה — פותח את הצנרת הזו לידיכם כדי שתוכלו לראות ולשלוט בכל שלב בעצמכם. -הדיאגרמה למטה מראה את צינור Easy RAG מהדוגמה של Quick Start. שים לב איך `AiServices` ו-`EmbeddingStoreContentRetriever` מכסים את כל המורכבות — אתה טוען מסמך, מצרף מחפש, ומקבל תשובות. הגישת Native במודול זה מפורקת כל אחת מהשלבים הנסתרים: +הדיאגרמה למטה מראה את צנרת Easy RAG. שימו לב איך `AiServices` ו-`EmbeddingStoreContentRetriever` מסתירים את כל המורכבות — אתם טוענים מסמך, מחברים מחפש, ומקבלים תשובות. הגישה Native במודול זה מפורקת לשלבים גלויים: -צינור Easy RAG - LangChain4j +Easy RAG Pipeline - LangChain4j -*דיאגרמה זו מציגה את צינור Easy RAG מ-`SimpleReaderDemo.java`. השווה זאת עם גישת Native שבמודול זה: Easy RAG מסתיר את ההטמעה, החיפוש והרכבת הפרומפט מאחורי `AiServices` ו-`ContentRetriever` — אתה טוען מסמך, מצרף מחפש, ומקבל תשובות. גישת Native במודול זה מפרקת את הצינור כך שאתה קורא כל שלב (הטמע, חפש, הרכב הקשר, הפק) בעצמך, ומספקת לך נראות ושליטה מלאות.* +*דיאגרמה זו מציגה את צנרת Easy RAG. השוו זאת לגישת Native שבמודול זה: Easy RAG מסתיר את ההשתקפות, החיפוש והרכבת הפרומפט מאחורי `AiServices` ו-`ContentRetriever` — אתם טוענים מסמך, מחברים מחפש, ומקבלים תשובות. בגישת Native פורקים את הצנרת הזו כך שקוראים כל שלב בעצמכם (השתקפות, חיפוש, הרכבת הקשר, הפקת תשובה), מה שמאפשר שליטה וצפייה מלאה.* ## איך זה עובד -צינור ה-RAG במודול זה מפורק לארבעה שלבים המופעלים ברצף בכל פעם שמשתמש שואל שאלה. ראשית, מסמך שהועלה **מפורש ומחולק לחתיכות** לחלקים ניתנים לניהול. חתיכות אלה מומרות ל**הטמעות וקטוריות** ומאוחסנות כך שניתן יהיה להשוות אותן מתמטית. כשהשאילתא מגיעה, המערכת מבצעת **חיפוש סמנטי** כדי למצוא את החתיכות הרלוונטיות ביותר, ולבסוף מעבירה אותן להקשר ל-LLM עבור **יצירת תשובה**. הסעיפים הבאים יסבירו כל שלב עם הקוד והדיאגרמות. נתחיל משלב ראשון. +צנרת ה-RAG במודול זה מתחלקת לארבעה שלבים שמתרחשים ברצף בכל פעם שמשתמש שואל שאלה. קודם, המסמך שהועלה נערך ומחולק ל**נתחים** קטנים ונוחים לעיבוד. נתחי המסמך מומרות ל**השתקפויות וקטוריות** ונאחסנות להשוואה מתמטית. כאשר מתקבלת שאילתא, המערכת מבצעת **חיפוש סמנטי** למציאת הנתחי המסמך הרלוונטיים, ולבסוף מעבירה אותם כהקשר למודל השפה להפקת **התשובה**. הסעיפים הבאים מפרטים כל שלב עם הקוד והדיאגרמות המתאימות. נתחיל עם השלב הראשון. ### עיבוד מסמכים [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -כשאתה מעלה מסמך, המערכת מפרשת אותו (PDF או טקסט פשוט), מצרפת מטא-דאטה כמו שם הקובץ, ואז מחלקת אותו לחתיכות — חלקים קטנים יותר שמתאימים בנוחות לחלון ההקשר של המודל. החתיכות חופפות במעט כך שלא יאבד ההקשר בגבולות. +כשאתם מעלים מסמך, המערכת מנתחת אותו (PDF או טקסט פשוט), מצרפת מטא-נתונים כמו שם הקובץ, ואז מחלקת אותו לנתחים — חתיכות קטנות שמתאימות בנוחות לחלון ההקשר של המודל. נתחי המסמך חופפים במעט כדי לא לאבד הקשר בגבולות הבלוקים. ```java // נתח את הקובץ שהועלה ועטוף אותו במסמך LangChain4j Document document = Document.from(content, metadata); -// חלק לחתיכות של 300 טוקנים עם חפיפה של 30 טוקנים +// חלק לחתיכות של 300 תווים עם חפיפה של 30 תווים DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -הדיאגרמה למטה מראה איך זה עובד בצורה ויזואלית. שים לב כיצד כל חתיכה חולקת כמה טוקנים עם השכנות שלה — חפיפה של 30 טוקנים מבטיחה שלא יאבד הקשר חשוב בין החתיכות: -חלוקת מסמך לחתיכות +הדיאגרמה למטה מציגה זאת באופן חזותי. שימו לב שכל נתח חולק טוקנים עם שכניו — חפיפה של 30 טוקנים מבטיחה שאין הקשר מפספס בין הבלוקים: -*דיאגרמה זו מציגה מסמך שמתחלק לחתיכות של 300 טוקנים עם חפיפה של 30 טוקנים, לשימור ההקשר בגבולות החתיכות.* +Document Chunking -> **🤖 נסה עם [GitHub Copilot](https://github.com/features/copilot) Chat:** פתח את [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ושאל: -> - "איך LangChain4j מחלק מסמכים לחתיכות ולמה החפיפה חשובה?" -> - "מה הגודל האופטימלי של חתיכה לסוגי מסמכים שונים ולמה?" -> - "איך לטפל במסמכים בשפות מרובות או עם עיצוב מיוחד?" +*דיאגרמה זו מציגה את חלוקת המסמך לנתחים בגודל 300 טוקנים עם חפיפה של 30 טוקנים, לשמירת ההקשר בגבולות הנתחים.* -### יצירת הטמעות +> **🤖 נסו עם [GitHub Copilot](https://github.com/features/copilot) Chat:** פתחו את [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ושאלו: +> - "איך LangChain4j מחלק מסמכים לנתחים ולמה החפיפה חשובה?" +> - "מה גודל הנתח האופטימלי לסוגי מסמכים שונים ומדוע?" +> - "איך מטפלים במסמכים בשפות מרובות או עם עיצוב מיוחד?" + +### יצירת השתקפויות [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -כל חתיכה מומרת לייצוג מספרי שנקרא הטמעה — למעשה ממיר משמעות למספרים. דגם ההטמעה אינו "חכם" כמו דגם שיחה; הוא לא יכול לבצע הוראות, להסיק מסקנות או לענות על שאלות. מה שהוא יודע לעשות הוא למפות טקסט לחלל מתמטי שבו משמעויות דומות קרובות זו לזו — "רכב" קרוב ל"אוטומוביל", "מדיניות החזרות" קרוב ל"החזר כספי שלי". תחשוב על דגם שיחה כעל אדם שאפשר לדבר איתו; דגם הטמעה הוא מערכת ארכוב טובה במיוחד. +כל נתח מומר לייצוג מספרי הנקרא השתקפות — בעצם ממיר משמעות למספרים. מודל ההשתקפות אינו "חכם" כמו מודל צ'אט; הוא לא מבצע הוראות, לא מסיק מסקנות ולא עונה על שאלות. מה שהוא כן עושה הוא למפות טקסט לחלל מתמטי שבו משמעויות דומות מתרכזות קרוב זו לזו — "car" ו-"automobile" קרובים, "מדיניות החזר" קרובה ל-"אחזיר את כספי". חשבו על מודל צ'אט כאדם שאפשר לדבר איתו; מודל השתקפות הוא מערכת מיון מצוינת. -הדיאגרמה למטה ממחישה את הקונספט — טקסט נכנס, וקטורים מספריים יוצאים, ומשמעויות דומות יוצרות וקטורים קרובים: +הדיאגרמה למטה ממחישה את הקונספט — טקסט נכנס, וקטורים מספריים יוצאים, ומשמעויות דומות ממוקמות קרוב בחלל הווקטורי: -קונספט דגם הטמעה +Embedding Model Concept -*דיאגרמה זו מראה כיצד דגם הטמעה ממיר טקסט לווקטורים מספריים, כשמשמעויות דומות — כמו "רכב" ו"אוטומוביל" — קרובות אחת לשנייה במרחב הווקטורי.* +*דיאגרמה זו מראה איך מודל השתקפות ממיר טקסט לווקטורים מספריים, ומניח משמעויות דומות — כמו "car" ו-"automobile" — סמוך זו לזו במרחב הווקטורי.* ```java @Bean @@ -154,29 +154,30 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -דיאגרמת המחלקה למטה מראה את שני זרמי העבודה בצינור RAG ואת מחלקות LangChain4j המיישמות אותם. **זרם ההכנסה** (רץ פעם אחת בעת ההעלאה) מחלק את המסמך, מממש את ההטמעות, ומאחסן אותן באמצעות `.addAll()`. **זרם השאילתא** (רץ בכל פעם שמשתמש שואל) מממש את השאלה, מחפש במאגר דרך `.search()`, ומעביר את ההקשר המתאים לדגם השיחה. שני הזרמים נפגשים בממשק המשותף `EmbeddingStore`: -מחלקות RAG של LangChain4j +דיאגרמת המחלקות למטה מראה את שתי זרימות העבודה בצנרת RAG ואת מחלקות LangChain4j שמממשות אותן. **זרם הבליעה** (רץ פעם אחת בעת ההעלאה) מחלק את המסמך, משתקף את הנתחים, ואוגר אותם באמצעות `.addAll()`. **זרם השאילתות** (רץ בכל פעם שמשתמש שואל) משתקף את השאלה, מחפש במאגר באמצעות `.search()`, ומעביר את ההקשר התואם למודל הצ'אט. שתי הזרימות נפגשות בממשק המשותף `EmbeddingStore`: + +LangChain4j RAG Classes -*דיאגרמה זו מראה את שני הזרמים בצינור RAG — הכנסת נתונים ושאילתות — ואיך הם מחוברים דרך EmbeddingStore משותף.* +*דיאגרמה זו מציגה את שתי הזרימות בצנרת RAG — בליעה ושאילתה — ואיך הן מתחברות דרך ממשק משותף EmbeddingStore.* -כאשר ההטמעות מאוחסנות, תוכן דומה מצטבר באופן טבעי במרחב הווקטורי. ההדמיה למטה מראה איך מסמכים על נושאים קרובים מסתדרים כנקודות סמוכות, מה שמאפשר את החיפוש הסמנטי: +לאחר שההשקפויות מאוחסנות, תוכן דומה מתרכז בטבעיות בחלל הווקטורי. הוויזואליזציה למטה מציגה איך מסמכים על נושאים קשורים מסתדרים כנקודות סמוכות, מה שמאפשר חיפוש סמנטי: -מרחב הטמעות וקטוריות +Vector Embeddings Space -*הדמיה זו מציגה כיצד מסמכים קשורים מצטברים ביחד במרחב וקטורי תלת-ממדי, עם נושאים כמו מסמכים טכניים, כללי עסקים ושאלות נפוצות שיוצרים קבוצות מובחנות.* +*וויזואליזציה זו מראה איך מסמכים קרובים בנושא מצטברים יחד במרחב וקטורי תלת-ממדי, עם נושאים כמו תיעוד טכני, כללי עסק ו-FAQs שיוצרים קבוצות מובחנות.* -כשהמשתמש מחפש, המערכת מבצעת ארבעה שלבים: מטמיעה את המסמכים פעם אחת, מטמיעה את השאילתא בכל חיפוש, משווה את וקטור השאילתא לכל הוקטורים המאוחסנים בעזרת דמיון קוסינוס, ומחזירה את הקטעים עם הציון הגבוה ביותר K. הדיאגרמה למטה מבקשת כל שלב ומחלקות LangChain4j המעורבות: +כאשר משתמש מחפש, המערכת עוקבת אחרי ארבעה שלבים: היא משתקפת את המסמכים פעם אחת, משתקפת את השאילתה בכל חיפוש, משווה את וקטור השאילתה עם כל הווקטורים המאוחסנים לפי דמיון קוסינוס, ומחזירה את קבצי הנתח המדורגים הכי גבוהים. הדיאגרמה למטה מפרטת כל שלב ואת מחלקות LangChain4j שמעורבות: -שלבי חיפוש הטמעה +Embedding Search Steps -*דיאגרמה זו מראה את תהליך חיפוש ההטמעה בארבעה שלבים: הטמעת מסמכים, הטמעת השאילתא, השוואת וקטורים עם דמיון קוסינוס, והחזרת התוצאות הטובות ביותר.* +*דיאגרמה זו מציגה את תהליך החיפוש בהשתקפויות בארבעה שלבים: השתקפות מסמכים, השתקפות השאילתה, השוואת וקטורים בעזרת דמיון קוסינוס, והחזרת תוצאות מובילות.* ### חיפוש סמנטי [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -כשאתה שואל שאלה, גם השאלה שלך הופכת להטמעה. המערכת משווה את הטמעת השאלה שלך עם כל הטמעות חתיכות המסמך. היא מוצאת את החתיכות עם המשמעויות הדומות ביותר - לא רק מילות מפתח תואמות, אלא דמיון סמנטי ממשי. +כשתשאלו שאלה, גם השאלה הופכת להשקפה. המערכת משווה את השתקפות השאלה שלכם לכל נתחי המסמך המושתקים. היא מוצאת את הנתחי המסמך עם המשמעויות הקרובות ביותר — לא רק חיפוש מילות מפתח, אלא דמיון סמנטי אמיתי. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +197,28 @@ for (EmbeddingMatch match : matches) { } ``` -הדיאגרמה למטה משווה בין חיפוש סמנטי לחיפוש מילות מפתח מסורתי. חיפוש מילות מפתח על "רכב" מפספס חתיכה על "מכוניות ומשאיות", אבל החיפוש הסמנטי מבין שהם משמעותם אותו דבר ומחזיר אותה תוצאה עם ציון גבוה: -חיפוש סמנטי +הדיאגרמה למטה משווה בין חיפוש סמנטי לחיפוש מילות מפתח מסורתי. חיפוש מילות מפתח על "vehicle" מפספס נתח המסביר "cars and trucks," אבל חיפוש סמנטי מבין שהם משמעותית זהים ומחזיר את זה כתוצאה עם דירוג גבוה: -*דיאגרמה זו משווה חיפוש מבוסס-מילות מפתח עם חיפוש סמנטי, ומראה איך חיפוש סמנטי מאתר תוכן מושגי קשור גם כשמילות המפתח המדויקות שונות.* -מתחת למכסה המנוע, דמיון נמדד באמצעות דמיון קוסינוס — בעצם שואל "האם שתי החצים הללו מצביעים לאותו כיוון?" שני מקטעים יכולים להשתמש במילים שונות לחלוטין, אך אם הם פירושם זהה, הווקטורים שלהם מצביעים באותו כיוון ומקבלים ציון קרוב ל-1.0: +Semantic Search -Cosine Similarity +*דיאגרמה זו משווה בין חיפוש מבוסס מילת מפתח לחיפוש סמנטי, ומראה כיצד חיפוש סמנטי מחזיר תוכן קשור רעיונית גם כשהמילות מפתח אינן זהות בדיוק.* -*התרשים הזה ממחיש את דמיון הקוסינוס כזוית בין וקטורי ההטמעה — וקטורים המותאמים טוב יותר מקבלים ציון קרוב יותר ל-1.0, מה שמצביע על דמיון סמנטי גבוה יותר.* +מתחת לפני השטח, הדמיון נמדד באמצעות דמיון קוסינוס — שואל בעצם "האם שני החצים מצביעים על אותו כיוון?" שני נתחי טקסט יכולים להשתמש במילים שונות לחלוטין, אך אם המשמעות זהה וקטוריהם מצביעים באותו כיוון ומקבלים ציון קרוב ל-1.0: + +Cosine Similarity +*תרשים זה ממחיש את הדמיון הקוסינוסי כזווית בין וקטורי הטמעה — וקטורים המיושרים יותר מקבלים ציון קרוב יותר ל-1.0, מה שמעיד על דמיון סמנטי גבוה יותר.* > **🤖 נסה עם [GitHub Copilot](https://github.com/features/copilot) Chat:** פתח את [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ושאל: > - "איך עובד חיפוש דמיון עם הטמעות ומה קובע את הציון?" -> - "איזה סף דמיון עליי להשתמש ואיך זה משפיע על התוצאות?" -> - "איך להתמודד עם מקרים שבהם לא נמצאו מסמכים רלוונטיים?" +> - "איזה סף דמיון כדאי להשתמש וכיצד זה משפיע על התוצאות?" +> - "איך מטפלים במקרים שבהם לא נמצאו מסמכים רלוונטיים?" -### יצירת תשובה +### יצירת תשובות [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -המקטעים הרלוונטיים ביותר מורכבים לפרומפט מובנה שכולל הנחיות מפורשות, ההקשר שנשלף, ושאלת המשתמש. המודל קורא את המקטעים הספציפיים האלה ועונה בהתבסס על המידע — הוא יכול להשתמש רק במה שנמצא מולו, מה שמונע הזיות. +החתיכות הרלוונטיות ביותר מורכבות לתוך פרומפט מובנה הכולל הוראות מפורשות, ההקשר שנשלף, ושאלת המשתמש. המודל קורא את החתיכות הספציפיות האלו ועונה על סמך המידע — הוא יכול להשתמש רק במה שיש מולו, מה שמונע הזיות. ```java String context = matches.stream() @@ -237,17 +239,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -התרשים למטה מראה את התהליך הזה בפעולה — המקטעים עם הציון הגבוה ביותר משלב החיפוש מוזנים לתבנית הפרומפט, ו-`OpenAiOfficialChatModel` מייצר תשובה מבוססת: +התרשים למטה מראה את ההרכבה בפעולה — החלקים המובילים בציון משלב החיפוש מוזרקים לתבנית הפרומפט, וה־`OpenAiOfficialChatModel` מייצר תשובה מבוססת: Context Assembly -*התרשים מציג איך המקטעים בעלי הציון הגבוה מורכבים לפרומפט מובנה, ומאפשרים למודל לייצר תשובה מבוססת מתוך הנתונים שלך.* +*תרשים זה מראה כיצד החתיכות בעלות הציון הגבוה מורכבות לפרומפט מובנה, ומאפשרות למודל לייצר תשובה מבוססת מהנתונים שלך.* ## הפעלת היישום -**אימות פריסה:** +**אמת את הפריסה:** -ודא שקובץ `.env` קיים בתיקיית השורש עם אישורי Azure (נוצר במהלך מודול 01). הפעל זאת מתיקיית המודול (`03-rag/`): +ודא שקובץ `.env` קיים בספריית השורש עם אישורי Azure (נוצר במהלך יחידת 01). הרץ זאת מתיקיית היחידה (`03-rag/`): **Bash:** ```bash @@ -256,46 +258,46 @@ cat ../.env # צריך להציג את AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYME **PowerShell:** ```powershell -Get-Content ..\.env # אמור להראות AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # צריך להציג את AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **הפעל את היישום:** -> **הערה:** אם כבר הפעלת את כל היישומים באמצעות `./start-all.sh` מתיקיית השורש (כמתואר במודול 01), מודול זה כבר רץ בפורט 8081. באפשרותך לדלג על פקודות ההפעלה למטה ולעבור ישירות ל-http://localhost:8081. +> **הערה:** אם התחלת כבר את כל היישומים באמצעות `./start-all.sh` מספריית השורש (כמתואר ביחידה 01), יחידה זו כבר רצה על הפורט 8081. אפשר לדלג על פקודות ההפעלה למטה ולעבור ישירות ל-http://localhost:8081. **אפשרות 1: שימוש ב-Spring Boot Dashboard (מומלץ למשתמשי VS Code)** -המיכל לפיתוח כולל את תוסף Spring Boot Dashboard, המספק ממשק חזותי לניהול כל יישומי Spring Boot. ניתן למצוא אותו בסרגל הפעילות בצד השמאלי של VS Code (חפש את סמל Spring Boot). +מיכל הפיתוח כולל את הרחבת Spring Boot Dashboard, שמספקת ממשק ויזואלי לניהול כל יישומי Spring Boot. ניתן למצוא אותו בסרגל הפעילות בצד שמאל של VS Code (חפש את סמל Spring Boot). -מסך Spring Boot Dashboard מאפשר: +מ-Spring Boot Dashboard, ניתן: - לראות את כל יישומי Spring Boot הזמינים בסביבת העבודה -- להפעיל/להפסיק יישומים בלחיצה אחת +- להפעיל/להפסיק יישומים בלחיצה יחידה - לצפות בלוגים של היישום בזמן אמת -- לעקוב אחר מצב היישום +- לנטר את מצב היישום -פשוט לחץ על כפתור ההפעלה שליד "rag" כדי להפעיל את המודול הזה, או הפעל את כל המודולים יחד. +פשוט תלחץ על כפתור ההפעלה לצד "rag" כדי להפעיל יחידה זו, או להפעיל את כל היחידות בבת אחת. Spring Boot Dashboard -*צילום המסך הזה מציג את Spring Boot Dashboard ב-VS Code, בו ניתן להפעיל, להפסיק ולעקוב אחר יישומים בצורה חזותית.* +*צילום מסך זה מראה את Spring Boot Dashboard ב-VS Code, שם ניתן להפעיל, לעצור ולנטר יישומים באופן ויזואלי.* **אפשרות 2: שימוש בסקריפטים של shell** -הפעל את כל יישומי האינטרנט (מודולים 01-04): +הפעל את כל יישומי האינטרנט (יחידות 01-04): **Bash:** ```bash -cd .. # מהספרייה השורשית +cd .. # מתיקיית השורש ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # מהספרייה הראשית +cd .. # מתיקיית השורש .\start-all.ps1 ``` -או הפעל רק את המודול הזה: +או הפעל רק יחידה זו: **Bash:** ```bash @@ -309,9 +311,9 @@ cd 03-rag .\start.ps1 ``` -שני הסקריפטים טוענים אוטומטית משתני סביבה מקובץ `.env` בתיקיית השורש ויבנו את קבצי ה-JAR אם הם אינם קיימים. +שני הסקריפטים טוענים אוטומטית משתנים מהסביבה מקובץ `.env` בספריית השורש ויבנו את קבצי ה-JAR אם אינם קיימים. -> **הערה:** אם אתה מעדיף לבנות את כל המודולים ידנית לפני ההפעלה: +> **הערה:** אם אתה מעדיף לבנות את כל היחידות ידנית לפני ההפעלה: > > **Bash:** > ```bash @@ -327,111 +329,111 @@ cd 03-rag פתח את http://localhost:8081 בדפדפן שלך. -**כדי לעצור:** +**להפסקת היישום:** **Bash:** ```bash -./stop.sh # רק מודול זה +./stop.sh # רק במודול זה # או cd .. && ./stop-all.sh # כל המודולים ``` **PowerShell:** ```powershell -.\stop.ps1 # מודול זה בלבד +.\stop.ps1 # רק מודול זה # או cd ..; .\stop-all.ps1 # כל המודולים ``` ## שימוש ביישום -היישום מספק ממשק רשת להעלאת מסמכים ושאילת שאלות. +היישום מספק ממשק אינטרנט להעלאת מסמכים ושאילת שאלות. RAG Application Interface -*צילום המסך מציג את ממשק היישום RAG בו ניתן להעלות מסמכים ולשאול שאלות.* +*צילום מסך זה מראה את ממשק יישום RAG שבו מטעינים מסמכים ושואלים שאלות.* ### העלאת מסמך -תתחיל בהעלאת מסמך - קבצי TXT מתאימים במיוחד לבדיקה. קיימת דוגמה בשם `sample-document.txt` בתיקייה זו שמכילה מידע על תכונות LangChain4j, יישום RAG, והמלצות טובות - מושלם לבדיקה. +התחל בהעלאת מסמך - קבצי TXT עובדים הכי טוב לבדיקה. קובץ `sample-document.txt` זמין בתיקייה זו וכולל מידע על תכונות LangChain4j, יישום RAG, ושיטות עבודה מומלצות - מצוין לבדוק עם המערכת. -המערכת מעבדת את המסמך שלך, מפרקת אותו למקטעים, ויוצרת הטמעות עבור כל מקטע. זה מתבצע אוטומטית בזמן ההעלאה. +המערכת מעבדת את המסמך, מפרקת אותו לחתיכות, ויוצרת הטמעות לכל חתיכה. זה נעשה אוטומטית בעת ההעלאה. -### שאילת שאלות +### שאל שאלות -כעת שאל שאלות ספציפיות לגבי תוכן המסמך. נסה משהו עובדתי שמצוין במפורש במסמך. המערכת מחפשת מקטעים רלוונטיים, כוללת אותם בפרומפט, ומייצרת תשובה. +כעת שאל שאלות ספציפיות בנוגע לתוכן המסמך. נסה משהו עובדתי שמפורש במפורש במסמך. המערכת מחפשת חתיכות רלוונטיות, כוללת אותן בפרומפט, ויוצרת תשובה. -### בדוק הפניות למקור +### בדוק הפניות למקורות -שים לב שכל תשובה כוללת הפניות למקורות עם ציוני דמיון. ציונים אלה (מ-0 עד 1) מראים עד כמה כל מקטע היה רלוונטי לשאלתך. ציונים גבוהים משמעותם התאמה טובה יותר. זה מאפשר לך לאמת את התשובה מול החומר המקורי. +שים לב שכל תשובה כוללת הפניות למקורות עם ציוני דמיון. ציונים אלו (0 עד 1) מראים עד כמה כל חתיכה הייתה רלוונטית לשאלתך. ציונים גבוהים משמעותם התאמות טובות יותר. זה מאפשר לך לאמת את התשובה מול חומר המקור. RAG Query Results -*צילום המסך מציג תוצאות שאילתה עם התשובה שנוצרה, הפניות למקור, וציוני רלוונטיות לכל מקטע שנשלף.* +*צילום מסך זה מראה תוצאות שאילתה עם התשובה שנוצרה, הפניות למקורות, וציוני רלוונטיות עבור כל חתיכה שהושגה.* ### נסה שאלות שונות -נסה סוגים שונים של שאלות: -- עובדות ספציפיות: "מה הנושא העיקרי?" +נסה סוגי שאלות שונים: +- עובדות ספציפיות: "מה הנושא המרכזי?" - השוואות: "מה ההבדל בין X ל-Y?" - סיכומים: "סכם את הנקודות המרכזיות לגבי Z" -עיין כיצד ציוני הרלוונטיות משתנים בהתאם לאיכות ההתאמה בין שאלתך לתוכן המסמך. +צפה כיצד ציוני הרלוונטיות משתנים בהתאם למידת ההתאמה של שאלתך לתוכן המסמך. ## מושגים מרכזיים -### אסטרטגיית פירוק למקטעים +### אסטרטגיית חיתוך לחתיכות -מסמכים מחולקים למקטעים של 300 טוקנים עם חפיפה של 30 טוקנים. איזון זה מבטיח שלכל מקטע יש הקשר מספק להיות משמעותי ועדיין קטן מספיק כדי לאפשר לכלול מקטעים מרובים בפרומפט. +המסמכים מחולקים לחתיכות של 300 תווים עם חפיפה של 30 תווים. איזון זה מבטיח שלכל חתיכה יש מספיק הקשר כדי להיות משמעותית, תוך שמירה על גודל קטן דיה לכלול מספר חתיכות בפרומפט. ### ציוני דמיון -כל מקטע שנשלף מגיע עם ציון דמיון בין 0 ל-1 שמצביע על מידת ההתאמה לשאלת המשתמש. התרשים למטה מראה את טווחי הציונים ואיך המערכת משתמשת בהם לסינון התוצאות: +כל חתיכה שהושגה מגיעה עם ציון דמיון בין 0 ל-1 המציין עד כמה היא תואמת את שאלת המשתמש. התרשים למטה מראה את טווחי הציונים וכיצד המערכת משתמשת בהם לסינון תוצאות: Similarity Scores -*התרשים מראה טווחי ציונים בין 0 ל-1, עם סף מינימלי של 0.5 שמסנן מקטעים לא רלוונטיים.* +*תרשים המדגים טווחי ציונים מ-0 עד 1, עם סף מינימום של 0.5 שמסנן חתיכות לא רלוונטיות.* הציונים נעים בין 0 ל-1: - 0.7-1.0: רלוונטי מאוד, התאמה מדויקת - 0.5-0.7: רלוונטי, הקשר טוב -- מתחת ל-0.5: מסונן החוצה, שונה מדי +- מתחת ל-0.5: מסונן החוצה, לא דומה מספיק -המערכת מושכת רק מקטעים עם ציון מעל הסף המינימלי כדי להבטיח איכות. +המערכת מחלצת רק חתיכות מעל לסף המינימלי כדי להבטיח איכות. -ההטמעות עובדות טוב כשהמשמעות מקובצת בצורה ברורה, אך יש להן נקודות עיוורות. התרשים למטה מדגים מצבי כשל נפוצים — מקטעים גדולים מדי מייצרים וקטורים "מעורפלים", מקטעים קטנים מדי חסרי הקשר, מונחים שאינם חד משמעיים מפנים למספר אשכולות, וחיפושים מדויקים (מספרי זיהוי, מספרי חלקים) אינם עובדים כלל עם הטמעות: +הטמעות עובדות טוב כאשר המשמעויות מתאגדות נקי, אך יש להן נקודות עיוורות. התרשים למטה מראה מצבי כשל נפוצים — חתיכות גדולות מדי מייצרות וקטורים מטושטשים, חתיכות קטנות מדי חסרות הקשר, מונחים דו משמעותיים מפנים למספר אשכולות, וחיפושים בהתאמה מדויקת (מספרי זיהוי, מספרי חלקים) אינם עובדים עם הטמעות בכלל: Embedding Failure Modes -*התרשים מראה מצבי כשל נפוצים בהטמעות: מקטעים גדולים מדי, קטנים מדי, מונחים לא ברורים שמפנים למספר אשכולות, וחיפושים מדויקים כמו מספרי זיהוי.* +*תרשים זה מראה מצבי כשל נפוצים בטמעות: חתיכות גדולות מדי, חתיכות קטנות מדי, מונחים דו משמעותיים המפנים לאשכולות מרובים, וחיפושים בהתאמה מדויקת כמו מספרי זיהוי.* ### אחסון בזיכרון -מודול זה משתמש באחסון בזיכרון לצורך פשטות. כשאתה מחדש את היישום, המסמכים שהועלו יאבדו. מערכות ייצור משתמשות במסדי נתונים וקטוריים מתמידים כגון Qdrant או Azure AI Search. +יחידה זו משתמשת באחסון בזיכרון לצורך הפשטה. כשאתה מפעיל מחדש את היישום, המסמכים שהועלו אובדים. מערכות פרודקשן משתמשות במסדי נתונים וקטוריים מתמידים כמו Qdrant או Azure AI Search. ### ניהול חלון הקשר -לכל מודל יש מגבלת חלון הקשר מקסימלית. אי אפשר לכלול כל מקטע ממסמך גדול. המערכת מושכת את חמשת (ברירת מחדל) המקטעים הרלוונטיים ביותר כדי להישאר בתוך הגבולות ולספק מספיק הקשר לתשובות מדויקות. +לכל מודל יש חלון הקשר מקסימלי. אינך יכול לכלול כל חתיכה ממסמך גדול. המערכת מחלצת את 5 החתיכות הרלוונטיות ביותר (ברירת מחדל) כדי להישאר בגבולות תוך מתן הקשר מספיק לתשובות מדויקות. ## מתי RAG חשוב -RAG לא תמיד הגישה הנכונה. מדריך ההחלטות למטה עוזר לקבוע מתי RAG מוסיף ערך ומתי גישות פשוטות יותר — כמו לכלול תוכן ישירות בפרומפט או להסתמך על הידע המובנה של המודל — די וישר: +RAG אינו תמיד הגישה הנכונה. מדריך ההחלטה למטה עוזר לך לקבוע מתי RAG מוסיף ערך מול מתי גישות פשוטות יותר — כמו הכללת תוכן ישירות בפרומפט או הסתמכות על הידע המובנה של המודל — מספיקות: When to Use RAG -*התרשים מציג מדריך החלטה מתי RAG מוסיף ערך ומתי גישות פשוטות מספיקות.* +*תרשים זה מראה מדריך החלטה מתי RAG מוסיף ערך ומתי גישות פשוטות מספקות.* -## שלבים הבאים +## השלבים הבאים -**מודול הבא:** [04-tools - סוכני AI עם כלים](../04-tools/README.md) +**היחידה הבאה:** [04-tools - סוכני AI עם כלים](../04-tools/README.md) --- -**ניווט:** [← קודם: מודול 02 - הנדסת פרומפטים](../02-prompt-engineering/README.md) | [חזרה לעמוד הראשי](../README.md) | [הבא: מודול 04 - כלים →](../04-tools/README.md) +**ניווט:** [← קודמת: יחידה 02 - הנדסת פרומפט](../02-prompt-engineering/README.md) | [חזרה לעמוד הראשי](../README.md) | [הבא: יחידה 04 - כלים →](../04-tools/README.md) --- -**כתב ויתור**: -מסמך זה תורגם באמצעות שירות תרגום בבינה מלאכותית [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, נא שים לב כי תרגומים אוטומטיים עלולים להכיל שגיאות או אי דיוקים. יש להתייחס למסמך המקורי בשפת המקור כמקור הסמכותי. עבור מידע קריטי מומלץ לתרגום מקצועי על ידי בני אדם. איננו אחראים לכל אי הבנה או פרשנות שגויה הנובעת משימוש בתרגום זה. +**כתב ויתור**: +מסמך זה תורגם באמצעות שירות תרגום אוטומטי [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש להחשיב את המסמך המקורי בשפתו הטבעית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אדם. אנו לא אחראים לכל אי-הבנה או פירוש שגוי הנובע מהשימוש בתרגום זה. \ No newline at end of file diff --git a/translations/he/04-tools/README.md b/translations/he/04-tools/README.md index ea720d8df..bf509c294 100644 --- a/translations/he/04-tools/README.md +++ b/translations/he/04-tools/README.md @@ -1,84 +1,84 @@ -# מודול 04: סוכני בינה מלאכותית עם כלים - -## תוכן העניינים - -- [סקירת וידאו](../../../04-tools) -- [מה תלמדו](../../../04-tools) -- [דרישות מוקדמות](../../../04-tools) -- [הבנת סוכני בינה מלאכותית עם כלים](../../../04-tools) -- [איך פועלת קריאת כלים](../../../04-tools) - - [הגדרות כלים](../../../04-tools) - - [קבלת החלטות](../../../04-tools) - - [הוצאה לפועל](../../../04-tools) - - [יצירת תגובה](../../../04-tools) - - [ארכיטקטורה: Spring Boot auto-wiring](../../../04-tools) -- [שרשור כלים](../../../04-tools) -- [הרצת האפליקציה](../../../04-tools) -- [שימוש באפליקציה](../../../04-tools) - - [נסה שימוש פשוט בכלים](../../../04-tools) - - [בדוק שרשור כלים](../../../04-tools) - - [ראה זרימת שיחה](../../../04-tools) - - [נסו ניסויים עם בקשות שונות](../../../04-tools) -- [מושגים מרכזיים](../../../04-tools) - - [תבנית ReAct (הסקה ופעולה)](../../../04-tools) - - [חשיבות תיאורי הכלים](../../../04-tools) - - [ניהול סשן](../../../04-tools) - - [טיפול בשגיאות](../../../04-tools) -- [כלים זמינים](../../../04-tools) -- [מתי להשתמש בסוכני מבוססי כלים](../../../04-tools) -- [כלים מול RAG](../../../04-tools) -- [צעדים הבאים](../../../04-tools) - -## סקירת וידאו - -צפו במפגש חי זה שמסביר כיצד להתחיל עם מודול זה: - -סוכני בינה מלאכותית עם כלים ו-MCP - מפגש חי - -## מה תלמדו - -עד כה, למדתם כיצד לנהל שיחות עם בינה מלאכותית, לבנות בקשות בצורה יעילה, ולבסס תגובות על המסמכים שלכם. אבל עדיין יש מגבלה בסיסית: מודלי שפה יכולים רק לייצר טקסט. הם לא יכולים לבדוק את מזג האוויר, לבצע חישובים, לשאול מאגרי מידע או לקיים אינטראקציה עם מערכות חיצוניות. - -כלים משנים את זה. בכך שהם נותנים למודל גישה לפונקציות שהוא יכול לקרוא להן, אתם הופכים אותו מיצרן טקסט לסוכן שיכול לבצע פעולות. המודל מחליט מתי הוא זקוק לכלי, איזה כלי להשתמש ומה הפרמטרים להעביר. הקוד שלכם מבצע את הפונקציה ומחזיר את התוצאה. המודל משלב את התוצאה הזאת בתגובתו. +# מודול 04: סוכני AI עם כלים + +## תוכן עניינים + +- [סיור וידאו](#סיור-וידאו) +- [מה תלמד](#מה-תלמד) +- [דרישות מוקדמות](#דרישות-מוקדמות) +- [הבנת סוכני AI עם כלים](#הבנת-סוכני-ai-עם-כלים) +- [איך קריאת כלים עובדת](#איך-קריאת-כלים-עובדת) + - [הגדרות כלים](#הגדרות-כלים) + - [קבלת החלטות](#קבלת-החלטות) + - [ביצוע](#ביצוע) + - [יצירת תגובה](#יצירת-תגובה) + - [ארכיטקטורה: חיבור אוטומטי ב-Spring Boot](#ארכיטקטורה-חיבור-אוטומטי-ב-spring-boot) +- [שרשור כלים](#שרשור-כלים) +- [הרצת היישום](#הרצת-היישום) +- [שימוש ביישום](#שימוש-באפליקציה) + - [נסה שימוש פשוט בכלי](#נסה-שימוש-פשוט-בכלי) + - [בדוק שרשור כלים](#בדוק-רצף-כלים) + - [ראה את זרם השיחה](#ראה-את-verlauf-השיחה) + - [התנסה בבקשות שונות](#נסה-בקשות-שונות) +- [מונחים מרכזיים](#רעיונות-מרכזיים) + - [תבנית ReAct (היסק ופעולה)](#תבנית-react-הסקה-ופעולה) + - [תיאורים של כלים חשובים](#תיאורי-כלים-חשובים) + - [ניהול סשן](#ניהול-מושבים) + - [ניהול שגיאות](#טיפול-בשגיאות) +- [כלים זמינים](#כלים-זמינים) +- [מתי להשתמש בסוכנים מבוססי כלים](#מתי-להשתמש-בסוכנים-מבוססי-כלים) +- [כלים מול RAG](#כלים-לעומת-rag) +- [שלבים הבאים](#השלבים-הבאים) + +## סיור וידאו + +צפו במפגש חי זה שמסביר איך להתחיל עם מודול זה: + +סוכני AI עם כלים ו-MCP - מפגש חי + +## מה תלמד + +עד כה למדת איך לנהל שיחות עם AI, לארגן פרומפטים ביעילות, ולבסס תגובות על המסמכים שלך. אך יש מגבלה יסודית: מודלים של שפה יכולים רק ליצור טקסט. הם לא יכולים לבדוק את מזג האוויר, לבצע חישובים, לשאול מאגרי מידע או לתקשר עם מערכות חיצוניות. + +כלים משנים את זה. על ידי מתן גישה לפונקציות שהמודל יכול לקרוא להן, אתה הופך אותו מגן טקסט לסוכן שיכול לבצע פעולות. המודל מחליט מתי הוא צריך כלי, איזה כלי להשתמש, ואילו פרמטרים להעביר. הקוד שלך מבצע את הפונקציה ומחזיר את התוצאה. המודל משלב את התוצאה הזאת לתגובה שלו. ## דרישות מוקדמות - השלמת [מודול 01 - מבוא](../01-introduction/README.md) (משאבי Azure OpenAI הוגדרו) -- מומלץ שהמודולים הקודמים התרחשו (מודול זה מתייחס ל[מושגי RAG ממודול 03](../03-rag/README.md) בהשוואה בין כלים ל-RAG) -- קובץ `.env` בספריית השורש עם קרדנציאליים של Azure (נוצר על ידי `azd up` במודול 01) +- מומלץ להשלים מודולים קודמים (המודול מתייחס ל[מושגי RAG ממודול 03](../03-rag/README.md) בהשוואה בין כלים ל-RAG) +- קובץ `.env` בתיקיית השורש עם אישורי Azure (נוצר על ידי `azd up` במודול 01) -> **הערה:** אם לא השלמתם את מודול 01, עקבו תחילה אחר הוראות הפריסה שם. +> **הערה:** אם לא השלמת את מודול 01, עקוב תחילה אחר הוראות הפריסה שם. -## הבנת סוכני בינה מלאכותית עם כלים +## הבנת סוכני AI עם כלים -> **📝 הערה:** המונח "סוכנים" במודול זה מתייחס לעוזרי בינה מלאכותית המורחבים ביכולת קריאת כלים. זה שונה מתבניות **Agentic AI** (סוכנים אוטונומיים עם תכנון, זיכרון והסקת מסקנות רב-שלבית) שנסקור ב[מודול 05: MCP](../05-mcp/README.md). +> **📝 הערה:** המונח "סוכנים" במודול זה מתייחס לעוזרי AI המשופרים עם יכולות קריאת כלים. זה שונה מתבניות **Agentic AI** (סוכנים אוטונומיים עם תכנון, זיכרון והיסק רב-שלבי) שנכסה ב-[מודול 05: MCP](../05-mcp/README.md). -בלי כלים, מודל שפה יכול רק לייצר טקסט מתוך נתוני האימון שלו. שאל אותו מה מזג האוויר הנוכחי, והוא יצטרך לנחש. תן לו כלים, והוא יכול לקרוא ל-API של מזג האוויר, לבצע חישובים או לשאול מאגר מידע — ואז לשזור את התוצאות האמיתיות הללו בתגובתו. +בלי כלים, מודל שפה יכול רק ליצור טקסט מהנתונים שבהם הוא אומן. שאלה אותו לגבי מזג האוויר הנוכחי, והוא צריך לנחש. תן לו כלים, והוא יכול לקרוא ל-API של מזג אוויר, לעשות חישובים או לשאול מסד נתונים — ואז לשלב את התוצאות האמיתיות הללו בתגובתו. בלי כלים מול עם כלים -*בלי כלים המודל רק מנחש — עם כלים הוא יכול לקרוא APIs, לבצע חישובים ולהחזיר נתונים בזמן אמת.* +*בלי כלים המודל יכול רק לנחש — עם כלים הוא יכול לקרוא ל-APIs, להריץ חישובים ולהחזיר נתונים בזמן אמת.* -סוכן בינה מלאכותית עם כלים פועל לפי תבנית **ReAct (הסקה ופעולה)**. המודל לא רק מגיב — הוא חושב על מה שהוא צריך, פועל על ידי קריאת כלי, מתבונן בתוצאה, ואז מחליט אם לפעול שוב או לספק את התשובה הסופית: +סוכן AI עם כלים פועל לפי תבנית **Reasoning and Acting (ReAct)**. המודל לא רק מגיב — הוא חושב על מה שהוא צריך, פועל על ידי קריאת כלי, מתבונן בתוצאה, ואז מחליט אם לפעול שוב או לספק את התשובה הסופית: -1. **הסקה** — הסוכן מנתח את שאלת המשתמש וקובע אילו מידע הוא צריך -2. **פעולה** — הסוכן בוחר את הכלי הנכון, מייצר את הפרמטרים המתאימים, וקורא לו -3. **התבוננות** — הסוכן מקבל את הפלט מהכלי ומעריך את התוצאה -4. **חזרה או תגובה** — אם נדרשת עוד מידע, הסוכן חוזר על המחזור; אחרת, מחבר תשובה בשפה טבעית +1. **היסק** — הסוכן מנתח את שאלת המשתמש ומחליט איזה מידע הוא צריך +2. **פעולה** — הסוכן בוחר את הכלי הנכון, מייצר את הפרמטרים הנכונים, וקורא לו +3. **התבוננות** — הסוכן מקבל את הפלט של הכלי ומעריך את התוצאה +4. **חזרה או תגובה** — אם יש צורך במידע נוסף, הסוכן חוזר; אחרת, הוא מחבר תשובה בשפה טבעית תבנית ReAct -*מחזור ReAct — הסוכן חושב מה לעשות, פועל על ידי קריאת כלי, מתבונן בתוצאה וחוזר עד שהוא יכול לספק את התשובה הסופית.* +*מחזור ReAct — הסוכן הוסק מה לעשות, פועל על ידי קריאת כלי, מתבונן בתוצאה, וחוזר עד שהוא יכול לספק את התשובה הסופית.* -זה מתרחש אוטומטית. אתם מגדירים את הכלים וההגדרות שלהם. המודל אחראי לקבלת ההחלטות מתי ואיך להשתמש בהם. +זה קורה אוטומטית. אתה מגדיר את הכלים ואת תיאורי הכלים שלהם. המודל מטפל בקבלת ההחלטות מתי ואיך להשתמש בהם. -## איך פועלת קריאת כלים +## איך קריאת כלים עובדת ### הגדרות כלים [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -אתם מגדירים פונקציות עם תיאורים ברורים ומפרטי פרמטרים. המודל רואה את התיאורים האלה בבקשת המערכת שלו ומבין מה כל כלי עושה. +אתה מגדיר פונקציות עם תיאורים ברורים ומפרט של פרמטרים. המודל רואה את התיאורים הללו בפרומפט של המערכת ומבין מה כל כלי עושה. ```java @Component @@ -97,134 +97,134 @@ public interface Assistant { } // העוזר מחובר אוטומטית על ידי Spring Boot עם: -// - bean של ChatModel +// - אובייקט ChatModel // - כל שיטות @Tool מתוך מחלקות @Component -// - ChatMemoryProvider לניהול מושבים +// - ספק זיכרון הצ'אט לניהול מושבים ``` -הדיאגרמה למטה מפורקת כל אנוטציה ומראה כיצד כל חלק עוזר לבינה להבין מתי לקרוא לכלי ואילו ארגומנטים להעביר: +הדיאגרמה למטה מפרקת כל אנוטציה ומראה איך כל חלק מסייע ל-AI להבין מתי לקרוא לכלי ואילו ארגומנטים להעביר: -מבנה הגדרות כלי +אנטומיה של הגדרות כלים -*מבנה של הגדרת כלי — @Tool אומר לבינה מתי להשתמש בו, @P מתאר כל פרמטר, ו-@AiService מחבר את הכל יחד בפתיחה.* +*אנטומיה של הגדרת כלי — @Tool אומר ל-AI מתי להשתמש בו, @P מתאר כל פרמטר, ו-@AiService מחבר הכל יחד בהפעלה.* -> **🤖 נסה עם [GitHub Copilot](https://github.com/features/copilot) צ׳אט:** פתח את [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ואז שאל: -> - "איך אשילב API אמיתי של מזג אוויר כמו OpenWeatherMap במקום נתוני מדומה?" -> - "מה הופך תיאור כלי לטוב שעוזר לבינה להשתמש בו נכון?" -> - "איך מטפלים בשגיאות API והגבלות קצב בהטמעת כלים?" +> **🤖 נסה עם [GitHub Copilot](https://github.com/features/copilot) Chat:** פתח את [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ושאל: +> - "איך הייתי משלב API אמיתי למזג אוויר כמו OpenWeatherMap במקום נתונים מדומים?" +> - "מה הופך תיאור כלי לטוב שמסייע ל-AI להשתמש בו נכון?" +> - "איך מטפלים בשגיאות API ומגבלות קצב ביישום כלים?" ### קבלת החלטות -כשמשתמש שואל "מה מזג האוויר בסיאטל?", המודל לא בוחר כלי באקראי. הוא משווה את כוונת המשתמש לכל תיאור כלי שיש לו גישה אליו, נותן ניקוד לכל אחד על רלוונטיות, ובוחר את ההתאמה הטובה ביותר. לאחר מכן הוא מייצר קריאת פונקציה מובנית עם הפרמטרים הנכונים — במקרה הזה, מגדיר `location` ל-"Seattle". +כאשר משתמש שואל "מה מזג האוויר בסיאטל?", המודל לא בוחר כלי באקראי. הוא משווה את הכוונה של המשתמש מול כל תיאור כלי שברשותו, מדרג כל אחד לפי רלוונטיות, ובוחר את ההתאמה הטובה ביותר. לאחר מכן הוא מייצר קריאת פונקציה מובנית עם הפרמטרים הנכונים — במקרה זה, מגדיר את `location` ל- `"Seattle"`. -אם אף כלי לא מתאים לבקשת המשתמש, המודל חוזר לענות מתוך הידע שלו. אם מספר כלים מתאימים, הוא בוחר את הספציפי ביותר. +אם אין כלי שמתאים לבקשת המשתמש, המודל עובר לענות מתוך הידע שלו. אם יש התאמה למספר כלים, הוא בוחר את הספציפי ביותר. -איך הבינה מחליטה איזה כלי להשתמש +איך ה-AI מחליט איזה כלי להשתמש -*המודל מעריך כל כלי זמין מול כוונת המשתמש ובוחר את ההתאמה הטובה ביותר — לכן כתיבת תיאורי כלים ברורים ומפורטים חשובה.* +*המודל מעריך כל כלי זמין מול כוונת המשתמש ובוחר את ההתאמה הטובה ביותר — לכן חשוב לכתוב תיאורי כלים ברורים וספציפיים.* -### הוצאה לפועל +### ביצוע [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot מחבר אוטומטית את הממשק ההכרזתי `@AiService` עם כל הכלים הרשומים, ו-LangChain4j מבצע את קריאות הכלים באופן אוטומטי. מאחורי הקלעים, זרימת קריאת הכלי עוברת שישה שלבים — משאלת משתמש בשפה טבעית ועד תשובה בשפה טבעית: +Spring Boot מחבר אוטומטית את הממשק ההצהרתי `@AiService` עם כל הכלים הרשומים, ו-LangChain4j מבצע קריאות כלי אוטומטית. מאחורי הקלעים, זרם קריאת כלי שלם עובר שישה שלבים — מהשאלה בשפה טבעית של המשתמש ועד התשובה בשפה טבעית: -זרימת קריאת כלים +זרימת קריאת כלי -*זרימה מקצה לקצה — המשתמש שואל שאלה, המודל בוחר כלי, LangChain4j מריץ אותו, והמודל שוזר את התוצאה לתגובה טבעית.* +*הזרימה מקצה לקצה — המשתמש שואל שאלה, המודל בוחר כלי, LangChain4j מבצע אותו, והמודל משלב את התוצאה בתגובה טבעית.* -אם הרצתם את [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) במודול 00, ראיתם כבר את התבנית הזאת — הכלים `Calculator` קראו באותה הדרך. דיאגרמת הרצף שלמטה מראה בדיוק מה קרה מתחת לפני השטח במהלך ההדגמה ההיא: +מאחורי הקלעים, `AiServices` מריץ את אותו לולאת קריאת כלים לכל כלי — כאן מיוצג על ידי `Calculator` פשוט. דיאגרמת הרצף למטה מראה בדיוק מה קורה מתחת לפני השטח: דיאגרמת רצף קריאת כלים -*לולאת קריאת הכלים מהדמו Quick Start — `AiServices` שולח את ההודעה שלך ואת סכמות הכלים ל-LLM, ה-LLM מגיב עם קריאת פונקציה כמו `add(42, 58)`, LangChain4j מבצע את המתודה `Calculator` מונעית, ומחזיר את התוצאה לתשובה הסופית.* +*לולאת קריאת כלי — `AiServices` שולח את ההודעה שלך ואת סכימות הכלים ל-LLM, ה-LLM מחזיר קריאת פונקציה כמו `add(42, 58)`, LangChain4j מבצע את המתודה של `Calculator` באופן מקומי, ומחזיר את התוצאה לתשובה הסופית.* -> **🤖 נסה עם [GitHub Copilot](https://github.com/features/copilot) צ׳אט:** פתח את [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ואז שאל: -> - "איך תבנית ReAct עובדת ולמה היא יעילה לסוכני בינה מלאכותית?" +> **🤖 נסה עם [GitHub Copilot](https://github.com/features/copilot) Chat:** פתח את [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ושאל: +> - "איך תבנית ReAct עובדת ולמה היא יעילה לסוכני AI?" > - "איך הסוכן מחליט איזה כלי להשתמש ובאיזה סדר?" -> - "מה קורה אם ביצוע של כלי נכשל - איך כדאי לטפל בשגיאות בצורה חזקה?" +> - "מה קורה אם ביצוע כלי נכשל - איך לטפל בשגיאות בצורה אמינה?" ### יצירת תגובה -המודל מקבל את נתוני מזג האוויר ומעצב אותם לתגובה בשפה טבעית למשתמש. +המודל מקבל את נתוני מזג האוויר ומעצב אותם לתגובה בשפה טבעית עבור המשתמש. -### ארכיטקטורה: Spring Boot auto-wiring +### ארכיטקטורה: חיבור אוטומטי ב-Spring Boot -מודול זה משתמש באינטגרציה של LangChain4j עם Spring Boot באמצעות ממשקי `@AiService` הכרזתיים. בזמן הפתיחה Spring Boot מגלה כל `@Component` המכיל מתודות עם `@Tool`, את bean ה-`ChatModel` שלך ו-`ChatMemoryProvider` — ואז מחבר את כולם לממשק `Assistant` יחיד ללא צורך בקוד נוסף. +מודול זה משתמש באינטגרציה של LangChain4j עם Spring Boot באמצעות ממשקי `@AiService` הצהרתיים. בהפעלה Spring Boot מוצא כל `@Component` שמכיל מתודות עם `@Tool`, את bean של ה-`ChatModel`, ו-`ChatMemoryProvider` — ואז מחבר אותם כולם לממשק `Assistant` יחיד ללא קוד boilerplate. -ארכיטקטורת Spring Boot auto-wiring +ארכיטקטורת חיבור אוטומטי של Spring Boot -*ממשק @AiService מחבר יחד את ה-ChatModel, רכיבי הכלים וספק הזיכרון — Spring Boot מטפל בכל החיבור אוטומטית.* +*ממשק @AiService מקשר יחד את ה-ChatModel, רכיבי הכלים, וספק הזיכרון — Spring Boot מטפל בחיבור כולו אוטומטית.* -הנה מחזור חיים מלא כתרשים רצף — מבקשת HTTP דרך הבקר, השירות והפרוקסי המחובר אוטומטית, כל הדרך להוצאה לפועל של הכלי וחזרה: +הנה מחזור החיים המלא של הבקשה כדיאגרמת רצף — מהבקשה HTTP דרך הבקר, השירות, והפרוקסי המחובר אוטומטית, ועד לביצוע הכלי והחזרה: -תרשים רצף קריאת כלים ב-Spring Boot +דיאגרמת רצף קריאת כלי ב-Spring Boot -*מחזור החיים המלא של בקשת Spring Boot — בקשת HTTP זורמת דרך הבקר והשירות לפרוקסי Assistant המטפל ב-LLM ובקריאות הכלים אוטומטית.* +*מחזור החיים המלא של בקשת Spring Boot — בקשת HTTP זורמת דרך הבקר והשירות לפרוקסי Assistant המחובר אוטומטית, שמנהל את ה-LLM וקריאות הכלים באופן אוטומטי.* -יתרונות מרכזיים בגישה זו: +יתרונות מרכזיים של גישה זו: -- **Spring Boot auto-wiring** — ChatModel והכלים מוזרקים אוטומטית +- **חיבור אוטומטי ב-Spring Boot** — הזרקת ChatModel וכלים אוטומטית - **תבנית @MemoryId** — ניהול זיכרון מבוסס סשן אוטומטי -- **מופע יחיד** — Assistant נוצר פעם אחת ומשומש מחדש לביצועים טובים יותר -- **הוצאה לפועל בטוחה טיפוסית** — מתודות Java נקראות ישירות עם המרה טיפוסית -- **ניהול סבב מסובב** — מטפל בשרשור כלים אוטומטית -- **ללא קוד מובנה מיותר** — ללא קריאות ידניות ל-`AiServices.builder()` או HashMap זיכרון +- **מופע יחיד** — Assistant נוצר פעם אחת ומשמש שוב לביצועים טובים יותר +- **ביצוע בטוח טיפוסית** — שיטות Java נקראות ישירות עם המרת טיפוסים +- **אורקסטרציה מרובת סבבים** — מטפלת בשרשור כלים אוטומטית +- **ללא boilerplate** — אין צורך לקריאות ידניות ל-AiServices.builder() או HashMap זיכרון -גישות חלופיות (עם גלגול `AiServices.builder()` ידני) דורשות יותר קוד ומפספסות את יתרונות האינטגרציה עם Spring Boot. +גישות חלופיות (קריאות ידניות ל-AiServices.builder()) דורשות יותר קוד וחסרות את יתרונות האינטגרציה של Spring Boot. ## שרשור כלים -**שרשור כלים** — הכוח האמיתי של סוכני כלים מתבצע כאשר שאלה אחת דורשת מספר כלים. שאלו "מה מזג האוויר בסיאטל בפרנהייט?" והסוכן יקשר אוטומטית שני כלים: קודם הוא יקרא ל-`getCurrentWeather` לקבלת הטמפרטורה בצלזיוס, ואז יעביר את הערך ל-`celsiusToFahrenheit` להמרה — הכל בסיבוב שיחה אחד. +**שרשור כלים** — הכוח האמיתי של סוכנים מבוססי כלים מתגלה כאשר שאלה בודדת דורשת כמה כלים. שאל "מה מזג האוויר בסיאטל בפארנהייט?" והסוכן אוטומטית בשרשרת של שני כלים: קודם הוא קורא ל-`getCurrentWeather` לקבלת הטמפרטורה בצלזיוס, ואז מעביר את הערך ל-`celsiusToFahrenheit` להמרה — כל זאת בסבב שיחה יחיד. דוגמה לשרשור כלים -*שרשור כלים בפעולה — הסוכן קורא ראשית ל-getCurrentWeather, אחר כך מחבר את התוצאה בצלזיוס ל-celsiusToFahrenheit, ומספק תשובה משולבת.* +*שרשור כלים בפעולה — הסוכן קורא קודם את getCurrentWeather, ואז מעביר את התוצאה בצלזיוס ל-celsiusToFahrenheit, ומספק תשובה משולבת.* -**כישלונות מכוונים** — בקשו מזג אוויר לעיר שאינה קיימת בנתוני המדומה. הכלי מחזיר הודעת שגיאה, והבינה מסבירה שהיא לא יכולה לעזור במקום לקרוס. כלים נכשלים בבטחה. הדיאגרמה למטה משווה בין שתי הגישות — עם טיפול שגיאות נכון הסוכן תופס את החריגה ומגיב באמצעות הסבר מועיל, בעוד ללא טיפול האפליקציה כולה קורסת: +**כשלונות אלגנטיים** — שאל לגבי מזג האוויר בעיר שאינה בנתונים המדומים. הכלי מחזיר הודעת שגיאה, וה-AI מסביר שהוא לא יכול לעזור במקום לקרוס. כלים נכשלים בצורה בטוחה. הדיאגרמה הבאה משווה בין שתי הגישות — עם טיפול שגיאות נכון הסוכן תופס את החריגה ומגיב בעזרה, ואילו בלי זה היישום כולו קורס: זרימת טיפול בשגיאות -*כאשר כלי נכשל, הסוכן תופס את השגיאה ומגיב בהסבר מועיל במקום לקרוס.* +*כאשר כלי נכשל, הסוכן תופס את השגיאה ומגיב עם הסבר מועיל במקום לקרוס.* -זה מתרחש בסיבוב שיחה יחיד. הסוכן מארגן את קריאות הכלים הרבות אוטונומית. +זה קורה בסבב שיחה אחד. הסוכן מנהל ביצוע של מספר קריאות כלים באופן עצמאי. -## הרצת האפליקציה +## הרצת היישום -**אימות הפריסה:** +**וודא פריסה:** -ודאו שקובץ `.env` קיים בספריית השורש עם קרדנציאליים של Azure (נוצר במהלך מודול 01). הריצו זאת מספריית המודול (`04-tools/`): +וודא שקובץ `.env` קיים בתיקיית השורש עם האישורים של Azure (נוצר במהלך מודול 01). הרץ זאת מתיקיית המודול (`04-tools/`): -**Bash:** +**בבש:** ```bash -cat ../.env # אמור להציג AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # צריך להציג את AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # צריך להציג את AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # אמור להציג את AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**הפעלת האפליקציה:** +**הפעל את היישום:** -> **הערה:** אם כבר התחלתם את כל האפליקציות באמצעות `./start-all.sh` מספריית השורש (כמתואר במודול 01), מודול זה כבר פועל בנמל 8084. ניתן לדלג על פקודות ההפעלה למטה וללכת ישירות ל- http://localhost:8084. +> **הערה:** אם כבר התחלת את כל היישומים באמצעות `./start-all.sh` מתיקיית השורש (כמתואר במודול 01), מודול זה כבר רץ על פורט 8084. ניתן לדלג על פקודות ההפעלה למטה ולעבור ישירות ל-http://localhost:8084. **אפשרות 1: שימוש ב-Spring Boot Dashboard (מומלץ למשתמשי VS Code)** -מיכל הפיתוח כולל את תוסף Spring Boot Dashboard, שמספק ממשק חזותי לניהול כל אפליקציות Spring Boot. ניתן למצוא אותו בסרגל הפעולות משמאל ב-VS Code (חפשו את סמל Spring Boot). +מיכל הפיתוח כולל את התוסף Spring Boot Dashboard, המציע ממשק ויזואלי לניהול כל יישומי Spring Boot. ניתן למצוא אותו בסרגל הפעילויות בצד שמאל של VS Code (חפש את הסמל של Spring Boot). -מה-Spring Boot Dashboard תוכלו: -- לראות את כל אפליקציות Spring Boot הזמינות בסביבת העבודה -- להפעיל/לכבות אפליקציות בלחיצה אחת -- לצפות ביומני האפליקציה בזמן אמת -- לנטר את מצב האפליקציה -פשוט לחצו על כפתור ההפעלה לצד "tools" כדי להתחיל את המודול הזה, או להפעיל את כל המודולים בבת אחת. +מ-Spring Boot Dashboard, ניתן: +- לראות את כל יישומי Spring Boot זמינים בסביבת העבודה +- להפעיל/להפסיק יישומים בלחיצה אחת +- לצפות ביומני היישומים בזמן אמת +- לנטר את מצב היישומים -ככה נראה לוח הבקרה של Spring Boot ב-VS Code: +פשוט לחץ על כפתור ההפעלה ליד "tools" כדי להפעיל את המודול הזה, או הפעל את כל המודולים בבת אחת. -Spring Boot Dashboard +כך נראה Spring Boot Dashboard ב-VS Code: +לוח בקרה של Spring Boot -*לוח הבקרה של Spring Boot ב-VS Code — הפעלה, עצירה ומעקב אחר כל המודולים במקום אחד* +*לוח הבקרה של Spring Boot ב-VS Code — הפעלה, עצירה וניטור של כל המודולים במקום אחד* **אפשרות 2: שימוש בסקריפטים של shell** @@ -238,11 +238,11 @@ cd .. # מתיקיית השורש **PowerShell:** ```powershell -cd .. # מתיקיית השורש +cd .. # מהספרייה השורשית .\start-all.ps1 ``` -או להפעיל רק את המודול הזה: +או הפעל רק את המודול הזה: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -שני הסקריפטים טוענים אוטומטית משתני סביבה מקובץ `.env` בשורש ויבנו את קבצי ה-JAR אם הם לא קיימים. +שני הסקריפטים טוענים אוטומטית משתני סביבה מקובץ `.env` השורש ויבנו את קבצי ה-JAR אם הם אינם קיימים. -> **הערה:** אם אתם מעדיפים לבנות את כל המודולים באופן ידני לפני ההפעלה: +> **הערה:** אם אתה מעדיף לבנות את כל המודולים ידנית לפני ההפעלה: > > **Bash:** > ```bash @@ -272,13 +272,13 @@ cd 04-tools > mvn clean package -DskipTests > ``` -פתחו את http://localhost:8084 בדפדפן שלכם. +פתח את http://localhost:8084 בדפדפן שלך. -**כדי לעצור:** +**לעצירה:** **Bash:** ```bash -./stop.sh # רק במודול זה +./stop.sh # מודול זה בלבד # או cd .. && ./stop-all.sh # כל המודולים ``` @@ -292,96 +292,96 @@ cd ..; .\stop-all.ps1 # כל המודולים ## שימוש באפליקציה -האפליקציה מספקת ממשק רשת שבו תוכלו לתקשר עם סוכן AI שיש לו גישה לכלי מזג אוויר והמרת טמפרטורות. כך נראה הממשק — כולל דוגמאות התחלה מהירה ולוח שיחה לשליחת בקשות: +האפליקציה מספקת ממשק ווב בו ניתן לתקשר עם סוכן AI שיש לו גישה לכלי מזג אוויר והמרת טמפרטורה. כך נראה הממשק — כולל דוגמאות התחלה מהירה ופאנל שיחה לשליחת בקשות: -AI Agent Tools Interface +ממשק כלים של סוכן AI -*ממשק כלי סוכן AI - דוגמאות מהירות וממשק שיחה לאינטראקציה עם הכלים* +*ממשק כלי סוכן AI - דוגמאות מהירות וממשק שיחה לאינטראקציה עם כלים* -### נסו שימוש פשוט בכלי +### נסה שימוש פשוט בכלי -התחילו עם בקשה פשוטה: "המר 100 מעלות פרנהייט לסלזיוס". הסוכן מזהה שהוא צריך להשתמש בכלי המרת הטמפרטורה, קורא לו עם הפרמטרים המתאימים, ומחזיר את התוצאה. שימו לב כמה זה טבעי - לא ציינתם איזה כלי להשתמש או איך לקרוא לו. +התחל עם בקשה פשוטה: "המר 100 מעלות פרנהייט לצלזיוס". הסוכן מזהה שהוא צריך את כלי המרת הטמפרטורה, מפעיל אותו עם הפרמטרים הנכונים ומחזיר את התוצאה. שים לב כמה זה טבעי - לא ציינת איזה כלי להשתמש או איך להפעיל אותו. -### בדקו שרשור כלים +### בדוק רצף כלים -עכשיו נסו משהו מורכב יותר: "מה מזג האוויר בסיאטל והמר את זה לפרנהייט?" צפו בסוכן מבצע זאת בשלבים. הוא קודם מקבל את מזג האוויר (שמחזיר בסלזיוס), מזהה צורך להמיר לפרנהייט, קורא לכלי ההמרה, ומשלב את שתי התוצאות לתגובה אחת. +עכשיו נסה משהו מורכב יותר: "מה מזג האוויר בסיאטל והמר את זה לפרנהייט?" צפה איך הסוכן עובד על זה בשלבים. הוא מקבל קודם את מזג האוויר (שמחזיר צלזיוס), מזהה שהוא צריך להמיר לפרנהייט, מפעיל את כלי ההמרה ומשלב את שתי התוצאות בתגובה אחת. -### ראו רצף השיחה +### ראה את Verlauf השיחה -ממשק השיחה שומר היסטוריית שיחה, ומאפשר לכם לנהל אינטראקציות מרובות סבבים. תוכלו לראות את כל השאלות והתגובות הקודמות, מה שמקל לעקוב אחר השיחה ולהבין איך הסוכן בונה הקשר לאורך החלפות מרובות. +ממשק השיחה שומר היסטוריית שיחה, ומאפשר לך לקיים אינטראקציות מרובות סבבים. תוכל לראות את כל השאלות והתשובות הקודמות, מה שמקל לעקוב אחרי השיחה ולהבין איך הסוכן בונה הקשר במהלך החלפות מרובות. -Conversation with Multiple Tool Calls +שיחה עם קריאות כלים מרובות -*שיחה מרובת סבבים המראה המרות פשוטות, בדיקות מזג אוויר ושרשור כלים* +*שיחת מרובות סבבים המציגה המרות פשוטות, בדיקות מזג אוויר ורצף כלים* -### נסו בקשות שונות +### נסה בקשות שונות -נסו שילובים שונים: +נסה שילובים שונים: - בדיקות מזג אוויר: "מה מזג האוויר בטוקיו?" - המרות טמפרטורה: "כמה זה 25°C בקלווין?" - שאילתות משולבות: "בדוק את מזג האוויר בפריז ואמר לי אם מעל 20°C" -שימו לב איך הסוכן מפרש שפת טבעית וממפה אותה לקריאות כלים מתאימות. +שימו לב איך הסוכן מפרש שפה טבעית וממפה לכך קריאות כלים מתאימות. ## רעיונות מרכזיים -### דפוס ReAct (היסק ופעולה) +### תבנית ReAct (הסקה ופעולה) -הסוכן מתחלף בין היסק (החלטה מה לעשות) ופעולה (שימוש בכלים). דפוס זה מאפשר פתרון בעיות עצמאי יותר מאשר תגובה פשוטה להוראות. +הסוכן מתחלף בין הסקה (החלטה מה לעשות) לבין פעולה (שימוש בכלים). תבנית זו מאפשרת פתרון בעיות עצמאי במקום רק תגובה להוראות. ### תיאורי כלים חשובים -איכות התיאורים של הכלים משפיעה ישירות על איך שהסוכן משתמש בהם. תיאורים ברורים ומפורטים מסייעים לדגם להבין מתי ואיך לקרוא לכל כלי. +איכות תיאורי הכלים שלך משפיעה ישירות על איך הסוכן משתמש בהם. תיאורים ברורים ומפורשים עוזרים למודל להבין מתי ואיך לקרוא לכל כלי. ### ניהול מושבים -האנוטציה `@MemoryId` מאפשרת ניהול זיכרון מבוסס מושבים באופן אוטומטי. לכל מזהה מושב מתקבל מופע `ChatMemory` מנוהל על ידי ה-bean `ChatMemoryProvider`, כך שמשתמשים מרובים יכולים לתקשר עם הסוכן בו זמנית ללא עירוב שיחות שלהם. התרשים הבא מראה כיצד משתמשים שונים מנותבים למחסני זיכרון מבודדים על בסיס מזהי המושב שלהם: +האנוטציה `@MemoryId` מאפשרת ניהול זיכרון מבוסס מושב באופן אוטומטי. לכל מזהה מושב יש מופע `ChatMemory` מנוהל על ידי ה-bean `ChatMemoryProvider`, כך שמספר משתמשים יכולים לתקשר עם הסוכן בו זמנית מבלי שהשיחות שלהם יתערבבו. התמונה הבאה מראה איך משתמשים מרובים מנותבים למחסני זיכרון מבודדים בהתבסס על מזהי המושבים שלהם: -Session Management with @MemoryId +ניהול מושבים עם @MemoryId -*כל מזהה מושב מתורגם להיסטוריית שיחה מבודדת — משתמשים לעולם לא רואים את ההודעות של אחרים.* +*לכל מזהה מושב יש היסטוריית שיחה מבודדת — משתמשים לעולם אינם רואים את ההודעות של אחרים.* ### טיפול בשגיאות -כלים עלולים להיכשל — ממשקי API עשויים לפוג תוקף, פרמטרים יכולים להיות לא תקינים, ושירותים חיצוניים יכולים להפסיק לפעול. סוכנים בייצור זקוקים לטיפול בשגיאות כדי שהדגם יוכל להסביר בעיות או לנסות חלופות במקום לקרוס. כאשר כלי זורק חריגה, LangChain4j תופס אותה ומחזיר את הודעת השגיאה לדגם, כך שהדגם יכול להסביר את הבעיה בשפת טבעית. +כלים יכולים להיכשל — APIים נגמרים בזמן, פרמטרים עלולים להיות לא חוקיים, שירותים חיצוניים נופלים. סוכני ייצור צריכים טיפול בשגיאות כדי שהמודל יוכל להסביר בעיות או לנסות אלטרנטיבות במקום לקרוס כל האפליקציה. כשכלי זורק חריגה, LangChain4j תופס אותה ומחזיר את הודעת השגיאה למודל, שיכול אז להסביר את הבעיה בשפה טבעית. ## כלים זמינים -התרשים הבא מראה את המערכת האקולוגית הרחבה של הכלים שניתן לבנות. מודול זה מדגים כלים למזג אוויר והמרת טמפרטורות, אך דפוס `@Tool` זהה פועל גם עבור כל שיטת Java — משאילתות לבסיסי נתונים ועד עיבוד תשלומים. +התמונה להלן מראה את האקוסיסטם הרחב של כלים שאפשר לבנות. מודול זה מדגים כלים של מזג אוויר וטמפרטורה, אך אותה תבנית `@Tool` עובדת עם כל שיטת Java — משאילתות מסד נתונים לעיבוד תשלומים. -Tool Ecosystem +אקוסיסטם כלים -*כל שיטת Java שמסומנת ב-@Tool זמינה ל-AI — הדפוס משתרע לבסיסי נתונים, APIs, דוא"ל, פעולות קבצים ועוד.* +*כל שיטת Java המסומנת ב-@Tool הופכת לזמינה לסוכן AI — התבנית מתרחבת למסדי נתונים, APIים, דוא"ל, פעולות קבצים ועוד.* -## מתי להשתמש בסוכני כלים +## מתי להשתמש בסוכנים מבוססי כלים -לא כל בקשה דורשת כלים. ההחלטה היא האם ה-AI צריך לתקשר עם מערכות חיצוניות או יכול לענות מתוך הידע שלו. המדריך הבא מסכם מתי הכלים מוסיפים ערך ומתי הם מיותרים: +לא כל בקשה דורשת כלים. ההחלטה תלויה אם ה-AI צריך אינטראקציה עם מערכות חיצוניות או יכול לענות מהידע שלו בלבד. המדריך הבא מסכם מתי כלים מוסיפים ערך ומתי הם מיותרים: -When to Use Tools +מתי להשתמש בכלים -*מדריך החלטות קצר — כלים הם עבור נתונים בזמן אמת, חישובים ופעולות; ידע כללי ומשימות יצירתיות לא זקוקים להם.* +*מדריך החלטה מהיר — כלים מיועדים לנתונים בזמן אמת, חישובים ופעולות; ידע כללי ומשימות יצירתיות לא דורשים אותם.* ## כלים לעומת RAG -מודולים 03 ו-04 מרחיבים את היכולות של ה-AI, אך בדרכים שונות במהותן. RAG מעניק לדגם גישה ל**ידע** על ידי אחזור מסמכים. כלים מאפשרים לדגם לבצע **פעולות** על ידי קריאות לפונקציות. התרשים הבא משווה בין שתי הגישות - כיצד כל זרימת עבודה פועלת ועד הפשרות שביניהן: +מודולים 03 ו-04 מגדילים את יכולות ה-AI, אך בדרכים שונות באופן יסודי. RAG נותן למודל גישה ל**ידע** על ידי אחזור מסמכים. כלים מאפשרים למודל לבצע **פעולות** באמצעות קריאות לפונקציות. התמונה הבאה משווה בין שתי הגישות זו לצד זו — מהאופן בו כל זרימת עבודה פועלת ועד לפשרות ביניהן: -Tools vs RAG Comparison +השוואה בין כלים ל-RAG -*RAG מושך מידע מתוך מסמכים סטטיים — כלים מבצעים פעולות ומגבשים נתונים דינמיים בזמן אמת. מערכות רבות בשימוש בייצור משלבות את שניהם.* +*RAG מושך מידע ממסמכים סטטיים — כלים מבצעים פעולות ואוספים נתונים דינמיים בזמן אמת. רבים ממערכות הייצור משלבות את שניהם.* -בפועל, מערכות רבות בשימוש בייצור משלבות את שתי הגישות: RAG לקרקע תשובות בתיעוד שלכם, וכלים לאחזור נתונים חיים או ביצוע פעולות. +בהכרח, מערכות ייצור רבות משלבות בין שתי הגישות: RAG להנחלת תשובות בתיעוד שלך, וכלים לאיסוף נתונים חיים או ביצוע פעולות. -## צעדים הבאים +## השלבים הבאים -**מודול הבא:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**מודול הבא:** [05-mcp - פרוטוקול הקשר למודל (MCP)](../05-mcp/README.md) --- -**ניווט:** [← קודם: מודול 03 - RAG](../03-rag/README.md) | [חזרה לעמוד הראשי](../README.md) | [הבא: מודול 05 - MCP →](../05-mcp/README.md) +**ניווט:** [← הקודם: מודול 03 - RAG](../03-rag/README.md) | [חזרה לעמוד הראשי](../README.md) | [הבא: מודול 05 - MCP →](../05-mcp/README.md) --- **כתב ויתור**: -מסמך זה תורגם באמצעות שירות תרגום בינה מלאכותית [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי דיוקים. המסמך המקורי בשפה המקורית שלו הוא המקור הסמכותי. למידע קריטי מומלץ להיעזר בתרגום מקצועי אנושי. איננו אחראים לכל אי הבנה או פרשנות שגויה שיתקבלו כתוצאה משימוש בתרגום זה. +מסמך זה תורגם באמצעות שירות תרגום אוטומטי [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש להחשיב את המסמך המקורי בשפתו הטבעית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אדם. אנו לא אחראים לכל אי-הבנה או פירוש שגוי הנובע מהשימוש בתרגום זה. \ No newline at end of file diff --git a/translations/he/README.md b/translations/he/README.md index 0de3564b5..183827383 100644 --- a/translations/he/README.md +++ b/translations/he/README.md @@ -2,18 +2,18 @@ # LangChain4j למתחילים -קורס לבניית יישומי בינה מלאכותית עם LangChain4j ו-Azure OpenAI GPT-5.2, מצ'אט בסיסי ועד סוכני AI. +קורס לבניית יישומי בינה מלאכותית עם LangChain4j ו-Azure OpenAI GPT-5.2, משיחה בסיסית עד סוכני בינה מלאכותית. -### 🌐 תמיכה ברב-שפות +### 🌐 תמיכה בריבוי שפות -#### נתמך באמצעות פעולה ב-GitHub (אוטומטי ותמיד מעודכן) +#### נתמכת באמצעות GitHub Action (אוטומטית ותמיד מעודכנת) -[ערבית](../ar/README.md) | [בנגלית](../bn/README.md) | [בולגרית](../bg/README.md) | [בורמזית (מיאנמר)](../my/README.md) | [סינית (מפושטת)](../zh-CN/README.md) | [סינית (מסורתית, הונג קונג)](../zh-HK/README.md) | [סינית (מסורתית, מקאו)](../zh-MO/README.md) | [סינית (מסורתית, טאיוואן)](../zh-TW/README.md) | [קרואטית](../hr/README.md) | [צ'כית](../cs/README.md) | [דנית](../da/README.md) | [הולנדית](../nl/README.md) | [אסטונית](../et/README.md) | [פינית](../fi/README.md) | [צרפתית](../fr/README.md) | [גרמנית](../de/README.md) | [יוונית](../el/README.md) | [עברית](./README.md) | [הינדי](../hi/README.md) | [הונגרית](../hu/README.md) | [אינדונזית](../id/README.md) | [איטלקית](../it/README.md) | [יפנית](../ja/README.md) | [קאנדה](../kn/README.md) | [חמרית](../km/README.md) | [קוריאנית](../ko/README.md) | [ליטאית](../lt/README.md) | [מלאית](../ms/README.md) | [מלאיאלאם](../ml/README.md) | [מראטי](../mr/README.md) | [נפאלית](../ne/README.md) | [ניגרית פידג'ין](../pcm/README.md) | [נורווגית](../no/README.md) | [פרסית (פרסי)](../fa/README.md) | [פולנית](../pl/README.md) | [פורטוגזית (ברזיל)](../pt-BR/README.md) | [פורטוגזית (פורטוגל)](../pt-PT/README.md) | [פנג'בית (גורמוכי)](../pa/README.md) | [רומנית](../ro/README.md) | [רוסית](../ru/README.md) | [סרבית (קירילית)](../sr/README.md) | [סלובקית](../sk/README.md) | [סלובנית](../sl/README.md) | [ספרדית](../es/README.md) | [סוואהילית](../sw/README.md) | [שוודית](../sv/README.md) | [טגאלוג (פיליפינית)](../tl/README.md) | [טמילית](../ta/README.md) | [טלוגו](../te/README.md) | [תאית](../th/README.md) | [טורקית](../tr/README.md) | [אוקראינית](../uk/README.md) | [אורדו](../ur/README.md) | [וייטנאמית](../vi/README.md) +[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](./README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **מעדיפים לשכפל מקומית?** +> **מעדיף לשכפל מקומית?** > -> מאגר זה כולל יותר מ-50 תרגומים של שפות, אשר מגדילים משמעותית את גודל ההורדה. לשכפול ללא תרגומים, השתמשו ב-sparse checkout: +> מאגר זה כולל יותר מ-50 תרגומים לשפות שונות שגדילים משמעותית את גודל ההורדה. כדי לשכפל ללא תרגומים, השתמש ב-sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,62 +29,59 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> זה נותן לכם את כל מה שצריך כדי להשלים את הקורס עם הורדה מהירה הרבה יותר. +> זה נותן לך את כל מה שאתה צריך כדי להשלים את הקורס במהירות הורדה גבוהה יותר. ## תוכן העניינים -1. [התחלה מהירה](00-quick-start/README.md) - התחילו עם LangChain4j -2. [מבוא](01-introduction/README.md) - למדו את יסודות LangChain4j -3. [הנדסת פרומפטים](02-prompt-engineering/README.md) - שלטו בעיצוב פרומפט יעיל -4. [RAG (יצירת תוכן משופרת בהבאה)](03-rag/README.md) - בניית מערכות מבוססות ידע חכמות -5. [כלים](04-tools/README.md) - אינטגרציה של כלים חיצוניים ועוזרים פשוטים -6. [MCP (פרוטוקול קונטקסט מודל)](05-mcp/README.md) - עבודה עם פרוטוקול קונטקסט מודל (MCP) ומודולים סוכנים +1. [הקדמה](01-introduction/README.md) - ללמוד את היסודות של LangChain4j +2. [הנדסת פרומפטים](02-prompt-engineering/README.md) - לשלוט בעיצוב פרומפטים אפקטיבי +3. [RAG (ייצור מחוזק אחזור)](03-rag/README.md) - לבנות מערכות מבוססות ידע חכמות +4. [כלים](04-tools/README.md) - לשלב כלים חיצוניים ועוזרים פשוטים +5. [MCP (פרוטוקול הקשר מודל)](05-mcp/README.md) - לעבוד עם פרוטוקול הקשר מודל (MCP) ומודולי סוכנים ### סיורים בווידאו -לכל מודול יש מושב חי בן שידור שבו עוברים שלב אחר שלב על הקונספטים והקוד. +לכל מודול יש מפגש חי נלווה שבו אנו עוברים שלב אחר שלב על המושגים והקוד. | מודול | וידאו | |--------|-------| -| 01 - מבוא | [התחלה עם LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 01 - הקדמה | [התחלה עם LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - הנדסת פרומפטים | [הנדסת פרומפטים עם LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG עם LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - כלים & 05 - MCP | [סוכני AI עם כלים ו-MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## מסלול למידה +## מסלול הלימוד -**חדש ב-LangChain4j?** עיינו ב-[מילון מונחים](docs/GLOSSARY.md) להגדרות מונחים ומושגים מרכזיים. +**חדש ב-LangChain4j?** עיין ב-[מילון המונחים](docs/GLOSSARY.md) להגדרות של מונחים ומושגים מרכזיים. > **התחלה מהירה** -1. פתחו ענף (Fork) למאגר זה לחשבון ה-GitHub שלכם -2. לחצו על **Code** → לשונית **Codespaces** → **...** → **New with options...** -3. השתמשו בהגדרות ברירת המחדל – זה יבחר את מיכל הפיתוח שיצרנו לקורס זה -4. לחצו על **Create codespace** -5. המתינו 5-10 דקות לסיום ההקמה של הסביבה -6. עברו ישר ל-[התחלה מהירה](./00-quick-start/README.md) כדי להתחיל! +1. פתח פורק של מאגר זה לחשבון ה-GitHub שלך +2. לחץ על **Code** → לשונית **Codespaces** → **...** → **חדש עם אפשרויות...** +3. השתמש כברירות המחדל – זה יבחר במכולת הפיתוח שנוצרה לקורס זה +4. לחץ על **Create codespace** +5. המתן 5-10 דקות לסיום הכנת הסביבה +6. קפוץ ישירות ל-[הקדמה](./01-introduction/README.md) כדי להתחיל! -לאחר השלמת המודולים, חקרו את [מדריך הבדיקות](docs/TESTING.md) כדי לראות את קונספטי הבדיקה של LangChain4j בפעולה. - -> **הערה:** ההדרכה הזו משתמשת גם בדגמי GitHub וגם ב-Azure OpenAI. מודול [התחלה מהירה](00-quick-start/README.md) משתמש בדגמי GitHub (אין צורך במנוי Azure), בעוד שהמודולים 1-5 משתמשים ב-Azure OpenAI. התחילו עם [חשבון Azure חינמי](https://aka.ms/azure-free-account) אם אין לכם כזה. +לאחר סיום המודולים, חקור את [מדריך הבדיקות](docs/TESTING.md) כדי לראות מושגי בדיקות של LangChain4j בפעולה. +> **הערה:** הדרכה זו משתמשת ב-Azure OpenAI. התחל עם [חשבון Azure חינמי](https://aka.ms/azure-free-account) אם אין לך אחד. ## למידה עם GitHub Copilot -כדי להתחיל לתכנת במהירות, פתחו את הפרויקט הזה בקודספייס של GitHub או ב-IDE מקומי עם devcontainer שסופק. ה-devcontainer בו משתמשים בקורס זה מוגדר מראש עם GitHub Copilot לתכנות משולב בינה מלאכותית. +כדי להתחיל לתכנת במהירות, פתח את הפרויקט הזה ב-GitHub Codespace או ב-IDE המקומי שלך עם devcontainer המסופק. ה-devcontainer שבו משתמשים בקורס זה מגיע מוגדר מראש עם GitHub Copilot לתכנות זוגי מבוסס AI. -כל דוגמת קוד כוללת שאלות מוצעות שתוכלו לשאול את GitHub Copilot להעמקת ההבנה שלכם. חפשו את הסימנים 💡/🤖 ב- +כל דוגמת קוד כוללת שאלות מוצעות שאתה יכול לשאול את GitHub Copilot כדי להעמיק את ההבנה שלך. חפש את הכותרות 💡/🤖 ב- - **כותרות קבצי Java** - שאלות ספציפיות לכל דוגמה -- **קבצי README של המודולים** - פיקודים לחקירה לאחר דוגמות הקוד - -**איך להשתמש:** פתחו כל קובץ קוד ושאלו את GitHub Copilot את השאלות המוצעות. יש לו הקשר מלא של מאגר הקוד ויכול להסביר, להרחיב ולהציע חלופות. +- **README של מודולים** - הנחיות לחקירה לאחר דוגמות קוד -רוצים ללמוד יותר? עיינו ב-[Copilot לתכנות משולב בינה מלאכותית](https://aka.ms/GitHubCopilotAI). +**איך משתמשים:** פתח כל קובץ קוד ושאל את Copilot את השאלות המוצעות. יש לו הקשר מלא של בסיס הקוד ויכול להסביר, להרחיב ולהציע אלטרנטיבות. +רוצה ללמוד עוד? עיין ב-[Copilot לתכנות זוגי מבוסס AI](https://aka.ms/GitHubCopilotAI). ## משאבים נוספים @@ -103,48 +100,48 @@ --- -### סדרת בינה מלאכותית גנרטיבית -[![בינה מלאכותית גנרטיבית למתחילים](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![בינה מלאכותית גנרטיבית (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![בינה מלאכותית גנרטיבית (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![בינה מלאכותית גנרטיבית (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### סדרת בינה מלאכותית יוצרת +[![בינה מלאכותית יוצרת למתחילים](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![בינה מלאכותית יוצרת (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![בינה מלאכותית יוצרת (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![בינה מלאכותית יוצרת (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### ליבת הלמידה +### לימוד בסיסי [![למידת מכונה למתחילים](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![מדעי הנתונים למתחילים](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![בינה מלאכותית למתחילים](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![סייברסקיוריטי למתחילים](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![פיתוח אתרים למתחילים](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT למתחילים](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![פיתוח XR למתחילים](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![אבטחת סייבר למתחילים](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### סדרת קופיילוט -[![קופיילוט לתכנות זוגי עם AI](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![קופיילוט ל-C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![הרפתקאות קופיילוט](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## קבלת עזרה +## לקבלת סיוע -אם אתה נתקל בבעיה או יש לך שאלות לגבי בניית אפליקציות AI, הצטרף ל: +אם נתקעת או יש לך שאלות על בניית אפליקציות בינה מלאכותית, הצטרף ל: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -אם יש לך משוב או בעיות בעת הבנייה בקר באתר: +אם יש לך משוב על המוצר או שגיאות בזמן בנייה בקרב: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## רישיון -רישיון MIT - עיין בקובץ [LICENSE](../../LICENSE) לפרטים. +רישיון MIT - ראה את קובץ [LICENSE](../../LICENSE) לפרטים. --- -**כתב ויתור**: -מסמך זה תורגם באמצעות שירות התרגום המלאכותי [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לשים לב כי תרגומים אוטומטיים עלולים להכיל טעויות או אי-דיוקים. המסמך המקורי בשפת המקור שלו נחשב למקור הסמכותי. למידע קריטי מומלץ להשתמש בתרגום מקצועי אנושי. איננו נושאים באחריות לכל אי-הבנות או פרשנויות שגויות הנובעות משימוש בתרגום זה. +**כתב ויתור**: +מסמך זה תורגם באמצעות שירות תרגום אוטומטי [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש להחשיב את המסמך המקורי בשפתו הטבעית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אדם. אנו לא אחראים לכל אי-הבנה או פירוש שגוי הנובע מהשימוש בתרגום זה. \ No newline at end of file diff --git a/translations/he/docs/GLOSSARY.md b/translations/he/docs/GLOSSARY.md index 6607373df..8c95ab18a 100644 --- a/translations/he/docs/GLOSSARY.md +++ b/translations/he/docs/GLOSSARY.md @@ -2,71 +2,71 @@ ## תוכן העניינים -- [מושגים מרכזיים](../../../docs) -- [רכיבי LangChain4j](../../../docs) -- [מושגי AI/ML](../../../docs) -- [מנגנוני הגנה](../../../docs) -- [הנדסת פרומפטים](../../../docs) -- [RAG (הפקה משודרגת על ידי אחזור)](../../../docs) -- [סוכנים וכלים](../../../docs) -- [מודול סוכני](../../../docs) -- [פרוטוקול הקשר מודל (MCP)](../../../docs) -- [שירותי Azure](../../../docs) -- [בדיקות ופיתוח](../../../docs) +- [מושגי ליבה](#מושגי-ליבה) +- [רכיבי LangChain4j](#רכיבי-langchain4j) +- [מושגי AI/ML](#מושגי-aiml) +- [קווי הגנה](#קווי-הגנה) +- [הנדסת פרומפט](#prompt-engineering---module-02) +- [RAG (יצירת תוכן מועשרת באחזור)](#rag-retrieval-augmented-generation---module-03) +- [סוכנים וכלים](#agents-and-tools---module-04) +- [מודול סוכני](#agentic-module---module-05) +- [פרוטוקול הקשר מודל (MCP)](#model-context-protocol-mcp---module-05) +- [שירותי Azure](#azure-services---module-01) +- [בדיקות ופיתוח](#testing-and-development---testing-guide) -הפניה מהירה למונחים ולמושגים שמשמשים לאורך הקורס. +התייחסות מהירה למונחים ומושגים בשימוש לאורך הקורס. -## מושגים מרכזיים +## מושגי ליבה -**סוכן AI** - מערכת המשתמשת ב-AI כדי להסיק מסקנות ולפעול באופן עצמאי. [מודול 04](../04-tools/README.md) +**סוכן AI** - מערכת המשתמשת בבינה מלאכותית כדי לחשוב ולפעול באופן אוטונומי. [מודול 04](../04-tools/README.md) -**שרשור** - רצף של פעולות כאשר הפלט מוזן לשלב הבא. +**שרשרת** - רצף של פעולות שבו הפלט מזין את השלב הבא. -**חלוקה לחלקים** - פירוק מסמכים לחלקים קטנים יותר. טיפוסי: 300-500 טוקנים עם חפיפה. [מודול 03](../03-rag/README.md) +**חיתוך** - פירוק מסמכים לחתיכות קטנות יותר. טיפוסי: 300-500 טוקנים עם חפיפה. [מודול 03](../03-rag/README.md) -**חלון הקשר** - מספר הטוקנים המרביים שהמודל יכול לעבד. GPT-5.2: 400K טוקנים (עד 272K קלט, 128K פלט). +**חלון הקשר** - מספר הטוקנים המקסימלי שמודל יכול לעבד. GPT-5.2: 400K טוקנים (עד 272K קלט, 128K פלט). -**אימבדינגים** - וקטורים מספריים המייצגים משמעות טקסטואלית. [מודול 03](../03-rag/README.md) +**הטמעות** - וקטורים נומריים המייצגים את משמעות הטקסט. [מודול 03](../03-rag/README.md) -**קריאת פונקציה** - המודל יוצר בקשות מובנות לקריאה לפונקציות חיצוניות. [מודול 04](../04-tools/README.md) +**קריאת פונקציה** - מודל שיוצר בקשות מובנות לקריאת פונקציות חיצוניות. [מודול 04](../04-tools/README.md) -**הלוצינציה** - כאשר מודלים מייצרים מידע שגוי אך סביר למראה. +**הלוצינציה** - כאשר מודלים מייצרים מידע שגוי אך סביר. -**פרומפט** - קלט טקסטואלי למודל שפה. [מודול 02](../02-prompt-engineering/README.md) +**פרומפט** - טקסט קלט למודל שפה. [מודול 02](../02-prompt-engineering/README.md) -**חיפוש סמנטי** - חיפוש על פי משמעות באמצעות אימבדינגים, לא לפי מילות מפתח. [מודול 03](../03-rag/README.md) +**חיפוש סמנטי** - חיפוש לפי משמעות באמצעות הטמעות, לא לפי מילות מפתח. [מודול 03](../03-rag/README.md) -**סטייטפול לעומת סטייטלס** - סטייטלס: ללא זיכרון. סטייטפול: שומר היסטוריית שיחה. [מודול 01](../01-introduction/README.md) +**מצבי זיכרון מול מצב ללא זיכרון** - ללא זיכרון: ללא היסטוריית שיחה. עם זיכרון: שומר היסטוריית שיחה. [מודול 01](../01-introduction/README.md) -**טוקנים** - יחידות הטקסט הבסיסיות שהמודלים מעבדים. משפיע על עלויות ומגבלות. [מודול 01](../01-introduction/README.md) +**טוקנים** - יחידות טקסט בסיסיות שהמודלים מעבדים. משפיע על עלויות ומגבלות. [מודול 01](../01-introduction/README.md) -**שרשור כלים** - ביצוע רציף של כלים כאשר הפלט משפיע על הקריאה הבאה. [מודול 04](../04-tools/README.md) +**שרשור כלים** - ביצוע כלי בסדר שבו הפלט משפיע על הקריאה הבאה. [מודול 04](../04-tools/README.md) ## רכיבי LangChain4j -**AiServices** - יוצר ממשקי שירות AI בטוחים מסוג. +**AiServices** - יוצר ממשקי שירותי AI בטיפוס בטוח. **OpenAiOfficialChatModel** - לקוח מאוחד למודלים של OpenAI ו-Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - יוצר אימבדינגים באמצעות הלקוח הרשמי של OpenAI (תומך ב-OpenAI ו-Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - יוצר הטמעות באמצעות לקוח OpenAI רשמי (תומך גם ב-OpenAI וגם ב-Azure OpenAI). **ChatModel** - ממשק ליבה למודלי שפה. **ChatMemory** - שומר היסטוריית שיחה. -**ContentRetriever** - מוצא חלקי מסמכים רלוונטיים ל-RAG. +**ContentRetriever** - מוצא חתיכות מסמך רלוונטיות ל-RAG. -**DocumentSplitter** - מפרק מסמכים לחלקים. +**DocumentSplitter** - מפרק מסמכים לחתיכות. -**EmbeddingModel** - ממיר טקסט לווקטורים מספריים. +**EmbeddingModel** - ממיר טקסט לווקטורים נומריים. -**EmbeddingStore** - מאחסן ומחזיר אימבדינגים. +**EmbeddingStore** - מאחסן ומבקש הטמעויות. -**MessageWindowChatMemory** - שומר חלון הזזה של הודעות אחרונות. +**MessageWindowChatMemory** - שומר חלון מחליק של הודעות אחרונות. -**PromptTemplate** - יוצר פרומפטים הניתנים לשימוש חוזר עם מקומות שמורים `{{variable}}`. +**PromptTemplate** - יוצר פרומפטים לשימוש חוזר עם מצייני מקום `{{variable}}`. -**TextSegment** - חלק טקסט עם מטה-נתונים. משמש ב-RAG. +**TextSegment** - חתיכת טקסט עם מטא-נתונים. משמש ב-RAG. **ToolExecutionRequest** - מייצג בקשת ביצוע כלי. @@ -74,123 +74,123 @@ ## מושגי AI/ML -**למידת דוגמאות מועטות (Few-Shot Learning)** - מתן דוגמאות בפרומפטים. [מודול 02](../02-prompt-engineering/README.md) +**למידה עם דוגמאות מועטות** - מתן דוגמאות בפרומפטים. [מודול 02](../02-prompt-engineering/README.md) -**מודל שפה גדול (LLM)** - מודלי AI שנלמדו על כמויות טקסט גדולות. +**מודל שפה גדול (LLM)** - מודלי AI המאומנים על כמויות טקסט גדולות. -**מאמץ הסקה** - פרמטר של GPT-5.2 ששולט בעומק החשיבה. [מודול 02](../02-prompt-engineering/README.md) +**מאמץ היסק** - פרמטר ב-GPT-5.2 השולט בעומק החשיבה. [מודול 02](../02-prompt-engineering/README.md) -**טמפרטורה** - שולטת ברנדומליות הפלט. נמוכה=דטרמיניסטי, גבוהה=יצירתי. +**טמפרטורה** - שולטת באקראיות הפלט. נמוכה=דטרמיניסטי, גבוהה=יצירתי. -**מסד נתונים וקטורי** - מסד נתונים מיוחד לאימבדינגים. [מודול 03](../03-rag/README.md) +**מסד וקטורים** - מסד נתונים ייעודי להטמעות. [מודול 03](../03-rag/README.md) -**למידת דוגמאות אפס (Zero-Shot Learning)** - ביצוע משימות ללא דוגמאות. [מודול 02](../02-prompt-engineering/README.md) +**למידה ללא דוגמאות** - ביצוע משימות ללא דוגמאות. [מודול 02](../02-prompt-engineering/README.md) -## מנגנוני הגנה - [מודול 00](../00-quick-start/README.md) +## קווי הגנה -**הגנה בעומק** - גישת אבטחה רב-שכבתית המשלבת מנגנוני הגנה ברמת האפליקציה עם מסנני בטיחות של ספקים. +**הגנה בעומק** - גישה רב-שכבתית לשמירה המשלבת קווי הגנה ברמת האפליקציה עם פילטרי בטיחות של ספק. -**חסימה קשיחה** - הספק מחזיר שגיאת HTTP 400 עבור הפרת תוכן חמורה. +**חסימה קשה** - ספק זורק שגיאת HTTP 400 עבור הפרות תוכן חמורות. -**InputGuardrail** - ממשק LangChain4j לאימות קלט משתמש לפני שהוא מגיע ל-LLM. חוסך עלויות ועכבה על ידי חסימת פרומפטים מזיקים מוקדם. +**InputGuardrail** - ממשק LangChain4j לאימות קלט משתמש לפני שהוא מגיע ל-LLM. חוסך עלויות ועיכובים על ידי חסימת פרומפטים מזיקים מוקדם. -**InputGuardrailResult** - סוג החזרה לאימות דרך מגבלות: `success()` או `fatal("reason")`. +**InputGuardrailResult** - סוג החזרה לאימות קווי הגנה: `success()` או `fatal("reason")`. **OutputGuardrail** - ממשק לאימות תגובות AI לפני החזרתן למשתמשים. -**מסנני בטיחות של ספקים** - מסנני תוכן מובנים מספקי AI (למשל, GitHub Models) שתופסים הפרות ברמת ה-API. +**פילטרי בטיחות ספק** - פילטרי תוכן מובנים מספקי AI (כגון Azure OpenAI) שתופסים הפרות ברמת ה-API. -**סרבנות רכה** - המודל מסרב בנימוס לענות מבלי להחזיר שגיאה. +**סרוב רך** - מודל מתרץ בנימוס סירוב למענה ללא זריקת שגיאה. -## הנדסת פרומפטים - [מודול 02](../02-prompt-engineering/README.md) +## הנדסת פרומפט - [מודול 02](../02-prompt-engineering/README.md) -**שרשרת מחשבה** - הסקה שלב-אחר-שלב לדיוק טוב יותר. +**שרשרת מחשבה** - היגיון שלב-אחרי-שלב לדיוק טוב יותר. **פלט מוגבל** - אכיפת פורמט או מבנה מסוים. -**רצון גבוה** - תבנית GPT-5.2 להסקה מעמיקה. +**רצון גבוה** - תבנית GPT-5.2 להיסק מעמיק. **רצון נמוך** - תבנית GPT-5.2 לתשובות מהירות. -**שיחה רב-סיבובית** - שימור הקשר לאורך החלפות שיחה. +**שיחה מרובת סבבים** - שמירת הקשר לאורך החלפות. -**פרומפט מבוסס תפקיד** - קביעת פרסונת מודל דרך הודעות מערכת. +**פרומפט מבוסס תפקיד** - קביעת פרסונה של המודל באמצעות הודעות מערכת. -**הרהור עצמי** - המודל מעריך ומשפר את הפלט שלו. +**השתקפות עצמית** - המודל מעריך ומשפר את הפלט שלו. -**אנליזה מובנית** - מסגרת הערכה קבועה. +**ניתוח מובנה** - מסגרת הערכה קבועה. -**תבנית ביצוע משימה** - תכנון → ביצוע → סיכום. +**תבנית ביצוע משימה** - תכנן → בצע → סכם. -## RAG (הפקה משודרגת על ידי אחזור) - [מודול 03](../03-rag/README.md) +## RAG (יצירת תוכן מועשרת באחזור) - [מודול 03](../03-rag/README.md) -**צינור עיבוד מסמכים** - טעינה → חלוקה → הטמעה → אחסון. +**צינור עיבוד מסמכים** - טעינה → חיתוך → הטמעה → אחסון. -**חנות אימבדינג בזיכרון** - אחסון בלתי-מתקיים לבדיקות. +**מאגר הטמעות בזיכרון** - אחסון שאינו מתמיד לבדיקות. -**RAG** - משלב אחזור עם הפקה כדי לעגן תגובות. +**RAG** - משלב אחזור עם יצירה כדי לעגן תגובות. **ציון דמיון** - מדד (0-1) של דמיון סמנטי. -**התייחסות למקור** - מטה-נתונים על התוכן שהוחזר. +**הפניה למקור** - מטא-נתונים אודות התוכן שנשלף. ## סוכנים וכלים - [מודול 04](../04-tools/README.md) -**@Tool Annotation** - מסמן מתודות Java ככלים הקריאים על ידי AI. +**@Tool Annotation** - מציין מתודות Java ככלים הניתנים לקריאה על ידי AI. -**תבנית ReAct** - הסקה → פעולה → תצפית → חזרה. +**תבנית ReAct** - חשיבה → פעולה → תצפית → חזרה. **ניהול מושבים** - הקשרים נפרדים למשתמשים שונים. -**כלי** - פונקציה שניתן להפעיל על ידי סוכן AI. +**כלי** - פונקציה שסוכן AI יכול לקרוא לה. -**תיאור כלי** - תיעוד מטרת הכלי ופרמטרים. +**תיאור כלי** - תיעוד המטרה והפרמטרים של הכלי. ## מודול סוכני - [מודול 05](../05-mcp/README.md) -**@Agent Annotation** - מסמן ממשקים כסוכני AI עם הגדרה הצהרתית של התנהגות. +**@Agent Annotation** - מציין ממשקים כסוכני AI עם הגדרת התנהגות דקלרטיבית. -**מאזין סוכן** - וו למעקב ביצוע סוכן דרך `beforeAgentInvocation()` ו-`afterAgentInvocation()`. +**Agent Listener** - וו למעקב ביצוע סוכן דרך `beforeAgentInvocation()` ו-`afterAgentInvocation()`. -**היקף סוכני** - זיכרון משותף בו סוכנים מאחסנים פלטים באמצעות `outputKey` לצריכה על ידי סוכנים אחרים. +**Agentic Scope** - זיכרון משותף שבו סוכנים מאחסנים פלטים באמצעות `outputKey` לצריכה של סוכנים בהמשך. -**AgenticServices** - בית חרושת ליצירת סוכנים באמצעות `agentBuilder()` ו-`supervisorBuilder()`. +**AgenticServices** - מפעל ליצירת סוכנים באמצעות `agentBuilder()` ו-`supervisorBuilder()`. -**זרימת עבודה מותנית** - ניתוב לפי תנאים לסוכנים מומחים שונים. +**זרימת עבודה מותנית** - ניתוב מבוסס תנאים לסוכנים מומחים שונים. -**אדם בלולאה** - תבנית עבודה שמוסיפה נקודות בדיקה אנושיות לאישור או סקירת תוכן. +**אדם בלולאה** - תבנית עבודה הכוללת נקודות בדיקה אנושיות לאישור או סקירת תוכן. -**langchain4j-agentic** - תלות Maven לבניית סוכנים הצהרתית (ניסיוני). +**langchain4j-agentic** - תלות Maven לבניית סוכנים דקלרטיבית (נסיוני). -**לולאת עבודה** - איטרציה של ביצוע סוכן עד שמתקיים תנאי (למשל, ציון איכות ≥ 0.8). +**זרימת עבודה מחזורית** - איטרציה של ביצוע סוכן עד שהתקיים תנאי (למשל ציון איכות ≥ 0.8). -**outputKey** - פרמטר אנוטציית סוכן המפרט היכן נשמרים התוצאות בהיקף הסוכני. +**outputKey** - פרמטר אנוטציה של סוכן המגדיר היכן נשמרים התוצאות ב-Agentic Scope. -**זרימת עבודה מקבילית** - הרצת מספר סוכנים במקביל למשימות עצמאיות. +**זרימת עבודה מקבילית** - הרצת סוכנים רבים במקביל למשימות עצמאיות. -**אסטרטגיית תגובה** - כיצד הממונה מנסח תשובה סופית: האחרון, סיכום, או מדורג. +**אסטרטגיית תגובה** - כיצד המפקח מנסח תשובה סופית: אחרון, סיכום, או מדורג. -**זרימת עבודה סדרתית** - ביצוע סוכנים בסדר שהפלט זורם לשלב הבא. +**זרימת עבודה עוקבת** - ביצוע סוכנים בסדר שבו הפלט זורם לשלב הבא. -**תבנית סוכן ממונה** - תבנית סוכני מתקדמת שבה LLM ממונה מחליט דינמית אילו סוכנים משניים להפעיל. +**תבנית סוכן מפקח** - תבנית סוכנית מתקדמת שבה LLM מפקח מחליט דינמית אילו תת-סוכנים להפעיל. ## פרוטוקול הקשר מודל (MCP) - [מודול 05](../05-mcp/README.md) **langchain4j-mcp** - תלות Maven לאינטגרציה של MCP ב-LangChain4j. -**MCP** - פרוטוקול הקשר מודל: סטנדרט לחיבור אפליקציות AI לכלים חיצוניים. בנה פעם, השתמש בכל מקום. +**MCP** - פרוטוקול הקשר מודל: תקן לחיבור אפליקציות AI לכלים חיצוניים. בנה פעם אחת, השתמש בכל מקום. -**לקוח MCP** - אפליקציה שמתחברת לשרתי MCP לגילוי ושימוש בכלים. +**לקוח MCP** - אפליקציה המחוברת לשרתים של MCP לגילוי ושימוש בכלים. -**שרת MCP** - שירות המציע כלים דרך MCP עם תיאורים ברורים וסכימות פרמטרים. +**שרת MCP** - שירות המביא את הכלים דרך MCP עם תיאורים ברורים וסכימות פרמטרים. -**McpToolProvider** - רכיב LangChain4j העוטף כלים של MCP לשימוש בשירותי AI וסוכנים. +**McpToolProvider** - רכיב של LangChain4j העוטף כלים של MCP לשימוש בשירותי AI וסוכנים. **McpTransport** - ממשק לתקשורת MCP. מימושים כוללים Stdio ו-HTTP. -**תחבורה Stdio** - תחבורה מקומית דרך stdin/stdout. שימושי לגישה לקבצים או כלים שורת פקודה. +**שילוח Stdio** - התקשרות תהליכים מקומי דרך stdin/stdout. שימושי לגישה למערכת הקבצים או כלי שורת פקודה. -**StdioMcpTransport** - מימוש LangChain4j המשיק שרת MCP כתת-תהליך. +**StdioMcpTransport** - מימוש LangChain4j שיוצר תהליך משנה של שרת MCP. **גילוי כלים** - הלקוח שואל את השרת על כלים זמינים עם תיאורים וסכימות. @@ -198,35 +198,33 @@ **Azure AI Search** - חיפוש בענן עם יכולות וקטוריות. [מודול 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - לפריסה של משאבי Azure. +**Azure Developer CLI (azd)** - פריסת משאבי Azure. **Azure OpenAI** - שירות AI ארגוני של מיקרוסופט. -**Bicep** - שפת תשתית כקוד של Azure. [מדריך תשתית](../01-introduction/infra/README.md) +**Bicep** - שפת התשתית-כקוד של Azure. [מדריך תשתית](../01-introduction/infra/README.md) **שם פריסה** - שם לפריסת מודל ב-Azure. -**GPT-5.2** - מודל OpenAI העדכני עם בקרת הסקה. [מודול 02](../02-prompt-engineering/README.md) +**GPT-5.2** - המודל העדכני ביותר של OpenAI עם בקרה על חשיבה. [מודול 02](../02-prompt-engineering/README.md) ## בדיקות ופיתוח - [מדריך בדיקות](TESTING.md) -**מכל פיתוח** - סביבה מבודדת לפיתוח. [הגדרות](../../../.devcontainer/devcontainer.json) +**Dev Container** - סביבת פיתוח מכולה. [קונפיגורציה](../../../.devcontainer/devcontainer.json) -**GitHub Models** - מגרש משחקים חינמי למודלי AI. [מודול 00](../00-quick-start/README.md) - -**בדיקות בזיכרון** - בדיקות עם אחסון בזיכרון. +**בדיקה בזיכרון** - בדיקות עם אחסון זיכרוני. **בדיקות אינטגרציה** - בדיקות עם תשתית אמיתית. **Maven** - כלי אוטומציה לבניית Java. -**Mockito** - מסגרת לדימוי ב-Java. +**Mockito** - מסגרת לעידוד מיזוג ב-Java. -**Spring Boot** - מסגרת אפליקציות Java. [מודול 01](../01-introduction/README.md) +**Spring Boot** - מסגרת אפליקציה ב-Java. [מודול 01](../01-introduction/README.md) --- **כתב ויתור**: -מסמך זה תורגם באמצעות שירות תרגום מבוסס בינה מלאכותית [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדייק, יש להביא בחשבון כי תרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. המסמך המקורי בשפתו הטבעית צריך להיחשב כמקור הסמכותי. למידע קריטי מומלץ להיעזר בתרגום מקצועי אנושי. איננו אחראים לכל אי-הבנה או פרשנות שגויה הנובעת מהשימוש בתרגום זה. +מסמך זה תורגם באמצעות שירות תרגום אוטומטי [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש להחשיב את המסמך המקורי בשפתו הטבעית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אדם. אנו לא אחראים לכל אי-הבנה או פירוש שגוי הנובע מהשימוש בתרגום זה. \ No newline at end of file diff --git a/translations/he/docs/TESTING.md b/translations/he/docs/TESTING.md index ff4beec73..ca4a175f2 100644 --- a/translations/he/docs/TESTING.md +++ b/translations/he/docs/TESTING.md @@ -2,19 +2,19 @@ ## תוכן העניינים -- [התחלה מהירה](../../../docs) -- [מה הבדיקות מכסות](../../../docs) -- [הרצת הבדיקות](../../../docs) -- [הרצת בדיקות ב-VS Code](../../../docs) -- [דפוסי בדיקה](../../../docs) -- [פילוסופיית בדיקה](../../../docs) -- [השלבים הבאים](../../../docs) +- [התחלה מהירה](#התחלה-מהירה) +- [מה מכסים הבדיקות](#מה-מכסים-הבדיקות) +- [הרצת הבדיקות](#הרצת-הבדיקות) +- [הרצת בדיקות ב-VS Code](#הרצת-בדיקות-ב-vs-code) +- [תבניות בדיקה](#תבניות-בדיקה) +- [פילוסופיית בדיקה](#פילוסופיית-בדיקה) +- [שלבים הבאים](#שלבים-הבאים) -מדריך זה מלמד כיצד לבדוק יישומי AI ללא צורך במפתחות API או שירותים חיצוניים. +מדריך זה מלווה אותך דרך הבדיקות שמדגימות כיצד לבדוק יישומי בינה מלאכותית מבלי שידרשו מפתחות API או שירותים חיצוניים. ## התחלה מהירה -הרץ את כל הבדיקות באמצעות פקודה אחת: +הפעל את כל הבדיקות עם פקודה אחת: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -כאשר כל הבדיקות עוברות, תראה פלט כמו בתמונה למטה — בדיקות רצות ללא כישלונות. +כשהכל עובר, תראה פלט כמו הצילום מסך מטה — הבדיקות רצות ללא כישלונות. -תוצאות בדיקות מוצלחות +Successful Test Results -*הרצת בדיקות מוצלחת המציגה את מעבר כל הבדיקות ללא כישלונות* +*ביצוע בדיקות מוצלחות המציג את כל הבדיקות שעוברות ללא כישלונות* -## מה הבדיקות מכסות +## מה מכסים הבדיקות -קורס זה מתמקד ב**בדיקות יחידה** שרצות מקומית. כל בדיקה מדגימה רעיון ספציפי ב־LangChain4j באופן מבודד. פירמידת הבדיקות למטה מראה היכן מתמקמים בדיקות היחידה — הן היסוד המהיר והאמין שעליו נשענת שאר אסטרטגיית הבדיקה שלך. +הקורס מתמקד ב**בדיקות יחידה** שמתבצעות מקומית. כל בדיקה מדגימה מושג ספציפי של LangChain4j בנפרד. פירמידת הבדיקות מטה מראה איפה בדיקות היחידה מתמקמות — הן הבסיס המהיר והאמין שעליו נשענת שאר אסטרטגיית הבדיקות שלך. -פירמידת בדיקה +Testing Pyramid -*פירמידת בדיקה המציגה את האיזון בין בדיקות יחידה (מהירות, מבודדות), בדיקות אינטגרציה (רכיבים אמיתיים) ובדיקות מקצה לקצה. הכשרה זו מכסה בדיקות יחידה.* +*פירמידת בדיקות המראה את האיזון בין בדיקות יחידה (מהירות, מבודדות), בדיקות אינטגרציה (רכיבים אמיתיים), ובדיקות מקצה לקצה. אימון זה מכסה בדיקות יחידה.* -| מודול | בדיקות | מיקוד | קבצים עיקריים | +| מודול | בדיקות | מיקוד | קבצים מרכזיים | |--------|-------|-------|-----------| -| **00 - התחלה מהירה** | 6 | תבניות פקודות והחלפת משתנים | `SimpleQuickStartTest.java` | -| **01 - מבוא** | 8 | זיכרון שיחה וצ׳אט מדינתי | `SimpleConversationTest.java` | -| **02 - הנדסת פקודות** | 12 | דפוסי GPT-5.2, דרגות נכונות, פלט מובנה | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | ספיגת מסמכים, הטמעות, חיפוש דמיון | `DocumentServiceTest.java` | -| **04 - כלים** | 12 | קריאת פונקציות ורצף כלים | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | פרוטוקול הקשר לדגם עם תקשורת stdio | `SimpleMcpTest.java` | +| **01 - מבוא** | 8 | זיכרון שיחות וצ'אט עם מצב | `SimpleConversationTest.java` | +| **02 - הנדסת פרומפטים** | 12 | דפוסי GPT-5.2, רמות נימוס, פלט מובנה | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | קליטת מסמכים, הטמעות, חיפוש דמיון | `DocumentServiceTest.java` | +| **04 - כלים** | 12 | קריאת פונקציות ושרשור כלים | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | פרוטוקול הקשר מודל עם הובלה stdio | `SimpleMcpTest.java` | ## הרצת הבדיקות -**הפעל את כל הבדיקות מהספרייה הראשית:** +**הרץ את כל הבדיקות מהספרייה הראשית:** **Bash:** ```bash @@ -63,12 +62,12 @@ mvn test mvn --% test ``` -**הרץ בדיקות למודול ספציפי:** +**הפעל בדיקות למודול מסוים:** **Bash:** ```bash cd 01-introduction && mvn test -# או מהשורש +# או משורש mvn test -pl 01-introduction ``` @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**הרץ מחלקת בדיקות אחת:** +**הרץ מחלקת בדיקה יחידה:** **Bash:** ```bash @@ -105,31 +104,31 @@ mvn --% test -Dtest=SimpleConversationTest#יש לשמור על היסטוריי ## הרצת בדיקות ב-VS Code -אם אתה משתמש ב-Visual Studio Code, חלון Test Explorer מספק ממשק גרפי להרצה ודיבוג של הבדיקות. +אם אתה משתמש ב-Visual Studio Code, התוסף Test Explorer מספק ממשק גרפי להרצה ודיבוג של בדיקות. VS Code Test Explorer -*חלון VS Code Test Explorer המציג עץ בדיקות עם כל מחלקות הבדיקה בג׳אווה ושיטות בדיקה בודדות* +*Test Explorer ב-VS Code המציג את עץ הבדיקות עם כל מחלקות בדיקות Java ושיטות בדיקה פרטניות* -**כיצד להפעיל בדיקות ב-VS Code:** +**להריץ בדיקות ב-VS Code:** -1. פתח את Test Explorer על ידי לחיצה על סמל הכור במערכת הפעילות -2. פתח את עץ הבדיקות בכדי לראות את כל המודולים ומחלקות הבדיקה -3. לחץ על כפתור ההפעלה ליד כל בדיקה להפעלה בודדת שלה -4. לחץ על "הרץ את כל הבדיקות" כדי להריץ את כל הסט -5. לחץ על הכפתור הימני בכל בדיקה ובחר "Debug Test" להגדרת נקודות עצירה ושלב דרך הקוד +1. פתח את Test Explorer על ידי לחיצה על סמל המבחנה בסרגל הפעילות +2. הרחב את עץ הבדיקות כדי לראות את כל המודולים ומחלקות הבדיקה +3. לחץ על כפתור ההפעלה ליד כל בדיקה כדי להריץ אותה בנפרד +4. לחץ על "Run All Tests" להריץ את כל המבחנים ביחד +5. לחץ קליק ימני על בדיקה ובחר "Debug Test" כדי להגדיר נקודות עצירה ולנווט בקוד -האקספלורר מציג סימני וי ירוקים לבדיקות שעוברות ומספק הודעות כשל מפורטות כשיש כישלון. +Test Explorer מראה סימני ביקורת ירוקים עבור בדיקות שעוברות ומספק הודעות כשל מפורטות כשביצוע נכשל. -## דפוסי בדיקה +## תבניות בדיקה -### דפוס 1: בדיקת תבניות פקודות +### תבנית 1: בדיקת תבניות פרומפט -הדפוס הפשוט ביותר בודק תבניות פקודות מבלי לקרוא למודל AI. אתה מוודא שהחלפת המשתנים עובדת כהלכה והפקודות מעוצבות כצפוי. +התבנית הפשוטה ביותר בודקת תבניות פרומפט בלי לקרוא למודל AI. אתה מוודא שהחלפת המשתנים מתבצעת כראוי והפרומפטים מעוצבים כנדרש. -בדיקת תבניות פקודות +Prompt Template Testing -*בדיקת תבניות פקודות המראה את זרימת החלפת המשתנים: תבנית עם מקומות מילוי → ערכים מוחלים → הפלט המעוצב נבדק* +*בדיקת תבניות פרומפט המציגה את זרימת החלפת המשתנים: תבנית עם מחסני מקומות → ערכים מוחלים → פלט מעוצב מאומת* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -בדיקה זו נמצאת ב־`00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**הפעל אותה:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#בדיקת עיצוב תבנית ההנחיה -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#פורמט תבנית הבקשה למבחן -``` +תבנית זו מאמתת שהחלפת משתנים עובדת כראוי והפרומפטים מעוצבים כנדרש — ללא צורך במפתח API או קריאת מודל. -### דפוס 2: יצירת דגמים מדומים (Mocking) +### תבנית 2: יצירת מודלים מדומים (Mocking) -כשבודקים לוגיקת שיחה, השתמש ב-Mockito ליצירת דגמים מדומים שמחזירים תגובות קבועות מראש. זה מייעל את הבדיקות והופך אותן למהירות, חינמיות ודטרמיניסטיות. +כשבודקים לוגיקת שיחה, משתמשים ב-Mockito ליצירת מודלים מדומים שמחזירים תגובות מוכנות מראש. זה הופך את הבדיקות למהירות, חינמיות ודטרמיניסטיות. -השוואת קריאת API מדומה מול אמיתית +Mock vs Real API Comparison -*השוואה שמדגימה מדוע עדיף להשתמש בדגמי מוק עבור בדיקות: הם מהירים, חינמיים, ודטרמיניסטיים ובנוסף אינם דורשים מפתחות API* +*השוואה המדגימה למה Mocks מועדפים בבדיקות: הם מהירים, חינמיים, דטרמיניסטיים, ולא דורשים מפתחות API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -דפוס זה מופיע ב־`01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. המוק מבטיח התנהגות עקבית כך שניתן לוודא שזיכרון השיחה מנוהל כהלכה. +תבנית זו מופיעה בקובץ `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. ה-Mock מקנה התנהגות עקבית כך שתוכל לבדוק ניהול זיכרון נכון. -### דפוס 3: בדיקת בידוד שיחה +### תבנית 3: בדיקת בידוד שיחות -זיכרון השיחה חייב להפריד בין משתמשים שונים. בדיקה זו מוודאת ששיחות לא מתערבבות זו בזו. +זיכרון השיחה חייב להפריד בין משתמשים שונים. בדיקה זו מאמתת ששיחות לא מערבלות הקשרים. -בידוד שיחה +Conversation Isolation -*בדיקת בידוד שיחה שמראה ניתוב זיכרונות נפרדים למשתמשים שונים למניעת עירבוב הקשר* +*בדיקת בידוד שיחות המראה חנויות זיכרון נפרדות למשתמשים שונים למניעת ערבוב הקשרים* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -כל שיחה שומרת היסטוריה עצמאית משלה. במערכות ייצור, הבידוד הזה הוא קריטי ליישומים מרובי משתמשים. +כל שיחה שומרת היסטוריה נפרדת משלה. במערכות פרודקשן הבידוד הזה קריטי ליישומים עם משתמשים מרובים. -### דפוס 4: בדיקת כלים באופן עצמאי +### תבנית 4: בדיקת כלים בנפרד -כלים הם פונקציות שה-AI יכול לקרוא להן. בדוק אותם ישירות כדי לוודא שהם עובדים נכון בלי תלות בהחלטות AI. +כלים הם פונקציות שה-AI יכול לקרוא להן. בדוק אותם ישירות כדי לוודא שהם עובדים כראוי ללא תלות בהחלטות של ה-AI. -בדיקת כלים +Tools Testing -*בדיקת כלים באופן עצמאי המראה הפעלת כלים מדומים ללא קריאות AI לאימות הלוגיקה העסקית* +*בדיקת כלים בצורה עצמאית המציגה הרצת כלים מדומים ללא קריאות AI כדי לוודא לוגיקת עסקים* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -בדיקות אלו מ־`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` מאמתות לוגיקת כלים ללא מעורבות AI. דוגמת הרצף מראה כיצד פלט של כלי אחד מוזן כקלט לאחר. +בדיקות אלו מקובץ `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` מאמתות לוגיקת כלים בלי מעורבות AI. דוגמת השרשור מראה כיצד פלט של כלי אחד מוזן לקלט של כלי אחר. -### דפוס 5: בדיקת RAG בזיכרון +### תבנית 5: בדיקת RAG בזיכרון -מערכות RAG במקור דורשות מסדי נתונים וקטוריים ושירותי הטמעות. דפוס הבדיקה בזיכרון מאפשר לבדוק את כל הצינור ללא תלות חיצונית. +מערכות RAG בדרך כלל דורשות מאגרי וקטורים ושירותי הטמעות. תבנית בזיכרון מאפשרת לך לבדוק את כל הצינור בלי תלות חיצונית. -בדיקת RAG בזיכרון +In-Memory RAG Testing -*זרימת בדיקת RAG בזיכרון שמדגימה ניתוח מסמכים, אחסון הטמעות, וחיפוש דמיון ללא צורך במסד נתונים* +*זרימת עבודה לבדיקה בזיכרון של RAG המציגה ניתוח מסמכים, אחסון הטמעות וחיפוש דמיון ללא צורך במסד נתונים* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -בדיקה זו מ־`03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` יוצרת מסמך בזיכרון ובודקת את פיצולו ואת ניהול המידע המטא. +בדיקה זו מקובץ `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` יוצרת מסמך בזיכרון ומאמתת פרגמנטציה וניהול מטא-נתונים. -### דפוס 6: בדיקת אינטגרציה של MCP +### תבנית 6: בדיקת אינטגרציה MCP -מודול MCP בודק את אינטגרציית פרוטוקול הקשר לדגם באמצעות תקשורת stdio. בדיקות אלו בודקות שהיישום שלך יכול ליצור ולתקשר עם שרתי MCP כתהליכים משניים. +מודול MCP בודק אינטגרציה של פרוטוקול הקשר מודל עם העברת stdio. בדיקות אלו מאמתות שהאפליקציה שלך יכולה להפעיל ולתקשר עם שרתי MCP כתהליכים משניים. -בדיקות ב־`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` מאמתות את התנהגות לקוח MCP. +הבדיקות ב-`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` מאמתות התנהגות לקוח MCP. -**הפעל אותן:** +**הרץ אותן:** **Bash:** ```bash @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## פילוסופיית בדיקה -בדוק את הקוד שלך, לא את ה-AI. הבדיקות שלך צריכות לאמת את הקוד שכתבת על ידי בדיקה כיצד נבנות הפקודות, כיצד מנוהל הזיכרון וכיצד הכלים מתבצעים. תגובות AI משתנות ואינן צריכות להיות חלק מההנחות בבדיקה. שאל את עצמך האם תבנית הפקודה שלך מחליפה משתנים כראוי, לא האם ה-AI נותן את התשובה הנכונה. +בדוק את הקוד שלך, לא את ה-AI. הבדיקות שלך אמורות לוודא את הקוד שכתבת על ידי בדיקת אופן בניית הפרומפטים, ניהול הזיכרון והפעלת הכלים. תגובות ה-AI משתנות ואסור שיהיו חלק מהוספות הבדיקות. שאל את עצמך אם תבנית הפרומפט מחליפה משתנים כראוי, לא אם ה-AI נותן את התשובה הנכונה. -השתמש במוקים לדגמי השפה. אלה תלות חיצונית שיכולה להיות איטית, יקרה ואינה דטרמיניסטית. מוקים מקצרים את זמן הבדיקה למילישניות במקום שניות, חינמיים ללא עלויות API, ודטרמיניסטיים עם תוצאה זהה בכל פעם. +השתמש ב-Mocks עבור מודלי שפה. הם תלות חיצונית שאיטית, יקרה, ולא דטרמיניסטית. Mocking הופך את הבדיקות למהירות תוך מילישניות במקום שניות, חינמיות ללא עלויות API, ודטרמיניסטיות עם אותו תוצאה בכל פעם. -שמור על בדיקות עצמאיות. כל בדיקה צריכה להגדיר את הנתונים שלה, לא להסתמך על בדיקות אחרות, ולנקות אחריה. בדיקות צריכות לעבור בכל סדר הרצה. +שמור על בדיקות עצמאיות. כל בדיקה צריכה להגדיר את הנתונים שלה, לא להסתמך על בדיקות אחרות, ולנקות אחריה. בדיקות צריכות לעבור ללא תלות בסדר הריצה. -בדוק מקרים קיצוניים מעבר לדרך הטבעית. נסה קלטים ריקים, גדולים מאוד, תווים מיוחדים, פרמטרים לא תקינים, ותנאי גבול. אלה לעיתים חושפים באגים שלא מופיעים בשימוש רגיל. +בדוק מקרים קיצוניים מעבר לנתיב המאושר. נסה קלטים ריקים, קלטים מאוד גדולים, תווים מיוחדים, פרמטרים לא תקינים ותנאי גבול. אלו לעיתים חושפים באגים ששימוש רגיל לא מראה. -השתמש בשמות תיאורים. השווה בין `shouldMaintainConversationHistoryAcrossMultipleMessages()` ל־`test1()`. הראשון אומר בדיוק מה נבדק, מה שמקל על איתור תקלות. +השתמש בשמות תיאוריים. השווה בין `shouldMaintainConversationHistoryAcrossMultipleMessages()` ל- `test1()`. הראשון אומר במדויק מה נבדק, מה שמקל מאוד על איתור כשלונות ודיבוג. -## השלבים הבאים +## שלבים הבאים -כעת כשאתה מבין את דפוסי הבדיקה, צלול עמוק יותר בכל מודול: +כעת כאשר הבנת את תבניות הבדיקה, העמק בכל מודול: -- **[00 - התחלה מהירה](../00-quick-start/README.md)** - התחיל מבסיס תבניות פקודות -- **[01 - מבוא](../01-introduction/README.md)** - למד ניהול זיכרון שיחה -- **[02 - הנדסת פקודות](../02/prompt-engineering/README.md)** - התמחה בדפוסי הנעת GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - בנה מערכות יצור-מגובה בדילוגים -- **[04 - כלים](../04-tools/README.md)** - מימש קריאות לפונקציות ורצפי כלים -- **[05 - MCP](../05-mcp/README.md)** - שלב פרוטוקול הקשר לדגם +- **[01 - מבוא](../01-introduction/README.md)** - למד ניהול זיכרון שיחות +- **[02 - הנדסת פרומפטים](../02-prompt-engineering/README.md)** - לשלוט בדפוסי פרומפט GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - בנה מערכות יצירה מוגברות בעזרת אחזור +- **[04 - כלים](../04-tools/README.md)** - יישם קריאת פונקציות ושרשראות כלים +- **[05 - MCP](../05-mcp/README.md)** - שלב את פרוטוקול הקשר מודל -קובצי README של כל מודול מספקים הסברים מפורטים על המושגים הנבדקים כאן. +קובץ README של כל מודול מספק הסברים מפורטים על המושגים שנבדקו כאן. --- @@ -358,6 +344,6 @@ cd 05-mcp; mvn --% test --- -**כתב ויתור**: -מסמך זה תורגם באמצעות שירות תרגום מבוסס בינה מלאכותית [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדייק, יש להבחין כי תרגומים אוטומטיים עלולים לכלול שגיאות או אי דיוקים. המסמך המקורי בשפת המקור שלו הוא המקור הסמכותי. עבור מידע קריטי מומלץ להיעזר בתרגום מקצועי אנושי. אנו לא נושאים באחריות לכל אי הבנה או פרשנות שגויה הנובעת משימוש בתרגום זה. +**כתב ויתור**: +מסמך זה תורגם באמצעות שירות תרגום אוטומטי [Co-op Translator](https://github.com/Azure/co-op-translator). למרות שאנו שואפים לדיוק, יש לקחת בחשבון שתרגומים אוטומטיים עלולים להכיל שגיאות או אי-דיוקים. יש להחשיב את המסמך המקורי בשפתו הטבעית כמקור הסמכות. למידע קריטי מומלץ להשתמש בתרגום מקצועי על ידי מתרגם אדם. אנו לא אחראים לכל אי-הבנה או פירוש שגוי הנובע מהשימוש בתרגום זה. \ No newline at end of file diff --git a/translations/hi/.co-op-translator.json b/translations/hi/.co-op-translator.json index dbf77c759..632753a94 100644 --- a/translations/hi/.co-op-translator.json +++ b/translations/hi/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "hi" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T23:09:50+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T07:54:35+00:00", "source_file": "01-introduction/README.md", "language_code": "hi" }, @@ -18,20 +18,20 @@ "language_code": "hi" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T23:12:14+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T07:49:34+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "hi" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T23:13:36+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T07:53:32+00:00", "source_file": "03-rag/README.md", "language_code": "hi" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:02:52+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T07:52:02+00:00", "source_file": "04-tools/README.md", "language_code": "hi" }, @@ -54,8 +54,8 @@ "language_code": "hi" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:44:29+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T07:48:00+00:00", "source_file": "README.md", "language_code": "hi" }, @@ -72,14 +72,14 @@ "language_code": "hi" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T23:17:02+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T07:50:01+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "hi" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T23:17:46+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T07:50:42+00:00", "source_file": "docs/TESTING.md", "language_code": "hi" } diff --git a/translations/hi/00-quick-start/README.md b/translations/hi/00-quick-start/README.md deleted file mode 100644 index 20d683bab..000000000 --- a/translations/hi/00-quick-start/README.md +++ /dev/null @@ -1,386 +0,0 @@ -# Module 00: क्विक स्टार्ट - -## Table of Contents - -- [परिचय](../../../00-quick-start) -- [LangChain4j क्या है?](../../../00-quick-start) -- [LangChain4j निर्भरताएँ](../../../00-quick-start) -- [पूर्वापेक्षाएँ](../../../00-quick-start) -- [सेटअप](../../../00-quick-start) - - [1. अपना GitHub टोकन प्राप्त करें](../../../00-quick-start) - - [2. अपना टोकन सेट करें](../../../00-quick-start) -- [उदाहरण चलाएँ](../../../00-quick-start) - - [1. बेसिक चैट](../../../00-quick-start) - - [2. प्रॉम्प्ट पैटर्न](../../../00-quick-start) - - [3. फंक्शन कॉलिंग](../../../00-quick-start) - - [4. दस्तावेज़ प्रश्नोत्तर (आसान RAG)](../../../00-quick-start) - - [5. ज़िम्मेदार AI](../../../00-quick-start) -- [प्रत्येक उदाहरण क्या दिखाता है](../../../00-quick-start) -- [अगले कदम](../../../00-quick-start) -- [समस्या निवारण](../../../00-quick-start) - -## परिचय - -यह क्विकस्टार्ट आपको LangChain4j के साथ यथाशीघ्र शुरूआत करने के लिए बनाया गया है। यह LangChain4j और GitHub मॉडल के साथ AI एप्लिकेशन बनाने के सबसे बुनियादी पहलुओं को कवर करता है। अगले मॉड्यूल में आप Azure OpenAI और GPT-5.2 पर स्विच करेंगे और प्रत्येक अवधारणा में गहराई से जाएँगे। - -## LangChain4j क्या है? - -LangChain4j एक Java लाइब्रेरी है जो AI-पावर्ड एप्लिकेशन बनाने को सरल बनाती है। HTTP क्लाइंट और JSON पार्सिंग से निपटने के बजाय, आप साफ़-सुथरे Java API के साथ काम करते हैं। - -LangChain में "चेन" का मतलब है कई घटकों को जोड़ना - आप प्रॉम्प्ट को मॉडल, फिर पार्सर से जोड़ सकते हैं, या कई AI कॉल्स को इस तरह जोड सकते हैं कि एक आउटपुट अगले इनपुट में जाए। यह क्विक स्टार्ट बुनियादी बातों पर केंद्रित है इससे पहले कि हम अधिक जटिल चेन पर जाएँ। - -LangChain4j Chaining Concept - -*LangChain4j में घटकों का चेनिंग - शक्तिशाली AI वर्कफ़्लोज़ बनाने के लिए बिल्डिंग ब्लॉक्स जुड़ रहे हैं* - -हम तीन मुख्य घटकों का उपयोग करेंगे: - -**ChatModel** - AI मॉडल इंटरैक्शन का इंटरफ़ेस। `model.chat("prompt")` कॉल करें और प्रतिक्रिया प्राप्त करें। हम `OpenAiOfficialChatModel` का उपयोग करते हैं जो OpenAI-संगत एंडपॉइंट्स जैसे GitHub मॉडल के साथ काम करता है। - -**AiServices** - प्रकार-सुरक्षित AI सेवा इंटरफेस बनाता है। मेथड्स परिभाषित करें, उन्हें `@Tool` से एनोटेट करें, और LangChain4j ऑर्केस्ट्रेशन संभालता है। AI आवश्यकता होने पर आपके Java मेथड्स को स्वचालित रूप से कॉल करता है। - -**MessageWindowChatMemory** - बातचीत का इतिहास बनाए रखता है। इसके बिना, प्रत्येक अनुरोध स्वतंत्र होता है। इसके साथ, AI पहले के संदेश याद रखता है और कई टर्न्स में संदर्भ बनाए रखता है। - -LangChain4j Architecture - -*LangChain4j आर्किटेक्चर - मुख्य घटक एक साथ मिलकर आपके AI एप्लिकेशन को चलाते हैं* - -## LangChain4j निर्भरताएँ - -यह क्विकस्टार्ट तीन Maven निर्भरताओं का उपयोग करता है [`pom.xml`](../../../00-quick-start/pom.xml) में: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` मॉड्यूल `OpenAiOfficialChatModel` क्लास प्रदान करता है जो OpenAI-संगत API से जुड़ता है। GitHub मॉडल्स इसी API फॉर्मेट का उपयोग करते हैं, इसलिए किसी विशेष अडैप्टर की आवश्यकता नहीं - बस बेस URL को `https://models.github.ai/inference` पर सेट करें। - -`langchain4j-easy-rag` मॉड्यूल दस्तावेज़ों को स्वचालित रूप से विभाजित, एम्बेड और पुनः प्राप्त करने की सुविधा देता है ताकि आप बिना मैनुअल कॉन्फ़िगरेशन के RAG एप्लिकेशन बना सकें। - -## पूर्वापेक्षाएँ - -**डेव कंटेनर का उपयोग कर रहे हैं?** Java और Maven पहले से इंस्टॉल हैं। आपको केवल GitHub पर्सनल एक्सेस टोकन चाहिए। - -**लोकल विकास:** -- Java 21+, Maven 3.9+ -- GitHub पर्सनल एक्सेस टोकन (नीचे निर्देश) - -> **नोट:** इस मॉड्यूल में GitHub मॉडल से `gpt-4.1-nano` का उपयोग होता है। कोड में मॉडल नाम को संशोधित न करें - यह GitHub के उपलब्ध मॉडलों के साथ काम करने के लिए कॉन्फ़िगर किया गया है। - -## सेटअप - -### 1. अपना GitHub टोकन प्राप्त करें - -1. जाएँ [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. "Generate new token" पर क्लिक करें -3. एक वर्णनात्मक नाम सेट करें (जैसे "LangChain4j Demo") -4. समय समाप्ति सेट करें (7 दिन अनुशंसित) -5. "Account permissions" में "Models" खोजें और इसे "Read-only" पर सेट करें -6. "Generate token" क्लिक करें -7. टोकन कॉपी करें और सुरक्षित रखें — आप इसे फिर नहीं देख पाएंगे - -### 2. अपना टोकन सेट करें - -**विकल्प 1: VS Code का उपयोग करके (अनुशंसित)** - -अगर आप VS Code उपयोग कर रहे हैं, तो अपनी टोकन प्रोजेक्ट रूट में `.env` फ़ाइल में जोड़ें: - -अगर `.env` फ़ाइल मौजूद नहीं है, तो `.env.example` को `.env` में कॉपी करें या प्रोजेक्ट रूट में नई `.env` फ़ाइल बनाएं। - -**`.env` फ़ाइल का उदाहरण:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env में -GITHUB_TOKEN=your_token_here -``` - -फिर आप आसानी से Explorer में किसी भी डेमो फ़ाइल (जैसे `BasicChatDemo.java`) पर राइट-क्लिक कर **"Run Java"** चुन सकते हैं या रन और डिबग पैनल से लॉन्च कॉन्फ़िगरेशन का उपयोग कर सकते हैं। - -**विकल्प 2: टर्मिनल का उपयोग करके** - -टोकन को पर्यावरण चर के रूप में सेट करें: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## उदाहरण चलाएँ - -**VS Code का उपयोग करते हुए:** Explorer में किसी भी डेमो फ़ाइल पर राइट-क्लिक करके **"Run Java"** चुनें, या रन और डिबग पैनल से लॉन्च कॉन्फ़िगरेशन का उपयोग करें (पहले सुनिश्चित करें कि आपने अपना टोकन `.env` फ़ाइल में जोड़ दिया है)। - -**Maven का उपयोग करते हुए:** वैकल्पिक रूप से, आप कमांड लाइन से चला सकते हैं: - -### 1. बेसिक चैट - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. प्रॉम्प्ट पैटर्न - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -यह ज़ीरो-शॉट, फ्यू-शॉट, चेन-ऑफ-थॉट और रोल-आधारित प्रॉम्प्टिंग दिखाता है। - -### 3. फंक्शन कॉलिंग - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI आपकी Java विधियों को आवश्यकतानुसार स्वचालित कॉल करता है। - -### 4. दस्तावेज़ प्रश्नोत्तर (आसान RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -आसानी से RAG के साथ अपने दस्तावेज़ों के बारे में प्रश्न पूछें जिसमें स्वचालित एम्बेडिंग और पुनः प्राप्ति होती है। - -### 5. ज़िम्मेदार AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -देखें कि AI सुरक्षा फ़िल्टर हानिकारक सामग्री को कैसे ब्लॉक करते हैं। - -## प्रत्येक उदाहरण क्या दिखाता है - -**बेसिक चैट** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -यहाँ से शुरू करें ताकि LangChain4j को सबसे सरल रूप में देखें। आप एक `OpenAiOfficialChatModel` बनाएंगे, `.chat()` के साथ एक प्रॉम्प्ट भेजेंगे, और प्रतिक्रिया प्राप्त करेंगे। यह आधार दिखाता है: कस्टम एंडपॉइंट और API कुंजी के साथ मॉडल को कैसे इनिशियलाइज़ करें। एक बार जब आप इस पैटर्न को समझ लेते हैं, तो बाकी सब कुछ इसी पर बनता है। - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ कोशिश करें:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) खोलें और पूछें: -> - "मैं इस कोड में GitHub Models से Azure OpenAI पर कैसे स्विच करूं?" -> - "OpenAiOfficialChatModel.builder() में मैं कौन से अन्य पैरामीटर कॉन्फ़िगर कर सकता हूँ?" -> - "पूरी प्रतिक्रिया की प्रतीक्षा करने के बजाय स्ट्रीमिंग प्रतिक्रिया कैसे जोड़ूं?" - -**प्रॉम्प्ट इंजीनियरिंग** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -अब जब आप मॉडल से बात करना जानते हैं, चलिए देखते हैं कि आप उससे क्या कहते हैं। यह डेमो उसी मॉडल सेटअप का उपयोग करता है लेकिन पाँच अलग-अलग प्रॉम्प्टिंग पैटर्न दिखाता है। सीधे निर्देशों के लिए ज़ीरो-शॉट प्रॉम्प्ट, उदाहरणों से सीखने वाले फ्यू-शॉट प्रॉम्प्ट, तर्क के चरण दिखाने वाले चेन-ऑफ-थॉट प्रॉम्प्ट, और संदर्भ सेट करने वाले रोल-आधारित प्रॉम्प्ट ट्राई करें। आप देखेंगे कि आपकी फ्रेमिंग के आधार पर एक ही मॉडल कैसे काफी अलग परिणाम देता है। - -यह डेमो प्रॉम्प्ट टेम्प्लेट्स को भी दिखाता है, जो वेरिएबल्स के साथ पुन: प्रयोज्य प्रॉम्प्ट बनाने का एक शक्तिशाली तरीका है। नीचे का उदाहरण LangChain4j `PromptTemplate` का उपयोग कर वेरिएबल्स भरने वाला प्रॉम्प्ट दिखाता है। AI प्रदान किए गए गंतव्य और गतिविधि के आधार पर जवाब देगा। - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ कोशिश करें:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) खोलें और पूछें: -> - "ज़ीरो-शॉट और फ्यू-शॉट प्रॉम्प्टिंग में क्या अंतर है, और मुझे कब कौन सा उपयोग करना चाहिए?" -> - "तापमान पैरामीटर मॉडल की प्रतिक्रियाओं को कैसे प्रभावित करता है?" -> - "प्रोडक्शन में प्रॉम्प्ट इंजेक्शन हमलों को रोकने के लिए कौन सी तकनीकें हैं?" -> - "सामान्य पैटर्न के लिए पुन: प्रयोज्य PromptTemplate ऑब्जेक्ट कैसे बनाएं?" - -**टूल इंटीग्रेशन** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -यहाँ LangChain4j शक्तिशाली हो जाता है। आप `AiServices` का उपयोग करके एक AI सहायक बनाएंगे जो आपकी Java मेथड्स कॉल कर सके। बस मेथड्स को `@Tool("description")` से एनोटेट करें और LangChain4j बाकी संभालता है - AI उपयोगकर्ता के प्रश्नों के आधार पर स्वचालित रूप से प्रत्येक टूल का उपयोग करता है। यह फंक्शन कॉलिंग प्रदर्शित करता है, AI को कार्रवाई करने में सक्षम बनाने की एक प्रमुख तकनीक, केवल प्रश्नों के जवाब देने के बजाय। - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ कोशिश करें:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) खोलें और पूछें: -> - "`@Tool` एनोटेशन कैसे काम करता है और LangChain4j इसके साथ पीछे क्या करता है?" -> - "क्या AI जटिल समस्याओं को हल करने के लिए कई टूल्स को अनुक्रम में कॉल कर सकता है?" -> - "अगर कोई टूल अपवाद फेंकता है तो क्या होता है - मुझे त्रुटियों को कैसे संभालना चाहिए?" -> - "मैं इस कैलकुलेटर उदाहरण की जगह वास्तविक API कैसे जोड़ूँ?" - -**दस्तावेज़ प्रश्नोत्तर (आसान RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -यहाँ आप LangChain4j के "Easy RAG" दृष्टिकोण का उपयोग करते हुए RAG (रिट्रीवल-ऑगमेंटेड जनरेशन) देखेंगे। दस्तावेज़ लोड किए जाते हैं, स्वचालित रूप से विभाजित और एम्बेडेड होते हैं एक मेमोरी स्टोर में, फिर एक कंटेंट रिट्रीवर AI को क्वेरी के समय प्रासंगिक टुकड़े देता है। AI आपके दस्तावेज़ों के आधार पर उत्तर देता है, अपनी सामान्य जानकारी के नहीं। - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ कोशिश करें:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) खोलें और पूछें: -> - "मॉडल के प्रशिक्षण डेटा की तुलना में RAG AI मतिभ्रम कैसे रोकता है?" -> - "यह आसान तरीका और कस्टम RAG पाइपलाइन में क्या अंतर है?" -> - "मैं इसे कई दस्तावेज़ों या बड़े ज्ञान भंडारों के लिए कैसे स्केल करूँ?" - -**ज़िम्मेदार AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -गतिरोध में रक्षा के साथ AI सुरक्षा बनाएं। यह डेमो दो सुरक्षा स्तर दिखाता है जो एक साथ काम करते हैं: - -**भाग 1: LangChain4j इनपुट गार्डरेल्स** - खतरनाक प्रॉम्प्ट्स को LLM तक पहुँचने से पहले ब्लॉक करें। कस्टम गार्डरेल्स बनाएं जो निषिद्ध कीवर्ड या पैटर्न की जांच करते हैं। ये आपके कोड में चलते हैं, इसलिए तेज़ और मुफ़्त होते हैं। - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**भाग 2: प्रदाता सुरक्षा फ़िल्टर** - GitHub मॉडल्स में अंतर्निहित फ़िल्टर हैं जो आपकी गार्डरेल्स से छूट गए मुद्दों को पकड़ते हैं। आप कड़े ब्लॉक्स (HTTP 400 त्रुटियां) गंभीर उल्लंघनों के लिए और सौम्य इनकार जहाँ AI विनम्रता से मना करता है, देखेंगे। - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ कोशिश करें:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) खोलें और पूछें: -> - "InputGuardrail क्या है और मैं अपना खुद का कैसे बनाऊँ?" -> - "कठोर ब्लॉक और सौम्य इनकार में क्या अंतर है?" -> - "गार्डरेल्स और प्रदाता फ़िल्टर दोनों एक साथ क्यों उपयोग करें?" - -## अगले कदम - -**अगला मॉड्यूल:** [01-परेचय - LangChain4j के साथ शुरुआत](../01-introduction/README.md) - ---- - -**नेपालिकेशन:** [← मुख्य पृष्ठ पर वापस](../README.md) | [अगला: मॉड्यूल 01 - परिचय →](../01-introduction/README.md) - ---- - -## समस्या निवारण - -### पहली बार Maven बिल्ड - -**समस्या**: शुरुआत में `mvn clean compile` या `mvn package` में लंबा समय लगता है (10-15 मिनट) - -**कारण**: Maven को पहली बार सभी प्रोजेक्ट निर्भरताएँ (Spring Boot, LangChain4j लाइब्रेरीज़, Azure SDK, आदि) डाउनलोड करनी होती हैं। - -**समाधान**: यह सामान्य व्यवहार है। अगली बार बिल्ड बहुत तेज़ होंगे क्योंकि निर्भरताएँ स्थानीय रूप से कैश हो जाती हैं। डाउनलोड समय आपके नेटवर्क की गति पर निर्भर करता है। - -### PowerShell Maven कमांड सिंटैक्स - -**समस्या**: Maven कमांड विफल होती हैं और त्रुटि देती हैं `Unknown lifecycle phase ".mainClass=..."` -**कारण**: PowerShell `=` को एक वैरिएबल असाइनमेंट ऑपरेटर के रूप में समझता है, जिससे Maven प्रॉपर्टी सिंटैक्स टूट जाता है - -**समाधान**: Maven कमांड से पहले स्टॉप-पार्सिंग ऑपरेटर `--%` का उपयोग करें: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` ऑपरेटर PowerShell को बताता है कि वह शेष सभी तर्कों को बिना किसी व्याख्या के सीधे Maven को भेज दे। - -### Windows PowerShell इमोजी डिस्प्ले - -**समस्या**: AI प्रतिक्रियाएं PowerShell में इमोजी के बजाय गड़बड़ अक्षर (जैसे `????` या `â??`) दिखाती हैं - -**कारण**: PowerShell की डिफ़ॉल्ट एन्कोडिंग UTF-8 इमोजी का समर्थन नहीं करती - -**समाधान**: Java एप्लिकेशन चलाने से पहले यह कमांड चलाएं: -```cmd -chcp 65001 -``` - -यह टर्मिनल में UTF-8 एन्कोडिंग को मजबूर करता है। विकल्प के रूप में, Windows Terminal का उपयोग करें जिसमें बेहतर यूनिकोड समर्थन होता है। - -### API कॉल्स डिबगिंग - -**समस्या**: AI मॉडल से ऑथेंटिकेशन त्रुटियां, रेट लिमिट्स, या अप्रत्याशित प्रतिक्रियाएं - -**समाधान**: उदाहरणों में `.logRequests(true)` और `.logResponses(true)` शामिल हैं ताकि API कॉल्स कंसोल में दिखाई दें। यह ऑथेंटिकेशन त्रुटियों, रेट लिमिट्स, या अप्रत्याशित प्रतिक्रियाओं की जाँच में मदद करता है। प्रोडक्शन में यह फ्लैग हटा दें ताकि लॉग शोर कम हो। - ---- - - -**अस्वीकरण**: -इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयासरत हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्राधिकृत स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सलाह दी जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। - \ No newline at end of file diff --git a/translations/hi/01-introduction/README.md b/translations/hi/01-introduction/README.md index e5383e512..8bad04af8 100644 --- a/translations/hi/01-introduction/README.md +++ b/translations/hi/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j के साथ शुरुआत करना +# मॉड्यूल 01: LangChain4j के साथ शुरुआत करना -## Table of Contents +## सामग्री सूची -- [Video Walkthrough](../../../01-introduction) -- [What You'll Learn](../../../01-introduction) -- [Prerequisites](../../../01-introduction) -- [Understanding the Core Problem](../../../01-introduction) -- [Understanding Tokens](../../../01-introduction) -- [How Memory Works](../../../01-introduction) -- [How This Uses LangChain4j](../../../01-introduction) -- [Deploy Azure OpenAI Infrastructure](../../../01-introduction) -- [Run the Application Locally](../../../01-introduction) -- [Using the Application](../../../01-introduction) - - [Stateless Chat (Left Panel)](../../../01-introduction) - - [Stateful Chat (Right Panel)](../../../01-introduction) -- [Next Steps](../../../01-introduction) +- [वीडियो वाकथ्रू](#वीडियो-वाकथ्रू) +- [आप क्या सीखेंगे](#आप-क्या-सीखेंगे) +- [पूर्वापेक्षाएं](#पूर्वापेक्षाएं) +- [मूल समस्या को समझना](#मूल-समस्या-को-समझना) +- [टोकन को समझना](#टोकन-को-समझना) +- [मेमोरी कैसे काम करती है](#मेमोरी-कैसे-काम-करती-है) +- [यह LangChain4j का उपयोग कैसे करता है](#यह-langchain4j-का-उपयोग-कैसे-करता-है) +- [Azure OpenAI इन्फ्रास्ट्रक्चर डिप्लॉय करें](#azure-openai-इन्फ्रास्ट्रक्चर-डिप्लॉय-करें) +- [ऐप्लिकेशन को लोकली चलाएं](#ऐप्लिकेशन-को-लोकली-चलाएं) +- [ऐप्लिकेशन का उपयोग](#ऐप्लिकेशन-का-उपयोग) + - [स्टेटलेस चैट (बायाँ पैनल)](#स्टेटलेस-चैट-बायाँ-पैनल) + - [स्टेटफुल चैट (दायाँ पैनल)](#स्टेटफुल-चैट-दायाँ-पैनल) +- [अगले कदम](#अगले-कदम) -## Video Walkthrough +## वीडियो वाकथ्रू -इस लाइव सत्र को देखें जो इस मॉड्यूल के साथ शुरुआत करने का तरीका समझाता है: +इस लाइव सेशन को देखें जो इस मॉड्यूल के साथ शुरुआत करने के तरीके को समझाता है: -Getting Started with LangChain4j - Live Session +LangChain4j के साथ शुरुआत - लाइव सेशन -## What You'll Learn +## आप क्या सीखेंगे -क्विक स्टार्ट में, आपने GitHub Models का उपयोग करके प्रॉम्प्ट भेजने, टूल कॉल करने, RAG पाइपलाइन बनाने और गार्डरिल्स टेस्ट करने के बारे में देखा। उन डेमो में संभावित कार्य दिखाई दिए — अब हम Azure OpenAI और GPT-5.2 पर स्विच करते हैं और उत्पादन-शैली के एप्लिकेशन बनाना शुरू करते हैं। यह मॉड्यूल संवादात्मक AI पर केंद्रित है जो संदर्भ याद रखता है और स्टेट बनाए रखता है — वे अवधारणाएँ जो क्विक स्टार्ट डेमो में उपयोग हुईं लेकिन स्पष्ट रूप से समझाई नहीं गईं। +यह LangChain4j और Azure OpenAI के साथ आपकी शुरुआती बिंदु है। हम मूल बातों से शुरू करते हैं और उत्पादन-शैली के ऐप्लिकेशन बनाना शुरू करते हैं। यह मॉड्यूल वार्तालाप एआई पर केंद्रित है जो संदर्भ को याद रखता है और स्टेट को बनाए रखता है — जो प्रत्येक बाद के मॉड्यूल का आधार है। -इस गाइड के दौरान हम Azure OpenAI के GPT-5.2 का उपयोग करेंगे क्योंकि इसकी उन्नत तर्क क्षमताएं विभिन्न पैटर्न के व्यवहार को अधिक स्पष्ट बनाती हैं। जब आप मेमोरी जोड़ते हैं, तो आप अंतर साफ़ देख पाएंगे। इससे यह समझना आसान हो जाता है कि प्रत्येक घटक आपके एप्लिकेशन में क्या लाता है। +इस गाइड में हम Azure OpenAI का GPT-5.2 उपयोग करेंगे क्योंकि इसकी उन्नत तर्क क्षमताएँ विभिन्न पैटर्न के व्यवहार को अधिक स्पष्ट बनाती हैं। जब आप मेमोरी जोड़ेंगे, तो आप स्पष्ट रूप से अंतर देखेंगे। इससे यह समझना आसान हो जाता है कि प्रत्येक घटक आपके ऐप्लिकेशन में क्या लाता है। -आप एक ऐसा एप्लिकेशन बनाएंगे जो दोनों पैटर्न प्रदर्शित करता है: +आप एक ऐसा ऐप़ बनाएंगे जो दोनों पैटर्न प्रदर्शित करता है: -**Stateless Chat** - प्रत्येक अनुरोध स्वतंत्र होता है। मॉडल को पिछली बातों की कोई जानकारी नहीं होती। यह वह पैटर्न है जो आपने क्विक स्टार्ट में उपयोग किया। +**स्टेटलेस चैट** - प्रत्येक अनुरोध स्वतंत्र होता है। मॉडल को पिछले संदेशों की कोई याददाश्त नहीं होती। यह सबसे सरल शुरुआत है। -**Stateful Conversation** - प्रत्येक अनुरोध में बातचीत का इतिहास शामिल होता है। मॉडल कई टर्न्स के बीच संदर्भ बनाए रखता है। यही वह आवश्यकताएँ होती हैं जो उत्पादन एप्लिकेशन के लिए होती हैं। +**स्टेटफुल वार्तालाप** - प्रत्येक अनुरोध में वार्तालाप इतिहास शामिल होता है। मॉडल कई बार बातचीत के बीच संदर्भ बनाए रखता है। यही उत्पादन ऐप्लिकेशन के लिए आवश्यक है। -## Prerequisites +## पूर्वापेक्षाएं -- Azure सदस्यता जिसमें Azure OpenAI एक्सेस हो +- Azure सदस्यता जिसमें Azure OpenAI पहुंच हो - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Note:** प्रदान किए गए devcontainer में Java, Maven, Azure CLI और Azure Developer CLI (azd) पहले से इंस्टॉल हैं। +> **नोट:** Java, Maven, Azure CLI और Azure Developer CLI (azd) पहले से प्रदत्त devcontainer में इंस्टॉल हैं। -> **Note:** यह मॉड्यूल Azure OpenAI पर GPT-5.2 का उपयोग करता है। डिप्लॉयमेंट `azd up` के माध्यम से स्वचालित रूप से कॉन्फ़िगर होता है - कोड में मॉडल नाम को परिवर्तन न करें। +> **नोट:** यह मॉड्यूल Azure OpenAI पर GPT-5.2 का उपयोग करता है। डिप्लॉयमेंट `azd up` के माध्यम से स्वचालित रूप से कॉन्फ़िगर किया जाता है - कोड में मॉडल नाम को संशोधित न करें। -## Understanding the Core Problem +## मूल समस्या को समझना -भाषा मॉडल स्वतंत्र होते हैं। प्रत्येक API कॉल स्वतंत्र होती है। यदि आप कहते हैं "मेरा नाम जॉन है" और फिर पूछते हैं "मेरा नाम क्या है?", तो मॉडल को पता नहीं होगा कि आपने अभी परिचय दिया है। यह हर अनुरोध को मानता है जैसे यह आपकी पहली बातचीत हो। +भाषा मॉडल स्टेटलेस होते हैं। प्रत्येक API कॉल स्वतंत्र होती है। यदि आप "मेरा नाम जॉन है" भेजते हैं और फिर पूछते हैं "मेरा नाम क्या है?", तो मॉडल को इसका कोई ज्ञान नहीं होता कि आपने खुद को अभी पेश किया था। यह हर अनुरोध को ऐसा मानता है मानो यह आपकी पहली बातचीत हो। -यह सरल प्रश्नोत्तर के लिए ठीक है लेकिन वास्तविक एप्लिकेशन के लिए नकारात्मक है। कस्टमर सर्विस बॉट को आपको कही गई बातें याद रखनी होती हैं। पर्सनल असिस्टेंट को संदर्भ की जरूरत होती है। कोई भी बहु-टर्न बातचीत मेमोरी की मांग करती है। +यह साधारण प्रश्न-उत्तर के लिए ठीक है लेकिन वास्तविक ऐप्लिकेशन के लिए बेकार है। ग्राहक सेवा बॉट्स को यह याद रखना पड़ता है कि आपने उनसे क्या कहा था। व्यक्तिगत सहायक को संदर्भ चाहिए। कोई भी बहु-चरण वार्तालाप मेमोरी की मांग करता है। -निम्नलिखित डायग्राम दोनों दृष्टिकोणों के बीच तुलना करता है — बाईं तरफ, एक स्वतंत्र कॉल जो आपका नाम भूल जाता है; दाईं तरफ, ChatMemory का सहारा लेकर एक Stateful कॉल जो नाम याद रखता है। +निम्नलिखित चित्र दो दृष्टिकोणों को तुलना करता है — बाएं तरफ, स्टेटलेस कॉल जो आपका नाम भूल जाता है; दाएँ तरफ, ChatMemory द्वारा समर्थित स्टेटफुल कॉल जो नाम याद रखता है। -Stateless vs Stateful Conversations +स्टेटलेस बनाम स्टेटफुल वार्तालाप -*Stateless (स्वतंत्र कॉल) और Stateful (संदर्भ-संग्रहीत) बातचीत के बीच का अंतर* +*स्टेटलेस (स्वतंत्र कॉल) और स्टेटफुल (संदर्भ-सचेत) वार्तालाप के बीच का अंतर* -## Understanding Tokens +## टोकन को समझना -बातचीत में उतरने से पहले, टोकन को समझना महत्वपूर्ण है - ये मूलभूत इकाइयाँ हैं जो भाषा मॉडल टेक्स्ट को प्रोसेस करती हैं: +वार्तालाप में डूबने से पहले, टोकन को समझना महत्वपूर्ण है - वह मूल यूनिट्स जिनका भाषा मॉडल द्वारा प्रसंस्करण किया जाता है: -Token Explanation +टोकन व्याख्या -*कैसे टेक्स्ट को टोकनों में तोड़ा जाता है - "I love AI!" चार अलग-अलग प्रोसेसिंग यूनिट बन जाते हैं* +*कैसे टेक्स्ट को टोकन में विभाजित किया जाता है - "I love AI!" 4 अलग-अलग प्रोसेसिंग यूनिट्स बन जाता है* -टोकन AI मॉडल्स के लिए टेक्स्ट मापने और प्रोसेस करने का तरीका हैं। शब्द, विराम चिह्न, और यहां तक कि स्पेस भी टोकन हो सकते हैं। आपके मॉडल में यह सीमित होता है कि इसे एक बार में कितने टोकन प्रोसेस करने की अनुमति है (GPT-5.2 के लिए 400,000 कुल टोकन, जिसमें 272,000 तक इनपुट टोकन और 128,000 आउटपुट टोकन शामिल हैं)। टोकन को समझना बातचीत की लंबाई और लागत को नियंत्रित करने में मदद करता है। +टोकन ही AI मॉडल टेक्स्ट को मापने और प्रोसेस करने का तरीका हैं। शब्द, विराम चिन्ह, और यहां तक कि स्थान भी टोकन हो सकते हैं। आपके मॉडल के पास एक सीमा होती है कि वह एक बार में कितने टोकन प्रोसेस कर सकता है (GPT-5.2 के लिए 400,000, जिसमें 272,000 इनपुट टोकन और 128,000 आउटपुट टोकन)। टोकन को समझना वार्तालाप की लंबाई और लागतों को प्रबंधित करने में मदद करता है। -## How Memory Works +## मेमोरी कैसे काम करती है -चैट मेमोरी stateless समस्या को बातचीत के इतिहास को बनाए रखकर हल करता है। मॉडल को भेजने से पहले, फ्रेमवर्क प्रासंगिक पिछली संदेशों को जोड़ देता है। जब आप पूछते हैं "मेरा नाम क्या है?", सिस्टम पूरी बातचीत का इतिहास भेजता है ताकि मॉडल देख सके कि आपने पहले कहा था "मेरा नाम जॉन है।" +चैट मेमोरी स्टेटलेस समस्या को वार्तालाप इतिहास को बनाए रखकर हल करती है। आपके अनुरोध को मॉडल को भेजने से पहले, फ्रेमवर्क प्रासंगिक पिछले संदेशों को जोड़ देता है। जब आप पूछते हैं "मेरा नाम क्या है?", तो सिस्टम वास्तव में पूरी वार्तालाप इतिहास भेजता है, जिससे मॉडल देख सकता है कि आपने पहले कहा था "मेरा नाम जॉन है।" -LangChain4j मेमोरी इम्प्लीमेंटेशन प्रदान करता है जो यह सब स्वचालित रूप से संभालता है। आप चुनते हैं कि कितने संदेश रखे जाएं और फ्रेमवर्क संदर्भ विंडो प्रबंधित करता है। नीचे दिया गया डायग्राम दर्शाता है कि MessageWindowChatMemory हाल की संदेशों की एक स्लाइडिंग विंडो कैसे बनाए रखता है। +LangChain4j मेमोरी कार्यान्वयन प्रदान करता है जो इसे स्वचालित रूप से संभालता है। आप यह चुनते हैं कि कितने संदेशों को रखना है और फ्रेमवर्क संदर्भ विंडो का प्रबंधन करता है। नीचे दिया गया चित्र दिखाता है कि MessageWindowChatMemory हाल के संदेशों की एक स्लाइडिंग विंडो कैसे बनाए रखता है। -Memory Window Concept +मेमोरी विंडो अवधारणा -*MessageWindowChatMemory हाल की संदेशों की स्लाइडिंग विंडो बनाए रखता है, पुराने संदेश स्वतः हटा देता है* +*MessageWindowChatMemory हाल के संदेशों की स्लाइडिंग विंडो बनाए रखता है, पुराने संदेशों को स्वचालित रूप से हटा देता है* -## How This Uses LangChain4j +## यह LangChain4j का उपयोग कैसे करता है -यह मॉड्यूल क्विक स्टार्ट का विस्तार करता है, Spring Boot एकीकृत करता है और बातचीत की मेमोरी जोड़ता है। भाग इस तरह जुड़ते हैं: +यह मॉड्यूल Spring Boot को इंटीग्रेट करता है और वार्तालाप मेमोरी जोड़ता है। यहाँ भाग कैसे जुड़े हैं: -**Dependencies** - दो LangChain4j लाइब्रेरी जोड़ें: +**डिपेंडेंसीज़** - दो LangChain4j लाइब्रेरीज़ जोड़ें: ```xml @@ -94,7 +94,7 @@ LangChain4j मेमोरी इम्प्लीमेंटेशन प् ``` -**Chat Model** - Azure OpenAI को Spring bean के रूप में कॉन्फ़िगर करें ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**चैट मॉडल** - Azure OpenAI को Spring bean के रूप में कॉन्फ़िगर करें ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -बिल्डर `azd up` द्वारा सेट किए गए पर्यावरण चर से क्रेडेंशियल पढ़ता है। Azure OpenAI से जुड़ने के लिए `baseUrl` अपने Azure endpoint पर सेट करें। +बिल्डर क्रेडेंशियल्स को `azd up` के द्वारा सेट किए गए पर्यावरण चर से पढ़ता है। `baseUrl` को आपके Azure endpoint पर सेट करने से OpenAI क्लाइंट Azure OpenAI के साथ काम करता है। -**Conversation Memory** - MessageWindowChatMemory के साथ चैट इतिहास ट्रैक करें ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**वार्तालाप मेमोरी** - MessageWindowChatMemory के साथ चैट इतिहास को ट्रैक करें ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,39 +124,39 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` के साथ मेमोरी बनाएं ताकि आखिरी 10 संदेश रखें। उपयोगकर्ता और AI संदेश टाइप किए गए रैपर के साथ जोड़ें: `UserMessage.from(text)` और `AiMessage.from(text)`। इतिहास `memory.messages()` से प्राप्त करें और मॉडल को भेजें। सेवा प्रति बातचीत ID अलग मेमोरी उदाहरण संग्रहीत करती है, जिससे कई उपयोगकर्ता एक साथ चैट कर सकते हैं। +`withMaxMessages(10)` के साथ मेमोरी बनाएं ताकि आखिरी 10 संदेश रखे जाएं। उपयोगकर्ता और AI संदेशों को टाइपेड रैपर से जोड़ें: `UserMessage.from(text)` और `AiMessage.from(text)`। इतिहास प्राप्त करें `memory.messages()` के साथ और इसे मॉडल को भेजें। सेवा हर वार्तालाप ID के लिए अलग मेमोरी इंस्टेंस संभालती है, जिससे कई उपयोगकर्ता एक साथ चैट कर सकते हैं। -> **🤖 GitHub Copilot के साथ आज़माएं:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) खोलें और पूछें: -> - "जब विंडो पूरी हो जाती है तो MessageWindowChatMemory कैसे निर्णय लेता है कि कौन से संदेश हटाने हैं?" -> - "क्या मैं कस्टम मेमोरी स्टोरेज डेटाबेस के बजाय इन-मेमोरी के रूप में लागू कर सकता हूँ?" -> - "पुराने बातचीत के इतिहास को संक्षेप करने के लिए मैं समरी कैसे जोड़ सकता हूँ?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ आज़माएं:** खोलें [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) और पूछें: +> - "MessageWindowChatMemory कब किन संदेशों को छोड़ने का निर्णय करता है जब विंडो पूरी हो जाती है?" +> - "क्या मैं इन-मेमोरी के बजाय डेटाबेस का उपयोग कर कस्टम मेमोरी स्टोरेज लागू कर सकता हूँ?" +> - "पुराने वार्तालाप इतिहास को संक्षिप्त करने के लिए मैं सारांश जोड़ने का तरीका कैसे करूँ?" -Stateless चैट endpoint मेमोरी पूरी तरह छोड़ देता है - केवल `chatModel.chat(prompt)` जैसा कि क्विक स्टार्ट में था। Stateful endpoint संदेश मेमोरी में जोड़ता है, इतिहास प्राप्त करता है, और उसे हर अनुरोध के साथ संदर्भ में शामिल करता है। मॉडल की कॉन्फ़िगरेशन समान, पैटर्न अलग। +स्टेटलेस चैट एंडपॉइंट पूरी तरह मेमोरी को छोड़ देता है - बस `chatModel.chat(prompt)` जैसे त्वरित प्रारंभ। स्टेटफुल एंडपॉइंट मेमोरी में संदेश जोड़ता है, इतिहास पुनः प्राप्त करता है, और प्रत्येक अनुरोध के साथ संदर्भ शामिल करता है। मॉडल कॉन्फ़िगरेशन वही है, केवल पैटर्न अलग हैं। -## Deploy Azure OpenAI Infrastructure +## Azure OpenAI इन्फ्रास्ट्रक्चर डिप्लॉय करें **Bash:** ```bash cd 01-introduction -azd up # सदस्यता और स्थान चुनें (eastus2 की सिफारिश की गई) +azd up # सदस्यता और स्थान चुनें (eastus2 की सलाह दी जाती है) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # सदस्यता और स्थान चुनें (eastus2 की सिफारिश की गई) +azd up # सदस्यता और स्थान चुनें (eastus2 की सिफारिश की जाती है) ``` -> **Note:** यदि आपको timeout त्रुटि मिले (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), तो बस `azd up` फिर से चलाएं। Azure संसाधन पृष्ठभूमि में अभी भी प्राविज़निंग में हो सकते हैं, और पुनः प्रयास से डिप्लॉयमेंट तब पूरा होगा जब संसाधन टर्मिनल स्थिति तक पहुंचें। +> **नोट:** यदि कोई टाइमआउट त्रुटि आती है (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), तो बस `azd up` फिर से चलाएँ। Azure संसाधन पृष्ठभूमि में अभी भी प्रावधान कर रहे हो सकते हैं, और पुनः प्रयास करने से डिप्लॉयमेंट पूरा हो जाएगा जब संसाधन टर्मिनल स्थिति में पहुंचेंगे। यह करेगा: -1. GPT-5.2 और text-embedding-3-small मॉडल के साथ Azure OpenAI संसाधन तैनात करेगा -2. प्रोजेक्ट रूट पर स्वचालित `.env` फ़ाइल बनाएगा जिसमें क्रेडेंशियल होंगे +1. GPT-5.2 और text-embedding-3-small मॉडलों के साथ Azure OpenAI संसाधन डिप्लॉय करेगा +2. प्रोजेक्ट रूट में `.env` फ़ाइल स्वचालित रूप से उत्पन्न करेगा जिसमें क्रेडेंशियल्स होंगे 3. सभी आवश्यक पर्यावरण चर सेट करेगा -**डिप्लॉयमेंट में समस्या?** विस्तृत समस्या समाधान के लिए [Infrastructure README](infra/README.md) देखें जिसमें सबडोमेन नाम संघर्ष, मैनुअल Azure पोर्टल डिप्लॉयमेंट चरण, और मॉडल कॉन्फ़िगरेशन गाइड शामिल हैं। +**डिप्लॉयमेंट में समस्या आ रही है?** विस्तृत समस्या निवारण के लिए [इन्फ्रास्ट्रक्चर README](infra/README.md) देखें जिसमें सबडोमेन नाम संघर्ष, Azure पोर्टल पर मैनुअल डिप्लॉयमेंट और मॉडल कॉन्फ़िगरेशन मार्गदर्शन शामिल हैं। -**डिप्लॉयमेंट सफल हुआ यह सत्यापित करें:** +**डिप्लॉयमेंट सफल होने का सत्यापन करें:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, आदि दिखाना च Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, आदि दिखाना चाहिए। ``` -> **Note:** `azd up` कमांड `.env` फ़ाइल स्वचालित रूप से बनाता है। यदि बाद में इसे अपडेट करने की आवश्यकता हो, तो आप `.env` फ़ाइल को मैन्युअल रूप से संपादित कर सकते हैं या इसे पुनः उत्पन्न कर सकते हैं: +> **नोट:** `azd up` कमांड स्वचालित रूप से `.env` फ़ाइल उत्पन्न करता है। यदि आपको बाद में इसे अपडेट करना हो, तो आप या तो `.env` फ़ाइल को मैन्युअल रूप से संपादित करें या इसे पुनः उत्पन्न करें: > > **Bash:** > ```bash @@ -182,11 +182,11 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, आदि दिखान > .\.azd-env.ps1 > ``` -## Run the Application Locally +## ऐप्लिकेशन को लोकली चलाएं **डिप्लॉयमेंट सत्यापित करें:** -सुनिश्चित करें कि रूट डायरेक्टरी में `.env` फ़ाइल मौजूद है जिसमें Azure क्रेडेंशियल्स हैं। इसे मॉड्यूल डायरेक्टरी (`01-introduction/`) से चलाएं: +सुनिश्चित करें कि `.env` फ़ाइल रूट डायरेक्ट्री में Azure क्रेडेंशियल्स के साथ मौजूद है। इसे मॉड्यूल डायरेक्ट्री (`01-introduction/`) से चलाएं: **Bash:** ```bash @@ -198,41 +198,41 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दिखाना च Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दिखाना चाहिए ``` -**एप्लिकेशन शुरू करें:** +**ऐप्लिकेशन शुरू करें:** -**विकल्प 1: Spring Boot Dashboard का उपयोग करें (VS Code उपयोगकर्ताओं के लिए अनुशंसित)** +**विकल्प 1: Spring Boot डैशबोर्ड का उपयोग करना (VS Code उपयोगकर्ताओं के लिए अनुशंसित)** -डेव कंटेनर में Spring Boot Dashboard एक्सटेंशन शामिल है, जो सभी Spring Boot एप्लिकेशन को प्रबंधित करने के लिए एक विज़ुअल इंटरफ़ेस प्रदान करता है। इसे VS Code के Activity Bar में बाईं ओर (Spring Boot आइकन देखें) पा सकते हैं। +डेव कंटेनर में Spring Boot डैशबोर्ड एक्सटेंशन शामिल है, जो सभी Spring Boot ऐप्लिकेशन प्रबंधित करने के लिए एक दृश्य इंटरफ़ेस प्रदान करता है। यह VS Code के बाएँ ओर Activity Bar में पाया जा सकता है (Spring Boot आइकन देखें)। -Spring Boot Dashboard से आप कर सकते हैं: -- विषमता में उपलब्ध सभी Spring Boot एप्लिकेशन देखें -- एक क्लिक से एप्लिकेशन शुरू/रोकें -- एप्लिकेशन लॉग वास्तविक समय में देखें -- एप्लिकेशन की स्थिति देखें +Spring Boot डैशबोर्ड से आप: +- कार्यक्षेत्र में सभी उपलब्ध Spring Boot ऐप्लिकेशन देख सकते हैं +- एक क्लिक में ऐप्लिकेशन स्टार्ट/स्टॉप कर सकते हैं +- असली समय में ऐप लॉग देख सकते हैं +- ऐप्लिकेशन स्थिति की निगरानी कर सकते हैं -केवल "introduction" के बगल में प्ले बटन क्लिक करें ताकि यह मॉड्यूल शुरू हो, या सभी मॉड्यूल को एक साथ शुरू करें। +बस "introduction" के बाजू में प्ले बटन क्लिक करें इस मॉड्यूल को शुरू करने के लिए, या सभी मॉड्यूल एक साथ शुरू करें। -Spring Boot Dashboard +Spring Boot डैशबोर्ड -*VS Code में Spring Boot Dashboard — सभी मॉड्यूल को एक जगह से शुरू, बंद और मॉनिटर करें* +*VS Code में Spring Boot डैशबोर्ड — एक ही जगह से सभी मॉड्यूल स्टार्ट, स्टॉप और मॉनिटर करें* -**विकल्प 2: शेल स्क्रिप्ट्स का उपयोग करें** +**विकल्प 2: शेल स्क्रिप्ट्स का उपयोग करना** -सभी वेब एप्लिकेशन (मॉड्यूल 01-04) शुरू करें: +सभी वेब ऐप्लिकेशन (मॉड्यूल 01-04) शुरू करें: **Bash:** ```bash -cd .. # रूट निर्देशिका से +cd .. # रूट डायरेक्टरी से ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # रूट डायरेक्टरी से +cd .. # मूल निर्देशिका से .\start-all.ps1 ``` -या केवल यह मॉड्यूल शुरू करें: +या केवल इस मॉड्यूल को शुरू करें: **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -दोनों स्क्रिप्टें स्वचालित रूप से रूट `.env` फ़ाइल से पर्यावरण चर लोड करेंगी और यदि JARs मौजूद नहीं हैं तो उन्हें बनाएंगी। +दोनों स्क्रिप्ट्स रूट `.env` फ़ाइल से पर्यावरण चर स्वचालित रूप से लोड करेंगी और यदि JARs मौजूद नहीं हैं तो उन्हें बिल्ड करेंगी। -> **Note:** यदि आप शुरू करने से पहले सभी मॉड्यूल मैन्युअली बनाना पसंद करते हैं: +> **नोट:** यदि आप शुरू करने से पहले सभी मॉड्यूल मैन्युअली बिल्ड करना पसंद करते हैं: > > **Bash:** > ```bash @@ -262,7 +262,7 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -अपने ब्राउजर में http://localhost:8080 खोलें। +ब्राउज़र में http://localhost:8080 खोलें। **रोकने के लिए:** @@ -275,48 +275,48 @@ cd .. && ./stop-all.sh # सभी मॉड्यूल **PowerShell:** ```powershell -.\stop.ps1 # केवल यह मॉड्यूल +.\stop.ps1 # यह मॉड्यूल केवल # या -cd ..; .\stop-all.ps1 # सभी मॉड्यूल +cd ..; .\stop-all.ps1 # सभी मॉड्यूल्स ``` -## Using the Application +## ऐप्लिकेशन का उपयोग -यह एप्लिकेशन दो चैट इम्प्लीमेंटेशन वाले वेब इंटरफ़ेस प्रदान करता है जो साथ-साथ हैं। +ऐप्लिकेशन एक वेब इंटरफ़ेस प्रदान करता है जिसमें दो चैट इम्प्लीमेंटेशन साइड-बाय-साइड हैं। -Application Home Screen +ऐप्लिकेशन होम स्क्रीन -*डैशबोर्ड सरल चैट (stateless) और संवादात्मक चैट (stateful) विकल्प दोनों दिखाता है* +*डैशबोर्ड जो Simple Chat (स्टेटलेस) और Conversational Chat (स्टेटफुल) विकल्पों को दिखाता है* -### Stateless Chat (Left Panel) +### स्टेटलेस चैट (बायाँ पैनल) -पहले इसे आज़माएं। पूछें "मेरा नाम जॉन है" और तुरंत उसके बाद पूछें "मेरा नाम क्या है?" मॉडल याद नहीं रखेगा क्योंकि प्रत्येक संदेश स्वतंत्र है। यह भाषा मॉडल एकीकरण के साथ मूल समस्या दर्शाता है - कोई बातचीत का संदर्भ नहीं। +यह पहले आजमाएं। पूछें "मेरा नाम जॉन है" और फिर तुरंत पूछें "मेरा नाम क्या है?" मॉडल याद नहीं रखेगा क्योंकि प्रत्येक संदेश स्वतंत्र है। यह मूल भाषा मॉडल इंटीग्रेशन की मूल समस्या दिखाता है - कोई वार्तालाप संदर्भ नहीं। -Stateless Chat Demo +स्टेटलेस चैट डेमो -*AI आपके पिछले संदेश से आपका नाम याद नहीं रखता* +*एआई आपके पिछले संदेश से आपका नाम याद नहीं रखता* -### Stateful Chat (Right Panel) +### स्टेटफुल चैट (दायाँ पैनल) -अब समान अनुक्रम यहां आज़माएं। पूछें "मेरा नाम जॉन है" और फिर "मेरा नाम क्या है?" इस बार यह याद रखता है। अंतर MessageWindowChatMemory है - यह बातचीत के इतिहास को बनाए रखता है और हर अनुरोध के साथ उस संदर्भ को शामिल करता है। यह उत्पादन संवादात्मक AI का तरीका है। +अब यही क्रम यहाँ आजमाएं। पूछें "मेरा नाम जॉन है" और फिर "मेरा नाम क्या है?" यह याद रखता है। फर्क MessageWindowChatMemory का है - यह वार्तालाप इतिहास बनाए रखता है और इसे प्रत्येक अनुरोध के साथ शामिल करता है। यही कैसे उत्पादन conversational AI काम करता है। -Stateful Chat Demo +स्टेटफुल चैट डेमो -*AI बातचीत में पहले के आपके नाम को याद रखता है* +*एआई बातचीत के दौरान आपके नाम को याद रखता है* -दोनों पैनल एक ही GPT-5.2 मॉडल का उपयोग करते हैं। केवल अंतर मेमोरी है। यह स्पष्ट करता है कि मेमोरी आपके एप्लिकेशन में क्या लाती है और क्यों यह वास्तविक उपयोग मामलों के लिए आवश्यक है। +दोनों पैनल एक ही GPT-5.2 मॉडल का उपयोग करते हैं। केवल फर्क मेमोरी है। यह स्पष्ट करता है कि मेमोरी आपके ऐप्लिकेशन में क्या लाती है और क्यों यह वास्तविक उपयोग के मामलों के लिए आवश्यक है। -## Next Steps +## अगले कदम -**अगला मॉड्यूल:** [02-prompt-engineering - GPT-5.2 के साथ प्रॉम्प्ट इंजीनियरिंग](../02-prompt-engineering/README.md) +**अगला मॉड्यूल:** [02-पrompt-engineering - GPT-5.2 के साथ प्रॉम्प्ट इंजीनियरिंग](../02-prompt-engineering/README.md) --- -**नेविगेशन:** [← पिछला: Module 00 - क्विक स्टार्ट](../00-quick-start/README.md) | [मुख्य पृष्ठ पर वापस](../README.md) | [अगला: Module 02 - प्रॉम्प्ट इंजीनियरिंग →](../02-prompt-engineering/README.md) +**नेविगेशन:** [← मुख्य पर वापस](../README.md) | [अगला: मॉड्यूल 02 - प्रॉम्प्ट इंजीनियरिंग →](../02-prompt-engineering/README.md) --- **अस्वीकरण**: -यह दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके अनुवादित किया गया है। जबकि हम सटीकता के लिए प्रयासरत हैं, कृपया ध्यान रखें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपने मूल भाषा में ही अधिकृत स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए पेशेवर मानव अनुवाद की सलाह दी जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम जिम्मेदार नहीं हैं। +इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। \ No newline at end of file diff --git a/translations/hi/02-prompt-engineering/README.md b/translations/hi/02-prompt-engineering/README.md index dfc7367d0..dac846843 100644 --- a/translations/hi/02-prompt-engineering/README.md +++ b/translations/hi/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ -# मॉड्यूल 02: GPT-5.2 के साथ प्रॉम्प्ट इंजिनीयरिंग - -## सामग्री सूची - -- [वीडियो वॉकथ्रू](../../../02-prompt-engineering) -- [आप क्या सीखेंगे](../../../02-prompt-engineering) -- [पूर्वापेक्षाएँ](../../../02-prompt-engineering) -- [प्रॉम्प्ट इंजिनीयरिंग को समझना](../../../02-prompt-engineering) -- [प्रॉम्प्ट इंजिनीयरिंग के मूल सिद्धांत](../../../02-prompt-engineering) - - [जीरो-शॉट प्रॉम्प्टिंग](../../../02-prompt-engineering) - - [फ्यू-शॉट प्रॉम्प्टिंग](../../../02-prompt-engineering) - - [चेन ऑफ थॉट](../../../02-prompt-engineering) - - [रोल-आधारित प्रॉम्प्टिंग](../../../02-prompt-engineering) - - [प्रॉम्प्ट टेम्पलेट्स](../../../02-prompt-engineering) -- [उन्नत पैटर्न](../../../02-prompt-engineering) -- [एप्लिकेशन चलाएँ](../../../02-prompt-engineering) -- [एप्लिकेशन के स्क्रीनशॉट](../../../02-prompt-engineering) -- [पैटर्न्स का अन्वेषण](../../../02-prompt-engineering) - - [कम बनाम अधिक उत्सुकता](../../../02-prompt-engineering) - - [टास्क निष्पादन (टूल प्रीऐम्बल्स)](../../../02-prompt-engineering) - - [स्वयं-प्रतिबिंबित कोड](../../../02-prompt-engineering) - - [संरचित विश्लेषण](../../../02-prompt-engineering) - - [मल्टी-टर्न चैट](../../../02-prompt-engineering) - - [चरण-दर-चरण तर्क](../../../02-prompt-engineering) - - [सीमित आउटपुट](../../../02-prompt-engineering) -- [आप वास्तव में क्या सीख रहे हैं](../../../02-prompt-engineering) -- [अगले कदम](../../../02-prompt-engineering) +# मॉड्यूल 02: GPT-5.2 के साथ प्रॉम्प्ट इंजीनियरिंग + +## विषय सूची + +- [वीडियो वॉकथ्रू](#वीडियो-वॉकथ्रू) +- [आप क्या सीखेंगे](#आप-क्या-सीखेंगे) +- [पूर्व आवश्यकताएँ](#पूर्व-आवश्यकताएँ) +- [प्रॉम्प्ट इंजीनियरिंग को समझना](#प्रॉम्प्ट-इंजीनियरिंग-को-समझना) +- [प्रॉम्प्ट इंजीनियरिंग की मूलभूत बातें](#प्रॉम्प्ट-इंजीनियरिंग-की-मूलभूत-बातें) + - [ज़ीरो-शॉट प्रॉम्प्टिंग](#ज़ीरो-शॉट-प्रॉम्प्टिंग) + - [फ्यू-शॉट प्रॉम्प्टिंग](#फ्यू-शॉट-प्रॉम्प्टिंग) + - [चेन ऑफ़ थॉट](#चेन-ऑफ़-थॉट) + - [रोल-आधारित प्रॉम्प्टिंग](#रोल-आधारित-प्रॉम्प्टिंग) + - [प्रॉम्प्ट टेम्प्लेट्स](#प्रॉम्प्ट-टेम्प्लेट्स) +- [उन्नत पैटर्न](#उन्नत-पैटर्न) +- [एप्लिकेशन चलाएँ](#एप्लिकेशन-चलाएँ) +- [एप्लिकेशन स्क्रीनशॉट](#एप्लिकेशन-स्क्रीनशॉट) +- [पैटर्न्स का अन्वेषण](#पैटर्न-का-अन्वेषण) + - [कम बनाम अधिक उत्साह](#कम-बनाम-उच्च-उत्साह) + - [कार्य निष्पादन (टूल प्रीएंबल्स)](#कार्य-निष्पादन-टूल-प्रीएम्बल्स) + - [आत्म-परावर्तित कोड](#स्वयं-प्रतिबिंबित-कोड) + - [संरचित विश्लेषण](#संरचित-विश्लेषण) + - [मल्टी-टर्न चैट](#बहु-चरण-वार्तालाप) + - [कदम-दर-कदम तर्क](#चरण-दर-चरण-तर्क) + - [संयमित आउटपुट](#सीमित-आउटपुट) +- [आप वास्तव में क्या सीख रहे हैं](#आप-वास्तव-में-क्या-सीख-रहे-हैं) +- [अगले कदम](#अगले-कदम) ## वीडियो वॉकथ्रू -इस लाइव सेशन को देखें जो इस मॉड्यूल के साथ शुरू करने का तरीका समझाता है: +इस लाइव सत्र को देखें जो बताता है कि इस मॉड्यूल के साथ कैसे शुरू करें: Prompt Engineering with LangChain4j - Live Session ## आप क्या सीखेंगे -निम्नलिखित चित्र इस मॉड्यूल में आप जिन मुख्य विषयों और कौशलों को विकसित करेंगे उनका अवलोकन प्रदान करता है — प्रॉम्प्ट परिष्करण तकनीकों से लेकर उस चरण-दर-चरण वर्कफ़्लो तक जिसे आप पालन करेंगे। +निम्नलिखित चित्र आपके लिए इस मॉड्यूल में विकसित होने वाले मुख्य विषयों और कौशलों का अवलोकन प्रस्तुत करता है — प्रॉम्प्ट परिशोधन तकनीकों से लेकर आप जिन चरण-दर-चरण वर्कफ़्लो का पालन करेंगे। What You'll Learn -पिछले मॉड्यूल में, आपने GitHub Models के साथ LangChain4j के बुनियादी इंटरैक्शंस और देखा कि कैसे मेमोरी Azure OpenAI के साथ संवादात्मक AI को सक्षम बनाती है। अब हम ध्यान केंद्रित करेंगे कि आप प्रश्न कैसे पूछते हैं — यानि प्रॉम्प्ट्स स्वयं — Azure OpenAI के GPT-5.2 का उपयोग करते हुए। जिस तरह से आप अपने प्रॉम्प्ट्स को संरचित करते हैं, वह आपके प्राप्त उत्तरों की गुणवत्ता को नाटकीय रूप से प्रभावित करता है। हम मूलभूत प्रॉम्प्टिंग तकनीकों की समीक्षा से शुरू करेंगे, फिर आठ उन्नत पैटर्न की ओर बढ़ेंगे जो GPT-5.2 की क्षमताओं का पूरा लाभ उठाते हैं। +पिछले मॉड्यूल में, आपने देखा कि कैसे मेमोरी Azure OpenAI के साथ बातचीत योग्य AI को सक्षम बनाती है। अब हम उस पर ध्यान केंद्रित करेंगे कि आप प्रश्न कैसे पूछते हैं — स्वयं प्रॉम्प्ट्स — Azure OpenAI के GPT-5.2 का उपयोग करते हुए। जिस तरह से आप अपने प्रॉम्प्ट संरचित करते हैं वह प्रतिक्रिया की गुणवत्ता को नाटकीय रूप से प्रभावित करता है। हम मूलभूत प्रॉम्प्टिंग तकनीकों की समीक्षा से शुरू करते हैं, फिर आठ उन्नत पैटर्न में जाते हैं जो GPT-5.2 की क्षमताओं का पूर्ण लाभ उठाते हैं। -हम GPT-5.2 का उपयोग करेंगे क्योंकि यह तर्क नियंत्रण पेश करता है - आप मॉडल को बता सकते हैं कि जवाब देने से पहले कितना सोचना है। यह विभिन्न प्रॉम्प्टिंग रणनीतियों को अधिक स्पष्ट बनाता है और आपको समझने में मदद करता है कि किस स्थिति में कौन-सी विधि का उपयोग करना है। साथ ही, Azure की GPT-5.2 के लिए कम रेट लिमिट्स GitHub Models के मुकाबले हमें लाभ पहुंचाएंगी। +हम GPT-5.2 का उपयोग करेंगे क्योंकि यह तर्क नियंत्रण (reasoning control) प्रस्तुत करता है - आप मॉडल को बता सकते हैं कि उत्तर देने से पहले कितना सोच-विचार करना है। यह विभिन्न प्रॉम्प्टिंग रणनीतियों को और स्पष्ट बनाता है और आपको समझने में मदद करता है कि कब किस दृष्टिकोण का उपयोग करना है। -## पूर्वापेक्षाएँ +## पूर्व आवश्यकताएँ -- मॉड्यूल 01 पूरा किया हो (Azure OpenAI संसाधन तैनात किए गए हों) -- `.env` फाइल रूट डायरेक्टरी में हो जिसमें Azure क्रेडेंशियल्स हों (`azd up` द्वारा मॉड्यूल 01 में बनाई गई) +- मॉड्यूल 01 पूरा किया हुआ (Azure OpenAI संसाधन तैनात) +- रूट डायरेक्ट्री में `.env` फ़ाइल जिसमें Azure प्रमाण-पत्र हैं (मॉड्यूल 01 में `azd up` द्वारा बनाई गई) -> **नोट:** यदि आपने मॉड्यूल 01 पूरा नहीं किया है, तो पहले वहाँ के तैनाती निर्देशों का पालन करें। +> **नोट:** यदि आपने मॉड्यूल 01 पूरा नहीं किया है, तो पहले वहां दिए तैनाती निर्देशों का पालन करें। -## प्रॉम्प्ट इंजिनीयरिंग को समझना +## प्रॉम्प्ट इंजीनियरिंग को समझना -मूल रूप से, प्रॉम्प्ट इंजिनीयरिंग अस्पष्ट निर्देशों और सटीक निर्देशों के बीच का अंतर है, जैसा कि नीचे तुलना में दिखाया गया है। +मूल रूप से, प्रॉम्प्ट इंजीनियरिंग अस्पष्ट निर्देशों और सटीक निर्देशों के बीच का अंतर है, जैसा कि नीचे के तुलना में दिखाया गया है। What is Prompt Engineering? -प्रॉम्प्ट इंजिनीयरिंग वह प्रक्रिया है जिसमें ऐसा इनपुट टेक्स्ट डिजाइन किया जाता है जो आपको लगातार आवश्यक परिणाम देता है। यह केवल प्रश्न पूछने के बारे में नहीं है — बल्कि यह अनुरोधों को इस प्रकार संरचित करने के बारे में है ताकि मॉडल बिल्कुल समझ सके कि आप क्या चाहते हैं और कैसे प्रदान करना है। +प्रॉम्प्ट इंजीनियरिंग उस इनपुट टेक्स्ट को डिज़ाइन करने के बारे में है जो लगातार आपको आवश्यक परिणाम देता है। यह केवल प्रश्न पूछने के बारे में नहीं है - बल्कि ऐसे अनुरोध बनाने के बारे में है जिससे मॉडल ठीक वही समझे जो आप चाहते हैं और कैसे देना है। -इसे एक सहकर्मी को निर्देश देने के रूप में सोचें। "बग ठीक करें" अस्पष्ट है। "UserService.java की लाइन 45 में नल चेक जोड़कर नल पॉइंटर एक्सेप्शन ठीक करें" विशिष्ट है। भाषा मॉडल भी इसी तरह काम करते हैं — विशिष्टता और संरचना महत्वपूर्ण होती है। +इसे एक सहकर्मी को निर्देश देने के रूप में सोचें। "बग को ठीक करें" अस्पष्ट है। "UserService.java की लाइन 45 में null प्वाइंटर एक्सेप्शन को null चेक जोड़कर ठीक करें" विशिष्ट है। भाषा मॉडल भी इसी तरह काम करते हैं - विशिष्टता और संरचना महत्वपूर्ण है। -नीचे का चित्र दिखाता है कि LangChain4j इस परिदृश्य में कैसे फिट बैठता है — आपके प्रॉम्प्ट पैटर्न को SystemMessage और UserMessage बिल्डिंग ब्लॉक्स के माध्यम से मॉडल से जोड़ता है। +नीचे का चित्र दिखाता है कि LangChain4j इस तस्वीर में कैसे फिट बैठता है — SystemMessage और UserMessage बिल्डिंग ब्लॉक्स के माध्यम से आपके प्रॉम्प्ट पैटर्न को मॉडल से जोड़ता है। How LangChain4j Fits -LangChain4j आधारभूत संरचना प्रदान करता है — मॉडल कनेक्शंस, मेमोरी, और मैसेज प्रकार — जबकि प्रॉम्प्ट पैटर्न वे सावधानीपूर्वक संरचित टेक्स्ट हैं जिन्हें आप उस आधारभूत संरचना के माध्यम से भेजते हैं। मुख्य बिल्डिंग ब्लॉक हैं `SystemMessage` (जो AI के व्यवहार और भूमिका को सेट करता है) और `UserMessage` (जो आपका वास्तविक अनुरोध लेकर आता है)। +LangChain4j वह आधारभूत संरचना प्रदान करता है — मॉडल कनेक्शन, मेमोरी, और संदेश प्रकार — जबकि प्रॉम्प्ट पैटर्न महज सावधानीपूर्वक संरचित टेक्स्ट हैं जिन्हें आप उस आधारभूत संरचना से भेजते हैं। मुख्य निर्माण खंड हैं `SystemMessage` (जो AI के व्यवहार और भूमिका को सेट करता है) और `UserMessage` (जो आपका वास्तविक अनुरोध ले जाता है)। -## प्रॉम्प्ट इंजिनीयरिंग के मूल सिद्धांत +## प्रॉम्प्ट इंजीनियरिंग की मूलभूत बातें -नीचे दिखाए गए पांच मुख्य तकनीकें प्रभावी प्रॉम्प्ट इंजिनीयरिंग की नींव हैं। प्रत्येक एक अलग पहलू को संबोधित करता है कि आप भाषा मॉडल के साथ कैसे संवाद करते हैं। +नीचे दिखाए गए पाँच मुख्य तकनीकें प्रभावी प्रॉम्प्ट इंजीनियरिंग की नींव बनाती हैं। प्रत्येक तकनीक भाषा मॉडल के साथ संचार के एक अलग पहलू को संबोधित करती है। Five Prompt Engineering Patterns Overview -इस मॉड्यूल में उन्नत पैटर्न्स में जाने से पहले, आइए पांच मौलिक प्रॉम्प्टिंग तकनीकों की समीक्षा करें। ये वे बिल्डिंग ब्लॉक्स हैं जिन्हें हर प्रॉम्प्ट इंजीनियर को जानना चाहिए। यदि आपने पहले ही [क्विक स्टार्ट मॉड्यूल](../00-quick-start/README.md#2-prompt-patterns) पूरा किया है, तो आपने इन्हें क्रियान्वित होते देखा होगा — यहाँ इनके पीछे का सैद्धांतिक ढांचा है। +इस मॉड्यूल में उन्नत पैटर्न में जाने से पहले, चलिए पाँच मौलिक प्रॉम्प्टिंग तकनीकों की समीक्षा करते हैं। ये वे बिल्डिंग ब्लॉक्स हैं जिन्हें हर प्रॉम्प्ट इंजीनियर को जानना चाहिए। -### जीरो-शॉट प्रॉम्प्टिंग +### ज़ीरो-शॉट प्रॉम्प्टिंग -सबसे सरल तरीका: मॉडल को कोई उदाहरण दिए बिना सीधे निर्देश दें। मॉडल पूरी तरह से अपने प्रशिक्षण पर निर्भर करता है ताकि वह कार्य समझे और निष्पादित करे। यह सरल अनुरोधों के लिए अच्छा काम करता है जहाँ अपेक्षित व्यवहार स्पष्ट होता है। +सबसे सरल तरीका: मॉडल को बिना किसी उदाहरण के सीधे निर्देश देना। मॉडल पूरी तरह से अपने प्रशिक्षण पर निर्भर करता है ताकि कार्य को समझे और क्रियान्वित करे। यह उन सरल अनुरोधों के लिए अच्छा काम करता है जहाँ अपेक्षित व्यवहार स्पष्ट होता है। Zero-Shot Prompting -*उदाहरण बिना सीधे निर्देश — मॉडल केवल निर्देश से कार्य का अनुमान लगाता है* +*उदाहरणों के बिना सीधे निर्देश — मॉडल केवल निर्देश से कार्य का अनुमान लगाता है* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // प्रतिक्रिया: "सकारात्मक" ``` -**कब उपयोग करें:** सरल वर्गीकरण, सीधे प्रश्न, अनुवाद, या कोई भी कार्य जिसे मॉडल बिना अतिरिक्त मार्गदर्शन के संभाल सकता है। +**कब उपयोग करें:** सरल वर्गीकरण, प्रत्यक्ष प्रश्न, अनुवाद, या कोई भी कार्य जिसे मॉडल बिना अतिरिक्त मार्गदर्शन के संभाल सकता है। ### फ्यू-शॉट प्रॉम्प्टिंग -उदाहरण प्रदान करें जो उस पैटर्न को प्रदर्शित करते हैं जिसे आप मॉडल से लागू करना चाहते हैं। मॉडल आपके उदाहरणों से अपेक्षित इनपुट-आउटपुट प्रारूप सीखता है और इसे नए इनपुट्स पर लागू करता है। इसका उपयोग उन कार्यों के लिए करें जहाँ वांछित प्रारूप या व्यवहार स्पष्ट नहीं है और निरंतरता महत्वपूर्ण है। +ऐसे उदाहरण प्रदान करें जो उस पैटर्न को प्रदर्शित करते हैं जिसे आप मॉडल से पालन करवाना चाहते हैं। मॉडल आपके उदाहरणों से अपेक्षित इनपुट-आउटपुट स्वरूप सीखता है और इसे नए इनपुट पर लागू करता है। इससे उन कार्यों के लिए लगातार जवाब मिलता है जहाँ अपेक्षित प्रारूप या व्यवहार स्पष्ट नहीं होता। Few-Shot Prompting -*उदाहरणों से सीखना — मॉडल पैटर्न पहचानता है और नए इनपुट्स पर लागू करता है* +*उदाहरणों से सीखना — मॉडल पैटर्न को पहचानता है और नए इनपुट पर लागू करता है* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**कब उपयोग करें:** कस्टम वर्गीकरण, सुसंगत प्रारूपण, डोमेन-विशिष्ट कार्य, या जब जीरो-शॉट परिणाम असंगत हों। +**कब उपयोग करें:** कस्टम वर्गीकरण, स्थिर स्वरूपण, डोमेन-विशिष्ट कार्य, या जब ज़ीरो-शॉट परिणाम असंगत हों। -### चेन ऑफ थॉट +### चेन ऑफ़ थॉट -मॉडल से कहें कि वह अपना तर्क चरण-दर-चरण दिखाए। सीधे उत्तर पर कूदने के बजाय, मॉडल समस्या को टुकड़ों में तोड़ता है और प्रत्येक भाग पर स्पष्ट रूप से काम करता है। इससे गणित, तर्क और बहु-चरण तर्क कार्यों में सटीकता बढ़ती है। +मॉडल को चरण-दर-चरण तर्क दिखाने के लिए कहें। सीधे उत्तर पर न जाकर, मॉडल समस्या को तोड़ता है और प्रत्येक भाग को स्पष्ट रूप से समझाता है। यह गणित, तर्क और बहु-चरण तर्क देने वाले कार्यों में सटीकता बढ़ाता है। Chain of Thought Prompting -*चरण-दर-चरण तर्क — जटिल समस्याओं को स्पष्ट तार्किक चरणों में तोड़ना* +*चरण-दर-चरण तर्क — जटिल समस्याओं को स्पष्ट तार्किक चरणों में विभाजित करना* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // मॉडल दिखाता है: 15 - 8 = 7, फिर 7 + 12 = 19 सेब ``` -**कब उपयोग करें:** गणित की समस्याएँ, तर्क पहेलियाँ, डिबगिंग, या कोई भी कार्य जहाँ तर्क प्रक्रिया दिखाने से सटीकता और विश्वास बढ़ता है। +**कब उपयोग करें:** गणित की समस्याएँ, तर्क पहेलियाँ, बग-फ़िक्सिंग, या कोई भी कार्य जहाँ तर्क प्रक्रिया दिखाने से सटीकता और भरोसा बढ़ता हो। ### रोल-आधारित प्रॉम्प्टिंग -एआई के लिए प्रश्न पूछने से पहले कोई व्यक्ति या भूमिका निर्धारित करें। यह संदर्भ प्रदान करता है जो उत्तर के टोन, गहराई और फोकस को आकार देता है। "सॉफ्टवेयर आर्किटेक्ट" का सुझाव "जूनियर डेवलपर" या "सुरक्षा ऑडिटर" से अलग होगा। +प्रश्न पूछने से पहले AI के लिए किसी भूमिका या व्यक्तित्व को सेट करें। यह ऐसा संदर्भ प्रदान करता है जो प्रतिक्रिया की टोन, गहराई और फोकस को आकार देता है। "सॉफ्टवेयर आर्किटेक्ट" अलग सलाह देता है, "जूनियर डेवलपर" अलग, और "सुरक्षा ऑडिटर" और अलग। Role-Based Prompting -*संदर्भ और व्यक्ति सेट करना — एक ही प्रश्न को सौंपे गए भूमिका के अनुसार अलग जवाब मिलता है* +*संदर्भ और भूमिका सेट करना — वही प्रश्न अलग- अलग भूमिका के आधार पर अलग जवाब पाता है* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**कब उपयोग करें:** कोड समीक्षा, ट्यूटरिंग, डोमेन-विशिष्ट विश्लेषण, या जब अलग विशेषज्ञता स्तर या दृष्टिकोण के लिए उत्तर चाहिए। +**कब उपयोग करें:** कोड समीक्षा, ट्यूटरिंग, डोमेन-विशिष्ट विश्लेषण, या जब आपको विशेष विशेषज्ञता स्तर या दृष्टिकोण के अनुसार प्रतिक्रिया चाहिए। -### प्रॉम्प्ट टेम्पलेट्स +### प्रॉम्प्ट टेम्प्लेट्स -चर प्लेसहोल्डर्स के साथ पुन: उपयोग योग्य प्रॉम्प्ट बनाएं। हर बार नया प्रॉम्प्ट लिखने के बजाय, एक बार टेम्पलेट परिभाषित करें और अलग-अलग मान भरें। LangChain4j का `PromptTemplate` क्लास इसे `{{variable}}` सिंटैक्स के साथ आसान बनाता है। +वेरिएबल प्लेसहोल्डर के साथ पुन: उपयोग योग्य प्रॉम्प्ट बनाएं। हर बार नया प्रॉम्प्ट लिखने के बजाय, एक टेम्प्लेट एक बार परिभाषित करें और अलग-अलग मान भरें। LangChain4j का `PromptTemplate` क्लास यह `{{variable}}` सिंटैक्स के साथ आसान बनाता है। Prompt Templates -*चर प्लेसहोल्डर्स के साथ पुन: उपयोग योग्य प्रॉम्प्ट — एक टेम्पलेट, कई उपयोग* +*वेरिएबल प्लेसहोल्डर के साथ पुन: उपयोग योग्य प्रॉम्प्ट — एक टेम्प्लेट, कई उपयोग* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**कब उपयोग करें:** अलग इनपुट के साथ पुनरावृत्ति प्रश्न, बैच प्रोसेसिंग, पुन: उपयोग योग्य AI वर्कफ़्लोज़ बनाना, या कोई भी परिदृश्य जहाँ प्रॉम्प्ट संरचना समान रहती है पर डेटा बदलता है। +**कब उपयोग करें:** अलग-अलग इनपुट के साथ बार-बार क्वेरी करना, बैच प्रोसेसिंग, पुन: उपयोग योग्य AI वर्कफ़्लो बनाना, या कोई भी परिदृश्य जहाँ प्रॉम्प्ट संरचना समान रहती है पर डेटा बदलता है। --- -ये पाँच मूल बातें आपको अधिकांश प्रॉम्प्टिंग कार्यों के लिए एक मजबूत उपकरण प्रदान करती हैं। इस मॉड्यूल का बाकी हिस्सा इन पर आधारित आठ उन्नत पैटर्न प्रदान करता है जो GPT-5.2 के तर्क नियंत्रण, स्वयं-मূল्यांकन, और संरचित आउटपुट क्षमताओं का उपयोग करते हैं। +ये पाँच मूलभूत चीजें आपको अधिकतर प्रॉम्प्टिंग कार्यों के लिए एक ठोस टूलकिट देती हैं। इस मॉड्यूल का बाकी हिस्सा इन पर आधारित है उन **आठ उन्नत पैटर्न्स** के साथ जो GPT-5.2 के reasoning control, self-evaluation, और structured output क्षमताओं का लाभ उठाते हैं। ## उन्नत पैटर्न -मूलभूत बातें हो जाने के बाद, आइए उन आठ उन्नत पैटर्न्स की ओर बढ़ें जो इस मॉड्यूल को अनूठा बनाते हैं। सभी समस्याओं के लिए एक ही तरीका जरूरी नहीं होता। कुछ प्रश्न त्वरित उत्तर चाहते हैं, कुछ को गहरे सोच-विचार की जरूरत होती है। कुछ को दिखाई देने वाला तर्क चाहिए, और कुछ को केवल परिणाम चाहिए। नीचे प्रत्येक पैटर्न किसी विशिष्ट परिदृश्य के लिए अनुकूलित है — और GPT-5.2 का तर्क नियंत्रण इस भेद को और भी स्पष्ट बनाता है। +मूल बातें कवर हो जाने के बाद, आइए उस आठ उन्नत पैटर्न पर जाएं जो इस मॉड्यूल को विशिष्ट बनाते हैं। सभी समस्याओं के लिए एक ही तरीका जरूरी नहीं। कुछ प्रश्नों को तेज़ जवाब चाहिए, तो कुछ को गहरे विचार की जरूरत। कुछ में दिखने वाला तर्क चाहिए, तो कुछ में केवल परिणाम चाहिए। नीचे प्रत्येक पैटर्न अलग परिदृश्य के लिए अनुकूलित है—और GPT-5.2 का reasoning control इस अंतर को और अधिक स्पष्ट बनाता है। Eight Prompting Patterns -*आठ प्रॉम्प्ट इंजिनीयरिंग पैटर्न्स और उनके उपयोग मामलों का अवलोकन* +*आठ प्रॉम्प्ट इंजीनियरिंग पैटर्न्स और उनके उपयोग मामलों का अवलोकन* -GPT-5.2 इन पैटर्न्स में एक और आयाम जोड़ता है: *तर्क नियंत्रण*। नीचे स्लाइडर दिखाता है कि आप मॉडल के सोचने के प्रयास को कैसे समायोजित कर सकते हैं — त्वरित, सीधे उत्तरों से लेकर गहरी, व्यापक विश्लेषण तक। +GPT-5.2 इन पैटर्नों में एक और आयाम जोड़ता है: *tर्क नियंत्रण (reasoning control)*। नीचे स्लाइडर दिखाता है कि आप मॉडल के सोचने के प्रयास को कैसे समायोजित कर सकते हैं — तेज़, सीधे जवाब से गहरी, विस्तृत विश्लेषण तक। Reasoning Control with GPT-5.2 -*GPT-5.2 का तर्क नियंत्रण आपको निर्दिष्ट करने देता है कि मॉडल कितना विचार करे — तेज़ सीधे उत्तर से लेकर गहरे अन्वेषण तक* +*GPT-5.2 का reasoning control आपको यह बताने देता है कि मॉडल को कितना सोचना चाहिए — तेज सीधे जवाब से लेकर गहरे अन्वेषण तक* -**कम उत्सुकता (त्वरित और केंद्रित)** - सरल प्रश्नों के लिए जहाँ आप तेज़, सीधे उत्तर चाहते हैं। मॉडल न्यूनतम तर्क करता है - अधिकतम 2 चरण। गणना, देखups, या सीधे प्रश्नों के लिए इसका उपयोग करें। +**कम उत्साह (तेज़ और केंद्रित)** - सरल प्रश्नों के लिए जहाँ आपको तेज, सीधे जवाब चाहिए। मॉडल न्यूनतम तर्क करता है - अधिकतम 2 कदम। इसका उपयोग गणना, तालाश, या सीधे प्रश्नों के लिए करें। ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **GitHub Copilot के साथ एक्सप्लोर करें:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) खोलें और पूछें: -> - "कम उत्सुकता और अधिक उत्सुकता प्रॉम्प्टिंग पैटर्न में क्या अंतर है?" -> - "प्रॉम्प्ट्स में XML टैग AI के जवाब को संरचित करने में कैसे मदद करते हैं?" -> - "मुझे स्वयं-प्रतिबिंबित पैटर्न्स कब और सीधे निर्देश कब उपयोग करने चाहिए?" +> 💡 **GitHub Copilot के साथ खोजें:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) खोलें और पूछें: +> - "कम उत्साह और अधिक उत्साह प्रॉम्प्टिंग पैटर्न में क्या अंतर है?" +> - "प्रॉम्प्ट्स में XML टैग्स AI की प्रतिक्रिया की संरचना कैसे मदद करते हैं?" +> - "जब मुझे आत्म-परावर्तन पैटर्न और सीधे निर्देश का उपयोग करना चाहिए?" -**अधिक उत्सुकता (गहरा और व्यापक)** - जटिल समस्याओं के लिए जहाँ आप व्यापक विश्लेषण चाहते हैं। मॉडल पूरी तरह से खोज करता है और विस्तृत तर्क दिखाता है। सिस्टम डिज़ाइन, आर्किटेक्चर निर्णय, या जटिल शोध के लिए इसका उपयोग करें। +**अधिक उत्साह (गहरा और व्यापक)** - जटिल समस्याओं के लिए जहाँ आप समग्र विश्लेषण चाहते हैं। मॉडल गहराई से खोज करता है और विस्तृत तर्क दिखाता है। इसका उपयोग सिस्टम डिज़ाइन, आर्किटेक्चर निर्णय, या जटिल शोध के लिए करें। ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**टास्क निष्पादन (चरण-दर-चरण प्रगति)** - बहु-चरण वर्कफ़्लो के लिए। मॉडल एक प्रारंभिक योजना प्रदान करता है, हर चरण का वर्णन करता है, फिर सारांश देता है। माइग्रेशन, कार्यान्वयन, या कोई भी बहु-चरण प्रक्रिया के लिए इसका उपयोग करें। +**कार्य निष्पादन (चरण-दर-चरण प्रगति)** - बहु-चरण वर्कफ़्लो के लिए। मॉडल upfront योजना प्रदान करता है, हर कदम चलता हुआ बताता है, फिर सारांश देता है। इसका उपयोग माइग्रेशन, कार्यान्वयन, या कोई भी बहु-चरण प्रक्रिया के लिए करें। ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -चेन-ऑफ-थॉट प्रॉम्प्टिंग स्पष्ट रूप से मॉडल से तर्क प्रक्रिया दिखाने को कहता है, जटिल कार्यों की सटीकता बढ़ाता है। चरण-दर-चरण टूटना मानव और AI दोनों को तार्किक समझ देता है। +चेन-ऑफ़-थॉट प्रॉम्प्टिंग स्पष्ट रूप से मॉडल से उसकी तर्क प्रक्रिया दिखाने के लिए कहता है, जो जटिल कार्यों में सटीकता बढ़ाता है। चरण-दर-चरण टूटना मानवों और AI दोनों के लिए तर्क को समझने में मदद करता है। -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ ट्राई करें:** इस पैटर्न के बारे में पूछें: -> - "लंबे समय तक चलने वाले ऑपरेशन्स के लिए टास्क निष्पादन पैटर्न को कैसे अनुकूलित करें?" -> - "प्रोडक्शन एप्लिकेशन में टूल प्रीऐम्बल्स को संरचित करने के श्रेष्ठ अभ्यास क्या हैं?" -> - "UI में मध्यवर्ती प्रगति अपडेट कैसे कैप्चर और प्रदर्शित करें?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ प्रयास करें:** इस पैटर्न के बारे में पूछें: +> - "मैं लंबी चलने वाली प्रक्रियाओं के लिए कार्य निष्पादन पैटर्न को कैसे अनुकूलित करूँ?" +> - "उत्पादक एप्लिकेशन में टूल प्रीएंबल्स की संरचना के लिए सर्वोत्तम अभ्यास क्या हैं?" +> - "UI में मध्यवर्ती प्रगति अपडेट कैसे कैप्चर और प्रदर्शित कर सकता हूँ?" -नीचे की आकृति इस योजना → निष्पादन → सारांश वर्कफ़्लो को दर्शाती है। +नीचे का चित्र इस योजना → निष्पादन → सारांश वर्कफ़्लो को दर्शाता है। Task Execution Pattern *बहु-चरण कार्यों के लिए योजना → निष्पादन → सारांश वर्कफ़्लो* -**स्वयं-प्रतिबिंबित कोड** - प्रोडक्शन-गुणवत्ता कोड उत्पन्न करने के लिए। मॉडल प्रोडक्शन मानकों के अनुसार कोड जनरेट करता है जिसमें उचित त्रुटि नियंत्रण होता है। नए फीचर्स या सेवाएँ बनाने के लिए इसका उपयोग करें। +**आत्म-परावर्तित कोड** - उत्पादन-गुणवत्ता वाले कोड का उत्पादन करने के लिए। मॉडल उत्पादन मानकों का पालन करते हुए कोड बनाता है जिसमें उचित त्रुटि प्रबंधन होता है। इसका उपयोग नई विशेषताएँ या सेवाएँ बनाने के लिए करें। ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -नीचे की आकृति इस पुनरावृत्त सुधार चक्र को दिखाती है — उत्पन्न करें, मूल्यांकन करें, कमजोरियाँ पहचानें, और सुधार करें जब तक कोड प्रोडक्शन मानकों को पूरा न कर ले। +नीचे के चित्र में यह पुनरावर्ती सुधार चक्र दिखाया गया है — उत्पन्न करें, मूल्यांकन करें, कमजोरियां पहचानें, और कोड उत्पादन मानकों तक पहुँचने तक परिष्कृत करें। Self-Reflection Cycle -*पुनरावृत्त सुधार चक्र - उत्पन्न करें, मूल्यांकन करें, मुद्दे पहचानें, सुधार करें, दोहराएं* +*पुनरावर्ती सुधार चक्र - बनाएं, मूल्यांकन करें, समस्या पहचानें, सुधार करें, दोहराएं* -**संरचित विश्लेषण** - सुसंगत मूल्यांकन के लिए। मॉडल एक तय फ़्रेमवर्क (सहीपन, प्रथाएँ, प्रदर्शन, सुरक्षा, रखरखाव) का उपयोग करते हुए कोड की समीक्षा करता है। कोड समीक्षा या गुणवत्ता आकलन के लिए उपयोग करें। +**संरचित विश्लेषण** - लगातार मूल्यांकन के लिए। मॉडल कोड को एक निश्चित फ्रेमवर्क (सहीपन, अभ्यास, प्रदर्शन, सुरक्षा, अनुरक्षणीयता) के तहत समीक्षा करता है। इसका उपयोग कोड समीक्षा या गुणवत्ता आकलनों के लिए करें। ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ ट्राई करें:** संरचित विश्लेषण के बारे में पूछें: -> - "विभिन्न प्रकार की कोड समीक्षाओं के लिए विश्लेषण फ़्रेमवर्क को कैसे अनुकूलित करें?" -> - "संरचित आउटपुट को प्रोग्रामेटिक रूप से पार्स और क्रियान्वित करने का सर्वोत्तम तरीका क्या है?" -> - "विभिन्न समीक्षा सत्रों में निरंतर गंभीरता स्तर कैसे सुनिश्चित करें?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ प्रयास करें:** संरचित विश्लेषण के बारे में पूछें: +> - "अलग-अलग प्रकार की कोड समीक्षाओं के लिए विश्लेषण फ्रेमवर्क को कैसे कस्टमाइज करू?" +> - "संरचित आउटपुट को प्रोग्रामेटिक रूप से पार्स और लागू करने का सबसे अच्छा तरीका क्या है?" +> - "अलग-अलग समीक्षा सत्रों में लगातार गंभीरता स्तर कैसे सुनिश्चित करें?" -नीचे की आकृति दिखाती है कि कैसे यह संरचित फ़्रेमवर्क कोड समीक्षा को निरंतर श्रेणियों में गंभीरता स्तर के साथ व्यवस्थित करता है। +निम्न चित्र यह दिखाता है कि कैसे यह संरचित फ्रेमवर्क कोड समीक्षा को लगातार श्रेणियों में severity levels के साथ व्यवस्थित करता है। Structured Analysis Pattern -*गंभीरता स्तर के साथ सुसंगत कोड समीक्षा के लिए फ़्रेमवर्क* +*गंभीरता स्तर के साथ लगातार कोड समीक्षाओं के लिए फ्रेमवर्क* -**मल्टी-टर्न चैट** - वार्तालाप के लिए जिसमें संदर्भ की आवश्यकता हो। मॉडल पहले के संदेश याद रखता है और उन पर आधारित प्रतिक्रियाएँ बनाता है। इंटरैक्टिव सहायता सत्र या जटिल प्रश्नोत्तर के लिए उपयोग करें। +**मल्टी-टर्न चैट** - ऐसी बातचीत के लिए जिसमें संदर्भ की जरूरत होती है। मॉडल पिछले संदेशों को याद रखता है और उन पर निर्माण करता है। इसका उपयोग इंटरेक्टिव हेल्प सेशंस या जटिल प्रश्नोत्तर के लिए करें। ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -नीचे की आकृति दिखाती है कि कैसे वार्तालाप संदर्भ कई टर्नों के दौरान जमा होता है और यह मॉडल के टोकन सीमा से कैसे संबंधित है। +नीचे का चित्र दिखाता है कि कैसे बातचीत का संदर्भ कई टर्न्स में जमा होता है और यह मॉडल के टोकन सीमा से कैसे संबंधित है। Context Memory -*कैसे वार्तालाप संदर्भ कई टर्नों में जमा होता है जब तक कि टोकन सीमा पहुँच न जाए* -**स्टेप-बाय-स्टेप तर्क** - ऐसे समस्याओं के लिए जहाँ स्पष्ट तर्क आवश्यक होता है। मॉडल प्रत्येक चरण के लिए स्पष्ट तर्क प्रस्तुत करता है। इसे गणित की समस्याओं, तर्क पहेलियों या तब उपयोग करें जब आपको सोचने की प्रक्रिया समझनी हो। +*कैसे बातचीत का संदर्भ एकाधिक टर्न्स में जमा होता है जब तक कि टोकन सीमा तक न पहुँचे* + +**कदम-दर-कदम तर्क** - ऐसे समस्याओं के लिए जिनमें स्पष्ट लॉजिक की आवश्यकता होती है। मॉडल हर कदम के लिए स्पष्ट तर्क दर्शाता है। इसका उपयोग गणित की समस्या, तर्क पहेली या जब आप सोचने की प्रक्रिया को समझना चाहते हैं। ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -नीचे दिया गया चित्र दिखाता है कि कैसे मॉडल समस्याओं को स्पष्ट, क्रमांकित तर्कात्मक चरणों में विभाजित करता है। +नीचे का चित्र दिखाता है कि कैसे मॉडल समस्याओं को स्पष्ट, क्रमांकित तार्किक चरणों में विभाजित करता है। Step-by-Step Pattern +*समस्याओं को स्पष्ट तार्किक चरणों में विभाजित करना* -*समस्याओं को स्पष्ट तर्कात्मक चरणों में विभाजित करना* - -**बाध्य आउटपुट** - ऐसे उत्तरों के लिए जिनमें विशिष्ट स्वरूप आवश्यकताएँ होती हैं। मॉडल सख्ती से स्वरूप और लंबाई नियमों का पालन करता है। इसे सारांशों या जब आपको सटीक आउटपुट संरचना चाहिए तब उपयोग करें। +**सीमित आउटपुट** - विशेष प्रारूप आवश्यकताओं वाले उत्तरों के लिए। मॉडल सख्ती से प्रारूप और लंबाई नियमों का पालन करता है। इसका उपयोग सारांशों के लिए या जब आपको सटीक आउटपुट संरचना की आवश्यकता हो। ```java String prompt = """ @@ -420,21 +420,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -निम्नलिखित चित्र दिखाता है कि कैसे बाधाएं मॉडल को सख्ती से आपके स्वरूप और लंबाई आवश्यकताओं के अनुरूप आउटपुट उत्पन्न करने के लिए मार्गदर्शन करती हैं। +निम्नलिखित आरेख दिखाता है कि कैसे प्रतिबंध मॉडल को आपके प्रारूप और लंबाई आवश्यकताओं के कड़ाई से पालन करने वाला आउटपुट उत्पन्न करने के लिए मार्गदर्शन करते हैं। Constrained Output Pattern -*विशिष्ट स्वरूप, लंबाई और संरचना आवश्यकताओं को लागू करना* +*विशिष्ट प्रारूप, लंबाई, और संरचना आवश्यकताओं को लागू करना* ## एप्लिकेशन चलाएँ **डिप्लॉयमेंट सत्यापित करें:** -सुनिश्चित करें कि `.env` फ़ाइल रूट डायरेक्टरी में मौजूद है जिसमें Azure क्रेडेंशियल्स हैं (Module 01 के दौरान बनाया गया)। इसे मॉड्यूल डायरेक्टरी (`02-prompt-engineering/`) से चलाएं: +सुनिश्चित करें कि `.env` फ़ाइल रूट निर्देशिका में मौजूद है जिसमें Azure क्रेडेंशियल्स हैं (जो मॉड्यूल 01 के दौरान बनाई गई थी)। इसे मॉड्यूल निर्देशिका (`02-prompt-engineering/`) से चलाएँ: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दिखाने चाहिए +cat ../.env # इसे AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दिखाना चाहिए ``` **PowerShell:** @@ -444,25 +444,25 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दिखा **एप्लिकेशन शुरू करें:** -> **नोट:** यदि आपने पहले ही रूट डायरेक्टरी से `./start-all.sh` का उपयोग करके सभी एप्लिकेशन शुरू कर दिए हैं (जैसा कि Module 01 में वर्णित है), तो यह मॉड्यूल पोर्ट 8083 पर पहले से चल रहा है। आप नीचे दिए गए स्टार्ट कमांड छोड़ सकते हैं और सीधे http://localhost:8083 पर जा सकते हैं। +> **नोट:** यदि आपने पहले ही रूट निर्देशिका से `./start-all.sh` का उपयोग करते हुए सभी एप्लिकेशन शुरू कर दिए हैं (जैसा कि मॉड्यूल 01 में बताया गया है), तो यह मॉड्यूल पहले से पोर्ट 8083 पर चल रहा है। आप नीचे दिए गए स्टार्ट कमांड्स छोड़ सकते हैं और सीधे http://localhost:8083 पर जा सकते हैं। -**ऑप्शन 1: Spring Boot डैशबोर्ड का उपयोग करना (VS Code उपयोगकर्ताओं के लिए अनुशंसित)** +**विकल्प 1: स्प्रिंग बूट डैशबोर्ड का उपयोग करना (VS कोड उपयोगकर्ताओं के लिए अनुशंसित)** -डेव कंटेनर में Spring Boot डैशबोर्ड एक्सटेंशन शामिल है, जो सभी Spring Boot एप्लिकेशन को प्रबंधित करने के लिए एक दृश्य इंटरफ़ेस प्रदान करता है। आप इसे VS Code के Activity Bar के बाईं ओर देख सकते हैं (Spring Boot आइकन देखें)। +डेव कंटेनर में स्प्रिंग बूट डैशबोर्ड एक्सटेंशन शामिल है, जो सभी स्प्रिंग बूट एप्लिकेशन को प्रबंधित करने के लिए एक दृश्य इंटरफ़ेस प्रदान करता है। आप इसे VS कोड के बाईं तरफ एक्टिविटी बार में पा सकते हैं (स्प्रिंग बूट आइकन देखें)। -Spring Boot डैशबोर्ड से आप: -- वर्कस्पेस में सभी उपलब्ध Spring Boot एप्लिकेशन देख सकते हैं -- एक क्लिक से एप्लिकेशन शुरू/रोक सकते हैं -- वास्तविक समय में एप्लिकेशन के लॉग देख सकते हैं -- एप्लिकेशन की स्थिति मॉनिटर कर सकते हैं +स्प्रिंग बूट डैशबोर्ड से, आप: +- वर्कस्पेस में सभी उपलब्ध स्प्रिंग बूट एप्लिकेशन देख सकते हैं +- एप्लिकेशन को एक क्लिक में शुरू/रोक सकते हैं +- वास्तविक समय में एप्लिकेशन लॉग देख सकते हैं +- एप्लिकेशन की स्थिति की निगरानी कर सकते हैं -"prompt-engineering" के बगल में प्ले बटन क्लिक करके इस मॉड्यूल को शुरू करें, या सभी मॉड्यूल एक साथ शुरू करें। +सिर्फ "prompt-engineering" के पास प्ले बटन पर क्लिक करें इस मॉड्यूल को शुरू करने के लिए, या सभी मॉड्यूल को एक साथ शुरू करें। Spring Boot Dashboard -*VS Code में Spring Boot डैशबोर्ड—सभी मॉड्यूल एक ही जगह से शुरू, रोकें और मॉनिटर करें* +*VS कोड में स्प्रिंग बूट डैशबोर्ड — सभी मॉड्यूल को एक स्थान से शुरू, रोकें, और मॉनिटर करें* -**ऑप्शन 2: शेल स्क्रिप्ट का उपयोग करना** +**विकल्प 2: शेल स्क्रिप्ट का उपयोग करना** सभी वेब एप्लिकेशन शुरू करें (मॉड्यूल 01-04): @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -दोनों स्क्रिप्ट रूट `.env` फ़ाइल से पर्यावरण चर स्वचालित रूप से लोड करती हैं और यदि JAR फ़ाइलें मौजूद नहीं हैं तो उन्हें बनाएंगी। +दोनों स्क्रिप्ट्स स्वतः रूट `.env` फ़ाइल से वातावरण वेरिएबल लोड करती हैं और यदि JAR फाइलें मौजूद नहीं हैं तो उन्हें बिल्ड भी करेंगी। -> **नोट:** यदि आप शुरू करने से पहले सभी मॉड्यूल मैन्युअली बिल्ड करना पसंद करते हैं: +> **नोट:** यदि आप शुरू करने से पहले मैन्युअली सभी मॉड्यूल बिल्ड करना चाहते हैं: > > **Bash:** > ```bash @@ -521,76 +521,76 @@ cd .. && ./stop-all.sh # सभी मॉड्यूल **PowerShell:** ```powershell -.\stop.ps1 # यह मॉड्यूल केवल +.\stop.ps1 # केवल यह मॉड्यूल # या -cd ..; .\stop-all.ps1 # सभी मॉड्यूल्स +cd ..; .\stop-all.ps1 # सभी मॉड्यूल ``` -## एप्लिकेशन स्क्रीनशॉट्स +## एप्लिकेशन स्क्रीनशॉट -यहां प्रॉम्प्ट इंजीनियरिंग मॉड्यूल का मुख्य इंटरफ़ेस है, जहाँ आप आठों पैटर्न एक साथ प्रयोग कर सकते हैं। +यहां प्रॉम्प्ट इंजीनियरिंग मॉड्यूल का मुख्य इंटरफ़ेस है, जहां आप सभी आठ पैटर्न को एक साथ प्रयोग कर सकते हैं। Dashboard Home -*मुख्य डैशबोर्ड जो सभी 8 प्रॉम्प्ट इंजीनियरिंग पैटर्न उनके लक्षणों और उपयोग मामलों के साथ दिखाता है* +*मुख्य डैशबोर्ड जो सभी 8 प्रॉम्प्ट इंजीनियरिंग पैटर्न को उनके लक्षणों और उपयोग मामलों के साथ दिखाता है* -## पैटर्न्स की खोज +## पैटर्न का अन्वेषण -वेब इंटरफ़ेस आपको विभिन्न प्रॉम्प्टिंग रणनीतियों के साथ प्रयोग करने देता है। प्रत्येक पैटर्न अलग-अलग समस्याओं को हल करता है - देखें कि कौन सा पैटर्न कब कार्य करता है। +वेब इंटरफ़ेस आपको विभिन्न प्रॉम्प्टिंग रणनीतियों का प्रयोग करने देता है। प्रत्येक पैटर्न विभिन्न समस्याओं को हल करता है - उन्हें आज़माएँ यह देखने के लिए कि हर दृष्टिकोण कब बेहतर काम करता है। -> **नोट: स्ट्रीमिंग बनाम नॉन-स्ट्रीमिंग** — प्रत्येक पैटर्न पेज पर दो बटन हैं: **🔴 स्ट्रीम रिस्पांस (लाइव)** और एक **नॉन-स्ट्रीमिंग** विकल्प। स्ट्रीमिंग Server-Sent Events (SSE) का उपयोग करता है ताकि मॉडल द्वारा जेनरेट किए जा रहे टोकन वास्तविक समय में दिखाई दें, इसलिए आप तुरंत प्रगति देख सकते हैं। नॉन-स्ट्रीमिंग विकल्प पूरी प्रतिक्रिया आने तक प्रतीक्षा करता है। गहरे तर्क वाले प्रॉम्प्ट्स (जैसे High Eagerness, Self-Reflecting Code) के लिए नॉन-स्ट्रीमिंग कॉल बहुत लंबा समय ले सकता है — कभी-कभी मिनटों तक — बिना कोई दृश्य प्रतिक्रिया। **जटिल प्रॉम्प्ट्स के साथ प्रयोग करते समय स्ट्रीमिंग का उपयोग करें** ताकि आप मॉडल को काम करते देखें और ऐसा न लगे कि अनुरोध टाइम आउट हो गया हो। +> **नोट: स्ट्रीमिंग बनाम नॉन-स्ट्रीमिंग** — प्रत्येक पैटर्न पेज पर दो बटन होते हैं: **🔴 Stream Response (Live)** और एक **नॉन-स्ट्रीमिंग** विकल्प। स्ट्रीमिंग सर्वर-सेन्ट इवेंट्स (SSE) का उपयोग करता है जो वास्तविक समय में टोकन दिखाता है जब मॉडल उन्हें उत्पन्न करता है, इसलिए आप तुरंत प्रगति देख सकते हैं। नॉन-स्ट्रीमिंग विकल्प पूरा उत्तर प्राप्त होने तक प्रतीक्षा करता है। गहरे तर्क वाले प्रॉम्प्ट्स (जैसे हाई ईगर्नेस, सेल्फ-रिफ्लेक्टिंग कोड) के लिए, नॉन-स्ट्रीमिंग कॉल बहुत लंबा समय ले सकता है — कभी-कभी मिनटों तक — बिना किसी दृश्य प्रतिक्रिया के। **जटिल प्रॉम्प्ट्स के साथ प्रयोग करते समय स्ट्रीमिंग का उपयोग करें** ताकि आप मॉडल के काम करते हुए देख सकें और यह न लगे कि अनुरोध अवधि समाप्त हो गई है। > -> **नोट: ब्राउज़र आवश्यकता** — स्ट्रीमिंग फीचर Fetch Streams API (`response.body.getReader()`) का उपयोग करता है, जो पूर्ण ब्राउज़र (Chrome, Edge, Firefox, Safari) में ही कार्य करता है। यह VS Code के इन-बिल्ट Simple Browser में काम नहीं करता क्योंकि उसका वेबव्यू ReadableStream API को सपोर्ट नहीं करता। यदि आप Simple Browser का उपयोग करते हैं, तो नॉन-स्ट्रीमिंग बटन सामान्य रूप से काम करेंगे — केवल स्ट्रीमिंग बटन प्रभावित होंगे। पूर्ण अनुभव के लिए बाहरी ब्राउज़र में `http://localhost:8083` खोलें। +> **नोट: ब्राउज़र आवश्यकता** — स्ट्रीमिंग फीचर Fetch Streams API (`response.body.getReader()`) का उपयोग करता है जिसे एक फुल ब्राउज़र (Chrome, Edge, Firefox, Safari) की जरूरत होती है। यह VS कोड के बिल्ट-इन सिंपल ब्राउज़र में काम नहीं करता है क्योंकि उसका वेबव्यू ReadableStream API का समर्थन नहीं करता। यदि आप सिंपल ब्राउज़र का उपयोग करते हैं, तो नॉन-स्ट्रीमिंग बटन सामान्य रूप से कार्य करेंगे — केवल स्ट्रीमिंग बटन प्रभावित होंगे। पूर्ण अनुभव के लिए `http://localhost:8083` को बाहरी ब्राउज़र में खोलें। -### कम बनाम अधिक उत्सुकता +### कम बनाम उच्च उत्साह -"15% of 200 क्या है?" जैसे सरल प्रश्न Low Eagerness के साथ पूछें। आपको तुरंत, सीधे उत्तर मिलेगा। अब "उच्च-ट्रैफ़िक API के लिए कैशिंग रणनीति डिज़ाइन करें" जैसा जटिल सवाल High Eagerness के साथ पूछें। **🔴 स्ट्रीम रिस्पांस (लाइव)** क्लिक करें और देखें कि मॉडल कैसे टोकन-दर-टोकन विस्तृत तर्क प्रस्तुत करता है। समान मॉडल, समान प्रश्न संरचना - लेकिन प्रॉम्प्ट बताता है कि कितना सोच-विचार करना है। +"200 का 15% क्या है?" जैसे सरल प्रश्न को कम उत्साह के साथ पूछें। आपको एक त्वरित, सीधे उत्तर मिलेगा। अब कुछ जटिल पूछें जैसे "उच्च-ट्रैफ़िक API के लिए कैशिंग रणनीति डिज़ाइन करें" उच्च उत्साह के साथ। **🔴 Stream Response (Live)** पर क्लिक करें और मॉडल के विस्तृत तर्क को टोकन-दर-टोकन देखें। समान मॉडल, समान प्रश्न संरचना - लेकिन प्रॉम्प्ट उसे बताता है कि कितना विचार करना है। ### कार्य निष्पादन (टूल प्रीएम्बल्स) -मल्टी-स्टेप वर्कफ़्लोज पहले से योजना और प्रगति narration से लाभ उठाते हैं। मॉडल बताता है कि वह क्या करेगा, हर चरण का वर्णन करता है, फिर परिणाम सारांशित करता है। +मल्टी-स्टेप वर्कफ़्लो पहले से योजना बनाने और प्रगति का वर्णन करने से लाभ उठाते हैं। मॉडल बताता है कि वह क्या करेगा, प्रत्येक चरण का वर्णन करता है, फिर परिणामों का सारांश करता है। -### स्व-प्रतिबिंबित कोड +### स्वयं-प्रतिबिंबित कोड -"एक ईमेल सत्यापन सेवा बनाएं" आज़माएं। केवल कोड जेनरेट करने और रुकने के बजाय, मॉडल जेनरेट करता है, गुणवत्ता मानदंडों के खिलाफ मूल्यांकन करता है, कमजोरियां पहचानता है, और सुधार करता है। आप देखेंगे कि यह तब तक पुनरावृत्ति करता है जब तक कोड उत्पादन मानकों को पूरा न कर ले। +"एक ईमेल सत्यापन सेवा बनाएं" आज़माएँ। केवल कोड उत्पन्न करने और रुकने की बजाय, मॉडल कोड उत्पन्न करता है, गुणवत्ता मानदंडों के खिलाफ मूल्यांकन करता है, कमजोरियां पहचानता है, और सुधार करता है। आप देखेंगे कि यह तब तक पुनरावृत्ति करता है जब तक कोड उत्पादन मानकों को पूरा न कर लें। ### संरचित विश्लेषण -कोड समीक्षा के लिए सुसंगत मूल्यांकन फ्रेमवर्क की आवश्यकता होती है। मॉडल कोड का विश्लेषण तय श्रेणियों (सहीपन, प्रथाएँ, प्रदर्शन, सुरक्षा) के साथ गंभीरता स्तरों के आधार पर करता है। +कोड समीक्षाओं को लगातार मूल्यांकन फ्रेमवर्क की आवश्यकता होती है। मॉडल कोड का विश्लेषण स्थिर श्रेणियों (शुद्धता, प्रथाएँ, प्रदर्शन, सुरक्षा) के साथ करता है और तीव्रता स्तर दर्शाता है। -### मल्टी-टर्न चैट +### बहु-चरण वार्तालाप -"Spring Boot क्या है?" पूछें, फिर तुरंत "मुझे एक उदाहरण दिखाओ" पूछें। मॉडल आपका पहला प्रश्न याद रखता है और आपको विशेष रूप से Spring Boot का उदाहरण देता है। बिना मेमोरी के, दूसरा प्रश्न बहुत अस्पष्ट होगा। +"स्प्रिंग बूट क्या है?" पूछें और तुरंत "मुझे एक उदाहरण दिखाएं" का पालन करें। मॉडल आपके पहले प्रश्न को याद रखता है और आपको विशेष रूप से स्प्रिंग बूट का उदाहरण देता है। बिना स्मृति के, दूसरा प्रश्न बहुत अस्पष्ट होता। -### स्टेप-बाय-स्टेप तर्क +### चरण-दर-चरण तर्क -कोई गणित की समस्या चुनें और इसे दोनों स्टेप-बाय-स्टेप तर्क और कम उत्सुकता के साथ आज़माएं। कम उत्सुकता सिर्फ उत्तर देता है — तेज लेकिन अस्पष्ट। स्टेप-बाय-स्टेप आपको हर गणना और निर्णय दिखाता है। +कोई गणित की समस्या चुनें और इसे चरण-दर-चरण तर्क और कम उत्साह दोनों के साथ आज़माएँ। कम उत्साह सिर्फ जल्दी उत्तर देता है - तेज लेकिन अस्पष्ट। चरण-दर-चरण आपको हर गणना और निर्णय दिखाता है। -### बाध्य आउटपुट +### सीमित आउटपुट -जब आपको विशिष्ट स्वरूप या शब्द संख्या की आवश्यकता हो, यह पैटर्न सख्ती से पालन करता है। ठीक 100 शब्दों के बुलेट पॉइंट फॉर्मेट में सारांश बनाएं। +जब आपको विशिष्ट प्रारूप या शब्द संख्या की आवश्यकता होती है, तो यह पैटर्न कड़ाई से पालन करता है। बिल्कुल 100 शब्दों वाले बुलेट पॉइंट फॉर्मेट में सारांश उत्पन्न करने का प्रयास करें। ## आप वास्तव में क्या सीख रहे हैं **तर्क प्रयास सब कुछ बदल देता है** -GPT-5.2 आपको प्रॉम्प्ट के जरिए गणना प्रयास नियंत्रित करने देता है। कम प्रयास तेज उत्तर देता है जिसमें न्यूनतम खोज होती है। उच्च प्रयास का मतलब है कि मॉडल गहराई से सोचने के लिए समय लेता है। आप सीख रहे हैं कि कार्य की जटिलता के अनुसार प्रयास मिलाएं — सरल प्रश्नों पर समय बर्बाद न करें, लेकिन जटिल निर्णय जल्दी न करें। +GPT-5.2 आपको अपने प्रॉम्प्ट्स के माध्यम से गणनात्मक प्रयास को नियंत्रित करने देता है। कम प्रयास का मतलब है तेज उत्तर जिसमें न्यूनतम खोज होती है। उच्च प्रयास का मतलब है मॉडल को गहराई से सोचने के लिए समय लेना। आप सीख रहे हैं कि प्रयास को कार्य की जटिलता के अनुसार मिलाएं - सरल प्रश्नों पर समय बर्बाद न करें, लेकिन जटिल निर्णयों में जल्दी न करें। -**संरचना व्यवहार को मार्गदर्शित करती है** +**संरचना व्यवहार का मार्गदर्शन करती है** -प्रॉम्प्ट में XML टैग्स देखें? वे केवल सजावट नहीं हैं। मॉडल संरचित निर्देशों का पालन मुक्त रूप के मुकाबले अधिक भरोसेमंद तरीके से करता है। जब आपको मल्टी-स्टेप प्रक्रियाएं या जटिल तर्क चाहिए, संरचना मॉडल को यह ट्रैक करने में मदद करती है कि वह कहाँ है और अगला क्या है। नीचे दिया गया चित्र एक अच्छी तरह से संरचित प्रॉम्प्ट को तोड़ता है, दिखाता है कि ``, ``, ``, ``, और `` जैसे टैग आपके निर्देशों को स्पष्ट खंडों में कैसे व्यवस्थित करते हैं। +प्रॉम्प्ट में XML टैग्स देखें? वे सजावट नहीं हैं। मॉडल संरचित निर्देशों का पालन स्वतंत्र पाठ की तुलना में अधिक विश्वसनीयता से करता है। जब आपको मल्टी-स्टेप प्रक्रियाएं या जटिल तर्क चाहिए, तो संरचना मॉडल की सहायता करती है यह ट्रैक करने में कि वह कहाँ है और अगला क्या है। नीचे दिया गया आरेख एक सुव्यवस्थित प्रॉम्प्ट को तोड़ता है, दिखाते हुए कि कैसे टैग्स जैसे ``, ``, ``, ``, और `` आपके निर्देशों को स्पष्ट अनुभागों में व्यवस्थित करते हैं। Prompt Structure -*एक अच्छी तरह से संरचित प्रॉम्प्ट की संरचना जिसमें स्पष्ट अनुभाग और XML-शैली संगठन है* +*एक सुव्यवस्थित प्रॉम्प्ट का अवयव जिसमें स्पष्ट अनुभाग और XML-शैली संगठन है* -**स्व-मूल्यांकन के जरिए गुणवत्ता** +**स्व-मूल्यांकन के माध्यम से गुणवत्ता** -स्व-प्रतिबिंबित पैटर्न गुणवत्ता मानदंडों को स्पष्ट बनाकर काम करते हैं। मॉडल पर "यह सही करेगा" की आशा करने के बजाय, आप उसे बताते हैं कि "सही" का क्या अर्थ है: सही तर्क, त्रुटि हैंडलिंग, प्रदर्शन, सुरक्षा। मॉडल तब अपनी आउटपुट का मूल्यांकन कर सकता है और सुधार कर सकता है। इससे कोड निर्माण लॉटरी नहीं बल्कि एक प्रक्रिया बन जाता है। +स्वयं-प्रतिबिंबित पैटर्न गुणवत्ता मानदंडों को स्पष्ट बनाकर काम करते हैं। मॉडल के "सही करने" की आशा करने के बजाय, आप इसे बताते हैं कि "सही" का क्या मतलब है: सही तर्क, त्रुटि प्रबंधन, प्रदर्शन, सुरक्षा। फिर मॉडल अपने आउटपुट का मूल्यांकन कर सकता है और सुधार कर सकता है। यह कोड जनरेशन को लॉटरी से प्रक्रिया में बदल देता है। **संदर्भ सीमित है** -मल्टी-टर्न वार्तालाप प्रत्येक अनुरोध के साथ संदेश इतिहास शामिल करके काम करता है। लेकिन सीमा होती है — प्रत्येक मॉडल की अधिकतम टोकन संख्या होती है। संवाद बढ़ने पर आपको ऐसी रणनीतियां अपनानी होंगी जिससे प्रासंगिक संदर्भ बना रहे बिना उस सीमा को पार किए। यह मॉड्यूल आपको मेमोरी कैसे काम करती है दिखाता है; बाद में आप सीखेंगे कब सारांश बनाना है, कब भूलना है, और कब पुनः प्राप्त करना है। +बहु-चरण वार्तालाप हर अनुरोध के साथ संदेश इतिहास शामिल कर काम करते हैं। लेकिन सीमा होती है - हर मॉडल की अधिकतम टोकन संख्या होती है। जैसे-जैसे बातचीत बढ़ती है, आपको प्रासंगिक संदर्भ बनाए रखने के लिए रणनीतियाँ अपनानी होंगी बिना उस सीमा को पार किए। यह मॉड्यूल आपको दिखाता है कि स्मृति कैसे काम करती है; बाद में आप सीखेंगे कि कब सारांश बनाना है, कब भूलना है, और कब पुनः प्राप्त करना है। ## अगले कदम @@ -598,11 +598,11 @@ GPT-5.2 आपको प्रॉम्प्ट के जरिए गणन --- -**नेविगेशन:** [← पिछला: Module 01 - परिचय](../01-introduction/README.md) | [मुख्य पृष्ठ पर वापस](../README.md) | [अगला: Module 03 - RAG →](../03-rag/README.md) +**नेविगेशन:** [← पिछला: मॉड्यूल 01 - परिचय](../01-introduction/README.md) | [मुख्य पेज पर वापस](../README.md) | [अगला: मॉड्यूल 03 - RAG →](../03-rag/README.md) --- **अस्वीकरण**: -यह दस्तावेज़ एआई अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके अनुवादित किया गया है। जबकि हम सटीकता के लिए प्रयासरत हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल भाषा में मूल दस्तावेज़ को अधिकृत स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। +इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। \ No newline at end of file diff --git a/translations/hi/03-rag/README.md b/translations/hi/03-rag/README.md index b283ddba4..0c07e23bd 100644 --- a/translations/hi/03-rag/README.md +++ b/translations/hi/03-rag/README.md @@ -1,144 +1,143 @@ -# Module 03: RAG (रिट्रीवल-ऑगमेंटेड जनरेशन) - -## Table of Contents - -- [Video Walkthrough](../../../03-rag) -- [What You'll Learn](../../../03-rag) -- [Prerequisites](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Does This Tutorial Use?](../../../03-rag) -- [How It Works](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload a Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matters](../../../03-rag) -- [Next Steps](../../../03-rag) - -## Video Walkthrough - -देखें यह लाइव सेशन जो बताता है कि इस मॉड्यूल के साथ कैसे शुरुआत करें: +# मॉड्यूल 03: RAG (रिट्रीवल-अगमेंटेड जनरेशन) + +## सामग्री-सूची + +- [वीडियो वॉकथ्रू](#वीडियो-वॉकथ्रू) +- [आप क्या सीखेंगे](#आप-क्या-सीखेंगे) +- [पूर्व आवश्यकताएँ](#पूर्व-आवश्यकताएँ) +- [RAG को समझना](#rag-को-समझना) + - [इस ट्यूटोरियल में कौन सा RAG दृष्टिकोण उपयोग होता है?](#इस-ट्यूटोरियल-में-कौन-सा-rag-दृष्टिकोण-उपयोग-होता-है) +- [यह कैसे काम करता है](#यह-कैसे-काम-करता-है) + - [दस्तावेज़ प्रसंस्करण](#दस्तावेज़-प्रसंस्करण) + - [एम्बेडिंग बनाना](#एम्बेडिंग-बनाना) + - [सिमेंटिक सर्च](#सिमेंटिक-सर्च) + - [उत्तर निर्माण](#उत्तर-उत्पन्न-करना) +- [एप्लिकेशन चलाना](#एप्लिकेशन-चलाएँ) +- [एप्लिकेशन का उपयोग](#एप्लिकेशन-का-उपयोग-करना) + - [दस्तावेज़ अपलोड करें](#एक-दस्तावेज़-अपलोड-करें) + - [प्रश्न पूछें](#प्रश्न-पूछें) + - [स्रोत संदर्भ जांचें](#स्रोत-संदर्भ-जांचें) + - [प्रश्नों के साथ प्रयोग करें](#प्रश्नों-के-साथ-प्रयोग-करें) +- [प्रमुख अवधारणाएँ](#मुख्य-अवधारणाएँ) + - [चंकिंग रणनीति](#खंडन-रणनीति) + - [समानता स्कोर](#समानता-स्कोर) + - [इन-मेमोरी भंडारण](#इन-मेमोरी-स्टोरेज) + - [कॉन्टेक्स्ट विंडो प्रबंधन](#संदर्भ-विंडो-प्रबंधन) +- [जब RAG महत्वपूर्ण होता है](#जब-rag-महत्वपूर्ण-होता-है) +- [अगले कदम](#अगले-कदम) + +## वीडियो वॉकथ्रू + +इस लाइव सत्र को देखें जो इस मॉड्यूल के साथ आरंभ करने का तरीका समझाता है: RAG with LangChain4j - Live Session -## What You'll Learn +## आप क्या सीखेंगे -पिछले मॉड्यूल्स में, आपने सीखा कि AI से बातचीत कैसे करें और अपने प्रॉम्प्ट्स को प्रभावी ढंग से कैसे संरचित करें। लेकिन एक मूलभूत सीमा है: भाषा मॉडल केवल वही जानते हैं जो उन्होंने प्रशिक्षण के दौरान सीखा है। वे आपकी कंपनी की नीतियों, आपके प्रोजेक्ट दस्तावेज़ या उन जानकारियों पर उत्तर नहीं दे सकते जिन पर वे प्रशिक्षित नहीं हुए। +पिछले मॉड्यूल में, आपने सीखा कि कैसे AI के साथ वार्तालाप करें और अपने प्रांप्ट्स को प्रभावी ढंग से संरचित करें। लेकिन एक मौलिक सीमा है: भाषा मॉडल केवल वही जानते हैं जो उन्होंने प्रशिक्षण के दौरान सीखा है। वे आपके कंपनी की नीतियों, आपके प्रोजेक्ट की डाक्यूमेंटेशन, या ऐसी किसी भी जानकारी पर सवाल का जवाब नहीं दे सकते जिन पर उन्हें प्रशिक्षित नहीं किया गया। -RAG (रिट्रीवल-ऑगमेंटेड जनरेशन) इस समस्या को हल करता है। मॉडल को आपकी जानकारी सिखाने की कोशिश करने के बजाय (जो महंगा और व्यावहारिक नहीं है), आप इसे अपने दस्तावेज़ों के माध्यम से खोज करने की क्षमता देते हैं। जब कोई प्रश्न पूछता है, तो सिस्टम प्रासंगिक जानकारी ढूंढता है और उसे प्रॉम्प्ट में शामिल करता है। मॉडल फिर उस प्राप्त संदर्भ के आधार पर उत्तर देता है। +RAG (रिट्रीवल-अगमेंटेड जनरेशन) इस समस्या का समाधान है। मॉडल को आपकी जानकारी सिखाने की बजाय (जो महंगा और अप्रैक्टिकल है), आप इसे आपके दस्तावेज़ों के माध्यम से खोजने की क्षमता देते हैं। जब कोई प्रश्न पूछता है, सिस्टम प्रासंगिक जानकारी खोजता है और उसे प्रांप्ट में शामिल करता है। मॉडल फिर उस पुनः प्राप्त संदर्भ के आधार पर उत्तर देता है। -RAG को एक संदर्भ पुस्तकालय देने के रूप में सोचें। जब आप प्रश्न पूछते हैं, तो सिस्टम: +RAG को आप मॉडल को एक संदर्भ पुस्तकालय देने के रूप में सोचिए। जब आप प्रश्न पूछते हैं, तंत्र: -1. **यूज़र क्वेरी** - आप सवाल पूछते हैं -2. **एम्बेडिंग** - आपके प्रश्न को एक वेक्टर में परिवर्तित करता है -3. **वेक्टर खोज** - समान दस्तावेज़ के टुकड़े खोजता है -4. **संदर्भ संयोजन** - प्रॉम्प्ट में प्रासंगिक टुकड़ों को जोड़ता है +1. **उपयोगकर्ता क्वेरी** - आप प्रश्न पूछते हैं +2. **एम्बेडिंग** - आपका प्रश्न वेक्टर में परिवर्तित होता है +3. **वेक्टर सर्च** - समान दस्तावेज़ चंक्स खोजता है +4. **संदर्भ संयोजन** - प्रासंगिक चंक्स को प्रांप्ट में जोड़ता है 5. **प्रतिक्रिया** - LLM संदर्भ के आधार पर उत्तर उत्पन्न करता है -यह मॉडल के उत्तरों को आपके वास्तविक डेटा पर आधारित करता है बजाय इसके कि वह केवल अपने प्रशिक्षण ज्ञान पर निर्भर करे या उत्तर गढ़े। +यह मॉडल के उत्तरों को आपके वास्तविक डेटा में आधार देता है बजाय इसके कि वह अपने प्रशिक्षण ज्ञान या अनुमान पर निर्भर हो। -## Prerequisites +## पूर्व आवश्यकताएँ -- पूरा किया हुआ [Module 00 - Quick Start](../00-quick-start/README.md) (इस मॉड्यूल में बाद में संदर्भित Easy RAG उदाहरण के लिए) -- पूरा किया हुआ [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI संसाधन तैनात, जिसमें `text-embedding-3-small` एम्बेडिंग मॉडल शामिल है) -- Azure क्रेडेंशियल्स के साथ रूट डायरेक्टरी में `.env` फ़ाइल (Module 01 में `azd up` द्वारा बनाई गई) +- पूरा किया हुआ [मॉड्यूल 01 - परिचय](../01-introduction/README.md) (Azure OpenAI संसाधन तैनात, जिसमें `text-embedding-3-small` एम्बेडिंग मॉडल शामिल है) +- रूट डायरेक्टरी में `.env` फ़ाइल जिसमें Azure क्रेडेंशियल्स हो (मॉड्यूल 01 में `azd up` द्वारा बनाया गया) -> **Note:** यदि आपने Module 01 पूरा नहीं किया है, तो वहां तैनाती निर्देशों का पालन करें। `azd up` कमांड GPT चैट मॉडल और इस मॉड्यूल द्वारा उपयोग किए जाने वाले एम्बेडिंग मॉडल दोनों को तैनात करता है। +> **ध्यान दें:** यदि आपने मॉड्यूल 01 पूरा नहीं किया है, तो पहले वहां तैनाती निर्देशों का पालन करें। `azd up` कमांड GPT चैट मॉडल और इस मॉड्यूल द्वारा उपयोग किए जाने वाले एम्बेडिंग मॉडल दोनों को तैनात करता है। -## Understanding RAG +## RAG को समझना -नीचे चित्र में मूल अवधारणा दर्शाई गई है: मॉडल के प्रशिक्षण डेटा पर केवल निर्भर रहने के बजाय, RAG प्रत्येक उत्तर उत्पन्न करने से पहले इसे आपकी दस्तावेजों की एक संदर्भ पुस्तकालय देता है। +नीचे दिया गया आरेख मुख्य अवधारणा को दर्शाता है: केवल मॉडल के प्रशिक्षण डेटा पर निर्भर रहने के बजाय, RAG इसे आपके दस्तावेज़ों की संदर्भ पुस्तकालय देता है ताकि वह प्रत्येक उत्तर बनाते समय उस पर सलाह कर सके। What is RAG -*यह चित्र एक मानक LLM (जो प्रशिक्षण डेटा से अनुमान लगाता है) और एक RAG-संवर्धित LLM (जो पहले आपकी दस्तावेजों से सलाह-मशविरा करता है) के बीच का अंतर दिखाता है।* +*यह आरेख एक मानक LLM (जो प्रशिक्षण डेटा से अनुमान लगाता है) और एक RAG-संवर्धित LLM (जो पहले आपके दस्तावेज़ों से सलाह लेता है) के बीच का अंतर दिखाता है।* -यहाँ टुकड़े अंत-से-अंत कैसे जुड़े हैं। उपयोगकर्ता का प्रश्न चार चरणों से होकर गुजरता है — एम्बेडिंग, वेक्टर खोज, संदर्भ संयोजन, और उत्तर जनरेशन — प्रत्येक पिछले पर आधारित: +यहाँ यह टुकड़े अंत-से-अंत कैसे जुड़ते हैं, बताया गया है। एक उपयोगकर्ता का प्रश्न चार चरणों से गुजरता है — एम्बेडिंग, वेक्टर सर्च, संदर्भ संयोजन, और उत्तर निर्माण — प्रत्येक पिछले पर आधारित: RAG Architecture -*यह चित्र अंत-से-अंत RAG पाइपलाइन दिखाता है — एक उपयोगकर्ता क्वेरी एम्बेडिंग, वेक्टर खोज, संदर्भ संयोजन, और उत्तर उत्पादन प्रक्रिया से गुजरती है।* +*यह आरेख अंत-से-अंत RAG पाइपलाइन दिखाता है — एक उपयोगकर्ता क्वेरी एम्बेडिंग, वेक्टर सर्च, संदर्भ संयोजन, और उत्तर निर्माण से गुजरती है।* -इस मॉड्यूल के बाकी हिस्से में प्रत्येक चरण को विस्तार से दिखाया गया है, जिसमें कोड है जिसे आप चला और संशोधित कर सकते हैं। +इस मॉड्यूल के बाकी हिस्से में हम प्रत्येक चरण को विस्तार से देखेंगे, जिनमें कोड भी शामिल है जिसे आप चला और संशोधित कर सकते हैं। -### Which RAG Approach Does This Tutorial Use? +### इस ट्यूटोरियल में कौन सा RAG दृष्टिकोण उपयोग होता है? -LangChain4j RAG को लागू करने के तीन तरीके प्रदान करता है, प्रत्येक अलग स्तर की अमूर्तता के साथ। नीचे दिए गए चित्र में ये एक-दूसरे के साथ तुलना की गई हैं: +LangChain4j तीन तरीके प्रदान करता है RAG को लागू करने के लिए, प्रत्येक अलग स्तर की अमूर्तता के साथ। नीचे दिया गया आरेख उन्हें एक साथ तुलना करता है: Three RAG Approaches in LangChain4j -*यह चित्र तीन LangChain4j RAG दृष्टिकोणों — Easy, Native, और Advanced — को उनके मुख्य घटकों और उपयोग के समय के साथ तुलना करता है।* +*यह आरेख तीन LangChain4j RAG दृष्टिकोणों — Easy, Native, और Advanced — को उनके मुख्य घटकों के साथ तुलना करता है और कब प्रत्येक का उपयोग करना है।* -| Approach | What It Does | Trade-off | +| दृष्टिकोण | यह क्या करता है | ट्रैड-ऑफ | |---|---|---| -| **Easy RAG** | `AiServices` और `ContentRetriever` के माध्यम से सब कुछ स्वचालित रूप से चलाता है। आप एक इंटरफ़ेस एनोटेट करते हैं, एक रिट्रीवर संलग्न करते हैं, और LangChain4j एम्बेडिंग, खोज, और प्रॉम्प्ट संयोजन को संभालता है। | न्यूनतम कोड, लेकिन आप हर चरण नहीं देख पाते। | -| **Native RAG** | आप स्वयं एम्बेडिंग मॉडल कॉल करते हैं, स्टोर में खोज करते हैं, प्रॉम्प्ट बनाते हैं, और उत्तर उत्पन्न करते हैं — हर चरण स्पष्ट रूप से। | अधिक कोड, लेकिन हर चरण स्पष्ट और संशोधित करने योग्य है। | -| **Advanced RAG** | प्लगनेबल क्वेरी ट्रांसफॉर्मर्स, राउटर्स, री-रैंकर्स और कंटेंट इंजेक्टर के साथ प्रोडक्शन-ग्रेड पाइपलाइनों के लिए `RetrievalAugmentor` फ्रेमवर्क का उपयोग करता है। | अधिकतम लचीलापन, लेकिन काफी अधिक जटिलता। | +| **Easy RAG** | सब कुछ `AiServices` और `ContentRetriever` के माध्यम से अपने आप वायर करता है। आप एक इंटरफ़ेस एनोटेट करते हैं, एक रिट्रीवर लगाते हैं, और LangChain4j एम्बेडिंग, खोज और प्रांप्ट संयोजन को पर्दे के पीछे संभालता है। | कम कोड, लेकिन आप प्रत्येक चरण में क्या हो रहा है यह नहीं देख पाते। | +| **Native RAG** | आप स्वयं एम्बेडिंग मॉडल कॉल करते हैं, स्टोर में खोज करते हैं, प्रांप्ट बनाते हैं, और उत्तर जनरेट करते हैं — एक स्पष्ट चरण के रूप में। | अधिक कोड, लेकिन हर चरण दिखाई देता है और संशोधित किया जा सकता है। | +| **Advanced RAG** | `RetrievalAugmentor` फ्रेमवर्क का उपयोग करता है जिसमें प्लग-इन योग्य क्वेरी ट्रांसफॉर्मर्स, राउटर्स, री-रैंकर्स, और कंटेंट इंजेक्टर्स होते हैं, उत्पादन-ग्रेड पाइपलाइनों के लिए। | अत्यधिक लचीलापन, लेकिन काफी अधिक जटिलता। | -**यह ट्यूटोरियल Native दृष्टिकोण का उपयोग करता है।** RAG पाइपलाइन के प्रत्येक चरण — क्वेरी का एम्बेडिंग, वेक्टर स्टोर में खोज, संदर्भ संयोजन, और उत्तर उत्पन्न करना — [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) में स्पष्ट रूप से लिखा गया है। यह जानबूझकर किया गया है: एक सीखने वाले संसाधन के रूप में, यह ज़्यादा महत्वपूर्ण है कि आप हर चरण देखें और समझें बजाय इसके कि कोड न्यूनतम हो। एक बार जब आप समझ जाएं कि टुकड़े कैसे फिट होते हैं, तो आप द्रुत प्रोटोटाइप के लिए Easy RAG या प्रोडक्शन सिस्टम के लिए Advanced RAG पर जा सकते हैं। +**यह ट्यूटोरियल Native दृष्टिकोण का उपयोग करता है।** RAG पाइपलाइन का प्रत्येक चरण — क्वेरी का एम्बेडिंग, वेक्टर स्टोर में खोज, संदर्भ संयोजन, और उत्तर निर्माण — स्पष्ट रूप से [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) में लिखा गया है। यह इरादतन है: एक सीखने के संसाधन के रूप में, यह ज़रूरी है कि आप हर चरण देखें और समझें बजाय इस बात के कि कोड न्यूनतम हो। एक बार जब आप समझ जाएँ कि टुकड़े कैसे जुड़ते हैं, तो आप Easy RAG के लिए जल्दी प्रोटोटाइप बनाने या Advanced RAG के लिए उत्पादन प्रणाली बना सकते हैं। -> **💡 Easy RAG पहले देख चुके हैं?** [Quick Start module](../00-quick-start/README.md) में एक Document Q&A उदाहरण ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) शामिल है जो Easy RAG दृष्टिकोण का उपयोग करता है — LangChain4j स्वचालित रूप से एम्बेडिंग, खोज, और प्रॉम्प्ट संयोजन को संभालता है। यह मॉड्यूल उस पाइपलाइन को खोलता है ताकि आप देख सकें और हर चरण को नियंत्रित कर सकें। +> **💡 Easy RAG के बारे में जिज्ञासु?** LangChain4j एक *Easy RAG* दृष्टिकोण भी प्रदान करता है जहाँ `AiServices` और `ContentRetriever` एम्बेडिंग, खोज, और प्रांप्ट संयोजन अपने आप संभालते हैं। यह मॉड्यूल अधिक स्पष्ट मार्ग अपनाता है — उस पाइपलाइन को खोलता है ताकि आप हर चरण खुद देख और नियंत्रण कर सकें। -नीचे चित्र उस Quick Start उदाहरण की Easy RAG पाइपलाइन दिखाता है। ध्यान दें कि कैसे `AiServices` और `EmbeddingStoreContentRetriever` सारी जटिलता को छुपाते हैं — आप दस्तावेज़ लोड करते हैं, एक रिट्रीवर संलग्न करते हैं, और उत्तर प्राप्त करते हैं। इस मॉड्यूल में Native दृष्टिकोण उन छुपे हुए चरणों को खोलता है: +नीचे दिया गया आरेख Easy RAG पाइपलाइन दिखाता है। गौर करें कि कैसे `AiServices` और `EmbeddingStoreContentRetriever` सारी जटिलता छुपाते हैं — आप एक दस्तावेज़ लोड करते हैं, रिट्रीवर लगाते हैं, और उत्तर प्राप्त करते हैं। इस मॉड्यूल में Native दृष्टिकोण उन छुपे चरणों को खोल देता है: Easy RAG Pipeline - LangChain4j -*यह चित्र `SimpleReaderDemo.java` से Easy RAG पाइपलाइन दिखाता है। इसे इस मॉड्यूल के Native दृष्टिकोण से तुलना करें: Easy RAG एम्बेडिंग, रिट्रीवल, और प्रॉम्प्ट संयोजन को `AiServices` और `ContentRetriever` के पीछे छुपा देता है — आप एक दस्तावेज़ लोड करते हैं, रिट्रीवर संलग्न करते हैं, और उत्तर प्राप्त करते हैं। इस मॉड्यूल में Native दृष्टिकोण उस पाइपलाइन को खोलता है ताकि आप हर चरण (एम्बेड, खोजें, संदर्भ संयोजन करें, उत्तर उत्पन्न करें) स्वयं कॉल करें, जिससे पूरी दृश्यता और नियंत्रण मिलता है।* +*यह आरेख Easy RAG पाइपलाइन दिखाता है। इसे इस मॉड्यूल के Native दृष्टिकोण के साथ तुलना करें: Easy RAG एम्बेडिंग, पुनः प्राप्ति, और प्रांप्ट संयोजन को `AiServices` और `ContentRetriever` के पीछे छुपाता है — आप एक दस्तावेज़ लोड करते हैं, रिट्रीवर लगाते हैं, और उत्तर प्राप्त करते हैं। इस मॉड्यूल का Native दृष्टिकोण वह पाइपलाइन खोलता है जिससे आप हर चरण (एम्बेड, सर्च, संदर्भ जोड़ना, जनरेट करना) स्वयं कॉल करते हैं, जिससे आपको पूर्ण दृश्यता और नियंत्रण मिलता है।* -## How It Works +## यह कैसे काम करता है -इस मॉड्यूल की RAG पाइपलाइन में चार चरण होते हैं जो हर बार उपयोगकर्ता प्रश्न पूछने पर क्रमशः चलते हैं। सबसे पहले, अपलोड किया हुआ दस्तावेज़ **पार्स और चंक** किया जाता है ताकि प्रबंधनीय टुकड़े बन सकें। फिर उन टुकड़ों को **वेक्टर एम्बेडिंग** में बदला जाता है और संग्रहीत किया जाता है ताकि उनकी गणितीय तुलना की जा सके। जब कोई क्वेरी आती है, तो सिस्टम एक **सिमेंटिक खोज** करता है ताकि सबसे प्रासंगिक टुकड़े मिल सकें, और अंत में इन्हें संदर्भ के रूप में LLM को पास करता है ताकि **उत्तर उत्पन्न किया जाए**। नीचे के अनुभागों में वास्तविक कोड और आरेखों के साथ प्रत्येक चरण के बारे में बताया गया है। पहले चरण को देखें। +इस मॉड्यूल में RAG पाइपलाइन चार चरणों में टूटती है जो उपयोगकर्ता के प्रश्न पूछने पर लगातार चलते हैं। पहले, अपलोड किया गया दस्तावेज़ **विश्लेषित और चंक्स में तोड़ा** जाता है। उन चंक्स को फिर **वेक्टर एम्बेडिंग्स** में बदला जाता है और संग्रहित किया जाता है ताकि उनकी गणितीय तुलना हो सके। जब क्वेरी आती है, सिस्टम एक **सैमेंटिक सर्च** करता है सबसे प्रासंगिक चंक्स खोजने के लिए, और अंततः उन्हें संदर्भ के रूप में LLM को **उत्तर निर्माण** के लिए पास करता है। नीचे के खंड प्रत्येक चरण को कोड और आरेखों के साथ समझाते हैं। पहला चरण देखते हैं। -### Document Processing +### दस्तावेज़ प्रसंस्करण [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -जब आप कोई दस्तावेज़ अपलोड करते हैं, तो सिस्टम उसे पार्स करता है (PDF या साधारण टेक्स्ट), फ़ाइलनाम जैसी मेटाडेटा संलग्न करता है, और फिर उसे टुकड़ों में तोड़ता है — छोटे भाग जो मॉडल के संदर्भ विंडो में आराम से फिट हो सकें। ये टुकड़े थोड़े ओवरलैप होते हैं ताकि सीमाओं पर संदर्भ खो न जाए। +जब आप दस्तावेज़ अपलोड करते हैं, सिस्टम उसे पार्स करता है (PDF या सामान्य टेक्स्ट), फ़ाइलनाम जैसे मेटाडेटा संलग्न करता है, और फिर इसे चंक्स में तोड़ता है — छोटे टुकड़े जो मॉडल के संदर्भ विंडो में आराम से फिट हो सके। ये चंक्स थोड़े ओवरलैप करते हैं ताकि आप सीमाओं पर संदर्भ न खोएं। ```java -// अपलोड की गई फ़ाइल को पार्स करें और इसे LangChain4j दस्तावेज़ में लपेटें +// अपलोड की गई फाइल को पार्स करें और इसे LangChain4j डॉक्यूमेंट में लपेटें Document document = Document.from(content, metadata); -// 300-टोकन के टुकड़ों में विभाजित करें जिसमें 30-टोकन का ओवरलैप हो +// 300-टोकन चंक्स में विभाजित करें जिसमें 30-टोकन ओवरलैप हो DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -नीचे दिया गया चित्र इसे विज़ुअली दिखाता है। ध्यान दें कि हर टुकड़ा अपने पड़ोसियों के साथ कुछ टोकन साझा करता है — 30 टोकन का ओवरलैप सुनिश्चित करता है कि कोई महत्वपूर्ण संदर्भ बीच में न खो जाए: + +निचे दिया गया आरेख इसे दृश्य रूप में दिखाता है। ध्यान दें कि प्रत्येक चंक अपने पड़ोसियों के साथ कुछ टोकन्स साझा करता है — 30 टोकन ओवरलैप यह सुनिश्चित करता है कि कोई महत्वपूर्ण संदर्भ छूट न जाए: Document Chunking -*यह चित्र दिखाता है कि कैसे 300-टोकन के टुकड़ों में 30-टोकन ओवरलैप के साथ दस्तावेज़ को विभाजित किया जाता है, जिससे टुकड़ों की सीमाओं पर संदर्भ संरक्षित रहता है।* +*यह आरेख दिखाता है कि कैसे एक दस्तावेज़ को 300-टोकन के चंक्स में 30-टोकन ओवरलैप के साथ विभाजित किया जाता है, जो चंक सीमाओं पर संदर्भ को सुरक्षित रखता है।* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ कोशिश करें:** Open [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) और पूछें: -> - "LangChain4j दस्तावेज़ों को टुकड़ों में कैसे विभाजित करता है और ओवरलैप क्यों महत्वपूर्ण है?" -> - "विभिन्न दस्तावेज़ प्रकारों के लिए आदर्श टुकड़ा आकार क्या है और क्यों?" -> - "मैं कई भाषाओं या विशेष स्वरूपण वाले दस्तावेज़ों को कैसे संभाल सकता हूँ?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ प्रयास करें:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) खोलें और पूछें: +> - "LangChain4j दस्तावेज़ों को कैसे चंक्स में बांटता है और ओवरलैप क्यों महत्वपूर्ण है?" +> - "विभिन्न दस्तावेज़ प्रकारों के लिए आदर्श चंक आकार क्या है और क्यों?" +> - "मैं कई भाषाओं में दस्तावेज़ों को या विशेष फॉर्मेटिंग के साथ कैसे संभालूं?" -### Creating Embeddings +### एम्बेडिंग बनाना [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -हर टुकड़े को एक संख्यात्मक प्रतिनिधित्व में बदला जाता है जिसे एम्बेडिंग कहा जाता है — मूल रूप से एक अर्थ-से-संख्या कनवर्टर। एम्बेडिंग मॉडल "बुद्धिमान" नहीं होता जैसे कि चैट मॉडल होता है; यह आदेशों का पालन नहीं कर सकता, तर्क नहीं कर सकता, या प्रश्नों का उत्तर नहीं दे सकता। जो यह कर सकता है वह टेक्स्ट को गणितीय स्थान में मैप करना है जहाँ समान अर्थ नज़दीक होते हैं — जैसे "कार" के पास "ऑटोमोबाइल", "रिफंड पॉलिसी" के पास "मेरे पैसे वापस" के वेक्टर होते हैं। चैट मॉडल को आप एक व्यक्त‍ि समझें जिससे बात करें; एक एम्बेडिंग मॉडल एक अत्यंत अच्छा फाइलिंग सिस्टम है। +प्रत्येक चंक को संख्यात्मक प्रतिनिधित्व में बदला जाता है जिसे एम्बेडिंग कहा जाता है — मूलतः अर्थ को संख्याओं में बदलने वाला कनवर्टर। एम्बेडिंग मॉडल "अक्लमंद" नहीं होता जैसे कि चैट मॉडल होता है; यह निर्देशों का पालन नहीं कर सकता, तर्क नहीं कर सकता, या प्रश्नों का जवाब नहीं दे सकता। यह केवल टेक्स्ट को गणितीय स्थान में मैप करता है जहाँ समान अर्थ वाले वेक्टर पास-पास होते हैं — "कार" के पास "ऑटोमोबाइल," "रिफंड पॉलिसी" के पास "मेरे पैसे वापस करें"। चैट मॉडल को एक ऐसे व्यक्ति की तरह सोचिए जिससे आप बात कर सकते हैं; एम्बेडिंग मॉडल एक अत्यंत अच्छा फाइलिंग सिस्टम है। -नीचे चित्र इस अवधारणा को दिखाता है — टेक्स्ट इनपुट होता है, संख्यात्मक वेक्टर निकलते हैं, और समान अर्थ के वेक्टर पास-पास होते हैं: +नीचे दिए गए आरेख में यह अवधारणा दृश्य रूप में है — टेक्स्ट अंदर जाता है, संख्यात्मक वेक्टर बाहर आते हैं, और समान अर्थ वाले वेक्टर पास-पास होते हैं: Embedding Model Concept -*यह चित्र दिखाता है कि कैसे एक एम्बेडिंग मॉडल टेक्स्ट को संख्यात्मक वेक्टर्स में परिवर्तित करता है, जिससे समान अर्थ जैसे "कार" और "ऑटोमोबाइल" वेक्टर स्पेस में एक-दूसरे के निकट स्थानित होते हैं।* +*यह आरेख दिखाता है कि कैसे एम्बेडिंग मॉडल टेक्स्ट को संख्यात्मक वेक्टर में परिवर्तित करता है, समान अर्थों को — जैसे "कार" और "ऑटोमोबाइल" — वेक्टर स्पेस में पास-पास रखता है।* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -नीचे क्लास डायरैक्ट दिखाता है कि RAG पाइपलाइन में दो अलग प्रवाह होते हैं और LangChain4j की कौन-कौन सी क्लासेज़ उन्हें लागू करती हैं। **इंजेशन फ्लो** (जो अपलोड के समय एक बार चलता है) दस्तावेज़ को विभाजित करता है, टुकड़ों को एम्बेड करता है, और `.addAll()` के माध्यम से उन्हें स्टोर करता है। **क्वेरी फ्लो** (जो हर बार उपयोगकर्ता प्रश्न पूछे जाता है) क्वेरी को एम्बेड करता है, स्टोर में `.search()` करता है, और मेल खाए हुए संदर्भ को चैट मॉडल को भेजता है। दोनों फ्लो एक साझा `EmbeddingStore` इंटरफेस पर मिलते हैं: + +निम्न वर्ग आरेख RAG पाइपलाइन में दो अलग-अलग प्रवाह और उन्हें लागू करने वाले LangChain4j वर्गों को दर्शाता है। **इंगेशन फ्लो** (जो अपलोड समय पर चलता है) दस्तावेज़ का विभाजन करता है, चंक्स को एम्बेड करता है, और `.addAll()` के माध्यम से संग्रह करता है। **क्वेरी फ्लो** (प्रत्येक बार जब उपयोगकर्ता पूछता है) प्रश्न को एम्बेड करता है, `.search()` के माध्यम से संग्रह को खोजता है, और मेल खाने वाले संदर्भ को चैट मॉडल को देता है। दोनों फ्लो एक साझा `EmbeddingStore` इंटरफ़ेस पर मिलते हैं: LangChain4j RAG Classes -*यह चित्र RAG पाइपलाइन में दो प्रवाह — इंजेशन और क्वेरी — दिखाता है और यह कि वे साझा EmbeddingStore के माध्यम से कैसे जुड़े हुए हैं।* +*यह आरेख RAG पाइपलाइन के दो प्रवाह दिखाता है — इंगेशन और क्वेरी — और कैसे वे एक साझा EmbeddingStore के माध्यम से जुड़ते हैं।* -एक बार एम्बेडिंग स्टोर हो जाने पर समान सामग्री स्वाभाविक रूप से वेक्टर स्पेस में क्लस्टर होती है। नीचे विज़ुअलाइज़ेशन दिखाता है कि संबंधित विषयों वाले दस्तावेज़ निकट बिंदुओं के रूप में समूहित होते हैं, जो सिमेंटिक खोज को संभव बनाता है: +एक बार एम्बेडिंग संग्रहित हो जाने के बाद, समान सामग्री स्वाभाविक रूप से वेक्टर स्पेस में समूहित हो जाती है। नीचे का दृश्य दिखाता है कि संबंधित विषयों वाले दस्तावेज़ पास-पास बिंदुओं के रूप में समाप्त होते हैं, जो सिमेंटिक सर्च को संभव बनाता है: Vector Embeddings Space -*यह विज़ुअलाइज़ेशन दिखाता है कि कैसे संबंधित दस्तावेज़ 3D वेक्टर स्पेस में समूहित होते हैं, जैसे टेक्निकल डॉक्स, बिजनेस रूल्स और FAQs अलग-अलग समूह बनाते हैं।* +*यह दृश्य दिखाता है कि कैसे संबंधित दस्तावेज़ 3D वेक्टर स्पेस में समूहित होते हैं, तकनीकी डाक्यूमेंट्स, व्यावसायिक नियम, और एफएक्यू जैसे विषय स्पष्ट समूह बनाते हैं।* -जब उपयोगकर्ता खोज करता है, तो सिस्टम चार चरणों का पालन करता है: दस्तावेजों को एक बार एम्बेड करता है, हर खोज पर क्वेरी को एम्बेड करता है, क्वेरी वेक्टर की तुलना कोसाइन सिमिलैरिटी के साथ सभी संग्रहीत वेक्टरों से करता है, और टॉप-के उच्चतम स्कोर वाले टुकड़े लौटाता है। नीचे चित्र हर चरण और LangChain4j क्लासेज़ को दिखाता है: +जब उपयोगकर्ता खोज करता है, सिस्टम चार चरणों का अनुसरण करता है: दस्तावेज़ों को एक बार एम्बेड करना, प्रत्येक खोज में क्वेरी को एम्बेड करना, कोशाइन समानता का उपयोग करके क्वेरी वेक्टर की तुलना सभी संग्रहित वेक्टरों से करना, और शीर्ष-K उच्च स्कोर वाले चंक्स लौटाना। नीचे आरेख में प्रत्येक चरण और LangChain4j वर्गों को दिखाया गया है: Embedding Search Steps -*यह चित्र चार-चरण एम्बेडिंग खोज प्रक्रिया दिखाता है: दस्तावेज़ एम्बेड करें, क्वेरी एम्बेड करें, कोसाइन सिमिलैरिटी से वेक्टर तुलना करें, और टॉप-के परिणाम लौटाएं।* +*यह आरेख चार-चरण एम्बेडिंग सर्च प्रक्रिया दिखाता है: दस्तावेज़ एम्बेड करें, क्वेरी एम्बेड करें, कोशाइन समानता से वेक्टरों की तुलना करें, और शीर्ष-K परिणाम लौटाएं।* -### Semantic Search +### सिमेंटिक सर्च [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -जब आप सवाल पूछते हैं, तो आपका सवाल भी एम्बेडिंग बन जाता है। सिस्टम आपके सवाल के एम्बेडिंग की तुलना दस्तावेज़ के सभी टुकड़ों के एम्बेडिंग से करता है। यह उन टुकड़ों को खोजता है जिनका अर्थ सबसे अधिक समान होता है - केवल मेल खाने वाले कीवर्ड नहीं, बल्कि वास्तविक सिमेंटिक समानता। +जब आप प्रश्न पूछते हैं, आपका प्रश्न भी एक एम्बेडिंग बन जाता है। सिस्टम आपके प्रश्न की एम्बेडिंग की तुलना सभी दस्तावेज़ चंक्स की एम्बेडिंग से करता है। यह उन चंक्स को ढूंढता है जिनका अर्थ सबसे समान होता है — केवल मिलते-जुलते कीवर्ड नहीं, बल्कि वास्तविक सैमेंटिक समानता। ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -नीचे चित्र सिमेंटिक खोज और पारंपरिक कीवर्ड खोज के बीच तुलना करता है। "vehicle" के लिए कीवर्ड खोज "cars and trucks" वाले टुकड़े को छोड़ देती है, लेकिन सिमेंटिक खोज समझती है कि उनका अर्थ समान है और उसे उच्च श्रेणी के मेल के रूप में लौटाती है: + +नीचे का आरेख पारंपरिक कीवर्ड खोज और सैमेंटिक खोज के बीच अंतर दिखाता है। "विकल्प" के लिए कीवर्ड खोज "कार और ट्रक" के बारे में एक चंक को मिस करती है, लेकिन सैमेंटिक खोज समझती है कि उनका अर्थ समान है और इसे उच्च स्कोर के साथ लौटाती है: Semantic Search -*यह चित्र कीवर्ड-आधारित खोज की तुलना सिमेंटिक खोज से करता है, दिखाता है कि सिमेंटिक खोज कैसे तब भी सैद्धांतिक रूप से संबंधित सामग्री पुनः प्राप्त करती है जब सटीक कीवर्ड भिन्न हों।* -Under the hood, similarity is measured using cosine similarity — essentially asking "are these two arrows pointing in the same direction?" Two chunks can use completely different words, but if they mean the same thing their vectors point the same way and score close to 1.0: +*यह आरेख कीवर्ड-आधारित खोज की तुलना सैमेंटिक खोज से करता है, दिखाता है कि सैमेंटिक खोज कैसे सैद्धांतिक रूप से संबंधित सामग्री पुनः प्राप्त करती है जब ठीक शब्द अलग होते हैं।* -Cosine Similarity +पर्दे के पीछे, समानता कोशाइन समानता का उपयोग करके मापी जाती है — मूलतः यह पूछती है "क्या ये दो तीर समान दिशा में इंगित करते हैं?" दो चंक्स पूरी तरह से अलग शब्दों का उपयोग कर सकते हैं, लेकिन यदि उनका अर्थ समान है तो उनके वेक्टर समान दिशा में होंगे और स्कोर 1.0 के करीब होगा: -*This diagram illustrates cosine similarity as the angle between embedding vectors — more aligned vectors score closer to 1.0, indicating higher semantic similarity.* +Cosine Similarity +*यह आरेख एम्बेडिंग वेक्टरों के बीच कोसाइन समानता को दर्शाता है — अधिक संरेखित वेक्टर 1.0 के करीब स्कोर करते हैं, जो उच्च सैमांतिक समानता सूचित करता है।* -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) and ask: -> - "How does similarity search work with embeddings and what determines the score?" -> - "What similarity threshold should I use and how does it affect results?" -> - "How do I handle cases where no relevant documents are found?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ आज़माएँ:** खोलें [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) और पूछें: +> - "एम्बेडिंग्स के साथ समानता खोज कैसे काम करती है और स्कोर क्या निर्धारित करता है?" +> - "मुझे कौन सा समानता थ्रेशोल्ड उपयोग करना चाहिए और यह परिणामों को कैसे प्रभावित करता है?" +> - "मैं उन मामलों को कैसे संभालूं जहाँ कोई प्रासंगिक दस्तावेज़ नहीं मिला?" -### Answer Generation +### उत्तर उत्पन्न करना [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -The most relevant chunks are assembled into a structured prompt that includes explicit instructions, the retrieved context, and the user's question. The model reads those specific chunks and answers based on that information — it can only use what's in front of it, which prevents hallucination. +सबसे प्रासंगिक खंडों को एक संरचित प्रोम्प्ट में एकत्रित किया जाता है जिसमें स्पष्ट निर्देश, पुनः प्राप्त संदर्भ, और उपयोगकर्ता का प्रश्न शामिल होता है। मॉडल उन विशिष्ट खंडों को पढ़ता है और उस जानकारी के आधार पर उत्तर देता है — यह केवल वही उपयोग कर सकता है जो उसके सामने है, जो भ्रम को रोकता है। ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -The diagram below shows this assembly in action — the top-scoring chunks from the search step are injected into the prompt template, and the `OpenAiOfficialChatModel` generates a grounded answer: +निचे दिया गया आरेख इस असेंबली को प्रदर्शित करता है — खोज चरण से शीर्ष स्कोर वाले खंडों को प्रोम्प्ट टेम्पलेट में इंजेक्ट किया जाता है, और `OpenAiOfficialChatModel` एक ठोस उत्तर उत्पन्न करता है: Context Assembly -*This diagram shows how the top-scoring chunks are assembled into a structured prompt, allowing the model to generate a grounded answer from your data.* +*यह आरेख दिखाता है कि कैसे शीर्ष स्कोर वाले खंडों को एक संरचित प्रोम्प्ट में जोड़ा जाता है, जिससे मॉडल आपके डेटा से आधारिक उत्तर उत्पन्न कर सकता है।* -## Run the Application +## एप्लिकेशन चलाएँ -**Verify deployment:** +**डिप्लॉयमेंट सत्यापित करें:** -Ensure the `.env` file exists in the root directory with Azure credentials (created during Module 01). Run this from the module directory (`03-rag/`): +सुनिश्‍चित करें कि रूट डायरेक्टरी में `.env` फ़ाइल मौजूद है जिसमें Azure प्रमाण-पत्र हैं (जो मॉड्यूल 01 के दौरान बनाई गई थी)। इसे मॉड्यूल डायरेक्टरी (`03-rag/`) से चलाएँ: **Bash:** ```bash @@ -259,43 +258,43 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दिखाना च Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दिखाना चाहिए ``` -**Start the application:** +**एप्लिकेशन शुरू करें:** -> **Note:** If you already started all applications using `./start-all.sh` from the root directory (as described in Module 01), this module is already running on port 8081. You can skip the start commands below and go directly to http://localhost:8081. +> **नोट:** यदि आपने पहले रूट डायरेक्टरी से `./start-all.sh` का उपयोग करके सभी एप्लिकेशन शुरू कर दिए हैं (जैसा कि मॉड्यूल 01 में बताया गया है), तो यह मॉड्यूल पहले से ही पोर्ट 8081 पर चल रहा है। आप नीचे दिए गए स्टार्ट कमांड छोड़ सकते हैं और सीधे http://localhost:8081 पर जा सकते हैं। -**Option 1: Using Spring Boot Dashboard (Recommended for VS Code users)** +**विकल्प 1: स्प्रिंग बूट डैशबोर्ड का उपयोग करें (VS कोड उपयोगकर्ताओं के लिए अनुशंसित)** -The dev container includes the Spring Boot Dashboard extension, which provides a visual interface to manage all Spring Boot applications. You can find it in the Activity Bar on the left side of VS Code (look for the Spring Boot icon). +डेव कंटेनर में स्प्रिंग बूट डैशबोर्ड एक्सटेंशन शामिल है, जो सभी स्प्रिंग बूट एप्लिकेशन को प्रबंधित करने के लिए एक दृश्य इंटरफेस प्रदान करता है। आप इसे VS कोड के बाएँ तरफ़ एक्टिविटी बार में पा सकते हैं (स्प्रिंग बूट आइकन देखें)। -From the Spring Boot Dashboard, you can: -- See all available Spring Boot applications in the workspace -- Start/stop applications with a single click -- View application logs in real-time -- Monitor application status +स्प्रिंग बूट डैशबोर्ड से आप: +- कार्यक्षेत्र में सभी उपलब्ध स्प्रिंग बूट एप्लिकेशन देख सकते हैं +- एक क्लिक में एप्लिकेशन शुरू/रोक सकते हैं +- वास्तविक समय में एप्लिकेशन लॉग देख सकते हैं +- एप्लिकेशन की स्थिति पर निगरानी रख सकते हैं -Simply click the play button next to "rag" to start this module, or start all modules at once. +बस "rag" के बगल में प्ले बटन पर क्लिक करें इस मॉड्यूल को शुरू करने के लिए, या सभी मॉड्यूल एक साथ शुरू करें। Spring Boot Dashboard -*This screenshot shows the Spring Boot Dashboard in VS Code, where you can start, stop, and monitor applications visually.* +*यह स्क्रीनशॉट VS कोड में स्प्रिंग बूट डैशबोर्ड दिखाता है, जहाँ आप एप्लिकेशन को दृश्य रूप से शुरू, रोक और मॉनिटर कर सकते हैं।* -**Option 2: Using shell scripts** +**विकल्प 2: शेल स्क्रिप्ट्स का उपयोग करें** -Start all web applications (modules 01-04): +सभी वेब एप्लिकेशन (मॉड्यूल 01-04) शुरू करें: **Bash:** ```bash -cd .. # मूल निर्देशिका से +cd .. # रूट डायरेक्टरी से ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # रूट निर्देशिका से +cd .. # रूट डायरेक्टरी से .\start-all.ps1 ``` -Or start just this module: +या सिर्फ़ इस मॉड्यूल को शुरू करें: **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Both scripts automatically load environment variables from the root `.env` file and will build the JARs if they don't exist. +दोनों स्क्रिप्ट्स स्वतः रूट `.env` फ़ाइल से पर्यावरण चर लोड करती हैं और यदि JARs मौजूद नहीं हैं तो उन्हें बनाएंगी। -> **Note:** If you prefer to build all modules manually before starting: +> **नोट:** यदि आप शुरू करने से पहले सभी मॉड्यूल्स को मैन्युअली बनाना पसंद करते हैं: > > **Bash:** > ```bash @@ -325,13 +324,13 @@ Both scripts automatically load environment variables from the root `.env` file > mvn clean package -DskipTests > ``` -Open http://localhost:8081 in your browser. +अपने ब्राउज़र में http://localhost:8081 खोलें। -**To stop:** +**रोकने के लिए:** **Bash:** ```bash -./stop.sh # केवल यह मॉड्यूल +./stop.sh # यह मॉड्यूल केवल # या cd .. && ./stop-all.sh # सभी मॉड्यूल्स ``` @@ -343,95 +342,95 @@ cd .. && ./stop-all.sh # सभी मॉड्यूल्स cd ..; .\stop-all.ps1 # सभी मॉड्यूल ``` -## Using the Application +## एप्लिकेशन का उपयोग करना -The application provides a web interface for document upload and questioning. +यह एप्लिकेशन दस्तावेज़ अपलोड और प्रश्न पूछने के लिए एक वेब इंटरफ़ेस प्रदान करता है। RAG Application Interface -*This screenshot shows the RAG application interface where you upload documents and ask questions.* +*यह स्क्रीनशॉट RAG एप्लिकेशन इंटरफ़ेस को दिखाता है जहाँ आप दस्तावेज़ अपलोड करते हैं और प्रश्न पूछते हैं।* -### Upload a Document +### एक दस्तावेज़ अपलोड करें -Start by uploading a document - TXT files work best for testing. A `sample-document.txt` is provided in this directory that contains information about LangChain4j features, RAG implementation, and best practices - perfect for testing the system. +एक दस्तावेज़ अपलोड करके शुरू करें - परीक्षण के लिए TXT फाइलें सबसे अच्छी हैं। इस डायरेक्टरी में `sample-document.txt` उपलब्ध है जिसमें LangChain4j फीचर्स, RAG इम्प्लिमेंटेशन, और सर्वोत्तम प्रथाओं की जानकारी है - सिस्टम परीक्षण के लिए उपयुक्त। -The system processes your document, breaks it into chunks, and creates embeddings for each chunk. This happens automatically when you upload. +सिस्टम आपके दस्तावेज़ को प्रोसेस करता है, उसे खंडों में तोड़ता है, और प्रत्येक खंड के लिए एम्बेडिंग बनाता है। यह सब आपके अपलोड करते ही स्वतः हो जाता है। -### Ask Questions +### प्रश्न पूछें -Now ask specific questions about the document content. Try something factual that's clearly stated in the document. The system searches for relevant chunks, includes them in the prompt, and generates an answer. +अब दस्तावेज़ सामग्री के बारे में विशिष्ट प्रश्न पूछें। कुछ तथ्यों के बारे में पूछें जो स्पष्ट रूप से दस्तावेज़ में बताए गए हों। सिस्टम प्रासंगिक खंड खोजता है, उन्हें प्रोम्प्ट में शामिल करता है, और उत्तर उत्पन्न करता है। -### Check Source References +### स्रोत संदर्भ जांचें -Notice each answer includes source references with similarity scores. These scores (0 to 1) show how relevant each chunk was to your question. Higher scores mean better matches. This lets you verify the answer against the source material. +ध्यान दें कि प्रत्येक उत्तर के साथ स्रोत संदर्भ और समानता स्कोर भी शामिल होते हैं। ये स्कोर (0 से 1 तक) दिखाते हैं कि आपका प्रश्न हर खंड के लिए कितना प्रासंगिक था। उच्च स्कोर बेहतर मेल के संकेत हैं। इससे आप स्रोत सामग्री के खिलाफ उत्तर की पुष्टि कर सकते हैं। RAG Query Results -*This screenshot shows query results with the generated answer, source references, and relevance scores for each retrieved chunk.* +*यह स्क्रीनशॉट क्वेरी परिणाम दिखाता है जिसमें उत्पन्न उत्तर, स्रोत संदर्भ, और प्रत्येक पुनः प्राप्त खंड के लिए प्रासंगिकता स्कोर शामिल हैं।* -### Experiment with Questions +### प्रश्नों के साथ प्रयोग करें -Try different types of questions: -- Specific facts: "What is the main topic?" -- Comparisons: "What's the difference between X and Y?" -- Summaries: "Summarize the key points about Z" +विभिन्न प्रकार के प्रश्न आजमाएं: +- विशिष्ट तथ्य: "मुख्य विषय क्या है?" +- तुलना: "X और Y में क्या अंतर है?" +- सारांश: "Z के बारे में मुख्य बिंदु संक्षेप करें" -Watch how the relevance scores change based on how well your question matches document content. +देखें कि आपकी प्रश्न के अनुसार प्रासंगिकता स्कोर कैसे बदलते हैं। -## Key Concepts +## मुख्य अवधारणाएँ -### Chunking Strategy +### खंडन रणनीति -Documents are split into 300-token chunks with 30 tokens of overlap. This balance ensures each chunk has enough context to be meaningful while staying small enough to include multiple chunks in a prompt. +दस्तावेज़ों को 300-टोकन के खंडों में विभाजित किया जाता है जिसमें 30 टोकन का ओवरलैप होता है। यह संतुलन सुनिश्चित करता है कि प्रत्येक खंड में पर्याप्त संदर्भ हो ताकि वह सार्थक हो, लेकिन इतना बड़ा न हो कि एक प्रोम्प्ट में कई खंड शामिल न कर सकें। -### Similarity Scores +### समानता स्कोर -Every retrieved chunk comes with a similarity score between 0 and 1 that indicates how closely it matches the user's question. The diagram below visualizes the score ranges and how the system uses them to filter results: +प्रत्येक पुनः प्राप्त खंड का उपयोगकर्ता के प्रश्न के साथ मेल खाने का समानता स्कोर 0 से 1 के बीच होता है। निचे दिया गया आरेख स्कोर सीमा दर्शाता है और सिस्टम कैसे उन्हें परिणाम फ़िल्टर करने के लिए उपयोग करता है: Similarity Scores -*This diagram shows score ranges from 0 to 1, with a minimum threshold of 0.5 that filters out irrelevant chunks.* +*यह आरेख 0 से 1 तक के स्कोर रेंज दिखाता है, जिसमें न्यूनतम थ्रेशोल्ड 0.5 है जो अप्रासंगिक खंडों को छानता है।* -Scores range from 0 to 1: -- 0.7-1.0: Highly relevant, exact match -- 0.5-0.7: Relevant, good context -- Below 0.5: Filtered out, too dissimilar +स्कोर 0 से 1 तक होते हैं: +- 0.7-1.0: अत्यंत प्रासंगिक, सटीक मेल +- 0.5-0.7: प्रासंगिक, अच्छा संदर्भ +- 0.5 से नीचे: फ़िल्टर आउट, बहुत असंबंधित -The system only retrieves chunks above the minimum threshold to ensure quality. +सिस्टम गुणवत्ता सुनिश्चित करने के लिए केवल न्यूनतम थ्रेशोल्ड से ऊपर के खंड पुनः प्राप्त करता है। -Embeddings work well when meaning clusters cleanly, but they have blind spots. The diagram below shows the common failure modes — chunks that are too large produce muddy vectors, chunks that are too small lack context, ambiguous terms point to multiple clusters, and exact-match lookups (IDs, part numbers) don't work with embeddings at all: +एम्बेडिंग्स तब अच्छा काम करती हैं जब अर्थ स्पष्ट रूप से विभाजित हो, लेकिन उनकी सीमाएँ होती हैं। नीचे दिया गया आरेख सामान्य विफलता मोड दिखाता है — बहुत बड़े खंड धुंधले वेक्टर बनाते हैं, बहुत छोटे खंडों में संदर्भ की कमी होती है, अस्पष्ट शब्द कई समूहों की ओर संकेत करते हैं, और सटीक मिलान खोज (आईडी, पार्ट नंबर) एम्बेडिंग्स के साथ काम नहीं करती: Embedding Failure Modes -*This diagram shows common embedding failure modes: chunks too large, chunks too small, ambiguous terms that point to multiple clusters, and exact-match lookups like IDs.* +*यह आरेख सामान्य एम्बेडिंग विफलता मोड दिखाता है: बहुत बड़े खंड, बहुत छोटे खंड, अस्पष्ट शब्द जो कई समूहों की ओर संकेत करते हैं, और आईडी जैसे सटीक मिलान खोज।* -### In-Memory Storage +### इन-मेमोरी स्टोरेज -This module uses in-memory storage for simplicity. When you restart the application, uploaded documents are lost. Production systems use persistent vector databases like Qdrant or Azure AI Search. +यह मॉड्यूल सरलता के लिए मेमोरी में संग्रहण का उपयोग करता है। जब आप एप्लिकेशन को पुनः प्रारंभ करते हैं, तो अपलोड किए गए दस्तावेज़ खो जाते हैं। प्रोडक्शन सिस्टम स्थायी वेक्टर डेटाबेस जैसे Qdrant या Azure AI Search का उपयोग करते हैं। -### Context Window Management +### संदर्भ विंडो प्रबंधन -Each model has a maximum context window. You can't include every chunk from a large document. The system retrieves the top N most relevant chunks (default 5) to stay within limits while providing enough context for accurate answers. +प्रत्येक मॉडल के पास अधिकतम संदर्भ विंडो होती है। आप बड़ी दस्तावेज़ से हर खंड शामिल नहीं कर सकते। सिस्टम शीर्ष N सबसे प्रासंगिक खंड (डिफ़ॉल्ट 5) पुनः प्राप्त करता है ताकि सीमा के भीतर रहकर पर्याप्त संदर्भ प्रदान कर सके और सटीक उत्तर दे सके। -## When RAG Matters +## जब RAG महत्वपूर्ण होता है -RAG isn't always the right approach. The decision guide below helps you determine when RAG adds value versus when simpler approaches — like including content directly in the prompt or relying on the model's built-in knowledge — are sufficient: +RAG हमेशा सही विकल्प नहीं होता। नीचे दिया गया निर्णय गाइड आपको यह निर्धारित करने में मदद करता है कि कब RAG मूल्य जोड़ता है और कब सरल दृष्टिकोण — जैसे सीधे प्रोम्प्ट में सामग्री शामिल करना या मॉडल के अंतर्निर्मित ज्ञान पर निर्भर रहना — पर्याप्त होता है: When to Use RAG -*This diagram shows a decision guide for when RAG adds value versus when simpler approaches are sufficient.* +*यह आरेख निर्णय गाइड दिखाता है कि कब RAG मूल्य जोड़ता है और कब सरल दृष्टिकोण पर्याप्त हैं।* -## Next Steps +## अगले कदम -**Next Module:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**अगला मॉड्यूल:** [04-tools - टूल्स के साथ AI एजेंट](../04-tools/README.md) --- -**Navigation:** [← Previous: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Back to Main](../README.md) | [Next: Module 04 - Tools →](../04-tools/README.md) +**नेविगेशन:** [← पिछला: मॉड्यूल 02 - प्रॉम्प्ट इंजीनियरिंग](../02-prompt-engineering/README.md) | [मुख्य पृष्ठ पर वापस जाएं](../README.md) | [अगला: मॉड्यूल 04 - टूल्स →](../04-tools/README.md) --- **अस्वीकरण**: -इस दस्तावेज़ का अनुवाद एआई अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। हम सटीकता के लिए प्रयासरत हैं, लेकिन कृपया ध्यान रखें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मातृभाषा में ही अधिकारिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए पेशेवर मानव अनुवाद की सलाह दी जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या भ्रांतियों के लिए हम जिम्मेदार नहीं हैं। +इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। \ No newline at end of file diff --git a/translations/hi/04-tools/README.md b/translations/hi/04-tools/README.md index 2d03d7652..cb322e8e6 100644 --- a/translations/hi/04-tools/README.md +++ b/translations/hi/04-tools/README.md @@ -1,84 +1,84 @@ -# माड्यूल 04: टूल्स के साथ AI एजेंट्स +# Module 04: उपकरणों के साथ एआई एजेंट ## विषय सूची -- [विडियो वॉकथ्रू](../../../04-tools) -- [आप क्या सीखेंगे](../../../04-tools) -- [पूर्वापेक्षाएँ](../../../04-tools) -- [टूल्स के साथ AI एजेंट्स को समझना](../../../04-tools) -- [टूल कॉलिंग कैसे काम करता है](../../../04-tools) - - [टूल परिभाषाएं](../../../04-tools) - - [निर्णय लेना](../../../04-tools) - - [कार्यान्वयन](../../../04-tools) - - [प्रतिक्रिया निर्माण](../../../04-tools) - - [आर्किटेक्चर: स्प्रिंग बूट ऑटो-वायरिंग](../../../04-tools) -- [टूल चेनिंग](../../../04-tools) -- [एप्लिकेशन चलाएँ](../../../04-tools) -- [एप्लिकेशन का उपयोग करना](../../../04-tools) - - [सरल टूल उपयोग आज़माएँ](../../../04-tools) - - [टेस्ट टूल चेनिंग](../../../04-tools) - - [बातचीत प्रवाह देखें](../../../04-tools) - - [विभिन्न अनुरोधों के साथ प्रयोग करें](../../../04-tools) -- [प्रमुख अवधारणाएं](../../../04-tools) - - [ReAct पैटर्न (तर्क और क्रिया)](../../../04-tools) - - [टूल विवरण महत्वपूर्ण हैं](../../../04-tools) - - [सत्र प्रबंधन](../../../04-tools) - - [त्रुटि प्रबंधन](../../../04-tools) -- [उपलब्ध टूल्स](../../../04-tools) -- [टूल-आधारित एजेंट कब उपयोग करें](../../../04-tools) -- [टूल्स बनाम RAG](../../../04-tools) -- [अगले कदम](../../../04-tools) +- [वीडियो वॉकथ्रू](#वीडियो-वॉकथ्रू) +- [आप क्या सीखेंगे](#आप-क्या-सीखेंगे) +- [पूर्व आवश्यकताएँ](#पूर्व-आवश्यकताएँ) +- [उपकरणों के साथ एआई एजेंट को समझना](#उपकरणों-के-साथ-एआई-एजेंट-को-समझना) +- [उपकरण कॉलिंग कैसे काम करती है](#उपकरण-कॉलिंग-कैसे-काम-करती-है) + - [उपकरण परिभाषाएँ](#उपकरण-परिभाषाएँ) + - [निर्णय लेना](#निर्णय-लेना) + - [कार्यान्वयन](#कार्यान्वयन) + - [प्रतिक्रिया उत्पादन](#प्रतिक्रिया-उत्पादन) + - [आर्किटेक्चर: स्प्रिंग बूट ऑटो-वायरिंग](#आर्किटेक्चर-स्प्रिंग-बूट-ऑटो-वायरिंग) +- [उपकरण श्रृंखला](#उपकरण-श्रृंखला) +- [एप्लिकेशन चलाएँ](#एप्लिकेशन-चलाएँ) +- [एप्लिकेशन का उपयोग करना](#एप्लिकेशन-का-उपयोग-करना) + - [सरल उपकरण उपयोग प्रयास करें](#सरल-टूल-उपयोग-आज़माएं) + - [उपकरण श्रृंखला का परीक्षण करें](#टूल-चेनिंग-का-परीक्षण-करें) + - [संवाद प्रवाह देखें](#बातचीत-के-प्रवाह-को-देखें) + - [विभिन्न अनुरोधों के साथ प्रयोग करें](#विभिन्न-अनुरोधों-के-साथ-प्रयोग-करें) +- [मुख्य अवधारणाएँ](#मुख्य-अवधारणाएँ) + - [ReAct पैटर्न (तर्क और क्रिया)](#react-पैटर्न-तर्क-और-क्रिया) + - [उपकरण विवरण महत्वपूर्ण हैं](#टूल-विवरण-महत्वपूर्ण-हैं) + - [सत्र प्रबंधन](#सत्र-प्रबंधन) + - [त्रुटि प्रबंधन](#त्रुटि-प्रबंधन) +- [उपलब्ध उपकरण](#उपलब्ध-टूल्स) +- [कब उपकरण-आधारित एजेंट का उपयोग करें](#कब-टूल-आधारित-एजेंट-का-उपयोग-करें) +- [उपकरण बनाम RAG](#टूल्स-बनाम-rag) +- [अगले चरण](#आगे-के-कदम) ## वीडियो वॉकथ्रू -इस लाइव सेशन को देखें जो बताता है कि इस माड्यूल के साथ कैसे शुरू करें: +इस लाइव सत्र को देखें जो बताता है कि इस मॉड्यूल की शुरुआत कैसे करें: AI Agents with Tools and MCP - Live Session ## आप क्या सीखेंगे -अब तक, आपने सीखा है कि AI के साथ बातचीत कैसे करनी है, प्रभावी प्रम्प्ट कैसे बनाएं, और अपने दस्तावेज़ों में जवाबों को आधारभूत कैसे करें। लेकिन एक मौलिक सीमा अभी भी है: भाषा मॉडल केवल टेक्स्ट जनरेट कर सकते हैं। वे मौसम की जाँच नहीं कर सकते, गणना नहीं कर सकते, डेटाबेस क्वेरी नहीं कर सकते, या बाहरी सिस्टम के साथ इंटरैक्ट नहीं कर सकते। +अब तक, आपने सीखा है कि AI के साथ बातचीत कैसे करनी है, प्रभावी रूप से प्रॉम्प्ट कैसे बनाना है, और अपने दस्तावेज़ों में प्रतिक्रियाओं का आधार कैसे रखना है। लेकिन एक मूलभूत सीमा अभी भी है: भाषा मॉडल केवल टेक्स्ट जनरेट कर सकते हैं। वे मौसम जांच नहीं सकते, गणना नहीं कर सकते, डेटाबेस क्वेरी नहीं कर सकते, या बाहरी सिस्टम से इंटरैक्ट नहीं कर सकते। -टूल्स इसे बदल देते हैं। मॉडल को उन फंक्शन्स तक पहुँच देने से जिन्हें वह कॉल कर सकता है, आप इसे एक टेक्स्ट जनरेटर से उस एजेंट में बदल देते हैं जो क्रियाएं कर सकता है। मॉडल निर्णय लेता है कि उसे कब टूल की जरूरत है, कौन सा टूल उपयोग करना है, और कौन से पैरामीटर पास करने हैं। आपका कोड फंक्शन को निष्पादित करता है और परिणाम लौटाता है। मॉडल उस परिणाम को अपनी प्रतिक्रिया में समाहित करता है। +उपकरण इस बात को बदल देते हैं। मॉडल को उन फंक्शंस तक पहुँच देकर जिन्हें वह कॉल कर सकता है, आप इसे एक टेक्स्ट जनरेटर से ऐसे एजेंट में बदल देते हैं जो कार्रवाई कर सकता है। मॉडल तय करता है कि इसे कब उपकरण चाहिए, किस उपकरण का उपयोग करना है, और कौन से पैरामीटर पास करने हैं। आपका कोड फंक्शन को निष्पादित करता है और परिणाम लौटाता है। मॉडल उस परिणाम को अपनी प्रतिक्रिया में सम्मिलित करता है। -## पूर्वापेक्षाएँ +## पूर्व आवश्यकताएँ -- पूरा हुआ [माड्यूल 01 - परिचय](../01-introduction/README.md) (Azure OpenAI संसाधन तैनात) -- पहले के माड्यूल्स पूरा करना सुझाया गया (यह माड्यूल [माड्यूल 03 के RAG कॉन्सेप्ट्स](../03-rag/README.md) का संदर्भ देता है टूल्स vs RAG तुलना में) -- रूट डायरेक्टरी में `.env` फ़ाइल जिसमें Azure क्रेडेंशियल्स हैं (माड्यूल 01 में `azd up` से बनाई गई) +- पूरा किया हुआ [Module 01 - परिचय](../01-introduction/README.md) (Azure OpenAI संसाधन तैनात किए गए) +- पिछले मॉड्यूल्स को पूरा करना अनुशंसित (यह मॉड्यूल टूल्स बनाम RAG तुलना में [मॉड्यूल 03 के RAG अवधारणाओं](../03-rag/README.md) का संदर्भ देता है) +- रूट डायरेक्टरी में `.env` फ़ाइल Azure क्रेडेंशियल के साथ (Module 01 में `azd up` द्वारा बनाई गई) -> **नोट:** यदि आपने माड्यूल 01 पूरा नहीं किया है, तो पहले वहाँ तैनाती निर्देशों का पालन करें। +> **नोट:** यदि आपने Module 01 पूरा नहीं किया है, तो पहले वहाँ तैनाती निर्देशों का पालन करें। -## टूल्स के साथ AI एजेंट्स को समझना +## उपकरणों के साथ एआई एजेंट को समझना -> **📝 नोट:** इस माड्यूल में "एजेंट्स" शब्द से तात्पर्य AI असिस्टेंट्स से है जो टूल-कॉलिंग क्षमताओं से संवर्धित हैं। यह अलग है **Agentic AI** पैटर्न से (स्वायत्त एजेंट्स जिनमें योजना, मेमोरी, और मल्टी-स्टेप तर्क शामिल हैं) जिन्हें हम [माड्यूल 05: MCP](../05-mcp/README.md) में कवर करेंगे। +> **📝 नोट:** इस मॉड्यूल में "एजेंट" शब्द उन एआई सहायक को संदर्भित करता है जो उपकरण कॉलिंग क्षमताओं के साथ बढ़ाए गए हैं। यह अलग है उन **Agentic AI** पैटर्न से (स्वायत्त एजेंट जिनके पास योजना, मेमोरी, और बहु-चरण तर्क होते हैं) जिन्हें हम [Module 05: MCP](../05-mcp/README.md) में कवर करेंगे। -बिना टूल्स के, एक भाषा मॉडल केवल अपने प्रशिक्षण डेटा से टेक्स्ट जनरेट कर सकता है। यदि आप उससे वर्तमान मौसम पूछें, तो वह अनुमान लगाने को मजबूर है। टूल दें और वह मौसम API कॉल कर सकता है, गणना कर सकता है, या डेटाबेस से क्वेरी कर सकता है — फिर उन वास्तविक परिणामों को अपनी प्रतिक्रिया में शामिल करता है। +बिना उपकरणों के, भाषा मॉडल केवल अपने प्रशिक्षण डेटा से टेक्स्ट जेनरेट कर सकता है। वर्तमान मौसम पूछिए, तो उसे अनुमान लगाना होता है। उपकरण दें, और वह मौसम API कॉल कर सकता है, गणना कर सकता है, या डेटाबेस क्वेरी कर सकता है — फिर उन असली परिणामों को अपनी प्रतिक्रिया में बुन सकता है। Without Tools vs With Tools -*बिना टूल्स मॉडल केवल अनुमान लगा सकता है — टूल्स के साथ वह API कॉल कर सकता है, गणना कर सकता है, और रियल-टाइम डेटा लौटाता है।* +*बिना उपकरणों मॉडल केवल अनुमान लगाता है — उपकरणों के साथ यह APIs कॉल कर सकता है, गणना चला सकता है, और वास्तविक समय डेटा वापस कर सकता है।* -टूल्स वाले AI एजेंट एक **Reasoning and Acting (ReAct)** पैटर्न का पालन करते हैं। मॉडल केवल जवाब नहीं देता — यह सोचता है कि उसे क्या चाहिए, एक टूल कॉल करता है, परिणाम देखता है, फिर फैसला करता है कि फिर से कार्य करना है या अंतिम उत्तर देना है: +उपकरणों के साथ एक AI एजेंट एक **Reasoning and Acting (ReAct)** पैटर्न का पालन करता है। मॉडल केवल प्रतिक्रिया नहीं देता — यह सोचता है कि उसे क्या चाहिए, एक उपकरण को कॉल करके कार्य करता है, परिणाम देखता है, और फिर तय करता है कि फिर से कार्य करना है या अंतिम उत्तर देना है: -1. **तर्क करें** — एजेंट उपयोगकर्ता के प्रश्न का विश्लेषण करता है और निर्धारित करता है कि उसे क्या जानकारी चाहिए -2. **क्रिया करें** — एजेंट सही टूल चुनता है, सही पैरामीटर जनरेट करता है, और उसे कॉल करता है -3. **निरीक्षण करें** — एजेंट टूल के आउटपुट को प्राप्त करता है और परिणाम का मूल्यांकन करता है -4. **दोहराएँ या उत्तर दें** — यदि और डेटा की जरूरत है तो एजेंट पुनः लूप करता है; अन्यथा, वह प्राकृतिक भाषा में उत्तर तैयार करता है +1. **तर्क करना** — एजेंट उपयोगकर्ता के प्रश्न का विश्लेषण करता है और यह निर्धारित करता है कि उसे क्या जानकारी चाहिए +2. **कार्य करना** — एजेंट सही उपकरण चुनता है, सही पैरामीटर बनाता है, और उसे कॉल करता है +3. **पर्यवेक्षण करना** — एजेंट उपकरण की आउटपुट प्राप्त करता है और परिणाम का मूल्यांकन करता है +4. **दोहराना या उत्तर देना** — यदि और डेटा चाहिए, तो एजेंट लूप करता है; अन्यथा, संवादात्मक भाषा में उत्तर तैयार करता है ReAct Pattern -*ReAct चक्र — एजेंट तय करता है कि क्या करना है, टूल कॉल करके क्रिया करता है, परिणाम देखता है, और तब तक लूप करता है जब तक अंतिम उत्तर दे न सके।* +*ReAct चक्र — एजेंट सोचता है कि क्या करना है, उपकरण कॉल करके कार्य करता है, परिणाम देखता है, और तब तक लूप करता है जब तक अंतिम उत्तर नहीं दे सकता।* -यह स्वचालित होता है। आप टूल्स और उनके विवरण परिभाषित करते हैं। मॉडल निर्णय लेता है कि उन्हें कब और कैसे उपयोग करना है। +यह स्वचालित होता है। आप उपकरण और उनके विवरण परिभाषित करते हैं। मॉडल निर्णय लेता है कि इन्हें कब और कैसे उपयोग करना है। -## टूल कॉलिंग कैसे काम करता है +## उपकरण कॉलिंग कैसे काम करती है -### टूल परिभाषाएं +### उपकरण परिभाषाएँ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -आप स्पष्ट विवरणों और पैरामीटर विनिर्देशों के साथ फंक्शन्स परिभाषित करते हैं। मॉडल अपने सिस्टम प्रम्प्ट में इन विवरणों को देखता है और समझता है कि हर टूल क्या करता है। +आप स्पष्ट विवरण और पैरामीटर विनिर्देशों के साथ פונ्क्शंस परिभाषित करते हैं। मॉडल अपने सिस्टम प्रॉम्प्ट में इन विवरणों को देखता है और समझता है कि प्रत्येक उपकरण क्या करता है। ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // आपकी मौसम खोज तर्क + // आपका मौसम खोज तर्क return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// सहायक स्वचालित रूप से Spring Boot द्वारा कनेक्ट किया गया है: -// - ChatModel बीन -// - @Component वर्गों की सभी @Tool विधियाँ +// सहायक स्वचालित रूप से स्प्रिंग बूट द्वारा वायर किया गया है: +// - चैटमॉडल बीन +// - @Component कक्षाओं से सभी @Tool मेथड // - सत्र प्रबंधन के लिए ChatMemoryProvider ``` -नीचे दिया गया आरेख हर एनोटेशन को तोड़ता है और दिखाता है कि AI को कब टूल कॉल करना है और कौन से तर्क पास करने हैं, यह कैसे समझ आता है: +नीचे वाला आरेख प्रत्येक एनोटेशन को तोड़ता है और दिखाता है कि कैसे हर हिस्सा AI को यह समझने में मदद करता है कि कब उपकरण कॉल करना है और कौन से तर्क पास करना हैं: Anatomy of Tool Definitions -*टूल परिभाषा की संरचना — @Tool AI को बताता है कि कब उपयोग करना है, @P प्रत्येक पैरामीटर का वर्णन करता है, और @AiService सब कुछ स्टार्टअप पर जोड़ता है।* +*उपकरण परिभाषा की संरचना — @Tool AI को बताता है कि इसे कब उपयोग करना है, @P प्रत्येक पैरामीटर का वर्णन करता है, और @AiService शुरूआत में सब कुछ वायर करता है।* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ आज़माएँ:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) खोलें और पूछें: -> - "मॉक डेटा की जगह असली OpenWeatherMap API को कैसे जोड़ा जाए?" -> - "एक अच्छा टूल विवरण क्या होता है जो AI को सही उपयोग में मदद करता है?" -> - "टूल इम्प्लीमेंटेशन में API त्रुटियों और रेट लिमिट्स को कैसे संभालें?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat के साथ प्रयास करें:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) खोलें और पूछें: +> - "मैं नकली डेटा की बजाय OpenWeatherMap जैसा वास्तविक मौसम API कैसे इंटीग्रेट करूं?" +> - "एक अच्छा उपकरण विवरण क्या है जो AI को इसे सही उपयोग करने में मदद करता है?" +> - "API त्रुटियां और रेट लिमिट्स को उपकरण कार्यान्वयन में कैसे हैंडल करें?" ### निर्णय लेना -जब कोई उपयोगकर्ता पूछता है "सीएटल में मौसम क्या है?", तो मॉडल यादृच्छिक टूल नहीं चुनता। यह उपयोगकर्ता की मंशा की तुलना उपलब्ध टूल विवरणों से करता है, प्रत्येक का प्रासंगिकता के लिए स्कोर बनाता है, और सबसे उपयुक्त चुनता है। फिर यह सही पैरामीटर के साथ एक संरचित फंक्शन कॉल बनाता है – इस केस में, `location` को `"Seattle"` सेट करता है। +जब कोई उपयोगकर्ता पूछता है "Seattle में मौसम कैसा है?", तो मॉडल कोई उपकरण यादृच्छिक रूप से नहीं चुनता। यह उपयोगकर्ता के इरादे की तुलना अपने हर उपकरण विवरण से करता है, प्रासंगिकता के लिए स्कोर करता है, और सबसे उपयुक्त चयन करता है। फिर यह सही पैरामीटर के साथ संरचित फंक्शन कॉल बनाता है — इस मामले में, `location` को `"Seattle"` सेट करना। -यदि कोई टूल उपयोगकर्ता के अनुरोध से मेल नहीं खाता, तो मॉडल अपने ज्ञान से जवाब देता है। यदि कई टूल मैच करते हैं, तो वह सबसे विशिष्ट चुनता है। +अगर कोई उपकरण उपयोगकर्ता के अनुरोध से मेल नहीं खाता, तो मॉडल अपने ज्ञान से उत्तर देता है। यदि कई उपकरण मेल खाते हैं, तो यह सबसे विशिष्ट चुनता है। How the AI Decides Which Tool to Use -*मॉडल हर उपलब्ध टूल का उपयोगकर्ता की मंशा के खिलाफ मूल्यांकन करता है और सबसे उपयुक्त चुनता है — इसलिए स्पष्ट, विशिष्ट टूल विवरण लिखना महत्वपूर्ण है।* +*मॉडल हर उपलब्ध उपकरण का उपयोगकर्ता के इरादे से मूल्यांकन करता है और सबसे उपयुक्त चुनता है — इसलिए स्पष्ट, विशिष्ट उपकरण विवरण लिखना महत्वपूर्ण है।* ### कार्यान्वयन [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -स्प्रिंग बूट डिक्लेरेटिव `@AiService` इंटरफेस के साथ सभी पंजीकृत टूल्स को ऑटो-वायर करता है, और LangChain4j स्वचालित रूप से टूल कॉल्स निष्पादित करता है। पर्दे के पीछे, एक टूल कॉल छह चरणों में प्रवाहित होती है — उपयोगकर्ता के प्राकृतिक भाषा प्रश्न से लेकर प्राकृतिक भाषा उत्तर तक: +स्प्रिंग बूट डिक्लेरेटिव `@AiService` इंटरफेस को सभी पंजीकृत उपकरणों के साथ ऑटो-वायर करता है, और LangChain4j स्वचालित रूप से उपकरण कॉल निष्पादित करता है। पर्दे के पीछे, एक पूरा उपकरण कॉल छह चरणों से गुजरता है — उपयोगकर्ता के संवादात्मक प्रश्न से लेकर वापस संवादात्मक उत्तर तक: Tool Calling Flow -*अंत-से-अंत प्रवाह — उपयोगकर्ता प्रश्न पूछता है, मॉडल टूल चुनता है, LangChain4j इसे निष्पादित करता है, और मॉडल परिणाम को प्राकृतिक प्रतिक्रिया में पिरोता है।* +*एंड-टू-एंड फ्लो — उपयोगकर्ता प्रश्न पूछता है, मॉडल उपकरण चुनता है, LangChain4j उसे निष्पादित करता है, और मॉडल परिणाम को प्राकृतिक प्रतिक्रिया में वेव करता है।* -यदि आपने माड्यूल 00 में [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) चलाया, तो आपने यह पैटर्न देखा होगा — `Calculator` टूल्स भी इसी तरह कॉल होते थे। नीचे सिक्वेंस डायग्राम में दिखाया गया है कि उस डेमो के दौरान क्या हुआ: +पर्दे के पीछे, `AiServices` किसी भी उपकरण के लिए वही उपकरण-कॉलिंग लूप चलाता है — यहाँ एक सरल `Calculator` से चित्रित किया गया है। नीचे अनुक्रम आरेख दिखाता है कि अंदर क्या होता है: Tool Calling Sequence Diagram -*क्विक स्टार्ट डेमो से टूल-कॉलिंग लूप — `AiServices` आपका संदेश और टूल स्कीमास LLM को भेजता है, LLM `add(42, 58)` जैसे फंक्शन कॉल के साथ जवाब देता है, LangChain4j स्थानीय रूप से `Calculator` मेथड चलाता है, और परिणाम अंतिम उत्तर के लिए वापस भेजता है।* +*उपकरण-कॉलिंग लूप — `AiServices` आपका संदेश और उपकरण स्कीमा LLM को भेजता है, LLM एक `add(42, 58)` जैसे फंक्शन कॉल के साथ जवाब देता है, LangChain4j स्थानीय रूप से `Calculator` मेथड को निष्पादित करता है, और अंतिम उत्तर के लिए परिणाम वापस देता है।* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चैट के साथ आज़माएँ:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) खोलें और पूछें: +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat के साथ प्रयास करें:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) खोलें और पूछें: > - "ReAct पैटर्न कैसे काम करता है और AI एजेंट्स के लिए यह क्यों प्रभावी है?" -> - "एजेंट यह कैसे तय करता है कि कौन सा टूल कब उपयोग करना है?" -> - "यदि टूल निष्पादन विफल हो जाए तो क्या होता है - त्रुटियों को मजबूत तरीके से कैसे संभालें?" +> - "एजेंट कैसे तय करता है कि कौन सा उपकरण उपयोग करना है और किस क्रम में?" +> - "अगर उपकरण निष्पादन विफल हो जाए तो क्या होता है - मैं त्रुटियों को मजबूती से कैसे संभालूं?" -### प्रतिक्रिया निर्माण +### प्रतिक्रिया उत्पादन -मॉडल मौसम डेटा प्राप्त करता है और उसे उपयोगकर्ता के लिए प्राकृतिक भाषा प्रतिक्रिया में फॉर्मेट करता है। +मॉडल मौसम डेटा प्राप्त करता है और उसे उपयोगकर्ता के लिए प्राकृतिक भाषा प्रतिक्रिया में रूपांतरित करता है। ### आर्किटेक्चर: स्प्रिंग बूट ऑटो-वायरिंग -यह माड्यूल LangChain4j के स्प्रिंग बूट इंटीग्रेशन का उपयोग करता है जिसमें डिक्लेरेटिव `@AiService` इंटरफेस शामिल हैं। स्टार्टअप पर स्प्रिंग बूट हर `@Component` खोजता है जिसमें `@Tool` मेथड्स हों, आपका `ChatModel` बीन, और `ChatMemoryProvider` — फिर इन्हें एकल `Assistant` इंटरफेस में जोड़ देता है बिना बोइलरप्लेट के। +यह मॉड्यूल LangChain4j के स्प्रिंग बूट इंटीग्रेशन का उपयोग करता है जिसमें डिक्लेरेटिव `@AiService` इंटरफेस होते हैं। शुरुआत में स्प्रिंग बूट हर `@Component` खोजता है जिसमें `@Tool` मेथड्स होते हैं, आपका `ChatModel` बीण, और `ChatMemoryProvider` — फिर इनके सबको एकल `Assistant` इंटरफेस में बिना बोयलप्लेट के जोड़ देता है। Spring Boot Auto-Wiring Architecture -*@AiService इंटरफेस ChatModel, टूल कम्पोनेंट्स, और मेमोरी प्रोवाइडर को जोड़ता है — स्प्रिंग बूट सभी वायरिंग स्वचालित रूप से संभालता है।* +*@AiService इंटरफेस ChatModel, उपकरण घटकों, और मेमोरी प्रोवाइडर को जोड़ता है — स्प्रिंग बूट स्वचालित रूप से सारी वायरिंग संभालता है।* -यहाँ पूरा रिक्वेस्ट जीवनचक्र सिक्वेंस डायग्राम के रूप में है — HTTP रिक्वेस्ट से लेकर कंट्रोलर, सेवा, ऑटो-वायर प्रॉक्सी, टूल निष्पादन और वापस: +यहाँ पूर्ण अनुरोध जीवनचक्र है एक अनुक्रम आरेख के रूप में — HTTP अनुरोध से लेकर कंट्रोलर, सेवा, और ऑटो-वायरड प्रॉक्सी तक, फिर उपकरण निष्पादन और वापस: Spring Boot Tool Calling Sequence -*पूरा स्प्रिंग बूट रिक्वेस्ट जीवनचक्र — HTTP रिक्वेस्ट कंट्रोलर और सेवा से होकर ऑटो-वायरड असिस्टेंट प्रॉक्सी तक जाता है, जो LLM और टूल कॉल्स का स्वचालित समन्वय करता है।* +*पूरा स्प्रिंग बूट अनुरोध जीवनचक्र — HTTP अनुरोध कंट्रोलर और सेवा के माध्यम से ऑटो-वायरड Assistant प्रॉक्सी तक प्रवाहित होता है, जो स्वयं LLM और उपकरण कॉलस का orchestration करता है।* -इस दृष्टिकोण के प्रमुख लाभ: +इस दृष्टिकोण के मुख्य लाभ: -- **स्प्रिंग बूट ऑटो-वायरिंग** — ChatModel और टूल स्वतः इंजेक्ट होते हैं +- **स्प्रिंग बूट ऑटो-वायरिंग** — ChatModel और उपकरण स्वचालित रूप से इंजेक्ट होते हैं - **@MemoryId पैटर्न** — स्वचालित सत्र-आधारित मेमोरी प्रबंधन -- **एकल इंस्टेंस** — बेहतर प्रदर्शन के लिए एक बार असिस्टेंट बनाया जाता है और पुनः उपयोग होता है -- **टाइप-सुरक्षित कार्यान्वयन** — जावा मेथड्स सीधे टाइप कन्वर्शन के साथ कॉल होते हैं -- **मल्टी-टर्न आर्केस्ट्रेशन** — टूल चेनिंग स्वचालित रूप से संभालता है -- **जीरो बोइलरप्लेट** — कोई मैनुअल `AiServices.builder()` कॉल या मेमोरी हैशमैप नहीं +- **एकल उदाहरण** — बेहतर प्रदर्शन के लिए Assistant एक बार बनाया जाता है और पुनः उपयोग किया जाता है +- **टाइप-सुरक्षित निष्पादन** — Java मेथड सीधे कोल्ड किए जाते हैं टाइप कन्वर्शन के साथ +- **मल्टी-टर्न संचालन** — उपकरण श्रृंखला स्वचालित रूप से संभालता है +- **शून्य बोयलप्लेट** — मैनुअल `AiServices.builder()` कॉल या मेमोरी HashMap की जरूरत नहीं -वैकल्पिक पद्धतियाँ (`AiServices.builder()` मैनुअल) अधिक कोड की मांग करती हैं और स्प्रिंग बूट के इंटीग्रेशन लाभों से वंचित रहती हैं। +वैकल्पिक दृष्टिकोण (मैनुअल `AiServices.builder()`) में अधिक कोड की आवश्यकता होती है और स्प्रिंग बूट इंटीग्रेशन के लाभ होते नहीं हैं। -## टूल चेनिंग +## उपकरण श्रृंखला -**टूल चेनिंग** — टूल-आधारित एजेंट्स की वास्तविक ताकत तब दिखती है जब एक प्रश्न के कई टूल्स की आवश्यकता होती है। पूछें "सीएटल में फ़ारेनहाइट में मौसम क्या है?" और एजेंट स्वचालित रूप से दो टूल्स चेन करता है: पहले `getCurrentWeather` को कॉल करता है जो सेल्सियस में तापमान देता है, फिर उसे `celsiusToFahrenheit` में पास करता है जो कन्वर्शन करता है — यह सब एक ही बातचीत टर्न में। +**उपकरण श्रृंखला** — उपकरण-आधारित एजेंटों की असली शक्ति तब दिखती है जब एक ही प्रश्न के लिए कई उपकरणों की जरूरत होती है। पूछें "Seattle में फ़ारेनहाइट में मौसम कैसा है?" और एजेंट स्वचालित रूप से दो उपकरणों को जोड़ता है: पहले `getCurrentWeather` कॉल करता है जो तापमान सेल्सियस में देता है, फिर वह मान `celsiusToFahrenheit` में भेजता है रूपांतरण के लिए — यह सब एक ही संवाद टर्न में। Tool Chaining Example -*टूल चेनिंग क्रिया में — एजेंट पहले getCurrentWeather को कॉल करता है, फिर सेल्सियस परिणाम को celsiusToFahrenheit में देता है, और सम्मिलित उत्तर प्रदान करता है।* +*उपकरण श्रृंखला क्रियान्वयन — एजेंट पहले getCurrentWeather कॉल करता है, फिर सेल्सियस परिणाम को celsiusToFahrenheit में पाइप करता है, और एक संयुक्त उत्तर प्रदान करता है।* -**सुगम विफलताएँ** — मॉक डेटा में न हो ऐसे शहर का मौसम पूछें। टूल त्रुटि संदेश लौटाता है, और AI समझाता है कि वह मदद नहीं कर सकता बजाय क्रैश होने के। टूल्स सुरक्षित रूप से विफल होते हैं। नीचे आरेख दोनों दृष्टिकोणों की तुलना करता है — सही त्रुटि प्रबंधन के साथ, एजेंट अपवाद पकड़कर मददगार उत्तर देता है, जबकि बिना इसके पूरी एप्लिकेशन क्रैश हो जाती है: +**सुगम विफलताएँ** — ऐसी किसी शहर का मौसम पूछें जो नकली डेटा में नहीं है। उपकरण त्रुटि संदेश लौटाता है, और AI बताता है कि वह मदद नहीं कर सकता बजाए क्रैश होने के। उपकरण सुरक्षित रूप से विफल होते हैं। नीचे वाला आरेख दो दृष्टिकोणों को दर्शाता है — उचित त्रुटि प्रबंधन के साथ, एजेंट अपवाद पकड़ता है और सहायक उत्तर देता है, जबकि बिना इसके पूरी एप्लीकेशन क्रैश हो जाती है: Error Handling Flow -*जब टूल विफल होता है, एजेंट त्रुटि पकड़ता है और क्रैश की बजाय सहायक व्याख्या देता है।* +*जब कोई उपकरण विफल होता है, तो एजेंट त्रुटि पकड़ता है और क्रैश होने के बजाय सहायक व्याख्या के साथ उत्तर देता है।* -यह एक ही बातचीत टर्न में होता है। एजेंट कई टूल कॉल्स का स्वायत्त समन्वय करता है। +यह एकल संवाद टर्न में होता है। एजेंट कई उपकरण कॉल का स्वायत्त संचालन करता है। ## एप्लिकेशन चलाएँ -**तैनाती जांचें:** +**तैनाती सत्यापित करें:** -सुनिश्चित करें कि रूट डायरेक्टरी में `.env` फ़ाइल है जिसमें Azure क्रेडेंशियल्स मौजूद हैं (जो माड्यूल 01 के दौरान बनाई गई थी)। माड्यूल डायरेक्टरी (`04-tools/`) से यह चलाएँ: +सुनिश्चित करें कि रूट डायरेक्टरी में `.env` फ़ाइल मौजूद है जिसमें Azure क्रेडेंशियल्स हैं (Module 01 के दौरान बनाई गई)। मॉड्यूल डायरेक्टरी (`04-tools/`) से इसे चलाएँ: **Bash:** ```bash @@ -207,38 +207,38 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दिखा **एप्लिकेशन शुरू करें:** -> **नोट:** यदि आपने पहले से ही रुट डायरेक्टरी से `./start-all.sh` का उपयोग कर सभी एप्लिकेशन शुरू कर दिए हैं (जैसा माड्यूल 01 में वर्णित है), तो यह माड्यूल पहले से ही पोर्ट 8084 पर चल रहा है। आप नीचे दिए स्टार्ट कमांड को छोड़ सकते हैं और सीधे http://localhost:8084 पर जा सकते हैं। +> **नोट:** यदि आपने पहले से रूट डायरेक्टरी से `./start-all.sh` का उपयोग करके सभी एप्लिकेशन शुरू कर दिए हैं (जैसा Module 01 में बताया गया है), तो यह मॉड्यूल पहले से पोर्ट 8084 पर चल रहा होगा। आप नीचे स्टार्ट कमांड छोड़ सकते हैं और सीधे http://localhost:8084 पर जा सकते हैं। -**विकल्प 1: स्प्रिंग बूट डैशबोर्ड का उपयोग करना (VS कोड उपयोगकर्ताओं के लिए अनुशंसित)** +**विकल्प 1: स्प्रिंग बूट डैशबोर्ड का उपयोग करना (VS Code उपयोगकर्ताओं के लिए अनुशंसित)** -डेव कंटेनर में स्प्रिंग बूट डैशबोर्ड एक्सटेंशन शामिल है, जो सभी स्प्रिंग बूट एप्लिकेशन प्रबंधित करने के लिए एक दृश्य इंटरफेस प्रदान करता है। आप इसे VS कोड के बाएं तरफ की एक्टिविटी बार में देख सकते हैं (स्प्रिंग बूट आइकन देखें)। +डेव कंटेनर में स्प्रिंग बूट डैशबोर्ड एक्सटेंशन शामिल है, जो सभी स्प्रिंग बूट एप्लिकेशन को प्रबंधित करने के लिए एक दृश्य इंटरफ़ेस प्रदान करता है। आप इसे VS Code के लेफ्ट साइड में गतिविधि बार में पा सकते हैं (स्प्रिंग बूट आइकन देखें)। स्प्रिंग बूट डैशबोर्ड से, आप: -- कार्यक्षेत्र में सभी उपलब्ध स्प्रिंग बूट एप्लिकेशन देख सकते हैं -- एक क्लिक में एप्लिकेशन शुरू/रोक सकते हैं -- एप्लिकेशन लॉग को रियल-टाइम में देख सकते हैं -- एप्लिकेशन स्थिति मॉनिटर कर सकते हैं -सिर्फ "tools" के बगल में प्ले बटन पर क्लिक करें ताकि यह मॉड्यूल शुरू हो सके, या सभी मॉड्यूल एक साथ शुरू करें। +- वर्कस्पेस में उपलब्ध सभी स्प्रिंग बूट एप्लिकेशन देख सकते हैं +- एक क्लिक में एप्लिकेशन स्टार्ट/स्टॉप कर सकते हैं +- रियल-टाइम में एप्लिकेशन लॉग्स देख सकते हैं +- एप्लिकेशन की स्थिति मॉनिटर कर सकते हैं -VS Code में Spring Boot डैशबोर्ड कुछ इस प्रकार दिखता है: +कृपया "tools" के बगल में प्ले बटन पर क्लिक करके इस मॉड्यूल को शुरू करें, या एक साथ सभी मॉड्यूल शुरू करें। +VS Code में स्प्रिंग बूट डैशबोर्ड कुछ ऐसा दिखता है: Spring Boot Dashboard -*VS Code में Spring Boot डैशबोर्ड — एक ही जगह से सभी मॉड्यूल शुरू, रोकें और मॉनिटर करें* +*VS कोड में Spring Boot डैशबोर्ड — सभी मॉड्यूल को एक ही जगह से शुरू, रोकें और मॉनिटर करें* -**विकल्प 2: शेल स्क्रिप्ट्स का उपयोग करना** +**ऑप्शन 2: शेल स्क्रिप्ट्स का उपयोग करना** सभी वेब एप्लिकेशन (मॉड्यूल 01-04) शुरू करें: **Bash:** ```bash -cd .. # रूट निर्देशिका से +cd .. # मूल निर्देशिका से ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # रूट डायरेक्टरी से +cd .. # रूट निर्देशिका से .\start-all.ps1 ``` @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -दोनों स्क्रिप्ट्स स्वचालित रूप से रूट `.env` फाइल से वातावरण चर लोड करती हैं और यदि JAR मौजूद नहीं हैं तो उन्हें बनाएंगी। +दोनों स्क्रिप्ट्स स्वचालित रूप से रूट `.env` फ़ाइल से पर्यावरण चर लोड करती हैं और यदि JAR मौजूद नहीं हैं तो उन्हें बनाएंगी। -> **नोट:** यदि आप शुरू करने से पहले सभी मॉड्यूल मैन्युअली बनाना पसंद करते हैं: +> **ध्यान दें:** यदि आप शुरू करने से पहले सभी मॉड्यूल को मैन्युअल रूप से बनाना पसंद करते हैं: > > **Bash:** > ```bash @@ -278,9 +278,9 @@ cd 04-tools **Bash:** ```bash -./stop.sh # केवल यह मॉड्यूल +./stop.sh # यह मॉड्यूल केवल # या -cd .. && ./stop-all.sh # सभी मॉड्यूल्स +cd .. && ./stop-all.sh # सभी मॉड्यूल ``` **PowerShell:** @@ -290,90 +290,90 @@ cd .. && ./stop-all.sh # सभी मॉड्यूल्स cd ..; .\stop-all.ps1 # सभी मॉड्यूल ``` -## एप्लिकेशन का उपयोग +## एप्लिकेशन का उपयोग करना -एप्लिकेशन एक वेब इंटरफ़ेस प्रदान करता है जहाँ आप एक AI एजेंट के साथ इंटरैक्ट कर सकते हैं जिसे मौसम और तापमान परिवर्तन उपकरणों तक पहुंच है। इंटरफ़ेस कुछ इस प्रकार दिखता है — इसमें त्वरित शुरुआत के उदाहरण और अनुरोध भेजने के लिए चैट पैनल शामिल हैं: +यह एप्लिकेशन एक वेब इंटरफ़ेस प्रदान करता है जहां आप एक एआई एजेंट के साथ इंटरैक्ट कर सकते हैं जिसे मौसम और तापमान रूपांतरण उपकरणों की पहुंच है। यहाँ इंटरफ़ेस कैसा दिखता है — इसमें त्वरित प्रारंभ उदाहरण और अनुरोध भेजने के लिए चैट पैनल शामिल है: AI Agent Tools Interface -*AI एजेंट टूल्स इंटरफ़ेस — टूल्स के साथ बातचीत के लिए त्वरित उदाहरण और चैट इंटरफ़ेस* +*AI एजेंट टूल्स इंटरफ़ेस - त्वरित उदाहरण और टूल्स के साथ बातचीत के लिए चैट इंटरफ़ेस* -### सरल टूल उपयोग आज़माएँ +### सरल टूल उपयोग आज़माएं -एक सीधे-सादे अनुरोध से शुरू करें: "100 डिग्री फ़ारेनहाइट को सेल्सियस में बदलें"। एजेंट समझता है कि उसे तापमान परिवर्तन टूल की जरूरत है, सही पैरामीटर के साथ इसे कॉल करता है, और परिणाम वापस करता है। ध्यान दें कि यह कितना स्वाभाविक लगता है - आपने यह निर्दिष्ट नहीं किया कि किस टूल का उपयोग करना है या इसे कैसे कॉल करना है। +एक सीधे-सादे अनुरोध से शुरू करें: "100 डिग्री फ़ारेनहाइट को सेल्सियस में कन्वर्ट करें"। एजेंट पहचानता है कि उसे तापमान रूपांतरण टूल की आवश्यकता है, सही मानकों के साथ उसे कॉल करता है, और परिणाम लौटाता है। ध्यान दें कि यह कितना स्वाभाविक महसूस होता है - आपने यह निर्दिष्ट नहीं किया कि कौन सा टूल उपयोग करना है या इसे कैसे कॉल करना है। ### टूल चेनिंग का परीक्षण करें -अब कुछ अधिक जटिल कोशिश करें: "सीएटल का मौसम कैसा है और इसे फ़ारेनहाइट में बदलें?" देखें कि एजेंट इसे चरण दर चरण कैसे संभालता है। पहले यह मौसम प्राप्त करता है (जो सेल्सियस लौटाता है), फिर पहचानता है कि इसे फ़ारेनहाइट में बदलने की जरूरत है, परिवर्तन टूल को कॉल करता है, और दोनों परिणामों को एक प्रतिक्रिया में जोड़ता है। +अब कुछ अधिक जटिल प्रयास करें: "सियैटल में मौसम कैसा है और इसे फ़ारेनहाइट में कन्वर्ट करें?" देखें कि एजेंट इसे चरणबद्ध तरीके से कैसे करता है। पहले वह मौसम प्राप्त करता है (जो सेल्सियस लौटाता है), पहचानता है कि फ़ारेनहाइट में कन्वर्ट करने की आवश्यकता है, रूपांतरण टूल को कॉल करता है, और दोनों परिणामों को एक उत्तर में संयोजित करता है। -### वार्तालाप प्रवाह देखें +### बातचीत के प्रवाह को देखें -चैट इंटरफ़ेस वार्तालाप इतिहास को बनाए रखता है, जिससे आप मल्टी-टर्न संवाद कर सकते हैं। आप सभी पिछले प्रश्न और प्रतिक्रियाएं देख सकते हैं, जिससे वार्तालाप को ट्रैक करना और समझना आसान होता है कि एजेंट कई आदान-प्रदान में संदर्भ कैसे बनाता है। +चैट इंटरफ़ेस बातचीत का इतिहास रखता है, जिससे आप बहु-चरण इंटरैक्शन कर सकते हैं। आप सभी पिछली पूछताछ और प्रतिक्रियाएँ देख सकते हैं, जिससे बातचीत का ट्रैक रखना और समझना आसान हो जाता है कि एजेंट कई विनिमयों के दौरान संदर्भ कैसे बनाता है। Conversation with Multiple Tool Calls -*मल्टी-टर्न वार्तालाप जिसमें सरल परिवर्तन, मौसम लुकअप, और टूल चेनिंग दिखाई दे रही है* +*सरल रूपांतरण, मौसम जांच और टूल चेनिंग दिखाते हुए बहु-चरण बातचीत* ### विभिन्न अनुरोधों के साथ प्रयोग करें -विभिन्न संयोजनों को आज़माएँ: -- मौसम की जानकारी: "टोक्यो में मौसम कैसा है?" -- तापमान परिवर्तन: "25°C कितना केल्विन में है?" -- संयोजित प्रश्न: "पेरिस में मौसम जांचें और बताएं कि क्या यह 20°C से ऊपर है" +विभिन्न संयोजन आजमाएं: +- मौसम जांच: "टोक्यो में मौसम कैसा है?" +- तापमान रूपांतरण: "25°C क्या केल्विन में है?" +- संयुक्त प्रश्न: "पेरिस में मौसम जांचें और बताएं कि क्या यह 20°C से ऊपर है" -ध्यान दें कि एजेंट कैसे प्राकृतिक भाषा को समझता है और इसे उपयुक्त टूल कॉल में मैप करता है। +ध्यान दें कि एजेंट प्राकृतिक भाषा को कैसे समझता है और उपयुक्त टूल कॉल से मैप करता है। ## मुख्य अवधारणाएँ -### ReAct पैटर्न (तर्क व क्रिया) +### ReAct पैटर्न (तर्क और क्रिया) -एजेंट तर्क (निर्णय लेना कि क्या करना है) और क्रिया (टूल्स का उपयोग करना) के बीच बारी-बारी से चलता है। यह पैटर्न केवल निर्देशों का पालन करने के बजाय स्वतंत्र समस्या-समाधान सक्षम बनाता है। +एजेंट तर्क (क्या करना है तय करना) और क्रिया (टूल्स का उपयोग करना) के बीच बारी-बारी से काम करता है। यह पैटर्न स्वायत्त समस्या समाधान सक्षम करता है न कि केवल निर्देशों का जवाब देना। ### टूल विवरण महत्वपूर्ण हैं -आपके टूल विवरण की गुणवत्ता सीधे प्रभावित करती है कि एजेंट उन्हें कैसे उपयोग करता है। स्पष्ट और विशिष्ट विवरण मॉडल को यह समझने में मदद करते हैं कि कब और कैसे प्रत्येक टूल को कॉल करना है। +आपके टूल विवरण की गुणवत्ता सीधे प्रभावित करती है कि एजेंट उन्हें कितना प्रभावी ढंग से उपयोग करता है। स्पष्ट, विशिष्ट विवरण मॉडल को यह समझने में मदद करते हैं कि कब और कैसे प्रत्येक टूल को कॉल करना है। -### सेशन प्रबंधन +### सत्र प्रबंधन -`@MemoryId` एनोटेशन स्वचालित सेशन-आधारित मेमोरी प्रबंधन सक्षम बनाता है। प्रत्येक सेशन ID को अपना `ChatMemory` उदाहरण मिलता है जो `ChatMemoryProvider` बीन द्वारा प्रबंधित होता है, इसलिए कई उपयोगकर्ता एक साथ एजेंट के साथ बातचीत कर सकते हैं बिना अपनी बातचीत के मेलजोल के। निम्न आरेख दिखाता है कि कैसे कई उपयोगकर्ताओं को उनके सेशन IDs के आधार पर पृथक मेमोरी स्टोर में राउट किया जाता है: +`@MemoryId` एनोटेशन स्वचालित सत्र-आधारित मेमोरी प्रबंधन सक्षम करता है। प्रत्येक सेशन आईडी को उसका अपना `ChatMemory` उदाहरण मिलता है जिसे `ChatMemoryProvider` बीन प्रबंधित करता है, ताकि कई उपयोगकर्ता बिना एक-दूसरे की बातचीत में मिलावट के एजेंट के साथ इंटरैक्ट कर सकें। निम्नलिखित आरेख दिखाता है कि कैसे कई उपयोगकर्ताओं को उनके सेशन आईडी के आधार पर अलग-अलग मेमोरी स्टोर्स में रूट किया जाता है: Session Management with @MemoryId -*प्रत्येक सेशन ID एक पृथक बातचीत इतिहास से जुड़ा होता है — उपयोगकर्ताओं को कभी भी एक-दूसरे के संदेश दिखाई नहीं देते।* +*प्रत्येक सेशन आईडी एक पृथक बातचीत इतिहास को मैप करती है — उपयोगकर्ता कभी भी एक-दूसरे के संदेश नहीं देखते।* ### त्रुटि प्रबंधन -टूल्स विफल हो सकते हैं — APIs टाइमआउट हो सकते हैं, पैरामीटर अमान्य हो सकते हैं, बाहरी सेवाएं डाउन हो सकती हैं। उत्पादन एजेंटों को त्रुटि प्रबंधन की जरूरत होती है ताकि मॉडल समस्याओं को समझा सके या विकल्प आज़मा सके बजाय इसके कि पूरी एप्लिकेशन क्रैश हो जाए। जब कोई टूल अपवाद फेंकता है, तो LangChain4j उसे पकड़ता है और त्रुटि संदेश मॉडल को वापस फीड करता है, जो तब प्राकृतिक भाषा में समस्या समझा सकता है। +टूल विफल हो सकते हैं — API टाइमआउट हो सकते हैं, पैरामीटर अवैध हो सकते हैं, बाहरी सेवाएँ बंद हो सकती हैं। प्रोडक्शन एजेंट को त्रुटि प्रबंधन की ज़रूरत होती है ताकि मॉडल समस्याओं की व्याख्या कर सके या विकल्प आज़मा सके बजाय इसके कि पूरी एप्लिकेशन क्रैश हो जाए। जब टूल कोई अपवाद फेंकता है, तो LangChain4j इसे पकड़ता है और त्रुटि संदेश मॉडल को वापस देता है, जो तब प्राकृतिक भाषा में समस्या समझा सकता है। ## उपलब्ध टूल्स -नीचे दिया गया आरेख उन व्यापक टूल्स के इकोसिस्टम को दर्शाता है जिन्हें आप बना सकते हैं। यह मॉड्यूल मौसम और तापमान टूल्स दिखाता है, लेकिन वही `@Tool` पैटर्न किसी भी जावा मेथड के लिए काम करता है — डेटाबेस क्वेरी से लेकर भुगतान प्रक्रिया तक। +निम्न आरेख उन व्यापक टूल्स का पारिस्थितिकी तंत्र दिखाता है जिन्हें आप बना सकते हैं। यह मॉड्यूल मौसम और तापमान टूल्स प्रदर्शित करता है, लेकिन वही `@Tool` पैटर्न किसी भी जावा मेथड के लिए काम करता है — डेटाबेस क्वेरीज से लेकर भुगतान प्रक्रियाएँ तक। Tool Ecosystem -*कोई भी जावा मेथड जो @Tool एनोटेशन के साथ है, AI के लिए उपलब्ध हो जाता है — यह पैटर्न डेटाबेस, API, ईमेल, फ़ाइल ऑपरेशन और अधिक तक फैलता है।* +*कोई भी जावा मेथड जिसे @Tool से एनोटेट किया गया है AI के लिए उपलब्ध हो जाता है — पैटर्न डेटाबेस, API, ईमेल, फ़ाइल ऑपरेशंस और अधिक तक बढ़ता है।* -## टूल-आधारित एजेंट कब उपयोग करें +## कब टूल-आधारित एजेंट का उपयोग करें -हर अनुरोध के लिए टूल्स की आवश्यकता नहीं होती। निर्णय इस पर निर्भर करता है कि AI को बाहरी सिस्टम के साथ इंटरैक्ट करना है या वह अपने ज्ञान से जवाब दे सकता है। निम्न मार्गदर्शिका संक्षेप में बताती है कि कब टूल्स मूल्य जोड़ते हैं और कब वे अनावश्यक होते हैं: +हर अनुरोध में टूल्स की आवश्यकता नहीं होती। निर्णय इस बात पर निर्भर करता है कि AI को बाहरी सिस्टम के साथ इंटरैक्ट करना है या वे अपने ज्ञान से जवाब दे सकते हैं। निम्न गाइड सारांशित करता है कि कब टूल्स उपयोगी होते हैं और कब वे आवश्यक नहीं: When to Use Tools -*एक त्वरित निर्णय गाइड — रियल-टाइम डेटा, गणना, और क्रियाओं के लिए टूल्स; सामान्य ज्ञान और रचनात्मक कार्यों के लिए आवश्यक नहीं।* +*एक त्वरित निर्णय मार्गदर्शिका — टूल्स रियल-टाइम डेटा, गणनाएँ, और क्रियाओं के लिए हैं; सामान्य ज्ञान और क्रिएटिव कार्यों के लिए आवश्यकता नहीं।* ## टूल्स बनाम RAG -मॉड्यूल 03 और 04 दोनों AI की क्षमताओं को बढ़ाते हैं, लेकिन मूल रूप से अलग तरीकों से। RAG मॉडल को **ज्ञान** तक पहुंच देता है दस्तावेज़ पुनः प्राप्त करके। टूल्स मॉडल को **क्रियाएं** करने की क्षमता देते हैं फ़ंक्शन कॉल करके। नीचे दिया गया आरेख इन दोनों दृष्टिकोणों की तुलना पक्ष-पक्ष में करता है — प्रत्येक वर्कफ़्लो कैसे चलता है और इनके बीच व्यापार-बंदियाँ: +मॉड्यूल 03 और 04 दोनों AI की क्षमताओं का विस्तार करते हैं, लेकिन मौलिक रूप से अलग तरीकों से। RAG मॉडल को **ज्ञान** तक पहुँच प्रदान करता है दस्तावेज़ पुनः प्राप्ति द्वारा। टूल्स मॉडल को **क्रियाएँ** करने की क्षमता देते हैं फ़ंक्शन कॉल करके। निम्न आरेख इन दोनों दृष्टिकोणों की तुलना एक साथ करता है — प्रत्येक वर्कफ़्लो कैसे काम करता है से लेकर उनके बीच ट्रेड-ऑफ तक: Tools vs RAG Comparison -*RAG स्थैतिक दस्तावेज़ों से जानकारी पुनः प्राप्त करता है — टूल्स क्रियाएं निष्पादित करते हैं और गतिशील, वास्तविक समय डेटा लाते हैं। कई उत्पादन प्रणालियाँ दोनों को मिलाकर उपयोग करती हैं।* +*RAG स्थैतिक दस्तावेज़ों से जानकारी पुनः प्राप्त करता है — टूल्स क्रियाएँ निष्पादित करते हैं और गतिशील, वास्तविक समय डेटा प्राप्त करते हैं। कई प्रोडक्शन सिस्टम दोनों को मिलाकर उपयोग करते हैं।* -व्यवहार में, कई उत्पादन प्रणालियाँ दोनों दृष्टिकोणों को मिलाती हैं: RAG आपके दस्तावेज़ीकरण में उत्तरों के लिए आधार प्रदान करता है, और टूल्स लाइव डेटा प्राप्त करने या काम करने के लिए। +वास्तव में, कई प्रोडक्शन सिस्टम दोनों दृष्टिकोणों को मिलाकर उपयोग करते हैं: RAG आपके दस्तावेज़ीकरण में उत्तरों को आधार देने के लिए, और टूल्स लाइव डेटा प्राप्त करने या संचालन करने के लिए। -## अगले कदम +## आगे के कदम -**अगला मॉड्यूल:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**अगला मॉड्यूल:** [05-mcp - मॉडल कॉन्टेक्स्ट प्रोटोकॉल (MCP)](../05-mcp/README.md) --- @@ -382,6 +382,6 @@ cd ..; .\stop-all.ps1 # सभी मॉड्यूल --- -**अस्वीकरण**: -इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयासरत हैं, कृपया ध्यान दें कि स्वचालित अनुवाद में त्रुटियाँ या असंगतियाँ हो सकती हैं। मौलिक दस्तावेज़ अपनी मूल भाषा में ही आधिकारिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए पेशेवर मानव अनुवाद की सलाह दी जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। +**अस्वीकरण**: +इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। \ No newline at end of file diff --git a/translations/hi/README.md b/translations/hi/README.md index 50fe7bc79..e2bb98f29 100644 --- a/translations/hi/README.md +++ b/translations/hi/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j के लिए शुरुआती +# शुरुआत के लिए LangChain4j -LangChain4j और Azure OpenAI GPT-5.2 के साथ AI एप्लिकेशन बनाने के लिए एक कोर्स, बुनियादी चैट से लेकर AI एजेंट तक। +LangChain4j और Azure OpenAI GPT-5.2 के साथ AI एप्लिकेशन बनाने के लिए एक कोर्स, बेसिक चैट से लेकर AI एजेंट्स तक। ### 🌐 बहुभाषी समर्थन -#### GitHub Action के माध्यम से समर्थित (स्वचालित और हमेशा अद्यतन) +#### GitHub Action के माध्यम से समर्थित (स्वचालित और हमेशा अपडेटेड) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](./README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **स्थानीय रूप से क्लोन करना प्राथमिकता देते हैं?** +> **स्थानीय क्लोन करना पसंद करते हैं?** > -> इस रिपॉजिटरी में 50+ भाषाओं के अनुवाद शामिल हैं जो डाउनलोड आकार को काफी बढ़ाते हैं। अनुवादों के बिना क्लोन करने के लिए, sparse checkout का उपयोग करें: +> इस रिपॉजिटरी में 50+ भाषा अनुवाद शामिल हैं जो डाउनलोड साइज को काफी बढ़ा देते हैं। अनुवादों के बिना क्लोन करने के लिए, sparse checkout का उपयोग करें: > > **Bash / macOS / Linux:** > ```bash @@ -29,61 +29,60 @@ LangChain4j और Azure OpenAI GPT-5.2 के साथ AI एप्लिक > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> यह आपको कोर्स पूरा करने के लिए आवश्यक सब कुछ देगा, वह भी बहुत तेज़ डाउनलोड के साथ। +> इससे आपको कोर्स पूरा करने के लिए जरूरी हर चीज़ बहुत तेज़ डाउनलोड के साथ मिल जाएगी। ## सामग्री सूची -1. [क्विक स्टार्ट](00-quick-start/README.md) - LangChain4j के साथ शुरुआत करें -2. [परिचय](01-introduction/README.md) - LangChain4j के मूल सिद्धांत सीखें -3. [प्रॉम्प्ट इंजीनियरिंग](02-prompt-engineering/README.md) - प्रभावी प्रॉम्प्ट डिज़ाइन में महारत हासिल करें -4. [RAG (रेट्रीवल-ऑगमेंटेड जेनरेशन)](03-rag/README.md) - बुद्धिमान ज्ञान-आधारित सिस्टम बनाएं -5. [उपकरण](04-tools/README.md) - बाहरी उपकरण और सरल सहायक एकीकृत करें -6. [MCP (मॉडल कॉन्टेक्स्ट प्रोटोकॉल)](05-mcp/README.md) - मॉडल कॉन्टेक्स्ट प्रोटोकॉल (MCP) और एजेन्टिक मॉड्यूल के साथ काम करें +1. [परिचय](01-introduction/README.md) - LangChain4j के मूल सिद्धांत सीखें +2. [प्रांप्ट इंजीनियरिंग](02-prompt-engineering/README.md) - प्रभावी प्रांप्ट डिज़ाइन में निपुण बनें +3. [RAG (रिट्रीवल-ऑगमेंटेड जेनरेशन)](03-rag/README.md) - बुद्धिमान ज्ञान-आधारित सिस्टम बनाएं +4. [उपकरण](04-tools/README.md) - बाहरी उपकरण और सरल सहायक जोड़े +5. [MCP (मॉडल कॉन्टेक्सट प्रोटोकॉल)](05-mcp/README.md) - मॉडल कॉन्टेक्सट प्रोटोकॉल (MCP) और एजेंटिक मॉड्यूल्स के साथ काम करें ### वीडियो वॉकथ्रू -प्रत्येक मॉड्यूल के साथ एक लाइव सत्र भी होता है जहाँ हम चरण-दर-चरण अवधारणाओं और कोड के माध्यम से चलते हैं। +हर मॉड्यूल के साथ एक लाइव सत्र होता है जहाँ हम अवधारणाओं और कोड को कदम-दर-कदम समझाते हैं। | मॉड्यूल | वीडियो | |--------|-------| | 01 - परिचय | [LangChain4j के साथ शुरुआत](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - प्रॉम्प्ट इंजीनियरिंग | [LangChain4j के साथ प्रॉम्प्ट इंजीनियरिंग](https://www.youtube.com/live/PJ6aBaE6bog) | +| 02 - प्रांप्ट इंजीनियरिंग | [LangChain4j के साथ प्रांप्ट इंजीनियरिंग](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [LangChain4j के साथ RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - उपकरण और 05 - MCP | [उपकरण और MCP के साथ AI एजेंट्स](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - उपकरण और 05 - MCP | [उपकरणों और MCP के साथ AI एजेंट्स](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## सीखने का मार्ग -**LangChain4j में नए हैं?** प्रमुख शब्दों और अवधारणाओं के लिए [शब्दावली](docs/GLOSSARY.md) देखें। +**LangChain4j में नए हैं?** प्रमुख शब्दों और अवधारणाओं की परिभाषाओं के लिए [शब्दावली](docs/GLOSSARY.md) देखें। -> **त्वरित शुरुआत** +> **शीघ्र आरंभ** -1. इस रिपॉजिटरी को अपने GitHub अकाउंट पर Fork करें -2. क्लिक करें **कोड** → **Codespaces** टैब → **...** → **नई विकल्पों के साथ...** -3. डिफ़ॉल्ट सेटिंग्स का उपयोग करें – यह इस कोर्स के लिए बनाए गए डेवलपमेंट कंटेनर को चुनेगा -4. क्लिक करें **कोडस्पेस बनाएँ** -5. वातावरण के तैयार होने के लिए 5-10 मिनट प्रतीक्षा करें -6. सीधे [क्विक स्टार्ट](./00-quick-start/README.md) पर जाएं और शुरुआत करें! +1. इस रिपॉजिटरी को अपने GitHub खाते में Fork करें +2. क्लिक करें **Code** → **Codespaces** टैब → **...** → **New with options...** +3. डिफ़ॉल्ट विकल्प चुनें – यह इस कोर्स के लिए बनाए गए डेवेलपमेंट कंटेनर को सेलेक्ट करेगा +4. क्लिक करें **Create codespace** +5. पर्यावरण तैयार होने के लिए 5-10 मिनट प्रतीक्षा करें +6. शुरू करने के लिए सीधे [परिचय](./01-introduction/README.md) पर जाएं! -मॉड्यूल पूरा करने के बाद, LangChain4j के परीक्षण अवधारणाओं को देखने के लिए [टेस्टिंग गाइड](docs/TESTING.md) एक्सप्लोर करें। +मॉड्यूल पूरा करने के बाद, LangChain4j के टेस्टिंग कॉन्सेप्ट्स को व्यावहारिक रूप में देखने के लिए [टेस्टिंग गाइड](docs/TESTING.md) देखें। -> **नोट:** यह प्रशिक्षण GitHub Models और Azure OpenAI दोनों का उपयोग करता है। [क्विक स्टार्ट](00-quick-start/README.md) मॉड्यूल में GitHub Models का उपयोग होता है (कोई Azure सदस्यता आवश्यक नहीं), जबकि मॉड्यूल 1-5 में Azure OpenAI का उपयोग होता है। अगर आपके पास नहीं है, तो एक [मुफ्त Azure अकाउंट](https://aka.ms/azure-free-account) के साथ शुरुआत करें। +> **नोट:** यह प्रशिक्षण Azure OpenAI का उपयोग करता है। यदि आपके पास एक नहीं है तो [FREE Azure अकाउंट](https://aka.ms/azure-free-account) के साथ शुरू करें। ## GitHub Copilot के साथ सीखना -कोडिंग जल्दी शुरू करने के लिए, इस प्रोजेक्ट को GitHub Codespace या आपके स्थानीय IDE में प्रदान किए गए devcontainer के साथ खोलें। इस कोर्स में उपयोग किया गया devcontainer GitHub Copilot के साथ पूर्व-संरचित है, जो AI पेयर प्रोग्रामिंग के लिए है। +जल्दी से कोडिंग शुरू करने के लिए, इस प्रोजेक्ट को GitHub Codespace या आपके स्थानीय IDE में दिए गए devcontainer के साथ खोलें। इस कोर्स में उपयोग किए गए devcontainer में पहले से GitHub Copilot AI पेयर्ड प्रोग्रामिंग के लिए कॉन्फ़िगर किया गया है। -प्रत्येक कोड उदाहरण में GitHub Copilot से पूछने के लिए सुझावित प्रश्न शामिल हैं जो आपकी समझ को गहरा करेंगे। देखें 💡/🤖 संकेत: +हर कोड उदाहरण में GitHub Copilot से पूछे जाने वाले सुझाए गए प्रश्न शामिल हैं ताकि आपकी समझ गहरी हो सके। 💡/🤖 संकेत खोजें: - **Java फ़ाइल हेडर** - प्रत्येक उदाहरण के लिए विशिष्ट प्रश्न -- **मॉड्यूल पढ़ें** - कोड उदाहरणों के बाद परीक्षण सुझाव +- **मॉड्यूल README** - कोड उदाहरणों के बाद एक्सप्लोरेशन प्रॉम्प्ट -**कैसे उपयोग करें:** कोई भी कोड फ़ाइल खोलें और Copilot से सुझावित प्रश्न पूछें। इसके पास कोडबेस का पूरा संदर्भ होता है और यह समझा सकता है, बढ़ा सकता है, और विकल्प सुझा सकता है। +**कैसे उपयोग करें:** किसी भी कोड फ़ाइल को खोलें और Copilot से सुझाए गए प्रश्न पूछें। उसके पास कोडबेस का पूरा संदर्भ होता है और वह समझा सकता है, बढ़ा सकता है, और विकल्प सुझा सकता है। -और जानना चाहते हैं? देखें [AI पेयर प्रोग्रामिंग के लिए Copilot](https://aka.ms/GitHubCopilotAI)। +अधिक जानना चाहते हैं? देखें [AI पेयर्ड प्रोग्रामिंग के लिए Copilot](https://aka.ms/GitHubCopilotAI)। ## अतिरिक्त संसाधन @@ -114,28 +113,28 @@ LangChain4j और Azure OpenAI GPT-5.2 के साथ AI एप्लिक [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![शुरुआती लोगों के लिए साइबरसिक्योरिटी](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![शुरुआती लोगों के लिए वेब डेव](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![शुरुआती लोगों के लिए IoT](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![शुरुआती लोगों के लिए XR विकास](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- - -### कोपिलट श्रृंखला -[![एआई पेयर्ड प्रोग्रामिंग के लिए कोपिलट](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET के लिए कोपिलट](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![कोपिलट एडवेंचर](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) + +### Copilot Series +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## सहायता प्राप्त करना -यदि आप फंस गए हैं या AI ऐप्स बनाने के बारे में कोई प्रश्न है, तो जुड़ें: +यदि आप अटक जाते हैं या AI ऐप्स बनाने के बारे में कोई प्रश्न है, तो जुड़ें: -[![Microsoft Foundry डिस्कॉर्ड](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) +[![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) यदि आपके पास उत्पाद प्रतिक्रिया या निर्माण के दौरान त्रुटियां हैं, तो जाएँ: -[![Microsoft Foundry डेवलपर फोरम](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) +[![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## लाइसेंस @@ -144,6 +143,6 @@ MIT लाइसेंस - विवरण के लिए [LICENSE](../../LIC --- -**अस्वीकरण**: -यह दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके अनुवादित किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियां या अशुद्धियां हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में प्राधिकृत स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की अनुशंसा की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। +**अस्वीकरण**: +इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। \ No newline at end of file diff --git a/translations/hi/docs/GLOSSARY.md b/translations/hi/docs/GLOSSARY.md index 550f149a9..b61ad22d8 100644 --- a/translations/hi/docs/GLOSSARY.md +++ b/translations/hi/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## सामग्री तालिका -- [मुख्य अवधारणाएँ](../../../docs) -- [LangChain4j घटक](../../../docs) -- [AI/ML अवधारणाएँ](../../../docs) -- [गार्डरेल्स](../../../docs) -- [प्रॉम्प्ट इंजीनियरिंग](../../../docs) -- [RAG (रीट्रीवल-ऑगमेंटेड जनरेशन)](../../../docs) -- [एजेंट और उपकरण](../../../docs) -- [एजेंटिक मॉड्यूल](../../../docs) -- [मॉडल कॉन्टेक्स्ट प्रोटोकॉल (MCP)](../../../docs) -- [Azure सेवाएँ](../../../docs) -- [परीक्षण और विकास](../../../docs) +- [मूल अवधारणाएँ](#मूल-अवधारणाएँ) +- [LangChain4j घटक](#langchain4j-घटक) +- [एआई/एमएल अवधारणाएँ](#aiml-अवधारणाएँ) +- [गार्डरेल](#गार्डरेल) +- [प्रॉम्प्ट इंजीनियरिंग](#prompt-engineering---module-02) +- [RAG (रीट्रिवल-अग्मेंटेड जनरेशन)](#rag-retrieval-augmented-generation---module-03) +- [एजेंट और टूल्स](#agents-and-tools---module-04) +- [एजेंटिक मॉड्यूल](#agentic-module---module-05) +- [मॉडल कॉन्टेक्स्ट प्रोटोकॉल (MCP)](#model-context-protocol-mcp---module-05) +- [एज़्योर सेवाएं](#azure-services---module-01) +- [टेस्टिंग और विकास](#testing-and-development---testing-guide) -पाठ्यक्रम में उपयोग किए जाने वाले शब्दों और अवधारणाओं के लिए त्वरित संदर्भ। +कोर्स के दौरान उपयोग किए गए शब्दों और अवधारणाओं के लिए त्वरित संदर्भ। -## मुख्य अवधारणाएँ +## मूल अवधारणाएँ -**AI एजेंट** - ऐसा सिस्टम जो AI का उपयोग करके स्वायत्त रूप से तर्क करता है और कार्रवाई करता है। [मॉड्यूल 04](../04-tools/README.md) +**AI एजेंट** - ऐसी प्रणाली जो AI का उपयोग करके स्वतंत्र रूप से तर्क करती है और कार्य करती है। [मॉड्यूल 04](../04-tools/README.md) -**चेन** - ऑपरेशनों का अनुक्रम जिसमें आउटपुट अगले चरण में जाता है। +**चेन** - संचालन की एक श्रृंखला जहाँ आउटपुट अगले चरण में जाता है। -**चंकिंग** - दस्तावेज़ों को छोटे टुकड़ों में तोड़ना। सामान्य: 300-500 टोकन ओवरलैप के साथ। [मॉड्यूल 03](../03-rag/README.md) +**चंकिंग** - दस्तावेज़ों को छोटे हिस्सों में तोड़ना। सामान्य: 300-500 टोकन ओवरलैप के साथ। [मॉड्यूल 03](../03-rag/README.md) -**संदर्भ विंडो** - अधिकतम टोकन जो कोई मॉडल संसाधित कर सकता है। GPT-5.2: 400K टोकन (272K इनपुट तक, 128K आउटपुट)। +**संदर्भ विंडो** - अधिकतम टोकन जो एक मॉडल संसाधित कर सकता है। GPT-5.2: 400K टोकन (अधिकतम 272K इनपुट, 128K आउटपुट)। **एम्बेडिंग्स** - टेक्स्ट के अर्थ को दर्शाने वाले संख्यात्मक वेक्टर। [मॉड्यूल 03](../03-rag/README.md) -**फंक्शन कॉलिंग** - मॉडल बाहरी फंक्शन कॉल करने के लिए संरचित अनुरोध उत्पन्न करता है। [मॉड्यूल 04](../04-tools/README.md) +**फंक्शन कॉलिंग** - मॉडल संरचित अनुरोध उत्पन्न करता है ताकि बाहरी फ़ंक्शंस कॉल किए जा सकें। [मॉड्यूल 04](../04-tools/README.md) -**हैलुसिनेशन** - जब मॉडल गलत लेकिन संभव सूचना उत्पन्न करते हैं। +**हलुसिनेशन** - जब मॉडल त्रुटिपूर्ण परंतु संभावित जानकारी उत्पन्न करते हैं। -**प्रॉम्प्ट** - भाषा मॉडल को दिया गया टेक्स्ट इनपुट। [मॉड्यूल 02](../02-prompt-engineering/README.md) +**प्रॉम्प्ट** - भाषा मॉडल को दिया गया पाठ इनपुट। [मॉड्यूल 02](../02-prompt-engineering/README.md) -**सेमान्टिक सर्च** - कीवर्ड्स के बजाय एम्बेडिंग्स के उपयोग से अर्थ द्वारा खोज। [मॉड्यूल 03](../03-rag/README.md) +**सेमांटिक खोज** - कीवर्ड के बजाय अर्थ के आधार पर खोज, एम्बेडिंग का उपयोग करके। [मॉड्यूल 03](../03-rag/README.md) -**स्टेटफुल बनाम स्टेटलेस** - स्टेटलेस: कोई मेमोरी नहीं। स्टेटफुल: वार्तालाप इतिहास बनाए रखता है। [मॉड्यूल 01](../01-introduction/README.md) +**स्टेटफुल बनाम स्टेटलेस** - स्टेटलेस: कोई मेमोरी नहीं। स्टेटफुल: बातचीत का इतिहास रखता है। [मॉड्यूल 01](../01-introduction/README.md) -**टोकन** - मॉडल द्वारा संसाधित मूल टेक्स्ट इकाइयाँ। लागत और सीमाओं को प्रभावित करता है। [मॉड्यूल 01](../01-introduction/README.md) +**टोकन** - मॉडल जो मूल टेक्स्ट इकाइयाँ संसाधित करते हैं। लागत और सीमाओं को प्रभावित करते हैं। [मॉड्यूल 01](../01-introduction/README.md) -**टूल चेनिंग** - टूल का अनुक्रमिक निष्पादन जहां आउटपुट अगली कॉल का इनपुट होता है। [मॉड्यूल 04](../04-tools/README.md) +**टूल चेनिंग** - टूल्स को क्रमिक रूप से चलाना जहाँ आउटपुट अगले कॉल के लिए जानकारी देता है। [मॉड्यूल 04](../04-tools/README.md) ## LangChain4j घटक -**AiServices** - टाइप-सुरक्षित AI सेवा इंटरफेस बनाता है। +**AiServices** - टाइप-सेफ AI सेवा इंटरफेस बनाता है। **OpenAiOfficialChatModel** - OpenAI और Azure OpenAI मॉडलों के लिए एकीकृत क्लाइंट। -**OpenAiOfficialEmbeddingModel** - OpenAI Official क्लाइंट के उपयोग से एम्बेडिंग्स बनाता है (दोनों OpenAI और Azure OpenAI समर्थित)। +**OpenAiOfficialEmbeddingModel** - OpenAI Official क्लाइंट का उपयोग करते हुए एम्बेडिंग बनाता है (OpenAI और Azure OpenAI दोनों समर्थित)। -**ChatModel** - भाषा मॉडलों के लिए मुख्य इंटरफेस। +**ChatModel** - भाषा मॉडलों के लिए मुख्य इंटरफ़ेस। -**ChatMemory** - वार्तालाप इतिहास बनाए रखता है। +**ChatMemory** - बातचीत का इतिहास बनाए रखता है। -**ContentRetriever** - RAG के लिए संबंधित दस्तावेज़ चंक खोजता है। +**ContentRetriever** - RAG के लिए प्रासंगिक दस्तावेज़ चंक खोजता है। -**DocumentSplitter** - दस्तावेज़ों को चंक में तोड़ता है। +**DocumentSplitter** - दस्तावेज़ों को चंक में विभाजित करता है। **EmbeddingModel** - टेक्स्ट को संख्यात्मक वेक्टर में परिवर्तित करता है। -**EmbeddingStore** - एम्बेडिंग्स स्टोर और पुनः प्राप्त करता है। +**EmbeddingStore** - एम्बेडिंग्स को संग्रहीत और पुनः प्राप्त करता है। -**MessageWindowChatMemory** - हाल की संदेशों की स्लाइडिंग विंडो बनाए रखता है। +**MessageWindowChatMemory** - हाल के संदेशों की स्लाइडिंग विंडो बनाए रखता है। -**PromptTemplate** - `{{variable}}` प्लेसहोल्डर्स के साथ पुन: उपयोग किए जाने योग्य प्रॉम्प्ट बनाता है। +**PromptTemplate** - पुन: प्रयोज्य प्रॉम्प्ट बनाता है जिसमें `{{variable}}` प्लेसहोल्डर होते हैं। **TextSegment** - मेटाडेटा के साथ टेक्स्ट चंक। RAG में उपयोग किया जाता है। -**ToolExecutionRequest** - टूल निष्पादन अनुरोध का प्रतिनिधित्व करता है। +**ToolExecutionRequest** - टूल निष्पादन के अनुरोध का प्रतिनिधित्व करता है। -**UserMessage / AiMessage / SystemMessage** - वार्तालाप संदेश प्रकार। +**UserMessage / AiMessage / SystemMessage** - बातचीत के संदेश प्रकार। ## AI/ML अवधारणाएँ **फ्यू-शॉट लर्निंग** - प्रॉम्प्ट में उदाहरण प्रदान करना। [मॉड्यूल 02](../02-prompt-engineering/README.md) -**लार्ज लैंग्वेज मॉडल (LLM)** - विशाल टेक्स्ट डेटा पर प्रशिक्षित AI मॉडल। +**लार्ज लैंग्वेज मॉडल (LLM)** - विशाल पाठ डेटा पर प्रशिक्षित AI मॉडल। -**तर्क प्रयास** - GPT-5.2 पैरामीटर जो सोच की गहराई को नियंत्रित करता है। [मॉड्यूल 02](../02-prompt-engineering/README.md) +**रीज़निंग एफर्ट** - GPT-5.2 पैरामीटर जो सोच की गहराई नियंत्रित करता है। [मॉड्यूल 02](../02-prompt-engineering/README.md) -**टेम्परेचर** - आउटपुट की यादृच्छिकता को नियंत्रित करता है। कम=नियतात्मक, उच्च=रचनात्मक। +**टेम्परेचर** - आउटपुट की यादृच्छिकता नियंत्रित करता है। निम्न=नियतात्मक, उच्च=सृजनात्मक। -**वेक्टर डेटाबेस** - एम्बेडिंग्स के लिए विशेष डेटाबेस। [मॉड्यूल 03](../03-rag/README.md) +**वेक्टर डाटाबेस** - एम्बेडिंग के लिए विशेष डेटाबेस। [मॉड्यूल 03](../03-rag/README.md) **जीरो-शॉट लर्निंग** - बिना उदाहरण के कार्य करना। [मॉड्यूल 02](../02-prompt-engineering/README.md) -## गार्डरेल्स - [मॉड्यूल 00](../00-quick-start/README.md) +## गार्डरेल -**गहराई में सुरक्षा** - एप्लिकेशन-स्तरीय गार्डरेल्स को प्रदाता सुरक्षा फ़िल्टरों के साथ जोड़ने वाला बहु-परत सुरक्षा दृष्टिकोण। +**डेफेंस इन डेप्थ** - मल्टी-लेयर सुरक्षा दृष्टिकोण जिसमें एप्लिकेशन-स्तरीय गार्डरेल्स को प्रदाता सुरक्षा फ़िल्टर के साथ जोड़ा जाता है। -**हार्ड ब्लॉक** - गंभीर सामग्री उल्लंघनों पर प्रदाता HTTP 400 त्रुटि फेंकता है। +**हार्ड ब्लॉक** - गंभीर सामग्री उल्लंघनों पर प्रदाता HTTP 400 त्रुटि देता है। -**InputGuardrail** - LangChain4j इंटरफेस जो LLM तक पहुँचने से पहले उपयोगकर्ता इनपुट को मान्य करता है। हानिकारक प्रॉम्प्ट को जल्दी रोककर लागत और विलंबता बचाता है। +**InputGuardrail** - LangChain4j इंटरफ़ेस जो LLM तक पहुंचने से पहले उपयोगकर्ता इनपुट को सत्यापित करता है। हानिकारक प्रॉम्प्ट को जल्दी रोककर लागत और विलंबता बचाता है। **InputGuardrailResult** - गार्डरेल सत्यापन के लिए रिटर्न टाइप: `success()` या `fatal("कारण")`। -**OutputGuardrail** - AI प्रतिक्रियाओं को उपयोगकर्ताओं को लौटाने से पहले मान्य करने के लिए इंटरफेस। +**OutputGuardrail** - AI प्रतिक्रियाओं को उपयोगकर्ताओं को लौटाने से पहले सत्यापित करने के लिए इंटरफ़ेस। -**प्रदाता सुरक्षा फ़िल्टर** - AI प्रदाताओं (जैसे GitHub मॉडल) से अंतर्निर्मित सामग्री फ़िल्टर जो API स्तर पर उल्लंघनों को पकड़ते हैं। +**प्रदाता सुरक्षा फ़िल्टर** - AI प्रदाताओं (जैसे Azure OpenAI) के अंतर्निर्मित सामग्री फ़िल्टर जो API स्तर पर उल्लंघनों को पकड़ते हैं। -**सॉफ्ट अस्वीकार** - मॉडल शिष्टतापूर्वक उत्तर देने से मना करता है बिना त्रुटि फेंके। +**सॉफ्ट रिफ़्यूजल** - मॉडल शिष्टतापूर्वक उत्तर देने से इनकार करता है बिना त्रुटि फेंके। ## प्रॉम्प्ट इंजीनियरिंग - [मॉड्यूल 02](../02-prompt-engineering/README.md) -**चेन-ऑफ़-थॉट** - बेहतर सटीकता के लिए चरण-दर-चरण तर्क। +**चेन-ऑफ-थॉट** - बेहतर सटीकता के लिए कदम-दर-कदम तर्क। -**प्रतिबंधित आउटपुट** - विशिष्ट प्रारूप या संरचना लागू करना। +**संसाधित आउटपुट** - विशिष्ट प्रारूप या संरचना लागू करना। -**अत्यधिक उत्सुकता** - GPT-5.2 पैटर्न जो गहन तर्क के लिए है। +**उच्च उत्साह** - GPT-5.2 पैटर्न जो गहन तर्क के लिए है। -**कम उत्सुकता** - GPT-5.2 पैटर्न जो तेजी से उत्तर देने के लिए है। +**निम्न उत्साह** - GPT-5.2 पैटर्न जो त्वरित उत्तरों के लिए है। -**मल्टी-टर्न वार्तालाप** - आदान-प्रदान के बीच संदर्भ बनाए रखना। +**मल्टी-टर्न बातचीत** - विनिमय के दौरान संदर्भ बनाए रखना। -**भूमिका-आधारित प्रॉम्प्टिंग** - सिस्टम संदेशों द्वारा मॉडल व्यक्तित्व सेट करना। +**भूमिका आधारित प्रॉम्प्टिंग** - सिस्टम संदेशों के माध्यम से मॉडल व्यक्तित्व सेट करना। -**आत्म-परावर्तन** - मॉडल अपनी आउटपुट का मूल्यांकन और सुधार करता है। +**स्व-परावर्तन** - मॉडल अपनी आउटपुट का मूल्यांकन करता है और सुधार करता है। **संरचित विश्लेषण** - निश्चित मूल्यांकन फ्रेमवर्क। -**कार्य निष्पादन पैटर्न** - योजना → क्रियान्वयन → सारांश। +**टास्क निष्पादन पैटर्न** - योजना → निष्पादन → सारांश। -## RAG (रीट्रीवल-ऑगमेंटेड जनरेशन) - [मॉड्यूल 03](../03-rag/README.md) +## RAG (रीट्रिवल-अग्मेंटेड जनरेशन) - [मॉड्यूल 03](../03-rag/README.md) -**दस्तावेज़ प्रसंस्करण पाइपलाइन** - लोड → चंक → एम्बेड → स्टोर। +**दस्तावेज़ प्रोसेसिंग पाइपलाइन** - लोड → चंक → एम्बेड → स्टोर। -**इन-मेमोरी एम्बेडिंग स्टोर** - परीक्षण के लिए गैर-स्थायी भंडारण। +**इन-मेमोरी एम्बेडिंग स्टोर** - परीक्षण के लिए अस्थायी भंडारण। -**RAG** - पुनः प्राप्ति के साथ जनरेशन को जोड़ता है ताकि प्रतिक्रियाएं आधारभूत बनें। +**RAG** - पुनर्प्राप्ति और जनरेशन को मिलाकर प्रतिक्रियाओं को आधार देता है। -**समानता स्कोर** - सेमान्टिक समानता का माप (0-1)। +**समानता स्कोर** - अर्थ की समानता का मापक (0-1)। -**स्रोत संदर्भ** - पुनः प्राप्त सामग्री के बारे में मेटाडेटा। +**स्रोत संदर्भ** - पुनर्प्राप्त की गई सामग्री के बारे में मेटाडेटा। -## एजेंट्स और टूल्स - [मॉड्यूल 04](../04-tools/README.md) +## एजेंट और टूल्स - [मॉड्यूल 04](../04-tools/README.md) -**@Tool एनोटेशन** - जावा विधियों को AI-काल करने योग्य उपकरण के रूप में चिह्नित करता है। +**@Tool एनोटेशन** - Java विधियों को AI-कॉल करने योग्य टूल के रूप में चिह्नित करता है। -**ReAct पैटर्न** - तर्क → कार्रवाई → अवलोकन → पुनरावृत्ति। +**ReAct पैटर्न** - तर्क → कार्य → पर्यवेक्षण → पुनरावृत्ति। -**सत्र प्रबंधन** - अलग-अलग उपयोगकर्ताओं के लिए संदर्भ अलग रखना। +**सेशन प्रबंधन** - विभिन्न उपयोगकर्ताओं के लिए अलग संदर्भ। -**टूल** - वह फंक्शन जिसे AI एजेंट कॉल कर सकता है। +**टूल** - एक फ़ंक्शन जिसे AI एजेंट कॉल कर सकता है। -**टूल विवरण** - उपकरण के उद्देश्य और पैरामीटर का दस्तावेजीकरण। +**टूल विवरण** - टूल के उद्देश्य और पैरामीटर का दस्तावेज़ीकरण। ## एजेंटिक मॉड्यूल - [मॉड्यूल 05](../05-mcp/README.md) -**@Agent एनोटेशन** - इंटरफेस को AI एजेंट्स के रूप में घोषित करता है जिसमें व्यवहारात्मक परिभाषा होती है। +**@Agent एनोटेशन** - इंटरफेस को AI एजेंट के रूप में चिह्नित करता है जहाँ घोषित व्यवहार निर्दिष्ट होता है। -**एजेंट लिसनर** - `beforeAgentInvocation()` और `afterAgentInvocation()` के माध्यम से एजेंट निष्पादन मॉनिटर करने के लिए हुक। +**एजेंट लिस्नर** - `beforeAgentInvocation()` और `afterAgentInvocation()` के माध्यम से एजेंट निष्पादन की निगरानी के लिए हुक। -**एजेंटिक स्कोप** - साझा मेमोरी जहाँ एजेंट आउटपुट संग्रहीत करते हैं, `outputKey` का उपयोग नीचे के एजेंट्स के लिए। +**एजेंटिक स्कोप** - साझा मेमोरी जहाँ एजेंट आउटपुट को `outputKey` का उपयोग करते हुए संग्रहीत करते हैं ताकि डाउनस्ट्रीम एजेंट उसका उपयोग कर सकें। -**AgenticServices** - `agentBuilder()` और `supervisorBuilder()` के द्वारा एजेंट बनाने का फैक्ट्री। +**AgenticServices** - `agentBuilder()` और `supervisorBuilder()` का उपयोग करते हुए एजेंट बनाने के लिए फैक्टरी। -**सशर्त कार्यप्रवाह** - स्थितियों के आधार पर विभिन्न विशेषज्ञ एजेंट्स को मार्गदर्शन। +**सशर्त वर्कफ़्लो** - स्थितियों के आधार पर भिन्न विशेषज्ञ एजेंटों को मार्ग देना। -**ह्यूमन-इन-द-लूप** - अनुमोदन या सामग्री समीक्षा के लिए मानव चेकपॉइंट जोड़ने वाला कार्यप्रवाह पैटर्न। +**मानव-इन-द-लूप** - अनुमोदन या सामग्री समीक्षा के लिए मानवीय जांच बिंदु जोड़ने वाला वर्कफ़्लो पैटर्न। -**langchain4j-agentic** - घोषणात्मक एजेंट निर्माण के लिए Maven निर्भरता (प्रयोगात्मक)। +**langchain4j-agentic** - घोषणा आधारित एजेंट निर्माण के लिए Maven डिपेंडेंसी (प्रायोगिक)। -**लूप कार्यप्रवाह** - एजेंट निष्पादन को तब तक दोहराएं जब तक कोई शर्त पूरी न हो (जैसे गुणवत्ता स्कोर ≥ 0.8)। +**लूप वर्कफ़्लो** - जब तक कोई शर्त पूरी न हो (जैसे गुणवत्ता स्कोर ≥ 0.8) एजेंट निष्पादन को दोहराना। -**outputKey** - एजेंट एनोटेशन पैरामीटर जो निर्दिष्ट करता है कि परिणाम एजेंटिक स्कोप में कहाँ संग्रहीत हैं। +**outputKey** - एजेंट एनोटेशन पैरामीटर जो एजेंटिक स्कोप में परिणाम कहाँ संग्रहीत होंगे यह निर्दिष्ट करता है। -**पैरालल कार्यप्रवाह** - स्वतंत्र कार्यों के लिए कई एजेंट्स को एक साथ चलाएं। +**पैरलल वर्कफ़्लो** - स्वतंत्र कार्यों के लिए कई एजेंटों को एक साथ चलाना। -**प्रतिक्रिया रणनीति** - पर्यवेक्षक अंतिम उत्तर कैसे बनाता है: LAST, SUMMARY, या SCORED। +**प्रतिक्रिया रणनीति** - सुपरवाइज़र अंतिम उत्तर कैसे तैयार करता है: LAST, SUMMARY, या SCORED। -**क्रमिक कार्यप्रवाह** - एजेंट्स को आदेश में निष्पादित करें जहाँ आउटपुट अगले चरण में जाता है। +**क्रमिक वर्कफ़्लो** - एजेंटों को क्रम से निष्पादित करना जहाँ आउटपुट अगले चरण को जाता है। -**सुपरवाइजर एजेंट पैटर्न** - उन्नत एजेंटिक पैटर्न जहाँ सुपरवाइजर LLM गतिशील रूप से निर्णय करता है कि कौन से उप-एजेंट्स को कॉल करना है। +**सुपरवाइज़र एजेंट पैटर्न** - उन्नत एजेंटिक पैटर्न जहाँ सुपरवाइज़र LLM गतिशील रूप से निर्णय लेता है कि कौन से उप-एजेंट बुलाने हैं। ## मॉडल कॉन्टेक्स्ट प्रोटोकॉल (MCP) - [मॉड्यूल 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j में MCP एकीकरण के लिए Maven निर्भरता। +**langchain4j-mcp** - LangChain4j में MCP एकीकरण के लिए Maven डिपेंडेंसी। -**MCP** - मॉडल कॉन्टेक्स्ट प्रोटोकॉल: बाहरी उपकरणों से जुड़े AI ऐप्स के लिए मानक। एक बार बनाएँ, हर जगह इस्तेमाल करें। +**MCP** - मॉडल कॉन्टेक्स्ट प्रोटोकॉल: AI एप्लिकेशन को बाहरी टूल से जोड़ने का मानक। एक बार बनाएं, हर जगह उपयोग करें। -**MCP क्लाइंट** - MCP सर्वरों से जुड़ने वाला और टूल्स का उपयोग करने वाला एप्लिकेशन। +**MCP क्लाइंट** - एप्लिकेशन जो MCP सर्वरों से जुड़ता है ताकि टूल खोजे और उपयोग किए जा सकें। -**MCP सर्वर** - MCP के माध्यम से उपकरणों को स्पष्ट विवरण और पैरामीटर स्कीमाओं के साथ एक्सपोज़ करने वाली सेवा। +**MCP सर्वर** - सेवा जो MCP के माध्यम से टूल प्रदान करती है, स्पष्ट विवरण और पैरामीटर स्कीमास के साथ। -**McpToolProvider** - LangChain4j घटक जो MCP टूल्स को AI सेवाओं और एजेंट्स में उपयोग के लिए लपेटता है। +**McpToolProvider** - LangChain4j घटक जो MCP टूल्स को AI सेवाओं और एजेंटों के उपयोग के लिए लपेटता है। -**McpTransport** - MCP संचार के लिए इंटरफेस। कार्यान्वयन में Stdio और HTTP शामिल हैं। +**McpTransport** - MCP संचार के लिए इंटरफ़ेस। लागू होने वाले प्रकारों में Stdio और HTTP शामिल हैं। -**Stdio ट्रांसपोर्ट** - stdin/stdout के माध्यम से स्थानीय प्रक्रिया ट्रांसपोर्ट। फाइल सिस्टम एक्सेस या कमांड-लाइन टूल के लिए उपयोगी। +**Stdio ट्रांसपोर्ट** - stdin/stdout के माध्यम से स्थानीय प्रक्रिया ट्रांसपोर्ट। फ़ाइल सिस्टम एक्सेस या कमांड-लाइन टूल के लिए उपयोगी। -**StdioMcpTransport** - MCP सर्वर को subprocess के रूप में चलाने वाली LangChain4j कार्यान्वयन। +**StdioMcpTransport** - LangChain4j कार्यान्वयन जो MCP सर्वर को सबप्रोसेस के रूप में चलाता है। -**टूल डिस्कवरी** - क्लाइंट सर्वर से उपलब्ध टूल के विवरण और स्कीमाएँ पूछता है। +**टूल खोज** - क्लाइंट उपलब्ध टूल्स के लिए सर्वर से विवरण और स्कीमास के साथ पूछताछ करता है। -## Azure सेवाएँ - [मॉड्यूल 01](../01-introduction/README.md) +## एज़्योर सेवाएं - [मॉड्यूल 01](../01-introduction/README.md) **Azure AI Search** - वेक्टर क्षमताओं के साथ क्लाउड खोज। [मॉड्यूल 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Azure संसाधनों को तैनात करता है। +**Azure Developer CLI (azd)** - Azure संसाधनों को डिप्लॉय करता है। -**Azure OpenAI** - Microsoft की एंटरप्राइज AI सेवा। +**Azure OpenAI** - माइक्रोसॉफ्ट की एंटरप्राइज़ AI सेवा। -**Bicep** - Azure इंफ्रास्ट्रक्चर-एज-कोड भाषा। [इन्फ्रास्ट्रक्चर गाइड](../01-introduction/infra/README.md) +**Bicep** - Azure इन्फ्रास्ट्रक्चर-ऐज-कोड भाषा। [इन्फ्रास्ट्रक्चर गाइड](../01-introduction/infra/README.md) **डिप्लॉयमेंट नाम** - Azure में मॉडल डिप्लॉयमेंट का नाम। **GPT-5.2** - तर्क नियंत्रण के साथ नवीनतम OpenAI मॉडल। [मॉड्यूल 02](../02-prompt-engineering/README.md) -## परीक्षण और विकास - [परीक्षण गाइड](TESTING.md) +## टेस्टिंग और विकास - [टेस्टिंग गाइड](TESTING.md) -**Dev Container** - कंटेनरीकृत विकास वातावरण। [कॉन्फ़िगरेशन](../../../.devcontainer/devcontainer.json) +**डेव कंटेनर** - कंटेनरयुक्त विकास पर्यावरण। [कॉन्फ़िगरेशन](../../../.devcontainer/devcontainer.json) -**GitHub मॉडल्स** - मुफ्त AI मॉडल प्लेग्राउंड। [मॉड्यूल 00](../00-quick-start/README.md) +**इन-मेमोरी टेस्टिंग** - इन-मेमोरी स्टोरेज के साथ परीक्षण। -**इन-मेमोरी परीक्षण** - इन-मेमोरी स्टोरेज के साथ परीक्षण। +**इंटीग्रेशन टेस्टिंग** - वास्तविक इन्फ्रास्ट्रक्चर के साथ परीक्षण। -**इंटीग्रेशन टेस्टिंग** - वास्तविक इंफ्रास्ट्रक्चर के साथ परीक्षण। +**Maven** - Java बिल्ड ऑटोमेशन टूल। -**Maven** - जावा बिल्ड ऑटोमेशन टूल। +**Mockito** - Java मॉकिंग फ्रेमवर्क। -**Mockito** - जावा मॉकिंग फ्रेमवर्क। - -**Spring Boot** - जावा एप्लिकेशन फ्रेमवर्क। [मॉड्यूल 01](../01-introduction/README.md) +**Spring Boot** - Java एप्लिकेशन फ्रेमवर्क। [मॉड्यूल 01](../01-introduction/README.md) --- **अस्वीकरण**: -यह दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके अनूदित किया गया है। जबकि हम सटीकता के लिए प्रयासरत हैं, कृपया ध्यान दें कि स्वचालित अनुवाद में त्रुटियां या गलतियां हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही अधिकारिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए पेशेवर मानव अनुवाद की सलाह दी जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम जिम्मेदार नहीं हैं। +इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। \ No newline at end of file diff --git a/translations/hi/docs/TESTING.md b/translations/hi/docs/TESTING.md index 41ec41e9b..4d42167e2 100644 --- a/translations/hi/docs/TESTING.md +++ b/translations/hi/docs/TESTING.md @@ -1,20 +1,20 @@ -# LangChain4j अनुप्रयोगों का परीक्षण +# LangChain4j एप्लिकेशन का परीक्षण ## विषय सूची -- [त्वरित प्रारंभ](../../../docs) -- [परीक्षण क्या कवर करते हैं](../../../docs) -- [परीक्षण चलाना](../../../docs) -- [VS Code में परीक्षण चलाना](../../../docs) -- [परीक्षण पैटर्न](../../../docs) -- [परीक्षण दर्शन](../../../docs) -- [अगले कदम](../../../docs) +- [त्वरित आरंभ](#त्वरित-आरंभ) +- [परीक्षण में क्या शामिल है](#परीक्षण-में-क्या-शामिल-है) +- [परीक्षण कैसे चलाएं](#परीक्षण-कैसे-चलाएं) +- [VS कोड में परीक्षण चलाना](#vs-कोड-में-परीक्षण-चलाना) +- [परीक्षण के पैटर्न](#परीक्षण-के-पैटर्न) +- [परीक्षण के दर्शन](#परीक्षण-के-दर्शन) +- [अगले कदम](#अगले-कदम) -यह गाइड आपको उन परीक्षणों के माध्यम से ले जाता है जो दिखाते हैं कि API कुंजियों या बाहरी सेवाओं की आवश्यकता के बिना AI अनुप्रयोगों का परीक्षण कैसे किया जाए। +यह मार्गदर्शिका आपको उन परीक्षणों से परिचित कराती है जो यह दिखाते हैं कि एआई एप्लिकेशन को बिना API कुंजी या बाहरी सेवाओं की आवश्यकता के कैसे परीक्षण किया जाए। -## त्वरित प्रारंभ +## त्वरित आरंभ -सभी परीक्षण एक कमांड के साथ चलाएं: +सभी परीक्षणों को केवल एक कमांड से चलाएं: **Bash:** ```bash @@ -26,30 +26,29 @@ mvn test mvn --% test ``` -जब सभी परीक्षण सफल हो जाते हैं, तो आपको नीचे दिए गए स्क्रीनशॉट के समान आउटपुट दिखाई देगा — बिना गलती के परीक्षण चलते हैं। +जब सभी परीक्षण सफल होते हैं, तो आपको नीचे दिए गए स्क्रीनशॉट जैसा आउटपुट दिखाई देगा — परीक्षण बिना किसी विफलता के चलते हैं। Successful Test Results -*सफल परीक्षण निष्पादन जो दिखाता है कि सभी परीक्षण बिना किसी असफलता के पास हो गए हैं* +*सभी परीक्षण सफलतापूर्वक चले और कोई विफलता नहीं हुई* -## परीक्षण क्या कवर करते हैं +## परीक्षण में क्या शामिल है -यह कोर्स **यूनिट टेस्ट** पर केंद्रित है जो स्थानीय रूप से चलते हैं। प्रत्येक परीक्षण एक विशिष्ट LangChain4j अवधारणा को अलग से प्रदर्शित करता है। नीचे दिया गया परीक्षण पिरामिड दिखाता है कि यूनिट टेस्ट कहाँ फिट होते हैं — वे तेज़, भरोसेमंद आधार बनाते हैं जिस पर आपकी बाकी परीक्षण रणनीति आधारित होती है। +यह कोर्स मुख्य रूप से **यूनिट टेस्ट** पर केंद्रित है जो स्थानीय रूप से चलते हैं। प्रत्येक परीक्षण LangChain4j की एक विशिष्ट अवधारणा को अकेले दिखाता है। नीचे दिया गया परीक्षण पिरामिड बताता है कि यूनिट टेस्ट कहाँ आते हैं — वे तेज़, विश्वसनीय आधार बनाते हैं जिस पर आपकी बाकी परीक्षण रणनीति आधारित होती है। Testing Pyramid -*परीक्षण पिरामिड जो यूनिट टेस्ट (तेज, अलग), इंटीग्रेशन टेस्ट (वास्तविक घटक), और एंड-टू-एंड टेस्ट के बीच संतुलन दिखाता है। यह प्रशिक्षण यूनिट परीक्षण को कवर करता है।* +*टेस्टिंग पिरामिड जो यूनिट टेस्ट (तेज़, अलग) और इंटीग्रेशन टेस्ट (वास्तविक घटक) और एंड-टू-एंड टेस्ट के बीच संतुलन दिखाता है। यह प्रशिक्षण यूनिट परीक्षण को कवर करता है।* -| मॉड्यूल | परीक्षण | ध्यान केंद्रित | मुख्य फाइलें | +| मॉड्यूल | परीक्षण | फोकस | मुख्य फ़ाइलें | |--------|-------|-------|-----------| -| **00 - त्वरित प्रारंभ** | 6 | प्रॉम्प्ट टेम्पलेट और वेरिएबल प्रतिस्थापन | `SimpleQuickStartTest.java` | -| **01 - परिचय** | 8 | संवाद स्मृति और Stateful चैट | `SimpleConversationTest.java` | +| **01 - परिचय** | 8 | वार्तालाप स्मृति और स्टेटफुल चैट | `SimpleConversationTest.java` | | **02 - प्रॉम्प्ट इंजीनियरिंग** | 12 | GPT-5.2 पैटर्न, उत्सुकता स्तर, संरचित आउटपुट | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | दस्तावेज़ इनटेक, एम्बेडिंग, समानता खोज | `DocumentServiceTest.java` | -| **04 - टूल्स** | 12 | फ़ंक्शन कॉलिंग और टूल चेनिंग | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | मॉडल कंटेक्स्ट प्रोटोकॉल विद Stdio ट्रांसपोर्ट | `SimpleMcpTest.java` | +| **03 - RAG** | 10 | दस्तावेज़ संग्रहण, एम्बेडिंग्स, समानता खोज | `DocumentServiceTest.java` | +| **04 - टूल्स** | 12 | फंक्शन कॉलिंग और टूल चेनिंग | `SimpleToolsTest.java`` | +| **05 - MCP** | 8 | मॉडल कंटेक्स्ट प्रोटोकॉल विथ स्टडियो ट्रांसपोर्ट | `SimpleMcpTest.java` | -## परीक्षण चलाना +## परीक्षण कैसे चलाएं **रूट से सभी परीक्षण चलाएं:** @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**किसी विशेष मॉड्यूल के लिए परीक्षण चलाएं:** +**किसी विशेष मॉड्यूल के परीक्षण चलाएं:** **Bash:** ```bash @@ -75,11 +74,11 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# या root से +# या रूट से mvn --% test -pl 01-introduction ``` -**एकल परीक्षण क्लास चलाएं:** +**एकल टेस्ट क्लास चलाएं:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**विशिष्ट परीक्षण मेथड चलाएं:** +**विशिष्ट टेस्ट मेथड चलाएं:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#वार्तालाप इतिहास को बनाए रखना चाहिए +mvn test -Dtest=SimpleConversationTest#वार्तालाप इतिहास बनाए रखना चाहिए ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#वार्तालाप इतिहास बनाए रखना चाहिए +mvn --% test -Dtest=SimpleConversationTest#क्या बातचीत का इतिहास बनाए रखना चाहिए ``` -## VS Code में परीक्षण चलाना +## VS कोड में परीक्षण चलाना -यदि आप Visual Studio Code का उपयोग कर रहे हैं, तो टेस्ट एक्सप्लोरर परीक्षण चलाने और डीबग करने के लिए एक ग्राफिकल इंटरफ़ेस प्रदान करता है। +यदि आप Visual Studio Code उपयोग कर रहे हैं, तो टेस्ट एक्सप्लोरर आपको परीक्षण चलाने और डीबग करने के लिए एक ग्राफिकल इंटरफेस प्रदान करता है। VS Code Test Explorer -*VS Code टेस्ट एक्सप्लोरर जो सभी जावा परीक्षण क्लास और व्यक्तिगत परीक्षण विधियों के साथ परीक्षण ट्री को दिखाता है* +*VS कोड टेस्ट एक्सप्लोरर सभी जावा टेस्ट क्लासेस और व्यक्तिगत टेस्ट मेथड्स के साथ टेस्ट ट्री दिखा रहा है* -**VS Code में परीक्षण चलाने के लिए:** +**VS कोड में परीक्षण चलाने के लिए:** 1. एक्टिविटी बार में बीकर आइकन पर क्लिक करके टेस्ट एक्सप्लोरर खोलें -2. सभी मॉड्यूल और परीक्षण क्लास देखने के लिए परीक्षण ट्री का विस्तार करें -3. किसी भी परीक्षण के बगल में प्ले बटन पर क्लिक करके उसे अकेले चलाएं -4. पूरी सूट चलाने के लिए "Run All Tests" पर क्लिक करें -5. किसी भी परीक्षण पर राइट-क्लिक करके "Debug Test" चुनें ताकि ब्रेकपॉइंट सेट कर सकें और कोड स्टेप थ्रू कर सकें +2. सभी मॉड्यूल और टेस्ट क्लासेस देखने के लिए टेस्ट ट्री विस्तारित करें +3. किसी भी टेस्ट के बगल में प्ले बटन पर क्लिक करके उसे व्यक्तिगत रूप से चलाएं +4. पूरे टेस्ट सूट को चलाने के लिए "Run All Tests" पर क्लिक करें +5. किसी भी टेस्ट पर राइट-क्लिक करें और "Debug Test" चुनें ताकि ब्रेकपॉइंट सेट करके कोड को चरण-दर-चरण चलाया जा सके -परीक्षण पास होने पर टेस्ट एक्सप्लोरर हरे चेकमार्क दिखाता है और असफल होने पर विस्तृत त्रुटि संदेश प्रदान करता है। +टेस्ट एक्सप्लोरर पास टेस्ट के लिए हरे चेकमार्क दिखाता है और विफल टेस्ट पर विस्तृत त्रुटि संदेश प्रदान करता है। -## परीक्षण पैटर्न +## परीक्षण के पैटर्न -### पैटर्न 1: प्रॉम्प्ट टेम्पलेट का परीक्षण +### पैटर्न 1: प्रॉम्प्ट टेम्प्लेट का परीक्षण -सबसे सरल पैटर्न AI मॉडल को कॉल किए बिना प्रॉम्प्ट टेम्पलेट का परीक्षण करता है। आप जांचते हैं कि वेरिएबल प्रतिस्थापन सही तरीके से काम करता है और प्रॉम्प्ट अपेक्षित रूप में स्वरूपित है। +सबसे सरल पैटर्न प्रॉम्प्ट टेम्प्लेट का परीक्षण करता है बिना किसी AI मॉडल को कॉल किए। आप सत्यापित करते हैं कि वेरिएबल प्रतिस्थापन सही ढंग से काम कर रहा है और प्रॉम्प्ट अपेक्षित फॉर्मेट में हैं। Prompt Template Testing -*प्रॉम्प्ट टेम्पलेट परीक्षण दिखाता है वेरिएबल प्रतिस्थापन फ्लो: प्लेसहोल्डर के साथ टेम्पलेट → मान लागू → स्वरूपित आउटपुट सत्यापित* +*प्रॉम्प्ट टेम्प्लेट परीक्षण जो वेरिएबल प्रतिस्थापन फ्लो दिखाता है: प्लेसहोल्डर्स के साथ टेम्प्लेट → मान लागू किए गए → फॉर्मेटेड आउटपुट सत्यापित* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -यह परीक्षण `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` में मौजूद है। - -**इसे चलाएं:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#परीक्षणप्रॉम्प्टटेम्पलेटफॉर्मैटिंग -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#परीक्षणप्रांप्टटेम्पलेटस्वरूपण -``` +यह पैटर्न सत्यापित करता है कि वेरिएबल प्रतिस्थापन सही है और प्रॉम्प्ट अपेक्षित फॉर्मेट में हैं — किसी API कुंजी या मॉडल कॉल की आवश्यकता नहीं। ### पैटर्न 2: भाषा मॉडलों का मॉकिंग -जब आप संवाद लॉजिक का परीक्षण करते हैं, तो Mockito का उपयोग करके नकली मॉडल बनाएं जो पूर्वनिर्धारित प्रतिक्रियाएं लौटाते हैं। इससे परीक्षण तेज़, मुफ्त और निर्धारक होते हैं। +जब वार्तालाप लॉजिक का परीक्षण किया जाता है, तो Mockito का उपयोग करके फेक मॉडल बनाएं जो पूर्वनिर्धारित प्रतिक्रियाएं लौटाते हैं। इससे परीक्षण तेज़, मुफ्त और निर्णायक होते हैं। Mock vs Real API Comparison -*तुलना दिखाती है कि परीक्षण के लिए मॉक क्यों बेहतर हैं: वे तेज़, मुफ्त, निर्धारक हैं और API कुंजी की आवश्यकता नहीं होती* +*तुलना दिखाती है कि मॉक क्यों परीक्षण के लिए बेहतर हैं: वे तेज़, मुफ्त, निर्णायक होते हैं और API कुंजी की जरूरत नहीं होती* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -यह पैटर्न `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` में मौजूद है। मॉक सुनिश्चित करता है कि व्यवहार सुसंगत रहे ताकि आप मेमोरी प्रबंधन सही ढंग से होता है यह सत्यापित कर सकें। +यह पैटर्न `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` में पाया जाता है। मॉक निश्चित व्यवहार सुनिश्चित करता है ताकि आप स्मृति प्रबंधन की जांच कर सकें। -### पैटर्न 3: संवाद पृथक्करण का परीक्षण +### पैटर्न 3: वार्तालाप अलगाव का परीक्षण -संवाद स्मृति को कई उपयोगकर्ताओं को अलग रखना चाहिए। यह परीक्षण सत्यापित करता है कि संवाद संदर्भों को मिलाते नहीं हैं। +वार्तालाप स्मृति को विभिन्न उपयोगकर्ताओं को अलग रखना चाहिए। यह परीक्षण सत्यापित करता है कि वार्तालाप संदर्भ नहीं मिलाते। Conversation Isolation -*संवाद पृथक्करण परीक्षण जो अलग-अलग उपयोगकर्ताओं के लिए अलग-अलग मेमोरी स्टोर दिखाता है ताकि संदर्भ मिश्रण न हो* +*वार्तालाप अलगाव परीक्षण जो दिखाता है कि अलग-अलग उपयोगकर्ताओं के लिए अलग स्मृति स्टोर होते हैं जिससे संदर्भ नहीं मिश्रित होता* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -प्रत्येक संवाद अपनी स्वतंत्र हिस्ट्री बनाए रखता है। उत्पादन प्रणालियों में, यह पृथक्करण मल्टी-यूजर अनुप्रयोगों के लिए महत्वपूर्ण है। +प्रत्येक वार्तालाप अपनी स्वतंत्र इतिहास रखता है। उत्पादन सिस्टम में यह अलगाव मल्टी-यूजर एप्लिकेशन के लिए महत्वपूर्ण है। -### पैटर्न 4: टूल्स को स्वतंत्र रूप से परीक्षण करना +### पैटर्न 4: टूल्स का स्वतंत्र परीक्षण -टूल वे फंक्शन हैं जिन्हें AI कॉल कर सकता है। उन्हें सीधे परीक्षण करें ताकि यह सुनिश्चित हो कि वे AI निर्णयों से स्वतंत्र रूप से सही काम करते हैं। +टूल्स वे फंक्शन हैं जिन्हें AI कॉल कर सकता है। इन्हें सीधे परीक्षण करें ताकि यह सुनिश्चित हो सके कि वे AI निर्णयों से स्वतंत्र सही काम करते हैं। Tools Testing -*टूल परीक्षण जो मॉक टूल के निष्पादन को बिना AI कॉल के दिखाता है ताकि बिजनेस लॉजिक सत्यापित किया जा सके* +*टूल्स का स्वतंत्र परीक्षण जो दिखाता है कि मॉक टूल निष्पादन बिना AI कॉल के व्यावसायिक लॉजिक को सत्यापित करता है* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -ये परीक्षण `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` से हैं जो AI शामिल किए बिना टूल लॉजिक की पुष्टि करते हैं। चेनिंग उदाहरण दिखाता है कि कैसे एक टूल का आउटपुट दूसरे के इनपुट में जाता है। +`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` के ये परीक्षण टूल लॉजिक को AI भागीदारी के बिना सत्यापित करते हैं। चेनिंग उदाहरण दिखाता है कि कैसे एक टूल का आउटपुट दूसरे के इनपुट में जाता है। ### पैटर्न 5: इन-मेमोरी RAG परीक्षण -RAG सिस्टम आमतौर पर वेक्टर डेटाबेस और एम्बेडिंग सेवाओं की आवश्यकता होते हैं। इन-मेमोरी पैटर्न आपको पूरी पाइपलाइन बाहरी आश्रयों के बिना परीक्षण करने देता है। +RAG सिस्टम पारंपरिक रूप से वेक्टर डेटाबेस और एम्बेडिंग सेवाओं की आवश्यकता रखते हैं। इन-मेमोरी पैटर्न पूरी पाइपलाइन को बाहरी निर्भरताओं के बिना परीक्षण करने देता है। In-Memory RAG Testing -*इन-मेमोरी RAG परीक्षण वर्कफ़्लो जो दस्तावेज़ पार्सिंग, एम्बेडिंग संग्रहण, और समानता खोज दिखाता है बिना डेटाबेस की आवश्यकता के* +*इन-मेमोरी RAG परीक्षण वर्कफ़्लो दिखाता है जो दस्तावेज़ पार्सिंग, एम्बेडिंग स्टोरेज, और समानता खोज बिना डेटाबेस की जरूरत के करता है* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -यह परीक्षण `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` में है जो मेमोरी में एक दस्तावेज़ बनाता है और चंकिन्ग तथा मेटाडेटा हैंडलिंग सत्यापित करता है। +यह परीक्षण `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` से है जो मेमोरी में दस्तावेज़ बनाता है और चंकिनग तथा मेटाडेटा हैंडलिंग को सत्यापित करता है। ### पैटर्न 6: MCP इंटीग्रेशन परीक्षण -MCP मॉड्यूल मॉडल कंटेक्स्ट प्रोटोकॉल एकीकरण को stdio ट्रांसपोर्ट के माध्यम से परीक्षण करता है। ये परीक्षण सत्यापित करते हैं कि आपका ऐप MCP सर्वर को सक्सप्रोसेस के रूप में लॉन्च और संचार कर सकता है। +MCP मॉड्यूल मॉडल कंटेक्स्ट प्रोटोकॉल इंटीग्रेशन का परीक्षण stdio ट्रांसपोर्ट के साथ करता है। ये परीक्षण सत्यापित करते हैं कि आपका एप्लिकेशन MCP सर्वर्स को subprocess के रूप में स्पॉन कर सकता है और उनसे संवाद स्थापित कर सकता है। -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` में परीक्षण MCP क्लाइंट व्यवहार की पुष्टि करते हैं। +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` में ये परीक्षण MCP क्लाइंट व्यवहार को सत्यापित करते हैं। -**इन्हें चलाएं:** +**उन्हें चलाएं:** **Bash:** ```bash @@ -326,30 +313,29 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## परीक्षण दर्शन +## परीक्षण के दर्शन -अपने कोड का परीक्षण करें, AI का नहीं। आपके परीक्षण कोड की जांच करनी चाहिए कि प्रॉम्प्ट कैसे बनाए गए हैं, मेमोरी कैसे प्रबंधित होती है, और टूल कैसे निष्पादित होते हैं। AI प्रतिक्रियाएँ भिन्न हो सकती हैं और उन्हें परीक्षण दावों में शामिल नहीं किया जाना चाहिए। खुद से पूछें कि क्या आपका प्रॉम्प्ट टेम्पलेट वेरिएबल सही ढंग से प्रतिस्थापित करता है, न कि AI सही उत्तर देता है या नहीं। +अपने कोड का परीक्षण करें, AI का नहीं। आपके परीक्षण लिखे गए कोड का सत्यापन करना चाहिए यह जांचकर कि प्रॉम्प्ट कैसे बनाए गए, स्मृति का प्रबंधन कैसे हुआ, और टूल कैसे क्रियान्वित हुए। AI उत्तर बदलते रहते हैं और उन्हें टेस्ट असर्शन में नहीं शामिल किया जाना चाहिए। स्वयं से पूछें कि क्या आपका प्रॉम्प्ट टेम्प्लेट सही वेरिएबल्स डाल रहा है, न कि AI सही उत्तर देता है या नहीं। -भाषा मॉडलों के लिए मॉक का उपयोग करें। वे बाहरी निर्भरता हैं जो धीमे, महंगे, और गैर-निर्धारक होते हैं। मॉकिंग परीक्षण को तेजी से बनाता है (मिलीसेकंड में बजाय सेकंड के), मुफ्त API लागत से मुक्त, और हर बार समान परिणाम के साथ निर्धारक। +भाषा मॉडलों के लिए मॉक का उपयोग करें। वे बाहरी निर्भरताएं हैं जो धीमी, महँगी, और गैर-निर्णायक होती हैं। मॉकिंग से परीक्षण तेज़, मुफ्त, और हमेशा समान परिणाम के साथ होते हैं। -परीक्षण स्वतंत्र रखें। प्रत्येक परीक्षण को अपने डेटा को सेटअप करना चाहिए, अन्य परीक्षणों पर निर्भर नहीं होना चाहिए, और खुद को साफ करना चाहिए। परीक्षण निष्पादन क्रम से स्वतंत्र रूप से पास होना चाहिए। +परीक्षण स्वतंत्र रखें। प्रत्येक परीक्षण अपनी डेटा सेटअप करे, अन्य परीक्षणों पर निर्भर न रहे, और अपने बाद साफ-सफाई करे। परीक्षण निष्पादन क्रम से स्वतंत्र होने चाहिए। -सुखद मार्ग से परे किनारे के मामले भी टेस्ट करें। खाली इनपुट, बहुत बड़े इनपुट, विशेष अक्षर, अवैध पैरामीटर, और सीमा स्थितियां आज़माएं। ये अक्सर बग उजागर करते हैं जिन्हें सामान्य उपयोग नहीं दिखाता। +साधारण मार्ग के परे किनारे के मामलों का परीक्षण करें। खाली इनपुट, बहुत बड़े इनपुट, विशेष अक्षर, अमान्य पैरामीटर और सीमा शर्तें आजमाएं। ये अक्सर ऐसे बग्स उजागर करते हैं जो सामान्य उपयोग में नहीं दिखते। -वर्णनात्मक नामों का उपयोग करें। `shouldMaintainConversationHistoryAcrossMultipleMessages()` की तुलना `test1()` से करें। पहला स्पष्ट रूप से बताता है कि क्या परीक्षण किया जा रहा है, जिससे डिबगिंग में आसानी होती है। +वर्णनात्मक नामों का उपयोग करें। `shouldMaintainConversationHistoryAcrossMultipleMessages()` की तुलना `test1()` से करें। पहला नाम स्पष्ट करता है कि क्या परीक्षण हो रहा है, जिससे त्रुटि निवारण आसान होता है। ## अगले कदम -अब जब आप परीक्षण पैटर्न समझ चुके हैं, तो प्रत्येक मॉड्यूल में गहराई से जाएं: +अब जब आप परीक्षण पैटर्न समझ गए हैं, तो प्रत्येक मॉड्यूल में गहराई से जाएं: -- **[00 - त्वरित प्रारंभ](../00-quick-start/README.md)** - प्रॉम्प्ट टेम्पलेट के मूल से शुरुआत करें -- **[01 - परिचय](../01-introduction/README.md)** - संवाद स्मृति प्रबंधन सीखें +- **[01 - परिचय](../01-introduction/README.md)** - वार्तालाप स्मृति प्रबंधन सीखें - **[02 - प्रॉम्प्ट इंजीनियरिंग](../02-prompt-engineering/README.md)** - GPT-5.2 प्रॉम्प्टिंग पैटर्न मास्टर करें -- **[03 - RAG](../03-rag/README.md)** - रिट्रीवल-ऑगमेंटेड जनरेशन सिस्टम बनाएं -- **[04 - टूल्स](../04-tools/README.md)** - फ़ंक्शन कॉलिंग और टूल चेन लागू करें -- **[05 - MCP](../05-mcp/README.md)** - मॉडल कंटेक्स्ट प्रोटोकॉल को एकीकृत करें +- **[03 - RAG](../03-rag/README.md)** - पुनःप्राप्ति-संवर्धित जनरेशन सिस्टम बनाएं +- **[04 - टूल्स](../04-tools/README.md)** - फंक्शन कॉलिंग और टूल चेन इम्प्लीमेंट करें +- **[05 - MCP](../05-mcp/README.md)** - मॉडल कंटेक्स्ट प्रोटोकॉल इंटीग्रेट करें -प्रत्येक मॉड्यूल की README यहाँ परीक्षण किए गए अवधारणाओं के विस्तृत स्पष्टीकरण प्रदान करती है। +प्रत्येक मॉड्यूल का README यहां परीक्षण किए गए अवधारणाओं का विस्तृत विवरण प्रदान करता है। --- @@ -358,6 +344,6 @@ cd 05-mcp; mvn --% test --- -**अस्वीकरण**: -इस दस्तावेज़ का अनुवाद एआई अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। हालांकि हम सटीकता के लिए प्रयासरत हैं, कृपया ध्यान दें कि स्वचालित अनुवाद में त्रुटियाँ या असंगतियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सलाह दी जाती है। इस अनुवाद के उपयोग से होने वाली किसी भी गलतफहमी या गलत व्याख्या की जिम्मेदारी हम पर नहीं होगी। +**अस्वीकरण**: +इस दस्तावेज़ का अनुवाद AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) का उपयोग करके किया गया है। जबकि हम सटीकता के लिए प्रयास करते हैं, कृपया ध्यान दें कि स्वचालित अनुवादों में त्रुटियाँ या अशुद्धियाँ हो सकती हैं। मूल दस्तावेज़ अपनी मूल भाषा में ही प्रामाणिक स्रोत माना जाना चाहिए। महत्वपूर्ण जानकारी के लिए, पेशेवर मानव अनुवाद की सिफारिश की जाती है। इस अनुवाद के उपयोग से उत्पन्न किसी भी गलतफहमी या गलत व्याख्या के लिए हम उत्तरदायी नहीं हैं। \ No newline at end of file diff --git a/translations/hr/.co-op-translator.json b/translations/hr/.co-op-translator.json index c598542e9..730b9f231 100644 --- a/translations/hr/.co-op-translator.json +++ b/translations/hr/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "hr" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T03:41:22+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T11:20:14+00:00", "source_file": "01-introduction/README.md", "language_code": "hr" }, @@ -18,20 +18,20 @@ "language_code": "hr" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T03:43:19+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T11:15:57+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "hr" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T03:44:32+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T11:19:25+00:00", "source_file": "03-rag/README.md", "language_code": "hr" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:43:47+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T11:18:09+00:00", "source_file": "04-tools/README.md", "language_code": "hr" }, @@ -54,8 +54,8 @@ "language_code": "hr" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:03:28+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T11:14:41+00:00", "source_file": "README.md", "language_code": "hr" }, @@ -72,14 +72,14 @@ "language_code": "hr" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T03:47:22+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T11:16:27+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "hr" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T03:48:06+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T11:17:04+00:00", "source_file": "docs/TESTING.md", "language_code": "hr" } diff --git a/translations/hr/00-quick-start/README.md b/translations/hr/00-quick-start/README.md deleted file mode 100644 index 4f9837c65..000000000 --- a/translations/hr/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modul 00: Brzi početak - -## Sadržaj - -- [Uvod](../../../00-quick-start) -- [Što je LangChain4j?](../../../00-quick-start) -- [Ovisnosti LangChain4j](../../../00-quick-start) -- [Preduvjeti](../../../00-quick-start) -- [Postavljanje](../../../00-quick-start) - - [1. Nabavite svoj GitHub token](../../../00-quick-start) - - [2. Postavite svoj token](../../../00-quick-start) -- [Pokrenite primjere](../../../00-quick-start) - - [1. Osnovni chat](../../../00-quick-start) - - [2. Uzorci prompta](../../../00-quick-start) - - [3. Pozivanje funkcija](../../../00-quick-start) - - [4. Pitanja i odgovori o dokumentima (Easy RAG)](../../../00-quick-start) - - [5. Odgovorni AI](../../../00-quick-start) -- [Što svaki primjer prikazuje](../../../00-quick-start) -- [Sljedeći koraci](../../../00-quick-start) -- [Rješavanje problema](../../../00-quick-start) - -## Uvod - -Ovaj brzi početak namijenjen je da vas što brže uvede u rad s LangChain4j. Obuhvaća apsolutne osnove izgradnje AI aplikacija s LangChain4j i GitHub modelima. U sljedećim modulima prelazite na Azure OpenAI i GPT-5.2 te dublje istražujete svaki koncept. - -## Što je LangChain4j? - -LangChain4j je Java biblioteka koja pojednostavljuje izradu aplikacija pokretanih umjetnom inteligencijom. Umjesto da se bavite HTTP klijentima i parsiranjem JSON-a, radite s čistim Java API-jima. - -"Chain" u LangChain odnosi se na povezivanje više komponenti – možete povezati prompt s modelom, zatim s parserom ili povezati više AI poziva gdje jedan izlaz služi kao sljedeći ulaz. Ovaj brzi početak fokusira se na osnove prije istraživanja složenijih lanaca. - -Koncept povezivanja u LangChain4j - -*Povezivanje komponenti u LangChain4j – gradivni blokovi koji se spajaju u moćne AI radne tijekove* - -Koristit ćemo tri glavne komponente: - -**ChatModel** - Sučelje za interakciju s AI modelima. Pozovite `model.chat("prompt")` i dobit ćete odgovor kao niz znakova. Koristimo `OpenAiOfficialChatModel` koji radi s OpenAI-kompatibilnim krajnjim točkama poput GitHub modela. - -**AiServices** - Stvara tip-sigurna AI sučelja za usluge. Definirajte metode, označite ih s `@Tool` i LangChain4j upravlja orkestracijom. AI automatski poziva vaše Java metode kad je potrebno. - -**MessageWindowChatMemory** - Održava povijest razgovora. Bez ovoga, svaki zahtjev je neovisan. S njim, AI pamti prethodne poruke i održava kontekst kroz više okreta. - -Arhitektura LangChain4j - -*Arhitektura LangChain4j – ključne komponente koje zajedno pokreću vaše AI aplikacije* - -## Ovisnosti LangChain4j - -Ovaj brzi početak koristi tri Maven ovisnosti u [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modul `langchain4j-open-ai-official` pruža klasu `OpenAiOfficialChatModel` koja se povezuje s OpenAI-kompatibilnim API-jima. GitHub modeli koriste isti API format, stoga nije potreban poseban adapter - samo usmjerite osnovnu URL adresu na `https://models.github.ai/inference`. - -Modul `langchain4j-easy-rag` pruža automatsko dijeljenje dokumenata, ugradnju i dohvat, tako da možete izgraditi RAG aplikacije bez ručnog podešavanja svakog koraka. - -## Preduvjeti - -**Koristite li Dev Container?** Java i Maven su već instalirani. Trebate samo GitHub osobni token za pristup. - -**Lokalni razvoj:** -- Java 21+, Maven 3.9+ -- GitHub osobni token za pristup (upute dolje) - -> **Napomena:** Ovaj modul koristi `gpt-4.1-nano` iz GitHub modela. Nemojte mijenjati ime modela u kodu – konfigurirano je za rad s dostupnim GitHub modelima. - -## Postavljanje - -### 1. Nabavite svoj GitHub token - -1. Idite na [GitHub postavke → Osobni tokeni za pristup](https://github.com/settings/personal-access-tokens) -2. Kliknite "Generate new token" -3. Postavite opisni naziv (npr. "LangChain4j Demo") -4. Postavite rok trajanja (preporučeno 7 dana) -5. U odjeljku "Account permissions" pronađite "Models" i postavite na "Read-only" -6. Kliknite "Generate token" -7. Kopirajte i spremite svoj token – više ga nećete vidjeti - -### 2. Postavite svoj token - -**Opcija 1: Korištenje VS Code (preporučeno)** - -Ako koristite VS Code, dodajte token u `.env` datoteku u korijenu projekta: - -Ako `.env` datoteka ne postoji, kopirajte `.env.example` u `.env` ili kreirajte novu `.env` datoteku u korijenu projekta. - -**Primjer `.env` datoteke:** -```bash -# U /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Zatim jednostavno desnim klikom na bilo koju demo datoteku (npr. `BasicChatDemo.java`) u Exploreru odaberite **"Run Java"** ili koristite konfiguracije za pokretanje u Run and Debug panelu. - -**Opcija 2: Korištenje terminala** - -Postavite token kao varijablu okoline: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Pokrenite primjere - -**Korištenje VS Code:** Jednostavno desni klik na bilo koju demo datoteku u Exploreru i odaberite **"Run Java"**, ili koristite konfiguracije za pokretanje iz Run and Debug panela (uvjerite se da ste prethodno dodali token u `.env` datoteku). - -**Korištenje Mavena:** Također možete pokrenuti iz naredbenog retka: - -### 1. Osnovni chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Uzorci prompta - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Prikazuje zero-shot, few-shot, chain-of-thought i promptanje temeljeno na ulozi. - -### 3. Pozivanje funkcija - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI automatski poziva vaše Java metode kad je potrebno. - -### 4. Pitanja i odgovori o dokumentima (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Postavite pitanja o svojim dokumentima koristeći Easy RAG s automatskom ugradnjom i dohvatom. - -### 5. Odgovorni AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Pogledajte kako sigurnosni filtri AI blokiraju štetni sadržaj. - -## Što svaki primjer prikazuje - -**Osnovni chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Započnite ovdje da vidite LangChain4j u najjednostavnijem obliku. Kreirat ćete `OpenAiOfficialChatModel`, poslati prompt s `.chat()` i dobiti povratni odgovor. Ovo pokazuje temelj: kako inicijalizirati modele s prilagođenim krajnjim točkama i API ključevima. Kad shvatite ovaj obrazac, sve ostalo se nadograđuje na njega. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) i pitajte: -> - "Kako prelazim s GitHub modela na Azure OpenAI u ovom kodu?" -> - "Koje druge parametre mogu konfigurirati u OpenAiOfficialChatModel.builder()?" -> - "Kako dodati streaming odgovore umjesto čekanja cijelog odgovora?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Sad kad znate kako razgovarati s modelom, istražimo što mu govorite. Ovaj demo koristi istu konfiguraciju modela, ali pokazuje pet različitih obrazaca promptanja. Isprobajte zero-shot promptove za izravne upute, few-shot promptove koji uče iz primjera, chain-of-thought promptove koji otkrivaju korake razmišljanja i promptove temeljene na ulozi koji postavljaju kontekst. Vidjet ćete kako isti model daje dramatično različite rezultate ovisno o načinu postavljanja zahtjeva. - -Demo također pokazuje predloške prompta (`PromptTemplate`), moćan način za kreiranje ponovno upotrebljivih promptova s varijablama. -Sljedeći primjer prikazuje prompt koji koristi LangChain4j `PromptTemplate` za popunjavanje varijabli. AI će odgovoriti na temelju danog odredišta i aktivnosti. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) i pitajte: -> - "Koja je razlika između zero-shot i few-shot promptanja i kada koristiti svaki?" -> - "Kako parametar temperature utječe na odgovore modela?" -> - "Koje tehnike postoje za sprječavanje napada ubacivanjem promptova u produkciji?" -> - "Kako mogu kreirati ponovo upotrebljive Predloške Promptova za uobičajene obrasce?" - -**Integracija alata** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Ovdje LangChain4j postaje moćan. Koristit ćete `AiServices` da kreirate AI asistenta koji može pozivati vaše Java metode. Samo označite metode s `@Tool("opis")` i LangChain4j se brine za ostalo – AI automatski odlučuje kada koristiti koji alat na temelju korisničkih zahtjeva. Ovo pokazuje pozivanje funkcija, ključnu tehniku za izgradnju AI koja može poduzimati radnje, ne samo odgovarati na pitanja. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) i pitajte: -> - "Kako radi @Tool anotacija i što LangChain4j radi s njom u pozadini?" -> - "Može li AI pozvati više alata u nizu za rješavanje složenih problema?" -> - "Što se događa ako alat baci iznimku – kako bih trebao rukovati greškama?" -> - "Kako bih integrirao pravi API umjesto ovog primjera kalkulatora?" - -**Pitanja i odgovori o dokumentima (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Ovdje ćete vidjeti RAG (generiranje potpomognuto dohvaćanjem) koristeći LangChain4j pristup "Easy RAG". Dokumenti se učitavaju, automatski dijele i ugrađuju u memorijsko spremište, zatim pretraživač sadržaja isporučuje relevantne dijelove AI tijekom upita. AI odgovara na temelju vaših dokumenata, a ne svoje opće baze znanja. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) i pitajte: -> - "Kako RAG sprječava AI halucinacije u usporedbi s korištenjem podataka o treningu modela?" -> - "Koja je razlika između ovog jednostavnog pristupa i prilagođene RAG cijevi?" -> - "Kako bih ovo skalirao za rad s više dokumenata ili većim bazama znanja?" - -**Odgovorni AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Izgradite sigurnost AI s obrambenim slojevima. Ovaj demo prikazuje dva sloja zaštite koji rade zajedno: - -**Dio 1: LangChain4j Input Guardrails** - Blokiraju opasne promptove prije nego što dođu do LLM-a. Kreirajte prilagođene zaštitne mehanizme koji provjeravaju zabranjene ključne riječi ili obrasce. Oni se izvršavaju u vašem kodu, pa su brzi i besplatni. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Dio 2: Provajderovi sigurnosni filtri** - GitHub modeli imaju ugrađene filtre koji hvataju ono što vaši guardrailsi mogu propustiti. Vidjet ćete stroge blokade (HTTP 400 greške) za teška kršenja i blage odbijanja gdje AI ljubazno odbija. - -> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) i pitajte: -> - "Što je InputGuardrail i kako napraviti vlastiti?" -> - "Koja je razlika između stroge blokade i blagoga odbijanja?" -> - "Zašto koristiti istovremeno guardrails i filtre provajdera?" - -## Sljedeći koraci - -**Sljedeći modul:** [01-introduction - Početak rada s LangChain4j](../01-introduction/README.md) - ---- - -**Navigacija:** [← Povratak na glavni](../README.md) | [Dalje: Modul 01 - Uvod →](../01-introduction/README.md) - ---- - -## Rješavanje problema - -### Prvo pokretanje Mavena - -**Problem**: Prvi `mvn clean compile` ili `mvn package` traje dugo (10-15 minuta) - -**Uzrok**: Maven treba preuzeti sve ovisnosti projekta (Spring Boot, LangChain4j biblioteke, Azure SDK-ove itd.) prilikom prvog builda. - -**Rješenje**: Ovo je normalno. Sljedeći buildovi bit će znatno brži jer se ovisnosti nalaze u lokalnoj predmemoriji. Vrijeme preuzimanja ovisi o brzini vaše mreže. - -### Sintaksa PowerShell Maven naredbe - -**Problem**: Maven naredbe ne uspijevaju s pogreškom `Unknown lifecycle phase ".mainClass=..."` -**Uzrok**: PowerShell interpretira `=` kao operator dodjele varijabli, što prekida sintaksu Maven svojstava - -**Rješenje**: Koristite operator za zaustavljanje parsiranja `--%` prije Maven naredbe: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operator `--%` govori PowerShellu da sve preostale argumente proslijedi doslovno Maven-u bez interpretacije. - -### Prikaz emotikona u Windows PowerShellu - -**Problem**: AI odgovori pokazuju čudne znakove (npr. `????` ili `â??`) umjesto emotikona u PowerShellu - -**Uzrok**: Zadani kôd znakova PowerShella ne podržava UTF-8 emotikone - -**Rješenje**: Pokrenite ovu naredbu prije izvođenja Java aplikacija: -```cmd -chcp 65001 -``` - -Ovo prisiljava UTF-8 kodiranje u terminalu. Alternativno, koristite Windows Terminal koji ima bolju podršku za Unicode. - -### Otklanjanje pogrešaka u API pozivima - -**Problem**: Greške pri autentikaciji, ograničenja brzine ili neočekivani odgovori s AI modela - -**Rješenje**: Primjeri uključuju `.logRequests(true)` i `.logResponses(true)` za prikaz API poziva u konzoli. Ovo pomaže u otklanjanju grešaka pri autentikaciji, ograničenjima brzine ili neočekivanim odgovorima. U proizvodnji uklonite ove oznake kako biste smanjili buku u zapisima. - ---- - - -**Odricanje od odgovornosti**: -Ovaj je dokument preveden korištenjem AI usluge prevođenja [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporučuje se profesionalni ljudski prijevod. Ne preuzimamo odgovornost za bilo kakve nesporazume ili pogrešna tumačenja koja proizlaze iz korištenja ovog prijevoda. - \ No newline at end of file diff --git a/translations/hr/01-introduction/README.md b/translations/hr/01-introduction/README.md index 645bf8826..fa8afa525 100644 --- a/translations/hr/01-introduction/README.md +++ b/translations/hr/01-introduction/README.md @@ -2,37 +2,37 @@ ## Sadržaj -- [Video vodič](../../../01-introduction) -- [Što ćete naučiti](../../../01-introduction) -- [Preduvjeti](../../../01-introduction) -- [Razumijevanje osnovnog problema](../../../01-introduction) -- [Razumijevanje tokena](../../../01-introduction) -- [Kako memorija funkcionira](../../../01-introduction) -- [Kako se koristi LangChain4j](../../../01-introduction) -- [Implementacija Azure OpenAI infrastrukture](../../../01-introduction) -- [Pokretanje aplikacije lokalno](../../../01-introduction) -- [Korištenje aplikacije](../../../01-introduction) - - [Stateless chat (lijevi panel)](../../../01-introduction) - - [Stateful chat (desni panel)](../../../01-introduction) -- [Sljedeći koraci](../../../01-introduction) +- [Video vodič](#video-vodič) +- [Što ćete naučiti](#što-ćete-naučiti) +- [Preduvjeti](#preduvjeti) +- [Razumijevanje osnovnog problema](#razumijevanje-osnovnog-problema) +- [Razumijevanje tokena](#razumijevanje-tokena) +- [Kako radna memorija funkcionira](#kako-radna-memorija-funkcionira) +- [Kako se koristi LangChain4j](#kako-se-koristi-langchain4j) +- [Implementacija Azure OpenAI infrastrukture](#implementacija-azure-openai-infrastrukture) +- [Pokretanje aplikacije lokalno](#pokretanje-aplikacije-lokalno) +- [Korištenje aplikacije](#korištenje-aplikacije) + - [Statički razgovor (lijevi panel)](#statički-razgovor-lijevi-panel) + - [Dinamički razgovor (desni panel)](#dinamički-razgovor-desni-panel) +- [Sljedeći koraci](#sljedeći-koraci) ## Video vodič -Pogledajte ovu live sesiju koja objašnjava kako započeti s ovim modulom: +Pogledajte ovu snimku uživo koja objašnjava kako započeti s ovim modulom: Getting Started with LangChain4j - Live Session ## Što ćete naučiti -U brzom početku koristili ste GitHub modele za slanje upita, pozivanje alata, izgradnju RAG pipelinea i testiranje zaštitnih ograda. Ti su demonstracijski primjeri pokazali što je moguće — sada prelazimo na Azure OpenAI i GPT-5.2 te započinjemo izgradnju aplikacija u produkcijskom stilu. Ovaj modul fokusira se na konverzacijski AI koji pamti kontekst i održava stanje — pojmove koje su ti primjeri u brzom početku koristili u pozadini ali nisu objasnili. +Ovo je vaša polazna točka s LangChain4j i Azure OpenAI. Počinjemo s osnovama i krećemo izgraditi proizvodne aplikacije. Ovaj modul se fokusira na konverzacijski AI koji pamti kontekst i održava stanje — temeljne koncepte na kojima se grade svi kasniji moduli. -Koristit ćemo Azure OpenAI GPT-5.2 kroz ovaj vodič jer njegove napredne sposobnosti rezoniranja čine ponašanje različitih šablona jasnijim. Kada dodate memoriju, jasno ćete vidjeti razliku. To olakšava razumijevanje što svaki komponent donosi vašoj aplikaciji. +Koristit ćemo Azure OpenAI-jev GPT-5.2 kroz ovaj vodič jer njegove napredne sposobnosti rezoniranja jasno pokazuju ponašanje raznih obrazaca. Kada dodate memoriju, razlika postaje očita. To olakšava razumijevanje što svaki dio donosi vašoj aplikaciji. -Izgradit ćete jednu aplikaciju koja demonstrira oba šablona: +Izgradit ćete jednu aplikaciju koja demonstrira oba obrasca: -**Stateless chat** - Svaki zahtjev je neovisan. Model nema memoriju prethodnih poruka. To je šablon koji ste koristili u brzom početku. +**Stateless Chat** - Svaki zahtjev je samostalan. Model nema memoriju prethodnih poruka. Ovo je najsimpiljnija polazna točka. -**Stateful conversation** - Svaki zahtjev uključuje povijest razgovora. Model održava kontekst kroz više okretaja. To je ono što produkcijske aplikacije zahtijevaju. +**Stateful Conversation** - Svaki zahtjev uključuje povijest razgovora. Model održava kontekst kroz više okretaja. To je ono što proizvodne aplikacije zahtijevaju. ## Preduvjeti @@ -41,37 +41,37 @@ Izgradit ćete jednu aplikaciju koja demonstrira oba šablona: - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Napomena:** Java, Maven, Azure CLI i Azure Developer CLI (azd) su predinstalirani u priloženom devcontaineru. +> **Napomena:** Java, Maven, Azure CLI i Azure Developer CLI (azd) su unaprijed instalirani u priloženom razvojnom kontejneru. -> **Napomena:** Ovaj modul koristi GPT-5.2 na Azure OpenAI. Implementacija se konfigurira automatski putem `azd up` — nemojte mijenjati naziv modela u kodu. +> **Napomena:** Ovaj modul koristi GPT-5.2 na Azure OpenAI. Implementacija se automatski konfigurira putem `azd up` - nemojte mijenjati ime modela u kodu. ## Razumijevanje osnovnog problema -Jezik modeli su bez stanja (stateless). Svaki API poziv je neovisan. Ako pošaljete "Moje ime je John" i zatim pitate "Kako se zovem?", model nema pojma da ste se upravo predstavili. On tretira svaki zahtjev kao da je prvi razgovor koji ste ikada imali. +Jezični modeli su bezstanja. Svaki API poziv je nezavisan. Ako pošaljete "Moje ime je John" pa zatim pitate "Kako se zovem?", model nema pojma da ste se upravo predstavili. Svaki zahtjev tretira kao da je prvi razgovor koji ste ikada vodili. -To je u redu za jednostavna pitanja i odgovore, ali beskorisno za prave aplikacije. Botovi za korisničku podršku trebaju pamtiti što ste im rekli. Osobni asistenti trebaju kontekst. Svaki višekratni razgovor zahtijeva memoriju. +To je u redu za jednostavna pitanja i odgovore, ali beskorisno za stvarne aplikacije. Botovi za korisničku službu moraju pamtiti što ste im rekli. Osobni asistenti trebaju kontekst. Svaki višekratni razgovor zahtijeva memoriju. -Sljedeći dijagram prikazuje kontrast dvaju pristupa — lijevo je stateless poziv koji zaboravlja vaše ime; desno je stateful poziv podržan ChatMemory koji ga pamti. +Sljedeća dijagram prikazuje kontrast dvaju pristupa — lijevo je bezstanični poziv koji zaboravlja vaše ime; desno je sa stanjem, potpomognut ChatMemory, koji ga pamti. Stateless vs Stateful Conversations -*Razlika između stateless (neovisnih poziva) i stateful (svjestan konteksta) razgovora* +*Razlika između bezstanih (nezavisnih poziva) i stanju svjesnih (kontekstnih) razgovora* ## Razumijevanje tokena -Prije nego što zaronite u razgovore, važno je razumjeti tokene - osnovne jedinice teksta koje jezični modeli obrađuju: +Prije nego što zaronimo u razgovore, važno je razumjeti tokene - osnovne jedinice teksta koje jezični modeli obrađuju: Token Explanation -*Primjer kako se tekst dijeli na tokene - "Volim AI!" postaje 4 zasebne jedinice za obradu* +*Primjer kako se tekst dijeli na tokene - "I love AI!" postaje 4 zasebne jedinice za obradu* -Tokeni su način na koji AI modeli mjere i obrađuju tekst. Riječi, interpunkcija pa čak i razmaci mogu biti tokene. Vaš model ima ograničenje koliko tokena može obraditi odjednom (400.000 za GPT-5.2, s do 272.000 ulaznih tokena i 128.000 izlaznih tokena). Razumijevanje tokena pomaže u upravljanju duljinom razgovora i troškovima. +Tokeni su način na koji AI modeli mjere i obrađuju tekst. Riječi, interpunkcija pa čak i praznine mogu biti tokeni. Vaš model ima ograničenje koliko tokena može obraditi odjednom (400.000 za GPT-5.2, s do 272.000 ulaznih tokena i 128.000 izlaznih tokena). Razumijevanje tokena pomaže u upravljanju duljinom razgovora i troškovima. -## Kako memorija funkcionira +## Kako radna memorija funkcionira -Chat memorija rješava problem stateless tako što održava povijest razgovora. Prije nego što pošaljete zahtjev modelu, okvir prethodno dodaje relevantne prethodne poruke. Kada pitate "Kako se zovem?", sustav zapravo šalje cijelu povijest razgovora, što modelu omogućuje da vidi da ste prije rekli "Moje ime je John." +Chat memorija rješava problem bezstanja tako što održava povijest razgovora. Prije nego što pošaljete zahtjev modelu, okvir prethodno dodaje relevantne prethodne poruke. Kad pitate "Kako se zovem?", sustav zapravo šalje cijelu povijest razgovora, dopuštajući modelu da vidi da ste ranije rekli "Moje ime je John." -LangChain4j pruža implementacije memorije koje to automatski upravljaju. Odaberete koliko poruka želite zadržati, a okvir upravlja kontekstualnim prozorom. Dijagram ispod pokazuje kako MessageWindowChatMemory održava klizni prozor nedavnih poruka. +LangChain4j nudi implementacije memorije koje to automatski rješavaju. Vi birate koliko poruka želite sačuvati, a okvir upravlja kontekstnim prozorom. Dijagram ispod prikazuje kako MessageWindowChatMemory održava klizni prozor nedavnih poruka. Memory Window Concept @@ -79,7 +79,7 @@ LangChain4j pruža implementacije memorije koje to automatski upravljaju. Odaber ## Kako se koristi LangChain4j -Ovaj modul proširuje brzi početak integrirajući Spring Boot i dodajući memoriju razgovora. Evo kako se dijelovi slažu: +Ovaj modul integrira Spring Boot i dodaje memoriju za razgovor. Evo kako se elementi slagaju: **Ovisnosti** - Dodajte dvije LangChain4j biblioteke: @@ -93,8 +93,8 @@ Ovaj modul proširuje brzi početak integrirajući Spring Boot i dodajući memor langchain4j-open-ai-official ``` - -**Chat model** - Konfigurirajte Azure OpenAI kao Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): + +**Chat Model** - Konfigurirajte Azure OpenAI kao Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -108,10 +108,10 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { .build(); } ``` + +Builder čita vjerodajnice iz varijabli okoline postavljenih `azd up`. Postavljanje `baseUrl` na vašu Azure krajnju točku omogućuje OpenAI klijentu rad s Azure OpenAI. -Builder čita vjerodajnice iz varijabli okoline postavljenih naredbom `azd up`. Postavljanje `baseUrl` na vaš Azure endpoint čini da OpenAI klijent radi s Azure OpenAI. - -**Memorija razgovora** - Pratite povijest chata s MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Memorija razgovora** - Pratite povijest razgovora s MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -123,64 +123,67 @@ memory.add(UserMessage.from("What's my name?")); AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` - -Kreirajte memoriju s `withMaxMessages(10)` da zadržite zadnjih 10 poruka. Dodajte korisničke i AI poruke s tipiziranim omotačima: `UserMessage.from(text)` i `AiMessage.from(text)`. Dohvatite povijest s `memory.messages()` i pošaljite je modelu. Servis pohranjuje odvojene instance memorije po ID-u razgovora, omogućujući istovremeni chat više korisnika. + +Kreirajte memoriju s `withMaxMessages(10)` za čuvanje posljednjih 10 poruka. Dodajte korisničke i AI poruke pomoću tipiziranih omotača: `UserMessage.from(text)` i `AiMessage.from(text)`. Dohvatite povijest s `memory.messages()` i pošaljite je modelu. Servis pohranjuje zasebne instance memorije po ID-u razgovora, dopuštajući višestrukim korisnicima istovremeni chat. > **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) i pitajte: > - "Kako MessageWindowChatMemory odlučuje koje poruke odbaciti kada je prozor pun?" -> - "Mogu li implementirati prilagođeno spremište memorije koristeći bazu podataka umjesto memorije u RAM-u?" -> - "Kako bih dodao sažimanje za kompresiju stare povijesti razgovora?" +> - "Mogu li implementirati prilagođenu pohranu memorije koristeći bazu podataka umjesto memorije?" +> - "Kako bih dodao sažimanje da komprimiram staru povijest razgovora?" -Stateless chat endpoint u potpunosti preskače memoriju - samo `chatModel.chat(prompt)` kao u brzom početku. Stateful endpoint dodaje poruke u memoriju, dohvaća povijest i uključuje taj kontekst sa svakim zahtjevom. Ista konfiguracija modela, različiti šabloni. +Endpoint za stateless chat u potpunosti preskače memoriju - samo `chatModel.chat(prompt)` kao u brzom početku. Stateful endpoint dodaje poruke u memoriju, dohvaća povijest i uključuje taj kontekst sa svakim zahtjevom. Ista konfiguracija modela, različiti obrasci. ## Implementacija Azure OpenAI infrastrukture -**Bash:** +**Bash:** ```bash cd 01-introduction azd up # Odaberite pretplatu i lokaciju (preporučeno eastus2) ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 01-introduction azd up # Odaberite pretplatu i lokaciju (preporučeno eastus2) ``` + -> **Napomena:** Ako naiđete na timeout grešku (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), jednostavno pokrenite `azd up` ponovno. Azure resursi mogu još biti u procesu postavljanja u pozadini, a ponovni pokušaj omogućuje dovršetak implementacije kad resursi dođu u terminalno stanje. +> **Napomena:** Ako naiđete na grešku timeouta (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), jednostavno ponovno pokrenite `azd up`. Azure resursi se mogu još postavljati u pozadini, a ponovni pokušaj omogućuje dovršetak implementacije kada resursi dođu u terminalno stanje. Ovo će: -1. Implementirati Azure OpenAI resurs s GPT-5.2 i modelima text-embedding-3-small -2. Automatski generirati `.env` datoteku u korijenu projekta s vjerodajnicama -3. Postaviti sve potrebne varijable okoline +1. Implementirati Azure OpenAI resurs s GPT-5.2 i modelima text-embedding-3-small +2. Automatski generirati `.env` datoteku u korijenu projekta s vjerodajnicama +3. Postaviti sve potrebne varijable okoline -**Imate problema s implementacijom?** Pogledajte [Infrastructure README](infra/README.md) za detaljne upute o rješavanju problema uključujući sukobe naziva poddomena, ručne korake implementacije kroz Azure Portal i savjete za konfiguraciju modela. +**Imate problema s implementacijom?** Pogledajte [Infrastructure README](infra/README.md) za detaljno rješavanje problema uključujući sukobe naziva poddomena, korake za ručnu implementaciju putem Azure Portala i upute za konfiguraciju modela. -**Provjerite je li implementacija uspješna:** +**Provjerite je li implementacija uspjela:** -**Bash:** +**Bash:** ```bash -cat ../.env # Trebao bi pokazati AZURE_OPENAI_ENDPOINT, API_KEY, itd. +cat ../.env # Trebalo bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY itd. ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # Trebalo bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, itd. +Get-Content ..\.env # Trebao bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, itd. ``` -> **Napomena:** Naredba `azd up` automatski generira `.env` datoteku. Ako je kasnije trebate ažurirati, možete ili ručno uređivati `.env` ili je ponovno generirati pokretanjem: -> -> **Bash:** + +> **Napomena:** `azd up` automatski generira `.env` datoteku. Ako je potrebno kasnije ažurirati, možete ju ili ručno urediti ili ponovno generirati pokretanjem: +> +> **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` -> -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` + ## Pokretanje aplikacije lokalno @@ -188,135 +191,140 @@ Get-Content ..\.env # Trebalo bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, itd. Provjerite postoji li `.env` datoteka u korijenskom direktoriju s Azure vjerodajnicama. Pokrenite ovo iz direktorija modula (`01-introduction/`): -**Bash:** +**Bash:** ```bash cat ../.env # Trebalo bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Trebalo bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` + **Pokrenite aplikacije:** -**Opcija 1: Koristeći Spring Boot Dashboard (preporučeno za korisnike VS Code-a)** +**Opcija 1: Korištenje Spring Boot Dashboarda (preporučeno za korisnike VS Code-a)** -Dev container uključuje Spring Boot Dashboard ekstenziju, koja pruža vizualno sučelje za upravljanje svim Spring Boot aplikacijama. Možete ga pronaći na Activity Bar-u s lijeve strane VS Code-a (potražite ikonu Spring Boot). +Razvojni kontejner uključuje ekstenziju Spring Boot Dashboard, koja pruža vizualno sučelje za upravljanje svim Spring Boot aplikacijama. Možete ju pronaći u traci aktivnosti na lijevoj strani VS Code-a (potražite ikonu Spring Boota). -Iz Spring Boot Dashboard-a možete: -- Vidjeti sve dostupne Spring Boot aplikacije u radnom prostoru -- Pokrenuti/zaustaviti aplikacije jednim klikom -- Pregledavati zapisnike aplikacija u realnom vremenu -- Pratiti status aplikacija +Iz Spring Boot Dashboarda možete: +- Vidjeti sve dostupne Spring Boot aplikacije u prostoru za rad +- Pokretati/zaustavljati aplikacije jednim klikom +- Pratiti zapisnike aplikacije u stvarnom vremenu +- Nadzirati stanje aplikacije -Samo kliknite tipku za pokretanje pored "introduction" za pokretanje ovog modula, ili pokrenite sve module odjednom. +Jednostavno kliknite tipku za pokretanje pored "introduction" za pokretanje ovog modula ili pokrenite sve module odjednom. Spring Boot Dashboard -*Spring Boot Dashboard u VS Code-u — pokrenite, zaustavite i pratite sve module s jednog mjesta* +*Spring Boot Dashboard u VS Codeu — pokrenite, zaustavite i pratite sve module s jednog mjesta* -**Opcija 2: Koristeći shell skripte** +**Opcija 2: Korištenje shell skripti** Pokrenite sve web aplikacije (moduli 01-04): -**Bash:** +**Bash:** ```bash cd .. # Iz korijenskog direktorija ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd .. # Iz korijenskog direktorija .\start-all.ps1 ``` + Ili pokrenite samo ovaj modul: -**Bash:** +**Bash:** ```bash cd 01-introduction ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 01-introduction .\start.ps1 ``` + -Obje skripte automatski učitavaju varijable okoline iz `.env` datoteke u korijenu i gradit će JAR-ove ako ne postoje. +Oba skripta automatski učitavaju varijable okoline iz korijenske `.env` datoteke i kompajlirat će JAR-ove ako ne postoje. -> **Napomena:** Ako želite ručno izgraditi sve module prije pokretanja: -> -> **Bash:** +> **Napomena:** Ako želite ručno izgraditi sve module prije pokretanja: +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` + Otvorite http://localhost:8080 u vašem pregledniku. **Za zaustavljanje:** -**Bash:** +**Bash:** ```bash ./stop.sh # Samo ovaj modul # Ili cd .. && ./stop-all.sh # Svi moduli ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # Samo ovaj modul # Ili cd ..; .\stop-all.ps1 # Svi moduli ``` + ## Korištenje aplikacije -Aplikacija pruža web sučelje s dvije implementacije chat-a jedna do druge. +Aplikacija pruža web sučelje s dvije implementacije chata jedna do druge. Application Home Screen -*Nadzorna ploča prikazuje opcije za Simple Chat (stateless) i Conversational Chat (stateful)* +*Prikaz nadzorne ploče s opcijama Simple Chat (bezstanje) i Conversational Chat (sa stanjem)* -### Stateless chat (lijevi panel) +### Statički razgovor (lijevi panel) -Isprobajte ovo prvo. Recite "Moje ime je John" pa odmah zatim "Kako se zovem?" Model se neće sjetiti jer je svaka poruka neovisna. Ovo demonstrira osnovni problem s integracijom jezičnih modela — nema konteksta razgovora. +Probajte najprije ovo. Recite "Moje ime je John" i zatim odmah pitajte "Kako se zovem?" Model neće zapamtiti jer je svaka poruka samostalna. Ovo ilustrira osnovni problem integracije jezičnih modela - nema kontekst razgovora. Stateless Chat Demo -*AI se ne sjeća vašeg imena iz prethodne poruke* +*AI ne pamti vaše ime iz prethodne poruke* -### Stateful chat (desni panel) +### Dinamički razgovor (desni panel) -Sada isprobajte isti niz ovdje. Recite "Moje ime je John" pa zatim "Kako se zovem?" Ovaj put se pamti. Razlika je MessageWindowChatMemory — održava povijest razgovora i uključuje je sa svakim zahtjevom. Ovako funkcionira produkcijski konverzacijski AI. +Sada isprobajte isti redoslijed ovdje. Recite "Moje ime je John" pa zatim "Kako se zovem?" Ovog puta model pamti. Razlika je u MessageWindowChatMemory - on održava povijest razgovora i uključuje je sa svakim zahtjevom. Ovo je način na koji produkcijski konverzacijski AI radi. Stateful Chat Demo -*AI se sjeća vašeg imena s početka razgovora* +*AI pamti vaše ime iz ranijeg dijela razgovora* -Oba panela koriste isti GPT-5.2 model. Jedina razlika je memorija. To jasno pokazuje što memorija donosi vašoj aplikaciji i zašto je ključna za stvarne slučajeve korištenja. +Oba panela koriste isti GPT-5.2 model. Jedina razlika je memorija. To jasno pokazuje što memorija donosi vašoj aplikaciji i zašto je bitna za stvarne slučajeve upotrebe. ## Sljedeći koraci -**Sljedeći modul:** [02-prompt-engineering - Prompt Engineering s GPT-5.2](../02-prompt-engineering/README.md) +**Sljedeći modul:** [02-prompt-engineering - Inženjering upita s GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigacija:** [← Prethodni: Modul 00 - Brzi početak](../00-quick-start/README.md) | [Natrag na početak](../README.md) | [Sljedeći: Modul 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigacija:** [← Nazad na početak](../README.md) | [Sljedeće: Modul 02 - Inženjering upita →](../02-prompt-engineering/README.md) --- **Napomena**: -Ovaj je dokument preveden pomoću AI usluge za prevođenje [Co-op Translator](https://github.com/Azure/co-op-translator). Iako nastojimo postići točnost, imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na izvornom jeziku treba se smatrati autoritativnim izvorom. Za važne informacije preporučuje se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešna tumačenja koja proizlaze iz korištenja ovog prijevoda. +Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporuča se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešne interpretacije koje proizlaze iz korištenja ovog prijevoda. \ No newline at end of file diff --git a/translations/hr/02-prompt-engineering/README.md b/translations/hr/02-prompt-engineering/README.md index 01e94095d..17c7e611c 100644 --- a/translations/hr/02-prompt-engineering/README.md +++ b/translations/hr/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ -# Modul 02: Inženjering prompta s GPT-5.2 +# Modul 02: Izrada upita s GPT-5.2 ## Sadržaj -- [Video vodič](../../../02-prompt-engineering) -- [Što ćete naučiti](../../../02-prompt-engineering) -- [Preduvjeti](../../../02-prompt-engineering) -- [Razumijevanje inženjeringa prompta](../../../02-prompt-engineering) -- [Osnove inženjeringa prompta](../../../02-prompt-engineering) - - [Zero-Shot promptiranje](../../../02-prompt-engineering) - - [Few-Shot promptiranje](../../../02-prompt-engineering) - - [Lanac misli](../../../02-prompt-engineering) - - [Promptiranje temeljeno na ulozi](../../../02-prompt-engineering) - - [Predlošci prompta](../../../02-prompt-engineering) -- [Napredni obrasci](../../../02-prompt-engineering) -- [Pokretanje aplikacije](../../../02-prompt-engineering) -- [Snimke zaslona aplikacije](../../../02-prompt-engineering) -- [Istraživanje obrazaca](../../../02-prompt-engineering) - - [Niska nasuprot visokoj žustrini](../../../02-prompt-engineering) - - [Izvršavanje zadatka (prolog za alate)](../../../02-prompt-engineering) - - [Kod za samorefleksiju](../../../02-prompt-engineering) - - [Strukturirana analiza](../../../02-prompt-engineering) - - [Višekratni razgovor](../../../02-prompt-engineering) - - [Korak po korak rezoniranje](../../../02-prompt-engineering) - - [Ograničeni izlaz](../../../02-prompt-engineering) -- [Što zapravo učite](../../../02-prompt-engineering) -- [Sljedeći koraci](../../../02-prompt-engineering) +- [Video vodič](#video-vodič) +- [Što ćete naučiti](#što-ćete-naučiti) +- [Preduvjeti](#preduvjeti) +- [Razumijevanje izrade upita](#razumijevanje-izrade-upita) +- [Osnove izrade upita](#osnove-izrade-upita) + - [Zero-Shot upiti](#zero-shot-upiti) + - [Few-Shot upiti](#few-shot-upiti) + - [Lanac razmišljanja](#lanac-razmišljanja) + - [Upiti temeljeni na ulozi](#upiti-temeljeni-na-ulozi) + - [Predlošci upita](#predlošci-upita) +- [Napredni obrasci](#napredni-obrasci) +- [Pokretanje aplikacije](#pokreni-aplikaciju) +- [Screenshotovi aplikacije](#snimke-zaslona-aplikacije) +- [Istraživanje obrazaca](#istraživanje-uzoraka) + - [Niska vs visoka volja](#niska-vs-visoka-željnost-eagerness) + - [Izvršenje zadatka (Predgovori alata)](#izvršenje-zadatka-unaprijed-definirani-alati) + - [Kod s vlastitim razmišljanjem](#samoreflektirajući-kod) + - [Strukturirana analiza](#strukturirana-analiza) + - [Višekratni razgovor](#višekratni-razgovor) + - [Razmišljanje korak po korak](#razmišljanje-korak-po-korak) + - [Ograničeni ishod](#ograničeni-izlaz) +- [Što zaista učite](#što-zapravo-učite) +- [Sljedeći koraci](#sljedeći-koraci) ## Video vodič Pogledajte ovu live sesiju koja objašnjava kako započeti s ovim modulom: -Inženjering prompta s LangChain4j - live sesija +Prompt Engineering with LangChain4j - Live Session ## Što ćete naučiti -Sljedeći dijagram pruža pregled ključnih tema i vještina koje ćete razviti u ovom modulu — od tehnika rafiniranja prompta do korak-po-korak tijeka rada koji ćete pratiti. +Sljedeći dijagram prikazuje pregled ključnih tema i vještina koje ćete razviti u ovom modulu — od tehnika usavršavanja upita do korak-po-korak tijeka rada koji ćete slijediti. -Što ćete naučiti +What You'll Learn -U prethodnim modulima istražili ste osnovne interakcije LangChain4j s GitHub modelima i vidjeli kako memorija omogućuje konverzacijski AI s Azure OpenAI. Sada ćemo se usredotočiti na način na koji postavljate pitanja — same promptove — koristeći Azure OpenAI GPT-5.2. Način na koji strukturirate svoje promptove drastično utječe na kvalitetu odgovora koje dobijete. Počinjemo pregledom osnovnih tehnika promptiranja, a zatim prelazimo na osam naprednih obrazaca koji u potpunosti koriste mogućnosti GPT-5.2. +U prethodnom modulu vidjeli ste kako memorija omogućuje konverzacijski AI s Azure OpenAI. Sada ćemo se usredotočiti na način na koji postavljate pitanja — same upite — koristeći Azure OpenAI GPT-5.2. Način na koji strukturirate svoje upite dramatično utječe na kvalitetu dobivenih odgovora. Počinjemo pregledom osnovnih tehnika izrade upita, a zatim prelazimo na osam naprednih obrazaca koji u potpunosti koriste mogućnosti GPT-5.2. -Koristit ćemo GPT-5.2 jer uvodi kontrolu rezoniranja - možete modelu reći koliko razmišljanja da obavi prije odgovora. Ovo čini različite strategije promptiranja jasnijima i pomaže vam razumjeti kada koristiti koji pristup. Također ćemo imati koristi od manjih ograničenja stope u Azure-u za GPT-5.2 u usporedbi s GitHub modelima. +Koristit ćemo GPT-5.2 jer uvodi kontrolu razmišljanja – možete reći modelu koliko razmišljanja treba prije odgovora. To čini različite strategije upita jasnijima i pomaže vam razumjeti kada koristiti koji pristup. ## Preduvjeti -- Završeni Modul 01 (Azure OpenAI resursi postavljeni) -- `.env` datoteka u korijenskom direktoriju s Azure vjerodajnicama (kreirana pomoću `azd up` u Modulu 01) +- Završeni Modul 01 (postavljeni Azure OpenAI resursi) +- `.env` datoteka u korijenskom direktoriju s Azure vjerodajnicama (kreirana naredbom `azd up` u Modulu 01) -> **Napomena:** Ako niste završili Modul 01, prvo slijedite upute za postavljanje tamo. +> **Napomena:** Ako niste završili Modul 01, prvo slijedite upute za postavljanje iz tog modula. -## Razumijevanje inženjeringa prompta +## Razumijevanje izrade upita -U svojoj srži, inženjering prompta je razlika između nejasnih uputa i preciznih, što donji primjer ilustrira. +Izrada upita u svojoj suštini razlikuje nejasne upute od preciznih, kao što donja usporedba ilustrira. -Što je inženjering prompta? +What is Prompt Engineering? -Inženjering prompta odnosi se na dizajniranje ulaznog teksta koji dosljedno daje rezultate koje trebate. Nije samo pitanje postavljanja pitanja - riječ je o strukturiranju zahtjeva tako da model točno razumije što želite i kako vam to dostaviti. +Izrada upita znači oblikovanje ulaznog teksta koji konzistentno donosi potrebne rezultate. Nije riječ samo o postavljanju pitanja — radi se o strukturiranju zahtjeva da model točno razumije što želite i kako to isporučiti. -Zamislite da dajete upute kolegi. "Popravi bug" je nejasno. "Popravi iznimku null pointer u UserService.java, red 45, dodajući provjeru na null" je specifično. Jezični modeli rade na isti način - specifičnost i struktura su bitni. +Možete to usporediti s davanjem uputa kolegi. "Popravi grešku" je nejasno. "Popravi iznimku null pointer u UserService.java na liniji 45 dodavanjem provjere null vrijednosti" je specifično. Jezični modeli funkcioniraju isto — specifičnost i struktura su bitni. -Dijagram ispod prikazuje kako se LangChain4j uklapa u ovu sliku — povezujući vaše obrasce prompta s modelom kroz gradivne blokove SystemMessage i UserMessage. +Dijagram ispod prikazuje kako se LangChain4j uklapa u ovu sliku — povezujući vaše obrasce upita s modelom putem građevnih blokova SystemMessage i UserMessage. -Kako se LangChain4j uklapa +How LangChain4j Fits -LangChain4j pruža infrastrukturu — veze modela, memoriju i vrste poruka — dok su obrasci prompta samo pažljivo strukturirani tekst koji šaljete kroz tu infrastrukturu. Ključni gradivni blokovi su `SystemMessage` (koji postavlja ponašanje i ulogu AI-a) i `UserMessage` (koja nosi vaš stvarni zahtjev). +LangChain4j pruža infrastrukturu — veze s modelom, memoriju i vrste poruka — dok su obrasci upita samo pažljivo strukturirani tekst koji šaljete kroz tu infrastrukturu. Ključni građevni blokovi su `SystemMessage` (koji postavlja ponašanje i ulogu AI-a) i `UserMessage` (koji prenosi vaš stvarni zahtjev). -## Osnove inženjeringa prompta +## Osnove izrade upita -Pet osnovnih tehnika prikazanih ispod čine temelj učinkovite izrade prompta. Svaka pokriva različit aspekt načina komunikacije s jezičnim modelima. +Pet osnovnih tehnika prikazanih u nastavku čine temelj učinkovite izrade upita. Svaka se bavi različitim aspektom kako komunicirate s jezičnim modelima. -Pregled pet obrazaca inženjeringa prompta +Five Prompt Engineering Patterns Overview -Prije nego što u ovom modulu prijeđemo na napredne obrasce, pregledajmo pet temeljnih tehnika promptiranja. To su gradivni blokovi koje svaki inženjer prompta treba poznavati. Ako ste već radili kroz [modul brzog početka](../00-quick-start/README.md#2-prompt-patterns), već ste ih vidjeli u akciji — evo konceptualnog okvira iza njih. +Prije nego što zaronimo u napredne obrasce ovog modula, pregledajmo pet osnovnih tehnika izrade upita. To su gradivni blokovi koje svaki inženjer upita treba znati. -### Zero-Shot promptiranje +### Zero-Shot upiti Najjednostavniji pristup: dajte modelu izravnu uputu bez primjera. Model se u potpunosti oslanja na svoje treniranje da razumije i izvrši zadatak. Ovo dobro funkcionira za jednostavne zahtjeve gdje je očekivano ponašanje očito. -Zero-Shot promptiranje +Zero-Shot Prompting -*Izravna uputa bez primjera — model zaključuje zadatak samo iz upute* +*Izravna uputa bez primjera — model zaključuje zadatak samo na temelju upute* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -89,13 +89,13 @@ String response = model.chat(prompt); **Kada koristiti:** Jednostavne klasifikacije, izravna pitanja, prijevodi ili bilo koji zadatak koji model može obraditi bez dodatnih uputa. -### Few-Shot promptiranje +### Few-Shot upiti -Pružite primjere koji demonstriraju obrazac koji želite da model slijedi. Model uči očekivani format ulaz-izlaz iz vaših primjera i primjenjuje ga na nove ulaze. Ovo dramatično poboljšava konzistentnost za zadatke gdje željeni format ili ponašanje nije očito. +Dajte primjere koji demonstriraju obrazac kojeg želite da model slijedi. Model uči očekivani format ulaza i izlaza iz vaših primjera i primjenjuje ga na nove unose. Ovo dramatično poboljšava dosljednost za zadatke gdje željeni format ili ponašanje nije očito. -Few-Shot promptiranje +Few-Shot Prompting -*Učenje iz primjera — model identificira obrazac i primjenjuje ga na nove ulaze* +*Učenje iz primjera — model prepoznaje obrazac i primjenjuje ga na nove unose* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kada koristiti:** Prilagođene klasifikacije, dosljedno formatiranje, zadaci specifični za domenu ili kada su rezultati zero-shot promptiranja nekonzistentni. +**Kada koristiti:** Prilagođene klasifikacije, dosljedno formatiranje, zadatke specifične za domen, ili kada su rezultati zero-shot upita nedosljedni. -### Lanac misli +### Lanac razmišljanja -Zatražite od modela da pokaže svoje rezoniranje korak-po-korak. Umjesto da preskoči direktno na odgovor, model razlaže problem i razrađuje svaki dio eksplicitno. Ovo poboljšava točnost kod matematičkih, logičkih i višestepenih razmišljanja. +Zatražite od modela da pokaže svoje razmišljanje korak po korak. Umjesto da skoči izravno na odgovor, model razlaže problem i prolazi kroz svaki dio u detalje. Ovo poboljšava točnost kod zadataka matematike, logike i višestupanjskog rezoniranja. -Promptiranje lanca misli +Chain of Thought Prompting -*Rezoniranje korak po korak — razbijanje složenih problema u eksplicitne logičke korake* +*Razmišljanje korak po korak — razbijanje složenih problema u jasne logičke korake* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Model prikazuje: 15 - 8 = 7, zatim 7 + 12 = 19 jabuka +// Model pokazuje: 15 - 8 = 7, zatim 7 + 12 = 19 jabuka ``` -**Kada koristiti:** Matematički problemi, logičke zagonetke, debugiranje ili bilo koji zadatak gdje pokazivanje procesa rezoniranja povećava točnost i povjerenje. +**Kada koristiti:** Matematiku, logičke zagonetke, otklanjanje pogrešaka ili bilo koji zadatak gdje prikaz procesa razmišljanja poboljšava točnost i povjerenje. -### Promptiranje temeljeno na ulozi +### Upiti temeljeni na ulozi -Postavite personu ili ulogu AI-u prije nego što postavite pitanje. Ovo pruža kontekst koji oblikuje ton, dubinu i fokus odgovora. "Softverski arhitekt" daje drukčiji savjet od "mlađeg developera" ili "auditor sigurnosti". +Postavite AI-u personu ili ulogu prije nego postavite pitanje. To osigurava kontekst koji oblikuje ton, dubinu i fokus odgovora. "Softverski arhitekt" daje drugačije savjete od "mlađeg programera" ili "sigurnosnog revizora". -Promptiranje temeljeno na ulozi +Role-Based Prompting -*Postavljanje konteksta i persone — isto pitanje daje različite odgovore ovisno o dodijeljenoj ulozi* +*Postavljanje konteksta i persone — isto pitanje dobiva različite odgovore ovisno o dodijeljenoj ulozi* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kada koristiti:** Pregledi koda, podučavanje, analiza specifična za domenu ili kada trebate odgovore prilagođene određenoj razini stručnosti ili perspektivi. +**Kada koristiti:** Pregled koda, podučavanje, domen-specifične analize ili kada trebate odgovore prilagođene određenoj razini stručnosti ili perspektivi. -### Predlošci prompta +### Predlošci upita -Napravite višekratno upotrebljive promtove s varijabilnim mjestima za unos. Umjesto da svaki put pišete novi prompt, definirajte predložak jednom i ispunjavajte različite vrijednosti. LangChain4j klasa `PromptTemplate` to olakšava s `{{variable}}` sintaksom. +Kreirajte ponovno upotrebljive upite s varijabilnim mjestima za unos. Umjesto da svaki put pišete novi upit, definirajte predložak jednom i unutar njega ispunite različite vrijednosti. LangChain4j klasa `PromptTemplate` to olakšava s `{{variable}}` sintaksom. -Predlošci prompta +Prompt Templates -*Višekratno upotrebljivi promptovi s varijabilnim mjestima — jedan predložak, mnoge namjene* +*Ponovno upotrebljivi upiti s varijabilnim mjestima — jedan predložak, mnogo upotreba* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Kada koristiti:** Ponavljani upiti s različitim ulazima, paketna obrada, izgradnja višekratno upotrebljivih AI tijekova rada ili bilo koji scenarij gdje struktura prompta ostaje ista, ali se podaci mijenjaju. +**Kada koristiti:** Ponavljani upiti s različitim unosima, obrada u grupi, izgradnja ponovno upotrebljivih AI tijekova rada ili bilo koji scenarij gdje struktura upita ostaje ista, ali se podaci mijenjaju. --- -Ovih pet temelja daje vam solidan alat za većinu zadataka promptiranja. Ostatak ovog modula gradi na njima s **osam naprednih obrazaca** koji iskorištavaju GPT-5.2-ove sposobnosti kontrole rezoniranja, samoocjenjivanja i strukturiranog izlaza. +Ovih pet osnovnih tehnika pružaju vam solidan alat za većinu zadataka izrade upita. Ostatak ovog modula nadograđuje na njih sa **osam naprednih obrazaca** koji koriste kontrolu razmišljanja GPT-5.2, samoprocjenu i mogućnosti strukturiranog izlaza. ## Napredni obrasci -S osnovama pokrivenima, prijeđimo na osam naprednih obrazaca koji ovaj modul čine jedinstvenim. Nisu svi problemi jednaki. Neka pitanja zahtijevaju brze odgovore, druga duboko razmišljanje. Neka zahtijevaju vidljivo rezoniranje, a druga samo rezultate. Svaki obrazac niže je optimiziran za drugačiji scenarij — i GPT-5.2 kontrola rezoniranja čini razlike još izraženijima. +Nakon što smo pokrili osnove, prelazimo na osam naprednih obrazaca koji ovaj modul čine jedinstvenim. Nisu svi problemi isti. Neka pitanja zahtijevaju brze odgovore, druga duboko razmišljanje. Neki zahtijevaju vidljivo razmišljanje, drugi samo rezultate. Svaki od niže navedenih obrazaca optimiziran je za drugačiji scenarij — a kontrola razmišljanja GPT-5.2 te razlike čini još izraženijima. -Osam obrazaca promptiranja +Eight Prompting Patterns -*Pregled osam obrazaca inženjeringa prompta i njihovih primjena* +*Pregled osam obrazaca izrade upita i njihovih slučajeva upotrebe* -GPT-5.2 dodaje još jednu dimenziju ovim obrascima: *kontrolu rezoniranja*. Klizač ispod pokazuje kako možete prilagoditi količinu razmišljanja modela — od brzih, izravnih do dubokih, temeljitih analiza. +GPT-5.2 dodaje novu dimenziju ovim obrascima: *kontrolu razmišljanja*. Kliznik ispod pokazuje kako možete prilagoditi trud razmišljanja modela — od brzih, izravnih odgovora do duboke, temeljite analize. -Kontrola rezoniranja s GPT-5.2 +Reasoning Control with GPT-5.2 -*GPT-5.2 kontrola rezoniranja vam omogućuje da odredite koliko razmišljanja model treba napraviti — od brzih izravnih odgovora do dubokih istraživanja* +*Kontrola razmišljanja GPT-5.2 omogućuje preciziranje koliko razmišljanja model treba izvesti — od brzih izravnih odgovora do dubokog istraživanja* -**Niska žustrina (brzo i fokusirano)** - Za jednostavna pitanja gdje želite brze, izravne odgovore. Model minimalno rezonira - maksimalno 2 koraka. Koristite za izračune, pretrage ili jednostavna pitanja. +**Niska volja (Brzo i fokusirano)** - Za jednostavna pitanja gdje želite brze, izravne odgovore. Model radi minimalno razmišljanja – najviše 2 koraka. Koristite ovo za izračune, pretraživanja ili jednostavna pitanja. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Istražite s GitHub Copilotom:** Otvorite [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) i pitajte: -> - "Koja je razlika između obrazaca promptiranja niske i visoke žustrine?" -> - "Kako XML oznake u promptovima pomažu strukturirati AI odgovor?" -> - "Kada bih trebao koristiti obrasce samorefleksije, a kada direktne upute?" +> 💡 **Istražite s GitHub Copilot:** Otvorite [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) i postavite pitanja: +> - "Koja je razlika između obrazaca niske i visoke volje u upitima?" +> - "Kako XML oznake u upitima pomažu u strukturiranju AI odgovora?" +> - "Kada koristiti obrasce sa samoprocjenom umjesto izravnih uputa?" -**Visoka žustrina (duboko i temeljito)** - Za složene probleme gdje želite podrobnu analizu. Model temeljito razmatra i prikazuje detaljno rezoniranje. Koristite za dizajn sustava, arhitektonske odluke ili kompleksna istraživanja. +**Visoka volja (Duboko i temeljito)** - Za složene probleme gdje želite detaljnu analizu. Model dubinski istražuje i pokazuje detaljno razmišljanje. Koristite za dizajn sustava, arhitektonske odluke ili složena istraživanja. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Izvršavanje zadatka (napredak korak-po-korak)** - Za tijekove rada s više koraka. Model daje početni plan, pripovijeda svaki korak dok ih izvršava, zatim daje sažetak. Koristite za migracije, implementacije ili bilo koji višekoračni proces. +**Izvršenje zadatka (Napredak korak po korak)** - Za višestepene tijekove rada. Model daje unaprijed plan, opisuje svaki korak dok radi i na kraju daje sažetak. Koristite za migracije, implementacije ili bilo koji višestepeni proces. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Lanac misli promptiranje eksplicitno traži od modela da prikaže proces rezoniranja, što poboljšava preciznost za složene zadatke. Razbijanje korak-po-korak pomaže ljudima i AI-u da razumiju logiku. +Lanac razmišljanja (Chain-of-Thought) eksplicitno traži model da pokaže proces razmišljanja, poboljšavajući točnost za složene zadatke. Razlaganje korak po korak pomaže i ljudima i AI-u razumjeti logiku. -> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) chatom:** Pitajte o ovom obrascu: -> - "Kako bih prilagodio obrazac izvršavanja zadatka za dugotrajne operacije?" -> - "Koje su najbolje prakse za strukturiranje prologa alata u produkcijskim aplikacijama?" -> - "Kako mogu snimiti i prikazati međukorake napretka u korisničkom sučelju?" +> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Pitajte o ovom obrascu: +> - "Kako bih prilagodio obrazac izvršenja zadatka za dugotrajne operacije?" +> - "Koje su najbolje prakse za strukturiranje predgovora alata u produkcijskim aplikacijama?" +> - "Kako mogu uhvatiti i prikazati međurezultate napretka u korisničkom sučelju?" Dijagram ispod ilustrira ovaj tijek rada Plan → Izvrši → Sažmi. -Obrazac izvršavanja zadatka +Task Execution Pattern *Tijek rada Plan → Izvrši → Sažmi za višestepene zadatke* -**Kod za samorefleksiju** - Za generiranje koda kvalitete pogodnog za produkciju. Model generira kod koji slijedi produkcijske standarde s odgovarajućim rukovanjem greškama. Koristite kada gradite nove značajke ili servise. +**Kod s vlastitim razmišljanjem** - Za generiranje koda koji zadovoljava produkcijske standarde. Model generira kod slijedeći produkcijske standarde s odgovarajućim upravljanjem greškama. Koristite kada razvijate nove značajke ili usluge. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Dijagram ispod prikazuje ovaj iterativni ciklus poboljšanja — generiraj, ocijeni, identificiraj slabosti, usavrši dok kod ne zadovolji produkcijske standarde. +Dijagram ispod prikazuje ovu iterativnu petlju poboljšanja — generiraj, procijeni, identificiraj slabosti i usavrši dok kod ne zadovolji standarde. -Ciklus samorefleksije +Self-Reflection Cycle -*Iterativni ciklus poboljšanja - generiraj, ocijeni, prepoznaj probleme, poboljšaj, ponovi* +*Iterativna petlja poboljšanja - generiraj, procijeni, identificiraj probleme, poboljšaj, ponavljaj* -**Strukturirana analiza** - Za dosljednu evaluaciju. Model pregledava kod koristeći fiksni okvir (ispravnost, prakse, izvedba, sigurnost, održivost). Koristite za preglede koda ili ocjenu kvalitete. +**Strukturirana analiza** - Za konzistentnu evaluaciju. Model pregledava kod koristeći fiksni okvir (ispravnost, prakse, performanse, sigurnost, održivost). Koristite za preglede koda ili procjene kvalitete. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) chatom:** Pitajte o strukturiranoj analizi: -> - "Kako mogu prilagoditi analitički okvir za različite vrste pregleda koda?" -> - "Koji je najbolji način za parsiranje i programsku obradu strukturiranog izlaza?" -> - "Kako osigurati dosljedne razine težine kroz različite revizijske sesije?" +> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Pitajte o strukturiranoj analizi: +> - "Kako mogu prilagoditi okvir analize za različite vrste pregleda koda?" +> - "Koji je najbolji način za parsiranje i programatsko postupanje sa strukturiranim izlazom?" +> - "Kako osigurati dosljedne nivoe ozbiljnosti kroz različite sesije pregleda?" -Dijagram u nastavku prikazuje kako ovaj strukturirani okvir organizira pregled koda u dosljedne kategorije s razinama težine. +Sljedeći dijagram prikazuje kako ovaj strukturirani okvir organizira pregled koda u dosljedne kategorije s nivoima ozbiljnosti. -Obrazac strukturirane analize +Structured Analysis Pattern -*Okvir za dosljedne preglede koda s razinama težine* +*Okvir za dosljedne preglede koda s nivoima ozbiljnosti* -**Višekratni razgovor** - Za razgovore kojima treba kontekst. Model pamti prethodne poruke i gradi na njima. Koristite za interaktivne pomoći ili složena pitanja i odgovore. +**Višekratni razgovor** - Za rasprave kojima treba kontekst. Model pamti prethodne poruke i gradi na njima. Koristite za interaktivne sesije pomoći ili složena pitanja i odgovore. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Dijagram ispod vizualizira kako se kontekst razgovora nakuplja s svakim okretom i kako se to odnosi na ograničenje tokena modela. +Dijagram ispod vizualizira kako se kontekst razgovora akumulira s svakim krugom i kako se odnosi prema ograničenju tokena modela. -Memorija konteksta +Context Memory -*Kako se kontekst razgovora nakuplja kroz više okreta dok ne dosegnu ograničenje tokena* -**Korak-po-korak razmišljanje** - Za probleme koji zahtijevaju vidljivu logiku. Model prikazuje eksplicitno razmišljanje za svaki korak. Koristite ovo za matematičke zadatke, logičke zagonetke ili kada trebate razumjeti proces razmišljanja. +*Kako se kontekst razgovora skuplja tijekom više krugova dok ne dostigne limit tokena* + +**Razmišljanje korak po korak** - Za probleme koji zahtijevaju vidljivu logiku. Model prikazuje eksplicitno razmišljanje za svaki korak. Koristite za matematičke probleme, logičke zagonetke ili kad trebate razumjeti proces razmišljanja. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Dijagram u nastavku ilustrira kako model razlaže probleme u eksplicitne, numerirane logičke korake. +Dijagram ispod ilustrira kako model razbija probleme u eksplicitne, numerirane logičke korake. Step-by-Step Pattern - *Razlaganje problema u eksplicitne logičke korake* -**Ograničeni izlaz** - Za odgovore sa specifičnim zahtjevima formata. Model strogo slijedi pravila formata i duljine. Koristite ovo za sažetke ili kada trebate preciznu strukturu izlaza. +**Ograničeni izlaz** - Za odgovore sa zahtjevima za specifični format. Model strogo prati pravila formata i duljine. Koristite ovo za sažetke ili kad vam treba precizna struktura izlaza. ```java String prompt = """ @@ -420,51 +420,51 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Sljedeći dijagram prikazuje kako ograničenja usmjeravaju model da proizvede izlaz koji strogo poštuje vaše zahtjeve za format i duljinu. +Sljedeća dijagrama pokazuje kako ograničenja usmjeravaju model da proizvede izlaz koji strogo poštuje vaše zahtjeve za formatom i duljinom. -Constrained Output Pattern +Oblik ograničenog izlaza -*Provjera specifičnih zahtjeva za format, duljinu i strukturu* +*Nametanje specifičnih zahtjeva za format, duljinu i strukturu* -## Pokrenite aplikaciju +## Pokreni aplikaciju -**Provjerite implementaciju:** +**Provjeri implementaciju:** -Provjerite da `.env` datoteka postoji u korijenskom direktoriju s Azure vjerodajnicama (kreirano tijekom Modula 01). Pokrenite ovo iz direktorija modula (`02-prompt-engineering/`): +Provjeri da datoteka `.env` postoji u korijenskom direktoriju s Azure vjerodajnicama (stvorena tijekom Modula 01). Pokreni ovo iz direktorija modula (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Trebao bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Trebalo bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Trebao bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Trebalo bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Pokrenite aplikaciju:** +**Pokreni aplikaciju:** -> **Napomena:** Ako ste već pokrenuli sve aplikacije koristeći `./start-all.sh` iz korijenskog direktorija (kako je opisano u Modulu 01), ovaj modul već radi na portu 8083. Možete preskočiti naredbe za start i direktno otvoriti http://localhost:8083. +> **Napomena:** Ako ste već pokrenuli sve aplikacije koristeći `./start-all.sh` iz korijenskog direktorija (kako je opisano u Modulu 01), ovaj modul već radi na portu 8083. Možete preskočiti naredbe za pokretanje ispod i otići direktno na http://localhost:8083. -**Opcija 1: Koristeći Spring Boot Dashboard (Preporučeno za korisnike VS Code-a)** +**Opcija 1: Korištenje Spring Boot nadzorne ploče (Preporučeno za VS Code korisnike)** -Dev container uključuje Spring Boot Dashboard ekstenziju, koja pruža vizualno sučelje za upravljanje svim Spring Boot aplikacijama. Možete je pronaći na Activity Baru na lijevoj strani VS Code-a (tražite ikonu Spring Boota). +Dev container uključuje ekstenziju Spring Boot Dashboard, koja pruža vizualno sučelje za upravljanje svim Spring Boot aplikacijama. Možete je pronaći na traci aktivnosti na lijevoj strani VS Codea (potražite ikonu Spring Boot). -Iz Spring Boot Dashboarda možete: -- Vidjeti sve dostupne Spring Boot aplikacije u workspaceu -- Pokrenuti/zaustaviti aplikacije jednim klikom -- Pratiti logove aplikacija u stvarnom vremenu -- Nadgledati status aplikacije +Iz Spring Boot nadzorne ploče možete: +- Vidjeti sve dostupne Spring Boot aplikacije u radnom prostoru +- Pokretati/zaustavljati aplikacije jednim klikom +- Pratiti dnevnike aplikacija u stvarnom vremenu +- Nadzirati status aplikacija -Jednostavno kliknite na gumb za pokretanje pokraj "prompt-engineering" da pokrenete ovaj modul, ili pokrenite sve module odjednom. +Jednostavno kliknite gumb za pokretanje pokraj "prompt-engineering" da biste pokrenuli ovaj modul ili pokrenite sve module odjednom. -Spring Boot Dashboard +Spring Boot Nadzorna ploča -*Spring Boot Dashboard u VS Code — pokrenite, zaustavite i pratite sve module s jednog mjesta* +*Spring Boot nadzorna ploča u VS Code — pokrenite, zaustavite i nadzirite sve module s jednog mjesta* -**Opcija 2: Koristeći shell skripte** +**Opcija 2: Korištenje shell skripti** -Pokrenite sve web aplikacije (moduli 01-04): +Pokreni sve web aplikacije (moduli 01-04): **Bash:** ```bash @@ -478,7 +478,7 @@ cd .. # Iz korijenskog direktorija .\start-all.ps1 ``` -Ili pokrenite samo ovaj modul: +Ili pokreni samo ovaj modul: **Bash:** ```bash @@ -492,7 +492,7 @@ cd 02-prompt-engineering .\start.ps1 ``` -Obje skripte automatski učitavaju varijable okoline iz `.env` datoteke u korijenu i izgradit će JAR-ove ako ne postoje. +Obje skripte automatski učitavaju varijable okoline iz korijenske `.env` datoteke i izgradit će JAR datoteke ako ne postoje. > **Napomena:** Ako želite ručno izgraditi sve module prije pokretanja: > @@ -508,7 +508,7 @@ Obje skripte automatski učitavaju varijable okoline iz `.env` datoteke u korije > mvn clean package -DskipTests > ``` -Otvorite http://localhost:8083 u vašem pregledniku. +Otvori http://localhost:8083 u svom pregledniku. **Zaustavljanje:** @@ -528,73 +528,73 @@ cd ..; .\stop-all.ps1 # Svi moduli ## Snimke zaslona aplikacije -Ovdje je glavno sučelje modula prompt engineering, gdje možete isprobavati svih osam uzoraka jedan pored drugoga. +Ovo je glavno sučelje modula za prompt engineering, gdje možete eksperimentirati sa svih osam uzoraka jedan pored drugog. -Dashboard Home +Početni zaslon nadzorne ploče -*Glavni dashboard koji prikazuje svih 8 uzoraka prompt engineeringa s njihovim karakteristikama i slučajevima upotrebe* +*Glavna nadzorna ploča prikazuje svih 8 uzoraka prompt engineeringa s njihovim karakteristikama i slučajevima upotrebe* ## Istraživanje uzoraka -Web sučelje vam omogućuje isprobavanje različitih strategija promptanja. Svaki uzorak rješava različite probleme - isprobajte ih da vidite kada koji pristup najbolje funkcionira. +Web sučelje omogućava eksperimentiranje s različitim strategijama promptanja. Svaki uzorak rješava različite probleme – isprobajte ih da vidite kad koji pristup najbolje funkcionira. -> **Napomena: Streaming vs. Non-Streaming** — Svaka stranica uzorka nudi dva gumba: **🔴 Stream Response (Live)** i **Ne-streaming** opciju. Streaming koristi Server-Sent Events (SSE) za prikaz tokena u stvarnom vremenu dok model generira odgovor, tako da odmah vidite napredak. Ne-streaming opcija čeka cijeli odgovor prije prikaza. Za promptove koji pokreću duboko razmišljanje (npr. High Eagerness, Self-Reflecting Code), ne-streaming poziv može trajati vrlo dugo – ponekad minute – bez vidljive povratne informacije. **Koristite streaming pri eksperimentiranju s kompleksnim promptovima** kako biste vidjeli rad modela i izbjegli dojam da je zahtjev istekao. +> **Napomena: Streaming vs Nesreaming** — Svaka stranica uzorka nudi dva gumba: **🔴 Stream Response (uživo)** i opciju **Nesreaming**. Streaming koristi Server-Sent Events (SSE) za prikaz tokena u stvarnom vremenu dok model generira, tako da odmah vidite tijek. Nesreaming opcija čeka cijeli odgovor prije prikaza. Za upite koji zahtijevaju duboko razmišljanje (npr. High Eagerness, Self-Reflecting Code), nesreaming poziv može trajati dugo — ponekad minute — bez vidljivog povratnog signala. **Koristite streaming pri eksperimentiranju s kompleksnim upitima** kako biste vidjeli kako model radi i izbjegli dojam da je zahtjev istekao. > -> **Napomena: Zahtjev za preglednikom** — Streaming funkcija koristi Fetch Streams API (`response.body.getReader()`) koji zahtijeva pravi preglednik (Chrome, Edge, Firefox, Safari). Ne radi u VS Code ugrađenom Simple Browseru, jer njegov webview ne podržava ReadableStream API. Ako koristite Simple Browser, gumbi za ne-streaming će raditi normalno — samo streaming gumbi su pogođeni. Otvorite `http://localhost:8083` u vanjskom pregledniku za potpunu funkcionalnost. +> **Napomena: Zahtjevi preglednika** — Streaming značajka koristi Fetch Streams API (`response.body.getReader()`) koji zahtijeva punu podršku preglednika (Chrome, Edge, Firefox, Safari). NE radi u VS Code ugrađenom Simple Browseru jer njegov webview ne podržava ReadableStream API. Ako koristite Simple Browser, nesreaming gumbi će raditi normalno — zahvaćeni su samo streaming gumbi. Otvorite `http://localhost:8083` u vanjskom pregledniku za punu funkcionalnost. -### Nisko vs. visoko intenzivno razmišljanje (Low vs High Eagerness) +### Niska vs visoka željnost (Eagerness) -Postavite jednostavno pitanje poput "Koliko je 15% od 200?" koristeći Low Eagerness. Dobit ćete trenutni, izravan odgovor. Sada postavite nešto složenije poput "Dizajniraj strategiju cachinga za API s velikim prometom" koristeći High Eagerness. Kliknite **🔴 Stream Response (Live)** i promatrajte detaljno razmišljanje modela, token po token. Isti model, ista struktura pitanja – ali prompt mu govori koliko duboko da razmišlja. +Postavite jednostavno pitanje poput "Koliko je 15% od 200?" koristeći Nisku željnost. Dobit ćete trenutni, direktan odgovor. Sada postavite nešto složenije poput "Dizajniraj strategiju keširanja za API s velikim prometom" koristeći Visoku željnost. Kliknite **🔴 Stream Response (uživo)** i gledajte kako se pojavljiva detaljna analiza modela token po token. Isti model, ista struktura pitanja – ali prompt određuje koliko razmišljanja treba biti. -### Izvršavanje zadataka (Tool Preambles) +### Izvršenje zadatka (Unaprijed definirani alati) -Višekoraci tijekovi rada imaju koristi od unaprijed planiranja i praćenja napretka. Model izlaže što će napraviti, opisuje svaki korak, zatim sažima rezultate. +Višestepeni tijek rada ima koristi od prethodnog planiranja i praćenja napretka. Model navodi što će raditi, objašnjava svaki korak, zatim sažima rezultate. ### Samoreflektirajući kod -Isprobajte "Napravite servis za validaciju email adresa". Umjesto da samo generira kod i stane, model generira, evaluira prema kriterijima kvalitete, identificira slabosti i poboljšava. Vidjet ćete iteracije dok kod ne ispuni proizvodne standarde. +Isprobajte "Napravite servis za validaciju e-pošte". Umjesto da samo generira kod i stane, model generira, evaluira prema kriterijima kvalitete, identificira slabosti i poboljšava. Vidjet ćete kako ponavlja dok kod ne zadovolji proizvodne standarde. ### Strukturirana analiza -Pregledi koda zahtijevaju konzistentne okvire evaluacije. Model analizira kod koristeći fiksne kategorije (ispravnost, prakse, performanse, sigurnost) s razinama težine. +Pregledi koda zahtijevaju dosljedne okvire evaluacije. Model analizira kod koristeći fiksne kategorije (ispravnost, praksa, izvedba, sigurnost) s razinama ozbiljnosti. -### Višekratna konverzacija (Multi-Turn Chat) +### Višekratni razgovor -Postavite pitanje "Što je Spring Boot?" zatim odmah nastavite s "Pokaži mi primjer". Model pamti prvo pitanje i daje vam specifičan Spring Boot primjer. Bez memorije, drugo pitanje bilo bi previše neodređeno. +Pitajte "Što je Spring Boot?" zatim odmah postavite "Pokaži mi primjer". Model pamti prvo pitanje i daje primjer specifičan za Spring Boot. Bez memorije, drugo pitanje bi bilo previše neodređeno. -### Korak-po-korak razmišljanje +### Razmišljanje korak-po-korak -Odaberite matematički problem i isprobajte oba načina: Step-by-Step Reasoning i Low Eagerness. Low eagerness odmah daje odgovor – brzo, ali nejasno. Korak-po-korak prikazuje svaki izračun i odluku. +Odaberite matematički problem i isprobajte ga s Razmišljanjem korak-po-korak i Niskom željnošću. Niska željnost samo daje odgovor – brzo ali nejasno. Razmišljanje korak-po-korak pokazuje svaki izračun i odluku. ### Ograničeni izlaz -Kad trebate specifične formate ili broj riječi, ovaj uzorak strogo provodi te zahtjeve. Isprobajte generiranje sažetka s točno 100 riječi u obliku nabrajanja. +Kad vam treba specifičan format ili točan broj riječi, ovaj uzorak nameće strogo pridržavanje. Pokušajte generirati sažetak s točno 100 riječi u obliku popisa. -## Što stvarno učite +## Što zapravo učite -**Uloženi napor u razmišljanje mijenja sve** +**Napori u razmišljanju mijenjaju sve** -GPT-5.2 vam dopušta kontrolu računalnog napora kroz vaše promptove. Niska razina znači brze odgovore s minimalnim istraživanjem. Visoka razina znači da model uzima vremena za duboko razmišljanje. Učite kako prilagoditi trud složenosti zadatka – ne trošite vrijeme na jednostavna pitanja, ali nemojte ni žuriti s kompleksnim odlukama. +GPT-5.2 vam omogućuje kontrolu računalnog napora kroz vaše upite. Nizak napor znači brze odgovore s minimalnim istraživanjem. Visok napor znači da model uzima vrijeme za duboko razmišljanje. Učite uskladiti napor s kompleksnošću zadatka – ne trošite vrijeme na jednostavna pitanja, ali nemojte ni požurivati složene odluke. -**Struktura vodi ponašanje** +**Struktura usmjerava ponašanje** -Primjećujete XML oznake u promptovima? One nisu ukrasne. Modeli pouzdanije prate strukturirane upute nego slobodni tekst. Kad trebate višekorake procese ili složenu logiku, struktura pomaže modelu pratiti gdje je i što slijedi. Dijagram ispod razlaže dobro strukturiran prompt pokazujući kako oznake poput ``, ``, ``, ``, i `` organiziraju vaše upute u jasne sekcije. +Primijetite XML oznake u promptima? Nisu samo ukras. Modeli pouzdanije slijede strukturirane upute nego slobodan tekst. Kad trebate višestepene procese ili složenu logiku, struktura pomaže modelu pratiti gdje je i što slijedi. Dijagram u nastavku razlaže dobro strukturirani prompt, pokazujući kako oznake poput ``, ``, ``, `` i `` organiziraju vaše upute u jasne sekcije. -Prompt Structure +Struktura prompta -*Anatomija dobro strukturiranog prompta s jasnim sekcijama i XML-stil organizacijom* +*Anatomija dobro strukturiranog prompta s jasnim sekcijama i organizacijom u XML stilu* **Kvaliteta kroz samo-evaluaciju** -Uzorke samoreflektirajućeg rada obilježava eksplicitno definiranje kriterija kvalitete. Umjesto da se nada da će model "ispravno" odraditi, vi mu točno kažete što znači "ispravno": točna logika, obrada pogrešaka, performanse, sigurnost. Model tada može evaluirati vlastiti izlaz i poboljšati ga. To proces generiranja koda pretvara iz lutrije u kontrolirani proces. +Samoreflektirajući uzorci rade tako da eksplicitno definiraju kriterije kvalitete. Umjesto da se nadaju da će model "ispravno napraviti", kažete mu točno što "ispravno" znači: ispravna logika, rukovanje greškama, izvedba, sigurnost. Model tada može vrednovati vlastiti izlaz i poboljšati ga. Time se generiranje koda pretvara iz lutrije u proces. **Kontekst je ograničen** -Višekratne konverzacije funkcioniraju tako da uz svaki zahtjev uključuju povijest poruka. Ali postoji ograničenje - svaki model ima maksimalan broj tokena. Kako se konverzacije povećavaju, potrebno je koristiti strategije da se relevantan kontekst zadrži bez prekoračenja limita. Ovaj modul pokazuje kako memorija radi; kasnije ćete naučiti kada sažimati, zaboraviti i ponovno dohvatiti. +Višekratni razgovori rade tako da uključuju povijest poruka u svaki zahtjev. No postoji granica – svaki model ima maksimalni broj tokena. Kako razgovori rastu, trebate strategije za održavanje relevantnog konteksta bez prekoračenja limita. Ovaj modul pokazuje kako radi memorija; kasnije ćete naučiti kad sažimati, kad zaboraviti i kad dohvatiti. ## Sljedeći koraci -**Sljedeći modul:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**Sljedeći modul:** [03-rag - RAG (generiranje potpomognuto dohvaćanjem)](../03-rag/README.md) --- @@ -603,6 +603,6 @@ Višekratne konverzacije funkcioniraju tako da uz svaki zahtjev uključuju povij --- -**Odricanje od odgovornosti**: -Ovaj je dokument preveden pomoću AI usluge za prevođenje [Co-op Translator](https://github.com/Azure/co-op-translator). Iako nastojimo postići točnost, imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za kritične informacije preporučuje se profesionalni ljudski prijevod. Ne odgovaramo za bilo kakve nesporazume ili pogrešna tumačenja koja proizlaze iz korištenja ovog prijevoda. +**Napomena**: +Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporuča se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešne interpretacije koje proizlaze iz korištenja ovog prijevoda. \ No newline at end of file diff --git a/translations/hr/03-rag/README.md b/translations/hr/03-rag/README.md index 1078e422b..ffb694c66 100644 --- a/translations/hr/03-rag/README.md +++ b/translations/hr/03-rag/README.md @@ -1,144 +1,143 @@ -# Modul 03: RAG (Generiranje potpomognuto pretraživanjem) +# Modul 03: RAG (Generacija potpomognuta dohvaćanjem) ## Sadržaj -- [Video vodič](../../../03-rag) -- [Što ćete naučiti](../../../03-rag) -- [Preduvjeti](../../../03-rag) -- [Razumijevanje RAG-a](../../../03-rag) - - [Koji RAG pristup koristi ovaj vodič?](../../../03-rag) -- [Kako to radi](../../../03-rag) - - [Obrada dokumenata](../../../03-rag) - - [Stvaranje embeddinga](../../../03-rag) - - [Semantičko pretraživanje](../../../03-rag) - - [Generiranje odgovora](../../../03-rag) -- [Pokrenite aplikaciju](../../../03-rag) -- [Korištenje aplikacije](../../../03-rag) - - [Učitajte dokument](../../../03-rag) - - [Postavite pitanja](../../../03-rag) - - [Provjerite izvore referenci](../../../03-rag) - - [Eksperimentirajte s pitanjima](../../../03-rag) -- [Ključni pojmovi](../../../03-rag) - - [Strategija dijeljenja na dijelove](../../../03-rag) - - [Ocjene sličnosti](../../../03-rag) - - [Pohrana u memoriji](../../../03-rag) - - [Upravljanje kontekstnim prozorom](../../../03-rag) -- [Kada je RAG važan](../../../03-rag) -- [Sljedeći koraci](../../../03-rag) +- [Video vodič](#video-vodič) +- [Što ćete naučiti](#što-ćete-naučiti) +- [Preduvjeti](#preduvjeti) +- [Razumijevanje RAG-a](#razumijevanje-rag-a) + - [Koji RAG pristup koristi ovaj vodič?](#koji-rag-pristup-koristi-ovaj-vodič) +- [Kako to radi](#kako-to-radi) + - [Obrada dokumenata](#obrada-dokumenata) + - [Stvaranje ugradnji (embeddinga)](#stvaranje-ugradnji-embeddinga) + - [Semantičko pretraživanje](#semantičko-pretraživanje) + - [Generiranje odgovora](#generiranje-odgovora) +- [Pokretanje aplikacije](#pokretanje-aplikacije) +- [Korištenje aplikacije](#korištenje-aplikacije) + - [Učitajte dokument](#prenesite-dokument) + - [Postavljajte pitanja](#postavljajte-pitanja) + - [Provjerite izvore](#provjerite-izvore) + - [Eksperimentirajte s pitanjima](#eksperimentirajte-s-pitanjima) +- [Ključni pojmovi](#ključni-pojmovi) + - [Strategija dijeljenja na dijelove](#strategija-dijeljenja-chunkanja) + - [Ocjene sličnosti](#rezultati-sličnosti) + - [Spremište u memoriji](#pohrana-u-memoriji) + - [Upravljanje kontekstom](#upravljanje-kontekstnim-prozorom) +- [Kada je RAG važan](#kada-je-rag-važan) +- [Sljedeći koraci](#sljedeći-koraci) ## Video vodič Pogledajte ovu uživo sesiju koja objašnjava kako započeti s ovim modulom: -RAG s LangChain4j - uživo sesija +RAG s LangChain4j - U živo ## Što ćete naučiti -U prethodnim modulima naučili ste kako voditi razgovore s AI-jem i kako učinkovitije strukturirati svoje upite. Ali postoji temeljno ograničenje: jezični modeli znaju samo ono što su naučili tijekom treninga. Oni ne mogu odgovoriti na pitanja o pravilnicima vaše tvrtke, vašoj projektnoj dokumentaciji ili bilo kojim informacijama na kojima nisu bili trenirani. +U prethodnim modulima naučili ste kako voditi razgovore s AI-jem i kako učinkovito strukturirati upite (prompte). No postoji temeljno ograničenje: jezični modeli znaju samo ono što su naučili tijekom treniranja. Ne mogu odgovoriti na pitanja o pravilnicima vaše tvrtke, dokumentaciji vašeg projekta ili bilo kojim informacijama na kojima nisu bili trenirani. -RAG (Generiranje potpomognuto pretraživanjem) rješava ovaj problem. Umjesto da pokušavate modelu "podučiti" vaše informacije (što je skupo i nepraktično), dajete mu mogućnost da pretražuje vaše dokumente. Kad netko postavi pitanje, sustav pronalazi relevantne informacije i uključuje ih u upit. Model tada odgovara na temelju tog dohvaćenog konteksta. +RAG (Generacija potpomognuta dohvaćanjem) rješava ovaj problem. Umjesto da pokušavate podučiti model vašim informacijama (što je skupo i nepraktično), dajete mu mogućnost da pretražuje vaše dokumente. Kad netko postavi pitanje, sustav pronalazi relevantne informacije i uključuje ih u prompt. Model zatim daje odgovor temeljen na tom dohvaćenom kontekstu. Zamislite RAG kao davanje modelu referentne knjižnice. Kad postavite pitanje, sustav: -1. **Korisnički upit** - Vi postavite pitanje -2. **Embedding** - Pretvara vaše pitanje u vektor -3. **Pretraživanje vektora** - Pronalazi slične dijelove dokumenta -4. **Sastavljanje konteksta** - Dodaje relevantne dijelove u upit -5. **Odgovor** - LLM generira odgovor temeljen na kontekstu +1. **Korisnički upit** - Postavite pitanje +2. **Ugradnja (embedding)** - Pretvara vaše pitanje u vektor +3. **Vektorska pretraga** - Pronalazi slične dijelove dokumenata +4. **Sastavljanje konteksta** - Dodaje relevantne dijelove u prompt +5. **Odgovor** - LLM generira odgovor temeljen na kontekstu -Ovo utemeljuje odgovore modela u vašim stvarnim podacima, umjesto da se oslanja samo na znanje iz treninga ili smišlja odgovore. +Ovo utemeljuje odgovore modela na vašim stvarnim podacima, a ne na njegovom znanju iz treninga ili izmišljenim odgovorima. ## Preduvjeti -- Završeni [Modul 00 - Brzi početak](../00-quick-start/README.md) (za Easy RAG primjer spomenut kasnije u ovom modulu) -- Završeni [Modul 01 - Uvod](../01-introduction/README.md) (Azure OpenAI resursi su postavljeni, uključujući embedding model `text-embedding-3-small`) -- `.env` datoteka u glavnom direktoriju s Azure akreditivima (stvorena naredbom `azd up` u Modulu 01) +- Završeni [Modul 01 - Uvod](../01-introduction/README.md) (Azure OpenAI resursi postavljeni, uključujući model ugradnje `text-embedding-3-small`) +- `.env` datoteka u root direktoriju s Azure vjerodajnicama (kreirana komandom `azd up` u Modulu 01) -> **Napomena:** Ako niste završili Modul 01, prvo pratite tamo upute za postavljanje. Naredba `azd up` postavlja i GPT chat model i embedding model koji koristi ovaj modul. +> **Napomena:** Ako niste završili Modul 01, prvo slijedite upute za postavljanje tamo. Komanda `azd up` postavlja i GPT chat model i embedding model koji koristi ovaj modul. ## Razumijevanje RAG-a -Dijagram ispod ilustrira osnovni koncept: umjesto oslanjanja samo na podatke modela iz treninga, RAG mu daje referentnu knjižnicu vaših dokumenata koje konzultira prije generiranja svakog odgovora. +Slika ispod ilustrira osnovni koncept: umjesto da se oslanjamo samo na podatke dobivene tijekom treninga modela, RAG modelu daje referentnu knjižnicu vaših dokumenata za konzultaciju prije generiranja svakog odgovora. Što je RAG -*Ovaj dijagram prikazuje razliku između standardnog LLM-a (koji nagađa iz trening podataka) i LLM-a s RAG poboljšanjem (koji prvo konzultira vaše dokumente).* +*Ova dijagram prikazuje razliku između standardnog LLM-a (koji nagađa na temelju treninga) i LLM-a poboljšanog RAG-om (koji prvo konzultira vaše dokumente).* -Evo kako se dijelovi povezuju od početka do kraja. Korisničko pitanje prolazi kroz četiri faze — embedding, pretraživanje vektora, sastavljanje konteksta i generiranje odgovora — gdje se svaka nadovezuje na prethodnu: +Evo kako dijelovi međusobno povezuju end-to-end. Korisničko pitanje prolazi kroz četiri faze — ugradnju, vektorsku pretragu, sastavljanje konteksta i generiranje odgovora — pri čemu se svaka nadovezuje na prethodnu: RAG arhitektura -*Ovaj dijagram prikazuje cjelokupni RAG pipeline — korisnički upit prolazi kroz embedding, pretraživanje vektora, sastavljanje konteksta i generiranje odgovora.* +*Ovaj dijagram prikazuje end-to-end RAG pipeline — korisnički upit prolazi kroz ugradnju, vektorsku pretragu, sastavljanje konteksta i generiranju odgovora.* -Ostatak ovog modula detaljno prolazi kroz svaku fazu, s kodom koji možete pokrenuti i mijenjati. +Ostatak ovog modula detaljno obrađuje svaku fazu, s kodom koji možete pokrenuti i mijenjati. ### Koji RAG pristup koristi ovaj vodič? -LangChain4j nudi tri načina za implementaciju RAG-a, svaki s različitom razinom apstrakcije. Dijagram ispod ih uspoređuje jedan uz drugog: +LangChain4j nudi tri načina implementacije RAG-a, svaki sa različitim razinama apstrakcije. Dijagram ispod ih uspoređuje: Tri RAG pristupa u LangChain4j -*Ovaj dijagram uspoređuje tri LangChain4j RAG pristupa — Easy, Native i Advanced — pokazujući njihove ključne komponente i kada koristiti koji.* +*Ovaj dijagram uspoređuje tri LangChain4j RAG pristupa — Easy, Native i Advanced — prikazujući njihove ključne komponente i kada koristiti koji.* | Pristup | Što radi | Kompromis | |---|---|---| -| **Easy RAG** | Automatizira sve kroz `AiServices` i `ContentRetriever`. Vi označavate sučelje, dodajete retriever i LangChain4j upravlja embeddingom, pretraživanjem i sastavljanjem upita u pozadini. | Minimalni kod, ali ne vidite što se događa u svakoj fazi. | -| **Native RAG** | Vi sami pozivate embedding model, pretražujete pohranu, gradite upit i generirate odgovor — jedan jasan korak po korak. | Više koda, ali svaka faza je vidljiva i može se mijenjati. | -| **Advanced RAG** | Koristi `RetrievalAugmentor` framework s priključnim transformatorima upita, ruterima, re-rankerima i injektorima sadržaja za produkcijske pipelineove. | Maksimalna fleksibilnost, ali znatno veća složenost. | +| **Easy RAG** | Automatski povezuje sve kroz `AiServices` i `ContentRetriever`. Označite sučelje, dodate retriever, a LangChain4j iza scene rukuje ugradnjom, pretragom i sastavljanjem prompta. | Minimalno koda, ali ne vidite što se događa u svakom koraku. | +| **Native RAG** | Vi pozivate embedding model, pretražujete pohranu, gradite prompt i generirate odgovor — pojedinačno, jasno i korak po korak. | Više koda, ali svaki je korak vidljiv i možete ga mijenjati. | +| **Advanced RAG** | Koristi `RetrievalAugmentor` okvir s pluggable transformatorima upita, routerima, re-rankerima i izvorima sadržaja za produkcijske pipeline. | Maksimalna fleksibilnost, ali znatno složenije. | -**Ovaj vodič koristi Native pristup.** Svaki korak RAG pipelinea — embedded upita, pretraživanje vektorske pohrane, sastavljanje konteksta i generiranje odgovora — eksplicitno je napisan u [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). To je namjerno: kao edukativni materijal, važnije je da vidite i razumijete svaku fazu nego da kod bude čošćen. Kad savladate kako se dijelovi uklapaju, možete preći na Easy RAG za brze prototipe ili Advanced RAG za produkcijske sustave. +**Ovaj vodič koristi Native pristup.** Svaki korak RAG pipelinea — ugradnja upita, pretraga vektorske pohrane, sastavljanje konteksta i generiranje odgovora — eksplicitno je napisan u [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). To je namjerno: kao resurs za učenje, važnije je da vidite i razumijete svaki korak negoli da je kod maksimalno skraćen. Kad ste upoznati s funkcioniranjem, možete prijeći na Easy RAG za brze prototipove ili Advanced RAG za produkcijske sustave. -> **💡 Već ste vidjeli Easy RAG u akciji?** Modul [Brzi početak](../00-quick-start/README.md) uključuje primjer Pitanja i Odgovora s dokumentima ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) koji koristi Easy RAG pristup — LangChain4j automatski upravlja embeddingom, pretraživanjem i sastavljanjem upita. Ovaj modul je sljedeći korak koji otvara pipeline da biste mogli vidjeti i kontrolirati svaku fazu sami. +> **💡 Zanimate Easy RAG?** LangChain4j također nudi pristup *Easy RAG* gdje `AiServices` i `ContentRetriever` automatski rukuju ugradnjom, pretragom i sastavljanjem prompta. Ovaj modul ide eksplicitnijim putem — razbijajući pipeline tako da možete vidjeti i kontrolirati svaki korak sami. -Dijagram ispod prikazuje Easy RAG pipeline iz spomenutog Brzog početka. Primijetite kako `AiServices` i `EmbeddingStoreContentRetriever` skrivaju svu kompleksnost — učitate dokument, dodate retriever i dobijete odgovore. Native pristup u ovom modulu otkriva svaku od tih skrivenih faza: +Dijagram ispod prikazuje Easy RAG pipeline. Primijetite kako `AiServices` i `EmbeddingStoreContentRetriever` skrivaju svu složenost — učitate dokument, dodate retriever i dobijete odgovore. Native pristup u ovom modulu ruši te skrivene korake: Easy RAG pipeline - LangChain4j -*Ovaj dijagram prikazuje Easy RAG pipeline iz `SimpleReaderDemo.java`. Usporedite ga s Native pristupom korištenim u ovom modulu: Easy RAG skriva embedding, dohvaćanje i sastavljanje upita iza `AiServices` i `ContentRetriever` — vi učitate dokument, dodate retriever i dobivate odgovore. Native pristup u ovom modulu otkriva pipeline tako da sami pozivate svaku fazu (embedding, pretraživanje, sastavljanje konteksta, generiranje), što vam daje potpunu vidljivost i kontrolu.* +*Ovaj dijagram prikazuje Easy RAG pipeline. Usporedite ovo s Native pristupom u ovom modulu: Easy RAG skriva ugradnju, pretraživanje i sastavljanje prompta iza `AiServices` i `ContentRetriever` — učitate dokument, dodate retriever i dobijete odgovore. Native pristup u ovom modulu razlaže pipeline tako da sami pozivate svaki korak (ugradnja, pretraga, sastavljanje konteksta, generiranje), dajući vam potpunu vidljivost i kontrolu.* ## Kako to radi -RAG pipeline u ovom modulu razlaže se na četiri faze koje se izvršavaju redom svaki put kad korisnik postavi pitanje. Prvo se učitani dokument **parsira i dijeli na dijelove** koji su upravljive veličine. Ti se dijelovi zatim pretvaraju u **vektorske embeddinge** i pohranjuju tako da se mogu matematički uspoređivati. Kad stigne upit, sustav izvršava **semantičko pretraživanje** za pronalazak najrelevantnijih dijelova, a zatim ih daje kao kontekst LLM-u za **generiranje odgovora**. Sljedeći odjeljci vode vas kroz svaku fazu s konkretnim kodom i dijagramima. Pogledajmo prvi korak. +RAG pipeline u ovom modulu sastoji se od četiri faze koje se izvode redom svaki put kad korisnik postavi pitanje. Prvo se učitani dokument **parsira i dijeli na dijelove** pogodne za korištenje. Ti se dijelovi potom pretvaraju u **vektorske ugradnje** i pohranjuju kako bi se mogli matematički uspoređivati. Kad dođe upit, sustav izvodi **semantičku pretragu** za pronalaženje najrelevantnijih dijelova i na kraju ih prosljeđuje kao kontekst LLM-u za **generiranje odgovora**. Sljedeći odjeljci detaljno objašnjavaju svaki korak s kodom i dijagramima. Pogledajmo prvi korak. ### Obrada dokumenata [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Kad učitate dokument, sustav ga parsira (PDF ili plain text), dodaje metapodatke poput naziva datoteke, a zatim dijeli na dijelove — manje dijelove koji stanu u kontekstni prozor modela. Ti se dijelovi lagano preklapaju kako se ne bi izgubio kontekst na granicama. +Kad učitate dokument, sustav ga parsira (PDF ili obični tekst), dodaje metapodatke poput naziva datoteke, a zatim ga dijeli na dijelove — manje cjeline koje stanu u kontekstni prozor modela. Ti se dijelovi djelomično preklapaju kako se ne bi izgubio kontekst na granicama. ```java -// Parsirajte prenesenu datoteku i zamotajte je u LangChain4j Dokument +// Parsiraj učitanu datoteku i umotaj je u LangChain4j dokument Document document = Document.from(content, metadata); -// Podijelite na dijelove od 300 tokena s preklapanjem od 30 tokena +// Podijeli na dijelove od 300 tokena s preklapanjem od 30 tokena DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -Dijagram ispod prikazuje kako to vizualno funkcionira. Primijetite kako svaki dio dijeli neke tokene s susjedima — preklapanje od 30 tokena osigurava da se nijedan važan kontekst ne izgubi u prijelazima: -Dijeljenje dokumenta na dijelove +Slika ispod vizualno prikazuje kako to funkcionira. Primijetite da svaki dio dijeli neke tokene s susjednim dijelovima — preklapanje od 30 tokena osigurava da nijedan važan kontekst ne ostane izgubljen između dijelova: -*Ovaj dijagram prikazuje dokument podijeljen u dijelove od 300 tokena s preklapanjem od 30 tokena, čime se čuva kontekst na granicama dijelova.* +Dijeljenje dokumenata na dijelove -> **🤖 Isprobajte uz [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) i pitajte: -> - "Kako LangChain4j dijeli dokumente na dijelove i zašto je preklapanje važno?" -> - "Koja je optimalna veličina dijelova za različite vrste dokumenata i zašto?" -> - "Kako postupiti s dokumentima na više jezika ili sa specialnim formatiranjem?" +*Ovaj dijagram prikazuje dokument podijeljen u dijelove od 300 tokena s preklapanjem od 30 tokena, čuvajući kontekst na granicama dijelova.* -### Stvaranje embeddinga +> **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) i pitajte: +> - "Kako LangChain4j dijeli dokumente na dijelove i zašto je preklapanje važno?" +> - "Koja je optimalna veličina dijelova za različite vrste dokumenata i zašto?" +> - "Kako rukovati dokumentima na više jezika ili sa specijalnim formatiranjem?" + +### Stvaranje ugradnji (embeddinga) [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Svaki se dio pretvara u numeričku reprezentaciju zvanu embedding — u osnovi pretvarač značenja u brojeve. Embedding model nije "inteligentan" poput chat modela; ne može slijediti upute, rezonirati niti odgovarati na pitanja. Ono što može jest mapirati tekst u matematički prostor gdje slična značenja završavaju blizu jedno drugom — "auto" blizu "vozilo", "pravila povrata" blizu "vrati novac". Zamislite chat model kao osobu s kojom razgovarate, a embedding model kao iznimno dobar sustav arhiviranja. +Svaki dio se pretvara u numerički prikaz nazvan embedding — u osnovi pretvarač značenja u brojeve. Embedding model nije "inteligentan" kao chat model; ne može slijediti upute, rezonirati ili odgovarati na pitanja. Ono što može jest preslikavati tekst u matematički prostor gdje slična značenja završavaju blizu jedno drugome — "auto" blizu "vozilo", "pravila povrata" blizu "vrati mi novac". Možete zamisliti chat model kao osobu s kojom razgovarate; embedding model je izuzetno dobar sustav za arhiviranje. -Dijagram ispod vizualizira ovaj koncept — ulazi tekst, izlaze numerički vektori, a slična značenja proizvode vektore koji su blizu: +Dijagram ispod vizualizira ovaj koncept — ulazi tekst, izlaze numerički vektori, a slična značenja proizvode vektore blizu jedan drugome: Koncept embedding modela -*Ovaj dijagram prikazuje kako embedding model pretvara tekst u numeričke vektore, stavljajući slična značenja — kao "auto" i "vozilo" — blizu jedno drugom u vektorskom prostoru.* +*Ovaj dijagram pokazuje kako embedding model pretvara tekst u numeričke vektore, smještajući slična značenja — poput "automobil" i "vozilo" — blizu jedno drugome u vektorskom prostoru.* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -Dijagram klase ispod prikazuje dva odvojena tijeka u RAG pipelineu i LangChain4j klase koje ih implementiraju. **Tijek unosa** (izvršava se jednom prilikom učitavanja) dijeli dokument, stvara embedding dijelova i pohranjuje ih pomoću `.addAll()`. **Tijek upita** (izvršava se svaki put kad korisnik pita) embedira pitanje, pretražuje pohranu preko `.search()`, i prosljeđuje pronađeni kontekst chat modelu. Oba tijeka se spajaju na zajedničko sučelje `EmbeddingStore`: + +Dijagram klasa ispod prikazuje dva zasebna toka u RAG pipelineu i LangChain4j klase koje ih implementiraju. **Tok unosa** (izvodi se jednom pri učitavanju) dijeli dokument, ugrađuje dijelove i pohranjuje ih preko `.addAll()`. **Tok upita** (izvodi se svaki put kad korisnik pita) ugrađuje upit, pretražuje pohranu preko `.search()`, i prosljeđuje podudarajući kontekst chat modelu. Oboje se spajaju na zajedničko sučelje `EmbeddingStore`: LangChain4j RAG klase -*Ovaj dijagram prikazuje dva tijeka u RAG pipelineu — unos i upit — i kako se povezuju kroz zajedničko EmbeddingStore sučelje.* +*Ovaj dijagram prikazuje dva toka u RAG pipelineu — unos i upit — i kako se povezuju preko zajedničkog EmbeddingStore sučelja.* -Kad se embeddingi pohrane, sličan sadržaj prirodno se grupira u vektorskom prostoru. Vizualizacija ispod pokazuje kako dokumenti o srodnim temama završavaju kao bliski točke, što čini semantičko pretraživanje mogućim: +Kad se embeddingi pohrane, sličan sadržaj prirodno klasterira u prostoru vektora. Vizualizacija ispod prikazuje kako dokumenti o srodnim temama završavaju kao susjedne točke, što omogućuje semantičku pretragu: Prostor vektorskih embeddinga -*Ova vizualizacija prikazuje kako se povezani dokumenti grupiraju u 3D vektorskom prostoru, s temama poput Tehničke dokumentacije, Poslovnih pravila i Često postavljanih pitanja stvarajući odvojene skupine.* +*Ova vizualizacija prikazuje kako se povezani dokumenti grupiraju u 3D vektorskom prostoru, s temama poput Tehničke dokumentacije, Poslovnih pravila i Često postavljanih pitanja formirajući odvojene skupine.* -Kad korisnik pretražuje, sustav slijedi četiri koraka: embedira dokumente jednom, embedira upit za svako pretraživanje, uspoređuje vektor upita sa svim pohranjenim vektorima koristeći kosinusnu sličnost i vraća top-K dijelova s najvišim rezultatima. Dijagram ispod vodi kroz svaki korak i uključene LangChain4j klase: +Kad korisnik pretražuje, sustav slijedi četiri koraka: jednom ugrađuje dokumente, kod svake pretrage ugrađuje upit, uspoređuje vektor upita sa svim pohranjenim vektorima koristeći kosinusnu sličnost i vraća top-K najviših rezultata. Dijagram ispod prikazuje svaki korak i LangChain4j klase uključene u proces: -Koraci pretraživanja embeddinga +Koraci embedding pretrage -*Ovaj dijagram prikazuje proces pretraživanja embeddingom u četiri koraka: embediranje dokumenata, embediranje upita, usporedbu vektora kosinusnom sličnosti i vraćanje top-K rezultata.* +*Ovaj dijagram pokazuje četverostepeni proces pretrage embeddinga: ugradnju dokumenata, ugradnju upita, usporedbu vektora kosinusnom sličnosti i vraćanje top-K rezultata.* ### Semantičko pretraživanje [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Kad postavite pitanje, i pitanje se pretvara u embedding. Sustav uspoređuje embedding vašeg pitanja sa embeddingima dijelova dokumenata. Pronalazi dijelove s najsličnijim značenjima — ne samo podudaranje ključnih riječi, već stvarnu semantičku sličnost. +Kad postavite pitanje, to pitanje se također pretvara u embedding. Sustav uspoređuje embedding vašeg pitanja sa svim embeddingima dijelova dokumenata. Pronalazi dijelove s najviše sličnosti u značenju — ne samo podudaranje ključnih riječi, već stvarnu semantičku sličnost. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -Dijagram ispod uspoređuje semantičko pretraživanje s tradicionalnim pretraživanjem po ključnim riječima. Pretraživanje po ključnim riječima za "vozilo" ne pronalazi dio o "automobilima i kamionima", ali semantičko pretraživanje razumije da znače isto i vraća ga kao visoko relevantan rezultat: -Semantičko pretraživanje +Dijagram ispod uspoređuje semantičku pretragu s tradicionalnom pretragom po ključnim riječima. Pretraga po ključnoj riječi "vozilo" promašuje dio o "automobilima i kamionima", ali semantička pretraga razumije da znače isto i vraća ga kao visokorangiranu podudarnost: + +Semantička pretraga -*Ovaj dijagram uspoređuje pretraživanje po ključnim riječima s semantičkim pretraživanjem, pokazujući kako semantičko pretraživanje dohvaća konceptualno povezani sadržaj čak i kad se ključne riječi ne podudaraju.* -Ispod haube, sličnost se mjeri korištenjem kosinusne sličnosti — praktički pitajući "pokazuju li ove dvije strelice u istom smjeru?" Dva dijela mogu koristiti potpuno različite riječi, ali ako znače isto, njihovi vektori pokazuju u istom smjeru i rezultat je blizak 1.0: +*Ovaj dijagram uspoređuje pretraživanje na temelju ključnih riječi s semantičkom pretragom, pokazujući kako semantička pretraga dohvaća konceptualno povezani sadržaj čak i kad se ne podudaraju točne ključne riječi.* -Cosine Similarity +Ispod haube, sličnost se mjeri korištenjem kosinusne sličnosti — u osnovi se pita "pokazuju li ove dvije strelice u istom smjeru?" Dva dijela mogu koristiti potpuno drukčije riječi, ali ako znače isto, njihovi vektori pokazuju u isti smjer i daju rezultat blizu 1.0: -*Ovaj dijagram ilustrira kosinusnu sličnost kao kut između vektora ugradnje — bolje poravnati vektori postižu rezultat bliži 1.0, što ukazuje na veću semantičku sličnost.* +Kosinusna sličnost +*Ovaj dijagram ilustrira kosinusnu sličnost kao kut između vektora ugradnje — vektori koji su bliže usklađeni dobivaju rezultat bliži 1.0, što ukazuje na veću semantičku sličnost.* > **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) i pitajte: > - "Kako radi pretraživanje sličnosti s ugradnjama i što određuje rezultat?" -> - "Koju granicu sličnosti trebam koristiti i kako to utječe na rezultate?" -> - "Kako postupiti u slučajevima kada se ne pronađu relevantni dokumenti?" +> - "Koju prag sličnosti bih trebao koristiti i kako to utječe na rezultate?" +> - "Kako postupiti kada se ne pronađu relevantni dokumenti?" ### Generiranje odgovora [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Najrelevantniji dijelovi se slažu u strukturirani upit koji uključuje izričite upute, dohvaćeni kontekst i korisničko pitanje. Model čita ti specifični dijelovi i odgovara na temelju tih informacija — može koristiti samo ono što je pred njim, što sprječava halucinacije. +Najrelevantniji dijelovi se sastavljaju u strukturirani upit koji uključuje eksplicitne upute, dohvaćeni kontekst i korisničko pitanje. Model čita te specifične dijelove i daje odgovor na temelju tih informacija — može koristiti samo ono što mu je predano, što sprječava halucinacije. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Dijagram ispod prikazuje ovaj proces sklapanja — najupečatljiviji dijelovi iz koraka pretraživanja ubacuju se u predložak upita, a `OpenAiOfficialChatModel` generira utemeljen odgovor: +Dijagram u nastavku prikazuje taj proces sastavljanja — dijelovi s najboljim ocjenama iz koraka pretraživanja ugrađuju se u predložak upita, a `OpenAiOfficialChatModel` generira utemeljen odgovor: -Context Assembly +Sastavljanje konteksta -*Ovaj dijagram pokazuje kako se najužiji dijelovi slažu u strukturirani upit, što omogućava modelu da generira utemeljen odgovor iz vaših podataka.* +*Ovaj dijagram prikazuje kako se dijelovi s najboljim ocjenama sastavljaju u strukturirani upit, omogućujući modelu generiranje utemeljenog odgovora iz vaših podataka.* -## Pokrenite aplikaciju +## Pokretanje aplikacije **Provjerite implementaciju:** -Provjerite postoji li `.env` datoteka u korijenskom direktoriju s Azure vjerodajnicama (kreirana tijekom Modula 01). Pokrenite ovo iz direktorija modula (`03-rag/`): +Provjerite postoji li `.env` datoteka u glavnom direktoriju sa Azure vjerodajnicama (stvorena tijekom Modula 01). Pokrenite ovo iz direktorija modula (`03-rag/`): **Bash:** ```bash @@ -261,25 +260,25 @@ Get-Content ..\.env # Trebao bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPLO **Pokrenite aplikaciju:** -> **Napomena:** Ako ste već pokrenuli sve aplikacije korištenjem `./start-all.sh` iz korijenskog direktorija (kako je opisano u Modulu 01), ovaj modul već radi na portu 8081. Možete preskočiti naredbe za pokretanje ispod i direktno otići na http://localhost:8081. +> **Napomena:** Ako ste već pokrenuli sve aplikacije koristeći `./start-all.sh` iz glavnog direktorija (kako je opisano u Modulu 01), ovaj modul već radi na portu 8081. Možete preskočiti naredbe za pokretanje u nastavku i izravno otvoriti http://localhost:8081. -**Opcija 1: Korištenje Spring Boot nadzorne ploče (Preporučeno za korisnike VS Codea)** +**Opcija 1: Korištenje Spring Boot nadzorne ploče (preporučeno za korisnike VS Codea)** -Razvojno okruženje uključuje ekstenziju Spring Boot Dashboards koja pruža vizualno sučelje za upravljanje svim Spring Boot aplikacijama. Možete je pronaći na traci aktivnosti lijevo u VS Codeu (potražite ikonu Spring Boot). +Razvojno okruženje uključuje Spring Boot nadzornu ploču, koja pruža vizualno sučelje za upravljanje svim Spring Boot aplikacijama. Pronaći ćete je u Traci aktivnosti s lijeve strane VS Codea (potražite ikonu Spring Boota). Iz Spring Boot nadzorne ploče možete: - Vidjeti sve dostupne Spring Boot aplikacije u radnom prostoru -- Pokretati i zaustavljati aplikacije jednim klikom -- Pregledavati zapisnike aplikacije u stvarnom vremenu +- Jednim klikom pokretati/zaustavljati aplikacije +- Pratiti logove aplikacije u stvarnom vremenu - Nadzirati status aplikacije -Jednostavno kliknite gumb za pokretanje pored "rag" da pokrenete ovaj modul ili pokrenite sve module odjednom. +Jednostavno kliknite gumb za reprodukciju pored "rag" za pokretanje ovog modula ili pokrenite sve module odjednom. -Spring Boot Dashboard +Spring Boot Nadzorna ploča -*Ovaj snimak zaslona prikazuje Spring Boot nadzornu ploču u VS Codeu, gdje možete vizualno pokretati, zaustavljati i nadzirati aplikacije.* +*Ovaj zaslon prikazuje Spring Boot nadzornu ploču u VS Codeu, gdje možete vizualno pokretati, zaustavljati i nadzirati aplikacije.* -**Opcija 2: Korištenje shell skripti** +**Opcija 2: Korištenje skripti u terminalu** Pokrenite sve web aplikacije (moduli 01-04): @@ -309,7 +308,7 @@ cd 03-rag .\start.ps1 ``` -Obje skripte automatski učitavaju varijable okoline iz `.env` datoteke u korijenu i izgradit će JAR datoteke ako ne postoje. +Obje skripte automatski učitavaju varijable okoline iz glavne `.env` datoteke i izgradit će JAR datoteke ako ne postoje. > **Napomena:** Ako želite ručno izgraditi sve module prije pokretanja: > @@ -318,7 +317,7 @@ Obje skripte automatski učitavaju varijable okoline iz `.env` datoteke u korije > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -327,7 +326,7 @@ Obje skripte automatski učitavaju varijable okoline iz `.env` datoteke u korije Otvorite http://localhost:8081 u vašem pregledniku. -**Zaustavljanje:** +**Za zaustavljanje:** **Bash:** ```bash @@ -347,27 +346,27 @@ cd ..; .\stop-all.ps1 # Svi moduli Aplikacija pruža web sučelje za prijenos dokumenata i postavljanje pitanja. -RAG Application Interface +Sučelje RAG aplikacije -*Ovaj snimak zaslona prikazuje sučelje RAG aplikacije gdje prenosite dokumente i postavljate pitanja.* +*Ovaj zaslon prikazuje sučelje RAG aplikacije gdje prenosite dokumente i postavljate pitanja.* ### Prenesite dokument -Započnite prijenosom dokumenta - TXT datoteke najbolje funkcioniraju za testiranje. U ovom direktoriju nalazi se `sample-document.txt` koji sadrži informacije o značajkama LangChain4j, implementaciji RAG-a i najboljim praksama - savršeno za testiranje sustava. +Počnite prijenosom dokumenta – TXT datoteke najbolje funkcioniraju za testiranje. U ovom direktoriju nalazi se `sample-document.txt` koji sadrži informacije o značajkama LangChain4j, implementaciji RAG-a i najboljim praksama – savršen za testiranje sustava. -Sustav obrađuje vaš dokument, dijeli ga na dijelove i stvara ugradnje za svaki dio. To se događa automatski kada prenesete dokument. +Sustav obrađuje vaš dokument, dijeli ga u dijelove i stvara ugradnje za svaki dio. To se događa automatski pri prijenosu. ### Postavljajte pitanja -Sada postavite specifična pitanja o sadržaju dokumenta. Isprobajte nešto faktualno što je jasno istaknuto u dokumentu. Sustav traži relevantne dijelove, uključuje ih u upit i generira odgovor. +Sada postavite specifična pitanja o sadržaju dokumenta. Isprobajte nešto faktualno što je jasno navedeno u dokumentu. Sustav traži relevantne dijelove, uključuje ih u upit i generira odgovor. ### Provjerite izvore -Primijetite da svaki odgovor uključuje izvore s rezultatima sličnosti. Ti rezultati (od 0 do 1) pokazuju koliko je svaki dio bio relevantan za vaše pitanje. Viši rezultati znače bolje podudaranje. To vam omogućuje da provjerite točnost odgovora prema izvornom materijalu. +Primijetite da svaki odgovor uključuje reference izvora sa sličnostnim rezultatima. Ti rezultati (od 0 do 1) pokazuju koliko je svaki dio bio relevantan za vaše pitanje. Viši rezultati znače bolje podudaranje. To vam omogućuje da provjerite točnost odgovora u odnosu na izvorni materijal. -RAG Query Results +Rezultati RAG upita -*Ovaj snimak zaslona prikazuje rezultate upita s generiranim odgovorom, referencama izvora i ocjenama relevantnosti za svaki dohvaćeni dio.* +*Ovaj zaslon prikazuje rezultate upita s generiranim odgovorom, referencama izvora i rezultatima relevantnosti za svaki dohvaćeni dio.* ### Eksperimentirajte s pitanjima @@ -376,50 +375,50 @@ Isprobajte različite vrste pitanja: - Usporedbe: "Koja je razlika između X i Y?" - Sažetke: "Sažmi ključne točke o Z" -Promatrajte kako se ocjene relevantnosti mijenjaju ovisno o tome koliko dobro vaše pitanje odgovara sadržaju dokumenta. +Promatrajte kako se rezultati relevantnosti mijenjaju ovisno o tome koliko vaše pitanje odgovara sadržaju dokumenta. ## Ključni pojmovi -### Strategija dijeljenja na dijelove +### Strategija dijeljenja (chunkanja) -Dokumenti se dijele na dijelove od 300 tokena s preklapanjem od 30 tokena. Ovaj balans osigurava da svaki dio ima dovoljno konteksta da bude značajan, a istovremeno ostaje dovoljno mali da se u upit može uključiti više dijelova. +Dokumenti se dijele na dijelove od 300 tokena s preklapanjem od 30 tokena. Ovaj omjer osigurava da svaki dio ima dovoljno konteksta da bude smislen, a istovremeno ostaje dovoljno malen da se može uključiti više dijelova u upit. ### Rezultati sličnosti -Svaki dohvaćeni dio dolazi s ocjenom sličnosti između 0 i 1 koja pokazuje koliko je blisko povezan s pitanjem korisnika. Dijagram ispod vizualizira raspon rezultata i kako sustav koristi te vrijednosti za filtriranje rezultata: +Svaki dohvaćeni dio dolazi s rezultatom sličnosti između 0 i 1 koji pokazuje koliko je blisko odgovarao korisničkom pitanju. Dijagram u nastavku vizualizira raspon rezultata i kako sustav koristi te vrijednosti za filtriranje rezultata: -Similarity Scores +Rezultati sličnosti -*Ovaj dijagram prikazuje raspon rezultata od 0 do 1, s minimalnom granicom od 0.5 koja filtrira irelevantne dijelove.* +*Ovaj dijagram prikazuje raspon rezultata od 0 do 1, s minimalnim pragom od 0.5 koji filtrira nerelevantne dijelove.* -Ocjene se kreću od 0 do 1: -- 0,7-1,0: Vrlo relevantno, točno podudaranje -- 0,5-0,7: Relevantno, dobar kontekst -- Ispod 0,5: Filtrirano, previše različito +Rezultati se kreću od 0 do 1: +- 0.7-1.0: Vrlo relevantno, točno podudaranje +- 0.5-0.7: Relevantno, dobar kontekst +- Ispod 0.5: Filtrirano, previše različito -Sustav dohvaća samo dijelove iznad minimalne granice kako bi osigurao kvalitetu. +Sustav dohvaća samo dijelove koji prelaze minimalni prag kako bi osigurao kvalitetu. -Ugradnje dobro funkcioniraju kada se značenje jasno grupira, ali imaju i slabosti. Dijagram ispod prikazuje česte uzroke neuspjeha — dijelovi preveliki daju nejasne vektore, dijelovi premali nemaju kontekst, dvosmisleni pojmovi upućuju na više grupa, a točno podudaranje pretraživanja (ID-ovi, brojevi dijelova) uopće ne funkcionira s ugradnjama: +Ugradnje dobro funkcioniraju kad se značenje jasno grupira, ali imaju i slabosti. Dijagram u nastavku prikazuje uobičajene načine pada—preveliki dijelovi proizvode mutne vektore, premali dijelovi nemaju kontekst, dvosmisleni pojmovi upućuju na više klastera, a točna pretraživanja (ID-ovi, brojevi dijelova) uopće ne rade s ugradnjama: -Embedding Failure Modes +Načini neuspjeha ugradnje -*Ovaj dijagram prikazuje česte načine neuspjeha ugradnji: dijelovi preveliki, dijelovi premali, dvosmisleni pojmovi koji upućuju na više grupa, te točno podudaranje pretraživanja poput ID-ova.* +*Ovaj dijagram prikazuje uobičajene načine pada ugradnji: prevelike dijelove, premale dijelove, dvosmislene pojmove koji upućuju na više skupina, te točna pretraživanja poput ID-ova.* ### Pohrana u memoriji -Ovaj modul koristi pohranu u memoriji radi jednostavnosti. Kada ponovno pokrenete aplikaciju, preneseni dokumenti se gube. Produkcijski sustavi koriste trajne vektorske baze podataka kao što su Qdrant ili Azure AI Search. +Ovaj modul koristi pohranu u memoriji radi jednostavnosti. Kada ponovno pokrenete aplikaciju, preneseni dokumenti se izgube. Produkcijski sustavi koriste trajne vektorske baze podataka poput Qdranta ili Azure AI Search. ### Upravljanje kontekstnim prozorom -Svaki model ima maksimalni kontekstni prozor. Ne možete uključiti svaki dio iz velikog dokumenta. Sustav dohvaća prvih N najrelevantnijih dijelova (zadano 5) kako bi ostao unutar ograničenja, a istovremeno pružio dovoljan kontekst za točne odgovore. +Svaki model ima maksimalni kontekstni prozor. Ne možete uključiti svaki dio iz velikog dokumenta. Sustav dohvaća prvih N najrelevantnijih dijelova (zadano 5) kako bi ostao unutar granica, a istovremeno pružio dovoljno konteksta za točne odgovore. ## Kada je RAG važan -RAG nije uvijek pravi pristup. Vodič za odluke ispod pomaže vam utvrditi kad RAG donosi dodatnu vrijednost u odnosu na jednostavnije pristupe — poput uključivanja sadržaja izravno u upit ili oslanjanja na ugrađeno znanje modela: +RAG nije uvijek pravi pristup. Sljedeći vodič za odluku pomaže procijeniti kada RAG donosi dodatnu vrijednost, a kada su jednostavniji pristupi — poput direktnog uključivanja sadržaja u upit ili oslanjanja na ugrađeno znanje modela — dovoljni: -When to Use RAG +Kada koristiti RAG -*Ovaj dijagram prikazuje vodič za odluke kada RAG donosi vrijednost u odnosu na jednostavnije pristupe.* +*Ovaj dijagram prikazuje vodič za odluku kada RAG dodaje vrijednost nasuprot kad su jednostavniji pristupi dovoljni.* ## Sljedeći koraci @@ -427,11 +426,11 @@ RAG nije uvijek pravi pristup. Vodič za odluke ispod pomaže vam utvrditi kad R --- -**Navigacija:** [← Prethodno: Modul 02 - Prompt inženjering](../02-prompt-engineering/README.md) | [Natrag na početak](../README.md) | [Sljedeće: Modul 04 - Alati →](../04-tools/README.md) +**Navigacija:** [← Prethodno: Modul 02 - Inženjering prompta](../02-prompt-engineering/README.md) | [Natrag na početak](../README.md) | [Sljedeće: Modul 04 - Alati →](../04-tools/README.md) --- -**Odricanje od odgovornosti**: -Ovaj je dokument preveden korištenjem AI usluge za prevođenje [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za kritične informacije preporučuje se profesionalni ljudski prijevod. Ne snosimo odgovornost za bilo kakve nesporazume ili kriva tumačenja proizašla iz korištenja ovog prijevoda. +**Napomena**: +Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporuča se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešne interpretacije koje proizlaze iz korištenja ovog prijevoda. \ No newline at end of file diff --git a/translations/hr/04-tools/README.md b/translations/hr/04-tools/README.md index c378b2bec..e6ce8b0b1 100644 --- a/translations/hr/04-tools/README.md +++ b/translations/hr/04-tools/README.md @@ -1,76 +1,76 @@ -# Modul 04: AI Agenti s Alatima +# Modul 04: AI agenti s alatima ## Sadržaj -- [Video vodič](../../../04-tools) -- [Što ćete naučiti](../../../04-tools) -- [Preduvjeti](../../../04-tools) -- [Razumijevanje AI agenata s alatima](../../../04-tools) -- [Kako funkcionira pozivanje alata](../../../04-tools) - - [Definicije alata](../../../04-tools) - - [Donosenje odluka](../../../04-tools) - - [Izvršenje](../../../04-tools) - - [Generiranje odgovora](../../../04-tools) - - [Arhitektura: Spring Boot automatsko povezivanje](../../../04-tools) -- [Lanca alata](../../../04-tools) -- [Pokrenite aplikaciju](../../../04-tools) -- [Korištenje aplikacije](../../../04-tools) - - [Isprobajte jednostavnu uporabu alata](../../../04-tools) - - [Testirajte povezivanje alata](../../../04-tools) - - [Pogledajte tijek razgovora](../../../04-tools) - - [Eksperimentirajte s različitim upitima](../../../04-tools) -- [Ključni pojmovi](../../../04-tools) - - [ReAct obrazac (Razmišljanje i djelovanje)](../../../04-tools) - - [Opis alata je važan](../../../04-tools) - - [Upravljanje sesijama](../../../04-tools) - - [Rukovanje greškama](../../../04-tools) -- [Dostupni alati](../../../04-tools) -- [Kada koristiti agente temeljene na alatima](../../../04-tools) -- [Alati vs RAG](../../../04-tools) -- [Sljedeći koraci](../../../04-tools) +- [Video vodič](#video-vodič) +- [Što ćete naučiti](#što-ćete-naučiti) +- [Preduvjeti](#preduvjeti) +- [Razumijevanje AI agenata s alatima](#razumijevanje-ai-agenata-s-alatima) +- [Kako funkcionira pozivanje alata](#kako-funkcionira-pozivanje-alata) + - [Definicije alata](#definicije-alata) + - [Donošenje odluka](#donošenje-odluka) + - [Izvršavanje](#izvršavanje) + - [Generiranje odgovora](#generiranje-odgovora) + - [Arhitektura: Spring Boot automatsko povezivanje](#arhitektura-spring-boot-automatsko-povezivanje) +- [Povezivanje alata](#povezivanje-alata) +- [Pokrenite aplikaciju](#pokrenite-aplikaciju) +- [Korištenje aplikacije](#korištenje-aplikacije) + - [Isprobajte jednostavnu upotrebu alata](#isprobajte-jednostavnu-uporabu-alata) + - [Testirajte povezivanje alata](#testirajte-lančano-korištenje-alata) + - [Pogledajte tijek razgovora](#pogledajte-tijek-razgovora) + - [Eksperimentirajte s različitim zahtjevima](#eksperimentirajte-s-različitim-zahtjevima) +- [Ključni pojmovi](#ključni-pojmovi) + - [ReAct obrazac (razmišljanje i djelovanje)](#react-obrazac-razmišljanje-i-djelovanje) + - [Opis alata je važan](#opisi-alata-su-važni) + - [Upravljanje sesijama](#upravljanje-sesijom) + - [Rukovanje pogreškama](#rukovanje-pogreškama) +- [Dostupni alati](#dostupni-alati) +- [Kada koristiti agente temeljene na alatima](#kada-koristiti-agente-koji-koriste-alate) +- [Alati vs RAG](#alati-naspram-rag) +- [Sljedeći koraci](#daljnji-koraci) ## Video vodič -Pogledajte ovu sesiju uživo koja objašnjava kako započeti s ovim modulom: +Pogledajte ovu live sesiju koja objašnjava kako započeti s ovim modulom: AI Agents with Tools and MCP - Live Session ## Što ćete naučiti -Do sada ste naučili kako voditi razgovore s AI, učinkovito strukturirati upite i povezivati odgovore s vašim dokumentima. No postoji osnovno ograničenje: modeli jezika mogu generirati samo tekst. Ne mogu provjeriti vremensku prognozu, izvršavati izračune, pretraživati baze podataka ili komunicirati s vanjskim sustavima. +Do sada ste naučili kako voditi razgovore s AI, učinkovito strukturirati upite i povezati odgovore s vašim dokumentima. No postoji temeljno ograničenje: jezični modeli mogu samo generirati tekst. Ne mogu provjeriti vremensku prognozu, izračunavati, upitavati baze podataka ili komunicirati s vanjskim sustavima. -Alati to mijenjaju. Dajući modelu pristup funkcijama koje može pozvati, pretvarate ga iz generatora teksta u agenta koji može poduzimati akcije. Model odlučuje kada mu treba alat, koji alat koristiti i koje parametre proslijediti. Vaš kod izvršava funkciju i vraća rezultat. Model zatim uklapa taj rezultat u svoj odgovor. +Alati to mijenjaju. Dajući modelu pristup funkcijama koje može pozivati, pretvarate ga iz generatora teksta u agenta koji može poduzimati radnje. Model odlučuje kad mu treba alat, koji alat koristiti i koje parametre poslati. Vaš kod izvršava funkciju i vraća rezultat. Model taj rezultat uključuje u svoj odgovor. ## Preduvjeti -- Završili [Modul 01 - Uvod](../01-introduction/README.md) (postavljeni Azure OpenAI resursi) -- Preporučeno završiti prethodne module (ovaj modul se poziva na [RAG koncepte iz Modula 03](../03-rag/README.md) u usporedbi Alati vs RAG) -- `.env` datoteka u korijenskom direktoriju s Azure vjerodajnicama (kreirana pomoću `azd up` u Modulu 01) +- Završeni [Modul 01 - Uvod](../01-introduction/README.md) (procure Azure OpenAI resursi) +- Prethodni moduli preporučeni (ovaj modul se u usporedbi Alati vs RAG poziva na [RAG koncepte iz Modula 03](../03-rag/README.md)) +- `.env` datoteka u korijenskom direktoriju sa Azure vjerodajnicama (kreirana naredbom `azd up` u Modulu 01) -> **Napomena:** Ako niste završili Modul 01, slijedite tamo upute za postavljanje prije nastavka. +> **Napomena:** Ako niste završili Modul 01, prvo slijedite upute za postavljanje tamo. ## Razumijevanje AI agenata s alatima -> **📝 Napomena:** Termin „agenti“ u ovom modulu odnosi se na AI asistente proširene mogućnošću pozivanja alata. Ovo je različito od **Agentic AI** obrazaca (autonomni agenti s planiranjem, memorijom i višekorak razmišljanjem) koje ćemo obraditi u [Modul 05: MCP](../05-mcp/README.md). +> **📝 Napomena:** Termin "agenti" u ovom modulu odnosi se na AI asistente obogaćene sposobnostima pozivanja alata. To se razlikuje od **Agentic AI** obrazaca (autonomni agenti s planiranjem, memorijom i višestupanjskim zaključivanjem) koje ćemo obraditi u [Modulu 05: MCP](../05-mcp/README.md). -Bez alata, model jezika može samo generirati tekst iz svojih podataka za treniranje. Pitajte ga za vremensku prognozu i on može samo nagađati. Dajte mu alate i može pozvati vremenski API, izvesti izračune ili pretražiti bazu podataka — zatim uklopiti te stvarne rezultate u svoj odgovor. +Bez alata, jezični model može samo generirati tekst na temelju svojih podataka za učenje. Pitajte ga za trenutnu vremensku prognozu i on mora nagađati. Dajte mu alate i on može pozvati vremenski API, izračunavati ili upitavati bazu podataka — a zatim te stvarne rezultate utkati u svoj odgovor. -Bez alata vs S alatima +Without Tools vs With Tools -*Bez alata model samo nagađa — s alatima može pozivati API-je, izvršavati izračune i vraćati podatke u stvarnom vremenu.* +*Bez alata model može samo nagađati — s alatima može pozivati API-je, izvoditi izračune i vraćati podatke u stvarnom vremenu.* -AI agent s alatima slijedi obrazac **Razmišljanje i djelovanje (ReAct)**. Model ne samo da odgovara — razmišlja što mu treba, djeluje pozivajući alat, promatra rezultat, a zatim odlučuje hoće li opet djelovati ili dati konačni odgovor: +AI agent s alatima slijedi **ReAct** obrazac (razmišljanje i djelovanje). Model ne samo da odgovara — on razmišlja što mu treba, djeluje pozivajući alat, promatra rezultat, pa odlučuje hoće li ponovno djelovati ili dati konačni odgovor: -1. **Razmišlja** — agent analizira korisnikovo pitanje i odlučuje koju informaciju treba -2. **Djeluje** — agent odabire pravi alat, generira točne parametre i poziva ga -3. **Promatra** — agent prima izlaz alata i evaluira rezultat -4. **Ponavlja ili odgovara** — ako je potrebno više podataka, agent počinje ispočetka; inače sastavlja odgovor na prirodnom jeziku +1. **Razmišljanje** — Agent analizira korisničko pitanje i određuje koje informacije su mu potrebne +2. **Djelovanje** — Agent odabire pravi alat, generira ispravne parametre i poziva alat +3. **Promatranje** — Agent prima izlaz alata i evaluira rezultat +4. **Ponavljanje ili Odgovor** — Ako je potrebno više podataka, agent se vraća na početak; inače sastavlja odgovor u prirodnom jeziku -ReAct obrazac +ReAct Pattern -*Ciklus ReAct — agent razmišlja što učiniti, djeluje pozivajući alat, promatra rezultat i ponavlja dok ne može dati konačni odgovor.* +*ReAct ciklus — agent razmišlja što treba napraviti, djeluje pozivajući alat, promatra rezultat i ponavlja dok ne može dati konačni odgovor.* -Ovo se odvija automatski. Definirate alate i njihove opise. Model donosi odluke o tome kada i kako ih koristiti. +Ovo se događa automatski. Vi definirate alate i njihove opise. Model donosi odluke o tome kada i kako ih koristiti. ## Kako funkcionira pozivanje alata @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Vaša logika pretrage vremena + // Vaša logika za pretraživanje vremenske prognoze return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Asistent je automatski povezan preko Spring Boot sa: +// Asistent je automatski povezan putem Spring Boot-a sa: // - ChatModel bean // - Sve @Tool metode iz @Component klasa -// - ChatMemoryProvider za upravljanje sesijama +// - ChatMemoryProvider za upravljanje sesijom ``` -Dijagram ispod detaljno objašnjava svaku oznaku i pokazuje kako svaki dio pomaže AI-u razumjeti kada pozvati alat i koje argumente proslijediti: +Sljedeća dijagram razlaže svaku oznaku i pokazuje kako svaki dio pomaže AI-u da razumije kada pozvati alat i koje argumente poslati: -Anatomija definicija alata +Anatomy of Tool Definitions -*Anatomija definicije alata — @Tool govori AI-u kada ga koristiti, @P opisuje svaki parametar, a @AiService povezuje sve zajedno pri pokretanju.* +*Anatomija definicije alata — @Tool kaže AI-u kada ga koristiti, @P opisuje svaki parametar, a @AiService povezuje sve pri pokretanju.* > **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) i pitajte: -> - "Kako bih integrirao pravi vremenski API poput OpenWeatherMap umjesto lažnih podataka?" -> - "Što čini dobar opis alata koji pomaže AI-u da ga ispravno koristi?" -> - "Kako rukovati API greškama i ograničenjima učestalosti u implementacijama alata?" +> - "Kako bih integrirao pravi vremenski API poput OpenWeatherMap umjesto testnih podataka?" +> - "Što čini dobar opis alata koji pomaže AI-u da ga pravilno koristi?" +> - "Kako se nositi s API pogreškama i ograničenjima u implementacijama alata?" ### Donošenje odluka -Kad korisnik pita "Kakvo je vrijeme u Seattleu?", model nasumično ne bira alat. On uspoređuje korisnikovu namjeru sa svim opisima alata kojima ima pristup, ocjenjuje relevantnost svakog i odabire najbolju podudarnost. Zatim generira strukturirani poziv funkcije s pravim parametrima — u ovom slučaju postavljajući `location` na `"Seattle"`. +Kad korisnik pita "Kakvo je vrijeme u Seattleu?", model ne bira alat nasumično. On uspoređuje korisničku namjeru s opisima svakog dostupnog alata, ocjenjuje relevantnost i odabire najbolju opciju. Zatim generira strukturirani poziv funkcije s pravim parametrima — u ovom slučaju, `location` postavlja na `"Seattle"`. -Ako nijedan alat ne odgovara korisnikovom zahtjevu, model se vraća odgovoru iz vlastitog znanja. Ako ih više odgovara, bira najtočniji. +Ako nijedan alat ne odgovara zahtjevu korisnika, model se vraća na odgovore iz vlastitog znanja. Ako više alata odgovara, odabire najprecizniji. -Kako AI odlučuje koji alat koristiti +How the AI Decides Which Tool to Use -*Model evaluira svaki dostupni alat u odnosu na namjeru korisnika i odabire najbolju opciju — zato je pisanje jasnih i specifičnih opisa alata važno.* +*Model procjenjuje svaki dostupan alat u odnosu na korisničku namjeru i bira najbolju opciju — zbog toga je važno pisati jasne i specifične opise alata.* -### Izvršenje +### Izvršavanje [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot automatski povezuje deklarativni `@AiService` sučelje sa svim registriranim alatima, a LangChain4j automatski izvršava pozive alata. Iza scene, kompletan poziv alata prolazi kroz šest faza — od korisnikovog pitanja na prirodnom jeziku sve do odgovora na prirodnom jeziku: +Spring Boot automatski povezuje deklarativno `@AiService` sučelje sa svim registriranim alatima, a LangChain4j automatski izvršava pozive alata. Iza kulisa, kompletan poziv alata prolazi kroz šest faza — od korisničkog pitanja u prirodnom jeziku do odgovora u istom obliku: -Tijek poziva alata +Tool Calling Flow -*Cjelokupni tijek — korisnik postavi pitanje, model odabere alat, LangChain4j ga izvrši, a model uklopi rezultat u prirodni odgovor.* +*Krajnji tijek — korisnik postavlja pitanje, model bira alat, LangChain4j ga izvršava, a model uklapa rezultat u prirodni odgovor.* -Ako ste pokrenuli [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) u Modulu 00, već ste vidjeli ovaj obrazac u praksi — alati `Calculator` su pozivani na isti način. Sljedeći sekvencijski dijagram prikazuje što se točno dogodilo tijekom tog demo primjera: +Iza scene, `AiServices` pokreće isti ciklus pozivanja alata za bilo koji alat — ovdje prikazan s jednostavnim `Calculator`. Sekvencijski dijagram prikazuje što se točno događa u pozadini: -Sekvencijski dijagram poziva alata +Tool Calling Sequence Diagram -*Petlja poziva alata iz Quick Start demo primjera — `AiServices` šalje vašu poruku i šeme alata LLM-u, LLM odgovara pozivom funkcije poput `add(42, 58)`, LangChain4j lokalno izvršava metodu `Calculator`, i vraća rezultat za konačni odgovor.* +*Ciklus pozivanja alata — `AiServices` šalje vašu poruku i sheme alata LLM-u, LLM vraća funkcijski poziv poput `add(42, 58)`, LangChain4j lokalno izvršava metodu `Calculator`, i rezultat vraća na sastavljanje konačnog odgovora.* > **🤖 Isprobajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorite [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) i pitajte: -> - "Kako funkcionira ReAct obrazac i zašto je efikasan za AI agente?" +> - "Kako funkcionira ReAct obrazac i zašto je učinkovit za AI agente?" > - "Kako agent odlučuje koji alat koristiti i kojim redoslijedom?" -> - "Što se događa ako izvršenje alata ne uspije - kako trebam robusno rukovati greškama?" +> - "Što se događa ako izvršavanje alata ne uspije - kako robusno rukovati pogreškama?" ### Generiranje odgovora -Model prima vremenske podatke i formatira ih u odgovor na prirodnom jeziku za korisnika. +Model prima podatke o vremenu i oblikuje ih u prirodni odgovor za korisnika. ### Arhitektura: Spring Boot automatsko povezivanje -Ovaj modul koristi LangChain4j integraciju za Spring Boot s deklarativnim `@AiService` sučeljima. Pri pokretanju Spring Boot otkriva svaki `@Component` koji sadrži `@Tool` metode, vaš `ChatModel` instancu i `ChatMemoryProvider` — te ih sve povezuje u jedno `Assistant` sučelje bez dodatnog koda. +Ovaj modul koristi LangChain4j Spring Boot integraciju s deklarativnim `@AiService` sučeljima. Pri pokretanju, Spring Boot otkriva svaki `@Component` koji sadrži `@Tool` metode, vaš `ChatModel` bean i `ChatMemoryProvider` — te ih povezuje u jedinstveno `Assistant` sučelje bez dodatnog koda. -Arhitektura automatskog povezivanja Spring Boot +Spring Boot Auto-Wiring Architecture -*Sučelje @AiService povezuje ChatModel, komponente alata i davatelja memorije — Spring Boot automatski upravlja povezivanjem.* +*@AiService sučelje povezuje ChatModel, komponente alata i memory provider — Spring Boot automatski upravlja povezivanjem.* -Evo potpunog životnog ciklusa zahtjeva kao sekvencijskog dijagrama — od HTTP zahtjeva preko kontrolera, servisa i proxy-ja s automatskim povezivanjem, sve do izvršenja alata i natrag: +Evo kompletnog životnog ciklusa zahtjeva u obliku sekvencijskog dijagrama — od HTTP zahtjeva kroz kontroler, servis i automatski povezan proxy, do izvršavanja alata i vraćanja: -Sekvenca poziva alata u Spring Bootu +Spring Boot Tool Calling Sequence -*Cjelokupan životni ciklus zahtjeva u Spring Bootu — HTTP zahtjev prolazi kroz kontroler i servis do automatski povezanog proxy-ja Assistant-a, koji orkestrira LLM i pozive alata.* +*Kompletan Spring Boot životni ciklus zahtjeva — HTTP zahtjev prolazi kroz kontroler i servis do automatski povezanog Assistant proxy-ja koji orkestrira LLM i pozive alata automatski.* Ključne prednosti ovog pristupa: -- **Spring Boot automatsko povezivanje** — ChatModel i alati automatski injektirani -- **@MemoryId obrazac** — Automatsko upravljanje memorijom temeljeno na sesiji -- **Pojedinačna instanca** — Assistant kreiran jednom i ponovno korišten radi bolje izvedbe -- **Izvršenje tipa sigurno za tipove** — Java metode pozvane izravno s konverzijom tipova -- **Orkestracija više koraka** — Automatska podrška za povezivanje alata u lanac -- **Nula dodatnog koda** — Nema ručnih `AiServices.builder()` poziva ili memorijskih HashMapa +- **Spring Boot automatsko povezivanje** — ChatModel i alati injektirani automatski +- **@MemoryId obrazac** — Automatsko upravljanje memorijom po sesiji +- **Jedinstvena instanca** — Assistant kreiran jednom i ponovno korišten za bolju izvedbu +- **Sigurno izvršavanje po tipu** — Java metode pozivane direktno s konverzijom tipova +- **Višestupanjska orkestracija** — Automatski rukuje povezivanjem alata +- **Nula suvišnog koda** — Nema ručnih poziva `AiServices.builder()` niti memorijskih HashMap-a -Alternativni pristupi (ručni `AiServices.builder()`) zahtijevaju više koda i nemaju prednosti Spring Boot integracije. +Alternativni pristupi (ručni `AiServices.builder()`) zahtijevaju više koda i ne iskorištavaju prednosti Spring Boot integracije. ## Povezivanje alata -**Povezivanje alata** — Prava snaga agenata temeljena na alatima dolazi do izražaja kada jedno pitanje zahtijeva više alata. Pitajte: "Kakvo je vrijeme u Seattleu u Fahrenheitu?" i agent automatski povezuje dva alata: prvo poziva `getCurrentWeather` da dobije temperaturu u Celzijusima, zatim tu vrijednost prosljeđuje u `celsiusToFahrenheit` za konverziju — sve u jednom krugu razgovora. +**Povezivanje alata** — prava snaga agenata temeljenih na alatima dolazi do izražaja kad jedno pitanje zahtijeva više alata. Pitajte "Kakvo je vrijeme u Seattleu u Fahrenheitima?" i agent automatski povezuje dva alata: prvo poziva `getCurrentWeather` za temperaturu u Celzijusima, zatim prosljeđuje tu vrijednost u `celsiusToFahrenheit` za konverziju — sve u jednom koraku razgovora. -Primjer povezivanja alata +Tool Chaining Example *Povezivanje alata u praksi — agent prvo poziva getCurrentWeather, zatim šalje rezultat u Celzijusima u celsiusToFahrenheit i daje objedinjeni odgovor.* -**Graceful Failures** — Pitajte za vremensku prognozu u gradu koji nije u lažnim podacima. Alat vraća poruku o grešci, a AI objašnjava da ne može pomoći umjesto da se sruši. Alati sigurnosno prijavljuju greške. Dijagram ispod uspoređuje oba pristupa — uz pravilno rukovanje greškama, agent uhvati iznimku i odgovori korisno, bez toga cijela aplikacija pada: +**Lagana obrada pogrešaka** — Pitajte za vrijeme u gradu koji nije u testnim podacima. Alat vraća poruku o pogrešci, a AI objašnjava da ne može pomoći umjesto da se sruši. Alati se sigurno kvare. Sljedeći dijagram uspoređuje dva pristupa — uz pravilnu obradu pogrešaka, agent hvata iznimku i korisno odgovara, dok bez nje cijela aplikacija pada: -Tijek rukovanja greškama +Error Handling Flow -*Kada alat zakaže, agent uhvati grešku i odgovara korisnim objašnjenjem umjesto rušenja.* +*Kad alat zakaže, agent hvata pogrešku i korisno objašnjava umjesto da izazove pad aplikacije.* -Ovo se događa u jednom krugu razgovora. Agent samostalno orkestrira višestruke pozive alata. +Sve se događa u jednom koraku razgovora. Agent samostalno orkestrira višestruke pozive alata. ## Pokrenite aplikaciju -**Provjerite implementaciju:** +**Provjerite postavke:** -Provjerite postoji li `.env` datoteka u korijenskom direktoriju s Azure vjerodajnicama (kreirana tijekom Modula 01). Pokrenite ovo iz direktorija modula (`04-tools/`): +Provjerite postoji li `.env` datoteka u korijenskom direktoriju sa Azure vjerodajnicama (kreirana tijekom Modula 01). Pokrenite ovo iz direktorija ovog modula (`04-tools/`): **Bash:** ```bash @@ -207,24 +207,24 @@ Get-Content ..\.env # Trebalo bi prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPL **Pokrenite aplikaciju:** -> **Napomena:** Ako ste već pokrenuli sve aplikacije koristeći `./start-all.sh` iz korijenskog direktorija (kako je opisano u Modulu 01), ovaj modul već radi na portu 8084. Možete preskočiti naredbe za pokretanje ispod i odmah otići na http://localhost:8084. +> **Napomena:** Ako ste već pokrenuli sve aplikacije pomoću `./start-all.sh` iz korijena (kako je opisano u Modulu 01), ovaj modul već radi na portu 8084. Možete preskočiti naredbe za pokretanje i odmah otići na http://localhost:8084. -**Opcija 1: Korištenje Spring Boot Dashboarda (Preporučeno za VS Code korisnike)** +**Opcija 1: Korištenje Spring Boot nadzorne ploče (preporučeno za korisnike VS Code-a)** -Dev kontejner uključuje ekstenziju Spring Boot Dashboard koja pruža vizualno sučelje za upravljanje svim Spring Boot aplikacijama. Možete je pronaći u Activity Baru na lijevoj strani VS Code-a (potražite Spring Boot ikonu). +Razvojni kontejner uključuje ekstenziju Spring Boot Dashboard koja pruža vizualni sučelje za upravljanje svim Spring Boot aplikacijama. Možete je pronaći u traci aktivnosti na lijevoj strani VS Code-a (potražite ikonu Spring Boot). -Iz Spring Boot Dashboarda možete: -- Vidjeti sve dostupne Spring Boot aplikacije u radnom prostoru +Iz Spring Boot nadzorne ploče možete: +- Vidjeti sve dostupne Spring Boot aplikacije u prostoru za rad - Pokrenuti/zaustaviti aplikacije jednim klikom -- Prikazivati logove aplikacije u stvarnom vremenu -- Pratiti status aplikacije -Jednostavno kliknite gumb za reprodukciju pored "tools" za pokretanje ovog modula ili pokrenite sve module odjednom. +- Pregledavati dnevnik aplikacija u stvarnom vremenu +- Nadzirati status aplikacija -Evo kako Spring Boot nadzorna ploča izgleda u VS Code-u: +Jednostavno kliknite gumb za pokretanje pored "tools" da pokrenete ovaj modul, ili pokrenite sve module odjednom. -Spring Boot Dashboard +Evo kako Spring Boot nadzorna ploča izgleda u VS Code-u: +Spring Boot nadzorna ploča -*Spring Boot nadzorna ploča u VS Code-u — pokrenite, zaustavite i pratite sve module s jednog mjesta* +*Spring Boot nadzorna ploča u VS Code — pokrenite, zaustavite i nadgledajte sve module s jednog mjesta* **Opcija 2: Korištenje shell skripti** @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Obje skripte automatski učitavaju varijable okoline iz glavne `.env` datoteke i izgrađuju JAR-ove ako ne postoje. +Oba skripta automatski učitavaju varijable okoline iz glavne `.env` datoteke i izgradit će JAR-ove ako ne postoje. -> **Napomena:** Ako želite ručno izgraditi sve module prije pokretanja: +> **Napomena:** Ako radije želite ručno izgraditi sve module prije pokretanja: > > **Bash:** > ```bash @@ -272,7 +272,7 @@ Obje skripte automatski učitavaju varijable okoline iz glavne `.env` datoteke i > mvn clean package -DskipTests > ``` -Otvorite http://localhost:8084 u vašem pregledniku. +Otvorite http://localhost:8084 u svom pregledniku. **Za zaustavljanje:** @@ -292,96 +292,96 @@ cd ..; .\stop-all.ps1 # Svi moduli ## Korištenje aplikacije -Aplikacija pruža web sučelje gdje možete komunicirati s AI agentom koji ima pristup alatima za vremensku prognozu i pretvorbu temperature. Evo kako sučelje izgleda — uključuje primjere za brz početak i chat panel za slanje upita: +Aplikacija pruža web sučelje gdje možete komunicirati s AI agentom koji ima pristup alatima za vremensku prognozu i pretvorbu temperature. Evo kako sučelje izgleda — uključuje primjere za brzi početak i chat panel za slanje zahtjeva: -AI Agent Tools Interface +Sučelje AI agent alata *Sučelje AI Agent Tools - brzi primjeri i chat sučelje za interakciju s alatima* -### Isprobajte jednostavno korištenje alata +### Isprobajte jednostavnu uporabu alata -Započnite s jednostavnim zahtjevom: "Pretvori 100 stupnjeva Fahrenheita u Celzijuse". Agent prepoznaje da mu treba alat za pretvorbu temperature, poziva ga s pravim parametrima i vraća rezultat. Primijetite koliko je prirodno — niste naveli koji alat koristiti niti kako ga pozvati. +Započnite sa jednostavnim zahtjevom: "Pretvori 100 stupnjeva Fahrenheit u Celzij." Agent prepoznaje da treba alat za pretvorbu temperature, poziva ga s odgovarajućim parametrima i vraća rezultat. Primijetite koliko je to prirodno - niste specificirali koji alat koristiti ili kako ga pozvati. -### Isprobajte povezivanje alata +### Testirajte lančano korištenje alata -Sada pokušajte složeniji zahtjev: "Kakvo je vrijeme u Seattleu i pretvori ga u Fahrenheite?" Promatrajte kako agent radi u koracima. Prvo dohvaća vremensku prognozu (koja vraća Celzijuse), prepoznaje da treba pretvoriti u Fahrenheite, poziva alat za pretvorbu i kombinira oba rezultata u jedan odgovor. +Sada pokušajte nešto složenije: "Kakvo je vrijeme u Seattleu i pretvori ga u Fahrenheit?" Promatrajte kako agent to obrađuje u koracima. Prvo dobiva vremensku prognozu (koja vraća Celzij), prepoznaje da treba pretvoriti u Fahrenheit, poziva alat za pretvorbu i spaja oba rezultata u jedan odgovor. ### Pogledajte tijek razgovora -Chat sučelje održava povijest razgovora, što vam omogućuje višekratne interakcije. Možete vidjeti sve prethodne upite i odgovore, olakšavajući praćenje razgovora i razumijevanje kako agent gradi kontekst kroz više izmjena. +Chat sučelje održava povijest razgovora, što vam omogućuje višekratne interakcije. Možete vidjeti sve prethodne upite i odgovore, što olakšava praćenje razgovora i razumijevanje kako agent gradi kontekst kroz više izmjena. -Conversation with Multiple Tool Calls +Razgovor s višestrukim pozivima alata -*Višekratni razgovor koji pokazuje jednostavne pretvorbe, provjere vremena i povezivanje alata* +*Višekratni razgovor koji pokazuje jednostavne pretvorbe, preglede vremenske prognoze i lančano korištenje alata* ### Eksperimentirajte s različitim zahtjevima Isprobajte razne kombinacije: -- Provjere vremena: "Kakvo je vrijeme u Tokiju?" -- Pretvorba temperatura: "Koliko je 25°C u Kelvinima?" +- Pregledi vremenske prognoze: "Kakvo je vrijeme u Tokiju?" +- Pretvorbe temperature: "Koliko je 25°C u Kelvinu?" - Kombinirani upiti: "Provjeri vrijeme u Parizu i reci mi je li iznad 20°C" -Primijetite kako agent interpretira prirodni jezik i preslikava ga na odgovarajuće pozive alata. +Primijetite kako agent interpretira prirodni jezik i povezuje ga s odgovarajućim pozivima alata. -## Ključni koncepti +## Ključni pojmovi -### ReAct obrazac (razmišljanje i djelovanje) +### ReAct obrazac (Razmišljanje i djelovanje) -Agent naizmjenično razmišlja (odlučuje što napraviti) i djeluje (koristi alate). Ovaj obrazac omogućava autonomno rješavanje problema umjesto da samo reagira na upute. +Agent naizmjence razmišlja (odlučuje što učiniti) i djeluje (koristi alate). Ovaj obrazac omogućuje autonomno rješavanje problema umjesto samo odgovaranja na upute. ### Opisi alata su važni -Kvaliteta opisa vaših alata izravno utječe na to koliko ih agent koristi. Jasni, specifični opisi pomažu modelu razumjeti kada i kako pozvati svaki alat. +Kvaliteta opisa vaših alata izravno utječe na to koliko ih agent učinkovito koristi. Jasni, specifični opisi pomažu modelu da razumije kada i kako pozvati svaki alat. -### Upravljanje sesijama +### Upravljanje sesijom -`@MemoryId` anotacija omogućava automatsko upravljanje memorijom na temelju sesija. Svaki ID sesije dobiva vlastitu `ChatMemory` instancu kojom upravlja `ChatMemoryProvider` bean, pa više korisnika može istovremeno komunicirati s agentom bez miješanja razgovora. Sljedeća dijagram ilustrira kako se više korisnika usmjerava u izolirane memorijske pohrane temeljene na njihovim ID-evima sesija: +@MemoryId anotacija omogućava automatsko upravljanje memorijom baziranom na sesiji. Svakom ID-u sesije dodjeljuje se vlastita instanca `ChatMemory` kojom upravlja `ChatMemoryProvider` bean, tako da više korisnika može istovremeno komunicirati s agentom bez međusobnog miješanja razgovora. Sljedeća shema prikazuje kako su više korisnika usmjereni na izolirane memorijske spremnike prema njihovim ID-ovima sesije: -Session Management with @MemoryId +Upravljanje sesijom s @MemoryId -*Svaki ID sesije preslikava se na izoliranu povijest razgovora — korisnici nikada ne vide poruke jedni drugih.* +*Svaki ID sesije mapira se na izoliranu povijest razgovora — korisnici nikada ne vide poruke jedni drugih.* -### Rukovanje greškama +### Rukovanje pogreškama -Alati mogu zakazati — API-ji mogu isteći, parametri mogu biti neispravni, vanjske usluge mogu pasti. Produkcijski agenti trebaju rukovanje greškama kako bi model mogao objasniti probleme ili pokušati alternative umjesto da se cijela aplikacija sruši. Kada alat baci iznimku, LangChain4j ju uhvati i prosljeđuje poruku o grešci natrag modelu, koji potom može objasniti problem prirodnim jezikom. +Alati mogu zakašljati — API-ji mogu isteći, parametri mogu biti nevaljani, vanjske usluge mogu prestati raditi. Producenti agenata trebaju rukovanje pogreškama kako bi model mogao objasniti probleme ili pokušati alternative umjesto da cijela aplikacija padne. Kad alat baci iznimku, LangChain4j je uhvati i proslijedi poruku o pogrešci natrag modelu, koji tada može objasniti problem prirodnim jezikom. ## Dostupni alati -Sljedeći dijagram prikazuje širok ekosustav alata koje možete izgraditi. Ovaj modul pokazuje alate za vremensku prognozu i temperaturu, ali isti `@Tool` obrazac djeluje za bilo koju Java metodu — od upita u bazu podataka do obrade plaćanja. +Sljedeća ilustracija prikazuje široki ekosustav alata koje možete izgraditi. Ovaj modul demonstrira vremenske i temperaturne alate, ali isti `@Tool` obrazac radi za bilo koju Java metodu — od upita u bazu podataka do obrade plaćanja. -Tool Ecosystem +Ekosustav alata -*Svaka Java metoda označena s @Tool postaje dostupna AI-u — obrazac se proširuje na baze podataka, API-je, email, rad s datotekama i još mnogo toga.* +*Svaka Java metoda označena s @Tool postaje dostupna AI-u — obrazac se širi na baze podataka, API-je, e-mail, rad s datotekama i još mnogo toga.* -## Kada koristiti agente temeljene na alatima +## Kada koristiti agente koji koriste alate -Ne svaki zahtjev treba alate. Odluka ovisi o tome treba li AI-u interakcija s vanjskim sustavima ili može odgovoriti iz vlastitog znanja. Sljedeći vodič sažima kada alati donose vrijednost, a kada nisu potrebni: +Ne treba svaki zahtjev koristiti alate. Odluka ovisi o tome treba li AI interakciju s vanjskim sustavima ili može odgovoriti iz vlastitog znanja. Sljedeći vodič sažima kada alati donose vrijednost, a kada nisu potrebni: -When to Use Tools +Kada koristiti alate -*Brzi vodič za odluke — alati služe za podatke u stvarnom vremenu, izračune i akcije; opće znanje i kreativni zadaci ih ne trebaju.* +*Brzi vodič za odluke — alati su za podatke u stvarnom vremenu, izračune i radnje; opće znanje i kreativni zadaci ih ne trebaju.* -## Alati nasuprot RAG-u +## Alati naspram RAG -Moduli 03 i 04 proširuju mogućnosti AI-a, ali na sasvim različite načine. RAG omogućuje modelu pristup **znanju** dohvaćanjem dokumenata. Alati omogućuju modelu da poduzima **akcije** pozivanjem funkcija. Sljedeći dijagram uspoređuje ove dvije pristupe - od načina rada svakog tijeka rada do kompromisa između njih: +Moduli 03 i 04 oboje proširuju što AI može učiniti, ali na temeljno različite načine. RAG omogućuje modelu pristup **znanju** dohvaćanjem dokumenata. Alati omogućuju modelu da poduzima **radnje** pozivajući funkcije. Sljedeća ilustracija uspoređuje ova dva pristupa jedan uz drugi — od načina rada svakog tijeka do kompromisa između njih: -Tools vs RAG Comparison +Usporedba Alati vs RAG -*RAG dohvaća informacije iz statičnih dokumenata — Alati izvršavaju akcije i dohvaćaju dinamičke, stvarne podatke. Mnogi produkcijski sustavi kombiniraju oboje.* +*RAG dohvaća informacije iz statičnih dokumenata — alati izvršavaju radnje i dohvaćaju dinamične, podatke u stvarnom vremenu. Mnogi produkcijski sustavi kombiniraju oba.* -U praksi mnogi produkcijski sustavi kombiniraju oba pristupa: RAG za utemeljenje odgovora u vašoj dokumentaciji, i Alate za dohvaćanje živih podataka ili izvođenje operacija. +U praksi, mnogi produkcijski sustavi kombiniraju oba pristupa: RAG za osnivanje odgovora u dokumentaciji, i Alate za dohvat uživo podataka ili izvođenje operacija. -## Sljedeći koraci +## Daljnji koraci **Sljedeći modul:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**Navigacija:** [← Prethodni: Modul 03 - RAG](../03-rag/README.md) | [Povratak na početak](../README.md) | [Sljedeći: Modul 05 - MCP →](../05-mcp/README.md) +**Navigacija:** [← Prethodni: Modul 03 - RAG](../03-rag/README.md) | [Natrag na početak](../README.md) | [Sljedeći: Modul 05 - MCP →](../05-mcp/README.md) --- -**Izjava o odricanju od odgovornosti**: -Ovaj dokument preveden je korištenjem AI usluge za prijevod [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na izvornom jeziku smatra se službenim i autoritativnim. Za važne informacije preporučuje se profesionalni ljudski prijevod. Ne snosimo odgovornost za bilo kakva nesporazuma ili pogrešne interpretacije proizašle iz korištenja ovog prijevoda. +**Napomena**: +Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporuča se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešne interpretacije koje proizlaze iz korištenja ovog prijevoda. \ No newline at end of file diff --git a/translations/hr/README.md b/translations/hr/README.md index bf817537a..032e06045 100644 --- a/translations/hr/README.md +++ b/translations/hr/README.md @@ -6,14 +6,14 @@ Tečaj za izgradnju AI aplikacija s LangChain4j i Azure OpenAI GPT-5.2, od osnov ### 🌐 Podrška za više jezika -#### Podržano putem GitHub akcije (automatizirano i uvijek ažurirano) +#### Podržano putem GitHub Akcije (Automatski i uvijek ažurno) -[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](./README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) +[Arabski](../ar/README.md) | [Bengalski](../bn/README.md) | [Bugarski](../bg/README.md) | [Burmanski (Myanmar)](../my/README.md) | [Kineski (pojednostavljeni)](../zh-CN/README.md) | [Kineski (tradicionalni, Hong Kong)](../zh-HK/README.md) | [Kineski (tradicionalni, Makao)](../zh-MO/README.md) | [Kineski (tradicionalni, Tajvan)](../zh-TW/README.md) | [Hrvatski](./README.md) | [Češki](../cs/README.md) | [Danski](../da/README.md) | [Nizozemski](../nl/README.md) | [Estonski](../et/README.md) | [Finski](../fi/README.md) | [Francuski](../fr/README.md) | [Njemački](../de/README.md) | [Grčki](../el/README.md) | [Hebrejski](../he/README.md) | [Hindi](../hi/README.md) | [Mađarski](../hu/README.md) | [Indonezijski](../id/README.md) | [Talijanski](../it/README.md) | [Japanski](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korejski](../ko/README.md) | [Litavski](../lt/README.md) | [Malajski](../ms/README.md) | [Malajalamski](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalski](../ne/README.md) | [Nigerijski pidžin](../pcm/README.md) | [Norveški](../no/README.md) | [Perzijski (Farsi)](../fa/README.md) | [Poljski](../pl/README.md) | [Portugalski (Brazil)](../pt-BR/README.md) | [Portugalski (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Rumunjski](../ro/README.md) | [Ruski](../ru/README.md) | [Srpski (ćirilica)](../sr/README.md) | [Slovački](../sk/README.md) | [Slovenski](../sl/README.md) | [Španjolski](../es/README.md) | [Svahili](../sw/README.md) | [Švedski](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Tajlandski](../th/README.md) | [Turski](../tr/README.md) | [Ukrajinski](../uk/README.md) | [Urdu](../ur/README.md) | [Vijetnamski](../vi/README.md) -> **Radije klonirati lokalno?** +> **Radije želite klonirati lokalno?** > -> Ovo spremište uključuje više od 50 prijevoda jezika što znatno povećava veličinu preuzimanja. Za kloniranje bez prijevoda, koristite sparse checkout: +> Ovaj repozitorij uključuje više od 50 prijevoda jezika što znatno povećava veličinu preuzimanja. Za kloniranje bez prijevoda, upotrijebite sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,28 +29,27 @@ Tečaj za izgradnju AI aplikacija s LangChain4j i Azure OpenAI GPT-5.2, od osnov > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> To vam daje sve što vam treba za dovršetak tečaja s mnogo bržim preuzimanjem. +> Ovo vam daje sve što trebate za dovršetak tečaja s mnogo bržim preuzimanjem. ## Sadržaj -1. [Brzi početak](00-quick-start/README.md) - Počnite s LangChain4j -2. [Uvod](01-introduction/README.md) - Naučite osnove LangChain4j -3. [Izrada upita (Prompt Engineering)](02-prompt-engineering/README.md) - Ovladavanje učinkovitim dizajnom upita -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Izgradite inteligentne sustave zasnovane na znanju -5. [Alati](04-tools/README.md) - Integrirajte vanjske alate i jednostavne asistente -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Rad s Model Context Protocol (MCP) i Agent modulima +1. [Uvod](01-introduction/README.md) - Naučite osnove LangChain4j +2. [Dizajn upita (Prompt Engineering)](02-prompt-engineering/README.md) - Ovladavanje efektivnim dizajnom upita +3. [RAG (poboljšana generacija)](03-rag/README.md) - Izgradite inteligentne sustave znanja +4. [Alati](04-tools/README.md) - Integrirajte vanjske alate i jednostavne asistente +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Rad s Model Context Protocol (MCP) i agentnim modulima ### Video vodiči -Svaki modul ima prateću sesiju uživo tijekom koje prolazimo kroz koncepte i kod korak po korak. +Svaki modul ima prateću live sesiju gdje detaljno prolazimo koncepte i kod korak po korak. | Modul | Video | |--------|-------| -| 01 - Uvod | [Početak rada s LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Izrada upita | [Izrada upita s LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - Uvod | [Početak s LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Dizajn upita | [Prompt Engineering s LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG s LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Alati i 05 - MCP | [AI agenti s alatima i MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Alati & 05 - MCP | [AI agenti s alatima i MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- @@ -60,30 +59,30 @@ Svaki modul ima prateću sesiju uživo tijekom koje prolazimo kroz koncepte i ko > **Brzi početak** -1. Forkajte ovo spremište na svoj GitHub račun +1. Napravite fork ovog repozitorija na svoj GitHub račun 2. Kliknite **Code** → karticu **Codespaces** → **...** → **New with options...** -3. Koristite zadane postavke – odabrati će se razvojnokontejner kreiran za ovaj tečaj +3. Koristite zadane vrijednosti – ovo će odabrati razvojni kontejner kreiran za ovaj tečaj 4. Kliknite **Create codespace** 5. Pričekajte 5-10 minuta da se okruženje pripremi -6. Odmah krenite na [Brzi početak](./00-quick-start/README.md) da započnete! +6. Odmah krenite na [Uvod](./01-introduction/README.md) i započnite! Nakon dovršetka modula, istražite [Vodič za testiranje](docs/TESTING.md) da vidite koncepte testiranja LangChain4j u praksi. -> **Napomena:** Ova obuka koristi i GitHub modele i Azure OpenAI. Modul [Brzi početak](00-quick-start/README.md) koristi GitHub modele (nije potrebna pretplata na Azure), dok moduli 1-5 koriste Azure OpenAI. Počnite s [BESPLATNIM Azure računom](https://aka.ms/azure-free-account) ako ga nemate. +> **Napomena:** Ova obuka koristi Azure OpenAI. Započnite s [BESPLATNIM Azure računom](https://aka.ms/azure-free-account) ako ga još nemate. ## Učenje s GitHub Copilotom -Za brz početak kodiranja otvorite ovaj projekt u GitHub Codespaceu ili svojem lokalnom IDE-u koristeći priloženi devcontainer. Devcontainer korišten u ovom tečaju dolazi unaprijed konfiguriran s GitHub Copilotom za AI u parnom programiranju. +Da brzo započnete s kodiranjem, otvorite ovaj projekt u GitHub Codespace ili u svom lokalnom IDE-u s priloženim devcontainerom. Devcontainer korišten u ovom tečaju dolazi unaprijed konfiguriran s GitHub Copilotom za AI zajedničko programiranje. Svaki primjer koda uključuje predložena pitanja koja možete postaviti GitHub Copilotu za dublje razumijevanje. Potražite 💡/🤖 oznake u: -- **zaglavljima Java datoteka** - pitanja specifična za svaki primjer -- **README datotekama modula** - istraživačke upute nakon primjera koda +- **Zaglavlja Java datoteka** - Pitanja specifična za svaki primjer +- **READMEs modula** - Poticaji za istraživanje nakon primjera koda **Kako koristiti:** Otvorite bilo koju datoteku s kodom i postavite Copilotu predložena pitanja. Ima potpuni kontekst baze koda i može objasniti, proširiti i predložiti alternative. -Želite li naučiti više? Pogledajte [Copilot za AI parno programiranje](https://aka.ms/GitHubCopilotAI). +Želite li saznati više? Pogledajte [Copilot za AI zajedničko programiranje](https://aka.ms/GitHubCopilotAI). ## Dodatni resursi @@ -103,7 +102,7 @@ Svaki primjer koda uključuje predložena pitanja koja možete postaviti GitHub --- -### Generativni AI serijal +### Serija Generativnog AI [![Generativni AI za početnike](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generativni AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generativni AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) @@ -111,40 +110,40 @@ Svaki primjer koda uključuje predložena pitanja koja možete postaviti GitHub --- -### Osnovno učenje +### Temeljno učenje [![ML za početnike](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science za početnike](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI za početnike](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Kibernetička sigurnost za početnike](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Web razvoj za početnike](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT za početnike](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR razvoj za početnike](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Copilot serija -[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +### Serija Copilot +[![Copilot za AI programiranje u paru](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot za C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot avantura](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Dobivanje pomoći -Ako zapnete ili imate bilo kakvih pitanja o izradi AI aplikacija, pridružite se: +Ako zapnete ili imate pitanja o izradi AI aplikacija, pridružite se: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Ako imate povratne informacije o proizvodu ili greške tijekom izrade, posjetite: +Ako imate povratne informacije o proizvodu ili se pojave greške tijekom izrade, posjetite: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licenca -MIT licenca - Pogledajte datoteku [LICENSE](../../LICENSE) za detalje. +MIT licenca - pogledajte datoteku [LICENSE](../../LICENSE) za detalje. --- -**Odricanje od odgovornosti**: -Ovaj dokument preveden je korištenjem AI prevoditeljskog servisa [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za ključne informacije preporučuje se profesionalni ljudski prijevod. Ne odgovaramo za bilo kakve nesporazume ili kriva tumačenja koja proizlaze iz uporabe ovog prijevoda. +**Napomena**: +Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporuča se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešne interpretacije koje proizlaze iz korištenja ovog prijevoda. \ No newline at end of file diff --git a/translations/hr/docs/GLOSSARY.md b/translations/hr/docs/GLOSSARY.md index 54eb6e08f..e8a388328 100644 --- a/translations/hr/docs/GLOSSARY.md +++ b/translations/hr/docs/GLOSSARY.md @@ -2,145 +2,145 @@ ## Sadržaj -- [Osnovni pojmovi](../../../docs) -- [Komponente LangChain4j](../../../docs) -- [Pojmovi AI/ML](../../../docs) -- [Sigurnosne mjere](../../../docs) -- [Inženjerstvo upita](../../../docs) -- [RAG (Generiranje uz pomoć dohvaćanja)](../../../docs) -- [Agent i alati](../../../docs) -- [Agentni modul](../../../docs) -- [Protokol konteksta modela (MCP)](../../../docs) -- [Azure usluge](../../../docs) -- [Testiranje i razvoj](../../../docs) - -Brzi pregled termina i pojmova korištenih tijekom tečaja. +- [Osnovni pojmovi](#osnovni-pojmovi) +- [Komponente LangChain4j](#komponente-langchain4j) +- [Pojmovi iz AI/ML](#pojmovi-iz-aiml) +- [Zaštitne mjere](#zaštitne-mjere) +- [Inženjering promptova](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agent i alati](#agents-and-tools---module-04) +- [Agentni modul](#agentic-module---module-05) +- [Protokol konteksta modela (MCP)](#model-context-protocol-mcp---module-05) +- [Azure usluge](#azure-services---module-01) +- [Testiranje i razvoj](#testing-and-development---testing-guide) + +Brzi pregled termina i koncepata korištenih kroz cijeli tečaj. ## Osnovni pojmovi -**AI Agent** - Sustav koji koristi AI za autonomno zaključivanje i djelovanje. [Modul 04](../04-tools/README.md) +**AI agent** - Sustav koji koristi AI za zaključivanje i autonomno djelovanje. [Modul 04](../04-tools/README.md) -**Lanac** - Sekvenca operacija gdje izlaz služi kao ulaz za sljedeći korak. +**Lanac** - Niz operacija gdje izlaz služi kao ulaz u sljedeći korak. -**Chunking** - Razbijanje dokumenata na manje dijelove. Tipično: 300-500 tokena s preklapanjem. [Modul 03](../03-rag/README.md) +**Chunking** - Dijeljenje dokumenata na manje dijelove. Tipično: 300-500 tokena s preklapanjem. [Modul 03](../03-rag/README.md) -**Prozor konteksta** - Maksimalan broj tokena koje model može obraditi. GPT-5.2: 400K tokena (do 272K ulaz, 128K izlaz). +**Prozor konteksta** - Maksimalni broj tokena koje model može obraditi. GPT-5.2: 400K tokena (do 272K ulaz, 128K izlaz). **Ugrađivanja (Embeddings)** - Numerički vektori koji predstavljaju značenje teksta. [Modul 03](../03-rag/README.md) -**Pozivanje funkcije** - Model generira strukturirane zahtjeve za pozivanje vanjskih funkcija. [Modul 04](../04-tools/README.md) +**Pozivanje funkcija** - Model generira strukturirane zahtjeve za pozivanje vanjskih funkcija. [Modul 04](../04-tools/README.md) **Halucinacija** - Kada modeli generiraju netočne, ali uvjerljive informacije. -**Upit (Prompt)** - Tekstualni ulaz za jezični model. [Modul 02](../02-prompt-engineering/README.md) +**Prompt** - Tekstualni ulaz za jezični model. [Modul 02](../02-prompt-engineering/README.md) -**Semantičko pretraživanje** - Pretraživanje prema značenju koristeći ugrađivanja, ne ključne riječi. [Modul 03](../03-rag/README.md) +**Semantičko pretraživanje** - Pretraživanje po značenju pomoću embeddingsa, ne ključnih riječi. [Modul 03](../03-rag/README.md) -**Stanje vs Bez stanja** - Bez stanja: bez memorije. Sa stanjem: čuva povijest razgovora. [Modul 01](../01-introduction/README.md) +**Stanje s memorijom vs bez memorije** - Bez memorije: nema pamćenja. Sa memorijom: održava povijest razgovora. [Modul 01](../01-introduction/README.md) -**Tokeni** - Osnovne tekstualne jedinice koje modeli obrađuju. Utječu na troškove i ograničenja. [Modul 01](../01-introduction/README.md) +**Tokeni** - Osnovne jedinice teksta koje modeli obrađuju. Utječu na troškove i ograničenja. [Modul 01](../01-introduction/README.md) **Lančano korištenje alata** - Sekvencijalno izvođenje alata gdje izlaz informira sljedeći poziv. [Modul 04](../04-tools/README.md) ## Komponente LangChain4j -**AiServices** - Stvara tip-sigurne sučelja AI usluga. +**AiServices** - Kreira tip-sigurne sučelje AI servisa. -**OpenAiOfficialChatModel** - Ujedinjeni klijent za OpenAI i Azure OpenAI modele. +**OpenAiOfficialChatModel** - Unificirani klijent za OpenAI i Azure OpenAI modele. -**OpenAiOfficialEmbeddingModel** - Stvara ugrađivanja pomoću službenog OpenAI klijenta (podržava i OpenAI i Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Kreira embeddings koristeći OpenAI Official klijent (podržava i OpenAI i Azure OpenAI). **ChatModel** - Osnovno sučelje za jezične modele. -**ChatMemory** - Čuva povijest razgovora. +**ChatMemory** - Održava povijest razgovora. **ContentRetriever** - Pronalazi relevantne dijelove dokumenata za RAG. -**DocumentSplitter** - Razbija dokumente na dijelove. +**DocumentSplitter** - Dijeli dokumente na dijelove. **EmbeddingModel** - Pretvara tekst u numeričke vektore. -**EmbeddingStore** - Pohranjuje i dohvaća ugrađivanja. +**EmbeddingStore** - Sprema i dohvaća embeddings. -**MessageWindowChatMemory** - Održava pomični prozor nedavnih poruka. +**MessageWindowChatMemory** - Održava klizni prozor s nedavnim porukama. -**PromptTemplate** - Stvara ponovno upotrebljive upite s oznakama `{{variable}}`. +**PromptTemplate** - Kreira ponovo iskoristive promptove s `{{promjenjiva}}` rezerviranim mjestima. -**TextSegment** - Tekstualni dio s metapodacima. Koristi se u RAG. +**TextSegment** - Tekstualni dio s metapodacima. Koristi se u RAG-u. -**ToolExecutionRequest** - Predstavlja zahtjev za izvršenje alata. +**ToolExecutionRequest** - Predstavlja zahtjev za izvođenje alata. -**UserMessage / AiMessage / SystemMessage** - Vrste poruka u razgovoru. +**UserMessage / AiMessage / SystemMessage** - Tipovi poruka u razgovoru. -## Pojmovi AI/ML +## Pojmovi iz AI/ML -**Few-Shot učenje** - Davanje primjera u upitima. [Modul 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Davanje primjera u promptovima. [Modul 02](../02-prompt-engineering/README.md) -**Veliki jezični model (LLM)** - AI modeli trenirani na ogromnim količinama tekstualnih podataka. +**Veliki jezični model (LLM)** - AI modeli trenirani na ogromnim tekstualnim podacima. -**Napori zaključivanja** - Parametar GPT-5.2 koji kontrolira dubinu razmišljanja. [Modul 02](../02-prompt-engineering/README.md) +**Poteškoća rezoniranja** - GPT-5.2 parametar koji kontrolira dubinu razmišljanja. [Modul 02](../02-prompt-engineering/README.md) -**Temperatura** - Kontrolira nasumičnost izlaza. Niska=deterministički, visoka=kreativni. +**Temperatura** - Kontrolira nasumičnost izlaza. Niska = deterministički, visoka = kreativno. -**Vektorska baza podataka** - Specijalizirana baza za ugrađivanja. [Modul 03](../03-rag/README.md) +**Vektorska baza podataka** - Specijalizirana baza za embeddings. [Modul 03](../03-rag/README.md) -**Zero-Shot učenje** - Izvođenje zadataka bez primjera. [Modul 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Izvođenje zadataka bez primjera. [Modul 02](../02-prompt-engineering/README.md) -## Sigurnosne mjere - [Modul 00](../00-quick-start/README.md) +## Zaštitne mjere -**Defense in Depth** - Višeslojni sigurnosni pristup koji kombinira sigurnosne mjere na razini aplikacije s provjerama pružatelja usluga. +**Defenziva u dubini** - Višeslojni sigurnosni pristup koji kombinira zaštitne mjere na razini aplikacije i sigurnosne filtre pružatelja. -**Hard Block** - Pružatelj vraća HTTP 400 grešku za ozbiljne povrede sadržaja. +**Hard Block** - Pružatelj daje HTTP 400 grešku za teška kršenja sadržaja. -**InputGuardrail** - Sučelje LangChain4j za provjeru korisničkog unosa prije nego što dođe do LLM-a. Štedi troškove i kašnjenje blokiranjem štetnih upita rano. +**InputGuardrail** - LangChain4j sučelje za validaciju korisničkog unosa prije nego dođe do LLM-a. Štedi troškove i latenciju blokirajući štetne unose na početku. -**InputGuardrailResult** - Povratni tip za validaciju čuvara: `success()` ili `fatal("razlog")`. +**InputGuardrailResult** - Povratni tip za validaciju pravilnika: `success()` ili `fatal("razlog")`. -**OutputGuardrail** - Sučelje za provjeru AI odgovora prije vraćanja korisnicima. +**OutputGuardrail** - Sučelje za validaciju AI odgovora prije vraćanja korisnicima. -**Provider Safety Filters** - Ugrađeni filtri sadržaja pružatelja AI usluga (npr. GitHub Models) koji hvataju povrede na razini API-ja. +**Provider Safety Filters** - Ug built-in filtri sadržaja od AI pružatelja usluga (npr. Azure OpenAI) koji sprečavaju kršenja na razini API-ja. -**Soft Refusal** - Model pristojno odbija odgovoriti bez bacanja greške. +**Soft Refusal** - Model uljudno odbija odgovoriti bez bacanja greške. -## Inženjerstvo upita - [Modul 02](../02-prompt-engineering/README.md) +## Inženjering promptova - [Modul 02](../02-prompt-engineering/README.md) -**Lanac razmišljanja** - Zaključenje korak po korak za veću preciznost. +**Lanac razmišljanja (Chain-of-Thought)** - Korak-po-korak razmišljanje za bolju točnost. **Ograničeni izlaz** - Nametanje određenog formata ili strukture. -**Visoka želja za odgovorom** - Uzorak GPT-5.2 za temeljito zaključivanje. +**Visoka motivacija** - GPT-5.2 obrazac za temeljito rezoniranje. -**Niska želja za odgovorom** - Uzorak GPT-5.2 za brze odgovore. +**Niska motivacija** - GPT-5.2 obrazac za brze odgovore. -**Višekratni razgovor** - Održavanje konteksta kroz razmjenu poruka. +**Višekratni dijalog** - Održavanje konteksta kroz razmjene. -**Uloge u upitu** - Postavljanje modela kroz sistemske poruke. +**Prompt po ulozi** - Postavljanje modela na određenu osobu putem sistemskih poruka. -**Samosvijest** - Model procjenjuje i poboljšava svoj izlaz. +**Samo-refleksija** - Model evaluira i poboljšava vlastiti izlaz. **Strukturirana analiza** - Fiksni okvir za evaluaciju. -**Uzorkovanje izvršenja zadatka** - Planiraj → Izvrši → Sažmi. +**Obrazac izvršavanja zadataka** - Planirati → Izvršiti → Sažeti. -## RAG (Generiranje uz pomoć dohvaćanja) - [Modul 03](../03-rag/README.md) +## RAG (Retrieval-Augmented Generation) - [Modul 03](../03-rag/README.md) -**Cjevovod obrade dokumenata** - Učitavanje → dijeljenje → ugrađivanje → pohrana. +**Procesiranje dokumenata** - Učitavanje → dijeljenje → ugrađivanje → pohrana. -**Pohrana ugrađivanja u memoriji** - Nepostojana pohrana za testiranje. +**Ugrađivanje u memoriji** - Nepostojana pohrana za testiranje. -**RAG** - Kombinira dohvaćanje i generiranje za utemeljenje odgovora. +**RAG** - Kombinira dohvaćanje podataka s generiranjem za utemeljene odgovore. **Ocjena sličnosti** - Mjera (0-1) semantičke sličnosti. -**Izvorni referent** - Metapodaci o dohvaćenom sadržaju. +**Referenca izvora** - Metapodaci o dohvaćenom sadržaju. ## Agent i alati - [Modul 04](../04-tools/README.md) -**@Tool anotacija** - Označava Java metode kao AI-pozive alata. +**@Tool oznaka** - Označava Java metode kao alate dostupne za AI pozive. -**ReAct uzorak** - Razmišljaj → Djeluj → Promatraj → Ponavljaj. +**ReAct obrazac** - Razmišljaj → Djeluj → Promatraj → Ponavljaj. -**Upravljanje sesijom** - Odvojeni konteksti za različite korisnike. +**Upravljanje sesijama** - Odvojeni konteksti za različite korisnike. **Alat** - Funkcija koju AI agent može pozvati. @@ -148,85 +148,83 @@ Brzi pregled termina i pojmova korištenih tijekom tečaja. ## Agentni modul - [Modul 05](../05-mcp/README.md) -**@Agent anotacija** - Označava sučelja kao AI agente s deklarativnim definiranje ponašanja. +**@Agent oznaka** - Označava sučelja kao AI agente s deklarativnim definiranjem ponašanja. -**Agentni slušatelj** - Kukica za praćenje izvršenja agenta preko `beforeAgentInvocation()` i `afterAgentInvocation()`. +**Agent Listener** - Kuka za praćenje izvođenja agenta putem `beforeAgentInvocation()` i `afterAgentInvocation()`. -**Agentni opseg** - Zajednička memorija gdje agenti pohranjuju rezultate koristeći `outputKey` za korištenje od strane drugih agenata. +**Agentni opseg (Agentic Scope)** - Dijeljena memorija u koju agenti pohranjuju rezultate koristeći `outputKey` za konzumaciju od strane drugih agenata. -**AgenticServices** - Tvornica za kreiranje agenata s `agentBuilder()` i `supervisorBuilder()`. +**AgenticServices** - Tvornica za kreiranje agenata koristeći `agentBuilder()` i `supervisorBuilder()`. -**Uvjetni tok rada** - Usmjeravanje prema uvjetima različitim specijalističkim agentima. +**Uvjetni tijek rada** - Usmjeravanje prema uvjetima različitim specijaliziranim agentima. -**Ljudski u petlji** - Uzorak toka rada koji dodaje ljudsku kontrolu za odobrenje ili pregled sadržaja. +**Human-in-the-Loop** - Obrazac tijeka rada koji uključuje ljudske točke odobravanja ili pregleda sadržaja. -**langchain4j-agentic** - Maven ovisnost za deklarativnu izgradnju agenata (eksperimentalno). +**langchain4j-agentic** - Maven ovisnost za deklarativno građenje agenata (eksperimentalno). -**Petlja toka rada** - Ponavljanje izvršenja agenta dok se ne zadovolji uvjet (npr. ocjena kvalitete ≥ 0.8). +**Petlja u tijeku rada** - Iteracija izvođenja agenta dok se ne ispuni uvjet (npr. ocjena kvalitete ≥ 0.8). -**outputKey** - Parametar anotacije agenta koji specificira gdje se rezultati pohranjuju u Agentni opseg. +**outputKey** - Parametar oznake agenta koji specificira gdje se rezultati spremaju u Agentni opseg. -**Paralelni tok rada** - Istovremeno pokretanje više agenata za neovisne zadatke. +**Paralelni tijek rada** - Istovremeno pokretanje više agenata za nezavisne zadatke. **Strategija odgovora** - Kako nadzornik formulira konačni odgovor: LAST, SUMMARY ili SCORED. -**Sekvencijalni tok rada** - Izvršavanje agenata po redu gdje izlaz teče u sljedeći korak. +**Sekvencijalni tijek rada** - Izvršavanje agenata redom gdje izlaz teče u sljedeći korak. -**Uzorak nadzornog agenta** - Napredni agentni uzorak gdje nadzorni LLM dinamički odlučuje koje pod-agente pozvati. +**Obrazac nadzornog agenta** - Napredni agentni obrazac gdje nadzorni LLM dinamički odlučuje koje pod-agente pozvati. ## Protokol konteksta modela (MCP) - [Modul 05](../05-mcp/README.md) -**langchain4j-mcp** - Maven ovisnost za MCP integraciju u LangChain4j. +**langchain4j-mcp** - Maven ovisnost za integraciju MCP-a u LangChain4j. -**MCP** - Protokol konteksta modela: standard za povezivanje AI aplikacija s vanjskim alatima. Izradi jednom, koristi svugdje. +**MCP** - Model Context Protocol: standard za povezivanje AI aplikacija s vanjskim alatima. Izradi jednom, koristi svugdje. -**MCP klijent** - Aplikacija koja se povezuje s MCP serverima za otkrivanje i korištenje alata. +**MCP klijent** - Aplikacija koja se povezuje na MCP servere radi otkrivanja i korištenja alata. -**MCP server** - Usluga koja izlaže alate preko MCP s jasnim opisima i šemama parametara. +**MCP server** - Usluga koja izlaže alate putem MCP-a s jasnim opisima i shemama parametara. -**McpToolProvider** - Komponenta LangChain4j koja omotava MCP alate za korištenje u AI uslugama i agentima. +**McpToolProvider** - Komponenta LangChain4j koja umotava MCP alate za korištenje u AI servisima i agentima. **McpTransport** - Sučelje za MCP komunikaciju. Implementacije uključuju Stdio i HTTP. -**Stdio transport** - Transport lokalnog procesa preko stdin/stdout. Korisno za pristup datotečnom sustavu ili komandnoj liniji. +**Stdio transport** - Lokalni procesni transport putem stdin/stdout. Koristan za pristup datotečnom sustavu ili CLI alate. -**StdioMcpTransport** - Implementacija LangChain4j koja pokreće MCP server kao podproces. +**StdioMcpTransport** - LangChain4j implementacija koja pokreće MCP server kao podproces. -**Otkriće alata** - Klijent pita server za dostupne alate s opisima i šemama. +**Otkrivanje alata** - Klijent upituje server za dostupne alate s opisima i shemama. ## Azure usluge - [Modul 01](../01-introduction/README.md) -**Azure AI Search** - Oblak pretraživanja s vektorskim mogućnostima. [Modul 03](../03-rag/README.md) +**Azure AI Search** - Cloud pretraživanje s vektorskim mogućnostima. [Modul 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Deploy Azure resursa. +**Azure Developer CLI (azd)** - Alat za deploy Azure resursa. -**Azure OpenAI** - Microsoftova AI servisna platforma za poduzeća. +**Azure OpenAI** - Microsoftova enterprise AI usluga. -**Bicep** - Azure jezik za infrastrukturu kao kod. [Vodič za infrastrukturu](../01-introduction/infra/README.md) +**Bicep** - Jezik za infrastrukturu kao kod u Azure-u. [Vodič za infrastrukturu](../01-introduction/infra/README.md) -**Naziv implementacije** - Ime za implementaciju modela u Azureu. +**Ime deploymenta** - Naziv za postavljanje modela u Azure. -**GPT-5.2** - Najnoviji OpenAI model s kontrolom zaključivanja. [Modul 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Najnoviji OpenAI model s kontrolom rezoniranja. [Modul 02](../02-prompt-engineering/README.md) ## Testiranje i razvoj - [Vodič za testiranje](TESTING.md) **Dev Container** - Kontejnerizirano razvojno okruženje. [Konfiguracija](../../../.devcontainer/devcontainer.json) -**GitHub modeli** - Besplatno AI igralište za modele. [Modul 00](../00-quick-start/README.md) - **Testiranje u memoriji** - Testiranje s pohranom u memoriji. **Integracijsko testiranje** - Testiranje s pravom infrastrukturom. **Maven** - Alat za automatizaciju gradnje za Javu. -**Mockito** - Java okvir za izradu imitacija (mock). +**Mockito** - Java framework za izradu lažnih objekata. -**Spring Boot** - Java aplikacijski okvir. [Modul 01](../01-introduction/README.md) +**Spring Boot** - Java aplikacijski framework. [Modul 01](../01-introduction/README.md) --- -**Izjava o odricanju odgovornosti**: -Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa [Co-op Translator](https://github.com/Azure/co-op-translator). Iako nastojimo biti točni, imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati službenim i autoritativnim izvorom. Za ključne informacije preporučuje se profesionalni ljudski prijevod. Ne snosimo odgovornost za bilo kakve nesporazume ili kriva tumačenja koja proizlaze iz korištenja ovog prijevoda. +**Napomena**: +Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporuča se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešne interpretacije koje proizlaze iz korištenja ovog prijevoda. \ No newline at end of file diff --git a/translations/hr/docs/TESTING.md b/translations/hr/docs/TESTING.md index d6d4cb2d4..1812a31d9 100644 --- a/translations/hr/docs/TESTING.md +++ b/translations/hr/docs/TESTING.md @@ -2,19 +2,19 @@ ## Sadržaj -- [Brzi početak](../../../docs) -- [Što testovi pokrivaju](../../../docs) -- [Pokretanje testova](../../../docs) -- [Pokretanje testova u VS Code](../../../docs) -- [Obrasci testiranja](../../../docs) -- [Filozofija testiranja](../../../docs) -- [Daljnji koraci](../../../docs) +- [Brzi početak](#brzi-početak) +- [Što testovi pokrivaju](#što-testovi-pokrivaju) +- [Pokretanje testova](#pokretanje-testova) +- [Pokretanje testova u VS Codeu](#pokretanje-testova-u-vs-codeu) +- [Obrasci testiranja](#obrasci-testiranja) +- [Filozofija testiranja](#filozofija-testiranja) +- [Sljedeći koraci](#sljedeći-koraci) -Ovaj vodič vodi vas kroz testove koji pokazuju kako testirati AI aplikacije bez potrebe za API ključevima ili vanjskim servisima. +Ovaj vodič vodi vas kroz testove koji pokazuju kako testirati AI aplikacije bez potrebe za API ključevima ili vanjskim uslugama. ## Brzi početak -Pokrenite sve testove s jednom naredbom: +Pokrenite sve testove jednom naredbom: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Kada svi testovi prođu, trebali biste vidjeti izlaz poput donje snimke zaslona — testovi se izvršavaju bez grešaka. +Kada svi testovi prođu, trebali biste vidjeti izlaz poput zaslonske snimke ispod — testovi su pokrenuti bez pogrešaka. -Uspješni rezultati testiranja +Uspješni rezultati testova -*Uspješno izvršavanje testova koje pokazuje da svi testovi prolaze bez grešaka* +*Uspješno izvršavanje testova koje pokazuje da svi testovi prolaze bez pogrešaka* ## Što testovi pokrivaju -Ovaj tečaj se fokusira na **jedinične testove** koji se izvode lokalno. Svaki test prikazuje određeni LangChain4j koncept u izolaciji. Testna piramida ispod prikazuje gdje se jedinični testovi uklapaju — oni čine brzu, pouzdanu osnovu na kojoj se gradi ostatak vaše test strategije. +Ovaj tečaj fokusira se na **jedinične testove** koji se izvode lokalno. Svaki test prikazuje specifičan LangChain4j koncept u izolaciji. Prikazana je piramida testiranja koja pokazuje gdje se uklapaju jedinični testovi — oni čine brzu, pouzdanu osnovu na kojoj se gradi ostatak vaše test strategije. -Testna piramida +Piramida testiranja -*Testna piramida koja prikazuje ravnotežu između jediničnih testova (brzi, izolirani), integracijskih testova (stvarne komponente) i end-to-end testova. Ova obuka pokriva jedinično testiranje.* +*Piramida testiranja koja pokazuje ravnotežu između jediničnih testova (brzi, izolirani), integracijskih testova (stvarne komponente) i end-to-end testova. Ova obuka pokriva jedinično testiranje.* -| Modul | Testovi | Fokus | Ključne datoteke | -|--------|-------|-------|-----------| -| **00 - Brzi početak** | 6 | Predlošci promptova i zamjena varijabli | `SimpleQuickStartTest.java` | -| **01 - Uvod** | 8 | Memorija razgovora i chat s održavanjem stanja | `SimpleConversationTest.java` | -| **02 - Inženjering promptova** | 12 | GPT-5.2 obrasci, razine spremnosti, strukturirani izlaz | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Unos dokumenata, ugradnje, pretraživanje sličnosti | `DocumentServiceTest.java` | -| **04 - Alati** | 12 | Pozivanje funkcija i povezivanje alata | `SimpleToolsTest.java` | +| Modul | Testovi | Fokus | Ključne Datoteke | +|--------|---------|-------|------------------| +| **01 - Uvod** | 8 | Memorija razgovora i stanje chat-a | `SimpleConversationTest.java` | +| **02 - Izrada prompta** | 12 | GPT-5.2 obrasci, razine spremnosti, strukturirani izlaz | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Učitavanje dokumenata, embeddings, pretraživanje sličnosti | `DocumentServiceTest.java` | +| **04 - Alati** | 12 | Pozivanje funkcija i lančanje alata | `SimpleToolsTest.java` | | **05 - MCP** | 8 | Model Context Protocol sa stdio transportom | `SimpleMcpTest.java` | ## Pokretanje testova -**Pokreni sve testove iz korijena:** +**Pokrenite sve testove iz korijena:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Pokreni testove za određeni modul:** +**Pokrenite testove za određeni modul:** **Bash:** ```bash @@ -75,11 +74,11 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Ili iz root-a +# Ili iz korijena mvn --% test -pl 01-introduction ``` -**Pokreni jednu test klasu:** +**Pokrenite jednu test klasu:** **Bash:** ```bash @@ -91,7 +90,7 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Pokreni određenu test metodu:** +**Pokrenite specifičnu test metodu:** **Bash:** ```bash @@ -103,33 +102,33 @@ mvn test -Dtest=SimpleConversationTest#trebaOdržavatiPovijestRazgovora mvn --% test -Dtest=SimpleConversationTest#trebaOdržavatiPovijestRazgovora ``` -## Pokretanje testova u VS Code +## Pokretanje testova u VS Codeu -Ako koristite Visual Studio Code, Test Explorer pruža grafičko sučelje za pokretanje i otklanjanje pogrešaka u testovima. +Ako koristite Visual Studio Code, Test Explorer pruža grafičko sučelje za pokretanje i ispravljanje testova. VS Code Test Explorer -*VS Code Test Explorer prikazuje stablo testova sa svim Java test klasama i pojedinačnim test metodama* +*VS Code Test Explorer koji prikazuje test stablo sa svim Java test klasama i pojedinačnim test metodama* -**Za pokretanje testova u VS Code:** +**Za pokretanje testova u VS Codeu:** -1. Otvorite Test Explorer klikom na ikonu epruvete u Activity Bar-u +1. Otvorite Test Explorer klikom na ikonu epruvete u trakci aktivnosti 2. Proširite stablo testova da vidite sve module i test klase -3. Kliknite gumb za reprodukciju pored bilo kojeg testa za pojedinačno pokretanje -4. Kliknite "Run All Tests" za pokretanje cijelog skupa -5. Desni klik na bilo koji test i odaberite "Debug Test" za postavljanje breakpoints i korak po korak praćenje koda +3. Kliknite gumb za pokretanje pokraj bilo kojeg testa da ga pojedinačno pokrenete +4. Kliknite "Run All Tests" za izvršenje cijelog skupa +5. Desni klik na bilo koji test i odaberite "Debug Test" za postavljanje točaka prekida i korak po korak praćenje koda -Test Explorer prikazuje zelene kvačice za prolazne testove i pruža detaljne poruke o greškama kada testovi zakažu. +Test Explorer prikazuje zelene kvačice za prolazne testove i pruža detaljne poruke o pogreškama kada testovi ne prođu. ## Obrasci testiranja -### Obrasc 1: Testiranje predložaka promptova +### Obrazac 1: Testiranje prompt predložaka -Najjednostavniji obrazac testira predloške promptova bez poziva bilo kojeg AI modela. Provjeravate da li zamjena varijabli radi ispravno i da su promptovi formatirani kako se očekuje. +Najjednostavniji obrazac testira prompt predloške bez pozivanja ikakvog AI modela. Provjeravate da li zamjena varijabli radi ispravno i da su promptovi formatirani kako se očekuje. -Testiranje predložaka promptova +Testiranje prompt predložaka -*Testiranje predložaka promptova koje pokazuje tijek zamjene varijabli: predložak s rezerviranim mjestima → primjenjene vrijednosti → provjera formatiranog izlaza* +*Testiranje prompt predložaka koje prikazuje tijek zamjene varijabli: predložak s rezerviranim mjestima → primijenjene vrijednosti → potvrđeni formatirani izlaz* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Ovaj test se nalazi u `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Pokrenite ga:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testirajFormatiranjePredloškaUpita -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testiranjeFormatiranjaPredloškaUpita -``` +Ovaj obrazac potvrđuje da zamjena varijabli radi ispravno i da su promptovi formatirani kako se očekuje — nije potreban API ključ niti poziv modela. -### Obrasc 2: Mockiranje jezičnih modela +### Obrazac 2: Mockiranje jezičnih modela -Pri testiranju logike razgovora, koristite Mockito za stvaranje lažnih modela koji vraćaju unaprijed određene odgovore. Time testovi postaju brzi, besplatni i deterministički. +Prilikom testiranja logike razgovora, koristite Mockito za stvaranje lažnih modela koji vraćaju unaprijed određene odgovore. Ovo čini testove brzim, besplatnim i determinističkim. Usporedba lažnog i stvarnog API-ja -*Usporedba koja pokazuje zašto su mockovi preferirani za testiranje: brzi, besplatni, deterministički i ne zahtijevaju API ključeve* +*Usporedba koja pokazuje zašto su mockovi poželjniji za testiranje: brzi su, besplatni, deterministički i ne zahtijevaju API ključeve* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Ovaj obrazac se pojavljuje u `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock osigurava dosljedno ponašanje kako biste mogli provjeriti ispravno upravljanje memorijom. +Ovaj obrazac nalazi se u `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock jamči dosljedno ponašanje kako bi se moglo potvrditi da upravljanje memorijom radi ispravno. -### Obrasc 3: Testiranje izolacije razgovora +### Obrazac 3: Testiranje izolacije razgovora -Memorija razgovora mora držati korisnike odvojene. Ovaj test provjerava da se konteksti ne miješaju u razgovorima. +Memorija razgovora mora držati različite korisnike odvojeno. Ovaj test potvrđuje da se razgovori ne miješaju. Izolacija razgovora -*Testiranje izolacije razgovora prikazuje odvojene memorijske jedinice za različite korisnike kako bi se spriječilo miješanje konteksta* +*Testiranje izolacije razgovora koje prikazuje odvojene memorijske pohrane za različite korisnike kako bi se spriječilo miješanje konteksta* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Svaki razgovor održava vlastitu neovisnu povijest. U produkcijskim sustavima ova izolacija je ključna za aplikacije s više korisnika. +Svaki razgovor održava vlastitu neovisnu povijest. U produkcijskim sustavima ova izolacija je ključna za multi-korisničke aplikacije. -### Obrasc 4: Testiranje alata neovisno +### Obrazac 4: Testiranje alata neovisno -Alati su funkcije koje AI može pozvati. Testirajte ih izravno kako biste osigurali da rade ispravno neovisno o AI odlukama. +Alati su funkcije koje AI može pozivati. Testirajte ih izravno kako biste osigurali da rade ispravno bez obzira na AI odluke. Testiranje alata -*Testiranje alata neovisno prikazuje izvođenje mock alata bez poziva AI-ja radi provjere logike poslovanja* +*Testiranje alata neovisno koje prikazuje izvršavanje mock alata bez AI poziva za potvrdu poslovne logike* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Ovi testovi iz `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` potvrđuju logiku alata bez uključenja AI-ja. Primjer povezivanja pokazuje kako izlaz jednog alata ulazi u drugi. +Ovi testovi iz `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validiraju logiku alata bez sudjelovanja AI-ja. Primjer lančanja pokazuje kako izlaz jednog alata ulazi u ulaz drugog. -### Obrasc 5: Testiranje RAG-a u memoriji +### Obrazac 5: Testiranje RAG u memoriji -RAG sustavi tradicionalno zahtijevaju vektorske baze podataka i servise za ugradnje. Uz obrazac u memoriji možete testirati cijeli proces bez vanjskih ovisnosti. +RAG sustavi tradicionalno zahtijevaju vektorske baze podataka i usluge za embeddings. Obrazac u memoriji omogućuje testiranje cijelog procesa bez vanjskih ovisnosti. -Testiranje RAG-a u memoriji +Testiranje RAG u memoriji -*Radni proces testiranja RAG-a u memoriji prikazuje parsiranje dokumenata, pohranu ugradnji i pretraživanje sličnosti bez potrebe za bazom podataka* +*Radni tijek testiranja RAG u memoriji koji prikazuje parsiranje dokumenata, pohranu embeddings i pretraživanje sličnosti bez baze podataka* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Ovaj test iz `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` stvara dokument u memoriji i provjerava segmentaciju i rukovanje metapodacima. +Ovaj test iz `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` stvara dokument u memoriji i provjerava dijeljenje i rukovanje metapodacima. -### Obrasc 6: Integracijsko testiranje MCP-a +### Obrazac 6: MCP integracijsko testiranje -MCP modul testira integraciju Model Context Protocola koristeći stdio transport. Ovi testovi potvrđuju da vaša aplikacija može pokretati i komunicirati s MCP serverima kao podprocesima. +MCP modul testira Model Context Protocol integraciju koristeći stdio transport. Ovi testovi potvrđuju da vaša aplikacija može pokretati i komunicirati s MCP serverima kao podprocesima. -Testovi u `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` potvrđuju ponašanje MCP klijenta. +Testovi u `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validiraju ponašanje MCP klijenta. **Pokrenite ih:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Filozofija testiranja -Testirajte svoj kod, ne AI. Vaši bi testovi trebali potvrditi kod koji pišete tako što provjeravaju kako se konstruiraju promptovi, kako se upravlja memorijom i kako se izvršavaju alati. Odgovori AI-ja variraju i ne bi trebali biti dio testnih tvrdnji. Pitajte se je li vaš predložak prompta ispravno zamijenio varijable, a ne daje li AI pravi odgovor. +Testirajte svoj kod, ne AI. Vaši testovi trebaju potvrditi kod koji pišete provjeravajući kako se promptovi konstruiraju, kako se upravlja memorijom i kako alati izvršavaju. AI odgovori variraju i ne bi trebali biti dio testnih tvrdnji. Pitajte se je li vaš prompt predložak ispravno zamijenio varijable, a ne daje li AI točan odgovor. -Koristite mockove za jezične modele. Oni su vanjske ovisnosti koje su spore, skupe i nedeterminističke. Mockiranje čini testove brzim, sa stotinama milisekundi umjesto sekundi, besplatnim bez troškova API-ja i determinističkim s istim rezultatom svaki put. +Koristite mockove za jezične modele. Oni su vanjske ovisnosti koje su spore, skupe i nedeterminističke. Mockiranje testove čini brzim s milisekundama umjesto sekundi, besplatnim bez troškova API-ja i determinističkim s istim rezultatom svaki put. -Držite testove neovisnima. Svaki test bi trebao sam postaviti svoje podatke, ne oslanjati se na druge testove i čisto ih očistiti. Testovi bi trebali prolaziti bez obzira na redoslijed izvršavanja. +Održavajte testove neovisnima. Svaki test treba postaviti svoje podatke, ne oslanjati se na druge testove i očistiti nakon sebe. Testovi bi trebali prolaziti bez obzira na redoslijed izvođenja. -Testirajte rubne slučajeve osim ugodnog toka. Isprobajte prazne ulaze, vrlo velike ulaze, posebne znakove, nevaljane parametre i granične uvjete. Oni često otkrivaju greške koje normalna upotreba ne pokazuje. +Testirajte rubne slučajeve izvan sretnog puta. Isprobajte prazne ulaze, vrlo velike ulaze, posebne znakove, nevažeće parametre i granične uvjete. Oni često otkrivaju pogreške koje normalna upotreba ne pokazuje. -Koristite deskriptivne nazive. Usporedite `shouldMaintainConversationHistoryAcrossMultipleMessages()` s `test1()`. Prvi vam točno govori što se testira, što olakšava otklanjanje pogrešaka. +Koristite opisna imena. Usporedite `shouldMaintainConversationHistoryAcrossMultipleMessages()` sa `test1()`. Prvo vam točno govori što se testira, što olakšava otklanjanje pogrešaka. -## Daljnji koraci +## Sljedeći koraci -Sada kada razumijete obrasce testiranja, dublje zaronite u svaki modul: +Sada kada razumijete obrasce testiranja, detaljnije se upoznajte sa svakim modulom: -- **[00 - Brzi početak](../00-quick-start/README.md)** - Počnite s osnovama predložaka promptova - **[01 - Uvod](../01-introduction/README.md)** - Naučite upravljanje memorijom razgovora -- **[02 - Inženjering promptova](../02/prompt-engineering/README.md)** - Ovladavanje GPT-5.2 obrascima promptova -- **[03 - RAG](../03-rag/README.md)** - Izgradite sustave za generiranje uz pojačanu pretraživost -- **[04 - Alati](../04-tools/README.md)** - Implementirajte pozivanje funkcija i lančane alate +- **[02 - Izrada prompta](../02/prompt-engineering/README.md)** - Savladajte obrasce promptiranja GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Izgradite sustave za generiranje potpomognuto pretraživanjem +- **[04 - Alati](../04-tools/README.md)** - Implementirajte pozivanje funkcija i lančanje alata - **[05 - MCP](../05-mcp/README.md)** - Integrirajte Model Context Protocol -README svakog modula pruža detaljna objašnjenja koncepata prikazanih ovdje. +README svakog modula pruža detaljna objašnjenja pojmova testiranih ovdje. --- -**Navigacija:** [← Povratak na glavni](../README.md) +**Navigacija:** [← Natrag na početnu](../README.md) --- -**Izjava o odricanju od odgovornosti**: -Ovaj dokument preveo je AI servis za prevođenje [Co-op Translator](https://github.com/Azure/co-op-translator). Iako nastojimo osigurati točnost, imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na izvornom jeziku treba se smatrati službenim i autoritativnim izvorom. Za kritične informacije preporučujemo profesionalni ljudski prijevod. Ne snosimo odgovornost za bilo kakva nesporazuma ili pogrešna tumačenja koja proizlaze iz upotrebe ovog prijevoda. +**Napomena**: +Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporuča se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešne interpretacije koje proizlaze iz korištenja ovog prijevoda. \ No newline at end of file diff --git a/translations/hu/.co-op-translator.json b/translations/hu/.co-op-translator.json index 11bc06f1b..4b3e549b9 100644 --- a/translations/hu/.co-op-translator.json +++ b/translations/hu/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "hu" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T02:42:33+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T08:53:38+00:00", "source_file": "01-introduction/README.md", "language_code": "hu" }, @@ -18,20 +18,20 @@ "language_code": "hu" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T02:45:44+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T08:49:17+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "hu" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T02:47:43+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T08:52:45+00:00", "source_file": "03-rag/README.md", "language_code": "hu" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:13:06+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T08:51:29+00:00", "source_file": "04-tools/README.md", "language_code": "hu" }, @@ -54,8 +54,8 @@ "language_code": "hu" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:51:39+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T08:47:49+00:00", "source_file": "README.md", "language_code": "hu" }, @@ -72,14 +72,14 @@ "language_code": "hu" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T02:54:06+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T08:49:44+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "hu" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T02:55:03+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T08:50:19+00:00", "source_file": "docs/TESTING.md", "language_code": "hu" } diff --git a/translations/hu/00-quick-start/README.md b/translations/hu/00-quick-start/README.md deleted file mode 100644 index 4590cda62..000000000 --- a/translations/hu/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modul 00: Gyors áttekintés - -## Tartalomjegyzék - -- [Bevezető](../../../00-quick-start) -- [Mi az a LangChain4j?](../../../00-quick-start) -- [LangChain4j Függőségek](../../../00-quick-start) -- [Előfeltételek](../../../00-quick-start) -- [Beállítás](../../../00-quick-start) - - [1. Szerezd meg a GitHub tokenedet](../../../00-quick-start) - - [2. Állítsd be a tokenedet](../../../00-quick-start) -- [Futtasd a példákat](../../../00-quick-start) - - [1. Alap chat](../../../00-quick-start) - - [2. Prompt minták](../../../00-quick-start) - - [3. Függvényhívás](../../../00-quick-start) - - [4. Dokumentum kérdések és válaszok (Easy RAG)](../../../00-quick-start) - - [5. Felelős MI](../../../00-quick-start) -- [Mit mutat be az egyes példa](../../../00-quick-start) -- [Következő lépések](../../../00-quick-start) -- [Hibaelhárítás](../../../00-quick-start) - -## Bevezető - -Ez a gyors indítás célja, hogy minél gyorsabban elindulj a LangChain4j használatával. Megismerteti az AI alkalmazások LangChain4j-vel és GitHub modellekkel történő alapvető építését. A következő modulokban Azure OpenAI és GPT-5.2-re váltasz, és mélyebben belemerülsz az egyes fogalmakba. - -## Mi az a LangChain4j? - -A LangChain4j egy Java könyvtár, amely leegyszerűsíti az MI-vezérelt alkalmazások készítését. HTTP kliensek és JSON feldolgozás helyett tiszta Java API-kkal dolgozol. - -A LangChain "lánc" arra utal, hogy több komponens láncolódik össze – például összekapcsolhatsz egy promptot egy modellel és egy elemzővel, vagy több MI hívás láncolódik, ahol az egyik kimenet a következő bemenete. Ez a gyorsstart az alapokra fókuszál, mielőtt bonyolultabb láncok felé lépne. - -LangChain4j Chaining Concept - -*Komponensek láncolása LangChain4j-ben – építőkövek kapcsolódnak, hogy erős MI munkafolyamatokat hozzanak létre* - -Három alapvető komponenst használunk: - -**ChatModel** - Az MI modellel való interakciók felülete. Meghívod: `model.chat("prompt")` és kapsz válaszstringet. Az `OpenAiOfficialChatModel`-t használjuk, amely kompatibilis OpenAI végpontokkal, például GitHub modellekkel. - -**AiServices** - Típusbiztos MI szolgáltatási interfészek létrehozása. Metódusokat definiálsz, `@Tool` annotációval látod el őket, és a LangChain4j kezeli az összehangolást. Az MI automatikusan hívja Java metódusaidat, ha szükséges. - -**MessageWindowChatMemory** - A beszélgetés előzményeit tárolja. Enélkül minden kérés független. Ezzel az MI megjegyzi a korábbi üzeneteket és megőrzi a kontextust több fordulón át. - -LangChain4j Architecture - -*LangChain4j architektúra – alapvető komponensek, amelyek együtt működnek az MI alkalmazásaid hajtásához* - -## LangChain4j Függőségek - -Ez a gyorsindítás három Maven függőséget használ a [`pom.xml`](../../../00-quick-start/pom.xml) fájlban: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -A `langchain4j-open-ai-official` modul biztosítja az `OpenAiOfficialChatModel` osztályt, amely OpenAI-kompatibilis API-khoz kapcsolódik. A GitHub Modellek ugyanazt az API formátumot használják, ezért nincs szükség külön adapterre – csak állítsd be az alap URL-t `https://models.github.ai/inference`-re. - -A `langchain4j-easy-rag` modul automatikus dokumentumfelosztást, beágyazást és visszakeresést biztosít, így RAG alkalmazásokat építhetsz anélkül, hogy manuálisan konfigurálnád az egyes lépéseket. - -## Előfeltételek - -**Fejlesztői konténer használata?** Java és Maven már telepítve van. Csak a GitHub Személyes Hozzáférési Tokent kell beszerezned. - -**Helyi fejlesztés:** -- Java 21+, Maven 3.9+ -- GitHub Személyes Hozzáférési Token (utasítások lent) - -> **Megjegyzés:** Ez a modul a GitHub Modellek `gpt-4.1-nano` változatát használja. Ne módosítsd a modell nevét a kódban – ez a GitHub elérhető modelljeihez van konfigurálva. - -## Beállítás - -### 1. Szerezd meg a GitHub tokenedet - -1. Nyisd meg a [GitHub Beállítások → Személyes hozzáférési tokenek](https://github.com/settings/personal-access-tokens) oldalt -2. Kattints a „Generate new token” gombra -3. Adj meg egy leíró nevet (pl. „LangChain4j Demo”) -4. Állíts be lejárati időt (7 nap javasolt) -5. Az „Account permissions” alatt keresd meg a „Models” opciót, és állítsd „Read-only”-ra -6. Kattints a „Generate token” gombra -7. Másold ki és mentsd el a tokenedet – később nem fogod látni újra - -### 2. Állítsd be a tokenedet - -**1. lehetőség: VS Code használata (ajánlott)** - -Ha VS Code-ot használsz, add hozzá a tokened a projekt gyökérkönyvtárában lévő `.env` fájlhoz: - -Ha a `.env` fájl nem létezik, másold a `.env.example` fájlt `.env` néven, vagy hozz létre egy új `.env` fájlt a projekt gyökerében. - -**Példa `.env` fájl:** -```bash -# A /workspaces/LangChain4j-for-Beginners/.env fájlban -GITHUB_TOKEN=your_token_here -``` - -Ezután egyszerűen kattints jobb gombbal egy bemutató fájlra (pl. `BasicChatDemo.java`) a Felfedezőben és válaszd a **„Run Java”** opciót, vagy használd a „Run and Debug” panel indítási konfigurációit. - -**2. lehetőség: Terminál használata** - -Állítsd be a token környezeti változóként: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Futtasd a példákat - -**VS Code használatával:** Egyszerűen kattints jobb gombbal egy bemutató fájlra a Felfedezőben, és válaszd a **„Run Java”** lehetőséget, vagy a „Run and Debug” panel indítási konfigurációit használd (előtte természetesen adj hozzá egy tokent a `.env` fájlhoz). - -**Maven használatával:** Vagy a parancssorból futtathatod: - -### 1. Alap chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Prompt minták - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Mutatja a zero-shot, few-shot, chain-of-thought és szerepkör-alapú promptokat. - -### 3. Függvényhívás - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -Az MI automatikusan hívja a Java metódusaidat, amikor szükséges. - -### 4. Dokumentum kérdések és válaszok (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Kérdezz a dokumentumaidról az Easy RAG használatával, automatikus beágyazás és visszakeresés mellett. - -### 5. Felelős MI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Nézd meg, hogyan blokkolják az MI biztonsági szűrők a káros tartalmakat. - -## Mit mutat be az egyes példa - -**Alap chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Kezdj itt, hogy meglásd a LangChain4j legegyszerűbb használatát. Létrehozol egy `OpenAiOfficialChatModel`-t, küldesz egy promptot `.chat()`-pel, és kapsz választ. Ez megmutatja az alapokat: hogyan inicializálj modelleket egyedi végpontokkal és API kulcsokkal. Ha megérted ezt a mintát, minden más erre épül. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) fájlt és kérdezd: -> - „Hogyan válthatnék a GitHub Modellekről Azure OpenAI-ra ebben a kódban?” -> - „Milyen egyéb paramétereket állíthatok az OpenAiOfficialChatModel.builder()-ben?” -> - „Hogyan adhatok streaming válaszokat a teljes válaszra való várakozás helyett?” - -**Prompt mérnökség** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Most, hogy tudod, hogyan beszélj a modellel, nézzük meg, hogy mit mondasz neki. Ez a demó ugyanazt a modell beállítást használja, de öt különböző prompt mintát mutat be. Próbáld ki a zero-shot promptokat közvetlen utasításokra, few-shot promptokat példák alapján való tanulásra, chain-of-thought promptokat az érvelési lépések felfedésére, és szerepalapú promptokat kontextus beállítására. Láthatod, hogyan ad ugyanaz a modell drámaian különböző eredményeket az igény keretezése alapján. - -A demó továbbá bemutat prompt sablonokat, amelyek hatékony módszert nyújtanak újrafelhasználható promptok létrehozására változókkal. -Az alábbi példa egy promptot mutat be a LangChain4j `PromptTemplate` használatával változók kitöltésére. Az MI a megadott célállomás és tevékenység alapján válaszol. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) fájlt és kérdezd: -> - „Mi a különbség a zero-shot és a few-shot prompt között, és mikor melyiket érdemes használni?” -> - „Hogyan befolyásolja a hőmérséklet paraméter a modell válaszait?” -> - „Milyen technikákkal lehet megelőzni a prompt injekciós támadásokat éles környezetben?” -> - „Hogyan hozhatok létre újrafelhasználható PromptTemplate objektumokat gyakori mintákhoz?” - -**Eszköz integráció** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Itt lesz igazán erős a LangChain4j. `AiServices` használatával létrehozhatsz egy MI asszisztenst, amely hívja a Java metódusaidat. Csak annotáld a metódusokat `@Tool("leírás")`-ral és a LangChain4j elintézi a többit – az MI automatikusan dönti el, mikor használja az egyes eszközöket a felhasználói kérés alapján. Ez bemutatja a függvényhívást mint kulcsfontosságú technikát az MI vezérelt akciók építéséhez, nem csak kérdések megválaszolásához. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) fájlt és kérdezd: -> - „Hogyan működik az @Tool annotáció, és mit csinál vele a LangChain4j a háttérben?” -> - „Lehet-e az MI több eszközt egymás után hívni összetett problémák megoldására?” -> - „Mi történik, ha egy eszköz kivételt dob – hogyan kezeljem a hibákat?” -> - „Hogyan integrálnék egy valódi API-t a kalkulátor példa helyett?” - -**Dokumentum kérdések és válaszok (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Itt láthatod a RAG (retrieval-augmented generation, tudás-kiegészítő generálás) működését a LangChain4j „Easy RAG” megközelítésével. A dokumentumokat betöltik, automatikusan felosztják és beágyazzák egy memóriában tárolt adatbázisba, majd egy tartalom visszakereső szolgáltatás szolgálat releváns részeket az MInek a lekérdezés idején. Az MI a dokumentumaid alapján válaszol, nem az általa általánosan ismert tudásra támaszkodik. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) fájlt és kérdezd: -> - „Hogyan akadályozza meg a RAG az MI tévesztéseket a modell tanítási adataihoz képest?” -> - „Miben különbözik ez az egyszerű megközelítés egy egyedi RAG csővezetéktől?” -> - „Hogyan skáláznám ezt több dokumentumra vagy nagyobb tudásbázisokra?” - -**Felelős MI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Építs MI biztonságot több szintű védelemmel. Ez a demó két védelmi réteget mutat be, amelyek együtt működnek: - -**1. rész: LangChain4j bemeneti korlátok** – Megakadályozzák, hogy veszélyes promptok eljussanak a LLM-hez. Egyedi korlátokat hozhatsz létre, amelyek tiltott kulcsszavakat vagy mintákat ellenőriznek. Ezek a kódodban futnak, így gyorsak és ingyenesek. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**2. rész: Szolgáltató biztonsági szűrők** – A GitHub Modellek beépített szűrőket használnak, amelyek elkapják, amit a te korlátjaid esetleg nem. Látsz szigorú blokkokat (HTTP 400 hibákat) súlyos szabálysértéseknél, valamint finomabb visszautasításokat, amikor az MI udvariasan elutasít. - -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) fájlt és kérdezd: -> - „Mi az InputGuardrail és hogyan készíthetem el a sajátomat?” -> - „Mi a különbség a szigorú blokkolás és a finom elutasítás között?” -> - „Miért használjuk együtt a korlátokat és a szolgáltató szűrőket?” - -## Következő lépések - -**Következő modul:** [01-bevezető - Kezdés a LangChain4j-vel](../01-introduction/README.md) - ---- - -**Navigáció:** [← Vissza a főoldalra](../README.md) | [Következő: Modul 01 - Bevezető →](../01-introduction/README.md) - ---- - -## Hibaelhárítás - -### Első Maven build - -**Probléma:** Az első `mvn clean compile` vagy `mvn package` futtatás sokáig tart (10-15 perc) - -**Ok:** A Mavennek meg kell töltenie az összes projektfüggőséget (Spring Boot, LangChain4j könyvtárak, Azure SDK-k stb.) az első build során. - -**Megoldás:** Ez normális viselkedés. A további build-ek sokkal gyorsabbak lesznek, mert a függőségek lokálisan cache-lődnek. A letöltési idő a hálózati sebességtől függ. - -### PowerShell Maven parancs szintaxis hiba - -**Probléma:** A Maven parancsok hibára futnak `Unknown lifecycle phase ".mainClass=..."` üzenettel -**Ok**: A PowerShell az `=` jelet változóértékadásként értelmezi, ami megszakítja a Maven tulajdonság szintaxisát - -**Megoldás**: Használja a stop-parsing `--%` operátort a Maven parancs előtt: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -A `--%` operátor megmondja a PowerShell-nek, hogy az összes fennmaradó argumentumot szó szerint továbbítsa a Mavennek értelmezés nélkül. - -### Windows PowerShell Emoji megjelenítés - -**Probléma**: Az AI válaszok helyett szemét karakterek jelennek meg (pl. `????` vagy `â??`) PowerShell-ben az emojik helyett - -**Ok**: A PowerShell alapértelmezett kódolása nem támogatja az UTF-8 emojikat - -**Megoldás**: Futtassa ezt a parancsot Java alkalmazások futtatása előtt: -```cmd -chcp 65001 -``` - -Ez kényszeríti az UTF-8 kódolást a terminálban. Alternatív megoldásként használja a Windows Terminalt, amely jobb Unicode támogatással rendelkezik. - -### API hívások hibakeresése - -**Probléma**: Hitelesítési hibák, aránykorlátozások vagy váratlan válaszok az AI modelltől - -**Megoldás**: A példák tartalmazzák a `.logRequests(true)` és `.logResponses(true)` hívásokat, hogy az API hívások megjelenjenek a konzolon. Ez segít a hitelesítési hibák, aránykorlátozások vagy váratlan válaszok hibakeresésében. Ezeket a zászlókat távolítsa el az éles környezetben a naplózási zaj csökkentése érdekében. - ---- - - -**Jogi Nyilatkozat**: -Ez a dokumentum az AI fordítási szolgáltatás [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum a saját nyelvén tekintendő hiteles forrásnak. Kritikus információk esetén professzionális emberi fordítást javaslunk. Nem vállalunk felelősséget az ebből eredő félreértésekért vagy félreértelmezésekért. - \ No newline at end of file diff --git a/translations/hu/01-introduction/README.md b/translations/hu/01-introduction/README.md index 80bdb5c30..4f108e37e 100644 --- a/translations/hu/01-introduction/README.md +++ b/translations/hu/01-introduction/README.md @@ -2,86 +2,86 @@ ## Tartalomjegyzék -- [Videó bemutató](../../../01-introduction) -- [Amit megtanulsz](../../../01-introduction) -- [Előfeltételek](../../../01-introduction) -- [A fő probléma megértése](../../../01-introduction) -- [Tokenek megértése](../../../01-introduction) -- [Hogyan működik a memória](../../../01-introduction) -- [Hogyan használja ezt a LangChain4j](../../../01-introduction) -- [Azure OpenAI infrastruktúra telepítése](../../../01-introduction) -- [Alkalmazás futtatása helyileg](../../../01-introduction) -- [Az alkalmazás használata](../../../01-introduction) - - [Állapot nélküli csevegés (bal panel)](../../../01-introduction) - - [Állapotfüggő csevegés (jobb panel)](../../../01-introduction) -- [Következő lépések](../../../01-introduction) - -## Videó bemutató - -Nézd meg ezt az élő bemutatót, amely elmagyarázza, hogyan kezdj neki ennek a modulnak: +- [Videós bemutató](#videós-bemutató) +- [Mit fogsz megtanulni](#mit-fogsz-megtanulni) +- [Előfeltételek](#előfeltételek) +- [Az alapvető probléma megértése](#az-alapvető-probléma-megértése) +- [Tokenek megértése](#tokenek-megértése) +- [Hogyan működik a memória](#hogyan-működik-a-memória) +- [Hogyan használja ezt a LangChain4j](#hogyan-használja-ezt-a-langchain4j) +- [Azure OpenAI infrastruktúra telepítése](#azure-openai-infrastruktúra-telepítése) +- [Alkalmazás helyi futtatása](#alkalmazás-helyi-futtatása) +- [Az alkalmazás használata](#az-alkalmazás-használata) + - [Állapot nélküli chat (bal panel)](#állapot-nélküli-chat-bal-panel) + - [Állapotkövető chat (jobb panel)](#állapotkövető-chat-jobb-panel) +- [Következő lépések](#következő-lépések) + +## Videós bemutató + +Nézd meg ezt az élő adást, amely elmagyarázza, hogyan kezdj neki ennek a modulnak: Getting Started with LangChain4j - Live Session -## Amit megtanulsz +## Mit fogsz megtanulni -A gyors start során GitHub modelleket használtál promptok küldésére, eszközök meghívására, RAG pipeline építésére és guardrail tesztelésére. Ezek a bemutatók megmutatták, mi lehetséges — most áttérünk az Azure OpenAI és a GPT-5.2 használatára, és elkezdjük produkciós stílusú alkalmazások építését. Ez a modul olyan beszélgető AI-ra fókuszál, amely emlékszik a kontextusra és fenntartja az állapotot — ezek azok a fogalmak, amelyeket a gyors start demók használtak a háttérben, de nem magyaráztak el. +Ez a kiindulópontod a LangChain4j és Azure OpenAI használatában. Az alapoktól indulunk, és elkezdjük építeni a produkciós stílusú alkalmazásokat. Ez a modul a beszélgető AI-ra fókuszál, amely emlékszik a kontextusra és fenntartja az állapotot — ezek az alapvető fogalmak, amelyekre a későbbi modulok épülnek. -Az egész útmutató során az Azure OpenAI GPT-5.2-jét használjuk, mert fejlett érvelési képességei miatt a különböző minták viselkedése egyértelműbb. Amikor memóriát adsz hozzá, tisztán látni fogod a különbséget. Ez megkönnyíti annak megértését, hogy az egyes komponensek mit hoznak az alkalmazásodba. +Az útmutató során az Azure OpenAI GPT-5.2-jét használjuk, mivel fejlett érvelési képességei miatt jobban láthatóvá válik a különböző minták viselkedése. Ha memóriát adsz hozzá, világosan látni fogod a különbséget. Ez megkönnyíti megérteni, hogy melyik komponens mit ad az alkalmazásodhoz. -Egy alkalmazást építesz, amely mindkét mintát bemutatja: +Egy alkalmazást fogsz építeni, amely mindkét mintát bemutatja: -**Állapot nélküli csevegés** - Minden kérés független. A modell nem emlékszik az előző üzenetekre. Ez az a minta, amit a gyors startban használtál. +**Állapot nélküli chat** – Minden kérés független. A modell nem emlékszik a korábbi üzenetekre. Ez a legegyszerűbb kiindulási pont. -**Állapotfüggő beszélgetés** - Minden kérés tartalmazza a beszélgetés előzményeit. A modell megőrzi a kontextust több fordulón át. Erre van szükség a produkciós alkalmazásokban. +**Állapotkövető beszélgetés** – Minden kérés tartalmazza a beszélgetés előzményeit. A modell több fordulón keresztül fenntartja a kontextust. Ez kell a produkciós alkalmazásokhoz. ## Előfeltételek -- Azure előfizetés Azure OpenAI hozzáféréssel +- Azure előfizetés Azure OpenAI-hozzáféréssel - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) > **Megjegyzés:** A Java, Maven, Azure CLI és Azure Developer CLI (azd) előre telepítve van a biztosított devcontainerben. -> **Megjegyzés:** Ez a modul az Azure OpenAI GPT-5.2-jét használja. A telepítés automatikusan a `azd up` paranccsal történik — ne módosítsd a modell nevét a kódban. +> **Megjegyzés:** Ez a modul az Azure OpenAI GPT-5.2 verzióját használja. A telepítés automatikusan konfigurálódik az `azd up` használatával – NE módosítsd a modell nevét a kódban. -## A fő probléma megértése +## Az alapvető probléma megértése -A nyelvi modellek állapot nélküli működésűek. Minden API hívás független. Ha elküldöd, hogy „A nevem John”, majd megkérdezed, „Mi a nevem?”, a modell nem tudja, hogy épp most mutatkoztál be. Minden kérés úgy kezel, mintha az lenne az első beszélgetésed valaha. +A nyelvi modellek állapot nélküli(ek). Minden API hívás független. Ha elküldöd, hogy "A nevem John", majd megkérdezed, hogy "Mi a nevem?", a modellnek fogalma sincs, hogy éppen bemutatkoztál. Minden kérést úgy kezel, mintha az lenne az első beszélgetésed valaha. -Ez egyszerű kérdés-válasz esetén rendben van, de valódi alkalmazásokhoz haszontalan. Az ügyfélszolgálati botoknak emlékezniük kell arra, amit mondtál. A személyi asszisztenseknek szükségük van kontextusra. Bármilyen többfordulós beszélgetés memóriát igényel. +Ez rendben van egyszerű kérdés-válasz esetén, de semmit sem ér valós alkalmazásokban. Az ügyfélszolgálati botoknak emlékezniük kell arra, amit mondtál nekik. A személyi asszisztenseknek kontextusra van szükségük. Bármilyen többfordulós beszélgetéshez memória kell. -Az alábbi ábra összehasonlítja a két megközelítést — bal oldalon egy állapot nélküli hívás, amely elfelejti a neved; jobb oldalon egy állapotfüggő hívás, melyet a ChatMemory támogat, és emlékszik rá. +A következő ábra bemutatja a két megközelítést – bal oldalon egy állapot nélküli hívás, amely elfelejti a neved; jobbra egy állapotkövető hívás a ChatMemory támogatásával, amely emlékszik rá. Stateless vs Stateful Conversations -*A különbség az állapot nélküli (független hívások) és az állapotfüggő (kontextus-érzékeny) beszélgetések között* +*Az állapot nélküli (független hívások) és az állapotkövető (kontextus-érzékeny) beszélgetések közötti különbség* ## Tokenek megértése -Mielőtt belevágnánk a beszélgetésekbe, fontos megérteni a tokeneket — a szöveg alapvető egységeit, amelyeket a nyelvi modellek feldolgoznak: +Mielőtt belemerülnénk a beszélgetésekbe, fontos megérteni a tokeneket - a nyelvi modellek által feldolgozott alapvető szövegegységeket: Token Explanation -*Példa arra, hogyan bontja szét a szöveget tokenekre — az "I love AI!" 4 különálló feldolgozási egységgé válik* +*Példa arra, hogyan törik fel a szöveg tokenekre – az "I love AI!" 4 külön feldolgozási egységgé válik* -A tokenek azok, amivel az AI modellek mérik és dolgozzák fel a szöveget. Szavak, írásjelek és akár szóközök is lehetnek tokenek. A modellednek van egy limitje, hogy mennyi tokent tud egyszerre feldolgozni (GPT-5.2 esetén 400,000, ebből legfeljebb 272,000 bemeneti és 128,000 kimeneti token). A tokenek megértése segít a beszélgetések hosszának és költségeinek kezelésében. +A tokenek azok az egységek, amikkel az AI modellek mérik és feldolgozzák a szöveget. Szavak, írásjelek és akár szóközök is lehetnek tokenek. A modellednek van egy határa, hogy egyszerre hány tokent képes feldolgozni (GPT-5.2 esetében 400,000 token, amiből legfeljebb 272,000 bemeneti és 128,000 kimeneti token lehet). A tokenek megértése segít szabályozni a beszélgetés hosszát és költségeit. ## Hogyan működik a memória -A beszélgetési memória megoldja az állapot nélküli problémát azáltal, hogy megőrzi a beszélgetés előzményeit. Mielőtt elküldenéd a kérésed a modellnek, a keretrendszer hozzáfűzi a releváns korábbi üzeneteket. Amikor megkérdezed, hogy „Mi a nevem?”, a rendszer valójában az egész beszélgetési előzményt elküldi, lehetővé téve, hogy a modell lássa, hogy korábban azt mondtad, „A nevem John”. +A chat memória megoldja az állapot nélküli problémát azáltal, hogy fenntartja a beszélgetés előzményeit. Mielőtt elküldenéd a kérést a modellnek, a keretrendszer hozzáfűzi a releváns korábbi üzeneteket. Amikor megkérdezed, hogy "Mi a nevem?", a rendszer valójában az egész beszélgetési előzményt továbbítja, így a modell látja, hogy korábban azt mondtad: "A nevem John." -A LangChain4j memóriamegoldásokat kínál, amelyek ezt automatikusan kezelik. Meghatározod, hány üzenetet szeretnél megtartani, és a keretrendszer kezeli a kontextusablakot. Az alábbi ábra megmutatja, hogyan tartja karban a MessageWindowChatMemory az üzenetek csúszó ablakát. +A LangChain4j memória implementációkat biztosít, amelyek ezt automatikusan kezelik. Te választod meg, hány üzenetet szeretnél megtartani, a keretrendszer pedig kezeli a kontextus ablakot. Az alábbi ábra azt mutatja, hogy a MessageWindowChatMemory hogyan tart fenn egy csúszóablakot a legfrissebb üzenetekből. Memory Window Concept -*A MessageWindowChatMemory egy csúszó ablakban tartja a legutóbbi üzeneteket, automatikusan kidobva a régi üzeneteket* +*MessageWindowChatMemory egy csúszóablakot tart fenn a legfrissebb üzenetekből, automatikusan törölve a régebbieket* ## Hogyan használja ezt a LangChain4j -Ez a modul kiterjeszti a gyors startot a Spring Boot integrálásával és beszélgetési memória hozzáadásával. Így illeszkednek össze a részek: +Ez a modul integrálja a Spring Boot-ot és hozzáadja a beszélgetési memóriát. Így kapcsolódnak össze az elemek: -**Függőségek** — Adj hozzá két LangChain4j könyvtárat: +**Függőségek** – Két LangChain4j könyvtár hozzáadása: ```xml @@ -94,7 +94,7 @@ Ez a modul kiterjeszti a gyors startot a Spring Boot integrálásával és besz ``` -**Chat modell** — Konfiguráld az Azure OpenAI-t Spring bean-ként ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chat modell** – Azure OpenAI configuração, Spring bean-ként ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -A builder a `azd up` által beállított környezeti változókból olvassa a hitelesítő adatokat. A `baseUrl` beállítása az Azure végpontodra teszi az OpenAI klienst Azure OpenAI-kompatibilissé. +A builder az `azd up` által beállított környezeti változókból olvassa a hitelesítést. A `baseUrl` beállítása az Azure végpontodra teszi az OpenAI klienst működővé Azure OpenAI-val. -**Beszélgetési memória** — Kövesd a chat előzményeit a MessageWindowChatMemory-val ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Beszélgetési memória** – Követi a chat előzményeket a MessageWindowChatMemory segítségével ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,39 +124,39 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Hozz létre memóriát `withMaxMessages(10)` paraméterrel, hogy az utolsó 10 üzenetet megtartsa. Adj hozzá felhasználói és AI üzeneteket típusos csomagolókkal: `UserMessage.from(text)` és `AiMessage.from(text)`. A történetet a `memory.messages()` segítségével kérheted le, és elküldheted a modellnek. A szolgáltatás külön memória példányokat tárol beszélgetésazonosítónként, így egyszerre több felhasználó is cseveghet. +A memóriát a `withMaxMessages(10)`-zel hozod létre, hogy az utolsó 10 üzenet maradjon meg. A felhasználói és AI üzeneteket típusos csomagolókkal adod hozzá: `UserMessage.from(text)` és `AiMessage.from(text)`. Az előzmények lekéréséhez `memory.messages()` hívható és küldhető a modellnek. A szolgáltatás minden beszélgetésazonosítóhoz külön memóriát tárol, így több felhasználó is egyszerre chatelhet. -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chat segítségével:** Nyisd meg a [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) fájlt, és kérdezd meg: -> - "Hogyan dönt a MessageWindowChatMemory arról, mely üzeneteket dobja el, amikor az ablak megtelik?" -> - "Megvalósíthatok-e egyéni memóriatárolót adatbázis használatával in-memory helyett?" -> - "Hogyan adhatnék hozzá összefoglalást, hogy tömörítsem a régi beszélgetési előzményeket?" +> **🤖 Próbáld ki [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)-t és kérdezd meg: +> - "Hogyan dönti el a MessageWindowChatMemory, hogy melyik üzeneteket dobja el, ha megtelik az ablak?" +> - "Meg tudok valósítani egyedi memória tárolást adatbázis használatával a memóriában?" +> - "Hogyan adnám hozzá az összefoglalást, hogy tömörítsem a régi beszélgetési előzményeket?" -Az állapot nélküli csevegés végpont teljesen kihagyja a memóriát — csak `chatModel.chat(prompt)`, mint a gyors startban. Az állapotfüggő végpont hozzáadja az üzeneteket a memóriához, lekéri a történetet, és minden kéréshez csatolja azt. Ugyanaz a modell konfiguráció, de más minták. +Az állapot nélküli chat végpont teljesen kihagyja a memóriát – csak `chatModel.chat(prompt)` mint a gyors kezdésnél. Az állapotkövető végpont hozzáadja az üzeneteket a memóriához, lekéri az előzményeket, és ezt a kontextust küldi minden kérésnél. Ugyanaz a modellkonfiguráció, más minták. ## Azure OpenAI infrastruktúra telepítése **Bash:** ```bash cd 01-introduction -azd up # Válassza ki az előfizetést és a helyszínt (ajánlott: eastus2) +azd up # Válassza ki az előfizetést és a helyszínt (az eastus2 javasolt) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Válassza ki az előfizetést és a helyet (az eastus2 ajánlott) +azd up # Válassza ki az előfizetést és a helyszínt (eastus2 ajánlott) ``` -> **Megjegyzés:** Ha időtúllépési hibába futsz (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), egyszerűen futtasd újra az `azd up` parancsot. Az Azure erőforrások még háttérben települhetnek, az ismétlés lehetővé teszi, hogy a telepítés befejeződjön, amint az erőforrások végleges állapotba kerülnek. +> **Megjegyzés:** Ha időtúllépési hibát kapsz (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), egyszerűen futtasd újra az `azd up` parancsot. Az Azure erőforrások még háttérben települhetnek, és az újrapróbálkozás engedélyezi, hogy a telepítés befejeződjön, amint az erőforrások elérnek egy végső állapotot. -Ez a következőket teszi: -1. Telepíti az Azure OpenAI erőforrást a GPT-5.2-vel és a text-embedding-3-small modellekkel +A parancs: +1. Telepíti az Azure OpenAI erőforrást a GPT-5.2 és text-embedding-3-small modellekkel 2. Automatikusan létrehozza a `.env` fájlt a projekt gyökérkönyvtárában a hitelesítő adatokkal 3. Beállít minden szükséges környezeti változót -**Telepítési problémák esetén?** Lásd az [infrastruktúra README](infra/README.md) fájlt a részletes hibakereséshez, többek között aldomain névütközések, manuális Azure Portal telepítési lépések és modell konfigurációs útmutató. +**Telepítési hibák esetén?** Lásd az [Infrastruktúra README](infra/README.md) fájlt részletes hibakereséssel, beleértve az aldoménnév konfliktusokat, kézi Azure Portal telepítési lépéseket és modellkonfigurációs útmutatót. -**Ellenőrizd, hogy sikeres volt-e a telepítés:** +**Ellenőrizd a telepítés sikerességét:** **Bash:** ```bash @@ -165,10 +165,10 @@ cat ../.env # Meg kell jelenítenie az AZURE_OPENAI_ENDPOINT, API_KEY stb. ért **PowerShell:** ```powershell -Get-Content ..\.env # Az AZURE_OPENAI_ENDPOINT, API_KEY stb. értékét kell megjeleníteni. +Get-Content ..\.env # Meg kell jeleníteni az AZURE_OPENAI_ENDPOINT, API_KEY stb. értékeket. ``` -> **Megjegyzés:** Az `azd up` parancs automatikusan létrehozza a `.env` fájlt. Ha később frissíteni kell, kézzel szerkesztheted, vagy újragenerálhatod a következőkkel: +> **Megjegyzés:** Az `azd up` parancs automatikusan generálja a `.env` fájlt. Ha később módosítani kell, vagy szerkesztheted kézzel, vagy újra generálhatod: > > **Bash:** > ```bash @@ -182,12 +182,11 @@ Get-Content ..\.env # Az AZURE_OPENAI_ENDPOINT, API_KEY stb. értékét kell me > .\.azd-env.ps1 > ``` - -## Alkalmazás futtatása helyileg +## Alkalmazás helyi futtatása **Ellenőrizd a telepítést:** -Győződj meg arról, hogy a `.env` fájl létezik a gyökérkönyvtárban az Azure hitelesítő adatokkal. Futtasd ezt a modul könyvtárából (`01-introduction/`): +Győződj meg róla, hogy a `.env` fájl létezik a gyökérkönyvtárban az Azure hitelesítő adatokkal. Futtasd ezt a modul könyvtárából (`01-introduction/`): **Bash:** ```bash @@ -196,44 +195,44 @@ cat ../.env # Meg kell jeleníteni az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMEN **PowerShell:** ```powershell -Get-Content ..\.env # Meg kell jeleníteni AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket +Get-Content ..\.env # Meg kell jeleníteni az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket ``` **Indítsd el az alkalmazásokat:** -**1. lehetőség: Spring Boot Dashboard használata (Ajánlott VS Code felhasználóknak)** +**Opció 1: Spring Boot Dashboard használata (ajánlott VS Code felhasználóknak)** -A fejlesztői konténer tartalmazza a Spring Boot Dashboard kiterjesztést, amely vizuális felületet nyújt az összes Spring Boot alkalmazás kezelésére. Megtalálod az Activity Bar bal oldalán VS Code-ban (keresd a Spring Boot ikont). +A dev konténer tartalmazza a Spring Boot Dashboard kiterjesztést, amely vizuális felületet biztosít az összes Spring Boot alkalmazás kezeléséhez. Megtalálod a VS Code bal oldalán az Activity Barban (keresd a Spring Boot ikont). A Spring Boot Dashboard segítségével: -- Láthatod a munkaterületen elérhető összes Spring Boot alkalmazást +- Láthatod az összes rendelkezésre álló Spring Boot alkalmazást a munkaterületen - Egy kattintással indíthatod/leállíthatod az alkalmazásokat -- Valós időben követheted az alkalmazás naplóit -- Figyelemmel kísérheted az alkalmazások állapotát +- Valós időben megtekintheted az alkalmazás naplóit +- Figyelheted az alkalmazás állapotát -Egyszerűen kattints a lejátszás gombra az "introduction" modul mellett ennek indításához, vagy indítsd el az összes modult egyszerre. +Csak kattints a lejátszás gombra az "introduction" mellett, hogy elindítsd ezt a modult, vagy indítsd el egyszerre az összes modult. Spring Boot Dashboard -*Spring Boot Dashboard VS Code-ban — indítsd, állítsd le és figyeld az összes modult egy helyen* +*A Spring Boot Dashboard a VS Code-ban – indíts, állíts le és felügyelj minden modult egy helyről* -**2. lehetőség: Shell scriptek használata** +**Opció 2: Shell scriptek használata** -Indítsd el az összes webalkalmazást (01-04 modulok): +Indítsd el az összes webalkalmazást (az 01-04 modulokat): **Bash:** ```bash -cd .. # A gyökérkönyvtárból +cd .. # Gyökérkönyvtárból ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Gyökérkönyvtárból +cd .. # A gyökérkönyvtárból .\start-all.ps1 ``` -Vagy indítsd csak ezt a modult: +Vagy csak ezt a modult: **Bash:** ```bash @@ -247,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Mindkét script automatikusan betölti a környezeti változókat a gyökér `.env` fájlból és lefordítja a JAR fájlokat, ha még nem léteznek. +Mindkét script automatikusan betölti a környezeti változókat a gyökér `.env` fájljából, és ha a JAR fájlok nem léteznek, lefordítja őket. -> **Megjegyzés:** Ha előbb szeretnéd kézzel lefordítani az összes modult: +> **Megjegyzés:** Ha inkább manuálisan építenéd meg az összes modult indulás előtt: > > **Bash:** > ```bash @@ -263,8 +262,7 @@ Mindkét script automatikusan betölti a környezeti változókat a gyökér `.e > mvn clean package -DskipTests > ``` - -Nyisd meg a http://localhost:8080 címet a böngésződben. +Nyisd meg böngészőben a http://localhost:8080 címet. **Leállításhoz:** @@ -282,44 +280,43 @@ cd .. && ./stop-all.sh # Minden modul cd ..; .\stop-all.ps1 # Minden modul ``` - ## Az alkalmazás használata -Az alkalmazás egy webes felületet biztosít két párhuzamosan megjelenített csevegés implementációval. +Az alkalmazás egy webes felületet biztosít két chat implementációval egymás mellett. Application Home Screen -*Irányítópult, amely mind a Simple Chat (állapot nélküli), mind a Conversational Chat (állapotfüggő) opciókat mutatja* +*Vezérlőpult, amely mind az Egyszerű Chat (állapot nélküli), mind a Beszélgető Chat (állapotkövető) lehetőségeket mutatja* -### Állapot nélküli csevegés (bal panel) +### Állapot nélküli chat (bal panel) -Ezzel próbáld először. Írd be, hogy „A nevem John”, majd azonnal kérdezd meg: „Mi a nevem?” A modell nem fog emlékezni, mert minden üzenet független. Ez demonstrálja az alapvető nyelvi modell integráció fő problémáját — nincs beszélgetési kontextus. +Ezt próbáld ki először. Írd be, hogy "A nevem John", majd azonnal kérdezd meg, hogy "Mi a nevem?" A modell nem fog emlékezni, mert minden üzenet független. Ez bemutatja az alapnyelvi modell integráció alapvető problémáját – nincs beszélgetési kontextus. Stateless Chat Demo -*Az AI nem emlékszik az előző üzenetben mondott nevedre* +*Az AI nem emlékszik a nevedre az előző üzenetből* -### Állapotfüggő csevegés (jobb panel) +### Állapotkövető chat (jobb panel) -Most próbáld meg ugyanezt itt. Írd be, hogy „A nevem John”, majd „Mi a nevem?” Ezúttal emlékszik. A különbség a MessageWindowChatMemory — ez kezeli a beszélgetési előzményeket és minden kéréshez csatolja azt. Így működik a produkciós beszélgető AI. +Most próbáld ugyanazt a sorrendet itt. Írd be, hogy "A nevem John", majd kérdezd meg, hogy "Mi a nevem?" Most emlékszik rá. A különbség a MessageWindowChatMemory – ez fenntartja a beszélgetési előzményeket, és minden kéréshez hozzáadja azokat. Így működik a produkciós beszélgető AI. Stateful Chat Demo -*Az AI emlékszik a beszélgetés korábbi részében mondott nevedre* +*Az AI emlékszik a nevedre a beszélgetés korábbi részéből* -Mindkét panel ugyanazt a GPT-5.2 modellt használja. Az egyetlen különbség a memória. Ez világossá teszi, hogy a memória mit ad hozzá az alkalmazásodhoz, és miért alapvető a valódi használati esetekhez. +Mindkét panel ugyanazt a GPT-5.2 modellt használja. Az egyetlen különbség a memória. Ez világossá teszi, hogy mit ad a memória az alkalmazásodhoz és miért elengedhetetlen a valós esetekhez. ## Következő lépések -**Következő modul:** [02-prompt-engineering - Prompt Engineering GPT-5.2-vel](../02-prompt-engineering/README.md) +**Következő modul:** [02-prompt-engineering - Prompt engineering GPT-5.2-vel](../02-prompt-engineering/README.md) --- -**Navigáció:** [← Előző: Modul 00 - Gyors start](../00-quick-start/README.md) | [Vissza a főoldalra](../README.md) | [Következő: Modul 02 - Prompttervezés →](../02-prompt-engineering/README.md) +**Navigáció:** [← Vissza a főoldalra](../README.md) | [Következő: Modul 02 - Prompt engineering →](../02-prompt-engineering/README.md) --- **Jogi nyilatkozat**: -Ezt a dokumentumot az AI fordító szolgáltatás [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével fordítottuk. Bár pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum anyanyelvű változata tekintendő hivatalos forrásnak. Fontos információk esetén professzionális emberi fordítást javaslunk. Nem vállalunk felelősséget az ezen fordítás használatából eredő félreértésekért vagy helytelen értelmezésekért. +Ez a dokumentum az AI fordítási szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Fontos információk esetén professzionális emberi fordítást javasolunk. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely ebből a fordításból ered. \ No newline at end of file diff --git a/translations/hu/02-prompt-engineering/README.md b/translations/hu/02-prompt-engineering/README.md index 09fb25947..4907428fa 100644 --- a/translations/hu/02-prompt-engineering/README.md +++ b/translations/hu/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Modul 02: Prompt Műszaki Tervezés a GPT-5.2-vel +# Modul 02: Prompt Mérés GPT-5.2-vel ## Tartalomjegyzék -- [Videós Bemutató](../../../02-prompt-engineering) -- [Amit Meg Fogsz Tanulni](../../../02-prompt-engineering) -- [Előfeltételek](../../../02-prompt-engineering) -- [A Prompt Műszaki Tervezés Megértése](../../../02-prompt-engineering) -- [A Prompt Műszaki Tervezés Alapjai](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Gondolatmenet Láncolata](../../../02-prompt-engineering) - - [Szerepalapú Prompting](../../../02-prompt-engineering) - - [Prompt Sablonok](../../../02-prompt-engineering) -- [Fejlett Minták](../../../02-prompt-engineering) -- [Az Alkalmazás Futtatása](../../../02-prompt-engineering) -- [Alkalmazás Képernyőképek](../../../02-prompt-engineering) -- [A Minták Felfedezése](../../../02-prompt-engineering) - - [Alacsony vs Magas Lelkesedés](../../../02-prompt-engineering) - - [Feladatvégrehajtás (Eszköz Előszövegek)](../../../02-prompt-engineering) - - [Önreflektáló Kód](../../../02-prompt-engineering) - - [Strukturált Elemzés](../../../02-prompt-engineering) - - [Többkörös Csevegés](../../../02-prompt-engineering) - - [Lépésről Lépésre Logika](../../../02-prompt-engineering) - - [Korlátozott Kimenet](../../../02-prompt-engineering) -- [Amit Valójában Meg Fogsz Tanulni](../../../02-prompt-engineering) -- [Következő Lépések](../../../02-prompt-engineering) - -## Videós Bemutató - -Nézd meg ezt az élő bemutatót, amely megmutatja, hogyan kezdhetsz neki ennek a modulnak: +- [Videós bemutató](#videós-bemutató) +- [Amit megtanulsz](#amit-megtanulsz) +- [Előfeltételek](#előfeltételek) +- [A Prompt Mérés megértése](#a-prompt-mérés-megértése) +- [A Prompt Mérés alapjai](#a-prompt-mérés-alapjai) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Gondolatmenet láncolata](#gondolatmenet-láncolata) + - [Szerepalapú Prompting](#szerepalapú-prompting) + - [Prompt sablonok](#prompt-sablonok) +- [Fejlett minták](#fejlett-minták) +- [Az alkalmazás futtatása](#az-alkalmazás-futtatása) +- [Az alkalmazás képernyőképei](#alkalmazás-képernyőképek) +- [A minták felfedezése](#a-minták-felfedezése) + - [Alacsony vs magas lelkesedés](#alacsony-vs-magas-lelkesedés) + - [Feladat-végrehajtás (Eszköz-előszavak)](#feladatteljesítés-eszköz-bevezetők) + - [Önreflektáló kód](#önszemléletű-kód) + - [Strukturált elemzés](#strukturált-elemzés) + - [Többfordulós csevegés](#többfordulós-chat) + - [Lépésről lépésre való érvelés](#lépésről-lépésre-történő-érvelés) + - [Korlátozott kimenet](#korlátozott-kimenet) +- [Amit valóban megtanulsz](#amit-valójában-tanulsz) +- [Következő lépések](#következő-lépések) + +## Videós bemutató + +Nézd meg ezt az élő adást, amely elmagyarázza, hogyan kezdj neki ennek a modulnak: Prompt Engineering with LangChain4j - Live Session -## Amit Meg Fogsz Tanulni +## Amit megtanulsz -A következő ábra áttekintést ad a kulcsfontosságú témákról és készségekről, amelyeket ebben a modulban fejleszteni fogsz — a prompt finomítási technikáktól a lépésről lépésre követett munkafolyamatig. +Az alábbi diagram áttekintést nyújt a modul kulcsfontosságú témáiról és készségeiről — a prompt finomítási technikáktól a lépésenkénti munkafolyamatig, amelyet követni fogsz. -Amit Meg Fogsz Tanulni +What You'll Learn -Az előző modulokban megismerted az alapvető LangChain4j interakciókat a GitHub modellekkel, és láthattad, hogyan teszi lehetővé a memória a beszélgető AI működését Azure OpenAI-val. Most arra koncentrálunk, hogyan teszel fel kérdéseket — vagyis magukra a promptokra — Azure OpenAI GPT-5.2 használatával. Az, hogy hogyan strukturálod a promptjaidat, drámaian befolyásolja a kapott válaszok minőségét. Kezdjük az alapvető prompting technikák áttekintésével, majd továbblépünk nyolc fejlett mintára, amelyek teljes mértékben kihasználják a GPT-5.2 képességeit. +Az előző modulban láttad, hogyan teszi lehetővé a memória a konverzációs AI-t az Azure OpenAI-val. Most arra fókuszálunk, hogyan teszel fel kérdéseket — azaz magukra a promptokra — az Azure OpenAI GPT-5.2 segítségével. A promptok felépítése drámaian befolyásolja a kapott válaszok minőségét. Először áttekintjük az alapvető prompting technikákat, majd áttérünk nyolc fejlett mintára, amelyek teljes mértékben kihasználják a GPT-5.2 képességeit. -A GPT-5.2-t azért használjuk, mert bevezeti az érvelés szabályozását — megmondhatod a modellnek, mennyi gondolkodást végezzen mielőtt válaszol. Ez világosabbá teszi a különböző prompting stratégiákat, és segít megérteni, mikor melyik megközelítést használd. Továbbá, az Azure kevesebb korlátozást tesz a GPT-5.2-re a GitHub modellekhez képest. +A GPT-5.2-t azért használjuk, mert bevezeti az érvelés szabályozását - megmondhatod a modellnek, mennyi gondolkodást végezzen a válaszadás előtt. Ez tisztábban láttatja a különböző prompting stratégiákat és segít megérteni, mikor melyiket alkalmazd. ## Előfeltételek - Az 01-es modul elvégzése (Azure OpenAI erőforrások telepítve) -- `.env` fájl a gyökérkönyvtárban Azure hitelesítő adatokkal (az `azd up` parancs által létrehozva az 01-es modulban) +- `.env` fájl a gyökérkönyvtárban Azure hitelesítő adatokkal (az `azd up` parancs hozta létre az 01-es modulban) -> **Megjegyzés:** Ha még nem végezted el az 01-es modult, először kövesd ott a telepítési útmutatót. +> **Megjegyzés:** Ha még nem végezted el az 01-es modult, először ott kövesd a telepítési utasításokat. -## A Prompt Műszaki Tervezés Megértése +## A Prompt Mérés megértése -Lényegében a prompt műszaki tervezés a homályos és a pontos utasítások közti különbség, amint ezt az alábbi összehasonlítás is illusztrálja. +Lényegében a prompt mérnökség a homályos utasítások és a pontosak közötti különbség, ahogy az alábbi összehasonlítás is mutatja. -Mi a Prompt Műszaki Tervezés? +What is Prompt Engineering? -A prompt műszaki tervezés az olyan bemeneti szöveg megtervezéséről szól, amely következetesen eléri a kívánt eredményeket. Nemcsak kérdések feltevéséről van szó - arról is, hogy úgy struktúrálod a kéréseket, hogy a modell pontosan értse, mit akarsz és hogyan kell teljesíteni. +A prompt mérnökség arról szól, hogy olyan bemenetet tervezz, amely következetesen a kívánt eredményeket hozza. Nem csak kérdések feltevése – hanem az igények olyan strukturálása, hogy a modell pontosan értse, mit szeretnél, és hogyan adja vissza. -Gondolj rá úgy, mint egy kollégának adott utasításra. „Javítsd meg a hibát” homályos. „Javítsd meg a null pointer kivételt a UserService.java 45. sorában null ellenőrzéssel” specifikus. A nyelvi modellek ugyanígy működnek — a specifikusság és a struktúra számít. +Gondolj rá úgy, mint amikor utasítást adsz egy kollégának. „Javítsd a hibát” homályos. „Javítsd a null pointer exception-t a UserService.java 45. sorában egy null ellenőrzés hozzáadásával” specifikus. A nyelvi modellek ugyanígy működnek – a konkrétság és az struktúra számít. -Az alábbi ábra mutatja, hogyan illeszkedik ide a LangChain4j — összekapcsolva a prompt mintáidat a modellel a SystemMessage és UserMessage építőelemek segítségével. +Az alábbi diagram azt mutatja, hogyan illeszkedik ebbe a képbe a LangChain4j — összekapcsolva a prompt mintáidat a modellel a SystemMessage és UserMessage építőelemek segítségével. -Hogyan Illeszkedik a LangChain4j +How LangChain4j Fits -A LangChain4j biztosítja az infrastruktúrát — modellkapcsolatok, memória és üzenettípusok — miközben a prompt minták egyszerűen gondosan strukturált szövegek, amelyeket ezen infrastruktúrán keresztül küldesz. A kulcsépítőelemek a `SystemMessage` (amely beállítja az MI viselkedését és szerepét) és a `UserMessage` (amely hordozza a tényleges kérésedet). +A LangChain4j az infrastruktúrát biztosítja — modellkapcsolatokat, memóriát és üzenettípusokat — míg a prompt minták csupán gondosan strukturált szövegek, amelyeket ezen az infrastruktúrán keresztül küldesz. A kulcsfontosságú építőelemek a `SystemMessage` (ami beállítja az AI viselkedését és szerepét) és a `UserMessage` (ami az aktuális kérést hordozza). -## A Prompt Műszaki Tervezés Alapjai +## A Prompt Mérés alapjai -Az alább bemutatott öt alapvető technika alkotja a hatékony prompt műszaki tervezés alapját. Mindegyik más aspektusát célozza meg annak, hogyan kommunikálsz a nyelvi modellekkel. +Az alább látható öt alapvető technika képezi a hatékony prompt mérnökség alapját. Mindegyik más-más aspektusát célozza meg annak, ahogyan kommunikálsz a nyelvi modellekkel. -Öt Prompt Műszaki Tervezési Minta Áttekintése +Five Prompt Engineering Patterns Overview -Mielőtt belevágnánk a modul fejlett mintáiba, tekintsük át az öt alapvető prompting technikát. Ezek azok az építőelemek, amelyeket minden prompt mérnöknek ismernie kell. Ha már dolgoztál a [Gyors kezdő modulon](../00-quick-start/README.md#2-prompt-patterns), láthattad őket működés közben — itt a mögöttes fogalmi keret. +Mielőtt belevágnánk a fejlett mintákba, nézzük át az öt alapvető prompting technikát. Ezek az építőelemei minden prompt mérnök eszköztárának. ### Zero-Shot Prompting -A legegyszerűbb megközelítés: közvetlen utasítást adsz a modellnek példa nélkül. A modell teljes egészében a tréningjére hagyatkozik a feladat megértésében és végrehajtásában. Ez jól működik egyértelmű kéréseknél, ahol a várt viselkedés nyilvánvaló. +A legegyszerűbb megközelítés: adj közvetlen utasítást a modellnek példák nélkül. A modell teljes mértékben a tanulására támaszkodik a feladat megértéséhez és végrehajtásához. Ez jól működik egyszerű kéréseknél, ahol az elvárt viselkedés nyilvánvaló. Zero-Shot Prompting -*Közvetlen utasítás példák nélkül — a modell csak az utasításból következteti a feladatot* +*Közvetlen utasítás példák nélkül — a modell csak az utasításból következtet a feladatra* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); // Válasz: "Pozitív" ``` - -**Mikor használd:** Egyszerű osztályozásoknál, közvetlen kérdéseknél, fordításnál vagy bármilyen feladatnál, amelyet a modell további útmutatás nélkül képes kezelni. + +**Mikor használd:** Egyszerű osztályozások, közvetlen kérdések, fordítások vagy bármilyen feladat, amit a modell további iránymutatás nélkül kezelni tud. ### Few-Shot Prompting -Adj példákat, amelyek megmutatják a modellt követendő mintát. A modell megtanulja az elvárt input-output formátumot a példáidból, majd alkalmazza azt új bemenetekre. Ez jelentősen javítja a konzisztenciát ott, ahol a kívánt formátum vagy viselkedés nem nyilvánvaló. +Adj példákat, amelyek megmutatják, milyen mintát szeretnél, hogy a modell kövessen. A modell megtanulja az elvárt input-output formátumot a példáidból, és alkalmazza azt új bemenetekre. Ez drámaian javítja a következetességet azoknál a feladatoknál, ahol a kívánt formátum vagy viselkedés nem nyilvánvaló. Few-Shot Prompting -*Példákból tanul — a modell felismeri a mintát és új bemenetekre alkalmazza* +*Példákból tanulva — a modell felismeri a mintát, és alkalmazza új inputokra* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**Mikor használd:** Egyedi osztályozásokhoz, egységes formázáshoz, speciális szakterületi feladatokhoz, vagy ha a zero-shot eredmények következetlenek. -### Gondolatmenet Láncolata +**Mikor használd:** Egyedi osztályozások, következetes formázás, domain-specifikus feladatok, vagy amikor a zero-shot eredmények nem megbízhatóak. + +### Gondolatmenet láncolata -Kérd meg a modellt, hogy lépésről lépésre mutassa be az érvelését. Ahelyett, hogy azonnal válaszolna, a modell bontsa le a problémát és részletezze a részeket. Ez javítja a pontosságot matekban, logikában és többlépéses érvelésben. +Kérd meg a modellt, hogy mutassa meg érvelését lépésről lépésre. Ahelyett, hogy azonnal válaszolna, a modell lebontja a problémát, és expliciten végighalad minden részen. Ez javítja a pontosságot matek, logika és többlépéses érvelési feladatoknál. -Gondolatmenet Láncolata Prompting +Chain of Thought Prompting -*Lépésről lépésre való érvelés — bonyolult problémák explicit logikai lépésekre bontása* +*Lépésenkénti érvelés — a komplex problémák explicit logikai lépésekre bontása* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// A modell így mutatja: 15 - 8 = 7, majd 7 + 12 = 19 alma +// A modell azt mutatja: 15 - 8 = 7, majd 7 + 12 = 19 alma ``` - -**Mikor használd:** Matekfeladatoknál, logikai rejtvényeknél, hibakeresésnél vagy bármilyen feladatnál, ahol az érvelési folyamat bemutatása javítja a pontosságot és a bizalmat. + +**Mikor használd:** Matematikai problémák, logikai rejtvények, hibakeresés vagy bármilyen feladat, ahol az érvelési folyamat láthatósága növeli a pontosságot és a bizalmat. ### Szerepalapú Prompting -Állíts be egy személyiséget vagy szerepet az MI-nek a kérdésed előtt. Ez kontextust ad, amely alakítja a válasz hangvételét, mélységét és fókuszát. Egy „szoftverarchitekt” más tanácsot ad, mint egy „junior fejlesztő” vagy egy „biztonsági auditor”. +Állíts be egy személyiséget vagy szerepet az AI-nak a kérdésed feltétele előtt. Ez kontextust ad, ami alakítja a válasz hangnemét, mélységét és fókuszát. Egy „szoftver architect” más tanácsot ad, mint egy „junior fejlesztő” vagy egy „biztonsági auditor”. -Szerepalapú Prompting +Role-Based Prompting -*Kontextus és személyiség beállítása — ugyanaz a kérdés más választ kap a kijelölt szereptől függően* +*Kontextus és személyiség beállítása — ugyanaz a kérdés más választ kap a megadott szerep függvényében* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**Mikor használd:** Kódáttekintéseknél, oktatásban, speciális szakterületi elemzéseknél vagy amikor a válaszokat egy adott szakértelmi szint vagy szemlélet szerint kell igazítani. -### Prompt Sablonok +**Mikor használd:** Kódellenőrzés, oktatás, domain-specifikus elemzések, vagy amikor a válaszokat egy adott szakértelmi szinthez vagy nézőponthoz kell szabni. + +### Prompt sablonok -Hozz létre újrahasználható promptokat változó helyőrzőkkel. Ahelyett, hogy mindig új promptot írjál, egyszer definiálj egy sablont, majd töltsd ki különböző értékekkel. A LangChain4j `PromptTemplate` osztálya ezt megkönnyíti a `{{variable}}` szintaxissal. +Készíts újrahasználható promptokat változó helyőrzőkkel. Új prompt írása helyett egyszer definiálsz egy sablont, majd különféle értékekkel töltöd fel. A LangChain4j `PromptTemplate` osztálya ezt `{{variable}}` szintaxissal egyszerűvé teszi. -Prompt Sablonok +Prompt Templates -*Újrahasználható promptok változó helyőrzőkkel — egy sablon, sok felhasználás* +*Újrahasználható prompt változó helyőrzőkkel — egy sablon, sok használat* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**Mikor használd:** Ismétlődő lekérdezéseknél, kötegelt feldolgozásnál, újrahasználható AI munkafolyamatok építésénél, vagy bármilyen helyzetben, ahol a prompt szerkezete ugyanaz marad, de az adatok változnak. + +**Mikor használd:** Ismétlődő lekérdezések különböző bemenetekkel, tömeges feldolgozás, újrahasználható AI munkafolyamatok építése, vagy bármilyen eset, ahol a prompt struktúrája azonos, de az adat változik. --- -Ezek az öt alapvető technika szilárd eszköztárat adnak a legtöbb prompting feladathoz. A modul további részében **nyolc fejlett mintát** ismerhetsz meg, amelyek kihasználják a GPT-5.2 érvelés szabályozását, önértékelését és strukturált kimeneti képességeit. +Ezek az öt alapelv egy szilárd eszköztárat ad a legtöbb prompting feladathoz. A modul további része erre épít **nyolc fejlett mintával**, amelyek kihasználják a GPT-5.2 érvelés-szabályozását, önértékelését és strukturált kimenet képességeit. -## Fejlett Minták +## Fejlett minták -Miután áttekintettük az alapokat, lépjünk tovább a nyolc fejlett mintára, amelyek egyedivé teszik ezt a modult. Nem minden problémához ugyanaz a megközelítés kell. Egyes kérdések gyors válaszokat igényelnek, mások mély gondolkodást. Egyesek látható érvelést, mások csak eredményeket. Az alábbi minták mindegyike egy adott szituációra optimalizált — és a GPT-5.2 érvelés szabályozása még nyilvánvalóbbá teszi a különbségeket. +Az alapok után térjünk át a nyolc fejlett mintára, amelyek egyedivé teszik ezt a modult. Nem minden probléma igényli ugyanazt a megközelítést. Egyes kérdések gyors válaszokat kívánnak, mások mély gondolkodást. Egyeseknél szükséges az érvelés láthatósága, másoknál csak az eredmény számít. Az alábbi minták mindegyike más helyzetre lett optimalizálva — és a GPT-5.2 érvelés-szabályozása még nyilvánvalóbbá teszi a különbségeket. -Nyolc Prompt Minta +Eight Prompting Patterns -*A nyolc prompt műszaki tervezési minták áttekintése és felhasználási eseteik* +*A nyolc prompt mérnökségi minta áttekintése és felhasználási eseteik* -A GPT-5.2 egy további dimenziót ad ezekhez a mintákhoz: *érvelés szabályozás*. Az alábbi csúszka mutatja, hogyan állíthatod be a modell gondolkodási erőfeszítését — a gyors, közvetlen válaszoktól a mély, alapos elemzésig. +A GPT-5.2 egy új dimenziót ad ezekhez a mintákhoz: *érvelés szabályozása*. Az alábbi csúszka azt mutatja, hogyan állíthatod be a modell gondolkodási erőfeszítését — a gyors, közvetlen válaszoktól a mély, alapos elemzésig. -Érvelés Szabályozás a GPT-5.2-vel +Reasoning Control with GPT-5.2 -*A GPT-5.2 érvelés szabályozásával megadhatod, mennyi gondolkodást végezzen a modell — gyors közvetlen válaszoktól a mély feltárásig* +*A GPT-5.2 érvelés szabályozásával megadhatod, mennyi gondolkodást végezzen a modell — a gyors közvetlen válaszoktól a mély feltárásig* -**Alacsony Lelkesedés (Gyors és Fókuszált)** - Egyszerű kérdésekhez, ahol gyors, közvetlen válaszokat szeretnél. A modell minimális érvelést végez - maximum 2 lépést. Használd számításokhoz, lekérdezésekhez vagy egyértelmű kérdésekhez. +**Alacsony lelkesedés (gyors és fókuszált)** - Egyszerű kérdésekhez, ahol gyors, tömör válaszokat akarsz. A modell minimális érvelést végez - maximum 2 lépés. Használd számításokhoz, keresésekhez, vagy egyenes kérdésekhez. ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> 💡 **Fedezd fel GitHub Copilot-tal:** Nyisd meg a [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) fájlt, és kérdezd meg: + +> 💡 **Fedezd fel GitHub Copilot-tal:** Nyisd meg a [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) fájlt és kérdezd: > - „Mi a különbség az alacsony és magas lelkesedésű prompting minták között?” -> - „Hogyan segítenek az XML tagek a promptok AI válaszának strukturálásában?” -> - „Mikor használjam az önreflektáló mintákat a közvetlen utasítással szemben?” +> - „Hogyan segítenek az XML tagek a promptokban az AI válaszának strukturálásában?” +> - „Mikor használjam az önreflexiós mintákat közvetlen utasítás helyett?” -**Magas Lelkesedés (Mély és Alapos)** - Összetett problémákhoz, ahol átfogó elemzésre van szükség. A modell alaposan feltár, részletes érvelést mutat. Használd rendszertervezéshez, architektúra döntésekhez vagy komplex kutatáshoz. +**Magas lelkesedés (mély és alapos)** - Komplex problémákhoz, ahol átfogó elemzést szeretnél. A modell alaposan vizsgálódik és részletes érvelést mutat. Használd rendszertervezéshez, architektúra döntésekhez vagy komplex kutatáshoz. ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**Feladatvégrehajtás (Lépésről lépésre haladás)** - Többlépéses munkafolyamatokhoz. A modell előre megtervezi a lépéseket, elmondja, mit csinál, majd összefoglal. Használd migrációkhoz, implementációkhoz vagy bármilyen többlépéses feladathoz. + +**Feladat-végrehajtás (lépésenkénti haladás)** - Többlépéses munkafolyamatokhoz. A modell előzetesen tervet ad, narrálja az egyes lépéseket, majd összefoglal. Használd migrációkhoz, implementációkhoz, vagy bármilyen többlépéses folyamathoz. ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -A Chain-of-Thought prompting kifejezetten kéri a modellt, hogy mutassa meg az érvelési folyamatát, javítva a pontosságot összetett feladatoknál. A lépésenkénti bontás segíti az embert és az MI-t is az logika megértésében. -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chat-ben:** Kérdezz erről a mintáról: -> - „Hogyan adaptálnám a feladatvégrehajtás mintát hosszú futású műveletekhez?” -> - „Mik a legjobb gyakorlatok az eszköz előszövegek strukturálásához éles alkalmazásokban?” -> - „Hogyan tudok megjeleníteni köztes előrehaladási frissítéseket egy felhasználói felületen?” +A Chain-of-Thought prompting kifejezetten kéri a modellt, hogy mutassa meg érvelési folyamatát, ami növeli a pontosságot összetett feladatoknál. A lépésenkénti bontás segíti az embereket és az AI-t is az értelem megértésében. -Az alábbi ábra szemlélteti ezt a Tervezés → Végrehajtás → Összefoglalás munkafolyamatot. +> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Csevegéssel:** Kérdezz erről a mintáról: +> - „Hogyan alakítanám át a feladat-végrehajtási mintát hosszú ideig futó műveletekre?” +> - „Mik a legjobb gyakorlatok eszköz-előszavak strukturálására éles alkalmazásokban?” +> - „Hogyan tudok rögzíteni és megjeleníteni köztes előrehaladási állapotokat egy UI-ban?” -Feladatvégrehajtási Minta +Az alábbi diagram illusztrálja a Terv → Végrehajtás → Összefoglalás munkafolyamatot. -*Tervezés → Végrehajtás → Összefoglalás munkafolyamat többlépéses feladatokhoz* +Task Execution Pattern -**Önreflektáló Kód** - Termelési minőségű kódgeneráláshoz. A modell a gyártási szabványoknak megfelelő, hibakezeléssel ellátott kódot hoz létre. Használd új funkciók vagy szolgáltatások építésére. +*Terv → Végrehajtás → Összefoglalás munkafolyamat többlépéses feladatokhoz* + +**Önreflektáló kód** - Termelési minőségű kód generálásához. A modell termelési szabványok szerint generál kódot megfelelő hibakezeléssel. Használd új funkciók vagy szolgáltatások fejlesztésénél. ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -Az alábbi ábra mutatja ezt az iteratív fejlesztési ciklust — generálás, értékelés, gyengeségek felismerése, majd finomítás, amíg a kód megfelel a gyártási szabványoknak. -Önreflexiós Ciklus +Az alábbi diagram ezt az iteratív fejlesztési ciklust mutatja be — generálás, értékelés, gyengeségek azonosítása és finomítás, amíg a kód megfelel a termelési szabványoknak. + +Self-Reflection Cycle -*Iteratív fejlesztési ciklus - generálás, értékelés, problémák felismerése, javítás, ismétlés* +*Iteratív fejlesztési ciklus - generálás, értékelés, problémák azonosítása, javítás, ismétlés* -**Strukturált Elemzés** - Következetes értékeléshez. A modell előre meghatározott keretrendszer szerint vizsgálja a kódot (helyesség, gyakorlatok, teljesítmény, biztonság, karbantarthatóság). Használd kódáttekintésekhez vagy minőségértékelésekhez. +**Strukturált elemzés** - Következetes értékeléshez. A modell egy rögzített keretrendszerrel vizsgálja a kódot (helyesség, gyakorlatok, teljesítmény, biztonság, fenntarthatóság). Használd kódellenőrzéshez vagy minőségellenőrzéshez. ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chat-ben:** Kérdezz strukturált elemzésről: -> - „Hogyan szabhatom testre az elemzési keretrendszert különféle kódáttekintésekhez?” -> - „Mi a legjobb módja a strukturált kimenet feldolgozásának programozottan?” -> - „Hogyan biztosítom a következetes súlyossági szinteket különböző áttekintési üléseken?” -Az alábbi ábra mutatja, hogyan szervezi ez a strukturált keretrendszer a kódáttekintést következetes kategóriákba súlyossági szintekkel. +> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Csevegéssel:** Kérdezz a strukturált elemzésről: +> - „Hogyan testre szabhatom az elemzési keretrendszert különböző kódellenőrzési típusokra?” +> - „Mi a legjobb módja a strukturált kimenet programozott feldolgozásának és feldolgozásának?” +> - „Hogyan biztosíthatom a következetes súlyossági szinteket különböző ellenőrzési ülések között?” -Strukturált Elemzési Minta +Az alábbi diagram bemutatja, hogyan szervezi ezt a strukturált keretrendszer egy kódellenőrzést következetes kategóriákba súlyossági szintekkel. -*Következetes kódáttekintési keretrendszer súlyossági szintekkel* +Structured Analysis Pattern -**Többkörös Csevegés** - Olyan beszélgetésekhez, amelyeknek kontextusra van szükségük. A modell emlékszik az előző üzenetekre és épít rájuk. Használd interaktív segítségnyújtó ülésekhez vagy komplex kérdés-válasz helyzetekhez. +*Következetes kódellenőrzések keretrendszere súlyossági szintekkel* + +**Többfordulós csevegés** - Kontextust igénylő beszélgetésekhez. A modell emlékszik az előző üzenetekre és azokra épít. Használd interaktív segítségnyújtó vagy összetett kérdés-felelet alkalmakhoz. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -Az alábbi ábra szemlélteti, hogyan halmozódik fel a beszélgetési kontextus minden körrel, és hogyan viszonyul ez a modell token limitjéhez. -Kontextus Memória +Az alábbi diagram szemlélteti, hogyan halmozódik fel a beszélgetés kontextusa fordulóról fordulóra, és hogyan kapcsolódik a modell token-korlátjához. + +Context Memory -*Hogyan halmozódik fel a beszélgetési kontextus többszöri körök alatt, amíg eléri a token korlátot* -**Lépésről-lépésre gondolkodás** – Látható logikát igénylő problémák esetén. A modell minden lépéshez expliciten bemutatja az okfejtést. Használd ezt matematikai problémákhoz, logikai rejtvényekhez, vagy amikor meg kell értened a gondolkodási folyamatot. +*Hogyan gyűlik össze a beszélgetés kontextusa több fordulón át a token-korlátig* + +**Lépésről lépésre való érvelés** - Látható logikát igénylő problémákhoz. A modell minden lépésnél explicit érvelést mutat. Használd matek problémákhoz, logikai rejtvényekhez, vagy amikor meg kell értened a gondolkodási folyamatot. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Az alábbi ábra bemutatja, hogyan bontja a modell a problémákat explicit, számozott logikai lépésekre. - -Lépésről-lépésre minta +Az alábbi diagram bemutatja, hogyan bontja a modell a problémákat explicit, számozott logikai lépésekre. -*Problémák explicit logikai lépésekre bontása* +Step-by-Step Pattern +*Problémák lebontása kifejezett logikai lépésekre* -**Korlátozott kimenet** – Specifikus formátumkövetelményekkel bíró válaszokhoz. A modell szigorúan követi a formátum- és hosszúságszabályokat. Használd összefoglalókhoz vagy precíz kimenetstruktúrát igénylő esetekben. +**Korlátozott kimenet** – Olyan válaszokhoz, amelyeknek specifikus formátum- és hosszúságkövetelményük van. A modell szigorúan követi a formátum és hosszúság szabályait. Használd ezt összefoglalókhoz vagy ha pontos kimeneti szerkezetre van szükséged. ```java String prompt = """ @@ -420,21 +420,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -A következő ábra bemutatja, hogyan irányítják a korlátok a modellt, hogy szigorúan az előírt formátum- és hosszúságszabályokat kövesse. +Az alábbi diagram bemutatja, hogyan irányítják a korlátozások a modellt, hogy olyan kimenetet készítsen, amely szigorúan megfelel a formátum- és hosszúsági követelményeknek. -Korlátozott kimenet minta +Constrained Output Pattern -*Specifikus formátum, hossz és struktúra követelményének érvényesítése* +*Speciális formátum-, hosszúsági és szerkezeti követelmények érvényesítése* -## A alkalmazás futtatása +## Az alkalmazás futtatása **Telepítés ellenőrzése:** -Győződj meg róla, hogy a `.env` fájl létezik a gyökérkönyvtárban az Azure hitelesítő adatokkal (amely a 01-es modulban készült). Futtasd ezt a modul könyvtárából (`02-prompt-engineering/`): +Győződj meg róla, hogy a `.env` fájl létezik a gyökérkönyvtárban az Azure hitelesítési adatokkal (amelyet az 01-es modul során hoztál létre). Futtasd ezt a modul könyvtárából (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Meg kell jelenítenie az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket +cat ../.env # Meg kell mutatnia az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket ``` **PowerShell:** @@ -442,27 +442,27 @@ cat ../.env # Meg kell jelenítenie az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYME Get-Content ..\.env # Meg kell jelenítenie az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket ``` -**Indítsd el az alkalmazást:** +**Az alkalmazás indítása:** -> **Megjegyzés:** Ha már elindítottad az összes alkalmazást a gyökérkönyvtárból `./start-all.sh` segítségével (ahogy az 01-es modul leírja), ez a modul már fut a 8083-as porton. Ekkor kihagyhatod az alábbi indítási parancsokat, és közvetlenül a http://localhost:8083 oldalra léphetsz. +> **Megjegyzés:** Ha már indítottad az összes alkalmazást a `./start-all.sh` használatával a gyökérkönyvtárból (ahogy az az 01-es modulban le van írva), akkor ez a modul már fut a 8083-as porton. Átugorhatod az alábbi indító parancsokat, és közvetlenül elmehetsz a http://localhost:8083 oldalra. -**1. lehetőség: Spring Boot Dashboard használata (Ajánlott VS Code felhasználóknak)** +**1. lehetőség: Spring Boot Dashboard használata (ajánlott VS Code felhasználóknak)** -A fejlesztői környezet tartalmazza a Spring Boot Dashboard bővítményt, ami vizuális felületet nyújt az összes Spring Boot alkalmazás kezelésére. A VS Code bal oldali tevékenységsávjában találod meg (a Spring Boot ikon alapján). +A fejlesztői konténer tartalmazza a Spring Boot Dashboard bővítményt, amely vizuális felületet biztosít az összes Spring Boot alkalmazás kezelésére. Megtalálod a VS Code bal oldali Művelet sávjában (keresd a Spring Boot ikont). -A Spring Boot Dashboardból: -- Megtekintheted az összes elérhető Spring Boot alkalmazást a munkaterületen -- Egy kattintással indíthatsz vagy állíthatsz le alkalmazásokat -- Valós időben nézheted az alkalmazás naplóit -- Figyelemmel kísérheted az alkalmazás állapotát +A Spring Boot Dashboard-ról: +- Az összes elérhető Spring Boot alkalmazást látod a munkaterületen +- Egy kattintással indíthatsz/leállíthatsz alkalmazásokat +- Valós időben nézheted az alkalmazások naplóit +- Figyelemmel kísérheted az alkalmazások állapotát -Egyszerűen kattints a lejátszás gombra a "prompt-engineering" modul mellett a modul indításához, vagy indíts el egyszerre minden modult. +Egyszerűen kattints a lejátszás gombra a "prompt-engineering" mellett az adott modul indításához, vagy indítsd el egyszerre az összes modult. Spring Boot Dashboard -*A Spring Boot Dashboard a VS Code-ban — indítsd, állítsd le és monitorozd az összes modult egy helyről* +*A Spring Boot Dashboard a VS Code-ban — indítsd, állítsd le és figyeld az összes modult egy helyről* -**2. lehetőség: Shell szkriptek használata** +**2. lehetőség: Shell script-ek használata** Indítsd el az összes webalkalmazást (01-04 modulok): @@ -478,7 +478,7 @@ cd .. # A gyökérkönyvtárból .\start-all.ps1 ``` -Vagy indítsd csak ezt a modult: +Vagy indítsd el csak ezt a modult: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Mindkét szkript automatikusan betölti a környezeti változókat a gyökér `.env` fájlból, és ha nem léteznek, legyártja a JAR fájlokat. +Mindkét script automatikusan betölti a root `.env` fájlban lévő környezeti változókat, és felépíti a JAR fájlokat, ha még nem léteznek. -> **Megjegyzés:** Ha inkább manuálisan szeretnéd buildelni az összes modult indítás előtt: +> **Megjegyzés:** Ha manuálisan szeretnéd buildelni az összes modult az indítás előtt: > > **Bash:** > ```bash @@ -508,7 +508,7 @@ Mindkét szkript automatikusan betölti a környezeti változókat a gyökér `. > mvn clean package -DskipTests > ``` -Nyisd meg böngészőben a http://localhost:8083 címet. +Nyisd meg a böngésződben a http://localhost:8083 címet. **Leállításhoz:** @@ -523,74 +523,74 @@ cd .. && ./stop-all.sh # Minden modul ```powershell .\stop.ps1 # Csak ez a modul # Vagy -cd ..; .\stop-all.ps1 # Az összes modul +cd ..; .\stop-all.ps1 # Minden modul ``` ## Alkalmazás képernyőképek -Itt a prompt engineering modul fő felülete, ahol egyszerre próbálhatod ki mind a nyolc mintát. +Íme a prompt engineering modul fő kezelőfelülete, ahol egyszerre kísérletezhetsz a nyolc minta mindegyikével. Dashboard Home -*A fő dashboard, amely az összes 8 prompt mérnöki mintát mutatja jellemzőikkel és használati eseteikkel* +*A fő műszerfal, mely az összes 8 prompt engineering mintát mutatja jellemzőikkel és használati eseteikkel együtt* -## Minták felfedezése +## A minták felfedezése -A webes felület lehetővé teszi a különböző promptolási stratégiák kipróbálását. Mindegyik minta más-más problémára ad választ – próbáld ki, hogy lásd, mikor működik jól melyik megközelítés. +A webes felület lehetővé teszi, hogy különböző promptolási stratégiákkal kísérletezz. Minden minta más problémát old meg – próbáld ki őket, hogy lásd, mikor működik jól egy-egy megközelítés. -> **Megjegyzés: Streaming és nem streaming** — Minden mintalapon két gombot találsz: **🔴 Stream Response (Live)** és egy **nem streaming** opciót. A streaming Server-Sent Events (SSE) használatával azonnal megjeleníti azokat a tokeneket, amelyeket a modell generál, így az előrehaladást közvetlenül láthatod. A nem streaming opció megvárja a teljes választ, mielőtt megjelenítené azt. Mély okfejtést igénylő promptoknál (például High Eagerness, Self-Reflecting Code) a nem streaming hívás nagyon hosszú ideig is eltarthat — akár percekig — látványos visszajelzés nélkül. **Használj streaminget, amikor összetett promptokkal kísérletezel**, így látod a modell működését és elkerülöd azt a benyomást, hogy a kérés időtúllépett. -> -> **Megjegyzés: Böngészőkövetelmény** — A streaming funkció a Fetch Streams API-t (`response.body.getReader()`) használja, ami teljes böngészőt igényel (Chrome, Edge, Firefox, Safari). Ez **nem** működik a VS Code beépített Simple Browserében, mert annak webnézete nem támogatja a ReadableStream API-t. Ha Simple Brosert használsz, a nem streaming gombok továbbra is normálisan működnek — csak a streaming gombokat érinti ez a korlátozás. A teljes élményhez külső böngészőben nyisd meg a `http://localhost:8083` címet. +> **Megjegyzés: Streaming vagy nem streaming** — Minden mintának van két gombja: **🔴 Stream Response (Live)** és egy **Nem streaming** opció. A streaming a Server-Sent Events (SSE) használatával valós időben mutatja a tokeneket, miközben a modell generálja őket, így azonnal látod a folyamatot. A nem streaming opció megvárja az egész választ, mielőtt megjeleníti. Mély gondolkodást igénylő promptoknál (pl. High Eagerness, Self-Reflecting Code) a nem streaming hívás nagyon hosszú ideig is eltarthat – néha percekig – látható visszajelzés nélkül. **Komplex promptok teszteléséhez használj streaminget**, hogy lásd a modell működését, és ne tűnjön úgy, mintha időtúllépés történt volna. +> +> **Megjegyzés: Böngésző követelmény** — A streaming funkció a Fetch Streams API-t használja (`response.body.getReader()`), ami teljes böngészőt igényel (Chrome, Edge, Firefox, Safari). Nem működik a VS Code beépített Simple Browser-ében, mivel annak webnézetében nem támogatott a ReadableStream API. Ha a Simple Browser-t használod, a nem streaming gombok továbbra is működnek rendesen – csak a streaming gombokat érinti. A teljes élményért nyisd meg `http://localhost:8083` külső böngészőben. ### Alacsony vs Magas lelkesedés -Tegyél fel egy egyszerű kérdést, például "Mi a 15%-a 200-nak?" Alacsony lelkesedéssel. Azonnali, közvetlen választ kapsz. Most kérdezz valami bonyolultabbat, például "Tervezzen meg egy caching stratégiát egy nagy forgalmú API-hoz" Magas lelkesedéssel. Kattints a **🔴 Stream Response (Live)** gombra, és nézd, miként jelenik meg részletes gondolkodás lépésről lépésre tokenenként. Ugyanaz a modell, ugyanaz a kérdés felépítés – de a prompt megmondja, mennyi gondolkodást végezzen. +Tegyél fel egy egyszerű kérdést, például „Mi a 15%-a 200-nak?” Alacsony lelkesedéssel azonnali, közvetlen választ kapsz. Most tegyél fel egy összetettebb kérdést, például „Tervezzen gyorsítótárazási stratégiát egy nagyforgalmú API-hoz” Magas lelkesedéssel. Kattints a **🔴 Stream Response (Live)**-re, és nézd, ahogy a modell részletes gondolkodása tokenenként megjelenik. Ugyanaz a modell, ugyanaz a kérdésfelépítés – csak a prompt határozza meg, mennyit gondolkodjon. -### Feladatvégrehajtás (Eszköz bevezetések) +### Feladatteljesítés (Eszköz bevezetők) -Többlépcsős munkafolyamatoknál előnyös az előzetes tervezés és a folyamat narrálása. A modell ismerteti, mit fog csinálni, lépésről lépésre mesél, majd összegzi az eredményeket. +A többlépéses munkafolyamatok előnyhöz jutnak az előzetes tervezés és az előrehaladás narrációja miatt. A modell vázolja, mit fog csinálni, narrálja az egyes lépéseket, majd összefoglalja az eredményeket. -### Önreflektáló kód +### Önszemléletű kód -Próbáld ki a "Hozz létre egy email érvényesítő szolgáltatást" promptot. Ahelyett, hogy csak kódot generálna és megállna, a modell generál, értékel minőségi kritériumok alapján, azonosít gyengeségeket, majd javít. Láthatod, ahogy iterál, amíg a kód megfelel a termelési szabványoknak. +Próbáld ki a „Hozz létre egy e-mail érvényesítő szolgáltatást” kérést. Ahelyett, hogy csak kódot generálna, és abbahagyná, a modell generál, értékel minőségi kritériumok alapján, azonosítja a gyengeségeket, majd javít. Látni fogod, hogy iterál addig, amíg a kód megfelel a termelési követelményeknek. ### Strukturált elemzés -Kódáttekintésekhez következetes értékelési keretek kellenek. A modell a kódot fix kategóriák szerint elemzi (helyesség, gyakorlatok, teljesítmény, biztonság), súlyossági szintekkel. +A kódáttekintésekhez konzisztens értékelési keretrendszerek szükségesek. A modell rögzített kategóriák (helyesség, gyakorlatok, teljesítmény, biztonság) és súlyossági szintek alapján elemzi a kódot. -### Többkörös csevegés +### Többfordulós chat -Kérdezd meg: "Mi az a Spring Boot?" majd közvetlenül kövesd azzal: "Mutass példát." A modell emlékszik az első kérdésre, és egy Spring Boot példát ad. Memória nélkül a második kérdés túl homályos lenne. +Kérdezd meg: „Mi az a Spring Boot?”, majd azonnal kérd meg: „Mutass egy példát”. A modell emlékszik az első kérdésedre és egy Spring Boot példát ad speciálisan. Memória nélkül a második kérdés túl általános lenne. -### Lépésről-lépésre gondolkodás +### Lépésről lépésre történő érvelés -Válassz egy matekfeladatot, és próbáld ki egyszerre a Lépésről-lépésre gondolkodást és az Alacsony lelkesedést. Az alacsony lelkesedés gyorsan csak a választ adja meg – gyors, de átláthatatlan. A lépésről lépésre bemutatja minden számítást és döntést. +Válassz egy matematikai problémát, és próbáld ki mind a Lépésről lépésre érvelést, mind az Alacsony lelkesedést. Az alacsony lelkesedés csak megadja a választ – gyors, de kevésbé átlátható. A lépésről lépésre megmutatja minden számítást és döntést. ### Korlátozott kimenet -Amikor meghatározott formátumra vagy szóközszámra van szükség, ez a minta szigorúan érvényesíti az előírásokat. Próbálj meg egy pontosan 100 szóból álló összefoglalót generálni felsorolásos formában. +Ha specifikus formátumra vagy szószámra van szükséged, ez a minta szigorúan betartatja ezeket. Próbálj meg egy pontosan 100 szóból álló listás összefoglalót generálni. ## Amit valójában tanulsz -**Az okfejtés erőfeszítése mindent megváltoztat** +**Az érvelési erőfeszítés mindent megváltoztat** -A GPT-5.2 lehetővé teszi, hogy a promptok által szabályozd a számítási erőfeszítést. Az alacsony erőfeszítés gyors válaszokat eredményez minimális feltárással. A magas erőfeszítés azt jelenti, hogy a modell mélyen és alaposan gondolkodik. Megtanulod az erőfeszítést a feladat komplexitásához igazítani – ne pazarold az időt egyszerű kérdésekre, de ne siesd el a bonyolult döntéseket sem. +A GPT-5.2 lehetővé teszi, hogy a promptjaidon keresztül szabályozd a számítási erőfeszítést. Az alacsony erőfeszítés gyors válaszokat jelent minimális feltárással. A magas erőfeszítés azt jelenti, hogy a modell időt szán a mély gondolkodásra. Megtanulod, hogyan igazítsd az erőfeszítést a feladat összetettségéhez – ne pazarold az időt egyszerű kérdésekre, de ne siess el összetett döntéseket se. -**A struktúra irányítja a viselkedést** +**A szerkezet szabályozza a viselkedést** -Észrevetted az XML címkéket a promptokban? Nem dekoratívak. A modellek a strukturált utasításokat megbízhatóbban követik, mint az szabad szöveget. Többlépcsős folyamatokhoz vagy összetett logikához a struktúra segít a modellnek követni, hol tart és mi következik. Az alábbi ábra egy jól strukturált promptot bont le, bemutatva, hogyan rendezi az utasításokat XML-stílusú címkék, mint ``, ``, ``, ``, és ``. +Észrevetted a promptokban szereplő XML címkéket? Nem csupán díszek. A modellek megbízhatóbban követik a strukturált utasításokat, mint a szabad szöveget. Amikor többlépéses folyamatokra vagy összetett logikára van szükség, a szerkezet segít a modellnek követni, hol tart, és mi következik. Az alábbi diagram lebontja egy jól strukturált prompt felépítését, és megmutatja, hogyan szervezik az utasításokat a ``, ``, ``, `` és `` címkék világos szakaszokra. -Prompt szerkezete +Prompt Structure -*Egy jól strukturált prompt anatómiája tiszta szakaszokkal és XML-stílusú szervezéssel* +*A jól strukturált prompt anatómiája világos szakaszokkal és XML-stílusú szervezéssel* **Minőség önértékeléssel** -Az önreflektáló minták úgy működnek, hogy a minőségi kritériumokat explicit módon megadják. Ahelyett, hogy remélnéd, hogy a modell "jól csinálja", pontosan megmondod neki, mit jelent a "helyes": logikai helyesség, hibakezelés, teljesítmény, biztonság. A modell így képes saját kimenetét értékelni és javítani. Ez előállításból folyamatot csinál. +Az önreflektáló minták úgy működnek, hogy a minőségi kritériumokat explicit módon megadják. Ahelyett, hogy csak remélnéd, hogy a modell "jól csinálja", pontosan megmondod neki, mit jelent a "jól": helyes logika, hibakezelés, teljesítmény, biztonság. A modell így értékelni tudja saját kimenetét és javítani. Ez a kódgenerálást lotériából folyamatba alakítja. **A kontextus véges** -A többkörös beszélgetések úgy működnek, hogy a lekérdezéshez mellékelik az üzenet előzményeit. Viszont van korlát – minden modellhez van maximális token-szám. Ahogy nő a beszélgetés, stratégiák kellenek, hogy a releváns kontextust megtartsd anélkül, hogy túllépnéd a plafont. Ez a modul megmutatja, hogyan működik a memória; később megtanulod, mikor foglalj össze, mikor felejts, és mikor hívj elő. +A többfordulós beszélgetések úgy működnek, hogy minden kéréshez tartalmazzák az üzenettörténetet. De van egy határ – minden modellnek maximális token száma van. Ahogy a beszélgetések nőnek, stratégiákra lesz szükséged, hogy a releváns kontextust megőrizd anélkül, hogy elérnéd a korlátot. Ez a modul megmutatja, hogyan működik a memória; később megtanulod, mikor foglalj össze, mikor felejts és mikor kérj vissza információt. ## Következő lépések @@ -604,5 +604,5 @@ A többkörös beszélgetések úgy működnek, hogy a lekérdezéshez mellékel **Jogi nyilatkozat**: -Ez a dokumentum az [Co-op Translator](https://github.com/Azure/co-op-translator) AI fordító szolgáltatásával készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az eredeti nyelven tekintendő hiteles forrásnak. Fontos információk esetén szakmai emberi fordítást javasolunk. Nem vállalunk felelősséget a fordítás használatából eredő félreértésekért vagy helytelen értelmezésekért. +Ez a dokumentum az AI fordítási szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Fontos információk esetén professzionális emberi fordítást javasolunk. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely ebből a fordításból ered. \ No newline at end of file diff --git a/translations/hu/03-rag/README.md b/translations/hu/03-rag/README.md index cb4c2e890..d4e9c2fbb 100644 --- a/translations/hu/03-rag/README.md +++ b/translations/hu/03-rag/README.md @@ -1,144 +1,143 @@ -# 03. modul: RAG (Retrieval-Augmented Generation) +# Modul 03: RAG (Retrieval-Augmented Generation) ## Tartalomjegyzék -- [Videós bemutató](../../../03-rag) -- [Amit megtanulsz](../../../03-rag) -- [Előfeltételek](../../../03-rag) -- [A RAG megértése](../../../03-rag) - - [Melyik RAG megközelítést használja ez az oktatóanyag?](../../../03-rag) -- [Hogyan működik](../../../03-rag) - - [Dokumentumfeldolgozás](../../../03-rag) - - [Beágyazások létrehozása](../../../03-rag) - - [Szemantikus keresés](../../../03-rag) - - [Válaszgenerálás](../../../03-rag) -- [Az alkalmazás futtatása](../../../03-rag) -- [Az alkalmazás használata](../../../03-rag) - - [Dokumentum feltöltése](../../../03-rag) - - [Kérdések feltevése](../../../03-rag) - - [Hivatkozások ellenőrzése](../../../03-rag) - - [Kísérletezés kérdésekkel](../../../03-rag) -- [Kulcsfogalmak](../../../03-rag) - - [Darabolási stratégia](../../../03-rag) - - [Hasonlósági pontszámok](../../../03-rag) - - [Memóriában tárolás](../../../03-rag) - - [Kontekstuális ablak kezelése](../../../03-rag) -- [Mikor fontos a RAG](../../../03-rag) -- [Következő lépések](../../../03-rag) +- [Videós bemutató](#videós-bemutató) +- [Mit fogsz megtanulni](#mit-fogsz-megtanulni) +- [Előfeltételek](#előfeltételek) +- [A RAG megértése](#a-rag-megértése) + - [Melyik RAG megközelítést használja ez a bemutató?](#melyik-rag-megközelítést-használja-ez-a-bemutató) +- [Hogyan működik](#hogyan-működik) + - [Dokumentumfeldolgozás](#dokumentumfeldolgozás) + - [Beágyazások készítése](#beágyazások-készítése) + - [Szemantikus keresés](#szemantikus-keresés) + - [Válaszgenerálás](#válaszgenerálás) +- [Az alkalmazás futtatása](#az-alkalmazás-futtatása) +- [Az alkalmazás használata](#az-alkalmazás-használata) + - [Dokumentum feltöltése](#dokumentum-feltöltése) + - [Kérdések feltevése](#kérdések-feltevése) + - [Forrás hivatkozások ellenőrzése](#forráshivatkozások-ellenőrzése) + - [Kísérletezés a kérdésekkel](#kísérletezz-a-kérdésekkel) +- [Kulcsfogalmak](#kulcsfogalmak) + - [Darabolási stratégia](#szeletelési-stratégia) + - [Hasonlósági pontszámok](#hasonlósági-pontszámok) + - [Memóriában tárolás](#memóriában-tárolás) + - [Kontextusablak kezelése](#kontextusablak-kezelése) +- [Mikor fontos a RAG](#mikor-fontos-a-rag) +- [Következő lépések](#következő-lépések) ## Videós bemutató -Nézd meg ezt az élő előadást, amely elmagyarázza, hogyan kezdhetsz neki ennek a modulnak: +Nézd meg ezt az élő adást, amely elmagyarázza, hogyan kezdhetsz neki ennek a modulnak: -RAG with LangChain4j - Live Session +RAG with LangChain4j - Élő adás -## Amit megtanulsz +## Mit fogsz megtanulni -Az előző modulokban megtanultad, hogyan folytass beszélgetést a mesterséges intelligenciával és hogyan építsd fel hatékonyan a promptokat. De van egy alapvető korlát: a nyelvi modellek csak azt tudják, amit a tanításuk során megtanultak. Nem tudnak válaszolni olyan kérdésekre, melyek céged szabályzataira, projekt dokumentációjára vagy olyan információkra vonatkoznak, amik nem szerepeltek a betanításukban. +Az előző modulokban megtanultad, hogyan folytass beszélgetéseket az MI-vel, és hogyan strukturáld hatékonyan a parancsaidat. De van egy alapvető korlát: a nyelvi modellek csak azt tudják, amit a tanítási folyamat során megtanultak. Nem képesek válaszolni a céges szabályzataiddal, a projekt dokumentációddal vagy bármilyen olyan információval kapcsolatos kérdésekre, amit nem tanítottak nekik. -A RAG (Retrieval-Augmented Generation) megoldja ezt a problémát. Ahelyett, hogy megpróbálnád megtanítani a modellnek a saját adataidat (ami drága és nem praktikus), lehetővé teszed számára, hogy átkutassa azokat a dokumentumaidat. Amikor valaki kérdez, a rendszer megtalálja a releváns információt, és beilleszti azt a promptba. A modell úgy válaszol, hogy figyelembe veszi a lekért kontextust. +A RAG (Retrieval-Augmented Generation) megoldja ezt a problémát. Ahelyett, hogy megpróbálnád megtanítani a modellnek az információidat (ami költséges és nem praktikus), képessé teszed arra, hogy a dokumentumaid között keressen. Ha valaki kérdést tesz fel, a rendszer megtalálja a releváns információkat és beépíti azokat a promptba. A modell pedig ezen visszakeresett kontextus alapján válaszol. -Gondolj a RAG-ra úgy, mint egy referencia könyvtárra a modell számára. Ha kérdezel valamit, a rendszer: +Gondolj a RAG-re úgy, mint egy hivatkozási könyvtár biztosítására a modell számára. Ha kérdezel valamit, a rendszer: -1. **Felhasználói kérdés** – felteszed a kérdést -2. **Beágyazás** – a kérdés vektorrá alakul -3. **Vektoros keresés** – hasonló dokumentumdarabokat talál -4. **Kontextus összeszerelése** – a releváns darabokat hozzáadja a prompthoz -5. **Válasz** – az LLM a kontextus alapján válaszol +1. **Felhasználói kérdés** – Feltesszük a kérdést +2. **Beágyazás** – A kérdés vektorosításra kerül +3. **Vektorkeresés** – Megkeresi a hasonló dokumentumdarabokat +4. **Kontextus összeállítása** – A releváns darabokat hozzáadja a prompthoz +5. **Válasz** – Az LLM a kontextus alapján válaszol -Ezáltal a modell válaszai a te valós adataidra alapozódnak, nem csak a betanítási tudásra vagy kitalált válaszokra. +Ez alapozza meg a modell válaszait a tényleges adataidra, ahelyett hogy a tanítási tudására hagyatkozna vagy találgatna válaszokat. ## Előfeltételek -- Befejezett [00. modul – Gyors kezdés](../00-quick-start/README.md) (a későbbiekben hivatkozott Easy RAG példa miatt) -- Befejezett [01. modul – Bevezetés](../01-introduction/README.md) (Azure OpenAI erőforrások telepítve, beleértve a `text-embedding-3-small` beágyazási modellt) -- `.env` fájl a gyökérkönyvtárban Azure-hitelesítő adatokkal (a Module 01-ben futtatott `azd up` által létrehozva) +- Befejezett [01-es modul - Bevezetés](../01-introduction/README.md) (az Azure OpenAI erőforrások telepítve, beleértve a `text-embedding-3-small` beágyazási modellt) +- `.env` fájl a gyökérkönyvtárban Azure hitelesítő adatokkal (a 01-es modulban a `azd up` parancs hozza létre) -> **Megjegyzés:** Ha nem fejezted be az 01. modult, előbb kövesd ott a telepítési utasításokat. Az `azd up` parancs telepíti mind a GPT csevegő modellt, mind a beágyazó modellt, amelyet ez a modul használ. +> **Megjegyzés:** Ha még nem végezted el az 01-es modult, először kövesd ott a telepítési útmutatót. Az `azd up` parancs telepíti mind a GPT chat modellt, mind a beágyazási modellt, amelyet ez a modul használ. ## A RAG megértése -Az alábbi ábra szemlélteti az alapelvet: a modell tanítási adatára támaszkodás helyett a RAG egy referencia könyvtárat ad neki a dokumentumaidról, amit minden válaszgenerálás előtt felkereshet. +Az alábbi ábra szemlélteti az alap koncepciót: ahelyett, hogy csak a modell tanítási adataira hagyatkozna, a RAG egy hivatkozási könyvtárt ad neki a dokumentumaidról, hogy minden válaszadás előtt konzultálhasson velük. -What is RAG +Mi az a RAG -*Ez az ábra megmutatja a különbséget egy hagyományos LLM (ami a tanítási adaton alapuló találgatást végez) és a RAG-alapú LLM között (ami először a dokumentumaidat nézi meg).* +*Ez az ábra bemutatja a különbséget a hagyományos LLM (ami a tanítási adatból tippel) és a RAG-megerősített LLM között (ami először megkeresi a dokumentumaidat).* -Íme, hogyan kapcsolódnak össze a részek az elejétől a végéig. Egy felhasználói kérdés négy lépésen megy keresztül — beágyazás, vektoros keresés, kontextus összeszerelés és válaszgenerálás — mindegyik az előzőre épít: +Így kapcsolódnak össze az egyes részek végponttól végpontig. A felhasználói kérdés négy lépésen megy keresztül — beágyazás, vektorkeresés, kontextus összeállítás, válaszgenerálás — mindegyik az előzőre épül: -RAG Architecture +RAG architektúra -*Ez az ábra megmutatja a teljes RAG folyamatot — a felhasználói kérdés beágyazáson, vektor keresésen, kontextus összeszerelésen, majd válaszgeneráláson megy keresztül.* +*Ez az ábra a RAG végponttól végpontig terjedő folyamatát mutatja — a felhasználói kérdés a beágyazáson, vektorkeresésen, kontextus összeállításon és válaszgeneráláson megy keresztül.* -A modul többi része részletesen végigvezeti az egyes lépéseket, futtatható és módosítható kóddal. +A modul további része részletesen végigvezet az egyes szakaszokon, futtatható és módosítható kóddal. -### Melyik RAG megközelítést használja ez az oktatóanyag? +### Melyik RAG megközelítést használja ez a bemutató? -A LangChain4j háromféleképpen kínálja a RAG megvalósítását, mindegyik más absztrakciós szinten. Az alábbi ábra összehasonlítja őket egymás mellett: +A LangChain4j három módot kínál a RAG implementálására, mindegyik más szintű absztrakciót nyújt. Az alábbi ábra ezeket hasonlítja össze egymás mellett: -Three RAG Approaches in LangChain4j +Három RAG megközelítés a LangChain4j-ben -*Ez az ábra összeveti a három LangChain4j RAG megközelítést — Egyszerű, Natív és Fejlett — megmutatva fő komponenseiket és az alkalmazásukhoz javasolt eseteket.* +*Ez az ábra összehasonlítja a három LangChain4j RAG megközelítést – Easy, Native és Advanced – bemutatva kulcsfontosságú összetevőiket és az alkalmazási területüket.* -| Megközelítés | Mit csinál | Hátrány | +| Megközelítés | Mit csinál | Kompromisszum | |---|---|---| -| **Egyszerű RAG** | Minden mind automatikusan kapcsolódik az `AiServices` és a `ContentRetriever` segítségével. Egy interfészt annotálsz, retrievert csatolsz, és a LangChain4j kezeli a beágyazást, keresést és a prompt összeállítását a háttérben. | Minimális kód, de nem látod mi történik lépésről lépésre. | -| **Natív RAG** | Te hívod a beágyazó modellt, keresed az áruházban, építed a promptot és generálod a válaszokat — minden egyes lépés explicit módon. | Több kód, de minden lépés látható és módosítható. | -| **Fejlett RAG** | A `RetrievalAugmentor` keretrendszert használja, csatlakoztatható kérdés transzformerekkel, routerekkel, újrarangsorolók és tartalombeesztő elemekkel gyártási szintű munkafolyamatokhoz. | Maximális rugalmasság, de lényegesen nagyobb komplexitás. | +| **Easy RAG** | Automatikusan beköti az egészet az `AiServices` és a `ContentRetriever` segítségével. Egy interfészt annotálsz, hozzácsatolsz egy retrievert, a LangChain4j pedig mögöttesen kezeli a beágyazást, keresést és prompt összeállítást. | Minimális kód, de nem látod az egyes lépéseket. | +| **Native RAG** | Te magad hívod meg a beágyazási modellt, keresel az adattárban, építed össze a promptot és generálod a választ — lépésenként, expliciten. | Több kód, de minden lépés látható és módosítható. | +| **Advanced RAG** | A `RetrievalAugmentor` keretrendszert használja csatlakoztatható lekérdező transzformerekkel, routerekkel, újrarendezőkkel és tartalom injektorokkal produkciós minőségű csővezetékekhez. | Maximális rugalmasság, de jelentősen bonyolultabb. | -**Ez az oktatóanyag a Natív megközelítést használja.** A RAG folyamat minden lépése — a kérdés beágyazása, a vektoros tároló keresése, a kontextus összeszerelése és a válaszgenerálás — explicit módon ki van írva a [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) fájlban. Ez szándékos: tanulási forrásként fontosabb, hogy minden lépést lásd és megérts, mint hogy a kód minimális legyen. Ha már magabiztos vagy, hogyan illeszkednek össze az elemek, áttérhetsz az Egyszerű RAG-ra gyors prototípusokhoz vagy Fejlett RAG-ra gyártási rendszerekhez. +**Ez a bemutató a Native megközelítést használja.** A RAG csővezeték minden lépése — a lekérdezés beágyazása, a vektortár keresése, a kontextus összeállítása és a válasz generálása — egyértelműen ki van írva a [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) fájlban. Ez szándékos: tanulási erőforrásként fontosabb, hogy lásd és megértsd az összes lépést, mint hogy a kód minimális legyen. Ha már kényelmesen érted az összefüggéseket, léphetsz tovább az Easy RAG-re gyors prototípusokhoz vagy az Advanced RAG-re produkciós rendszerekhez. -> **💡 Már láttad az Egyszerű RAG működését?** A [Gyors kezdés modul](../00-quick-start/README.md) tartalmaz egy Dokumentum Kérdezz-Felelek példát ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), amely az Egyszerű RAG megközelítést használja — a LangChain4j automatikusan kezeli a beágyazást, keresést és prompt összeállítást. Ez a modul egy lépéssel tovább megy, és lebontja ezt a folyamatot, így láthatod és vezérelheted az egyes lépéseket magad. +> **💡 Kíváncsi vagy az Easy RAG-re?** A LangChain4j kínál egy *Easy RAG* megközelítést is, ahol az `AiServices` és a `ContentRetriever` automatikusan kezelik a beágyazást, keresést és prompt összeállítást. Ez a modul az explicitabb utat választja — a csővezetéket megnyitva, hogy te lásd és irányítsd az egyes lépéseket. -Az alábbi ábra szemlélteti az Egyszerű RAG folyamatot abból a Gyors kezdés példából. Figyeld meg, hogyan rejti el az `AiServices` és az `EmbeddingStoreContentRetriever` az egész komplexitást — betöltesz egy dokumentumot, csatolsz egy retrievert, és kapsz válaszokat. A Natív megközelítés ennek a rejtett folyamatnak a felbontása: +Az alábbi ábra az Easy RAG csővezetéket mutatja. Figyeld meg, hogy az `AiServices` és az `EmbeddingStoreContentRetriever` hogyan rejti el a teljes bonyolultságot — dokumentumot töltesz be, csatolsz retrievert és kapsz válaszokat. Ez a modul natív megközelítése azonban kinyitja a rejtett lépéseket: -Easy RAG Pipeline - LangChain4j +Easy RAG csővezeték - LangChain4j -*Ez az ábra az Egyszerű RAG folyamatot mutatja a `SimpleReaderDemo.java`-ból. Hasonlítsd össze a Natív megközeléssel, amit ebben a modulban használsz: az Egyszerű RAG elrejti a beágyazást, a keresést és a prompt összeállítást az `AiServices` és `ContentRetriever` mögött — feltöltesz egy dokumentumot, csatolsz egy retrievert és kapsz válaszokat. Ebben a modulban a Natív megközelítés felbontja ezt a folyamatot, így te hívhatod meg a lépéseket (beágyazás, keresés, kontextus összeszerelés, válaszgenerálás) saját magad, teljes láthatóságot és irányítást kapva.* +*Ez az ábra az Easy RAG csővezetéket ábrázolja. Hasonlítsd össze a natív megközeléssel, amit ebben a modulban használsz: az Easy RAG elrejti a beágyazást, visszakeresést és prompt összeállítást az `AiServices` és `ContentRetriever` mögött — dokumentumot töltesz be, hozzácsatolsz egy retrievert és kapsz válaszokat. A Natív megközelítés ezen modulban kinyitja a csővezetéket, így magad hívod az egyes lépéseket (beágyazás, keresés, kontextus összeállítás, generálás), teljes láthatóságot és kontrollt adva.* ## Hogyan működik -Ebben a modulban a RAG folyamat négy, egymás után futó lépésből áll, melyeket a rendszer minden kérdésnél lefuttat. Először egy feltöltött dokumentumot **feldolgoz és darabol** kisebb, kezelhető darabokra. Ezeket a darabokat aztán **vektoros beágyazásokká** alakítja és elmenti, hogy matematikailag összehasonlíthatók legyenek. Amikor megérkezik egy kérdés, a rendszer **szemantikus keresést** végez, hogy megtalálja a legrelevánsabb darabokat, majd ezeket a darabokat adja át kontextusként az LLM-nek a **válaszgeneráláshoz**. Az alábbi részeket végigvesszük kóddal és ábrákkal. Nézzük az első lépést. +Az ebben a modulban lévő RAG csővezeték négy egymást követő lépésből áll, amelyek lefutnak minden alkalommal, amikor egy felhasználó kérdést tesz fel. Először az feltöltött dokumentumot **feldolgozza és darabolja** kezelhető darabokra. Ezeket a darabokat aztán **vektor beágyazásokká** alakítja és eltárolja, hogy matematikailag össze lehessen hasonlítani őket. Amikor érkezik egy lekérdezés, a rendszer **szemantikus keresést** végez a legrelevánsabb darabok megtalálására, majd ezeket átadja kontextusként az LLM-nek a **válaszgenerálás**hez. Az alábbi szakaszok vezetik végig az egyes lépéseket valós kóddal és ábrákkal. Nézzük az első lépést. ### Dokumentumfeldolgozás [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Amikor feltöltesz egy dokumentumot, a rendszer feldolgozza (PDF vagy sima szöveg), hozzáad metaadatokat, mint például a fájlnév, majd darabokra bontja — kisebb részekre, amelyek kényelmesen beférnek a modell kontextusablakába. Ezek a darabok kissé átfedik egymást, hogy a határokon ne vesszen el fontos kontextus. +Amikor feltöltesz egy dokumentumot, a rendszer feldolgozza (PDF vagy sima szöveg), hozzácsatol metaadatokat, mint például a fájlnév, majd darabokra bontja — kisebb részekre, amelyek kényelmesen beleférnek a modell kontextusablakába. Ezek a darabok kicsit átfedik egymást, hogy ne vesszen el kontextus a határoknál. ```java -// A feltöltött fájl elemzése és becsomagolása LangChain4j Dokumentumba +// Elemezze a feltöltött fájlt, és csomagolja LangChain4j Dokumentumba Document document = Document.from(content, metadata); -// 300 tokenes darabokra bontás 30 tokenes átfedéssel +// Ossza 300 tokenes darabokra, 30 token átfedéssel DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Az alábbi ábra vizuálisan mutatja, hogyan működik ez. Figyeld meg, hogy minden darab megoszt néhány token-t a szomszédjaival — a 30 tokenes átfedés biztosítja, hogy ne vesszen el fontos kontextus a darabhatároknál: +Az alábbi ábra vizuálisan mutatja ennek működését. Figyeld meg, hogy minden darab egyes tokeneket megoszt a szomszédjaival — a 30 tokenes átfedés biztosítja, hogy ne vesszen el fontos kontextus a darabhatároknál: -Document Chunking +Dokumentum darabolása -*Ez az ábra egy dokumentum 300 tokenes darabokra bontását mutatja 30 tokenes átfedéssel, megőrizve a kontextust a darabhatároknál.* +*Ez az ábra egy dokumentum 300 tokenes darabokra bontását mutatja 30 token átfedéssel, megőrizve a darabhatárok kontextusát.* -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Csevegést:** Nyisd meg a [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) fájlt és kérdezd meg: -> - "Hogyan darabolja fel a LangChain4j a dokumentumokat darabokra és miért fontos az átfedés?" -> - "Mi az optimális darabméret különböző dokumentumtípusokhoz és miért?" -> - "Hogyan kezelem a többnyelvű vagy speciális formázású dokumentumokat?" +> **🤖 Próbáld ki [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) fájlt és kérdezd meg: +> - "Hogyan darabolja a LangChain4j a dokumentumokat és miért fontos az átfedés?" +> - "Mi az optimális darabméret különböző dokumentumtípusok esetén és miért?" +> - "Hogyan kezeljem a többnyelvű vagy speciális formázású dokumentumokat?" -### Beágyazások létrehozása +### Beágyazások készítése [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Minden darabot egy számszerűsített reprezentációvá alakítanak, amit embeddingnek nevezünk — lényegében jelentésből számokra konvertáló eszköz. A beágyazó modell nem „intelligens” úgy, mint egy csevegőmodell; nem tud utasításokat követni, érvelni vagy kérdésekre válaszolni. Amit tud, hogy a szöveget egy olyan matematikai térbe helyezi, ahol a hasonló jelentések egymáshoz közel kerülnek — például a „car” és az „automobile”, vagy a „refund policy” és a „return my money”. Gondolj egy csevegőmodellre, mint egy emberre, akivel beszélgetsz; egy embedding modell pedig egy szuperjó irattár. +Minden darabot egy numerikus ábrázolássá alakítanak, amit beágyazásnak nevezünk — lényegében egy jelentés-számokra átalakító. A beágyazási modell nem "intelligens" úgy, mint egy chat modell; nem követ utasításokat, nem gondolkodik, nem válaszol kérdésekre. Amit viszont tud, hogy a szöveget egy matematikai térbe helyezi, ahol hasonló jelentések egymáshoz közel eső vektorok lesznek — például "autó" közel "járműhöz", "visszatérítési szabályzat" közel a "pénzem vissza" kifejezéshez. Gondolj a chat modellre, mint egy beszélgető partnerre; egy beágyazási modell egy kimagaslóan jó iratkezelő rendszer. -Az alábbi ábra vizualizálja ezt a koncepciót — szöveg megy be, numerikus vektorok jönnek ki, és hasonló jelentések közeli vektorokat eredményeznek: +Az alábbi ábra ezt a koncepciót szemlélteti — bejön a szöveg, kimennek numerikus vektorok, és a hasonló jelentések közeli vektorokat eredményeznek: -Embedding Model Concept +Beágyazási modell koncepció -*Ez az ábra szemlélteti, hogyan konvertál egy embedding modell szöveget számszerű vektorokká, ahol a hasonló jelentések — például „car” és „automobile” — egymáshoz közeli helyet foglalnak el a vektortérben.* +*Ez az ábra megmutatja, hogyan alakít egy beágyazási modell szöveget numerikus vektorokká, ahol a hasonló jelentések egymáshoz közel helyezkednek el a vektortérben — például "autó" és "jármű".* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Az osztálydiagram megmutatja a RAG folyamat két különálló áramlatát és a LangChain4j osztályokat, amelyek megvalósítják azokat. A **betöltő áramlat** (feltöltéskor egyszer lefut) darabolja a dokumentumot, beágyazza a darabokat és eltárolja őket `.addAll()` hívással. A **lekérdező áramlat** (minden egyes kérdésnél fut) beágyazza a kérdést, `.search()` segítségével keresi a tárolóban, majd a megtalált kontextust átadja a csevegőmodellnek. Mindkét áramlat az `EmbeddingStore` közös interfészen keresztül kapcsolódik: +Az osztálydiagram az alábbi két folyamatról szól a RAG-csővezetékben, és a LangChain4j osztályokról, amelyek megvalósítják őket. Az **adatfeltöltési folyamat** (feltöltéskor fut egyszer) szétbontja a dokumentumot, beágyazza a darabokat, majd eltárolja őket `.addAll()` segítségével. A **lekérdezési folyamat** (minden kérdésnél fut) beágyazza a kérdést, megkeresi az adattárat `.search()`-al, és átadja a talált kontextust a chat modellnek. Mindkét folyamat találkozik a közös `EmbeddingStore` interfészen: -LangChain4j RAG Classes +LangChain4j RAG osztályok -*Ez az ábra megmutatja a RAG két áramlatát — betöltést és lekérdezést — és azok kapcsolódását a közös EmbeddingStore-on keresztül.* +*Ez az ábra a RAG két folyamatát mutatja — adatfeltöltést és lekérdezést —, és azt, hogy ezek hogyan kapcsolódnak a közös EmbeddingStore-hoz.* -Ha a beágyazásokat eltárolták, a hasonló tartalmak természetesen együtt csoportosulnak a vektortérben. Az alábbi vizualizáció mutatja, hogyan rendeződnek a kapcsolódó témájú dokumentumok szomszédos pontokká, ami lehetővé teszi a szemantikus keresést: +Ha egyszer eltároltuk a beágyazásokat, a hasonló tartalmak természetesen együtt csoportosulnak a vektortérben. Az alábbi vizualizáció megmutatja, hogy a kapcsolódó témákhoz tartozó dokumentumok hogyan állnak össze közeli pontokká, ami lehetővé teszi a szemantikus keresést: -Vector Embeddings Space +Vektor beágyazások tere -*Ez a vizualizáció mutatja, hogyan csoportosulnak a kapcsolódó dokumentumok 3D vektortérben, olyan témák mellett, mint Műszaki dokumentáció, Üzleti szabályok és GYIK, amelyek elkülönült csoportokat alkotnak.* +*Ez a vizualizáció mutatja, hogyan csoportosulnak a kapcsolódó dokumentumok 3D vektortérben, ahol a technikai dokumentumok, üzleti szabályok és GYIK témakörök elkülönülő csoportokat alkotnak.* -Amikor egy felhasználó keres, a rendszer négy lépést követ: egyszer beágyazza a dokumentumokat, minden keresésnél beágyazza a kérdést, a kérdés vektorát összehasonlítja az összes eltárolt vektorral koszinusz hasonlóság alapján, és a legmagasabb pontszámú top-K darabot adja vissza. Az alábbi ábra végigviszi ezeket a lépéseket és a LangChain4j osztályokat: +Amikor a felhasználó keres, a rendszer négy lépést követ: egyszer beágyazza a dokumentumokat, minden keresésnél beágyazza a lekérdezést, összehasonlítja a kérdés vektorát az összes eltárolt vektorral koszinusz hasonlósággal, majd visszaadja a legjobb K darabot. Az alábbi ábra végigvezet minden lépésen és a kapcsolódó LangChain4j osztályokon: -Embedding Search Steps +Beágyazás alapú keresés lépései -*Ez az ábra a négy lépéses beágyazás-keresés folyamatot mutatja: dokumentumok beágyazása, kérdés beágyazása, vektorok összehasonlítása koszinusz hasonlósággal, és a top-K eredmények visszaadása.* +*Ez az ábra a beágyazási keresés négy lépését mutatja: dokumentumok beágyazása, lekérdezés beágyazása, vektorok összehasonlítása koszinusz hasonlósággal és a legjobb K eredmény visszaadása.* ### Szemantikus keresés [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Amikor kérdést teszel fel, a kérdésed is beágyazásra kerül. A rendszer összehasonlítja a kérdés beágyazását az összes dokumentumdarab beágyazásával. Megtalálja a leginkább hasonló jelentésű darabokat — nem csak a kulcsszó egyezéseket, hanem a tényleges szemantikus hasonlóságot. +Amikor kérdést teszel fel, a kérdésed is beágyazódik. A rendszer összehasonlítja a kérdés beágyazását az összes dokumentumdarab beágyazásával. Megtalálja a leginkább hasonló jelentésű darabokat — nem csak kulcsszó egyezést, hanem tényleges szemantikus hasonlóságot keres. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Az alábbi ábra összehasonlítja a szemantikus keresést a hagyományos kulcsszavas kereséssel. Egy kulcsszavas keresés a „vehicle” szóra nem talál meg egy „cars and trucks” darabot, míg a szemantikus keresés megérti, hogy ez ugyanazt jelenti, és magas pontszámmal adja vissza: +Az alábbi ábra összehasonlítja a szemantikus keresést a hagyományos kulcsszavas kereséssel. Egy kulcsszavas keresés a "jármű" szóra nem talál meg egy "autókról és teherautókról" szóló darabot, de a szemantikus keresés megérti, hogy ezek ugyanazt jelentik, és magas pontszámmal visszaadja: -Semantic Search +Szemantikus keresés -*Ez az ábra bemutatja a kulcsszavas keresést és a szemantikus keresést, megmutatva, hogyan hoz vissza a szemantikus keresés fogalmilag kapcsolódó tartalmat még akkor is, ha a pontos kulcsszavak eltérnek.* -A háttérben a hasonlóságot koszinusz hasonlóság méri — gyakorlatilag azt kérdezi, "ez a két nyíl ugyanabba az irányba mutat-e?" Két töredék teljesen eltérő szavakat használhat, de ha ugyanazt jelenti, a vektorjaik ugyanabba az irányba mutatnak és az értékük 1,0-hoz közeli: +*Ez az ábra összehasonlítja a kulcsszó-alapú keresést a szemantikus kereséssel, megmutatva, hogy a szemantikus keresés konceptuálisan kapcsolódó tartalmakat is visszaad akkor is, ha a kulcsszavak eltérnek.* -Koszinusz hasonlóság +A háttérben a hasonlóságot koszinusz hasonlósággal mérik — lényegében azt kérdezik: "ez a két nyíl ugyanabba az irányba mutat?" Két darab teljesen eltérő szavakat használhat, de ha ugyanazt jelenti, a vektoraik ugyanabba az irányba mutatnak és közelítik az 1.0 értéket: -*Ez az ábra a koszinusz hasonlóságot mutatja be, mint az embedding vektorok közötti szöget — a jobban összehangolt vektorok közelebb állnak az 1,0-hoz, ami magasabb szemantikai hasonlóságot jelez.* +Koszinusz hasonlóság +*Ez az ábra a koszinusz hasonlóságot szemlélteti, mint a beágyazási vektorok közötti szög – minél jobban illeszkednek a vektorok, annál közelebb kerül az érték 1.0-hoz, ami magasabb szemantikai hasonlóságot jelez.* -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) fájlt és kérdezd meg: -> - "Hogyan működik a hasonlóság keresés embeddingekkel és mi határozza meg az értékelést?" -> - "Milyen hasonlósági küszöböt használjak és ez hogyan befolyásolja az eredményeket?" -> - "Hogyan kezelem, ha nem talál releváns dokumentumokat?" +> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chat segítségével:** Nyisd meg a [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) fájlt, és kérdezd meg: +> - "Hogyan működik a hasonlóság alapú keresés a beágyazásokkal, és mi határozza meg a pontszámot?" +> - "Milyen hasonlósági küszöböt használjak, és ez hogyan befolyásolja az eredményeket?" +> - "Hogyan kezeljem azokat az eseteket, amikor nem található releváns dokumentum?" ### Válaszgenerálás [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -A legrelevánsabb töredékeket egy strukturált promptba szerkesztik, mely tartalmazza az explicit utasításokat, a lekért kontextust és a felhasználó kérdését. A modell ezeket a konkrét töredékeket olvassa be, és ezek alapján válaszol — csak a rendelkezésére álló információkat használhatja, ami megakadályozza a téves válaszokat. +A legrelevánsabb szeletek egy strukturált promptba vannak összerakva, amely tartalmaz explicit utasításokat, a lekérdezett kontextust és a felhasználó kérdését. A modell ezeket a konkrét szeleteket olvassa el, és ezek alapján válaszol – csak a rendelkezésre álló információt használhatja, ami megakadályozza a kitalációt. ```java String context = matches.stream() @@ -237,65 +236,65 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Az alábbi ábra ezt a szerkesztést mutatja — a keresési lépésből a legjobb pontszámú töredékeket a prompt sablonba illesztik, és az `OpenAiOfficialChatModel` egy megalapozott választ generál: +Az alábbi ábra mutatja ezt az összerakást működés közben – a keresési lépésből a legjobb pontszámú szeletek beépülnek a prompt sablonba, majd az `OpenAiOfficialChatModel` generál egy megalapozott választ: -Kontekstus összeállítása +Context Assembly -*Ez az ábra azt mutatja, hogyan szervezik össze a legjobb pontszámú töredékeket egy strukturált promptba, amely a modell számára alapozott választ enged meg a saját adataidból.* +*Ez az ábra megmutatja, hogyan épülnek be a legjobb pontszámú szeletek egy strukturált promptba, lehetővé téve, hogy a modell megalapozott választ generáljon az adataidból.* -## Futtasd az alkalmazást +## Az alkalmazás futtatása -**Ellenőrizd az üzembe helyezést:** +**Telepítés ellenőrzése:** -Győződj meg arról, hogy a `.env` fájl létezik a gyökérkönyvtárban az Azure hitelesítő adatokkal (a 01-es modulban létrehozva). Futtasd ezt a modul könyvtárából (`03-rag/`): +Győződj meg róla, hogy a gyökérkönyvtárban létezik a `.env` fájl Azure hitelesítő adatokkal (amely a 01-es modul során jön létre). Futtasd ezt a modul könyvtárából (`03-rag/`): **Bash:** ```bash -cat ../.env # Meg kell jelenítenie az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket +cat ../.env # Meg kell jeleníteni az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket ``` **PowerShell:** ```powershell -Get-Content ..\.env # Meg kell jelenítenie az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket +Get-Content ..\.env # Meg kell jeleníteni az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket ``` -**Indítsd el az alkalmazást:** +**Az alkalmazás indítása:** -> **Megjegyzés:** Ha már elindítottad az összes alkalmazást az `./start-all.sh`-al a gyökérkönyvtárból (ahogy a 01-es modul leírja), akkor ez a modul már fut a 8081-es porton. Az alábbi indító parancsokat átugorhatod, és közvetlenül a http://localhost:8081 címre léphetsz. +> **Megjegyzés:** Ha már elindítottad az összes alkalmazást az `./start-all.sh` segítségével a gyökérkönyvtárból (ahogy az 01-es modulban le van írva), ez a modul már fut a 8081-es porton. Megspórolhatod az alábbi indító parancsokat, és egyből megnyithatod a http://localhost:8081 címet. -**1. Opció: Spring Boot Dashboard használata (javasolt VS Code felhasználóknak)** +**1. lehetőség: Spring Boot Dashboard használata (ajánlott VS Code felhasználóknak)** -A fejlesztői konténer tartalmazza a Spring Boot Dashboard kiterjesztést, amely vizuális kezelőfelületet biztosít az összes Spring Boot alkalmazáshoz. A VS Code bal oldalán az Activity Bar-ban találod (keresd a Spring Boot ikont). +A fejlesztői konténer tartalmazza a Spring Boot Dashboard bővítményt, amely vizuális felületet biztosít az összes Spring Boot alkalmazás kezeléséhez. A VS Code bal oldali Activity Bar-ján találod (keresd a Spring Boot ikont). -A Spring Boot Dashboardból: -- Megtekintheted az összes rendelkezésre álló Spring Boot alkalmazást a munkaterületen -- Egy kattintással indíthatsz/leállíthatsz alkalmazásokat -- Valós idejű alkalmazásnaplókat nézhetsz -- Nyomon követheted az alkalmazás állapotát +A Spring Boot Dashboard-ból elvégezheted: +- Az összes elérhető Spring Boot alkalmazás megtekintését a munkaterületen +- Az alkalmazások egy kattintással való indítását/leállítását +- Az alkalmazás naplóinak valós idejű megtekintését +- Az alkalmazás állapotának monitorozását -Egyszerűen kattints a "rag" melletti lejátszás gombra a modul elindításához, vagy indítsd el egyszerre az összes modult. +Egyszerűen kattints a lejátszás gombra a "rag" modul mellett az indításhoz, vagy indítsd el az összes modult egyszerre. Spring Boot Dashboard -*Ez a képernyőkép a Spring Boot Dashboardot mutatja a VS Code-ban, ahol vizuálisan indíthatsz, állíthatsz le és figyelhetsz alkalmazásokat.* +*Ez a képernyőkép a Spring Boot Dashboard-ot mutatja VS Code-ban, ahol vizuálisan indíthatsz, leállíthatsz és figyelhetsz alkalmazásokat.* -**2. Opció: Shell szkriptek használata** +**2. lehetőség: Shell scriptek használata** -Indítsd el az összes webalkalmazást (01-04-es modulok): +Indítsd el az összes webalkalmazást (01-04 modulok): **Bash:** ```bash -cd .. # A gyökér könyvtárból +cd .. # A gyökérkönyvtárból ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # A gyökérkönyvtárból +cd .. # A gyökér könyvtárból .\start-all.ps1 ``` -Vagy indítsd csak ezt a modult: +Vagy indítsd el csak ezt a modult: **Bash:** ```bash @@ -309,16 +308,16 @@ cd 03-rag .\start.ps1 ``` -Mindkét szkript automatikusan betölti a környezeti változókat a gyökér `.env` fájlból, és ha nem léteznek, lefordítja a JAR fájlokat. +Mindkét script automatikusan betölti a környezeti változókat a gyökér `.env` fájlból, és lefordítja a JAR fájlokat, ha még nem léteznek. -> **Megjegyzés:** Ha inkább manuálisan fordítanád le az összes modult indítás előtt: +> **Megjegyzés:** Ha inkább kézzel fordítanád le az összes modult az indítás előtt: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -345,81 +344,81 @@ cd ..; .\stop-all.ps1 # Minden modul ## Az alkalmazás használata -Az alkalmazás webes felületet biztosít dokumentum feltöltéshez és kérdések feltevéséhez. +Az alkalmazás egy webes felületet kínál dokumentum feltöltéshez és kérdések feltevéséhez. -RAG alkalmazás felület +RAG Application Interface *Ez a képernyőkép a RAG alkalmazás felületét mutatja, ahol dokumentumokat töltesz fel és kérdéseket teszel fel.* ### Dokumentum feltöltése -Kezdd egy dokumentum feltöltésével — teszteléshez a TXT fájlok a legjobbak. Ebben a könyvtárban található egy `sample-document.txt`, amely információkat tartalmaz a LangChain4j jellemzőiről, RAG megvalósításról és bevált gyakorlatokról — tökéletes a rendszer kipróbálásához. +Kezdd egy dokumentum feltöltésével – teszteléshez a TXT fájlok a legjobbak. Ehhez a könyvtárhoz tartozik egy `sample-document.txt`, amely a LangChain4j jellemzőiről, a RAG implementációról és legjobb gyakorlatokról tartalmaz információkat – tökéletes a rendszer teszteléséhez. -A rendszer feldolgozza a dokumentumot, felbontja töredékekre, és embeddingeket készít mindegyikhez. Ez automatikusan megtörténik a feltöltéskor. +A rendszer feldolgozza a dokumentumodat, felbontja szeletekre, és létrehozza minden szelethez a beágyazást. Ez automatikusan megtörténik a feltöltéskor. ### Kérdések feltevése -Most tegyél fel konkrét kérdéseket a dokumentum tartalmáról. Próbálj meg valami tényszerűt kérdezni, ami egyértelműen szerepel a dokumentumban. A rendszer megkeresi a releváns töredékeket, beilleszti azokat a promptba, és választ generál. +Most tegyél fel konkrét kérdéseket a dokumentum tartalmáról. Próbálj meg valami tényszerűt, ami egyértelműen benne van a dokumentumban. A rendszer megkeresi a releváns szeleteket, beilleszti azokat a promptba és generál egy választ. ### Forráshivatkozások ellenőrzése -Figyeld meg, hogy minden válasz tartalmaz forráshivatkozásokat a hasonlósági pontszámokkal. Ezek a pontszámok (0 és 1 között) azt mutatják, milyen releváns volt az adott töredék a kérdésedhez. A magasabb pontszám jobb egyezést jelent. Ez lehetővé teszi, hogy ellenőrizd a választ az eredeti forrás alapján. +Vegyük észre, hogy minden válasz tartalmaz forráshivatkozásokat a hasonlósági pontszámokkal együtt. Ezek a pontszámok (0-tól 1-ig) azt jelzik, milyen releváns volt az adott szelet a kérdésedre. A magasabb pontszám jobb találatot jelent. Így ellenőrizheted a választ az eredeti forrással szemben. -RAG lekérdezési eredmények +RAG Query Results -*Ez a képernyőkép a lekérdezési eredményeket mutatja a generált válasszal, forráshivatkozásokkal és relevancia pontszámokkal minden lekért töredékhez.* +*Ez a képernyőkép kérdező eredményeket mutat, a generált választ, forráshivatkozásokat és az egyes lekért szeletek relevancia pontszámait.* ### Kísérletezz a kérdésekkel -Próbálj ki különféle kérdéstípusokat: +Próbálj ki különböző típusú kérdéseket: - Konkrét tények: "Mi a fő téma?" - Összehasonlítások: "Mi a különbség X és Y között?" -- Összefoglalók: "Foglald össze a Z-vel kapcsolatos kulcspontokat" +- Összefoglalók: "Foglald össze a Z legfontosabb pontjait" -Nézd meg, hogyan változnak a relevancia pontszámok az alapján, hogy mennyire egyezik a kérdés a dokumentumtartalommal. +Figyeld meg, hogyan változnak a relevancia pontszámok attól függően, mennyire egyezik a kérdésed a dokumentum tartalmával. -## Alapfogalmak +## Kulcsfogalmak -### Töredékezési stratégia +### Szeletelési stratégia -A dokumentumokat 300 tokenes töredékekre bontják 30 token átfedéssel. Ez a balansz biztosítja, hogy minden töredéknek legyen elég kontextusa az értelmes tartalomhoz, miközben elég kicsi marad ahhoz, hogy több töredéket is bele lehessen foglalni egy promptba. +A dokumentumokat 300 tokenes szeletekre bontjuk, 30 token átfedéssel. Ez az egyensúly biztosítja, hogy minden szeletnek elegendő kontextusa legyen a jelentéshez, miközben elég kicsi ahhoz, hogy több szelet is bekerülhessen egy promptba. ### Hasonlósági pontszámok -Minden lekért töredékhez tartozik egy 0 és 1 közötti hasonlósági pontszám, amely jelzi, mennyire egyezik a felhasználó kérdésével. Az alábbi ábra vizualizálja a pontszám tartományokat és azt, hogy a rendszer hogyan használja ezeket az eredmények szűrésére: +Minden lekért szelethez tartozik egy 0 és 1 közötti hasonlósági pontszám, amely azt mutatja, mennyire egyezik a felhasználó kérdésével. Az alábbi ábra vizualizálja a pontszám tartományokat és azt, hogyan használja a rendszer ezeket az eredmények szűrésére: -Hasonlósági pontszámok +Similarity Scores -*Ez az ábra a pontszám tartományokat mutatja 0-tól 1-ig, egy 0,5-ös minimum küszöbbel, ami kiszűri az irreleváns töredékeket.* +*Ez az ábra a 0-tól 1-ig tartó pontszámokat mutatja, egy 0,5-ös minimum küszöbbel, amely kiszűri a nem releváns szeleteket.* -A pontszámok 0 és 1 között mozognak: -- 0,7-1,0: Nagyon releváns, pontos egyezés +A pontszámok tartománya: +- 0,7-1,0: Nagyon releváns, pontos találat - 0,5-0,7: Releváns, jó kontextus -- 0,5 alatt: Kiszűrve, túl eltérő +- 0,5 alatt: Kiszűrt, túl eltérő -A rendszer csak a minimum küszöböt meghaladó töredékeket veszi figyelembe a minőség biztosításához. +A rendszer csak a minimum küszöböt meghaladó szeleteket hozza vissza a minőség biztosítása érdekében. -Az embeddingek jól működnek, ha a jelentések tisztán csoportosulnak, de vannak vakfoltjaik. Az alábbi ábra az általános hibamódokat mutatja — a túl nagy töredékek zavaros vektorokat eredményeznek, a túl kicsiknek nincs kontextusa, az ambivalens kifejezések több klaszterre mutathatnak, és a pontos egyezés keresések (azonosítók, cikkszámok) nem működnek embeddingekkel: +A beágyazások jól működnek, ha a jelentés tisztán csoportosul, de vannak gyenge pontjaik. Az alábbi ábra bemutatja a gyakori hibamódokat – túl nagy szeletek zavaros vektorokat eredményeznek, túl kicsik kontextus hiányában szenvednek, kétértelmű kifejezések több klaszterre mutathatnak, és az azonosítás alapú keresések (azonosítók, cikkszámok) egyáltalán nem működnek beágyazásokkal: -Embedding hibamódok +Embedding Failure Modes -*Ez az ábra az embeddingek gyakori hibamódjait mutatja be: túl nagy, túl kicsi töredékek, több klaszterre mutató kifejezések és azonosító típusú keresések, amelyek nem működnek embeddinggel.* +*Ez az ábra a beágyazások általános hibamódjait mutatja: túl nagy szeletek, túl kicsi szeletek, kétértelmű kifejezések, és pontos egyezésű keresések, mint az azonosítók.* ### Memóriában tárolás -Ez a modul a egyszerűség kedvéért memóriában tárol. Ha újraindítod az alkalmazást, az feltöltött dokumentumok elvesznek. Éles rendszerek tartós vektor adatbázisokat használnak, mint a Qdrant vagy az Azure AI Search. +Ez a modul egyszerűség kedvéért memóriában tárolja az adatokat. Az alkalmazás újraindításakor a feltöltött dokumentumok elvesznek. Éles rendszerek tartós vektordatabázisokat használnak, például Qdrant vagy Azure AI Search. ### Kontextusablak kezelése -Minden modellnek van egy maximális kontextusablaka. Nem tudsz minden töredéket belefoglalni egy nagy dokumentumból. A rendszer a top N legrelevánsabb töredéket kéri le (alapértelmezett 5), hogy a határokat tartsa és elég kontextust adjon a pontos válaszokhoz. +Minden modellnek van maximális kontextusablaka. Nem fér be minden szelet nagy dokumentumokból. A rendszer az N legrelevánsabb szeletet hozza vissza (alapértelmezett 5), hogy a határokon belül maradjon, miközben elég kontextust ad a pontos válaszokhoz. -## Mikor számít a RAG +## Mikor fontos a RAG -A RAG nem mindig a megfelelő megközelítés. Az alábbi döntési segédlet segít eldönteni, mikor érdemes RAG-ot használni, és mikor elegendő az egyszerűbb megoldás — például a tartalom közvetlen promptba illesztése vagy a modell beépített tudásának használata: +A RAG nem mindig a megfelelő megoldás. Az alábbi döntési útmutató segít eldönteni, mikor ad hozzáadott értéket a RAG, és mikor elegendőek egyszerűbb megoldások – például a tartalom közvetlen beillesztése a promptba vagy a modell beépített tudására támaszkodás: -Mikor használjuk a RAG-ot +When to Use RAG -*Ez az ábra egy döntési segédletet mutat be, hogy mikor ad értéket a RAG, és mikor elegendőek az egyszerűbb megoldások.* +*Ez az ábra döntési útmutatót mutat, hogy mikor érdemes használni a RAG-ot, és mikor elegendőek egyszerűbb megoldások.* ## Következő lépések @@ -427,11 +426,11 @@ A RAG nem mindig a megfelelő megközelítés. Az alábbi döntési segédlet se --- -**Navigáció:** [← Előző: 02-es modul - Prompt fejlesztés](../02-prompt-engineering/README.md) | [Vissza a főoldalra](../README.md) | [Következő: 04-es modul - Eszközök →](../04-tools/README.md) +**Navigáció:** [← Előző: 02-es modul – Prompt mérnökség](../02-prompt-engineering/README.md) | [Vissza a főoldalra](../README.md) | [Következő: 04-es modul – Eszközök →](../04-tools/README.md) --- -**Jogi nyilatkozat**: -Ez a dokumentum az AI fordító szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) használatával készült. Bár igyekszünk pontos fordítást biztosítani, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Kritikus információk esetén szakmai, emberi fordítást javaslunk. Nem vállalunk felelősséget az ebből eredő félreértésekért vagy hibás értelmezésekért. +**Jogi nyilatkozat**: +Ez a dokumentum az AI fordítási szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Fontos információk esetén professzionális emberi fordítást javasolunk. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely ebből a fordításból ered. \ No newline at end of file diff --git a/translations/hu/04-tools/README.md b/translations/hu/04-tools/README.md index 67aac03c6..add48cc1c 100644 --- a/translations/hu/04-tools/README.md +++ b/translations/hu/04-tools/README.md @@ -1,84 +1,84 @@ -# 04. modul: AI ügynökök eszközökkel +# Modul 04: MI Ügynökök eszközökkel ## Tartalomjegyzék -- [Videós bemutató](../../../04-tools) -- [Mit tanulsz meg](../../../04-tools) -- [Előfeltételek](../../../04-tools) -- [AI ügynökök megértése eszközökkel](../../../04-tools) -- [Hogyan működik az eszközhívás](../../../04-tools) - - [Eszközdefiníciók](../../../04-tools) - - [Döntéshozatal](../../../04-tools) - - [Végrehajtás](../../../04-tools) - - [Válaszgenerálás](../../../04-tools) - - [Architektúra: Spring Boot automatikus bekötés](../../../04-tools) -- [Eszközláncolás](../../../04-tools) -- [Az alkalmazás futtatása](../../../04-tools) -- [Az alkalmazás használata](../../../04-tools) - - [Egyszerű eszközhasználat kipróbálása](../../../04-tools) - - [Eszközláncolás tesztelése](../../../04-tools) - - [Párbeszédfolyam megtekintése](../../../04-tools) - - [Különböző kérdések kipróbálása](../../../04-tools) -- [Kulcsfogalmak](../../../04-tools) - - [ReAct minta (gondolkodás és cselekvés)](../../../04-tools) - - [Az eszközleírások számítanak](../../../04-tools) - - [Munkamenet-kezelés](../../../04-tools) - - [Hibakezelés](../../../04-tools) -- [Elérhető eszközök](../../../04-tools) -- [Mikor használjunk eszközalapú ügynököket](../../../04-tools) -- [Eszközök kontra RAG](../../../04-tools) -- [Következő lépések](../../../04-tools) - -## Videós bemutató - -Nézd meg ezt az élő részvételű bemutatót, amely elmagyarázza, hogyan kezdj hozzá ehhez a modulhoz: - -AI Agents with Tools and MCP - Live Session - -## Mit tanulsz meg - -Eddig megtanultad, hogyan folytass párbeszédeket az AI-val, hogyan építsd fel hatékonyan a promptokat, és hogyan alapozd válaszaidat a dokumentumaidra. De van egy alapvető korlát: a nyelvi modellek csak szöveget képesek generálni. Nem tudnak időjárást ellenőrizni, számításokat végezni, adatbázisokat lekérdezni vagy külső rendszerekkel kommunikálni. - -Az eszközök ezt megváltoztatják. Azáltal, hogy a modell hozzáférhet olyan függvényekhez, amiket meghívhat, szöveggenerátorból olyan ügynökké alakul, amely képes műveleteket végrehajtani. A modell eldönti, mikor kell eszköz, melyik eszközt használja, és milyen paraméterekkel hívja meg. A te kódod végrehajtja a függvényt és visszaadja az eredményt. A modell beépíti ezt az eredményt a válaszába. +- [Videó Bemutató](#videó-bemutató) +- [Amit Megtanulsz](#amit-megtanulsz) +- [Előfeltételek](#előfeltételek) +- [Mesterséges Intelligencia Ügynökök Eszközökkel](#mesterséges-intelligencia-ügynökök-eszközökkel) +- [Hogyan Működik az Eszköz Meghívás](#hogyan-működik-az-eszköz-meghívás) + - [Eszköz Definíciók](#eszköz-definíciók) + - [Döntéshozatal](#döntéshozatal) + - [Végrehajtás](#végrehajtás) + - [Válaszgenerálás](#válaszgenerálás) + - [Architektúra: Spring Boot Automatikus Bekötés](#architektúra-spring-boot-automatikus-bekötés) +- [Eszközláncolás](#eszközláncolás) +- [Az Alkalmazás Futattása](#az-alkalmazás-futattása) +- [Az Alkalmazás Használata](#az-alkalmazás-használata) + - [Egyszerű Eszköz Használat Kipróbálása](#próbálj-ki-egyszerű-eszközhasználatot) + - [Eszközláncolás Tesztelése](#teszteld-az-eszköz-láncolást) + - [Beszélgetési Folyamat Megtekintése](#nézd-meg-a-beszélgetés-menetét) + - [Különböző Kérések Kipróbálása](#kísérletezz-különféle-kérésekkel) +- [Kulcsfogalmak](#főbb-fogalmak) + - [ReAct Minta (Érvelés és Cselekvés)](#react-minta-gondolkodás-és-cselekvés) + - [Az Eszköz Leírások Fontossága](#az-eszközleírások-fontossága) + - [Munkamenet Kezelés](#munkamenet-kezelés) + - [Hibakezelés](#hibakezelés) +- [Elérhető Eszközök](#elérhető-eszközök) +- [Mikor Használjunk Eszköz-alapú Ügynököket](#mikor-használj-eszköz-alapú-ügynököket) +- [Eszközök vs RAG](#eszközök-vs-rag) +- [Következő Lépések](#következő-lépések) + +## Videó Bemutató + +Nézd meg ezt az élő munkamenetet, amely elmagyarázza, hogyan kezdj neki ennek a modulnak: + +MI Ügynökök eszközökkel és MCP - Élő Munkamenet + +## Amit Megtanulsz + +Eddig megtanultad, hogyan folytass beszélgetést a MI-vel, hogyan strukturáld hatékonyan a promptokat, és hogyan kötöd válaszaidat a dokumentumaidhoz. De van egy alapvető korlát: a nyelvi modellek csak szöveget generálnak. Nem tudják lekérdezni az időjárást, számításokat végezni, adatbázisokat lekérdezni vagy külső rendszerekkel kommunikálni. + +Az eszközök ezt megváltoztatják. Azáltal, hogy a modellhez hozzáférést adsz hívható funkciókhoz, alakítsd át szöveggenerátorból ügynökké, aki képes cselekedni. A modell eldönti, mikor van szüksége eszközre, melyik eszközt használja, és milyen paramétereket ad át. A kódod végrehajtja a funkciót és visszaadja az eredményt. A modell beépíti ezt az eredményt a válaszába. ## Előfeltételek -- Elvégezted az [01. modul - Bevezetés](../01-introduction/README.md) anyagát (Azure OpenAI erőforrások telepítve) -- Ajánlott a korábbi modulok elvégzése (ez a modul a [03. modul RAG fogalmaira](../03-rag/README.md) hivatkozik az Eszközök kontra RAG összehasonlításban) -- `.env` fájl a gyökérkönyvtárban Azure hitelesítőkkel (amit az `azd up` létrehozott az 01. modulban) +- Elkészült a [01. modul - Bevezetés](../01-introduction/README.md) (Azure OpenAI erőforrások telepítve) +- Az előző modulok elvégzése ajánlott (ez a modul hivatkozik a [RAG koncepciókra a 03. modulból](../03-rag/README.md) az Eszközök vs RAG összehasonlításban) +- `.env` fájl a gyökérkönyvtárban Azure hitelesítő adatokkal (az `azd up` létrehozza az 01. modulban) -> **Megjegyzés:** Ha még nem végezted el az 01. modult, előbb kövesd ott a telepítési útmutatót. +> **Megjegyzés:** Ha nem végezted el az 01. modul befejezését, előbb kövesd az ottani telepítési utasításokat. -## AI ügynökök megértése eszközökkel +## Mesterséges Intelligencia Ügynökök Eszközökkel -> **📝 Megjegyzés:** Ebben a modulban az "ügynök" kifejezés olyan AI asszisztenseket jelöl, amelyek eszközhívó képességekkel vannak bővítve. Ez különbözik a **Agentic AI** mintáktól (önálló ügynökök tervezéssel, memóriával és többlépéses érveléssel), amelyeket majd a [05. modulban: MCP](../05-mcp/README.md) tárgyalunk. +> **📝 Megjegyzés:** Ebben a modulban az „ügynökök” kifejezés olyan MI asszisztenseket jelöl, amelyek eszköz-hívási képességekkel bővültek. Ez eltér az **Agentic AI** mintáktól (önálló ügynökök tervezéssel, memóriával és többlépcsős érveléssel), amelyeket a [05. modulban: MCP](../05-mcp/README.md) fedünk le. -Eszközök nélkül a nyelvi modell csak szöveget tud generálni a tanítási adataiból. Ha megkérdezed az aktuális időjárást, csupán találgatnia kell. Ha eszközöket adsz neki, akkor például egy időjárási API-t hívhat meg, számításokat végezhet, vagy lekérdezheti egy adatbázist – majd az így kapott valós eredményeket beépíti a válaszába. +Eszközök nélkül a nyelvi modell csak szöveget generál a tanulási adataiból. Ha megkérdezed az aktuális időjárást, csak találgat. Ha eszközöket adsz neki, hívhat időjárás API-t, végezhet számításokat vagy adatbázis lekérdezést — majd a valós eredményeket beépíti a válaszába. -Without Tools vs With Tools +Eszközök nélkül vs Eszközökkel -*Eszközök nélkül a modell csak találgat — eszközökkel API-kat hívhat, számításokat végezhet és valós idejű adatokat adhat vissza.* +*Eszközök nélkül a modell csak találgat — eszközökkel API-kat hívhat, számításokat végezhet, és valós idejű adatokat szolgáltathat.* -Az AI ügynök eszközökkel egy **Reasoning and Acting (ReAct)** mintát követ. A modell nem csak válaszol — végiggondolja, mire van szüksége, eszközt hív meg, megfigyeli az eredményt, majd eldönti, hogy újra cselekszik, vagy leadja a végső választ: +Az eszközökkel rendelkező MI ügynök egy **Reasoning and Acting (ReAct)** mintát követ. A modell nem csak válaszol — megfontolja, mire van szüksége, cselekszik eszközhívással, megfigyeli az eredményt, majd eldönti, hogy újra cselekszik-e vagy végső választ ad: -1. **Érvelés** — Az ügynök elemzi a felhasználó kérdését, és megállapítja, milyen információra van szüksége -2. **Cselekvés** — Az ügynök kiválasztja a megfelelő eszközt, generálja a helyes paramétereket, és meghívja azt -3. **Megfigyelés** — Kézhez kapja az eszköz eredményét és értékeli azt -4. **Ismétlés vagy válaszadás** — Ha több adat szükséges, visszatér az első ponthoz; ha nem, természetes nyelvű választ fogalmaz meg +1. **Érvelés** — Az ügynök elemzi a felhasználó kérdését és meghatározza, milyen információ szükséges +2. **Cselekvés** — Az ügynök kiválasztja a megfelelő eszközt, előállítja a helyes paramétereket, és hívja azt +3. **Megfigyelés** — Az ügynök megkapja az eszköz kimenetét és értékeli az eredményt +4. **Ismétlés vagy Válaszadás** — Ha további adatok kellettek, visszatér a ciklus elejére; másképp összefoglalja a választ természetes nyelven -ReAct Pattern +ReAct Minta -*A ReAct ciklus — az ügynök végiggondolja mit tegyen, cselekszik az eszköz meghívásával, megfigyeli az eredményt, és ismétel, amíg végső választ tud adni.* +*A ReAct ciklus — az ügynök megfontolja, mit kell tennie, cselekszik eszközhívással, megfigyeli az eredményt, és addig ismétel, amíg végső választ nem adhat.* -Ez automatikusan történik. Te definiálod az eszközöket és azok leírásait. A modell dönt az eszközhasználatról, hogy mikor és hogyan alkalmazza őket. +Ez automatikusan történik. Te határozod meg az eszközöket és azok leírásait. A modell kezeli a döntéshozatalt arról, mikor és hogyan használja őket. -## Hogyan működik az eszközhívás +## Hogyan Működik az Eszköz Meghívás -### Eszközdefiníciók +### Eszköz Definíciók [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Függvényeket határozol meg világos leírásokkal és paraméter specifikációkkal. A modell ezeket a leírásokat látja a rendszerüzenetben, és érti, mit csinál az adott eszköz. +Egyértelmű leírással és paraméter specifikációkkal rendelkezel a funkciókat. A modell ezeknek a leírásoknak látja a tartalmát a rendszerpromptban, és megérti, mire való az egyes eszköz. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Az időjárás lekérdezési logikája + // Az időjárás lekérdezés logikája return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,143 +96,143 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Az asszisztens automatikusan a Spring Boot által van összekötve: +// Az asszisztens automatikusan össze van kötve a Spring Boot által: // - ChatModel bean // - Minden @Tool metódus az @Component osztályokból -// - ChatMemoryProvider a munkamenet kezeléséhez +// - ChatMemoryProvider a munkamenet kezelésére ``` -Az alábbi ábra szétbont minden annotációt és megmutatja, hogyan segít mindegyik része az AI-nak megérteni, mikor kell az eszközt hívni és milyen argumentumokat kell átadni: +Az alábbi diagram lebontja az összes annotációt, és megmutatja, hogyan segít minden elem az MI-nek megérteni, mikor kell meghívni az eszközt és milyen argumentumokat adjon át: -Anatomy of Tool Definitions +Az Eszköz Definíciók Anatómiája -*Egy eszközdefiníció felépítése — @Tool jelzi az AI-nak, mikor használja, @P írja le az egyes paramétereket, és az @AiService összeköti az egészet az induláskor.* +*Az eszköz definíció anatómiája — az @Tool megmondja az MI-nek, mikor használja, az @P leírja az egyes paramétereket, és az @AiService mindent összeköt indításkor.* > **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) fájlt és kérdezd meg: -> - "Hogyan integrálnék egy valós időjárási API-t, mint az OpenWeatherMap a teszt adatok helyett?" -> - "Mi tesz ki egy jó eszközleírást, ami segíti az AI-t, hogy helyesen használja?" -> - "Hogyan kezeljem az API hibákat és a hívási korlátokat az eszközmegvalósításokban?" +> - "Hogyan integrálnék egy valós időjárás API-t, mint az OpenWeatherMap ahelyett, hogy teszt adatot használok?" +> - "Mi tesz egy jó eszköz leírást, ami segíti az MI helyes használatát?" +> - "Hogyan kezelem az API hibákat és korlátokat az eszköz implementációkban?" ### Döntéshozatal -Ha a felhasználó megkérdezi: „Milyen az időjárás Seattle-ben?”, a modell nem véletlenszerűen választ eszközt. Összehasonlítja a felhasználó szándékát minden eszközleírással, értékeli mindegyik relevanciáját, és a legjobbat választja ki. Ezután generál egy strukturált függvényhívást a megfelelő paraméterekkel – ebben az esetben a `location` értéke `"Seattle"` lesz. +Amikor a felhasználó megkérdezi: „Milyen az idő Seattle-ben?”, a modell nem véletlenszerűen választ eszközt. Összeveti a felhasználó szándékát az összes hozzáférhető eszköz leírásával, pontozza azok relevanciáját, és kiválasztja a legjobbat. Ezután előállít egy strukturált függvényhívást a megfelelő paraméterekkel — jelen esetben `location` értéke `"Seattle"`. -Ha egyik eszköz sem illik, a modell a saját tudására támaszkodva válaszol. Több eszköz esetén a legspecifikusabbat választja. +Ha egyik eszköz sem felel meg, a modell a saját tudásából válaszol. Ha több eszköz is megfelel, a legspecifikusabbat választja ki. -How the AI Decides Which Tool to Use +Hogyan dönt az MI, melyik eszközt használja -*A modell minden elérhető eszközt értékel a felhasználói szándék szerint, és a legjobbat választja ki — ezért fontos, hogy világos, specifikus eszközleírásokat írj.* +*A modell minden elérhető eszközt értékel a felhasználó szándékához képest és kiválasztja a legjobb találatot — ezért fontos a tiszta, pontos eszközleírás megírása.* ### Végrehajtás [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -A Spring Boot automatikusan beköti a deklaratív `@AiService` interfészt az összes regisztrált eszközzel, és a LangChain4j automatikusan végrehajtja az eszköz hívásokat. A háttérben egy teljes eszközhívás hat szakaszon keresztül halad – a felhasználó természetes nyelvű kérdésétől a természetes nyelvű válasz visszaadásáig: +Spring Boot automatikusan beköti a deklaratív `@AiService` interfészt az összes regisztrált eszközhöz, és a LangChain4j automatikusan végrehajtja az eszközhívásokat. A háttérben egy komplett eszközhívási folyamat zajlik hat szakaszon át — a felhasználó természetes nyelvű kérdésétől a válasz természetes nyelvű megformálásáig: -Tool Calling Flow +Eszköz Meghívási Folyamat -*Végponttól végpontig folyamat — a felhasználó kérdez, a modell eszközt választ, a LangChain4j végrehajtja, és a modell a kapott eredményt beépíti a választba.* +*Az end-to-end folyamat — a felhasználó kérdez, a modell kiválaszt egy eszközt, a LangChain4j végrehajtja, és a modell beépíti az eredményt a válaszba.* -Ha a [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) példát lefuttattad 00-ban, már láttad ezt a mintát működés közben – a `Calculator` eszközöket ugyanígy hívta meg. Az alábbi szekvencia diagram pontosan megmutatja, mi történt a háttérben a demó során: +A háttérben az `AiServices` futtatja ugyanazt az eszközhívási ciklust bármely eszköz esetén — itt egy egyszerű `Calculator` példával illusztrálva. Az alábbi sorrendi diagram pontosan megmutatja a belső lépéseket: -Tool Calling Sequence Diagram +Eszköz Meghívási Sorrendi Diagram -*Eszközhívási ciklus a Quick Start demóból — az `AiServices` elküldi az üzenetet és az eszköz sémákat az LLM-nek, az LLM egy függvényhívással válaszol, mint az `add(42, 58)`, a LangChain4j helyben végrehajtja a `Calculator` metódust, majd az eredményt visszacsatolja a végső válaszhoz.* +*Az eszközhívási ciklus — az `AiServices` elküldi az üzenetedet és az eszköz sémákat az LLM-nek, az LLM válasza egy függvényhívás, például `add(42, 58)`, a LangChain4j helyben végrehajtja a `Calculator` metódust, majd az eredményt visszaküldi a végső válaszhoz.* -> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg az [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) fájlt és kérdezd meg: -> - "Hogyan működik a ReAct minta és miért hatékony az AI ügynökök számára?" -> - "Hogyan dönt az ügynök, hogy melyik eszközt használja és milyen sorrendben?" -> - "Mi történik, ha egy eszköz végrehajtása meghiúsul – hogyan kezeljem robosztusan a hibákat?" +> **🤖 Próbáld ki a [GitHub Copilot](https://github.com/features/copilot) Chattel:** Nyisd meg a [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) fájlt és kérdezd meg: +> - "Hogyan működik a ReAct minta és miért hatékony MI ügynökök számára?" +> - "Hogyan dönt az ügynök, melyik eszközt használja és milyen sorrendben?" +> - "Mi történik, ha egy eszközhívás sikertelen — hogyan kezeljem robusztusan a hibákat?" ### Válaszgenerálás -A modell megkapja az időjárási adatokat, és természetes nyelvű választ formáz belőlük a felhasználónak. +A modell megkapja az időjárási adatot és természetes nyelvű válaszra formázza a felhasználó számára. -### Architektúra: Spring Boot automatikus bekötés +### Architektúra: Spring Boot Automatikus Bekötés -Ez a modul a LangChain4j Spring Boot integrációját használja deklaratív `@AiService` interfészekkel. Induláskor a Spring Boot felfedezi az összes `@Component`-et, melyek `@Tool` metódusokat tartalmaznak, a `ChatModel` bean-t és a `ChatMemoryProvider`-t — majd mindet egyetlen `Assistant` interfészbe kötve összerendezi, mindezt null boilerplate kóddal. +Ez a modul használja a LangChain4j Spring Boot integrációját deklaratív `@AiService` interfészekkel. Indításkor a Spring Boot felfedezi az összes `@Component`-et, amelyek tartalmaznak `@Tool` metódusokat, a te `ChatModel` binnedet, és a `ChatMemoryProvider`-t — majd mindet egyetlen `Assistant` interfészbe köt összeszerelés nélkül. -Spring Boot Auto-Wiring Architecture +Spring Boot Automatikus Bekötési Architektúra -*Az @AiService interfész összekapcsolja a ChatModelt, az eszköz komponenseket és a memória szolgáltatót — a Spring Boot minden bekötést automatikusan elintéz.* +*Az @AiService interfész összekapcsolja a ChatModelt, eszköz komponenseket és memória szolgáltatót — a Spring Boot automatikusan kezeli a bekötést.* -Íme a teljes kérés életciklusa egy szekvencia diagramon – az HTTP kérésből az vezérlőn, szolgáltatáson és az automatikusan kötött proxy-n keresztül az eszköz végrehajtásig és vissza: +Itt van a teljes kérés-életciklus egy sorrendi diagramon — a HTTP kérésből a kontrolleren át a szolgáltatásig, az automatikusan bekötött proxyig, majd az eszköz végrehajtásig és vissza: -Spring Boot Tool Calling Sequence +Spring Boot Eszköz Meghívási Sorrendi Diagram -*A teljes Spring Boot kéréséletciklus — az HTTP kérés áthalad a vezérlőn és a szolgáltatáson az automatikusan kötött Assistant proxyig, amely automatikusan összehangolja az LLM-et és az eszközhívásokat.* +*Teljes Spring Boot kérés életciklus — HTTP kérés a kontrolleren és szolgáltatáson áthalad az automatikusan bekötött Assistant proxyhoz, amely automatikusan koordinálja az LLM-et és az eszközhívásokat.* -Az eljárás fő előnyei: +E megközelítés fő előnyei: -- **Spring Boot automatikus bekötés** — ChatModel és eszközök automatikusan injektálva -- **@MemoryId minta** — Automatikus munkamenet-alapú memória kezelés -- **Egyetlen példány** — Assistant egyszer létrejön és újrafelhasználható, jobb teljesítményért +- **Spring Boot automatikus bekötés** — ChatModel és eszközök automatikusan be vannak injektálva +- **@MemoryId minta** — Automatikus munkamenet alapú memória kezelés +- **Egyetlen példány** — Assistant egyszer létrejön és újrahasználható a jobb teljesítményért - **Típusbiztos végrehajtás** — Java metódusok közvetlen hívása típuskonverzióval -- **Multi-turn koordináció** — Eszközláncolást automatikusan kezeli -- **Null boilerplate** — Nincs manuális `AiServices.builder()` hívás vagy memória HashMap +- **Több körös koordinálás** — Automatikusan kezeli az eszközláncolást +- **Nulla alap kódolás** — Nem szükséges kézi `AiServices.builder()` hívás vagy memória HashMap -Alternatív megközelítések (manuális `AiServices.builder()`) több kódot igényelnek és nem élvezhetik a Spring Boot integráció előnyeit. +Alternatív megoldások (kézi `AiServices.builder()`) több kódot igényelnek és nem használják ki a Spring Boot előnyeit. ## Eszközláncolás -**Eszközláncolás** — Az eszközalapú ügynökök valós ereje akkor mutatkozik meg, ha egyetlen kérdés több eszközt igényel. Például: „Milyen az időjárás Seattle-ben Fahrenheitben?” Az ügynök automatikusan láncol két eszközt: először meghívja a `getCurrentWeather`-t, hogy megszerezze a Celsius hőmérsékletet, majd ezt az értéket átadja a `celsiusToFahrenheit`-nek a konvertáláshoz — mindez egyetlen beszélgetési körben. +**Eszközláncolás** — Az eszköz-alapú ügynökök valódi ereje akkor mutatkozik meg, amikor egyetlen kérdés több eszközt igényel. Kérdezd meg: „Milyen az idő Seattle-ben Fahrenheitben?”, és az ügynök automatikusan összefűz két eszközt: először meghívja a `getCurrentWeather`-t, hogy megszerezze a Celsius hőmérsékletet, majd átadja azt a `celsiusToFahrenheit`-nek átváltásra — mindezt egyetlen beszélgetési körben. -Tool Chaining Example +Eszközláncolás Példa -*Eszközláncolás működés közben — az ügynök először hívja a getCurrentWeather-t, majd az így kapott Celsius eredményt átvezeti a celsiusToFahrenheit-nek, és közös választ ad.* +*Eszközláncolás működés közben — az ügynök először hívja a getCurrentWeather-t, majd a Celsius eredményt átvezeti a celsiusToFahrenheit-nek, és összetett választ ad.* -**Zökkenőmentes hibakezelés** — Kérdezz időjárást egy városról, amely nincs a teszt adatok között. Az eszköz hibaüzenetet ad vissza, és az AI elmagyarázza, hogy nem tud segíteni ahelyett, hogy összeomlana. Az eszközök biztonságosan hibáznak. Az alábbi ábra összehasonlítja a két megközelítést — megfelelő hibakezeléssel az ügynök elkapja a kivételt és segítőkész választ ad, hibakezelés nélkül az egész alkalmazás összeomlik: +**Kulturált Hibakezelés** — Kérdezz rá egy város időjárására, ami nincs benne a teszt adatokban. Az eszköz hibát jelez, és az MI elmagyarázza, hogy nem tud segíteni ahelyett, hogy összeomlik. Az eszközök biztonságosan hibáznak. Az alábbi diagram összehasonlítja a két megközelítést — megfelelő hibakezeléssel az ügynök elkapja a kivételt és segítőkész választ ad, hibakezelés nélkül pedig az egész alkalmazás összeomlik: -Error Handling Flow +Hibakezelési Folyamat -*Ha egy eszköz hibázik, az ügynök elkapja a hibát és segítőkész magyarázattal válaszol az összeomlás helyett.* +*Ha egy eszköz hibát okoz, az ügynök elkapja és inkább hasznos magyarázattal válaszol, nem pedig összeomlik.* -Ez egyetlen beszélgetési körben történik. Az ügynök önállóan koordinál több eszköz hívást. +Ez egyetlen beszélgetési körben történik. Az ügynök önállóan koordinál több eszközhívást. -## Az alkalmazás futtatása +## Az Alkalmazás Futattása **Telepítés ellenőrzése:** -Győződj meg róla, hogy a `.env` fájl létezik a gyökérkönyvtárban az Azure hitelesítőkkel (az 01. modul során jött létre). Futtasd ezt a modul könyvtárából (`04-tools/`): +Ellenőrizd, hogy a `.env` fájl létezik a gyökérkönyvtárban Azure hitelesítő adatokkal (az 01. modul során készült). Futtasd ezt a modul könyvtárában (`04-tools/`): **Bash:** ```bash -cat ../.env # Meg kell jeleníteni az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket +cat ../.env # Meg kell jelenítenie az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket ``` **PowerShell:** ```powershell -Get-Content ..\.env # Meg kell jeleníteni az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket +Get-Content ..\.env # Meg kell jelenítenie az AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT értékeket ``` -**Alkalmazás indítása:** +**Indítsd el az alkalmazást:** -> **Megjegyzés:** Ha már elindítottad az összes alkalmazást a gyökérkönyvtárból `./start-all.sh`-al (ahogy az 01. modulban le van írva), akkor ez a modul már fut a 8084-es porton. Az indítási parancsokat ilyenkor kihagyhatod, és közvetlenül a http://localhost:8084 címre mehetsz. +> **Megjegyzés:** Ha már elindítottad az összes alkalmazást a gyökérkönyvtárból `./start-all.sh` használatával (amint az az 01. modulban szerepel), akkor ez a modul már fut a 8084-es porton. Átugorhatod a lentebb lévő indító parancsokat, és közvetlenül a http://localhost:8084 címre mehetsz. -**1. lehetőség: Spring Boot Dashboard használata (VS Code felhasználóknak ajánlott)** +**1. lehetőség: Spring Boot Dashboard használata (ajánlott VS Code felhasználóknak)** -A fejlesztői konténer tartalmazza a Spring Boot Dashboard bővítményt, amely vizuális felületet biztosít az összes Spring Boot alkalmazás kezeléséhez. A VS Code bal oldali Tevékenység sávjában találod (keresd a Spring Boot ikont). +A fejlesztői konténer tartalmazza a Spring Boot Dashboard bővítményt, amely vizuális felületet biztosít minden Spring Boot alkalmazás kezeléséhez. A bal oldali tevékenységsávban találod a Spring Boot ikont. -A Spring Boot Dashboard segítségével: -- Megnézheted az összes elérhető Spring Boot alkalmazást a munkaterületen +A Spring Boot Dashboard-ból: +- Láthatod az összes elérhető Spring Boot alkalmazást a munkaterületen - Egy kattintással indíthatsz/leállíthatsz alkalmazásokat -- Valós időben láthatod az alkalmazások naplóit -- Figyelemmel kísérheted az alkalmazás állapotát -Egyszerűen kattints a lejátszás gombra a "tools" mellett, hogy elindítsd ezt a modult, vagy indíts el egyszerre minden modult. +- Valós időben megtekintheted az alkalmazás naplóit +- Figyelheted az alkalmazás állapotát -Így néz ki a Spring Boot Dashboard a VS Code-ban: +Egyszerűen kattints a "tools" melletti lejátszás gombra ennek a modulnak az indításához, vagy indítsd el az összes modult egyszerre. -Spring Boot Dashboard +Így néz ki a Spring Boot Dashboard a VS Code-ban: +Spring Boot műszerfal -*A Spring Boot Dashboard a VS Code-ban — indítsd, állítsd le és figyeld az összes modult egy helyről* +*A Spring Boot műszerfal a VS Code-ban — indítsd, állítsd le és figyeld az összes modult egy helyről* -**2. lehetőség: Shell scriptek használata** +**2. lehetőség: Shell szkriptek használata** -Indítsd el az összes webalkalmazást (a 01-04 modulok): +Indítsd el az összes webalkalmazást (01-04 modulok): **Bash:** ```bash -cd .. # Gyökérkönyvtárból +cd .. # A gyökérkönyvtárból ./start-all.sh ``` @@ -242,7 +242,7 @@ cd .. # A gyökérkönyvtárból .\start-all.ps1 ``` -Vagy indítsd csak ezt a modult: +Vagy indítsd el csak ezt a modult: **Bash:** ```bash @@ -256,16 +256,16 @@ cd 04-tools .\start.ps1 ``` -Mindkét script automatikusan betölti a környezeti változókat a gyökér `.env` állományból, és lefordítja a JAR-okat, ha még nem léteznek. +Mindkét szkript automatikusan betölti a környezeti változókat a gyökér `.env` fájlból, és felépíti a JAR fájlokat, ha azok nem léteznek. -> **Megjegyzés:** Ha inkább manuálisan akarod lefordítani az összes modult az indítás előtt: +> **Megjegyzés:** Ha inkább kézzel akarod felépíteni az összes modult indulás előtt: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -292,84 +292,84 @@ cd ..; .\stop-all.ps1 # Minden modul ## Az alkalmazás használata -Az alkalmazás egy webes felületet biztosít, ahol egy AI ügynökkel kommunikálhatsz, aki rendelkezik időjárás- és hőmérséklet-konvertáló eszközökkel. Íme, így néz ki a felület — tartalmaz gyorsindítási példákat és egy csevegőpanelt a kérések elküldéséhez: +Az alkalmazás webes felületet biztosít, ahol egy AI ügynökkel léphetsz kapcsolatba, mely hozzáfér időjárás- és hőmérséklet-konvertáló eszközökhöz. Így néz ki a felület — tartalmaz gyorsindító példákat és egy chat panelt a kérések küldéséhez: -AI Agent Tools Interface +AI Ügynök Eszközök Felület -*Az AI Agent Tools felület – gyors példák és csevegőfelület az eszközökkel való interakcióhoz* +*Az AI Ügynök Eszközök felülete - gyors példák és chat felület az eszközökkel való interakcióhoz* ### Próbálj ki egyszerű eszközhasználatot -Kezdj egy egyszerű kérdéssel: „Alakítsd át 100 Fahrenheit fokot Celsiusra.” Az ügynök felismeri, hogy szüksége van a hőmérséklet-konvertáló eszközre, megfelelő paraméterekkel meghívja, és visszaadja az eredményt. Figyeld meg, milyen természetes ez — nem kellett megadnod, hogy melyik eszközt használd vagy hogyan hívd meg. +Kezdj egy egyszerű kéréssel: „Alakítsd át a 100 Fahrenheit fokot Celsiusra”. Az ügynök felismeri, hogy szüksége van a hőmérséklet-konvertáló eszközre, meghívja a megfelelő paraméterekkel, és visszaadja az eredményt. Figyeld meg, milyen természetes érzés — nem kellett megadnod, melyik eszközt használja vagy hogyan hívja meg. -### Teszteld az eszközök láncolását +### Teszteld az eszköz láncolást -Most próbálj valami bonyolultabbat: „Milyen az időjárás Seattle-ben, és alakítsd át Fahrenheitbe?” Nézd meg, hogyan dolgozza fel ezt az ügynök lépésről lépésre. Először lekéri az időjárást (ami Celsiusban ad választ), felismeri, hogy át kell váltani Fahrenheitbe, meghívja a konverziós eszközt, majd egyesíti mindkét eredményt egy válaszba. +Most próbálj valami bonyolultabbat: „Milyen az időjárás Seattle-ben és alakítsd át Fahrenheitre?” Nézd, ahogy az ügynök lépésenként dolgozik. Először lekéri az időjárást (ami Celsiusban ad választ), felismeri, hogy át kell konvertálni Fahrenheitre, meghívja a konverziós eszközt, majd összefűzi mindkét eredményt egy válaszba. -### Nézd meg a beszélgetés folyamatát +### Nézd meg a beszélgetés menetét -A csevegőfelület megőrzi a beszélgetés előzményeit, így több lépésből álló interakciókat folytathatsz. Láthatod az összes korábbi kérdést és választ, így könnyű követni a párbeszédet és megérteni, hogyan építi fel az ügynök a kontextust több csere során. +A chat felület megőrzi a beszélgetés előzményeit, lehetővé téve a többlépcsős interakciókat. Láthatod az összes korábbi kérdést és választ, így könnyű nyomon követni a párbeszédet és megérteni, hogyan építi fel az ügynök a kontextust több forduló alatt. -Conversation with Multiple Tool Calls +Többszörös eszközhívásokkal folytatott beszélgetés -*Többszörös lépéses beszélgetés egyszerű átváltásokról, időjárás-lekérdezésekről és eszközláncolásról* +*Többlépcsős beszélgetés egyszerű átalakításokról, időjárás lekérdezésekről és eszköz láncolásról* ### Kísérletezz különféle kérésekkel Próbálj ki különböző kombinációkat: -- Időjárás lekérdezése: „Milyen az időjárás Tokióban?” -- Hőmérséklet átváltások: „Mennyi 25°C Kelvinben?” -- Összetett kérdések: „Nézd meg az időjárást Párizsban, és mondd meg, ha 20°C fölött van” +- Időjárás lekérdezések: „Milyen az időjárás Tokióban?” +- Hőmérséklet átváltások: „Mennyi 25 °C Kelvinben?” +- Összetett kérdések: „Nézd meg az időjárást Párizsban, és mondd meg, hogy 20 °C felett van-e” -Vedd észre, hogyan értelmezi az ügynök a természetes nyelvet, és hogyan kapcsolja össze a megfelelő eszközhívásokkal. +Figyeld meg, ahogy az ügynök a természetes nyelvet értelmezi és hozzárendeli a megfelelő eszközhívásokat. -## Kulcsfontosságú fogalmak +## Főbb fogalmak ### ReAct minta (Gondolkodás és Cselekvés) -Az ügynök váltogat a gondolkodás (döntés, mit tegyen) és a cselekvés (eszközök használata) között. Ez a minta lehetővé teszi az autonóm problémamegoldást az egyszerű utasításokra adott válasz helyett. +Az ügynök váltogat a gondolkodás (döntés, mit tegyen) és a cselekvés (eszközök használata) között. Ez a minta lehetővé teszi az autonóm problémamegoldást, nem csak az utasításokra adott válaszokat. -### Az eszközleírások jelentősége +### Az eszközleírások fontossága -Az eszközleírások minősége közvetlenül befolyásolja, hogy az ügynök mennyire jól használja őket. A világos, pontos leírások segítenek a modellnek megérteni, mikor és hogyan hívja meg az adott eszközt. +Az eszközleírások minősége közvetlenül befolyásolja, hogy az ügynök mennyire jól használja őket. Egyértelmű, pontos leírások segítik a modellt megérteni, mikor és hogyan hívja meg az adott eszközt. ### Munkamenet-kezelés -Az `@MemoryId` annotáció lehetővé teszi az automatikus munkamenetalapú memória kezelést. Minden munkamenetazonosítóhez saját `ChatMemory` példány tartozik, amit a `ChatMemoryProvider` bean kezel, így több felhasználó egyszerre is kommunikálhat az ügynökkel anélkül, hogy összekeverednének a beszélgetéseik. Az alábbi ábra bemutatja, hogyan irányítódnak a felhasználók elkülönített memóriatárolókhoz az azonosítóik alapján: +Az `@MemoryId` annotáció lehetővé teszi az automatikus munkamenetalapú memória kezelését. Minden munkamenet ID saját `ChatMemory` példányt kap, melyet a `ChatMemoryProvider` bean kezel, így egyszerre több felhasználó is kommunikálhat az ügynökkel anélkül, hogy egymás beszélgetéseit látnák. Az alábbi ábra mutatja, hogyan irányítja a rendszer a felhasználókat különálló memória tárolókba az ID-jük alapján: -Session Management with @MemoryId +Munkamenet-kezelés @MemoryId-vel -*Minden munkamenetazonosítóhoz elkülönített beszélgetési előzmény tartozik — a felhasználók soha nem látják egymás üzeneteit.* +*Minden munkamenet ID különálló beszélgetési előzményhez tartozik — a felhasználók sosem látják egymás üzeneteit.* ### Hibakezelés -Az eszközök hibázhatnak — az API-k időtúlléphetnek, hibásak lehetnek a paraméterek, leállhatnak külső szolgáltatások. A termelési környezetben az ügynököknek kell hibakezelést biztosítani, hogy a modell meg tudja magyarázni a problémákat vagy alternatívákat próbáljon ahelyett, hogy az egész alkalmazás összeomlik. Ha egy eszköz kivételt dob, a LangChain4j elkapja, és a hibaüzenetet visszaküldi a modellnek, ami természetes nyelven magyarázhatja el a problémát. +Az eszközök hibázhatnak — API-k időtúllépnek, hibás paraméterek lehetnek, külső szolgáltatások leállhatnak. A gyártásban használt ügynököknek szükségük van hibakezelésre, hogy a modell elmagyarázhassa a problémákat, vagy alternatívákat próbálhasson ahelyett, hogy az egész alkalmazás összeomlana. Ha egy eszköz kivételt dob, a LangChain4j elkapja azt, majd visszajuttatja a hibaüzenetet a modellnek, amely természetes nyelven képes elmagyarázni a problémát. ## Elérhető eszközök -Az alábbi ábra a használható eszközök széles ökoszisztémáját mutatja be. Ez a modul az időjárás- és hőmérséklet-eszközöket demonstrálja, de ugyanaz az `@Tool` minta bármely Java metódusra alkalmazható — az adatbázis-lekérdezésektől a fizetési feldolgozásig. +Az alábbi ábra bemutatja az eszközök széles ökoszisztémáját, amelyet építhetsz. Ez a modul időjárás- és hőmérséklet-eszközöket mutat be, de az `@Tool` minta bármilyen Java metódusra működik — az adatbázis-lekérdezésektől a fizetési feldolgozásig. -Tool Ecosystem +Eszközök ökoszisztémája -*Minden Java metódus, amelyet az @Tool annotációval látsz el, elérhetővé válik az AI számára — a minta kiterjed adatbázisokra, API-kra, e-mailekre, fájlműveletekre és még sok másra.* +*Bármely `@Tool` annotációval ellátott Java metódus elérhetővé válik az AI számára — a minta kiterjed adatbázisokra, API-kra, e-mailekre, fájlműveletekre és még sok másra.* -## Mikor használjunk eszköz-alapú ügynököket +## Mikor használj eszköz-alapú ügynököket -Nem minden kérés igényli az eszközöket. A döntés azon múlik, hogy az AI-nak szüksége van-e külső rendszerekkel való interakcióra, vagy a saját tudásából válaszolhat-e. Az alábbi útmutató összefoglalja, mikor adnak értéket az eszközök és mikor nincs rájuk szükség: +Nem minden kérés igényel eszközöket. A döntés azon múlik, hogy az AI-nak szüksége van-e külső rendszerekkel való interakcióra, vagy saját tudásából tud válaszolni. Az alábbi útmutató összefoglalja, mikor tesznek hozzá értéket az eszközök, és mikor feleslegesek: -When to Use Tools +Mikor használjunk eszközöket -*Gyors döntési útmutató — az eszközök valós idejű adatokhoz, számításokhoz és műveletekhez valók; az általános tudás és kreatív feladatok nem igénylik őket.* +*Egy gyors döntési útmutató — az eszközök valós idejű adatokra, számításokra és műveletekre valók; az általános tudás és kreatív feladatok nem igénylik őket.* -## Eszközök vs RAG +## Eszközök vs. RAG -A 03 és 04 modulok mindegyike kibővíti, hogy az AI mit tud, de alapvetően eltérő módon. A RAG a modellnek ad **ismeretet** azáltal, hogy dokumentumokat keres elő. Az eszközök a modellnek képességet adnak **műveletek végrehajtására** függvényhívásokkal. Az alábbi ábra ezt a két megközelítést hasonlítja össze egymás mellett — a működési módoktól a közöttük lévő kompromisszumokig: +A 03-as és 04-es modulok egyaránt bővítik az AI képességeit, ám alapvetően más módon. A RAG a modellt **tudással** látja el dokumentumok előhívásával. Az eszközök a modellnek cselekvési képességet adnak függvényhívások által. Az alábbi ábra összehasonlítja ezt a két megközelítést egymás mellett — hogyan működik mindkét munkafolyamat és milyen kompromisszumokat rejtenek: -Tools vs RAG Comparison +Eszközök és RAG összehasonlítása -*A RAG statikus dokumentumokból szerez információt — az Eszközök műveleteket hajtanak végre és dinamikus, valós idejű adatokat kérnek le. Sok termelési rendszer mindkettőt kombinálja.* +*A RAG statikus dokumentumokból gyűjt információt — az eszközök műveleteket hajtanak végre és dinamikus, valós idejű adatokat szereznek. Sok termelési rendszer mindkettőt használja.* -Gyakorlatban számos termelési rendszer mindkét megközelítést alkalmazza: RAG-ot arra, hogy az válaszokat a dokumentációdban megalapozza, és Eszközöket a valós adatok lekérésére vagy műveletek végrehajtására. +Gyakorlatban sok termelési rendszer kombinálja a két megoldást: RAG a dokumentációban való alátámasztáshoz, és eszközök az élő adatok lekéréséhez vagy műveletek végrehajtásához. ## Következő lépések @@ -382,6 +382,6 @@ Gyakorlatban számos termelési rendszer mindkét megközelítést alkalmazza: R --- -**Jóváhagyás**: -Ez a dokumentum az AI fordítószolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár igyekszünk pontos fordítást biztosítani, kérjük, vegye figyelembe, hogy az automatikus fordítás hibákat vagy pontatlanságokat tartalmazhat. Az eredeti, anyanyelvi dokumentum tekinthető a hiteles forrásnak. Fontos információk esetén professzionális, emberi fordítást javaslunk. Nem vállalunk felelősséget a fordítás használatából eredő félreértésekért vagy téves értelmezésekért. +**Jogi nyilatkozat**: +Ez a dokumentum az AI fordítási szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Fontos információk esetén professzionális emberi fordítást javasolunk. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely ebből a fordításból ered. \ No newline at end of file diff --git a/translations/hu/README.md b/translations/hu/README.md index f71c75763..9831a3772 100644 --- a/translations/hu/README.md +++ b/translations/hu/README.md @@ -2,18 +2,18 @@ # LangChain4j kezdőknek -Egy tanfolyam AI alkalmazások építéséhez LangChain4j-vel és Azure OpenAI GPT-5.2-vel, az alapvető csevegéstől az AI ügynökökig. +Tanfolyam AI alkalmazások építéséhez LangChain4j és Azure OpenAI GPT-5.2 használatával, az alapvető csevegéstől az AI ügynökökig. ### 🌐 Többnyelvű támogatás -#### GitHub Action révén támogatott (Automatizált és Mindig naprakész) +#### GitHub Action segítségével támogatott (Automatizált és mindig naprakész) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](./README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Inkább helyben klónoznál?** +> **Inkább helyileg klónoznál?** > -> Ez a tároló 50+ nyelvi fordítást tartalmaz, ami jelentősen megnöveli a letöltési méretet. Fordítások nélküli klónozáshoz használd a sparse checkout-ot: +> Ez a tároló több mint 50 nyelvi fordítást tartalmaz, ami jelentősen megnöveli a letöltési méretet. A fordítások nélküli klónozáshoz használd a sparse checkout-ot: > > **Bash / macOS / Linux:** > ```bash @@ -29,61 +29,60 @@ Egy tanfolyam AI alkalmazások építéséhez LangChain4j-vel és Azure OpenAI G > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Így minden rendelkezésedre áll a tanfolyam elvégzéséhez, sokkal gyorsabb letöltéssel. +> Ezzel minden szükséges fájlt megkapsz a tanfolyam elvégzéséhez sokkal gyorsabb letöltéssel. ## Tartalomjegyzék -1. [Gyors kezdés](00-quick-start/README.md) - Kezdj el dolgozni a LangChain4j-vel -2. [Bevezetés](01-introduction/README.md) - Ismerd meg a LangChain4j alapjait -3. [Prompt tervezés](02-prompt-engineering/README.md) - Tanuld meg a hatékony prompt tervezést -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Építs intelligens tudásalapú rendszereket -5. [Eszközök](04-tools/README.md) - Integrálj külső eszközöket és egyszerű asszisztenseket -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Dolgozz a Model Context Protocol-lal (MCP) és Agentikus modulokkal +1. [Bevezetés](01-introduction/README.md) - Ismerkedj meg a LangChain4j alapjaival +2. [Prompt tervezés](02-prompt-engineering/README.md) - Sajátítsd el a hatékony prompt tervezést +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Építs intelligens tudásalapú rendszereket +4. [Eszközök](04-tools/README.md) - Integrálj külső eszközöket és egyszerű asszisztenseket +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Dolgozz a Model Context Protocol (MCP) és az agenticus modulokkal ### Videós bemutatók -Minden modulhoz élő közvetítés társul, ahol lépésről lépésre bemutatjuk a koncepciókat és a kódot. +Minden modulhoz tartozik egy élő bemutató, ahol lépésről lépésre végigvezetünk a koncepciókon és a kódon. | Modul | Videó | |--------|-------| -| 01 - Bevezetés | [Kezdés a LangChain4j-vel](https://www.youtube.com/live/nl_troDm8rQ) | +| 01 - Bevezetés | [LangChain4j-vel való kezdés](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - Prompt tervezés | [Prompt tervezés LangChain4j-vel](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG LangChain4j-vel](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Eszközök & 05 - MCP | [AI ügynökök Eszközökkel és MCP-vel](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Eszközök és 05 - MCP | [AI ügynökök eszközökkel és MCP-vel](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## Tanulási útvonal -**Új vagy a LangChain4j-ben?** Nézd meg a [Fogalomtárat](docs/GLOSSARY.md) a kulcsfogalmak és definíciók megértéséhez. +**Új vagy a LangChain4j-ben?** Nézd meg a [Szójegyzéket](docs/GLOSSARY.md) a kulcsfogalmak és kifejezések magyarázatáért. > **Gyors kezdés** 1. Forkold ezt a tárolót a GitHub fiókodba 2. Kattints a **Code** → **Codespaces** fülre → **...** → **Új opciókkal...** -3. Használd az alapértelmezetteket – ez kiválasztja a tanfolyamhoz létrehozott Fejlesztési konténert -4. Kattints a **Kódterület létrehozása** gombra -5. Várj 5-10 percet, amíg a környezet készen áll -6. Ugrás közvetlenül a [Gyors kezdés](./00-quick-start/README.md) szekcióhoz, hogy elkezdhesd! +3. Használd az alapértelmezetteket – ez kiválasztja a tanfolyamhoz készült fejlesztői konténert +4. Kattints a **Codespace létrehozása** gombra +5. Várj 5-10 percet, amíg az környezet készen áll +6. Ugorj közvetlenül a [Bevezetéshez](./01-introduction/README.md) és kezdj neki! -A modulok elvégzése után fedezd fel a [Tesztelési útmutatót](docs/TESTING.md), hogy lásd a LangChain4j tesztelési koncepcióit gyakorlatban. +A modulok teljesítése után fedezd fel a [Tesztelési útmutatót](docs/TESTING.md), hogy lásd a LangChain4j tesztelési koncepcióit működés közben. -> **Megjegyzés:** Ez a képzés egyszerre használ GitHub Modelleket és Azure OpenAI-t. A [Gyors kezdés](00-quick-start/README.md) modul GitHub Modelleket használ (nem szükséges Azure előfizetés), míg az 1-5. modulok Azure OpenAI-t. Ha még nincs, kezdj egy [INGYENES Azure fiókkal](https://aka.ms/azure-free-account). +> **Megjegyzés:** Ez a képzés Azure OpenAI-t használ. Ha még nincs, kezdj egy [INGYENES Azure fiókkal](https://aka.ms/azure-free-account). -## Tanulás GitHub Copilot-tal +## Tanulás GitHub Copilottal -Gyorsan kezdj el kódolni, ha ezt a projektet megnyitod egy GitHub Codespace-ben vagy a helyi fejlesztői környezetedben a mellékelt devcontainer-rel. A tanfolyam során használt devcontainer előre konfigurált a GitHub Copilot AI páros programozáshoz. +Gyors kódolásindításhoz nyisd meg ezt a projektet GitHub Codespace-ben vagy helyi fejlesztői környezetben az ehhez a tanfolyamhoz biztosított devcontainer segítségével. A tanfolyamban használt devcontainer előre konfigurálva tartalmazza a GitHub Copilot-ot AI társprogramozáshoz. -Minden kód példában találsz javasolt kérdéseket, amiket GitHub Copilot-nak tehetsz fel a mélyebb megértés érdekében. Keresd a 💡/🤖 jelzéseket a következőkben: +Minden kódpéldához tartoznak ajánlott kérdések, amelyeket feltehetsz a GitHub Copilot-nak, hogy mélyítsd a megértésed. Keress a 💡/🤖 jelöléseket: - **Java fájlfejlécekben** - Példánként specifikus kérdések -- **Modulok README fájljaiban** - Felfedező kérdések a kód példák után +- **Modul README-kben** - Feltáró kérdések a kódrészletek után -**Használat módja:** Nyisd meg bármely kód fájlt és tedd fel a javasolt kérdéseket Copilot-nak. Teljes kontextusa van a kódalapon, elmagyaráz, kiterjeszt, és alternatívákat javasol. +**Használat:** Nyiss meg egy kódfájlt és tedd fel a javasolt kérdéseket a Copilot-nak. Teljes rálátása van a kódbázisra, így magyarázni, kiegészíteni és alternatívákat javasolni képes. -Szeretnél többet tudni? Nézd meg a [Copilot AI Párprogramozáshoz](https://aka.ms/GitHubCopilotAI) témát. +Szeretnél többet megtudni? Olvasd el a [Copilot AI társprogramozáshoz](https://aka.ms/GitHubCopilotAI) oldalt. ## További források @@ -111,40 +110,41 @@ Szeretnél többet tudni? Nézd meg a [Copilot AI Párprogramozáshoz](https://a --- -### Alapvető tanulás -[![Gépi tanulás kezdőknek](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +### Alapvető tananyag +[![ML kezdőknek](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Adattudomány kezdőknek](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI kezdőknek](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Kiberbiztonság kezdőknek](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Webfejlesztés kezdőknek](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT kezdőknek](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR fejlesztés kezdőknek](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Copilot sorozat -[![Copilot AI páros programozáshoz](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot C#/.NET-hez](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot Kaland](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Segítségkérés -Ha elakad vagy kérdése van az AI alkalmazásfejlesztéssel kapcsolatban, csatlakozz: +Ha elakadnál vagy bármilyen kérdésed van az AI alkalmazások fejlesztésével kapcsolatban, csatlakozz: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Ha termék-visszajelzése vagy hibája van fejlesztés közben, látogasson el ide: +Ha visszajelzésed van a termékről vagy hibákat tapasztalsz fejlesztés közben, látogass el ide: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licenc -MIT Licenc - Részletekért lásd a [LICENSE](../../LICENSE) fájlt. +MIT Licenc - Részletek a [LICENSE](../../LICENSE) fájlban találhatók. --- -**Jogi nyilatkozat**: -Ez a dokumentum az AI fordítószolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár igyekszünk pontosságra, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Kritikus információk esetén professzionális emberi fordítást javaslunk. Nem vállalunk felelősséget a fordítás használatából eredő félreértésekért vagy téves értelmezésekért. +**Jogi nyilatkozat**: +Ez a dokumentum az AI fordítási szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Fontos információk esetén professzionális emberi fordítást javasolunk. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely ebből a fordításból ered. \ No newline at end of file diff --git a/translations/hu/docs/GLOSSARY.md b/translations/hu/docs/GLOSSARY.md index 9f68c48f7..91457a869 100644 --- a/translations/hu/docs/GLOSSARY.md +++ b/translations/hu/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j Szójegyzék +# LangChain4j Szószedet ## Tartalomjegyzék -- [Alapfogalmak](../../../docs) -- [LangChain4j komponensek](../../../docs) -- [AI/ML fogalmak](../../../docs) -- [Guardrails](../../../docs) -- [Prompt mérnökség](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Ügynökök és eszközök](../../../docs) -- [Agentikus modul](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure szolgáltatások](../../../docs) -- [Tesztelés és fejlesztés](../../../docs) +- [Alapfogalmak](#alapfogalmak) +- [LangChain4j Összetevők](#langchain4j-összetevők) +- [AI/ML Fogalmak](#aiml-fogalmak) +- [Biztonsági Keretek](#biztonsági-keretek) +- [Prompt Tervezés](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Ügynökök és Eszközök](#agents-and-tools---module-04) +- [Agentikus Modul](#agentic-module---module-05) +- [Modell Kontextus Protokoll (MCP)](#model-context-protocol-mcp---module-05) +- [Azure Szolgáltatások](#azure-services---module-01) +- [Tesztelés és Fejlesztés](#testing-and-development---testing-guide) Gyors hivatkozás a kurzus során használt kifejezésekhez és fogalmakhoz. ## Alapfogalmak -**AI ügynök** - Olyan rendszer, amely AI-t használ önálló gondolkodásra és cselekvésre. [Module 04](../04-tools/README.md) +**AI Ügynök** - Olyan rendszer, amely AI-t használ önálló érvelésre és cselekvésre. [Module 04](../04-tools/README.md) -**Lánc** - Műveletsorozat, ahol az eredmény a következő lépés bemenete. +**Lánc** - Műveletsorozat, ahol az eredmény a következő lépés bemenetévé válik. -**Darabolás** - Dokumentumok kisebb részekre bontása. Tipikus: 300-500 token átfedéssel. [Module 03](../03-rag/README.md) +**Darabolás (Chunking)** - Dokumentumok kisebb darabokra bontása. Általános: 300-500 token átfedéssel. [Module 03](../03-rag/README.md) -**Kontextus ablak** - Maximális token szám, amelyet egy modell feldolgozni tud. GPT-5.2: 400K token (legfeljebb 272K bemenet, 128K kimenet). +**Kontekstus Ablak** - Maximális tokenek száma, amit a modell képes feldolgozni. GPT-5.2: 400K token (legfeljebb 272K bemenet, 128K kimenet). -**Beágyazások** - Numerikus vektorok, amelyek a szöveg jelentését reprezentálják. [Module 03](../03-rag/README.md) +**Beágyazások (Embeddings)** - Numerikus vektorok, amelyek a szöveg jelentését reprezentálják. [Module 03](../03-rag/README.md) -**Funkcióhívás** - A modell strukturált kéréseket generál külső funkciók meghívására. [Module 04](../04-tools/README.md) +**Függvényhívás (Function Calling)** - A modell strukturált kéréseket generál külső függvények meghívására. [Module 04](../04-tools/README.md) **Hallucináció** - Amikor a modellek helytelen, de hihető információt generálnak. -**Prompt** - Szöveges bemenet a nyelvi modellnek. [Module 02](../02-prompt-engineering/README.md) +**Prompt** - Szöveges bemenet egy nyelvi modellhez. [Module 02](../02-prompt-engineering/README.md) -**Szemantikus keresés** - Keresés a jelentés alapján, beágyazásokat használva, nem kulcsszavakat. [Module 03](../03-rag/README.md) +**Szemantikus Keresés** - A jelentés alapján keres, beágyazásokat használva, nem kulcsszavakat. [Module 03](../03-rag/README.md) -**Állapotmentes vs állapotőr** - Állapotmentes: nincs memóriája. Állapotőr: megőrzi a beszélgetés előzményeit. [Module 01](../01-introduction/README.md) +**Állapotkezelés nélküli vs Állapotkezelő** - Stateless: nincs memória. Stateful: megőrzi a beszélgetés történetét. [Module 01](../01-introduction/README.md) -**Tokenek** - Alapvető szövegegységek, amelyeket a modellek feldolgoznak. Hatással vannak a költségekre és korlátokra. [Module 01](../01-introduction/README.md) +**Tokenek** - Alapvető szövegegységek, amelyeket a modellek feldolgoznak. Befolyásolja a költségeket és korlátokat. [Module 01](../01-introduction/README.md) -**Eszköz láncolás** - Eszközök egymás utáni végrehajtása, ahol az eredmény befolyásolja a következő hívást. [Module 04](../04-tools/README.md) +**Eszközláncolás** - Eszközök egymás utáni végrehajtása, ahol az eredmény befolyásolja a következő hívást. [Module 04](../04-tools/README.md) -## LangChain4j komponensek +## LangChain4j Összetevők **AiServices** - Típusbiztos AI szolgáltatás interfészek létrehozása. **OpenAiOfficialChatModel** - Egyesített kliens az OpenAI és Azure OpenAI modellekhez. -**OpenAiOfficialEmbeddingModel** - Beágyazások létrehozása az OpenAI hivatalos kliensével (támogatja mindkettőt: OpenAI és Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Beágyazások létrehozása az OpenAI Official klienssel (támogatja az OpenAI-t és Azure OpenAI-t is). -**ChatModel** - Nyelvi modellek fő interfésze. +**ChatModel** - Alapvető interfész nyelvi modellekhez. -**ChatMemory** - Megőrzi a beszélgetés előzményeit. +**ChatMemory** - A beszélgetés előzményeinek tárolása. -**ContentRetriever** - Megtalálja a releváns dokumentumdarabokat RAG-hez. +**ContentRetriever** - Releváns dokumentumdarabokat keres RAG-hoz. -**DocumentSplitter** - Dokumentumokat tördel darabokra. +**DocumentSplitter** - Dokumentumokat darabol darabokra. **EmbeddingModel** - Szöveget numerikus vektorokká alakít. -**EmbeddingStore** - Beágyazások tárolása és lekérése. +**EmbeddingStore** - Beágyazások tárolása és előhívása. -**MessageWindowChatMemory** - Az utolsó üzenetek mozgóablakát kezeli. +**MessageWindowChatMemory** - Az utóbbi üzenetek csúszó ablakának tárolása. -**PromptTemplate** - Újrafelhasználható promtok létrehozása `{{variable}}` helyőrzőkkel. +**PromptTemplate** - Újrahasználható promptok létrehozása `{{variable}}` helyőrzőkkel. -**TextSegment** - Szöveg darab metaadatokkal. RAG-ben használatos. +**TextSegment** - Metadatákkal ellátott szövegrész. Használt RAG-ban. -**ToolExecutionRequest** - Az eszköz végrehajtási kérésének reprezentációja. +**ToolExecutionRequest** - Eszközvégrehajtási kérés reprezentációja. -**UserMessage / AiMessage / SystemMessage** - Beszélgetési üzenettípusok. +**UserMessage / AiMessage / SystemMessage** - Beszélgetés üzenettípusai. -## AI/ML fogalmak +## AI/ML Fogalmak -**Few-Shot Learning** - Példák biztosítása promptokban. [Module 02](../02-prompt-engineering/README.md) +**Few-Shot Tanulás** - Példák megadása a promptokban. [Module 02](../02-prompt-engineering/README.md) -**Nagy nyelvi modell (LLM)** - Nagy mennyiségű szöveg alapján tanított AI modellek. +**Nagy Nyelvi Modell (LLM)** - Hatalmas szövegadatokon tanított AI modellek. -**Gondolkodási erőfeszítés** - GPT-5.2 paraméter, ami befolyásolja a gondolkodás mélységét. [Module 02](../02-prompt-engineering/README.md) +**Érvelési Erőfeszítés** - GPT-5.2 paraméter, amely az érvelés mélységét szabályozza. [Module 02](../02-prompt-engineering/README.md) -**Hőmérséklet** - A kimenet véletlenszerűségét szabályozza. Alacsony=determinista, magas=kreatív. +**Hőmérséklet** - A kimenet véletlenszerűségének szabályozása. Alacsony=detereminisztikus, magas=alkotó. -**Vektoradatbázis** - Beágyazásokra specializált adatbázis. [Module 03](../03-rag/README.md) +**Vektor Adatbázis** - Beágyazásokhoz specializált adatbázis. [Module 03](../03-rag/README.md) -**Zero-Shot Learning** - Feladat végrehajtása példa nélkül. [Module 02](../02-prompt-engineering/README.md) +**Zero-Shot Tanulás** - Feladatok elvégzése példák nélkül. [Module 02](../02-prompt-engineering/README.md) -## Guardrails - [Module 00](../00-quick-start/README.md) +## Biztonsági Keretek -**Mélységi védelem** - Többrétegű biztonsági megközelítés, amely az alkalmazásszintű guardrail-eket kombinálja a szolgáltató biztonsági szűrőivel. +**Mélységi Védelem** - Többrétegű biztonsági megközelítés, amely az alkalmazásszintű biztonsági kereteket szolgáltatói biztonsági szűrőkkel kombinálja. -**Kemény blokkolás** - A szolgáltató HTTP 400 hibát dob súlyos tartalmi szabálysértés esetén. +**Kemény Blokkolás** - A szolgáltató HTTP 400-as hibát dob súlyos tartalmi megsértések esetén. -**InputGuardrail** - LangChain4j interfész a felhasználói bemenet ellenőrzésére, mielőtt az LLM-hez jutna. Költséget és késleltetést spórol, mert korán blokkolja a káros promptokat. +**InputGuardrail** - LangChain4j interfész a felhasználói bemenet érvényesítésére, mielőtt az eléri az LLM-et. Költség- és késleltetés-megtakarítás az ártalmas promptok korai blokkolásával. **InputGuardrailResult** - Guardrail ellenőrzés visszatérési típusa: `success()` vagy `fatal("ok")`. -**OutputGuardrail** - Interfész AI válaszok ellenőrzésére, mielőtt visszajutnak a felhasználókhoz. +**OutputGuardrail** - Interfész az AI válaszok érvényesítésére, mielőtt visszaküldik a felhasználónak. -**Szolgáltató biztonsági szűrők** - AI szolgáltatók beépített tartalomszűrői (pl. GitHub modellek), amelyek API szinten észlelik a szabálysértéseket. +**Szolgáltatói Biztonsági Szűrők** - Beépített tartalmi szűrők AI szolgáltatóktól (pl. Azure OpenAI), amelyek az API szinten fogják az áthágásokat. -**Lágy elutasítás** - A modell udvariasan megtagadja a választ anélkül, hogy hibát dobna. +**Lágy Elutasítás** - A modell udvariasan megtagadja a választ anélkül, hogy hibát dobna. -## Prompt mérnökség - [Module 02](../02-prompt-engineering/README.md) +## Prompt Tervezés - [Module 02](../02-prompt-engineering/README.md) -**Gondolatmenet-lánc** - Lépésenkénti érvelés a jobb pontosságért. +**Gondolatmenet Lánc** - Lépésenkénti érvelés a jobb pontosságért. -**Korlátozott kimenet** - Meghatározott formátum vagy szerkezet kikényszerítése. +**Korlátozott Kimenet** - Meghatározott formátum vagy struktúra érvényesítése. -**Magas igyekezet** - GPT-5.2 minta a részletes érveléshez. +**Magas Lelkesedés** - GPT-5.2 minta a mélyreható érveléshez. -**Alacsony igyekezet** - GPT-5.2 minta a gyors válaszokhoz. +**Alacsony Lelkesedés** - GPT-5.2 minta gyors válaszokhoz. -**Többkörös beszélgetés** - Kontextus fenntartása az üzenetváltások között. +**Többfordulós Beszélgetés** - Kontextus megőrzése az üzenetváltások között. -**Szerepalapú promptolás** - Modell személyiség beállítása rendszerüzenetekkel. +**Szerepalapú Promptolás** - Modell személyiségének beállítása rendszerüzeneteken keresztül. -**Önreflexió** - A modell értékeli és fejleszti a saját kimenetét. +**Önreflexió** - A modell értékeli és javítja a saját kimenetét. -**Strukturált elemzés** - Rögzített értékelési keretrendszer. +**Strukturált Elemzés** - Rögzített értékelési keretrendszer. -**Feladatvégrehajtási minta** - Tervezés → Végrehajtás → Összefoglalás. +**Feladatvégrehajtási Minta** - Terv → Végrehajtás → Összegzés. ## RAG (Retrieval-Augmented Generation) - [Module 03](../03-rag/README.md) -**Dokumentumfeldolgozó csővezeték** - Betöltés → darabolás → beágyazás → tárolás. +**Dokumentumfeldolgozó Folyamat** - Betöltés → darabolás → beágyazás → tárolás. -**Memóriabeli beágyazás tároló** - Nem tartós tároló teszteléshez. +**Memóriabeli Beágyazás Tároló** - Nem perzisztens tároló teszteléshez. -**RAG** - Kombinálja a keresést és generálást a válaszok megalapozásához. +**RAG** - Összekapcsolja a lekérdezést a generálással, hogy megalapozott válaszokat adjon. -**Hasonlósági pontszám** - (0-1) számszerűsíti a szemantikus hasonlóságot. +**Hasonlósági Pontszám** - A szemantikai hasonlóság mértéke (0-1 között). -**Forrás referencia** - Lekért tartalom metaadatai. +**Forrás Hivatkozás** - Metaadat a lekért tartalomról. -## Ügynökök és eszközök - [Module 04](../04-tools/README.md) +## Ügynökök és Eszközök - [Module 04](../04-tools/README.md) -**@Tool annotáció** - Java metódusokat jelöl AI által hívható eszközökként. +**@Tool Annotáció** - Java metódusokat jelöl AI-hívható eszközökként. -**ReAct minta** - Érvelés → cselekvés → megfigyelés → ismétlés. +**ReAct Minta** - Érvelés → Cselekvés → Megfigyelés → Ismétlés. -**Munkamenet kezelés** - Különböző felhasználók külön kontextusai. +**Munkamenet Kezelés** - Különálló kontextusok különböző felhasználók számára. -**Eszköz** - Funkció, amit AI ügynök meghívhat. +**Eszköz** - Olyan funkció, amelyet az AI ügynök meghívhat. -**Eszköz leírás** - Dokumentáció az eszköz céljáról és paramétereiről. +**Eszköz Leírás** - Dokumentáció az eszköz céljáról és paramétereiről. -## Agentikus modul - [Module 05](../05-mcp/README.md) +## Agentikus Modul - [Module 05](../05-mcp/README.md) -**@Agent annotáció** - Interfészeket jelöl AI ügynökökként deklaratív viselkedésdefinícióval. +**@Agent Annotáció** - Interfészeket jelöl AI ügynökökként deklaratív viselkedésdefinícióval. -**Agent Listener** - Hook az ügynök végrehajtásának megfigyelésére `beforeAgentInvocation()` és `afterAgentInvocation()` segítségével. +**Agent Listener** - Horog az ügynök végrehajtásának figyelésére `beforeAgentInvocation()` és `afterAgentInvocation()` segítségével. -**Agentikus hatókör** - Megosztott memória, ahol az ügynökök az `outputKey` segítségével tárolják az eredményeket a következő ügynökök számára. +**Agentikus Terület** - Megosztott memória, ahol az ügynökök az outputokat tárolják `outputKey` használatával, hogy a downstream ügynökök hozzáférjenek. -**AgenticServices** - Ügynökök létrehozó gyára `agentBuilder()` és `supervisorBuilder()` használatával. +**AgenticServices** - Ügynökök létrehozására szolgáló gyár `agentBuilder()` és `supervisorBuilder()` segítségével. -**Feltételes munkafolyamat** - Feltételek alapján irányított út különböző szakértő ügynökökhöz. +**Feltételes Munkafolyamat** - Feltételek alapján irányítás különböző szakértő ügynökökhöz. -**Ember a hurokban** - Munkafolyamat minta, amely emberi ellenőrzőpontokat ad jóváhagyás vagy tartalmi ellenőrzés céljából. +**Humán a Hurokban** - Munkafolyamat minta emberi ellenőrző pontokkal jóváhagyás vagy tartalmi átvizsgálás céljából. **langchain4j-agentic** - Maven függőség deklaratív ügynöképítéshez (kísérleti). -**Ciklus munkafolyamat** - Ügynök végrehajtás ismétlése, amíg a feltétel teljesül (pl. minőségi pontszám ≥ 0.8). +**Ciklus Munkafolyamat** - Az ügynök végrehajtásának ismétlése, amíg a feltétel teljesül (pl. minőségi pontszám ≥ 0.8). -**outputKey** - Ügynök annotáció paraméter, mely megadja, hol tárolódnak az eredmények az Agentikus hatókörben. +**outputKey** - Ügynök annotációs paraméter, amely megadja, hová kerülnek az eredmények az Agentikus Területen. -**Párhuzamos munkafolyamat** - Több ügynök párhuzamos futtatása független feladatokra. +**Párhuzamos Munkafolyamat** - Több ügynök egyidejű futtatása független feladatokra. -**Válaszstratégia** - Hogyan fogalmazza meg a felügyelő a végső választ: LEGUTOLSÓ, ÖSSZEFOGLALÓ vagy ÉRTÉKELT. +**Válasz Stratégia** - Hogyan fogalmazza meg a felügyelő a végső választ: LAST, SUMMARY, vagy SCORED. -**Szekvenciális munkafolyamat** - Ügynökök sorrendben végrehajtva, ahol az eredmény továbbáramlik a következő lépéshez. +**Sorrendiségi Munkafolyamat** - Ügynökök végrehajtása sorrendben, ahol az eredmény továbbáramlik a következő lépésre. -**Felügyelő ügynök minta** - Fejlett ügynökös minta, ahol a felügyelő LLM dinamikusan dönti el, mely al-ügynököket hívja meg. +**Felügyelő Ügynök Minta** - Haladó agentikus minta, ahol egy felügyelő LLM dinamikusan dönt a részügynökök meghívásáról. -## Model Context Protocol (MCP) - [Module 05](../05-mcp/README.md) +## Modell Kontextus Protokoll (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - Maven függőség MCP integrációhoz LangChain4j-ben. +**langchain4j-mcp** - Maven függőség az MCP integrációhoz LangChain4j-ben. -**MCP** - Model Context Protocol: szabvány AI alkalmazások csatlakoztatására külső eszközökhöz. Egyszer építsd fel, bárhol használd. +**MCP** - Modell Kontextus Protokoll: szabvány AI alkalmazások külső eszközökhöz való csatlakoztatására. Egyszer építed, mindenhol használod. -**MCP kliens** - Alkalmazás, amely MCP szerverekhez csatlakozik, hogy eszközöket fedezzen fel és használjon. +**MCP Kliens** - Alkalmazás, amely MCP szerverekhez csatlakozik eszközök felderítésére és használatára. -**MCP szerver** - Szolgáltatás, amely MCP-n keresztül eszközöket tesz elérhetővé egyértelmű leírásokkal és paraméter sémákkal. +**MCP Szerver** - Szolgáltatás, amely MCP-n keresztül elérhető eszközöket kínál világos leírásokkal és paraméter sémákkal. -**McpToolProvider** - LangChain4j komponens, amely becsomagolja az MCP eszközöket AI szolgáltatások és ügynökök használatára. +**McpToolProvider** - LangChain4j komponens, amely MCP eszközöket csomagol AI szolgáltatások és ügynökök számára. -**McpTransport** - MCP kommunikációs interfész. Megvalósítások között van Stdio és HTTP. +**McpTransport** - Interfész az MCP kommunikációhoz. Megvalósítások között szerepel a Stdio és HTTP. -**Stdio transport** - Helyi folyamat szállítás stdin/stdout-on keresztül. Hasznos fájlrendszer eléréséhez vagy parancssori eszközökhöz. +**Stdio Szállítás** - Helyi folyamat szállítás stdin/stdout-on keresztül. Hasznos fájlrendszer-hozzáféréshez vagy parancssori eszközökhöz. -**StdioMcpTransport** - LangChain4j megvalósítás, amely MCP szervert indít alfolyamatként. +**StdioMcpTransport** - LangChain4j megvalósítás, amely MCP szervert szubprocesszként indít. -**Eszköz felfedezés** - A kliens lekérdezi a szervert az elérhető eszközök leírásaival és sémáival. +**Eszköz Felderítés** - A kliens lekérdezi a szervert az elérhető eszközökről leírásokkal és sémákkal. -## Azure szolgáltatások - [Module 01](../01-introduction/README.md) +## Azure Szolgáltatások - [Module 01](../01-introduction/README.md) -**Azure AI Search** - Felhő alapú keresés vektor támogatással. [Module 03](../03-rag/README.md) +**Azure AI Search** - Felhőalapú keresés vektoros képességekkel. [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Azure erőforrások telepítése. +**Azure Developer CLI (azd)** - Azure erőforrásokat telepít. -**Azure OpenAI** - Microsoft vállalati AI szolgáltatása. +**Azure OpenAI** - A Microsoft vállalati AI szolgáltatása. -**Bicep** - Azure infrastruktúra-kód nyelv. [Infrastrukturális útmutató](../01-introduction/infra/README.md) +**Bicep** - Azure infrastruktúra kódnyelve. [Infrastruktúra Útmutató](../01-introduction/infra/README.md) -**Telepítés neve** - Modell telepítésének neve Azure-ban. +**Telepítés Neve** - Modell telepítésének neve Azure-ban. -**GPT-5.2** - Legújabb OpenAI modell érvelési vezérléssel. [Module 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Legújabb OpenAI modell az érvelés szabályozásával. [Module 02](../02-prompt-engineering/README.md) -## Tesztelés és fejlesztés - [Tesztelési útmutató](TESTING.md) +## Tesztelés és Fejlesztés - [Tesztelési Útmutató](TESTING.md) -**Dev Container** - Konténerizált fejlesztői környezet. [Konfiguráció](../../../.devcontainer/devcontainer.json) +**Fejlesztői Konténer** - Konténerizált fejlesztési környezet. [Konfiguráció](../../../.devcontainer/devcontainer.json) -**GitHub modellek** - Ingyenes AI modell játszótér. [Module 00](../00-quick-start/README.md) +**Memóriabeli Tesztelés** - Tesztelés memóriabeli tárolóval. -**Memóriabeli tesztelés** - Tesztelés memóriabeli tárolóval. - -**Integrációs tesztelés** - Tesztelés valódi infrastruktúrával. +**Integrációs Tesztelés** - Tesztelés valós infrastruktúrával. **Maven** - Java build automatizációs eszköz. -**Mockito** - Java mocking könyvtár. +**Mockito** - Java mockolási keretrendszer. -**Spring Boot** - Java alkalmazáskeretrendszer. [Module 01](../01-introduction/README.md) +**Spring Boot** - Java alkalmazás keretrendszer. [Module 01](../01-introduction/README.md) --- **Jogi nyilatkozat**: -Ez a dokumentum az [Co-op Translator](https://github.com/Azure/co-op-translator) mesterséges intelligencia alapú fordító szolgáltatásával készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Kritikus információk esetén professzionális emberi fordítást javaslunk. Nem vállalunk felelősséget az e fordítás használatából eredő félreértésekért vagy félreértelmezésekért. +Ez a dokumentum az AI fordítási szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Fontos információk esetén professzionális emberi fordítást javasolunk. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely ebből a fordításból ered. \ No newline at end of file diff --git a/translations/hu/docs/TESTING.md b/translations/hu/docs/TESTING.md index 87c687380..18f17c1d6 100644 --- a/translations/hu/docs/TESTING.md +++ b/translations/hu/docs/TESTING.md @@ -2,19 +2,19 @@ ## Tartalomjegyzék -- [Gyors Kezdet](../../../docs) -- [Mit Fednek Le a Tesztek](../../../docs) -- [A Tesztek Futtatása](../../../docs) -- [Tesztek Futtatása VS Code-ban](../../../docs) -- [Tesztelési Minták](../../../docs) -- [Tesztelési Filozófia](../../../docs) -- [Következő Lépések](../../../docs) +- [Gyors Kezdés](#gyors-kezdés) +- [Mit Fednek Le a Tesztek](#mit-fednek-le-a-tesztek) +- [Tesztek Futtatása](#tesztek-futtatása) +- [Tesztek Futtatása VS Code-ban](#tesztek-futtatása-vs-code-ban) +- [Tesztelési Minták](#tesztelési-minták) +- [Tesztelési Filozófia](#tesztelési-filozófia) +- [Következő Lépések](#következő-lépések) -Ez az útmutató végigvezet a teszteken, amelyek bemutatják, hogyan lehet AI alkalmazásokat tesztelni API kulcsok vagy külső szolgáltatások használata nélkül. +Ez az útmutató végigvezet a teszteken, amelyek bemutatják, hogyan lehet AI alkalmazásokat tesztelni API-kulcsok vagy külső szolgáltatások nélkül. -## Gyors Kezdet +## Gyors Kezdés -Futtasd az összes tesztet egyetlen parancs segítségével: +Futtass minden tesztet egyetlen parancssal: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Ha minden teszt sikeresen lefut, az alábbi képernyőképen láthatóhoz hasonló kimenetet kell látnod — tesztek nulla hibával futnak. +Ha minden teszt sikeresen lefut, a következő képernyőképhez hasonló kimenetet látsz — a tesztek eredménye nulla hiba. Sikeres Teszteredmények -*Sikeres tesztfuttatás, amely mutatja, hogy minden teszt átment, nulla hibával* +*Sikeres tesztfuttatás, amelyen minden teszt hibamentesen átmegy* ## Mit Fednek Le a Tesztek -Ez a kurzus **egységtesztekre** fókuszál, amelyek helyben futnak. Minden teszt egy egyedi LangChain4j koncepciót mutat be elszigetelten. Az alábbi tesztelési piramis megmutatja, hol helyezkednek el az egységtesztek — ők alkotják a gyors, megbízható alapot, amelyre a többi tesztelési stratégia épül. +Ez a kurzus elsősorban **unit tesztekre** fókuszál, amelyeket helyben futtatunk. Minden teszt egy adott LangChain4j koncepciót mutat be izoláltan. Az alábbi tesztpiramis megmutatja, hova illeszkednek az unit tesztek — ezek alkotják a gyors, megbízható alapot, amelyre a további tesztstratégia épül. Tesztelési Piramis -*Tesztelési piramis, amely mutatja az egységtesztek (gyors, elszigetelt), integrációs tesztek (valós komponensek) és end-to-end tesztek egyensúlyát. Ez a képzés az egységtesztelést fedi le.* +*Tesztelési piramis, amely az unit tesztek (gyors, izolált), integrációs tesztek (valós komponensek) és end-to-end tesztek közötti egyensúlyt ábrázolja. Ez a képzés az unit tesztelést fedi.* | Modul | Tesztek | Fókusz | Kulcsfájlok | |--------|-------|-------|-----------| -| **00 - Gyors Kezdet** | 6 | Parancssablonok és változó behelyettesítés | `SimpleQuickStartTest.java` | -| **01 - Bevezetés** | 8 | Beszélgetés memória és állapot-alapú chat | `SimpleConversationTest.java` | -| **02 - Prompt Mérnökség** | 12 | GPT-5.2 minták, buzgósági szintek, strukturált kimenet | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Dokumentum-beolvasás, beágyazások, hasonlóság keresés | `DocumentServiceTest.java` | -| **04 - Eszközök** | 12 | Függvényhívás és eszközláncolás | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol stdio átvitel használatával | `SimpleMcpTest.java` | +| **01 - Bevezetés** | 8 | Beszélgetés memóriája és állapotfüggő chat | `SimpleConversationTest.java` | +| **02 - Prompt Tervezés** | 12 | GPT-5.2 minták, lelkesedési szintek, strukturált kimenet | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Dokumentum feldolgozás, beágyazások, hasonlóság keresés | `DocumentServiceTest.java` | +| **04 - Eszközök** | 12 | Függvényhívás és eszköz láncolás | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol stdio transzporttal | `SimpleMcpTest.java` | -## A Tesztek Futtatása +## Tesztek Futtatása -**Futtasd az összes tesztet a gyökérkönyvtárból:** +**Minden teszt futtatása a gyökérből:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Futtass teszteket egy adott modulra:** +**Egy adott modul tesztjeinek futtatása:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Futtass egyedi teszt osztályt:** +**Egyetlen tesztosztály futtatása:** **Bash:** ```bash @@ -91,7 +90,7 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Futtass egy konkrét tesztmetódust:** +**Egy adott tesztmetódus futtatása:** **Bash:** ```bash @@ -100,36 +99,36 @@ mvn test -Dtest=SimpleConversationTest#meg kell tartani a beszélgetés előzmé **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#meg kell őrizni a beszélgetési előzményeket +mvn --% test -Dtest=SimpleConversationTest#meg kell tartani a beszélgetés előzményeit ``` ## Tesztek Futtatása VS Code-ban -Ha Visual Studio Code-ot használsz, a Test Explorer grafikus felületet nyújt a tesztek futtatásához és hibakereséséhez. +Ha Visual Studio Code-ot használsz, a Test Explorer grafikus felületet biztosít a tesztek futtatásához és hibakereséséhez. VS Code Teszt Felfedező -*VS Code Teszt Felfedező, amely mutatja a tesztfát az összes Java tesztosztállyal és egyedi tesztmetódussal* +*VS Code Test Explorer, amely mutatja a tesztfát az összes Java tesztosztállyal és az egyéni tesztmetódusokkal* **Tesztek futtatása VS Code-ban:** -1. Nyisd meg a Test Explorer-t az Activity Bar-ban a lombik ikonra kattintva -2. Bontsd ki a tesztfát, hogy lásd az összes modult és teszt osztályt -3. Kattints a lejátszás gombra bármelyik teszt mellett az egyedüli futtatáshoz -4. Kattints a "Run All Tests"-re az egész tesztcsomag futtatásához -5. Jobb klikk bármely teszten és válaszd a "Debug Test" opciót a breakpointok beállításához és lépésekhez a kódban +1. Nyisd meg a Test Explorert az Activity Bar-ban lévő lombik ikonra kattintva +2. Bontsd ki a tesztfát, hogy lásd az összes modult és tesztosztályt +3. Kattints bármelyik teszthez tartozó lejátszás gombra, hogy azt egyedileg futtasd +4. Kattints a „Run All Tests” gombra az egész tesztcsomag futtatásához +5. Jobb klikk bármely teszt fölött, majd válaszd a „Debug Test” menüpontot a töréspontok beállításához és lépésenkénti futtatáshoz -A Test Explorer zöld pipákat mutat a sikeres teszteknél, illetve részletes hibajelentést, ha egy teszt megbukik. +A Test Explorer zöld pipát mutat a sikeres tesztek mellett és részletes hibajelentést ad, ha egy teszt kudarcot vall. ## Tesztelési Minták -### Minta 1: Parancssablonok Tesztelése +### Minta 1: Prompt Sablonok Tesztelése -A legegyszerűbb minta a parancssablonokat teszteli AI modell hívás nélkül. Ellenőrzöd, hogy a változó helyettesítés helyesen működik-e és a promptok az elvárt formátumban vannak-e. +A legegyszerűbb minta a prompt sablonokat teszteli AI modell hívása nélkül. Ellenőrzöd, hogy a változó helyettesítés helyesen működik-e és a promptok a várt formában készülnek el. -Parancssablon Tesztelés +Prompt Sablon Tesztelése -*Parancssablon tesztelés, amely mutatja a változó helyettesítés folyamatát: sablon helyőrzőkkel → értékekkel kiegészítve → formázott kimenet ellenőrizve* +*Prompt sablon tesztelése változó helyettesítés folyamatával: sablon helyőrzőkkel → értékek alkalmazva → formázott kimenet ellenőrizve* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Ez a teszt a `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` fájlban található. +Ez a minta ellenőrzi a változó helyettesítést és hogy a promptok a várakozásoknak megfelelően formázottak — nem szükséges API kulcs vagy modell hívás. -**Futtasd:** +### Minta 2: Nyelvi Modellek "Mock"-olása -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#tesztPromptSablonFormázás -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#tesztPromptSablonFormázás -``` - -### Minta 2: Nyelvi Modellek Mockolása - -Beszélgetési logika tesztelésekor használd a Mockito-t hogy hamis modelleket hozz létre, amelyek előre meghatározott válaszokat adnak. Ez gyorsabbá, ingyenessé és determinisztikussá teszi a teszteket. +Beszélgetési logika teszteléskor használj Mockito-t hamis modellek létrehozására, amelyek előre meghatározott válaszokat adnak. Ezáltal a tesztek gyorsak, ingyenesek és determinisztikusak lesznek. -Mock és Valós API Összehasonlítás +Mock és Valódi API Összehasonlítás -*Összehasonlítás, hogy miért előnyösek a mock-ok a teszteléshez: gyorsak, ingyenesek, determinisztikusak, nincs szükség API kulcsokra* +*Összehasonlítás, ami megmutatja, miért előnyösebb a mock az API teszteléshez: gyors, ingyenes, determinisztikus és nem igényel API kulcsokat* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 felhasználói + 3 MI üzenet + assertThat(history).hasSize(6); // 3 felhasználói + 3 mesterséges intelligencia üzenet } } ``` -Ez a minta megtalálható a `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` fájlban. A mock biztosítja az állandó viselkedést, hogy az emlékezetkezelés helyes működését ellenőrizhesd. +Ez a minta megtalálható az `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` fájlban. A mock egységes viselkedést biztosít, így ellenőrizheted, hogy a memória kezelése helyes. -### Minta 3: Beszélgetés Elszigeteltségének Tesztelése +### Minta 3: Beszélgetés Izoláció Tesztelése -A beszélgetés memóriának külön kell választania a több felhasználót. Ez a teszt ellenőrzi, hogy a beszélgetések nem keverik össze a kontextusokat. +A beszélgetés memóriának meg kell tartania az egyes felhasználók szétválasztását. Ez a teszt igazolja, hogy a beszélgetések nem keverik a kontextusokat. -Beszélgetés Elszigetelés +Beszélgetés Izoláció -*Beszélgetés elszigetelés tesztelése, amely bemutatja, hogy eltérő felhasználók számára külön memóriatárolók vannak, hogy megelőzze a kontextus összekeveredését* +*Beszélgetés izolációjának tesztelése, amely különálló memória tárolókat mutat eltérő felhasználók számára a kontextus keveredés elkerüléséhez* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Minden beszélgetés saját, független előzményeket tart fenn. Éles rendszerekben ez az elszigetelés kritikus a többfelhasználós alkalmazások esetében. +Minden beszélgetés saját, független előzményt tart fenn. Termelési rendszerekben ez az izoláció elengedhetetlen a többfelhasználós alkalmazásokhoz. ### Minta 4: Eszközök Független Tesztelése -Az eszközök olyan funkciók, amelyeket az AI hívhat meg. Teszteld őket közvetlenül, hogy biztos legyél benne, hogy jól működnek AI döntések nélkül is. +Az eszközök olyan függvények, amelyeket az AI hívhat meg. Teszteld őket közvetlenül, hogy biztosan helyesen működnek az AI döntéseitől függetlenül. Eszközök Tesztelése -*Eszközök független tesztelése, amely mutatja a mock eszközök futtatását AI hívások nélkül, hogy ellenőrizze az üzleti logikát* +*Eszközök független tesztelése mock eszköz futtatással AI hívások nélkül az üzleti logika ellenőrzéséhez* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Ezek a tesztek a `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` fájlból valók, amelyek validálják az eszközlogikát AI részvétel nélkül. A láncolási példa azt mutatja, hogyan táplálja egy eszköz kimenete a másik bemenetét. +Ezek a tesztek az `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` fájlból származnak és az eszközök logikáját validálják AI részvétel nélkül. A láncolás példa mutatja, hogyan táplálja egy eszköz kimenete a másikat bemenetként. -### Minta 5: Memóriában Futó RAG Tesztelés +### Minta 5: Memóriában Futtatott RAG Tesztelés -A RAG rendszerek hagyományosan vektorigényes adatbázisokat és beágyazási szolgáltatásokat használnak. A memóriában futó minta lehetővé teszi az egész folyamat tesztelését külső függőségek nélkül. +A RAG rendszerek hagyományosan vektoralapú adatbázisokat és embedding szolgáltatásokat igényelnek. A memóriában futtatott minta lehetővé teszi, hogy az egész folyamatot külső függőségek nélkül teszteld. -Memóriában Futó RAG Tesztelés +Memóriában Futtatott RAG Tesztelés -*Memóriában futó RAG tesztelési munkafolyamat, amely bemutatja a dokumentum feldolgozását, beágyazás tárolást és hasonlóság keresést adatbázis nélkül* +*Memóriában futtatott RAG tesztelési folyamat, amely dokumentum feldolgozást, beágyazott tárolást és hasonlóság keresést mutat be adatbázis nélkül* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Ez a teszt a `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` fájlból kreál a memóriában dokumentumot és ellenőrzi a darabolást és metaadat kezelését. +Ez a teszt az `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` fájlból létrehoz egy dokumentumot memóriában, és ellenőrzi a szeletelést és metaadat kezelést. ### Minta 6: MCP Integrációs Tesztelés -Az MCP modul a Model Context Protocol integrációját teszteli stdio átvitel használatával. Ezek a tesztek igazolják, hogy az alkalmazás képes MCP szervereket folyamatként indítani és velük kommunikálni. +Az MCP modul a Model Context Protocol integrációját teszteli stdio transzport használatával. Ezek a tesztek igazolják, hogy az alkalmazás képes MCP szervereket alfolyamatként indítani és kommunikálni velük. -Az `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` fájlban lévő tesztek validálják az MCP kliens viselkedését. +Az `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` tesztek validálják az MCP kliens viselkedését. **Futtasd őket:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Tesztelési Filozófia -A kódodat teszteld, ne az AI-t. A tesztjeidnek azt kell ellenőrizniük, hogy a te általad írt kód hogyan működik, például hogy a promptok hogyan épülnek fel, hogyan kezelődik a memória és hogyan működnek az eszközök. Az AI válaszai változóak lehetnek, és nem szabad, hogy a tesztelés tárgyát képezzék. Kérdezd meg inkább, hogy a prompt sablon helyesen helyettesíti-e a változókat, nem pedig azt, hogy az AI jól válaszol-e. +A kódodat teszteld, ne az AI-t. A tesztjeidnek azt kell ellenőrizniük, hogy a kód, amit írsz, helyesen építi fel a promptokat, kezeli a memóriát és futtatja az eszközöket. Az AI válaszai változékonyak, és nem részei a teszt elvárásoknak. Inkább azt kérdezd meg magadtól, hogy a prompt sablonod helyesen helyettesíti-e a változókat, nem azt, hogy az AI ad-e helyes választ. -Használj mock-okat a nyelvi modellekhez. Ezek külső függőségek, amelyek lassúak, drágák és nem determinisztikusak. A mockolás gyors, milliszekundumos, ingyenes és mindig azonos eredményt ad. +Használj mockokat a nyelvi modellekhez. Ezek külső függőségek, lassúak, drágák és nem determinisztikusak. A mockolás gyorsítja a teszteket (milliszekundumok), ingyenessé teszi őket (nincs API költség) és determinisztikussá (ugyanaz az eredmény mindig). -Tartsd a teszteket függetlennek. Minden teszt állítsa be a saját adatait, ne támaszkodjon más tesztekre, és takarítson maga után. A teszteknek bármilyen futási sorrendben át kell menniük. +Tartsd függetlennek a teszteket. Minden teszt állítsa be saját adatait, ne függjön más tesztektől, és takarítsa el maga után. A teszteknek akkor is sikeresnek kell lenniük, ha a futtatási sorrendet megváltoztatod. -Tesztelj szélsőséges eseteket a megszokott útvonalakon túl. Próbálj ki üres bemeneteket, nagyon nagy adatokat, speciális karaktereket, érvénytelen paramétereket és határfeltételeket. Ezek gyakran fednek fel olyan hibákat, amiket a normál használat nem. +Tesztelj szélsőséges eseteket is a szokásos eseteken túl. Próbálj ki üres bemeneteket, nagyon nagyméretű bemeneteket, speciális karaktereket, érvénytelen paramétereket és határértékeket. Ezek gyakran fednek fel hibákat, amelyeket normál használat nem mutat ki. -Használj leíró neveket. Összehasonlítva a `shouldMaintainConversationHistoryAcrossMultipleMessages()` és a `test1()` neveket: az első pontosan elmondja, hogy mit tesztel, könnyebbé téve a hibák keresését. +Használj leíró neveket. Hasonlítsd össze a `shouldMaintainConversationHistoryAcrossMultipleMessages()` és a `test1()` nevű metódusokat. Az első pontosan elmondja, mit tesztel a kód, így a hibakeresés jóval egyszerűbb. ## Következő Lépések -Most, hogy megérted a tesztelési mintákat, mélyedj el az egyes modulokban: +Most, hogy érted a tesztelési mintákat, mélyedj el minden modulban: -- **[00 - Gyors Kezdet](../00-quick-start/README.md)** - Kezdd a parancssablon alapokkal -- **[01 - Bevezetés](../01-introduction/README.md)** - Tanuld meg a beszélgetés memória kezelését -- **[02 - Prompt Mérnökség](../02/prompt-engineering/README.md)** - Sajátítsd el a GPT-5.2 promptolási mintákat -- **[03 - RAG](../03-rag/README.md)** - Építs lekérdezés-kiterjesztett generálási rendszereket -- **[04 - Eszközök](../04-tools/README.md)** - Valósítsd meg a függvényhívást és eszközláncokat -- **[05 - MCP](../05-mcp/README.md)** - Integráld a Model Context Protocol-t +- **[01 - Bevezetés](../01-introduction/README.md)** - Ismerd meg a beszélgetés memóriakezelését +- **[02 - Prompt Tervezés](../02-prompt-engineering/README.md)** - Sajátítsd el a GPT-5.2 prompt mintákat +- **[03 - RAG](../03-rag/README.md)** - Építs lekérdezés-alapú generáló rendszereket +- **[04 - Eszközök](../04-tools/README.md)** - Valósíts meg függvényhívásokat és eszköz láncokat +- **[05 - MCP](../05-mcp/README.md)** - Integráld a Model Context Protocolt -Minden modul README-je részletes magyarázatokat ad a itt tesztelt koncepciókról. +Minden modul README fájl részletesen magyarázza a itt tesztelt koncepciókat. --- -**Navigáció:** [← Vissza a Főoldalra](../README.md) +**Navigáció:** [← Vissza a főoldalra](../README.md) --- -**Nyilatkozat**: -Ezt a dokumentumot az AI fordító szolgáltatás [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével fordítottuk le. Bár igyekszünk a pontosságra, kérjük, vegye figyelembe, hogy az automatikus fordítások tartalmazhatnak hibákat vagy pontatlanságokat. Az eredeti dokumentum a saját nyelvén tekintendő hiteles forrásnak. Kritikus információk esetén professzionális, emberi fordítást javaslunk. Nem vállalunk felelősséget az ebből eredő félreértésekért vagy helytelen értelmezésekért. +**Jogi nyilatkozat**: +Ez a dokumentum az AI fordítási szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár az pontosságra törekszünk, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Fontos információk esetén professzionális emberi fordítást javasolunk. Nem vállalunk felelősséget semmilyen félreértésért vagy téves értelmezésért, amely ebből a fordításból ered. \ No newline at end of file diff --git a/translations/id/.co-op-translator.json b/translations/id/.co-op-translator.json index 973981455..3ce948560 100644 --- a/translations/id/.co-op-translator.json +++ b/translations/id/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "id" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T20:24:39+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T10:10:12+00:00", "source_file": "01-introduction/README.md", "language_code": "id" }, @@ -18,20 +18,20 @@ "language_code": "id" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T20:27:13+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T10:05:28+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "id" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T20:28:48+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T10:09:24+00:00", "source_file": "03-rag/README.md", "language_code": "id" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T12:33:48+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T10:08:01+00:00", "source_file": "04-tools/README.md", "language_code": "id" }, @@ -54,8 +54,8 @@ "language_code": "id" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:11:34+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T10:03:59+00:00", "source_file": "README.md", "language_code": "id" }, @@ -72,14 +72,14 @@ "language_code": "id" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T20:32:06+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T10:06:01+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "id" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T20:32:50+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T10:06:40+00:00", "source_file": "docs/TESTING.md", "language_code": "id" } diff --git a/translations/id/00-quick-start/README.md b/translations/id/00-quick-start/README.md deleted file mode 100644 index b059b8662..000000000 --- a/translations/id/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Mulai Cepat - -## Daftar Isi - -- [Pendahuluan](../../../00-quick-start) -- [Apa itu LangChain4j?](../../../00-quick-start) -- [Dependensi LangChain4j](../../../00-quick-start) -- [Prasyarat](../../../00-quick-start) -- [Pengaturan](../../../00-quick-start) - - [1. Dapatkan Token GitHub Anda](../../../00-quick-start) - - [2. Atur Token Anda](../../../00-quick-start) -- [Jalankan Contoh](../../../00-quick-start) - - [1. Chat Dasar](../../../00-quick-start) - - [2. Pola Prompt](../../../00-quick-start) - - [3. Panggilan Fungsi](../../../00-quick-start) - - [4. Tanya Jawab Dokumen (Easy RAG)](../../../00-quick-start) - - [5. AI Bertanggung Jawab](../../../00-quick-start) -- [Apa yang Ditunjukkan Setiap Contoh](../../../00-quick-start) -- [Langkah Selanjutnya](../../../00-quick-start) -- [Pemecahan Masalah](../../../00-quick-start) - -## Pendahuluan - -Mulai cepat ini dimaksudkan agar Anda bisa langsung menggunakan LangChain4j secepat mungkin. Ini mencakup dasar-dasar membangun aplikasi AI dengan LangChain4j dan Model GitHub. Pada modul-modul berikutnya Anda akan beralih ke Azure OpenAI dan GPT-5.2 dan menggali lebih dalam setiap konsep. - -## Apa itu LangChain4j? - -LangChain4j adalah perpustakaan Java yang mempermudah pembangunan aplikasi bertenaga AI. Alih-alih berurusan dengan klien HTTP dan parsing JSON, Anda bekerja dengan API Java yang bersih. - -"Chain" dalam LangChain mengacu pada menghubungkan beberapa komponen bersama-sama - Anda mungkin menghubungkan prompt ke model ke parser, atau menghubungkan beberapa panggilan AI di mana satu output menjadi input berikutnya. Mulai cepat ini fokus pada dasar-dasar sebelum mengeksplorasi rantai yang lebih kompleks. - -Konsep Penggabungan LangChain4j - -*Menggabungkan komponen dalam LangChain4j - blok bangunan menghubungkan untuk membuat alur kerja AI yang kuat* - -Kita akan menggunakan tiga komponen inti: - -**ChatModel** - Antarmuka untuk interaksi model AI. Panggil `model.chat("prompt")` dan dapatkan string respon. Kami menggunakan `OpenAiOfficialChatModel` yang bekerja dengan endpoint yang kompatibel dengan OpenAI seperti Model GitHub. - -**AiServices** - Membuat antarmuka layanan AI yang tipe-aman. Definisikan metode, anotasi dengan `@Tool`, dan LangChain4j menangani orkestrasi. AI secara otomatis memanggil metode Java Anda saat dibutuhkan. - -**MessageWindowChatMemory** - Mempertahankan riwayat percakapan. Tanpa ini, setiap permintaan bersifat independen. Dengan ini, AI ingat pesan sebelumnya dan mempertahankan konteks di beberapa gilirannya. - -Arsitektur LangChain4j - -*Arsitektur LangChain4j - komponen inti bekerja bersama untuk memberi tenaga pada aplikasi AI Anda* - -## Dependensi LangChain4j - -Mulai cepat ini menggunakan tiga dependensi Maven dalam [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modul `langchain4j-open-ai-official` menyediakan kelas `OpenAiOfficialChatModel` yang terhubung ke API yang kompatibel dengan OpenAI. Model GitHub menggunakan format API yang sama, jadi tidak diperlukan adaptor khusus — cukup arahkan URL dasar ke `https://models.github.ai/inference`. - -Modul `langchain4j-easy-rag` menyediakan pemisahan dokumen otomatis, embedding, dan pengambilan sehingga Anda dapat membangun aplikasi RAG tanpa mengkonfigurasi setiap langkah secara manual. - -## Prasyarat - -**Menggunakan Dev Container?** Java dan Maven sudah terpasang. Anda hanya memerlukan Token Akses Pribadi GitHub. - -**Pengembangan Lokal:** -- Java 21+, Maven 3.9+ -- Token Akses Pribadi GitHub (instruksi di bawah) - -> **Catatan:** Modul ini menggunakan `gpt-4.1-nano` dari Model GitHub. Jangan ubah nama model dalam kode — ini dikonfigurasi untuk bekerja dengan model yang tersedia di GitHub. - -## Pengaturan - -### 1. Dapatkan Token GitHub Anda - -1. Pergi ke [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Klik "Generate new token" -3. Beri nama yang deskriptif (misal, "LangChain4j Demo") -4. Tentukan masa berlaku (7 hari direkomendasikan) -5. Di bawah "Account permissions", cari "Models" dan atur ke "Read-only" -6. Klik "Generate token" -7. Salin dan simpan token Anda — Anda tidak akan melihatnya lagi - -### 2. Atur Token Anda - -**Pilihan 1: Menggunakan VS Code (Direkomendasikan)** - -Jika Anda menggunakan VS Code, tambahkan token Anda ke file `.env` di root proyek: - -Jika file `.env` tidak ada, salin `.env.example` ke `.env` atau buat file `.env` baru di root proyek. - -**Contoh file `.env`:** -```bash -# Di /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Lalu Anda cukup klik kanan pada file demo apa saja (misal `BasicChatDemo.java`) di Explorer dan pilih **"Run Java"** atau gunakan konfigurasi peluncuran dari panel Run and Debug. - -**Pilihan 2: Menggunakan Terminal** - -Atur token sebagai variabel lingkungan: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Jalankan Contoh - -**Menggunakan VS Code:** Cukup klik kanan pada file demo apa saja di Explorer dan pilih **"Run Java"**, atau gunakan konfigurasi peluncuran dari panel Run and Debug (pastikan token sudah ditambahkan ke file `.env` dulu). - -**Menggunakan Maven:** Alternatifnya, Anda dapat menjalankan dari baris perintah: - -### 1. Chat Dasar - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Pola Prompt - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Menampilkan zero-shot, few-shot, chain-of-thought, dan prompt berbasis peran. - -### 3. Panggilan Fungsi - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI secara otomatis memanggil metode Java Anda saat dibutuhkan. - -### 4. Tanya Jawab Dokumen (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Tanyakan pertanyaan tentang dokumen Anda menggunakan Easy RAG dengan embedding dan pengambilan otomatis. - -### 5. AI Bertanggung Jawab - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Lihat bagaimana filter keamanan AI memblokir konten berbahaya. - -## Apa yang Ditunjukkan Setiap Contoh - -**Chat Dasar** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Mulai di sini untuk melihat LangChain4j dalam bentuk paling sederhana. Anda akan membuat `OpenAiOfficialChatModel`, mengirim prompt dengan `.chat()`, dan mendapatkan respons kembali. Ini menunjukkan fondasi: bagaimana menginisialisasi model dengan endpoint dan kunci API khusus. Setelah memahami pola ini, semuanya dibangun di atasnya. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) dan tanyakan: -> - "Bagaimana saya beralih dari Model GitHub ke Azure OpenAI dalam kode ini?" -> - "Parameter lain apa yang bisa saya konfigurasi di OpenAiOfficialChatModel.builder()?" -> - "Bagaimana cara menambahkan streaming respons alih-alih menunggu respons lengkap?" - -**Rekayasa Prompt** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Sekarang Anda tahu cara berkomunikasi dengan model, mari jelajahi apa yang Anda katakan padanya. Demo ini menggunakan setup model yang sama tapi menunjukkan lima pola prompting berbeda. Coba zero-shot untuk instruksi langsung, few-shot yang belajar dari contoh, chain-of-thought yang mengungkap langkah penalaran, dan prompt berbasis peran yang menetapkan konteks. Anda akan melihat bagaimana model yang sama memberikan hasil sangat berbeda tergantung cara Anda mengatur permintaan. - -Demo juga memperlihatkan template prompt, yang merupakan cara kuat untuk membuat prompt yang dapat digunakan ulang dengan variabel. -Contoh berikut menunjukkan prompt menggunakan LangChain4j `PromptTemplate` untuk mengisi variabel. AI akan menjawab berdasarkan tujuan dan aktivitas yang diberikan. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) dan tanyakan: -> - "Apa perbedaan antara zero-shot dan few-shot prompting, dan kapan harus menggunakan masing-masing?" -> - "Bagaimana parameter temperature memengaruhi respons model?" -> - "Apa saja teknik untuk mencegah serangan injeksi prompt di produksi?" -> - "Bagaimana cara membuat objek PromptTemplate yang dapat digunakan ulang untuk pola umum?" - -**Integrasi Alat** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Di sinilah LangChain4j menjadi kuat. Anda akan menggunakan `AiServices` untuk membuat asisten AI yang dapat memanggil metode Java Anda. Cukup anotasi metode dengan `@Tool("deskripsi")` dan LangChain4j mengurus sisanya — AI secara otomatis memutuskan kapan menggunakan setiap alat berdasarkan permintaan pengguna. Ini menunjukkan panggilan fungsi, teknik utama untuk membangun AI yang bisa mengambil tindakan, bukan hanya menjawab pertanyaan. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) dan tanyakan: -> - "Bagaimana anotasi @Tool bekerja dan apa yang LangChain4j lakukan di balik layar?" -> - "Apakah AI bisa memanggil beberapa alat secara berurutan untuk memecahkan masalah kompleks?" -> - "Apa yang terjadi jika sebuah alat melemparkan pengecualian — bagaimana saya menangani kesalahan?" -> - "Bagaimana cara mengintegrasikan API nyata bukan contoh kalkulator ini?" - -**Tanya Jawab Dokumen (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Di sini Anda akan melihat RAG (retrieval-augmented generation) menggunakan pendekatan "Easy RAG" LangChain4j. Dokumen dimuat, secara otomatis dipisah dan diembed ke dalam penyimpanan memori, kemudian pengambil konten memberikan potongan relevan ke AI saat waktu kueri. AI menjawab berdasarkan dokumen Anda, bukan pengetahuan umum model. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) dan tanyakan: -> - "Bagaimana RAG mencegah halusinasi AI dibandingkan menggunakan data pelatihan model?" -> - "Apa perbedaan pendekatan mudah ini dengan pipeline RAG kustom?" -> - "Bagaimana saya mengskalakan ini untuk menangani banyak dokumen atau basis pengetahuan yang lebih besar?" - -**AI Bertanggung Jawab** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Bangun keamanan AI dengan pertahanan berlapis. Demo ini menunjukkan dua lapis perlindungan bekerja bersama: - -**Bagian 1: LangChain4j Input Guardrails** - Memblokir prompt berbahaya sebelum mencapai LLM. Buat guardrail kustom yang memeriksa kata kunci atau pola terlarang. Ini dijalankan di kode Anda, jadi cepat dan gratis. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Bagian 2: Filter Keamanan Penyedia** - Model GitHub memiliki filter bawaan yang menangkap apa yang mungkin terlewat guardrails Anda. Anda akan melihat blok keras (error HTTP 400) untuk pelanggaran berat dan penolakan lunak di mana AI menolak dengan sopan. - -> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) dan tanyakan: -> - "Apa itu InputGuardrail dan bagaimana cara membuatnya?" -> - "Apa perbedaan antara blok keras dan penolakan lunak?" -> - "Mengapa menggunakan keduanya, guardrails dan filter penyedia?" - -## Langkah Selanjutnya - -**Modul Berikutnya:** [01-introduction - Memulai dengan LangChain4j](../01-introduction/README.md) - ---- - -**Navigasi:** [← Kembali ke Utama](../README.md) | [Berikutnya: Module 01 - Pendahuluan →](../01-introduction/README.md) - ---- - -## Pemecahan Masalah - -### Build Maven Pertama Kali - -**Masalah**: `mvn clean compile` atau `mvn package` awal memakan waktu lama (10-15 menit) - -**Penyebab**: Maven perlu mengunduh semua dependensi proyek (Spring Boot, perpustakaan LangChain4j, SDK Azure, dll.) saat build pertama kali. - -**Solusi**: Ini perilaku normal. Build berikutnya akan jauh lebih cepat karena dependensi sudah disimpan lokal. Waktu unduh tergantung kecepatan jaringan Anda. - -### Sintaks Perintah Maven di PowerShell - -**Masalah**: Perintah Maven gagal dengan error `Unknown lifecycle phase ".mainClass=..."` -**Penyebab**: PowerShell mengartikan `=` sebagai operator penugasan variabel, yang merusak sintaks properti Maven - -**Solusi**: Gunakan operator stop-parsing `--%` sebelum perintah Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operator `--%` memberi tahu PowerShell untuk meneruskan semua argumen yang tersisa secara literal ke Maven tanpa interpretasi. - -### Tampilkan Emoji di Windows PowerShell - -**Masalah**: Respon AI menampilkan karakter sampah (misalnya, `????` atau `â??`) alih-alih emoji di PowerShell - -**Penyebab**: Encoding default PowerShell tidak mendukung emoji UTF-8 - -**Solusi**: Jalankan perintah ini sebelum mengeksekusi aplikasi Java: -```cmd -chcp 65001 -``` - -Ini memaksa encoding UTF-8 di terminal. Alternatifnya, gunakan Windows Terminal yang memiliki dukungan Unicode lebih baik. - -### Debugging Panggilan API - -**Masalah**: Kesalahan autentikasi, batasan rate, atau respon tak terduga dari model AI - -**Solusi**: Contoh termasuk `.logRequests(true)` dan `.logResponses(true)` untuk menampilkan panggilan API di konsol. Ini membantu memecahkan masalah kesalahan autentikasi, batasan rate, atau respon tak terduga. Hapus flag ini di produksi untuk mengurangi kebisingan log. - ---- - - -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk akurat, harap diingat bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi yang kritis, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau salah tafsir yang timbul dari penggunaan terjemahan ini. - \ No newline at end of file diff --git a/translations/id/01-introduction/README.md b/translations/id/01-introduction/README.md index a3d96bb00..dbe6a7e33 100644 --- a/translations/id/01-introduction/README.md +++ b/translations/id/01-introduction/README.md @@ -2,37 +2,37 @@ ## Daftar Isi -- [Video Walkthrough](../../../01-introduction) -- [Apa yang Akan Anda Pelajari](../../../01-introduction) -- [Prasyarat](../../../01-introduction) -- [Memahami Masalah Inti](../../../01-introduction) -- [Memahami Token](../../../01-introduction) -- [Cara Kerja Memori](../../../01-introduction) -- [Cara Ini Menggunakan LangChain4j](../../../01-introduction) -- [Menerapkan Infrastruktur Azure OpenAI](../../../01-introduction) -- [Menjalankan Aplikasi Secara Lokal](../../../01-introduction) -- [Menggunakan Aplikasi](../../../01-introduction) - - [Obrolan Stateless (Panel Kiri)](../../../01-introduction) - - [Obrolan Stateful (Panel Kanan)](../../../01-introduction) -- [Langkah Selanjutnya](../../../01-introduction) +- [Video Walkthrough](#video-walkthrough) +- [Apa yang Akan Anda Pelajari](#apa-yang-akan-anda-pelajari) +- [Prasyarat](#prasyarat) +- [Memahami Masalah Inti](#memahami-masalah-inti) +- [Memahami Token](#memahami-token) +- [Cara Kerja Memori](#cara-kerja-memori) +- [Bagaimana Ini Menggunakan LangChain4j](#bagaimana-ini-menggunakan-langchain4j) +- [Menerapkan Infrastruktur Azure OpenAI](#menerapkan-infrastruktur-azure-openai) +- [Menjalankan Aplikasi Secara Lokal](#menjalankan-aplikasi-secara-lokal) +- [Menggunakan Aplikasi](#menggunakan-aplikasi) + - [Chat Tanpa Status (Panel Kiri)](#chat-tanpa-status-panel-kiri) + - [Chat Dengan Status (Panel Kanan)](#chat-dengan-status-panel-kanan) +- [Langkah Selanjutnya](#langkah-selanjutnya) ## Video Walkthrough Tonton sesi langsung ini yang menjelaskan cara memulai dengan modul ini: -Getting Started with LangChain4j - Live Session +Memulai dengan LangChain4j - Sesi Langsung ## Apa yang Akan Anda Pelajari -Dalam quick start, Anda menggunakan Model GitHub untuk mengirim prompt, memanggil alat, membangun pipeline RAG, dan menguji guardrails. Demo tersebut menunjukkan apa yang mungkin — sekarang kita beralih ke Azure OpenAI dan GPT-5.2 dan mulai membangun aplikasi bergaya produksi. Modul ini fokus pada AI percakapan yang mengingat konteks dan menjaga status — konsep yang digunakan oleh demo quick start di balik layar tapi tidak dijelaskan. +Ini adalah titik awal Anda dengan LangChain4j dan Azure OpenAI. Kami mulai dengan dasar-dasar dan mulai membangun aplikasi gaya produksi. Modul ini berfokus pada AI percakapan yang mengingat konteks dan mempertahankan status — konsep dasar yang dibangun oleh setiap modul berikutnya. -Kita akan menggunakan GPT-5.2 dari Azure OpenAI sepanjang panduan ini karena kemampuan penalarannya yang maju membuat perilaku pola yang berbeda lebih jelas. Saat Anda menambahkan memori, Anda akan melihat perbedaannya dengan jelas. Ini memudahkan Anda memahami apa yang dibawa setiap komponen ke aplikasi Anda. +Kami akan menggunakan GPT-5.2 Azure OpenAI sepanjang panduan ini karena kemampuan penalarannya yang maju membuat perilaku pola yang berbeda lebih jelas. Ketika Anda menambahkan memori, Anda akan melihat perbedaannya dengan jelas. Ini membuat lebih mudah untuk memahami apa yang dibawa setiap komponen ke aplikasi Anda. -Anda akan membangun satu aplikasi yang menunjukkan kedua pola: +Anda akan membangun satu aplikasi yang menunjukkan kedua pola tersebut: -**Obrolan Stateless** - Setiap permintaan bersifat independen. Model tidak mengingat pesan sebelumnya. Ini adalah pola yang Anda gunakan dalam quick start. +**Chat Tanpa Status** - Setiap permintaan bersifat independen. Model tidak mengingat pesan sebelumnya. Ini adalah titik awal yang paling sederhana. -**Percakapan Stateful** - Setiap permintaan menyertakan riwayat percakapan. Model menjaga konteks di beberapa giliran. Ini yang dibutuhkan oleh aplikasi produksi. +**Percakapan Dengan Status** - Setiap permintaan mencakup riwayat percakapan. Model mempertahankan konteks di beberapa giliran. Ini yang dibutuhkan aplikasi produksi. ## Prasyarat @@ -41,47 +41,47 @@ Anda akan membangun satu aplikasi yang menunjukkan kedua pola: - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Catatan:** Java, Maven, Azure CLI dan Azure Developer CLI (azd) sudah terpasang dalam devcontainer yang disediakan. +> **Catatan:** Java, Maven, Azure CLI, dan Azure Developer CLI (azd) telah diinstal sebelumnya di devcontainer yang disediakan. -> **Catatan:** Modul ini menggunakan GPT-5.2 di Azure OpenAI. Deployment dikonfigurasi otomatis melalui `azd up` - jangan ubah nama model di kode. +> **Catatan:** Modul ini menggunakan GPT-5.2 di Azure OpenAI. Penyebaran dikonfigurasi secara otomatis melalui `azd up` - jangan ubah nama model di kode. ## Memahami Masalah Inti -Model bahasa bersifat stateless. Setiap panggilan API independen. Jika Anda mengirim "Nama saya John" lalu tanya "Siapa nama saya?", model tidak tahu bahwa Anda baru saja memperkenalkan diri. Model memperlakukan setiap permintaan seolah-olah itu adalah percakapan pertama Anda. +Model bahasa tidak memiliki status. Setiap panggilan API bersifat independen. Jika Anda mengirim "Nama saya John" dan kemudian bertanya "Siapa nama saya?", model tidak tahu Anda baru saja memperkenalkan diri. Model memperlakukan setiap permintaan seolah itu adalah percakapan pertama Anda. -Ini cukup untuk Q&A sederhana tapi tidak berguna untuk aplikasi nyata. Bot layanan pelanggan perlu mengingat apa yang Anda katakan. Asisten pribadi perlu konteks. Setiap percakapan multi-giliran membutuhkan memori. +Ini baik untuk tanya jawab sederhana tapi tidak berguna untuk aplikasi nyata. Bot layanan pelanggan perlu mengingat apa yang Anda bilang. Asisten pribadi perlu konteks. Percakapan multi-giliran memerlukan memori. -Diagram berikut membandingkan dua pendekatan — di kiri, panggilan stateless yang lupa nama Anda; di kanan, panggilan stateful dengan ChatMemory yang mengingatnya. +Diagram berikut membandingkan kedua pendekatan — di kiri, panggilan tanpa status yang melupakan nama Anda; di kanan, panggilan dengan status yang didukung oleh ChatMemory yang mengingatnya. -Stateless vs Stateful Conversations +Percakapan Tanpa Status vs Dengan Status -*Perbedaan antara percakapan stateless (panggilan independen) dan stateful (memahami konteks)* +*Perbedaan antara percakapan tanpa status (panggilan independen) dan dengan status (sadar konteks)* ## Memahami Token -Sebelum masuk ke percakapan, penting untuk memahami token - unit teks dasar yang diproses model bahasa: +Sebelum masuk ke percakapan, penting untuk memahami token - unit dasar teks yang diproses model bahasa: -Token Explanation +Penjelasan Token -*Contoh bagaimana teks dipecah menjadi token - "I love AI!" menjadi 4 unit pemrosesan terpisah* +*Contoh bagaimana teks dipecah menjadi token - "I love AI!" menjadi 4 unit proses terpisah* -Token adalah cara model AI mengukur dan memproses teks. Kata, tanda baca, bahkan spasi bisa menjadi token. Model Anda memiliki batas berapa banyak token yang bisa diproses sekaligus (400.000 untuk GPT-5.2, dengan hingga 272.000 token input dan 128.000 token output). Memahami token membantu Anda mengatur panjang percakapan dan biaya. +Token adalah cara model AI mengukur dan memproses teks. Kata, tanda baca, dan bahkan spasi bisa menjadi token. Model Anda memiliki batas berapa banyak token yang bisa diproses sekaligus (400.000 untuk GPT-5.2, dengan hingga 272.000 token input dan 128.000 token output). Memahami token membantu Anda mengelola panjang percakapan dan biaya. ## Cara Kerja Memori -Chat memory menyelesaikan masalah stateless dengan menjaga riwayat percakapan. Sebelum mengirim permintaan ke model, framework menambahkan pesan sebelumnya yang relevan. Ketika Anda tanya "Siapa nama saya?", sistem sebenarnya mengirim seluruh riwayat percakapan, memungkinkan model melihat Anda sebelumnya berkata "Nama saya John." +Memori chat memecahkan masalah tanpa status dengan mempertahankan riwayat percakapan. Sebelum mengirim permintaan ke model, kerangka kerja menyisipkan pesan relevan sebelumnya. Ketika Anda bertanya "Siapa nama saya?", sistem sebenarnya mengirim seluruh riwayat percakapan, memungkinkan model melihat bahwa Anda sebelumnya berkata "Nama saya John." -LangChain4j menyediakan implementasi memori yang menangani ini secara otomatis. Anda memilih berapa banyak pesan yang disimpan dan framework mengelola jendela konteks. Diagram di bawah menunjukkan bagaimana MessageWindowChatMemory menjaga jendela geser pesan terbaru. +LangChain4j menyediakan implementasi memori yang mengelola ini secara otomatis. Anda memilih berapa banyak pesan yang disimpan dan kerangka kerja mengatur jendela konteks. Diagram di bawah menunjukkan bagaimana MessageWindowChatMemory mempertahankan jendela geser dari pesan-pesan terbaru. -Memory Window Concept +Konsep Jendela Memori -*MessageWindowChatMemory menjaga jendela geser pesan terbaru, otomatis menghapus pesan lama* +*MessageWindowChatMemory mempertahankan jendela geser dari pesan terbaru, secara otomatis menghapus pesan lama* -## Cara Ini Menggunakan LangChain4j +## Bagaimana Ini Menggunakan LangChain4j -Modul ini memperluas quick start dengan mengintegrasikan Spring Boot dan menambahkan memori percakapan. Berikut cara komponennya bekerja sama: +Modul ini mengintegrasikan Spring Boot dan menambahkan memori percakapan. Ini bagaimana komponennya saling melengkapi: -**Dependencies** - Tambahkan dua pustaka LangChain4j: +**Dependensi** - Tambahkan dua pustaka LangChain4j: ```xml @@ -94,7 +94,7 @@ Modul ini memperluas quick start dengan mengintegrasikan Spring Boot dan menamba ``` -**Chat Model** - Konfigurasikan Azure OpenAI sebagai bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Model Chat** - Konfigurasikan Azure OpenAI sebagai bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder membaca kredensial dari variabel lingkungan yang diatur oleh `azd up`. Menetapkan `baseUrl` ke endpoint Azure Anda membuat klien OpenAI bekerja dengan Azure OpenAI. +Builder membaca kredensial dari variabel lingkungan yang diatur oleh `azd up`. Mengatur `baseUrl` ke endpoint Azure Anda membuat klien OpenAI berfungsi dengan Azure OpenAI. -**Memori Percakapan** - Melacak riwayat obrolan dengan MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Memori Percakapan** - Melacak riwayat chat dengan MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Buat memori dengan `withMaxMessages(10)` untuk menyimpan 10 pesan terakhir. Tambahkan pesan pengguna dan AI dengan pembungkus tipe: `UserMessage.from(text)` dan `AiMessage.from(text)`. Ambil riwayat dengan `memory.messages()` dan kirimkan ke model. Service menyimpan instance memori terpisah per ID percakapan, memungkinkan banyak pengguna mengobrol secara bersamaan. +Buat memori dengan `withMaxMessages(10)` untuk menyimpan 10 pesan terakhir. Tambahkan pesan pengguna dan AI dengan pembungkus bertipe: `UserMessage.from(text)` dan `AiMessage.from(text)`. Ambil riwayat dengan `memory.messages()` dan kirim ke model. Layanan menyimpan instansi memori terpisah per ID percakapan, memungkinkan banyak pengguna chat secara bersamaan. -> **🤖 Coba dengan Chat [GitHub Copilot](https://github.com/features/copilot):** Buka [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) dan tanyakan: -> - "Bagaimana MessageWindowChatMemory memutuskan pesan mana yang dihapus saat jendelanya penuh?" -> - "Bisakah saya mengimplementasikan penyimpanan memori kustom menggunakan database daripada di memori?" +> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) dan tanyakan: +> - "Bagaimana MessageWindowChatMemory memutuskan pesan mana yang dihapus saat jendela penuh?" +> - "Bisakah saya mengimplementasikan penyimpanan memori khusus menggunakan database daripada di memori?" > - "Bagaimana saya menambahkan ringkasan untuk mengompres riwayat percakapan lama?" -Endpoint obrolan stateless melewati memori sepenuhnya - hanya `chatModel.chat(prompt)` seperti quick start. Endpoint stateful menambahkan pesan ke memori, mengambil riwayat, dan menyertakan konteks itu di setiap permintaan. Konfigurasi model sama, pola berbeda. +Endpoint chat tanpa status melewati memori sepenuhnya - hanya `chatModel.chat(prompt)` seperti pada awal cepat. Endpoint dengan status menambahkan pesan ke memori, mengambil riwayat, dan menyertakan konteks tersebut dengan setiap permintaan. Konfigurasi model sama, pola berbeda. ## Menerapkan Infrastruktur Azure OpenAI @@ -144,23 +144,23 @@ azd up # Pilih langganan dan lokasi (eastus2 direkomendasikan) **PowerShell:** ```powershell cd 01-introduction -azd up # Pilih langganan dan lokasi (disarankan eastus2) +azd up # Pilih langganan dan lokasi (eastus2 direkomendasikan) ``` -> **Catatan:** Jika Anda menghadapi kesalahan timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), cukup jalankan kembali `azd up`. Sumber daya Azure mungkin masih dalam proses penyediaan di latar belakang, dan mencoba lagi memungkinkan deployment selesai setelah sumber daya mencapai status terminal. +> **Catatan:** Jika Anda mengalami kesalahan waktu habis (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), jalankan saja `azd up` lagi. Sumber daya Azure mungkin masih dalam proses penyediaan di latar belakang, dan mencoba ulang memungkinkan penyebaran selesai setelah sumber daya mencapai status terminal. Ini akan: 1. Menerapkan sumber daya Azure OpenAI dengan model GPT-5.2 dan text-embedding-3-small -2. Otomatis membuat file `.env` di root proyek dengan kredensial +2. Secara otomatis menghasilkan file `.env` di root proyek dengan kredensial 3. Mengatur semua variabel lingkungan yang diperlukan -**Mengalami masalah deployment?** Lihat [Infrastructure README](infra/README.md) untuk pemecahan masalah terperinci termasuk konflik nama subdomain, langkah manual deployment Azure Portal, dan panduan konfigurasi model. +**Mengalami masalah penyebaran?** Lihat [README Infrastruktur](infra/README.md) untuk pemecahan masalah mendetail termasuk konflik nama subdomain, langkah penyebaran manual di Portal Azure, dan panduan konfigurasi model. -**Verifikasi deployment berhasil:** +**Verifikasi penyebaran berhasil:** **Bash:** ```bash -cat ../.env # Harus menampilkan AZURE_OPENAI_ENDPOINT, API_KEY, dll. +cat ../.env # Harus menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, dll. ``` **PowerShell:** @@ -168,7 +168,7 @@ cat ../.env # Harus menampilkan AZURE_OPENAI_ENDPOINT, API_KEY, dll. Get-Content ..\.env # Harus menampilkan AZURE_OPENAI_ENDPOINT, API_KEY, dll. ``` -> **Catatan:** Perintah `azd up` otomatis menghasilkan file `.env`. Jika perlu memperbarui nanti, Anda dapat mengedit manual file `.env` atau membuat ulang dengan menjalankan: +> **Catatan:** Perintah `azd up` secara otomatis menghasilkan file `.env`. Jika Anda perlu memperbaruinya nanti, Anda bisa mengedit file `.env` secara manual atau menghasilkannya ulang dengan menjalankan: > > **Bash:** > ```bash @@ -184,7 +184,7 @@ Get-Content ..\.env # Harus menampilkan AZURE_OPENAI_ENDPOINT, API_KEY, dll. ## Menjalankan Aplikasi Secara Lokal -**Verifikasi deployment:** +**Verifikasi penyebaran:** Pastikan file `.env` ada di direktori root dengan kredensial Azure. Jalankan ini dari direktori modul (`01-introduction/`): @@ -200,23 +200,23 @@ Get-Content ..\.env # Harus menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Mulai aplikasi:** -**Pilihan 1: Menggunakan Spring Boot Dashboard (Direkomendasikan untuk pengguna VS Code)** +**Opsi 1: Menggunakan Spring Boot Dashboard (Disarankan untuk pengguna VS Code)** Dev container mencakup ekstensi Spring Boot Dashboard, yang menyediakan antarmuka visual untuk mengelola semua aplikasi Spring Boot. Anda dapat menemukannya di Bilah Aktivitas di sisi kiri VS Code (cari ikon Spring Boot). Dari Spring Boot Dashboard, Anda dapat: - Melihat semua aplikasi Spring Boot yang tersedia di workspace -- Memulai/berhenti aplikasi dengan satu klik +- Mulai/berhenti aplikasi dengan satu klik - Melihat log aplikasi secara real-time - Memantau status aplikasi -Cukup klik tombol putar di samping "introduction" untuk memulai modul ini, atau mulai semua modul sekaligus. +Cukup klik tombol main di sebelah "introduction" untuk memulai modul ini, atau mulai semua modul sekaligus. Spring Boot Dashboard *Spring Boot Dashboard di VS Code — mulai, hentikan, dan pantau semua modul dari satu tempat* -**Pilihan 2: Menggunakan skrip shell** +**Opsi 2: Menggunakan skrip shell** Mulai semua aplikasi web (modul 01-04): @@ -248,7 +248,7 @@ cd 01-introduction Kedua skrip secara otomatis memuat variabel lingkungan dari file `.env` root dan akan membangun JAR jika belum ada. -> **Catatan:** Jika Anda ingin membangun semua modul secara manual sebelum mulai: +> **Catatan:** Jika Anda lebih suka membangun semua modul secara manual sebelum memulai: > > **Bash:** > ```bash @@ -262,49 +262,49 @@ Kedua skrip secara otomatis memuat variabel lingkungan dari file `.env` root dan > mvn clean package -DskipTests > ``` -Buka http://localhost:8080 di peramban Anda. +Buka http://localhost:8080 di browser Anda. -**Untuk berhenti:** +**Untuk menghentikan:** **Bash:** ```bash -./stop.sh # Modul ini saja +./stop.sh # Hanya modul ini # Atau cd .. && ./stop-all.sh # Semua modul ``` **PowerShell:** ```powershell -.\stop.ps1 # Modul ini saja +.\stop.ps1 # Hanya modul ini # Atau cd ..; .\stop-all.ps1 # Semua modul ``` ## Menggunakan Aplikasi -Aplikasi menyediakan antarmuka web dengan dua implementasi obrolan berdampingan. +Aplikasi menyediakan antarmuka web dengan dua implementasi chat berdampingan. -Application Home Screen +Layar Utama Aplikasi -*Dashboard menampilkan opsi Simple Chat (stateless) dan Conversational Chat (stateful)* +*Dashboard menunjukkan opsi Simple Chat (tanpa status) dan Conversational Chat (dengan status)* -### Obrolan Stateless (Panel Kiri) +### Chat Tanpa Status (Panel Kiri) -Coba ini dulu. Tanyakan "Nama saya John" lalu langsung tanya "Siapa nama saya?" Model tidak akan mengingat karena setiap pesan bersifat independen. Ini menunjukkan masalah inti integrasi model bahasa dasar - tanpa konteks percakapan. +Coba ini dulu. Tanyakan "Nama saya John" dan kemudian langsung tanya "Siapa nama saya?" Model tidak akan mengingat karena setiap pesan bersifat independen. Ini menunjukkan masalah inti dari integrasi model bahasa dasar - tidak ada konteks percakapan. -Stateless Chat Demo +Demo Chat Tanpa Status *AI tidak mengingat nama Anda dari pesan sebelumnya* -### Obrolan Stateful (Panel Kanan) +### Chat Dengan Status (Panel Kanan) -Sekarang coba urutan yang sama di sini. Tanyakan "Nama saya John" lalu "Siapa nama saya?" Kali ini ia mengingatnya. Bedanya adalah MessageWindowChatMemory - ia menjaga riwayat percakapan dan menyertakannya dengan setiap permintaan. Inilah cara AI percakapan produksi bekerja. +Sekarang coba urutan yang sama di sini. Tanyakan "Nama saya John" dan kemudian "Siapa nama saya?" Kali ini diingat. Bedanya adalah MessageWindowChatMemory - ini mempertahankan riwayat percakapan dan memasukkannya dengan setiap permintaan. Inilah cara kerja AI percakapan produksi. -Stateful Chat Demo +Demo Chat Dengan Status -*AI mengingat nama Anda dari awal percakapan* +*AI mengingat nama Anda dari percakapan sebelumnya* -Kedua panel menggunakan model GPT-5.2 yang sama. Satu-satunya perbedaan adalah memori. Ini membuat jelas apa yang dibawa memori ke aplikasi Anda dan mengapa penting untuk kasus penggunaan nyata. +Kedua panel menggunakan model GPT-5.2 yang sama. Satu-satunya perbedaan adalah memori. Ini membuat jelas apa yang dibawa memori ke aplikasi Anda dan mengapa itu penting untuk kasus penggunaan nyata. ## Langkah Selanjutnya @@ -312,11 +312,11 @@ Kedua panel menggunakan model GPT-5.2 yang sama. Satu-satunya perbedaan adalah m --- -**Navigasi:** [← Sebelumnya: Modul 00 - Quick Start](../00-quick-start/README.md) | [Kembali ke Utama](../README.md) | [Berikutnya: Modul 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigasi:** [← Kembali ke Utama](../README.md) | [Berikutnya: Modul 02 - Rekayasa Prompt →](../02-prompt-engineering/README.md) --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk mencapai ketepatan, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sahih. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau tafsir yang timbul dari penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk mencapai akurasi, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/id/02-prompt-engineering/README.md b/translations/id/02-prompt-engineering/README.md index 2845b85b2..919f922ad 100644 --- a/translations/id/02-prompt-engineering/README.md +++ b/translations/id/02-prompt-engineering/README.md @@ -2,80 +2,80 @@ ## Daftar Isi -- [Video Walkthrough](../../../02-prompt-engineering) -- [Apa yang Akan Anda Pelajari](../../../02-prompt-engineering) -- [Persyaratan Awal](../../../02-prompt-engineering) -- [Memahami Rekayasa Prompt](../../../02-prompt-engineering) -- [Dasar-Dasar Rekayasa Prompt](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Template Prompt](../../../02-prompt-engineering) -- [Pola Lanjutan](../../../02-prompt-engineering) -- [Jalankan Aplikasi](../../../02-prompt-engineering) -- [Cuplikan Aplikasi](../../../02-prompt-engineering) -- [Menjelajah Pola](../../../02-prompt-engineering) - - [Antusiasme Rendah vs Tinggi](../../../02-prompt-engineering) - - [Eksekusi Tugas (Preambul Alat)](../../../02-prompt-engineering) - - [Kode yang Merefleksikan Diri](../../../02-prompt-engineering) - - [Analisis Terstruktur](../../../02-prompt-engineering) - - [Chat Multi-Turn](../../../02-prompt-engineering) - - [Penalaran Langkah-demi-Langkah](../../../02-prompt-engineering) - - [Output Terbatas](../../../02-prompt-engineering) -- [Apa yang Sebenarnya Anda Pelajari](../../../02-prompt-engineering) -- [Langkah Selanjutnya](../../../02-prompt-engineering) +- [Video Walkthrough](#video-walkthrough) +- [Apa yang Akan Anda Pelajari](#apa-yang-akan-anda-pelajari) +- [Prasyarat](#prasyarat) +- [Memahami Rekayasa Prompt](#memahami-rekayasa-prompt) +- [Dasar-dasar Rekayasa Prompt](#dasar-dasar-rekayasa-prompt) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Pola Lanjutan](#pola-lanjutan) +- [Jalankan Aplikasi](#jalankan-aplikasi) +- [Screenshot Aplikasi](#tangkapan-layar-aplikasi) +- [Menjelajahi Pola-pola](#menjelajahi-pola) + - [Eagerness Rendah vs Tinggi](#low-vs-high-eagerness) + - [Eksekusi Tugas (Preambel Alat)](#task-execution-tool-preambles) + - [Kode Reflektif Diri](#self-reflecting-code) + - [Analisis Terstruktur](#structured-analysis) + - [Obrolan Multi-Turn](#multi-turn-chat) + - [Penalaran Langkah demi Langkah](#step-by-step-reasoning) + - [Output Terbatas](#constrained-output) +- [Apa yang Sebenarnya Anda Pelajari](#apa-yang-sebenarnya-anda-pelajari) +- [Langkah Berikutnya](#langkah-berikutnya) ## Video Walkthrough -Tonton sesi langsung ini yang menjelaskan cara memulai dengan modul ini: +Tonton sesi langsung ini yang menjelaskan bagaimana memulai dengan modul ini: Prompt Engineering with LangChain4j - Live Session ## Apa yang Akan Anda Pelajari -Diagram berikut memberikan gambaran tentang topik utama dan keterampilan yang akan Anda kembangkan dalam modul ini — dari teknik penyempurnaan prompt hingga alur kerja langkah demi langkah yang akan Anda ikuti. +Diagram berikut memberikan gambaran tentang topik dan keterampilan utama yang akan Anda kembangkan di modul ini — dari teknik penyempurnaan prompt hingga alur kerja langkah demi langkah yang akan Anda ikuti. -What You'll Learn +Apa yang Akan Anda Pelajari -Dalam modul sebelumnya, Anda menjelajahi interaksi dasar LangChain4j dengan Model GitHub dan melihat bagaimana memori memungkinkan AI percakapan dengan Azure OpenAI. Sekarang kita akan fokus pada bagaimana Anda mengajukan pertanyaan — prompt itu sendiri — menggunakan GPT-5.2 dari Azure OpenAI. Cara Anda menyusun prompt secara dramatis memengaruhi kualitas jawaban yang Anda dapatkan. Kami mulai dengan tinjauan teknik prompting dasar, lalu berlanjut ke delapan pola lanjutan yang memanfaatkan sepenuhnya kemampuan GPT-5.2. +Di modul sebelumnya, Anda melihat bagaimana memori memungkinkan AI percakapan dengan Azure OpenAI. Sekarang kita akan fokus pada bagaimana Anda mengajukan pertanyaan — prompt itu sendiri — menggunakan GPT-5.2 dari Azure OpenAI. Cara Anda menyusun prompt sangat memengaruhi kualitas jawaban yang Anda dapatkan. Kita mulai dengan tinjauan teknik prompting dasar, lalu berlanjut ke delapan pola lanjutan yang memanfaatkan sepenuhnya kemampuan GPT-5.2. -Kami menggunakan GPT-5.2 karena memperkenalkan kontrol penalaran - Anda dapat memberi tahu model seberapa banyak berpikir sebelum menjawab. Ini membuat berbagai strategi prompting menjadi lebih jelas dan membantu Anda memahami kapan menggunakan setiap pendekatan. Kami juga akan mendapat manfaat dari batasan rate lebih sedikit di Azure untuk GPT-5.2 dibandingkan Model GitHub. +Kita akan menggunakan GPT-5.2 karena ia memperkenalkan kontrol penalaran - Anda dapat memberi tahu model seberapa banyak berpikir sebelum menjawab. Ini membuat berbagai strategi prompting lebih jelas dan membantu Anda memahami kapan menggunakan pendekatan yang mana. -## Persyaratan Awal +## Prasyarat -- Menyelesaikan Modul 01 (sumber daya Azure OpenAI telah dideploy) +- Telah menyelesaikan Modul 01 (sumber daya Azure OpenAI telah dideploy) - File `.env` di direktori root dengan kredensial Azure (dibuat oleh `azd up` di Modul 01) -> **Catatan:** Jika Anda belum menyelesaikan Modul 01, ikuti instruksi deployment di sana terlebih dahulu. +> **Catatan:** Jika Anda belum menyelesaikan Modul 01, ikuti instruksi penyebaran di sana terlebih dahulu. ## Memahami Rekayasa Prompt -Pada intinya, rekayasa prompt adalah perbedaan antara instruksi yang samar dan yang tepat, seperti yang ditunjukkan perbandingan di bawah ini. +Pada dasarnya, rekayasa prompt adalah perbedaan antara instruksi yang samar dan yang spesifik, seperti yang diilustrasikan pada perbandingan di bawah ini. -What is Prompt Engineering? +Apa itu Rekayasa Prompt? -Rekayasa prompt adalah tentang merancang teks input yang secara konsisten memberikan hasil yang Anda butuhkan. Ini bukan hanya tentang mengajukan pertanyaan - ini tentang menyusun permintaan sehingga model memahami dengan tepat apa yang Anda inginkan dan bagaimana menyajikannya. +Rekayasa prompt adalah tentang merancang teks input yang secara konsisten memberikan hasil yang Anda butuhkan. Ini bukan hanya tentang mengajukan pertanyaan - ini tentang menyusun permintaan agar model memahami dengan tepat apa yang Anda inginkan dan bagaimana cara menyampaikannya. -Pikirkan seperti memberi instruksi kepada rekan kerja. "Perbaiki bug" itu samar. "Perbaiki null pointer exception di UserService.java baris 45 dengan menambahkan pengecekan null" itu spesifik. Model bahasa bekerja dengan cara yang sama — spesifikasi dan struktur sangat penting. +Bayangkan seperti memberikan instruksi ke rekan kerja. "Perbaiki bug" itu samar. "Perbaiki null pointer exception di UserService.java baris 45 dengan menambahkan pengecekan null" itu spesifik. Model bahasa bekerja dengan cara yang sama - spesifik dan struktur sangat penting. -Diagram di bawah menunjukkan bagaimana LangChain4j masuk ke dalam gambar ini — menghubungkan pola prompt Anda ke model melalui blok bangunan SystemMessage dan UserMessage. +Diagram di bawah ini menunjukkan bagaimana LangChain4j masuk ke dalam gambar ini — menghubungkan pola prompt Anda ke model melalui blok bangunan SystemMessage dan UserMessage. -How LangChain4j Fits +Bagaimana LangChain4j Bekerja -LangChain4j menyediakan infrastruktur — koneksi model, memori, dan tipe pesan — sementara pola prompt hanyalah teks yang disusun dengan hati-hati yang Anda kirim melalui infrastruktur itu. Blok bangunan kunci adalah `SystemMessage` (yang mengatur perilaku dan peran AI) dan `UserMessage` (yang membawa permintaan Anda yang sebenarnya). +LangChain4j menyediakan infrastruktur — koneksi model, memori, dan jenis pesan — sementara pola prompt hanyalah teks yang disusun dengan cermat yang Anda kirimkan melalui infrastruktur itu. Blok bangunan kunci adalah `SystemMessage` (yang mengatur perilaku dan peran AI) dan `UserMessage` (yang membawa permintaan Anda yang sebenarnya). -## Dasar-Dasar Rekayasa Prompt +## Dasar-dasar Rekayasa Prompt -Lima teknik inti yang ditunjukkan di bawah ini membentuk fondasi rekayasa prompt yang efektif. Masing-masing menangani aspek berbeda dari bagaimana Anda berkomunikasi dengan model bahasa. +Lima teknik inti yang ditunjukkan di bawah ini membentuk dasar rekayasa prompt yang efektif. Masing-masing menangani aspek berbeda dari cara Anda berkomunikasi dengan model bahasa. -Five Prompt Engineering Patterns Overview +Gambaran Lima Pola Rekayasa Prompt -Sebelum menyelami pola-pola lanjutan dalam modul ini, mari tinjau kembali lima teknik prompting dasar. Ini adalah blok bangunan yang harus diketahui setiap insinyur prompt. Jika Anda sudah mengerjakan [modul Quick Start](../00-quick-start/README.md#2-prompt-patterns), Anda sudah melihat ini dalam praktik — di sini kerangka konseptual di baliknya. +Sebelum menyelami pola-pola lanjutan di modul ini, mari kita tinjau lima teknik prompting dasar. Ini adalah blok bangunan yang harus diketahui setiap insinyur prompt. ### Zero-Shot Prompting -Pendekatan paling sederhana: beri instruksi langsung ke model tanpa contoh. Model sepenuhnya mengandalkan pelatihannya untuk memahami dan menjalankan tugas. Ini bekerja baik untuk permintaan yang langsung di mana perilaku yang diharapkan jelas. +Pendekatan paling sederhana: berikan model instruksi langsung tanpa contoh. Model sepenuhnya mengandalkan pelatihannya untuk memahami dan menjalankan tugas tersebut. Ini bekerja baik untuk permintaan yang langsung di mana perilaku yang diharapkan jelas. Zero-Shot Prompting @@ -84,18 +84,18 @@ Pendekatan paling sederhana: beri instruksi langsung ke model tanpa contoh. Mode ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// Respon: "Positif" +// Respons: "Positif" ``` **Kapan digunakan:** Klasifikasi sederhana, pertanyaan langsung, terjemahan, atau tugas apa pun yang dapat ditangani model tanpa panduan tambahan. ### Few-Shot Prompting -Berikan contoh yang menunjukkan pola yang ingin Anda model ikuti. Model belajar format input-output yang diharapkan dari contoh Anda dan menerapkannya ke input baru. Ini secara dramatis meningkatkan konsistensi untuk tugas di mana format atau perilaku yang diinginkan tidak jelas. +Berikan contoh-contoh yang menunjukkan pola yang Anda ingin model ikuti. Model belajar format input-output yang diharapkan dari contoh Anda dan menerapkannya ke input baru. Ini secara dramatis meningkatkan konsistensi untuk tugas yang format atau perilakunya tidak jelas. Few-Shot Prompting -*Belajar dari contoh — model mengidentifikasi pola dan menerapkannya pada input baru* +*Belajar dari contoh — model mengidentifikasi pola dan menerapkannya ke input baru* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kapan digunakan:** Klasifikasi khusus, format yang konsisten, tugas domain-spesifik, atau ketika hasil zero-shot tidak konsisten. +**Kapan digunakan:** Klasifikasi khusus, format konsisten, tugas spesifik domain, atau ketika hasil zero-shot tidak konsisten. ### Chain of Thought -Minta model menunjukkan penalarannya langkah demi langkah. Alih-alih langsung menuju jawaban, model memecah masalah dan mengerjakan setiap bagian secara eksplisit. Ini meningkatkan akurasi pada tugas matematika, logika, dan penalaran bertahap. +Minta model menunjukkan penalarannya langkah demi langkah. Alih-alih langsung memberikan jawaban, model memecah masalah dan mengerjakan setiap bagian secara eksplisit. Ini meningkatkan akurasi pada masalah matematika, logika, dan penalaran multi-langkah. Chain of Thought Prompting -*Penalaran langkah demi langkah — memecah masalah kompleks menjadi langkah logis eksplisit* +*Penalaran langkah demi langkah — memecah masalah kompleks menjadi langkah logis yang eksplisit* ```java String prompt = """ @@ -137,11 +137,11 @@ String response = model.chat(prompt); ### Role-Based Prompting -Tetapkan persona atau peran untuk AI sebelum Anda mengajukan pertanyaan. Ini memberikan konteks yang membentuk nada, kedalaman, dan fokus respons. "Arsitek perangkat lunak" memberikan saran berbeda dari "pengembang junior" atau "auditor keamanan". +Tetapkan persona atau peran untuk AI sebelum mengajukan pertanyaan Anda. Ini memberikan konteks yang membentuk nada, kedalaman, dan fokus jawaban. "Arsitek perangkat lunak" memberikan nasihat berbeda dari "pengembang junior" atau "auditor keamanan". Role-Based Prompting -*Menetapkan konteks dan persona — pertanyaan yang sama mendapat respons berbeda tergantung peran yang ditugaskan* +*Menetapkan konteks dan persona — pertanyaan yang sama mendapat jawaban berbeda tergantung pada peran yang diberikan* ```java String prompt = """ @@ -157,13 +157,13 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kapan digunakan:** Review kode, pengajaran, analisis domain-spesifik, atau saat Anda membutuhkan respons yang disesuaikan dengan tingkat keahlian atau perspektif tertentu. +**Kapan digunakan:** Review kode, pengajaran, analisis spesifik domain, atau saat Anda membutuhkan jawaban yang disesuaikan dengan tingkat keahlian atau perspektif tertentu. ### Prompt Templates -Membuat prompt yang dapat digunakan ulang dengan placeholder variabel. Alih-alih menulis prompt baru setiap kali, definisikan template sekali dan isi dengan nilai berbeda. Kelas `PromptTemplate` di LangChain4j memudahkan ini dengan sintaks `{{variable}}`. +Buat prompt yang dapat digunakan ulang dengan placeholder variabel. Alih-alih menulis prompt baru setiap kali, definisikan template sekali dan isi dengan nilai berbeda. Kelas `PromptTemplate` dari LangChain4j memudahkan ini dengan sintaks `{{variable}}`. -Prompt Templates +Template Prompt *Prompt yang dapat digunakan ulang dengan placeholder variabel — satu template, banyak penggunaan* @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Kapan digunakan:** Query berulang dengan input yang berbeda, pemrosesan batch, membangun alur kerja AI yang dapat digunakan ulang, atau skenario apa pun di mana struktur prompt tetap sama tapi data berubah. +**Kapan digunakan:** Pertanyaan berulang dengan input berbeda, pemrosesan batch, membangun workflow AI yang dapat digunakan ulang, atau skenario apa pun di mana struktur prompt tetap sama tetapi datanya berubah. --- -Lima dasar ini memberi Anda toolkit solid untuk sebagian besar tugas prompting. Sisanya dari modul ini membangun di atasnya dengan **delapan pola lanjutan** yang memanfaatkan kontrol penalaran, evaluasi mandiri, dan kemampuan output terstruktur GPT-5.2. +Lima dasar ini memberi Anda alat yang kuat untuk sebagian besar tugas prompting. Sisa modul ini membangun di atasnya dengan **delapan pola lanjutan** yang memanfaatkan kontrol penalaran, evaluasi diri, dan kemampuan output terstruktur GPT-5.2. ## Pola Lanjutan -Dengan dasar-dasar telah dibahas, mari kita beralih ke delapan pola lanjutan yang menjadikan modul ini unik. Tidak semua masalah membutuhkan pendekatan yang sama. Beberapa pertanyaan membutuhkan jawaban cepat, lainnya butuh pemikiran mendalam. Ada yang butuh penalaran yang terlihat, ada juga yang hanya butuh hasil. Setiap pola di bawah dioptimalkan untuk skenario berbeda — dan kontrol penalaran GPT-5.2 membuat perbedaan ini semakin jelas. +Setelah memahami dasar, mari beralih ke delapan pola lanjutan yang membuat modul ini unik. Tidak semua masalah memerlukan pendekatan yang sama. Beberapa pertanyaan perlu jawaban cepat, beberapa perlu pemikiran mendalam. Ada yang perlu penalaran yang terlihat, ada yang hanya perlu hasil. Setiap pola di bawah ini dioptimalkan untuk skenario berbeda — dan kontrol penalaran GPT-5.2 membuat perbedaan itu semakin nyata. -Eight Prompting Patterns +Delapan Pola Prompting -*Ikhtisar delapan pola rekayasa prompt dan kasus penggunaannya* +*Gambaran delapan pola rekayasa prompt dan kasus penggunaannya* -GPT-5.2 menambahkan dimensi lain ke pola-pola ini: *kontrol penalaran*. Penggeser di bawah ini menunjukkan bagaimana Anda bisa mengatur tingkat berpikir model — dari jawaban cepat dan langsung sampai analisis yang mendalam dan menyeluruh. +GPT-5.2 menambahkan dimensi lain ke pola-pola ini: *kontrol penalaran*. Slider di bawah ini menunjukkan bagaimana Anda dapat menyesuaikan usaha berpikir model — dari jawaban cepat dan langsung hingga analisis mendalam dan menyeluruh. -Reasoning Control with GPT-5.2 +Kontrol Penalaran dengan GPT-5.2 -*Kontrol penalaran GPT-5.2 memungkinkan Anda menentukan seberapa banyak model harus berpikir — dari jawaban cepat hingga eksplorasi mendalam* +*Kontrol penalaran GPT-5.2 memungkinkan Anda menentukan seberapa banyak model harus berpikir — dari jawaban cepat langsung hingga eksplorasi yang mendalam* -**Antusiasme Rendah (Cepat & Fokus)** - Untuk pertanyaan sederhana di mana Anda ingin jawaban yang cepat dan langsung. Model melakukan penalaran minimal - maksimum 2 langkah. Gunakan ini untuk perhitungan, pencarian, atau pertanyaan langsung. +**Eagerness Rendah (Cepat & Fokus)** - Untuk pertanyaan sederhana di mana Anda menginginkan jawaban cepat dan langsung. Model melakukan penalaran minimal - maksimum 2 langkah. Gunakan ini untuk perhitungan, pencarian, atau pertanyaan yang langsung. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Jelajahi dengan GitHub Copilot:** Buka [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) dan tanyakan: -> - "Apa perbedaan antara pola prompting antusiasme rendah dan tinggi?" -> - "Bagaimana tag XML dalam prompt membantu menyusun respons AI?" +> - "Apa perbedaan antara pola eagerness rendah dan eagerness tinggi?" +> - "Bagaimana tag XML dalam prompt membantu menyusun jawaban AI?" > - "Kapan saya harus menggunakan pola refleksi diri vs instruksi langsung?" -**Antusiasme Tinggi (Mendalam & Menyeluruh)** - Untuk masalah kompleks di mana Anda ingin analisis yang komprehensif. Model menjelajah dengan menyeluruh dan menunjukkan penalaran rinci. Gunakan ini untuk desain sistem, keputusan arsitektur, atau riset kompleks. +**Eagerness Tinggi (Mendalam & Menyeluruh)** - Untuk masalah kompleks di mana Anda menginginkan analisis komprehensif. Model mengeksplorasi secara menyeluruh dan menunjukkan penalaran terperinci. Gunakan ini untuk desain sistem, keputusan arsitektur, atau riset kompleks. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Eksekusi Tugas (Kemajuan Langkah-demi-Langkah)** - Untuk alur kerja multi-langkah. Model menyediakan rencana awal, menceritakan setiap langkah saat dikerjakan, lalu memberi ringkasan. Gunakan ini untuk migrasi, implementasi, atau proses multi-langkah apa pun. +**Eksekusi Tugas (Kemajuan Langkah demi Langkah)** - Untuk alur kerja multi-langkah. Model memberikan rencana di awal, menjelaskan setiap langkah saat bekerja, lalu memberi ringkasan. Gunakan ini untuk migrasi, implementasi, atau proses multi-langkah apa pun. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Prompting Chain-of-Thought secara eksplisit meminta model untuk menunjukkan proses penalarannya, meningkatkan akurasi untuk tugas kompleks. Pemecahan langkah demi langkah membantu manusia dan AI memahami logika. +Chain-of-Thought prompting secara eksplisit meminta model menunjukkan proses penalarannya, meningkatkan akurasi untuk tugas kompleks. Pemecahan langkah demi langkah membantu manusia dan AI memahami logika. -> **🤖 Coba dengan Chat [GitHub Copilot](https://github.com/features/copilot):** Tanyakan tentang pola ini: -> - "Bagaimana saya mengadaptasi pola eksekusi tugas untuk operasi jangka panjang?" -> - "Apa praktik terbaik untuk menyusun preambul alat di aplikasi produksi?" -> - "Bagaimana cara menangkap dan menampilkan pembaruan kemajuan perantara di UI?" +> **🤖 Coba dengan Obrolan [GitHub Copilot](https://github.com/features/copilot):** Tanyakan tentang pola ini: +> - "Bagaimana saya menyesuaikan pola eksekusi tugas untuk operasi yang berjalan lama?" +> - "Apa praktik terbaik untuk menyusun preambel alat dalam aplikasi produksi?" +> - "Bagaimana cara menangkap dan menampilkan pembaruan kemajuan antara dalam UI?" -Diagram berikut mengilustrasikan alur kerja Rencana → Eksekusi → Ringkasan ini. +Diagram di bawah ini menggambarkan alur kerja Plan → Execute → Summarize ini. -Task Execution Pattern +Pola Eksekusi Tugas -*Alur kerja Rencana → Eksekusi → Ringkasan untuk tugas multi-langkah* +*Alur kerja Plan → Execute → Summarize untuk tugas multi-langkah* -**Kode yang Merefleksikan Diri** - Untuk menghasilkan kode berkualitas produksi. Model menghasilkan kode mengikuti standar produksi dengan penanganan kesalahan yang tepat. Gunakan ini saat membangun fitur atau layanan baru. +**Kode Reflektif Diri** - Untuk menghasilkan kode berkualitas produksi. Model menghasilkan kode sesuai standar produksi dengan penanganan kesalahan yang sesuai. Gunakan ini saat membangun fitur atau layanan baru. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagram berikut menunjukkan siklus perbaikan iteratif ini — menghasilkan, mengevaluasi, mengidentifikasi kelemahan, dan menyempurnakan sampai kode memenuhi standar produksi. +Diagram di bawah ini menunjukkan siklus perbaikan iteratif — menghasilkan, mengevaluasi, mengidentifikasi kelemahan, dan menyempurnakan sampai kode memenuhi standar produksi. -Self-Reflection Cycle +Siklus Refleksi Diri -*Siklus perbaikan iteratif - hasilkan, evaluasi, identifikasi masalah, perbaiki, ulangi* +*Siklus perbaikan iteratif - menghasilkan, mengevaluasi, identifikasi masalah, perbaiki, ulangi* -**Analisis Terstruktur** - Untuk evaluasi yang konsisten. Model meninjau kode menggunakan kerangka kerja tetap (kebenaran, praktik, kinerja, keamanan, pemeliharaan). Gunakan ini untuk review kode atau penilaian kualitas. +**Analisis Terstruktur** - Untuk evaluasi yang konsisten. Model meninjau kode menggunakan kerangka kerja tetap (kebenaran, praktik, performa, keamanan, pemeliharaan). Gunakan ini untuk review kode atau penilaian kualitas. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Coba dengan Chat [GitHub Copilot](https://github.com/features/copilot):** Tanyakan tentang analisis terstruktur: -> - "Bagaimana saya dapat menyesuaikan kerangka analisis untuk berbagai jenis review kode?" -> - "Apa cara terbaik mengurai dan memproses output terstruktur secara programatik?" -> - "Bagaimana memastikan tingkat keparahan yang konsisten di berbagai sesi review?" +> **🤖 Coba dengan Obrolan [GitHub Copilot](https://github.com/features/copilot):** Tanyakan tentang analisis terstruktur: +> - "Bagaimana saya dapat menyesuaikan kerangka analisis untuk jenis review kode yang berbeda?" +> - "Apa cara terbaik untuk mengurai dan menangani output terstruktur secara programatik?" +> - "Bagaimana saya memastikan tingkat keparahan konsisten di berbagai sesi review?" -Diagram berikut menunjukkan bagaimana kerangka terstruktur ini mengorganisasi review kode ke dalam kategori konsisten dengan tingkat keparahan. +Diagram berikut menunjukkan bagaimana kerangka kerja terstruktur ini mengorganisasikan review kode ke dalam kategori konsisten dengan tingkat keparahan. -Structured Analysis Pattern +Pola Analisis Terstruktur -*Kerangka kerja untuk review kode konsisten dengan tingkat keparahan* +*Kerangka kerja untuk review kode yang konsisten dengan tingkat keparahan* -**Chat Multi-Turn** - Untuk percakapan yang membutuhkan konteks. Model mengingat pesan sebelumnya dan membangun dari sana. Gunakan ini untuk sesi bantuan interaktif atau tanya jawab kompleks. +**Obrolan Multi-Turn** - Untuk percakapan yang membutuhkan konteks. Model mengingat pesan sebelumnya dan membangun dari situ. Gunakan ini untuk sesi bantuan interaktif atau tanya jawab kompleks. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Diagram berikut memvisualisasikan bagaimana konteks percakapan terakumulasi dengan setiap giliran dan bagaimana itu terkait dengan batas token model. +Diagram di bawah memvisualisasikan bagaimana konteks percakapan terkumpul dengan setiap giliran dan bagaimana hal itu terkait dengan batas token model. -Context Memory +Memori Konteks -*Bagaimana konteks percakapan terkumpul selama beberapa giliran sampai mencapai batas token* -**Penalaran Langkah demi Langkah** - Untuk masalah yang memerlukan logika yang terlihat. Model menunjukkan penalaran eksplisit untuk setiap langkah. Gunakan ini untuk masalah matematika, teka-teki logika, atau ketika Anda perlu memahami proses pemikiran. +*Bagaimana konteks percakapan terkumpul selama beberapa giliran hingga mencapai batas token* + +**Penalaran Langkah demi Langkah** - Untuk masalah yang memerlukan logika yang terlihat. Model menunjukkan penalaran eksplisit untuk setiap langkah. Gunakan ini untuk masalah matematika, teka-teki logika, atau saat Anda perlu memahami proses pemikiran. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagram di bawah ini menggambarkan bagaimana model memecah masalah menjadi langkah-langkah logis yang eksplisit dan bernomor. +Diagram di bawah ini mengilustrasikan bagaimana model memecah masalah menjadi langkah logis bernomor yang eksplisit. Pola Langkah demi Langkah - *Memecah masalah menjadi langkah-langkah logis yang eksplisit* -**Output Terbatas** - Untuk respons dengan persyaratan format tertentu. Model mengikuti aturan format dan panjang secara ketat. Gunakan ini untuk ringkasan atau ketika Anda memerlukan struktur output yang tepat. +**Output Terbatas** - Untuk respons dengan persyaratan format tertentu. Model secara ketat mengikuti aturan format dan panjang. Gunakan ini untuk ringkasan atau saat Anda membutuhkan struktur output yang tepat. ```java String prompt = """ @@ -420,11 +420,11 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagram berikut menunjukkan bagaimana batasan membimbing model untuk menghasilkan output yang benar-benar mengikuti format dan persyaratan panjang Anda. +Diagram berikut menunjukkan bagaimana batasan membimbing model untuk menghasilkan output yang secara ketat mematuhi persyaratan format dan panjang Anda. -Pola Output Terbatas +Constrained Output Pattern -*Menegakkan persyaratan format, panjang, dan struktur tertentu* +*Memaksakan persyaratan format, panjang, dan struktur tertentu* ## Jalankan Aplikasi @@ -444,19 +444,19 @@ Get-Content ..\.env # Harus menampilkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Mulai aplikasi:** -> **Catatan:** Jika Anda sudah memulai semua aplikasi menggunakan `./start-all.sh` dari direktori root (seperti yang dijelaskan di Modul 01), modul ini sudah berjalan di port 8083. Anda dapat melewati perintah mulai di bawah dan langsung buka http://localhost:8083. +> **Catatan:** Jika Anda sudah memulai semua aplikasi menggunakan `./start-all.sh` dari direktori root (seperti yang dijelaskan di Modul 01), modul ini sudah berjalan di port 8083. Anda dapat melewati perintah mulai di bawah dan langsung menuju http://localhost:8083. -**Opsi 1: Menggunakan Spring Boot Dashboard (Disarankan untuk pengguna VS Code)** +**Opsi 1: Menggunakan Spring Boot Dashboard (Direkomendasikan untuk pengguna VS Code)** -Dev container sudah termasuk ekstensi Spring Boot Dashboard, yang menyediakan antarmuka visual untuk mengelola semua aplikasi Spring Boot. Anda dapat menemukannya di Activity Bar di sisi kiri VS Code (cari ikon Spring Boot). +Kontainer dev sudah menyertakan ekstensi Spring Boot Dashboard, yang menyediakan antarmuka visual untuk mengelola semua aplikasi Spring Boot. Anda dapat menemukannya di Activity Bar di sisi kiri VS Code (cari ikon Spring Boot). Dari Spring Boot Dashboard, Anda dapat: - Melihat semua aplikasi Spring Boot yang tersedia di workspace -- Memulai/berhenti aplikasi dengan satu klik +- Memulai/mengehentikan aplikasi dengan satu klik - Melihat log aplikasi secara real-time - Memantau status aplikasi -Cukup klik tombol play di sebelah "prompt-engineering" untuk memulai modul ini, atau mulai semua modul sekaligus. +Cukup klik tombol play di samping "prompt-engineering" untuk memulai modul ini, atau mulai semua modul sekaligus. Spring Boot Dashboard @@ -514,7 +514,7 @@ Buka http://localhost:8083 di browser Anda. **Bash:** ```bash -./stop.sh # Hanya modul ini +./stop.sh # Modul ini saja # Atau cd .. && ./stop-all.sh # Semua modul ``` @@ -528,81 +528,81 @@ cd ..; .\stop-all.ps1 # Semua modul ## Tangkapan Layar Aplikasi -Berikut adalah antarmuka utama modul rekayasa prompt, di mana Anda dapat bereksperimen dengan kedelapan pola secara berdampingan. +Berikut adalah antarmuka utama modul rekayasa prompt, tempat Anda dapat bereksperimen dengan delapan pola secara berdampingan. -Beranda Dashboard +Dashboard Home -*Dashboard utama yang menunjukkan semua 8 pola rekayasa prompt beserta karakteristik dan kasus penggunaannya* +*Dashboard utama menampilkan semua 8 pola rekayasa prompt dengan karakteristik dan kasus penggunaannya* ## Menjelajahi Pola -Antarmuka web memungkinkan Anda bereksperimen dengan berbagai strategi prompt. Setiap pola menyelesaikan masalah yang berbeda - coba untuk melihat kapan setiap pendekatan bersinar. +Antarmuka web memungkinkan Anda bereksperimen dengan berbagai strategi prompt. Setiap pola memecahkan masalah berbeda - coba untuk melihat kapan tiap pendekatan efektif. -> **Catatan: Streaming vs Non-Streaming** — Setiap halaman pola menawarkan dua tombol: **🔴 Stream Response (Live)** dan opsi **Non-streaming**. Streaming menggunakan Server-Sent Events (SSE) untuk menampilkan token secara real-time saat model menghasilkannya, sehingga Anda melihat progres langsung. Opsi non-streaming menunggu seluruh respons selesai baru menampilkannya. Untuk prompt yang memicu penalaran mendalam (misalnya, High Eagerness, Self-Reflecting Code), panggilan non-streaming dapat memakan waktu sangat lama — kadang menit — tanpa umpan balik yang terlihat. **Gunakan streaming saat bereksperimen dengan prompt kompleks** agar Anda dapat melihat model bekerja dan menghindari kesan bahwa permintaan kadaluwarsa. +> **Catatan: Streaming vs Non-Streaming** — Setiap halaman pola menawarkan dua tombol: **🔴 Stream Response (Live)** dan opsi **Non-streaming**. Streaming menggunakan Server-Sent Events (SSE) untuk menampilkan token secara real-time saat model menghasilkan, sehingga Anda melihat kemajuan segera. Opsi non-streaming menunggu seluruh respons sebelum menampilkannya. Untuk prompt yang memicu penalaran mendalam (misal, High Eagerness, Self-Reflecting Code), panggilan non-streaming bisa memakan waktu lama — terkadang menit — tanpa umpan balik terlihat. **Gunakan streaming saat bereksperimen dengan prompt kompleks** agar Anda bisa melihat model bekerja dan menghindari kesan request timeout. > -> **Catatan: Persyaratan Browser** — Fitur streaming menggunakan Fetch Streams API (`response.body.getReader()`) yang memerlukan browser penuh (Chrome, Edge, Firefox, Safari). Ini **tidak** berfungsi di Simple Browser bawaan VS Code, karena webview-nya tidak mendukung API ReadableStream. Jika Anda menggunakan Simple Browser, tombol non-streaming tetap berfungsi normal — hanya tombol streaming yang terpengaruh. Buka `http://localhost:8083` di browser eksternal untuk pengalaman penuh. +> **Catatan: Kebutuhan Browser** — Fitur streaming menggunakan Fetch Streams API (`response.body.getReader()`) yang membutuhkan browser penuh (Chrome, Edge, Firefox, Safari). Fitur ini **tidak** bekerja di Simple Browser bawaan VS Code, karena webview-nya tidak mendukung ReadableStream API. Jika menggunakan Simple Browser, tombol non-streaming tetap bekerja normal — hanya tombol streaming yang terpengaruh. Buka `http://localhost:8083` di browser eksternal untuk pengalaman lengkap. ### Low vs High Eagerness -Tanyakan pertanyaan sederhana seperti "Berapa 15% dari 200?" menggunakan Low Eagerness. Anda akan mendapatkan jawaban langsung dan instan. Sekarang tanyakan sesuatu yang kompleks seperti "Rancang strategi caching untuk API dengan trafik tinggi" menggunakan High Eagerness. Klik **🔴 Stream Response (Live)** dan lihat penalaran rinci model muncul token demi token. Model sama, struktur pertanyaan sama - tetapi prompt memberi tahu seberapa banyak pemikiran yang harus dilakukan. +Tanyakan pertanyaan sederhana seperti "What is 15% of 200?" menggunakan Low Eagerness. Anda akan mendapatkan jawaban langsung dan cepat. Sekarang tanyakan hal rumit seperti "Design a caching strategy for a high-traffic API" menggunakan High Eagerness. Klik **🔴 Stream Response (Live)** dan saksikan penalaran rinci model muncul token demi token. Model sama, struktur pertanyaan sama - tapi prompt memberi tahu seberapa banyak pemikiran yang harus dilakukan. -### Pelaksanaan Tugas (Tool Preambles) +### Task Execution (Tool Preambles) -Workflow multi-langkah mendapat manfaat dari perencanaan awal dan narasi kemajuan. Model menguraikan apa yang akan dilakukan, menceritakan tiap langkah, lalu merangkum hasil. +Alur kerja multi-langkah mendapat manfaat dari perencanaan awal dan penceritaan kemajuan. Model menguraikan apa yang akan dilakukan, menceritakan setiap langkah, lalu merangkum hasil. ### Self-Reflecting Code -Coba "Buat layanan validasi email". Alih-alih hanya menghasilkan kode dan berhenti, model menghasilkan, mengevaluasi berdasarkan kriteria kualitas, mengidentifikasi kelemahan, dan memperbaiki. Anda akan melihat iterasi hingga kode memenuhi standar produksi. +Coba "Create an email validation service". Alih-alih hanya menghasilkan kode dan berhenti, model menghasilkan, mengevaluasi berdasarkan kriteria kualitas, mengidentifikasi kelemahan, dan memperbaiki. Anda akan melihat iterasi hingga kode memenuhi standar produksi. -### Analisis Terstruktur +### Structured Analysis Review kode membutuhkan kerangka evaluasi yang konsisten. Model menganalisis kode menggunakan kategori tetap (kebenaran, praktik, performa, keamanan) dengan tingkat keparahan. ### Multi-Turn Chat -Tanyakan "Apa itu Spring Boot?" kemudian langsung lanjutkan dengan "Tunjukkan contoh". Model mengingat pertanyaan pertama Anda dan memberi contoh Spring Boot yang spesifik. Tanpa memori, pertanyaan kedua akan terlalu ambigu. +Tanyakan "What is Spring Boot?" lalu segera tindak lanjuti dengan "Show me an example". Model mengingat pertanyaan pertama dan memberikan contoh Spring Boot khusus. Tanpa memori, pertanyaan kedua terlalu ambigu. -### Penalaran Langkah demi Langkah +### Step-by-Step Reasoning -Pilih masalah matematika dan coba dengan Penalaran Langkah demi Langkah dan Low Eagerness. Low eagerness hanya memberi jawaban - cepat tapi buram. Penalaran langkah demi langkah menunjukkan setiap perhitungan dan keputusan. +Pilih masalah matematika dan coba dengan Step-by-Step Reasoning dan Low Eagerness. Low eagerness hanya memberi jawaban - cepat tapi tidak transparan. Langkah demi langkah menunjukkan setiap perhitungan dan keputusan. -### Output Terbatas +### Constrained Output -Saat Anda membutuhkan format atau jumlah kata tertentu, pola ini menegakkan kepatuhan ketat. Coba menghasilkan ringkasan dengan tepat 100 kata dalam format poin-poin. +Saat Anda membutuhkan format atau jumlah kata tertentu, pola ini menegakkan kepatuhan ketat. Coba buat ringkasan dengan tepat 100 kata dalam format poin-poin. ## Apa yang Sebenarnya Anda Pelajari -**Upaya Penalaran Mengubah Segalanya** +**Usaha Penalaran Mengubah Segalanya** -GPT-5.2 memungkinkan Anda mengontrol upaya komputasi lewat prompt Anda. Upaya rendah berarti respons cepat dengan eksplorasi minimal. Upaya tinggi berarti model mengambil waktu untuk berpikir mendalam. Anda belajar mencocokkan upaya dengan kompleksitas tugas - jangan membuang waktu untuk pertanyaan sederhana, tapi juga jangan terburu-buru pada keputusan kompleks. +GPT-5.2 memungkinkan Anda mengontrol usaha komputasi lewat prompt. Usaha rendah berarti respons cepat dengan eksplorasi minimal. Usaha tinggi berarti model meluangkan waktu untuk berpikir mendalam. Anda belajar mencocokkan usaha dengan kompleksitas tugas - jangan buang waktu untuk pertanyaan sederhana, tapi jangan terburu-buru pada keputusan rumit. **Struktur Membimbing Perilaku** -Perhatikan tag XML di dalam prompt? Mereka bukan hiasan. Model mengikuti instruksi terstruktur lebih andal daripada teks bebas. Saat Anda membutuhkan proses multi-langkah atau logika kompleks, struktur membantu model melacak posisinya dan tahap selanjutnya. Diagram di bawah memecah prompt yang terstruktur dengan baik, menunjukkan bagaimana tag seperti ``, ``, ``, ``, dan `` mengatur instruksi Anda ke dalam bagian yang jelas. +Perhatikan tag XML dalam prompt? Mereka bukan hiasan. Model mengikuti instruksi terstruktur lebih dapat diandalkan daripada teks bebas. Saat Anda butuh proses multi-langkah atau logika kompleks, struktur membantu model melacak posisi dan langkah selanjutnya. Diagram di bawah memecah prompt terstruktur dengan tag seperti ``, ``, ``, ``, dan `` yang mengorganisasi instruksi Anda menjadi bagian jelas. -Struktur Prompt +Prompt Structure -*Anatomi prompt yang terstruktur dengan bagian yang jelas dan organisasi bergaya XML* +*Anatomi prompt terstruktur dengan bagian jelas dan organisasi gaya XML* **Kualitas Melalui Evaluasi Diri** -Pola self-reflecting bekerja dengan membuat kriteria kualitas eksplisit. Alih-alih berharap model "melakukannya dengan benar", Anda memberi tahu secara tepat apa arti "benar": logika benar, penanganan error, performa, keamanan. Model kemudian dapat mengevaluasi outputnya sendiri dan memperbaiki. Ini mengubah pembuatan kode dari lotere menjadi proses. +Pola self-reflecting bekerja dengan membuat kriteria kualitas eksplisit. Alih-alih berharap model "melakukannya dengan benar", Anda memberitahu persis apa arti "benar": logika benar, penanganan error, performa, keamanan. Model kemudian bisa mengevaluasi output sendiri dan memperbaiki. Ini mengubah pembuatan kode dari keberuntungan menjadi proses. **Konteks Itu Terbatas** -Percakapan multi-putar bekerja dengan menyertakan riwayat pesan dalam tiap permintaan. Tapi ada batasnya - setiap model memiliki jumlah token maksimum. Saat percakapan bertambah, Anda memerlukan strategi untuk mempertahankan konteks relevan tanpa mencapai batas itu. Modul ini menunjukkan cara kerja memori; nanti Anda akan belajar kapan merangkum, kapan melupakan, dan kapan mengambil kembali. +Percakapan multi-giliran bekerja dengan menyertakan riwayat pesan pada setiap permintaan. Tapi ada batas - setiap model punya maksimum token. Saat percakapan bertambah, Anda perlu strategi menjaga konteks relevan tanpa melewati batas itu. Modul ini menunjukkan cara kerja memori; nanti Anda akan belajar kapan merangkum, kapan melupakan, dan kapan mengambil kembali. -## Langkah Selanjutnya +## Langkah Berikutnya **Modul Berikutnya:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigasi:** [← Sebelumnya: Modul 01 - Pengantar](../01-introduction/README.md) | [Kembali ke Utama](../README.md) | [Berikutnya: Modul 03 - RAG →](../03-rag/README.md) +**Navigasi:** [← Sebelumnya: Modul 01 - Pendahuluan](../01-introduction/README.md) | [Kembali ke Utama](../README.md) | [Berikutnya: Modul 03 - RAG →](../03-rag/README.md) --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk memberikan terjemahan yang akurat, harap diperhatikan bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang berwenang. Untuk informasi yang sangat penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang salah yang timbul dari penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk mencapai akurasi, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/id/03-rag/README.md b/translations/id/03-rag/README.md index a314f918d..907c6263c 100644 --- a/translations/id/03-rag/README.md +++ b/translations/id/03-rag/README.md @@ -2,29 +2,29 @@ ## Daftar Isi -- [Video Walkthrough](../../../03-rag) -- [Apa yang Akan Anda Pelajari](../../../03-rag) -- [Prasyarat](../../../03-rag) -- [Memahami RAG](../../../03-rag) - - [Pendekatan RAG Mana yang Digunakan Tutorial Ini?](../../../03-rag) -- [Cara Kerjanya](../../../03-rag) - - [Pemrosesan Dokumen](../../../03-rag) - - [Membuat Embedding](../../../03-rag) - - [Pencarian Semantik](../../../03-rag) - - [Pembuatan Jawaban](../../../03-rag) -- [Menjalankan Aplikasi](../../../03-rag) -- [Menggunakan Aplikasi](../../../03-rag) - - [Mengunggah Dokumen](../../../03-rag) - - [Mengajukan Pertanyaan](../../../03-rag) - - [Memeriksa Referensi Sumber](../../../03-rag) - - [Bereksperimen dengan Pertanyaan](../../../03-rag) -- [Konsep Kunci](../../../03-rag) - - [Strategi Chunking](../../../03-rag) - - [Skor Kesamaan](../../../03-rag) - - [Penyimpanan Dalam Memori](../../../03-rag) - - [Manajemen Jendela Konteks](../../../03-rag) -- [Kapan RAG Penting](../../../03-rag) -- [Langkah Selanjutnya](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [Apa yang Akan Anda Pelajari](#apa-yang-akan-anda-pelajari) +- [Prasyarat](#prasyarat) +- [Memahami RAG](#memahami-rag) + - [Pendekatan RAG Mana yang Digunakan Tutorial Ini?](#pendekatan-rag-mana-yang-digunakan-tutorial-ini) +- [Cara Kerjanya](#cara-kerjanya) + - [Pemrosesan Dokumen](#pemrosesan-dokumen) + - [Membuat Embedding](#membuat-embedding) + - [Pencarian Semantik](#pencarian-semantik) + - [Pembuatan Jawaban](#pembuatan-jawaban) +- [Jalankan Aplikasi](#menjalankan-aplikasi) +- [Menggunakan Aplikasi](#menggunakan-aplikasi) + - [Unggah Dokumen](#unggah-dokumen) + - [Ajukan Pertanyaan](#ajukan-pertanyaan) + - [Periksa Referensi Sumber](#periksa-referensi-sumber) + - [Bereksperimen dengan Pertanyaan](#bereksperimen-dengan-pertanyaan) +- [Konsep Utama](#konsep-utama) + - [Strategi Pemotongan](#strategi-pemecahan-potongan) + - [Skor Kemiripan](#skor-kesamaan) + - [Penyimpanan dalam Memori](#penyimpanan-dalam-memori) + - [Manajemen Jendela Konteks](#manajemen-jendela-konteks) +- [Kapan RAG Penting](#kapan-rag-penting) +- [Langkah Berikutnya](#langkah-selanjutnya) ## Video Walkthrough @@ -34,107 +34,106 @@ Tonton sesi langsung ini yang menjelaskan cara memulai dengan modul ini: ## Apa yang Akan Anda Pelajari -Dalam modul sebelumnya, Anda belajar bagaimana melakukan percakapan dengan AI dan menyusun prompt secara efektif. Namun ada keterbatasan mendasar: model bahasa hanya tahu apa yang mereka pelajari selama pelatihan. Mereka tidak bisa menjawab pertanyaan tentang kebijakan perusahaan Anda, dokumentasi proyek Anda, atau informasi lain yang tidak mereka latih. +Dalam modul sebelumnya, Anda belajar bagaimana melakukan percakapan dengan AI dan menyusun prompt Anda secara efektif. Namun ada keterbatasan mendasar: model bahasa hanya tahu apa yang mereka pelajari selama pelatihan. Mereka tidak bisa menjawab pertanyaan tentang kebijakan perusahaan Anda, dokumentasi proyek Anda, atau informasi apa pun yang tidak mereka latih. -RAG (Retrieval-Augmented Generation) memecahkan masalah ini. Alih-alih mencoba mengajari model informasi Anda (yang mahal dan tidak praktis), Anda memberinya kemampuan untuk mencari dokumen Anda. Ketika seseorang mengajukan pertanyaan, sistem menemukan informasi relevan dan menyertakannya dalam prompt. Model kemudian menjawab berdasarkan konteks yang ditemukan tersebut. +RAG (Retrieval-Augmented Generation) memecahkan masalah ini. Alih-alih mencoba mengajarkan model informasi Anda (yang mahal dan tidak praktis), Anda memberinya kemampuan untuk mencari melalui dokumen Anda. Ketika seseorang mengajukan pertanyaan, sistem menemukan informasi yang relevan dan memasukkannya ke dalam prompt. Model kemudian menjawab berdasarkan konteks yang diambil tersebut. -Pikirkan RAG seperti memberikan pustaka referensi untuk model. Saat Anda bertanya, sistem melakukan: +Pikirkan RAG sebagai memberikan model sebuah perpustakaan referensi. Ketika Anda mengajukan pertanyaan, sistem: -1. **Kueri Pengguna** - Anda mengajukan pertanyaan +1. **Query Pengguna** - Anda mengajukan pertanyaan 2. **Embedding** - Mengubah pertanyaan Anda menjadi vektor -3. **Pencarian Vektor** - Menemukan potongan dokumen serupa -4. **Perakitan Konteks** - Menambahkan potongan relevan ke prompt -5. **Respons** - LLM menghasilkan jawaban berdasarkan konteks +3. **Pencarian Vektor** - Menemukan potongan dokumen yang mirip +4. **Perakitan Konteks** - Menambahkan potongan relevan ke dalam prompt +5. **Respons** - LLM menghasilkan jawaban berdasarkan konteks tersebut -Ini membuat tanggapan model berlandaskan data nyata Anda alih-alih hanya mengandalkan pengetahuan pelatihan atau mengarang jawaban. +Ini membuat jawaban model berlandaskan data nyata Anda, bukan hanya mengandalkan pengetahuan pelatihannya atau mengarang jawaban. ## Prasyarat -- Telah menyelesaikan [Modul 00 - Quick Start](../00-quick-start/README.md) (untuk contoh Easy RAG yang dirujuk di modul ini) -- Telah menyelesaikan [Modul 01 - Introduction](../01-introduction/README.md) (sumber daya Azure OpenAI sudah diterapkan, termasuk model embedding `text-embedding-3-small`) +- Telah menyelesaikan [Modul 01 - Pengantar](../01-introduction/README.md) (sumber daya Azure OpenAI telah dikerahkan, termasuk model embedding `text-embedding-3-small`) - File `.env` di direktori root dengan kredensial Azure (dibuat oleh `azd up` di Modul 01) -> **Catatan:** Jika Anda belum menyelesaikan Modul 01, ikuti dulu petunjuk penerapannya di sana. Perintah `azd up` menerapkan model chat GPT dan model embedding yang digunakan modul ini. +> **Catatan:** Jika Anda belum menyelesaikan Modul 01, ikuti petunjuk penyebaran di sana terlebih dahulu. Perintah `azd up` mengerahkan model GPT chat dan model embedding yang digunakan modul ini. ## Memahami RAG -Diagram di bawah menggambarkan konsep inti: alih-alih hanya mengandalkan data pelatihan model, RAG memberinya perpustakaan referensi dari dokumen Anda untuk dikonsultasikan sebelum menghasilkan setiap jawaban. +Diagram di bawah ini menggambarkan konsep inti: alih-alih hanya mengandalkan data pelatihan model, RAG memberinya perpustakaan referensi dokumen Anda untuk dikonsultasikan sebelum membuat setiap jawaban. Apa itu RAG -*Diagram ini menunjukkan perbedaan antara LLM standar (yang menebak dari data pelatihan) dan LLM yang ditingkatkan RAG (yang berkonsultasi dengan dokumen Anda terlebih dahulu).* +*Diagram ini menunjukkan perbedaan antara LLM standar (yang menebak dari data pelatihan) dan LLM yang diperkuat RAG (yang berkonsultasi dengan dokumen Anda terlebih dahulu).* -Berikut bagaimana bagian-bagian itu terhubung dari awal sampai akhir. Pertanyaan pengguna mengalir melalui empat tahap — embedding, pencarian vektor, perakitan konteks, dan pembuatan jawaban — yang masing-masing dibangun dari tahap sebelumnya: +Berikut bagaimana bagian-bagian tersebut terhubung end-to-end. Pertanyaan pengguna mengalir melalui empat tahap — embedding, pencarian vektor, perakitan konteks, dan pembuatan jawaban — masing-masing membangun dari tahap sebelumnya: Arsitektur RAG -*Diagram ini menunjukkan alur lengkap pipeline RAG — pertanyaan pengguna mengalir melalui embedding, pencarian vektor, perakitan konteks, dan pembuatan jawaban.* +*Diagram ini menunjukkan pipeline RAG end-to-end — query pengguna mengalir melalui embedding, pencarian vektor, perakitan konteks, dan pembuatan jawaban.* -Sisanya dari modul ini memandu tahap demi tahap secara rinci, dengan kode yang dapat Anda jalankan dan modifikasi. +Sisa modul ini menjelaskan setiap tahap secara detail, dengan kode yang dapat Anda jalankan dan modifikasi. ### Pendekatan RAG Mana yang Digunakan Tutorial Ini? -LangChain4j menawarkan tiga cara untuk mengimplementasikan RAG, masing-masing dengan tingkat abstraksi berbeda. Diagram berikut membandingkannya berdampingan: +LangChain4j menawarkan tiga cara mengimplementasikan RAG, masing-masing dengan tingkat abstraksi yang berbeda. Diagram di bawah membandingkan mereka berdampingan: Tiga Pendekatan RAG di LangChain4j -*Diagram ini membandingkan tiga pendekatan RAG LangChain4j — Easy, Native, dan Advanced — menunjukkan komponen utamanya dan kapan digunakan.* +*Diagram ini membandingkan tiga pendekatan LangChain4j RAG — Easy, Native, dan Advanced — menunjukkan komponen utama mereka dan kapan harus menggunakan masing-masing.* -| Pendekatan | Apa yang Dilakukan | Trade-off | +| Pendekatan | Fungsi | Perdagangan | |---|---|---| -| **Easy RAG** | Menghubungkan semuanya secara otomatis melalui `AiServices` dan `ContentRetriever`. Anda anotasi antarmuka, pasang retriever, dan LangChain4j mengatur embedding, pencarian, dan perakitan prompt secara tersembunyi. | Kode minimal, tapi Anda tidak melihat apa yang terjadi setiap tahap. | -| **Native RAG** | Anda memanggil model embedding, mencari ke dalam penyimpanan, membangun prompt, dan membuat jawaban sendiri — satu langkah eksplisit dalam satu waktu. | Lebih banyak kode, tapi setiap tahap terlihat dan dapat dimodifikasi. | -| **Advanced RAG** | Menggunakan framework `RetrievalAugmentor` dengan transformator kueri, router, re-ranker, dan injektor konten yang dapat dipasang untuk pipeline produksi. | Fleksibilitas maksimal, tapi jauh lebih kompleks. | +| **Easy RAG** | Menghubungkan semuanya secara otomatis lewat `AiServices` dan `ContentRetriever`. Anda hanya memberi anotasi pada interface, memasang retriever, dan LangChain4j mengelola embedding, pencarian, dan perakitan prompt di balik layar. | Kode minim, tapi Anda tidak melihat apa yang terjadi di tiap langkah. | +| **Native RAG** | Anda memanggil model embedding, mencari di penyimpanan, membangun prompt, dan menghasilkan jawaban sendiri — satu langkah eksplisit tiap waktu. | Lebih banyak kode, tapi setiap tahap terlihat dan bisa dimodifikasi. | +| **Advanced RAG** | Menggunakan framework `RetrievalAugmentor` dengan transformer query yang bisa disambungkan, router, re-ranker, dan injector konten untuk pipeline produksi. | Fleksibilitas maksimum, tapi jauh lebih kompleks. | -**Tutorial ini menggunakan pendekatan Native.** Setiap tahap pipeline RAG — embedding kueri, pencarian di vector store, penyusunan konteks, dan pembuatan jawaban — ditulis secara eksplisit dalam [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Ini disengaja: sebagai sumber belajar, lebih penting Anda melihat dan memahami setiap tahap dibandingkan kode yang dipersingkat. Setelah Anda nyaman dengan susunan bagian-bagiannya, Anda bisa beralih ke Easy RAG untuk prototipe cepat atau Advanced RAG untuk sistem produksi. +**Tutorial ini menggunakan pendekatan Native.** Setiap langkah pipeline RAG — embedding query, mencari di penyimpanan vektor, merakit konteks, dan membuat jawaban — dituliskan secara eksplisit di [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Ini disengaja: sebagai sumber belajar, lebih penting Anda melihat dan memahami setiap tahap daripada kode dipersingkat. Setelah Anda nyaman dengan bagaimana bagian-bagian berfungsi bersama, Anda bisa pindah ke Easy RAG untuk prototipe cepat atau Advanced RAG untuk sistem produksi. -> **💡 Sudah melihat Easy RAG berjalan?** Modul [Quick Start](../00-quick-start/README.md) mencakup contoh Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) yang menggunakan pendekatan Easy RAG — LangChain4j menangani embedding, pencarian, dan perakitan prompt secara otomatis. Modul ini mengambil langkah berikutnya dengan membuka pipeline tersebut agar Anda bisa melihat dan mengontrol setiap tahap secara sendiri. +> **💡 Ingin tahu tentang Easy RAG?** LangChain4j juga menyediakan pendekatan *Easy RAG* di mana `AiServices` dan `ContentRetriever` menangani embedding, pencarian, dan perakitan prompt otomatis. Modul ini mengambil jalur yang lebih eksplisit — membuka pipeline itu agar Anda bisa melihat dan mengontrol tiap tahap sendiri. -Diagram berikut menunjukkan pipeline Easy RAG dari contoh Quick Start itu. Perhatikan bagaimana `AiServices` dan `EmbeddingStoreContentRetriever` menyembunyikan semua kompleksitas — Anda memuat dokumen, memasang retriever, dan mendapat jawaban. Pendekatan Native di modul ini membuka setiap langkah tersembunyi tersebut: +Diagram di bawah mengilustrasikan pipeline Easy RAG. Perhatikan bagaimana `AiServices` dan `EmbeddingStoreContentRetriever` menyembunyikan seluruh kompleksitas — Anda memuat dokumen, memasang retriever, dan mendapatkan jawaban. Pendekatan Native dalam modul ini membuka tiap langkah tersembunyi tersebut: Pipeline Easy RAG - LangChain4j -*Diagram ini menunjukkan pipeline Easy RAG dari `SimpleReaderDemo.java`. Bandingkan dengan pendekatan Native yang digunakan modul ini: Easy RAG menyembunyikan embedding, pencarian, dan perakitan prompt di balik `AiServices` dan `ContentRetriever` — Anda memuat dokumen, memasang retriever, dan mendapat jawaban. Pendekatan Native membuka pipeline itu sehingga Anda memanggil setiap tahap (embed, cari, susun konteks, buat jawaban) sendiri, memberikan visibilitas dan kontrol penuh.* +*Diagram ini menunjukkan pipeline Easy RAG. Bandingkan dengan pendekatan Native yang digunakan modul ini: Easy RAG menyembunyikan embedding, pengambilan, dan perakitan prompt lewat `AiServices` dan `ContentRetriever` — Anda memuat dokumen, memasang retriever, dan mendapat jawaban. Pendekatan Native memecah pipeline itu sehingga Anda panggil tiap tahap (embed, search, assemble context, generate) sendiri, memberikan visibilitas dan kontrol penuh.* ## Cara Kerjanya -Pipeline RAG dalam modul ini terbagi menjadi empat tahap yang berjalan berurutan setiap kali pengguna mengajukan pertanyaan. Pertama, dokumen yang diunggah **diparsing dan dipecah menjadi potongan** yang mudah ditangani. Potongan-potongan tersebut kemudian dikonversi menjadi **embedding vektor** dan disimpan agar bisa dibandingkan secara matematika. Saat kueri datang, sistem melakukan **pencarian semantik** untuk menemukan potongan paling relevan, dan akhirnya melewatkannya sebagai konteks kepada LLM untuk **pembuatan jawaban**. Bagian-bagian berikut menjelaskan setiap tahap dengan kode dan diagram nyata. Mari lihat tahap pertama. +Pipeline RAG dalam modul ini terbagi menjadi empat tahap yang dijalankan berurutan setiap kali pengguna mengajukan pertanyaan. Pertama, dokumen yang diunggah **diparsing dan dipotong** menjadi bagian-bagian yang mudah dikelola. Potongan-potongan itu kemudian dikonversi menjadi **embedding vektor** dan disimpan agar bisa dibandingkan secara matematis. Ketika query datang, sistem melakukan **pencarian semantik** untuk menemukan potongan paling relevan, dan akhirnya melewatkannya sebagai konteks ke LLM untuk **pembuatan jawaban**. Bagian-bagian di bawah ini menjelaskan tiap tahap dengan kode dan diagram nyata. Mari kita lihat langkah pertama. ### Pemrosesan Dokumen [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Saat Anda mengunggah dokumen, sistem memparsingnya (PDF atau teks biasa), menambahkan metadata seperti nama file, lalu memecahnya menjadi potongan — bagian lebih kecil yang muat dengan nyaman dalam jendela konteks model. Potongan ini sedikit tumpang tindih agar konteks pada batas-batas tidak hilang. +Ketika Anda mengunggah dokumen, sistem memparsingnya (PDF atau teks biasa), menambahkan metadata seperti nama file, lalu memecahnya menjadi potongan—bagian kecil yang muat dengan nyaman di jendela konteks model. Potongan-potongan ini saling tumpang tindih sedikit sehingga konteks di batas potongan tidak hilang. ```java -// Mengurai file yang diunggah dan membungkusnya dalam Dokumen LangChain4j +// Parse file yang diunggah dan bungkus dalam Dokumen LangChain4j Document document = Document.from(content, metadata); -// Membagi menjadi potongan-potongan 300-token dengan tumpang tindih 30-token +// Pisahkan menjadi potongan 300-token dengan tumpang tindih 30-token DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Diagram di bawah menunjukkan bagaimana ini bekerja secara visual. Perhatikan bagaimana setiap potongan berbagi beberapa token dengan tetangganya — tumpang tindih 30 token memastikan tidak ada konteks penting yang terlewatkan: +Diagram di bawah menunjukkan cara kerjanya secara visual. Perhatikan bagaimana tiap potongan berbagi beberapa token dengan tetangganya — tumpang tindih 30 token menjamin tidak ada konteks penting yang hilang di antara celah-celah: -Pecah Dokumen menjadi Chunk +Pemotongan Dokumen -*Diagram ini menunjukkan dokumen dipecah menjadi potongan 300-token dengan tumpang tindih 30-token, menjaga konteks di batas potongan.* +*Diagram ini menunjukkan dokumen dipotong menjadi potongan 300 token dengan tumpang tindih 30 token, menjaga konteks di batas potongan.* -> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) dan tanyakan: -> - "Bagaimana LangChain4j memecah dokumen menjadi potongan dan mengapa tumpang tindih itu penting?" -> - "Berapa ukuran potongan optimal untuk berbagai jenis dokumen dan mengapa?" -> - "Bagaimana menangani dokumen dalam beberapa bahasa atau dengan format khusus?" +> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) dan tanya: +> - "Bagaimana LangChain4j memotong dokumen menjadi potongan dan mengapa tumpang tindih itu penting?" +> - "Berapa ukuran potongan optimal untuk berbagai tipe dokumen dan mengapa?" +> - "Bagaimana saya menangani dokumen berbahasa ganda atau dengan format khusus?" ### Membuat Embedding [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Setiap potongan dikonversi menjadi representasi numerik yang disebut embedding — pada dasarnya pengubah makna ke angka. Model embedding tidak "cerdas" seperti model chat; ia tidak bisa mengikuti instruksi, bernalar, atau menjawab pertanyaan. Yang bisa dilakukan adalah memetakan teks ke ruang matematis di mana makna serupa berdekatan — "mobil" dekat "automobile", "kebijakan pengembalian" dekat "pengembalian uang saya." Pikirkan model chat sebagai orang yang bisa diajak bicara; model embedding adalah sistem pengarsipan ultra-efisien. +Setiap potongan diubah menjadi representasi numerik yang disebut embedding—pada dasarnya pengubah makna menjadi angka. Model embedding tidak "cerdas" seperti model chat; ia tidak bisa mengikuti instruksi, bernalar, atau menjawab pertanyaan. Yang bisa ia lakukan adalah memetakan teks ke ruang matematis di mana makna serupa berdekatan — "mobil" dekat dengan "automobile," "kebijakan pengembalian dana" dekat dengan "kembalikan uang saya." Anggap model chat seperti seseorang yang bisa diajak bicara; model embedding adalah sistem pengarsipan yang sangat baik. -Diagram di bawah memvisualisasikan konsep ini — teks masuk, vektor numerik keluar, dan makna serupa menghasilkan vektor berdekatan: +Diagram di bawah memvisualisasikan konsep ini — teks masuk, vektor numerik keluar, dan makna serupa menghasilkan vektor yang berdekatan: Konsep Model Embedding @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Diagram kelas di bawah menunjukkan dua alur terpisah dalam pipeline RAG dan kelas LangChain4j yang mengimplementasikannya. **Alur ingestasi** (dijalankan sekali saat unggah) memecah dokumen, meng-embed potongan, dan menyimpannya lewat `.addAll()`. **Alur kueri** (dijalankan setiap kali pengguna bertanya) meng-embed pertanyaan, mencari di penyimpanan lewat `.search()`, dan melewatkan konteks yang cocok ke model chat. Kedua alur bertemu di interface `EmbeddingStore` bersama: +Diagram kelas di bawah menunjukkan dua aliran terpisah dalam pipeline RAG dan kelas LangChain4j yang mengimplementasikannya. Aliran **ingest** (dijalankan sekali saat upload) memecah dokumen, membangun embedding potongan, dan menyimpannya lewat `.addAll()`. Aliran **query** (dijalankan setiap kali pengguna bertanya) membangun embedding pertanyaan, mencari di store lewat `.search()`, dan melewatkan konteks yang cocok ke model chat. Kedua aliran bertemu di interface bersama `EmbeddingStore`: -Kelas RAG LangChain4j +Kelas LangChain4j RAG -*Diagram ini menunjukkan dua alur dalam pipeline RAG — ingestasi dan kueri — dan bagaimana mereka terhubung melalui EmbeddingStore bersama.* +*Diagram ini menunjukkan dua aliran dalam pipeline RAG — ingest dan query — dan bagaimana mereka terhubung melalui EmbeddingStore bersama.* -Setelah embedding disimpan, konten serupa secara alami mengelompok di ruang vektor. Visualisasi di bawah menunjukkan bagaimana dokumen terkait topik berakhir sebagai titik berdekatan, yang memungkinkan pencarian semantik: +Setelah embedding tersimpan, konten serupa secara alami mengelompok bersama dalam ruang vektor. Visualisasi di bawah menunjukkan dokumen tentang topik terkait menjadi titik-titik yang berdekatan, yang membuat pencarian semantik menjadi mungkin: Ruang Embedding Vektor -*Visualisasi ini menunjukkan bagaimana dokumen terkait mengelompok dalam ruang vektor 3D, dengan topik seperti Dokumen Teknis, Aturan Bisnis, dan FAQ membentuk kelompok berbeda.* +*Visualisasi ini menunjukkan bagaimana dokumen terkait mengelompok bersama dalam ruang vektor 3D, dengan topik seperti Dokumen Teknis, Aturan Bisnis, dan FAQ membentuk kelompok terpisah.* -Saat pengguna mencari, sistem mengikuti empat langkah: embedding dokumen sekali, embedding kueri setiap pencarian, membandingkan vektor kueri dengan semua vektor yang disimpan menggunakan kemiripan kosinus, dan mengembalikan potongan dengan skor teratas. Diagram berikut menjelaskan setiap langkah dan kelas LangChain4j yang terlibat: +Ketika pengguna melakukan pencarian, sistem mengikuti empat langkah: buat embedding dokumen sekali, buat embedding query untuk tiap pencarian, bandingkan vektor query terhadap semua vektor yang tersimpan menggunakan cosine similarity, dan kembalikan top-K potongan dengan skor tertinggi. Diagram di bawah menjelaskan tiap langkah dan kelas LangChain4j terkait: -Langkah-Langkah Pencarian Embedding +Langkah Pencarian Embedding -*Diagram ini menunjukkan proses pencarian embedding empat langkah: embed dokumen, embed kueri, bandingkan vektor dengan kemiripan kosinus, dan kembalikan hasil top-K.* +*Diagram ini menunjukkan proses pencarian embedding empat langkah: buat embedding dokumen, buat embedding query, bandingkan vektor dengan cosine similarity, dan kembalikan hasil top-K.* ### Pencarian Semantik [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Saat Anda mengajukan pertanyaan, pertanyaan Anda juga diubah menjadi embedding. Sistem membandingkan embedding pertanyaan Anda dengan embedding semua potongan dokumen. Ia menemukan potongan dengan makna paling mirip — bukan hanya kecocokan kata kunci, tapi kemiripan semantik aktual. +Ketika Anda mengajukan pertanyaan, pertanyaan Anda juga diubah menjadi embedding. Sistem membandingkan embedding pertanyaan Anda dengan embedding semua potongan dokumen. Ia menemukan potongan dengan makna paling mirip — bukan hanya mencocokkan kata kunci, tetapi kesamaan semantik sesungguhnya. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Diagram di bawah membandingkan pencarian semantik dengan pencarian kata kunci tradisional. Pencarian kata kunci untuk "kendaraan" melewatkan potongan tentang "mobil dan truk," tapi pencarian semantik memahami mereka bermakna sama dan mengembalikannya sebagai hasil dengan skor tinggi: +Diagram di bawah membandingkan pencarian semantik dengan pencarian kata kunci tradisional. Pencarian kata kunci untuk "kendaraan" melewatkan potongan tentang "mobil dan truk," tapi pencarian semantik memahami mereka berarti hal yang sama dan mengembalikannya sebagai kecocokan dengan skor tinggi: Pencarian Semantik -*Diagram ini membandingkan pencarian berbasis kata kunci dengan pencarian semantik, menunjukkan bagaimana pencarian semantik mengambil konten terkait konsep meskipun kata kunci tepat berbeda.* -Di balik layar, kesamaan diukur menggunakan cosine similarity — pada dasarnya menanyakan "apakah dua panah ini menunjuk ke arah yang sama?" Dua potongan bisa menggunakan kata-kata yang benar-benar berbeda, tetapi jika mereka bermakna sama maka vektor mereka menunjuk ke arah yang sama dan skor mendekati 1.0: +*Diagram ini membandingkan pencarian berbasis kata kunci dengan pencarian semantik, menunjukkan bagaimana pencarian semantik mengambil konten yang secara konseptual terkait walaupun kata kunci tepat berbeda.* -Kesamaan Cosine +Di belakang layar, kemiripan diukur menggunakan cosine similarity — pada dasarnya menanyakan "apakah dua panah ini menunjuk ke arah yang sama?" Dua potongan bisa menggunakan kata-kata yang sangat berbeda, tapi jika maknanya sama, vektor mereka menunjuk ke arah yang sama dan skornya mendekati 1.0: -*Diagram ini menggambarkan cosine similarity sebagai sudut antara vektor embedding — vektor yang lebih sejajar mendapat skor mendekati 1.0, yang menunjukkan kesamaan semantik yang lebih tinggi.* +Cosine Similarity +*Diagram ini menggambarkan kesamaan kosinus sebagai sudut antara vektor embedding — vektor yang lebih sejajar mendapatkan skor mendekati 1.0, yang menunjukkan kesamaan semantik yang lebih tinggi.* > **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) dan tanyakan: -> - "Bagaimana cara kerja pencarian kesamaan dengan embeddings dan apa yang menentukan skor?" -> - "Ambang batas kesamaan apa yang harus saya gunakan dan bagaimana pengaruhnya terhadap hasil?" -> - "Bagaimana saya menangani kasus di mana tidak ditemukan dokumen yang relevan?" +> - "Bagaimana pencarian kesamaan bekerja dengan embeddings dan apa yang menentukan skornya?" +> - "Ambang kesamaan berapa yang harus saya gunakan dan bagaimana pengaruhnya terhadap hasil?" +> - "Bagaimana saya menangani kasus ketika tidak ada dokumen relevan yang ditemukan?" -### Generasi Jawaban +### Pembuatan Jawaban [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Potongan paling relevan dirangkai menjadi prompt terstruktur yang mencakup instruksi eksplisit, konteks yang diambil, dan pertanyaan pengguna. Model membaca potongan spesifik tersebut dan menjawab berdasarkan informasi itu — model hanya dapat menggunakan apa yang ada di depannya, yang mencegah halusinasi. +Potongan paling relevan disusun menjadi sebuah prompt terstruktur yang mencakup instruksi eksplisit, konteks yang diambil, dan pertanyaan pengguna. Model membaca potongan-potongan tertentu tersebut dan menjawab berdasarkan informasi itu — model hanya dapat menggunakan apa yang ada di depannya, sehingga mencegah halusinasi. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Diagram di bawah menunjukkan perakitan ini dalam aksi — potongan dengan skor tertinggi dari langkah pencarian disisipkan ke dalam template prompt, dan `OpenAiOfficialChatModel` menghasilkan jawaban yang berdasar: +Diagram di bawah menunjukkan proses penyusunan ini — potongan dengan skor tertinggi dari langkah pencarian disuntikkan ke dalam template prompt, dan `OpenAiOfficialChatModel` menghasilkan jawaban yang berlandaskan: -Perakitan Konteks +Context Assembly -*Diagram ini menunjukkan bagaimana potongan dengan skor tertinggi dirangkai menjadi prompt terstruktur, memungkinkan model menghasilkan jawaban yang berdasar dari data Anda.* +*Diagram ini menunjukkan bagaimana potongan dengan skor tertinggi disusun menjadi prompt terstruktur, memungkinkan model menghasilkan jawaban yang berlandaskan data Anda.* ## Menjalankan Aplikasi -**Verifikasi deployment:** +**Verifikasi penerapan:** -Pastikan file `.env` ada di direktori root dengan kredensial Azure (dibuat selama Modul 01). Jalankan ini dari direktori modul (`03-rag/`): +Pastikan file `.env` ada di direktori root dengan kredensial Azure (dibuat saat Modul 01). Jalankan dari direktori modul (`03-rag/`): **Bash:** ```bash @@ -261,23 +260,23 @@ Get-Content ..\.env # Harus menampilkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Mulai aplikasi:** -> **Catatan:** Jika Anda sudah menjalankan semua aplikasi menggunakan `./start-all.sh` dari direktori root (seperti yang dijelaskan di Modul 01), modul ini sudah berjalan di port 8081. Anda dapat melewati perintah mulai di bawah dan langsung ke http://localhost:8081. +> **Catatan:** Jika Anda sudah memulai semua aplikasi menggunakan `./start-all.sh` dari direktori root (seperti dijelaskan di Modul 01), modul ini sudah berjalan di port 8081. Anda bisa melewati perintah mulai di bawah dan langsung ke http://localhost:8081. **Opsi 1: Menggunakan Spring Boot Dashboard (Disarankan untuk pengguna VS Code)** -Dev container menyertakan ekstensi Spring Boot Dashboard, yang menyediakan antarmuka visual untuk mengelola semua aplikasi Spring Boot. Anda dapat menemukannya di Activity Bar di sisi kiri VS Code (cari ikon Spring Boot). +Container dev menyertakan ekstensi Spring Boot Dashboard, yang menyediakan antarmuka visual untuk mengelola semua aplikasi Spring Boot. Anda dapat menemukannya di Bilah Aktivitas di sebelah kiri VS Code (cari ikon Spring Boot). Dari Spring Boot Dashboard, Anda dapat: - Melihat semua aplikasi Spring Boot yang tersedia di workspace -- Memulai/berhenti aplikasi dengan satu klik -- Melihat log aplikasi secara real time +- Memulai/menghentikan aplikasi dengan sekali klik +- Melihat log aplikasi secara real-time - Memantau status aplikasi Cukup klik tombol play di samping "rag" untuk memulai modul ini, atau mulai semua modul sekaligus. Spring Boot Dashboard -*Tangkapan layar ini menunjukkan Spring Boot Dashboard di VS Code, tempat Anda dapat memulai, menghentikan, dan memantau aplikasi secara visual.* +*Tangkapan layar ini menunjukkan Spring Boot Dashboard di VS Code, tempat Anda bisa memulai, menghentikan, dan memantau aplikasi secara visual.* **Opsi 2: Menggunakan skrip shell** @@ -295,7 +294,7 @@ cd .. # Dari direktori root .\start-all.ps1 ``` -Atau mulai hanya modul ini: +Atau hanya mulai modul ini: **Bash:** ```bash @@ -309,7 +308,7 @@ cd 03-rag .\start.ps1 ``` -Kedua skrip secara otomatis memuat variabel lingkungan dari file `.env` root dan akan membangun file JAR jika belum ada. +Kedua skrip secara otomatis memuat variabel lingkungan dari file `.env` root dan akan membangun JAR jika belum ada. > **Catatan:** Jika Anda lebih suka membangun semua modul secara manual sebelum memulai: > @@ -318,20 +317,20 @@ Kedua skrip secara otomatis memuat variabel lingkungan dari file `.env` root dan > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Buka http://localhost:8081 di browser Anda. +Buka http://localhost:8081 di peramban Anda. **Untuk menghentikan:** **Bash:** ```bash -./stop.sh # Modul ini saja +./stop.sh # Hanya modul ini # Atau cd .. && ./stop-all.sh # Semua modul ``` @@ -345,65 +344,65 @@ cd ..; .\stop-all.ps1 # Semua modul ## Menggunakan Aplikasi -Aplikasi menyediakan antarmuka web untuk mengunggah dokumen dan mengajukan pertanyaan. +Aplikasi menyediakan antarmuka web untuk unggah dokumen dan bertanya. -Antarmuka Aplikasi RAG +RAG Application Interface -*Tangkapan layar ini menunjukkan antarmuka aplikasi RAG di mana Anda mengunggah dokumen dan mengajukan pertanyaan.* +*Tangkapan layar ini menunjukkan antarmuka aplikasi RAG tempat Anda mengunggah dokumen dan mengajukan pertanyaan.* ### Unggah Dokumen -Mulailah dengan mengunggah dokumen — file TXT paling cocok untuk pengujian. `sample-document.txt` disediakan di direktori ini yang berisi informasi tentang fitur LangChain4j, implementasi RAG, dan praktik terbaik — sempurna untuk pengujian sistem. +Mulailah dengan mengunggah dokumen — file TXT paling ideal untuk pengujian. Sebuah `sample-document.txt` disediakan di direktori ini yang memuat informasi tentang fitur LangChain4j, implementasi RAG, dan praktik terbaik — sangat cocok untuk menguji sistem. -Sistem memproses dokumen Anda, memecahnya menjadi potongan-potongan, dan membuat embedding untuk setiap potongan. Ini terjadi secara otomatis saat Anda mengunggah. +Sistem memproses dokumen Anda, memecahnya menjadi potongan-potongan, dan membuat embeddings untuk setiap potongan. Ini terjadi otomatis saat Anda unggah. ### Ajukan Pertanyaan -Sekarang ajukan pertanyaan spesifik tentang isi dokumen. Cobalah sesuatu yang faktual dan jelas tercantum dalam dokumen. Sistem mencari potongan relevan, menyertakannya dalam prompt, dan menghasilkan jawaban. +Sekarang ajukan pertanyaan spesifik tentang konten dokumen. Cobalah sesuatu yang faktual dan jelas disebutkan dalam dokumen. Sistem mencari potongan relevan, memasukkannya ke dalam prompt, dan menghasilkan jawaban. ### Periksa Referensi Sumber -Perhatikan setiap jawaban menyertakan referensi sumber dengan skor kesamaan. Skor ini (0 sampai 1) menunjukkan seberapa relevan setiap potongan terhadap pertanyaan Anda. Skor lebih tinggi berarti kecocokan yang lebih baik. Ini memungkinkan Anda memverifikasi jawaban terhadap bahan sumber. +Perhatikan setiap jawaban menyertakan referensi sumber dengan skor kesamaan. Skor ini (0 sampai 1) menunjukkan tingkat relevansi potongan terhadap pertanyaan Anda. Skor lebih tinggi berarti kecocokan lebih baik. Ini memungkinkan Anda memverifikasi jawaban sesuai sumber aslinya. -Hasil Query RAG +RAG Query Results *Tangkapan layar ini menunjukkan hasil query dengan jawaban yang dihasilkan, referensi sumber, dan skor relevansi untuk setiap potongan yang diambil.* ### Bereksperimen dengan Pertanyaan -Coba jenis pertanyaan berbeda: +Coba berbagai jenis pertanyaan: - Fakta spesifik: "Apa topik utama?" -- Perbandingan: "Apa perbedaan antara X dan Y?" -- Ringkasan: "Ringkas poin penting tentang Z" +- Perbandingan: "Apa beda antara X dan Y?" +- Ringkasan: "Ringkas poin-poin kunci tentang Z" -Perhatikan bagaimana skor relevansi berubah berdasarkan seberapa baik pertanyaan Anda cocok dengan isi dokumen. +Perhatikan bagaimana skor relevansi berubah berdasarkan seberapa baik pertanyaan Anda cocok dengan konten dokumen. -## Konsep Kunci +## Konsep Utama -### Strategi Chunking +### Strategi Pemecahan Potongan -Dokumen dibagi menjadi potongan 300 token dengan tumpang tindih 30 token. Keseimbangan ini memastikan setiap potongan memiliki konteks cukup untuk bermakna sambil tetap kecil agar beberapa potongan bisa dimasukkan ke dalam prompt. +Dokumen dibagi menjadi potongan 300 token dengan tumpang tindih 30 token. Keseimbangan ini memastikan setiap potongan memiliki cukup konteks untuk bermakna sambil tetap cukup kecil agar bisa menyertakan beberapa potongan dalam sebuah prompt. ### Skor Kesamaan -Setiap potongan yang diambil disertai skor kesamaan antara 0 dan 1 yang menunjukkan seberapa dekat kecocokannya dengan pertanyaan pengguna. Diagram di bawah memvisualisasikan rentang skor dan bagaimana sistem menggunakannya untuk menyaring hasil: +Setiap potongan yang diambil disertai dengan skor kesamaan antara 0 dan 1 yang menunjukkan seberapa dekat kecocokannya dengan pertanyaan pengguna. Diagram di bawah memvisualisasikan rentang skor dan bagaimana sistem menggunakannya untuk menyaring hasil: -Skor Kesamaan +Similarity Scores -*Diagram ini menunjukkan rentang skor dari 0 sampai 1, dengan ambang minimum 0.5 yang menyaring potongan tidak relevan.* +*Diagram ini menunjukkan rentang skor dari 0 sampai 1, dengan ambang minimum 0,5 yang menyaring potongan yang tidak relevan.* -Skor berkisar dari 0 sampai 1: -- 0.7-1.0: Sangat relevan, cocok persis -- 0.5-0.7: Relevan, konteks baik -- Di bawah 0.5: Disaring, terlalu tidak mirip +Skor berkisar antara 0 sampai 1: +- 0,7-1,0: Sangat relevan, cocok tepat +- 0,5-0,7: Relevan, konteks baik +- Di bawah 0,5: Disaring, terlalu tidak mirip -Sistem hanya mengambil potongan di atas ambang minimum untuk memastikan kualitas. +Sistem hanya mengambil potongan di atas ambang minimum untuk menjamin kualitas. -Embedding bekerja baik saat makna mengelompok dengan jelas, tetapi memiliki titik buta. Diagram di bawah menggambarkan mode kegagalan umum — potongan terlalu besar menghasilkan vektor kabur, potongan terlalu kecil kurang konteks, istilah ambigu menunjuk ke beberapa klaster, dan pencocokan persis (ID, nomor bagian) sama sekali tidak bekerja dengan embedding: +Embedding bekerja baik saat makna terklaster secara bersih, tetapi memiliki titik buta. Diagram di bawah menunjukkan mode kegagalan umum — potongan terlalu besar menghasilkan vektor yang kabur, potongan terlalu kecil kurang konteks, istilah ambigu menunjuk ke beberapa klaster, dan pencarian cocok tepat (ID, nomor bagian) sama sekali tidak berfungsi dengan embedding: -Mode Kegagalan Embedding +Embedding Failure Modes -*Diagram ini menunjukkan mode kegagalan embedding umum: potongan terlalu besar, potongan terlalu kecil, istilah ambigu yang menunjuk ke beberapa klaster, dan pencarian kecocokan persis seperti ID.* +*Diagram ini menunjukkan mode kegagalan embedding yang umum: potongan terlalu besar, potongan terlalu kecil, istilah ambigu yang menunjuk ke beberapa klaster, dan pencarian cocok tepat seperti ID.* ### Penyimpanan Dalam Memori @@ -411,19 +410,19 @@ Modul ini menggunakan penyimpanan dalam memori untuk kesederhanaan. Ketika Anda ### Manajemen Jendela Konteks -Setiap model memiliki jendela konteks maksimum. Anda tidak bisa memasukkan semua potongan dari dokumen besar. Sistem mengambil N potongan paling relevan terbanyak (default 5) agar tetap dalam batas sambil menyediakan cukup konteks untuk jawaban akurat. +Setiap model memiliki jendela konteks maksimum. Anda tidak bisa menyertakan semua potongan dari dokumen besar. Sistem mengambil N potongan paling relevan teratas (default 5) agar tetap dalam batas sambil menyediakan konteks cukup untuk jawaban akurat. ## Kapan RAG Penting -RAG tidak selalu menjadi pendekatan yang tepat. Panduan keputusan di bawah membantu Anda menentukan kapan RAG menambah nilai dibandingkan kapan pendekatan lebih sederhana — seperti menyertakan konten langsung dalam prompt atau mengandalkan pengetahuan bawaan model — sudah cukup: +RAG tidak selalu menjadi pendekatan yang tepat. Panduan keputusan di bawah membantu Anda menentukan kapan RAG memberikan nilai tambah dibandingkan pendekatan yang lebih sederhana — seperti memasukkan konten langsung ke prompt atau mengandalkan pengetahuan bawaan model: -Kapan Menggunakan RAG +When to Use RAG -*Diagram ini menunjukkan panduan keputusan kapan RAG menambah nilai versus kapan pendekatan lebih sederhana sudah memadai.* +*Diagram ini menunjukkan panduan keputusan kapan RAG memberikan nilai tambah dan kapan pendekatan sederhana sudah cukup.* ## Langkah Selanjutnya -**Modul Berikutnya:** [04-tools - Agen AI dengan Tools](../04-tools/README.md) +**Modul Berikutnya:** [04-tools - Agen AI dengan Alat](../04-tools/README.md) --- @@ -432,6 +431,6 @@ RAG tidak selalu menjadi pendekatan yang tepat. Panduan keputusan di bawah memba --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya mencapai ketepatan, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sahih. Untuk informasi penting, disarankan menggunakan terjemahan manusia profesional. Kami tidak bertanggung jawab atas kesalahpahaman atau salah interpretasi yang timbul dari penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk mencapai akurasi, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/id/04-tools/README.md b/translations/id/04-tools/README.md index 93ec2dee9..67062321c 100644 --- a/translations/id/04-tools/README.md +++ b/translations/id/04-tools/README.md @@ -2,75 +2,75 @@ ## Daftar Isi -- [Video Walkthrough](../../../04-tools) -- [Apa yang Akan Anda Pelajari](../../../04-tools) -- [Prasyarat](../../../04-tools) -- [Memahami Agen AI dengan Alat](../../../04-tools) -- [Cara Kerja Pemanggilan Alat](../../../04-tools) - - [Definisi Alat](../../../04-tools) - - [Pengambilan Keputusan](../../../04-tools) - - [Eksekusi](../../../04-tools) - - [Pembuatan Respons](../../../04-tools) - - [Arsitektur: Spring Boot Auto-Wiring](../../../04-tools) -- [Merangkai Alat](../../../04-tools) -- [Menjalankan Aplikasi](../../../04-tools) -- [Menggunakan Aplikasi](../../../04-tools) - - [Mencoba Penggunaan Alat Sederhana](../../../04-tools) - - [Menguji Merangkai Alat](../../../04-tools) - - [Melihat Alur Percakapan](../../../04-tools) - - [Bereksperimen dengan Permintaan Berbeda](../../../04-tools) -- [Konsep Kunci](../../../04-tools) - - [Pola ReAct (Reasoning and Acting)](../../../04-tools) - - [Deskripsi Alat itu Penting](../../../04-tools) - - [Manajemen Sesi](../../../04-tools) - - [Penanganan Kesalahan](../../../04-tools) -- [Alat yang Tersedia](../../../04-tools) -- [Kapan Menggunakan Agen Berbasis Alat](../../../04-tools) -- [Alat vs RAG](../../../04-tools) -- [Langkah Berikutnya](../../../04-tools) - -## Video Walkthrough +- [Video Penjelasan](#video-penjelasan) +- [Apa yang Akan Anda Pelajari](#apa-yang-akan-anda-pelajari) +- [Prasyarat](#prasyarat) +- [Memahami Agen AI dengan Alat](#memahami-agen-ai-dengan-alat) +- [Cara Kerja Pemanggilan Alat](#cara-kerja-pemanggilan-alat) + - [Definisi Alat](#definisi-alat) + - [Pengambilan Keputusan](#pengambilan-keputusan) + - [Eksekusi](#eksekusi) + - [Pembuatan Respons](#pembuatan-respons) + - [Arsitektur: Spring Boot Auto-Wiring](#arsitektur-spring-boot-auto-wiring) +- [Rangkaian Alat](#rangkaian-alat) +- [Jalankan Aplikasi](#jalankan-aplikasi) +- [Menggunakan Aplikasi](#menggunakan-aplikasi) + - [Coba Penggunaan Alat Sederhana](#coba-penggunaan-alat-sederhana) + - [Uji Rangkaian Alat](#uji-rangkaian-alat) + - [Lihat Alur Percakapan](#lihat-alur-percakapan) + - [Eksperimen dengan Permintaan Berbeda](#eksperimen-dengan-permintaan-berbeda) +- [Konsep Kunci](#konsep-kunci) + - [Pola ReAct (Reasoning and Acting)](#pola-react-penalaran-dan-bertindak) + - [Deskripsi Alat itu Penting](#deskripsi-alat-penting) + - [Manajemen Sesi](#manajemen-sesi) + - [Penanganan Kesalahan](#penanganan-error) +- [Alat yang Tersedia](#alat-yang-tersedia) +- [Kapan Menggunakan Agen Berbasis Alat](#kapan-menggunakan-agen-berbasis-alat) +- [Alat vs RAG](#alat-vs-rag) +- [Langkah Berikutnya](#langkah-berikutnya) + +## Video Penjelasan Tonton sesi langsung ini yang menjelaskan cara memulai dengan modul ini: -AI Agents with Tools and MCP - Live Session +Agen AI dengan Alat dan MCP - Sesi Langsung ## Apa yang Akan Anda Pelajari -Sejauh ini, Anda sudah belajar bagaimana berinteraksi dengan AI, menyusun prompt secara efektif, dan memberikan dasar jawaban dari dokumen Anda. Namun ada keterbatasan mendasar: model bahasa hanya dapat menghasilkan teks. Model tidak bisa memeriksa cuaca, melakukan perhitungan, mengakses database, atau berinteraksi dengan sistem eksternal. +Sampai saat ini, Anda telah belajar cara berkomunikasi dengan AI, menyusun prompt secara efektif, dan menghubungkan respons dengan dokumen Anda. Namun masih ada keterbatasan mendasar: model bahasa hanya dapat menghasilkan teks. Mereka tidak dapat memeriksa cuaca, melakukan perhitungan, mengquery basis data, atau berinteraksi dengan sistem eksternal. -Alat mengubah hal ini. Dengan memberi model akses ke fungsi yang dapat dipanggil, Anda mengubahnya dari generator teks menjadi agen yang dapat mengambil tindakan. Model memutuskan kapan membutuhkan alat, alat mana yang dipakai, dan parameter apa yang dikirim. Kode Anda mengeksekusi fungsi dan mengembalikan hasilnya. Model menggabungkan hasil tersebut ke dalam responsnya. +Alat mengubah ini. Dengan memberikan model akses ke fungsi yang dapat dipanggilnya, Anda mengubahnya dari generator teks menjadi agen yang dapat melakukan tindakan. Model memutuskan kapan membutuhkan alat, alat mana yang digunakan, dan parameter apa yang diberikan. Kode Anda mengeksekusi fungsi tersebut dan mengembalikan hasilnya. Model menggabungkan hasil tersebut ke dalam responsnya. ## Prasyarat -- Telah menyelesaikan [Modul 01 - Pengantar](../01-introduction/README.md) (sumber daya Azure OpenAI sudah dipasang) -- Disarankan menyelesaikan modul sebelumnya (modul ini merujuk pada [konsep RAG dari Modul 03](../03-rag/README.md) dalam perbandingan Alat vs RAG) -- File `.env` di direktori root berisi kredensial Azure (dibuat oleh `azd up` di Modul 01) +- Menyelesaikan [Modul 01 - Pengenalan](../01-introduction/README.md) (sumber daya Azure OpenAI sudah diterapkan) +- Disarankan telah menyelesaikan modul sebelumnya (modul ini mengacu pada [konsep RAG dari Modul 03](../03-rag/README.md) dalam perbandingan Alat vs RAG) +- File `.env` di direktori root dengan kredensial Azure (dibuat oleh `azd up` di Modul 01) -> **Catatan:** Jika Anda belum menyelesaikan Modul 01, ikuti instruksi pemasangan di sana terlebih dahulu. +> **Catatan:** Jika Anda belum menyelesaikan Modul 01, ikuti instruksi penerapan di sana terlebih dahulu. ## Memahami Agen AI dengan Alat -> **📝 Catatan:** Istilah "agen" di modul ini merujuk pada asisten AI yang diperkaya dengan kemampuan pemanggilan alat. Ini berbeda dengan pola **Agentic AI** (agen otonom dengan perencanaan, memori, dan penalaran bertahap) yang akan kita bahas di [Modul 05: MCP](../05-mcp/README.md). +> **📝 Catatan:** Istilah "agen" dalam modul ini merujuk pada asisten AI yang ditingkatkan dengan kemampuan pemanggilan alat. Ini berbeda dengan pola **Agentic AI** (agen otonom dengan perencanaan, memori, dan penalaran multi-langkah) yang akan kami bahas di [Modul 05: MCP](../05-mcp/README.md). -Tanpa alat, model bahasa hanya bisa menghasilkan teks berdasarkan data pelatihannya. Tanya cuaca saat ini, ia hanya menebak. Beri alat, model bisa memanggil API cuaca, melakukan perhitungan, atau mengakses database — lalu menggabungkan hasil nyata itu ke responsnya. +Tanpa alat, model bahasa hanya dapat menghasilkan teks dari data pelatihannya. Tanyakan tentang cuaca terkini, dan dia harus menebak. Berikan alat, dan model dapat memanggil API cuaca, melakukan perhitungan, atau mengquery basis data — lalu memasukkan hasil nyata itu ke dalam responsnya. -Without Tools vs With Tools +Tanpa Alat vs Dengan Alat -*Tanpa alat model hanya bisa menebak — dengan alat ia dapat memanggil API, melakukan perhitungan, dan mengembalikan data waktu nyata.* +*Tanpa alat model hanya bisa menebak — dengan alat model dapat memanggil API, melakukan perhitungan, dan mengembalikan data waktu nyata.* -Agen AI dengan alat mengikuti pola **Reasoning and Acting (ReAct)**. Model tidak hanya merespons — ia berpikir tentang apa yang dibutuhkan, bertindak dengan memanggil alat, mengamati hasil, lalu memutuskan apakah bertindak lagi atau memberikan jawaban akhir: +Agen AI dengan alat mengikuti pola **Reasoning and Acting (ReAct)**. Model tidak hanya merespons — ia berpikir tentang apa yang dibutuhkannya, bertindak dengan memanggil alat, mengamati hasilnya, lalu memutuskan apakah perlu bertindak lagi atau memberikan jawaban akhir: -1. **Reason** — Agen menganalisis pertanyaan pengguna dan menentukan informasi yang diperlukan +1. **Reason** — Agen menganalisis pertanyaan pengguna dan menentukan informasi yang dibutuhkan 2. **Act** — Agen memilih alat yang tepat, menghasilkan parameter yang benar, dan memanggilnya -3. **Observe** — Agen menerima output alat dan mengevaluasi hasilnya -4. **Repeat or Respond** — Jika perlu data tambahan, agen mengulang; jika tidak, menyusun jawaban dalam bahasa alami +3. **Observe** — Agen menerima keluaran alat dan mengevaluasi hasilnya +4. **Repeat or Respond** — Jika data lebih dibutuhkan, agen mengulangi; jika tidak, menyusun jawaban dalam bahasa alami -ReAct Pattern +Pola ReAct -*Siklus ReAct — agen menganalisis aksi yang harus dilakukan, bertindak dengan memanggil alat, mengamati hasil, dan mengulangi hingga dapat memberikan jawaban akhir.* +*Siklus ReAct — agen berpikir tentang apa yang harus dilakukan, bertindak dengan memanggil alat, mengamati hasilnya, dan mengulangi sampai dapat memberikan jawaban akhir.* -Ini terjadi secara otomatis. Anda mendefinisikan alat dan deskripsinya. Model menangani pengambilan keputusan kapan dan bagaimana menggunakannya. +Ini terjadi secara otomatis. Anda mendefinisikan alat dan deskripsinya. Model yang menangani pengambilan keputusan tentang kapan dan bagaimana menggunakannya. ## Cara Kerja Pemanggilan Alat @@ -78,7 +78,7 @@ Ini terjadi secara otomatis. Anda mendefinisikan alat dan deskripsinya. Model me [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Anda mendefinisikan fungsi dengan deskripsi yang jelas dan spesifikasi parameter. Model melihat deskripsi ini dalam prompt sistem dan memahami fungsi masing-masing alat. +Anda mendefinisikan fungsi dengan deskripsi jelas dan spesifikasi parameter. Model melihat deskripsi ini dalam sistem prompt-nya dan mengerti apa fungsi tiap alat. ```java @Component @@ -96,135 +96,135 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Asisten secara otomatis dihubungkan oleh Spring Boot dengan: +// Asisten secara otomatis terhubung oleh Spring Boot dengan: // - Bean ChatModel // - Semua metode @Tool dari kelas @Component // - ChatMemoryProvider untuk manajemen sesi ``` + +Diagram di bawah ini memecah setiap anotasi dan menunjukkan bagaimana setiap bagian membantu AI memahami kapan memanggil alat dan argumen apa yang harus dikirim: -Diagram berikut memecah setiap anotasi dan menunjukkan bagaimana setiap bagian membantu AI memahami kapan memanggil alat dan argumen apa yang diberikan: +Anatomi Definisi Alat -Anatomy of Tool Definitions +*Anatomi definisi alat — @Tool memberitahu AI kapan menggunakannya, @P mendeskripsikan tiap parameter, dan @AiService menghubungkan semuanya saat startup.* -*Anatomi definisi alat — @Tool memberi tahu AI kapan menggunakannya, @P mendeskripsikan setiap parameter, dan @AiService menghubungkan semuanya saat startup.* - -> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) dan tanyakan: -> - "Bagaimana saya mengintegrasikan API cuaca nyata seperti OpenWeatherMap menggantikan data tiruan?" -> - "Apa yang membuat deskripsi alat bagus sehingga membantu AI menggunakannya dengan benar?" -> - "Bagaimana menangani kesalahan API dan batasan rate dalam implementasi alat?" +> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) dan tanyakan: +> - "Bagaimana saya mengintegrasikan API cuaca nyata seperti OpenWeatherMap alih-alih data tiruan?" +> - "Apa yang membuat deskripsi alat yang bagus agar AI menggunakannya dengan benar?" +> - "Bagaimana menangani kesalahan API dan batas panggilan dalam implementasi alat?" ### Pengambilan Keputusan -Saat pengguna bertanya "Bagaimana cuaca di Seattle?", model tidak memilih alat secara acak. Ia membandingkan maksud pengguna dengan setiap deskripsi alat yang tersedia, memberi nilai relevansi, dan memilih yang paling cocok. Kemudian ia menghasilkan panggilan fungsi terstruktur dengan parameter yang tepat — dalam contoh ini, mengatur `location` ke `"Seattle"`. +Ketika pengguna bertanya "Bagaimana cuaca di Seattle?", model tidak memilih alat secara acak. Ia membandingkan niat pengguna dengan setiap deskripsi alat yang tersedia, memberikan skor relevansi, lalu memilih yang paling sesuai. Model kemudian membuat panggilan fungsi terstruktur dengan parameter yang benar — dalam kasus ini, mengatur `location` ke `"Seattle"`. -Jika tidak ada alat yang cocok dengan permintaan pengguna, model kembali menjawab dari pengetahuannya sendiri. Jika ada beberapa alat cocok, model memilih yang paling spesifik. +Jika tidak ada alat yang cocok dengan permintaan pengguna, model kembali menjawab berdasarkan pengetahuannya sendiri. Jika ada beberapa alat yang cocok, ia memilih yang paling spesifik. -How the AI Decides Which Tool to Use +Bagaimana AI Memutuskan Menggunakan Alat -*Model mengevaluasi semua alat tersedia terhadap maksud pengguna dan memilih yang paling cocok — ini sebabnya menulis deskripsi alat yang jelas dan spesifik sangat penting.* +*Model mengevaluasi setiap alat yang tersedia terhadap niat pengguna dan memilih yang paling tepat — ini sebabnya menulis deskripsi alat yang jelas dan spesifik penting.* ### Eksekusi [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot secara otomatis mengalirkan interface deklaratif `@AiService` dengan semua alat terdaftar, dan LangChain4j mengeksekusi panggilan alat secara otomatis. Di balik layar, panggilan alat lengkap berjalan melalui enam tahap — dari pertanyaan bahasa alami pengguna sampai jawaban bahasa alami kembali: +Spring Boot secara otomatis menghubungkan interface deklaratif `@AiService` dengan semua alat yang terdaftar, dan LangChain4j mengeksekusi panggilan alat secara otomatis. Di balik layar, panggilan alat lengkap melalui enam tahap — dari pertanyaan bahasa alami pengguna hingga jawaban dalam bahasa alami kembali: -Tool Calling Flow +Alur Pemanggilan Alat -*Alur lengkap — pengguna mengajukan pertanyaan, model memilih alat, LangChain4j mengeksekusi alat, dan model menggabungkan hasilnya ke respons alami.* +*Alur ujung ke ujung — pengguna menanyakan pertanyaan, model memilih alat, LangChain4j mengeksekusi, dan model menggabungkan hasilnya menjadi respons alami.* -Jika Anda menjalankan [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) di Modul 00, Anda sudah melihat pola ini beraksi — alat `Calculator` juga dipanggil dengan cara yang sama. Diagram urutan di bawah menunjukkan persis apa yang terjadi di balik layar selama demo: +Di balik layar, `AiServices` menjalankan loop pemanggilan alat yang sama untuk alat apa pun — di sini digambarkan dengan kalkulator sederhana. Diagram urutan di bawah menunjukkan persis apa yang terjadi: -Tool Calling Sequence Diagram +Diagram Urutan Pemanggilan Alat -*Loop pemanggilan alat dari demo Quick Start — `AiServices` mengirimkan pesan dan skema alat ke LLM, LLM membalas dengan panggilan fungsi seperti `add(42, 58)`, LangChain4j mengeksekusi metode `Calculator` secara lokal, dan mengembalikan hasil untuk jawaban akhir.* +*Loop pemanggilan alat — `AiServices` mengirim pesan dan skema alat ke LLM, LLM membalas dengan panggilan fungsi seperti `add(42, 58)`, LangChain4j mengeksekusi metode `Calculator` secara lokal, dan memberikan hasil kembali untuk jawaban akhir.* -> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) dan tanyakan: -> - "Bagaimana pola ReAct bekerja dan mengapa efektif untuk agen AI?" -> - "Bagaimana agen memutuskan alat mana yang digunakan dan dalam urutan apa?" -> - "Apa yang terjadi jika eksekusi alat gagal - bagaimana menangani kesalahan dengan baik?" +> **🤖 Coba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) dan tanyakan: +> - "Bagaimana pola ReAct bekerja dan mengapa efektif untuk agen AI?" +> - "Bagaimana agen memutuskan alat mana yang digunakan dan dalam urutan apa?" +> - "Apa yang terjadi jika eksekusi alat gagal - bagaimana cara menangani kesalahan dengan kuat?" ### Pembuatan Respons -Model menerima data cuaca dan memformatnya menjadi respons bahasa alami untuk pengguna. +Model menerima data cuaca dan memformatnya menjadi jawaban bahasa alami untuk pengguna. ### Arsitektur: Spring Boot Auto-Wiring -Modul ini menggunakan integrasi LangChain4j dengan Spring Boot melalui interface deklaratif `@AiService`. Saat startup, Spring Boot menemukan setiap `@Component` yang memiliki metode `@Tool`, bean `ChatModel`, dan `ChatMemoryProvider` — lalu mengalirkan semuanya ke satu interface `Assistant` tanpa kode boilerplate. +Modul ini menggunakan integrasi Spring Boot LangChain4j dengan interface deklaratif `@AiService`. Saat startup, Spring Boot menemukan setiap `@Component` yang berisi metode `@Tool`, bean `ChatModel` Anda, dan `ChatMemoryProvider` — lalu menghubungkan semuanya menjadi interface `Assistant` tunggal tanpa kode boilerplate. -Spring Boot Auto-Wiring Architecture +Arsitektur Spring Boot Auto-Wiring -*Interface @AiService menggabungkan ChatModel, komponen alat, dan penyedia memori — Spring Boot menangani pengaliran otomatis.* +*Interface @AiService mengikat ChatModel, komponen alat, dan penyedia memori — Spring Boot menangani penghubungan semuanya secara otomatis.* -Berikut siklus lengkap permintaan sebagai diagram urutan — dari permintaan HTTP lewat controller, service, proxy auto-wired, sampai eksekusi alat dan kembali: +Berikut siklus hidup permintaan lengkap dalam diagram urutan — dari permintaan HTTP melalui controller, service, dan proxy auto-wired, sampai eksekusi alat dan kembali: -Spring Boot Tool Calling Sequence +Diagram Urutan Pemanggilan Alat Spring Boot -*Siklus lengkap permintaan Spring Boot — permintaan HTTP mengalir melalui controller dan service ke proxy Assistant auto-wired, yang mengorkestrasi LLM dan pemanggilan alat secara otomatis.* +*Siklus hidup permintaan Spring Boot lengkap — permintaan HTTP mengalir melalui controller dan service ke proxy Assistant auto-wired, yang mengorkestrasi LLM dan pemanggilan alat secara otomatis.* Manfaat utama pendekatan ini: -- **Spring Boot auto-wiring** — ChatModel dan alat otomatis dimasukkan -- **Pola @MemoryId** — Manajemen memori berbasis sesi otomatis -- **Satu instance** — Assistant dibuat sekali dan dipakai ulang untuk kinerja lebih baik -- **Eksekusi tipe aman** — Metode Java dipanggil langsung dengan konversi tipe -- **Orkestrasi multi-putaran** — Menangani perangkainan alat secara otomatis -- **Tanpa boilerplate** — Tidak perlu panggilan manual `AiServices.builder()` atau HashMap memori +- **Spring Boot auto-wiring** — ChatModel dan alat disuntikkan otomatis +- **Pola @MemoryId** — Manajemen memori berbasis sesi otomatis +- **Instansi tunggal** — Assistant dibuat sekali dan digunakan ulang untuk performa baik +- **Eksekusi tipe-safenya** — Metode Java dipanggil langsung dengan konversi tipe +- **Orkestrasi multi-langkah** — Menangani rangkaian alat secara otomatis +- **Nol boilerplate** — Tanpa panggilan manual `AiServices.builder()` atau HashMap memori -Pendekatan alternatif (manual `AiServices.builder()`) membutuhkan kode lebih banyak dan kehilangan manfaat integrasi Spring Boot. +Pendekatan alternatif (manual `AiServices.builder()`) memerlukan kode lebih banyak dan kehilangan manfaat integrasi Spring Boot. -## Merangkai Alat +## Rangkaian Alat -**Merangkai Alat** — Kekuatan sesungguhnya agen berbasis alat terlihat saat satu pertanyaan memerlukan beberapa alat. Tanya "Bagaimana cuaca di Seattle dalam Fahrenheit?" dan agen secara otomatis menggabungkan dua alat: pertama memanggil `getCurrentWeather` untuk suhu dalam Celsius, lalu meneruskan hasil itu ke `celsiusToFahrenheit` untuk konversi — semua dalam satu langkah percakapan. +**Rangkaian Alat** — Kekuatan sebenarnya dari agen berbasis alat terlihat saat satu pertanyaan memerlukan banyak alat. Tanyakan "Bagaimana cuaca di Seattle dalam Fahrenheit?" dan agen secara otomatis menghubungkan dua alat: pertama memanggil `getCurrentWeather` untuk mendapatkan suhu dalam Celsius, kemudian meneruskan nilai itu ke `celsiusToFahrenheit` untuk konversi — semua dalam satu putaran percakapan. -Tool Chaining Example +Contoh Rangkaian Alat -*Merangkai alat sedang berjalan — agen memanggil getCurrentWeather dulu, lalu mengalirkan hasil Celsius ke celsiusToFahrenheit, dan memberikan jawaban gabungan.* +*Rangkaian alat dalam aksi — agen memanggil getCurrentWeather terlebih dahulu, lalu memasukkan hasil Celsius ke celsiusToFahrenheit, dan memberi jawaban gabungan.* -**Penanganan Gagal dengan Anggun** — Tanya cuaca di kota yang tidak ada dalam data tiruan. Alat mengembalikan pesan kesalahan, dan AI menjelaskan bahwa ia tidak bisa membantu daripada mengalami crash. Alat gagal dengan aman. Diagram berikut membandingkan dua pendekatan — dengan penanganan kesalahan yang tepat, agen menangkap pengecualian dan merespon dengan penjelasan, sementara tanpa penanganan aplikasi keseluruhan crash: +**Kegagalan yang Elegan** — Minta cuaca di kota yang tidak ada dalam data tiruan. Alat mengembalikan pesan kesalahan, dan AI menjelaskan bahwa ia tidak bisa membantu daripada aplikasi langsung crash. Alat gagal dengan aman. Diagram di bawah membandingkan dua pendekatan — dengan penanganan kesalahan yang tepat, agen menangkap pengecualian dan menjawab dengan penjelasan yang membantu, sedangkan tanpa itu aplikasi langsung crash: -Error Handling Flow +Alur Penanganan Kesalahan -*Saat alat gagal, agen menangkap kesalahan dan merespon dengan penjelasan yang membantu daripada mengalami crash.* +*Saat alat gagal, agen menangkap kesalahan dan merespons dengan penjelasan yang membantu daripada mengalami crash.* -Ini terjadi dalam satu langkah percakapan. Agen mengorkestrasi banyak panggilan alat secara mandiri. +Ini terjadi dalam satu putaran percakapan. Agen mengorkestrasi banyak panggilan alat secara mandiri. -## Menjalankan Aplikasi +## Jalankan Aplikasi -**Verifikasi pemasangan:** +**Verifikasi penerapan:** -Pastikan file `.env` ada di direktori root berisi kredensial Azure (dibuat saat Modul 01). Jalankan ini dari direktori modul (`04-tools/`): +Pastikan file `.env` ada di direktori root dengan kredensial Azure (dibuat selama Modul 01). Jalankan ini dari direktori modul (`04-tools/`): -**Bash:** +**Bash:** ```bash cat ../.env # Harus menampilkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # Harus menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Harus menampilkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Mulai aplikasi:** -> **Catatan:** Jika Anda sudah menjalankan semua aplikasi menggunakan `./start-all.sh` dari direktori root (seperti dijelaskan di Modul 01), modul ini sudah berjalan di port 8084. Anda bisa melewati perintah mulai di bawah dan langsung menuju http://localhost:8084. +> **Catatan:** Jika Anda sudah memulai semua aplikasi menggunakan `./start-all.sh` dari direktori root (seperti dijelaskan di Modul 01), modul ini sudah berjalan pada port 8084. Anda dapat melewati perintah mulai di bawah dan langsung buka http://localhost:8084. -**Opsi 1: Menggunakan Spring Boot Dashboard (Disarankan untuk pengguna VS Code)** +**Opsi 1: Menggunakan Spring Boot Dashboard (Direkomendasikan untuk pengguna VS Code)** -Dev container menyertakan ekstensi Spring Boot Dashboard, yang menyediakan antarmuka visual untuk mengelola semua aplikasi Spring Boot. Anda dapat menemukannya di Activity Bar di sisi kiri VS Code (cari ikon Spring Boot). +Kontainer pengembangan mencakup ekstensi Spring Boot Dashboard, yang menyediakan antarmuka visual untuk mengelola semua aplikasi Spring Boot. Anda dapat menemukannya di Activity Bar di sisi kiri VS Code (cari ikon Spring Boot). -Dari Spring Boot Dashboard, Anda dapat: -- Melihat semua aplikasi Spring Boot yang tersedia di workspace -- Memulai/menghentikan aplikasi dengan satu klik -- Melihat log aplikasi secara real-time +Dari Spring Boot Dashboard, Anda bisa: +- Melihat semua aplikasi Spring Boot yang tersedia di workspace +- Memulai/menyerahkan aplikasi dengan satu klik +- Melihat log aplikasi secara real-time - Memantau status aplikasi -Cukup klik tombol putar di samping "tools" untuk memulai modul ini, atau mulai semua modul sekaligus. -Ini tampilan Spring Boot Dashboard di VS Code: +Cukup klik tombol putar di sebelah "tools" untuk memulai modul ini, atau mulai semua modul sekaligus. +Berikut tampilan Spring Boot Dashboard di VS Code: Spring Boot Dashboard -*Spring Boot Dashboard di VS Code — mulai, hentikan, dan pantau semua modul dari satu tempat* +*Spring Boot Dashboard di VS Code — mulai, berhenti, dan monitor semua modul dari satu tempat* **Opsi 2: Menggunakan skrip shell** @@ -272,13 +272,13 @@ Kedua skrip secara otomatis memuat variabel lingkungan dari file `.env` di root > mvn clean package -DskipTests > ``` -Buka http://localhost:8084 di peramban Anda. +Buka http://localhost:8084 di browser Anda. -**Untuk menghentikan:** +**Untuk berhenti:** **Bash:** ```bash -./stop.sh # Hanya modul ini +./stop.sh # Modul ini saja # Atau cd .. && ./stop-all.sh # Semua modul ``` @@ -292,42 +292,42 @@ cd ..; .\stop-all.ps1 # Semua modul ## Menggunakan Aplikasi -Aplikasi menyediakan antarmuka web di mana Anda dapat berinteraksi dengan agen AI yang memiliki akses ke alat cuaca dan konversi suhu. Ini tampilan antarmukanya — termasuk contoh cepat mulai dan panel obrolan untuk mengirim permintaan: +Aplikasi menyediakan antarmuka web di mana Anda dapat berinteraksi dengan agen AI yang memiliki akses ke alat cuaca dan konversi suhu. Berikut tampilan antarmukanya — termasuk contoh cepat dan panel obrolan untuk mengirim permintaan: AI Agent Tools Interface -*Antarmuka AI Agent Tools - contoh cepat dan antarmuka obrolan untuk berinteraksi dengan alat* +*Antarmuka Alat Agen AI - contoh cepat dan antarmuka obrolan untuk berinteraksi dengan alat* ### Coba Penggunaan Alat Sederhana -Mulai dengan permintaan sederhana: "Konversikan 100 derajat Fahrenheit ke Celsius". Agen mengenali bahwa ia membutuhkan alat konversi suhu, memanggilnya dengan parameter yang benar, dan mengembalikan hasilnya. Perhatikan betapa alami rasanya — Anda tidak menspesifikasikan alat mana yang harus digunakan atau bagaimana memanggilnya. +Mulai dengan permintaan sederhana: "Konversi 100 derajat Fahrenheit ke Celsius". Agen mengenali bahwa ia memerlukan alat konversi suhu, memanggilnya dengan parameter yang tepat, dan mengembalikan hasilnya. Perhatikan betapa alami cara ini - Anda tidak perlu menentukan alat mana yang digunakan atau bagaimana memanggilnya. ### Uji Rangkaian Alat -Sekarang coba yang lebih kompleks: "Bagaimana cuaca di Seattle dan konversikan ke Fahrenheit?" Saksikan agen bekerja melalui ini dalam beberapa langkah. Pertama ia mendapatkan cuaca (yang mengembalikan Celsius), mengenali ia perlu mengubah ke Fahrenheit, memanggil alat konversi, dan menggabungkan kedua hasil tersebut menjadi satu respons. +Sekarang coba sesuatu yang lebih kompleks: "Bagaimana cuaca di Seattle dan konversikan ke Fahrenheit?" Saksikan bagaimana agen mengerjakan ini dalam beberapa langkah. Pertama mengambil cuaca (yang mengembalikan dalam Celsius), mengenali perlu mengonversi ke Fahrenheit, memanggil alat konversi, dan menggabungkan kedua hasil menjadi satu respons. ### Lihat Alur Percakapan -Antarmuka obrolan menyimpan riwayat percakapan, memungkinkan Anda melakukan interaksi multi-langkah. Anda dapat melihat semua kueri dan respons sebelumnya, sehingga mudah melacak percakapan dan memahami bagaimana agen membangun konteks melalui beberapa pertukaran. +Antarmuka obrolan menyimpan riwayat percakapan, memungkinkan Anda melakukan interaksi berputar-putar. Anda bisa melihat semua pertanyaan dan jawaban sebelumnya, membuatnya mudah melacak percakapan dan memahami bagaimana agen membangun konteks selama beberapa pertukaran. Conversation with Multiple Tool Calls -*Percakapan multi-langkah yang menunjukkan konversi sederhana, pencarian cuaca, dan rantai alat* +*Percakapan multi-putar yang menunjukkan konversi sederhana, pencarian cuaca, dan rangkaian alat* -### Eksperimen dengan Berbagai Permintaan +### Eksperimen dengan Permintaan Berbeda Coba berbagai kombinasi: - Pencarian cuaca: "Bagaimana cuaca di Tokyo?" - Konversi suhu: "Berapa 25°C dalam Kelvin?" -- Kueri gabungan: "Periksa cuaca di Paris dan beri tahu jika suhunya di atas 20°C" +- Pertanyaan gabungan: "Periksa cuaca di Paris dan beri tahu jika di atas 20°C" -Perhatikan bagaimana agen menginterpretasikan bahasa alami dan memetakan ke panggilan alat yang sesuai. +Perhatikan bagaimana agen mengartikan bahasa alami dan memetakan ke panggilan alat yang sesuai. -## Konsep Utama +## Konsep Kunci -### Pola ReAct (Reasoning and Acting) +### Pola ReAct (Penalaran dan Bertindak) -Agen bergantian antara berpikir (memutuskan apa yang harus dilakukan) dan bertindak (menggunakan alat). Pola ini memungkinkan pemecahan masalah secara mandiri, bukan hanya merespon instruksi. +Agen bergantian antara penalaran (memutuskan apa yang harus dilakukan) dan bertindak (menggunakan alat). Pola ini memungkinkan pemecahan masalah secara mandiri daripada hanya merespon instruksi. ### Deskripsi Alat Penting @@ -335,53 +335,53 @@ Kualitas deskripsi alat Anda langsung memengaruhi seberapa baik agen menggunakan ### Manajemen Sesi -Anotasi `@MemoryId` memungkinkan manajemen memori berbasis sesi secara otomatis. Setiap ID sesi mendapatkan instansi `ChatMemory` sendiri yang dikelola oleh bean `ChatMemoryProvider`, sehingga banyak pengguna dapat berinteraksi dengan agen sekaligus tanpa percakapan mereka bercampur. Diagram berikut menunjukkan bagaimana banyak pengguna diarahkan ke penyimpanan memori terisolasi berdasarkan ID sesi mereka: +Anotasi `@MemoryId` memungkinkan manajemen memori berbasis sesi secara otomatis. Setiap ID sesi mendapatkan instansi `ChatMemory` yang dikelola oleh bean `ChatMemoryProvider`, sehingga banyak pengguna dapat berinteraksi dengan agen secara bersamaan tanpa percakapan tercampur. Diagram berikut menunjukkan bagaimana banyak pengguna diarahkan ke penyimpanan memori terisolasi berdasarkan ID sesi mereka: Session Management with @MemoryId *Setiap ID sesi memetakan ke riwayat percakapan yang terisolasi — pengguna tidak pernah melihat pesan satu sama lain.* -### Penanganan Kesalahan +### Penanganan Error -Alat bisa gagal — API bisa timeout, parameter mungkin tidak valid, layanan eksternal bisa mati. Agen produksi membutuhkan penanganan kesalahan supaya model dapat menjelaskan masalah atau mencoba alternatif daripada membuat aplikasi macet. Saat alat melempar pengecualian, LangChain4j menangkapnya dan mengirimkan pesan kesalahan kembali ke model, yang kemudian dapat menjelaskan masalah dalam bahasa alami. +Alat dapat gagal — API timeout, parameter mungkin tidak valid, layanan eksternal mati. Agen produksi memerlukan penanganan error agar model dapat menjelaskan masalah atau mencoba alternatif daripada aplikasi keseluruhan crash. Ketika alat melempar pengecualian, LangChain4j menangkapnya dan mengirim pesan error kembali ke model, yang kemudian dapat menjelaskan masalah dalam bahasa alami. ## Alat yang Tersedia -Diagram di bawah menunjukkan ekosistem luas alat yang dapat Anda bangun. Modul ini mendemonstrasikan alat cuaca dan suhu, tapi pola `@Tool` yang sama berlaku untuk metode Java apa pun — dari kueri basis data hingga pemrosesan pembayaran. +Diagram di bawah ini menunjukkan ekosistem luas alat yang dapat Anda bangun. Modul ini menampilkan alat cuaca dan suhu, tetapi pola `@Tool` yang sama berlaku untuk metode Java manapun — dari kueri database hingga pemrosesan pembayaran. Tool Ecosystem -*Metode Java apapun yang dianotasikan dengan @Tool menjadi tersedia untuk AI — pola ini meluas ke database, API, email, operasi file, dan lainnya.* +*Metode Java manapun yang dianotasi dengan @Tool tersedia untuk AI — pola ini meluas ke database, API, email, operasi file, dan lainnya.* ## Kapan Menggunakan Agen Berbasis Alat -Tidak setiap permintaan membutuhkan alat. Keputusan tergantung apakah AI perlu berinteraksi dengan sistem eksternal atau dapat menjawab dari pengetahuannya sendiri. Panduan berikut merangkum kapan alat memberikan nilai tambah dan kapan tidak diperlukan: +Tidak semua permintaan membutuhkan alat. Keputusan tergantung apakah AI perlu berinteraksi dengan sistem eksternal atau dapat menjawab dari pengetahuannya sendiri. Panduan berikut merangkum kapan alat memberikan nilai dan kapan tidak diperlukan: When to Use Tools -*Panduan keputusan cepat — alat untuk data waktu nyata, perhitungan, dan aksi; pengetahuan umum dan tugas kreatif tidak memerlukannya.* +*Panduan singkat — alat untuk data real-time, kalkulasi, dan aksi; pengetahuan umum dan tugas kreatif tidak membutuhkannya.* ## Alat vs RAG -Modul 03 dan 04 keduanya memperluas kemampuan AI, tapi dengan cara yang sangat berbeda. RAG memberi model akses ke **pengetahuan** dengan mengambil dokumen. Alat memberi model kemampuan mengambil **aksi** dengan memanggil fungsi. Diagram di bawah membandingkan dua pendekatan ini secara berdampingan — dari cara kerja setiap alur hingga kelebihan dan kekurangannya: +Modul 03 dan 04 sama-sama memperluas kemampuan AI, tetapi dengan cara fundamental yang berbeda. RAG memberi model akses ke **pengetahuan** dengan mengambil dokumen. Alat memberi model kemampuan untuk mengambil **aksi** dengan memanggil fungsi. Diagram berikut membandingkan kedua pendekatan — dari cara kerja setiap alur hingga trade-off di antara keduanya: Tools vs RAG Comparison -*RAG mengambil informasi dari dokumen statis — Alat menjalankan aksi dan mengambil data dinamis waktu nyata. Banyak sistem produksi menggabungkan keduanya.* +*RAG mengambil informasi dari dokumen statis — Alat menjalankan aksi dan mengambil data dinamis real-time. Banyak sistem produksi menggabungkan keduanya.* -Dalam praktiknya, banyak sistem produksi menggabungkan kedua pendekatan: RAG untuk mendasarkan jawaban pada dokumentasi Anda, dan Alat untuk mengambil data langsung atau melakukan operasi. +Dalam praktiknya, banyak sistem produksi menggabungkan kedua pendekatan: RAG untuk mendasari jawaban dalam dokumentasi Anda, dan Alat untuk mengambil data langsung atau melakukan operasi. -## Langkah Selanjutnya +## Langkah Berikutnya **Modul Berikutnya:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**Navigasi:** [← Sebelumnya: Modul 03 - RAG](../03-rag/README.md) | [Kembali ke Utama](../README.md) | [Berikutnya: Modul 05 - MCP →](../05-mcp/README.md) +**Navigasi:** [← Sebelumnya: Modul 03 - RAG](../03-rag/README.md) | [Kembali ke Beranda](../README.md) | [Selanjutnya: Modul 05 - MCP →](../05-mcp/README.md) --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk mencapai akurasi, harap diperhatikan bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sahih. Untuk informasi penting, disarankan untuk menggunakan terjemahan manusia profesional. Kami tidak bertanggung jawab atas kesalahpahaman atau kesalahan interpretasi yang timbul dari penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk mencapai akurasi, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/id/README.md b/translations/id/README.md index cc14f116d..a3437b3e1 100644 --- a/translations/id/README.md +++ b/translations/id/README.md @@ -2,7 +2,7 @@ # LangChain4j untuk Pemula -Sebuah kursus untuk membangun aplikasi AI dengan LangChain4j dan Azure OpenAI GPT-5.2, dari obrolan dasar hingga agen AI. +Sebuah kursus untuk membangun aplikasi AI dengan LangChain4j dan Azure OpenAI GPT-5.2, dari chat dasar hingga agen AI. ### 🌐 Dukungan Multi-Bahasa @@ -11,9 +11,9 @@ Sebuah kursus untuk membangun aplikasi AI dengan LangChain4j dan Azure OpenAI GP [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](./README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Lebih Suka Mengkloning Secara Lokal?** +> **Lebih suka Clone Secara Lokal?** > -> Repositori ini mencakup lebih dari 50 terjemahan bahasa yang secara signifikan meningkatkan ukuran unduhan. Untuk mengkloning tanpa terjemahan, gunakan sparse checkout: +> Repositori ini mencakup 50+ terjemahan bahasa yang secara signifikan meningkatkan ukuran unduhan. Untuk meng-clone tanpa terjemahan, gunakan sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -34,56 +34,55 @@ Sebuah kursus untuk membangun aplikasi AI dengan LangChain4j dan Azure OpenAI GP ## Daftar Isi -1. [Mulai Cepat](00-quick-start/README.md) - Mulai dengan LangChain4j -2. [Pengantar](01-introduction/README.md) - Pelajari dasar-dasar LangChain4j -3. [Rekayasa Prompt](02-prompt-engineering/README.md) - Kuasai desain prompt yang efektif -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Bangun sistem berbasis pengetahuan yang cerdas -5. [Alat](04-tools/README.md) - Integrasikan alat eksternal dan asisten sederhana -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Bekerja dengan Model Context Protocol (MCP) dan modul Agentic +1. [Pengantar](01-introduction/README.md) - Pelajari dasar-dasar LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Kuasai desain prompt yang efektif +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Bangun sistem berbasis pengetahuan yang cerdas +4. [Tools](04-tools/README.md) - Integrasikan alat eksternal dan asisten sederhana +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Bekerja dengan Model Context Protocol (MCP) dan modul Agentic -### Video Tutorial +### Video Panduan -Setiap modul memiliki sesi langsung pendamping di mana kami berjalan melalui konsep dan kode langkah demi langkah. +Setiap modul memiliki sesi live pendamping dimana kita membahas konsep dan kode langkah demi langkah. | Modul | Video | |--------|-------| | 01 - Pengantar | [Memulai dengan LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Rekayasa Prompt | [Rekayasa Prompt dengan LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 02 - Prompt Engineering | [Prompt Engineering dengan LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG dengan LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Alat & 05 - MCP | [Agen AI dengan Alat dan MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Tools & 05 - MCP | [Agen AI dengan Tools dan MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## Jalur Pembelajaran -**Baru di LangChain4j?** Lihat [Glosarium](docs/GLOSSARY.md) untuk definisi istilah dan konsep kunci. +**Baru mengenal LangChain4j?** Lihat [Glosarium](docs/GLOSSARY.md) untuk definisi istilah dan konsep kunci. > **Mulai Cepat** 1. Fork repositori ini ke akun GitHub Anda 2. Klik **Code** → tab **Codespaces** → **...** → **New with options...** -3. Gunakan default – ini akan memilih container Pengembangan yang dibuat untuk kursus ini +3. Gunakan pengaturan default – ini akan memilih kontainer Pengembangan yang dibuat untuk kursus ini 4. Klik **Create codespace** -5. Tunggu 5-10 menit sampai lingkungan siap -6. Langsung lompat ke [Mulai Cepat](./00-quick-start/README.md) untuk memulai! +5. Tunggu 5-10 menit hingga lingkungan siap +6. Langsung ke [Pengantar](./01-introduction/README.md) untuk memulai! Setelah menyelesaikan modul-modul, jelajahi [Panduan Pengujian](docs/TESTING.md) untuk melihat konsep pengujian LangChain4j secara langsung. -> **Catatan:** Pelatihan ini menggunakan baik GitHub Models maupun Azure OpenAI. Modul [Mulai Cepat](00-quick-start/README.md) menggunakan GitHub Models (tidak perlu langganan Azure), sementara modul 1-5 menggunakan Azure OpenAI. Mulailah dengan [akun Azure GRATIS](https://aka.ms/azure-free-account) jika Anda belum memilikinya. +> **Catatan:** Pelatihan ini menggunakan Azure OpenAI. Mulailah dengan [akun Azure GRATIS](https://aka.ms/azure-free-account) jika Anda belum memilikinya. ## Belajar dengan GitHub Copilot -Untuk cepat mulai coding, buka proyek ini di GitHub Codespace atau IDE lokal Anda dengan devcontainer yang disediakan. Devcontainer yang digunakan dalam kursus ini sudah dikonfigurasi sebelumnya dengan GitHub Copilot untuk pemrograman berpasangan AI. +Untuk memulai pengkodean dengan cepat, buka proyek ini di GitHub Codespace atau IDE lokal Anda dengan devcontainer yang disediakan. Devcontainer yang digunakan dalam kursus ini sudah dikonfigurasi sebelumnya dengan GitHub Copilot untuk pemrograman berpasangan AI. -Setiap contoh kode menyertakan pertanyaan yang disarankan yang dapat Anda tanyakan ke GitHub Copilot untuk memperdalam pemahaman Anda. Cari prompt 💡/🤖 di: +Setiap contoh kode mencakup pertanyaan yang disarankan yang dapat Anda tanyakan ke GitHub Copilot untuk memperdalam pemahaman Anda. Cari prompt 💡/🤖 di: -- **Header file Java** - Pertanyaan khusus untuk setiap contoh +- **Header file Java** - Pertanyaan spesifik untuk setiap contoh - **README modul** - Prompt eksplorasi setelah contoh kode -**Cara menggunakan:** Buka file kode apa pun dan tanyakan pertanyaan yang disarankan ke Copilot. Ia memiliki konteks penuh dari basis kode dan dapat menjelaskan, memperluas, serta menyarankan alternatif. +**Cara menggunakan:** Buka file kode apa saja dan tanyakan pertanyaan yang disarankan kepada Copilot. Ia memiliki konteks penuh dari basis kode dan bisa menjelaskan, memperluas, dan menyarankan alternatif. -Ingin belajar lebih banyak? Lihat [Copilot untuk Pemrograman Berpasangan AI](https://aka.ms/GitHubCopilotAI). +Ingin belajar lebih lanjut? Lihat [Copilot untuk Pemrograman Berpasangan AI](https://aka.ms/GitHubCopilotAI). ## Sumber Daya Tambahan @@ -115,7 +114,7 @@ Ingin belajar lebih banyak? Lihat [Copilot untuk Pemrograman Berpasangan AI](htt [![ML untuk Pemula](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science untuk Pemula](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI untuk Pemula](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Keamanan Siber untuk Pemula](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -134,7 +133,7 @@ Jika Anda mengalami kesulitan atau memiliki pertanyaan tentang membangun aplikas [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Jika Anda memiliki umpan balik produk atau mengalami kesalahan saat membangun, kunjungi: +Jika Anda memiliki masukan produk atau menemukan kesalahan saat membangun, kunjungi: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) @@ -145,6 +144,6 @@ Lisensi MIT - Lihat file [LICENSE](../../LICENSE) untuk detail. --- -**Penolakan**: -Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk keakuratan, harap diperhatikan bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang berwenang. Untuk informasi yang penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau salah tafsir yang timbul dari penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk mencapai akurasi, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/id/docs/GLOSSARY.md b/translations/id/docs/GLOSSARY.md index 96d2e9fed..2e159013b 100644 --- a/translations/id/docs/GLOSSARY.md +++ b/translations/id/docs/GLOSSARY.md @@ -2,65 +2,65 @@ ## Daftar Isi -- [Konsep Inti](../../../docs) -- [Komponen LangChain4j](../../../docs) -- [Konsep AI/ML](../../../docs) -- [Guardrails](../../../docs) -- [Rekayasa Prompt](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agen dan Alat](../../../docs) -- [Modul Agenik](../../../docs) -- [Protokol Konteks Model (MCP)](../../../docs) -- [Layanan Azure](../../../docs) -- [Pengujian dan Pengembangan](../../../docs) +- [Konsep Inti](#konsep-inti) +- [Komponen LangChain4j](#komponen-langchain4j) +- [Konsep AI/ML](#konsep-aiml) +- [Guardrails](#guardrails) +- [Rekayasa Prompt](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agen dan Alat](#agents-and-tools---module-04) +- [Modul Agentic](#agentic-module---module-05) +- [Protokol Konteks Model (MCP)](#model-context-protocol-mcp---module-05) +- [Layanan Azure](#azure-services---module-01) +- [Pengujian dan Pengembangan](#testing-and-development---testing-guide) Referensi cepat untuk istilah dan konsep yang digunakan sepanjang kursus. ## Konsep Inti -**AI Agent** - Sistem yang menggunakan AI untuk bernalar dan bertindak secara mandiri. [Module 04](../04-tools/README.md) +**Agen AI** - Sistem yang menggunakan AI untuk bernalar dan bertindak secara otonom. [Modul 04](../04-tools/README.md) -**Chain** - Urutan operasi di mana keluaran menjadi masukan langkah berikutnya. +**Rantai** - Urutan operasi di mana keluaran menjadi masukan langkah berikutnya. -**Chunking** - Memecah dokumen menjadi bagian lebih kecil. Biasanya: 300-500 token dengan tumpang tindih. [Module 03](../03-rag/README.md) +**Pengchunkan** - Memecah dokumen menjadi potongan-potongan lebih kecil. Umum: 300-500 token dengan tumpang tindih. [Modul 03](../03-rag/README.md) -**Context Window** - Maksimum token yang dapat diproses model. GPT-5.2: 400K token (hingga 272K input, 128K output). +**Jendela Konteks** - Jumlah token maksimum yang dapat diproses model. GPT-5.2: 400K token (hingga 272K masukan, 128K keluaran). -**Embeddings** - Vektor numerik yang mewakili makna teks. [Module 03](../03-rag/README.md) +**Embedding** - Vektor numerik yang merepresentasikan makna teks. [Modul 03](../03-rag/README.md) -**Function Calling** - Model menghasilkan permintaan terstruktur untuk memanggil fungsi eksternal. [Module 04](../04-tools/README.md) +**Pemanggilan Fungsi** - Model menghasilkan permintaan terstruktur untuk memanggil fungsi eksternal. [Modul 04](../04-tools/README.md) -**Hallucination** - Saat model menghasilkan informasi yang salah tapi tampak masuk akal. +**Halusinasi** - Ketika model menghasilkan informasi yang salah namun masuk akal. -**Prompt** - Masukan teks untuk model bahasa. [Module 02](../02-prompt-engineering/README.md) +**Prompt** - Input teks untuk model bahasa. [Modul 02](../02-prompt-engineering/README.md) -**Semantic Search** - Pencarian berdasarkan makna dengan embeddings, bukan kata kunci. [Module 03](../03-rag/README.md) +**Pencarian Semantik** - Pencarian berdasarkan makna menggunakan embedding, bukan kata kunci. [Modul 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: tanpa memori. Stateful: menyimpan riwayat percakapan. [Module 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: tanpa memori. Stateful: mempertahankan riwayat percakapan. [Modul 01](../01-introduction/README.md) -**Tokens** - Unit dasar teks yang diproses model. Mempengaruhi biaya dan batasan. [Module 01](../01-introduction/README.md) +**Token** - Unit dasar teks yang diproses model. Mempengaruhi biaya dan batasan. [Modul 01](../01-introduction/README.md) -**Tool Chaining** - Eksekusi alat berurutan di mana keluaran memberi informasi untuk panggilan berikutnya. [Module 04](../04-tools/README.md) +**Rantai Alat** - Eksekusi alat secara berurutan di mana keluaran menjadi masukan berikutnya. [Modul 04](../04-tools/README.md) ## Komponen LangChain4j -**AiServices** - Membuat antarmuka layanan AI yang tipe-safenya terjamin. +**AiServices** - Membuat antarmuka layanan AI yang tipe-aman. **OpenAiOfficialChatModel** - Klien terpadu untuk model OpenAI dan Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Membuat embeddings menggunakan klien OpenAI Official (mendukung OpenAI dan Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Membuat embedding menggunakan klien OpenAI Official (mendukung OpenAI dan Azure OpenAI). **ChatModel** - Antarmuka inti untuk model bahasa. -**ChatMemory** - Menyimpan riwayat percakapan. +**ChatMemory** - Mempertahankan riwayat percakapan. -**ContentRetriever** - Menemukan potongan dokumen yang relevan untuk RAG. +**ContentRetriever** - Menemukan potongan dokumen relevan untuk RAG. **DocumentSplitter** - Memecah dokumen menjadi potongan. **EmbeddingModel** - Mengubah teks menjadi vektor numerik. -**EmbeddingStore** - Menyimpan dan mengambil embeddings. +**EmbeddingStore** - Menyimpan dan mengambil embedding. **MessageWindowChatMemory** - Menjaga jendela geser pesan terbaru. @@ -74,159 +74,157 @@ Referensi cepat untuk istilah dan konsep yang digunakan sepanjang kursus. ## Konsep AI/ML -**Few-Shot Learning** - Memberikan contoh dalam prompt. [Module 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Memberikan contoh di dalam prompt. [Modul 02](../02-prompt-engineering/README.md) **Large Language Model (LLM)** - Model AI yang dilatih pada data teks besar. -**Reasoning Effort** - Parameter GPT-5.2 yang mengontrol kedalaman penalaran. [Module 02](../02-prompt-engineering/README.md) +**Effort Penalaran** - Parameter GPT-5.2 yang mengatur kedalaman pemikiran. [Modul 02](../02-prompt-engineering/README.md) -**Temperature** - Mengontrol keacakan keluaran. Rendah=deterministik, tinggi=kreatif. +**Temperature** - Mengatur tingkat randomness keluaran. Rendah=deterministik, tinggi=kreatif. -**Vector Database** - Basis data khusus untuk embeddings. [Module 03](../03-rag/README.md) +**Database Vektor** - Database khusus untuk embedding. [Modul 03](../03-rag/README.md) -**Zero-Shot Learning** - Melakukan tugas tanpa contoh. [Module 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Melakukan tugas tanpa contoh. [Modul 02](../02-prompt-engineering/README.md) -## Guardrails - [Module 00](../00-quick-start/README.md) +## Guardrails -**Defense in Depth** - Pendekatan keamanan berlapis yang menggabungkan guardrails tingkat aplikasi dengan filter keamanan penyedia. +**Pertahanan Berlapis** - Pendekatan keamanan berlapis yang menggabungkan guardrails di tingkat aplikasi dengan filter keamanan penyedia. -**Hard Block** - Penyedia memberikan error HTTP 400 untuk pelanggaran konten serius. +**Blok Keras** - Penyedia mengeluarkan error HTTP 400 untuk pelanggaran konten berat. -**InputGuardrail** - Antarmuka LangChain4j untuk memvalidasi masukan pengguna sebelum diterima LLM. Menghemat biaya dan latensi dengan memblokir prompt berbahaya lebih awal. +**InputGuardrail** - Antarmuka LangChain4j untuk memvalidasi input pengguna sebelum mencapai LLM. Menghemat biaya dan latensi dengan memblokir prompt berbahaya sejak awal. -**InputGuardrailResult** - Tipe pengembalian untuk validasi guardrail: `success()` atau `fatal("reason")`. +**InputGuardrailResult** - Tipe kembalian untuk validasi guardrail: `success()` atau `fatal("reason")`. **OutputGuardrail** - Antarmuka untuk memvalidasi respons AI sebelum dikembalikan ke pengguna. -**Provider Safety Filters** - Filter konten bawaan dari penyedia AI (misal, GitHub Models) yang mendeteksi pelanggaran di tingkat API. +**Filter Keamanan Penyedia** - Filter konten bawaan dari penyedia AI (misal: Azure OpenAI) yang menangkap pelanggaran di tingkat API. -**Soft Refusal** - Model dengan sopan menolak menjawab tanpa mengeluarkan error. +**Penolakan Lembut** - Model dengan sopan menolak menjawab tanpa menghasilkan error. -## Rekayasa Prompt - [Module 02](../02-prompt-engineering/README.md) +## Rekayasa Prompt - [Modul 02](../02-prompt-engineering/README.md) **Chain-of-Thought** - Penalaran langkah demi langkah untuk akurasi lebih baik. -**Constrained Output** - Memaksa format atau struktur tertentu. +**Keluaran Terbatas** - Menerapkan format atau struktur tertentu. -**High Eagerness** - Pola GPT-5.2 untuk penalaran mendalam. +**Semangat Tinggi** - Pola GPT-5.2 untuk pemikiran mendalam. -**Low Eagerness** - Pola GPT-5.2 untuk jawaban cepat. +**Semangat Rendah** - Pola GPT-5.2 untuk jawaban cepat. -**Multi-Turn Conversation** - Mempertahankan konteks antar pertukaran. +**Percakapan Multi-Turn** - Mempertahankan konteks antar pertukaran. -**Role-Based Prompting** - Menetapkan persona model melalui pesan sistem. +**Prompt Berdasarkan Peran** - Menetapkan persona model via pesan sistem. -**Self-Reflection** - Model mengevaluasi dan meningkatkan keluarannya. +**Refleksi Diri** - Model mengevaluasi dan memperbaiki keluarannya. -**Structured Analysis** - Kerangka evaluasi tetap. +**Analisis Terstruktur** - Kerangka evaluasi tetap. -**Task Execution Pattern** - Rencana → Eksekusi → Ringkasan. +**Pola Eksekusi Tugas** - Rencana → Jalankan → Ringkas. -## RAG (Retrieval-Augmented Generation) - [Module 03](../03-rag/README.md) +## RAG (Retrieval-Augmented Generation) - [Modul 03](../03-rag/README.md) -**Document Processing Pipeline** - Muat → potong → buat embedding → simpan. +**Pipeline Pemrosesan Dokumen** - Muat → potong → embedding → simpan. -**In-Memory Embedding Store** - Penyimpanan non-persisten untuk pengujian. +**Penyimpanan Embedding In-Memory** - Penyimpanan non-persisten untuk pengujian. -**RAG** - Menggabungkan pengambilan dengan generasi untuk menguatkan jawaban. +**RAG** - Menggabungkan pengambilan dengan generasi untuk menguatkan respons. -**Similarity Score** - Ukuran (0-1) kesamaan semantik. +**Skor Kemiripan** - Ukuran (0-1) kemiripan semantik. -**Source Reference** - Metadata tentang konten yang diambil. +**Referensi Sumber** - Metadata tentang konten yang diambil. -## Agen dan Alat - [Module 04](../04-tools/README.md) +## Agen dan Alat - [Modul 04](../04-tools/README.md) **@Tool Annotation** - Menandai metode Java sebagai alat yang dapat dipanggil AI. -**ReAct Pattern** - Bernalar → Bertindak → Mengamati → Ulangi. +**Pola ReAct** - Bernalar → Bertindak → Mengamati → Ulang. -**Session Management** - Konteks terpisah untuk pengguna berbeda. +**Manajemen Sesi** - Konteks terpisah untuk pengguna berbeda. -**Tool** - Fungsi yang dapat dipanggil agen AI. +**Alat** - Fungsi yang dapat dipanggil agen AI. -**Tool Description** - Dokumentasi tujuan dan parameter alat. +**Deskripsi Alat** - Dokumentasi tujuan dan parameter alat. -## Modul Agenik - [Module 05](../05-mcp/README.md) +## Modul Agentic - [Modul 05](../05-mcp/README.md) **@Agent Annotation** - Menandai antarmuka sebagai agen AI dengan definisi perilaku deklaratif. **Agent Listener** - Hook untuk memantau eksekusi agen melalui `beforeAgentInvocation()` dan `afterAgentInvocation()`. -**Agentic Scope** - Memori bersama tempat agen menyimpan keluaran menggunakan `outputKey` yang dapat digunakan agen lain. +**Agentic Scope** - Memori bersama tempat agen menyimpan keluaran menggunakan `outputKey` untuk dikonsumsi agen lain. -**AgenticServices** - Pabrik untuk membuat agen menggunakan `agentBuilder()` dan `supervisorBuilder()`. +**AgenticServices** - Pabrik pembuatan agen menggunakan `agentBuilder()` dan `supervisorBuilder()`. -**Conditional Workflow** - Rute berbasis kondisi menuju agen spesialis berbeda. +**Alur Kerja Bersyarat** - Pengarahan berdasarkan kondisi ke agen spesialis berbeda. -**Human-in-the-Loop** - Pola alur kerja yang menambahkan titik pemeriksaan manusia untuk persetujuan atau tinjauan konten. +**Manusia dalam Loop** - Pola alur kerja menambahkan titik pemeriksaan manusia untuk persetujuan atau peninjauan konten. -**langchain4j-agentic** - Dependensi Maven untuk pembuatan agen deklaratif (eksperimental). +**langchain4j-agentic** - Dependensi Maven untuk pembangunan agen deklaratif (eksperimental). -**Loop Workflow** - Iterasi eksekusi agen sampai kondisi terpenuhi (misal, skor kualitas ≥ 0.8). +**Alur Kerja Loop** - Iterasi eksekusi agen sampai kondisi terpenuhi (misal: skor kualitas ≥ 0.8). -**outputKey** - Parameter anotasi agen yang menentukan tempat hasil disimpan di Agentic Scope. +**outputKey** - Parameter anotasi agen yang menentukan tempat penyimpanan hasil di Agentic Scope. -**Parallel Workflow** - Menjalankan beberapa agen secara simultan untuk tugas independen. +**Alur Kerja Paralel** - Menjalankan beberapa agen secara bersamaan untuk tugas independen. -**Response Strategy** - Cara supervisor merumuskan jawaban akhir: LAST, SUMMARY, atau SCORED. +**Strategi Respons** - Cara supervisor merumuskan jawaban akhir: LAST, SUMMARY, atau SCORED. -**Sequential Workflow** - Menjalankan agen berurutan di mana keluaran mengalir ke langkah berikutnya. +**Alur Kerja Berurutan** - Menjalankan agen secara urut di mana keluaran mengalir ke langkah berikutnya. -**Supervisor Agent Pattern** - Pola agenik tingkat lanjut di mana supervisor LLM secara dinamis memutuskan sub-agen mana yang dipanggil. +**Pola Agen Supervisor** - Pola agentic lanjutan di mana LLM supervisor secara dinamis memutuskan sub-agen mana yang dipanggil. -## Protokol Konteks Model (MCP) - [Module 05](../05-mcp/README.md) +## Protokol Konteks Model (MCP) - [Modul 05](../05-mcp/README.md) -**langchain4j-mcp** - Dependensi Maven untuk integrasi MCP di LangChain4j. +**langchain4j-mcp** - Dependensi Maven untuk integrasi MCP dalam LangChain4j. -**MCP** - Model Context Protocol: standar untuk menghubungkan aplikasi AI ke alat eksternal. Bangun sekali, gunakan di mana saja. +**MCP** - Model Context Protocol: standar untuk menghubungkan aplikasi AI ke alat eksternal. Bangun sekali, gunakan di mana-mana. -**MCP Client** - Aplikasi yang terhubung ke server MCP untuk menemukan dan menggunakan alat. +**Klien MCP** - Aplikasi yang terhubung ke server MCP untuk menemukan dan menggunakan alat. -**MCP Server** - Layanan yang mengekspos alat melalui MCP dengan deskripsi jelas dan skema parameter. +**Server MCP** - Layanan yang mengekspos alat lewat MCP dengan deskripsi jelas dan skema parameter. -**McpToolProvider** - Komponen LangChain4j yang membungkus alat MCP untuk digunakan di layanan AI dan agen. +**McpToolProvider** - Komponen LangChain4j yang membungkus alat MCP untuk dipakai dalam layanan dan agen AI. -**McpTransport** - Antarmuka untuk komunikasi MCP. Implementasi termasuk Stdio dan HTTP. +**McpTransport** - Antarmuka untuk komunikasi MCP. Implementasi meliputi Stdio dan HTTP. -**Stdio Transport** - Transport proses lokal melalui stdin/stdout. Berguna untuk akses sistem berkas atau alat command-line. +**Transport Stdio** - Transport proses lokal lewat stdin/stdout. Berguna untuk akses sistem berkas atau alat baris perintah. **StdioMcpTransport** - Implementasi LangChain4j yang menjalankan server MCP sebagai subprocess. -**Tool Discovery** - Klien menanyakan server tentang alat yang tersedia dengan deskripsi dan skema. +**Penemuan Alat** - Klien menanyakan server tentang alat tersedia berikut deskripsi dan skema. -## Layanan Azure - [Module 01](../01-introduction/README.md) +## Layanan Azure - [Modul 01](../01-introduction/README.md) -**Azure AI Search** - Pencarian cloud dengan kemampuan vektor. [Module 03](../03-rag/README.md) +**Azure AI Search** - Pencarian awan dengan kapabilitas vektor. [Modul 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Men-deploy sumber daya Azure. +**Azure Developer CLI (azd)** - Mendeploy sumber daya Azure. **Azure OpenAI** - Layanan AI perusahaan Microsoft. **Bicep** - Bahasa infrastruktur sebagai kode Azure. [Panduan Infrastruktur](../01-introduction/infra/README.md) -**Deployment Name** - Nama untuk penyebaran model di Azure. +**Nama Deployment** - Nama untuk deployment model di Azure. -**GPT-5.2** - Model OpenAI terbaru dengan kontrol penalaran. [Module 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Model OpenAI terbaru dengan kontrol penalaran. [Modul 02](../02-prompt-engineering/README.md) ## Pengujian dan Pengembangan - [Panduan Pengujian](TESTING.md) -**Dev Container** - Lingkungan pengembangan berbasis kontainer. [Konfigurasi](../../../.devcontainer/devcontainer.json) +**Dev Container** - Lingkungan pengembangan containerized. [Konfigurasi](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Playground model AI gratis. [Module 00](../00-quick-start/README.md) +**Pengujian In-Memory** - Pengujian dengan penyimpanan in-memory. -**In-Memory Testing** - Pengujian dengan penyimpanan memori. +**Pengujian Integrasi** - Pengujian dengan infrastruktur nyata. -**Integration Testing** - Pengujian dengan infrastruktur nyata. - -**Maven** - Alat otomasi build Java. +**Maven** - Alat otomatisasi build Java. **Mockito** - Framework mocking Java. -**Spring Boot** - Kerangka aplikasi Java. [Module 01](../01-introduction/README.md) +**Spring Boot** - Framework aplikasi Java. [Modul 01](../01-introduction/README.md) --- **Penafian**: -Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya mencapai ketepatan, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang otoritatif. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini. +Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk mencapai akurasi, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/id/docs/TESTING.md b/translations/id/docs/TESTING.md index a25ed0c4e..1d020415d 100644 --- a/translations/id/docs/TESTING.md +++ b/translations/id/docs/TESTING.md @@ -2,15 +2,15 @@ ## Daftar Isi -- [Mulai Cepat](../../../docs) -- [Apa yang Diuji](../../../docs) -- [Menjalankan Tes](../../../docs) -- [Menjalankan Tes di VS Code](../../../docs) -- [Pola Pengujian](../../../docs) -- [Filosofi Pengujian](../../../docs) -- [Langkah Selanjutnya](../../../docs) +- [Mulai Cepat](#mulai-cepat) +- [Apa yang Diuji oleh Tes](#apa-yang-diuji-oleh-tes) +- [Menjalankan Tes](#menjalankan-tes) +- [Menjalankan Tes di VS Code](#menjalankan-tes-di-vs-code) +- [Polapola Pengujian](#polapola-pengujian) +- [Filosofi Pengujian](#filosofi-pengujian) +- [Langkah Selanjutnya](#langkah-selanjutnya) -Panduan ini memandu Anda melalui tes yang menunjukkan bagaimana menguji aplikasi AI tanpa memerlukan kunci API atau layanan eksternal. +Panduan ini memandu Anda melalui tes yang menunjukkan cara menguji aplikasi AI tanpa membutuhkan kunci API atau layanan eksternal. ## Mulai Cepat @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Saat semua tes berhasil, Anda akan melihat output seperti pada tangkapan layar di bawah — tes berjalan tanpa kegagalan. +Saat semua tes berhasil, Anda akan melihat keluaran seperti tangkapan layar di bawah — tes berjalan tanpa kegagalan. Hasil Tes Berhasil *Eksekusi tes yang berhasil menunjukkan semua tes lulus tanpa kegagalan* -## Apa yang Diuji +## Apa yang Diuji oleh Tes -Kursus ini berfokus pada **unit test** yang dijalankan secara lokal. Setiap tes menunjukkan konsep LangChain4j tertentu secara terpisah. Piramida pengujian di bawah menunjukkan posisi unit test — mereka membentuk fondasi yang cepat dan andal yang dibangun atas strategi pengujian Anda. +Kursus ini fokus pada **unit test** yang dijalankan secara lokal. Setiap tes menunjukkan konsep LangChain4j tertentu secara terpisah. Piramida pengujian di bawah ini menunjukkan tempat unit test — mereka membentuk fondasi yang cepat dan dapat diandalkan yang membangun strategi pengujian Anda. Piramida Pengujian -*Piramida pengujian menunjukkan keseimbangan antara unit test (cepat, terisolasi), integration test (komponen asli), dan end-to-end test. Pelatihan ini membahas pengujian unit.* +*Piramida pengujian menunjukkan keseimbangan antara unit test (cepat, terisolasi), integration test (komponen nyata), dan end-to-end test. Pelatihan ini mencakup pengujian unit.* -| Modul | Tes | Fokus | Berkas Utama | -|--------|-------|-------|-----------| -| **00 - Mulai Cepat** | 6 | Template prompt dan substitusi variabel | `SimpleQuickStartTest.java` | -| **01 - Pengantar** | 8 | Memori percakapan dan chat stateful | `SimpleConversationTest.java` | -| **02 - Rekayasa Prompt** | 12 | Pola GPT-5.2, tingkat eagerness, output terstruktur | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Pengolahan dokumen, embeddings, pencarian kemiripan | `DocumentServiceTest.java` | -| **04 - Alat** | 12 | Pemanggilan fungsi dan pengurutan alat | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol dengan transportasi Stdio | `SimpleMcpTest.java` | +| Modul | Tes | Fokus | Berkas Kunci | +|--------|-------|-------|--------------| +| **01 - Pengenalan** | 8 | Memori percakapan dan obrolan dengan status | `SimpleConversationTest.java` | +| **02 - Rekayasa Prompt** | 12 | Polapola GPT-5.2, tingkat keinginan, output terstruktur | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Pengambilan dokumen, embeddings, pencarian kemiripan | `DocumentServiceTest.java` | +| **04 - Alat** | 12 | Pemanggilan fungsi dan rantai alat | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol dengan transport stdio | `SimpleMcpTest.java` | ## Menjalankan Tes -**Jalankan semua tes dari direktori root:** +**Jalankan semua tes dari root:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Jalankan kelas tes tunggal:** +**Jalankan satu kelas tes:** **Bash:** ```bash @@ -91,7 +90,7 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Jalankan metode tes spesifik:** +**Jalankan metode tes tertentu:** **Bash:** ```bash @@ -105,7 +104,7 @@ mvn --% test -Dtest=SimpleConversationTest#harusMempertahankanRiwayatPercakapan ## Menjalankan Tes di VS Code -Jika Anda menggunakan Visual Studio Code, Test Explorer menyediakan antarmuka grafis untuk menjalankan dan men-debug tes. +Jika Anda menggunakan Visual Studio Code, Test Explorer menyediakan antarmuka grafis untuk menjalankan dan debug tes. VS Code Test Explorer @@ -113,23 +112,23 @@ Jika Anda menggunakan Visual Studio Code, Test Explorer menyediakan antarmuka gr **Untuk menjalankan tes di VS Code:** -1. Buka Test Explorer dengan mengklik ikon tabung kimia di Activity Bar +1. Buka Test Explorer dengan mengklik ikon tabung di Bar Aktivitas 2. Perluas pohon tes untuk melihat semua modul dan kelas tes -3. Klik tombol play di samping tes apa pun untuk menjalankannya secara individual -4. Klik "Run All Tests" untuk menjalankan seluruh suite -5. Klik kanan pada tes apa pun dan pilih "Debug Test" untuk menetapkan breakpoint dan menelusuri kode +3. Klik tombol putar di samping tes apa pun untuk menjalankannya secara individual +4. Klik "Run All Tests" untuk menjalankan seluruh rangkaian +5. Klik kanan tes mana pun dan pilih "Debug Test" untuk menetapkan breakpoint dan menelusuri kode -Test Explorer menampilkan tanda centang hijau untuk tes yang lulus dan menyediakan pesan kegagalan mendetail saat tes gagal. +Test Explorer menunjukkan tanda centang hijau untuk tes yang berhasil dan memberikan pesan kegagalan rinci ketika tes gagal. -## Pola Pengujian +## Polapola Pengujian -### Pola 1: Menguji Template Prompt +### Polapola 1: Menguji Template Prompt -Pola paling sederhana menguji template prompt tanpa memanggil model AI. Anda memverifikasi bahwa substitusi variabel bekerja dengan benar dan prompt diformat sesuai harapan. +Polapola paling sederhana menguji template prompt tanpa memanggil model AI apapun. Anda memverifikasi bahwa penggantian variabel bekerja dengan benar dan prompt diformat sesuai yang diharapkan. Pengujian Template Prompt -*Pengujian template prompt menunjukkan alur substitusi variabel: template dengan placeholder → nilai diterapkan → output diformat diverifikasi* +*Pengujian template prompt menunjukkan alur penggantian variabel: template dengan placeholder → nilai diterapkan → output yang diformat diverifikasi* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Tes ini berada di `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Polapola ini memverifikasi bahwa penggantian variabel bekerja dengan benar dan prompt diformat sesuai harapan — tanpa kunci API atau pemanggilan model. -**Jalankan:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#pengujianFormatTemplatPrompt -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#ujiFormatTemplatePrompt -``` - -### Pola 2: Mocking Model Bahasa +### Polapola 2: Mocking Model Bahasa -Saat menguji logika percakapan, gunakan Mockito untuk membuat model palsu yang mengembalikan respons yang sudah ditentukan. Ini membuat tes cepat, gratis, dan deterministik. +Saat menguji logika percakapan, gunakan Mockito untuk membuat model palsu yang mengembalikan respons yang telah ditentukan. Ini membuat tes cepat, gratis, dan deterministik. Perbandingan Mock vs API Asli -*Perbandingan yang menunjukkan mengapa mock lebih disukai untuk pengujian: cepat, gratis, deterministik, dan tidak memerlukan kunci API* +*Perbandingan yang menunjukkan alasan mock lebih disukai untuk pengujian: cepat, gratis, deterministik, dan tidak membutuhkan kunci API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Pola ini muncul di `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock memastikan perilaku konsisten sehingga Anda dapat memverifikasi pengelolaan memori berfungsi dengan benar. +Polapola ini muncul di `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock memastikan perilaku konsisten sehingga Anda dapat memverifikasi pengelolaan memori bekerja dengan benar. -### Pola 3: Menguji Isolasi Percakapan +### Polapola 3: Menguji Isolasi Percakapan -Memori percakapan harus menjaga beberapa pengguna tetap terpisah. Tes ini memverifikasi bahwa percakapan tidak mencampur konteks. +Memori percakapan harus menjaga beberapa pengguna terpisah. Tes ini memverifikasi bahwa percakapan tidak mencampurkan konteks. Isolasi Percakapan -*Pengujian isolasi percakapan menunjukkan penyimpanan memori terpisah untuk pengguna berbeda agar konteks tidak tercampur* +*Pengujian isolasi percakapan menunjukkan penyimpanan memori terpisah untuk pengguna berbeda agar mencegah pencampuran konteks* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Setiap percakapan mempertahankan riwayat independennya sendiri. Dalam sistem produksi, isolasi ini sangat penting untuk aplikasi multi-pengguna. +Setiap percakapan mempertahankan riwayat independennya sendiri. Dalam sistem produksi, isolasi ini penting untuk aplikasi multi-pengguna. -### Pola 4: Menguji Alat Secara Mandiri +### Polapola 4: Menguji Alat Secara Mandiri -Alat adalah fungsi yang dapat dipanggil AI. Uji langsung untuk memastikan alat berfungsi dengan benar tanpa bergantung pada keputusan AI. +Alat adalah fungsi yang dapat dipanggil AI. Uji alat tersebut langsung untuk memastikan mereka bekerja dengan benar terlepas dari keputusan AI. Pengujian Alat -*Pengujian alat secara mandiri memperlihatkan eksekusi alat mock tanpa panggilan AI untuk memverifikasi logika bisnis* +*Pengujian alat secara mandiri menunjukkan eksekusi alat mock tanpa panggilan AI untuk memverifikasi logika bisnis* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Tes ini dari `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` memvalidasi logika alat tanpa keterlibatan AI. Contoh chaining menunjukkan bagaimana output alat satu menjadi input alat lain. +Tes ini dari `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` memvalidasi logika alat tanpa keterlibatan AI. Contoh chaining menunjukkan bagaimana output satu alat menjadi input alat lain. -### Pola 5: Pengujian RAG In-Memory +### Polapola 5: Pengujian RAG Dalam Memori -Sistem RAG biasanya memerlukan basis data vektor dan layanan embedding. Pola in-memory memungkinkan pengujian alur lengkap tanpa ketergantungan eksternal. +Sistem RAG secara tradisional memerlukan database vektor dan layanan embedding. Polapola dalam memori memungkinkan Anda menguji seluruh pipeline tanpa ketergantungan eksternal. -Pengujian RAG In-Memory +Pengujian RAG Dalam Memori -*Alur kerja pengujian RAG in-memory menunjukkan parsing dokumen, penyimpanan embedding, dan pencarian kemiripan tanpa memerlukan database* +*Alur kerja pengujian RAG dalam memori memperlihatkan parsing dokumen, penyimpanan embedding, dan pencarian kemiripan tanpa memerlukan database* ```java @Test @@ -306,11 +293,11 @@ void testProcessTextDocument() { } ``` -Tes ini dari `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` membuat dokumen di memori dan memverifikasi pemisahan chunk dan penanganan metadata. +Tes ini dari `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` membuat dokumen dalam memori dan memverifikasi teknik pemecahan dan penanganan metadata. -### Pola 6: Pengujian Integrasi MCP +### Polapola 6: Pengujian Integrasi MCP -Modul MCP menguji integrasi Model Context Protocol menggunakan transportasi stdio. Tes ini memverifikasi aplikasi Anda dapat memunculkan dan berkomunikasi dengan server MCP sebagai subprocess. +Modul MCP menguji integrasi Model Context Protocol menggunakan transport stdio. Tes ini memverifikasi aplikasi Anda dapat menjalankan dan berkomunikasi dengan server MCP sebagai subprocess. Tes di `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` memvalidasi perilaku klien MCP. @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## Filosofi Pengujian -Uji kode Anda, bukan AI-nya. Tes Anda harus memvalidasi kode yang Anda tulis dengan memeriksa bagaimana prompt dibuat, bagaimana memori dikelola, dan bagaimana alat dieksekusi. Respons AI bervariasi dan tidak boleh menjadi bagian dari pernyataan tes. Tanyakan pada diri Anda apakah template prompt Anda menggantikan variabel dengan benar, bukan apakah AI memberikan jawaban yang benar. +Uji kode Anda, bukan AI. Tes Anda harus memverifikasi kode yang Anda tulis dengan memeriksa bagaimana prompt dibangun, bagaimana memori dikelola, dan bagaimana alat dijalankan. Respons AI bervariasi dan tidak seharusnya menjadi bagian dari asersi tes. Tanyakan pada diri sendiri apakah template prompt Anda mengganti variabel dengan benar, bukan apakah AI memberikan jawaban yang tepat. -Gunakan mock untuk model bahasa. Mereka adalah dependensi eksternal yang lambat, mahal, dan tidak deterministik. Mock membuat tes cepat dengan waktu mili-detik daripada detik, gratis tanpa biaya API, dan deterministik dengan hasil yang sama setiap kali. +Gunakan mock untuk model bahasa. Mereka adalah dependensi eksternal yang lambat, mahal, dan tidak deterministik. Mock membuat tes cepat dengan millisecond bukan detik, gratis tanpa biaya API, dan deterministik dengan hasil yang sama setiap kali. -Jaga tes agar tetap independen. Setiap tes harus menyiapkan datanya sendiri, tidak bergantung pada tes lain, dan membersihkan setelahnya. Tes harus lulus terlepas dari urutan eksekusi. +Jaga tes agar mandiri. Setiap tes harus menyiapkan data sendiri, tidak bergantung pada tes lain, dan membersihkan dirinya sendiri. Tes harus berhasil terlepas dari urutan eksekusi. -Uji kasus tepi di luar jalur bahagia. Coba input kosong, input sangat besar, karakter khusus, parameter tidak valid, dan kondisi batas. Ini sering mengungkap bug yang tidak tampak pada penggunaan biasa. +Uji kasus tepi di luar jalur senang. Coba input kosong, input sangat besar, karakter khusus, parameter tidak valid, dan kondisi batas. Ini sering mengungkap bug yang tidak diketahui dalam penggunaan normal. -Gunakan nama yang deskriptif. Bandingkan `shouldMaintainConversationHistoryAcrossMultipleMessages()` dengan `test1()`. Yang pertama memberi tahu Anda persis apa yang diuji, membuat debugging kegagalan jauh lebih mudah. +Gunakan nama deskriptif. Bandingkan `shouldMaintainConversationHistoryAcrossMultipleMessages()` dengan `test1()`. Yang pertama memberi tahu Anda tepat apa yang diuji, membuat debugging kegagalan jauh lebih mudah. ## Langkah Selanjutnya -Sekarang Anda memahami pola pengujian, gali lebih dalam setiap modul: +Sekarang Anda memahami pola pengujian, dalami setiap modul: -- **[00 - Mulai Cepat](../00-quick-start/README.md)** - Mulai dengan dasar template prompt -- **[01 - Pengantar](../01-introduction/README.md)** - Pelajari pengelolaan memori percakapan -- **[02 - Rekayasa Prompt](../02-prompt-engineering/README.md)** - Kuasai pola pemicu GPT-5.2 +- **[01 - Pengenalan](../01-introduction/README.md)** - Pelajari manajemen memori percakapan +- **[02 - Rekayasa Prompt](../02/prompt-engineering/README.md)** - Kuasai polapola prompting GPT-5.2 - **[03 - RAG](../03-rag/README.md)** - Bangun sistem retrieval-augmented generation -- **[04 - Alat](../04-tools/README.md)** - Implementasikan pemanggilan fungsi dan rangkaian alat +- **[04 - Alat](../04-tools/README.md)** - Implementasikan pemanggilan fungsi dan rantai alat - **[05 - MCP](../05-mcp/README.md)** - Integrasikan Model Context Protocol -README setiap modul menyediakan penjelasan mendetail mengenai konsep yang diuji di sini. +README setiap modul menyediakan penjelasan terperinci tentang konsep yang diuji di sini. --- @@ -358,6 +344,6 @@ README setiap modul menyediakan penjelasan mendetail mengenai konsep yang diuji --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan layanan penerjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berusaha untuk akurasi, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau kekeliruan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah dan utama. Untuk informasi yang bersifat penting, disarankan menggunakan jasa penerjemah profesional manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau kesalahan interpretasi yang timbul dari penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Meskipun kami berupaya untuk mencapai akurasi, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/it/.co-op-translator.json b/translations/it/.co-op-translator.json index de388851e..d3d727300 100644 --- a/translations/it/.co-op-translator.json +++ b/translations/it/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "it" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T21:29:46+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T10:32:55+00:00", "source_file": "01-introduction/README.md", "language_code": "it" }, @@ -18,20 +18,20 @@ "language_code": "it" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T21:31:57+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T10:28:09+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "it" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T21:33:23+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T10:32:00+00:00", "source_file": "03-rag/README.md", "language_code": "it" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:48:56+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T10:30:32+00:00", "source_file": "04-tools/README.md", "language_code": "it" }, @@ -54,8 +54,8 @@ "language_code": "it" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:03:18+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T10:25:08+00:00", "source_file": "README.md", "language_code": "it" }, @@ -72,14 +72,14 @@ "language_code": "it" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T21:36:30+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T10:28:42+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "it" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T21:37:11+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T10:29:20+00:00", "source_file": "docs/TESTING.md", "language_code": "it" } diff --git a/translations/it/00-quick-start/README.md b/translations/it/00-quick-start/README.md deleted file mode 100644 index b98b93e59..000000000 --- a/translations/it/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modulo 00: Avvio Rapido - -## Indice - -- [Introduzione](../../../00-quick-start) -- [Cos'è LangChain4j?](../../../00-quick-start) -- [Dipendenze LangChain4j](../../../00-quick-start) -- [Prerequisiti](../../../00-quick-start) -- [Configurazione](../../../00-quick-start) - - [1. Ottieni il tuo token GitHub](../../../00-quick-start) - - [2. Imposta il tuo token](../../../00-quick-start) -- [Esegui gli esempi](../../../00-quick-start) - - [1. Chat di base](../../../00-quick-start) - - [2. Modelli di prompt](../../../00-quick-start) - - [3. Chiamata di funzioni](../../../00-quick-start) - - [4. Domande e risposte sui documenti (Easy RAG)](../../../00-quick-start) - - [5. AI responsabile](../../../00-quick-start) -- [Cosa mostra ogni esempio](../../../00-quick-start) -- [Passi successivi](../../../00-quick-start) -- [Risoluzione dei problemi](../../../00-quick-start) - -## Introduzione - -Questo avvio rapido è pensato per farti partire rapidamente con LangChain4j. Copre le basi assolute per costruire applicazioni AI con LangChain4j e GitHub Models. Nei moduli successivi passerai ad Azure OpenAI e GPT-5.2 e approfondirai ogni concetto. - -## Cos'è LangChain4j? - -LangChain4j è una libreria Java che semplifica la costruzione di applicazioni AI. Invece di gestire client HTTP e parsing JSON, si lavora con API Java pulite. - -La "catena" in LangChain si riferisce al concatenamento di più componenti - potresti concatenare un prompt a un modello a un parser, o concatenare più chiamate AI dove un output alimenta il successivo input. Questo avvio rapido si concentra sui fondamenti prima di esplorare catene più complesse. - -Concetto di concatenamento LangChain4j - -*Componenti concatenati in LangChain4j - blocchi costitutivi che si connettono per creare potenti flussi di lavoro AI* - -Utilizzeremo tre componenti principali: - -**ChatModel** - Interfaccia per interazioni con il modello AI. Chiamare `model.chat("prompt")` e ottenere una stringa di risposta. Usiamo `OpenAiOfficialChatModel` che funziona con endpoint compatibili OpenAI come GitHub Models. - -**AiServices** - Crea interfacce di servizi AI tipizzate. Definisci metodi, annotali con `@Tool` e LangChain4j gestisce l'orchestrazione. L'AI chiama automaticamente i tuoi metodi Java quando necessario. - -**MessageWindowChatMemory** - Mantiene la cronologia della conversazione. Senza di essa, ogni richiesta è indipendente. Con essa, l'AI ricorda i messaggi precedenti e mantiene il contesto attraverso più turni. - -Architettura LangChain4j - -*Architettura LangChain4j - componenti core che lavorano insieme per alimentare le tue applicazioni AI* - -## Dipendenze LangChain4j - -Questo avvio rapido utilizza tre dipendenze Maven nel [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Il modulo `langchain4j-open-ai-official` fornisce la classe `OpenAiOfficialChatModel` che si connette ad API compatibili OpenAI. GitHub Models usa lo stesso formato API, quindi non serve un adattatore speciale - basta puntare la URL base a `https://models.github.ai/inference`. - -Il modulo `langchain4j-easy-rag` offre divisione automatica dei documenti, embedding e retrieval così da poter costruire applicazioni RAG senza configurare manualmente ogni passaggio. - -## Prerequisiti - -**Usi il Dev Container?** Java e Maven sono già installati. Ti serve solo un Personal Access Token GitHub. - -**Sviluppo locale:** -- Java 21+, Maven 3.9+ -- Personal Access Token GitHub (istruzioni sotto) - -> **Nota:** Questo modulo usa `gpt-4.1-nano` da GitHub Models. Non modificare il nome del modello nel codice - è configurato per funzionare con i modelli disponibili su GitHub. - -## Configurazione - -### 1. Ottieni il tuo token GitHub - -1. Vai su [Impostazioni GitHub → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Clicca "Genera nuovo token" -3. Dai un nome descrittivo (es. "Demo LangChain4j") -4. Imposta scadenza (consigliato 7 giorni) -5. Sotto "Permessi account", trova "Models" e imposta su "Sola lettura" -6. Clicca "Genera token" -7. Copia e salva il token - non sarà più visibile - -### 2. Imposta il tuo token - -**Opzione 1: Usare VS Code (Consigliato)** - -Se usi VS Code, aggiungi il token nel file `.env` nella radice del progetto: - -Se il file `.env` non esiste, copia `.env.example` in `.env` o crea un nuovo `.env` nella radice del progetto. - -**Esempio file `.env`:** -```bash -# In /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Poi basta cliccare col destro su un qualsiasi file demo (es. `BasicChatDemo.java`) nell'Explorer e scegliere **"Run Java"** oppure usare le configurazioni di avvio dal pannello Run and Debug. - -**Opzione 2: Usare il Terminale** - -Imposta il token come variabile d’ambiente: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Esegui gli esempi - -**Usando VS Code:** Basta cliccare col tasto destro un file demo nell'Explorer e scegliere **"Run Java"**, oppure usare le configurazioni dal pannello Run and Debug (assicurati prima di avere aggiunto il token nel file `.env`). - -**Usando Maven:** In alternativa, esegui da linea di comando: - -### 1. Chat di base - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Modelli di prompt - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Mostra prompting zero-shot, few-shot, chain-of-thought e basato su ruoli. - -### 3. Chiamata di funzioni - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -L’AI chiama automaticamente i tuoi metodi Java quando necessario. - -### 4. Domande e risposte sui documenti (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Fai domande sui tuoi documenti usando Easy RAG con embedding e retrieval automatici. - -### 5. AI responsabile - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Vedi come i filtri di sicurezza AI bloccano contenuti dannosi. - -## Cosa mostra ogni esempio - -**Chat di base** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Inizia qui per vedere LangChain4j nel suo aspetto più semplice. Creerai un `OpenAiOfficialChatModel`, invierai un prompt con `.chat()`, e otterrai una risposta. Questo dimostra la base: come inizializzare modelli con endpoint e chiavi API personalizzate. Una volta compreso questo schema, tutto il resto si basa su di esso. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) e chiedi: -> - "Come passo da GitHub Models ad Azure OpenAI in questo codice?" -> - "Quali altri parametri posso configurare in OpenAiOfficialChatModel.builder()?" -> - "Come aggiungo risposte in streaming invece di aspettare la risposta completa?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Ora che sai come parlare con un modello, esploriamo cosa gli dici. Questa demo usa la stessa configurazione modello ma mostra cinque diversi modelli di prompt. Prova prompt zero-shot per istruzioni dirette, few-shot che imparano dagli esempi, chain-of-thought che mostrano i passaggi di ragionamento, e prompt basati su ruoli che impostano il contesto. Vedrai come lo stesso modello dà risultati molto diversi in base a come formuli la richiesta. - -La demo mostra anche template di prompt, un modo potente per creare prompt riutilizzabili con variabili. -L’esempio sotto mostra un prompt che usa il LangChain4j `PromptTemplate` per riempire variabili. L’AI risponderà basandosi sulla destinazione e attività fornita. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) e chiedi: -> - "Qual è la differenza tra zero-shot e few-shot prompting, e quando dovrei usare ciascuno?" -> - "Come influisce il parametro temperature sulle risposte del modello?" -> - "Quali tecniche ci sono per prevenire attacchi di injection nei prompt in produzione?" -> - "Come posso creare oggetti PromptTemplate riutilizzabili per modelli comuni?" - -**Integrazione di strumenti** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Qui LangChain4j diventa potente. Userai `AiServices` per creare un assistente AI che chiama i tuoi metodi Java. Basta annotare metodi con `@Tool("descrizione")` e LangChain4j fa il resto - l’AI decide automaticamente quando usare ogni strumento in base a cosa chiede l’utente. Questo dimostra la chiamata di funzioni, una tecnica chiave per costruire AI che può agire, non solo rispondere a domande. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) e chiedi: -> - "Come funziona l’annotazione @Tool e cosa fa LangChain4j dietro le quinte?" -> - "L’AI può chiamare più strumenti in sequenza per risolvere problemi complessi?" -> - "Cosa succede se uno strumento genera un’eccezione - come gestisco gli errori?" -> - "Come integrazione una vera API invece di questo esempio calcolatrice?" - -**Domande e risposte sui documenti (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Qui vedrai RAG (retrieval-augmented generation) usando l’approccio "Easy RAG" di LangChain4j. I documenti sono caricati, automaticamente divisi e embedded in una memoria, poi un content retriever fornisce i pezzi rilevanti all’AI al momento della richiesta. L’AI risponde basandosi sui tuoi documenti, non sulla sua conoscenza generale. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) e chiedi: -> - "Come RAG previene le allucinazioni AI rispetto all’uso dei dati di training del modello?" -> - "Qual è la differenza tra questo approccio facile e una pipeline RAG personalizzata?" -> - "Come farei a scalare questo per gestire più documenti o basi di conoscenza più grandi?" - -**AI responsabile** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Costruisci sicurezza AI con difesa in profondità. Questa demo mostra due livelli di protezione che lavorano insieme: - -**Parte 1: LangChain4j Input Guardrails** - Blocca prompt pericolosi prima che raggiungano il LLM. Crea guardrail personalizzati che cercano parole chiave o modelli vietati. Questi girano nel tuo codice, quindi sono veloci e gratuiti. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Parte 2: Filtri di sicurezza del provider** - GitHub Models ha filtri integrati che intercettano quello che potrebbero perdere i tuoi guardrail. Vedrai blocchi rigidi (errori HTTP 400) per violazioni gravi e rifiuti morbidi dove l’AI declina educatamente. - -> **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) e chiedi: -> - "Cos’è InputGuardrail e come creane uno mio?" -> - "Qual è la differenza tra blocco rigido e rifiuto morbido?" -> - "Perché usare insieme guardrail e filtri provider?" - -## Passi successivi - -**Modulo Successivo:** [01-introduction - Introduzione a LangChain4j](../01-introduction/README.md) - ---- - -**Navigazione:** [← Indietro al Principale](../README.md) | [Prossimo: Modulo 01 - Introduzione →](../01-introduction/README.md) - ---- - -## Risoluzione dei problemi - -### Prima Compilazione Maven - -**Problema**: `mvn clean compile` o `mvn package` iniziali richiedono molto tempo (10-15 minuti) - -**Causa**: Maven deve scaricare tutte le dipendenze del progetto (Spring Boot, librerie LangChain4j, SDK Azure, ecc.) alla prima compilazione. - -**Soluzione**: Comportamento normale. Le compilazioni successive saranno molto più rapide perché le dipendenze sono memorizzate in cache localmente. Il tempo di download dipende dalla velocità della tua rete. - -### Sintassi comando Maven in PowerShell - -**Problema**: I comandi Maven falliscono con errore `Unknown lifecycle phase ".mainClass=..."` -**Causa**: PowerShell interpreta `=` come operatore di assegnazione di variabile, interrompendo la sintassi delle proprietà Maven - -**Soluzione**: Usa l'operatore di stop-parsing `--%` prima del comando Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -L'operatore `--%` indica a PowerShell di passare letteralmente tutti gli argomenti rimanenti a Maven senza interpretazione. - -### Visualizzazione Emoji in Windows PowerShell - -**Problema**: Le risposte AI mostrano caratteri strani (es. `????` o `â??`) invece delle emoji in PowerShell - -**Causa**: La codifica predefinita di PowerShell non supporta le emoji UTF-8 - -**Soluzione**: Esegui questo comando prima di eseguire le applicazioni Java: -```cmd -chcp 65001 -``` - -Questo forza la codifica UTF-8 nel terminale. In alternativa, usa Windows Terminal che ha un supporto Unicode migliore. - -### Debug delle chiamate API - -**Problema**: Errori di autenticazione, limiti di frequenza o risposte inaspettate dal modello AI - -**Soluzione**: Gli esempi includono `.logRequests(true)` e `.logResponses(true)` per mostrare le chiamate API nella console. Questo aiuta a risolvere errori di autenticazione, limiti di frequenza o risposte inaspettate. Rimuovi queste opzioni in produzione per ridurre il rumore nei log. - ---- - - -**Avvertenza**: -Questo documento è stato tradotto utilizzando il servizio di traduzione automatica [Co-op Translator](https://github.com/Azure/co-op-translator). Pur facendo del nostro meglio per garantire la precisione, si prega di notare che le traduzioni automatiche possono contenere errori o inesattezze. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale umana. Non ci assumiamo alcuna responsabilità per fraintendimenti o interpretazioni errate derivanti dall’uso di questa traduzione. - \ No newline at end of file diff --git a/translations/it/01-introduction/README.md b/translations/it/01-introduction/README.md index 4eb8641ff..10eeb3c9e 100644 --- a/translations/it/01-introduction/README.md +++ b/translations/it/01-introduction/README.md @@ -2,19 +2,19 @@ ## Indice -- [Video Dimostrativo](../../../01-introduction) -- [Cosa Imparerai](../../../01-introduction) -- [Prerequisiti](../../../01-introduction) -- [Comprendere il Problema Principale](../../../01-introduction) -- [Comprendere i Token](../../../01-introduction) -- [Come Funziona la Memoria](../../../01-introduction) -- [Come Viene Usato LangChain4j](../../../01-introduction) -- [Distribuire l'Infrastruttura Azure OpenAI](../../../01-introduction) -- [Eseguire l'Applicazione Localmente](../../../01-introduction) -- [Usare l'Applicazione](../../../01-introduction) - - [Chat Senza Stato (Pannello Sinistro)](../../../01-introduction) - - [Chat Con Stato (Pannello Destro)](../../../01-introduction) -- [Prossimi Passi](../../../01-introduction) +- [Video Dimostrativo](#video-dimostrativo) +- [Cosa Imparerai](#cosa-imparerai) +- [Prerequisiti](#prerequisiti) +- [Comprendere il Problema Centrale](#comprendere-il-problema-centrale) +- [Comprendere i Token](#comprendere-i-token) +- [Come Funziona la Memoria](#come-funziona-la-memoria) +- [Come Questo Usa LangChain4j](#come-questo-usa-langchain4j) +- [Distribuire l'Infrastruttura Azure OpenAI](#distribuire-linfrastruttura-azure-openai) +- [Eseguire l'Applicazione Localmente](#eseguire-lapplicazione-localmente) +- [Usare l'Applicazione](#usare-lapplicazione) + - [Chat Stateless (Pannello Sinistro)](#chat-stateless-pannello-sinistro) + - [Chat Stateful (Pannello Destro)](#chat-stateful-pannello-destro) +- [Passi Successivi](#passi-successivi) ## Video Dimostrativo @@ -24,62 +24,62 @@ Guarda questa sessione live che spiega come iniziare con questo modulo: ## Cosa Imparerai -Nel quick start, hai usato i Modelli GitHub per inviare prompt, chiamare strumenti, costruire una pipeline RAG e testare le protezioni. Quelle demo hanno mostrato cosa è possibile — ora passiamo ad Azure OpenAI e GPT-5.2 e iniziamo a costruire applicazioni in stile produzione. Questo modulo si concentra sull'AI conversazionale che ricorda il contesto e mantiene lo stato — i concetti che quelle demo del quick start usavano dietro le quinte ma non spiegavano. +Questo è il tuo punto di partenza con LangChain4j e Azure OpenAI. Iniziamo con i fondamenti e cominciamo a costruire applicazioni in stile produzione. Questo modulo si concentra sull'intelligenza artificiale conversazionale che ricorda il contesto e mantiene lo stato — i concetti fondamentali su cui si basano tutti i moduli successivi. -Useremo GPT-5.2 di Azure OpenAI in tutta la guida perché le sue capacità avanzate di ragionamento rendono il comportamento dei diversi pattern più evidente. Quando aggiungi la memoria, vedrai chiaramente la differenza. Questo rende più facile capire cosa ogni componente apporta alla tua applicazione. +Useremo GPT-5.2 di Azure OpenAI per tutta la guida perché le sue capacità avanzate di ragionamento rendono più evidente il comportamento dei diversi pattern. Quando aggiungi la memoria, vedrai chiaramente la differenza. Questo rende più facile capire cosa ogni componente porta alla tua applicazione. -Costruirai un'applicazione che dimostra entrambi i pattern: +Costruirai un’applicazione che dimostra entrambi i pattern: -**Chat Senza Stato** - Ogni richiesta è indipendente. Il modello non ha memoria dei messaggi precedenti. Questo è il pattern usato nel quick start. +**Chat Stateless** - Ogni richiesta è indipendente. Il modello non ha memoria dei messaggi precedenti. Questo è il punto di partenza più semplice. -**Conversazione Con Stato** - Ogni richiesta include la cronologia della conversazione. Il modello mantiene il contesto su più turni. Questo è ciò che le applicazioni di produzione richiedono. +**Conversazione Stateful** - Ogni richiesta include la cronologia della conversazione. Il modello mantiene il contesto su più turni. Questo è ciò di cui hanno bisogno le applicazioni di produzione. ## Prerequisiti -- Sottoscrizione Azure con accesso ad Azure OpenAI +- Sottoscrizione Azure con accesso Azure OpenAI - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) > **Nota:** Java, Maven, Azure CLI e Azure Developer CLI (azd) sono preinstallati nel devcontainer fornito. -> **Nota:** Questo modulo usa GPT-5.2 su Azure OpenAI. La distribuzione è configurata automaticamente tramite `azd up` - non modificare il nome del modello nel codice. +> **Nota:** Questo modulo usa GPT-5.2 su Azure OpenAI. Il deployment è configurato automaticamente tramite `azd up` - non modificare il nome del modello nel codice. -## Comprendere il Problema Principale +## Comprendere il Problema Centrale -I modelli di linguaggio sono senza stato. Ogni chiamata API è indipendente. Se invii "Mi chiamo John" e poi chiedi "Come mi chiamo?", il modello non ha idea che tu ti sia appena presentato. Tratta ogni richiesta come se fosse la prima conversazione che hai mai avuto. +I modelli di linguaggio sono stateless. Ogni chiamata API è indipendente. Se invii "Mi chiamo John" e poi chiedi "Come mi chiamo?", il modello non ha idea che ti sei appena presentato. Tratta ogni richiesta come se fosse la prima conversazione che hai mai avuto. -Questo va bene per semplici Q&A ma è inutile per applicazioni reali. I bot del servizio clienti devono ricordare cosa hai detto loro. Gli assistenti personali hanno bisogno di contesto. Qualsiasi conversazione multi-turno richiede memoria. +Questo va bene per semplici Q&A ma è inutile per applicazioni reali. I bot di assistenza clienti devono ricordare cosa hai detto. Gli assistenti personali hanno bisogno di contesto. Qualsiasi conversazione multi-turno richiede memoria. -Il diagramma seguente mette a confronto i due approcci — a sinistra, una chiamata senza stato che dimentica il tuo nome; a destra, una chiamata con stato supportata da ChatMemory che lo ricorda. +Il diagramma seguente contrappone i due approcci — a sinistra, una chiamata stateless che dimentica il tuo nome; a destra, una chiamata stateful supportata da ChatMemory che lo ricorda. Stateless vs Stateful Conversations -*La differenza tra conversazioni senza stato (chiamate indipendenti) e con stato (consapevoli del contesto)* +*La differenza tra conversazioni stateless (chiamate indipendenti) e stateful (consapevoli del contesto)* ## Comprendere i Token -Prima di immergersi nelle conversazioni, è importante comprendere i token - le unità di base del testo che i modelli di linguaggio elaborano: +Prima di immergerci nelle conversazioni, è importante capire i token - le unità base di testo che i modelli di linguaggio elaborano: Token Explanation *Esempio di come il testo viene suddiviso in token - "I love AI!" diventa 4 unità di elaborazione separate* -I token sono il modo in cui i modelli AI misurano ed elaborano il testo. Parole, punteggiatura e persino spazi possono essere token. Il tuo modello ha un limite sul numero di token che può elaborare in una volta (400.000 per GPT-5.2, con fino a 272.000 token in input e 128.000 in output). Comprendere i token ti aiuta a gestire la lunghezza della conversazione e i costi. +I token sono come i modelli AI misurano ed elaborano il testo. Parole, punteggiatura e perfino spazi possono essere token. Il tuo modello ha un limite di quanti token può elaborare contemporaneamente (400.000 per GPT-5.2, con fino a 272.000 token in input e 128.000 in output). Capire i token ti aiuta a gestire la lunghezza della conversazione e i costi. ## Come Funziona la Memoria -La memoria nella chat risolve il problema dello stato mantenendo la cronologia della conversazione. Prima di inviare la tua richiesta al modello, il framework antepone i messaggi precedenti rilevanti. Quando chiedi "Come mi chiamo?", il sistema in realtà invia l'intera cronologia della conversazione, permettendo al modello di vedere che hai detto "Mi chiamo John" in precedenza. +La memoria chat risolve il problema stateless mantenendo la cronologia della conversazione. Prima di inviare la tua richiesta al modello, il framework antepone i messaggi precedenti rilevanti. Quando chiedi "Come mi chiamo?", il sistema invia in realtà tutta la cronologia della conversazione, permettendo al modello di vedere che prima hai detto "Mi chiamo John." -LangChain4j fornisce implementazioni di memoria che gestiscono questo automaticamente. Scegli quanti messaggi conservare e il framework gestisce la finestra di contesto. Il diagramma sotto mostra come MessageWindowChatMemory mantiene una finestra scorrevole dei messaggi recenti. +LangChain4j fornisce implementazioni di memoria che gestiscono questo automaticamente. Tu scegli quanti messaggi conservare e il framework gestisce la finestra di contesto. Il diagramma sotto mostra come MessageWindowChatMemory mantiene una finestra scorrevole dei messaggi recenti. Memory Window Concept -*MessageWindowChatMemory mantiene una finestra scorrevole dei messaggi recenti, eliminandone automaticamente i più vecchi* +*MessageWindowChatMemory mantiene una finestra scorrevole dei messaggi recenti, scartando automaticamente quelli più vecchi* -## Come Viene Usato LangChain4j +## Come Questo Usa LangChain4j -Questo modulo estende il quick start integrando Spring Boot e aggiungendo la memoria nella conversazione. Ecco come si incastrano i pezzi: +Questo modulo integra Spring Boot e aggiunge la memoria conversazionale. Ecco come si incastrano i componenti: **Dipendenze** - Aggiungi due librerie LangChain4j: @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Il builder legge le credenziali dalle variabili d'ambiente impostate da `azd up`. Impostare `baseUrl` al tuo endpoint Azure fa funzionare il client OpenAI con Azure OpenAI. +Il builder legge le credenziali dalle variabili d'ambiente impostate da `azd up`. Impostare `baseUrl` al tuo endpoint Azure permette al client OpenAI di funzionare con Azure OpenAI. -**Memoria della Conversazione** - Traccia la cronologia chat con MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Memoria Conversazione** - Traccia la cronologia chat con MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Crea la memoria con `withMaxMessages(10)` per tenere gli ultimi 10 messaggi. Aggiungi messaggi utente e AI con wrapper tipizzati: `UserMessage.from(text)` e `AiMessage.from(text)`. Recupera la cronologia con `memory.messages()` e inviala al modello. Il servizio memorizza istanze di memoria separate per ID conversazione, consentendo a più utenti di chattare contemporaneamente. +Crea la memoria con `withMaxMessages(10)` per conservare gli ultimi 10 messaggi. Aggiungi messaggi utente e AI con wrapper tipizzati: `UserMessage.from(text)` e `AiMessage.from(text)`. Recupera la cronologia con `memory.messages()` e inviala al modello. Il servizio conserva istanze di memoria separate per ogni ID conversazione, permettendo a più utenti di chattare contemporaneamente. > **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) e chiedi: -> - "Come decide MessageWindowChatMemory quali messaggi eliminare quando la finestra è piena?" -> - "Posso implementare una memoria personalizzata usando un database invece che in memoria?" -> - "Come potrei aggiungere una sintesi per comprimere la vecchia cronologia della conversazione?" +> - "Come decide MessageWindowChatMemory quali messaggi scartare quando la finestra è piena?" +> - "Posso implementare uno storage di memoria personalizzato usando un database invece della memoria in RAM?" +> - "Come potrei aggiungere il sommario per comprimere la vecchia cronologia della conversazione?" -L'endpoint chat senza stato salta completamente la memoria - usa soltanto `chatModel.chat(prompt)` come nel quick start. L'endpoint con stato aggiunge messaggi alla memoria, recupera la cronologia e include quel contesto ad ogni richiesta. Stessa configurazione del modello, pattern differenti. +L’endpoint chat stateless salta completamente la memoria — usa solo `chatModel.chat(prompt)` come nel quick start. L’endpoint stateful aggiunge messaggi alla memoria, recupera la cronologia e include quel contesto ad ogni richiesta. Stessa configurazione modello, pattern diversi. ## Distribuire l'Infrastruttura Azure OpenAI @@ -144,19 +144,19 @@ azd up # Seleziona sottoscrizione e posizione (eastus2 consigliato) **PowerShell:** ```powershell cd 01-introduction -azd up # Seleziona l'abbonamento e la posizione (consigliato eastus2) +azd up # Seleziona sottoscrizione e posizione (consigliato eastus2) ``` -> **Nota:** Se riscontri un errore di timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), esegui semplicemente di nuovo `azd up`. Le risorse Azure potrebbero essere ancora in provisioning in background, e riprovare consente alla distribuzione di completarsi una volta che le risorse raggiungono uno stato terminale. +> **Nota:** Se incontri un errore di timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), esegui semplicemente di nuovo `azd up`. Le risorse Azure potrebbero ancora essere in fase di provisioning in background, e riprovare permette al deployment di completarsi una volta che le risorse raggiungono uno stato terminale. Questo farà: 1. Distribuire la risorsa Azure OpenAI con modelli GPT-5.2 e text-embedding-3-small -2. Generare automaticamente il file `.env` nella root del progetto con le credenziali -3. Impostare tutte le variabili di ambiente necessarie +2. Generare automaticamente il file `.env` nella radice del progetto con le credenziali +3. Configurare tutte le variabili d’ambiente richieste -**Problemi nella distribuzione?** Consulta il [README dell'Infrastruttura](infra/README.md) per una risoluzione dettagliata dei problemi inclusi conflitti di nomi di sottodomini, passaggi manuali di distribuzione tramite Azure Portal e linee guida sulla configurazione del modello. +**Hai problemi con il deployment?** Consulta il [README Infrastruttura](infra/README.md) per la risoluzione dettagliata dei problemi, inclusi conflitti di nome del sottodominio, passaggi manuali di deployment da Azure Portal e consigli per la configurazione del modello. -**Verifica che la distribuzione sia riuscita:** +**Verifica che il deployment sia riuscito:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Dovrebbe mostrare AZURE_OPENAI_ENDPOINT, API_KEY, ecc. Get-Content ..\.env # Dovrebbe mostrare AZURE_OPENAI_ENDPOINT, API_KEY, ecc. ``` -> **Nota:** Il comando `azd up` genera automaticamente il file `.env`. Se devi aggiornarlo dopo, puoi modificare direttamente il file `.env` oppure rigenerarlo eseguendo: +> **Nota:** Il comando `azd up` genera automaticamente il file `.env`. Se devi aggiornarlo in seguito, puoi modificare manualmente il file `.env` oppure rigenerarlo eseguendo: > > **Bash:** > ```bash @@ -184,9 +184,9 @@ Get-Content ..\.env # Dovrebbe mostrare AZURE_OPENAI_ENDPOINT, API_KEY, ecc. ## Eseguire l'Applicazione Localmente -**Verifica la distribuzione:** +**Verifica il deployment:** -Assicurati che il file `.env` esista nella directory root con le credenziali Azure. Esegui questo dalla directory del modulo (`01-introduction/`): +Assicurati che il file `.env` esista nella directory radice con le credenziali Azure. Esegui questo dal modulo (`01-introduction/`): **Bash:** ```bash @@ -200,21 +200,21 @@ Get-Content ..\.env # Dovrebbe mostrare AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Avvia le applicazioni:** -**Opzione 1: Usare Spring Boot Dashboard (Consigliato per utenti VS Code)** +**Opzione 1: Usare Spring Boot Dashboard (Raccomandato per utenti VS Code)** -Il dev container include l'estensione Spring Boot Dashboard, che fornisce un'interfaccia visiva per gestire tutte le applicazioni Spring Boot. La trovi nella Activity Bar sul lato sinistro di VS Code (cerca l'icona di Spring Boot). +Il dev container include l’estensione Spring Boot Dashboard, che offre un’interfaccia visiva per gestire tutte le applicazioni Spring Boot. La trovi nella Activity Bar a sinistra di VS Code (cerca l’icona Spring Boot). Dal Spring Boot Dashboard puoi: -- Vedere tutte le applicazioni Spring Boot disponibili nell'area di lavoro -- Avviare/arrestare applicazioni con un clic -- Visualizzare i log delle applicazioni in tempo reale +- Vedere tutte le applicazioni Spring Boot disponibili nell’area di lavoro +- Avviare/arrestare applicazioni con un solo click +- Visualizzare i log in tempo reale - Monitorare lo stato delle applicazioni -Clicca semplicemente il pulsante play accanto a "introduction" per avviare questo modulo, oppure avvia tutti i moduli insieme. +Basta cliccare sul pulsante play accanto a "introduction" per avviare questo modulo, o avviare tutti i moduli contemporaneamente. Spring Boot Dashboard -*Il Spring Boot Dashboard in VS Code — avvia, arresta e monitora tutti i moduli da un unico posto* +*Spring Boot Dashboard in VS Code — avvia, ferma e monitora tutti i moduli da un unico posto* **Opzione 2: Usare script shell** @@ -222,13 +222,13 @@ Avvia tutte le applicazioni web (moduli 01-04): **Bash:** ```bash -cd .. # Dalla directory root +cd .. # Dalla directory radice ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Dalla directory root +cd .. # Dalla directory radice .\start-all.ps1 ``` @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Entrambi gli script caricano automaticamente le variabili d'ambiente dal file `.env` della root e compileranno i JAR se non esistono. +Entrambi gli script caricano automaticamente le variabili d’ambiente dal file `.env` radice e compileranno i JAR se non esistono. -> **Nota:** Se preferisci compilare tutti i moduli manualmente prima di avviare: +> **Nota:** Se preferisci compilare manualmente tutti i moduli prima di avviare: > > **Bash:** > ```bash @@ -282,41 +282,41 @@ cd ..; .\stop-all.ps1 # Tutti i moduli ## Usare l'Applicazione -L'applicazione fornisce un'interfaccia web con due implementazioni di chat affiancate. +L'applicazione fornisce un’interfaccia web con due implementazioni di chat affiancate. Application Home Screen -*Dashboard che mostra entrambe le opzioni Simple Chat (senza stato) e Conversational Chat (con stato)* +*Dashboard che mostra le opzioni di Simple Chat (stateless) e Conversational Chat (stateful)* -### Chat Senza Stato (Pannello Sinistro) +### Chat Stateless (Pannello Sinistro) -Prova prima questa. Chiedi "Mi chiamo John" e poi subito dopo chiedi "Come mi chiamo?" Il modello non ricorderà perché ogni messaggio è indipendente. Questo dimostra il problema principale con l'integrazione base dei modelli di linguaggio - nessun contesto di conversazione. +Prova prima questa. Chiedi "Mi chiamo John" e poi subito dopo chiedi "Come mi chiamo?" Il modello non ricorderà perché ogni messaggio è indipendente. Questo dimostra il problema centrale dell’integrazione basica del modello di linguaggio - nessun contesto conversazionale. Stateless Chat Demo *L'AI non ricorda il tuo nome dal messaggio precedente* -### Chat Con Stato (Pannello Destro) +### Chat Stateful (Pannello Destro) -Ora prova la stessa sequenza qui. Chiedi "Mi chiamo John" e poi "Come mi chiamo?" Questa volta lo ricorda. La differenza è MessageWindowChatMemory - mantiene la cronologia della conversazione e la include ad ogni richiesta. Così funziona l'AI conversazionale in produzione. +Ora prova la stessa sequenza qui. Chiedi "Mi chiamo John" e poi "Come mi chiamo?" Questa volta lo ricorda. La differenza è MessageWindowChatMemory - mantiene la cronologia della conversazione e la include in ogni richiesta. Così funziona l’intelligenza artificiale conversazionale in produzione. Stateful Chat Demo -*L'AI ricorda il tuo nome da prima nella conversazione* +*L'AI ricorda il tuo nome detto in precedenza nella conversazione* -Entrambi i pannelli usano lo stesso modello GPT-5.2. L'unica differenza è la memoria. Questo rende chiaro cosa la memoria apporta alla tua applicazione e perché è essenziale per casi d'uso reali. +Entrambi i pannelli usano lo stesso modello GPT-5.2. L’unica differenza è la memoria. Questo rende chiaro cosa la memoria porta alla tua applicazione e perché è fondamentale per casi d’uso reali. -## Prossimi Passi +## Passi Successivi -**Modulo Successivo:** [02-prompt-engineering - Prompt Engineering con GPT-5.2](../02-prompt-engineering/README.md) +**Modulo Successivo:** [02-prompt-engineering - Ingegneria del Prompt con GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigazione:** [← Precedente: Modulo 00 - Quick Start](../00-quick-start/README.md) | [Indietro al Principale](../README.md) | [Successivo: Modulo 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigazione:** [← Torna al Principale](../README.md) | [Avanti: Modulo 02 - Ingegneria del Prompt →](../02-prompt-engineering/README.md) --- -**Avvertenza**: -Questo documento è stato tradotto utilizzando il servizio di traduzione automatica [Co-op Translator](https://github.com/Azure/co-op-translator). Pur facendo del nostro meglio per garantire l’accuratezza, si prega di considerare che le traduzioni automatiche possono contenere errori o inesattezze. Il documento originale nella sua lingua natale deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un traduttore umano. Non siamo responsabili per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. +**Disclaimer**: +Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire la precisione, si prega di notare che le traduzioni automatizzate possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un essere umano. Non siamo responsabili per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. \ No newline at end of file diff --git a/translations/it/02-prompt-engineering/README.md b/translations/it/02-prompt-engineering/README.md index 35fb1495b..5936ed156 100644 --- a/translations/it/02-prompt-engineering/README.md +++ b/translations/it/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ # Modulo 02: Ingegneria dei Prompt con GPT-5.2 -## Sommario - -- [Video Dimostrativo](../../../02-prompt-engineering) -- [Cosa Imparerai](../../../02-prompt-engineering) -- [Prerequisiti](../../../02-prompt-engineering) -- [Comprendere l'Ingegneria dei Prompt](../../../02-prompt-engineering) -- [Fondamenti di Ingegneria dei Prompt](../../../02-prompt-engineering) - - [Prompt Zero-Shot](../../../02-prompt-engineering) - - [Prompt Few-Shot](../../../02-prompt-engineering) - - [Catena di Pensiero](../../../02-prompt-engineering) - - [Prompt Basati sul Ruolo](../../../02-prompt-engineering) - - [Template per Prompt](../../../02-prompt-engineering) -- [Modelli Avanzati](../../../02-prompt-engineering) -- [Esegui l'Applicazione](../../../02-prompt-engineering) -- [Screenshot dell'Applicazione](../../../02-prompt-engineering) -- [Esplorando i Modelli](../../../02-prompt-engineering) - - [Bassa vs Alta Motivazione](../../../02-prompt-engineering) - - [Esecuzione di Compiti (Introduzioni agli Strumenti)](../../../02-prompt-engineering) - - [Codice Auto-Riflessivo](../../../02-prompt-engineering) - - [Analisi Strutturata](../../../02-prompt-engineering) - - [Chat Multi-Turno](../../../02-prompt-engineering) - - [Ragionamento Passo-Passo](../../../02-prompt-engineering) - - [Output Vincolato](../../../02-prompt-engineering) -- [Cosa Stai Veramente Imparando](../../../02-prompt-engineering) -- [Prossimi Passi](../../../02-prompt-engineering) - -## Video Dimostrativo +## Indice + +- [Video Guida](#video-guida) +- [Cosa Imparerai](#cosa-imparerai) +- [Prerequisiti](#prerequisiti) +- [Comprendere l'Ingegneria dei Prompt](#comprendere-lingegneria-dei-prompt) +- [Fondamenti dell'Ingegneria dei Prompt](#fondamenti-dellingegneria-dei-prompt) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Pattern Avanzati](#pattern-avanzati) +- [Esegui l'Applicazione](#esegui-lapplicazione) +- [Screenshot dell'Applicazione](#screenshot-dellapplicazione) +- [Esplorando i Pattern](#esplorare-i-pattern) + - [Bassa contro Alta Voglia](#bassa-vs-alta-propensione) + - [Esecuzione di Compiti (Preamboli degli Strumenti)](#esecuzione-di-attività-pre-amboli-per-gli-strumenti) + - [Codice Auto-Riflettente](#codice-auto-riflessivo) + - [Analisi Strutturata](#analisi-strutturata) + - [Chat Multi-Turno](#chat-multi-turno) + - [Ragionamento Passo-Passo](#ragionamento-passo-passo) + - [Output Vincolato](#output-vincolato) +- [Cosa Stai Davvero Imparando](#cosa-impari-veramente) +- [Prossimi Passi](#prossimi-passi) + +## Video Guida Guarda questa sessione live che spiega come iniziare con questo modulo: -Prompt Engineering con LangChain4j - Sessione Live +Ingegneria dei Prompt con LangChain4j - Sessione Live ## Cosa Imparerai -Il diagramma seguente offre una panoramica degli argomenti chiave e delle competenze che svilupperai in questo modulo — dalle tecniche di raffinamento dei prompt al workflow passo-passo che seguirai. +Il diagramma seguente offre una panoramica degli argomenti chiave e delle competenze che svilupperai in questo modulo — dalle tecniche di raffinamento del prompt fino al flusso di lavoro passo-passo che seguirai. Cosa Imparerai -Nei moduli precedenti, hai esplorato interazioni base di LangChain4j con i modelli GitHub e visto come la memoria abilita l’IA conversazionale con Azure OpenAI. Ora ci concentreremo su come porre domande — i prompt stessi — utilizzando GPT-5.2 di Azure OpenAI. Il modo in cui strutturi i tuoi prompt influisce notevolmente sulla qualità delle risposte ottenute. Iniziamo con una revisione delle tecniche fondamentali di prompting, poi passeremo a otto modelli avanzati che sfruttano appieno le capacità di GPT-5.2. +Nel modulo precedente hai visto come la memoria abilita l'AI conversazionale con Azure OpenAI. Ora ci concentreremo su come formulare le domande — i prompt stessi — usando GPT-5.2 di Azure OpenAI. Il modo in cui strutturi i prompt influisce dramaticamente sulla qualità delle risposte che ottieni. Iniziamo con una revisione delle tecniche fondamentali di prompting, per poi passare a otto pattern avanzati che sfruttano appieno le capacità di GPT-5.2. -Useremo GPT-5.2 perché introduce il controllo del ragionamento - puoi indicare al modello quanto riflettere prima di rispondere. Questo rende più evidenti le diverse strategie di prompting e aiuta a capire quando usare ciascun approccio. Beneficeremo anche di limiti di frequenza meno restrittivi su GPT-5.2 rispetto ai modelli GitHub. +Useremo GPT-5.2 perché introduce il controllo del ragionamento — puoi indicare al modello quanta riflessione fare prima di rispondere. Questo rende più evidenti le diverse strategie di prompting e ti aiuta a capire quando usare ciascun approccio. ## Prerequisiti -- Modulo 01 completato (risorse Azure OpenAI distribuite) -- File `.env` nella directory principale con credenziali Azure (creato da `azd up` nel Modulo 01) +- Completato il Modulo 01 (risorse Azure OpenAI distribuite) +- File `.env` nella directory root con credenziali Azure (creato da `azd up` nel Modulo 01) -> **Nota:** Se non hai completato il Modulo 01, segui prima le istruzioni di distribuzione lì. +> **Nota:** Se non hai completato il Modulo 01, segui prima le istruzioni di deployment lì. ## Comprendere l'Ingegneria dei Prompt -Alla base, l’ingegneria dei prompt è la differenza tra istruzioni vaghe e precise, come illustra il confronto qui sotto. +Alla base, l'ingegneria dei prompt è la differenza tra istruzioni vaghe e istruzioni precise, come illustra il confronto sottostante. Cos'è l'Ingegneria dei Prompt? -L’ingegneria dei prompt consiste nel progettare un testo di input che ottenga costantemente i risultati desiderati. Non si tratta solo di fare domande - ma di strutturare le richieste affinché il modello capisca esattamente cosa vuoi e come fornire la risposta. +L'ingegneria dei prompt consiste nel progettare testi di input che ottengano costantemente i risultati desiderati. Non si tratta solo di fare domande — ma di strutturare le richieste in modo che il modello capisca esattamente cosa vuoi e come fornirlo. -Pensalo come dare istruzioni a un collega. "Correggi l’errore" è vago. "Correggi la eccezione null pointer in UserService.java alla linea 45 aggiungendo un controllo null" è specifico. I modelli linguistici funzionano allo stesso modo - specificità e struttura sono importanti. +Pensa a quando dai istruzioni a un collega. "Sistema il bug" è vago. "Sistema l'eccezione null pointer in UserService.java alla riga 45 aggiungendo un controllo null" è specifico. I modelli linguistici funzionano allo stesso modo — la specificità e la struttura contano. -Il diagramma seguente mostra come LangChain4j si inserisce in questo contesto — collegando i tuoi modelli di prompt al modello attraverso i costrutti SystemMessage e UserMessage. +Il diagramma qui sotto mostra come LangChain4j si inserisce in questo contesto — collegando i tuoi pattern di prompt al modello tramite i blocchi costitutivi SystemMessage e UserMessage. -Come si integra LangChain4j +Come si Inserisce LangChain4j -LangChain4j fornisce l’infrastruttura — connessioni ai modelli, memoria e tipi di messaggi — mentre i modelli di prompt sono semplicemente testi accuratamente strutturati che invii attraverso questa infrastruttura. I principali costrutti sono `SystemMessage` (che imposta il comportamento e il ruolo dell’IA) e `UserMessage` (che contiene la tua richiesta vera e propria). +LangChain4j fornisce l'infrastruttura — connessioni al modello, memoria e tipi di messaggi — mentre i pattern di prompt sono semplicemente testo strutturato inviato attraverso quell'infrastruttura. I blocchi chiave sono `SystemMessage` (che imposta il comportamento e il ruolo dell'AI) e `UserMessage` (che veicola la tua richiesta reale). -## Fondamenti di Ingegneria dei Prompt +## Fondamenti dell'Ingegneria dei Prompt -Le cinque tecniche principali mostrate qui sotto costituiscono la base per un’ingegneria dei prompt efficace. Ognuna affronta un aspetto diverso della comunicazione con i modelli linguistici. +Le cinque tecniche di base mostrate qui sotto costituiscono la base dell'ingegneria dei prompt efficace. Ognuna affronta un aspetto diverso di come comunichi con i modelli linguistici. -Panoramica di Cinque Modelli di Ingegneria dei Prompt +Panoramica dei Cinque Pattern di Ingegneria dei Prompt -Prima di immergerci nei modelli avanzati di questo modulo, rivediamo cinque tecniche fondamentali di prompting. Questi sono i mattoni che ogni ingegnere di prompt dovrebbe conoscere. Se hai già seguito il [modulo Quick Start](../00-quick-start/README.md#2-prompt-patterns), li hai già visti in azione — ecco il quadro concettuale alla base. +Prima di immergerci nei pattern avanzati di questo modulo, diamo una revisione a cinque tecniche fondamentali di prompting. Questi sono i mattoni che ogni ingegnere di prompt dovrebbe conoscere. -### Prompt Zero-Shot +### Zero-Shot Prompting -L’approccio più semplice: dare al modello un’istruzione diretta senza esempi. Il modello si affida interamente al proprio addestramento per comprendere ed eseguire il compito. Funziona bene per richieste semplici dove il comportamento atteso è chiaro. +L'approccio più semplice: dare al modello un’istruzione diretta senza esempi. Il modello si basa interamente sul suo training per comprendere ed eseguire il compito. Funziona bene per richieste semplici dove il comportamento atteso è ovvio. -Prompt Zero-Shot +Zero-Shot Prompting -*Istruzione diretta senza esempi — il modello deduce il compito dall’istruzione stessa* +*Istruzione diretta senza esempi — il modello deduce il compito solo dall’istruzione* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Risposta: "Positivo" ``` -**Quando usarlo:** Classificazioni semplici, domande dirette, traduzioni o qualsiasi compito che il modello può gestire senza ulteriori indicazioni. +**Quando usarlo:** Classificazioni semplici, domande dirette, traduzioni o qualsiasi compito che il modello può gestire senza guida aggiuntiva. -### Prompt Few-Shot +### Few-Shot Prompting -Fornisci esempi che dimostrano il modello da seguire. Il modello apprende il formato input-output atteso dai tuoi esempi e lo applica ai nuovi input. Questo migliora notevolmente la coerenza per compiti dove il formato o comportamento desiderato non è ovvio. +Fornire esempi che mostrino il pattern che vuoi il modello segua. Il modello assimila il formato input-output atteso dagli esempi e lo applica a nuovi input. Questo migliora drasticamente la coerenza per compiti dove il formato o comportamento desiderato non è ovvio. -Prompt Few-Shot +Few-Shot Prompting -*Apprendimento dagli esempi — il modello identifica il modello e lo applica a nuovi input* +*Apprendimento dagli esempi — il modello identifica il pattern e lo applica a nuovi input* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Quando usarlo:** Classificazioni personalizzate, formattazioni coerenti, compiti specifici di dominio, o quando i risultati zero-shot sono incoerenti. +**Quando usarlo:** Classificazioni personalizzate, formattazioni consistenti, compiti specifici di dominio, o quando i risultati zero-shot sono incoerenti. -### Catena di Pensiero +### Chain of Thought -Chiedi al modello di mostrare il ragionamento passo-passo. Invece di saltare direttamente alla risposta, il modello scompone il problema e lavora esplicitamente su ogni parte. Questo migliora l’accuratezza in matematica, logica e ragionamenti multi-fase. +Chiedi al modello di mostrare il suo ragionamento passo-passo. Invece di saltare direttamente alla risposta, il modello scompone il problema e lavora esplicitamente su ogni parte. Questo migliora l'accuratezza in matematica, logica e ragionamenti multi-step. -Prompt Catena di Pensiero +Prompting Chain of Thought -*Ragionamento passo-passo — scomporre problemi complessi in passaggi logici espliciti* +*Ragionamento passo-passo — scomporre problemi complessi in passi logici espliciti* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Il modello mostra: 15 - 8 = 7, poi 7 + 12 = 19 mele ``` -**Quando usarlo:** Problemi matematici, puzzle logici, debug o qualsiasi compito dove mostrare il processo di ragionamento migliora accuratezza e fiducia. +**Quando usarlo:** Problemi di matematica, giochi di logica, debugging o qualsiasi compito dove mostrare il processo di ragionamento migliora accuratezza e fiducia. -### Prompt Basati sul Ruolo +### Role-Based Prompting -Imposta una persona o ruolo per l’IA prima di porre la domanda. Questo fornisce un contesto che modella il tono, la profondità e il focus della risposta. Un "architetto software" dà consigli diversi rispetto a un "sviluppatore junior" o a un "auditor di sicurezza". +Imposta una persona o un ruolo per l'AI prima di fare la domanda. Questo fornisce contesto che modella il tono, la profondità e il focus della risposta. Un "architetto software" dà consigli diversi rispetto a un "developer junior" o un "auditor di sicurezza". -Prompt Basati sul Ruolo +Role-Based Prompting -*Impostare contesto e persona — stessa domanda, risposte diverse a seconda del ruolo assegnato* +*Impostare contesto e persona — la stessa domanda riceve risposte diverse in base al ruolo assegnato* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Quando usarlo:** Revisioni di codice, tutoraggio, analisi specifiche di dominio, o quando servono risposte personalizzate a un livello di esperienza o prospettiva precisa. +**Quando usarlo:** Code review, tutoring, analisi specifiche di dominio, o quando hai bisogno di risposte su misura per un livello di competenza o prospettiva particolari. -### Template per Prompt +### Prompt Templates -Crea prompt riutilizzabili con segnaposto variabili. Invece di scrivere un nuovo prompt ogni volta, definisci un template una volta e inserisci valori diversi. La classe `PromptTemplate` di LangChain4j rende facile questo con la sintassi `{{variabile}}`. +Crea prompt riutilizzabili con segnaposti variabili. Invece di scrivere un prompt nuovo ogni volta, definisci un template una volta sola e riempi con valori diversi. La classe `PromptTemplate` di LangChain4j rende facile questo con la sintassi `{{variable}}`. -Template per Prompt +Prompt Templates -*Prompt riutilizzabili con segnaposto variabili — un template, molti usi* +*Prompt riutilizzabili con segnaposti variabili — un template, molteplici usi* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Quando usarlo:** Query ripetute con input diversi, elaborazioni batch, costruzione di workflow AI riutilizzabili, o qualsiasi scenario in cui la struttura del prompt resta la stessa ma cambiano i dati. +**Quando usarlo:** Query ripetute con input diversi, elaborazioni batch, costruzione di workflow AI riutilizzabili, o ogni scenario dove la struttura del prompt resta la stessa ma cambiano i dati. --- -Questi cinque fondamenti ti danno una solida cassetta degli attrezzi per la maggior parte dei compiti di prompting. Il resto di questo modulo si basa su di essi con **otto modelli avanzati** che sfruttano il controllo del ragionamento, l’auto-valutazione e le capacità di output strutturato di GPT-5.2. +Questi cinque fondamenti ti danno un kit solido per la maggior parte dei compiti di prompting. Il resto di questo modulo si basa su di essi con **otto pattern avanzati** che sfruttano il controllo del ragionamento, l’auto-valutazione e le capacità di output strutturato di GPT-5.2. -## Modelli Avanzati +## Pattern Avanzati -Con i fondamenti coperti, passiamo agli otto modelli avanzati che rendono questo modulo unico. Non tutti i problemi richiedono lo stesso approccio. Alcune domande richiedono risposte rapide, altre un ragionamento profondo. Alcuni hanno bisogno di ragionamenti visibili, altri solo dei risultati. Ciascun modello qui sotto è ottimizzato per uno scenario diverso — e il controllo del ragionamento di GPT-5.2 rende queste differenze ancora più marcate. +Con i fondamenti coperti, passiamo agli otto pattern avanzati che rendono questo modulo unico. Non tutti i problemi necessitano dello stesso approccio. Alcune domande richiedono risposte rapide, altre pensiero profondo. Alcune vogliono ragionamenti visibili, altre solo i risultati. Ogni pattern qui sotto è ottimizzato per uno scenario diverso — e il controllo del ragionamento di GPT-5.2 rende le differenze ancora più marcate. -Otto Modelli di Prompting +Otto Pattern di Prompting -*Panoramica degli otto modelli di ingegneria dei prompt e i loro casi d’uso* +*Panoramica degli otto pattern di ingegneria dei prompt e i loro casi d’uso* -GPT-5.2 aggiunge un’altra dimensione a questi modelli: *il controllo del ragionamento*. Il cursore qui sotto mostra come puoi regolare lo sforzo di pensiero del modello — da risposte rapide e dirette ad analisi profonde e dettagliate. +GPT-5.2 aggiunge un’altra dimensione a questi pattern: *il controllo del ragionamento*. Il cursore qui sotto mostra come puoi regolare lo sforzo di pensiero del modello — da risposte rapide e dirette a analisi profonde e complete. Controllo del Ragionamento con GPT-5.2 -*Il controllo del ragionamento di GPT-5.2 ti permette di specificare quanto il modello deve riflettere — da risposte veloci e dirette a esplorazioni approfondite* +*Il controllo del ragionamento di GPT-5.2 ti permette di specificare quanta riflessione il modello deve fare — da risposte rapide a esplorazioni profonde* -**Bassa Motivazione (Veloce & Mirato)** - Per domande semplici dove vuoi risposte rapide e dirette. Il modello fa un ragionamento minimo - massimo 2 passaggi. Usalo per calcoli, ricerche o domande dirette. +**Bassa Voglia (Veloce & Focalizzato)** - Per domande semplici dove vuoi risposte veloci e dirette. Il modello esegue un ragionamento minimo - massimo 2 passi. Usa questo per calcoli, ricerche, o domande immediate. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Esplora con GitHub Copilot:** Apri [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) e chiedi: -> - "Qual è la differenza tra modelli di prompting a bassa e alta motivazione?" -> - "Come aiutano i tag XML nei prompt a strutturare la risposta dell’IA?" -> - "Quando dovrei usare modelli di auto-riflessione rispetto a istruzioni dirette?" +> - "Qual è la differenza tra pattern di bassa voglia e alta voglia nei prompting?" +> - "Come aiutano i tag XML nei prompt a strutturare la risposta dell’AI?" +> - "Quando dovrei usare pattern di auto-riflessione vs istruzioni dirette?" -**Alta Motivazione (Profondo & Dettagliato)** - Per problemi complessi dove vuoi un’analisi completa. Il modello esplora a fondo e mostra un ragionamento dettagliato. Usalo per progettazioni di sistema, decisioni di architettura o ricerche complesse. +**Alta Voglia (Profondo & Completo)** - Per problemi complessi dove vuoi un’analisi esaustiva. Il modello esplora a fondo e mostra un ragionamento dettagliato. Usa questo per progettazione di sistemi, decisioni architetturali, o ricerche complesse. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Esecuzione di Compiti (Progresso Passo-Passo)** - Per flussi di lavoro multi-step. Il modello fornisce un piano iniziale, narra ogni passaggio mentre lavora, poi fornisce un riepilogo. Usalo per migrazioni, implementazioni o qualsiasi processo multi-step. +**Esecuzione di Compiti (Progresso Passo-Passo)** - Per workflow multi-step. Il modello fornisce un piano iniziale, narra ogni passo mentre lavora, poi dà un riepilogo. Usa questo per migrazioni, implementazioni o qualsiasi processo a più fasi. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Il prompting Catena di Pensiero chiede esplicitamente al modello di mostrare il ragionamento, migliorando l’accuratezza per compiti complessi. La scomposizione passo-passo aiuta sia gli umani che l’IA a comprendere la logica. +Il prompting Chain-of-Thought chiede esplicitamente al modello di mostrare il processo di ragionamento, migliorando l’accuratezza per compiti complessi. La scomposizione passo-passo aiuta sia gli umani che l’AI a capire la logica. -> **🤖 Prova con la Chat di [GitHub Copilot](https://github.com/features/copilot):** Chiedi su questo modello: -> - "Come adatterei il modello di esecuzione compiti per operazioni di lunga durata?" -> - "Quali sono le best practice per strutturare le introduzioni degli strumenti nelle applicazioni di produzione?" -> - "Come posso catturare e mostrare aggiornamenti di progresso intermedi in un’interfaccia utente?" +> **🤖 Prova con la Chat di [GitHub Copilot](https://github.com/features/copilot):** Chiedi di questo pattern: +> - "Come adattare il pattern di esecuzione di compiti per operazioni a lunga durata?" +> - "Quali sono le best practice per strutturare i preamboli degli strumenti in applicazioni di produzione?" +> - "Come catturare e mostrare aggiornamenti intermedi di progresso in un’interfaccia utente?" Il diagramma qui sotto illustra questo flusso Plan → Execute → Summarize. -Modello di Esecuzione dei Compiti +Pattern di Esecuzione di Compiti *Flusso Plan → Execute → Summarize per compiti multi-step* -**Codice Auto-Riflessivo** - Per generare codice di qualità produttiva. Il modello genera codice seguendo standard di produzione con una gestione errori adeguata. Usalo per costruire nuove funzionalità o servizi. +**Codice Auto-Riflettente** - Per generare codice di qualità produzione. Il modello genera codice secondo standard produttivi con gestione appropriata degli errori. Usa questo quando costruisci nuove funzionalità o servizi. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Il diagramma seguente mostra questo ciclo di miglioramento iterativo — genera, valuta, identifica debolezze e affina fino a quando il codice soddisfa gli standard produttivi. +Il diagramma qui sotto mostra questo ciclo iterativo di miglioramento — genera, valuta, individua punti deboli e affina finché il codice raggiunge gli standard produttivi. Ciclo di Auto-Riflessione -*Ciclo di miglioramento iterativo - genera, valuta, identifica problemi, migliora, ripeti* +*Ciclo iterativo di miglioramento – genera, valuta, individua problemi, migliora, ripeti* -**Analisi Strutturata** - Per valutazioni coerenti. Il modello revisiona il codice usando un quadro fisso (correttezza, pratiche, performance, sicurezza, manutenibilità). Usalo per review di codice o valutazioni di qualità. +**Analisi Strutturata** - Per valutazioni consistenti. Il modello revisiona codice usando un framework fisso (correttezza, pratiche, performance, sicurezza, manutenibilità). Usa questo per code review o valutazioni di qualità. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Prova con la Chat di [GitHub Copilot](https://github.com/features/copilot):** Chiedi sull’analisi strutturata: -> - "Come posso personalizzare il quadro di analisi per diversi tipi di revisioni di codice?" -> - "Qual è il modo migliore per analizzare e agire su output strutturati programmaticamente?" +> **🤖 Prova con la Chat di [GitHub Copilot](https://github.com/features/copilot):** Chiedi dell’analisi strutturata: +> - "Come personalizzare il framework di analisi per diversi tipi di code review?" +> - "Qual è il modo migliore per analizzare e agire su output strutturato programmaticamente?" > - "Come garantire livelli di severità coerenti tra diverse sessioni di revisione?" -Il diagramma seguente mostra come questo quadro strutturato organizza una revisione di codice in categorie coerenti con livelli di severità. +Il diagramma seguente mostra come questo framework strutturato organizza una code review in categorie consistenti con livelli di severità. -Modello di Analisi Strutturata +Pattern di Analisi Strutturata -*Quadro per revisioni di codice coerenti con livelli di severità* +*Framework per code review coerenti con livelli di severità* -**Chat Multi-Turno** - Per conversazioni che necessitano contesto. Il modello ricorda i messaggi precedenti e costruisce su di essi. Usalo per sessioni di aiuto interattive o Q&A complessi. +**Chat Multi-Turno** - Per conversazioni che necessitano di contesto. Il modello ricorda i messaggi precedenti e costruisce sopra di essi. Usa questo per sessioni di aiuto interattive o Q&A complessi. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Il diagramma seguente visualizza come il contesto della conversazione si accumula a ogni turno e come si relaziona al limite di token del modello. +Il diagramma qui sotto visualizza come il contesto della conversazione si accumula ad ogni turno e come questo si rapporta al limite di token del modello. Memoria del Contesto -*Come il contesto di conversazione si accumula su più turni fino a raggiungere il limite di token* -**Step-by-Step Reasoning** - Per problemi che richiedono una logica visibile. Il modello mostra un ragionamento esplicito per ogni passaggio. Usalo per problemi di matematica, puzzle logici o quando hai bisogno di comprendere il processo di pensiero. +*Come il contesto della conversazione si accumula su più turni fino a raggiungere il limite di token* + +**Ragionamento Passo-Passo** - Per problemi che richiedono logica visibile. Il modello mostra ragionamenti espliciti per ciascun passo. Usa questo per problemi di matematica, rompicapi logici, o quando serve comprendere il processo di pensiero. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Il diagramma sottostante illustra come il modello suddivide i problemi in passaggi logici espliciti e numerati. - -Schema Passo-Passo +Il diagramma qui sotto illustra come il modello suddivide i problemi in passi logici numerati ed espliciti. -*Scomporre i problemi in passaggi logici espliciti* +Pattern Passo-Passo +*Suddividere i problemi in passaggi logici espliciti* -**Constrained Output** - Per risposte con requisiti di formato specifici. Il modello segue rigorosamente le regole di formato e lunghezza. Usalo per riassunti o quando hai bisogno di una struttura di output precisa. +**Output vincolato** - Per risposte con requisiti di formato specifici. Il modello segue rigorosamente le regole di formato e lunghezza. Usalo per riepiloghi o quando hai bisogno di una struttura di output precisa. ```java String prompt = """ @@ -420,9 +420,9 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Il seguente diagramma mostra come i vincoli guidano il modello a produrre un output che aderisce rigorosamente al tuo formato e ai requisiti di lunghezza. +Il diagramma seguente mostra come i vincoli guidano il modello a produrre un output che aderisce rigorosamente ai tuoi requisiti di formato e lunghezza. -Schema Output Vincolato +Constrained Output Pattern *Applicare requisiti specifici di formato, lunghezza e struttura* @@ -430,7 +430,7 @@ Il seguente diagramma mostra come i vincoli guidano il modello a produrre un out **Verifica il deployment:** -Assicurati che il file `.env` esista nella directory principale con le credenziali Azure (create durante il Modulo 01). Esegui questo dal modulo (`02-prompt-engineering/`): +Assicurati che il file `.env` esista nella directory principale con le credenziali di Azure (create durante il Modulo 01). Esegui questo dalla directory del modulo (`02-prompt-engineering/`): **Bash:** ```bash @@ -444,37 +444,37 @@ Get-Content ..\.env # Dovrebbe mostrare AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Avvia l'applicazione:** -> **Nota:** Se hai già avviato tutte le applicazioni usando `./start-all.sh` dalla directory principale (come descritto nel Modulo 01), questo modulo è già in esecuzione sulla porta 8083. Puoi saltare i comandi di avvio qui sotto e andare direttamente a http://localhost:8083. +> **Nota:** Se hai già avviato tutte le applicazioni usando `./start-all.sh` dalla directory principale (come descritto nel Modulo 01), questo modulo è già in esecuzione sulla porta 8083. Puoi saltare i comandi di avvio seguenti e andare direttamente a http://localhost:8083. -**Opzione 1: Uso del Spring Boot Dashboard (Consigliato per utenti VS Code)** +**Opzione 1: Usare Spring Boot Dashboard (Consigliato per utenti VS Code)** -Il contenitore di sviluppo include l'estensione Spring Boot Dashboard, che fornisce un'interfaccia visiva per gestire tutte le applicazioni Spring Boot. La trovi nella Activity Bar sul lato sinistro di VS Code (cerca l'icona di Spring Boot). +Il container di sviluppo include l'estensione Spring Boot Dashboard, che fornisce un'interfaccia visuale per gestire tutte le applicazioni Spring Boot. Puoi trovarla nella Activity Bar sul lato sinistro di VS Code (cerca l'icona Spring Boot). Dal Spring Boot Dashboard puoi: -- Vedere tutte le applicazioni Spring Boot disponibili nel workspace -- Avviare/fermare le applicazioni con un solo clic -- Visualizzare i log delle applicazioni in tempo reale -- Monitorare lo stato delle applicazioni +- Vedere tutte le applicazioni Spring Boot disponibili nell'area di lavoro +- Avviare/fermare applicazioni con un solo clic +- Visualizzare i log dell'applicazione in tempo reale +- Monitorare lo stato dell'applicazione -Basta cliccare il pulsante play accanto a "prompt-engineering" per avviare questo modulo, o avviare tutti i moduli contemporaneamente. +Clicca semplicemente il pulsante play accanto a "prompt-engineering" per avviare questo modulo, oppure avvia tutti i moduli insieme. Spring Boot Dashboard *Il Spring Boot Dashboard in VS Code — avvia, ferma e monitora tutti i moduli da un unico posto* -**Opzione 2: Uso di script shell** +**Opzione 2: Usare gli script shell** Avvia tutte le applicazioni web (moduli 01-04): **Bash:** ```bash -cd .. # Dalla directory principale +cd .. # Dalla directory radice ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Dalla directory radice +cd .. # Dalla directory principale .\start-all.ps1 ``` @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Entrambi gli script caricano automaticamente le variabili d'ambiente dal file `.env` nella directory principale e costruiranno i JAR se non esistono. +Entrambi gli script caricano automaticamente le variabili d'ambiente dal file `.env` nella root e compileranno i JAR se non esistono. -> **Nota:** Se preferisci compilare tutti i moduli manualmente prima di avviare: +> **Nota:** Se preferisci compilare manualmente tutti i moduli prima di avviare: > > **Bash:** > ```bash @@ -508,7 +508,7 @@ Entrambi gli script caricano automaticamente le variabili d'ambiente dal file `. > mvn clean package -DskipTests > ``` -Apri http://localhost:8083 nel browser. +Apri http://localhost:8083 nel tuo browser. **Per fermare:** @@ -528,81 +528,81 @@ cd ..; .\stop-all.ps1 # Tutti i moduli ## Screenshot dell'Applicazione -Ecco l'interfaccia principale del modulo di prompt engineering, dove puoi sperimentare tutti e otto i pattern fianco a fianco. +Ecco l'interfaccia principale del modulo di prompt engineering, dove puoi sperimentare con tutti e otto i pattern fianco a fianco. Dashboard Home -*La dashboard principale che mostra tutti gli 8 pattern di prompt engineering con le loro caratteristiche e casi d'uso* +*La dashboard principale che mostra tutti e 8 i pattern di prompt engineering con le loro caratteristiche e casi d'uso* -## Esplorazione dei Pattern +## Esplorare i Pattern -L'interfaccia web ti permette di sperimentare diverse strategie di prompting. Ogni pattern risolve diversi problemi — provali per capire quando ciascun approccio funziona meglio. +L'interfaccia web ti permette di sperimentare diverse strategie di prompting. Ogni pattern risolve problemi differenti - prova a vedere quando ogni approccio dà il meglio. -> **Nota: Streaming vs Non-Streaming** — Ogni pagina di pattern offre due pulsanti: **🔴 Stream Response (Live)** e una opzione **Non-streaming**. Lo streaming usa Server-Sent Events (SSE) per mostrare i token in tempo reale mentre il modello li genera, così vedi subito i progressi. L'opzione non-streaming aspetta l'intera risposta prima di visualizzarla. Per prompt che avviano ragionamenti complessi (es. High Eagerness, Self-Reflecting Code), la chiamata non-streaming può richiedere molto tempo — a volte minuti — senza alcun feedback visibile. **Usa lo streaming quando sperimenti prompt complessi** così puoi vedere il modello lavorare ed evitare l'impressione che la richiesta sia andata in timeout. +> **Nota: Streaming vs Non-Streaming** — Ogni pagina di pattern offre due pulsanti: **🔴 Stream Response (Live)** e una opzione **Non-streaming**. Lo streaming utilizza Server-Sent Events (SSE) per mostrare i token in tempo reale mentre il modello li genera, così vedi il progresso immediatamente. L'opzione non-streaming aspetta l'intera risposta prima di mostrarla. Per prompt che richiedono ragionamenti profondi (es. High Eagerness, Self-Reflecting Code), la chiamata non-streaming può richiedere molto tempo — a volte minuti — senza feedback visibile. **Usa lo streaming quando sperimenti con prompt complessi** così puoi vedere il modello in azione ed evitare l'impressione che la richiesta sia scaduta. > -> **Nota: Requisito Browser** — La funzione streaming usa la Fetch Streams API (`response.body.getReader()`) che richiede un browser completo (Chrome, Edge, Firefox, Safari). Non funziona nel Simple Browser integrato in VS Code, poiché la sua webview non supporta la ReadableStream API. Se usi il Simple Browser, i pulsanti non-streaming funzioneranno normalmente — solo i pulsanti streaming sono interessati. Apri `http://localhost:8083` in un browser esterno per l'esperienza completa. +> **Nota: Requisiti Browser** — La funzionalità di streaming usa Fetch Streams API (`response.body.getReader()`) che richiede un browser completo (Chrome, Edge, Firefox, Safari). Non funziona nel Simple Browser integrato di VS Code, poiché la sua webview non supporta ReadableStream API. Se usi Simple Browser, i pulsanti non-streaming funzionano normalmente — solo quelli streaming sono influenzati. Apri `http://localhost:8083` in un browser esterno per l'esperienza completa. -### Low vs High Eagerness +### Bassa vs Alta Propensione -Fai una domanda semplice come "Qual è il 15% di 200?" usando Low Eagerness. Otterrai una risposta istantanea e diretta. Ora chiedi qualcosa di complesso come "Progetta una strategia di caching per una API ad alto traffico" usando High Eagerness. Clicca **🔴 Stream Response (Live)** e guarda apparire il ragionamento dettagliato del modello token per token. Stesso modello, stessa struttura di domanda — ma il prompt indica quanta riflessione deve fare. +Fai una domanda semplice come "Qual è il 15% di 200?" usando Bassa Propensione. Otterrai una risposta istantanea e diretta. Ora chiedi qualcosa di complesso come "Progetta una strategia di caching per un'API ad alto traffico" usando Alta Propensione. Clicca **🔴 Stream Response (Live)** e guarda il ragionamento dettagliato del modello apparire token per token. Stesso modello, stessa struttura di domanda - ma il prompt indica quanto pensiero attivare. -### Esecuzione di Compiti (Tool Preambles) +### Esecuzione di Attività (Pre-amboli per gli Strumenti) -I workflow multi-step beneficiano di pianificazione anticipata e narrazione dei progressi. Il modello delinea cosa farà, narra ogni passo e poi riassume i risultati. +I workflow a più fasi beneficiano di una pianificazione anticipata e narrazione del progresso. Il modello descrive cosa farà, narra ogni passaggio, poi riassume i risultati. -### Codice Auto-Riflettente +### Codice Auto-Riflessivo -Prova "Crea un servizio di validazione email". Invece di generare solo il codice e fermarsi, il modello genera, valuta secondo criteri di qualità, identifica debolezze e migliora. Lo vedrai iterare fino a quando il codice soddisfa gli standard di produzione. +Prova "Crea un servizio di validazione email". Invece di generare solo codice e fermarsi, il modello genera, valuta secondo criteri di qualità, identifica debolezze e migliora. Vedrai iterare finché il codice non raggiunge standard di produzione. ### Analisi Strutturata -Le revisioni di codice necessitano di framework di valutazione coerenti. Il modello analizza il codice usando categorie fisse (correttezza, pratiche, prestazioni, sicurezza) con livelli di gravità. +Le revisioni del codice necessitano di framework di valutazione coerenti. Il modello analizza il codice usando categorie fisse (correttezza, pratiche, performance, sicurezza) con livelli di gravità. -### Chat Multi-Turno +### Chat Multi-turno -Chiedi "Cos'è Spring Boot?" e subito dopo "Fammi vedere un esempio". Il modello ricorda la tua prima domanda e ti dà un esempio specifico di Spring Boot. Senza memoria, la seconda domanda sarebbe troppo vaga. +Chiedi "Cos'è Spring Boot?" e subito dopo "Mostrami un esempio". Il modello ricorda la prima domanda e ti dà un esempio specifico di Spring Boot. Senza memoria, la seconda domanda sarebbe troppo vaga. -### Step-by-Step Reasoning +### Ragionamento Passo-Passo -Scegli un problema di matematica e provalo sia con Step-by-Step Reasoning che con Low Eagerness. Low Eagerness ti dà solo la risposta — veloce ma opaca. Step-by-step ti mostra ogni calcolo e decisione. +Scegli un problema matematico e prova sia il Ragionamento Passo-Passo che la Bassa Propensione. La bassa propensione dà solo la risposta - veloce ma opaca. Il passo-passo mostra ogni calcolo e decisione. -### Constrained Output +### Output Vincolato -Quando hai bisogno di formati specifici o conteggi di parole, questo pattern impone un'adesione rigorosa. Prova a generare un riassunto con esattamente 100 parole in formato elenco puntato. +Quando necessiti formati specifici o conti parole precisi, questo pattern fa rispettare questi limiti rigorosi. Prova a generare un riepilogo con esattamente 100 parole in formato elenco puntato. -## Cosa Stai Davvero Imparando +## Cosa Impari Veramente **Lo Sforzo di Ragionamento Cambia Tutto** -GPT-5.2 ti permette di controllare lo sforzo computazionale tramite i prompt. Poco sforzo significa risposte rapide con esplorazione minima. Molto sforzo significa che il modello impiega tempo per riflettere profondamente. Stai imparando ad abbinare lo sforzo alla complessità del compito — non perdere tempo con domande semplici, ma non affrettare decisioni complesse. +GPT-5.2 ti permette di controllare lo sforzo computazionale tramite i prompt. Poco sforzo significa risposte rapide con esplorazione minima. Alto sforzo significa che il modello impiega tempo per riflettere in profondità. Stai imparando ad abbinare lo sforzo alla complessità del compito - non sprecare tempo con domande semplici, ma non affrettare nemmeno decisioni complesse. **La Struttura Guida il Comportamento** -Hai notato i tag XML nei prompt? Non sono decorativi. I modelli seguono istruzioni strutturate in modo più affidabile rispetto al testo libero. Quando hai bisogno di processi multi-step o logica complessa, la struttura aiuta il modello a tenere traccia di dove si trova e cosa viene dopo. Il diagramma sotto scompone un prompt ben strutturato, mostrando come tag come ``, ``, ``, ``, e `` organizzano le tue istruzioni in sezioni chiare. +Hai notato i tag XML nei prompt? Non sono decorativi. I modelli seguono istruzioni strutturate in modo più affidabile rispetto al testo libero. Quando ti servono processi multi-step o logica complessa, la struttura aiuta il modello a sapere dove si trova e cosa viene dopo. Il diagramma qui sotto scompone un prompt ben strutturato, mostrando come tag come ``, ``, ``, ``, e `` organizzano le istruzioni in sezioni chiare. -Struttura del Prompt +Prompt Structure *Anatomia di un prompt ben strutturato con sezioni chiare e organizzazione in stile XML* -**Qualità tramite Auto-Valutazione** +**Qualità Tramite Auto-Valutazione** -I pattern che usano l'auto-riflessione funzionano rendendo espliciti i criteri di qualità. Invece di sperare che il modello "faccia bene", gli dici esattamente cosa significa "bene": logica corretta, gestione degli errori, prestazioni, sicurezza. Il modello può quindi valutare la propria uscita e migliorare. Questo trasforma la generazione di codice da una lotteria a un processo. +I pattern auto-riflessivi funzionano rendendo espliciti i criteri di qualità. Invece di sperare che il modello "faccia bene", gli dici esattamente cosa significa "bene": logica corretta, gestione errori, performance, sicurezza. Il modello può quindi valutare il proprio output e migliorare. Questo trasforma la generazione di codice da una lotteria a un processo. **Il Contesto è Finito** -Le conversazioni multi-turno funzionano includendo la storia dei messaggi con ogni richiesta. Ma c'è un limite — ogni modello ha un conteggio massimo di token. Man mano che le conversazioni crescono, avrai bisogno di strategie per mantenere contesto rilevante senza superare quel limite. Questo modulo ti mostra come funziona la memoria; più avanti imparerai quando riassumere, quando dimenticare e quando recuperare. +Le conversazioni multi-turno funzionano includendo la cronologia dei messaggi ad ogni richiesta. Ma c'è un limite - ogni modello ha un massimo di token. Man mano che le conversazioni crescono, ti serviranno strategie per mantenere il contesto rilevante senza superare quel limite. Questo modulo ti mostra come funziona la memoria; più avanti imparerai quando riassumere, quando dimenticare e quando recuperare. -## Passi Successivi +## Prossimi Passi **Prossimo Modulo:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigazione:** [← Precedente: Modulo 01 - Introduzione](../01-introduction/README.md) | [Torna al Principale](../README.md) | [Avanti: Modulo 03 - RAG →](../03-rag/README.md) +**Navigazione:** [← Precedente: Modulo 01 - Introduzione](../01-introduction/README.md) | [Torna al Principale](../README.md) | [Successivo: Modulo 03 - RAG →](../03-rag/README.md) --- **Disclaimer**: -Questo documento è stato tradotto utilizzando il servizio di traduzione automatica [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per l’accuratezza, si prega di considerare che le traduzioni automatiche possono contenere errori o imprecisioni. Il documento originale nella sua lingua natìa deve essere considerato la fonte autorevole. Per informazioni critiche si raccomanda la traduzione professionale umana. Non siamo responsabili per eventuali incomprensioni o interpretazioni errate derivanti dall’uso di questa traduzione. +Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire la precisione, si prega di notare che le traduzioni automatizzate possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un essere umano. Non siamo responsabili per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. \ No newline at end of file diff --git a/translations/it/03-rag/README.md b/translations/it/03-rag/README.md index 288420242..2b23d2391 100644 --- a/translations/it/03-rag/README.md +++ b/translations/it/03-rag/README.md @@ -1,113 +1,112 @@ -# Modulo 03: RAG (Generazione Integrata con Recupero) +# Modulo 03: RAG (Generazione Potenziata da Recupero) ## Indice -- [Video Guida](../../../03-rag) -- [Cosa Imparerai](../../../03-rag) -- [Prerequisiti](../../../03-rag) -- [Comprendere RAG](../../../03-rag) - - [Quale Approccio RAG Usa Questo Tutorial?](../../../03-rag) -- [Come Funziona](../../../03-rag) - - [Elaborazione del Documento](../../../03-rag) - - [Creazione degli Embedding](../../../03-rag) - - [Ricerca Semantica](../../../03-rag) - - [Generazione della Risposta](../../../03-rag) -- [Esegui l'Applicazione](../../../03-rag) -- [Uso dell'Applicazione](../../../03-rag) - - [Carica un Documento](../../../03-rag) - - [Fai Domande](../../../03-rag) - - [Controlla le Riferimenti alla Fonte](../../../03-rag) - - [Sperimenta con le Domande](../../../03-rag) -- [Concetti Chiave](../../../03-rag) - - [Strategia di Scomposizione](../../../03-rag) - - [Punteggi di Similarità](../../../03-rag) - - [Memorizzazione in RAM](../../../03-rag) - - [Gestione della Finestra di Contesto](../../../03-rag) -- [Quando RAG è Importante](../../../03-rag) -- [Prossimi Passi](../../../03-rag) - -## Video Guida - -Guarda questa sessione dal vivo che spiega come iniziare con questo modulo: - -RAG con LangChain4j - Sessione dal Vivo +- [Guida Video](#guida-video) +- [Cosa Imparerai](#cosa-imparerai) +- [Prerequisiti](#prerequisiti) +- [Comprendere RAG](#comprendere-rag) + - [Quale approccio RAG utilizza questo tutorial?](#quale-approccio-rag-utilizza-questo-tutorial) +- [Come Funziona](#come-funziona) + - [Elaborazione del Documento](#elaborazione-del-documento) + - [Creazione degli Embedding](#creazione-degli-embedding) + - [Ricerca Semantica](#ricerca-semantica) + - [Generazione della Risposta](#generazione-della-risposta) +- [Esecuzione dell’Applicazione](#esegui-lapplicazione) +- [Utilizzo dell’Applicazione](#usare-lapplicazione) + - [Caricare un Documento](#carica-un-documento) + - [Porre Domande](#fai-domande) + - [Verificare le Riferimenti alle Fonti](#controlla-i-riferimenti-delle-fonti) + - [Sperimentare con le Domande](#sperimenta-con-le-domande) +- [Concetti Chiave](#concetti-chiave) + - [Strategia di Suddivisione in Chunk](#strategia-di-suddivisione-in-chunk) + - [Punteggi di Similarità](#punteggi-di-similarità) + - [Memorizzazione In-Memory](#storage-in-memoria) + - [Gestione della Finestra di Contesto](#gestione-della-finestra-di-contesto) +- [Quando RAG è Importante](#quando-rag-conta) +- [Passi Successivi](#passaggi-successivi) + +## Guida Video + +Guarda questa sessione live che spiega come iniziare con questo modulo: + +RAG con LangChain4j - Sessione Live ## Cosa Imparerai -Nei moduli precedenti, hai imparato come conversare con l'IA e strutturare efficacemente i tuoi prompt. Ma c'è una limitazione fondamentale: i modelli di linguaggio conoscono solo ciò che hanno appreso durante l'addestramento. Non possono rispondere a domande sulle politiche della tua azienda, sulla documentazione del tuo progetto o su qualsiasi informazione su cui non sono stati addestrati. +Nei moduli precedenti, hai imparato come avere conversazioni con l’AI e strutturare efficacemente i tuoi prompt. Ma c’è una limitazione fondamentale: i modelli linguistici conoscono solo ciò che hanno appreso durante l’addestramento. Non possono rispondere a domande sulle politiche della tua azienda, sulla documentazione del tuo progetto o su qualsiasi informazione su cui non sono stati addestrati. -RAG (Generazione Integrata con Recupero) risolve questo problema. Invece di cercare di insegnare al modello le tue informazioni (operazione costosa e poco pratica), gli dai la capacità di cercare nei tuoi documenti. Quando qualcuno fa una domanda, il sistema trova informazioni rilevanti e le include nel prompt. Il modello risponde quindi in base a quel contesto recuperato. +RAG (Generazione Potenziata da Recupero) risolve questo problema. Invece di cercare di insegnare al modello le tue informazioni (cosa costosa e poco pratica), gli dai la capacità di cercare tra i tuoi documenti. Quando qualcuno fa una domanda, il sistema trova informazioni rilevanti e le include nel prompt. Il modello risponde quindi basandosi su quel contesto recuperato. -Pensa a RAG come a fornire al modello una biblioteca di riferimento. Quando fai una domanda, il sistema: +Pensa a RAG come a fornire al modello una biblioteca di riferimento. Quando chiedi una domanda, il sistema: -1. **Query Utente** - Fai una domanda -2. **Embedding** - Converte la tua domanda in un vettore -3. **Ricerca Vettoriale** - Trova chunk di documenti simili -4. **Assemblaggio del Contesto** - Aggiunge chunk rilevanti al prompt -5. **Risposta** - LLM genera una risposta basata sul contesto +1. **Query Utente** - Fai una domanda +2. **Embedding** - Converte la tua domanda in un vettore +3. **Ricerca Vettoriale** - Trova chunk di documento simili +4. **Assemblaggio del Contesto** - Aggiunge chunk rilevanti al prompt +5. **Risposta** - LLM genera una risposta basata sul contesto -Questo fa sì che le risposte del modello siano radicate nei tuoi dati reali invece di basarsi solo sulla conoscenza dell'addestramento o inventare risposte. +Questo radica le risposte del modello nei tuoi dati reali invece di affidarsi solo alla conoscenza dell'addestramento o di inventare risposte. ## Prerequisiti -- Aver completato il [Modulo 00 - Quick Start](../00-quick-start/README.md) (per l'esempio Easy RAG citato successivamente in questo modulo) -- Aver completato il [Modulo 01 - Introduzione](../01-introduction/README.md) (risorse Azure OpenAI distribuite, incluso il modello di embedding `text-embedding-3-small`) -- File `.env` nella directory radice con credenziali Azure (creato con `azd up` nel Modulo 01) +- Completato il [Modulo 01 - Introduzione](../01-introduction/README.md) (risorse Azure OpenAI distribuite, incluso il modello di embedding `text-embedding-3-small`) +- File `.env` nella directory root con le credenziali Azure (creato da `azd up` nel Modulo 01) -> **Nota:** Se non hai completato il Modulo 01, segui prima le istruzioni di distribuzione lì. Il comando `azd up` distribuisce sia il modello chat GPT sia il modello embedding usato da questo modulo. +> **Nota:** Se non hai completato il Modulo 01, segui prima lì le istruzioni di distribuzione. Il comando `azd up` distribuisce sia il modello GPT chat sia il modello di embedding usato in questo modulo. ## Comprendere RAG -Il diagramma qui sotto illustra il concetto fondamentale: invece di affidarsi solo ai dati di addestramento del modello, RAG gli fornisce una biblioteca di riferimento dei tuoi documenti da consultare prima di generare ogni risposta. +Il diagramma qui sotto illustra il concetto principale: invece di affidarsi solo ai dati di addestramento del modello, RAG gli fornisce una biblioteca di riferimento dei tuoi documenti da consultare prima di generare ogni risposta. -Cos'è RAG +Cos’è RAG *Questo diagramma mostra la differenza tra un LLM standard (che indovina dai dati di addestramento) e un LLM potenziato con RAG (che consulta prima i tuoi documenti).* -Ecco come i pezzi si connettono end-to-end. La domanda di un utente passa attraverso quattro fasi — embedding, ricerca vettoriale, assemblaggio del contesto e generazione della risposta — ciascuna costruita sulla precedente: +Ecco come si connettono i pezzi end-to-end. La domanda di un utente passa attraverso quattro fasi — embedding, ricerca vettoriale, assemblaggio del contesto, e generazione della risposta — ognuna si basa sulla precedente: Architettura RAG -*Questo diagramma mostra la pipeline RAG end-to-end — una query utente passa attraverso embedding, ricerca vettoriale, assemblaggio del contesto e generazione della risposta.* +*Questo diagramma mostra il flusso completo RAG — una query utente attraversa embedding, ricerca vettoriale, assemblaggio del contesto, e generazione della risposta.* -Il resto di questo modulo illustra ogni fase in dettaglio, con codice che puoi eseguire e modificare. +Il resto di questo modulo percorre ogni fase in dettaglio, con codice che puoi eseguire e modificare. -### Quale Approccio RAG Usa Questo Tutorial? +### Quale approccio RAG utilizza questo tutorial? -LangChain4j offre tre modi per implementare RAG, ciascuno con un diverso livello di astrazione. Il diagramma qui sotto li confronta affiancati: +LangChain4j offre tre modi per implementare RAG, ognuno con un diverso livello di astrazione. Il diagramma seguente li confronta fianco a fianco: Tre Approcci RAG in LangChain4j -*Questo diagramma confronta i tre approcci RAG di LangChain4j — Easy, Native e Advanced — mostrando i loro componenti chiave e quando usarli.* +*Questo diagramma confronta i tre approcci RAG di LangChain4j — Easy, Native, e Advanced — mostrando i loro componenti chiave e quando usarli.* | Approccio | Cosa Fa | Compromesso | |---|---|---| -| **Easy RAG** | Collega tutto automaticamente tramite `AiServices` e `ContentRetriever`. Annoti un'interfaccia, colleghi un retriever, e LangChain4j gestisce embedding, ricerca e assemblaggio prompt dietro le quinte. | Codice minimo, ma non vedi cosa succede a ogni passo. | -| **Native RAG** | Chiami il modello di embedding, cerchi nello store, costruisci il prompt e generi la risposta tu stesso — un passo esplicito per volta. | Più codice, ma ogni fase è visibile e modificabile. | -| **Advanced RAG** | Usa il framework `RetrievalAugmentor` con trasformatori di query pluggabili, router, ri-ordinatori e iniettori di contenuto per pipeline di livello produttivo. | Massima flessibilità, ma complessità significativamente maggiore. | +| **Easy RAG** | Collega tutto automaticamente tramite `AiServices` e `ContentRetriever`. Annoti un’interfaccia, alleghi un retriever, e LangChain4j gestisce embedding, ricerca e assemblaggio del prompt dietro le quinte. | Minimo codice, ma non vedi cosa succede in ogni passaggio. | +| **Native RAG** | Chiami direttamente il modello di embedding, cerchi nel magazzino, costruisci il prompt e generi la risposta — un passo esplicito alla volta. | Più codice, ma ogni fase è visibile e modificabile. | +| **Advanced RAG** | Usa il framework `RetrievalAugmentor` con trasformatori di query pluggabili, router, riordinatori e iniettori di contenuti per pipeline di livello produzione. | Massima flessibilità, ma complessità significativamente maggiore. | -**Questo tutorial usa l'approccio Native.** Ogni fase della pipeline RAG — embedding della query, ricerca nel vettore store, assemblaggio del contesto e generazione della risposta — è scritta esplicitamente in [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Questo è intenzionale: come risorsa di apprendimento è più importante che tu veda e capisca ogni fase piuttosto che minimizzare il codice. Una volta che ti senti a tuo agio con il funzionamento dei pezzi, puoi passare a Easy RAG per prototipi rapidi o a Advanced RAG per sistemi di produzione. +**Questo tutorial usa l’approccio Native.** Ogni fase della pipeline RAG — embedding della query, ricerca nel vector store, assemblaggio del contesto, e generazione della risposta — è esplicitamente scritta in [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Questo è intenzionale: come risorsa didattica, è più importante che tu veda e capisca ogni fase piuttosto che ridurre al minimo il codice. Quando sarai a tuo agio con come i pezzi si incastrano, potrai passare a Easy RAG per prototipi rapidi o Advanced RAG per sistemi di produzione. -> **💡 Hai già visto Easy RAG in azione?** Il [modulo Quick Start](../00-quick-start/README.md) include un esempio di Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) che usa l'approccio Easy RAG — LangChain4j gestisce automaticamente embedding, ricerca e assemblaggio prompt. Questo modulo fa il passo successivo rompendo quella pipeline per farti vedere e controllare ogni fase da solo. +> **💡 Curioso su Easy RAG?** LangChain4j offre anche un approccio *Easy RAG* dove `AiServices` e un `ContentRetriever` gestiscono automaticamente embedding, ricerca e assemblaggio del prompt. Questo modulo prende la strada più esplicita — aprendo quella pipeline così puoi vedere e controllare ogni fase. -Il diagramma qui sotto mostra la pipeline Easy RAG di quell'esempio Quick Start. Nota come `AiServices` e `EmbeddingStoreContentRetriever` nascondano tutta la complessità — carichi un documento, colleghi un retriever e ottieni risposte. L'approccio Native in questo modulo apre ognuno di quegli step nascosti: +Il diagramma qui sotto mostra la pipeline Easy RAG. Nota come `AiServices` e `EmbeddingStoreContentRetriever` nascondono tutta la complessità — carichi un documento, alleghi un retriever, e ottieni risposte. L’approccio Native in questo modulo apre ognuno di quei passaggi nascosti: Pipeline Easy RAG - LangChain4j -*Questo diagramma mostra la pipeline Easy RAG da `SimpleReaderDemo.java`. Confrontalo con l'approccio Native usato in questo modulo: Easy RAG nasconde embedding, recupero e assemblaggio prompt dietro `AiServices` e `ContentRetriever` — carichi un documento, colleghi un retriever e ottieni risposte. L'approccio Native in questo modulo rompe quella pipeline così chiami ogni fase (embed, ricerca, assemblaggio contesto, generazione) tu stesso, dandoti piena visibilità e controllo.* +*Questo diagramma mostra la pipeline Easy RAG. Confrontala con l’approccio Native usato in questo modulo: Easy RAG nasconde embedding, recupero e assemblaggio del prompt dietro `AiServices` e `ContentRetriever` — carichi un documento, alleghi un retriever e ottieni risposte. L’approccio Native in questo modulo apre quella pipeline così chiami ogni fase (embed, ricerca, assemblaggio contesto, generazione) tu stesso, dandoti piena visibilità e controllo.* ## Come Funziona -La pipeline RAG in questo modulo si suddivide in quattro fasi che si eseguono in sequenza ogni volta che un utente fa una domanda. Per prima cosa, un documento caricato viene **analizzato e suddiviso in chunk** gestibili. Quei chunk vengono poi convertiti in **embedding vettoriali** e memorizzati così da poter essere confrontati matematicamente. Quando arriva una query, il sistema esegue una **ricerca semantica** per trovare i chunk più rilevanti, e infine li passa come contesto all'LLM per la **generazione della risposta**. Le sezioni seguenti spiegano ogni fase con codice e diagrammi concreti. Vediamo il primo passo. +La pipeline RAG in questo modulo si scompone in quattro fasi eseguite in sequenza ogni volta che un utente fa una domanda. Prima, un documento caricato viene **analizzato e suddiviso in chunk** in parti gestibili. Quei chunk vengono poi convertiti in **embedding vettoriali** e memorizzati così da poter essere confrontati matematicamente. Quando arriva una query, il sistema esegue una **ricerca semantica** per trovare i chunk più rilevanti, e infine li passa come contesto al LLM per la **generazione della risposta**. Le sezioni qui sotto illustrano ogni fase con il codice reale e diagrammi. Guardiamo il primo passo. ### Elaborazione del Documento [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Quando carichi un documento, il sistema lo analizza (PDF o testo semplice), aggiunge metadati come il nome del file, e poi lo divide in chunk — pezzi più piccoli che stanno comodamente nella finestra di contesto del modello. Questi chunk si sovrappongono leggermente così non perdi il contesto ai confini. +Quando carichi un documento, il sistema lo analizza (PDF o testo semplice), allega i metadati come il nome file, e poi lo suddivide in chunk — parti più piccole che si adattano comodamente nella finestra di contesto del modello. Questi chunk si sovrappongono leggermente così non perdi contesto ai confini. ```java -// Analizza il file caricato e incapsulalo in un Documento LangChain4j +// Analizza il file caricato e incapsulalo in un Document di LangChain4j Document document = Document.from(content, metadata); // Dividi in blocchi di 300 token con una sovrapposizione di 30 token @@ -117,26 +116,26 @@ DocumentSplitter splitter = DocumentSplitters List segments = splitter.split(document); ``` -Il diagramma qui sotto mostra come funziona visivamente. Nota come ogni chunk condivide alcuni token con i suoi vicini — una sovrapposizione di 30 token assicura che nessun contesto importante venga perso: +Il diagramma qui sotto mostra come funziona visivamente. Nota come ogni chunk condivide alcuni token con i vicini — la sovrapposizione di 30 token assicura che nessun contesto importante cada tra le crepe: Suddivisione Documento in Chunk -*Questo diagramma mostra un documento suddiviso in chunk da 300 token con sovrapposizione di 30 token, preservando il contesto ai confini dei chunk.* +*Questo diagramma mostra un documento suddiviso in chunk di 300 token con sovrapposizione di 30 token, preservando il contesto ai confini dei chunk.* -> **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) e chiedi: -> - "Come divide LangChain4j i documenti in chunk e perché la sovrapposizione è importante?" -> - "Qual è la dimensione ottimale dei chunk per diversi tipi di documento e perché?" +> **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) e chiedi: +> - "Come divide LangChain4j i documenti in chunk e perché la sovrapposizione è importante?" +> - "Qual è la dimensione ottimale dei chunk per diversi tipi di documento e perché?" > - "Come gestisco documenti in più lingue o con formattazioni speciali?" ### Creazione degli Embedding [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Ogni chunk viene convertito in una rappresentazione numerica chiamata embedding — essenzialmente un convertitore da significato a numeri. Il modello di embedding non è "intelligente" come un modello chat; non può seguire istruzioni, ragionare o rispondere a domande. Quello che può fare è mappare il testo in uno spazio matematico dove significati simili si trovano vicini — "auto" vicino a "automobile," "politica di rimborso" vicino a "restituisci il mio denaro." Pensa a un modello chat come a una persona con cui puoi parlare; un modello di embedding è un sistema di archiviazione ultra-efficiente. +Ogni chunk viene convertito in una rappresentazione numerica chiamata embedding — essenzialmente un convertitore da significato a numeri. Il modello di embedding non è "intelligente" come un modello chat; non può seguire istruzioni, ragionare o rispondere a domande. Quello che può fare è mappare il testo in uno spazio matematico dove significati simili si trovano vicini — “auto” vicino a “automobile,” “politica di rimborso” vicino a “restituisci i miei soldi.” Pensa a un modello chat come a una persona con cui puoi parlare; un modello di embedding è un sistema di archiviazione ultra efficiente. Il diagramma qui sotto visualizza questo concetto — entra testo, escono vettori numerici, e significati simili producono vettori vicini: -Concetto Modello di Embedding +Concetto Modello Embedding *Questo diagramma mostra come un modello di embedding converte testo in vettori numerici, collocando significati simili — come "auto" e "automobile" — vicini nello spazio vettoriale.* @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Il diagramma delle classi qui sotto mostra i due flussi separati in una pipeline RAG e le classi LangChain4j che li implementano. Il **flusso di ingestione** (eseguito una volta al caricamento) divide il documento, crea gli embedding dei chunk e li memorizza via `.addAll()`. Il **flusso di query** (eseguito ogni volta che un utente fa una domanda) crea l'embedding della domanda, cerca nello store via `.search()`, e passa il contesto trovato al modello chat. Entrambi i flussi si incontrano all'interfaccia condivisa `EmbeddingStore`: +Il diagramma delle classi qui sotto mostra i due flussi separati in una pipeline RAG e le classi di LangChain4j che li implementano. Il **flusso di ingestione** (eseguito una volta al caricamento) divide il documento, crea gli embedding dei chunk, e li memorizza tramite `.addAll()`. Il **flusso di query** (eseguito ogni volta che un utente fa una domanda) crea l’embedding della domanda, cerca nel magazzino con `.search()`, e passa il contesto corrispondente al modello chat. Entrambi i flussi si incontrano nell’interfaccia condivisa `EmbeddingStore`: -Classi RAG LangChain4j +Classi RAG di LangChain4j -*Questo diagramma mostra i due flussi in una pipeline RAG — ingestione e query — e come si connettono attraverso un EmbeddingStore condiviso.* +*Questo diagramma mostra i due flussi in una pipeline RAG — ingestione e query — e come si connettono tramite un EmbeddingStore condiviso.* -Una volta memorizzati gli embedding, contenuti simili si raggruppano naturalmente insieme nello spazio vettoriale. La visualizzazione qui sotto mostra come documenti su argomenti correlati finiscono come punti vicini, rendendo possibile la ricerca semantica: +Una volta memorizzati gli embedding, contenuti simili naturalmente si raggruppano insieme nello spazio vettoriale. La visualizzazione qui sotto mostra come documenti su temi affini finiscono come punti vicini, il che rende possibile la ricerca semantica: -Spazio degli Embedding Vettoriali +Spazio Embedding Vettoriali -*Questa visualizzazione mostra come documenti correlati si raggruppano nello spazio vettoriale 3D, con argomenti come Documenti Tecnici, Regole Aziendali e FAQ che formano gruppi distinti.* +*Questa visualizzazione mostra come documenti correlati si raggruppano nello spazio vettoriale 3D, con temi come Documentazione Tecnica, Regole Aziendali e FAQ che formano gruppi distinti.* -Quando un utente effettua una ricerca, il sistema segue quattro passi: embeddare i documenti una volta, embeddare la query a ogni ricerca, confrontare il vettore della query con tutti i vettori memorizzati usando la similarità coseno, e restituire i primi K chunk con punteggio più alto. Il diagramma qui sotto illustra ogni step e le classi LangChain4j coinvolte: +Quando un utente cerca, il sistema segue quattro passaggi: crea embedding dei documenti una volta, crea embedding della query a ogni ricerca, confronta il vettore della query con tutti i vettori memorizzati usando la similarità del coseno, e restituisce i top-K chunk con punteggio più alto. Il diagramma qui sotto descrive ogni passaggio e le classi LangChain4j coinvolte: -Passi della Ricerca per Embedding +Passaggi della Ricerca con Embedding -*Questo diagramma mostra il processo di ricerca per embedding in quattro passi: embeddare i documenti, embeddare la query, confrontare i vettori con similarità coseno, e restituire i risultati top-K.* +*Questo diagramma mostra il processo in quattro fasi della ricerca con embedding: crea embedding dei documenti, crea embedding della query, confronta vettori con similarità del coseno, e restituisce i migliori risultati.* ### Ricerca Semantica [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Quando fai una domanda, anche la tua domanda viene convertita in un embedding. Il sistema confronta l'embedding della tua domanda con quelli di tutti i chunk del documento. Trova i chunk con significati più simili — non solo con parole chiave corrispondenti, ma con reale similarità semantica. +Quando fai una domanda, anche la tua domanda diventa un embedding. Il sistema confronta l’embedding della tua domanda con gli embedding di tutti i chunk di documento. Trova i chunk con i significati più simili - non solo parole chiave corrispondenti, ma vera somiglianza semantica. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Il diagramma qui sotto mette a confronto la ricerca semantica con la ricerca tradizionale per parole chiave. Una ricerca keyword per "vehicle" perde un chunk su "car and trucks," ma la ricerca semantica capisce che significano la stessa cosa e lo restituisce come risultato di punteggio alto: +Il diagramma qui sotto contrappone la ricerca semantica alla ricerca tradizionale basata su parole chiave. Una ricerca per parola chiave “veicolo” perde un chunk su “auto e camion,” ma la ricerca semantica capisce che significano la stessa cosa e lo restituisce come risultato con punteggio alto: Ricerca Semantica *Questo diagramma confronta la ricerca basata su parole chiave con la ricerca semantica, mostrando come la ricerca semantica recupera contenuti concettualmente correlati anche quando le parole chiave esatte differiscono.* -Sotto il cofano, la similarità è misurata usando la similarità coseno — che in sostanza chiede "queste due frecce puntano nella stessa direzione?" Due chunk possono usare parole completamente diverse, ma se significano la stessa cosa i loro vettori puntano nella stessa direzione e ottengono un punteggio vicino a 1.0: -Similarità Coseno +Nel dettaglio, la similarità si misura usando la similarità del coseno — in pratica, si chiede “queste due frecce puntano nella stessa direzione?” Due chunk possono usare parole completamente diverse, ma se significano la stessa cosa i loro vettori puntano nella stessa direzione e hanno un punteggio vicino a 1.0: -*Questo diagramma illustra la similarità coseno come l'angolo tra vettori di embedding — vettori più allineati ottengono un punteggio più vicino a 1.0, indicando una maggiore similarità semantica.* +Similarità del Coseno +*Questo diagramma illustra la similarità del coseno come l'angolo tra vettori di embedding — vettori più allineati ottengono un punteggio più vicino a 1.0, indicando una maggiore similarità semantica.* > **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) e chiedi: > - "Come funziona la ricerca di similarità con gli embeddings e cosa determina il punteggio?" -> - "Quale soglia di similarità dovrei usare e come influenza i risultati?" -> - "Come gestisco i casi in cui non si trovano documenti rilevanti?" +> - "Quale soglia di similarità dovrei usare e come influisce sui risultati?" +> - "Come gestisco i casi in cui non vengono trovati documenti rilevanti?" -### Generazione della Risposta +### Generazione della risposta [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -I chunk più rilevanti sono assemblati in un prompt strutturato che include istruzioni esplicite, il contesto recuperato e la domanda dell'utente. Il modello legge quei chunk specifici e risponde basandosi su quelle informazioni — può usare solo ciò che ha davanti, il che previene allucinazioni. +I chunk più rilevanti vengono assemblati in un prompt strutturato che include istruzioni esplicite, il contesto recuperato e la domanda dell'utente. Il modello legge quei chunk specifici e risponde basandosi su quelle informazioni — può usare solo ciò che ha davanti, il che previene allucinazioni. ```java String context = matches.stream() @@ -237,21 +236,21 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Il diagramma sottostante mostra questa composizione in azione — i chunk con il punteggio più alto dalla fase di ricerca sono inseriti nel template del prompt, e il `OpenAiOfficialChatModel` genera una risposta fondata: +Il diagramma seguente mostra questo assemblaggio in azione — i chunk con il punteggio più alto dalla fase di ricerca vengono inseriti nel modello di prompt, e `OpenAiOfficialChatModel` genera una risposta fondata: -Assemblaggio del Contesto +Assemblaggio del contesto -*Questo diagramma mostra come i chunk con il punteggio più alto sono assemblati in un prompt strutturato, permettendo al modello di generare una risposta basata sui tuoi dati.* +*Questo diagramma mostra come i chunk con il punteggio più alto vengono assemblati in un prompt strutturato, permettendo al modello di generare una risposta fondata sui tuoi dati.* -## Esegui l'Applicazione +## Esegui l'applicazione **Verifica il deployment:** -Assicurati che il file `.env` esista nella directory root con le credenziali Azure (create durante il Modulo 01). Esegui questo dalla directory del modulo (`03-rag/`): +Assicurati che il file `.env` esista nella directory principale con le credenziali Azure (creato durante il Modulo 01). Esegui questo dal modulo directory (`03-rag/`): **Bash:** ```bash -cat ../.env # Dovrebbe mostrare AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Deve mostrare AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -261,37 +260,37 @@ Get-Content ..\.env # Dovrebbe mostrare AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Avvia l'applicazione:** -> **Nota:** Se hai già avviato tutte le applicazioni usando `./start-all.sh` dalla directory root (come descritto nel Modulo 01), questo modulo è già in esecuzione sulla porta 8081. Puoi saltare i comandi di avvio qui sotto e andare direttamente su http://localhost:8081. +> **Nota:** Se hai già avviato tutte le applicazioni usando `./start-all.sh` dalla directory principale (come descritto nel Modulo 01), questo modulo è già in esecuzione sulla porta 8081. Puoi saltare i comandi di avvio qui sotto e andare direttamente a http://localhost:8081. **Opzione 1: Usare Spring Boot Dashboard (Consigliato per utenti VS Code)** -Il container di sviluppo include l’estensione Spring Boot Dashboard, che fornisce un'interfaccia visiva per gestire tutte le applicazioni Spring Boot. Puoi trovarla nella Activity Bar a sinistra in VS Code (cerca l’icona di Spring Boot). +Il container di sviluppo include l'estensione Spring Boot Dashboard, che fornisce un'interfaccia visiva per gestire tutte le applicazioni Spring Boot. La trovi nella Activity Bar a sinistra di VS Code (cerca l'icona Spring Boot). -Dal Spring Boot Dashboard, puoi: -- Vedere tutte le applicazioni Spring Boot disponibili nello workspace -- Avviare/fermare applicazioni con un solo clic -- Visualizzare i log delle applicazioni in tempo reale -- Monitorare lo stato delle applicazioni +Dal Spring Boot Dashboard puoi: +- Vedere tutte le applicazioni Spring Boot disponibili nell'area di lavoro +- Avviare/fermare applicazioni con un click +- Visualizzare i log applicazione in tempo reale +- Monitorare lo stato dell'applicazione -Basta cliccare il pulsante play accanto a "rag" per avviare questo modulo, oppure avviare tutti i moduli insieme. +Clicca semplicemente il pulsante play accanto a "rag" per avviare questo modulo, oppure avvia tutti i moduli insieme. Spring Boot Dashboard -*Questa schermata mostra il Spring Boot Dashboard in VS Code, dove puoi avviare, fermare e monitorare visivamente le applicazioni.* +*Questo screenshot mostra il Spring Boot Dashboard in VS Code, dove puoi avviare, fermare e monitorare le applicazioni visivamente.* -**Opzione 2: Usare gli script shell** +**Opzione 2: Usare script shell** -Avvia tutte le applicazioni web (moduli 01-04): +Avvia tutte le web app (moduli 01-04): **Bash:** ```bash -cd .. # Dalla directory principale +cd .. # Dalla directory radice ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Dalla directory root +cd .. # Dalla directory principale .\start-all.ps1 ``` @@ -309,7 +308,7 @@ cd 03-rag .\start.ps1 ``` -Entrambi gli script caricano automaticamente le variabili d’ambiente dal file `.env` nella root e compileranno i JAR se non esistono. +Entrambi gli script caricano automaticamente le variabili d'ambiente dal file `.env` nella root e compileranno i JAR se non esistono. > **Nota:** Se preferisci compilare manualmente tutti i moduli prima di avviare: > @@ -325,113 +324,113 @@ Entrambi gli script caricano automaticamente le variabili d’ambiente dal file > mvn clean package -DskipTests > ``` -Apri http://localhost:8081 nel browser. +Apri http://localhost:8081 nel tuo browser. **Per fermare:** **Bash:** ```bash ./stop.sh # Solo questo modulo -# O +# Oppure cd .. && ./stop-all.sh # Tutti i moduli ``` **PowerShell:** ```powershell .\stop.ps1 # Solo questo modulo -# O +# Oppure cd ..; .\stop-all.ps1 # Tutti i moduli ``` -## Uso dell'Applicazione +## Usare l'applicazione -L'applicazione fornisce un'interfaccia web per il caricamento dei documenti e per porre domande. +L'applicazione fornisce un'interfaccia web per caricare documenti e fare domande. -Interfaccia Applicazione RAG +Interfaccia applicazione RAG -*Questa schermata mostra l’interfaccia dell’applicazione RAG dove carichi documenti e poni domande.* +*Questo screenshot mostra l'interfaccia dell'applicazione RAG dove carichi documenti e fai domande.* -### Carica un Documento +### Carica un documento -Inizia caricando un documento - i file TXT sono i migliori per i test. Un `sample-document.txt` è fornito in questa directory e contiene informazioni sulle funzionalità di LangChain4j, implementazione RAG e best practices - perfetto per testare il sistema. +Inizia caricando un documento - i file TXT sono ideali per i test. Un `sample-document.txt` è fornito in questa directory e contiene informazioni sulle funzionalità di LangChain4j, l'implementazione RAG e le best practice - perfetto per testare il sistema. -Il sistema processa il tuo documento, lo suddivide in chunk e crea embeddings per ogni chunk. Questo avviene automaticamente al caricamento. +Il sistema processa il tuo documento, lo suddivide in chunk e crea gli embedding per ogni chunk. Questo avviene automaticamente durante il caricamento. -### Poni Domande +### Fai domande -Ora poni domande specifiche sul contenuto del documento. Prova qualcosa di fattuale che sia chiaramente indicato nel documento. Il sistema cerca chunk rilevanti, li include nel prompt e genera una risposta. +Ora poni domande specifiche sul contenuto del documento. Prova qualcosa di fattuale e chiaramente espresso nel documento. Il sistema cerca i chunk rilevanti, li include nel prompt e genera una risposta. -### Verifica le Fonti +### Controlla i riferimenti delle fonti -Nota che ogni risposta include riferimenti alle fonti con i punteggi di similarità. Questi punteggi (da 0 a 1) mostrano quanto ogni chunk era rilevante per la tua domanda. Punteggi più alti significano corrispondenze migliori. Questo ti permette di verificare la risposta confrontandola con il materiale sorgente. +Nota che ogni risposta include riferimenti alle fonti con punteggi di similarità. Questi punteggi (da 0 a 1) mostrano quanto ogni chunk era rilevante per la tua domanda. Punteggi più alti indicano corrispondenze migliori. Questo ti permette di verificare la risposta rispetto al materiale di origine. -Risultati Query RAG +Risultati query RAG -*Questa schermata mostra i risultati della query con la risposta generata, i riferimenti alle fonti e i punteggi di rilevanza per ogni chunk recuperato.* +*Questo screenshot mostra i risultati della query con la risposta generata, i riferimenti alle fonti e i punteggi di rilevanza per ogni chunk recuperato.* -### Sperimenta con le Domande +### Sperimenta con le domande Prova diversi tipi di domande: -- Fatti specifici: "Qual è l’argomento principale?" +- Fatti specifici: "Qual è l'argomento principale?" - Confronti: "Qual è la differenza tra X e Y?" -- Sommari: "Riassumi i punti chiave riguardo a Z" +- Sommari: "Riassumi i punti chiave su Z" -Osserva come cambiano i punteggi di rilevanza in base a quanto la tua domanda corrisponde al contenuto del documento. +Guarda come cambiano i punteggi di rilevanza in base a quanto la tua domanda corrisponde al contenuto del documento. -## Concetti Chiave +## Concetti chiave -### Strategia di Suddivisione in Chunk +### Strategia di suddivisione in chunk -I documenti sono suddivisi in chunk da 300 token con 30 token di sovrapposizione. Questo equilibrio garantisce che ogni chunk abbia abbastanza contesto per essere significativo ma rimanga sufficientemente piccolo per includere più chunk in un prompt. +I documenti vengono suddivisi in chunk da 300 token con 30 token di sovrapposizione. Questo equilibrio garantisce che ogni chunk abbia abbastanza contesto per essere significativo e allo stesso tempo rimanga abbastanza piccolo da includere più chunk in un prompt. -### Punteggi di Similarità +### Punteggi di similarità -Ogni chunk recuperato ha un punteggio di similarità compreso tra 0 e 1 che indica quanto si avvicina alla domanda dell’utente. Il diagramma sottostante visualizza gli intervalli di punteggio e come il sistema li usa per filtrare i risultati: +Ogni chunk recuperato ha un punteggio di similarità che va da 0 a 1 e indica quanto corrisponde alla domanda dell'utente. Il diagramma seguente visualizza gli intervalli dei punteggi e come il sistema li usa per filtrare i risultati: -Punteggi di Similarità +Punteggi di similarità -*Questo diagramma mostra gli intervalli di punteggio da 0 a 1, con una soglia minima di 0.5 che filtra i chunk irrilevanti.* +*Questo diagramma mostra gli intervalli di punteggio da 0 a 1, con una soglia minima di 0.5 che filtra i chunk non rilevanti.* -I punteggi variano da 0 a 1: +I punteggi vanno da 0 a 1: - 0.7-1.0: Altamente rilevante, corrispondenza esatta - 0.5-0.7: Rilevante, buon contesto - Sotto 0.5: Filtrato, troppo dissimile -Il sistema recupera solo chunk sopra la soglia minima per garantire qualità. +Il sistema recupera solo i chunk sopra la soglia minima per garantire qualità. -Gli embeddings funzionano bene quando i significati si raggruppano chiaramente, ma hanno punti ciechi. Il diagramma sottostante mostra i modi comuni di fallimento — chunk troppo grandi producono vettori confusi, chunk troppo piccoli mancano di contesto, termini ambigui puntano a più cluster, e ricerche esatte (ID, numeri di parte) non funzionano affatto con gli embeddings: +Gli embeddings funzionano bene quando il significato forma cluster chiari, ma hanno punti ciechi. Il diagramma sotto mostra i comuni modi di fallimento — chunk troppo grandi producono vettori confusi, chunk troppo piccoli mancano di contesto, termini ambigui puntano a più cluster, e ricerche di corrispondenza esatta (ID, numeri di parte) non funzionano affatto con gli embeddings: -Modi di Fallimento degli Embeddings +Modalità di fallimento degli embedding -*Questo diagramma mostra i modi comuni di fallimento degli embeddings: chunk troppo grandi, chunk troppo piccoli, termini ambigui che puntano a cluster multipli, e ricerche esatte come ID.* +*Questo diagramma mostra i comuni errori degli embedding: chunk troppo grandi, chunk troppo piccoli, termini ambigui che puntano a più cluster, e ricerche di corrispondenza esatta come ID.* -### Memorizzazione in Memoria +### Storage in memoria -Questo modulo usa una memorizzazione in memoria per semplicità. Quando riavvii l’applicazione, i documenti caricati vanno persi. I sistemi di produzione usano database vettoriali persistenti come Qdrant o Azure AI Search. +Questo modulo usa storage in memoria per semplicità. Quando riavvii l'applicazione, i documenti caricati vengono persi. I sistemi di produzione usano database vettoriali persistenti come Qdrant o Azure AI Search. -### Gestione della Finestra di Contesto +### Gestione della finestra di contesto -Ogni modello ha una massima finestra di contesto. Non puoi includere ogni chunk da un documento lungo. Il sistema recupera i primi N chunk più rilevanti (default 5) per restare nei limiti fornendo abbastanza contesto per risposte accurate. +Ogni modello ha una finestra di contesto massima. Non puoi includere ogni chunk di un documento grande. Il sistema recupera i primi N chunk più rilevanti (default 5) per rimanere entro i limiti pur fornendo abbastanza contesto per risposte accurate. -## Quando RAG Conta +## Quando RAG conta -RAG non è sempre l’approccio giusto. La guida decisionale sottostante ti aiuta a capire quando RAG apporta valore rispetto a quando approcci più semplici — come includere direttamente il contenuto nel prompt o affidarsi alla conoscenza built-in del modello — sono sufficienti: +RAG non è sempre l'approccio giusto. La guida alla decisione qui sotto ti aiuta a determinare quando RAG aggiunge valore rispetto a quando approcci più semplici — come includere il contenuto direttamente nel prompt o affidarsi alla conoscenza incorporata del modello — sono sufficienti: -Quando Usare RAG +Quando usare RAG -*Questo diagramma mostra una guida decisionale per quando RAG apporta valore rispetto a quando approcci più semplici sono sufficienti.* +*Questo diagramma mostra una guida alla decisione per quando RAG aggiunge valore rispetto a quando approcci più semplici sono sufficienti.* -## Prossimi Passi +## Passaggi successivi -**Modulo Successivo:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Prossimo Modulo:** [04-tools - Agenti AI con Tool](../04-tools/README.md) --- -**Navigazione:** [← Precedente: Modulo 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Torna al Principale](../README.md) | [Successivo: Modulo 04 - Tools →](../04-tools/README.md) +**Navigazione:** [← Precedente: Modulo 02 - Ingegneria del Prompt](../02-prompt-engineering/README.md) | [Torna al Principale](../README.md) | [Successivo: Modulo 04 - Tools →](../04-tools/README.md) --- **Disclaimer**: -Questo documento è stato tradotto utilizzando il servizio di traduzione automatica [Co-op Translator](https://github.com/Azure/co-op-translator). Pur impegnandoci per garantire accuratezza, si prega di essere consapevoli che le traduzioni automatiche possono contenere errori o imprecisioni. Il documento originale nella sua lingua originale deve essere considerato la fonte autorevole. Per informazioni critiche, si consiglia di utilizzare una traduzione professionale effettuata da un essere umano. Non ci assumiamo alcuna responsabilità per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. +Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire la precisione, si prega di notare che le traduzioni automatizzate possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un essere umano. Non siamo responsabili per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. \ No newline at end of file diff --git a/translations/it/04-tools/README.md b/translations/it/04-tools/README.md index 7f922739d..01af8fba4 100644 --- a/translations/it/04-tools/README.md +++ b/translations/it/04-tools/README.md @@ -2,75 +2,75 @@ ## Indice -- [Video Walkthrough](../../../04-tools) -- [Cosa Imparerai](../../../04-tools) -- [Prerequisiti](../../../04-tools) -- [Comprendere gli Agenti AI con Strumenti](../../../04-tools) -- [Come Funziona la Chiamata agli Strumenti](../../../04-tools) - - [Definizioni degli Strumenti](../../../04-tools) - - [Processo Decisionale](../../../04-tools) - - [Esecuzione](../../../04-tools) - - [Generazione della Risposta](../../../04-tools) - - [Architettura: Auto-Iniezione di Spring Boot](../../../04-tools) -- [Catena di Strumenti](../../../04-tools) -- [Avvia l'Applicazione](../../../04-tools) -- [Uso dell'Applicazione](../../../04-tools) - - [Prova l'Uso Semplice dello Strumento](../../../04-tools) - - [Test della Catena di Strumenti](../../../04-tools) - - [Guarda il Flusso della Conversazione](../../../04-tools) - - [Sperimenta con Diverse Richieste](../../../04-tools) -- [Concetti Chiave](../../../04-tools) - - [Pattern ReAct (Ragionamento e Azione)](../../../04-tools) - - [Le Descrizioni degli Strumenti Contano](../../../04-tools) - - [Gestione della Sessione](../../../04-tools) - - [Gestione degli Errori](../../../04-tools) -- [Strumenti Disponibili](../../../04-tools) -- [Quando Usare Agenti Basati su Strumenti](../../../04-tools) -- [Strumenti vs RAG](../../../04-tools) -- [Prossimi Passi](../../../04-tools) - -## Video Walkthrough - -Guarda questa sessione live che spiega come iniziare con questo modulo: - -Agenti AI con Strumenti e MCP - Sessione Live +- [Video Esplicativo](#video-esplicativo) +- [Cosa Imparerai](#cosa-imparerai) +- [Prerequisiti](#prerequisiti) +- [Comprendere gli Agenti AI con Strumenti](#comprendere-gli-agenti-ai-con-strumenti) +- [Come Funziona la Chiamata agli Strumenti](#come-funziona-la-chiamata-agli-strumenti) + - [Definizioni degli Strumenti](#definizioni-degli-strumenti) + - [Processo Decisionale](#processo-decisionale) + - [Esecuzione](#esecuzione) + - [Generazione della Risposta](#generazione-della-risposta) + - [Architettura: Auto-Wiring di Spring Boot](#architettura-auto-wiring-di-spring-boot) +- [Concatenazione degli Strumenti](#concatenazione-degli-strumenti) +- [Esegui l'Applicazione](#esegui-lapplicazione) +- [Utilizzo dell'Applicazione](#uso-dellapplicazione) + - [Prova l'Uso Semplice di uno Strumento](#prova-un-uso-semplice-degli-strumenti) + - [Testa la Concatenazione degli Strumenti](#prova-la-catena-di-strumenti) + - [Visualizza il Flusso della Conversazione](#vedi-il-flusso-di-conversazione) + - [Sperimenta con Richieste Diverse](#sperimenta-con-diverse-richieste) +- [Concetti Chiave](#concetti-chiave) + - [Pattern ReAct (Ragionamento e Azione)](#pattern-react-ragionare-e-agire) + - [Importanza delle Descrizioni degli Strumenti](#le-descrizioni-degli-strumenti-contano) + - [Gestione della Sessione](#gestione-della-sessione) + - [Gestione degli Errori](#gestione-degli-errori) +- [Strumenti Disponibili](#strumenti-disponibili) +- [Quando Usare Agenti Basati su Strumenti](#quando-usare-agenti-basati-su-strumenti) +- [Strumenti vs RAG](#strumenti-vs-rag) +- [Passi Successivi](#passi-successivi) + +## Video Esplicativo + +Guarda questa sessione dal vivo che spiega come iniziare con questo modulo: + +AI Agents with Tools and MCP - Live Session ## Cosa Imparerai -Finora, hai imparato come conversare con l'AI, strutturare efficacemente i prompt e ancorare le risposte ai tuoi documenti. Ma esiste ancora un limite fondamentale: i modelli linguistici possono solo generare testo. Non possono controllare il meteo, effettuare calcoli, interrogare database o interagire con sistemi esterni. +Finora, hai imparato come avere conversazioni con l'AI, strutturare efficacemente i prompt e basare le risposte sui tuoi documenti. Ma c'è ancora una limitazione fondamentale: i modelli linguistici possono solo generare testo. Non possono controllare il meteo, eseguire calcoli, interrogare database o interagire con sistemi esterni. -Gli strumenti cambiano questo. Dando al modello accesso a funzioni che può chiamare, lo trasformi da generatore di testo a un agente che può compiere azioni. Il modello decide quando ha bisogno di uno strumento, quale strumento usare e quali parametri passare. Il tuo codice esegue la funzione e restituisce il risultato. Il modello incorpora quel risultato nella sua risposta. +Gli strumenti cambiano questo. Fornendo al modello l'accesso a funzioni che può chiamare, lo trasformi da generatore di testo a un agente che può eseguire azioni. Il modello decide quando ha bisogno di uno strumento, quale usare e quali parametri passare. Il tuo codice esegue la funzione e restituisce il risultato. Il modello incorpora quel risultato nella sua risposta. ## Prerequisiti -- Completato il [Modulo 01 - Introduzione](../01-introduction/README.md) (risorse Azure OpenAI distribuite) +- Completato [Modulo 01 - Introduzione](../01-introduction/README.md) (risorse Azure OpenAI distribuite) - Completati i moduli precedenti consigliati (questo modulo fa riferimento ai [concetti RAG del Modulo 03](../03-rag/README.md) nel confronto Strumenti vs RAG) -- File `.env` nella directory radice con le credenziali Azure (creato con `azd up` nel Modulo 01) +- File `.env` nella directory radice con credenziali Azure (creato da `azd up` nel Modulo 01) > **Nota:** Se non hai completato il Modulo 01, segui prima le istruzioni di distribuzione lì. ## Comprendere gli Agenti AI con Strumenti -> **📝 Nota:** Il termine "agenti" in questo modulo si riferisce ad assistenti AI potenziati con capacità di chiamata di strumenti. Questo è diverso dai pattern di **Agentic AI** (agenti autonomi con pianificazione, memoria e ragionamento multi-step) che tratteremo in [Modulo 05: MCP](../05-mcp/README.md). +> **📝 Nota:** Il termine "agenti" in questo modulo si riferisce ad assistenti AI arricchiti con capacità di chiamata di strumenti. Questo è diverso dai pattern **Agentic AI** (agenti autonomi con pianificazione, memoria e ragionamento multi-step) che tratteremo in [Modulo 05: MCP](../05-mcp/README.md). -Senza strumenti, un modello linguistico può solo generare testo dai dati di addestramento. Chiedigli il meteo attuale e deve indovinare. Dagli strumenti, può chiamare un'API meteo, effettuare calcoli o interrogare un database — poi inserire quei risultati reali nella risposta. +Senza strumenti, un modello linguistico può solo generare testo dai suoi dati di addestramento. Chiedigli il meteo attuale e deve indovinare. Dagli strumenti, può chiamare un'API meteo, eseguire calcoli o interrogare un database — poi integra quei risultati reali nella risposta. Senza Strumenti vs Con Strumenti -*Senza strumenti il modello può solo indovinare — con gli strumenti può chiamare API, eseguire calcoli e restituire dati in tempo reale.* +*Senza strumenti il modello può solo indovinare — con strumenti può chiamare API, eseguire calcoli e restituire dati in tempo reale.* -Un agente AI con strumenti segue un pattern **Reasoning and Acting (ReAct)**. Il modello non si limita a rispondere — pensa a ciò di cui ha bisogno, agisce chiamando uno strumento, osserva il risultato e decide se agire ancora o fornire la risposta finale: +Un agente AI con strumenti segue un pattern di **Ragionamento e Azione (ReAct)**. Il modello non si limita a rispondere — pensa a ciò di cui ha bisogno, agisce chiamando uno strumento, osserva il risultato, poi decide se agire nuovamente o fornire la risposta finale: -1. **Ragiona** — L'agente analizza la domanda dell'utente e determina quali informazioni servono -2. **Agisci** — L'agente seleziona lo strumento giusto, genera i parametri corretti e lo chiama -3. **Osserva** — L'agente riceve l'output dello strumento e valuta il risultato -4. **Ripeti o Rispondi** — Se servono altri dati, l'agente ripete; altrimenti compone una risposta in linguaggio naturale +1. **Ragionare** — L'agente analizza la domanda dell'utente e determina quali informazioni servono +2. **Agire** — L'agente seleziona lo strumento giusto, genera i parametri corretti e lo chiama +3. **Osservare** — L'agente riceve l'output dello strumento e valuta il risultato +4. **Ripetere o Rispondere** — Se servono più dati, l'agente ricomincia; altrimenti compone una risposta in linguaggio naturale Pattern ReAct -*Il ciclo ReAct — l'agente ragiona su cosa fare, agisce chiamando uno strumento, osserva il risultato e ripete fino a fornire la risposta finale.* +*Il ciclo ReAct — l'agente ragiona su cosa fare, agisce chiamando uno strumento, osserva il risultato e ripete finché può fornire la risposta finale.* -Questo accade in modo automatico. Definisci gli strumenti e le loro descrizioni. Il modello gestisce le decisioni su quando e come usarli. +Questo avviene automaticamente. Definisci tu gli strumenti e le loro descrizioni. Il modello si occupa di decidere quando e come usarli. ## Come Funziona la Chiamata agli Strumenti @@ -78,7 +78,7 @@ Questo accade in modo automatico. Definisci gli strumenti e le loro descrizioni. [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Definisci funzioni con descrizioni chiare e specifiche dei parametri. Il modello vede queste descrizioni nel prompt di sistema e capisce cosa fa ogni strumento. +Definisci funzioni con descrizioni chiare e specifiche sui parametri. Il modello vede queste descrizioni nel prompt di sistema e capisce cosa fa ogni strumento. ```java @Component @@ -96,137 +96,137 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Assistant è automaticamente collegato da Spring Boot con: +// Assistant è automaticamente configurato da Spring Boot con: // - Bean ChatModel -// - Tutti i metodi @Tool delle classi @Component +// - Tutti i metodi @Tool dalle classi @Component // - ChatMemoryProvider per la gestione della sessione ``` -Il diagramma seguente analizza ogni annotazione e mostra come ogni pezzo aiuta l'AI a capire quando chiamare lo strumento e quali argomenti passare: +Il diagramma sottostante scompone ogni annotazione e mostra come ciascun elemento aiuti l'AI a capire quando chiamare lo strumento e quali argomenti passare: Anatomia delle Definizioni degli Strumenti -*Anatomia di una definizione di strumento — @Tool indica all'AI quando usarlo, @P descrive ogni parametro, e @AiService collega tutto all'avvio.* +*Anatomia di una definizione di strumento — @Tool dice all'AI quando usarlo, @P descrive ogni parametro, e @AiService connette tutto all'avvio.* > **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) e chiedi: -> - "Come potrei integrare una vera API meteo come OpenWeatherMap invece dei dati di esempio?" -> - "Cosa rende una buona descrizione dello strumento che aiuta l'AI ad usarlo correttamente?" -> - "Come gestisco errori API e limiti di chiamate nelle implementazioni degli strumenti?" +> - "Come integrerei una vera API meteo come OpenWeatherMap invece dei dati mock?" +> - "Cosa rende una descrizione di uno strumento efficace per permettere all'AI di usarlo correttamente?" +> - "Come gestisco errori API e limiti di chiamata nelle implementazioni degli strumenti?" ### Processo Decisionale -Quando un utente chiede "Che tempo fa a Seattle?", il modello non sceglie uno strumento a caso. Confronta l'intento dell'utente con ogni descrizione degli strumenti a cui ha accesso, valuta la rilevanza di ciascuno e seleziona la corrispondenza migliore. Genera quindi una chiamata di funzione strutturata con i parametri corretti — in questo caso impostando `location` a `"Seattle"`. +Quando un utente chiede "Com'è il meteo a Seattle?", il modello non sceglie uno strumento a caso. Confronta l'intento dell'utente con ogni descrizione strumento accessibile, assegna un punteggio di pertinenza e seleziona la corrispondenza migliore. Genera quindi una chiamata di funzione strutturata con i parametri corretti — in questo caso, impostando `location` su `"Seattle"`. -Se nessuno strumento corrisponde alla richiesta dell'utente, il modello risponde con le sue conoscenze interne. Se più strumenti corrispondono, sceglie quello più specifico. +Se nessuno strumento corrisponde alla richiesta, il modello risponde dalla sua conoscenza. Se più strumenti corrispondono, sceglie quello più specifico. Come l'AI Decide Quale Strumento Usare -*Il modello valuta ogni strumento disponibile rispetto all'intento dell'utente e seleziona la corrispondenza migliore — perciò scrivere descrizioni chiare e specifiche è importante.* +*Il modello valuta ogni strumento disponibile rispetto all'intento dell'utente e seleziona la corrispondenza migliore — per questo scrivere descrizioni chiare e specifiche è importante.* ### Esecuzione [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot collega automaticamente l'interfaccia dichiarativa `@AiService` con tutti gli strumenti registrati, e LangChain4j esegue le chiamate agli strumenti automaticamente. Dietro le quinte, una chiamata completa ad uno strumento scorre attraverso sei fasi — dalla domanda in linguaggio naturale dell'utente fino alla risposta in linguaggio naturale: +Spring Boot auto-collega l'interfaccia dichiarativa `@AiService` con tutti gli strumenti registrati, e LangChain4j esegue automaticamente le chiamate agli strumenti. Dietro le quinte, una chiamata completa passa attraverso sei fasi — dalla domanda in linguaggio naturale dell'utente fino alla risposta in linguaggio naturale: -Flusso di Chiamata agli Strumenti +Flusso della Chiamata agli Strumenti -*Il flusso end-to-end — l'utente fa una domanda, il modello seleziona uno strumento, LangChain4j lo esegue, e il modello intreccia il risultato in una risposta naturale.* +*Il flusso end-to-end — l'utente chiede, il modello seleziona uno strumento, LangChain4j lo esegue, e il modello integra il risultato in una risposta naturale.* -Se hai eseguito il [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) nel Modulo 00, hai già visto questo pattern in azione — anche gli strumenti `Calculator` venivano chiamati nello stesso modo. Il diagramma di sequenza seguente mostra esattamente cosa è successo sotto il cofano durante quella demo: +Dietro le quinte, `AiServices` esegue lo stesso ciclo di chiamata per qualsiasi strumento — qui illustrato con un semplice `Calculator`. Il diagramma di sequenza qui sotto mostra esattamente cosa succede internamente: -Diagramma di Sequenza per la Chiamata agli Strumenti +Diagramma di Sequenza della Chiamata agli Strumenti -*Il ciclo di chiamata agli strumenti dalla demo Quick Start — `AiServices` manda il tuo messaggio e gli schemi degli strumenti al LLM, il LLM risponde con una chiamata di funzione come `add(42, 58)`, LangChain4j esegue il metodo `Calculator` localmente, e restituisce il risultato per la risposta finale.* +*Il ciclo di chiamata dello strumento — `AiServices` invia il tuo messaggio e gli schemi degli strumenti al LLM, il LLM risponde con una chiamata di funzione come `add(42, 58)`, LangChain4j esegue localmente il metodo `Calculator`, e restituisce il risultato per la risposta finale.* > **🤖 Prova con [GitHub Copilot](https://github.com/features/copilot) Chat:** Apri [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) e chiedi: -> - "Come funziona il pattern ReAct e perché è efficace per gli agenti AI?" +> - "Come funziona il pattern ReAct e perché è efficace per agenti AI?" > - "Come decide l'agente quale strumento usare e in che ordine?" -> - "Cosa succede se l'esecuzione di uno strumento fallisce - come gestire gli errori in modo robusto?" +> - "Cosa succede se l'esecuzione di uno strumento fallisce - come gestire robustamente gli errori?" ### Generazione della Risposta -Il modello riceve i dati meteorologici e li formatta in una risposta in linguaggio naturale per l'utente. +Il modello riceve i dati meteo e li formatta in una risposta in linguaggio naturale per l'utente. -### Architettura: Auto-Iniezione di Spring Boot +### Architettura: Auto-Wiring di Spring Boot -Questo modulo usa l'integrazione LangChain4j con Spring Boot tramite interfacce dichiarative `@AiService`. All'avvio Spring Boot scopre ogni `@Component` che contiene metodi annotati `@Tool`, il tuo bean `ChatModel` e il `ChatMemoryProvider` — quindi li collega tutti in una singola interfaccia `Assistant` senza necessità di codice boilerplate. +Questo modulo usa l'integrazione Spring Boot di LangChain4j con interfacce dichiarative `@AiService`. All'avvio Spring Boot scopre ogni `@Component` che contiene metodi `@Tool`, il bean `ChatModel`, e il `ChatMemoryProvider` — poi li connette tutti in una singola interfaccia `Assistant` senza alcun boilerplate. -Architettura Auto-Iniezione di Spring Boot +Architettura Auto-Wiring Spring Boot -*L'interfaccia @AiService unisce il ChatModel, i componenti degli strumenti e il provider di memoria — Spring Boot gestisce automaticamente tutta l'iniezione.* +*L'interfaccia @AiService collega ChatModel, componenti degli strumenti e provider di memoria — Spring Boot gestisce automaticamente il wiring.* -Ecco il ciclo di vita completo della richiesta come diagramma di sequenza — dalla richiesta HTTP attraverso controller, servizio e proxy auto-iniettato, fino all'esecuzione dello strumento e ritorno: +Ecco il ciclo completo della richiesta come diagramma di sequenza — dalla richiesta HTTP passando per controller, servizio e proxy auto-collegato, fino all'esecuzione dello strumento e ritorno: -Sequenza di Chiamata degli Strumenti con Spring Boot +Sequenza di Chiamata Strumento in Spring Boot -*Il ciclo di vita completo di una richiesta in Spring Boot — la richiesta HTTP passa attraverso controller e servizio fino al proxy Assistant auto-iniettato, che orchestra automaticamente la chiamata al LLM e agli strumenti.* +*Il ciclo completo della richiesta Spring Boot — la richiesta HTTP passa per controller e servizio fino al proxy Assistant auto-wired, che orchestra LLM e chiamate agli strumenti automaticamente.* -Principali vantaggi di questo approccio: +Vantaggi chiave di questo approccio: -- **Auto-iniezione di Spring Boot** — ChatModel e strumenti iniettati automaticamente +- **Auto-wiring di Spring Boot** — ChatModel e strumenti iniettati automaticamente - **Pattern @MemoryId** — Gestione automatica della memoria basata sulla sessione -- **Istanza singola** — Assistant creato una volta e riutilizzato per migliori prestazioni +- **Singola istanza** — Assistant creato una volta e riutilizzato per migliori prestazioni - **Esecuzione type-safe** — Metodi Java chiamati direttamente con conversione tipi -- **Orchestrazione multi-turno** — Gestisce la catena di strumenti automaticamente -- **Zero boilerplate** — Nessuna chiamata manuale `AiServices.builder()` o hashmap per la memoria +- **Orchestrazione multi-turn** — Gestisce automaticamente concatenazione degli strumenti +- **Zero boilerplate** — Nessuna chiamata manuale a `AiServices.builder()` o mappe di memoria -Approcci alternativi (manuale `AiServices.builder()`) richiedono più codice e non beneficiano dell'integrazione con Spring Boot. +Approcci alternativi (costruzione manuale con `AiServices.builder()`) richiedono più codice e perdono i vantaggi dell’integrazione con Spring Boot. -## Catena di Strumenti +## Concatenazione degli Strumenti -**Catena di Strumenti** — La vera potenza degli agenti basati su strumenti emerge quando una singola domanda richiede più strumenti. Chiedi "Che tempo fa a Seattle in Fahrenheit?" e l'agente collega automaticamente due strumenti: prima chiama `getCurrentWeather` per ottenere la temperatura in Celsius, poi passa quel valore a `celsiusToFahrenheit` per la conversione — tutto in un unico turno di conversazione. +**Tool Chaining** — La vera potenza degli agenti basati su strumenti si manifesta quando una singola domanda richiede più strumenti. Chiedi "Com'è il meteo a Seattle in Fahrenheit?" e l'agente concatena automaticamente due strumenti: prima chiama `getCurrentWeather` per ottenere la temperatura in Celsius, poi passa quel valore a `celsiusToFahrenheit` per la conversione — tutto in un solo turno di conversazione. -Esempio di Catena di Strumenti +Esempio di Concatenazione degli Strumenti -*Catena di strumenti in azione — l'agente chiama prima getCurrentWeather, poi passa il risultato in Celsius a celsiusToFahrenheit e fornisce una risposta combinata.* +*Concatenazione degli strumenti in azione — l'agente chiama prima getCurrentWeather, poi passa il risultato Celsius a celsiusToFahrenheit, e fornisce una risposta combinata.* -**Gestione Elegante degli Errori** — Chiedi il meteo in una città che non è nei dati di esempio. Lo strumento restituisce un messaggio di errore, e l'AI spiega che non può aiutare invece di bloccarsi. Gli strumenti falliscono in modo sicuro. Il diagramma sotto confronta i due approcci — con una corretta gestione degli errori, l'agente cattura l'eccezione e risponde in maniera utile, mentre senza di essa l'intera applicazione va in crash: +**Gestione Elegante degli Errori** — Chiedi il meteo in una città non presente nei dati mock. Lo strumento restituisce un messaggio di errore, e l'AI spiega che non può aiutare invece di andare in crash. Gli strumenti falliscono in modo sicuro. Il diagramma seguente confronta i due approcci — con una gestione corretta degli errori, l'agente intercetta l'eccezione e risponde utilmente, mentre senza di essa l'intera applicazione crasha: Flusso di Gestione degli Errori -*Quando uno strumento fallisce, l'agente cattura l'errore e risponde con una spiegazione utile invece di andare in crash.* +*Quando uno strumento fallisce, l'agente cattura l'errore e risponde con una spiegazione utile anziché crashare.* -Questo accade in un singolo turno di conversazione. L'agente orchestra più chiamate agli strumenti autonomamente. +Questo avviene in un singolo turno di conversazione. L'agente gestisce autonomamente più chiamate di strumenti. -## Avvia l'Applicazione +## Esegui l'Applicazione **Verifica la distribuzione:** -Assicurati che il file `.env` esista nella directory radice con le credenziali Azure (creato durante il Modulo 01). Esegui questo dal directory del modulo (`04-tools/`): +Assicurati che il file `.env` esista nella directory radice con le credenziali Azure (creato durante il Modulo 01). Esegui questo dal direttorio del modulo (`04-tools/`): -**Bash:** +**Bash:** ```bash cat ../.env # Dovrebbe mostrare AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Dovrebbe mostrare AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Avvia l'applicazione:** -> **Nota:** Se hai già avviato tutte le applicazioni usando `./start-all.sh` dalla directory radice (come descritto nel Modulo 01), questo modulo è già in esecuzione sulla porta 8084. Puoi saltare i comandi di avvio qui sotto e andare direttamente su http://localhost:8084. +> **Nota:** Se hai già avviato tutte le applicazioni usando `./start-all.sh` dalla directory radice (come descritto nel Modulo 01), questo modulo è già in esecuzione sulla porta 8084. Puoi saltare i comandi di avvio di seguito e andare direttamente a http://localhost:8084. -**Opzione 1: Uso del Spring Boot Dashboard (Raccomandato per utenti VS Code)** +**Opzione 1: Usare Spring Boot Dashboard (Consigliato per utenti VS Code)** -Il container di sviluppo include l'estensione Spring Boot Dashboard, che fornisce un'interfaccia visiva per gestire tutte le applicazioni Spring Boot. Puoi trovarlo nella Activity Bar sulla sinistra di VS Code (cerca l'icona di Spring Boot). +Il contenitore di sviluppo include l'estensione Spring Boot Dashboard, che fornisce un'interfaccia visiva per gestire tutte le applicazioni Spring Boot. Puoi trovarla nella Activity Bar a sinistra di VS Code (cerca l'icona Spring Boot). -Dal Spring Boot Dashboard, puoi: -- Vedere tutte le applicazioni Spring Boot disponibili nello spazio di lavoro -- Avviare/fermare applicazioni con un solo clic -- Visualizzare in tempo reale i log delle applicazioni -- Monitorare lo stato dell'applicazione -Basta cliccare sul pulsante play accanto a "tools" per avviare questo modulo, oppure avviare tutti i moduli insieme. +Dal Spring Boot Dashboard puoi: +- Vedere tutte le applicazioni Spring Boot disponibili nel workspace +- Avviare/fermare applicazioni con un clic +- Visualizzare i log in tempo reale +- Monitorare lo stato delle applicazioni -Ecco come appare la Spring Boot Dashboard in VS Code: +Clicca semplicemente il pulsante play accanto a "tools" per avviare questo modulo, o avvia tutti i moduli insieme. -Spring Boot Dashboard +Ecco come appare il Spring Boot Dashboard in VS Code: +Cruscotto Spring Boot -*La Spring Boot Dashboard in VS Code — avvia, ferma e monitora tutti i moduli da un unico posto* +*Il Cruscotto Spring Boot in VS Code — avvia, ferma e monitora tutti i moduli da un unico posto* -**Opzione 2: Utilizzo di script shell** +**Opzione 2: Uso di script shell** Avvia tutte le applicazioni web (moduli 01-04): @@ -238,7 +238,7 @@ cd .. # Dalla directory radice **PowerShell:** ```powershell -cd .. # Dalla directory radice +cd .. # Dalla directory root .\start-all.ps1 ``` @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Entrambi gli script caricano automaticamente le variabili d’ambiente dal file `.env` nella radice e compileranno i JAR se non esistono. +Entrambi gli script caricano automaticamente le variabili d'ambiente dal file `.env` nella root e compileranno i JAR se non esistono. -> **Nota:** Se preferisci compilare tutti i moduli manualmente prima di avviare: +> **Nota:** Se preferisci compilare manualmente tutti i moduli prima dell'avvio: > > **Bash:** > ```bash @@ -290,90 +290,90 @@ cd .. && ./stop-all.sh # Tutti i moduli cd ..; .\stop-all.ps1 # Tutti i moduli ``` -## Uso dell’Applicazione +## Uso dell'Applicazione -L’applicazione fornisce un’interfaccia web dove puoi interagire con un agente AI che ha accesso a strumenti meteo e di conversione della temperatura. Ecco come appare l’interfaccia — include esempi rapidi e un pannello chat per inviare richieste: +L'applicazione offre un'interfaccia web dove puoi interagire con un agente AI che ha accesso agli strumenti meteo e di conversione della temperatura. Ecco come appare l'interfaccia — include esempi rapidi e un pannello chat per inviare richieste: -AI Agent Tools Interface +Interfaccia Strumenti Agente AI -*L’interfaccia AI Agent Tools - esempi rapidi e interfaccia chat per interagire con gli strumenti* +*L'interfaccia Strumenti Agente AI - esempi rapidi e interfaccia chat per interagire con gli strumenti* ### Prova un Uso Semplice degli Strumenti -Inizia con una richiesta semplice: "Converti 100 gradi Fahrenheit in Celsius". L’agente riconosce che serve lo strumento di conversione della temperatura, lo richiama con i parametri corretti e restituisce il risultato. Nota quanto sembra naturale — non hai specificato quale strumento usare o come chiamarlo. +Inizia con una richiesta semplice: "Converti 100 gradi Fahrenheit in Celsius". L'agente riconosce che deve utilizzare lo strumento di conversione della temperatura, lo chiama con i parametri corretti e restituisce il risultato. Nota quanto sia naturale — non hai specificato quale strumento usare né come chiamarlo. ### Prova la Catena di Strumenti -Ora prova qualcosa di più complesso: "Com'è il meteo a Seattle e converti in Fahrenheit?" Guarda l’agente lavorare a questo per passi. Prima ottiene il meteo (che ritorna in Celsius), riconosce che deve convertire in Fahrenheit, chiama lo strumento di conversione, e combina entrambi i risultati in una singola risposta. +Ora prova qualcosa di più complesso: "Com'è il tempo a Seattle e converti la temperatura in Fahrenheit?" Guarda l'agente lavorare a tappe. Prima ottiene le condizioni meteo (che ritorna in Celsius), riconosce che deve convertire in Fahrenheit, chiama lo strumento di conversione e combina entrambi i risultati in una risposta unica. -### Vedi il Flusso della Conversazione +### Vedi il Flusso di Conversazione -L’interfaccia chat conserva la cronologia delle conversazioni, permettendoti di avere interazioni multi-turno. Puoi vedere tutte le query e risposte precedenti, rendendo facile tracciare la conversazione e capire come l’agente costruisce il contesto attraverso più scambi. +L'interfaccia chat mantiene la cronologia della conversazione, permettendoti di avere interazioni multi-turno. Puoi vedere tutte le query e risposte precedenti, rendendo facile tracciare la conversazione e capire come l'agente costruisca il contesto nel corso degli scambi. -Conversation with Multiple Tool Calls +Conversazione con Molteplici Chiamate a Strumenti *Conversazione multi-turno che mostra conversioni semplici, ricerche meteo e concatenamento di strumenti* -### Sperimenta con Richieste Diverse +### Sperimenta con Diverse Richieste Prova varie combinazioni: -- Ricerche meteo: "Com'è il meteo a Tokyo?" +- Ricerche meteo: "Che tempo fa a Tokyo?" - Conversioni di temperatura: "Quanto sono 25°C in Kelvin?" -- Query combinate: "Controlla il meteo a Parigi e dimmi se è sopra i 20°C" +- Query combinate: "Controlla il tempo a Parigi e dimmi se è sopra i 20°C" -Nota come l’agente interpreta il linguaggio naturale e lo mappa a chiamate appropriate agli strumenti. +Nota come l'agente interpreta il linguaggio naturale e lo mappa alle chiamate appropriate degli strumenti. ## Concetti Chiave -### Pattern ReAct (Reasoning and Acting) +### Pattern ReAct (Ragionare e Agire) -L’agente alterna tra ragionamento (decidere cosa fare) e azione (usare gli strumenti). Questo pattern permette la risoluzione autonoma dei problemi invece di rispondere solo a istruzioni. +L'agente alterna ragionamento (decidere cosa fare) e azione (uso degli strumenti). Questo pattern permette una risoluzione autonoma dei problemi più che una semplice risposta a istruzioni. ### Le Descrizioni degli Strumenti Contano -La qualità delle descrizioni degli strumenti influisce direttamente sull’efficacia dell’agente nell’utilizzarli. Descrizioni chiare e specifiche aiutano il modello a capire quando e come chiamare ciascuno strumento. +La qualità delle descrizioni degli strumenti influisce direttamente su quanto bene l'agente li utilizzi. Descrizioni chiare e specifiche aiutano il modello a capire quando e come chiamare ogni strumento. ### Gestione della Sessione -L’annotazione `@MemoryId` abilita la gestione automatica della memoria basata sulla sessione. Ogni ID di sessione ottiene la propria istanza di `ChatMemory` gestita dal bean `ChatMemoryProvider`, così più utenti possono interagire con l’agente simultaneamente senza che le conversazioni si mescolino. Il diagramma seguente mostra come più utenti vengono indirizzati a memorie isolate basate sui loro ID di sessione: +L'annotazione `@MemoryId` abilita la gestione automatica della memoria basata sulla sessione. Ogni ID sessione ottiene una propria istanza di `ChatMemory` gestita dal bean `ChatMemoryProvider`, così più utenti possono interagire con l'agente simultaneamente senza mescolare le conversazioni. Il diagramma seguente mostra come diversi utenti vengano indirizzati a memorie isolate in base ai loro ID sessione: -Session Management with @MemoryId +Gestione Sessione con @MemoryId -*Ogni ID di sessione mappa a una storia di conversazione isolata — gli utenti non vedono mai i messaggi degli altri.* +*Ogni ID sessione mappa a una cronologia conversazionale isolata — gli utenti non vedono mai i messaggi degli altri.* ### Gestione degli Errori -Gli strumenti possono fallire — le API scadono, i parametri potrebbero essere invalidi, i servizi esterni si interrompono. Gli agenti in produzione necessitano della gestione degli errori così il modello può spiegare i problemi o tentare alternative anziché far crashare l’intera applicazione. Quando uno strumento lancia un’eccezione, LangChain4j la cattura e restituisce il messaggio di errore al modello, che può quindi spiegare il problema in linguaggio naturale. +Gli strumenti possono fallire — le API scadono, i parametri possono essere invalidi, i servizi esterni possono non rispondere. Gli agenti di produzione necessitano di gestione errori affinché il modello possa spiegare i problemi o provare alternative anziché far crashare l'intera applicazione. Quando uno strumento lancia un'eccezione, LangChain4j la cattura e passa il messaggio d'errore al modello, che può quindi spiegare il problema in linguaggio naturale. ## Strumenti Disponibili -Il diagramma sottostante mostra il vasto ecosistema di strumenti che puoi costruire. Questo modulo dimostra strumenti per il meteo e la temperatura, ma lo stesso pattern `@Tool` funziona per qualsiasi metodo Java — dalle query al database all’elaborazione dei pagamenti. +Il diagramma sotto mostra l'ecosistema ampio degli strumenti che puoi costruire. Questo modulo dimostra strumenti meteo e di temperatura, ma lo stesso pattern `@Tool` funziona per qualsiasi metodo Java — dalle query al database alle elaborazioni di pagamento. -Tool Ecosystem +Ecosistema Strumenti -*Qualsiasi metodo Java annotato con @Tool diventa disponibile per l’AI — il pattern si estende a database, API, email, operazioni su file e altro.* +*Qualsiasi metodo Java annotato con @Tool diventa disponibile all'AI — il pattern si estende a database, API, email, operazioni su file e altro.* ## Quando Usare Agenti Basati su Strumenti -Non ogni richiesta necessita di strumenti. La decisione dipende dal fatto che l’AI debba interagire con sistemi esterni o possa rispondere dalla propria conoscenza. La guida seguente riassume quando gli strumenti aggiungono valore e quando non sono necessari: +Non tutte le richieste necessitano strumenti. La decisione dipende dal fatto che l'AI debba interagire con sistemi esterni o possa rispondere dal proprio sapere. La guida seguente riepiloga quando gli strumenti aggiungono valore e quando sono superflui: -When to Use Tools +Quando Usare Strumenti -*Una guida veloce per decidere — gli strumenti servono per dati in tempo reale, calcoli e azioni; conoscenza generale e compiti creativi non ne hanno bisogno.* +*Una guida rapida — gli strumenti servono per dati in tempo reale, calcoli e azioni; conoscenza generale e compiti creativi non ne hanno bisogno.* ## Strumenti vs RAG -I moduli 03 e 04 estendono entrambi le capacità dell’AI, ma in modi fondamentalmente diversi. RAG dà al modello accesso alla **conoscenza** recuperando documenti. Gli strumenti danno al modello la capacità di compiere **azioni** chiamando funzioni. Il diagramma sottostante confronta questi due approcci fianco a fianco — da come funziona ciascun flusso di lavoro ai compromessi tra di essi: +I moduli 03 e 04 estendono entrambi le capacità dell'AI, ma in modi fondamentalmente diversi. RAG dà al modello accesso alla **conoscenza** recuperando documenti. Gli strumenti danno al modello la capacità di compiere **azioni** chiamando funzioni. Il diagramma sotto confronta queste due strategie fianco a fianco — dal modo in cui opera ciascun workflow fino ai compromessi tra loro: -Tools vs RAG Comparison +Confronto Strumenti vs RAG -*RAG recupera informazioni da documenti statici — gli strumenti eseguono azioni e recuperano dati dinamici e in tempo reale. Molti sistemi di produzione combinano entrambi.* +*RAG recupera informazioni da documenti statici — Strumenti eseguono azioni e ottengono dati dinamici e in tempo reale. Molti sistemi di produzione combinano entrambi.* -In pratica, molti sistemi di produzione combinano entrambi gli approcci: RAG per ancorare le risposte nella documentazione, e Strumenti per recuperare dati live o eseguire operazioni. +In pratica, molti sistemi di produzione combinano entrambi gli approcci: RAG per basare le risposte sulla documentazione, e Strumenti per recuperare dati vivi o eseguire operazioni. ## Passi Successivi -**Prossimo Modulo:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Modulo Successivo:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- @@ -382,6 +382,6 @@ In pratica, molti sistemi di produzione combinano entrambi gli approcci: RAG per --- -**Disclaimer**: -Questo documento è stato tradotto utilizzando il servizio di traduzione automatica AI [Co-op Translator](https://github.com/Azure/co-op-translator). Pur impegnandoci per garantire accuratezza, si prega di considerare che le traduzioni automatiche possono contenere errori o inesattezze. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si consiglia una traduzione professionale effettuata da un esperto umano. Non siamo responsabili per eventuali incomprensioni o interpretazioni errate derivanti dall’uso di questa traduzione. +**Disclaimer**: +Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire la precisione, si prega di notare che le traduzioni automatizzate possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un essere umano. Non siamo responsabili per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. \ No newline at end of file diff --git a/translations/it/README.md b/translations/it/README.md index 13c55ba14..ccdecfd97 100644 --- a/translations/it/README.md +++ b/translations/it/README.md @@ -6,14 +6,14 @@ Un corso per costruire applicazioni AI con LangChain4j e Azure OpenAI GPT-5.2, d ### 🌐 Supporto Multilingue -#### Supportato tramite GitHub Action (Automatico & Sempre Aggiornato) +#### Supportato tramite GitHub Action (Automatizzato & Sempre Aggiornato) -[Arabo](../ar/README.md) | [Bengalese](../bn/README.md) | [Bulgaro](../bg/README.md) | [Birmano (Myanmar)](../my/README.md) | [Cinese (Semplificato)](../zh-CN/README.md) | [Cinese (Tradizionale, Hong Kong)](../zh-HK/README.md) | [Cinese (Tradizionale, Macao)](../zh-MO/README.md) | [Cinese (Tradizionale, Taiwan)](../zh-TW/README.md) | [Croato](../hr/README.md) | [Ceco](../cs/README.md) | [Danese](../da/README.md) | [Olandese](../nl/README.md) | [Estone](../et/README.md) | [Finlandese](../fi/README.md) | [Francese](../fr/README.md) | [Tedesco](../de/README.md) | [Greco](../el/README.md) | [Ebraico](../he/README.md) | [Hindi](../hi/README.md) | [Ungherese](../hu/README.md) | [Indonesiano](../id/README.md) | [Italiano](./README.md) | [Giapponese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Coreano](../ko/README.md) | [Lituano](../lt/README.md) | [Malese](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalese](../ne/README.md) | [Pidgin Nigeriano](../pcm/README.md) | [Norvegese](../no/README.md) | [Persiano (Farsi)](../fa/README.md) | [Polacco](../pl/README.md) | [Portoghese (Brasile)](../pt-BR/README.md) | [Portoghese (Portogallo)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Rumeno](../ro/README.md) | [Russo](../ru/README.md) | [Serbo (Cirillico)](../sr/README.md) | [Slovacco](../sk/README.md) | [Sloveno](../sl/README.md) | [Spagnolo](../es/README.md) | [Swahili](../sw/README.md) | [Svedese](../sv/README.md) | [Tagalog (Filippino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Tailandese](../th/README.md) | [Turco](../tr/README.md) | [Ucraino](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamita](../vi/README.md) +[Arabo](../ar/README.md) | [Bengalese](../bn/README.md) | [Bulgaro](../bg/README.md) | [Birmano (Myanmar)](../my/README.md) | [Cinese (Semplificato)](../zh-CN/README.md) | [Cinese (Tradizionale, Hong Kong)](../zh-HK/README.md) | [Cinese (Tradizionale, Macao)](../zh-MO/README.md) | [Cinese (Tradizionale, Taiwan)](../zh-TW/README.md) | [Croato](../hr/README.md) | [Ceco](../cs/README.md) | [Danese](../da/README.md) | [Olandese](../nl/README.md) | [Estone](../et/README.md) | [Finlandese](../fi/README.md) | [Francese](../fr/README.md) | [Tedesco](../de/README.md) | [Greco](../el/README.md) | [Ebraico](../he/README.md) | [Hindi](../hi/README.md) | [Ungherese](../hu/README.md) | [Indonesiano](../id/README.md) | [Italiano](./README.md) | [Giapponese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Coreano](../ko/README.md) | [Lituano](../lt/README.md) | [Malese](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalese](../ne/README.md) | [Pidgin Nigeriano](../pcm/README.md) | [Norvegese](../no/README.md) | [Persiano (Farsi)](../fa/README.md) | [Polacco](../pl/README.md) | [Portoghese (Brasile)](../pt-BR/README.md) | [Portoghese (Portogallo)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Rumeno](../ro/README.md) | [Russo](../ru/README.md) | [Serbo (Cirillico)](../sr/README.md) | [Slovacco](../sk/README.md) | [Sloveno](../sl/README.md) | [Spagnolo](../es/README.md) | [Swahili](../sw/README.md) | [Svedese](../sv/README.md) | [Tagalog (Filippino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thailandese](../th/README.md) | [Turco](../tr/README.md) | [Ucraino](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamita](../vi/README.md) -> **Preferisci Clonare Localmente?** +> **Preferisci clonare localmente?** > -> Questo repository include più di 50 traduzioni in lingue diverse che aumentano significativamente la dimensione del download. Per clonare senza le traduzioni, usa sparse checkout: +> Questo repository include traduzioni in più di 50 lingue, il che aumenta significativamente la dimensione del download. Per clonare senza traduzioni, usa il sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,26 +29,25 @@ Un corso per costruire applicazioni AI con LangChain4j e Azure OpenAI GPT-5.2, d > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Questo ti fornisce tutto il necessario per completare il corso con un download molto più veloce. +> Questo ti dà tutto il necessario per completare il corso con un download molto più veloce. ## Indice -1. [Avvio Rapido](00-quick-start/README.md) - Inizia con LangChain4j -2. [Introduzione](01-introduction/README.md) - Impara le basi di LangChain4j -3. [Ingegneria del Prompt](02-prompt-engineering/README.md) - Padroneggia la progettazione efficace dei prompt -4. [RAG (Generazione con Recupero)](03-rag/README.md) - Costruisci sistemi intelligenti basati sulla conoscenza -5. [Strumenti](04-tools/README.md) - Integra strumenti esterni e assistenti semplici -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Lavora con il Model Context Protocol (MCP) e moduli agentici +1. [Introduzione](01-introduction/README.md) - Impara le basi di LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Diventa esperto nel design efficace dei prompt +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Costruisci sistemi intelligenti basati sulla conoscenza +4. [Strumenti](04-tools/README.md) - Integra strumenti esterni e assistenti semplici +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Lavora con il Model Context Protocol (MCP) e i moduli Agentici -### Tutorial Video +### Video Tutorial -Ogni modulo ha una sessione live di accompagnamento dove spieghiamo i concetti e il codice passo dopo passo. +Ogni modulo ha una sessione live associata in cui esaminiamo i concetti e il codice passo dopo passo. | Modulo | Video | |--------|-------| | 01 - Introduzione | [Iniziare con LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Ingegneria del Prompt | [Ingegneria del Prompt con LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 02 - Prompt Engineering | [Prompt Engineering con LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG con LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Strumenti & 05 - MCP | [Agenti AI con Strumenti e MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | @@ -56,34 +55,34 @@ Ogni modulo ha una sessione live di accompagnamento dove spieghiamo i concetti e ## Percorso di Apprendimento -**Nuovo a LangChain4j?** Dai un’occhiata al [Glossario](docs/GLOSSARY.md) per le definizioni dei termini e concetti chiave. +**Sei nuovo in LangChain4j?** Dai un’occhiata al [Glossario](docs/GLOSSARY.md) per definizioni di termini chiave e concetti. > **Avvio Rapido** -1. Effettua il fork di questo repository nel tuo account GitHub -2. Clicca **Code** → scheda **Codespaces** → **...** → **Nuovo con opzioni…** -3. Usa le impostazioni predefinite – questo selezionerà il contenitore di sviluppo creato per questo corso +1. Fai il fork di questo repository sul tuo account GitHub +2. Clicca **Code** → scheda **Codespaces** → **...** → **Nuovo con opzioni...** +3. Usa i valori predefiniti – questo selezionerà il contenitore di sviluppo creato per questo corso 4. Clicca **Crea codespace** -5. Attendi 5-10 minuti che l’ambiente sia pronto -6. Vai direttamente a [Avvio Rapido](./00-quick-start/README.md) per iniziare! +5. Attendi 5-10 minuti per l’ambiente pronto +6. Vai direttamente a [Introduzione](./01-introduction/README.md) per iniziare! -Dopo aver completato i moduli, esplora la [Guida al Testing](docs/TESTING.md) per vedere in azione i concetti di testing di LangChain4j. +Dopo aver completato i moduli, esplora la [Guida ai Test](docs/TESTING.md) per vedere in azione i concetti di testing di LangChain4j. -> **Nota:** Questa formazione utilizza sia GitHub Models che Azure OpenAI. Il modulo [Avvio Rapido](00-quick-start/README.md) usa GitHub Models (non è necessaria un’abbonamento Azure), mentre i moduli da 1 a 5 utilizzano Azure OpenAI. Inizia con un [account Azure GRATUITO](https://aka.ms/azure-free-account) se non ne possiedi uno. +> **Nota:** Questa formazione usa Azure OpenAI. Inizia con un [account Azure GRATUITO](https://aka.ms/azure-free-account) se non ne hai uno. -## Imparare con GitHub Copilot +## Apprendimento con GitHub Copilot -Per iniziare rapidamente a programmare, apri questo progetto in un GitHub Codespace o nel tuo IDE locale con il devcontainer fornito. Il devcontainer usato in questo corso è preconfigurato con GitHub Copilot per la programmazione AI in coppia. +Per iniziare rapidamente a programmare, apri questo progetto in un GitHub Codespace o nel tuo IDE locale con il devcontainer fornito. Il devcontainer usato in questo corso viene preconfigurato con GitHub Copilot per la programmazione in coppia AI. -Ogni esempio di codice include domande suggerite che puoi fare a GitHub Copilot per approfondire la comprensione. Cerca i prompt 💡/🤖 in: +Ogni esempio di codice include domande suggerite che puoi porre a GitHub Copilot per approfondire la tua comprensione. Cerca i prompt 💡/🤖 in: -- **Intestazioni dei file Java** - Domande specifiche per ogni esempio +- **Intestazioni di file Java** - Domande specifiche per ogni esempio - **README dei moduli** - Prompt di esplorazione dopo gli esempi di codice -**Come usarlo:** Apri qualsiasi file di codice e poni a Copilot le domande suggerite. Ha il contesto completo del codice e può spiegare, estendere e suggerire alternative. +**Come usare:** Apri qualsiasi file di codice e poni a Copilot le domande suggerite. Ha il contesto completo del codice e può spiegare, estendere e suggerire alternative. -Vuoi saperne di più? Guarda [Copilot per la Programmazione AI in Coppia](https://aka.ms/GitHubCopilotAI). +Vuoi saperne di più? Dai un’occhiata a [Copilot per programmazione in coppia AI](https://aka.ms/GitHubCopilotAI). ## Risorse Aggiuntive @@ -113,9 +112,9 @@ Vuoi saperne di più? Guarda [Copilot per la Programmazione AI in Coppia](https: ### Apprendimento Base [![ML per Principianti](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Scienza dei Dati per Principianti](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science per Principianti](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI per Principianti](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Cybersecurity per Principianti](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -145,6 +144,6 @@ Licenza MIT - Vedi il file [LICENSE](../../LICENSE) per i dettagli. --- -**Disclaimer**: -Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Pur facendo del nostro meglio per garantire l’accuratezza, si prega di notare che le traduzioni automatiche possono contenere errori o imprecisioni. Il documento originale nella sua lingua natìa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale umana. Non siamo responsabili per eventuali fraintendimenti o interpretazioni errate derivanti dall’uso di questa traduzione. +**Disclaimer**: +Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire la precisione, si prega di notare che le traduzioni automatizzate possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un essere umano. Non siamo responsabili per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. \ No newline at end of file diff --git a/translations/it/docs/GLOSSARY.md b/translations/it/docs/GLOSSARY.md index b67470264..b4e1683a0 100644 --- a/translations/it/docs/GLOSSARY.md +++ b/translations/it/docs/GLOSSARY.md @@ -2,29 +2,29 @@ ## Indice -- [Concetti Fondamentali](../../../docs) -- [Componenti LangChain4j](../../../docs) -- [Concetti AI/ML](../../../docs) -- [Guardrails](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Generazione Arricchita da Recupero)](../../../docs) -- [Agenti e Strumenti](../../../docs) -- [Modulo Agentico](../../../docs) -- [Protocollo di Contesto Modello (MCP)](../../../docs) -- [Servizi Azure](../../../docs) -- [Testing e Sviluppo](../../../docs) +- [Concetti Principali](#concetti-principali) +- [Componenti LangChain4j](#componenti-langchain4j) +- [Concetti AI/ML](#concetti-aiml) +- [Guardrails](#guardrails) +- [Prompt Engineering](#prompt-engineering---modulo-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---modulo-03) +- [Agenti e Strumenti](#agenti-e-strumenti---modulo-04) +- [Modulo Agentic](#modulo-agentic---modulo-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---modulo-05) +- [Servizi Azure](#servizi-azure---modulo-01) +- [Testing e Sviluppo](#testing-e-sviluppo---guida-al-testing) -Riferimento rapido per termini e concetti usati durante il corso. +Riferimento rapido per termini e concetti utilizzati durante il corso. -## Concetti Fondamentali +## Concetti Principali -**Agente AI** - Sistema che utilizza AI per ragionare e agire autonomamente. [Modulo 04](../04-tools/README.md) +**Agente AI** - Sistema che utilizza AI per ragionare e agire in autonomia. [Modulo 04](../04-tools/README.md) **Catena** - Sequenza di operazioni in cui l'output alimenta il passo successivo. -**Suddivisione (Chunking)** - Suddividere documenti in pezzi più piccoli. Tipico: 300-500 token con sovrapposizione. [Modulo 03](../03-rag/README.md) +**Chunking** - Suddivisione di documenti in pezzi più piccoli. Tipico: 300-500 token con sovrapposizione. [Modulo 03](../03-rag/README.md) -**Finestra di Contesto** - Massimo numero di token che un modello può processare. GPT-5.2: 400K token (fino a 272K input, 128K output). +**Finestra di Contesto** - Numero massimo di token che un modello può processare. GPT-5.2: 400K token (fino a 272K input, 128K output). **Embedding** - Vettori numerici che rappresentano il significato del testo. [Modulo 03](../03-rag/README.md) @@ -32,155 +32,155 @@ Riferimento rapido per termini e concetti usati durante il corso. **Allucinazione** - Quando i modelli generano informazioni errate ma plausibili. -**Prompt** - Testo di input per un modello di linguaggio. [Modulo 02](../02-prompt-engineering/README.md) +**Prompt** - Input testuale per un modello di linguaggio. [Modulo 02](../02-prompt-engineering/README.md) **Ricerca Semantica** - Ricerca basata sul significato usando embedding, non parole chiave. [Modulo 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: nessuna memoria. Stateful: mantiene la cronologia della conversazione. [Modulo 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: senza memoria. Stateful: mantiene la cronologia della conversazione. [Modulo 01](../01-introduction/README.md) -**Token** - Unità base di testo che i modelli processano. Influisce su costi e limiti. [Modulo 01](../01-introduction/README.md) +**Token** - Unità base di testo processata dai modelli. Incide su costi e limiti. [Modulo 01](../01-introduction/README.md) -**Catena di Strumenti** - Esecuzione sequenziale di strumenti dove l'output informa la chiamata successiva. [Modulo 04](../04-tools/README.md) +**Catena di Strumenti** - Esecuzione sequenziale di strumenti in cui l'output informa la chiamata successiva. [Modulo 04](../04-tools/README.md) ## Componenti LangChain4j -**AiServices** - Crea interfacce di servizi AI type-safe. +**AiServices** - Crea interfacce di servizio AI type-safe. **OpenAiOfficialChatModel** - Client unificato per modelli OpenAI e Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Crea embedding usando il client ufficiale OpenAI (supporta sia OpenAI che Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Crea embedding usando il client OpenAI Official (supporta sia OpenAI che Azure OpenAI). **ChatModel** - Interfaccia core per modelli di linguaggio. **ChatMemory** - Mantiene la cronologia della conversazione. -**ContentRetriever** - Trova i chunk di documento rilevanti per RAG. +**ContentRetriever** - Trova chunk di documenti rilevanti per RAG. **DocumentSplitter** - Suddivide documenti in chunk. **EmbeddingModel** - Converte testo in vettori numerici. -**EmbeddingStore** - Memorizza e recupera embedding. +**EmbeddingStore** - Salva e recupera embedding. **MessageWindowChatMemory** - Mantiene una finestra mobile dei messaggi recenti. -**PromptTemplate** - Crea prompt riutilizzabili con segnaposti `{{variable}}`. +**PromptTemplate** - Crea prompt riutilizzabili con segnaposto `{{variable}}`. -**TextSegment** - Chunk di testo con metadati. Usato in RAG. +**TextSegment** - Chunk di testo con metadata. Usato in RAG. -**ToolExecutionRequest** - Rappresenta una richiesta di esecuzione di uno strumento. +**ToolExecutionRequest** - Rappresenta la richiesta di esecuzione di uno strumento. **UserMessage / AiMessage / SystemMessage** - Tipi di messaggi di conversazione. ## Concetti AI/ML -**Few-Shot Learning** - Fornire esempi all'interno dei prompt. [Modulo 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Fornire esempi nei prompt. [Modulo 02](../02-prompt-engineering/README.md) **Large Language Model (LLM)** - Modelli AI addestrati su grandi quantità di testo. -**Sforzo di Ragionamento** - Parametro GPT-5.2 che controlla la profondità del pensiero. [Modulo 02](../02-prompt-engineering/README.md) +**Sforzo di Ragionamento** - Parametro GPT-5.2 che controlla la profondità del ragionamento. [Modulo 02](../02-prompt-engineering/README.md) -**Temperatura** - Controlla la casualità in output. Basso=deterministico, alto=creativo. +**Temperatura** - Controlla la casualità dell'output. Bassa=deterministico, alta=creativo. **Database Vettoriale** - Database specializzato per embedding. [Modulo 03](../03-rag/README.md) **Zero-Shot Learning** - Eseguire compiti senza esempi. [Modulo 02](../02-prompt-engineering/README.md) -## Guardrails - [Modulo 00](../00-quick-start/README.md) +## Guardrails -**Difesa in Profondità** - Approccio di sicurezza a più livelli che combina guardrails a livello applicativo con filtri di sicurezza del provider. +**Difesa in Profondità** - Approccio di sicurezza multilivello che combina guardrails a livello applicativo con filtri di sicurezza del provider. -**Blocco Rigido** - Il provider lancia un errore HTTP 400 per gravi violazioni di contenuto. +**Blocco Duro** - Il provider restituisce errore HTTP 400 per violazioni gravi dei contenuti. -**InputGuardrail** - Interfaccia LangChain4j per validare l'input dell'utente prima che raggiunga l'LLM. Risparmia costi e latenza bloccando prompt dannosi in anticipo. +**InputGuardrail** - Interfaccia LangChain4j per convalidare l'input utente prima che raggiunga l'LLM. Riduce costi e latenza bloccando prompt dannosi in anticipo. **InputGuardrailResult** - Tipo di ritorno per la validazione guardrail: `success()` o `fatal("reason")`. -**OutputGuardrail** - Interfaccia per validare le risposte AI prima di restituirle agli utenti. +**OutputGuardrail** - Interfaccia per convalidare le risposte AI prima di restituirle agli utenti. -**Filtri di Sicurezza del Provider** - Filtri di contenuto integrati dai provider AI (es. GitHub Models) che intercettano violazioni a livello API. +**Filtri di Sicurezza del Provider** - Filtri di contenuto integrati dai provider AI (es. Azure OpenAI) che intercettano violazioni a livello API. -**Rifiuto Soft** - Il modello declina educatamente di rispondere senza generare errore. +**Rifiuto Morbido** - Il modello declina educatamente di rispondere senza generare errore. ## Prompt Engineering - [Modulo 02](../02-prompt-engineering/README.md) -**Catena di Pensiero (Chain-of-Thought)** - Ragionamento passo-passo per maggiore accuratezza. +**Chain-of-Thought** - Ragionamento passo dopo passo per maggiore accuratezza. -**Output Vincolato (Constrained Output)** - Applicare formato o struttura specifici. +**Output Vincolato** - Forzare un formato o struttura specifica. -**Alta Prontezza (High Eagerness)** - Pattern GPT-5.2 per ragionamento approfondito. +**Alta Voglia** - Pattern GPT-5.2 per ragionamento approfondito. -**Bassa Prontezza (Low Eagerness)** - Pattern GPT-5.2 per risposte rapide. +**Bassa Voglia** - Pattern GPT-5.2 per risposte rapide. -**Conversazione Multi-Turno** - Mantenere il contesto attraverso gli scambi. +**Conversazione Multi-Turno** - Mantenere il contesto tra scambi. -**Prompting Basato sul Ruolo** - Definire la persona del modello tramite messaggi di sistema. +**Prompting Basato su Ruolo** - Impostare la persona del modello tramite messaggi di sistema. **Auto-Riflessione** - Il modello valuta e migliora il proprio output. -**Analisi Strutturata** - Quadro di valutazione fisso. +**Analisi Strutturata** - Framework di valutazione fisso. -**Pattern di Esecuzione del Compito** - Pianifica → Esegui → Riassumi. +**Pattern di Esecuzione compiti** - Pianifica → Esegui → Riepiloga. -## RAG (Generazione Arricchita da Recupero) - [Modulo 03](../03-rag/README.md) +## RAG (Retrieval-Augmented Generation) - [Modulo 03](../03-rag/README.md) -**Pipeline di Elaborazione Documento** - Carica → suddividi → incorpora → archivia. +**Pipeline di Elaborazione Documenti** - Carica → spezza → embedd → archivia. -**Archiviazione Embedding In-Memory** - Memorizzazione non persistente per test. +**Embedding Store in Memoria** - Storage non persistente per test. -**RAG** - Combina recupero con generazione per ancorare le risposte. +**RAG** - Combina retrieval con generazione per ancorare le risposte. -**Punteggio di Similarità** - Misura (0-1) di somiglianza semantica. +**Punteggio di Similarità** - Misura (0-1) di similarità semantica. -**Riferimento alla Fonte** - Metadati sul contenuto recuperato. +**Riferimento alla Fonte** - Metadata sul contenuto recuperato. ## Agenti e Strumenti - [Modulo 04](../04-tools/README.md) -**Annotazione @Tool** - Marca metodi Java come strumenti richiamabili dall'AI. +**Annotazione @Tool** - Marca metodi Java come strumenti richiamabili dall’AI. **Pattern ReAct** - Ragiona → Agisci → Osserva → Ripeti. -**Gestione Sessione** - Contesti separati per utenti differenti. +**Gestione Sessione** - Contesti separati per utenti diversi. -**Strumento (Tool)** - Funzione che un agente AI può chiamare. +**Strumento** - Funzione che un agente AI può chiamare. -**Descrizione Strumento** - Documentazione dello scopo e dei parametri dello strumento. +**Descrizione Strumento** - Documentazione dello scopo e parametri dello strumento. -## Modulo Agentico - [Modulo 05](../05-mcp/README.md) +## Modulo Agentic - [Modulo 05](../05-mcp/README.md) **Annotazione @Agent** - Marca interfacce come agenti AI con definizione comportamentale dichiarativa. -**Agent Listener** - Hook per monitorare l’esecuzione agente tramite `beforeAgentInvocation()` e `afterAgentInvocation()`. +**Agent Listener** - Hook per monitorare esecuzione agente via `beforeAgentInvocation()` e `afterAgentInvocation()`. -**Ambito Agentico (Agentic Scope)** - Memoria condivisa dove gli agenti memorizzano output utilizzando `outputKey` per agenti a valle. +**Ambito Agentic** - Memoria condivisa dove agenti salvano output usando `outputKey` per agenti a valle. **AgenticServices** - Factory per creare agenti usando `agentBuilder()` e `supervisorBuilder()`. -**Workflow Condizionale** - Routing basato su condizioni verso agenti specialisti diversi. +**Flusso Condizionale** - Routing basato su condizioni verso agenti specialisti differenti. -**Human-in-the-Loop** - Pattern di workflow che aggiunge checkpoint umani per approvazione o revisione contenuti. +**Human-in-the-Loop** - Pattern di flusso che aggiunge checkpoint umani per approvazione o revisione contenuti. -**langchain4j-agentic** - Dipendenza Maven per costruzione agenti dichiarativa (sperimentale). +**langchain4j-agentic** - Dipendenza Maven per costruzione dichiarativa agenti (sperimentale). -**Workflow a Ciclo (Loop Workflow)** - Iterare l’esecuzione agente finché una condizione è soddisfatta (es. punteggio qualità ≥ 0.8). +**Flusso a Ciclo** - Itera esecuzione agente fino a soddisfare una condizione (es. punteggio qualità ≥ 0.8). -**outputKey** - Parametro annotazione agente che specifica dove vengono archiviati i risultati nell’Ambito Agentico. +**outputKey** - Parametro annotazione agente che specifica dove salvare i risultati in Ambito Agentic. -**Workflow Parallelo** - Esegue più agenti simultaneamente per compiti indipendenti. +**Flusso Parallelo** - Esegue più agenti simultaneamente per compiti indipendenti. **Strategia di Risposta** - Come il supervisore formula la risposta finale: LAST, SUMMARY, o SCORED. -**Workflow Sequenziale** - Esegue agenti in ordine dove l’output fluisce al passo successivo. +**Flusso Sequenziale** - Esecuzione agente in ordine in cui l'output fluisce al passo successivo. -**Pattern Agent Supervisore** - Pattern avanzato agentico dove un LLM supervisore decide dinamicamente quali sub-agenti invocare. +**Pattern Agente Supervisore** - Pattern agentic avanzato in cui un supervisore LLM decide dinamicamente quali sotto-agenti invocare. -## Protocollo di Contesto Modello (MCP) - [Modulo 05](../05-mcp/README.md) +## Model Context Protocol (MCP) - [Modulo 05](../05-mcp/README.md) -**langchain4j-mcp** - Dipendenza Maven per l’integrazione MCP in LangChain4j. +**langchain4j-mcp** - Dipendenza Maven per integrazione MCP in LangChain4j. -**MCP** - Model Context Protocol: standard per collegare app AI a strumenti esterni. Scrivi una volta, usa ovunque. +**MCP** - Model Context Protocol: standard per connettere app AI a strumenti esterni. Costruisci una volta, usa ovunque. -**Client MCP** - Applicazione che si connette a server MCP per scoprire e usare strumenti. +**Client MCP** - Applicazione che si connette a server MCP per scoprire e utilizzare strumenti. **Server MCP** - Servizio che espone strumenti via MCP con descrizioni chiare e schemi parametri. @@ -188,45 +188,43 @@ Riferimento rapido per termini e concetti usati durante il corso. **McpTransport** - Interfaccia per comunicazione MCP. Implementazioni includono Stdio e HTTP. -**Trasporto Stdio** - Trasporto processo locale tramite stdin/stdout. Utile per accesso filesystem o strumenti da riga di comando. +**Trasporto Stdio** - Trasporto processo locale via stdin/stdout. Utile per accesso filesystem o strumenti CLI. -**StdioMcpTransport** - Implementazione LangChain4j che avvia server MCP come processo secondario. +**StdioMcpTransport** - Implementazione LangChain4j che avvia server MCP come subprocesso. -**Scoperta Strumenti** - Client interroga server per strumenti disponibili con descrizioni e schemi. +**Scoperta Strumenti** - Il client interroga il server per strumenti disponibili con descrizioni e schemi. ## Servizi Azure - [Modulo 01](../01-introduction/README.md) -**Azure AI Search** - Ricerca cloud con funzionalità vettoriali. [Modulo 03](../03-rag/README.md) +**Azure AI Search** - Ricerca cloud con capacità vettoriali. [Modulo 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Deploy di risorse Azure. +**Azure Developer CLI (azd)** - Distribuisce risorse Azure. **Azure OpenAI** - Servizio AI enterprise di Microsoft. **Bicep** - Linguaggio infrastructure-as-code per Azure. [Guida Infrastructure](../01-introduction/infra/README.md) -**Nome di Deploy** - Nome per il deployment del modello in Azure. +**Nome Distribuzione** - Nome per il deployment del modello in Azure. **GPT-5.2** - Ultimo modello OpenAI con controllo del ragionamento. [Modulo 02](../02-prompt-engineering/README.md) -## Testing e Sviluppo - [Guida Testing](TESTING.md) +## Testing e Sviluppo - [Guida al Testing](TESTING.md) **Dev Container** - Ambiente di sviluppo containerizzato. [Configurazione](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Playground AI gratuito. [Modulo 00](../00-quick-start/README.md) +**Testing in Memoria** - Test con storage in memoria. -**Testing In-Memory** - Testing con archiviazione in memoria. +**Testing di Integrazione** - Test con infrastruttura reale. -**Testing di Integrazione** - Testing con infrastruttura reale. +**Maven** - Strumento di automazione build Java. -**Maven** - Strumento Java per automazione build. +**Mockito** - Framework mocking Java. -**Mockito** - Framework Java per mocking. - -**Spring Boot** - Framework applicativo Java. [Modulo 01](../01-introduction/README.md) +**Spring Boot** - Framework applicazioni Java. [Modulo 01](../01-introduction/README.md) --- -**Avvertenza**: -Questo documento è stato tradotto utilizzando il servizio di traduzione automatica [Co-op Translator](https://github.com/Azure/co-op-translator). Pur impegnandoci per garantire accuratezza, si prega di notare che le traduzioni automatiche possono contenere errori o inesattezze. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un umano. Non ci assumiamo alcuna responsabilità per malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. +**Disclaimer**: +Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire la precisione, si prega di notare che le traduzioni automatizzate possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un essere umano. Non siamo responsabili per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. \ No newline at end of file diff --git a/translations/it/docs/TESTING.md b/translations/it/docs/TESTING.md index 65dcef413..96c080b6c 100644 --- a/translations/it/docs/TESTING.md +++ b/translations/it/docs/TESTING.md @@ -1,20 +1,20 @@ -# Testing LangChain4j Applications +# Testare le applicazioni LangChain4j -## Table of Contents +## Sommario -- [Quick Start](../../../docs) -- [What the Tests Cover](../../../docs) -- [Running the Tests](../../../docs) -- [Running Tests in VS Code](../../../docs) -- [Testing Patterns](../../../docs) -- [Testing Philosophy](../../../docs) -- [Next Steps](../../../docs) +- [Avvio rapido](#avvio-rapido) +- [Cosa coprono i test](#cosa-coprono-i-test) +- [Esecuzione dei test](#esecuzione-dei-test) +- [Esecuzione dei test in VS Code](#esecuzione-dei-test-in-vs-code) +- [Modelli di test](#modelli-di-test) +- [Filosofia dei test](#filosofia-dei-test) +- [Passi successivi](#passi-successivi) -Questa guida ti accompagna attraverso i test che dimostrano come testare applicazioni AI senza richiedere chiavi API o servizi esterni. +Questa guida ti guida attraverso i test che mostrano come testare applicazioni AI senza richiedere chiavi API o servizi esterni. -## Quick Start +## Avvio rapido -Esegui tutti i test con un unico comando: +Esegui tutti i test con un solo comando: **Bash:** ```bash @@ -26,30 +26,29 @@ mvn test mvn --% test ``` -Quando tutti i test passano, dovresti vedere un output simile allo screenshot qui sotto — i test vengono eseguiti con zero errori. +Quando tutti i test passano, dovresti vedere un output simile allo screenshot qui sotto — test eseguiti con zero fallimenti. -Risultati Test Riusciti +Successful Test Results -*Esecuzione di test riuscita che mostra tutti i test superati senza errori* +*Esecuzione riuscita dei test che mostra tutti i test superati con zero fallimenti* -## What the Tests Cover +## Cosa coprono i test -Questo corso si concentra su **test unitari** che vengono eseguiti localmente. Ogni test dimostra un concetto specifico di LangChain4j in isolamento. La piramide dei test mostrata sotto indica dove si collocano i test unitari — formano la base veloce e affidabile su cui si costruisce il resto della strategia di testing. +Questo corso si concentra sui **test unitari** che vengono eseguiti localmente. Ogni test dimostra un concetto specifico di LangChain4j in isolamento. La piramide dei test qui sotto mostra dove si collocano i test unitari — essi formano la base rapida e affidabile su cui costruisce il resto della tua strategia di test. -Piramide dei Test +Testing Pyramid *Piramide dei test che mostra l’equilibrio tra test unitari (veloci, isolati), test di integrazione (componenti reali) e test end-to-end. Questa formazione copre il testing unitario.* -| Modulo | Test | Focus | File Chiave | -|--------|-------|-------|-------------| -| **00 - Quick Start** | 6 | Template prompt e sostituzione variabili | `SimpleQuickStartTest.java` | -| **01 - Introduction** | 8 | Memoria conversazionale e chat con stato | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | Pattern GPT-5.2, livelli di eagerness, output strutturato | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Ingestione documenti, embeddings, ricerca per similarità | `DocumentServiceTest.java` | -| **04 - Tools** | 12 | Chiamata funzioni e concatenamento strumenti | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol con trasporto Stdio | `SimpleMcpTest.java` | +| Modulo | Test | Focus | File chiave | +|--------|-------|-------|-----------| +| **01 - Introduzione** | 8 | Memoria della conversazione e chat con stato | `SimpleConversationTest.java` | +| **02 - Prompt Engineering** | 12 | Pattern GPT-5.2, livelli di prontezza, output strutturato | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Ingestione documenti, embeddings, ricerca di similarità | `DocumentServiceTest.java` | +| **04 - Tools** | 12 | Chiamata di funzioni e concatenamento di tool | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol con trasporto stdio | `SimpleMcpTest.java` | -## Running the Tests +## Esecuzione dei test **Esegui tutti i test dalla root:** @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Esegui i test di un modulo specifico:** +**Esegui i test per un modulo specifico:** **Bash:** ```bash @@ -103,9 +102,9 @@ mvn test -Dtest=SimpleConversationTest#dovrebbeMantenereLaCronologiaDellaConvers mvn --% test -Dtest=SimpleConversationTest#dovrebbeMantenereLaCronologiaDellaConversazione ``` -## Running Tests in VS Code +## Esecuzione dei test in VS Code -Se usi Visual Studio Code, il Test Explorer offre un’interfaccia grafica per eseguire e fare il debug dei test. +Se usi Visual Studio Code, il Test Explorer fornisce un’interfaccia grafica per eseguire e fare il debug dei test. VS Code Test Explorer @@ -113,23 +112,23 @@ Se usi Visual Studio Code, il Test Explorer offre un’interfaccia grafica per e **Per eseguire i test in VS Code:** -1. Apri il Test Explorer cliccando sull’icona del becher nella Activity Bar +1. Apri il Test Explorer cliccando l’icona del becher nella barra attività 2. Espandi l’albero dei test per vedere tutti i moduli e le classi di test 3. Clicca il pulsante play accanto a qualsiasi test per eseguirlo singolarmente 4. Clicca su "Run All Tests" per eseguire l’intera suite -5. Clicca col tasto destro su un test e scegli "Debug Test" per impostare breakpoint e fare step attraverso il codice +5. Clicca col tasto destro su un test e seleziona "Debug Test" per impostare breakpoint ed eseguire passo passo -Il Test Explorer mostra spunte verdi per i test superati e fornisce messaggi dettagliati in caso di fallimento. +Il Test Explorer mostra segni di spunta verdi per i test superati e fornisce messaggi dettagliati in caso di fallimento. -## Testing Patterns +## Modelli di test -### Pattern 1: Testing Prompt Templates +### Modello 1: Testare i template dei prompt -Il pattern più semplice testa i template dei prompt senza chiamare alcun modello AI. Verifichi che la sostituzione delle variabili funzioni correttamente e che i prompt siano formattati come previsto. +Il modello più semplice testa i template dei prompt senza chiamare alcun modello AI. Verifichi che la sostituzione delle variabili funzioni correttamente e che i prompt siano formattati come previsto. -Testing Template Prompt +Prompt Template Testing -*Testing dei template di prompt che mostra il flusso di sostituzione variabili: template con segnaposto → applicazione dei valori → output formattato verificato* +*Test dei template di prompt che mostra il flusso di sostituzione delle variabili: template con segnaposto → valori applicati → output formattato verificato* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Questo test si trova in `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Questo modello verifica che la sostituzione delle variabili funzioni correttamente e che i prompt siano formattati come previsto — non è richiesta alcuna chiave API o chiamata al modello. -**Eseguilo:** +### Modello 2: Mocking dei modelli linguistici -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testareLaFormattazioneDelModelloDiPrompt -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatting -``` - -### Pattern 2: Mocking Language Models - -Quando testi la logica di conversazione, usa Mockito per creare modelli finti che restituiscono risposte predeterminate. Questo rende i test veloci, gratuiti e deterministici. +Quando testi la logica della conversazione, usa Mockito per creare modelli falsi che restituiscono risposte predeterminate. Questo rende i test veloci, gratuiti e deterministici. -Confronto Mock vs API reale +Mock vs Real API Comparison -*Confronto che mostra perché si preferiscono i mock per il testing: sono veloci, gratuiti, deterministici e non richiedono chiavi API* +*Confronto che mostra perché i mock sono preferiti per il testing: sono veloci, gratuiti, deterministici e non richiedono chiavi API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Questo pattern appare in `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Il mock garantisce un comportamento consistente così da poter verificare che la gestione della memoria funzioni correttamente. +Questo modello appare in `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Il mock garantisce comportamento consistente così puoi verificare che la gestione della memoria funzioni correttamente. -### Pattern 3: Testing Conversation Isolation +### Modello 3: Testare l’isolamento della conversazione -La memoria della conversazione deve mantenere separati più utenti. Questo test verifica che le conversazioni non mescolino i contesti. +La memoria della conversazione deve mantenere gli utenti separati. Questo test verifica che le conversazioni non mescolino i contesti. -Isolamento della conversazione +Conversation Isolation -*Testing dell’isolamento della conversazione che mostra archivi di memoria separati per utenti diversi per evitare mescolamento dei contesti* +*Test dell’isolamento delle conversazioni che mostra archivi di memoria separati per diversi utenti per evitare mescolanze di contesto* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Ogni conversazione mantiene la propria storia indipendente. Nei sistemi di produzione, questo isolamento è critico per applicazioni multiutente. +Ogni conversazione mantiene la propria storia indipendente. Nei sistemi di produzione, questo isolamento è critico per applicazioni multi-utente. -### Pattern 4: Testing Tools Independently +### Modello 4: Testare i tool indipendentemente -Gli strumenti sono funzioni che l’AI può chiamare. Testali direttamente per assicurarti che funzionino correttamente indipendentemente dalle decisioni dell’AI. +I tool sono funzioni che l’AI può chiamare. Testali direttamente per assicurarti che funzionino correttamente indipendentemente dalle decisioni AI. -Testing Strumenti +Tools Testing -*Testing degli strumenti indipendentemente che mostra esecuzione di tool mock senza chiamate AI per verificare la logica di business* +*Testare i tool in modo indipendente mostrando l’esecuzione di tool mock senza chiamate AI per verificare la logica di business* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Questi test da `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` convalidano la logica degli strumenti senza coinvolgimento AI. L’esempio di concatenamento mostra come l’output di uno strumento alimenti l’input di un altro. +Questi test da `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` convalidano la logica dei tool senza coinvolgimento AI. L’esempio di concatenamento mostra come l’output di un tool alimenta l’input di un altro. -### Pattern 5: In-Memory RAG Testing +### Modello 5: Test RAG in memoria -I sistemi RAG tradizionalmente richiedono database vettoriali e servizi di embedding. Il pattern in-memory ti permette di testare l’intera pipeline senza dipendenze esterne. +I sistemi RAG richiedono tradizionalmente database vettoriali e servizi di embedding. Il modello in memoria ti permette di testare l’intera pipeline senza dipendenze esterne. -Testing RAG In-Memory +In-Memory RAG Testing -*Flusso di lavoro RAG in-memory che mostra parsing documenti, memorizzazione embedding e ricerca per similarità senza richiedere un database* +*Workflow di test RAG in memoria che mostra parsing documenti, memorizzazione embedding e ricerca di similarità senza richiedere un database* ```java @Test @@ -306,9 +293,9 @@ void testProcessTextDocument() { } ``` -Questo test da `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` crea un documento in memoria e verifica chunking e gestione meta-dati. +Questo test da `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` crea un documento in memoria e verifica il chunking e la gestione dei metadata. -### Pattern 6: MCP Integration Testing +### Modello 6: Test d’integrazione MCP Il modulo MCP testa l’integrazione del Model Context Protocol usando il trasporto stdio. Questi test verificano che la tua applicazione possa avviare e comunicare con server MCP come sottoprocessi. @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## Testing Philosophy +## Filosofia dei test -Testa il tuo codice, non l’AI. I tuoi test dovrebbero validare il codice che scrivi controllando come i prompt vengono costruiti, come la memoria viene gestita e come gli strumenti vengono eseguiti. Le risposte AI variano e non dovrebbero far parte delle asserzioni di test. Chiediti se il tuo template di prompt sostituisce correttamente le variabili, non se l’AI dà la risposta giusta. +Testa il tuo codice, non l’AI. I tuoi test dovrebbero convalidare il codice che scrivi controllando come i prompt sono costruiti, come la memoria è gestita e come i tool vengono eseguiti. Le risposte AI variano e non dovrebbero far parte delle asserzioni dei test. Chiediti se il tuo template di prompt sostituisce correttamente le variabili, non se l’AI fornisce la risposta giusta. -Usa i mock per i modelli linguistici. Sono dipendenze esterne che sono lente, costose e non deterministiche. Il mocking rende i test veloci con millisecondi anziché secondi, gratuiti senza costi API, e deterministici con lo stesso risultato ogni volta. +Usa i mock per i modelli linguistici. Sono dipendenze esterne che sono lente, costose e non deterministiche. Il mocking rende i test veloci con millisecondi invece di secondi, gratuiti senza costi API e deterministici con lo stesso risultato ogni volta. -Mantieni i test indipendenti. Ogni test dovrebbe preparare i propri dati, non dipendere da altri test, e pulire dopo sé stesso. I test dovrebbero passare indipendentemente dall’ordine di esecuzione. +Mantieni i test indipendenti. Ogni test dovrebbe preparare i propri dati, non dipendere da altri test e pulire dopo di sé. I test dovrebbero passare indipendentemente dall’ordine di esecuzione. -Testa i casi limite oltre il percorso positivo. Prova input vuoti, input molto grandi, caratteri speciali, parametri non validi e condizioni al limite. Questi spesso fanno emergere bug che l’uso normale non rivela. +Testa casi limite oltre il percorso ottimale. Prova input vuoti, input molto grandi, caratteri speciali, parametri non validi e condizioni di confine. Questi spesso rivelano bug che l’uso normale non espone. -Usa nomi descrittivi. Confronta `shouldMaintainConversationHistoryAcrossMultipleMessages()` con `test1()`. Il primo ti dice esattamente cosa viene testato, rendendo il debug dei fallimenti molto più facile. +Usa nomi descrittivi. Confronta `shouldMaintainConversationHistoryAcrossMultipleMessages()` con `test1()`. Il primo ti dice esattamente cosa viene testato, facilitando molto il debug in caso di fallimenti. -## Next Steps +## Passi successivi -Ora che conosci i pattern di testing, approfondisci ogni modulo: +Ora che conosci i modelli di test, approfondisci ogni modulo: -- **[00 - Quick Start](../00-quick-start/README.md)** - Inizia con le basi dei template prompt -- **[01 - Introduction](../01-introduction/README.md)** - Impara la gestione della memoria conversazionale +- **[01 - Introduzione](../01-introduction/README.md)** - Impara la gestione della memoria della conversazione - **[02 - Prompt Engineering](../02/prompt-engineering/README.md)** - Padroneggia i pattern di prompting GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Costruisci sistemi di retrieval-augmented generation -- **[04 - Tools](../04-tools/README.md)** - Implementa chiamate funzioni e catene di strumenti -- **[05 - MCP](../05-mcp/README.md)** - Integra Model Context Protocol +- **[03 - RAG](../03-rag/README.md)** - Costruisci sistemi di generazione arricchita da recupero +- **[04 - Tools](../04-tools/README.md)** - Implementa chiamate di funzione e catene di strumenti +- **[05 - MCP](../05-mcp/README.md)** - Integra il Model Context Protocol -Il README di ogni modulo fornisce spiegazioni dettagliate dei concetti trattati qui. +Il README di ogni modulo fornisce spiegazioni dettagliate dei concetti testati qui. --- -**Navigazione:** [← Torna alla Home](../README.md) +**Navigazione:** [← Torna al principale](../README.md) --- **Disclaimer**: -Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Pur impegnandoci per l’accuratezza, si prega di considerare che le traduzioni automatiche possono contenere errori o inesattezze. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda la traduzione professionale effettuata da un esperto umano. Non ci assumiamo alcuna responsabilità per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. +Questo documento è stato tradotto utilizzando il servizio di traduzione AI [Co-op Translator](https://github.com/Azure/co-op-translator). Sebbene ci impegniamo per garantire la precisione, si prega di notare che le traduzioni automatizzate possono contenere errori o imprecisioni. Il documento originale nella sua lingua nativa deve essere considerato la fonte autorevole. Per informazioni critiche, si raccomanda una traduzione professionale effettuata da un essere umano. Non siamo responsabili per eventuali malintesi o interpretazioni errate derivanti dall’uso di questa traduzione. \ No newline at end of file diff --git a/translations/ja/.co-op-translator.json b/translations/ja/.co-op-translator.json index c51e6b623..4d3eb81f7 100644 --- a/translations/ja/.co-op-translator.json +++ b/translations/ja/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ja" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T22:53:02+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T07:40:13+00:00", "source_file": "01-introduction/README.md", "language_code": "ja" }, @@ -18,20 +18,20 @@ "language_code": "ja" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T22:55:27+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T07:34:48+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ja" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T22:56:54+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T07:39:12+00:00", "source_file": "03-rag/README.md", "language_code": "ja" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:54:33+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T07:37:40+00:00", "source_file": "04-tools/README.md", "language_code": "ja" }, @@ -54,8 +54,8 @@ "language_code": "ja" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:42:39+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T07:33:15+00:00", "source_file": "README.md", "language_code": "ja" }, @@ -72,14 +72,14 @@ "language_code": "ja" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T23:00:19+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T07:35:31+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ja" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T23:01:11+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T07:36:12+00:00", "source_file": "docs/TESTING.md", "language_code": "ja" } diff --git a/translations/ja/00-quick-start/README.md b/translations/ja/00-quick-start/README.md deleted file mode 100644 index b8aa89c57..000000000 --- a/translations/ja/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# モジュール 00: クイックスタート - -## 目次 - -- [はじめに](../../../00-quick-start) -- [LangChain4jとは？](../../../00-quick-start) -- [LangChain4jの依存関係](../../../00-quick-start) -- [前提条件](../../../00-quick-start) -- [セットアップ](../../../00-quick-start) - - [1. GitHubトークンを取得する](../../../00-quick-start) - - [2. トークンを設定する](../../../00-quick-start) -- [例を実行する](../../../00-quick-start) - - [1. 基本的なチャット](../../../00-quick-start) - - [2. プロンプトパターン](../../../00-quick-start) - - [3. 関数呼び出し](../../../00-quick-start) - - [4. ドキュメントQ&A（Easy RAG）](../../../00-quick-start) - - [5. 責任あるAI](../../../00-quick-start) -- [各例で何を学べるか](../../../00-quick-start) -- [次のステップ](../../../00-quick-start) -- [トラブルシューティング](../../../00-quick-start) - -## はじめに - -このクイックスタートは、LangChain4jをできるだけ早く始められるように設計されています。LangChain4jとGitHubモデルを使ったAIアプリケーション構築の基本をカバーします。次のモジュールではAzure OpenAIとGPT-5.2に切り替え、それぞれの概念をより深く掘り下げます。 - -## LangChain4jとは？ - -LangChain4jはJavaライブラリで、AI搭載アプリケーションの構築を簡素化します。HTTPクライアントやJSON解析を扱う代わりに、クリーンなJava APIを使って作業します。 - -LangChainの「チェーン」は複数のコンポーネントを連結することを指します。プロンプトからモデル、モデルからパーサーへ、または複数のAI呼び出しを連結して、一つの出力が次の入力に繋がるようにします。このクイックスタートでは、より複雑なチェーンを探索する前に基本に焦点を当てます。 - -LangChain4j Chaining Concept - -*LangChain4jのチェーンコンポーネント – ブロックを組み合わせて強力なAIワークフローを構築* - -主に以下の三つのコアコンポーネントを使用します： - -**ChatModel** - AIモデルとの対話用インターフェース。`model.chat("prompt")`を呼び出して応答文字列を得ます。OpenAI互換のエンドポイントで動作する`OpenAiOfficialChatModel`を使用します。 - -**AiServices** - 型安全なAIサービスインターフェースを作成します。メソッドを定義し、`@Tool`で注釈を付けると、LangChain4jが全体のオーケストレーションを処理します。AIは必要に応じて自動的にJavaメソッドを呼び出します。 - -**MessageWindowChatMemory** - 会話履歴を維持します。これがないと各リクエストは独立していますが、これがあるとAIは前のメッセージを記憶し、複数のターンにわたるコンテキストを保ちます。 - -LangChain4j Architecture - -*LangChain4jアーキテクチャ – コアコンポーネントが協働しAIアプリケーションに力を与える* - -## LangChain4jの依存関係 - -このクイックスタートでは、[`pom.xml`](../../../00-quick-start/pom.xml)の３つのMaven依存を利用します。 - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official`モジュールは、OpenAI互換APIに接続する`OpenAiOfficialChatModel`クラスを提供します。GitHub Modelsは同じAPI形式を使っているため、特別なアダプターは不要で、ベースURLを`https://models.github.ai/inference`に指定するだけです。 - -`langchain4j-easy-rag`モジュールは自動的なドキュメント分割、埋め込み、および検索機能を提供し、手動設定なしでRAGアプリケーションを構築できます。 - -## 前提条件 - -**Dev Containerを使う場合？** JavaとMavenはすでにインストールされています。必要なのはGitHubパーソナルアクセストークンのみです。 - -**ローカル開発：** -- Java 21以上、Maven 3.9以上 -- GitHubパーソナルアクセストークン（下記手順参照） - -> **注意:** このモジュールはGitHub Modelsの`gpt-4.1-nano`を使用します。コード内のモデル名は変更しないでください。GitHubの利用可能モデルに合わせて設定されています。 - -## セットアップ - -### 1. GitHubトークンを取得する - -1. [GitHub設定 → パーソナルアクセストークン](https://github.com/settings/personal-access-tokens)に移動 -2. 「新しいトークンを生成」をクリック -3. 説明的な名前を設定（例：「LangChain4j Demo」） -4. 有効期限を設定（7日推奨） -5. 「アカウント権限」から「Models」を見つけて「読み取り専用」に設定 -6. 「トークンを生成」をクリック -7. トークンをコピーし保存してください—再表示されません - -### 2. トークンを設定する - -**オプション1: VS Codeを使用（推奨）** - -VS Codeを使う場合、プロジェクトルートの`.env`ファイルにトークンを追加します： - -`.env`ファイルが存在しない場合は、`.env.example`をコピーして`.env`として保存するか、新規作成してください。 - -**例 `.env` ファイル:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env にて -GITHUB_TOKEN=your_token_here -``` - -それから、エクスプローラーで任意のデモファイル（例: `BasicChatDemo.java`）を右クリックして**「Run Java」**を選択するか、実行とデバッグパネルの起動構成を使います。 - -**オプション2: ターミナルを使用** - -環境変数としてトークンを設定します： - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## 例を実行する - -**VS Codeを使う場合：** エクスプローラーで任意のデモファイルを右クリックし、**「Run Java」**を選択するか、実行とデバッグパネルの起動構成を使ってください（事前にトークンを`.env`ファイルに設定していることを確認してください）。 - -**Mavenを使う場合：** コマンドラインから次のように実行できます： - -### 1. 基本的なチャット - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. プロンプトパターン - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -ゼロショット、数ショット、連鎖思考、ロールベースのプロンプトを示します。 - -### 3. 関数呼び出し - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AIは必要に応じて自動的にあなたのJavaメソッドを呼び出します。 - -### 4. ドキュメントQ&A（Easy RAG） - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -自動埋め込みと検索を用いたEasy RAGでドキュメントへの質問が可能です。 - -### 5. 責任あるAI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -AIセーフティフィルターが有害な内容をブロックする様子を確認できます。 - -## 各例で何を学べるか - -**基本的なチャット** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -ここから始めて、LangChain4jの最も基本的な部分を見てみましょう。`OpenAiOfficialChatModel`を作成し、`.chat()`でプロンプトを送り、応答を得る方法を示します。これはモデル初期化の基礎を示し、エンドポイントやAPIキーのカスタム設定方法を学べます。このパターンを理解すれば他のすべての学習に応用できます。 - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す：** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java)を開いて質問してください： -> - 「このコードでGitHub ModelsからAzure OpenAIに切り替えるにはどうすれば良いですか？」 -> - 「OpenAiOfficialChatModel.builder()で設定できる他のパラメータは何ですか？」 -> - 「応答完了を待たずにストリーミングレスポンスを追加するにはどうしますか？」 - -**プロンプトエンジニアリング** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -モデルとの会話方法が分かったら、次は何を話すかを探ります。このデモでは同じモデル設定で5つの異なるプロンプトパターンを示します。ゼロショットプロンプト（直接指示）、少数ショットプロンプト（例から学習）、連鎖思考プロンプト（推論過程の開示）、ロールベースプロンプト（文脈設定）などです。リクエストの枠組み次第で同じモデルが劇的に異なる結果を返すことが分かります。 - -また、変数付きで再利用可能なプロンプトを作成する強力な方法としてプロンプトテンプレートも示します。 -下記例ではLangChain4jの`PromptTemplate`を使って変数を埋めています。AIは指定された目的地とアクティビティに基づいて答えます。 - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す：** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java)を開いて質問してください： -> - 「ゼロショットと少数ショットプロンプトの違いと、それぞれを使うべき場面は？」 -> - 「temperatureパラメータはモデルの応答にどう影響しますか？」 -> - 「本番環境でのプロンプトインジェクション攻撃を防ぐ技術は何ですか？」 -> - 「共通パターン用の再利用可能なPromptTemplateオブジェクトをどう作成しますか？」 - -**ツール統合** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -ここでLangChain4jの力を実感できます。`AiServices`を使い、Javaメソッドを呼び出せるAIアシスタントを作成します。メソッドに`@Tool("説明")`を付けるだけで、LangChain4jがすべて処理し、AIはユーザーの要望に応じて適切なツールを呼び出します。これは関数呼び出しの技術で、質問に答えるだけでなくアクションを実行するAI構築の重要技法です。 - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す：** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java)を開いて質問してください： -> - 「@Tool 注釈はどう機能し、LangChain4jはそれを内部でどう扱いますか？」 -> - 「AIは複数のツールを順番に呼び出して複雑な問題を解決できますか？」 -> - 「ツールが例外を投げた時はどうすれば良いですか？」 -> - 「この計算機例の代わりに実際のAPIを統合するにはどうしますか？」 - -**ドキュメントQ&A（Easy RAG）** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -ここではLangChain4jの「Easy RAG」アプローチを使ったRAG（検索強化生成）を紹介します。ドキュメントを読み込み、自動分割・埋め込みしてメモリ内ストアに保存し、検索時に関連チャンクをAIに供給します。AIは一般知識ではなくあなたのドキュメントに基づいて回答します。 - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す：** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)を開いて質問してください： -> - 「RAGはモデルの訓練データを使うのと比べてAIの幻覚をどう防ぎますか？」 -> - 「この簡単な方法とカスタムRAGパイプラインの違いは何ですか？」 -> - 「複数ドキュメントや大規模ナレッジベースでのスケールアップはどうしますか？」 - -**責任あるAI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -多層防御でAIの安全性を構築します。このデモでは二段階の保護を示します： - -**パート1: LangChain4jの入力ガードレール** - LLMに到達する前に危険なプロンプトをブロックします。禁止キーワードやパターンをチェックする独自ガードレールを作成可能。コード内で動作するため、高速かつ無料です。 - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**パート2: プロバイダーの安全フィルター** - GitHub Modelsに組み込まれたフィルターで、ガードレールをすり抜ける内容も検出します。重大な違反にはハードブロック（HTTP 400エラー）、軽度のものはAIが丁寧に拒否します。 - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す：** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java)を開いて質問してください： -> - 「InputGuardrailとは何ですか？どうやって自分で作るのですか？」 -> - 「ハードブロックとソフト拒否の違いは何ですか？」 -> - 「なぜガードレールとプロバイダーフィルターの両方を使うのですか？」 - -## 次のステップ - -**次のモジュール:** [01-introduction - LangChain4jを始める](../01-introduction/README.md) - ---- - -**ナビゲーション:** [← メインに戻る](../README.md) | [次へ: モジュール 01 - はじめに →](../01-introduction/README.md) - ---- - -## トラブルシューティング - -### 初回のMavenビルド - -**問題:** 初めての`mvn clean compile`や`mvn package`が非常に時間がかかる（10-15分） - -**原因:** Mavenが初回ビルド時にすべての依存関係（Spring Boot、LangChain4jライブラリ、Azure SDKなど）をダウンロードするため - -**解決策:** 正常な挙動です。次回以降は依存関係がローカルにキャッシュされるため高速になります。ダウンロード時間はネットワーク速度に依存します。 - -### PowerShellでのMavenコマンド構文 - -**問題:** Mavenコマンドが`Unknown lifecycle phase ".mainClass=..."`エラーで失敗する -**原因**: PowerShell は `=` を変数代入演算子として解釈し、Maven のプロパティ構文を壊してしまう - -**解決策**: Maven コマンドの前に停止解析演算子 `--%` を使う： - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` 演算子は PowerShell に対して、残りのすべての引数を解釈せずに文字通り Maven に渡すよう指示する。 - -### Windows PowerShell の絵文字表示 - -**問題**: PowerShell で AI の応答が絵文字の代わりに文字化け（例：`????` や `â??`）として表示される - -**原因**: PowerShell の既定のエンコーディングは UTF-8 絵文字に対応していない - -**解決策**: Java アプリケーションの実行前に次のコマンドを実行する： -```cmd -chcp 65001 -``` - -これによりターミナルで UTF-8 エンコーディングが強制される。あるいは、Unicode のサポートが優れている Windows Terminal を使用する方法もある。 - -### API コールのデバッグ - -**問題**: 認証エラー、レート制限、または AI モデルからの予期しない応答 - -**解決策**: サンプルコードには `.logRequests(true)` と `.logResponses(true)` が含まれており、API コールをコンソールに表示する。これにより認証エラーやレート制限、予期しない応答のトラブルシューティングがしやすくなる。本番環境ではログのノイズを減らすためにこれらのフラグを外すこと。 - ---- - - -**免責事項**： -本書類はAI翻訳サービス[Co-op Translator](https://github.com/Azure/co-op-translator)を使用して翻訳されました。正確性の確保に努めておりますが、自動翻訳には誤りや不正確な部分が含まれる可能性があります。原文（原言語）の書類が正式かつ権威ある情報源とみなされます。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じた誤解や誤訳について、当方は一切責任を負いません。 - \ No newline at end of file diff --git a/translations/ja/01-introduction/README.md b/translations/ja/01-introduction/README.md index 5890171fa..5de5c51c8 100644 --- a/translations/ja/01-introduction/README.md +++ b/translations/ja/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j 入門 +# Module 01: LangChain4j のはじめ方 ## 目次 -- [動画ウォークスルー](../../../01-introduction) -- [学べること](../../../01-introduction) -- [前提条件](../../../01-introduction) -- [コア問題の理解](../../../01-introduction) -- [トークンの理解](../../../01-introduction) -- [メモリの仕組み](../../../01-introduction) -- [LangChain4j の利用方法](../../../01-introduction) -- [Azure OpenAI インフラの展開](../../../01-introduction) -- [アプリケーションのローカル実行](../../../01-introduction) -- [アプリケーションの使用方法](../../../01-introduction) - - [ステートレスチャット（左パネル）](../../../01-introduction) - - [ステートフルチャット（右パネル）](../../../01-introduction) -- [次のステップ](../../../01-introduction) +- [動画ウォークスルー](#動画ウォークスルー) +- [学習内容](#学習内容) +- [前提条件](#前提条件) +- [コア問題の理解](#コア問題の理解) +- [トークンの理解](#トークンの理解) +- [メモリの仕組み](#メモリの仕組み) +- [LangChain4j の使用方法](#langchain4j-の使用方法) +- [Azure OpenAI インフラの展開](#azure-openai-インフラの展開) +- [ローカルでアプリケーションを実行する](#ローカルでアプリケーションを実行する) +- [アプリケーションの使用方法](#アプリケーションの使用方法) + - [ステートレスチャット（左パネル）](#ステートレスチャット（左パネル）) + - [ステートフルチャット（右パネル）](#ステートフルチャット（右パネル）) +- [次のステップ](#次のステップ) ## 動画ウォークスルー -このモジュールの始め方を説明するライブセッションをご覧ください： +このモジュールの始め方を説明するライブセッションを見る： Getting Started with LangChain4j - Live Session -## 学べること +## 学習内容 -クイックスタートでは、GitHub Models を使ってプロンプト送信、ツール呼び出し、RAG パイプラインの構築、ガードレールのテストを行いました。これらのデモは可能なことを示しました — 今回は Azure OpenAI と GPT-5.2 に切り替え、本格的なプロダクションアプリケーションの構築を始めます。このモジュールは、会話のコンテキストを記憶し状態を維持する会話型AIにフォーカスします — クイックスタートデモで使われていたが説明されていなかった概念です。 +これは LangChain4j と Azure OpenAI の出発点です。基本から始めて、本格的なアプリケーションを構築していきます。このモジュールは、会話の文脈を覚え状態を維持する対話型AIに焦点を当てており、後のすべてのモジュールで基盤となる概念です。 -本ガイドでは Azure OpenAI の GPT-5.2 を通して利用します。高度な推論機能により、異なるパターンの挙動がより明確に分かります。メモリを追加すると、その違いがはっきり見えます。これにより、各コンポーネントがアプリケーションに何をもたらすか理解しやすくなります。 +このガイド全体で Azure OpenAI の GPT-5.2 を使用します。高度な推論機能により、異なるパターンの挙動の違いが明確になるためです。メモリを追加すると、その違いがはっきり分かります。これにより、それぞれのコンポーネントがアプリケーションにもたらす効果を理解しやすくなります。 -以下の2つのパターンを示すアプリケーションを構築します： +両方のパターンを示すアプリケーションを1つ作成します： -**ステートレスチャット** - 各リクエストは独立しています。モデルは前回のメッセージを記憶しません。クイックスタートで使ったのはこのパターンです。 +ステートレスチャット - 各リクエストは独立しています。モデルは前のメッセージを覚えていません。最もシンプルな出発点です。 -**ステートフル会話** - 各リクエストに会話履歴を含みます。モデルは複数ターンの文脈を維持します。これがプロダクションアプリケーションで必要なパターンです。 +ステートフル会話 - 各リクエストに会話履歴が含まれます。モデルは複数ターンにわたって文脈を維持します。これは本番アプリケーションで必須です。 ## 前提条件 -- Azure OpenAI へのアクセスがある Azure サブスクリプション +- Azure OpenAI アクセスがある Azure サブスクリプション - Java 21、Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **注意：** Java、Maven、Azure CLI、Azure Developer CLI (azd) は提供された devcontainer に事前インストールされています。 +> **Note:** Java、Maven、Azure CLI、Azure Developer CLI (azd) は提供される devcontainer に事前にインストールされています。 -> **注意：** 本モジュールは Azure OpenAI の GPT-5.2 を使用します。`azd up` で自動的に展開されるため、コード内のモデル名は変更しないでください。 +> **Note:** 本モジュールは Azure OpenAI の GPT-5.2 を使用します。展開は `azd up` により自動設定されます。コード内のモデル名を変更しないでください。 ## コア問題の理解 -言語モデルはステートレスです。各 API コールは独立しています。「私の名前はジョンです」と送っても、次に「私の名前は何？」と聞いても、モデルは直前に自己紹介を受けたことを知りません。すべてのリクエストをその会話が初めてであるかのように扱います。 +言語モデルはステートレス（状態を持たない）です。各API呼び出しは独立しています。「私の名前はジョンです」と送ってから「私の名前は何ですか？」と尋ねても、モデルは自己紹介した直後だとは認識しません。すべてのリクエストを、今までで初めての会話だと扱います。 -これは単純な Q&A には問題ありませんが、本物のアプリケーションには役に立ちません。カスタマーサービスボットはユーザーからの情報を記憶している必要があります。パーソナルアシスタントは文脈を必要とします。マルチターン会話はメモリを要求します。 +これは簡単なQ&Aには使えますが、本格的なアプリケーションには役に立ちません。カスタマーサポートのボットはあなたが何を言ったか覚える必要があります。パーソナルアシスタントは文脈を必要とします。複数ターンの対話にはメモリが不可欠です。 -以下の図は2つのアプローチを対比しています — 左は名前を忘れるステートレス呼び出し、右は ChatMemory が背後にあるステートフル呼び出しです。 +下図は両者の対比です — 左は名前を忘れるステートレス呼び出し、右はChatMemoryで名前を覚えているステートフル呼び出しです。 Stateless vs Stateful Conversations -*ステートレス（独立した呼び出し）とステートフル（コンテキスト認識）会話の違い* +*ステートレス（独立呼び出し）とステートフル（文脈認識）会話の違い* ## トークンの理解 -会話に入る前に、トークンの理解が重要です — 言語モデルが処理するテキストの基本単位： +会話に入る前に、トークンを理解することが重要です。トークンは言語モデルが処理するテキストの基本単位です： Token Explanation -*テキストがどのようにトークンに分割されるかの例 — 「I love AI!」は4つの別々の処理単位になる* +*テキストがトークンに分解される例 — 「I love AI!」は4つの別々の処理単位になる* -トークンは AI モデルがテキストを計測・処理する単位です。単語、句読点、スペースもトークンになり得ます。モデルには同時に処理できるトークン数の制限があります（GPT-5.2 は最大400,000トークン、入力最大272,000、出力最大128,000）。トークンの理解は会話の長さやコスト管理に役立ちます。 +トークンはAIモデルがテキストを計測・処理する単位です。単語、句読点、スペースもトークンになり得ます。モデルには一度に処理できるトークン数の上限があり（GPT-5.2では40万トークン、入力最大27.2万トークン＋出力最大12.8万トークン）、トークンを理解することは会話の長さとコスト管理に役立ちます。 ## メモリの仕組み -チャットメモリはステートレス問題を解決するため、会話履歴を保ちます。リクエストをモデルに送る前に、関連する過去のメッセージを前置きします。「私の名前は何？」と聞くと、実際にはこれまでの会話履歴全体を送り、モデルは「私の名前はジョンです」と言われていたことを参照できます。 +チャットメモリは、ステートレス問題を解決し会話履歴を保持します。リクエストをモデルに送る前に、フレームワークは関連する過去のメッセージを先頭に付け加えます。「私の名前は何ですか？」と聞くと、実際には全会話履歴が送られ、モデルは「私の名前はジョンです」と以前に言ったことを見られます。 -LangChain4j はこの処理を自動化するメモリの実装を提供します。保持するメッセージ数を指定すれば、フレームワークがコンテキストウィンドウを管理します。下図は MessageWindowChatMemory が最新メッセージのスライディングウィンドウを維持する様子です。 +LangChain4j は、この処理を自動化するメモリ実装を提供します。保持するメッセージ数を選択でき、フレームワークがコンテキストウィンドウを管理します。下図は MessageWindowChatMemory が最近のメッセージのスライディングウィンドウを維持する様子です。 Memory Window Concept -*MessageWindowChatMemory は最近のメッセージのスライディングウィンドウを維持し、古いものを自動削除* +*MessageWindowChatMemory は最近のメッセージのスライドウィンドウを管理し、古いメッセージを自動的に破棄する* -## LangChain4j の利用方法 +## LangChain4j の使用方法 -このモジュールはクイックスタートを拡張し、Spring Boot と会話メモリを統合します。構成は以下の通り： +このモジュールは Spring Boot と会話メモリを統合しています。構成は以下の通りです： -**依存関係** — 2つの LangChain4j ライブラリを追加： +依存関係 — 2つの LangChain4j ライブラリを追加： ```xml @@ -94,7 +94,7 @@ LangChain4j はこの処理を自動化するメモリの実装を提供しま ``` -**チャットモデル** — Azure OpenAI を Spring Bean として設定 ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java))： +チャットモデル — Azure OpenAI を Spring Bean として設定 ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java))： ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -ビルダーは `azd up` で設定された環境変数から認証情報を読み込みます。`baseUrl` を Azure エンドポイントに設定することで、OpenAI クライアントは Azure OpenAI と連携します。 +ビルダーは `azd up` によって設定された環境変数から認証情報を読み取ります。`baseUrl` に Azure エンドポイントを設定することで、OpenAI クライアントが Azure OpenAI に対応します。 -**会話メモリ** — MessageWindowChatMemory でチャット履歴をトラック ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java))： +会話メモリ — MessageWindowChatMemory でチャット履歴を追跡 ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java))： ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,39 +124,39 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` で直近10メッセージを保持します。ユーザーとAIのメッセージは型付きラッパーで追加：`UserMessage.from(text)` と `AiMessage.from(text)`。履歴は `memory.messages()` で取得しモデルへ送信。サービスは会話IDごとに別々のメモリインスタンスを保持し、複数ユーザーの同時チャットに対応します。 +`withMaxMessages(10)` で直近10メッセージを保持するメモリを作成。ユーザー・AIメッセージは型付きラッパーで追加：`UserMessage.from(text)` と `AiMessage.from(text)`。`memory.messages()` で履歴を取得しモデルに渡します。サービスは会話IDごとにメモリを分けて保持するため、複数ユーザーの同時会話が可能です。 -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat で試すには：** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) を開いて、以下を質問： -> - "MessageWindowChatMemory はウィンドウがいっぱいの時どのメッセージをドロップするかどう決めているの？" -> - "インメモリの代わりにデータベースを使ったカスタムメモリストレージは実装可能？" -> - "古い会話履歴を圧縮するために要約機能を追加するには？" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat も活用してみましょう：** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) を開き、以下を質問： +> - 「MessageWindowChatMemory はウィンドウが満杯の時にどのメッセージを破棄するかどう決めているの？」 +> - 「インメモリではなくデータベースを使ったカスタムメモリストレージを実装できる？」 +> - 「古い会話履歴を圧縮するために要約を追加するにはどうする？」 -ステートレスチャットエンドポイントはメモリを完全にスキップし、クイックスタートと同じく `chatModel.chat(prompt)` のみ。ステートフルエンドポイントはメモリにメッセージを追加、履歴を取得し、そのコンテキストを含めてリクエストします。同じモデル設定ですが異なるパターンです。 +ステートレスチャットのエンドポイントはメモリを使わず、`chatModel.chat(prompt)` のみでクイックスタートと同様です。ステートフルはメモリにメッセージを追加し履歴を取得、毎回その文脈をリクエストに含めます。同じモデル設定で異なるパターンを体験できます。 ## Azure OpenAI インフラの展開 **Bash:** ```bash cd 01-introduction -azd up # サブスクリプションと場所を選択します（eastus2 推奨） +azd up # サブスクリプションと場所を選択します（eastus2推奨） ``` **PowerShell:** ```powershell cd 01-introduction -azd up # サブスクリプションと場所を選択してください（eastus2がおすすめ） +azd up # サブスクリプションと場所を選択してください（eastus2推奨） ``` -> **注意:** タイムアウトエラー (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) が出た場合は、単純に `azd up` を再実行してください。Azure リソースはまだプロビジョニング中の可能性があり、再試行でリソースが確定状態になると展開が完了します。 +> **Note:** タイムアウトエラー (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) が起きても、`azd up` を再度実行してください。Azure リソースはまだ展開中かもしれず、再試行でリソースが最終状態に到達すれば展開が完了します。 -これで以下が行われます： -1. GPT-5.2 と text-embedding-3-small モデルを備えた Azure OpenAI リソースを展開 -2. プロジェクトルートに `.env` ファイルを自動生成（認証情報入り） -3. 必要な環境変数をすべて設定 +これにより： +1. GPT-5.2 と text-embedding-3-small モデルを持つ Azure OpenAI リソースを展開 +2. プロジェクトルートに資格情報入りの `.env` ファイルが自動生成 +3. 必要な環境変数がすべて設定される -**展開に問題がある場合**は [Infrastructure README](infra/README.md) を参照してください。サブドメイン名の衝突、Azure ポータルでの手動デプロイ手順、モデル構成の案内を含みます。 +**展開に問題がありますか？** サブドメイン名の競合、Azure ポータル手動展開手順、モデル構成ガイダンスなど詳しいトラブルシューティングは [Infrastructure README](infra/README.md) を参照してください。 -**展開成功の確認：** +**展開が成功したか確認：** **Bash:** ```bash @@ -165,10 +165,10 @@ cat ../.env # AZURE_OPENAI_ENDPOINT、API_KEYなどを表示する必要があ **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT、API_KEYなどを表示する必要があります。 +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT、API_KEY などを表示する必要があります。 ``` -> **注意:** `azd up` コマンドは自動で `.env` ファイルを生成します。後で更新が必要な場合は `.env` を直接編集するか、以下のコマンドで再生成可能です： +> **Note:** `azd up` コマンドは `.env` ファイルを自動生成します。後から更新する必要があれば、手動で編集するか以下のコマンドで再生成できます： > > **Bash:** > ```bash @@ -182,12 +182,11 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT、API_KEYなどを表示する必 > .\.azd-env.ps1 > ``` +## ローカルでアプリケーションを実行する -## アプリケーションのローカル実行 +**展開の検証：** -**展開の確認：** - -Azure 認証情報を含む `.env` ファイルがルートディレクトリに存在していることを確認し、モジュールディレクトリ (`01-introduction/`) で以下を実行： +Azure資格情報が入った `.env` ファイルがルートにあることを確認し、モジュールディレクトリ（`01-introduction/`）から以下を実行： **Bash:** ```bash @@ -199,27 +198,27 @@ cat ../.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENTを表示する必要 Get-Content ..\.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT を表示する必要があります ``` -**アプリケーションの起動：** +**アプリケーションを起動：** -**オプション1: Spring Boot Dashboard の利用（VS Code ユーザーに推奨）** +**オプション1：Spring Boot ダッシュボードを使用（VS Codeユーザー推奨）** -devcontainer には Spring Boot Dashboard 拡張機能が含まれており、Spring Boot アプリを視覚的に管理できます。VS Code 左側のアクティビティバーにある Spring Boot アイコンでアクセス可能です。 +開発コンテナには Spring Boot ダッシュボード拡張機能が含まれており、VS Code 左のアクティビティバーの Spring Boot アイコンから全Spring Bootアプリケーションを視覚的に管理できます。 -Spring Boot Dashboard から： -- ワークスペース内のすべての Spring Boot アプリを確認 -- ワンクリックで起動/停止 -- リアルタイムでログ表示 -- アプリの状態監視 +ダッシュボードからは： +- ワークスペース内のすべてのSpring Bootアプリケーションを一覧表示 +- ワンクリックでアプリの起動/停止 +- リアルタイムでアプリケーションログを閲覧 +- アプリの状態を監視 -"introduction" の横の再生ボタンをクリックするだけでこのモジュールを起動、またはすべてのモジュールを一括起動できます。 +「introduction」の横の再生ボタンを押せばこのモジュールが起動、またはすべてのモジュールを同時に起動できます。 Spring Boot Dashboard -*VS Code の Spring Boot Dashboard — すべてのモジュールをまとめて起動、停止、監視可能* +*VS Code の Spring Boot ダッシュボード — 一箇所から全モジュールを起動・停止・監視* -**オプション2: シェルスクリプト利用** +**オプション2：シェルスクリプトを使う方法** -すべてのウェブアプリ（モジュール01-04）を起動: +すべてのウェブアプリ（モジュール01-04）を起動： **Bash:** ```bash @@ -233,7 +232,7 @@ cd .. # ルートディレクトリから .\start-all.ps1 ``` -このモジュールだけ起動: +または、このモジュールだけを起動： **Bash:** ```bash @@ -247,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -両スクリプトはルートの `.env` ファイルから環境変数を自動読み込みし、JAR がなければビルドも行います。 +いずれのスクリプトもルートの `.env` ファイルから環境変数を自動で読み込み、JARが無ければビルドします。 -> **注意:** 起動前にすべてのモジュールを手動ビルドしたい場合： +> **Note:** もし、起動前にすべてのモジュールを手動でビルドしたい場合： > > **Bash:** > ```bash @@ -281,44 +280,43 @@ cd .. && ./stop-all.sh # すべてのモジュール cd ..; .\stop-all.ps1 # すべてのモジュール ``` - ## アプリケーションの使用方法 -アプリケーションは2つのチャット実装を並べて Web インターフェイスで提供します。 +このアプリには2種類のチャット実装が並んで表示されるウェブインターフェイスがあります。 Application Home Screen -*シンプルチャット（ステートレス）と会話チャット（ステートフル）の両オプションを表示するダッシュボード* +*シンプルチャット（ステートレス）と会話チャット（ステートフル）を両方表示するダッシュボード* ### ステートレスチャット（左パネル） -まずはこちらを試してください。「私の名前はジョンです」と伝え、直後に「私の名前は何ですか？」と聞いてみましょう。モデルは覚えていません。各メッセージが独立しているためです。これは基本的な言語モデル統合のコア問題 — 会話の文脈がないことを示します。 +まずはこちらを試してください。「私の名前はジョンです」と言い、すぐに「私の名前は何ですか？」と尋ねると、モデルは記憶していません。メッセージは独立しているためです。これは基本的な言語モデル統合におけるコア問題を示しています — 会話文脈が無いこと。 Stateless Chat Demo -*AIは前のメッセージからあなたの名前を覚えていません* +*AIは前のメッセージから名前を覚えません* ### ステートフルチャット（右パネル） -同じ流れをこちらでも試します。「私の名前はジョンです」と伝え、「私の名前は何ですか？」と聞くと、今回は覚えています。違いは MessageWindowChatMemory です — 会話履歴を維持し、それをリクエストに含めます。これが本番の会話 AI の動作方法です。 +同じ順番をこちらで試してください。「私の名前はジョンです」と言い、そのあと「私の名前は何ですか？」と言うと、今回は覚えています。違いは MessageWindowChatMemory で、会話履歴を保持し、毎回のリクエストに含めています。これが本番用の会話型AIの仕組みです。 Stateful Chat Demo -*AIは会話の初めにあなたの名前を覚えています* +*AIは以前の会話から名前を覚えています* -両パネルとも同じ GPT-5.2 モデルを使います。違うのはメモリだけです。これによりメモリがアプリに何をもたらし、実利用でなぜ不可欠かが明瞭になります。 +両パネルは同じ GPT-5.2 モデルを使用し、違いはメモリだけです。これによりメモリがアプリケーションに何をもたらすかが明確になり、実際のユースケースで不可欠な理由が理解できます。 ## 次のステップ -**次のモジュール：** [02-prompt-engineering - GPT-5.2 によるプロンプトエンジニアリング](../02-prompt-engineering/README.md) +**次のモジュール:** [02-prompt-engineering - GPT-5.2によるプロンプトエンジニアリング](../02-prompt-engineering/README.md) --- -**ナビゲーション：** [← 前：Module 00 - クイックスタート](../00-quick-start/README.md) | [メインに戻る](../README.md) | [次：Module 02 - プロンプトエンジニアリング →](../02-prompt-engineering/README.md) +**ナビゲーション:** [← メインへ戻る](../README.md) | [次へ: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- -**免責事項**： -本書類はAI翻訳サービス[Co-op Translator](https://github.com/Azure/co-op-translator)を使用して翻訳されました。正確性を期していますが、自動翻訳には誤りや不正確な箇所が含まれる場合があります。原文の母国語版が正式な情報源とみなされます。重要な情報については、専門の人間による翻訳をお勧めします。本翻訳の利用により生じた誤解や誤訳について、当方は一切の責任を負いかねます。 +**免責事項**： +本書類は AI 翻訳サービス [Co-op Translator](https://github.com/Azure/co-op-translator) を使用して翻訳されています。正確性を期していますが、自動翻訳には誤りや不正確な部分が含まれる可能性があることをご承知おきください。原文の原語版が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じたいかなる誤解や解釈違いについても、当方は責任を負いかねます。 \ No newline at end of file diff --git a/translations/ja/02-prompt-engineering/README.md b/translations/ja/02-prompt-engineering/README.md index a68344c06..393cc025c 100644 --- a/translations/ja/02-prompt-engineering/README.md +++ b/translations/ja/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# モジュール 02: GPT-5.2 を使ったプロンプトエンジニアリング +# Module 02: GPT-5.2によるプロンプトエンジニアリング ## 目次 -- [ビデオウォークスルー](../../../02-prompt-engineering) -- [学習内容](../../../02-prompt-engineering) -- [前提条件](../../../02-prompt-engineering) -- [プロンプトエンジニアリングの理解](../../../02-prompt-engineering) -- [プロンプトエンジニアリングの基本](../../../02-prompt-engineering) - - [ゼロショットプロンプティング](../../../02-prompt-engineering) - - [フューショットプロンプティング](../../../02-prompt-engineering) - - [チェーン・オブ・ソート](../../../02-prompt-engineering) - - [ロールベースプロンプティング](../../../02-prompt-engineering) - - [プロンプトテンプレート](../../../02-prompt-engineering) -- [高度なパターン](../../../02-prompt-engineering) -- [アプリケーションの実行](../../../02-prompt-engineering) -- [アプリケーションのスクリーンショット](../../../02-prompt-engineering) -- [パターンの探求](../../../02-prompt-engineering) - - [低い意欲 vs 高い意欲](../../../02-prompt-engineering) - - [タスク実行（ツールのプレアンブル）](../../../02-prompt-engineering) - - [自己反省コード](../../../02-prompt-engineering) - - [構造化分析](../../../02-prompt-engineering) - - [マルチターンチャット](../../../02-prompt-engineering) - - [ステップバイステップ推論](../../../02-prompt-engineering) - - [制約付き出力](../../../02-prompt-engineering) -- [本当に学んでいること](../../../02-prompt-engineering) -- [次のステップ](../../../02-prompt-engineering) - -## ビデオウォークスルー - -このモジュールの始め方を説明したライブセッションをご覧ください： - -LangChain4jによるプロンプトエンジニアリング - ライブセッション +- [動画ウォークスルー](#動画ウォークスルー) +- [学習内容](#学習内容) +- [前提条件](#前提条件) +- [プロンプトエンジニアリングの理解](#プロンプトエンジニアリングの理解) +- [プロンプトエンジニアリングの基本](#プロンプトエンジニアリングの基本) + - [ゼロショットプロンプト](#ゼロショットプロンプト) + - [フューショットプロンプト](#フューショットプロンプト) + - [チェーン・オブ・ソート](#チェーン・オブ・ソート) + - [ロールベースプロンプト](#ロールベースプロンプト) + - [プロンプトテンプレート](#プロンプトテンプレート) +- [高度なパターン](#高度なパターン) +- [アプリケーションの実行](#アプリケーションを実行する) +- [アプリケーションのスクリーンショット](#アプリケーションのスクリーンショット) +- [パターンの探求](#パターンを探る) + - [低い熱意 vs 高い熱意](#low-vs-high-eagerness) + - [タスク実行（ツールプレアンブル）](#タスク実行（ツールのプレアンブル）) + - [自己反省コード](#自己反省コード) + - [構造化分析](#構造化分析) + - [マルチターンチャット](#マルチターンチャット) + - [ステップバイステップ推論](#ステップバイステップ推論) + - [制約付き出力](#制約付き出力) +- [本当に学んでいること](#本当に学んでいること) +- [次のステップ](#次のステップ) + +## 動画ウォークスルー + +このモジュールの始め方を解説するライブセッションをご覧ください: + +Prompt Engineering with LangChain4j - Live Session ## 学習内容 -以下の図は、このモジュールで開発する主要なトピックとスキルの概要を示しています — プロンプトの洗練手法から、あなたが辿るステップバイステップのワークフローまで。 +以下の図は、このモジュールで習得する主要なトピックとスキルの概要を示しています — プロンプト精緻化技術から、順を追ったワークフローまで。 -学習内容 +What You'll Learn -前のモジュールでは、GitHubモデルとの基本的なLangChain4jのやり取りを探り、Azure OpenAIによる会話型AIがメモリでどのように動作するかを見ました。今回はAzure OpenAIのGPT-5.2を使い、質問の仕方—つまりプロンプトそのものに焦点を当てます。プロンプトの構造は、得られる応答の質に劇的な影響を与えます。基本的なプロンプト技術の復習から始め、次にGPT-5.2の能力を最大限に活かす８つの高度なパターンに進みます。 +前のモジュールでは、Azure OpenAIと会話型AIのメモリ機能について見ました。今回は質問の投げ方、つまりAzure OpenAIのGPT-5.2を使った「プロンプトそのもの」に焦点を当てます。プロンプトの構造が回答の質に大きく影響します。基本的なプロンプティング技術の復習から始め、次にGPT-5.2の能力をフル活用した8つの高度なパターンへ進みます。 -GPT-5.2は推論制御を導入しているので、モデルに回答前にどれだけ考えるかを指示できます。これにより異なるプロンプト戦略がより明確になり、どのアプローチをいつ使うべきか理解が深まります。また、GPT-5.2はGitHubモデルよりAzureのレート制限が緩いため、その恩恵も受けられます。 +GPT-5.2を使う理由は、推論制御機能が導入されたためです — モデルにどれだけ考えさせるか指示できます。これにより異なるプロンプト戦略が明確になり、どの方法を使うべきか理解しやすくなります。 ## 前提条件 -- モジュール 01 を完了していること（Azure OpenAIリソースがデプロイされている） -- ルートディレクトリに Azure 資格情報が入った `.env` ファイルがあること（モジュール 01 で `azd up` により作成されたもの） +- モジュール01を完了していること（Azure OpenAIリソースが展開済み） +- ルートディレクトリにAzure認証情報を含む`.env`ファイルがあること（モジュール01の`azd up`で作成） -> **注意:** モジュール 01 を完了していない場合は、まずそこでのデプロイ手順に従ってください。 +> **注意:** モジュール01を完了していない場合は、そちらの展開手順を最初に行ってください。 ## プロンプトエンジニアリングの理解 -プロンプトエンジニアリングの本質は、あいまいな指示と正確な指示の違いにあります。以下の比較がそれを示しています。 +本質的に、プロンプトエンジニアリングは「曖昧な指示」と「正確な指示」の違いです。以下の比較図がそれを示しています。 -プロンプトエンジニアリングとは？ +What is Prompt Engineering? -プロンプトエンジニアリングは、必要な結果を一貫して引き出す入力テキストを設計することです。単に質問を投げるだけでなく、モデルに欲しい内容とその提供方法を正確に理解させるためのリクエスト構造を作ることです。 +プロンプトエンジニアリングとは、一貫して必要な結果を得るための入力テキストを設計することです。単に質問するだけではなく、モデルが何をどう届けるべきか正確に理解させるためのリクエストの構造化です。 -言い換えれば同僚に指示を出すようなものです。「バグを修正して」はあいまいです。「UserService.javaの45行目でヌルポインター例外が起きているのでヌルチェックを追加して修正して」は具体的です。言語モデルも同様に、具体性と構造が重要です。 +これは同僚に指示を出すようなものです。「バグを直して」のような曖昧な指示より、「UserService.javaの45行目のNullPointerExceptionを防ぐためにnullチェックを追加して」のように具体的です。言語モデルも同様で、具体性と構造が重要です。 -下図はLangChain4jがどのようにこの概念にフィットするかを示しています — あなたのプロンプトパターンを `SystemMessage` と `UserMessage` という構築ブロックを通じてモデルにつなげています。 +下図はLangChain4jがこの仕組みにどう関わるかを示しています — プロンプトパターンをSystemMessageやUserMessageの構成要素を通じてモデルに接続します。 -LangChain4jのフィット感 +How LangChain4j Fits -LangChain4jはインフラを提供します — モデルの接続、メモリ、メッセージタイプ — 一方でプロンプトパターンはそのインフラを通す、よく構造化されたテキストです。主要な構成要素は `SystemMessage`（AIの挙動・役割を設定）と `UserMessage`（実際のリクエストを運ぶもの）です。 +LangChain4jはインフラを提供します — モデル接続、メモリ、メッセージ種別 — プロンプトパターンはそのインフラを通じて送る注意深く構造化されたテキストです。重要な構成要素は`SystemMessage`（AIの振る舞い・役割を設定）と`UserMessage`（実際のリクエストを伝達）です。 ## プロンプトエンジニアリングの基本 -以下に示す５つのコア技術が、有効なプロンプトエンジニアリングの基礎をなします。各技術は言語モデルとのコミュニケーションの異なる側面に応えます。 +以下の5つのコアテクニックが効果的なプロンプトエンジニアリングの基盤を形成します。各技術は言語モデルとのコミュニケーションの異なる側面に対応しています。 -５つのプロンプトエンジニアリングパターンの概要 +Five Prompt Engineering Patterns Overview -このモジュールの高度なパターンに入る前に、５つの基礎的なプロンプト技術を復習しましょう。これらは全てのプロンプトエンジニアが知っておくべきビルディングブロックです。もし既に[クイックスタートモジュール](../00-quick-start/README.md#2-prompt-patterns)を経験していれば、これらは実践で見たことがあるでしょう — ここではその概念的な枠組みを示します。 +このモジュールの高度なパターンに入る前に、5つの基本的なプロンプティング技術を振り返りましょう。これはすべてのプロンプトエンジニアが知るべき基礎です。 -### ゼロショットプロンプティング +### ゼロショットプロンプト -もっとも単純な方法：例を一切示さずにモデルに直接指示を与えます。モデルはトレーニングだけを頼りにタスクを理解し実行します。予想される挙動が明白な単純な依頼に適しています。 +最もシンプルなアプローチ：例なしでモデルに直接指示を与えます。モデルはトレーニングのみを頼りにタスクを理解し実行します。この方法は期待される動作が明白な単純なリクエストに適しています。 -ゼロショットプロンプティング +Zero-Shot Prompting -*例なしの直接指示 — モデルは指示からタスクを推測する* +*例なしの直接指示 — モデルは指示だけからタスクを推測* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// 返信:「ポジティブ」 +// 反応：「ポジティブ」 ``` -**利用時:** 単純な分類、直接的な質問、翻訳、あるいは追加の指導が不要なタスク。 +**使用タイミング:** 単純な分類、直接の質問、翻訳、または追加指示なしでモデルが処理可能なタスク。 -### フューショットプロンプティング +### フューショットプロンプト -モデルに従って欲しいパターンの例を示します。モデルは例から期待される入出力フォーマットを学び、新しい入力にも適用します。これにより形式や挙動が明確でないタスクの一貫性が大幅に向上します。 +モデルに従ってほしいパターンを示す例を提供します。モデルは例から期待される入出力形式を学び、新しい入力に適用します。望ましいフォーマットや振る舞いが明白でないタスクにおける一貫性が大幅に向上します。 -フューショットプロンプティング +Few-Shot Prompting -*例から学ぶ — モデルはパターンを特定し新しい入力に適用* +*例から学習 — モデルはパターンを認識し新しい入力に適用* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**利用時:** カスタム分類、一貫したフォーマット、ドメイン固有のタスク、またはゼロショットの結果が不安定な場合。 +**使用タイミング:** カスタム分類、一貫したフォーマット、ドメイン特化タスク、またはゼロショットの結果が不安定な場合。 ### チェーン・オブ・ソート -モデルに推論を段階的に示すように頼みます。答えに飛びつくのではなく、問題を分解し各部分を明示的に考えるので、数学、論理、多段階の推論タスクの精度が向上します。 +モデルに推論プロセスを段階的に示させます。直接答えを出すのではなく、問題を分解し明示的に各部分を検証します。数学、論理、多段階推論における正確性を向上します。 -チェーン・オブ・ソートプロンプティング +Chain of Thought Prompting -*ステップごとの推論 — 複雑な問題を明確な論理ステップへ分解* +*段階的推論 — 複雑な問題を論理的な段階に細分化* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// モデルは示しています：15 - 8 = 7、次に7 + 12 = 19個のリンゴ +// このモデルは示しています：15 - 8 = 7、次に7 + 12 = 19個のりんご ``` -**利用時:** 数学の問題、論理パズル、デバッグ、または推論過程の提示が精度と信頼性を高めるタスク。 +**使用タイミング:** 数学問題、論理パズル、デバッグ、または推論プロセスを示すことで精度と信頼性が向上するタスク。 -### ロールベースプロンプティング +### ロールベースプロンプト -AIに質問する前にペルソナや役割を設定します。これにより回答のトーン、深さ、重点が形作られます。「ソフトウェアアーキテクト」と「ジュニア開発者」や「セキュリティ監査官」では異なる助言になります。 +質問の前にAIに役割やペルソナを設定します。これが応答のトーンや深さ、焦点を形成します。「ソフトウェアアーキテクト」と「ジュニア開発者」や「セキュリティ監査人」では異なるアドバイスが得られます。 -ロールベースプロンプティング +Role-Based Prompting -*コンテキストとペルソナの設定 — 同じ質問でも役割に応じて別の回答になる* +*文脈とペルソナの設定 — 同じ質問でも割り当てた役割によって応答が変わる* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**利用時:** コードレビュー、チュータリング、ドメイン固有の分析、または特定の専門性や視点に合わせた応答が必要な場合。 +**使用タイミング:** コードレビュー、指導、ドメイン特化分析、または特定の専門レベルや視点に合わせた応答が必要な場合。 ### プロンプトテンプレート -変数プレースホルダーを使った再利用可能なプロンプトを作成します。毎回新しいプロンプトを書くのではなく、一度テンプレートを定義し異なる値を埋めます。LangChain4jの `PromptTemplate` クラスは `{{variable}}` 構文でこれを簡単にします。 +変数プレースホルダーを使った再利用可能なプロンプトを作成します。毎回新しいプロンプトを作る代わりに、一度テンプレート定義し異なる値を埋め込みます。LangChain4jの`PromptTemplate`クラスは`{{variable}}`構文でこれを簡単にします。 -プロンプトテンプレート +Prompt Templates -*変数プレースホルダーを使った再利用可能なプロンプト — 一つのテンプレートで多用途* +*変数プレースホルダー付き再利用プロンプト — 1つのテンプレートで多数の使い方* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**利用時:** 入力が変わる繰り返しの問い合わせ、バッチ処理、再利用可能なAIワークフロー構築、構造は同じでデータだけ変わるシナリオ。 +**使用タイミング:** 異なる入力を使う繰り返しクエリ、バッチ処理、再利用可能なAIワークフロー構築、またはプロンプト構造は変わらずデータのみ変わる場合。 --- -これら５つの基本でほとんどのプロンプトタスクに対応可能な堅固なツールキットが得られます。このモジュールの残りは、GPT-5.2の推論制御、自己評価、構造化出力能力を活用する**８つの高度なパターン**に基づいて構築されます。 +これら5つの基本技術はほとんどのプロンプト作業に対して堅実なツールキットを提供します。このモジュールの残りは、GPT-5.2の推論制御、自己評価、構造化出力機能を活用した8つの高度なパターンに発展します。 ## 高度なパターン -基本が理解できたところで、このモジュール独自の８つの高度なパターンに進みましょう。すべての問題が同じアプローチを必要としません。いくつかの質問は即座の答えを必要とし、他はじっくり考えることが必要です。推論を明示的に示すものもあれば結果だけを求めるものもあります。以下の各パターンは異なるシナリオに最適化されており、GPT-5.2の推論制御により違いがよりはっきりします。 +基本技術を押さえたら、このモジュール特有の8つの高度なパターンに進みます。すべての問題に同じアプローチは不要です。質問によってはすばやい回答が必要なものから、深い考察が求められるものまであります。見える推論が必要な場合もあれば、結果だけが重要な場合も。以下の各パターンは異なるシナリオに最適化されており、GPT-5.2の推論制御によって違いがさらに際立ちます。 -８つのプロンプトパターン +Eight Prompting Patterns -*８つのプロンプトエンジニアリングパターンとその使用例の概要* +八つのプロンプトエンジニアリングパターンとそのユースケースの概要 -GPT-5.2はこれらパターンにもう一つの次元を加えます：*推論制御*。以下のスライダーはモデルの思考量を調整できる様子を示します — 速く直接的な答えから、深く徹底的な分析まで。 +GPT-5.2はこれらのパターンにもう一つの次元を追加します：推論制御。下のスライダーはモデルの思考の深さを調整する様子を示しています — 素早い直接回答から深く徹底した分析まで。 -GPT-5.2による推論制御 +Reasoning Control with GPT-5.2 -*GPT-5.2の推論制御により、モデルがどれだけ考えるかを指定可能 — 高速な直答から深い探求まで* +*GPT-5.2の推論制御により、モデルがどれだけ考えるか指定可能 — 速く直接的な回答から深い探求まで* -**低い意欲（速く・集中）** - 単純な質問に速く直接的な答えが欲しい場合。モデルは最少の推論（最大２ステップ）で済ませます。計算やルックアップ、単純質問に最適。 +**低い熱意（素早く・集中）** - 速く直接回答が欲しい単純な質問向け。モデルは最小限の推論のみ — 最大2ステップ。計算、検索、または簡単な質問に最適。 ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **GitHub Copilotで探る:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java)を開き、以下を聞いてみましょう： -> - 「低い意欲と高い意欲のプロンプトパターンの違いは何ですか？」 -> - 「プロンプト内のXMLタグはAIの応答構造にどう役立っていますか？」 -> - 「自己反省パターンと直接指示はいつ使い分けるべき？」 +> 💡 **GitHub Copilotで探る:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) を開き、以下の質問をしてみましょう： +> - 「低い熱意と高い熱意のプロンプトパターンの違いは何ですか？」 +> - 「プロンプト内のXMLタグはAIの応答構造化にどう役立っていますか？」 +> - 「自己反省パターンと直接指示はいつ使い分けるべきですか？」 -**高い意欲（深く・徹底）** - 複雑な問題に包括的な分析が必要な場合。モデルは詳細な推論を示し徹底的に探ります。システム設計やアーキテクチャ決定、複雑な調査に適用。 +**高い熱意（深く・徹底的）** - より複雑な問題で包括的な分析が必要なとき。モデルは徹底的に探求し詳細な推論を示します。システム設計、アーキテクチャの意思決定、複雑な調査に適します。 ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**タスク実行（ステップごとの進行）** - 複数段階のワークフローの場合。モデルは先に計画を示し、処理中に各ステップをナレーションし、最後に要約を出します。移行作業、実装、マルチステップ処理に活用。 +**タスク実行（ステップバイステップ進行）** - 多段階ワークフローで使用。モデルは最初に計画を示し、作業の各ステップを説明し、最後に要約します。移行作業や実装など複雑なプロセスに最適。 ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -チェーン・オブ・ソートプロンプティングはモデルに推論過程を明示的に示すよう頼み、複雑タスクの正確性を高めます。ステップバイステップの分解は人とAI双方の理解を促進します。 +チェーン・オブ・ソートプロンプトは明示的に推論プロセスを示すことで精度を上げます。ステップごとの分解により人間とAIの双方が論理を理解しやすくなります。 -> **🤖 [GitHub Copilot](https://github.com/features/copilot)チャットで試す:** このパターンについて質問してください： -> - 「長時間実行のオペレーションにタスク実行パターンをどう適応しますか？」 -> - 「本番アプリケーションでのツールプレアンブルの構成ベストプラクティスは？」 -> - 「UIで中間進捗をどうキャプチャし表示すれば良いですか？」 +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試そう:** このパターンについて質問してみてください： +> - 「長時間実行する操作にタスク実行パターンをどう適用しますか？」 +> - 「本番環境アプリでのツールプレアンブル構造のベストプラクティスは？」 +> - 「UIで途中進捗のキャプチャと表示をどう行いますか？」 以下の図はこの計画 → 実行 → 要約のワークフローを示します。 -タスク実行パターン +Task Execution Pattern -*マルチステップタスクのための計画 → 実行 → 要約のワークフロー* +*多段階タスクの計画 → 実行 → 要約ワークフロー* -**自己反省コード** - 本番品質コードを生成するため。モデルは本番基準を守り、適切なエラー処理付きのコードを生成します。新機能やサービス構築の際に利用。 +自己反省コード - 本番品質のコード生成に向けて。モデルは本番標準に従ったコードを適切なエラーハンドリング付きで生成します。新機能やサービス構築に最適。 ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下図はこの反復改善ループを示しています — 生成、評価、弱点の特定、改良を繰り返し本番基準まで高める。 +以下の図は、この反復改善ループ — 生成、評価、弱点の特定、改善を繰り返しながら本番基準に達するまでの過程です。 -自己反省サイクル +Self-Reflection Cycle -*反復的改善ループ - 生成 → 評価 → 問題識別 → 改良 → 繰り返し* +*反復的改善ループ — 生成、評価、課題検出、改善、繰り返し* -**構造化分析** - 一貫した評価のため。モデルは固定の枠組み（正確さ、プラクティス、パフォーマンス、セキュリティ、保守性）でコードをレビューします。コードレビューや品質評価に最適。 +構造化分析 - 一貫した評価のため。モデルは固定フレームワーク（正確性、プラクティス、パフォーマンス、セキュリティ、保守性）を用いてコードをレビューします。コードレビューや品質評価に適用。 ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 [GitHub Copilot](https://github.com/features/copilot)チャットで試す:** 構造化分析について質問してください： -> - 「コードレビューの種類に合わせて分析フレームワークをカスタマイズするには？」 -> - 「構造化出力をプログラムで解析し活用するベスト方法は？」 -> - 「レビュー間で一貫した重大度レベルを確保するには？」 +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試そう:** 構造化分析について質問してください： +> - 「異なる種類のコードレビューに合わせフレームワークをカスタマイズするには？」 +> - 「構造化出力をプログラム的に解析し活用するベストな方法は？」 +> - 「異なるレビューセッション間で一貫した重大度レベルをどう保つか？」 -以下の図は、一貫性あるコードレビューを重大度レベル別のカテゴリーに分類するフレームワークを示しています。 +以下の図は、この構造化フレームワークがコードレビューを一貫したカテゴリと重大度レベルに整理する様子を示します。 -構造化分析パターン +Structured Analysis Pattern -*一貫したコードレビューのための重大度レベルによるフレームワーク* +一貫した重大度レベル付きコードレビューのためのフレームワーク -**マルチターンチャット** - 文脈を要する対話に。モデルは過去のメッセージを記憶し積み重ねて応答します。対話型ヘルプや複雑なQ&Aに適用。 +マルチターンチャット - コンテキストが必要な会話用。モデルは過去のメッセージを記憶し積み重ねます。インタラクティブなヘルプや複雑なQ&Aに利用。 ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -以下の図は会話文脈がターンを重ねるごとにどう積み上がり、モデルのトークン制限にどう関係するかを示します。 +以下の図は、会話コンテキストが複数ターンにわたって蓄積し、モデルのトークン制限にどう関係するかを視覚化しています。 -コンテキストメモリ +Context Memory -*複数ターンで会話コンテキストがどのように積み重なりトークン制限に到達するか* -**ステップバイステップの推論** - 論理が明示的に必要な問題に対して。モデルは各ステップの明示的な推論を示します。数学の問題、論理パズル、または思考過程を理解したい場合に利用してください。 +複数ターンの会話でコンテキストが蓄積されトークン制限に達する仕組み + +ステップバイステップ推論 - 見える論理が必要な問題向け。モデルは各ステップの明示的な推論を示します。数学問題、論理パズル、思考プロセスを理解したい場合に適用。 ```java String prompt = """ @@ -398,13 +399,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -以下の図は、モデルが問題を明示的で番号付きの論理的ステップに分解する方法を示しています。 +以下の図は、モデルが問題を明示的で番号付きの論理的ステップに分解する様子を示します。 Step-by-Step Pattern -*問題を明示的な論理的ステップに分解する* +問題を明確な論理ステップに分解する -**制約付き出力** - 特定のフォーマット要件がある回答の場合。モデルはフォーマットと長さのルールを厳格に守ります。要約や正確な出力構造が必要な場合に利用してください。 +制約付き出力 - 特定のフォーマット要件がある応答向け。モデルはフォーマットおよび長さのルールを厳密に遵守します。要約や正確な出力構造が必要な場合に使用してください。 ```java String prompt = """ @@ -420,21 +421,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -以下の図は、制約がモデルをどのように案内して厳密にフォーマットと長さの要件に従った出力を生成するかを示しています。 +以下の図は、制約がどのようにモデルを導いてフォーマットと長さの要件を厳守した出力を生成するかを示しています。 Constrained Output Pattern -*特定のフォーマット、長さ、構造の要件を強制* +*特定のフォーマット、長さ、構造要件の強制* -## アプリケーションの起動 +## アプリケーションを実行する -**展開の確認：** +**デプロイの確認:** -ルートディレクトリに`.env`ファイルがAzureの認証情報と共に存在することを確認してください（Module 01で作成済み）。モジュールのディレクトリ（`02-prompt-engineering/`）から以下を実行します。 +ルートディレクトリにAzure認証情報が含まれる `.env` ファイルが存在することを確認してください（モジュール01で作成済み）。モジュールディレクトリ（`02-prompt-engineering/`）から次を実行します： **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENTを表示する必要があります +cat ../.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT を表示する必要があります ``` **PowerShell:** @@ -442,29 +443,29 @@ cat ../.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENTを表示する必要 Get-Content ..\.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT を表示する必要があります ``` -**アプリケーションの開始：** +**アプリケーションを起動する:** -> **注意：** すでにルートディレクトリから`./start-all.sh`を用いて全アプリケーションを起動している場合（Module 01の説明参照）、このモジュールはすでにポート8083で起動しています。以下の起動コマンドはスキップして http://localhost:8083 に直接アクセスできます。 +> **注意:** すでにルートディレクトリから `./start-all.sh` を使ってすべてのアプリケーションを起動している場合（モジュール01の説明参照）、このモジュールはすでにポート8083で動作しています。以下の起動コマンドはスキップし、直接 http://localhost:8083 にアクセスしてください。 -**オプション 1：Spring Boot Dashboardの使用（VS Codeユーザーに推奨）** +**オプション1: Spring Boot Dashboardの使用（VS Codeユーザーに推奨）** -devコンテナにはSpring Boot Dashboard拡張機能が含まれており、すべてのSpring Bootアプリケーションを視覚的に管理できます。VS Codeの左側のアクティビティバーにあるSpring Bootアイコンを探してください。 +開発コンテナにはSpring Boot Dashboard拡張機能が含まれており、すべてのSpring Bootアプリケーションを管理するビジュアルインターフェイスを提供します。VS Codeの左側のアクティビティバーにあるSpring Bootアイコンからアクセスできます。 -Spring Boot Dashboardからは以下が可能です： -- ワークスペース内のすべてのSpring Bootアプリケーションを見る -- クリックひとつでアプリケーションの起動・停止 -- リアルタイムでログを確認 -- アプリケーションの状態を監視 +Spring Boot Dashboardからは： +- ワークスペース内のすべてのSpring Bootアプリケーションを確認できます +- アプリケーションの起動/停止をワンクリックで行えます +- アプリケーションのログをリアルタイムで表示できます +- アプリケーションの状態を監視できます -「prompt-engineering」の横の再生ボタンをクリックするとこのモジュールが起動します。全モジュールを一括で起動することも可能です。 +「prompt-engineering」横の再生ボタンをクリックするだけでこのモジュールを開始するか、すべてのモジュールを一度に起動できます。 Spring Boot Dashboard -*VS CodeのSpring Boot Dashboard — 1箇所で全モジュールを開始、停止、監視可能* +*VS CodeのSpring Boot Dashboard — 一か所から全モジュールの起動、停止、監視が可能* -**オプション 2：シェルスクリプトの利用** +**オプション2: シェルスクリプトの使用** -すべてのウェブアプリケーション（モジュール 01-04）を起動： +すべてのWebアプリケーション（モジュール01～04）を起動： **Bash:** ```bash @@ -478,7 +479,7 @@ cd .. # ルートディレクトリから .\start-all.ps1 ``` -または、このモジュールだけを起動： +またはこのモジュールだけを起動： **Bash:** ```bash @@ -492,25 +493,25 @@ cd 02-prompt-engineering .\start.ps1 ``` -これらのスクリプトはどちらもルートの`.env`ファイルから環境変数を自動で読み込み、JARファイルが存在しない場合はビルドを行います。 +両方のスクリプトはルートの `.env` ファイルから環境変数を自動読み込みし、JARファイルがなければビルドします。 -> **注意：** 事前に全モジュールを手動でビルドしたい場合： +> **注意:** 起動前にすべてのモジュールを手動でビルドしたい場合： > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -ブラウザで http://localhost:8083 を開きます。 +ブラウザで http://localhost:8083 を開いてください。 -**停止方法：** +**停止するには:** **Bash:** ```bash @@ -528,69 +529,69 @@ cd ..; .\stop-all.ps1 # すべてのモジュール ## アプリケーションのスクリーンショット -こちらはPrompt Engineeringモジュールのメインインターフェイスです。8つのパターンすべてを並べて試せます。 +こちらがプロンプトエンジニアリングモジュールのメインインターフェイスで、8つのパターンを並べて試せます。 Dashboard Home -*8つのPrompt Engineeringパターンの特徴と使用例を示すメインダッシュボード* +*8つのプロンプトエンジニアリングパターンとその特長、ユースケースを示すメインダッシュボード* -## パターンの探索 +## パターンを探る -Webインターフェイスでは異なるプロンプト戦略を試せます。各パターンは異なる問題を解決します。試してみて、どのアプローチがどの場面で有効かを体感してください。 +Webインターフェイスでは異なるプロンプト戦略を試せます。各パターンは異なる課題を解決します—それぞれのアプローチがどんな場面で効果的か試してください。 -> **注意：ストリーミングと非ストリーミング** — 各パターンページには「🔴 Stream Response (Live)」と「非ストリーミング」ボタンの2つがあります。ストリーミングはServer-Sent Events（SSE）を使い、モデルが生成するトークンをリアルタイムで表示します。進捗が即座に見えるのが特徴です。非ストリーミングはレスポンス全体が完成するまで待って表示します。深い推論を必要とするプロンプト（例：High Eagerness、Self-Reflecting Code）では非ストリーミングの呼び出しが非常に長時間かかり、数分に及ぶこともあります。複雑なプロンプトを試す際はストリーミングを使うのがおすすめです。モデルが動作している様子が見え、リクエストがタイムアウトした印象を避けられます。 +> **注意: ストリーミング vs 非ストリーミング** — すべてのパターンページには2つのボタンがあります：**🔴 ストリームレスポンス（ライブ）** と 非ストリーミング オプション。ストリーミングはServer-Sent Events（SSE）を使い、モデルが生成するトークンをリアルタイムで表示するので進捗がすぐ見えます。非ストリーミングは応答全体を待ってから表示します。高い思考を要するプロンプト（例：High Eagerness、Self-Reflecting Code）では非ストリーミング呼び出しは長時間かかり、数分におよぶこともあり、進捗が見えません。**複雑なプロンプトを試す際はストリーミングを使い、モデルが動いている様子を見て、タイムアウトと誤解されるのを防いでください。** > -> **注意：ブラウザ要件** — ストリーミング機能はFetch Streams API（`response.body.getReader()`）を使用しており、完全なブラウザ（Chrome、Edge、Firefox、Safari）が必要です。VS Code内蔵のSimple Browserでは動作しません。これはSimple BrowserのwebviewがReadableStream APIに対応していないためです。Simple Browser使用時でも非ストリーミングボタンは正常に動作します。ストリーミングボタンのみ影響を受けます。ストリーミングを完全に体験したい場合は外部ブラウザで `http://localhost:8083` を開いてください。 +> **注意: ブラウザ要件** — ストリーミング機能はFetch Streams API（`response.body.getReader()`）を使用し、完全なブラウザ（Chrome、Edge、Firefox、Safari）が必要です。VS Code内蔵のSimple Browserでは機能しません。Simple BrowserはReadableStream APIをサポートしないためです。Simple Browser利用時は非ストリーミングボタンは通常通り動作し、影響があるのはストリーミングボタンだけです。フル機能を使うには外部ブラウザで http://localhost:8083 を開いてください。 ### Low vs High Eagerness -「200の15%はいくつ？」のような簡単な質問をLow Eagernessで訊くと、即座に直接的な答えが得られます。次に「高トラフィックAPIのキャッシュ戦略を設計してください」といった複雑な問題をHigh Eagernessで試し、**🔴 Stream Response (Live)** をクリックしてモデルの詳細な推論をトークン単位で見てみてください。同じモデル、同じ質問構造でも、プロンプトがどれだけ考えるかを指示しています。 +「200の15%は？」のような単純な質問はLow Eagernessで尋ねてください。即座に直球の回答が返ってきます。次に「高トラフィックAPIのキャッシュ戦略を設計してください」と複雑な質問をHigh Eagernessで試してください。**🔴 ストリームレスポンス（ライブ）** をクリックすると、モデルの詳細な推論がトークン単位で表示されます。同じモデル、同じ質問構造ですが、プロンプトが思考の深さを指示します。 -### タスク実行（ツールプレアンブル） +### タスク実行（ツールのプレアンブル） -複数ステップのワークフローでは事前計画と進捗報告が役立ちます。モデルは何をするかをアウトライン化し、各ステップを説明し、最後に結果をまとめます。 +複数ステップのワークフローは事前計画と進行状況のナレーションが有効です。モデルは実行することを示し、各ステップを説明し、結果を要約します。 -### 自己反省型コード +### 自己反省コード -「メール検証サービスを作成してください」を試してください。単にコードを生成して終了するのではなく、モデルは生成したコードを評価基準に照らして評価し、弱点を特定し、改善します。コードが本番品質に達するまで繰り返す様子が見られます。 +「メール検証サービスを作成してください」を試してみてください。単にコードを生成して止まるのではなく、モデルが生成、品質基準による評価、弱点の特定、改善を行います。コードが本番基準に達するまで繰り返し改善する過程が見えます。 ### 構造化分析 -コードレビューには一貫した評価フレームワークが必要です。モデルは（正確さ、慣習、パフォーマンス、セキュリティ）という固定カテゴリごとに、重大度レベルも含めてコードを評価します。 +コードレビューには一貫した評価フレームワークが必要です。モデルは正確性、プラクティス、パフォーマンス、セキュリティの固定カテゴリでコードを分析し、重要度を付けます。 ### マルチターンチャット -「Spring Bootとは何ですか？」と尋ねた後すぐに「例を見せてください」と続けてみてください。モデルは最初の質問を記憶し、具体的なSpring Bootの例を返します。メモリが無いと、2つ目の質問はあいまいすぎて適切に答えられません。 +「Spring Bootとは？」と尋ねてから、「例を見せて」と続けてください。モデルは最初の質問を覚えており、具体的なSpring Bootの例を返します。記憶がなければ2つ目の質問は曖昧すぎます。 -### ステップバイステップの推論 +### ステップバイステップ推論 -数学の問題を選び、Step-by-Step ReasoningとLow Eagernessの両方で試してください。Low eagernessは答えのみを高速に返しますが、過程が不透明です。Step-by-Stepではすべての計算と判断プロセスを示します。 +数学の問題を選び、Step-by-Step ReasoningとLow Eagernessの両方で試してください。Low Eagernessは答えだけをすばやく返しますが過程は見えません。Step-by-stepはすべての計算と判断を詳細に示します。 ### 制約付き出力 -特定のフォーマットや語数が必要な場合、このパターンは厳密な遵守を強制します。ちょうど100語の箇条書き要約を生成してみてください。 +特定のフォーマットや語数を必要とする場合、このパターンは厳密な遵守を強制します。100語の要約を箇条書き形式で生成してみてください。 -## 真に学んでいること +## 本当に学んでいること -**推論努力がすべてを変える** +推論努力がすべてを変える -GPT-5.2はプロンプトを通じて計算努力の度合いを制御できます。努力が少ないほど簡潔に素早い応答が得られ、探索は最小限です。努力が多いほどモデルは深い思考に時間をかけます。タスクの複雑さに合わせて努力を調整する方法を学びましょう。簡単な質問に無駄な時間をかけず、複雑な判断を急がないように。 +GPT-5.2はプロンプトを通じて計算努力を制御できます。努力が少ないと素早い応答で探求は最小限。努力が大きいと深くじっくり考えます。課題の複雑さに応じて努力を調整することを学びます—単純な質問に時間を無駄にせず、複雑な判断は急がない。 -**構造が動作を導く** +構造が振る舞いを導く -プロンプト内のXMLタグに注目してください。単なる装飾ではありません。モデルは自由形式のテキストよりも構造化された指示に従いやすいです。複数ステップの処理や複雑な論理が必要な場合、構造はモデルが現在地と次の処理を追跡する助けとなります。以下の図はよく構造化されたプロンプトの分解で、``、``、``、``、``といったタグがどのように指示を明確なセクションに整理するかを示しています。 +プロンプトにXMLタグがあるのに気づきましたか？装飾ではありません。モデルは自由文より構造化された指示により確実に従います。複数ステップや複雑な論理が必要な場合、構造がモデルの現在位置と次の処理を追跡する助けになります。下図はよく構造化されたプロンプトを分解し、``, ``, ``, ``, `` といったタグが指示を明確なセクションに整理する様子を示しています。 Prompt Structure -*明確なセクションとXML形式で構成されたよく構造化されたプロンプトの解剖* +*明確なセクションとXML風の構造で整理されたよく構造化されたプロンプト* -**自己評価による品質向上** +自己評価による品質向上 -自己反省型パターンは品質基準を明示的にします。モデルが「正しくやる」ことを期待するのではなく、「正しい」とは何かを具体的に伝えます：論理の正確さ、エラーハンドリング、パフォーマンス、セキュリティ。モデルは自らの出力を評価し改善可能です。これによりコード生成が運任せではなくプロセスに変わります。 +自己反省パターンは品質基準を明示することで機能します。モデルが「正しくやる」ことを期待するかわりに、「正しい」とは何か（正確な論理、エラーハンドリング、パフォーマンス、安全性）を正確に伝えます。モデルは自身の出力を評価し改善できるため、コード生成は宝くじでなく計画的なプロセスになります。 -**コンテキストには限りがある** +コンテキストは有限 -マルチターン会話は各リクエストにメッセージ履歴を含めることで成立しますが、モデルには最大トークン数の限界があります。会話が長くなるほど、関連するコンテキストを維持しつつ上限に達しない戦略が必要です。このモジュールではメモリの仕組みを学び、その後、いつ要約し、いつ忘れ、いつ再取得するかを学びます。 +マルチターン会話は各リクエストにメッセージ履歴を含めることで成り立ちますが、トークン制限があります。会話が長くなると上限に達するため、関連コンテキストを維持しつつ制限を回避する戦略が必要です。本モジュールではメモリの仕組みを示し、後で要約、忘却、取得のタイミングを学びます。 ## 次のステップ @@ -598,11 +599,11 @@ GPT-5.2はプロンプトを通じて計算努力の度合いを制御できま --- -**ナビゲーション:** [← 前へ: Module 01 - Introduction](../01-introduction/README.md) | [メインへ戻る](../README.md) | [次へ: Module 03 - RAG →](../03-rag/README.md) +**ナビゲーション:** [← 前へ: モジュール 01 - はじめに](../01-introduction/README.md) | [メインへ戻る](../README.md) | [次へ: モジュール 03 - RAG →](../03-rag/README.md) --- -**免責事項**: -本書類はAI翻訳サービス「[Co-op Translator](https://github.com/Azure/co-op-translator)」を使用して翻訳されました。正確性には努めておりますが、自動翻訳には誤りや不正確な部分が含まれる場合があります。原文の元の言語による文書が権威ある情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じたいかなる誤解や誤訳についても、弊社は一切責任を負いかねます。 - +**免責事項**： +本書類は AI 翻訳サービス [Co-op Translator](https://github.com/Azure/co-op-translator) を使用して翻訳されています。正確性を期していますが、自動翻訳には誤りや不正確な部分が含まれる可能性があることをご承知おきください。原文の原語版が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じたいかなる誤解や解釈違いについても、当方は責任を負いかねます。 + \ No newline at end of file diff --git a/translations/ja/03-rag/README.md b/translations/ja/03-rag/README.md index 604651c69..e449ca606 100644 --- a/translations/ja/03-rag/README.md +++ b/translations/ja/03-rag/README.md @@ -1,144 +1,143 @@ -# モジュール 03: RAG (Retrieval-Augmented Generation) +# Module 03: RAG (Retrieval-Augmented Generation) -## 目次 +## Table of Contents -- [ビデオウォークスルー](../../../03-rag) -- [学習内容](../../../03-rag) -- [前提条件](../../../03-rag) -- [RAGの理解](../../../03-rag) - - [このチュートリアルで使うRAGの方式は？](../../../03-rag) -- [仕組み](../../../03-rag) - - [ドキュメント処理](../../../03-rag) - - [埋め込みの作成](../../../03-rag) - - [セマンティックサーチ](../../../03-rag) - - [回答生成](../../../03-rag) -- [アプリケーションの実行](../../../03-rag) -- [アプリケーションの使い方](../../../03-rag) - - [ドキュメントのアップロード](../../../03-rag) - - [質問する](../../../03-rag) - - [出典の確認](../../../03-rag) - - [質問で実験](../../../03-rag) -- [重要なコンセプト](../../../03-rag) - - [チャンク化戦略](../../../03-rag) - - [類似度スコア](../../../03-rag) - - [インメモリストレージ](../../../03-rag) - - [コンテキストウィンドウ管理](../../../03-rag) -- [RAGが重要な理由](../../../03-rag) -- [次のステップ](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding RAG](#understanding-rag) + - [Which RAG Approach Does This Tutorial Use?](#which-rag-approach-does-this-tutorial-use) +- [How It Works](#how-it-works) + - [Document Processing](#document-processing) + - [Creating Embeddings](#creating-embeddings) + - [Semantic Search](#semantic-search) + - [Answer Generation](#答えの生成) +- [Run the Application](#アプリケーションを実行する) +- [Using the Application](#アプリケーションの使用方法) + - [Upload a Document](#ドキュメントをアップロードする) + - [Ask Questions](#質問をする) + - [Check Source References](#ソース参照を確認する) + - [Experiment with Questions](#質問を変えて試す) +- [Key Concepts](#主要な概念) + - [Chunking Strategy](#チャンク化戦略) + - [Similarity Scores](#類似度スコア) + - [In-Memory Storage](#インメモリストレージ) + - [Context Window Management](#コンテキストウィンドウ管理) +- [When RAG Matters](#rag-が重要な場合) +- [Next Steps](#次のステップ) -## ビデオウォークスルー +## Video Walkthrough -このモジュールの始め方を解説するライブセッションを視聴してください: +このモジュールの開始方法を説明するライブセッションをご覧ください： -LangChain4jによるRAG - ライブセッション +RAG with LangChain4j - Live Session -## 学習内容 +## What You'll Learn -前のモジュールでは、AIと対話し、効果的にプロンプトを構築する方法を学びました。しかし根本的な制約があります：言語モデルは訓練時に学んだことしか知りません。あなたの会社の方針やプロジェクトのドキュメント、訓練されていない情報について質問に答えることはできません。 +前のモジュールでは、AIとの会話方法や効果的なプロンプトの構造化方法を学びました。しかし、根本的な制約があります。言語モデルはトレーニング時に学んだことしか知りません。会社の方針、プロジェクトのドキュメント、あるいはトレーニングされていない情報に関する質問には答えられないのです。 -RAG（Retrieval-Augmented Generation）はこの問題を解決します。モデルに情報を直接教えるのではなく（これはコストが高く非現実的です）、文書を検索する能力を与えます。質問が来ると、システムは関連情報を検索し、それをプロンプトに含めます。モデルはその検索されたコンテキストを基に回答します。 +RAG（Retrieval-Augmented Generation）はこの問題を解決します。モデルに情報を教えるのではなく（これは費用がかかり非現実的です）、ドキュメントを検索する能力を与えます。質問が来ると、システムは関連する情報を見つけてプロンプトに組み込みます。モデルはその取得されたコンテキストに基づいて回答します。 -RAGをモデルに参照図書館を与えるイメージで考えてください。質問をすると、システムは： +RAGはモデルに参考図書館を与えるようなものです。質問をすると、システムは： -1. **ユーザークエリ** - 質問が入力される -2. **埋め込み** - 質問をベクトルに変換 -3. **ベクトル検索** - 類似した文書チャンクを検索 -4. **コンテキストの組み立て** - 関連チャンクをプロンプトに追加 -5. **回答** - LLMがそのコンテキストを元に回答を生成 +1. ユーザークエリ - あなたが質問する +2. 埋め込み - 質問をベクトルに変換 +3. ベクトル検索 - 類似のドキュメントチャンクを検索 +4. コンテキスト組み立て - 関連チャンクをプロンプトに追加 +5. 応答 - LLMがそのコンテキストに基づいて回答 -これにより、モデルの応答が訓練知識に依存したり、作り話をするのではなく、実際のデータに基づいたものになります。 +これにより、モデルの回答がトレーニング知識に依存したり、架空の回答をするのではなく、実際のデータに根ざしたものになります。 -## 前提条件 +## Prerequisites -- [モジュール 00 - クイックスタート](../00-quick-start/README.md) を完了していること（このモジュールで後述するEasy RAGの例のため） -- [モジュール 01 - イントロダクション](../01-introduction/README.md) を完了していること（Azure OpenAIのリソースがデプロイ済み、`text-embedding-3-small` 埋め込みモデルも含む） -- ルートディレクトリにAzure認証情報を含む `.env` ファイルがあること（モジュール 01 の `azd up` コマンドで作成） +- [Module 01 - Introduction](../01-introduction/README.md) の完了（Azure OpenAI リソース展開済み、`text-embedding-3-small` 埋め込みモデル含む） +- ルートディレクトリに Azure 資格情報が記載された `.env` ファイル（Module 01 の `azd up` コマンドで作成） -> **注意:** モジュール 01 をまだ完了していない場合は、そこでの展開手順を先に行ってください。`azd up` コマンドはこのモジュールで使うGPTチャットモデルと埋め込みモデルの両方を展開します。 +> **Note:** Module 01 を完了していなければ、まずそこで展開手順を実行してください。`azd up` コマンドは GPT チャットモデルとこのモジュールで使う埋め込みモデルの両方を展開します。 -## RAGの理解 +## Understanding RAG -下図はコアコンセプトを示しています：モデルの訓練データだけに頼る代わりに、RAGは回答を生成する前に参照するためのあなたのドキュメントのライブラリをモデルに与えます。 +以下の図はコアコンセプトを示しています：モデルのトレーニングデータのみに頼るのではなく、RAGは回答を生成する前に参照できるドキュメントのライブラリをモデルに与えます。 -RAGとは +What is RAG -*この図は標準的なLLM（訓練データから推測する）と、RAG強化型LLM（まずあなたのドキュメントを参照する）との違いを示しています。* +*この図は標準的なLLM（トレーニングデータから推測）と、RAG強化LLM（まずドキュメントを参照）の違いを示しています。* -全体の流れはこうなります。ユーザーの質問は四つの段階を経ます — 埋め込み、ベクトル検索、コンテキストの組み立て、回答生成 — 各段階が前の段階の出力を踏まえています： +ユーザーの質問が次の4段階で処理される様子が接続されます — 埋め込み、ベクトル検索、コンテキスト組み立て、回答生成 — 各段階が前の段階の上に成り立っています： -RAGアーキテクチャ +RAG Architecture -*この図はエンドツーエンドのRAGパイプラインを示しており、ユーザークエリが埋め込み、ベクトル検索、コンテキスト組み立て、回答生成の順に処理されます。* +*この図はユーザークエリが埋め込み、ベクトル検索、コンテキスト組み立て、回答生成を経るエンドツーエンドのRAGパイプラインを示しています。* -このモジュールでは、各段階を詳細に解説し、動かして変更できるコードを提供しています。 +このモジュールの残りの部分で各段階を詳細にコードと共に説明します。 -### このチュートリアルで使うRAGの方式は？ +### Which RAG Approach Does This Tutorial Use? -LangChain4jは3つのRAG実装方法を提供しており、それぞれ抽象度が異なります。下図はそれらを並べて比較しています： +LangChain4jは3つのRAG実装方法を提供しており、それぞれ抽象化のレベルが異なります。以下の図はそれらを比較しています： -LangChain4jの3つのRAG方式 +Three RAG Approaches in LangChain4j -*この図はLangChain4jの3つのRAGアプローチ（Easy, Native, Advanced）を比較し、それぞれの主要コンポーネントと利用タイミングを示しています。* +*この図はLangChain4jの3つのRAGアプローチ（Easy、Native、Advanced）を比較し、主要なコンポーネントと利用シーンを示しています。* -| 方式 | 概要 | トレードオフ | +| アプローチ | 内容 | トレードオフ | |---|---|---| -| **Easy RAG** | `AiServices` と `ContentRetriever` により全てが自動接続されます。インターフェースに注釈を付けてリトリーバーをセットすれば、LangChain4jが背後で埋め込み、検索、プロンプトの組み立てを行います。 | コードは最小限ですが、内部処理は見えません。 | -| **Native RAG** | 自分で埋め込みモデルを呼び出し、ストアを検索して、プロンプトを構築し、回答を生成します — 明示的に一段階ずつ操作します。 | コードは多めですが、各段階を見て変更可能です。 | -| **Advanced RAG** | `RetrievalAugmentor` フレームワークを使い、プラガブルなクエリ変換器、ルーター、再ランキング、コンテンツ注入を組み込んでプロダクションレベルのパイプラインを構築します。 | 柔軟性最大ですが、かなりの複雑さを伴います。 | +| **Easy RAG** | `AiServices` と `ContentRetriever` を通じてすべてを自動的に接続。インターフェースに注釈を付けてリトリーバを追加すると、埋め込み、検索、プロンプト組み立てをLangChain4jが裏で処理。 | コードは最小限だが、各段階の処理内容が見えない。 | +| **Native RAG** | 埋め込みモデルを呼び出し、ストアを検索し、プロンプトを構築し、回答を生成する各ステップを明示的に記述。 | コード量は増えるが、各段階が見える＆変更可能。 | +| **Advanced RAG** | `RetrievalAugmentor` フレームワークを使い、クエリ変換器、ルーター、再ランキング、コンテンツ注入をプラグインで構成する本格的なパイプライン。 | 最大の柔軟性。ただし複雑度が大幅に増す。 | -**このチュートリアルではNative方式を使います。** RAGパイプラインの各段階 — クエリの埋め込み、ベクトルストア検索、コンテキスト組み立て、回答生成 — は [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) に明示的に書かれています。学習教材として、コードを最小化するよりも各段階を見て理解することが重要なためです。仕組みを理解したら、手軽なプロトタイプ用にEasy RAGに移行したり、プロダクション用にAdvanced RAGを使うこともできます。 +**本チュートリアルは Native アプローチを使用します。** RAGパイプラインの各ステップ— クエリの埋め込み、ベクターストアの検索、コンテキストの組み立て、回答の生成 — は[`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java)に明示的に書かれています。これは学習リソースとして、コードの最適化よりもすべての段階を見て理解することが重要だからです。仕組みがわかれば、簡単な試作には Easy RAG、実運用には Advanced RAG に段階的に移行可能です。 -> **💡 Easy RAGは既に見たことがありますか？** [クイックスタート モジュール](../00-quick-start/README.md) には、Easy RAG方式を使ったドキュメントQ&Aの例（[`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)）があります。LangChain4jが埋め込み、検索、プロンプトの組み立てを自動的に行います。このモジュールでは、そのパイプラインを分解して各段階を自分で見て制御できるようにします。 +> **💡 Easy RAGが気になる方へ:** LangChain4jは `AiServices` と `ContentRetriever` が埋め込み、検索、プロンプト組み立てを自動的に扱う *Easy RAG* も提供しています。このモジュールは明示的なルートを取り、各段階を分解して制御できるようにしています。 -下の図はクイックスタートにあるEasy RAGパイプラインを示しています。`AiServices` と `EmbeddingStoreContentRetriever` は全ての複雑さを隠しており、ドキュメントをロードしてリトリーバーを付ければ回答が得られます。このモジュールのNative方式は、その隠れた各ステップを開きます： +以下の図は Easy RAG パイプラインを示しています。`AiServices` と `EmbeddingStoreContentRetriever` が複雑さを隠し、ドキュメントを読み込みリトリーバを接続して回答を得るだけです。モジュールで使う Native アプローチはそれらを分解します： -Easy RAGパイプライン - LangChain4j +Easy RAG Pipeline - LangChain4j -*この図は `SimpleReaderDemo.java` のEasy RAGパイプラインです。Native方式（本モジュール）と比較してください：Easy RAGは `AiServices` と `ContentRetriever` の背後に埋め込み、検索、プロンプト組み立てを隠していますが、Native方式は各段階（埋め込み、検索、コンテキスト組み立て、生成）を自分で呼び出し、完全に可視化・制御できます。* +*この図は Easy RAG のパイプラインを示しています。モジュールで使う Native アプローチは埋め込み、検索、コンテキスト組み立てを自分で呼び出せるように分解し、完全に見える化と制御を可能にします。* -## 仕組み +## How It Works -このモジュールのRAGパイプラインは、ユーザーが質問をするたびに実行される4つの段階に分かれます。まず、アップロードされたドキュメントは**解析・チャンク化**され、扱いやすいサイズに分割されます。そのチャンクは**ベクトル埋め込み**に変換され、数値的に比較できるよう保存されます。クエリが来ると、システムは**セマンティックサーチ**を行い最も関連するチャンクを見つけ、最後にそれらをコンテキストとしてLLMに渡して**回答を生成**します。以下に各段階のコードと図解で説明します。まずは最初のステップから見てみましょう。 +このモジュールのRAGパイプラインは、ユーザーが質問するたびに順番に実行される4つの段階に分かれています。まずアップロードされた文書が解析・分割されて扱いやすい断片になります。これらの断片はベクトル埋め込みに変換され保存され、数学的に比較可能になります。クエリが来ると、意味検索で最も関連性のある断片を探し、最後にそれらをコンテキストとしてLLMに渡し回答生成します。以下に実際のコードと図で各段階を解説します。まず最初の段階から見ていきましょう。 -### ドキュメント処理 +### Document Processing [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -ドキュメントをアップロードすると、システムはそれを解析します（PDFやテキスト）。ファイル名などのメタデータを付与し、モデルのコンテキストウィンドウに収まる小さなチャンクに分割します。チャンクは少し重複しており、境界でコンテキストを失わないようにしています。 +ドキュメントをアップロードすると、システムはそれを（PDFまたはプレーンテキストとして）解析し、ファイル名などのメタデータを付け、モデルのコンテキストウィンドウに収まるサイズのチャンク（断片）に分割します。チャンクは少し重なりがあって、境界でのコンテキスト損失を防ぎます。 ```java -// アップロードされたファイルを解析し、LangChain4jドキュメントにラップする +// アップロードされたファイルを解析し、LangChain4jのDocumentにラップします Document document = Document.from(content, metadata); -// 30トークンの重なりを持つ300トークンのチャンクに分割する +// 300トークンごとに分割し、30トークンの重複を持たせます DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` + +以下の図は視覚的にその様子を示しています。隣接するチャンクは同じトークンをいくつか共有しており、30トークンの重複によって重要なコンテキストが失われません： -下図は視覚的に表しています。チャンク同士は30トークン分重複しているため、重要なコンテキストが欠落しません： +Document Chunking -ドキュメントのチャンク化 +*この図は300トークンチャンクを30トークン重複で分割し、チャンク境界でコンテキストを維持する様子を示しています。* -*この図はドキュメントを300トークンずつ、30トークンの重複をもって分割する様子です。チャンク境界のコンテキストが維持されます。* +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) を開き、次の質問をどうぞ： +> - 「LangChain4j はどのように文書をチャンク化し、なぜ重複が重要か？」 +> - 「異なる文書タイプに最適なチャンクサイズは何でその理由は？」 +> - 「多言語または特殊書式の文書はどう扱う？」 -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) を開いて質問してください： -> - 「LangChain4jはどうやってドキュメントをチャンクに分けるのか？ なぜ重複が重要なのか？」 -> - 「ドキュメントの種類ごとに最適なチャンクサイズは？ なぜそうか？」 -> - 「多言語ドキュメントや特殊書式の処理はどうする？」 - -### 埋め込みの作成 +### Creating Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -各チャンクは意味を数値化した埋め込みに変換されます。埋め込みモデルはチャットモデルのように「賢い」わけではありません。指示に従ったり推論したり質問に答えることはできません。代わりに、テキストを数学空間にマッピングし、似た意味が近い位置に来るよう変換します — 「car」と「automobile」が近く、「refund policy」と「return my money」も近くなります。チャットモデルが話せる人なら、埋め込みモデルは超優秀なファイリングシステムと考えられます。 +各チャンクは「埋め込み」と呼ばれる数値表現に変換されます — これは「意味を数字に変換する装置」のようなものです。埋め込みモデルはチャットモデルのように「賢い」わけではなく、指示に従ったり推論したり質問に答えたりはできません。できるのはテキストを数学空間にマッピングし、意味が似ているものを近くに置くことだけです — 「car（車）」は「automobile（自動車）」の近くに、「refund policy（返金規定）」は「return my money（返金）」の近くに配置されるイメージです。チャットモデルは会話できる人のようなもの、埋め込みモデルは超優秀なファイリングシステムです。 -下図はこの概念を示しています — テキストを入力し、数値ベクトルが出力され、似た意味は近いベクトル位置に配置されます： +以下の図はこの概念を視覚化しています — テキストが入って数値ベクトルが出力され、意味が似ているものはベクトル空間で近くに位置します： -埋め込みモデルの概念 +Embedding Model Concept -*この図はテキストを数値ベクトルに変換し、「car」と「automobile」のような類似する意味をベクトル空間で近接させる埋め込みモデルの仕組みを示しています。* +*この図は埋め込みモデルがテキストを数値ベクトルに変換し、「car」と「automobile」のような類似した意味をベクトル空間で近接させることを示しています。* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` + +以下のクラス図はRAGパイプラインの2つの別々の流れと、それを実装するLangChain4jのクラスを示しています。取り込みフロー（アップロード時に一度実行）は文書を分割しチャンクを埋め込み、`.addAll()` 経由で保存します。クエリフロー（ユーザー毎の質問時に実行）は質問を埋め込み、`.search()` でストアを検索し該当コンテキストをチャットモデルに渡します。両フローは共通の `EmbeddingStore` インターフェースでつながっています： -下図はRAGパイプラインの2つのフローと、それを実装するLangChain4jクラスのクラス図です。**取り込みフロー**（アップロード時に1回実行）はドキュメントを分割しチャンクを埋め込み、`.addAll()`で保存します。**クエリフロー**（毎回質問時に実行）は質問を埋め込み、`.search()`でストアを検索し、マッチしたコンテキストをチャットモデルに渡します。両フローは共通の `EmbeddingStore` インターフェースで接続します： - -LangChain4j RAGクラス +LangChain4j RAG Classes -*この図はRAGパイプラインの取り込みフローとクエリフローが、共有のEmbeddingStoreを介して接続される様子を示しています。* +*この図はRAGパイプラインにおける二つのフロー（取り込み＆クエリ）とそれらを共有のEmbeddingStoreを通じて接続している様子を示しています。* -埋め込みが保存されると、類似コンテンツは自然にベクトル空間でクラスタ化されます。下図は関連トピックのドキュメントが近くに集まり、セマンティックサーチが可能になる様子を3Dで示しています： +埋め込みが保存されると、類似コンテンツは自動的にベクトル空間で近接してクラスタを形成します。以下の視覚化は関連トピックの文書が近接ポイントとして配置され、意味検索を可能にする様子を示しています： -ベクトル埋め込み空間 +Vector Embeddings Space -*この図は「技術文書」「ビジネスルール」「FAQ」など、関連文書が3Dベクトル空間で異なるクラスターを形成する様子を示しています。* +*この視覚化はテクニカルドキュメント、ビジネスルール、FAQなどの関連文書が3Dベクトル空間で別々のクラスタを形成する様子を示しています。* -検索時は4つのステップを順に実行します：文書を一度埋め込み、検索時にクエリを埋め込み、コサイン類似度で全ベクトルと比較し、上位K件のチャンクを返す。下図は各ステップと対応するLangChain4jクラスを示しています： +検索時は4ステップで進みます：文書に一度埋め込み、検索毎にクエリを埋め込み、コサイン類似度で全ベクトルと比較し、上位K件を返す。以下の図は各ステップと関わるLangChain4jクラスを示しています： -埋め込み検索のステップ +Embedding Search Steps -*この図は、文書埋め込み、クエリ埋め込み、コサイン類似度による比較、上位K件の返却という4ステップの埋め込み検索プロセスを示しています。* +*この図は文書の埋め込み、クエリの埋め込み、コサイン類似度によるベクトル比較、トップK件の返却という4ステップの埋め込み検索プロセスを示しています。* -### セマンティックサーチ +### Semantic Search [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -質問が入力されると、その質問も埋め込みに変換されます。システムは質問の埋め込みを全文書チャンクの埋め込みと比較し、最も意味的に近いチャンクを見つけます。単なるキーワードの一致ではなく、本当の意味の類似性を考慮します。 +質問をすると、その質問も埋め込みに変換されます。システムは質問の埋め込みとすべての文書チャンクの埋め込みを比較します。単なるキーワードの一致ではなく、真の意味的類似を持つチャンクを特定します。 ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` + +以下の図は意味検索と従来のキーワード検索の違いを比較しています。「vehicle」というキーワード検索は「cars and trucks」についてのチャンクを見逃してしまいますが、意味検索は同義であることを理解し高スコアで返します： -下図はセマンティックサーチと従来のキーワード検索を比較しています。キーワード検索で「vehicle」を検索すると「cars and trucks」についてのチャンクは見つかりませんが、セマンティックサーチは意味が同じと理解し、高スコアで返します： +Semantic Search -セマンティックサーチ +*この図はキーワード検索と意味検索の比較を示しており、意味検索が正確なキーワードが異なっていても意味的に関連するコンテンツを返す様子を示しています。* -*この図はキーワード検索とセマンティックサーチを比較し、セマンティックサーチがキーワードが異なっていても概念的に関連するコンテンツを取得する様子を示しています。* -内部的には、類似度はコサイン類似度で測定されます。これは本質的に「これら二つの矢印は同じ方向を指しているか？」という問いです。二つのチャンクはまったく異なる言葉を使っていても、意味が同じであればベクトルは同じ方向を指し、スコアは1.0に近づきます： +内部的には類似度はコサイン類似度で測定されます — 「これら2つの矢印は同じ方向を向いているか？」を問うようなものです。全く違う言葉でも意味が同じなら、ベクトルは同じ方向を示しスコアは1.0に近くなります： Cosine Similarity +*この図は、埋め込みベクトル間の角度としてのコサイン類似度を示しています — より整列したベクトルはスコアが1.0に近くなり、より高い意味的類似度を示します。* -*この図は埋め込みベクトル間の角度としてコサイン類似度を示しています。より整列したベクトルは1.0に近いスコアとなり、より高い意味的類似性を示します。* - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す：** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java)を開き、以下を尋ねてみてください： -> - 「埋め込みによる類似検索はどのように機能し、スコアは何によって決まるのか？」 -> - 「どのような類似度の閾値を使うべきで、結果にどう影響するのか？」 -> - 「関連するドキュメントが見つからなかった場合はどう処理するのか？」 +> **🤖 [GitHub Copilot](https://github.com/features/copilot) チャットで試す:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) を開いて次のように尋ねてください: +> - 「埋め込みを使った類似検索はどのように機能し、スコアは何によって決まるのか？」 +> - 「どの類似度閾値を使うべきで、それが結果にどう影響するのか？」 +> - 「関連するドキュメントが見つからなかった場合はどう対応すべきか？」 -### 回答生成 +### 答えの生成 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -最も関連性の高いチャンクは、明示的な指示、取得したコンテキスト、ユーザーの質問を含む構造化されたプロンプトに組み込まれます。モデルはこれらの特定のチャンクを読み、その情報に基づいて回答します — モデルは目の前の情報のみを使用できるため、幻覚（hallucination）を防止します。 +最も関連性の高いチャンクが、明示的な指示や取得したコンテキスト、ユーザーの質問を含む構造化されたプロンプトに組み立てられます。モデルはその特定のチャンクのみを読み、それに基づいて回答を生成します — 使用できるのは目の前の情報のみであるため、幻覚を防げます。 ```java String context = matches.stream() @@ -237,51 +236,51 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -下図はこの組み立ての動作例を示しています — 検索ステップでトップスコアを得たチャンクがプロンプトテンプレートに注入され、`OpenAiOfficialChatModel`が根拠のある回答を生成します： +下の図はこの組み立ての動作を示しています — 検索ステップで上位のスコアを得たチャンクがプロンプトテンプレートに注入され、`OpenAiOfficialChatModel` が根拠のある回答を生成します: Context Assembly -*この図はトップスコアのチャンクが構造化されたプロンプトに組み込まれ、モデルがデータに基づいた回答を生成する様子を示しています。* +*この図は、上位スコアのチャンクが構造化されたプロンプトに組み込まれ、モデルがあなたのデータから根拠のある回答を生成できる様子を示しています。* -## アプリケーションの実行 +## アプリケーションを実行する -**デプロイを確認する：** +**デプロイを確認する:** -ルートディレクトリにAzure認証情報を含む`.env`ファイルが存在することを確認してください（モジュール01で作成済み）。モジュールディレクトリ(`03-rag/`)から以下を実行します： +ルートディレクトリに Azure の資格情報を含む `.env` ファイルが存在することを確認してください（モジュール01で作成）。モジュールディレクトリ（`03-rag/`）からこれを実行します: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENTを表示する必要があります +cat ../.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT を表示する必要があります ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENTを表示する必要があります +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT を表示する必要があります ``` -**アプリケーションを起動する：** +**アプリケーションを起動する:** -> **注意：** もしルートディレクトリから`./start-all.sh`で全アプリケーションを起動済みの場合（モジュール01で説明）、本モジュールは既にポート8081で実行中です。以下の起動コマンドはスキップして http://localhost:8081 へ直接アクセスできます。 +> **注意:** ルートディレクトリから `./start-all.sh` を使ってすでにすべてのアプリケーションを起動している場合（モジュール01で説明）、このモジュールはすでにポート8081で動作しています。以下の起動コマンドはスキップして http://localhost:8081 に直接アクセスできます。 -**オプション1：Spring Boot Dashboardを使用する（VS Codeユーザーに推奨）** +**オプション1: Spring Boot ダッシュボードを使用する（VS Codeユーザーに推奨）** -DevコンテナにはSpring Boot Dashboard拡張機能が含まれており、すべてのSpring Bootアプリケーションを視覚的に管理できます。VS Codeの左側のアクティビティバーでSpring Bootアイコンを探してください。 +開発コンテナには Spring Boot ダッシュボード拡張機能が含まれており、すべての Spring Boot アプリを視覚的に管理できます。VS Code 左側のアクティビティバーで Spring Boot アイコンを探してください。 -Spring Boot Dashboardからは以下が可能です： -- ワークスペース内のすべてのSpring Bootアプリケーションを確認 -- クリック一つでアプリケーションの起動・停止 -- リアルタイムでアプリケーションログを閲覧 -- アプリケーションの状態監視 +Spring Boot ダッシュボードからは: +- ワークスペース内のすべてのSpring Bootアプリを確認可能 +- ワンクリックでアプリの起動/停止 +- リアルタイムでアプリケーションログを表示 +- アプリの状態を監視可能 -「rag」の横にある再生ボタンをクリックしてこのモジュールを起動するか、すべてのモジュールを一括で起動できます。 +「rag」の横の再生ボタンをクリックすればこのモジュールを起動、またはすべてのモジュールをまとめて起動できます。 Spring Boot Dashboard -*このスクリーンショットはVS CodeのSpring Boot Dashboardで、ここからアプリケーションの起動・停止や監視が行えます。* +*このスクリーンショットは、VS Code の Spring Boot ダッシュボードの様子で、アプリの起動、停止、監視を視覚的に行えます。* -**オプション2：シェルスクリプトを使用する** +**オプション2: シェルスクリプトを使用する** -すべてのWebアプリ（モジュール01〜04）を起動： +すべてのウェブアプリケーション（モジュール01-04）を起動: **Bash:** ```bash @@ -295,7 +294,7 @@ cd .. # ルートディレクトリから .\start-all.ps1 ``` -または、このモジュールだけ起動： +またはこのモジュールのみを起動: **Bash:** ```bash @@ -309,25 +308,25 @@ cd 03-rag .\start.ps1 ``` -両方のスクリプトはルートの`.env`ファイルから環境変数を自動で読み込み、必要に応じてJARをビルドします。 +どちらのスクリプトもルートの `.env` ファイルから環境変数を自動的に読み込み、JARファイルがなければビルドします。 -> **注意：** もし事前に全モジュールを手動ビルドしたい場合： +> **注意:** 起動前に手動で全モジュールをビルドしたい場合: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -ブラウザで http://localhost:8081 を開きます。 +ブラウザで http://localhost:8081 を開いてください。 -**停止するには：** +**停止するには:** **Bash:** ```bash @@ -343,95 +342,95 @@ cd .. && ./stop-all.sh # すべてのモジュール cd ..; .\stop-all.ps1 # すべてのモジュール ``` -## アプリケーションの利用方法 +## アプリケーションの使用方法 -このアプリケーションはドキュメントアップロードと質問用のWebインターフェイスを提供します。 +このアプリはドキュメントのアップロードと質問用のウェブインターフェースを提供します。 RAG Application Interface -*このスクリーンショットは、ドキュメントをアップロードして質問できるRAGアプリケーションのインターフェイスです。* +*このスクリーンショットは、ドキュメントをアップロードして質問を行うRAGアプリケーションのインターフェースを示しています。* -### ドキュメントのアップロード +### ドキュメントをアップロードする -まずドキュメントをアップロードしてください — テスト用にはTXTファイルが最適です。このディレクトリにはLangChain4jの機能、RAGの実装方法、ベストプラクティスが含まれた`sample-document.txt`が用意されており、システムのテストに最適です。 +まずドキュメントをアップロードしてください — テストにはTXTファイルが最適です。このディレクトリには LangChain4j の機能、RAG 実装、ベストプラクティスに関する情報を含む `sample-document.txt` が用意されており、システムのテストに最適です。 -アップロードするとシステムは自動でドキュメントを処理し、チャンクに分割して各チャンクの埋め込みを作成します。 +システムはアップロードされたドキュメントを処理し、チャンクに分割して各チャンクの埋め込みを作成します。これはアップロード時に自動的に行われます。 -### 質問する +### 質問をする -ドキュメント内容に関して具体的な質問をしてみてください。文書中にはっきり記載されている事実に関する質問がおすすめです。システムは関連チャンクを検索し、プロンプトに含めて回答を生成します。 +次に、ドキュメントの内容に関して具体的な質問をしてください。ドキュメントに明確に記載された事実を尋ねてみましょう。システムは関連性の高いチャンクを検索し、それをプロンプトに含めて回答を生成します。 -### ソース参照の確認 +### ソース参照を確認する -回答には類似度スコア付きのソース参照が含まれます。スコアは0から1までで、質問に対して各チャンクがどれほど関連しているかを示します。スコアが高いほど関連性が高いことを意味し、回答の元になる情報を検証するのに役立ちます。 +各回答には類似度スコア付きのソース参照が含まれていることに注意してください。これらのスコア（0から1）は、どれだけそのチャンクが質問に関連しているかを示します。高いスコアはよりマッチしていることを意味し、回答の根拠をソースで確認できます。 RAG Query Results -*このスクリーンショットは生成回答、ソース参照、各取得チャンクの関連度スコアを含むクエリ結果を示しています。* +*このスクリーンショットは、生成された回答、ソースの参照、および取得された各チャンクの関連度スコアを示したクエリ結果です。* -### 質問の実験 +### 質問を変えて試す -様々なタイプの質問を試せます： -- 具体的な事実：「主なテーマは何ですか？」 -- 比較：「XとYの違いは何ですか？」 -- 要約：「Zについての重要ポイントを要約してください」 +様々なタイプの質問を試してみてください: +- 具体的な事実: 「主なトピックは何ですか？」 +- 比較: 「XとYの違いは何ですか？」 +- 要約: 「Zについての重要ポイントをまとめてください」 -質問内容によって関連度スコアがどのように変わるかを観察してください。 +質問がドキュメント内容にどれだけマッチしているかで関連度スコアがどう変化するか観察してください。 -## 重要な概念 +## 主要な概念 -### チャンク分割戦略 +### チャンク化戦略 -ドキュメントは300トークンごとに分割され、30トークンのオーバーラップがあります。このバランスでチャンクは十分な文脈を持ちつつ小さく保たれ、複数のチャンクをプロンプトに含めやすくなっています。 +ドキュメントは300トークンのチャンクに分割され、30トークンの重なりがあります。このバランスにより、それぞれのチャンクが意味のある文脈を十分に持ちながら、複数チャンクをプロンプトに含めやすいサイズに保たれています。 ### 類似度スコア -取得された各チャンクには0から1の間の類似度スコアが付き、質問との類似度を示します。下図はスコアのレンジとシステムがどのようにそれをフィルタリングに使うかを示しています： +取得された各チャンクには、質問にどれだけ密接にマッチしているかを示す0から1の類似度スコアが付与されます。下の図はスコアの範囲とシステムの結果フィルタリングの方法を可視化しています: Similarity Scores -*この図は0から1のスコア範囲と、0.5の最小閾値で無関係なチャンクが除外されることを示しています。* +*この図は、スコアが0から1の範囲で、0.5の最低閾値を設定して関連の薄いチャンクを除外している様子を示しています。* -スコアの範囲は以下の通りです： -- 0.7〜1.0：非常に関連性が高く、完全に一致 -- 0.5〜0.7：関連性があり良好な文脈 -- 0.5未満：除外、類似度が低すぎる +スコアの範囲は次の通り: +- 0.7〜1.0: 非常に関連性が高く、正確にマッチ +- 0.5〜0.7: 関連性があり良い文脈 +- 0.5未満: 除外される、類似性が低すぎる -システムは品質を保証するため、最小閾値以上のチャンクのみを取得します。 +システムは品質を保証するため、最低閾値以上のチャンクのみを取得します。 -埋め込みは意味がクラスタリングできるときに効果的ですが、盲点もあります。下図はよくある失敗例を示しています — 大きすぎるチャンクは曖昧なベクトルを生成し、小さすぎるチャンクは文脈が不足し、曖昧な用語は複数のクラスタを指し、IDや部品番号などの完全一致検索は埋め込みでは機能しません： +埋め込みは意味のクラスタリングが明確な場合によく機能しますが、盲点もあります。下の図はよくある失敗モードを示しています — チャンクが大きすぎるとベクトルが不鮮明に、チャンクが小さすぎると文脈が不足、曖昧な用語は複数クラスタを指し、IDや部品番号の正確一致は埋め込みでは機能しません: Embedding Failure Modes -*この図は一般的な埋め込みの失敗モードを示しています：チャンクが大きすぎる、小さすぎる、複数クラスタを指す曖昧な用語、IDのような完全一致検索。* +*この図は一般的な埋め込み失敗モードを示しています: 大きすぎるチャンク、小さすぎるチャンク、複数クラスタを指す曖昧な用語、IDのような正確一致検索。* -### メモリ内ストレージ +### インメモリストレージ -このモジュールは簡潔さのためにメモリ内ストレージを使用しています。アプリケーションを再起動するとアップロードしたドキュメントは失われます。実際のシステムではQdrantやAzure AI Searchなどの永続的なベクターデータベースを使用します。 +このモジュールは簡単さのためインメモリストレージを使用しています。アプリを再起動するとアップロードしたドキュメントは消えてしまいます。商用システムでは Qdrant や Azure AI Search のような永続的なベクターデータベースを使用します。 ### コンテキストウィンドウ管理 -各モデルには最大のコンテキストウィンドウがあり、巨大なドキュメントのすべてのチャンクを含めることはできません。システムは関連度の高い上位Nチャンク（デフォルトは5）を取得し、制限内で十分な文脈を提供したうえで正確な回答を可能にします。 +各モデルには最大コンテキストウィンドウがあります。大きなドキュメントのすべてのチャンクを含めることはできません。システムは最も関連性の高い上位Nチャンク（デフォルト5）だけを取得して制限内に収めつつ、正確な回答に十分な文脈を提供します。 -## RAGが重要となる場合 +## RAG が重要な場合 -RAGはいつも最適なアプローチではありません。下図の意思決定ガイドは、RAGが価値を提供する場合と、直接プロンプトに内容を含めるかモデルの内蔵知識に頼る方が十分な場合の判断に役立ちます： +RAGは常に最適なアプローチではありません。下の意思決定ガイドは、RAGが価値を追加する場合と、コンテンツをプロンプトに直接含めたりモデルの内蔵知識に頼ったりする簡単な方法で十分な場合の判断に役立ちます: When to Use RAG -*この図はRAGの価値がある場合と、より単純なアプローチが十分な場合の判断ガイドを示しています。* +*この図は、RAGが価値を持つ場合と、より簡単な方法で十分な場合の意思決定ガイドを示しています。* ## 次のステップ -**次のモジュール：** [04-tools - ツールを使ったAIエージェント](../04-tools/README.md) +**次のモジュール:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**ナビゲーション：** [← 前：モジュール02 - プロンプトエンジニアリング](../02-prompt-engineering/README.md) | [メインへ戻る](../README.md) | [次：モジュール04 - ツール →](../04-tools/README.md) +**ナビゲーション:** [← 前: モジュール02 - プロンプトエンジニアリング](../02-prompt-engineering/README.md) | [メインに戻る](../README.md) | [次: モジュール04 - ツール →](../04-tools/README.md) --- **免責事項**： -本ドキュメントはAI翻訳サービス「[Co-op Translator](https://github.com/Azure/co-op-translator)」を使用して翻訳されました。正確性を期していますが、自動翻訳には誤りや不正確な部分が含まれる場合があります。原文が権威ある情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の使用により生じた誤解や解釈の違いについて、一切の責任を負いかねます。 - +本書類は AI 翻訳サービス [Co-op Translator](https://github.com/Azure/co-op-translator) を使用して翻訳されています。正確性を期していますが、自動翻訳には誤りや不正確な部分が含まれる可能性があることをご承知おきください。原文の原語版が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じたいかなる誤解や解釈違いについても、当方は責任を負いかねます。 + \ No newline at end of file diff --git a/translations/ja/04-tools/README.md b/translations/ja/04-tools/README.md index 96ea2975e..147cca6df 100644 --- a/translations/ja/04-tools/README.md +++ b/translations/ja/04-tools/README.md @@ -1,76 +1,76 @@ -# モジュール 04: ツールを使った AI エージェント +# Module 04: ツールを使用したAIエージェント ## 目次 -- [ビデオウォークスルー](../../../04-tools) -- [学習内容](../../../04-tools) -- [前提条件](../../../04-tools) -- [ツールを使った AI エージェントの理解](../../../04-tools) -- [ツール呼び出しの仕組み](../../../04-tools) - - [ツール定義](../../../04-tools) - - [意思決定](../../../04-tools) - - [実行](../../../04-tools) - - [応答生成](../../../04-tools) - - [アーキテクチャ: Spring Boot の自動配線](../../../04-tools) -- [ツールチェイニング](../../../04-tools) -- [アプリケーションの実行](../../../04-tools) -- [アプリケーションの使用方法](../../../04-tools) - - [簡単なツールの使用を試す](../../../04-tools) - - [ツールチェイニングをテストする](../../../04-tools) - - [会話の流れを見る](../../../04-tools) - - [様々なリクエストを試す](../../../04-tools) -- [重要な概念](../../../04-tools) - - [ReAct パターン（推論と行動）](../../../04-tools) - - [ツールの説明が重要](../../../04-tools) - - [セッション管理](../../../04-tools) - - [エラー処理](../../../04-tools) -- [利用可能なツール](../../../04-tools) -- [ツールベースエージェントを使うタイミング](../../../04-tools) -- [ツールと RAG の比較](../../../04-tools) -- [次のステップ](../../../04-tools) +- [ビデオウォークスルー](#ビデオウォークスルー) +- [学習内容](#学習内容) +- [前提条件](#前提条件) +- [ツールを使用したAIエージェントの理解](#ツールを使用したaiエージェントの理解) +- [ツール呼び出しの仕組み](#ツール呼び出しの仕組み) + - [ツール定義](#ツール定義) + - [意思決定](#意思決定) + - [実行](#実行) + - [レスポンス生成](#レスポンス生成) + - [アーキテクチャ：Spring Bootの自動ワイヤリング](#アーキテクチャ：spring-bootの自動ワイヤリング) +- [ツールチェイニング](#ツールチェイニング) +- [アプリケーションを実行する](#アプリケーションを実行する) +- [アプリケーションの使用方法](#アプリケーションの使用) + - [シンプルなツール使用を試す](#シンプルなツール使用を試す) + - [ツールチェイニングをテストする](#ツールチェーンを試す) + - [会話の流れを見る](#会話フローを見る) + - [さまざまなリクエストを試す](#さまざまなリクエストを試す) +- [重要な概念](#重要なコンセプト) + - [ReActパターン（Reasoning and Acting）](#reactパターン（推論と行動）) + - [ツールの説明が重要](#ツールの説明が重要) + - [セッション管理](#セッション管理) + - [エラーハンドリング](#エラーハンドリング) +- [利用可能なツール](#利用可能なツール) +- [ツールベースのエージェントを使うべき場合](#ツールベースエージェントを使うべき場合) +- [ツールとRAGの比較](#ツール-vs-rag) +- [次のステップ](#次のステップ) ## ビデオウォークスルー -以下のライブセッションで、このモジュールの始め方を説明しています： +このモジュールの開始方法を説明するライブセッションをご覧ください： -ツールを使った AI エージェントと MCP - ライブセッション +ツールを使用したAIエージェントとMCP - ライブセッション ## 学習内容 -これまでに、AI との会話方法、効果的なプロンプトの構造化、文書に基づいた回答の作成について学びました。しかし根本的な制約があります。言語モデルはテキストしか生成できません。天気の確認、計算、データベースの照会、外部システムとのやり取りはできません。 +これまでに、AIとの会話方法、効果的なプロンプトの構造化、ドキュメントに基づく応答方法を学びました。しかし、根本的な制約がまだあります：言語モデルはテキストしか生成できません。天気を確認したり、計算をしたり、データベースを照会したり、外部システムと連携したりはできません。 -ツールがこれを変えます。モデルが呼び出せる機能へのアクセスを持つことで、単なるテキスト生成器から行動可能なエージェントに変わります。モデルはツールが必要な時、どのツールを使うか、どのパラメータを渡すかを決定します。コードがその関数を実行し、結果を返します。モデルはその結果を応答に取り込みます。 +ツールがこれを変えます。モデルに呼び出せる関数へのアクセス権を与えることで、単なるテキスト生成器から、行動できるエージェントへと変わります。モデルはいつツールが必要か、どのツールを使うか、どのパラメーターを渡すかを決定します。コードは関数を実行し結果を返却します。モデルはその結果を応答に組み込みます。 ## 前提条件 -- [モジュール 01 - はじめに](../01-introduction/README.md) 完了（Azure OpenAI リソースを展開済み） -- 推奨される前モジュールの完了（本モジュールのツール vs RAG 比較で [モジュール 03 の RAG コンセプト](../03-rag/README.md) を参照） -- ルートディレクトリに Azure 資格情報を含む `.env` ファイルが存在（モジュール 01 の `azd up` で作成） +- [Module 01 - Introduction](../01-introduction/README.md) を完了していること（Azure OpenAIリソースがデプロイ済み） +- これまでのモジュールを推奨（本モジュールでは [Module 03のRAGコンセプト](../03-rag/README.md) をツールとRAGの比較で参照） +- ルートディレクトリにAzure認証情報を含む `.env` ファイルがあること（Module 01の `azd up` により作成） -> **注意:** モジュール 01 をまだ完了していない場合は、まずそこで展開手順に従ってください。 +> **注意:** Module 01を完了していない場合は、まずそこでのデプロイ手順に従ってください。 -## ツールを使った AI エージェントの理解 +## ツールを使用したAIエージェントの理解 -> **📝 注意:** 本モジュールの「エージェント」という用語はツール呼び出し機能を強化された AI アシスタントを指します。これは [モジュール 05: MCP](../05-mcp/README.md) で扱う計画、記憶、多段階推論を持つ自律エージェントの **Agentic AI** パターンとは異なります。 +> **📝 注記:** 本モジュールの「エージェント」とは、ツール呼び出し機能が強化されたAIアシスタントを指します。これは [Module 05: MCP](../05-mcp/README.md) で扱う **Agentic AI**（計画、記憶、多段推論を持つ自律的エージェント）とは異なります。 -ツールがなければ言語モデルは訓練データからのテキストしか生成できません。現在の天気を尋ねても推測するしかありません。ツールがあれば天気APIを呼び出したり、計算を行ったり、データベースを照会し、その実際の結果を応答に織り交ぜられます。 +ツール無しでは、言語モデルは訓練データからテキストを生成するだけです。現在の天気を聞かれても推測して答えます。ツールを与えると、天気APIを呼び出したり、計算したり、データベースを照会したりでき、実際の結果を応答に織り込めます。 -ツールなし vs ツールあり +ツール無し vs ツールあり -*ツールなしではモデルは推測のみ、ツールありではAPI呼び出しや計算、リアルタイムデータを返せる。* +*ツールなしではモデルは推測のみ。ツールがあればAPI呼び出し、計算実行、リアルタイムデータの返却が可能。* -ツール付き AI エージェントは **Reasoning and Acting (ReAct)** パターンを採用します。モデルは単に応答するだけでなく、必要なものを考え、ツールを呼び出し、結果を観察して、再度行動するか最終回答を出すかを決めます： +ツールを持つAIエージェントは **Reasoning and Acting (ReAct)** パターンをたどります。モデルはただ返答するのではなく、必要なものを考え、ツールを呼び出して行動し、結果を観察し、再度行動するか最終回答を出すかを決めます： -1. **Reason（推論）** — ユーザーの質問を分析し必要な情報を判断 -2. **Act（行動）** — 適切なツールを選び、正しいパラメータを生成し呼び出す -3. **Observe（観察）** — ツールの出力を受け取り結果を評価 -4. **Repeat or Respond（繰り返すか回答）** — さらにデータが必要なら繰り返し、なければ自然言語の回答を作成 +1. **Reason** — エージェントはユーザーの質問を分析し必要な情報を判断 +2. **Act** — 適切なツールを選び、正しいパラメーターを生成して呼び出す +3. **Observe** — ツールの出力を受け取り結果を評価 +4. **Repeat or Respond** — さらに情報が必要ならループし、そうでなければ自然言語の答えを作成 -ReAct パターン +ReActパターン -*ReAct サイクル — エージェントは何をするか推論し、ツールを呼び行動し、結果を観察して最終回答まで繰り返す。* +*ReActサイクル — エージェントは何をすべきか推論し、ツールを呼び出して行動し、結果を観察し、最終回答を返すまで繰り返す。* -これは自動で行われます。あなたはツールと説明文を定義し、モデルがいつどのように使うかの意思決定を行います。 +これは自動的に行われます。ツールと説明を定義すれば、モデルがいつどのように使うかの意思決定を自動で行います。 ## ツール呼び出しの仕組み @@ -78,7 +78,7 @@ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -明確な説明とパラメータ仕様を持つ関数を定義します。モデルはこれらをシステムプロンプトで読み、各ツールの役割を理解します。 +関数を明確な説明とパラメーター仕様で定義します。モデルはこれらの説明をシステムプロンプトで確認し、各ツールの役割を理解します。 ```java @Component @@ -99,136 +99,136 @@ public interface Assistant { // アシスタントはSpring Bootによって自動的に接続されています: // - ChatModelビーン // - @Componentクラスのすべての@Toolメソッド -// - セッション管理のためのChatMemoryProvider +// - セッション管理用のChatMemoryProvider ``` - -以下の図は各アノテーションの詳細と、それが AI にツール呼び出しや引数指定を理解させる方法を示しています： + +以下の図は全てのアノテーションを分解し、AIがツールをいつ呼び出すべきかや渡す引数を理解する仕組みを示しています： ツール定義の構造 -*ツール定義の構造 — @Tool はAIにいつ使うか伝え、@P は各パラメータを説明し、@AiService が起動時に全てを組み合わせる。* +*ツール定義の構造 — @ToolはAIに使用タイミングを示し、@Pは各パラメーターを説明。@AiServiceは起動時に全てをワイヤリング。* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat で試す:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) を開き、次のように聞いてみましょう： -> - "How would I integrate a real weather API like OpenWeatherMap instead of mock data?" -> - "What makes a good tool description that helps the AI use it correctly?" -> - "How do I handle API errors and rate limits in tool implementations?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) を開き、以下を質問： +> - 「モックデータの代わりにOpenWeatherMapのような実際の天気APIを統合するには？」 +> - 「AIが正しく使うための良いツール説明は何か？」 +> - 「ツール実装でAPIエラーやレート制限をどう扱う？」 ### 意思決定 -ユーザーが「シアトルの天気は？」と聞くと、モデルはランダムにツールを選びません。ユーザー意図を全ツール説明と比較し関連度をスコア化、最適なものを選びます。構造化された関数呼び出しを生成し、例えば `location` を `"Seattle"` に設定します。 +ユーザーが「シアトルの天気は？」と尋ねたら、モデルはツールを無作為に選びません。ユーザーの意図を全ツールの説明ごとに比較し、関連度をスコア付けし、最適なものを選択します。そして適切なパラメーター（例：`location`に`"Seattle"`）を設定した構造化関数呼び出しを生成します。 -該当ツールがなければモデル自体の知識で回答し、複数該当すればもっとも具体的なツールを選びます。 +どのツールも合致しなければ、モデルは自身の知識から回答します。複数候補があれば最も具体的なものを選びます。 -AIがどのツールを使うか決める仕組み +AIが使用するツールを決める仕組み -*モデルは全ツールをユーザーの意図と照らして評価し最適なものを選択 — だから明確で具体的なツール説明が重要。* +*モデルはユーザーの意図と全ツールを評価し最適なものを選択。だから明確で具体的な説明が重要。* ### 実行 [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot が `@AiService` インターフェイスを全ツールで自動ワイヤリングし、LangChain4j がツール呼び出しを自動実行します。背後ではユーザーの自然言語質問から自然言語回答まで6段階のフローがあります： +Spring Bootは宣言的な`@AiService`インターフェイスを全ツールと自動でワイヤリングし、LangChain4jはツール呼び出しを自動実行します。内部的には、ユーザーの自然言語から最終応答まで6段階のフローがあります： ツール呼び出しフロー -*エンドツーエンドの流れ — ユーザー質問→モデルがツール選択→LangChain4jが実行→モデルが結果を応答に組み込む。* +*エンドツーエンドの流れ — ユーザーの質問からモデルがツール選択し、LangChain4jが実行し、結果を自然言語応答に織り込む。* -モジュール 00 の [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) を実行していれば、このパターンは既に体験済みです。計算ツール `Calculator` が同様に呼ばれていました。下図はその際の詳細なシーケンス図です： +内部では`AiServices`が単純な`Calculator`でもツール呼び出しループを走らせます。以下のシーケンス図は詳細を示します： -ツール呼び出しシーケンス図 +ツール呼び出しのシーケンス図 -*クイックスタートのツール呼び出しループ — `AiServices` がメッセージとスキーマをLLMに送り、LLMが `add(42, 58)` のような関数呼び出しで応答、LangChain4j がローカルで実行し結果を返す。* +*ツール呼び出しループ — `AiServices`はメッセージとスキーマをLLMに送り、LLMは`add(42, 58)`のような関数呼び出しを返し、LangChain4jがローカル実行し結果をLLMへ返す。* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat で試す:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) を開き、次の質問をしてみましょう： -> - "ReAct パターンはどう機能し、なぜ AI エージェントに効果的なのか？" -> - "エージェントはどのようにツールを選び、その順序はどう決めているのか？" -> - "ツール実行が失敗した場合はどうなるのか？エラーを堅牢に処理するには？" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chatで試す:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) で以下を質問： +> - 「ReActパターンはどう動作しなぜAIエージェントに有効か？」 +> - 「エージェントはどのツールをどの順序で使うかどうやって決める？」 +> - 「ツール実行が失敗した場合どうなる？堅牢なエラーハンドリングは？」 -### 応答生成 +### レスポンス生成 -モデルは天気データを受け取り、ユーザー向けに自然言語の応答を作成します。 +モデルは天気データを受け取り、ユーザー向けに自然言語でフォーマットします。 -### アーキテクチャ: Spring Boot の自動配線 +### アーキテクチャ：Spring Bootの自動ワイヤリング -本モジュールは LangChain4j の Spring Boot 連携を使用し、宣言的な `@AiService` インターフェイスを利用します。起動時に Spring Boot は `@Tool` メソッドを含む全ての `@Component`、あなたの `ChatModel` ビーン、`ChatMemoryProvider` を検出し、ボイラープレートなしで単一の `Assistant` インターフェイスに全て結合します。 +本モジュールはLangChain4jのSpring Boot統合を使い、宣言的な`@AiService`インターフェイスを利用。起動時にSpring Bootは`@Tool`を含む全`@Component`、あなたの`ChatModel`ビーン、`ChatMemoryProvider`を検知し、単一の`Assistant`インターフェイスにワイヤリングします。ボイラープレートは不要です。 -Spring Boot 自動配線アーキテクチャ +Spring Bootの自動ワイヤリングアーキテクチャ -*@AiService インターフェイスは ChatModel、ツールコンポーネント、メモリプロバイダーを結びつけ、Spring Boot が全配線を自動で処理。* +*@AiServiceインターフェイスはChatModel、ツールコンポーネント、メモリプロバイダーを結合し、Spring Bootが全てのワイヤリングを自動処理。* -以下はリクエストのライフサイクル全体をシーケンス図にしたものです。HTTP リクエストからコントローラー、サービス、Auto-Wired プロキシを経てツール実行、応答までの流れ： +以下はHTTPリクエストからコントローラー、サービス、自動ワイヤリングプロキシ経由でツール実行までの完全なリクエストライフサイクルを示すシーケンス図です： -Spring Boot ツール呼び出しシーケンス +Spring Bootのツール呼び出しシーケンス -*Spring Boot のリクエストライフサイクル全体 — HTTPリクエストがコントローラー、サービスを通って Auto-Wired Assistant プロキシへ届き、LLM とツール呼び出しを自動で調整。* +*完全なSpring Bootリクエストライフサイクル — HTTPリクエストがコントローラーとサービスを通り、自動ワイヤリングされたAssistantプロキシがLLMとツール呼び出しをオーケストレーション。* -この手法の主な利点： +この方式の主な利点： -- **Spring Boot 自動配線** — ChatModel とツールを自動注入 -- **@MemoryId パターン** — セッションベースのメモリ管理自動化 -- **単一インスタンス** — Assistant を一度作成し再利用で性能向上 -- **型安全な実行** — Java メソッドを型変換付きで直接呼び出し -- **マルチターン制御** — ツールチェインを自動管理 -- **ボイラープレートゼロ** — 手動で `AiServices.builder()` 呼び出し不要 +- **Spring Boot自動ワイヤリング** — ChatModelとツールを自動注入 +- **@MemoryIdパターン** — セッションベースのメモリ管理を自動化 +- シングルインスタンス — Assistantを一度作成し性能向上のため再利用 +- 型安全な実行 — Javaメソッドを型変換して直接呼び出し +- マルチターンオーケストレーション — ツールチェイニングを自動処理 +- ボイラープレートゼロ — 手動での `AiServices.builder()` やメモリのHashMapは不要 -手動で `AiServices.builder()` を使う代替案はコード量が増え、Spring Boot 連携の利点を享受できません。 +手動の `AiServices.builder()` のような代替手法はコード量が増え、Spring Bootの統合メリットを享受できません。 ## ツールチェイニング -**ツールチェイニング** — ツールベースエージェントの真価は、一つの質問に複数ツールを連鎖的に使うところにあります。「シアトルの天気は華氏で？」と聞くと、まず `getCurrentWeather` ツールで摂氏温度を取得し、その後 `celsiusToFahrenheit` ツールに渡して変換します。これが一つの会話ターン内で自動的に行われます。 +ツールチェイニング — ツールベースエージェントの真骨頂は、単一の質問に複数ツールを連携して使う場合に発揮されます。「シアトルの華氏での天気は？」と尋ねると、エージェントは自動的に2つのツールを連結します：まず`getCurrentWeather`で摂氏温度を得て、それを`celsiusToFahrenheit`に渡し変換し、一度の会話ターンで答えを返します。 -ツールチェイニング例 +ツールチェイニングの例 -*ツールチェイニング実例 — まず getCurrentWeather を呼び、摂氏の結果を celsiusToFahrenheit に渡して複合回答を生成。* +*ツールチェイニングの実例 — まずgetCurrentWeatherを呼び、摂氏結果をcelsiusToFahrenheitに渡し連結した答えを返す。* -**優雅な失敗** — モックデータにない都市の天気を尋ねると、ツールがエラーメッセージを返し、AI はクラッシュせず助けられない旨を説明します。ツールは安全に失敗します。下図はその対比で、適切なエラー処理がある場合は例外をキャッチし丁寧に回答、処理しなければアプリ全体がクラッシュします： +優雅な失敗処理 — モックデータにない都市の天気を聞くと、ツールはエラーメッセージを返し、AIはクラッシュする代わりに助けられない旨を説明します。ツールは安全に失敗します。以下の図は2つのアプローチを比較：適切なエラーハンドリングありの場合はエージェントが例外を捕捉し親切に応答、一方で無しの場合はアプリ全体がクラッシュ： -エラー処理の流れ +エラーハンドリングの流れ -*ツールが失敗した際、例外をキャッチしてクラッシュせず説明を返すのが望ましい挙動。* +*ツールが失敗するとエージェントはエラーを捕捉し、クラッシュせずに役立つ説明で応答。* -これらは一つの会話ターンで自動実行されます。エージェントが複数のツール呼び出しを自律的に調整します。 +これは一つの会話ターンで発生します。エージェントは複数ツール呼び出しを自律的にオーケストレーションします。 -## アプリケーションの実行 +## アプリケーションを実行する -**展開の確認:** +**デプロイの確認：** -ルートディレクトリに Azure 資格情報を含む `.env` ファイルがあることを確認します（モジュール 01 で作成済み）。次のコマンドをモジュールディレクトリ（`04-tools/`）で実行します： +ルートディレクトリにAzure認証情報入りの`.env`ファイルがあることを確認してください（Module 01で作成済み）。モジュールディレクトリ(`04-tools/`)から以下を実行： **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENTを表示する必要があります +cat ../.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT を表示する必要があります ``` - + **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT を表示する必要があります +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENTを表示する必要があります ``` - -**アプリケーションの起動:** -> **注意:** ルートディレクトリで `./start-all.sh` を使いすでに全アプリを起動済みの場合（モジュール 01 参照）、本モジュールはポート8084で既に稼働中です。以下の起動コマンドはスキップし、直接 http://localhost:8084 にアクセスしてください。 +**アプリケーションの起動：** + +> **注意:** 既にルートディレクトリの `./start-all.sh` から全アプリを起動済みなら（Module 01で説明）、このモジュールはポート8084で動作中です。以下の起動コマンドはスキップして http://localhost:8084 に直接アクセス可能です。 -**オプション1: Spring Boot ダッシュボードを使う（VS Codeユーザーに推奨）** +**オプション1: Spring Bootダッシュボードの使用（VS Codeユーザー推奨）** -Dev コンテナには Spring Boot ダッシュボード拡張が含まれており、全ての Spring Boot アプリケーションを視覚的に管理できます。VS Code の左側アクティビティバーで Spring Boot アイコンを探してください。 +DevコンテナにはSpring Bootダッシュボード拡張機能が含まれており、全Spring Bootアプリを視覚的に管理可能です。VS Codeの左側アクティビティバーにSpring Bootアイコンがあります。 -Spring Boot ダッシュボードからは以下が可能です： -- ワークスペース内の全 Spring Boot アプリを一覧表示 -- クリック一つでアプリの起動・停止 -- リアルタイムでのログの閲覧 -- アプリケーションの状態監視 -「tools」の横にある再生ボタンをクリックするだけで、このモジュールを開始するか、すべてのモジュールを一度に開始できます。 +Spring Bootダッシュボードからは： +- ワークスペース内の全Spring Bootアプリを確認 +- クリック一つでアプリ起動／停止 +- アプリログをリアルタイム表示 +- アプリ状態を監視 -以下は VS Code の Spring Boot ダッシュボードの画面例です: +"tools" の横の再生ボタンをクリックすればこのモジュールが起動します。全モジュールを一括起動も可能です。 +以下はVS CodeでのSpring Bootダッシュボードの様子です： Spring Boot Dashboard -*VS Code の Spring Boot ダッシュボード — すべてのモジュールを一か所で起動、停止、監視* +*VS CodeのSpring Bootダッシュボード — すべてのモジュールを一箇所で起動、停止、監視* -**オプション 2: シェルスクリプトを使う** +**オプション2: シェルスクリプトの使用** -すべてのウェブアプリケーション（モジュール 01-04）を起動する: +すべてのウェブアプリケーション（モジュール01-04）を起動： **Bash:** ```bash @@ -242,7 +242,7 @@ cd .. # ルートディレクトリから .\start-all.ps1 ``` -または、このモジュールだけを起動する: +またはこのモジュールだけ起動： **Bash:** ```bash @@ -256,16 +256,16 @@ cd 04-tools .\start.ps1 ``` -両方のスクリプトは自動的にルートの `.env` ファイルから環境変数を読み込み、JAR が存在しない場合はビルドします。 +両方のスクリプトはルートの`.env`ファイルから環境変数を自動的に読み込み、JARが存在しない場合はビルドします。 -> **注意:** すべてのモジュールを手動でビルドしてから起動したい場合: +> **注意:** 起動前にすべてのモジュールを手動でビルドしたい場合： > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -274,7 +274,7 @@ cd 04-tools ブラウザで http://localhost:8084 を開いてください。 -**停止方法:** +**停止するには：** **Bash:** ```bash @@ -290,86 +290,86 @@ cd .. && ./stop-all.sh # すべてのモジュール cd ..; .\stop-all.ps1 # すべてのモジュール ``` -## アプリケーションの使い方 +## アプリケーションの使用 -このアプリケーションはウェブインターフェイスを提供し、天気情報や温度変換ツールにアクセス可能な AI エージェントと対話できます。以下がインターフェイスの画面です — クイックスタート用の例とリクエスト送信用のチャットパネルが含まれます: +このアプリケーションは、天気や温度変換ツールにアクセス可能なAIエージェントと対話できるウェブインターフェースを提供します。インターフェースは以下のようなもので、クイックスタート例やリクエストを送るためのチャットパネルが含まれています： AI Agent Tools Interface -*AI エージェントツールのインターフェイス — クイック例とツール操作用チャットインターフェイス* +*AIエージェントツールのインターフェース - クイック例とツールとの対話用チャットインターフェース* -### 簡単なツール使用を試す +### シンプルなツール使用を試す -まずは単純なリクエストから試してください: 「100度の華氏を摂氏に変換して」。エージェントは温度変換ツールを使う必要があると認識し、適切なパラメータで呼び出して結果を返します。どのツールを使うかや呼び出し方を書かなくても自然に動作する点に注目してください。 +単純なリクエスト「100度華氏を摂氏に変換してください」から始めてみましょう。エージェントは温度変換ツールを使う必要があることを認識し、正しいパラメータで呼び出して結果を返します。どのツールを使うかや呼び出し方を指定しなくても自然に機能するのが分かります。 -### ツールの連鎖をテスト +### ツールチェーンを試す -次に少し複雑な例を試します: 「シアトルの天気を教えて、それを華氏に変換して」。エージェントは段階を追って処理します。まず天気情報を取得（摂氏で返る）、次に華氏に変換する必要があると認識し、変換ツールを呼び出し、両方の結果を一つの回答にまとめます。 +次により複雑な例：「シアトルの天気はどうですか？そしてそれを華氏に変換してください」を試してみましょう。エージェントが段階的に処理する様子が見られます。まず天気情報（摂氏で返される）を取得し、次に華氏に変換する必要があると判断し変換ツールを呼び、両方の結果を組み合わせて応答します。 -### 会話の流れを見る +### 会話フローを見る -チャットインターフェイスは会話の履歴を保持し、複数ターンの対話が可能です。過去の問い合わせや回答をすべて確認できるので、会話の文脈がどのように構築されているか追いやすくなっています。 +チャットインターフェースは会話履歴を維持し、複数ターンの対話を可能にします。すべての前回の質問と回答を確認できるため、会話の流れを追いやすく、複数のやり取りによるコンテキスト構築が理解しやすくなっています。 Conversation with Multiple Tool Calls -*複数ターン対話の例 — 単純な変換、天気情報取得、ツール連携の様子* +*シンプルな変換、天気確認、ツールチェーンを示す複数ターン会話例* -### いろいろなリクエストを試す +### さまざまなリクエストを試す -さまざまな組み合わせをお試しください: -- 天気情報確認: 「東京の天気は？」 -- 温度変換: 「25℃はケルビンでいくつ？」 -- 複合問い合わせ: 「パリの天気を調べて20℃以上か教えて」 +以下のような組み合わせを試してみてください： +- 天気確認：「東京の天気は？」 +- 温度変換：「25°Cはケルビンでいくつ？」 +- 複合クエリ：「パリの天気を調べて、20°Cを超えているか教えて」 -エージェントが自然言語を理解し、適切なツール呼び出しにマッピングする様子がわかります。 +エージェントが自然言語を解釈し、適切なツール呼び出しにマッピングする様子がわかります。 -## 重要な概念 +## 重要なコンセプト -### ReAct パターン（推論と行動） +### ReActパターン（推論と行動） -エージェントは推論（何をすべきか考える）と行動（ツールを使う）を交互に行います。このパターンにより、単なる指示への反応ではなく、自律的な問題解決が可能になります。 +エージェントは推論（何をすべきか決定）と行動（ツールの使用）を交互に行います。このパターンにより、単なる指示への応答ではなく自律的な問題解決が可能になります。 ### ツールの説明が重要 -ツールの説明内容がエージェントの使い方に直接影響します。明確かつ具体的な説明が、いつどのようにツールを呼び出すべきかモデルが理解するのに役立ちます。 +ツールの説明の質が高いと、エージェントがそれらを使う精度が向上します。分かりやすく具体的な説明はモデルがいつどのようにツールを呼び出すか理解するのに役立ちます。 ### セッション管理 -`@MemoryId` アノテーションによって、自動のセッションベースのメモリ管理が可能になります。各セッション ID ごとに `ChatMemory` インスタンスが `ChatMemoryProvider` ビーンによって管理され、複数ユーザーが同時にエージェントと対話しても会話が混ざりません。以下の図は複数ユーザーをセッション ID に基づいた独立メモリーストアにルーティングする仕組みを示しています: +`@MemoryId`アノテーションにより自動的なセッションベースのメモリ管理が可能です。各セッションIDに`ChatMemory`インスタンスが割り当てられ、`ChatMemoryProvider`ビーンが管理するため、複数ユーザーが同時にエージェントと対話しても会話が混ざりません。以下の図はセッションIDごとに別々のメモリストアにルーティングされる様子を示しています： Session Management with @MemoryId -*各セッション ID は独立した会話履歴に対応 — ユーザー同士のメッセージは見えない* +*各セッションIDは独立した会話履歴に対応—ユーザーは互いのメッセージを決して見ません。* -### エラー処理 +### エラーハンドリング -ツールは失敗することがあります — API のタイムアウト、無効なパラメータ、外部サービスの停止など。実用的なエージェントはエラー処理が必要で、モデルは問題を説明したり代替手段を試すことができ、アプリケーション全体がクラッシュしないようにします。ツールが例外をスローすると LangChain4j がキャッチし、エラーメッセージをモデルに渡し、モデルは自然言語で問題を説明します。 +ツールは失敗することがあります — APIのタイムアウト、パラメータの不正、外部サービス障害など。実運用エージェントはエラーハンドリングを備え、モデルが問題を説明したり代替手段を試すことでアプリケーション全体のクラッシュを防ぎます。ツールが例外を投げた場合、LangChain4jはそれをキャッチしてエラーメッセージをモデルに返し、モデルは自然言語で問題を説明できます。 ## 利用可能なツール -以下の図は構築可能なツールの広範なエコシステムを示しています。このモジュールでは天気と温度のツールを例示していますが、同じ `@Tool` パターンはあらゆる Java メソッドに適用可能です — データベース問い合わせから支払い処理まで対応します。 +以下の図は構築可能なツールの広範なエコシステムを示しています。このモジュールでは天気と温度のツールを示しましたが、同じ`@Tool`パターンは任意のJavaメソッドに適用可能です—データベースクエリから決済処理まで幅広く使えます。 Tool Ecosystem -*@Tool アノテーションを付けた任意の Java メソッドが AI に利用可能に — パターンはデータベース、API、メール、ファイル操作など拡張可能です。* +*@Toolアノテーション付きのJavaメソッドはAIに利用可能になり、このパターンはデータベース、API、メール、ファイル操作などにも拡張可能です。* -## ツールベースのエージェントを使うタイミング +## ツールベースエージェントを使うべき場合 -すべてのリクエストにツールが必要なわけではありません。判断基準は AI が外部システムとやりとりする必要があるか、自身の知識だけで回答可能かです。以下のガイドはツールが有用な場合と不要な場合をまとめています: +すべてのリクエストにツールが必要なわけではありません。外部システムとやり取りが必要か、またはAI自身の知識だけで答えられるかで決まります。以下のガイドはツールが価値を発揮する場合と不要な場合の目安を示しています： When to Use Tools -*簡単な判断ガイド — ツールはリアルタイムデータ、計算、操作を扱う時に使う。一般知識や創造的な作業では不要。* +*簡単な判断ガイド — ツールはリアルタイムデータ、計算、アクション時に使い、一般知識や創造的なタスクには不要です。* -## ツールと RAG の違い +## ツール vs RAG -モジュール 03 と 04 はどちらも AI の機能を拡張しますが、基本的に異なる方法です。RAG はドキュメント検索によってモデルに**知識**へのアクセスを提供します。ツールは関数呼び出しによりモデルが**行動**できるようにします。以下の図はそれぞれのワークフローやトレードオフを並べて比較しています: +モジュール03と04はどちらもAIの能力を拡張しますが、基本的に異なる方法です。RAGはドキュメントの知識にアクセスさせます。ツールは関数を呼び出して行動を取らせます。以下の図はこれら両者の比較で、ワークフローの違いからトレードオフまで示しています： Tools vs RAG Comparison -*RAG は静的ドキュメントから情報を取得 — ツールは動的かつリアルタイムのデータを操作および取得。多くの本番システムは両者を組み合わせている。* +*RAGは静的ドキュメントから情報を取得—ツールはアクションを実行し動的なリアルタイムデータを取得。多くの本番システムは両者を併用しています。* -実際、多くの本番環境では両者を組み合わせます: RAG でドキュメントに基づく回答を生成し、ツールでライブデータ取得や操作を行う形です。 +実際、多くの本番システムではRAGでドキュメントに基づいた回答を行い、ツールでライブデータ取得や操作を行う両アプローチの組み合わせを採用しています。 ## 次のステップ @@ -377,11 +377,11 @@ cd ..; .\stop-all.ps1 # すべてのモジュール --- -**ナビゲーション:** [← 前へ: モジュール 03 - RAG](../03-rag/README.md) | [メインへ戻る](../README.md) | [次へ: モジュール 05 - MCP →](../05-mcp/README.md) +**ナビゲーション:** [← 前へ: Module 03 - RAG](../03-rag/README.md) | [メインへ戻る](../README.md) | [次へ: Module 05 - MCP →](../05-mcp/README.md) --- -**免責事項**： -本書類はAI翻訳サービス「[Co-op Translator](https://github.com/Azure/co-op-translator)」を使用して翻訳されています。正確性を期しておりますが、自動翻訳には誤りや不正確な部分が含まれる可能性があることをご承知おきください。原文の言語で記載された文書が正式な情報源とみなされます。重要な情報については、専門の人間による翻訳を推奨いたします。本翻訳の使用により生じた誤解や誤訳について、一切の責任を負いかねます。 - +**免責事項**： +本書類は AI 翻訳サービス [Co-op Translator](https://github.com/Azure/co-op-translator) を使用して翻訳されています。正確性を期していますが、自動翻訳には誤りや不正確な部分が含まれる可能性があることをご承知おきください。原文の原語版が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じたいかなる誤解や解釈違いについても、当方は責任を負いかねます。 + \ No newline at end of file diff --git a/translations/ja/README.md b/translations/ja/README.md index 73968048a..a68031fd0 100644 --- a/translations/ja/README.md +++ b/translations/ja/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j 入門者向け +# LangChain4j 初心者向け -LangChain4j と Azure OpenAI GPT-5.2 を使った AI アプリケーション構築コース。基本的なチャットから AI エージェントまで。 +LangChain4j と Azure OpenAI GPT-5.2 を使って、基本的なチャットからAIエージェントまでのAIアプリケーションを構築するコース。 ### 🌐 マルチ言語対応 -#### GitHub Action によるサポート（自動＆常に最新） +#### GitHub Action 経由でサポート（自動＆常に最新） -[アラビア語](../ar/README.md) | [ベンガル語](../bn/README.md) | [ブルガリア語](../bg/README.md) | [ビルマ語（ミャンマー）](../my/README.md) | [中国語（簡体字）](../zh-CN/README.md) | [中国語（繁体字、香港）](../zh-HK/README.md) | [中国語（繁体字、マカオ）](../zh-MO/README.md) | [中国語（繁体字、台湾）](../zh-TW/README.md) | [クロアチア語](../hr/README.md) | [チェコ語](../cs/README.md) | [デンマーク語](../da/README.md) | [オランダ語](../nl/README.md) | [エストニア語](../et/README.md) | [フィンランド語](../fi/README.md) | [フランス語](../fr/README.md) | [ドイツ語](../de/README.md) | [ギリシャ語](../el/README.md) | [ヘブライ語](../he/README.md) | [ヒンディー語](../hi/README.md) | [ハンガリー語](../hu/README.md) | [インドネシア語](../id/README.md) | [イタリア語](../it/README.md) | [日本語](./README.md) | [カンナダ語](../kn/README.md) | [クメール語](../km/README.md) | [韓国語](../ko/README.md) | [リトアニア語](../lt/README.md) | [マレー語](../ms/README.md) | [マラヤーラム語](../ml/README.md) | [マラーティー語](../mr/README.md) | [ネパール語](../ne/README.md) | [ナイジェリア・ピジン語](../pcm/README.md) | [ノルウェー語](../no/README.md) | [ペルシャ語（ファルシ）](../fa/README.md) | [ポーランド語](../pl/README.md) | [ポルトガル語（ブラジル）](../pt-BR/README.md) | [ポルトガル語（ポルトガル）](../pt-PT/README.md) | [パンジャブ語（グルムキー）](../pa/README.md) | [ルーマニア語](../ro/README.md) | [ロシア語](../ru/README.md) | [セルビア語（キリル）](../sr/README.md) | [スロバキア語](../sk/README.md) | [スロベニア語](../sl/README.md) | [スペイン語](../es/README.md) | [スワヒリ語](../sw/README.md) | [スウェーデン語](../sv/README.md) | [タガログ語（フィリピン）](../tl/README.md) | [タミル語](../ta/README.md) | [テルグ語](../te/README.md) | [タイ語](../th/README.md) | [トルコ語](../tr/README.md) | [ウクライナ語](../uk/README.md) | [ウルドゥー語](../ur/README.md) | [ベトナム語](../vi/README.md) +[アラビア語](../ar/README.md) | [ベンガル語](../bn/README.md) | [ブルガリア語](../bg/README.md) | [ビルマ語 (ミャンマー)](../my/README.md) | [中国語（簡体字）](../zh-CN/README.md) | [中国語（繁体字、香港）](../zh-HK/README.md) | [中国語（繁体字、マカオ）](../zh-MO/README.md) | [中国語（繁体字、台湾）](../zh-TW/README.md) | [クロアチア語](../hr/README.md) | [チェコ語](../cs/README.md) | [デンマーク語](../da/README.md) | [オランダ語](../nl/README.md) | [エストニア語](../et/README.md) | [フィンランド語](../fi/README.md) | [フランス語](../fr/README.md) | [ドイツ語](../de/README.md) | [ギリシャ語](../el/README.md) | [ヘブライ語](../he/README.md) | [ヒンディー語](../hi/README.md) | [ハンガリー語](../hu/README.md) | [インドネシア語](../id/README.md) | [イタリア語](../it/README.md) | [日本語](./README.md) | [カンナダ語](../kn/README.md) | [クメール語](../km/README.md) | [韓国語](../ko/README.md) | [リトアニア語](../lt/README.md) | [マレー語](../ms/README.md) | [マラヤーラム語](../ml/README.md) | [マラーティー語](../mr/README.md) | [ネパール語](../ne/README.md) | [ナイジェリア・ピジン語](../pcm/README.md) | [ノルウェー語](../no/README.md) | [ペルシャ語（ファルシ）](../fa/README.md) | [ポーランド語](../pl/README.md) | [ポルトガル語（ブラジル）](../pt-BR/README.md) | [ポルトガル語（ポルトガル）](../pt-PT/README.md) | [パンジャブ語（グルムキー）](../pa/README.md) | [ルーマニア語](../ro/README.md) | [ロシア語](../ru/README.md) | [セルビア語（キリル文字）](../sr/README.md) | [スロバキア語](../sk/README.md) | [スロベニア語](../sl/README.md) | [スペイン語](../es/README.md) | [スワヒリ語](../sw/README.md) | [スウェーデン語](../sv/README.md) | [タガログ語（フィリピン語）](../tl/README.md) | [タミル語](../ta/README.md) | [テルグ語](../te/README.md) | [タイ語](../th/README.md) | [トルコ語](../tr/README.md) | [ウクライナ語](../uk/README.md) | [ウルドゥー語](../ur/README.md) | [ベトナム語](../vi/README.md) -> **ローカルにクローンしたいですか？** +> **ローカルでクローンする方が良いですか？** > -> このリポジトリには50以上の言語翻訳が含まれており、ダウンロードサイズが大幅に増えます。翻訳なしでクローンするにはスパースチェックアウトを使ってください： +> このリポジトリには50以上の言語翻訳が含まれているため、ダウンロードサイズが大きくなります。翻訳なしでクローンする場合は、スパースチェックアウトを使用してください： > > **Bash / macOS / Linux:** > ```bash @@ -22,68 +22,67 @@ LangChain4j と Azure OpenAI GPT-5.2 を使った AI アプリケーション構 > git sparse-checkout set --no-cone '/*' '!translations' '!translated_images' > ``` > -> **CMD（Windows）:** +> **CMD (Windows):** > ```cmd > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> これにより、コースを完了するために必要なすべてが非常に高速にダウンロードできます。 +> これにより、コースを完了するために必要なすべてが、はるかに速いダウンロードで手に入ります。 ## 目次 -1. [クイックスタート](00-quick-start/README.md) - LangChain4j の始め方 -2. [紹介](01-introduction/README.md) - LangChain4j の基本を学ぶ -3. [プロンプトエンジニアリング](02-prompt-engineering/README.md) - 効果的なプロンプト設計を習得 -4. [RAG（検索拡張生成）](03-rag/README.md) - 知識ベースのインテリジェントシステムを構築 -5. [ツール](04-tools/README.md) - 外部ツールと簡単なアシスタントを統合 -6. [MCP（モデルコンテキストプロトコル）](05-mcp/README.md) - モデルコンテキストプロトコル（MCP）とエージェントモジュールを扱う +1. [イントロダクション](01-introduction/README.md) - LangChain4j の基本を学ぶ +2. [プロンプトエンジニアリング](02-prompt-engineering/README.md) - 効果的なプロンプト設計を習得 +3. [RAG（検索強化生成）](03-rag/README.md) - インテリジェントな知識ベースシステムを構築 +4. [ツール](04-tools/README.md) - 外部ツールとシンプルなアシスタントを統合 +5. [MCP（モデルコンテキストプロトコル）](05-mcp/README.md) - MCPとエージェントモジュールで作業 ### ビデオウォークスルー -各モジュールには、概念とコードをステップごとに解説するライブセッションがあります。 +各モジュールには伴走ライブセッションがあり、コンセプトとコードをステップごとに解説します。 | モジュール | ビデオ | |--------|-------| -| 01 - 紹介 | [LangChain4jのはじめ方](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - プロンプトエンジニアリング | [LangChain4jのプロンプトエンジニアリング](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [LangChain4jのRAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - ツール & 05 - MCP | [ツールとMCPを活用したAIエージェント](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 01 - イントロダクション | [LangChain4j を使った入門](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - プロンプトエンジニアリング | [LangChain4j でのプロンプトエンジニアリング](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [LangChain4j のRAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 04 - ツール & 05 - MCP | [ツールとMCPを使ったAIエージェント](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## 学習パス -**LangChain4jが初めてですか？** 主要な用語と概念の定義については [用語集](docs/GLOSSARY.md) をご覧ください。 +**LangChain4j初心者ですか？** 重要用語や概念の定義は [Glossary](docs/GLOSSARY.md) をご覧ください。 > クイックスタート 1. このリポジトリをあなたのGitHubアカウントにフォークする -2. **Code** → **Codespaces** タブ → **...** → **新規オプション付きで作成...** をクリック -3. デフォルトのまま使用 – コース用に作成された開発コンテナが選択されます -4. コードスペースを作成 をクリック -5. 環境が準備されるまで5～10分待つ -6. すぐに [クイックスタート](./00-quick-start/README.md) に移動して開始！ +2. **Code** → **Codespaces** タブ → **...** → **New with options...** をクリック +3. デフォルトのまま – これにより、このコース用に作成された開発コンテナが選択されます +4. **Create codespace** をクリック +5. 環境が準備されるまで5〜10分待つ +6. すぐに [イントロダクション](./01-introduction/README.md) にジャンプして開始！ -モジュールを完了したら、[テストガイド](docs/TESTING.md) を見て LangChain4j のテストコンセプトを実践で確認してください。 +モジュールを修了したら、[テストガイド](docs/TESTING.md) を参照して LangChain4j のテスト概念を実践で確認しましょう。 -> **注意：** このトレーニングでは GitHub モデルと Azure OpenAI の両方を使用します。[クイックスタート](00-quick-start/README.md) モジュールでは GitHub モデル（Azure サブスクリプション不要）を使い、モジュール1～5では Azure OpenAI を使います。まだお持ちでない場合は、[無料Azureアカウント](https://aka.ms/azure-free-account)で始めましょう。 +> **注意:** 本トレーニングは Azure OpenAI を使用します。まだお持ちでない場合は、[無料の Azure アカウント](https://aka.ms/azure-free-account) をご利用ください。 -## GitHub Copilot での学習 +## GitHub Copilot で学ぶ -素早くコーディングを始めるには、このプロジェクトを GitHub Codespace または、提供されている devcontainer を使ってローカルIDEで開きます。このコースで使う devcontainer は AI ペアプログラミング用の GitHub Copilot が事前に設定されています。 +すぐにコーディングを始めたい場合は、このプロジェクトを GitHub Codespace または提供された devcontainer を使ってローカル IDE で開いてください。本コースで使う devcontainer は AIペアプログラミング用に GitHub Copilot が事前設定されています。 -各コード例には、理解を深めるために GitHub Copilot に質問できる推奨質問が含まれています。💡/🤖 のプロンプトを探してください： +各コード例には、GitHub Copilot に質問して理解を深めるための質問例があります。以下で 💡/🤖 のプロンプトを探してください： -- **Java ファイルヘッダー** - 各例に特化した質問 -- **モジュール README** - コード例の後の探究用プロンプト +- **Java ファイルのヘッダー** - 各例に特化した質問 +- **モジュールの README** - コード例後の探求用プロンプト -**使い方：** 任意のコードファイルを開き、推奨質問を Copilot に尋ねてみてください。コードベース全体の文脈を理解しており、説明や拡張、提案もできます。 +**使い方:** どのコードファイルでも開いて、提案された質問をCopilotに尋ねてください。コードベース全体のコンテキストが把握されており、説明や拡張、代替案の提案が可能です。 -もっと知りたい？ [AIペアプログラミング用Copilot](https://aka.ms/GitHubCopilotAI) をチェックしてください。 +もっと学びたいですか？ [AI ペアプログラミングのための Copilot](https://aka.ms/GitHubCopilotAI) をご覧ください。 ## 追加リソース @@ -95,7 +94,7 @@ LangChain4j と Azure OpenAI GPT-5.2 を使った AI アプリケーション構 [![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents +### Azure / Edge / MCP / エージェント [![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) [![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) [![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -111,40 +110,41 @@ LangChain4j と Azure OpenAI GPT-5.2 を使った AI アプリケーション構 --- -### コアラーニング +### コア学習 [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![初心者のためのサイバーセキュリティ](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![初心者のためのWeb開発](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![初心者のためのIoT](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![初心者のためのXR開発](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Copilot シリーズ -[![AIペアプログラミング向けCopilot](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET向けCopilot](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilotアドベンチャー](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## ヘルプを得るには -AIアプリの開発で困ったり質問がある場合は、次に参加してください: +AI アプリの構築で困ったり質問がある場合は、次に参加してください: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -製品のフィードバックや開発中のエラーについては、次を訪問してください: +製品のフィードバックや構築中にエラーがあった場合は、次を参照してください: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## ライセンス -MITライセンス - 詳細は[LICENSE](../../LICENSE)ファイルをご覧ください。 +MIT ライセンス - 詳細は [LICENSE](../../LICENSE) ファイルを参照してください。 --- -**免責事項**: -本書類は AI 翻訳サービス [Co-op Translator](https://github.com/Azure/co-op-translator) を使用して翻訳されています。正確さを期していますが、自動翻訳には誤りや不正確な箇所が含まれる可能性があることをご了承ください。原文のネイティブ言語での文書が権威ある情報源とみなされます。重要な情報については、専門の人間翻訳をご利用いただくことを推奨します。本翻訳の利用により生じた誤解や誤訳について、一切の責任を負いかねます。 +**免責事項**： +本書類は AI 翻訳サービス [Co-op Translator](https://github.com/Azure/co-op-translator) を使用して翻訳されています。正確性を期していますが、自動翻訳には誤りや不正確な部分が含まれる可能性があることをご承知おきください。原文の原語版が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じたいかなる誤解や解釈違いについても、当方は責任を負いかねます。 \ No newline at end of file diff --git a/translations/ja/docs/GLOSSARY.md b/translations/ja/docs/GLOSSARY.md index 3fe5422ea..7004c5f04 100644 --- a/translations/ja/docs/GLOSSARY.md +++ b/translations/ja/docs/GLOSSARY.md @@ -2,137 +2,137 @@ ## 目次 -- [基本概念](../../../docs) -- [LangChain4j コンポーネント](../../../docs) -- [AI/ML 概念](../../../docs) -- [ガードレール](../../../docs) -- [プロンプトエンジニアリング](../../../docs) -- [RAG (検索拡張生成)](../../../docs) -- [エージェントとツール](../../../docs) -- [エージェンティックモジュール](../../../docs) -- [モデルコンテキストプロトコル (MCP)](../../../docs) -- [Azure サービス](../../../docs) -- [テストと開発](../../../docs) +- [コアコンセプト](#コアコンセプト) +- [LangChain4j コンポーネント](#langchain4j-コンポーネント) +- [AI/ML コンセプト](#aiml-コンセプト) +- [ガードレール](#ガードレール) +- [プロンプトエンジニアリング](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [エージェントとツール](#agents-and-tools---module-04) +- [エージェンシックモジュール](#agentic-module---module-05) +- [モデルコンテキストプロトコル (MCP)](#model-context-protocol-mcp---module-05) +- [Azure サービス](#azure-services---module-01) +- [テストおよび開発](#testing-and-development---testing-guide) コース全体で使用される用語と概念のクイックリファレンス。 -## 基本概念 +## コアコンセプト -**AI エージェント** - AIを使用して自律的に推論し行動するシステム。 [モジュール 04](../04-tools/README.md) +**AIエージェント** - AIを使用して自律的に推論し行動するシステム。 [モジュール 04](../04-tools/README.md) -**チェーン** - 出力が次のステップの入力となる一連の操作。 +チェーン - 出力が次のステップに入力される一連の操作。 -**チャンク化** - 文書を小さい断片に分割すること。典型的には300～500トークン、重複あり。 [モジュール 03](../03-rag/README.md) +チャンク分割 - ドキュメントをより小さな部分に分割すること。典型的には300〜500トークンで重複あり。 [モジュール 03](../03-rag/README.md) -**コンテキストウィンドウ** - モデルが処理できる最大のトークン数。GPT-5.2: 40万トークン（入力最大27.2万、出力12.8万）。 +コンテキストウィンドウ - モデルが処理できる最大トークン数。GPT-5.2: 400Kトークン（最大272K入力、128K出力）。 -**埋め込み（Embeddings）** - テキストの意味を表す数値ベクトル。 [モジュール 03](../03-rag/README.md) +**埋め込み (Embeddings)** - テキストの意味を表す数値ベクトル。 [モジュール 03](../03-rag/README.md) -**関数呼び出し** - モデルが外部関数呼び出し用の構造化リクエストを生成すること。 [モジュール 04](../04-tools/README.md) +関数呼び出し - モデルが外部関数を呼び出すための構造化リクエストを生成。 [モジュール 04](../04-tools/README.md) -**幻覚（Hallucination）** - モデルが誤っているがもっともらしい情報を生成すること。 +ハルシネーション - モデルが誤ったが妥当な情報を生成すること。 -**プロンプト** - 言語モデルへのテキスト入力。 [モジュール 02](../02-prompt-engineering/README.md) +プロンプト - 言語モデルへのテキスト入力。 [モジュール 02](../02-prompt-engineering/README.md) -**意味検索（Semantic Search）** - キーワードではなく埋め込みを使用した意味による検索。 [モジュール 03](../03-rag/README.md) +セマンティックサーチ - キーワードではなく埋め込みを使った意味に基づく検索。 [モジュール 03](../03-rag/README.md) -**状態あり vs 状態なし** - 状態なし: メモリなし。状態あり: 会話履歴を保持。 [モジュール 01](../01-introduction/README.md) +**ステートフル vs ステートレス** - ステートレス：記憶なし。ステートフル：会話履歴を維持。 [モジュール 01](../01-introduction/README.md) -**トークン** - モデルが処理する基本テキスト単位。コストや制限に影響。 [モジュール 01](../01-introduction/README.md) +トークン - モデルが処理する基本的なテキスト単位。コストと制限に影響。 [モジュール 01](../01-introduction/README.md) -**ツールチェイニング** - 一連のツール実行で出力が次の呼び出しを決定。 [モジュール 04](../04-tools/README.md) +ツールチェイニング - 出力が次の呼び出しに連動する連続的なツール実行。 [モジュール 04](../04-tools/README.md) ## LangChain4j コンポーネント -**AiServices** - 型安全なAIサービスインターフェイスを作成。 +**AiServices** - 型安全なAIサービスインターフェースを作成。 **OpenAiOfficialChatModel** - OpenAIおよびAzure OpenAIモデルの統合クライアント。 -**OpenAiOfficialEmbeddingModel** - OpenAI公式クライアントを用いた埋め込み作成（OpenAIとAzure OpenAI両対応）。 +**OpenAiOfficialEmbeddingModel** - OpenAI Officialクライアントを使った埋め込み生成（OpenAIとAzure OpenAIの両方対応）。 -**ChatModel** - 言語モデルのコアインターフェイス。 +**ChatModel** - 言語モデルのコアインターフェース。 **ChatMemory** - 会話履歴を維持。 -**ContentRetriever** - RAG用に関連する文書チャンクを検索。 +**ContentRetriever** - RAG用の関連ドキュメントチャンクを検索。 -**DocumentSplitter** - 文書をチャンクに分割。 +**DocumentSplitter** - ドキュメントをチャンクに分割。 **EmbeddingModel** - テキストを数値ベクトルに変換。 -**EmbeddingStore** - 埋め込みの保存・取得。 +**EmbeddingStore** - 埋め込みの保存と検索。 **MessageWindowChatMemory** - 最近のメッセージのスライディングウィンドウを維持。 -**PromptTemplate** - `{{variable}}` プレースホルダーを含む再利用可能なプロンプトを作成。 +**PromptTemplate** - `{{variable}}` プレースホルダーで再利用可能なプロンプトを作成。 **TextSegment** - メタデータ付きテキストチャンク。RAGで使用。 -**ToolExecutionRequest** - ツール実行リクエストを表現。 +**ToolExecutionRequest** - ツール実行リクエストを表す。 -**UserMessage / AiMessage / SystemMessage** - 会話メッセージのタイプ。 +**UserMessage / AiMessage / SystemMessage** - 会話メッセージの種類。 -## AI/ML 概念 +## AI/ML コンセプト -**Few-Shot Learning** - プロンプト内に例を提示。 [モジュール 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - プロンプトに例を提供。 [モジュール 02](../02-prompt-engineering/README.md) -**大規模言語モデル（LLM）** - 大量のテキストデータで訓練されたAIモデル。 +**大規模言語モデル (LLM)** - 大量のテキストデータで訓練されたAIモデル。 -**推論努力（Reasoning Effort）** - GPT-5.2のパラメータで思考の深さを制御。 [モジュール 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - GPT-5.2で思考の深さを制御するパラメーター。 [モジュール 02](../02-prompt-engineering/README.md) -**温度（Temperature）** - 出力のランダム性を制御。低=決定的、高=創造的。 +**Temperature** - 出力のランダム性を制御。低いと決定的、高いと創造的。 -**ベクトルデータベース** - 埋め込みに特化したデータベース。 [モジュール 03](../03-rag/README.md) +ベクターデータベース - 埋め込み用の特殊データベース。 [モジュール 03](../03-rag/README.md) -**Zero-Shot Learning** - 例なしでタスクを行うこと。 [モジュール 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - 例なしでタスクを実行。 [モジュール 02](../02-prompt-engineering/README.md) -## ガードレール - [モジュール 00](../00-quick-start/README.md) +## ガードレール -**多層防御（Defense in Depth）** - アプリケーションレベルのガードレールとプロバイダー安全フィルターを組み合わせた多層セキュリティアプローチ。 +**多層防御 (Defense in Depth)** - アプリケーションレベルのガードレールとプロバイダーのセーフティフィルターを組み合わせた多層セキュリティアプローチ。 -**ハードブロック** - 重大なコンテンツ違反に対しプロバイダーがHTTP 400エラーを返す。 +ハードブロック - 深刻なコンテンツ違反でプロバイダーがHTTP 400エラーを返す。 -**InputGuardrail** - LLMに到達する前のユーザー入力を検証するLangChain4jインターフェイス。危険なプロンプトを早期に遮断しコストと遅延を節約。 +**InputGuardrail** - LLMに到達する前にユーザー入力を検証するLangChain4jインターフェース。害のあるプロンプトを早期にブロックしコストと遅延を削減。 -**InputGuardrailResult** - ガードレール検証の返却型：`success()` または `fatal("理由")`。 +**InputGuardrailResult** - ガードレール検証の返却型：`success()` または `fatal("reason")`。 -**OutputGuardrail** - ユーザーに返す前にAI応答を検証するインターフェイス。 +**OutputGuardrail** - AIの応答をユーザーに返す前に検証するインターフェース。 -**プロバイダー安全フィルター** - AIプロバイダー（例：GitHub Models）がAPIレベルで違反を検出する組み込みコンテンツフィルター。 +プロバイダーセーフティフィルター - AIプロバイダー（例：Azure OpenAI）によるAPIレベルのコンテンツフィルター。 -**ソフト拒否（Soft Refusal）** - エラーを返さず丁寧に回答を控えるモデルの応答。 +ソフトリファーザル - モデルがエラーを出さず丁寧に回答を拒否。 ## プロンプトエンジニアリング - [モジュール 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - 正確性向上のための段階的推論。 +**Chain-of-Thought** - 精度向上のための段階的推論。 -**制約付き出力** - 特定の形式や構造を強制。 +制約付き出力 - 特定のフォーマットや構造の強制。 -**高熱意（High Eagerness）** - GPT-5.2 の徹底的な推論パターン。 +**高い熱意 (High Eagerness)** - GPT-5.2の徹底的推論パターン。 -**低熱意（Low Eagerness）** - GPT-5.2 の迅速な回答パターン。 +**低い熱意 (Low Eagerness)** - GPT-5.2の迅速な回答パターン。 -**マルチターン会話** - 複数回のやりとりでコンテキストを維持。 +マルチターン会話 - やり取り間でコンテキストを維持。 -**役割ベースプロンプティング** - システムメッセージでモデルのペルソナを設定。 +役割に基づくプロンプト - システムメッセージでモデルの人格を設定。 -**自己省察** - モデルが出力を評価・改善。 +自己反省 - モデルが自身の出力を評価・改善。 -**構造化分析** - 固定評価フレームワーク。 +構造化分析 - 固定評価フレームワーク。 -**タスク実行パターン** - 計画 → 実行 → 要約。 +タスク実行パターン - 計画 → 実行 → 要約。 -## RAG（検索拡張生成） - [モジュール 03](../03-rag/README.md) +## RAG (Retrieval-Augmented Generation) - [モジュール 03](../03-rag/README.md) -**文書処理パイプライン** - 読み込み → チャンク化 → 埋め込み → 保存。 +ドキュメント処理パイプライン - ロード → チャンク化 → 埋め込み → 保存。 -**インメモリ埋め込みストア** - 非永続的なテスト用ストレージ。 +インメモリ埋め込みストア - テスト用の非永続的ストレージ。 -**RAG** - 検索と生成を組み合わせて応答を根拠付ける。 +**RAG** - 検索と生成を組み合わせて応答を根拠づけ。 -**類似度スコア** - 意味的類似度の尺度（0～1）。 +類似度スコア - セマンティック類似度の尺度（0〜1）。 -**ソース参照** - 検索されたコンテンツのメタデータ。 +出典参照 - 取得したコンテンツのメタデータ。 ## エージェントとツール - [モジュール 04](../04-tools/README.md) @@ -140,63 +140,63 @@ **ReAct パターン** - 推論 → 行動 → 観察 → 繰り返し。 -**セッション管理** - ユーザーごとに異なるコンテキストを保持。 +セッション管理 - ユーザーごとに異なるコンテキストを分離。 -**ツール** - AIエージェントが呼べる関数。 +ツール - AIエージェントが呼び出せる関数。 -**ツール説明** - ツールの目的とパラメータのドキュメント。 +ツール説明 - ツールの目的とパラメーターのドキュメント。 -## エージェンティックモジュール - [モジュール 05](../05-mcp/README.md) +## エージェンシックモジュール - [モジュール 05](../05-mcp/README.md) -**@Agent アノテーション** - 宣言的な振る舞い定義でインターフェイスをAIエージェントとしてマーク。 +**@Agent アノテーション** - 宣言的な振る舞い定義でインターフェースをAIエージェントにマーク。 -**エージェントリスナー** - `beforeAgentInvocation()` と `afterAgentInvocation()` でエージェント実行を監視するフック。 +エージェントリスナー - `beforeAgentInvocation()` と `afterAgentInvocation()` でエージェント実行を監視するフック。 -**エージェンティックスコープ** - エージェントが `outputKey` を使って結果を保存し下流のエージェントが利用する共有メモリ。 +エージェンシックスコープ - エージェントが `outputKey` を使い出力を保存し、下流エージェントが利用する共有メモリ。 -**AgenticServices** - `agentBuilder()` と `supervisorBuilder()` を使ったエージェント作成用ファクトリ。 +**AgenticServices** - `agentBuilder()` と `supervisorBuilder()` でエージェント作成のファクトリ。 -**条件付きワークフロー** - 条件に基づき異なる専門エージェントにルーティング。 +条件付きワークフロー - 条件に基づき異なる専門エージェントへルーティング。 -**ヒューマン・イン・ザ・ループ** - 人間による承認やコンテンツレビューを加えるワークフローパターン。 +ヒューマンインザループ - 承認や内容確認のために人間のチェックポイントを加えるワークフローパターン。 -**langchain4j-agentic** - 宣言的エージェント構築用のMaven依存関係（実験的）。 +**langchain4j-agentic** - 宣言的エージェント構築のためのMaven依存関係（実験的）。 -**ループワークフロー** - 条件を満たすまでエージェント実行を繰り返す（例：品質スコア≥0.8）。 +ループワークフロー - 品質スコア ≥ 0.8 などの条件を満たすまでエージェント実行を繰り返し。 -**outputKey** - エージェントアノテーションパラメータでエージェンティックスコープ内の結果保存場所を指定。 +**outputKey** - エージェントアノテーションのパラメーターで、結果をエージェンシックスコープに保存する場所を指定。 -**並列ワークフロー** - 複数エージェントを同時に実行し独立タスクを処理。 +並列ワークフロー - 複数エージェントを同時に実行し独立したタスクを処理。 -**応答戦略** - スーパーバイザーが最終回答を形成する方法：LAST, SUMMARY, または SCORED。 +応答戦略 - スーパーバイザーが最終回答を形成する方法：LAST、SUMMARY、または SCORED。 -**逐次ワークフロー** - 順番にエージェントを実行し出力を次に渡す。 +逐次ワークフロー - エージェントを順番に実行し、出力が次のステップへ流れる。 -**スーパーバイザーエージェントパターン** - スーパーバイザーLLMが動的に呼び出すサブエージェントを決定する高度なエージェンティックパターン。 +スーパーバイザーエージェントパターン - スーパーバイザーLLMがサブエージェントの呼び出しを動的に決定する高度なエージェンシックパターン。 -## モデルコンテキストプロトコル（MCP） - [モジュール 05](../05-mcp/README.md) +## モデルコンテキストプロトコル (MCP) - [モジュール 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4jのMCP統合用Maven依存関係。 +**langchain4j-mcp** - LangChain4jでのMCP統合用Maven依存関係。 -**MCP** - モデルコンテキストプロトコル：AIアプリと外部ツールを接続するための標準。1回構築すればどこでも使用可能。 +**MCP** - Model Context Protocol：AIアプリを外部ツールに接続する標準。一度構築すればどこでも利用可能。 -**MCP クライアント** - MCPサーバーに接続しツールを発見・使用するアプリケーション。 +**MCPクライアント** - MCPサーバーに接続してツールを発見・利用するアプリケーション。 -**MCP サーバー** - MCP経由でツールを公開し説明とパラメータスキーマを提供するサービス。 +**MCPサーバー** - MCPでツールを公開し、明確な説明とパラメータスキーマを提供するサービス。 -**McpToolProvider** - LangChain4jのコンポーネントでMCPツールをラップしAIサービスやエージェントで使用。 +**McpToolProvider** - MCPツールをラップしてAIサービスやエージェントで使用可能にするLangChain4jコンポーネント。 -**McpTransport** - MCP通信のインターフェイス。実装例にStdioやHTTPがある。 +**McpTransport** - MCP通信のためのインターフェース。StdioやHTTPなどの実装あり。 -**Stdio トランスポート** - stdin/stdout経由のローカルプロセス通信。ファイルシステムアクセスやコマンドラインツールに便利。 +**Stdio トランスポート** - stdin/stdoutを用いたローカルプロセストランスポート。ファイルシステムアクセスやCLIツールに有用。 -**StdioMcpTransport** - LangChain4jがMCPサーバーをサブプロセスとして起動する実装。 +**StdioMcpTransport** - MCPサーバーをサブプロセスとして起動するLangChain4jの実装。 -**ツール発見** - クライアントがサーバーへ利用可能ツールの説明やスキーマを問い合わせ。 +ツール発見 - クライアントがサーバーに利用可能ツールの説明とスキーマを問い合わせる。 ## Azure サービス - [モジュール 01](../01-introduction/README.md) -**Azure AI Search** - ベクトル機能を備えたクラウド検索。 [モジュール 03](../03-rag/README.md) +**Azure AI Search** - ベクター機能付きクラウド検索。 [モジュール 03](../03-rag/README.md) **Azure Developer CLI (azd)** - Azureリソースのデプロイツール。 @@ -204,29 +204,27 @@ **Bicep** - Azureのインフラコード言語。 [インフラガイド](../01-introduction/infra/README.md) -**デプロイメント名** - Azureにおけるモデルデプロイの名前。 +デプロイメント名 - Azureでのモデルデプロイ名。 **GPT-5.2** - 推論制御機能を備えた最新のOpenAIモデル。 [モジュール 02](../02-prompt-engineering/README.md) -## テストと開発 - [テストガイド](TESTING.md) +## テストおよび開発 - [テストガイド](TESTING.md) -**Dev Container** - コンテナ化された開発環境。 [設定](../../../.devcontainer/devcontainer.json) +**Devコンテナ** - コンテナ化された開発環境。 [設定](../../../.devcontainer/devcontainer.json) -**GitHub Models** - 無償のAIモデルプレイグラウンド。 [モジュール 00](../00-quick-start/README.md) +インメモリテスト - インメモリストレージを使ったテスト。 -**インメモリテスト** - インメモリストレージを用いたテスト。 +統合テスト - 実インフラを用いたテスト。 -**統合テスト** - 実インフラを用いたテスト。 +**Maven** - Javaのビルド自動化ツール。 -**Maven** - Java用ビルド自動化ツール。 - -**Mockito** - Javaモックフレームワーク。 +**Mockito** - Javaのモッキングフレームワーク。 **Spring Boot** - Javaアプリケーションフレームワーク。 [モジュール 01](../01-introduction/README.md) --- -**免責事項**： -本書類はAI翻訳サービス「[Co-op Translator](https://github.com/Azure/co-op-translator)」を使用して翻訳されています。正確性の向上に努めておりますが、自動翻訳には誤りや不正確な箇所が含まれる可能性があります。原文が正本としての権威ある資料とみなされます。重要な情報については、専門の人間翻訳を推奨します。本翻訳の利用により生じたいかなる誤解や誤訳についても、当方は一切の責任を負いかねます。 - +**免責事項**： +本書類は AI 翻訳サービス [Co-op Translator](https://github.com/Azure/co-op-translator) を使用して翻訳されています。正確性を期していますが、自動翻訳には誤りや不正確な部分が含まれる可能性があることをご承知おきください。原文の原語版が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じたいかなる誤解や解釈違いについても、当方は責任を負いかねます。 + \ No newline at end of file diff --git a/translations/ja/docs/TESTING.md b/translations/ja/docs/TESTING.md index 6ec0cb12f..3b459a211 100644 --- a/translations/ja/docs/TESTING.md +++ b/translations/ja/docs/TESTING.md @@ -2,19 +2,19 @@ ## 目次 -- [クイックスタート](../../../docs) -- [テストの対象範囲](../../../docs) -- [テストの実行](../../../docs) -- [VS Codeでのテスト実行](../../../docs) -- [テストパターン](../../../docs) -- [テスト哲学](../../../docs) -- [次のステップ](../../../docs) +- [クイックスタート](#クイックスタート) +- [テストの対象](#テストの対象) +- [テストの実行](#テストの実行) +- [VS Codeでのテスト実行](#vs-codeでのテスト実行) +- [テストパターン](#テストパターン) +- [テスト哲学](#テスト哲学) +- [次のステップ](#次のステップ) -このガイドでは、APIキーや外部サービスを必要とせずにAIアプリケーションをテストする方法を示すテストを通じて説明します。 +このガイドでは、APIキーや外部サービスを必要とせずにAIアプリケーションをテストする方法を示すテストについて説明します。 ## クイックスタート -以下のコマンドで全テストを実行します： +すべてのテストを一つのコマンドで実行します： **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -すべてのテストが成功すると、以下のスクリーンショットのようにゼロの失敗で実行されます。 +すべてのテストが成功すると、以下のスクリーンショットのように、失敗ゼロでテストが完了した出力が表示されます。 Successful Test Results -*全テストが失敗なく成功した実行結果の例* +すべてのテストが失敗ゼロで成功したテスト実行結果の例 -## テストの対象範囲 +## テストの対象 -このコースはローカルで実行される**ユニットテスト**に焦点を当てています。それぞれのテストはLangChain4jの特定の概念を単体で示します。以下のテストピラミッドはユニットテストの位置付けを示しており、テスト戦略の基盤となる高速かつ信頼できるものです。 +このコースはローカルで実行される単体テストに焦点を当てています。各テストはLangChain4jの特定の概念を単独で示しています。下のテストピラミッドは単体テストの位置付けを示しており、高速かつ信頼性が高い基盤として他のテスト戦略の土台となります。 Testing Pyramid -*ユニットテスト（高速で単体）、統合テスト（実際のコンポーネント）、エンドツーエンドテストのバランスを示すテストピラミッド。このトレーニングはユニットテストを扱っています。* +*単体テスト（高速、孤立的）、統合テスト（実際のコンポーネント）、エンドツーエンドテストのバランスを示すテストピラミッド。このトレーニングでは単体テストを扱います。* -| モジュール | テスト数 | フォーカス | 主要ファイル | +| モジュール | テスト数 | 焦点 | 主なファイル | |--------|-------|-------|-----------| -| **00 - クイックスタート** | 6 | プロンプトテンプレートと変数置換 | `SimpleQuickStartTest.java` | -| **01 - はじめに** | 8 | 会話メモリと状態を持つチャット | `SimpleConversationTest.java` | -| **02 - プロンプトエンジニアリング** | 12 | GPT-5.2パターン、熱意レベル、構造化出力 | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | ドキュメント取り込み、埋め込み、類似検索 | `DocumentServiceTest.java` | -| **04 - ツール** | 12 | 関数呼び出しとツールの連結 | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Stdioトランスポートによるモデルコンテキストプロトコル | `SimpleMcpTest.java` | +| **01 - Introduction** | 8 | 会話のメモリと状態を持つチャット | `SimpleConversationTest.java` | +| **02 - Prompt Engineering** | 12 | GPT-5.2パターン、熱意レベル、構造化出力 | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | ドキュメント取込、埋め込み、類似検索 | `DocumentServiceTest.java` | +| **04 - Tools** | 12 | 関数呼び出しとツール連結 | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Stdioトランスポートを用いたModel Context Protocol | `SimpleMcpTest.java` | ## テストの実行 -**ルートから全テストを実行：** +**ルートからすべてのテストを実行：** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**特定モジュールのテストを実行：** +**特定のモジュールのテストを実行：** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**単一テストクラスの実行：** +**単一のテストクラスを実行：** **Bash:** ```bash @@ -95,41 +94,41 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#会話履歴を維持するべきか +mvn test -Dtest=SimpleConversationTest#会話履歴を維持する必要があります ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#会話履歴を維持すべきか +mvn --% test -Dtest=SimpleConversationTest#会話履歴を維持する必要があります ``` ## VS Codeでのテスト実行 -Visual Studio Codeを使用している場合、Test Explorerはテストの実行やデバッグをグラフィカルに行うインターフェースを提供します。 +Visual Studio Codeを使用している場合、Test Explorerがテストの実行とデバッグのためのグラフィカルなインターフェースを提供します。 VS Code Test Explorer -*すべてのJavaテストクラスおよび個別のテストメソッドを表示したVS Code Test Explorerのテストツリー* +*すべてのJavaテストクラスと個別のテストメソッドが表示されたVS CodeのTest Explorerのテストツリー* **VS Codeでテストを実行するには：** 1. アクティビティバーのフラスコアイコンをクリックしてTest Explorerを開く -2. テストツリーを展開してすべてのモジュールとテストクラスを確認 -3. 任意のテスト横の再生ボタンをクリックして単独で実行 +2. テストツリーを展開してモジュールとテストクラスを確認 +3. 任意のテストの再生ボタンをクリックして個別に実行 4. 「Run All Tests」をクリックして全テストを実行 -5. 任意のテストを右クリックして「Debug Test」を選択し、ブレークポイントを設定してコードをステップ実行 +5. 任意のテストを右クリックし「Debug Test」を選択してブレークポイントを設定し、コードをステップ実行可能 -Test Explorerは成功したテストに緑のチェックマークを表示し、失敗時には詳細なエラーメッセージを提供します。 +テストが成功するとTest Explorerに緑のチェックマークが表示され、失敗すると詳細な失敗メッセージが表示されます。 ## テストパターン ### パターン1：プロンプトテンプレートのテスト -最も単純なパターンは、AIモデルを呼び出さずにプロンプトテンプレートをテストします。変数置換が正しく機能し、期待した形式でプロンプトが生成されることを検証します。 +最も単純なパターンはAIモデルを呼び出さずにプロンプトテンプレートをテストするものです。変数の置換が正しく動作し、プロンプトが期待通りにフォーマットされていることを検証します。 Prompt Template Testing -*変数置換の流れを示すプロンプトテンプレートのテスト：プレースホルダー付きテンプレート → 値の適用 → フォーマット済み出力の検証* +*プレースホルダーのあるテンプレート→値の適用→フォーマットされた出力の検証という変数置換の流れを示すプロンプトテンプレートのテスト* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -このテストは `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` にあります。 +このパターンは変数の置換が正しく機能し、プロンプトが期待通りにフォーマットされることを検証します。APIキーやモデル呼び出しは不要です。 -**実行方法：** +### パターン2：言語モデルのモッキング -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#テストプロンプトテンプレートのフォーマット -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatting -``` - -### パターン2：言語モデルのモック - -会話ロジックをテストする際は、Mockitoを使ってあらかじめ決められた応答を返す偽モデルを作成します。これによりテストは高速かつ無料で決定論的に実行できます。 +会話ロジックをテストするときは、Mockitoを使ってあらかじめ決まった応答を返すフェイクモデルを作成します。これによりテストが高速、無料、決定論的になります。 Mock vs Real API Comparison -*テストにモックが推奨される理由を示す比較：高速、無料、決定論的、APIキー不要* +*モックがテストに適している理由を示す比較：高速、無料、決定論的でAPIキー不要* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3ユーザー + 3 AIメッセージ + assertThat(history).hasSize(6); // 3つのユーザーと3つのAIメッセージ } } ``` -このパターンは `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` にあります。モックにより一貫した動作が保証され、メモリ管理が正しく動くか検証可能です。 +このパターンは `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` に現れます。モックにより一貫した動作が保証され、メモリ管理が正しく動作することを検証可能です。 -### パターン3：会話の分離テスト +### パターン3：会話の隔離テスト -会話メモリは複数ユーザーを分けて管理しなければなりません。このテストは会話の文脈が混ざらないことを確認します。 +会話のメモリは複数ユーザーを区別する必要があります。このテストは会話がコンテキストを混同しないことを検証します。 Conversation Isolation -*異なるユーザーのためにメモリストアを分離し文脈の混合を防ぐ会話分離テスト* +*異なるユーザーのために分離されたメモリストアを示し、コンテキスト混入を防ぐ会話隔離のテスト* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -それぞれの会話は独立した履歴を保持します。実際のシステムでは、この分離がマルチユーザー環境で非常に重要です。 +各会話は独立した履歴を保持します。本番システムではこの隔離がマルチユーザーアプリケーションに不可欠です。 -### パターン4：ツールの単独テスト +### パターン4：ツールの独立テスト -ツールはAIが呼び出せる関数です。AIの判断に関わらず正しく動作するか、直接テストします。 +ツールはAIが呼び出す関数です。AIの判断に関わらず正しく動作することを直接テストします。 Tools Testing -*AI呼び出しなしでモックツールを実行し、ビジネスロジックを検証するツールの単独テスト* +*ビジネスロジックを検証するためにAI呼び出しなしでモックツールを実行するツールの独立テスト* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -これらのテストは `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` にあり、AIの関与なしでツールロジックを検証します。連結例では一つのツールの出力を別のツールの入力として渡します。 +これらのテストは `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` にあり、AIを介さずにツールロジックの検証を行います。チェイン例では一つのツールの出力が他の入力になる様子を示します。 ### パターン5：インメモリRAGテスト -RAGシステムは通常ベクトルデータベースや埋め込みサービスを必要としますが、インメモリパターンなら外部依存なしにパイプライン全体をテストできます。 +RAGシステムは通常ベクターデータベースや埋め込みサービスを必要とします。インメモリパターンを使うと外部依存なしにパイプライン全体をテストできます。 In-Memory RAG Testing -*データベース不要でドキュメント解析、埋め込み保存、類似検索を行うインメモリRAGテストのワークフロー* +*ドキュメント解析、埋め込み格納、類似検索がデータベース不要で行われるインメモリRAGテストのワークフロー* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -このテストは `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` にあり、メモリ内にドキュメントを作成してチャンク分割やメタデータ処理を検証します。 +このテストは `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` にあり、メモリ内でドキュメントを作成しチャンク分割とメタデータ処理を検証します。 ### パターン6：MCP統合テスト -MCPモジュールはstdioトランスポートを使ったモデルコンテキストプロトコルの統合をテストします。これらのテストはMCPサーバーをサブプロセスとして起動し通信できるか検証します。 +MCPモジュールはstdioトランスポートを用いたModel Context Protocolの統合をテストします。これらのテストではアプリケーションがMCPサーバーをサブプロセスとして起動し通信可能か検証します。 -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` のテストコードがMCPクライアントの挙動をチェックします。 +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` のテストがMCPクライアントの動作を検証します。 -**実行方法：** +**実行コマンド：** **Bash:** ```bash @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## テスト哲学 -AIをテストするのではなく、コードをテストしましょう。テストは、プロンプトの構成方法、メモリ管理、ツールの実行を検証するために書いた自分のコードを評価すべきです。AIの回答は変動するため、テストの検証に含めてはいけません。プロンプトテンプレートが変数を正しく置換できているかを問うべきで、AIが正しい回答を返すかは問いません。 +AIではなくコードをテストしましょう。テストはプロンプト構築やメモリ管理、ツールの実行を検証するためのものです。AIの応答は変動するためテストアサーションに含めるべきではありません。プロンプトテンプレートが正しく変数を置換するかを検証し、AIが正解を出すかは問いません。 -言語モデルにはモックを使いましょう。言語モデルは遅く、コストがかかり、決定論的でない外部依存です。モックを使うことでテストはミリ秒単位の高速さ、APIコスト不要の無料、毎回同じ結果を返す決定論的なものになります。 +言語モデルはモックを使いましょう。言語モデルは外部依存であり遅く、高価で、非決定論的です。モックを使うことでテストはミリ秒単位で高速に、料金も発生せず、毎回同じ結果が得られます。 -テストは独立させましょう。各テストは自身でデータをセットアップし、他のテストに依存せず、後始末を行うべきです。テストの実行順に関わらず成功する必要があります。 +テストは独立させましょう。各テストは自身のデータを設定し、他のテストに依存せず、自分で後始末を行います。実行順に関係なく通るべきです。 -正常系以外の境界ケースもテストしましょう。空入力、非常に大きな入力、特殊文字、無効なパラメータ、境界条件などを試してください。これらは通常の利用では見つからないバグを発見することがあります。 +正常系以外もテストしましょう。空入力や非常に大きな入力、特殊文字、無効パラメータ、境界条件などを試します。これらは通常の使用では見つからないバグを露呈します。 -分かりやすい名前を使いましょう。`shouldMaintainConversationHistoryAcrossMultipleMessages()` と `test1()` を比べてください。前者は何をテストしているかすぐ分かり、失敗時のデバッグも容易です。 +説明的な名前を使いましょう。`shouldMaintainConversationHistoryAcrossMultipleMessages()` と `test1()` を比べると、前者は何を検証しているかが明確で、失敗時のデバッグがはるかに楽です。 ## 次のステップ -これらのテストパターンを理解したら、各モジュールをさらに深く学んでいきましょう： +テストパターンを理解したら、各モジュールの詳細に進みましょう： -- **[00 - クイックスタート](../00-quick-start/README.md)** - プロンプトテンプレートの基礎を開始 -- **[01 - はじめに](../01-introduction/README.md)** - 会話メモリ管理を学ぶ -- **[02 - プロンプトエンジニアリング](../02-prompt-engineering/README.md)** - GPT-5.2のプロンプトパターンをマスター -- **[03 - RAG](../03-rag/README.md)** - 検索強化生成システムを構築 -- **[04 - ツール](../04-tools/README.md)** - 関数呼び出しとツールチェーンを実装 -- **[05 - MCP](../05-mcp/README.md)** - モデルコンテキストプロトコルを統合 +- **[01 - Introduction](../01-introduction/README.md)** - 会話メモリ管理の学習 +- **[02 - Prompt Engineering](../02/prompt-engineering/README.md)** - GPT-5.2のプロンプトパターン習得 +- **[03 - RAG](../03-rag/README.md)** - 検索強化生成システムの構築 +- **[04 - Tools](../04-tools/README.md)** - 関数呼び出しとツールチェーンの実装 +- **[05 - MCP](../05-mcp/README.md)** - Model Context Protocolの統合 -各モジュールのREADMEではここで扱った概念の詳細説明が提供されています。 +各モジュールのREADMEにはここでテストした概念の詳細な説明が記載されています。 --- @@ -358,6 +344,6 @@ AIをテストするのではなく、コードをテストしましょう。テ --- -**免責事項**： -本書類はAI翻訳サービス[Co-op Translator](https://github.com/Azure/co-op-translator)を使用して翻訳されました。正確性には努めておりますが、自動翻訳には誤りや不正確な部分が含まれる可能性があります。原文の言語によるオリジナル文書を正式な情報源としてください。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じる誤解や誤った解釈について、当方は一切責任を負いかねます。 +**免責事項**： +本書類は AI 翻訳サービス [Co-op Translator](https://github.com/Azure/co-op-translator) を使用して翻訳されています。正確性を期していますが、自動翻訳には誤りや不正確な部分が含まれる可能性があることをご承知おきください。原文の原語版が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳を推奨します。本翻訳の利用により生じたいかなる誤解や解釈違いについても、当方は責任を負いかねます。 \ No newline at end of file diff --git a/translations/km/.co-op-translator.json b/translations/km/.co-op-translator.json index 9be86ed9d..8d712866a 100644 --- a/translations/km/.co-op-translator.json +++ b/translations/km/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "km" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-04-06T16:23:52+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T13:33:14+00:00", "source_file": "01-introduction/README.md", "language_code": "km" }, @@ -18,20 +18,20 @@ "language_code": "km" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-04-06T16:29:14+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T13:27:09+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "km" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-04-06T16:31:53+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T13:32:02+00:00", "source_file": "03-rag/README.md", "language_code": "km" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-04-06T16:37:38+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T13:30:16+00:00", "source_file": "04-tools/README.md", "language_code": "km" }, @@ -54,8 +54,8 @@ "language_code": "km" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:21:59+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T13:25:04+00:00", "source_file": "README.md", "language_code": "km" }, @@ -72,14 +72,14 @@ "language_code": "km" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-04-06T16:39:04+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T13:27:58+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "km" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-04-06T16:40:32+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T13:28:36+00:00", "source_file": "docs/TESTING.md", "language_code": "km" } diff --git a/translations/km/00-quick-start/README.md b/translations/km/00-quick-start/README.md deleted file mode 100644 index 32f3b8deb..000000000 --- a/translations/km/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# ម៉ូឌុល 00: ចាប់ផ្តើមរហ័ស - -## តារាងមាតិកា - -- [ការណែនាំ](#ការណែនាំ) -- [LangChain4j ជាអ្វី?](#langchain4j-ជាអ្វី) -- [ការពឹងផ្អែក LangChain4j](#ការពឹងផ្អែក-langchain4j) -- [លក្ខខណ្ឌមុន](#លក្ខខណ្ឌមុន) -- [ការតំឡើង](#ការតំឡើង) - - [1. ទទួលបាន Token GitHub របស់អ្នក](#1-ទទួលបាន-token-github-របស់អ្នក) - - [2. កំណត់ Token របស់អ្នក](#2-កំណត់-token-របស់អ្នក) -- [រត់ឧទាហរណ៍](#រត់ឧទាហរណ៍) - - [1. ជជែកមូលដ្ឋាន](#1-ជជែកមូលដ្ឋាន) - - [2. គំរូ Prompt](#2-គំរូ-prompt) - - [3. ការហៅមុខងារ](#3-ការហៅមុខងារ) - - [4. សំណួរ-ចម្លើយឯកសារ (Easy RAG)](#4-សំណួរ-ចម្លើយឯកសារ-easy-rag) - - [5. ដំណើរការយ៉ាងទទួលខុសត្រូវ](#5-ដំណើរការយ៉ាងទទួលខុសត្រូវ) -- [អ្វីដែលឧទាហរណ៍នីមួយៗបង្ហាញ](#អ្វីដែលឧទាហរណ៍នីមួយៗបង្ហាញ) -- [ជំហានបន្ទាប់](#ជំហានបន្ទាប់) -- [ដំណោះស្រាយបញ្ហា](#ដំណោះស្រាយបញ្ហា) - -## ការណែនាំ - -ការចាប់ផ្តើមរហ័សនេះមានគោលបំណងឲ្យអ្នកអាចប្រើ LangChain4j បានឆាប់រហ័សបំផុត។ វាមានប៉ុណ្ណោះជាផ្នែកមូលដ្ឋាននៃការលាយបញ្ចូលកម្មវិធី AI ជាមួយ LangChain4j និង GitHub Models។ នៅក្នុងម៉ូឌុលបន្ទាប់ អ្នកនឹងប្ដូរទៅ Azure OpenAI និង GPT-5.2 ហើយជ្រៀតជ្រែកជ្រៅជាងនីមួយៗ។ - -## LangChain4j ជាអ្វី? - -LangChain4j គឺជាបណ្ណាល័យ Java ដែលធ្វើឲ្យការសាងសង់កម្មវិធីដែលផ្គត់ផ្គង់ដោយ AI កាន់តែងាយស្រួល។ ជំនួសការដោះស្រាយអតិថិជន HTTP និងការបកស្រាយ JSON អ្នកបម្រើជាមួយ API Java ស្អាតៗ។ - -"ខ្សែ" ក្នុង LangChain មានន័យថាការចងខ្សែរភ្ជាប់គ្នារវាងសមាសភាពជាច្រើន — អ្នកអាចចង prompt ទៅម៉ូឌែល ទៅ parser ឬចងកិច្ចហៅ AI ជាច្រើនរួមគ្នា ដែលលទ្ធផលមួយផ្គត់ផ្គង់ជា input បន្ទាប់។ ការចាប់ផ្តើមរហ័សនេះផ្តោតលើមូលដ្ឋានមុនពេលស្វែងយល់ខ្សែស្មុគស្មាញជាងនេះ។ - -LangChain4j Chaining Concept - -*ការចងខ្សែសមាសភាពក្នុង LangChain4j - ឧបករណ៍សង់ភាគហ៊ុនដែលភ្ជាប់គ្នាដើម្បីបង្កើតដំណើរការងារចំណី AI មានអំណាច* - -យើងនឹងប្រើរូបមន្តចម្បងបី៖ - -**ChatModel** - វិភាគសម្រាប់ការប្រាស្រ័យទាក់ទងជាមួយម៉ូឌែល AI។ ហៅ `model.chat("prompt")` ហើយទទួលបានខ្សែប្រែតប។ យើងប្រើ `OpenAiOfficialChatModel` ដែលដំណើរការជាមួយចំណុចបញ្ចូល OpenAI-compatible ដូចជា GitHub Models។ - -**AiServices** - បង្កើតចំណុចបម្រើ AI ផ្ទាល់ខ្លួន។ កំណត់វិធីសាស្រ្ត ដាក់ស្លាកជាមួយ `@Tool` ហើយ LangChain4j នឹងដោះស្រាយការរៀបចំអនុវត្តរបស់វា។ AI នឹងហៅវិធីសាស្រ្ត Java របស់អ្នកដោយស្វ័យប្រវត្តិពេលចាំបាច់។ - -**MessageWindowChatMemory** - រក្សាទុកប្រវត្តិជជែក។ ប្រសិនមិនមានវា សំណើរៀងរាល់សំណុំឯកសារតាំងឡាយដោយឯករាជ្យ។ មានវា AI នឹងចងចាំសារប្រកាសមុនៗ និងរក្សាបរិបទក្នុងច្រើនសកម្មភាពជន្ទល់។ - -LangChain4j Architecture - -*ស្ថាបត្យកម្ម LangChain4j - សមាសភាពស្នូលដំណើរការជាមួយគ្នាដើម្បីផ្គត់ផ្គង់កម្មវិធី AI របស់អ្នក* - -## ការពឹងផ្អែក LangChain4j - -ការចាប់ផ្តើមរហ័សនេះប្រើការពឹងផ្អែក Maven បីមុខក្នុង [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -ម៉ូឌុល `langchain4j-open-ai-official` ផ្គូផ្គងថ្នាក់ `OpenAiOfficialChatModel` ដែលភ្ជាប់ទៅ API មានលក្ខណៈ OpenAI-compatible។ GitHub Models ប្រើទ្រង់ទ្រាយ API ដូចគ្នា ដូច្នេះមិនចាំបាច់មាន adapter ពិសេសទេ — គ្រាន់តែបង្ហាញ URL មូលដ្ឋានទៅ `https://models.github.ai/inference` ។ - -ម៉ូឌុល `langchain4j-easy-rag` ផ្ដល់ជូនការបំបែកឯកសារដោយស្វ័យប្រវត្តិ ការបញ្ចូល embedding និងការដកយក retrieval ដូច្នេះអ្នកអាចសង់កម្មវិធី RAG បានដោយមិនត្រូវកំណត់ដៃរាល់ជំហានទេ។ - -## លក្ខខណ្ឌមុន - -**ប្រើ Dev Container?** Java និង Maven បានតំឡើងរួចជាស្រេច។ អ្នកត្រូវតែមានតែ Token Personal Access GitHub màng។ - -**ការអភិវឌ្ឍន៍ក្នុងតំបន់**៖ -- Java 21+, Maven 3.9+ -- Token Personal Access GitHub (សេចក្ដីណែនាំខាងក្រោម) - -> **សម្គាល់:** ម៉ូឌុលនេះប្រើ `gpt-4.1-nano` ពី GitHub Models។ កុំផ្លាស់ប្ដូរឈ្មោះម៉ូឌែលក្នុងកូដ - វាត្រូវបានកំណត់ជាស្រេចដើម្បីដំណើរការជាមួយម៉ូឌែលដែលមានក្នុង GitHub ។ - -## ការតំឡើង - -### 1. ទទួលបាន Token GitHub របស់អ្នក - -1. ទៅកាន់ [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. ចុច "Generate new token" -3. កំណត់ឈ្មោះពណ៌នា (ឧ. "LangChain4j Demo") -4. កំណត់កំណត់ថ្ងៃផុតកំណត់ (មូលដ្ឋាន 7ថ្ងៃ) -5. នៅក្រោម "Account permissions" រក "Models" និងកំណត់ទៅ "Read-only" -6. ចុច "Generate token" -7. ចម្លង និងរក្សាទុក token របស់អ្នក — វានឹងមិនបង្ហាញឡើងវិញទេ - -### 2. កំណត់ Token របស់អ្នក - -**ជម្រើស 1: ប្រើ VS Code (យកអនុសាសន៍)** - -បើអ្នកប្រើ VS Code បន្ថែម token របស់អ្នកទៅក្នុងឯកសារ `.env` នៅជម្រកគម្រោង៖ - -បើឯកសារ `.env` មិនមានទេ ចម្លង `.env.example` ទៅ `.env` ឬបង្កើតឯកសារ `.env` ថ្មីនៅជម្រកគម្រោង។ - -**ឧទាហរណ៍ឯកសារ `.env`:** -```bash -# នៅក្នុង /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -បន្ទាប់មកអ្នកអាចចុចស្ដាំលើឯកសារបង្ហាញ (ឧ. `BasicChatDemo.java`) នៅក្នុង Explorer ហើយជ្រើស **"Run Java"** ឬប្រើការកំណត់ការចាប់ផ្តើមពីផ្នែក Run and Debug។ - -**ជម្រើស 2: ប្រើ Terminal** - -កំណត់ token ជាអថេរស្ថានបរិយាកាស៖ - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## រត់ឧទាហរណ៍ - -**ប្រើ VS Code:** គ្រាន់តែចុចស្ដាំលើឯកសារបង្ហាញណាមួយនៅក្នុង Explorer ហើយជ្រើស **"Run Java"**, ឬប្រើកំណត់ចាប់ផ្តើមពីផ្នែក Run and Debug (ប្រាកដថាអ្នកបានបន្ថែម token ទៅឯកសារ `.env` មុននេះ)។ - -**ប្រើ Maven:** ជម្រើសផ្សេង៖ អ្នកអាចដំណើរការពីបន្ទាត់បញ្ជា៖ - -### 1. ជជែកមូលដ្ឋាន - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. គំរូ Prompt - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -បង្ហាញ zero-shot, few-shot, chain-of-thought, និង role-based prompting។ - -### 3. ការហៅមុខងារ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI នឹងហៅវិធីសាស្រ្ត Java របស់អ្នកដោយស្វ័យប្រវត្តិពេលត្រូវការ។ - -### 4. សំណួរ-ចម្លើយឯកសារ (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -សួរពីឯកសាររបស់អ្នកដោយប្រើ Easy RAG ជាមួយការបញ្ចូល embedding និង retrieval ដោយស្វ័យប្រវត្តិ។ - -### 5. ដំណើរការយ៉ាងទទួលខុសត្រូវ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -មើលវិធានការសុវត្ថិភាព AI ដែលបិទខ្លឹមសារមិនប្រក្រតី។ - -## អ្វីដែលឧទាហរណ៍នីមួយៗបង្ហាញ - -**ជជែកមូលដ្ឋាន** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -ចាប់ផ្តើមនៅទីនេះ ដើម្បីមើល LangChain4j ក្នុងរូបមន្តដ៏សាមញ្ញបំផុត។ អ្នកនឹងបង្កើត `OpenAiOfficialChatModel`, ផ្ញើ prompt ជាមួយ `.chat()`, ហើយទទួលការឆ្លើយតប។ នេះបង្ហាញមូលដ្ឋាន៖ របៀបចាប់ផ្តើមម៉ូឌែលជាមួយចំណុចបញ្ចូល និង API keys។ ពេលអ្នកយល់របៀបនេះ ប្រសិនបើអ្វីផ្សេងៗទៀតសំណង់លើវា។ - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) ហើយសួរ៖ -> - "តើខ្ញុំធ្វើដូចម្តេចប្ដូរពី GitHub Models ទៅ Azure OpenAI ក្នុងកូដនេះ?" -> - "តើមានប៉ារ៉ាម៉ែត្រាអ្វីផ្សេងទៀតដែលខ្ញុំអាចកំណត់ក្នុង OpenAiOfficialChatModel.builder()?" -> - "តើធ្វើដូចម្តេចដើម្បីបន្ថែម streaming responses រឿយៗ មិនបន្តរហូតទាល់តែបានចម្លើយពេញ?" - -**ការបង្កើត Prompt** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -ឥឡូវនេះដែលអ្នកបានដឹងរបៀបនិយាយទៅម៉ូឌែល ចាំមើលអ្វីដែលអ្នកនិយាយទៅវា។ ឧទាហរណ៍នេះប្រើវិធីសាស្រ្តម៉ូឌែលដដែល បង្ហាញគំរូ prompting ប្រាំផ្សេងគ្នា។ សាកល្បង zero-shot prompts សម្រាប់ការណែនាំផ្ទាល់, few-shot prompts ដែលរៀនពីគំរូ, chain-of-thought prompts ដែលបង្ហាញដំណាក់កាលគិត, និង role-based prompts ដែលកំណត់បរិបទ។ អ្នកនឹងឃើញម៉ូឌែលដដែលផ្ដល់លទ្ធផលខុសគ្នាយ៉ាងខ្លាំងផ្អែកលើរបៀបអ្នកកំណត់សំណើ។ - -ឧទាហរណ៍នេះក៏បង្ហាញសាច់រឿង prompt templates ដែលជាវិធីខ្លាំងមួយក្នុងការបង្កើត prompts ប្រើបានឡើងវិញជាមួយអថេរ។ -ឧទាហរណ៍ខាងក្រោមបង្ហាញ prompt ប្រើ `PromptTemplate` នៃ LangChain4j ដើម្បីបញ្ចូលអថេរ។ AI នឹងឆ្លើយតបផ្អែកលើចំណុចផ្នែក និងសកម្មភាពដែលបានផ្ដល់។ - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) ហើយសួរ៖ -> - "តើមានភាពខុសគ្នាអ្វីខ្លះរវាង zero-shot និង few-shot prompting ហើយពេលណាខ្ញុំគួរប្រើមួយ?" -> - "តើប៉ារ៉ាម៉ែត្រា temperature មានឥទ្ធិពលយ៉ាងដូចម្តេចលើយន្តការឆ្លើយតបរបស់ម៉ូឌែល?" -> - "តើមានវិធីសាស្រ្តអ្វីខ្លះដើម្បីទប់ស្កាត់ការវាយលុក prompt injection នៅក្នុងផលិតផល?" -> - "តើធ្វើដូចម្តេចដើម្បីបង្កើតអវត្តមាន PromptTemplate ដែលប្រើឡើងវិញសម្រាប់គំរូទូទៅ?" - -**ការតភ្ជាប់ឧបករណ៍** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -នេះជាកន្លែងដែល LangChain4j មានអំណាចខ្លាំង។ អ្នកនឹងប្រើ `AiServices` ដើម្បីបង្កើតជំនួយការមាន AI អាចហៅវិធីសាស្រ្ត Java របស់អ្នក។ គ្រាន់តែដាក់ស្លាកវិធីសាស្រ្តជាមួយ `@Tool("ពិពណ៌នា")` ហើយ LangChain4j នឹងដោះស្រាយអ្វីៗទាំងអស់ – AI ដឹងដោយស្វ័យប្រវត្តិពេលណាគួរប្រើឧបករណ៍មួយៗ ដោយផ្អែកលើយុទ្ធសាស្រ្តដែលអ្នកសុំ។ វាបង្ហាញការហៅមុខងារ ដែលជាវិធីសាស្រ្តសំខាន់សម្រាប់សាងសង់ AI ដែលអាចធ្វើសកម្មភាព មិនមែនត្រឹមតែឆ្លើយសំណួរទេ។ - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ហើយសួរ៖ -> - "តើស្លាក @Tool ធ្វើការ​យ៉ាងដូចម្តេច ហើយ LangChain4j ធ្វើអ្វីជាមួយវានៅក្រោយដេគ័រ?" -> - "តើ AI អាចហៅឧបករណ៍ជាច្រើនជាទំរង់លំដាប់ដើម្បីដោះស្រាយបញ្ហាស្មុគស្មាញបានទេ?" -> - "តើមានអ្វីកើតឡើងបើឧបករណ៍បោះបង់ករណីកំហុស — តើខ្ញុំគួរដោះស្រាយកំហុសយ៉ាងដូចម្តេច?" -> - "តើធ្វើដូចម្តេចដើម្បីភ្ជាប់ API ពិតប្រាកដជំនួសឧទាហរណ៍ calculator នេះ?" - -**សំណួរ-ចម្លើយឯកសារ (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -នៅទីនេះ អ្នកនឹងឃើញ RAG (retrieval-augmented generation) ប្រើវិធីសាស្រ្ត "Easy RAG" របស់ LangChain4j។ ឯកសារត្រូវបានផ្ទុក ស្វ័យប្រវត្តិក្នុងការបំបែក និងបញ្ចូល embedding ទៅក្នុងឃ្លាំងក្នុងចិត្ត ហើយអ្នកប្រើ content retriever ផ្ដល់ផ្នែកទាក់ទងទៅ AI ពេលសួរ។ AI ឆ្លើយតបផ្អែកលើឯកសាររបស់អ្នក មិនមែនជាលទ្ធផលទូទៅសម្រាប់ចំណេះដឹងទេ។ - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) ហើយសួរ៖ -> - "តើ RAG ធ្វើដូចម្តេចដើម្បីទប់ស្កាត់ការត្រលប់មិនពិតរបស់ AI ប្រសិនបើប្រៀបធៀបនឹងប្រើទិន្នន័យបណ្ដុះបណ្ដាលរបស់ម៉ូឌែល?" -> - "តើភាពខុសគ្នាអ្វីខ្លះរវាងវិធីសាស្រ្តងាយៗនេះ និងបាញ់ RAG ផ្ទាល់ខ្លួន?" -> - "តើធ្វើដូចម្តេចដើម្បីពង្រីកវាដើម្បីគ្រប់គ្រងឯកសារច្រើន ឬមូលដ្ឋានចំណេះដឹងធំ?" - -**ដំណើរការយ៉ាងទទួលខុសត្រូវ** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -សាងសង់សុវត្ថិភាព AI ជាមួយការពារផ្នែកជាច្រើន។ ឧទាហរណ៍នេះបង្ហាញពីការការពារមានស្រទាប់ពីរដោយដំណើរការជាមួយគ្នា៖ - -**ផ្នែកទី 1: LangChain4j Input Guardrails** - បិទសារ prompt ដែលធ្វើអាក្រក់មុនពួកវាចូលដល់ LLM។ បង្កើត guardrails ផ្ទាល់ខ្លួនដែលត្រួតពិនិត្យពាក្យគន្លឹះ ឬគំរូហាមឃាត់។ វាត្រូវបានរត់ក្នុងកូដរបស់អ្នក ដូច្នេះវារហ័ស និងឥតគិតថ្លៃ។ - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**ផ្នែកទី 2: Provider Safety Filters** - GitHub Models មានថ្នាក់រាំងខ្ទប់ដែលចាប់អ្វីដែល guardrails របស់អ្នកអាចខកខាន។ អ្នកនឹងឃើញការរាំងខ្ទប់តឹង (កំហុស HTTP 400) សម្រាប់ការរាំងខ្ទប់ធ្ងន់ធ្ងរ និងការល៉ែងបំលែងដោយទោសដែល AI រំលងដោយសុភាព។ - -> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) ហើយសួរ៖ -> - "InputGuardrail ជាអ្វី ហើយធ្វើដូចម្តេចដើម្បីបង្កើតរបស់ខ្លួន?" -> - "ភាពខុសគ្នារវាងការរាំងខ្ទបតឹង និងការលោតត្រឡប់ ស្ថិតនៅណា?" -> - "ហេតុអ្វីបានជាប្រើ guardrails និង filters រួមគ្នា?" - -## ជំហានបន្ទាប់ - -**ម៉ូឌុលបន្ទាប់៖** [01-introduction - Getting Started with LangChain4j](../01-introduction/README.md) - ---- - -**ការរុករក៖** [← ត្រឡប់ទៅមុខចម្បង](../README.md) | [បន្ទាប់៖ ម៉ូឌុល 01 - ការណែនាំ →](../01-introduction/README.md) - ---- - -## ដំណោះស្រាយបញ្ហា - -### សំណុំ Maven ដំបូង - -**បញ្ហា**: `mvn clean compile` ឬ `mvn package` ដំបូងចំណាយពេលយូរ (១០-១៥ នាទី) - -**មូលហេតុ**: Maven ត្រូវការទាញទាញការពឹងផ្អែកគ្រប់យ៉ាង (Spring Boot, បណ្ណាល័យ LangChain4j, Azure SDKs, ល) នៅលើសំណុំដំបូង។ - -**ដំណោះស្រាយ**: នេះគឺជា​ជំនួសធម្មតា។ ការស្នើរសុំបន្ទាប់នឹងរហ័សជាង ចំពោះសារព័ត៌មានដែលបានរក្សាទុកក្នុងតំបន់។ ពេលទាញយកអាស្រ័យលើល្បឿនបណ្ដាញរបស់អ្នក។ - -### ពាក្យបញ្ជា Maven របស់ PowerShell - -**បញ្ហា**: ពាក្យបញ្ជា Maven បរាជ័យជាមួយកំហុស `Unknown lifecycle phase ".mainClass=..."` -**មូលហេតុ**: PowerShell ពិចារណាពាក្យ `=` ជាអ្នកប្រតិបត្តិការចាត់ចែងអថេរ ដែលបំបែកវាក្យសម្ព័ន្ធគុណលក្ខណៈ Maven - -**ដំណោះស្រាយ**: ប្រើតួអក្សរស្រើបចាប់ parsing `--%` មុនពាក្យបញ្ជា Maven៖ - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -តួអក្សរ `--%` ប្រាប់ PowerShell អោយបញ្ជូនអាគុយម៉ង់ដែលនៅសល់ទាំងអស់ទៅ Maven ដោយផ្ទាល់ដោយគ្មានការបកស្រាយ។ - -### ការបង្ហាញអេម៉ូជី Windows PowerShell - -**បញ្ហា**: ការឆ្លើយតបទៅ AI បង្ហាញអක្សរច្រាសចរ (ឧ. `????` ឬ `â??`) ជំនួសអេម៉ូជីនៅ PowerShell - -**មូលហេតុ**: ការអ៊ិនកូដលំនាំដើមរបស់ PowerShell មិនគាំទ្រអេម៉ូជី UTF-8 ទេ - -**ដំណោះស្រាយ**: រត់ពាក្យបញ្ជានេះមុនពេលបញ្ចូលកម្មវិធី Java: -```cmd -chcp 65001 -``` - -នេះបង្ខំអោយមានការអ៊ិនកូដ UTF-8 នៅក្នុងទ терминាល់។ ជាជម្រើស វាអាចប្រើ Windows Terminal ដែលមានការគាំទ្រអក្សរយូនីកូដល្អជាង។ - -### ការបញ្ឆិត API Calls - -**បញ្ហា**: កំហុសការផ្ទៀងផ្ទាត់ អត្រាកំណត់ ឬការឆ្លើយតបមិនរំពឹងទុកពីម៉ូដែល AI - -**ដំណោះស្រាយ**: ឧទាហរណ៍មាន `.logRequests(true)` និង `.logResponses(true)` ដើម្បីបង្ហាញការហៅ API នៅ console។ វាជួយក្នុងការបញ្ឆិតកំហុសផ្ទៀងផ្ទាត់ អត្រាកំណត់ ឬការឆ្លើយតបមិនរំពឹងទុក។ ដកចេញប៊្លាស់ទាំងនេះនៅពេលផលិតកម្មដើម្បីកាត់បន្ថយសំឡេងកំណត់ហេតុ។ - ---- - - -**ការបដិសេធ**៖ -ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាបកប្រែកម្មវិធី AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទាំងដែលយើងខិតខំសំរាប់ភាពត្រឹមត្រូវ សូមយល់ឱ្យបានថាការបកប្រែកម្មវិធីដោយស្វ័យប្រវត្តិអាចមានកំហុស ឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមនៅក្នុងភាសាតំបន់របស់ខ្លួនគួរត្រូវបានឱ្យភាពមានសុពលភាពជាផ្លូវការបំផុត។ សម្រាប់ព័ត៌មានសំខាន់ៗ សំណូមពរបកប្រែដោយអ្នកជំនាញដែលមានជំនាញមនុស្សត្រូវបានណែនាំ។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការប្រែប្រាស់យ៉ាងមិនត្រឹមត្រូវណាមួយដែលកើតឡើងពីការប្រើប្រាស់ការបកប្រែនេះឡើយ។ - \ No newline at end of file diff --git a/translations/km/01-introduction/README.md b/translations/km/01-introduction/README.md index f2451698f..61f9b536c 100644 --- a/translations/km/01-introduction/README.md +++ b/translations/km/01-introduction/README.md @@ -1,87 +1,87 @@ -# មេឌុល ០១៖ ការចាប់ផ្តើមជាមួយ LangChain4j +# Module 01: ការចាប់ផ្តើមជាមួយ LangChain4j -## តារាងមាតិការណ៍ +## តារាងមាតិកា -- [វីដេអូបង្ហាញ](#វីដេអូបង្ហាញ) +- [ការបង្ហាញវីដេអូ](#ការបង្ហាញវីដេអូ) - [អ្វីដែលអ្នកនឹងរៀន](#អ្វីដែលអ្នកនឹងរៀន) -- [លក្ខខណ្ឌមុន](#លក្ខខណ្ឌមុន) -- [ការយល់ដឹងអំពីបញ្ហាគ្រឹះ](#ការយល់ដឹងអំពីបញ្ហាគ្រឹះ) -- [ការយល់ដឹងអំពីសញ្ញាសំគាល់](#ការយល់ដឹងអំពីសញ្ញាសំគាល់) -- [របៀបដំណើរការមេមឺរី](#របៀបដំណើរការមេមឺរី) -- [របៀបដែលនេះប្រើ LangChain4j](#របៀបដែលនេះប្រើ-langchain4j) -- [ចាត់ចែង និងដាក់បញ្ចូលហេដ្ឋារចនាសម្ព័ន្ធ Azure OpenAI](#ចាត់ចែង-និងដាក់បញ្ចូលហេដ្ឋារចនាសម្ព័ន្ធ-azure-openai) -- [បើកដំណើរការ​កម្មវិធី​នៅ​តំបន់មូលដ្ឋាន](#បើកដំណើរការ​កម្មវិធី​នៅ​តំបន់មូលដ្ឋាន) +- [លក្ខណៈបូករួមដែលត្រូវការ](#លក្ខណៈបូករួមដែលត្រូវការ) +- [ការយល់ដឹងពីបញ្ហាចម្បង](#ការយល់ដឹងពីបញ្ហាចម្បង) +- [ការយល់ដឹងអំពី Tokens](#ការយល់ដឹងអំពី-tokens) +- [របៀបដែលមេម៉ូរីដំណើរការ](#របៀបដែលមេម៉ូរីដំណើរការ) +- [របៀបប្រើ LangChain4j នេះ](#របៀបប្រើ-langchain4j-នេះ) +- [ដាក់ឲ្យដំណើរការ Facebook OpenAI](#ដាក់ឲ្យដំណើរការ-azure-openai-infrastructure) +- [រត់កម្មវិធីនៅក្នុងម៉ាស៊ីន](#រត់កម្មវិធីនៅក្នុងម៉ាស៊ីន) - [ការប្រើកម្មវិធី](#ការប្រើកម្មវិធី) - - [ជជែកមិនមានស្ថានភាព (ផ្នែកឆ្វេង)](#ជជែកមិនមានស្ថានភាព-ផ្នែកឆ្វេង) - - [ជជែកមានស្ថានភាព (ផ្នែកស្តាំ)](#ជជែកមានស្ថានភាព-ផ្នែកស្តាំ) + - [chat Stateless (ផ្នែកឆ្វេង)](#stateless-chat-ផ្នែកឆ្វេង) + - [chat Stateful (ផ្នែកស្តាំ)](#stateful-chat-ផ្នែកស្តាំ) - [ជំហានបន្ទាប់](#ជំហានបន្ទាប់) -## វីដេអូបង្ហាញ +## ការបង្ហាញវីដេអូ -មើលសម័យផ្សាយបន្តផ្ទាល់នេះ ដែលពន្យល់ពីរបៀបចាប់ផ្តើមជាមួយមេឌុលនេះ៖ +មើលវីដេអូផ្ទាល់នេះដែលពន្យល់ពីរបៀបចាប់ផ្តើមជាមួយមូឌុលនេះ៖ -Getting Started with LangChain4j - Live Session +ការចាប់ផ្តើមជាមួយ LangChain4j - សម័យផ្ទាល់ ## អ្វីដែលអ្នកនឹងរៀន -ក្នុងការចាប់ផ្ដើមលឿន អ្នកបានប្រើម៉ូឌែល GitHub ដើម្បីផ្ញើសំណើរ ហៅឧបករណ៍ បង្កើតផ្លូវ RAG និងសាកល្បងការការពារ។ បង្ហាញទាំងនោះបង្ហាញអ្វីដែលអាចធ្វើបាន — ឥលូវយើងប្រែទៅប្រើ Azure OpenAI និង GPT-5.2 ហើយចាប់ផ្តើមបង្កើតកម្មវិធីស្ទីលផលិតកម្ម។ មេឌុលនេះផ្ដោតលើ AI សន្ទនាដែលចងចាំ context និងរក្សាស្ថានភាព — គំនិតដែលបង្ហាញក្នុងសម័យចាប់ផ្តើមលឿន ប៉ុន្តែមិនបានពន្យល់។ +នេះជាចំណុចចាប់ផ្តើមរបស់អ្នកជាមួយ LangChain4j និង Azure OpenAI។ យើងចាប់ផ្តើមពីមូលដ្ឋានហើយចាប់ផ្តើមកសាងកម្មវិធីបែបផលិតកម្ម។ មូឌុលនេះផ្តោតលើ AI សន្ទនា ដែលចងចាំcontext និងរក្សាស្ថានភាព — គោលនយោបាយមូលដ្ឋានដែលមូឌុលបន្ទាប់ទាំងអស់បានបើកចំហ។ -យើងនឹងប្រើ GPT-5.2 របស់ Azure OpenAI ជារយៈពេលដឹកនាំនេះ ព្រោះសមត្ថភាពសំរាប់គំនិតៈចំលែកកម្រិតខ្ពស់បន្ថែមធ្វើអោយអាកប្បបរមាផ្គួបគ្នានៅលើរចនាប័ទ្មផ្សេងៗច្បាស់លាស់ជាងមុន។ ពេលអ្នកបន្ថែមមេមឺរី អ្នកនឹងឃើញភាពខុសគ្នាច្បាស់។ វាធ្វើអោយយល់យ៉ាងងាយស្រួលថាផ្នែកណាមួយនាំមកអ្វីដល់កម្មវិធីរបស់អ្នក។ +យើងនឹងប្រើ GPT-5.2 របស់ Azure OpenAI ទូទាំងមេរៀននេះ ព្រោះសមត្ថភាពហេតុផលខ្ពស់របស់វាធ្វើឲ្យការបង្ហាញទម្រង់នានាផ្សេងៗកាន់តែច្បាស់លាស់។ នៅពេលអ្នកបន្ថែមមេម៉ូរី អ្នកនឹងឃើញភាពខុសគ្នាដោយច្បាស់។ វាធ្វើឲ្យងាយស្រួលក្នុងការយល់ថាផ្នែកណាផ្តល់អ្វីទៅកម្មវិធីរបស់អ្នក។ -អ្នកនឹងបង្កើតកម្មវិធីមួយដែលបង្ហាញរចនាប័ទ្មទាំងពីរ៖ +អ្នកនឹងបង្កើតកម្មវិធីមួយ ដែលបង្ហាញទាំងពីរទម្រង់នេះ៖ -**ជជែកមិនមានស្ថានភាព** - ការសំណើរ​ស្ទើរក្នុងមួយសំណើគឺឯករាជ្យ។ ម៉ូឌែលមិនមានមេមឺរីនៃសារមុនៗទេ។ នេះគឺជារចនាប័ទ្មដែលបានប្រើនៅក្នុងការចាប់ផ្តើមលឿន។ +**Stateless Chat** - រាល់សំណើគឺឯករាជ្យ។ ម៉ូឌែលមិនមានការចងចាំសារមុន។ នេះជាចំណុចចាប់ផ្តើមសាមញ្ញបំផុត។ -**ជជែកមានស្ថានភាព** - ការសំណើរ​មួយរួមមានប្រវត្តិការសន្ទនា។ ម៉ូឌែលរក្សាស្ថានភាព context រយៈពេលជាច្រើនជំនួស។ នេះគឺជាចាំបាច់សម្រាប់កម្មវិធីផលិតកម្ម។ +**Stateful Conversation** - រាល់សំណើរមានប្រវត្តិការសន្ទនា។ ម៉ូឌែលរក្សា context ជាយូរជាងនេះ។ នេះជាវត្ថុដែលកម្មវិធីផលិតកម្មត្រូវការ។ -## លក្ខខណ្ឌមុន +## លក្ខណៈបូករួមដែលត្រូវការ -- អនុញ្ញាត Azure ដែលមានចូលប្រើ Azure OpenAI +- ចុះឈ្មោះ Azure ជាមួយការចូលប្រើ Azure OpenAI - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **សម្គាល់៖** Java, Maven, Azure CLI និង Azure Developer CLI (azd) ត្រូវបានដំឡើងរួចជាមុននៅក្នុង devcontainer ដែលបានផ្ដល់។ +> **កំណត់ចំណាំ:** Java, Maven, Azure CLI និង Azure Developer CLI (azd) ត្រូវបានដំឡើងរួចនៅក្នុង devcontainer ដែលផ្តល់ជូន។ -> **សម្គាល់៖** មេឌុលនេះប្រើ GPT-5.2 នៅលើ Azure OpenAI។ ការចាត់ចែងត្រូវបានកំណត់ដោយស្វ័យប្រវត្តិតាម `azd up` — សូមកុំផ្លាស់ប្តូរឈ្មោះម៉ូឌែលនៅក្នុងកូដ។ +> **កំណត់ចំណាំ:** មូឌុលនេះប្រើ GPT-5.2 នៅលើ Azure OpenAI។ ការដំឡើងត្រូវបានកំណត់ដោយស្វ័យប្រវត្តិតាម `azd up` - មិនត្រូវកែប្រែឈ្មោះម៉ូឌែលក្នុងកូដឡើយ។ -## ការយល់ដឹងអំពីបញ្ហាគ្រឹះ +## ការយល់ដឹងពីបញ្ហាចម្បង -ម៉ូឌែលភាសាគឺមិនមានស្ថានភាពទេ។ ការហៅ API មួយៗជា​ឯករាជ្យ។ ប្រសិនបើអ្នកផ្ញើ "ឈ្មោះខ្ញុំគឺ John" ហើយបន្ទាប់មកសួរ "ឈ្មោះខ្ញុំអ្វី?" ម៉ូឌែលមិនមានគំនិតថា អ្នកទើបជំរាបខ្លួនទេ។ វាប្រព្រឹត្តទៅនូវការសំណើរ​រាល់យ៉ាងដូចជាដើមជជែកដំបូងពិតប្រាកដរបស់អ្នក។ +ម៉ូឌែលភាសាគឺស្ថានភាពឯករាជ្យ។ រាល់ការហៅ API គឺឯករាជ្យ។ ប្រសិនបើអ្នកផ្ញើ "ខ្ញុំឈ្មោះ John" ហើយបន្ទាប់មកសួរ "ឈ្មោះខ្ញុំជាអ្វី?" ម៉ូឌែលមិនដឹងថាអ្នកបានណែនាំខ្លួនហើយ។ វាត្រូវគ្រប់សំណើដូចជាលើកដំបូងដែលអ្នកបានចាប់ផ្តើមសន្ទនា។ -នេះល្អសម្រាប់ Q&A ងាយៗ ប៉ុន្តាមិនប្រយោជន៍សម្រាប់កម្មវិធីពិតប្រាកដទេ។ យន្តហោះបម្រើអតិថិជនត្រូវការចងចាំអ្វីដែលអ្នកបានប្រាប់។ ជំនួយករការផ្ទាល់ខ្លួនត្រូវការចំណេះដឹង context។ ជជែកច្រើនជំហានត្រូវការមេមឺរី។ +នេះល្អសម្រាប់សំណួរនិងចម្លើយសាមញ្ញ ប៉ុន្តែមិនមានប្រយោជន៍សម្រាប់កម្មវិធីពិតប្រាកដទេ។ បុត្យសេវាកម្មអតិថិជនត្រូវការចងចាំអ្វីដែលអ្នកបានប្រាប់។ ជំនួយការផ្ទាល់ខ្លួនត្រូវការប្រភេទContext។ ការសន្ទនាច្រើនជំហានត្រូវការមេម៉ូរី។ -តារាងខាងក្រោមបង្ហាញការប្រៀបធៀបច្រើនរបស់របៀបទាំងពីរ — ផ្នែកឆ្វេង ជាការហៅមិនមានស្ថានភាពដែលភ្លេចឈ្មោះអ្នក; ផ្នែកស្តាំ ជាការហៅមានស្ថានភាពដែលមាន ChatMemory ដែលចងចាំវា។ +គំនូសតាងខាងក្រោមបង្ហាញការប្រៀបធៀបរវាងវិធីសាស្រ្តពីរនេះ — ផ្នែកឆ្វេង ជាការហៅឯករាជ្យដែលភ្លេចឈ្មោះអ្នក; ផ្នែកស្តាំ ជាការហៅមានស្ថានភាព ដែលគាំទ្រ ChatMemory ដែលចងចាំវា។ Stateless vs Stateful Conversations -*ភាពខុសគ្នារវាងជជែកមិនមានស្ថានភាព (ហៅឯករាជ្យ) និងជជែកមានស្ថានភាព (យល់ context)* +*ភាពខុសគ្នារវាង សន្ទនាឯករាជ្យ និងសន្ទនាដែលមាន context* -## ការយល់ដឹងអំពីសញ្ញាសំគាល់ +## ការយល់ដឹងអំពី Tokens -មុនចូលក្នុងជជែក វាជារឿងសំខាន់ក្នុងការយល់សញ្ញាសំគាល់ - ឯកតាគោលនៃអត្ថបទដែលម៉ូឌែលភាសាដំណើរការ៖ +មុនពេលចូលទៅក្នុងការសន្ទនា គួរយល់ដឹងអំពី tokens - អង្គធាតុមូលដ្ឋាននៃអត្ថបទដែលម៉ូឌែលភាសាដំណើរការ៖ Token Explanation -*ឧទាហរណ៍របៀបអត្ថបទបែកជាសញ្ញាសំគាល់ - "I love AI!" ក្លាយទៅជា ៤ ឯកតា ដំណើរការបំបែក* +*ឧទាហរណ៍ពីរបៀបអត្ថបទបំបែកជាទុកខន្លះៗ - "I love AI!" ក្លាយទៅជាឯកតាប្រតិបត្តិការពីរ ៤* -សញ្ញាសំគាល់គឺជារបៀបដែលម៉ូឌែល AI វាស់ និងដំណើរការ​អត្ថបទ។ ពាក្យ វាយនភាព និងចន្លោះអាចជាសញ្ញាសំគាល់ផងដែរ។ ម៉ូឌែលរបស់អ្នកមានកំណត់ពីមួយដល់ប៉ុន្មានសញ្ញាសំគាល់វាអាចដំណើរការបានក្នុងមួយពេល (៤០០,០០០ សម្រាប់ GPT-5.2, ជាមួយបញ្ចូលរហូតដល់ ២៧២,០០០ និងបញ្ចេញរហូតដល់ ១២៨,០០០ សញ្ញាសំគាល់)។ ការយល់សញ្ញាសំគាល់ជួយអ្នកគ្រប់គ្រងប្រវែងជជែក និងចំណាយ។ +Tokens ជារបៀបដែលម៉ូឌែល AI វាស់វែង និងដំណើរការ អត្ថបទ។ ពាក្យ សញ្ញាវិនិច្ឆ័យ និងកន្លែងទទេ ទាំងអស់អាចជាទុកខន្លះបាន។ ម៉ូឌែលរបស់អ្នកមានកំណត់មាត្រជាចំនួន token វាអាចដំណើរការបាននៅមួយ ពេល (៤០០,០០០ សម្រាប់ GPT-5.2, រួមមានបញ្ចូលតុកខាន់ ២៧២,០០០ និងចេញតុកខាន់ ១២៨,០០០)។ ការយល់ពី token ជួយអ្នកគ្រប់គ្រងរយៈពេលសន្ទនា និងថ្លៃដើម។ -## របៀបដំណើរការមេមឺរី +## របៀបដែលមេម៉ូរីដំណើរការ -មេមឺរីជជែកដោះស្រាយបញ្ហាមិនមានស្ថានភាពដោយរក្សាប្រវត្តិជជែក។ មុនផ្ញើសំណើទៅម៉ូឌែល ស៊េវាកម្មនឹងបញ្ចូលសារមុនៗដែលពាក់ព័ន្ធ។ ពេលអ្នកសួរ "ឈ្មោះខ្ញុំអ្វី?" ប្រព័ន្ធពិតប្រាកដផ្ញើប្រវត្តិជជែកទាំងមូល ឱ្យម៉ូឌែលឮថា អ្នកបាននិយាយថា "ឈ្មោះខ្ញុំគឺ John" មុនហើយ។ +Chat memory ធ្វើការដោះស្រាយបញ្ហាស្ថានភាពឯករាជ្យ ដោយរក្សាប្រវត្តិសន្ទនា។ មុនផ្ញើសំណើទៅម៉ូឌែល វាដាក់សារ relevants មុននៗជាមុន។ នៅពេលអ្នកសួរ "ឈ្មោះខ្ញុំជាអ្វី?" ប្រព័ន្ធផ្ញើប្រវត្តិសន្ទនាដល់ម៉ូឌែល ដូច្នេះវាឃើញថាអ្នកបាននិយាយថា "ខ្ញុំឈ្មោះ John" មុនហើយ។ -LangChain4j ផ្ដល់នូវការអនុញ្ញាតមេមឺរីដែលគ្រប់គ្រងស្វ័យប្រវត្តិនេះ។ អ្នកជ្រើសរើសចំនួនសារដែលចង់រក្សា ហើយ framework គ្រប់គ្រង context window។ តារាងខាងក្រោមបង្ហាញរបៀប MessageWindowChatMemory រក្សានូវបង្អួចរអិលនៃសារថ្មីៗ។ +LangChain4j ផ្តល់ជូននូវការអនុវត្តមេម៉ូរី ដែលដំណើរការដោយស្វ័យប្រវត្តិ។ អ្នកជ្រើសរើសចំនួនសារដែលអាចរក្សាទុក ហើយ framework គ្រប់គ្រងប្រអប់ context ជូនអ្នក។ គំនូសតាងខាងក្រោមបង្ហាញពីរបៀបដែល MessageWindowChatMemory រក្សាប្រអប់ចលករជាសារថ្មីៗ។ Memory Window Concept -*MessageWindowChatMemory រក្សាបង្អួចរអិលនៃសារថ្មីៗ ដោយស្វ័យប្រវត្តិ drop សារចាស់ៗ* +*MessageWindowChatMemory រក្សាប្រអប់ចលនា ស៊ីធីរបស់សារថ្មីៗ ដោយជាប្រព័ន្ធចេញសារចាស់ៗដោយស្វ័យប្រវត្តិ* -## របៀបដែលនេះប្រើ LangChain4j +## របៀបប្រើ LangChain4j នេះ -មេឌុលនេះបន្ថែមការចាប់ផ្តើមលឿនដោយរួមបញ្ចូល Spring Boot និងបន្ថែមមេមឺរីជជែក។ នេះជារបៀបដែលផ្នែកជាប់គ្នា៖ +មូឌុលនេះបញ្ចូល Spring Boot ហើយបន្ថែមមេម៉ូរីសន្ទនា។ របៀបភ្ជាប់គ្នារបស់វា៖ -**ឧបករណ៍ដែលទាមទារ** - បន្ថែមបណ្ណាល័យ LangChain4j ពីរយ៉ាង៖ +**Dependencies** - បន្ថែមបណ្ណាល័យ LangChain4j ពីរ៖ ```xml @@ -93,8 +93,8 @@ LangChain4j ផ្ដល់នូវការអនុញ្ញាតមេម langchain4j-open-ai-official ``` - -**ម៉ូឌែលជជែក** - កំណត់ Azure OpenAI ជា Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java))៖ + +**Chat Model** - កំណត់ Azure OpenAI ជា Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java))៖ ```java @Bean @@ -108,10 +108,10 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { .build(); } ``` - -កម្មវិធីបង្កើតអានសញ្ញាប័ត្រពី environment variables ដែលកំណត់ដោយ `azd up`។ ការកំណត់ `baseUrl` ទៅចំណុចបញ្ចូល Azure របស់អ្នកធ្វើអោយ client OpenAI ធ្វើការ​ជាមួយ Azure OpenAI ។ -**មេមឺរីជជែក** - តាមដានប្រវត្តិជជែកជាមួយ MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java))៖ +Builder អានអត្តសញ្ញាណពីបរិយាកាសដែលបានកំណត់ដោយ `azd up`។ ការកំណត់ `baseUrl` ទៅចំណុចចេញ Azure របស់អ្នក ធ្វើឲ្យ client OpenAI ធ្វើការជាមួយ Azure OpenAI បាន។ + +**Conversation Memory** - តាមដានប្រវត្តិការសន្ទនាជាមួយ MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java))៖ ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -123,202 +123,202 @@ memory.add(UserMessage.from("What's my name?")); AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` - -បង្កើតមេមឺរីជាមួយ `withMaxMessages(10)` ដើម្បីរក្សាសារចុងក្រោយ ១០ ។ បន្ថែមសារអ្នកប្រើ និង AI ជាមួយអ្នកបន្ទាត់ typed: `UserMessage.from(text)` និង `AiMessage.from(text)`។ ទាញយកប្រវត្តិជាមួយ `memory.messages()` ហើយផ្ញើទៅម៉ូឌែល។ សេវាកម្មរក្សាទុក instance មេមឺរីបំបែកតាម conversation ID, អនុញ្ញាតឱ្យអ្នកប្រើច្រើនជជែកក្នុងពេលតែមួយ។ -> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat :** បើក [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ហើយសួរ៖ -> - "MessageWindowChatMemory បញ្ចេញសារណាដែលពេលបង្អួចពេញដូចម្តេច?" -> - "តើខ្ញុំអាចអនុវត្តការផ្ទុកមេមឺរីផ្ទាល់ខ្លួនជាមួយមូលដ្ឋានទិន្នន័យផ្ទាន់នឹងមេមឺរីក្នុងចិត្តបានទេ?" -> - "តើខ្ញុំនឹងបន្ថែមសរុបមាត្រសំរាប់បង្ហាប់ប្រវត្តិជជែកចាស់ៗយ៉ាងដូចម្តេច?" +បង្កើតមេម៉ូរីជាមួយ `withMaxMessages(10)` ដើម្បីរក្សាសារចុងក្រោយ១០សារ។ បន្ថែមសារអ្នកប្រើ និង AI ជាមួយ Typed wrappers: `UserMessage.from(text)` និង `AiMessage.from(text)`។ ទាញយកប្រវត្តិយ៉ាង `memory.messages()` ហើយផ្ញើទៅម៉ូឌែល។ សេវាកម្មរក្សារម៉េម៉ូរីអក្សរផ្សេងៗទុករៀងរាល់ conversation ID អនុញ្ញាតឲ្យអ្នកប្រើជាច្រើនបានសន្ទនាតាមពីរដល់ព្រម។ + +> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ហើយសួរ៖ +> - "MessageWindowChatMemory ធ្វើដូចម្តេចក្នុងការសម្រេចចិត្តចេញសារណាដែលទៅពេលប៉ុន្មានពេញប្រអប់?" +> - "តើខ្ញុំអាចអនុវត្តផ្ទុកមេម៉ូរីផ្ទាល់ខ្លួនដោយប្រើទិន្នន័យបញ្ជីទិន្នន័យជំនួសមេម៉ូរីក្នុងម៉ោនទេ?" +> - "តើខ្ញុំនឹងបន្ថែមការសង្ខេបដើម្បីចុះកម្រិតប្រវត្តិការសន្ទនា​ចាស់ៗបានដូចម្តេច?" -ចំណុចចូលជជែកមិនមានស្ថានភាពមិនឆែកមេមឺរីទេ - គ្រាន់តែ `chatModel.chat(prompt)` ដូចការចាប់ផ្តើមលឿន។ ចំណុចចូលមានស្ថានភាពបន្ថែមសារទៅមេមឺរី ទាញប្រវត្តិហើយបញ្ចូល context ជាមួយសំណើរ។ ការកំណត់ម៉ូឌែលដូចគ្នា តែរចនាប័ទ្មផ្សេងគ្នា។ +Chat Stateless មាន endpoint មិនប្រើមេម៉ូរីទាំងអស់ - គឺ `chatModel.chat(prompt)` ដូចជាការចាប់ផ្តើមលឿន។ Chat Stateful បន្ថែមសារចូលទៅមេម៉ូរី ទាញយកប្រវត្តិ ហើយរួមបញ្ចូល context តាមកំណត់សំណើរ។ ការកំណត់ម៉ូឌែលដូចគ្នា តែបែបបទខុសគ្នា។ -## ចាត់ចែង និងដាក់បញ្ចូលហេដ្ឋារចនាសម្ព័ន្ធ Azure OpenAI +## ដាក់ឲ្យដំណើរការ Azure OpenAI Infrastructure -**Bash:** +**Bash:** ```bash cd 01-introduction -azd up # ជ្រើសរើសការជាវ និងទីតាំង (ត្រូវបានណែនាំ eastus2) +azd up # ជ្រើសរើសការប្រព្រឹត្តិការណ៍ និងទីតាំង (eastus2 គឺត្រូវបានផ្តល់អនុសាសន៍) ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 01-introduction -azd up # ជ្រើសរើសការជាវ និងទីតាំង (ច្បាប់ណែនាំ eastus2) +azd up # ជ្រើសរើសការជាវ និងទីតាំង (មែនទែនថា eastus2) ``` - -> **សម្គាល់៖** ប្រសិនបើបង្ហាញកំហុស timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), សូមរត់ `azd up` ម្តងទៀត។ ធនធាន Azure ប្រហែលនៅក្នុងដំណើរការពេលក្រោយ ហើយការព្យាយាមម្ដងទៀតអនុញ្ញាតឱ្យការចាត់ចែងបញ្ចប់ពេលធនធានទៅស្ថានភាពចុងក្រោយ។ -នេះនឹង៖ -1. ចាត់ចែងធនធាន Azure OpenAI ជាមួយម៉ូឌែល GPT-5.2 និង text-embedding-3-small -2. បង្កើតឯកសារ `.env` ដោយស្វ័យប្រវត្តិក្នុងដើមគម្រោង ជាមួយសញ្ញាប័ត្រ -3. កំណត់អថេរ environment ទាំងអស់ដែលត្រូវការ +> **កំណត់ចំណាំ:** ប្រសិនបើអ្នកជួបបញ្ហាចុងបញ្ចប់ពេលស្នើសុំ (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), ចូររត់ `azd up` ម្តងទៀត។ អង្គភាព Azure អាចនៅក្រោមដំណើរការនៅខាងក្រោយ ហើយការសាកល្បងឡើងវិញធ្វើឲ្យការដាក់ឲ្យដំណើរការសម្រេចបានពេលអង្គភាពចប់នៅស្ថានភាពចុងក្រោយ។ + +វានឹង៖ +1. ដាក់ឲ្យដំណើរការ Azure OpenAI ជាមួយម៉ូឌែល GPT-5.2 និង text-embedding-3-small +2. បង្កើតឯកសារ `.env` ឯកសារដើមក្នុងគម្រោងជាស្វ័យប្រវត្តិ ជាមួយអត្តសញ្ញាណ +3. កំណត់អថេរបរិយាកាសទាំងអស់ដែលត្រូវការ -**មានបញ្ហាចាត់ចែង?**មើល [README ហេដ្ឋារចនាសម្ព័ន្ធ](infra/README.md) សម្រាប់ដំណោះស្រាយលម្អិតរួមទាំងបញ្ហាឈ្មោះស៊ឹបដែន បច្ចេកទេសដាក់ផ្សាយដៃ Azure Portal និងមគ្គុទេសក៍កំណត់ម៉ូឌែល។ +**ប្រឈមបញ្ហាក្នុងការដាក់ឲ្យដំណើរការ?** មើល [Infrastructure README](infra/README.md) សម្រាប់ការដោះស្រាយលម្អិត រួមមានបញ្ហាឈ្មោះ subdomain, ជំហានដាក់មិនឲ្យប្រើ Azure Portal ដោយដៃ និងការណែនាំកំណត់ម៉ូឌែល។ -**ធ្វើការត្រួតពិនិត្យថានៅក្នុងការចាត់ចែងបានជោគជ័យ៖** +**បញ្ជាក់ថាការដាក់បានជោគជ័យ៖** -**Bash:** +**Bash:** ```bash -cat ../.env # ត្រូវបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, ល។ +cat ../.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, ល។ ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, ល។ ``` - -> **សម្គាល់៖** ពាក្យបញ្ជា `azd up` បង្កើតឯកសារ `.env` ដោយស្វ័យប្រវត្តិ។ ប្រសិនបើអ្នកចង់ធ្វើបច្ចុប្បន្នភាព វាអាចកែតម្រូវឯកសារ `.env` ដោយដៃ ឬបង្កើតឡើងវិញដោយរត់៖ -> -> **Bash:** + +> **កំណត់ចំណាំ:** ពាក្យបញ្ជា `azd up` បង្កើតឯកសារ `.env` ដោយស្វ័យប្រវត្តិ។ ប្រសិនបើអ្នកចង់បន្ទាន់សម័យនៅពេលក្រោយ អ្នកអាចកែប្រែឯកសារ `.env` ដោយដៃ ឬបង្កើតឡើងវិញដោយរត់ ៖ +> +> **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` - -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` - -## បើកដំណើរការ​កម្មវិធី​នៅ​តំបន់មូលដ្ឋាន -**ធ្វើការត្រួតពិនិត្យការចាត់ចែង៖** +## រត់កម្មវិធីនៅក្នុងម៉ាស៊ីន -ធ្វើឲ្យប្រាកដថា ឯកសារ `.env` មាននៅក្នុងថតដើម ជាមួយសញ្ញាប័ត្ររបស់ Azure។ រត់ពាក្យបញ្ជានេះពីថតមេឌុល (`01-introduction/`)៖ +**បញ្ជាក់ការដាក់បាន៖** -**Bash:** +ធ្វើឲ្យប្រាកដថា ឯកសារ `.env` មាននៅក្នុងថតdir root ដោយមានអត្តសញ្ញាណ Azure។ រត់ពីថតមូឌុល (`01-introduction/`)៖ + +**Bash:** ```bash cat ../.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # ត្រូវបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **ចាប់ផ្តើមកម្មវិធី៖** -**ជម្រើស ១៖ ប្រើ Spring Boot Dashboard (ផ្ដល់អនុសាសន៍សម្រាប់អ្នកប្រើ VS Code)** +**ជម្រើស ១៖ ប្រើ Spring Boot Dashboard (ផ្នែកណែនាំសម្រាប់អ្នកប្រើ VS Code)** -Dev container រួមបញ្ចូលផ្នែកបន្ថែម Spring Boot Dashboard ដែលផ្ដល់ចំណុចប្រទាក់ដ៏ទាក់ទាញសម្រាប់គ្រប់គ្រងកម្មវិធី Spring Boot ទាំងអស់។ អ្នកអាចរកឃើញវានៅ Activity Bar ភាគខាងឆ្វេង នៃ VS Code (សូមសង្កេតសញ្ញារបស់ Spring Boot)។ +Dev container រួមបញ្ចូលផ្នែកបន្ថែម Spring Boot Dashboard ដែលផ្តល់អន្តរកម្មមើលគ្រប់គ្រងកម្មវិធី Spring Boot ទាំងអស់។ អ្នកអាចស្វែងរកវានៅ Activity Bar ផ្នែកខាងឆ្វេងនៃ VS Code (មើលរូបតំណាង Spring Boot)។ ពី Spring Boot Dashboard អ្នកអាច៖ -- មើលកម្មវិធី Spring Boot ទាំងអស់ក្នុងworkspace -- ចាប់ផ្តើម/បញ្ឈប់កម្មវិធីដោយចុចតែមួយ -- មើលកំណត់ហេតុកម្មវិធីក្នុងពេលពិត -- ត្រួតពិនិត្យស្ថានភាពកម្មវិធី +- មើលកម្មវិធី Spring Boot ទាំងអស់ក្នុង workspace +- ចាប់ផ្តើម/បញ្ឈប់កម្មវិធីដោយចុចប៊ូតុងតែមួយ +- មើលកំណត់ហេតុកម្មវិធីពេលវេលាពិត +- ត្រួតពិនិត្យស្ថានភាពកម្មវិធី -គ្រាន់តែចុចប៊ូតុងលេងនៅចំហៀង "introduction" ដើម្បីចាប់ផ្តើមមេឌុលនេះ ឬចាប់ផ្តើមមេឌុលទាំងអស់ក្នុងពេលតែមួយ។ +គ្រាន់តែក្លិចប៊ូតុង play នៅជាប់នឹង "introduction" ដើម្បីចាប់ផ្តើមមូឌុលនេះ ឬចាប់ផ្តើមមូឌុលទាំងអស់ម្តង។ Spring Boot Dashboard -*ផ្ទាំង Spring Boot Dashboard ក្នុង VS Code — ចាប់ផ្តើម បញ្ឈប់ និងត្រួតពិនិត្យមេឌុលទាំងអស់ពីកន្លែងតែមួយ* +*Spring Boot Dashboard ក្នុង VS Code — ចាប់ផ្តើម បញ្ឈប់ និងត្រួតពិនិត្យមូឌុលទាំងអស់ពីកន្លែងតែមួយ* -**ជម្រើស ២៖ ប្រើស្គ្រីប shell** +**ជម្រើស ២៖ ប្រើ shell scripts** -ចាប់ផ្តើមកម្មវិធីគេហទំព័រទាំងអស់ (មេឌុល ០១-០៤): +ចាប់ផ្តើមកម្មវិធីវេបទាំងអស់ (មូឌុល 01-04): -**Bash:** +**Bash:** ```bash -cd .. # ពីថតគោល +cd .. # ពីថតគ្រប់គ្រាន់ ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd .. # ពីថតដើម .\start-all.ps1 ``` - -ឬចាប់ផ្តើមតែម្ដងមេឌុលនេះ៖ -**Bash:** +ឬចាប់ផ្តើមតែម្ដងមូឌុលនេះ៖ + +**Bash:** ```bash cd 01-introduction ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 01-introduction .\start.ps1 ``` - -ស្គ្រីបទាំងពីរទាំងអស់បញ្ចូលអថេរ environment ពីឯកសារ `.env` ដើម និងនឹងបន្ថែមការសង់ JAR ប្រសិនបើវាមិនមាន។ -> **សម្គាល់៖** ប្រសិនបើអ្នកចង់សង់មេឌុលទាំងអស់ដោយដៃមុនចាប់ផ្តើម៖ -> -> **Bash:** +Script ទាំងពីរនឹងផ្ទុកអថេរបរិយាកាសពីឯកសារ `.env` នៅថតដើម និងនឹងសង់ JAR ប្រសិនមិនមានមានរួច។ + +> **កំណត់ចំណាំ:** ប្រសិនអ្នកចង់សាងសង់មូឌុលទាំងអស់ដោយដៃមុនចាប់ផ្តើម៖ +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + បើក http://localhost:8080 នៅក្នុងកម្មវិធីរុករករបស់អ្នក។ **ដើម្បីបញ្ឈប់៖** -**Bash:** +**Bash:** ```bash ./stop.sh # ម៉ូឌុលនេះតែប៉ុណ្ណោះ # ឬ cd .. && ./stop-all.sh # ម៉ូឌុលទាំងអស់ ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # ម៉ូឌុលនេះតែប៉ុណ្ណោះ -# រឺ +# ឬ cd ..; .\stop-all.ps1 # ម៉ូឌុលទាំងអស់ ``` - + ## ការប្រើកម្មវិធី -កម្មវិធីផ្ដល់ចំណុចប្រទាក់វេបដែលមានការអនុវត្តជជែកពីរពីរេក្ដៅជាប់គ្នា។ +កម្មវិធីផ្តល់អ៊ីនធរណេតមុខមាត់ជាមួយការអនុវត្តសន្ទនាពីរជាប់ផ្សេងគ្នា។ Application Home Screen -*ផ្ទាំងបង្ហាញជម្រើសទាំងពីរនៃជជែកសាមញ្ញ (មិនមានស្ថានភាព) និងជជែកពិភាក្សា (មានស្ថានភាព)* +*ផ្ទាំង Dashboard បង្ហាញទាំង Simple Chat (stateless) និង Conversational Chat (stateful)* -### ជជែកមិនមានស្ថានភាព (ផ្នែកឆ្វេង) +### Stateless Chat (ផ្នែកឆ្វេង) -សាកល្បងនេះជាមុន។ សួរ "ឈ្មោះខ្ញុំគឺ John" ហើយភ្លាមៗសួរ "ឈ្មោះខ្ញុំអ្វី?" ម៉ូឌែលមិនចងចាំទេ ពីព្រោះសារនិមួយៗឯករាជ្យ។ នេះបង្ហាញបញ្ហាគ្រឹះនៃការចងក្រងម៉ូឌែលភាសាថ្មីៗ - គ្មាន context ជជែក។ +សាកល្បងនេះជាមុន។ សួរ "ខ្ញុំឈ្មោះ John" ហើយភ្លាមៗសួរ "ឈ្មោះខ្ញុំជាអ្វី?" ម៉ូឌែលមិនចងចាំព្រោះរាល់សារ គឺឯករាជ្យ។ នេះបង្ហាញបញ្ហាចម្បងនៃការចងក្រងម៉ូឌែលភាសាមិនមាន context។ Stateless Chat Demo -*AI មិនចងចាំឈ្មោះរបស់អ្នកពីសារ​មុន​ទេ* +*AI មិនចងចាំឈ្មោះអ្នកពីសារមុនទេ* -### ជជែកមានស្ថានភាព (ផ្នែកស្តាំ) +### Stateful Chat (ផ្នែកស្តាំ) -ឥឡូវសាកល្បងលំដាប់ដូចគ្នានៅទីនេះ។ សួរ "ឈ្មោះខ្ញុំគឺ John" ហើយបន្ទាប់មក "ឈ្មោះខ្ញុំអ្វី?" ម្តងនេះវាចងចាំ។ ភាពខុសគ្នាគឺ MessageWindowChatMemory — វារក្សាប្រវត្តិជជែក និងរួមបញ្ចូល context ជាមួយសំណើរ។ នេះជារបៀបដែល AI ជជែកផលិតកម្មដំណើរការ។ +ឥឡូវនេះសាកល្បងជាដើមដូចគ្នានៅទីនេះ។ សួរ "ខ្ញុំឈ្មោះ John" ហើយបន្ទាប់មក "ឈ្មោះខ្ញុំជាអ្វី?" ពេលនេះវាចងចាំបាន។ ភាពខុសគ្នាគឺ MessageWindowChatMemory - វាត្រូវបានរក្សាប្រវត្តិការសន្ទនា និងរួមបញ្ចូលជាមួយរាល់សំណើ។ នេះជារបៀបដែល AI សន្ទនាកម្មវិធីផលិតកម្មដំណើរការ។ Stateful Chat Demo -*AI ចងចាំឈ្មោះរបស់អ្នកពីមុនក្នុងជជែក* +*AI ចងចាំឈ្មោះអ្នកពីការសន្ទនាមុន* -ផ្នែកទាំងពីរប្រើម៉ូឌែល GPT-5.2 ដូចគ្នា។ ភាពខុសគ្នាអាស្រ័យលើមេមឺរី។ វាធ្វើអោយយល់ច្បាស់ថាមេមឺរីនាំមកនូវអ្វីទៅកម្មវិធីរបស់អ្នក និងហេតុអ្វីវាជាកត្តាចាំបាច់សម្រាប់ករណីប្រើប្រាស់ពិតប្រាកដ។ +ផ្ទាំងទាំងពីរប្រើម៉ូឌែលតែមួយ GPT-5.2។ ភាពខុសគ្នាគឺមេម៉ូរី។ នេះធ្វើឲ្យច្បាស់ថាមេម៉ូរីផ្តល់អ្វីដល់កម្មវិធីរបស់អ្នក និងម៉េចវាសំខាន់សម្រាប់ករណីប្រើប្រាស់ពិតប្រាកដ។ ## ជំហានបន្ទាប់ -**មេឌុលបន្ទាប់៖** [02-prompt-engineering - វិជ្ជាជីវ Prompt ជាមួយ GPT-5.2](../02-prompt-engineering/README.md) +**មូឌុលបន្ទាប់៖** [02-prompt-engineering - ការបង្កើត Prompt ជាមួយ GPT-5.2](../02-prompt-engineering/README.md) --- -**ការជូនដំណឹងៈ** [← មុន៖ មេឌុល ០០ - ចាប់ផ្តើមលឿន](../00-quick-start/README.md) | [ត្រឡប់ទៅទំព័រដើម](../README.md) | [បន្ទាប់៖ មេឌុល ០២ - Prompt Engineering →](../02-prompt-engineering/README.md) +**ចុះទៅក្រោយ៖** [← ត្រឡប់ទៅទំព័រចម្បង](../README.md) | [បន្ទាប់៖ មូឌុល 02 - ការបង្កើត Prompt →](../02-prompt-engineering/README.md) --- -**ការបដិសេធ**៖ -ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាកម្មបកប្រែ AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ក្នុងនាមជាក្រុមហ៊ុនយើងខ្ញុំខិតខំប្រឹងប្រែងដើម្បីបានភាពត្រឹមត្រូវ សូមយល់ឲ្យបានថាការបកប្រែដោយស្វ័យប្រវត្តិនេះអាចមានកំហុស ឬការមិនត្រឹមត្រូវខ្លះ។ ឯកសារដើមជាភាសាមូលដ្ឋានគួរត្រូវបានគិតថាជាលក្ខណៈប្រភពផ្លូវការជាអាទិភាព។ សម្រាប់ព័ត៌មានដែលមានសារៈសំខាន់ណាស់ គួរប្រើការបកប្រែមនុស្សជំនាញជាផ្លូវការ។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកស្រាយខុសពីការប្រើប្រាស់ការបកប្រែនេះឡើយ។ +**ការបដិសេធ**: +ឯកសារនេះត្រូវបានបម្លែងភាសា ដោយប្រើសេវាបម្លែងភាសា AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទោះយើងខ្ញុំមានក្តីប្រាថ្នាឱ្យបានច្បាស់លាស់ តែសូមយល់ដឹងថាការបម្លែងដោយស្វ័យប្រវត្តិក៏អាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមជាភាសាទីតាំងគួរត្រូវបានគេប្រើជាប្រភពច្បាស់លាស់។ សម្រាប់ព័ត៌មានសំខាន់ៗ សូមណែនាំឱ្យប្រើប្រាស់ការប្រែដោយមនុស្សជំនាញ។ យើងខ្ញុំមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកស្រាយខុសបន្ទាប់ពីការប្រើប្រាស់ការបម្លែងនេះនោះទេ។ \ No newline at end of file diff --git a/translations/km/02-prompt-engineering/README.md b/translations/km/02-prompt-engineering/README.md index d00d4a5ac..d1391f51b 100644 --- a/translations/km/02-prompt-engineering/README.md +++ b/translations/km/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Module 02: វិស្វកម្មបញ្ចូលសេចក្តីបញ្ជា​ជាមួយ GPT-5.2 +# មុឌុល ០២៖ ការរចនាព្យួរជាមួយ GPT-5.2 -## តារាងមាតិកា +## តារាងខ្លឹមសារ -- [វីដេអូបង្ហាញ](#វីដេអូបង្ហាញ) +- [ការដើរកាត់វីដេអូ](#ការដើរកាត់វីដេអូ) - [អ្វីដែលអ្នកនឹងរៀន](#អ្វីដែលអ្នកនឹងរៀន) -- [លក្ខខណ្ឌមូលដ្ឋាន](#លក្ខខណ្ឌមូលដ្ឋាន) -- [ការយល់ដឹងអំពីវិស្វកម្មបញ្ចូលសេចក្តីបញ្ជា](#ការយល់ដឹងអំពីវិស្វកម្មបញ្ចូលសេចក្តីបញ្ជា) -- [មូលដ្ឋានវិស្វកម្មបញ្ចូលសេចក្តីបញ្ជា](#មូលដ្ឋានវិស្វកម្មបញ្ចូលសេចក្តីបញ្ជា) - - [បញ្ចូលសេចក្តីបញ្ជា​ពីគ្មានឧទាហរណ៍](#បញ្ចូលសេចក្តីបញ្ជា​ពីគ្មានឧទាហរណ៍) - - [បញ្ចូលសេចក្តីបញ្ជា​ពីមានឧទាហរណ៍少数](#បញ្ចូលសេចក្តីបញ្ជា​ពីមានឧទាហរណ៍少数) - - [ខ្សែសង្វាក់គំនិត](#ខ្សែសង្វាក់គំនិត) - - [បញ្ចូលសេចក្តីបញ្ជាចូលតួ](#បញ្ចូលសេចក្តីបញ្ជាចូលតួ) - - [គំរូបញ្ចូលសេចក្តីបញ្ជា](#គំរូបញ្ចូលសេចក្តីបញ្ជា) -- [រចនាប័ទ្មជាប់កម្រិតខ្ពស់](#រចនាប័ទ្មជាប់កម្រិតខ្ពស់) -- [រត់កម្មវិធី](#បើកដំណើរការ​-application) -- [រូបថតអេក្រង់កម្មវិធី](#រូបភាពនៃកម្មវិធី) -- [ស្ទូចស្ទង់រចនាប័ទ្ម](#ស្វែងយល់អំពីលំនាំបួន) - - [ទំនិញទាប និងខ្ពស់នៃការខិតខំ](#លំនាំបួន-low-vs-high-eagerness) - - [ការអនុវត្តភារកិច្ច (បញ្ជីឧបករណ៍)](#ការប្រតិបត្តិភារកិច្ច-ការពន្យល់-tool) - - [កូដដែលអាចធ្វើចិត្តខ្លួនឯង](#កូដបញ្ញ្រពិចារណាដោយខ្លួនឯង) - - [ការវិភាគរចនាសម្ព័ន្ធ](#វិភាគរចនាសម្ព័ន្ធ) - - [ការជជែកចល័តច្រើនជុំ](#ការសន្ទនាច្រើនជំរើស) - - [ការយល់ដឹងជំហានមួយៗ](#ការពិចារណាជាដំណាក់កាល) - - [លទ្ធផលដែលមានការកំណត់](#ការបញ្ចេញលទ្ធផលដែលមានកំណត់) +- [លក្ខខណ្ឌមុន](#លក្ខខណ្ឌមុន) +- [ការយល់ដឹងអំពីការរចនាព្យួរ](#ការយល់ដឹងអំពីការរចនាព្យួរ) +- [មូលដ្ឋាននៃការរចនាព្យួរ](#មូលដ្ឋាននៃការរចនាព្យួរ) + - [ការរចនាព្យួរដោយគ្មានឧទាហរណ៍](#ការរចនាព្យួរដោយគ្មានឧទាហរណ៍) + - [ការរចនាព្យួរដោយមានឧទាហរណ៍តិច](#ការរចនាព្យួរដោយមានឧទាហរណ៍តិច) + - [ខ្សែររបស់គំនិត](#ខ្សែររបស់គំនិត) + - [ការរចនាព្យួរផ្អែកលើតួនាទី](#ការរចនាព្យួរផ្អែកលើតួនាទី) + - [គំរូព្យួរ](#គំរូព្យួរ) +- [រចនាដែលមានកម្រិតខ្ពស់](#រចនាដែលមានកម្រិតខ្ពស់) +- [រត់កម្មវិធី](#ចាប់ផ្តើមកម្មវិធី) +- [រូបភាពចាប់ផ្តើមកម្មវិធី](#រូបថតថេបកម្មវិធី) +- [ការស្រាវជ្រាវលើរចនា](#ការស្វែងយល់ពីគំរូផ្សេងៗ) + - [ចំណង់ចំណូលចិត្តទាប និងខ្ពស់](#ឧស្សាហ៍ទាប-និងឧស្សាហ៍ខ្ពស់) + - [ការអនុវត្តបច្ចេកទេស (ការណែនាំឧបករណ៍)](#ការអនុវត្តភារកិច្ច-tool-preambles) + - [កូដស្វ័យប្រវត្តិក្នុងការពិចារណា](#កូដដែលមានការពិចារណាផ្ទាល់ខ្លួន) + - [វិភាគដែលមានរចនាសម្ព័ន្ធ](#ការវិភាគដែលមានរចនាសម្ព័ន្ធ) + - [ការផ្លាស់ប្តូរក្នុងមួយជំនួបច្រើនជុំ](#ការសន្ទនាពហុជំហាន) + - [ការពិចារណាជំហានដោយជំហាន](#ការគិតជាជំហានៗ) + - [លទ្ធផលដែលគ្រប់គ្រងបាន](#លទ្ធផលមានកំណត់) - [អ្វីដែលអ្នកពិតជាកំពុងរៀន](#អ្វីដែលអ្នកកំពុងរៀនពិតប្រាកដ) - [ជំហានបន្ទាប់](#ជំហានបន្ទាប់) -## វីដេអូបង្ហាញ +## ការដើរកាត់វីដេអូ -មើលវគ្គផ្សាយបន្តផ្ទាល់នេះដែលពន្យល់ពីរបៀបចាប់ផ្តើមជាមួយម៉ូឌុលនេះ៖ +មើលសម័យបន្តផ្ទាល់នេះដែលពន្យល់ពីរបៀបចាប់ផ្តើមជាមួយមុឌុលនេះ៖ Prompt Engineering with LangChain4j - Live Session ## អ្វីដែលអ្នកនឹងរៀន -ខ្សែភាពយន្តខាងក្រោមផ្តល់ជាទិដ្ឋភាពទូលំទូលាយអំពីប្រធានបទនិងជំនាញសំខាន់ដែលអ្នកនឹងអwickាឡើងនៅក្នុងម៉ូឌុលនេះ — ចាប់ពីបច្ចេកវិទ្យាកែលំអបញ្ចូលសេចក្តីបញ្ជាទៅដល់លំនាំដំណើរការជំហានមួយៗដែលអ្នកនឹងអនុវត្ត។ +ភាពសង្ខេបខាងក្រោមផ្តល់ឲ្យការយល់ដឹងអំពីប្រធានបច្ច័យ និងជំនាញសំខាន់ដែលអ្នកនឹងអភិវឌ្ឍក្នុងមុឌុលនេះ — ចាប់ពីបច្ចេកទេសកែសម្រួលព្យួរហើយដល់ដំណើរការជំហានដោយជំហានដែលអ្នកនឹងអនុវត្ត។ What You'll Learn -នៅក្នុងម៉ូឌុលមុនៗ អ្នកបានស្វែងយល់អំពីប្រតិកម្មទម្រង់LangChain4j ជាមួយម៉ូឌែល GitHub ហើយបានឃើញពីរបៀបដែលអង្គចងចាំអនុញ្ញាតឱ្យជជែកជាមួយ AI ជាមួយ Azure OpenAI។ ពេលនេះពួកយើងនឹងផ្តោតលើរបៀបដែលអ្នកសួរសំនួរ — គឺបញ្ចូលសេចក្តីបញ្ជាផ្ទាល់ — ដោយប្រើប្រាស់ GPT-5.2 របស់ Azure OpenAI។ របៀបដែលអ្នករៀបចំព័ត៌មានបញ្ចូលសេចក្តីបញ្ជាអា្នកប៉ះពាល់យ៉ាងខ្លាំងដល់គុណភាពនៃចម្លើយដែលអ្នកទទួលបាន។ យើងចាប់ផ្តើមពីការពិនិត្យវិធីសាស្រ្តបញ្ចូលសេចក្តីបញ្ជាមូលដ្ឋាន ហើយបន្ទាប់មកទៅរចនាប័ទ្ម​ជាប់កម្រិតខ្ពស់ប្រាំបួន ដែលប្រើអត្ថប្រយោជន៍ពេញលេញនៃសមត្ថភាព GPT-5.2។ +នៅមុឌុលមុន អ្នកបានមើលថាលំនាំចងចាំផ្តល់អនុសាសន៏សម្រាប់AIពិភាក្សាជាមួយ Azure OpenAI។ ឥឡូវនេះយើងនឹងផ្តោតលើរបៀបដែលអ្នកសួរពាក្យ — ព្យួរផ្ទាល់ខ្លួន — ដោយប្រើ GPT-5.2 របស់ Azure OpenAI។ របៀបដែលអ្នករៀបចំព្យួររបស់អ្នកមានប្រសិទ្ធភាពយ៉ាងខ្លាំងលើគុណភាពនៃចម្លើយដែលអ្នកទទួលបាន។ យើងចាប់ផ្តើមជាមួយការត្រួតពិនិត្យបច្ចេកទេសបន្ទាត់មូលដ្ឋានរួចចូលទៅកាន់រចនាដែលមានកម្រិតខ្ពស់បួនបីដែលប្រើប្រាស់អត្ថប្រយោជន៍ពេញលេញនៃសមត្ថភាព GPT-5.2។ -យើងនឹងប្រើ GPT-5.2 ព្រោះវានាំមកនូវការត្រួតពិនិត្យឃ្លានគំនិត — អ្នកអាចប្រាប់ម៉ូឌែលពីចំនួនការគិតដែលគួរធ្វើមុនពេលឆ្លើយ។ នេះធ្វើឱ្យយុទ្ធសាស្រ្ដបញ្ចូលសេចក្តីបញ្ជាភ្លាត់ៗជាងមុន និងជួយអ្នកយល់ថាតើពេលណាត្រូវប្រើវិធីណាមួយ។ អ្នកនឹងទទួលបានអត្ថប្រយោជន៍ពីកំណត់ត្រាគប់ Azure តិចជាងសម្រាប់ GPT-5.2 ប្រក្រោះម៉ូឌែល GitHub។ +យើងប្រើ GPT-5.2 ព្រោះវាផ្តល់មុខងារគ្រប់គ្រងការពិចារណា — អ្នកអាចប្រាប់ម៉ូដែលថាតើត្រូវគិតប៉ុន្មានមុនពេលឆ្លើយ។ វាធ្វើឲ្យយុទ្ធសាស្រ្តការរចនាព្យួរប្រកបដោយភាពច្បាស់លាស់និងជួយឲ្យអ្នកយល់ពេលណាដែលគួរប្រើគន្លងនីមួយៗ។ -## លក្ខខណ្ឌមូលដ្ឋាន +## លក្ខខណ្ឌមុន -- បានបញ្ចប់ Module 01 (ធនធាន Azure OpenAI បានដាក់ចេញ) -- ឯកសារ `.env` នៅថតឫសជាមួយព័ត៌មានសម្ភារៈ Azure (បានបង្កើតដោយ `azd up` ក្នុង Module 01) +- បានបញ្ចប់មុឌុល ០១ (ធនធាន Azure OpenAI ត្រូវបានដំឡើង) +- មានឯកសារ `.env` នៅក្នុងថតឫកមូល ដោយមានសញ្ញាសម្ងាត់ Azure (បង្កើតដោយ `azd up` ក្នុងមុឌុល ០១) -> **សម្គាល់៖** ប្រសិនបើអ្នកមិនទាន់បានបញ្ចប់ Module 01 សូមអនុវត្តការណែនាំដំណើរការដាក់ចេញនៅទីនោះជាមួយ។ +> **ចំណាំ:** ប្រសិនបើអ្នកមិនបានបញ្ចប់មុឌុល ០១ នោះ សូមអនុវត្តតាមសេចក្តីណែនាំដំឡើងនោះជាមុន។ -## ការយល់ដឹងអំពីវិស្វកម្មបញ្ចូលសេចក្តីបញ្ជា +## ការយល់ដឹងអំពីការរចនាព្យួរ -មូលដ្ឋាននៃវិស្វកម្មបញ្ចូលសេចក្តីបញ្ជាគឺខុសគ្នារវាងការណែនាំមិនច្បាស់លាស់និងការណែនាំច្បាស់លាស់ ដូចដែលការប្រៀបធៀបទីលើបានបង្ហាញ។ +នៅចំណុចមូលដ្ឋាន ការរចនាព្យួរក្នុងន័យក្លាហានគ្នារវាងការណែនាំអក្សរខុសច្បាស់ និងដែលច្បាស់លាស់ពិត ដូចដែលការប្រៀបធៀបខាងក្រោមបង្ហាញ។ What is Prompt Engineering? -វិស្វកម្មបញ្ចូលសេចក្តីបញ្ជាគឺការរចនាអត្ថបទបញ្ចូលដែលបានលើកទឹកចិត្តឱ្យអ្នកទទួលបានលទ្ធផលដែលអ្នកត្រូវការ។ វាមិនមែនបញ្ចូលសំនួរតែប៉ុណ្ណោះទេ — វាគឺការរៀបចំការស្នើរក្នុងយ៉ាងដែលម៉ូឌែលនឹងយល់យ៉ាងច្បាស់ថាអ្នកចង់បានអ្វី និងវិធីសាស្រ្ដដឹកជញ្ជូន។ +ការរចនាព្យួរគឺមានគោលបំណងបង្កើតអត្ថបទបញ្ចូលដែលបានទទួលលទ្ធផលដែលអ្នកត្រូវការ​យ៉ាងប្រាកដ។ វាមិនមែនថាជាការសួរពាក្យតែប៉ុណ្ណោះទេ — វាគឺជាការរៀបចំសំណើ ម្យ៉ាងណាឲ្យម៉ូដែលយល់ច្បាស់ថាអ្នកចង់បានអ្វីនិងរបៀបដើម្បីផ្តល់វា។ -គិតថាវាដូចជាការផ្តល់ការណែនាំទៅក្រុមការងារម្នាក់មួយ។ "ជួសជុលកំហុស" គឺមិនច្បាស់។ "ជួសជុលកំហុស null pointer នៅ UserService.java ជួរលេខ 45 ដោយបន្ថែមការត្រួតពិនិត្យ null" គឺច្បាស់លាស់។ ម៉ូឌែលភាសាចេះធ្វើដូចគ្នា — ការបញ្ជាក់ និងរចនាសម្ព័ន្ធមានសារៈសំខាន់។ +គិតជាប្រភេទការផ្ដល់ការណែនាំទៅមិត្តរួមការងារ៖ “ជួសជុលកំហុស” គឺមិនច្បាស់លាស់ហើយ។ “ជួសជុលកំហុស null pointer ក្នុង UserService.java ជួរ ៤៥ ដោយបន្ថែមការត្រួតពិនិត្យ null” គឺច្បាស់លាស់។ ម៉ូដែលភាសារងារដូចគ្នា — លម្អិតផ្ទាល់ខ្លួន និងរចនាសម្ព័ន្ធមានសារៈសំខាន់។ -រូបភាពខាងក្រោមបង្ហាញពីរបៀបដែល LangChain4j បង្កើតការតភ្ជាប់ —ភ្ជាប់គំរូសំណង់របស់អ្នកទៅម៉ូឌែលតាមរយៈប្លុកសាររចនាដូចជា SystemMessage និង UserMessage។ +គំនូរខាងក្រោមបង្ហាញពីរបៀបដែល LangChain4j ចូលរួមក្នុងរូបភាពនេះ —ភ្ជាប់រចនាបែបព្យួររបស់អ្នកទៅម៉ូដែលតាមរយៈគ្រឿងបន្លាស់ SystemMessage និង UserMessage។ How LangChain4j Fits -LangChain4j ផ្តល់អគ្គិសនីបច្ចេកវិទ្យា — ការតភ្ជាប់ម៉ូឌែល អង្គចងចាំ និងប្រភេទសារ — ខណៈពេលដែលរចនាប័ទ្មបញ្ចូលសេចក្តីបញ្ជាគឺអត្ថបទដែលបានរៀបចំយ៉ាងប្រុងប្រយ័ត្នដែលអ្នកផ្ញើតាមរយៈបច្ចេកវិទ្យានេះ។ ប្លុកសំខាន់គឺ `SystemMessage` (កំណត់អាកប្បកិរិយា និងតួរតំណាង AI) និង `UserMessage` (បញ្ចេញសំណើរពិតប្រាកដរបស់អ្នក)។ +LangChain4j ផ្ដល់ដល់ហេដ្ឋារចនាសម្ព័ន្ធ — ការតភ្ជាប់ម៉ូដែល, ការចងចាំ និងប្រភេទសារបញ្ចូល — ខណៈដែលរចនាបែបព្យួរគឺជាអត្ថបទដែលបានរៀបចំយ៉ាងម៉ត់ចត់ដែលអ្នកផ្ញើតាមរយៈហេដ្ឋារចនាសម្ព័ន្ធនោះ។ គ្រឿងបន្លាស់សំខាន់ៗមាន `SystemMessage` (ដែលកំណត់អកប្បកិរិយា និងតួនាទី AI) និង `UserMessage` (ដែលផ្ទុកសំណើពិតប្រាកដរបស់អ្នក)។ -## មូលដ្ឋានវិស្វកម្មបញ្ចូលសេចក្តីបញ្ជា +## មូលដ្ឋាននៃការរចនាព្យួរ -បច្ចេកទេសចម្បងប្រាំខាងក្រោមបង្កើតមូលដ្ឋាននៃវិស្វកម្មបញ្ចូលសេចក្តីបញ្ជាដែលមានប្រសិទ្ធភាព។ មួយៗសំដៅលើផ្នែកផ្សេងគ្នានៃរបៀបដែលអ្នកទំនាក់ទំនងជាមួយម៉ូឌែលភាសា។ +បច្ចេកទេសមូលដ្ឋានប្រាំដែលបង្ហាញខាងក្រោមបង្កើតមូលដ្ឋាននៃការរចនាព្យួរដោយប្រសិទ្ធិភាព។ ពួកវាដោះស្រាយពីមុខងារផ្សេងៗនៃរបៀបអ្នកទំនាក់ទំនងជាមួយម៉ូដែលភាសារ។ Five Prompt Engineering Patterns Overview -មុនចូលទៅកាន់រចនាប័ទ្មជាប់កម្រិតខ្ពស់ក្នុងម៉ូឌុលនេះ ខណៈពេលពិនិត្យវិធីសាស្រ្តបញ្ចូលសេចក្តីបញ្ជាមូលដ្ឋានប្រាំវា។ វាជាប្លុកសំបុត្រដែលអ្នកវិស្វកម្មបញ្ចូលសេចក្តីបញ្ជាគួរតែស្គាល់។ ប្រសិនបើអ្នកបានអនុវត្តពី [ម៉ូឌុលចាប់ផ្តើមរហ័ស](../00-quick-start/README.md#2-prompt-patterns) នោះអ្នកបានឃើញវាជាការអនុវត្ត — នេះគឺមូលដ្ឋានគំនិតតូចៗនៅពីក្រោយវា។ +មុនពិនិត្យមើលរចនាដែលមានកម្រិតខ្ពស់នៅក្នុងមុឌុលនេះ សូមពិនិត្យបច្ចេកទេសរៀបចំព្យួរមូលដ្ឋានប្រាំមួយ។ ពួកវាជាគ្រឿងដាក់បញ្ចូលនៃអ្នកដែលបំរើការរចនាព្យួរជាផ្លូវការមួយៗគួរតែស្គាល់។ -### បញ្ចូលសេចក្តីបញ្ជា​ពីគ្មានឧទាហរណ៍ +### ការរចនាព្យួរដោយគ្មានឧទាហរណ៍ -វិធីសាមញ្ញបំផុត៖ ផ្តល់ពិធីការណែនាំផ្ទាល់ទៅម៉ូឌែលដោយគ្មានឧទាហរណ៍ណាមួយ។ ម៉ូឌែលពឹងផ្អែកលើការបណ្តុះបណ្តាលរបស់ខ្លួនទាំងមូលដើម្បីយល់ និងអនុវត្តភារកិច្ច។ វារក្សាបានល្អសម្រាប់ការស្នើសូចូលសាមញ្ញដែលអាកប្បកិរិយាដែលរំពឹងទុកគឺច្បាស់។ +វិធីដ៏សាមញ្ញបំផុត៖ ផ្តល់ការណែនាំផ្ទាល់ទៅម៉ូដែលដោយមិនមានឧទាហរណ៍ណាមួយ។ ម៉ូដែលពឹងផ្អែកលើការបណ្តុះបណ្តាលទាំងមូលដើម្បីយល់និងអនុវត្តការងារ។ វាដំណើរការល្អសម្រាប់សំណើត្រង់ៗដែលសកម្មភាពរង់ចាំក៏ច្បាស់លាស់។ Zero-Shot Prompting -*ការណែនាំផ្ទាល់ដោយគ្មានឧទាហរណ៍ — ម៉ូឌែលយល់ពីភារកិច្ចពីការណែនាំតែប៉ុណ្ណោះ* +*ការណែនាំផ្តាច់មុខដោយគ្មានឧទាហរណ៍ — ម៉ូដែលបញ្ចេញការងារពីការណែនាំនោះតែមួយ* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// ចម្លើយ៖ "អវិជ្ជមាន" +// សេចក្ដីឆ្លើយតប: "វិជ្ជមាន" ``` - -**ពេលណាត្រូវប្រើ៖** ការបែងចែកសាមញ្ញ សំនួរផ្ទាល់ ការបកប្រែ ឬភារកិច្ចណាមួយដែលម៉ូឌែលអាចដំណើរការដោយគ្មានការណែនាំបន្ថែម។ -### បញ្ចូលសេចក្តីបញ្ជា​ពីមានឧទាហរណ៍少数 +**ពេលដែលគួរប្រើ:** ការដាក់ចំណាត់ថ្នាក់សាមញ្ញ សំណួរផ្ទាល់ ការប្រែសម្រួល ឬកម្មវិធីណាមួយដែលម៉ូដែលអាចដោះស្រាយដោយគ្មានការណែនាំបន្ថែម។ -ផ្តល់ឧទាហរណ៍ដែលបង្ហាញលំនាំដែលអ្នកចង់ឱ្យម៉ូឌែលអនុវត្ត។ ម៉ូឌែលរៀនពីទ្រង់ទ្រាយបញ្ចូល-លទ្ធផលដែលរំពឹងទុកពីឧទាហរណ៍របស់អ្នកហើយអនុវត្តទៅលើបញ្ចូលថ្មី។ វាជំនួយជាប់លាប់ខ្លាំងសម្រាប់ភារកិច្ចដែលទ្រង់ទ្រាយឬអាកប្បកិរិយាដែលមិនច្បាស់។ +### ការរចនាព្យួរដោយមានឧទាហរណ៍តិច + +ផ្តល់ឧទាហរណ៍ដែលបង្ហាញរចនាបែបដែលអ្នកចង់ឲ្យម៉ូដែលអនុវត្ត។ ម៉ូដែលរៀនពីទ្រង់ទ្រាយបញ្ចូល-បញ្ចេញដែលរំពឹងទុកពីឧទាហរណ៍របស់អ្នក ហើយអនុវត្តវាទៅលើទ្រង់ទ្រាយថ្មីៗ។ វាធ្វើឲ្យមានភាពសម្រាប់សកម្មភាពដែលបែបបទ ឬអាកប្បកិរិយា មិនច្បាស់លាស់។ Few-Shot Prompting -*រៀនពីឧទាហរណ៍ — ម៉ូឌែលស្គាល់លំនាំហើយអនុវត្តទៅលើបញ្ចូលថ្មី* +*រៀនពីឧទាហរណ៍ — ម៉ូដែលកំណត់គំរូនិងអនុវត្តទៅលើបញ្ចូលថ្មី* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**ពេលណាត្រូវប្រើ៖** ការបែងចែកផ្ទាល់ខ្លួន ទ្រង់ទ្រាយឥតបំភាន់ ភារកិច្ចជាតិសាស្ត្រពិសេស ឬពេលលទ្ធផលគ្មានសុវត្ថិភាពក្នុង Zero-Shot។ -### ខ្សែសង្វាក់គំនិត +**ពេលដែលគួរប្រើ:** ការដាក់ចំណាត់ថ្នាក់ផ្ទាល់ខ្លួន, ការតម្រឹមទ្រង់ទ្រាយឯកជន, ការងារជំនាញពិសេស, ឬពេលលទ្ធផល zero-shot មិនមានភាពថេរ។ + +### ខ្សែររបស់គំនិត -ស្នើឱ្យម៉ូឌែលបង្ហាញការគិតរបស់ខ្លួនជាជំហានៗ។ ជំនួសការជាបន្ទាត់ឆ្លើយតបភ្លាមៗ ម៉ូឌែលបំបែកបញ្ហាក្នុងជំហានតូចៗនិងដំណើរការតាមជំហាន។ វាជួយកែលម្អភាពត្រឹមត្រូវលើគណិតវិទ្យា តក្ក្រុវិទ្យា និងការយល់ដឹងពហុជំហាន។ +ស្នើឲ្យម៉ូដែលបង្ហាញការពិចារណាជំហានដោយជំហាន។ មិនត្រូវលោតទៅចម្លើយតាមបណ្តោះអាសន្នទេ ម៉ូដែលបំបែកបញ្ហានិងដំណើរការលម្អិតក្នុងមួយជំហាន។ វាប្រែប្រួលកម្រិតត្រឹមត្រូវសម្រាប់គណិតវិទ្យា តុល្យភាព និងការពិចារណាច្រើនជំហាន។ Chain of Thought Prompting -*ការគិតជាជំហានៗ — បំបែកបញ្ហាស្មុគស្មាញទៅជាជំហានត្រឹមត្រូវច្បាស់លាស់* +*ការពិចារណាជំហានៗ — បំបែកបញ្ហាស្មុគស្មាញជា​ជំហាន​ត្រឹមត្រូវ* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// ម៉ូដែលបង្ហាញថា៖ 15 - 8 = 7, បន្ទាប់មក 7 + 12 = 19 ផ្លែប៉ោម +// ម៉ូដែលបង្ហាញ៖ ១៥ - ៨ = ៧ ហើយបន្ទាប់មក ៧ + ១២ = ១៩ ផ្លែប៉ោម ``` - -**ពេលណាត្រូវប្រើ៖** បញ្ហាគណិតវិទ្យា ប្រដាប់ឡូហ្គិក ការកែលម្អកំហុស ឬភារកិច្ចណាមួយដែលបង្ហាញដំណើរការគិតជួយកែលម្អភាពត្រឹមត្រូវ និងទំនុកចិត្ត។ -### បញ្ចូលសេចក្តីបញ្ជាចូលតួ +**ពេលដែលគួរប្រើ:** បញ្ហាគណិតវិទ្យា, ប្រដាល់តុល្យភាព, ការជួសជុលកំហុស, ឬកម្មវិធីណាមួយដែលបង្ហាញដំណើរការពិចារណាធ្វើឲ្យមានភាពត្រឹមត្រូវនិងទុកចិត្ត។ -កំណត់តួឬបុគ្គលសម្រាប់ AI មុនពេលសួរសំណួរ។ វាផ្តល់បរិបទដែលរៀបចំសម្លេង ជម្រៅ និងមុខងារការតបសូម រៀបចំដូចជា "វិស្វករទូរគមនាគមន៍" ផ្តល់យោបល់ផ្សេងពី "អ្នកអភិវឌ្ឍន៍កម្រិតជប់លៀង" ឬ "អ្នកត្រួតពិនិត្យសុវត្ថិភាព"។ +### ការរចនាព្យួរផ្អែកលើតួនាទី + +កំណត់តួនាទី ឬម performedល្អមួយសម្រាប់ AI មុនសួរពាក្យ។ វាបង្កើតបរិបទដែលកំណត់សំលេង ជម្រៅ និងចំណុចផ្ដោតនៃចម្លើយ។ “ស្ថាបត្យករពហុបញ្ហា” ផ្តល់យោបល់ខុសពី “អភិវឌ្ឍន៍កម្រិតតិច” ឬ “អ្នកត្រួតពិនិត្យសុវត្ថិភាព”។ Role-Based Prompting -*កំណត់បរិបទ និងតួ — សំណួរដូចគ្នាបានចម្លើយខុសគ្នាដោយផ្អែកលើតួដែលបានផ្ដល់* +*កំណត់បរិបទនិងតួនាទី — សំណួរដូចគ្នាបានចម្លើយខុសគ្នាដែលពឹងផ្អែកលើតួនាទីដែលបានកំណត់* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**ពេលណាត្រូវប្រើ៖** ពិនិត្យកូដ បង្រៀន វិភាគពិសេសដែន ឬពេលដែលអ្នកត្រូវការចម្លើយពិសេសសម្រាប់កម្រិតជំនាញ ឬទស្សនវិស័យជាក់លាក់មួយ។ -### គំរូបញ្ចូលសេចក្តីបញ្ជា +**ពេលដែលគួរប្រើ:** ពិនិត្យកូដ, ការបង្រៀន, វិភាគជំនាញពិសេស, ឬពេលអ្នកត្រូវការឆ្លើយតបដែលសម្របសម្រួលនឹងកម្រិតជំនាញឬទស្សនៈជាក់លាក់។ + +### គំរូព្យួរ -បង្កើតបញ្ចូលសេចក្តីបញ្ជាដែលអាចប្រើជាថ្មីជាមួយចំណុចប្រែប្រាស់។ ជំនួសការសរសេរបញ្ចូលថ្មីរៀងរាល់ដង កំណត់គំរូមួយហើយបញ្ចូលតម្លៃផ្សេងៗ។ ថ្នាក់ `PromptTemplate` របស់ LangChain4j ធ្វើឱ្យវាងាយស្រួលជាមួយវចនាសាស្ត្រ `{{variable}}`។ +បង្កើតព្យួរដដែលអាចប្រើប្រាស់ឡើងវិញជាមួយកន្លែងសម្រាប់បញ្ចូលអថេរ។ មិនចាំបាច់សរសេរព្យួរថ្មីរៀងរាល់ដងទេ​ ប៉ុន្តែកំណត់គំរូមួយម្ដងហើយបញ្ចូលតម្លៃផ្សេងៗ។ ថ្នាក់ `PromptTemplate` របស់ LangChain4j ធ្វើឲ្យវាងាយស្រួលជាមួយវេយ្យាករណ៍ `{{variable}}`។ Prompt Templates -*បញ្ចូលដែលអាចប្រើឡើងវិញជាមួយចំណុចប្រែប្រាស់ — មួយគំរូ អ្នកប្រើជាច្រើនលក្ខណៈ* +*ព្យួរអាចប្រើឡើងវិញជាមួយកន្លែងសម្រាប់បញ្ចូលអថេរ — មួយគំរូ ដងៗណាស់* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**ពេលណាត្រូវប្រើ៖** ការស្នើសុំពីរប់បៀបធ្វើផ្សេងៗ ការប្រមូលផ្តុំ ការបង្កើតដំណើរការជាមួយ AI ឬស្ថានការណ៍ណាមួយដែលរចនាសម្ព័ន្ធបញ្ចូលសេចក្តីបញ្ជានៅស្ថិតនៅតែមិនប្រែប្រួល ប៉ុន្តែទិន្នន័យប្តូរតាម។ + +**ពេលដែលគួរប្រើ:** សំណួរប្រចាំមានបញ្ចូលផ្សេងៗ, ដំណើរការជាច្រើនក្នុងដំណើរការ, ការសង់បណ្ដាញ AI ដែលអាចប្រើឡើងវិញ, ឬស្ថានភាពណាដែលរចនាព្យួរដែលដូចគ្នានៅទម្រាំ ប៉ុន្តែទិន្នន័យផ្លាស់ប្តូរ។ --- -បច្ចេកទេសបួននេះផ្តល់ឱ្យអ្នកនូវឧបករណ៍រឹងមាំសម្រាប់ភារកិច្ចភាគច្រើននៃការបញ្ចូលសេចក្តីបញ្ជា។ បំណែកនៅសល់នៃម៉ូឌុលនេះបង្កើតលើវាជាមួយ **រចនាប័ទ្មជាប់កម្រិតខ្ពស់ប្រាំបួន** ដែលប្រើប្រយោជន៍គ្រប់លក្ខណៈ reasoning control, ការវាយតម្លៃខ្លួនឯង និងសមត្ថភាពលទ្ធផលដែលមានរចនា។ +បច្ចេកទេសប្រាំនេះផ្តល់ឲ្យអ្នកឧបករណ៍មូលដ្ឋានរឹងមាំសម្រាប់ភាគច្រើននៃការរចនាព្យួរ។ សំណុំរចនាគន្លងខ្ពស់ប្រាំបីខាងក្រោមបង្កើតឡើងលើកម្រិតនោះជាមួយនូវសមត្ថភាពគ្រប់គ្រងការពិចារណា ស្វ័យវាយតម្លៃ និងលទ្ធផលមានរចនាសម្ព័ន្ធរបស់ GPT-5.2។ -## រចនាប័ទ្មជាប់កម្រិតខ្ពស់ +## រចនាដែលមានកម្រិតខ្ពស់ -ក្រោយពីគ្របដណ្តប់មូលដ្ឋានហើយ យើងទៅទស្សនារចនាប័ទ្មជាប់កម្រិតខ្ពស់ប្រាំបួនដែលធ្វើឱ្យម៉ូឌុលនេះមានផ្ទេរជាក់លាក់។ មិនមែនគ្រប់បញ្ហាក៏មានរបៀបដូចគ្នាទេ។ សំនួរក៏មានបែបផែនឆ្លើយតបលឿន ក៏មានដែលត្រូវការតំលៃលឹម។ ម្នាក់ទទួលបានការគិតបង្ហាញវាសំខាន់ ខណៈអ្នកផ្សេងទៀតត្រូវការលទ្ធផលត្រឹមតែឃើញ។ រចនាប័ទ្មក្នុងក្រោមនេះត្រូវបានបង្កើតសម្រាប់ស្ថានការណ៍ផ្សេងៗ — ហើយការគ្រប់គ្រងគំនិតរបស់ GPT-5.2 ជួយធ្វើឱ្យភាពខុសគ្នាស្របតាមន័យកាន់តែច្បាស់។ +បន្ទាប់ពីបានគ្របដណ្តប់មូលដ្ឋាន តោះទៅរចនាខ្ពស់ប្រាំបីដែលធ្វើឲ្យមុឌុលនេះមានភាពពិសេស។ មុខងារមិនគ្រប់គ្នាជាមួយគ្នាទេ។ សំណួរខ្លះត្រូវការចម្លើយរហ័ស ខ្លះត្រូវការគិតជ្រៅ។ មានខ្លះត្រូវការការពិចារណាដែលអាចមើលឃើញ ខណៈដែលខ្លះត្រូវតែមានលទ្ធផលតែប៉ុណ្ណោះ។ រចនាផ្សេងៗខាងក្រោមត្រូវបានបង្កើតឡើងសម្រាប់ស្ថានភាពខ្លួនវិញៗ — ហើយសមត្ថភាពគ្រប់គ្រងការពិចារណារបស់ GPT-5.2 ធ្វើឲ្យភាពខុសគ្នាទាំងនេះប្រែប្រួលច្បាស់រឹង។ Eight Prompting Patterns -*ទិដ្ឋភាពទូលំទូលាយនៃរចនាប័ទ្មបញ្ចូលសេចក្តីបញ្ជាប្រាំបួននិងករណីប្រើ* +*ភាពសង្ខេបនៃរចនាព្យួរចំនួនប្រាំបី និងករណីប្រើប្រាស់របស់ពួកវា* -GPT-5.2 បន្ថែមវិមាត្រថ្មីមួយទៀតទៅរចនាប័ទ្មទាំងនេះ៖ *ការគ្រប់គ្រងគំនិត*។ ស្លាយខាងក្រោមបង្ហាញពីរបៀបដែលអ្នកអាចកំណត់កំរិតការគិតរបស់ម៉ូឌែល — ចាប់ពីចម្លើយលឿន ផ្ទាល់ ទៅការវិភាគជ្រៅ។ +GPT-5.2 បន្ថែមទំហំបន្ថែមមួយទៅលើរចនានេះ៖ *ការគ្រប់គ្រងការពិចារណា*។ អ្នកអាចបត់បែនភាពព្យួររបស់ម៉ូដែលតាមការគិត — ពីចម្លើយរហ័ស ត្រង់ទៅការវិភាគជ្រៅ ច្បាស់លាស់។ Reasoning Control with GPT-5.2 -*ការគ្រប់គ្រងគំនិតរបស់ GPT-5.2 អនុញ្ញាតឱ្យអ្នកកំណត់ថា ម៉ូឌែលគួរគិតប៉ុន្មាន — ចាប់ពីចម្លើយផ្ទាល់លឿនទៅការស្រាវជ្រាវជ្រៅ* +*ការគ្រប់គ្រងការពិចារណាដោយ GPT-5.2 អ្នកអាចបញ្ជាក់ថាជំហានគិតមួយៗត្រូវធ្វើប៉ុន្មាន — ពីចម្លើយរហ័សប៉ុណ្ណោះ ទៅការស្វែងយល់ជ្រៅ* -**ទំនិញទាប (លឿននិងផ្តោតសំខាន់)** - សម្រាប់សំណួរសាមញ្ញដែលអ្នកចង់បានចម្លើយលឿនផ្ទាល់។ ម៉ូឌែលគិតតិចបំផុត - មិនលើសពី 2 ជំហាន។ ប្រើសម្រាប់គណនាចំនួន ស្វែងរក ឬសំនួរសាមញ្ញដោយផ្ទាល់។ +**ចំណង់ចំណូលចិត្តទាប (រហ័ស និងផ្ដោតលើ)** - សម្រាប់សំណួរសាមញ្ញដែលអ្នកចង់បានចម្លើយរហ័សផ្ទាល់។ ម៉ូដែលធ្វើការពិចារណា​តិចបំផុត - មិនលើសពី ២ ជំហាន។ ប្រើសម្រាប់ការគណនា ស្វែងរក ឬសំណួរដែលត្រង់ៗ។ ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> 💡 **ស្វែងយល់ជាមួយ GitHub Copilot:** បើក [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ហើយសួរ៖ -> - "តើភាពខុសគ្នារវាងទំនិញទាបនិងខ្ពស់ក្នុងរចនាប័ទ្មបញ្ចូលសេចក្តីបញ្ជាជា​បែបណា?" -> - "តើតែ XML ក្នុងបញ្ចូលសេចក្តីបញ្ជាជួយរៀបចំចម្លើយ AI យ៉ាងដូចម្តេច?" -> - "ពេលណាអ្នកគួរប្រើរចនាប័ទ្មដឹកនាំខ្លួនឯងប្រើប្រាស់ជំនួសវិធីសាស្រ្តផ្ទាល់?" -**ទំនិញខ្ពស់ (ជ្រៅនិងពេញលេញ)** - សម្រាប់បញ្ហាស្មុគស្មាញដែលអ្នកចង់បានការវិភាគពេញលេញ។ ម៉ូឌែលស្រាវជ្រាវយ៉ាងពេញលេញហើយបង្ហាញការគិតលម្អិត។ ប្រើសម្រាប់រចនាបระบบ ការសម្រេចចិត្តអាគារឬស្រាវជ្រាវស្មុគស្មាញ។ +> 💡 **សាកល្បងជាមួយ GitHub Copilot:** បើក [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ហើយសួរ៖ +> - "អ្វីខុសគ្នារវាងចំណង់ចំណូលចិត្តទាបនិងខ្ពស់ក្នុងរៀបចំព្យួរមានអ្វីខ្លះ?" +> - "Tag XML នៅក្នុងព្យួរជួយរចនាចម្លើយAI ដោយរបៀបណា?" +> - "ពេលណាខ្ញុំគួរប្រើរចនាការពិចារណាផ្ទាល់ខ្លួន ប្រៀបនឹងការណែនាំផ្តាច់មុខ?" + +**ចំណង់ចំណូលចិត្តខ្ពស់ (ជ្រៅ និងប្រុងប្រយ័ត្ន)** - សម្រាប់បញ្ហាស្មុគស្មាញដែលចង់បានការវិភាគផ្ដឹមផ្ដាច់។ ម៉ូដែលធ្វើការស្វែងយល់ជ្រៅហើយបង្ហាញការពិចារណាជាផ្នែកលម្អិត។ ប្រើសម្រាប់រចនាប្រព័ន្ធ ការសម្រេចចិត្តរចនា ឬស្រាវជ្រាវស្មុគស្មាញ។ ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**ការអនុវត្តភារកិច្ច (ដំណើរការជំហានបន្តិចបន្តិច)** - សម្រាប់ដំណើរការជាច្រើនជំហាន។ ម៉ូឌែលផ្តល់ផែនការ ផ្សាយពាណិជ្ជកម្មជំហានៗហើយចុងក្រោយផ្តល់សេចក្តីសង្ខេប។ ប្រើសម្រាប់ការផ្លាស់ប្តូរ ការអនុវត្ត ឬដំណើរការជាច្រើនជំហានណាមួយ។ + +**ការអនុវត្តភារកិច្ច (ដំណើរការជំហានលម្អិត)** - សម្រាប់ដំណើរការច្រើនជំហាន។ ម៉ូដែលផ្តល់គម្រោងជាមុន រាយការណ៍ជំហានក្នុងមួយជំហាន បន្ទាប់មកផ្តល់សម្រួលរាយការណ៍។ ប្រើសម្រាប់ការផ្លាស់ប្តូរ សម្រេចការអនុវត្ត ឬដំណើរការច្រើនជំហានណាមួយ។ ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -ការបញ្ចូលសេចក្តីបញ្ជារចនាប័ទ្ម Chain-of-Thought ស្នើម៉ូឌែលបង្ហាញដំណើរការគិតរបស់ខ្លួនយ៉ាងច្បាស់លាស់ កែលម្អភាពត្រឹមត្រូវសម្រាប់ភារកិច្ចស្មុគស្មាញ។ ការបំបែកជាជំហានជួយទាំងមនុស្ស និង AI យល់ពីលក្ខណ:ត្រឹមត្រូវ។ -> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** សួរអំពីរចនាប័ទ្មនេះ៖ -> - "តើធ្វើដូចម្តេចដើម្បីឲ្យរចនាប័ទ្មអនុវត្តភារកិច្ចប្រកបដោយដំណើរការផ្លាស់ប្តូរជាប្រចាំ?" -> - "តើអ្វីទៅជាបំណងល្អបំផុតសម្រាប់ការរៀបចំការណែនាំឧបករណ៍ក្នុងកម្មវិធីផលិតកម្ម?" -> - "តើធ្វើដូចម្តេចដើម្បីចាប់យកនិងបង្ហាញការអាប់ដេតដំណោយកំណត់មធ្យមក្នុង UI?" +ការរចនាព្យួរបែប Chain-of-Thought ស្នើឲ្យម៉ូដែលបង្ហាញដំណើរការពិចារណារបស់ខ្លួន ដើម្បីបង្កើនភាពត្រឹមត្រូវសម្រាប់បញ្ហាស្មុគស្មាញ។ ការបំបែកជំហានៗនេះជួយឲ្យមនុស្ស និង AI សំរាប់យល់ល្បឿនតុល្យភាព។ -រូបភាពខាងក្រោមបង្ហាញដំណើរការ Plan → Execute → Summarize នេះ។ +> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** សួរអំពីរចនានេះ៖ +> - "តើខ្ញុំអាចកែប្រែរចនាអនុវត្តភារកិច្ចសម្រាប់ប្រតិបត្តិការវែងយូរបែបណា?" +> - "អ្វីជាប្រសិទ្ធិភាពល្អបំផុតសម្រាប់រៀបចំការណែនាំឧបករណ៍នៅកម្មវិធីផលិត?" +> - "តើខ្ញុំអាចចាប់យក និងបង្ហាញការកំណត់សំណើរវគ្គកណ្តាលនៅ UI ដោយរបៀបណា?" + +គំនូរខាងក្រោមបង្ហាញដំណើរការគ្រោង→អនុវត្ត→សង្ខេប។ Task Execution Pattern -*ដំណើរការចាប់ផែនការ → អនុវត្ត → សង្ខេបសម្រាប់ភារកិច្ចជាច្រើនជំហាន* +*ដំណើរការគ្រោង→អនុវត្ត→សង្ខេបសម្រាប់ភារកិច្ចច្រើនជំហាន* -**កូដដែលអាចធ្វើចិត្តខ្លួនឯង** - សម្រាប់បង្កើតកូដមានគុណភាពផលិតកម្ម។ ម៉ូឌែលបង្កើតកូដដែលគោរពស្តង់ដារផលិតកម្ម ជាមួយការគ្រប់គ្រងកំហុសត្រឹមត្រូវ។ ប្រើពេលបង្កើតមុខងារថ្មី ឬសេវាកម្ម។ +**កូដស្វ័យប្រវត្តិក្នុងការពិចារណា** - សម្រាប់បង្កើតកូដគុណភាពផលិតកម្ម។ ម៉ូដែលបង្កើតកូដតាមស្តង់ដារផលិតកម្មជាមួយចំណាយកិច្ចការពារ ការប៉ះពាល់កំហុស។ ប្រើសម្រាប់កសាងកម្មវិធី ឬសេវាកម្មថ្មី។ ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -រូបភាពខាងក្រោមបង្ហាញវដ្តកែលម្អបន្តិចបន្តួចនេះ — បង្កើត វាយតម្លៃ សង្កេតហ្វាគសន៍ និងកែសម្រួលរហូតដល់កូដសម្របសម្រួលតាមស្តង់ដារផលិតកម្ម។ + +គំនូរខាងក្រោមបង្ហាញរចនាចម្រាស់ហើយពិចារណាជាថ្មីរបៀបផ្សំគ្នា — បង្កើតវា វាយតម្លៃ សម្គាល់ខ្សោយ ទៅកែប្រែរហូតដល់កូដឆ្លងតាមស្តង់ដារផលិតកម្ម។ Self-Reflection Cycle -*វដ្តកែលម្អបន្តិចបន្តួច - បង្កើត, វាយតម្លៃ, សង្កេតហ្វាគសន៍, កែលម្អ, ធ្វើម្ដងទៀត* +*ចម្រាស់ឡើងវិញជាថ្មី — បង្កើត វាយតម្លៃ សម្គាល់បញ្ហា កែប្រែ ហើយធ្វើម្តងទៀត* -**ការវិភាគរចនាសម្ព័ន្ធ** - សម្រាប់ការវាយតម្លៃមានរចនាសម្ព័ន្ធ។ ម៉ូឌែលពិនិត្យកូដដោយប្រើស៊ុមស្តង់ដារត្រឹមត្រូវ (ភាពត្រឹមត្រូវ, វិធានការ, សមត្ថភាព, សុវត្ថិភាព, តម្រូវបន្ថែមសមត្ថភាព)។ ប្រើសម្រាប់ការពិនិត្យកូដ ឬការវាយតម្លៃគុណភាព។ +**វិភាគដែលមានរចនាសម្ព័ន្ធ** - សម្រាប់ការវាយតម្លៃប្រចាំ។ ម៉ូដែលពិនិត្យកូដដោយប្រើសំណុំគោលការណ៍ថេរ (ត្រឹមត្រូវ, អនុវត្តន៍, សមត្ថភាព, សុវត្ថិភាព និងអាចថែទាំបាន)។ ប្រើសម្រាប់ពិនិត្យកូដ ឬការវាយតម្លៃគុណភាព។ ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** សួរអំពីការវិភាគរចនាសម្ព័ន្ធ៖ -> - "តើធ្វើដូចម្តេចដើម្បីប្ដូរនីតិវិធីវិភាគសម្រាប់ប្រភេទនានាការពិនិត្យកូដ?" -> - "តើវិធីល្អបំផុតក្នុងការបំលែង និងអនុវត្តលទ្ធផលដែលមានរចនាសម្ព័ន្ធជាកម្មវិធី?" -> - "តើធ្វើដូចម្តេចដើម្បីធានាថាជំហិនភាពធ្ងន់ធ្ងរត្រូវបានគ្រប់គ្រាន់នៅក្នុងសម័យពិនិត្យខុសត្រូវ?" -រូបភាពខាងក្រោមបង្ហាញពីរបៀបដែលស៊ុមនេះរៀបចំការពិនិត្យកូដជាបណ្ដាប័ណ្ណដូចស៊ុមដែលមានជំហានធ្ងន់ធ្ងរជាប់បន្ត។ +> **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** សួរអំពីវិភាគដែលមានរចនាសម្ព័ន្ធ៖ +> - "តើខ្ញុំអាចប្ដូរប្រព័ន្ធវិភាគសម្រាប់ប្រភេទពិនិត្យកូដផ្សេងៗយ៉ាងដូចម្តេច?" +> - "អ្វីជាវិធីល្អបំផុតក្នុងការបញ្ចូលនិងដំណើរការលទ្ធផលមានរចនាសម្ព័ន្ធដោយកម្មវិធី?" +> - "តើធ្វើយ៉ាងដូចម្តេចដើម្បីធានាកម្រិតធ្ងន់ធ្ងរមានភាពថេររវាងវគ្គពិនិត្យផ្សេងៗ?" + +គំនូរខាងក្រោមបង្ហាញពីរបៀបដែលប្រព័ន្ធដែលមានរចនាសម្ព័ន្ធ ចាត់ចែងការពិនិត្យកូដជាក្រុមប្រភេទមានកម្រិតធ្ងន់ធ្ងរ។ Structured Analysis Pattern -*ស៊ុមសម្រាប់ការពិនិត្យកូដជាប់លាប់មានជំហាន់ធ្ងន់ធ្ងរ* +*ប្រព័ន្ធសម្រាប់ការពិនិត្យកូដដោយមានកម្រិតធ្ងន់ធ្ងរត្រឹមត្រូវ* -**ជជែកចល័តច្រើនជុំ** - សម្រាប់ការជជែកដែលត្រូវការបរិបទ។ ម៉ូឌែលចងចាំសារមុនៗហើយសាងសង់លើវាទៀត។ ប្រើសម្រាប់ជំនួយផ្ទាល់ សម័យសំណួរឆ្លើយស្មុគស្មាញ។ +**ការផ្លាស់ប្តូរច្រើនជុំ** - សម្រាប់ការពិភាក្សាត្រូវការបរិបទ។ ម៉ូដែលចងចាំសារ​មុនៗ ហើយបន្ថែមលើពួកវា។ ប្រើសម្រាប់សម័យជំនួយអន្តរកម្ម ឬ Q&A ស្មុគស្មាញ។ ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -រូបភាពខាងក្រោមបង្ហាញពីរបៀបដែលបរិបទការជជែកជាប់ជាលំហូរនិងរបៀបដែលវាត្រូវបានចំនួន token របស់ម៉ូឌែល។ + +គំនូរខាងក្រោមបង្ហាញពីរបៀបដែលបរិបទការពិភាក្សាបន្ថែមជាបន្តបន្ទាប់រហូតដល់ដែនកំណត់កូដ Token ។ Context Memory -*របៀបដែលបរិបទជជែកបូកបន្ថែមនៅលើជុំជាដំណាក់កាលរហូតដល់ដល់កំណត់ token* -**ការពិចារណាជាដំណាក់កាល** - សម្រាប់បញ្ហាដែលត្រូវការតុល្យ្យវិចារ​ដែលមើលឃើញបាន។ ម៉ូដែលបង្ហាញការពិចារណាដែលច្បាស់លាស់សម្រាប់ជំហាននីមួយៗ។ ប្រើវាសម្រាប់បញ្ហាគណិតវិទ្យា បញ្ហាជាលំហាត់ ឬពេលដែលអ្នកត្រូវការយល់ដឹងពីដំណើរការគិត។ +*របៀបកំណត់បរិបទការពិភាក្សាបន្ថែមកើនឡើងជាច្រើនជុំរហូតដល់ដែនកំណត់នៃកូដ Token* + +**ការពិចារណាជំហានដោយជំហាន** - សម្រាប់បញ្ហាត្រូវការតុល្យភាពដែលអាចមើលឃើញ។ ម៉ូដែលបង្ហាញការពិចារណាច្បាស់លាស់សម្រាប់ជំហាននីមួយៗ។ ប្រើសម្រាប់បញ្ហាគណិតវិទ្យា ប្រដាល់តុល្យភាព ឬពេលអ្នកចង់យល់ដំណើរការពិចារណា។ ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -រូបភាពខាងក្រោមបង្ហាញពីរបៀបដែលម៉ូដែលបំបែកបញ្ហាទៅជាជំហានតុល្យ្យវិចារតាមលំដាប់លេខយ៉ាងច្បាស់លាស់។ +គំនូរខាងក្រោមបង្ហាញម៉ូដែលបំបែកបញ្ហាជាចំនុចបញ្ជាក់លំអិតមានលេខរៀងច្បាស់។ Step-by-Step Pattern +*បំបែកបញ្ហាទៅជជំហានត្រឹមត្រូវយ៉ាងច្បាស់* -*ការបែងចែកបញ្ហាទៅជាជំហានតុល្យ្យវិចារច្បាស់លាស់* - -**ការបញ្ចេញលទ្ធផលដែលមានកំណត់** - សម្រាប់ចម្លើយដែលមានតំរូវការរចនាសម្ព័ន្ធជាក់លាក់។ ម៉ូដែលអនុវត្តតាមច្បាប់រចនាសម្ព័ន្ធ និងប្រវែងយ៉ាងតឹងរ៉ឹង។ ប្រើវាសម្រាប់ជាអត្ថបទសង្ខេប ឬពេលដែលអ្នកត្រូវការរចនាសម្ព័ន្ធលទ្ធផលយ៉ាងត្រឹមត្រូវ។ +**លទ្ធផលមានកំណត់** - សម្រាប់ចម្លើយដែលមានលក្ខខណ្ឌទ្រង់ទ្រាយជាក់លាក់។ ម៉ូដែលអនុវត្តដោយត្រឹមត្រូវតាមលក្ខខណ្ឌនិងប្រវែង។ ប្រើសម្រាប់សេចក្តីសង្ខេបឬពេលដែលអ្នកត្រូវការរចនាសម្ព័ន្ធលទ្ធផលច្បាស់លាស់។ ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -រូបភាពខាងក្រោមបង្ហាញពីរបៀបដែលលក្ខខណ្ឌបញ្ជារម៉ូដែលឲ្យផលិតលទ្ធផលដែលគោរពតាមរចនាសម្ព័ន្ធ និងប្រវែងដោយតឹងរ៉ឹង។ +រូបភាពខាងក្រោមបង្ហាញពីរបៀបដែលលក្ខខណ្ឌការ​បញ្ជានាំម៉ូដែលឲ្យបង្កើតលទ្ធផលដែលគោរពត្រឹមត្រូវទៅលក្ខខណ្ឌទ្រង់ទ្រាយនិងប្រវែងរបស់អ្នក។ Constrained Output Pattern -*ការជំរុញកំណត់រចនាសម្ព័ន្ធ ប្រវែង និងតំរូវការរចនាសម្ព័ន្ធ* +*ការតម្រូវលក្ខខណ្ឌទ្រង់ទ្រាយ ប្រវែង និងរចនាសម្ព័ន្ធជាក់លាក់* -## បើកដំណើរការ​ Application +## ចាប់ផ្តើមកម្មវិធី -**ផ្ទៀងផ្ទាត់ការបញ្ចូលប្រព័ន្ធ៖** +**ផ្ទៀងផ្ទាត់ការដំឡើង៖** -ធានាថា​ឯកសារ `.env` មាននៅក្នុងថតមូលដ្ធានជាមួយឯកសារទទួលស្គាល់ Azure (បានបង្កើតនៅម៉ូឌុល 01)។ ប្រើពាក្យបញ្ជានេះពីថតម៉ូឌុល (`02-prompt-engineering/`)៖ +ធ្វើអោយប្រាកដថា​ឯកសារ `.env` មាននៅក្នុងថតដើមជាមួយអត្តសញ្ញាណ Azure (បានបង្កើតនៅម៉ូឌុល ០១)។ រត់ពីថតម៉ូឌុល (`02-prompt-engineering/`)៖ **Bash:** ```bash @@ -439,46 +439,46 @@ cat ../.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, **PowerShell:** ```powershell -Get-Content ..\.env # ត្រូវបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **ចាប់ផ្តើមកម្មវិធី៖** -> **សម្គាល់៖** ប្រសិនបើអ្នកបានចាប់ផ្តើមកម្មវិធីទាំងអស់ដោយប្រើ `./start-all.sh` ពីថតមូលដ្ឋាន (ដូចបានពិពណ៌នារួចរាល់នៅម៉ូឌុល 01) ម៉ូឌុលនេះគឺកំពុងដំណើរការនៅលើរន្ធ 8083។ អ្នកអាចរំលងពាក្យបញ្ជាចាប់ផ្តើមខាងក្រោម ហើយទៅកាន់ http://localhost:8083 ត្រង់។ +> **សំណើចំណាំ៖** ប្រសិនបើអ្នកបានចាប់ផ្តើមកម្មវិធីទាំងអស់រួចដោយការប្រើប្រាស់ `./start-all.sh` ពីថតដើម (ដូចបានពិពណ៌នានៅម៉ូឌុល ០១) ម៉ូឌុលនេះស្ថិតនៅលើព្រឹត្តិការណ៍ ៨០៨៣រួចហើយ។ អ្នកអាចបដិសេធការបញ្ជារចាប់ផ្តើមខាងក្រោម ហើយលោតទៅ http://localhost:8083 តែប៉ុណ្ណោះ។ -**ជម្រើសទី 1៖ ប្រើ Spring Boot Dashboard (ណែនាំសម្រាប់អ្នកប្រើ VS Code)** +**ជម្រើសទី ១: ប្រើ Spring Boot Dashboard (ណែនាំសម្រាប់អ្នកប្រើ VS Code)** -dev container រួមបញ្ចូលផ្នែកពង្រីក Spring Boot Dashboard ដែលផ្តល់ឱ្យអ្នកនូវផ្ទៃមុខភ្ជាប់មើល ហើយគ្រប់គ្រងកម្មវិធី Spring Boot ទាំងអស់។ អ្នកអាចរកឃើញវានៅក្នុង Activity Bar ខាងឆ្វេងក្នុង VS Code (សូមស្វែងរករូបតំណាង Spring Boot)។ +dev container រួមបញ្ចូលផ្នែកបន្ថែម Spring Boot Dashboard ដែលផ្ដល់នូវចំណុចប្រទាក់មើលទិដ្ឋភាពដើម្បីគ្រប់គ្រងកម្មវិធី Spring Bootទាំងអស់។ អ្នកអាចរកឃើញវានៅក្នុង Activity Bar នៅខាងឆ្វេងរបស់ VS Code (ស្វែងរករូបតំណាង Spring Boot) ។ ពី Spring Boot Dashboard អ្នកអាច៖ -- មើលកម្មវិធី Spring Boot ទាំងអូលដែលមាននៅក្នុងកន្លែងធ្វើការ -- ចាប់ផ្តើម/ផ្អាកកម្មវិធីដោយមួយចុច -- មើលកំណត់ហេតុកម្មវិធីដោយពេលវេលាពិត +- មើលកម្មវិធី Spring Boot ទាំងអស់ដែលមានក្នុងលំនាំការងារ +- ចាប់ផ្តើម/ឈប់កម្មវិធីបានដោយចុចតែមួយ +- មើលកំណត់ហេតុកម្មវិធីនៅពេលពិត - តាមដានស្ថានភាពកម្មវិធី -គ្រាន់តែនៅលើប៊ូតុងលេងជិត "prompt-engineering" ដើម្បីចាប់ផ្តើមម៉ូឌុលនេះ ឬចាប់ផ្តើមម៉ូឌុលទាំងអស់រៀងៗខ្លួន។ +គ្រាន់តែចុចប៊ូតុងបញ្ចូលនៅជាប់ឈ្មោះ "prompt-engineering" ដើម្បីចាប់ផ្តើមម៉ូឌុលនេះ ឬចាប់ផ្តើមម៉ូឌុលទាំងអស់ក្នុងលើកមួយ។ Spring Boot Dashboard -*Spring Boot Dashboard ក្នុង VS Code — ចាប់ផ្តើម បញ្ឈប់ និងតាមដានម៉ូឌុលទាំងអស់ពីកន្លែងតែមួយ* +*Spring Boot Dashboard នៅក្នុង VS Code — ចាប់ផ្តើម ឈប់ និងតាមដានម៉ូឌុលទាំងអស់ពីកន្លែងមួយ* -**ជម្រើសទី 2៖ ប្រើ shell scripts** +**ជម្រើសទី ២: ប្រើ script shell** -ចាប់ផ្តើមកម្មវិធីបណ្តាញទាំងអស់ (ម៉ូឌុល 01-04): +ចាប់ផ្តើមកម្មវិធីបណ្ដាញទាំងអស់ (ម៉ូឌុល ០១-០៤): **Bash:** ```bash -cd .. # ពីថតដើម +cd .. # ពីថតឬស ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # ពីថតមូលដ្ឋាន +cd .. # ពីថតឫស .\start-all.ps1 ``` -ឬចាប់ផ្តើមតែម៉ូឌុលនេះ៖ +ឬចាប់ផ្តើមតែម៉ូឌុលនេះប៉ុណ្ណោះ: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -ស្គ្រីបទាំងពីរនេះ ប្រើប្រាស់អថេរបរិស្ថានពីឯកសារ `.env` នៅថតមូលដ្ឋានដោយស្វ័យប្រវត្តិ និងនឹងសង់ JAR ប្រសិនបើវាមិនមានទេ។ +script ទាំងពីរនេះប្រើប្រាស់បរិយាកាសអថេរជាដំណើរការពីឯកសារ `.env` នៅថតដើម ដូច្នេះវានឹងធ្វើការបង្កើត JAR ដែលមិនមាន។ -> **សម្គាល់៖** ប្រសិនបើអ្នកចូលចិត្តសង់ម៉ូឌុលទាំងអស់ដោយដៃមុនចាប់ផ្តើម៖ +> **សំណើចំណាំ៖** ប្រសិនបើអ្នកចង់បង្កើតម៉ូឌុលទាំងអស់ដោយដៃមុនចាប់ផ្តើម៖ > > **Bash:** > ```bash @@ -508,15 +508,15 @@ cd 02-prompt-engineering > mvn clean package -DskipTests > ``` -បើក http://localhost:8083 ក្នុងកម្មវិធីរុករករបស់អ្នក។ +បើក http://localhost:8083 នៅក្នុងកម្មវិធីរកមើលវេបរបស់អ្នក។ **ដើម្បីបញ្ឈប់៖** **Bash:** ```bash -./stop.sh # មុឌូលនេះតែប៉ុណ្ណោះ +./stop.sh # ម៉ូឌុលនេះតែប៉ុណ្ណោះ # ឬ -cd .. && ./stop-all.sh # មុឌូលទាំងអស់ +cd .. && ./stop-all.sh # ម៉ូឌុលទាំងអស់ ``` **PowerShell:** @@ -526,71 +526,73 @@ cd .. && ./stop-all.sh # មុឌូលទាំងអស់ cd ..; .\stop-all.ps1 # ម៉ូឌុលទាំងអស់ ``` -## រូបភាពនៃកម្មវិធី +## រូបថតថេបកម្មវិធី -នេះជាបន្ទះផ្ទៃមុខសំខាន់នៃម៉ូឌុល prompt engineering ដែលអ្នកអាចសាកល្បងលេងជាមួយលំនាំប្រាំបួនជាប់គ្នា។ +នេះជាចំណុចប្រទាក់មុខរបស់ម៉ូឌុល prompt engineering ដែលអ្នកអាចសាកល្បងជាមួយគំរូទាំងប្រាំបួននៅជេីងមួយ។ Dashboard Home -*បន្ទះផ្ទៃមុខសំខាន់បង្ហាញលំនាំបួននៃ prompt engineering ជាមួយលក្ខណៈនិងករណីប្រើប្រាស់របស់ពួកវា* +*ផ្ទាំងបញ្ជាពហុមុខងារបង្ហាញគំរូជា ៨ នៃ prompt engineering ជាមួយលក្ខណៈ និងករណីប្រើប្រាស់* -## ស្វែងយល់អំពីលំនាំបួន +## ការស្វែងយល់ពីគំរូផ្សេងៗ -ផ្ទៃមុខវេបសាយអនុញ្ញាតអ្នកសាកល្បងយុទ្ធសាស្រ្ត prompting ផ្សេងៗគ្នា។ លំនាំបួននីមួយៗដោះស្រាយបញ្ហាផ្សេងៗ - សាកល្បងវាដើម្បីមើលពេលណាលំនាំបួនណាមួយសំខាន់។ +ចំណុចប្រទាក់វេបអនុញ្ញាតឱ្យអ្នកសាកល្បងនូវយុទ្ធសាស្រ្តការស្នមន៏ខុសៗគ្នា។ គំរូមួយៗដោះស្រាយបញ្ហាផ្សេងៗគ្នា - សាកល្បងមើលពេលណាដំណាក់ទ្រួយនីមួយៗបង្ហាញ។ -> **សម្គាល់៖ Streaming ទល់នឹង Non-Streaming** — ទំព័រលំនាំបួនជាមួយប៊ូតុងពីរដូចជា **🔴 Stream Response (Live)** និងជម្រើស **Non-streaming**។ Streaming ប្រើ Server-Sent Events (SSE) ដើម្បីបង្ហាញ token ដំណើរការពេលវេលាពិត ខណៈម៉ូដែលបង្កើតវា ដូច្នេះអ្នកឃើញការរីកចម្រើនភ្លាមៗ។ ជម្រើស non-streaming រង់ចាំចំលើយពេញលេញ មុនបង្ហាញវា។ សម្រាប់ prompt ដែលបង្កការគិតជ្រៅ (ឧ. High Eagerness, Self-Reflecting Code) ការហៅ non-streaming អាចពេលយូរ - មួយចំនួនជាទី ២០ - គ្មានមតិបង្ហាញទេ។ **ប្រើ streaming នៅពេលសាកល្បង prompt ស្មុគស្មាញ** ដូច្នេះអ្នកអាចឃើញម៉ូដែលដំណើរការនិងជៀសវាងការយល់ថា​សំណើត្រូវបានផុតកំណត់ពេល។ +> **សំណើចំណាំ៖ Streaming ប្រៀបធៀប Non-Streaming** — ទំព័រកម្មវិធីនីមួយៗមានប៊ូតុងពីរជា **🔴 Stream Response (Live)** និងជម្រើស **Non-streaming**។ Streaming ប្រើ Server-Sent Events (SSE) ដើម្បីបង្ហាញសញ្ញាទៅវិញឆាប់ៗពេលម៉ូដែលបង្កើតវា ដូច្នេះអ្នកឃើញភាពជោគជ័យភ្លាមៗ។ ជម្រើស Non-streaming រង់ចាំការឆ្លើយទាំងមូលមុនបង្ហាញ។ សម្រាប់បញ្ជាការដែលត្រូវការសុខចិត្តជ្រៅ (ឧ. High Eagerness, Self-Reflecting Code) ការហៅ non-streaming អាចយឺតណាស់ — មិនមានមតិយោបល់ឲ្យឃើញផង។ **ប្រើ streaming ពេលសាកល្បងបញ្ចូលធ្វើការលំបាក** ដើម្បីឲ្យឃើញម៉ូដែលយកការ និងចៀសវាងអត្តចរិតថា សំណើមានពេលវេលាផុតកំណត់។ > -> **សម្គាល់៖ តំរូវការម៉ាស៊ីនរុករក** — លក្ខណៈ streaming ប្រើប្រាស់ Fetch Streams API (`response.body.getReader()`) ដែលត្រូវការ Browser ពេញលេញ (Chrome, Edge, Firefox, Safari)។ វាមិនដំណើរការនៅក្នុង Simple Browser របស់ VS Code ទេ ព្រោះ webview របស់វាមិនគាំទ្រ ReadableStream API។ ប្រសិនបើប្រើ Simple Browser ប៊ូតុង non-streaming នឹងធម្មតា ប៉ុន្តែប៊ូតុង streaming នឹងមិនដំណើរការ។ បើក http://localhost:8083 នៅក្នុងកម្មវិធីរុករកខាងក្រៅសម្រាប់បទពិសោធន៍ពេញលេញ។ +> **សំណើចំណាំ៖ តម្រូវការ Browser** — លក្ខណៈ Streaming ប្រើ Fetch Streams API (`response.body.getReader()`) ដែលតម្រូវឲ្យប្រើ browser ពេញលេញ (Chrome, Edge, Firefox, Safari)។ វាមិនដំណើរការនៅក្នុង Simple Browser របស់ VS Code ទេ ព្រោះ webview នោះមិនគាំទ្រ ReadableStream API។ ប្រើ Simple Browser ប៊ូតុង non-streaming នឹងដំណើរការប្រក្រតី — មានគ្រាន់តែប៊ូតុង streaming ផ្ទាល់ល្អប៉ុណ្ណោះ។ បើក `http://localhost:8083` នៅកាន់ browser ខាងក្រៅសម្រាប់បទពិសោធន៍ពេញលេញ។ -### លំនាំបួន Low vs High Eagerness +### ឧស្សាហ៍ទាប និងឧស្សាហ៍ខ្ពស់ -សួរប្រសាសន៍ជាការងារងាយៗដូចជា "១០០% នៃ ២០០ គឺប៉ុន្មាន?" ដោយប្រើ Low Eagerness។ អ្នកនឹងទទួលបានចម្លើយភ្លាមៗ និងផ្ទាល់។ ឥឡូវសួរប្រសាសន៍ស្មុគស្មាញដូចជា "រចនាសម្ព័ន្ធ caching សម្រាប់ API ដែលមានចរាចរណ៍ច្រើន" ប្រើ High Eagerness។ ចុច **🔴 Stream Response (Live)** ហើយមើលការតុល្យវិចារលម្អិតតាម token មួយៗ។ ម៉ូដែលដូចគ្នា រចនាសម្ព័ន្ធសំណួរដូចគ្នា ប៉ុន្តែ prompt បញ្ជាកុលវិចារជម្រៅ។ +សួរការសំណួរងាយៗ "តើ ១៥% នៃ ២០០ ជាអ្វី?" ដោយប្រើ Low Eagerness។ អ្នកនឹងទទួលបានចម្លើយភ្លាមៗ និងផ្ទាល់។ ឥឡូវសាកល្បងបញ្ហាស្មុគស្មាញ "រចនាគោលនយោបាយ caching សម្រាប់ API គ្រប់ល្បឿនខ្ពស់" ដោយប្រើ High Eagerness។ ចុច **🔴 Stream Response (Live)** ហើយមើលការពិចារណារបស់ម៉ូដែលចេញមកជាជំហានៗ។ ម៉ូដែលដដែល បែបសំណួរដដែល — តែ prompt បង្ហាញពីកម្រិតការគិត។ -### ការប្រតិបត្តិភារកិច្ច (ការពន្យល់ Tool) +### ការអនុវត្តភារកិច្ច (Tool Preambles) -ការធ្វើការជាច្រើនជំហានទទួលបានអត្ថប្រយោជន៍ពីការធ្វើផែនការ និងបង្រៀនដំណើរការជាជំហានៗ។ ម៉ូដែលនិយាយផែនការនឹងធ្វើ អ្នកនិយាយដំណើរការជំហាននីមួយៗ ហើយសង្ខេបលទ្ធផល។ +ចំណាត់ថ្នាក់ពហុជំហានមានអត្ថប្រយោជន៍ពីការធ្វើផែនការជាមុន និងរាយការណ៍វឌ្ឍនភាព។ ម៉ូដែលបង្ហាញអ្វីដែលវានឹងធ្វើ រាយការណ៍ជំហាននីមួយៗ បន្ទាប់សង្ខេបលទ្ធផល។ -### កូដបញ្ញ្រពិចារណាដោយខ្លួនឯង +### កូដដែលមានការពិចារណាផ្ទាល់ខ្លួន -សាកល្បង "បង្កើតសេវាកម្មផ្ទៀងផ្ទាត់អ៊ីមែល"។ មិនត្រឹមតែបង្កើតកូដហើយបញ្ឈប់ទេ ម៉ូដែលបង្កើត វាយតម្លៃតាមលក្ខណៈគុណភាព សម្គាល់កំរិតខ្សោយ ហើយធ្វើឲ្យប្រសើរឡើង។ អ្នកអាចមើលឃើញវាកែប្រែរហូតកូដសមរម្យសម្រាប់ផលិតកម្ម។ +សាកល្បង "បង្កើតសេវាកម្មផ្ទៀងផ្ទាត់អ៊ីមែល"។ មិនត្រឹមតែបង្កើតកូដ ហើយបញ្ឈប់ប៉ុណ្ណោះទេ ម៉ូដែលបង្កើត វាយតម្លៃតាមគោលការណ៍គុណភាព សម្គាល់ចំណុចខ្សោយ ហើយធ្វើឲ្យកែលម្អ។ អ្នកនឹងឃើញវាធ្វើឡើងបន្តរហូតដល់កូដស្ថិតនៅក្នុងគោលការណ៍ផលិតកម្ម។ -### វិភាគរចនាសម្ព័ន្ធ +### ការវិភាគដែលមានរចនាសម្ព័ន្ធ -ការពិនិត្យកូដតម្រូវការវិធីសាស្រ្តវាយតម្លៃជាប់លាប់។ ម៉ូដែលវាយតម្លៃកូដ ដោយប្រើប្រភេទដែលកំណត់ជាក់លាក់ (ភាពត្រឹមត្រូវ, បច្ចេកទេស, ប្រសិទ្ធភាព, សុវត្ថិភាព) ជាមួយកម្រិតធ្ងន់ធ្ងរ។ +ការត្រួតពិនិត្យកូដត្រូវការសៀវភៅប្រវត្តិការវាយតម្លៃដែលមានលក្ខណៈច្បាស់លាស់។ ម៉ូដែលវិភាគកូដដោយប្រើចំណាត់ថ្នាក់ថេរ (ភាពត្រឹមត្រូវ អនុវត្ត អតិភូតិយភាព សុវត្ថិភាព) ជាមួយកម្រិតធ្ងន់ធ្ងរ។ -### ការសន្ទនាច្រើនជំរើស +### ការសន្ទនាពហុជំហាន -សួរថា "Spring Boot ជាអ្វី?" បន្ទាប់មកភ្លាមៗបន្តដោយ "បង្ហាញគំរូមួយ"។ ម៉ូដែលចាំសំណួរដំបូងរបស់អ្នក ហើយផ្តល់ឧទាហរណ៍ Spring Boot ជាក់លាក់។ បើគ្មានកំណត់ចំណាំសំណួរទីពីរនោះនឹងស្ងាត់ពេក។ +សួរ "តើ Spring Boot ជាអ្វី?" បន្ទាប់មកភ្លាមៗសួរថា "បង្ហាញឧទាហរណ៍មួយ"។ ម៉ូដែលចងចាំសំណួរដំបូងរបស់អ្នក ហើយផ្ដល់ឧទាហរណ៍ Spring Boot ជាក់លាក់។ ប្រសិនមិនមានការចងចាំសំណួរទីពីរនោះជំនួសនឹងអាក្រក់។ -### ការពិចារណាជាដំណាក់កាល +### ការគិតជាជំហានៗ -ជ្រើសបញ្ហាគណិតវិទ្យា ហើយសាកល្បងជាមួយ Step-by-Step Reasoning និង Low Eagerness។ Low Eagerness ផ្តល់តែចម្លើយ-រហ័ស ប៉ុន្តែមិនបង្ហាញដំណើរការ។ Step-by-step បង្ហាញគ្រប់កំណត់គណនា និងសេចក្តីសម្រេច។ +ជ្រើសបញ្ហាគណិតវិទ្យាមួយ ហើយសាកល្បងជាមួយ Step-by-Step Reasoning និង Low Eagerness។ ឧស្សាហ៍ទាបផ្ដល់តែចម្លើយ - រហ័ស ប៉ុន្តែមិនច្បាស់លាស់។ ជំហានដោយជំហានបង្ហាញគ្រប់កំណត់ពិសោធន៍និងសេចក្តីសំរេច។ -### ការបញ្ចេញលទ្ធផលដែលមានកំណត់ +### លទ្ធផលមានកំណត់ -ពេលដែលអ្នកចាំបាច់ការរចនាសម្ព័ន្ធ ឬចំនួនពាក្យជាក់លាក់ រចនាសម្ព័ន្ធនេះអនុវត្តយ៉ាងតឹងរ៉ឹង។ សាកល្បងបង្កើតសង្ខេបជាមួយចំនួនពាក្យ precisely 100 នៅជារាងចំណុច។ +ពេលដែលអ្នកត្រូវការទ្រង់ទ្រាយជាក់លាក់ឬចំនួនពាក្យជាក់លាក់ គំរូនេះបង្ខំឲ្យគោរពយ៉ាងតឹងរ៉ឹង។ សាកល្បងបង្កើតសេចក្តីសង្ខេបមានពាក្យពេញ ១០០ ក្នុងទ្រង់ទ្រាយចំណុច។ ## អ្វីដែលអ្នកកំពុងរៀនពិតប្រាកដ -**កិរិយាពិចារណាផ្លាស់ប្ដូរពីរបៀបគ្រប់យ៉ាង** +**ការខំប្រឹងគិតបម្លែងអ្វីគ្រប់យ៉ាង** + +GPT-5.2 អនុញ្ញាតឲ្យអ្នកត្រួតពិនិត្យការខំប្រឹងគិតតាមរយៈ prompts របស់អ្នក។ ខំ​ប្រឹងទាបមានន័យថាចម្លើយរហ័ស និងរួមបញ្ចូលតាមដានតិចតួច។ ខំ​ប្រឹងខ្ពស់មានន័យថាម៉ូដែលចំណាយពេលគិតជ្រៅ។ អ្នកកំពុងរៀនផ្គូរផ្គងការខំប្រឹងទៅនឹងកម្រិតស្មុគស្មាញនៃភារកិច្ច - កុំចំណាយពេលលើសំណួរងាយៗ ប៉ុន្តែមិនត្រូវរត់រាក់លើសេចក្តីសម្រេចខុសៗផង។ -GPT-5.2 អនុញ្ញាតឲ្យអ្នកគ្រប់គ្រងកិរិយានៃកាកបរិច្ឆេទតាម prompt របស់អ្នក។ កិរិយាថយចុះមានន័យថាចម្លើយរហ័សដោយច្រើនតិចការស្វែងរក។ កិរិយាឡើងខ្ពស់មានន័យម៉ូដែលយកពេលគិតជម្រៅ។ អ្នកកំពុងរៀនឲ្យសន្ទស្សន៍កិរិយាសម្រាប់សម្ព្ទភាពភារកិច្ច - កុំសាយថយពេលលើសំណួរងាយៗ ប៉ុន្តែមិនត្រូវបង្ហោះលើសំណើរពិបាកផងដែរ។ +**រចនាសម្ព័ន្ធនាំផ្លូវអាកប្បកិរិយា** -**រចនាសម្ព័ន្ធណែនាំឲ្យមានកិរិយា** +ចំណាំពីស្លាក XML នៅក្នុង prompt ទេ? ពួកវាមិនមែនសម្រាប់ស្អាតតែប៉ុណ្ណោះទេ ម៉ូដែលអនុវត្តតាមការណែនាំដែលមានរចនាសម្ព័ន្ធបានច្បាស់លាស់ជាងអត្ថបទសេរី។ ពេលដែលអ្នកត្រូវការជំហានច្រើន ឬតុល្យវិធីសាស្រ្តស្មុគស្មាញ រចនាសម្ព័ន្ធជួយម៉ូដែលចងក្រងទីតាំង និងអ្វីដែលត្រូវធ្វើបន្ត។ -សម្គាល់តុ XML នៅក្នុង prompt? វាមិនមែនតែក្រាសស្រវឹងទេ។ ម៉ូដែលអនុវត្តតាមការណែនាំមានរចនាសម្ព័ន្ធយ៉ាងទៀងទាត់ជាងអត្ថបទស្ទាតមួយ។ ពេលអ្នកចាំបាច់ដំណើរការជាច្រើនជំហាន ឬតុល្យវិចារស្មុគស្មាញ រចនាសម្ព័ន្ធជួយម៉ូដែលតាមដានទីតាំងនិងអ្វីដែលនឹងមកបន្ទាប់។ រូបភាពខាងក្រោមបង្ហាញចំណុចលម្អិតនៃ prompt ដែលមានកំណត់ជា ``, ``, ``, ``, និង `` ដែលរៀបចំការណែនាំរបស់អ្នកជាផ្នែកច្បាស់លាស់។ +រូបភាពខាងក្រោមបំបែក prompt រចនាសម្ព័ន្ធល្អបង្ហាញរបៀបដែលស្លាក ``, ``, ``, ``, និង `` រៀបចំការណែនាំឲ្យច្បាស់។ Prompt Structure -*រចនាសម្ព័ន្ធរបស់ prompt ទំាងមានផ្នែកច្បាស់និងរបៀបរៀបចំលក្ខណៈ XML* +*រចនាសម្ព័ន្ធ prompt ដែលមានផ្នែកច្បាស់ និងរៀបចំដោយស្ទីល XML* -**គុណភាពតាមរយៈការវាយតម្លៃដោយខ្លួនឯង** +**គុណភាពតាមវិធីវាយតម្លៃផ្ទាល់ខ្លួន** -លំនាំបញ្ញ្រពិចារណាដោយខ្លួនឯងដំណើរការដោយការបង្ហាញលក្ខណៈគុណភាពច្បាស់លាស់។ មិនត្រឹមតែសង្ឃឹមថាម៉ូដែល "ធ្វើបានត្រឹមត្រូវ" ទេ ប៉ុន្តែអ្នកប្រាប់វាត្រឹមត្រូវមានន័យថា៖ តុល្យ្យវិចារត្រឹមត្រូវ ការដោះស្រាយកំហុស ប្រសិទ្ធភាព និងសុវត្ថិភាព។ ម៉ូដែលអាចវាយតម្លៃលទ្ធផលខ្លួនឯង ហើយធ្វើឲ្យប្រសើរឡើង។ នេះបម្លែងកូដពីការចាប់សំណាងទៅជាដំណើរការត្រឹមត្រូវ។ +គំរូ self-reflecting ធ្វើការ​ដោយបញ្ចាក់ច្បាស់លាស់អំពីគោលការណ៍គុណភាព។ មិនត្រឹមតែសង្ឃឹមថាម៉ូដែល "ធ្វើបានត្រឹមត្រូវ" ទេ អ្នកប្រាប់វាត្រឹមត្រូវជា​យ៉ាងដូចម្តេច៖ តុល្យវិធីត្រឹមត្រូវ ការគ្រប់គ្រងកំហុស ការសម្របសម្រួល ប្រសិទ្ធភាព សុវត្ថិភាព។ ម៉ូដែលអាចវាយតម្លៃលទ្ធផលផ្ទាល់ខ្លួននិងកែលម្អបាន។ នេះបម្លែងការបង្កើតកូដពីជោគជ័យឥតប្រាក់រង្វាន់ទៅជាដំណើរការមួយ។ -**context គឺមានកំណត់** +**បរិបទមានកំណត់** -ការសន្ទនាច្រើនជំរើសដំណើរការតាមរយៈការរួមបញ្ចូលប្រវត្តិសារ ជាមួយនឹងសំណើនីមួយៗ។ ប៉ុន្តែមានកំណត់ - ម៉ូដែលទាំងអស់មានកំណត់ token ទៅតែប៉ុន្មាន។ ពេលកាលបរិច្ឆេទកើនឡើង អ្នកត្រូវការយុទ្ធសាស្រ្តរក្សា context ដែលពាក់ព័ន្ធដោយមិនឲ្យលើសកម្រិតនោះ។ ម៉ូឌុលនេះបង្ហាញពីរបៀបដំណើរការចងចាំ; បន្ទាប់មកអ្នកនឹងរៀនពេលណាត្រូវសង្ខេប ពេលណាចាំបាច់ភ្លេច និងពេលណាដកយកវិញ។ +សន្ទនា​ពហុជំហានដំណើរការដោយបញ្ចូលប្រវត្តិសារ​នៅលើសំណើរ​នីមួយៗ។ ប៉ុន្តែមានកំណត់ - ម៉ូដែលមួយៗមានចំនួន token អតិបរមា។ តាមពេលសន្ទនាកើនឡើង អ្នកត្រូវការយុទ្ធសាស្ត្រដើម្បីរក្សាបរិបទដែលពាក់ព័ន្ធដោយមិនឲ្យលើសកំណត់នោះ។ ម៉ូឌុលនេះបង្ហាញរបៀបធ្វើការចំណាំ; ពេលក្រោយអ្នកនឹងរៀនពេលណាដើម្បីសង្ខេប ពេលណាដើម្បីភ្លេច និងពេលណាដើម្បីគ្រប់គ្រង។ ## ជំហានបន្ទាប់ @@ -598,11 +600,11 @@ GPT-5.2 អនុញ្ញាតឲ្យអ្នកគ្រប់គ្រង --- -**ការរុករក៖** [← មុន៖ ម៉ូឌុល 01 - ទិដ្ឋភាពទូទៅ](../01-introduction/README.md) | [ត្រលប់ទៅមុខភាគ](../README.md) | [បន្ទាប់៖ ម៉ូឌុល 03 - RAG →](../03-rag/README.md) +**ចរចារប្រវត្តិ៖** [← មុន៖ ម៉ូឌុល ០១ - ការណែនាំ](../01-introduction/README.md) | [ត្រឡប់ទៅផ្ទៃដើម](../README.md) | [បន្ទាប់៖ ម៉ូឌុល ០៣ - RAG →](../03-rag/README.md) --- -**ការបដិសេធ**៖ -ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាបកប្រែ AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ខណៈពេលដែលយើងខិតខំឡើងដល់ភាពត្រឹមត្រូវ សូមយល់ដឹងថាការបកប្រែដោយស្វ័យប្រវត្តិនេះអាចមានកំហុស ឬការខុសត្រូវខ្លះៗ។ ឯកសារដែលមានភាសាម្ដងកើតគួរត្រូវបានរក្សាជាជំនួយដើមដែលមានសុពលភាព។ សម្រាប់ព័ត៌មានដ៏សំខាន់ សូមណែនាំឲ្យប្រើការបកប្រែដោយមនុស្សដែលមានជំនាញ។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកប្រែខុសដែលកើតមានពីការប្រើប្រាស់ការបកប្រែនេះឡើយ។ +**ការបដិសេធ**: +ឯកសារនេះត្រូវបានបម្លែងភាសា ដោយប្រើសេវាបម្លែងភាសា AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទោះយើងខ្ញុំមានក្តីប្រាថ្នាឱ្យបានច្បាស់លាស់ តែសូមយល់ដឹងថាការបម្លែងដោយស្វ័យប្រវត្តិក៏អាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមជាភាសាទីតាំងគួរត្រូវបានគេប្រើជាប្រភពច្បាស់លាស់។ សម្រាប់ព័ត៌មានសំខាន់ៗ សូមណែនាំឱ្យប្រើប្រាស់ការប្រែដោយមនុស្សជំនាញ។ យើងខ្ញុំមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកស្រាយខុសបន្ទាប់ពីការប្រើប្រាស់ការបម្លែងនេះនោះទេ។ \ No newline at end of file diff --git a/translations/km/03-rag/README.md b/translations/km/03-rag/README.md index ca2a95d0a..67ac408ee 100644 --- a/translations/km/03-rag/README.md +++ b/translations/km/03-rag/README.md @@ -1,144 +1,143 @@ -# ម៉ូឌុល ០៣៖ RAG (ការបង្កើតដោយបន្ថែមការស្វែងរក) - -## តារាងខ្លឹមសារ - -- [វីដេអូផ្លាស់ប្តូរ](#វីដេអូផ្លាស់ប្តូរ) -- [អ្វីដែលអ្នកនឹងរៀន](#អ្វីដែលអ្នកនឹងរៀន) -- [លក្ខខណ្ឌមុន](#លក្ខខណ្ឌមុន) -- [ការយល់ដឹងអំពី RAG](#ការយល់ដឹងអំពី-rag) - - [ជម្រើស RAG តើមេរៀននេះប្រើអ្វី?](#ជម្រើស-rag-តើមេរៀននេះប្រើអ្វី) -- [របៀបដំណើរការ](#របៀបដំណើរការ) - - [ការប្រព្រឹត្តទៅលើឯកសារ](#ការប្រព្រឹត្តទៅលើឯកសារ) - - [ការបង្កើត embeddings](#ការបង្កើត-embeddings) - - [ការស្វែងរកស្រដៀង](#ការស្វែងរកស្រដៀង) - - [ការបង្កើតចម្លើយ](#ការផលិតចម្លើយ) -- [រត់កម្មវិធី](#រត់កម្មវិធី) -- [ការប្រើប្រាស់កម្មវិធី](#ការប្រើប្រាស់កម្មវិធី) - - [អាប់ឡូដឯកសារ](#អាប់ឡូតឯកសារ) - - [សួរប្រធានបទ](#សួរសំណួរ) - - [ពិនិត្យប្រភពយោង](#ពិនិត្យយោងប្រភព) - - [សាកល្បងជាមួយសំនួរ](#សាកល្បងសំណួរ) -- [គំនិតសំខាន់ៗ](#គំនិតសំខាន់ៗ) - - [យុទ្ធសាស្ត្រកែក](#យុទ្ធសាស្ត្របំបែកចំណែក-chunking) - - [ពិន្ទុស្រដៀង](#ពិន្ទុភាពស្រដៀងគ្នា-similarity-scores) - - [ការផ្ទុកក្នុងចង្វាក់](#ឃ្លាំងទិន្នន័យក្នុងម៉េម៉ូរី) - - [ការគ្រប់គ្រងបង្អួចបរិបទ](#ការគ្រប់គ្រងបរិវេណបរិបទ) -- [ពេលដែល RAG មានសារៈសំខាន់](#ពេលណាដែល-rag-មានសារៈសំខាន់) -- [ជំហានបន្ទាប់](#ជំហានបន្ទាប់) - -## វីដេអូផ្លាស់ប្តូរ - -ទស្សនាពិធីបន្តផ្ទាល់នេះដែលពណ៌នាអំពីរបៀបចាប់ផ្តើមជាមួយម៉ូឌុលនេះ៖ +# Module 03: RAG (Retrieval-Augmented Generation) + +## Table of Contents + +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding RAG](#understanding-rag) + - [Which RAG Approach Does This Tutorial Use?](#which-rag-approach-does-this-tutorial-use) +- [How It Works](#how-it-works) + - [Document Processing](#document-processing) + - [Creating Embeddings](#creating-embeddings) + - [Semantic Search](#semantic-search) + - [Answer Generation](#ការបង្កើតចម្លើយ) +- [Run the Application](#ប្រតិបត្តិកម្មកម្មវិធី) +- [Using the Application](#ការប្រើប្រាស់កម្មវិធី) + - [Upload a Document](#បញ្ចូលឯកសារ) + - [Ask Questions](#សួរសំណួរ) + - [Check Source References](#ពិនិត្យប្រភពយោង) + - [Experiment with Questions](#សាកល្បងសំណួរ) +- [Key Concepts](#គំនិតសំខាន់ៗ) + - [Chunking Strategy](#ពិន្ទុភាពស្រដៀងគ្នា) + - [Similarity Scores](#ការផ្ទុកនៅក្នុងម៉ាស៊ីន) + - [In-Memory Storage](#ការគ្រប់គ្រងបរិវេណបរិបទ) + - [Context Window Management](#ពេលដែល-rag-មានសារៈសំខាន់) +- [When RAG Matters](#ជំហានបន្ទាប់) +- [Next Steps](#next-steps) + +## Video Walkthrough + +សូមមើលវីដេអូចាក់ផ្សាយផ្ទាល់នេះ ដែលពន្យល់ពីរបៀបចាប់ផ្តើមជាមួយម៉ូឌុលនេះ៖ RAG with LangChain4j - Live Session -## អ្វីដែលអ្នកនឹងរៀន +## What You'll Learn -ក្នុងម៉ូឌុលមុនៗ អ្នកបានរៀនរបៀបធ្វើការសន្ទនាជាមួយ AI និងរចនាសម្ព័ន្ធសំណួររបស់អ្នកយ៉ាងមានប្រសិទ្ធិភាព។ ប៉ុន្តែមានការជាប់កំណត់មួយសំខាន់៖ គំរូភាសាអាចដឹងតែអ្វីដែលពួកវាបានរៀនពេលហ្វឹកហាត់ប៉ុណ្ណោះ។ វាមិនអាចឆ្លើយសំណួរអំពីគោលការណ៍ក្រុមហ៊ុនរបស់អ្នក ឬឯកសារគម្រោងរបស់អ្នក ឬព័ត៌មានណាមួយដែលពួកវាមិនបានហ្វឹកហាត់ទេ។ +ក្នុងម៉ូឌុលមុនៗ អ្នកបានរៀនពីរបៀបធ្វើការពិភាក្សាជាមួយ AI និងរចនាសំណួរដោយមានប្រសិទ្ធភាព។ ប៉ុន្តែមានកំណត់មួយគឺៈ ម៉ូដែលភាសានេះចេះតែលើកដំបូងតាមការបណ្តុះបណ្តាល ប៉ុន្តែមិនអាចឆ្លើយសំណួរអំពីនយោបាយក្រុមហ៊ុន រឺឯកសារពីគម្រោងរបស់អ្នក ឬព័ត៌មានណាដែលវាមិនបានបណ្តុះបណ្តាលទេ។ -RAG (Retrieval-Augmented Generation) ជួយដោះសោនេះ។ ជំនួសការព្យាយាមបង្រៀនគំរូដោយផ្ទាល់ (ដែលថ្លៃថ្នូរនិងមិនពេញចិត្ត) អ្នកអាចផ្ដល់សមត្ថភាពស្វែងរកឯកសាររបស់អ្នក។ នៅពេលដែលមាននរណាម្នាក់សួរបញ្ហា ប្រព័ន្ធនាំឱ្យឯកសារដែលពាក់ព័ន្ធមកជាប់ក្នុងសំណួរ។ គំរូនឹងឆ្លើយតបដោយផ្អែកលើបរិបទដែលបានយកមកនោះ។ +RAG (Retrieval-Augmented Generation) គឺដោះស្រាយបញ្ហានេះ។ ជំនួសការសំខាន់បង្រៀនម៉ូដែលពីព័ត៌មានអ្នក (ដែលមានដំណើរការពិបាក និងថ្លៃ) អ្នកផ្ដល់វត្ថុសមត្ថភាពស្វែងរកក្នុងឯកសាររបស់អ្នក។ ពេលមាននរណាម្នាក់សួរសំណួរ ប្រព័ន្ធនឹងស្វែងរកព័ត៌មានពាក់ព័ន្ធ ហើយបញ្ចូលវាទៅក្នុងសំណួរ។ ម៉ូដែលនោះបន្ទាប់មកឆ្លើយផ្អែកលើបរិបទដែលបានយកមក។ -គិតថា RAG ជាការផ្ដល់បណ្ណាល័យយោងឱ្យគំរូ។ នៅពេលអ្នកសួរបញ្ហា ប្រព័ន្ធ៖ +គិតថា RAG គឺជាការផ្ដល់បណ្ណាល័យយោងឲ្យម៉ូដែល។ ពេលអ្នកសួរសំណួរ ប្រព័ន្ធធ្វើដូចជា៖ -1. **សំណួរអ្នកប្រើ** - អ្នកសួរ -2. **Embedding** - បម្លែងសំណួររបស់អ្នកទៅជាទ្រង់ទ្រាយវ៉ិចទ័រ -3. **ការស្វែងរកវ៉ិចទ័រ** - ស្វែងរកម្ជុលឯកសារដែលស្រដៀងគ្នា -4. **ការប្រមូលបរិបទ** - បន្ថែមម្ជុលពាក់ព័ន្ធទៅក្នុងសំណួរ -5. **ចម្លើយ** - គំរូជ GENERATE ចម្លើយផ្អែកលើបរិបទ +1. **User Query** - អ្នកសួរសំណួរ +2. **Embedding** - បម្លែងសំណួររបស់អ្នកទៅជាវ៉ិចទ័រ +3. **Vector Search** - ស្វែងរកដុំឯកសារដែលមានស្រដៀងគ្នា +4. **Context Assembly** - បន្ថែមដុំដែលពាក់ព័ន្ធទៅក្នុងសំណួរ +5. **Response** - LLM បង្កើតចម្លើយផ្អែកលើបរិបទ -នេះធ្វើឱ្យចម្លើយរបស់គំរូស្ថិតនៅលើទិន្នន័យពិតជារបស់អ្នក មិនគួរឱ្យពឹងផ្អែកលើចំណេះដឹងហ្វឹកហាត់របស់វា ឬបង្កើតចម្លើយឡើងមក។ +វាផ្តល់ឲ្យចម្លើយរបស់ម៉ូដែលមានមូលដ្ឋានលើទិន្នន័យពិតរបស់អ្នក ជំនួសការជឿលើចំណេះដឹងបណ្តុះបណ្តាលចាស់ៗ រឺបង្កើតចម្លើយខុស។ -## លក្ខខណ្ឌមុន +## Prerequisites -- បានបញ្ចប់ [Module 00 - Quick Start](../00-quick-start/README.md) (សម្រាប់ឧទាហរណ៍ Easy RAG ដែលបានយោងនៅក្នុងម៉ូឌុលនេះ) -- បានបញ្ចប់ [Module 01 - Introduction](../01-introduction/README.md) (ធនធាន Azure OpenAI ត្រូវបានដំណើរការ រួមទាំងម៉ូឌុល embedding `text-embedding-3-small`) -- មានឯកសារ `.env` នៅថត root រួចជាមួយសេវាប្រតិបត្តិ Azure (បានបង្កើតដោយ `azd up` ក្នុង Module 01) +- បានបញ្ចប់ [Module 01 - Introduction](../01-introduction/README.md) (ធនធាន Azure OpenAI ត្រូវបានដាក់ប្រើ រួមទាំងម៉ូដែល `text-embedding-3-small`) +- ឯកសារ `.env` នៅក្នុងថតដើម មានសក្ខីប័ត្រ Azure (បានបង្កើតដោយ `azd up` ក្នុង Module 01) -> **សម្គាល់៖** បើអ្នកមិនទាន់បានបញ្ចប់ Module 01 ទេ សូមអនុវត្តតាមការណែនាំដំណើរការនៅទីនោះជាមុន។ ពាក្យបញ្ជា `azd up` នឹងដំណើរការម៉ូឌុល GPT chat និងម៉ូឌុល embedding ដែលប្រើសម្រាប់ម៉ូឌុលនេះ។ +> **Note:** ប្រសិនបើអ្នកមិនបានបញ្ចប់ Module 01 សិនទេ សូមអនុវត្តតាមការណែនាំនៃការដាក់ប្រើនៅទីនោះ។ ពាក្យបញ្ជា `azd up` នោះដាក់ប្រើម៉ូដែល GPT chat និងម៉ូដែល embedding ដែលយើងប្រើក្នុងម៉ូឌុលនេះ។ -## ការយល់ដឹងអំពី RAG +## Understanding RAG -រូបភាពខាងក្រោមបង្ហាញពីគំនិតសំខាន់៖ ជំនួសការពឹងផ្អែកលើទិន្នន័យហ្វឹកហាត់របស់គំរូតែប៉ុណ្ណោះ RAG ផ្ដល់បណ្ណាល័យយោងឯកសាររបស់អ្នកសម្រាប់ពិនិត្យមុនពេលបង្កើតចម្លើយ។ +គំនូរបង្ហាញខាងក្រោមបង្ហាញពីគំនិតមូលដ្ឋាន៖ ជំនួសការជឿលើទិន្នន័យបណ្តុះបណ្តាលម៉ូដែលតែប៉ុណ្ណោះ RAG ផ្ដល់ឲ្យវាបណ្ណាល័យយោងឯកសាររបស់អ្នកដើម្បីពិចារណា មុននឹងបង្កើតចម្លើយនីមួយៗ។ What is RAG -*រូបភាពនេះបង្ហាញពីភាពខុសគ្នារវាង LLM ទូទៅ (ដែលប៉ះសមាហរណ៍ពីទិន្នន័យហ្វឹកហាត់) និង LLM ដែលមានការបន្ថែម RAG (ដែលពិនិត្យឯកសាររបស់អ្នកជាមុន)* +*គំនូរនេះបង្ហាញពីភាពខុសគ្នារវាង LLM ទូទៅ (ដែលធ្វើដំណើរការពីទិន្នន័យបណ្តុះបណ្តាល) និង LLM ដែលពង្រីកដោយ RAG (ដែលពិចារណាឯកសាររបស់អ្នកជាមុនសិន)។* -នេះជារបៀបផ្នែកផ្សេងៗភ្ជាប់គ្នា។ សំណួរអ្នកប្រើឆ្លងកាត់ជាដំណាក់កាលបួន — embedding, ការស្វែងរកវ៉ិចទ័រ, ការប្រមូលបរិបទ និងការបង្កើតចម្លើយ — ដែលមានការរីកចម្រើនពីមួយទៅមួយ៖ +នេះគឺជារបៀបភ្ជាប់របស់ផ្នែកទាំងអស់ចាប់ពីដំណាក់កាលមួយដល់មួយផ្សេងទៀត។ សំណួររបស់អ្នកប្រើត្រូវបានដឹកនាំឆ្លងកាត់បួនជំហាន — បង្កើត embedding, ស្វែងរកវ៉ិចទ័រ, ប្រមុំបរិបទ, និងបង្កើតចម្លើយ — ធ្វើការចងខាងលើនៃជំហានមុនៗ៖ RAG Architecture -*រូបភាពនេះបង្ហាញពីផ្លូវភ្ជាប់ RAG ចាប់ពីដំណាក់កាល embedding, ស្វែងរកវ៉ិចទ័រ, ប្រមូលបរិបទ និងបង្កើតចម្លើយ។* +*គំនូរនេះបង្ហាញពីបណ្តាញ RAG ពេញលេញ — សំណួរអ្នកប្រើឆ្លងកាត់ embedding, ស្វែងរកវ៉ិចទ័រ, ប្រមុំបរិបទ និងបង្កើតចម្លើយ។* -នៅសល់ម៉ូឌុលនេះនឹងពិពណ៌នាលម្អិតពីដំណាក់កាលទាំងអស់ ជាមួយកូដដែលអ្នកអាចរត់និងកែប្រែបាន។ +នៅម៉ូឌុលនេះ យើងនឹងបង្ហាញរៀងរាល់ជំហាននេះជាពិសេស ដោយមានកូដដែលអ្នកអាចរត់ និងកែប្រែ។ -### ជម្រើស RAG តើមេរៀននេះប្រើអ្វី? +### Which RAG Approach Does This Tutorial Use? -LangChain4j ផ្តល់វិធីបីក្នុងការអនុវត្ត RAG ដែលមានកំរិត abstraction ខុសគ្នា។ រូបភាពខាងក្រោមប្រៀបធៀបវាចំនួនពីរសំរាប់មេរៀននេះ៖ +LangChain4j ផ្ដល់ជម្រើសបីនៃការអនុវត្ត RAG ដែលមានកម្រិត abstraction ផ្សេងៗគ្នា។ គំនូរខាងក្រោមប្រៀបធៀបពួកវាចំហៀងគ្នា៖ Three RAG Approaches in LangChain4j -*រូបភាពប្រៀបធៀបវិធីបីរបស់ LangChain4j ក្នុង RAG — Easy, Native, និង Advanced — បង្ហាញគ្រឿងផ្សំនិងពេលប្រើបច្ចេកទេសនីមួយៗ។* +*គំនូរនេះប្រៀបធៀបនូវជម្រើសបីរបស់ RAG នៅក្នុង LangChain4j ៖ Easy, Native, និង Advanced — បង្ហាញផ្នែកសំខាន់ៗ និងពេលវេលាដែលត្រូវប្រើនីមួយៗ។* -| វិធី | វាធ្វើអ្វី | ចំណាយជំនួស | +| Approach | What It Does | Trade-off | |---|---|---| -| **Easy RAG** | ភ្ជាប់បន្ទាប់បន្សំដោយស្វ័យប្រវត្តិតាម `AiServices` និង `ContentRetriever`។ អ្នកបញ្ចូល interface មួយ រួចភ្ជាប់ retriever ហើយ LangChain4j ត្រូវបានគ្រប់គ្រង embedding, ស្វែងរក, និងប្រមូល prompt ជាក្រោយ។ | កូដតិច ប៉ុន្តែនៅមិនមើលឃើញមុខងារនៅកម្រិតនីមួយៗ។ | -| **Native RAG** | អ្នកហៅម៉ូឌុល embedding, ស្វែងរកហាងទិន្នន័យ, បង្កើត prompt, និងសរសេរកូដចម្លើយផ្ទាល់ខ្លួន — តែរៀងលំដាប់។ | កូដច្រើន តែអាចមើលឃើញនិងកែប្រែក្នុងគ្រប់ដំណាក់កាលបាន។ | -| **Advanced RAG** | ប្រើស្រាសម៉ូឌុល `RetrievalAugmentor` ជាមួយនឹង transformers សំណួរ, routers, re-rankers, និង injectors សម្រាប់បណ្តាញផលិតកម្ម។ | មានភាពបត់បែនខ្ពស់បំផុត ប៉ុន្តែកាន់តែស្មុគស្មាញ។ | +| **Easy RAG** | តភ្ជាប់អ្វីៗគ្រប់យ៉ាងដោយស្វ័យប្រវត្តិ តាមរយៈ `AiServices` និង `ContentRetriever`។ អ្នកកំណត់ interface ប្រើ retriever ហើយ LangChain4j ធ្វើការបង្កើត embedding, ស្វែងរក, និងសំណុំសំណួរក្រោយឆាក។ | កូដតិច ប៉ុន្តែអ្នកមិនមើលឃើញអ្វីក្តៅក្តោងចេញពីក្នុងជំហាននីមួយៗទេ។ | +| **Native RAG** | អ្នកហៅម៉ូដែល embedding, ស្វែងរកក្នុងម៉ាស៊ីនផ្ទុក, បង្កើតសំណួរ និងបង្កើតចម្លើយដោយផ្ទាល់ មានជំហានច្បាស់លាស់មួយៗ។ | កូដច្រើនបន្តិច ប៉ុន្តែពីរបៀបស្នូលមានការមើលឃើញ និងអាចកែប្រែបាន។ | +| **Advanced RAG** | ប្រើ framework `RetrievalAugmentor` ដោយអាចបន្ថែម query transformers, routers, re-rankers និង content injectors សម្រាប់ផលិតផលកម្រិតខ្ពស់។ | មានភាពបត់បែនខ្ពស់បំផុត ប៉ុន្តែមានភាពស្មុគស្មាញខ្ពស់ជាងមុន។ | -**មេរៀននេះប្រើវិធី Native។** រៀងរាល់ដំណាក់កាលក្នុង RAG — embedding សំណួរ, ស្វែងរកក្នុងហាងវ៉ិចទ័រ, ប្រមូលបរិបទ, និងបង្កើតចម្លើយ — ត្រូវបានសរសេរជាផ្ទាល់ក្នុង [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java)។ នេះគ្រាន់តែជាផ្នែកការសិក្សា ដែលសំខាន់ជាងគេគឺអ្នកអាចមើលឃើញនិងយល់ដឹងពីរៀងរាល់ដំណាក់កាល ជំនួសការត្រូវបន្ថយកូដ។ បន្ទាប់ពីអ្នកស្គាល់វា អ្នកអាចទៅកាន់ Easy RAG សម្រាប់ម៉ូឌែលរហ័ស ឬ Advanced RAG សម្រាប់ប្រព័ន្ធផលិតកម្ម។ +**មេរៀននេះប្រើវិធី Native។** ជំហាននីមួយៗក្នុងបណ្តាញ RAG — embedding សំណួរ, ស្វែងរកវ៉ិចទ័រ, ប្រមូលបរិបទ, និងបង្កើតចម្លើយ — ត្រូវបានសរសេរឱ្យច្បាស់ក្នុង [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java)។ វាសំដៅក្នុងការសិក្សា ដែលសំខាន់ជាងគឺអ្នកបានមើលឃើញនិងយល់ព្រមគ្នាពីជំហាននីមួយៗ ជាជាងកូដតិចបំផុត។ បន្ទាប់ពីអ្នកចេះរួច អ្នកអាចធ្វើដំណើរទៅ Easy RAG សម្រាប់ពុម្ពគំរូរហ័សឬ Advanced RAG សម្រាប់ប្រព័ន្ធផលិតកម្ម។ -> **💡 បានឃើញ Easy RAG ដំណើរការហើយទេ?** ម៉ូឌុល [Quick Start](../00-quick-start/README.md) មានឧទាហរណ៍ Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) ប្រើវិធី Easy RAG — LangChain4j គ្រប់គ្រង embedding, ស្វែងរក និងប្រមូល prompt ដោយស្វ័យប្រវត្តិ។ ម៉ូឌុលនេះធ្វើកំហាត់បន្ទាប់ ដោយបំបែកផ្លូវភ្ជាប់នេះដល់អ្នកដើម្បីអ្នកអាចមើលសភាពនិងគ្រប់គ្រងរៀងរាល់ដំណាក់កាលដោយផ្ទាល់។ +> **💡 ចង់ដឹងអំពី Easy RAG?** LangChain4j ក៏ផ្ដល់ជម្រើស *Easy RAG* ផងដែរ ដែល `AiServices` និង `ContentRetriever` ធ្វើអ្វីគ្រប់យ៉ាងដោយស្វ័យប្រវត្តិក្នុងការបង្កើត embedding, ស្វែងរក, និងបង្រួមសំណួរ។ ម៉ូឌុលនេះប្រើវិធីពន្លឿនបង្ហាញសាច់ដុំ pipeline ដូច្នេះអ្នកអាចមើលនិងគ្រប់គ្រងរាល់ជំហានដោយផ្ទាល់។ -រូបភាពខាងក្រោមបង្ហាញផ្លូវភ្ជាប់ Easy RAG ពីឧទាហរណ៍ Quick Start ។ សូមចំណាំរបៀបដែល `AiServices` និង `EmbeddingStoreContentRetriever` លាក់កម្រិតស្មុគស្មាញទាំងអស់ — អ្នកផ្ទុកឯកសារ ភ្ជាប់ retriever ហើយទទួលចម្លើយ។ វិធី Native ក្នុងម៉ូឌុលនេះបំបែកដំណាក់កាលទាំងនោះ៖ +គំនូរខាងក្រោមបង្ហាញ pipeline Easy RAG។ សូមចាប់អារម្មណ៍ពីរបៀប `AiServices` និង `EmbeddingStoreContentRetriever` បានលាក់បន្ថយភាពស្មុគស្មាញ — អ្នកផ្ទុកឯកសារ បត់ retriever ហើយទទួលបានចម្លើយ។ វិធី Native គេបំបែកជំហានទាំងនេះឲ្យមើលច្បាស់ ៖ Easy RAG Pipeline - LangChain4j -*រូបភាពនេះបង្ហាញផ្លូវភ្ជាប់ Easy RAG ពី `SimpleReaderDemo.java`។ ប្រៀបធៀបជាមួយវិធី Native ប្រើម៉ូឌុលនេះ៖ Easy RAG លាក់ embedding, ស្វែងរក និងប្រមូល prompt នៅក្រោយ `AiServices` និង `ContentRetriever` — អ្នកផ្ទុកឯកសារ ភ្ជាប់ retriever ហើយទទួលចម្លើយ។ វិធី Native ខាងម៉ូឌុលនេះបំបែកផ្លូវភ្ជាប់ដើម្បីអ្នកអាចហៅជាលម្អិត រៀងរាល់ដំណាក់កាល (embed, ស្វែងរក, ប្រមូលបរិបទ, បង្កើត) ដោយផ្ទាល់, ផ្តល់នូវទិដ្ឋភាពនិងការគ្រប់គ្រងពេញលេញ។* +*គំនូរនេះបង្ហាញ pipeline Easy RAG។ ប្រៀបធៀបជាមួយវិធី Native ក្នុងម៉ូឌុលនេះ៖ Easy RAG លាក់ការបង្កើត embedding, ស្វែងរក និងចាក់បញ្ចូលសំណួរក្រោយឆាកក្រោយ `AiServices` និង `ContentRetriever` — អ្នកផ្ទុកឯកសារ បត់ retriever ហើយទទួលបានចម្លើយ។ វិធី Native ធ្វើបើក pipeline ដូច្នេះអ្នកហៅជំហាន embedding, ស្វែងរក, ប្រមូលបរិបទ និងបង្កើតដោយផ្ទាល់។* -## របៀបដំណើរការ +## How It Works -ផ្លូវភ្ជាប់ RAG ក្នុងម៉ូឌុលនេះបំបែកជាចំនួនបួនដំណាក់កាលដែលដំណើរការជាលំដាប់រៀងរាល់ពេលអ្នកប្រើសួរបញ្ហា។ ជាមុនសិនឯកសារដែលបានអាប់ឡូដនឹងត្រូវបាន **បកអាន និងកែក** ជាពកដុំតូចៗដែលអាចគ្រប់គ្រងបាន។ ដុំឯកសារនោះបន្ទាប់មកត្រូវបានបម្លែងទៅជារាងមួយនៅក្នុងវិស័យវ៉ិចទ័រសម្រាប់ឱ្យប្រៀបធៀបគ្នាយ៉ាងគណនាសាស្ត្រ។ នៅពេលមានសំណួរ ប្រព័ន្ធនឹងអនុវត្តការ **ស្វែងរកស្រដៀង** ដើម្បីរកដុំឯកសារដែលពាក់ព័ន្ធបំផុត ហើយបញ្ចូនជាបរិបទទៅ LLM ដើម្បីធ្វើ **ការបង្កើតចម្លើយ**។ ផ្នែកខាងក្រោមនឹងពិពណ៌នារបៀបដំណើរការរៀងរាល់ដំណាក់កាលជាមួយកូដនិងរូបភាព។ ចាប់ផ្តើមពីជំហានទីមួយ។ +Pipeline RAG ក្នុងម៉ូឌុលនេះបំបែកជាបួនជំហាន ដែលរត់រៀងរាល់ពេលអ្នកប្រើសួរសំណួរ។ ជំហានដំបូង គឺក្នុងការចម្លងឯកសារគឺ **បំបែក និងបំបែកជាចំណែកតូចៗ** ដែលគ្រប់គ្រងបាន។ ដុំទាំងនេះបន្ទាប់មកត្រូវបម្លែងទៅជាវ៉ិចទ័រ **embedding** ហើយផ្ទុកតំបន់ដែលអាចប្រៀបធៀបទៅគ្នាបាន។ ពេលមានសំណួរ ប្រព័ន្ធធ្វើ **ស្វែងរកមន្ដសញ្ញា** ដើម្បីស្វែងរកដុំដែលពាក់ព័ន្ធច្រើនបំផុត ហើយនៅចុងបំផុតផ្ញើវាទៅជាព័ត៌មានបន្ថែមសម្រាប់ម៉ូដែល LLM ដើម្បី **បង្កើតចម្លើយ**។ ចំណុចខាងក្រោមពន្យល់លម្អិតជាមួយកូដនិងគំនូរ។ តោះមើលជំហានដំបូង។ -### ការប្រព្រឹត្តទៅលើឯកសារ +### Document Processing [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -ពេលអ្នកអាប់ឡូដឯកសារ ប្រព័ន្ធនឹងបកអានវា (PDF ឬអត្ថបទធម្មតា) ភ្ជាប់រូបមន្តដូចជា ឈ្មោះឯកសារ ហើយបំបែកវាទៅជាពកដុំតូចៗ — ដុំដែលមានទំហំសមរម្យសម្រាប់បញ្ចូលក្នុងបរិបទគំរូដោយងាយស្រួល។ ពកដុំទាំងនោះត្រូវបានធ្វើឲ្យទ្រង់ទ្រាយឆ្លាស់កាត់ខ្លះៗ ដើម្បីមិនបាត់បង់បរិបទនៅចំណុចចែក។ +ពេលអ្នកផ្ទុកឯកសារ ប្រព័ន្ធនឹងត្រួតពិនិត្យវា (PDF ឬអត្ថបទទម្រង់សាមញ្ញ) ប្រកាន់ metadata ដូចជា ឈ្មោះឯកសារ ហើយបំបែកវាជាចំណែកតូចៗ — ដុំតូចៗដែលសមរម្យជាមួយបរិបទម៉ូដែលនឹងគ្រប់គ្រង។ ដុំទាំងនេះមានការរួមគ្នាអតិបរមា ដើម្បីមិនបាត់បង់បរិបទនៅចំណុចប្រទាក់។ ```java -// វាយតម្លៃឯកសារដែលបានផ្ទុកឡើងហើយប្តូរវាទៅជាឯកសារ LangChain4j Document +// ពិនិត្យឯកសារដ៏អាប់ឡូដ ហើយបិទវាទៅក្នុងឯកសារ LangChain4j Document Document document = Document.from(content, metadata); -// បំបែកជា​​ចំណុច 300-តួអក្សរជាមួយការឆ្លងកាត់ 30-តួអក្សរ +// បំបែកជាផ្នែក 300 Tokenដែលមានការប៉ះពាល់ 30 Token DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -រូបភាពខាងក្រោមបង្ហាញរបៀបដែលវាដំណើរការដោយមើល៖ សូមចំណាំថាពកដុំនីមួយៗមានការចែករំលែកគ្នាក្នុងចំនួន ៣០ tokens ដើម្បីធានាមិនខកខានបរិបទសំខាន់នៅជិតប្រទាក់ដុំ៖ +គំនូរខាងក្រោមបង្ហាញពីរបៀបដំណើរការនេះដោយអាជីព។ សូមចាប់អារម្មណ៍ថាសំណុំ tokens មួយចំនួនត្រូវបានចែករំលែកជាមួយដុំជិតខាង — ការជ្រៀតចូល 30-token បានធានាថា បរិបទសំខាន់មិនបាត់បង់នៅចំនុចប្រទាក់ទេ៖ Document Chunking -*រូបភាពនេះបង្ហាញឯកសារត្រូវបានបំបែកជាពកដុំ ៣០០ token មាន ៣០ token ឆ្លាស់កាត់ទ្រង់ទ្រាយ រក្សារបរិបទនៅប្រទាក់ពកដុំ។* +*គំនូរនេះបង្ហាញឯកសារត្រូវបានចែកជាចំណែក 300-token ជាមួយការជ្រៀតចូល 30-token ដើម្បីរក្សាបរិបទនៅចំណុចប្រទាក់។* > **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ហើយសួរ៖ -> - "LangChain4j បំបែកឯកសារជាពកដុំ និងហេតុអ្វីបានជាចំណុចឆ្លាស់កាត់បរិបទមានសារះសំខាន់?" -> - "តើទំហំពកដុំសាកសមបំផុតសម្រាប់ប្រភេទឯកសារផ្សេងៗជាអ្វី ហើយហេតុអ្វី?" -> - "តើធ្វើម៉េចដើម្បីដោះស្រាយឯកសារមានភាសាច្រើន ឬមានទ្រង់ទ្រាយពិសេស?" +> - "LangChain4j បំបែកឯកសារជាចំណែកតូចៗ និងហេតុអ្វីបានជាការជ្រៀតចូលសំខាន់?" +> - "ទំហំ chunk ល្អបំផុតសម្រាប់ប្រភេទឯកសារផ្សេងគ្នា ដូចម្តេច ហើយហេតុអ្វី?" +> - "តើធុញធេងចំពោះឯកសារជាភាសាច្រើន រឺមានទម្រង់ពិសេសយ៉ាងដូចម្តេច?" -### ការបង្កើត embeddings +### Creating Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -រាល់ពកដុំត្រូវបានបម្លែងទៅជា​តំណាងឲ្យជាលេខឈ្មោះ embedding — ជាការបម្លែងអត្ថន័យទៅលេខ។ ម៉ូឌុល embedding មិនមែនជាមនុស្សប្រាជ្ញា ដូចម៉ូឌុល chat ទេ; វាមិនអាចធ្វើតាមការណែនាំ ឬវាយនភាព ឬឆ្លើយសំណួរបានទេ។ វាអាចផ្ញើអត្ថបទទៅក្នុងវិស័យគណិតវិទ្យា ដែលមានអត្ថន័យស្រដៀងគ្នាវាស្ថិតជិតគ្នា — "ឡាន" ជិត "រថយន្ត," "គោលការណ៍សងប្រាក់" ជិត "បង្វិលប្រាក់ខ្ញុំ"។ គិតថាម៉ូឌុល chat គឺជាមនុស្សដែលអ្នកអាចនិយាយទៅ; ម៉ូឌុល embedding គឺជាប្រព័ន្ធថតស្ថិតិល្អឥតខ្ចោះ។ +ដុំតូចៗនីមួយៗត្រូវបានបំលែងទៅជាចំណាំលេខ ដែលហៅថា embedding — មានន័យថា ជាឧបករណ៍បម្លែងអត្ថន័យទៅជាលេខ។ ម៉ូដែល embedding មិនមែនជា "ឆ្លាត" ដូចម៉ូដែល chat; វាមិនអាចដើរតាមសេចក្ដីណែនាំ ឬសន្និដ្ឋាន ឬឆ្លើយសំណួរបាន។ អ្វីដែលវាធ្វើបានគឺផ្គត់ផ្គង់អត្តន័យអត្ថបទទៅក្នុងទីតាំងគណិតវិទ្យា ដែលមានន័យដូចគ្នាស្ថិតជិតគ្នា — "ឡាន" ជិត "យានយន្ត" "គោលការណ៍បង្វិលប្រាក់" ជិត "ការត្រឡប់ប្រាក់"។ គិតថា ម៉ូដែល chat គឺជាមនុស្សដែលអ្នកអាចនិយាយ; ម៉ូដែល embedding គឺជាប្រព័ន្ធរៀបចំឯកសារល្អឥតខ្ចោះ។ -រូបភាពខាងក្រោមបង្ហាញចំណុចមួយនេះ — អត្ថបទចូល កំនត់វ៉ិចទ័រចេញ ហើយអត្ថន័យស្រដៀងគ្នានាំឱ្យវ៉ិចទ័រដំឡើងជិតគ្នា៖ +គំនូរខាងក្រោមបង្ហាញទ្រឹស្តីនេះ — អត្ថបទចូល ទិដ្ឋភាពលេខចេញ និងមានអត្ថន័យដូចគ្នាទៅជាវ៉ិចទ័រជិតៗគ្នា៖ Embedding Model Concept -*រូបភាពនេះបង្ហាញថាម៉ូឌុល embedding បម្លែងអត្ថបទទៅវ៉ិចទ័រជាលេខ ដាក់អត្ថន័យស្រដៀងគ្នាចំណាត់ជិតគ្នា ក្នុងវិស័យវ៉ិចទ័រ។* +*គំនូរនេះបង្ហាញពីរបៀបម៉ូដែល embedding បំលែងអត្ថបទទៅជាវ៉ិចទ័រលេខ ដាក់អត្ថន័យដូចគ្នាចូលជិតគ្នានៅក្នុងអាកាសវ៉ិចទ័រ។* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -រូបភាពបង្ហាញពីសំណុំនៃចរន្តពីរ ក្នុងផ្លូវភ្ជាប់ RAG និងថ្នាក់ LangChain4j ដែលអនុវត្ត។ ការបញ្ចូលទិន្នន័យ (រត់ពេលអាប់ឡូដ) ពីរការបំបែកឯកសារ, embedding ពកដុំ, និងរក្សាទុកតាម `.addAll()`។ ចរន្តសំណួរ (រត់រាល់ពេលអ្នកសួរ) ដាក់ embedding សំណួរ, ស្វែងរកក្នុងហាងតាម `.search()`, និងផ្ញើបរិបទដែលបានជ្រើសទៅកាន់ម៉ូឌុល chat។ ចរន្តទាំងពីរនេះភ្ជាប់គ្នាតាម interface `EmbeddingStore`៖ +គំនូរបង្ហាញពីចរន្តទាំងពីរនៃ pipeline RAG និងក្លាសស៍ LangChain4j ដែលអនុវត្តវា។ **ចរន្ត ingestion** (រត់ម្តងពេលផ្ទុកឯកសារ) បំបែកឯកសារ, បង្កើត embedding, ហើយផ្ទុកដោយ `.addAll()`។ **ចរន្តសំណួរ** (រត់រាល់ពេលអ្នកប្រើ) បង្កើត embedding សំណួរ, ស្វែងរកក្នុងឃ្លាំងដោយ `.search()`, ហើយផ្ញើបរិបទដែលបានជួបជុំទៅម៉ូដែល chat។ ចរន្តទាំងពីរជួបគ្នាចំណុច `EmbeddingStore` ដែលចែករំលែក៖ LangChain4j RAG Classes -*រូបភាពនេះបង្ហាញពីចរន្តពីរក្នុងផ្លូវភ្ជាប់ RAG — ingestion និង query — និងរបៀបភ្ជាប់តាម EmbeddingStore រួមវាយ។* +*គំនូរនេះបង្ហាញពីចរន្ត ingestion និងសំណួរនៃ pipeline RAG និងវាតភ្ជាប់គ្នាតាម `EmbeddingStore` មួយរួម។* -ពេលដែល embeddings ត្រូវបានរក្សាទុក ខ្លឹមសារដែលស្រដៀងគ្នានឹងជំបូរជាក្រុមនៅក្នុងវិស័យវ៉ិចទ័រ។ រូបភាពខាងក្រោមបង្ហាញឯកសារដែលទាក់ទងគ្នាដាក់ជារូបមន្តនៅជិតគ្នា ដូចជា Technical Docs, Business Rules, និង FAQs ដែលបង្កើតជាក្រុមច្បាស់លាស់។ +ពេលផ្ទុក embeddings រួច អត្ថបទដែលស្រដៀងគ្នានឹងត្រូវចែកជាក្រុមនៅក្នុងអាកាសវ៉ិចទ័រ។ គំនូរបង្ហាញនេះបង្ហាញឯកសារដែលពាក់ព័ន្ធគ្នាចុះជាចំណុចជិតៗគ្នា ដែលធ្វើឲ្យស្វែងរកមន្ដសញ្ញាអាចធ្វើបាន៖ Vector Embeddings Space -*រូបភាពនេះបង្ហាញពីការដាក់ក្រុមឯកសារតាមប្រធានបទក្នុងវិស័យវ៉ិចទ័រ 3D, ដែលផ្តល់ជាក្រុមច្បាស់លាស់ជាច្រើនប្រភេទ។* +*ការលេងស្ទាយខាងលើបង្ហាញពីការចែកជាក្រុមឯកសារដែលពាក់ព័ន្ធគ្នានៅក្នុងអាកាសវ៉ិចទ័រ 3D ដូចជាឯកសារបច្ចេកទេស, ច្បាប់អាជីវកម្ម និង FAQ ដែលបង្កើតក្រុមបំបែកច្បាស់។* -ពេលអ្នកស្វែងរក ប្រព័ន្ធនឹងអនុវត្តជានូវជំហានបួន៖ embed ឯកសារ ម្តង, embed សំណួរ រាល់ពេលស្វែងរក, ប្រៀបធៀបវ៉ិចទ័រសំណួរជាមួយវ៉ិចទ័រទាំងអស់តាម cosine similarity, ហើយត្រឡប់ម្ជុលដែលមានពិន្ទុខ្ពស់ចំនួន top-K។ រូបភាពខាងក្រោមបង្ហាញជ្រុលជំហាននីមួយៗ និងថ្នាក់ LangChain4j ដែលពាក់ព័ន្ធ៖ +ពេលមានសំណួរ ប្រព័ន្ធអនុវត្តបួនជំហានៈ បង្កើត embedding ឯកសារម្តងៗ, បង្កើត embedding សំណួរ រៀបចំវ៉ិចទ័រសំណួរស្របទៅវ៉ិចទ័រផ្ទុក ដោយប្រើ cosine similarity ហើយវិលត្រឡប់ក្រុមដុំដែលមានពិន្ទុខ្ពស់បំផុត។ គំនូរខាងក្រោមបង្ហាញរៀងរាល់ជំហាន និងក្លាសស៍ LangChain4j ដែលពាក់ព័ន្ធ៖ Embedding Search Steps -*រូបភាពនេះបង្ហាញដំណើរការស្វែងរកដោយ embedding បួនជំហាន៖ embed ឯកសារ, embed សំណួរ, ប្រៀបធៀវ៉ិចទ័រតាម cosine similarity, និងត្រឡប់លទ្ធផល top-K។* +*គំនូរនេះបង្ហាញដំណើរការស្វែងរកបួនជំហាន៖ បង្កើត embedding ឯកសារ, បង្កើត embedding សំណួរ, ប្រៀបធៀរវ៉ិចទ័រដោយ cosine similarity និងត្រឡប់លទ្ធផលល្អៗ។* -### ការស្វែងរកស្រដៀង +### Semantic Search [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -ពេលអ្នកសួរបញ្ហា សំណួរអ្នកក៏ត្រូវបានបម្លែងទៅជាវ៉ិចទ័រ embedding ផងដែរ។ ប្រព័ន្ធប្រៀបធៀប embedding នៃសំណួរអ្នកជាមួយ embedding នៃEach chunk of document។ វាស្វែងរកដុំដែលមានអត្ថន័យស្រដៀងគ្នាម៉ោង — មិនគ្រាន់តែស្វែងរកពាក្យគន្លឹះ ប៉ុន្តែស្វែងរកតាមអត្ថន័យពិតប្រាកដ។ +ពេលអ្នកសួរសំណួរ សំណួររបស់អ្នកក៏ត្រូវបានបម្លែងទៅជា embedding ផងដែរ។ ប្រព័ន្ធប្រៀបធៀប embedding សំណួររបស់អ្នកនឹង embedding របស់ដុំឯកសារទាំងអស់។ វាស្វែងរកដុំដែលមានអត្ថន័យស្រដៀងគ្នាជាងគេ — មិនមែនតែពាក្យគន្លឹះធម្មតាទេ ប៉ុន្តែមានភាពស្រដៀងចំពោះអត្ថន័យពិតប្រាកដ។ ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -រូបភាពខាងក្រោមប្រៀបធៀបស្វែងរកស្រដៀងនិងស្វែងរកពាក្យគន្លឹះបែបផ្ទាល់។ ការស្វែងរកពាក្យគន្លឹះ “យានយន្ត” បាត់ខ្លះពាក្យស្តីពី "ឡាន និងរថយន្ត" ប៉ុន្តែស្វែងរកស្រដៀងយល់ថាពួកវាមានន័យដូចគ្នា ហើយត្រឡប់ចម្លើយដែលមានពិន្ទុខ្ពស់មកវិញ៖ +គំនូរខាងក្រោមបង្ហាញការប្រៀបធៀបរវាងស្វែងរកដោយពាក្យគន្លឹះ និងស្វែងរកមន្ដសញ្ញា។ ស្វែងរកពាក្យគន្លឹះ "vehicle" មិនរកឃើញដុំអំពី "cars and trucks" តែស្វែងរកមន្ដសញ្ញាប្រាកដជាថាគួរតែស្វែងរកនិងឆ្លើយតបបានខ្ពស់៖ Semantic Search -*រូបភាពនេះប្រៀបធៀបស្វែងរកផ្អែកលើពាក្យគន្លឹះជាមួយស្វែងរកស្រដៀង បង្ហាញពីរបៀបដែលស្វែងរកស្រដៀងយកមាតិកាដែលពាក់ព័ន្ធជាគំនិត ទោះបីពាក្យគន្លឹះខុសគ្នាក៏ដោយ។* -ក្រោមធ្នូ ហត្ថកម្មភាពស្រដៀងគ្នាត្រូវបានវាស់ដោយប្រើភាពស្រដៀងគ្នា cosine — ជាការស្នើសុំថា "តើ Arrow ទាំងពីរនេះកំពុងបញ្ជាក់ទិសដូចគ្នាទេ?" ផ្នែកពីរអាចប្រើពាក្យខុសគ្នារួចមក តែកាលបរិច្ឆេទហើយ ពួកវាមានន័យដូចគ្នា vector របស់ពួកវាបញ្ជាក់ទិសដូចគ្នា និងមានពិន្ទុជិត 1.0៖ +*គំនូរនេះប្រៀបធៀបការស្វែងរកផ្អែកលើពាក្យគន្លឹះ និងមន្ដសញ្ញា បង្ហាញថាមន្ដសញ្ញាអាចយកមាតិកាដែលពាក់ព័ន្ធដោយគំនិត ទោះបីពាក្យគន្លឹះខុសគ្នាក៏ដោយ។* -Cosine Similarity +ក្រោមទ្វារទ្រង់ទ្រាយនេះ ភាពស្រដៀងគ្នាត្រូវបានវាស់ដោយ cosine similarity — ដូចជាសួរថា "គ្រែចំហៀងទាំងពីរនេះទៅទិសដូចគ្នាទេ?"។ ដុំពីរអាចប្រើពាក្យផ្សេងគ្នាទាំងស្រុង ប៉ុន្តែប្រសិនបើពួកវាមានអត្ថន័យដូចគ្នា វ៉ិចទ័ររបស់ពួកវាចង្អុលទៅទិសដូចគ្នានិងបានពិន្ទុជិត 1.0៖ -*រូបភាពនេះបង្ហាញពីភាពស្រដៀងគ្នា cosine ជាកំពស់ណែនกลางរវាងវេកទ័របញ្ចូល — វេកទ័រដែលស្របគ្នាច្បាស់មានពិន្ទុជិត 1.0 បង្ហាញពីភាពស្រដៀងគ្នាផ្នែកន័យខ្ពស់។* +Cosine Similarity +*រូបភាពនេះបង្ហាញពីភាពស្រដៀងគ្នារវាងកោងខ្លួននៃវ៉ិចទ័រ embedding — វ៉ិចទ័រដែលស្រដៀងគ្នាច្រើននឹងមានតម្លៃជិត 1.0 ដែលបង្ហាញពីភាពស្រដៀងគ្នាផ្នែកអត្ថន័យខ្ពស់។* > **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ហើយសួរ៖ -> - "តើការស្វែងរកភាពស្រដៀងគ្នាធ្វើការបានយ៉ាងដូចម្តេចជាមួយការបញ្ចូល និងតើអ្វីកំណត់ពិន្ទុ?" -> - "តើខ្នងដែនភាពស្រដៀងគ្នាណាដែលគួរត្រូវបានប្រើ ហើយវា​ផ្លាស់ប្តូរវិញលទ្ធផលយ៉ាងដូចម្តេច?" -> - "តើខ្ញុំគ្រប់គ្រងករណីដែលមិនមានឯកសារសាកសមបានយ៉ាងដូចម្តេច?" +> - "តើការស្វែងរកភាពស្រដៀងគ្នាធ្វើការដោយរបៀបណាមួយជាមួយ embeddings ហើយអ្វីទៅជាផ្នែកកំណត់ពិន្ទុ?" +> - "តើខ្ញុំគួរប្រើគន្លងភាពស្រដៀងគ្នាដូចម្តេច ហើយវាអាចប៉ះពាល់លទ្ធផលយ៉ាងដូចម្តេច?" +> - "តើខ្ញុំនឹងដោះស្រាយករណីនៅពេលគ្មានឯកសារទាក់ទងបែបណា?" -### ការផលិតចម្លើយ +### ការបង្កើតចម្លើយ [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -ផ្នែកដែលមានសារៈសំខាន់បំផុតត្រូវបានប្រមូលឡើងជាសំណុំសេចក្តីថ្លែងដែលមានការណែនាំច្បាស់លាស់ បរិបទដែលបានយកពីប្រតិបត្តិការ និងសំណួររបស់អ្នកប្រើ។ ម៉ូដែលអានផ្នែកជាក់លាក់នៃការបញ្ចូលនោះហើយឆ្លើយតបដោយផ្អែកលើព័ត៌មាននោះ — វាអាចប្រើតែអ្វីដែលមាននៅមុខវាប៉ុណ្ណោះ ដែលជួយទប់ស្កាត់ការស្រមៃខុស។ +ចំណែកដែលពាក់ព័ន្ធបំផុតត្រូវបានប្រមូលគ្នាទៅជាសំណួរដែលមានរចនាសម្ព័ន្ធ ដែលរួមមានការណែនាំច្បាស់លាស់, បរិបទដែលបានយកមក, និងសំណួររបស់អ្នកប្រើ។ ម៉ូឌែលនឹងអានចំណែកជាក់លាក់នោះ ហើយឆ្លើយតបយោងតាមព័ត៍មាន។ វាអាចប្រើតែអ្វីដែលមាននៅមុខវាប៉ុណ្ណោះ ដែលជាមធ្យោបាយទប់ទល់ការស្រមេញ។ ```java String context = matches.stream() @@ -236,95 +235,95 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` - -រូបភាពខាងក្រោមបង្ហាញពីការប្រមូលនេះក្នុងសកម្មភាព — ផ្នែកដែលមានពិន្ទុំួយបំផុតពីជំហានស្វែងរកត្រូវបានចាក់ចូលទៅក្នុងសំពាធរ_TEMPLATE_ ហើយ `OpenAiOfficialChatModel` បង្កើតចម្លើយស្ថាពរៈ + +រូបភាពខាងក្រោមបង្ហាញពីការប្រមូលផ្តុំការងារនេះ — ចំណែកដែលទទួលពិន្ទុខ្ពស់បំផុតពីជំហានស្វែងរកត្រូវបានដាក់ចូលទៅក្នុងគំរូសំណួរ ហើយ `OpenAiOfficialChatModel` បង្កើតចម្លើយដែលមានមូលដ្ឋាន៖ Context Assembly -*រូបភាពនេះបង្ហាញពីរបៀបដែលផ្នែកដែលមានពិន្ទុខ្ពស់បំផុតត្រូវបានប្រមូលជាសំពាធរ​រចនាម៉ូដ បណ្តាលឲ្យម៉ូដែលអាចបង្កើតចម្លើយមានមូលដ្ឋានពីទិន្នន័យរបស់អ្នក។* +*រូបភាពនេះបង្ហាញពីរបៀបដែលចំណែកដែលទទួលពិន្ទុខ្ពស់បំផុត ត្រូវបានប្រមូលផ្តុំទៅជា prompt ដែលមានរចនាសម្ព័ន្ធ ដើម្បីឲ្យម៉ូឌែលបង្កើតចម្លើយដែលមានមូលដ្ឋានពីទិន្នន័យរបស់អ្នក។* -## រត់កម្មវិធី +## ប្រតិបត្តិកម្មកម្មវិធី -**បញ្ជាក់ការតំឡើង៖** +**ផ្ទៀងផ្ទាត់ការដាក់បង្ហាញ៖** -ប្រាកដថាឯកសារ `.env` មាននៅក្នុងថតគោលជាមួយសញ្ញាប័ត្ររបស់ Azure (បានបង្កើតនៅពេល Module 01)។ ប្រតិបត្តិការនេះពីថត module (`03-rag/`): +ធានាថា​ឯកសារ `.env` មាននៅក្នុងថតដើម ជាមួយលិខិត​អ្នកប្រើប្រាស់ Azure (បានបង្កើតក្នុងម៉ូឌុល 01)។ ប្រតិបត្តិការនេះពីថតម៉ូឌុល (`03-rag/`)៖ **Bash:** ```bash cat ../.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **PowerShell:** ```powershell -Get-Content ..\.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # ត្រូវបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **ចាប់ផ្តើមកម្មវិធី៖** -> **កំណត់ចំណាំ៖** ប្រសិនបើអ្នកបានចាប់ផ្តើមកម្មវិធីទាំងអស់ដោយប្រើ `./start-all.sh` ពីថតគោល (ដូចដែលបានពិពណ៌នានៅ Module 01) ខ្នងនេះបានដំណើរការហើយនៅលើ port 8081 អ្នកអាចរំលងពាក្យបញ្ជាចាប់ផ្តើមខាងក្រោម ហើយចូលទៅកាន់ http://localhost:8081 ត្រង់។ +> **ចំណាំ៖** បើអ្នកបានចាប់ផ្តើមកម្មវិធីទាំងអស់ដោយប្រើ `./start-all.sh` ពីថតដើម (ដូចបានពិពណ៌នា ក្នុងម៉ូឌុល 01) ម៉ូឌុលនេះបានដំណើរការហើយនៅលើព្រិច 8081។ អ្នកអាចរំលងពាក្យបញ្ជារចាប់ផ្តើមខាងក្រោម ហើយចូលទៅ http://localhost:8081 នៅផ្ទាល់។ -**ជម្រើសទី 1: ប្រើ Spring Boot Dashboard (ណែនាំសម្រាប់អ្នកប្រើ VS Code)** +**ជម្រើស 1៖ ប្រើ Spring Boot Dashboard (ណែនាំសម្រាប់អ្នកប្រើ VS Code)** -Dev container រួមបញ្ចូលអ៊ិចស្ទេនស្យុង Spring Boot Dashboard ដែលផ្ដល់ផ្ទាំងចង្អុលមួយសម្រាប់គ្រប់គ្រងកម្មវិធី Spring Boot ទាំងអស់។ អ្នកអាចរកឃើញវានៅក្នុង Activity Bar ផ្នែកខាងឆ្វេងនៃ VS Code (ស្វែងរករូបតំណាង Spring Boot)។ +dev container មានការ​ដំឡើង Spring Boot Dashboard ដែលឲ្យចំណុចប្រទាក់វីស្វលម្រាប់គ្រប់គ្រងកម្មវិធី Spring Boot ទាំងអស់។ អ្នកអាចរកវានៅក្នុង Activity Bar នៅផ្នែកឆ្វេងនៃ VS Code (ស្វែងរករូបតំណាង Spring Boot)។ -ពី Spring Boot Dashboard អ្នកអាច៖ -- មើលកម្មវិធី Spring Boot ទាំងអស់ដែលមាននៅក្នុង workspace -- ចាប់ផ្តើម/បញ្ឈប់កម្មវិធីដោយចុចតែមួយ -- មើលកំណត់ហេតុកម្មវិធីបច្ចុប្បន្ន -- តាមដានស្ថានភាពកម្មវិធី +ពី Spring Boot Dashboard អ្នកអាច៖ +- មើលកម្មវិធី Spring Boot ទាំងអស់នៅក្នុងផ្ទៃការ +- ចាប់ផ្តើម/បរាជ័យកម្មវិធីដោយចុចតែមួយ +- មើលកំណត់ហេតុកម្មវិធីដោយពេលវេលានិយម +- ត្រួតពិនិត្យស្ថានភាពកម្មវិធី -គ្រាន់តែចុចប៊ូតុងចាក់ហ្គេមនៅជាប់ "rag" ដើម្បីចាប់ផ្តើមខ្នងនេះ ឬចាប់ផ្តើមម៉ូឌុលទាំងអស់ក្នុងមួយពេល។ +គ្រាន់តែចុចប៊ូតុងរត់ លើ "rag" ដើម្បីចាប់ផ្តើមម៉ូឌុលនេះ ឬចាប់ផ្តើមម៉ូឌុលទាំងអស់ពេលតែមួយ។ Spring Boot Dashboard -*រូបថតអេក្រង់នេះបង្ហាញ Spring Boot Dashboard ក្នុង VS Code ដែលអ្នកអាចចាប់ផ្តើម បញ្ឈប់ និងតាមដានកម្មវិធីដោយមានការបង្ហាញពីរូបភាពផ្ទាល់។* +*រូបថតអេក្រង់នេះបង្ហាញ Spring Boot Dashboard នៅក្នុង VS Code ដែលអ្នកអាចចាប់ផ្តើម បញ្ឈប់ និងត្រួតពិនិត្យកម្មវិធីដោយភាពវីស្វល។* -**ជម្រើសទី 2: ប្រើ script shell** +**ជម្រើស 2៖ ប្រើស្គ្រីប shell** -ចាប់ផ្តើមកម្មវិធីវេបសាយទាំងអស់ (module 01-04): +ចាប់ផ្តើមកម្មវិធីវែបទាំងអស់ (ម៉ូឌុល 01-04)៖ **Bash:** ```bash cd .. # ពីថតឫស ./start-all.sh ``` - + **PowerShell:** ```powershell cd .. # ពីថតឫស .\start-all.ps1 ``` - -ឬចាប់ផ្តើមតែម៉ូឌុលនេះប៉ុណ្ណោះ៖ + +ឬចាប់ផ្តើមម៉ូឌុលនេះប៉ុណ្ណោះ៖ **Bash:** ```bash cd 03-rag ./start.sh ``` - + **PowerShell:** ```powershell cd 03-rag .\start.ps1 ``` + +ស្គ្រីបទាំងពីរនេះផ្ទុកអថេរបរិស្ថានពីឯកសារ `.env` នៅថតដើមដោយស្វ័យប្រវត្តិ ហើយនឹងបើកសំណុំ JAR ប្រសិនបើវាមិនមាន។ -Script ទាំងពីរបង្ហាប់បញ្ចូលអថេរបរិស្ថានពីឯកសារ `.env` នៅថតគោលដោយស្វ័យប្រវត្តិ ហើយនឹងបង្កើត JAR បើវាមិនមាន។ - -> **កំណត់ចំណាំ៖** ប្រសិនបើអ្នកចង់បង្កើតម៉ូឌុលទាំងអស់ដោយដៃ មុនចាប់ផ្តើម៖ -> +> **ចំណាំ៖** ប្រសិនបើអ្នកចង់បង្កើតម៉ូឌុលទាំងអស់ដោយដៃ មុនចាប់ផ្តើម៖ +> > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + បើក http://localhost:8081 ក្នុងកម្មវិធីរុករករបស់អ្នក។ **ដើម្បីបញ្ឈប់៖** @@ -335,91 +334,91 @@ Script ទាំងពីរបង្ហាប់បញ្ចូលអថេរ # ឬ cd .. && ./stop-all.sh # ម៉ូឌុលទាំងអស់ ``` - + **PowerShell:** ```powershell -.\stop.ps1 # ម៉ូឌូលនេះតែប៉ុណ្ណោះ +.\stop.ps1 # ម៉ូឌុលនេះតែប៉ុណ្ណោះ # ឬ -cd ..; .\stop-all.ps1 # ម៉ូឌូល​ទាំងអស់ +cd ..; .\stop-all.ps1 # ម៉ូឌុលទាំងអស់ ``` - + ## ការប្រើប្រាស់កម្មវិធី -កម្មវិធីផ្ដល់ផ្ទៃមុខវេបសម្រាប់អាប់ឡូតឯកសារនិងសួរសំណួរ។ +កម្មវិធីនេះផ្តល់អេក្រង់វែបសម្រាប់បញ្ចូលឯកសារ និងសំណួរ។ RAG Application Interface -*រូបថតអេក្រង់នេះបង្ហាញផ្ទៃមុខកម្មវិធី RAG ដែលអ្នកអាចអាប់ឡូតឯកសារ ហើយសួរសំណួរ។* +*រូបថតអេក្រង់នេះបង្ហាញចំណុចប្រទាក់កម្មវិធី RAG ដែលអ្នកអាចបញ្ចូលឯកសារ និងសួរបញ្ហា។* -### អាប់ឡូតឯកសារ +### បញ្ចូលឯកសារ -ចាប់ផ្តើមដោយអាប់ឡូតឯកសារ - ថត TXT ធ្វើការល្អបំផុតសម្រាប់ការប្រលង។ មានឯកសារ `sample-document.txt` ផ្តល់នៅក្នុងថតនេះ ដែលមានព័ត៌មានអំពីមុខងារ LangChain4j, ការអនុវត្ត RAG និងរបៀបអនុវត្តល្អបំផុត - សមស្របសម្រាប់សាកល្បងប្រព័ន្ធ។ +ចាប់ផ្តើមដោយបញ្ចូលឯកសារ — ឯកសារ TXT ធ្វើការ​បានល្អសម្រាប់សាកល្បង។ មានឯកសារ `sample-document.txt` ផ្តល់ជូននៅក្នុងថតនេះដែលមានព័ត៌មានអំពីលក្ខណៈពិសេស LangChain4j, ការអនុវត្ត RAG, និងលក្ខណៈបច្ចេកទេសល្អៗ — ល្អឥតខ្ចោះសម្រាប់សាកល្បងប្រព័ន្ធ។ -ប្រព័ន្ធដំណើរការឯកសាររបស់អ្នក បំបែកវាជាចំណែកៗ ហើយបង្កើត embeddings សម្រាប់ចំណែកនីមួយៗ។ នេះកើតឡើងដោយស្វ័យប្រវត្តិខណៈអ្នកអាប់ឡូត។ +ប្រព័ន្ធនឹងដំណើរការឯកសាររបស់អ្នក ដាក់បំបែកវាជាចំណែក និងបង្កើត embeddings សម្រាប់ចំណែកនីមួយៗ។ នេះកើតឡើងដោយស្វ័យប្រវត្តិពេលអ្នកបញ្ចូលឯកសារ។ ### សួរសំណួរ -ឥឡូវនេះសូមសួរសំណួរជាក់លាក់អំពីមាតិកាឯកសារ។ សាកល្បងនិយាយពីអ្វីដែលមានភាពជាក់លាក់នៅក្នុងឯកសារ។ ប្រព័ន្ធស្វែងរកចំណែកដែលពាក់ព័ន្ធ បញ្ចូលវាទៅក្នុងសំពាធរ និងបង្កើតចម្លើយ។ +ឥឡូវនេះសួរសំណួរជាក់លាក់អំពីមាតិកាឯកសារ។ សូមសាកល្បងសំណួរដែលជាការពិតដែលបញ្ជាក់ច្បាស់នៅក្នុងឯកសារ។ ប្រព័ន្ធនឹងស្វែងរកចំណែកដែលពាក់ព័ន្ធ បញ្ចូលវាទៅក្នុង prompt ហើយបង្កើតចម្លើយ។ -### ពិនិត្យយោងប្រភព +### ពិនិត្យប្រភពយោង -ចំណាំថាចម្លើយនីមួយៗមានយោងប្រភពជាមួយពិន្ទុភាពស្រដៀងគ្នា។ ពិន្ទុទាំងនេះ (ចាប់ពី 0 ដល់ 1) បង្ហាញពីភាពសាកសមរបស់ចំណែកនីមួយៗចំពោះសំណួររបស់អ្នក។ ពិន្ទុខ្ពស់មានន័យថាផ្សំគ្នាឡើងបានល្អ។ នេះអនុញ្ញាតឲ្យអ្នកផ្ទៀងផ្ទាត់ចម្លើយជាមួយវត្ថុធាតុដើម។ +កត់សម្គាល់ថាចម្លើយនីមួយៗមានយោងកូដប្រភពជាមួយពិន្ទុភាពស្រដៀងគ្នា។ ពិន្ទុទាំងនេះ (ពី 0 ដល់ 1) បង្ហាញពីចំណែកណាដែលពាក់ព័ន្ធនឹងសំណួររបស់អ្នក។ ពិន្ទុខ្ពស់បង្ហាញពីការផ្គូផ្គងល្អ។ វាគ្រប់គ្រងឲ្យអ្នកអាចបញ្ជាក់ចម្លើយតាមសម្ភារៈប្រភពបាន។ RAG Query Results -*រូបថតអេក្រង់នេះបង្ហាញលទ្ធផលស្នើរសុំព្រមទាំងចម្លើយដែលបានបង្កើត, យោងប្រភព និងពិន្ទុភាពសមស្របសម្រាប់ចំណែកទាញយកនីមួយៗ។* +*រូបថតអេក្រង់នេះបង្ហាញលទ្ធផលសំណួរ ដែលមានចម្លើយបានបង្កើត លក្ខណៈយោងប្រភព និងពិន្ទុភាពស្រដៀងគ្នាសម្រាប់ចំណែកដែលបានយកមក។* ### សាកល្បងសំណួរ -សាកល្បងសំណួរប្រភេទផ្សេងៗ៖ -- ព័ត៌មានជាក់លាក់៖ "ប្រធានបទចម្បងគឺអ្វី?" -- ការប្រៀបធៀប៖ "តើខុសគ្នារវាង X និង Y មានអ្វីខ្លះ?" -- សង្ខេប៖ "សង្ខេបចំណុចសំខាន់អំពី Z" +សាកល្បងសំណួរប្រភេទផ្សេងៗ៖ +- ព័ត៌មានជាក់លាក់៖ "ប្រធានបទសំខាន់បំផុតគឺអ្វី?" +- ការប្រៀបធៀប៖ "តើចំណុចខុសគ្នារវាង X និង Y ជាអ្វី?" +- សេចក្តីសង្ខេប៖ "សង្ខេបចំណុចសំខាន់ៗអំពី Z" -មើលមើលពិន្ទុសមស្របប្រែប្រួលដូចម្តេចដោយផ្អែកលើរបៀបដែលសំណួររបស់អ្នកត្រូវគ្នាជាមួយមាតិកាឯកសារ។ +មើលពិន្ទុភាពស្រដៀងគ្នាប្រែប្រួលយ៉ាងដូចម្តេចអាស្រ័យលើរបៀបសំណួររបស់អ្នកផ្គូផ្គងនឹងមាតិកាឯកសារ។ ## គំនិតសំខាន់ៗ -### យុទ្ធសាស្ត្របំបែកចំណែក (Chunking) +###​យុទ្ធសាស្រ្តបំបែកចំណែក -ឯកសារត្រូវបានបំបែកជាចំណែក 300 តួអក្សរជាមួយ 30 តួអក្សរនៃការអូវចេញ។ ការតុល្យភាពនេះធ្វើឲ្យចំណែកនីមួយៗមានបរិបទគ្រប់គ្រាន់ដើម្បីមានអត្ថន័យ ខណៈពេលនៅតូចគ្រប់គ្រាល់ដើម្បីអាចដាក់ច្រើនចំណែកក្នុងសំពាធរ។ +ឯកសារត្រូវបានបំបែកជាចំណែក 300 តួអក្សរជាមួយភាពប្រហាក់ប្រហែល 30 តួអក្សរ រវាងចំណែក។ ការតម្រង់តុល្យនេះធានាថាចំណែកទាំងអស់មានបរិបទគ្រប់គ្រាន់ដើម្បីមានអត្ថន័យ ខណៈដែលនៅតូចគ្រប់គ្រាន់ដើម្បីរួមបញ្ចូលច្រើនចំណែកនៅក្នុង prompt។ -### ពិន្ទុភាពស្រដៀងគ្នា (Similarity Scores) +### ពិន្ទុភាពស្រដៀងគ្នា -ចំណែករាល់ផ្នែកដែលចាប់យកបាន ជាមួយពិន្ទុភាពស្រដៀងគ្នារវាង 0 និង 1 បង្ហាញថាតើវាដូចដល់សំណួររបស់អ្នកយ៉ាងណា។ រូបភាពខាងក្រោមបង្ហាញជួរពិន្ទុ និងរបៀបដែលប្រព័ន្ធប្រើប្រាស់វាដើម្បីត្រងលទ្ធផល៖ +ចំណែករាល់ទៅត្រឡប់មកទាំងអស់នាំមកជាមួយពិន្ទុភាពស្រដៀងគ្នារវាង 0 និង 1 ដែលបង្ហាញពីភាពផ្គូផ្គងជិតស្និទ្ធនឹងសំណួររបស់អ្នកប្រើ។ រូបភាពខាងក្រោមបង្ហាញជួរកំណត់ពិន្ទុ និងរបៀបប្រើប្រាស់សម្រាប់ត្រងលទ្ធផល៖ Similarity Scores -*រូបភាពនេះបង្ហាញពីជួរពិន្ទុចាប់ពី 0 ដល់ 1 ដែលមានខ្នងដែនគោល 0.5 ត្រៀមចំណែកដែលមិនពាក់ព័ន្ធកន្លែង។* +*រូបភាពនេះបង្ហាញជួរពិន្ទុពី 0 ទៅ 1 ជាមួយគន្លងតិចបំផុត 0.5 ដែលត្រងចេញចំណែកដែលគ្មានទាក់ទង។* -ពិន្ទុជួរពី 0 ដល់ 1៖ -- 0.7-1.0៖ ពាក់ព័ន្ធខ្ពស់, ទំនាក់ទំនងជាក់លាក់ -- 0.5-0.7៖ ពាក់ព័ន្ធ មាតិកាល្អ -- ต่ำกว่า 0.5៖ ត្រូវបានត្រះចេញ មិនសមរម្យ +ពិន្ទូមានជួរពី 0 ទៅ 1៖ +- 0.7-1.0៖ ពាក់ព័ន្ធខ្ពស់ ការផ្គូផ្គងត្រឹមត្រូវ +- 0.5-0.7៖ ពាក់ព័ន្ធ មានបរិបទល្អ +- ក្រោម 0.5៖ ត្រូវបានត្រងចេញ មិនស្រដៀងគ្នា -ប្រព័ន្ធយកតែចំណែកដែលមានពិន្ទូលើសខ្នងដែនគោលប៉ុណ្ណោះ ដើម្បីធានាថាគុណភាពល្អ។ +ប្រព័ន្ធទទួលតែចំណែកខ្ពស់ជាងគន្លងតិចបំផុត ដើម្បីធានាគុណភាព។ -ការបញ្ចូលគ្នាដំណើរការល្អពេលមានការបែងចែកមាតិកាដែលច្បាស់លាស់ ប៉ុន្តែវាមានចំណុចខ្វើល។ រូបភាពខាងក្រោមបង្ហាញពីលក្ខខណ្ឌបរាជ័យធម្មតា — ចំណែកធំពេកបណ្តាលវេកទ័រល្មោភ, ចំណែកតូចពេកងាយខ្វះបរិបទ, លក្ខណៈមិនច្បាស់បង្ហាញទៅកាន់ចំណែករាប់ពីរ, និងការស្វែងរកម្ដងតែមួយ(IDs, ល.ឈ្មោះផ្នែក) មិនសមស្របជាមួយការបញ្ចូលគ្នាទេ៖ +Embeddings ធ្វើការល្អនៅពេលផ្នែកន័យត្រូវបានក្រុមមានរឹងបូត្រពិស្ដី ប៉ុន្តែវាក៏មានចំណុចខ្សោយផងដែរ។ រូបភាពខាងក្រោមបង្ហាញអំពីជំងឺពេញនិយមសម្រាប់ embedding — ចំណែកធំពេកបង្កើតវ៉ិចទ័រមានភាពបាក់បែក, ចំណែកតូចពេកមិនមានបរិបទគ្រប់គ្រាន់, ពាក្យអبه្រតិលចៅខាតបង្ហាញចំណាត់ថ្នាក់ជាច្រើន, និងការស្វែងរកដោយភាពយ៉ាងត្រឺមត្រូវ (IDs, លេខផ្នែក) មិនអាចប្រើបានជាមួយ embeddings ទេ៖ Embedding Failure Modes -*រូបភាពនេះបង្ហាញពីលក្ខខណ្ឌបរាជ័យធម្មតាតាមការបញ្ចូល — ចំណែកធំ, ចំណែកតូច, លក្ខណៈមិនច្បាស់ដែលបង្ហាញចំណែកច្រើន, និងស្វែងរកត្រឹមត្រូវដូចជា ID។* +*រូបភាពនេះបង្ហាញពីរបៀបបរាជ័យទូទៅរបស់ embedding៖ ចំណែកធំពេក, ចំណែកតូចពេក, ពាក្យមិនច្បាស់ដែលបង្ហាញទៅកាន់ចំណាត់ថ្នាក់ទឹកប្រាក់ច្រើន, និងការស្វែងរកត្រឹមត្រូវដូចជា IDs។* -### ឃ្លាំងទិន្នន័យក្នុងម៉េម៉ូរី +### ការផ្ទុកនៅក្នុងម៉ាស៊ីន -ម៉ូឌុលនេះប្រើឃ្លាំងទិន្នន័យក្នុងម៉េម៉ូរីសម្រាប់ភាពសាមញ្ញ។ ប្រសិនបើអ្នកបើកកម្មវិធីឡើងវិញ ឯកសារដែលបានអាប់ឡូតនឹងបាត់បង់។ ប្រព័ន្ធផលិតកម្មប្រើប្រាស់មូលដ្ឋានទិន្នន័យវ៉ិចទ័រដែលជាប់ខ្ពស់ដូចជា Qdrant ឬ Azure AI Search។ +ម៉ូឌុលនេះប្រើការផ្ទុកក្នុងម៉ាស៊ីនសម្រាប់ភាពសាមញ្ញ។ ពេលអ្នកបញ្ចូលកម្មវិធីឡើងវិញ ឯកសារ​ដែលបានដាក់បញ្ចូលនឹងបាត់បង់។ ប្រព័ន្ធទីផ្សារប្រើមូលដ្ឋានទិន្នន័យវ៉ិចទ័រដែលបន្តបាន ដូចជា Qdrant ឬ Azure AI Search។ ### ការគ្រប់គ្រងបរិវេណបរិបទ -ម៉ូដែលនីមួយៗមានបរិវេណបរិបទអតិបរិមា។ អ្នកមិនអាចរួមបញ្ចូលចំណែកគ្រប់យ៉ាងពីឯកសារធំៗទាំងអស់បានទេ។ ប្រព័ន្ធនាំយកចំណែក N (លំនាំដើម 5) ដែលមានភាពពាក់ព័ន្ធខ្ពស់បំផុត ដើម្បីនៅក្នុងកំណត់ហេតុ និងផ្តល់បរិបទគ្រប់គ្រាន់សម្រាប់ចម្លើយត្រឹមត្រូវ។ +ម៉ូឌែលនីមួយៗមានបរិវេណបរិបទអតិបរមា។ អ្នកមិនអាចបញ្ចូលចំណែកគ្រប់អស់ពីឯកសារធំមួយបានទេ។ ប្រព័ន្ធរើសចំណែកទំនងបំផុត N (លំនាំដើម 5) ដើម្បីនៅក្នុងកម្រិត និងផ្តល់បរិបទគ្រប់គ្រាន់សម្រាប់ចម្លើយត្រឹមត្រូវ។ -## ពេលណាដែល RAG មានសារៈសំខាន់ +## ពេលដែល RAG មានសារៈសំខាន់ -RAG មិនមែនជាការជ្រើសរើសត្រឹមត្រូវគ្រប់ពេលទេ។ ជំនួយសំរាប់សម្រេចចិត្តខាងក្រោមជួយអ្នកកំណត់ពេលដែល RAG បន្ថែមតម្លៃ បើប្រៀបធៀបនឹងវិធីសាស្ត្រសាមញ្ញ — ដូចជាការរួមបញ្ចូលមាតិកាត្រូវក្នុងសំពាធរ ឬផ្អែកលើចំណេះដឹងដែលមានរបស់ម៉ូដែល — គឺគ្រប់គ្រាន់៖ +RAG មិនមែនជាវិធីសាស្រ្តត្រឹមត្រូវសម្រាប់គ្រប់ករណីទេ។ ឯកសារដឹកនាំខាងក្រោមជួយអ្នកកំណត់ពេលណា RAG បន្ថែមតម្លៃ បើប្រៀបធៀបនឹងវិធីសាមញ្ញៗ — ដូចជាភ្ជាប់មាតិកាចូលដោយផ្ទាល់ក្នុង prompt ឬពឹងផ្អែកលើចំណេះដឹងក្នុងម៉ូឌែល — មានគ្រាប់ខ្ទង់គ្រប់គ្រាន់៖ When to Use RAG -*រូបភាពនេះបង្ហាញឧបករណ៍សម្រេចចិត្តពេលណា RAG បន្ថែមតម្លៃ និងពេលណាវិធីសាមញ្ញគ្រប់គ្រាន់។* +*រូបភាពនេះបង្ហាញពិធីសាស្រ្តសម្រេចចិត្តពេលណា RAG បន្ថែមតម្លៃ និងពេលណា វិធីសាមញ្ញគ្រាប់ខ្ទង់គ្រប់គ្រាន់។* ## ជំហានបន្ទាប់ @@ -427,11 +426,11 @@ RAG មិនមែនជាការជ្រើសរើសត្រឹមត --- -**ការរុករក៖** [← សេចក្ដីមុន: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [ត្រឡប់ទៅផ្នែកមេ](../README.md) | [បន្ទាប់: Module 04 - Tools →](../04-tools/README.md) +**ការយោង៖** [← មុន៖ ម៉ូឌុល 02 - វិទ្យាសាស្ត្រ Prompt](../02-prompt-engineering/README.md) | [ត្រឡប់ទៅផ្ទាំងដើម](../README.md) | [បន្ទាប់៖ ម៉ូឌុល 04 - Tools →](../04-tools/README.md) --- -**ការបញ្ចេញការទទួលខុសត្រូវ**៖ -ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាកម្មបកប្រែ AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ខណៈពួកយើងខិតខំរកភាពត្រឹមត្រូវ សូមយល់ឲ្យបានថាការបកប្រែដោយស្វ័យប្រវត្តិអាចមានកំហុស ឬការមិនត្រឹមត្រូវ។ ឯកសារដើមក្នុងភាសាម្ចាស់របស់វាគួរត្រូវបានគិតថាជាមូលដ្ឋានសំខាន់។ សម្រាប់ព័ត៌មានសំខាន់ៗ ការបកប្រែដោយមនុស្សវិជ្ជាជីវៈត្រូវបានផ្ដល់អនុសាសន៍។ ពួកយើងមិនទទួលខុសត្រូវចំពោះការយល់ខុស ឬការបកស្រាយមិនត្រឹមត្រូវណាមួយដែលកើតឡើងពីការប្រើប្រាស់ការបកប្រែនេះ។ +**ការបដិសេធ**: +ឯកសារនេះត្រូវបានបម្លែងភាសា ដោយប្រើសេវាបម្លែងភាសា AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទោះយើងខ្ញុំមានក្តីប្រាថ្នាឱ្យបានច្បាស់លាស់ តែសូមយល់ដឹងថាការបម្លែងដោយស្វ័យប្រវត្តិក៏អាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមជាភាសាទីតាំងគួរត្រូវបានគេប្រើជាប្រភពច្បាស់លាស់។ សម្រាប់ព័ត៌មានសំខាន់ៗ សូមណែនាំឱ្យប្រើប្រាស់ការប្រែដោយមនុស្សជំនាញ។ យើងខ្ញុំមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកស្រាយខុសបន្ទាប់ពីការប្រើប្រាស់ការបម្លែងនេះនោះទេ។ \ No newline at end of file diff --git a/translations/km/04-tools/README.md b/translations/km/04-tools/README.md index 85dbdbdc3..dcb5c6469 100644 --- a/translations/km/04-tools/README.md +++ b/translations/km/04-tools/README.md @@ -1,84 +1,84 @@ -# Module ០៤៖ មនុស្សប្រើប្រាស់ AI ជាមួយឧបករណ៍ +# ម៉ូឌុល 04: អេយ្យង់ AI ជាមួយឧបករណ៍ ## តារាងមាតិកា -- [ការតំណើរកម្មវីដេអូ](#ការតំណើរកម្មវីដេអូ) +- [ការបង្ហាញវីដេអូ](#ការបង្ហាញវីដេអូ) - [អ្វីដែលអ្នកនឹងរៀន](#អ្វីដែលអ្នកនឹងរៀន) - [លក្ខខណ្ឌមុន](#លក្ខខណ្ឌមុន) -- [ការយល់ដឹងអំពីមនុស្សប្រើ AI ជាមួយឧបករណ៍](#ការយល់ដឹងអំពីមនុស្សប្រើ-ai-ជាមួយឧបករណ៍) -- [របៀបដែលការហៅឧបករណ៍ធ្វើការ](#របៀបដែលការហៅឧបករណ៍ធ្វើការ) - - [ការកំណត់ឧបករណ៍](#ការកំណត់ឧបករណ៍) - - [ការធ្វើសេចក្ដីសម្រេច](#ការធ្វើសេចក្ដីសម្រេច) - - [ការអនុវត្តន៍](#ការអនុវត្តន៍) - - [ការបង្កើតចម្លើយ](#ការបង្កើតចម្លើយ) - - [រចនាសម្ព័ន្ធ៖ ការតភ្ជាប់ Spring Boot យ៉ាងប្រពៃណី](#រចនាសម្ព័ន្ធ៖-ការតភ្ជាប់-spring-boot-យ៉ាងប្រពៃណី) -- [ការតភ្ជាប់ឧបករណ៍ជាសង្សា](#ការតភ្ជាប់ឧបករណ៍ជាសង្សា) -- [បើកមេរោគ](#បើកមេរោគ) -- [ការប្រើកម្មវិធី](#ការប្រើប្រាស់កម្មវិធី) - - [សាកល្បងការប្រើឧបករណ៍សាមញ្ញ](#សាកល្បងការប្រើឧបករណ៍សាមញ្ញ) - - [សាកល្បងការតភ្ជាប់ឧបករណ៍](#សាកល្បងការភ្ជាប់ឧបករណ៍) - - [មើលទិដ្ឋភាពការសន្ទនា](#មើលដំណើរការជជែក) - - [សាកល្បងជាមួយសំណើនានា](#សាកល្បងបញ្ចូលសំណើផ្សេងៗ) -- [មូលដ្ឋានគំនិត](#ទ្រឹស្តីសំខាន់ៗ) - - [គំរូ ReAct (ការពិចារណា និងអនុវត្ត)](#លំនាំ-react-ការត្រួតពិនិត្យ-និងសកម្មភាព) - - [ការពណ៌នាឧបករណ៍មានសារៈសំខាន់](#ការពិពណ៌នាឧបករណ៍មានសារៈសំខាន់) - - [ការគ្រប់គ្រងសម័យសន្ទនា](#ការគ្រប់គ្រងសម័យប្រតិបត្តិការ) - - [ការដោះស្រាយកំហុស](#ការគ្រប់គ្រងកំហុស) -- [ឧបករណ៍ដែលមាន](#ឧបករណ៍ដែលមានស្រាប់) -- [ពេលណាដែលត្រូវប្រើមនុស្សប្រើផ្អែកលើឧបករណ៍](#ពេលណានឹងប្រើភ្នាក់ងារដែលផ្អែកលើឧបករណ៍) -- [ឧបករណ៍ ប្រឆាំង RAG](#ឧបករណ៍-និង-rag) -- [ជំហានបន្ទាប់](#ជំហានបន្ទាប់) - -## ការតំណើរកម្មវីដេអូ - -មើលសម័យផ្សាយបន្តផ្ទាល់នេះដែលអោយពន្យល់ពីរបៀបចាប់ផ្ដើមជាមួយមេរោគនេះ៖ - -AI Agents with Tools and MCP - Live Session +- [ការយល់ដឹងអំពីអេយ្យង់ AI ជាមួយឧបករណ៍](#ការយល់ដឹងអំពីអេយ្យង់-ai-ជាមួយឧបករណ៍) +- [វិធីដែលការហៅឧបករណ៍ដំណើរការ](#វិធីដែលការហៅឧបករណ៍ដំណើរការ) + - [និយមន័យឧបករណ៍](#និយមន័យឧបករណ៍) + - [ការធ្វើសេចក្តីសម្រេច](#ការធ្វើសេចក្តីសម្រេច) + - [ការអនុវត្ត](#ការអនុវត្ត) + - [ការបង្កើតការឆ្លើយតប](#ការបង្កើតការឆ្លើយតប) + - [ស្ថាបត្យកម្ម៖ ការតភ្ជាប់ Spring Boot អូតូ](#ស្ថាបត្យកម្ម៖-ការតភ្ជាប់-spring-boot-អូតូ) +- [ការច្រកឧបករណ៍](#ការច្រកឧបករណ៍) +- [រត់កម្មវិធី](#រត់កម្មវិធី) +- [ការប្រើប្រាស់កម្មវិធី](#ការប្រើប្រាស់កម្មវិធី) + - [សាកល្បងការប្រើប្រាស់ឧបករណ៍សាមញ្ញ](#សាកល្បងការប្រើប្រាស់ឧបករណ៍ងាយៗ) + - [សាកល្បងការច្រកឧបករណ៍](#សាកល្បងការចងខ្សែឧបករណ៍) + - [មើលលំនាំការសន្ទនា](#មើលចម្ងល់ជជែក) + - [ចុះពិសោធន៍ជាមួយសំណើផ្សេងៗ](#សាកល្បងសំណើផ្សេងៗ) +- [គំនិតសំខាន់ៗ](#ការយល់ដឹងសំខាន់ៗ) + - [គំរូ ReAct (ការគិត និង ការប្រតិបត្តិការ)](#រចនាប័ទ្ម-react-ហេតុផល-និងសកម្មភាព) + - [ការពិពណ៌នាឧបករណ៍មានសារៈសំខាន់](#ការពិពណ៌នាឧបករណ៍មានសារៈសំខាន់) + - [ការគ្រប់គ្រងសម័យ](#ការគ្រប់គ្រងសម័យសន្ទនា) + - [ការដោះស្រាយកំហុស](#ការដោះស្រាយកំហុស) +- [ឧបករណ៍ដែលមាន](#ឧបករណ៍ដែលមាន) +- [ពេលណាជ្រើសប្រើអេយ្យង់លើគោលនយោបាយឧបករណ៍](#ពេលណា-គួរប្រើភ្នាក់ងារតាមឧបករណ៍) +- [ឧបករណ៍ប្រៀបធៀបជាមួយ RAG](#ឧបករណ៍ប្រៀបធៀប-rag) +- [ជំហានបន្ទាប់](#next-steps) + +## ការបង្ហាញវីដេអូ + +មើលសម័យផ្សាយបន្តផ្ទាល់នេះដែលពន្យល់ពីរបៀបចាប់ផ្តើមជាមួយម៉ូឌុលនេះ៖ + +អេយ្យង់ AI ជាមួយឧបករណ៍ និង MCP - សម័យផ្សាយបន្តផ្ទាល់ ## អ្វីដែលអ្នកនឹងរៀន -មកដល់ពេលនេះ អ្នកបានរៀនពីរបៀបធ្វើសន្ទនាជាមួយ AI ដើម្បីរៀបចំការរំពឹងទុកយ៉ាងមានប្រសិទ្ធភាព ហើយយកចម្លើយឲ្យស្ថិតក្នុងឯកសាររបស់អ្នក។ ប៉ុន្តែមានកំណត់មូលដ្ឋានមួយ៖ គំរូភាសាអាចបង្កើតតែអត្ថបទតែប៉ុណ្ណោះ។ វាមិនអាចពិនិត្យស្ថានភាពអាកាសធាតុ គណនា ស្វែងរកក្នុងមូលដ្ឋានទិន្នន័យ ឬតាំងស្ថិតិជាមួយប្រព័ន្ធក្រៅបានទេ។ +មកដល់ពេលនេះ អ្នកបានរៀនពីរបៀបមានការសន្ទនាជាមួយ AI ចាក់សោមកនិយមផ្តើមល្អ និងដាក់មូលដ្ឋានចម្លើយក្នុងឯកសាររបស់អ្នក។ ប៉ុន្តែមានកំណត់មូលដ្ឋានមួយ៖ ម៉ូឌែលភាសាអាចបង្កើតតែក្នុងអត្ថបទប៉ុណ្ណោះ។ ពួកវាមិនអាចពិនិត្យអាកាសធាតុ គណនាលទ្ធផល សាកសួរទិន្នន័យ ឬចូលរួមជាមួយប្រព័ន្ធខាងក្រៅបាន។ -ឧបករណ៍បម្លែងសម្រាប់នេះ។ ដោយផ្តល់ឱ្យគំរូនូវមុខងារដែលវាអាចហៅបាន អ្នកបម្លែងវាពីអ្នកបង្កើតអត្ថបទជាមនុស្សប្រើដែលអាចអនុវត្តសកម្មភាព។ គំរូសម្រេចចិត្តពេលណាដែលវាទាមទារឧបករណ៍ ត្រូវប្រើឧបករណ៍ណា និងអ្វីជាអ៊ុតប៉ារ៉ាម៉ែត្រដើម្បីផ្តល់។ កូដរបស់អ្នកអនុវត្តមុខងារ ហើយត្រឡប់លទ្ធផលវិញ។ គំរូបញ្ចូលលទ្ធផលនោះទៅក្នុងចម្លើយរបស់វា។ +ឧបករណ៍ផ្លាស់ប្តូរនេះ។ ដោយផ្តល់ឱ្យម៉ូឌែលនូវមុខងារ ដែលវាអាចហៅបាន អ្នកបម្លែងវា​ពីម៉ាស៊ីនបង្កើតអត្ថបទទៅជា អេយ្យង់ដែលអាចអនុវត្តសកម្មភាពបាន។ ម៉ូឌែលសម្រេចថាតើវាត្រូវការ ឧបករណ៍ណា ដើម្បីប្រើទេ ហើយត្រូវផ្តល់ប៉ារ៉ាម៉ែត្រអ្វី។ កូដរបស់អ្នកអនុវត្តមុខងារនោះហើយ ត្រឡប់លទ្ធផលមកវិញ។ ម៉ូឌែលបញ្ចូលលទ្ធផលនោះទៅក្នុងចម្លើយរបស់វា។ ## លក្ខខណ្ឌមុន -- បានបញ្ចប់ [មេរោគ ០១ - ការណែនាំ](../01-introduction/README.md) (ធនធាន Azure OpenAI បានដាក់តម្រូវ) -- បានបញ្ចប់មេរោគមុនៗដែលបានណែនាំ (មេរោគនេះយោងទៅលើ [មូលដ្ឋាន RAG ពីមេរោគ ០៣](../03-rag/README.md) ក្នុងការប្រៀបធៀបទៅឧបករណ៍ប្រឆាំង RAG) -- មានឯកសារ `.env` ក្នុងថតក្រឡាដំបូងជាមួយគណនី Azure (បង្កើតដោយ `azd up` នៅក្នុងមេរោគ ០១) +- បានបញ្ចប់ [ម៉ូឌុល 01 - ការណែនាំ](../01-introduction/README.md) (ធនធាន Azure OpenAI ត្រូវបានដាក់ឲ្យដំណើរការ) +- បានបញ្ចប់ម៉ូឌុលមុនៗដែលបានផ្ដល់អនុសាសន៍ (ម៉ូឌុលនេះយោងទៅតាម [គំនិត RAG ពី ម៉ូឌុល 03](../03-rag/README.md) ក្នុងការប្រៀបធៀប Tools vs RAG) +- មានឯកសារ `.env` នៅក្នុងថតដើម ដែលមានអត្តសញ្ញាណ Azure (បង្កើតដោយ `azd up` ក្នុងម៉ូឌុល 01) -> **ចំណាំ៖** ប្រសិនបើអ្នកមិនទាន់បញ្ចប់មេរោគ ០១ កុំភ្លេចអនុវត្តតាមការណែនាំដាក់តម្រូវនៅទីនោះជាមុន។ +> **សម្គាល់៖** ប្រសិនបើអ្នកមិនបានបញ្ចប់ម៉ូឌុល 01 សូមអនុវត្តបទបញ្ជារដ្ឋបាលការដាក់ឲ្យដំណើរការនោះជាមុនសិន។ -## ការយល់ដឹងអំពីមនុស្សប្រើ AI ជាមួយឧបករណ៍ +## ការយល់ដឹងអំពីអេយ្យង់ AI ជាមួយឧបករណ៍ -> **📝 ចំណាំ៖** ពាក្យ "agents" ក្នុងមេរោគនេះចង្អុលទៅកាន់ជំនួយការដែលមានសមត្ថភាពហៅឧបករណ៍ AI។ វាខុសគ្នាទៅពីគំរូ **Agentic AI** (មនុស្សប្រើអោយមានការធ្វើផែនការ ភ្លិចផ្លាស់ និងការពិចារណាច្រើនជំហាន) ដែលយើងនឹងរៀននៅ [មេរោគ ០៥: MCP](../05-mcp/README.md)។ +> **📝 សម្គាល់៖** ពាក្យថា "អេយ្យង់" ក្នុងម៉ូឌុលនេះ មានន័យជាអ្នកជំនួយ AI ដែលមានសមត្ថភាពហៅឧបករណ៍។ នេះខុសពីគំរូ **Agentic AI** (អេយ្យង់របស់តែម្នាក់ដែលមានការធ្វើដំណើរការប្រកបដោយផែនការ អង្គចងចាំ និងការគិតចម្រុះជាច្រើនជំហាន) ដែលយើងនឹងពិភាក្សា នៅក្នុង [ម៉ូឌុល 05: MCP](../05-mcp/README.md)។ -ហើយគ្មានឧបករណ៍ អ្នកត្រូវបង្កើតអត្ថបទតែមួយតាមចំណេះដឹងហ្វូងហ្វឺនរបស់វា។ ប្រសិនបើអ្នកសួរអំពីអាកាសធាតុបច្ចុប្បន្ន វាចាំបាច់ត្រូវវាយតម្លៃមិនពិតមែន។ ប្រសិនបើអ្នកផ្តល់ឧបករណ៍ វាអាចហៅ API អាកាសធាតុ ប្រេនកាលគណនា ឬស្វែងរកមូលដ្ឋានទិន្នន័យ — ហើយបន្ថែមលទ្ធផលពិតទៅក្នុងចម្លើយរបស់វា។ +គ្រប់ពេលដែលគ្មានឧបករណ៍ ម៉ូឌែលភាសាអាចបង្កើតបានតែក៍អត្ថបទពីទិន្នន័យហ្វឹកហាត់របស់វា។ សួរអំពីអាកាសធាតុបច្ចុប្បន្ន វាត្រូវតែទាយប៉ុណ្ណោះ។ ផ្តល់ឧបករណ៍វា វាអាចហៅ API អាកាសធាតុ បំពេញកំហិត សាកសួរទិន្នន័យ ហើយបញ្ចូលលទ្ធផលពិតទាំងនោះទៅក្នុងចម្លើយរបស់វា។ -Without Tools vs With Tools +គ្មានឧបករណ៍ ប្រៀបធៀប ជាមួយឧបករណ៍ -*គ្មានឧបករណ៍៖ គំរូត្រឹមតែទាយទ៉ៅ — មានឧបករណ៍៖ វាអាចហៅ API, ប្រតិបត្តិការ គណនា និងផ្តល់ទិន្នន័យពេលវេលាពិតបាន។* +*គ្មានឧបករណ៍ ម៉ូឌែលអាចទាយប៉ុណ្ណោះ — មានឧបករណ៍ វាអាចហៅ API ដំណើរការ គណនាលទ្ធផល និងបង្រួមទិន្នន័យពេលវេលាពិត។* -មនុស្សប្រើ AI ជាមួយឧបករណ៍អនុវត្តគំរូ **Reasoning and Acting (ReAct)**។ គំរូមិនត្រឹមតែឆ្លើយតប — វានឹកឃើញអ្វីដែលវាទាមទារ អនុវត្តដោយហៅឧបករណ៍ អង្កេតលទ្ធផល ហើយសម្រេចថាត្រូវអនុវត្តបន្តឬផ្តល់ចម្លើយចុងក្រោយ៖ +អេយ្យង់ AI ជាមួយឧបករណ៍អនុវត្តគំរូ **Reasoning and Acting (ReAct)**។ ម៉ូឌែលមិនត្រឹមតែឆ្លើយ — វាគិតអំពីអ្វីដែលវាត្រូវការ អនុវត្តដោយហៅឧបករណ៍ មើលលទ្ធផល ហើយសម្រេចចិត្តថាតើត្រូវអនុវត្តបន្ត ឬផ្តល់ចម្លើយចុងក្រោយ៖ -1. **ចិត្ដត្រូវ គិត** — មនុស្សប្រើវិភាគសំណួររបស់អ្នកប្រើ និងកំណត់ព័ត៌មានដែលត្រូវការ -2. **អនុវត្ត** — ជ្រើសឧបករណ៍ត្រឹមត្រូវ បង្កើតអ៊ុតប៉ារ៉ាម៉ែត្រត្រឹមត្រូវ ហើយហៅវា -3. **សង្កេត** — ទទួលយកលទ្ធផលឧបករណ៍ និងវាយតម្លៃលទ្ធផល -4. **ចម្លងឡើងវិញ ឬឆ្លើយតប** — បើត្រូវការទិន្នន័យបន្ថែម មនុស្សប្រើត្រឡប់ទៅជំហាន1 បើមិនដូច្នោះ វាបង្កើតចម្លើយភាសាធម្មជាតិ +១. **គិត** — អេយ្យង់វិភាគសំណួររបស់អ្នកប្រើ ហើយកំណត់ថាត្រូវការព័ត៌មានអ្វី +២. **អនុវត្ត** — អេយ្យង់ជ្រើសរើសឧបករណ៍ត្រឹមត្រូវ បង្កើតប៉ារ៉ាម៉ែត្រត្រឹមត្រូវ ហើយហៅវា +៣. **មើល** — អេយ្យង់ទទួលលទ្ធផលពីឧបករណ៍ និងវាយតំលៃលទ្ធផល +៤. **ធ្វើម្តុំបន្តឬឆ្លើយ** — ប្រសិនបើត្រូវការទិន្នន័យបន្ថែម អេយ្យង់ត្រឡប់ទៅដំណាក់កាលដើម ប្រសិនមិនទេ វាសរសេរចម្លើយភាសាពិតប្រាកដ -ReAct Pattern +គំរូ ReAct -*ជំរៅវដ្ត ReAct — មនុស្សប្រើគិតអំពីអ្វីដែលត្រូវធ្វើ អនុវត្តដោយហៅឧបករណ៍ សង្កេតលទ្ធផល ហើយធ្វើវដ្តរហូតដល់អាចផ្តល់ចម្លើយចុងក្រោយបាន។* +*លំនាំ ReAct — អេយ្យង់គិតពីអ្វីដែលត្រូវធ្វើ អនុវត្តដោយហៅឧបករណ៍ មើលលទ្ធផល ហើយធ្វើម្តុំរហូតដល់វាចម្លើយបាន។* -រឿងនេះកើតឡើងដោយស្វ័យប្រវត្តិ។ អ្នកកំណត់ឧបករណ៍ និងការពណ៌នារបស់វា។ គំរូគ្រប់គ្រងការធ្វើសេចក្តីសម្រេចពេលណា និងរបៀបប្រើវា។ +នេះកើតឡើងដោយស្វ័យប្រវត្តិ។ អ្នកកំណត់ឧបករណ៍ និងការពិពណ៌នារបស់ពួកវា។ ម៉ូឌែលទទួលខុសត្រូវលើការសម្រេចចិត្តថាតើពេលណា និងរបៀបប្រើពួកវា។ -## របៀបដែលការហៅឧបករណ៍ធ្វើការ +## វិធីដែលការហៅឧបករណ៍ដំណើរការ -### ការកំណត់ឧបករណ៍ +### និយមន័យឧបករណ៍ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -អ្នកកំណត់មុខងារជាមួយការពណ៌នាសម្គាល់ច្បាស់លាស់ និងលក្ខណៈប៉ារ៉ាម៉ែត្របញ្ជាក់។ គំរូឃើញការពណ៌នាទាំងនេះក្នុងប្រអប់ប្រព័ន្ធរបស់វា ហើយយល់ពីអ្វីដែលឧបករណ៍នីមួយៗធ្វើ។ +អ្នកកំណត់មុខងារជាមួយការពិពណ៌នាផ្អែកស្អាត និងការបញ្ជាក់ប៉ារ៉ាម៉ែត្រ។ ម៉ូឌែលមើលការពិពណ៌នាទាំងនេះក្នុង prompt ប្រព័ន្ធរបស់វា ហើយយល់ថាឧបករណ៍នីមួយៗធ្វើអ្វី។ ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // ការស្វែងរកអាកាសធាតុរបស់អ្នក + // ខ lógica ស្វែងរកអាកាសធាតុរបស់អ្នក return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,153 +96,153 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// ជំនួយការត្រូវបានភ្ជាប់ដោយស្វ័យប្រវត្តិដោយ Spring Boot ជាមួយៈ -// - ChatModel bean -// - វិធីសាស្រ្តទាំងអស់ @Tool ពីថ្នាក់ @Component -// - ChatMemoryProvider សម្រាប់ការគ្រប់គ្រងសម័យ​ប្រើប្រាស់ +// ជំនួយករត្រូវបានភ្ជាប់ដោយ Spring Boot ដោយស្វ័យប្រវត្តិជាមួយ៖ +// - កំណត់ Bean ChatModel +// - វិធីសាស្រ្ត @Tool ទាំងអស់ពីថ្នាក់ @Component +// - ChatMemoryProvider សម្រាប់ការគ្រប់គ្រងសម័យ ``` + +រូបរាងខាងក្រោមបំបែកអនុសាសន៍នីមួយៗ ហើយបង្ហាញថាផ្នែកណាមួយជួយ AI យល់ពេលណាហៅឧបករណ៍ និងប៉ារ៉ាម៉ែត្រអ្វី៖ -ផែនរូបមួយខាងក្រោមបំបែករាល់ស្លាក និងបង្ហាញអំពីរបៀបដែលមុខងារទាំងនេះជួយ AI យល់ពេលហៅឧបករណ៍ និងអ្វីជាអ៊ុតប៉ារ៉ាម៉ែត្រដែលវាត្រូវផ្ដល់៖ +រចនាសម្ព័ន្ធនៃនិយមន័យឧបករណ៍ -Anatomy of Tool Definitions - -*រចនាសម្ព័ន្ធនៃការកំណត់ឧបករណ៍ — @Tool ប្រាប់ AI ពេលប្រើវា @P ពណ៌នាពីអ៊ុតប៉ារ៉ាម៉ែត្រនីមួយៗ និង @AiService ភ្ជាប់គ្រប់របស់នៅពេលចាប់ផ្ដើម។* +*រចនាសម្ព័ន្ធនៃនិយមន័យឧបករណ៍ — @Tool ប្រាប់ AI ពេលត្រូវប្រើវា, @P ពិពណ៌នាប៉ារ៉ាម៉ែត្រនីមួយៗ និង @AiService តភ្ជាប់រួមគ្រប់យ៉ាងក្នុងពេលចាប់ផ្តើម។* > **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ហើយសួរ៖ -> - "តើធ្វើដូចម្តេចដើម្បីភ្ជាប់ API អាកាសធាតុពិតដូចជា OpenWeatherMap ជំនួសទិន្នន័យគំរូ?" -> - "អ្វីដែលធ្វើឲ្យការពណ៌នាឧបករណ៏ល្អ ដែលជួយ AI ប្រើវាបានត្រឹមត្រូវ?" -> - "តើធ្វើដូចម្តេចដើម្បីដោះស្រាយកំហុស API និងកំណត់កម្រិតអត្រាក្នុងការអនុវត្តឧបករណ៍?" +> - "តើធ្វើដូចម្តេចដើម្បីអន្តរកម្មជាមួយ API អាកាសធាតុពិតៗដូចជា OpenWeatherMap ជំនួសទិន្នន័យគំរូ?" +> - "តើអ្វីជាការពិពណ៌នាឧបករណ៍ល្អដែលជួយ AI ប្រើវាបានត្រឹមត្រូវ?" +> - "តើត្រូវដោះស្រាយកំហុស API និងកំណត់កំណត់អត្រាដូចម្តេចនៅក្នុងអនុវត្តឧបករណ៍?" -### ការធ្វើសេចក្ដីសម្រេច +### ការធ្វើសេចក្តីសម្រេច -ពេលដែលអ្នកប្រើសួរ "អាកាសធាតុបច្ចុប្បន្ននៅ Seattle ជាអ្វី?" គំរូមិនបានជ្រើសឧបករណ៍មួយដោយចៃដន្យ។ វាប្រៀបធៀបបំណងអ្នកប្រើទៅនឹងការពណ៌នានៃឧបករណ៍ដែលវាមាន ប្រមានពិន្ទុរៀងរាល់ឧបករណ៍ ហើយជ្រើសឧបករណ៍ល្អបំផុត។ បន្ទាប់មកវាបង្កើតហៅមុខងារមានរចនាសម្ព័ន្ធជាមួយអ៊ុតប៉ារ៉ាម៉ែត្រដែលត្រឹមត្រូវ — ក្នុងករណីនេះ គឺកំណត់ `location` ទៅជា `"Seattle"`។ +ពេលអ្នកប្រើសួរ "អាកាសធាតុនៅ Seattle ជាអ្វី?" ម៉ូឌែលមិនជ្រើសឧបករណ៍ដោយចៃដន្យទេ។ វាប្រៀបធៀបเจตនារបស់អ្នកប្រើជាមួយការពិពណ៌នាឧបករណ៍ទាំងអស់ ហើយផ្ដល់ពិន្ទុរៀងរាល់ឧបករណ៍នីមួយៗ នឹងជ្រើសរើសឧបករណ៍ល្អបំផុត។ បន្ទាប់មក វាបង្កើតការហៅមុខងារដោយរចនាសម្ព័ន្ធជាមួយប៉ារ៉ាម៉ែត្រ ត្រឹមត្រូវ — ក្នុងករណីនេះ កំណត់ `location` ទៅ `"Seattle"`។ -បើគ្មានឧបករណ៍ណាផ្គូផ្គងសំណើអ្នកប្រើ គំរូនឹងឆ្លើយតបពីចំណេះដឹងផ្ទាល់ខ្លួន។ ប្រសិនបើមានឧបករណ៍ជាច្រើនផ្គូផ្គង គំរូជ្រើសយកឧបករណ៍ដែលពិសេសបំផុត។ +បើគ្មានឧបករណ៍ណាមួយផ្គូរផ្គងសំណើររបស់អ្នកប្រើ ម៉ូឌែលត្រូវតបតាមចំណេះដឹងផ្ទាល់ខ្លួន។ បើមានឧបករណ៍ជាច្រើនផ្គូរផ្គង វាជ្រើសដ៏ច្បាស់លាស់បំផុត។ -How the AI Decides Which Tool to Use +របៀបដែល AI សម្រេចចិត្តជ្រើសរើសឧបករណ៍ -*គំរូវាយតម្លៃរាល់ឧបករណ៍ដែលអាចប្រើទៅនឹងបំណងអ្នកប្រើ ហើយជ្រើសឧបករណ៍ល្អបំផុត — ដូច្នេះហេតុអ្វីបានជាការសរសេរការពណ៌នាឧបករណ៍យ៉ាងច្បាស់ និងពិសេសមានសារៈសំខាន់។* +*ម៉ូឌែលវាយតំលៃឧបករណ៍ទាំងអស់ជាមួយចេតនារបស់អ្នកប្រើ ហើយជ្រើសឧបករណ៍ល្អបំផុត — នេះហេតុអ្វីបានជាការសរសេរការពិពណ៌នាឧបករណ៍ច្បាស់លាស់ និងច្បាស់ថាអ្វីសំខាន់។* -### ការអនុវត្តន៍ +### ការអនុវត្ត [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot តភ្ជាប់ដោយស្វ័យប្រវត្តិ `@AiService` ជាមួយឧបករណ៍ដែលបានចុះបញ្ជីទាំងអស់ ខណៈ LangChain4j អនុវត្តហៅឧបករណ៍យ៉ាងស្វ័យប្រវត្តិ។ នៅក្រោយមេឃ វដ្តហៅឧបករណ៍ពេញលេញឆ្លងកាត់ចំនួនប្រាំមួយជំហាន — ពីសំណួរភាសាធម្មជាតិរបស់អ្នកប្រើមកដល់ចម្លើយភាសាធម្មជាតិវិញ៖ +Spring Boot តភ្ជាប់ដោយស្វ័យប្រវត្តិនូវចំណុច `@AiService` ដែលមានអ៊ីនធើហ្វេសរជាមួយឧបករណ៍ចុះបញ្ជីទាំងអស់ ហើយ LangChain4j អនុវត្តការហៅឧបករណ៍ដោយស្វ័យប្រវត្តិ។ នៅផ្នែកខាងក្រោយ មានដំណើរការហៅឧបករណ៍គ្រប់ប្រយោគប្រាំមួយជំហាន — ពីសំណួរ ភាសាធម្មជាតិរបស់អ្នក ប្រហែលមកដល់ចម្លើយភាសាធម្មជាតិ៖ -Tool Calling Flow +លំនាំហៅឧបករណ៍ -*ដំណើរការពេញលេញ៖ អ្នកប្រើសួរសំណួរ គំរូជ្រើសឧបករណ៍ LangChain4j អនុវត្តមុខងារ ហើយគំរូបញ្ចូលលទ្ធផលទៅក្នុងចម្លើយធម្មជាតិ។* +*លំនាំដំណើរការពេញលេញ — អ្នកប្រើសួរសំណួរ ម៉ូឌែលជ្រើសឧបករណ៍ LangChain4j អនុវត្តវា ហើយម៉ូឌែលបញ្ចូលលទ្ធផលក្នុងចម្លើយ។ -បើអ្នកបានរត់ [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) នៅក្នុងមេរោគ ០០ អ្នកបានឃើញគំរូនេះក្នុងសកម្មភាពហើយ — ឧបករណ៍ `Calculator` ត្រូវបានហៅដូចគ្នា។ គំនូសម៉ូដលម្រោយខាងក្រោមបង្ហាញអ្វីដែលកើតឡើងនៅក្រោមម្ខាងបែបនេះ៖ +នៅផ្នែកខាងក្រោយ, `AiServices` ប្រតិបត្តិដំណើរការហៅឧបករណ៍ដូចគ្នាសម្រាប់ឧបករណ៍ណាមួយ — នៅទីនេះបង្ហាញជាមួយ `Calculator` សាមញ្ញ។ រូបរាងលំដាប់ក្រោមបង្ហាញគ្រប់អ្វីកើតឡើងក្រោមស្បែក៖ -Tool Calling Sequence Diagram +រូបទីតាំងលំដាប់ហៅឧបករណ៍ -*វដ្តហៅឧបករណ៍ពីសំណួរ Quick Start — `AiServices` ផ្ញើសារ និងស_SCHEMA_ឧបករណ៍ទៅ LLM, LLM ឆ្លើយនៅជាមួយហៅមុខងារដូចជា `add(42, 58)`, LangChain4j ធ្វើវិធីសាស្រ្ត `Calculator` នៅក្នុងមូលដ្ឋាន និងដាក់ទិន្នន័យវិញសម្រាប់ចម្លើយចុងក្រោយ។* +*ដំណើរការហៅឧបករណ៍ — `AiServices` ផ្ញើសាររបស់អ្នក និងស្គីម៉ាតឧបករណ៍ទៅ LLM, LLM តបនូវហៅមុខងារដូចជា `add(42, 58)`, LangChain4j អនុវត្តមេធតិគេទ locally, ហើយផ្ញើលទ្ធផលត្រឡប់សម្រាប់ចម្លើយចុងក្រោយ។* > **🤖 សាកល្បងជាមួយ [GitHub Copilot](https://github.com/features/copilot) Chat:** បើក [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ហើយសួរ៖ -> - "តើគំរូ ReAct ដំណើរការយ៉ាងដូចម្តេច និងហេតុអ្វីវាអាចមានប្រសិទ្ធភាពសម្រាប់មនុស្សប្រើ AI?" -> - "តើមនុស្សប្រើសម្រេចចិត្តប្រើឧបករណ៍ណា និងរៀបលំដាប់យ៉ាងដូចម្តេច?" -> - "តើមានអ្វីកើតឡើង បើការអនុវត្តឧបករណ៍មួយបរាជ័យ — តើត្រូវដោះស្រាយកំហុសយ៉ាងម៉េចឲ្យរឹងមាំ?" +> - "តើគំរូ ReAct ដំណើរការយ៉ាងដូចម្តេច ហើយហេតុអ្វីវាមានប្រសិទ្ធភាពសម្រាប់អេយ្យង់ AI?" +> - "តើអេយ្យង់សម្រេចចិត្តជ្រើសរើសឧបករណ៍ណា និងតាមលំដាប់ដូចម្តេច?" +> - "តើមានអ្វីកើតឡើងប្រសិនបើការអនុវត្តឧបករណ៍បរាជ័យ - តើខ្ញុំគួរដោះស្រាយកំហុសយ៉ាងរឹងមាំដូចម្ដេច?" -### ការបង្កើតចម្លើយ +### ការបង្កើតការឆ្លើយតប -គំរូទទួលយកទិន្នន័យអាកាសធាតុ ហើយបំលែងវាទៅជាចម្លើយភាសាធម្មជាតិចំពោះអ្នកប្រើ។ +ម៉ូឌែលទទួលបានទិន្នន័យអាកាសធាតុ ហើយបំលែងវាទៅជាចម្លើយភាសាធម្មជាតិសម្រាប់អ្នកប្រើ។ -### រចនាសម្ព័ន្ធ៖ ការតភ្ជាប់ Spring Boot យ៉ាងប្រពៃណី +### ស្ថាបត្យកម្ម៖ ការតភ្ជាប់ Spring Boot អូតូ -មេរោគនេះប្រើការបញ្ចូល LangChain4j ជាមួយ Spring Boot រូបមន្ត `@AiService` ។ នៅពេលចាប់ផ្ដើម Spring Boot រកឃើញគ្រប់ `@Component` ដែលមានវិធីសាស្រ្ត `@Tool`, គ្រឿងចក្រ `ChatModel` និងអ្នកផ្គត់ផ្គង់ចងចាំ `ChatMemoryProvider` ហើយភ្ជាប់ទាំងអស់ទៅក្នុងរូបមន្ត `Assistant` ដោយគ្មានកូដច្រើន។ +ម៉ូឌុលនេះប្រើប្រាស់ការតភ្ជាប់ Spring Boot របស់ LangChain4j ជាមួយអ៊ីនធើហ្វេស `@AiService` ដោយប្រកាស។ នៅពេលចាប់ផ្តើម Spring Boot រកឃើញគ្រប់ `@Component` ដែលមានមធ្យោបាយ `@Tool` ទំព័ររបស់អ្នក `ChatModel` ប៊ីន និង `ChatMemoryProvider` — បន្ទាប់មកតភ្ជាប់គ្នាទៅជា អ៊ីនធើហ្វេស Assistant តែមួយដោយគ្មានការចាំបាច់គ្រប់គ្រងនៅដៃ។ -Spring Boot Auto-Wiring Architecture +ស្ថាបត្យកម្មតភ្ជាប់ Spring Boot អូតូ -*រូបមន្ត @AiService ភ្ជាប់ ChatModel, ប្លកបន្ទះឧបករណ៍ និងអ្នកផ្គត់ផ្គង់ចងចាំ — Spring Boot គ្រប់គ្រងការតភ្ជាប់ពេញលេញដោយស្វ័យប្រវត្តិ។* +*អ៊ីនធើហ្វេស @AiService ភ្ជាប់រួម ChatModel, គ្រឿងផ្នែកឧបករណ៍, និងអ្នកផ្គត់ផ្គង់អង្គចងចាំ — Spring Boot គ្រប់គ្រងការតភ្ជាប់នូវទាំងអស់ដោយស្វ័យប្រវត្តិ។* -ខាងក្រោមគឺជាចំណុចអង្គការសំណើពេញលេញជាគំនូសម៉ូដល — ពីសំណើ HTTP ក្រោមកម្មវិធីគ្រប់គ្រង កម្មវិធីសេវា និងដំណាក់កាលភ្ជាប់ដោយស្វ័យប្រវត្តិ រហូតដល់ការអនុវត្តឧបករណ៍ និងត្រឡប់វិញ៖ +នេះជារូបភាពលំដាប់ពេញលេញនៃជីវចក្រសំណើ — ពីសំណើ HTTP តាមរយៈ Controller, Service, និង Proxy តភ្ជាប់ដោយស្វ័យប្រវត្តិ ទៅដល់ការអនុវត្តឧបករណ៍ និងត្រឡប់មកវិញ៖ -Spring Boot Tool Calling Sequence +រូបទីតាំងលំដាប់ហៅឧបករណ៍ Spring Boot -*ជីវិតវដ្តសំណើ Spring Boot ពេញលេញ — សំណើ HTTP ប្រតិបត្តិការតាមរយៈកម្មវិធីគ្រប់គ្រង និងសេវា ទៅអ្នក代理 Assistant ភ្ជាប់ដោយស្វ័យប្រវត្តិ ដែលគ្រប់គ្រង LLM និងហៅឧបករណ៍ដោយស្វ័យប្រវត្តិ។* +*ជីវចក្រ សំណើ Spring Boot ពេញលេញ — សំណើ HTTP ឌូលបានតាម Controller និង Service ទៅ Proxy Assistant តភ្ជាប់ដោយស្វ័យប្រវត្តិ ដែលបញ្ជាលម្អិត LLM និងការហៅឧបករណ៍ដោយស្វ័យប្រវត្តិ។* អត្ថប្រយោជន៍សំខាន់ៗនៃវិធីនេះ៖ -- **Spring Boot auto-wiring** — ChatModel និងឧបករណ៍វាយដាក់ទៅដោយស្វ័យប្រវត្តិ -- **គំរូ @MemoryId** — ការគ្រប់គ្រងចងចាំក្នុងសម័យដោយស្វ័យប្រវត្តិ -- **ឯកតាតែមួយ** — បង្កើតឧបករណ៍ Assistant មួយលើក និងប្រើជាញឹកញាប់ ដើម្បីប្រសើរឡើង -- **ការអនុវត្តអោយជាប់ប្រភេទ** — វិធីសាស្រ្ត Java ត្រូវហៅដោយផ្ទាល់ ជាមួយការបំលែងប្រភេទ -- **ការគ្រប់គ្រងជាច្រើនជំហាន** — គ្រប់គ្រងរលូនការតភ្ជាប់ឧបករណ៍ដោយស្វ័យប្រវត្តិ -- **គ្មានកូដមួយជូន** — គ្មានការហៅដោយដៃ `AiServices.builder()` ឬ Map ចងចាំ HashMap +- **Spring Boot auto-wiring** — ChatModel និងឧបករណ៍ត្រូវបានចាក់បញ្ចូលដោយស្វ័យប្រវត្តិ +- **គំរូ @MemoryId** — ការគ្រប់គ្រងអង្គចងចាំផ្អែកលើសម័យដោយស្វ័យប្រវត្តិ +- **ឧបករណ៍តែមួយ** — Assistant បង្កើតម្តងហើយប្រើបន្តសម្រាប់សមត្ថភាពល្អបំផុត +- **ការអនុវត្តប្រភេទសុវត្ថិភាព** — ហៅវិធីសាស្ត្រ Java ដោយផ្ទាល់ជាមួយការបម្លែងប្រភេទ +- **ការបង្រួមជាច្រើនជំហាន** — គ្រប់គ្រងការច្រកឧបករណ៍ដោយស្វ័យប្រវត្តិ +- **គ្មាន boilerplate** — គ្មានការហៅ `AiServices.builder()` យ៉ាងដៃ អោយ HashMap អង្គចងចាំ។ -វិធីសាស្រ្តជំនួស (អនុវត្តដោយដៃ `AiServices.builder()`) ត្រូវការកូដច្រើនជាង និងខ្វះអត្ថប្រយោជន៍ Spring Boot។ +វិធីនិយមផ្សេងទៀត (ធ្វើដោយដៃ `AiServices.builder()`) ត្រូវការកូដច្រើនជាង និងខ្វះអត្ថប្រយោជន៍របស់ Spring Boot។ -## ការតភ្ជាប់ឧបករណ៍ជាសង្សា +## ការច្រកឧបករណ៍ -**ការតភ្ជាប់ឧបករណ៍ជាសង្សា** — អំណាចពិតប្រាកដនៃមនុស្សប្រើផ្អែកលើឧបករណ៍ បង្ហាញពេលសំណួរតែមួយតម្រូវឲ្យប្រើឧបករណ៍មួយចំនួន។ សួរ "អាកាសធាតុបច្ចុប្បន្ននៅ Seattle ជា Fahrenheit យ៉ាងដូចម្តេច?" មនុស្សប្រើអូតូម៉ាទិកវត្ថុធាតុឧបករណ៍ពីរជញ្ជាំង៖ ជំហានដំបូងហៅ `getCurrentWeather` ដើម្បីទទួលសីតុណ្ហភាពជាសេลស្យុស រួចបញ្ជូនតម្លៃនោះទៅ `celsiusToFahrenheit` សម្រាប់បម្លែង — ទាំងអស់នៅក្នុងវដ្តសន្ទនាតែមួយ។ +**ការច្រកឧបករណ៍** — កម្លាំងពិតប្រាកដនៃអេយ្យង់លើពិធីប៍តឧបករណ៍បង្ហាញខ្លួនពេលសំណួរតែមួយត្រូវការឧបករណ៍ច្រើន។ សួរ "អាកាសធាតុនៅ Seattle នៅក្នុង Fahrenheit ជារូបមន្តបែបណា?" ហើយអេយ្យង់ច្រកឧបករណ៍ពីរដងស្វ័យប្រវត្តិ៖ ជាលំដាប់ វាហៅ `getCurrentWeather` ដើម្បីទទួលសីតុណ្ហភាពជាដំណាក់កាលសែលស្យុស បន្ទាប់មកផ្ដល់តម្លៃនោះទៅ `celsiusToFahrenheit` សម្រាប់បម្លែង — សរុបនៅក្នុងជំហានសន្ទនាតែមួយ។ -Tool Chaining Example +ឧទាហរណ៍ការច្រកឧបករណ៍ -*ការតភ្ជាប់ឧបករណ៍ក្នុងសកម្មភាព — មនុស្សប្រើហៅ getCurrentWeather ជាជំហានដំបូង បន្ទាប់បញ្ចូលលទ្ធផលសេលស្យុសទៅជា celsiusToFahrenheit ហើយផ្តល់ចម្លើយរួមជាមួយគ្នា។* +*ការច្រកឧបករណ៍ក្នុងសកម្មភាព — អេយ្យង់ហៅ getCurrentWeather ជាលំដាប់ដើម បន្ទាប់បញ្ចូលលទ្ធផលសែលស្យុសទៅ celsiusToFahrenheit ហើយផ្តល់ចម្លើយរួមជាមួយ។* -**មិនបានជោគជ័យយ៉ាងស្រស់ស្អាត** — សួរអំពីអាកាសធាតុនៅទីក្រុងមួយដែលមិនមានក្នុងទិន្នន័យគំរូ។ ឧបករណ៍ត្រឡប់មកនូវសារ ខុស និង AI ពន្យល់ថាវាមិនអាចជួយបានជាងការបំបួលកម្មវិធី។ ឧបករណ៍បរាជ័យយ៉ាងសុវត្ថិភាព។ ផែនរូបខាងក្រោមបង្ហាញការប្រៀបធៀបរវាងពីរវិធី — ជាមួយការដោះស្រាយកំហុសត្រឹមត្រូវ មនុស្សប្រើចាប់ករណី និងឆ្លើយតបដោយជួយសម្រួល ខណៈគ្មានវា កម្មវិធីទាំងមូលបរាជ័យចុះ៖ +**ការបរាជ័យយ៉ាងទន់ភ្លប់** — សួរអំពីអាកាសធាតុខាងក្នុងទីក្រុងដែលមិនមានទិន្នន័យគំរូ។ ឧបករណ៍បង្ហាញសារខុស និង AI ពន្យល់ថាវាមិនអាចជួយបានជាមិនបំផ្លាញកម្មវិធី។ ឧបករណ៍បរាជ័យដោយសុវត្ថិភាព។ រូបថតខាងក្រោមបង្ហាញភាពខុសគ្នារវាង វិធីទាំងពីរ — ជាមួយការដោះស្រាយកំហុសល្អ អេយ្យង់ចាប់ករណីកំហុស ហើយឆ្លើយតបជាសំណូមពរជួយ ខណៈពេលគ្មានវិធីនេះ កម្មវិធីទាំងមូលបញ្ឈប់ដំណើរការ៖ -Error Handling Flow +ដំណើរការដោះស្រាយកំហុស -*ពេលដែលឧបករណ៍បរាជ័យ មនុស្សប្រើចាប់ករណីកំហុស និងឆ្លើយតបដោយជួយវិញ ជំនួសការបំបួលកម្មវិធី។* +*ពេលឧបករណ៍បរាជ័យ អេយ្យង់ចាប់ករណីកំហុស ហើយឆ្លើយតបជាមួយការពន្យល់ជួយជំនួយ មិនបណ្តាលឲ្យកម្មវិធីបរាជ័យទាំងមូល។* -រឿងនេះកើតឡើងក្នុងវដ្តសន្ទនាតែមួយ។ មនុស្សប្រើគ្រប់គ្រងហៅឧបករណ៍ជាច្រើនដោយស្វ័យប្រវត្តិ។ +នេះកើតឡើងក្នុងជំហានសន្ទនាតែមួយ។ អេយ្យង់គ្រប់គ្រងការហៅឧបករណ៍ជាច្រើនដោយស្វ័យប្រវត្តិ។ -## បើកមេរោគ +## រត់កម្មវិធី -**ផ្ទៀងផ្ទាត់ការដាក់តម្រូវ៖** +**ផ្ទៀងផ្ទាត់ការដាក់ឲ្យដំណើរការ៖** -ធ្វើឲ្យប្រាកដថា មានឯកសារ `.env` ក្នុងថតក្រឡាដំបូង ជាមួយគណនី Azure (បានបង្កើតនៅក្នុងពេលមេរោគ ០១)។ រត់បញ្ជាលក់នេះពីថតមេរោគ (`04-tools/`)៖ +ធានាថា ឯកសារ `.env` មាននៅក្នុងថតដើមជាមួយអត្តសញ្ញាណ Azure (បង្កើតក្នុងម៉ូឌុល 01)។ រត់ការបញ្ជាខាងក្រោមពីថតម៉ូឌុល (`04-tools/`)៖ -**Bash:** +**Bash:** ```bash -cat ../.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # ត្រូវបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # គួរតែបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # គួរត្រូវបង្ហាញ AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` + +**ចាប់ផ្តើមកម្មវិធី៖** -**ចាប់ផ្ដើមកម្មវិធី៖** - -> **ចំណាំ៖** ប្រសិនបើអ្នកបានចាប់ផ្ដើមកម្មវិធីទាំងអស់ដោយ `./start-all.sh` ពីថតក្រឡាដំបូង (ដូចបានពិពណ៌នានៅមេរោគ ០១) មេរោគនេះមានដំណើរការលើកំពូល ៨០៨៤ រួចហើយ។ អ្នកអាចរំលងពាក្យបញ្ជារតាមខាងក្រោម និងចូលទៅ http://localhost:8084 តែម្តង។ +> **សម្គាល់៖** ប្រសិនបើអ្នកបានចាប់ផ្តើមកម្មវិធីទាំងអស់ដោយប្រើ `./start-all.sh` ពីថតឯកសារដើម (ដែលបានពិពណ៌នានៅម៉ូឌុល 01), ម៉ូឌុលនេះកំពុងដំណើរការនៅព្រនឹង 8084 រួចហើយ។ អ្នកអាចរំលងបញ្ជារចាប់ផ្តើមខាងក្រោម ហើយផ្ទេរទៅ http://localhost:8084 ដោយផ្ទាល់។ -**ជម្រើស ១៖ ប្រើ Spring Boot Dashboard (ណែនាំសម្រាប់អ្នកប្រើ VS Code)** +**ជម្រើស ១៖ ប្រើ Spring Boot Dashboard (ផ្ដល់អនុសាសន៍សម្រាប់អ្នកប្រើ VS Code)** -ថត dev មានបន្ថែម Spring Boot Dashboard ដែលផ្តល់ម៉ឺនុយឃើញបានច្បាស់ ដើម្បីគ្រប់គ្រងកម្មវិធី Spring Boot ទាំងអស់។ អ្នកអាចរកវាបាននៅក្នុងផ្ទាំងសកម្មភាពខាងឆ្វេងនៃ VS Code (ស្វែងរករូបតំណាង Spring Boot)។ +Dev container រួមបញ្ចូលផ្នែកបន្ថែម Spring Boot Dashboard ដែលផ្តល់ចំណុចប្រទាក់តាមរយៈរូបភាពសម្រាប់គ្រប់គ្រងកម្មវិធី Spring Boot ទាំងអស់។ អ្នកអាចរកវាក្នុង Activity Bar នៅខាងឆ្វេងនៃ VS Code (សូមស្វែងរករូបតំណាង Spring Boot)។ -ពី Spring Boot Dashboard អ្នកអាច៖ -- មើលកម្មវិធី Spring Boot ទាំងអស់ដែលអាចប្រើបានក្នុងលំហ -- ចាប់ផ្ដើម/បញ្ឈប់កម្មវិធីដោយចុចមួយគត់ -- មើលបន្ទាត់កំណត់ហេតុកម្មវិធីពេលវេលាពិត -- តាមដានស្ថានភាពកម្មវិធី -គ្រាន់តែចុចប៊ូតុងលេងនៅข้าง "tools" ដើម្បីចាប់ផ្តើមម៉ូឌុលនេះ ឬចាប់ផ្តើមម៉ូឌុលទាំងអស់ក្នុងពេលតែមួយ។ +ពីក្នុង Spring Boot Dashboard អ្នកអាច៖ +- មើលកម្មវិធី Spring Boot ទាំងអស់ក្នុងworkspace +- ចាប់ផ្តើម/បិទកម្មវិធីដោយចុចតែមួយ +- មើលកំណត់ហេតុកម្មវិធីជាមួយពេលវេលាពិត +- ត្រួតពិនិត្យស្ថានភាពកម្មវិធី -នេះជារូបរាងរបស់ Spring Boot Dashboard នៅក្នុង VS Code៖ +គ្រាន់តែចុចប៊ូតុងលេងនៅជាប់ "tools" ដើម្បីចាប់ផ្តើមម៉ូឌុលនេះ ឬចាប់ផ្តើមម៉ូឌុលទាំងអស់ជាមួយគ្នា។ -Spring Boot Dashboard +នេះជារូបរាង Spring Boot Dashboard នៅក្នុង VS Code៖ +ផ្ទាំងគ្រប់គ្រង Spring Boot -*Spring Boot Dashboard ក្នុង VS Code — ចាប់ផ្តើម បញ្ឈប់ និងតាមដានម៉ូឌុលទាំងអស់ពីកន្លែងតែមួយ* +*ផ្ទាំងគ្រប់គ្រង Spring Boot ក្នុង VS Code — ចាប់ផ្តើម បញ្ឈប់ និងត្រួតពិនិត្យមើលម៉ូឌុលទាំងអស់ពីកន្លែងតែមួយ* -**ជម្រើសទី 2៖ ប្រើស្គ្រីប shell** +**ជម្រើសទី 2: ការប្រើប្រាស់ស្គ្រីប shell** -ចាប់ផ្តើមកម្មវិធីបណ្ដាញទាំងអស់ (ម៉ូឌុល 01-04): +ចាប់ផ្តើមកម្មវិធីវេបទាំងអស់ (ម៉ូឌុល ០១-០៤): **Bash:** ```bash -cd .. # ពីថតឫស +cd .. # ពីថតមេ ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # ពីថតមេ +cd .. # ពីថតឫស .\start-all.ps1 ``` -ឬចាប់ផ្តើមតែម៉ូឌុលនេះប៉ុណ្ណោះ៖ +ឬចាប់ផ្តើមតែម៉ូឌុលនេះប៉ុណ្ណោះ: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -ស្គ្រីបទាំងពីរនេះត្រូវបញ្ចូលអថេរបរិស្ឋានពីឯកសារ `.env` នៅ root ដោយស្វ័យប្រវត្តិ ហើយនឹងកសាង JAR ប្រសិនបើវាមិនមានទេ។ +ស្គ្រីបទាំងពីរនេះបំពេញអូតូម៉ាទិចអថេរបរិស្ថានពីឯកសារ `.env` ជាមូឌុលដើម និងនឹងកសាង JAR ប្រសិនបើវា​មិនមាន។ -> **ចំណាំ៖** ប្រសិនបើអ្នកចូលចិត្តកសាងម៉ូឌុលទាំងអស់ដោយដៃ មុនចាប់ផ្តើម៖ +> **ចំណាំ៖** ប្រសិនបើអ្នកចង់កសាងម៉ូឌុលទាំងអស់ដោយដៃ មុនចាប់ផ្តើម: > > **Bash:** > ```bash @@ -272,13 +272,13 @@ cd 04-tools > mvn clean package -DskipTests > ``` -បើក http://localhost:8084 នៅក្នុងកម្មវិធីរុករករបស់អ្នក។ +បើក http://localhost:8084 ក្នុងគេហទំព័ររបស់អ្នក។ -**ដើម្បីបញ្ឈប់៖** +**ដើម្បីបញ្ឈប់:** **Bash:** ```bash -./stop.sh # ម៉ូឌុលនេះតែប៉ុណ្ណោះ +./stop.sh # មូឌុលនេះតែមួយ # ឬ cd .. && ./stop-all.sh # ម៉ូឌុលទាំងអស់ ``` @@ -292,96 +292,96 @@ cd ..; .\stop-all.ps1 # ម៉ូឌុលទាំងអស់ ## ការប្រើប្រាស់កម្មវិធី -កម្មវិធីផ្ដល់នូវចំណុចចូលបណ្ដាញដែលអ្នកអាចបំពេញប្រតិបត្តិការជាមួយភ្នាក់ងារប្រព័ន្ធឆ្លាត ដែលមានការចូលប្រើទៅឧបករណ៍អាកាសធាតុនិងបំលែងសីតុណ្ហភាព។ នេះជារូបរាងចំណុចចូល — មានឧទាហរណ៍ចាប់ផ្តើមយ៉ាងឆាប់រហ័ស និងផ្ទាំងជជែកសម្រាប់ផ្ញើសំណើ: +កម្មវិធីផ្តល់ជូនផ្ទៃតាប៉ាល់វេប ដែលអ្នកអាចអន្តរកម្មជាមួយសេវាកម្ម AI ដែលមានការចូលដំណើរការឧបករណ៍អាកាសធាតុ និងបម្លែងសីតុណ្ហភាព។ នេះជាទម្រង់ផ្ទៃតាប៉ាល់ — រួមមានគំរូចាប់ផ្តើមលឿន និងផ្ទាំងនៃជជែកសម្រាប់ផ្ញើសំណើ: -AI Agent Tools Interface +ផ្ទៃតាប៉ាល់ឧបករណ៍ភ្នាក់ងារ AI -*ចំណុចចូលឧបករណ៍ភ្នាក់ងារប្រព័ន្ធឆ្លាត - ឧទាហរណ៍ឆាប់ និងចំណុចចូលជជែកសម្រាប់ធ្វើប្រតិបត្តិការជាមួយឧបករណ៍* +*ផ្ទៃតាប៉ាល់ឧបករណ៍ភ្នាក់ងារ AI - គំរូលឿន និងផ្ទាំងជជែកសម្រាប់អន្តរកម្មជាមួយឧបករណ៍* -### សាកល្បងការប្រើឧបករណ៍សាមញ្ញ +### សាកល្បងការប្រើប្រាស់ឧបករណ៍ងាយៗ -ចាប់ផ្តើមជាមួយសំណើធម្មតា៖ "បំលែង 100 ដឺក្រេ Fahrenheit ទៅ Celsius"។ ភ្នាក់ងារយល់ថាវាត្រូវការ ឧបករណ៍បំលែងសីតុណ្ហភាព មកហៅវាជាមួយប៉ារ៉ាម៉ែត្រយ៉ាងត្រឹមត្រូវ ហើយត្រឡប់លទ្ធផលវិញ។ សម្រួល ស្រាប់តែមានអារម្មណ៍ធម្មតា - អ្នកមិនចាក់បញ្ជាក់ថាត្រូវប្រើឧបករណ៍ណាឬរបៀបទំនាក់ទំនងយ៉ាងដូចម្តេចទេ។ +ចាប់ផ្តើមជាមួយសំណើសាមញ្ញ៖ "បម្លែង ១០០ ដឺក្រេ Fahrenheit ទៅ Celsius"។ ភ្នាក់ងារ ស្គាល់ថាវាដើម្បីត្រូវការឧបករណ៍បម្លែងសីតុណ្ហភាព ហៅវាដោយប៉ាម៉ែត្រសមត្ថភាព ហើយតបអតិថិជនវិញជាលទ្ធផល។ សង្កេតមើលភាពធម្មជាតិនេះ — អ្នកមិនបានបញ្ជាក់ថាឧបករណ៍ណា ត្រូវប្រើ ឬរបៀបហៅវា។ -### សាកល្បងការភ្ជាប់ឧបករណ៍ +### សាកល្បងការចងខ្សែឧបករណ៍ -ឥឡូវនេះសាកល្បងអ្វីមួយស្មុគស្មាញ៖ "អាកាសធាតុ​នៅ Seattle ជាអ្វី ហើយបំលែងវាប្រែទៅ Fahrenheit?" មើលភ្នាក់ងារដំណើរការនៅជំហានៗ។ វាទទួលអាកាសធាតុ (ដែលត្រឡប់ Celsius) ជាលើកដំបូង ហើយយល់ថាត្រូវបំលែងទៅ Fahrenheit ហៅឧបករណ៍បំលែង ហើយបញ្ចូលលទ្ធផលទាំងពីរចូលជាសម្លៀកបំពាក់ឆ្លើយតបមួយ។ +ឥលូវសាកល្បងអ្វីដែលស្មុគស្មាញជាង៖ "អាកាសធាតុ​នៅ Seattle ជាយ៉ាងដូចម្តេច ហើយបម្លែងវាទៅ Fahrenheit?" មើលភ្នាក់ងារធ្វើការជាច្រកៗ។ វាទទួលអាកាសធាតុនេះជាចុងក្រោយ (ដែលត្រឡប់ Celsius) ហើយស្គាល់ថាវាត្រូវបម្លែងទៅ Fahrenheit ហៅឧបករណ៍បម្លែង ហើយបញ្ចូលលទ្ធផលទាំងពីរចូលជាមួយបង្ហាញចម្លើយមួយ។ -### មើលដំណើរការជជែក +### មើលចម្ងល់ជជែក -ផ្ទាំងជជែករក្សាប្រវត្តិការជជែក ត្រូវបានអនុញ្ញាតឱ្យអ្នកមានអន្តរកម្មពហុដងជាមួយភ្នាក់ងារ។ អ្នកអាចមើលសំណួរនិងចម្លើយជាច្រើនបាន គ្រប់គ្រាន់សម្រាប់តាមដានសន្ទនា និងយល់ពីរបៀបដែលភ្នាក់ងារជំរុញបរិបទតាមការប្ដូរប្រក់ៗ។ +ផ្ទាំងជជែករក្សាប្រវត្តិជជែក អនុញ្ញាតឱ្យអ្នកមានការប្រាស្រ័យពហុជុំ។ អ្នកអាចមើលសំណួរនិងចម្លើយមុនៗទាំងអស់ ប្រើប្រាស់បានឆាប់យល់ផងដែរ អំពីរបៀបភ្នាក់ងារបង្កើតបរិបទក្នុងការជជែកជាបន្តបន្ទាប់។ -Conversation with Multiple Tool Calls +ជជែកជាមួយការហៅឧបករណ៍ច្រើន -*ការជជែកពហុដងបង្ហាញការបំលែងសាមញ្ញ ការស្វែងរកអាកាសធាតុ និងការភ្ជាប់ឧបករណ៍* +*ការជជែកពហុជុំបង្ហាញការបម្លែងសាមញ្ញ អាកាសធាតុរុករក និងចងខ្សែឧបករណ៍* -### សាកល្បងបញ្ចូលសំណើផ្សេងៗ +### សាកល្បងសំណើផ្សេងៗ -សាកល្បងបញ្ចូលផ្សំផ្សេងៗ៖ -- ស្វែងរកអាកាសធាតុ៖ "អាកាសធាតុ​នៅ Tokyo ជាអ្វី?" -- បំលែងសីតុណ្ហភាព៖ "តើ 25°C ជា Kelvin ឬ?" -- សំណួរបញ្ចូល៖ "ពិនិត្យអាកាសធាតុ​នៅ Paris ហើយប្រាប់ខ្ញុំថាវាច្រើនជាង 20°C រឺទេ" +សាកល្បងតម្រង់ផ្សេងៗ៖ +- រុករកអាកាសធាតុ: "អាកាសធាតុ​ក្នុងទីក្រុង Tokyo ជាយ៉ាងដូចម្តេច?" +- បម្លែងសីតុណ្ហភាព: "តើ ២៥°C ជាតម្លៃប៉ុន្មាន Kelvin?" +- សំណើរភ្ជាប់គ្នា: "ពិនិត្យអាកាសធាតុ​ក្នុង Paris ហើយប្រាប់ខ្ញុំ ប្រសិនបើវាលើស ២០°C" -មើលថាភ្នាក់ងារពន្យល់ភាសាប្រកបដោយធម្មជាតិ ហើយផ្គូផ្គងវាជាមួយការហៅឧបករណ៍ត្រឹមត្រូវ។ +សង្កេតមើលរបៀបភ្នាក់ងារបកប្រែភាសាធម្មជាតិ និងភ្ជាប់ទៅការហៅឧបករណ៍ដូចត្រូវការ។ -## ទ្រឹស្តីសំខាន់ៗ +## ការយល់ដឹងសំខាន់ៗ -### លំនាំ ReAct (ការត្រួតពិនិត្យ និងសកម្មភាព) +### រចនាប័ទ្ម ReAct (ហេតុផល និងសកម្មភាព) -ភ្នាក់ងារប្រែប្រួលគំនិត (សម្រេចចិត្តថាត្រូវធ្វើអ្វី) និងសកម្មភាព (ប្រើឧបករណ៍)។ លំនាំនេះអនុញ្ញាតឱ្យដោះស្រាយបញ្ហាដោយផ្ទាល់ខ្លួន មិនមែនតែឆ្លើយតបទៅតាមសេចក្តីណែនាំទេ។ +ភ្នាក់ងារប្រែប្រួលរវាងការគិត (សម្រេចថាតើត្រូវធ្វើអ្វី) និងការប្រតិបត្តិ (ប្រើឧបករណ៍)។ រចនាប័ទ្មនេះអនុញ្ញាតឲ្យដោះស្រាយបញ្ហាដោយឯករាជ្យ មិនមែនគ្រាន់តែបញ្ចេញចម្លើយតាមបទបញ្ជា។ ### ការពិពណ៌នាឧបករណ៍មានសារៈសំខាន់ -គុណភាពនៃការពិពណ៌នាឧបករណ៍របស់អ្នកប៉ះពាល់យ៉ាងខ្លាំងទៅលើរបៀបដែលភ្នាក់ងារប្រើប្រាស់វា។ ការពិពណ៌នាប្រកបដោយច្បាស់លាស់ និងជាក់លាក់ជួយឲ្យម៉ូដែលយល់ពេលណា ហើយធ្វើដូចម្តេចដើម្បីហៅឧបករណ៍នីមួយៗ។ +គុណភាពនៃការពិពណ៌នាឧបករណ៍របស់អ្នកមានឥទ្ធិពលដល់របៀបដែលភ្នាក់ងារប្រើប្រាស់វា។ ការពិពណ៌នាដែលច្បាស់លាស់ និងជាក់លាក់ជួយឲ្យគំរូយល់ថាតើពេលណានិងរបៀបណា ត្រូវហៅឧបករណ៍នីមួយៗ។ -### ការគ្រប់គ្រងសម័យប្រតិបត្តិការ +### ការគ្រប់គ្រងសម័យសន្ទនា -ម៉ាក `@MemoryId` អនុញ្ញាតការគ្រប់គ្រងចងចាំក្នុងសម័យប្រតិបត្តិការដោយស្វ័យប្រវត្តិ។ ពីរយៈសម័យទាំងអស់មាន `ChatMemory` ផ្ទាល់ខ្លួនដែលគ្រប់គ្រងដោយ bean `ChatMemoryProvider` ដូច្នេះអ្នកប្រើប្រាស់ជាច្រើនអាចមានអន្តរកម្មជាមួយភ្នាក់ងារហើយការសន្ទនារបស់ពួកគេមិនប៉ះពាល់គ្នាទេ។ រូបភាពខាងក្រោមបង្ហាញពីរបៀបដែលអ្នកប្រើប្រាស់ជាច្រើនត្រូវបានផ្ញើទៅឃ្លាំងចងចាំបំបែកដោយផ្អែកលើ ID សម័យរបស់ពួកគេ៖ +ការកំណត់ `@MemoryId` អនុញ្ញាតការគ្រប់គ្រងអនុស្សាវរីយ៍តាមសម័យសន្ទនា តាមរយៈ `ChatMemory` ដែលគ្រប់គ្រងដោយ `ChatMemoryProvider` ធ្វើឲ្យអ្នកប្រើច្រើននាក់អាចអន្តរកម្មជាមួយភ្នាក់ងារដូចគ្នាបានដោយមិនចម្រុះជាមួយ។ សំណូមពរបង្ហាញរបៀបដែលអ្នកប្រើប្រាស់ជាច្រើនត្រូវបានបំបែកទៅកាន់ទូរសំឡេងផ្ទាល់ខ្លួនដោយផ្អែកលើសម្គាល់សម័យរបស់ពួកគេ៖ -Session Management with @MemoryId +ការគ្រប់គ្រងសម័យជាមួយ @MemoryId -*រាល់ ID សម័យភ្ជាប់ទៅនឹងប្រវត្តិសន្ទនារដាច់ដោយឡែក — អ្នកប្រើប្រាស់មិនដែលមើលឃើញសារ​របស់គ្នាប៉ុន្មាននោះទេ។* +*សម្គាល់សម័យនីមួយៗផ្ទៀងផ្ទាត់ទៅប្រវត្តិជជែកបំបែក - អ្នកប្រើមិនដែលមើលឃើញសាររបស់គ្នាទេ។* -### ការគ្រប់គ្រងកំហុស +### ការដោះស្រាយកំហុស -ឧបករណ៍អាចបរាជ័យ — API អាចពេលវេលាបញ្ចប់មុនពេលហៅរូច ប៉ារ៉ាម៉ែត្រអាចមិនត្រឹមត្រូវ សេវាកម្មខាងក្រៅអាចបិទ។ ភ្នាក់ងារក្នុងផលិតកម្មត្រូវការជំនួយគ្រប់គ្រងកំហុស ដើម្បីម៉ូដែលអាចពន្យល់បញ្ហា ឬសាកល្បងជម្រើសផ្សេងទៀត ជំនួសការបរាជ័យកម្មវិធីទាំងមូល។ ពេលឧបករណ៍ដាក់បញ្ហា LangChain4j នឹងចាប់កំហុសនោះ ហើយផ្ដល់សារកំហុសទៅម៉ូដែល ដែលអាចពន្យល់បញ្ហាក្នុងភាសាធម្មជាតិនោះបាន។ +ឧបករណ៍អាចបរាជ័យ — អាយភីអាយវេលាមិនគ្រប់គ្រាន់ ប៉ារ៉ាម៉ែត្រអាចមិនត្រឹមត្រូវ សេវាកម្មខាងក្រៅអាចទៀតពេល។ ភ្នាក់ងារផលិតកម្មត្រូវការការដោះស្រាយកំហុស ដើម្បីឲ្យគំរូអាចពន្យល់បញ្ហា ឬសាកល្បងជម្រើសផ្សេងៗដោយមិនបង្កើតកំហុសធំទូលាយវិញ។ ឧបករណ៍បោះសំណើកំហុស LangChain4j ចាប់យក ហើយផ្ញើសារបញ្ហាចូលទៅគំរូ ដែលបន្ទាប់មកអាចពន្យល់បញ្ហានោះជាភាសាធម្មជាតិ។ -## ឧបករណ៍ដែលមានស្រាប់ +## ឧបករណ៍ដែលមាន -រូបភាពខាងក្រោមបង្ហាញអេកូស៊ីស្ទីមធំទូលាយនៃឧបករណ៍ដែលអ្នកអាចបង្កើត។ ម៉ូឌុលនេះបង្ហាញឧបករណ៍អាកាសធាតុ និងបំលែងសីតុណ្ហភាព ប៉ុន្តាលំនាំ `@Tool` ដូចគ្នាអាចប្រើបានសម្រាប់មធ្យោបាយ Java ណាមួយទៀត — ពីសំណួរទិន្នន័យរហូតដល់ដំណើរការបង់ប្រាក់។ +គំនូរសូមមើលខាងក្រោមបង្ហាញពីប្រព័ន្ធឧបករណ៍ដែលអ្នកអាចកសាង។ ម៉ូឌុលនេះបង្ហាញឧបករណ៍អាកាសធាតុ និងសីតុណ្ហភាព ប៉ុន្តែរចនាប័ទ្ម `@Tool` ដូចគ្នាអាចប្រើសម្រាប់មធ្យោបាយ Java ទាំងអស់ — ពីការស្វែងយល់ទិន្នន័យទៅដល់ការចំណាយប្រាក់។ -Tool Ecosystem +ប្រព័ន្ធឧបករណ៍ -*មធ្យោបាយ Java ណាមួយដែលមានម៉ាក @Tool នឹងអាចប្រើជាមួយ AI បាន — លំនាំនេះពង្រីកទៅដល់មូលដ្ឋានទិន្នន័យ API អ៊ីមែល ប្រតិបត្តិការឯកសារ និងផ្សេងៗទៀត។* +*មធ្យោបាយ Java ណាមួយដែលមាន `@Tool` នឹងអាចប្រើបានដោយ AI — រចនាប័ទ្មពង្រីកទៅកាន់ទិន្នន័យ, API, អ៊ីមែល, ប្រតិបត្តិការឯកសារ និងវែងទៀត។* -## ពេលណានឹងប្រើភ្នាក់ងារដែលផ្អែកលើឧបករណ៍ +## ពេលណា គួរប្រើភ្នាក់ងារតាមឧបករណ៍ -មិនមែនសំណើរ គ្រប់ប្រភេទត្រូវការឧបករណ៍ទេ។ ការសម្រេចចិត្តមានលទ្ធភាពថា AI ត្រូវអន្តរកម្មជាមួយប្រព័ន្ធខាងក្រៅ ឬអាចឆ្លើយតបពីចំណេះដឹងផ្ទាល់ខ្លួន។ មតិណែនាំខាងក្រោមជាសង្ខេបពេលណា ឧបករណ៍កំពុងបន្ថែមតម្លៃ និងពេលណាដែលវាមិនចាំបាច់៖ +មិនមែនសំណើរ​ទាំងអស់ត្រូវការឧបករណ៍ទេ។ ការសម្រេចចិត្តនៅផ្តល់តម្លៃថា AI ត្រូវអន្តរកម្មជាមួយប្រព័ន្ធខាងក្រៅរឺអាចឆ្លើយពីចំណេះដឹងផ្ទាល់ខ្លួន។ មគ្គុទេសក៍ខាងក្រោមសង្ខេបពេលណាឧបករណ៍មានតម្លៃ និងពេលណាអត់ត្រូវការ៖ -When to Use Tools +ពេលណា គួរប្រើឧបករណ៍ -*មគ្គុទេសក៍សម្រេចចិត្តរហ័ស — ឧបករណ៍សម្រាប់ទិន្នន័យពេលវេលាពិត ការគណនា និងសកម្មភាព; ចំណេះដឹងទូទៅ និងការងារច្នៃប្រឌិតមិនចាំបាច់។* +*មគ្គុទេសក៍សម្រេចឆាប់ - ឧបករណ៍សម្រាប់ទិន្នន័យបច្ចុប្បន្ន, ការគណនា និងសកម្មភាព; ចំណេះដឹងទូទៅ និងភារកិច្ចបង្កើតមិនត្រូវការវា។* -## ឧបករណ៍ និង RAG +## ឧបករណ៍ប្រៀបធៀប RAG -ម៉ូឌុល 03 និង 04 សងប៉ុន្មានអ្វីដែល AI អាចធ្វើបាន ប៉ុន្តែជារបៀបខុសគ្នាដាច់ដោយឡែក។ RAG ផ្ដល់សមត្ថភាពដើម្បីចូលដំណឹងក្នុងចំណេះដឹងដោយយកឯកសារជាវិស័យ។ ឧបករណ៍ផ្ដល់សមត្ថភាពអនុវត្តសកម្មភាពដោយហៅមុខងារ។ រូបភាពខាងក្រោមប្រៀបធៀបរបៀបទាំងពីរ នៅផ្នែកមុខទីពីរដូចគ្នា — ពីរបៀបដំណើរការប្រព័ន្ធ រហូតដល់ការផ្លាស់ប្តូរជាផ្នែកប្រយោជន៍៖ +ម៉ូឌុល ០៣ និង ០៤ ពង្រីកអ្វីដែល AI អាចធ្វើបាន ប៉ុន្តែមានរបៀបខុសគ្នាចម្បង។ RAG ផ្ដល់ការចូលដំណើរការចំណេះដឹងដោយស្វែងយល់ឯកសារ។ ឧបករណ៍ផ្ដល់សមត្ថភាពធ្វើសកម្មភាពដោយហៅមុខងារ។ រូបភាពខាងក្រោមប្រៀបធៀបពីររបៀបនេះជាបន្ទាត់ជាមួយ — ពីរបៀបដំណើរការដល់ការជ្រាបចំណាយរវាងពួកវា៖ -Tools vs RAG Comparison +ប្រៀបធៀបឧបករណ៍និង RAG -*RAG យកព័ត៌មានពីឯកសារមានរូបភាពស្តាទីកាល — ឧបករណ៍អនុវត្តសកម្មភាព និងយកទិន្នន័យពេលវេលាពិត។ ប្រព័ន្ធផលិតកម្មច្រើនភ្ជាប់រួមទាំងពីរ។* +*RAG ស្វែងយល់ពីឯកសារស្ថិតស្ថេរ — ឧបករណ៍អនុវត្តសកម្មភាព និងយកទិន្នន័យបច្ចុប្បន្នសកម្មភាព ដំណើរការកម្មវិធីច្រើនប្រព័ន្ធផ្សំគ្នាទាំងពីរ។* -ប្រាកដឡើង ប្រព័ន្ធផលិតកម្មជាច្រើនភ្ជាប់រួមពីរបៀបនេះ៖ RAG សម្រាប់ធានាថាចម្លើយមានមូលដ្ឋានពីឯកសាររបស់អ្នក និងឧបករណ៍សម្រាប់យកទិន្នន័យពេលវេលាពិត ឬអនុវត្តអនុសាសន៍។ +នៅក្នុងអនុវត្តន៍ កម្មវិធីផលិតភាពច្រើនប្រើរួមគ្នា៖ RAG សម្រាប់ផ្តល់មូលដ្ឋានចម្លើយក្នុងឯកសារ និងឧបករណ៍សម្រាប់យកទិន្នន័យបច្ចុប្បន្ន ឬអនុវត្តសកម្មភាព។ -## ជំហានបន្ទាប់ +##ជំហានបន្ទាប់ **ម៉ូឌុលបន្ទាប់៖** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**ការរុករក៖** [← មុន៖ ម៉ូឌុល 03 - RAG](../03-rag/README.md) | [ត្រឡប់ទៅបង្អួចផ្លូវចម្បង](../README.md) | [បន្ទាប់៖ ម៉ូឌុល 05 - MCP →](../05-mcp/README.md) +**ការរុករក៖** [← មុន៖ ម៉ូឌុល ០៣ - RAG](../03-rag/README.md) | [ត្រឡប់ទៅមុខមារ](../README.md) | [បន្ទាប់៖ ម៉ូឌុល ០៥ - MCP →](../05-mcp/README.md) --- -**ការបដិសេធ**: -ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាកម្មបកប្រែ AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ខណៈដែលយើងខិតខំប្រឹងប្រែងដើម្បីភាពត្រឹមត្រូវ សូមប្រយ័ត្នថាការបកប្រែដោយស្វ័យប្រវត្តិនេះអាចមានកំហុស ឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមនៅក្នុងភាសាម្ចាស់ដើមគួរត្រូវបានគិតថាជាធនធានដ៏សំខាន់។ សម្រាប់ព័ត៌មានសំខាន់ៗ ការបកប្រែដោយមនុស្សជំនាញជាមូលដ្ឋានគឺល្អបំផុត។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកប្រែខុសដែលកើតឡើងពីការប្រើប្រាស់ការបកប្រែនេះឡើយ។ +**ការបដិសេធ**: +ឯកសារនេះត្រូវបានបម្លែងភាសា ដោយប្រើសេវាបម្លែងភាសា AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទោះយើងខ្ញុំមានក្តីប្រាថ្នាឱ្យបានច្បាស់លាស់ តែសូមយល់ដឹងថាការបម្លែងដោយស្វ័យប្រវត្តិក៏អាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមជាភាសាទីតាំងគួរត្រូវបានគេប្រើជាប្រភពច្បាស់លាស់។ សម្រាប់ព័ត៌មានសំខាន់ៗ សូមណែនាំឱ្យប្រើប្រាស់ការប្រែដោយមនុស្សជំនាញ។ យើងខ្ញុំមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកស្រាយខុសបន្ទាប់ពីការប្រើប្រាស់ការបម្លែងនេះនោះទេ។ \ No newline at end of file diff --git a/translations/km/README.md b/translations/km/README.md index 133ed9f98..094a9f7d2 100644 --- a/translations/km/README.md +++ b/translations/km/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j សម្រាប់អ្នកចាប់ផ្ដើម +# LangChain4j សម្រាប់អ្នកដំបូងរើប -វគ្គសិក្សាមួយសម្រាប់បង្កើតកម្មវិធី AI ជាមួយ LangChain4j និង Azure OpenAI GPT-5.2 ចាប់ពីការជជែកមូលដ្ឋានដល់ភ្នាក់ងារ AI។ +វគ្គសិក្សាសម្រាប់ការសង់កម្មវិធី AI ជាមួយ LangChain4j និង Azure OpenAI GPT-5.2 ពីការជជែកមូលដ្ឋានមកដល់ភ្នាក់ងារ AI។ -### 🌐 គាំទ្រភាសាម៉ុលធី +### 🌐 គាំទ្រភាសាច្រើន -#### គាំទ្រដោយសកម្មភាព GitHub (ស្វ័យប្រវត្តិ និងតែងតែទាន់សម័យ) +#### គាំទ្រដោយ GitHub Action (ស្វ័យប្រវត្តិ និងតែងតែទាន់សម័យ) -[អារ៉ាប់](../ar/README.md) | [បង់ក្លា](../bn/README.md) | [ប៊ុលហ្គារី](../bg/README.md) | [មីយ៉ាន់ម៉ា (ភាសាប៊ឺម៉ាស)](../my/README.md) | [ចិន (សាមញ្ញ)](../zh-CN/README.md) | [ចិន (ប្រពៃណី, ហុងកុង)](../zh-HK/README.md) | [ចិន (ប្រពៃណី, ម៉ាកាវ)](../zh-MO/README.md) | [ចិន (ប្រពៃណី, តៃវ៉ាន់)](../zh-TW/README.md) | [ក្រូអាស៊ី](../hr/README.md) | [ខេហ្ស](../cs/README.md) | [ដាណាខ្ក](../da/README.md) | [ដាច](../nl/README.md) | [អេស្តូនីយ៉ា](../et/README.md) | [ហ្វិនឡង់](../fi/README.md) | [បារាំង](../fr/README.md) | [អាល្លឺម៉ង់](../de/README.md) | [ក្រិច](../el/README.md) | [ហេប៊ရွ](../he/README.md) | [ហិណ្ឌី](../hi/README.md) | [ហុងគ្រី](../hu/README.md) | [ឥណ្ឌូណេស៊ី](../id/README.md) | [អ៊ីតាលី](../it/README.md) | [ជប៉ុន](../ja/README.md) | [កណណាដា](../kn/README.md) | [ខ្មែរ](./README.md) | [កូរ៉េ](../ko/README.md) | [លីទុយអានី](../lt/README.md) | [ម៉ាឡៃ](../ms/README.md) | [ម៉ាឡាឡាយ៉ាលាំ](../ml/README.md) | [ម៉ារាថី](../mr/README.md) | [នេប៉ាល់](../ne/README.md) | [ភាសាគូគូហ្វីននី](../pcm/README.md) | [ន័រវែ](../no/README.md) | [ភាសាផេរូស (ហ្វា្ទស៊ី)](../fa/README.md) | [ប៉ូឡិន](../pl/README.md) | [ភាសាប៉ូរទុយហ្កាល់ (ប្រេស៊ីល)](../pt-BR/README.md) | [ភាសាប៉ូរទុយហ្កាល់ (ប៉ូរទុយហ្កាល់)](../pt-PT/README.md) | [ភាសាផុនជាប៊ី (គួរមូឃី)](../pa/README.md) | [រូម៉ានី](../ro/README.md) | [រុស្ស៊ី](../ru/README.md) | [សឺប៊ី (អក្សរអង់គ្លេស)](../sr/README.md) | [ស្លូវាគ](../sk/README.md) | [ស្លូវេនី](../sl/README.md) | [អេស្ប៉ាញ](../es/README.md) | [ស្វាហ៊ីលី](../sw/README.md) | [ស៊ុយអែ](../sv/README.md) | [តាឡាហ្គោ (ហ្វីលីពីន)](../tl/README.md) | [តាមីល](../ta/README.md) | [តេលូទូ](../te/README.md) | [ថៃ](../th/README.md) | [ទួរគី](../tr/README.md) | [អ៊ុយក្រែន](../uk/README.md) | [អ៊ឺឌូ](../ur/README.md) | [វៀតណាម](../vi/README.md) +[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](./README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **ចង់ចម្លងនៅក្នុងកុំព្យូទ័រអ្នកទេ?** +> **ចង់ធ្វើការ Clone នៅក្នុងម៉ាស៊ីនខ្លួនឯង?** > -> ឃ្លាំងនេះមានការប្រែភាសា ៥០+ ដែលបង្កើនទំហំទាញយកយ៉ាងច្រើន។ ដូច្នេះដើម្បីចម្លងដោយគ្មានភាសាប្រែ ប្រើ sparse checkout៖ +> ឃ្លាំងនេះរួមបញ្ចូលការប្រែសម្រួលភាសាជាង ៥០ ដែលបង្កើនទំហំការទាញយកយ៉ាងច្រើន។ ដើម្បី Clone ដោយគ្មានការប្រែសម្រួល ប្រើ sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,120 +29,119 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> វានឹងផ្គត់ផ្គង់អ្វីដែលអ្នកត្រូវការដើម្បីបញ្ចប់វគ្គសិក្សានេះដោយទាញយកលឿនជាងមុន។ +> វានឹងផ្គត់ផ្គង់អ្វីដែលអ្នកត្រូវការ ដើម្បីបញ្ចប់វគ្គសិក្សានេះជាមួយនឹងការទាញយកលឿនជាងមុន។ ## តារាងមាតិកា -1. [ចាប់ផ្ដើមយ៉ាងរហ័ស](00-quick-start/README.md) - ចាប់ផ្ដើមជាមួយ LangChain4j -2. [បង្ហាញសង្ខេប](01-introduction/README.md) - រៀនអំពីមូលដ្ឋាន LangChain4j -3. [បច្ចេកវិទ្យាគំនិតបញ្ចូល](02-prompt-engineering/README.md) - ធ្វើឲ្យចេះរចនាគំនិតឲ្យបានប្រសើរ -4. [RAG (ការបង្កើតដែលអភិវឌ្ឍដោយការយកតម្លៃបន្ថែម)](03-rag/README.md) - បង្កើតប្រព័ន្ធចំណេះដឹងវចនាធិប្បាយ -5. [ឧបករណ៍](04-tools/README.md) - បញ្ចូលឧបករណ៍ខាងក្រៅ និងជំនួយងាយៗ -6. [MCP (ប្រព័ន្ធបរិបទគំរូ)](05-mcp/README.md) - ធ្វើការជាមួយប្រព័ន្ធបរិបទគំរូ (MCP) និងមជ្ឈមណ្ឌលភ្នាក់ងារ +1. [ការប្រុងប្រាជ្ញា](01-introduction/README.md) - រៀនពីមូលដ្ឋាននៃ LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - សម្របសម្រួលការរចនាការបញ្ជា +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - សង់ប្រព័ន្ធនៃចំណេះដឹងដ៏ឆ្លាតវៃ +4. [ឧបករណ៍](04-tools/README.md) - ប្រព័ន្ធបញ្ចូលឧបករណ៍ខាងក្រៅ និងអ្នកជួយសាមញ្ញ +5. [MCP (Model Context Protocol)](05-mcp/README.md) - ធ្វើការជាមួយ Model Context Protocol (MCP) និងម៉ូឌុល Agentic -### សិក្សាតាមវីដេអូ +### វីដេអូចេញដំណើរ -មូឌុលរាល់មួយមានវីដេអូផ្ញើផ្សាយផ្ទាល់ដែលយើងដើរឆ្ពោះតាមគំនិត និងកូដជំហានដោយជំហាន។ +មហាសេដ្ឋីនីមួយៗមានវគ្គសិក្សាផ្ទាល់ខ្លួនដែលយើងបើកចំហរជំហានទៅជំហានពន្យល់ពីគំនិត និងកូដ។ -| មូឌុល | វីដេអូ | -|--------|---------| -| 01 - បង្ហាញសង្ខេប | [ចាប់ផ្ដើមជាមួយ LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - បច្ចេកវិទ្យាគំនិតបញ្ចូល | [បច្ចេកវិទ្យាគំនិតបញ្ចូលជាមួយ LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| មហាសេដ្ឋី | វីដេអូ | +|--------|-------| +| 01 - ការប្រុងប្រាជ្ញា | [ការចាប់ផ្តើមជាមួយ LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Prompt Engineering | [រចនាបណ្ដាំដំណើរការជាមួយ LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG ជាមួយ LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - ឧបករណ៍ និង 05 - MCP | [ភ្នាក់ងារ AI ជាមួយឧបករណ៍ និង MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## ផ្លូវការសិក្សា +## ផ្លូវរៀន -**ថ្មីចំពោះ LangChain4j ទេ?** សូមពិនិត្យមើល [ពាក្យស្នូល](docs/GLOSSARY.md) សម្រាប់និយមន័យនៃពាក្យ និងគំនិតសំខាន់ៗ។ +**ថ្មីចំពោះ LangChain4j?** សូមពិនិត្យមើល [ពាក្យកំណត់](docs/GLOSSARY.md) សម្រាប់និយមន័យនៃពាក្យសំខាន់ៗ និងយោបល់។ -> **ចាប់ផ្ដើមយ៉ាងរហ័ស** +> **ចាប់ផ្តើមយ៉ាងរហ័ស** -1. ខ្ចីឃ្លាំងនេះទៅគណនី GitHub របស់អ្នក -2. ចុច **Code** → តារាង **Codespaces** → **...** → **New with options...** -3. ប្រើលំនាំដើម – វានឹងជ្រើសគ្រប់គ្រងកុងតឺន័រអភិវឌ្ឍន៍ដែលបានបង្កើតសម្រាប់វគ្គសិក្សានេះ +1. Fork ឃ្លាំងនេះទៅកាន់គណនី GitHub របស់អ្នក +2. ចុច **Code** → **Codespaces** ប៊ិច → **...** → **New with options...** +3. ប្រើលំនាំដើម – វានឹងជ្រើសបំពង់អភិវឌ្ឍន៍ដែលបានបង្កើតសម្រាប់វគ្គនេះ 4. ចុច **Create codespace** -5. ចាំរយៈពេល ៥-១០ នាទីរហូតដល់បរិវេណត្រៀមរួច -6. ឆ្លងតទៅកាន់ [ចាប់ផ្ដើមយ៉ាងរហ័ស](./00-quick-start/README.md) ដើម្បីចាប់ផ្ដើម! +5. រង់ចាំ 5-10 នាទីសម្រាប់បរិយាកាសរួចរាល់ +6. រំកិលទៅ [ការប្រុងប្រាជ្ញា](./01-introduction/README.md) ដើម្បីចាប់ផ្តើម! -បន្ទាប់ពីបញ្ចប់មូឌុលទាំងអស់ សូមស្វែងយល់ពី[មគ្គុទេសក៍សាកល្បង](docs/TESTING.md) ដើម្បីមើលមាតិកាចំណេះដឹង LangChain4j ក្នុងសកម្មភាព។ +បន្ទាប់ពីបញ្ចប់មហាសេដ្ឋី សូមស្វែងយល់ពី [មគ្គុទេសក៍សាកល្បង](docs/TESTING.md) ដើម្បីមើលគំនិតលើការតេស្ត LangChain4j ក្នុងសកម្មភាព។ -> **ចំណាំ:** វគ្គបណ្តុះបណ្តាលនេះប្រើទាំង GitHub Models និង Azure OpenAI។ មូឌុល [ចាប់ផ្ដើមយ៉ាងរហ័ស](00-quick-start/README.md) ប្រើ GitHub Models (មិនចាំបាច់មានជាវ Azure) ខណៈមូឌុលទី ១ ដល់ ៥ ប្រើ Azure OpenAI។ ចាប់ផ្ដើមជាមួយគណនី Azure [ឥតគិតថ្លៃ](https://aka.ms/azure-free-account) ប្រសិនបើអ្នកមិនមានទេ។ +> **ចំណាំ៖** ការបណ្តុះបណ្តាលនេះប្រើ Azure OpenAI។ ចាប់ផ្តើមជាមួយ [គណនី Azure មិនគិតថ្លៃ](https://aka.ms/azure-free-account) ប្រសិនបើអ្នកមិនមានទេ។ ## រៀនជាមួយ GitHub Copilot -ដើម្បីចាប់ផ្ដើមកូដលឿន សូមបើកគម្រោងនេះនៅក្នុង GitHub Codespace ឬ IDE ក្នុងកុំព្យូទ័រមូលដ្ឋានរបស់អ្នកជាមួយ devcontainer ដែលបានផ្តល់ជូន។ devcontainer នៅក្នុងវគ្គសិក្សានេះបានកំណត់រួចជាមួយ GitHub Copilot សម្រាប់កម្មវិធីឆ្លើយតប AI រួមគ្នា។ +ដើម្បីចាប់ផ្តើមគូរយូធូបឆាប់រហ័ស បើកគម្រោងនេះនៅក្នុង GitHub Codespace ឬ IDE ផ្ទាល់ខ្លួនជាមួយ devcontainer ដែលបានផ្តល់ជូន។ devcontainer ដែលប្រើនៅវគ្គនេះមានការតំឡើងរួចហើយនឹង GitHub Copilot សម្រាប់កម្មវិធីសរសេរកូដជាគូ AI។ -ឧទាហរណ៍កូដនីមួយៗមានសំណួរដែលបានផ្តល់អោយអ្នកអាចសួរទៅ GitHub Copilot ដើម្បីពង្រឹងការយល់ដឹង។ ស្វែងរកសញ្ញា 💡/🤖 នៅក្នុង៖ +គំរូកូដនីមួយៗមានសំណួរផ្តល់អនុសាសន៍ដែលអ្នកអាចសួរបាន GitHub Copilot ដើម្បីជ្រាបច្បាស់ជាងមុន។ ស្វែងរកសញ្ញា 💡/🤖 នៅក្នុង៖ -- **ចំណងជើងឯកសារ Java** - សំណួរតាមលំដាប់ឧទាហរណ៍នីមួយៗ -- **មាតិកាមូឌុល** - សំណួរស្រាវជ្រាវបន្ទាប់ពីឧទាហរណ៍កូដ +- **មុខកថា Java** - សំណួរពិសេសសម្រាប់គំរូនីមួយៗ +- **README មហាសេដ្ឋី** - សំណួរជ្រាបច្បាស់បូកបន្ថែមបន្ទាប់ពីគំរូកូដ -**វិធីប្រើ៖** បើកឯកសារកូដណាមួយហើយសួរសំណួរដែលបានផ្តល់ជូនដោយ Copilot។ វាមានបរិបទពេញលេញនៃជំនួយទាំងមូល អាចពន្យល់ ពង្រីក និងផ្តល់ជម្រើសជាច្រើនបាន។ +**របៀបប្រើ៖** បើកឯកសារកូដណាមួយ ហើយសួរអ្នកជំនួយ Copilot ពីសំណួរផ្តល់អនុសាសន៍។ វាមានបទបង្ហាញពេញលេញនៃកូដ ហើយអាចពន្យល់ ពង្រីក និងផ្តល់ជម្រើសជំនួស។ -ចង់រៀនបន្ថែមទៀត? សូមពិនិត្យ [Copilot សម្រាប់កម្មវិធី AI រួមគ្នា](https://aka.ms/GitHubCopilotAI)។ +ចង់រៀនបន្ថែមទៀត? សូមពិនិត្យមើល [Copilot សម្រាប់កម្មវិធីសរសេរកូដជាគូ AI](https://aka.ms/GitHubCopilotAI)។ ## ធនធានបន្ថែម ### LangChain -[![LangChain4j សម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js សម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain សម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / អ្នកភ្នាក់ងារ -[![AZD សម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI សម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP សម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents សម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Agents +[![AZD សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![ភ្នាក់ងារ AI សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### ស៊េរី AI បង្កើត -[![Generative AI សម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +### ស៊េរី Generative AI +[![Generative AI សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) [![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### ការសិក្សាគោល -[![ម៉ាស៊ីនរៀនសម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![វិទ្យាសាស្រ្តទិន្នន័យសម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI សម្រាប់អ្នកចាប់ផ្ដើម](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![សន្តិសុខប្រព័ន្ធទំនាក់ទំនងសម្រាប់អ្នកចាប់ផ្តើម](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![ការអភិវឌ្ឍវេបសាយសម្រាប់អ្នកចាប់ផ្តើម](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT សម្រាប់អ្នកចាប់ផ្តើម](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![ការអភិវឌ្ឍ XR សម្រាប់អ្នកចាប់ផ្តើម](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +### ការសិក្សាក្តៅ +[![ML សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![វិទ្យាសាស្រ្តទិន្នន័យសម្រាប់អ្នកដំបូង](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI សម្រាប់អ្នកដំបូង](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![សុវត្ថិភាពវេបសាយសម្រាប់អ្នកដំបូង](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- - + ### ស៊េរី Copilot -[![Copilot សម្រាប់កម្មវិធីបញ្ចូល AI ជាគូ](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot សម្រាប់ C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot ធ្វើដំណើរ](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## សូមទទួលបានជំនួយ +## ទទួលបានជំនួយ -ប្រសិនបើអ្នកមាន​បញ្ហា ឬ​មានសំណួរ​អំពី​ការស្ថាបនាបញ្ចូលកម្មវិធី AI សូមចូលរួម៖ +បើអ្នកមានបញ្ហា ឬមានសំនួរអំពីការបង្កើតកម្មវិធី AI សូមចូលរួម: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -ប្រសិនបើអ្នកមានមតិយោបល់ពីផលិតផល ឬកំហុសពេលកំពុងស្ថាបនាអ្នកអាចចូលទៅកាន់៖ +បើអ្នកមានមតិប្រកាសផលិតផល ឬកំហុសពេលបង្កើត សូមចូលរកបាននៅ: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) -## របៀបអនុញ្ញាត +## អាជ្ញាប័ណ្ណ -បណ្ណៈកម្ម MIT - មើល [LICENSE](../../LICENSE) ឯកសារសម្រាប់ព័ត៌មានលម្អិត។ +អាជ្ញាប័ណ្ណ MIT - មើលឯកសារ [LICENSE](../../LICENSE) សម្រាប់ព័ត៌មានលម្អិត។ --- -**ព័ត៌មានបដិសេធ**៖ -ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាកម្មបកប្រែ AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទោះយើងខ្ញុំមានការខំប្រឹងប្រែងសម្រាប់ភាពត្រឹមត្រូវ ក៏សូមយល់ឲ្យបានថា ការបកប្រែដោយស្វ័យប្រវត្តិនេះអាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមនៅក្នុងភាសាទូទៅគួរត្រូវបានគេចាត់ទុកថាជាផ្នែកទិន្នផលផ្លូវការ។ សម្រាប់ព័ត៌មានសំខាន់ៗ ការបកប្រែដោយមនុស្សជំនាញគឺជាជម្រើសដែលបានណែនាំ។ យើងខ្ញុំមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំនិយម ឬការបកប្រែខុសដែលអាចកើតឡើងពីការប្រើប្រាស់ការបកប្រែនេះទេ។ +**ការបដិសេធ**: +ឯកសារនេះត្រូវបានបម្លែងភាសា ដោយប្រើសេវាបម្លែងភាសា AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទោះយើងខ្ញុំមានក្តីប្រាថ្នាឱ្យបានច្បាស់លាស់ តែសូមយល់ដឹងថាការបម្លែងដោយស្វ័យប្រវត្តិក៏អាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមជាភាសាទីតាំងគួរត្រូវបានគេប្រើជាប្រភពច្បាស់លាស់។ សម្រាប់ព័ត៌មានសំខាន់ៗ សូមណែនាំឱ្យប្រើប្រាស់ការប្រែដោយមនុស្សជំនាញ។ យើងខ្ញុំមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកស្រាយខុសបន្ទាប់ពីការប្រើប្រាស់ការបម្លែងនេះនោះទេ។ \ No newline at end of file diff --git a/translations/km/docs/GLOSSARY.md b/translations/km/docs/GLOSSARY.md index 365f9a87f..44f24bb6a 100644 --- a/translations/km/docs/GLOSSARY.md +++ b/translations/km/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j វចនានុក្រម +# LangChain4j អត្ថន័យ​បញ្ជី​ថ្មីៗ -## សារពីបារាំង +## តារាងមាតិកា -- [ចំណុចមូលដ្ឋាន](#ចំណុចមូលដ្ឋាន) -- [សមាសភាគ LangChain4j](#សមាសភាគ-langchain4j) -- [យល់ដឹងអំពី AI/ML](#គំនិត-aiml) -- [ការក្សារព្រៀង](#guardrails---module-00) -- [ការដឹកនាំ Prompt](#prompt-engineering---module-02) -- [RAG (ការបង្កើតជួយដោយការទាញយក)](#rag-retrieval-augmented-generation---module-03) +- [មូលដ្ឋានគំនិត](#មូលដ្ឋានគំនិត) +- [ធាតុ LangChain4j](#ធាតុ-langchain4j) +- [គំនិត AI/ML](#គំនិត-aiml) +- [ឧបករណ៍ការពារ](#ឧបករណ៍ការពារ) +- [វិស្វកម្មការផ្ដល់�rompt](#prompt-engineering---module-02) +- [RAG (ការបង្កើតបន្ថែមដោយការស្ទង់តាម)](#rag-retrieval-augmented-generation---module-03) - [ភ្នាក់ងារ និងឧបករណ៍](#agents-and-tools---module-04) - [ម៉ូឌុល Agentic](#agentic-module---module-05) -- [ពProtocol សម្រាប់បរិបទម៉ូដែល (MCP)](#model-context-protocol-mcp---module-05) +- [ពិធីការបរិបទម៉ូឌែល (MCP)](#model-context-protocol-mcp---module-05) - [សេវាកម្ម Azure](#azure-services---module-01) -- [ការធ្វើតេស្ត និងអភិវឌ្ឍន៍](#testing-and-development---testing-guide) +- [ការតេស្ត និងការអភិវឌ្ឍ](#testing-and-development---testing-guide) -យោងយ៉ាងឆាប់រហ័សសម្រាប់ពាក្យ និងគំនិតដែលប្រើជារួមទាំងមូលវគ្គសិក្សា។ +យោងរាយរយសំរាប់ពាក្យនិងគំនិតដែលប្រើក្នុងមេរៀន។ -## ចំណុចមូលដ្ឋាន +## មូលដ្ឋានគំនិត -**ភ្នាក់ងារ AI** - ប្រព័ន្ធដែលប្រើ AI ដើម្បីគិតយល់ និងប្រព្រឹត្តិអំពើដោយផ្ទាល់ខ្លួន។ [Module 04](../04-tools/README.md) +**ភ្នាក់ងារ AI** - ប្រព័ន្ធដែលប្រើ AI ដើម្បីចង្អុលសេចក្ដីហើយអនុវត្តដោយស្វ័យប្រវត្តិ។ [Module 04](../04-tools/README.md) -**ខ្សែភាព** - ចំណាត់តាងនៃប្រតិបត្តិការដែលលទ្ធផលដឹកនាំទៅជំហានបន្ទាប់។ +**ខ្សែ** - ជួរនៃប្រតិបត្តិការដែលលទ្ធផលចេញដល់ជំហានបន្ទាប់។ -**ការបំបែក (Chunking)** - បំបែកឯកសារជាទំព័រតូចៗ។ ជារឿយៗ៖ ៣០០-៥០០ តូកិន ជាមួយការជាប់គ្នា។ [Module 03](../03-rag/README.md) +**ការបែងចែកឯកសារ** - ការបំបែកឯកសារជាចំណែកតូចៗ។ ឧទាហរណ៍: 300-500 តូចខ្ទង់ដោយប្រែប្រួលស្ទើរតែមានអនុលូមក។ [Module 03](../03-rag/README.md) -**បង្អួចបរិបទ** - ចំនួនតូកិនអតិបរមាដែលម៉ូដែលអាចដំណើរការ។ GPT-5.2៖ ៤០០K តូកិន (រហូតដល់ ២៧២K ទិន្នន័យចូល, ១២៨K លទ្ធផលចេញ). +**បង្អួចបរិបទ** - បរិមាណតូចបំផុតនៃតូចខ្ទង់ដែលម៉ូឌែលអាចដំណើរការ។ GPT-5.2: 400K តូចខ្ទង់ (រហូតដល់ 272K បញ្ចូល, 128K លទ្ធផលចេញ)។ -**កំណត់តាង (Embeddings)** - វ៉ិកទ័រសង្គ្រោះចំនួនដែលតំណាងអត្ថន័យអត្ថបទ។ [Module 03](../03-rag/README.md) +**ការបញ្ចូលអក្សរ​** - វិចិត្រស័ក្តិលេខគណនាដែលជាតំណាងអត្ថន័យអក្សរ។ [Module 03](../03-rag/README.md) -**ការហៅមុខងារ (Function Calling)** - ម៉ូដែលបង្កើតសំណើរ ទ្រង់ទ្រាយរចនាសម្ព័ន្ធដើម្បីហៅមុខងារបន្ទាប់ពីក្រៅ។ [Module 04](../04-tools/README.md) +**ការហៅមុខងារ** - ម៉ូឌែលបង្កើតសំណើរ​រចនាសម្ព័ន្ធសម្រាប់ហៅមុខងារនៅក្រៅ។ [Module 04](../04-tools/README.md) -**ការមើលឃើញមិនត្រឹមត្រូវ (Hallucination)** - នៅពេលម៉ូដែលបង្កើតព័ត៌មានខុសប្លែកប៉ុន្តែសមស្រប។ +**ការស្រមៃពិតប្រាកដ** - ពេលដែលម៉ូឌែលបង្កើតព័ត៌មានមិនត្រឹមត្រូវប៉ុន្តែមើលទៅឆ្ងល់។ -**Prompt** - អត្ថបទបញ្ចូលទៅម៉ូដែលភាសា។ [Module 02](../02-prompt-engineering/README.md) +**prompt** - អក្សរបញ្ចូលទៅម៉ូឌែលភាសា។ [Module 02](../02-prompt-engineering/README.md) -**ស្វែងរក តាមអត្ថន័យ Semantic Search** - ស្វែងរកតាមអត្ថន័យដោយកំណត់តាង មិនមែនតាមពាក្យគន្លឹះ។ [Module 03](../03-rag/README.md) +**ស្វែងរកដោយមនុស្សអត្ថន័យ** - ស្វែងរកដោយផ្អែកលើអត្ថន័យប្រើ embeddings មិនមែនពាក្យគន្លឹះ។ [Module 03](../03-rag/README.md) -**មានស្ថានភាព (Stateful) ទល់នឹង គ្មានស្ថានភាព (Stateless)** - Stateless៖ គ្មានចងចាំ។ Stateful៖ រក្សាបទសម្ភាសន៍ជាចំណងចាំ។ [Module 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: គ្មានចងចាំ។ Stateful: រក្សាបរិបទនៃការសន្ទនា។ [Module 01](../01-introduction/README.md) -**តូកិន (Tokens)** - ឯកតាអត្ថបទមូលដ្ឋានដែលម៉ូដែលដំណើរការ។ មានឥទ្ធិពលដល់កម្រៃនិងកំណត់។ [Module 01](../01-introduction/README.md) +**តូចខ្ទង់** - ឯកតាអក្សរមូលដ្ឋានដែលម៉ូឌែលដំណើរការ។ ប៉ះពាល់តម្លៃនិងដែនកំណត់។ [Module 01](../01-introduction/README.md) -**ការបង្រួបបង្រួមឧបករណ៍ (Tool Chaining)** - ដំណើរការឧបករណ៍ជាប់ៗដែលលទ្ធផលជួយដឹកនាំហៅជំហានបន្ទាប់។ [Module 04](../04-tools/README.md) +**Tool Chaining** - ការប្រើឧបករណ៍ជាដំណាក់កាលដែលលទ្ធផលចេញជួយក្នុងការហៅបន្ទាប់។ [Module 04](../04-tools/README.md) -## សមាសភាគ LangChain4j +## ធាតុ LangChain4j -**AiServices** - បង្កើតចំណុចប្រទាក់សេវាកម្ម AI ប្រភេទសុវត្ថិភាព។ +**AiServices** - បង្កើតចំណុចបំផុតសេវាកម្ម AI មានប្រភេទត្រឹមត្រូវ។ -**OpenAiOfficialChatModel** - អតិថិជនរួម​សម្រាប់ម៉ូដែល OpenAI និង Azure OpenAI។ +**OpenAiOfficialChatModel** - អតិថិជនតែមួយសម្រាប់ម៉ូឌែល OpenAI និង Azure OpenAI ។ -**OpenAiOfficialEmbeddingModel** - បង្កើតកំណត់តាងដោយប្រើអតិថិជន OpenAI Official (គាំទ្រ OpenAI និង Azure OpenAI ទាំងពីរ)។ +**OpenAiOfficialEmbeddingModel** - បង្កើត embeddings ដោយប្រើអតិថិជន OpenAI ក្នុងផ្លូវការរួមទាំង OpenAI និង Azure OpenAI។ -**ChatModel** - ចំណុចប្រទាក់សំខាន់សម្រាប់ម៉ូដែលភាសា។ +**ChatModel** - ចំណុចបំផុតសម្រាប់ម៉ូឌែលភាសា។ -**ChatMemory** - រក្សាបទសម្ភាសន៍ជាចំណងចាំ។ +**ChatMemory** - រក្សាបរិបទនៃការសន្ទនា។ -**ContentRetriever** - រកយកចំណុចឯកសារសម្រាប់ RAG។ +**ContentRetriever** - ស្វែងរកចំណែកឯកសារដែលសមស្របសម្រាប់ RAG។ -**DocumentSplitter** - បំបែកឯកសារ​ឲ្យក្លាយជាផ្នែក។ +**DocumentSplitter** - បំបែកឯកសារជាចំណែកតូចៗ។ -**EmbeddingModel** - បម្លែងអត្ថបទទៅជាវ៉ិកទ័រលេខ។ +**EmbeddingModel** - បំលែងអត្ថបទទៅជាវិចិត្រស័ក្តិលេខ។ -**EmbeddingStore** - រក្សាទុកនិងយកកំណត់តាងវិញ។ +**EmbeddingStore** - ទីតាំងស្តុកនិងយក embeddings។ -**MessageWindowChatMemory** - រក្សាបង្អួចសារបច្ចុប្បន្នជាមួយ ប្លក់បិទ។ +**MessageWindowChatMemory** - រក្សាបង្អួចបង្ហាញសារថ្មីៗនៃសារ។ -**PromptTemplate** - បង្កើត prompt អាចប្រើបន្តជាមួយភាគតំណាង `{{variable}}`។ +**PromptTemplate** - បង្កើត prompt ដែលអាចប្រើឡើងវិញជាមួយ `{{variable}}` ។ -**TextSegment** - ផ្នែកអត្ថបទជាមួយទិន្នន័យមេតាដាតា។ ប្រើក្នុង RAG។ +**TextSegment** - ចំណាត់ក្រុមអក្សរជាមួយព័ត៌មានបន្ថែម។ ប្រើក្នុង RAG។ -**ToolExecutionRequest** - តំណាងសំណើរអនុវត្តឧបករណ៍។ +**ToolExecutionRequest** - បង្ហាញសំណើរប្រើឧបករណ៍។ -**UserMessage / AiMessage / SystemMessage** - ប្រភេទសារបទសម្ភាសន៍។ +**UserMessage / AiMessage / SystemMessage** - ប្រភេទសារសន្ទនា។ ## គំនិត AI/ML -**ការសិក្សា Few-Shot** - ផ្តល់ឧទាហរណ៍ក្នុង prompt។ [Module 02](../02-prompt-engineering/README.md) +**ការរៀនពីគំរូតិច** - ផ្ដល់ឧទាហរណ៍ក្នុង prompt ។ -**ម៉ូដែលភាសាធំ (LLM)** - ម៉ូដែល AI ដែលបានហ្វឹកហាត់លើទិន្នន័យអត្ថបទធំទូលាយ។ +**ម៉ូឌែលភាសាជាតួធំ (LLM)** - ម៉ូឌែល AI ដែលបានហ្វឹកហាត់លើទិន្នន័យអត្ថបទធំ។ -**កំរិតការគិត (Reasoning Effort)** - ព៉ារ៉ាម៉ែត្រ GPT-5.2 ដែលគ្រប់គ្រងជម្រៅនៃការគិត។ [Module 02](../02-prompt-engineering/README.md) +**កំរិតការសំរាប់ហេតុផល** - ប៉ារ៉ាម៉ែត្រ GPT-5.2 ដែលគ្រប់គ្រងជម្រៅនៃការគិតសំរាប់ហេតុផល។ -**សីតុណ្ហភាព (Temperature)** - គ្រប់គ្រងភាពចៃឆៃនៃលទ្ធផល។ ទាប=កំណត់ត្រា ឡើងខ្ពស់=ច្នៃប្រឌិត។ +**សីតុណ្ហភាព** - គ្រប់គ្រងភាពចៃដន្យនៃលទ្ធផល។ ទាប=ច្បាស់លាស់, ខ្ពស់=បង្កើតភាពច្នៃប្រឌិត។ -**មូលដ្ឋានទិន្នន័យ វ៉ិកទ័រ (Vector Database)** - មូលដ្ឋានទិន្នន័យឯកទេសសម្រាប់កំណត់តាង។ [Module 03](../03-rag/README.md) +**មូលដ្ឋានទិន្នន័យវិចិត្រស័ក្តិ** - មូលដ្ឋានទិន្នន័យពិសេសសម្រាប់ embeddings។ [Module 03](../03-rag/README.md) -**ការសិក្សា Zero-Shot** - អនុវត្តន៍ភារកិច្ចដោយគ្មានឧទាហរណ៍។ [Module 02](../02-prompt-engineering/README.md) +**ការរៀនពីគំរូសូន្យ** - ការប្រតិបត្តិការដោយគ្មានឧទាហរណ៍។ [Module 02](../02-prompt-engineering/README.md) -## ការក្សារព្រៀង - [Module 00](../00-quick-start/README.md) +## ឧបករណ៍ការពារ -**ការពារ ជ្រៅក្នុងជម្រៅ (Defense in Depth)** - វិធីសាស្រ្តសន្តិសុខប៉ាន់ប្រមាណជាច្រើនជាតិដែលបញ្ចូលការក្សារព្រៀងកម្រិតកម្មវិធីជាមួយជម្រៅត្រួតពិនិត្យសុវត្ថិភាពអ្នកផ្គត់ផ្គង់។ +**ការពារជាន់ខ្ពស់** - វិធីសាស្រ្តសុវត្ថិភាពច្រើនស្រទាប់រួមបញ្ចូល guardrails កម្រិតកម្មវិធីជាមួយនឹងតម្រងសុវត្ថិភាពរបស់អ្នកផ្គត់ផ្គង់។ -**ការបង្ហាញខ្លាំង (Hard Block)** - អ្នកផ្គត់ផ្គង់បោះបង់កំហុស HTTP 400 សម្រាប់ការបំពានខ្លាំងៗរបស់មាតិកា។ +**ការរាំងខ្ទប់តឹងរឹង** - អ្នកផ្គត់ផ្គង់បោះបង់កំហុស HTTP 400 សម្រាប់ការបំពានខ្លាំង។ -**InputGuardrail** - ចំណុចប្រទាក់ LangChain4j សម្រាប់ផ្ទៀងផ្ទាត់ការបញ្ចូលអ្នកប្រើមុនវាចូលដល់ LLM។ រក្សាទុកថវិកា និងពេលវេលាដោយការបណ្ដេញ prompt ដែលមានគ្រោះថ្នាក់ឆាប់។ +**InputGuardrail** - ចំណុចប្រទាក់ LangChain4j សម្រាប់ផ្ទៀងផ្ទាត់បញ្ចូលអ្នកប្រើ មុនវាចូល LLM។ ជួយសន្សំថ្លៃនិងពេលវេលា ដោយរាំងខ្ទប់ prompt ដែលមានគ្រោះថ្នាក់បានមុនពេលពេញលេញ។ **InputGuardrailResult** - ប្រភេទត្រឡប់សម្រាប់ការផ្ទៀងផ្ទាត់ guardrail៖ `success()` ឬ `fatal("reason")`។ -**OutputGuardrail** - ចំណុចប្រទាក់សម្រាប់ផ្ទៀងផ្ទាត់ចម្លើយ AI មុនត្រឡប់ទៅអ្នកប្រើប្រាស់។ +**OutputGuardrail** - ចំណុចប្រទាក់សម្រាប់ផ្ទៀងផ្ទាត់ចម្លើយ AI មុនទទួលទៅអ្នកប្រើ។ -**ជម្រៅត្រួតពិនិត្យសុវត្ថិភាពអ្នកផ្គត់ផ្គង់** - ត្រួតពិនិត្យមាតិកាដែលសាងសង់ដោយអ្នកផ្គត់ផ្គង់ AI (ឧ. GitHub Models) ដែលចាប់ការបំពាននៅកម្រិត API។ +**តម្រងសុវត្ថិភាពអ្នកផ្គត់ផ្គង់** - តម្រងមាតិកាដែលបានបង្កើតជំនួយពីអ្នកផ្គត់ផ្គង់ AI (ឧ. Azure OpenAI) ដែលចាប់ឃើញការបំពាននៅកម្រិត API។ -**ការបដិសេធទន់ភ្លន់ (Soft Refusal)** - ម៉ូដែលបដិសេធយ៉ាងល្អប្រសើរដោយមិនបង្ហាញកំហុស។ +**ការបដិសេធស្រាល** - ម៉ូឌែលអធ្យាស្រ័យបដិសេធឆ្លើយតបដោយគ្មានកំហុស។ -## ការដឹកនាំ Prompt - [Module 02](../02-prompt-engineering/README.md) +## Prompt Engineering - [Module 02](../02-prompt-engineering/README.md) -**ចងšប្រសួត Chain-of-Thought** - គិតជាជំហានទាំងមូលសម្រាប់ភាពត្រឹមត្រូវល្អប្រសើរ។ +**Chain-of-Thought** - ដំណើរគំនិតជាដំណាក់កាល សម្រាប់ភាពត្រឹមត្រូវកាន់តែល្អ។ -**លទ្ធផលដាក់កំណត់ (Constrained Output)** - អនុវត្តទ្រង់ទ្រាយឬរចនាសម្ព័ន្ធជាក់លាក់។ +**លទ្ធផលកំណត់** - បង្ខំទ្រង់ទ្រាយ ឬរចនាសម្ព័ន្ធជាក់លាក់។ -**ការត្រៀមខ្ពស់ (High Eagerness)** - លំនាំ GPT-5.2 សម្រាប់ការគិតជ្រៅល្អ។ +**ភាពឆាប់រហ័សខ្ពស់** - រចនាសម្ព័ន្ធ GPT-5.2 សម្រាប់ការគិតហេតុផលយ៉ាងពេញលេញ។ -**ការត្រៀមទាប (Low Eagerness)** - លំនាំ GPT-5.2 សម្រាប់ចម្លើយរហ័ស។ +**ភាពឆាប់រហ័សទាប** - រចនាសម្ព័ន្ធ GPT-5.2 សម្រាប់ចម្លើយរហ័ស។ -**ការសន្ទនាច្រើនជុំ (Multi-Turn Conversation)** - រក្សាបរិបទទាំងមូលនៅពេលចរចា។ +**ការសន្ទនាច្រើនជុំ** - រក្សាឯកសារបរិបទជាមធ្យមក្នុងការផ្លាស់ប្ដូរព័ត៌មាន។ -**Prompting ជាប្រភេទតួនាទី (Role-Based Prompting)** - កំណត់ផ្ទាល់ខ្លួនម៉ូដែលតាមសាររបៀបប្រព័ន្ធ។ +**ការផ្ដល់ Prompt ផ្អែកលើតួនាទី** - កំណត់ពិណាណម៉ូឌែលតាមសាររបស់ប្រព័ន្ធ។ -**ការបញ្ចេញចំណាស់ខ្លួន (Self-Reflection)** - ម៉ូដែលវាយតម្លៃ និងកែលម្អលទ្ធផល។ +**ការពិចារណាខ្លួនឯង** - ម៉ូឌែលវាយតម្លៃ និងបង្កើតលទ្ធផលល្អប្រសើរឡើង។ -**វិភាគរចនាសម្ព័ន្ធ (Structured Analysis)** - ស៊ើបការវាយតម្លៃកំណត់។ +**វិភាគមានរចនាសម្ព័ន្ធ** - ឯកសារវាយតម្លៃច្បាស់លាស់។ -**លំនាំអនុវត្តភារកិច្ច (Task Execution Pattern)** - គំរោង → អនុវត្ត → សង្ខេប។ +**លំនាំអនុវត្តភារកិច្ច** - ប្លង់ → អនុវត្ត → សង្ខេប។ -## RAG (ការបង្កើតជួយដោយការទាញយក) - [Module 03](../03-rag/README.md) +## RAG (ការបង្កើតបន្ថែមដោយការស្ទង់តាម) - [Module 03](../03-rag/README.md) -**បណ្ដាញដំណើរការឯកសារ (Document Processing Pipeline)** - ផ្ទុក → បំបែក → បង្រួប → រក្សាទុក។ +**ស្រង់បច្ចេកទេសឯកសារ** - បង្ហាញ → បំបែក → បញ្ចូល → ស្តុក។ -**ឃ្លាំងបង្រួបក្នុងនឹកស្មារតី (In-Memory Embedding Store)** - ការផ្ទុកមិនថ្នាក់ថ្នងសម្រាប់ធ្វើតេស្ត។ +**ការផ្ទុក Embedding នៅក្នុងអង្គចងចាំ** - ទីតាំងមិនថ្លៃចិត្តសម្រាប់ការតេស្ត។ -**RAG** - បញ្ចូលការទាញយកជាមួយការបង្កើត ដើម្បីធានាចម្លើយមានគោលដៅ។ +**RAG** - ផ្តល់កំរិតការស្វែងរក រួមជាមួយបង្កើតដើម្បីបម្រុងការឆ្លើយតប។ -**ពិន្ទុស្រដៀងគ្នា (Similarity Score)** - វិមាត្រពិន្ទុ (0-1) នៃអត្ថន័យស្រដៀងគ្នា។ +**ពិន្ទុស្រដៀង** - វាស់ (0-1) នៃស្រដៀងដោយអត្ថន័យ។ -**យោងប្រភព (Source Reference)** - ទិន្នន័យពីមាតិកាដែលបានទាញយក។ +**យោងប្រភព** - ព័ត៌មានបន្ថែមអំពីមាតិកាដែលបានរកឃើញ។ -## ភ្នាក់ងារ និងឧបករណ៍ - [Module 04](../04-tools/README.md) +## ភ្នាក់ងារ និង ឧបករណ៍ - [Module 04](../04-tools/README.md) -**@Tool Annotation** - សម្គាល់វិធីសាស្រ្ត Java ជាឧបករណ៍អាចហៅដោយ AI។ +**@Tool Annotation** - កំណត់វិធីសាស្រ្ត Java ជាឧបករណ៍ដែលអាចហៅបានដោយ AI។ -**លំនាំ ReAct** - គិត → ប្រព្រឹត្ត → ស្ទង់មើល → ជម្រុញទៀត។ +**លំនាំ ReAct** - គិត → អនុវត្ត → ទស្សនា → តម្រូវឡើងវិញ។ -**គ្រប់គ្រងសម័យ (Session Management)** - បរិបទបំបែកសម្រាប់អ្នកប្រើផ្សេងៗ។ +**ការគ្រប់គ្រងវគ្គសិក្សា** - បរិបទបំបែកសម្រាប់អ្នកប្រើប្រាស់ផ្សេងៗ។ -**ឧបករណ៍ (Tool)** - មុខងារភ្នាក់ងារ AI អាចហៅបាន។ +**ឧបករណ៍** - មុខងារដែលភ្នាក់ងារ AI អាចហៅបាន។ -**ការពិពណ៌នាឧបករណ៍ (Tool Description)** - ឯកសារពីគោលបំណង និងប៉ារ៉ាម៉ែត្រឧបករណ៍។ +**ការពណ៌នាឧបករណ៍** - ឯកសារអំពីគោលបំណងនិងប៉ារ៉ាម៉ែត្រ។ ## ម៉ូឌុល Agentic - [Module 05](../05-mcp/README.md) -**@Agent Annotation** - សម្គាល់ចំណុចប្រទាក់ជាភ្នាក់ងារ AI ជាមួយនឹងការកំណត់ទំរង់អនុវត្តន៍មិនប្រែប្រួល។ +**@Agent Annotation** - កំណត់ចំណុចប្រទាក់ជាភ្នាក់ងារ AI ជាមួយនឹងការបរិយាយអាកប្បកិរិយា។ -**Agent Listener** - Hook សម្រាប់ត្រួតពិនិត្យអនុវត្តភ្នាក់ងារ តាម `beforeAgentInvocation()` និង `afterAgentInvocation()`។ +**Agent Listener** - Hook សម្រាប់តាមដានការអនុវត្តភ្នាក់ងារ តាមរយៈ `beforeAgentInvocation()` និង `afterAgentInvocation()`។ -**Agentic Scope** - ចំណងចាំចែករំលែកដែលភ្នាក់ងាររក្សាទុកលទ្ធផលប្រើ `outputKey` សម្រាប់ភ្នាក់ងារដទៃទៀត។ +**Agentic Scope** - អង្គចងចាំរួមដែលភ្នាក់ងារផ្ទុកលទ្ធផលប្រើ `outputKey` សម្រាប់ភ្នាក់ងារផ្សេងទៀតប្រើបន្ត។ -**AgenticServices** - រោងចក្រ​ក្នុងការបង្កើតភ្នាក់ងារដោយប្រើ `agentBuilder()` និង `supervisorBuilder()`។ +**AgenticServices** - រោងចក្រ បង្កើតភ្នាក់ងារដោយប្រើ `agentBuilder()` និង `supervisorBuilder()`។ -**លំនាំ Workflow មានលក្ខខណ្ឌ (Conditional Workflow)** - ផ្លូវទៅភ្នាក់ងារពិសេសនានាតាមលក្ខខណ្ឌ។ +**ដំណើរការដោយមានលក្ខ័ខណ្ឌ** - ផ្លូវទៅតាមលក្ខខណ្ឌទៅភ្នាក់ងារជំនាញផ្សេងៗ។ -**មនុស្សក្នុងបន្ទាត់ (Human-in-the-Loop)** - លំនាំធ្វើការ បញ្ចូលចំណុចពិនិត្យមនុស្សសម្រាប់អនុម័ត ឬពិនិត្យមាតិកា។ +**មនុស្សនៅក្នុងសៀវភៅ** - លំនាំដំណើរការខ្សែភ្នាក់ងារដែលបន្ថែមចំណុចមនុស្សសម្រាប់អនុម័ត ឬពិនិត្យមាតិកា។ -**langchain4j-agentic** - Maven dependency សម្រាប់ការសង់ភ្នាក់ងារដោយប្រើការបញ្ចេញសេចក្តីថ្លែង (experimental)។ +**langchain4j-agentic** - Maven dependency សម្រាប់ការបង្កើតភ្នាក់ងារជាសេចក្តីប្រកាស (ការប្រឡង)។ -**លំនាំជុំកំណត់ (Loop Workflow)** - ច្រៀងអនុវត្តភ្នាក់ងារឡើងវិញរហូតបានលក្ខខណ្ឌ (ឧ. ពិន្ទុគុណភាព ≥ 0.8)។ +**លំនាំ Loop** - វដ្តការអនុវត្តភ្នាក់ងារដល់ពេលលទ្ធផលបំពេញលក្ខណៈ (ឧ. ពិន្ទុគុណភាព ≥ 0.8) ។ -**outputKey** - ប៉ារ៉ាម៉ែត្រសម្គាល់ភ្នាក់ងារដែលកំណត់ទីតាំងរក្សាលទ្ធផលក្នុង Agentic Scope។ +**outputKey** - ប៉ារ៉ាម៉ែត្រ annotation ភ្នាក់ងារ បញ្ជាក់កន្លែងដែលលទ្ធផលត្រូវផ្ទុកក្នុង Agentic Scope។ -**លំនាំដំណើរការពហុបរិច្ឆេទ (Parallel Workflow)** - ប្រតិបត្តិភ្នាក់ងារច្រើនជាលំនាំសម័យសម្រាប់ការងារឯករាជ្យ។ +**លំនាំប្រតិបត្តិការជាប្រព័ន្ធ 병ឹះ** - រត់ភ្នាក់ងារច្រើនជាសមាជិកសម្រាប់ភារកិច្ចឯករាជ្យ។ -**យុទ្ធសាស្រ្តចម្លើយ (Response Strategy)** - របៀបដែលអ្នកដឹកនាំសម្រេចចម្លើយចុងក្រោយ៖ LAST, SUMMARY, ឬ SCORED។ +**យុទ្ធសាស្រ្តចម្លើយ** - របៀបដែលអ្នកគ្រប់គ្រងបង្ហាញចម្លើយចុងក្រោយ៖ LAST, SUMMARY, ឬ SCORED។ -**លំនាំដំណើរការតាមលំដាប់ (Sequential Workflow)** - អនុវត្តភ្នាក់ងារតាមលំដាប់ដែលលទ្ធផលចេញទៅជំហានបន្ទាប់។ +**លំនាំប្រតិបត្តិការតម្រង់តំណរដោយលំដាប់** - អនុវត្តភ្នាក់ងារតាមលំដាប់ដែលលទ្ធផលចេញទៅជាជំហានបន្ទាប់។ -**លំនាំ Supervisor Agent** - លំនាំ agentic 진보ដែលអ្នកដឹកនាំ LLM សម្រេចចិត្ត δυναμικά អំពី sub-agents ដែលត្រូវហៅ។ +**លំនាំ Supervisor Agent** - លំនាំ agentic ដែលស្ថិតនៅកម្រិតខ្ពស់ ស្ថិតនៅលើ LLM អ្នកគ្រប់គ្រង ដែលសម្រេចចិត្តផ្ទាល់ពីភ្នាក់ងារតូចៗដើម្បីហៅ។ -## ពProtocol សម្រាប់បរិបទម៉ូដែល (MCP) - [Module 05](../05-mcp/README.md) +## ពិធីការបរិបទម៉ូឌែល (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - Maven dependency សម្រាប់ការរួមបញ្ចូល MCP ក្នុង LangChain4j។ +**langchain4j-mcp** - Maven dependency សម្រាប់ការរួមបញ្ចូល MCP ក្នុង LangChain4j ។ -**MCP** - ប្រព័ន្ធបរិបទម៉ូដែល: ស្តង់ដារសម្រាប់ភ្ជាប់កម្មវិធី AI ទៅឧបករណ៍ក្រៅ។ សង់ម្តង ប្រើឲ្យទូទៅ។ +**MCP** - ពិធីការបរិបទម៉ូឌែល៖ ស្តង់ដារសម្រាប់ភ្ជាប់កម្មវិធី AI ទៅឧបករណ៍ក្រៅ។ សាងសង់ម្តង ប្រើបានគ្រប់ទីកន្លែង។ -**MCP Client** - កម្មវិធីភ្ជាប់ទៅម៉ាស៊ីនបម្រើ MCP ដើម្បីស្វែងរកនិងប្រើឧបករណ៍។ +**អតិថិជន MCP** - កម្មវិធីភ្ជាប់ទៅម៉ាស៊ីនបម្រើ MCP ដើម្បីរកឧបករណ៍ និងប្រើវា។ -**MCP Server** - សេវាកម្មបង្ហាញឧបករណ៍តាម MCP ជាមួយពិពណ៌នាច្បាស់លាស់ និងស្គីម៉ា៉ប៉ារ៉ាម៉ែត្រ។ +**ម៉ាស៊ីនបម្រើ MCP** - សេវាកម្មបង្ហាញឧបករណ៍តាមរយៈ MCP ជាមួយនឹងការពិពណ៌នាច្បាស់លាស់និង schemas ប៉ារ៉ាម៉ែត្រ។ -**McpToolProvider** - សមាសភាគ LangChain4j ដែលបាយឧបករណ៍ MCP សម្រាប់ប្រើក្នុងសេវាកម្ម AI និងភ្នាក់ងារ។ +**McpToolProvider** - ធាតុ LangChain4j ដែលរុំឧបករណ៍ MCP សម្រាប់ប្រើប្រាស់ក្នុងសេវាកម្ម AI និងភ្នាក់ងារ។ **McpTransport** - ចំណុចប្រទាក់សម្រាប់ការទំនាក់ទំនង MCP។ ការអនុវត្តមាន Stdio និង HTTP។ -**Stdio Transport** - ដំណើរការបញ្ជូនក្នុងស្រុកតាម stdin/stdout។ ប្រយោជន៍សម្រាប់ចូលប្រើប្រព័ន្ធឯកសារ ឬឧបករណ៍ command-line។ +**Stdio Transport** - ការដឹកជញ្ជូនដំណើរការតំបន់បណ្ដាញតាមរយៈ stdin/stdout។ ប្រយោជន៍សម្រាប់ចូលប្រព័ន្ធឯកសារ ឬឧបករណ៍បញ្ជា។ -**StdioMcpTransport** - អនុវត្ត LangChain4j ដែលបើកម៉ាស៊ីនបម្រើ MCP ជាកម្មវិធីរង។ +**StdioMcpTransport** - អនុវត្ត LangChain4j ដែលបង្កើតម៉ាស៊ីនបម្រើ MCP ជាដំណើរការ​ជាប់ផ្នែកក្រោម។ -**ការស្វែងរកឧបករណ៍ (Tool Discovery)** - អតិថិជនសួរសំណួរម៉ាស៊ីនបម្រើ ស្ដីពីឧបករណ៍ដែលមានជាមួយពិពណ៌នា និងស្គីម៉ា។ +**ការស្វែងរកឧបករណ៍** - អតិថិជនសួរម៉ាស៊ីនបម្រើ ដើម្បីស្វែងរកឧបករណ៍ដែលមានជាមួយពិពណ៌នានិង schemas។ ## សេវាកម្ម Azure - [Module 01](../01-introduction/README.md) -**Azure AI Search** - ស្វែងរកពពកជាមួយមុខងារវ៉ិកទ័រ។ [Module 03](../03-rag/README.md) +**Azure AI Search** - ស្វែងរកពពកជាមួយសមត្ថភាពវិចិត្រស័ក្តិ។ [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - ដំណើរការដាក់ឲ្យដំណើរការ Azure resources។ +**Azure Developer CLI (azd)** - ប្រើប្រាស់ធនធាន Azure ។ -**Azure OpenAI** - សេវា AI អាជីវកម្មរបស់ Microsoft។ +**Azure OpenAI** - សេវាកម្ម AI សម្រាប់ស្ថាប័នរបស់ Microsoft ។ -**Bicep** - ភាសាកូដដំណើរការ Azure। [Infrastructure Guide](../01-introduction/infra/README.md) +**Bicep** - ភាសា Azure សម្រាប់ infrastructure-as-code ។ [Infrastructure Guide](../01-introduction/infra/README.md) -**ឈ្មោះដាក់ឲ្យដំណើរការ (Deployment Name)** - ឈ្មោះសម្រាប់ដាក់ម៉ូដែលក្នុង Azure។ +**ឈ្មោះការចែកចាយ** - ឈ្មោះសម្រាប់ការចែកចាយម៉ូឌែលក្នុង Azure ។ -**GPT-5.2** - ម៉ូដែល OpenAI ថ្មីៗជាមួយការគ្រប់គ្រងការគិត។ [Module 02](../02-prompt-engineering/README.md) +**GPT-5.2** - ម៉ូឌែលផ្លូវការ OpenAI ថ្មីបំផុត មានការគ្រប់គ្រងបញ្ហាចម្ងល់។ [Module 02](../02-prompt-engineering/README.md) -## ការធ្វើតេស្ត និងអភិវឌ្ឍន៍ - [Testing Guide](TESTING.md) +## ការតេស្ត និងការអភិវឌ្ឍ - [Testing Guide](TESTING.md) -**Dev Container** - បរិយាកាសអភិវឌ្ឍដែលមាន container រួមបញ្ចូល។ [Configuration](../../../.devcontainer/devcontainer.json) +**Dev Container** - បរិយាកាសអភិវឌ្ឍបានធ្វើជាបន្ទប់ container។ [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - ទីលានម៉ូដែល AI ឥតគិតថ្លៃ។ [Module 00](../00-quick-start/README.md) +**ការតេស្តក្នុងអង្គចងចាំ** - ការតេស្តដោយប្រើទីតាំងម៉េមូរី។ -**In-Memory Testing** - ការធ្វើតេស្តជាមួយការផ្ទុកក្នុងនឹកស្មារតី។ +**ការតេស្តរួមបញ្ចូល** - ការតេស្តជាមួយផ្នែកហេដ្ឋារចនាសម្ព័ន្ធពិតប្រាកដ។ -**Integration Testing** - ការធ្វើតេស្តជាមួយហេដ្ឋារចនាសម្ព័ន្ធពិត។ +**Maven** - ឧបករណ៍សាងសង់ Java ។ -**Maven** - ឧបករណ៍ស្វយ័តសំរាប់កសាង Java។ +**Mockito** - ស៊្រ្ដេហ្វ Java សម្រាប់ធ្វើ mocking ។ -**Mockito** - ស្ថាបត្យកម្ម mocking សម្រាប់ Java។ - -**Spring Boot** - ស៊ុមកម្មវិធី Java។ [Module 01](../01-introduction/README.md) +**Spring Boot** - ស៊្រ្ដេហ្វកម្មវិធី Java ។ [Module 01](../01-introduction/README.md) --- -**ការបដិសេធ**៖ -ឯកសារនេះត្រូវបានបកប្រែដោយប្រើសេវាកម្មបកប្រែ AI [Co-op Translator](https://github.com/Azure/co-op-translator) ។ ខណៈពេលយើងខំប្រឹងរកភាពត្រឹមត្រូវ យើងសូមជ្រាបថាការបកប្រែដោយស្វ័យប្រវត្តិអាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមក្នុងភាសាប្រពៃណីគួរត្រូវបានឱ្យមានសិទ្ធិជាឯកសារដើមដែលមានអំណាចច្បាប់។ សម្រាប់ព័ត៌មានសំខាន់ៗ យើងផ្តល់អនុសាសន៍ឱ្យប្រើការបកប្រែដោយមនុស្សជំនាញវិជ្ជាជីវៈ។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកស្រាយខុសប្រភពចេញពីការប្រើប្រាស់ការបកប្រែនេះឡើយ។ +**ការបដិសេធ**: +ឯកសារនេះត្រូវបានបម្លែងភាសា ដោយប្រើសេវាបម្លែងភាសា AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទោះយើងខ្ញុំមានក្តីប្រាថ្នាឱ្យបានច្បាស់លាស់ តែសូមយល់ដឹងថាការបម្លែងដោយស្វ័យប្រវត្តិក៏អាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមជាភាសាទីតាំងគួរត្រូវបានគេប្រើជាប្រភពច្បាស់លាស់។ សម្រាប់ព័ត៌មានសំខាន់ៗ សូមណែនាំឱ្យប្រើប្រាស់ការប្រែដោយមនុស្សជំនាញ។ យើងខ្ញុំមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកស្រាយខុសបន្ទាប់ពីការប្រើប្រាស់ការបម្លែងនេះនោះទេ។ \ No newline at end of file diff --git a/translations/km/docs/TESTING.md b/translations/km/docs/TESTING.md index 3e941ab9b..55571146d 100644 --- a/translations/km/docs/TESTING.md +++ b/translations/km/docs/TESTING.md @@ -1,20 +1,20 @@ # ការធ្វើតេស្តកម្មវិធី LangChain4j -## ប្រធានបទ +## មាតិការដ្ឋាន - [ចាប់ផ្តើមយ៉ាងឆាប់រហ័ស](#ចាប់ផ្តើមយ៉ាងឆាប់រហ័ស) -- [អ្វីដែលការធ្វើតេស្តគ្របដណ្តប់](#អ្វីដែលការធ្វើតេស្តគ្របដណ្តប់) -- [ការបង្ហាញការធ្វើតេស្ត](#ការរត់ការធ្វើតេស្ត) -- [ការធ្វើតេស្តក្នុង VS Code](#ការរត់ការធ្វើតេស្តក្នុង-vs-code) -- [គំរូការធ្វើតេស្ត](#គំរូការធ្វើតេស្ត) +- [តេស្តបានគ្របដណ្តប់អ្វីខ្លះ](#តេស្តបានគ្របដណ្តប់អ្វីខ្លះ) +- [របៀបរត់តេស្ត](#របៀបរត់តេស្ត) +- [របៀបរត់តេស្តក្នុង VS Code](#របៀបរត់តេស្តក្នុង-vs-code) +- [រចនាប័ទ្មតេស្ត](#រចនាប័ទ្មតេស្ត) - [ទស្សនៈការធ្វើតេស្ត](#ទស្សនៈការធ្វើតេស្ត) - [ជំហានបន្ទាប់](#ជំហានបន្ទាប់) -មគ្គុទេសក៍នេះនាំអ្នកឆ្លងកាត់ការធ្វើតេស្តដែលបង្ហាញពីរបៀបធ្វើតេស្តកម្មវិធី AI ដោយមិនត្រូវការទៅកាន់កូនសោ API ឬសេវាកម្មខាងក្រៅ។ +មេរៀននេះនឹងដើរតាមជំហានតេស្តដែលបង្ហាញពីរបៀបធ្វើតេស្តកម្មវិធី AI ដោយមិនត្រូវការខ្សែសោ API ឬសេវាកម្មខាងក្រៅ។ ## ចាប់ផ្តើមយ៉ាងឆាប់រហ័ស -រត់ការធ្វើតេស្តទាំងអស់ជាមួយពាក្យបញ្ជាពីរយៈពេលតែមួយ: +រត់តេស្តទាំងអស់ជាមួយពាក្យបញ្ជា​មួយ៖ **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -ពេលដំណើរការតេស្តទាំងអស់ជាលទ្ធផលជោគជ័យ អ្នកគួរបង្ហាញចេញដូចក្នុងរូបថតអេក្រង់ខាងក្រោម — ការធ្វើតេស្តមិនមានកំហុស។ +ពេលតេស្តទាំងអស់ជោគជ័យ អ្នកគួរតែឃើញលទ្ធផលដូចក្នុងរូបថតអេក្រង់ខាងក្រោម — តេស្តប្រារព្ធដោយគ្មានកំហុសទេ។ -លទ្ធផលការធ្វើតេស្តជោគជ័យ +Successful Test Results -*ការបង្ហាញលទ្ធផលសម្រេចបានពោលពីការធ្វើតេស្តទាំងអស់ជោគជ័យដោយគ្មានកំហុសណាមួយ* +*ការរត់តេស្តបានជោគជ័យ បង្ហាញឲ្យឃើញថាតេស្តទាំងអស់ជោគជ័យដោយគ្មានកំហុស* -## អ្វីដែលការធ្វើតេស្តគ្របដណ្តប់ +## តេស្តបានគ្របដណ្តប់អ្វីខ្លះ -វគ្គនេះផ្តោតលើ **ការធ្វើតេស្តឯកតា** ដែលរត់នៅក្នុងស៊ើបការណ៍របស់អ្នក។ ការធ្វើតេស្តមួយៗបង្ហាញពីមូលដ្ឋានគំនិត LangChain4j ក្នុងលក្ខណៈឯកសារពីរ។ ប៉ុរក្សាទិកក្ខណៈមួយព្យាង្គខាងក្រោមបង្ហាញកន្លែងដែលការធ្វើតេស្តឯកតាវាយតម្លៃ — ពួកវាជាគ្រឹះរហ័ស ទុកចិត្តបាន ដែលយុទ្ធសាស្ត្រធ្វើតេស្តផ្សេងទៀតរបស់អ្នកអាចសាងសង់។ +វគ្គនេះផ្ដោតលើ **តេស្តឯកត្តា** ដែលរត់នៅក្នុងម៉ាស៊ីនមួយខ្នាត។ តេស្តនីមួយៗបង្ហាញពីគំនិត LangChain4j ជាក់លាក់ដោយផ្តោតលើឯកត្តា។ ពិរាម៉ីតតេស្តខាងក្រោមបង្ហាញកន្លែងដែលតេស្តឯកត្តាទៅ ដោយវាបង្កើតមូលដ្ឋានរហ័ស និងទុកទុកដើម្បីឱ្យយុទ្ធសាស្រ្តតេស្តផ្សេងទៀតមានស្ថេរភាព។ -ព្យាង្គការធ្វើតេស្ត +Testing Pyramid -*ព្យាង្គការធ្វើតេស្តបង្ហាញពីតុល្យភាពរវាងការធ្វើតេស្តឯកតា (រហ័ស បែកប្រែកឯកត្តា), ការធ្វើតេស្តរួម (ធាតុពិត), និងការធ្វើតេស្តចុងក្រោយ។ ការបណ្តុះបណ្តាលនេះគ្របដណ្តប់ការធ្វើតេស្តឯកតា។* +*ពិរាម៉ីតតេស្តបង្ហាញពីតុល្យភាពចន្លោះតេស្តឯកត្តា (រហ័ស និងឯកទ្ទឹម), តេស្តបញ្ចូលគ្នា (សមាសភាគពិត), និងតេស្តចប់ដល់បញ្ចប់។ ការបណ្តុះបណ្តាលនេះគ្របដណ្តប់តេស្តឯកត្តា។* -| ម៉ូឌុល | ការធ្វើតេស្ត | ការផ្តោត | ឯកសារសំខាន់ៗ | -|--------|-------------|----------|------------------| -| **00 - ចាប់ផ្តើមយ៉ាងឆាប់រហ័ស** | 6 | គំរូផ្ទាំងបញ្ចូល និងការប្ដូរព័ត៌មានអថេរ | `SimpleQuickStartTest.java` | -| **01 - ការណែនាំ** | 8 | អនុស្សាវរីយ៍ជជែក និងការចាប់ផ្តើមជជែកមានស្ថានភាព | `SimpleConversationTest.java` | -| **02 - វិជ្ជាជីវៈផ្នែកផ្ទាំងបញ្ចូល** | 12 | គំរូ GPT-5.2, កម្រិតប្រាថ្នា, លទ្ធផលមានរចនាសម្ព័ន្ធ | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | ការបញ្ចូលឯកសារ, embedding, ស្វែងរកស្រដៀង | `DocumentServiceTest.java` | -| **04 - ឧបករណ៍** | 12 | ការហៅមុខងារ និងច្រកឧបករណ៍ | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | ព protocol Model Context ព្យាយាមជាមួយការបញ្ជូន stdio | `SimpleMcpTest.java` | +| ម៉ូឌុល | តេស្ត | ការផ្តោតលើ | កាលវិភាគ សំខាន់ៗ | +|--------|-------|--------------|--------------------| +| **01 - ការណែនាំ** | 8 | ការចងចាំការសន្ទនា និងស្ថានភាពការច្រើនបញ្ចូល | `SimpleConversationTest.java` | +| **02 - هندسة الطلبات (Prompt Engineering)** | 12 | លំនាំ GPT-5.2, កម្រិតភាពចង់បាន, លទ្ធផលប្រកបដោយរចនាសម្ព័ន | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | ការច្រោះឯកសារ, embeddings, ស្វែងរកស្រដៀងគ្នា | `DocumentServiceTest.java` | +| **04 - Tools** | 12 | ការហៅមុខងារ និងការចងខ្សែឧបករណ៍ | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol ជាមួយការដឹកជញ្ជូន stdio | `SimpleMcpTest.java` | -## ការរត់ការធ្វើតេស្ត +## របៀបរត់តេស្ត -**រត់ការធ្វើតេស្តទាំងអស់ពីដើម:** +**រត់តេស្តទាំងអស់ពីថតឫស៖** **Bash:** ```bash @@ -63,23 +62,23 @@ mvn test mvn --% test ``` -**រត់ការធ្វើតេស្តសម្រាប់ម៉ូឌុលជាក់លាក់:** +**រត់តេស្តម៉ូឌុលជាក់លាក់៖** **Bash:** ```bash cd 01-introduction && mvn test -# ឬពីរ៉ូត +# ឬពីរួត mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# ឬពី root +# ឬពីរគោល mvn --% test -pl 01-introduction ``` -**រត់ថ្នាក់តេស្តតែមួយ:** +**រត់តេស្តថ្នាក់មួយចំណាត់ថ្នាក់៖** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**រត់វិធីសាស្ត្រធ្វើតេស្តជាក់លាក់:** +**រត់វិធីសាស្រ្តតេស្តជាក់លាក់៖** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#ត្រូវរក្សាប្រវត្តិសន្ទស្សន៍ហេតុផល +mvn test -Dtest=SimpleConversationTest#ត្រូវតែរក្សាប្រវត្តិសន្ទនា ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#គួរតែរក្សាប្រវត្តិការសន្ទនា +mvn --% test -Dtest=SimpleConversationTest#គួរត្រូវរក្សាទុកប្រវត្តិការជជែក ``` -## ការរត់ការធ្វើតេស្តក្នុង VS Code +## របៀបរត់តេស្តក្នុង VS Code -បើអ្នកកំពុងប្រើ Visual Studio Code, Test Explorer ផ្តល់ផ្ទាំងកំហាត់សម្រាប់រត់និងដាក់តំបន់ហាំខូចការធ្វើតេស្ត។ +បើអ្នកប្រើ Visual Studio Code ភាសារតេស្តបង្ហាញផ្ទាំងក្រាហ្វិកសម្រាប់រត់ និងបង្រៀនកំហុសតេស្ត។ VS Code Test Explorer -*VS Code Test Explorer បង្ហាញដើមឈើតេស្តជាមួយថ្នាក់ Java ទាំងអស់ និងវិធីសាស្ត្រធ្វើតេស្តឯកជន* +*Test Explorer នៅ VS Code បង្ហាញខ្សែព្រំតេស្តជាមួយថ្នាក់ Java ទាំងអស់ និងវិធីសាស្រ្តតេស្តនីមួយៗ* -**ដើម្បីរត់ការធ្វើតេស្តក្នុង VS Code៖** +**របៀបរត់តេស្តនៅក្នុង VS Code៖** -1. បើក Test Explorer ដោយចុចរូបតំណាងខាំប៊ើក នៅ Activity Bar -2. វែងឆ្ងាយដើមឈើទីតានឹងឃើញម៉ូឌុលនិងថ្នាក់ធ្វើតេស្តទាំងអស់ -3. ចុចប៊ូតុងលេងពីជាប់ក្បែរ test ដើម្បីរត់វាឯកជន -4. ចុច "Run All Tests" ដើម្បីបំពេញការតេស្តទាំងមូល -5. ស្ដាំប៊ូតុង test មួយណាមួយ ហើយជ្រើស "Debug Test" ដើម្បីដាក់ចំណុចបំបែក និងដើរតាមកូដ +1. បើក Test Explorer ដោយចុចរូបសញ្ញាកែវគ្រឿងក្នុង Activity Bar +2. ពង្រីកខ្សែព្រំតេស្ត ដើម្បីឃើញម៉ូឌុល និងថ្នាក់តេស្តទាំងអស់ +3. ចុចប៊ូតុងលេងនៅក្បែរ តេស្តណាមួយ ដើម្បីរត់វាផ្ទាល់ខ្លួន +4. ចុច “Run All Tests” ដើម្បីអនុវត្តស៊ុមរុំទាំងអស់ +5. ចុចស្ដាំលើតេស្តណាមួយ ហើយជ្រើស “Debug Test” ដើម្បីកំណត់ចំណុចបំបែក ហើយធ្វើជំហានហ្គេហ្វតាមកូដ -Test Explorer បង្ហាញសញ្ញាស្រីនែការពិនិត្យជោគជ័យនិងផ្ដល់សារ​ការខូចលក្ខណៈពិសេសពេលធ្វើតេស្តបរាជ័យ។ +Test Explorer បង្ហាញសញ្ញាឆែកបៃតងសម្រាប់តេស្តជោគជ័យ ហើយផ្ដល់សារ​កំហុស​លំអិត​ពេលមានការបរាជ័យ។ -## គំរូការធ្វើតេស្ត +## រចនាប័ទ្មតេស្ត -### គំរូទី 1៖ ការធ្វើតេស្តគំរូផ្ទាំងបញ្ចូល +### រចនាប័ទ្ម 1៖ តេស្តទាន់គំរូរ Prompt -គំរូសាមញ្ញបំផុតធ្វើតេស្តគំរូផ្ទាំងបញ្ចូលដោយមិនហៅម៉ូដែល AI ទាំងអស់ទេ។ អ្នកត្រួតពិនិត្យថាការប្តូរព័ត៌មានអថេរធ្វើការបំពេញបានត្រឹមត្រូវ និងគំរូមានទ្រង់ទ្រាយត្រឹមត្រូវ។ +រចនាប័ទ្មងាយៗបំផុតគឺតេស្តទាន់គំរូនៃ prompt ដោយមិនហៅម៉ូដែល AI ណាមួយទេ។ អ្នកធ្វើការត្រួតពិនិត្យថាការប្តូរតម្លៃចម្លើយត្រូវបានអនុវត្តបានត្រឹមត្រូវ និងការបង្ហាញ prompt ត្រូវបានបំរែបំរួលតាមលក្ខណៈដែលបានរំពឹងទុក។ -ការធ្វើតេស្តគំរូផ្ទាំងបញ្ចូល +Prompt Template Testing -*ការធ្វើតេស្តគំរូផ្ទាំងបញ្ចូលបង្ហាញលំហូរការប្តូរព័ត៌មានអថេរ៖ គំរូជាមួយចន្លោះ → តម្លៃអនុវត្ត → លទ្ធផលគំរូបានបញ្ជាក់* +*តេស្តទាន់គំរូ prompt បង្ហាញលំហ្វុកាល ប្តូរតម្លៃ៖ គំរូមានកន្លែងទុកតម្លៃ → តម្លៃត្រូវបានដាក់ → ផលបញ្ចេញសម្រេចបានត្រឹមត្រូវ* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -តេស្តនេះស្នាក់នៅក្នុង `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`។ +រចនាប័ទ្មនេះបញ្ចាក់ថាការប្តូរតម្លៃអថេរបានប្រតិបត្តិនៅត្រឹមត្រូវ និង prompt មានរចនាសម្ព័នត្រឹមត្រូវ — មិនត្រូវការខ្សែសោ API ឬការហៅម៉ូដែលឡើយ។ -**រត់វា:** +### រចនាប័ទ្ម 2៖ ពាក់ម៉ូឌែលភាសា (Mocking Language Models) -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#ពិនិត្យមើលការរៀបចំទំរង់គំរូសំណួរ -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#ពិនិត្យមើលការចាក់ប្លង់ទំរង់Prompt -``` - -### គំរូទី 2៖ ការសម្ងោលម៉ូដែលភាសា - -ពេលធ្វើតេស្តនូវលូដឹងជជែក ប្រើ Mockito ដើម្បីបង្កើតម៉ូដែលក្លែងបន្លំ ដែលត្រឡប់ចម្លើយបានកំណត់ជាមុន។ នេះធ្វើឲ្យការធ្វើតេស្តរហ័ស មិនគិតថ្លៃ និងមានលទ្ធផលកំណត់។ +ពេលធ្វើតេស្តตรវិទ្យាសន្ទនា សូមប្រើ Mockito ដើម្បីបង្កើតម៉ូឌែលបន្លំដែលត្រឡប់ចម្លើយដែលបានកំណត់ជាមុន។ វាធ្វើឱ្យតេស្តរហ័ស មិនគិតថ្លៃ និងមានលទ្ធផលមិនបម្លែង។ -ការប្រៀបធៀបរវាងមូក និង API ពិត +Mock vs Real API Comparison -*ការប្រៀបធៀបបង្ហាញមូលហេតុដែលមូកគឺពេញចិត្តសម្រាប់ការធ្វើតេស្ត៖ វារហ័ស មិនគិតថ្លៃ កំណត់លទ្ធផល ហើយមិនត្រូវការកូនសោ API* +*ការប្រៀបធៀបបង្ហាញថា mocks ត្រូវបានពេញចិត្តសម្រាប់ធ្វើតេស្ត ហៅគេថារហ័ស មិនគិតថ្លៃ មានលទ្ធផលមិនបម្លែង និងមិនត្រូវការខ្សែសោ API* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // សារអ្នកប្រើ 3 សារ AI 3 + assertThat(history).hasSize(6); // ៣ សាររបស់អ្នកប្រើ + ៣ សាររបស់អ៊ីធី } } ``` -គំរូនេះវេចខ្ចប់នៅក្នុង `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`។ មូកធានាថាការជួញដូរចំណាំមានភាពជាប់លាប់ ដូច្នេះអ្នកអាចត្រួតពិនិត្យការគ្រប់គ្រងអនុស្សាវរីយ៍បានត្រឹមត្រូវ។ +រចនាប័ទ្មនេះបង្ហាញក្នុង `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`។ Mock ផ្តល់ឱ្យមានអាកប្បកិរិយាដូចគ្នា ដូច្នេះអ្នកអាចពិនិត្យមើលថាការគ្រប់គ្រងចងចាំដំណើរការត្រឹមត្រូវ។ -### គំរូទី 3៖ ការធ្វើតេស្តការរឹតបន្តឹងជជែក +### រចនាប័ទ្ម 3៖ តេស្តការបំបែកសន្ទនា -អនុស្សាវរីយ៍ជជែកត្រូវរក្សាការបំបែកអ្នកប្រើប្រាស់ជាច្រើន។ តេស្តនេះបញ្ជាក់ថាជជែកមិនរួមបញ្ចូលបរិបទគ្នា។ +ចងចាំសន្ទនានឹងត្រូវកាន់តែបំបែកអ្នកប្រើប្រាស់ជាច្រើន។ តេស្តនេះធ្វើការបញ្ជាក់ថាសន្ទនាគ្មានការលាយបញ្ចូលប្រភេទត្រួតពិនិត្យ context។ -ការរឹតបន្តឹងជជែក +Conversation Isolation -*ការធ្វើតេស្តការរឹតបន្តឹងជជែកបង្ហាញផ្ទាំងចងចាំផ្ដាច់ពីរបស់អ្នកប្រើប្រាស់ផ្សេងៗ ដើម្បីការពារមិនអោយបរិបទរួមបញ្ចូលគ្នា* +*តេស្តការបំបែកសន្ទនា បង្ហាញពីការផ្ទុកចងចាំជាច្រើនបំបែកសម្រាប់អ្នកប្រើប្រាស់ផ្សេងៗ ដើម្បីមិនឱ្យមានការលាយ context* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -ជជែកនីមួយៗរក្សាប្រវត្តិសាស្ត្រឯកតាពិបាករបស់ខ្លួន។ នៅប្រព័ន្ធផលិតផល ការរឹតបន្តឹងនេះមានសារៈសំខាន់សម្រាប់កម្មវិធីមនុស្សច្រើន។ +សន្ទនាទីមួយៗរក្សាប្រវត្តិសាស្រ្តឯករាជ្យរបស់ខ្លួន។ ក្នុងប្រព័ន្ធផលិតកម្ម ការបំបែកនេះសំខាន់សម្រាប់កម្មវិធីអ្នកប្រើជាច្រើន។ -### គំរូទី 4៖ ការធ្វើតេស្តឧបករណ៍ដោយឯករាជ្យ +### រចនាប័ទ្ម 4៖ តេស្តឧបករណ៍ដោយឡែក -ឧបករណ៍គឺជាឧបករណ៍ដែល AI អាចហៅបាន។ ធ្វើតេស្តពួកវាត្រូវតែដូចជា វាធ្វើការងារពិតដោយមិនពឹងផ្អែកលើការសម្រេចចិត្ត AI។ +ឧបករណ៍គឺជាមុខងារដែល AI អាចហៅ។ តេស្តវាដោយផ្ទាល់ ដើម្បីធានាថាវាធ្វើការត្រឹមត្រូវដោយមិនគិតពីការសម្រេចចិត្ត AI។ -ការធ្វើតេស្តឧបករណ៍ +Tools Testing -*ការធ្វើតេស្តឧបករណ៍ដោយឯករាជ្យបង្ហាញពីការប្រតិបត្តិមូកឧបករណ៍ដោយគ្មានការហៅ AI ដើម្បីបញ្ជាក់លទ្ធផលអាជីវកម្ម* +*តេស្តឧបករណ៍ដោយឡែក បង្ហាញពីរត់ឧបករណ៍ mock ដោយគ្មានការចូលរួម AI ដើម្បីពិនិត្យលទ្ធផលអាជីវកម្ម* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -ការធ្វើតេស្តទាំងនេះពី `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ផ្ទៀងផ្ទាត់ហេតុផលឧបករណ៍ដោយគ្មានការចូលរួមនៃ AI។ ឧទាហរណ៍ច្រកបង្ហាញរបៀបលទ្ធផលឧបករណ៍មួយចាក់ចូលក្នុងបញ្ចូលរបស់មួយផ្សេងទៀត។ +តេស្តទាំងនេះពី `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` សម្គាល់លទ្ធផលឧបករណ៍ដោយមិនរួមបញ្ចូល AI។ ឧទាហរណ៍ចងខ្សែបង្ហាញពីរបៀបចេញលទ្ធផលឧបករណ៍មួយដល់ការបញ្ចូលឧបករណ៍មួយផ្សេងទៀត។ -### គំរូទី 5៖ ការធ្វើតេស្ត RAG ក្នុងអនុស្សា +### រចនាប័ទ្ម 5៖ តេស្ត RAG In-Memory -ប្រព័ន្ធ RAG ផ្នែកតំណរភាពត្រូវការពិធីការទិន្នន័យហ្គេហ្វ និងសេវាកម្ម embedding។ គំរូអនុស្សាវរីយ៍បន្ថែមឲ្យអ្នកអាចធ្វើតេស្តសមាសភាគទាំងមូលដោយគ្មានការពឹងផ្អែកខាងក្រៅ។ +ប្រព័ន្ធ RAG ជាទូទៅត្រូវការមូលដ្ឋានទិន្នន័យវ៉ិចទ័រ និងសេវាកម្ម embedding។ រៀងរាល់រចនាប័ទ្ម in-memory អនុញ្ញាតឱ្យអ្នកធ្វើតេស្តផ្ទាល់pipelineទាំងមូលដោយគ្មានការពឹងផ្អែកខាងក្រៅ។ -ការធ្វើតេស្ត RAG ក្នុងអនុស្សាវរីយ៍ +In-Memory RAG Testing -*លំហូរការធ្វើតេស្ត RAG ក្នុងអនុស្សាវរីយ៍បង្ហាញការបំបែកឯកសារ, រក្សាទុក embedding និងស្វែងរកស្រដៀងដោយមិនចាំបាច់មុខម៉ូដែលទិន្នន័យ* +*ដំណើរការតេស្ត RAG in-memory បង្ហាញពីការបំបែកឯកសារ, ជំនួយ embedding និងស្វែងរកស្រដៀង គ្មានតម្រូវការមូលដ្ឋានទិន្នន័យ* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -តេស្តនេះពី `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` បង្កើតឯកសារមួយក្នុងអនុស្សាវរីយ៍ ហើយផ្ទៀងផ្ទាត់ការបំបែក និងដំណើរការព័ត៌មាន metadata ។ +តេស្តនេះពី `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` បង្កើតឯកសារនៅក្នុងចងចាំ ហើយពិនិត្យមើលការបំបែកខ្នាត និងការដាក់ទិន្នន័យ meta។ -### គំរូទី 6៖ ការធ្វើតេស្តការរួមបញ្ចូល MCP +### រចនាប័ទ្ម 6៖ តេស្តរួមបញ្ចូល MCP -ម៉ូឌុល MCP ធ្វើតេស្តការរួមបញ្ចូល Model Context Protocol ដោយប្រើការបញ្ជូន stdio។ តេស្តទាំងនេះធានាថាកម្មវិធីរបស់អ្នកអាចបង្កើត និងទំនាក់ទំនងជាមួយម៉ាស៊ីនបម្រើ MCP ក្នុងរូបភាព subprocess។ +ម៉ូឌុល MCP តេស្តការរួមបញ្ចូល Model Context Protocol ដោយប្រើការដឹកជញ្ជូន stdio។ តេស្តទាំងនោះបញ្ជាក់ថាកម្មវិធីរបស់អ្នកអាចបង្កើត និងទំនាក់ទំនងជាមួយម៉ាស៊ីនមេ MCP ជាទម្រង់ subprocess ។ -តេស្តនៅក្នុង `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` ផ្ទៀងផ្ទាត់ឥរិយាបថអតិថិជន MCP។ +តេស្តក្នុង `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` សម្គាល់អាកប្បកិរិយាអតិថិជន MCP។ -**រត់ពួកវា:** +**រត់វា៖** **Bash:** ```bash @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## ទស្សនៈការធ្វើតេស្ត -ធ្វើតេស្តកូដរបស់អ្នក មិនមែន AI ទេ។ ការធ្វើតេស្តរបស់អ្នកគួរតែផ្ទៀងផ្ទាត់កូដដែលអ្នកបានសរសេរ ដោយពិនិត្យថាគំរូត្រូវបានកសាងយ៉ាងដូចម្តេច, គ្រប់គ្រងអនុស្សាវរីយ៍យ៉ាងដូចម្តេច, និងរបៀបដែលឧបករណ៍ដំណើរការ។ ចម្លើយ AI ផ្លាស់ប្តូរហើយមិនគួរត្រូវបានប្រើក្នុងការបញ្ជាក់ការធ្វើតេស្តទេ។ សួរខ្លួនឯងថាគំរូផ្ទាំងបញ្ចូលរបស់អ្នកប្ដូរព័ត៌មានអថេរបានត្រឹមត្រូវឬអត់ មិនមែនថា AI ផ្តល់ចម្លើយត្រូវឬអត់។ +តេស្តកូដរបស់អ្នក មិនមែន AI ទេ។ តេស្តរបស់អ្នកគួរតែបញ្ជាក់ពីកូដដែលអ្នកសរសេរដោយពិនិត្យពីរបៀបកសាង prompt របៀបគ្រប់គ្រងការចងចាំ និងរបៀបអនុវត្តឧបករណ៍។ ប្រតិកម្ម AI ពេញចិត្តធ្វើការប្រែប្រួល ហើយមិនគួរជាផ្នែកនៃការត្រួតពិនិត្យតេស្តទេ។ សួរខ្លួនឯងថាតើទាន់គំរូ prompt របស់អ្នកប្ដូរអថេរបានត្រឹមត្រូវ, មិនមែន AI ទេ។ -ប្រើមូកសម្រាប់ម៉ូដែលភាសា។ ពួកវាជាឧបករណ៍ខាងក្រៅដែលយឺត, ថ្លៃថ្លា, និងមិនកំណត់លទ្ធផល។ ការសម្ងោលធ្វើឲ្យការធ្វើតេស្តរហ័សមានម៉ិលលីវិនាទីជំនួសវិនាទី, មិនគិតថ្លៃដោយគ្មានការចំណាយ API, និងកំណត់លទ្ធផលជាការងារ។ +ប្រើ mocks សម្រាប់ម៉ូឌែលភាសា។ វាធ្វើជាមូលដ្ឋានខាងក្រៅ ដែលយឺត, ខ្លីថ្លៃ, និងមិនមានលទ្ធផលថេរ។ การ mock ធ្វើឲ្យតេស្តរហ័សក្នុងម៉ីលីវិនាទី មិនគិតថ្លៃ និងមានលទ្ធផលដោយមិនផ្លាស់ប្តូរ។ -រក្សាឲ្យការធ្វើតេស្តឯករាជ្យ។ តេស្តនីមួយៗគួរតែបង្កើតទិន្នន័យរបស់ខ្លួន មិនពឹងផ្អែកលើតេស្តផ្សេងទៀត ហើយសម្អាតក្រោយខ្លួន។ តេស្តគួរតែជោគជ័យមិនគិតពីលំដាប់ដំណើរការ។ +រក្សាតេស្តឲ្យដោយឯករាជ្យ។ តេស្តនីមួយៗគួរតែបង្កើតទិន្នន័យរបស់ខ្លួន ដោយមិនពឹងផ្អែកលើតេស្តផ្សេងទៀត និងសម្អាតបន្ទាប់ពីការរត់។ តេស្តគួរតែជោគជ័យដោយមិនគិតពីលំដាប់អនុវត្ត។ -ធ្វើតេស្តករណីជិតមុខលំបាកក្រៅផ្លូវយ៉ាងសប្បាយ។ សាកល្បងការបញ្ចូលទទេ, ទំហំធំ, តួអក្សរពិសេស, ប៉ារ៉ាម៉ែត្រមិនត្រឹមត្រូវ, និងលក្ខខណ្ឌលំបាក។ ពួកវាញឹកញាប់បង្ហាញកំហុសដែលប្រើប្រាស់ធម្មតាមិនបង្ហាញទេ។ +តេស្តករណីស៊ីតគែមៗក្រៅផ្លូវការអំណោយសុភមង្គល។ សាកល្បងបញ្ចូលទិន្នន័យទទេ, ទិន្នន័យធំ, តួអក្សរពិសេស, ប៉ារ៉ាម៉ែត្រខុសប្រក្រតី, និងលក្ខខណ្ឌគែម។ ពួកវាជាប់ឲ្យគ្រប់បញ្ហាដែលប្រើប្រាស់ធម្មតាមិនបង្ហាញ។ -ប្រើឈ្មោះពិពណ៌នា។ ប្រៀបធៀប `shouldMaintainConversationHistoryAcrossMultipleMessages()` ជាមួយ `test1()`។ មួយដំបូងប្រាប់អ្នកយ៉ាងច្បាស់ថាអ្វីកំពុងត្រូវបានធ្វើតេស្ត បង្កើតការដោះសោតកំហុសកាន់តែងាយស្រួល។ +ប្រើឈ្មោះពណ៌នាថ្មីៗ។ ប្រៀបធៀប `shouldMaintainConversationHistoryAcrossMultipleMessages()` ជាមួយ `test1()`។ វាឲ្យដឹងជាក់លាក់ថាអ្វីត្រូវតេស្ត និងធ្វើឱ្យការបកស្រាយកំហុសកាន់តែងាយស្រួល។ ## ជំហានបន្ទាប់ -ឥឡូវលោកអ្នកយល់ពីគំរូការធ្វើតេស្ត បណ្តល់នូវការលើកទឹកចិត្តស្វែងយល់ជ្រាលជ្រៅទៀតនៅក្នុងម៉ូឌុលនីមួយៗ៖ +ឥឡូវនេះដែលអ្នកយល់ពីរចនាប័ទ្មតេស្ត ចូលរៀនជ្រាលជ្រៅក្នុងម៉ូឌុលនីមួយៗ៖ -- **[00 - ចាប់ផ្តើមយ៉ាងឆាប់រហ័ស](../00-quick-start/README.md)** - ចាប់ផ្តើមជាមួយគំរូផ្ទាំងបញ្ចូលមូលដ្ឋាន -- **[01 - ការណែនាំ](../01-introduction/README.md)** - រៀនការគ្រប់គ្រងអនុស្សាវរីយ៍ជជែក -- **[02 - វិជ្ជាជីវៈផ្នែកផ្ទាំងបញ្ចូល](../02-prompt-engineering/README.md)** - ជំនាញគំរូ GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - កសាងប្រព័ន្ធបង្កើនការស្វែងរក -- **[04 - ឧបករណ៍](../04-tools/README.md)** - ដំណើរការហៅមុខងារនិងច្រកឧបករណ៍ +- **[01 - ការណែនាំ](../01-introduction/README.md)** - ធ្វើការគ្រប់គ្រងចងចាំសន្ទនា +- **[02 - هندسة الطلبات (Prompt Engineering)](../02/prompt-engineering/README.md)** - អនុវត្តលំនាំ GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - បង្កើតប្រព័ន្ធបង្កើតឡើងវិញដោយការទាញយក +- **[04 - Tools](../04-tools/README.md)** - អនុវត្តហៅមុខងារ និងខ្សែឧបករណ៍ - **[05 - MCP](../05-mcp/README.md)** - រួមបញ្ចូល Model Context Protocol -README របស់ម៉ូឌុលនីមួយៗផ្តល់នូវការពិពណ៌នាត្រឹមត្រូវពាក់ព័ន្ធនឹងកំណត់ការធ្វើតេស្តនៅទីនេះ។ +README នៃម៉ូឌុលនិមួយៗផ្ដល់ការពន្យល់លម្អិតនៃគំនិតដែលបានតេស្តនៅទីនេះ។ --- -**រុករក៖** [← ថយក្រោយទៅមុខ](../README.md) +**ច្រកចេញ៖** [← ត្រឡប់ទៅមុខវិចិត្រសាល](../README.md) --- -**ការជូនដំណឹង**៖ -ឯកសារនេះត្រូវបានបកប្រែក្នុងជំនួយសេវាកម្មបកប្រែ AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ខណៈពេលដែលយើងខិតខំបំពេញភាពត្រឹមត្រូវ សូមយល់ដឹងថាការបកប្រែដោយស្វ័យប្រវត្តិក្នុងខ្លះអាចមានកំហុស ឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមនៅភាសាទ្រព្យសម្បត្តិរបស់វាគួរត្រូវបានគេយកជាទិដ្ឋភាពផ្លូវការ។ សម្រាប់ព័ត៌មានចំបង ការបកប្រែដោយអ្នកជំនាញមនុស្សត្រូវបានផ្តល់អនុសាសន៍។ យើងមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកប្រែខុសប្លែកណាមួយដែលកើតឡើងពីការប្រើប្រាស់ការបកប្រែនេះទេ។ +**ការបដិសេធ**: +ឯកសារនេះត្រូវបានបម្លែងភាសា ដោយប្រើសេវាបម្លែងភាសា AI [Co-op Translator](https://github.com/Azure/co-op-translator)។ ទោះយើងខ្ញុំមានក្តីប្រាថ្នាឱ្យបានច្បាស់លាស់ តែសូមយល់ដឹងថាការបម្លែងដោយស្វ័យប្រវត្តិក៏អាចមានកំហុសឬភាពមិនត្រឹមត្រូវ។ ឯកសារដើមជាភាសាទីតាំងគួរត្រូវបានគេប្រើជាប្រភពច្បាស់លាស់។ សម្រាប់ព័ត៌មានសំខាន់ៗ សូមណែនាំឱ្យប្រើប្រាស់ការប្រែដោយមនុស្សជំនាញ។ យើងខ្ញុំមិនទទួលខុសត្រូវចំពោះការយល់ច្រឡំ ឬការបកស្រាយខុសបន្ទាប់ពីការប្រើប្រាស់ការបម្លែងនេះនោះទេ។ \ No newline at end of file diff --git a/translations/kn/.co-op-translator.json b/translations/kn/.co-op-translator.json index 004de0e81..d18d46a36 100644 --- a/translations/kn/.co-op-translator.json +++ b/translations/kn/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "kn" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T02:18:49+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T13:00:16+00:00", "source_file": "01-introduction/README.md", "language_code": "kn" }, @@ -18,20 +18,20 @@ "language_code": "kn" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T02:21:47+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T12:47:04+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "kn" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T02:23:54+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T12:59:17+00:00", "source_file": "03-rag/README.md", "language_code": "kn" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:19:21+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T12:53:39+00:00", "source_file": "04-tools/README.md", "language_code": "kn" }, @@ -54,8 +54,8 @@ "language_code": "kn" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:18:22+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T12:41:24+00:00", "source_file": "README.md", "language_code": "kn" }, @@ -72,14 +72,14 @@ "language_code": "kn" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T02:28:39+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T12:47:36+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "kn" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T02:29:37+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T12:52:14+00:00", "source_file": "docs/TESTING.md", "language_code": "kn" } diff --git a/translations/kn/00-quick-start/README.md b/translations/kn/00-quick-start/README.md deleted file mode 100644 index 7a339c0d7..000000000 --- a/translations/kn/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# ಕಾರ್ಯಾಗಾರ 00: ತ್ವರಿತ ಪ್ರಾರಂಭ - -## ವಿಷಯಸೂಚಿ - -- [ಪರಿಚಯ](../../../00-quick-start) -- [ಲ್ಯಾಂಗ್‌ಚೈನ್4j ಎಂದರೆ ಏನು?](../../../00-quick-start) -- [ಲ್ಯಾಂಗ್‌ಚೈನ್4j ಅವಲಂಬನೆಗಳು](../../../00-quick-start) -- [ಪೂರ್ವಾಪೇಕ್ಷಿತಗಳು](../../../00-quick-start) -- [ಸಕ್ರಿಯಗೊಳಿಸುವಿಕೆ](../../../00-quick-start) - - [1. ನಿಮ್ಮ GitHub ಟೋಕನ್ ಪಡೆಯಿರಿ](../../../00-quick-start) - - [2. ನಿಮ್ಮ ಟೋಕನ್ ಸೆಟ್ ಮಾಡಿ](../../../00-quick-start) -- [ಉದಾಹರಣೆಗಳನ್ನು ಚಲಾಯಿಸಿ](../../../00-quick-start) - - [1. ಮೂಲчат್](../../../00-quick-start) - - [2. ಪ್ರಾಂಪ್ಟ್ ವಿನ್ಯಾಸಗಳು](../../../00-quick-start) - - [3. ಫಂಕ್ಷನ್ ಕರೆಮಾಡುವಿಕೆ](../../../00-quick-start) - - [4. ಡಾಕ್ಯುಮೆಂಟ್ ಪ್ರಶ್ನೋತ್ತರ (ಸುಲಭ RAG)](../../../00-quick-start) - - [5. ಜವಾಬ್ದಾರಿಯುತ AI](../../../00-quick-start) -- [ಪ್ರತಿ ಉದಾಹರಣೆ ಏನು ತೋರಿಸುತ್ತದೆ](../../../00-quick-start) -- [ಮುಂದಿನ ಹಂತಗಳು](../../../00-quick-start) -- [ತೊಂದರೆ ಪರಿಹಾರ](../../../00-quick-start) - -## ಪರಿಚಯ - -ಈ ತ್ವರಿತ ಪ್ರಾರಂಭವು LangChain4j ಬಳಸಿ ನಿಮಗೆ ಸಾಧ್ಯವಾದಷ್ಟು ಬೇಗ ಕಾರ್ಯಾರಂಭ ಮಾಡಲು ಉದ್ದೇಶಿಸಲಾಗಿದೆ. ಇದು LangChain4j ಮತ್ತು GitHub ಮಾದರಿಗಳೊಂದಿಗೆ AI ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಸುಲಭವಾಗಿ ರಚಿಸುವ ಮೂಲಭೂತ ವಿಷಯಗಳನ್ನು ಒಳಗೊಂಡಿದೆ. ಮುಂದಿನ ಕಾರ್ಯಾಗಾರಗಳಲ್ಲಿ ನೀವು Azure OpenAI ಮತ್ತು GPT-5.2 ಗೆ ಬದಲಾವಣೆ ಮಾಡಿ ಪ್ರತಿ ಕಲ್ಪನೆಗಳನ್ನು ಆಳವಾಗಿ ಅಧ್ಯಯನ ಮಾಡುತ್ತೀರಿ. - -## ಲ್ಯಾಂಗ್‌ಚೈನ್4j ಎಂದರೆ ಏನು? - -ಲ್ಯಾಂಗ್‌ಚೈನ್4j ಒಂದು ಜಾವಾ ಲೈಬ್ರರಿ ಆಗಿದ್ದು, AI ಚಾಲಿತ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ಮಿಸಲು ಸುಲಭಗೊಳಿಸುತ್ತದೆ. HTTP ಕ್ಲೈಂಟ್‌ಗಳು ಮತ್ತು JSON ಪಾರ್ಸಿಂಗ್ ಕಾರ್ಯಗಳನ್ನು ನಿಭಾಯಿಸುವ ಬದಲಾಗಿ, ನೀವು ಸ್ವಚ್ಛ ಜಾವಾ API ಗಳೊಂದಿಗೆ ಕೆಲಸ ಮಾಡುತ್ತೀರಿ. - -ಲ್ಯಾಂಗ್‌ಚೈನ್‌ನಲ್ಲಿ "ಚೈನ್" ಅಂದರೆ ಅನೇಕ ಘಟಕಗಳನ್ನು ಸರಣಿಯಾಗಿ ಸಂಯೋಜಿಸುವುದು — ನೀವು ಪ್ರಾಂಪ್ಟ್ ಅನ್ನು ಮಾದರಿಗೆ, ಹಾಗು ಅದರಿಂದ ಪಾರ್ಸರ್‌ಗೆ, ಅಥವಾ ಅನೇಕ AI ಕರೆಗಳನ್ನು ಸರಣಿಯಾಗಿ ಸೇರಿಸಬಹುದು, ಅಲ್ಲಿ ಒಂದು ಔಟ್ಪುಟ್ ಮುಂದಿನ ಇನ್‌ಪುಟ್ ಆಗಿ ಬಳಸಲ್ಪಡುತ್ತದೆ. ಈ ತ್ವರಿತ ಪ್ರಾರಂಭ ಮೂಲಭೂತಾಂಶಗಳ ಮೇಲೆ ಕೇಂದ್ರಿತವಾಗಿದೆ, ಮುಂದಕ್ಕೆ ಹೆಚ್ಚು ಸಂಕೀರ್ಣ ಸರಣಿಗಳನ್ನು ಅನ್ವೇಷಿಸುವ ಮೊದಲು. - -LangChain4j Chaining Concept - -*ಲ್ಯಾಂಗ್‌ಚೈನ್4j ನಲ್ಲಿ ಘಟಕಗಳನ್ನು ಸರಣಿಪಡಿಸುವುದು - ಶಕ್ತಿಶಾಲಿ AI ಕಾರ್ಯಪ್ರವಾಹಗಳನ್ನು ನಿರ್ಮಿಸುವ ಕಟ್ಟಡ ಬ್ಲಾಕ್ಗಳು* - -ನಾವು ಮೂರು ಪ್ರಮುಖ ಘಟಕಗಳನ್ನು ಬಳಸುತ್ತೇವೆ: - -**ChatModel** - AI ಮಾದರಿಯ ಜೊತೆಗೆ ಸಂವಹನ ಮಾಡುವ ಅಂತರಮುಖ. `model.chat("prompt")` ಅನ್ನು ಕರೆಸಿ ಉತ್ತರ ಸರಣಿಯನ್ನು ಪಡೆಯಿರಿ. ನಾವು `OpenAiOfficialChatModel` ಅನ್ನು ಬಳಸುತ್ತೇವೆ ಅದು GitHub Models ಹಾಗು OpenAI-ಅನುಕೂಲ ಎಂಡ್‌ಪಾಯಿಂಟ್‌ಗಳೊಂದಿಗೆ ಕೆಲಸ ಮಾಡುತ್ತದೆ. - -**AiServices** - ಪ್ರಕಾರ-ಸುರಕ್ಷಿತ AI ಸೇವಾ ಅಂತರಮುಖಗಳನ್ನು ಸೃಷ್ಟಿಸುತ್ತದೆ. ವಿಧಾನಗಳನ್ನು ವ್ಯಾಖ್ಯಾನಿಸಿ, ಅವುಗಳನ್ನು `@Tool` ಅನೋಟೇಷನ್ ಮಾಡಿ, ಮತ್ತು LangChain4j ಇವುಗಳ ನಿರ್ವಹಣೆಯನ್ನು ಮಾಡುತ್ತದೆ. AI ಅಗತ್ಯವಿದ್ದಾಗ ನಿಮ್ಮ ಜಾವಾ ವಿಧಾನಗಳನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಕರೆ ಮಾಡುತ್ತದೆ. - -**MessageWindowChatMemory** - ಮಾತುಕತೆಯ ಇತಿಹಾಸವನ್ನು ನಿರ್ವಹಿಸುತ್ತದೆ. ಇದಿಲ್ಲದೆ ಪ್ರತಿ ವಿನಂತಿ ಸ್ವತಂತ್ರವಾಗಿರುತ್ತದೆ. ಇದಿರುವಾಗ, AI ಹಿಂದಿನ ಸಂದೇಶಗಳನ್ನು ನೆನಪಿಡುತ್ತದೆ ಮತ್ತು ಹಲವಾರು ಹಂತಗಳಲ್ಲಿ ಸಂದರ್ಭ ನಿರ್ವಹಣೆ ಮಾಡುತ್ತದೆ. - -LangChain4j Architecture - -*ಲ್ಯಾಂಗ್‌ಚೈನ್4j ಸ್ಥಾಪನೆ - ಕೋರ್ ಘಟಕಗಳು ಸೇರಿ ನಿಮ್ಮ AI ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಚಾಲನೆ ನೀಡುತ್ತವೆ* - -## ಲ್ಯಾಂಗ್‌ಚೈನ್4j ಅವಲಂಬನೆಗಳು - -ಈ ತ್ವರಿತ ಪ್ರಾರಂಭವು [`pom.xml`](../../../00-quick-start/pom.xml) ನಲ್ಲಿ ಮೂರು Maven ಅವಲಂಬನೆಗಳನ್ನು ಉಪಯೋಗಿಸುತ್ತದೆ: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` ಘಟಕವು `OpenAiOfficialChatModel` ಕ್ಲಾಸ್ ಅನ್ನು ಒದಗಿಸುತ್ತದೆ ಅದು OpenAI-ಅನುಕೂಲ API ಗಳಿಗೆ ಸಂಪರ್ಕ ಮಾಡುತ್ತದೆ. GitHub Models ಅದೇ API ಸ್ವರೂಪವನ್ನು ಬಳಸುತ್ತದೆ, ಆದ್ದರಿಂದ ವಿಶೇಷ ಅಡಾಪ್ಟರ್ ಅಗತ್ಯವಿಲ್ಲ - ಕೇವಲ ಮೂಲ URL ಅನ್ನು `https://models.github.ai/inference` ಗೆ ಸೂಚಿಸಿ. - -`langchain4j-easy-rag` ಘಟಕವು ಸ್ವಯಂಚಾಲಿತ ಡಾಕ್ಯುಮೆಂಟ್ ವಿಭಜನೆ, ಎम्बೆಡಿಂಗ್ ಮತ್ತು ಹುಡುಕಾಟ ವ್ಯವಸ್ಥೆಯನ್ನು ಒದಗಿಸುತ್ತದೆ, ಇದರಿಂದ ನೀವು RAG ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಕೈೆಯಿಂದ ಪ್ರತಿ ಹಂತವನ್ನು ಸಂರಚಿಸುವ ಅಗತ್ಯವಿಲ್ಲದೆ ನಿರ್ಮಿಸಬಹುದು. - -## ಪೂರ್ವಾಪೇಕ್ಷಿತಗಳು - -**ಡೆವ್ ಕಂಟೈನರ್ ಬಳಸಿ ಸಂತೋೕಷ?** ಜಯ ಮತ್ತು ಮೆವನ್ ಈಗಾಗಲೇ ಪ್ರತಿಷ್ಠಾಪಿಸಲಾಗಿದೆ. ನಿಮಗೆ ಕೇವಲ GitHub ವೈಯಕ್ತಿಕ ಪ್ರವೇಶ ಟೋಕನ್ ಬೇಕು. - -**ಸ್ಥಳೀಯ ಅಭಿವೃದ್ಧಿ:** -- ಜಾವಾ 21+, ಮೆವನ್ 3.9+ -- GitHub ವೈಯಕ್ತಿಕ ಪ್ರವೇಶ ಟೋಕನ್ (ನೀಡಲಾದ ಸೂಚನೆಗಳು ಕೆಳಗಿನಂತಿವೆ) - -> **ಗಮನಿಸಿ:** ಈ ಕಾರ್ಯಾಗಾರವು GitHub Models ರಿಂದ `gpt-4.1-nano` ಬಳಕೆ ಮಾಡುತ್ತದೆ. ಕೋಡ್‌ನಲ್ಲಿ ಮಾದರಿಯ ಹೆಸರನ್ನು ಬದಲಾಯಿಸಬೇಡಿ - ಇದು GitHub ಲಭ್ಯವಿರುವ ಮಾದರಿಗಳೊಂದಿಗೆ ಕೆಲಸ ಮಾಡಲು ಸಂರಚಿಸಲಾಗಿದೆ. - -## ಸಕ್ರಿಯಗೊಳಿಸುವಿಕೆ - -### 1. ನಿಮ್ಮ GitHub ಟೋಕನ್ ಪಡೆದುಕೊಳ್ಳಿ - -1. [GitHub ಸೆಟ್ಟಿಂಗ್ಸ್ → ವೈಯಕ್ತಿಕ ಪ್ರವೇಶ ಟೋಕನ್‌ಗಳು](https://github.com/settings/personal-access-tokens) ಗೆ ಹೋಗಿ -2. "ಹೊಸ ಟೋಕನ್ ಹುಟ್ಟುಹಾಕಿ" ಕ್ಲಿಕ್ ಮಾಡಿ -3. ವಿವರಣೆಾತ್ಮಕ ಹೆಸರು ನೀಡಿ (ಉದಾ: "LangChain4j ಡೆಮೊ") -4. ಅವಧಿ ನಿರ್ಧರಿಸಿ (7 ದಿನ ಶಿಫಾರಸು ಮಾಡಲಾಗಿದೆ) -5. "ಖಾತೆ ಅನುಮತಿಗಳು" ಅಡಿ "ಮಾದರಿಗಳು (Models)" ಅನ್ನು "ಓದಲು ಮಾತ್ರ (Read-only)" ಗೆ ಸೆಟ್ ಮಾಡಿ -6. "ಟೋಕನ್ ಸೃಷ್ಟಿಸಿ" ಕ್ಲಿಕ್ ಮಾಡಿ -7. ನಿಮ್ಮ ಟೋಕನ್ ಅನ್ನು ನಕಲಿಸಿ ಮತ್ತು ಸುರಕ್ಷಿತವಾಗಿ ಉಳಿಸಿ - ಇದು ಮರುಪಡೆಯಲು ಸಾಧ್ಯವಿಲ್ಲ - -### 2. ನಿಮ್ಮ ಟೋಕನ್ ಸೆಟ್ ಮಾಡಿ - -**ಆಯ್ಕೆ 1: VS ಕೋಡ್ ಬಳಸಿ (ಶಿಫಾರಸು ಮಾಡಲಾಗಿದೆ)** - -ನೀವು VS ಕೋಡ್ ಬಳಸಿ ಇದ್ದರೆ, ನಿಮ್ಮ ಟೋಕನ್ ಅನ್ನು ಯೋಜನೆಯ ರೂಟ್‌ನಲ್ಲಿರುವ `.env` ಫೈಲ್‌ಗೆ ಸೇರಿಸಿ: - -`.env` ಫೈಲ್ ಇಲ್ಲದಿದ್ದರೆ, `.env.example` ನಕಲು ಮಾಡಿ `.env` ಎಂದು ಹೆಸರು ಹಾಕಿ ಅಥವಾ ಹೊಸ `.env` ಫೈಲ್ ತಯಾರಿಸಿ. - -**ಉದಾಹರಣೆಯ `.env` ಫೈಲ್:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env ನಲ್ಲಿ -GITHUB_TOKEN=your_token_here -``` - -ನಂತರ, ಎಕ್ಸ್‌ಪ್ಲೋರರ್‌ನಲ್ಲಿ ಯಾವುದೇ ಡೆಮೊ ಫೈಲ್ (ಉದಾ: `BasicChatDemo.java`) ಮೇಲೆ ರೈಟ್-ಕ್ಲಿಕ್ ಮಾಡಿ **"Run Java"** ಆಯ್ಕೆಮಾಡಿ ಅಥವಾ ಓಡುತ್ತಿರುವ ಮತ್ತು ಡಿಬಗ್ ಪ್ಯಾನೆಲ್‌ನ ಲಾಂಚ್ ಕಾನ್ಫಿಗರೇಷನ್‌ಗಳನ್ನು ಉಪಯೋಗಿಸಿ. - -**ಆಯ್ಕೆ 2: ಟರ್ಮಿನಲ್ ಬಳಸಿ** - -ಟೋಕನ್ ಅನ್ನು ಪರಿಸರ ಚರ (environment variable) ಆಗಿ ಸೆಟ್ ಮಾಡಿ: - -**ಬ್ಯಾಶ್:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**ಪವರ್‌ಶೆಲ್:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## ಉದಾಹರಣೆಗಳನ್ನು ಚಲಾಯಿಸಿ - -**VS ಕೋಡ್ ಬಳಸಿ:** ಯಾವುದೇ ಡೆಮೊ ಫೈಲ್ ಮೇಲೆ ರೈಟ್-ಕ್ಲಿಕ್ ಮಾಡಿ **"Run Java"** ಆಯ್ಕೆಮಾಡಿ, ಅಥವಾ ಓಡಿಸುವ ಮತ್ತು ಡಿಬಗ್ ಪ್ಯಾನೆಲ್‌ನ ಲಾಂಚ್ ಕಾನ್ಫಿಗರೇಷನ್ ಉಪಯೋಗಿಸಿ (ನಿಮ್ಮ ಟೋಕನ್ `.env` ಫೈಲಿನಲ್ಲಿ ಸೇರಿಸಿರುವುದನ್ನು ಖಾತ್ರಿ ಪಡಿಸಿಕೊಳ್ಳಿ). - -**ಮೆವನ್ ಬಳಸಿ:** ಮುಂತಾದಂತೆ, ಕಮಾಂಡ್ ಲೈನಿಂದ ಆಗಬಹುದು: - -### 1. ಮೂಲчат್ - -**ಬ್ಯಾಶ್:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**ಪವರ್‌ಶೆಲ್:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. ಪ್ರಾಂಪ್ಟ್ ವಿನ್ಯಾಸಗಳು - -**ಬ್ಯಾಶ್:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**ಪವರ್‌ಶೆಲ್:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -ಶೂನ್ಯ-ಶಾಟ್, ಕೆಲವು-ಶಾಟ್, ಚೈನ್-ಆಫ್-ಥಾಟ್ ಮತ್ತು ಪಾತ್ರಾಧಾರಿತ ಪ್ರಾಂಪ್ಟ್ ಅನ್ನು ತೋರಿಸುತ್ತದೆ. - -### 3. ಫಂಕ್ಷನ್ ಕರೆಮಾಡುವಿಕೆ - -**ಬ್ಯಾಶ್:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**ಪವರ್‌ಶೆಲ್:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI ಬೇಕಾದಾಗ ನಿಮ್ಮ ಜಾವಾ ವಿಧಾನಗಳನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಕರೆ ಮಾಡುತ್ತದೆ. - -### 4. ಡಾಕ್ಯುಮೆಂಟ್ ಪ್ರಶ್ನೋತ್ತರ (ಸುಲಭ RAG) - -**ಬ್ಯಾಶ್:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**ಪವರ್‌ಶೆಲ್:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -ಸ್ವಯಂಚಾಲಿತ ಎಂಬೆಡಿಂಗ್ ಮತ್ತು ಹುಡುಕಾಟದೊಂದಿಗೆ ಸುಲಭ RAG ಉಪಯೋಗಿಸಿ ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟ್ಗಳ ಬಗ್ಗೆ ಪ್ರಶ್ನೆಗಳು ಕೇಳಿ. - -### 5. ಜವಾಬ್ದಾರಿಯುತ AI - -**ಬ್ಯಾಶ್:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**ಪವರ್‌ಶೆಲ್:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -AI ಸುರಕ್ಷತಾ ಫಿಲ್ಟರ್‌ಗಳು ಹಾನಿಕಾರಕ ವಿಷಯಗಳನ್ನು ಹೇಗೆ ತಡೆಹಿಡಿಯುತ್ತವೆ ಎಂದು ನೋಡಿ. - -## ಪ್ರತಿ ಉದಾಹರಣೆ ಏನು ತೋರಿಸುತ್ತದೆ - -**ಮೂಲчат್** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -ಇಲ್ಲಿ LangChain4j ಅನ್ನು ಅತ್ಯಂತ ಸರಳವಾಗಿ ನೋಡಬಹುದು. ನೀವು `OpenAiOfficialChatModel` ರಚಿಸಿ, `.chat()` ಮೂಲಕ ಪ್ರಾಂಪ್ಟ್ ಕಳುಹಿಸಿ ಮತ್ತು ಪ್ರತಿಕ್ರಿಯೆ ಪಡೆಯುತ್ತೀರಿ. ಇದು ಆಧಾರವನ್ನು ತೋರಿಸುತ್ತದೆ: ಕಸ್ಟಮ್ ಎಂಡ್‌ಪಾಯಿಂಟ್ ಹಾಗೂ API ಕೀಲಿಗಳೊಂದಿಗೆ ಮಾದರಿಗಳನ್ನು ಪ್ರಾರಂಭಿಸುವುದು ಹೇಗೆ ಎಂಬುದು. ಈ ಮಾದರಿಯನ್ನು ಅರ್ಜಿ ಮಾಡುವ ಮೂಲಕ ಎಲ್ಲವನ್ನೂ ನಿರ್ಮಿಸಲಾಗುತ್ತದೆ. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 GitHub Copilot ಮೂಲಕ ಪ್ರಯತ್ನಿಸಿ:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: -> - "GitHub Models ನಿಂದ Azure OpenAI ಗೆ ಈ ಕೋಡ್‌ನಲ್ಲಿ ನಾನು ಹೇಗೆ ಬದಲಾಯಿಸಬಹುದು?" -> - "OpenAiOfficialChatModel.builder() ನಲ್ಲಿ ಇನ್ನೇನು ನಿಯಮಗಳನ್ನು ನಾನು ಸಂರಚಿಸಬಹುದು?" -> - "ಪೂರ್ಣ ಪ್ರತಿಕ್ರಿಯೆ ಬರುವೆಯೆಂದು ಕಾಯದೆ ಸ್ಟ್ರೀಮಿಂಗ್ ಪ್ರತಿಕ್ರಿಯೆಗಳನ್ನು ನಾನು ಹೇಗೆ ಸೇರಿಸಬಹುದು?" - -**ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -ನೀವು ಈಗ ಮಾದರಿಯನ್ನು ಹೇಗೆ ಮಾತನಾಡಿಸುವುದು ತಿಳಿದಿದ್ದಾರೆ, ಅದಕ್ಕೆ ನೀವು ಏನು ಹೇಳುತ್ತೀರಿ ಎಂಬುದನ್ನು ಅನ್ವೇಷಿಸೋಣ. ಈ ಡೆಮೊ ಅದೇ ಮಾದರಿ ರಚನೆಯನ್ನು ಉಪಯೋಗಿಸಿ ಐದು ವಿಭಿನ್ನ ಪ್ರಾಂಪ್ಟ್ ವಿನ್ಯಾಸಗಳನ್ನು ತೋರಿಸುತ್ತದೆ. ನೇರ ನಿರ್ದೇಶನಗಳಿಗಾಗಿ ಶೂನ್ಯ-ಶಾಟ್ ಪ್ರಾಂಪ್ಟ್‌ಗಳು, ಉದಾಹರಣೆಗಳಿಂದ ಕಲಿಯುವ ಪಿಗ್ಗೆ-ಶಾಟ್, ಚಿಂತನೆ ಸರಣಿಯನ್ನು ಹಂಚುವ ಚೈನ್-ಆಫ್-ಥಾಟ್, ಮತ್ತು ಸನ್ನಿವೇಶವನ್ನು ಸೆಟ್ ಮಾಡುವ ಪಾತ್ರಾಧಾರಿತ ಪ್ರಾಂಪ್ಟ್ ಗಳನ್ನು ಪ್ರಯತ್ನಿಸಿ. ನೀವು ಭಿನ್ನವಾಗಿ ವಿನ್ಯಾಸಗೊಳಿಸಿದ ಪ್ರಾಂಪ್ಟ್ ಆಧಾರಿತ ಪರಿಣಾಮಗಳನ್ನು ನೋಡುತ್ತೀರಿ. - -ಡೆಮೊ ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೆಟ್‌ಗಳೂ ತೋರಿಸುತ್ತದೆ, ಅವು ಮರುಬಳಕೆ ಮಾಡಬಹುದಾದ ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ವೇರಿಯಬಲ್ಗಳೊಂದಿಗೆ ರಚಿಸುವ ಶಕ್ತಿಶಾಲಿ ವಿಧಾನವಾಗಿದೆ. -ಕೆಳಗಿನ ಉದಾಹರಣೆ LangChain4j `PromptTemplate` ಬಳಸಿಕೊಂಡು ವೇರಿಯಬಲ್ಗಳನ್ನು ತುಂಬುವ ಪ್ರಾಂಪ್ಟ್ ಅನ್ನು ತೋರಿಸುತ್ತದೆ. AI ಕೊಟ್ಟಿರುವ ಗಮ್ಯಸ್ಥಾನ ಮತ್ತು ಚಟುವಟಿಕೆಯ ಆಧಾರದ ಮೇಲೆ ಉತ್ತರಿಸುತ್ತದೆ. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 GitHub Copilot ಮೂಲಕ ಪ್ರಯತ್ನಿಸಿ:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: -> - "ಶೂನ್ಯ-ಶಾಟ್ ಮತ್ತು ಕೆಲವು-ಶಾಟ್ ಪ್ರಾಂಪ್ಟ್ ಮಧ್ಯೆ ವ್ಯತ್ಯಾಸ ಏನು ಮತ್ತು ಯಾವಾಗ ಯಾವದನ್ನು ಬಳಸಬೇಕು?" -> - "ತಾಪಮಾನ ನಿಯಮವು ಮಾದರಿಯ ಪ್ರತಿಕ್ರಿಯೆಗಳನ್ನು ಹೇಗೆ ಪ್ರಭಾವಿಸುತ್ತದೆ?" -> - "ಉತ್ಪಾದನೆಯಲ್ಲಿ ಪ್ರಾಂಪ್ಟ್ ಇಂಜೆಕ್ಷನ್ ದಾಳಿ ತಡೆಯಲು ಯಾವುದೇ ತಂತ್ರಗಳನ್ನು ನಾನು ಬಳಸಬಹುದು?" -> - "ಸಾಮಾನ್ಯ ವಿನ್ಯಾಸಗಳಿಗಾಗಿ ಮರುಬಳಕೆ ಮಾಡಬಹುದಾದ PromptTemplate ವಸ್ತುಗಳನ್ನು ಹೇಗೆ ಸೃಷ್ಟಿಸಬಹುದು?" - -**ಸಾಧನ ಸಂಯೋಜನೆ** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -ಇಲ್ಲಿ LangChain4j ಶಕ್ತಿಶಾಲಿಯಾಗುತ್ತದೆ. ನೀವು `AiServices` ಬಳಸಿ ಒಂದು AI ಸಹಾಯಕೆಯನ್ನು ಬರೆದು ನಿಮ್ಮ ಜಾವಾ ವಿಧಾನಗಳನ್ನು ಕರೆಯಬಹುದು. ವಿಧಾನಗಳನ್ನು `@Tool("ವಿವರಣೆ")` ಜೊತೆಗೆ ಅನೋಟೇಟ್ ಮಾಡಿ, ಲ್ಯಾಂಗ್‌ಚೈನ್4j ಇತರ ಎಲ್ಲ ನಿರ್ವಹಣೆ ಮಾಡುತ್ತದೆ - AI ಬಳಕೆದಾರ ಕೇಳುವ ಪ್ರಕಾರ ಯಾವ ಸಾಧನೆಯನ್ನು ಬಳಕೆ ಮಾಡಬೇಕೆಂದು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ನಿರ್ಧರಿಸುತ್ತದೆ. ಇದು ಫಂಕ್ಷನ್ ಕರೆಮಾಡುವಿಕೆಯ ಮಹತ್ವದ ತಂತ್ರವನ್ನು ತೋರಿಸುತ್ತದೆ, ಅದು AI ಯನ್ನು ಜವಾಬ್ದಾರಿಗಳೊಂದಿಗೆ ಕ್ರಮಗಳನ್ನು ಕೈಗೊಳ್ಳಲು ಸಾಧ್ಯವಾಗಿಸುತ್ತದೆ. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 GitHub Copilot ಮೂಲಕ ಪ್ರಯತ್ನಿಸಿ:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: -> - "@Tool ಅನೋಟೇಷನ್ ಹೇಗೆ ಕೆಲಸ ಮಾಡುತ್ತದೆ ಮತ್ತು ಲ್ಯಾಂಗ್‌ಚೈನ್4j ಅದನ್ನು ಹಿಂದೆ ಹೇಗೆ ನಿರ್ವಹಿಸುತ್ತದೆ?" -> - "ಸಂಯೋಜಿತ ಸಮಸ್ಯೆಗಳನ್ನು ಪರಿಹರಿಸಲು AI ಅನೇಕ ಸಾಧನಗಳನ್ನು क्रमವಾಗಿ ಕರೆ ಮಾಡಬಹುದೇ?" -> - "ಒಂದು ಸಾಧನದಲ್ಲಿ ತಪ್ಪು ಉಂಟಾದರೆ ನಾನು ಹೇಗೆ ದೋಷಗಳನ್ನು ಹ್ಯಾಂಡಲ್ ಮಾಡಬೇಕು?" -> - "ಈ ಕ್ಯಾಲ್ಕ್ಯುಲೇಟರ್ ಉದಾಹರಣೆಯ ಬದಲು ನಿಜವಾದ API ಅನ್ನು ನಾನು ಹೇಗೆ ಸಂಯೋಜಿಸಬಹುದು?" - -**ಡಾಕ್ಯುಮೆಂಟ್ ಪ್ರಶ್ನೋತ್ತರ (ಸುಲಭ RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -ಇಲ್ಲಿ ನೀವು LangChain4j ನ "ಸುಲಭ RAG" ವಿಧಾನದಿಂದ RAG (ರಿಟ್ರಿವಲ್-ಆಗ್ಮೆಂಟೆಡ್ ಜನರೇಶನ್) ನೋಡುತ್ತೀರಿ. ಡಾಕ್ಯುಮೆಂಟ್ಗಳು ಲೋಡ್ ಆಗಿ, ಸ್ವಯಂಚಾಲಿತವಾಗಿ ವಿಭಜನೆ ಮಾಡಲ್ಪಡಿ, ಮೆಮರಿ ಆಧಾರಿತ ಸ್ಟೋರ್‌ಗೆ ಎम्बೆಡ್ ಆಗುತ್ತವೆ, ನಂತರ ವಿಷಯ ಪೂರೈಸುವ ಯಂತ್ರವು AI ಗೆ ಸಂಬಂಧಿಸಿದ ಭಾಗಗಳನ್ನು ಪ್ರಶ್ನೆ ಸಮಯದಲ್ಲಿ ಒದಗಿಸುತ್ತದೆ. AI ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳ ಆಧಾರದ ಮೇಲೆ ಉತ್ತರಿಸುತ್ತದೆ, ಅದರ ಸಾಮಾನ್ಯ ಜ್ಞಾನ ಅಲ್ಲ. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 GitHub Copilot ಮೂಲಕ ಪ್ರಯತ್ನಿಸಿ:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: -> - "RAG AI ಹಲ್ಲಿನ ನಿಯಂತ್ರಣವನ್ನು ಮಾದರಿಯ ತರಬೇತಿ ದತ್ತಾಂಶದ ಬಳಕೆಯಿಂದ ಹೇಗೆ ತಡೆಯುತ್ತದೆ?" -> - "ಈ ಸುಲಭ ವಿಧಾನ ಮತ್ತು ಕಸ್ಟಮ್ RAG ಪೈಪ್‌ಲೈನ್ ಮಧ್ಯೆ ವ್ಯತ್ಯಾಸವೇನು?" -> - "ಹಲವಾರು ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳು ಅಥವಾ ದೊಡ್ಡ ಜ್ಞಾನ ಆಧಾರಗಳನ್ನು ನಾನು ಹೇಗೆ ತಡೆತಿರುಗಿಸುವೆ?" - -**ಜವಾಬ್ದಾರಿಯುತ AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -ಆಳವಾದ ರಕ್ಷಣೆಯೊಂದಿಗೆ AI ಸುರಕ್ಷತೆ ನಿರ್ಮಿಸಿ. ಈ ಡೆಮೊ ಎರಡು ಅವರಣೆಗಳನ್ನು ಒಟ್ಟಿಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ: - -**ಭಾಗ 1: LangChain4j ಇನ್‌ಪುಟ್ ಗಾರ್ಡ್‌ರೈಲುಗಳು** - ಅಪಾಯಕಾರಿ ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು LLM ಗೆ ತಲುಪುವ ಮೊದಲು ತಡೆಯುತ್ತವೆ. ನಿಷಿದ್ಧಕೀಲಿಕೋಶಗಳು ಅಥವಾ ವಿನ್ಯಾಸಗಳಿಗೆ ತಕ್ಕಂತೆ ಕಸ್ಟಮ್ ಗಾರ್ಡ್‌ರೈಲುಗಳನ್ನು ರಚಿಸಿ. ಇವು ನಿಮ್ಮ ಕೋಡಿನಲ್ಲಿ ಕಾರ್ಯನಿರ್ವಹಿಸುವುದರಿಂದ ವೇಗವಾಗಿ ಮತ್ತು ಉಚಿತ. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**ಭಾಗ 2: ಪ್ರೊವೈಡರ್ ಸುರಕ್ಷತಾ ಫಿಲ್ಟರ್‌ಗಳು** - GitHub Models ನಲ್ಲಿರುವ ಸ್ಥಿರ ಫಿಲ್ಟರ್‌ಗಳು ನಿಮ್ಮ ಗಾರ್ಡ್‌ರೈಲುಗಳು ತಪ್ಪುವುದು ಹಿಡಿಯುತ್ತವೆ. ಗಂಭೀರ ಉಲ್ಲಂಘನೆಗಳಿಗೆ ಹಾರ್ಡ್ ಬ್ಲಾಕ್‌ಗಳು (HTTP 400 ದೋಷಗಳು) ಮತ್ತು ಸಾಫ್ಟ್ ನಿರಾಕರಣೆಗಳಿವೆ, ಅಂದರೆ AI ವಿನಮ್ರವಾಗಿ ತಿರಸ್ಕರಿಸುತ್ತದೆ. - -> **🤖 GitHub Copilot ಮೂಲಕ ಪ್ರಯತ್ನಿಸಿ:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: -> - "InputGuardrail ಅಂದರೇನು ಮತ್ತು ನಾನು ನನ್ನದೇನನ್ನು ಹೇಗೆ ರಚಿಸಬಹುದು?" -> - "ಹಾರ್ಡ್ ಬ್ಲಾಕ್ ಮತ್ತು ಸಾಫ್ಟ್ ನಿರಾಕರಣೆಯ ವ್ಯತ್ಯಾಸವೇನು?" -> - "ಗೂಡಾಗಿ ಮತ್ತು ಪ್ರೊವೈಡರ್ ಫಿಲ್ಟರ್‌ಗಳನ್ನು ಒಟ್ಟಿಗೆ ಬಳಸудың ಪ್ರಯೋಜನವೇನು?" - -## ಮುಂದಿನ ಹಂತಗಳು - -**ಮುಂದಿನ ಕಾರ್ಯಾಗಾರ:** [01-ಪರಿಚಯ - LangChain4j ಜೊತೆ ಆರಂಭಿಸುವುದು](../01-introduction/README.md) - ---- - -**ನವಿಗೆಶನ್:** [← ಮುಖ್ಯಕ್ಕೆ ಹಿಂದಿರುಗಿ](../README.md) | [ಮುಂದಿನ: ಕಾರ್ಯಾಗಾರ 01 - ಪರಿಚಯ →](../01-introduction/README.md) - ---- - -## ತೊಂದರೆ ಪರಿಹಾರ - -### ಮೊದಲ ಬಾರಿಗೆ ಮೆವನ್ ಬಿಲ್ಡ್ - -**ಸಮಸ್ಯೆ:** ಆರಂಭಿಕ `mvn clean compile` ಅಥವಾ `mvn package` ಬಹಳ ಸಮಯ ತೆಗೆದುಕೊಳ್ಳುತ್ತದೆ (10-15 ನಿಮಿಷಗಳು) - -**ಕಾರಣ:** ಮೆವನ್ ಮೊದಲ ಬಾರಿಗೆ ಎಲ್ಲಾ ಪ್ರಾಜೆಕ್ಟ್ ಅವಲಂಬನೆಗಳನ್ನು (Spring Boot, LangChain4j ಲೈಬ್ರರಿಗಳು, Azure SDK ಗಳು ಇತ್ಯಾದಿ) ಡೌನ್‌ಲೋಡ್ ಮಾಡಬೇಕಾಗಿದೆ. - -**ಉಪಾಯ:** ಇದು ಸಾಮಾನ್ಯ ವರ್ತನೆ. ಮುಂದಿನ ಬಿಲ್ಡ್‌ಗಳು ಸ್ಥಳೀಯವಾಗಿ ಕ್ಯಾಶ್ ಆಗಿರುವುದರಿಂದ ವೇಗವಾಗಿ ನಡೆಯುತ್ತವೆ. ಡೌನ್‌ಲೋಡ್ ಸಮಯ ನಿಮ್ಮ ನೆಟ್‌ವರ್ಕ್ ವೇಗದ ಮೇಲೆ ಆಧಾರಿತವಾಗಿರುತ್ತದೆ. - -### ಪವರ್‌ಶೆಲ್ ಮೆವನ್ ಕಮಾಂಡ್ ವ್ಯಾಕರಣ - -**ಸಮಸ್ಯೆ:** ಮೆವನ್ ಕಮಾಂಡ್‌ಗಳು `Unknown lifecycle phase ".mainClass=..."` ದೋಷದೊಂದಿಗೆ ವಿಫಲವಾಗುತ್ತವೆ -**ಕಾರಣ**: PowerShell `=` ಅನ್ನು ವೈಯರಿಯಬಲ್ ನಿಯೋಜನೆ ಅಪರೇಟರ್ ಎಂದು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುತ್ತದೆ, ಇದು Maven ಪ್ರಾಪರ್ಟಿ ಸಿಂಟ್ಯಾಕ್ಸ್ ಅನ್ನು ಮುರಿಯುತ್ತದೆ - -**ಪರಿಹಾರ**: Maven ಆಜ್ಞೆಯ ಮೊದಲು ಸ್ಟಾಪ್-पಾರ್ಸಿಂಗ್ ಅಪರೇಟರ್ `--%` ಬಳಸಿ: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` ಅಪರೇಟರ್ PowerShell ಗೆ ಉಳಿದ ಎಲ್ಲಾ ಆರ್ಗ್ಯುಮೆಂಟ್ಸ್ ಅನ್ನು Maven ಗೆ ಅರ್ಥಮಾಡಿಕೊಳ್ಳದೆ ನೇರವಾಗಿ ಪಾಸ್ ಮಾಡುವಂತೆ ಹೇಳುತ್ತದೆ. - -### Windows PowerShell Emoji ಪ್ರದರ್ಶನ - -**ಸಮಸ್ಯೆ**: PowerShell ನಲ್ಲಿ ಇಮೋಜಿಗಳ ಬದಲು AI ಪ್ರತಿಕ್ರಿಯೆಗಳು ತ್ಯಾಜ್ಯ ಅಕ್ಷರಗಳು (ಉದಾ. `????` ಅಥವಾ `â??`) ತೋರಿಸುತ್ತವೆ - -**ಕಾರಣ**: PowerShell ಡಿಫಾಲ್ಟ್ ಎನ್‌ಕೊಡಿಂಗ್ UTF-8 ಇಮೋಜೀವನ್ನು ಬೆಂಬಲಿಸುವುದಿಲ್ಲ - -**ಪರಿಹಾರ**: ಜಾವಾ ಅಪ್ಲಿಕೆಷನ್‌ಗಳನ್ನು ನಡೆಸುವ ಮೊದಲು ಈ ಆಜ್ಞಾನವನ್ನು ಓಡಿ: -```cmd -chcp 65001 -``` - -ಇದು ಟರ್ಮಿನಲ್ ನಲ್ಲಿ UTF-8 ಎನ್‌ಕೊಡಿಂಗ್ ಅನ್ನು ಬಲಪಡಿಸುತ್ತದೆ. ಪರ್ಯಾಯವಾಗಿ, ಉತ್ತಮ ಯುನಿಕೋಡ್ ಬೆಂಬಲವುಳ್ಳ Windows Terminal ಅನ್ನು ಬಳಸಿ. - -### API ಕರೆಗಳ ಡಿಬಗ್ಗಿಂಗ್ - -**ಸಮಸ್ಯೆ**: ಪ್ರವೇಶ ಪರಿಶೀಲನೆ ದೋಷಗಳು, ದರ ಮಿತಿಗಳು ಅಥವಾ AI ಮಾದರಿಯಿಂದ ಅಪ್ರತೀಕ್ಷಿತ ಪ್ರತಿಕ್ರಿಯೆಗಳು - -**ಪರಿಹಾರ**: ಉದಾಹರಣೆಗಳಲ್ಲಿ `.logRequests(true)` ಮತ್ತು `.logResponses(true)` ಸೇರಿವೆ, ಇದು API ಕರೆಗಳನ್ನು ಕನ್ಸೋಲ್ ನಲ್ಲಿ ತೋರಿಸುತ್ತದೆ. ಇದು ಪ್ರವೇಶ ಪರಿಶೀಲನೆ ದೋಷಗಳು, ದರ ಮಿತಿಗಳು ಅಥವಾ ಅಪ್ರತೀಕ್ಷಿತ ಪ್ರತಿಕ್ರಿಯೆಗಳನ್ನು ಪರಿಹರಿಸಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ. ಲಾಗ್ ಧ್ವನಿಹರಣ ಕಡಿಮೆ ಮಾಡಲು ಉತ್ಪಾದನೆಯಲ್ಲಿ ಈ ಫ್ಲ್ಯಾಗ್‌ಗಳನ್ನು ತೆಗೆದುಹಾಕಿ. - ---- - - -**ಅస್ಪಷ್ಟಿಕೆ**: -ಈ ದಾಖಲೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಎಂಬ AI ಅನುವಾದ ಸೇವೆಯನ್ನು ಬಳಸಿ ಅನುವದಿಸಲಾಗಿದೆ. ನಾವು ಶುದ್ಧತೆಗೆ ಪ್ರಯತ್ನಿಸುತ್ತಿದ್ದರೂ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ನಿಖರತೆ ಕೊರತೆಗಳು ಇರಬಹುದು ಎಂದು ದಯವಿಟ್ಟು ಗಮನಿಸಿ. ಮೂಲ ಭಾಷೆಯ ದಾಖಲೆ ಅನಧಿಕೃತ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದದ ಬಳಕೆಯಿಂದ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪು ಅರ್ಥಮಾಡಿಕೆ ಅಥವಾ ತುಂಡು ಅರ್ಥಗಳಿಗಾಗಿ ನಾವು ಜವಾಬ್ದಾರಿಯಲ್ಲ. - \ No newline at end of file diff --git a/translations/kn/01-introduction/README.md b/translations/kn/01-introduction/README.md index 556a7a4a4..4a7c99b4c 100644 --- a/translations/kn/01-introduction/README.md +++ b/translations/kn/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j ಜೊತೆ ಆರಂಭಿಸುವುದು +# ನಿಯಮ 01: ಲಾಂಗ್‍ಚೈನ್4ಜೆ ಜೊತೆಗೆ ಪ್ರಾರಂಭಿಸುವುದು -## ವಿಷಯಗಳು +## ವಿಷಯಗಳ ಪರಿಚಯ -- [ವೀಡಿಯೊ ನಡೆಯಣೆ](../../../01-introduction) -- [ನೀವು ಏನು ಕಲಿಯುತ್ತೀರಿ](../../../01-introduction) -- [ಮುಂದಿನ ಆವಶ್ಯಕತೆಗಳು](../../../01-introduction) -- [ಮೂಲ ಸಮಸ್ಯೆಯನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು](../../../01-introduction) -- [ಟೋಕನ್ಗಳನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು](../../../01-introduction) -- [ಗೋಚರಿಸುವಿಕೆ ಹೇಗೆ ಕೆಲಸಮಾಡುತ್ತದೆ](../../../01-introduction) -- [ಇದು LangChain4j ಅನ್ನು ಹೇಗೆ ಬಳಸುತ್ತದೆ](../../../01-introduction) -- [Azure OpenAI ಮೂಲಸೌಕರ್ಯ ನಿಯೋಜನೆ](../../../01-introduction) -- [ಅಪ್ಲಿಕೇಶನ್ ಅನ್ನು ಸ್ಥಳೀಯವಾಗಿ ಚಾಲನೆ ಮಾಡುವುದು](../../../01-introduction) -- [ಅಪ್ಲಿಕೇಶನ್ ಬಳಸುವುದು](../../../01-introduction) - - [Stateless ಚಾಟ್ (ಎಡ ಪ್ಯಾನೆಲ್)](../../../01-introduction) - - [Stateful ಚಾಟ್ (ಸುಳಿವು ಬಲ ಪ್ಯानेಲ್)](../../../01-introduction) -- [ಮುಂದಿನ ಹಂತಗಳು](../../../01-introduction) +- [ವೀಡಿಯೊ ವಾಕ್‍ಥ್ರೂ](#ವೀಡಿಯೊ-ವಾಕ್‍ಥ್ರೂ) +- [ನೀವು ಏನು ಕಲಿಯುತ್ತೀರಿ](#ನೀವು-ಏನು-ಕಲಿಯುತ್ತೀರಿ) +- [ಪೂರ್ವಾಪೇಕ್ಷಿತಗಳು](#ಪೂರ್ವಾಪೇಕ್ಷಿತಗಳು) +- [ಮೂಲ ಸಮಸ್ಯೆಯನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು](#ಮೂಲ-ಸಮಸ್ಯೆಯನ್ನು-ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು) +- [ಟೋಕನ್ಗಳನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು](#ಟೋಕನ್ಗಳನ್ನು-ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು) +- [ಮೆಮರೀ ಹೇಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ](#ಮೆಮರೀ-ಹೇಗೆ-ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ) +- [ಇದು ಲಾಂಗ್‍ಚೈನ್4ಜೆ ಅನ್ನು ಹೇಗೆ ಬಳಸುತ್ತದೆ](#ಇದು-ಲಾಂಗ್‍ಚೈನ್4ಜೆ-ಅನ್ನು-ಹೇಗೆ-ಬಳಸುತ್ತದೆ) +- [ಅಜೂರ್ ಓಪನ್‌ಎಐ ಮೂಲಸೌಕರ್ಯವನ್ನು ನಿಯೋಜಿಸಿ](#ಅಜೂರ್-ಓಪನ್‌ಎಐ-ಮೂಲಸೌಕರ್ಯವನ್ನು-ನಿಯೋಜಿಸಿ) +- [ಅಪ್ಲಿಕೇಶನ್ ಅನ್ನು ಸ್ಥಳೀಯವಾಗಿ ರನ್ಮಾಡಿ](#ಅಪ್ಲಿಕೇಶನ್-ಅನ್ನು-ಸ್ಥಳೀಯವಾಗಿ-ರನ್ಮಾಡಿ) +- [ಅಪ್ಲಿಕೇಶನ್ ಬಳಕೆ](#ಅಪ್ಲಿಕೇಶನ್-ಬಳಕೆ) + - [ರಾಜಕೀಯ ಚಾಟ್ (ಎಡ ಪ್ಯಾನಲ್)](#ರಾಜಕೀಯ-ಚಾಟ್-ಎಡ-ಪ್ಯಾನಲ್) + - [ಸ್ಥಾಯಿಶೀಲ ಚಾಟ್ (ಬಲ ಪ್ಯಾನಲ್)](#ಸ್ಥಾಯಿಶೀಲ-ಚಾಟ್-ಬಲ-ಪ್ಯಾನಲ್) +- [ಮುಂದಿನ ಹಂತಗಳು](#ಮುಂದಿನ-ಹಂತಗಳು) -## ವೀಡಿಯೊ ನಡೆಯಣೆ +## ವೀಡಿಯೊ ವಾಕ್‍ಥ್ರೂ -ಈ ಘಟಕವನ್ನು ಹೇಗೆ ಪ್ರಾರಂಭಿಸುವುದೆಂದು ವಿವರಿಸುವ ಲೈವ್ ಸೆಷನ್ ಅನ್ನು ನೋಡು: +ಈ ಲೈವ್ ಸೆಷನ್‌ ಅನ್ನು ನೋಡು, ಇದು ಈ ನಿಯಮದೊಂದಿಗೆ ಪ್ರಾರಂಭಿಸಲು ಹೇಗೆ ಎಂಬುದನ್ನು ವಿವರಿಸುತ್ತದೆ: -LangChain4j ಜೊತೆ ಆರಂಭಿಸುವುದು - ಲೈವ್ ಸೆಷನ್ +Getting Started with LangChain4j - Live Session ## ನೀವು ಏನು ಕಲಿಯುತ್ತೀರಿ -ಈ ತ್ವರಿತ ಆರಂಭದಲ್ಲಿ, ನೀವು GitHub ಮಾದರಿಗಳನ್ನು ಬಳಸಿಕೊಂಡು ಪ್ರಾಂಪ್ಟ್ಗಳನ್ನು ಕಳುಹಿಸುವುದು, ಉಪಕರಣಗಳನ್ನು ಕರೆಯುವುದು, RAG ಪೈಪ್‌ಲೈನ್ ಸൃഷ್ಠಿಸುವುದು ಮತ್ತು ಗಾರ್ಡ್‌ರೈಲ್‌ಗಳು ಪರೀಕ್ಷಿಸುವುದು ಕಲಿತಿರಿ. ಆ ಡೆಮೊಗಳು ಏನು ಸಾಧ್ಯವೋ ತೋರುತ್ತವೆ — ಈಗ ನಾವು Azure OpenAI ಮತ್ತು GPT-5.2 ಗೆ ಬದಲಾಗುತ್ತೇವೆ ಮತ್ತು ಉತ್ಪಾದನಾ ಶೈಲಿಯ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ಮಿಸಲು ಆರಂಭಿಸುತ್ತೇವೆ. ಈ ಘಟಕವು ಸಂಭಾಷಣೆಯ AI ಮೇಲೆ ಕೇಂದ್ರೀಕರಿಸುತ್ತದೆ, ಇದು ಸಂದರ್ಭವನ್ನು ನೆನಪಿಡುತ್ತದೆ ಮತ್ತು ಸ್ಥಿತಿಯನ್ನು ಕಾಪಾಡುತ್ತದೆ — ಈ ತ್ವರಿತ ಆರಂಭ ಡೆಮೊಗಳಲ್ಲಿ ಬಳಕೆ ಮಾಡಿದ ಆದರೆ ವಿವರಿಸದ ಕಲ್ಪನೆಗಳು. +ಇದು ಲಾಂಗ್‍ಚೈನ್4ಜೆ ಮತ್ತು ಅಜೂರ್ ಓಪನ್‌ಎಐ ಜೊತೆಗೆ ನಿಮ್ಮ ಪ್ರಾರಂಭಬಿಂದುವಾಗಿದೆ. ನಾವು ಮೂಲತತ್ವಗಳಿಂದ ಪ್ರಾರಂಭಿಸಿ ಉತ್ಪಾದನಾ ಶೈಲಿ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ಮಿಸಲು ಪ್ರಾರಂಭಿಸುತ್ತೇವೆ. ಈ ನಿಯಮ ಸಂವಾದಾತ್ಮಕ AI ಗೆ ಕೇಂದ್ರೀಕೃತವಾಗಿದೆ, ಅದು ಸಾಂದರ್ಭವನ್ನು ನೆನಸುತ್ತದೆ ಮತ್ತು ಸ್ಥಿತಿಯನ್ನು ಇಡುವುದು — ಪ್ರತೀ ನಂತರದ ನಿಯಮವು ಅವಲಂಬಿಸುವ ಮೂಲಭೂತ ಕಲ್ಪನೆಗಳು. -ನಾವು ಈ ಮಾರ್ಗದರ್ಶಿಯಲ್ಲಿ Azure OpenAI ನ GPT-5.2 ಅನ್ನು ಬಳಕೆಮಾಡುತ್ತೇವೆ ಏಕೆಂದರೆ ಅದರ ಅಗ್ರಗಣ್ಯ ವಿವೇಚನಾ ಸಾಮರ್ಥ್ಯಗಳು ವಿಭಿನ್ನ ಮಾದರಿಗಳ ವರ்த்தನೆಗಳು ಸ್ಪಷ್ಟವಾಗುವಂತೆ ಮಾಡುತ್ತವೆ. ನೀವು ಮೆಮೊರಿ ಸೇರಿಸಿದಾಗ, ವ್ಯತ್ಯಾಸವನ್ನು ಸ್ಪಷ್ಟವಾಗಿ ಕಾಣುತ್ತೀರಿ. ಇದು ನಿಮ್ಮ ಅಪ್ಲಿಕೇಶನ್‌ಗೆ ಪ್ರತಿ ಘಟಕ ಏನು ತರುತ್ತದೆ ಎಂಬುದನ್ನು ಸುಲಭವಾಗಿ ಅರ್ಥಮಾಡಿಕೊಳ್ಳಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ. +ನಾವು ಈ ಮಾರ್ಗದರ್ಶನದಲ್ಲಿ ಅಜೂರ್ ಓಪನ್‌ಎಐನ GPT-5.2 ಅನ್ನು ಸಂಪೂರ್ಣವಾಗಿ ಬಳಸುತ್ತೇವೆ ಏಕೆಂದರೆ ಅದರ ಉನ್ನತವಾದ ತರ್ಕ ಸಾಮರ್ಥ್ಯಗಳು ವಿಭಿನ್ನ ವಿನ್ಯಾಸಗಳ ವರ್ತನೆಯನ್ನು ಸ್ಪಷ್ಟಗೊಳಿಸುತ್ತವೆ. ನೀವು ಮೆಮರೀ ಸೇರಿಸಿದಾಗ, ವ್ಯತ್ಯಾಸ ಸ್ಪಷ್ಟವಾಗಿ ಕಾಣುತ್ತದೆ. ಇದು ನಿಮ್ಮ ಅಪ್ಲಿಕೇಶನ್‌ಗೆ ಪ್ರತೀ ഘಟಕ ಏನು ತರಬಹುದು ಎಂದು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದರಲ್ಲಿ ಸಹಾಯ ಮಾಡುತ್ತದೆ. -ನೀವು ಒಂದೇ ಅಪ್ಲಿಕೇಶನ್ ನಿರ್ಮಿಸುತ್ತೀರಿ, ಅದು ಎರಡೂ ಮಾದರಿಗಳನ್ನು ತೋರಿಸುತ್ತದೆ: +ನೀವು ಎರಡು ವಿನ್ಯಾಸಗಳನ್ನೂ ತೋರಿಸುವ ಒಂದು ಅಪ್ಲಿಕೇಶನ್ ನಿರ್ಮಿಸುವಿರಿ: -**Stateless ಚಾಟ್** - ಪ್ರತಿ ವಿನಂತಿ ಸ್ವತಂತ್ರ. ಮಾದರಿಯ ಬಳಿ ಹಿಂದಿನ ಸಂದೇಶಗಳ ಮೆಮೊರಿ ಇಲ್ಲ. ಇದು ನೀವು ತ್ವರಿತ ಆರಂಭದಲ್ಲಿ ಬಳಸಿದ್ದ ಮಾದರಿಯಾಗಿದೆ. +**ರಾಜಕೀಯ ಚಾಟ್** - ಪ್ರತೀ ವಿನಂತಿ ಸ್ವತಂತ್ರವಾಗಿದೆ. ಮಾದರಿ ಹಿಂದಿನ ಸಂದೇಶಗಳನ್ನು ನೆನಸುವುದಿಲ್ಲ. ಇದು ಸರಳವಾದ ಪ್ರಾರಂಭದ ಬಿಂದುವಾಗಿದೆ. -**Stateful ಸಂಭಾಷಣೆ** - ಪ್ರತಿ ವಿನಂತಿಯಲ್ಲಿ ಸಂಭಾಷಣಾ ಇತಿಹಾಸವನ್ನು ಸೇರಿಸಲಾಗಿದೆ. ಮಾದರಿ ಹಲವಾರು ಸುತ್ತುಗಳಲ್ಲಿ ಸನ್ನಿವಾರವನ್ನು ಕಾಪಾಡುತ್ತದೆ. ಇದು ಉತ್ಪಾದನಾ ಅಪ್ಲಿಕೇಶನ್‌ಗಳಿಗೆ ಅಗತ್ಯ. +**ಸ್ಥಾಯಿಶೀಲ ಸಂವಾದ** - ಪ್ರತೀ ವಿನಂತಿಗೆ ಸಂವಾದ ಇತಿಹಾಸ ಸೇರಿದೆ. ಮಾದರಿ ಹಲವಾರು ತಿರುವುಗಳ ನಡುವೆ ಸಾಂದರ್ಭಿಕತೆಯನ್ನು ನಡಿಸ್ತದೆ. ಇದು ಉತ್ಪಾದನಾ ಅಪ್ಲಿಕೇಶನ್‌ಗಳಿಗೆ ಬೇಕಾಗಿರುವುದು. -## ಮುಂದಿನ ಆವಶ್ಯಕತೆಗಳು +## ಪೂರ್ವಾಪೇಕ್ಷಿತಗಳು -- Azure OpenAI ಪ್ರವೇಶವಿರುವ Azure ಚಂದಾದಾರಿಕೆ -- Java 21, Maven 3.9+ -- Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) -- Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) +- ಅಜೂರ್ ಸಬ್ಸ್ಕ್ರಿಪ್ಶನ್ ಜೊತೆಗೆ ಅಜೂರ್ ಓಪನ್‌ಎಐ ಪ್ರವೇಶ +- ಜವಾ 21, ಮೇವೆನ್ 3.9+ +- ಅಜೂರ್ CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) +- ಅಜೂರ್ ಡೆವಲಪರ್ CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **ಗಮನಿಸಿ:** Java, Maven, Azure CLI ಮತ್ತು Azure Developer CLI (azd) ಪೂರ್ವನಿಯೋಜಿತವಾಗಿ ನೀಡಲಾದ ಡೆವ್ ಕಾಂಟೈನರ್‌ನಲ್ಲಿ ಇವೆ. +> **ಗಮನಿಸಿ:** ಜವಾ, ಮೇವೆನ್, ಅಜೂರ್ CLI ಮತ್ತು ಅಜೂರ್ ಡೆವಲಪರ್ CLI (azd) ಪೂರ್ವನಿಷ್ಠಿತವಾಗಿ devcontainernalli ಒಳಗೊಂಡಿವೆ. -> **ಗಮನಿಸಿ:** ಈ ಘಟಕವು Azure OpenAI ಮೇಲೆ GPT-5.2 ಅನ್ನು ಬಳಸುತ್ತದೆ. ನಿಯೋಜನೆ ಸ್ವಯಂಚಾಲಿತವಾಗಿ `azd up` ಮೂಲಕ ಮಾಡಲ್ಪಡುತ್ತದೆ - ಕೋಡ್‌ನಲ್ಲಿ ಮಾದರಿಯ ಹೆಸರನ್ನು ಬದಲಿಸಬೇಡಿ. +> **ಗಮನಿಸಿ:** ಈ ನಿಯಮವು ಅಜೂರ್ ಓಪನ್‌ಎಐನಲ್ಲಿ GPT-5.2 ಅನ್ನು ಬಳಸುತ್ತದೆ. ನಿಯೋಜನೆ `azd up` ಮೂಲಕ ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಸಂರಚಿತವಾಗಿದೆ - ಕೋಡ್ನಲ್ಲಿ ಮಾದರಿಯ ಹೆಸರನ್ನು ಬದಲಾಯಿಸಬೇಡಿ. ## ಮೂಲ ಸಮಸ್ಯೆಯನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು -ಭಾಷಾ ಮಾದರಿಗಳು Stateless ಆಗಿವೆ. ಪ್ರತಿ API ಕರೆ ಸ್ವತಂತ್ರವಾಗಿದೆ. ನೀವು "ನನ್ನ ಹೆಸರು ಜಾನ್" ಅನ್ನು ಕಳುಹಿಸಿ ನಂತರ "ನನ್ನ ಹೆಸರು ಏನು?" ಎಂದು ಕೇಳಿದರೆ, ಮಾದರಿಗೇನೂ ತಿಳಿದಿರಲಿಲ್ಲ ನೀವು ತನ್ನನ್ನು ಪರಿಚಯಿಸಿದ್ದೀರಿ ಎಂಬುದನ್ನು. ಇದು ಪ್ರತಿ ವಿನಂತಿಯನ್ನು ಮೊದಲ ಸಂಭಾಷಣೆ ಆಗಿದೆ ಎಂದು ಭಾವಿಸುತ್ತದೆ. +ಭಾಷಾ ಮಾದರಿಗಳು ರಾಜಕೀಯ (stateless) ಆಗಿವೆ. ಪ್ರತೀ API ಕರೆ ಸ್ವತಂತ್ರವಾಗಿದೆ. ನೀವು "ನನ್ನ ಹೆಸರು ಜಾನ್" ಅನ್ನು ಕಳುಹಿಸಿದ পরে "ನನ್ನ ಹೆಸರು ಏನು?" ಎಂದು ಕೇಳಿದಲ್ಲಿ, ಮಾದರಿಗೆ ನೀವು ತಾಜಾ ಪರಿಚಯಿಸಿದ್ದು ಎಂಬುದರ ಎನಾದರೂ ತಿಳಿದಿಲ್ಲ. ಇದು ಪ್ರತೀ ವಿನಂತಿಯನ್ನು ಮೊದಲ ಸಂವಾದವಾಗಿದೆ ಎಂಬಂತೆ ಪರಿಗಣಿಸುತ್ತದೆ. -ಸರಳ Q&A ಗಾಗಿ ಇದು ಸರಿಯಾಗಿದೆ ಆದರೆ ವಾಸ್ತವಿಕ ಅಪ್ಲಿಕೇಶನ್‌ಗಳಿಗೆ ಉಪಯುಕ್ತವಲ್ಲ. ಗ್ರಾಹಕ ಸೇವಾ ಬಾಟ್ಗಳು ನೀವು ಹೇಳಿದ ವಿಚಾರಗಳನ್ನು ನೆನಪಿಟ್ಟಿಕೊಳ್ಳಬೇಕು. ವೈಯಕ್ತಿಕ ಸಹಾಯಕರಿಗೆ ಸಂದರ್ಭ ಬೇಕು. ಯಾವುದೇ ಬಹು-ಸುತ್ತು ಸಂಭಾಷಣೆಗೆ ಮೆಮೊರಿ ಅಂತಹದು. +ಸಾದಾ ಪ್ರಶ್ನೋತ್ತರಕ್ಕೆ ಇದು ಸರಿ ಆದರೆ ನಿಜವಾದ ಅಪ್ಲಿಕೇಶನ್‌ಗಳಿಗೆ ಉಪಯೋಗವಿಲ್ಲ. ಗ್ರಾಹಕ ಸೇವೆಯ ಬಾಟ್‌ಗಳು ನೀವು ಹೇಳಿದ್ದನ್ನು ನೆನಸಿಕೊಳ್ಳಬೇಕು. ವೈಯಕ್ತಿಕ ಸಹಾಯಕರು ಸಾಂದರ್ಭಿಕತೆಯನ್ನು ಬೇಕಾಗಿರುತ್ತವೆ. ಯಾವುದೇ ಬಹು ತಿರುವಿನ ಸಂವಾದಕ್ಕೆ ಮೆಮರೀ ಅಗತ್ಯ. -ಕೆಳಗಿನ ಚಿತ್ರದಲ್ಲಿ ಎರಡು ವಿಧಾನಗಳನ್ನು ತೋರಿಸಲಾಗಿದೆ – ಎಡಗಡೆ, stateless ಕರೆ ನಿಮ್ಮ ಹೆಸರನ್ನು ಮರೆತುಹೋಗುತ್ತದೆ; ಬಲಗಡೆ, ChatMemory ಬೆಂಬಲಿತ stateful ಕರೆ ಅದು ನೆನಪಿಟ್ಟುಕೊಳ್ಳುತ್ತದೆ. +ಕೆಳಗಿನ ಚಿತ್ರದಲ್ಲಿ ದಕ್ಷಿಣ ಬದಿಯಲ್ಲಿ ರಾಜಕೀಯ ಕರೆ ಇದ್ದು ನಿಮ್ಮ ಹೆಸರನ್ನು ಮರೆತಿದೆ; ಬಲಬದಿಯಲ್ಲಿ ChatMemory ಬೆಂಬಲಿತ ಸ್ಥಾಯಿಶೀಲ ಕರೆ ಇದೆ ಅದು ಹೆಸರನ್ನು ನೆನಸುತ್ತದೆ. Stateless vs Stateful Conversations -*Stateless (ಸ್ವತಂತ್ರ ಕರೆಗಳು) ಮತ್ತು Stateful (ಸಂದರ್ಭ-ಅನುವಾದಿತ) ಸಂಭಾಷಣೆಗಳ ನಡುವಿನ ವ್ಯತ್ಯಾಸ* +*ರಾಜಕೀಯ (ಸ್ವತಂತ್ರ ಕರೆಗಳು) ಮತ್ತು ಸ್ಥಾಯಿಶೀಲ (ಸಾಂದರ್ಭಿಕತೆ ಗೊತ್ತಿರುವ) ಸಂವಾದಗಳ ನಡುವಿನ ವ್ಯತ್ಯಾಸ* -## ಟೋಕನ್ಗಳನ್ನು ಅರ್ಥ ಮಾಡಿಕೊಳ್ಳುವುದು +## ಟೋಕನ್ಗಳನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು -ಸಂಭಾಷಣೆಯಲ್ಲಿ ಮುಳುಗಿಕೊಳ್ಳುವುದಕ್ಕೆ ಮುಂಚೆ, ಟೋಕನ್ಗಳನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು ಅಗತ್ಯ - ಭಾಷಾ ಮಾದರಿಗಳು ಸಂಸ್ಕರಿಸುವ ಅಸ್ತಿತ್ವ ಪಠ್ಯದ ಮೂಲ ಘಟಕಗಳು: +ಸಂವಾದಗಳಿಗೆ ಕೈಹೊರಡುವ ಮುನ್ನ, ಟೋಕನ್ಗಳನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು ಮುಖ್ಯ - ಭಾಷಾ ಮಾದರಿಗಳು ಪ್ರಕ್ರಿಯೆ ಮಾಡುವ ಪಠ್ಯದ ಮೂಲ ಘಟಕಗಳು: Token Explanation -*ಪಠ್ಯವು ಟೋಕನ್ಗೆ ಹೇಗೆ ವಿಭಜಿಸಲಾಗುತ್ತದೆ ಎಂಬ ಉದಾಹರಣೆ - "I love AI!" 4 ಪ್ರತ್ಯೇಕ ಸಂಸ್ಕರಣ ಘಟಕಗಳಾಗುತ್ತದೆ* +*ಪಠ್ಯವನ್ನು ಹೇಗೆ ಟೋಕನ್ಗಾಗಿ ತುಂಡುಮಾಡಲಾಗುತ್ತದೆ ಎಂಬ ಉದಾಹರಣೆ - "I love AI!" ಎಂಬುದು 4 ಪ್ರತ್ಯೇಕ ಪ್ರಕ್ರಿಯೆ ಘಟಕಗಳಾಗಿ ಪರಿಗಣಿಸಲಾಗುತ್ತದೆ* -ಟೋಕನ್‌ಗಳು AI ಮಾದರಿಗಳ ಪಠ್ಯವನ್ನು ಅಳತೆ ಮತ್ತು ಸಂಸ್ಕರಿಸುವ ವಿಧಾನ. ಪದಗಳು, विरಾಮಚಿಹ್ , ಮತ್ತು ಇವತ್ತು ಸ್ಪೇಸ್‌ಗಳು ಟೋಕನ್‌ಗಳಾಗಿರಬಹುದು. ನಿಮ್ಮ ಮಾದರಿಗೆ ಒಟ್ಟಾರೆ ಎಷ್ಟು ಟೋಕನ್‌ಗಳನ್ನು ಒಂದೇ ಸಲ ಪ್ರಕ್ರಿಯೆ ಮಾಡಬಹುದು ಎಂಬ ಮಿತಿ ಇರುತ್ತದೆ (GPT-5.2 ಗಾಗಿ 400,000, 272,000 ಇನ್ಪುಟ್ ಟೋಕನ್‌ಗಳು ಮತ್ತು 128,000 ಔಟ್ಪುಟ್ ಟೋಕನ್‌ಗಳವರೆಗೆ). ಟೋಕನ್ಗಳನ್ನು ಅರಿತುಕೊಳ್ಳುವುದು ಸಂಭಾಷಣೆಗೆ ಗಾತ್ರ ಮತ್ತು ವೆಚ್ಚವನ್ನು ನಡೆಸಲು ಸಹಾಯಕ. +ಟೋಕನ್ಗಳು AI ಮಾದರಿಗಳು ಪಠ್ಯವನ್ನು ಅಳೆಯುವ ಮತ್ತು ಪ್ರಕ್ರಿಯೆ ಮಾಡುವ ವಿಧಾನವಾಗಿದೆ. ಪದಗಳು, ವ್ಯಾಕರಣ ಚಿಹ್ನೆಗಳು ಮತ್ತು‌ ಖಾಲಿ ಬಿರುವು ಕೂಡ ಟೋಕನಾಗಬಹುದು. ನಿಮ್ಮ ಮಾದರಿಗೆ ಅದೇ ಸಮಯದಲ್ಲಿ ಎಷ್ಟು ಟೋಕನುಗಳನ್ನು ಪ್ರಕ್ರಿಯೆ ಮಾಡಬಹುದು ಎಂಬ ಮಿತಿ ಇದೆ (GPT-5.2 ಗಾಗಿ 400,000, 272,000 ಇನ್‌ಪುಟ್ ಟೋಕನ್ಗಳು ಮತ್ತು 128,000 ಔಟ್‌ಪುಟ್ ಟೋಕನ್ಗಳವರೆಗೆ). ಟೋಕನ್ಗಳ ಅರ್ಥಮಾಡಿಕೋಳ್ಳುವುದು ಸಂವಾದದ ಉದ್ದ ಮತ್ತು ವೆಚ್ಚಗಳನ್ನು ನಿರ್ವಹಿಸಲು ನೆರವಾಗುತ್ತದೆ. -## ಗೋಚರಿಸುವಿಕೆ ಹೇಗೆ ಕೆಲಸಮಾಡುತ್ತದೆ +## ಮೆಮರೀ ಹೇಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ -ಚಾಟ್ ಮೆಮೊರಿ stateless ಸಮಸ್ಯೆಯನ್ನು ಸಂಭಾಷಣಾ ಇತಿಹಾಸವನ್ನು ಕಾಪಾಡಿಕೊಂಡು ಪರಿಹರಿಸುತ್ತದೆ. ನಿಮ್ಮ ವಿನಂತಿಯನ್ನು ಮಾದರಿಗೆ ಕಳುಹಿಸುವ ಮುಂಚೆ, ಫ್ರೆಮ್‌ವರ್ಕ್ ಸಂಬಂಧಿಸಿದ ಹಿಂದಿನ ಸಂದೇಶಗಳನ್ನು ಸೇರಿಸುತ್ತದೆ. ನೀವು "ನನ್ನ ಹೆಸರು ಏನು?" ಎಂದು ಕೇಳಿದಾಗ, ವ್ಯವಸ್ಥೆ ಸಂಪೂರ್ಣ ಸಂಭಾಷಣೆಯ ಇತಿಹಾಸವನ್ನು ಕಳುಹಿಸುತ್ತಿದೆ, ಇದರಿಂದ ಮಾದರಿ ನೀವು "ನನ್ನ ಹೆಸರು ಜಾನ್" ಎಂದಿದ್ದೀರಿ ಎಂದು ಕಂಡುಕೊಳ್ಳುತ್ತದೆ. +ಚಾಟ್ ಮೆಮರೀ ರಾಜಕೀಯ ಸಮಸ್ಯೆಯನ್ನು ಸಂವಾದ ಇತಿಹಾಸವನ್ನು ನಡಿಸಿಕೊಡುವುದರ ಮೂಲಕ ಪರಿಹರಿಸುತ್ತದೆ. ನಿಮ್ಮ ವಿನಂತಿಯನ್ನು ಮಾದರಿಗೆ ಕಳುಹಿಸುವ ಮೊದಲು, ಫ್ರೇಮ್‌ವರ್ಕ್ ಸಂಬಂಧಿತ ಹಿಂದಿನ ಸಂದೇಶಗಳನ್ನು ಸೇರಿಸುತ್ತದೆ. ನೀವು "ನನ್ನ ಹೆಸರು ಏನು?" ಎಂದು ಕೇಳಿದಾಗ, ವ್ಯವಸ್ಥೆ ನಿಜವಾಗಿಯೂ ಸಂಪೂರ್ಣ ಸಂವಾದ ಇತಿಹಾಸವನ್ನು ಕಳುಹಿಸುತ್ತದೆ, ಹೀಗಾಗಿ ಮಾದರಿಗೆ ನೀವು ಹಿಂದಿನದಾಗಿ "ನನ್ನ ಹೆಸರು ಜಾನ್" ಎಂದಿದ್ದೀರಿ ಎಂದು ಕಾಣುತ್ತದೆ. -LangChain4j ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಈ ಕಾರ್ಯವನ್ನು ನಿಭಾಯಿಸುವ ಮೆಮೊರಿ ಜಾಲಿಗಳನ್ನು ಒದಗಿಸುತ್ತದೆ. ನೀವು ಎಷ್ಟು ಸಂದೇಶಗಳನ್ನು ಉಳಿಸಬೇಕೆಂದು ಆಯ್ಕೆಮಾಡುತ್ತೀರಿ ಮತ್ತು ಫ್ರೆಮ್‌ವರ್ಕ್ ಸನ್ನಿವೃದ್ಧಿ ವಿಂಡೋವನ್ನು ನಿರ್ವಹಿಸುತ್ತದೆ. ಕೆಳಗಿನ ಚಿತ್ರದಲ್ಲಿ MessageWindowChatMemory ಇತ್ತೀಚಿನ ಸಂದೇಶಗಳ ಸ್ಲೈಡಿಂಗ್ ವಿಂಡೋ ಅನ್ನು ಹೇಗೆ ನಿರ್ವಹಿಸುತ್ತದೆ ಎಂಬುದನ್ನು ತೋರಿಸಲಾಗಿದೆ. +ಲಾಂಗ್‍ಚೈನ್4ಜೆ ಎರಡೂ ಮೆಮೊರೀ ಅನುಷ್ಠಾನಗಳನ್ನು ತರುತ್ತದೆ, ಅವುಗಳನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ನಿರ್ವಹಿಸುತ್ತದೆ. ನೀವು ಎಷ್ಟು ಸಂದೇಶಗಳನ್ನು ಉಳಿಸಬೇಕೆಂದು ಆಯ್ಕೆಮಾಡುತ್ತೀರಿ ಮತ್ತು ಫ್ರೇಮ್‌ವರ್ಕ್ ಸಾಂದರ್ಭಿಕ ವಿಂಡೋವನ್ನು ನಿರ್ವಹಿಸುತ್ತದೆ. ಕೆಳಗಿನ ಚಿತ್ರದಲ್ಲಿ MessageWindowChatMemory ಇತ್ತೀಚಿನ ಸಂದೇಶಗಳ ಸ್ಲೈಡಿಂಗ್ ವಿಂಡೋ ಅನ್ನು ಹೇಗೆ ನಿರ್ವಹಿಸುತ್ತದೆ ಎಂಬುದು ತೋರ್ಪಡಿಸಲಾಗಿದೆ. Memory Window Concept -*MessageWindowChatMemory ಇತ್ತೀಚಿನ ಸಂದೇಶಗಳ ಸ್ಲೈಡಿಂಗ್ ವಿಂಡೋವನ್ನು ನಿರ್ವಹಿಸುತ್ತದೆ, ಹಳೆಯದನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಬಿಟ್ಟುಹಾಕುತ್ತದೆ* +*MessageWindowChatMemory ಇತ್ತೀಚಿನ ಸಂದೇಶಗಳ ಸ್ಲೈಡಿಂಗ್ ವಿಂಡೋ ಅನ್ನು ನಿರ್ವಹಿಸುತ್ತದೆ, ಹಳೆಯಗಳನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಕಳೆದುಹೋಗುತ್ತದೆ* -## ಇದು LangChain4j ಅನ್ನು ಹೇಗೆ ಬಳಸುತ್ತದೆ +## ಇದು ಲಾಂಗ್‍ಚೈನ್4ಜೆ ಅನ್ನು ಹೇಗೆ ಬಳಸುತ್ತದೆ -ಈ ಘಟಕವು ತ್ವರಿತ ಆರಂಭವನ್ನು ವಿಸ್ತರಿಸಿ Spring Boot ಅನ್ನು ಜೋಡಿಸಿ ಮತ್ತು ಸಂಭಾಷಣಾ ಮೆಮೊರಿಯನ್ನು ಸೇರಿಸುತ್ತದೆ. ಇವು ಭಾಗಗಳು ಹೀಗಿವೆ: +ಈ ನಿಯಮವು ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅನ್ನು ಜೋಡಿಸಿ ಸಂವಾದ ಮೆಮೊರೀ ಸೇರಿಸುತ್ತದೆ. ಭಾಗಗಳು ಹೇಗೆ ಹೊಂದಿಕೊಂಡಿವೆ ಎಂಬುದನ್ನು ನೋಡೋಣ: -**निर्भरತೆಗಳು** - ಎರಡು LangChain4j ಗ್ರಂಥಾಲಯಗಳನ್ನು ಸೇರಿಸಿ: +**ಆಧಾರಗಳು** - ಎರಡು ಲಾಂಗ್‍ಚೈನ್4ಜೆ ಗ್ರಂಥಾಲಯಗಳನ್ನು ಸೇರಿಸಿ: ```xml @@ -94,7 +94,7 @@ LangChain4j ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಈ ಕಾರ್ಯವನ ``` -**ಚಾಟ್ ಮಾದರಿ** - Azure OpenAI ಅನ್ನು Spring ಬೀನ್ ಆಗಿ ಕಾನ್ಫಿಗರ್ ಮಾಡಿ ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**ಚಾಟ್ ಮಾದರಿ** - ಅಜೂರ್ ಓಪನ್‌ಎಐ ಅನ್ನು ಸ್ಪ್ರಿಂಗ್ ಬೀನ್ ಆಗಿ ಸಂರಚಿಸಿ ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -ಬಿಲ್ಡರ್ `azd up` ಮೂಲಕ ಸೆಟ್ ಮಾಡಲಾದ ಪರಿಸರ변ಶಾಲದಿಂದ ಪ್ರಮಾಣಪತ್ರಗಳನ್ನು ಓದುತ್ತದೆ. `baseUrl` ಅನ್ನು ನಿಮ್ಮ Azure ಟರ್ಮಿನಲ್‌ನ ಲಿಂಕ್‌ಗೆ ಹೊಂದಿಸುವುದರಿಂದ OpenAI ಕ್ಲೈನ್ಟ್ Azure OpenAI ಜೊತೆ ಕೆಲಸ ಮಾಡುತ್ತದೆ. +ಬಿಲ್ಡರ್ `azd up` ಮೂಲಕ ಸಿದ್ಧವಾಗಿರುವ ಪರಿಸರ ಬದಲಾಯಿಸುವ ಬದಲಾವಣೆಯಿಂದ ಮಾನ್ಯತೆಗಳನ್ನು ಓದುತ್ತದೆ. `baseUrl` ಅನ್ನು ನಿಮ್ಮ ಅಜೂರ್ ಎಂಡ್‍ಪಾಯಿಂಟ್‌ಗೆ ಸೆಟ್ ಮಾಡುವುದರಿಂದ ಓಪನ್‌ಎಐ ಕ್ಲೈಂಟ್ ಅಜೂರ್ ಓಪನ್‌ಎಐ ಜೊತೆಗೆ ಕೆಲಸಮಾಡುತ್ತದೆ. -**ಸಂಭಾಷಣಾ ಮೆಮೊರಿ** - MessageWindowChatMemory ಬಳಸಿ ಚಾಟ್ ಇತಿಹಾಸವನ್ನು ಟ್ರಾಕ್ ಮಾಡಿ ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**ಸಂವಾದ ಮೆಮೊರೀ** - MessageWindowChatMemory ಮೂಲಕ ಚಾಟ್ ಇತಿಹಾಸವನ್ನು ಟ್ರ್ಯಾಕ್ ಮಾಡಿ ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,43 +124,43 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` ಜೊತೆಗೆ ಮೆಮೊರಿಯನ್ನು ರಚಿಸಿ ಇದರಿಂದ ಕೊನೆಯ 10 ಸಂದೇಶಗಳು ಉಳಿಯುತ್ತವೆ. ಬಳಕೆದಾರ ಮತ್ತು AI ಸಂದೇಶಗಳಿಗೆ ಟೈಪ್ ಮಾಡಿದ ರಾಪರ್‌ಗಳನ್ನು ಬಳಸಿ: `UserMessage.from(text)` ಮತ್ತು `AiMessage.from(text)`. ಇತಿಹಾಸವನ್ನು `memory.messages()` ಉಪಯೋಗಿಸಿ ಪಡೆಯಿರಿ ಮತ್ತು ಅದನ್ನು ಮಾದರಿಗೆ ಕಳುಹಿಸಿ. ಸೇವೆ ಪ್ರತಿ ಸಂಭಾಷಣೆ ID ಗಾಗಿ ವಿಭಿನ್ನ ಮೆಮೊರಿ ಅರ್ಪಣೆಗಳನ್ನು ಸಂಗ್ರಹಿಸುತ್ತದೆ, ಇದರಿಂದ ಬಹುಬಳಕೆದಾರರು ಒಂದೇ ಸಮಯದಲ್ಲಿ ಚಾಟ್ ಮಾಡಬಹುದು. +`withMaxMessages(10)` ಬಳಸಿ ಮೆಮೊರೀ ಸೃಷ್ಟಿಸಿ ბოლო 10 ಸಂದೇಶಗಳನ್ನು ಉಳಿಸಬಹುದು. ಬಳಕೆದಾರ ಮತ್ತು AI ಸಂದೇಶಗಳನ್ನು ಸರಿಯಾದ ವಿಧಾನದ ಅರ್ಹತೆಗಳನ್ನು ಬಳಸಿಕೊಂಡು ಸೇರಿಸಿ: `UserMessage.from(text)` ಮತ್ತು `AiMessage.from(text)`. ಇತಿಹಾಸವನ್ನು `memory.messages()` ಮೂಲಕ ಪಡೆದು ಮಾದರಿಗೆ ಕಳುಹಿಸಿ. ಸೇವೆ ಪ್ರತಿ ಸಂವಾದ ID ಗೆ ಪ್ರತ್ಯೇಕ ಮೆಮರೀ ಉದಾಹರಣೆಗಳನ್ನು ಸಂಗ್ರಹಿಸುತ್ತದೆ, ಇದು ಬಹು ಬಳಕೆದಾರರು ಸಮಕಾಲೀನವಾಗಿ ಚಾಟ್ ಮಾಡಲು ಸಹಾಯಕ. -> **🤖 GitHub Copilot ಜೊತೆ ಪ್ರಯತ್ನಿಸಿ:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ಓದಿ ಮತ್ತು ಕೇಳಿ: -> - "MessageWindowChatMemory ವಿಂಡೋ ತುಂಬಿದಾಗ ಯಾವ ಸಂದೇಶಗಳನ್ನು ಬಿಟ್ಟುಹಾಕಬೇಕೆಂದು ಹೇಗೆ ನಿರ್ಧರಿಸುತ್ತದೆ?" -> - "ನಾನು ಇನ್-ಮೆಮೊರಿ ಬದಲು ಡೇಟಾಬೇಸ್ ಬಳಸಿ ಕಸ್ಟಮ್ ಮೆಮೊರಿ ಸ್ಟೋರ್ ಮಾಡಬಹುದೆ?" -> - "ಹಳೆಯ ಸಂಭಾಷಣಾ ಇತಿಹಾಸವನ್ನು ಸಂಕ್ಷಿಪ್ತಗೊಳಿಸಲು ಸಾರಾಂಶ ಸೇರಿಸುವುದನ್ನು ಹೇಗೆ ಸೇರಿಸುವುದು?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ಚಾಟ್ ಇದೇನೆಂದೋ ಪ್ರಯತ್ನಿಸಿ:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ಓದಿ ಮತ್ತು ಕೇಳಿ: +> - "MessageWindowChatMemory ವಿಂಡೋ ತುಂಬಿರುವಾಗ ಯಾವ ಸಂದೇಶಗಳನ್ನು ಬಿಟ್ಟುಹೋಗಲು ನಿರ್ಧರಿಸುತ್ತದೆ?" +> - "ನಾನು ಇನ್‌ಮೆಮೊರೀ ಬದಲು ಡೇಟಾಬೇಸ್ ಬಳಸಿ ಕಸ್ಟಮ್ ಮೆಮೊರೀ ಸಂಗ್ರಹಣೆಯನ್ನು ಅಳವಡಿಸಬಹುದೆ?" +> - "ಹಳೆಯ ಸಂವಾದ ಇತಿಹಾಸವನ್ನು ಸಂಕ್ಷಿಪ್ತಗೊಳಿಸಲು ಸಮರಿșaನ್ ಅನ್ನು ಹೇಗೆ ಸೇರಿಸುವೆ?" -Stateless ಚಾಟ್ ಎಂಡ್‌ಪಾಯಿಂಟ್ ಮೆಮೊರಿಯನ್ನು ಪೂರ್ಣವಾಗಿ ವಿಲೇವಾರಿ ಮಾಡುತ್ತದೆ - ಕೇವಲ `chatModel.chat(prompt)` ತ್ವರಿತ ಆರಂಭದಲ್ಲಿ ಇದ್ದಂತೆಯೇ. Stateful ಎಂಡ್‌ಪಾಯಿಂಟ್ ಸಂದೇಶಗಳನ್ನು ಮೆಮೊರಿಗೆ ಸೇರಿಸಿ, ಇತಿಹಾಸವನ್ನು ಪಡೆದು, ಆ ಸನ್ನಿವಾರವನ್ನು ಪ್ರತಿ ವಿನಂತಿಯೊಂದಿಗೆ ಸೇರಿಸುತ್ತದೆ. ಅದೇ ಮಾದರಿ ಕಾನ್ಫಿಗರೇಷನ್, ವಿಭಿನ್ನ ಮಾದರಿಗಳು. +ರಾಜಕೀಯ ಚಾಟ್ ಎಂಡ್‍ಪಾಯಿಂಟ್ ಮೆಮೊರೀ ಸಂಪೂರ್ಣವಾಗಿ ಬಿಟ್ಟುಹೋಗುತ್ತದೆ - ಕೇವಲ `chatModel.chat(prompt)` ಅನ್ನು ಬಳಸುತ್ತೇವೆ. ಸ್ಥಾಯಿಶೀಲ ಎಂಡ್‍ಪಾಯಿಂಟ್ ಮೆಮೊರಿಗೆ ಸಂದೇಶಗಳನ್ನು ಸೇರಿಸಿ, ಇತಿಹಾಸ ಪಡೆಯುತ್ತವೆ ಮತ್ತು ಆ ಸಾಂದರ್ಭಿಕತೆಯನ್ನು ಪ್ರತೀ ವಿನಂತಿಗೆ ಸೇರಿಸುತ್ತವೆ. ಮಾದರಿ ಸಂರಚನೆ ಕೆಲವುಸರಿಯಾಗಿದ್ದರೂ, ವಿನ್ಯಾಸ ವಿಭಿನ್ನ. -## Azure OpenAI ಮೂಲಸೌಕರ್ಯ ನಿಯೋಜನೆ ಮಾಡಿ +## ಅಜೂರ್ ಓಪನ್‌ಎಐ ಮೂಲಸೌಕರ್ಯವನ್ನು ನಿಯೋಜಿಸಿ **ಬ್ಯಾಶ್:** ```bash cd 01-introduction -azd up # ಸಬ್ಸ್ಕ್ರಿಪ್ಷನ್ ಮತ್ತು ಸ್ಥಳವನ್ನು ಆಯ್ಕೆಮಾಡಿ (ಪಶ್ಚಿಮ_us2 ಶಿಫಾರಸು ಮಾಡಲಾಗಿದೆ) +azd up # ನಿಮ್ಮ ಸದಸ್ಯತ್ವ ಮತ್ತು ಸ್ಥಳವನ್ನು ಆಯ್ಕೆಮಾಡಿ (eastus2 ಶിപಾರಸು ಮಾಡಲಾಗಿದೆ) ``` **ಪವರ್‌ಶೆಲ್:** ```powershell cd 01-introduction -azd up # ಸಬ್ಸ್ಕ್ರಿಪ್ಷನ್ ಮತ್ತು ಸ್ಥಳವನ್ನು ಆಯ್ಕೆಮಾಡಿ (ಉತ್ತರಪೂರ್ವ ಕೊಂಡಿ 2 ಶಿಫಾರಸು ಮಾಡಲಾಗಿದೆ) +azd up # ಸಬ್ಸ್ಕ್ರಿಪ್ಷನ್ ಮತ್ತು ಸ್ಥಳವನ್ನು ಆಯ್ಕೆಮಾಡಿ (eastus2 ಶಿಫಾರಸು ಮಾಡಲಾಗಿದೆ) ``` -> **ಗಮನಿಸಿ:** ನೀವು Timeout ದೋಷವನ್ನು ಎದುರಿಸಿದರೆ (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), `azd up` ಅನ್ನು ಮರುಚಲಾಯಿಸಿ. Azure ಸಂಪನ್ಮೂಲಗಳು ಹಿನ್ನೆಲೆಯಲ್ಲಿ ಇನ್ನೂ ನಿಯೋಜನೆಯಲ್ಲಿರಬಹುದು, ಮರುಪ್ರಯತ್ನಿಸಿ ಸಿಬ್ಬಂದಿ ಸ್ಥಿತಿಗೆ ಬರುವ ಸಮಯದಲ್ಲಿ ನಿಯೋಜನೆ ಪೂರ್ಣಗೊಳ್ಳುತ್ತದೆ. +> **ಗಮನಿಸಿ:** ನೀವು ಟೈಮೌಟ್ ದೋಷವನ್ನು ಎದುರಿಸುತ್ತಿದ್ದರೆ (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), `azd up` ಅನ್ನು ಮತ್ತೆ ಓಡಿಸಿ. ಅಜೂರ್ ಸಂಪನ್ಮೂಲಗಳು ಇನ್ನೂ ಶೇಖರಣೆಯಲ್ಲಿರಬಹುದು, ಮರುಪ್ರಯತ್ನವು ಸಂಪನ್ಮೂಲಗಳು ಅಂತಿಮ ಸ್ಥಿತಿಗೆ ತಲುಪಿದ ಮೇಲೆ ನಿಯೋಜನೆಯನ್ನು ಪೂರ್ಣಗೊಳಿಸುತ್ತದೆ. -ಇದು: -1. GPT-5.2 ಮತ್ತು text-embedding-3-small ಮಾದರಿಗಳೊಂದಿಗೆ Azure OpenAI ಸಂಪನ್ಮೂಲವನ್ನು ನಿಯೋಜಿಸುತ್ತದೆ -2. ಯೋಜನೆಯ ರೂಟ್ನಲ್ಲಿ ಪ್ರಮಾಣಪತ್ರಗಳೊಂದಿಗೆ `.env` ಫೈಲ್ ಸ್ವಯಂ-উತ್ಪಾದಿಸುತ್ತದೆ -3. ಎಲ್ಲಾ ಅಗತ್ಯ ಬಾಹ್ಯವರಣಗಳನ್ನು ಹೊಂದಿಸುತ್ತದೆ +ಇದು ಮಾಡುತ್ತದೆ: +1. GPT-5.2 ಮತ್ತು text-embedding-3-small ಮಾದರಿಗಳೊಂದಿಗೆ ಅಜೂರ್ ಓಪನ್‌ಎಐ ಸಂಪನ್ಮೂಲ ನಿಯೋಜನೆ +2. ಮಾನ್ಯತೆಗಳೊಂದಿಗೆ ಪ್ರಾಜೆಕ್ಟ್ ಮೂಲದಲ್ಲಿ `.env` ಫೈಲ್ ಸ್ವಯಂಚಾಲಿತ ರಚನೆ +3. ಎಲ್ಲಾ ಅಗತ್ಯ ಪರಿಸರ ಬದಲಾಯಿಸುವುವನ್ನು ಸೆಟ್ ಮಾಡುವುದು -**ನಿಯೋಜನೆಯಲ್ಲಿ ಸಮಸ್ಯೆಯಿದೆಯೇ?** ಸಿಂಪ್ರದಾಹ ಉಗಳನಾ ಫಲಕವನ್ನು ನೋಡಿ [Infrastructure README](infra/README.md) ನಲ್ಲಿ ಉಪವಲಯ ಹೆಸರು ಗೊಂದಲಗಳು, ಕೈಯಿಂದ Azure Portal ನಿಯೋಜನೆ ಹಂತಗಳು, ಮತ್ತು ಮಾದರಿ ಕಾನ್ಫಿಗರೇಶನ್ ಮಾರ್ಗದರ್ಶನದ ವಿವರಗಳು ಇವೆ. +**ನಿಯೋಜನೆಯಲ್ಲಿ ಸಮಸ್ಯೆಗಳಿವೇ?** ಉಪ ಡೊಮೇನ್ ಹೆಸರು ಸಂಧಾನಗಳು, ಕೈಯಿಂದ ಅಜೂರ್ ಪೋರ್ಟಲ್ ನಿಯೋಜನೆ ಹಂತಗಳು ಮತ್ತು ಮಾದರಿ ಸಂರಚನಾ ಮಾರ್ಗದರ್ಶನವನ್ನು ಒಳಗೊಂಡ [ಮೂಲಸೌಕರ್ಯ README](infra/README.md) ನೋಡಿ. -**ನಿಯೋಜನೆ ಯಶಸ್ವಿಯಾಗಿದೆ ಎಂದು ಪರಿಶೀಲಿಸಿ:** +**ನಿಯೋಜನೆ ಯಶಸ್ವಿಯಾಗಿದೆ ಎಂದು ದೃಢೀಕರಿಸಿ:** **ಬ್ಯಾಶ್:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY ಮುಂತಾದವುಗಳನ್ನು ತೋರಿಸಬೇಕು. +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY ಇತ್ಯಾದಿಗಳನ್ನು ಪ್ರದರ್ಶಿಸಬೇಕು. ``` **ಪವರ್‌ಶೆಲ್:** @@ -168,7 +168,7 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY ಮುಂತಾದವುಗಳನ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, ಇತ್ಯಾದಿಗಳನ್ನು ತೋರಿಸಬೇಕು. ``` -> **ಗಮನಿಸಿ:** `azd up` ಆज्ञೆ ಸ್ವಯಂಚಾಲಿತವಾಗಿ `.env` ಫೈಲ್ ಉತ್ಪಾದಿಸುತ್ತದೆ. ನಂತರ ಅದನ್ನು ಬದಲಾಯಿಸಲು `.env` ಫೈಲ್ ಅನ್ನು ಕೈಯಿಂದ ಸಂಪಾದಿಸಬಹುದು ಅಥವಾ ಮರುಉತ್ಪಾದಿಸಲು ಕೆಳಗಿನ ಪ್ರಕ್ರಿಯೆಯನ್ನು ಅನುಸರಿಸಿ: +> **ಗಮನಿಸಿ:** `azd up` ಆದೇಶವು ಸ್ವಯಂಚಾಲಿತವಾಗಿ `.env` ಫೈಲ್ ಅನ್ನು ರಚಿಸುತ್ತದೆ. ನೀವು ಬಳಿಕ ಅದನ್ನು ನವೀಕರಿಸುವ ಅಗತ್ಯವಿದ್ದರೆ, `.env` ಫೈಲ್ ಅನ್ನು ಕೈಯಿಂದ ಸಂಪಾದಿಸಬಹುದು ಅಥವಾ ಪರಿಶೀಲನೆಗಾಗಿ ಇವನ್ನು ಮತ್ತೆ ರಚಿಸಬಹುದು: > > **ಬ್ಯಾಶ್:** > ```bash @@ -182,15 +182,16 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, ಇತ್ಯಾದಿಗ > .\.azd-env.ps1 > ``` -## ಅಪ್ಲಿಕೇಶನ್ ಅನ್ನು ಸ್ಥಳೀಯವಾಗಿ ಚಾಲನೆ ಮಾಡುವುದು -**ನಿಯೋಜನೆ ಪರಿಶೀಲನೆ:** +## ಅಪ್ಲಿಕೇಶನ್ ಅನ್ನು ಸ್ಥಳೀಯವಾಗಿ ರನ್ಮಾಡಿ -`.env` ಫೈಲ್ ಅನ್ನು ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ ನಿಮ್ಮ Azure ಪ್ರಮಾಣಪತ್ರಗಳೊಂದಿಗೆ ಇರಿಸಿಕೊಳ್ಳಿ. ಈ ಕಾರ್ಯವನ್ನು ಘಟಕ ಡೈರೆಕ್ಟರಿಯಿಂದ (`01-introduction/`) ನಡೆಸಿ: +**ನಿಯೋಜನೆಯನ್ನು ಪರಿಶೀಲಿಸಿ:** + +ಅಜೂರ್ ಮಾನ್ಯತೆಗಳೊಂದಿಗೆ `.env` ಫೈಲ್ ಮೂಲ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ ಇರುತ್ತದೆ ಎಂದು ಖಚಿತಪಡಿಸಿಕೊಳ್ಳಿ. ಈ ನಿಯಮ ಡೈರೆಕ್ಟರಿಯಿಂದ (`01-introduction/`) ಈ ಆદેશಗಳನ್ನು ರನ್ ಮಾಡಿ: **ಬ್ಯಾಶ್:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ಅನ್ನು ಪ್ರದರ್ಶಿಸಬೇಕು +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ಅನ್ನು ತೋರಿಸಬೇಕು ``` **ಪವರ್‌ಶೆಲ್:** @@ -200,39 +201,39 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ಅನ್ನ **ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿ:** -**ಆಯ್ಕೆ 1: Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ಬಳಕೆ (VS Code ಬಳಕೆದಾರರಿಗೆ ಶಿಫಾರಸು)** +**ಆಯ್ಕೆ 1: ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್ಬೋರ್ಡ್ ಬಳಸಿ (VS ಕೋಡ್ ಬಳಕೆದಾರರಿಗೆ ಶಿಫಾರಸ್ಸು ಮಾಡಲಾಗಿದೆ)** -ಡೆವ್ ಕಂಟೈನರ್‌ನಲ್ಲಿ Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ವಿಸ್ತರಣೆಯನ್ನು ಒಳಗೊಂಡಿದೆ, ಇದು ಎಲ್ಲಾ Spring Boot ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ದೃಶ್ಯರೂಪದಲ್ಲಿ ನಿರ್ವಹಿಸಲು ಸಹಾಯಮಾಡುತ್ತದೆ. ನೀವು ಅವುಗಳನ್ನು VS Code ನ ಎಡ ಬದಿಯಲ್ಲಿದ್ದ Activity Bar ನಲ್ಲಿ(Spring Boot ಐಕಾನ್ ನೋಡಬಹುದು) ಕಾಣಬಹುದು. +ಡೇವ್ ಕಂಟೈನರ್ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್ಬೋರ್ಡ್ ವಿಸ್ತರಣೆ ಹೊಂದಿಸಿದೆ, ಇದು ಎಲ್ಲಾ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ವಹಿಸಲು ದೃಶ್ಯ ಇಂಟರ್ಫೇಸ್ ಒದಗಿಸುತ್ತದೆ. ನೀವು ಇದನ್ನು VS ಕೋಡ್‌ನ ಎಡ നിറದ ಸ್ತಂಭದಲ್ಲಿ (Activity Bar) ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಐಕಾನ್ ಅಡಿಯಲ್ಲಿ ಕಾಣಬಹುದು. -Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್‌ನಿಂದ ನೀವು: -- ಕೆಲಸದ ಸ್ಥಳದಲ್ಲಿರುವ ಎಲ್ಲಾ Spring Boot ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನೋಡಬಹುದು -- ಒತ್ತುವ ಮೂಲಕ ಆರಂಭ/ನಿಲ್ಲಿಸಬಹುದಾಗಿದೆ -- ಅಪ್ಲಿಕೇಶನ್ ಲಾಗ್‌ಗಳನ್ನು ನೇರವಾಗಿ ವೀಕ್ಷಿಸಬಹುದು -- ಅಪ್ಲಿಕೇಶನ್ ಸ್ಥಿತಿಯನ್ನು ಗಮನಿಸಬಹುದು +ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್ಬೋರ್ಡ್‌ನಿಂದ ನೀವು: +- ಕಾರ್ಯಕ್ಷೇತ್ರದಲ್ಲಿನ ಎಲ್ಲಾ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನೋಡಿ +- ಒಂದು ಕ್ಲಿಕ್‌ನೊಂದಿಗೆ ಅಪ್ಲಿಕೇಶನ್ ಗಳನ್ನು ಪ್ರಾರಂಭ / ನಿಲ್ಲಿಸಿ +- ಅಪ್ಲಿಕೇಶನ್ ಲಾಗ್‌ಗಳನ್ನು ನೇರ-ಸಮಯದಲ್ಲಿ ವೀಕ್ಷಿಸಿ +- ಅಪ್ಲಿಕೇಶನ್ ಸ್ಥಿತಿಯನ್ನು ಗಮನಿಸಿ -"introduction" ಬगलೆಯ ಪ್ಲೇ ಬಟನ್ ಕ್ಲಿಕ್ ಮಾಡಿ ಈ ಘಟಕವನ್ನು ಪ್ರಾರಂಭಿಸಿ ಅಥವಾ ಎಲ್ಲಾ ಘಟಕಗಳನ್ನು ಒಟ್ಟಿಗೆ ಪ್ರಾರಂಭಿಸಿ. +"introduction" ಹತ್ತಿರ ಇರುವ ಪ್ಲೇ ಬಟನ್ ಕ್ಲಿಕ್ ಮಾಡಿ ಈ ನಿಯಮವನ್ನು ಪ್ರಾರಂಭಿಸಿ, ಅಥವಾ ಎಲ್ಲಾ ನಿಯಮಗಳನ್ನು ಒಟ್ಟಾಗಿ ಪ್ರಾರಂಭಿಸಿ. Spring Boot Dashboard -*VS Code ನಲ್ಲಿ Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ — ಎಲ್ಲ ಘಟಕಗಳನ್ನು ಒಂದು ಜಾಗದಿಂದ ಪ್ರಾರಂಭಿಸಿ, ನಿಲ್ಲಿಸಿ ಮತ್ತು ಮೇಲ್ವಿಚಾರಣೆ ಮಾಡಿ* +*VS ಕೋಡ್‌ನಲ್ಲಿನ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್ಬೋರ್ಡ್ — ಒಂದೇ ಸ್ಥಳದಿಂದ ಎಲ್ಲಾ ನಿಯಮಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿ, ನಿಲ್ಲಿಸಿ ಮತ್ತು ಪರಿಶೀಲಿಸಿ* -**ಆಯ್ಕೆ 2: Shell ಸ್ಕ್ರಿಪ್ಟ್ ಬಳಕೆ** +**ಆಯ್ಕೆ 2: ಶೆಲ್ ಸ್ಕ್ರಿಪ್ಟ್ ಬಳಸಿ** -ಎಲ್ಲಾ ವೆಬ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿ (ಘಟಕಗಳು 01-04): +ಎಲ್ಲಾ ವೆಬ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು (ನಿಯಮಗಳು 01-04) ಪ್ರಾರಂಭಿಸಿ: **ಬ್ಯಾಶ್:** ```bash -cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿ ನಿಂದ +cd .. # ರೂಟ್ ಡೈರೆಕ್ಟરીಯಿಂದ ./start-all.sh ``` **ಪವರ್‌ಶೆಲ್:** ```powershell -cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿ ನಿಂದ +cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಿಂದ .\start-all.ps1 ``` -ಅಥವಾ ಕೇವಲ ಈ ಘಟಕವನ್ನು ಪ್ರಾರಂಭಿಸಿ: +ಅಥವಾ ಕೇವలం ಈ ನಿಯಮವನ್ನು ಪ್ರಾರಂಭಿಸಿ: **ಬ್ಯಾಶ್:** ```bash @@ -246,9 +247,9 @@ cd 01-introduction .\start.ps1 ``` -ಎರಡೂ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ರೂಟ್ `.env` ಫೈಲ್‌ನಿಂದ ಪರಿಸರ ವ್ಯೇರಿಯಬಲ್ಗಳನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಲೋಡ್ ಮಾಡುತ್ತವೆ ಮತ್ತು ಜಾರ್‌ಗಳನ್ನು ಬಿಲ್ಡ್ ಮಾಡುತ್ತವೆ ಇಲ್ಲದಿದ್ದರೆ. +ಎರಡು ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಮೂಲ `.env` ಫೈಲ್‌ನಿಂದ ಪರಿಸರ ಬದಲಾಯಿಸುವುವನ್ನು ಲೋಡ್ ಮಾಡಿ, ಮತ್ತು ಜೆಆರ್‌ಗಳು ಇಲ್ಲದಿದ್ದರೆ ನಿರ್ಮಿಸುವವು. -> **ಗಮನಿಸಿ:** ನೀವು ಪ್ರಾರಂಭಿಸುವ ಮೊದಲು ಎಲ್ಲಾ ಘಟಕಗಳನ್ನು ಕೈಯಿಂದ ಬಿಲ್ಡ್ ಮಾಡಬೇಕಾದರೆ: +> **ಗಮನಿಸಿ:** ನೀವು ಪ್ರಾರಂಭಿಸುವ ಮುನ್ನ ಎಲ್ಲಾ ನಿಯಮಗಳನ್ನು ಕೈಯಿಂದ ನಿರ್ಮಿಸಲು ಇಚ್ಛಿಸಿದರೆ: > > **ಬ್ಯಾಶ್:** > ```bash @@ -270,7 +271,7 @@ cd 01-introduction ```bash ./stop.sh # ಈ ಮೋಡ್ಯೂಲ್ ಮಾತ್ರ # ಅಥವಾ -cd .. && ./stop-all.sh # ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್ಸ್ +cd .. && ./stop-all.sh # ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್‌ಗಳು ``` **ಪವರ್‌ಶೆಲ್:** @@ -280,43 +281,44 @@ cd .. && ./stop-all.sh # ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್ಸ್ cd ..; .\stop-all.ps1 # ಎಲ್ಲಾ ಮಾಯಾಜಾಲಗಳು ``` -## ಅಪ್ಲಿಕೇಶನ್ ಬಳಸುವುದು -ಅಪ್ಲಿಕೇಶನ್ ಎರಡು ಚಾಟ್ ಜಾಲಿಗಳನ್ನು ಪಕ್ಕಪಕ್ಕವಾಗಿ ಹೊಂದಿರುವ ವೆಬ್ ಇಂಟರ್ಫೇಸ್ ಒದಗಿಸುತ್ತದೆ. +## ಅಪ್ಲಿಕೇಶನ್ ಬಳಕೆ + +ಅಪ್ಲಿಕೇಶನ್ ಎರಡು ಚಾಟ್ ಅನುಷ್ಟಾನಗಳನ್ನು ಪಕ್ಕಾ ಪಕ್ಕಿ ನೀಡುತ್ತದೆ. -ಅಪ್ಲಿಕೇಶನ್ ಮುಖಪುಟ +Application Home Screen -*Dashboard ನಲ್ಲಿ Simple Chat (stateless) ಮತ್ತು Conversational Chat (stateful) ಆಯ್ಕೆಗಳು* +*ಸರಳ ಚಾಟ್ (ರಾಜಕೀಯ) ಮತ್ತು ಸಂವಾದಾತ್ಮಕ ಚಾಟ್ (ಸ್ಥಾಯಿಶೀಲ) ಆಯ್ಕೆಗಳನ್ನು ತೋರಿಸುವ ಡ್ಯಾಶ್ಬೋರ್ಡ್* -### Stateless ಚಾಟ್ (ಎಡ ಪ್ಯಾನೆಲ್) +### ರಾಜಕೀಯ ಚಾಟ್ (ಎಡ ಪ್ಯಾನಲ್) -ಮೊದಲು ಇದನ್ನು ಪ್ರಯತ್ನಿಸಿ. "ನನ್ನ ಹೆಸರು ಜಾನ್" ಎಂದು ಹೇಳಿ ನಂತರ ತಕ್ಷಣ "ನನ್ನ ಹೆಸರು ಏನು?" ಎಂದು ಕೇಳಿ. ಮಾದರಿ ನೆನಪಿರಲಾರದು ಏಕೆಂದರೆ ಪ್ರತಿ ಸಂದೇಶ ಸ್ವತಂತ್ರ. ಇದು ಮೂಲ ಭಾಷಾ ಮಾದರಿ ಏಕೀಕರಣದ ಮುಖ್ಯ ಸಮಸ್ಯೆಯನ್ನು ತೋರುತ್ತದೆ - ಯಾವುದೇ ಸಂಭಾಷಣಾ ಸಂದರ್ಭವಿಲ್ಲ. +ಮೊದಲು ಇದನ್ನು ಪ್ರಯತ್ನಿಸಿ. "ನನ್ನ ಹೆಸರು ಜಾನ್" ಎಂದು ಹೇಳಿ, ತಕ್ಷಣ "ನನ್ನ ಹೆಸರು ಏನು?" ಎಂದು ಕೇಳಿ. ಮಾದರಿ ನೆನಸುವುದಿಲ್ಲ ಏಕೆಂದರೆ ಪ್ರತಿಯೊಂದು ಸಂದೇಶವೂ ಸ್ವತಂತ್ರವಾಗಿದೆ. ಇದು ಮೂಲ ಭಾಷಾ ಮಾದರಿ ಸಂಯೋಜನೆಯ ಪ್ರಮುಖ ಸಮಸ್ಯೆಯನ್ನು ತೋರುತ್ತದೆ - ಸಂವಾದ ಸಾಂದರ್ಭಿಕತೆ ಇಲ್ಲ. Stateless Chat Demo -*AI ಹಿಂದಿನ ಸಂದೇಶದಿಂದ ನಿಮ್ಮ ಹೆಸರನ್ನು ನೆನಪಿಡಲ್ಲ* +*AI ಹಿಂದಿನ ಸಂದೇಶದಿಂದ ನಿಮ್ಮ ಹೆಸರನ್ನು ನೆನಸುವುದಿಲ್ಲ* -### Stateful ಚಾಟ್ (ಬಲ ಪ್ಯಾನೆಲ್) +### ಸ್ಥಾಯಿಶೀಲ ಚಾಟ್ (ಬಲ ಪ್ಯಾನಲ್) -ಈಗ ಇದೇ ಕ್ರಮವನ್ನು ಇಲ್ಲಿ ಪ್ರಯತ್ನಿಸಿ. "ನನ್ನ ಹೆಸರು ಜಾನ್" ಮತ್ತು "ನನ್ನ ಹೆಸರು ಏನು?" ಇದಾಗಿ ಕೇಳಿ. ಈ ಸಲ ಅದು ನೆನಪಿಡುತ್ತದೆ. ವ್ಯತ್ಯಾಸವೆಂದರೆ MessageWindowChatMemory — ಅದು ಸಂಭಾಷಣಾ ಇತಿಹಾಸವನ್ನು ಕಾಪಾಡಿ ಪ್ರತಿ ವಿನಂತಿಗೆ ಸೇರಿಸುತ್ತದೆ. ಇದು ಉತ್ಪಾದನಾ ಸಂಭಾಷಣಾ AI ಹೇಗೆ ಕೆಲಸ ಮಾಡುತ್ತದೆ. +ಈಗ ಇದೇ ಕ್ರಮವನ್ನು ಇಲ್ಲಿ ಪ್ರಯತ್ನಿಸಿ. "ನನ್ನ ಹೆಸರು ಜಾನ್" ಮತ್ತು ನಂತರ "ನನ್ನ ಹೆಸರು ಏನು?" ಇದು ನೆನಸುತ್ತದೆ. ವ್ಯತ್ಯಾಸವೆಂದರೆ MessageWindowChatMemory - ಇದು ಸಂವಾದ ಇತಿಹಾಸವನ್ನು ನಡಿಸುತ್ತಿದ್ದು ಪ್ರತಿ ವಿನಂತಿಗೆ ಸೇರಿಸುತ್ತದೆ. ಇವು ಉತ್ಪಾದನಾ ಸಂವಾದಾತ್ಮಕ AI ಹೇಗೆ ಕೆಲಸಮಾಡುತ್ತದೆ ಎಂಬುದನ್ನು ತೋರುತ್ತದೆ. Stateful Chat Demo -*AI ಮುಂಚಿತ ಸಂಭಾಷಣೆಯಲ್ಲಿ ನಿಮಗೆ ಹೆಸರನ್ನು ನೆನಪಿಡುತ್ತದೆ* +*AI ಸಂವಾದದ ಮೊದಲ ಭಾಗದಿಂದ ನಿಮ್ಮ ಹೆಸರನ್ನು ನೆನಸಿಕೊಳ್ಳುತ್ತದೆ* -ಎರಡು ಪ್ಯಾನೆಲ್‌ಗಳು ಒಂದೇ GPT-5.2 ಮಾದರಿ ಬಳಕೆಮಾಡುತ್ತವೆ. ಒಂದೇ ವ್ಯತ್ಯಾಸ ಮೆಮೊರಿ. ಇದರಿಂದ ಮೆಮೊರಿ ನಿಮ್ಮ ಅಪ್ಲಿಕೇಶನ್‌ಗೆ ಏನು ತರುತ್ತದೆ ಮತ್ತು ನಿಜ ಜೀವನದ ಪ್ರಕರಣಗಳಿಗಾಗಿ ಇದು ಏಕೆ ಅವಶ್ಯಕ ಎಂಬುದು ಸ್ಪಷ್ಟವಾಗುತ್ತದೆ. +ಎರಡೂ ಪ್ಯಾನಲ್ಗಳು ಒಂದೇ GPT-5.2 ಮಾದರಿಯನ್ನು ಬಳಸುತವೆ. ಅವುಗಳಲ್ಲಿನ ಒಂದೇ ವ್ಯತ್ಯಾಸ ಮೆಮರೀ. ಇದು ಮೆಮರೀ ನಿಮ್ಮ ಅಪ್ಲಿಕೇಶನ್‌ಗೆ ಏನು ತರಬಹುದು ಮತ್ತು ಏಕೆ ನಿಜ ಜೀವನ ಪ್ರಕರಣಗಳಿಗೆ ಅತ್ಯಾವಶ್ಯಕವೋ ಸ್ಪಷ್ಟಪಡಿಸುತ್ತದೆ. ## ಮುಂದಿನ ಹಂತಗಳು -**ಮುಂದಿನ ಘಟಕ:** [02-prompt-engineering - GPT-5.2 ಜೊತೆ ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್](../02-prompt-engineering/README.md) +**ಮುಂದಿನ ನಿಯಮ:** [02-prompt-engineering - GPT-5.2 ನೊಂದಿಗೆ ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್](../02-prompt-engineering/README.md) --- -**ನಾವಿಗೇಷನ್:** [← ಹಿಂದಿನ: Module 00 - Quick Start](../00-quick-start/README.md) | [ಮುಖ್ಯಕ್ಕೆ ಹಿಂತಿರುಗಿ](../README.md) | [ಮುಂದಿನ: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**ನ್ಯಾಸಕರು:** [← ಹಿಂದಿನ ಮುಖ್ಯ ಪುಟಕ್ಕೆ](../README.md) | [ಮುಂದಿನ: ನಿಯಮ 02 - ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್ →](../02-prompt-engineering/README.md) --- -**ಅಸ್ವೀಕಾರ**: -ಈ ದಾಖಲೆ ಎಐ ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಗಾಗಿ ಪ್ರಯತ್ನಿಸಿದರೂ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ತಪ್ಪುಗಳು ಅಥವಾ ಅಸತ್ಯತೆಗಳಿರಬಹುದು ಎಂಬದರ ಕುರಿತು ಜಾಗರೂಕರಾಗಿರಿ. ಮೂಲ ಭಾಷೆಯಲ್ಲಿ ಈ ದಾಖಲೆ ಪ್ರಧಾನ ಹಾಗೂ ಅಧಿಕೃತ ಮೂಲವಾಗಿದೆ. ಗಂಭೀರ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದ ಬಳಕೆಯಿಂದ ಉಂಟಾಗಿರುವ ಯಾವುದೇ ತಪ್ಪು ಧಾರಣೆಗಳು ಅಥವಾ ಭ್ರಮೆಗಳಿಗಾಗಿ ನಾವು ಹೊಣೆಗಾರರಲ್ಲ. +**ಅಸ್ವೀಕಾರ**: +ಈ ದಸ್ತಾವೇಜು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಯನ್ನು ಸಾಧಿಸಲು ಪ್ರಯತ್ನಿಸುತ್ತಿದ್ದರೂ, ದಯವಿಟ್ಟು ಗಮನಿಸಿ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ಅಸಡ್ಡೆಗಳು ಇರಬಹುದು. ಮೂಲ ಭಾಷೆಯಲ್ಲಿರುವ ಮೂಲ ದಸ್ತಾವೇಜು ಪ್ರಾಮಾಣಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದವನ್ನು ಬಳಸುವ ಮೂಲಕ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪು ಅರ್ಥಗಳ ಅಥವಾ ತಪ್ಪು ವ್ಯಾಖ್ಯಾನಗಳ ಬಗ್ಗೆ ನಾವು ಹೊಣೆಗಾರರಲ್ಲ. \ No newline at end of file diff --git a/translations/kn/02-prompt-engineering/README.md b/translations/kn/02-prompt-engineering/README.md index e29636701..6290e1216 100644 --- a/translations/kn/02-prompt-engineering/README.md +++ b/translations/kn/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# ಮೂಲಕೋಪ 02: GPT-5.2 ನೊಂದಿಗೆ ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ - -## ವಿಷಯಗಳ ಪಟ್ಟಿಯನ್ನು - -- [ವಿಡಿಯೋ ವಾಕ್‌ಥ್ರೂ](../../../02-prompt-engineering) -- [ನೀವು ಏನು ಕಲಿಯುತ್ತೀರಿ](../../../02-prompt-engineering) -- [ಪೂರ್ವಶರತ್ತುಗಳು](../../../02-prompt-engineering) -- [ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್‌ನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು](../../../02-prompt-engineering) -- [ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಮೂಲತತ್ತ್ವಗಳು](../../../02-prompt-engineering) - - [ಸೀ‍ರೋ-ಶಾಟ್ ಪ್ರಾಂಪ್ಟ್](../../../02-prompt-engineering) - - [ಫ್ಯೂ-ಶಾಟ್ ಪ್ರಾಂಪ್ಟ್](../../../02-prompt-engineering) - - [ಚೈನ್ ಆಫ್ಾಥ್](../../../02-prompt-engineering) - - [ಪಾತ್ರಾ ಆಧಾರಿತ ಪ್ರಾಂಪ್ಟ್](../../../02-prompt-engineering) - - [ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್ಸ್](../../../02-prompt-engineering) -- [ಅಗ್ಗತ್ಯ ಪ್ಯಾಟರ್ನ್ಗಳು](../../../02-prompt-engineering) -- [ಅಪ್ಲಿಕೇಶನ್ ಅನ್ನು ನಿರ್ವಹಿಸಿ](../../../02-prompt-engineering) -- [ಅಪ್ಲಿಕೇಶನ್ ಸ್ಕ್ರೀನ್‌ಶಾಟ್‌ಗಳು](../../../02-prompt-engineering) -- [ಪ್ಯಾಟರ್ನ್ಗಳನ್ನು ಅನ್ವೇಷಿಸುವುದು](../../../02-prompt-engineering) - - [ಕಡಿಮೆ ಮತ್ತು ಹೆಚ್ಚು ಉತ್ಸಾಹ](../../../02-prompt-engineering) - - [ಕಾರ್ಯನಿರ್ವಹಣೆ (ಟೂಲ್ ಪ್ರೀಆಂಬಲ್ಸ್)](../../../02-prompt-engineering) - - [ಸ್ವಯಂ-ಪರಿಶೀಲನ ಕೋಡ್](../../../02-prompt-engineering) - - [ಸಂರಚಿತ ವಿಶ್ಲೇಷಣೆ](../../../02-prompt-engineering) - - [ಬಹು-ಪಟ್ಟು ಚಾಟ್](../../../02-prompt-engineering) - - [ಹಂತದ ಮೂಲಕ ಕಾರಣೀಕರಣ](../../../02-prompt-engineering) - - [ನಿಬಂಧಿತ ಔಟ್‌ಪುಟ್](../../../02-prompt-engineering) -- [ನೀವು ನಿಜವಾಗಿಯೂ ಏನು ಕಲಿಯುತ್ತೀರಿ](../../../02-prompt-engineering) -- [ಮುಂದಿನ ಹೆಜ್ಜೆಗಳು](../../../02-prompt-engineering) - -## ವಿಡಿಯೋ ವಾಕ್‌ಥ್ರೂ - -ಈ ಮೋಡ್ಯೂಲ್ ಅನ್ನು ಹೇಗೆ ಪ್ರಾರಂಭಿಸಲು ಎಂಬುದನ್ನು ವಿವರಿಸುವ ಈ ಲೈವ್ ಸೆಶನ್ ಅನ್ನು ವೀಕ್ಷಿಸಿ: +# Module 02: GPT-5.2 ನೊಂದಿಗೆ ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ + +## ವಿಷಯಗಳ ಪಟ್ಟಿ + +- [ವೀಡಿಯೋ ವಾಕ್ಥ್ರೂ](#ವೀಡಿಯೋ-ವಾಕ್ಥ್ರೂ) +- [ನೀವು ಕಲಿಯುವುದೇನು](#ನೀವು-ಕಲಿಯುವುದೇನು) +- [ಆವಶ್ಯಕತೆಗಳಿವೆ](#ಆವಶ್ಯಕತೆಗಳಿವೆ) +- [ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಅನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು](#ಪ್ರಾಂಪ್ಟ್-ಎಂಜಿನಿಯರಿಂಗ್-ಅನ್ನು-ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು) +- [ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಮೂಲತತ್ವಗಳು](#ಪ್ರಾಂಪ್ಟ್-ಎಂಜಿನಿಯರಿಂಗ್-ಮೂಲತತ್ವಗಳು) + - [ಝೀરો್-ಶಾಟ್ ಪ್ರಾಂಪ್ಟಿಂಗ್](#ಝೀโร್-ಶಾಟ್-ಪ್ರಾಂಪ್ಟಿಂಗ್) + - [ಫ್ಯೂ-ಶಾಟ್ ಪ್ರಾಂಪ್ಟಿಂಗ್](#ಫ್ಯೂ-ಶಾಟ್-ಪ್ರಾಂಪ್ಟಿಂಗ್) + - [ಚೈನ್ ಆಫ್ ಥಾಟ್](#ಚೈನ್-ಆಫ್-ಥಾಟ್) + - [ರೋಲ್-ಬೇಸ್ ಪ್ರಾಂಪ್ಟಿಂಗ್](#ರೋಲ್-ಬೇಸ್-ಪ್ರಾಂಪ್ಟಿಂಗ್) + - [ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟುಗಳು](#ಪ್ರಾಂಪ್ಟ್-ಟೆಂಪ್ಲೇಟುಗಳು) +- [ಅತ್ಯಾಧುನಿಕ ಸ್ವರೂಪಗಳು](#ಅತ್ಯಾಧುನಿಕ-ಸ್ವರೂಪಗಳು) +- [ಅಪ್ಲಿಕೇಶನ್ ಚಾಲನೆ ಮಾಡಿ](#ಅಪ್ಲಿಕೇಶನ್-ಅನ್ನು-ಓಡಿಸಿ) +- [ಅಪ್ಲಿಕೇಶನ್ ಸ್ಕ್ರೀನ್‌ಶಾಟ್‌ಗಳು](#ಅಪ್ಲಿಕೇಶನ್-ಸ್ಕ್ರೀನ್‌ಶಾಟ್‌ಗಳು) +- [ಸ್ವರೂಪಗಳನ್ನು ಅನ್ವೇಷಣೆ ಮಾಡುವುದು](#ಪ್ಯಾಟರ್ನ್‌ಗಳನ್ನು-ಅನ್ವೇಷಿಸುವುದು) + - [ಕೆಳಗೂ ಮೇಲಿನ ಉತ್ಸಾಹ](#ಕಡಿಮೆ-ವಿರುದ್ಧ-ಹೆಚ್ಚು-ಆಸಕ್ತಿ) + - [ಕಾರ್ಯ ನಿರ್ವಹಣೆ (ಟೂಲ್ ಪ್ರೀಮೇಬಲ್ಸ್)](#ಕಾರ್ಯಾಚರಣೆ-ಟೂಲ್-ಪ್ರೀऐಂಬಲ್‌ಗಳು) + - [ಸ್ವ-ಪ್ರತಿಬಿಂಬಿಸುವ ಕೋಡ್](#ಸ್ವ-ಪರಿಶೀಲನೆಯ-ಕೋಡ್) + - [ಸಂರಚಿತ ವಿಶ್ಲೇಷಣೆ](#ಸೂತ್ರಬದ್ಧ-ವಿಶ್ಲೇಷಣೆ) + - [ಬಹು-ಉಳಿತಾಯ ಸಂಭಾಷಣೆ](#ಬಹು-ಟರ್ನ್-ಚಾಟ್) + - [ಹೊಂದಿಕೆ-ಹೊಂದಿಕೆಯಿಂದ ಲಾಜಿಕ್](#ಹೆಜ್ಜೆ-ಹಂತ-ಆಲೋಚನೆ) + - [ನಿಯಂತ್ರಿತ ಔಟ್‌ಪುಟ್](#ಬಂಧಿತ-ಔಟ್‌ಪುಟ್) +- [ನೀವು ನಿಜವಾಗಿಯೂ ಕಲಿಯುತ್ತಿರುವುದು](#ನೀವು-ನಿಜವಾಗಿಯೂ-ಕಲಿಯುತ್ತಿರುವುದು) +- [ಮುಂಭಾಗದ ಕ್ರಮಗಳು](#ಮುಂದಿನ-ಹಂತಗಳು) + +## ವೀಡಿಯೋ ವಾಕ್ಥ್ರೂ + +ಈ ಲೈವ್ ಸೆಷನ್ ಅನ್ನು ವೀಕ್ಷಿಸಿ ಇದು ಈ ಮೋಡ್ಯೂಲ್‌ಗೆ ಹೇಗೆ ಪ್ರಾರಂಭಿಸಲು ಎಂಬುದನ್ನು ವಿವರಿಸುತ್ತದೆ: Prompt Engineering with LangChain4j - Live Session -## ನೀವು ಏನು ಕಲಿಯುತ್ತೀರಿ +## ನೀವು ಕಲಿಯುವುದೇನು -ಕೆಳಗಿನ ಆಕರ ಚಿತ್ರದಲ್ಲಿ ಈ ಮೋಡ್ಯೂಲ್‌ನಲ್ಲಿ ನೀವು ಅಭಿವೃದ್ಧಿಪಡಿಸುವ ಪ್ರಮುಖ ವಿಷಯಗಳು ಮತ್ತು ಕೌಶಲ್ಯಗಳ ಅವಲೋಕನ ನೀಡಲಾಗಿದೆ — ಪ್ರಾಂಪ್ಟ್ ಸುಧಾರಣಾ ತಂತ್ರಗಳು ಮತ್ತು ಹಂತದ ಮೂಲಕ ಕಾರ್ಯಪ್ರವಾಹವನ್ನು ನೀವು ಅನುಸರಿಸುವ ವಿಧಾನದಿಂದ. +ಕೆಳಗಿನ ಚಿತ್ರವು ನೀವು ಈ ಮೋಡ್ಯೂಲ್‌ನಲ್ಲಿ ಅಭಿವೃದ್ಧಿಪಡಿಸುವ ಪ್ರಮುಖ ವಿಷಯಗಳು ಮತ್ತು ಕೌಶಲ್ಯಗಳ ಒಂದು ಅವಲೋಕನವನ್ನು ನೀಡುತ್ತದೆ — ಪ್ರಾಂಪ್ಟ್ ಶುದ್ಧೀಕರಣ ತಂತ್ರಗಳಿಂದ ಆರಂಭಿಸಿ ನೀವು ಅನುಸರಿಸುವ ಹಂತ-ಹಂತ ಕಾರ್ಯಪ್ರವಾಹವರೆಗೆ. What You'll Learn -ಹಿಂದಿನ ಮೋಡ್ಯೂಲ್‌ಗಳಲ್ಲಿ, ನೀವು GitHub ಮಾದರಿಗಳೊಂದಿಗೆ ಮೂಲ LangChain4j ಸಂವಹನಗಳನ್ನು ಅನ್ವೇಷಿಸಿದ್ದಾರೆ ಮತ್ತು ಹೇಗೆ ಮೆಮೊರಿ Azure OpenAI ಮೂಲಕ ಸಂಭಾಷಣಾತ್ಮಕ AIಗೆ ಅವಕಾಶ ನೀಡುತ್ತದೆ ಎಂದು ನೋಡಿದ್ದಾರೆ. ಈಗ ನಾವು ನೀವು ಹೇಗೆ ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳುತ್ತೀರಿ — ಅಂದರೆ ಪ್ರಾಂಪ್ಟ್‌ಗಳು — Azure OpenAI ನ GPT-5.2 ಬಳಕೆ ಮಾಡುವುದು ಹೇಗೆ ಎಂಬುದಾಗಿ ಗಮನವನ್ನು ನೀಡುತ್ತೇವೆ. ನೀವು ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ರೂಪಿಸುವ ರೀತಿ ಇಲ್ಲಿಯ ಪ್ರತಿಕ್ರಿಯೆಗಳ ಗುಣಮಟ್ಟದ ಮೇಲೆ ಬಹುಪಾಲಾಗಿ ಪ್ರಭಾವ ಬೀರುತ್ತದೆ. ನಾವು ಪ್ರಾಥಮಿಕ ಪ್ರಾಂಪ್ಟಿಂಗ್ ತಂತ್ರಗಳನ್ನು ಪರಿಶೀಲಿಸಿ, ನಂತರ GPT-5.2 ಯ ಸಂಪೂರ್ಣ ಸಾಮರ್ಥ್ಯಗಳನ್ನು ಬಳಸಿ восೈಸ್ ತಂತ್ರಗಳನ್ನು ಎಂಟು ಅಗ್ತ್ವ. +ಹಿಂದಿನ ಮೋಡ್ಯೂಲ್‌ನಲ್ಲಿ, ನೀವು ಹೇಗೆ ಮೆಮೊರಿ ಸಂವಾದಾತ್ಮಕ AI ಗೆ ಅನುಮತಿಸುತ್ತದೆ ಎಂಬುದನ್ನು Azure OpenAI ಸಹಿತ ಗಮನಿಸಿದಿರಿ. ಈಗ ನಾವು ಹೇಗೆ ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳುತ್ತೀರಿ - ಪ್ರಾಂಪ್ಟ್ಗಳು ಸ್ವತಂಶ - ಬಳಕೆಮಾಡುವುದು ಅನ್ನು ನೋಡುತ್ತೇವೆ, Azure OpenAI ನ GPT-5.2 ಬಳಸಿ. ನೀವು ನಿಮ್ಮ ಪ್ರಾಂಪ್ಟ್ ಗಳನ್ನು ಹೇಗೆ ರಚಿಸುವಿರಿ ಎಂಬುದು ನೀವು ಪಡೆಯುವ ಪ್ರತಿಕ್ರಿಯೆಗಳ ಗುಣಮಟ್ಟವನ್ನು ಬಹುಮುಖ್ಯವಾಗಿ ಪ್ರಭಾವಿಸುತ್ತದೆ. ನಾವು ಮೊದಲಿಗೆ ಮೂಲ ಪ್ರಾಂಪ್ಟಿಂಗ್ ತಂತ್ರಗಳನ್ನು ಪರಿಶೀಲಿಸುತ್ತೇವೆ, ನಂತರ GPT-5.2 ನ ಶಕ್ತಿಗಳನ್ನು ಸಂಪೂರ್ಣವಾಗಿ ಬಳಸುವ ಎಂಟು ಅತ್ಯಾಧುನಿಕ ಸ್ವರೂಪಗಳಿಗೆ ಹೋಗುತ್ತೇವೆ. -ನಾವು GPT-5.2 ಯನ್ನು ಬಳಸುತ್ತೇವೆ ಏಕೆಂದರೆ ಇದು ಕಾರಣೀಕರಣ ನಿಯಂತ್ರಣವನ್ನು ಪರಿಚಯಿಸುತ್ತದೆ - ನೀವು ಮಾದರಿಯನ್ನು ಉತ್ತರಿಸುವ ಮೊದಲು ಎಷ್ಟು ಚಿಂತನೆ ಮಾಡಬೇಕೆಂದು ಹೇಳಬಹುದು. ಇದು ವಿಭಿನ್ನ ಪ್ರಾಂಪ್ಟ್ ತಂತ್ರಗಳನ್ನು ಸ್ಪಷ್ಟವಾಗಿಸುತ್ತದೆ ಮತ್ತು ಯಾವಾಗ ಯಾವ ವಿಧಾನವನ್ನು ಬಳಸಬೇಕೆಂದು ತಿಳಿಯಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ. GitHub ಮಾದರಿಗಳಿಗಿಂತಲೂ Azure ಯ ಕಡಿಮೆ ದರ ಮಿತಿಗಳು GPT-5.2 ಗಾಗಿ ಲಾಭಕಾರಿಯಾಗಿವೆ. +ನಾವು GPT-5.2 ಅನ್ನು ಬಳಸುತ್ತೇವೆ ಏಕೆಂದರೆ ಇದು ಯುಕ್ತಿ ನಿಯಂತ್ರಣವನ್ನು ಪರಿಚಯಿಸುತ್ತದೆ - ನೀವು ಮಾದರಿಯೆಷ್ಟು ಯೋಚನೆ ಮಾಡಬೇಕು ಎಂದು ಹೇಳಬಹುದು. ಇದರಿಂದ ವಿಭಿನ್ನ ಪ್ರಾಂಪ್ಟಿಂಗ್ ತಂತ್ರಗಳು ಹೆಚ್ಚು ಸ್ಪಷ್ಟವಾಗುತ್ತವೆ ಮತ್ತು ನೀವು ಯಾವ ತಂತ್ರವನ್ನು ಯಾವಾಗ ಬಳಸಬೇಕು ಎಂಬುದನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಲು ಸಹಾಯವಾಗುತ್ತದೆ. -## ಪೂರ್ವಶರತ್ತುಗಳು +## ಆವಶ್ಯಕತೆಗಳಿವೆ -- ಪೂರ್ಣಗೊಳಿಸಿದ ಮೊಡ್ಯೂಲ್ 01 (Azure OpenAI ಸಂಪನ್ಮೂಲಗಳು ನಿಯೋಜಿಸಲಾಗಿದೆ) -- ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ `.env` ಫೈಲ್ ಹಾಗೂ Azure ಕ್ರೆಡೆನ್ಷಿಯಲ್ಸ್ (ಮೊಡ್ಯೂಲ್ 01 ರ `azd up` ಮೂಲಕ ರಚಿಸಲಾಗಿದೆ) +- ಪೂರ್ಣಗೊಂಡಿದೆ Module 01 (Azure OpenAI ಸಂಪನ್ಮೂಲಗಳು ನಿಯೋಜಿಸಲಾಗಿದೆ) +- ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿನ `.env` ಫೈಲ್ ಅನ್ನು Azure ಪ್ರಾಮಾಣಿಕತೆಗಳೊಂದಿಗೆ ಹೊಂದಿದೆ (`azd up` ಬಳಸಿ Module 01 ನಲ್ಲಿ ಸೃಷ್ಟಿಸಿದ) -> **ನೋಟ್:** ನೀವು ಮೊಡ್ಯೂಲ್ 01 ನ್ನು ಪೂರ್ಣಗೊಳಿಸದಿದ್ದರೆ, ಮೊದಲಿಗೆ ಅಲ್ಲಿ ನಿಯೋಜನೆ ಸೂಚನೆಗಳನ್ನು ಅನುಸರಿಸಿ. +> **ಗಮನಿಸಿ:** ನೀವು Module 01 ಅನ್ನು ಪೂರ್ಣಗೊಳಿಸದಿದ್ದರೆ, ಮೊದಲಿಗೆ ಅಲ್ಲಿನ ನಿಯೋಜನೆ ಸೂಚನೆಯನ್ನು ಅನುಸರಿಸಿ. -## ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು +## ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಅನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು -ಅದರಿಂದ ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಅರ್ಥಾತ್ ಅಸ್ಪಷ್ಟ ಸೂಚನೆಗಳು ಮತ್ತು ಸ್ಪಷ್ಟ ಸೂಚನೆಗಳ ನಡುವಿನ ವ್ಯತ್ಯಾಸವಾಗಿದೆ, ಕೆಳಗಿನ ಹೋಲಿಕೆ ಅದನ್ನು ತೋರಿಸುತ್ತದೆ. +ಮೂಲದಲ್ಲಿ, ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಅಸ್ಪಷ್ಟ ಉಪದೇಶಗಳು ಮತ್ತು ನಿಖರವಾದವುಗಳ ನಡುವಿನ ವ್ಯತ್ಯಾಸವಾಗಿದೆ, ಕೆಳಗಿನ ಹೋಲಿಕೆಯಿಂದ ಸ್ಪಷ್ಟವಾಗುತ್ತದೆ. What is Prompt Engineering? -ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಎಂದರೆ ನೀವು ಬೇಕಾದ ಫಲಿತಾಂಶಗಳನ್ನು ನಿರಂತರವಾಗಿ ಸಂಪಾದಿಸುವಂತಹ ಇನ್ಪುಟ್ ಪಠ್ಯದ ವಿನ್ಯಾಸ ಮಾಡುವುದು. ಇದು صرف ಪ್ರಶ್ನೆ ಕೇಳುವುದಕ್ಕಲ್ಲ — ಇದು ಮಾದರಿ ನೀವು ಏನು ಬಯಸುತ್ತೀರಿ ಮತ್ತು ಅದನ್ನು ಹೇಗೆ ಒದಗಿಸಬೇಕೆಂದು ಖಚಿತವಾಗುವುದಕ್ಕಾಗಿ ವಿನಂತಿಗಳನ್ನು ಆಗಟಾಲು ಮಾಡುವುದು. +ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಎಂದರೆ ನೀವು ಬೇಕಾದ ಫಲಿತಾಂಶಗಳನ್ನು ಸತತವಾಗಿ ಪಡೆಯಲು ಇನ್‌ಪುಟ್ ಪಠ್ಯವನ್ನು ರೂಪಿಸುವುದಾಗಿದೆ. ಇದು ಕೇವಲ ಪ್ರಶ್ನೆ ಕೇಳುವುದಿಲ್ಲ - ಇದು ವಿನಂತಿಗಳನ್ನು ವಿನ್ಯಾಸಗೊಳಿಸುವುದು, ಇದರಿಂದ ಮಾದರಿ ಯಾವುದು ಬೇಕು ಮತ್ತು ಹೇಗೆ ಒದಗಿಸಲು ಪರಿಪಾಟಿಯಾಗುತ್ತದೆ ಎಂಬುದನ್ನು ಸಂಪೂರ್ಣವಾಗಿ ಅర్థಮಾಡಿಕೊಳ್ಳುತ್ತದೆ. -ಇದನ್ನು ಕೆಲಸಗಾರರಿಗೆ ಸೂಚನೆ ನೀಡುವಂತೆ ಭಾವಿಸಿ. "ದೋಷವನ್ನು ಸರಿಪಡಿಸಿ" ಅಸ್ಪಷ್ಟವಾಗಿದೆ. "UserService.java ಸಾಲು 45 ರಲ್ಲಿ ನೂಲ್ ಪಾಯಿಂಟರ್ ಎಕ್ಸೆಪ್ಷನ್ ಅನ್ನು ನೂಲ್ ಚೆಕ್ ಸಿಗ್ನಲ್ ಸೇರಿಸುವ ಮೂಲಕ ಸರಿಪಡಿಸಿ" ವಿಶೇಷವಾಗಿದೆ. ಭಾಷಾ ಮಾದರಿಗಳು ಅದೇ ರೀತಿ ಕೆಲಸ ಮಾಡುತ್ತವೆ - ಸ್ಪಷ್ಟತೆ ಮತ್ತು ರೂಪರೇಖೆ ಮುಖ್ಯ. +ನೀವು ಸಹೋದ್ಯೋಗಿಗೆ ಸೂಚನೆಗಳನ್ನು ನೀಡುತ್ತಿದ್ದಂತೆ ಭಾವಿಸಿ. "ದೋಷ ಸರಿ ಮಾಡಿ" ಅಸ್ಪಷ್ಟವಾಗಿದೆ. "UserService.java ಲೈನ್ 45 ನಲ್ಲಿ ನಲ್ ಪಾಯಿಂಟರ್ ಎಕ್ಸೆಪ್ಶನ್ ಸರಿ ಮಾಡು, ನಲ್ ಚೆಕ್ ಸೇರಿಸುವ ಮೂಲಕ" ನಿಖರವಾಗಿದೆ. ಭಾಷಾ ಮಾದರಿಗಳು ಒಂದೇ ರೀತಿಯಲ್ಲಿ ಕೆಲಸ ಮಾಡುತ್ತವೆ - ನಿಖರತೆ ಮತ್ತು ರಚನೆ ಮುಖ್ಯ. -ಕೆಳಗಿನ ಚಿತ್ರ LangChain4j ಈ ಚಿತ್ರಕ್ಕೆ ಹೇಗೆ ಹೊಂದಿಕೊಳ್ಳುತ್ತದೆ ಎಂದು ತೋರಿಸುತ್ತದೆ — ನೀವು ಪ್ರಾಂಪ್ಟ್ ಮಾದರಿಗಳನ್ನು SystemMessage ಮತ್ತು UserMessage ರಚನಾ ಘಟಕಗಳ ಮೂಲಕ ಮಾದರಿಗೆ ಸಂಪರ್ಕಿಸುವುದು. +ಕೆಳಗಿನ ಚಿತ್ರವು LangChain4j ಈ ಚಿತ್ರದಲ್ಲಿ ಹೇಗೆ ಹೊಂದಿದೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ — ನಿಮ್ಮ ಪ್ರಾಂಪ್ಟ್ ಸ್ವರೂಪಗಳನ್ನು SystemMessage ಮತ್ತು UserMessage ನಿರ್ಮಾಣ ಘಟಕಗಳ ಮೂಲಕ ಮಾದರಿಯೊಂದಿಗೆ ಸಂಪರ್ಕಿಸುತ್ತದೆ. How LangChain4j Fits -LangChain4j ಮೂಲವೈಭಾಗ ಒದಗಿಸುತ್ತದೆ — ಮಾದರಿ ಸಂಪರ್ಕಗಳು, ಮೆಮೊರಿ ಮತ್ತು ಸಂದೇಶ ಪ್ರಕಾರಗಳು — ಮತ್ತು ಪ್ರಾಂಪ್ಟ್ ಮಾದರಿಗಳು ಆ ಮೂಲವೈಭಾಗದಿಂದ ಕಳುಹಿಸುವ ಕಸ್ಟಮೈಸ್ ಮಾಡಿದ ಪಠ್ಯ ಮಾತ್ರ. ಪ್ರಮುಖ ರಚನಾ ಘಟಕಗಳು `SystemMessage` (ಯಾವುದು AI ನ ವರ್ತನೆ ಮತ್ತು ಪಾತ್ರವನ್ನು ಹೊಂದಿಸುತ್ತದೆ) ಮತ್ತು `UserMessage` (ನಿಮ್ಮ ನಿಜವಾದ ವಿನಂತಿಯನ್ನು ಹೊತ್ತುಕೊಳ್ಳುವುದು). +LangChain4j ಮೂಲಭೂತ ಸೌಲಭ್ಯಗಳನ್ನು ಒದಗಿಸುತ್ತದೆ — ಮಾದರಿ ಸಂಪರ್ಕಗಳು, ಮೆಮೊರಿ ಮತ್ತು ಸಂದೇಶ ಪ್ರಕಾರಗಳು — ಮತ್ತು ಪ್ರಾಂಪ್ಟ್ ಸ್ವರೂಪಗಳು ಅದು ರಚಿಸಿದ ಪಠ್ಯವಷ್ಟೇ ಆಗಿವೆ. ಪ್ರಮುಖ ನಿರ್ಮಾಣ ಘಟಕಗಳು `SystemMessage` (ಇವು AI ನ ವರ್ತನೆ ಮತ್ತು ಪಾತ್ರವನ್ನು ಹೊಂದಿದೆ) ಮತ್ತು `UserMessage` (ನಿಮ್ಮ ನಿಜವಾದ ವಿನಂತಿಯನ್ನು ಸಾಗಿಸುತ್ತದೆ). -## ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಮೂಲತತ್ತ್ವಗಳು +## ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಮೂಲತತ್ವಗಳು -ಕೆಳಗಿನ ಐದು ಮೂಲ ತಂತ್ರಗಳು ಪರಿಣಾಮಕಾರಿಯಾದ ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ನ ಮೂಲಭೂತ ಆಧಾರವನ್ನು ರೂಪಿಸುತ್ತವೆ. ಪ್ರತಿಯೊಂದು ಭಾಷಾ ಮಾದರಿಗಳೊಂದಿಗೆ ನಿಮ್ಮ ಸಂವಹನದ ವಿಭಿನ್ನ ಅಂಶವನ್ನು ಮುಟ್ಟುತ್ತದೆ. +ಕೆಳಗಿನ ಐದು ಪ್ರಮುಖ ತಂತ್ರಗಳು ಪರಿಣಾಮಕಾರಿ ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್‌ನ ಅಡಿಪಾಯವನ್ನು ರೂಪಿಸುತ್ತವೆ. ಪ್ರತಿಯೊಂದು ಭಾಷಾ ಮಾದರಿಗಳೊಂದಿಗೆ ನೀವು ಹೇಗೆ ಸಂವಹನ ಮಾಡುತ್ತೀರಿ ಎಂಬುದರ ವಿಭಿನ್ನ ಅಂಶವನ್ನು ಈವತ್ತು ನಿರ್ಧರಿಸುತ್ತದೆ. Five Prompt Engineering Patterns Overview -ಈ ಮೊಡ್ಯೂಲ್‌ನಲ್ಲಿನ ಅಗತ್ಯ ಪ್ಯಾಟರ್ನ್ಗಳಿಗೆ ಮುನ್ನಡೆಸುವ ಮೊದಲು, ಐದು ಸಾವರ್ಹಿತ ಪ್ರಾಂಪ್ಟಿಂಗ್ ತಂತ್ರಗಳನ್ನು ಪರಿಶೀಲಿಸೋಣ. ಇವು ಪ್ರತಿ ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರ್ ತಿಳಿದಿಹಾಗಿರಬೇಕಾದ ರಚನಾ ಘಟಕಗಳು. ನೀವು ಇತ್ತmadan [Quick Start module](../00-quick-start/README.md#2-prompt-patterns) ನಲ್ಲಿ ಎಲ್ಲಾ ಅಂಶಗಳನ್ನು ನೋಡಿ ಇದ್ದೀರಿ — ಕೆಳಕಂಡ ಅವಲೋಕನ ಇವುಗಳ ಹಿಂದಿನ ಕಲ್ಪನಾ ರಚನೆ. +ಈ ಮೋಡ್ಯೂಲ್‌ನ ಅತ್ಯಾಧುನಿಕ ಸ್ವರೂಪಗಳಿಗೆ ಮುನ್ನಡೆಯುವ ಮುನ್ನ, ಒಂಭತ್ತು ಮೂಲಭೂತ ಪ್ರಾಂಪ್ಟಿಂಗ್ ತಂತ್ರಗಳನ್ನು ಪರಿಶೀಲಿಸೋಣ. ಇವು ಪ್ರತಿ ಪ್ರಮಿನ್ ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರ್ ತಿಳಿದುಕೊಳ್ಳಬೇಕಾದ ಇವು. -### ಸೀರೆ-ಶಾಟ್ ಪ್ರಾಂಪ್ಟಿಂಗ್ +### ಝೀโร್-ಶಾಟ್ ಪ್ರಾಂಪ್ಟಿಂಗ್ -ಸರಳ ಆದೇಶ: ಮಾದರಿಗೆ ಉದಾಹರಣೆಗಳಿಲ್ಲದೆ ನೇರ ಸೂಚನೆ ನೀಡುವುದು. ಮಾದರಿ ಸಂಪೂರ್ಣವಾಗಿ ತನ್ನ ತರಬೇತಿನ ಮೇಲೆ ಅವಲಂಬಿಸಿದೆ ಮತ್ತು ಕಾರ್ಯವನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಿ ಮತ್ತು ನಿರ್ವಹಿಸುತ್ತದೆ. ಕೋಷ್ಟಕ ಕಾರ್ಯಗಳಿಗೆ ಇದು ಬಹಳ ಪರಿಣಾಮಕಾರಿಯಾಗಿದೆ. +ಸರಳವಾದ ವಿಧಾನ: ಮಾದರಿಗೆ ಉದಾಹರಣೆಗಳಿಲ್ಲದೆ ನೇರ ಆದೇಶ ನೀಡುವುದು. ಮಾದರಿ ಸಂಪೂರ್ಣವಾಗಿ ತನ್ನ ತರಬೇತಿಯ ಮೇಲೆ ಅವಲಂಬಿತವಾಗಿದೆ ಕಾರ್ಯವನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಲು ಮತ್ತು ನಡೆಸಲು. ಇದು ಸರಳ ವಿನಂತಿಗಳಿಗೆ ಸೂಕ್ತವಾಗಿದೆ, ಅಲ್ಲಿ ನಿರೀಕ್ಷಿತ ವರ್ತನೆ ಸ್ಪಷ್ಟವಾಗಿದೆ. Zero-Shot Prompting -*ಉದಾಹರಣೆಗಳಿಲ್ಲದೆ ನೇರ ಸೂಚನೆ — ಮಾದರಿ ಕೇವಲ ಸೂಚನೆಯಿಂದ ಕಾರ್ಯವನ್ನು ತಿಳಿದುಕೊಳ್ಳುತ್ತದೆ* +*ಉದಾಹರಣೆ ಇಲ್ಲದ ನೇರ ಆದೇಶ — ಮಾದರಿ ಆದೇಶದಿಂದಲೇ ಕಾರ್ಯವನ್ನು ಅನುವಾದಿಸುತ್ತದೆ* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// ಪ್ರತಿಕ್ರಿಯೆ: "ಪ್ರಶಂಸಾತ್ಮಕ" +// ಪ್ರತಿಕ್ರಿಯೆ: "ಧನಾತ್ಮಕ" ``` -**ಬಳಸುವಾಗ:** ಸರಳ ವರ್ಗೀಕರಣ, ನೇರ ಪ್ರಶ್ನೆಗಳು, ಅನುವಾದಗಳು ಅಥವಾ ಯಾವುದೇ ಕಾರ್ಯ ತಾಂತ್ರಿಕ ಮಾರ್ಗದರ್ಶನವಿಲ್ಲದೆ ನಿಭಾಯಿಸಬಹುದಾದ. +**ಯಾವಾಗ ಬಳಸಬೇಕು:** ಸರಳ ವರ್ಗೀಕರಣಗಳು, ನೇರ ಪ್ರಶ್ನೆಗಳು, ಅನುವಾದಗಳು ಅಥವಾ ಯಾವುದೇ ಕಾರ್ಯಗಳು, ಮಾದರಿ ಹೆಚ್ಚುವರಿ ಮಾರ್ಗದರ್ಶನವಿಲ್ಲದೆ ನಿರ್ವಹಿಸಬಲ್ಲಾಗಬೇಕು. ### ಫ್ಯೂ-ಶಾಟ್ ಪ್ರಾಂಪ್ಟಿಂಗ್ -ನೀವು ಬಯಸುವ ಮಾದರಿಯನ್ನು ಹೊರಹಾಕುವ ಉದಾಹರಣೆಗಳನ್ನು ಒದಗಿಸಿ. ಮಾದರಿ ನಿಮ್ಮ ಉದಾಹರಣೆಗಳಿಂದ ನಿರೀಕ್ಷಿತ ಇನ್ಪುಟ್-ಔಟ್‌ಪುಟ್ ಬಗೆಯನ್ನು ಕಲಿತುಕೊಳ್ಳುತ್ತದೆ ಮತ್ತು ಹೊಸ ಇನ್ಪುಟ್‌ಗಳಿಗೆ ಅದನ್ನು ಅನ್ವಯಿಸುತ್ತದೆ. ಇದು ಬಯಸಿದ ಪ್ಯಾಟರ್ನ್ ಸ್ಪಷ್ಟವಿಲ್ಲದ ಕಾರ್ಯಗಳಿಗಾಗಿ ವೈಸರಿಕೆ ಹೆಚ್ಚಿಸುತ್ತದೆ. +ನೀವು ಅಗತ್ಯವಿರುವ ಮಾದರಿಯನ್ನು ತೋರಿಸುವ ಉದಾಹರಣೆಗಳನ್ನು ಒದಗಿಸಿ. ಮಾದರಿ ನಿಮ್ಮ ಉದಾಹರಣೆಗಳಿಂದ ನಿರೀಕ್ಷಿತ ಇನ್‌ಪುಟ್- ಔಟ್‌ಪುಟ್ ನ ಮಾದರಿಯನ್ನು ಕಲಿತುಕೊಳ್ಳುತ್ತದೆ ಮತ್ತು ಹೊಸ ಇನ್‌ಪುಟ್‌ಗಳಿಗೆ ಅದನ್ನು ಅನ್ವಯಿಸುತ್ತದೆ. ಇದರಿಂದ ನಿರಂತರತೆ ತಾಜಾ ಆದೇಶಗಳಲ್ಲೂ ಹೆಚ್ಚುತ್ತದೆ, ಮುಖ್ಯವಾಗಿ ನಿರೀಕ್ಷಿತ ಫಾರ್ಮ್ಯಾಟ್ ಅಥವಾ ವರ್ತನೆ ಸ್ಪಷ್ಟವಾಗದ ಪರಿಸ್ಥಿತಿಗಳಲ್ಲಿ. Few-Shot Prompting -*ಉದಾಹರಣೆಗಳಿಂದ ಕಲಿತ ಹಾಗೆ — ಮಾದರಿ ಪ್ಯಾಟರ್ನ್ ಗುರುತಿಸಿ ಹೊಸ ಇನ್ಪುಟ್‌ಗೆ ಅನ್ವಯಿಸುತ್ತದೆ* +*ಉದಾಹರಣೆಗಳಿಂದ ಕಲಿಯುವುದು — ಮಾದರಿ ಮಾದರಿಯನ್ನು ಗುರುತಿಸಿ ಹೊಸ ಇನ್‌ಪುಟ್‌ಗಳಿಗೆ ಅನ್ವಯಿಸುತ್ತದೆ* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**ಬಳಸುವಾಗ:** ಕಸ್ಟಮ್ ವರ್ಗೀಕರಣ, ಸಧಾರಿತ ರೂಪುರೇಷೆ, ಪ್ರಾದೇಶಿಕ ಕಾರ್ಯಗಳು, ಅಥವಾ ಸೀರೆ-ಶಾಟ್ ಫಲಿತಾಂಶಗಳು ಅಸ್ಥಿರವಾಗಿರುವಾಗ. +**ಯಾವಾಗ ಬಳಸಬೇಕು:** ಕಸ್ಟಮ್ ವರ್ಗೀಕರಣಗಳು, ನಿರಂತರ ಫಾರ್ಮ್ಯಾಟಿಂಗ್, ಕ್ಷೇತ್ರ-ನಿರ್ದಿಷ್ಟ ಕೆಲಸಗಳು, ಅಥವಾ ಝೀರೋ-ಶಾಟ್ ಫಲಿತಾಂಶಗಳು ಅಸ್ಥಿರವಾಗಿರುವಾಗ. ### ಚೈನ್ ಆಫ್ ಥಾಟ್ -ಮಾಡೆಲ್ ಹಂತ ಹಂತವಾಗಿ ನಿರ್ಣಯವನ್ನು ತೋರಿಸಲು ಕೇಳಿ. ನೇರ ಉತ್ತರ ನೀಡುವ ಬದಲು, ಮಾದರಿ ಸಮಸ್ಯೆಯನ್ನು ವಿಭಜಿಸಿ ಪ್ರತಿ ಹಂತದಲ್ಲಿ ಸ್ಪಷ್ಟವಾಗಿ ಕೆಲಸ ಮಾಡುತ್ತದೆ. ಇದು ಗಣಿತ, ತರ್ಕ, ಮತ್ತು ಬಹು-ಹಂತ ಕಾರಣೀಕರಣದ ಕಾರ್ಯಗಳಲ್ಲಿ ನಿಖರತೆಯನ್ನು ಹೆಚ್ಚಿಸುತ್ತದೆ. +ಮಾದರಿಯನ್ನು ಹಂತದ ಹಂತವಾಗಿ ತನ್ನ ಯುಕ್ತಿಕ ಚಿಂತನೆ ತೋರುವಂತೆ ಕೇಳಿ. ನೇರವಾಗಿ ಉತ್ತರಕ್ಕೆ ಹಾರದೇ, ಮಾದರಿ each ಭಾಗವನ್ನು ಸ್ಪಷ್ಟವಾಗಿ ವಿಭಾಗಿಸಿ ಪ್ರಕ್ರಿಯೆಯ ಮೂಲಕ ಹೋಗುತ್ತದೆ. ಇದು ಗಣಿತ, ತಾರ್ಕಿಕ, ಮತ್ತು ಬಹು ಹಂತದ ಯುಕ್ತಿ ಕಾರ್ಯಗಳಲ್ಲಿ ನಿಖರತೆಗೆ ಉತ್ತೇಜನ ನೀಡುತ್ತದೆ. Chain of Thought Prompting -*ಹಂತ-ಹಂತ ಕಾರಣೀಕರಣ — ಸಂಕೀರ್ಣ ಸಮಸ್ಯೆಗಳನ್ನು ಸ್ಪಷ್ಟ ತರ್ಕ ಹಂತಗಳಿಗೆ ವಿಭಜಿಸುವುದು* +*ಹಂತದಿಂದ ಹಂತಕ್ಕೆ ಯುಕ್ತಿ — ಸಂಕೀರ್ಣ პრობლემೆಗಳನ್ನು ಸ್ಪಷ್ಟ ತಾರ್ಕಿಕ ಹಂತಗಳಾಗಿ ಭಂಗಿಮಾಡುವುದು* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// ಮಾದರಿ ತೋರಿಸುತ್ತದೆ: 15 - 8 = 7, ನಂತರ 7 + 12 = 19 ಸೇಬುಗಳು +// ಮಾದರಿ ತೋರುತ್ತದೆ: 15 - 8 = 7, ನಂತರ 7 + 12 = 19 ಸೇಬುಗಳು ``` -**ಬಳಸುವಾಗ:** ಗಣಿತದ ಸಮಸ್ಯೆಗಳು, ತರ್ಕದ ಪಜಲ್‌ಗಳು, ಡಿಬಗಿಂಗ್, ಅಥವಾ ಕಾರಣೀಕರಣ ಪ್ರಕ್ರಿಯೆಯನ್ನು ತೋರಿಸುವುದರಿಂದ ನಿಖರತೆ ಮತ್ತು ವಿಶ್ವಾಸ ಹೆಚ್ಚುವ ಕಾರ್ಯಗಳು. +**ಯಾವಾಗ ಬಳಸಬೇಕು:** ಗಣಿತ ಸಮಸ್ಯೆಗಳು, ತಾರ್ಕಿಕ ಪuzzlesಗಳು, ಡಿಬಗ್ ಮಾಡುವುದು, ಅಥವಾ ಯುಕ್ತಿ ಪ್ರಕ್ರಿಯೆಯನ್ನು ತೋರುವುದು ನಿಖರತೆ ಮತ್ತು ವಿಶ್ವಾಸಯುತತೆಗೆ ಸಹಾಯ ಮಾಡುವ ಯಾವುದೇ ಕಾರ್ಯ. -### ಪಾತ್ರ ಆಧಾರಿತ ಪ್ರಾಂಪ್ಟಿಂಗ್ +### ರೋಲ್-ಬೇಸ್ ಪ್ರಾಂಪ್ಟಿಂಗ್ -ನಿಮ್ಮ ಪ್ರಶ್ನೆ ಮೊದಲು AI ಗೆ ಪಾತ್ರ ಅಥವಾ ವ್ಯಕ್ತಿತ್ವವನ್ನು ಸೆಟ್ ಮಾಡಿ. ಇದು ಪ್ರತಿಕ್ರಿಯೆಯ ಶೈಲಿ, ಆಳ ಮತ್ತು ಕೇಂದ್ರೀಕೃತತೆಗೆ ಸಾಂದರ್ಭಿಕತೆ ಒದಗಿಸುತ್ತದೆ. "ಸಾಫ್ಟ್‌ವೇರ್ ವಾಸ್ತುಶಿಲ್ಪಿ" "ಮೌಲಿಕ ಅಭಿವೃದ್ಧಿಕಾರ" ಅಥವಾ "ಸುರಕ್ಷತಾ ಪರಿಶೀಲಕ" ಇತ್ಯಾದಿಗಳಿಗಿಂತ ವಿಭಿನ್ನ ಸಲಹೆ ನೀಡುತ್ತದೆ. +AI ಗೆ ಪ್ರಶ್ನೆ ಕೇಳುವ ಮುನ್ನ ಪರ್ಸೋನ ಅಥವಾ ಪಾತ್ರವನ್ನು ಹೊಂದಿಸಿ. ಇದು ಪ್ರತಿಕ್ರಿಯೆಯ ಶೈಲಿ, ಆಳ ಮತ್ತು ಗಮನಕ್ಕೆ ಸಂದರ್ಭ ಒದಗಿಸುತ್ತದೆ. "ಸಾಫ್ಟ್‌ವೇರ್ ವಾಸ್ತುಕಾರ" "ಜೂನಿಯರ್ ಡೆವಲಪರ್" ಅಥವಾ "ಸುರಕ್ಷತಾ ಪರಿಶೀಲಕ" ಭಿನ್ನ ಸಲಹೆಗಳನ್ನು ನೀಡುತ್ತದೆ. Role-Based Prompting -*ಸಂದರ್ಭ ಮತ್ತು ವ್ಯಕ್ತಿತ್ವವನ್ನು ನಿಯೋಜಿಸುವುದು — ಅದೇ ಪ್ರಶ್ನೆಗೆ ನಿಯೋಜಿತ ಪಾತ್ರದಿಂದ ವಿಭಿನ್ನ ಪ್ರತಿಕ್ರಿಯೆ* +*ಸಂದರ್ಭ ಮತ್ತು ಪಾತ್ರವನ್ನು ಹೊಂದಿಸುವುದು — ಒಬ್ಬೇ ಪ್ರಶ್ನೆಗೆ ಸಂಬಂಧಿಸಿದ ಪಾತ್ರಕ್ಕೆ ಅನ್ವಯಿಸಿ ವಿಭಿನ್ನ ಪ್ರತಿಕ್ರಿಯೆ* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**ಬಳಸುವಾಗ:** ಕೋಡ್ ವಿಮರ್ಶೆಗಳು, ಟ್ಯೂಟೋರಿಂಗ್, ಪ್ರಾದೇಶಿಕ ವಿಶ್ಲೇಷಣೆ, ಅಥವಾ ಅತ್ಯಧಿಕ ತಜ್ಞತೆಯ ಅಥವಾ ದೃಷ್ಟಿಕೋನವಿನ ಪ್ರಕಾರ ಪ್ರತಿಕ್ರಿಯೆಗಳು ಬೇಕಾದಾಗ. +**ಯಾವಾಗ ಬಳಸಬೇಕು:** ಕೋಡ್ ಸಮೀಕ್ಷೆಗಳು, ಟ್ಯೂಟೋರಿಂಗ್, ಕ್ಷೇತ್ರ-ನಿರ್ದಿಷ್ಟ ವಿಶ್ಲೇಷಣೆ, ಅಥವಾ ನಿರ್ದಿಷ್ಟ ಪರಿಣತಿಯಿಂದ ಸಂಬಂಧವಾದ ಪ್ರತಿಕ್ರಿಯೆಗಳು ಬೇಕಾದಾಗ. -### ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್ಸ್ +### ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟುಗಳು -ಚರ ಪ್ರತ್ಯೇಕಕಗಳೊಂದಿಗೆ ಮರುಬಳಕೆ ಮಾಡಬಹುದಾದ ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ಸೃಷ್ಟಿಸಿ. ಪ್ರತಿಸಾರಿ ಪ್ರಾಂಪ್ಟ್ ಬರೆಯುವುದರ ಬದಲು, ಒಮ್ಮೆ ಟೆಂಪ್ಲೇಟನ್ನು ವ್ಯಾಖ್ಯಾನಿಸಿ ವಿಭಿನ್ನ ಮೌಲ್ಯಗಳನ್ನು ತುಂಬಿ. LangChain4j ನ `PromptTemplate` ವರ್ಗವು ಇದನ್ನು `{{variable}}` ಸಿಂಟ್ಯಾಕ್ಸ್ ಬಳಸಿ ಸುಲಭಗೊಳಿಸುತ್ತದೆ. +ಚಲನೆಯಾಗಿ ಬದಲಾಗುವ ಸ್ಥಾನಮಾನಗಳನ್ನು ಹೊಂದಿರುವ ಪುನರುಪಯೋಗಿಸುವ ಪ್ರಾಂಪ್ಟ್‌ಗಳ ರಚನೆ ಮಾಡಿ. ಪ್ರತಿಯೊಮ್ಮೆ ಹೊಸ प्रಾಂಪ್ಟ್ ಬರೆಯುವ ಬದಲು, ಒಂದು ಟೆಂಪ್ಲೇಟ್ ನ್ನು ಒಂದೇ ಬಾರಿಗೆ ನಿರ್ಧರಿಸಿ ವಿಭಿನ್ನ ಮೌಲ್ಯಗಳನ್ನು ತುಂಬಿ. LangChain4j ನ `PromptTemplate` ಕ್ಲಾಸು ಇದನ್ನು `{{variable}}` ಸಿಂಟ್ಯಾಕ್ಸಿನೊಂದಿಗೆ ಸುಲಭವಾಗಿ ಮಾಡುತ್ತದೆ. Prompt Templates -*ಚರ ಪ್ರತ್ಯೇಕಕಗಳೊಂದಿಗೆ ಮರುಬಳಕೆ ಮಾಡಬಹುದಾದ ಪ್ರಾಂಪ್ಟ್‌ಗಳು — ಒಂದು ಟೆಂಪ್ಲೇಟು, ಅನೇಕ ಬಳಕೆಗಳು* +*ಸ್ಥಾನಮಾನಗಳನ್ನು ಹೊಂದಿರುವ ಪುನರುಪಯೋಗಿಸುವ ಪ್ರಾಂಪ್ಟ್ — ಒಂದು ಟೆಂಪ್ಲೇಟ್, ಅನೇಕ ಉಪಯೋಗಗಳು* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**ಬಳಸುವಾಗ:** ವಿಭಿನ್ನ ಇನ್ಪುಟ್‌ಗಳೊಂದಿಗೆ ಮರುಬಳಕೆ ಮಾಡುವ ಪ್ರಶ್ನೆಗಳು, ಬ್ಯಾಚ್ ಪ್ರೊಸೆಸಿಂಗ್, ಮರುಬಳಕೆ ಮಾಡಬಹುದಾದ AI ಕಾರ್ಯಪ್ರವಾಹ ನಿರ್ಮಾಣ, ಅಥವಾ ಪ್ರಾಂಪ್ಟ್ ರಚನೆ ನಿಶ್ಚಿತವಾಗಿರುತ್ತದೆ ಆದರೆ ಡೇಟಾ ಬದಲಾಗುತ್ತದೆ. +**ಯಾವಾಗ ಬಳಸಬೇಕು:** ವಿಭಿನ್ನ ಇನ್‌ಪುಟ್‌ಗಳೊಂದಿಗೆ ಪುನರಾವರ್ತಿತ ಪ್ರಶ್ನೆಗಳು, ಬ್ಯಾಚ್ ಪ್ರಕ್ರಿಯೆ, ಪುನರುಪಯೋಗಿಸುವ AI ಕಾರ್ಯಪ್ರವಾಹ ನಿರ್ಮಾಣ, ಅಥವಾ ಯಾವುದೇ ಪರಿಸ್ಥಿತಿ ಇಲ್ಲಿ ಪ್ರಾಂಪ್ಟ್ ರಚನೆ ಒಂದೇ ಆದರೆ ಡೇಟಾ ಬದಲಾಗುತ್ತದೆ. --- -ಈ ಐದು ಮೂಲತತ್ತ್ವಗಳು ಬಹುಪಾಲು ಪ್ರಾಂಪ್ಟಿಂಗ್ ಕಾರ್ಯಗಳಿಗಾಗಿ ನಿಮಗೆ ಭದ್ರತಾ ಸಲಕರಣೆಗಳನ್ನು ಒದಗಿಸುತ್ತವೆ. ಈ ಮೋಡ್ಯೂಲ್ ಮುಂದಿನ ಭಾಗದಲ್ಲಿ **ಎಂಟು ಮತ್ತಷ್ಟು ಉನ್ನತ ಪ್ಯಾಟರ್ನ್ಗಳ** ಬಗ್ಗೆ ವಿವರ ನೀಡುತ್ತದೆ, ಅವು GPT-5.2 ಯ ಕಾರಣೀಕರಣ ನಿಯಂತ್ರಣ, ಸ್ವಯಂ-ಮೌಲ್ಯಾಂಕನ ಮತ್ತು ಸಂರಚಿತ ಔಟ್‌ಪುಟ್ ಸಾಮರ್ಥ್ಯಗಳನ್ನು ಬಳಸದಂತೆ. +ಈ ಐದು ಮೂಲಭೂತಗಳು ನಿಮಗೆ ಹೆಚ್ಚಿನ ಪ್ರಾಂಪ್ಟಿಂಗ್ ಕಾರ್ಯಗಳಿಗೆ ಉತ್ತಮ ಉಪಕರಣಸಮೂಹವನ್ನು ನೀಡುತ್ತದೆ. ಈ ಮೋಡ್ಯೂಲ್ ಉಳಿದ ಹಂತದಲ್ಲಿ **ಎಂಟು ಅತ್ಯಾಧುನಿಕ ಸ್ವರೂಪಗಳು** ಇದ್ದಾರೆ, ಇವು GPT-5.2 ನ ಯುಕ್ತಿ ನಿಯಂತ್ರಣ, ಸ್ವ-ಮೌಲ್ಯಮಾಪನ ಮತ್ತು ಸಂರಚಿತ ಔಟ್‌ಪುಟ್ ಸಾಮರ್ಥ್ಯಗಳನ್ನು ಬಳಸಿ. -## ಉನ್ನತ ಪ್ಯಾಟರ್ನ್ಗಳು +## ಅತ್ಯಾಧುನಿಕ ಸ್ವರೂಪಗಳು -ಮೂಲತತ್ತ್ವಗಳನ್ನು ಆವರಿಸಿದ ಮೇಲೆ, ಈ ಮೋಡ್ಯೂಲ್ ಅನ್ನು ವಿಶಿಷ್ಟಗೊಳಿಸುವ ಎಂಟು ಉನ್ನತ ಪ್ಯಾಟರ್ನ್ಗಳ ಕಡೆ ಸಾಗೋಣ. ಎಲ್ಲ ಸಮಸ್ಯೆಗಳಿಗೂ ಒಂದೇ ಉಪಾಯವಿಲ್ಲ. ಕೆಲ ಪ್ರಶ್ನೆಗಳು ತ್ವರಿತ ಉತ್ತರಗಳನ್ನು ಬೇಕು, ಇನ್ನಷ್ಟು ವಿಚಾರಪಾವತಿಯನ್ನು ಬ್ಯಾಂಕುಗೊಳ್ಳಲಿರುವ ಇರುತ್ತವೆ. ಕೆಲವೊಂದು ಕಾರಣೀಕರಣವನ್ನು ನೋಡಬೇಕು, ಇನ್ನು केही ಗುರ್ತಿಸಿದ ಫಲಿತಾಂಶ ಬೇಕು. ಕೆಳಗಿನ ಪ್ರತಿ ಪ್ಯಾಟರ್ನ್ ವಿಭಿನ್ನ ಸಂದರ್ಭಗಳಿಗೆ ಅನೂಗುಂಟಗೊಳಿಸಲಾಗಿದೆ — ಮತ್ತು GPT-5.2 ಯ ಕಾರಣೀಕರಣ ನಿಯಂತ್ರಣವು ಈ ವ್ಯತ್ಯಾಸಗಳನ್ನು ಇನ್ನಷ್ಟು ಸ್ಪಷ್ಟಗೊಳಿಸುತ್ತದೆ. +ಮೂಲಭೂತಗಳನ್ನು ಮುಗಿಸಿದ ನಂತರ, ಈ ಮೋಡ್ಯೂಲ್ ಅನ್ನು ವಿಶಿಷ್ಟ ಮಾಡಿರುವ ಎಂಟು ಅತ್ಯಾಧುನಿಕ ಸ್ವರೂಪಗಳಿಗೆ ಸಾಗೋಣ. ಎಲ್ಲಾ ಸಮಸ್ಯೆಗಳಿಗೆ ಒಂದೇ ವಿಧಾನ ಬೇಕಾಗುವುದಿಲ್ಲ. ಕೆಲವು ಪ್ರಶ್ನೆಗಳು ಸುಲಭ ಉತ್ತರಗಳನ್ನು ಬೇಡುತ್ತವೆ, ಮತ್ತಷ್ಟು ಆಳವಾದ ಯುಕ್ತಿಯನ್ನು ಅಗತ್ಯವಿದೆ. ಕೆಲವು ಸ್ಪಷ್ಟ ಯುಕ್ತಿಯನ್ನು ತೋರಬೇಕು, ಇನ್ನಿತರ ಪ್ರಶ್ನೆಗಳು ಫಲಿತಾಂಶಗಳನ್ನು ಮಾತ್ರ ಬಯಸುತ್ತವೆ. ಕೆಳಗಿನ ಪ್ರತಿಯೊಂದು ಸ್ವರೂಪವು ವಿಭಿನ್ನ ಪರಿಸ್ಥಿತಿಗೆ ಅನುಗುಣವಾಗಿದೆ — ಮತ್ತು GPT-5.2 ಯುಕ್ತಿ ನಿಯಂತ್ರಣ ವ್ಯತ್ಯಾಸಗಳನ್ನು ಇನ್ನೂ ಸ್ಪಷ್ಟಗೊಳಿಸುತ್ತದೆ. Eight Prompting Patterns -*ಹೊರಗಿನ ಎಂಟು ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಪ್ಯಾಟರ್ನ್ಗಳ ಮತ್ತು ಅವುಗಳ ಬಳಕೆ ಉಪಾಯಗಳ ಅವಲೋಕನ* +*ಎಂಟು ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ ಸ್ವರೂಪಗಳ ಅವಲೋಕನ ಮತ್ತು ಅವುಗಳ ಉಪಯೋಗಗಳು* -GPT-5.2 ಈ ಪ್ಯಾಟರ್ನ್ಗಳಿಗೆ ಮತ್ತೊಂದು ಆಯಾಮವನ್ನು ಸೇರಿಸಿದೆ: *ಕಾರಣೀಕರಣ ನಿಯಂತ್ರಣ*. ಕೆಳಗಿನ ಸ್ಲೈಡರ್ ಮೂಲಕ ನೀವು ಮಾದರಿಯ ಚಿಂತನೆಯ ಮೌಲ್ಯವನ್ನು ಹೊಂದಿಸಬಹುದು — ತ್ವರಿತ ನೇರ ಉತ್ತರಗಳಿಂದ ಆಳವಾದ ಸರಿಯಾದ ವಿಶ್ಲೇಷಣೆಯವರೆಗೆ. +GPT-5.2 ಈ ಸ್ವರೂಪಗಳಿಗೆ ಇನ್ನೊಂದು ಆಯಾಮವನ್ನು ಸೇರಿಸಿದೆ: *ಯುಕ್ತಿ ನಿಯಂತ್ರಣ*. ಕೆಳಗಿನ ಸ್ಲೈಡರ್ ಮಾದರಿಯ ಯೋಚನಾ ಶ್ರಮವನ್ನು ಹೊಂದಿಸಲು ನಿಮಗೆ ಸಾಧ್ಯವಾಗುತ್ತದೆ — ತ್ವರಿತ, ನೇರ ಉತ್ತರಗಳಿಂದ ಆಳವಾದ ವಿಶ್ಲೇಷಣೆಗೆ. Reasoning Control with GPT-5.2 -*GPT-5.2 ಯ ಕಾರಣೀಕರಣ ನಿಯಂತ್ರಣವು ನಿಮಗೆ ಮಾದರಿ ಎಷ್ಟು ಚಿಂತಿಸಬೇಕೆಂದು ವಿವರಿಸಲು ಅನುಮತಿಸುತ್ತದೆ — ವೇಗದ ನೇರ ಉತ್ತರಗಳಿಂದ ಆಳವಾದ ಅನ್ವೇಷಣೆ ತನಕ* +*GPT-5.2 ಯುಕ್ತಿ ನಿಯಂತ್ರಣವು ನಿಮಗೆ ಮಾದರಿಗೆಷ್ಟು ಯೋಚನೆ ಮಾಡುವುದು ಮಾರ್ಪಡಿಸಲು ಅವಕಾಶ ನೀಡುತ್ತದೆ — ಶೀಘ್ರ ನೇರ ಉತ್ತರರಿಂದ ಆಳವಾದ ಅನ್ವೇಷಣೆಗೆ* -**ಕಡಿಮೆ ಉತ್ಸಾಹ (ತ್ವರಿತ ಮತ್ತು ಕೆಂದ್ರಿತ)** - ಸ್ಥೂಲ ಪ್ರಶ್ನೆಗಳಿಗೆ ನೀವು ವೇಗದ, ನೇರ ಉತ್ತರಗಳನ್ನು ಬಯಸುವಾಗ. ಮಾದರಿ ಅಲ್ಪವಾದ ಕಾರಣೀಕರಣವನ್ನು ಮಾಡುತ್ತದೆ - ಗರಿಷ್ಠ 2 ಹಂತಗಳು. ಲೆಕ್ಕಾಚಾರ, ಹುಡುಕಾಟ ಅಥವಾ ನೇರ ಪ್ರಶ್ನೆಗಳಿಗೆ ಇದನ್ನು ಬಳಸಿ. +**ಕಡಿಮೆ ಉತ್ಸಾಹ (ತ್ವರಿತ ಮತ್ತು ಕೇಂದ್ರೀಕೃತ)** - ಸರಳ ಪ್ರಶ್ನೆಗಳಿಗಾಗಿ ಶೀಘ್ರ, ನೇರ ಉತ್ತರ ಬೇಕಾದಾಗ. ಮಾದರಿ ಕನಿಷ್ಠ ಯುಕ್ತಿ ಮಾಡುತ್ತದೆ - ಗರಿಷ್ಠ 2 ಹಂತಗಳು. ಇದನ್ನು ಗಣನೆಗಳು, ಹುಡುಕಾಟಗಳು, ಅಥವಾ ಸರಳ ಪ್ರಶ್ನೆಗಳಿಗಾಗಿ ಉಪಯೋಗಿಸಿ. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **GitHub Copilot ಸಹಾಯದಿಂದ ಅನ್ವೇಷಿಸಿ:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: -> - "ಕಡಿಮೆ ಉತ್ಸಾಹ ಮತ್ತು ಹೆಚ್ಚಿನ ಉತ್ಸಾಹ ಪ್ರಾಂಪ್ಟ್ ಪ್ಯಾಟರ್ನ್ಗಳ ಮಧ್ಯೆ ಏನು ಭೇದವಿದೆ?" -> - "ಪ್ರಾಂಪ್ಟ್‌ಗಳಲ್ಲಿ XML ಟ್ಯಾಗ್ಗಳು AI ಯ ಪ್ರತಿಕ್ರಿಯೆಯ ರಚನೆಯಲ್ಲಿ ಹೇಗೆ ಸಹಾಯಕವಾಗುತ್ತವೆ?" -> - "ಸ್ವಯಂ-ಪರಿಶೀಲನೆ ಪ್ಯಾಟರ್ನ್ಗಳನ್ನು ಮತ್ತು ನೇರ ಸೂಚನೆಗಳನ್ನು ಯಾವಾಗ ಬಳಸಬೇಕು?" +> 💡 **GitHub Copilot ನೊಂದಿಗೆ ಅನ್ವೇಷಿಸಿ:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: +> - "ಕಡಿಮೆ ಉತ್ಸಾಹ ಮತ್ತು ಹೆಚ್ಚು ಉತ್ಸಾಹ ಪ್ರಾಂಪ್ಟಿಂಗ್ ಸ್ವರೂಪಗಳ ನಡುವೆ ಏನು ವ್ಯತ್ಯಾಸವಿದೆ?" +> - "ಪ್ರಾಂಪ್ಟ್ಗಳಲ್ಲಿ XML ಟ್ಯಾಗ್ ಗಳು AI ಪ್ರತಿಕ್ರಿಯೆಯ ರಚನೆಯನ್ನು ಹೇಗೆ ಸಹಾಯ ಮಾಡುತ್ತವೆ?" +> - "ಸ್ವ-ಪ್ರತಿಬಿಂಬಿಸುವ ಸ್ವರೂಪಗಳು ಮತ್ತು ನೇರ ಆದೇಶಗಳ დროს ಯಾವಾಗ ಯಾವನ್ನು ಬಳಸಬೇಕು?" -**ಹೆಚ್ಚಿನ ಉತ್ಸಾಹ (ಆಳವಾದ ಮತ್ತು ಸಂಪೂರ್ಣ)** - ಸಂಕೀರ್ಣ ಸಮಸ್ಯೆಗಳಿಗೆ നിങ്ങൾ ಬಹುಮಟ್ಟಿನ ವಿಶ್ಲೇಷಣೆಯನ್ನು ಬಯಸುವಾಗ. ಮಾದರಿ ಆಳವಾಗಿ ಅನ್ವೇಷಿಸಿ ವಿವರವಾದ ಕಾರಣೀಕರಣವನ್ನು ತೋರಿಸುತ್ತದೆ. ಇದು ಸಿಸ್ಟಮ್ ಡಿಸೈನ್, ವಾಸ್ತುಶಿಲ್ಪ ತೀರ್ಮಾನಗಳು ಅಥವಾ ಸಂಕೀರ್ಣ ಸಂಶೋಧನೆಗಳಿಗೆ ಸೂಕ್ತ. +**ಹೆಚ್ಚು ಉತ್ಸಾಹ (ಆಳವಾದ ಮತ್ತು ಸಂಪೂರ್ಣ)** - ಸಂಕೀರ್ಣ ಸಮಸ್ಯೆಗಳಿಗಾಗಿ ಸಮಗ್ರ ವಿಶ್ಲೇಷಣೆ ಬೇಕಾದಾಗ. ಮಾದರಿ ಆಳವಾಗಿ ಅನ್ವೇಷಣೆ ಮಾಡುತ್ತದೆ ಮತ್ತು ವಿವರವಾದ ಯುಕ್ತಿಯನ್ನು ತೋರುತ್ತದೆ. ಇದನ್ನು ಸಿಸ್ಟಂ ವಿನ್ಯಾಸ, ವಾಸ್ತುಶಿಲ್ಪ ನಿರ್ಣಯಗಳು, ಅಥವಾ ಸಂಕೀರ್ಣ ಸಂಶೋಧನೆಗಳಿಗಾಗಿಯೂ ಉಪಯೋಗಿಸಿ. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**ಕಾರ್ಯನಿರ್ವಹಣೆ (ಹಂತಿಂದ ಹಂತದ ಪ್ರಗತಿ)** - ಬಹು ಹಂತ ಕಾರ್ಯಪ್ರವಾಹಗಳಿಗಾಗಿ. ಮಾದರಿ ಮುಂಚಿತ ಯೋಜನೆಯನ್ನು ಒದಗಿಸಿ, ಪ್ರತಿ ಹಂತವನ್ನು ಕೆಲಸ ಮಾಡುತ್ತಲೇ ವಿವರಿಸುತ್ತಾಳೆ ಮತ್ತು ನಂತರ ಸಾರಾಂಶ ನೀಡುತ್ತದೆ. ಇದು ಮೈಗ್ರೇಷನ್, ಅನುಷ್ಠಾನ ಅಥವಾ ಯಾವುದೇ ಬಹು ಹಂತ ಪ್ರಕ್ರಿಯೆಗೆ ಸೂಕ್ತ. +**ಕಾರ್ಯ ನಿರ್ವಹಣೆ (ಹಂತ ಹಂತವಾಗಿ ಪ್ರಗತಿ)** - ಬಹು ಹಂತ ಕಾರ್ಯಗಳಿಗೆ. ಮಾದರಿ ಮುಂಚಿತ ಯೋಜನೆಯನ್ನು ಒದಗಿಸುತ್ತದೆ, ಪ್ರತಿ ಹಂತವನ್ನು ಕಾರ್ಯಾಚರಿಸುತ್ತಾ ವರ್ಣಿಸುತ್ತದೆ, ನಂತರ ಸಾರಾಂಶ ನೀಡುತ್ತದೆ. ಇದನ್ನು ಮೈಗ್ರೇಷನ್, ಅನುಷ್ಠಾನಗಳು ಅಥವಾ ಯಾವುದೇ ಬಹು ಹಂತ ಪ್ರಕ್ರಿಯೆಗೆ ಉಪಯೋಗಿಸಿ. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ಚೈನ್-ಆಫ್-ಥಾಟ್ ಪ್ರಾಂಪ್ಟಿಂಗ್ ಸ್ಪಷ್ಟವಾಗಿ ಕಾರಣೀಕರಣ ಪ್ರಕ್ರಿಯೆಯನ್ನು ತೋರಿಸಲು ಮಾದರಿಯನ್ನು ಕೇಳುತ್ತದೆ, ಇದು ಸಂಕೀರ್ಣ ಕಾರ್ಯಗಳಲ್ಲಿ ನಿಖರತೆಯನ್ನು ಹೆಚ್ಚಿಸುತ್ತದೆ. ಹಂತ-ಹಂತ ಬೃಹತ್ ಅನುಸರಿಸುವುದು ಮನುಷ್ಯ ಮತ್ತು AI ಎರಡಕ್ಕೂ ತರ್ಕವನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಲು ಸಹಾಯಮಾಡುತ್ತದೆ. +ಚೈನ್-ಆಫ್-ಥಾಟ್ ಪ್ರಾಂಪ್ಟಿಂಗ್ ಸ್ಪಷ್ಟವಾಗಿ ಮಾದರಿಯಿಂದ ಅದರ ಯುಕ್ತಿ ಪ್ರಕ್ರಿಯೆಯನ್ನು ತೋರುವಂತೆ ಹೇಳುತ್ತದೆ, ಸಂಕೀರ್ಣ ಕಾರ್ಯಗಳಿಗೆ ನಿಖರತೆಯನ್ನು ನೋಡಿಕೊಳ್ಳುತ್ತದೆ. ಹಂತ-ಹಂತವಾಗಿ ಭಂಗಿಮಾಡುವುದು ಮನುಷ್ಯರು ಮತ್ತು AI ಗೆ ತಾರ್ಕಿಕವನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಲು ಸಹಾಯವಾಗುತ್ತದೆ. -> **🤖 GitHub Copilot ಚಾಟ್ ಸಹಿತ ಪ್ರಯತ್ನಿಸಿ:** ಈ ಪ್ಯಾಟರ್ನ್ ಕುರಿತು ಕೇಳಿ: -> - "ದೀರ್ಘಕಾಲಚಾರಿ ಕಾರ್ಯಗಳಿಗಾಗಿ ಕಾರ್ಯನಿರ್ವಹಣಾ ಮಾದರಿಯನ್ನು ನಾನು ಹೇಗೆ ಹೊಂದಿಸಬಹುದು?" -> - "ಉತ್ಪಾದನೆ ಅಪ್ಲಿಕೇಶನ್‌ಗಳಲ್ಲಿ ಟೂಲ್ ಪ್ರೀಆಂಬಲ್ಸ್ ಅನ್ನು ನಿರ್ಮಿಸುವ ಉತ್ತಮ ಪರಿಕಲ್ಪನೆಗಳು ಏನು?" -> - "UI ನಲ್ಲಿ ಮಧ್ಯಂತರ ಪ್ರಗತಿ ನವೀಕರಣಗಳನ್ನು ಹೇಗೆ ಹಿಡಿಯಬಹುದು ಮತ್ತು ಪ್ರದರ್ಶಿಸಬಹುದು?" +> **🤖 GitHub Copilot ಚಾಟ್ ಬಳಸಿ ಪ್ರಯತ್ನಿಸಿ:** ಈ ಸ್ವರೂಪ ಕುರಿತು ಕೇಳಿ: +> - "ನಾನು ಹಳೇ ಕಾರ್ಯ ನಿರ್ವಹಣೆ ಸ್ವರೂಪವನ್ನು ದೀರ್ಘ ಸಮಯದ ಕಾರ್ಯಗಳಿಗೆ ಹೇಗೆ ಹೊಂದಿಸಬಹುದು?" +> - "ಪ್ರೊಡಕ್ಷನ್ ಅಪ್ಲಿಕೇಶನ್ಗಳಲ್ಲಿ ಟೂಲ್ ಪ್ರೀಮೇಬಲ್‌ಗಳು ರಚನೆಗಾಗಿ ಉತ್ತಮ ಅಭ್ಯಾಸಗಳು ಯಾವುವು?" +> - "ನಾನು ಮಧ್ಯಸ್ಥ ಪ್ರಗತಿ ಅಪ್‌ಡೇಟ್ಗಳನ್ನು UI ನಲ್ಲಿ ಹೇಗೆ ಹಿಡಿದು ಮತ್ತು ತೋರಿಸಬಹುದು?" -ಕೆಳಗಿನ ಆಕರ ಚಿತ್ರವು ಈ ಯೋಜನೆ → ಕಾರ್ಯನಿರ್ವಹಣೆ → ಸಾರಾಂಶ ಕಾರ್ಯಪ್ರವಾಹವನ್ನು ಸಾಂದರ್ಭಿಕಗೊಳಿಸುತ್ತದೆ. +ಕೆಳಗಿನ ಚಿತ್ರವು ಈ ಯೋಜನೆ → ನಿರ್ವಹಣೆ → ಸಾರಾಂಶ ಕಾರ್ಯಪ್ರವಾಹವನ್ನು ತೋರಿಸುತ್ತದೆ. Task Execution Pattern -*ಯೋಜನೆ → ಕಾರ್ಯನಿರ್ವಹಣೆ → ಸಾರಾಂಶ ಬಹು ಹಂತದ ಕಾರ್ಯಗಳಿಗಾಗಿ* +*ಹಂತ ಹಂತ ಕಾರ್ಯಗಳಿಗೆ ಯೋಜನೆ → ನಿರ್ವಹಣೆ → ಸಾರಾಂಶ ಕಾರ್ಯಪ್ರವಾಹ* -**ಸ್ವಯಂ-ಪರಿಶೀಲನ ಕೋಡ್** - ಉತ್ಪಾದನಾ ಗುಣಮಟ್ಟದ ಕೋಡ್ ರಚನೆಗೆ. ಮಾದರಿ ಉತ್ಪಾದನಾ ಮಾನದಂಡಗಳು ಮತ್ತು ಸರಿಯಾದ ದೋಷ ನಿರ್ವಹಣೆಗೆ ಅನುಗುಣವಾಗಿ ಕೋಡ್ ರಚಿಸುತ್ತದೆ. ಹೊಸ ವೈಶಿಷ್ಟ್ಯಗಳು ಅಥವಾ ಸೇವೆಗಳನ್ನು ನಿರ್ಮಿಸುವಾಗ ಬಳಸಿ. +**ಸ್ವ-ಪ್ರತಿಬಿಂಬಿಸುವ ಕೋಡ್** - ಉತ್ಖಲಿತ ಗುಣಮಟ್ಟದ ಕೋಡ್ ರಚನೆಗೆ. ಮಾದರಿ ಉತ್ಪಾದನಾ ಮಟ್ಟದ ಕೋಡ್‌ನ್ನು ರಚಿಸುತ್ತದೆ, ಸರಿ ದೋಷ ನಿರ್ವಹಣೆಯೊಂದಿಗೆ. ಹೊಸ ವೈಶಿಷ್ಟ್ಯಗಳು ಅಥವಾ ಸೇವೆಗಳ ನಿರ್ಮಾಣಕ್ಕೆ ಬಳಸು. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ಕೆಳಗಿನ ಆಕರ ಚಿತ್ರವು ಈ ಪುನರಾವೃತ್ತಿ ಸುಧಾರಣಾ ವಲಯವನ್ನು ತೋರಿಸುತ್ತದೆ — ರಚಿಸಿ, ಮೌಲ್ಯಾಂಕನ ಮಾಡಿ, ದುರ್ಬಲತೆಗಳನ್ನು ಗುರುತಿಸಿ ಮತ್ತು ಕೋಡ್ ಉತ್ಪಾದನಾ ಮಾನದಂಡಗಳಿಗೆ ಹೊಂದುವವರೆಗೆ ಸುಧಾರಿಸಿ. +ಕೆಳಗಿನ ಚಿತ್ರದಲ್ಲಿ ಈ ಪುರಸ್ಕೃತ ಸುಧಾರಣೆ ಲೂಪ್ ಅನ್ನು ತೋರಿಸಲಾಗಿದೆ — ರಚಿಸಿ, ಮೌಲ್ಯಮಾಪನ ಮಾಡಿ, ದುರ್ಬಲತೆಗಳನ್ನು ಗುರುತಿಸಿ, ಮತ್ತು ಕೋಡ್ ಉತ್ಪಾದನಾ ಮಾನದಂಡಗಳನ್ನು ಪೂರೈಸುವವರೆಗೆ ಪರಿಷ್ಕರಿಸಿ. Self-Reflection Cycle -*ಪುನರಾವೃತ್ತಿ ಸುಧಾರಣೆಯ ಸರಣಿ - ರಚಿಸಿ, ಮೌಲ್ಯಾಂಕನ ಮಾಡಿ, ಸಮಸ್ಯೆಗಳನ್ನು ಗುರುತಿಸಿ, ಸುಧಾರಿಸಿ, ಪುನರಾವೃತ್ತಿ ಮಾಡಿರಿ* +*ಪುನರಾವರ್ತಿತ ಸುಧಾರಣೆ ಲೂಪ್ - ರಚನೆ, ಮೌಲ್ಯಮಾಪನ, ಸಮಸ್ಯೆ ಗುರುತು, ಸುಧಾರಣೆ, ಪುನರಾವರ್ತನೆ* -**ಸಂರಚಿತ ವಿಶ್ಲೇಷಣೆ** - ಸ್ಥಿತಿಗತ ಮೌಲ್ಯಾಂಕನಕ್ಕಾಗಿ. ಮಾದರಿ ಕೋಡಿಯ ಪರಿಶೀಲನೆಯನ್ನು ನಿಶ್ಚಿತವಾದ ರಚನೆ (ತಪ್ಪು, ಅಭ್ಯಾಸಗಳು, ಕಾರ್ಯಕ್ಷಮತೆ, ಸುರಕ್ಷತೆ, ನಿರ್ವಹಣಾ ಸಾಮರ್ಥ್ಯ) ಅನುಸರಿಸಿ ಮಾಡುತ್ತದೆ. ಕೋಡ್ ವಿಮರ್ಶೆ ಅಥವಾ ಗುಣಮಟ್ಟ ಮೌಲ್ಯಾಂಕನಗಳಿಗೆ ಇದನ್ನು ಬಳಸಿ. +**ಸಂರಚಿತ ವಿಶ್ಲೇಷಣೆ** - ನಿರಂತರ ಮೌಲ್ಯಮಾಪನಕ್ಕೆ. ಮಾದರಿ ಕೋಡ್‌ಗಳನ್ನು ಸ್ಥಿರ ಫ್ರೇಮ್‌ವರ್ಕ್ (ಸರಿಯಾದಿಕೆ, ಅಭ್ಯಾಸಗಳು, ಕಾರ್ಯಕ್ಷಮತೆ, ಭದ್ರತೆ, ನಿರ್ವಹಣೆ) ಬಳಸಿ ವಿಮರ್ಶಿಸುತ್ತದೆ. ಕೋಡ್ ವಿಮರ್ಶೆಗಳು ಅಥವಾ ಗುಣಮಟ್ಟ ನಿರ್ಣಯಗಳಿಗೆ ಉಪಯೋಗಿಸಿ. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 GitHub Copilot ಚಾಟ್ ಮೂಲಕ ಪ್ರಯತ್ನಿಸಿ:** ಸಂರಚಿತ ವಿಶ್ಲೇಷಣೆ ಕುರಿತು ಕೇಳಿ: -> - "ವಿಭಿನ್ನ ಕೋಡ್ ವಿಮರ್ಶೆಗಳಿಗಾಗಿ ವಿಶ್ಲೇಷಣಾ ಚಟುವಟಿಕೆಯನ್ನು ನಾನು ಹೇಗೆ ಕಸ್ಟಮೈಸ್ ಮಾಡಬಹುದು?" -> - "ಸಂರಚಿತ ಔಟ್‌ಪುಟ್ ಅನ್ನು ಪ್ರೋಗ್ರಾಮ್ ಮೂಲಕ ಪಾರ್ಸ್ ಮಾಡಿ ಕ್ರಿಯಾತ್ಮಕಗೊಳಿಸುವ ಉತ್ತಮ ವಿಧಾನವೇನು?" -> - "ವಿಭಿನ್ನ ವಿಮರ್ಶಾ ಸೆಷನ್‌ಗಳಲ್ಲಿನ ತೀವ್ರತೆ ಮಟ್ಟಗಳನ್ನು ಸ್ಥಿರವಾಗಿರಿಸುವುದು ಹೇಗೆ?" +> **🤖 GitHub Copilot ಚಾಟ್ ಬಳಸಿ ಪ್ರಯತ್ನಿಸಿ:** ಸಂರಚಿತ ವಿಶ್ಲೇಷಣೆ ಕುರಿತು ಕೇಳಿ: +> - "ನಾನು ವಿಭಿನ್ನ ಕೋಡ್ ವಿಮರ್ಶೆ ಪ್ರಕಾರಗಳಿಗೆ ವಿಶ್ಲೇಷಣಾ ಫ್ರೇಮ್‌ವರ್ಕ್ ಅನ್ನು ಹೇಗೆ ಕಸ್ಟಮೈಸ್ ಮಾಡಬಹುದು?" +> - "ಸಂರಚಿತ ಔಟ್‌ಪುಟ್ ಅನ್ನು ಪ್ರೋಗ್ರಾಮಾಟಿಕವಾಗಿ ಪಾರ್ಸ್ ಮಾಡಿ ನಡೆಯಿಸುವ ಉತ್ತಮ ಮಾರ್ಗವೇನು?" +> - "ನಾನು ವಿಭಿನ್ನ ವಿಮರ್ಶಾ ಅವಧಿಗಳಲ್ಲಿ ಸ್ಥಿರ ತೀವ್ರತಾ ಮಟ್ಟಗಳನ್ನು ಹೇಗೆ ಖಾತ್ರಿ ಪಡಿಸಬಹುದು?" -ಕೆಳಗಿನ ಚಿತ್ರವು ಈ ಸಂರಚಿತ ಚಟುವಟಿಕೆಯು ಕೋಡ್ ವಿಮರ್ಶೆಯನ್ನು ತೀವ್ರತೆ ಮಟ್ಟಗಳೊಂದಿಗೆ ಸುರಕ್ಷಿತ ವರ್ಗಗಳಾಗಿ ಹೇಗೆ ಸಂಘಟಿಸುತ್ತದೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ. +ಕೆಳಗಿನ ಚಿತ್ರವು ಈ ಸಂರಚಿತ ಫ್ರೇಮ್‌ವರ್ಕ್ ಹೇಗೆ ಕೋಡ್ ವಿಮರ್ಶೆಯನ್ನು ಸ್ಥಿರ ವರ್ಗಗಳಲ್ಲಿ ಮತ್ತು ತೀವ್ರತಾ ಮಟ್ಟಗಳೊಂದಿಗೆ ಆಯೋಜಿಸುತ್ತದೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ. Structured Analysis Pattern -*ತೀವ್ರತೆ ಮಟ್ಟಗಳೊಂದಿಗೆ ಸ್ಥಿರ ಕೋಡ್ ವಿಮರ್ಶೆಗಳ ಚಟುವಟಿಕೆ ಚಟುವಟಿಕೆ* +*ತೀವ್ರತಾ ಮಟ್ಟಗಳಿಂದ ಸ್ಥಿರ ಕೋಡ್ ವಿಮರ್ಶೆಗಳಿಗಾಗಿ ಫ್ರೇಮ್‌ವರ್ಕ್* -**ಬಹು-ಪಟ್ಟು ಚಾಟ್** - ಸಂದರ್ಶನಗಳು ಸಧಾನ ಬೇಕಾಗುವಾಗ. ಮಾದರಿ ಹಿಂದಿನ ಸಂದೇಶಗಳನ್ನು ನೆನಪಿನಲ್ಲಿ ಇಡುತ್ತದೆ ಮತ್ತು ಅವನ್ನು ಆಧರಿಸಿ ಸಂವಹನ ಸ್ಥಾಪಿಸುತ್ತದೆ. ಇಂಟರ್ಯಾಕ್ಟಿವ್ ಸಹಾಯ ಸೆಷನ್‌ಗಳು ಅಥವಾ ಸಂಕೀರ್ಣ ಪ್ರಶ್ನೆ-ಉತ್ತರಗಳಿಗೆ ಬಹುಪಟ್ಟು ಚಾಟ್ ಬಳಸಿ. +**ಬಹು-ಉಳಿತಾಯ ಸಂಭಾಷಣೆ** - ಸಂದರ್ಭ ಬೇಕಾದ ಸಂಭಾಷಣೆಗಳಿಗೆ. ಮಾದರಿ ಹಿಂದಿನ ಸಂದೇಶಗಳನ್ನು ನೆನಪಿನಲ್ಲಿ ಇಟ್ಟುಕೊಂಡು ಅವುಗಳ ಮೇಲೆ ಕಟ್ಟಿಕೊಳುತ್ತದೆ. ಸಹಾಯ ಆಧಾರಿತ ಪರಸ್ಪರ ಸಹಾಯಕ ಸೆಶನ್ಗಳು ಅಥವಾ ಸಂಕೀರ್ಣ ಪ್ರಶ್ನೋತ್ತರಗಳಿಗೆ ಉಪಯೋಗಿಸಿ. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -ಕೆಳಗಿನ ಆಕರ ಚಿತ್ರವು ಸಂಭಾಷಣೆಯ ಸಧಾನವು ಪ್ರತಿ ತಿರುವಿನಲ್ಲಿ ಹೇಗೆ ಸಂಗ್ರಹವಾಗುತ್ತದೆ ಮತ್ತು ಇದು ಮಾದರಿಯ ಟೋಕನ್ ಮಿತಿಗೆ ಹೇಗೆ ಸಂಬಂಧಿಸಿದೆ ಎಂದು ಚಿತ್ರಿಸುತ್ತದೆ. +ಕೆಳಗಿನ ಚಿತ್ರವು ಹೇಗೆ ಸಂಭಾಷಣೆ ಸಂದರ್ಭ ಪರಸ್ಪರ ಉಳಿತಾಯವಾಗುತ್ತೆ ಮತ್ತು ಮಾದರಿಯ ಟೋಕನ್ ಮಿತಿಯೊಂದಿಗೆ ಇದಕ್ಕೆ ಸಂಬಂಧ ಯಾಕೆ ಇದೆ ಎಂದು ಕാഴ്ചಕೊಡುತ್ತದೆ. Context Memory -*ಸಂದರ್ಶನದ ಸಧಾನವು ಹಲವು ತಿರುವುಗಳಲ್ಲಿ ಸಂಗ್ರಹವಾಗಿ ಟೋಕನ್ ಮಿತಿಗೆ ತಲುಪುವ ರೀತಿ* -**ಹಂತದ ಮೂಲಕ ತರ್ಕ** - ದೃಶ್ಯತಮಕವಾದ ತರ್ಕವಿರುವ ಸಮಸ್ಯೆಗಳಿಗೆ. ಪ್ರತಿ ಹಂತದಿಗಾಗಿ ಮಾದರಿ ಸ್ಪಷ್ಟ ತರ್ಕವನ್ನು ತೋರಿಸುತ್ತದೆ. ಗಣಿತ ಸಮಸ್ಯೆಗಳು, ತರ್ಕ ಪಜಲ್‌ಗಳು ಅಥವಾ ಚಿಂತನೆಯ ಪ್ರಕ್ರಿಯೆಯನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಬೇಕಾದಾಗ ಇದನ್ನು ಬಳಸಿ. +*ಬಹು ಹಂತ ಸಂಭಾಷಣೆಗಳಲ್ಲಿ ಸಂದರ್ಶನ ಸಂದರ್ಭವು ಟೋಕನ್ ಮಿತಿವರೆಗೆ ಹೇಗೆ ಜಮೆಯುತ್ತದೆ* + +**ಹಂತ-ಹಂತ ಲಾಜಿಕ್** - ದೃಶ್ಯಮಾನ ತಾರ್ಕಿಕತೆ ಬೇಕಾದ ಸಮಸ್ಯೆಗಳಿಗೆ. ಮಾದರಿ ಪ್ರತಿ ಹಂತಕ್ಕೆ ಸ್ಪಷ್ಟ ಯುಕ್ತಿ ತೋರುತ್ತದೆ. ಗಣಿತ ಸಮಸ್ಯೆಗಳು, ತಾರ್ಕಿಕ ಪuzzlesಗಳು ಅಥವಾ ಯೋಚನೆಯ ಪ್ರಕ್ರಿಯೆಯನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಬೇಕಾದಾಗ ಇದನ್ನು ಉಪಯೋಗಿಸಿ. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ಕೆಳಗಿನ ಚಿತ್ರವು ಮಾದರಿ ಸಮಸ್ಯೆಗಳನ್ನು ಸ್ಪಷ್ಟವಾಗಿ ಸಂಖ್ಯಾಂಕಿತ ತರ್ಕ ಹಂತಗಳಿಗೆ ಹೇಗೆ ವಿಭಾಗಿಸುತ್ತದೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ. - -ಹಂತದ ಮೂಲಕ ಮಾದರಿ +ಕೆಳಗಿನ ಚಿತ್ರವು ಮಾದರಿ ಸಮಸ್ಯೆಗಳನ್ನು ಸಂಖ್ಯಿತ ಲಾಜಿಕ್ ಹಂತಗಳಾಗಿ ಹೇಗೆ ವಿಭಜಿಸುತ್ತದೆ ಎಂಬುದನ್ನು ಪ್ರದರ್ಶಿಸುತ್ತದೆ. -*ಸಮಸ್ಯೆಗಳನ್ನು ಸ್ಪಷ್ಟ ತರ್ಕ ಹಂತಗಳಾಗಿ ವಿಭಾಗಿಸುವುದು* +Step-by-Step Pattern +*ಸಮಸ್ಯೆಗಳನ್ನು ಸ್ಪಷ್ಟ ಲಾಜಿಕಲ್ ಹೆಜ್ಜೆಗಳಿಗೆ ವಿಭಜಿಸುವುದು* -**ಮಿತಿಗೊಳ್ಳಲಾದ Output** - ನಿರ್ದಿಷ್ಟ ಫಾರ್ಮ್ಯಾಟ್ მოთხოვನೆಗಳಿರುವ ಪ್ರತಿಕ್ರಿಯೆಗಳಿಗಾಗಿ. ಮಾದರಿ ಫಾರ್ಮ್ಯಾಟ್ ಮತ್ತು ಉದ್ದ ನಿಯಮಗಳನ್ನು ಕಟ್ಟುನಿಟ್ಟಾಗಿ ಪಾಲಿಸುತ್ತದೆ. ಸಾರಾಂಶಗಳಿಗಾಗಿ ಅಥವಾ ನಿಖರ Output ರಚನೆ ಬೇಕಾದಾಗ ಇದನ್ನು ಬಳಸಿ. +**ಬಂಧಿತ ಔಟ್‌പುಟ್** - ವಿಶೇಷ ವಿನ್ಯಾಸದ ಅಗತ್ಯಗಳಿರುವ ಪ್ರತಿಕ್ರಿಯೆಗಳಿಗಾಗಿ. ಮಾದರಿ ವಿನ್ಯಾಸ ಮತ್ತು ಉದ್ದ ನಿಯಮಗಳನ್ನು ಕಟ್ಟುನಿಟ್ಟಾಗಿ ಅನುಸರಿಸುತ್ತದೆ. ಸಾರಾಂಶಗಳಿಗಾಗಿ ಅಥವಾ ನೀವು ನಿಖರ ಔಟ್‌ಪುಟ್ ರಚನೆಯ ಅವಶ್ಯಕತೆ ಇರುವಾಗ ಇದನ್ನು ಬಳಸಿ. ```java String prompt = """ @@ -420,189 +420,189 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ಕೆಳಗಿನ ಚಿತ್ರವು ನಿಯಮಗಳು ಮಾದರಿಯನ್ನು ಹೇಗೆ ನಿಮ್ಮ ಫಾರ್ಮ್ಯಾಟ್ ಮತ್ತು ಉದ್ದ ನಿಯಮಗಳನ್ನು ಕಟ್ಟುನಿಟ್ಟಾಗಿ ಪಾಲಿಸುವ Output ಸೃಷ್ಟಿಸಲು ಮಾರ್ಗದರ್ಶನ ಕೊಡುತ್ತವೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ. +ಕೆಳಗಿನ ಚಿತ್ರವು ನಿಯಮಗಳು ಹೇಗೆ ನಿಮ್ಮ ವಿನ್ಯಾಸ ಮತ್ತು ಉದ್ದ ಅಗತ್ಯಗಳನ್ನು ಕಟ್ಟುನಿಟ್ಟಾಗಿ ಅನುಸರಿಸುವ ಔಟ್‌ಪುಟ್ ಉತ್ಪಾದಿಸಲು ಮಾದರಿಯನ್ನು ಮಾರ್ಗದರ್ಶಿಸುತ್ತವೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ. -ನಿಯಂತ್ರಿತ Output ಮಾದರಿ +Constrained Output Pattern -*ನಿರ್ದಿಷ್ಟ ಫಾರ್ಮ್ಯಾಟ್, ಉದ್ದ ಮತ್ತು ರಚನೆ ನಿಯಮಗಳನ್ನು ಜೋರಾಗಿ ಅನುಸರಿಸುವುದು* +*ವಿಶೇಷ ವಿನ್ಯಾಸ, ಉದ್ದ ಮತ್ತು ರಚನಾ ಅವಶ್ಯಕತೆಗಳನ್ನು ಅನ್ವಯಿಸುವುದು* -## ಅಪ್ಲಿಕೇಶನ್ ಚಾಲನೆ +## ಅಪ್ಲಿಕೇಶನ್ ಅನ್ನು ಓಡಿಸಿ -**ಹೊಂದಾಣಿಕೆಯನ್ನು ಖಚಿತಪಡಿಸಿಕೊಳ್ಳಿ:** +**ವಿತರಣೆ ಪರಿಶೀಲಿಸಿ:** -ಬೇಸ್ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ `.env` ಫೈಲ್ ಪುನರಾವರ್ತಿತವಾಗಿ ಅಜೂರ್ ಪ್ರಮಾಣಪತ್ರಗಳೊಂದಿಗೆ (ಮೊಡ್ಯೂಲ್ 01 ರಲ್ಲಿ ನಿರ್ಮಿಸಲಾಗಿದೆ) ಇದ್ದು ಖಚಿತಪಡಿಸಿಕೊಳ್ಳಿ. ಇದನ್ನು ಮೋಡ್ಯೂಲ್ ಡೈರೆಕ್ಟರಿ (`02-prompt-engineering/`) ನಿಂದ ಚಾಲನೆಮಾಡಿ: +ಕೋಣೆಯಲ್ಲಿ ನಿರ್ಮಿತವಾದ Module 01 ನ ಸಮಯದಲ್ಲಿ ಅಪ್ಲಿಕೇಶನ್ ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ `.env` ಫೈಲ್ Azure ಪ್ರಮಾಣಪತ್ರಗಳೊಂದಿಗೆ ಇರುತ್ತದೆ ಎಂದು ಖಚಿತಪಡಿಸಿಕೊಳ್ಳಿ. ಇದನ್ನು ಈ module ಡೈರೆಕ್ಟರಿ (`02-prompt-engineering/`)ದಿಂದ ಓಡಿಸಿ: -**ಬ್ಯಾಶ್:** +**Bash:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ಅನ್ನು ತೋರಿಸಬೇಕು ``` -**ಪವರ್‌ಶೆಲ್:** +**PowerShell:** ```powershell Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ಅನ್ನು ತೋರಿಸಬೇಕು ``` -**ಅಪ್ಲಿಕೇಶನ್ ಪ್ರಾರಂಭಿಸಿ:** +**ಅಪ್ಲಿಕೇಶನ್ ಪ್ರಾರಂಭಿಸಿ:** -> **ಗಮನಿಸಿ:** ನೀವು ಈಗಾಗಲೇ `./start-all.sh` ಅನ್ನು ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಿಂದ (ಮೊಡ್ಯೂಲ್ 01 ರಲ್ಲಿ ವಿವರಿಸಿದಂತೆ) ಎಲ್ಲಾ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿದ್ದರೆ, ಈ ಮೋಡ್ಯೂಲ್ ಈಗಾಗಲೇ 8083 ಪೋರ್ಟ್‌ನಲ್ಲಿ ಚಾಲನೆಗೊಳ್ಳುತ್ತಿದೆ. ಕೆಳಗಿನ ಪ್ರಾರಂಭ ಆಜ್ಞೆಗಳನ್ನು ಬಿಟ್ಟು, ನೇರವಾಗಿ http://localhost:8083 ಗೆ ಹೋಗಬಹುದು. +> **ಸೂಚನೆ:** ನೀವು ಈಗಾಗಲೇ ಬ್ರಹತ್ ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಿಂದ `./start-all.sh` ಬಳಸಿಕೊಂಡು ಎಲ್ಲಾ ಅಪ್ಲಿಕೇಶನ್ಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿದ್ದರೆ (Module 01 ನಲ್ಲಿ ವರ್ಣಿಸಲಾಗಿದೆ), ಈ module ಈಗಾಗಲೇ 8083 ಪೋರ್ಟ್‌ನಲ್ಲಿ ಓಡುತ್ತಿದೆ. ನೀವು ಕೆಳಗಿನ ಪ್ರಾರಂಭ ಆಜ್ಞಾನವನ್ನು ತಪ್ಪಿಸಿ ಬಿಟ್ಟು ನೇರವಾಗಿ http://localhost:8083 ಗೆ ಹೋಗಬಹುದು. -**ಆಯ್ಕೆ 1: ಸ್ಫ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ಬಳಸುವುದು (VS ಕೋಡ್ ಬಳಕೆದಾರರಿಗೆ ಶಿಫಾರಸು)** +**ಆಯ್ಕೆ 1: Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ಬಳಸಿ (VS Code ಬಳಕೆದಾರರಿಗೆ ಶಿಫಾರಸು ಮಾಡಲಾಗಿದೆ)** -ಡಿವ್ ಕಂಟೈನರ್ ಸ್ಫ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ವಿಸ್ತರಣೆ ಒಳಗೊಂಡಿದೆ, ಇದು ಎಲ್ಲಾ ಸ್ಫ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ವಹಿಸುವ ದೃಶ್ಯಾತ್ಮಕ ಇಂಟರ್ಫೇಸ್ ಒದಗಿಸುತ್ತದೆ. ನೀವು ಇದನ್ನು VS ಕೋಡ್‌ನ ಎಕ್ಟಿವಿಟಿ ಬಾರ್‌ನ ಎಡಭಾಗದಲ್ಲಿ ಕಾಣಬಹುದು (ಸ್ಫ್ರಿಂಗ್ ಬೂಟ್ ಐಕಾನ್ ನೋಡಿ). +ಡೆವ್ ಕಂಟೇನರ್ ಅನ್ನು Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ವಿಸ್ತರಣೆಯೊಂದಿಗೆ ಒಳಗೊಂಡಿದೆ, ಇದು ಎಲ್ಲಾ Spring Boot ಅಪ್ಲಿಕೇಶನ್ಗಳನ್ನು ದೃಷ್ಟಿಸಿದ ಮೇಲೆ ನಿರ್ವಹಿಸುವ ದೃಶ್ಯಮಾಹಿತಿ ನೀಡುತ್ತದೆ. ನೀವು ಇದನ್ನು VS Code ಎಡಭಾಗದಲ್ಲಿರುವ ಚಟುವಟಿಕೆ ಬಾರ್ನಲ್ಲಿ (Spring Boot ಐಕಾನ್ ಹುಡುಕಿ) ಕಾಣಬಹುದು. -ಸ್ಫ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್‌ನಿಂದ ನೀವು: -- ಕಾರ್ಯಕ್ಷೇತ್ರದಲ್ಲಿರುವ ಎಲ್ಲಾ ಸ್ಫ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನೋಡಬಹುದು -- ಒಂದು ಕ್ಲಿಕ್‌ನಲ್ಲಿ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪ್ರಾರಂಭ/ನಿಲ್ಲಿಸಬಹುದು -- ಅಪ್ಲಿಕೇಶನ್ ಲಾಗ್‌ಗಳನ್ನು实时ವಾಗಿ ವೀಕ್ಷಿಸಬಹುದು -- ಅಪ್ಲಿಕೇಶನ್ ಸ್ಥಿತಿಯನ್ನು ಮನಃಪೂರ್ವಕವಾಗಿ ನೋಡಬಹುದು +Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್‌ನಿಂದ, ನೀವು: +- ವರ್ಕ್‌ಸ್ಪೇಸ್‌ನಲ್ಲಿರುವ ಎಲ್ಲಾ ಲಭ್ಯವಿರುವ Spring Boot ಅಪ್ಲಿಕೇಶನ್ಗಳನ್ನು ನೋಡಬಹುದು +- ಒಂದೇ ಕ್ಲಿಕ್ಕಿನಿಂದ ಅಪ್ಲಿಕೇಶನ್ಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿ/ನಿಲ್ಲಿಸಬಹುದು +- ಅಪ್ಲಿಕೇಶನ್ ದಾಖಲೆಗಳನ್ನು ನಿಜ ಕಾಲದಲ್ಲಿ ವೀಕ್ಷಿಸಬಹುದು +- ಅಪ್ಲಿಕೇಶನ್ ಸ್ಥಿತಿಯನ್ನು ನಿರೀಕ್ಷಿಸಬಹುದು -ಈ ಮೋಡ್ಯೂಲ್ ಅನ್ನು ಪ್ರಾರಂಭಿಸಲು "prompt-engineering" ಮೆಟ್ಟಿಲು ಪಕ್ಕದ ಪ್ಲೇ ಬಟನ್ ಕ್ಲಿಕ್ ಮಾಡಿರಿ, ಅಥವಾ ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್‌ಗಳನ್ನು ಒಂದೇ ಬಾರಿ ಪ್ರಾರಂಭಿಸಬಹುದು. +"prompt-engineering" ಪಕ್ಕದಲ್ಲಿ ಇರುವ ಪ್ಲೇ ಬಟನ್ ಮೇಲೆ ಕ್ಲಿಕ್ ಮಾಡಿ ಈ module ಅನ್ನು ಪ್ರಾರಂಭಿಸಬಹುದು, ಅಥವಾ ಎಲ್ಲ module ಗಳನ್ನು ಒಟ್ಟಿಗೆ ಪ್ರಾರಂಭಿಸಬಹುದು. Spring Boot Dashboard -*VS ಕೋಡ್‌ನಲ್ಲಿನ ಸ್ಫ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ — ಎಲ್ಲ ಮೋಡ್ಯೂಲ್‌ಗಳನ್ನು ಒಂದೇ ಸ್ಥಳದಲ್ಲಿರುವ ಪ್ರಾರಂಭ, ನಿಲ್ಲಿಸುವುದು ಮತ್ತು ವೀಕ್ಷಣೆ* +*VS Code ನಲ್ಲಿ Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ — ಎಲ್ಲ module ಗಳನ್ನು ಒಂದೇ ಸ್ಥಳದಿಂದ ಪ್ರಾರಂಭಿಸಿ, ನಿಲ್ಲಿಸಿ ಮತ್ತು ನೋಡಿಕೊಳ್ಳಿ* -**ಆಯ್ಕೆ 2: ಶೆಲ್ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳನ್ನು ಬಳಸಿ** +**ಆಯ್ಕೆ 2: ಶೆಲ್ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಬಳಸುವುದು** -ಎಲ್ಲಾ ವೆಬ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳು (ಮೊಡ್ಯೂಲ್‌ಗಳು 01-04) ಪ್ರಾರಂಭಿಸಿ: +ಎಲ್ಲಾ ವೆಬ್ ಅಪ್ಲಿಕೇಶನ್ಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿ (module ಗಳು 01-04): -**ಬ್ಯಾಶ್:** +**Bash:** ```bash -cd .. # ರೂಟ್ ಡಯರೆಕ್ಟರಿ ನಿಂದ +cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿ ನಿಂದ ./start-all.sh ``` -**ಪವರ್‌ಶೆಲ್:** +**PowerShell:** ```powershell -cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿ‌ನಿಂದ +cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಿಂದ .\start-all.ps1 ``` -ಅಥವಾ ಈ ಮೋಡ್ಯೂಲ್ ಮಾತ್ರ ಪ್ರಾರಂಭಿಸಿ: +ಅಥವಾ ಈ module ಮಾತ್ರ ಪ್ರಾರಂಭಿಸಿ: -**ಬ್ಯಾಶ್:** +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` -**ಪವರ್‌ಶೆಲ್:** +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` -ಎರಡೂ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ರುಟ್ `.env` ಫೈಲ್‌ನಿಂದ ಪರಿಸರ ಚರಗಳನ್ನು ಲೋಡ್ ಮಾಡುತ್ತವೆ ಮತ್ತು JARಗಳಿರದಿದ್ದರೆ ಅವನ್ನು ನಿರ್ಮಿಸುತ್ತವೆ. +ಇರ್ನಿವೇಶನ್ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ರೂಟ್ `.env` ಫೈಲ್‌ನಿಂದ ಪರಿಸರ ವ್ಯತ್ಯಾಸಗಳನ್ನು ಲೋಡ್ ಮಾಡುತ್ತವೆ ಮತ್ತು JAR ಫೈಲ್‌ಗಳು ಇಲ್ಲದಿದ್ದರೆ ನಿರ್ಮಿಸುತ್ತವೆ. -> **ಗಮನಿಸಿ:** ಪ್ರಾರಂಭಿಸುವ ಮೊದಲು ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್‌ಗಳನ್ನು ಕೈಯಿಂದ ನಿರ್ಮಿಸಲು ಬಯಸಿದರೆ: +> **ಸೂಚನೆ:** ನೀವು ಪ್ರಾರಂಭಿಸುವ ಮುನ್ನ ಎಲ್ಲಾ module ಗಳನ್ನು ಕೈಯಲ್ಲಿ ನಿರ್ಮಿಸಲು ಇಚ್ಛಿಸಿದರೆ: > -> **ಬ್ಯಾಶ್:** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **ಪವರ್‌ಶೆಲ್:** +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -ನಿಮ್ಮ ಬ್ರೌಸರ್‌ನಲ್ಲಿ http://localhost:8083 ತೆರೆಯಿರಿ. +ನಿಮ್ಮ ಬ್ರೌಸರಿನಲ್ಲಿ http://localhost:8083 ತೆರೆಯಿರಿ. **ನಿಲ್ಲಿಸಲು:** -**ಬ್ಯಾಶ್:** +**Bash:** ```bash ./stop.sh # ಈ ಘಟಕ ಮಾತ್ರ # ಅಥವಾ cd .. && ./stop-all.sh # ಎಲ್ಲಾ ಘಟಕಗಳು ``` -**ಪವರ್‌ಶೆಲ್:** +**PowerShell:** ```powershell -.\stop.ps1 # ಈ ಘಟಕ ಮಾತ್ರ +.\stop.ps1 # ಈ ಮాడ್ಯೂಲ್ ಮಾತ್ರ # ಅಥವಾ -cd ..; .\stop-all.ps1 # ಎಲ್ಲಾ ಘಟಕಗಳು +cd ..; .\stop-all.ps1 # ಎಲ್ಲಾ ಮಾಡ್ಯೂಲ್‌ಗಳು ``` -## ಅಪ್ಲಿಕೇಶನ್ ಸ್ಕ್ರೀನ್‌ಶಾಟ್‌ಗಳು +## ಅಪ್ಲಿಕೇಶನ್ ಸ್ಕ್ರೀನ್‌ಶಾಟ್‌ಗಳು -ಇದು ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್ ಮೋಡ್ಯೂಲ್‌ನ ಮುಖ್ಯ ಇಂಟರ್ಫೇಸ್ ಆಗಿದ್ದು, ನೀವು ಎಲ್ಲ ಎಂಟು ಮಾದರಿಗಳೊಂದಿಗೆ ಜೊತೆಗೆ ಪ್ರಯೋಗ ಮಾಡಬಹುದು. +ಇದು prompt engineering module ನ ಮುಖ್ಯ ಮುಖಪುಟವಾಗಿದೆ, ನೀವು ಇಲ್ಲಿ ಎಲ್ಲಾ ಎಂಟು ಪ್ಯಾಟರ್ನ್‌ಗಳ ಜೊತೆ ಜೊತೆಗೆ ಪ್ರಯತ್ನಿಸಬಹುದು. -ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ಮನೆ +Dashboard Home -*ಎಲ್ಲಾ 8 ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್ ಮಾದರಿಗಳ ಲಕ್ಷಣಗಳು ಮತ್ತು ಬಳಕೆದಾರಿಕೆಗಳೊಂದಿಗೆ ಮುಖ್ಯ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್‌ ಪ್ರದರ್ಶನ* +*ಮುಖ್ಯ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್‌ನಲ್ಲಿ 8 ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್ ಪ್ಯಾಟರ್ನ್‌ಗಳ ಲಕ್ಷಣಗಳು ಮತ್ತು ಉಪಯೋಗ ಪ್ರಕರಣಗಳು* -## ಮಾದರಿಗಳನ್ನು ಅನ್ವೇಷಿಸುವುದು +## ಪ್ಯಾಟರ್ನ್‌ಗಳನ್ನು ಅನ್ವೇಷಿಸುವುದು -ವೆಬ್ ಇಂಟರ್ಫೇಸ್ ನಿಮಗೆ ವಿವಿಧ ಪ್ರಾಂಪ್ಟ್ ತಂತ್ರಗಳನ್ನು ಪ್ರಯೋಗಿಸಲು ಅನುಮತಿಸುತ್ತದೆ. ಪ್ರತಿ ಮಾದರಿ ವಿಭಿನ್ನ ಸಮಸ್ಯೆಗಳನ್ನು ಪರಿಹರಿಸುತ್ತದೆ - ಯಾವಾಗ ಯಾವುದು ಹೆಚ್ಚು ಪರಿಣಾಮಕಾರಿಯಾಗಿದೆ ಎಂದು ನೋಡಲು ಪ್ರಯತ್ನಿಸಿ. +ವೆಬ್ ಇಂಟರ್ಫೇಸ್ ವಿವಿಧ ಪ್ರಾಂಪ್ಟ್ ತಂತ್ರಗಳನ್ನು ಪ್ರಯತ್ನಿಸುವ ಅವಕಾಶ ಕೊಡುತ್ತದೆ. ಪ್ರತಿ ಪ್ಯಾಟರ್ನ್ ವಿಭಿನ್ನ ಸಮಸ್ಯೆಗಳನ್ನು ಪರಿಹರಿಸುತ್ತದೆ - ಅವನ್ನು ಕಂಡುಬಂದಾಗ ಆ ಪ್ರಕಾರದ ವಿಧಾನ ಎಲ್ಲಿ ಉತ್ತಮ ಎಂದು ನೋಡಿರಿ. -> **ಗಮನಿಸಿ: ಸ್ಟ್ರೀಮಿಂಗ್ vs ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್** — ಪ್ರತಿ ಮಾದರಿ ಪುಟದಲ್ಲಿ ಎರಡು ಬಟನ್‌ಗಳು ಇವೆ: **🔴 ಸ್ಟ್ರೀಮ್ ಪ್ರತಿಕ್ರಿಯೆ (ಲೈವ್)** ಮತ್ತು **ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್** ಆಯ್ಕೆ. ಸ್ಟ್ರೀಮಿಂಗ್ ನೊಂದಿಗೆ Server-Sent Events (SSE) ಉಪಯೋಗಿಸಿ ಟೋಕನ್‌ಗಳನ್ನು ನಿಜ ಕಾಲದಲ್ಲಿ ತೋರಿಸಲಾಗುತ್ತದೆ ಹೀಗಾಗಿ ನೀವು ಪ್ರಗತಿಯನ್ನು ತಕ್ಷಣ ನೋಡಬಹುದು. ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್ ಆಯ್ಕೆ ಸಂಪೂರ್ಣ ಉತ್ತರದ ನಂತರ ಮಾತ್ರ ತೋರಿಸುತ್ತದೆ. ತೀವ್ರ ತರ್ಕವುಳ್ಳ ಪ್ರಾಂಪ್ಟ್‌ಗಳ (ಉದಾಹರಣೆಗೆ, ಹೈ ಇಗನೆಸ್, ಸ್ವಯಂ-ಪರಿಶೀಲನೆಯ ಕೋಡ್) ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್ ಕರೆ ಬಹಳ ಸಮಯ ತೆಗೆದುಕೊಳ್ಳಬಹುದು — ಕೆಲವೊಮ್ಮೆ ನಿಮಿಷಗಳವರೆಗೂ — ದೃಶ್ಯತಮಕ ಪ್ರತಿಕ್ರಿಯೆಯಿಲ್ಲದೆ. **ಕಠಿಣ ಪ್ರಾಂಪ್ಟ್‌ಗಳೊಂದಿಗೆ ಪ್ರಯೋಗ ಮಾಡುವಾಗ ಸ್ಟ್ರೀಮಿಂಗ್ ಬಳಸಿ** ಹೀಗಾಗಿ ಮಾದರಿ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತಿರುವುದನ್ನು ನೋಡಬಹುದು ಮತ್ತು ವಿನಂತಿ ಸಮಯ ಮೀರಿದಂತೆ ಭಾವನೆ ತಪ್ಪಿಸುತ್ತೀರಿ. +> **ಸೂಚನೆ: ಸ್ಟ್ರೀಮಿಂಗ್ ಎದುರು ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್** — ಪ್ರತಿಯೊಂದು ಪ್ಯಾಟರ್ನ್ ಪುಟದಲ್ಲಿ ಎರಡು ಬಟನ್‌ಗಳು ಇರುತ್ತದೆ: **🔴 ಸ್ರೋತ ಪ್ರತಿಕ್ರಿಯೆ (ಲೈವ್)** ಮತ್ತು ಒಂದು **ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್** ಆಯ್ಕೆ. ಸ್ಟ್ರೀಮಿಂಗ್ ಮಾದರಿ ನಿಜ ಕಾಲದಲ್ಲಿ ಟೋಕನ್‌ಗಳನ್ನು ತೋರಿಸಲು Server-Sent Events (SSE) ಬಳಕೆಮಾಡುತ್ತದೆ, ಇದರಿಂದ ಪ್ರಗತಿ ತಕ್ಷಣವೇ ಕಾಣುತ್ತದೆ. ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್ ಆಯ್ಕೆ ಸಂಪೂರ್ಣ ಪ್ರತಿಕ್ರಿಯೆಗೆ ಕಾಯುತ್ತದೆ. ದೀರ್ಘ ಆಲೋಚನೆಗೆ ಹೆಚ್ಚು ಸಮಯ ಬೇಕಾಗುವ ಪ್ರಶ್ನೆಗಳಿಗೆ (ಉದಾಹರಣೆಗೆ High Eagerness, Self-Reflecting Code) ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್ ಕರೆಗೆ ಬಹಳ ಸಮಯ (ಕೆಲಸಮಾನಗಳು) ಬೇಕಾಗಬಹುದು ಮತ್ತು ಯಾವುದೇ ದೃಷ್ಟಿಗೋಚರ ನಿರೀಕ್ಷೆ ಇಲ್ಲ. **ಜಟಿಲ ಪ್ರಾಂಪ್ಟ್ ಪ್ರಯೋಗಿಸುವಾಗ ಸ್ಟ್ರೀಮಿಂಗ್ ಬಳಸಿ** - ಇದು ಮಾದರಿ ಕಾರ್ಯಕ್ಷಮತೆಯನ್ನು ತೋರಿಸುತ್ತದೆ ಮತ್ತು ಸಮಯ ಮೀರಿತಾಯಿತ ಎನ್ನುವ ಭಾವವನ್ನು ತಪ್ಪಿಸುತ್ತದೆ. > -> **ಗಮನಿಸಿ: ಬ್ರೌಸರಿನ ಅಗತ್ಯತೆ** — ಸ್ಟ್ರೀಮಿಂಗ್ ವೈಶಿಷ್ಟ್ಯ Fetch Streams API (`response.body.getReader()`) ಬಳಸುತ್ತದೆ, ಇದು ಸಂಪೂರ್ಣ ಬ್ರೌಸರ್‌ಗಳಿಗೆ (ಕ್ರೋಮ್, ಎಡ್ಜ್, ಫೈರ್ಫಾಕ್ಸ್, ಸಫಾರಿ) ಬೇಕಾಗಿದೆ. VS ಕೋಡ್‌ನಲ್ಲಿನ ಸಂಯೋಜಿತ ಸಿಂಪಲ್ ಬ್ರೌಸರ್ ಸ್ಟ್ರೀಮಿಂಗ್ ಕಾರ್ಯಾಚರಣೆಯನ್ನು ಬೆಂಬಲಿಸುವುದಿಲ್ಲ. ಸಿಂಪಲ್ ಬ್ರೌಸರ್ ಬಳಸಿದರೆ, ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್ ಬಟನ್‌ಗಳು ಸಾಮಾನ್ಯವಾಗಿ ಕಾರ್ಯ ನಿರ್ವಹಿಸುತ್ತವೆ — ಕೇವಲ ಸ್ಟ್ರೀಮಿಂಗ್ ಬಟನ್‌ಗಳು ಪ್ರಭಾವಿತ ಆಗುತ್ತವೆ. ಸಂಪೂರ್ಣ ಅನುಭವಕ್ಕಾಗಿ `http://localhost:8083` ಅನ್ನು ಹೊರಗಿನ ಬ್ರೌಸರ್‌ನಲ್ಲಿ ತೆರೆಯಿರಿ. +> **ಸೂಚನೆ: ಬ್ರೌಸರಿನ ಅಗತ್ಯತೆ** — ಸ್ಟ್ರೀಮಿಂಗ್ ವೈಶಿಷ್ಟ್ಯ Fetch Streams API (`response.body.getReader()`) ಬಳಸುತ್ತದೆ, ಇದು ಸಂಪೂರ್ಣ ಬ್ರೌಸರ್‌ಗಳು (Chrome, Edge, Firefox, Safari) ಅವಶ್ಯಕ. VS Code ನ ಒಳಗೊಂಡ ಸರಳ ಬ್ರೌಸರ್ (Simple Browser) ಇದನ್ನು ಬೆಂಬಲಿಸುವುದಿಲ್ಲ, ಏಕೆಂದರೆ ಅದರ ವೆಬ್‌ವ್ಯೂ ReadableStream API ಅನ್ನು ಭೊಡಲಾಗುವುದಿಲ್ಲ. ಸರಳ ಬ್ರೌಸರ್ ಬಳಕೆಯಾದರೆ ನಾನ್-ಸ್ಟ್ರೀಮಿಂಗ್ ಬಟನ್‌ಗಳು ಸಾಮಾನ್ಯವಾಗಿ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ; ಸ್ಟ್ರೀಮಿಂಗ್ ಬಟನ್‌ಗಳಿಗೆ ಮಾತ್ರ ಎಫೆಕ್ಟ್ ಆಗುತ್ತದೆ. ಸಂಪೂರ್ಣ ಅನುಭವಕ್ಕಾಗಿ http://localhost:8083 ಅನ್ನು ಹೊರಗಿನ ಬ್ರೌಸರ್‌ನಲ್ಲಿ ತೆರೆಯಿರಿ. -### ತಗ್ಗು vs ಹೆಚ್ಚು ಉತ್ಸಾಹ +### ಕಡಿಮೆ ವಿರುದ್ಧ ಹೆಚ್ಚು ಆಸಕ್ತಿ -ಸಾಧಾರಣ ಪ್ರಶ್ನೆ "200 ರ 15% ಏನು?" ಅನ್ನು ತಗ್ಗು ಉತ್ಸಾಹದಿಂದ ಕೇಳಿ. ನಿಮಗೆ ತಕ್ಷಣದ, ನೇರ ಉತ್ತರ ಸಿಗುತ್ತದೆ. ಈಗ "ಮೇಲು ಸಂಚಾರ APIಗಾಗಿ ಕ್ಯಾಶಿಂಗ್ ತಂತ್ರವನ್ನು ರೂಪಿಸಿ" ಎಂಬ ಸಂಕೀರ್ಣ ಪ್ರಶ್ನೆಯನ್ನು ಹೆಚ್ಚು ಉತ್ಸಾಹದಿಂದ ಕೇಳಿ. **🔴 ಸ್ಟ್ರೀಮ್ ಪ್ರತಿಕ್ರಿಯೆ (ಲೈವ್)** ಕ್ಲಿಕ್ ಮಾಡಿ ಮತ್ತು ಮಾದರಿಯ ವಿಸ್ತೃತ ತರ್ಕವನ್ನು ಫಲಕದಿಂದ ಟೋಕನ್‌ಗೆ ಮುಂಚೆಯಾಗಿ ನೋಡಿ. ಅದೇ ಮಾದರಿ, ಅದೇ ಪ್ರಶ್ನೆ ರಚನೆ - ಆದರೆ ಪ್ರಾಂಪ್ಟ್ ಎಷ್ಟು ಚಿಂತೆಯೊಂದನ್ನು ಮಾಡಬೇಕೆಂದು ಹೇಳುತ್ತದೆ. +"200 ರ 15% ಎಷ್ಟು?" ಎಂದು ಕಡಿಮೆ ಆಸಕ್ತಿಯಿಂದ ಸರಳ ಪ್ರಶ್ನೆ ಕೇಳಿ. ನಿಮಗೆ ತಕ್ಷಣ, ನೇರ ಉತ್ತರ ದೊರೆಯುತ್ತದೆ. ಈಗ "ಹೆಚ್ಚು ಟ್ರಾಫಿಕ್ ಇರುವ API ಗೆ ಕ್ಯಾಶಿಂಗ್ ತಂತ್ರವನ್ನು ವಿನ್ಯಾಸಮಾಡಿ" ಎಂದು ಹೆಚ್ಚು ಆಸಕ್ತಿಯಿಂದ ಕೇಳಿ. **🔴 ಸ್ರೋತ ಪ್ರತಿಕ್ರಿಯೆ (ಲೈವ್)** ಮೇಲೆ ಕ್ಲಿಕ್ ಮಾಡಿ, ಮಾದರಿ ಟೋಕನ್ ಪ್ರತಿ ಟೋಕನ್ ವಿಶ್ಲೇಷಣೆ ನೀಡುವುದನ್ನು ನೋಡಿ. ಸಮಾನ ಮಾದರಿ, ಸಮಾನ ಪ್ರಶ್ನಾ ರಚನೆ - ಆದರೆ ಪ್ರಾಂಪ್ಟ್ ಆಲೋಚನೆಯ ಪ್ರಮಾಣವನ್ನು ಸೂಚಿಸುತ್ತದೆ. -### ಕಾರ್ಯ ನಿರ್ವಹಣೆ (ಟೂಲ್ ಪ್ರೀambles) +### ಕಾರ್ಯಾಚರಣೆ (ಟೂಲ್ ಪ್ರೀऐಂಬಲ್‌ಗಳು) -ಬಹು ಹಂತದ ಕಾರ್ಯಪ್ರವಾಹಗಳು ಪ್ರಾರಂಭಿಕ ಯೋಜನೆ ಮತ್ತು ಪ್ರಗತಿ ವಿವರಣೆಯಿಂದ ಲಾಭ ಪಡೆಯುತ್ತವೆ. ಮಾದರಿ ಏನು ಮಾಡಲು ಹೋಗುತ್ತಿದೆ ಎಂದು ವಿವರಿಸುತ್ತದೆ, ಪ್ರತಿ ಹಂತವನ್ನು ವರ್ಣಿಸುತ್ತದೆ, ನಂತರ ಫಲಿತಾಂಶಗಳನ್ನು ಸಾರಾಂಶ ಮಾಡುತ್ತದೆ. +ಬಹು-ಹೆಜ್ಜೆ ಕಾರ್ಯವಿಧಾನಗಳಿಂದ ಮುಂಚಿತ ಯೋಜನೆ ಮತ್ತು ಪ್ರಗತಿ ವಿವರಣೆ ಲಾಭವಾಗುತ್ತದೆ. ಮಾದರಿ ತಯಾರಿಕೆಯಿಂದ ಪ್ರತಿ ಹಂತವನ್ನು ವಿವರಿಸಿ, ನಂತರ ಫಲಿತಾಂಶಗಳನ್ನು ಸಂಗ್ರಹಿಸುತ್ತದೆ. -### ಸ್ವಯಂ-ಪರಿಶೀಲಿಸುವ ಕೋಡ್ +### ಸ್ವ-ಪರಿಶೀಲನೆಯ ಕೋಡ್ -"ಇಮೇಲ್ ಮಾನ್ಯತೆ ಸೇವೆಯನ್ನು ರಚಿಸಿ" ಎಂದು ಪ್ರಯತ್ನಿಸಿ. ಕೇವಲ ಕೋಡ್ ರಚಿಸುವುದನ್ನು ನಿಲ್ಲಿಸಿ, ಮಾದರಿ ರಚಿಸುತ್ತದೆ, ಗುಣಮಟ್ಟ ಮಾಪಕಗಳೊಂದಿಗೆ ಮೌಲ್ಯಮಾಪನ ಮಾಡುತ್ತದೆ, ದುರ್ಬಲತೆಗಳನ್ನು ಗುರುತಿಸುತ್ತದೆ ಮತ್ತು ಸುಧಾರಿಸುತ್ತದೆ. ಕೋಡ್ ಉತ್ಪಾದನಾ ಮಾನದಂಡಗಳನ್ನು ತುಂಬುವವರೆಗೆ ಪುನರಾವೃತಿಯನ್ನು ನೋಡುತ್ತೀರಿ. +"ಇಮೇಲ್ ಪ್ರಮಾಣೀಕರಣ ಸೇವೆ ಸೃಷ್ಟಿಸಿ" ಎಂದು ಪ್ರಯತ್ನಿಸಿ. ಕೇವಲ ಕೋಡ್ ರಚಿಸುವುದನ್ನು ನಿಲ್ಲಿಸಿ, ಮಾದರಿ ಉತ್ಪಾದಿಸುವ, ಗುಣಮಟ್ಟ ಮಾನದಂಡಗಳಿಗೆ ವಿರುದ್ಧವಾಗಿ ಮಾದರಿಯನ್ನು ಮೌಲ್ಯಮಾಪನ ಮಾಡಿ, ದೋಷಗಳನ್ನು ಗುರುತಿಸಿ ಮತ್ತು ಸುಧಾರಿಸುತ್ತದೆ. ನೀವು ಕೋಡ್ ಉತ್ಪಾದನೆ ಪ್ರಮಾಣಿತಗಳಿಗೆ ತಲುಪುವವರೆಗೆ ಪುನರಾವರ್ತನೆ ಕಾಣುತ್ತೀರಿ. -### ಸಂರಚಿತ ವಿಶ್ಲೇಷಣೆ +### ಸೂತ್ರಬದ್ಧ ವಿಶ್ಲೇಷಣೆ -ಕೋಡ್ ವಿಮರ್ಶೆಗಳಿಗೆ ನಿರಂತರ ಮೌಲ್ಯಮಾಪನ ಚಟುವಟಿಕೆಗಳು ಬೇಕು. ಮಾದರಿ ಕೋಡ್ ಅನ್ನು ನಿಶ್ಚಿತ ವರ್ಗಗಳ (ಸರಿಯಾದತೆ, ಅಭ್ಯಾಸಗಳು, ಕಾರ್ಯಕ್ಷಮತೆ, ಭದ್ರತೆ) ಮೂಲಕ ಗಂಭೀರತಾ ಹಂತಗಳೊಂದಿಗೆ ವಿಶ್ಲೇಷಿಸುತ್ತದೆ. +ಕೋಡ್ ವಿಮರ್ಶೆಗಳು ಸತತ ಮೌಲ್ಯಮಾಪನ ಚೌಕಟವನ್ನು ಬೇಕಾಗಿಸುತ್ತದೆ. ಮಾದರಿ ಸ್ಥಿರ ವರ್ಗಗಳನ್ನು (ತಪ್ಪು, ಅಭ್ಯಾಸಗಳು, ಕಾರ್ಯಕ್ಷಮತೆ, ಭದ್ರತೆ) ತೀವ್ರತೆ ಮಟ್ಟಗಳೊಂದಿಗೆ ವಿಶ್ಲೇಷಿಸುತ್ತದೆ. -### ಬಹು-ತಿರುವು ಸಂಭಾಷಣೆ +### ಬಹು-ಟರ್ನ್ ಚಾಟ್ -"ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಎಂಬುದು ಏನು?" ಎಂದು ಕೇಳಿ ನಂತರ ತಕ್ಷಣ "ಒಂದು ಉದಾಹರಣೆಯನ್ನು ತೋರಿಸಿ" ಎಂದು ಕೇಳಿ. ಮಾದರಿ ನಿಮ್ಮ ಮೊದಲ ಪ್ರಶ್ನೆಯನ್ನು ನೆನಪಿಡುತ್ತದೆ ಮತ್ತು ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಉದಾಹರಣೆಯನ್ನು ನೀಡುತ್ತದೆ. ಸ್ಮರಣೆ ಇಲ್ಲದೆ, ಎರಡನೇ ಪ್ರಶ್ನೆ ಅಸ್ಪಷ್ಟವಾಗುತ್ತದೆ. +"Spring Boot ಎಂದರೆ ಏನು?" ಎಂದು ಕೇಳಿ ನಂತರ ತಕ್ಷಣ "ಒಂದು ಉದಾಹರಣೆಯನ್ನು ತೋರಿಸಿ" ಎಂದು ಕೇಳಿ. ಮಾದರಿ ನಿಮ್ಮ ಮೊದಲ ಪ್ರಶ್ನೆಯನ್ನು ನೆನಪಿಡುತ್ತದೆ ಮತ್ತು ಸ್ಪಷ್ಟವಾಗಿ Spring Boot ಉದಾಹರಣೆಯನ್ನು ನೀಡುತ್ತದೆ. ಸ್ಮರಣೆ ಇಲ್ಲದೆ ಎರಡನೇ ಪ್ರಶ್ನೆ ತುಂಬಾ ಸಿಬ್ಬಂದಿಯಾಗಿರುತ್ತದೆ. -### ಹಂತದ ಮೂಲಕ ತರ್ಕ +### ಹೆಜ್ಜೆ ಹಂತ ಆಲೋಚನೆ -ಗಣಿತ ಸಮಸ್ಯೆಯನ್ನು ಆರಿಸಿ ಮತ್ತು ಹಂತದ ಮೂಲಕ ತರ್ಕ ಮತ್ತು ತಗ್ಗು ಉತ್ಸಾಹದೊಂದಿಗೆ ಪ್ರಯತ್ನಿಸಿ. ತಗ್ಗು ಉತ್ಸಾಹವು ನಿಮ್ಮಿಗೆ ಕೇವಲ ಉತ್ತರವನ್ನು ದ್ರುತವಾಗಿ ಮತ್ತು ಅಸ್ಪಷ್ಟವಾಗಿ ನೀಡುತ್ತದೆ. ಹಂತ ಹಂತ ತರ್ಕವು ಪ್ರತಿ ಗಣನೆ ಮತ್ತು ತೀರ್ಮಾನವನ್ನು ತೋರಿಸುತ್ತದೆ. +ಗಣಿತದ ಸಮಸ್ಯೆಯನ್ನು ಆರಿಸಿ ಮತ್ತು Step-by-Step Reasoning ಮತ್ತು Low Eagerness ಎರಡರಲ್ಲಿಯೂ ಪ್ರಯತ್ನಿಸಿ. ಕಡಿಮೆ ಆಸಕ್ತಿ ತ್ವರಿತವಾಗಿ ಉತ್ತರ ಕೊಡುತ್ತದೆ ಆದರೆ ಅಪ್ರತ्यक्षವಾಗಿದೆ. ಹೆದಗೆ-ಹೆಜ್ಜೆ ಪ್ರತಿಯೊಂದು ಗಣನೆ ಮತ್ತು ನಿರ್ಣಯವನ್ನು ತೋರಿಸುತ್ತದೆ. -### ನಿಯಂತ್ರಿತ Output +### ಬಂಧಿತ ಔಟ್‌ಪುಟ್ -ನೀವು ನಿರ್ದಿಷ್ಟ ಫಾರ್ಮ್ಯಾಟ್ ಅಥವಾ ಪದ ಎಣಿಕೆಗಳ ಅವಶ್ಯಕತೆಯಿದ್ದಾಗ, ಈ ಮಾದರಿ ಕಟ್ಟುನಿಟ್ಟಾಗಿ ಪಾಲನೆಯನ್ನು ಜೋರಾಗಿಸುತ್ತದೆ. ನಿಖರವಾಗಿ 100 ಪದಗಳ ಸಾರಾಂಶವು ಬുള്ളೆಟ್ ಪಾಯಿಂಟ್ ಫಾರ್ಮ್ಯಾಟ್‌ನಲ್ಲಿ ರಚಿಸಿ ನೋಡಿರಿ. +ನೀವು ವಿಶೇಷ ವಿನ್ಯಾಸಗಳು ಅಥವಾ ಪದಗಳ ಸಂಖ್ಯೆಯನ್ನು ಬೇಕಾಗಿದ್ದಾಗ, ಈ ಪ್ಯಾಟರ್ನ್ ಕಟ್ಟುನಿಟ್ಟಾಗಿ ಅನುಸರಿಸುತ್ತದೆ. ನಿಖರವಾಗಿ 100 ಪದಗಳಲ್ಲಿ ಬುಲೆಟ್ ಪಾಯಿಂಟ್ ರೂಪದಲ್ಲಿ ಸಾರಾಂಶ ರಚಿಸಿ. ## ನೀವು ನಿಜವಾಗಿಯೂ ಕಲಿಯುತ್ತಿರುವುದು -**ತರ್ಕ ಪ್ರಯತ್ನ ಎಲ್ಲವನ್ನೂ ಬದಲಾಯಿಸುತ್ತದೆ** +**ಆಲೋಚನಾ ಪ್ರಯತ್ನ ಎಲ್ಲವನ್ನೂ ಬದಲಿಸುತ್ತದೆ** -GPT-5.2 ನಿಮ್ಮ ಪ್ರಾಂಪ್ಟ್‌ಗಳ ಮೂಲಕ ಗಣನೆ ಪ್ರಯತ್ನವನ್ನು ನಿಯಂತ್ರಣ ಮಾಡುತ್ತದೆ. ಕಡಿಮೆ ಪ್ರಯತ್ನವೇ dünscheಳಾದ ಉತ್ತರಗಳನ್ನು ವೇಗವಾಗಿ ನೀಡುತ್ತದೆ. ಹೆಚ್ಚು ಪ್ರಯತ್ನವು ಮಾದರಿಯನ್ನು ಆಳವಾಗಿ ಚಿಂತಿಸುವಂತೆ ಮಾಡುತ್ತದೆ. ನೀವು ಕಾರ್ಯ ಸಂಕೀರ್ಣತೆಗೆ ಅನುಗುಣವಾಗಿ ಪ್ರಯತ್ನವನ್ನು ಹೊಂದಿಸುವ ಕಲಿತಿದ್ದೀರಿ - ಸರಳ ಪ್ರಶ್ನೆಗಳಿಗೆ ಸಮಯ ವ್ಯರ್ಥ ಮಾಡಬೇಡಿ, ಆದರೆ ಸಂಕೀರ್ಣ ನಿರ್ಣಯಗಳನ್ನು ತ್ವರಿತಗೊಳಿಸಬೇಡಿ. +GPT-5.2 ನಿಮ್ಮ ಪ್ರಾಂಪ್ಟ್ ಮೂಲಕ ಗಣನೆ ಪ್ರಯತ್ನವನ್ನು ನಿಯಂತ್ರಣಕ್ಕೆ ನೆಡುತ್ತದೆ. ಕಡಿಮೆ ಪ್ರಯತ್ನವು ತ್ವರಿತ ಪ್ರತಿಕ್ರಿಯೆಗಳ ಜೊತೆ ಕಡಿಮೆ ಅನ್ವೇಷಣೆಯನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುತ್ತದೆ. ಹೆಚ್ಚು ಪ್ರಯತ್ನವು ಮಾದರಿಯನ್ನು ಆಳವಾಗಿ ಆಲೋಚಿಸಲು ಸಮಯ ಕೊಡುತ್ತದೆ. ನೀವು ಕಾರ್ಯದ ಜಟಿಲತೆಯನ್ನು ಪರಿಶೀಲಿಸಿ ಪ್ರಯತ್ನವನ್ನು ಹೊಂದಿಕೊಳ್ಳಲು ಕಲಿಯುತ್ತಿದ್ದೀರಿ - ಸರಳ ಪ್ರಶ್ನೆಗಳಲ್ಲಿ ಸಮಯ ವ್ಯರ್ಥಮಾಡಿಕೊಳ್ಳಬೇಡಿ, ಜಟಿಲ ನಿರ್ಣಯಗಳಿಗೆ ಬೇಗಬೇಡಿ. -**ರಚನೆ ವರ್ತನೆಗೆ ಮಾರ್ಗದರ್ಶನ ನೀಡುತ್ತದೆ** +**ರಚನೆ ನಡೆಗಾರಿಕೆಯನ್ನು ಮಾರ್ಗದರ್ಶಿಸುತ್ತದೆ** -ಪ್ರಾಂಪ್ಟ್‌ಗಳಲ್ಲಿ XML ಟ್ಯಾಗ್‌ಗಳನ್ನು ಗಮನಿಸಿ? ಅವು ಅಲಂಕಾರಿಕವಲ್ಲ. ಮಾದರಿಗಳು ಸ್ವತಃ ನಿರ್ದಿಷ್ಟ ಸೂಚನೆಗಳನ್ನು ಸ್ವತಃ ಅನ್ವಯಿಸುವಲ್ಲಿ ಹೆಚ್ಚು ನಂಬಿಕೆಯಾಗಿರುತ್ತಾರೆ. ಬಹು ಹಂತ ಪ್ರಕ್ರಿಯೆಗಳು ಅಥವಾ ಸಂಕೀರ್ಣ ತರ್ಕ ಬೇಕಾದಾಗ, ರಚನೆ ಮಾದರಿಯನ್ನು ಯಾವ ಹಂತದಲ್ಲಿದೆ ಮತ್ತು ಮುಂದೆ ಏನು ಬರುವುದೆಂದು ತಪ್ಪದೇ ಅನುಸರಿಸಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ. ಕೆಳಗಿನ ಆಕೃತಿ ಚೆನ್ನಾಗಿ ರಚಿಸಲಾದ ಪ್ರಾಂಪ್ಟಿನ ವಿಭಾಗಗಳನ್ನು ತೋರಿಸುತ್ತದೆ, ``, ``, ``, ``, `` ಮುಂತಾದ ಟ್ಯಾಗ್‌ಗಳು ನಿಮ್ಮ ಸೂಚನೆಗಳನ್ನು ಸ್ಪಷ್ಟ ವಿಭಾಗಗಳಲ್ಲಿ ಜೋಡಿಸುತ್ತವೆ. +ಪ್ರಾಂಪ್ಟ್ ಗಳಲ್ಲಿನ XML ಟ್ಯಾಗ್‌ಗಳನ್ನು ಗಮನಿಸಿ? ಅವು ಅಲಂಕಾರವಲ್ಲ. ಮಾದರಿಗಳು ರಚನಾತ್ಮಕ ಸೂಚನೆಗಳನ್ನು ಮುಕ್ತಲೇಖನಕ್ಕಿಂತ ಹೆಚ್ಚಿನ ನಂಬಿಕೆಯೊಂದಿಗೆ ಅನುಸರಿಸುತ್ತವೆ. ಬಹು-ಹೆಜ್ಜೆ ಪ್ರಕ್ರಿಯೆಗಳು ಅಥವಾ ಜಟಿಲ ಲಾಜಿಕ್ ಬೇಕಾದಾಗ, ರಚನೆ ಮಾದರಿಗೆ ತನ್ನ ಸ್ಥಿತಿಯನ್ನು ಮತ್ತು ಮುಂದೇನು ಮಾಡಬೇಕೆಂದು ತಿಳಿಯಲು ಸಹಾಯಮಾಡುತ್ತದೆ. ಕೆಳಗಿನ ಚಿತ್ರವು ಒಳ್ಳೆಯ ರಚನೆಯ ಪ್ರಾಂಪ್ಟ್ ಅನ್ನು ವಿಶ್ಲೇಷಿಸಿ ``, ``, ``, ``, ಮತ್ತು `` ಟ್ಯಾಗ್‌ಗಳ ಮೂಲಕ ಸ್ಪಷ್ಟ ವಿಭಾಗಗಳಲ್ಲಿ ನಿಮ್ಮ ಸೂಚನೆಗಳನ್ನು ಏರ್ಪಡಿಸುವುದನ್ನು ತೋರಿಸುತ್ತದೆ. -ಪ್ರಾಂಪ್ಟ್ ರಚನೆ +Prompt Structure -*ಸ್ಪಷ್ಟ ವಿಭಾಗಗಳು ಮತ್ತು XML-ಶೈಲಿಯ ಸಂಘಟನೆ ಹೊಂದಿದ ನಲಿವು ಬದ್ಧವಾದ ಪ್ರಾಂಪ್ಟ್‌ನ ಅಂಶಗಳು* +*ಸದೃಢ ರಚನೆಯನ್ನು ಹೊಂದಿದ್ದು ಸ್ಪಷ್ಟ ವಿಭಾಗಗಳು ಮತ್ತು XML ಶೈಲಿಯ ವ್ಯವಸ್ಥೆಯೊಂದು* -**ಗುಣಮಟ್ಟ ಸ್ವಯಂ-ಮೌಲ್ಯಮಾಪನದ ಮೂಲಕ** +**ಸ್ವ ಮೌಲ್ಯಮಾಪನದ ಮೂಲಕ ಗುಣಮಟ್ಟ** -ಸ್ವಯಂ-ಪರಿಶೀಲಿಸುವ ಮಾದರಿಗಳು ಗುಣಮಟ್ಟ ಮಾಪಕಗಳನ್ನು ಸ್ಪಷ್ಟಪಡಿಸುವ ಮೂಲಕ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ. "ಮಾದರಿ ಸರಿಯಾಗಿಧರಿಸು" ಎಂದು ನಿರೀಕ್ಷಿಸುವ ಬದಲಿಗೆ, ನೀವು ನಿರ್ದಿಷ್ಟವಾಗಿ "ಸರಿಹೊಂದುತ್ತದೆ" ಎಂದರೆ ಏನೆಂದು ಹೇಳುತ್ತೀರಿ: ಸರಿಯಾದ ತರ್ಕ, ದೋಷ ನಿರ್ವಹಣೆ, ಕಾರ್ಯಕ್ಷಮತೆ, ಭದ್ರತೆ. ನಂತರ ಮಾದರಿ ತನ್ನ ಸ್ವಂತ Output ಅನ್ನು ಮೌಲ್ಯಮಾಪನ ಮಾಡಿ ಸುಧಾರದೊಡನೆ ಪರಿಷ್ಕರಿಸಬಹುದು. ಇದು ಕೋಡ್ ರಚನೆಯನ್ನು ಲೋಕಾಠ್ಪ ತಲುಪದೇ, ಪ್ರಕ್ರಿಯೆಯೊಂದಾಗಿ ಪರಿವರ್ತಿಸುತ್ತದೆ. +ಸ್ವ-ಪರಿಶೀಲನೆ ಪ್ಯಾಟರ್ನ್ಗಳು ಗುಣಮಟ್ಟ ಮಾನದಂಡಗಳನ್ನು ಬಹಿರಂಗಗೊಳಿಸುವ ಕಾರ್ಯತಂತ್ರದಿಂದ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ. ಮಾದರಿ "ಸರಿಯಾಗಿ ಮಾಡುತ್ತದೆ" ಎಂಬ ನಿರೀಕ್ಷೆಗಳ ಬದಲು, ನೀವು "ಸರಿಯಾಗಿ" ಅರ್ಥ ಎಷ್ಟೋ ಬಗೆಯ ನಿಯಮಗಳು: ಸರಿಯಾದ ಲಾಜಿಕ್, ದೋಷ ನಿರ್ವಹಣೆ, ಕಾರ್ಯಕ್ಷಮತೆ, ಭದ್ರತೆ ಎಂದು ಸರಳವಾಗಿ ಹೇಳುತ್ತೀರಾ. ನಂತರ ಮಾದರಿ ತನ್ನದೇ ಔಟ್‌ಪುಟ್ ಅನ್ನು ಮೌಲ್ಯಮಾಪನ ಮಾಡಿ ಸುಧಾರಿಸಬಹುದು. ಇದರಿಂದ ಕೋಡ್ ರಚನೆ ಲಾಟರಿ ಕ್ಷೇತ್ರದಿಂದ ಕಂಪ್ಲೀಟ್ ಪ್ರಕ್ರಿಯೆಯಾಗಿ ಪರಿವರ್ತನೆಗೊಳ್ಳುತ್ತದೆ. -**ಸಂದರ್ಭ ಚುಕ್ಕಟವಾಗಿದೆ** +**ಸಂದರ್ಭವು ಸೀಮಿತವಾಗಿದೆ** -ಬಹು-ತಿರುವು ಸಂಭಾಷಣೆಗಳು ಪ್ರತಿ ವಿನಂತಿಯಲ್ಲಿ ಸಂದೇಶ ಇತಿಹಾಸವನ್ನು ಒಳಗೊಳ್ಳುವುದರಿಂದ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ. ಆದರೆ ಗಡಿ ಇದೆ - ಪ್ರತಿಯೊಂದು ಮಾದರಿಯ ಟೋಕನ್ ಪ್ರಮಾಣದ ಗರಿಷ್ಠ ಮಿತಿ ಇದೆ. ಸಂಭಾಷಣೆಗಳಾದಂತೆ, ಸಂಬಂಧಿಸಿದ ಸಂದರ್ಭವನ್ನು ಮಿತಿಭಾದಿಸುವ ತಂತ್ರಗಳನ್ನು ಅಗತ್ಯವಿದೆ. ಈ ಮೋಡ್ಯೂಲ್‌ನಲ್ಲಿ ನೀವು ಹೇಗೆ ಸ್ಮರಣೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ ಎಂಬುದನ್ನು ನೋಡುತ್ತೀರಿ; ನಂತರ ನೀವು ಯಾವಾಗ ಸಾರಾಂಶ ಮಾಡಬೇಕು, ಯಾವಾಗ ಮರೆತರೂ, ಮತ್ತು ಯಾವಾಗ ಪಡೆದುಕೊಳ್ಳಬೇಕು ಎಂಬುದನ್ನು ತಿಳಿಯುತ್ತೀರಿ. +ಬಹು-ಟರ್ನ್ ಸಂಭಾಷಣೆಗಳು ಪ್ರತಿ ವಿನಂತಿಯೊಂದಿಗೆ ಸಂದೇಶ ಇತಿಹಾಸವನ್ನು ಒಳಗೊಂಡಿರುವ ಮೂಲಕ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ. ಆದ್ರು ಮಿತಿಯಿದೆ - ಪ್ರತಿ ಮಾದರಿಗೂ ಗರಿಷ್ಠ ಟೋಕನ್ ಗಣನೆ ಇರುತ್ತದೆ. ಸಂಭಾಷಣೆಗಳು ಹೆಚ್ಚಾಗುವಂತೆ, ನೀವು ಸಂಬಂಧಿಸಿದ ಸಂದರ್ಭವನ್ನು ಇರಿಸಿಕೊಳ್ಳುವ ಮಾರ್ಗವನ್ನು ಕಂಡುಹಿಡಿಯಬೇಕಾಗುತ್ತದೆ ಆದರೆ ಮಿತಿಯನ್ನು ಮೀರಕೂಡದು. ಈ module ನಿಮಗೆ ಸ್ಮರಣೆ ಹೇಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ ಎಂದು ತೋರಿಸುತ್ತದೆ; ನಂತರ ನೀವು ಯಾವಾಗ ಸಾರಾಂಶ ಮಾಡುವುದು, ಯಾವಾಗ ಮರೆತುಹೋಗುವುದು, ಮತ್ತು ಯಾವಾಗ ಮತ್ತೆ ಪಡೆಯಬೇಕು ಎಂಬುದನ್ನು ಕಲಿಯೋದು. ## ಮುಂದಿನ ಹಂತಗಳು -**ಮುಂದಿನ ಮೋಡ್ಯೂಲ್:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**ಮುಂದಿನ module:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**ನಾವಿಗೇಷನ್:** [← ಹಿಂದಿನ: ಮೋಡ್ಯೂಲ್ 01 - ಪರಿಚಯ](../01-introduction/README.md) | [ಮುಖ್ಯ ಪುಟಕ್ಕೆ ಹಿಂತಿರುಗಿ](../README.md) | [ಮುಂದಿನ: ಮೋಡ್ಯೂಲ್ 03 - RAG →](../03-rag/README.md) +**ನೆವಿಗೆಶನ್:** [← ಹಿಂದಿನದು: Module 01 - ಪರಿಚಯ](../01-introduction/README.md) | [ಮೇನ್‌ಗೆ ಹಿಂತಿರುಗಿ](../README.md) | [ಮುಂದಿನದು: Module 03 - RAG →](../03-rag/README.md) --- -**ನಿರಾಕರಣಾ ಪ್ರಕಟಣೆ**: -ಈ ದಾಖಲೆ AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಉಪಯೋಗಿಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಗೆ ಪ್ರಯತ್ನಿಸಿದರೂ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ತಪ್ಪುಗಳು ಅಥವಾ ಅಪರಿಶುದ್ಧತೆಗಳಿರಬಹುದು. ಮೂಲ ಭಾಷೆಯಲ್ಲಿದ್ದ ದಾಖಲೆ ಅಧಿಕಾರೀಕ ಆಗಿದ್ದು, ಅದನ್ನು ಮಾನ್ಯ ಮೂಲವಾಗಿ ಪರಿಗಣಿಸಬೇಕು. ಅತಿ ಮಹತ್ವದ ಮಾಹಿತಿಗೆ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದ ಬಳಕೆಯಿಂದ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪುಅರ್ಥಗಳ ಅಥವಾ ದೋಷವಿವರಣೆಗಳಿಗಾಗಿ ನಾವು ಹೊಣೆಗಾರರುಾಗಿರುವುದಿಲ್ಲ. +**ಅಸ್ವೀಕಾರ**: +ಈ ದಸ್ತಾವೇಜು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಯನ್ನು ಸಾಧಿಸಲು ಪ್ರಯತ್ನಿಸುತ್ತಿದ್ದರೂ, ದಯವಿಟ್ಟು ಗಮನಿಸಿ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ಅಸಡ್ಡೆಗಳು ಇರಬಹುದು. ಮೂಲ ಭಾಷೆಯಲ್ಲಿರುವ ಮೂಲ ದಸ್ತಾವೇಜು ಪ್ರಾಮಾಣಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದವನ್ನು ಬಳಸುವ ಮೂಲಕ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪು ಅರ್ಥಗಳ ಅಥವಾ ತಪ್ಪು ವ್ಯಾಖ್ಯಾನಗಳ ಬಗ್ಗೆ ನಾವು ಹೊಣೆಗಾರರಲ್ಲ. \ No newline at end of file diff --git a/translations/kn/03-rag/README.md b/translations/kn/03-rag/README.md index d4b177361..b3cbb8664 100644 --- a/translations/kn/03-rag/README.md +++ b/translations/kn/03-rag/README.md @@ -1,144 +1,143 @@ -# Module 03: RAG (ಪುನರಾವರ್ತನೆ-ವೃದ್ಧಿಪಡಿಸಿದ ತಯಾರಿ) +# Module 03: RAG (ಪ್ರತಿಪ್ರಾಪ್ತಿ-ಸಹಾಯಿತ ಉತ್ಪಾದನೆ) -## ವಿಷಯ ಸಂಗ್ರಹ +## ವಿಷಯಗಳಪಟ್ಟಿ -- [ವಿಡಿಯೋ ವಾಕ್ಥ್ರೂ](../../../03-rag) -- [ನೀವು ಕಲಿಯೋದು ಏನು](../../../03-rag) -- [ಮೂಲಾಗ್ರಹಣಗಳು](../../../03-rag) -- [RAG ನ ಅರಿವು](../../../03-rag) - - [ಈ ಪಾಠವು ಯಾವ RAG ವಿಧಾನವನ್ನು ಬಳಕೆ ಮಾಡುತ್ತದೆ?](../../../03-rag) -- [ಎಲాగే ಇದು ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ](../../../03-rag) - - [ಡಾಕ್ಯುಮೆಂಟ್ ಪ್ರಕ್ರಿಯೆ](../../../03-rag) - - [ಎಂಬೆಡ್ಡಿಂಗ್ ರಚನೆ](../../../03-rag) - - [ಅರ್ಥಪೂರ್ಣ ಶೋಧನೆ](../../../03-rag) - - [ಉತ್ತರ ತಯಾರಿ](../../../03-rag) -- [ಅಪ್ಲಿಕೇಶನ್ ಚಲಾಯಿಸಿ](../../../03-rag) -- [ಅಪ್ಲಿಕೇಶನ್ ಬಳಕೆ](../../../03-rag) - - [ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ್ಲೋಡ್ ಮಾಡಿ](../../../03-rag) - - [ಪ್ರಶ್ನೆಗಳ ಕೇಳಿ](../../../03-rag) - - [ಮೂಲ ಉಲ್ಲೇಖಗಳನ್ನು ಪರಿಶೀಲಿಸಿ](../../../03-rag) - - [ಪ್ರಶ್ನೆಗಳನ್ನು ಪ್ರಯೋಗಿಸಿ](../../../03-rag) -- [ಮುಖ್ಯ ತತ್ವಗಳು](../../../03-rag) - - [ಚಂಕಿಂಗ್ ತಂತ್ರಜ್ಞಾನ](../../../03-rag) - - [ಸಮಾನತೆ ಅಂಕೆಗಳು](../../../03-rag) - - [ಇನ್-ಮೆಮೊರಿ ಸಂಗ್ರಹಣೆ](../../../03-rag) - - [ಸಂದರ್ಭ ಕಿಟಕಿ ನಿರ್ವಹಣೆ](../../../03-rag) -- [RAG ಎಷ್ಟು ಮುಖ್ಯ?](../../../03-rag) -- [ಮುಂದಿನ ಹಂತಗಳು](../../../03-rag) +- [ವಿಡಿಯೋ ಓಟ](#ವಿಡಿಯೋ-ಓಟ) +- [ನೀವು ಕಲಿಯುವುದು](#ನೀವು-ಕಲಿಯುವುದು) +- [ಮೊದಲು ಬೇಕಾಗಿರುವದು](#ಮೊದಲಿಗೆ-ಬೇಕಾಗಿರುವುದು) +- [RAG ಅನ್ನು ತಿಳಿದುಕೊಳ್ಳುವುದು](#rag-ಅನ್ನು-ತಿಳಿದುಕೊಳ್ಳುವುದು) + - [ಈ ಟ್ಯುಟೋರಿಯಲ್ ಯಾವ RAG ವಿಧಾನವನ್ನು ಬಳಸುತ್ತದೆ?](#ಈ-ಟ್ಯುಟೋರಿಯಲ್-ಯಾವ-rag-ವಿಧಾನವನ್ನು-ಬಳಸುತ್ತದೆ) +- [ಇದು ಹೇಗೆ ಕೆಲಸ ಮಾಡುತ್ತದೆ](#ಇದು-ಹೇಗೆ-ಕೆಲಸ-ಮಾಡುತ್ತದೆ) + - [ದಾಖಲೆ ಪ್ರಕ್ರಿಯೆ](#ಡಾಕ್ಯುಮೆಂಟ್-ಪ್ರಕ್ರಿಯೆ) + - [ಎಂಬೆಡ್ಡಿಂಗ್ ಸೃಷ್ಟಿಸುವುದು](#ಎಂಬೆಡ್ಡಿಂಗ್-ಸೃಷ್ಠಿ) + - [ಅರ್ಥ ಬೋಧಕ ಹುಡುಕಾಟ](#ಅರ್ಥಬೋಧಕ-ಹುಡುಕಾಟ) + - [ಉತ್ತರ ಉತ್ಪಾದನೆ](#ಉತ್ತರ-ರಚನೆ) +- [ಅಪ್ಲಿಕೇಶನ್ ಓಡಿಸಿ](#ಅಪ್ಲಿಕೇಶನ್-ಚಾಲನೆ) +- [ಅಪ್ಲಿಕೇಶನ್ ಬಳಸುವುದು](#ಅಪ್ಲಿಕೇಶನ್-ಬಳಕೆ) + - [ದಾಖಲೆ ಅಪ್ಲೋಡ್ ಮಾಡಲಾಗಿದೆ](#ಡಾಕ್ಯುಮೆಂಟ್-ಅಪ್ಲೋಡ್-ಮಾಡುವುದು) + - [ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳಿ](#ಪ್ರಶ್ನೆಗಳು-ಕೇಳಿ) + - [ಮೂಲ ಉಲ್ಲೇಖಗಳನ್ನು ಪರಿಶೀಲಿಸಿ](#ಮೂಲ-ಸೂಚನೆಗಳನ್ನು-ಪರಿಶೀಲಿಸುವುದು) + - [ಪ್ರಶ್ನೆಗಗಳೊಂದಿಗೆ ಪ್ರયોગ ಮಾಡಿ](#ಪ್ರಶ್ನೆಗಳಲ್ಲಿ-ಪ್ರಯೋಗ-ಮಾಡಿ) +- [ಮುಖ್ಯವಾಗಿ ತತ್ವಗಳು](#ಪ್ರಮುಖ-ಕಲ್ಪನೆಗಳು) + - [ಚಂಕಿಂಗ್ ತಂತ್ರವಿಧಾನ](#ತುಣಕುಗಳ-ತಂತ್ರ) + - [ಒಪಾದನೆ ಅಂಕಗಳು](#ಸಮಾನತೆ-ಅಂಕೆಗಳು) + - [ಸ್ಮೃತಿ ಸಂಗ್ರಹಣೆ](#ಮೆಮೊರಿ-ಸಂಗ್ರಹಣೆ) + - [ಸಂದರ್ಭ ವಿಂಡೋ ನಿರ್ವಹಣೆ](#ಸನ್ನಿವೇಶ-ಕಿಟಕಿ-ನಿರ್ವಹಣೆ) +- [ಯಾವಾಗ RAG ಮಹತ್ವವಾಗುತ್ತದೆ](#rag-ಯಾಗಿರುವ-ಸಂದರ್ಭಗಳು) +- [ಮುಂದಿನ ಹೆಜ್ಜೆಗಳು](#ಮುಂದಿನ-ಹಂತಗಳು) -## ವಿಡಿಯೋ ವಾಕ್ಥ್ರೂ +## ವಿಡಿಯೋ ಓಟ -ಈ ಚಲನಾವಳಿಯನ್ನು ವೀಕ್ಷಿಸಿ, ಇದು ಈ ಮೊಡ್ಯೂಲ್ ನೊಂದಿಗೆ ಹೇಗೆ ಪ್ರಾರಂಭಿಸಬೇಕು ಎಂಬುದನ್ನು ವಿವರಿಸುತ್ತದೆ: +ಈ ಲೈವ್ ಸೆಷನ್ ನೋಡಿ, ಇದು ಈ ಮೊಡ್ಯೂಲ್ ಆರಂಭಿಸುವ ರೀತಿಯನ್ನು ವಿವರಿಸುತ್ತದೆ: -LangChain4j ಜೊತೆಗೆ RAG - ನೇರ ಸೇಷನ್ +RAG with LangChain4j - Live Session -## ನೀವು ಕಲಿಯೋದು ಏನು +## ನೀವು ಕಲಿಯುವುದು -ಹಿಂದಿನ ಮೊಡ್ಯೂಲ್‌ಗಳಲ್ಲಿ, ನೀವು AI ಜೊತೆ ಸಂಭಾಷಣೆ ಹೇಗೆ ಮಾಡಬೇಕು ಹಾಗೂ ನಿಮ್ಮ ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ಪರಿಣಾಮಕಾರಿಯಾಗಿ ಹೇಗೆ ರಚಿಸಬೇಕು ಎಂಬುದನ್ನು ಕಲಿತಿರಿ. ಆದರೆ ಒಂದು ಮೂಲಭೂತ ಸೀಮಿತತೆ ಇದೆ: ಭಾಷಾ ಮಾದರಿಗಳು ಕೇವಲ ತರಬೇತಿ ಸಮಯದಲ್ಲಿ ಕಲಿತ ಮಾಹಿತಿಯನ್ನಷ್ಟೇ ಗೊತ್ತಿವೆ. ಅವು ನಿಮ್ಮ ಕಂಪನಿಯ سياಷ್ಟೆಗಳು, ನಿಮ್ಮ ಪ್ರಾಜೆಕ್ಟ್ ಡಾಕ್ಯುಮೆಂಟೇಶನ್ ಅಥವಾ ಅವು ತರಬೇತು ಪಡೆಯದ ಯಾವುದೇ ಮಾಹಿತಿಯನ್ನು ಉತ್ತರಿಸಲು ಸಾಧ್ಯವಿಲ್ಲ. +ಹಿಂದಿನ ಮೋಡ್ಯೂಲ್‌ಗಳಲ್ಲಿ, ನೀವು AI ಜೊತೆಗೆ ಸಂಭಾಷಣೆ ಮಾಡುವುದು ಮತ್ತು ನಿಮ್ಮ ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ಪರಿಣಾಮಕಾರಿಯಾಗಿ ರಚಿಸುವುದನ್ನು ಕಲಿತಿದ್ದೀರಿ. ಆದರೆ ಇದರಲ್ಲಿ ಅಂಶಗಳ ನಿರ್ಬಂಧವಿದೆ: ಭಾಷಾ ಮಾದರಿಗಳು ತರಬೇತಿಗಾಗಿ ಕಲಿತ ವಿಷಯ ಮಾತ್ರವೇ ತಿಳಿದುಕೊಳ್ಳುತ್ತವೆ. ಅವು ನಿಮ್ಮ ಕಂಪನಿಯ ನೀತಿಗಳು, ನಿಮ್ಮ ಪ್ರಾಜೆಕ್ಟ್ ಡಾಕ್ಯುಮೆಂಟೇಶನ್ ಅಥವಾ ಅವರು ತರಬೇತಿಗೆ ಒಳಪಡದ ಯಾವುದೇ ಮಾಹಿತಿಯನ್ನು ಉತ್ತರಿಸತಕ್ಕವಿಲ್ಲ. -RAG (ಪುನರಾವರ್ತನೆ-ವೃದ್ಧಿಪಡಿಸಿದ ತಯಾರಿ) ಈ ಸಮಸ್ಯೆಯನ್ನು ಪರಿಹರಿಸುತ್ತದೆ. ಮಾದರಿಯನ್ನು ನಿಮ್ಮ ಮಾಹಿತಿಯನ್ನು ಕಲಿಸುವ ಬದಲು (ಅದು ದುಬಾರಿಯಾಗಿದ್ದು ಅಪ್ರಾಯೋಗಿಕವಲ್ಲ), ನೀವು ಅದಕ್ಕೆ ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಪರಿಶೀಲಿಸುವ ಸಾಮರ್ಥ್ಯ ನೀಡುವಿರಿ. ಯಾರಾದರೂ ಪ್ರಶ್ನೆ ಕೇಳಿದಾಗ, ಸಿಸ್ಟಮ್ ಸಂಬಂಧಿತ ಮಾಹಿತಿಯನ್ನು ಹುಡುಕಿ ಅದನ್ನ ಪ್ರಾಂಪ್ಟ್‌ನೊಳಗೆ ಸೇರಿಸುತ್ತದೆ. ನಂತರ ಮಾದರಿ ಆ ಪಡೆದ ಸಂದರ್ಭದ ಆಧಾರದ ಮೇಲೆ ಉತ್ತರ ನೀಡುತ್ತದೆ. +RAG (Retrieval-Augmented Generation - ಪ್ರತಿಪ್ರಾಪ್ತಿ ಹೆಚ್ಚಿಸಲಾದ ಉತ್ಪಾದನೆ) ಈ ಸಮಸ್ಯೆ ಪರಿಹರಿಸುತ್ತದೆ. ಮಾದರಿಯನ್ನು ನಿಮ್ಮ ಮಾಹಿತಿಯನ್ನು ಕಲಿಸುವ ಬದಲು (ಅದು ದುರ್ಗಮ ಮತ್ತು ಅಸಾಧ್ಯ), ನೀವು ಅದಕ್ಕೆ ನಿಮ್ಮ ದಾಖಲೆಗಳ ಮೂಲಕ ಹುಡುಕುವ ಸಾಮರ್ಥ್ಯವನ್ನು ನೀಡುತ್ತೀರಿ. ಯಾರಾದರೂ ಪ್ರಶ್ನೆ ಕೇಳಿದಾಗ, ವ್ಯವಸ್ಥೆ ಸಂಬಂಧಿಸಿದ ಮಾಹಿತಿಯನ್ನು ಹುಡುಕಿ ಪ್ರಾಂಪ್ಟ್‌ಗೆ ಸೇರಿಸುತ್ತದೆ. ಮಾದರಿ ನಂತರ ಆ ಪ್ರತಿಪ್ರಾಪ್ತ ಸಂಧರ್ಭವನ್ನು ಆಧರಿಸಿ ಉತ್ತರಿಸುತ್ತದೆ. -RAG ಅನ್ನು ಮಾದರಿಗೆ ಉಲ್ಲೇಖ ಗ್ರಂಥಾಲಯವನ್ನು ನೀಡಿರುವಂತೆ ಕಳೆಯಿರಿ. ನೀವು ಪ್ರಶ್ನೆ ಕೇಳಿದಾಗ, ಸಿಸ್ಟಮ್: +RAG ಅನ್ನು ಮಾದರಿಗೆ ಒಂದು ಉಲ್ಲೇಖ ಗ್ರಂಥಾಲಯ ನೀಡುವಂತೆ ಪರಿಗಣಿಸಿ. ನೀವು ಪ್ರಶ್ನೆ ಕೇಳಿದಾಗ, ವ್ಯವಸ್ಥೆ: -1. **ಬಳಕೆದಾರ ಪ್ರಶ್ನೆ** - ನೀವು ಪ್ರಶ್ನೆ ಕೇಳುತ್ತೀರಿ -2. **ಎಂಬೆಡ್ಡಿಂಗ್** - ನಿಮ್ಮ ಪ್ರಶ್ನೆ ವಕ್ಟರಾಗಿ ಪರಿವರ್ತನೆ ಮಾಡಲ್ಪಡುತ್ತದೆ -3. **ವಕ್ಟರ್ ಶೋಧನೆ** - ಸನ್ನಿಹಿತ ಡಾಕ್ಯುಮೆಂಟ್ ಚಂಕ್‌ಗಳನ್ನು ಹುಡುಕುತ್ತದೆ -4. **ಸಂದರ್ಭ ಸಂಯೋಜನೆ** - ಸಂಬಂಧಿತ ಚಂಕ್‌ಗಳನ್ನು ಪ್ರಾಂಪ್ಟ್‌ಗೆ ಸೇರಿಸುತ್ತದೆ -5. **ಪ್ರತಿಕ್ರಿಯೆ** - LLM ಆ ಸಂದರ್ಭದ ಆಧಾರದ ಮೇಲೆ ಉತ್ತರ ಸೃಷ್ಟಿಸುತ್ತದೆ +1. **ಬಳಕೆದಾರನ ಪ್ರಶ್ನೆ** - ನೀವು ಒಂದು ಪ್ರಶ್ನೆ ಕೇಳುತ್ತೀರಿ +2. **ಎಂಬೆಡ್ಡಿಂಗ್** - ನಿಮ್ಮ ಪ್ರಶ್ನೆಯನ್ನು ವೆಕ್ಟರಾಗಿ ಪರಿವರ್ತಿಸುತ್ತದೆ +3. **ವೆಕ್ಟರ್ ಹುಡುಕಾಟ** - ಸಮಾನಮಾನದ ದಸ್ತಾವೇಜು ಚುಂಕ್‌ಗಳನ್ನು ಹುಡುಕುತ್ತದೆ +4. **ಸಂದರ್ಭ ಸಂಯೋಜನೆ** - ಸಂಬಂಧಿಸಿದ ಚುಂಕ್‌ಗಳನ್ನು ಪ್ರಾಂಪ್ಟ್‌ಗೆ ಸೇರಿಸುತ್ತದೆ +5. **ಪ್ರತಿಕ್ರಿಯೆ** - LLM ಆಂದಿರಿಸುಗೆ ಆ ಸಂಧರ್ಭದ ಆಧಾರಿತ ಉತ್ತರವನ್ನು ತಯಾರಿಸುತ್ತದೆ -ಇದು ಮಾದರಿಯ ಪ್ರತಿಕ್ರೀಯೆಗಳನ್ನು ಅದರ ತರಬೇತಿ ಜ್ಞಾನಗಿಂತಲೂ ನಿಮ್ಮ ವಾಸ್ತವಿಕ ಡೇಟಾದ ಆಧಾರದಲ್ಲಿ ನೆಲೆಸಲು ಸಹಾಯಮಾಡುತ್ತದೆ. +ಇದು ಮಾದರಿಯ ಉತ್ತರಗಳನ್ನು ಅದರ ತರಬೇತಿ ತಿಳಿವಳಿಕೆಗೆ ಭರವಸೆ ಇಡುವ ಬದಲು ನಿಮ್ಮ ನಿಜವಾದ ಡೇಟಾದ ಮೇಲೆ ನೆಲೆಸುತ್ತದೆ. -## ಮೂಲಾಗ್ರಹಣಗಳು +## ಮೊದಲಿಗೆ ಬೇಕಾಗಿರುವುದು -- ಪೂರ್ಣಗೊಂಡಿದೆ [Module 00 - ತ್ವರಿತ ಪ್ರಾರಂಭ](../00-quick-start/README.md) (ಈ ಮೊಡ್ಯೂಲ್‌ನ ನಂತರದ ಉದಾಹರಣೆಯಾಗಿ ರಿಯಾಯಿತ RAG) -- ಪೂರ್ಣಗೊಂಡಿದೆ [Module 01 - ಪರಿಚಯ](../01-introduction/README.md) (Azure OpenAI ಸಂಪನ್ಮೂಲಗಳು ಸ್ಥಾಪಿಸಲಾಗಿದೆ, `text-embedding-3-small` ಎಂಬ_embedding ಮಾದರಿ ಸೇರಿದಂತೆ) -- ಮೂಲಾಣ್ವಯ `.env` ಫೈಲ್‌ನಲ್ಲಿ Azure ದೃಢೀಕರಣಗಳೊಂದಿಗೆ (Module 01 ನಲ್ಲಿ `azd up` ಮೂಲಕ ಸೃಷ್ಟಿಸಲಾಗಿದೆ) +- ಪೂರ್ಣಗೊಂಡ [Module 01 - ಪರಿಚಯ](../01-introduction/README.md) (Azure OpenAI ಸಂಪನ್ಮೂಲಗಳನ್ನು ನಿಯೋಜಿಸಲಾಗಿದೆ, `text-embedding-3-small` ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿಯನ್ನು ಸೇರಿಸಿ) +- ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ `.env` ಫೈಲ್ ಆಗಿರುವುದು (Module 01 ನಲ್ಲಿ `azd up` ಮೂಲಕ ರಚಿಸಲಾಗಿದೆ) -> **ಗುರುತಿಸು:** ನೀವು Module 01 ಪೂರ್ಣಗೊಳಿಸಿರಲಿಲ್ಲ ಏನಾದರೂ, ಮೊದಲಿಗೆ ಅಲ್ಲಿ ಡಿಪ್ಲಾಯ್ಮೆಂಟ್ ಸೂಚನೆಗಳನ್ನು ಅನುಸರಿಸಿ. `azd up` ಆಜ್ಞೆ GPT ಚಾಟ್ ಮಾದರಿಯನ್ನೂ ಮತ್ತು ಈ ಮೊಡ್ಯೂಲ್ ಬಳಕೆ ಮಾಡುವ ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿಯನ್ನೂ ಡಿಪ್ಲಾಯ್ ಮಾಡುತ್ತದೆ. +> **ಗಮನಿಸಿ:** ನೀವು Module 01 ನ ಪೂರ್ಣಗೊಳಿಸದಿದ್ದರೆ, ಮೊದಲಿಗೆ ಅಲ್ಲಿ ನೀಡಲಾದ ನಿಯೋಜನೆ ಸೂಚನೆಗಳನ್ನು ಅನುಸರಿಸಿ. `azd up` ಆಜ್ಞೆ GPT ಚಾಟ್ ಮಾದರಿ ಮತ್ತು ಈ ಮೋಡ್ಯೂಲ್ ಬಳಸುವ ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿಯನ್ನು ಎರಡನ್ನೂ ನಿಯೋಜಿಸುತ್ತದೆ. -## RAG ನ ಅರಿವು +## RAG ಅನ್ನು ತಿಳಿದುಕೊಳ್ಳುವುದು -ಕೆಳಗಿನ ಚಿತ್ರೀಕರಣವು ಮೂಲ ಕಲ್ಪನೆಯನ್ನು ಚಿತ್ರಿಸುತ್ತದೆ: ಮಾದರಿಯ ತರಬೇತಿ ಮಾಹಿತಿಯ ಮೇಲೆ ಮಾತ್ರ ಅವಲಂಬಿಸದಂತೆ, RAG ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳ ಉಲ್ಲೇಖ ಗ್ರಂಥಾಲಯವನ್ನು ನೀಡುತ್ತದೆ ಪ್ರತಿಯೊಂದು ಉತ್ತರ ತಯಾರಿಸುವ ಮುನ್ನ ಅವುಗಳನ್ನು ಪರಿಶೀಲಿಸಲು. +ಕೆಳಗಿನ ಚಿತ್ರವು ಮೂಲಭೂತ ವಿಚಾರವನ್ನು ವಿವರಿಸುತ್ತದೆ: ಮಾದರಿಯ ತರಬೇತಿ ದತ್ತಾಂಶದಲ್ಲಿ ಮಾತ್ರ ಅವಲಂಬಿಸುವ ಬದಲು, RAG ಪ್ರತಿ ಉತ್ತರ ತಯಾರಿಸುವ ಮೊದಲು ನಿಮ್ಮ ದಾಖಲೆಗಳ ಉಲ್ಲೇಖ ಗ್ರಂಥಾಲಯವನ್ನು ಒದಗಿಸುವುದು. -RAG ಎಂದರೆ ಏನು +What is RAG -*ಈ ಚಿತ್ರಣವು ಸಾಂಪ್ರದಾಯಿಕ LLM (ತರಬೇತಿ ಡೇಟಾದಿಂದ ಅಂದಾಜು ಮಾಡುತ್ತದೆ) ಮತ್ತು RAG-ವೃದ್ಧಿತ LLM (ಮೊದಲು ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಪರಿಶೀಲಿಸುತ್ತದೆ) ನಡುವಿನ ವ್ಯತ್ಯಾಸವನ್ನು ತೋರಿಸುತ್ತದೆ.* +*ಈ ಚಿತ್ರವು ಕ್ರಮಬದ್ಧ LLM (ಅವು ತರಬೇತಿ ದತ್ತಾಂಶದಿಂದ ಊಹಿಸುವದು) ಮತ್ತು RAG-ಉನ್ನತಿಗೊಳ್ಳಲಾದ LLM (ಅವು ಮೊದಲು ನಿಮ್ಮ ದಸ್ತಾವೇಜುಗಳನ್ನು ಪರಾಮರ್ಶಿಸುವದು) ನಡುವಿನ ವ್ಯತ್ಯಾಸವನ್ನು ತೋರಿಸುತ್ತದೆ.* -ದಾಖಲೆಯ ಭಾಗಗಳು ಎಲೆ-ಎಲೆ ಓಟವನ್ನು ಹೇಗೆ ಸಂಪರ್ಕಿಸುತ್ತವೆ ಎಂದು ಇಲ್ಲಿ ಹೇಳಲಾಗಿದೆ. ಬಳಕೆದಾರನ ಪ್ರಶ್ನೆ ನಾಲ್ಕು ಹಂತಗಳಿಂದ (ಎಂಬೆಡ್ಡ್, ವಕ್ಟರ್ ಶೋಧನೆ, ಸಂದರ್ಭ ಸಂಯೋಜನೆ, ಉತ್ತರ ತಯಾರಿ) ಸಾಗುತ್ತದೆ — ಪ್ರತಿಯೊಂದು ಹಂತವು ಹಿಂದಿನದನ್ನು ಆಧರಿಸಿದೆ: +ಈ ಭಾಗಗಳು ಹೇಗೆ ಅಂತರ್‌ಸೆಳುವಾಗಿವೆ ಎಂಬುದನ್ನು ಇಲ್ಲಿ ನೋಡೋಣ. ಬಳಕೆದಾರರ ಪ್ರಶ್ನೆ ನಾಲ್ಕು ಹಂತಗಳ ಮೂಲಕ ಹರಡುತ್ತದೆ — ಎಂಬೆಡ್ಡಿಂಗ್, ವೆಕ್ಟರ್ ಹುಡುಕಾಟ, ಸಂಧರ್ಭ ಸಂಯೋಜನೆ, ಮತ್ತು ಉತ್ತರ ಉತ್ಪಾದನೆ — ಪ್ರತಿಯೊಂದು ಹಂತ ಹಿಂದಿನ ಹಂತದ ಮೇಲೆ ನಿರ್ಮಿತವಾಗಿದೆ: -RAG ವಾಸ್ತುಶಿಲ್ಪ +RAG Architecture -*ಈ ಚಿತ್ರಣವು RAG ಪೈಪ್ಲೈನ್‌ನ ಎಲೆ-ಎಲೆ ಕ್ರಮವನ್ನು ತೋರಿಸುತ್ತದೆ — ಬಳಕೆದಾರ ಪ್ರಶ್ನೆ ಎಂಬೆಡ್ಡಿಂಗ್, ವಕ್ಟರ್ ಶೋಧನೆ, ಸಂದರ್ಭ ಸಂಯೋಜನೆ, ಹಾಗೂ ಉತ್ತರ ನಿರ್ಮಾಣದ ಮೂಲಕ ಸಾಗುತ್ತದೆ.* +*ಈ ಚಿತ್ರವು ಅಂತಿಮ RAG ಪೈಪ್‌ಲೈನ್ ಅನ್ನು ತೋರಿಸುತ್ತದೆ — ಬಳಕೆದಾರ ಪ್ರಶ್ನೆ ಎಂಬರ್, ವೆಕ್ಟರ್ ಹುಡುಕಾಟ, ಸಂಧರ್ಭ ಸಂಯೋಜನೆ ಮತ್ತು ಉತ್ತರ ಉತ್ಪಾದನೆ ಮುಖಾಂತರ ಹರಡುತ್ತದೆ.* -ಈ ಮೊಡ್ಯೂಲ್‌ನ ಉಳಿದ ಭಾಗವು ಪ್ರತಿಯೊಂದು ಹಂತವನ್ನು ವಿವರವಾಗಿ ಕೀನದಂತೆ ತೋರಿಸುತ್ತದೆ, ಜೊತೆಗೆ ನೀವು ಓಡಿಸಬಲ್ಲ ಹಾಗೂ ಬದಲಾಯಿಸಬಲ್ಲ ಕೋಡ್ ನೊಂದಿಗೆ. +ಈ ಮೋಡ್ಯೂಲ್‌ನ ಇತರ ಭಾಗವು ಪ್ರತಿ ಹಂತವನ್ನು ವಿವರವಾಗಿ ನಡಿಸಿ, ನೀವು ಓಡಿಸಿ ಮತ್ತು ಬದಲಿಸಬಹುದಾದ ಕೋಡ್ ಜೊತೆಗೆ ನೀಡುತ್ತದೆ. -### ಈ ಪಾಠದಲ್ಲಿ ಯಾವ RAG ವಿಧಾನ ಬಳಕೆ ಮಾಡಲಾಗಿದೆ? +### ಈ ಟ್ಯುಟೋರಿಯಲ್ ಯಾವ RAG ವಿಧಾನವನ್ನು ಬಳಸುತ್ತದೆ? -LangChain4j ಮೂರು ರೀತಿಗಳಲ್ಲಿ RAG ಅನ್ನು ಅನುಷ್ಠಾನಗೊಳಿಸುತ್ತದೆ, ಪ್ರತಿ ಒಂದು ವಿಭಿನ್ನ ಮಟ್ಟದ ಅವಲೋಕನ ಹೊಂದಿದೆ. ಕೆಳಗಿನ ಚಿತ್ರಣದಲ್ಲಿ ಅವುಗಳನ್ನು ಸಮನಾಗಿ ಹೋಲಿಸಲಾಗಿದೆ: +LangChain4j RAG ಅನ್ನು ಜಾರಿಗೆ ತರಲು ಮೂರು ವಿಧಾನಗಳನ್ನು ಒದಗಿಸುತ್ತದೆ, ಪ್ರತಿ ಒಂದು ವಿಭಿನ್ನ ಸಾರತನದ ಮಟ್ಟವನ್ನು ಹೊಂದಿದೆ. ಕೆಳಗಿನ ಚಿತ್ರದಲ್ಲಿ ಅವುತು ಹೋಲಿಕೆ ಮಾಡಲಾಗಿದೆ: -LangChain4j ನಲ್ಲಿ ಮೂರು RAG ವಿಧಾನಗಳು +Three RAG Approaches in LangChain4j -*ಈ ಚಿತ್ರಣವು LangChain4j ಯಲ್ಲಿರುವ ಮೂರು RAG ವಿಧಾನಗಳ — Easy, Native, ಮತ್ತು Advanced — ಪ್ರಮುಖ ಅಂಶಗಳನ್ನೂ ಮತ್ತು ಬಳಸುವ ಸಂದರ್ಭಗಳನ್ನೂ ತೋರಿಸುತ್ತದೆ.* +*ಈ ಚಿತ್ರವು LangChain4j ನಲ್ಲಿ ಇರುವ ಮೂರು RAG ವಿಧಾನಗಳನ್ನು ಹೋಲೈಸುತ್ತದೆ — ಇಸಿ, ಮೂಲ, ಹಾಗೂ ಸುಧಾರಿತ — ಅವುಗಳ ಪ್ರಮುಖ ಅಂಶಗಳು ಹಾಗೂ ಯುರಿಗಾಗಿರುವ ಸಂದರ್ಭಗಳು.* -| ವಿಧಾನ | ಅದು ಏನು ಮಾಡುತ್ತದೆ | ವ್ಯಾಪ್ತಿಚೌಕಟ್ಟು | +| ವಿಧಾನ | ಇದು ಏನು ಮಾಡುತ್ತದೆ | ವ್ಯಾಪಾರ-ಆಫ್ | |---|---|---| -| **ಸರಳ RAG** | `AiServices` ಮತ್ತು `ContentRetriever` ಮೂಲಕ ಎಲ್ಲವನ್ನೂ ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಸಂಪರ್ಕಿಸುತ್ತದೆ. ನೀವು ಇಂಟರ್ಫೇಸ್ ಅನ್ನು ಸೂಚಿಸುತ್ತೀರಿ, ರಿಟ್ರಿವರ್ ಅನ್ನು ಲಗತ್ತಿಸುತ್ತೀರಿ, ಆಗ LangChain4j ಎಂಬೆಡ್ಡಿಂಗ್, ಶೋಧನೆ, ಹಾಗು ಪ್ರಾಂಪ್ಟ್ ಸಂಯೋಜನೆಗಳನ್ನು ಹಿಂದೆ ನಡಿಸುತ್ತದೆ. | ಅತ್ಯल्प ಕೋಡ್, ಆದರೆ ಪ್ರತಿಯೊಂದು ಹಂತದಲ್ಲಿಯೇ ಏನು ನಡೆಯುತ್ತಿದೆ ನೋಡಲು ಆಗದು. | -| **ನೈಟಿವ್ RAG** | ನೀವು ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿಯನ್ನು ಕರೆದುಕೊಳ್ಳುತ್ತೀರಿ, ಸಂಗ್ರಹಸ್ಥಳವನ್ನು ಹುಡುಕುತ್ತೀರಿ, ಪ್ರಾಂಪ್ಟ್ ರಚಿಸುತ್ತೀರಿ, ಹಾಗೂ ನಿಮ್ಮಿಂದ ಉತ್ತರ ಸೃಷ್ಟಿಸುತ್ತೀರಿ — ಸ್ಪಷ್ಟವಾದ ಒಂದು ಹಂತ ಪ್ರತಿ ಸಮಯ. | ಹೆಚ್ಚು ಕೋಡ್, ಆದರೆ ಎಲ್ಲಾ ಹಂತಗಳನ್ನು ಕಣ್ತುಂಬಿಕೊಳ್ಳಬಹುದು ಮತ್ತು ಬದಲಾಯಿಸಬಹುದು. | -| **ಅಡ್ವಾನ್ಸ್ RAG** | `RetrievalAugmentor` ಫ್ರೇಮ್ವರ್ಕ್ ಅನ್ನು ಬಳಸಿ, ಕ್ವೆರೀ ಪರಿವರ್ತಕರು, ಮಾರ್ಗ ನಿರ್ದೇಶಕರು, ಪುನಃ ಅಂಕಿತಕಾರರು, ಮತ್ತು ವಿಷಯ ಸಂಯೋಜಕರೊಂದಿಗೆ ಉತ್ಪಾದನಾ ಮತ್ತು ಪ್ರಾಂಪ್ಟ್ ಗ್ರೇಡ್ ಪೈಪ್ಲೈನ್ಗಳಿಗೆ. | ಪರಮಲವಚನೀಯತೆ ಆದರೆ ಗಣನೀಯವಾಗಿ ಹೆಚ್ಚಿನ ಜಟಿಲತೆ. | +| **ಇಸಿ RAG** | ಎಲ್ಲಾ ಕೆಲಸಗಳನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ `AiServices` ಮತ್ತು `ContentRetriever` ಮೂಲಕ ಸಂಪರ್ಕಿಸುತ್ತದೆ. ನೀವು ಒಂದು ಇಂಟರ್‌ಫೇಸ್ ಅನ್ನು ಅಂಶಮಾಡಿ, ರಿಟ್ರೀವರ್ ಅಳವಡಿಸಿ, LangChain4j ಎಂಬೆಡ್ಡಿಂಗ್, ಹುಡುಕಾಟ ಮತ್ತು ಪ್ರಾಂಪ್ಟ್ ಸಂಯೋಜನೆಗಳನ್ನು ಹಿಂಭಾಗದಲ್ಲಿ ನಿರ್ವಹಿಸುತ್ತದೆ. | ಕನಿಷ್ಟ ಕೋಡ್, ಆದರೆ ಪ್ರತಿ ಹಂತದಲ್ಲಿ ಏನು ನಡೆಯುತ್ತಿದೆ ಅರ್ಥವಾಗುವುದಿಲ್ಲ. | +| **ಮೂಲ RAG** | ನೀವು ತಡದಿಂದ ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿಯನ್ನು ಕರೆ ಮಾಡಿ, ಸ್ಟೋರ್ ಅನ್ನು ಹುಡುಕಿ, ಪ್ರಾಂಪ್ಟ್ ರಚಿಸಿ ಮತ್ತು ಉತ್ತರ ಉತ್ಪಾದನೆ ಮಾಡುತ್ತೀರಿ — ಪ್ರತಿಯೊಂದು ಹಂತವನ್ನು ಸ್ಪಷ್ಟವಾಗಿ ಕ್ರಮಬದ್ಧವಾಗಿ. | ಹೆಚ್ಚು ಕೋಡ್, ಆದರೆ ಪ್ರತಿಯೊಂದು ಹಂತವೂ ಗೋಚರವಾಗಿದ್ದು ಬದಲಾಯಿಸಲು ಸಾಧ್ಯ. | +| **ಸುಧಾರಿತ RAG** | `RetrievalAugmentor` ಫ್ರೇಮ್‌ವರ್ಕ್ ಅನ್ನು ಬಳಸಿ ಜನರಲ್-ಗ್ರೇಡ್ ಪೈಪ್‌ಲೈನ್‌ಗಳಿಗೆ ಪ್ಲಗ್ ಮಾಡಬಹುದಾದ ಪ್ರಶ್ನಾ ಪರಿವರ್ತಕರು, ರೌಟರ್ಸ್, ಮರು-ರ್ಯಾಂಕರ್ಸ್ ಮತ್ತು ವಿಷಯ ಸಂಯೋಜಕರುಗಳನ್ನು ಹೊಂದಿದೆ. | ಗರಿಷ್ಠ ವಿವರಣೆ ಮತ್ತು ಸ್ವಾತಂತ್ರ್ಯ, ಆದರೆ ಬಹುಪರಿಶ್ರಮದೊಂದಿಗೆ. | -**ಈ ಪಾಠದಲ್ಲಿ ನೈಟಿವ್ ವಿಧಾನ ಬಳಸದಾಗಿದೆ.** RAG ಪೈಪ್ಲೈನಿನ ಪ್ರತಿಯೊಂದು ಹಂತವನ್ನು — ಕ್ವೆರಿಯನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡುವುದು, ವಕ್ಟರ್ ಸ್ಟೋರ್ ಅನ್ನು ಶೋಧಿಸುವುದು, ಸಂದರ್ಭ ಸಂಯೋಜಿಸುವುದು, ಮತ್ತು ಉತ್ತರ ಸೃಷ್ಟಿಸುವುದು — [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ನಲ್ಲಿ ಸ್ಪಷ್ಟವಾಗಿ ಬರೆಯಲಾಗಿದೆ. ಇದು ಉದ್ದೇಶಿತವಾಗಿದೆ: ಅಧ್ಯಯನ ಸಂಪನ್ಮೂಲವಾಗಿ, ಪ್ರತಿಯೊಂದು ಹಂತವನ್ನು ನೀವು ಕಂಡು ಅರಿತುಕೊಳ್ಳುವುದು ಕೋಡ್ ಕಡಿಮೆ ಮಾಡಿಕೊಳ್ಳುವುದಕ್ಕಿಂತ ಹೆಚ್ಚು ಮಹತ್ವದಂತೆ. ನೀವು ಭಾಗಗಳು ಹೇಗೆ ಜೋಡಿಸುತ್ತವೆ ಎಂದು ಅರ್ಥಮಾಡಿಕೊಂಡ ನಂತರ, ತ್ವರಿತ ಪ್ರೋಟೋಟೈಪ್‌ಗಳಿಗೆ ಸರಳ RAG ಅಥವಾ ಉತ್ಪಾದನಾ ವ್ಯವಸ್ಥೆಗಳಿಗೆ ಉತ್ತಮ RAG ಕಡೆ ತಿರುಗಬಹುದು. +**ಈ ಟ್ಯುಟೋರಿಯಲ್ ಮೂಲ ವಿಧಾನವನ್ನು ಬಳಸುತ್ತದೆ.** RAG ಪೈಪ್‌ಲೈನ್‌ನ ಪ್ರತಿಯೊಬ್ಬ ಹಂತ — ಪ್ರಶ್ನೆ embeddings, ವೆಕ್ಟರ್‌ಸ್ಟೋರ್ ಹುಡುಕಾಟ, ಸನ್ನಿವೇಶ ಸಂಯೋಜನೆ ಮತ್ತು ಉತ್ತರ ಉತ್ಪಾದನೆ — ಎಲ್ಲವೂ [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ನಲ್ಲಿ ಸ್ಪಷ್ಟವಾಗಿ ಬರೆಯಲ್ಪಟ್ಟಿವೆ. ಇದು ಉದ್ದೇಶಪೂರ್ವಕವಾಗಿದೆ: ಕಲಿಕೆಯ ಸಂಪನ್ಮೂಲವಾಗಿ ಪ್ರತಿಯೊಂದು ಹಂತವನ್ನು ನೀವು ವೀಕ್ಷಿಸಿ ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು ಪ್ರಮುಖ, ಕೋಡ್ ಕಡಿಮೆಗೊಳಿಸುವುದಕ್ಕಿಂತ. ಹಂತಗಳನ್ನು ಹೇಗೆ ಹೊಂದಿಸಿಕೊಳ್ಳುವುದು ತಿಳಿದ ನಂತರ, ನೀವು ತ್ವರಿತ ಪ್ರೋಟೋಟೈಪ್ಗಾಗಿ ಇಸಿ RAG ಅಥವಾ ಉತ್ಪಾದನಾ ವ್ಯವಸ್ಥೆಗಳಿಗೆ ಸುಧಾರಿತ RAG ಗೆ ಹೆಜ್ಜೆ ಹಾಕಬಹುದು. -> **💡 ಸರಳ RAG ವನ್ನು ಈಗಾಗಲೇ ನೋಡಿದ್ದೀರಾ?** [ತ್ವರಿತ ಪ್ರಾರಂಭ ಮೊಡ್ಯೂಲ್](../00-quick-start/README.md) ಡಾಕ್ಯುಮೆಂಟ್ ಪ್ರಶ್ನೋತ್ತರ ಉದಾಹರಣೆ ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) ಒಳಗೊಂಡಿದೆ, ಇದು ಸರಳ RAG ವಿಧಾನವನ್ನು ಬಳಸುತ್ತದೆ — LangChain4j ಎಂಬೆಡ್ಡಿಂಗ್, ಶೋಧನೆ ಮತ್ತು ಪ್ರಾಂಪ್ಟ್ ಸಂಯೋಜನೆಯನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ನಿರ್ವಹಿಸುತ್ತದೆ. ಈ ಮೊಡ್ಯೂಲ್ ಮುಂದಿನ ಹಂತವನ್ನು ತೆಗೆದು ಆ ಪೈಪ್ಲೈನ್ ಅನ್ನು ಮುರಿದು ಪ್ರತಿಯೊಂದು ಹಂತವನ್ನು ನೀವು ನೋಡಲು ಹಾಗೂ ನಿಯಂತ್ರಣ ಮಾಡಲು ಸಾಧ್ಯವಾಗಿಸುತ್ತದೆ. +> **💡 ಇಸಿ RAG ಬಗ್ಗೆ ಕುತೂಹಲವೇ?** LangChain4j ಇಸಿ RAG ಮಾದರಿಯನ್ನು ಸಹ ಒದಗಿಸುತ್ತದೆ, ಇಲ್ಲಿ `AiServices` ಮತ್ತು `ContentRetriever` ಎಂಬೆಡ್ಡಿಂಗ್, ಹುಡುಕಾಟ ಮತ್ತು ಪ್ರಾಂಪ್ಟ್ ಸಂಯೋಜನೆಯನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ನಿರ್ವಹಿಸುತ್ತವೆ. ಈ ಮೋಡ್ಯೂಲ್ ಸ್ಪಷ್ಟ ಹಾದಿಯನ್ನು ಅನುಸರಿಸುತ್ತದೆ — ಆ ಪೈಪ್‌ಲೈನ್ ಅನ್ನು ಪಡೆದೊಯ್ಯುತ್ತದೆ ಮತ್ತು ನೀವು ಪ್ರತಿಯೊಂದು ಹಂತವನ್ನು ನೋಡಲು ಹಾಗೂ ನಿಯಂತ್ರಿಸಲು ಸಹಾಯವಾಗುತ್ತದೆ. -ಕೆಳಗಿನ ಚಿತ್ರವು Easy RAG ಪೈಪ್ಲೈನ್ ಅನ್ನು ಆ ತ್ವರಿತ ಪ್ರಾರಂಭ ಉದಾಹರಣೆಯಿಂದ ತೋರಿಸುತ್ತದೆ. ಗಮನಿಸಿ ಹೇಗೆ `AiServices` ಮತ್ತು `EmbeddingStoreContentRetriever` ಎಲ್ಲಾ ಸಂಕೀರ್ಣತೆಯನ್ನು ಅಡಗಿಸುತ್ತವೆ — ನೀವು ಡಾಕ್ಯುಮೆಂಟ್ ಲೋಡ್ ಮಾಡುತ್ತೀರಿ, ರಿಟ್ರಿವರ್ ಅನ್ನು ಲಗತ್ತಿಸುತ್ತೀರಿ, ಹಾಗೂ ಉತ್ತರ ಪಡೆಯುತ್ತೀರಿ. ಈ ಮೊಡ್ಯೂಲ್‌ನ ನೈಟಿವ್ ವಿಧಾನ ಆ ಲುಪ್ಯಾಗಿರುವ ಹಂತಗಳನ್ನು ಮುರಿದು ಬಳಸುವವರಿಗೆ ಸ್ಪಷ್ಟತೆ ನೀಡುತ್ತದೆ: +ಕೆಳಗಿನ ಚಿತ್ರವು ಇಸಿ RAG ಪೈಪ್‌ಲೈನ್ ತೋರಿಸುತ್ತದೆ. `AiServices` ಮತ್ತು `EmbeddingStoreContentRetriever` ಎಲ್ಲ ಜಟಿಲತೆಯನ್ನು ಕೊನೆಯವರೆಗೂ ಗೂಪ್ತವಾಗಿಸುತ್ತದೆ — ನೀವು ಒಂದು ಡಾಕ್ಯುಮೆಂಟ್ ಲೋಡ್ ಮಾಡಿ, ರಿಟ್ರೀವರ್ ಅಳವಡಿಸಿ, ಉತ್ತರಗಳನ್ನು ಪಡೆಯುತ್ತೀರಿ. ಈ ಮೋಡ್ಯೂಲ್‌ನ ಮೂಲ ವಿಧಾನ ಆ ಎಲ್ಲಾ ಅಡಗೆ ಹಂತಗಳನ್ನು ತೆರೆದಿರುವುದು: -ಸರಳ RAG ಪೈಪ್ಲೈನ್ - LangChain4j +Easy RAG Pipeline - LangChain4j -*ಈ ಚಿತ್ರವು `SimpleReaderDemo.java` ಯಿಂದ Easy RAG ಪೈಪ್ಲೈನನ್ನು ತೋರಿಸುತ್ತದೆ. ಈ ಮೊಡ್ಯೂಲ್‌ನ ನೈಟಿವ್ ವಿಧಾನವನ್ನು ಹೋಲಿಸಿ: Easy RAG ಎಂಬೆಡ್ಡಿಂಗ್, ರಿಟ್ರಿವಲ್ ಮತ್ತು ಪ್ರಾಂಪ್ಟ್ ಸಂಯೋಜನೆಯನ್ನು `AiServices` ಮತ್ತು `ContentRetriever` ಹಿಂದಿನಿಂದ ಸಡುದಿಸುತ್ತದೆ — ನೀವು ಡಾಕ್ಯುಮೆಂಟ್ ಲೋಡ್ ಮಾಡಿ, ರಿಟ್ರಿವರ್ ಅನ್ನು ಲಗತ್ತಿಸಿ, ಮತ್ತು ಉತ್ತರಗಳನ್ನ ಪಡೆಯುತ್ತೀರಿ. ನೈಟಿವ್ ವಿಧಾನವು ಆ ಪೈಪ್ಲೈನನ್ನು ಮುರಿದು ಪ್ರತಿಯೊಂದು ಹಂತವನ್ನು (ಎಂಬೆಡ್, ಶೋಧನೆ, ಸಂದರ್ಭ ಸಂಯೋಜನೆ, ಸೃಷ್ಟಿ) ನೀವು ಕರೆಯುವಂತೆ ಮಾಡುತ್ತದೆ, ಸಂಪೂರ್ಣ ದೃশ্যತೆಯನ್ನು ಮತ್ತು ನಿಯಂತ್ರಣವನ್ನು ಒದಗಿಸುತ್ತದೆ.* +*ಈ ಚಿತ್ರವು ಇಸಿ RAG ಪೈಪ್‌ಲೈನ್ ತೋರಿಸುತ್ತದೆ. ಈ ಮೋಡ್ಯೂಲ್‌ನಲ್ಲಿ ಬಳಸಲಾದ ಮೂಲ ವಿಧಾನ ಜೊತೆಗೆ ಹೋಲಿಸಿ: ಇಸಿ RAG ಎಂಬೆಡ್ಡಿಂಗ್, ಪ್ರತಿಪ್ರಾಪ್ತಿ ಮತ್ತು ಪ್ರಾಂಪ್ಟ್ ಸಂಯೋಜನೆಯನ್ನು `AiServices` ಮತ್ತು `ContentRetriever` ಹಿಂದೆ ಮುಚ್ಚಿ ಇಡುತ್ತದೆ — ನೀವು ಡಾಕ್ಯುಮೆಂಟ್ ಲೋಡ್ ಮಾಡಿ, ರಿಟ್ರೀವರ್ ಅಳವಡಿಸಿ, ಉತ್ತರಗಳನ್ನು ಪಡೆಯುತ್ತೀರಿ. ಮೂಲ ವಿಧಾನದಲ್ಲಿ ಪ್ರತಿಯೊಂದು ಹಂತಗಳನ್ನು ತೆರೆಯಲಾಗುತ್ತದೆ ಮತ್ತು ನೀವು ಆ ಹಂತಗಳನ್ನು ಕರೆ ಮಾಡಿ, ಸಂಪೂರ್ಣ ನೋಟ ಮತ್ತು ನಿಯಂತ್ರಣ ಹೊಂದುತ್ತೀರಿ.* -## ಹೇಗಿದೆ ಇದರ ಕಾರ್ಯವೈಖರಿ +## ಇದು ಹೇಗೆ ಕೆಲಸ ಮಾಡುತ್ತದೆ -ಈ ಮೊಡ್ಯೂಲ್‌ನ RAG ಪೈಪ್ಲೈನ್ ಬಳಕೆದಾರನು ಪ್ರಶ್ನೆ ಕೇಳುವ ಪ್ರತೀ ಬಾರಿ ಸರಣಿಯಲ್ಲಿ ಚಾಲನೆಯಲ್ಲಿರುವ ನಾಲ್ಕು ಹಂತಗಳಾಗಿ ವಿಭಜಿಸಲಾಗಿದೆ. ಮೊದಲು, ಅಪ್ಲೋಡ್ ಮಾಡಿದ ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು **ಪಾರ್ಸ್ ಮತ್ತು ಚಂಕ್** ಮಾಡುತ್ತದೆ — ಸುಲಭವಾಗಿ ನಿರ್ವಹಿಸುವ ಸಾಧ್ಯವಾದಂತೆ ತುಂಡುಗಳಲ್ಲಿ. ಆ ಚাংಕ್‌ಗಳನ್ನು ನಂತರ **ವಕ್ಟರ್ ಎಂಬೆಡ್ಡಿಂಗ್** ಗಳಾಗಿ ಪರಿವರ್ತಿಸಿ ಸಂಗ್ರಹಿಸಬಹುದು — ಇದರಿಂದ ಅವು ಗಣಿತೀಯವಾಗಿ ಹೋಲಿಸಬಹುದು. ಪ್ರಶ್ನೆ ಬಂದಾಗ, ಸಿಸ್ಟಂ **ಅರ್ಥಪೂರ್ಣ ಶೋಧನೆಯನ್ನು** ಕಾರ್ಯಗತಗೊಳಿಸಿ ಅತ್ಯಂತ ಸಂಬಂಧಿತ ಚಂಕ್‌ಗಳನ್ನು ಹುಡುಕುತ್ತದೆ, ಮತ್ತು ಕೊನೆಯಲ್ಲಿ ಅವುಗಳನ್ನು ಮಾಹಿತಿ ಕಾರಣಿಕವಾಗಿ LLM ಗೆ **ಉತ್ತರ ತಯಾರಿಗೆ** ಪಾಸಾಗಿ ಒದಗಿಸುತ್ತದೆ. ಈ ಕೆಳಗಿನ ವಿಭಾಗಗಳು ಪ್ರತ್ಯೇಕ ಹಂತವನ್ನು ನಡೆಸುವ ಕೋಡ್ ಮತ್ತು ಚಿತ್ರಣಗಳೊಂದಿಗೆ ವಿವರಿಸುತ್ತವೆ. ಮೊದಲು ಹಂತವನ್ನು ನೋಡೋಣ. +ಈ ಮೋಡ್ಯೂಲ್‌ನ RAG ಪೈಪ್‌ಲೈನ್ ನಾಲ್ಕು ಹಂತಗಳಾಗಿ ವಿಂಗಡಿಸಲಾಗಿದೆ, ಪ್ರತಿ ಬಾರಿ ಬಳಕೆದಾರ ಪ್ರಶ್ನೆ ಕೇಳುವಾಗ ಕ್ರಮವಾಗಿ ನಡೆಯುತ್ತದೆ. ಮೊದಲು, ಅಪ್ಲೋಡ್ ಮಾಡಿದ ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು **ಪಾರ್ಸ್ ಮಾಡಲಾಗುತ್ತದೆ ಮತ್ತು ಚುಂಕ್ಗಳಾಗಿ ವಿಭಜಿಸಲಾಗುತ್ತದೆ** — ನಿರ್ವಹಣೀಯ ಭಾಗಗಳು. ಆ ಚುಂಕ್ಗಳನ್ನು ನಂತರ **ವೆಕ್ಟರ್ ಎಂಬೆಡ್ಡಿಂಗ್‌ಗಳಿಗೆ** ಪರಿವರ್ತಿಸಿ ಸಂಗ್ರಹಿಸಲಾಗುತ್ತದೆ, ಅಂದರೆ ಅವುಗೈಯು ವಿವರಣಾತ್ಮಕವಾಗಿ ಹೋಲಿಸಲಾಗುತ್ತದೆ. ಪ್ರಶ್ನೆ ಬಂದಾಗ, ವ್ಯವಸ್ಥೆ ಸಂಬಂಧಿಸಿದ ಚುಂಕ್‌ಗಳನ್ನು ಕಂಡುಹಿಡಿಯಲು **ಅರ್ಥ ಬೋಧಕ ಹುಡುಕಾಟ** ನೆರವನ್ನು ಒದಗಿಸುತ್ತದೆ ಮತ್ತು ಅಂತಿಮವಾಗಿ ಅವುಗಳನ್ನು LLM ಗೆ **ಉತ್ತರ ಉತ್ಪಾದನೆಗೆ** ಸನ್ನಿವೇಶವಾಗಿ ಪಾಸು ಮಾಡುತ್ತದೆ. ಕೆಳಗಿನ ವಿಭಾಗಗಳು ಪ್ರತಿ ಹಂತವನ್ನು ನಿಜವಾದ ಕೋಡ್ ಮತ್ತು ಚಿತ್ರಗಳೊಂದಿಗೆ ವಿವರಿಸುತ್ತವೆ. ಮೊದಲ ಹಂತ ನೋಡೋಣ. ### ಡಾಕ್ಯುಮೆಂಟ್ ಪ್ರಕ್ರಿಯೆ [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -ನೀವು ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ್ಲೋಡ್ ಮಾಡಿದಾಗ, ಸಿಸ್ಟಮ್ ಅದನ್ನು ಪಾರ್ಸ್ ಮಾಡುತ್ತದೆ (PDF ಅಥವಾ ಸಾದಾ ಪಠ್ಯ), ಫೈಲ್ ನಾಮ ಮತ್ತು ಇತರೆ ಮೆಟಾಡೇಟಾವನ್ನು ಲಗತ್ತಿಸುತ್ತದೆ, ನಂತರ ಅದನ್ನು ಚಂಕ್ ಗಳಾಗಿ ವಿಭಜಿಸುತ್ತದೆ — ಚಿಕ್ಕ ತುಂಡುಗಳು, ಹಾಗಾಗಿ ಮಾದರಿಯ ಸಂದರ್ಭ ಕಿಟಕಿಗೆ ಸರಿಯಾಗಿ ಹೊಂದಿಕೊಳ್ಳುತ್ತವೆ. ಈ ಚಂಕ್‌ಗಳಿಂದ ಕೆಲವು ಭಾಗಗಳು ನಿಗದಿ ಮಾಡಲಾಗುತ್ತದೆ ಇದು ಮಾರ್ಜಿನಲ್ಲಿರುವ ಸಂದರ್ಭ ಹಿಡಿದುಕೊಳ್ಳಲು. +ನೀವು ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ್ಲೋಡ್ ಮಾಡಿದಾಗ, ವ್ಯವಸ್ಥೆ ಅದನ್ನು (PDF ಅಥವಾ ಸರಳ ಪಠ್ಯ) ಪಾರ್ಸ್ ಮಾಡುತ್ತದೆ, ಫೈಲ್‌ನಾಮ್ ಮುಂತಾದ ಮೆಟಾಡೇಟಾವನ್ನು ಲಗತ್ತಿಸುತ್ತದೆ, ನಂತರ ಅದನ್ನು ಚುಂಕ್ಗಳಾಗಿ ವಿಭಜಿಸುತ್ತದೆ — ಮಾದರಿಯ ಸನ್ನಿವೇಶ ವಿಂಡೋಗೆ ಸೂಕ್ತವಾಗುವ ಚಿಕ್ಕ ಭಾಗಗಳು. ಈ ಚುಂಕ್‌ಗಳು ಸ್ವಲ್ಪ ತುಡಿಯುತ್ತವೆ, ಹಾಗಾಗಿ ಅಂಚುಗಳಲ್ಲಿ ಸಂಧರ್ಭ ಕಳೆದುಕೊಳ್ಳುವುದಿಲ್ಲ. ```java -// ಅಪ್ಲೋಡ್ ಮಾಡಿದ ಫೈಲ್ ಅನ್ನು ವಿಶ್ಲೇಷಿಸಿ ಮತ್ತು ಅದನ್ನು LangChain4j ಡಾಕ್ಯುಮೆಂಟ್‌ನಲ್ಲಿ ಮೊರೆಹೆಚ್ಚು ಮಾಡಿ +// ಅಪ್ಲೋಡ್ ಮಾಡಲಾದ ಫೈಲನ್ನು ವಿಶ್ಲೇಷಿಸಿ ಮತ್ತು ಅದನ್ನು LangChain4j ಡಾಕ್ಯುಮೆಂಟ್‌ನಲ್ಲಿ ಹಿತಗೊಳಿಸಿ Document document = Document.from(content, metadata); -// 300 ಟೋಕನ್ ತುಂಡುಗಳಾಗಿ ವಿಭಜಿಸಿ 30 ಟೋಕನ್ ಒಪ್ಪಿಗೆಯೊಂದಿಗೆ +// 300-ಟೋಕನ್ ತುಣುಕುಗಳಿಂದ ವಿಭಜಿಸಿ, 30-ಟೋಕನ್ ಸಹಭಾಗಿತ್ವದೊಂದಿಗೆ DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -ಕೆಳಗಿನ ಚಿತ್ರಣದಲ್ಲಿ ಇದನ್ನು ದೃಶ್ಯತಃ ತೋರಿಸಲಾಗಿದೆ. ಪ್ರತಿಯೊಂದು ಚಂಕ್ ತನ್ನ ಬದಿವಾಳಗಳೊಂದಿಗೆ ಕೆಲವು ಟೋಕನ್‌ಗಳನ್ನು ಹಂಚಿಕೊಳ್ಳುತ್ತದೆ — 30-ಟೋಕನ್ ಓವರ್ ಲ್ಯಾಪ್ ಇದರಿಂದ ಯಾವುದೇ ಪ್ರಮುಖ ಸಂದರ್ಭದಲ್ಲಿ ಬಿಂದುಗಳಿಗೆ ಮೊರೆತುಹೋಗುವುದಿಲ್ಲ: +ಕೆಳಗಿನ ಚಿತ್ರವು ಇದನ್ನು ದೃಶ್ಯಮಾನವಾಗಿ ತೋರಿಸುತ್ತದೆ. ಪ್ರತಿ ಚುಂಕ್ ತನ್ನ ಹತ್ತಿರದ ಚುಂಕ್‌ಗಳೊಂದಿಗೆ ಕೆಲವು ಟೋಕನ್‌ಗಳನ್ನು ಹಂಚಿಕೊಳ್ಳುತ್ತದೆ — 30-ಟೋಕನ್ ತುಡಿಯುವಿಕೆ ಯಾವುದೇ ಪ್ರಮುಖ ಸಂಧರ್ಭವು ತಪ್ಪದೇ ಇರುತ್ತದೆ: -ಡಾಕ್ಯುಮೆಂಟ್ ಚಂಕಿಂಗ್ +Document Chunking -*ಈ ಚಿತ್ರಣವು 30-ಟೋಕನ್ ಓವರ್ ಲ್ಯಾಪ್ ಜೊತೆ 300-ಟೋಕನ್ ಚಂಕ್ಗಳಾಗಿ ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು ವಿಭಜಿಸುವುದನ್ನು ತೋರಿಸುತ್ತದೆ, ಚಂಕ್ ಗಡಿಯಾರಗಳಲ್ಲಿ ಸಂದರ್ಭದಲ್ಲಿ ಕಾಪಾಡಿಕೊಳ್ಳುತ್ತದೆ.* +*ಈ ಚಿತ್ರವು ದಸ್ತಾವೇಜನ್ನು 300-ಟೋಕನ್ ಚುಂಕ್‌ಗಳಾಗಿ, 30-ಟೋಕನ್ ತುಡಿಯುವಿಕೆಯಿಂದ ಬಿಚ್ಚುತ್ತದೆ, ಚುಂಕ್ ಅಂಚುಗಳಲ್ಲಿ ಸಂಧರ್ಭ ರಕ್ಷಣೆ ಮಾಡುತ್ತದೆ.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ಚಾಟ್ ಜೊತೆ ಪ್ರಯತ್ನಿಸಿ:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: -> - "LangChain4j ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಚಂಕ್‌ಗಳಲ್ಲಿ ಹೇಗೆ ಹಂಚುತ್ತದೆ ಮತ್ತು ಓವರ್ ಲ್ಯಾಪ್ ಬಹಳ ಮುಖ್ಯವೆಂದು ಯಾಕೆ?" -> - "ಬಗೆಯ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳಿಗೆ ಸೂಕ್ತ ಚಂಕ್ ಗಾತ್ರ ಏನು ಮತ್ತು ಯಾಕೆ?" -> - "ಹೆಚ್ಚು ಭಾಷೆಗಳಲ್ಲಿನ ಅಥವಾ ವಿಶೇಷ ಫಾರ್ಮ್ಯಾಟಿಂಗ್ ಹೊಂದಿರುವ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಹೇಗೆ ನಿರ್ವಹಿಸಲು?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ಚಾಟ್ ಮೂಲಕ ಪ್ರಯತ್ನಿಸಿ:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: +> - "LangChain4j ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಚುಂಕ್‌ಗಳಾಗಿ ಹೇಗೆ ವಿಭಜಿಸುತ್ತದೆ ಮತ್ತು ತುಡಿಯುವಿಕೆ ಏಕೆ ಮುಖ್ಯ?" +> - "ಬಿವಿಧ ಡಾಕ್ಯುಮೆಂಟ್ ಪ್ರಕಾರಗಳಿಗೆ ಯಾವುದು ಉತ್ಕೃಷ್ಟ ಚುಂಕ್ ಗಾತ್ರ ಮತ್ತು ಯಾಕೆ?" +> - "ಬಹುಭಾಷೆ ಅಥವಾ ವಿಶೇಷ ಸ್ವರೂಪಣೆಯ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ನಾನು ಹೇಗೆ ನಿರ್ವಹಿಸಬಹುದು?" -### ಎಂಬೆಡ್ಡಿಂಗ್ ರಚನೆ +### ಎಂಬೆಡ್ಡಿಂಗ್ ಸೃಷ್ಠಿ [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -ಪ್ರತಿಯೋಂದು ಚಂಕ್ ಸಂಖ್ಯಾತದ ಪ್ರತಿನಿಧಿತ್ವಕ್ಕೆ (ಎಂಬೆಡ್ಡಿಂಗ್) ಮಾರ್ಪಡಿಸಲಾಗುತ್ತದೆ — ಅರ್ಥವನ್ನು ಸಂಖ್ಯೆಗಳ ರೂಪದಲ್ಲಿ ಪರಿವರ್ತಿಸುವ ಸಾಧನ. ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿ ಚಾಟ್ ಮಾದರಿ ಇಂಥ 'ಗುಣವಂತಿಕೆ' ಹೊಂದಿರುವುದಿಲ್ಲ; ಇದು ಸೂಚನೆಗಳನ್ನು ಅನುಸರಿಸುವುದಿಲ್ಲ, ತರ್ಕ ಮಾಡುವುದಿಲ್ಲ, ಅಥವಾ ಪ್ರಶ್ನೆಗಳಿಗೆ ಉತ್ತರಿಸುವುದಿಲ್ಲ. ಇದು ಕೇವಲ ಪಠ್ಯವನ್ನು ಗಣಿತೀಯ ಸ್ಥಲಕ್ಕೆ ಮ್ಯಾಪ್ ಮಾಡುತ್ತದೆ, ಅಲ್ಲಿ ಸಾದೃಶ್ಯ ಅರ್ಥವು ಒಂದುರ್ ಪವಾಡಿ ಹತ್ತಿರ ಇರುತ್ತದೆ — ಉದಾ: "ಕಾರು" "ಆಟೋಮೊಬೈಲ್" ಹತ್ತಿರ, "ಹಣ ವಾಪಸ್ ನಿಯಮ" "ನನ್ನ ಹಣ ವಾಪಸ್" ಹತ್ತಿರ. ಚಾಟ್ ಮಾದರಿಯನ್ನು ನೀವು ಮಾತನಾಡಬಹುದಾದ ವ್ಯಕ್ತಿ ಎಂದು ಊಹಿಸಿ; ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿ ಅತ್ಯುತ್ತಮ ದಾಖಲಾತಿ ವ್ಯವಸ್ಥೆಯಂತೆ. +ಪ್ರತಿ ಚುಂಕ್ ಸಂಖ್ಯಾತ್ಮಕ ಪ್ರತಿನಿಧಾನವೊಂದು ಆಗಿ ಪರಿವರ್ತಿಸಲಾಗುತ್ತದೆ, ಅದನ್ನು ಎಂಬೆಡ್ಡಿಂಗ್ ಎಂದು ಕರೆಯಲಾಗುತ್ತದೆ — ಅರ್ಥವನ್ನು ಅಂಕೆಗಳಾಗಿ ಪರಿವರ್ತಿಸುವ ಸಾಧನ. ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿ "ಚಾತುರ್ಯ" ಹೊಂದಿರುವ ಚಾಟ್ ಮಾದರಿಯಂತೆ ಅಲ್ಲ; ಅದು ಸೂಚನೆ ಅನುಸರಿಸಲು, ಯುಕ್ತಿ ಮಾಡುವುದು ಅಥವಾ ಪ್ರಶ್ನೆಗಳಿಗೆ ಉತ್ತರ ನೀಡುವುದು ಸಾಧ್ಯವಿಲ್ಲ. ಆದರೆ ಅದು ಪಠ್ಯವನ್ನು ಗಣಿತೀಯ ಜಾಗದಲ್ಲಿ ನಕ್ಷೆ ಮಾಡುತ್ತದೆ, ಅಲ್ಲಿ ಸಮಾನ ಅರ್ಥಗಳವು ಹತ್ತಿರ ಇರುವವು — "ಕಾರು" ಮತ್ತು "ಆಟೋಮೊಬೈಲ್", "ಧನ ಸರ್ಕಾರ" ಮತ್ತು "ನನ್ನ ಹಣ ಹಿಂತಿರುಗು" ಹತ್ತಿರವೇ ಇರುತ್ತವೆ. ಚಾಟ್ ಮಾದರಿಯನ್ನು ನೀವು ಮಾತನಾಡಬಲ್ಲ ವ್ಯಕ್ತಿಯಾಗಿ ಪರಿಗಣಿಸಿದರೆ, ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿ ಅತ್ಯುತ್ತಮ ದಾಖಲೆ ವ್ಯವಸ್ಥೆಯಂತೆಯೇ. -ಕೆಳಗಿನ ಚಿತ್ರಣ ಈ ಕಲ್ಪನೆಯನ್ನು ದೃಶ್ಯಮಾಡುತ್ತದೆ — ಪಠ್ಯ ಒಳಗೆ ಹೋಗುತ್ತದೆ, ಸಂಖ್ಯಾತ ವಕ್ಟರ್ ಬರುವುದೋ, ಸಮಾನ ಅರ್ಥಗಳವು ಹತ್ತಿರ ನೆಲೆ ಮಾಡುತ್ತವೆ: +ಕೆಳಗಿನ ಚಿತ್ರವು ಈ ತತ್ತ್ವವನ್ನು ದೃಶ್ಯರೂಪದಲ್ಲಿ ತೋರಿಸುತ್ತದೆ — ಪಠ್ಯ ಒಳಗೆ ಹೋಗುತ್ತದೆ, ಸಂಖ್ಯಾತ್ಮಕ ವೆಕ್ಟರ್‌ಗಳು ಹೊರಗೆ ಬರುತ್ತವೆ, ಮತ್ತು ಸಮಾನ ಅರ್ಥಗಳು ಹತ್ತಿರ ಇರುವ ವೆಕ್ಟರ್‌ಗಳನ್ನು ಉತ್ಪಾದಿಸುತ್ತವೆ: -ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿ ಕಲ್ಪನೆ +Embedding Model Concept -*ಈ ಚಿತ್ರಣವು ಪಠ್ಯವನ್ನು ಸಂಖ್ಯಾತ ವಕ್ಟರ್ಗಳಾಗಿ ಪರಿವರ್ತಿಸುವ ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿಯನ್ನು ತೋರಿಸುತ್ತದೆ, ಸಮಾನ ಅರ್ಥಗಳು (ಉದಾಹರಣೆಗೆ "ಕಾರು" ಮತ್ತು "ಆಟೋಮೊಬೈಲ್") ವಕ್ಟರ್ ಸ್ಥಳದಲ್ಲಿ ಹತ್ತಿರ ಇರುತ್ತವೆ.* +*ಈ ಚಿತ್ರವು ಎಂಬೆಡ್ಡಿಂಗ್ ಮಾದರಿ ಪಠ್ಯವನ್ನು ಸಂಖ್ಯಾತ್ಮಕ ವೆಕ್ಟರ್‌ಗಳಾಗಿ ಪರಿವರ್ತಿಸುವ ವಿಧಾನವನ್ನು, ಮತ್ತು ಸಮಾನ ಅರ್ಥಗಳಂತೆ "ಕಾರು" ಮತ್ತು "ಆಟೋಮೊಬೈಲ್" ಹತ್ತಿರ ಇಟ್ಟುಕೊಳ್ಳುತ್ತದೆ ಎಂದು ತೋರಿಸುತ್ತದೆ.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -ಕೆಳಗಿನ ವರ್ಗ ಚಿತ್ರವು RAG ಪೈಪ್ಲೈನ್‍ನಲ್ಲಿ ಎರಡು ಪ್ರತ್ಯೇಕ ಪ್ರವಾಹಗಳನ್ನು ಮತ್ತು ಅವುಗಳನ್ನು ಅನುಷ್ಠಾನಗೊಳಿಸುವ LangChain4j ವರ್ಗಗಳನ್ನು ತೋರಿಸುತ್ತದೆ. **ಅವಲೋಕನ ಪ್ರವಾಹ** (ಒಮ್ಮೆ ಅಪ್ಲೋಡ್ ಸಮಯದಲ್ಲಿ ನಡೆಯುತ್ತದೆ) ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು ವಿಭಜಿಸಿ, ಚಂಕ್ ಗಳನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡಿ, ಮತ್ತು ಅವುಗಳನ್ನು `.addAll()` ಮೂಲಕ ಸಂಗ್ರಹಿಸುತ್ತದೆ. **ಪ್ರಶ್ನೆ ಪ್ರವಾಹ** (ಪ್ರತಿ ಬಾರಿ ಬಳಕೆದಾರನು ಕೇಳುವಾಗ) ಪ್ರಶ್ನೆಯನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡಿ, `.search()` ಮೂಲಕ ಸಂಗ್ರಹವನ್ನು ಹುಡುಕುತ್ತದೆ, ಮತ್ತು ಹೊಂದಿದ ಸಂದರ್ಭವನ್ನು ಚಾಟ್ ಮಾದರಿಗೆ ಒದಗಿಸುತ್ತದೆ. ಎರಡೂ ಪ್ರವಾಹಗಳು ಹಂಚಲಾದ `EmbeddingStore` ಇಂಟರ್‌ಫೇಸ್ನಲ್ಲಿ ಸೇರಿಕೊಳ್ಳುತ್ತವೆ: +ಕೆಳಗಿನ ವರ್ಗ ಚಿತ್ರವು RAG ಪೈಪ್‌ಲೈನ್‌ನ ಎರಡು ಪ್ರತ್ಯೇಕ ಹರಿವನ್ನು ಮತ್ತು LangChain4j ವರ್ಗಗಳನ್ನು ತೋರಿಸುತ್ತದೆ. **ಇಂಗೆಷನ್ ಹರಿವು** (ಅಪ್ಲೋಡ್ ಸಮಯದಲ್ಲಿ ಒಂದೇ ಬಾರಿ ನಡೆಯುವದು) ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು ವಿಭಜಿಸಿ ಚುಂಕ್‌ಗಳನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡಿ, ನಂತರ `.addAll()` ಮೂಲಕ ಸಂಗ್ರಹಿಸುತ್ತದೆ. **ಪ್ರಶ್ನೆ ಹರಿವು** (ಬಳಕೆದಾರರು ಪ್ರತಿಸುವಾಗ ಪ್ರತಿಯೊಮ್ಮೆ ನಡೆಯುವದು) ಪ್ರಶ್ನೆಯನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡಿ, `.search()` ಮೂಲಕ ಹುಡುಕಿ, ಹೊಂದಿದ ಸಂಧರ್ಭವನ್ನು ಚಾಟ್ ಮಾದರಿಗೆ ಪಾಸು ಮಾಡುತ್ತದೆ. ಎರಡೂ ಹರಿವುಗಳು ಹಂಚಿಕೊಳ್ಳುವ `EmbeddingStore` ಇಂಟರ್‌ಫೇಸ್‌ನಲ್ಲಿ ಸೇರುತ್ತವೆ: -LangChain4j RAG ವರ್ಗಗಳು +LangChain4j RAG Classes -*ಈ ಚಿತ್ರಣವು RAG ಪೈಪ್ಲೈನಿನ ಎರಡು ಪ್ರವಾಹಗಳನ್ನು — ಅವಲೋಕನ ಮತ್ತು ಪ್ರಶ್ನೆ — ಮತ್ತು ಅವು ಹೇಗೆ ಹಂಚಲ್ಪಟ್ಟ EmbeddingStore ಮೂಲಕ ಸಂಪರ್ಕ ಹೊಂದಿರುವುದನ್ನು ತೋರಿಸುತ್ತದೆ.* +*ಈ ಚಿತ್ರವು RAG ಪೈಪ್‌ಲೈನ್‌ನ ಎರಡು ಹರಿವುಗಳನ್ನು ತೋರಿಸುತ್ತದೆ — ಇಂಗೆಷನ್ ಮತ್ತು ಪ್ರಶ್ನೆ — ಮತ್ತು ಅವು ಹಂಚಿಕೊಳ್ಳುವ EmbeddingStore ಮೂಲಕ ಸಂಪರ್ಕ ಹೊಂದಿವೆ.* -ಎಂಬೆಡ್ಡಿಂಗ್‌ಗಳು ಸಂಗ್ರಹವಾದ ಮೇಲೆ, ಸಂಬಂಧಿತ ವಿಷಯವು ಸಹಜವಾಗಿ ವಕ್ಟರ್ ಸ್ಥಳದಲ್ಲಿ ಗುಚ್ಛಗೆ ಸೇರಿಕೊಳ್ಳುತ್ತದೆ. ಕೆಳಗಿನ ದೃಶ್ಯವು ಸಂಬಂಧಿತ ವಿಷಯಗಳೊಡನೆ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳು ಹತ್ತಿರದ ಬಿಂದುಗಳಾಗಿ ಹೇಗೆ ನೆಲೆ ಮಾಡುತ್ತವೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ, ಇದು ಅರ್ಥಪೂರ್ಣ ಶೋಧನೆಯನ್ನು ಸಾಧ್ಯ ಮಾಡುತ್ತದೆ: +ಒಮ್ಮೆ ಎಂಬೆಡ್ಡಿಂಗ್‌ಗಳನ್ನು ಸಂಗ್ರಹಿಸಿದರೆ, ಸಮಾನ ವಿಷಯಗಳು ಸ್ವಾಭಾವಿಕವಾಗಿ ವೆಕ್ಟರ್ ಜಾಗದಲ್ಲಿ ಗುಂಪು ಬದ್ಧವಾಗುತ್ತವೆ. ಕೆಳಗಿನ ದೃಶ್ಯದಲ್ಲಿ ಸಂಬಂಧಪಟ್ಟ ವಿಷಯಗಳ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳು ಹತ್ತಿರದ ಬಿಂದುಗಳಾಗಿ ಕಾಣುತ್ತಿರುವುದು, ಇದು ಅರ್ಥಬೋಧಕ ಹುಡುಕಾಟದ ಸಾಧ್ಯತೆಯನ್ನು ಸೃಷ್ಟಿಸುತ್ತದೆ: -ವಕ್ಟರ್ ಎಂಬೆಡ್ಡಿಂಗ್ ಸ್ಥಳ +Vector Embeddings Space -*ಈ ದೃಶ್ಯವು ತಾಂತ್ರಿಕ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳು, ವ್ಯವಹಾರ ನಿಯಮಗಳು, ಮತ್ತು FAQ ಸೇರಿದಂತೆ ವಿಷಯಗಳಾದವರು 3D ವಕ್ಟರ್ ಸ್ಥಳದಲ್ಲಿ ಹೇಗೆ ವಿಭಜಿತ ಗುಂಪುಗಳಾಗಿ ಸೇರುತ್ತವೆ ಎಂದು ತೋರಿಸುತ್ತದೆ.* +*ಈ ದೃಶ್ಯವು ತಾಂತ್ರಿಕ ಡಾಕ್ಸ್, ವ್ಯವಹಾರ ನಿಯಮಗಳು ಮತ್ತು FAQs ಮುಂತಾದ ವಿಷಯಗಳೊಂದಿಗೆ ಸಂಬಂಧಿಸಿದ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳು 3D ವೆಕ್ಟರ್ ಜಾಗದಲ್ಲಿ ಗುಂಪು ಬದ್ಧವಾಗಿರುವುದನ್ನು ತೋರಿಸುತ್ತದೆ.* -ಬಳಕೆದಾರನು ಹುಡುಕಲು ಹೋದಾಗ, ಸಿಸ್ಟಮ್ ನಾಲ್ಕು ಹಂತಗಳನ್ನು ಅನುಸರಿಸುತ್ತದೆ: ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು ಒಂದು ಬಾರಿ ಎಂಬೆಡ್ಡ್ ಮಾಡಿ, ಪ್ರತಿ ಹುಡುಕಾಟಕ್ಕೆ ಪ್ರಶ್ನೆಯನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡಿ, ಪ್ರಶ್ನೆ ವಕ್ಟರ್ ಅನ್ನು ಎಲ್ಲಾ ಸಂಗ್ರಹಿತ ವಕ್ಟರ್‌ಗಳೊಂದಿಗೆ ಕಾಸೈನ್ ಸಾದೃಶ್ಯತೆ ಬಳಸಿ ಹೋಲಿಸಿ, ಮತ್ತು ಅತ್ಯುತ್ತಮ ತಲಾ-K ಅಂಕೆ ಪಡೆದ ಚಂಕ್‌ಗಳನ್ನು ಹಿಂತಿರುಗಿಸುತ್ತದೆ. ಕೆಳಗಿನ ಚಿತ್ರಣದಲ್ಲಿ ಪ್ರತಿ ಹಂತ ಮತ್ತು LangChain4j ವರ್ಗಗಳು ವಿವರಿಸಲಾಗಿದೆ: +ಬಳಕೆದಾರರು ಹುಡುಕುವಾಗ, ವ್ಯವಸ್ಥೆ ನಾಲ್ಕು ಹಂತಗಳನ್ನು ಅನುಸರಿಸುತ್ತದೆ: ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಒಂದು ಬಾರಿ ಎಂಬೆಡ್ಡ್ ಮಾಡುವುದು, ಹುಡುಕಾಟದಲ್ಲಿ ಪ್ರಶ್ನೆಯನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡುವುದು, ಪ್ರಶ್ನೆಯ ವೆಕ್ಟರ್ ಅನ್ನು ಎಲ್ಲಾ ಸಂಗ್ರಹಿತ ವೆಕ್ಟರ್‌ಗಳೊಂದಿಗೆ ಕೋಸೈನ್ ಒತ್ತಿಣಿಕೆ ಬಳಸಿ ಹೋಲಿಸುದು, ಮತ್ತು ಶೀರ್ಷಿಕೆ K ಅತ್ಯುಚ್ಛ ಅಂಕಗಳ ಚುಂಕ್‌ಗಳನ್ನು ಹಿಂತಿರುಗಿಸುವದು. ಕೆಳಗಿನ ಚಿತ್ರವು ಪ್ರತಿ ಹಂತವನ್ನು ಹಾಗೂ LangChain4j ವರ್ಗಗಳನ್ನು ವಿವರಿಸುತ್ತದೆ: -ಎಂಬೆಡ್ಡಿಂಗ್ ಶೋಧನ ಹಂತಗಳು +Embedding Search Steps -*ಈ ಚಿತ್ರಣವು ನಾಲ್ಕು ಹಂತಗಳಿರುವ ಎಂಬೆಡ್ಡಿಂಗ್ ಶೋಧನಾ ಪ್ರಕ್ರಿಯೆಯನ್ನು ತೋರಿಸುತ್ತದೆ: ಡಾಕ್ಯುಮೆಂಟ್ ಗಳನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡುವುದು, ಶೋಧನಿಗೆ ಪ್ರಶ್ನೆಯನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡುವುದು, ವಕ್ಟರ್‌ಗಳನ್ನ ಕಾಸೈನ್ ಸಾದೃಶ್ಯತೆ ಮೂಲಕ ಹೋಲಿಸಿ, ಮತ್ತು ಶ್ರೇಷ್ಠ-K ಫಲಿತಾಂಶಗಳನ್ನು ಹಿಂತಿರುಗಿಸುವುದು.* +*ಈ ಚಿತ್ರವು ನಾಲ್ಕು ಹಂತಗಳ ಎಂಬೆಡ್ಡಿಂಗ್ ಹುಡುಕಾಟ ಪ್ರಕ್ರಿಯೆಯನ್ನು ತೋರಿಸುತ್ತದೆ: ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡುವುದು, ಪ್ರಶ್ನೆಯನ್ನು ಎಂಬೆಡ್ಡ್ ಮಾಡುವುದು, ಕೋಸೈನ್ ಸಾಮ್ಯತೆ ಮೂಲಕ ವೆಕ್ಟರ್‌ಗಳನ್ನು ಹೋಲಿಸುವುದು, ಮತ್ತು ಶ್ರೇಷ್ಟ K ಫಲಿತಾಂಶಗಳನ್ನು ಹಿಂತಿರುಗಿಸುವುದು.* -### ಅರ್ಥಪೂರ್ಣ ಶೋಧನೆ +### ಅರ್ಥಬೋಧಕ ಹುಡುಕಾಟ [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -ನೀವು ಪ್ರಶ್ನೆ ಕೇಳಿದಾಗ, ನೀವು ಕೇಳಿದ ಪ್ರಶ್ನೆಯೂ ಎಂಬೆಡ್ಡಿಂಗ್ ಆಗುತ್ತದೆ. ಸಿಸ್ಟಮ್ ನಿಮ್ಮ ಪ್ರಶ್ನೆಯ ಎಂಬೆಡ್ಡಿಂಗ್ ಅನ್ನು ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳ ಪ್ರತಿಯೊಂದು ಚಂಕ್ ಎಂಬೆಡ್ಡಿಂಗ್‌ಗಳೊಂದಿಗೆ ಹೋಲಿಸುತ್ತದೆ. ಇದು ಅರ್ಥದಲ್ಲಿ ಸಮಾನವಾದ ಚಂಕ್‌ಗಳನ್ನು ಹುಡುಕುತ್ತದೆ - ಕೀವರ್ಡ್‌ಗಳು ಮಾತ್ರ ಅಲ್ಲ, ನಿಖರಾರ್ಥ ಸಾದೃಶ್ಯತೆ ಕೂಡ. +ನೀವು ಪ್ರಶ್ನೆ ಕೇಳಿದಾಗ, ನಿಮ್ಮ ಪ್ರಶ್ನೆಯು ಕೂಡ ಒಂದು ಎಂಬೆಡ್ಡಿಂಗ್ ಆಗುತ್ತದೆ. ವ್ಯವಸ್ಥೆ ನಿಮ್ಮ ಪ್ರಶ್ನೆಯ ಎಂಬೆಡ್ಡಿಂಗ್ ಅನ್ನು ಎಲ್ಲಾ ಡಾಕ್ಯುಮೆಂಟ್ ಚುಂಕ್ ಎಂಬೆಡ್ಡಿಂಗ್‌ಗಳ ಎದುರಾಗಿ ಹೋಲಿಸುತ್ತದೆ. ಅದು ಅರ್ಥದಲ್ಲಿ ಸಮಾನವಾದ ಚುಂಕ್‌ಗಳನ್ನು ಹುಡುಕುತ್ತದೆ - ಕೀವರ್ಡ್ ನುಡಿಗಳು ಮಾತ್ರವಲ್ಲ, ಸಂಪೂರ್ಣ ಅರ್ಥಸಮಾನತೆಯ ಮೇಲೆ. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -ಕೆಳಗಿನ ಚಿತ್ರಣವು ಕೀವರ್ಡ್ ಶೋಧನೆ ಮತ್ತು ಅರ್ಥಪೂರ್ಣ ಶೋಧನೆಯ ನಡುವೆ ವಿರುದ್ಧತೆ ತೋರಿಸುತ್ತದೆ. "ವಾಹನ" ಎಂಬ ಕೀವರ್ಡ್ ಹುಡುಕಾಟವು "ಕಾರುಗಳು ಮತ್ತು ಟ್ರಕ್‌ಗಳು" ಎಂಬ ಚಂಕ್ ಅನ್ನು ತಪ್ಪಿಸಿಬಿಡುತ್ತದೆ, ಆದರೆ ಅರ್ಥಪೂರ್ಣ ಶೋಧನೆ ಅರ್ಥವನ್ನು ಸರಿಯಾಗಿ ಗ್ರಹಿಸಿ ಅದನ್ನು ಉತ್ತಮ ಅಂಕೆ ಪಡೆಯುವ ಮುಖಾಂತರ ಹಿಂತಿರುಗಿಸುತ್ತದೆ: +ಕೆಳಗಿನ ಚಿತ್ರವು ಅರ್ಥಬೋಧಕ ಹುಡುಕಾಟವನ್ನು ಶ್ರೇಣಿಪದ ನೇಹಸಿ-ಹುಡುಕಾಟದೊಂದಿಗೆ ಹೋಲಿಸುತ್ತದೆ. "ವಾಹನ" ಒ关键词 ಹುಡುಕಾಟವು "ಕಾರ್ ಮತ್ತು ಟ್ರಕ್" ಬಗ್ಗೆ ಒಂದು ಚುಂಕ್ ತಪ್ಪಿಸುತ್ತದೆ, ಆದರೆ ಅರ್ಥಬೋಧಕ ಹುಡುಕಾಟ ಅವು ಸಮಾನವೆಂದು ಅರಿತು ಅದನ್ನು ಉತ್ತಮ ಆಂಕೆಯೊಂದಿಗೆ ವಿಷಯವಾಗಿ ಕರೆಸಿಕೊಳ್ಳುತ್ತದೆ: -ಅರ್ಥಪೂರ್ಣ ಶೋಧನೆ +Semantic Search -*ಈ ಚಿತ್ರಣವು ಕೀವರ್ಡ್ ಆಧಾರಿತ ಶೋಧನೆ ಮತ್ತು ಅರ್ಥಪೂರ್ಣ ಶೋಧನೆಯ ನಡುವಿನ ವ್ಯತ್ಯಾಸವನ್ನು ತೋರಿಸುತ್ತದೆ, ಸಮಾನಾರ್ಥದ ವಿಷಯಗಳನ್ನು ಮರಳುಕಂಪದ ಭಾಗಗಳಂತೆ ವಿವಿಧ ಶಬ್ದಗಳಿದ್ದರೂ ಕೂಡ ಅರಿತು ಹಿಂತಿರುಗಿಸುವುದನ್ನು.* -ಹುಡಿನಲ್ಲಿ, ಸಾದೃಶ್ಯವನ್ನು ಕೋಸೈನ್ ಸಾದೃಶ್ಯ ಬಳಸಿ ಅಳೆಯಲಾಗುತ್ತದೆ — ಮೂಲತಃ "ಈ ಎರಡು ಬಾಣಗಳು ಒಂದೇ ದಿಕ್ಕಿನಲ್ಲಿ ಸೂಚಿಸುತ್ತಿವೆಯೇ?" ಎಂದು ಕೇಳುವುದು. ಎರಡು ಚಂಕುಗಳು ಸಂಪೂರ್ಣವಾಗಿ ಬೇರೆಯಾದ ಪದಗಳನ್ನು ಬಳಸಬಹುದು, ಆದರೆ ಅವುಗಳ ಅರ್ಥ ಒಂದೇ ಆಗಿದ್ದರೆ ಅವುಗಳ ವೆಕ್ಟರ್‌ಗಳು ಅದೇ ದಿಕ್ಕಿನಲ್ಲಿ ಇರಿಸಿ ಸ್ಕೋರ್ 1.0ಕ್ಕೆ ಹತ್ತಿರವಾಗಿರುತ್ತವೆ: +*ಈ ಚಿತ್ರವು ಕೀವರ್ಡ್ ಆಧಾರಿತ ಹುಡುಕಾಟ ಮತ್ತು ಅರ್ಥಬೋಧಕ ಹುಡುಕಾಟವನ್ನು ಹೋಲಿಸುತ್ತದೆ, ಅರ್ಥಬೋಧಕ ಹುಡುಕಾಟವು ನಿಖರ ಕೀವರ್ಡ್ ಬೇಧವು ಇರುವಾಗಲೂ ತತ್ವಪೂರ್ಣವಾಗಿ ಸಂಬಂಧಿಸಿದ ವಿಷಯವನ್ನು ಪಡೆಯುತ್ತದೆ ಎಂದು ತೋರಿಸುತ್ತದೆ.* -ಕೋಸೈನ್ ಸಾದృಶ್ಯ +ಕೆಳಮನೆ, ಸಾಮ್ಯತೆಯನ್ನು ಕೋಸೈನ್ ಸಮಾನತೆ ಮೂಲಕ ಅಳೆಯಲಾಗುತ್ತದೆ — ಅಂದರೆ "ಈ ಎರಡು ಬಾಣಗಳು ಒಂದೇ ದಿಕ್ಕಿನಲ್ಲಿ ಸೂಚಿಸುತ್ತಿವೆಯಾ?" ಎಂದು ಪ್ರಶ್ನಿಸುವಂತೆ. ಎರಡು ಚುಂಕ್ಗಳು ಸಂಪೂರ್ಣ ವಿಭಿನ್ನ ಪದಗಳನ್ನು ಬಳಸಬಹುದು, ಆದರೆ ಅವು ಒಂದೇ ಅರ್ಥ ಹೊಂದಿದ್ದರೆ ಅವುಗಳ ವೆಕ್ಟರ್‌ಗಳು ಒಂದೇ ದಿಕ್ಕಿನಲ್ಲಿ ನಿಲುಕುತ್ತವೆ ಮತ್ತು 1.0 ಕ್ಕೂ ಸಮೀಪ ಅಂಕೆಯನ್ನು ಪಡೆಯುತ್ತವೆ: -*ಈ ಚಿತ್ರಣವು ಕಾಸೈನ್ ಸಾದೃಶ್ಯವನ್ನು ಎಮ್ಬೆಡ್ಡಿಂಗ್ ವೆಕ್ಟರ್‌ಗಳ ನಡುವಿನ ಕೋನವಾಗಿ ವಿವರಿಸುತ್ತದೆ — ಹೆಚ್ಚು ಸರಿಹೊಂದಿದ ವೆಕ್ಟರ್‌ಗಳು 1.0ಕ್ಕೆ ಹತ್ತಿರ ಸ್ಕೋರ್ ನೀಡುತ್ತವೆ, ಇದು ಹೆಚ್ಚಿನ ಅರ್ಥಾತ್ಮಕ ಸಾದೃಶ್ಯವನ್ನು ಸೂಚಿಸುತ್ತದೆ.* +Cosine Similarity +*ಈ ರೇಖಾಚಿತ್ರವು ಆಂಬೆಡ್ಡಿಂಗ್ ವೆಕ್ಟರ್‌ಗಳ ಮಧ್ಯದಲ್ಲಿನ ಕೋಸೈನ್ ಸಮಾನತೆಯನ್ನು ಕೋನವಾಗಿ ತೋರಿಸುತ್ತದೆ — ಹೆಚ್ಚು ಅನುರಂಜಿತ ವೆಕ್ಟರ್‌ಗಳು 1.0 ಗೆ ಹತ್ತಿರದ ಅಂಕೆಯನ್ನು ಪಡೆಯುತ್ತವೆ, ಇದು ಹೆಚ್ಚು ಅರ್ಥಪೂರ್ಣ ಸಮಾನತೆಯನ್ನು ಸೂಚಿಸುತ್ತದೆ.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ಚಾಟ್ ಜೊತೆಗೆ ಪ್ರಯತ್ನಿಸಿ:** ತೆರೆಯಿರಿ [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ಮತ್ತು ಕೇಳಿ: -> - "ಎಂಬೆಡ್ಡಿಂಗ್‌ಗಳೊಂದಿಗೆ ಸಾದೃಶ್ಯ ಹುಡುಕಾಟ ಹೇಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ ಮತ್ತು ಸ್ಕೋರ್ ಅನ್ನು ಏನು ನಿರ್ಧರಿಸುತ್ತದೆ?" -> - "ಎಷ್ಟು ಸಾದೃಶ್ಯದ ಗಡಿ ಬಳಸಬೇಕು ಮತ್ತು ಅದು ಫಲಿತಾಂಶಗಳಿಗೆ ಹೇಗೆ ಪ್ರಭಾವ ಬೀರುತ್ತದೆ?" -> - "ಸಂಬಂಧಿತ ದಾಖಲೆಗಳು ದೊರೆಯದ ಸಂದರ್ಭದಲ್ಲಿ ನಾನು ಹೇಗೆ ನಿರ್ವಹಿಸಬೇಕು?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ಚಾಟ್‌ನೊಂದಿಗೆ ಪ್ರಯತ್ನಿಸಿ:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ಅನ್ನು ತೆರೆಯಿರಿ ಮತ್ತು ಕೇಳಿ: +> - "ಆಂಬೆಡ್ಡಿಂಗ್‌ಗಳೊಂದಿಗೆ ಸಮಾನತೆ ಹುಡುಕಾಟ ಹೇಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ ಮತ್ತು ಅಂಕೆಯನ್ನು ಏನು ನಿರ್ಣಯಿಸುತ್ತದೆ?" +> - "ಯಾವ ಸಮಾನತೆ ತಟಸ್ಥತೆ ನಾನು ಬಳಸಬೇಕು ಮತ್ತು ಅದು ಫಲಿತಾಂಶಗಳಿಗೆ ಹೇಗೆ ಪ್ರಭಾವ ಬೀರುವದು?" +> - "ಯಾವುದೇ ಸಂಬಂಧಿಸಿದ ದಾಖಲೆಗಳು ಕಂಡುಬರುವಿಲ್ಲದ ಸಂದರ್ಭಗಳಲ್ಲಿ ನಾನು ಹೇಗೆ ಕೈಗಾರಿಕೆಗೆ ಬರುವುದು?" -### ಉತ್ತರ ಉತ್ಪಾದನೆ +### ಉತ್ತರ ರಚನೆ [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -ಅತ್ಯಂತ ಸಂಬಂಧಿತ ಚಂಕುಗಳನ್ನು ಗಟ್ಟಿಯಾದ ನಿರ্দেশನೆಗಳು, ತರಿಸಿಕೊಂಡ ಪೃಥ್ವಿ ಮತ್ತು ಬಳಕೆದಾರನ ಪ್ರಶ್ನೆಯನ್ನು ಒಳಗೊಂಡು ಸಂರಚಿತ ಪ್ರಾಂಪ್ಟಿನಲ್ಲಿ ಸಂಯೋಜಿಸಲಾಗುತ್ತದೆ. ಮಾದರಿ ಆ ನಿರ್ದಿಷ್ಟ ಚಂಕುಗಳನ್ನು ಓದಿ ಆ ಮಾಹಿತಿ ಆಧಾರಿತವಾಗಿ ಉತ್ತರಿಸುತ್ತದೆ — ಅದು ಮುಂದೆ ಇರುವ ದತ್ತಾಂಶವನ್ನು ಮಾತ್ರ ಬಳಸಬಹುದು, ಇದು ಕಲ್ಪನೆ ತಪ್ಪುವಲ್ಲಿ ತಡೆ ನೀಡುತ್ತದೆ. +ಅತ್ಯಂತ ಸಂಬಂಧಿಸಿದ ತುಣುಕುಗಳನ್ನು ಒಂದು ಸಂರಚಿತ ಪ್ರಾಂಪ್ಟ್‌ನಲ್ಲಿ ಜೋಡಿಸಲಾಗುತ್ತದೆ, ಇದರಲ್ಲಿ ಸ್ಪಷ್ಟ ಸೂಚನೆಗಳು, ಪಡೆದುಕೊಂಡ ಸಂಧರ್ಭ ಮತ್ತು ಬಳಕೆದಾರರ ಪ್ರಶ್ನೆ ಸೇರಿರುತ್ತವೆ. ಮಾದರಿ ಆ ತುಣುಕುಗಳನ್ನು ಓದುತ್ತದೆ ಮತ್ತು ಆ ಮಾಹಿತಿಯ ಆಧಾರದಲ್ಲಿ ಉತ್ತರ ನೀಡುತ್ತದೆ — ಅದು ಎದುರುನಿದ್ದವಷ್ಟೇ ಬಳಸಲು ಸಾಧ್ಯ, ಹಾಳು ಕಲ್ಪನೆಗಳನ್ನು ತಡೆಗಟ್ಟುತ್ತದೆ. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -ಕೆಳಗಿನ ಚಿತ್ರಣವು ಈ ಸಂಯೋಜನೆಯನ್ನು ಕ್ರಿಯಾಶೀಲವಾಗಿ ತೋರಿಸುತ್ತದೆ — ಹುಡುಕಾಟ ಹಂತದಿಂದ ಟಾಪ್-ಸ್ಕೋರ್ ಮಾಡಿದ ಚಂಕುಗಳನ್ನು ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟಿಗೆ ಬಳಸಲಾಗುತ್ತದೆ, ಮತ್ತು `OpenAiOfficialChatModel` ಆಧಾರದ ಮೇಲಿನ ಉತ್ತರವನ್ನು ರಚಿಸುತ್ತದೆ: +ಕೆಳಗಿನ ರೇಖಾಚಿತ್ರವು ಈ ಸಂಯೋಜನೆಯನ್ನು ಪ್ರದರ್ಶಿಸುತ್ತದೆ — ಹುಡುಕಾಟ ಹಂತದ ಮೇಲ್ಪಡೆ ಸಂದರ್ಶನಗಳು ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್‌ನಲ್ಲಿ ಪೊರೆಸಲಾಗಿ, `OpenAiOfficialChatModel` ನೆಲಬದ್ಧ ಮಾಹಿತಿ ಜೊತೆಗೆ ಉತ್ತರವನ್ನು ತಯಾರಿಸುತ್ತದೆ: -ಪೃಥ್ವಿ ಸಂಯೋಜನೆ +Context Assembly -*ಈ ಚಿತ್ರಣವು ಟಾಪ್-ಸ್ಕೋರ್ ಮಾಡಿದ ಚಂಕುಗಳನ್ನು ಸಂಯೋಜಿತ ಪ್ರಾಂಪ್ಟ್ ಗೆ ಹೇಗೆ ಸೇರಿಸಲಾಗುತ್ತದೆ ಎಂದು ತೋರಿಸುತ್ತದೆ, ಇದರಿಂದ ಮಾದರಿಗೆ ನಿಮ್ಮ ಡೇಟಾದಿಂದ ಗಟ್ಟಿಯಾದ ಉತ್ತರ ಸೃಷ್ಟಿ ಸಾಧ್ಯವಾಗುತ್ತದೆ.* +*ಈ ರೇಖಾಚಿತ್ರವು ಪ್ರಾಂಪ್ಟ್‌ಗೆ ಮೇಲ್ಪಡೆ ಸಂದರ್ಶನಗಳು ಸಂಯೋಜಿಸುವ ವಿಧಾನವನ್ನು ತೋರಿಸುತ್ತದೆ, ಇದರಿಂದ ಮಾದರಿ ನಿಮ್ಮ ಡೇಟಾದಿಂದ ನೆಲಬದ್ಧ ಉತ್ತರವನ್ನು ತಯಾರಿಸಲು ಸಾಧ್ಯವಾಗುತ್ತದೆ.* ## ಅಪ್ಲಿಕೇಶನ್ ಚಾಲನೆ -**ಪ್ರತಿಷ್ಠಾಪನೆ ಪರಿಶೀಲಿಸಿ:** +**ನಿಯೋಜನ ಪರಿಶೀಲನೆ:** -ಮೂಲ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ `.env` ಕಡತವಾದು ಅಜುರ್ ಕ್ರೆಡೆನ್ಶಿಯಲ್ಸ್ ಜೊತೆಗೆ ಇರುತ್ತದೆ (ಮಾಡ್ಯೂಲ್ 01 ರ ಸಮಯದಲ್ಲಿ ರಚಿಸಲಾಗಿತ್ತು). ಇದನ್ನು ಮಾಡ್ಯೂಲ್ ಡೈರೆಕ್ಟರಿಯಿಂದ (`03-rag/`) ಚಾಲನೆ ಮಾಡಿ: +ಮೂಲ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ `.env` ಫೈಲ್ ಅಸ್ತಿತ್ವದಲ್ಲಿದೆ ಎಂದು ಖಚಿತಪಡಿಸಿಕೊಳ್ಳಿ, ಅಲ್ಲಿ ಆಯೋಜನಾ 01 ರಲ್ಲಿ ಸೃಷ್ಟಿಸಲಾದ ಅಜೂರ್ ದೃಢೀಕರಣಗಳಿವೆ. ಈ ಮODULE ಡೈರೆಕ್ಟರಿಯಿಂದ (`03-rag/`) ಇದನ್ನು ಚಾಲನೆಮಾಡಿ: **Bash:** ```bash @@ -256,46 +255,46 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ಅನ್ನು ತೋ **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ಅನ್ನು ತೋರಿಸಬೇಕು +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ತೋರಿಸಬೇಕು ``` **ಅಪ್ಲಿಕೇಶನ್ ಪ್ರಾರಂಭಿಸಿ:** -> **ಗಮನಿಸಿ:** ನಿಮ್ಮು ಮೂಲ ಡೈರೆಕ್ಟರಿಯಿಂದ `./start-all.sh` ಬಳಸಿ ಎಲ್ಲಾ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಈಗಾಗಲೇ ಪ್ರಾರಂಭಿಸಿದ್ದರೆ (ಮಾಡ್ಯೂಲ್ 01 ಅನುಸಾರ), ಈ ಮಾಡ್ಯೂಲ್ ಈಗಾಗಲೆ 8081 ಪೋರ್ಟ್‌ನಲ್ಲಿ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತಿದೆ. ಕೆಳಗಿನ ಪ್ರಾರಂಭ ಆಜ್ಞೆಗಳನ್ನು ನೀವು ಬಿಟ್ಟುಬಿಡಬಹುದು ಮತ್ತು ನೇರವಾಗಿ http://localhost:8081 ಗೆ ಹೋಗಬಹುದು. +> **ಗಮನಿಸಿ:** ನೀವು ಎಲ್ಲಾ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಒಂದೇ ಬಾರಿ ಮೂಲ ಡೈರೆಕ್ಟರಿಯಿಂದ `./start-all.sh` ಮೂಲಕ ಪ್ರಾರಂಭಿಸಿದ್ದರೆ (ಅನುವಾಗಿ Module 01 ನಲ್ಲಿ ವಿವರಣೆ ನೀಡಲಾಗಿದೆ), ಈ ಮODULE ಈಗಾಗಲೇ ಪೋರ್ಟ್ 8081 ನಲ್ಲಿ ಚಾಲನೆಯಲ್ಲಿದೆ. ಕೆಳಗಿನ ಪ್ರಾರಂಭ ಆಜ್ಞೆಗಳನ್ನು ಬಿಟ್ಟು ಹೋಗಿ ನೇರವಾಗಿ http://localhost:8081 ಗೆ ಹೋಗಬಹುದು. -**ಆಯ್ಕೆಯು 1: ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ಬಳಸಿ (VS ಕೋಡ್ ಬಳಕೆದಾರರಿಗೆ ಶಿಫಾರಸು ಇದೆ)** +**ಆಯ್ಕೆ 1: ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ಬಳಕೆ (VS ಕೋಡ್ ಬಳಕೆದಾರರಿಗೆ ಶಿಫಾರಸು)** -ಡೆವ್ ಕಂಟೈನರ್ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ವಿಸ್ತರಣೆ ಒಳಗೊಂಡಿದೆ, ಅದು ಎಲ್ಲಾ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ದೃಶ್ಯಾತ್ಮಕವಾಗಿ ನಿರ್ವಹಿಸಲು ಅವಕಾಶ ನೀಡುತ್ತದೆ. ನೀವು ಅದನ್ನು VS ಕೋಡ್‌ನಲ್ಲಿ ಎಕ್ಟಿವಿಟಿ ಬಾರ್‌ನ ಎಡಭಾಗದಲ್ಲಿ (ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಐಕಾನ್ ನೋಡಿರಿ) ಕಾಣಬಹುದು. +ಡೇವ್ ಕಂಟೈನರ್‌ನಲ್ಲಿ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ವಿಸ್ತರಣೆ ಇದೆ, ಇದು ಎಲ್ಲಾ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ದೃಶ್ಯಾತ್ಮಕವಾಗಿ ನಿರ್ವಹಿಸಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ. ನೀವು VS ಕೋಡ್‌ನ ಎಡಭಾಗದಲ್ಲಿರುವ ಕ್ರಿಯಾಶೀಲತೆ ಪಟ್ಟಿಯಲ್ಲಿ (Activity Bar) ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಐಕಾನ್ ನೋಡಿ ಇದನ್ನು ಕಾಣಬಹುದು. ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್‌ನಿಂದ ನೀವು: -- ವೋರ್ಕ್‌ಸ್ಪೇಸ್‌ನ ಅಲೆಲ್ವತ್ತು ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನೋಡಬಹುದು -- ಒಂದೇ ಕ್ಲಿಕ್‌ನಲ್ಲಿ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪ್ರಾರಂಭ/ನಿಲ್ಲಿಸಬಹುದು -- ಅಪ್ಲಿಕೇಶನ್ ಲಾಗ್‌ಗಳನ್ನು ನೈಜ ಸಮಯದಲ್ಲಿ ವೀಕ್ಷಿಸಬಹುದು -- ಅಪ್ಲಿಕೇಶನ್ ಸ್ಥಿತಿಯನ್ನು ಮೇಲ್ವಿಚಾರಣೆ ಮಾಡಬಹುದು +- ಕಾರ್ಯಕ್ಷೇತ್ರದಲ್ಲಿರುವ ಎಲ್ಲಾ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನೋಡಿ +- ಒಂದೇ ಕ್ಲಿಕ್‌ನಿಂದ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪ್ರಾರಂಭ/ನಿಲ್ಲಿಸಿ +- ಅಪ್ಲಿಕೇಶನ್ ಲಾಗ್‌ಗಳನ್ನು ನಿಜ ಸಮಯದಲ್ಲಿ ನೋಡಿರಿ +- ಅಪ್ಲಿಕೇಶನ್ ಸ್ಥಿತಿಯನ್ನು ಮೇಲ್ವಿಚಾರಿಸಿ -ಕೆಲಸ ಪ್ರಯೋಗಕ್ಕಾಗಿ "rag" ಬಳಗಿನ ಪ್ಲೇ ಬಟನ್ ಒತ್ತಿ ಈ ಮಾಡ್ಯೂಲ್ ಪ್ರಾರಂಭಿಸಿ ಅಥವಾ ಎಲ್ಲಾ ಮಾಡ್ಯೂಲ್‌ಗಳನ್ನು ಒಂದೇ ಸಮಯದಲ್ಲಿ ಪ್ರಾರಂಭಿಸಿ. +"rag" ಪಕ್ಕದ ಪ್ಲೇ ಬಟನ್ ಕ್ಲಿಕ್ ಮಾಡಿ ಈ ಮODULE ಪ್ರಾರಂಭಿಸುವುದು ಅಥವಾ ಎಲ್ಲ ಮODULEಗಳನ್ನು ಒಟ್ಟಿಗೆ ಪ್ರಾರಂಭಿಸುವುದು. -ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ +Spring Boot Dashboard -*ಈ ಸ್ಕ್ರೀನ್‌ಶಾಟ್‌ವು VS ಕೋಡ್‌ನ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ಅನ್ನು ತೋರಿಸುತ್ತದೆ, ಇಲ್ಲಿ ನೀವು ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ದೃಶ್ಯಾತ್ಮಕವಾಗಿ ಪ್ರಾರಂಭಿಸಲು, ನಿಲ್ಲಿಸಲು ಮತ್ತು ಮೇಲ್ವಿಚಾರಣೆ ಮಾಡಲು পারবেন.* +*ಈ ಸ್ಕ್ರೀನ್‌ಶಾಟ್ VS ಕೋಡ್‌ನ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ಅನ್ನು ತೋರಿಸುತ್ತದೆ, ಇಲ್ಲಿ ನೀವು ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪ್ರಾರಂಭ, ನಿಲ್ಲಿಸುವ ಹಾಗೂ ದೃಶ್ಯಾತ್ಮಕವಾಗಿ ಮೇಲ್ವಿಚಾರಣೆ ಮಾಡಬಹುದು.* -**ಆಯ್ಕೆಯು 2: ಶೆಲ್ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಬಳಸಿ** +**ಆಯ್ಕೆ 2: ಶೆಲ್ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳನ್ನು ಬಳಕೆ ಮಾಡಿ** -ಎಲ್ಲಾ ವೆಬ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಆರಂಭಿಸು (ಮಾಡ್ಯೂಲ್ 01-04): +ಎಲ್ಲಾ ವೆಬ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳು (ಮODULEಗಳು 01-04) ಪ್ರಾರಂಭಿಸಿ: **Bash:** ```bash -cd .. # ಮೂಲ ಡೈರೆಕ್ಟರಿ ನಿಂದ +cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಿಂದ ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # ಮೂಲ ಡೈರೆಕ್ಟರಿಯಿಂದ +cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿ ನಿಂದ .\start-all.ps1 ``` -ಅಥವಾ ಈ ಮಾಡ್ಯೂಲ್ ಮಾತ್ರ ಪ್ರಾರಂಭಿಸು: +ಅಥವಾ ಈ ಮODULE ಮಾತ್ರ ಪ್ರಾರಂಭಿಸಿ: **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -ಎರಡೂ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಮೂಲ `.env` ಕಡತದಿಂದ ಪರಿಸರ ಚರಗಳನ್ನ ತುಂಬುತ್ತವೆ ಮತ್ತು JAR ಗಳು ಇಲ್ಲದಿದ್ದರೆ ನಿರ್ಮಿಸುತ್ತವೆ. +ಎರಡೂ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಮೂಲ `.env` ಫೈಲ್‌ನಿಂದ ಪರಿಸರ ವೇರಿಯಬಲ್ಗಳನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಲೋಡ್ ಮಾಡುತ್ತವೆ ಮತ್ತು ಜಾರ್ ಫೈಲ್‌ಗಳಿಲ್ಲದಿದ್ದರೆ ತಯಾರಿಸುತ್ತವೆ. -> **ಗಮನಿಸಿ:** ನೀವು ಪ್ರಾರಂಭಿಸುವ ಮುಂಚೆ ಎಲ್ಲಾ ಮಾಡ್ಯೂಲ್‌ಗಳನ್ನು ಕೈಯಿಂದ ನಿರ್ಮಿಸಲು ಇಚ್ಛಿಸಿದರೆ: +> **ಗಮನಿಸಿ:** ನೀವು ಪ್ರಾರಂಭಿಸುವ ಮುನ್ನ ಎಲ್ಲಾ ಮODULEಗಳನ್ನು ಕೈಯಿಂದ ನಿರ್ಮಿಸಲು ಇಚ್ಛಿಸಿದರೆ: > > **Bash:** > ```bash @@ -331,107 +330,107 @@ cd 03-rag **Bash:** ```bash -./stop.sh # ಈ ಮೋಡ್ಯೂಲ್ ಮಾತ್ರ +./stop.sh # ಈ ಮಾಯಾಜಾಲ ಮಾತ್ರ # ಅಥವಾ -cd .. && ./stop-all.sh # ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್‌ಗಳು +cd .. && ./stop-all.sh # ಎಲ್ಲಾ ಮಾಯಾಜಾಲಗಳು ``` **PowerShell:** ```powershell -.\stop.ps1 # ಈ ಮೋಡ್ಯೂಲ್ ಮಾತ್ರ +.\stop.ps1 # ಈ ಮಾಯಾಜಾಲ ಮಾತ್ರ # ಅಥವಾ -cd ..; .\stop-all.ps1 # ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್‌ಗಳು +cd ..; .\stop-all.ps1 # ಎಲ್ಲಾ ಮಾಯಾಜಾಲಗಳು ``` ## ಅಪ್ಲಿಕೇಶನ್ ಬಳಕೆ -ಅಪ್ಲಿಕೇಶನ್ ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ್ಲೋಡ್ ಮತ್ತು ಪ್ರಶ್ನಿಸುವ ವೆಬ್ ಇಂಟರ್‌ಫೇಸ್ ಅನ್ನು ಒದಗಿಸುತ್ತದೆ. +ಅಪ್ಲಿಕೇಶನ್ ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ್ಲೋಡ್ ಮತ್ತು ಪ್ರಶ್ನೆಯನ್ನು ವೆಬ್ ಇಂಟರ್‌ಫೇಸ್ ಮೂಲಕ ಒದಗಿಸುತ್ತದೆ. -RAG ಅಪ್ಲಿಕೇಶನ್ ಇಂಟರ್‌ಫೇಸ್ +RAG Application Interface -*ಈ ಸ್ಕ್ರೀನ್‌ಶಾಟ್‌ನಲ್ಲಿ RAG ಅಪ್ಲಿಕೇಶನ್ ಇಂಟರ್‌ಫೇಸ್ ಕಾಣಬಹುದು, ನೀವು ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ್ಲೋಡ್ ಮಾಡಿ ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳಬಹುದು.* +*ಈ ಸ್ಕ್ರೀನ್‌ಶಾಟ್ RAG ಅಪ್ಲಿಕೇಶನ್ ಇಂಟರ್‌ಫೇಸ್ ಅನ್ನು ತೋರಿಸುತ್ತದೆ, ಇಲ್ಲಿ ನೀವು ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಅಪ್ಲೋಡ್ ಮಾಡಿ ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳಬಹುದು.* -### ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ್ಲೋಡ್ ಮಾಡಿ +### ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ್ಲೋಡ್ ಮಾಡುವುದು -ಮೂರು ಉಪವಿಭಾಗವಾಗಿ ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ்லೋಡ್ ಮಾಡಿ ಪ್ರಾರಂಭಿಸಿ - ಟೆಕ್ಸ್ಟ್ ಫೈಲ್ಗಳು ಪರೀಕ್ಷೆಗೆ ಅತ್ಯುತ್ತಮ. ಈ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ LangChain4j ಫೀಚರ್ಸ್, RAG ಅನುಷ್ಠಾನ ಮತ್ತು ಉತ್ತಮ ಅಭ್ಯಾಸಗಳ ಕುರಿತು ಮಾಹಿತಿ ಹೊಂದಿರುವ `sample-document.txt` ಒದಗಿಸಲಾಗಿದೆ - ವ್ಯವಸ್ಥೆಯನ್ನು ಪರೀಕ್ಷಿಸಲು ಸೂಕ್ತ. +ಡಾಕ್ಯುಮೆಂಟ್ ಅಪ್ಲೋಡ್ ಮಾಡಿಕೊಳ್ಳುವುದು ಆರಂಭವೊಂದು — ಪರೀಕ್ಷೆಗಾಗಿ TXT ಫೈಲ್‌ಗಳು ಅತ್ಯುತ್ತಮ. ಈ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ `sample-document.txt` ಒದಗಿಸಲಾಗಿದೆ, ಇದು LangChain4j ವೈಶಿಷ್ಟ್ಯಗಳು, RAG ಅನುಷ್ಠಾನ, ಮತ್ತು ಉತ್ತಮ ಅಭ್ಯಾಸಗಳ ಕುರಿತು ಮಾಹಿತಿಯನ್ನು ಒಳಗೊಂಡಿದೆ — ವ್ಯವಸ್ಥೆಯನ್ನು ಪರೀಕ್ಷಿಸಲು ಪರಿಪೂರ್ಣ. -ವ್ಯವಸ್ಥೆ ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು ಪ್ರಕ್ರಿಯೆಗೊಳಿಸಿ, ಅದನ್ನು ಚಂಕುಗಳಾಗಿ ವಿಭಜಿಸಿ, ಪ್ರತಿ ಚಂಕಿಗೆ ಎಮ್ಬೆಡ್ಡಿಂಗ್ ಸೃಷ್ಟಿಸುತ್ತದೆ. ಇದು ನೀವು ಅಪ್ಲೋಡ್ ಮಾಡಿದಾಗ ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಆಗುತ್ತದೆ. +ವ್ಯವಸ್ಥೆ ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು ಪ್ರಕ್ರಿಯೆ ಮಾಡುತ್ತದೆ, ಅದನ್ನು ತುಣುಕುಗಳಾಗಿ բաժಡಿಸುತ್ತದೆ ಮತ್ತು ಪ್ರತಿಯೊಂದು ತುಣುಕಿಗೆ ಆಂಬೆಡ್ಡಿಂಗ್ ತಯಾರಿಸುತ್ತದೆ. ಅದು ಸ್ವಯಂಚಾಲಿತವಾಗಿಯೇ ಅಪ್ಲೋಡ್ ಮಾಡಿದಾಗ ನಡೆಯುತ್ತದೆ. -### ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳಿ +### ಪ್ರಶ್ನೆಗಳು ಕೇಳಿ -ಈಗ ಡಾಕ್ಯುಮೆಂಟ್ ವಿಷಯದ ಕುರಿತು ನಿರ್ದಿಷ್ಟವಾದ ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳಿ. ಡಾಕ್ಯುಮೆಂಟ್‌ನಲ್ಲಿ ಸ್ಪಷ್ಟವಾಗಿ ನೀಡಲಾಗಿರುವ ಸತ್ಯದ ವಿಷಯವನ್ನು ಪ್ರಯತ್ನಿಸಿ. ವ್ಯವಸ್ಥೆ ಸಂಬಂಧಿತ ಚಂಕುಗಳನ್ನು ಹುಡುಕಿ, ಅವುಗಳನ್ನು ಪ್ರಾಂಪ್ಟ್‌ಗೆ ಸೇರಿಸಿ ಮತ್ತು ಉತ್ತರವನ್ನು ಉತ್ಪಾದಿಸುತ್ತದೆ. +ಈಗ ಡಾಕ್ಯುಮೆಂಟ್ ವಿಷಯದ ಬಗ್ಗೆ ನಿರ್ದಿಷ್ಟ ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳಿ. ಡಾಕ್ಯುಮೆಂಟ್‌ನಲ್ಲಿ ಸ್ಪಷ್ಟವಾಗಿ ಹೇಳಲ್ಪಟ್ಟ ವಾಸ್ತವಿಕ ವಿಷಯಗಳನ್ನು ಪ್ರಯತ್ನಿಸಿ. ವ್ಯವಸ್ಥೆ ಸಂಬಂಧಿಸಿದ ತುಣುಕಿನ ಹುಡುಕಾಟ ಮಾಡುತ್ತದೆ, ಅವುಗಳನ್ನು ಪ್ರಾಂಪ್ಟ್‌ಗೆ ಸೇರಿಸಿ ಉತ್ತರವನ್ನು ರಚಿಸುತ್ತದೆ. -### ಮೂಲ ಉಲ್ಲೇಖ ಪರಿಶೀಲಿಸಿ +### ಮೂಲ ಸೂಚನೆಗಳನ್ನು ಪರಿಶೀಲಿಸುವುದು -ಪ್ರತಿ ಉತ್ತರವು ಸಾಮಾನ್ಯವಾಗಿ ಮೂಲ ಉಲ್ಲೇಖಗಳನ್ನು ಸಾದೃಶ್ಯ ಸ್ಕೋರ್‌ಗಳೊಂದಿಗೆ ನೀಡುತ್ತದೆ. ಈ ಸ್ಕೋರ್‌ಗಳು (0 ರಿಂದ 1) ಪ್ರತಿಯೊಂದು ಚಂಕು ನಿಮ್ಮ ಪ್ರಶ್ನೆಗೆ ಎಷ್ಟು ಸಂಬಂಧಿತವಾಗಿತ್ತು ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತವೆ. ಹೆಚ್ಚಿನ ಸ್ಕೋರ್‌ಗಳು ಉತ್ತಮ ಹೊಂದಿಕೆಯನ್ನು ಸೂಚಿಸುತ್ತವೆ. ಇದರಿಂದ ನೀವು ಉತ್ತರವನ್ನು ಮೂಲ ವಸ್ತುವಿಗೆ ವಿರುದ್ಧ ಪರಿಶೀಲಿಸಬಹುದು. +ಪ್ರತಿ ಉತ್ತರದೊಂದಿಗೆ ಮೂಲ ಸೂಚನೆಗಳು ಮತ್ತು ಸಮಾನತೆಯ ಅಂಕೆಗಳು ಇದ್ದವೆ. ಈ ಅಂಕೆಗಳು (0 ರಿಂದ 1) ನಿಮ್ಮ ಪ್ರಶ್ನೆಯೊಂದಿಗೆ ಸಂಬಂಧಿಸಿದ ಪ್ರತಿಯೊಂದು ತುಣುಕಿನ ಸಂಬಂಧವನ್ನು ತೋರಿಸುತ್ತವೆ. ಹೆಚ್ಚು ಅಂಕೆಗಳು ಉತ್ತಮ ಹೊಂದಾಣಿಕೆಯನ್ನು ಸೂಚಿಸುತ್ತವೆ. ಇದರಿಂದ ನೀವು ಉತ್ತರವನ್ನು ಮೂಲ ವಸ್ತುಗಳ ಸಾಗಣೆಯೊಂದಿಗೆ ಪರಿಶೀಲಿಸಬಹುದು. -RAG ಪ್ರಶ್ನೆ ಫಲಿತಾಂಶಗಳು +RAG Query Results -*ಈ ಸ್ಕ್ರೀನ್‌ಶಾಟ್‌ನಲ್ಲಿ ಉತ್ಪಾದಿತ ಉತ್ತರ, ಮೂಲ ಉಲ್ಲೇಖಗಳು ಮತ್ತು ಪ್ರತಿಯೊಂದು ಕಂಡುಬಂದ ಚಂಕಿನ ಪ್ರಸ್ತುತ ಸಾದೃಶ್ಯ ಸ್ಕೋರ್‌ಗಳೊಂದಿಗೆ ಪ್ರಶ್ನೆ ಫಲಿತಾಂಶಗಳನ್ನು ತೋರಿಸುತ್ತದೆ.* +*ಈ ಸ್ಕ್ರೀನ್‌ಶಾಟ್‌ನಲ್ಲಿ ಉತ್ಪಾದಿತ ಉತ್ತರ, ಮೂಲ ಸೂಚನೆಗಳು ಮತ್ತು ಪ್ರತಿಯೊಂದು ಪಡೆದ ತುಣುಕಿನ ಸಂಬಂಧ ಅಂಕೆಗಳೊಂದಿಗೆ ಪ್ರಶ್ನೆ ಫಲಿತಾಂಶಗಳನ್ನು ತೋರಿಸಲಾಗಿದೆ.* -### ಪ್ರಶ್ನೆಗಳೊಂದಿಗೆ ಪ್ರಯೋಗ ಮಾಡಿ +### ಪ್ರಶ್ನೆಗಳಲ್ಲಿ ಪ್ರಯೋಗ ಮಾಡಿ ವಿವಿಧ ವಿಧದ ಪ್ರಶ್ನೆಗಳನ್ನು ಪ್ರಯತ್ನಿಸಿ: - ನಿರ್ದಿಷ್ಟ ವಾಸ್ತವಗಳು: "ಮುಖ್ಯ ವಿಷಯವೇನು?" -- ಹೋಲಿಕೆಗಳು: "X ಮತ್ತು Y ನಡುವಿನ ವ್ಯತ್ಯಾಸವೇನು?" -- ಸಾರಾಂಶಗಳು: "Z ಬಗ್ಗೆ ಮುಖ್ಯ ಅಂಶಗಳನ್ನು ಸಾರಾಂಶ ಮಾಡಿ" +- ಹೋಲಿಕೆಗಳು: "X ಮತ್ತು Y ನಡುವೆ ಏನು ವ್ಯತ್ಯಾಸವಿದೆ?" +- ಸಾರಾಂಶ: "Z ಕುರಿತು ಮುಖ್ಯ ಅಂಶಗಳನ್ನು ಸಂಕ್ಷಿಪ್ತಗೊಳಿಸಿ" -ನಿಮ್ಮ ಪ್ರಶ್ನೆ ಎಷ್ಟೊಂದು ಚೆನ್ನಾಗಿ ಡಾಕ್ಯುಮೆಂಟ್ ವಿಷಯದೊಂದಿಗೆ ಹೊಂದಿದೆಯೋ ಅವುದರ ಮೇರೆಗೆ ಸಾದೃಶ್ಯ ಸ್ಕೋರ್‌ಗಳ ಬದಲಾವಣೆಯನ್ನು ಗಮನಿಸಿ. +ನಿಮ್ಮ ಪ್ರಶ್ನೆ ಡಾಕ್ಯುಮೆಂಟ್ ವಿಷಯದೊಂದಿಗೆ ಅಥ್ವವಾಗುವಿಕೆಯನ್ನು ಅವಲಂಬಿಸಿ ಸಂಬಂಧ ಅಂಕೆಗಳ ಬದಲಾವಣೆಯನ್ನು ಗಮನಿಸಿ. -## ಪ್ರಮುಖ ತತ್ವಗಳು +## ಪ್ರಮುಖ ಕಲ್ಪನೆಗಳು -### ಚಂಕಿಂಗ್ ತಂತ್ರಜ್ಞಾನ +### ತುಣಕುಗಳ ತಂತ್ರ -ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು 300 ಟೋಕನ್‌ಗಳ ಚಂಕುಗಳಾಗಿ ಮತ್ತು 30 ಟೋಕನ್‌ಗಳ ಓವರ್‌ಲ್ಯಾಪ್‌ನೊಂದಿಗೆ ವಿಭಜಿಸಲಾಗುತ್ತದೆ. ಈ ಸಮತೋಲನದಿಂದ ಪ್ರತಿ ಚಂಕಿಗೆ ಅರ್ಥಬೋಧಕವಾಗಲು ಸಾಕಷ್ಟು ಪೃಥ್ವಿಯುಂಟಾಗುತ್ತದೆ ಮತ್ತು ಚಿಕ್ಕ ಗಾತ್ರದಲ್ಲೇ ಹಲವು ಚಂಕುಗಳನ್ನು ಪ್ರಾಂಪ್ಟ್‌ನಲ್ಲಿ ಸೇರಿಸಲು ಸಾಧ್ಯವಾಗುತ್ತದೆ. +ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು 300-ಟೋಕನ್ ತುಣುಕಾಗಿ 30 ಟೋಕನ್ ಎಲ್ಲಾಪ್ ಹೊಂದಿಸಿ ವಿಭಾಗ ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಸಮತೋಲನವು ಪ್ರತಿ ತುಣುಕಿಗೆ ಪ್ರಾಸಂಗಿಕತೆಯಷ್ಟು ಸನ್ನಿವೇಶವನ್ನು ನೀಡುತ್ತದೆ ಮತ್ತು ಸಾಕಷ್ಟು ತುಣುಕುಗಳನ್ನು ಪ್ರಾಂಪ್ಟ್‌ಗೆ ಸೇರಿಸಲು ಸಣ್ಣದಾಗಿರಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ. -### ಸಾದೃಶ್ಯ ಸ್ಕೋರ್‌ಗಳು +### ಸಮಾನತೆ ಅಂಕೆಗಳು -ಪ್ರತಿಯೊಂದು ಪೃಥ್ವಿಯಿಂದ ಪಡೆದ ಚಂಕುಗಳಿಗೆ ಬಳಕೆದಾರರ ಪ್ರಶ್ನೆಗೆ ಎಷ್ಟು ಹೊಂದಿದೆಯೋ ಮಾರ್ಕೆ ಮಾಡುವ 0ರಿಂದ 1ರೊಳಗಿನ ಸಾದೃಶ್ಯ ಸ್ಕೋರ್ ಇದೆ. ಕೆಳಗಿನ ಚಿತ್ರಣ ಸ್ಕೋರ್ ದೈರ್ಪ್ಯವನ್ನು ಮತ್ತು ವ್ಯವಸ್ಥೆ ಅವುಗಳನ್ನು ಹೇಗೆ ಫಲಿತಾಂಶಗಳನ್ನು ಶೋಧಿಸಲು ಬಳಸುತ್ತದೆಯೋ ತೋರಿಸುತ್ತದೆ: +ಪ್ರತಿ ಪಡೆದ ತುಣುಕಿನತ್ತ 0 ರಿಂದ 1 ಜಾತಿಯ ಸಮಾನತೆ ಅಂಕೆ ಇರುತ್ತದೆ, ಇದು ಬಳಕೆದಾರರ ಪ್ರಶ್ನೆಯೊಂದಿಗೆ ಅದರ ಹೊಂದಾಣಿಕೆಯನ್ನು ಸೂಚಿಸುತ್ತದೆ. ಕೆಳಗಿನ ರೇಖಾಚಿತ್ರವು ಅಂಕೆ ಮಾರುಕಟ್ಟೆಯನ್ನು ಮತ್ತು ವ್ಯವಸ್ಥೆಯು ಅವುಗಳನ್ನು ಫಲಿತಾಂಶಗಳನ್ನು ತಳ್ಳುವುದು ಹೇಗೆ ಎಂಬುದನ್ನು ವಿವರಿಸುತ್ತದೆ: -ಸಾದೃಶ್ಯ ಸ್ಕೋರ್‌ಗಳು +Similarity Scores -*ಈ ಚಿತ್ರಣವು 0ರಿಂದ 1ರವರೆಗೆ ಸ್ಕೋರ್ ವ್ಯಾಪ್ತಿಗಳನ್ನು ತೋರಿಸುತ್ತದೆ, ಅತಿತರ ಮೂಲ ಚಂಕುಗಳನ್ನು ಫಿಲ್ಟರ್ ಮಾಡಲು ಕನಿಷ್ಠ 0.5 ಗಡಿ ಹೊಂದಿದೆ.* +*ಈ ರೇಖಾಚಿತ್ರವು 0 ರಿಂದ 1 ರವರೆಗೆ ಅಂಕೆಗಳ ವ್ಯಾಪ್ತಿಯನ್ನು ತೋರಿಸುತ್ತದೆ, ಇದರಲ್ಲಿ ಕನಿಷ್ಠ ಮಿತಿ 0.5 ಆಗಿದ್ದು ಸಂಬಂಧವಿಲ್ಲದ ತುಣುಕುಗಳನ್ನು ತಳ್ಳುತ್ತದೆ.* -ಸ್ಕೋರ್ ವ್ಯಾಪ್ತಿಗಳು 0ರಿಂದ 1ರವರೆಗೆ: -- 0.7-1.0: ಅತ್ಯಂತ ಸಂಬಂಧಿತ, ನಿಖರ ಹೊಂದಿಕೆ -- 0.5-0.7: ಸಂಬಂಧಿತ, ಉತ್ತಮ ಪೃಥ್ವಿ -- 0.5 ಕ್ಕಿಂತ ಕೆಳಗೆ: ಫಿಲ್ಟರ್‌ಗೊಳಿಸಲ್ಪಟ್ಟ, ಬಹಳ ಅಸಂಬಂಧಿತ +ಅಂಕೆಗಳ ವ್ಯಾಪ್ತಿ 0 ರಿಂದ 1: +- 0.7-1.0: ಅತ್ಯಂತ ಸಂಬಂಧಿತ, ನಿಖರ ಹೊಂದಾಣಿಕೆ +- 0.5-0.7: ಸಂಬಂಧಿತ, ಉತ್ತಮ ಪ್ರಾಸಂಗಿಕತೆ +- 0.5 ಕ್ಕಿಂತ ಕಡಿಮೆ: ತಳ್ಳಲ್ಪಟ್ಟಿವೆ, ತುಂಬಾ ಭಿನ್ನ -ನಿರ್ದೇಶನದ ಗುಣಾತ್ಮಕತೆಗೆ ಖಚಿತತೆಗೆ ವ್ಯವಸ್ಥೆ ಕನಿಷ್ಠ ಗಡಿಯನ್ನು ಮೀರಿ వచ్చిన ಚಂಕುಗಳನ್ನು ಮಾತ್ರ ಪಡೆಯುತ್ತದೆ. +ಮಾಹಿತಿಯ ಗುಣಮಟ್ಟಕ್ಕಾಗಿ ವ್ಯವಸ್ಥೆ ಕನಿಷ್ಠ ಮಿತಿಗಿಂತ ಮೇಲ್ಪಡೆ ತುಣುಕನ್ನು ಮಾತ್ರ ಪಡೆಯುತ್ತದೆ. -ಎಂಬೆಡ್ಡಿಂಗ್‌ಗಳು ಅರ್ಥ ಕ್ಲಸ್ಟರ್‌ಗಳು ಸ್ವಚ್ಛವಾಗಿದ್ದಾಗ ಉತ್ತಮ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ, ಆದರೆ ಅವುಗಳಿಗೆ ಕೆಲ ಅಂಧಪ್ರದೇಶಗಳಿವೆ. ಕೆಳಗಿನ ಚಿತ್ರಣ ಸಾಮಾನ್ಯ ವೈಫಲ್ಯ ಮಾದರಿಗಳನ್ನು ತೋರಿಸುತ್ತದೆ — ಅತಿದೊಡ್ಡ ಚಂಕುಗಳು ಮಾಂಡ್ಯ ವೆಕ್ಟರ್‌ಗಳನ್ನು ಉತ್ಪತ್ತು ಮಾಡುತ್ತವೆ, ಅತ Litt ಲ ಚಂಕುಗಳು ಪೃಥ್ವಿಯ ಕೊರತೆ ಕಂಡುಬರುತ್ತದೆ, ಅನಂಬiguous ಪದಗಳು ಬಹು ಕ್ಲಸ್ಟರ್‌ಗಳಿಗೆ ಸೂಚಿಸುತ್ತವೆ, ಮತ್ತು ನಿಖರ ಹೊಂದಿಕೆಯ ಲುಕ್‌ಅಪ್‌ಗಳು (ಐಡಿಗಳು, ಭಾಗ ಸಂಖ್ಯೆಗಳು) ಎಂಬೆಡ್ಡಿಂಗ್‌ಗಳಿಗೆ ಕೆಲಸ ಮಾಡುವುದಿಲ್ಲ: +ಆಂಬೆಡ್ಡಿಂಗ್‌ಗಳು ಅರ್ಥಾಸ್ಪದ ಗುಂಪುಗಳನ್ನು ಚೆನ್ನಾಗಿ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ, ಆದಾಗ್ಯೂ ಅವುಗೆ ಕೆಲ ಅಂಗಲಾಗುವಿಕೆಗಳಿವೆ. ಕೆಳಗಿನ ರೇಖಾಚಿತ್ರವು ಸಾಮಾನ್ಯ ವಿಫಲತೆಯ ರೀತಿಗಳನ್ನು ತೋರಿಸುತ್ತದೆ — ತುಂಬಾ ದೊಡ್ಡ ತುಣುಕುಗಳು ಅಲಿಸತ ನೀರೆಯಂತೆ ವೆಕ್ಟರ್‌ಗಳನ್ನು ಸೃಷ್ಟಿಸುತ್ತವೆ, ತುಂಬಾ ಸಣ್ಣ ತುಣುಕಿಗೆ ಸನ್ನಿವೇಶ ಕೊರತೆ, ಅನಿಶ್ಚಿತ ಪದಗಳು ಹಲವು ಗುಂಪುಗಳಿಗೆ ಸೂಚನೆ ನೀಡುತ್ತವೆ, ಮತ್ತು ನಿಖರ-ಹೊಂದಾಣಿಕೆ ಹುಡುಕಾಟಗಳು (ID ಗಳು, ಭಾಗ ಸಂಖ್ಯೆ) ಆಂಬೆಡ್ಡಿಂಗ್‌ಗಳೊಂದಿಗೆ ಕೆಲಸ ಮಾಡುತ್ತಿಲ್ಲ: -ಎಂಬೆಡ್ಡಿಂಗ್ ವಿಫಲತೆ ಮಾದರಿಗಳು +Embedding Failure Modes -*ಈ ಚಿತ್ರಣದಲ್ಲಿ ಸಾಮಾನ್ಯ ಎಂಬೆಡ್ಡಿಂಗ್ ವಿಫಲತೆ ಮಾದರಿಗಳು ತೋರಿಸಲಾಗಿದೆ: ಚಂಕುಗಳು ತುಂಬಾ ದೊಡ್ಡದಾಗಿರೋದು, ಚಂಕುಗಳು ತುಂಬಾ ಸಣ್ಣದಾಗಿರೋದು, ಅನಂಬiguous ಪದಗಳು ಬಹು ಕ್ಲಸ್ಟರ್‌ಗಳಿಗೆ ಸೂಚಿಸುವುದು, ಮತ್ತು ನಿಖರ ಹೊಂದಿಕೆಯ ಲುಕ್‌ಅಪ್ಗಳಂತಹ ಐಡಿಗಳು.* +*ಈ ರೇಖಾಚಿತ್ರವು ಸಾಮಾನ್ಯ ಆಂಬೆಡ್ಡಿಂಗ್ ವಿಫಲತೆ ಕ್ರಮಗಳನ್ನು ತೋರಿಸುತ್ತದೆ: ತುಂಬಾ ದೊಡ್ಡ ತುಣಕುಗಳು, ತುಂಬಾ ಸಣ್ಣ ತುಣಕುಗಳು, ಅನಿಶ್ಚಿತ ಪದಗಳು ಬಹು ಗುಂಪುಗಳಿಗೆ ಸೂಚಿಸುವುದು, ಮತ್ತು IDಗಳಂತಹ ನಿಖರ-ಹೊಂದಾಣಿಕೆ ಹುಡುಕಾಟಗಳು.* -### ಇನ್-ಮೆಮರಿ ಸಂಗ್ರಹಣೆ +### ಮೆಮೊರಿ ಸಂಗ್ರಹಣೆ -ಈ ಮಾಡ್ಯೂಲ್ ಸರಳತೆಗೆ ಇನ್-ಮೆಮರಿ ಸಂಗ್ರಹಣೆಯನ್ನು ಬಳಸುತ್ತದೆ. ನೀವು ಅಪ್ಲಿಕೇಶನ್ ಅನ್ನು ಮರುಪ್ರಾರಂಭಿಸಿದಾಗ ಅಪ್ಲೋಡ್ ಮಾಡಿದ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳು ನಷ್ಟವಾಗುತ್ತವೆ. ಉತ್ಪಾದನಾ ವ್ಯವಸ್ಥೆಗಳು Qdrant ಅಥವಾ ಅಜುರ್ AI ಸರ್ಚ್ ಇದ್ದಂತಹ ಸ್ಥಿರ ವೆಕ್ಟರ್ ಡೇಟಾಬೇಸ್‌ಗಳನ್ನು ಬಳಸುತ್ತವೆ. +ಈ ಮODULE ಸರಳತೆಗೆ ಮೆಮೊರಿ ಸಂಗ್ರಹಣೆಯನ್ನು ಬಳಸುತ್ತದೆ. ಅಪ್ಲಿಕೇಶನ್ ಮರುಪ್ರಾರಂಭಿಸಿದಾಗ ಅಪ್ಲೋಡ್ ಮಾಡಿದ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳು ಕಳೆದುಹೋಗುತ್ತವೆ. ಉತ್ಪಾದನಾ ವ್ಯವಸ್ಥೆಗಳು Qdrant ಅಥವಾ Azure AI Search ಮುಂತಾದ ಸ್ಥಿರ ವೆಕ್ಟರ್ ಡೇಟಾಬೇಸ್‌ಗಳನ್ನು ಬಳಸುತ್ತದೆ. -### ಪೃಥ್ವಿ ವಿಂಡೋ ನಿರ್ವಹಣೆ +### ಸನ್ನಿವೇಶ ಕಿಟಕಿ ನಿರ್ವಹಣೆ -ಪ್ರತಿ ಮಾದರಿಯು ಗರಿಷ್ಠ ಪೃಥ್ವಿ ವಿಂಡೋ ಹೊಂದಿದೆ. ಬೃಹತ್ ಡಾಕ್ಯುಮೆಂಟ್‌ನ ಪ್ರತಿಯೊಂದು ಚಂಕುಗಳನ್ನು ಸೇರಿಸುವ ಸಾಧ್ಯತೆ ಇಲ್ಲ. ವ್ಯವಸ್ಥೆ ಮೆಚ್ಚಿನ ಟಾಪ್ N ಚಂಕುಗಳನ್ನು (ಡೀಫಾಲ್ಟ್ 5) ಪಡೆದು ಮಿತಿಗಳಿಗೆ ಒಳಗಿರುತ್ತಾ, ಸರಿಯಾದ ಉತ್ತರಕ್ಕೆ ಸಾಕಷ್ಟು ಪೃಥ್ವಿಯನ್ನು ಒದಗಿಸುತ್ತದೆ. +ಪ್ರತಿ ಮಾದರಿಗೊಂದು ಗರಿಷ್ಠ ಸನ್ನಿವೇಶ ಕಿಟಕಿ ಇದೆ. ದೊಡ್ಡ ಡಾಕ್ಯುಮೆಂಟ್‌ನ ಎಲ್ಲಾ ತುಣುಕುಗಳನ್ನು ಸೇರಿಸಲು ಸಾಧ್ಯವಿಲ್ಲ. ವ್ಯವಸ್ಥೆ ಪ್ರಾಮುಖ್ಯತೆಯ ಮೇಲ್ಪಡೆ N (ನಿರ್ಮಾಣಮ್ 5) ತುಣುಕುಗಳನ್ನು ಪಡೆದು ಸೇರಿಸುವ ಮೂಲಕ ನಿಯಂತ್ರಣದಲ್ಲಿರುತ್ತದೆ ಮತ್ತು ಸರಿಯಾದ ಉತ್ತರಕ್ಕೆ ಸನ್ನಿವೇಶದ ಸಾಕಷ್ಟು ಪ್ರಮಾಣ ಒದಗಿಸುತ್ತದೆ. -## RAG ಯಾರು ಮುಖ್ಯ +## RAG ಯಾಗಿರುವ ಸಂದರ್ಭಗಳು -RAG ಸದಾ ಸರಿಯಾದ ವಿಧಾನವಲ್ಲ. ಕೆಳಗಿನ ನಿರ್ಣಯ ಮಾರ್ಗದರ್ಶಿ ನಿಮಗೆ RAG ನಲ್ಲಿ ಮೌಲ್ಯವಿದ್ದರೆ ಅಥವಾ ಸರಳ ವಿಧಾನಗಳು (ಪ್ರಾಂಪ್ಟ್‌ಗೆ ವಿಷಯವನ್ನು ನೇರ ಸೇರಿಸುವುದು ಅಥವಾ ಮಾದರಿಯ ಹೊರಗಿದ್ದ ಜ್ಞಾನವನ್ನು ನಂಬುವುದು) ಸಾಕಾಗುವುದನ್ನು ಹೇಗೆ ಗಡಿಯಿಡಬಹುದು ಎಂಬುದನ್ನು ಸಹಾಯ ಮಾಡುತ್ತದೆ: +RAG ಯಾವಾಗಲೂ ಸರಿಯಾದ ವಿಧಾನವಲ್ಲ. ಕೆಳಗಿನ ತೀರ್ಮಾನ ಮಾರ್ಗದರ್ಶಿ RAG ಹೆಚ್ಚುವಾಗಿ ಮೌಲ್ಯವನ್ನು ಸೇರಿಸುವಾಗ ಮತ್ತು ಸರಳ ವಿಧಾನಗಳು — ಅಂದರೆ ಪ್ರಾಂಪ್ಟ್‌ಗೆ ನೇರ ವಿಷಯ ಸೇರಿಸುವುದು ಅಥವಾ ಮಾದರಿಯ ನಿರ್ಮಿತ ಜ್ಞಾನವನ್ನು ಅವಲಂಬಿಸುವುದು — ಯಾಕಾಗು ಸಾಕಾಗುವುದು ಎಂಬುದನ್ನು ನಿರ್ಧರಿಸಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ: -RAG ಯಾವಾಗ ಬಳಸಬೇಕು +When to Use RAG -*ಈ ಚಿತ್ರಣವು RAG ಯಾಗು ಬೆಲೆ ಏರುತ್ತದೆ, ಹಾಗೂ ಎಷ್ಟಾಗಲೀ ಸರಳ ವಿಧಾನಗಳು ಸಾಕಾಗುವ ಸಂದರ್ಭವನ್ನು ತೋರಿಸುವ ನಿರ್ಣಯ ಮಾರ್ಗದರ್ಶಿಯನ್ನು ವಿವರಿಸುತ್ತದೆ.* +*ಈ ರೇಖಾಚಿತ್ರವು RAG ಹೆಚ್ಚುವಾಗಿ ಮೌಲ್ಯವನ್ನು ಸೇರಿಸುವ ಸಂದರ್ಭ ಮತ್ತು ಸರಳ ವಿಧಾನಗಳು ಸಾಕಾಗುವ ಸಂದರ್ಭಗಳ ತೀರ್ಮಾನ ಮಾರ್ಗದರ್ಶಿಯಿದೆ.* ## ಮುಂದಿನ ಹಂತಗಳು -**ಮುಂದಿನ ಮಾಡ್ಯೂಲ್:** [04-tools - ಸಾಧನಗಳೊಂದಿಗೆ ಕೃತಕ ಬುದ್ಧಿಮತ್ತೆ ಏಜೆಂಟ್ಗಳು](../04-tools/README.md) +**ಮುಂದಿನ ಮODULE:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**ನಿರ್ದೇಶನ:** [← ಹಿಂದಿನ: ಮಾಡ್ಯೂಲ್ 02 - ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್](../02-prompt-engineering/README.md) | [ಮೂಲಕ್ಕೆ ಹಿಂತಿರುಗಿ](../README.md) | [ಮುಂದಿನ: ಮಾಡ್ಯೂಲ್ 04 - ಸಾಧನಗಳು →](../04-tools/README.md) +**ನಾವಿಗೇಶನ್:** [← ಹಿಂದಿನದು: Module 02 - ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್](../02-prompt-engineering/README.md) | [ಮೇಲ್ಗಡೆ ಕುಟುಂಬಕ್ಕೆ](../README.md) | [ಮುಂದಿನದು: Module 04 - ಸಾಧನಗಳು →](../04-tools/README.md) --- -**ತಪ್ಪಿಸು ಸೂಚನೆ**: -ಈ ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಗೆ ಪ್ರಯತ್ನಿಸುವುದರಿಂದ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ತಪ್ಪುಗಳು ಅಥವಾ ಅವಿವೇಕತೆಗಳಿರುವ ಸಾಧ್ಯತೆಯಿದೆ ಎಂದು ದಯವಿಟ್ಟು ಗಮನಿಸಿ. ಮೂಲ ಡಾಕ್ಯುಮೆಂಟ್ ಅದರ ಮೂಲ ಭಾಷೆಯಲ್ಲಿ ಅಧಿಕೃತ ಮೂಲವಾಗಿರುತ್ತದೆ ಎಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗಿದೆ. ಈ ಅನುವಾದ ಬಳಕೆಯಿಂದ ಸಂಭವಿಸುವ ಯಾವುದೇ ತಪ್ಪು ಗ್ರಹಿಕೆಗಳು ಅಥವಾ ತಪ್ಪು ಅರ್ಥಗಳನ್ನು ನಾವು ಹೊಣೆಗಾರರಾಗುವುದಿಲ್ಲ. +**ಅಸ್ವೀಕಾರ**: +ಈ ದಸ್ತಾವೇಜು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಯನ್ನು ಸಾಧಿಸಲು ಪ್ರಯತ್ನಿಸುತ್ತಿದ್ದರೂ, ದಯವಿಟ್ಟು ಗಮನಿಸಿ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ಅಸಡ್ಡೆಗಳು ಇರಬಹುದು. ಮೂಲ ಭಾಷೆಯಲ್ಲಿರುವ ಮೂಲ ದಸ್ತಾವೇಜು ಪ್ರಾಮಾಣಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದವನ್ನು ಬಳಸುವ ಮೂಲಕ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪು ಅರ್ಥಗಳ ಅಥವಾ ತಪ್ಪು ವ್ಯಾಖ್ಯಾನಗಳ ಬಗ್ಗೆ ನಾವು ಹೊಣೆಗಾರರಲ್ಲ. \ No newline at end of file diff --git a/translations/kn/04-tools/README.md b/translations/kn/04-tools/README.md index 0776d5ef1..206319ade 100644 --- a/translations/kn/04-tools/README.md +++ b/translations/kn/04-tools/README.md @@ -1,84 +1,84 @@ -# Module 04: ಟೂಲ್ಗಳೊಂದಿಗೆ ಎಐ ಏಜೆಂಟ್ಗಳು - -## ವಿಷಯ ಸೂಚಿಕೆ - -- [ವೀಡಿಯೋ ವಾಕ್‌ಥ್ರೂ](../../../04-tools) -- [ನೀವು ಕಲಿಯುವುದು](../../../04-tools) -- [ಪೂರ್ವಾಪೇಕ್ಷಿತಗಳು](../../../04-tools) -- [ಟೂಲ್ಗಳೊಂದಿಗೆ ಎಐ ಏಜೆಂಟ್ಗಳನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು](../../../04-tools) -- [ಟೂಲ್ ಕರೆದೊಯ್ಯುವಿಕೆ ಹೇಗೆ ಕೆಲಸಮಾಡುತ್ತದೆ](../../../04-tools) - - [ಟೂಲ್ ವ್ಯಾಖ್ಯಾನಗಳು](../../../04-tools) - - [ನಿರ್ಧಾರ ಕೈಗೊಳ್ಳುವುದು](../../../04-tools) - - [ಕಾರ್ಯ ನಿರ್ವಹಣೆ](../../../04-tools) - - [ಪ್ರತಿಕ್ರಿಯೆ ಪುಟ್‌ಪಡಿಸುವಿಕೆ](../../../04-tools) - - [ವಾಸ್ತುಶಿಲ್ಪ: ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಆಟೋ- ವೈಯರಿಂಗ್](../../../04-tools) -- [ಟೂಲ್ ಚೈನಿಂಗ್](../../../04-tools) -- [ಅ್ಯಪ್ಲಿಕೇಶನ್ ರನ್ ಮಾಡುವುದು](../../../04-tools) -- [ಅ್ಯಪ್ಲಿಕೇಶನ್ ಬಳಸುವುದು](../../../04-tools) - - [ಸರಳ ಟೂಲ್ ಬಳಕೆ ಪ್ರಯತ್ನಿಸಿ](../../../04-tools) - - [ಟೂಲ್ ಚೈನಿಂಗ್ ಪರೀಕ್ಷಿಸಿ](../../../04-tools) - - [ಸಂವಾದದ ಹರಿವು ನೋಡಿ](../../../04-tools) - - [ವಿವಿಧ ವಿನಂತಿಗಳೊಂದಿಗೆ ಪ್ರಯೋಗಮಾಡಿ](../../../04-tools) -- [ಪ್ರಮುಖ ಕಲ್ಪನೆಗಳು](../../../04-tools) - - [ReAct ಮಾದರಿ (ಯುಕ್ತಿ ಮತ್ತು ಕ್ರಮ)](../../../04-tools) - - [ಟೂಲ್ ವಿವರಣೆಗಳು ಪ್ರಮುಖವೆ](../../../04-tools) - - [ಸೆಷನ್ ನಿರ್ವಹಣೆ](../../../04-tools) - - [ದೋಷ ನಿರ್ವಹಣೆ](../../../04-tools) -- [ಲಭ್ಯವಿರುವ ಟೂಲ್ಗಳು](../../../04-tools) -- [ಟೂಲ್ ಆಧಾರಿತ ಏಜೆಂಟ್ ಅನ್ನು ಬಳಸಬೇಕಾಗುವ ಸಮಯ](../../../04-tools) -- [ಟೂಲ್ಗಳು ವಿರುದ್ಧ RAG](../../../04-tools) -- [ಮುಂದಿನ ಹಂತಗಳು](../../../04-tools) - -## ವೀಡಿಯೋ ವಾಕ್‌ಥ್ರೂ - -ಈ ಮODULE ಅನ್ನು ಆರಂಭಿಸುವುದರಲ್ಲಿ ಸಹಾಯವಾಗುವ ಲೈವ್ ಸೆಷನ್ ಅನ್ನು ನೋಡಿ: +# Module 04: AI ಏಜೆಂಟ్లు ಉಪಕರಣಗಳೊಂದಿಗೆ + +## ವಿಷಯಗಳ ಪಟ್ಟಿ + +- [ವೀಡಿಯೊ ಮಾರ್ಗದರ್ಶನ](#ವೀಡಿಯೊ-ಮಾರ್ಗದರ್ಶನ) +- [ನಿಮಗೆ ಏನು ಕಲಿಯಲಿದೆ](#ನಿಮಗೆ-ಏನು-ಕಲಿಯಲಿದೆ) +- [ಆವಶ್ಯಕತೆಗಳು](#ಆವಶ್ಯಕತೆಗಳು) +- [ಉಪಕರಣಗಳೊಂದಿಗೆ AI ಏಜೆಂಟ್ಸ್ ಅನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು](#ಉಪಕರಣಗಳೊಂದಿಗೆ-ai-ಏಜೆಂಟ್ಸ್-ಅನ್ನು-ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು) +- [ಉಪಕರಣ ಕರೆ ಹೇಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ](#ಉಪಕರಣ-ಕರೆ-ಹೇಗೆ-ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ) + - [ಉಪಕರಣ ವ್ಯಾಖ್ಯಾನಗಳು](#ಉಪಕರಣ-ವ್ಯಾಖ್ಯಾನಗಳು) + - [ ನಿರ್ಧಾರ ಕೈಗೊಳ್ಳುವುದು](#ನಿರ್ಧಾರ-ಕೈಗೊಳ್ಳುವುದು) + - [ನಿರ್ವಹಣೆ](#ನಿರ್ವಹಣೆ) + - [ಪ್ರತಿಕ್ರಿಯೆ ರಚನೆ](#ಪ್ರತಿಕ್ರಿಯೆ-ರಚನೆ) + - [ವಾಸ್ತುಶಿಲ್ಪ: ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಸ್ವಯಂ-ವೈರಿಂಗ್](#ವಾಸ್ತುಶಿಲ್ಪ-ಸ್ಪ್ರಿಂಗ್-ಬೂಟ್-ಸ್ವಯಂ-ವೈರಿಂಗ್) +- [ಉಪಕರಣ ಸರಪಳಿ](#ಉಪಕರಣ-ಸರಪಳಿ) +- [ಅಪ್ಲಿಕೇಶನ್ ಜೋಡಿಸಿ](#ಅಪ್ಲಿಕೇಶನ್-ಜೋಡಿಸಿ) +- [ಅಪ್ಲಿಕೇಶನ್ ಬಳಕೆ](#ಅಪ್ಲಿಕೇಶನ್-ಬಳಕೆ) + - [ಸರಳ ಉಪಕರಣ ಬಳಕೆ ಪ್ರಯತ್ನಿಸಿ](#ಸರಳ-ಉಪಕರಣ-ಬಳಕೆಯನ್ನು-ಪ್ರಯತ್ನಿಸಿ) + - [ಉಪಕರಣ ಸರಪಳಿಗಾಗಿ ಪರೀಕ್ಷಿಸಿ](#ಟೂಲ್-ಚೈನ್-ಪರೀಕ್ಷೆ) + - [ಸಂವಾದ ಹರಿವಿನಲ್ಲಿ ನೋಡಿ](#ಸಂಭಾಷಣಾ-ಹರಿವು-ನೋಡಿ) + - [ವಿಭಿನ್ನ ವಿನಂತಿಗಳೊಂದಿಗೆ ಅನುಭವಿಸಿ](#ವಿವಿಧ-ವಿನಂತಿಗಳನ್ನು-ಪ್ರಯತ್ನಿಸಿ) +- [ಮುಖ್ಯ концеп್ಗಳು](#ಮುಖ್ಯ-ಪರಿಕಲ್ಪನೆಗಳು) + - [ReAct ಪ್ಯಾಟರ್ನ್ (ತರ್ಕ ಮತ್ತು ಕ್ರಮ)](#react-ಮಾದರಿ-ತರ್ಕ-ಮತ್ತು-ಕಾರ್ಯ) + - [ಉಪಕರಣ ವಿವರಣೆಗಳು ಮುಖ್ಯಬಾಗಿವೆ](#ಉಪಕರಣ-ವಿವರಣೆಗಳು-ಮುಖ್ಯ) + - [ಸತ್ರ ನಿರ್ವಹಣೆ](#ಸೆಷನ್-ನಿರ್ವಹಣೆ) + - [ದೋಷ ಹ್ಯಾಂಡ್ಲಿಂಗ್](#ದೋಷ-ನಿರ್ವಹಣೆ) +- [ಲಭ್ಯವಿರುವ ಉಪಕರಣಗಳು](#ಲಭ್ಯವಿರುವ-ಉಪಕರಣಗಳು) +- [ಯಾಗಾಗಲೀ ಉಪಕರಣ-ಆಧಾರಿತ ಏಜೆಂಟ್ಸ್ ಬಳಕೆ ಮಾಡುವುದು](#ಉಪಕರಣ-ಆಧಾರಿತ-ಏಜೆಂಟ್‌ಗಳನ್ನು-ಯಾವಾಗ-ಬಳಸಬೇಕು) +- [ಉಪಕರಣಗಳು ಮತ್ತು RAG](#ಉಪಕರಣಗಳು-ಮತ್ತು-rag) +- [ಮುಂದಿನ ಹಂತಗಳು](#ಮುಂದಿನ-ಹಂತಗಳು) + +## ವೀಡಿಯೊ ಮಾರ್ಗದರ್ಶನ + +ಈ ಮಾಯಾಜಾಲವನ್ನು ಹೇಗೆ ಪ್ರಾರಂಭಿಸಬೇಕು ಎಂಬುದನ್ನು ವಿವರಣಾತ್ಮಕವಾಗಿ ತಿಳಿಸುವ ಈ ಲೈಕ್ ಸೆಷನ್ ನೋಡಿ: AI Agents with Tools and MCP - Live Session -## ನೀವು ಕಲಿಯುವುದು +## ನಿಮಗೆ ಏನು ಕಲಿಯಲಿದೆ -ಈವರೆಗೆ, ನೀವು ಎಐ ಜೊತೆ ಸಂವಾದ ನಡೆಸುವುದು, ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ಪರಿಣಾಮಕಾರಿಯಾಗಿ ರಚಿಸುವುದು ಮತ್ತು ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳಲ್ಲಿ ಪ್ರತಿಕ್ರಿಯೆಗಳನ್ನು ನೆಲೆಮಾಡುವುದು ಹೇಗೆ ಎನ್ನುವುದನ್ನು ಕಲಿಸಿದ್ದಾರೆ. ಆದರೆ ಇನ್ನೂ ಒಂದು ಮೂಲಭೂತ ಸೀಮಿತತೆ ಇದೆ: ಭಾಷಾ ಮಾದರಿಗಳು ಕೇವಲ ಪಠ್ಯವನ್ನು ರಚಿಸುವಷ್ಟೇ ಮಾಡಬಲ್ಲವು. ಅವು ಹವಾಮಾನವನ್ನು ಪರಿಶೀಲಿಸಲು, ಲెక్కಾಚಾರಗಳನ್ನು ಮಾಡಬಲ್ಲವುವು, ಡೇಟಾಬೇಸ್‌ಗಳನ್ನು ವಿಚಾರಿಸಬಹುದಿಲ್ಲ, ಅಥವಾ ಹೊರಗಿನ ವ್ಯವಸ್ಥೆಗಳೊಂದಿಗೆ ಸಂವಹನ ಮಾಡಲಾರವು. +ಈವರೆಗೂ, ನೀವು AIೊಂದಿಗೆ ಸಂಭಾಷಣೆಗಳನ್ನು ನಡೆಸುವಿಕೆ, ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ಪರಿಣಾಮಕಾರಿಯಾಗಿ ರಚಿಸುವಿಕೆ ಮತ್ತು ಉತ್ತರಗಳನ್ನು ಡಾಕ್ಯುಮೆಂಟ್ಸ್‌ನಲ್ಲಿ ಸ್ಥಾಪಿಸುವಿಕೆ ಏನಾಗುತ್ತದೆ ಎಂದು ಕಲಿತಿದ್ದೀರ. ಆದರೆ ಇನ್ನೂ ಒಂದು ಆಧಾರಭೂತ ಮಿತಿಯಿದೆ: ಭಾಷಾ ಮಾದರಿಗಳು ಪಠ್ಯವನ್ನು ಮಾತ್ರ ಉತ್ಪಾದಿಸಬಹುದು. ಅವು ಹವಾಮಾನ ಪರಿಶೀಲಿಸಲು, ಗಣನೆ ಮಾಡಲು, ಡೇಟಾಬೇಸ್‌ಗಳನ್ನ ವಿಚಾರಿಸುವುದಕ್ಕೆ ಅಥವಾ ಬಾಹ್ಯ ವ್ಯವಸ್ಥೆಗಳೊಂದಿಗೆ ಸಂವಹನ ಮಾಡಲು ಸಾಧ್ಯವಿಲ್ಲ. -ಟೂಲ್ಗಳು ಇದನ್ನು ಬದಲಾಯಿಸುತ್ತವೆ. ಮಾದರಿಗೂ ಕರೆಮಾಡಬಹುದಾದ ಕಾರ್ಯಗಳಿಗೆ ಪ್ರವೇಶ ನೀಡುವುದರಿಂದ, ನೀವು ಅವರನ್ನು ಪಠ್ಯ ರಚನಕಾರರಾಗಿ ಅಲ್ಲದೆ ಕ್ರಮ ಕೈಗೊಳ್ಳುವ ಏಜೆಂಟ್‌గా ಪರಿವರ್ತಿಸುತ್ತೀರಿ. ಮಾದರಿ ಯಾವಾಗ ಟೂಲ್ ಬೇಕಾಗುತ್ತದೆ, ಯಾವ ಟೂಲ್ ಬಳಸಬೇಕೆಂದು ಮತ್ತು ಯಾವ ಪ್ಯಾರಾಮೀಟರ್‌ಗಳನ್ನು ಪಾಸ್ ಮಾಡಬೇಕೆಂದು ತೀರ್ಮಾನಿಸುತ್ತದೆ. ನಿಮ್ಮ ಕೋಡ್ ಆ ಕಾರ್ಯವನ್ನು ನಿರ್ವಹಿಸಿ ಫಲಿತಾಂಶವನ್ನು ಹಿಂತಿರುಗಿಸುತ್ತದೆ. ಮಾದರಿ ಆ ಫಲಿತಾಂಶವನ್ನು ತನ್ನ ಪ್ರತಿಕ್ರಿಯೆಯಲ್ಲಿ ಸೇರಿಸುತ್ತದೆ. +ಉಪಕರಣಗಳು ಇದನ್ನು ಬದಲಿಸುತ್ತವೆ. ಮಾದರಿಗೆ ಕರೆ ಮಾಡಬಹುದಾದ ಕಾರ್ಯಕ್ಷಮತೆ ನೀಡುವುದರಿಂದ ಅವು ಪಠ್ಯ ಉತ್ಪಾದಕನಿಂದ ಕ್ರಮ ಕೈಗೊಳ್ಳುವ ಏಜೆಂಟ್ ಆಗಿ ಮಾರ್ಪಡುತ್ತವೆ. ಮಾದರಿ ಯಾವಾಗ ಉಪಕರಣ ಬೇಕು, ಯಾವ ಉಪಕರಣ ಬಳಸಬೇಕು ಮತ್ತು ಯಾವುದೇ ಪ್ಯಾರಾಮೀಟರ್‌ಗಳನ್ನು ನೀಡಬೇಕೆಂಬುದನ್ನು ನಿರ್ಧರಿಸುತ್ತದೆ. ನಿಮ್ಮ ಕೋಡ್ ಆ ಕಾರ್ಯಕ್ಷಮತೆಯನ್ನು ನಿರ್ವಹಿಸಿ ಫಲಿತಾಂಶವನ್ನು ಹಿಂತಿರುಗಿಸುತ್ತದೆ. ಮಾದರಿ ಆ ಫಲಿತಾಂಶವನ್ನು ತನ್ನ ಪ್ರತಿಕ್ರಿಯೆಗೆ ಸೇರಿಸುತ್ತದೆ. -## ಪೂರ್ವಾಪೇಕ್ಷಿತಗಳು +## ಆವಶ್ಯಕತೆಗಳು -- ಪೂರ್ಣಗೊಂಡಿದೆ: [ಮodule 01 - ಪರಿಚಯ](../01-introduction/README.md) (ಅಜೂರ್ ಓಪನ್ AI ಸಂಪನ್ಮೂಲಗಳು ನಿಯೋಜಿಸಲ್ಪಟ್ಟಿವೆ) -- ಶಿಫಾರಸುಪಡಿಸಿದ ಹಿಂದಿನ ಮODULEಗಳನ್ನು ಪೂರ್ಣಗೊಳಿಸಲಾಗಿದೆ (ಈ ಮODULE [ಮODULE 03 ನಿಂದ RAG ಕಲ್ಪನೆಗಳನ್ನು](../03-rag/README.md) ಟೂಲ್ಗಳು ವಿರುದ್ಧ RAG ಹೋಲಿಕೆಯಲ್ಲಿ ಉಲ್ಲೇಖಿಸುತ್ತದೆ) -- ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ `.env` ಫೈಲ್ ಇದೆ, ಅಜೂರ್ ಪ್ರಮಾಣಪತ್ರಗಳೊಂದಿಗೆ (`azd up` ಮೂಲಕ Module 01 ನಲ್ಲಿ ಸೃಷ್ಟಿಸಲಾಗಿದೆ) +- ಪೂರ್ಣಗೊಳಿಸಿರುವ [Module 01 - ಪರಿಚಯ](../01-introduction/README.md) (ಅಜೂರ್ ಓಪನ್AI ಸಂಪನ್ಮೂಲಗಳು ನಿಯೋಜಿಸಲಾಗಿದೆ) +- ಪೂರ್ವದ ಮಾಡ್ಯೂಲ್‌ಗಳನ್ನು ಪೂರ್ಣಗೊಳಿಸಿರಬೇಕು (ಈ ಮಾಡ್ಯೂಲ್ [RAG ಕಲ್ಪನೆಗಳನ್ನು Module 03](../03-rag/README.md) ನಿಯೋಜನೆ ಮಾಡುತ್ತದೆ) +- ರೂಟ್ ಡೈರೆಕ್ಟ್ರಿಯಲ್ಲಿ `.env` ಫೈಲ್ ಅಜೂರ್ ಪ್ರಮಾಣಪತ್ರಗಳೊಂದಿಗೆ (Module 01 ರಲ್ಲಿ `azd up` ರನ್ ಮಾಡುವ ಮೂಲಕ ಸೃಷ್ಟಿಸಲಾಗಿದೆ) -> **ಸೂಚನೆ:** ನೀವು Module 01 ಅನ್ನು ಪೂರ್ಣಗೊಳಿಸದಿದ್ದರೆ, ಮೊದಲು ಅಲ್ಲಿ ನಿಯೋಜನೆ ಸೂಚನಗಳನ್ನು ಅನುಸರಿಸಿ. +> **ಸೂಚನೆ:** ನೀವು Module 01 ಮುಗಿಸದಿದ್ದರೆ, ಮೊದಲಿಗೆ ನಿಯೋಜನೆ ಸೂಚನೆಗಳನ್ನು ಅನುಸರಿಸಿ. -## ಟೂಲ್ಗಳೊಂದಿಗೆ ಎಐ ಏಜೆಂಟ್ಗಳನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು +## ಉಪಕರಣಗಳೊಂದಿಗೆ AI ಏಜೆಂಟ್ಸ್ ಅನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು -> **📝 ಸೂಚನೆ:** ಈ ಮODULEನಲ್ಲಿ "ಏಜೆಂಟ್" ಪದವು ಟೂಲ್-ಕರೆಗೊಳ್ಳುವ ಸಾಮರ್ಥ್ಯಗಳಿಂದ ಸುಧಾರಿಸಿದ ಎಐ ಸಹಾಯಕರಿಗೆ ಸಂಬಂಧಿಸಿದೆ. ಇದು [ಮODULE 05: MCP](../05-mcp/README.md)ನಲ್ಲಿ ಚರ್ಚಿಸುವ **Agentic AI** ಮಾದರಿಗಳಿಂದ (ಸ್ವತಂತ್ರ ಏಜೆಂಟ್ಗಳು ಯೋಜನೆ, ಸ್ಮರಣೆ, ಮತ್ತು ಬಹು ಹಂತದ ಯುಕ್ತಿಯೊಂದಿಗೆ) ಭಿನ್ನವಾಗಿದೆ. +> **📝 ಟಿಪ್ಪಣಿ:** ಈ ಮಾಡ್ಯೂಲ್‌ನಲ್ಲಿ "ಏಜೆಂಟ್ಸ್" ಪದ AI ಸಹಾಯಕರನ್ನು ಸೂಚಿಸುತ್ತದೆ, ಉಪಕರಣ-ಕಾಲ್ ಮಾಡುವ ಸಾಮರ್ಥ್ಯಗಳೊಂದಿಗೆ ವೃದ್ಧಿಪಡಿಸಲಾಗಿದೆ. ಇದು [Module 05: MCP](../05-mcp/README.md) ನಲ್ಲಿ ನಾವು ಕವರ್ ಮಾಡುವ **Agentic AI** ಮಾದರಿಗಳು (ಸ್ವಯಂಚಾಲಿತ ಏಜೆಂಟ್ಸ್, ಯೋಜನೆ, ಸ್ಮರಣೆ ಮತ್ತು ಬಹು-ಹಂತ ರೀಸನಿಂಗ್) ಭಿನ್ನವಾಗಿದೆ. -ಟೂಲ್ಗಳು ಇಲ್ಲದಿದ್ದರೆ, ಭಾಷಾ ಮಾದರಿ ತನ್ನ ತರಬೇತಿ ದತ್ತಾಂಶದಿಂದ ಮಾತ್ರ ಪಠ್ಯವನ್ನು ರಚಿಸಬಲ್ಲದು. ಹವಾಮಾನ ಯಾವುವು ಎಂದು ಕೇಳಿದರೆ, ಅದು ಊಹಿಸಬೇಕಾಗುತ್ತದೆ. ಟೂಲ್ಗಳು ನೀಡಿದರೆ, ಅದು ಹವಾಮಾನ API ಕರೆಗೊಳ್ಳಬಹುದು, ಲెక్కಾಚಾರಗಳನ್ನು ನಿರ್ವಹಿಸಬಹುದು ಅಥವಾ ಡೇಟಾಬೇಸ್ ಅನ್ನು ವಿಚಾರಿಸಬಹುದು — ನಂತರ ಆ ನಿಜವಾದ ಫಲಿತಾಂಶಗಳನ್ನು ತನ್ನ ಪ್ರತಿಕ್ರಿಯೆಯಲ್ಲಿ ಜೋಡಿಸುತ್ತದೆ. +ಉಪಕರಣಗಳಿಲ್ಲದೆ, ಭಾಷಾ ಮಾದರಿ ತನ್ನ ತರಬೇತಿ ಡೇಟಾದಿಂದ ಮಾತ್ರ ಪಠ್ಯವನ್ನು ಉತ್ಪಾದಿಸಬಹುದು. ನಿರ್ಧಿಷ್ಟ ಹವಾಮಾನವನ್ನು ಕೇಳಿದರೆ, ಅದು ಊಹೆ ಮಾಡಬೇಕು. ಉಪಕರಣಗಳನ್ನು ನೀಡಿದರೆ, ಅದು ಹವಾಮಾನ API ಅನ್ನು ಕರೆ ಮಾಡಬಹುದು, ಗಣನೆ ಮಾಡಿ ಅಥವಾ ಡೇಟಾಬೇಸ್ ವಿಚಾರಿಸಬಹುದು — ನಂತರ ಆ ವಾಸ್ತವಿಕ ಫಲಿತಾಂಶಗಳನ್ನು ತನ್ನ ಉತ್ತರದಲ್ಲಿ ಬೆರೆಸಿಕೊಳ್ಳಬಹುದು. -Without Tools vs With Tools +ಉಪಕರಣಗಳಿಲ್ಲದೆ vs ಉಪಕರಣಗಳೊಂದಿಗೆ -*ಟೂಲ್ಗಳಿಲ್ಲದೆ ಮಾದರಿ ಕೇವಲ ಊಹೆ ಮಾಡಬಹುದು — ಟೂಲ್ಗಳೊಂದಿಗೆ ಅದು APIs ಅನ್ನು ಕರೆ ಮಾಡಬಹುದು, ಲెక్కಾಚಾರಗಳನ್ನು ನಡೆಸಬಹುದು ಮತ್ತು ನಿಜಕಾಲದ ಡೇಟಾ ಹಿಂತಿರುಗಿಸಬಹುದು.* +*ಉಪಕರಣವಿಲ್ಲದೆ ಮಾದರಿ ಊಹಿಸಲು ಮಾತ್ರ ಸಾಧ್ಯ — ಉಪಕರಣಗಳೊಂದಿಗೆ ಅದು APIs ಅನ್ನು ಕರೆ ಮಾಡಬಹುದು, ಗಣನೆಗಳು ನಡೆಸಬಹುದು ಮತ್ತು ನೈಜ-ಸಮಯ ದತ್ತಾಂಶ ಹಿಂತಿರುಗಿಸಬಹುದು.* -ಟೂಲ್ಗಳೊಂದಿಗೆ AI ಏಜೆಂಟ್ **ಯುಕ್ತಿ ಮತ್ತು ಕ್ರಮ (ReAct)** ಮಾದರಿಯನ್ನು ಅನುಸರಿಸುತ್ತದೆ. ಮಾದರಿ ಕೇವಲ ಪ್ರತಿಕ್ರಿಯಿಸುವುದಿಲ್ಲ — ಇದು ಬೇಕಾದುದನ್ನು ಯೋಚಿಸುತ್ತದೆ, ಟೂಲ್ ಅನ್ನು ಕರೆಮಾಡಿ ಆಕ್ರಮಣ ವಾಗಿದೆ, ಫಲಿತಾಂಶವನ್ನು ಪರಿಶೀಲಿಸುತ್ತದೆ, ನಂತರ ಮತ್ತೊಮ್ಮೆ ಕ್ರಮ ಕೈಗೊಳ್ಳಬೇಕೆ, ಅಂತಿಮ ಉತ್ತರ ಕೊಡುವುದಕ್ಕೆ ಯೋಚಿಸುತ್ತದೆ: +ಉಪಕರಣಗಳೊಂದಿಗೆ AI ಏಜೆಂಟ್ ಒಂದು **ಅವಲೋಕನ ಮತ್ತು ಕ್ರಮ (ReAct)** ಮಾದರಿಯನ್ನು ಅನುಸರಿಸುತ್ತದೆ. ಮಾದರಿ ಕೇವಲ ಪ್ರತಿಕ್ರಿಯಿಸುವುದಿಲ್ಲ — ಅದು ಏನು ಬೇಕು ಎಂದು ಯೋಚಿಸುತ್ತದೆ, ಉಪಕರಣವನ್ನು ಕರೆಮಾಡಿ ಕ್ರಮವನ್ನು ಕೈಗೊಳ್ಳುತ್ತದೆ, ಫಲಿತಾಂಶವನ್ನು ಗಮನಿಸುತ್ತಿದೆ ಮತ್ತು ಮತ್ತೆ ಕ್ರಮ ಕೈಗೊಳ್ಳಬೇಕೆಂಬುದನ್ನು ಅಥವಾ ಅಂತಿಮ ಉತ್ತರವನ್ನು ನೀಡಬೇಕೆಂಬುದನ್ನು ನಿರ್ಧರಿಸುತ್ತದೆ: -1. **ಯುಕ್ತಿ** — ಬಳಕೆದಾರನ ಪ್ರಶ್ನೆಯನ್ನು ವಿಶ್ಲೇಷಿಸಿ ಮತ್ತು ಬೇಕಾದ ಮಾಹಿತಿಯನ್ನು ನಿರ್ಧರಿಸಿ -2. **ಕ್ರಮ** — ಸರಿಯಾದ ಟೂಲ್ ಆಯ್ಕೆ ಮಾಡಿ, ಸರಿಯಾದ ಪ್ಯಾರಾಮೀಟರ್‌ಗಳನ್ನು ರಚಿಸಿ, ಅದನ್ನು ಕರೆಮಾಡಿ -3. **ನೋಟ** — ಟೂಲ್ ನ ಹೊರಹೊಮ್ಮುವಿಕೆಯನ್ನು ಸ್ವೀಕರಿಸಿ ಮತ್ತು ಫಲಿತಾಂಶವನ್ನು ವಿಮರ್ಶಿಸಿ -4. **ಪುನರಾವರ್ತನೆ ಅಥವಾ ಪ್ರತಿಕ್ರಿಯೆ** — ಹೆಚ್ಚು ಡೇಟಾ ಬೇಕಾದರೆ ಲೂಪ್ ಮಾಡಿ; ಇಲ್ಲದಿದ್ದರೆ ಸಹಜ ಭಾಷೆಯ ಉತ್ತರ ರಚಿಸಿ +1. **ತರ್ಕಮಾಡೋಣ** — ಬಳಕೆದಾರನ ಪ್ರಶ್ನೆಯನ್ನು ವಿಶ್ಲೇಷಿಸಿ ಯಾವ ಮಾಹಿತಿ ಬೇಕೆಂದು ನಿರ್ಧರಿಸುವುದು +2. **ಕ್ರಮ ತೆಗೆದುಕೊಳ್ಳಿ** — ಸರಿಯಾದ ಉಪಕರಣವನ್ನು ಆಯ್ಕೆಮಾಡಿ, ಸರಿಯಾದ ಪ್ಯಾರಾಮೀಟರ್‌ಗಳನ್ನು ರಚಿಸಿ ಮತ್ತು ಅದನ್ನು ಕರೆಮಾಡುವುದು +3. **ನೋಟಮಾಡಿ** — ಉಪಕರಣದ ಫಲಿತಾಂಶವನ್ನು ಪಡೆದು ಪರಿಶೀಲಿಸುವುದು +4. **ಮರುಕಳುಹಿಸಿ ಅಥವಾ ಪ್ರತಿಕ್ರಿಯಿಸಿ** — ಇನ್ನಷ್ಟು ಡೇಟಾ ಬೇಕಾದರೆ ಪುನರಾವೃತ್ತಿ ಮಾಡುವುದು; ಇಲ್ಲದಿದ್ದರೆ ಸರಳ ಉತ್ತರ ರಚಿಸುವುದು -ReAct Pattern +ReAct ಮಾದರಿ -*ReAct ಚಕ್ರ — ಏಜೆಂಟ್ ಏನು ಮಾಡಬೇಕೆಂದಿದೆಂದು ಯುಕ್ತಿ ಮಾಡುವುದು, ಟೂಲ್ ಕರೆಮಾಡಿ ಕ್ರಮ ಕೈಗೊಳ್ಳುವುದು, ಫಲಿತಾಂಶವನ್ನು ನೋಡಿ, ಆಗ ತನಕ ಲೂಪ್ ಮಾಡುವುದು ಮತ್ತು ಅಂತಿಮ ಉತ್ತರವನ್ನು ಒದಗಿಸುವುದು.* +*ReAct ಚಕ್ರ — ಏಜೆಂಟ್ ಏನು ಮಾಡಬೇಕೆಂದು ತರ್ಕಮಾಡುತ್ತದೆ, ಉಪಕರಣವನ್ನು ಕರೆಮಾಡಿ ಕ್ರಮ ತೆಗೆದುಕೊಳ್ಳುತ್ತದೆ, ಫಲಿತಾಂಶವನ್ನು ಗಮನಿಸಿ ಬಂದಿಲ್ಲಿಗೆ ಅಂತಿಮ ಉತ್ತರವನ್ನು ನೀಡುವವರೆಗೆ ಪುನರಾವೃತ್ತಿ ಮಾಡುತ್ತದೆ.* -ಇದು ಸ್ವಯಂಚಾಲಿತವಾಗಿದು. ನೀವು ಟೂಲ್ಗಳನ್ನು ಮತ್ತು ಅವುಗಳ ವಿವರಣೆಗಳನ್ನು ನಿರ್ಧರಿಸುತ್ತೀರಿ. ಮಾದರಿ ಯಾವಾಗ ಮತ್ತು ಹೇಗೆ ಬಳಸಬೇಕೆಂಬ ನಿರ್ಧಾರವನ್ನು ಕೈಗೊಳ್ಳುತ್ತದೆ. +ಇದು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ನಡೆಯುತ್ತದೆ. ನೀವು ಉಪಕರಣಗಳನ್ನು ಮತ್ತು ಅವುಗಳ ವಿವರಣೆಗಳನ್ನುนิರ್ಧರಿಸುತ್ತೀರಿ. ಮಾದರಿ ಅವುಗಳನ್ನು ಬಳಸಲು ಯಾವಾಗ ಮತ್ತು ಹೇಗೆ ತಿಳಿದುಕೊಳ್ಳುವ ನಿರ್ಧಾರ ಮಾಡುತ್ತದೆ. -## ಟೂಲ್ ಕರೆದೊಯ್ಯುವಿಕೆ ಹೇಗೆ ಕೆಲಸಮಾಡುತ್ತದೆ +## ಉಪಕರಣ ಕರೆ ಹೇಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ -### ಟೂಲ್ ವ್ಯಾಖ್ಯಾನಗಳು +### ಉಪಕರಣ ವ್ಯಾಖ್ಯಾನಗಳು [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -ನೀವು ಸ್ಪಷ್ಟ ವಿವರಣೆಗಳು ಮತ್ತು 参数ವಿವರಣೆಗಳೊಂದಿಗೆ ಕಾರ್ಯಗಳನ್ನು ವ್ಯಾಖ್ಯಾನಿಸುತ್ತೀರಿ. ಮಾದರಿ ಈ ವಿವರಣೆಗಳನ್ನು ತನ್ನ ಸಿಸ್ಟಮ್ ಪ್ರಾಂಪ್ಟ್‌ನಲ್ಲಿ ನೋಡಿ ಪ್ರತಿ ಟೂಲ್ಗೆ ಏನು ಕೆಲಸ ಇದೆ ಎಂದು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುತ್ತದೆ. +ನೀವು ಸ್ಪಷ್ಟ ವಿವರಣೆಗಳು ಮತ್ತು ಪ್ಯಾರಾಮೀಟರ್ ವಿವರಣೆಗಳೊಂದಿಗೆ ಕಾರ್ಯಗಳನ್ನು ವ್ಯಾಖ್ಯಾನಿಸುತ್ತೀರಿ. ಮಾದರಿ ತನ್ನ ಸಿಸ್ಟಮ್ ಪ್ರಾಂಪ್ಟ್‌ನಲ್ಲಿ ಈ ವಿವರಣೆಗಳನ್ನು ನೋಡಿ ಪ್ರತಿಯೊಂದು ಉಪಕರಣ ಏನು ಮಾಡುತ್ತದೆ ಎಂದು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುತ್ತದೆ. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // ನಿಮ್ಮ ಹವಾಮಾನ ಹುಡುಕುವ ಲಾಜಿಕ್ + // ನಿಮ್ಮ ಹವಾಮಾನ ಹುಡುಕಾಟ ತರ್ಕ return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,293 +96,293 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Spring Boot ಮೂಲಕ ಸಹಾಯಕನು ಸ್ವತಃ ತರುವಾಯ ಮಾಡಲಾಗಿದೆ: -// - ChatModel ಬಿನ್ -// - @Component ವರ್ಗಗಳಲ್ಲಿನ ಎಲ್ಲಾ @Tool ವಿಧಾನಗಳು -// - ಸೆಷನ್ ನಿರ್ವಹಣೆಯಿಗಾಗಿ ChatMemoryProvider +// ಸಹಾಯಕನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ Spring Boot ಮೂಲಕ ಸಂಪರ್ಕಿಸಲಾಗಿದೆ: +// - ChatModel ಬೀನ್ +// - @Component ವರ್ಗಗಳಿಂದ ಎಲ್ಲಾ @Tool ಮೆಥೋಡ್‌ಗಳು +// - ಸೆಷನ್ ನಿರ್ವಹಣೆಗೆ ChatMemoryProvider ``` -ಕೆಳಗಿನ ಚಿತ್ರಣವು ಪ್ರತಿ ಅನೋಟೇಶನ್ ಅನ್ನು ವಿಶ್ಲೇಷಿಸುತ್ತದೆ ಮತ್ತು ಯಾವ ಭಾಗ ಎಐಗೆ ಟೂಲನ್ನು ಕರೆಮಾಡಬೇಕೆಂದು ಮತ್ತು ಯಾವವಾದಿ ಪ್ಯಾರಾಮೀಟರ್ ಗಳನ್ನು ಪಾಸ್ ಮಾಡಬೇಕೆಂದು ತಿಳಿಸುತ್ತದೆ: +ಕೆಳಗಿನ ಚಿತ್ತರಣದಲ್ಲಿ ಪ್ರತಿ ಅಂಕಗಳನ್ನು ವಿಭಜಿಸಲಾಗಿದ್ದು, ಪ್ರತಿಯೊಂದು ಭಾಗ AIಗೆ ಉಪಕರಣವನ್ನು ಯಾವಾಗ ಕರೆ ಮಾಡಬೇಕು ಮತ್ತು ಯಾವ аргументы ಇಡುವುದೇ ಎಂಬುದನ್ನು ತಿಳಿಸುವಂತೆ ಸಹಾಯ ಮಾಡುತ್ತದೆ: -Anatomy of Tool Definitions +ಉಪಕರಣ ವ್ಯಾಖ್ಯಾನಗಳ ರಚನೆ -*ಟೂಲ್ ವ್ಯಾಖ್ಯಾನದ ರಚನೆ — @Tool ಎಂಬುದು ಎಐಗೆ ಇದನ್ನು ಯಾವಾಗ ಬಳಸಬೇಕು ಎಂದು ತಿಳಿಸುತ್ತದೆ, @P ಪ್ರತಿ 参数ವಿವರಣೆ ನೀಡುತ್ತದೆ, ಮತ್ತು @AiService ಪ್ರಾರಂಭಾವಧಿಯಲ್ಲಿ ಎಲ್ಲವನ್ನೂ ಸಂಪರ್ಕಿಸುತ್ತದೆ.* +*ಉಪಕರಣ ವ್ಯಾಖ್ಯಾನದ ರಚನೆ — @Tool ಉಪಕರಣವನ್ನು ಯಾವಾಗ ಬಳಸಬೇಕು ಎಂಬುದನ್ನು AIಗೆ ಹೇಳುತ್ತದೆ, @P ಪ್ರತಿ ಪ್ಯಾರಾಮೀಟರ್ ಅನ್ನು ವಿವರಿಸುತ್ತದೆ, ಮತ್ತು @AiService ಪ್ರಾರಂಭದಲ್ಲಿ ಎಲ್ಲವನ್ನೂ ಸಂಧಿಸುತ್ತದೆ.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ಚಾಟ್ ಜೊತೆ ಪ್ರಯತ್ನಿಸಿ:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ದೇವರ ನೋಡಿ: -> - "ನನಗೆ ನಕಲಿ ಡೇಟಾ ಬದಲು ನಿಜವಾದ OpenWeatherMap ಹವಾಮಾನ API ಅನ್ನು ಏನು ಸೇರಿಸಬೇಕು?" -> - "ಎಐಗೆ ಸರಿಯಾಗಿ ಬಳಸಲು ಸಹಾಯ ಮಾಡುವ ಉತ್ತಮ ಟೂಲ್ ವಿವರಣೆ ಏನು?" -> - "ಟೂಲ್ ಅನುಷ್ಠಾನದಲ್ಲಿ API ದೋಷಗಳು ಮತ್ತು ರೇಟ್ ಲಿಮಿಟ್‌ಗಳನ್ನು ಹೇಗೆ ನಿರ್ವಹಿಸಬೇಕು?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ಚಾಟ್‌ನೊಂದಿಗೆ ಪ್ರಯತ್ನಿಸಿ:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ತೆರೆದೂ ಕೇಳಿ: +> - "ಪ್ರಾಮಾಣಿಕ ಡೇಟಾ ಬದಲು mock data ನಂತರ OpenWeatherMap ನಂತಹ ನಿಜವಾದ ಹವಾಮಾನ API ಅನ್ನು ಹೇಗೆ ಇಂಟಿಗ್ರೇಟ್ ಮಾಡಲಿ?" +> - "AI ಉಪಕರಣವನ್ನು ಸರಿಯಾಗಿ ಬಳಸಲು ಸಹಾಯ ಮಾಡುವ ಉತ್ತಮ ಉಪಕರಣ ವಿವರಣೆ ಹೇಗಿರಬೇಕು?" +> - "API错误和速率限制处理要怎么实现?" ### ನಿರ್ಧಾರ ಕೈಗೊಳ್ಳುವುದು -ಬಳಕೆದಾರನು "ಸ್ಯಾಟಲ್‌ನಲ್ಲಿ ಹವಾಮಾನ ಹೇಗಿದೆ?" ಎಂದು ಕೇಳಿದಾಗ, ಮಾದರಿ ಯಾದೃಚ್ಛಿಕವಾಗಿ ಟೂಲನ್ನು ಆಯ್ಕೆಮಾಡುವುದಿಲ್ಲ. ಅದು ಬಳಕೆದಾರರ ಉದ್ದೇಶವನ್ನು ಪ್ರತಿ ಟೂಲ್ ವಿವರಣೆಯೊಂದಿಗೆ ಹೋಲಿಸಿ, ಪ್ರಸ್ತುತತೆಯನ್ನು ಅಸತ್ತೂಡುತ್ತದೆ, ಮತ್ತು ಉಚಿತವಾದ ಯಥಾರ್ಥವನ್ನು ಆಯ್ಕೆಮಾಡುತ್ತದೆ. ನಂತರ ಅದು ಸರಿಯಾದ ಪ್ಯಾರಾಮೀಟರ್‌ಗಳೊಂದಿಗೆ ಸಾಂರಚನಾತ್ಮಕ ಕಾರ್ಯಕರೆಗೊಳ್ಳುವಿಕೆಯನ್ನು ತಯಾರಿಸುತ್ತದೆ — ಈ ಸಂದರ್ಭದಲ್ಲಿ, `location` ಅನ್ನು `"Seattle"` ಎಂದು ಸೆಟ್ ಮಾಡುತ್ತದೆ. +ಬಳಕೆದಾರ "ಸಿಯಾಟಲ್‌ನಲ್ಲಿ ಹವಾಮಾನ ಏನೆಂದು?" ಎಂದು ಕೇಳಿದಾಗ, ಮಾದರಿ ಯಾದೃಚ್ಛಿಕವಾಗಿ ಉಪಕರಣ ಆಯ್ಕೆಮಾಡುವುದಿಲ್ಲ. ಅದು ಬಳಕೆದಾರದ ಉದ್ದೇಶವನ್ನು ಪ್ರತಿ ಉಪಕರಣ ವಿವರಣೆಯೊಂದಿಗೆ ಹೋಲಿಕೆ ಮಾಡುತ್ತದೆ, ಪ್ರತ್ಯೇಕವಾಗಿ ಪ್ರಾಸಕ್ತಿಗಾಗಿ ಅಂಕ ಹಚ್ಚುತ್ತದೆ ಮತ್ತು ಉತ್ತಮ ಹೊಂದಿಕೆಯನ್ನು ಆಯ್ಕೆಮಾಡುತ್ತದೆ. ನಂತರ ಸರಿಯಾದ ಪ್ಯಾರಾಮೀಟರ್‌ಗಳೊಂದಿಗೆ ರಚಿತ ಕಾರ್ಯಕ್ಷಮತೆ ಕರೆ ರಚಿಸುತ್ತದೆ — ಈ ದೃಷ್ಠಾಂತದಲ್ಲಿ `location` ಅನ್ನು `"Seattle"` ಎಂದು ನಿಗದಿಪಡಿಸುತ್ತದೆ. -ಯಾವುದೇ ಟೂಲ್ ಬಳಕೆದಾರರ ವಿನಂತಿಗೆ ಸರಿಹೊಬ್ಬದಿದ್ದರೆ, ಮಾದರಿ ತನ್ನದೇ ಜ್ಞಾನದಿಂದ ಉತ್ತರಿಸುತ್ತದೆ. ಹಲವಾರು ಟೂಲ್ಗಳು ಹೊಂದಿದ್ದರೆ, ಅತ್ಯಂತ ಸ್ಪಷ್ಟವಾದುದನ್ನು ಆಯ್ಕೆಮಾಡುತ್ತದೆ. +ಯಾವುದೇ ಉಪಕರಣ ಬಳಕೆದಾರನ ವಿನಂತಿಗೆ ಹೊಂದಿಕೆಯಾಗದಿದ್ದರೆ, ಮಾದರಿ ತನ್ನ ಜ್ಞಾನದಿಂದ ಉತ್ತರ ನೀಡುತ್ತದೆ. ಬಹುಮಾನ ಉಪಕರಣಗಳು ಹೊಂದಿಕೆಯಾಗಿದ್ದರೆ, ಮಾದರಿ ಅತ್ಯಂತ ವಿಶಿಷ್ಟವಾದುದನ್ನು ಆಯ್ಕೆಮಾಡುತ್ತದೆ. -How the AI Decides Which Tool to Use +AI ಯಾವ ಉಪಕರಣವನ್ನು ಬಳಸಬೇಕು ಎಂದು ನಿರ್ಧರಿಸುವುದು -*ಮಾದರಿ ಪ್ರತಿ ಲಭ್ಯವಿರುವ ಟೂಲ್ನ್ನು ಬಳಕೆದಾರರ ಉದ್ದೇಶದ ವಿರುದ್ಧ ಮೌಲ್ಯಾಂಕನ ಮಾಡಿ ಉತ್ತಮದನ್ನು ಆಯ್ಕೆಮಾಡುತ್ತದೆ — ಆದ್ದರಿಂದ ಸ್ಪಷ್ಟ, ಖಚಿತ ಟೂಲ್ ವಿವರಣೆಗಳನ್ನು ಬರೆಯುವಿಕೆ ಎಷ್ಟು ಮುಖ್ಯವೋ ಅುತ್ತದೆ.* +*ಮಾದರಿ ಪ್ರತಿ ಲಭ್ಯವಿರುವ ಉಪಕರಣವನ್ನು ಬಳಕೆದಾರದ ಉದ್ದೇಶಕ್ಕೆ ಮೌಲ್ಯಮಾಪನ ಮಾಡಿ ಅತ್ಯುತ್ತಮ ಹೊಂದಿಕೆಯನ್ನು ಆಯ್ಕೆಮಾಡುತ್ತದೆ — ಇದಕ್ಕಾಗಿ ಸ್ಪಷ್ಟ, ನಿರ್ದಿಷ್ಟ ಉಪಕರಣ ವಿವರಣೆಗಳನ್ನು ಬರೆಯುವುದು ಮುಖ್ಯ.* -### ಕಾರ್ಯ ನಿರ್ವಹಣೆ +### ನಿರ್ವಹಣೆ [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -ಸ್ಕೃತಿ ಬೂಟ್ ಆಟೋ- ಬೈಯರ್ ಡಿಕ್ಲೇರೇಟಿವ್ `@AiService` ಇಂಟರ್ಫೇಸ್ನನ್ನು ಎಲ್ಲಾ ನೋಂದಾಯಿಸಲಾದ ಟೂಲ್ಗಳಿಗೆ ತಾನೆ ಸಂಪರ್ಕಿಸುತ್ತದೆ, ಮತ್ತು LangChain4j ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಟೂಲ್ ಕರೆಗಳನ್ನು ಕಾರ್ಯಗತಗೊಳಿಸುತ್ತದೆ. ಹಿಂದೆ, ಬಳಕೆದಾರರ ಸಹಜ ಭಾಷೆಯ ಪ್ರಶ್ನೆಯಿಂದ ಆರಂಭವಾಗಿ ಸಹಜ ಭಾಷೆಯ ಉತ್ತರಕ್ಕೆ ಹದಿನಾರು ಹಂತಗಳ ಮೂಲಕ ಸಂಪೂರ್ಣ ಟೂಲ್ ಕರೆ ಹರಿವು ಚಾಲನೆಯುತ: +Spring Boot `@AiService` ಡಿಕ್ಲೇಟಿವ್ ಇಂಟರ್ಫೇಸ್ನನ್ನು ಎಲ್ಲಾ ನೋಂದಾಯಿತ ಉಪಕರಣಗಳೊಂದಿಗೆ ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಜೋಡಿಸಿದೆ, ಮತ್ತು LangChain4j ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಉಪಕರಣ ಕರೆಗಳನ್ನು ನಿರ್ವಹಿಸುತ್ತದೆ. ಹಿಂಬ್ಯಾಂಕ್‌ನಲ್ಲಿ, ಸಂಪೂರ್ಣ ಉಪಕರಣ ಕರೆ ಆರು ಹಂತಗಳಲ್ಲಿ ಸಾಗುತ್ತದೆ — ಬಳಕೆದಾರನ ನೈಸರ್ಗಿಕ ಭಾಷೆ ಪ್ರಶ್ನೆಯಿಂದ ಹಿಂದಿರುಗಿ ನೈಸರ್ಗಿಕ ಭಾಷೆ ಉತ್ತರಕ್ಕೆ: -Tool Calling Flow +ಉಪಕರಣ ಕರೆ ಹರಿವು -*ಎಂತು-ಎಂತು ಹರಿವು — ಬಳಕೆದಾರನು ಪ್ರಶ್ನೆಯನ್ನು ಕೇಳುತ್ತಾನೆ, ಮಾದರಿ ಟೂಲ್ ಆಯ್ಕೆ ಮಾಡುತ್ತದೆ, LangChain4j ಅದನ್ನು ಕಾರ್ಯಗತಗೊಳಿಸುತ್ತದೆ, ಮತ್ತು ಮಾದರಿ ಫಲಿತಾಂಶವನ್ನು ಸಹಜ ಪ್ರತಿಕ್ರಿಯೆಯಲ್ಲಿ ಹಾಕುತ್ತದೆ.* +*ಎಂಬರು ಎಲ್ಲ ಹಂತಗಳ ಹರಿವು — ಬಳಕೆದಾರನು ಪ್ರಶ್ನೆ ಕೇಳುತ್ತಾನೆ, ಮಾದರಿ ಉಪಕರಣ ಆಯ್ಕೆ ಮಾಡುತ್ತದೆ, LangChain4j ಅದನ್ನು ಕಾರ್ಯಗತಗೊಳಿಸುತ್ತದೆ ಮತ್ತು ಫಲಿತಾಂಶವನ್ನು ನೈಸರ್ಗಿಕ ಉತ್ತರದಲ್ಲಿ ಸೇರಿಸುತ್ತದೆ.* -ನೀವು Module 00 ನಲ್ಲಿ [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ದೋಡಿಸಿದ್ದರೆ, ಈ ಮಾದರಿಯನ್ನು ನೀವು ಈಗಾಗಲೇ ನೋಡಿದ್ದೀರಿ — `Calculator` ಟೂಲ್ಗಳನ್ನು ಕೂಡ ಅಷ್ಟೇ ವಿಧವಾಗಿ ಕರೆಸಲಾಗಿದೆ. ಕೆಳಗಿನ ಸೀಕ್ವೆನ್ಸ್ ಚಿತ್ರಣವು ಆ ಡೆಮೊನಲ್ಲಿ ಆದ್ದನ್ನೆಲ್ಲ ವಿವರಿಸುತ್ತದೆ: +ಹಿಂಬ್ಯಾಂಕ್‌ನಲ್ಲಿ, `AiServices` ಯಾವುದೇ ಉಪಕರಣಕ್ಕೆ ಅದೇ ಉಪಕರಣ-ಕಾಲ್ ಲೂಪನ್ನು ನಿರ್ವಹಿಸುತ್ತದೆ — ಇಲ್ಲಿ ಸರಳ `Calculator` ಉಪಕರಣ ಉದಾಹರಣೆಯಾಗಿ ತೋರಿಸಲಾಗಿದೆ. ಕೆಳಗಿನ ಕ್ರಮ ಚಿತ್ತರಣாவில் ಖಚಿತವಾಗಿ ದಿಟಿಸಲಾಗಿದೆ: -Tool Calling Sequence Diagram +ಉಪಕರಣ ಕರೆ ಕ್ರಮ ಚಾರ್ಟ್ -*ಕ್ವಿಕ್ ಸ್ಟಾರ್ಟ್ ಡೆಮೊನಿಂದ ಟೂಲ್-ಕರೆದೊಯ್ಯುವ ಲೂಪ್ — `AiServices` ನಿಮ್ಮ ಸಂದೇಶ ಮತ್ತು ಟೂಲ್ ಸ್ಕೀಮಾಗಳನ್ನು LLM ಗೆ ಕಳುಹಿಸುತ್ತದೆ, LLM `add(42, 58)` ಎಂಬ ಕಾರ್ಯಕರೆಗೆ ಉತ್ತರಿಸುತ್ತದೆ, LangChain4j ಸ್ಥಳೀಯವಾಗಿ `Calculator` ಸತ್ಯಾನ್ವಯಿಸುವಿಕೆ ನಡೆಸುತ್ತದೆ, ಮತ್ತು ಫಲಿತಾಂಶವನ್ನು ಅಂತಿಮ ಉತ್ತರಕ್ಕೆ ಹಿಂತಿರುಗಿಸುತ್ತದೆ.* +*ಉಪಕರಣ ಕರೆ ಲೂಪ್ — `AiServices` ನಿಮ್ಮ ಸಂದೇಶ ಮತ್ತು ಉಪಕರಣ ಸ್ಕೀಮಾಗಳನ್ನು LLM ಗೆ ಕಳುಹಿಸುತ್ತದೆ, LLM `add(42, 58)` ಎಂಬ ಕಾರ್ಯ ಕರೆಯನ್ನು ಮರುಪ್ರತಿಸುತೆ, LangChain4j ಸ್ಥಳೀಯವಾಗಿ `Calculator` ಮೆಥಡ್ ಅನ್ನು ಕಾರ್ಯಗತಗೊಳಿಸುತ್ತದೆ, ಮತ್ತು ಅಂತಿಮ ಉತ್ತರಕ್ಕಾಗಿ ಫಲಿತಾಂಶವನ್ನು ಹಿಂತಿರುಗಿಸುತ್ತದೆ.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ಚಾಟ್ ಜೊತೆ ಪ್ರಯತ್ನಿಸಿ:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ಒೕಪನ್ ಮಾಡಿ ಕೇಳಿ: -> - "ReAct ಮಾದರಿ ಹೇಗೆ ಕೆಲಸಮಾಡುತ್ತದೆ ಮತ್ತು ಏಕೆ ಎಐ ಏಜೆಂಟ್ಗಳಿಗೆ ಪರಿಣಾಮಕಾರಿಯಾಗಿದೆ?" -> - "ಏಜೆಂಟ್ ಯಾವ ಟೂಲ್ ಬಳಸಬೆಕು ಮತ್ತು ಯಾವ ಕ್ರಮದಲ್ಲಿ ಎಂದು ಹೇಗೆ ನಿರ್ಧರಿಸುತ್ತದೆ?" -> - "ಟೂಲ್ ಕಾರ್ಯ ನಿರ್ವಹಣೆ ವಿಫಲವಾದರೆ ಏನಾಗುತ್ತದೆ - ನಾನು ದೋಷಗಳನ್ನು ಆಸಕ್ತಿಯಿಂದ ಹೇಗೆ ನಿರ್ವಹಿಸಬೇಕು?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ಚಾಟ್‌ನೊಂದಿಗೆ ಪ್ರಯತ್ನಿಸಿ:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ತೆರೆದೂ ಕೇಳಿ: +> - "ReAct ಮಾದರಿ ಹೇಗೆ ಕಾರ್ಯಗತಗೊಳಿಸಲಾಗುತ್ತದೆ ಮತ್ತು AI ಏಜೆಂಟ್‌ಗಳಿಗೆ ಇದು ಪರಿಣಾಮಕಾರಿಯೆ? " +> - "ಏಜೆಂಟ್ ಯಾವ ಉಪಕರಣವನ್ನು ಯಾವ ಕ್ರಮದಲ್ಲಿ ಬಳಸಬೇಕೆಂದು ಹೇಗೆ ನಿರ್ಧರಿಸುತ್ತದೆ?" +> - "ಉಪಕರಣ ನಿರ್ವಹಣೆ ವಿಫಲವಾದರೆ ಏನು — ದೋಷಗಳನ್ನು ಹೇಗೆ ದೃಢವಾಗಿ ಹ್ಯಾಂಡಲ್ ಮಾಡಬೇಕು?" -### ಪ್ರತಿಕ್ರಿಯೆ ಪುಟ್‌ಪಡಿಸುವಿಕೆ +### ಪ್ರತಿಕ್ರಿಯೆ ರಚನೆ -ಮಾದರಿ ಹವಾಮಾನ ಡೇಟಾವನ್ನು ಸ್ವೀಕರಿಸಿ ಅದನ್ನು ಬಳಕೆದಾರನಿಗೆ ಸಹಜ ಭಾಷೆಯ ಪ್ರತಿಕ್ರಿಯೆಯಾಗಿ ವಿನ್ಯಾಸಗೊಳ್ಳುತ್ತದೆ. +ಮಾದರಿ ಹವಾಮಾನ ಡೇಟಾವನ್ನು ಪಡೆದು ಬಳಕೆದಾರನಿಗೆ ನೈಸರ್ಗಿಕ ಭಾಷೆಯಲ್ಲಿ ಪ್ರತಿಕ್ರಿಯೆ ರೂಪಿಗೆ ಪರಿವರ್ತಿಸುತ್ತದೆ. -### ವಾಸ್ತುಶಿಲ್ಪ: ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಆಟೋ- ವೈಯರಿಂಗ್ +### ವಾಸ್ತುಶಿಲ್ಪ: ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಸ್ವಯಂ-ವೈರಿಂಗ್ -ಈ ಮODULE LangChain4j ನ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಏಕೀಕರಣವನ್ನು ಡಿಕ್ಲೇರೇಟಿವ್ `@AiService` ಇಂಟರ್ಫೇಸ್ಗಳೊಂದಿಗೆ ಬಳಸುತ್ತದೆ. ಪ್ರಾರಂಭದಲ್ಲಿ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಪ್ರತಿಯೊಬ್ಬ `@Component` ಅನ್ನು ಕಂಡುಹಿಡಿಯುತ್ತದೆ, ಅದರಲ್ಲಿ `@Tool` ವಿಧಾನಗಳಿವೆ, ನಿಮ್ಮ `ChatModel` ಬಿನ್, ಮತ್ತು `ChatMemoryProvider` — ನಂತರ ಅವುಗಳೆಲ್ಲವನ್ನು ಶೂನ್ಯ ಬೋಯ್ಲರ್‌ಪ್ಲೇಟ್‌ನೊಂದಿಗೆ ಏಕ `Assistant` ಇಂಟರ್ಫೇಸ್ಗಾಗಿ ವೈಯರ್ ಮಾಡುತ್ತದೆ. +ಈ ಮಾಡ್ಯೂಲ್ LangChain4j ನ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಏಕೀಕರಣವನ್ನು ಡಿಕ್ಲೇಟಿವ್ `@AiService` ಇಂಟರ್ಫೇಸ್‌ಗಳೊಂದಿಗೆ ಬಳಕೆಮಾಡುತ್ತದೆ. ಆರಂಭದಲ್ಲಿ Spring Boot ಪ್ರತಿ `@Component` ಅನ್ನು ಪತ್ತೆಹಚ್ಚುತ್ತದೆ ಅದು `@Tool` ವಿಧಾನಗಳನ್ನು ಬಾಳುತ್ತದೆ, ನಿಮ್ಮ `ChatModel` ಬೀನ್ ಮತ್ತು `ChatMemoryProvider` - ನಂತರ ಅವುಗಳೆಲ್ಲವನ್ನು ಸರಳ `Assistant` ಇಂಟರ್ಫೇಸ್‌ಗೆ ನೂತನವಾಗಿ ಜೋಡಿಸುತ್ತದೆ. -Spring Boot Auto-Wiring Architecture +Spring Boot ಸ್ವಯಂ-ವೈರಿಂಗ್ ವಾಸ್ತುಶಿಲ್ಪ -*@AiService ಇಂಟರ್ಫೇಸ್ ChatModel, ಟೂಲ್ ಘಟಕಗಳು, ಮತ್ತು ಮೆಮೊರಿ ಒದಗಿಸುವಿಕೆಯನ್ನು ಸೇರಿಸಲು ಸಹಾಯಕವಾಗಿದ್ದು — ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಇವೆಲ್ಲವನ್ನು ಆಟೋಮ್ಯಾಟಿಕ್‌ ಆಗಿ ವೈಯರ್ ಮಾಡುತ್ತದೆ.* +*`@AiService` ಇಂಟರ್ಫೇಸ್ ChatModel, ಉಪಕರಣ ಘಟಕಗಳು ಮತ್ತು ಸ್ಮರಣೆ ಒದಗಿಸುವವರನ್ನು ಜೋಡಿಸುತ್ತದೆ — Spring Boot ಎಲ್ಲ ವೈರಿಂಗ್ ಅನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ನಿರ್ವಹಿಸುತ್ತದೆ.* -ಇದಲ್ಲದೆ, ಕೆಳಗಿನ ಪೂರ್ಣ ವಿನಂತಿ ಜೀವನಚರ್ತಿಯನ್ನು ಸೀಕ್ವೆನ್ಸ್ ಚಿತ್ತಾರ ರೂಪದಲ್ಲಿ ನೋಡಿ — HTTP ವಿನಂತಿಯಿಂದ ಕಂಡ್ರೋಲ್, ಸರ್ವೀಸ್, ಆಟೋ- ವೈಯರ್ ಪ್ರಾಕ್ಸಿ ಮೂಲಕ, ಟೂಲ್ ಕಾರ್ಯವಾಯುವಿಕೆ ಮತ್ತು ಹಿಂತಿರುಗುವಿಕೆಗೆ至る: +ಇದು ಸಂಪೂರ್ಣ ವಿನಂತಿ ಜೀವನಚರಿತ್ರೆಯನ್ನು ಕ್ರಮ ಚಿತ್ತರಣವಾಗಿ ತೋರಿಸುತ್ತದೆ — HTTP ವಿನಂತಿಯಿಂದ ಕಂಟ್ರೋಲರ್, ಸೇವೆ ಮತ್ತು ಸ್ವಯಂ-ವೈರಿಂಗ್ ಪ್ರಾಕ್ಸಿ ಮೂಲಕ ನೀಡುವ ತನಕ, ಉಪಕರಣ ನಿರ್ವಹಣೆ ಮತ್ತು ಹಿಂತಿರುಗಿ: -Spring Boot Tool Calling Sequence +Spring Boot ಉಪಕರಣ ಕರೆ ಕ್ರಮ -*ಪೂರ್ಣ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ವಿನಂತಿ ಜೀವನಚರ್ತಿ — HTTP ವಿನಂತಿ ಕಂಡ್ರೋಲರ್ ಮತ್ತು ಸರ್ವೀಸ್ ಮೂಲಕ ಆಟೋ- ವೈಯರ್‌ ಆಗಿರುವ Assistant ಪ್ರಾಕ್ಸಿಗೆ ಹರಿದು, ಅದು LLM ಮತ್ತು ಟೂಲ್ ಕರೆಗಳನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಸಂಚಾಲಿಸುತ್ತದೆ.* +*ಪೂರ್ಣ Spring Boot ವಿನಂತಿ ಜೀವನಚರಿತ್ರೆ — HTTP ವಿನಂತಿ ಕಂಟ್ರೋಲರ್ ಮತ್ತು ಸೇವೆ ಮೂಲಕ ಸ್ವಯಂಚಾಲಿತ ಉತ್ತರಕಾರಕ ಪ್ರಾಕ್ಸಿಗೆ ಹರಿದು, ಅದು LLM ಮತ್ತು ಉಪಕರಣ ಕರೆಗಳನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ವ್ಯವಸ್ಥಾಪಿಸುತ್ತದೆ.* -ಈ ವಿಧಾನದಿಂದ ಲಭ್ಯವಿರುವ ಪ್ರಮುಖ ಪ್ರಯೋಜನಗಳು: +ಈ ವಿಧಾನದ ಪ್ರಮುಖ ಪ್ರಯೋಜನಗಳು: -- **ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಆಟೋ- ವೈಯರಿಂಗ್** — ChatModel ಮತ್ತು ಟೂಲ್ಗಳು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಇಂಜೆಕ್ಟ್ ಆಗುತ್ತವೆ -- **@MemoryId ಮಾದರಿ** — ಸ್ವಯಂಚಾಲಿತ ಸೆಷನ್ ಆಧಾರಿತ ಮೆಮೊರಿ ನಿರ್ವಹಣೆ -- **ಒಂದು ಉದಾಹರಣೆ** — Assistant ಒಂದೇ ಬಾರಿಗೆ ಸೃಷ್ಟಿಸಿ ಉತ್ತಮ ಕಾರ್ಯಕ್ಷಮತೆಗೆ ಮರುಬಳಕೆ -- **ಟೈಪ್-ಸೇಫ್ ಕಾರ್ಯ ನಿರ್ವಹಣೆ** — ಜಾವಾ ವಿಧಾನಗಳನ್ನು ನೇರವಾಗಿ ಟೈಪ್ ಪರಿವರ್ತನೆಯೊಂದಿಗೆ ಕರೆ ಮಾಡುತ್ತದೆ -- **ಬಹು-ತಿರುವು ಸಂಚಾಲನೆ** — ಟೂಲ್ ಚೈನಿಂಗ್ ಅನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ನಿರ್ವಹಿಸುತ್ತದೆ -- **ಸೊನ್ನೆ ಬೋಯ್ಲರ್‌ಪ್ಲೇಟ್** — ಕೈಯಿಂದ `AiServices.builder()` ಕರೆಗಳು ಅಥವಾ ಮೆಮೊರಿ ಹ್ಯಾಷ್‌ಮ್ಯಾಪ್ ಇಲ್ಲ +- **Spring Boot ಸ್ವಯಂ-ವೈರಿಂಗ್** — ChatModel ಮತ್ತು ಉಪಕರಣಗಳು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಒಳಗೊಂಡಿರುತ್ತವೆ +- **@MemoryId ಮಾದರಿ** — ಸ್ವಯಂಚಾಲಿತ ಸತ್ರ ಆಧಾರಿತ ಸ್ಮರಣೆ ನಿರ್ವಹಣೆ +- **ಒಂದು ಉದಾಹರಣೆ** — Assistant ಒಮ್ಮೆ ತಯಾರಿಸಿ ಮರುಬಳಕೆಗಾಗಿ +- **ಪ್ರಕಾರ-ಭದ್ರ ಕೊಡುಗೆ** — ಜಾವಾ ವಿಧಾನಗಳನ್ನು ನೇರವಾಗಿ ತರಗತಿ ರೂಪಾಂತರದಿಂದ ಕರೆಮಾಡು +- **ಬಹು-ತಿರುವು ಸಂಯೋಜನೆ** — ಒಟ್ಟಾಗಿ ಉಪಕರಣ ಸರಪಳಿಯನ್ನು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ನಿರ್ವಹಿಸುತ್ತದೆ +- **ಶೂನ್ಯ ಬಾಯ್ಲರ್‌ಪ್ಲೇಟ್** — ಯಾವುದೇ ಕೈಯಿಂದ `AiServices.builder()` ಕರೆಗಳು ಅಥವಾ `HashMap` ಸ್ಮರಣೆ ಬೇಕಾಗುವುದಿಲ್ಲ -ಮ್ಯಾನುಯಲ್ `AiServices.builder()` ಬಳಸಿ ಪರ್ಯಾಯ ವಿಧಾನಗಳು ಹೆಚ್ಚುವರಿ ಕೋಡ್ ಅಗತ್ಯವಿರುತ್ತವೆ ಮತ್ತು ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಏಕೀಕರಣ ಲಾಭಗಳನ್ನು ಮಿಸ್ ಮಾಡುತ್ತವೆ. +ಬದಲಿ ವಿಧಾನಗಳಾದ ಕೈಯಿಂದ `AiServices.builder()` ಹೆಚ್ಚಿನ ಕೋಡ್ ಅಗತ್ಯವಿದೆ ಮತ್ತು Spring Boot ಏಕೀಕರಣದ ಪ್ರಯೋಜನಗಳನ್ನು ತಪ್ಪಿಸುತ್ತವೆ. -## ಟೂಲ್ ಚೈನಿಂಗ್ +## ಉಪಕರಣ ಸರಪಳಿ -**ಟೂಲ್ ಚೈನಿಂಗ್** — ಸತ್ಯಕ್ಕೂರ್ಾಚಿ ಜಾಗತಿಕ ಶಕ್ತಿ ಟೂಲ್- ಆಧಾರಿತ ಏಜೆಂಟ್‌ಗಳಲ್ಲಿ ಕಂಡುಬರುತ್ತದೆ, ಏಕೆಂದರೆ ಒಂದೇ ಪ್ರಶ್ನೆಗೆ ಬಹು ಟೂಲ್ಗಳ ಅಗತ್ಯವಿರುತ್ತದೆ. "ಸ್ಯಾಟಲ್‌ನ ಹವಾಮಾನ ಫಾರೆನ್‌ಹೀಟ್ ನಲ್ಲಿ ಏನು?" ಎಂದು ಕೇಳಿದರೆ, ಏಜೆಂಟ್ ಸ್ವಯంచಾಲಿತವಾಗಿ ಎರಡು ಟೂಲ್ಗಳನ್ನು ಕಂಡುಹಿಡಿದು ಸಂಪರ್ಕಿಸುತ್ತದೆ: ಮೊದಲು `getCurrentWeather` ಅನ್ನು ಸಿ ಸೆಲ್ಸಿಯಸ್ ನಲ್ಲಿ ತಾಪಮಾನ ಪಡೆಯಲು ಕರೆಮಾಡುವುದು, ನಂತರ ಆ ಬೆಲೆಯನ್ನು `celsiusToFahrenheit` ಗೆ ಪರಿವರ್ತನೆಗಾಗಿ ಪಾಸ್ ಮಾಡುವುದು — ಎಲ್ಲವೂ ಒಂದೇ ಸಂವಾದ ತಿರುವಿನಲ್ಲಿ. +**ಉಪಕರಣ ಸರಪಳಿ** — ಉಪಕರಣ ಆಧಾರಿತ ಏಜೆಂಟ್‌ಗಳ ನಿಜವಾದ ಶಕ್ತಿ ಒಂದು ಪ್ರಶ್ನೆಗೆ ಬಹು ಉಪಕರಣಗಳು ಬೇಕಾದಾಗ ಬರುತ್ತದೆ. "ಸಿಯಾಟಲ್‌ನಲ್ಲಿ ಹವಾಮಾನ ಫಾರೆನ್‌ಹೀಟ್‌ನಲ್ಲಿ ಏನೆಂದು?" ಎಂದು ಕೇಳಿದರೆ ಏಜೆಂಟ್ ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಎರಡು ಉಪಕರಣಗಳನ್ನು ಸರಪಳಿ ಮಾಡುತ್ತದೆ: ಮೊದಲಿಗೆ ಅದು `getCurrentWeather` ಅನ್ನು ಕರೆಮಾಡಿ ಸೆಲ್ಸಿಯಸ್ ನಲ್ಲಿ ತಾಪಮಾನ ಪಡೆಯುತ್ತದೆ, ನಂತರ ಆ ಮೌಲ್ಯವನ್ನು `celsiusToFahrenheit` ಗೆ ಕಳುಹಿಸಿ ಬದಲಾವಣೆ ಮಾಡುತ್ತದೆ — ಇವು ಎಲ್ಲವು ಒಂದೇ ಸಂಭಾಷಣಾ ತಿರುವಿನಲ್ಲಿ. -Tool Chaining Example +ಉಪಕರಣ ಸರಪಳಿ ಉದಾಹರಣೆ -*ಟೂಲ್ ಚೈನಿಂಗ್ ಕಾರ್ಯಾಚರಣೆ — ಏಜೆಂಟ್ ಮೊದಲು getCurrentWeather ಕರೆ ಮಾಡುತ್ತದೆ, ನಂತರ ಸೆಲ್ಸಿಯಸ್ ಫಲಿತಾಂಶವನ್ನು celsiusToFahrenheit ಗೆ ಪೈಪ್ ಮಾಡಿ ಸಂಯುಕ್ತ ಉತ್ತರ ನೀಡುತ್ತದೆ.* +*ಉಪಕರಣ ಸರಪಳಿಯಲ್ಲಿ — ಏಜೆಂಟ್ ಮೊದಲು getCurrentWeather ಅನ್ನು ಕರೆಮಾಡುತ್ತದೆ, ನಂತರ ಸೆಲ್ಸಿಯಸ್ ಫಲಿತಾಂಶವನ್ನು celsiusToFahrenheit ಗೆ ಪೈಪ್ ಮಾಡುತ್ತದೆ, ಮತ್ತು ಸಂಯುಕ್ತ ಉತ್ತರ ನೀಡುತ್ತದೆ.* -**ಗೌರವಯುತ ವಿಫಲತೆಗಳು** — ನಕಲಿ ಡೇಟಾದಲ್ಲಿಲ್ಲದ ನಗರದಲ್ಲಿ ಹವಾಮಾನ ಕೇಳಿದರೆ, ಟೂಲ್ ದೋಷ ಸಂದೇಶ ನೀಡುತ್ತದೆ ಮತ್ತು ಎಐ ಸಹಾಯಕವಾಗಿ ಸಹಾಯ ಮಾಡಲು ಆಗದಂತಿದೆ ಎಂದು ವಿವರಿಸುತ್ತದೆ, ಸಂಘಟನೆ ಬೀಳಿಸುವುದಿಲ್ಲ. ಟೂಲ್ಗಳು ಸುರಕ್ಷಿತವಾಗಿ ವಿಫಲವಾಗುತ್ತವೆ. ಕೆಳಗಿನ ಚಿತ್ರಣದಲ್ಲಿ ಎರಡು ವಿಧಾನಗಳ ವ್ಯತ್ಯಾಸ ತೋರಿಸಲಾಗಿದೆ — ಸರಿಯಾದ ದೋಷ ನಿರ್ವಹಣೆಯೊಂದಿಗೆ, ಏಜೆಂಟ್ ಪರಿಸ್ಥಿತಿಯನ್ನು ಹಿಡಿದು ಸಹಾಯಕ ಪ್ರತಿಕ್ರಿಯೆ ನೀಡುತ್ತದೆ, ಇಲ್ಲದಿದ್ದರೆ ಸಂಪೂರ್ಣ ಆ್ಯಪ್ಲಿಕೇಶನ್ ಕ್ರ್ಯಾಶ್ ಆಗುತ್ತದೆ: +**ಶ್ರದ್ಧಾಪೂರ್ವಕ ವಿಫಲತೆಗಳು** — mock data ಯಲ್ಲಿ ಇಲ್ಲದ ನಗರದಲ್ಲಿ ಹವಾಮಾನ ಕೇಳಿದರೆ. ಉಪಕರಣದ ಫಲಿತಾಂಶ ದೋಷ ಸಂದೇಶ ನೀಡುತ್ತದೆ, ಮತ್ತು AI ಸಹಾಯ ಮಾಡಲಾಗುವುದಿಲ್ಲ ಎಂದು ಸ್ಪಷ್ಟಪಡಿಸುತ್ತದೆ ಬದಲಿಗೆ ಅಪ್ಲಿಕೇಶನ್ ಕ್ರ್ಯಾಷ್ ಆಗುವುದಿಲ್ಲ. ಉಪಕರಣಗಳು ಸುರಕ್ಷಿತವಾಗಿ ವಿಫಲಗೊಳ್ಳುತ್ತವೆ. ಕೆಳಗಿನ ಚಿತ್ರ ಎರಡು ವಿಧಾನಗಳನ್ನು ಹೋಲಿಸುತ್ತದೆ — ಸೂಕ್ತ ದೋಷ ನಿರ್ವಹಣೆಯೊಂದಿಗೆ ಏಜೆಂಟ್ ಅಪವಾದವನ್ನು ಹಿಡಿದು ಸಹಾಯಕರ ಪ್ರತಿಕ್ರಿಯೆಯನ್ನು ನೀಡುತ್ತದೆ, ಅದೇ ವೇಳೆ ಅದು ಇಲ್ಲದಿದ್ದರೆ ಅಪ್ಲಿಕೇಶನ್ ಸಂಪೂರ್ಣವಾಗಿ ನזಿಕೊಂಡಿರುತ್ತದೆ: -Error Handling Flow +ದೋಷ ನಿರ್ವಹಣೆ ಹರಿವು -*ಟೂಲ್ ವಿಫಲವಾದಾಗ, ಏಜೆಂಟ್ ದೋಷವನ್ನು ಹಿಡಿದು ಕ್ರ್ಯಾಶ್ ಆಗದೆ ಸಹಾಯಕರ ಪ್ರತಿಕ್ರಿಯೆ ನೀಡುತ್ತದೆ.* +*ಉಪಕರಣ ವಿಫಲವಾದಾಗ, ಏಜೆಂಟ್ ದೋಷವನ್ನು ಹಿಡಿದು ಕ್ರ್ಯಾಷ್ ಆಗುವುದು ಬದಲು ಸಹಾಯಕರ ವಿವರಿಸಿ ಪ್ರತಿಕ್ರಿಯೆ ನೀಡುತ್ತದೆ.* -ಇದು ಒಂದೇ ಸಂವಾದ ತಿರುವಿನಲ್ಲಿ ನಡೆಯುತ್ತದೆ. ಏಜೆಂಟ್ ಸ್ವತಂತ್ರವಾಗಿ ಬಹು ಟೂಲ್ ಕರೆಗಳನ್ನು ಸಂಚಾಲಿಸುತ್ತದೆ. +ಇದು ಒಂದೇ ಸಂಭಾಷಣಾ ತಿರುವಿನಲ್ಲಿ ನಡೆಯುತ್ತದೆ. ಏಜೆಂಟ್ ಬಹು ಉಪಕರಣ ಕರೆಗಳನ್ನು ಸ್ವತಃ ನಿರ್ವಹಿಸುತ್ತದೆ. -## ಆ್ಯಪ್ಲಿಕೇಶನ್ ಓದಿ +## ಅಪ್ಲಿಕೇಶನ್ ಜೋಡಿಸಿ -**ನಿಯೋಜನ ಪರಿಶೀಲನೆ:** +**ನಿಯೋಜನೆ ಪರಿಶೀಲಿಸಿ:** -Module 01 ನಲ್ಲಿ ಸೃಷ್ಟಿಸಿದ ಅಜೂರ್ ಪ್ರಮಾಣಪತ್ರಗಳೊಂದಿಗೆ ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಲ್ಲಿ `.env` ಫೈಲ್ ಇರುವುದನ್ನು ಖಚಿತಪಡಿಸಿಕೊಳ್ಳಿ. ಈ ಫೋಲ್ಡರ್ (`04-tools/`) ನಲ್ಲಿ ಈ ಕಮಾಂಡ್ ಓಡಿ: +Module 01 ನಲ್ಲಿ ಸೃಷ್ಟಿಸಲಾದ ಅಜೂರ್ ಪ್ರಮಾಣಪತ್ರಗಳೊಂದಿಗೆ `.env` ಫೈಲ್ ರೂಟ್ ಡೈರೆಕ್ಟ್ರಿಯಲ್ಲಿ ಇರುವುದನ್ನು ಖಚಿತಪಡಿಸಿಕೊಳ್ಳಿ. ಇದನ್ನು ಮಾಡ್ಯೂಲ್ ಡೈರೆಕ್ಟ್ರಿಯಲ್ಲಿ (`04-tools/`)ರಿಂದ ರನ್ ಮಾಡಿ: -**ಬಾಶ್:** +**ಬ್ಯಾಶ್:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ತೆಳುಕಬೇಕು +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ಅನ್ನು ತೋರಿಸಬೇಕು ``` -**ಪವರ್‌ಷೆಲ್:** +**ಪವರ್‌ಶೆಲ್:** ```powershell Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ಅನ್ನು ತೋರಿಸಬೇಕು ``` -**ಅ್ಯಪ್ಲಿಕೇಶನ್ ಪ್ರಾರಂಭಿಸಿ:** +**ಅಪ್ಲಿಕೇಶನ್ ಪ್ರಾರಂಭಿಸಿ:** -> **ಸೂಚನೆ:** ನೀವು Module 01 ರ ರೂಟ್ ಡೈರೆಕ್ಟರಿಯಿಂದ `./start-all.sh` ಮೂಲಕ ಎಲ್ಲಾ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಈಗಾಗಲೇ ಪ್ರಾರಂಭಿಸಿದೆರೆ, ಈ ಮODULE ಈಗಾಗಲೇ 8084 ಪೋರ್ಟ್ ನಲ್ಲಿ চলেುತ್ತಿದೆ. ಕೆಳಗಿನ ಪ್ರಾರಂಭ ಕಮಾಂಡ್‌ಗಳನ್ನು ಬಿಟ್ಟು http://localhost:8084 ಗೆ ನೇರವಾಗಿ ಹೋಗಬಹುದು. +> **ಸೂಚನೆ:** ನೀವು ಮೊದಲು ರೂಟ್ ಡೈರೆಕ್ಟ್ರಿಯಿಂದ `./start-all.sh` ರನ್ ಮಾಡಿಕೊಂಡಿದ್ದರೆ (Module 01 ನಲ್ಲಿ ವಿವರಿಸಲಾಗಿದೆ), ಈ ಮಾಡ್ಯೂಲ್ ಈಗಾಗಲೇ 8084 ಪೋರ್ಟ್‌ನಲ್ಲಿ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತಿದೆ. ನೀವು ಕೆಳಗಿನ ಪ್ರಾರಂಭ ಆದೇಶಗಳನ್ನು ಉಲ್ಲೇಖಿಸದೆ ನೇರವಾಗಿ http://localhost:8084 ಗೆ ಹೋಗಬಹುದು. -**ಆಯ್ಕೆ 1: ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಷ್‌ಬೋರ್ಡ್ ಬಳಕೆ (VS Code ಉಪಯೋಗಿಗಳಿಗಾಗಿ ಶಿಫಾರಸು)** +**ಆಯ್ಕೆ 1: ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್ಬೋರ್ಡ್ ಬಳಸುವುದು (VS ಕೋಡ್ ಬಳಕೆದಾರರಿಗೆ ಶಿಫಾರಸು)** -ಡಿವ್ containರಿನಲ್ಲಿ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಷ್‌ಬೋರ್ಡ್ ವಿಸ್ತರಣೆ ಇದೆ, ಇದು ಎಲ್ಲಾ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ವಹಿಸಲು ದೃಶ್ಯಾತ್ಮಕ ಅಂತರ್ಫೇಸ್ ನೀಡುತ್ತದೆ. ನೀವು VS Code‌ನ ಎಡ ಬದಿಯದಲ್ಲಿ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಐಕಾನ್ ನೋಡಬಹುದು. +ಡೆವ್ ಕಂಟೈನರ್ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್ಬೋರ್ಡ್ ವಿಸ್ತರಣೆ ಸೇರಿದೆ, ಇದು ಎಲ್ಲಾ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ವಹಿಸಲು ದೃಶ್ಯಮಯ ಇಂಟರ್ಫೇಸ್ ಒದಗಿಸುತ್ತದೆ. ನೀವು ಅದನ್ನು VS ಕೋಡ್‌ನ ಎಡಭಾಗದಲ್ಲಿನ activity ಬಾರ್‌ನಲ್ಲಿ ಕಂಡುಹೇಳಬಹುದು (ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಐಕಾನ್ ನೋಡಿರಿ). -ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ನಿಂದ, ನೀವು: -- ವರ್ಕ್‌ಸ್ಪೇಸ್‌ನಲ್ಲಿರುವ ಎಲ್ಲಾ ಲಭ್ಯವಿರುವ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನೋಡಬಹುದು -- ಒತ್ತುವಿಕೆಯಿಂದ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಆರಂಭಿಸಿ/ನಿಲ್ಲಿಸಬಹುದು -- ಅ‍ಪ್ಲಿಕೇಶನ್ ಲಾಗ್‌ನ್ನು ನೇರವಾಗಿ ವೀಕ್ಷಿಸಬಹುದು -- ಅಪ್ಲಿಕೇಶನ್ ಸ್ಥಿತಿಯನ್ನು ವೀಕ್ಷಿಸಬಹುದು -ಸರಳವಾಗಿ "tools" ಬಳಿಯ ಪ್ಲೇ ಬಟನ್ ಕ್ಲಿಕ್ ಮಾಡಿ ಈ ಮೊಡ್ಯೂಲ್ ಅನ್ನು ಪ್ರಾರಂಭಿಸಿ, ಅಥವಾ ಎಲ್ಲಾ ಮೊಡ್ಯೂಲ್‌ಗಳನ್ನು ಒಮ್ಮೆಲಾಗಿ ಪ್ರಾರಂಭಿಸಿ. +ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್ಬೋರ್ಡ್ ಮೂಲಕ ನೀವು: +- ಕಾರ್ಯಕ್ಷೇತ್ರದಲ್ಲಿನ ಎಲ್ಲಾ ಲಭ್ಯವಿರುವ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಅಪ್ಲಿಕೇಶನ್ಗಳನ್ನು ನೋಡಬಹುದು +- ಏಕ ಕ್ಲಿಕ್ ಮೂಲಕ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪ್ರಾರಂಭ/ನಿಲ್ಲಿಸಬಹುದು +- ಅಪ್ಲಿಕೇಶನ್ ಲಾಗ್‌ಗಳನ್ನು ನಿಜ-ಸಮಯದಲ್ಲಿ ನೋಡಬಹುದು +- ಅಪ್ಲಿಕೇಶನ್ ಸ್ಥಿತಿಯನ್ನು ನಿಗಾ ವಹಿಸಬಹುದು -ಇದು VS Code ನಲ್ಲಿ Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ ಹೇಗಿರುತ್ತದೆ ಎಂಬುದಾಗಿದೆ: +"tools" ಪಕ್ಕದ ಪ್ಲೇ ಬಟನ್ ಕ್ಲಿಕ್ ಮಾಡಿ ಈ ಮಾಡ್ಯೂಲ್ ಅನ್ನು ಪ್ರಾರಂಭಿಸಬಹುದು ಅಥವಾ ಎಲ್ಲ ಮಾಡ್ಯೂಲ್‌ಗಳನ್ನು ಒಟ್ಟಿಗೆ ಆರಂಭಿಸಬಹುದು. -Spring Boot Dashboard +VS ಕೋಡಿನಲ್ಲಿ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್ಬೋರ್ಡ್ ಈ ರೀತಿ ಕಾಣುತ್ತದೆ: +ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ -*VS Code ನಲ್ಲಿ Spring Boot ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ — ಒಂದು ಸ್ಥಳದಿಂದ ಎಲ್ಲಾ ಮೊಡ್ಯೂಲ್‌ಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿ, ನಿಲ್ಲಿಸಿ, ಮತ್ತು ಸ್ಟೇಟಸ್ ಅನ್ನು ಗಮನಿಸಿ* +*VS ಕೋಡ್‌ನಲ್ಲಿ ಸ್ಪ್ರಿಂಗ್ ಬೂಟ್ ಡ್ಯಾಶ್‌ಬೋರ್ಡ್ — ಒಬ್ಬೇ ಸ್ಥಳದಿಂದ ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್‌ಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿ, ನಿಲ್ಲಿಸಿ ಮತ್ತು ಮೇಲ್ವಿಚಾರಣೆ ಮಾಡಿ* -**ಆಯ್ಕೆ 2: ಶೆಲ್ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಬಳಸುವುದು** +**ಆಯ್ಕೆ 2: ಶೆಲ್ ಸ್ಕ್ರಿಪ್ಟ್ಗಳ ಬಳಕೆ** -ಎಲ್ಲಾ ವೆಬ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪ್ರಾರಂಭಿಸಿ (ಮೊಡ್ಯೂಲ್ 01-04): +ಎಲ್ಲಾ ವೆಬ್ ಅಪ್ಲಿಕೇಶನ್‌ಗಳು (ಮೋಡ್ಯೂಲ್‌ಗಳು 01-04) ಪ್ರಾರಂಭಿಸಿ: -**Bash:** +**ಬ್ಯಾಶ್:** ```bash -cd .. # ಮೂಲ ಡೈರೆಕ್ಟರಿಯಿಂದ +cd .. # ಮೂಲ ಡೈರેક્ટರಿ ನಿಂದ ./start-all.sh ``` - -**PowerShell:** + +**ಪವರ್‌ಶೆಲ್:** ```powershell -cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿ ನಿಂದ +cd .. # ರೂಟ್ ಡೈರೆಕ್ಟರಿ ಇಂದ .\start-all.ps1 ``` + +ಅಥವಾ ಈ ಮೋಡ್ಯೂಲ್ ಅನ್ನು ಮಾತ್ರ ಪ್ರಾರಂಭಿಸಿ: -ಅಥವಾ ಈ ಮೊಡ್ಯೂಲ್ ಮಾತ್ರ ಪ್ರಾರಂಭಿಸಿ: - -**Bash:** +**ಬ್ಯಾಶ್:** ```bash cd 04-tools ./start.sh ``` - -**PowerShell:** + +**ಪವರ್‌ಶೆಲ್:** ```powershell cd 04-tools .\start.ps1 ``` + +ಎರಡೂ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ರೂಟ್ `.env` ಫೈಲ್‌ನಿಂದ ಪರಿಸರ ನೇಮಕಾಂಕಗಳನ್ನು ಲೋಡ್ ಮಾಡುತ್ತವೆ ಮತ್ತು JAR ಗಳನ್ನು ನಿರ್ಮಿಸುವುದಿಲ್ಲದಿದ್ದರೆ ಅವುಗಳನ್ನು ನಿರ್ಮಿಸುತ್ತವೆ. -ಎರಡೂ ಸ್ಕ್ರಿಪ್ಟ್‌ಗಳು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ರೂಟ್ `.env` ಫೈಲ್‌ನಿಂದ ಪರಿಸರ ಸಂಚಿಕೆಗಳನ್ನು ಲೋಡ್ ಮಾಡುತ್ತವೆ ಮತ್ತು JAR ಗಳಿಲ್ಲದಿದ್ದರೆ ಅವುಗಳನ್ನು ನಿರ್ಮಿಸುತ್ತವೆ. - -> **ಗಮನಿಸಿ:** ನೀವು ಪ್ರಾರಂಭಿಸಲು ಮುನ್ನ ಎಲ್ಲಾ ಮೊಡ್ಯೂಲ್‌ಗಳನ್ನು ಕೈಯಿಂದ ನಿರ್ಮಿಸಲು ಇಚ್ಛಿಸಿದರೆ: +> **ಗಮನಿಸಿ:** ನೀವು ಪ್ರಾರಂಭಿಸುವ ಮೊದಲು ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್‌ಗಳನ್ನು ಕೈಯಿಂದ ನಿರ್ಮಿಸಲು ಇಚ್ಛಿಸುವರೆಂದರೆ: > -> **Bash:** +> **ಬ್ಯಾಶ್:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell:** +> **ಪವರ್‌ಶೆಲ್:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -ನಿಮ್ಮ ಬ್ರೌಸರ್‌ನಲ್ಲಿ http://localhost:8084 ಓಪನ್ ಮಾಡಿ. + +ನಿಮ್ಮ ಬ್ರೌಸರ್‌ನಲ್ಲಿ http://localhost:8084 ಅನ್ನು ತೆರೆಯಿರಿ. **ನಿಲ್ಲಿಸಲು:** -**Bash:** +**ಬ್ಯಾಶ್:** ```bash -./stop.sh # ಈ ಮಾಡ್ಯೂಲ್ ಮಾತ್ರ +./stop.sh # ಈ ಮಾಯಾಜಾಲ ಮಾತ್ರ # ಅಥವಾ -cd .. && ./stop-all.sh # ಎಲ್ಲಾ ಮಾಡ್ಯೂಲ್‌ಗಳು +cd .. && ./stop-all.sh # ಎಲ್ಲಾ ಮಾಯಾಜಾಲಗಳು ``` - -**PowerShell:** + +**ಪವರ್‌ಶೆಲ್:** ```powershell .\stop.ps1 # ಈ ಮೋಡ್ಯೂಲ್ ಮಾತ್ರ # ಅಥವಾ -cd ..; .\stop-all.ps1 # ಎಲ್ಲಾ ಮೋಡ್ಯೂಲುಗಳು +cd ..; .\stop-all.ps1 # ಎಲ್ಲಾ ಮೋಡ್ಯೂಲ್‌ಗಳು ``` + +## ಅಪ್ಲಿಕೇಶನ್ ಬಳಕೆ -## ಅಪ್ಲಿಕೇಶನ್ ಬಳಸುವುದು - -ಈ ಅಪ್ಲಿಕೇಶನ್ ಒಂದು ವೆಬ್ ಇಂಟರ್ಫೇಸ್ ಒದಗಿಸುತ್ತದೆ, ಇಲ್ಲಿ ನೀವು ಹವಾಮಾನ ಮತ್ತು ತಾಪಮಾನ ಪರಿವರ್ತನೆ ಉಪಕರಣಗಳಿಗೆ ಪ್ರವೇಶ ಇರುವ AI ഏಜೆಂಟ್ ಜೊತೆಗೆ ಸಂವಹನ ಮಾಡಬಹುದು. ಇಂತಿದಾಗಿದೆ ಇಂಟರ್ಫೇಸ್ — ಇದರಲ್ಲಿ ತ್ವರಿತ ಪ್ರಾರಂಭ ಉದಾಹರಣೆಗಳು ಮತ್ತು ವಿನಂತಿಗಳನ್ನು ಕಳುಹಿಸಲು ಚಾಟ್ ಪ್ಯಾನೆಲ್ ಸೌಲಭ್ಯ ಇದೆ: +ಅಪ್ಲಿಕೇಶನ್ ಒಂದು ವೆಬ್ ಇಂಟರ್ಫೇಸ್ ಒದಗಿಸುತ್ತದೆ, ಅಲ್ಲಿ ನೀವು ಹವಾಮಾನ ಮತ್ತು ತಾಪಮಾನ ಪರಿವರ್ತನೆ ಉಪಕರಣಗಳನ್ನು ಹೊಂದಿರುವ AI ಏಜೆಂಟ್ ಜೊತೆ ಸಂವಹನ ಮಾಡಬಹುದು. ಇಂಟರ್ಫೇಸ್ ಹೀಗಿದೆ — ಇದು ತ್ವರಿತ ಪ್ರಾರಂಭ ಉದಾಹರಣೆಗಳು ಮತ್ತು ವಿನಂತಿಗಳನ್ನು ಕಳುಹಿಸಲು ಚಾಟ್ ಪ್ಯಾನೆಲ್ ಅನ್ನು ಒಳಗೊಂಡಿದೆ: -AI Agent Tools Interface +AI ಏಜೆಂಟ್ ಟೂಲ್ಸ್ ಇಂಟರ್ಫೇಸ್ -*AI ಏಜೆಂಟ್ ಟೂಲ್ಸ್ ಇಂಟರ್ಫೇಸ್ - ತ್ವರಿತ ಉದಾಹರಣೆಗಳು ಮತ್ತು ಸಾಧನಗಳೊಂದಿಗೆ ಸಂವಹನಕ್ಕೆ ಚಾಟ್ ಇಂಟರ್‌ಫೇಸ್* +*AI ಏಜೆಂಟ್ ಟೂಲ್ಸ್ ಇಂಟರ್ಫೇಸ್ - ಟೂಲ್‌ಗಳ ಜೊತೆಗೆ ಸಂವಹನ ಮಾಡಲು ತ್ವರಿತ ಉದಾಹರಣೆಗಳು ಮತ್ತು ಚಾಟ್ ಇಂಟರ್ಫೇಸ್* ### ಸರಳ ಉಪಕರಣ ಬಳಕೆಯನ್ನು ಪ್ರಯತ್ನಿಸಿ -ಸರಳ ವಿನಂತಿಯಿಂದ ಪ್ರಾರಂಭಿಸಿ: "100 ಡಿಗ್ರಿ ಫಾರೆನ್‌ಹೈಟ್ ಅನ್ನು ಸೆಲ್ಸಿಯಸ್ ಗೆ ಪರಿವರ್ತಿಸಿ". ಏಜೆಂಟ್ ಇದನ್ನು ತಾಪಮಾನ ಪರಿವರ್ತನೆ ಉಪಕರಣ ಬೇಕಾಗಿದೆ ಎಂದು ಗುರುತಿಸಿ, ಸರಿಯಾದ ಅಂಶಗಳೊಂದಿಗೆ ಕರೆ ಮಾಡಿ ಫಲಿತಾಂಶವನ್ನು ಹಿಂದಿರುಗಿಸುತ್ತದೆ. ನೀವು ಯಾವ ಉಪಕರಣವನ್ನು ಬಳಸಬೇಕೆಂದು ಅಥವಾ ಹೇಗೆ ಕರೆ ಮಾಡಬೇಕೆಂದು ನಿರ್ದಿಷ್ಟಪಡಿಸದೆ ಈ ಸಹಜವಾಗಿದೆ ಎಂದು ಗಮನಿಸಿ. +ಸರಳ ವಿನಂತಿಯಿಂದ ಪ್ರಾರಂಭಿಸಿ: "100 ಡಿಗ್ರಿ ಫಾರೆನ್ಹೈಟ್ ಅನ್ನು ಸೆಲ್ಸಿಯಸ್‌ಗೆ ಪರಿವರ್ತಿಸಿ". ಏಜೆಂಟ್ ತಾಪಮಾನ ಪರಿವರ್ತನೆ ಉಪಕರಣ ಬೇಕಾಗಿದೆ ಎಂದು ಗುರುತಿಸಿ, ಸರಿಯಾದ ನಿಯಮಾನುಗ್ಗವಾಗಿ ಅದನ್ನು ಕರೆದು ಫಲಿತಾಂಶ ಹಿಂತಿರುಗಿಸುತ್ತದೆ. ನೀವು ಯಾವ ಉಪಕರಣವನ್ನು ಬಳಸಬೇಕೆಂದು ಅಥವಾ ಅದನ್ನು ಹೇಗೆ ಕರೆದುಕೊಳ್ಳಬೇಕೆಂದು ತಿಳಿಸುವ ಅವಶ್ಯಕತೆ ಇಲ್ಲದೆ ಇದು ಹೇಗೆ ಸಹಜವಾಗಿದೆಯೆಂದು ಗಮನಿಸಿ. -### ಉಪಕರಣ ಸರಪಳಿ ಪರೀಕ್ಷೆ ಮಾಡಿ +### ಟೂಲ್ ಚೈನ್ ಪರೀಕ್ಷೆ -ಇದೀಗ ಮತ್ತಷ್ಟು ಸಂಕೀರ್ಣವನ್ನೊಬ್ಬಿಸಿ: "ಸಿಯಾಟಲ್ ನಲ್ಲಿ ಹವಾಮಾನ ಏನು ಮತ್ತು ಅದನ್ನು ಫಾರೆನ್‌ಹೈಟ್ ಗೆ ಪರಿವರ್ತಿಸು?" ಆಯ್ಕೆ ಪ್ರಕ್ರಿಯೆಯ ಮೂಲಕ ಏಜೆಂಟ್ ಹೇಗೆ ಕೆಲಸ ಮಾಡುತ್ತದೆ ಎಂಬುದನ್ನು ನೋಡಿ. ಮೊದಲನೇದಾಗಿ ಹವಾಮಾನ ಪಡೆಯುತ್ತದೆ (ಅದು ಸೆಲ್ಸಿಯಸ್ ನ್ನು ನೀಡುತ್ತದೆ), ನಂತರ ಫಾರೆನ್‌ಹೈಟ್ ಗೆ ಪರಿವರ್ತನೆ ಬೇಕಾಗಿದೆ ಎಂದು ಗುರುತಿಸಿ, ಪರಿವರ್ತನೆ ಉಪಕರಣವನ್ನು ಕರೆಸಿ, ಎರಡೂ ಫಲಿತಾಂಶಗಳನ್ನು ಒಟ್ಟಾಗಿ ಉತ್ತರವಾಗಿ ಹೊಂದಾಣಿಕೆ ಮಾಡುತ್ತದೆ. +ಈಗ ಸ್ವಲ್ಪ ಗೊಂದಲದ ವಿಷಯವನ್ನು ಪ್ರಯತ್ನಿಸಿ: "ಸಿಯಾಟಲ್‌ನ ಹವಾಮಾನ ಯಾವಾಗಿದ್ದು ಅದನ್ನು ಫಾರೆನ್ಹೈಟ್‌ಗೆ ಪರಿವರ್ತಿಸಿ?" ಏಜೆಂಟ್ ಹಂತ ಹಂತವಾಗಿ ಇದನ್ನು ನಿರ್ವಹಿಸುವುದನ್ನು ಗಮನಿಸಿ. ಮೊದಲು હવಾಮાન (ಸೆಲ್ಸಿಯಸ್‌ನಲ್ಲಿ ನೀಡುತ್ತದೆ) ಪಡೆಯುತ್ತದೆ, ನಂತರ ಫಾರೆನ್ಹೈಟ್‌ಗೆ ಪರಿವರ್ತಿಸಬೇಕೆಂಬ ಅಗತ್ಯವನ್ನು ಗುರುತಿಸಿ, ಪರಿವರ್ತನೆ ಉಪಕರಣವನ್ನು ಕರೆದು ಎರಡರ ಫಲಿತಾಂಶಗಳನ್ನು ಸಂಯೋಜಿಸಿ ಪ್ರತಿಕ್ರಿಯೆಯನ್ನು ನೀಡುತ್ತದೆ. -### ಸಂಭಾಷಣೆಯ ಪ್ರವಾಹವನ್ನು ನೋಡಿ +### ಸಂಭಾಷಣಾ ಹರಿವು ನೋಡಿ -ಚಾಟ್ ಇಂಟರ್ಫೇಸ್ ಸಂಭಾಷಣೆ ಇತಿಹಾಸವನ್ನು ಕಾಪಾಡುತ್ತದೆ, ಇದು ಬಹು ಪ್ರತ್ಯುತ್ತರ ಸಂವಹನಗಳಿಗೂ ಅನುಮತಿಸುತ್ತದೆ. ನೀವು ಎಲ್ಲಾ ಹಳೆಯ ಪ್ರಶ್ನೆಗಳು ಮತ್ತು ಪ್ರತಿಕ್ರಿಯೆಗಳನ್ನು ನೋಡಬಹುದು, ಇದರಿಂದ ಸಂಭಾಷಣೆಯನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುವುದು ಮತ್ತು ಏಜೆಂಟ್ ಅನೇಕ ವಿನಿಮಯಗಳ ಮೂಲಕ ಭಾಗವನ್ನು ಹೇಗೆ ನಿರ್ಮಿಸುತ್ತದೆಯೋ ತಿಳಿದುಕೊಳ್ಳುವುದು ಸುಲಭ. +ಚಾಟ್ ಇಂಟರ್ಫೇಸ್ ಸಂಭಾಷಣೆಯ ಇತಿಹಾಸವನ್ನು ಕಾಪಾಡಿಕೊಳ್ಳುತ್ತದೆ, ಇದರಿಂದ ನೀವು ಬಹು-ತಿರುವು ಸಂವಹನಗಳನ್ನು ನಡೆಸಬಹುದು. ಎಲ್ಲಾ ಹಿಂದಿನ ವಿನಂತಿಗಳು ಮತ್ತು ಉತ್ತರಗಳನ್ನು ನೀವು ನೋಡಬಹುದು, ಇದು ಸಂವಹನವನ್ನು ಟ್ರ್ಯಾಕ್ ಮಾಡಲು ಮತ್ತು ಏಜೆಂಟ್ ಹಲವು ವಿನಿಮಯಗಳ ಮೂಲಕ ಹೇಗೆ ಸಂಕೇತವನ್ನು ನಿರ್ಮಿಸುತ್ತಿದೆ ಎಂಬುದನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಲು ಸುಲಭ ಮಾಡುತ್ತದೆ. -Conversation with Multiple Tool Calls +ಬಹು ಉಪಕರಣ ಕರೆಗಳೊಂದಿಗೆ ಸಂಭಾಷಣೆ -*ಬಹು-ತಿರುವಿನ ಸಂಭಾಷಣೆ, ಸರಳ ಪರಿವರ್ತನೆಗಳು, ಹವಾಮಾನ ಪರಿಶೀಲನೆಗಳು ಮತ್ತು ಉಪಕರಣ ಸರಪಳಿ ತೋರಿಸುತ್ತಿದೆ* +*ಸರಳ ಪರಿವರ್ತನೆಗಳು, ಹವಾಮಾನ ಹುಡುಕಾಟಗಳು ಮತ್ತು ಟೂಲ್ ಚೈನಿಂಗ್ ತೋರಿಸುವ ಬಹು-ತಿರುವು ಸಂಭಾಷಣೆ* -### ವಿವಿಧ ವಿನಂತಿಗಳೊಂದಿಗೆ ಪ್ರಯೋಗ ಮಾಡಿ +### ವಿವಿಧ ವಿನಂತಿಗಳನ್ನು ಪ್ರಯತ್ನಿಸಿ -ವಿವಿಧ ಸಮ್ಮಿಶ್ರಣ ಪ್ರಯತ್ನಿಸಿ: -- ಹವಾಮಾನ ಪರಿಶೀಲನೆಗಳು: "ಟೋಕಿಯೋದಲ್ಲಿ ಹವಾಮಾನ ಹೇಗಿದೆ?" -- ತಾಪಮಾನ ಪರಿವರ್ತನೆಗಳು: "25°C ಅನ್ನು ಕೆಲ್ವಿನ್ ಗೆ ಪರಿವರ್ತಿಸು?" -- ಸಂಯುಕ್ತ ಪ್ರಶ್ನೆಗಳು: "ಪ್ಯಾರಿಸ್ ನಲ್ಲಿ ಹವಾಮಾನ ಪರಿಶೀಲಿಸಿ ಮತ್ತು ಅದು 20°C ಗಿಂತ ಮೇಲಾಗಿದೆಯೇ ನೋಡಿ" +ವಿವಿಧ ಸಂಯೋಜನೆಗಳನ್ನು ಪ್ರಯತ್ನಿಸಿ: +- ಹವಾಮಾನ ಹುಡುಕಾಟಗಳು: "ಟೋಕಿಯೋನಲ್ಲಿ ಹವಾಮಾನ ಹೇಗಿದೆ?" +- ತಾಪಮಾನ ಪರಿವರ್ತನೆಗಳು: "25°C ಅನ್ನು ಕೆಲ್ವಿನ್‌ಗೆ ಪರಿವರ್ತಿಸಿ?" +- ಸಂಯೋಜಿತ ಪ್ರಶ್ನೆಗಳು: "ಪ್ಯಾರಿಸ್‌ನಲ್ಲಿ ಹವಾಮಾನವನ್ನು ಪರಿಶೀಲಿಸಿ ಮತ್ತು ಅದು 20°C ಕ್ಕಿಂತ ಮೇಲಾಗಿದ್ದರೆ ಹೇಳಿ" -ಎದುರಾಗಿ, ಏಜೆಂಟ್ ಸಹಜ ಭಾಷೆಯನ್ನು ಹೇಗೆ ಅರ್ಥಮಾಡಿಕೊಂಡು ಸೂಕ್ತ ಉಪಕರಣ ಕರೆಗಳಿಗೆ ನಕ್ಷೆ ಮಾಡಿ ಎಂದು ಗಮನಿಸಿ. +ಎಷ್ಟು ಸಾದರವಾಗಿ ಏಜೆಂಟ್ ಪ್ರಕೃತಿಯ ಭಾಷೆಯನ್ನು ಅರ್ಥಮಾಡುತ್ತದೆಯೆಂದು ಮತ್ತು ಒತ್ತಾಯಿತೂಲ ಕಾಲ್‌ಗಳಿಗೆ ಹೋಲಿಕೆ ಮಾಡುತ್ತದೆಯೆಂದು ಗಮನಿಸಿ. -## ಪ್ರಮುಖ ಕಲ್ಪನೆಗಳು +## ಮುಖ್ಯ ಪರಿಕಲ್ಪನೆಗಳು -### ReAct ಮಾದರಿ (ತರ್ಕ ಮತ್ತು ಕ್ರಿಯೆ) +### ReAct ಮಾದರಿ (ತರ್ಕ ಮತ್ತು ಕಾರ್ಯ) -ಏಜೆಂಟ್ ತರ್ಕ (ಎನ್ನುವುದು ಹೇಗೆ ಎಂಬುದನ್ನು ನಿರ್ಧರಿಸುವುದು) ಮತ್ತು ಕ್ರಿಯೆ (ಉಪಕರಣಗಳನ್ನು ಬಳಸುವುದು) ನಡುವೆ ಬದಲಾಯಿಸುತ್ತಾನೆ. ಈ ಮಾದರಿ ಸ್ವಾಯತ್ತ ಸಮಸ್ಯಾ ಪರಿಹಾರವನ್ನು ಅನುಮತಿಸುತ್ತದೆ, ಕೇವಲ ಸೂಚನೆಗಳಿಗೆ ಪ್ರತಿಕ್ರಿಯಿಸುವುದನ್ನು ಮಾತ್ರವಲ್ಲ. +ಏಜೆಂಟ್ ತರ್ಕ (ಏನು ಮಾಡಬೇಕು ಎಂದು ನಿರ್ಧರಿಸುವುದು) ಮತ್ತು ಕಾರ್ಯ (ಟೂಲ್‌ಗಳನ್ನು ಬಳಸುವುದು) ನಡುವೆ ಪರ್ಯಾಯವಾಗಿ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ. ಈ ಮಾದರಿ ಸ್ವಾಯತ್ತವಾದ ಸಮಸ್ಯಾ ಪರಿಹಾರಕ್ಕೆ ಅವಕಾಶ ನೀಡುತ್ತದೆ, ಆದರೆ ಕೇವಲ ಸೂಚನೆಗಳಿಗೆ ಪ್ರತಿಕ್ರಿಯಿಸುವುದಕ್ಕೆ ಅಲ್ಲ. -### ಉಪಕರಣ ವಿವರಣೆಗಳು ಪ್ರಮುಖವಾಗಿವೆ +### ಉಪಕರಣ ವಿವರಣೆಗಳು ಮುಖ್ಯ -ನಿಮ್ಮ ಉಪಕರಣಗಳ ವಿವರಣೆಗಳ ಗುಣಮಟ್ಟದಿಂದ ಏಜೆಂಟ್ ಅವುಗಳನ್ನು ಹೇಗೆ ಬಳಸುತ್ತದೆ ಎಂಬುದನ್ನು ನೇರವಾಗಿ ಪ್ರಭಾವಿಸುತ್ತದೆ. ಸ್ಪಷ್ಟ, ವಿಶೇಷ ವಿವರಣೆಗಳು ಮಾದರಿಯನ್ನು ಯಾವಾಗ ಮತ್ತು ಹೇಗೆ ಉಪಕರಣವನ್ನು ಕರೆಮಾಡಬೇಕೆಂದು ಸಹಾಯಮಾಡುತ್ತವೆ. +ನಿಮ್ಮ ಉಪಕರಣ ವಿವರಣೆಗಳ ಗುಣಮಟ್ಟ ನೇರವಾಗಿ ಏಜೆಂಟ್ ಅವುಗಳನ್ನು ಹೇಗೆ ಬಳಸುವುದನ್ನು ಪ್ರಭಾವಿಸುತ್ತದೆ. ಸ್ಪಷ್ಟ, ನಿರ್ದಿಷ್ಟ ವಿವರಣೆಗಳು ಮಾದರಿಯನ್ನು ಯಾವಾಗ ಮತ್ತು ಹೇಗೆ ಪ್ರತಿಯೊಂದು ಉಪಕರಣವನ್ನು ಕರೆದುಕೊಳ್ಳಬೇಕು ಎಂಬುದನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳಲು ಸಹಾಯ ಮಾಡುತ್ತವೆ. ### ಸೆಷನ್ ನಿರ್ವಹಣೆ -`@MemoryId` ವಿವರಿಸುವಿಕೆ ಸ್ವಯಂಚಾಲಿತ ಸೆಷನ್ ಆಧಾರಿತ ಮೆಮೊರಿ ನಿರ್ವಹಣೆಯನ್ನು ಸಕ್ರಿಯಗೊಳಿಸುತ್ತದೆ. ಪ್ರತಿ ಸೆಷನ್ ID ಒಬ್ಬದೇ ತನ್ನ `ChatMemory` ಉದಾಹರಣೆಯನ್ನು `ChatMemoryProvider` ಬೀನ್ ಮೂಲಕ ನಿರ್ವಹಿಸಲಾಗುತ್ತದೆ, ಆದ್ದರಿಂದ ಬಹು ಬಳಕೆದಾರರು ಏಜೆಂಟ್ ಜೊತೆಗೆ ಒಂದೇ ಸಮಯದಲ್ಲಿ ಸಂವಹನ ನಡೆಸಬಹುದು ಮತ್ತು ಅವರ ಸಂಭಾಷಣೆಗಳು ಮಿಶ್ರಿತವಾಗುವುದಿಲ್ಲ. ಕೆಳಗಿನ ಚಿತ್ರದಲ್ಲಿ, ಬಹು ಬಳಕೆದಾರರು ಅವರ ಸೆಷನ್ ID ಗಳ ಆಧಾರದಲ್ಲಿ ವಿಭಿನ್ನ ಮೆಮೊರಿ ಸಂಗ್ರಹಗಳಿಗೆ ಹೇಗೆ ಹಾದು ಹೋಗುತ್ತಾರೆ ಎಂಬುದು ತೋರಿಸಲಾಗಿದೆ: +`@MemoryId` ವಿವರಣೆ ಸ್ವಯಂಚಾಲಿತ ಸೆಷನ್ ಆಧಾರಿತ ಮೆಮೊರಿ ನಿರ್ವಹಣೆಯನ್ನು ಸಕ್ರಿಯಗೊಳಿಸುತ್ತದೆ. ಪ್ರತಿ ಸೆಷನ್ ID ತನ್ನದೇ ಆದ `ChatMemory` ಘಟಕವನ್ನು ಹೊಂದಿದ್ದು, ಅದನ್ನು `ChatMemoryProvider` ಬೀನ್ ನಿರ್ವಹಿಸುತ್ತದೆ, ಆದ್ದರಿಂದ ಅನೇಕ ಬಳಕೆದಾರರು ಏಜೆಂಟ್ ಜೊತೆ ಸಮತೋಲನವಾಗಿ ಸಂವಹನ ಮಾಡಬಹುದು ಅವರಿಗೆ ಸಂಭಾಷಣೆಗಳ ಮಿಶ್ರಣವಾಗದು. ಕೆಳಗಿನ ಚಿತ್ರವು ಹೇಗೆ ಅನೇಕ ಬಳಕೆದಾರರನ್ನು ಪ್ರತ್ಯೇಕ ಮೆಮೊರಿ ಅಂಗಡಿಗಳಿಗೆ ಅವರ ಸೆಷನ್ ID ಗಳ ಆಧಾರಿನಲ್ಲಿ ಮಾರ್ಗದರ್ಶನ ಮಾಡಲಾಗುತ್ತದೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ: -Session Management with @MemoryId +@MemoryId ಜೊತೆ ಸೆಷನ್ ನಿರ್ವಹಣೆ -*ಪ್ರತಿ ಸೆಷನ್ ID ಪ್ರತ್ಯೇಕ ಸಂಭಾಷಣಾ ಇತಿಹಾಸಕ್ಕೆ ನಕ್ಷೆ ಮಾಡುತ್ತದೆ — ಬಳಕೆದಾರರು ಪರಸ್ಪರ ಸಂದೇಶಗಳನ್ನು ನೋಡುವುದಿಲ್ಲ.* +*ಪ್ರತಿ ಸೆಷನ್ ID ಪ್ರತ್ಯೇಕ ಸಂಭಾಷಣಾ ಇತಿಹಾಸಕ್ಕೆ ಜೋಡಣೆ — ಬಳಕೆದಾರರು ಒಬ್ಬರ ಸಂದೇಶಗಳನ್ನು ಮತ್ತೊಬ್ಬರು ಎಂದಿಗೂ ನೋಡುವುದಿಲ್ಲ.* ### ದೋಷ ನಿರ್ವಹಣೆ -ಉಪಕರಣಗಳು ವಿಫಲವಾಗಬಹುದು — API ಗಳು ಸಮಯ ಮೀರಬಹುದು, ಪರಿಮಾಣಗಳು ತಪ್ಪಾಗಿರಬಹುದು, ಬಾಹ್ಯ ಸೇವೆಗಳು ಬಂದುಕೊಳ್ಳಬಹುದು. ಉತ್ಪಾದನಾ ಏಜೆಂಟ್‌ಗಳು ದೋಷ ನಿರ್ವಹಣೆಯನ್ನು ಹೊಂದಬೇಕು, ώστε ಮಾದರಿ ಸಮಸ್ಯೆಗಳನ್ನು ವಿವರಿಸಬಹುದು ಅಥವಾ ಬದಲಾವಣೆಗಳನ್ನು ಪ್ರಯತ್ನಿಸಬಹುದು, ಸಂಪೂರ್ಣ ಅಪ್ಲಿಕೇಶನ್ ಕ್ರ್ಯಾಶ್ ಆಗುವುದನ್ನು ತಪ್ಪಿಸಲು. ಉಪಕರಣದಲ್ಲಿ ಎಕ್ಸೆಪ್ಷನ್ Throw ಆದಾಗ, LangChain4j ಅದನ್ನು ಹಿಡಿದು ದೋಷ ಸಂದೇಶವನ್ನು ಮತ್ತೆ ಮಾದರಿಗೆ ಕಳುಹಿಸುತ್ತದೆ, ಇದು ಸಮಸ್ಯೆಯನ್ನು ಸಹಜ ಭಾಷೆಯಲ್ಲಿ ವಿವರಿಸಲು ನೆರವಾಗುತ್ತದೆ. +ಉಪಕರಣಗಳು ವಿಫಲವಾಗಬಹುದು — API ಗಳು ಸಮಯ ಮೀರಬಹುದು, ನಿಯಮಾಂಕಗಳು ಅಮಾನ್ಯವಾಗಬಹುದು, ಬಾಹ್ಯ ಸೇವೆಗಳ ನಿರ್ವಹಣೆ ಕಡಿಮೆಯಾಗಬಹುದು. ಉತ್ಪಾದನಾ ಏಜೆಂಟ್‌ಗಳು ದೋಷ ನಿರ್ವಹಣೆಯನ್ನು ಬೇಕಾಗಿರುತ್ತವೆ, ಆದ್ದರಿಂದ ಮಾದರಿ ಸಮಸ್ಯೆಗಳನ್ನು ವಿವರಿಸಲು ಅಥವಾ ಪರ್ಯಾಯ ಪ್ರಯತ್ನಿಸಲು ಸಾಧ್ಯವಾಗುತ್ತದೆ במקום ಸಂಪೂರ್ಣ ಅಪ್ಲಿಕೇಶನ್ ಕ್ರ್ಯಾಷ್ ಆಗುವುದು. ಉಪಕರಣವು ತೊಂದರೆ ಬೀರಿದಾಗ, LangChain4j ಅದನ್ನು ಹಿಡಿದು ದೋಷ ಸಂದೇಶವನ್ನು ಮಾದರಿಗೆ ಹಿಂತಿರುಗಿಸುತ್ತದೆ, ಇದರಿಂದ ಅದು ಸಾಂಸ್ಕೃತಿಕ ಭಾಷೆಯಲ್ಲಿ ಸಮಸ್ಯೆಯನ್ನು ವಿವರಿಸಬಹುದು. ## ಲಭ್ಯವಿರುವ ಉಪಕರಣಗಳು -ಕೆಳಗಿನ ಚಿತ್ರವು ನೀವು ರಚಿಸಬಹುದಾದ ಉಪಕರಣಗಳ ವಿಶಾಲ ಪರಿಸರ ವ್ಯವಸ್ಥೆಯನ್ನು ತೋರಿಸುತ್ತದೆ. ಈ ಮೊಡ್ಯೂಲ್ ಹವಾಮಾನ ಮತ್ತು ತಾಪಮಾನ ಉಪಕರಣಗಳನ್ನು ಪ್ರದರ್ಶಿಸುತ್ತದೆ, ಆದರೆ ಅದೇ `@Tool` ಮಾದರಿ ಯಾವುದೇ Java ವಿಧಾನಕ್ಕೆ ಅನ್ವಯಿಸುತ್ತದೆ — ಡೇಟಾ ಬೇಸ್ ಪ್ರಶ್ನೆಗಳಿಂದ ಪಾವತಿ ಪ್ರಕ್ರಿಯೆಗೆ. +ಕೆಳಗಿನ ಚಿತ್ರವು ನೀವು ನಿರ್ಮಿಸಬಹುದಾದ ವ್ಯಾಪಕ ಉಪಕರಣ ಸಮೂಹವನ್ನು ತೋರಿಸುತ್ತದೆ. ಈ ಮೋಡ್ಯೂಲ್ ಹವಾಮಾನ ಮತ್ತು ತಾಪಮಾನ ಉಪಕರಣಗಳನ್ನು ಪ್ರದರ್ಶಿಸುತ್ತದೆ, ಆದರೆ ಅದೇ `@Tool` ಮಾದರಿ ಯಾವುದೆ ಜಾವಾ ವಿಧಾನಕ್ಕೂ ಕೆಲಸ ಮಾಡುತ್ತದೆ — ಡೇಟಾಬೇಸ್ ಪ್ರಶ್ನೆಗಳಿಂದ ಪಾವತಿ ಪ್ರಕ್ರಿಯೆಯವರೆಗೆ. -Tool Ecosystem +ಉಪಕರಣಗಳ ಪರಿಸರ -*ಯಾವುದೇ Java ವಿಧಾನ `@Tool` ಅಟ್ಯಾನೋಟೇಶನ್ ಸಹಿತ AI ಉಪಯೋಗಕ್ಕೆ ಲಭ್ಯವಾಗುತ್ತದೆ — ಮಾದರಿ ಡೇಟಾಬೇಸ್ಗಳು, API ಗಳು, ಇಮೇಲ್, ಫೈಲ್ ಕಾರ್ಯಾಚರಣೆಗಳು ಮತ್ತು ಇನ್ನಷ್ಟು ವಿಸ್ತರಿಸಿದೆ.* +*ಯಾವುದೇ ಜಾವಾ ವಿಧಾನವನ್ನು @Tool ಅಂಕಿತಗೊಳಿಸಿದರೆ ಅದು AI ಗೆ ಲಭ್ಯವಾಗುತ್ತದೆ — ಈ ಮಾದರಿ ಡೇಟಾಬೇಸ್, API ಗಳು, ಇಮೇಲ್, ಫೈಲ್ ಚಾಲನೆಗಳು ಮತ್ತು ಇನ್ನಷ್ಟು ವಿಸ್ತರಿಸುತ್ತದೆ.* -## ಉಪಕರಣ ಆಧಾರಿತ ಏಜೆಂಟ್ ಗಳನ್ನು ಯಾವಾಗ ಬಳಸುವುದು +## ಉಪಕರಣ ಆಧಾರಿತ ಏಜೆಂಟ್‌ಗಳನ್ನು ಯಾವಾಗ ಬಳಸಬೇಕು -ಎಲ್ಲಾ ವಿನಂತಿಗಳಿಗೆ ಉಪಕರಣಗಳು hoeftಾ ಇಲ್ಲ. ತೀರ್ಮಾನವು ಏನುಂದರೆ AI ಬಾಹ್ಯ ವ್ಯವಸ್ಥೆಗಳೊಡನೆ ಸಂವಹನ ಮಾಡಬೇಕೇ ಅಥವಾ ತನ್ನ ಸ್ವಂತ ಜ್ಞಾನದಿಂದ ಉತ್ತರ ನೀಡಬಹುದೇ ಎಂಬುದು. ಕೆಳಗಿನ ಮಾರ್ಗದರ್ಶಿ ಉಪಕರಣಗಳು ಹಿತಕರವಾಗುವಾಗ ಮತ್ತು ಅವಶ್ಯಕವಿಲ್ಲದಾಗ ಯಾವುದು ಎಂದು ಸಂಕ್ಷಿಪ್ತವಾಗಿ ವಿವರಿಸುತ್ತದೆ: +ಎಲ್ಲಾ ವಿನಂತಿಗಳಿಗೂ ಉಪಕರಣಗಳ ಅಗತ್ಯವೇ ಇಲ್ಲ. ತೀರ್ಮಾನ ಎಐ ಗೆ ಹೊರಗಿನ ವ್ಯವಸ್ಥೆಗಳಿಗೆ ಸಂವಹನ ಬೇಕೋ ಅಥವಾ ತನ್ನ ಸ್ವಂತ ಜ್ಞಾನದಿಂದ ಉತ್ತರಿಸಬಹುದೋ ಎನ್ನುವುದರ್ಟಿ ಮೇಲಿದೆ. ಕೆಳಗಿನ ಮಾರ್ಗದರ್ಶಿಯು ಯಾವಾಗ ಉಪಕರಣಗಳು ಮೌಲ್ಯ ವೃದ್ಧಿ ಮಾಡುತ್ತವೆ ಮತ್ತು ಯಾವಾಗ ಅವು ಅನಾವಶ್ಯಕ ಎನ್ನುವುದನ್ನು ಸಾರುತ್ತದೆ: -When to Use Tools +ಯಾವಾಗ ಉಪಕರಣಗಳನ್ನು ಬಳಸಬೇಕು -*ತ್ವರಿತ ನಿರ್ಧಾರ ಮಾರ್ಗದರ್ಶಿ — ಉಪಕರಣಗಳು ನೈಜ-ಸಮಯ ಡೇಟಾ, ಗಣನೆಗಳು ಮತ್ತು ಕ್ರಿಯೆಗಳಿಗಾಗಿ; ಸಾಮಾನ್ಯ ಜ್ಞಾನ ಮತ್ತು ಸೃಜನಾತ್ಮಕ ಕಾರ್ಯಗಳಿಗೆ ಅವಶ್ಯಕವಿಲ್ಲ.* +*ಏಕ ತ್ವರಿತ ನಿರ್ಧಾರ ಮಾರ್ಗದರ್ಶಿ — ಉಪಕರಣಗಳು ನೈಜ ಸಮಯ ಡೇಟಾ, ಗಣನೆಗಳು, ಮತ್ತು ಕಾರ್ಯಗಳಿಗೆ; ಸಾಮಾನ್ಯ ಜ್ಞಾನ ಮತ್ತು ಸೃಜನಾತ್ಮಕ ಕಾರ್ಯಗಳಿಗೆ ಅವಶ್ಯಕವಿಲ್ಲ.* ## ಉಪಕರಣಗಳು ಮತ್ತು RAG -ಮೊಡ್ಯೂಲ್‌ಗಳು 03 ಮತ್ತು 04 ಎರಡೂ AI ಯ ಶಕ್ತಿಯನ್ನು ವಿಸ್ತಾರಗೊಳಿಸುತ್ತವೆ, ಆದೃಷ್ಠಾಂಶದಲ್ಲಿ ಬೇರೆ ರೀತಿಯಲ್ಲಿ. RAG ಮಾದರಿಗೆ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಪ್ರಾಪ್ತಿಗೊಳಿಸುವ ಮೂಲಕ **ಜ್ಞಾನ** ಕಾರ್ಯನಿರ್ವಹಿಸಲು ಅವಕಾಶ ನೀಡುತ್ತದೆ. ಉಪಕರಣಗಳು ಕಾರ್ಯಗಳನ್ನು ತಾನೆ — ಕಾರ್ಯ ನಿರ್ವಹಣೆಗಾಗಿ ಫಂಕ್ಷನ್‌ಗಳನ್ನು ಕರೆಯುವ ಮೂಲಕ. ಕೆಳಗಿನ ಚಿತ್ರದಲ್ಲಿ ಈ ಎರಡು ವಿಧಾನಗಳನ್ನು ಪಕ್ಕಪಕ್ಕವಾಗಿ ಹೋಲಿಸಲಾಗಿದೆ — ಪ್ರತಿಯೊಂದು ಕೆಲಸ ಹೇಗೆ ನಡೆಯುತ್ತದೆ ಮತ್ತು ಅವುಗಳ ನಡುವಿನ ವ್ಯತ್ಯಾಸಗಳನ್ನು ವಿವರಿಸುತ್ತವೆ: +ಮೋಡ್ಯೂಲ್‌ಗಳು 03 ಮತ್ತು 04 ಎರಡೂ AI ಮಾಡಬಹುದಾದುದನ್ನು ವಿಸ್ತರಿಸುತ್ತವೆ, ಆದರೆ ಮೂಲತಃ ವಿಭಿನ್ನ ರೀತಿಯಲ್ಲಿ. RAG ಮಾದರಿ **ಜ್ಞಾನ** ನಿಮಗೆ ನಿರ್ವಹಿಸಲಾದ ದಾಖಲಾತಿಗಳನ್ನು ಪಡೆದುಕೊಳ್ಳುವುದರ ಮೂಲಕ ಲಭ್ಯವಾಗುತ್ತದೆ. ಉಪಕರಣಗಳು, ಮಾದರಿಯು ಕಾರ್ಯಗಳನ್ನು ಕೈಗೊಳ್ಳಲು ಸಾಮರ್ಥ್ಯವನ್ನು ನೀಡುತ್ತವೆ. ಕೆಳಗಿನ ಚಿತ್ರವು ಈ ಎರಡು ರೀತಿ ನೀತಿಯಿಂದ ಸರಿಯಾದ ಹೋಲಿಕೆಯನ್ನು ನೀಡುತ್ತದೆ — ಯಾವ ರೀತಿ ಪ್ರತಿ ಕಾರ್ಯಪ್ರವಾಹ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತದೆ ಮತ್ತು ಅವುಗಳ ನಡುವೆ ವ್ಯತ್ಯಾಸ: -Tools vs RAG Comparison +ಉಪಕರಣಗಳು Vs RAG ಹೋಲಿಕೆ -*RAG ಸ್ಥಿರ ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳಿಂದ ಮಾಹಿತಿ ಪಡೆಯುತ್ತದೆ — ಉಪಕರಣಗಳು ಕ್ರಿಯೆಗಳನ್ನು ನಿರ್ವಹಿಸಿ ನೈಜ-ಸಮಯ ಡೇಟಾ ಪಡೆದುಕೊಳ್ಳುತ್ತವೆ. ಅನೇಕ ಉತ್ಪಾದನಾ ವ್ಯವಸ್ಥೆಗಳು ಎರಡನ್ನೂ ಸೇರಿಸಿ ಬಳಸುತ್ತವೆ.* +*RAG ಸ್ಥಿರ ದಾಖಲೆಗಳಿಂದ ಮಾಹಿತಿ ಪಡೆಯುತ್ತದೆ — ಉಪಕರಣಗಳು ಕ್ರಿಯೆಗಳನ್ನು ನಿರ್ವಹಿಸಿ, ಡೈನಾಮಿಕ್, ನೈಜ ಸಮಯ ಡೇಟಾ ಪಡೆಯುತ್ತವೆ. ಅನೇಕ ಉತ್ಪಾದನಾ ವ್ಯವಸ್ಥೆಗಳು ಎರಡನ್ನೂ ಸಂಯೋಜಿಸುತ್ತವೆ.* -ವಾಸ್ತವದಲ್ಲಿ, ಅನೇಕ ಉತ್ಪಾದನಾ ವ್ಯವಸ್ಥೆಗಳು ಎರಡೂ ವಿಧಾನಗಳನ್ನು ಸೇರಿಸಿ ಬಳಸುತ್ತವೆ: RAG ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟೇಷನ್‌ನಲ್ಲಿ ಉತ್ತರಗಳನ್ನು ನೆಲೆಸಲು ಮತ್ತು ಉಪಕರಣಗಳು ನೈಜ-ಸಮಯ ಡೇಟಾ ಪಡೆಯಲು ಅಥವಾ ಕಾರ್ಯಗಳನ್ನು ನಿರ್ವಹಿಸಲು. +ವಾಸ್ತವದಲ್ಲಿ, ಅನೇಕ ಉತ್ಪಾದನಾ ವ್ಯವಸ್ಥೆಗಳು ಎರಡನೇ ಮಾರ್ಗಗಳನ್ನು ಸಂಯೋಜಿಸುತ್ತವೆ: RAG ನಿಮ್ಮ ಡಾಕ್ಯುಮೆಂಟೇಶನ್‌ನಲ್ಲಿನ ಉತ್ತರಗಳಿಗೆ ಸ್ಥಿರ ನೆಲೆ ನೀಡಲು ಮತ್ತು ಉಪಕರಣಗಳು ನೈಜ ಡೇಟಾವನ್ನು ಪಡೆಯಲು ಅಥವಾ ಕಾರ್ಯಾಚರಣೆಗಳನ್ನು ನಡೆಸಲು. ## ಮುಂದಿನ ಹಂತಗಳು -**ಮುಂದಿನ ಮೊಡ್ಯೂಲ್:** [05-mcp - ಮಾದರಿ ಸಾಂದರ್ಭಿಕ ಪ್ರೋಟೋಕಾಲ್ (MCP)](../05-mcp/README.md) +**ಮುಂದಿನ ಮೋಡ್ಯೂಲ್:** [05-mcp - ಮಾದರಿ ಸನ್ನಿವೇಶ ಪ್ರೋಟೋಕಾಲ್ (MCP)](../05-mcp/README.md) --- -**ನಾವಿಗೇಶನ್:** [← ಹಿಂದಿನದು: ಮೊಡ್ಯೂಲ್ 03 - RAG](../03-rag/README.md) | [ಮೆయిన్ ಗೆ ಹಿಂತಿರುಗಿ](../README.md) | [ಮುಂದಿನದು: ಮೊಡ್ಯೂಲ್ 05 - MCP →](../05-mcp/README.md) +**ಮಾರ್ಗದರ್ಶನ:** [← ಹಿಂದಿನ: ಮೋಡ್ಯೂಲ್ 03 - RAG](../03-rag/README.md) | [ಮುಖ್ಯ ಪೃಷ್ಟೆಗೆ ಹಿಂದಿರುಗಿ](../README.md) | [ಮುಂದಿನ: ಮೋಡ್ಯೂಲ್ 05 - MCP →](../05-mcp/README.md) --- -**ಜುಮ್ಲೆ**: -ಈ ದಸ್ತಾವೇಜು [Co-op Translator](https://github.com/Azure/co-op-translator) ಎಂಬ AI ಅನುವಾದ ಸೇವೆಯ ಮೂಲಕ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ಶುದ್ದತೆಯತ್ತ ಪ್ರಯತ್ನ ಮಾಡಿದರೂ ಸಹ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳು ತಪ್ಪುಗಳನ್ನೇ ಅಥವಾ ಅಸತ್ಯತೆಯನ್ನೇ ಹೊಂದಿರಬಹುದು ಎಂಬ ಸಂಗತಿಯನ್ನು ಜ್ಞಾನದಲ್ಲಿ ಇಡಿಕೊಳ್ಳಿ. ಮೂಲ ಭಾಷೆಯಲ್ಲಿನ ಪ್ರಾಥಮಿಕ ದಸ್ತಾವೇಜನ್ನು ಪ್ರಾಮಾಣಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದ ಬಳಕೆಯಿಂದ ಉಂಟಾಗುವ ಯಾವುದೆ ತಪ್ಪು ಗ್ರಹಿಕೆ ಅಥವಾ ತಪ್ಪು ವಿವರಣೆಗಾಗಿ ನಾವು ಜವಾಬ್ದಾರಿಯಾಗಿರುವುದಿಲ್ಲ. +**ಅಸ್ವೀಕಾರ**: +ಈ ದಸ್ತಾವೇಜು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಯನ್ನು ಸಾಧಿಸಲು ಪ್ರಯತ್ನಿಸುತ್ತಿದ್ದರೂ, ದಯವಿಟ್ಟು ಗಮನಿಸಿ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ಅಸಡ್ಡೆಗಳು ಇರಬಹುದು. ಮೂಲ ಭಾಷೆಯಲ್ಲಿರುವ ಮೂಲ ದಸ್ತಾವೇಜು ಪ್ರಾಮಾಣಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದವನ್ನು ಬಳಸುವ ಮೂಲಕ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪು ಅರ್ಥಗಳ ಅಥವಾ ತಪ್ಪು ವ್ಯಾಖ್ಯಾನಗಳ ಬಗ್ಗೆ ನಾವು ಹೊಣೆಗಾರರಲ್ಲ. \ No newline at end of file diff --git a/translations/kn/README.md b/translations/kn/README.md index e91fc98d2..204bb5094 100644 --- a/translations/kn/README.md +++ b/translations/kn/README.md @@ -1,21 +1,21 @@ LangChain4j -# LangChain4j ಆರಂಭಿಕರಿಗೆ +# LangChain4j ಆರಂಭಿಕರಿಗಾಗಿ -ಬೇಸಿಕ್ ಚಾಟ್‌ನಿಂದ AI ഏಜೆಂಟ್ಗಳು ತನಕ LangChain4j ಮತ್ತು Azure OpenAI GPT-5.2 ಬಳಸಿ AI ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ಮಿಸಲು ಕೋರ್ಸ್. +LangChain4j ಮತ್ತು Azure OpenAI GPT-5.2 ನೊಂದಿಗೆ AI ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ಮಿಸುವ ಕೋರ್ಸ್, ಮೂಲಭೂತ ಚಾಟ್‌ನಿಂದ AI ಏಜೆಂಟ್ಸ್ ವರೆಗೆ. ### 🌐 ಬಹುಭಾಷಾ ಬೆಂಬಲ -#### GitHub ಕ್ರಿಯೆಯ ಮೂಲಕ ಬೆಂಬಲಿಸಲಾಗಿದೆ (ಸ್ವಯಂಚಾಲಿತ ಮತ್ತು ಯಾವಾಗಲೂ ನವೀಕರಿಸಲಾಗಿದೆ) +#### GitHub Action ಮೂಲಕ ಬೆಂಬಲಿಸಲಾಗಿದೆ (ಸ್ವಯಂಚಾಲಿತ ಮತ್ತು ಯಾವಾಗಲೂ ನವೀಕರಿಸಲಾಗಿದೆ) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](./README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **ಸ್ಥಳೀಯವಾಗಿ ಕ್ಲೋನ್ ಮಾಡಲು ಇಚ್ಛಿಸುತ್ತೀರಾ?** +> **ಸ್ಥಳೀಯವಾಗಿ ಕ್ಲೋನ್ ಮಾಡಲು ಇಷ್ಟವಿದೆಯಾ?** > -> ಈ ರೆಪೊದಲ್ಲಿ 50+ ಭಾಷಾ ಅನುವಾದಗಳು ಸೇರಿವೆ, ಅದು ಡೌನ್ಲೋಡ್ ಗಾತ್ರವನ್ನು ಬಹಳ ಹೆಚ್ಚಿಸುತ್ತದೆ. ಅನುವಾದಗಳನ್ನು ಹೊರತುಪಡಿಸಿ ಕ್ಲೋನ್ ಮಾಡಲು, ಸ್ಪಾರ್ಸ್ ಔಟ್‌ಶಾಟ್ ಅನ್ನು ಬಳಸಿ: +> ಈ ರಿಪಾಜಿಟರಿಯಲ್ಲಿ 50+ ಭಾಷಾಂತರಗಳು ಸೇರಿಕೊಂಡಿದ್ದು ಡೌನ್ಲೋಡ್ ಗಾತ್ರವನ್ನು ಪ್ರಮುಖವಾಗಿ ಹೆಚ್ಚಿಸುತ್ತವೆ. ಭಾಷಾಂತರಗಳಿಲ್ಲದೆ ಕ್ಲೋನ್ ಮಾಡಲು sparse checkout ಉಪಯೋಗಿಸಿ: > -> **Bash / macOS / Linux:** +> **Bash / macOS / ಲಿನಕ್ಸ್ನಲ್ಲಿ:** > ```bash > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners @@ -29,61 +29,60 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> ಇದರ ಮೂಲಕ ಕೋರ್ಸ್ ನ ಪೂರ್ಣಗೊಳಿಸಲು ಬೇಕಾದ ಎಲ್ಲವನ್ನೂ ಹೆಚ್ಚು ವೇಗದ ಡೌನ್ಲೋಡ್ ಜೊತೆಗೆ ಪಡೆಯಬಹುದು. +> ಇದು ನಿಮಗೆ ಅಗತ್ಯವಿರುವ ಎಲ್ಲಾ ವಿಷಯಗಳನ್ನು ಹೆಚ್ಚು ವೇಗವಾಗಿ ಡೌನ್ಲೋಡ್ ಮಾಡಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ. -## ವಿಷಯಗಳ ಪಟ್ಟಿ +## ವಿಷಯಗಳ ಟೇಬಲ್ -1. [ತ್ವರಿತ ಪ್ರಾರಂಭ](00-quick-start/README.md) - LangChain4j ನೊಂದಿಗೆ ಪ್ರಾರಂಭಿಸಿ -2. [ಪರಿಚಯ](01-introduction/README.md) - LangChain4j ನ ಮೂಲ ತತ್ವಗಳು ಕಲಿಯಿರಿ -3. [ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್](02-prompt-engineering/README.md) - ಪರಿಣಾಮಕಾರಿ ಪ್ರಾಂಪ್ಟ್ ವಿನ್ಯಾಸದಲ್ಲಿ ಪರಿಣತಿ ಸಾಧಿಸಿ -4. [RAG (ರಿಟ್ರೈವಲ್-ಆಧ್ಯಾಯಿತ ಜನರೇಷನ್)](03-rag/README.md) - ಬುದ್ಧಿವಂತಿಕೆಯ ವಿಷಯಾಧಾರಿತ ಪದ್ಧತಿಗಳನ್ನು ನಿರ್ಮಿಸಿ -5. [ಉಪಕರಣಗಳು](04-tools/README.md) - ಬಾಹ್ಯ ಉಪಕರಣಗಳು ಮತ್ತು ಸರಳ ಸಹಾಯಕರನ್ನು ಸಂಯೋಜಿಸಿ -6. [MCP (ಮಾಡೆಲ್ ಕಾಂಟೆಕ್ಸ್ಟ್ ಪ್ರೋಟೋಕಾಲ್)](05-mcp/README.md) - ಮಾದರಿ ಕಾಂಟೆಕ್ಸ್ಟ್ ಪ್ರೋಟೋಕಾಲ್ (MCP) ಮತ್ತು ಏಜೆಂಟಿಕ್ ಮಡ್ಯೂಲ್‌ಗಳೊಂದಿಗೆ ಕೆಲಸ ಮಾಡಿ +1. [ಪರಿಚಯ](01-introduction/README.md) - LangChain4j ಮೂಲತತ್ವಗಳನ್ನು ಕಲಿಯಿರಿ +2. [ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್](02-prompt-engineering/README.md) - ಪರಿಣಾಮಕಾರಿ ಪ್ರಾಂಪ್ಟ್ ವಿನ್ಯಾಸದಲ್ಲಿ ಪರಿಣತಿ ಪಡೆಯಿರಿ +3. [RAG (ರಿಟ್ರೀವಲ್-ಆಗ್ಮೆಂಟೆಡ್ ಜನರೇಷನ್)](03-rag/README.md) - ಬುದ್ಧಿವಂತ ಜ್ಞಾನ ಆಧಾರಿತ ವ್ಯವಸ್ಥೆಗಳು ನಿರ್ಮಿಸಿ +4. [ಉಪಕರಣಗಳು](04-tools/README.md) - ಹೊರಗಿನ ಸಾಧನಗಳನ್ನು ಮತ್ತು ಸರಳ ಸಹಾಯಕರನ್ನು ಸಂಯೋಜಿಸಿ +5. [MCP (ಮೋಡೆಲ್ ಕಾಂಟೆಕ್ಸ್ಟ್ ಪ್ರೋಟೋಕಾಲ್)](05-mcp/README.md) - Model Context Protocol (MCP) ಮತ್ತು ಏಜೆಂಟಿಕ್ ಮಾಯುಲುಗಳೊಂದಿಗೆ ಕೆಲಸ ಮಾಡಿರಿ -### ವೀಡಿಯೋ ವಾಕ್‌ಥ್ರೂಗಳು +### ವೀಡಿಯೊ ವಾಕ್ತ್ರೂಗಳು -ಪ್ರತಿ ಮಡ್ಯೂಲ್‌ಗೆ ಒಂದು ಸಮಕಾಲೀನ ಲೈವ್ ಸತ್ರವಿದೆ, ಅಲ್ಲಿ ನಾವು ಸಂಜ್ಞೆಗಳು ಮತ್ತು ಕೋಡ್ ಅನ್ನು ಹಂತ ಹಂತವಾಗಿ ಪಾಠಮಾಡುತ್ತೇವೆ. +ಪ್ರತಿಯೊಂದು ಘಟಕಕ್ಕೂ ಒಂದು ಲೈವ್ ಸೆಷನ್ ಇದೆ, ಅಲ್ಲಿ ನಾವು ತತ್ವಗಳು ಮತ್ತು ಕೋಡ್ ಅನ್ನು ಹೆಜ್ಜೆ ಹೆಜ್ಜೆಗೆ ಅನುಸರಿಸಿ ಪರಿಶೀಲಿಸುತ್ತೇವೆ. -| ಮಡ್ಯೂಲ್ | ವೀಡಿಯೋ | -|--------|---------| -| 01 - ಪರಿಚಯ | [LangChain4j ನೊಂದಿಗೆ ತ್ವರಿತ ಪ್ರಾರಂಭ](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್ | [LangChain4j ಸಹಿತ ಪ್ರಾಂಪ್ಟ್ ಇಂಜಿನಿಯರಿಂಗ್](https://www.youtube.com/live/PJ6aBaE6bog) | +| ಘಟಕ | ವೀಡಿಯೊ | +|--------|-------| +| 01 - ಪರಿಚಯ | [LangChain4j ಜೊತೆ ಆರಂಭಿಸುವುದು](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ | [LangChain4j ಜೊತೆಗೆ ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [LangChain4j ಜೊತೆ RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - ಉಪಕರಣಗಳು ಮತ್ತು 05 - MCP | [ಉಪಕರಣಗಳು ಮತ್ತು MCP ಸಹಿತ AI ಏಜೆಂಟ್ಗಳು](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - ಉಪಕರಣಗಳು & 05 - MCP | [ಉಪಕರಣಗಳು ಮತ್ತು MCP ಇರುವ AI ಏಜೆಂಟ್ಸ್](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## ಅಧ್ಯಯನ ಮಾರ್ಗ +## ಅಧ್ಯಯನ ಪಥ -**LangChain4jನಲ್ಲಿ ಹೊಸವರು?** ಮುಖ್ಯ ಪದಗಳು ಮತ್ತು ಸಂಜ್ಞೆಗಳ ವ್ಯಾಖ್ಯಾನಕ್ಕಾಗಿ [ಕೋಶ](docs/GLOSSARY.md) ನೋಡಿ. +**LangChain4j ಹೊಸದಾಗಿದೆಯೇ?** ಪ್ರಮುಖ ಪದಗಳು ಮತ್ತು ತತ್ವಗಳ ವ್ಯಾಖ್ಯಾನಗಳಿಗೆ [ಗ್ಲಾಸರಿ](docs/GLOSSARY.md) ನೋಡಿ. > **ತ್ವರಿತ ಪ್ರಾರಂಭ** -1. ಈ ರೆಪೊವನ್ನು ನಿಮ್ಮ GitHub ಖಾತೆಗೆ Fork ಮಾಡಿ -2. **Code** → **Codespaces** ಟ್ಯಾಬ್ → **...** → **ಹೊಸ ಆಯ್ಕೆಯೊಂದಿಗೆ...** ಮೇಲೆ ಕ್ಲಿಕ್ ಮಾಡಿ -3. ಪೂರ್ವನಿಗದಿತವನ್ನು ಬಳಸಿ – ಇದು ಈ ಕೋರ್ಸಿಗೆ ತಯಾರಿಸಿದ ಡೆವಲಪ್ಮೆಂಟ್ ಕಾಂಟೇನರ್ ಆಯ್ಕೆ ಮಾಡುತ್ತದೆ -4. **Codespace ರಚಿಸಿ** ಕ್ಲಿಕ್ ಮಾಡಿ +1. ಈ ರಿಪಾಜಿಟರಿಯನ್ನು ನಿಮ್ಮ GitHub ಖಾತೆಗೆ ಫೋರ್ಕ್ ಮಾಡಿ +2. **Code** → **Codespaces** ಟ್ಯಾಬ್ → **...** → **ಹೊಸ ಆಯ್ಕೆಗಳು ಬಳಸಿ...** ಕ್ಲಿಕ್ ಮಾಡಿ +3. ಮೂಲಭೂತಗಳನ್ನು ಬಳಸಿ – ಇದು ಈ ಕೋರ್ಸ್‌ಗೆ ವಿನಿರ್ಮಿತ ಡೆವಲಪ್‌ಮೆಂಟ್ ಕಂಟೇನರ್ ಆಯ್ಕೆ ಮಾಡುತ್ತದೆ +4. **Create codespace** ಕ್ಲಿಕ್ ಮಾಡಿ 5. ಪರಿಸರ ಸಿದ್ಧವಾಗಲು 5-10 ನಿಮಿಷ ಕಾಯಿರಿ -6. ತಕ್ಷಣವೇ ಪ್ರಾರಂಭಿಸಲು [ತ್ವರಿತ ಪ್ರಾರಂಭ](./00-quick-start/README.md) ಗೆ ಜಂಪ್ ಮಾಡಿ! +6. ಪ್ರಾರಂಭಿಸಲು ನೇರವಾಗಿ [ಪರಿಚಯ](./01-introduction/README.md) ಗೆ ಹೋಗಿ! -ಮಡ್ಯೂಲ್‌ಗಳನ್ನು ಪೂರ್ಣಗೊಳಿಸಿದ ನಂತರ, LangChain4j ಟೆಸ್ಟಿಂಗ್ ತತ್ತ್ವಗಳನ್ನು ಕ್ರಿಯಾಶೀಲವಾಗಿ ನೋಡಲು [ಟೆಸ್ಟಿಂಗ್ ಗೈಡ್](docs/TESTING.md) ಅನ್ನು ಅನ್ವೇಷಿಸಿ. +ಘಟಕಗಳನ್ನು ಪೂರ್ಣಗೊಳಿಸಿದ ಬಳಿಕ, LangChain4j ಪರೀಕ್ಷಾ ತತ್ವಗಳನ್ನು ಅನುಭವಿಸಲು [ಪರೀಕ್ಷಾ ಮಾರ್ಗದರ್ಶಿ](docs/TESTING.md) ಅನ್ನು ಅನ್ವೇಷಿಸಿ. -> **ಗಮನಿಸಿ:** ಈ ತರಬೇತಿ GitHub ಮಾದರಿಗಳ ಮತ್ತು Azure OpenAI ಎರಡನ್ನೂ ಬಳಸುತ್ತದೆ. [ತ್ವರಿತ ಪ್ರಾರಂಭ](00-quick-start/README.md) ಮಡ್ಯೂಲ್ GitHub ಮಾದರಿಗಳನ್ನು ಬಳಸುತ್ತದೆ (Azure ಸಬ್ಸ್ಕ್ರಿಪ್ಷನ್ ಅಗತ್ಯವಿಲ್ಲ), ಆದರೆ 1-5 ಮಡ್ಯೂಲ್‌ಗಳು Azure OpenAI ಬಳಕೆ ಮಾಡುತ್ತವೆ. ನೀವು ಹೊಂದಿಲ್ಲದಿದ್ದರೆ [ಉಚಿತ Azure ಖಾತೆ](https://aka.ms/azure-free-account) ಜೊತೆಗೆ ಪ್ರಾರಂಭಿಸಿ. +> **ಸೂಚನೆ:** ಈ ತರಬೇತಿ Azure OpenAI ಅನ್ನು ಬಳಸುತ್ತದೆ. ನಿಮಗೆ ಇಲ್ಲದಿದ್ದರೆ [ಉಚಿತ Azure ಖಾತೆ](https://aka.ms/azure-free-account) ಮೂಲಕ ಪ್ರಾರಂಭಿಸಿ. -## GitHub Copilot ಜೊತೆಗೆ ಅಧ್ಯಯನ +## GitHub Copilot ಮೂಲಕ ಅಧ್ಯಯನ -ತ್ವರಿತವಾಗಿ ಕೊಂಡಿಡಿಂಗ್ ಮಾಡಲು, ಈ ಯೋಜನೆಯನ್ನು GitHub Codespace ಅಥವಾ ಸ್ಥಳೀಯ IDE ನಲ್ಲಿ devcontainer ಜೊತೆಗೆ ತೆರೆಯಿರಿ. ಈ ಕೋರ್ಸ್‌ನಲ್ಲಿ ಬಳಸಲಾಗುವ devcontainer GitHub Copilot ನೊಂದಿಗೆ ಪೂರ್ವ-ಕಾನ್ಫಿಗರ್ ಆಗಿದೆ AI ಜೋಡಿನ ಪ್ರೋಗ್ರಾಮಿಂಗ್‌ಗೆ. +ತ್ವರಿತವಾಗಿ ಕೋಡಿಂಗ್ ಪ್ರಾರಂಭಿಸಲು, ಈ ಯೋಜನೆಯನ್ನು GitHub Codespace ಅಥವಾ ನಿಮ್ಮ ಸ್ಥಳೀಯ IDE ಯಲ್ಲಿ devcontainer ಜೊತೆ ತೆರೆಯಿರಿ. ಈ ಕೋರ್ಸ್‌ನಲ್ಲಿ ಬಳಕೆಯಾದ devcontainer AI ಜತೆಗೆ ಜೋಡಣಾ ಪ್ರೋಗ್ರಾಮಿಂಗ್‌ಗೆ GitHub Copilot ಪೂರ್ವಕಂಡಿತವಾಗಿದೆ. -ಪ್ರತಿ ಕೋಡ್ ಉದಾಹರಣೆಯಲ್ಲಿ GitHub Copilot ಗೆ ಕೇಳಬಹುದಾದ ಪ್ರಸ್ತಾಪಿತ ಪ್ರಶ್ನೆಗಳಿವೆ, ಇದು ನಿಮ್ಮ ಅರ್ಥೈಸಿಕೆಯನ್ನು ಗಾಢವಾಗಿಸುತ್ತದೆ. ಕೆಳಗಿನ ಕಡೆ 💡/🤖 ಸೂಚನೆಗಳನ್ನು ನೋಡಿ: +ಪ್ರತಿ ಕೋಡ್ ಉದಾಹರಣೆಯು GitHub Copilot ಗೆ ಕೇಳಬಹುದಾದ ಸಲಹೆಗಳ ಪ್ರಶ್ನೆಗಳನ್ನು ಒಳಗೊಂಡಿರುತ್ತದೆ, ಇದು ನಿಮ್ಮ ಅರ್ಥವನ್ನು ಗಾಢಗೆ ಮಾಡುತ್ತದೆ. ಕೆಳಗಿನ ಸ್ಥಳಗಳಲ್ಲಿ 💡/🤖 ಟಿಪ್ಪಣಿಗಳನ್ನು ಹುಡುಕಿ: -- **ಜಾವಾ ಫೈಲ್ ಶೀರ್ಷಿಕೆಗಳು** - ಪ್ರತಿ ಉದಾಹರಣೆಗೆ ವಿಶೇಷವಾದ ಪ್ರಶ್ನೆಗಳು -- **ಮಡ್ಯೂಲ್ READMEಗಳು** - ಕೋಡ್ ಉದಾಹರಣೆಯ ನಂತರ ಅನ್ವೇಷಣೆಯ ಪ್ರಸ್ತಾಪಗಳು +- **ಜಾವಾ ಕಡತದ ಹೆಡರ್ಸ್** - ಪ್ರತಿ ಉದಾಹರಣೆಗೆ ವಿಶೇಷವಾದ ಪ್ರಶ್ನೆಗಳು +- **ಘಟಕಗಳ READMEಗಳು** - ಕೋಡ್ ಉದಾಹರಣೆಗಳ ನಂತರದ ಅನ್ವೇಷಣೆ ಪ್ರಶ್ನೆಗಳು -**ಹೇಗೆ ಬಳಕೆ ಮಾಡುವುದು:** ಯಾವುದೇ ಕೋಡ್ ಫೈಲ್ ತೆರೆಯಿರಿ ಮತ್ತು ಪ್ರಸ್ತಾಪಿತ ಪ್ರಶ್ನೆಗಳು Copilot ಗೆ ಕೇಳಿ. ಈ ಹೆಸರು ಹಾಗೂ ಕೋಡ್‌ಬೇಸ್‌ನ ಸಂಪೂರ್ಣ ಪೋಷಣೆಯೊಂದಿಗೆ ಇದೆ ಮತ್ತು ವಿವರಣೆ, ವಿಸ್ತರಣೆ ಮತ್ತು ಪರ್ಯಾಯ ತಿಳಿಸಬಹುದು. +**ಬಳಸದ ವಿಧಾನ:** ಯಾವುದಾದ್ರೊಂದು ಕೋಡ್ ಫೈಲ್ ತೆರೆಯಿರಿ ಮತ್ತು Copilot ಗೆ ಸಲಹೆ ಮಾಡಿದ ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳಿ. ಇದಕ್ಕೆ ಸಂಪೂರ್ಣ ಕೋಡ್ ಪರಿಧಿ ಅರ್ಥವಾಗಿದ್ದು, ವಿವರಿಸುವುದು, ವಿಸ್ತರಿಸುವುದು ಮತ್ತು ಪರ್ಯಾಯಗಳನ್ನು ಸೂಚಿಸುವುದೂ ಇದೆ. -ಇನ್ನಷ್ಟು ತಿಳಿಯಲು ಇಚ್ಛೆಯಿದೆಯೇ? ನೋಡಿ [AI ಜೋಡಿನ ಪ್ರೋಗ್ರಾಮಿಂಗ್ Copilot](https://aka.ms/GitHubCopilotAI). +ಹೆಚ್ಚು ಕಲಿಯಲು ಬಯಸುವಿರಾ? [AI ಜೊತೆಯ ಕಾರ್ಯಕ್ರಮಕ್ಕೆ Copilot](https://aka.ms/GitHubCopilotAI) ನೋಡಿ. ## ಹೆಚ್ಚುವರಿ ಸಂಪನ್ಮೂಲಗಳು @@ -103,7 +102,7 @@ --- -### ತಯಾರಣಾತ್ಮಕ AI ಸರಣಿ +### Generative AI Series [![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) @@ -115,36 +114,36 @@ [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![ಆರಂಭಿಕರಿಗಾಗಿ ಸೈಬರ್‌ಸಿಕ್ಯುರಿಟಿ](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![ಆರಂಭಿಕರಿಗಾಗಿ ವೆಬ್ ಡೆವ್](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![ಆರಂಭಿಕರಿಗಾಗಿ ಐಒಟಿ](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![ಆರಂಭಿಕರಿಗಾಗಿ ಎಕ್ಸ್‌ಆರ್ ಅಭಿವೃದ್ಧಿ](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### ಕೋಪಿಲಟ್ ಸರಣಿ -[![AI ಜೋಡಿಯ ಪ್ರೋಗ್ರಾಮಿಂಗ್‌ಗೆ ಕೋಪಿಲಾಟ್](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET ಗೆ ಕೋಪಿಲಾಟ್](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![ಕೋಪಿಲಾಟ್ ಸಾಹಸ](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +### ಕೋಪೈಲಟ್ ಸರಣಿ +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## ಸಹಾಯ ಪಡೆಯುವುದು -ನೀವು ಅಡ್ಡಪಡೆದರೆ ಅಥವಾ AI ಅಪ್ಲಿಕೇಶನ್ಗಳ ರಚನೆ ಬಗ್ಗೆ ಯಾವುದೇ ಪ್ರಶ್ನೆಗಳು ಇದ್ದರೆ, ಸೇರಿ: +ನೀವು ಅಡ್ಡಿದರೆ ಅಥವಾ AI ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ನಿರ್ಮಿಸುವ ಬಗ್ಗೆ ಯಾವುದೇ ಪ್ರಶ್ನೆಗಳಿದ್ದರೆ, ಸೇರಿ: -[![ಮೈಕ್ರೋಸಾಫ್ಟ್ ಫೌಂಡ್ರಿ ಡಿಸ್ಕೋರ್ಡ್](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) +[![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -ನೀವು ಉತ್ಪನ್ನ ಪ್ರತಿಕ್ರಿಯೆ ಅಥವಾ ದೋಷಗಳನ್ನು ಕಾಣಿಸುವಾಗ ಭೇಟಿಮಾಡಿ: +ನೀವು ಉತ್ಪನ್ನ ಪ್ರತಿಕ್ರಿಯೆ ಅಥವಾ ನಿರ್ಮಿಸುವ ಸಮಯದಲ್ಲಿ ತೊಂದರೆಗಳಿದ್ದರೆ ಇಲ್ಲಿ ಭೇಟಿ ನೀಡಿ: -[![ಮೈಕ್ರೋಸಾಫ್ಟ್ ಫೌಂಡ್ರಿ ಡೆವಲಪರ್ ಫೋರಂ](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) +[![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## ಪರವಾನಗಿ -MIT ಪರವಾನಗಿ - ವಿವರಗಳಿಗೆ [LICENSE](../../LICENSE) ಕಡತ ನೋಡಿ. +MIT ಪರವಾನಗಿ - ವಿವರಗಳಿಗೆ [LICENSE](../../LICENSE) ಕಡತವನ್ನು ನೋಡಿ. --- -**ತಪ್ಪಿತಡೆ:** -ಈ ದಸ್ತಾವೇಜು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ಶುದ್ಧತೆಯಿಗಾಗಿ ಪ್ರಯತ್ನಿಸುತ್ತಿರುವದರಿಂದ, ದಯವಿಟ್ಟು ಗಮನಿಸಿ ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ತಪ್ಪುಗಳು ಇರಬಹುದಾಗಿದೆ. ಅದರ ಮೂಲ ಭಾಷೆಯ ವರದಿಯನ್ನು ಪ್ರಾಮಾಣಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಮಹತ್ವದ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದೋಪಯೋಗದಿಂದ ಸಂಭವಿಸಬಹುದಾದ ಯಾವುದೇ ದುರವಧಾನಗಳು ಅಥವಾ ತಪ್ಪು ಅರ್ಥಗೊಳ್ಳಿಕೆಗೆ ನಾವು ಹೊಣೆಗಾರರಾಗುತ್ತೇವೆ. +**ಅಸ್ವೀಕಾರ**: +ಈ ದಸ್ತಾವೇಜು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಯನ್ನು ಸಾಧಿಸಲು ಪ್ರಯತ್ನಿಸುತ್ತಿದ್ದರೂ, ದಯವಿಟ್ಟು ಗಮನಿಸಿ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ಅಸಡ್ಡೆಗಳು ಇರಬಹುದು. ಮೂಲ ಭಾಷೆಯಲ್ಲಿರುವ ಮೂಲ ದಸ್ತಾವೇಜು ಪ್ರಾಮಾಣಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದವನ್ನು ಬಳಸುವ ಮೂಲಕ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪು ಅರ್ಥಗಳ ಅಥವಾ ತಪ್ಪು ವ್ಯಾಖ್ಯಾನಗಳ ಬಗ್ಗೆ ನಾವು ಹೊಣೆಗಾರರಲ್ಲ. \ No newline at end of file diff --git a/translations/kn/docs/GLOSSARY.md b/translations/kn/docs/GLOSSARY.md index eb20ca0fe..017605f0b 100644 --- a/translations/kn/docs/GLOSSARY.md +++ b/translations/kn/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j ಶಬ್ದಕೋಶ +# LangChain4j ಗ್ಲಾಸ್ಸರಿ -## ವಿಷಯಗಳ ಪಟ್ಟಿಯನ್ನು +## ವಿಷಯ সূಚೀ -- [ಮೂಲಗರcstring್ಯಂಗಳು](../../../docs) -- [LangChain4j ಘಟಕಗಳು](../../../docs) -- [AI/ML ಸಂಯೋಜನೆಗಳು](../../../docs) -- [ಗಾರ್ಡರೈಲ್ಸ್](../../../docs) -- [ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್](../../../docs) -- [RAG (ಪುನಃಯೋಜಿತ ಉತ್ಪಾದನೆ)](../../../docs) -- [ಏಜೆಂಟುಗಳು ಮತ್ತು ಟೂಲ್ಸ್](../../../docs) -- [ಏಜೆಂಟಿಕ್ ಮODULE](../../../docs) -- [ಮಾಡೆಲ್ ಕಾಂಟೆಕ್ಸ್ಟ್ ಪ್ರೋಟೋಕಾಲ್ (MCP)](../../../docs) -- [ಅಜುರ್ ಸೇವೆಗಳು](../../../docs) -- [ಪರೀಕ್ಷಾ ಮತ್ತು ಅಭಿವೃದ್ಧಿ](../../../docs) +- [ಮುಖ್ಯ ತತ್ವಗಳು](#ಮುಖ್ಯ-ತತ್ವಗಳು) +- [LangChain4j ಘಟಕಗಳು](#langchain4j-ಘಟಕಗಳು) +- [AI/ML ತತ್ವಗಳು](#aiml-ತತ್ವಗಳು) +- [ರಕ್ಷಣಾ ಮಾರ್ಗಗಳು](#ರಕ್ಷಣಾ-ಮಾರ್ಗಗಳು) +- [ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್](#prompt-engineering---module-02) +- [RAG (ಮರುಪಡೆಯುವ ಅನ್ವಯ ಸಂಕಲನ)](#rag-retrieval-augmented-generation---module-03) +- [ಏಜೆಂಟ್ಸ್ ಮತ್ತು ಉಪಕರಣಗಳು](#agents-and-tools---module-04) +- [ಏಜೆಂಟಿಕ್ ಮಾಡ್ಯೂಲ್](#agentic-module---module-05) +- [ಮಾದರಿ ಸಾಂದರ್ಭಿಕ ಪ್ರೋಟೋಕಾಲ್ (MCP)](#model-context-protocol-mcp---module-05) +- [ಅಜೂರ್ ಸೇವೆಗಳು](#azure-services---module-01) +- [ಪರೀಕ್ಷಣೆ ಮತ್ತು ಅಭಿವೃದ್ಧಿ](#testing-and-development---testing-guide) -ಕೋರ್ಸ್‌ನಲ್ಲಿ ಬಳಕೆಯಾಗುವ ಪದಗಳು ಮತ್ತು ಸಂಯೋಜನೆಗಳ ತ್ವರಿತ ಸೂತ್ರ. + ಕೋರ್ಸ್‌ನಲ್ಲಿ ಬಳಕೆ ಮಾಡಿರುವ ಪದಗಳು ಮತ್ತು ತತ್ವಗಳ ವೇಗವಾಗಿ 術ರಣೆ. -## ಮೂಲಗರcstring್ಯಂಗಳು +## ಮುಖ್ಯ ತತ್ವಗಳು -**AI ಏಜೆಂಟ್** - ಸ್ವತಂತ್ರವಾಗಿ ತರ್ಕ್ಮಾಡಿ ಮತ್ತು ಕಾರ್ಯಾನುಷ್ಠಾನ ಮಾಡುವ AI ಉಪಾಯಕ ವ್ಯವಸ್ಥೆ. [ಮಾಡ್ಯೂಲ್ 04](../04-tools/README.md) +**AI ಏಜೆಂಟ್** - AI ಬಳಸಿಕೊಂಡು ಸ್ವಯಂಚಾಲಿತವಾಗಿ ಯೋಚನೆ ಮತ್ತು ಕಾರ್ಯನಿರ್ವಹಿಸುವ ವ್ಯವಸ್ಥೆ. [ಮಾಡ್ಯೂಲ್ 04](../04-tools/README.md) -**ಚೈನ್** - ನಿರಂತರ ಕಾರ್ಯಾಲಯಗಳ ಸರಪಳಿ, ಒಂದು ಹೊರತಂಡವು ಮುಂದಿನ ಹಂತಕ್ಕೆ ಆಹಾರ ನೀಡುತ್ತದೆ. +**ಚೈನ್** - ಕ್ರಮವಾಗಿ ನಡೆಯುವ ಕಾರ್ಯದ ಸಾಲು, ಹೊರತುಪಡಿಸಿ ಮುಂದಿನ ಹಂತಕ್ಕೆ ಇತ್ಯರ್ಥ ನೀಡಿ. -**ಚಂಕಿಂಗ್** - ದಾಖಲೆಗಳನ್ನು ಚಿಕ್ಕ ತುಂಡುಗಳಾಗಿ ವಿಭಜಿಸುವುದು. ಸಾಮಾನ್ಯ: 300-500 ಟೋಕನ್‌ಗಳು ನಿಧಾನವಾಗಿ ಒಪ್ಪಂದ. [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) +**ಚಂಕಿಂಗ್** - ದಸ್ತಾವೇಜುಗಳನ್ನು ಸಣ್ಣ ತುಂಡುಗಳಾಗಿ ವಿಭಜಿಸುವುದು. ಸಾಮಾನ್ಯ: 300-500 ಟೋಕನ್ಸ್ ಮೇಲೆ ನಡೆಯುತ್ತದೆ. [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) -**ಕಾಂಟೆಕ್ಸ್ಟ್ ವಿಂಡೋ** - ಮಾದರಿಯು ಪ್ರಕ್ರಿಯೆ ಮಾಡಬಹುದಾದ ಗರಿಷ್ಠ ಟೋಕನ್‌ಗಳು. GPT-5.2: 400,000 ಟೋಕನ್‌ಗಳು (272,000 ಇನ್‌ಪುಟ್, 128,000 ಔಟ್‌ಪುಟ್ ವರೆಗೆ). +**ಸಾಂದರ್ಭಿಕ ವಿಂಡೋ** - ಮಾದರಿ ಪ್ರಕ್ರಿಯೆಸಬಹುದಾದ ಗರಿಷ್ಠ ಟೋಕನ್ಸ್. GPT-5.2: 400K ಟೋಕನ್ಸ್ (ಗರಿಷ್ಠ 272K ಇನ್‌ಪುಟ್, 128K ಔಟ್‌ಪುಟ್). **ಎಂಬೆಡ್ಡಿಂಗ್ಸ್** - ಪಠ್ಯದ ಅರ್ಥವನ್ನು ಪ್ರತಿನಿಧಿಸುವ ಸಂಖ್ಯಾತ್ಮಕ ವೆಕ್ಟರ್‌ಗಳು. [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) -**ಫಂಕ್ಷನ್ ಕಾಲಿಂಗ್** - ಮಾದರಿ ಹೊರಗಿನ ಕಾರ್ಯಗಳನ್ನು ಕರೆ ಮಾಡಲು ರಚನೆಯ ವಿನಂತಿಗಳನ್ನು ಉತ್ಪಾದಿಸುತ್ತದೆ. [ಮಾಡ್ಯೂಲ್ 04](../04-tools/README.md) +**ಫಂಕ್ಷನ್ ಕರೆ** - ಮಾದರಿ ಬಾಹ್ಯ ಕಾರ್ಯಗಳನ್ನು ಕರೆ ಮಾಡುವುದು ಈಡೇರಿಸುವ ರಚನಾತ್ಮಕ ವಿನಂತಿಗಳನ್ನು ತಯಾರಿಸುತ್ತದೆ. [ಮಾಡ್ಯೂಲ್ 04](../04-tools/README.md) -**ಹ್ಯಾಲೂಸಿನೇಷನ್** - ಮಾದರಿಗಳು ತಪ್ಪು ಆದರೆ ಸಾಧ್ಯತೆಯ ಮಾಹಿತಿಯನ್ನು ರಚಿಸುವಾಗ. +**ಹ್ಯಾಲ್ಯೂಸಿನೇಷನ್** - ಮಾದರಿಗಳು ತಪ್ಪಾದ ಆದರೆ ನಂಬಿಕಯೋಗ್ಯ ಮಾಹಿತಿಯನ್ನು ರಚಿಸುವಾಗ. -**ಪ್ರಾಂಪ್ಟ್** - ಭಾಷಾ ಮಾದರಿಗೆ ಪಠ್ಯದ ಇನ್‌ಪುಟ್. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) +**ಪ್ರಾಂಪ್ಟ್** - ಭಾಷಾ ಮಾದರಿಗೆ ಪಠ್ಯ ಇನ್‌ಪುಟ್. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) -**ಸೆಮ್ಯಾಂಟಿಕ್ ಶೋಧ** - ಕೀವರ್ಡ್ಗಳಿಲ್ಲದೆ ಅರ್ಥ ಬಳಸಿ ಹುಡುಕು. [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) +**ಸಮಾನಾರ್ಥಕ ಹುಡುಕು** - ಕೀವರ್ಡ್ ಬಳಕೆಯ ಬದಲು ಎಂಬೆಡ್ಡಿಂಗ್ಸ್ ಬಳಸಿ ಅರ್ಥದ ಮೂಲಕ ಹುಡುಕು. [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) -**ಸ್ಟೇಟ್‌ಫುಲ್ ವಿರುದ್ಧ ಸ್ಟೇಟ್‌ಲೆಸ್** - ಸ್ಟೇಟ್‌ಲೆಸ್: ಜ್ಞಾಪಕವಿಲ್ಲ. ಸ್ಟೇಟ್‌ಫುಲ್: ಸಂಭಾಷಣಾ ಇತಿಹಾಸವನ್ನು ಕಾಯ್ದು ಕೊಳ್ಳುತ್ತದೆ. [ಮಾಡ್ಯೂಲ್ 01](../01-introduction/README.md) +**ಸ್ಟೇಟ್‌ಫುಲ್ ವಿರುದ್ದ ಸ್ಟೇಟ್‌ಲೆಸ್** - ಸ್ಟೇಟ್‌ಲೆಸ್: ಮೇಮರಿ ಇಲ್ಲ. ಸ್ಟೇಟ್‌ಫುಲ್: ಸಂವಾದ ಇತಿಹಾಸವನ್ನು ಇಡುತ್ತದೆ. [ಮಾಡ್ಯೂಲ್ 01](../01-introduction/README.md) -**ಟೋಕನ್ಗಳು** - ಮಾದರಿಗಳು ಪ್ರಕ್ರಿಯೆ ಮಾಡುವ ಮೂಲ ಪಠ್ಯ ಘಟಕಗಳು. ವೆಚ್ಚ ಮತ್ತು ಮಿತಿಗಳನ್ನು ಪ್ರಭಾವಿಸುತ್ತದೆ. [ಮಾಡ್ಯೂಲ್ 01](../01-introduction/README.md) +**ಟೋಕನ್ಸ್** - ಮಾದರಿಗಳು ಪ್ರಕ್ರಿಯೆಸುವ ಮೂಲ ಪಠ್ಯ ಘಟಕಗಳು. ವೆಚ್ಚ ಮತ್ತು ਸੀಮಿತಗೊಳಿಸುವಿಕೆಗೆ ಪ್ರಭಾವ ಬೀರುತ್ತವೆ. [ಮಾಡ್ಯೂಲ್ 01](../01-introduction/README.md) -**ಟೂಲ್ ಚೈನಿಂಗ್** - ನಿರಂತರ ಟೂಲ್ ಕಾರ್ಯಾಚರಣೆ, ಹೊರತಂಡ ಮುಂದಿನ ಕರೆಗಾಗಿ ಮಾಹಿತಿ ನೀಡುತ್ತದೆ. [ಮಾಡ್ಯೂಲ್ 04](../04-tools/README.md) +**ಟೂಲ್ ಚೈನಿಂಗ್** - ಕ್ರಮಬದ್ಧವಾಗಿ ಉಪಕರಣ ಕಾರ್ಯಾಚರಣೆ, ಹೊರತುಪಡಿಸಿ ಮುಂದಿನ ಕರೆಗೆ ಮಾಹಿತಿ ಒದಗಿಸುವುದು. [ಮಾಡ್ಯೂಲ್ 04](../04-tools/README.md) ## LangChain4j ಘಟಕಗಳು -**AiServices** - ಪ್ರಕಾರ-ಸುರಕ್ಷಿತ AI ಸೇವಾ ಇಂಟರ್ಫೇಸ್‌ಗಳನ್ನು ರಚಿಸುತ್ತದೆ. +**AiServices** - ಟೈಪ್-ಸೇಫಾ AI ಸೇವಾ ಇಂಟರ್ಫೇಸ್‌ಗಳನ್ನು ಸೃಷ್ಟಿಸುತ್ತದೆ. -**OpenAiOfficialChatModel** - OpenAI ಮತ್ತು ಅಜುರ್ OpenAI ಮಾದರಿಗಳಿಗೆ ಏಕೀಕೃತ ಕ್ಲೈಂಟ್. +**OpenAiOfficialChatModel** - OpenAI ಮತ್ತು ಅಜೂರ್ OpenAI ಮಾದರಿಗಳಿಗಾಗಿ ಏಕೀಕೃತ ಕ್ಲೈಂಟ್. -**OpenAiOfficialEmbeddingModel** - OpenAI ಅಧಿಕೃತ ಕ್ಲೈಂಟ್ ಬಳಸಿ ಎಂಬೆಡ್ಡಿಂಗ್ಸ್ ರಚಿಸುತ್ತದೆ (OpenAI ಮತ್ತು ಅಜುರ್ OpenAI ಎರಡನ್ನೂ ಬೆಂಬಲಿಸುತ್ತದೆ). +**OpenAiOfficialEmbeddingModel** - OpenAI ಅಧಿಕೃತ ಕ್ಲೈಂಟ್ ಬಳಸಿ ಎಂಬೆಡ್ಡಿಂಗ್ಸ್ ಸೃಷ್ಟಿಸುತ್ತದೆ (OpenAI ಮತ್ತು ಅಜೂರ್ OpenAI ಎರಡನ್ನೂ ಬೆಂಬಲಿಸುತ್ತದೆ). -**ChatModel** - ಭಾಷಾ ಮಾದರಿಗಳಿಗೆ ಕೇಂದ್ರ ಇಂಟರ್ಫೇಸ್. +**ChatModel** - ಭಾಷಾ ಮಾದರಿಗಳ ಮುಖ್ಯ ಇಂಟರ್ಫೇಸ್. -**ChatMemory** - ಸಂಭಾಷಣಾ ಇತಿಹಾಸವನ್ನು ಕಾಯ್ದುಕೊಳ್ಳುತ್ತದೆ. +**ChatMemory** - ಸಂವಾದ ಇತಿಹಾಸವನ್ನು ಕಾಯ್ದಿರಿಸುತ್ತದೆ. -**ContentRetriever** - RAG ಗಾಗಿ ಸಂಬಂಧಿತ ಡಾಕ್ಯುಮೆಂಟ್ ಚಂಕ್‌ಗಳನ್ನು ಕಂಡುಹಿಡಿಯುತ್ತದೆ. +**ContentRetriever** - RAG ಗಾಗಿ ಸಂಬಂಧಿಸಿದ ದಸ್ತಾವೇಜು ಚಂಕ್‌ಗಳನ್ನು ಹುಡುಕುತ್ತದೆ. -**DocumentSplitter** - ಡಾಕ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಚಂಕ್‌ಗಳಲ್ಲಿ ವಿಭಜಿಸುತ್ತದೆ. +**DocumentSplitter** - ದಸ್ತಾವೇಜುಗಳನ್ನು ಚಂಕ್‌ಗಳಾಗಿ ವಿಭಜಿಸುತ್ತದೆ. **EmbeddingModel** - ಪಠ್ಯವನ್ನು ಸಂಖ್ಯಾತ್ಮಕ ವೆಕ್ಟರ್‌ಗಳಾಗಿ ಪರಿವರ್ತಿಸುತ್ತದೆ. -**EmbeddingStore** - ಎಂಬೆಡ್ಡಿಂಗ್ಗಳನ್ನು ಸಂಗ್ರಹಿಸಿ ಮತ್ತು ತಲುಪುತ್ತದೆ. +**EmbeddingStore** - ಎಂಬೆಡ್ಡಿಂಗ್ಸ್ ನ್ನು ಸಂಗ್ರಹಿಸುತ್ತದೆ ಮತ್ತು ಮರುಪಡೆಯುತ್ತದೆ. -**MessageWindowChatMemory** - ಇತ್ತೀಚಿನ ಸಂದೇಶಗಳ ಸ್ಲೈಡಿಂಗ್ ವಿಂಡೋವನ್ನು ಕಾಯ್ದುಕೊಳ್ಳುತ್ತದೆ. +**MessageWindowChatMemory** - ಇತ್ತೀಚಿನ ಸಂದೇಶಗಳ ಸ್ಲೈಡಿಂಗ್ ವಿಂಡೋವನ್ನು ನಿರ್ವಹಿಸುತ್ತದೆ. -**PromptTemplate** - `{{variable}}` ಪ್ಲೇಸ್‌ಹೋಲ್ಡರ್‌ಗಳೊಂದಿಗೆ ಪುನಃಬಳಕೆ ಸಾಧ್ಯವಾದ ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ರಚಿಸುತ್ತದೆ. +**PromptTemplate** - `{{variable}}` ಪ್ಲೇಸ್‌ಹೋಲ್ಡರ್‌ಗಳೊಂದಿಗೆ ಪೂನರುಪಯೋಗಿ ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ರಚಿಸುತ್ತದೆ. -**TextSegment** - ಮೆಟಾಡೇಟಾವಿರುವ ಪಠ್ಯದ ತುಂಡು. RAGನಲ್ಲಿ ಬಳಕೆ. +**TextSegment** - ಮೆಟಾಡೇಟಾ ಹೊಂದಿದ ಪಠ್ಯ ತುಂಡು. RAG ನಲ್ಲಿ ಬಳಕೆ. -**ToolExecutionRequest** - ಟೂಲಿನ ಕಾರ್ಯಾಚರಣೆಯ ವಿನಂತಿ ಪ್ರತಿನಿಧಿಸುತ್ತದೆ. +**ToolExecutionRequest** - ಉಪಕರಣ ಕಾರ್ಯನಿರ್ವಹಣೆ ವಿನಂತಿಯನ್ನು ಪ್ರತಿನಿಧಿಸುತ್ತದೆ. -**UserMessage / AiMessage / SystemMessage** - ಸಂಭಾಷಣಾ ಸಂದೇಶ ಮಾದರಿಗಳು. +**UserMessage / AiMessage / SystemMessage** - ಸಂವಾದ ಸಂದೇಶ ಪ್ರಕಾರಗಳು. -## AI/ML ಸಂಯೋಜನೆಗಳು +## AI/ML ತತ್ವಗಳು -**ಫ್ಯೂ-ಶಾಟ್ ಲರ್ನಿಂಗ್** - ಪ್ರಾಂಪ್ಟ್‌ನಲ್ಲಿ ಉದಾಹರಣೆಗಳನ್ನು ನೀಡುವುದು. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) +**ಫ್ಯೂ-ಶಾಟ್ ಲರ್ನಿಂಗ್** - ಪ್ರಾಂಪ್ಟ್‌ಗಳಲ್ಲಿ ಉದಾಹರಣೆಗಳನ್ನು ಕೊಡುವುದು. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) -**ಲಾರ್ಜ್ ಲ್ಯಾಂಗ್ವೇಜ್ ಮಾದರಿ (LLM)** - ವಿಶಾಲವಾದ ಪಠ್ಯ ಡೇಟಾದ ಮೇಲೆ ತರಬೇತಿ ಪಡೆದ AI ಮಾದರಿಗಳು. +**ಲಾರ್ಜ್ ಲ್ಯಾಂಗ್ವೇಜ್ ಮಾದರಿ (LLM)** - ವಿಸ್ತೃತ ಪಠ್ಯ ಡೇಟಾ ಮೇಲೆ ತರಬೇತಿ ಪಡೆದ AI ಮಾದರಿಗಳು. -**ತರ್ಕ ಪ್ರಯತ್ನ** - ಅನ್ವಯವನ್ನು ಆಳವಾಗಿ ನಿಯಂತ್ರಿಸುವ GPT-5.2 ಪ್ಯಾರಾಮೀಟರ್. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) +**ಯೋಚನಾ ಪ್ರಯತ್ನ** - GPT-5.2 ನಿಯಂತ್ರಿಸುವ ಯೋಚಿಸುವ ಆಳ. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) -**ಟೆಂಪರೆಚರ್** - ಔಟ್‌ಪುಟ್ ಯಾದೃಚ್ಛಿಕತೆಯನ್ನು ನಿಯಂತ್ರಿಸುತ್ತದೆ. ಕಡಿಮೆ=ನಿರ್ಧಿಷ್ಟ, ಹೆಚ್ಚು=ರಚನಾತ್ಮಕ. +**ತೆಂಪರೆಚರ್** - ಔಟ್‌ಪುಟ್ ಅನಿಶ್ಚಿತತೆಯನ್ನು ನಿಯಂತ್ರಿಸುತ್ತದೆ. ಕಡಿಮೆ=ನಿರ್ದಿಷ್ಟ, ಹೆಚ್ಚಿನ=ಸೃಜನಶೀಲ. -**ವೆಕ್ಟರ್ ಡೇಟಾಬೇಸ್** - ಎಂಬೆಡ್ಡಿಂಗ್ಸ್‌ಗಾಗಿ ಪರಿಣತ ಡೇಟಾಬೇಸ್. [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) +**ವೆಕ್ಟರ್ ಡೇಟಾಬೇಸ್** - ಎಂಬೆಡ್ಡಿಂಗ್ಸ್‌ಗೆ ವಿಶೇಷ ಡೇಟಾಬೇಸ್. [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) -**ಶೂನ್ಯ-ಶಾಟ್ ಲರ್ನಿಂಗ್** - ಉದಾಹರಣೆಗಳಿಲ್ಲದೆ ಕಾರ್ಯ ಮಾಡುವಿಕೆ. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) +**ಜೀરો-ಶಾಟ್ ಲರ್ನಿಂಗ್** - ಉದಾಹರಣೆ ಇಲ್ಲದೆ ಕಾರ್ಯಗಳನ್ನು ನಿರ್ವಹಿಸುವುದು. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) -## ಗಾರ್ಡರೈಲ್ಸ್ - [ಮಾಡ್ಯೂಲ್ 00](../00-quick-start/README.md) +## ರಕ್ಷಣಾ ಮಾರ್ಗಗಳು -**ಡಿಫೆನ್ಸ್ ಇನ್ ಡೆಪ್ತ್** - ಅಪ್ಲಿಕೇಶನ್-ಮಟ್ಟದ ಗಾರ್ಡರೈಲ್ಸ್ ಮತ್ತು ಪೂರೈಕೆದಾರರ ಸುರಕ್ಷತಾ ಫಿಲ್ಟರ್‌ಗಳನ್ನು ಸಂಯೋಜಿಸುವ ಬಹು-ಮಟ್ಟದ ಭದ್ರತಾ ದೃಷ್ಟಿಕೋನ. +**ಡಿಫೆನ್ಸ್ ಇನ್ ಡೆಪ್ತ್** - ಅಪ್ಲಿಕೇಶನ್-ಲೆವೆಲ್ ರಕ್ಷಣಾ ಮಾರ್ಗಗಳನ್ನು ಮತ್ತು ಪ್ರೊವೈಡರ್ ಸೆಫ್ಟಿ ಫಿಲ್ಟರ್‌ಗಳನ್ನು ಸಂಯೋಜಿಸುವ ಬಹುಮಟ್ಟದ ಭದ್ರತಾ ವಿಧಾನ. -**ಹಾರ್ಡ್ ಬ್ಲಾಕ್** - ಗಂಭೀರ ವಿಷಯ ಉಲ್ಲಂಘನೆಗಳಿಗಾಗಿ ಪೂರೈಕೆದಾರ HTTP 400 ದೋಷವನ್ನು ಹೊಡುತ್ತದೆ. +**ಹಾರ್ಡ್ ಬ್ಲಾಕ್** - ಗಂಭೀರ ವಿಷಯ ಉಲ್ಲಂಘನೆಗಳಿಗೆ ಪ್ರೊವೈಡರ್ HTTP 400 ದೋಷ ತೋರಿಸುತ್ತದೆ. -**ಇನ್‌ಪುಟ್ ಗಾರ್ಡರೈಲ್** - ಲ್ಯಾಂಗ್ಚೈನ್4j ಇಂಟರ್ಫೇಸ್, LLM ಮುಂಚೆ ಬಳಕೆದಾರ ಇನ್‌ಪುಟ್ ಅನ್ನು ತಪಾಸಣೆ ಮಾಡುತ್ತದೆ. ಹಾನಿಕರ ಪ್ರಾಂಪ್ಟ್‌ಗಳನ್ನು ಆರಂಭದಲ್ಲಿ ತಡೆಯುವುದರಿಂದ ವೆಚ್ಚ ಮತ್ತು ವಿಳಂಬ ಉಳಿಸುತ್ತದೆ. +**InputGuardrail** - LangChain4j ಇಂಟರ್ಫೇಸ್ LLM ಗೆ ಹೋಗುವ ಮೊದಲು ಬಳಕೆದಾರ ಇನ್‌ಪುಟ್ ಮಾನ್ಯತೆಗೊಳಿಸು ತುದಿಗೆ ಸೇರಿಸುವ ಮೂಲಕ ವೆಚ್ಚ ಮತ್ತು ವಿಳಂಬವನ್ನು ಉಳಿಸುತ್ತದೆ. -**ಇನ್‌ಪುಟ್ ಗಾರ್ಡರೈಲ್‌ರಿಸಲ್ಟ್** - ಗಾರ್ಡರೈಲ್ ಪರಿಶೋಧನೆಗೆ ಮರುಮಾಡುವ ಪ್ರಕಾರ: `success()` ಅಥವಾ `fatal("reason")`. +**InputGuardrailResult** - ಗಾರ್ಡ್ರೈಲ್ ಮಾನ್ಯತೆಯ ಪ್ರತಿಕ್ರಿಯಾ ಪ್ರಕಾರ: `success()` ಅಥವಾ `fatal("ಕಾರಣ")`. -**ಔಟ್‌ಪುಟ್ ಗಾರ್ಡರೈಲ್** - ಬಳಕೆದಾರರಿಗೆ ಪೋಸ್ಟ್ ಆಗುವ AI ಪ್ರತಿಕ್ರಿಯೆಗಳನ್ನು ಪರಿಶೀಲಿಸುವ ಇಂಟರ್ಫೇಸ್. +**OutputGuardrail** - ಬಳಕೆದಾರರಿಗೆ ಹಿಂದಿರುಗಿಸುವ ಮೊದಲು AI ಪ್ರತಿಕ್ರಿಯೆಗಳನ್ನು ಮಾನ್ಯತೆಗೊಳಿಸುವ ಇಂಟರ್ಫೇಸ್. -**ಪೂರೈಕೆದಾರ ಸುರಕ್ಷತಾ ಫಿಲ್ಟರ್‌ಗಳು** - AI ಪೂರೈಕೆದಾರರಿಂದ (ಉದಾ. GitHub ಮಾದರಿಗಳು) API ಮಟ್ಟದಲ್ಲಿ ಉಲ್ಲಂಘನೆಗಳನ್ನು ಹಿಡಿಯುವ ಒಳನಾಡು ವಿಷಯ ಫಿಲ್ಟರ್‌ಗಳು. +**Provider Safety Filters** - API ಮಟ್ಟದಲ್ಲಿ ಉಲ್ಲಂಘನೆಗಳನ್ನು ಹಿಡಿಯುವ, AI ಪ್ರೊವೈಡರ್‌ಗಳಲ್ಲಿ (ಉದಾ: ಅಜೂರ್ OpenAI) ನಿರ್ಮಿತ ವಿಷಯ ಫಿಲ್ಟರ್‌ಗಳು. -**ಸಾಫ್ಟ್ ರಿಫ್ಯೂಸಲ್** - ಮಾದರಿ ದೋಷವಿಲ್ಲದೆ ವಿನಮ್ರವಾಗಿ ಉತ್ತರ ನೀಡಲು ನಿರಾಕರಿಸುವುದು. +**Soft Refusal** - ಮಾದರಿ ದೋಷ ತೋರಿಸುವದೆ ಇಲ್ಲದೆ ಶಿಷ್ಟವಾಗಿ ಉತ್ತರ ನೀಡಲು ನಿರಾಕರಿಸುವುದು. ## ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್ - [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) -**ಚೈನ್-ಆಫ್-ಥಾಟ್** - ಉತ್ತಮ ನಿಖರತೆಗೆ ಹಂತ ಹಂತreasoning. +**ಚೈನ್-ಆಫ್-ಥಾಟ್** - ಉತ್ತಮ ನಿಖರತೆಗಾಗಿ ಹಂತಬಿಡುವ ಯೋಚನೆ. -**ಶ್ರುತಿದೋಷಿತ ಔಟ್‌ಪುಟ್** - ನಿರ್ದಿಷ್ಟ ರೂಪ ಅಥವಾ ರಚನೆ ಜಾರಿಮಾಡುವುದು. +**ಬಂಧಿತ ಔಟ್‌ಪುಟ್** - ನಿರ್ದಿಷ್ಟ ರೂಪ ಅಥವಾ ರಚನೆಯನ್ನು ಅನುವರ್ಥಿಸುವುದು. -**ಹೈ ಈಗರ್ನೆಸ್** - ಆಳವಾದ ತರ್ಕಕ್ಕಾಗಿ GPT-5.2 ಮಾದರಿ. +**ಹೆಚ್ಚಿನ ಉತ್ಸಾಹ** - GPT-5.2 ನ ಸಂಪೂರ್ಣ ಯೋಚನೆಗಾಗಿ ವಿನ್ಯಾಸ ಮಾಡಲಾದ ಮಾದರಿ. -**ಲೋ ಈಗರ್ನೆಸ್** - ವೇಗದ ಉತ್ತರಗಳಿಗಾಗಿ GPT-5.2 ಮಾದರಿ. +**ಕಡಿಮೆ ಉತ್ಸಾಹ** - ಶೀಘ್ರ ಉತ್ತರಗಳಿಗೆ GPT-5.2 ಮಾದರಿ ಮಾದರಿ. -**ಮಲ್ಟಿ-ಟರ್ನ್ ಸಂಭಾಷಣೆ** - ವಾಣಿಜ್ಯ ವಿನಿಮಯದ ಸಂದರ್ಭವನ್ನು ಕಾಯ್ದುಕೊಳ್ಳುವುದು. +**ಬಹು-ತಿರುಗು ಸಂವಾದ** - ವಿನಿಮಯಗಳಲ್ಲಿ ಸಾಂದರ್ಭಿಕತೆಯನ್ನು ಕಾಪಾಡುವುದು. -**ಪಾತ್ರಾಧಾರಿತ ಪ್ರಾಂಪ್ಟಿಂಗ್** - ಸಿಸ್ಟಮ್ ಸಂದೇಶಗಳ ಮೂಲಕ ಮಾದರಿಯ ವ್ಯಕ್ತಿತ್ವವನ್ನು ಸೆಟ್ ಮಾಡುವುದು. +**ಪಾತ್ರಾಧಾರಿತ ಪ್ರಾಂಪ್ಟಿಂಗ್** - ಸಿಸ್ಟಂ ಸಂದೇಶಗಳ ಮೂಲಕ ಮಾದರಿ ವ್ಯಕ್ತಿತ್ವವನ್ನು ಹೊಂದಿಸುವುದು. -**ಸ್ವ-ಪರಿಶೀಲನೆ** - ಮಾದರಿ ತನ್ನ ಔಟ್‌ಪುಟ್ ಅನ್ನು ಮೌಲ್ಯಮಾಪನ ಮಾಡಿ ಸುಧಾರಿಸುತ್ತದೆ. +**ಸ್ವ-ಪರಿಶೀಲನೆ** - ಮಾದರಿ ತನ್ನ ಔಟ್‌ಪುಟ್ ಬೆಲೆಮಾಚಿ ಸುಧಾರಿಸುತ್ತದೆ. -**ರಚನಾತ್ಮಕ ವಿಶ್ಲೇಷಣೆ** - ಸ್ಥಿರ ಮೌಲ್ಯಮಾಪನ ಚೌಕಟ್ಟಿನೊಂದಿಗೆ. +**ಸಂರಚಿತ ವಿಶ್ಲೇಷಣೆ** - ಸ್ಥಿರ ಮೌಲ್ಯಮಾಪನ ರೂಪರೇಖೆ. -**ಕಾರ್ಯನಿರ್ವಾಹಣಾ ಮಾದರಿ** - ಯೋಜನೆ → ಅನುಷ್ಠಾನ → ಸಾರಾಂಶ. +**ಕಾರ್ಯ ನಿರ್ವಹಣಾ ಮಾದರಿ** - ಯೋಜನೆ → ನಿರ್ವಹಣೆ → ಸಾರಾಂಶ. -## RAG (ಪುನಃಯೋಜಿತ ಉತ್ಪಾದನೆ) - [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) +## RAG (ಮರುಪಡೆಯುವ ಅನ್ವಯ ಸಂಕಲನ) - [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) -**ಡಾಕ್ಯುಮೆಂಟ್ ಪ್ರಕ್ರಿಯೆ ಪೈಪ್‌ಲೈನ್** - ಲೋಡ್ → ಚಂಕ್ → ಎಂಬೆಡ್ → ಸಂಗ್ರಹಿಸಿ. +**ದಸ್ತಾವೇಜು ಪ್ರಕ್ರಿಯೆ ಪೈಪ್‌ಲೈನ್** - ಲೋಡ್ → ಚಂಕ್ → ಎಂಬೆಡ್ಡ್ → ಸ್ಟೋರ್. -**ಇನ್-ಮೆಮರಿ ಎಂಬೆಡ್ಡಿಂಗ್ ಸ್ಟೋರ್** - ಪರೀಕ್ಷೆಯಿಗಾಗಿ ಅಸ್ಥಿರ ಸಂಗ್ರಹಣೆ. +**ಇನ್-ಮೆಮೋರಿ ಎಂಬೆಡ್ಡಿಂಗ್ ಸ್ಟೋರ್** - ಪರೀಕ್ಷೆಗಾಗಿ ಅಸ್ಥಾಯಿ ಸಂಗ್ರಹಣೆ. -**RAG** - ಪ್ರತಿಕ್ರಿಯೆಗಳಿಗೆ ಜಾಗೃತತೆಯನ್ನು ಒದಗಿಸಲು ರಿಟ್ರೈವಲ್ ಮತ್ತು ಉತ್ಪಾದನೆಯನ್ನು ಸಂಯೋಜಿಸುತ್ತದೆ. +**RAG** - ಮರುಪಡೆಯುವಿಕೆಯನ್ನು ಉತ್ಪತ್ತಿಯೊಂದಿಗೆ ಸಂಯೋಜಿಸಿ ಪ್ರತಿಕ್ರಿಯೆಗಳನ್ನು ಸ್ಥಾಪಿಸುತ್ತದೆ. -**ಸಮಾನತೆ ಅಂಕ** - ಅರ್ಥಪೂರ್ಣ ಸಮಾನತೆಯ ಪ್ರಮಾಣ (0-1). +**ಸಮಾನತೆ ಅಂಕ** - ಅರ್ಥ ಸಮ್ಮಿಲನದ ಮಾಪಕ (0-1). -**ಮೂಲ ಉಲ್ಲೇಖ** - ಪಡೆದ ವಿಷಯದ ಮೆಟಾಡೇಟಾ. +**ಮೂಲ ಉಲ್ಲೇಖ** - ಮರುಪಡೆಯಲಾದ ವಿಷಯದ ಮೆಟಾಡೇಟಾ. -## ಏಜೆಂಟುಗಳು ಮತ್ತು ಟೂಲ್ಸ್ - [ಮಾಡ್ಯೂಲ್ 04](../04-tools/README.md) +## ಏಜೆಂಟ್ಸ್ ಮತ್ತು ಉಪಕರಣಗಳು - [ಮಾಡ್ಯೂಲ್ 04](../04-tools/README.md) -**@ಟೂಲ್ ಅನೋಟೇಷನ್** - ಜಾವಾ ವಿಧಾನಗಳನ್ನು AI-ಕೆಲೆಯ ಸಾಧನಗಳಾಗಿ ಗುರುತಿಸುವುದು. +**@Tool ಅಳವಡಿಕೆ** - AI ಕರೆ ಮಾಡಬಹುದಾದ ಉಪಕರಣಗಳಾಗಿ ಜಾವಾ ವಿಧಾನಗಳನ್ನು ಗುರುತುಮಾಡುತ್ತದೆ. -**ರಿಏಕ್ಟ್ ಮಾದರಿ** - ತರ್ಕ್ಮಾಡಿ → ಕಾರ್ಯ ನೀಡಿ → ತಿಳಿದುಕೊಳ್ಳಿ → ಪುನರಾವರ್ತನೆ. +**ReAct ಮಾದರಿ** - ಯೋಚನೆ → ಕಾರ್ಯ → ಹಂಚಿಕೆ → ಪುನರಾವೃತ. -**ಸೆಷನ್ ನಿರ್ವಹಣೆ** - ವಿಭಿನ್ನ ಬಳಕೆದಾರರಿಗೆ ವಿಭಿನ್ನ ಸಂದರ್ಭಗಳನ್ನು ನಿರ್ವಹಣೆ. +**ಅಧಿವೇಶನ ನಿರ್ವಹಣೆ** - ವಿಭಿನ್ನ ಬಳಕೆದಾರರಿಗಾಗಿ ಪ್ರತ್ಯೇಕ ಸಾಂದರ್ಭಿಕತೆಗಳು. -**ಟೂಲ್** - AI ಏಜೆಂಟ್ ಕರೆ ಮಾಡಬಹುದಾದ ಕಾರ್ಯ. +**ಉಪಕರಣ** - AI ಏಜೆಂಟ್ ಕರೆ ಮಾಡಬಹುದಾದ ಕಾರ್ಯ. -**ಟೂಲ್ ವಿವರಣೆ** - ಟೂಲಿನ ಉದ್ದೇಶ ಮತ್ತು ಪ್ಯಾರಾಮೀಟರ್‌ಗಳ ದಾಖಲಾತಿ. +**ಉಪಕರಣ ವಿವರಣೆ** - ಉಪಕರಣ ಉದ್ದೇಶ ಮತ್ತು ಪರಿಮಾಣಗಳ ಡಾಕ್ಯುಮೆಂಟ್. -## ಏಜೆಂಟಿಕ್ ಮODULE - [ಮಾಡ್ಯೂಲ್ 05](../05-mcp/README.md) +## ಏಜೆಂಟಿಕ್ ಮಾಡ್ಯೂಲ್ - [ಮಾಡ್ಯೂಲ್ 05](../05-mcp/README.md) -**@ಏಜೆಂಟ್ ಅನೋಟೇಷನ್** - ಘೋಷಣಾತ್ಮಕ ವರ್ತನೆ ವಿವರಣೆಯೊಂದಿಗೆ ಏಜೆಂಟ್‌ಗಳನ್ನು ಗುರುತಿಸುವ ಇಂಟರ್ಫೇಸ್‌ಗಳು. +**@Agent ಅಳವಡಿಕೆ** - ಘೋಷಣಾತ್ಮಕ ವರ್ತನೆ ವಿಸ್ತಾರಣೆಯೊಂದಿಗೆ AI ಏಜೆಂಟ್‌ಗಳಾಗಿ ಇಂಟರ್ಫೇಸ್ ಗುರುತುಮಾಡುತ್ತದೆ. -**ಏಜೆಂಟ್ ಲಿಸನರ್** - `beforeAgentInvocation()` ಮತ್ತು `afterAgentInvocation()` ಮೂಲಕ ಏಜೆಂಟ್ ಕಾರ್ಯ ನಿರೀಕ್ಷಣೆಗೆ ಹೂಕ್. +**ಏಜೆಂಟ್ ಶ್ರೋತೃ** - `beforeAgentInvocation()` ಮತ್ತು `afterAgentInvocation()` ಮೂಲಕ ಏಜೆಂಟ್ ಕಾರ್ಯಾಚರಣೆ ಮೇಲ್ವಿಚಾರಣೆಗೆ ಹೂಕ್. -**ಏಜೆಂಟಿಕ್ ವ್ಯಾಪ್ತಿ** - `outputKey` ಬಳಸಿ ಏಜೆಂಟ್‌ಗಳು ಫಲಿತಾಂಶಗಳನ್ನು ಸಂಗ್ರಹಿಸುವ ಹಂಚಿಕೆಯ ಆತನಕೃತಿ ಜ್ಞಾಪಕ. +**ಏಜೆಂಟಿಕ್ ವ್ಯಾಪ್ತಿ** - ಏಜೆಂಟ್‌ಗಳು `outputKey` ಬಳಸಿ ಫಲಿತಾಂಶಗಳನ್ನು ಸಂಗ್ರಹಿಸುವ ಹಂಚಿಕೆಯ ಮೆಮೊರಿ, ಹೀಗಾಗಿ ನಂತರದ ಏಜೆಂಟ್‌ಗಳು ಬಳಸಬಹುದು. -**ಏಜೆಂಟಿಕ್ ಸೇವೆಗಳು** - `agentBuilder()` ಮತ್ತು `supervisorBuilder()` ಬಳಸಿ ಏಜೆಂಟ್‌ಗಳ ರಚನೆಗಾಗಿ ಕಾರ್ಖಾನೆ. +**ಏಜೆಂಟಿಕ್ ಸೇವೆಗಳು** - `agentBuilder()` ಮತ್ತು `supervisorBuilder()` ಬಳಸಿ ಏಜೆಂಟ್‌ಗಳನ್ನು ನಿರ್ಮಿಸುವ ಫ್ಯಾಕ್ಟರಿ. -**ಶರತ್ತ್ workflow** - ವಿಭಿನ್ನ ವಿಶೇಷಜ್ಞ ಏಜೆಂಟುಗಳಿಗೆ ನಿಯಮಗಳ ಆಧಾರದ ಮೇಲೆ ಮಾರ್ಗ. +**ಶರತ್ತು ಆಧಾರಿತ ಕಾರ್ಯಪ್ರವಾಹ** - ವಿಭಿನ್ನ ವಿಶೇಷಜ್ಞ ಏಜೆಂಟ್‌ಗಳಿಗೆ ಮಾರ್ಗವನ್ನು ನಿರ್ಧರಿಸುವುದು. -**ಮಾನವ-ನಿಮಿತ್ತ ಲೂಪ್** - ಮನುಷ್ಯ სპეციಫಿಕ್ ನ್ಯಾಯಮೂಲ್ಯ ಅಥವಾ ವಿಷಯ ವಿಮర్శನಿಗಾಗಿ ಕಾರ್ಯಪ್ರವಾಹ ಮಾದರಿ. +**ಮಾನವ-ಇನ್-ದಿ-ಲೂಪ್** - ಮಾನವ ಪರಿಶೀಲನೆಗಳು ಅಥವಾ ವಿಷಯ ವಿಮರ್ಶೆಗಾಗಿ ಕಾರ್ಯಪ್ರವಾಹ ಮಾದರಿ. -**langchain4j-agentic** - ಘೋಷಣಾತ್ಮಕ ಏಜೆಂಟ್ ನಿರ್ಮಾಣಕ್ಕೆ ಮೇವೆನ್ ಅವಲಂಬನೆ (ಪ್ರಯೋಗಾತ್ಮಕ). +**langchain4j-agentic** - ಘೋಷಣಾತ್ಮಕ ಏಜೆಂಟ್ ನಿರ್ಮಾಣದ ಮೇವನ್ ಅವಲಂಬನೆ (ಪ್ರಾಯೋಗಿಕ). -**ಲೂಪ್ ವರ್ಕ್‌ಫ್ಲೋ** - ಗುಣಮಟ್ಟ ಅಂಕ ≥ 0.8 ಮುಂತಾದ ನಿಯಮ ಪೂರೈಸುವ ತನಕ ಏಜೆಂಟ್ ಕಾರ್ಯ ನಿರ್ವಹಣೆ ಪುನರಾವರ್ತಿಸುವುದು. +**ಲೂಪ್ ಕಾರ್ಯಪ್ರವಾಹ** - ಶರತ್ತು ಪೂರೈವರೆಗೆ ಏಜೆಂಟ್ ಕಾರ್ಯಾಚರಣೆಯನ್ನು ಪುನರಾವರ್ತಿಸುವುದು (ಉದಾ: ಗುಣಮಟ್ಟ ಅಂಕ ≥ 0.8). -**outputKey** - ಏಜೆಂಟ್ ಅನೋಟೇಷನ್ ಪ್ಯಾರಾಮೀಟರ್, ಏಜೆಂಟಿಕ್ ವ್ಯಾಪ್ತಿಯಲ್ಲಿ ಫಲಿತಾಂಶ ಹುರಿಯುವ ಸ್ಥಳ. +**outputKey** - ಏಜೆಂಟಿಕ್ ವ್ಯಾಪ್ತಿಯಲ್ಲಿ ಫಲಿತಾಂಶಗಳ ಭಂಡಾರ ಸ್ಥಳವನ್ನು ಸೂಚಿಸುವ ಏಜೆಂಟ್ ಅಳವಡಿಕೆ ಪರಿಮाण. -**ಪ್ಯಾರೆಲ್ಲಲ್ ವರ್ಕ್‌ಫ್ಲೋ** - ಸ್ವತಂತ್ರ ಕಾರ್ಯಗಳಿಗೆ ಹಲವಾರು ಏಜೆಂಟ್‌ಗಳನ್ನು ಒಂದೇ ಅವಧಿಯಲ್ಲಿ ಚಲಾಯಿಸುವುದು. +**ಪ್ಯಾರಲಲ್ ಕಾರ್ಯಪ್ರವಾಹ** - ಸ್ವತಂತ್ರ ಕಾರ್ಯಗಳಿಗೆ ಹಲವಾರು ಏಜೆಂಟ್‌ಗಳನ್ನು samtid ಗತವಾಗಿ ಚಲಿಸುವುದು. -**ಪ್ರತಿಕ್ರಿಯೆ ತಂತ್ರ** - ಮೇಲ್ವಿಚಾರಕ ಅಂತಿಮ ಉತ್ತರವನ್ನು ರೂಪಿಸುವ ವಿಧಾನ: ಅಂತಿಮ, ಸಾರಾಂಶ ಅಥವಾ ಅಂಕಿತ. +**ಪ್ರತಿಕ್ರಿಯೆ ಯುಕ್ತಿ** - ಮೇಲ್ವಿಚಾರಕ ಅಂತಿಮ ಉತ್ತರವನ್ನು ಹೇಗೆ ರೂಪಿಸುವುದು: LAST, SUMMARY, ಅಥವಾ SCORED. -**ಕ್ರಮಬದ್ಧ ವರ್ಕ್‌ಫ್ಲೋ** - ಕಾರ್ಯ ಕ್ರಮ ಸರಿಯಲ್ಲಿದ್ಯವಾಗಿ ನಿರ್ವಹಣೆ, ಹೊರತಂಡ ಮುಂದಿನ ಹಂತಕ್ಕೆ ಸಾಗುತ್ತದೆ. +**ಕ್ರಮಬದ್ಧ ಕಾರ್ಯಪ್ರವಾಹ** - ಕ್ರಮವಾಗಿ ಏಜೆಂಟ್‌ಗಳನ್ನು ಕಾರ್ಯಗತಗೊಳಿಸುವುದು, ಹೊರತುಪಡಿಸಿ ಔಟ್‌ಪುಟ್ ಮುಂದಿನ ಹಂತಕ್ಕೆ ಹೋಮುತ್ತದೆ. -**ಮೇಲ್ವಿಚಾರಕ ಏಜೆಂಟ್ ಮಾದರಿ** - ಮೇಲ್ವಿಚಾರಕ LLM ಡೈನಾಮಿಕ್ ಉಪ ಏಜೆಂಟ್‌ಗಳನ್ನು ಕರೆಮಾಡಲು ತೀರ್ಮಾನಿಸುವ ಪ್ರಗತಿಯಾದ ಏಜೆಂಟಿಕ್ ಮಾದರಿ. +**ಮೇಲ್ವಿಚಾರಕ ಏಜೆಂಟ್ ಮಾದರಿ** -ど a dynamic supervisor LLM decides which sub-agents to invoke്. -## ಮಾಡೆಲ್ ಕಾಂಟೆಕ್ಸ್ಟ್ ಪ್ರೋಟೋಕಾಲ್ (MCP) - [ಮಾಡ್ಯೂಲ್ 05](../05-mcp/README.md) +## ಮಾದರಿ ಸಾಂದರ್ಭಿಕ ಪ್ರೋಟೋಕಾಲ್ (MCP) - [ಮಾಡ್ಯೂಲ್ 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4jನಲ್ಲಿ MCP ಏಕೀಕರಣಕ್ಕಾಗಿ ಮೇವೆನ್ ಅವಲಂಬನೆ. +**langchain4j-mcp** - LangChain4j ನಲ್ಲಿ MCP ಏಕೀಕರಣಕ್ಕಾಗಿ ಮೇವನ್ ಅವಲಂಬನೆ. -**MCP** - ಮಾಡೆಲ್ ಕಾಂಟೆಕ್ಸ್ಟ್ ಪ್ರೋಟೋಕಾಲ್: AI ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಹೊರಗಿನ ಟೂಲ್ಗಳಿಗೆ ಸಂಪರ್ಕಿಸುವ ಮಾನದಂಡ. ಒಮ್ಮೆ ರಚಿಸಿ ಎಲ್ಲೆಡೆ ಬಳಸಿ. +**MCP** - ಮಾದರಿ ಸಾಂದರ್ಭಿಕ ಪ್ರೋಟೋಕಾಲ್: AI ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಬಾಹ್ಯ ಉಪಕರಣಗಳಿಗೆ ಸಂಪರ್ಕಿಸುವ ಮಾನಕ. ಒಮ್ಮೆ ನಿರ್ಮಿಸಿ ಎಲ್ಲೆಡೆ ಬಳಸಿ. -**MCP ಕ್ಲೈಂಟ್** - MCP ಸರ್ವರ್‌ಗಳಿಗೆ ಸಂಪರ್ಕ ಹೊಂದಿ ಟೂಲ್ಗಳನ್ನು ಪತ್ತೆಮಾಡಿ ಬಳಕೆಗೆ ಸುಧಾರಿಸುವ ಅಪ್ಲಿಕೇಶನ್. +**MCP ಕ್ಲೈಂಟ್** - MCP ಸರ್ವರ್‌ಗಳಿಗೆ ಸಂಪರ್ಕಿಸಿ ಉಪಕರಣಗಳನ್ನು ಕಂಡುಹಿಡಿಯುವ ಮತ್ತು ಬಳಸುವ ಅಪ್ಲಿಕೇಶನ್. -**MCP ಸರ್ವರ್** - ಸ್ಪಷ್ಟ ವಿವರಣೆ ಮತ್ತು ಪ್ಯಾರಾಮೀಟರ್ schemas ಮೂಲಕ ಟೂಲ್ಗಳನ್ನು MCP ಮೂಲಕ ಅನಾವರಣ ಮಾಡುವ ಸೇವೆ. +**MCP ಸರ್ವರ್** - ವೀಕ್ಷಣೀಯ ವಿವರಣೆಗಳು ಮತ್ತು ಪರಿಮಾಣ ಸ್ಕೀಮಾಡೊಂದಿಗೆ MCP ಮೂಲಕ ಉಪಕರಣಗಳನ್ನು ಹೊರತರುವ ಸೇವೆ. -**McpToolProvider** - LangChain4j ಘಟಕ, MCP ಟೂಲ್ಗಳನ್ನು AI ಸೇವೆಗಳು ಮತ್ತು ಏಜೆಂಟ್‌ಗಳಲ್ಲಿ ಬಳಸಿ ಮುಡುಪುಗೊಳಿಸುತ್ತದೆ. +**McpToolProvider** - LangChain4j ಘಟಕ, AI ಸೇವೆಗಳು ಮತ್ತು ಏಜೆಂಟ್‌ಗಳಲ್ಲಿ ಬಳಸಲು MCP ಉಪಕರಣಗಳನ್ನು ಮುಸ್ಲಿಮಾಡುತ್ತದೆ. -**McpTransport** - MCP ಸಂಪರ್ಕಕ್ಕಾಗಿ ಇಂಟರ್ಫೇಸ್. ಅನುಷ್ಠಾನಗಳು Stdio ಮತ್ತು HTTP ಒಳಗೊಂಡಿವೆ. +**McpTransport** - MCP ಸಂವಹನದ ಇಂಟರ್ಫೇಸ್. ಅನುಷ್ಠಾನಗಳಲ್ಲಿ ಸ್ಟಿಡಿಯೋ ಮತ್ತು HTTP ಒಳಗೊಂಡಿದೆ. -**Stdio ಟ್ರಾನ್ಸ್‌ಪೋರ್ಟ್** - ಸ್ಥಳೀಯ ಪ್ರಕ್ರಿಯೆಯ ಸಂಪರ್ಕ, stdin/stdout ಮೂಲಕ. ಫೈಲ್‌ಸಿಸ್ಟಮ್ ಪ್ರವೇಶ ಅಥವಾ ಕಮಾಂಡ್‌ ಲೈನ್ ಟೂಲ್ಗಳಿಗಾಗಿ ಲಾಭಕಾರಿ. +**ಸ್ಟಿಡಿಯೋ ಟ್ರಾನ್ಸ್‌ಪೋರ್ಟ್** - stdin/stdout ಮೂಲಕ ಸ್ಥಳೀಯ ಪ್ರಕ್ರಿಯೆ ಸಂವಹನ. ಫೈಲ್‌ಸಿಸ್ಟಮ್ ಪ್ರವೇಶ ಅಥವಾ ಕಮಾಂಡ್ ಲೈನ್ ಉಪಕರಣಕ್ಕೆ ಅನುಕೂಲಕರ. -**StdioMcpTransport** - LangChain4j ಅನುಷ್ಠಾನ, subprocess ಆಗಿ MCP ಸರ್ವರ್ ಅನ್ನು ಪ್ರಾರಂಭಿಸುವುದು. +**ಸ್ಟಿಡಿಯೋMcpTransport** - LangChain4j ಅನುಷ್ಠಾನ, MCP ಸರ್ವರ್ ಅನ್ನು ಉಪಪ್ರಕ್ರಿಯೆಯಾಗಿ_spawn_ ಮಾಡುತ್ತದೆ. -**ಟೂಲ್ ಡಿಸ್ಕವರಿ** - ಕ್ಲೈಂಟ್ ಸರ್ವರ್‌ಗೆ ಟೂಲ್ಗಳಿಗಾಗಿ ವಿವರಣೆ ಮತ್ತು schemas ಜೊತೆ ಪ್ರಶ್ನೆಗಳು. +**ಉಪಕರಣ ಪರಿಶೋಧನೆ** - ಕ್ಲೈಂಟ್ ಸರ್ವರ್‌ನಿಂದ ಲಭ್ಯವಿರುವ ಉಪಕರಣಗಳನ್ನು ವಿವರಣೆಗಳೊಂದಿಗೆ ಸೇರಿ ಪ್ರಶ್ನೆ ಮಾಡುವುದು. -## ಅಜುರ್ ಸೇವೆಗಳು - [ಮಾಡ್ಯೂಲ್ 01](../01-introduction/README.md) +## ಅಜೂರ್ ಸೇವೆಗಳು - [ಮಾಡ್ಯೂಲ್ 01](../01-introduction/README.md) -**ಅಜುರ್ AI ಶೋಧ** - ವೆಕ್ಟರ್ ಸಾಮರ್ಥ್ಯಗಳೊಂದಿಗೆ ಕ್ಲೌಡ್ ಶೋಧ. [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) +**Azure AI Search** - ವೆಕ್ಟರ್ ಸಾಮರ್ಥ್ಯಗಳೊಂದಿಗೆ ಕ್ಲೌಡ್ ಹುಡುಕಾಟ. [ಮಾಡ್ಯೂಲ್ 03](../03-rag/README.md) -**ಅಜುರ್ ಡೆವಲಪರ್ CLI (azd)** - ಅಜುರ್ ಸಂಪನ್ಮೂಲಗಳನ್ನು ನಿಯೋಜಿಸುತ್ತದೆ. +**Azure Developer CLI (azd)** - ಅಜೂರ್ ಸಂಪನ್ಮೂಲಗಳನ್ನು ನಿಯೋಜಿಸುತ್ತದೆ. -**ಅಜುರ್ OpenAI** - ಮೈಕ್ರೋಸಾಫ್ಟ್ ಉದ್ಯಮ AI ಸೇವೆ. +**Azure OpenAI** - ಮೈಕ್ರೋಸಾಫ್ಟ್‌ನ ಉದ್ಯಮ AI ಸೇವೆ. -**ಬೈಸೆಪ್** - ಅಜುರ್ ಇನ್ಫ್ರಾಸ್ಟ್ರಕ್ಚರ್-ಎಸ್-ಕೋಡ್ ಭಾಷೆ. [ಇನ್ಫ್ರಾ ಗೈಡ್](../01-introduction/infra/README.md) +**Bicep** - ಅಜೂರ್ ಮೂಲಸೌಕರ್ಯ-ಎನ್-ಕೋಡ್ ಭಾಷೆ. [ಮೂಲಸೌಕರ್ಯ ಮಾರ್ಗದರ್ಶಿ](../01-introduction/infra/README.md) -**ನಿಯೋಜನೆ ಹೆಸರು** - ಅಜುರ್‌ನಲ್ಲಿ ಮಾದರಿ ನಿಯೋಜನೆಯ ಹೆಸರು. +**ನಿಯೋಜನೆ ಹೆಸರು** - ಅಜೂರ್‌ನಲ್ಲಿನ ಮಾದರಿ ನಿಯೋಜನೆಗೆ ಹೆಸರು. -**GPT-5.2** - ತರ್ಕ ನಿಯಂತ್ರಣದೊಂದಿಗೆ ಇತ್ತೀಚಿನ OpenAI ಮಾದರಿ. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) +**GPT-5.2** - ಯೋಚನೆ ನಿಯಂತ್ರಣದೊಂದಿಗೆ ಇತ್ತೀಚಿನ OpenAI ಮಾದರಿ. [ಮಾಡ್ಯೂಲ್ 02](../02-prompt-engineering/README.md) -## ಪರೀಕ್ಷಾ ಮತ್ತು ಅಭಿವೃದ್ಧಿ - [ಪರೀಕ್ಷಾ ಮಾರ್ಗದರ್ಶಿ](TESTING.md) +## ಪರೀಕ್ಷಣೆ ಮತ್ತು ಅಭಿವೃದ್ಧಿ - [ಪರೀಕ್ಷಣೆ ಮಾರ್ಗದರ್ಶಿ](TESTING.md) -**ಡೆವ್ ಕಂಟೈನರ್** - ಕಂಟೈನರ್ ಆಧಾರಿತ ಅಭಿವೃದ್ಧಿ ಪರಿಸರ. [ರಚನೆ](../../../.devcontainer/devcontainer.json) +**ಡಿವ್ ಕಂಟೈನರ್** - ಕಂಟೈನರ್ ಆಧಾರಿತ ಅಭಿವೃದ್ಧಿ ಪರಿಸರ. [ನೀಮನ](../../../.devcontainer/devcontainer.json) -**GitHub ಮಾದರಿಗಳು** - ಉಚಿತ AI ಮಾದರಿ ಆಟೋಣ. [ಮಾಡ್ಯೂಲ್ 00](../00-quick-start/README.md) +**ಇನ್-ಮೆಮೊರಿ ಪರೀಕ್ಷೆ** - ಇನ್-ಮೆಮೊರಿ ಸಂಗ್ರಹಣೆಯೊಂದಿಗೆ ಪರೀಕ್ಷೆ. -**ಇನ್-ಮೆಮರಿ ಪರೀಕ್ಷೆ** - ಇನ್-ಮೆಮರಿ ಸಂಗ್ರಹಣೆಯಿಂದ ಪರೀಕ್ಷೆ. +**ಆಣ್ವಯಾತ್ಮಕ ಪರೀಕ್ಷೆ** - ನಿಜವಾದ ಮೂಲಸೌಕರ್ಯದೊಂದಿಗೆ ಪರೀಕ್ಷೆ. -**ಒಕ್ಕೂಟ ಪರೀಕ್ಷೆ** - ನಿಜವಾದ ಮೂಲಸೌಕರ್ಯದಿಂದ ಪರೀಕ್ಷೆ. +**ಮೇವನ್** - ಜಾವಾ ನಿರ್ಮಾಣ ಸ್ವಯಂಚಾಲಕ ಸಾಧನ. -**ಮೇವೆನ್** - ಜಾವಾ ನಿರ್ಮಾಣ ಸ್ವಚಾಲಿತ ಸಾಧನ. +**Mockito** - ಜಾವಾ ಮಾಕ್‌ಿಂಗ ಫ್ರೇಮ್‌ವರ್ಕ್. -**Mockito** - ಜಾವಾ ಮೋಕಿಂಗ್ ಫ್ರೇಮ್ವರ್ಕ್. - -**Spring Boot** - ಜಾವಾ ಅಪ್ಲಿಕೇಶನ್ ಫ್ರೇಮ್ವರ್ಕ್. [ಮಾಡ್ಯೂಲ್ 01](../01-introduction/README.md) +**Spring Boot** - ಜಾವಾ ಅಪ್ಲಿಕೇಶನ್ ಫ್ರೇಮ್‌ವರ್ಕ್. [ಮಾಡ್ಯೂಲ್ 01](../01-introduction/README.md) --- -**ಎಚ್ಚರಿಕೆ**: -ಈ ದಾಖಲೆ ಅನ್ನು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ಶುದ್ಧತೆಗಾಗಿ ಪ್ರಯತ್ನಿಸುವುದಾದರೂ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ತಪ್ಪುಗಳು ಅಥವಾ ಅಸ್ಪಷ್ಟತೆಗಳಿರಬಹುದು ಎಂಬುದನ್ನು ದಯವಿಟ್ಟು ಗಮನಿಸಿ. ಮೂಲ ಭಾಷೆಯಲ್ಲಿರುವ ಅತ್ಯಂತ ಪ್ರಾಮಾಣಿಕ ದಾಖಲೆವನ್ನು ಪ್ರಾಧಿಕಾರಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಗಂಭೀರ ಮಾಹಿತಿಗಾಗಿ ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದ ಬಳಸದರಿಂದ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪು ಗ್ರಹಿಕೆಗಳು ಅಥವಾ ಅರ್ಥಮಾಡಿಕೊಳಕುಗಳಿಗೆ ನಾವು ಜವಾಬ್ದಾರಿಯಾಗುವುದಿಲ್ಲ. +**ಅಸ್ವೀಕಾರ**: +ಈ ದಸ್ತಾವೇಜು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಯನ್ನು ಸಾಧಿಸಲು ಪ್ರಯತ್ನಿಸುತ್ತಿದ್ದರೂ, ದಯವಿಟ್ಟು ಗಮನಿಸಿ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ಅಸಡ್ಡೆಗಳು ಇರಬಹುದು. ಮೂಲ ಭಾಷೆಯಲ್ಲಿರುವ ಮೂಲ ದಸ್ತಾವೇಜು ಪ್ರಾಮಾಣಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದವನ್ನು ಬಳಸುವ ಮೂಲಕ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪು ಅರ್ಥಗಳ ಅಥವಾ ತಪ್ಪು ವ್ಯಾಖ್ಯಾನಗಳ ಬಗ್ಗೆ ನಾವು ಹೊಣೆಗಾರರಲ್ಲ. \ No newline at end of file diff --git a/translations/kn/docs/TESTING.md b/translations/kn/docs/TESTING.md index 0e4ae92d2..a9dd6c11e 100644 --- a/translations/kn/docs/TESTING.md +++ b/translations/kn/docs/TESTING.md @@ -1,20 +1,20 @@ # LangChain4j ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಪರೀಕ್ಷಿಸುವುದು -## ವಿಷಯಗಳ ಪಟ್ಟಿ +## ವಿಷಯಗಳು -- [ತ್ವರಿತ ಪ್ರಾರಂಭ](../../../docs) -- [ಪರೀಕ್ಷೆಗಳು ಏನು ಒಳಗೊಂಡಿವೆ](../../../docs) -- [ಪರೀಕ್ಷೆಗಳನ್ನು ನಡೆಸುವುದು](../../../docs) -- [VS ಕೋಡ್‌ನಲ್ಲಿ ಪರೀಕ್ಷೆಗಳನ್ನು ನಡೆಸುವುದು](../../../docs) -- [ಪರೀಕ್ಷಾ ಉಲ್ಲೇಖಗಳು](../../../docs) -- [ಪರೀಕ್ಷಾ ತತ್ತ್ವಶಾಸ್ತ್ರ](../../../docs) -- [ಮುಂದಿನ ಹಂತಗಳು](../../../docs) +- [ಶೀಘ್ರ ಪ್ರಾರಂಭ](#ಶೀಘ್ರ-ಪ್ರಾರಂಭ) +- [ಪರೀಕ್ಷೆಗಳು ಏನು ಕವರ್ ಮಾಡುತ್ತವೆ](#ಪರೀಕ್ಷೆಗಳು-ಏನು-ಕವರ್-ಮಾಡುತ್ತವೆ) +- [ಪರೀಕ್ಷೆಗಳನ್ನು ನಡೆಸುವುದು](#ಪರೀಕ್ಷೆಗಳನ್ನು-ನಡೆಸುವುದು) +- [VS ಕೋಡ್‌ನಲ್ಲಿ ಪರೀಕ್ಷೆಗಳನ್ನು ನಡೆಸುವುದು](#vs-ಕೋಡ್‌ನಲ್ಲಿ-ಪರೀಕ್ಷೆಗಳನ್ನು-ನಡೆಸುವುದು) +- [ಪರೀಕ್ಷೆ ಮಾದರಿಗಳು](#ಪರೀಕ್ಷೆ-ಮಾದರಿಗಳು) +- [ಪರೀಕ್ಷೆ ತತ್ವಶಾಸ್ತ್ರ](#ಪರೀಕ್ಷೆ-ತತ್ವಶಾಸ್ತ್ರ) +- [ಮುಂದಿನ ಹೆಜ್ಜೆಗಳು](#ಮುಂದಿನ-ಹೆಜ್ಜೆಗಳು) -ಈ ಮಾರ್ಗದರ್ಶಿ API ಕೀಗಳು ಅಥವಾ ಹೊರಗಿನ ಸೇವೆಗಳ ಅಗತ್ಯವಿಲ್ಲದೆ AI ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಹೇಗೆ ಪರೀಕ್ಷಿಸಲು ಸಾಧ್ಯವೆಂಬುದನ್ನು ತೋರಿಸುವ ಪರೀಕ್ಷೆಗಳ ಮೂಲಕ ನಿಮಗೆ ಮಾರ್ಗದರ್ಶನ ಮಾಡುತ್ತದೆ. +ಈ ಮಾರ್ಗದರ್ಶಿ API ರಹಸ್ಯಗಳು ಅಥವಾ ಹೊರಗಿನ ಸೇವೆಗಳನ್ನು ಅವಲಂಬಿಸದೆ ಎಐ ಅಪ್ಲಿಕೇಶನ್‌ಗಳನ್ನು ಹೇಗೆ ಪರೀಕ್ಷಿಸುವುದನ್ನು ತೋರಿಸುವ ಪರೀಕ್ಷೆಗಳ ಮೂಲಕ ನಿಮ್ಮನ್ನು ನಡೆಸುತ್ತದೆ. -## ತ್ವರಿತ ಪ್ರಾರಂಭ +## ಶೀಘ್ರ ಪ್ರಾರಂಭ -ಒಂದು ಆಜ್ಞೆಯೊಂದಿಗೆ ಎಲ್ಲಾ ಪರೀಕ್ಷೆಗಳನ್ನು ರನ್ ಮಾಡಿ: +ಒಂದು ಆಜ್ಞೆ ಮೂಲಕ ಎಲ್ಲಾ ಪರೀಕ್ಷೆಗಳನ್ನು ನಡೆಸಿ: **ಬ್ಯಾಶ್:** ```bash @@ -26,32 +26,32 @@ mvn test mvn --% test ``` -ಎಲ್ಲಾ ಪರೀಕ್ಷೆಗಳು ಯಶಸ್ವಿಯಾಗಿ ನಡೆದರೆ, ಕೆಳಗಿನ ಸ್ಕ್ರೀನ್ಶಾಟ್‌ನಂತೆ ಔಟ್‌ಪುಟ್ ಕಾಣಬೇಕು — ಯಾವುದೇ ವಿಫಲತೆಗಳಿಲ್ಲದೆ ಪರೀಕ್ಷೆಗಳು ನಡೆಯುತ್ತವೆ. + +ಎಲ್ಲಾ ಪರೀಕ್ಷೆಗಳು ಸಫಲವಾಗಿದ್ದರೆ, ಕೆಳಗಿನ ಸ್ಕ್ರೀನ್ಶಾಟ್‌ನಲ್ಲಿ ಇರುವಂತೆ ಔಟ್‌ಪುಟ್ ಕಾಣಬೇಕು — ಪ್ರಮಾದಗಳಿಲ್ಲದೆ ಪರೀಕ್ಷೆಗಳು ನಡೆಯುತ್ತವೆ. Successful Test Results -*ಯಶಸ್ವಿಯಾದ ಪರೀಕ್ಷೆಗಳ ನಿರ್ವಹಣೆ ಸಕಲ ಪರೀಕ್ಷೆಗಳು ಯಾವುದೇ ದೋಷಗಳಿಲ್ಲದೆ ಜಯವಂತವಾಗಿದೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ* +*ಪ್ರಮಾದಗಳಿಲ್ಲದೆ ಎಲ್ಲಾ ಪರೀಕ್ಷೆಗಳು ಸಫಲವಾಗಿ ನಡೆದಿರುವುದನ್ನು ತೋರಿಸುವ ಯಶಸ್ವಿ ಪರೀಕ್ಷಾ ಕಾರ್ಯಪ್ರದರ್ಶನ* -## ಪರೀಕ್ಷೆಗಳು ಏನು ಒಳಗೊಂಡಿವೆ +## ಪರೀಕ್ಷೆಗಳು ಏನು ಕವರ್ ಮಾಡುತ್ತವೆ -ಈ ಕೋರ್ಸ್ ಸ್ಥಳೀಯವಾಗಿ ನಡೆಯುವ **ಒಕ್ಕಣೆ ಪರೀಕ್ಷೆಗಳನ್ನು** (unit tests) ಗಮನಿಸುತ್ತದೆ. ಪ್ರತಿ ಪರೀಕ್ಷೆ ಒಂದು ನಿರ್ದಿಷ್ಟ LangChain4j ತತ್ವವನ್ನು ವಿಭಿನ್ನವಾಗಿ ತೋರಿಸುತ್ತದೆ. ಕೆಳಗಿನ ಪರೀಕ್ಷಾ ಪಿರಮಿಡುವು ಒಕ್ಕಣೆ ಪರೀಕ್ಷೆಗಳು ಎಲ್ಲಿ ಹೊಂದಿಕೊಳ್ಳುತ್ತವೆ ಎಂಬುದನ್ನು ತೋರುತ್ತದೆ — ಇವು ವೇಗವಾದ, ನಂಬಬಹುದಾದ ಆಧಾರವನ್ನು ರೂಪಿಸಿ, ನಿಮ್ಮ ಇತರೆ ಪರೀಕ್ಷಾ ತಂತ್ರಗಳನ್ನು ನಿರ್ಮಾಪಕವಾಗಿವೆ. +ಈ ಕೋರ್ಸ್ ಸ್ಥಳೀಯವಾಗಿ ನಡೆಯುವ **ಯೂನಿಟ್ ಪರೀಕ್ಷೆಗಳನ್ನು** ಕೌಂದಲ್ಯಗೊಳಿಸಿದೆ. ಪ್ರತಿ ಪರೀಕ್ಷೆಲಲ್ಲಿ LangChain4j ಯೊಂದು ನಿಖರವಾದ ಕಲ್ಪನೆಯನ್ನು ಪ್ರತ್ಯೇಕವಾಗಿ ಪ್ರದರ್ಶಿಸುತ್ತದೆ. ಕೆಳಗಿನ ಪರೀಕ್ಷಾ ಪಿರಮಿಡ್ ಯೂನಿಟ್ ಪರೀಕ್ಷೆಗಳು ಎಲ್ಲ ಅಂಶಗಳ ತಳಹದಿಯಾಗಿವೆ ಎಂಬುದನ್ನು ತೋರಿಸುತ್ತದೆ — ಇವು ವೇಗದ, ಭರವಸೆಯಾದ ಅಸ್ತಂಭಗಳು. Testing Pyramid -*ಒಕ್ಕಣೆ ಪರೀಕ್ಷೆಗಳು (ವೇಗವಾದ, ವಿಭಜಿತ), ಸಂಯೋಜನೆ ಪರೀಕ್ಷೆಗಳು (ನಿಜವಾದ ಘಟಕಗಳು), ಮತ್ತು ಅಂತ್ಯ-देखि-ಅಂತ್ಯ ಪರೀಕ್ಷೆಗಳ ನಡುವಿನ ಸಮತೋಲನವನ್ನು ತೋರುವ ಪರೀಕ್ಷಾ ಪಿರಮಿಡು. ಈ ತರಬೇತಿ ಒಕ್ಕಣೆ ಪರೀಕ್ಷೆಯನ್ನು ಒಳಗೊಂಡಿದೆ.* +*ಪರೀಕ್ಷಾ ಪಿರಮಿಡ್, ಯೂನಿಟ್ ಪರೀಕ್ಷೆಗಳ (ವೇಗದ, ಪ್ರತ್ಯೇಕित), ಏಕೀಕರಣ ಪರೀಕ್ಷೆಗಳು (ನಿಜವಾದ ಘಟಕಗಳು), ಮತ್ತು ಅಂತ್ಯ-ಮುಗಿಯುವ ಪರೀಕ್ಷೆಗಳನ್ನು ತೋರಿಸುತ್ತದೆ. ಈ ತರಬೇತಿ ಯೂನಿಟ್ ಪರೀಕ್ಷೆಯನ್ನು ಒಳಗೊಂಡಿದೆ.* -| ಮೊಡ್ಯೂಲ್ | ಪರೀಕ್ಷೆಗಳು | ಗಮನ | ಮುಖ್ಯ ಫೈಲ್‌ಗಳು | -|--------|-------|-------|-----------| -| **00 - ತ್ವರಿತ ಪ್ರಾರಂಭ** | 6 | ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟುಗಳು ಮತ್ತು ಬದಲಾವಣಾ ಪರಿವರ್ತನೆ | `SimpleQuickStartTest.java` | -| **01 - ಪರಿಚಯ** | 8 | ಸಂವಾದ ಸ್ಮೃತಿ ಮತ್ತು ಸ್ಥಿತಿ ಸಂವಾದ | `SimpleConversationTest.java` | -| **02 - ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್** | 12 | GPT-5.2 ಮಾದರಿಗಳು, ಆಸಕ್ತಿರ್ದೇಶಕ ಮಟ್ಟಗಳು, ವಿನ್ಯಾಸಗೊಳಿಸಿದ ಔಟ್‌ಪುಟ್ | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | ಡಾಕ್ಯುಮೆಂಟ್ ಒಳಗೊಂಡಿಕೆ, ಎಂಬೆಡ್ಡಿಂಗ್ಸ್, ಸಾದೃಶ್ಯ ಹುಡುಕಾಟ | `DocumentServiceTest.java` | -| **04 - ಉಪಕರಣಗಳು** | 12 | ಕಾರ್ಯ ಕರೆ ಮತ್ತು ಉಪಕರಣ ಸರಪಳಿ | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol ಜೊತೆಗೆ Stdio ಸಾರಿಗೆ | `SimpleMcpTest.java` | +| ಮೋಡುಲ್ | ಪರೀಕ್ಷೆಗಳು | ಗುರಿ | ಪ್ರಮುಖ ಕಡತಗಳು | +|--------|------------|-------|-------------------| +| **01 - ಪರಿಚಯ** | 8 | ಸಂಭಾಷಣೆ ಮೆಮೊರಿ ಮತ್ತು ಸ್ಥಿತಿಗತ ಚಾಟ್ | `SimpleConversationTest.java` | +| **02 - ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್** | 12 | GPT-5.2 ಮಾದರಿಗಳು, ಆಸಕ್ತಿಯ ಮಟ್ಟಗಳು, ಸಂರಚಿತ ಔಟ್‌ಪುಟ್ | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | ಡಾಕ್ಯುಮೆಂಟ್ ಇಂಜೆಕ್ಷನ್, ಎಂಭೆಡಿಂಗ್ಸ್, ಸಾದೃಶ್ಯ ಹುಡುಕಿ | `DocumentServiceTest.java` | +| **04 - ಉಪಕರಣಗಳು** | 12 | ಫಂಕ್ಷನ್ ಕರೆದೊಯ್ಯುವುದು ಮತ್ತು ಉಪಕರಣ ಸರಪಳಿ | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol ಸ್ಟ್ಡಿಯೋ ಸಾರಿಗೆ | `SimpleMcpTest.java` | ## ಪರೀಕ್ಷೆಗಳನ್ನು ನಡೆಸುವುದು -**ಮೂಲದಿಂದ ಎಲ್ಲಾ ಪರೀಕ್ಷೆಗಳನ್ನು ರನ್ ಮಾಡು:** +**ಮೂಲ ಡೈರೆಕ್ಟರಿಯಿಂದ ಎಲ್ಲಾ ಪರೀಕ್ಷೆಗಳನ್ನು ಚಲಾಯಿಸು:** **ಬ್ಯಾಶ್:** ```bash @@ -63,23 +63,25 @@ mvn test mvn --% test ``` -**ನಿರ್ದಿಷ್ಟ ಮೊಡ್ಯೂಲ್‌ಗೆ ಪರೀಕ್ಷೆಗಳನ್ನು ರನ್ ಮಾಡು:** + +**ನಿರ್ದಿಷ್ಟ ಮೋಡುಲ್‌ಗೆ ಪರೀಕ್ಷೆಗಳನ್ನು ನಿರ್ವಹಿಸಲು:** **ಬ್ಯಾಶ್:** ```bash cd 01-introduction && mvn test -# ಅಥವಾ ಮೂಲದಿಂದ +# ಅಥವಾ ರೂಟ್‌ನಿಂದ mvn test -pl 01-introduction ``` **ಪವರ್‌ಶೆಲ್:** ```powershell cd 01-introduction; mvn --% test -# ಅಥವಾ ರೂಟ್‌ನಿಂದ +# ಅಥವಾ ಮೂಳಿನಿಂದ mvn --% test -pl 01-introduction ``` -**ಒಂದು ಪರೀಕ್ಷಾ ಕ್ಲಾಸ್ ರನ್ ಮಾಡು:** + +**ಒಂದು ಪರೀಕ್ಷಾ ಕ್ಲಾಸ್ ಅನ್ನು ನಡೆಸಲು:** **ಬ್ಯಾಶ್:** ```bash @@ -91,45 +93,47 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**ನಿರ್ದಿಷ್ಟ ಪರೀಕ್ಷಾ ವಿಧಾನ ರನ್ ಮಾಡು:** + +**ನಿರ್ದಿಷ್ಟ ಪರೀಕ್ಷಾ ಮೆಥಡ್ ಅನ್ನು ನಡೆಸಲು:** **ಬ್ಯಾಶ್:** ```bash -mvn test -Dtest=SimpleConversationTest#ಸಂವowaćನ ಇತಿಹಾಸವನ್ನು ಕಾಪಾಡಬೇಕು +mvn test -Dtest=SimpleConversationTest#ಸಂಭಾಷಣಾ ಇತಿಹಾಸವನ್ನು ಕಾಯ್ದುಕೊಳ್ಳಬೇಕು ``` **ಪವರ್‌ಶೆಲ್:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#ಸಂಭಾಷಣೆ ಇತಿಹಾಸವನ್ನು ಕಾಪಾಡಿಕೊಳ್ಳಬೇಕು +mvn --% test -Dtest=SimpleConversationTest#ಸಂಭಾಷಣಾ ಇತಿಹಾಸವನ್ನು ಕಾಯ್ದುಕೊಳ್ಳಬೇಕು ``` + ## VS ಕೋಡ್‌ನಲ್ಲಿ ಪರೀಕ್ಷೆಗಳನ್ನು ನಡೆಸುವುದು -ನೀವು Visual Studio Code ಬಳಸುತ್ತಿದ್ದರೆ, Test Explorer ಗ್ರಾಫಿಕಲ್ ಇಂಟರ್ಫೇಸ್‌ನ್ನು ಪರೀಕ್ಷೆಗಳು ರನ್ ಮತ್ತು ಡಿಬಗ್ ಮಾಡಲು ನೀಡುತ್ತದೆ. +ನೀವು Visual Studio Code ಬಳಸುತ್ತಿದ್ದರೆ, ಟೆಸ್ಟ್ ಎಕ್ಸ್‌ಪ್ಲೋರ್ ಗ್ರಾಫಿಕಲ್ ಇಂಟರ್ಫೇಸ್ ಅನ್ನು ಒದಗಿಸುತ್ತದೆ, ಇದು ಪರೀಕ್ಷೆಗಳನ್ನು ಚಲಾಯಿಸುವುದಕ್ಕೆ ಮತ್ತು ಡಿಬಗ್ ಮಾಡಲು ಸಹಾಯಕ. VS Code Test Explorer -*VS ಕೋಡ್ ಟೆಸ್ಟ್ ಎಕ್ಸ್‌ಪ್ಲೋರರ್ ಎಲ್ಲಾ ಜಾವಾ ಪರೀಕ್ಷಾ ಕ್ಲಾಸ್‌ಗಳು ಮತ್ತು ವೈಯಕ್ತಿಕ ಪರೀಕ್ಷಾ ವಿಧಾನಗಳೊಂದಿಗೆ ಪರೀಕ್ಷಾ ಮರವನ್ನು ತೋರುತ್ತದೆ* +*VS ಕೋಡ್ ಟೆಸ್ಟ್ ಎಕ್ಸ್ಪ್ಲೋರ್ ಟೆಸ್ಟ್ ಗಿಡವು ಎಲ್ಲ Java ಟೆಸ್ಟ್ ಕ್ಲಾಸುಗಳ ಮತ್ತು ವೈಯಕ್ತಿಕ ಪರೀಕ್ಷಾ ವಿಧಾನಗಳೊಂದಿಗೆ ತೋರಿಸುತ್ತದೆ* **VS ಕೋಡ್‌ನಲ್ಲಿ ಪರೀಕ್ಷೆಗಳನ್ನು ನಡೆಸಲು:** -1. ಚಟುವಟಿಕೆ ಬಾರಿನಲ್ಲಿ ಇರುವ ಬಿಕರ್ ಐಕಾನ್ ಮೇಲೆ ಕ್ಲಿಕ್ ಮಾಡಿ Test Explorer ತೆರೆಯಿರಿ -2. ಎಲ್ಲಾ ಮೊಡ್ಯೂಲ್‌ಗಳು ಮತ್ತು ಪರೀಕ್ಷಾ ಕ್ಲಾಸ್‌ಗಳನ್ನು ನೋಡಲು ಪರೀಕ್ಷಾ ಮರವನ್ನು ವಿಸ್ತರಿಸಿ -3. ಯಾವುದೇ ಪರೀಕ್ಷೆಯನ್ನು ವೈಯಕ್ತಿಕವಾಗಿ ರನ್ ಮಾಡಲು ಅದರ ಪಕ್ಕದ ಪ್ಲೇ ಬಟನ್ ಕ್ಲಿಕ್ ಮಾಡಿ -4. ಪೂರ್ಣ ಸьют್ ಅನ್ನು ರನ್ ಮಾಡಲು "Run All Tests" ಕ್ಲಿಕ್ ಮಾಡಿ -5. ಯಾವುದೇ ಪರೀಕ್ಷೆಯನ್ನು ರೈಟ್ ಕ್ಲಿಕ್ ಮಾಡಿ "Debug Test" ಆಯ್ಕೆ ಮಾಡಿ ಬ್ರೇಕ್‌ಪಾಯಿಂಟ್‌ಗಳನ್ನು ಸೆಟ್ ಮಾಡಿ ಮತ್ತು ಕೋಡ್ನಲ್ಲಿ ಪ್ರಗತಿಪಡಿರಿ +1. ಕ್ರಿಯೆ ಪಟ್ಟಿಯ ಬಾರ್‌ನಲ್ಲಿ ಬಿಕರ್ ಐಕಾನ್ ಕ್ಲಿಕ್ ಮಾಡಿ ಟೆಸ್ಟ್ ಎಕ್ಸ್‌ಪ್ಲೋರರ್ ಅನ್ನು ತೆರೆದುಕೊಳ್ಳಿ +2. ಎಲ್ಲಾ ಮೋಡುಲ್‌ಗಳು ಮತ್ತು ಟೆಸ್ಟ್ ಕ್ಲಾಸ್‌ಗಳನ್ನು ವಿಸ್ತರಿಸಿ ನೋಡಿ +3. ಪ್ರತಿ ಪರೀಕ್ಷೆಯ ಬೆರಗಿನ ಬटनನ್ನು ಕ್ಲಿಕ್ ಮಾಡಿ ಅದು ವೈಯಕ್ತಿಕವಾಗಿ ಚಲಾಯಿಸಲು +4. "ಎಲ್ಲಾ ಪರೀಕ್ಷೆಗಳನ್ನು ನಡೆಸು" ಕ್ಲಿಕ್ ಮಾಡಿ ಸಂಪೂರ್ಣ ಸ್ಯೂಟ್ ಕಾರ್ಯಗತಗೊಳಿಸಲು +5. ಯಾವುದೇ ಪರೀಕ್ಷೆಯನ್ನು ರೈಟ್ ಕ್ಲಿಕ್ ಮಾಡಿ "ಡಿಬಗ್ ಟೆಸ್ಟ್" ಆಯ್ಕೆ ಮಾಡಿ ಬ್ರೇಕ್ ಪಾಯಿಂಟ್‌ಗಳನ್ನು ಸೆಟ್ ಮಾಡಿ ಮತ್ತು ಕ್ರಮದಲ್ಲಿ ಹೆಜ್ಜೆ ಹಾಕಿ -ಪరీక్షೆ ಯಶಸ್ವಿಯಾಗಿದ್ದಾಗ, ಪರೀಕ್ಷಾ ಎಕ್ಸ್‌ಪ್ಲೋರರ್ ಹಸಿರು ಚಿನ್ನದ ಗುರುತುಗಳನ್ನು ತೋರಿಸುತ್ತದೆ ಮತ್ತು ವಿಫಲವಾದಾಗ ವಿವರವಾದ ದೋಷ ಸಂದೇಶಗಳನ್ನು ನೀಡುತ್ತದೆ. +ಪರೀಕ್ಷೆಗಳು ಪಾಸಾಗುವಾಗ ಹಸಿರು ಸಾಧ್ಯತೆ ಗುರುತು ತೋರಿಸುತ್ತವೆ ಮತ್ತು ವೈಫಲ್ಯಗಳಾಗುವಾಗ ವಿವರಣಾತ್ಮಕ ಜತೆಗಿನ ಸಂದೇಶ ನೀಡುತ್ತವೆ. -## ಪರೀಕ್ಷಾ ಉಲ್ಲೇಖಗಳು +## ಪರೀಕ್ಷೆ ಮಾದರಿಗಳು -### ಉಲ್ಲೇಖ 1: ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟುಗಳನ್ನು ಪರೀಕ್ಷಿಸುವುದು +### ಮಾದರಿ 1: ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್‌ಗಳನ್ನು ಪರೀಕ್ಷಿಸುವುದು -ಸರಳವಾದ ಉಲ್ಲೇಖವು ಯಾವುದೇ AI ಮಾದರಿಯನ್ನು ಕರೆಸದೇ ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟುಗಳನ್ನು ಪರೀಕ್ಷಿಸುತ್ತದೆ. ನಿಮಗೆ ಬದಲಾವಣೆ ಪರಿವರ್ತನೆ ಸರಿಯಾಗಿ ಕೆಲಸ ಮಾಡುತ್ತಿದೆಯೇ ಮತ್ತು ಪ್ರಾಂಪ್ಟ್‌ಗಳು ನಿರೀಕ್ಷಿತ ರೀತಿಯಲ್ಲಿ ವಿನ್ಯಾಸಗೊಳ್ಳುತ್ತವೆಯೇ ಎಂಬುದನ್ನು ಪರಿಶೀಲಿಸುವ ಅವಕಾಶ ಇರುತ್ತದೆ. +ಸರಳವಾದ ಮಾದರಿ ಯಾವುದೇ ಎಐ ಮಾದರಿಯನ್ನು ಕರೆದಿಲ್ಲದೆ ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್‌ಗಳನ್ನು ಪರೀಕ್ಷಿಸುತ್ತದೆ. ನೀವು ವ್ಯತ್ಯಯವನ್ನು ಸರಿಯಾಗಿ ಬದಲಾಯಿಸಲಾಗುತ್ತದೆಯೇ ಮತ್ತು ಪ್ರಾಂಪ್ಟ್‌ಗಳು ನಿರೀಕ್ಷಿತವಾಗಿ ರೂಪಿಸಬಹುದೇ ಎಂದು ಪರಿಶೀಲಿಸಬೇಕು. Prompt Template Testing -*ಬದಲಾವಣೆ ಸ್ಥಾನದೊಂದಿಗೆ ಟೆಂಪ್ಲೇಟ್ → ಮೌಲ್ಯ ಅನ್ವಯಣೆ → ವಿನ್ಯಾಸಗೊಳಿಸಿದ ಔಟ್‌ಪುಟ್ ಪರಿಶೀಲನೆ ಹರಿವು ತೋರಿಸುವ ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್ ಪರೀಕ್ಷೆ* +*ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್ ಪರೀಕ್ಷಿಸುವುದು, ಪ್ಲೇಸ್‌ಹೋಲ್ಡರ್‌ಗಳೊಂದಿಗೆ ಟೆಂಪ್ಲೇಟ್ → ಮೌಲ್ಯ ಬದಲಾಯಿಸುವುದು → ರೂಪಿತ ಔಟ್‌ಪುಟ್ ಪರಿಶೀಲನೆ* ```java @Test @@ -148,27 +152,15 @@ void testPromptTemplateFormatting() { } ``` -ಈ ಪರೀಕ್ಷೆ `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` ನಲ್ಲಿ ಇದೆ. +ಈ ಮಾದರಿ ವ್ಯತ್ಯಯ ಬದಲಾವಣೆ ಸರಿಯಾಗಿ ನಡೆಯುತ್ತದೆ ಎಂದು ಮತ್ತು ಪ್ರಾಂಪ್ಟ್ ಗಳು ನಿರೀಕ್ಷಿತವಾಗಿ ರೂಪಿತವಾಗುತ್ತವೆ ಎಂದು ಪರಿಶೀಲಿಸುತ್ತದೆ — API ಕೀ ಅಥವಾ ಮಾದರಿ ಕರೆಗೆ ಅಗತ್ಯವಿಲ್ಲ. -**ಇದನ್ನು ರನ್ ಮಾಡುವ ಮೂಲಕ:** +### ಮಾದರಿ 2: ಭಾಷಾ ಮಾದರಿಗಳನ್ನು ಮಾಕ್ ಮಾಡುವುದು -**ಬ್ಯಾಶ್:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#ಪರೀಕ್ಷಾ ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟಿನ ರೂಪರೇಷೆ -``` - -**ಪವರ್‌ಶೆಲ್:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#ಟೆಸ್ಟ್ ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟು ಫಾರ್ಮ್ಯಾಟಿಂಗ್ -``` - -### ಉಲ್ಲೇಖ 2: ಭಾಷಾ ಮಾದರಿಗಳನ್ನು ಮಾಕಿಂಗ್ ಮಾಡುವುದು - -ಸಂವಾದ ಲಾಜಿಕ್ನು ಪರೀಕ್ಷಿಸುವಾಗ, ನಿರ್ಧಾರಿತ ಪ್ರತಿಕ್ರಿಯೆಗಳನ್ನ ನೀಡುವ ನಕಲಿ ಮಾದರಿಗಳನ್ನು ರಚಿಸಲು Mockito ಬಳಸಿ. ಇದರಿಂದ ಪರೀಕ್ಷೆಗಳು ವೇಗವಾಗಿ, ಉಚಿತವಾಗಿ ಮತ್ತು ನಿರ್ದಿಷ್ಟವಾಗಿ ನಡೆಯುತ್ತವೆ. +ಸಂಭಾಷಣೆ ತರ್ಕವನ್ನು ಪರೀಕ್ಷಿಸುವಾಗ, ಹಿಂದಿನಿಂದ ನಿಗದಿತ ಪ್ರತಿಕ್ರಿಯೆ ನೀಡುವ ನಕಲಿ ಮಾದರಿಗಳನ್ನು ಸೃಷ್ಟಿಸಲು Mockito ಬಳಸಿರಿ. ಇದರಿಂದ ಪರೀಕ್ಷೆಗಳು ವೇಗವಾಗಿ, ಉಚಿತವಾಗಿ, ಮತ್ತು ನಿರ್ಧಿಷ್ಟವಾಗುತ್ತವೆ. Mock vs Real API Comparison -*ಪರೀಕ್ಷೆಗಾಗಿ ಮಾಕ್‌ಗಳನ್ನು προಥಮಸ್ಥಾನದಿರುವುದಕ್ಕೆ ಕಾರಣ ತೋರಿಸುವ ಹೋಲಿಕೆ: ಅವುಗಳು ವೇಗವಾದವು, ಉಚಿತವಾಗಿವೆ, ನಿರ್ದಿಷ್ಟವಾಗಿವೆ ಮತ್ತು API ಕೀಲಿಗಳನ್ನು ಅಗತ್ಯವಾಗದೆ ಇರಿಸುವುದು* +*ಮೂಕಿ ಮಾದರಿಗಳು ಏಕೆ ಆಪಿಯು ಕಿಲಿಯ ಬದಿಗೆ ಇಷ್ಟಪಡುವುದನ್ನು ತೋರಿಸುವ ಹೋಲಿಕೆ: ಅವು ವೇಗವಾದ, ಉಚಿತ, ನಿರ್ಧಿಷ್ಟ, ಮತ್ತು API ಕೀಗಳನ್ನು ಬೇಕಾಗದೆ* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +210,15 @@ class SimpleConversationTest { } ``` -ಈ ಉಲ್ಲೇಖ `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`‌ನಲ್ಲಿ ಇದೆ. ಮಾಕ್ ಸ್ಥಿರ ಬಿಹೇವಿಯರ್ ಖಚಿತಪಡಿಸುವುದರಿಂದ ನೀವು ಸ್ಮೃತಿ ನಿರ್ವಹಣೆಯು ಸರಿಯಾಗಿದೆಯೇ ಎಂದು ಪರಿಶೀಲಿಸಬಹುದು. +ಈ ಮಾದರಿ `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` ನಲ್ಲಿ ಕಾಣಬಹುದು. ಮಾಕ್ ನಿರಂತರ ವರ್ತನೆ ಖಚಿತಪಡಿಸಿಕೊಳುತ್ತದೆ ನೀವು ಮೆಮೊರಿ ನಿರ್ವಹಣೆಯನ್ನು ಸರಿಯಾಗಿ ಪರಿಶೀಲಿಸಬಹುದು. -### ಉಲ್ಲೇಖ 3: ಸಂವಾದ ವಿಭಜನೆಯ ಪರೀಕ್ಷೆ +### ಮಾದರಿ 3: ಸಂಭಾಷಣೆ ಪ್ರತ್ಯೇಕತೆಯನ್ನು ಪರೀಕ್ಷಿಸುವುದು -ಸಂವಾದ ಸ್ಮೃತಿ ಹಲವು ಬಳಕೆದಾರರನ್ನು ಬೇರೆಯಾಗಿ ಹಿಡಿದಿಡಬೇಕು. ಈ ಪರೀಕ್ಷೆ ಸಂವಾದಗಳು ಸ೦ದರ್ಭಗಳನ್ನು ಮಿಶ್ರಮಾಡುವುದಿಲ್ಲ ಎಂದು ಪರಿಶೀಲಿಸುತ್ತದೆ. +ಸಂಭಾಷಣೆ ಮೆಮೊರಿಯು ಬಾಹ್ಯ ಬಳಕೆದಾರರಿಗೆ ಪ್ರತ್ಯೇಕವಾಗಿರಬೇಕು. ಈ ಪರೀಕ್ಷೆ ಸಂಭಾಷಣೆಗಳು ಸಂಧರ್ಭಗಳನ್ನು ಮಿಶ್ರಿಸುವುದರಿಂದ ತಪ್ಪಿಸಿಕೊಳ್ತದೆ ಎಂದು ಖಚಿತಪಡಿಸುತ್ತದೆ. Conversation Isolation -*ವಿಭಿನ್ನ ಬಳಕೆದಾರರಿಗಾಗಿ ಪ್ರತ್ಯೇಕ ಸ್ಮೃತಿ ಸಂಗ್ರಹಣೆ ತೋರಿಸುವ ಸಂವಾದ ವಿಭಜನೆಯ ಪರೀಕ್ಷೆ, ಸ೦ದರ್ಭ ಮಿಶ್ರಣ ತಡೆಯಲು* +*ವಿವಿಧ ಬಳಕೆದಾರರಿಗಾಗಿ ಪ್ರತ್ಯೇಕ ಮೆಮೊರಿ ಮಳಕನ್ನು ತೋರಿಸುವ ಸಂಭಾಷಣೆ ಪ್ರತ್ಯೇಕತೆ ಪರೀಕ್ಷೆ* ```java @Test @@ -250,15 +242,15 @@ void shouldIsolateConversationsByid() { } ``` -ಪ್ರತಿ ಸಂವಾದವು ತನ್ನ ಸ್ವತಂತ್ರ ಇತಿಹಾಸವನ್ನು ನಿರ್ವಹಿಸುತ್ತದೆ. ಉತ್ಪಾದನಾ ವ್ಯವಸ್ಥೆಗಳಲ್ಲಿ, ಬಹು ಬಳಕೆದಾರರ ಅಪ್ಲಿಕೇಶನ್‌ಗಳಿಗೆ ಈ ವಿಭಜನೆ ಅವಶ್ಯಕ. +ಪ್ರತಿ ಸಂಭಾಷಣೆ ತನ್ನ ಸ್ವಂತ ಸ್ವತಂತ್ರ ಇತಿಹಾಸವನ್ನು ನಿಭಾಯಿಸುತ್ತದೆ. ಉತ್ಪಾದನೆ ವ್ಯವಸ್ಥೆಗಳಲ್ಲಿ, ಈ ಪ್ರತ್ಯೇಕತೆ ಬಹು-ಬಳಕೆದಾರ ಅಪ್ಲಿಕೇಶನ್‌ಗಳಿಗೆ ಪ್ರಮುಖವಾಗಿದೆ. -### ಉಲ್ಲೇಖ 4: ಉಪಕರಣಗಳನ್ನು ಸ್ವತಂತ್ರವಾಗಿ ಪರೀಕ್ಷಿಸುವುದು +### ಮಾದರಿ 4: ಉಪಕರಣಗಳನ್ನು ಸ್ವತಂತ್ರವಾಗಿ ಪರೀಕ್ಷಿಸುವುದು -ಉಪಕರಣಗಳು AI ಕರೆಸಬಹುದಾದ ಕಾರ್ಯಗಳಾಗಿವೆ. AI ನಿರ್ಧಾರಗಳ ಪ್ರಭಾವವಿಲ್ಲದೆ ಸರಿಯಾಗಿ ಕೆಲಸ ಮಾಡುತ್ತಿರುವುದನ್ನು ಖಚಿತಪಡಿಸಲು ಅವುಗಳನ್ನು ನೇರವಾಗಿ ಪರೀಕ್ಷಿಸಿ. +ಉಪಕರಣಗಳು ಎಐ ಕರೆತರುವ ಕಾರ್ಯಗಳಾಗಿವೆ. ಅವುಗಳನ್ನು ನೇರವಾಗಿ ಪರೀಕ್ಷಿಸಿ ಒಳ್ಳೆಯ ತರ್ಕಗಳನ್ನು ಎಲ್ಲಿಂದಲಾದರೂ ಕೆಲಸ ಮಾಡುತ್ತವೆ ಎಂದು ಖಚಿತಪಡಿಸಿಕೊಳ್ಳಿ. Tools Testing -*AI ಕರೆಗಳು ಇಲ್ಲದೆ ನಕಲಿ ಉಪಕರಣ ಕಾರ್ಯಗತಗೊಳಿಸುವಿಕೆ ತೋರಿಸುವ ಉಪಕರಣಗಳ ಸ್ವತಂತ್ರ ಪರೀಕ್ಷೆ, ವ್ಯವಹಾರ ಲಾಜಿಕ್ ಪರಿಶೀಲನೆಗಾಗಿ* +*ಎಐ ಕರೆಗಳಿಲ್ಲದೆ ನಕಲಿ ಉಪಕರಣ ನಿರ್ವಹಣೆಯನ್ನು ತೋರಿಸುವ ಉಪಕರಣ ಪರಿಶೀಲನೆ* ```java @Test @@ -281,15 +273,15 @@ void shouldDemonstrateToolChaining() { } ``` -`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ನಿಂದ ಈ ಪರೀಕ್ಷೆಗಳು AI ಭಾಗವಹಿಸದೇ ಉಪಕರಣ ಲಾಜಿಕ್ ಸರಿಹೊರಹನ್ನು ದೃಢಪಡಿಸುತ್ತವೆ. ಸರಪಳಿ ಉದಾಹರಣೆ ಒಂದು ಉಪಕರಣದ ಔಟ್‌ಪುಟ್ ಮತ್ತೊಂದು ಉಪಕರಣದ ಇನ್‌ಪುಟ್ ಆಗಿ ಬಳಸಲಿರುವ ವಿಧಾನ ತೋರಿಸುತ್ತದೆ. +`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ನಿಂದ ಈ ಪರೀಕ್ಷೆಗಳು ಎಐ ಭಾಗವಹಿಸದೇ ಉಪಕರಣ ತರ್ಕವನ್ನು ಪರಿಶೀಲಿಸುತ್ತವೆ. ಸರಪಳಿ ಮಾದರಿ ಒಂದು ಉಪಕರಣದ ಔಟ್‌ಪುಟ್ ಮತ್ತೊಂದು ಉಪಕರಣದ ಇನ್‌ಪುಟ್ ಆಗುವುದು ಹೇಗೋ ತೋರಿಸುತ್ತದೆ. -### ಉಲ್ಲೇಖ 5: ಮೇಮರಿ RAG ಪರೀಕ್ಷೆ +### ಮಾದರಿ 5: ಮೆಮೊರಿಯಲ್ಲಿರುವ RAG ಪರೀಕ್ಷೆ -RAG ವ್ಯವಸ್ಥೆಗಳು ಸಾಮಾನ್ಯವಾಗಿ ವೆಕ್ಟರ್ ಡೇಟಾಬೇಸ್ ಮತ್ತು ಎಂಬೆಡ್ಡಿಂಗ್ ಸೇವೆಗಳ ಅವಶ್ಯಕತೆ ಇರುತ್ತದೆ. ಮೇಮರಿ ಉಲ್ಲೇಖವು ಹೊರಗಿನ ಅವಲಂಬನೆಗಳು ಇಲ್ಲದೆ ಸಂಪೂರ್ಣ ಪೈಪ್‌ಲೈನ್ ಅನ್ನು ಪರೀಕ್ಷಿಸಲು ಅನುಮತಿಸುತ್ತದೆ. +RAG ವ್ಯವಸ್ಥೆಗಳು ಸಾಮಾನ್ಯವಾಗಿ ವೆಕ್ಟರ್ ಡೇಟಾಬೇಸ್‌ಗಳು ಮತ್ತು ಎಂಭೆಡಿಂಗ್ ಸೇವೆಗಳ ಅಗತ್ಯವಿರುತ್ತದೆ. ಮೆಮೊರಿಯಲ್ಲಿರುವ ಮಾದರಿ ನೀವು ಹೊರಗಿನ ಅವಲಂಬನೆಗಳಿಲ್ಲದೆ ಸಂಪೂರ್ಣ ಪೈಪ್ಲೈನ್ ಅನ್ನು ಪರೀಕ್ಷಿಸಲು ಸಹಾಯ ಮಾಡುತ್ತದೆ. In-Memory RAG Testing -*ಡಾಕ್ಯುಮೆಂಟ್ ಪಾರ್ಸಿಂಗ್, ಎಂಬೆಡ್ಡಿಂಗ್ ಸಂಗ್ರಹಣೆ ಮತ್ತು ಸಾದೃಶ್ಯ ಹುಡುಕಾಟವನ್ನು ಡೇಟಾಬೇಸ್ ಅವಶ್ಯಕತೆ ಇಲ್ಲದೆ ತೋರಿಸುವ ಮೇಮರಿ RAG ಪರೀಕ್ಷೆಯ ಕಾರ್ಯವಾಹಿ* +*ಡಾಕ್ಯುಮೆಂಟ್ ವಿಶ್ಲೇಷಣೆ, ಎಂಭೆಡಿಂಗ್ ಸಂಗ್ರಹಣೆ, ಮತ್ತು ಸಾದೃಶ್ಯ ಹುಡುಕಿಕೆಯನ್ನು ಡೇಟಾಬೇಸ್ ವಿನಾ ತೋರಿಸುವ ಮೆಮೊರಿಯಲ್ಲಿ RAG ಪರಿಶೀಲನೆ ಕಾರ್ಯಪ್ರವಾಹ* ```java @Test @@ -306,15 +298,15 @@ void testProcessTextDocument() { } ``` -ಈ ಪರೀಕ್ಷೆ `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` ನಲ್ಲಿ ಇದೆ, ಇದು ಡಾಕ್ಯುಮೆಂಟ್ ಅನ್ನು ಮೇಮರಿಯಲ್ಲಿ ರೂಪಿಸಿ ಚಂಕಿಂಗ್ ಮತ್ತು ಮೆಟಾಡೇಟಾ ನಿರ್ವಹಣೆಯನ್ನು ಪರಿಶೀಲಿಸುತ್ತದೆ. +`03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` ನಿಂದ ಈ ಪರೀಕ್ಷೆ ಎರಡು ದೃಷ್ಟಾಂತಗಳನ್ನು ಸೃಷ್ಟಿಸಿ ಅವುಗಳ ವಿಭಾಗಣೆ ಮತ್ತು ಮೆಟಾಡೇಟಾ ನಿರ್ವಹಣೆಯನ್ನು ಪರಿಶೀಲಿಸುತ್ತದೆ. -### ಉಲ್ಲೇಖ 6: MCP ಸಂಯೋಜನಾ ಪರೀಕ್ಷೆ +### ಮಾದರಿ 6: MCP ಏಕೀಕರಣ ಪರೀಕ್ಷೆ -MCP ಮೊಡ್ಯೂಲ್ Model Context Protocol ಸಂಯೋಜನೆಯನ್ನು stdio ಸಾರಿಗೆಯೊಂದಿಗೆ ಪರೀಕ್ಷಿಸುತ್ತದೆ. ಈ ಪರೀಕ್ಷೆಗಳು ನಿಮ್ಮ ಅಪ್ಲಿಕೇಶನ್ MCP ಸರ್ವರ್‌ಗಳನ್ನು subprocess ಗಳಾಗಿ ಸ್ಟಾರ್ಟ್ ಮಾಡಿ ಸಂವಹನ ನಡೆಸಬಲ್ಲುದೇ ಎಂಬುದನ್ನು ದೃಢಪಡಿಸುತ್ತವೆ. +MCP ಮೋಡುಲ್ Model Context Protocol ಅನ್ನು ಸ್ಟ್ಡಿಯೋ ಸಾರಿಗೆ ಬಳಸಿ ಏಕೀಕರಿಸುವುದನ್ನು ಪರೀಕ್ಷಿಸುತ್ತದೆ. ಈ ಪರೀಕ್ಷೆಗಳು ನಿಮ್ಮ ಅಪ್ಲಿಕೇಶನ್ MCP ಸರ್ವರ್‌ಗಳನ್ನು ಉಪಪ್ರಕ್ರಿಯೆಗಳಾಗಿ ಆರಂಭಿಸಿ ಸಂವಹನ ಮಾಡಬಲ್ಲದು ಎಂದು ಖಚಿತ ಮಾಡಲು ಸಹಾಯಮಾಡುತ್ತವೆ. -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` ನಲ್ಲಿ ಪರೀಕ್ಷೆಗಳು MCP ಕ್ಲಯಿಂಟ್ ವರ್ತನೆಯನ್ನ ಪರಿಶೀಲಿಸುತ್ತವೆ. +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` ನಲ್ಲಿ ಇರುವ ಪರೀಕ್ಷೆಗಳು MCP ಕ್ಲೈಂಟ್ ವರ್ತನೆಯನ್ನು ಖಚಿತಪಡಿಸುತ್ತವೆ. -**ಅವುಗಳನ್ನು ರನ್ ಮಾಡುವುದಕ್ಕಾಗಿ:** +**ನಡೆಸಲು:** **ಬ್ಯಾಶ್:** ```bash @@ -326,38 +318,38 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## ಪರೀಕ್ಷಾ ತತ್ತ್ವಶಾಸ್ತ್ರ -ನೀವು AI ಯನ್ನು ಪರೀಕ್ಷಿಸುವುದಲ್ಲ, ನಿಮ್ಮ ಕೋಡನ್ನು ಪರೀಕ್ಷಿಸಿ. ನಿಮ್ಮ ಪರೀಕ್ಷೆಗಳು ನೀವು ಬರೆದ ಕೋಡನ್ನು ಪರಿಶೀಲಿಸುವಂತೆ ರಚಿಸಬೇಕು, ಅಂದರೆ ಪ್ರಾಂಪ್ಟ್‌ಗಳು ಹೇಗೆ ನಿರ್ಮಿಸಲ್ಪಡುವುವು, ಸ್ಮೃತಿ ಹೇಗೆ ನಿರ್ವಹಿಸಲಾಗುವುದು ಮತ್ತು ಉಪಕರಣಗಳು ಹೇಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ ಎಂಬುದನ್ನು ಚೆಕ್ ಮಾಡಬೇಕು. AI ಪ್ರತಿಕ್ರಿಯೆಗಳು ಬೇರೆಬೇರೆ ಆಗಿರಬಹುದು, ಅವು ಪರೀಕ್ಷಾ ದೃಢೀಕರಣದ ಭಾಗವಾಗಬಾರದು. ನಿಮ್ಮ ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್ ಸರಿಯಾಗಿ ಬದಲಾವಣೆಗಳನ್ನು ಪರಿವರ್ತಿಸುತ್ತದೆಯೇ ಎಂದು ಪ್ರಶ್ನಿಸಿ, AI ಸರಿಯಾದ ಉತ್ತರ ಕೊಟ್ಟಿದೆಯೇ ಎಂದು ಅಲ್ಲ. +## ಪರೀಕ್ಷೆ ತತ್ವಶಾಸ್ತ್ರ + +ನೀವು ಎಐಯನ್ನು ಪರೀಕ್ಷಿಸುವುದಿಲ್ಲ; ನಿಮ್ಮ ಕೋಡ್ ಅನ್ನು ಪರೀಕ್ಷಿಸಿ. ನಿಮ್ಮ ಪರೀಕ್ಷೆಗಳು ನೀವು ಬರೆಯುವ ಕೋಡ್ ಅನ್ನು ಪರಿಶೀಲಿಸಬೆಕು: ಪ್ರಾಂಪ್ಟ್‌ಗಳು ಹೇಗೆ ರಚಿಸಲ್ಪಡುತ್ತವೆ, ಮೆಮೊರಿ ಹೇಗೆ ನಿರ್ವಹಿಸಲಾಗುತ್ತದೆ, ಮತ್ತು ಉಪಕರಣಗಳು ಹೇಗೆ ಕಾರ್ಯನಿರ್ವಹಿಸುತ್ತವೆ. ಎಐ ಪ್ರತಿಕ್ರಿಯೆಗಳು ಬದಲಾಗಬಹುದು ಮತ್ತು ಪರೀಕ್ಷಾ ಖಾತ್ರಿ ಭಾಗವಾಗಬಾರದು. ನಿಮ್ಮ ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್ ವ್ಯತ್ಯಯಗಳನ್ನು ಸರಿಯಾಗಿ ಬದಲಾಯಿಸುವುದೇ ಪ್ರಶ್ನಿಸಿರಿ, ಏನಿಲ್ಲ ಎಐ ಸರಿಯಾದ ಉತ್ತರವನ್ನು ಕೊಡುವುದೇ ಅಲ್ಲ. -ಭಾಷಾ ಮಾದರಿಗಳಿಗಾಗಿ ಮಾಕ್‌ಗಳನ್ನು ಬಳಸಿ. ಅವು ನಿಧಾನ, ದುಬಾರಿ ಮತ್ತು ನಿರ್ಧಾರಾತ್ಮಕವಲ್ಲದ ಹೊರಗಿನ ಅವಲಂಬನೆಗಳಾಗಿವೆ. ಮಾಕಿಂಗ್ ಪರೀಕ್ಷೆಗಳನ್ನು ಸೆಕೆಂಡ್‌ಗಳ ಬದಲಾಗಿ ಮಿಲಿಸೆಕೆಂಡ್‌ಗಳಲ್ಲಿ ವೇಗವಾಗಿ, API ಖರ್ಚಿಲ್ಲದೆ ಉಚಿತವಾಗಿ ಮತ್ತು ಯಾವಾಗಲೂ ಒಂದೇ ಫಲಿತಾಂಶ ನೀಡುವಂತೆ ನಿರ್ಧಾರಾತ್ಮಕವಾಗಿ ಮಾಡುತ್ತದೆ. +ಭಾಷಾ ಮಾದರಿಗಳಿಗೆ ಮಾಕ್‌ಗಳನ್ನು ಬಳಸಿ. ಅವು ಹೊರಗಿನ ಅವಲಂಬನೆಗಳು, ಯವು ನಿಧಾನ, ದುಬಾರಿಯಾಗಿವೆ ಮತ್ತು ನಿರ್ಣಾಯಕವಲ್ಲ. ಮಾಕ್ ಪರೀಕ್ಷೆಗಳನ್ನು ಸೆಕೆಂಡುಗಳ ಬದಲು ಮಿಲಿ ಸೆಕೆಂಡುಗಳಲ್ಲಿ ವೇಗವಾಗಿ, ಉಚಿತವಾಗಿ, ಮತ್ತು ನ್ಯಾಯಸಮ್ಮತವಾಗಿ ಮಾಡಿ. -ಪರೀಕ್ಷೆಗಳನ್ನು ಸ್ವತಂತ್ರವಾಗಿ ಇಡು. ಪ್ರತಿ ಪರೀಕ್ಷೆ ತನ್ನ ಸ್ವಂತ ಡೇಟಾವನ್ನು ಸಿದ್ದಪಡಿಸಬೇಕು, ಇತರ ಪರೀಕ್ಷೆಗಳ ಮೇಲೆ ಆಶ್ರಯವಿರುವುದಿಲ್ಲ, ಮತ್ತು ತನ್ನ ನಂತರ ಸ್ವಚ್ಛಗೊಳಿಸಬೇಕು. ಪರೀಕ್ಷೆಗಳು ಕಾರ್ಯಾಚರಣಾ ಕ್ರಮದ ಮೇಲೆ ಅವಲಂಬಿಸದಿರಲಿ. +ಪರೀಕ್ಷೆಗಳನ್ನು ಸ್ವತಂತ್ರವಾಗಿರಿಸಿ. ಪ್ರತಿ ಪರೀಕ್ಷೆ ತನ್ನದೇ ಆದ ಡೇಟಾವನ್ನು ಸಿದ್ಧಪಡಿಸಬೇಕು, ಇತರ ಪರೀಕ್ಷೆಗಳಿಗೆ ಅವಲಂಬಿಸಬಾರದು ಮತ್ತು ಸ್ವಚ್ಛಗೊಳಿಸುವುದು ಮಾಡಬೇಕು. ಪರೀಕ್ಷೆಗಳು ನಿರ್ಗತಿಗಳ ಕ್ರಮದಿಂದ ಪ್ರಭಾವಿತರಾಗಬಾರದು. -ಸುಖಪಥವನ್ನು ಮೀರಿ ಗಡಿ ಪ್ರಕರಣಗಳನ್ನು ಪರೀಕ್ಷಿಸಿ. ಖಾಲಿ ಒಳmondುಗಳು, ಬಹು ದೊಡ್ಡ ಒಳmondುಗಳು, ವಿಶೇಷ ಅಕ್ಷರಗಳು, ಅಮಾನ್ಯ ನಿಯಮಗಳು ಮತ್ತು ಅಳವಡಿಕೆ ವಿಮರ್ಶೆಗಳನ್ನು ಪ್ರಯತ್ನಿಸಿ. ಇವು ಸಾಮಾನ್ಯ ಬಳಕೆಯಲ್ಲಿ ಕಾಣಿಸದ ದೋಷಗಳನ್ನು ಬಹುಶಃ ಪತ್ತೆಹಚ್ಚುತ್ತವೆ. +ಸಂತುಷ್ಟಿಸುವ ಮಾರ್ಗದ ಹೊರಗಿನ ಪ್ರಾಂಬಲಗಳನ್ನು ಪರೀಕ್ಷಿಸಿ. ಖಾಲಿ ಇನ್‌ಪುಟ್‌ಗಳು, ಬಹು ದೊಡ್ಡ ಇನ್‌ಪುಟ್‌ಗಳು, ವಿಶೇಷ ಅಕ್ಷರಗಳು, ಅಮಾನ್ಯ ಪರಿಮಾಣಗಳು, ಮತ್ತು ಗಡಿದೊಡ್ಡ ನಿಯಮಗಳನ್ನು ಪ್ರಯತ್ನಿಸಿ. ಸಾಮಾನ್ಯ ಬಳಕೆಯಲ್ಲಿ ಮೂಡು ಕಾಣದ ದೋಷಗಳನ್ನು ಓದಲು ಇದು ಸಹಾಯ ಮಾಡುತ್ತದೆ. -ವಿವರಣಾತ್ಮಕ ಹೆಸರುಗಳನ್ನು ಬಳಸಿರಿ. ಉದಾಹರಣೆಗೆ `shouldMaintainConversationHistoryAcrossMultipleMessages()` ಅನ್ನು `test1()` ಜೊತೆ ಹೋಲಿಸಿ. ಮೊದಲದು ಯಾವುದು ಪರೀಕ್ಷೆಯಾಗಿದೆ ಎಂಬುದನ್ನು ಸರಿಯಾಗಿ ತಿಳಿಸುತ್ತದೆ, ದೋಷ ಪರಿಶೀಲನೆಯನ್ನು ತುಂಬಾ ಸುಲಭಗೊಳಿಸುತ್ತದೆ. +ವಿವರಣಾತ್ಮಕ ಹೆಸರುಗಳನ್ನು ಬಳಸಿ. `shouldMaintainConversationHistoryAcrossMultipleMessages()` ಮತ್ತು `test1()`ನ್ನು ಹೋಲಿಸಿ. ಮೊದಲದು ಪರಿಶೀಲನೆಯ ವಿಷಯವನ್ನು ನಿಖರವಾಗಿ ತಿಳಿಸುವ ಕಾರಣ ವೈಫಲ್ಯಗಳನ್ನು ಡಿಬಗ್ ಮಾಡುವುದು ಸುಲಭ. -## ಮುಂದಿನ ಹಂತಗಳು +## ಮುಂದಿನ ಹೆಜ್ಜೆಗಳು -ನೀವು ಈಗ ಪರೀಕ್ಷಾ ಉಲ್ಲೇಖಗಳನ್ನು ಅರ್ಥಮಾಡಿಕೊಂಡಿದ್ದೀರಿ, ಪ್ರತಿ ಮಂಟಪದಲ್ಲಿ ಕೆಲವು ಗಂಭೀರ ಅಧ್ಯಯನ ಮಾಡಿ: +ಈಗ ನೀವು ಪರೀಕ್ಷಾ ಮಾದರಿಗಳನ್ನು ಅರ್ಥಮಾಡಿಕೊಂಡಿದ್ದೀರಿ, ಪ್ರತಿ ಮೋಡುಲ್ ಆಳವಾಗಿ ವಿಶ್ಲೇಷಿಸಿ: -- **[00 - ತ್ವರಿತ ಪ್ರಾರಂಭ](../00-quick-start/README.md)** - ಪ್ರಾಂಪ್ಟ್ ಟೆಂಪ್ಲೇಟ್ ಮೂಲಭೂತಗಳು -- **[01 - ಪರಿಚಯ](../01-introduction/README.md)** - ಸಂವಾದ ಸ್ಮೃತಿ ನಿರ್ವಹಣೆ ಕಲಿತುಕೊಳ್ಳಿ -- **[02 - ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್](../02-prompt-engineering/README.md)** - GPT-5.2 ಪ್ರಾಂಪ್ಟ್ ಮಾದರಿಗಳನ್ನು ماهಿರ ಆಗಿ -- **[03 - RAG](../03-rag/README.md)** - ರಿಟ್ರೀವಲ್-ಆಗ್ಮೆಂಟೆಡ್ ಜೇನರೇಷನ್ ವ್ಯವಸ್ಥೆಗಳನ್ನು ನಿರ್ಮಿಸಿ -- **[04 - ಉಪಕರಣಗಳು](../04-tools/README.md)** - ಕಾರ್ಯ ಕರೆ ಮತ್ತು ಉಪಕರಣ ಸರಪಳಿಗಳನ್ನು ಜಾರಿಗೆ ತರುವುದು -- **[05 - MCP](../05-mcp/README.md)** - Model Context Protocol ಸಂಯೋಜಿಸಿ +- **[01 - ಪರಿಚಯ](../01-introduction/README.md)** - ಸಂಭಾಷಣೆ ಮೆಮೊರಿ ನಿರ್ವಹಣೆಯನ್ನು ಕಲಿಯಿರಿ +- **[02 - ಪ್ರಾಂಪ್ಟ್ ಎಂಜಿನಿಯರಿಂಗ್](../02-prompt-engineering/README.md)** - GPT-5.2 ಪ್ರಾಂಪ್ಟ್ ಮಾದರಿಗಳನ್ನು ಅಭ್ಯಾಸ ಮಾಡಿ +- **[03 - RAG](../03-rag/README.md)** - ರಿಟ್ರೀವಲ್-ಆಗ್ಮೆಂಟೆಡ್ ಜನರೇಶನ್ ವ್ಯವಸ್ಥೆಗಳನ್ನು ನಿರ್ಮಿಸಿ +- **[04 - ಉಪಕರಣಗಳು](../04-tools/README.md)** - ಫಂಕ್ಷನ್ ಕರೆಮಾಡುವಿಕೆ ಮತ್ತು ಉಪಕರಣ ಸರಪಳಿಗಳನ್ನು ಅನುಷ್ಟಿಸಲು +- **[05 - MCP](../05-mcp/README.md)** - Model Context Protocol ಏಕೀಕರಿಸಿ -ಪ್ರತಿ ಮಂಟಪದ README ಇಲ್ಲಿ ಪರೀಕ್ಷಿಸಲಾದ ತತ್ವಗಳ ವಿವರವಾದ ವಿವರಣೆಗಳನ್ನು ನೀಡುತ್ತದೆ. +ಪ್ರತಿಯೊಂದು ಮೋಡುಲ್‌ನ README ಇಲ್ಲಿ ಪರೀಕ್ಷಿಸಲಾದ ಕಲ್ಪನೆಗಳ ವಿವರಗಳನ್ನು ನೀಡುತ್ತದೆ. --- -**Navigation:** [← ಹಿಂದುಮುಖ ಮಾಡಿ ಮುಖ್ಯ ಪುಟへ](../README.md) +**ನಾವಿಗೇಷನ್:** [← ಮುಖ್ಯಕ್ಕೆ ಹಿಂತಿರುಗಿ](../README.md) --- -**ಅಮರ್ಪಣೆ**: -ಈ ದಾಖಲೆ AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವದಿಸಲಾಗಿದೆ. ನಾವು ಶುದ್ಧತೆಯಿಗಾಗಿ ಪ್ರಯತ್ನಿಸಿದರೂ, ಸ್ವಯಂಕ್ರಿಯ ಅನುವಾದದಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ಅಸತ್ಯತೆಗಳಿರಬಹುದೆಂದು ದಯವಿಟ್ಟು ಗಮನಿಸಿ. ಮೂಲ ದಸ್ತಾವೇಜು ಅದರ ಸ್ವದೇಶಿ ಭಾಷೆಯಲ್ಲಿ ಪ್ರಾಧಿಕೃತ ಮೂಲವಾಗಿಯೇ ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದ ಬಳಕೆಯಿಂದ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪುದೊಡ್ಡಿಕೆಗಳು ಅಥವಾ ತಪ್ಪು ಅರ್ಥಗಳಿಂದ ನಾವು ಜವಾಬ್ದಾರರಾಗುವುದಿಲ್ಲ. +**ಅಸ್ವೀಕಾರ**: +ಈ ದಸ್ತಾವೇಜು AI ಅನುವಾದ ಸೇವೆ [Co-op Translator](https://github.com/Azure/co-op-translator) ಬಳಸಿ ಅನುವಾದಿಸಲಾಗಿದೆ. ನಾವು ನಿಖರತೆಯನ್ನು ಸಾಧಿಸಲು ಪ್ರಯತ್ನಿಸುತ್ತಿದ್ದರೂ, ದಯವಿಟ್ಟು ಗಮನಿಸಿ, ಸ್ವಯಂಚಾಲಿತ ಅನುವಾದಗಳಲ್ಲಿ ದೋಷಗಳು ಅಥವಾ ಅಸಡ್ಡೆಗಳು ಇರಬಹುದು. ಮೂಲ ಭಾಷೆಯಲ್ಲಿರುವ ಮೂಲ ದಸ್ತಾವೇಜು ಪ್ರಾಮಾಣಿಕ ಮೂಲವೆಂದು ಪರಿಗಣಿಸಬೇಕು. ಪ್ರಮುಖ ಮಾಹಿತಿಗಾಗಿ, ವೃತ್ತಿಪರ ಮಾನವ ಅನುವಾದವನ್ನು ಶಿಫಾರಸು ಮಾಡಲಾಗುತ್ತದೆ. ಈ ಅನುವಾದವನ್ನು ಬಳಸುವ ಮೂಲಕ ಉಂಟಾಗುವ ಯಾವುದೇ ತಪ್ಪು ಅರ್ಥಗಳ ಅಥವಾ ತಪ್ಪು ವ್ಯಾಖ್ಯಾನಗಳ ಬಗ್ಗೆ ನಾವು ಹೊಣೆಗಾರರಲ್ಲ. \ No newline at end of file diff --git a/translations/ko/.co-op-translator.json b/translations/ko/.co-op-translator.json index bf277e0aa..26f5e9f81 100644 --- a/translations/ko/.co-op-translator.json +++ b/translations/ko/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ko" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T23:02:30+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T07:47:21+00:00", "source_file": "01-introduction/README.md", "language_code": "ko" }, @@ -18,20 +18,20 @@ "language_code": "ko" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T23:04:26+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T07:42:38+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ko" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T23:05:35+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T07:46:26+00:00", "source_file": "03-rag/README.md", "language_code": "ko" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:58:10+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T07:45:08+00:00", "source_file": "04-tools/README.md", "language_code": "ko" }, @@ -54,8 +54,8 @@ "language_code": "ko" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:43:25+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T07:41:01+00:00", "source_file": "README.md", "language_code": "ko" }, @@ -72,14 +72,14 @@ "language_code": "ko" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T23:08:10+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T07:43:11+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ko" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T23:08:49+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T07:43:49+00:00", "source_file": "docs/TESTING.md", "language_code": "ko" } diff --git a/translations/ko/00-quick-start/README.md b/translations/ko/00-quick-start/README.md deleted file mode 100644 index 824ddacf0..000000000 --- a/translations/ko/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: 빠른 시작 - -## 목차 - -- [소개](../../../00-quick-start) -- [LangChain4j란?](../../../00-quick-start) -- [LangChain4j 의존성](../../../00-quick-start) -- [사전 요구 사항](../../../00-quick-start) -- [설정](../../../00-quick-start) - - [1. GitHub 토큰 받기](../../../00-quick-start) - - [2. 토큰 설정하기](../../../00-quick-start) -- [예제 실행하기](../../../00-quick-start) - - [1. 기본 채팅](../../../00-quick-start) - - [2. 프롬프트 패턴](../../../00-quick-start) - - [3. 함수 호출](../../../00-quick-start) - - [4. 문서 Q&A (Easy RAG)](../../../00-quick-start) - - [5. 책임 있는 AI](../../../00-quick-start) -- [각 예제가 보여주는 것](../../../00-quick-start) -- [다음 단계](../../../00-quick-start) -- [문제 해결](../../../00-quick-start) - -## 소개 - -이 빠른 시작 가이드는 LangChain4j를 최대한 빠르게 시작할 수 있도록 설계되었습니다. LangChain4j와 GitHub 모델을 사용하여 AI 애플리케이션을 구축하는 기본을 다룹니다. 다음 모듈에서는 Azure OpenAI와 GPT-5.2로 전환하여 각 개념을 더 깊이 탐구합니다. - -## LangChain4j란? - -LangChain4j는 AI 기반 애플리케이션 구축을 단순화하는 자바 라이브러리입니다. HTTP 클라이언트와 JSON 파싱을 다루는 대신, 깔끔한 자바 API로 작업할 수 있습니다. - -LangChain의 "체인"이란 여러 구성 요소를 연결하는 것을 의미합니다 - 프롬프트를 모델에 연결하고 파서와 연결하거나 여러 AI 호출을 연결하여 한 출력이 다음 입력이 되는 식입니다. 이 빠른 시작에서는 더 복잡한 체인을 탐구하기 전 기본에 집중합니다. - -LangChain4j Chaining Concept - -*LangChain4j에서 구성 요소를 체인으로 연결 - 강력한 AI 워크플로를 만드는 빌딩 블록* - -세 가지 핵심 구성 요소를 사용합니다: - -**ChatModel** - AI 모델 상호작용을 위한 인터페이스입니다. `model.chat("prompt")`를 호출하여 응답 문자열을 받습니다. 우리는 OpenAI 호환 엔드포인트(예: GitHub 모델)와 작동하는 `OpenAiOfficialChatModel`을 사용합니다. - -**AiServices** - 타입 안정 AI 서비스 인터페이스를 생성합니다. 메서드를 정의하고 `@Tool`로 주석 처리하면 LangChain4j가 오케스트레이션을 처리합니다. AI가 필요할 때 자동으로 자바 메서드를 호출합니다. - -**MessageWindowChatMemory** - 대화 기록을 유지합니다. 이 기능 없이는 각 요청이 독립적입니다. 이 기능이 있으면 AI가 이전 메시지를 기억하여 여러 턴에 걸쳐 컨텍스트를 유지합니다. - -LangChain4j Architecture - -*LangChain4j 아키텍처 - 핵심 구성 요소가 함께 작동하여 AI 애플리케이션을 구동* - -## LangChain4j 의존성 - -이 빠른 시작은 [`pom.xml`](../../../00-quick-start/pom.xml) 내의 세 가지 Maven 의존성을 사용합니다: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` 모듈은 OpenAI 호환 API에 연결하는 `OpenAiOfficialChatModel` 클래스를 제공합니다. GitHub 모델은 동일한 API 형식을 사용하므로 특별한 어댑터가 필요 없으며, 기본 URL을 `https://models.github.ai/inference`로 지정하면 됩니다. - -`langchain4j-easy-rag` 모듈은 자동 문서 분할, 임베딩, 검색 기능을 제공하여 각 단계를 수동으로 구성하지 않고 RAG 애플리케이션을 구축할 수 있게 합니다. - -## 사전 요구 사항 - -**Dev Container를 사용 중이신가요?** Java와 Maven이 이미 설치되어 있습니다. 오직 GitHub 개인 액세스 토큰만 필요합니다. - -**로컬 개발 환경:** -- Java 21 이상, Maven 3.9 이상 -- GitHub 개인 액세스 토큰 (아래 지침 참조) - -> **참고:** 이 모듈은 GitHub 모델의 `gpt-4.1-nano` 모델을 사용합니다. 코드 내 모델 이름을 변경하지 마십시오 - GitHub에서 제공하는 모델에 맞게 구성되어 있습니다. - -## 설정 - -### 1. GitHub 토큰 받기 - -1. [GitHub 설정 → 개인 액세스 토큰](https://github.com/settings/personal-access-tokens)으로 이동 -2. "새 토큰 생성" 클릭 -3. 설명 이름 설정 (예: "LangChain4j 데모") -4. 만료 기간 설정 (7일 권장) -5. "계정 권한"에서 "Models"를 "읽기 전용"으로 설정 -6. "토큰 생성" 클릭 -7. 토큰을 복사하여 저장 (다시 볼 수 없습니다) - -### 2. 토큰 설정하기 - -**옵션 1: VS Code 사용(권장)** - -VS Code를 사용하는 경우 프로젝트 루트의 `.env` 파일에 토큰을 추가합니다: - -`.env` 파일이 없으면 `.env.example`을 복사해 `.env`로 만들거나 새로운 `.env` 파일을 프로젝트 루트에 생성하세요. - -**예시 `.env` 파일:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env 에서 -GITHUB_TOKEN=your_token_here -``` - -이후 탐색기에서 데모 파일(예: `BasicChatDemo.java`)을 우클릭하고 **"Run Java"**를 선택하거나, 실행 및 디버그 패널의 실행 구성을 사용할 수 있습니다. - -**옵션 2: 터미널 사용** - -환경 변수로 토큰을 설정합니다: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## 예제 실행하기 - -**VS Code 사용 시:** 탐색기에서 데모 파일을 우클릭하고 **"Run Java"** 선택하거나 실행 및 디버그 패널의 실행 구성을 사용하세요 (먼저 `.env` 파일에 토큰을 추가해야 합니다). - -**Maven 사용 시:** 명령줄에서 다음과 같이 실행할 수 있습니다: - -### 1. 기본 채팅 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. 프롬프트 패턴 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -제로샷, 퓨샷, 사고의 사슬, 역할 기반 프롬프팅을 보여줍니다. - -### 3. 함수 호출 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI가 필요할 때 자동으로 자바 메서드를 호출합니다. - -### 4. 문서 Q&A (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -자동 임베딩 및 검색이 포함된 Easy RAG로 문서에 대한 질문을 할 수 있습니다. - -### 5. 책임 있는 AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -AI 안전 필터가 유해한 콘텐츠를 차단하는 방식을 확인할 수 있습니다. - -## 각 예제가 보여주는 것 - -**기본 채팅** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -LangChain4j의 가장 기본적인 모습을 여기서 확인하세요. `OpenAiOfficialChatModel`을 생성하고 `.chat()`으로 프롬프트를 보내며 응답을 받습니다. 이 기본 패턴을 이해하면 나머지 내용은 이 위에 구축됩니다. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) 채팅으로 시도해 보기:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java)를 열고 묻기: -> - "이 코드에서 GitHub 모델에서 Azure OpenAI로 어떻게 전환하나요?" -> - "OpenAiOfficialChatModel.builder()에서 다른 설정 가능한 매개변수는 무엇인가요?" -> - "완전한 응답을 기다리는 대신 스트리밍 응답을 어떻게 추가하나요?" - -**프롬프트 엔지니어링** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -모델과 대화하는 방법을 알았다면, 이제 무엇을 말할지 살펴봅니다. 이 데모는 동일한 모델 설정을 사용하지만 다섯 가지 다른 프롬프트 패턴을 보여줍니다. 직접 지시하는 제로샷, 예제로 학습하는 퓨샷, 추론 단계를 나타내는 사고의 사슬, 문맥을 설정하는 역할 기반 프롬프트를 시도해 보세요. 동일 모델이 어떻게 요청 방식에 따라 크게 다른 결과를 내는지 확인할 수 있습니다. - -프롬프트 템플릿도 시연하는데, 변수로 재사용 가능한 프롬프트를 만드는 강력한 방법입니다. -아래 예시는 LangChain4j `PromptTemplate`을 사용해 변수를 채운 프롬프트로, AI가 제공된 목적지와 활동에 따라 답변합니다. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) 채팅으로 시도해 보기:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java)를 열고 묻기: -> - "제로샷과 퓨샷 프롬프팅의 차이점은 무엇이며 각각 언제 사용해야 하나요?" -> - "온도 파라미터가 모델 응답에 어떻게 영향을 주나요?" -> - "프로덕션에서 프롬프트 인젝션 공격을 방지하는 기술은 무엇이 있나요?" -> - "일반 패턴에 대해 재사용 가능한 PromptTemplate 객체를 어떻게 만들 수 있나요?" - -**도구 통합** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -LangChain4j의 강력한 기능을 경험할 부분입니다. `AiServices`를 사용해 자바 메서드를 호출할 수 있는 AI 비서을 만듭니다. 메서드에 `@Tool("설명")`로 주석만 달면 LangChain4j가 나머지를 처리하여 AI가 사용자 요청에 따라 도구를 자동으로 선택해 호출합니다. 액션을 수행하는 AI 구축에 핵심적인 함수 호출 기능을 보여줍니다. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) 채팅으로 시도해 보기:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java)를 열고 묻기: -> - "@Tool 주석은 어떻게 작동하며 LangChain4j가 뒤에서 무엇을 하나요?" -> - "AI가 복잡한 문제를 풀기 위해 여러 도구를 순차적으로 호출할 수 있나요?" -> - "도구가 예외를 발생시키면 어떻게 오류를 처리해야 하나요?" -> - "이 계산기 예제 대신 실제 API를 통합하려면 어떻게 하나요?" - -**문서 Q&A (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -LangChain4j의 "Easy RAG" 접근법을 통한 RAG (검색 증강 생성)를 보게 됩니다. 문서가 로드되어 자동으로 분할 및 임베딩되어 인메모리 저장소에 저장되고, 컨텐츠 검색기가 쿼리 시점에 관련 청크를 AI에 제공합니다. AI는 일반 지식이 아니라 문서 기준으로 답변합니다. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) 채팅으로 시도해 보기:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)를 열고 묻기: -> - "모델 훈련 데이터 사용과 비교해 RAG가 AI 허위정보(hallucination)를 어떻게 방지하나요?" -> - "이 쉬운 접근법과 커스텀 RAG 파이프라인의 차이점은 무엇인가요?" -> - "여러 문서나 더 큰 지식 기반을 처리하도록 확장하려면 어떻게 해야 하나요?" - -**책임 있는 AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -다층 방어로 AI 안전을 구축합니다. 이 데모에서는 두 가지 보호 계층이 함께 작동하는 방식을 보여줍니다: - -**1부: LangChain4j 입력 가드레일** - 위험한 프롬프트가 LLM에 도달하기 전에 차단합니다. 금지된 키워드나 패턴을 검사하는 커스텀 가드레일을 만들 수 있습니다. 코드 내에서 실행되어 빠르고 무료입니다. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**2부: 제공자 안전 필터** - GitHub 모델은 가드레일이 놓칠 수 있는 부분을 포착하는 내장 필터를 갖고 있습니다. 심각한 위반에 대해 강력 차단(HTTP 400 오류)과 AI가 정중히 거절하는 완화 차단을 볼 수 있습니다. - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) 채팅으로 시도해 보기:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java)를 열고 묻기: -> - "InputGuardrail이란 무엇이며, 직접 만드는 방법은?" -> - "강력 차단과 완화 거절의 차이점은 무엇인가요?" -> - "왜 가드레일과 제공자 필터를 함께 사용하나요?" - -## 다음 단계 - -**다음 모듈:** [01-introduction - LangChain4j 시작하기](../01-introduction/README.md) - ---- - -**탐색:** [← 메인으로 돌아가기](../README.md) | [다음: Module 01 - 소개 →](../01-introduction/README.md) - ---- - -## 문제 해결 - -### 처음 Maven 빌드 시 - -**문제:** 초기 `mvn clean compile` 또는 `mvn package` 실행 시 오래 걸림 (10-15분) - -**원인:** Maven이 첫 빌드 시 프로젝트 의존성(스프링 부트, LangChain4j 라이브러리, Azure SDK 등)을 모두 다운로드해야 함 - -**해결:** 정상적인 동작입니다. 이후 빌드는 의존성 캐시로 인해 훨씬 빠릅니다. 다운로드 속도는 네트워크 상태에 따라 다릅니다. - -### PowerShell Maven 명령 구문 오류 - -**문제:** Maven 명령 실행 시 `Unknown lifecycle phase ".mainClass=..."` 오류 발생 -**원인**: PowerShell이 `=` 를 변수 할당 연산자로 해석하여 Maven 속성 구문을 깨뜨림 - -**해결책**: Maven 명령어 앞에 stop-parsing 연산자 `--%` 를 사용하십시오: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` 연산자는 PowerShell에 나머지 인수를 해석 없이 Maven에 문자 그대로 전달하도록 지시합니다. - -### Windows PowerShell 이모지 표시 - -**문제**: PowerShell에서 AI 응답이 이모지 대신 쓰레기 문자(예: `????` 또는 `â??`)로 표시됨 - -**원인**: PowerShell 기본 인코딩이 UTF-8 이모지를 지원하지 않음 - -**해결책**: 자바 애플리케이션 실행 전에 다음 명령을 실행하십시오: -```cmd -chcp 65001 -``` - -이 명령은 터미널에서 UTF-8 인코딩을 강제 적용합니다. 또는 유니코드 지원이 더 좋은 Windows Terminal을 사용하십시오. - -### API 호출 디버깅 - -**문제**: 인증 오류, 속도 제한 또는 AI 모델에서 예상치 못한 응답 발생 - -**해결책**: 예제에는 API 호출을 콘솔에 표시하기 위해 `.logRequests(true)` 와 `.logResponses(true)` 가 포함되어 있습니다. 이는 인증 오류, 속도 제한 또는 예상치 못한 응답 문제를 해결하는 데 도움이 됩니다. 프로덕션에서는 로그 소음을 줄이기 위해 이 플래그들을 제거하십시오. - ---- - - -**면책 조항**: -이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 노력하고 있으나 자동 번역에는 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원본 문서의 원어 버전을 권위 있는 자료로 간주해야 합니다. 중요한 정보의 경우 전문적인 인간 번역을 권장합니다. 이 번역의 사용으로 발생하는 오해나 잘못된 해석에 대해서는 당사가 책임지지 않습니다. - \ No newline at end of file diff --git a/translations/ko/01-introduction/README.md b/translations/ko/01-introduction/README.md index 6770e4455..0a2d893d4 100644 --- a/translations/ko/01-introduction/README.md +++ b/translations/ko/01-introduction/README.md @@ -2,19 +2,19 @@ ## 목차 -- [비디오 안내](../../../01-introduction) -- [학습 내용](../../../01-introduction) -- [전제 조건](../../../01-introduction) -- [핵심 문제 이해하기](../../../01-introduction) -- [토큰 이해하기](../../../01-introduction) -- [메모리 작동 방식](../../../01-introduction) -- [LangChain4j 활용 방법](../../../01-introduction) -- [Azure OpenAI 인프라 배포](../../../01-introduction) -- [로컬에서 애플리케이션 실행하기](../../../01-introduction) -- [애플리케이션 사용법](../../../01-introduction) - - [상태 없는 채팅 (왼쪽 패널)](../../../01-introduction) - - [상태 있는 채팅 (오른쪽 패널)](../../../01-introduction) -- [다음 단계](../../../01-introduction) +- [비디오 안내](#비디오-안내) +- [학습 내용](#학습-내용) +- [필수 조건](#필수-조건) +- [핵심 문제 이해하기](#핵심-문제-이해하기) +- [토큰 이해하기](#토큰-이해하기) +- [메모리 작동 원리](#메모리-작동-원리) +- [LangChain4j 사용 방법](#langchain4j-사용-방법) +- [Azure OpenAI 인프라 배포하기](#azure-openai-인프라-배포하기) +- [애플리케이션 로컬 실행하기](#애플리케이션-로컬-실행하기) +- [애플리케이션 사용법](#애플리케이션-사용법) + - [상태 비저장 대화 (왼쪽 패널)](#상태-비저장-대화-왼쪽-패널) + - [상태 저장 대화 (오른쪽 패널)](#상태-저장-대화-오른쪽-패널) +- [다음 단계](#다음-단계) ## 비디오 안내 @@ -24,64 +24,64 @@ ## 학습 내용 -빠른 시작에서 GitHub 모델을 사용해 프롬프트를 보내고, 도구를 호출하며, RAG 파이프라인을 빌드하고, 가드레일을 테스트했습니다. 그 데모들은 가능한 기능을 보여주었고—이제 Azure OpenAI와 GPT-5.2로 전환하며 실제 생산용 애플리케이션을 구축하기 시작합니다. 이 모듈은 대화형 AI에 초점을 맞추며, 컨텍스트를 기억하고 상태를 유지하는 개념에 대해 다룹니다—빠른 시작 데모에서 암묵적으로 사용되었으나 자세히 설명하지 않은 개념입니다. +이것은 LangChain4j와 Azure OpenAI의 출발점입니다. 기본부터 시작하여 프로덕션 스타일 애플리케이션을 구축합니다. 이 모듈은 컨텍스트를 기억하고 상태를 유지하는 대화형 AI에 집중하며, 이후 모든 모듈의 기초가 되는 개념입니다. -이 가이드 전체에서 Azure OpenAI의 GPT-5.2를 사용할 것입니다. GPT-5.2의 고급 추론 기능 덕분에 다양한 패턴의 동작이 더 명확하게 드러납니다. 메모리를 추가하면 차이를 뚜렷하게 확인할 수 있습니다. 이는 각 구성 요소가 애플리케이션에 기여하는 바를 이해하는 데 도움이 됩니다. +이 가이드 전체에서 Azure OpenAI의 GPT-5.2를 사용할 것입니다. 이 모델은 고급 추론 능력이 있어 다양한 패턴의 동작 차이가 더 명확하게 드러납니다. 메모리를 추가하면 차이를 분명히 알 수 있습니다. 따라서 각 구성 요소가 애플리케이션에 어떤 기여를 하는지 이해하기 쉽습니다. -두 가지 패턴을 보여주는 하나의 애플리케이션을 구축할 것입니다: +두 가지 패턴을 모두 보여주는 하나의 애플리케이션을 만들 것입니다: -**상태 없는 채팅** - 각 요청이 독립적입니다. 모델은 이전 메시지를 기억하지 않습니다. 이것이 빠른 시작에서 사용한 패턴입니다. +**상태 비저장 대화** - 각 요청이 독립적입니다. 모델은 이전 메시지를 기억하지 않습니다. 가장 단순한 시작점입니다. -**상태 있는 대화** - 각 요청에 대화 기록이 포함됩니다. 모델이 여러 턴에 걸쳐 컨텍스트를 유지합니다. 생산용 애플리케이션에 필요한 방식입니다. +**상태 저장 대화** - 각 요청에 대화 기록이 포함됩니다. 모델이 다중 턴 동안 컨텍스트를 유지합니다. 프로덕션 애플리케이션에 필요한 방식입니다. -## 전제 조건 +## 필수 조건 -- Azure OpenAI 접근 권한이 있는 Azure 구독 +- Azure 구독 및 Azure OpenAI 접근 권한 - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **참고:** Java, Maven, Azure CLI 및 Azure Developer CLI(azd)는 제공된 devcontainer에 사전 설치되어 있습니다. +> **참고:** 제공된 개발 컨테이너에는 Java, Maven, Azure CLI 및 Azure Developer CLI(azd)가 미리 설치되어 있습니다. -> **참고:** 이 모듈은 Azure OpenAI에서 GPT-5.2를 사용합니다. 배포는 `azd up`으로 자동 구성되므로 코드 내 모델 이름을 수정하지 마십시오. +> **참고:** 이 모듈은 Azure OpenAI에서 GPT-5.2를 사용합니다. 배포는 `azd up` 명령으로 자동 구성되므로 코드 내 모델 이름을 변경하지 마세요. ## 핵심 문제 이해하기 -언어 모델은 상태를 유지하지 않습니다. 각 API 호출은 독립적입니다. "내 이름은 존이야"라는 메시지를 보내고 나서 "내 이름이 뭐야?"라고 물어도, 모델은 자신이 방금 자신을 소개했음을 알지 못합니다. 모든 요청을 처음 하는 대화인 것처럼 처리합니다. +언어 모델은 상태 비저장입니다. 각 API 호출은 독립적입니다. 예를 들어 "내 이름은 John입니다"라고 입력한 후 "내 이름이 뭐지?"라고 물으면, 모델은 방금 자신을 소개한 것을 알지 못합니다. 매 요청을 처음 대화라고 간주합니다. -이것은 단순한 Q&A에는 괜찮지만 실제 애플리케이션에는 무용지물입니다. 고객 서비스 봇은 사용자가 무엇을 말했는지 기억해야 하고, 개인 비서도 컨텍스트가 필요합니다. 다중 턴 대화에는 메모리가 필요합니다. +간단한 Q&A에는 괜찮지만 실제 애플리케이션에는 무용지물입니다. 고객 지원 봇은 당신이 말한 것을 기억해야 하고, 개인 비서는 컨텍스트가 필요합니다. 다중 턴 대화는 메모리가 필요합니다. -다음 다이어그램은 두 접근 방식을 대비합니다 — 왼쪽은 이름을 잊는 상태 없는 호출, 오른쪽은 이름을 기억하는 ChatMemory 기반 상태 있는 호출입니다. +다음 다이어그램은 두 가지 접근법을 대비합니다 — 왼쪽은 이름을 잊어버리는 상태 비저장 호출, 오른쪽은 ChatMemory가 백업하여 기억하는 상태 저장 호출입니다. Stateless vs Stateful Conversations -*상태 없는(독립 호출) 대화와 상태 있는(컨텍스트 인식) 대화의 차이* +*상태 비저장(독립 호출)과 상태 저장(컨텍스트 인지) 대화의 차이* ## 토큰 이해하기 -대화로 들어가기 전에, 토큰—언어 모델이 처리하는 텍스트의 기본 단위—을 이해하는 것이 중요합니다: +대화에 들어가기 전에 토큰을 이해하는 것이 중요합니다 - 언어 모델이 처리하는 텍스트의 기본 단위입니다: Token Explanation -*텍스트가 어떻게 토큰으로 나뉘는지 예시—"I love AI!"가 4개의 별도 처리 단위가 됨* +*텍스트가 토큰으로 분리되는 예 - "I love AI!"는 4개의 별도 처리 단위로 나뉩니다* -토큰은 AI 모델이 텍스트를 측정하고 처리하는 방법입니다. 단어, 구두점, 심지어 공백도 토큰이 될 수 있습니다. 모델은 한 번에 처리할 수 있는 토큰 수에 제한이 있습니다(GPT-5.2는 최대 400,000 토큰, 입력 토큰 최대 272,000, 출력 토큰 최대 128,000). 토큰을 이해하면 대화 길이와 비용 관리를 쉽게 할 수 있습니다. +토큰은 AI 모델이 텍스트를 측정하고 처리하는 방법입니다. 단어, 구두점, 심지어 공백도 토큰이 될 수 있습니다. 모델마다 한 번에 처리 가능한 토큰 수 제한이 있습니다(GPT-5.2는 최대 400,000 토큰, 입력 272,000 토큰 및 출력 128,000 토큰). 토큰 이해는 대화 길이와 비용 관리에 도움이 됩니다. -## 메모리 작동 방식 +## 메모리 작동 원리 -챗 메모리는 상태 없음을 해결하기 위해 대화 기록을 유지합니다. 당신의 요청을 모델에 보내기 전에, 프레임워크가 관련 이전 메시지를 앞에 덧붙입니다. "내 이름이 뭐야?"라고 물으면, 시스템은 실제로 전체 대화 기록을 전송해 모델이 이전에 "내 이름은 존이야"라고 말한 것을 볼 수 있게 합니다. +채팅 메모리는 상태 비저장 문제를 대화 기록을 유지함으로써 해결합니다. 모델에 요청을 보내기 전에 프레임워크가 관련 이전 메시지를 앞에 붙입니다. "내 이름이 뭐지?"라고 물을 때 시스템은 실제로 전체 대화 기록을 보내 모델이 "내 이름은 John입니다"라고 이전에 말한 것을 알 수 있게 합니다. -LangChain4j는 이 작업을 자동으로 처리하는 메모리 구현체를 제공합니다. 보관할 메시지 수를 선택하면 프레임워크가 컨텍스트 윈도우를 관리합니다. 아래 다이어그램은 MessageWindowChatMemory가 최근 메시지의 슬라이딩 윈도우를 어떻게 유지하는지 보여줍니다. +LangChain4j는 이를 자동으로 처리하는 메모리 구현체를 제공합니다. 유지할 메시지 수를 선택하면 프레임워크가 컨텍스트 창을 관리합니다. 아래 다이어그램은 MessageWindowChatMemory가 최근 메시지의 슬라이딩 윈도우를 유지하는 방식을 보여줍니다. Memory Window Concept -*MessageWindowChatMemory는 최근 메시지의 슬라이딩 윈도우를 유지하며 오래된 메시지는 자동으로 버림* +*MessageWindowChatMemory는 최근 메시지의 슬라이딩 윈도우를 유지하며 오래된 메시지는 자동으로 삭제* -## LangChain4j 활용 방법 +## LangChain4j 사용 방법 -이 모듈은 빠른 시작을 확장하여 Spring Boot를 통합하고 대화 메모리를 추가합니다. 구성 요소들의 연결 방식은 다음과 같습니다: +이 모듈은 Spring Boot와 통합되어 대화 메모리를 추가합니다. 구성요소는 다음과 같이 연결됩니다: -**종속성** - 두 개의 LangChain4j 라이브러리를 추가: +종속성 - 두 개의 LangChain4j 라이브러리를 추가: ```xml @@ -93,8 +93,8 @@ LangChain4j는 이 작업을 자동으로 처리하는 메모리 구현체를 langchain4j-open-ai-official ``` - -**챗 모델** - Azure OpenAI를 Spring 빈으로 설정 ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): + +**채팅 모델** - Azure OpenAI를 Spring 빈으로 구성 ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -108,10 +108,10 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { .build(); } ``` - -빌더는 `azd up`으로 설정된 환경 변수에서 자격 증명을 읽습니다. `baseUrl`을 Azure 엔드포인트로 설정하면 OpenAI 클라이언트가 Azure OpenAI와 작동합니다. -**대화 메모리** - MessageWindowChatMemory로 채팅 기록 추적 ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +빌더는 `azd up`로 설정된 환경 변수에서 자격 증명을 읽습니다. `baseUrl`을 Azure 엔드포인트로 설정하면 OpenAI 클라이언트가 Azure OpenAI와 연결됩니다. + +**대화 메모리** - MessageWindowChatMemory로 대화 기록 추적 ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -123,116 +123,115 @@ memory.add(UserMessage.from("What's my name?")); AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` - -`withMaxMessages(10)`로 메모리를 생성해 마지막 10개 메시지를 보관합니다. 사용자 및 AI 메시지는 각각 `UserMessage.from(text)`와 `AiMessage.from(text)`로 타입 래퍼를 사용해 추가합니다. `memory.messages()`로 기록을 가져와 모델에 보냅니다. 서비스는 대화 ID별로 별도의 메모리 인스턴스를 저장해 여러 사용자가 동시에 채팅할 수 있습니다. -> **🤖 GitHub Copilot Chat으로 시도해 보세요:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)를 열고 다음을 질문하세요: -> - "MessageWindowChatMemory가 윈도우가 가득 찼을 때 어떤 메시지를 버리는지 어떻게 결정하나요?" -> - "메모리를 인메모리 대신 데이터베이스를 이용해 저장하도록 커스텀 구현할 수 있나요?" -> - "과거 대화 기록을 압축하는 요약 기능을 어떻게 추가할 수 있나요?" +`withMaxMessages(10)`로 마지막 10개의 메시지를 유지하는 메모리를 생성합니다. 사용자 메시지와 AI 메시지는 각각 `UserMessage.from(text)`와 `AiMessage.from(text)`로 래핑합니다. `memory.messages()`로 기록을 조회해 모델에 보냅니다. 서비스는 각 대화 ID별로 별도의 메모리 인스턴스를 저장해 여러 사용자가 동시에 대화할 수 있도록 합니다. + +> **🤖 GitHub Copilot 채팅으로 시도해보세요:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)를 열고 물어보세요: +> - "MessageWindowChatMemory가 윈도우가 가득 찼을 때 어떤 메시지를 삭제할지 어떻게 결정하나요?" +> - "메모리를 메모리 대신 데이터베이스를 사용해 커스텀으로 구현할 수 있나요?" +> - "오래된 대화 기록을 압축하기 위한 요약 기능을 어떻게 추가할 수 있나요?" -상태 없는 채팅 엔드포인트는 메모리를 완전히 건너뛰고 빠른 시작과 같이 `chatModel.chat(prompt)`만 호출합니다. 상태 있는 엔드포인트는 메시지를 메모리에 추가하고 기록을 불러와 요청마다 컨텍스트를 포함합니다. 같은 모델 설정, 다른 패턴입니다. +상태 비저장 채팅 엔드포인트는 메모리를 전혀 사용하지 않고 `chatModel.chat(prompt)`를 호출합니다. 상태 저장 엔드포인트는 메시지를 메모리에 추가하고 기록을 불러와 각 요청에 컨텍스트로 포함합니다. 동일한 모델 구성, 다른 패턴입니다. -## Azure OpenAI 인프라 배포 +## Azure OpenAI 인프라 배포하기 **Bash:** ```bash cd 01-introduction azd up # 구독 및 위치 선택 (eastus2 권장) ``` - + **PowerShell:** ```powershell cd 01-introduction -azd up # 구독 및 위치 선택(동부 미국 2 추천) +azd up # 구독 및 위치 선택 (eastus2 권장) ``` - -> **참고:** 타임아웃 오류(`RequestConflict: Cannot modify resource ... provisioning state is not terminal`)가 발생하면 단순히 `azd up`을 다시 실행하세요. Azure 리소스가 여전히 프로비저닝 중일 수 있으며, 재시도하면 리소스가 정상 상태에 도달할 때까지 배포가 완료됩니다. -이 작업은 다음을 수행합니다: -1. GPT-5.2 및 text-embedding-3-small 모델이 포함된 Azure OpenAI 리소스 배포 -2. 프로젝트 루트에 자격 증명 `.env` 파일 자동 생성 -3. 필요 환경 변수 모두 설정 +> **참고:** 만약 `RequestConflict: Cannot modify resource ... provisioning state is not terminal`과 같은 타임아웃 오류가 발생하면, 단순히 `azd up`를 다시 실행하세요. Azure 리소스가 아직 프로비저닝 중일 수 있으며, 재시도하여 리소스가 완료 상태에 도달하면 배포가 완료됩니다. -**배포 문제 있나요?** [인프라 README](infra/README.md)를 참조해 서브도메인 이름 충돌, 수동 Azure Portal 배포, 모델 구성 관련 문제 해결법을 확인하세요. +다음 작업이 수행됩니다: +1. GPT-5.2와 text-embedding-3-small 모델이 포함된 Azure OpenAI 리소스 배포 +2. 자격 증명이 포함된 `.env` 파일을 프로젝트 루트에 자동 생성 +3. 필요한 모든 환경 변수 설정 -**배포 성공 확인:** +**배포에 문제가 있나요?** 하위 도메인 이름 충돌, 수동 Azure Portal 배포 단계, 모델 구성 가이드 등 자세한 문제 해결은 [인프라 README](infra/README.md)를 참조하세요. + +**배포 성공 여부 확인:** **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY 등을 보여야 합니다. +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY 등을 표시해야 합니다. ``` - + **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY 등을 보여야 합니다. +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY 등을 표시해야 합니다. ``` - -> **참고:** `azd up` 명령은 `.env` 파일을 자동 생성합니다. 나중에 업데이트가 필요하면 `.env` 파일을 수동으로 수정하거나 다음 명령어로 재생성할 수 있습니다: -> + +> **참고:** `azd up` 명령은 `.env` 파일을 자동 생성합니다. 나중에 업데이트가 필요하면 `.env` 파일을 직접 수정하거나 다음 명령어를 실행해 재생성할 수 있습니다: +> > **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` - +> > **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` +## 애플리케이션 로컬 실행하기 -## 로컬에서 애플리케이션 실행하기 +**배포 확인:** -**배포 확인:** - -프로젝트 루트에 Azure 자격 증명이 포함된 `.env` 파일이 있는지 확인하세요. 모듈 디렉터리(`01-introduction/`)에서 다음을 실행합니다: +`.env` 파일이 루트 디렉터리에 Azure 자격 증명과 함께 존재하는지 확인하세요. 모듈 디렉터리(`01-introduction/`)에서 다음을 실행합니다: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 표시해야 합니다 +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 보여줘야 합니다 ``` - + **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 보여야 합니다 +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 표시해야 합니다 ``` - -**애플리케이션 시작:** -**옵션 1: Spring Boot Dashboard 사용 (VS Code 사용자에게 권장)** +**애플리케이션 시작:** -개발 컨테이너에는 Spring Boot Dashboard 확장 프로그램이 포함되어 있으며, 모든 Spring Boot 애플리케이션을 시각적으로 관리할 수 있습니다. VS Code 왼쪽의 액티비티 바에서(Spring Boot 아이콘을 찾아) 확인할 수 있습니다. +**옵션 1: Spring Boot 대시보드 사용 (VS Code 사용자를 위한 권장 방법)** -Spring Boot Dashboard에서는: -- 작업 공간 내 모든 Spring Boot 애플리케이션을 확인 가능 -- 클릭 한 번으로 애플리케이션 시작/중지 -- 실시간 로그 확인 -- 애플리케이션 상태 모니터링 +개발 컨테이너는 Spring Boot 대시보드 확장 기능을 포함하며, 이를 통해 모든 Spring Boot 애플리케이션을 시각적으로 관리할 수 있습니다. VS Code 왼쪽 활동 표시줄에서 Spring Boot 아이콘을 찾으세요. -"introduction" 옆 플레이 버튼을 클릭해 이 모듈을 시작하거나, 모든 모듈을 한 번에 시작하세요. +Spring Boot 대시보드를 사용하여: +- 작업 공간 내 모든 Spring Boot 애플리케이션 확인 +- 애플리케이션을 클릭 한 번으로 시작/중지 +- 실시간 애플리케이션 로그 보기 +- 애플리케이션 상태 모니터링 + +`introduction` 옆의 재생 버튼을 클릭해 이 모듈을 시작하거나, 모든 모듈을 한 번에 시작할 수 있습니다. Spring Boot Dashboard -*VS Code의 Spring Boot Dashboard — 한 곳에서 모든 모듈을 시작, 중지, 모니터링* +*VS Code 내의 Spring Boot 대시보드 — 한 곳에서 모든 모듈 시작, 중지 및 모니터링* **옵션 2: 셸 스크립트 사용** -모든 웹 애플리케이션(모듈 01-04) 시작: +모든 웹 애플리케이션 (모듈 01-04) 시작: **Bash:** ```bash cd .. # 루트 디렉토리에서 ./start-all.sh ``` - + **PowerShell:** ```powershell -cd .. # 루트 디렉토리에서 +cd .. # 루트 디렉터리에서 .\start-all.ps1 ``` - + 또는 이 모듈만 시작: **Bash:** @@ -240,29 +239,29 @@ cd .. # 루트 디렉토리에서 cd 01-introduction ./start.sh ``` - + **PowerShell:** ```powershell cd 01-introduction .\start.ps1 ``` - + 두 스크립트는 루트 `.env` 파일에서 환경 변수를 자동으로 로드하며, JAR 파일이 없으면 빌드합니다. -> **참고:** 시작 전에 모든 모듈을 수동으로 빌드하려면: -> +> **참고:** 시작 전에 수동으로 모든 모듈을 빌드하려면: +> > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + 브라우저에서 http://localhost:8080 을 엽니다. **중지하려면:** @@ -273,7 +272,7 @@ cd 01-introduction # 또는 cd .. && ./stop-all.sh # 모든 모듈 ``` - + **PowerShell:** ```powershell .\stop.ps1 # 이 모듈만 @@ -281,44 +280,43 @@ cd .. && ./stop-all.sh # 모든 모듈 cd ..; .\stop-all.ps1 # 모든 모듈 ``` - ## 애플리케이션 사용법 -애플리케이션은 두 가지 채팅 구현을 나란히 보여주는 웹 인터페이스를 제공합니다. +애플리케이션은 두 개의 채팅 구현을 나란히 제공하는 웹 인터페이스를 제공합니다. Application Home Screen -*상태 없는 단순 채팅과 상태 있는 대화형 채팅 옵션을 보여주는 대시보드* +*간단 채팅(상태 비저장)과 대화형 채팅(상태 저장) 옵션을 모두 보여주는 대시보드* -### 상태 없는 채팅 (왼쪽 패널) +### 상태 비저장 대화 (왼쪽 패널) -먼저 이 패널을 사용해 보세요. "내 이름은 존이야"라고 말하고 바로 "내 이름이 뭐야?"라고 질문하세요. 모델은 기억하지 못할 것입니다. 메시지가 서로 독립적이기 때문에 이전 메시지를 기억하지 않습니다. 이것이 언어 모델 통합의 핵심 문제—대화 컨텍스트가 없음—를 보여줍니다. +먼저 이것을 시도해보세요. "내 이름은 John입니다"라고 물어본 다음 바로 "내 이름이 뭐야?"라고 질문하세요. 모델은 기억하지 못합니다. 각 메시지가 독립적이기 때문입니다. 이것이 기본 언어 모델 통합의 핵심 문제 — 대화 컨텍스트가 없다는 점 — 를 보여줍니다. Stateless Chat Demo -*AI가 이전 메시지에서 이름을 기억하지 못함* +*AI는 이전 메시지에서 이름을 기억하지 못함* -### 상태 있는 채팅 (오른쪽 패널) +### 상태 저장 대화 (오른쪽 패널) -이제 똑같은 순서를 이곳에서 시도해 보세요. "내 이름은 존이야"라고 말하고 "내 이름이 뭐야?"라고 물으면 이번에는 기억합니다. 차이는 MessageWindowChatMemory 덕분이며, 대화 기록을 유지해 요청마다 포함시키기 때문입니다. 이것이 생산 대화형 AI의 작동 원리입니다. +이제 같은 질문을 여기서 해보세요. "내 이름은 John입니다"라고 말한 후 "내 이름이 뭐야?"라고 질문하면 이번에는 기억합니다. 차이점은 MessageWindowChatMemory 덕분입니다 — 대화 기록을 유지하며 각 요청에 포함시킵니다. 이것이 프로덕션 대화형 AI의 작동 방식입니다. Stateful Chat Demo -*AI가 대화 중 이전에 말한 이름을 기억함* +*AI는 대화 초반에 말한 이름을 기억함* -두 패널 모두 같은 GPT-5.2 모델을 사용합니다. 유일한 차이는 메모리입니다. 이로써 메모리가 애플리케이션에 무엇을 가져다주고 실제 사용 사례에 왜 필수적인지 명확히 알 수 있습니다. +두 패널 모두 동일한 GPT-5.2 모델을 사용합니다. 유일한 차이점은 메모리입니다. 이를 통해 메모리가 애플리케이션에 어떤 가치를 주는지, 실제 사용 사례에 왜 필수적인지 명확히 알 수 있습니다. ## 다음 단계 -**다음 모듈:** [02-prompt-engineering - GPT-5.2를 이용한 프롬프트 엔지니어링](../02-prompt-engineering/README.md) +**다음 모듈:** [02-prompt-engineering - GPT-5.2와 함께하는 프롬프트 엔지니어링](../02-prompt-engineering/README.md) --- -**네비게이션:** [← 이전: Module 00 - 빠른 시작](../00-quick-start/README.md) | [메인으로 돌아가기](../README.md) | [다음: Module 02 - 프롬프트 엔지니어링 →](../02-prompt-engineering/README.md) +**내비게이션:** [← 메인으로 돌아가기](../README.md) | [다음: 모듈 02 - 프롬프트 엔지니어링 →](../02-prompt-engineering/README.md) --- -**면책 조항**: -이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 노력하고 있으나, 자동 번역에는 오류나 부정확성이 포함될 수 있음을 유의하시기 바랍니다. 원본 문서의 원어가 권위 있는 자료로 간주되어야 합니다. 중요한 정보의 경우 전문 인간 번역을 권장합니다. 본 번역 사용으로 인한 오해나 잘못된 해석에 대해서는 당사가 책임지지 않습니다. +**면책 조항**: +이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역은 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원본 문서의 원어본이 권위 있는 자료로 간주되어야 합니다. 중요한 정보의 경우, 전문가의 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다. \ No newline at end of file diff --git a/translations/ko/02-prompt-engineering/README.md b/translations/ko/02-prompt-engineering/README.md index c2c107010..c7caf6745 100644 --- a/translations/ko/02-prompt-engineering/README.md +++ b/translations/ko/02-prompt-engineering/README.md @@ -2,84 +2,84 @@ ## 목차 -- [비디오 안내](../../../02-prompt-engineering) -- [학습 내용](../../../02-prompt-engineering) -- [사전 준비 사항](../../../02-prompt-engineering) -- [프롬프트 엔지니어링 이해하기](../../../02-prompt-engineering) -- [프롬프트 엔지니어링 기본 원칙](../../../02-prompt-engineering) - - [제로샷 프롬팅](../../../02-prompt-engineering) - - [퓨샷 프롬팅](../../../02-prompt-engineering) - - [사고의 연쇄](../../../02-prompt-engineering) - - [역할 기반 프롬팅](../../../02-prompt-engineering) - - [프롬프트 템플릿](../../../02-prompt-engineering) -- [고급 패턴](../../../02-prompt-engineering) -- [애플리케이션 실행하기](../../../02-prompt-engineering) -- [애플리케이션 스크린샷](../../../02-prompt-engineering) -- [패턴 탐구하기](../../../02-prompt-engineering) - - [낮은 열의 vs 높은 열의](../../../02-prompt-engineering) - - [작업 실행 (툴 프리앰블)](../../../02-prompt-engineering) - - [자기 반영 코드](../../../02-prompt-engineering) - - [구조화된 분석](../../../02-prompt-engineering) - - [다중 회차 채팅](../../../02-prompt-engineering) - - [단계별 추론](../../../02-prompt-engineering) - - [제한된 출력](../../../02-prompt-engineering) -- [실제로 배우는 것](../../../02-prompt-engineering) -- [다음 단계](../../../02-prompt-engineering) - -## 비디오 안내 +- [비디오 워크스루](#비디오-워크스루) +- [학습 내용](#학습-내용) +- [사전 준비 사항](#사전-준비-사항) +- [프롬프트 엔지니어링 이해하기](#프롬프트-엔지니어링-이해하기) +- [프롬프트 엔지니어링 기초](#프롬프트-엔지니어링-기초) + - [제로샷 프롬프트](#제로샷-프롬프트) + - [퓨샷 프롬프트](#퓨샷-프롬프트) + - [사고의 연쇄](#사고의-연쇄) + - [역할 기반 프롬프트](#역할-기반-프롬프트) + - [프롬프트 템플릿](#프롬프트-템플릿) +- [고급 패턴](#고급-패턴) +- [애플리케이션 실행하기](#애플리케이션-실행) +- [애플리케이션 스크린샷](#애플리케이션-스크린샷) +- [패턴 탐구](#패턴-탐색) + - [낮은 열의 vs 높은 열의](#낮은-집중력-vs-높은-집중력) + - [작업 실행 (도구 프리앰블)](#작업-실행-도구-프리앰블) + - [자기 반영 코드](#자기-반영-코드) + - [구조화된 분석](#구조적-분석) + - [다중 턴 대화](#다중-회차-채팅) + - [단계별 추론](#단계별-추론) + - [제약된 출력](#제한된-출력) +- [진짜 배우는 것](#당신이-실제로-배우는-것) +- [다음 단계](#다음-단계) + +## 비디오 워크스루 이 모듈 시작 방법을 설명하는 라이브 세션을 시청하세요: -Prompt Engineering with LangChain4j - Live Session +LangChain4j와 함께하는 프롬프트 엔지니어링 - 라이브 세션 ## 학습 내용 -다음 다이어그램은 이 모듈에서 개발할 주요 주제와 기술 개요를 제공합니다 — 프롬프트 세련화 기법부터 따라야 하는 단계별 워크플로우까지. +아래 다이어그램은 이 모듈을 통해 개발할 주요 주제와 기술 개요를 제공합니다 — 프롬프트 다듬기 기법부터 단계별 워크플로우까지. -What You'll Learn +학습 내용 -이전 모듈에서는 GitHub 모델과 기본 LangChain4j 상호작용을 탐구했고, 메모리가 Azure OpenAI와 함께 어떻게 대화형 AI를 구현하는지 살펴보았습니다. 이제는 질문하는 방식 — 즉, 프롬프트 자체 — 에 집중합니다. Azure OpenAI의 GPT-5.2를 사용하며, 프롬프트 구성 방법이 응답 품질에 얼마나 큰 영향을 미치는지 알아봅니다. 기본 프롬프트 기술을 리뷰한 다음 GPT-5.2의 기능을 최대한 활용하는 8가지 고급 패턴으로 이동합니다. +이전 모듈에서는 Azure OpenAI를 사용한 대화형 AI에서 메모리가 어떻게 작동하는지 보았습니다. 이제는 질문하는 방법 — 즉 프롬프트 자체 — 에 집중합니다. 프롬프트를 구성하는 방식이 응답 품질에 크게 영향을 미칩니다. 먼저 기본 프롬프트 기술을 검토한 후 GPT-5.2의 기능을 최대한 활용하는 여덟 개의 고급 패턴으로 넘어갑니다. -GPT-5.2를 사용하는 이유는 추론 제어 기능이 도입되어 모델이 답변 전 얼마나 많이 생각할지 지시할 수 있기 때문입니다. 이는 다양한 프롬프트 전략을 분명하게 하며, 언제 어떤 방식을 사용할지 이해하는 데 도움이 됩니다. 또한 GitHub 모델보다 GPT-5.2는 Azure에서 더 적은 호출 제한을 가지고 있어 이점이 있습니다. +GPT-5.2를 사용하는 이유는 추론 제어 기능을 도입했기 때문입니다 — 모델이 답변 전 얼마나 많이 생각할지 지정할 수 있습니다. 이는 다양한 프롬프트 전략의 차이를 명확히 하고, 각 접근법을 언제 써야 할지 이해하는 데 도움을 줍니다. ## 사전 준비 사항 -- 모듈 01 완성 (Azure OpenAI 리소스 배포 완료) -- 루트 디렉터리에 Azure 자격 증명이 포함된 `.env` 파일 (모듈 01에서 `azd up` 명령어 실행으로 생성됨) +- 모듈 01 완료 (Azure OpenAI 리소스 배포) +- 루트 디렉터리에 Azure 자격 증명이 포함된 `.env` 파일 (모듈 01에서 `azd up` 명령어로 생성됨) -> **참고:** 모듈 01을 완료하지 않았다면, 먼저 해당 모듈의 배포 지침을 따라주세요. +> **참고:** 모듈 01을 완료하지 않았다면, 먼저 거기서 배포 지침을 따르세요. ## 프롬프트 엔지니어링 이해하기 -본질적으로 프롬프트 엔지니어링은 모호한 명령과 정확한 명령의 차이입니다. 아래 비교가 그것을 보여줍니다. +프롬프트 엔지니어링의 핵심은 모호한 지시와 정확한 지시의 차이점에 있습니다. 다음 비교가 이를 보여줍니다. -What is Prompt Engineering? +프롬프트 엔지니어링이란? -프롬프트 엔지니어링은 원하는 결과를 꾸준히 얻을 수 있도록 입력 텍스트를 설계하는 것입니다. 단순히 질문하는 것이 아니라, 모델이 정확히 무엇을 원하는지 그리고 어떻게 전달할 것인지 이해하도록 요청을 구조화하는 것입니다. +프롬프트 엔지니어링은 원하는 결과를 일관되게 얻을 수 있는 입력 텍스트를 설계하는 작업입니다. 단순히 질문하는 것이 아니라, 모델이 정확히 무엇을 원하며 어떻게 전달할지 이해하도록 요청을 구조화하는 것입니다. -예를 들어 동료에게 지시하는 것과 같습니다. "버그를 고쳐라"는 모호하지만, "UserService.java 45번째 줄에서 널 포인터 예외를 널 체크를 추가하여 수정하라"는 구체적입니다. 언어 모델도 마찬가지이며, 구체성 및 구조가 중요합니다. +동료에게 지시하는 것과 비슷합니다. "버그 고쳐"는 모호하지만, "UserService.java의 45번째 줄에서 널 포인터 예외를 널 체크 추가로 고쳐"는 구체적입니다. 언어 모델도 마찬가지입니다 — 구체성과 구조가 중요합니다. -아래 다이어그램은 LangChain4j가 어떻게 이 과정에서 역할을 하는지 보여줍니다 — SystemMessage와 UserMessage 빌딩 블록을 통해 프롬프트 패턴을 모델에 연결합니다. +아래 다이어그램은 LangChain4j가 이 과정에서 어떻게 작동하는지 보여줍니다 — 프롬프트 패턴을 시스템 메시지와 사용자 메시지 빌딩 블록을 통해 모델에 연결합니다. -How LangChain4j Fits +LangChain4j의 역할 -LangChain4j는 인프라스트럭처를 제공합니다 — 모델 연결, 메모리, 메시지 타입 — 반면 프롬프트 패턴은 그 인프라를 통해 전달하는 정교하게 구조화된 텍스트일 뿐입니다. 핵심 빌딩 블록은 `SystemMessage` (AI의 동작과 역할 설정)와 `UserMessage` (실제 요청 전달)입니다. +LangChain4j는 인프라스트럭처 — 모델 연결, 메모리, 메시지 유형 — 를 제공합니다. 프롬프트 패턴은 그 인프라를 통해 전송하는 체계적으로 구성된 텍스트일 뿐입니다. 핵심 빌딩 블록은 AI의 행동과 역할을 설정하는 `SystemMessage` 와 실제 요청을 전달하는 `UserMessage` 입니다. -## 프롬프트 엔지니어링 기본 원칙 +## 프롬프트 엔지니어링 기초 -아래 보여지는 다섯 가지 핵심 기법은 효과적인 프롬프트 엔지니어링의 기본입니다. 각각은 언어 모델과 소통하는 다른 면을 다룹니다. +아래 다섯 가지 핵심 기술은 효과적인 프롬프트 엔지니어링의 토대입니다. 각각은 언어 모델과 소통하는 다양한 측면을 다룹니다. -Five Prompt Engineering Patterns Overview +다섯 가지 프롬프트 엔지니어링 패턴 개요 -이 모듈의 고급 패턴에 들어가기 전에, 다섯 가지 기본 프롬프트 기법을 복습해 봅시다. 이는 모든 프롬프트 엔지니어가 알아야 하는 빌딩 블록입니다. 만약 이미 [빠른 시작 모듈](../00-quick-start/README.md#2-prompt-patterns)을 완료했다면, 여기에 그 이론적 프레임워크가 있습니다. +이 모듈의 고급 패턴에 들어가기 전에 다섯 가지 기본 프롬프트 기술을 복습합니다. 모든 프롬프트 엔지니어가 알아야 할 빌딩 블록입니다. -### 제로샷 프롬팅 +### 제로샷 프롬프트 -가장 간단한 방식: 예시 없이 모델에 직접 명령을 내립니다. 모델은 자신의 학습만을 바탕으로 작업을 이해하고 수행합니다. 이는 예상 행동이 명확한 간단한 요청에 적합합니다. +가장 단순한 방식: 예시 없이 모델에 직접 지시를 내립니다. 모델은 오로지 학습된 내용을 바탕으로 작업을 이해하고 수행합니다. 예상되는 행동이 명확한 간단한 요청에 적합합니다. -Zero-Shot Prompting +제로샷 프롬프트 -*예시 없이 직접 명령 — 모델이 명령만으로 작업을 추론* +*예시 없이 직접 지시 — 모델이 지시만 보고 작업을 추론함* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // 응답: "긍정적" ``` -**사용 시기:** 단순 분류, 직접 질문, 번역 또는 추가 안내 없이 모델이 처리 가능한 작업. +**사용 시기:** 단순 분류, 직접 질문, 번역 또는 추가 안내 없이 모델이 처리할 수 있는 작업. -### 퓨샷 프롬팅 +### 퓨샷 프롬프트 -모델이 따라야 할 패턴을 보여주는 예시를 제공합니다. 모델은 제공된 입력-출력 형식을 학습하고 이를 새로운 입력에 적용합니다. 이는 원하는 형식이나 행동이 명확하지 않은 작업에서 일관성을 대폭 향상시킵니다. +모델이 따라야 할 패턴을 보여주는 예시를 제공합니다. 모델은 예시에서 입력-출력 형식을 배우고 이를 새로운 입력에 적용합니다. 원하는 형식이나 행동이 명확하지 않을 때 일관성 향상에 효과적입니다. -Few-Shot Prompting +퓨샷 프롬프트 -*예시를 통해 학습 — 모델이 패턴을 파악해 새 입력에 적용* +*예시로 학습 — 모델이 패턴을 파악해 새로운 입력에 적용* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**사용 시기:** 맞춤 분류, 일관된 포매팅, 도메인 특화 작업, 제로샷 결과가 불안정할 때. +**사용 시기:** 맞춤 분류, 일관된 형식, 도메인 특화 작업, 제로샷 결과가 불안정할 때. ### 사고의 연쇄 -모델에게 단계별 추론 과정을 보여 달라고 요청합니다. 바로 답을 제시하기보다 문제를 분해해 각 부분을 명확히 해결해 나갑니다. 수학, 논리, 다단계 추론 작업에서 정확도를 높입니다. +모델이 reasoning(추론) 과정을 단계별로 보여주도록 합니다. 바로 답을 내지 않고 문제를 분해해 각 부분을 명확히 처리합니다. 수학, 논리, 다단계 추론 문제의 정확도를 높입니다. -Chain of Thought Prompting +사고의 연쇄 프롬프트 -*단계별 추론 — 복잡한 문제를 명백한 논리적 단계로 분해* +*단계별 추론 — 복잡한 문제를 명확한 논리 단계로 분해* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// 모델은 15 - 8 = 7을 보여주고, 그 다음에 7 + 12 = 19개의 사과를 보여줍니다 +// 모델은 15 - 8 = 7을 보여주고, 그 다음에 7 + 12 = 19 사과를 보여줍니다 ``` -**사용 시기:** 수학 문제, 논리 퍼즐, 디버깅 또는 추론 과정이 정확도와 신뢰도를 높이는 작업. +**사용 시기:** 수학 문제, 논리 퍼즐, 디버깅, 추론 과정을 보여줘야 정확도와 신뢰가 높아지는 경우. -### 역할 기반 프롬팅 +### 역할 기반 프롬프트 -질문 전에 AI에게 페르소나나 역할을 부여합니다. 이는 응답의 톤, 깊이, 초점을 형성하는 맥락을 제공합니다. “소프트웨어 아키텍트”는 “주니어 개발자”나 “보안 감사관”과는 다른 조언을 줍니다. +질문 전에 AI에게 페르소나 또는 역할을 부여합니다. 이는 응답의 어조, 깊이, 초점을 결정하는 컨텍스트를 제공합니다. "소프트웨어 아키텍트"와 "주니어 개발자", "보안 감사자"가 주는 조언은 다릅니다. -Role-Based Prompting +역할 기반 프롬프트 -*맥락과 페르소나 설정 — 같은 질문도 역할에 따라 다른 답변* +*컨텍스트와 페르소나 설정 — 같은 질문도 역할에 따라 다른 응답* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**사용 시기:** 코드 리뷰, 튜터링, 도메인 특화 분석 혹은 특정 전문성 수준이나 관점에 맞춘 응답이 필요할 때. +**사용 시기:** 코드 리뷰, 멘토링, 도메인 특화 분석, 특정 전문성 수준 또는 관점에 맞는 응답이 필요할 때. ### 프롬프트 템플릿 -가변 자리표시자를 가진 재사용 가능한 프롬프트를 만듭니다. 매번 새 프롬프트를 작성하는 대신 템플릿을 한 번 정의하고 다양한 값을 채웁니다. LangChain4j의 `PromptTemplate` 클래스는 `{{variable}}` 구문으로 쉽게 지원합니다. +변수 자리 표시자가 포함된 재사용 가능한 프롬프트를 만듭니다. 매번 새 프롬프트를 작성하는 대신, 템플릿을 한 번 정의하고 다른 값을 채웁니다. LangChain4j의 `PromptTemplate` 클래스는 `{{variable}}` 구문으로 쉽게 만듭니다. -Prompt Templates +프롬프트 템플릿 -*변수 자리표시자가 포함된 재사용 가능한 프롬프트 — 하나의 템플릿, 여러 용도* +*변수 자리표시자가 있는 재사용 가능한 프롬프트 — 하나의 템플릿, 여러 활용* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**사용 시기:** 다양한 입력을 가진 반복 쿼리, 배치 처리, 재사용 가능한 AI 워크플로우 구축 또는 프롬프트 구조는 고정이고 데이터만 변경되는 시나리오. +**사용 시기:** 다양한 입력을 반복 질의, 배치 처리, 재사용 가능한 AI 워크플로우 구축, 프롬프트 구조는 같고 자료만 바뀔 때. --- -이 다섯 가지 기본기는 대부분의 프롬팅 작업에 탄탄한 도구세트를 제공합니다. 이 모듈의 나머지 부분은 여기에 **8가지 고급 패턴**을 더해 GPT-5.2의 추론 제어, 자기 평가 및 구조화된 출력 기능을 활용합니다. +이 다섯 가지 기초는 대부분 프롬프트 작업의 견고한 도구 키트를 제공합니다. 이 모듈의 나머지는 GPT-5.2의 추론 제어, 자기 평가, 구조화된 출력 기능을 활용한 여덟 개의 고급 패턴으로 확장합니다. ## 고급 패턴 -기본기를 다룬 후, 이 모듈만의 고유한 8가지 고급 패턴으로 넘어갑니다. 모든 문제에 동일한 접근법이 필요한 것은 아닙니다. 어떤 질문은 빠른 답변이 필요하고, 어떤 것은 깊은 사고가 필요합니다. 일부는 추론 과정을 시각적으로 보여야 하며, 다른 것은 결과만 필요합니다. 아래 각 패턴은 각기 다른 상황에 최적화되어 있으며, GPT-5.2의 추론 제어 기능이 차이를 더욱 뚜렷하게 만듭니다. +기초를 다졌으니, 이 모듈을 독특하게 만드는 여덟 개의 고급 패턴으로 넘어갑니다. 모든 문제에 같은 접근법이 필요한 건 아닙니다. 어떤 질문은 빠른 답변이, 어떤 질문은 깊은 사고가 필요합니다. 어떤 것은 추론 과정을 눈에 띄게 보여야 하고 어떤 것은 결과만 있으면 됩니다. 아래 각 패턴은 서로 다른 시나리오에 최적화되어 있으며, GPT-5.2의 추론 제어 덕분에 차이가 더욱 뚜렷해졌습니다. -Eight Prompting Patterns +여덟 가지 프롬프트 패턴 -*8가지 프롬프트 엔지니어링 패턴 및 사용 사례 개요* +*여덟 가지 프롬프트 엔지니어링 패턴과 해당 활용 사례 개요* -GPT-5.2가 이 패턴들에 또 다른 축을 더합니다: *추론 제어*. 슬라이더를 통해 모델이 얼마나 많이 사고할지 조절할 수 있습니다 — 빠르고 직접적인 답변에서 깊고 철저한 분석까지. +GPT-5.2는 여기에 *추론 제어* 라는 차원을 더했습니다. 아래 슬라이더는 모델의 사고 노력 정도를 조정하는 모습을 보여줍니다 — 빠르고 직접적인 답변부터 깊고 철저한 분석까지. -Reasoning Control with GPT-5.2 +GPT-5.2의 추론 제어 -*GPT-5.2의 추론 제어로 모델이 사고하는 정도를 지정할 수 있음 — 빠른 직접 답변부터 깊은 탐색까지* +*GPT-5.2의 추론 제어는 모델이 생각할 양을 지정할 수 있음 — 빠른 직접 답변부터 깊은 탐색까지* -**낮은 열의 (빠르고 집중적)** - 빠르고 직접적인 답변을 원하는 단순 질문에 적합합니다. 모델은 최소한의 추론만 수행 — 최대 2단계. 계산, 조회 또는 명확한 질문에 사용하세요. +**낮은 열의 (빠르고 집중됨)** - 빠르고 직접적인 답변이 필요한 간단한 질문에 적합합니다. 모델은 최소한의 추론만 하며 최대 2단계 내에서 작업합니다. 계산, 조회, 단순 질문에 사용하세요. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **GitHub Copilot으로 탐구하기:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) 파일을 열고 다음 질문을 해보세요: -> - "낮은 열의와 높은 열의 프롬팅 패턴의 차이는 무엇인가요?" -> - "프롬프트 내 XML 태그가 AI 응답 구조에 어떻게 도움을 주나요?" -> - "자기 반영 패턴과 직접 명령 패턴을 언제 사용해야 하나요?" +> 💡 **GitHub Copilot으로 탐색하기:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) 파일을 열고 질문해보세요: +> - "낮은 열의와 높은 열의 프롬프트 패턴의 차이는 무엇인가요?" +> - "프롬프트 내 XML 태그가 AI 응답 구조화에 어떻게 도움이 되나요?" +> - "언제 자기 반영 패턴을, 언제 직접 지시를 써야 하나요?" -**높은 열의 (깊고 철저함)** - 포괄적인 분석이 필요한 복잡한 문제에 적합합니다. 모델이 철저히 탐구하고 상세한 추론을 보여줍니다. 시스템 설계, 아키텍처 결정, 복잡한 연구에 사용할 수 있습니다. +**높은 열의 (깊고 철저함)** - 포괄적 분석과 상세 추론이 필요한 복잡 문제에 적합합니다. 모델은 철저히 탐색하고 자세한 추론 과정을 보여줍니다. 시스템 설계, 아키텍처 결정, 복잡한 연구에 사용하세요. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**작업 실행 (단계별 진행)** - 다단계 워크플로우를 위해. 모델이 처음에 계획을 제시하고, 작업하는 동안 각 단계를 설명하며, 마지막에 요약을 제공합니다. 마이그레이션, 구현 등 다단계 작업에 적합합니다. +**작업 실행 (단계별 진행)** - 다단계 워크플로우에 적합합니다. 모델이 사전에 계획을 제시하고 각 단계를 수행하며 설명한 뒤 최종 요약을 제공합니다. 마이그레이션, 구현, 다단계 프로세스에 사용하세요. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -사고의 연쇄 프롬팅은 모델이 추론 과정을 명시적으로 보여 주도록 하여 복잡한 작업에서 정확도를 향상시킵니다. 단계별 분해는 인간과 AI 모두가 논리를 이해하는 데 도움을 줍니다. +Chain-of-Thought 프롬프트는 모델이 추론 과정을 명확히 드러내도록 명령합니다. 복잡한 작업의 정확도가 향상되며, 단계별 분해가 인간과 AI 모두 논리를 이해하는 데 도움을 줍니다. -> **🤖 GitHub Copilot Chat에서 시도해보세요:** 다음 질문을 해보세요: -> - "장시간 소요되는 작업에 작업 실행 패턴을 어떻게 적용할 수 있나요?" -> - "프로덕션 애플리케이션에서 툴 프리앰블 구조화의 모범 사례는 무엇인가요?" -> - "중간 진행 상황을 UI에 캡처하고 표시하는 방법은?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat으로 시도해보세요:** 이 패턴에 대해 질문해보세요: +> - "장기 실행 작업에 작업 실행 패턴을 어떻게 적응시킬 수 있을까요?" +> - "프로덕션 애플리케이션에서 도구 프리앰블 구조의 모범 사례는 무엇인가요?" +> - "중간 진행 상태를 UI에 표시하려면 어떻게 캡처하고 보여줘야 할까요?" -아래 다이어그램은 이 계획 → 실행 → 요약 워크플로우를 나타냅니다. +아래 다이어그램은 이 계획 → 실행 → 요약 워크플로우를 보여줍니다. -Task Execution Pattern +작업 실행 패턴 *다단계 작업을 위한 계획 → 실행 → 요약 워크플로우* -**자기 반영 코드** - 프로덕션 품질의 코드를 생성하기 위해. 모델은 적절한 에러 핸들링과 함께 프로덕션 표준을 따르는 코드를 생성합니다. 새로운 기능이나 서비스를 구축할 때 사용하세요. +**자기 반영 코드** - 프로덕션 수준 코드 생성을 위한 패턴입니다. 모델이 적절한 오류 처리와 함께 프로덕션 표준에 맞는 코드를 생성합니다. 신규 기능이나 서비스 개발 시 활용하세요. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -아래 다이어그램은 반복 개선 루프 — 생성, 평가, 약점 파악, 개선 — 이 프로덕션 표준을 만족할 때까지 반복하는 과정을 보여줍니다. +아래 다이어그램은 반복적 개선 사이클 — 생성, 평가, 약점 식별, 개선 — 을 보여줍니다. 이 과정을 통해 코드는 프로덕션 기준에 맞춰집니다. -Self-Reflection Cycle +자기 반영 사이클 -*반복 개선 루프 — 생성, 평가, 문제 파악, 개선, 반복* +*반복적 개선 사이클 - 생성 → 평가 → 문제점 확인 → 개선 → 반복* -**구조화된 분석** - 일관된 평가를 위해. 모델은 고정된 프레임워크(정확성, 관행, 성능, 보안, 유지보수성)를 사용해 코드를 검토합니다. 코드 리뷰나 품질 평가에 적합합니다. +**구조화된 분석** - 일관된 평가를 위한 패턴입니다. 모델이 고정된 프레임워크(정확성, 관행, 성능, 보안, 유지보수성)를 사용해 코드를 검토합니다. 코드 리뷰나 품질 평가에 적합합니다. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 GitHub Copilot Chat에서 시도해보세요:** 구조화된 분석에 대해 질문해보세요: -> - "다양한 코드 리뷰 유형별로 분석 프레임워크를 어떻게 맞춤화할 수 있나요?" -> - "구조화된 출력을 프로그램적으로 파싱하고 활용하는 최선의 방법은 무엇인가요?" -> - "서로 다른 리뷰 세션에서 심각도 수준을 일관되게 유지하려면 어떻게 해야 하나요?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat으로 시도해보세요:** 구조화된 분석에 대해 질문하세요: +> - "다양한 코드 리뷰 유형에 맞게 분석 프레임워크를 어떻게 맞춤화할 수 있나요?" +> - "구조화된 출력을 프로그램적으로 파싱하고 처리하는 최선의 방법은 무엇인가요?" +> - "다양한 리뷰 세션에서 일관된 심각도 수준을 유지하려면 어떻게 해야 하나요?" -아래 다이어그램은 이 구조화된 프레임워크가 심각도 수준과 함께 코드를 일관되게 검토하도록 분류하는 방법을 보여줍니다. +아래 다이어그램은 이 구조화된 프레임워크가 심각도 수준과 함께 코드 리뷰를 일관된 카테고리로 조직하는 방식을 보여줍니다. -Structured Analysis Pattern +구조화된 분석 패턴 -*심각도 수준을 포함한 일관된 코드 리뷰를 위한 프레임워크* +*심각도 수준과 함께 일관된 코드 리뷰를 위한 프레임워크* -**다중 회차 채팅** - 맥락이 필요한 대화에 적합합니다. 모델은 이전 메시지를 기억하고 이를 기반으로 빌드업합니다. 대화형 도움말 세션이나 복잡한 Q&A에 사용합니다. +**다중 턴 대화** - 문맥이 필요한 대화에 적합한 패턴입니다. 모델이 이전 메시지를 기억하고 그 위에 쌓아 올립니다. 대화형 도움말 세션이나 복잡한 Q&A에 활용하세요. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -아래 다이어그램은 각 회차마다 대화 맥락이 어떻게 누적되며, 그 누적이 모델의 토큰 한도와 어떻게 관련되는지 시각화합니다. +아래 다이어그램은 대화 문맥이 여러 턴을 거치며 누적되는 방식과 이것이 모델의 토큰 제한과 어떻게 관련되는지 시각화합니다. -Context Memory +문맥 메모리 -*여러 회차에 걸쳐 대화 맥락이 누적되고 토큰 한도에 도달하는 과정* -**단계별 추론** - 명확한 논리가 필요한 문제에 사용합니다. 모델이 각 단계를 명시적으로 설명합니다. 수학 문제, 논리 퍼즐 또는 사고 과정을 이해해야 할 때 사용하세요. +*대화 문맥이 여러 턴에 걸쳐 누적되어 토큰 제한에 도달하는 과정* + +**단계별 추론** - 논리를 눈에 띄게 보여줘야 하는 문제에 적합합니다. 모델이 각 단계를 명시적이고 번호가 매겨진 논리적 단계로 나누어 보여줍니다. 수학문제, 논리 퍼즐, 추론 과정을 이해해야 할 때 사용하세요. ```java String prompt = """ @@ -397,14 +398,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +아래 다이어그램은 모델이 문제를 명확한 번호가 매겨진 논리 단계로 분해하는 방식을 보여줍니다. -아래 다이어그램은 모델이 문제를 명확한 번호가 붙은 논리적 단계로 어떻게 분해하는지 보여줍니다. - -Step-by-Step Pattern - +단계별 패턴 *문제를 명확한 논리 단계로 분해하기* -**제한된 출력** - 특정 형식 요구사항이 있는 응답에 사용합니다. 모델이 형식과 길이 규칙을 엄격히 준수합니다. 요약하거나 정확한 출력 구조가 필요할 때 사용하세요. +**제한된 출력** - 특정 형식 요구사항이 있는 응답용. 모델은 형식 및 길이 규칙을 엄격히 준수합니다. 요약하거나 정확한 출력 구조가 필요할 때 사용하세요. ```java String prompt = """ @@ -420,21 +420,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -아래 다이어그램은 제약조건이 모델이 특정 형식과 길이 요구사항을 엄격히 준수하도록 안내하는 방식을 보여줍니다. +다음 다이어그램은 제약 조건이 모델이 형식과 길이 요구사항을 엄격히 준수하는 출력을 생성하도록 안내하는 방식을 보여줍니다. -Constrained Output Pattern +제한된 출력 패턴 -*특정 형식, 길이, 구조 요구사항을 강제하기* +*특정 형식, 길이 및 구조 요구사항 강제 적용* ## 애플리케이션 실행 **배포 확인:** -루트 디렉터리에 Azure 자격 증명(모듈 01에서 생성)과 함께 `.env` 파일이 존재하는지 확인하세요. 모듈 디렉터리(`02-prompt-engineering/`)에서 다음을 실행합니다: +모듈 01에서 생성한 Azure 자격 증명이 포함된 `.env` 파일이 루트 디렉터리에 존재하는지 확인하세요. 모듈 디렉터리(`02-prompt-engineering/`)에서 다음을 실행합니다: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 표시해야 합니다 +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 보여야 합니다 ``` **PowerShell:** @@ -444,37 +444,37 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 보여야 **애플리케이션 시작:** -> **참고:** 이미 루트 디렉터리에서 `./start-all.sh` (모듈 01 설명 참고)를 사용해 모든 애플리케이션을 시작했다면 이 모듈은 포트 8083에서 이미 실행 중입니다. 아래 시작 명령은 건너뛰고 http://localhost:8083 로 바로 접속하세요. +> **참고:** 이미 루트 디렉터리에서 `./start-all.sh`로 모든 애플리케이션을 시작한 경우(모듈 01 참조), 이 모듈은 이미 포트 8083에서 실행 중입니다. 아래 시작 명령은 건너뛰고 바로 http://localhost:8083 으로 접속하세요. -**옵션 1: Spring Boot 대시보드 사용하기 (VS Code 사용자 권장)** +**옵션 1: Spring Boot 대시보드 사용 (VS Code 사용자 권장)** -dev 컨테이너에는 Spring Boot 대시보드 확장이 포함되어 있어 모든 Spring Boot 애플리케이션을 시각적으로 관리할 수 있습니다. VS Code 왼쪽 Activity Bar에서 Spring Boot 아이콘을 찾아보세요. +개발 컨테이너에는 모든 Spring Boot 애플리케이션 관리를 위한 시각적 인터페이스인 Spring Boot Dashboard 확장 기능이 포함되어 있습니다. VS Code 왼쪽의 활동 표시줄에서 Spring Boot 아이콘을 찾을 수 있습니다. -Spring Boot 대시보드에서: -- 워크스페이스 내 모든 Spring Boot 애플리케이션을 확인 -- 클릭 한 번으로 애플리케이션 시작/중지 -- 실시간으로 애플리케이션 로그 보기 +Spring Boot 대시보드에서는 다음이 가능합니다: +- 작업 공간 내 모든 Spring Boot 애플리케이션 확인 +- 단일 클릭으로 애플리케이션 시작/중지 +- 애플리케이션 로그 실시간 보기 - 애플리케이션 상태 모니터링 -"prompt-engineering" 옆의 재생 버튼을 클릭하면 이 모듈을 시작하거나 모든 모듈을 한 번에 시작할 수 있습니다. +"prompt-engineering" 옆의 재생 버튼을 클릭해 이 모듈을 시작하거나 모든 모듈을 한 번에 시작할 수 있습니다. -Spring Boot Dashboard +Spring Boot 대시보드 -*VS Code 내 Spring Boot 대시보드 — 하나의 장소에서 모든 모듈 시작, 중지, 모니터링* +*VS Code의 Spring Boot 대시보드 — 한 곳에서 모든 모듈을 시작, 중지 및 모니터링* -**옵션 2: 셸 스크립트 사용하기** +**옵션 2: 셸 스크립트 사용** 모든 웹 애플리케이션(모듈 01-04) 시작: **Bash:** ```bash -cd .. # 루트 디렉터리에서 +cd .. # 루트 디렉토리에서 ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # 루트 디렉토리에서 +cd .. # 루트 디렉터리에서부터 .\start-all.ps1 ``` @@ -492,16 +492,16 @@ cd 02-prompt-engineering .\start.ps1 ``` -두 스크립트는 자동으로 루트 `.env` 파일에서 환경 변수를 불러오고, JAR 파일이 없으면 빌드합니다. +두 스크립트 모두 루트 `.env` 파일에서 환경 변수를 자동으로 로드하며, JAR 파일이 없으면 빌드합니다. -> **참고:** 시작 전에 모든 모듈을 수동으로 빌드하고 싶다면: +> **참고:** 모든 모듈을 수동으로 빌드한 후 시작하고 싶다면: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -528,81 +528,81 @@ cd ..; .\stop-all.ps1 # 모든 모듈 ## 애플리케이션 스크린샷 -아래는 프롬프트 엔지니어링 모듈의 메인 인터페이스로, 8가지 패턴을 나란히 실험할 수 있습니다. +아래는 프롬프트 엔지니어링 모듈의 주요 인터페이스입니다. 여기서 8가지 패턴을 나란히 실험할 수 있습니다. -Dashboard Home +대시보드 홈 -*특징과 사용 사례가 표시된 8가지 프롬프트 엔지니어링 패턴 전용 메인 대시보드* +*8가지 프롬프트 엔지니어링 패턴과 특성 및 사용 사례를 보여주는 메인 대시보드* ## 패턴 탐색 -웹 인터페이스에서 다양한 프롬프트 전략을 실험할 수 있습니다. 각 패턴은 다른 문제를 해결합니다 — 언제 어떤 접근법이 유리한지 직접 확인해 보세요. +웹 인터페이스에서 다양한 프롬프팅 전략을 실험할 수 있습니다. 각 패턴은 다른 문제를 해결하므로, 각 접근법이 언제 빛을 발하는지 직접 확인해보세요. -> **참고: 스트리밍 vs 비스트리밍** — 모든 패턴 페이지는 **🔴 실시간 스트림 응답**과 **비스트리밍** 두 버튼을 제공합니다. 스트리밍은 서버 전송 이벤트(SSE)를 사용해 토큰이 생성되는 즉시 보여 줍니다. 비스트리밍은 전체 응답이 완료될 때까지 기다립니다. 깊은 추론이 필요한 프롬프트(예: High Eagerness, Self-Reflecting Code)는 비스트리밍 호출 시 몇 분씩 걸리며 아무 피드백 없을 수 있습니다. **복잡한 프롬프트를 실험할 때는 스트리밍을 사용해 모델 작업 과정을 실시간으로 확인하세요.** 요청이 타임아웃된 것처럼 느끼는 일을 방지할 수 있습니다. +> **참고: 스트리밍 vs 비스트리밍** — 모든 패턴 페이지에는 두 가지 버튼이 있습니다: **🔴 스트림 응답 (실시간)** 와 비스트리밍 옵션. 스트리밍은 서버-전송 이벤트(SSE)를 사용해 모델이 생성하는 토큰을 실시간으로 표시하므로 즉시 진행 상황을 볼 수 있습니다. 비스트리밍 옵션은 전체 응답을 기다린 후 표시합니다. 심층 추론을 유발하는 프롬프트(예: High Eagerness, Self-Reflecting Code)는 비스트리밍 호출 시 매우 오래 걸리거나(때론 수분 이상) 아무런 피드백 없이 대기할 수 있습니다. **복잡한 프롬프트 실험 시 스트리밍을 사용하세요**. 모델 작업 과정이 보여 요청이 타임아웃된 것처럼 느끼지 않도록 합니다. > -> **참고: 브라우저 요구사항** — 스트리밍 기능은 Fetch Streams API (`response.body.getReader()`)를 사용하며, 완전한 브라우저(Chrome, Edge, Firefox, Safari)가 필요합니다. VS Code 내장 Simple Browser는 ReadableStream API를 지원하지 않아 스트리밍이 작동하지 않습니다. Simple Browser에서 비스트리밍 버튼은 정상 작동하지만 스트리밍 버튼만 제한됩니다. 전체 기능을 위해 외부 브라우저에서 `http://localhost:8083`에 접속하세요. +> **참고: 브라우저 요구사항** — 스트리밍 기능은 Fetch Streams API(`response.body.getReader()`)를 사용하며, Chrome, Edge, Firefox, Safari 같은 완전한 브라우저에서만 작동합니다. VS Code 내장 간단 브라우저(Simple Browser)는 ReadableStream API를 지원하지 않아 스트리밍 기능이 작동하지 않습니다. 간단 브라우저를 사용할 경우, 비스트리밍 버튼은 정상 동작하지만 스트리밍 버튼만 영향을 받습니다. 완전한 경험을 위해 외부 브라우저에서 `http://localhost:8083` 을 여세요. -### 낮은 열의도 vs 높은 열의도 +### 낮은 집중력 vs 높은 집중력 -"200의 15%는 얼마인가?" 같은 단순 질문을 낮은 열의도( Low Eagerness)로 물어보세요. 즉각적이고 직관적인 답을 얻을 수 있습니다. "트래픽이 많은 API를 위한 캐싱 전략 설계" 같은 복잡한 질문은 높은 열의도(High Eagerness)로 물어보세요. **🔴 실시간 스트림 응답**을 클릭해 모델의 자세한 추론 과정을 한 토큰씩 확인하세요. 같은 모델, 같은 질문 구조지만 프롬프트가 사고의 깊이를 조절합니다. +"200의 15%가 얼마입니까?" 같은 단순 질문을 낮은 집중력(Low Eagerness)으로 물어보면 즉시 직접적인 답변을 받습니다. 반면 "고트래픽 API를 위한 캐싱 전략 설계를 해주세요" 같은 복잡한 질문은 높은 집중력(High Eagerness)으로 물어보세요. **🔴 스트림 응답 (실시간)** 을 클릭하면 모델의 자세한 추론이 토큰 단위로 나타나는 것을 볼 수 있습니다. 같은 모델, 같은 질문 구조이지만 얼마나 깊이 생각할지 프롬프트가 지시합니다. ### 작업 실행 (도구 프리앰블) -여러 단계의 워크플로에는 미리 계획하고 진행 상황을 서술하는 것이 유리합니다. 모델이 수행할 작업을 개괄하고, 각 단계를 설명하며, 결과를 요약합니다. +다단계 워크플로우는 사전 계획과 진행 상황 내레이션에 유리합니다. 모델이 할 일을 개괄하고 각 단계를 설명한 뒤 결과를 요약합니다. -### 자기반영 코드 +### 자기 반영 코드 -"이메일 유효성 검사 서비스 생성"을 시도해 보세요. 단순히 코드만 생성하지 않고, 모델이 품질 기준에 따라 평가하고 약점 파악 후 개선하며, 생산 기준에 맞을 때까지 반복합니다. +"이메일 유효성 검사 서비스를 만들어라"를 시도해 보세요. 단순히 코드를 생성하고 멈추는 대신 모델이 생성, 품질 기준에 대한 평가, 약점 발견, 개선까지 수행합니다. 코드가 프로덕션 수준에 도달할 때까지 반복 과정을 볼 수 있습니다. -### 구조화된 분석 +### 구조적 분석 -코드 리뷰에는 일관된 평가 프레임워크가 필요합니다. 모델은 고정된 범주별(정확성, 관행, 성능, 보안) 심각도 레벨을 사용해 코드를 분석합니다. +코드 리뷰는 일관된 평가 체계가 필요합니다. 모델이 고정된 카테고리(정확성, 관행, 성능, 보안)와 심각도 수준으로 코드를 분석합니다. -### 다중 턴 대화 +### 다중 회차 채팅 -"Spring Boot가 뭐야?"라고 물은 후 즉시 "예시 보여줘"라고 이어 질문해 보세요. 모델은 첫 질문을 기억하고 구체적인 Spring Boot 예시를 제공합니다. 기억 기능이 없으면 두 번째 질문은 너무 모호합니다. +"Spring Boot가 뭐야?"라고 묻고 바로 "예제를 보여줘"라고 이어 질문하세요. 모델이 첫 질문을 기억해 Spring Boot 예제를 구체적으로 제공합니다. 메모리가 없으면 두 번째 질문은 너무 애매할 것입니다. ### 단계별 추론 -수학 문제를 골라 단계별 추론과 낮은 열의도 방식 모두로 시도해 보세요. 낮은 열의도는 빠르지만 정답만 제공합니다. 단계별 추론은 모든 계산과 결정을 보여줍니다. +수학 문제 하나를 골라 단계별 추론과 낮은 집중력으로 각각 시도해 보세요. 낮은 집중력은 빠르지만 답만 줍니다 - 불투명합니다. 단계별은 모든 계산과 결정을 보여줍니다. ### 제한된 출력 -특정 형식이나 단어 수가 낯에 필요할 때 이 패턴은 엄격히 준수하게 합니다. 정확히 100단어 요약을 글머리 기호 형식으로 생성해 보세요. +특정 형식이나 단어 수가 필요할 때 이 패턴이 엄격히 준수하게 합니다. 정확히 100단어 분량의 요약을 글머리표 형식으로 만들어 보세요. -## 진짜 배우는 것 +## 당신이 실제로 배우는 것 **추론 노력은 모든 것을 바꾼다** -GPT-5.2는 프롬프트를 통해 연산 노력 정도를 조절할 수 있습니다. 적은 노력은 빠르고 최소한의 탐색을 의미합니다. 많은 노력은 모델이 깊게 사고하도록 합니다. 작업 복잡도에 맞게 노력을 조절하는 법을 배우는 것입니다 — 단순 질문에 시간 낭비하지 말고, 복잡한 결정도 서두르지 마세요. +GPT-5.2는 프롬프트를 통해 계산 노력을 제어할 수 있게 합니다. 낮은 노력은 빠른 응답과 최소 탐색을 의미합니다. 높은 노력은 모델이 시간을 들여 깊이 사고하는 것입니다. 작업 복잡도에 맞춰 노력을 조절하는 법을 배우는 겁니다 - 단순 질문에 쓸데없이 오래 투자하지 말고, 복잡한 결정은 서두르지 마세요. -**구조가 행동을 안내한다** +**구조가 행동을 이끈다** -프롬프트 내 XML 태그를 주목하세요? 단순한 장식이 아닙니다. 모델은 자유 텍스트보다 구조화된 지시문을 더 신뢰성 있게 따릅니다. 다단계 과정이나 복잡한 논리가 필요할 때 구조는 모델이 현재 위치와 다음 단계를 추적하는 데 도움을 줍니다. 아래 다이어그램은 ``, ``, ``, ``, `` 같은 태그가 명확히 구분된 섹션으로 지시를 조직하는 방식을 보여줍니다. +프롬프트의 XML 태그를 보셨나요? 장식이 아닙니다. 모델은 구조화된 지시사항을 자유 텍스트보다 훨씬 신뢰성 있게 따릅니다. 여러 단계 과정이나 복잡한 논리가 필요할 때 구조는 모델이 어디에 있고 다음에 무엇을 해야 하는지 추적하는 데 도움을 줍니다. 아래 다이어그램은 잘 구성된 프롬프트를 분해하여 ``, ``, ``, ``, `` 같은 태그가 어떻게 명확한 섹션으로 지시사항을 조직하는지 보여줍니다. -Prompt Structure +프롬프트 구조 -*명확한 구획과 XML 스타일 구성으로 이루어진 잘 구조화된 프롬프트 해부* +*명확한 섹션과 XML 스타일 구성을 갖춘 잘 짜인 프롬프트 해부* -**자기평가로 품질 향상** +**자기 평가를 통한 품질 보증** -자기반영 패턴은 품질 기준을 명시적으로 만듭니다. 모델이 “잘 하길 바라기”보다 “올바름”이 무엇인지(정확한 논리, 오류 처리, 성능, 보안)를 직접 알려줍니다. 모델은 스스로 출력물을 평가하고 개선할 수 있습니다. 코드 생성을 복권이 아닌 과정으로 바꾸는 것입니다. +자기 반영 패턴은 품질 기준을 명확히 제시하는 방식으로 작동합니다. 모델이 "잘 하길 바라기"보다는 무엇이 "옳음"인지 정확히 알려줍니다: 올바른 논리, 오류 처리, 성능, 보안 등. 모델은 스스로 출력물을 평가하고 개선할 수 있습니다. 코드 생성을 복권에서 체계적인 프로세스로 바꾸는 셈입니다. **컨텍스트는 유한하다** -다중 턴 대화는 각 요청에 메시지 이력을 포함해 작동합니다. 하지만 최대 토큰 수 한도가 있습니다. 대화가 길어질수록 관련 컨텍스트를 유지하면서 한도를 넘지 않는 전략이 필요합니다. 이 모듈에서 메모리 작동 방식을 배우고, 추후에 언제 요약하고 잊고 불러올지 배울 것입니다. +다중 회차 대화는 각 요청에 메시지 기록을 포함하는 방식으로 작동하지만 제한이 있습니다 - 모든 모델은 최대 토큰 수 한도가 있습니다. 대화가 길어질수록 관련 컨텍스트를 유지하면서 한도에 도달하지 않도록 전략이 필요합니다. 이 모듈은 메모리 작동법을 보여주고, 이후 요약, 잊기, 검색 시점을 배우게 됩니다. ## 다음 단계 -**다음 모듈:** [03-rag - RAG (검색 확장 생성)](../03-rag/README.md) +**다음 모듈:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**네비게이션:** [← 이전: 모듈 01 - 소개](../01-introduction/README.md) | [메인으로 돌아가기](../README.md) | [다음: 모듈 03 - RAG →](../03-rag/README.md) +**탐색:** [← 이전: 모듈 01 - 소개](../01-introduction/README.md) | [메인으로 돌아가기](../README.md) | [다음: 모듈 03 - RAG →](../03-rag/README.md) --- -**면책 조항**: -이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 이용해 번역되었습니다. 정확성을 위해 노력하고 있으나, 자동 번역은 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원문은 해당 언어로 된 원본 문서를 권위 있는 출처로 간주해야 합니다. 중요한 정보의 경우 전문적인 인간 번역을 권장합니다. 이 번역 사용으로 인한 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다. +**면책 조항**: +이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역은 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원본 문서의 원어본이 권위 있는 자료로 간주되어야 합니다. 중요한 정보의 경우, 전문가의 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다. \ No newline at end of file diff --git a/translations/ko/03-rag/README.md b/translations/ko/03-rag/README.md index d9e8e9480..d2b0093a9 100644 --- a/translations/ko/03-rag/README.md +++ b/translations/ko/03-rag/README.md @@ -1,144 +1,143 @@ -# Module 03: RAG (검색 보강 생성) +# Module 03: RAG (검색 증강 생성) ## 목차 -- [비디오 워크스루](../../../03-rag) -- [학습 내용](../../../03-rag) -- [전제 조건](../../../03-rag) -- [RAG 이해하기](../../../03-rag) - - [이 튜토리얼에서 사용하는 RAG 접근법은?](../../../03-rag) -- [동작 원리](../../../03-rag) - - [문서 처리](../../../03-rag) - - [임베딩 생성](../../../03-rag) - - [의미 기반 검색](../../../03-rag) - - [답변 생성](../../../03-rag) -- [애플리케이션 실행](../../../03-rag) -- [애플리케이션 사용법](../../../03-rag) - - [문서 업로드](../../../03-rag) - - [질문하기](../../../03-rag) - - [소스 참조 확인](../../../03-rag) - - [질문 실험하기](../../../03-rag) -- [핵심 개념](../../../03-rag) - - [청킹 전략](../../../03-rag) - - [유사도 점수](../../../03-rag) - - [메모리 내 저장소](../../../03-rag) - - [컨텍스트 윈도우 관리](../../../03-rag) -- [RAG가 중요한 시점](../../../03-rag) -- [다음 단계](../../../03-rag) +- [비디오 워크스루](#비디오-워크스루) +- [학습 내용](#학습-내용) +- [필수 조건](#필수-조건) +- [RAG 이해하기](#rag-이해하기) + - [이 튜토리얼에서 사용하는 RAG 접근법은?](#이-튜토리얼에서-사용하는-rag-접근법은) +- [작동 원리](#작동-원리) + - [문서 처리](#문서-처리) + - [임베딩 생성](#임베딩-생성) + - [시맨틱 검색](#시맨틱-검색) + - [답변 생성](#응답-생성) +- [애플리케이션 실행하기](#애플리케이션-실행) +- [애플리케이션 사용법](#애플리케이션-사용법) + - [문서 업로드](#문서-업로드) + - [질문하기](#질문하기) + - [소스 참조 확인](#출처-확인하기) + - [질문 실험하기](#다양한-질문-시도하기) +- [핵심 개념](#주요-개념) + - [청킹 전략](#청크-분할-전략) + - [유사도 점수](#유사도-점수) + - [인메모리 저장소](#인메모리-저장소) + - [컨텍스트 윈도우 관리](#문맥-창-관리) +- [RAG가 중요한 경우](#rag가-중요한-경우) +- [다음 단계](#다음-단계) ## 비디오 워크스루 -이 모듈 시작 방법을 설명하는 라이브 세션을 시청하세요: +이 모듈을 시작하는 방법을 설명하는 라이브 세션을 시청하세요: RAG with LangChain4j - Live Session ## 학습 내용 -이전 모듈에서는 AI와 대화하는 방법과 효과적으로 프롬프트를 구성하는 방법을 배웠습니다. 하지만 근본적인 한계가 있습니다: 언어 모델은 오직 훈련 시 학습한 내용만 알고 있습니다. 회사 정책, 프로젝트 문서 또는 훈련 받지 않은 정보에 대한 질문에 답할 수 없습니다. +이전 모듈에서 AI와 대화하고 프롬프트를 효과적으로 구성하는 방법을 배웠습니다. 하지만 근본적인 한계가 있습니다: 언어 모델은 학습 시에만 알고 있는 정보만을 바탕으로 작동합니다. 회사 정책, 프로젝트 문서, 혹은 학습되지 않은 정보에 대해 질문하면 답변할 수 없습니다. -RAG(검색 보강 생성)는 이 문제를 해결합니다. 모델에게 정보를 직접 가르치는 대신(비용도 많이 들고 실용적이지도 않음), 문서 내에서 검색 기능을 제공합니다. 누군가 질문을 하면 시스템이 관련 정보를 찾아 프롬프트에 포함시킵니다. 모델은 그 검색된 컨텍스트를 기반으로 답변합니다. +RAG (검색 증강 생성)는 이 문제를 해결합니다. 모델에게 정보를 직접 가르치려 하기보다(비용과 실용성 문제), 문서 내에서 검색할 수 있는 능력을 제공합니다. 누군가 질문을 하면, 시스템이 관련 정보를 찾아 프롬프트에 포함시키고 모델은 그 검색된 컨텍스트를 바탕으로 답변합니다. -RAG를 모델에게 참고 도서관을 주는 것으로 생각해 보세요. 질문하면 시스템은: +RAG를 모델에게 참고 도서관을 제공하는 것으로 생각해 보세요. 질문하면 시스템은 다음을 수행합니다: -1. **사용자 쿼리** - 질문을 합니다 -2. **임베딩** - 질문을 벡터로 변환합니다 +1. **사용자 질의** - 질문을 합니다 +2. 임베딩 - 질문을 벡터로 변환합니다 3. **벡터 검색** - 유사한 문서 청크를 찾습니다 -4. **컨텍스트 구성** - 관련 청크를 프롬프트에 추가합니다 -5. **응답** - LLM이 그 컨텍스트 기반으로 답변을 생성합니다 +4. **컨텍스트 조립** - 관련 청크를 프롬프트에 추가합니다 +5. 응답 - LLM이 컨텍스트를 기반으로 답변을 생성합니다 -이로써 모델의 답변이 학습 지식에만 의존하지 않고 실제 데이터에 근거하도록 합니다. +이렇게 하면 모델의 응답이 학습 지식에 근거하지 않고 실제 데이터에 기반하여 제공됩니다. -## 전제 조건 +## 필수 조건 -- [Module 00 - 빠른 시작](../00-quick-start/README.md) 완료 (이 모듈에서 나중에 참조하는 Easy RAG 예제 사용법) -- [Module 01 - 소개](../01-introduction/README.md) 완료 (Azure OpenAI 리소스 배포, `text-embedding-3-small` 임베딩 모델 포함) -- 루트 디렉토리에 Azure 자격 증명이 포함된 `.env` 파일 (Module 01에서 `azd up` 명령으로 생성됨) +- [Module 01 - 소개](../01-introduction/README.md) 완료 (Azure OpenAI 리소스가 배포되어야 하며 `text-embedding-3-small` 임베딩 모델 포함) +- 루트 디렉터리에 `.env` 파일에 Azure 자격 증명 포함 (`Module 01`에서 `azd up` 실행 시 생성) -> **참고:** Module 01을 완료하지 않았다면 먼저 배포 지침을 따라 진행하세요. `azd up` 명령은 이 모듈에서 사용하는 GPT 채팅 모델과 임베딩 모델을 모두 배포합니다. +> **참고:** Module 01을 완료하지 않았다면 우선 그 지침을 따라 배포하세요. `azd up` 명령은 이 모듈에서 사용하는 GPT 채팅 모델과 임베딩 모델을 모두 배포합니다. ## RAG 이해하기 -아래 다이어그램은 핵심 개념을 보여줍니다: 단순히 모델의 학습 데이터에 의존하는 대신, RAG는 답변 생성 전에 참조할 사용자의 문서 라이브러리를 제공합니다. +아래 다이어그램은 핵심 개념을 보여줍니다: 모델의 학습 데이터에만 의존하는 대신, RAG는 답변 생성 전에 참조할 수 있는 문서 라이브러리를 제공합니다. What is RAG -*이 다이어그램은 표준 LLM(학습 데이터로 추측)과 RAG 강화 LLM(문서를 먼저 참조) 간의 차이를 보여줍니다.* +*이 다이어그램은 일반 LLM(학습 데이터만 추론)과 RAG 강화 LLM(먼저 문서를 참조하는)의 차이를 보여줍니다.* -다음은 단계별 동작 연결 방식입니다. 사용자의 질문은 임베딩, 벡터 검색, 컨텍스트 구성, 답변 생성의 네 단계를 거치며 이전 단계에 따라 쌓입니다: +사용자 질문이 임베딩 → 벡터 검색 → 컨텍스트 조립 → 답변 생성이라는 네 단계로 흐르는 과정을 보여줍니다: RAG Architecture -*이 다이어그램은 사용자 쿼리가 임베딩, 벡터 검색, 컨텍스트 구성, 답변 생성 단계를 거치는 RAG 파이프라인을 보여줍니다.* +*이 다이어그램은 RAG 파이프라인의 처음부터 끝까지—임베딩, 벡터 검색, 컨텍스트 조립, 답변 생성 단계를 거치는 사용자 질의 흐름을 보여줍니다.* -이 모듈 나머지에서는 실제 코드와 함께 각 단계를 상세히 설명합니다. +이 모듈의 나머지 부분은 각 단계를 실제 코드와 함께 상세히 다룹니다. ### 이 튜토리얼에서 사용하는 RAG 접근법은? -LangChain4j는 세 가지 RAG 구현 방식을 제공합니다. 이 다이어그램은 세 가지 방식을 나란히 비교합니다: +LangChain4j는 추상화 수준이 다른 세 가지 RAG 구현 방식을 제공합니다. 아래 다이어그램은 이들을 나란히 비교한 것입니다: Three RAG Approaches in LangChain4j -*이 다이어그램은 LangChain4j의 Easy, Native, Advanced 세 가지 RAG 접근법의 주요 구성 요소와 사용 시기를 비교한 것입니다.* +*이 다이어그램은 LangChain4j의 세 가지 RAG 방식(쉬운, 네이티브, 고급)과 주요 구성요소, 사용 시기를 비교합니다.* -| 방법 | 설명 | 트레이드오프 | +| 접근법 | 설명 | 트레이드오프 | |---|---|---| -| **Easy RAG** | `AiServices`와 `ContentRetriever`를 통해 모든 단계가 자동으로 연결됩니다. 인터페이스에 주석을 달고 리트리버를 연결하기만 하면 LangChain4j가 임베딩, 검색, 프롬프트 조립을 뒤에서 처리합니다. | 코드가 최소화되지만 각 단계가 어떻게 작동하는지 볼 수 없습니다. | -| **Native RAG** | 임베딩 모델 호출, 저장소 검색, 프롬프트 구성, 답변 생성 단계를 직접 한 단계씩 명시적으로 구현합니다. | 더 많은 코드 작성이 필요하지만 모든 단계가 보여지고 수정 가능합니다. | -| **Advanced RAG** | 쿼리 변환기, 라우터, 재정렬기, 콘텐츠 주입기를 플러그인 방식으로 사용하는 `RetrievalAugmentor` 프레임워크를 활용해 프로덕션급 파이프라인을 구축합니다. | 최고의 유연성을 제공하지만 상당히 복잡합니다. | +| **쉬운 RAG** | `AiServices`와 `ContentRetriever`를 통해 모든 걸 자동으로 연결합니다. 인터페이스에 주석을 달고 리트리버를 연결하면 임베딩, 검색, 프롬프트 조립을 LangChain4j가 처리합니다. | 코드가 최소화되지만 각 단계가 어떻게 동작하는지 볼 수 없습니다. | +| **네이티브 RAG** | 임베딩 모델을 호출하고 저장소를 검색하며 프롬프트를 구성하고 답변을 생성하는 각 단계를 직접 명시적으로 수행합니다. | 코드가 더 많지만 모든 단계를 명확히 보고 수정할 수 있습니다. | +| **고급 RAG** | 플러그형 쿼리 변환기, 라우터, 재순위기, 콘텐츠 주입기를 갖춘 `RetrievalAugmentor` 프레임워크를 사용하여 프로덕션급 파이프라인을 구성합니다. | 가장 유연하지만 복잡도가 크게 증가합니다. | -**이 튜토리얼은 Native 방식을 사용합니다.** 쿼리 임베딩, 벡터 저장소 검색, 컨텍스트 조립, 답변 생성 등 RAG 파이프라인의 각 단계가 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 내에 명확히 작성되어 있습니다. 학습 자료로서 코드를 최소화하기보다 각 단계를 보고 이해하는 것이 중요하기 때문입니다. 단계별 동작에 익숙해지면 빠른 프로토타입을 위해 Easy RAG로, 프로덕션 시스템에는 Advanced RAG로 진행할 수 있습니다. +**이 튜토리얼은 네이티브 방식을 사용합니다.** 쿼리 임베딩, 벡터 저장소 검색, 컨텍스트 조립, 답변 생성 등 RAG 파이프라인의 각 단계가 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java)에서 명시적으로 작성되어 있습니다. 학습용으로서 코드를 최소화하는 것보다 각 단계를 보고 이해하는 것이 중요하기 때문입니다. 이후엔 쉽게 쓰려면 쉬운 RAG, 프로덕션용이라면 고급 RAG를 선택할 수 있습니다. -> **💡 Easy RAG를 이미 경험해 보셨나요?** [빠른 시작 모듈](../00-quick-start/README.md)에는 Easy RAG를 사용한 문서 Q&A 예제([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java))가 있습니다 — LangChain4j가 임베딩, 검색, 프롬프트 조립을 자동으로 처리합니다. 이 모듈은 그 파이프라인을 분해하여 각 단계를 직접 보고 제어할 수 있도록 한 단계 더 나아갑니다. +> **💡 쉬운 RAG에 관심 있나요?** LangChain4j는 `AiServices`와 `ContentRetriever`가 임베딩, 검색, 프롬프트 조립을 자동으로 처리하는 *쉬운 RAG* 방식을 지원합니다. 이 모듈은 각 단계를 직접 열어 보고 제어하는 명시적인 경로를 택했습니다. -아래 다이어그램은 그 빠른 시작 예제의 Easy RAG 파이프라인을 보여줍니다. `AiServices`와 `EmbeddingStoreContentRetriever`가 모든 복잡함을 숨기고, 문서를 로드해 리트리버를 연결하면 바로 답변을 받을 수 있습니다. 이 모듈의 Native 방식은 그 숨겨진 단계들을 모두 분해합니다: +아래 다이어그램은 쉬운 RAG 파이프라인을 보여줍니다. `AiServices`와 `EmbeddingStoreContentRetriever`가 복잡함을 숨기고 있어, 문서를 로드하고 리트리버만 붙이면 바로 답변을 얻을 수 있습니다. 이 모듈의 네이티브 방식은 그 숨겨진 각 단계를 연 세부 과정을 보여줍니다: Easy RAG Pipeline - LangChain4j -*이 다이어그램은 `SimpleReaderDemo.java`의 Easy RAG 파이프라인을 보여줍니다. Easy RAG는 임베딩, 검색, 프롬프트 조립을 `AiServices`와 `ContentRetriever` 뒤에 숨깁니다 — 문서를 로드하고 리트리버를 연결하면 답을 받습니다. 이 모듈의 Native 방식은 그 파이프라인을 분해해 각 단계(임베딩, 검색, 컨텍스트 조립, 생성)를 직접 호출하고 전체 과정을 볼 수 있습니다.* +*이 다이어그램은 쉬운 RAG 파이프라인을 나타냅니다. 이 모듈에서 사용하는 네이티브 방식과 비교해 보세요: 쉬운 RAG는 임베딩, 검색, 프롬프트 조립을 `AiServices`와 `ContentRetriever` 뒤에 숨기지만, 네이티브 방식은 각 단계를 직접 호출해 완전한 가시성과 제어를 제공합니다.* -## 동작 원리 +## 작동 원리 -이 모듈의 RAG 파이프라인은 사용자가 질문할 때마다 순차로 실행되는 네 단계로 나뉩니다. 먼저 업로드된 문서를 **파싱하고 청크**로 나눕니다. 청크들은 모델의 컨텍스트 창에 잘 맞을 만큼 작은 조각입니다. 그런 다음 청크를 **벡터 임베딩**으로 변환해 수학적으로 비교 가능하게 저장합니다. 질문이 들어오면 시스템은 **의미 기반 검색**을 수행해 가장 관련성 높은 청크를 찾고, 마지막으로 LLM에 그 청크들을 컨텍스트로 전달해 **답변 생성**을 합니다. 아래 각 단계를 코드와 다이어그램으로 설명합니다. 먼저 첫 단계부터 살펴보겠습니다. +이 모듈의 RAG 파이프라인은 사용자가 질문할 때마다 순차적으로 네 단계로 실행됩니다. 먼저 업로드된 문서를 **파싱하고 청킹(분할)** 합니다. 그런 다음 청크들을 벡터 임베딩으로 변환하여 저장하고, 쿼리가 들어오면 시맨틱 검색으로 관련 청크를 찾고, 마지막으로 이 청크들을 LLM에 컨텍스트로 넘겨 답변 생성을 합니다. 아래 섹션은 각 단계를 코드 및 도표로 설명합니다. 첫 번째 단계를 살펴보겠습니다. ### 문서 처리 [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -문서를 업로드하면 시스템이 해당 문서를 파싱(PDF 또는 일반 텍스트), 파일명 같은 메타데이터를 첨부한 뒤 문서를 청크로 분할합니다 — 모델 컨텍스트 크기에 맞게 적당히 작은 조각들입니다. 청크 사이에는 약간 겹침이 있어 경계 부분에서 컨텍스트 손실을 방지합니다. +문서를 업로드하면 시스템이 PDF 또는 일반 텍스트를 파싱하고, 파일명 같은 메타데이터를 추가한 후, 모델의 컨텍스트 윈도우에 잘 맞는 크기로 청크로 나눕니다. 청크끼리는 경계에서 약간 겹칩니다. ```java -// 업로드된 파일을 분석하고 LangChain4j 문서로 감싸기 +// 업로드된 파일을 파싱하고 LangChain4j 문서에 래핑합니다 Document document = Document.from(content, metadata); -// 30토큰 중첩으로 300토큰 청크로 분할하기 +// 30토큰 겹침을 가진 300토큰 청크로 분할합니다 DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -아래 다이어그램은 작동 방식을 시각적으로 보여줍니다. 각 청크가 이웃 청크와 일부 토큰을 공유하는 모습을 볼 수 있습니다 — 30 토큰의 겹침이 중요한 컨텍스트가 끊기지 않게 보장합니다: +아래 다이어그램은 이를 시각적으로 보여줍니다. 각 청크가 이웃 청크와 약간씩 토큰을 공유하는데, 30토큰 겹침은 중요한 컨텍스트가 경계에서 끊어지지 않도록 보장합니다: Document Chunking -*이 다이어그램은 문서를 300 토큰씩 청크로 나누고 30 토큰씩 겹치게 하여 청크 경계에서 컨텍스트가 보존되는 과정을 보여줍니다.* +*이 다이어그램은 문서를 300토큰 크기 청크로 나누고 30토큰씩 겹쳐 청크 경계에서 컨텍스트를 유지하는 방법을 보여줍니다.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) 챗으로 시도해보세요:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) 열고 질문해보세요: -> - "LangChain4j가 문서를 어떻게 청크로 분할하며 왜 겹침이 중요한가요?" -> - "문서 유형별 최적 청크 크기는 얼마이며 그 이유는?" -> - "다국어 문서나 특수 포매팅 문서는 어떻게 처리할까요?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat과 함께 시도해 보세요:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java)를 열고 질문해 보세요: +> - "LangChain4j가 문서를 어떻게 청킹하고 겹침이 왜 중요한가요?" +> - "문서 타입별 최적 청크 크기는 무엇이며 이유는?" +> - "다국어 문서나 특수 포맷 문서는 어떻게 처리하나요?" ### 임베딩 생성 [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -각 청크는 임베딩이라 불리는 수치적 표현으로 변환됩니다 — 의미를 숫자로 바꾸는 과정입니다. 임베딩 모델은 챗 모델처럼 지능적이지 않습니다; 지시를 따르거나 추론하거나 질문에 직접 답하지 못합니다. 텍스트를 수학적 공간에 매핑해 유사 의미가 가까이 위치하도록 합니다 — 예를 들어 "car"와 "automobile"이 가깝고, "refund policy"와 "return my money"가 가깝게 배치됩니다. 챗 모델이 대화 상대라면, 임베딩 모델은 매우 훌륭한 분류 시스템이라 할 수 있습니다. +각 청크는 임베딩이라고 하는 수치적 표현으로 변환됩니다 — 본질적으로 의미를 수치로 바꾸는 역할입니다. 임베딩 모델은 챗 모델처럼 "똑똑한" 것이 아닙니다; 명령을 따르거나 추론하거나 질문에 답할 수 없습니다. 다만, 비슷한 의미를 가진 텍스트들이 가까운 수학적 공간에 놓이도록 매핑합니다 — "car"와 "automobile", "refund policy"와 "return my money"가 비슷하게 위치하는 것처럼요. 챗 모델을 사람이랑 대화하는 것에 비유한다면 임베딩 모델은 매우 잘 짜인 분류 시스템입니다. -아래 다이어그램은 이 개념을 시각화했습니다 — 텍스트 입력, 수치 벡터 출력, 유사 의미가 근접한 위치에 자리잡음: +아래 다이어그램은 이 개념을 시각화합니다 — 텍스트가 들어가면 수치 벡터가 나오고, 비슷한 의미들은 서로 가까운 벡터로 나타납니다: Embedding Model Concept -*이 다이어그램은 임베딩 모델이 텍스트를 수치 벡터로 변환하며, "car"와 "automobile" 같은 유사 의미를 벡터 공간에서 가까운 위치에 배치하는 과정을 보여줍니다.* +*이 다이어그램은 임베딩 모델이 텍스트를 수치 벡터로 변환하고, "car"와 "automobile"처럼 비슷한 의미가 벡터 공간에서 가까이 위치하는 방식을 보여줍니다.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -아래 클래스 다이어그램은 RAG 파이프라인의 두 가지 흐름과 LangChain4j 클래스 구현을 보여줍니다. **등록 흐름**(업로드 시 1회 실행)은 문서를 분할하고, 청크를 임베딩해 `.addAll()`로 저장합니다. **쿼리 흐름**(사용자 질문 때마다 실행)은 질문을 임베딩하고, 저장소를 `.search()`해 일치하는 컨텍스트를 챗 모델에 전달합니다. 두 흐름은 `EmbeddingStore`라는 공통 인터페이스를 통해 연결됩니다: +아래 클래스 다이어그램은 RAG 파이프라인의 두 흐름과 이를 구현한 LangChain4j 클래스를 보여줍니다. **인제스션 흐름**(업로드 시 단 한 번 실행)은 문서를 분할하고 청크를 임베딩한 뒤 `.addAll()`로 저장합니다. **쿼리 흐름**(사용자 질문 시 실행)은 질문을 임베딩하고 `.search()`로 저장소를 검색한 뒤 매칭된 컨텍스트를 채팅 모델에 전달합니다. 두 흐름은 공용 `EmbeddingStore` 인터페이스를 경유합니다: LangChain4j RAG Classes -*이 다이어그램은 RAG 파이프라인의 등록 흐름과 쿼리 흐름, 그리고 공유 EmbeddingStore를 통한 연결 방식을 보여줍니다.* +*이 다이어그램은 RAG 파이프라인의 인제스션 및 쿼리 두 흐름과 공용 EmbeddingStore를 통한 연결을 보여줍니다.* -임베딩이 저장되면 유사한 내용이 자연스럽게 벡터 공간에 군집을 형성합니다. 아래 시각화는 관련 주제의 문서들이 벡터 공간 내에 가까운 점으로 모이는 모습을 보여주며, 이것이 의미 기반 검색이 가능하게 하는 기반입니다: +임베딩이 저장되면 유사한 내용은 벡터 공간에서 자연스럽게 군집을 이룹니다. 아래 시각화는 관련 주제 문서들이 3D 벡터 공간에서 근접한 점으로 나타나는 모습을 보여주어 시맨틱 검색의 가능성을 시사합니다: Vector Embeddings Space -*이 시각화는 기술 문서, 비즈니스 규칙, FAQ 같은 주제별 관련 문서들이 3D 벡터 공간에서 별개의 군집을 형성하는 모습을 보여줍니다.* +*이 시각화는 기술 문서, 비즈니스 규칙, FAQ 같은 주제가 3D 벡터 공간에서 별도 클러스터를 형성하는 방식을 보여줍니다.* -사용자가 검색할 때 시스템은 네 단계를 따릅니다: 문서를 한 번 임베딩, 매 검색 시 질문 임베딩, 코사인 유사도로 질문 벡터와 저장된 모든 벡터 비교, 상위 K개 청크 반환. 아래 다이어그램은 각 단계와 관련 LangChain4j 클래스를 보여줍니다: +사용자가 검색할 때 시스템은 네 단계를 거칩니다: 문서를 한 번 임베딩, 검색 시 쿼리 임베딩, 쿼리 벡터와 저장된 모든 벡터를 코사인 유사도로 비교, 그 중 상위 K개 청크 반환. 아래 다이어그램은 각 단계와 관여하는 LangChain4j 클래스를 표시합니다: Embedding Search Steps -*이 다이어그램은 임베딩 검색 네 단계 과정을 보여줍니다: 문서 임베딩, 질문 임베딩, 코사인 유사도 비교, 상위 K개 결과 반환.* +*이 다이어그램은 임베딩 검색 과정 네 단계를 — 문서 임베딩, 쿼리 임베딩, 코사인 유사도 비교, 상위 K결과 반환 — 보여줍니다.* -### 의미 기반 검색 +### 시맨틱 검색 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -질문을 하면 그 질문 역시 임베딩으로 변환됩니다. 시스템은 질문 임베딩을 모든 문서 청크 임베딩과 비교합니다. 가장 의미가 비슷한 청크들을 찾는데, 단순 키워드 일치가 아니라 실제 의미 유사성입니다. +사용자가 질문을 하면 질문 자체도 임베딩으로 변환됩니다. 시스템은 질문 임베딩과 모든 문서 청크 임베딩을 비교하여 가장 의미가 비슷한 청크를 찾습니다 — 키워드 일치뿐 아니라 실제 시맨틱 유사성을 평가합니다. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -아래 다이어그램은 의미 기반 검색과 전통적인 키워드 검색을 대비해서 보여줍니다. "vehicle"이라는 키워드 검색은 "cars and trucks" 내용 청크를 놓치지만, 의미 기반 검색은 같은 의미임을 이해하고 높은 점수를 주어 반환합니다: +아래 다이어그램은 시맨틱 검색과 전통적인 키워드 검색을 대비하여 설명합니다. "vehicle" 검색 키워드로는 "cars and trucks"가 포함된 청크를 놓치지만, 시맨틱 검색은 동일한 의미임을 이해해 상위 점수를 줍니다: Semantic Search -*이 다이어그램은 키워드 기반 검색과 의미 기반 검색을 비교하며, 의미 기반 검색은 정확한 키워드가 달라도 개념적으로 관련된 콘텐츠를 찾아내는 과정을 보여줍니다.* -내부적으로 유사도는 코사인 유사도(cosine similarity)를 사용하여 측정됩니다 — 본질적으로 "이 두 화살표가 같은 방향을 가리키고 있나요?"라고 묻는 것과 같습니다. 두 개의 청크가 전혀 다른 단어를 사용하더라도 의미가 같으면 그 벡터들은 같은 방향을 가리키며 점수는 1.0에 가깝게 나옵니다: +*이 다이어그램은 키워드 기반 검색과 시맨틱 검색을 비교하며, 시맨틱 검색은 정확한 키워드가 다르더라도 개념적으로 연관된 내용을 찾아서 반환하는 모습을 나타냅니다.* -Cosine Similarity +내부적으로 유사도는 코사인 유사도로 측정합니다 — "두 벡터가 같은 방향을 가리키는지"를 묻는 셈입니다. 서로 다른 단어를 써도 의미가 같으면 벡터 방향이 같아 점수가 1.0에 가까워집니다: -*이 다이어그램은 임베딩 벡터 간의 각도로서 코사인 유사도를 보여줍니다 — 벡터가 더 일치할수록 점수가 1.0에 가까워져 더 높은 의미적 유사성을 나타냅니다.* +Cosine Similarity +*이 다이어그램은 임베딩 벡터 사이의 각도로 코사인 유사도를 나타냅니다 — 더 정렬된 벡터는 1.0에 가까운 점수를 획득하여 더 높은 의미론적 유사성을 나타냅니다.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat으로 시도해 보세요:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java)를 열고 다음을 물어보세요: +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat으로 시도해보세요:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java)를 열고 다음을 물어보세요: > - "임베딩과 함께 유사도 검색은 어떻게 작동하며 점수는 무엇에 의해 결정되나요?" -> - "어떤 유사도 임계값을 사용해야 하며 결과에 어떻게 영향을 주나요?" -> - "관련 문서가 없을 때는 어떻게 처리하나요?" +> - "어떤 유사도 임계값을 사용해야 하며 결과에 어떤 영향을 미치나요?" +> - "관련 문서를 찾지 못한 경우 어떻게 처리하나요?" -### 답변 생성 +### 응답 생성 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -가장 관련성 높은 청크들이 명확한 지침, 검색된 문맥, 사용자 질문을 포함하는 구조화된 프롬프트로 조립됩니다. 모델은 특정 청크만 읽고 그 정보를 바탕으로 답변을 생성하며 — 앞에 있는 정보만을 사용하므로 환각을 방지할 수 있습니다. +가장 관련성 높은 청크들은 명확한 지침, 검색된 문맥, 그리고 사용자의 질문을 포함하는 구조화된 프롬프트로 조립됩니다. 모델은 특정 청크만 읽고 이 정보를 바탕으로 답변을 생성하여 환각을 방지합니다. ```java String context = matches.stream() @@ -237,47 +236,47 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -아래 다이어그램은 이 조립 과정을 보여줍니다 — 검색 단계에서 최고 점수의 청크들이 프롬프트 템플릿에 주입되고, `OpenAiOfficialChatModel`이 근거 있는 답변을 생성합니다: +아래 다이어그램은 조립 과정을 보여줍니다 — 검색 단계에서 최고 점수를 받은 청크들이 프롬프트 템플릿에 삽입되고, `OpenAiOfficialChatModel`이 근거 있는 답변을 생성합니다: Context Assembly -*이 다이어그램은 최고 점수 청크가 구조화된 프롬프트로 조립되어 모델이 데이터로부터 근거 있는 답변을 생성하는 방식을 보여줍니다.* +*이 다이어그램은 최고 점수를 받은 청크들을 구조화된 프롬프트로 조립하여 모델이 데이터에서 근거 있는 답변을 생성하는 방식을 보여줍니다.* -## 애플리케이션 실행하기 +## 애플리케이션 실행 **배포 확인:** -`.env` 파일이 루트 디렉토리에 존재하며 Azure 자격 증명(모듈 01에서 생성됨)이 포함되어 있는지 확인하세요. 모듈 디렉토리(`03-rag/`)에서 다음을 실행합니다: +루트 디렉토리에 Azure 자격 증명과 함께 `.env` 파일이 존재하는지 확인하세요(Module 01에서 생성됨). 모듈 디렉토리(`03-rag/`)에서 다음 명령을 실행합니다: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 표시해야 합니다 +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT을 표시해야 합니다 ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT을(를) 보여야 합니다 +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 보여야 합니다 ``` **애플리케이션 시작:** -> **참고:** 이미 루트 디렉토리에서 `./start-all.sh` (모듈 01에서 설명)를 사용해 모든 애플리케이션을 시작했다면, 이 모듈은 포트 8081에서 이미 실행 중입니다. 아래 시작 명령어를 건너뛰고 바로 http://localhost:8081 으로 이동하세요. +> **참고:** 루트 디렉토리에서 `./start-all.sh`를 사용해 모든 애플리케이션을 이미 시작했다면(Module 01에 설명된 대로), 이 모듈은 이미 포트 8081에서 실행 중입니다. 아래 시작 명령은 건너뛰고 바로 http://localhost:8081 로 이동할 수 있습니다. -**옵션 1: Spring Boot 대시보드 사용 (VS Code 사용자에 권장)** +**옵션 1: Spring Boot 대시보드 사용 (VS Code 사용자 권장)** -개발 컨테이너에는 Spring Boot 대시보드 확장 프로그램이 포함되어 있어 모든 Spring Boot 애플리케이션을 시각적으로 관리할 수 있습니다. VS Code 왼쪽 활동 바에서 Spring Boot 아이콘을 찾으세요. +개발 컨테이너에는 모든 Spring Boot 애플리케이션을 관리할 수 있는 Spring Boot 대시보드 확장 기능이 포함되어 있습니다. VS Code 왼쪽의 Activity Bar에서 Spring Boot 아이콘을 찾으세요. -Spring Boot 대시보드에서 할 수 있는 일은: -- 작업 공간 내 모든 Spring Boot 애플리케이션 보기 +Spring Boot 대시보드에서 할 수 있는 작업: +- 워크스페이스의 모든 Spring Boot 애플리케이션 보기 - 클릭 한 번으로 애플리케이션 시작/중지 -- 실시간으로 애플리케이션 로그 보기 +- 실시간 애플리케이션 로그 확인 - 애플리케이션 상태 모니터링 -"rag" 옆의 플레이 버튼을 클릭하여 이 모듈을 시작하거나 모든 모듈을 한 번에 시작할 수 있습니다. +"rag" 옆의 재생 버튼을 클릭해 이 모듈을 시작하거나 모든 모듈을 한 번에 시작할 수 있습니다. Spring Boot Dashboard -*이 스크린샷은 VS Code에서 Spring Boot 대시보드를 보여주며, 애플리케이션을 시각적으로 시작, 중지, 모니터링할 수 있습니다.* +*이 스크린샷은 VS Code에서 Spring Boot 대시보드를 보여주며, 여기서 애플리케이션을 시각적으로 시작, 중지 및 모니터링할 수 있습니다.* **옵션 2: 셸 스크립트 사용** @@ -291,7 +290,7 @@ cd .. # 루트 디렉토리에서 **PowerShell:** ```powershell -cd .. # 루트 디렉토리에서 +cd .. # 루트 디렉터리에서 .\start-all.ps1 ``` @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -두 스크립트 모두 루트 `.env` 파일에서 환경 변수를 자동으로 로드하며, JAR 파일이 없으면 빌드합니다. +두 스크립트 모두 루트 `.env` 파일에서 환경 변수를 자동으로 로드하며, JAR 파일이 없는 경우 빌드합니다. -> **참고:** 모든 모듈을 수동으로 빌드한 후 시작하고 싶다면: +> **참고:** 시작하기 전에 모든 모듈을 수동으로 빌드하려면: > > **Bash:** > ```bash @@ -345,93 +344,93 @@ cd ..; .\stop-all.ps1 # 모든 모듈 ## 애플리케이션 사용법 -이 애플리케이션은 문서 업로드와 질문을 위한 웹 인터페이스를 제공합니다. +애플리케이션은 문서 업로드와 질문을 위한 웹 인터페이스를 제공합니다. RAG Application Interface -*이 스크린샷은 문서를 업로드하고 질문할 수 있는 RAG 애플리케이션 인터페이스를 보여줍니다.* +*이 스크린샷은 문서를 업로드하고 질문하는 RAG 애플리케이션 인터페이스를 보여줍니다.* ### 문서 업로드 -우선 문서를 업로드하세요 - TXT 파일이 테스트용으로 가장 적합합니다. 이 디렉토리에는 LangChain4j 기능, RAG 구현, 모범 사례에 대한 정보를 담은 `sample-document.txt`가 제공되어 있어 시스템 테스트에 완벽합니다. +먼저 문서를 업로드하세요 - 테스트용으로는 TXT 파일이 가장 적합합니다. 이 디렉토리에 `sample-document.txt` 파일이 포함되어 있으며, LangChain4j 기능, RAG 구현, 모범 사례에 대한 정보가 들어있어 테스트에 완벽합니다. -시스템은 문서를 처리하고 청크로 분할한 후 각 청크에 임베딩을 생성합니다. 업로드하면 이 과정이 자동으로 진행됩니다. +시스템은 문서를 처리하고, 청크로 분할하며, 각 청크에 대한 임베딩을 생성합니다. 업로드 시 자동으로 수행됩니다. ### 질문하기 -이제 문서 내용에 관한 구체적인 질문을 해 보세요. 문서에 명확히 서술된 사실적 내용을 시도해 보는 것이 좋습니다. 시스템은 관련 청크를 검색하여 프롬프트에 포함시키고 답변을 생성합니다. +이제 문서 내용에 대해 구체적인 질문을 해보세요. 문서에 명확히 명시된 사실 기반 질문이 좋습니다. 시스템은 관련 청크를 검색해 프롬프트에 포함하고 답변을 생성합니다. -### 출처 확인 +### 출처 확인하기 -각 답변에는 유사도 점수가 포함된 출처 참고가 포함됩니다. 이 점수(0부터 1까지)는 각 청크가 질문과 얼마나 관련 있는지를 나타냅니다. 점수가 높을수록 더 좋은 매칭입니다. 이를 통해 답변을 원본 자료와 검증할 수 있습니다. +각 답변에는 유사도 점수가 포함된 출처 참조가 포함되어 있습니다. 이 점수(0~1)는 각 청크가 질문과 얼마나 관련성이 높은지를 보여줍니다. 점수가 높을수록 더 좋은 매칭입니다. 이를 통해 답변의 출처 자료와 대조할 수 있습니다. RAG Query Results -*이 스크린샷은 생성된 답변, 출처 참고, 검색된 각 청크의 관련성 점수를 포함한 쿼리 결과를 보여줍니다.* +*이 스크린샷은 생성된 답변, 출처 참조, 검색된 각 청크의 관련성 점수를 포함한 쿼리 결과를 보여줍니다.* -### 다양한 질문 실험하기 +### 다양한 질문 시도하기 -다양한 유형의 질문을 시도해 보세요: -- 구체적 사실: "주요 주제는 무엇인가요?" +다양한 유형의 질문을 시도해보세요: +- 구체적인 사실: "주요 주제가 무엇인가요?" - 비교: "X와 Y의 차이점은 무엇인가요?" -- 요약: "Z에 관한 핵심 내용을 요약해 주세요." +- 요약: "Z에 대한 주요 내용을 요약해 주세요." -질문이 문서 내용과 얼마나 잘 맞는지에 따라 관련성 점수가 어떻게 변하는지 확인하세요. +질문과 문서 내용의 매칭 정도에 따라 관련성 점수가 어떻게 변하는지 관찰하세요. ## 주요 개념 ### 청크 분할 전략 -문서는 300 토큰 청크로 나누며, 30 토큰씩 중첩(overlap)됩니다. 이 균형은 각 청크가 충분한 문맥을 갖도록 하면서도 프롬프트에 여러 청크를 포함할 수 있게 작은 크기를 유지합니다. +문서는 300토큰 청크로 분할되며, 30토큰이 중첩됩니다. 이 균형은 청크가 적절한 맥락을 포함하되 너무 크지 않아 프롬프트에 여러 청크를 포함할 수 있도록 합니다. ### 유사도 점수 -검색된 각 청크에는 0부터 1까지의 유사도 점수가 붙어 있으며, 이는 사용자의 질문과 얼마나 밀접한 관련이 있는지를 나타냅니다. 아래 다이어그램은 점수 범위와 시스템이 이를 어떻게 사용해 결과를 필터링하는지 시각화했습니다: +검색된 각 청크에는 0과 1 사이의 유사도 점수가 붙으며, 이는 사용자의 질문과 얼마나 밀접하게 일치하는지를 나타냅니다. 아래 다이어그램은 점수 범위와 시스템이 이를 사용해 결과를 필터링하는 방식을 시각화합니다: Similarity Scores -*이 다이어그램은 0부터 1까지 점수 범위와 0.5의 최소 임계값을 보여주며, 임계값 이하 청크는 필터링됩니다.* +*이 다이어그램은 0에서 1 범위의 점수와 0.5 이상의 최소 임계값이 어떻게 관련 없는 청크를 필터링하는지 보여줍니다.* -점수 범위: +점수 범위는 다음과 같습니다: - 0.7-1.0: 매우 관련성 높음, 정확한 매칭 -- 0.5-0.7: 관련성 있음, 좋은 문맥 -- 0.5 미만: 필터링됨, 너무 다름 +- 0.5-0.7: 관련성 있음, 양호한 문맥 +- 0.5 미만: 필터링 됨, 너무 이질적임 -시스템은 품질을 보장하기 위해 최소 임계값 이상의 청크만 검색합니다. +시스템은 품질을 보장하기 위해 최소 임계값 이상인 청크만 검색합니다. -임베딩은 의미가 명확하게 군집될 때 잘 작동하지만, 한계도 있습니다. 아래 다이어그램은 대표적인 실패 사례를 보여줍니다 — 너무 큰 청크는 뒤섞인 벡터를 만들고, 너무 작은 청크는 문맥 부족, 애매한 용어는 여러 군집을 가리키며, ID나 부품 번호 같은 정확한 매칭 조회는 임베딩과 전혀 작동하지 않습니다: +임베딩은 의미가 명확히 군집될 때 잘 작동하지만, 맹점도 존재합니다. 아래 다이어그램은 일반적인 실패 모드를 보여줍니다 — 너무 큰 청크는 흐릿한 벡터를 만들고, 너무 작은 청크는 문맥이 부족하며, 애매한 용어는 여러 군집을 가리키고, 정확 매칭 조회(ID, 부품 번호)는 임베딩에서 작동하지 않습니다: Embedding Failure Modes -*이 다이어그램은 임베딩의 흔한 실패 모드인 너무 큰 청크, 너무 작은 청크, 여러 군집을 가리키는 애매한 용어, 그리고 ID 같은 정확한 매칭 조회 문제를 보여줍니다.* +*이 다이어그램은 일반적인 임베딩 실패 모드를 보여줍니다: 청크가 너무 크거나, 너무 작거나, 여러 군집을 가리키는 애매한 용어, 그리고 ID 같은 정확 매칭 조회.* -### 메모리 내 저장소 +### 인메모리 저장소 -이 모듈은 간단하게 메모리 내 저장소만 사용합니다. 애플리케이션을 재시작하면 업로드한 문서는 사라집니다. 실제 운영 환경에서는 Qdrant나 Azure AI Search 같은 지속적 벡터 데이터베이스를 사용합니다. +이 모듈은 간단히 하기 위해 인메모리 저장소를 사용합니다. 애플리케이션을 재시작하면 업로드된 문서가 사라집니다. 실제 환경에서는 Qdrant 나 Azure AI Search 같은 영구 벡터 데이터베이스를 사용합니다. -### 컨텍스트 창 관리 +### 문맥 창 관리 -각 모델에 최대 컨텍스트 창이 있습니다. 큰 문서의 모든 청크를 포함할 수 없습니다. 시스템은 상위 N개(기본 5개)의 가장 관련 있는 청크만 검색해 제한 내에서 충분한 문맥을 제공합니다. +각 모델은 최대 문맥 창이 있습니다. 큰 문서에서 모든 청크를 포함할 수 없습니다. 시스템은 정확한 답변을 제공하면서 한도를 지키기 위해 가장 관련성 높은 상위 N개 청크(기본값 5개)만 검색합니다. ## RAG가 중요한 경우 -RAG가 항상 최선의 접근법은 아닙니다. 아래 의사 결정 가이드가 RAG가 가치를 더하는 경우와 단순히 콘텐츠를 프롬프트에 포함시키거나 모델 내장 지식을 사용하는 것이 충분한 경우를 판단하는 데 도움을 줍니다: +RAG는 항상 적합한 접근법은 아닙니다. 아래 의사결정 가이드는 RAG가 가치를 더하는 경우와, 단순히 프롬프트에 내용을 포함하거나 모델 내장 지식에 의존하는 것이 충분한 경우를 구분하는 데 도움이 됩니다: When to Use RAG -*이 다이어그램은 RAG가 가치를 더하는 경우와 단순한 접근법으로 충분한 경우를 구분하는 의사 결정 가이드를 보여줍니다.* +*이 다이어그램은 RAG가 가치를 더하는 경우와 단순한 접근법이 충분한 경우에 대한 의사결정 가이드를 보여줍니다.* ## 다음 단계 -**다음 모듈:** [04-tools - 도구를 활용한 AI 에이전트](../04-tools/README.md) +**다음 모듈:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**네비게이션:** [← 이전: 모듈 02 - 프롬프트 엔지니어링](../02-prompt-engineering/README.md) | [메인으로 돌아가기](../README.md) | [다음: 모듈 04 - 도구 →](../04-tools/README.md) +**탐색:** [← 이전: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [메인으로 돌아가기](../README.md) | [다음: Module 04 - Tools →](../04-tools/README.md) --- -**면책 조항**: -이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 노력하고 있지만, 자동 번역에는 오류나 부정확성이 포함될 수 있음을 양지해 주시기 바랍니다. 원문은 해당 언어의 원본 문서가 권위 있는 출처임을 인정해 주십시오. 중요한 정보의 경우 전문적인 인간 번역을 권장합니다. 본 번역 사용으로 인한 오해나 잘못된 해석에 대해서는 책임지지 않습니다. +**면책 조항**: +이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역은 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원본 문서의 원어본이 권위 있는 자료로 간주되어야 합니다. 중요한 정보의 경우, 전문가의 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다. \ No newline at end of file diff --git a/translations/ko/04-tools/README.md b/translations/ko/04-tools/README.md index 3e93a4a3f..e62e57a17 100644 --- a/translations/ko/04-tools/README.md +++ b/translations/ko/04-tools/README.md @@ -1,76 +1,76 @@ -# Module 04: 도구를 갖춘 AI 에이전트 +# Module 04: 도구가 있는 AI 에이전트 ## 목차 -- [비디오 워크스루](../../../04-tools) -- [학습할 내용](../../../04-tools) -- [필수 조건](../../../04-tools) -- [도구를 갖춘 AI 에이전트 이해하기](../../../04-tools) -- [도구 호출 작동 방식](../../../04-tools) - - [도구 정의](../../../04-tools) - - [의사 결정](../../../04-tools) - - [실행](../../../04-tools) - - [응답 생성](../../../04-tools) - - [아키텍처: Spring Boot 자동 연결](../../../04-tools) -- [도구 체인](../../../04-tools) -- [애플리케이션 실행](../../../04-tools) -- [애플리케이션 사용법](../../../04-tools) - - [단순 도구 사용 시도하기](../../../04-tools) - - [도구 체인 테스트하기](../../../04-tools) - - [대화 흐름 보기](../../../04-tools) - - [다양한 요청 실험하기](../../../04-tools) -- [핵심 개념](../../../04-tools) - - [ReAct 패턴 (추론과 행동)](../../../04-tools) - - [도구 설명의 중요성](../../../04-tools) - - [세션 관리](../../../04-tools) - - [오류 처리](../../../04-tools) -- [사용 가능한 도구](../../../04-tools) -- [도구 기반 에이전트 사용 시기](../../../04-tools) -- [도구와 RAG 비교](../../../04-tools) -- [다음 단계](../../../04-tools) +- [비디오 워크스루](#비디오-워크스루) +- [학습 내용](#학습-내용) +- [사전 요구 사항](#사전-요구-사항) +- [도구가 있는 AI 에이전트 이해하기](#도구가-있는-ai-에이전트-이해하기) +- [도구 호출 작동 방식](#도구-호출-작동-방식) + - [도구 정의](#도구-정의) + - [의사 결정](#의사-결정) + - [실행](#실행) + - [응답 생성](#응답-생성) + - [아키텍처: Spring Boot 자동 주입](#아키텍처-spring-boot-자동-주입) +- [도구 체이닝](#도구-체이닝) +- [애플리케이션 실행하기](#애플리케이션-실행하기) +- [애플리케이션 사용법](#애플리케이션-사용법) + - [간단한 도구 사용 시도하기](#간단한-도구-사용해보기) + - [도구 체이닝 테스트하기](#도구-연쇄-테스트) + - [대화 흐름 살펴보기](#대화-흐름-보기) + - [다양한 요청 실험하기](#다양한-요청-실험) +- [핵심 개념](#주요-개념) + - [ReAct 패턴 (추론 및 실행)](#react-패턴-추론-및-행동) + - [도구 설명의 중요성](#도구-설명의-중요성) + - [세션 관리](#세션-관리) + - [오류 처리](#오류-처리) +- [사용 가능한 도구](#사용-가능한-도구) +- [도구 기반 에이전트 사용 시기](#도구-기반-에이전트-사용-시기) +- [도구 vs RAG](#도구와-rag의-차이) +- [다음 단계](#다음-단계) ## 비디오 워크스루 이 모듈 시작 방법을 설명하는 라이브 세션을 시청하세요: -도구를 갖춘 AI 에이전트와 MCP - 라이브 세션 +도구가 있는 AI 에이전트와 MCP - 라이브 세션 -## 학습할 내용 +## 학습 내용 -지금까지 AI와 대화를 나누고, 효과적으로 프롬프트를 구조화하며, 응답을 문서 기반으로 연동하는 방법을 배웠습니다. 하지만 기본적인 한계가 있습니다: 언어 모델은 텍스트만 생성할 수 있습니다. 날씨를 확인하거나, 계산을 수행하거나, 데이터베이스를 조회하거나, 외부 시스템과 상호작용할 수 없습니다. +지금까지 AI와 대화하는 법, 효과적인 프롬프트 구조화, 문서에 기반한 응답 방법을 배웠습니다. 하지만 근본적인 한계가 있습니다: 언어 모델은 텍스트만 생성할 수 있습니다. 날씨를 확인하거나 계산을 수행하거나 데이터베이스를 쿼리하거나 외부 시스템과 상호작용할 수 없습니다. -도구가 이를 바꿉니다. 모델이 호출할 수 있는 기능에 접근 권한을 부여하면 텍스트 생성기에서 행동할 수 있는 에이전트로 변환됩니다. 모델은 언제 도구가 필요한지, 어떤 도구를 사용하고, 어떤 매개변수를 전달할지 결정합니다. 코드는 해당 함수 실행 후 결과를 반환합니다. 모델은 그 결과를 응답에 반영합니다. +도구가 이를 바꿉니다. 모델이 호출할 수 있는 기능에 접근할 수 있도록 하면, 텍스트 생성기에서 행동을 취할 수 있는 에이전트로 변합니다. 모델은 어떤 도구가 필요한지, 어떤 도구를 사용할지, 어떤 매개변수를 전달할지 결정합니다. 그리고 코드는 함수를 실행하여 결과를 반환합니다. 모델은 그 결과를 응답에 반영합니다. -## 필수 조건 +## 사전 요구 사항 -- [Module 01 - 소개](../01-introduction/README.md) 완료 (Azure OpenAI 리소스 배포됨) -- 이전 모듈 완료 권장 (이 모듈에서는 [Module 03 RAG 개념](../03-rag/README.md)을 도구와 RAG 비교 시 언급함) -- 루트 디렉터리에 Azure 자격 증명이 담긴 `.env` 파일 존재 (Module 01에서 `azd up` 명령으로 생성) +- [Module 01 - 소개](../01-introduction/README.md)를 완료 (Azure OpenAI 리소스 배포 완료) +- 이전 모듈 완료 권장 (이 모듈에서는 [Module 03의 RAG 개념](../03-rag/README.md)을 도구 vs RAG 비교에서 참조) +- 루트 디렉터리에 Azure 자격 증명이 포함된 `.env` 파일 (Module 01에서 `azd up`으로 생성됨) -> **참고:** Module 01을 완료하지 않았다면, 먼저 해당 배포 지침을 따르세요. +> **참고:** Module 01을 완료하지 않았다면, 먼저 그곳의 배포 지침을 따르세요. -## 도구를 갖춘 AI 에이전트 이해하기 +## 도구가 있는 AI 에이전트 이해하기 -> **📝 참고:** 이 모듈에서 "에이전트"란 도구 호출 기능이 향상된 AI 도우미를 의미합니다. 이는 [Module 05: MCP](../05-mcp/README.md)에서 다룰 계획인 **Agentic AI** 패턴(자율 에이전트, 계획, 메모리, 다중 단계 추론)과는 다릅니다. +> **📝 참고:** 이 모듈에서 "에이전트"라는 용어는 도구 호출 기능이 추가된 AI 보조자를 의미합니다. 이는 [Module 05: MCP](../05-mcp/README.md)에서 다룰 **Agentic AI** 패턴(계획, 기억, 다단계 추론이 포함된 자율 에이전트)과는 다릅니다. -도구가 없으면, 언어 모델은 단지 훈련 데이터에서 텍스트를 생성할 뿐입니다. 현재 날씨를 물으면 추측할 수밖에 없습니다. 도구를 주면, 날씨 API를 호출하거나, 계산을 하거나, 데이터베이스를 조회한 다음 실제 결과를 응답에 녹일 수 있습니다. +도구 없이는 언어 모델이 훈련 데이터에서 텍스트만 생성할 수 있습니다. 현재 날씨를 묻는다면 추측할 수밖에 없습니다. 도구를 주면 날씨 API 호출, 계산 수행, 데이터베이스 쿼리 등을 할 수 있고, 그 실제 결과를 응답에 통합합니다. -도구 없음 vs 도구 있음 +Without Tools vs With Tools -*도구가 없으면 모델은 추측만 하지만, 도구가 있으면 API 호출, 계산 실행, 실시간 데이터 반환이 가능합니다.* +*도구 없이는 모델이 추측만 하지만 도구를 사용하면 API 호출, 계산 실행, 실시간 데이터 제공 가능.* -도구를 갖춘 AI 에이전트는 **추론하고 행동하는 (ReAct)** 패턴을 따릅니다. 모델은 단순히 응답하는 것이 아니라, 무엇이 필요한지 생각하고, 도구를 호출해 행동하며, 결과를 관찰하고, 다시 행동할지 최종 답변을 할지 결정합니다: +도구가 있는 AI 에이전트는 **추론 및 실행(Reasoning and Acting, ReAct)** 패턴을 따릅니다. 모델은 단순히 응답하는 것이 아니라 무엇이 필요한지 생각하고, 도구를 호출하여 행동하며, 결과를 관찰한 뒤 다시 행동할지 최종 답변을 할지 결정합니다: -1. **추론** — 에이전트가 사용자 질문을 분석하고 필요한 정보를 결정 -2. **행동** — 적절한 도구를 선택하고 정확한 매개변수를 생성하여 호출 -3. **관찰** — 도구 출력 결과를 받고 평가 -4. **반복하거나 응답** — 추가 데이터가 필요하면 다시 반복, 아니면 자연어 답변 작성 +1. 추론 — 에이전트가 사용자의 질문을 분석하고 필요한 정보를 파악함 +2. 실행 — 적합한 도구를 선택, 올바른 매개변수를 생성하여 호출 +3. 관찰 — 도구 출력물을 받고 결과 평가 +4. **반복 또는 응답** — 더 많은 정보가 필요하면 반복, 아니면 자연어 답변 작성 -ReAct 패턴 +ReAct Pattern -*ReAct 사이클 — 에이전트가 무엇을 해야 할지 추론하고, 도구를 호출하며, 결과를 관찰하고, 최종 답변을 낼 때까지 반복.* +*ReAct 사이클 — 에이전트가 무엇을 할지 추론하고, 도구를 호출해 실행한 후 결과를 관찰하며 최종 답변까지 반복.* -이 과정은 자동으로 이뤄집니다. 도구와 설명을 정의하면, 모델이 언제 어떻게 사용할지 결정합니다. +이 과정은 자동으로 일어납니다. 도구와 설명을 정의하면 모델이 언제 어떻게 사용할지 결정합니다. ## 도구 호출 작동 방식 @@ -78,7 +78,7 @@ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -함수를 명확한 설명과 매개변수 명세와 함께 정의합니다. 모델은 시스템 프롬프트에서 이 설명을 보고 각 도구가 무엇을 하는지 이해합니다. +명확한 설명과 매개변수 명세를 갖춘 함수를 정의합니다. 모델은 시스템 프롬프트에서 설명을 보고 각 도구가 하는 일을 이해합니다. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // 귀하의 날씨 조회 로직 + // 날씨 조회 로직 return "Weather in " + location + ": 22°C, cloudy"; } } @@ -101,130 +101,131 @@ public interface Assistant { // - @Component 클래스의 모든 @Tool 메서드 // - 세션 관리를 위한 ChatMemoryProvider ``` + +아래 다이어그램은 각 어노테이션이 무엇을 의미하며 AI가 언제 도구를 호출하고 어떤 인수를 전달할지 이해하는 데 어떻게 도움이 되는지 보여줍니다: -아래 다이어그램은 모든 어노테이션을 분해하여 각 부분이 AI가 도구를 언제 호출하고 어떤 인자를 전달할지 이해하는 데 어떻게 도움이 되는지 보여줍니다: +도구 정의 해부 -도구 정의 구성 +*도구 정의의 구조 — @Tool은 AI에 사용할 때를 알리고, @P는 각 매개변수를 설명하며, @AiService가 시작 시 모든 것을 연결합니다.* -*도구 정의 구조 — @Tool은 AI에 도구 사용 시점을 알려주고, @P는 각 매개변수를 설명하며, @AiService는 시작 시 모두 연결합니다.* - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat으로 시도해보세요:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java)를 열고 질문해보세요: -> - "모의 데이터 대신 OpenWeatherMap 같은 실제 날씨 API를 어떻게 통합하나요?" -> - "AI가 제대로 도구를 사용하도록 돕는 좋은 도구 설명은 무엇인가요?" -> - "도구 구현 시 API 오류와 호출 제한은 어떻게 처리하나요?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat에서 시도해보세요:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java)를 열고 질문하세요: +> - "모의 데이터 대신 OpenWeatherMap과 같은 실제 날씨 API를 어떻게 통합하나요?" +> - "AI가 올바르게 도구를 사용하도록 돕는 좋은 도구 설명은 무엇인가요?" +> - "도구 구현 시 API 오류 및 호출 제한은 어떻게 처리하나요?" ### 의사 결정 -사용자가 "시애틀 날씨 어때?"라고 물으면, 모델은 무작위로 도구를 고르지 않습니다. 사용자 의도를 각 도구 설명과 비교해 관련성을 점수화한 후 가장 적합한 도구를 선택합니다. 그런 다음 구조화된 함수 호출을 생성하는데, 여기서는 `location`이 `"Seattle"`로 설정됩니다. +사용자가 "시애틀 날씨 알려줘"라고 물으면 모델이 무작위로 도구를 고르지 않습니다. 모델은 사용자 의도를 모든 도구 설명과 비교해 관련 점수를 매기고 최선의 도구를 선택합니다. 그런 다음 올바른 매개변수를 포함한 구조화된 함수 호출을 생성하며, 이 경우 `location`을 `"Seattle"`로 설정합니다. -사용자 요청에 맞는 도구가 없으면 모델은 자체 지식에서 답변합니다. 여러 도구가 매칭되면 가장 구체적인 것을 선택합니다. +어떤 도구도 요청과 일치하지 않으면 모델이 자신의 지식으로 답합니다. 여러 도구가 일치하면 가장 구체적인 도구를 선택합니다. -AI가 도구 선택하는 방법 +AI가 도구 선택하는 방식 -*모델은 사용자 의도에 대해 모든 도구를 평가하고 최적을 선택합니다 — 명확하고 구체적인 도구 설명이 중요한 이유입니다.* +*모델은 모든 도구를 사용자 의도와 비교하며 최상의 일치를 선택하기 때문에 명확하고 구체적인 도구 설명이 중요합니다.* ### 실행 [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot가 선언적인 `@AiService` 인터페이스를 모든 등록된 도구와 자동 연결하고 LangChain4j가 도구 호출을 자동 실행합니다. 내부적으로는 여섯 단계로 완전한 도구 호출 흐름이 이뤄집니다 — 사용자의 자연어 질문부터 자연어 답변까지: +Spring Boot는 선언적 `@AiService` 인터페이스를 모든 등록된 도구와 자동으로 연결하며, LangChain4j는 도구 호출을 자동으로 실행합니다. 내부적으로 완전한 도구 호출은 여섯 단계로 흐르며 — 사용자의 자연어 질문에서 최종 자연어 답변까지 진행됩니다: 도구 호출 흐름 -*엔드투엔드 흐름 — 사용자가 질문하면 모델이 도구를 선택하고, LangChain4j가 실행하며, 결과를 자연어 응답에 반영합니다.* +*종단간 플로우 — 사용자가 질문하면 모델이 도구를 선택, LangChain4j가 실행, 모델이 결과를 자연어 응답에 통합.* -Module 00의 [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java)를 실행해 봤다면 이미 이 패턴을 경험했을 겁니다 — `Calculator` 도구도 같은 방식으로 호출됩니다. 아래 시퀀스 다이어그램은 데모 중 내부에서 무슨 일이 있었는지 보여줍니다: +내부적으로 `AiServices`는 여기 단순한 `Calculator` 예제로 모든 도구 호출 루프를 실행합니다. 아래 시퀀스 다이어그램은 내부에서 정확히 어떤 일이 일어나는지 보여줍니다: 도구 호출 시퀀스 다이어그램 -*퀵 스타트 데모의 도구 호출 루프 — `AiServices`가 메시지와 도구 스키마를 LLM에 보내고, LLM이 `add(42, 58)` 같은 함수 호출로 응답하며 LangChain4j가 로컬에서 `Calculator` 메서드를 실행하고 결과를 최종 답변으로 다시 전달.* +*도구 호출 루프 — `AiServices`가 메시지와 도구 스키마를 LLM에 보내면 LLM이 `add(42, 58)`과 같은 함수 호출을 응답하고, LangChain4j가 `Calculator` 메서드를 로컬에서 실행 후 결과를 마지막 응답을 위해 다시 전달.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat으로 시도해보세요:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java)를 열어 질문해보세요: -> - "ReAct 패턴은 어떻게 작동하고 왜 AI 에이전트에 효과적인가요?" -> - "에이전트는 어떤 도구를 언제, 어떤 순서로 결정하나요?" -> - "도구 실행 실패 시 어떻게 처리해야 하나요, 오류 관리를 견고하게 하려면?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat에서 시도해보세요:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java)를 열고 질문하세요: +> - "ReAct 패턴은 어떻게 작동하며 AI 에이전트에 왜 효과적인가요?" +> - "에이전트가 어떤 도구를 어떤 순서로 사용할지 어떻게 결정하나요?" +> - "도구 실행 실패 시 어떻게 오류를 견고하게 처리해야 하나요?" ### 응답 생성 -모델은 날씨 데이터를 받아 사용자에게 자연어로 정리된 응답을 작성합니다. +모델은 날씨 데이터를 받아 사용자를 위한 자연어 응답으로 형식을 만듭니다. -### 아키텍처: Spring Boot 자동 연결 +### 아키텍처: Spring Boot 자동 주입 -이 모듈은 LangChain4j의 Spring Boot 통합과 선언적 `@AiService` 인터페이스를 사용합니다. 시작 시 Spring Boot가 `@Tool` 메서드를 가진 모든 `@Component`, `ChatModel` 빈, `ChatMemoryProvider`를 찾아 한 개의 `Assistant` 인터페이스로 모두 연결합니다. 보일러플레이트 코드가 전혀 없습니다. +이 모듈은 LangChain4j의 Spring Boot 연동을 사용하며 선언적 `@AiService` 인터페이스를 적용합니다. 시작 시 Spring Boot는 `@Tool` 메서드가 포함된 모든 `@Component`, `ChatModel` 빈, `ChatMemoryProvider`를 탐색하여 모두를 하나의 `Assistant` 인터페이스로 연결합니다. 별도의 보일러플레이트 없이 완료됩니다. -Spring Boot 자동 연결 아키텍처 +Spring Boot 자동 주입 아키텍처 -*@AiService 인터페이스가 ChatModel, 도구 컴포넌트, 메모리 프로바이더를 하나로 연결 — Spring Boot가 모든 연결을 자동으로 처리.* +*@AiService 인터페이스가 ChatModel, 도구 컴포넌트, 메모리 제공자를 연결 — Spring Boot가 모든 연결을 자동으로 처리.* -전체 요청 수명 주기를 나타내는 시퀀스 다이어그램입니다 — HTTP 요청에서 컨트롤러, 서비스, 자동 연결된 프록시를 거쳐 도구 실행 및 결과 반환까지: +전체 요청 수명주기를 시퀀스 다이어그램으로 표현하면 아래와 같습니다 — HTTP 요청에서 컨트롤러, 서비스, 자동 주입 프록시, 도구 실행 및 응답까지 모두 포함: Spring Boot 도구 호출 시퀀스 -*완벽한 Spring Boot 요청 수명 주기 — HTTP 요청이 컨트롤러와 서비스를 거쳐 자동 연결된 Assistant 프록시로 흘러 들어가 LLM과 도구 호출을 자동으로 조율합니다.* +*Spring Boot의 완전한 요청 라이프사이클 — HTTP 요청이 컨트롤러 및 서비스를 거쳐 자동 주입된 Assistant 프록시로 흐르고, LLM과 도구 호출을 자동으로 조율.* -이 접근법의 주요 이점: +이 접근법의 주요 장점: -- **Spring Boot 자동 연결** — ChatModel과 도구가 자동 주입됨 -- **@MemoryId 패턴** — 자동 세션 기반 메모리 관리 -- **단일 인스턴스** — Assistant를 한 번 생성해 성능 향상 -- **타입 안전 실행** — Java 메서드를 타입 변환과 함께 직접 호출 -- **다중 회차 조율** — 도구 체인을 자동으로 처리 -- **제로 보일러플레이트** — 수동 `AiServices.builder()` 호출이나 메모리 HashMap 불필요 +- **Spring Boot 자동 주입** — ChatModel과 도구가 자동으로 삽입됨 +- **@MemoryId 패턴** — 자동 세션 기반 메모리 관리 +- **단일 인스턴스** — Assistant가 한 번 생성되어 재사용으로 성능 향상 +- **타입 안전 실행** — 자바 메서드를 타입 변환과 함께 직접 호출 +- **다중 턴 오케스트레이션** — 도구 체이닝 자동 처리 +- **보일러플레이트 없음** — 수동 `AiServices.builder()` 호출이나 메모리 해시맵 불필요 -수동 `AiServices.builder()` 방식은 더 많은 코드가 필요하고 Spring Boot 통합의 이점을 활용하지 못합니다. +수동 `AiServices.builder()` 사용 같은 대체 방법은 코드가 더 많고 Spring Boot 연동 장점이 부족합니다. -## 도구 체인 +## 도구 체이닝 -**도구 체인** — 단일 질문에 여러 도구가 필요한 경우 도구 기반 에이전트의 진정한 힘이 드러납니다. "시애틀의 화씨 온도는?" 이라고 물으면 에이전트는 두 도구를 자동 체인합니다: 먼저 `getCurrentWeather`를 호출해 섭씨 온도를 받고, 그 값을 `celsiusToFahrenheit`에 전달해 변환합니다 — 모든 과정을 한 회차 대화에서 처리합니다. +**도구 체이닝** — 도구 기반 에이전트의 진정한 힘은 단일 질문에 여러 도구가 동시에 필요할 때 발휘됩니다. 예를 들어 "시애틀의 화씨 기준 날씨는?"이라 묻는다면 에이전트는 자동으로 두 개 도구를 체이닝합니다: 먼저 `getCurrentWeather`를 호출해 섭씨 온도를 받아오고, 그 값을 `celsiusToFahrenheit`로 전달해 화씨로 변환합니다 — 모두 한 대화 턴 안에서 진행됩니다. -도구 체인 예시 +도구 체이닝 예제 -*도구 체인 동작 — 에이전트가 먼저 getCurrentWeather를 호출하고, 섭씨 결과를 celsiusToFahrenheit에 전달해 결합된 답변을 제공합니다.* +*도구 체이닝 동작 — 에이전트가 먼저 getCurrentWeather를 호출하고, 섭씨 결과를 celsiusToFahrenheit에 연결해 결합된 답변을 전달.* -**우아한 실패 처리** — 모의 데이터에 없는 도시의 날씨를 요청하면, 도구는 오류 메시지를 반환하고 AI는 도와줄 수 없다고 설명하는 방식으로 충돌 없이 대응합니다. 안전하게 실패합니다. 아래 다이어그램은 두 방식을 대비합니다 — 적절한 오류 처리 시 에이전트가 예외를 잡아 유용한 응답을 하며, 그렇지 않으면 전체 앱이 충돌합니다: +**우아한 실패 처리** — 모의 데이터에 없는 도시의 날씨를 요청하면 도구가 오류 메시지를 반환하고 AI가 도움을 줄 수 없음을 설명하면서 크래시하지 않습니다. 도구는 안전하게 실패합니다. 아래 다이어그램은 두 방식을 대비합니다 — 적절한 오류 처리 시 에이전트가 예외를 잡아 유용한 설명으로 응답하지만, 그렇지 않으면 애플리케이션 전체가 중단됨: 오류 처리 흐름 -*도구 실패 시 에이전트가 오류를 잡아 충돌 없이 도움 설명 응답을 반환합니다.* +*도구 실패 시 에이전트가 오류를 잡아 충돌 대신 도움 되는 설명을 응답.* -모든 과정은 단일 대화 회차에서 이뤄집니다. 에이전트가 여러 도구 호출을 자율적으로 조율합니다. +모든 과정이 한 번의 대화 턴 내에서 일어나며, 에이전트가 여러 도구 호출을 자율적으로 조율합니다. -## 애플리케이션 실행 +## 애플리케이션 실행하기 -**배포 검증:** +**배포 확인:** -루트 디렉터리에 Azure 자격 증명 `.env` 파일이 있는지 확인하세요 (Module 01에서 생성됨). 모듈 디렉터리(`04-tools/`)에서 다음을 실행합니다: +루트 디렉터리에 Azure 자격 증명이 포함된 `.env` 파일이 있는지 확인하세요 (Module 01에서 생성됨). 모듈 디렉터리(`04-tools/`)에서 다음을 실행: -**Bash:** +**Bash:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 표시해야 합니다 ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT를 보여줘야 합니다 +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT을(를) 보여야 합니다 ``` - + **애플리케이션 시작:** -> **참고:** 이미 루트 디렉터리에서 `./start-all.sh`로 모든 애플리케이션을 시작했다면 (Module 01 설명 참조), 이 모듈은 8084 포트에서 실행 중입니다. 아래 시작 명령은 건너뛰고 바로 http://localhost:8084 접속해도 됩니다. +> **참고:** 만약 이미 루트 디렉터리에서 `./start-all.sh`로 모든 애플리케이션을 시작했다면(Module 01에 설명), 이 모듈은 포트 8084에서 실행 중입니다. 아래 시작 명령은 건너뛰고 http://localhost:8084 로 바로 접속해도 됩니다. + +**옵션 1: Spring Boot 대시보드 사용 (VS Code 사용자 추천)** -**옵션 1: Spring Boot 대시보드 사용하기 (VS Code 사용자 권장)** +개발 컨테이너는 Spring Boot 대시보드 확장 기능이 포함되어 있어 모든 Spring Boot 애플리케이션을 시각적으로 관리할 수 있습니다. VS Code 좌측 활동 표시줄에서 스프링 부트 아이콘을 찾아 실행하세요. -개발 컨테이너에는 Spring Boot 대시보드 확장 기능이 포함되어 있어 모든 Spring Boot 애플리케이션을 시각적으로 관리할 수 있습니다. VS Code 왼쪽 액티비티 바에서 Spring Boot 아이콘을 찾으면 됩니다. +Spring Boot 대시보드에서 할 수 있는 작업: -Spring Boot 대시보드에서는: -- 작업 영역 내 모든 Spring Boot 애플리케이션 목록 확인 -- 클릭 한 번으로 애플리케이션 시작/중지 -- 실시간 애플리케이션 로그 보기 -- 애플리케이션 상태 모니터링 -도구 옆에 있는 재생 버튼을 클릭하여 이 모듈을 시작하거나 모든 모듈을 한 번에 시작하세요. +- 워크스페이스 내 모든 Spring Boot 애플리케이션 확인 +- 버튼 클릭으로 애플리케이션 시작/중지 +- 실시간 로그 보기 +- 애플리케이션 상태 모니터링 -VS Code에서 Spring Boot 대시보드가 어떻게 보이는지 다음과 같습니다: +"tools" 옆의 재생 버튼을 클릭하면 이 모듈이 시작되고, 원하는 경우 모든 모듈을 동시에 시작할 수도 있습니다. -Spring Boot Dashboard +VS Code에서 Spring Boot 대시보드는 다음과 같이 표시됩니다: +Spring Boot 대시보드 -*VS Code의 Spring Boot 대시보드 — 한 곳에서 모든 모듈을 시작, 중지 및 모니터링* +*VS Code의 Spring Boot 대시보드 — 한 곳에서 모든 모듈을 시작, 중지 및 모니터링하세요* **옵션 2: 셸 스크립트 사용** @@ -238,7 +239,7 @@ cd .. # 루트 디렉터리에서 **PowerShell:** ```powershell -cd .. # 루트 디렉토리에서 +cd .. # 루트 디렉토리에서부터 .\start-all.ps1 ``` @@ -256,7 +257,7 @@ cd 04-tools .\start.ps1 ``` -두 스크립트 모두 루트 `.env` 파일에서 환경 변수를 자동으로 로드하며, JAR 파일이 없으면 빌드합니다. +두 스크립트 모두 루트 `.env` 파일에서 환경 변수를 자동으로 로드하며 존재하지 않는 경우 JAR 파일을 빌드합니다. > **참고:** 시작 전에 모든 모듈을 수동으로 빌드하려면: > @@ -272,7 +273,7 @@ cd 04-tools > mvn clean package -DskipTests > ``` -브라우저에서 http://localhost:8084 를 엽니다. +브라우저에서 http://localhost:8084 를 여세요. **중지하려면:** @@ -290,87 +291,86 @@ cd .. && ./stop-all.sh # 모든 모듈 cd ..; .\stop-all.ps1 # 모든 모듈 ``` +## 애플리케이션 사용법 -## 애플리케이션 사용하기 - -이 애플리케이션은 날씨 및 온도 변환 도구에 접근할 수 있는 AI 에이전트와 상호작용할 수 있는 웹 인터페이스를 제공합니다. 인터페이스는 다음과 같으며, 빠른 시작 예제와 요청을 보낼 수 있는 채팅 패널이 포함되어 있습니다: +애플리케이션은 날씨 및 온도 변환 도구에 접근할 수 있는 AI 에이전트와 상호작용할 수 있는 웹 인터페이스를 제공합니다. 인터페이스는 다음과 같습니다 — 빠른 시작 예제와 요청을 보낼 수 있는 채팅 패널이 포함되어 있습니다: -AI Agent Tools Interface +AI 에이전트 도구 인터페이스 -*AI 에이전트 도구 인터페이스 - 도구와 상호작용하기 위한 빠른 예제 및 채팅 인터페이스* +*AI 에이전트 도구 인터페이스 - 빠른 예제와 도구와 상호작용할 수 있는 채팅 인터페이스* ### 간단한 도구 사용해보기 -간단한 요청으로 시작해보세요: "100도 화씨를 섭씨로 변환해줘". 에이전트는 온도 변환 도구가 필요함을 인지하고 올바른 매개변수로 호출하여 결과를 반환합니다. 어느 도구를 사용할지 지정하지 않아도 자연스레 작동하는 것을 확인할 수 있습니다. +간단한 요청부터 시작하세요: "100도 화씨를 섭씨로 변환해줘". 에이전트는 온도 변환 도구가 필요함을 인식하고 올바른 매개변수로 호출하여 결과를 반환합니다. 어떤 도구를 사용하거나 호출 방법을 지정하지 않았음에도 자연스럽게 작동하는 점을 확인하세요. -### 도구 체인 사용해보기 +### 도구 연쇄 테스트 -이번에는 좀 더 복잡한 요청을 시도해보세요: "시애틀 날씨가 어때? 그리고 화씨로 변환해줘." 에이전트가 단계별로 작업하는 과정을 볼 수 있습니다. 먼저 날씨 정보를 얻고(섭씨로 반환), 화씨로 변환해야 함을 인지하고 변환 도구를 호출하여 두 결과를 하나의 응답으로 결합합니다. +더 복잡한 시도를 해보세요: "시애틀의 날씨는 어떻고 화씨로 변환해줘?" 에이전트가 단계를 거쳐 작업하는 모습을 지켜보세요. 먼저 날씨 데이터를 가져오고(섭씨 반환), 화씨로 변환해야 함을 인식하여 변환 도구를 호출한 뒤 두 결과를 합쳐 응답합니다. -### 대화 흐름 확인하기 +### 대화 흐름 보기 -채팅 인터페이스는 대화 기록을 유지하여 다중 턴 상호작용이 가능합니다. 이전 문의와 응답을 모두 볼 수 있어 대화를 추적하고 에이전트가 여러 교환을 통해 문맥을 어떻게 구축하는지 쉽게 이해할 수 있습니다. +채팅 인터페이스는 대화 기록을 유지하여 다중 턴 상호작용이 가능합니다. 이전 쿼리와 응답을 모두 확인할 수 있어 대화 추적 및 에이전트가 여러 교환을 통해 어떻게 맥락을 구축하는지 이해하기 쉽습니다. -Conversation with Multiple Tool Calls +다중 도구 호출과의 대화 -*간단한 변환, 날씨 조회, 도구 체인으로 이루어진 다중 턴 대화 예시* +*간단한 변환, 날씨 조회, 도구 연쇄를 보여주는 다중 턴 대화* -### 다양한 요청 시도해보기 +### 다양한 요청 실험 -다양한 조합을 시도해 보세요: -- 날씨 조회: "도쿄 날씨가 어때?" +다양한 조합을 시도해보세요: +- 날씨 조회: "도쿄 날씨 어때?" - 온도 변환: "25°C는 켈빈으로 얼마야?" -- 복합 쿼리: "파리 날씨 확인하고 20°C 이상인지 알려줘" +- 결합 쿼리: "파리 날씨 확인하고 20°C 이상인지 알려줘" -에이전트가 자연어를 해석해 적절한 도구 호출로 매핑하는 방식을 확인할 수 있습니다. +에이전트가 자연어를 해석하고 적절한 도구 호출로 매핑하는 방식을 확인하세요. ## 주요 개념 -### ReAct 패턴 (추론과 실행) +### ReAct 패턴 (추론 및 행동) -에이전트는 추론(무엇을 할지 결정)과 실행(도구 사용)을 번갈아 수행합니다. 이 패턴은 단순 명령 응답이 아니라 자율적 문제 해결을 가능하게 합니다. +에이전트는 추론(무엇을 할지 결정)과 행동(도구 사용)을 번갈아 수행합니다. 이 패턴은 단순 지시 응답이 아닌 자율적 문제 해결을 가능하게 합니다. -### 도구 설명이 중요함 +### 도구 설명의 중요성 -도구 설명의 품질이 에이전트가 도구를 얼마나 잘 사용하는지를 직접 결정합니다. 명확하고 구체적인 설명이 모델이 언제, 어떻게 각 도구를 호출할지 이해하는 데 도움이 됩니다. +도구 설명의 품질은 에이전트가 도구를 얼마나 잘 사용하는지에 직접 영향을 미칩니다. 명확하고 구체적인 설명은 모델이 언제 어떻게 도구를 호출할지 이해하는 데 도움을 줍니다. ### 세션 관리 -`@MemoryId` 어노테이션은 자동 세션 기반 메모리 관리를 가능하게 합니다. 각 세션 ID마다 `ChatMemory` 인스턴스가 `ChatMemoryProvider` 빈에 의해 관리되어 여러 사용자가 대화를 섞지 않고 독립적으로 상호작용할 수 있습니다. 아래 그림은 여러 사용자가 자신의 세션 ID에 따라 격리된 메모리 저장소로 라우팅되는 과정을 보여줍니다: +`@MemoryId` 주석은 자동 세션 기반 메모리 관리를 가능하게 합니다. 각 세션 ID마다 `ChatMemory` 인스턴스가 `ChatMemoryProvider` 빈에 의해 관리되어 여러 사용자가 동시에 다른 대화 내역을 볼 수 없습니다. 다음 다이어그램은 세션 ID에 따라 격리된 메모리 저장소로 여러 사용자를 라우팅하는 방식을 보여줍니다: -Session Management with @MemoryId +@MemoryId를 이용한 세션 관리 -*각 세션 ID는 격리된 대화 기록에 매핑되어, 사용자의 메시지가 서로 보이지 않습니다.* +*각 세션 ID는 격리된 대화 기록으로 매핑되어 사용자는 서로의 메시지를 볼 수 없습니다.* ### 오류 처리 -도구는 실패할 수 있습니다 — API 타임아웃, 잘못된 매개변수, 외부 서비스 장애 등. 운영 환경에서는 모델이 문제를 설명하거나 대안을 시도할 수 있도록 오류 처리가 필요합니다. 도구가 예외를 던지면 LangChain4j가 이를 잡아 모델에 오류 메시지를 피드백하며, 모델은 자연어로 문제를 설명할 수 있습니다. +도구는 실패할 수 있습니다 — API 타임아웃, 잘못된 매개변수, 외부 서비스 중단 등. 프로덕션 환경의 에이전트는 오류 처리가 필요하여 모델이 문제를 설명하거나 대안을 시도할 수 있어야 합니다. 도구가 예외를 던지면 LangChain4j가 이를 포착해 오류 메시지를 모델에 전달하고, 모델이 자연어로 문제를 설명할 수 있습니다. ## 사용 가능한 도구 -아래 다이어그램은 구축할 수 있는 다양한 도구 생태계를 보여줍니다. 이 모듈은 날씨 및 온도 도구를 보여주지만 같은 `@Tool` 패턴은 데이터베이스 쿼리부터 결제 처리까지 모든 Java 메서드에 적용할 수 있습니다. +아래 다이어그램은 구축 가능한 도구의 광범위한 생태계를 보여줍니다. 이 모듈은 날씨 및 온도 도구를 시연하지만, 동일한 `@Tool` 패턴은 데이터베이스 쿼리부터 결제 처리까지 모든 Java 메서드에 적용됩니다. -Tool Ecosystem +도구 생태계 -*@Tool 어노테이션이 적용된 모든 Java 메서드는 AI에 의해 사용 가능해지며, 이 패턴은 데이터베이스, API, 이메일, 파일 작업 등으로 확장됩니다.* +*@Tool로 주석 처리된 모든 Java 메서드는 AI에서 사용할 수 있습니다 — 이 패턴은 데이터베이스, API, 이메일, 파일 작업 등으로 확장됩니다.* ## 도구 기반 에이전트 사용 시기 -모든 요청에 도구가 필요한 것은 아닙니다. AI가 외부 시스템과 상호작용해야 하는지, 아니면 자체 지식으로 응답할 수 있는지의 문제입니다. 다음 가이드는 도구가 가치가 있을 때와 불필요할 때를 요약합니다: +모든 요청에 도구가 필요한 것은 아닙니다. AI가 외부 시스템과 상호작용해야 하는지, 자체 지식으로 답변할 수 있는지에 따라 결정됩니다. 다음 가이드는 도구가 가치를 더하는 경우와 불필요한 경우를 요약합니다: -When to Use Tools +도구 사용 시기 -*빠른 결정 가이드 — 도구는 실시간 데이터, 계산, 작업에 사용되며 일반 지식이나 창의적 작업에는 필요하지 않습니다.* +*간단 의사 결정 가이드 — 도구는 실시간 데이터, 계산 및 작업용; 일반 지식과 창의적 작업은 필요하지 않습니다.* -## 도구 vs RAG +## 도구와 RAG의 차이 -모듈 03과 04는 AI의 기능을 확장하지만 근본적으로 다른 방식입니다. RAG는 문서 검색을 통해 모델에 **지식** 접근을 허용합니다. 도구는 함수 호출을 통해 모델에 **행동** 수행 능력을 부여합니다. 아래 그림은 두 접근법을 나란히 비교하며 각 워크플로우와 장단점도 보여줍니다: +모듈 03과 04는 AI가 할 수 있는 일을 확장하지만 근본적으로 다른 방식입니다. RAG는 문서 검색을 통해 모델에 지식을 제공합니다. 도구는 기능 호출을 통해 모델에 작업 수행 능력을 부여합니다. 아래 다이어그램은 두 접근 방식을 나란히 비교합니다 — 워크플로우 운영 방식부터 장단점까지: -Tools vs RAG Comparison +도구 vs RAG 비교 -*RAG는 정적 문서에서 정보를 검색하고 — 도구는 작업을 실행하며 동적, 실시간 데이터를 가져옵니다. 많은 운영 시스템은 두 방식을 결합합니다.* +*RAG는 정적 문서에서 정보를 검색 — 도구는 동적 실시간 데이터를 가져오거나 작업을 실행합니다. 많은 프로덕션 시스템은 두 방법을 모두 사용합니다.* -실제로 많은 운영 시스템은 두 방식을 결합해 사용합니다: RAG는 문서 기반 근거 제공용, 도구는 실시간 데이터 획득 및 작업 수행용입니다. +실제로 많은 프로덕션 시스템은 두 접근법을 함께 사용합니다: 문서 기반 답변 근거에는 RAG를, 라이브 데이터 조회나 작업 수행에는 도구를 사용합니다. ## 다음 단계 @@ -378,11 +378,11 @@ cd ..; .\stop-all.ps1 # 모든 모듈 --- -**탐색:** [← 이전: 모듈 03 - RAG](../03-rag/README.md) | [메인으로 돌아가기](../README.md) | [다음: 모듈 05 - MCP →](../05-mcp/README.md) +**내비게이션:** [← 이전: 모듈 03 - RAG](../03-rag/README.md) | [메인으로 돌아가기](../README.md) | [다음: 모듈 05 - MCP →](../05-mcp/README.md) --- -**면책 조항**: -이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 노력하고 있으나 자동 번역에는 오류나 부정확한 내용이 포함될 수 있음을 알려드립니다. 원문은 해당 언어의 원본 문서를 권위 있는 자료로 간주해야 합니다. 중요한 정보의 경우 전문 인간 번역을 권장합니다. 이 번역의 사용으로 인해 발생하는 어떠한 오해나 잘못된 해석에 대해서도 당사는 책임을 지지 않습니다. +**면책 조항**: +이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역은 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원본 문서의 원어본이 권위 있는 자료로 간주되어야 합니다. 중요한 정보의 경우, 전문가의 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다. \ No newline at end of file diff --git a/translations/ko/README.md b/translations/ko/README.md index b75ab364c..ef572753b 100644 --- a/translations/ko/README.md +++ b/translations/ko/README.md @@ -1,19 +1,19 @@ LangChain4j -# 초보자를 위한 LangChain4j +# LangChain4j 초보자용 -기본 챗봇부터 AI 에이전트까지, LangChain4j와 Azure OpenAI GPT-5.2로 AI 애플리케이션을 구축하는 과정입니다. +LangChain4j와 Azure OpenAI GPT-5.2를 사용하여 기본 채팅부터 AI 에이전트까지 AI 애플리케이션을 구축하는 과정입니다. ### 🌐 다국어 지원 -#### GitHub Action을 통한 지원 (자동화 및 항상 최신 상태 유지) +#### GitHub Action을 통해 지원 (자동화 및 항상 최신 상태 유지) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](./README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **로컬에 복제하시겠습니까?** +> **로컬로 클론하는 것을 선호하나요?** > -> 이 저장소는 50개 이상의 언어 번역을 포함하고 있어 다운로드 크기가 크게 증가합니다. 번역 없이 복제하려면 sparse checkout을 사용하세요: +> 이 저장소에는 50개 이상의 언어 번역이 포함되어 있어 다운로드 크기가 크게 증가합니다. 번역 없이 클론하려면 희소 체크아웃을 사용하세요: > > **Bash / macOS / Linux:** > ```bash @@ -29,82 +29,81 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> 이 방법으로 훨씬 빠른 다운로드로 과정에 필요한 모든 것을 받을 수 있습니다. +> 이 방법으로 훨씬 빠른 다운로드로 코스를 완료하는 데 필요한 모든 것을 얻을 수 있습니다. ## 목차 -1. [빠른 시작](00-quick-start/README.md) - LangChain4j 시작하기 -2. [소개](01-introduction/README.md) - LangChain4j 기본 개념 배우기 -3. [프롬프트 엔지니어링](02-prompt-engineering/README.md) - 효과적인 프롬프트 디자인 마스터하기 -4. [RAG (검색 기반 생성)](03-rag/README.md) - 지능형 지식 기반 시스템 구축하기 -5. [도구](04-tools/README.md) - 외부 도구 및 간단한 어시스턴트 통합하기 -6. [MCP (모델 컨텍스트 프로토콜)](05-mcp/README.md) - 모델 컨텍스트 프로토콜(MCP) 및 에이전틱 모듈 다루기 +1. [소개](01-introduction/README.md) - LangChain4j 기본 개념 배우기 +2. [프롬프트 엔지니어링](02-prompt-engineering/README.md) - 효과적인 프롬프트 설계 마스터하기 +3. [RAG (검색 기반 생성)](03-rag/README.md) - 지능형 지식 기반 시스템 구축 +4. [도구](04-tools/README.md) - 외부 도구와 간단한 어시스턴트 통합 +5. [MCP (모델 컨텍스트 프로토콜)](05-mcp/README.md) - MCP와 에이전틱 모듈 사용하기 -### 비디오 안내 +### 비디오 워크스루 -각 모듈에는 개념과 코드를 단계별로 안내하는 라이브 세션이 포함되어 있습니다. +각 모듈에는 개념과 코드를 단계별로 안내하는 라이브 세션이 함께 제공됩니다. | 모듈 | 비디오 | |--------|-------| | 01 - 소개 | [LangChain4j 시작하기](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - 프롬프트 엔지니어링 | [LangChain4j로 프롬프트 엔지니어링](https://www.youtube.com/live/PJ6aBaE6bog) | +| 02 - 프롬프트 엔지니어링 | [LangChain4j에서의 프롬프트 엔지니어링](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [LangChain4j와 함께하는 RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - 도구 & 05 - MCP | [도구와 MCP를 활용한 AI 에이전트](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - 도구 & 05 - MCP | [도구 및 MCP를 활용한 AI 에이전트](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## 학습 경로 -**LangChain4j가 처음이신가요?** 주요 용어나 개념에 대한 정의는 [용어집](docs/GLOSSARY.md)을 참고하세요. +**LangChain4j를 처음 접하나요?** 주요 용어와 개념 정의는 [용어집](docs/GLOSSARY.md)을 참고하세요. > **빠른 시작** -1. 이 저장소를 본인의 GitHub 계정으로 포크하세요 -2. **Code** → **Codespaces** 탭 → **...** → 옵션 선택 새 코드스페이스 만들기를 클릭하세요 -3. 기본값을 사용하세요 – 이 과정용으로 만들어진 개발 컨테이너가 선택됩니다 -4. 코드스페이스 생성을 클릭하세요 -5. 환경이 준비될 때까지 5~10분 기다리세요 -6. 바로 [빠른 시작](./00-quick-start/README.md)으로 이동해 시작하세요! +1. 이 저장소를 GitHub 계정에 포크합니다. +2. **Code** → **Codespaces** 탭 → **...** → **옵션과 함께 새로 만들기...** 클릭 +3. 기본값 사용 – 이 과정에 맞게 만들어진 개발 컨테이너가 선택됩니다. +4. **코드스페이스 만들기** 클릭 +5. 환경 준비까지 5-10분 기다리기 +6. 바로 [소개](./01-introduction/README.md)로 이동해 시작하세요! -모듈을 완료한 후, LangChain4j 테스트 개념을 실제로 확인하려면 [테스트 가이드](docs/TESTING.md)를 살펴보세요. +모듈을 완료하면 [테스트 가이드](docs/TESTING.md)를 통해 LangChain4j 테스트 개념을 직접 확인해 보세요. -> **참고:** 이 교육 과정은 GitHub 모델과 Azure OpenAI를 모두 사용합니다. [빠른 시작](00-quick-start/README.md) 모듈은 GitHub 모델을 사용하며(별도의 Azure 구독 불필요), 1~5 모듈은 Azure OpenAI를 사용합니다. 계정이 없으시면 [무료 Azure 계정](https://aka.ms/azure-free-account)으로 시작하세요. +> **참고:** 본 교육은 Azure OpenAI를 사용합니다. 아직 계정이 없으면 [무료 Azure 계정](https://aka.ms/azure-free-account)으로 시작하세요. -## GitHub Copilot과 함께하는 학습 +## GitHub Copilot과 함께 배우기 -프로그래밍을 빠르게 시작하려면 GitHub Codespace나 제공된 devcontainer를 통해 이 프로젝트를 로컬 IDE에서 열어보세요. 이 과정에서 사용하는 devcontainer는 AI 페어 프로그래밍을 위한 GitHub Copilot이 미리 구성되어 있습니다. +빠르게 코딩을 시작하려면 GitHub Codespace 또는 제공된 devcontainer를 사용하여 이 프로젝트를 로컬 IDE에서 여세요. 이 과정에서 사용되는 devcontainer는 AI 페어 프로그래밍을 위한 GitHub Copilot이 사전 구성되어 있습니다. -예제 코드마다 GitHub Copilot에게 묻는 추천 질문이 포함되어 있어 이해도를 높일 수 있습니다. 💡/🤖 프롬프트는 다음 위치에서 확인하세요: +각 코드 예제에는 GitHub Copilot에게 물어볼 수 있는 추천 질문이 포함되어 있어 이해를 깊게 할 수 있습니다. 💡/🤖 프롬프트는 다음 위치에서 찾으세요: -- **Java 파일 헤더** - 각 예제별 구체적인 질문 -- **모듈 README** - 코드 예제 뒤 탐색용 질문 +- **Java 파일 헤더** - 각 예제별 구체적 질문 +- **모듈 README** - 코드 예제 후 탐색을 위한 질문 -**사용법:** 어떤 코드 파일이라도 열고 추천 질문을 Copilot에게 물어보세요. 전체 코드베이스를 맥락으로 이해하고, 설명하거나 확장 및 대안 제시가 가능합니다. +**사용 방법:** 코드 파일을 열고 추천 질문을 Copilot에게 물어보세요. Copilot은 코드베이스 전체를 파악하고 있어 설명, 확장 및 대안 제시가 가능합니다. -더 자세히 알고 싶다면, [AI 페어 프로그래밍을 위한 Copilot](https://aka.ms/GitHubCopilotAI)을 참고하세요. +더 배우고 싶나요? [AI 페어 프로그래밍용 Copilot](https://aka.ms/GitHubCopilotAI)을 확인하세요. ## 추가 자료 ### LangChain -[![초보자를 위한 LangChain4j](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![초보자를 위한 LangChain.js](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![초보자를 위한 LangChain](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j 초보자용](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js 초보자용](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain 초보자용](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / 에이전트 -[![초보자를 위한 AZD](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![초보자를 위한 Edge AI](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![초보자를 위한 MCP](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![초보자를 위한 AI 에이전트](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Agents +[![AZD 초보자용](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI 초보자용](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP 초보자용](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI 에이전트 초보자용](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### 생성 AI 시리즈 -[![초보자를 위한 생성 AI](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![생성 AI 초보자용](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![생성 AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![생성 AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) [![생성 AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) @@ -112,10 +111,11 @@ --- ### 핵심 학습 -[![초보자를 위한 ML](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![초보자를 위한 데이터 과학](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![초보자를 위한 AI](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![초보자를 위한 사이버보안](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![ML 초보자용](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![데이터 과학 초보자용](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI 초보자용](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![사이버보안 초보자용](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + [![초보자를 위한 웹 개발](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![초보자를 위한 IoT](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![초보자를 위한 XR 개발](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -123,28 +123,28 @@ --- ### Copilot 시리즈 -[![AI 페어 프로그래밍용 Copilot](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![AI 페어 프로그래밍을 위한 Copilot](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![C#/.NET용 Copilot](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![Copilot 어드벤처](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## 도움말 받기 +## 도움 받기 -AI 앱 개발 중 막히거나 질문이 있을 경우, 다음에 참여하세요: +AI 앱 구축 중 막히거나 질문이 있으면 다음에 참여하세요: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -제품 피드백이나 빌드 중 오류가 있으면 방문하세요: +제품 피드백이나 빌드 중 오류가 있으면 다음을 방문하세요: -[![Microsoft Foundry 개발자 포럼](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) +[![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## 라이선스 -MIT 라이선스 - 자세한 내용은 [LICENSE](../../LICENSE) 파일을 참고하세요. +MIT 라이선스 - 자세한 내용은 [LICENSE](../../LICENSE) 파일을 참조하세요. --- -**면책 조항**: -이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 노력하고 있으나, 자동 번역에는 오류나 부정확성이 포함될 수 있음을 유의하시기 바랍니다. 원본 문서의 원어본이 권위 있는 출처로 간주되어야 합니다. 중요한 정보에 대해서는 전문적인 인력에 의한 번역을 권장합니다. 이 번역의 사용으로 발생하는 오해나 오해석에 대해 당사는 책임을 지지 않습니다. +**면책 조항**: +이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역은 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원본 문서의 원어본이 권위 있는 자료로 간주되어야 합니다. 중요한 정보의 경우, 전문가의 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다. \ No newline at end of file diff --git a/translations/ko/docs/GLOSSARY.md b/translations/ko/docs/GLOSSARY.md index ded7329fb..8efcfd460 100644 --- a/translations/ko/docs/GLOSSARY.md +++ b/translations/ko/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## 목차 -- [핵심 개념](../../../docs) -- [LangChain4j 구성 요소](../../../docs) -- [AI/ML 개념](../../../docs) -- [가드레일](../../../docs) -- [프롬프트 엔지니어링](../../../docs) -- [RAG (검색 증강 생성)](../../../docs) -- [에이전트 및 도구](../../../docs) -- [에이전틱 모듈](../../../docs) -- [모델 컨텍스트 프로토콜 (MCP)](../../../docs) -- [Azure 서비스](../../../docs) -- [테스팅 및 개발](../../../docs) - -과정 전반에서 사용되는 용어 및 개념에 대한 빠른 참조입니다. +- [핵심 개념](#핵심-개념) +- [LangChain4j 구성 요소](#langchain4j-구성-요소) +- [AI/ML 개념](#aiml-개념) +- [가드레일](#가드레일) +- [프롬프트 엔지니어링](#prompt-engineering---module-02) +- [RAG (검색 증강 생성)](#rag-retrieval-augmented-generation---module-03) +- [에이전트 및 도구](#agents-and-tools---module-04) +- [에이전틱 모듈](#agentic-module---module-05) +- [모델 컨텍스트 프로토콜 (MCP)](#model-context-protocol-mcp---module-05) +- [Azure 서비스](#azure-services---module-01) +- [테스트 및 개발](#testing-and-development---testing-guide) + +과정 전반에서 사용되는 용어 및 개념에 대한 빠른 참고. ## 핵심 개념 -**AI 에이전트** - AI를 사용하여 자율적으로 추론하고 행동하는 시스템. [모듈 04](../04-tools/README.md) +**AI 에이전트** - AI를 사용해 자율적으로 추론하고 행동하는 시스템. [모듈 04](../04-tools/README.md) -**체인** - 출력이 다음 단계 입력으로 이어지는 작업 순서. +체인 - 출력이 다음 단계로 연결되는 일련의 작업. -**청킹** - 문서를 더 작은 조각으로 분할. 일반적으로 300-500 토큰과 중첩 포함. [모듈 03](../03-rag/README.md) +**청킹(Chunking)** - 문서를 작은 조각으로 나누기. 일반적으로 300-500 토큰, 중첩 포함. [모듈 03](../03-rag/README.md) -**컨텍스트 윈도우** - 모델이 처리 가능한 최대 토큰 수. GPT-5.2: 400K 토큰 (최대 272K 입력, 128K 출력). +**컨텍스트 윈도우** - 모델이 처리할 수 있는 최대 토큰 수. GPT-5.2: 400K 토큰 (입력 최대 272K, 출력 128K). -**임베딩** - 텍스트 의미를 표현하는 수치 벡터. [모듈 03](../03-rag/README.md) +**임베딩(Embeddings)** - 텍스트 의미를 수치 벡터로 표현. [모듈 03](../03-rag/README.md) -**함수 호출** - 모델이 외부 함수를 호출하기 위한 구조화된 요청 생성. [모듈 04](../04-tools/README.md) +**함수 호출(Function Calling)** - 모델이 외부 함수를 호출하기 위한 구조화된 요청 생성. [모듈 04](../04-tools/README.md) -**환각** - 모델이 그럴듯하지만 잘못된 정보를 생성하는 현상. +**환각(Hallucination)** - 모델이 그럴듯하지만 잘못된 정보를 생성하는 현상. -**프롬프트** - 언어 모델에 입력하는 텍스트. [모듈 02](../02-prompt-engineering/README.md) +**프롬프트(Prompt)** - 언어 모델에 입력하는 텍스트. [모듈 02](../02-prompt-engineering/README.md) -**시맨틱 검색** - 키워드가 아닌 의미를 사용한 검색. 임베딩 활용. [모듈 03](../03-rag/README.md) +**의미 검색(Semantic Search)** - 키워드 대신 임베딩을 사용하여 의미로 검색. [모듈 03](../03-rag/README.md) -**상태 저장 대 무상태** - 무상태: 메모리 없음. 상태 저장: 대화 기록 유지. [모듈 01](../01-introduction/README.md) +**상태 유지 vs 상태 비유지(Stateful vs Stateless)** - 상태 비유지: 메모리 없음. 상태 유지: 대화 기록 유지. [모듈 01](../01-introduction/README.md) -**토큰** - 모델이 처리하는 기본 텍스트 단위. 비용 및 한도에 영향. [모듈 01](../01-introduction/README.md) +**토큰(Tokens)** - 모델이 처리하는 기본 텍스트 단위. 비용과 한도에 영향. [모듈 01](../01-introduction/README.md) -**도구 체인** - 출력이 다음 호출에 반영되는 연속적인 도구 실행. [모듈 04](../04-tools/README.md) +**도구 연결(Tool Chaining)** - 출력이 다음 호출에 영향을 주는 도구의 순차 실행. [모듈 04](../04-tools/README.md) ## LangChain4j 구성 요소 -**AiServices** - 유형 안전 AI 서비스 인터페이스 생성. +**AiServices** - 타입 안전 AI 서비스 인터페이스 생성. -**OpenAiOfficialChatModel** - OpenAI 및 Azure OpenAI 모델을 위한 통합 클라이언트. +**OpenAiOfficialChatModel** - OpenAI와 Azure OpenAI 모델을 위한 통합 클라이언트. -**OpenAiOfficialEmbeddingModel** - OpenAI Official 클라이언트를 사용해 임베딩 생성 (OpenAI와 Azure OpenAI 모두 지원). +**OpenAiOfficialEmbeddingModel** - OpenAI 공식 클라이언트를 사용해 임베딩 생성 (OpenAI 및 Azure OpenAI 지원). -**ChatModel** - 언어 모델의 핵심 인터페이스. +**ChatModel** - 언어 모델의 핵심 인터페이스. -**ChatMemory** - 대화 기록 유지. +**ChatMemory** - 대화 기록 유지. -**ContentRetriever** - RAG를 위한 관련 문서 청크 검색. +**ContentRetriever** - RAG용 관련 문서 조각 검색. -**DocumentSplitter** - 문서 청크로 분할. +**DocumentSplitter** - 문서를 청크로 분할. -**EmbeddingModel** - 텍스트를 수치 벡터로 변환. +**EmbeddingModel** - 텍스트를 수치 벡터로 변환. -**EmbeddingStore** - 임베딩 저장 및 검색. +**EmbeddingStore** - 임베딩 저장 및 조회. -**MessageWindowChatMemory** - 최근 메시지의 슬라이딩 윈도우 유지. +**MessageWindowChatMemory** - 최근 메시지에 대한 슬라이딩 윈도우 유지. -**PromptTemplate** - `{{variable}}` 자리표시자를 포함한 재사용 가능한 프롬프트 생성. +**PromptTemplate** - `{{variable}}` 자리표시자가 있는 재사용 가능한 프롬프트 생성. -**TextSegment** - 메타데이터가 포함된 텍스트 청크. RAG에서 사용. +**TextSegment** - 메타데이터가 포함된 텍스트 청크. RAG에서 사용. -**ToolExecutionRequest** - 도구 실행 요청 표현. +**ToolExecutionRequest** - 도구 실행 요청을 나타냄. -**UserMessage / AiMessage / SystemMessage** - 대화 메시지 유형. +**UserMessage / AiMessage / SystemMessage** - 대화 메시지 유형. ## AI/ML 개념 -**Few-Shot 학습** - 프롬프트에 예시를 제공. [모듈 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - 프롬프트에 예제를 제공하는 학습법. [모듈 02](../02-prompt-engineering/README.md) -**대형 언어 모델(LLM)** - 방대한 텍스트 데이터로 훈련된 AI 모델. +**대형 언어 모델 (LLM)** - 방대한 텍스트 데이터로 훈련된 AI 모델. -**추론 강도** - GPT-5.2의 사고 깊이 조절 매개변수. [모듈 02](../02-prompt-engineering/README.md) +**추론 노력(Reasoning Effort)** - GPT-5.2의 사고 심도 조절 파라미터. [모듈 02](../02-prompt-engineering/README.md) -**온도** - 출력의 무작위성 조절. 낮음=결정적, 높음=창의적. +**온도(Temperature)** - 출력의 무작위성 조절. 낮음=결정적, 높음=창의적. -**벡터 데이터베이스** - 임베딩에 특화된 데이터베이스. [모듈 03](../03-rag/README.md) +**벡터 데이터베이스(Vector Database)** - 임베딩을 위한 특화 데이터베이스. [모듈 03](../03-rag/README.md) -**Zero-Shot 학습** - 예시 없이 작업 수행. [모듈 02](../02-prompt-engineering/README.md) +**제로샷 학습(Zero-Shot Learning)** - 예제 없이 작업 수행. [모듈 02](../02-prompt-engineering/README.md) -## 가드레일 - [모듈 00](../00-quick-start/README.md) +## 가드레일 -**Defense in Depth** - 애플리케이션 수준 가드레일과 공급자 안전 필터를 결합한 다중 계층 보안 접근법. +**Deep Defense(Defense in Depth)** - 애플리케이션 수준 가드레일과 공급자 안전 필터를 결합한 다중 보안 계층. -**Hard Block** - 심각한 콘텐츠 위반에 대해 공급자가 HTTP 400 오류 반환. +**하드 블록(Hard Block)** - 심각한 콘텐츠 위반 시 공급자가 HTTP 400 오류를 반환. -**InputGuardrail** - LLM에 도달하기 전 사용자 입력을 검증하는 LangChain4j 인터페이스. 유해한 프롬프트 조기 차단으로 비용과 지연 절감. +**InputGuardrail** - LLM에 도달하기 전에 사용자 입력을 검증하는 LangChain4j 인터페이스. 해로운 프롬프트를 조기에 차단해 비용과 지연 감소. -**InputGuardrailResult** - 가드레일 검증 반환형: `success()` 또는 `fatal("사유")`. +**InputGuardrailResult** - 가드레일 검증 반환 타입: `success()` 또는 `fatal("reason")`. -**OutputGuardrail** - AI 응답을 사용자에게 반환하기 전에 검증하는 인터페이스. +**OutputGuardrail** - 사용자에게 전달하기 전 AI 응답을 검증하는 인터페이스. -**공급자 안전 필터** - API 수준에서 위반사항을 탐지하는 AI 공급자 내장 콘텐츠 필터(예: GitHub Models). +**공급자 안전 필터(Provider Safety Filters)** - AI 공급자(예: Azure OpenAI)의 API 수준 내장 콘텐츠 필터. -**Soft Refusal** - 오류 없이 정중히 답변 거절. +**소프트 거부(Soft Refusal)** - 모델이 오류 없이 정중하게 응답을 거절함. ## 프롬프트 엔지니어링 - [모듈 02](../02-prompt-engineering/README.md) -**체인 오브 쏘트(Chain-of-Thought)** - 더 나은 정확도를 위한 단계별 추론. +**생각의 연쇄(Chain-of-Thought)** - 더 나은 정확도를 위한 단계별 추론. -**제한된 출력** - 특정 형식 또는 구조 강제 적용. +**제약된 출력(Constrained Output)** - 특정 형식 또는 구조 강제 적용. -**높은 열의도(High Eagerness)** - 철저한 추론을 위한 GPT-5.2 패턴. +**높은 열의(High Eagerness)** - 철저한 추론용 GPT-5.2 패턴. -**낮은 열의도(Low Eagerness)** - 빠른 답변을 위한 GPT-5.2 패턴. +**낮은 열의(Low Eagerness)** - 빠른 답변용 GPT-5.2 패턴. -**다중 회차 대화** - 교환 간 컨텍스트 유지. +**다중 대화(Multi-Turn Conversation)** - 교환 간 컨텍스트 유지. -**역할 기반 프롬프트** - 시스템 메시지를 통해 모델 페르소나 설정. +**역할 기반 프롬프트(Role-Based Prompting)** - 시스템 메시지를 통한 모델 페르소나 설정. -**자기 성찰** - 모델이 결과물을 평가하고 개선. +**자기 성찰(Self-Reflection)** - 모델이 출력 평가 및 개선. -**구조화 분석** - 고정된 평가 프레임워크. +**구조화 분석(Structured Analysis)** - 고정 평가 프레임워크. -**작업 실행 패턴** - 계획 → 실행 → 요약. +**작업 실행 패턴(Task Execution Pattern)** - 계획 → 실행 → 요약. ## RAG (검색 증강 생성) - [모듈 03](../03-rag/README.md) -**문서 처리 파이프라인** - 로드 → 청크 → 임베딩 → 저장. +**문서 처리 파이프라인** - 로드 → 청크 분할 → 임베딩 → 저장. -**인메모리 임베딩 저장소** - 테스트용 비영속 저장소. +**인메모리 임베딩 저장소** - 테스트용 비영속 저장소. -**RAG** - 검색과 생성을 결합해 응답 근거 제공. +**RAG** - 검색과 생성을 결합하여 응답에 근거 제공. -**유사도 점수** - 의미적 유사도 (0-1) 측정. +**유사도 점수(Similarity Score)** - 의미적 유사성의 0-1 척도. -**출처 참조** - 검색된 콘텐츠 메타데이터. +**출처 참조(Source Reference)** - 검색된 콘텐츠에 대한 메타데이터. ## 에이전트 및 도구 - [모듈 04](../04-tools/README.md) -**@Tool 어노테이션** - 자바 메서드를 AI 호출 가능 도구로 표시. +**@Tool 애노테이션** - Java 메서드를 AI 호출 도구로 표시. -**ReAct 패턴** - 추론 → 행동 → 관찰 → 반복. +**ReAct 패턴** - 추론 → 행동 → 관찰 → 반복. -**세션 관리** - 사용자별 별도 컨텍스트. +**세션 관리(Session Management)** - 사용자 별 별도 컨텍스트 유지. -**도구** - AI 에이전트가 호출할 수 있는 함수. +**도구(Tool)** - AI 에이전트가 호출할 수 있는 함수. -**도구 설명** - 도구 목적 및 매개변수 문서화. +**도구 설명(Tool Description)** - 도구 목적 및 매개변수 문서화. ## 에이전틱 모듈 - [모듈 05](../05-mcp/README.md) -**@Agent 어노테이션** - 선언적 행동 정의가 있는 AI 에이전트 인터페이스 표시. +**@Agent 애노테이션** - 선언적 행위 정의가 가능한 AI 에이전트 인터페이스 표시. -**Agent Listener** - `beforeAgentInvocation()` 및 `afterAgentInvocation()`을 통한 에이전트 실행 모니터링 훅. +**에이전트 리스너(Agent Listener)** - `beforeAgentInvocation()`, `afterAgentInvocation()`을 통한 에이전트 실행 모니터링 훅. -**에이전틱 범위** - 에이전트가 출력물을 `outputKey`를 사용해 저장, 이후 에이전트가 소비하는 공유 메모리. +**에이전틱 스코프(Agentic Scope)** - 에이전트가 결과를 저장하는 공유 메모리, 하류 에이전트가 소비. -**AgenticServices** - `agentBuilder()`와 `supervisorBuilder()`를 사용해 에이전트 생성하는 팩토리. +**AgenticServices** - `agentBuilder()`, `supervisorBuilder()`를 통한 에이전트 생성용 팩토리. -**조건부 워크플로우** - 조건에 따라 다른 전문 에이전트로 경로 분기. +**조건 워크플로우(Conditional Workflow)** - 조건에 따라 다른 전문 에이전트로 분기. -**Human-in-the-Loop** - 승인 또는 콘텐츠 검토를 위한 인간 검증 단계가 추가된 워크플로우 패턴. +**휴먼-인-더-루프(Human-in-the-Loop)** - 승인 또는 콘텐츠 검토를 위한 인간 관문이 포함된 워크플로우 패턴. -**langchain4j-agentic** - 선언적 에이전트 빌딩용 메이븐 의존성(실험적). +**langchain4j-agentic** - 선언적 에이전트 빌딩용 Maven 의존성(실험적). -**루프 워크플로우** - 조건 충족 시까지 에이전트 실행 반복 (예: 품질 점수 ≥ 0.8). +**루프 워크플로우(Loop Workflow)** - 품질 점수 ≥ 0.8 등 조건 만족 시까지 에이전트 실행 반복. -**outputKey** - 에이전트 어노테이션 매개변수로, 결과가 에이전틱 범위의 어디에 저장되는지 지정. +**outputKey** - 에이전트 애노테이션 매개변수로 결과가 저장되는 에이전틱 스코프 위치 지정. -**병렬 워크플로우** - 독립 작업을 위해 여러 에이전트를 동시에 실행. +**병렬 워크플로우(Parallel Workflow)** - 독립 작업을 위한 다중 에이전트 동시 실행. -**응답 전략** - 감독자가 최종 답변 작성 방법: LAST, SUMMARY, 또는 SCORED. +**응답 전략(Response Strategy)** - 관리자가 최종 답변을 구성하는 방식: LAST, SUMMARY, SCORED. -**순차 워크플로우** - 에이전트를 순서대로 실행하며 출력이 다음 단계로 흐름. +**순차 워크플로우(Sequential Workflow)** - 출력이 다음 단계로 흐르는 순차적 에이전트 실행. -**감독 에이전트 패턴** - 감독 LLM이 동적으로 어떤 하위 에이전트를 호출할지 결정하는 고급 에이전틱 패턴. +**관리자 에이전트 패턴(Supervisor Agent Pattern)** - 감독 LLM이 하위 에이전트를 동적으로 호출하는 고급 에이전틱 패턴. ## 모델 컨텍스트 프로토콜 (MCP) - [모듈 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j에서 MCP 통합을 위한 메이븐 의존성. +**langchain4j-mcp** - LangChain4j의 MCP 통합용 Maven 의존성. -**MCP** - Model Context Protocol: AI 앱과 외부 도구 연결을 위한 표준. 한 번 구축해 어디서나 사용. +**MCP** - 모델 컨텍스트 프로토콜: AI 앱과 외부 도구 연결을 위한 표준. 한 번 구축하면 어디서나 사용 가능. -**MCP 클라이언트** - MCP 서버에 연결해 도구를 탐색하고 사용하는 애플리케이션. +**MCP 클라이언트(Client)** - MCP 서버에 연결해 도구를 발견하고 사용하는 애플리케이션. -**MCP 서버** - 명확한 설명과 매개변수 스키마를 통해 도구를 MCP로 제공하는 서비스. +**MCP 서버(Server)** - 명확한 설명과 매개변수 스키마를 갖춘 MCP 도구를 노출하는 서비스. -**McpToolProvider** - AI 서비스와 에이전트에서 사용할 수 있도록 MCP 도구를 래핑하는 LangChain4j 구성 요소. +**McpToolProvider** - AI 서비스 및 에이전트용 MCP 도구를 래핑하는 LangChain4j 구성 요소. -**McpTransport** - MCP 통신 인터페이스. 구현체로 Stdio 및 HTTP 포함. +**McpTransport** - MCP 통신 인터페이스. 구현체는 Stdio 및 HTTP 포함. -**Stdio 전송** - stdin/stdout을 통한 로컬 프로세스 전송. 파일 시스템 접근 또는 명령줄 도구에 유용. +**Stdio Transport** - stdin/stdout을 사용하는 로컬 프로세스 통신. 파일시스템 접근이나 명령행 도구용. -**StdioMcpTransport** - MCP 서버를 서브프로세스로 실행하는 LangChain4j 구현체. +**StdioMcpTransport** - MCP 서버를 하위 프로세스로 실행하는 LangChain4j 구현체. -**도구 탐색** - 클라이언트가 서버에 사용 가능한 도구들의 설명과 스키마 요청. +**도구 검색(Tool Discovery)** - 클라이언트가 설명 및 스키마가 포함된 사용 가능한 도구를 서버에 질의. ## Azure 서비스 - [모듈 01](../01-introduction/README.md) -**Azure AI Search** - 벡터 기능을 갖춘 클라우드 검색. [모듈 03](../03-rag/README.md) +**Azure AI Search** - 벡터 기능을 갖춘 클라우드 검색. [모듈 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Azure 리소스 배포 도구. +**Azure Developer CLI (azd)** - Azure 리소스 배포 도구. -**Azure OpenAI** - 마이크로소프트의 엔터프라이즈 AI 서비스. +**Azure OpenAI** - 마이크로소프트의 엔터프라이즈 AI 서비스. -**Bicep** - Azure 인프라스트럭처 코드 언어. [인프라 가이드](../01-introduction/infra/README.md) +**Bicep** - Azure 인프라 코드 언어. [인프라 가이드](../01-introduction/infra/README.md) -**배포 이름** - Azure에서 모델 배포명. +**배포 이름(Deployment Name)** - Azure에서 모델 배포 이름. -**GPT-5.2** - 추론 조절 기능이 있는 최신 OpenAI 모델. [모듈 02](../02-prompt-engineering/README.md) +**GPT-5.2** - 추론 제어 기능을 갖춘 최신 OpenAI 모델. [모듈 02](../02-prompt-engineering/README.md) -## 테스팅 및 개발 - [테스트 가이드](TESTING.md) +## 테스트 및 개발 - [테스트 가이드](TESTING.md) -**Dev Container** - 컨테이너화된 개발 환경. [구성](../../../.devcontainer/devcontainer.json) +**개발 컨테이너(Dev Container)** - 컨테이너화된 개발 환경. [구성](../../../.devcontainer/devcontainer.json) -**GitHub Models** - 무료 AI 모델 플레이그라운드. [모듈 00](../00-quick-start/README.md) +**인메모리 테스트(In-Memory Testing)** - 인메모리 저장소를 이용한 테스트. -**인메모리 테스팅** - 인메모리 저장소를 활용한 테스트. +**통합 테스트(Integration Testing)** - 실제 인프라 환경에서의 테스트. -**통합 테스트** - 실제 인프라와 연동하는 테스트. +**Maven** - Java 빌드 자동화 도구. -**Maven** - 자바 빌드 자동화 도구. +**Mockito** - Java 모킹 프레임워크. -**Mockito** - 자바 모킹 프레임워크. - -**Spring Boot** - 자바 애플리케이션 프레임워크. [모듈 01](../01-introduction/README.md) +**Spring Boot** - Java 애플리케이션 프레임워크. [모듈 01](../01-introduction/README.md) --- -**면책 조항**: -이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 최선을 다하고 있으나, 자동 번역에는 오류나 부정확한 점이 있을 수 있음을 양지해 주시기 바랍니다. 원문은 해당 언어의 원본 문서를 권위 있는 출처로 간주해야 합니다. 중요한 정보의 경우, 전문적인 인간 번역을 권장합니다. 본 번역물의 사용으로 인해 발생하는 모든 오해나 오해에 대해서는 당사가 책임지지 않습니다. +**면책 조항**: +이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역은 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원본 문서의 원어본이 권위 있는 자료로 간주되어야 합니다. 중요한 정보의 경우, 전문가의 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다. \ No newline at end of file diff --git a/translations/ko/docs/TESTING.md b/translations/ko/docs/TESTING.md index 5b2727e88..e98e8abbb 100644 --- a/translations/ko/docs/TESTING.md +++ b/translations/ko/docs/TESTING.md @@ -2,19 +2,19 @@ ## 목차 -- [빠른 시작](../../../docs) -- [테스트 범위](../../../docs) -- [테스트 실행하기](../../../docs) -- [VS Code에서 테스트 실행하기](../../../docs) -- [테스트 패턴](../../../docs) -- [테스트 철학](../../../docs) -- [다음 단계](../../../docs) +- [빠른 시작](#빠른-시작) +- [테스트 범위](#테스트-범위) +- [테스트 실행](#테스트-실행) +- [VS Code에서 테스트 실행](#vs-code에서-테스트-실행) +- [테스트 패턴](#테스트-패턴) +- [테스트 철학](#테스트-철학) +- [다음 단계](#다음-단계) -이 가이드는 API 키나 외부 서비스 없이 AI 애플리케이션을 테스트하는 방법을 보여주는 테스트들을 안내합니다. +이 가이드는 API 키나 외부 서비스를 요구하지 않고 AI 애플리케이션을 테스트하는 방법을 보여주는 테스트를 안내합니다. ## 빠른 시작 -단일 명령어로 모든 테스트를 실행하세요: +한 번의 명령으로 모든 테스트를 실행하세요: **Bash:** ```bash @@ -26,30 +26,29 @@ mvn test mvn --% test ``` -모든 테스트가 통과하면 아래 스크린샷과 같은 출력이 나타납니다 — 테스트가 하나도 실패하지 않고 실행됩니다. +모든 테스트가 통과하면 아래 스크린샷과 같은 출력이 나타납니다 — 실패 없이 테스트가 실행됩니다. Successful Test Results -*모든 테스트가 실패 없이 성공적으로 실행된 사례* +*모든 테스트가 실패 없이 성공적으로 실행된 결과* ## 테스트 범위 -이 과정은 로컬에서 실행되는 **단위 테스트**에 초점을 맞춥니다. 각 테스트는 고립된 상태에서 특정 LangChain4j 개념을 보여줍니다. 아래 테스트 피라미드는 단위 테스트가 어디에 속하는지 보여줍니다 — 단위 테스트는 나머지 테스트 전략이 구축되는 빠르고 신뢰할 수 있는 기반을 형성합니다. +이 과정은 로컬에서 실행되는 **단위 테스트(unit test)** 에 집중합니다. 각 테스트는 LangChain4j의 특정 개념을 독립적으로 보여줍니다. 아래 테스트 피라미드는 단위 테스트가 어디에 위치하는지 보여줍니다 — 빠르고 신뢰할 수 있는 기초로서 나머지 테스트 전략이 구축됩니다. Testing Pyramid -*단위 테스트(빠르고 고립됨), 통합 테스트(실제 컴포넌트), 그리고 엔드투엔드 테스트 간 균형을 보여주는 테스트 피라미드. 이 교육은 단위 테스트를 다룹니다.* +*단위 테스트(빠르고 독립적), 통합 테스트(실제 컴포넌트), 엔드 투 엔드 테스트 간의 균형을 보여주는 테스트 피라미드. 이 훈련은 단위 테스트를 다룹니다.* -| 모듈 | 테스트 수 | 중점 | 주요 파일 | +| 모듈 | 테스트 수 | 집중 내용 | 주요 파일 | |--------|-------|-------|-----------| -| **00 - 빠른 시작** | 6 | 프롬프트 템플릿 및 변수 대체 | `SimpleQuickStartTest.java` | -| **01 - 소개** | 8 | 대화 메모리 및 상태 유지 채팅 | `SimpleConversationTest.java` | -| **02 - 프롬프트 엔지니어링** | 12 | GPT-5.2 패턴, 열의 수준, 구조화된 출력 | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | 문서 입력, 임베딩, 유사도 검색 | `DocumentServiceTest.java` | -| **04 - 도구** | 12 | 함수 호출 및 도구 체이닝 | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Stdio 전송방식의 모델 컨텍스트 프로토콜 | `SimpleMcpTest.java` | +| **01 - 소개** | 8 | 대화 메모리 및 상태 기반 채팅 | `SimpleConversationTest.java` | +| **02 - 프롬프트 엔지니어링** | 12 | GPT-5.2 패턴, eagerness 레벨, 구조화된 출력 | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | 문서 수집, 임베딩, 유사도 검색 | `DocumentServiceTest.java` | +| **04 - 툴** | 12 | 함수 호출 및 도구 체인 | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Stdio 전송을 사용하는 모델 컨텍스트 프로토콜 | `SimpleMcpTest.java` | -## 테스트 실행하기 +## 테스트 실행 **루트에서 모든 테스트 실행:** @@ -63,12 +62,12 @@ mvn test mvn --% test ``` -**특정 모듈의 테스트 실행:** +**특정 모듈 테스트 실행:** **Bash:** ```bash cd 01-introduction && mvn test -# 루트에서 또는 +# 또는 루트에서부터 mvn test -pl 01-introduction ``` @@ -95,41 +94,41 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#대화 기록을 유지해야 합니다 +mvn test -Dtest=SimpleConversationTest#대화 기록을 유지해야 함 ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#대화 기록을 유지해야 합니다 +mvn --% test -Dtest=SimpleConversationTest#대화 기록을 유지해야 함 ``` -## VS Code에서 테스트 실행하기 +## VS Code에서 테스트 실행 -Visual Studio Code를 사용하는 경우, 테스트 탐색기는 테스트를 실행하고 디버그할 수 있는 그래픽 인터페이스를 제공합니다. +Visual Studio Code를 사용한다면, Test Explorer가 테스트 실행과 디버깅을 위한 그래픽 인터페이스를 제공합니다. VS Code Test Explorer -*모든 자바 테스트 클래스와 개별 테스트 메서드를 보여주는 VS Code 테스트 탐색기* +*모든 Java 테스트 클래스와 개별 테스트 메서드가 표시된 VS Code Test Explorer* -**VS Code에서 테스트를 실행하려면:** +**VS Code에서 테스트 실행 방법:** -1. 활동 표시줄에서 플라스크 아이콘을 클릭하여 테스트 탐색기를 엽니다. -2. 테스트 트리를 확장해 모든 모듈과 테스트 클래스를 확인합니다. -3. 임의의 테스트 옆의 실행 버튼을 클릭해 개별 실행합니다. -4. "모든 테스트 실행"을 클릭해 전체 테스트를 실행합니다. -5. 임의의 테스트에서 마우스 오른쪽 버튼을 클릭 후 "테스트 디버그"를 선택해 중단점을 설정하고 코드 단계를 밟아갈 수 있습니다. +1. 활동 표시줄의 비커 아이콘을 클릭하여 Test Explorer를 엽니다 +2. 테스트 트리를 확장하여 모든 모듈과 테스트 클래스를 봅니다 +3. 개별 테스트를 실행하려면 원하는 테스트 옆의 실행 버튼을 클릭합니다 +4. 전체 테스트 스위트를 실행하려면 "Run All Tests"를 클릭합니다 +5. 원하는 테스트를 우클릭하고 "Debug Test"를 선택하여 중단점을 설정하고 단계 실행할 수 있습니다 -테스트 탐색기는 통과한 테스트에는 녹색 체크표시를, 실패한 테스트에는 자세한 실패 메시지를 제공합니다. +Test Explorer는 테스트가 통과하면 녹색 체크표시를 보여주고, 실패 시 상세 실패 메시지를 제공합니다. ## 테스트 패턴 ### 패턴 1: 프롬프트 템플릿 테스트 -가장 단순한 패턴으로, AI 모델을 호출하지 않고 프롬프트 템플릿을 테스트합니다. 변수 대체가 올바르게 작동하는지, 프롬프트가 예상대로 형식화되는지 확인합니다. +가장 단순한 패턴으로, AI 모델을 호출하지 않고 프롬프트 템플릿을 테스트합니다. 변수 치환이 올바르게 작동하는지와 프롬프트 포맷이 예상대로인지 검증합니다. Prompt Template Testing -*프롬프트 템플릿 테스트: 플레이스홀더가 있는 템플릿 → 값 적용 → 포맷된 출력 확인 흐름* +*플레이스홀더가 포함된 템플릿 → 값 적용 → 포맷된 출력 검증의 변수 치환 흐름을 보여주는 프롬프트 템플릿 테스트* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -이 테스트는 `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`에 위치합니다. - -**실행 방법:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#테스트프롬프트템플릿포맷팅 -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#테스트프롬프트템플릿포매팅 -``` +이 패턴은 변수 치환이 올바로 작동하고 프롬프트가 예상대로 포맷되는지를 검증합니다 — API 키나 모델 호출은 필요하지 않습니다. -### 패턴 2: 언어 모델 모킹 +### 패턴 2: 언어 모델 모킹(Mock) -대화 로직 테스트 시 Mockito를 사용해 미리 정해진 응답을 반환하는 가짜 모델을 만듭니다. 이렇게 하면 테스트가 빠르고 무료이며 결정론적입니다. +대화 로직을 테스트할 때는 Mockito를 사용해 미리 정해진 응답을 반환하는 가짜 모델을 만드세요. 이를 통해 테스트는 빠르고, 무료이며, 결정적입니다. Mock vs Real API Comparison -*테스트에 모킹이 선호되는 이유 비교: 빠르고, 무료이며, 결정론적이고, API 키가 필요 없음* +*모킹이 테스트에 선호되는 이유 — 빠르고, 무료, 결정적이며 API 키 불필요함* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -이 패턴은 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`에 나타납니다. 모킹은 일관된 동작을 보장해 메모리 관리가 올바르게 작동하는지 검증합니다. +이 패턴은 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`에서 확인할 수 있습니다. 모킹은 일관된 동작을 보장하여 메모리 관리를 정확히 검증할 수 있습니다. -### 패턴 3: 대화 고립성 테스트 +### 패턴 3: 대화 격리 테스트 -대화 메모리는 여러 사용자를 분리해야 합니다. 이 테스트는 대화가 컨텍스트를 섞지 않는지 확인합니다. +대화 메모리는 여러 사용자를 분리해야 합니다. 이 테스트는 대화가 서로 섞이지 않는지를 검증합니다. Conversation Isolation -*대화 고립성 테스트: 서로 다른 사용자용 독립 메모리 저장소로 컨텍스트 혼합 방지* +*서로 다른 사용자의 별도 메모리 저장소를 보여주어 컨텍스트 혼합을 방지하는 대화 격리 테스트* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -각 대화는 독립된 히스토리를 유지합니다. 운영 환경에서는 이 고립성이 다중 사용자 애플리케이션에 매우 중요합니다. +각 대화는 독립적인 기록을 유지합니다. 운영 환경에서는 멀티유저 애플리케이션에 이 격리가 필수적입니다. ### 패턴 4: 도구 독립 테스트 -도구는 AI가 호출할 수 있는 함수들입니다. AI 결정과 관계없이 도구가 올바르게 작동하는지 직접 테스트합니다. +도구는 AI가 호출할 수 있는 함수입니다. AI 결정과 상관없이 도구가 정상 작동하는지 직접 테스트하세요. Tools Testing -*도구 독립 테스트: AI 호출 없이 모킹 도구 실행으로 비즈니스 로직 검증* +*AI 호출 없이 모킹된 도구 실행으로 비즈니스 로직을 검증하는 도구 독립 테스트* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -이 테스트들은 `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`에서 AI 개입 없이 도구 로직을 검증합니다. 체이닝 예제는 한 도구의 출력이 다른 도구 입력으로 어떻게 이어지는지 보여줍니다. +`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`에서 나온 이 테스트들은 AI 개입 없이 도구 로직을 검증합니다. 체인 예시에서는 하나 도구의 출력이 다른 도구의 입력으로 연결되는 것을 보여줍니다. ### 패턴 5: 인메모리 RAG 테스트 -RAG 시스템은 보통 벡터 데이터베이스와 임베딩 서비스가 필요합니다. 인메모리 패턴을 사용하면 외부 의존성 없이 파이프라인 전체를 테스트할 수 있습니다. +RAG 시스템은 전통적으로 벡터 데이터베이스와 임베딩 서비스를 요구합니다. 인메모리 패턴은 외부 의존성 없이 전체 파이프라인을 테스트할 수 있도록 합니다. In-Memory RAG Testing -*인메모리 RAG 테스트 워크플로우: 데이터베이스 없이 문서 파싱, 임베딩 저장, 유사도 검색* +*데이터베이스 없이 문서 파싱, 임베딩 저장, 유사도 검색을 보여주는 인메모리 RAG 테스트 워크플로우* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -이 테스트는 `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`에서 메모리에 문서를 생성하고 청크 분할 및 메타데이터 처리를 검증합니다. +`03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`의 이 테스트는 문서를 메모리에서 생성하고 청킹 및 메타데이터 처리를 검증합니다. ### 패턴 6: MCP 통합 테스트 -MCP 모듈은 stdio 전송방식을 사용하는 모델 컨텍스트 프로토콜 통합을 테스트합니다. 이 테스트들은 애플리케이션이 서브프로세스로 MCP 서버를 실행하고 통신할 수 있는지 검증합니다. +MCP 모듈은 stdio 전송을 사용하는 모델 컨텍스트 프로토콜 통합을 테스트합니다. 이 테스트들은 애플리케이션이 MCP 서버를 서브프로세스로 생성하고 통신할 수 있는지 검증합니다. -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java`에 MCP 클라이언트 동작을 검증하는 테스트가 있습니다. +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` 테스트에서 MCP 클라이언트 동작을 확인할 수 있습니다. -**실행 방법:** +**실행 명령:** **Bash:** ```bash @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## 테스트 철학 -AI를 테스트하지 말고, 코드를 테스트하세요. 테스트는 프롬프트가 어떻게 구성되는지, 메모리가 어떻게 관리되는지, 도구가 어떻게 실행되는지를 검증해야 합니다. AI 응답은 달라질 수 있으므로 테스트 단언에 포함하지 마세요. 프롬프트 템플릿이 올바른 변수 대체를 하는지를 묻고, AI가 정답을 주는지를 묻지 마세요. +AI가 아니라 여러분의 코드를 테스트하세요. 테스트는 프롬프트 구성, 메모리 관리, 도구 실행 방식을 검증해야 합니다. AI 응답은 변동성이 크므로 테스트 단언문의 일부가 되어서는 안 됩니다. 프롬프트 템플릿이 변수를 올바르게 대체하는지 스스로에게 물어보세요, AI가 정확한 답을 주는지는 묻지 마세요. -언어 모델에는 모킹을 사용하세요. 언어 모델은 느리고, 비용이 들며, 비결정론적인 외부 의존성입니다. 모킹은 테스트를 초 단위가 아닌 밀리초 단위로 빠르게 만들고, API 비용이 없으며, 항상 같은 결과로 결정론적입니다. +언어 모델은 모킹하세요. 외부 의존성이며 느리고, 비용이 들며, 결정적이지 않기 때문입니다. 모킹은 테스트를 밀리초 단위로 빠르고, 무료로, 매번 같은 결과를 내게 만듭니다. -테스트는 독립적으로 유지하세요. 각 테스트는 자신의 데이터를 설정하고, 다른 테스트에 의존하지 않으며, 스스로 정리해야 합니다. 테스트는 실행 순서와 관계없이 통과해야 합니다. +테스트는 독립적으로 유지하세요. 각 테스트는 데이터를 스스로 설정하고, 다른 테스트에 의존하지 않으며, 끝난 뒤 정리해야 합니다. 실행 순서에 관계없이 테스트가 통과해야 합니다. -정상 경로뿐 아니라 경계 조건도 테스트하세요. 빈 입력, 매우 큰 입력, 특수 문자, 잘못된 매개변수, 경계 조건 등을 시도하세요. 이런 테스트는 정상 사용에서 발견하기 어려운 버그를 노출합니다. +행복한 경로 외 케이스를 테스트하세요. 빈 입력, 매우 큰 입력, 특수 문자, 잘못된 매개변수, 경계 조건들을 시도하세요. 이는 정상 사용 시 드러나지 않는 버그를 발견하게 해 줍니다. -설명적인 이름을 사용하세요. `shouldMaintainConversationHistoryAcrossMultipleMessages()`와 `test1()`를 비교해보세요. 전자는 무엇을 테스트하는지 정확히 알려줘 실패 원인 파악이 훨씬 쉽습니다. +설명적인 이름을 사용하세요. `shouldMaintainConversationHistoryAcrossMultipleMessages()`와 `test1()`을 비교해 보세요. 첫 번째는 무엇이 테스트되는지 정확히 알려 주어 실패 시 디버깅을 훨씬 쉽게 만듭니다. ## 다음 단계 -이제 테스트 패턴을 이해했으니 각 모듈을 더 깊이 탐구하세요: +테스트 패턴을 이해했으니 각 모듈을 더 깊이 탐구하세요: -- **[00 - 빠른 시작](../00-quick-start/README.md)** - 프롬프트 템플릿 기본부터 시작 -- **[01 - 소개](../01-introduction/README.md)** - 대화 메모리 관리 배우기 -- **[02 - 프롬프트 엔지니어링](../02/prompt-engineering/README.md)** - GPT-5.2 프롬프트 패턴 마스터하기 -- **[03 - RAG](../03-rag/README.md)** - 검색 보강 생성 시스템 구축하기 -- **[04 - 도구](../04-tools/README.md)** - 함수 호출 및 도구 체인 구현하기 -- **[05 - MCP](../05-mcp/README.md)** - 모델 컨텍스트 프로토콜 통합하기 +- **[01 - 소개](../01-introduction/README.md)** - 대화 메모리 관리 학습 +- **[02 - 프롬프트 엔지니어링](../02/prompt-engineering/README.md)** - GPT-5.2 프롬프트 패턴 마스터 +- **[03 - RAG](../03-rag/README.md)** - 검색 기반 생성 시스템 구축 +- **[04 - 툴](../04-tools/README.md)** - 함수 호출 및 도구 체인 구현 +- **[05 - MCP](../05-mcp/README.md)** - 모델 컨텍스트 프로토콜 통합 -각 모듈의 README는 여기서 테스트된 개념들을 상세히 설명합니다. +각 모듈의 README에서 여기서 테스트된 개념을 자세히 설명합니다. --- -**네비게이션:** [← 메인으로 돌아가기](../README.md) +**탐색:** [← 메인으로 돌아가기](../README.md) --- -**면책 조항**: -이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 최선을 다하고 있으나, 자동 번역은 오류나 부정확성이 포함될 수 있음을 유의해 주시기 바랍니다. 원본 문서가 권위 있는 출처로 간주되어야 합니다. 중요한 정보의 경우에는 전문적인 인간 번역을 권장합니다. 이 번역의 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다. +**면책 조항**: +이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 기하기 위해 노력하고 있으나, 자동 번역은 오류나 부정확한 부분이 있을 수 있음을 유의하시기 바랍니다. 원본 문서의 원어본이 권위 있는 자료로 간주되어야 합니다. 중요한 정보의 경우, 전문가의 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다. \ No newline at end of file diff --git a/translations/lt/.co-op-translator.json b/translations/lt/.co-op-translator.json index a8609ce1d..7672d53be 100644 --- a/translations/lt/.co-op-translator.json +++ b/translations/lt/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "lt" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T20:13:08+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T13:55:44+00:00", "source_file": "01-introduction/README.md", "language_code": "lt" }, @@ -18,20 +18,20 @@ "language_code": "lt" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T20:15:55+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T13:50:47+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "lt" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T20:17:45+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T13:54:50+00:00", "source_file": "03-rag/README.md", "language_code": "lt" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:43:31+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T13:53:23+00:00", "source_file": "04-tools/README.md", "language_code": "lt" }, @@ -54,8 +54,8 @@ "language_code": "lt" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:57:01+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T13:49:21+00:00", "source_file": "README.md", "language_code": "lt" }, @@ -72,14 +72,14 @@ "language_code": "lt" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T20:21:51+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T13:51:18+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "lt" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T20:22:46+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T13:51:58+00:00", "source_file": "docs/TESTING.md", "language_code": "lt" } diff --git a/translations/lt/00-quick-start/README.md b/translations/lt/00-quick-start/README.md deleted file mode 100644 index 3fc0db08e..000000000 --- a/translations/lt/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modulis 00: Greitas pradėjimas - -## Turinys - -- [Įvadas](../../../00-quick-start) -- [Kas yra LangChain4j?](../../../00-quick-start) -- [LangChain4j priklausomybės](../../../00-quick-start) -- [Reikalavimai](../../../00-quick-start) -- [Sąranka](../../../00-quick-start) - - [1. Gaukite savo GitHub raktą](../../../00-quick-start) - - [2. Nustatykite savo raktą](../../../00-quick-start) -- [Paleiskite pavyzdžius](../../../00-quick-start) - - [1. Pagrindinis pokalbis](../../../00-quick-start) - - [2. Prompto šablonai](../../../00-quick-start) - - [3. Funkcijų iškvietimas](../../../00-quick-start) - - [4. Dokumentų klausimai ir atsakymai (Easy RAG)](../../../00-quick-start) - - [5. Atsakingas DI](../../../00-quick-start) -- [Ką rodo kiekvienas pavyzdys](../../../00-quick-start) -- [Kitos veiksmų gairės](../../../00-quick-start) -- [Trikčių šalinimas](../../../00-quick-start) - -## Įvadas - -Šis greitas pradžios vadovas skirtas kuo greičiau pradėti naudotis LangChain4j. Jame aptariami absoliučiai pagrindai, kaip kurti DI programas su LangChain4j ir GitHub Modeliais. Kitose moduliuose pereisite prie Azure OpenAI ir GPT-5.2 bei gilinsitės į kiekvieną koncepciją. - -## Kas yra LangChain4j? - -LangChain4j yra Java biblioteka, kuri supaprastina DI varomų programų kūrimą. Vietoje darbo su HTTP klientais ir JSON analizavimu, jūs dirbate su švariais Java API. - -„Chain“ LangChain pavadinime reiškia kelių komponentų sujungimą – galite sujungti promptą su modeliu, parseriu ar sujungti kelis DI kvietimus, kur vienas išvestis tampa kito įvestimi. Šis greitas pradžios vadovas fokusuojasi į pagrindus, prieš pereinant prie sudėtingesnių grandinių. - -LangChain4j Chaining Concept - -*Komponentų sujungimas LangChain4j – blokai jungiasi, kad sukurtų galingus DI darbo srautus* - -Naudosime tris pagrindinius komponentus: - -**ChatModel** – sąsaja DI modelio sąveikoms. Iškvieskite `model.chat("prompt")` ir gaukite atsakymą kaip eilutę. Naudojame `OpenAiOfficialChatModel`, kuris veikia su OpenAI suderinamais galais, tokiais kaip GitHub Modeliai. - -**AiServices** – sukuria tipo saugias DI paslaugų sąsajas. Apibrėžkite metodus, paženklinkite juos `@Tool`, ir LangChain4j valdo orkestraciją. DI automatiškai kviečia jūsų Java metodus prireikus. - -**MessageWindowChatMemory** – išlaiko pokalbio istoriją. Be to, kiekvienas užklausimas yra nepriklausomas. Su ja DI prisimena ankstesnius pranešimus ir palaiko kontekstą per kelis etapus. - -LangChain4j Architecture - -*LangChain4j architektūra – pagrindiniai komponentai kartu suteikia jūsų DI programoms galią* - -## LangChain4j priklausomybės - -Šis greitas pradžios vadovas naudoja tris Maven priklausomybes [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modulis `langchain4j-open-ai-official` suteikia klasę `OpenAiOfficialChatModel`, kuri jungiasi prie OpenAI suderinamų API. GitHub Modeliai naudoja tą patį API formatą, tad nereikia specialaus adapterio – tiesiog nurodykite bazinį URL `https://models.github.ai/inference`. - -Modulis `langchain4j-easy-rag` suteikia automatinį dokumentų skaidymą, įterpimą ir traukimą, kad galėtumėte kurti RAG programas be rankinio kiekvieno žingsnio konfigūravimo. - -## Reikalavimai - -**Naudojate Dev konteinerį?** Java ir Maven jau įdiegti. Jums reikia tik GitHub Asmeninio Prieigos Rakto. - -**Vietiniam kūrimui:** -- Java 21+, Maven 3.9+ -- GitHub Asmeninis Prieigos Raktas (instrukcijos žemiau) - -> **Pastaba:** Šiame modulyje naudojamas `gpt-4.1-nano` GitHub Modelių modelis. Nekeiskite modelio pavadinimo kode – jis nustatytas dirbti su GitHub turimais modeliais. - -## Sąranka - -### 1. Gaukite savo GitHub raktą - -1. Eikite į [GitHub Nustatymai → Asmeniniai prieigos raktai](https://github.com/settings/personal-access-tokens) -2. Paspauskite „Sukurti naują raktą“ -3. Nustatykite aprašomą pavadinimą (pvz., "LangChain4j Demo") -4. Nustatykite galiojimo laiką (rekomenduojama 7 dienos) -5. Skiltyje „Sąskaitos leidimai“ raskite „Models“ ir nustatykite „Tik skaitymas“ -6. Spauskite „Sukurti raktą“ -7. Nukopijuokite ir išsaugokite raktą – jo daugiau nepamatysite - -### 2. Nustatykite savo raktą - -**1 pasirinkimas: Naudojant VS Code (rekomenduojama)** - -Jei naudojate VS Code, pridėkite savo raktą `.env` faile projekto šaknyje: - -Jei `.env` failo nėra, nukopijuokite `.env.example` į `.env` arba sukurkite naują `.env` failą projekto šaknyje. - -**Pavyzdys `.env` failo:** -```bash -# Failas /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Tuomet galite tiesiog dešiniuoju pelės mygtuku spustelėti bet kurį demonstracinį failą (pvz., `BasicChatDemo.java`) naršyklėje ir pasirinkti **„Run Java“** arba naudoti paleidimo konfigūracijas Run and Debug skydelyje. - -**2 pasirinkimas: Naudojant terminalą** - -Nustatykite raktą kaip aplinkos kintamąjį: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Paleiskite pavyzdžius - -**Naudojant VS Code:** Tiesiog dešiniuoju pelės mygtuku spustelėkite bet kurį demonstracinį failą naršyklėje ir pasirinkite **„Run Java“**, arba naudokite paleidimo konfigūracijas Run and Debug skydelyje (įsitikinkite, kad iš pradžių pridėjote savo raktą į `.env` failą). - -**Naudojant Maven:** Taip pat galite paleisti komandinėje eilutėje: - -### 1. Pagrindinis pokalbis - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Prompto šablonai - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Rodo zero-shot, few-shot, chain-of-thought ir roliniu pagrindu paremtus promptus. - -### 3. Funkcijų iškvietimas - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -DI automatiškai kviečia jūsų Java metodus prireikus. - -### 4. Dokumentų klausimai ir atsakymai (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Užduokite klausimus apie savo dokumentus naudodami Easy RAG su automatiniu įterpimu ir traukimu. - -### 5. Atsakingas DI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Žiūrėkite, kaip DI saugumo filtrai blokuoja kenksmingą turinį. - -## Ką rodo kiekvienas pavyzdys - -**Pagrindinis pokalbis** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Pradėkite čia, kad pamatytumėte LangChain4j paprastumą. Sukursite `OpenAiOfficialChatModel`, išsiųsite promptą su `.chat()` ir gausite atsakymą. Tai rodo pagrindą: kaip inicijuoti modelius su pasirinktais galais ir API raktais. Supratus šį modelį, visa kita statoma remiantis juo. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) ir paklauskite: -> - „Kaip pakeisčiau šį kodą, kad naudotų GitHub Modelius vietoje Azure OpenAI?“ -> - „Kokius kitus parametrus galiu konfigūruoti OpenAiOfficialChatModel.builder()?“ -> - „Kaip pridėti transliuojamus atsakymus vietoje laukimo viso atsakymo?“ - -**Prompto inžinerija** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Dabar, kai žinote, kaip bendrauti su modeliu, pažvelkime, ką jam sakote. Ši demonstracija naudoja tą patį modelio nustatymą, bet rodo penkis skirtingus promptų šablonus. Išbandykite zero-shot promptus tiesioginiams nurodymams, few-shot promptus, kurie mokosi iš pavyzdžių, chain-of-thought promptus, kurie atskleidžia loginio mąstymo žingsnius, ir rolinių vaidmenų promptus, nustatančius kontekstą. Matysite, kaip tas pats modelis duoda drastiškai skirtingus rezultatus, priklausomai nuo to, kaip formuluojate užklausą. - -Demonstracija taip pat rodo promptų šablonus, kurie yra galingas būdas kurti pakartotinai naudojamus promptus su kintamaisiais. -Toliau pateiktas pavyzdys naudoja LangChain4j `PromptTemplate`, kad užpildytų kintamuosius. DI atsakys remdamasis nurodyta paskirties vieta ir veikla. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) ir paklauskite: -> - „Kuo skiriasi zero-shot ir few-shot promptai ir kada naudoti kiekvieną?“ -> - „Kaip temperatūros parametras veikia modelių atsakymus?“ -> - „Kokios yra technikos, kad išvengti promptų injekcijos atakų gamyboje?“ -> - „Kaip sukurti pakartotinai naudojamus PromptTemplate objektus dažniausiai naudojamiems šablonams?“ - -**Įrankių integracija** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Čia LangChain4j tampa galingas. Naudosite `AiServices`, kad sukurtumėte DI pagalbininką, kuris gali iškvietinėti jūsų Java metodus. Tiesiog paženklinkite metodus `@Tool("aprašymas")` ir LangChain4j rūpinasi likusiu – DI automatiškai nusprendžia, kada naudoti kiekvieną įrankį, pagal tai, ko vartotojas paprašo. Tai demonstruoja funkcijų iškvietimą – svarbią techniką kurti DI, kuris gali imtis veiksmų, o ne tik atsakyti į klausimus. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ir paklauskite: -> - „Kaip veikia @Tool anotacija ir ką LangChain4j daro su ja užkulisiuose?“ -> - „Ar DI gali iškviesti kelis įrankius iš eilės, kad išspręstų sudėtingas problemas?“ -> - „Kas atsitinka, jei įrankis meta išimtį – kaip turėčiau tvarkyti klaidas?“ -> - „Kaip integruočiau tikrą API vietoje šio skaičiuotuvo pavyzdžio?“ - -**Dokumentų klausimai ir atsakymai (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Čia matysite RAG (retrieval-augmented generation) naudojant LangChain4j „Easy RAG“ metodą. Dokumentai įkeliami, automatiškai suskaidomi ir įterpiami į atminties saugyklą, tada turinio paieškos įrankis pateikia susijusius fragmentus DI užklausos metu. DI atsako remdamasis jūsų dokumentais, o ne bendromis žiniomis. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) ir paklauskite: -> - „Kaip RAG sumažina DI haliucinacijas, palyginti su modelio mokymo duomenimis?“ -> - „Kuo skiriasi šis paprastas metodas nuo individualaus RAG vamzdyno?“ -> - „Kaip išplėsti tai keliems dokumentams ar didesnėms žinių bazėms?“ - -**Atsakingas DI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Statykite DI saugumą gynybiniu sluoksniu. Ši demonstracija rodo dvi apsaugos sluoksnio funkcijas kartu: - -**1 dalis: LangChain4j naudojimo ribojimai (Input Guardrails)** – Blokuoja pavojingus promptus prieš jiems pasiekiant LLM. Sukurkite savo ribojimus, kurie tikrina uždraustus raktinius žodžius ar šablonus. Jie veikia jūsų kode, todėl greiti ir nemokami. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**2 dalis: Tiekėjo saugumo filtrai** – GitHub Modeliai turi įmontuotus filtrus, kurie pagauna tai, ką jūsų ribojimai gali praleisti. Matysite griežtus blokus (HTTP 400 klaidas) už rimtus pažeidimus ir švelnius atsisakymus, kai DI mandagiai atsisako. - -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) ir paklauskite: -> - „Kas yra InputGuardrail ir kaip sukurti savo?“ -> - „Kuo skiriasi griežtas užblokavimas nuo švelnaus atsisakymo?“ -> - „Kodėl naudoti ir ribojimus, ir tiekėjo filtrus kartu?“ - -## Kitos veiksmų gairės - -**Kitas modulis:** [01-introduction - Pradžia su LangChain4j](../01-introduction/README.md) - ---- - -**Navigacija:** [← Grįžti į pagrindinį](../README.md) | [Kitas: Modulis 01 - Įvadas →](../01-introduction/README.md) - ---- - -## Trikčių šalinimas - -### Pirmas Maven sukūrimas - -**Problema:** Pirmas `mvn clean compile` arba `mvn package` vykdymas užtrunka (10-15 minučių) - -**Priežastis:** Maven pirmą kartą turi atsisiųsti visas projekto priklausomybes (Spring Boot, LangChain4j bibliotekas, Azure SDK ir kt.). - -**Sprendimas:** Tai normalu. Tolimesni kūrimai bus ženkliai greitesni, nes priklausomybės bus talpinamos vietoje. Atsisiuntimo laikas priklauso nuo jūsų tinklo greičio. - -### PowerShell Maven komandos sintaksės klaida - -**Problema:** Maven komandos nepavyksta su klaida `Unknown lifecycle phase ".mainClass=..."` -**Priežastis**: PowerShell interpretuoja `=` kaip kintamojo priskyrimo operatorių, todėl Maven savybių sintaksė sugadinama - -**Sprendimas**: Naudokite sustabdymo interpretavimą operatorių `--%` prieš Maven komandą: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operatorius `--%` nurodo PowerShell perduoti visas likusias argumentų dalis pažodžiui Maven be interpretacijos. - -### Windows PowerShell emoji rodymas - -**Problema**: AI atsakymai PowerShell rodomi kaip nesuprantami simboliai (pvz., `????` arba `â??`) vietoje emoji - -**Priežastis**: PowerShell numatytoji koduotė nepalaiko UTF-8 emoji - -**Sprendimas**: Paleiskite šią komandą prieš vykdant Java programas: -```cmd -chcp 65001 -``` - -Tai privers terminalą naudoti UTF-8 koduotę. Alternatyviai naudokite Windows Terminal, kuris geriau palaiko Unicode. - -### API kvietimų derinimas - -**Problema**: Autentifikacijos klaidos, užklausų limitai arba netikėti AI modelio atsakymai - -**Sprendimas**: Pavyzdžiai naudoja `.logRequests(true)` ir `.logResponses(true)`, kad parodytų API kvietimus konsolėje. Tai padeda tirti autentifikacijos klaidas, užklausų limitus ar netikėtus atsakymus. Pašalinkite šias parinktis gamybai, kad sumažintumėte žurnalų triukšmą. - ---- - - -**Atsakomybės apribojimas**: -Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, atkreipkite dėmesį, kad automatizuoti vertimai gali turėti klaidų arba netikslumų. Originalus dokumentas jo gimtąja kalba laikomas autoritetingu šaltiniu. Esant svarbiai informacijai, rekomenduojamas profesionalus žmogaus vertimas. Mes neatsakome už bet kokius nesusipratimus ar klaidingus interpretavimus, atsiradusius dėl šio vertimo naudojimo. - \ No newline at end of file diff --git a/translations/lt/01-introduction/README.md b/translations/lt/01-introduction/README.md index 2ce7d42ae..59d8d01ba 100644 --- a/translations/lt/01-introduction/README.md +++ b/translations/lt/01-introduction/README.md @@ -2,37 +2,37 @@ ## Turinys -- [Vaizdo įrašo apžvalga](../../../01-introduction) -- [Ką išmoksi](../../../01-introduction) -- [Reikalavimai](../../../01-introduction) -- [Pagrindinės problemos supratimas](../../../01-introduction) -- [Tokenų supratimas](../../../01-introduction) -- [Kaip veikia atmintis](../../../01-introduction) -- [Kaip tai naudoja LangChain4j](../../../01-introduction) -- [Azure OpenAI infrastruktūros diegimas](../../../01-introduction) -- [Programos paleidimas lokaliai](../../../01-introduction) -- [Programos naudojimas](../../../01-introduction) - - [Beprekių pokalbis (kairysis skydelis)](../../../01-introduction) - - [Su preke pokalbis (dešinysis skydelis)](../../../01-introduction) -- [Kiti žingsniai](../../../01-introduction) +- [Vaizdo įrašo apžvalga](#vaizdo-įrašo-apžvalga) +- [Ką išmoksite](#ką-išmoksite) +- [Reikalavimai](#reikalavimai) +- [Pagrindinės problemos supratimas](#pagrindinės-problemos-supratimas) +- [Tokenų supratimas](#tokenų-supratimas) +- [Kaip veikia atmintis](#kaip-veikia-atmintis) +- [Kaip tai naudoja LangChain4j](#kaip-tai-naudoja-langchain4j) +- [Azure OpenAI infrastruktūros diegimas](#azure-openai-infrastruktūros-diegimas) +- [Programos paleidimas lokaliai](#programos-paleidimas-lokaliai) +- [Programos naudojimas](#programos-naudojimas) + - [Valstybės neįtvirtinta pokalbių sistema (kairysis skydelis)](#valstybės-neįtvirtinta-pokalbių-sistema-kairysis-skydelis) + - [Valstybės įtvirtinta pokalbių sistema (dešinysis skydelis)](#valstybės-įtvirtinta-pokalbių-sistema-dešinysis-skydelis) +- [Kiti žingsniai](#kiti-žingsniai) ## Vaizdo įrašo apžvalga -Žiūrėkite šią tiesioginę sesiją, kurioje paaiškinama, kaip pradėti darbą su šiuo moduliu: +Žiūrėkite tiesioginę sesiją, kurioje paaiškinama, kaip pradėti naudotis šiuo moduliu: -Pradžia su LangChain4j - tiesioginė sesija +Pradžia su LangChain4j – Tiesioginė sesija -## Ką išmoksi +## Ką išmoksite -Greitojo starto metu naudoji GitHub modelius siųsti užklausas, kviesti įrankius, kurti RAG srautą ir testuoti apsaugos mechanizmus. Šie demonstraciniai pavyzdžiai parodė, kas įmanoma — dabar pereisime prie Azure OpenAI ir GPT-5.2 bei pradėsime kurti gamybinius aplikacijas. Šis modulis orientuotas į pokalbių AI, kuris įsimena kontekstą ir palaiko būseną — tai yra koncepcijos, kurias greitojo starto demonstracijos naudojo užkulisiuose, bet nepaaiškino. +Tai jūsų pradžios taškas su LangChain4j ir Azure OpenAI. Pradėsime nuo pagrindų ir pradėsime kurti gamybinio stiliaus programas. Šis modulis orientuotas į pokalbių AI, kuris prisimena kontekstą ir palaiko būseną – tai yra pagrindinės sąvokos, kurias vėlesni moduliai vysto. -Visame vadove naudosime Azure OpenAI GPT-5.2, nes jo pažangios loginio mąstymo galimybės aiškiau parodo skirtingų modelių elgseną. Kai pridėsite atmintį, skirtumas bus akivaizdus. Tai palengvina supratimą, ką kiekviena sudedamoji dalis atneša jūsų aplikacijai. +Visos šios pamokos metu naudosime Azure OpenAI GPT-5.2, nes jo pažangios atpažinimo galimybės leidžia aiškiau matyti skirtingų modelių elgesio skirtumus. Įdiegus atmintį, aiškiai matysite skirtumą. Tai padeda geriau suprasti, ką kiekviena dalis prideda jūsų programai. -Sukursite vieną aplikaciją, kuri demonstruos abu modelius: +Jūs sukursite vieną programą, kuri demonstruoja abu modelius: -**Beprekis pokalbis** – Kiekviena užklausa yra nepriklausoma. Modelis neužsimena apie ankstesnes žinutes. Tai buvo modelis, kurį naudojote greitame paleidyme. +**Valstybės neįtvirtinta pokalbių sistema** – kiekvienas užklausimas yra nepriklausomas. Modelis neprisimena ankstesnių žinučių. Tai paprasčiausias pradžios taškas. -**Su preke pokalbis** – Kiekviena užklausa apima pokalbio istoriją. Modelis palaiko kontekstą per kelis žingsnius. Tai yra tai, ko reikalauja gamybinės aplikacijos. +**Valstybės įtvirtinta pokalbių sistema** – kiekviena užklausa apima pokalbio istoriją. Modelis palaiko kontekstą keliuose etapuose. Tai reikalinga gamybinėms programoms. ## Reikalavimai @@ -41,45 +41,45 @@ Sukursite vieną aplikaciją, kuri demonstruos abu modelius: - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Pastaba:** Java, Maven, Azure CLI bei Azure Developer CLI (azd) yra iš anksto įdiegti pateiktame kūrimo konteineryje. +> **Pastaba:** Java, Maven, Azure CLI ir Azure Developer CLI (azd) yra iš anksto įdiegti pateiktame devcontainer. -> **Pastaba:** Šis modulis naudoja GPT-5.2 Azure OpenAI. Diegimas yra automatiškai konfigūruojamas naudojant `azd up` – nekeiskite modelio pavadinimo kode. +> **Pastaba:** Šis modulis naudoja GPT-5.2 Azure OpenAI. Diegimas konfigūruojamas automatiškai per `azd up` - nekeiskite modelio pavadinimo kode. ## Pagrindinės problemos supratimas -Kalbų modeliai yra beprekiai. Kiekvienas API kvietimas yra nepriklausomas. Jei parašysite „Mano vardas John“ ir po to paklausite „Koks mano vardas?“, modelis neturi jokios informacijos, jog ką tik prisistatėte. Jis traktuoja kiekvieną užklausą tarsi jis būtų pirmas kartas, kai kalbatės. +Kalbų modeliai yra be būsenos. Kiekvienas API kvietimas yra nepriklausomas. Jei paskelbsite "Mano vardas John" ir po to klausite "Koks mano vardas?", modelis nežino, kad ką tik prisistatėte. Jis laiko kiekvieną užklausą it tai būtų pirmas pokalbis. -Tai tinka paprastiems klausimų-atsakymų atvejams, bet yra nenaudinga tikroms aplikacijoms. Klientų aptarnavimo robotai turi įsiminti, ką jiems pasakėte. Asmeniniai asistentai turi turėti kontekstą. Bet koks daugiapakopis pokalbis reikalauja atminties. +Tai tinka paprastiems klausimams ir atsakymams, bet nėra naudinga realioms programoms. Klientų aptarnavimo robotai turi prisiminti, ką jiems pasakėte. Asmeniniai asistentai reikia konteksto. Bet kuris kelių etapų pokalbis reikalauja atminties. -Žemiau pateiktame paveiksle palyginamos dvi strategijos — kairėje beprekis kvietimas, kuris pamiršta jūsų vardą; dešinėje – su preke kvietimas, kuriam ChatMemory palaiko atmintį ir prisimena. +Toliau pateikiamas diagrama vaizduoja abi prieigas – kairėje, valstybės neįtvirtintas kvietimas, kuris pamiršta jūsų vardą; dešinėje, valdoma pokalbių atmintimi ChatMemory, kuri jį prisimena. -Beprekiai ir Su preke pokalbiai +Valstybės neįtvirtintos ir valstybės įtvirtintos pokalbiai -*Skirtumas tarp beprekių (nepriklausomų kvietimų) ir su preke (konteksto palaikymo) pokalbių* +*Skirtumas tarp valstybės neįtvirtintų (nepriklausomų kvietimų) ir valstybės įtvirtintų (su kontekstu) pokalbių* ## Tokenų supratimas -Prieš pradedant pokalbius, svarbu suprasti tokenus – pagrindinius teksto vienetus, kuriuos apdoroja kalbų modeliai: +Prieš pradedant pokalbius svarbu suprasti tokenus – pagrindinius teksto vienetus, kuriuos apdoroja kalbų modeliai: -Tokenų paaiškinimas +Tokeno paaiškinimas -*Pavyzdys, kaip tekstas suskaidomas į tokenus – „I love AI!“ tampa 4 atskiromis apdorojimo dalimis* +*Pavyzdys, kaip tekstas suskaidomas į tokenus – "Aš myliu AI!" tampa 4 atskiromis apdorojimo vienetais* -Tokenai yra kaip AI modeliai matuoja ir apdoroja tekstą. Žodžiai, skyrybos ženklai ir net tarpai gali būti tokenais. Jūsų modeliui yra apribojimas, kiek tokenų jis gali apdoroti vienu metu (400 000 GPT-5.2 atveju, su iki 272 000 įėjimo tokenų ir 128 000 išėjimo tokenų). Suprasti tokenus padeda valdyti pokalbio ilgį ir sąnaudas. +Tokenai yra tai, kaip AI modeliai matuoja ir apdoroja tekstą. Žodžiai, skyrybos ženklai ir net tarpai gali būti tokenais. Jūsų modelis turi ribą, kiek tokenų jis gali apdoroti iš karto (400 000 tokenų GPT-5.2, iš jų iki 272 000 įvesties tokenų ir 128 000 išvesties tokenų). Tokenų supratimas padeda valdyti pokalbio ilgį ir sąnaudas. ## Kaip veikia atmintis -Pokalbių atmintis sprendžia beprekių problemą, palaikydama pokalbio istoriją. Prieš siųsdamas užklausą modeliui, karkasas prideda svarbias ankstesnes žinutes. Kai klausiate „Koks mano vardas?“, sistema iš tikrųjų siunčia visą pokalbio istoriją, leidžiančią modeliui matyti, kad anksčiau sakėte „Mano vardas John.“ +Pokalbių atmintis išsprendžia valstybės neįtvirtinimo problemą palaikydama pokalbio istoriją. Prieš siųsdama jūsų užklausą modeliui, sistema įterpia atitinkamas ankstesnes žinutes. Kai klausiate "Koks mano vardas?", sistema išsiunčia visą pokalbio istoriją, leidžiančią modeliui matyti, kad anksčiau pasakėte "Mano vardas John." -LangChain4j suteikia atminties įgyvendinimus, kurie tai daro automatiškai. Jūs pasirenkate, kiek žinučių išlaikyti, o karkasas valdo konteksto langą. Žemiau esantis paveikslas rodo, kaip MessageWindowChatMemory palaiko slenkantį langą su naujausiomis žinutėmis. +LangChain4j teikia atminties įgyvendinimus, kurie tai automatiškai valdo. Jūs pasirenkate, kiek žinučių išlaikyti, o sistema rūpinasi konteksto lange. Toliau pateikta diagrama rodo, kaip MessageWindowChatMemory palaiko slankiojančio lango principą su neseniai naudotomis žinutėmis. Atminties lango koncepcija -*MessageWindowChatMemory palaiko slenkantį langą su naujausiomis žinutėmis, automatiškai pašalindamas senas* +*MessageWindowChatMemory palaiko slankiojantį langą su naujausiomis žinutėmis, automatiškai išmetant senas* ## Kaip tai naudoja LangChain4j -Šis modulis plečia greitojo paleidimo procesą, integruodamas Spring Boot ir pridedant pokalbių atmintį. Štai kaip komponentai susijungia: +Šis modulis integruoja Spring Boot ir prideda pokalbių atmintį. Štai kaip dalys dera tarpusavyje: **Priklausomybės** – pridėkite dvi LangChain4j bibliotekas: @@ -94,7 +94,7 @@ LangChain4j suteikia atminties įgyvendinimus, kurie tai daro automatiškai. Jū ``` -**Pokalbių modelis** – sukonfigūruokite Azure OpenAI kaip Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Pokalbių modelis** – konfigūruokite Azure OpenAI kaip Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builderis skaito kredencialus iš aplinkos kintamųjų, nustatytų naudojant `azd up`. `baseUrl` nustatymas į jūsų Azure endpointą leidžia OpenAI klientui dirbti su Azure OpenAI. +Konstruktorius nuskaito kredencialus iš aplinkos kintamųjų, nustatytų `azd up`. Nustatant `baseUrl` į jūsų Azure endpointą leidžiama OpenAI klientui dirbti su Azure OpenAI. -**Pokalbių atmintis** – sekite pokalbių istoriją su MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Pokalbių atmintis** – sekite pokalbio istoriją su MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Sukurkite atmintį su `withMaxMessages(10)`, kad išlaikytumėte paskutines 10 žinučių. Pridėkite naudotojo ir AI žinutes naudodami tipizuotus apvalkalus: `UserMessage.from(text)` ir `AiMessage.from(text)`. Istoriją gaunate su `memory.messages()` ir siunčiate modeliui. Servisas saugo atskiras atminties instancijas kiekvienam pokalbio ID, leidžiant keliems naudotojams kalbėtis vienu metu. +Kurti atmintį su `withMaxMessages(10)`, kad išlaikytumėte paskutines 10 žinučių. Pridėti vartotojo ir AI žinutes su tipizuotais apvyniojimais: `UserMessage.from(text)` ir `AiMessage.from(text)`. Gauti istoriją su `memory.messages()` ir perduoti modeliui. Paslauga saugo atskiras atminties instancijas pagal pokalbio ID, leidžiant keliems vartotojams vienu metu bendrauti. -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ir paklauskite: -> - „Kaip MessageWindowChatMemory nusprendžia, kurias žinutes pašalinti, kai langas pilnas?“ -> - „Ar galiu įgyvendinti savitą atminties saugojimą naudojant duomenų bazę vietoje atminties?“ -> - „Kaip pridėčiau suvestinių funkcionavimą senos pokalbio istorijos glaudinimui?“ +> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) pokalbiu:** Atidarykite [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ir paklauskite: +> - "Kaip MessageWindowChatMemory nusprendžia, kurias žinutes išmesti, kai langas pilnas?" +> - "Ar galiu įgyvendinti savo atminties saugojimo sprendimą naudojant duomenų bazę vietoje atminties?" +> - "Kaip pridėti santrauką, kad suspausčiau seną pokalbio istoriją?" -Beprekis pokalbio endpointas praleidžia atmintį – tiesiog `chatModel.chat(prompt)`, kaip greitojo starto metu. Su preke endpointas prideda žinutes į atmintį, gauna istoriją ir įtraukia kontekstą prie kiekvienos užklausos. Toks pats modelio konfigūravimas, skirtingos strategijos. +Valstybės neįtvirtinta pokalbių pabaigos taškas visiškai praleidžia atmintį – tiesiog `chatModel.chat(prompt)`, kaip pradžioje. Valstybės įtvirtinta pabaigos taškas įtraukią žinutes į atmintį, gauna istoriją ir kiekvienai užklausai prideda šį kontekstą. Tas pats modelio konfigūravimas, skirtingi modeliai. ## Azure OpenAI infrastruktūros diegimas @@ -147,16 +147,16 @@ cd 01-introduction azd up # Pasirinkite prenumeratą ir vietą (rekomenduojama eastus2) ``` -> **Pastaba:** Jei gaunate timeout klaidą (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), tiesiog paleiskite `azd up` dar kartą. Azure resursai gali dar būti diegiami fone, o pakartotinai bandant leidžia diegimui baigtis, kai resursai pasiekia galutinę būseną. +> **Pastaba:** Jei susiduriate su laiko ribos klaida (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), tiesiog dar kartą paleiskite `azd up`. Azure ištekliai gali vis dar būti diegiami fone ir bandymas dar kartą leidžia diegimui baigtis, kai ištekliai pasiekia galutinę būseną. Tai atliks: -1. Azure OpenAI resurso su GPT-5.2 ir text-embedding-3-small modeliais diegimą -2. Automatinį `.env` failo generavimą projekto šakniniame kataloge su kredencialais -3. Visų reikiamų aplinkos kintamųjų nustatymą +1. Diegs Azure OpenAI resursą su GPT-5.2 ir text-embedding-3-small modeliais +2. Automatiškai sukurs `.env` failą projekto šaknyje su kredencialais +3. Konfigūruos visus reikalingus aplinkos kintamuosius -**Susiduriate su diegimo problemomis?** Peržiūrėkite [Infrastruktūros README](infra/README.md) detaliam trikčių šalinimui, įskaitant potinklio vardų konfliktus, rankinius Azure Portalo diegimo žingsnius ir modelių konfigūracijos rekomendacijas. +**Turite diegimo problemų?** Žr. [Infrastruktūros README](infra/README.md) puslapį, kuriame pateikiamos detalios trikčių šalinimo instrukcijos, įskaitant subdomeno pavadinimų konfliktus, rankinius Azure portalo diegimo žingsnius ir modelio konfigūracijos rekomendacijas. -**Patikrinkite, ar diegimas sėkmingas:** +**Patikrinkite, ar diegimas pavyko:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY ir kt. Get-Content ..\.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY ir kt. ``` -> **Pastaba:** `azd up` komanda automatiškai generuoja `.env` failą. Jei norite jį atnaujinti vėliau, galite redaguoti `.env` rankiniu būdu arba sugeneruoti dar kartą vykdydami: +> **Pastaba:** Komanda `azd up` automatiškai sukuria `.env` failą. Jei vėliau reikės jį atnaujinti, galite redaguoti `.env` failą rankiniu būdu arba atkurti jį vėl paleisdami: > > **Bash:** > ```bash @@ -186,7 +186,7 @@ Get-Content ..\.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY ir kt. **Patikrinkite diegimą:** -Įsitikinkite, kad `.env` failas yra šakniniame kataloge su Azure kredencialais. Vykdykite tai iš modulio katalogo (`01-introduction/`): +Įsitikinkite, kad `.env` failas su Azure kredencialais yra šakniniame kataloge. Paleiskite tai modulyje (`01-introduction/`): **Bash:** ```bash @@ -195,34 +195,34 @@ cat ../.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **PowerShell:** ```powershell -Get-Content ..\.env # Turėtų parodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Paleiskite programas:** -**1 variantas: Naudojant Spring Boot Dashboard (rekomenduojama VS Code naudotojams)** +**1 variantas: Naudojant Spring Boot Dashboard (rekomenduojama VS Code vartotojams)** -Kūrimo konteineryje yra Spring Boot Dashboard plėtinys, kuris suteikia vizualų sąsajos valdymą visoms Spring Boot aplikacijoms. Rasite jį veiklų juostoje kairėje VS Code pusėje (ieškokite Spring Boot ikonos). +Dev konteineryje yra Spring Boot Dashboard plėtinys, suteikiantis vizualų valdymo įrankį visoms Spring Boot programoms. Rasite jį veiklos juostoje (Activity Bar) kairėje VS Code pusėje (žr. Spring Boot piktogramą). -Spring Boot Dashboard galite: -- Matyti visas prieinamas Spring Boot programas darbo erdvėje -- Vienu spustelėjimu paleisti/stabdyti programas -- Realiu laiku peržiūrėti programų žurnalus -- Stebėti programų būseną +Naudodamiesi Spring Boot Dashboard galite: +- Matyti visas įdiegtas Spring Boot programas darbinėje erdvėje +- Vienu paspaudimu paleisti/stabdyti programas +- Stebėti programų žurnalus realiu laiku +- Žiūrėti programų būseną -Tiesiog spustelėkite paleidimo mygtuką šalia „introduction“, kad paleistumėte šį modulį arba paleiskite visus modulius vienu metu. +Tiesiog spustelėkite paleidimo mygtuką šalia „introduction“, kad pradėtumėte šį modulį, arba paleiskite visus modulius vienu metu. -Spring Boot Dashboard +Spring Boot dashboard *Spring Boot Dashboard VS Code — paleiskite, sustabdykite ir stebėkite visus modulius vienoje vietoje* -**2 variantas: Naudojant shell skriptus** +**2 variantas: Naudojant komandos eilutės scenarijus** Paleiskite visas žiniatinklio programas (modulius 01-04): **Bash:** ```bash -cd .. # Iš pagrindinio katalogo +cd .. # Iš šaknų katalogo ./start-all.sh ``` @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Abu skriptai automatiškai įkelia aplinkos kintamuosius iš šakniniame `.env` faile ir sukurs JAR failus, jei jų nėra. +Abu scenarijai automatiškai įkelia aplinkos kintamuosius iš šakninio `.env` failo ir, jei nebus, sukurs JAR failus. -> **Pastaba:** Jei norite rankiniu būdu sukompiliuoti visus modulius prieš paleidimą: +> **Pastaba:** Jei norite rankiniu būdu iš anksto sukompiliuoti visus modulius: > > **Bash:** > ```bash @@ -262,9 +262,9 @@ Abu skriptai automatiškai įkelia aplinkos kintamuosius iš šakniniame `.env` > mvn clean package -DskipTests > ``` -Atidarykite naršyklėje http://localhost:8080 +Atidarykite http://localhost:8080 naršyklėje. -**Sustabdyti:** +**Norėdami sustabdyti:** **Bash:** ```bash @@ -282,41 +282,41 @@ cd ..; .\stop-all.ps1 # Visi moduliai ## Programos naudojimas -Programa pateikia internetinę sąsają su dviem pokalbių įgyvendinimais šalia vienas kito. +Programa suteikia žiniatinklio sąsają su dviem šoninės kitos pokalbių implementacijomis. -Programos pradžios ekranas +Programos pradinis ekranas -*Prietaisų skydelis rodo tiek Paprasto pokalbio (beprekio), tiek Pokalbio su išlaikymu (su preke) galimybes* +*Valdymo skydelis, rodantis paprastos pokalbių sistemos (valstybės neįtvirtintos) ir pokalbių sistemos su būsena (valstybės įtvirtintos) parinktis* -### Beprekis pokalbis (kairysis skydelis) +### Valstybės neįtvirtinta pokalbių sistema (kairysis skydelis) -Pabandykite pradžioje šią versiją. Paklauskite „Mano vardas John“ ir tuoj pat „Koks mano vardas?“ Modelis neprisimins, nes kiekviena žinutė yra nepriklausoma. Tai demonstruoja pagrindinę problemą su paprasta kalbos modelio integracija – nėra pokalbio konteksto. +Išbandykite pirmiausia šią. Paklauskite „Mano vardas John“ ir iškart tada klauskite „Koks mano vardas?“ Modelis neprisimins, nes kiekviena žinutė yra nepriklausoma. Tai parodo pagrindinę problemą su bazine kalbų modelių integracija – jokio pokalbio konteksto. -Beprekio pokalbio demonstracija +Valstybės neįtvirtintos pokalbių demonstracija *Dirbtinis intelektas neprisimena jūsų vardo iš ankstesnės žinutės* -### Pokalbis su išlaikymu (dešinysis skydelis) +### Valstybės įtvirtinta pokalbių sistema (dešinysis skydelis) -Dabar išbandykite tą patį seką čia. Paklauskite „Mano vardas John“ ir po to „Koks mano vardas?“ Šį kartą AI prisimena. Skirtumas yra MessageWindowChatMemory – palaiko pokalbio istoriją ir prideda ją prie kiekvienos užklausos. Taip veikia gamybiniai pokalbių AI. +Dabar pabandykite tą patį seką čia. Paklauskite „Mano vardas John“ ir tada „Koks mano vardas?“ Šį kartą sistema atsimena. Skirtumas yra MessageWindowChatMemory – ji palaiko pokalbio istoriją ir kiekvienai užklausai prideda tą kontekstą. Tokiu būdu veikia gamybinis pokalbių AI. -Pokalbio su išlaikymu demonstracija +Valstybės įtvirtintos pokalbių demonstracija -*Dirbtinis intelektas prisimena jūsų vardą iš ankstesnio pokalbio* +*Dirbtinis intelektas prisimena jūsų vardą iš ankstesnių pokalbio etapų* -Abu skydeliai naudoja tą patį GPT-5.2 modelį. Vienintelis skirtumas – atmintis. Tai aiškiai parodo, ką atmintis atneša jūsų aplikacijai ir kodėl ji būtina tikrame naudojime. +Abi sąsajos naudoja tą patį GPT-5.2 modelį. Vienintelis skirtumas yra atmintis. Tai aiškiai parodo, ką atmintis suteikia jūsų programai ir kodėl ji yra būtina tikram naudojimui. ## Kiti žingsniai -**Kitas modulis:** [02-prompt-engineering - Užklausų kūrimas su GPT-5.2](../02-prompt-engineering/README.md) +**Kitas modulis:** [02-prompt-engineering - Prompt Engineering su GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigacija:** [← Ankstesnis: Modulis 00 - Greitas startas](../00-quick-start/README.md) | [Atgal į pagrindinį](../README.md) | [Kitas: Modulis 02 - Užklausų kūrimas →](../02-prompt-engineering/README.md) +**Navigacija:** [← Grįžti prie pagrindinio](../README.md) | [Toliau: Modulis 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- -**Atsakomybės atsisakymas**: -Šis dokumentas buvo išverstas naudojant KI vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, atkreipkite dėmesį, kad automatizuoti vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba turėtų būti laikomas tikruoju šaltiniu. Dėl svarbios informacijos rekomenduojamas profesionalus žmogaus vertimas. Mes neatsakome už jokius nesusipratimus ar klaidingas interpretacijas, kilusias naudojant šį vertimą. +**Atsakomybės apribojimas**: +Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojama naudoti profesionalų žmogiškąjį vertimą. Mes neatsakome už jokius nesusipratimus ar neteisingą interpretaciją, kilusią naudojantis šiuo vertimu. \ No newline at end of file diff --git a/translations/lt/02-prompt-engineering/README.md b/translations/lt/02-prompt-engineering/README.md index 7a57f71f4..b694b3bf8 100644 --- a/translations/lt/02-prompt-engineering/README.md +++ b/translations/lt/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Modulis 02: Promptų inžinerija su GPT-5.2 +# 02 modulis: Užklausų inžinerija su GPT-5.2 ## Turinys -- [Vaizdo įrašo apžvalga](../../../02-prompt-engineering) -- [Ko išmoksite](../../../02-prompt-engineering) -- [Reikalavimai](../../../02-prompt-engineering) -- [Promptų Inžinerijos Suvokimas](../../../02-prompt-engineering) -- [Promptų Inžinerijos Pagrindai](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Grandinės mintis](../../../02-prompt-engineering) - - [Rolės pagrindu kuriamas promptas](../../../02-prompt-engineering) - - [Promptų šablonai](../../../02-prompt-engineering) -- [Pažangios struktūros](../../../02-prompt-engineering) -- [Paleiskite programą](../../../02-prompt-engineering) -- [Programos ekrano nuotraukos](../../../02-prompt-engineering) -- [Mokslo struktūrų tyrinėjimas](../../../02-prompt-engineering) - - [Mažas ir didelis entuziazmas](../../../02-prompt-engineering) - - [Užduoties vykdymas (Įrankių įvadas)](../../../02-prompt-engineering) - - [Savi reflektuojantis kodas](../../../02-prompt-engineering) - - [Struktūrinė analizė](../../../02-prompt-engineering) - - [Daugiapakopis pokalbis](../../../02-prompt-engineering) - - [Žingsnis po žingsnio argumentavimas](../../../02-prompt-engineering) - - [Ribotas išvesties formatas](../../../02-prompt-engineering) -- [Ką iš tiesų išmoksite](../../../02-prompt-engineering) -- [Kiti žingsniai](../../../02-prompt-engineering) - -## Vaizdo įrašo apžvalga - -Peržiūrėkite šią tiesioginę sesiją, kuri paaiškina, kaip pradėti darbą su šiuo moduliu: - -Promptų inžinerija su LangChain4j - tiesioginė sesija +- [Vaizdo įrašo peržiūra](#vaizdo-įrašo-peržiūra) +- [Ko išmoksite](#ko-išmoksite) +- [Priešmokymai](#priešmokymai) +- [Supratimas apie užklausų inžineriją](#supratimas-apie-užklausų-inžineriją) +- [Užklausų inžinerijos pagrindai](#užklausų-inžinerijos-pagrindai) + - [Zero-Shot užklausos](#zero-shot-užklausos) + - [Few-Shot užklausos](#few-shot-užklausos) + - [Grandininio mąstymo užklausos](#grandininio-mąstymo-užklausos) + - [Rolės pagrindu paremtos užklausos](#rolės-pagrindu-paremtos-užklausos) + - [Užklausų šablonai](#užklausų-šablonai) +- [Pažangiosios šablonai](#pažangiosios-šablonai) +- [Programos paleidimas](#programos-paleidimas) +- [Programos ekrano kopijos](#programos-ekrano-vaizdai) +- [Šablonų tyrinėjimas](#modelių-tyrinėjimas) + - [Mažas ir didelis entuziazmas](#mažas-ir-didelis-entuziazmas-low-vs-high-eagerness) + - [Užduoties vykdymas (įrankių preambulės)](#užduočių-vykdymas-įrankių-įvadai) + - [Savirefleksinis kodas](#savianalizės-kodas-self-reflecting-code) + - [Struktūruota analizė](#strukturizuota-analizė) + - [Daugiaetapiai pokalbiai](#daugkartinis-pokalbis) + - [Žingsnis po žingsnio mąstymas](#žingsnis-po-žingsnio-mąstymas) + - [Apribotas išvestis](#apribotas-išvesties-formatas) +- [Tikrasis mokymasis](#ko-išties-išmokstate) +- [Kiti žingsniai](#tolimesni-žingsniai) + +## Vaizdo įrašo peržiūra + +Peržiūrėkite šią tiesioginę sesiją, kurioje paaiškinama, kaip pradėti darbą su šiuo moduliu: + +Prompt Engineering with LangChain4j - Live Session ## Ko išmoksite -Ši diagrama apžvelgia pagrindines temas ir įgūdžius, kuriuos įgysite šiame modulyje — nuo promptų tobulinimo technikų iki žingsnis po žingsnio darbo eigos, kurios laikysitės. +Toliau pateiktas diagramas apžvelgia pagrindines temas ir įgūdžius, kuriuos įgysite šio modulio metu — nuo užklausų tobulinimo technikų iki žingsnis po žingsnio darbo eigos. -Ko išmoksite +What You'll Learn -Anksčiau moduliuose tyrinėjote pagrindinius LangChain4j sąveikos su GitHub modeliais pavyzdžius ir matėte, kaip atmintis leidžia palaikyti pokalbių AI naudojant Azure OpenAI. Dabar sutelksime dėmesį į tai, kaip užduodate klausimus — pačius promptus — naudodami Azure OpenAI GPT-5.2. Jūsų promptų struktūra dramatiškai įtakoja atsakymų kokybę. Pradedame nuo pagrindinių promptų technikų apžvalgos, po to pereiname prie aštuonių pažangių struktūrų, kurios visiškai išnaudoja GPT-5.2 galimybes. +Ankstesniame modulyje matėte, kaip atmintis leidžia pokalbių dirbtiniam intelektui naudoti Azure OpenAI. Dabar sutelksime dėmesį į tai, kaip užduodate klausimus — pačias užklausas — naudojant Azure OpenAI GPT-5.2. Užklausų struktūra smarkiai veikia gaunamų atsakymų kokybę. Pradedame nuo pagrindinių užklausų technikų apžvalgos, o vėliau pereisime prie aštuonių pažangių šablonų, atskleidžiančių GPT-5.2 galimybes. -Naudosime GPT-5.2, nes jis įveda samprotavimo valdymą - galite nurodyti modeliui, kiek mąstymo atlikti prieš atsakant. Tai pabrėžia skirtingas promptų strategijas ir padeda suprasti, kada naudoti kurią. Taip pat pasinaudosime mažesniais GPT-5.2 Azure apribojimais, palyginti su GitHub modeliais. +Naudosime GPT-5.2, nes jis įveda mąstymo kontrolę – galite pasakyti modeliui, kiek jis turi pagalvoti prieš atsakydamas. Tai daro skirtingas užklausų strategijas aiškesnes ir padeda suprasti, kada naudoti įvairius metodus. -## Reikalavimai +## Priešmokymai -- Įvykdytas modulis 01 (Azure OpenAI ištekliai diegti) -- `.env` failas pagrindiniame kataloge su Azure kredencialais (sukurtas vykdant `azd up` modulyje 01) +- Baigtas 01 modulis (Azure OpenAI ištekliai paskelbti) +- `.env` failas šakniniame kataloge su Azure prisijungimo duomenimis (sukurtas naudojant `azd up` 01 modulyje) -> **Pastaba:** Jei dar neįvykdėte modulio 01, pirmiausia atlikite diegimo instrukcijas ten. +> **Pastaba:** Jei nebaigėte 01 modulio, pirmiausia vykdykite jame pateiktas diegimo instrukcijas. -## Promptų inžinerijos suvokimas +## Supratimas apie užklausų inžineriją -Iš esmės promptų inžinerija yra skirtumas tarp miglotų ir tikslių nurodymų, kaip žemiau palyginta. +Iš esmės užklausų inžinerija yra skirtumas tarp neaiškių instrukcijų ir tikslių nurodymų, kaip iliustruoja žemiau pateiktas palyginimas. -Kas yra promptų inžinerija? +What is Prompt Engineering? -Promptų inžinerija yra įvesties teksto kūrimas, kuris nuosekliai duoda jums reikalingus rezultatus. Tai ne tik klausimų uždavimas - tai užklausų struktūrizavimas, kad modelis tiksliai suprastų, ko norite ir kaip tai pateikti. +Užklausų inžinerija reiškia įvesties teksto kūrimą, kuris nuosekliai suteikia reikiamus rezultatus. Tai ne tik klausimų uždavimas — tai prašymų struktūrizavimas taip, kad modelis tiksliai suprastų, ko norite ir kaip tai pateikti. -Įsivaizduokite, kad duodate nurodymus kolegai. „Pataisyk klaidą“ yra miglota. „Pataisyk null pointer exception UserService.java faile, eilutėje 45, pridėdamas null patikrą“ yra specifikuota. Kalbos modeliai veikia ta pati logika - specifika ir struktūra yra svarbios. +Galvokite apie tai, kaip instrukcijų suteikimą kolegai. „Pataisyk klaidą“ yra neaišku. „Pataisyk null pointer exception UserService.java 45 eilutėje pridėdamas null tikrinimą“ yra konkretu. Kalbų modeliai veikia taip pat – svarbi tikslių ir struktūrizuotų instrukcijų reikšmė. -Žemiau diagrama parodo, kaip LangChain4j įsilieja į šią sistemą — jungiant jūsų promptų šablonus su modeliu per SystemMessage ir UserMessage statybos blokėlius. +Žemiau pateikta schema rodo, kaip LangChain4j įsilieja į šį procesą — jungia jūsų užklausų šablonus su modeliu per `SystemMessage` ir `UserMessage` konstrukcijas. -Kaip LangChain4j įsilieja +How LangChain4j Fits -LangChain4j suteikia infrastruktūrą — modelio jungtis, atmintį ir žinučių tipus — o promptų šablonai yra tiesiog kruopščiai suformuotas tekstas, kuriuo perduodate per tą infrastruktūrą. Pagrindiniai statybos blokai yra `SystemMessage` (nustato AI elgesį ir rolę) ir `UserMessage` (neša jūsų faktinį prašymą). +LangChain4j teikia infrastruktūrą — modelių jungtis, atmintį ir žinučių tipus — o užklausų šablonai yra tiesiog kruopščiai struktūruotas tekstas, siunčiamas per šią infrastruktūrą. Pagrindiniai statybiniai blokai yra `SystemMessage` (nustato DI elgesį ir vaidmenį) bei `UserMessage` (talpina jūsų užklausą). -## Promptų inžinerijos pagrindai +## Užklausų inžinerijos pagrindai -Penki pagrindiniai metodai pateikti žemiau sudaro efektyvios promptų inžinerijos pagrindą. Kiekvienas iš jų sprendžia skirtingą, kaip bendraujate su kalbos modeliais, aspektą. +Žemiau parodytos penkios pagrindinės technikos formuoja efektyvios užklausų inžinerijos pagrindą. Kiekviena sprendžia skirtingą kalbos modelių bendravimo aspektą. -Penki promptų inžinerijos šablonai - apžvalga +Five Prompt Engineering Patterns Overview -Prieš pereidami prie pažangių šablonų šiame modulyje, apžvelkime penkias pagrindines promptų technikas. Tai statybiniai blokai, kuriuos turėtų pažinti kiekvienas promptų inžinierius. Jei jau dirbote su [greito starto moduliu](../00-quick-start/README.md#2-prompt-patterns), matėte juos veikime — čia jų konceptualus pagrindas. +Prieš pradedant pažangius šablonus šiame modulyje, apžvelkime penkias pagrindines užklausų technikas. Tai yra statybiniai blokai, kuriuos turi žinoti kiekvienas užklausų inžinierius. -### Zero-Shot Prompting +### Zero-Shot užklausos -Paprastasis metodas: suteikite modeliui tiesioginį nurodymą be pavyzdžių. Modelis visiškai pasikliauja savo mokymu suprasti ir atlikti užduotį. Tai gerai veikia paprastoms užklausoms, kai elgsena yra aiški. +Paprastumiausias metodas: duoti modeliui tiesioginę instrukciją be pavyzdžių. Modelis visiškai pasikliauja savo mokymu, kad suprastų ir įvykdytų užduotį. Tai gerai veikia paprastoms užklausoms, kur numatytas elgesys aiškus. Zero-Shot Prompting -*Tiesioginis nurodymas be pavyzdžių — modelis daro išvadą apie užduotį remdamasis tik nurodymu* +*Tiesioginė instrukcija be pavyzdžių — modelis nuspėja užduotį tik iš instrukcijos* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// Atsakymas: „Teigiamas“ +// Atsakymas: "Teigiamas" ``` -**Kada naudoti:** paprastoms klasifikacijoms, tiesioginiams klausimams, vertimams ar kitoms užduotims, kur modelis gali dirbti be papildomų nurodymų. +**Kada naudoti:** paprasta klasifikacija, tiesioginiai klausimai, vertimai arba bet kokia užduotis, kurią modelis gali atlikti be papildomų nurodymų. -### Few-Shot Prompting +### Few-Shot užklausos -Pateikite pavyzdžių, kurie demonstruoja modelio pageidaujamą šabloną. Modelis išmoksta tikėtino įvesties-išvesties formato pagal jūsų pavyzdžius ir taiko jį naujoms įvestims. Tai dramatiškai pagerina nuoseklumą užduotyse, kuriose norimas formatas ar elgsena nėra akivaizdūs. +Pateikite pavyzdžių, demonstruojančių modelio sekamą šabloną. Modelis iš jūsų pavyzdžių išmoksta reikiamą įvesties-išvesties formatą ir taiko jį naujoms įvestims. Tai žymiai pagerina nuoseklumą užduotyse, kur pageidaujamas formatas arba elgesys nėra akivaizdus. Few-Shot Prompting -*Mokymasis iš pavyzdžių — modelis identifikuoja šabloną ir taiko jį naujoms įvestims* +*Mokymasis iš pavyzdžių — modelis atpažįsta šabloną ir taiko naujoms įvestims* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kada naudoti:** suasmenintoms klasifikacijoms, nuosekliam formatavimui, domeno specifinėms užduotims ar kai zero-shot rezultatai yra nevienodi. +**Kada naudoti:** individualios klasifikacijos, nuoseklus formatavimas, domeno specifinės užduotys arba kai zero-shot rezultatai yra nenuoseklūs. -### Grandinės mintis +### Grandininio mąstymo užklausos -Prašykite modelio parodyti savo samprotavimą žingsnis po žingsnio. Vietoj tiesioginio atsakymo, modelis suskaido problemą ir aiškiai dirba su kiekviena dalimi. Tai pagerina tikslumą matematikos, logikos ir daugiažingsnių užduočių atvejais. +Paprašykite modelio parodyti savo mąstymą žingsnis po žingsnio. Vietoje tiesioginio atsakymo modelis išskaido problemą ir išsamiai ją analizuoja. Tai pagerina tikslumą matematikos, logikos ir daugelio žingsnių mąstymo užduotyse. -Grandinės mintis - Promptinimas +Chain of Thought Prompting -*Žingsnis po žingsnio argumentavimas — sudėtingų problemų suskaidymas į aiškius loginius žingsnius* +*Žingsnis po žingsnio mąstymas — sudėtingų problemų dalijimas į aiškius loginius žingsnius* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Modelis rodo: 15 - 8 = 7, tada 7 + 12 = 19 obuolių ``` -**Kada naudoti:** matematikos užduotims, logikos galvosūkiams, derinimui ar kitoms užduotims, kuriose mąstymo proceso demonstravimas gerina tikslumą ir pasitikėjimą. +**Kada naudoti:** matematinės problemos, loginiai galvosūkiai, klaidų taisymas arba bet kokia užduotis, kurioje mąstymo proceso demonstravimas gerina tikslumą ir pasitikėjimą. -### Rolės pagrindu kuriamas promptas +### Rolės pagrindu paremtos užklausos -Nustatykite AI personažą ar vaidmenį prieš užduodami klausimą. Tai suteikia kontekstą, kuris formuoja tono, gilumo ir atsakymo fokuso pobūdį. „Programinės įrangos architektas“ pateikia kitokią rekomendaciją nei „jaunesnysis programuotojas“ ar „saugumo auditorius“. +Nustatykite DI personą arba vaidmenį prieš užduodami klausimą. Tai suteikia kontekstą, kuris formuoja atsakymo toną, gylį ir fokusuotumą. „Programinės įrangos architektas“ duoda kitokius patarimus nei „jaunesnysis programuotojas“ arba „saugumo auditorius“. -Rolės pagrindu kuriamas promptas +Role-Based Prompting -*Konteksto ir personažo nustatymas — tas pats klausimas gauna skirtingą atsakymą priklausomai nuo priskirtos rolės* +*Kontexto ir personos nustatymas — tas pats klausimas gauna skirtingą atsakymą priklausomai nuo priskirto vaidmens* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kada naudoti:** kodo peržiūroms, mokymui, domeno specifinėms analizėms ar kai reikia atsakymų, pritaikytų pagal tam tikrą ekspertizės lygį ar perspektyvą. +**Kada naudoti:** kodo peržiūros, mokymas, domeno specifinė analizė arba kai reikia atsakymų, pritaikytų konkretaus lygio patirčiai ar perspektyvai. -### Promptų šablonai +### Užklausų šablonai -Sukurkite pakartotinai naudojamus promptus su kintamųjų vietomis. Užuot rašę naują promptą kiekvieną kartą, apibrėžkite šabloną kartą ir įterpkite skirtingas reikšmes. LangChain4j `PromptTemplate` klasė tai palengvina naudodama `{{variable}}` sintaksę. +Kurkite pakartotinai naudojamas užklausas su kintamaisiais žymekliais. Užuot rašę naują užklausą kiekvieną kartą, apibrėžkite šabloną vieną kartą ir užpildykite skirtingas reikšmes. LangChain4j `PromptTemplate` klasė tai supaprastina su `{{variable}}` sintakse. -Promptų šablonai +Prompt Templates -*Pakartotinai naudojami promptai su kintamųjų vietomis — vienas šablonas, daug panaudojimų* +*Pakartotinai naudojamos užklausos su kintamais žymekliais — vienas šablonas, daug panaudojimų* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Kada naudoti:** pasikartojančioms užklausoms su skirtinga įvestimi, masinėms apdorojimo užduotims, pakartotinai naudojamų AI darbo eigos kūrimui ar bet kuriai situacijai, kai prompto struktūra išlieka ta pati, bet duomenys keičiasi. +**Kada naudoti:** pasikartojančios užklausos su skirtingomis įvestimis, partijų apdorojimas, pakartotiniai DI darbo eigos kūrimas arba bet kuri situacija, kai užklausos struktūra išlieka ta pati, bet keičiasi duomenys. --- -Šie penki pagrindai suteikia jums tvirtą įrankių rinkinį daugumai promptų užduočių. Likusi šio modulio dalis plėtoja juos su **aštuoniais pažangiais šablonais**, kurie išnaudoja GPT-5.2 samprotavimo valdymą, savęs vertinimą ir struktūruotos išvesties galimybes. +Šios penkios pagrindinės technikos suteikia jums tvirtą įrankių rinkinį daugumai užklausų. Likusi šio modulio dalis plečia jas su **aštuoniais pažangiais šablonais**, kurie išnaudoja GPT-5.2 mąstymo kontrolę, savivertinimą ir struktūruotų išvesties galimybes. -## Pažangios struktūros +## Pažangiosios šablonai -Įvaldę pagrindus, pereikime prie aštuonių pažangių šablonų, kurie daro šį modulį unikaliai. Ne visiems klausimams reikia tokio paties požiūrio. Kai kurie reikalauja greitų atsakymų, kiti gilios analizės. Kai kuriems reikalingas matomas samprotavimas, kitiems tik rezultatai. Kiekvienas žemiau pateiktas šablonas yra optimizuotas skirtingam scenarijui — o GPT-5.2 samprotavimo valdymas šiuos skirtumus dar labiau pabrėžia. +Išmokę pagrindus, pereikime prie aštuonių pažangių šablonų, kurie daro šį modulį unikalų. Ne visoms problemoms tinka tas pats požiūris. Kai kurie klausimai reikalauja greitų atsakymų, kiti – gilios analizės. Kai kuriems reikia matomo mąstymo, kitiems – tiesiog rezultatų. Kiekvienas žemiau pateiktas šablonas optimizuotas skirtingam scenarijui — o GPT-5.2 mąstymo kontrolė dar labiau sustiprina skirtumus. -Aštuoni promptų inžinerijos šablonai +Eight Prompting Patterns -*Aštuoni promptų inžinerijos šablonų ir jų panaudojimo apžvalga* +*Aštuonių užklausų inžinerijos šablonų apžvalga ir jų panaudojimo atvejai* -GPT-5.2 suteikia papildomą dimensiją šioms struktūroms: *samprotavimo valdymą*. Žemiau esantis slankiklis rodo, kaip galite reguliuoti modeliui skirtą mąstymo pastangų kiekį — nuo greitų, tiesioginių atsakymų iki gilaus, kruopštaus analizavimo. +GPT-5.2 įveda dar vieną šių šablonų dimensiją: *mąstymo kontrolę*. Žemiau esantis slankiklis rodo, kaip galite reguliuoti, kiek modeliui reikia galvoti – nuo greitų tiesioginių atsakymų iki gilaus, išsamaus analizavimo. -Samprotavimo valdymas su GPT-5.2 +Reasoning Control with GPT-5.2 -*GPT-5.2 samprotavimo valdymas leidžia nurodyti, kiek mąstymo modelis turi atlikti — nuo greitų tiesioginių atsakymų iki gilios analizės* +*GPT-5.2 mąstymo kontrolė leidžia nurodyti, kiek mąstymo turi atlikti modelis — nuo greitų tiesioginių atsakymų iki gilaus tyrinėjimo* -**Mažas entuziazmas (Greita & Tiksli)** - Skirti paprastiems klausimams, kur reikia greitų, tiesioginių atsakymų. Modelis atlieka minimalų samprotavimą – daugiausia 2 žingsnius. Naudokite skaičiavimams, paieškoms ar tiesioginiams klausimams. +**Mažas entuziazmas (Greita ir tikslinė)** – paprastiems klausimams, kur norite greitų, tiesioginių atsakymų. Modelis atlieka minimalią analizę – daugiausia 2 žingsnius. Naudokite tai skaičiavimams, paieškoms ar paprastiems klausimams. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Išbandykite su GitHub Copilot:** Atidarykite [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ir paklauskite: -> - „Kuo skiriasi mažo ir didelio entuziazmo promptų šablonai?“ -> - „Kaip XML žymos promptuose padeda struktūruoti AI atsakymą?“ -> - „Kada naudoti savęs reflektavimo šablonus, o kada tiesioginius nurodymus?“ +> 💡 **Tyrinėkite su GitHub Copilot:** Atidarykite [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ir paklauskite: +> - "Kuo skiriasi mažo ir didelio entuziazmo užklausų šablonai?" +> - "Kaip XML žymos užklausose padeda struktūrizuoti AI atsakymą?" +> - "Kada naudoti savirefleksijos šablonus, o kada tiesioginę instrukciją?" -**Didelis entuziazmas (Gilumas & Kruopštumas)** - Skirta sudėtingoms problemoms, kur norite išsamių analizų. Modelis kruopščiai gilina problemą ir rodo detalias mintis. Naudojama sistemų projektavimui, architektūros sprendimams arba sudėtingiems tyrimams. +**Didelis entuziazmas (Gilus ir kruopštus)** – sudėtingoms problemoms, kai reikia išsamios analizės. Modelis atlieka išsamų tyrimą ir pateikia detalų mąstymą. Naudokite tai sistemos dizaino, architektūros sprendimams arba sudėtingiems tyrimams. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Užduoties vykdymas (Žingsnis po žingsnio pažanga)** - Skirta daugiažingsnėms darbo eigoms. Modelis pateikia pradžioje planą, pasako apie kiekvieną žingsnį dirbdamas, tada pateikia santrauką. Naudokite migracijoms, įgyvendinimams ar bet kokiai daugiažingsnei veiklai. +**Užduoties vykdymas (žingsnis po žingsnio pažanga)** – daugiaetapiams darbo eigos procesams. Modelis pateikia išankstinį planą, pasakoja apie kiekvieną žingsnį jį vykdydamas, po to apibendrina. Naudokite migracijoms, įgyvendinimams ar bet kuriam daugiaetapiam procesui. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Grandinės minties promptinimas aiškiai ragina modelį parodyti samprotavimo procesą, kas pagerina sudėtingų užduočių tikslumą. Žingsnis po žingsnio analizė padeda tiek žmonėms, tiek AI suprasti logiką. +Grandininio mąstymo užklausos aiškiai prašo modelio parodyti savo mąstymo procesą, kas pagerina tikslumą sudėtingų užduočių sprendimuose. Žingsnis po žingsnio suskaidymas padeda suprasti logiką tiek žmonėms, tiek DI. > **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) pokalbiu:** Paklauskite apie šį šabloną: -> - „Kaip pritaikyčiau užduoties vykdymo šabloną ilgiau trunkančioms operacijoms?“ -> - „Kokios yra geriausios praktikos įrankių įvadų struktūravimui gamybinėse programose?“ -> - „Kaip fiksuoti ir rodyti tarpinę pažangą UI?“ +> - "Kaip adaptuočiau užduoties vykdymo šabloną ilgai trukmės operacijoms?" +> - "Kokios yra geriausios praktikos struktūrizuojant įrankių preambules gamybos programose?" +> - "Kaip fiksuoti ir rodyti tarpinę pažangą naudotojo sąsajoje?" -Žemiau pateikta diagrama iliustruoja šią Plan → Vykdyti → Santrauka darbo eigą. +Žemiau pateikta schema iliustruoja šią Plan → Vykdyti → Apibendrinti darbo eigą. -Užduoties vykdymo šablonas +Task Execution Pattern -*Planavimas → Vykdymas → Santrauka daugiažingsnėms užduotims* +*Plan → Vykdyti → Apibendrinti darbo eiga daugiaetapėms užduotims* -**Savi reflektuojantis kodas** - Skirta generuoti gamybinės kokybės kodui. Modelis kuria kodą vadovaudamasis gamybos standartais su tinkamu klaidų valdymu. Naudojama kuriant naujas funkcijas ar paslaugas. +**Savirefleksinis kodas** – gamybinės kokybės kodo generavimui. Modelis generuoja kodą laikydamasis gamybinei programinei įrangai keliamų reikalavimų su tinkama klaidų tvarkymo logika. Naudokite tai kuriant naujas funkcijas ar paslaugas. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Žemiau diagrama rodo šią iteratyvios tobulinimo ciklą — generavimą, vertinimą, silpnųjų vietų nustatymą ir tobulinimą, kol kodas atitinka gamybos standartus. +Žemiau pateikta schema rodo šį iteracinio tobulinimo ciklą – generuoti, vertinti, identifikuoti silpnas vietas ir tobulinti, kol kodas atitinka gamybinius standartus. -Savi reflektavimo ciklas +Self-Reflection Cycle -*Iteratyvus tobulinimo ciklas - generuoti, vertinti, identifikuoti problemas, gerinti, kartoti* +*Iteracinio tobulinimo ciklas – generuoti, vertinti, rasti problemas, gerinti, kartoti* -**Struktūrinė analizė** - Nuosekliam vertinimui. Modelis peržiūri kodą naudodamas fiksuotą sistemą (teisingumas, praktikos, našumas, saugumas, priežiūra). Naudojama kodo peržiūroms ar kokybės įvertinimams. +**Struktūruota analizė** – nuosekliai vertinti. Modelis peržiūri kodą naudodamas fiksuotą sistemą (teisingumas, geros praktikos, veikimas, saugumas, prižiūrimumas). Naudokite tai kodo peržiūroms arba kokybės vertinimams. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) pokalbiu:** Paklauskite apie struktūrinę analizę: -> - „Kaip pritaikyti analizės sistemą skirtingo tipo kodo peržiūroms?“ -> - „Koks geriausias būdas programiškai išskaidyti ir veikti pagal struktūrizuotą išvestį?“ -> - „Kaip užtikrinti nuoseklius reikšmingumo lygius skirtingose peržiūros sesijose?“ +> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) pokalbiu:** Paklauskite apie struktūruotą analizę: +> - "Kaip pritaikyti analizės sistemą skirtingoms kodo peržiūroms?" +> - "Kokia geriausia praktika programiškai apdoroti struktūruotą išvestį?" +> - "Kaip užtikrinti nuoseklius sunkumo lygius skirtinguose peržiūros seansuose?" -Žemiau pateikta diagrama parodo, kaip ši struktūrinė sistema organizuoja kodo peržiūrą nuosekliomis kategorijomis su reikšmingumo lygiais. +Žemiau pateikta schema rodo, kaip ši struktūruota sistema organizuoja kodo peržiūrą į nuoseklias kategorijas ir sunkumo lygius. -Struktūrinės analizės šablonas +Structured Analysis Pattern -*Kodo peržiūrų nuoseklumo sistema su reikšmingumo lygiais* +*Sistema nuoseklioms kodo peržiūroms su sunkumo lygiais* -**Daugiapakopis pokalbis** - Pokalbiams, kuriems reikalingas kontekstas. Modelis prisimena ankstesnes žinutes ir juo remiasi. Naudojama interaktyvioms pagalbos sesijoms ar sudėtingoms Q&A. +**Daugiaetapiai pokalbiai** – pokalbiams, kuriems reikalingas kontekstas. Modelis prisimena ankstesnes žinutes ir kuria jas toliau. Naudokite tai interaktyvioms pagalbos sesijoms arba sudėtingiems klausimų-atsakymų veiksmams. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Žemiau diagrama vizualizuoja, kaip pokalbio kontekstas kaupiasi su kiekvienu žingsniu ir kaip tai susiję su modelio tokenų limitu. +Schema žemiau vizualizuoja, kaip kontekstas kaupiasi per kelis pokalbio žingsnius ir kaip tai susiję su modelio tokenų limitu. -Konteksto atmintis +Context Memory -*Kaip pokalbio kontekstas kaupiasi daugeliu žingsnių iki pasiekiant tokenų limitą* -**Žingsnis po žingsnio mąstymas** – Skirta problemoms, kurioms reikalinga matoma logika. Modelis aiškiai parodo samprotavimus kiekviename žingsnyje. Naudokite tai matematiniams uždaviniams, logikos galvosūkams ar kai reikia suprasti mąstymo procesą. +*Kaip pokalbio kontekstas kaupiasi per daugiau nei vieną žingsnį iki tokenų limito pasiekimo* + +**Žingsnis po žingsnio mąstymas** – problemoms, kurioms reikia matomos logikos. Modelis rodo aiškų kiekvieno žingsnio mąstymo procesą. Naudokite tai matematikos uždaviniams, logikos galvosūkiams arba kai norite suprasti mąstymo eigą. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Žemiau pateiktas diagrama iliustruoja, kaip modelis suskaido problemas į aiškius, numeruotus loginius žingsnius. +Žemiau pateikta schema iliustruoja, kaip modelis skaido problemas į aiškius, sunumeruotus loginius žingsnius. Step-by-Step Pattern - *Probleminių uždavinių suskaidymas į aiškius loginius žingsnius* -**Apribotas išvesties formatas** – Skirta atsakymams su konkrečiomis formato reikalavimų taisyklėmis. Modelis griežtai laikosi formato ir ilgio taisyklių. Naudokite tai santraukoms arba kai reikalinga tiksli išvesties struktūra. +**Apribotas Išvestis** – Atsakymams su konkrečiais formato reikalavimais. Modelis griežtai laikosi formato ir ilgumo taisyklių. Naudokite tai suvestinėms arba kai reikia tikslios išvesties struktūros. ```java String prompt = """ @@ -420,61 +420,61 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Žemiau pateikta diagrama rodo, kaip apribojimai nukreipia modelį generuoti išvestį, kuri griežtai atitinka jūsų formato ir ilgio reikalavimus. +Toliau pateiktas paveikslėlis rodo, kaip apribojimai nukreipia modelį generuoti išvestį, kuri griežtai atitinka jūsų formatą ir ilgumo reikalavimus. -Constrained Output Pattern +Apriboto išvesties modelio pavyzdys -*Specialių formato, ilgio ir struktūros reikalavimų užtikrinimas* +*Reikalavimų formatui, ilgumui ir struktūrai taikymas* -## Paleiskite programą +## Programos paleidimas **Patikrinkite diegimą:** -Įsitikinkite, kad projekto šakniniame kataloge egzistuoja `.env` failas su Azure kredencialais (sukurtais Modulyje 01). Paleiskite tai iš modulio katalogo (`02-prompt-engineering/`): +Įsitikinkite, kad `.env` failas egzistuoja pagrindiniame kataloge su Azure prisijungimo duomenimis (sukurti 1 modulyje). Paleiskite tai iš modulio katalogo (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Turėtų parodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Turėtų parodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Paleiskite programą:** -> **Pastaba:** Jei jau paleidote visas programas naudodami `./start-all.sh` iš šakniniame katalogo (kaip aprašyta Modulyje 01), šis modulis jau veikia 8083 prievade. Galite praleisti žemiau pateiktas starto komandas ir tiesiogiai nueiti į http://localhost:8083. +> **Pastaba:** Jei jau paleidote visas programas naudodami `./start-all.sh` iš pagrindinio katalogo (kaip aprašyta 1 modulyje), šis modulis jau veikia 8083 prievade. Galite praleisti žemiau pateiktas paleidimo komandas ir tiesiogiai eiti į http://localhost:8083. **1 variantas: Naudojant Spring Boot Dashboard (rekomenduojama VS Code naudotojams)** -Dev konteineryje yra Spring Boot Dashboard plėtinys, kuris suteikia vizualią sąsają visoms Spring Boot programoms valdyti. Jį rasite Aktyvumo juostoje kairėje VS Code pusėje (ieškokite Spring Boot ikonos). +Dev container įtraukia Spring Boot Dashboard plėtinį, kuris suteikia vizualią sąsają visoms Spring Boot programoms valdyti. Jį rasite Activity Bar kairėje VS Code pusėje (ieškokite Spring Boot ikonos). Iš Spring Boot Dashboard galite: -- Matyti visas darbo aplinkoje esančias Spring Boot programas -- Vienu spustelėjimu paleisti/stabdyti programas -- Realiai matyti programų žurnalus -- Stebėti programų būseną +- Peržiūrėti visas darbo erdvėje esančias Spring Boot programas +- Paleisti / sustabdyti programas vienu paspaudimu +- Realizuoti programos žurnalus realiu laiku +- Stebėti programos būseną -Tiesiog spustelėkite paleidimo mygtuką šalia „prompt-engineering“, kad paleistumėte šį modulį, arba paleiskite visus modulius vienu metu. +Tiesiog paspauskite paleidimo mygtuką šalia „prompt-engineering“, kad paleistumėte šį modulį, arba paleiskite visus modulius vienu metu. -Spring Boot Dashboard +Spring Boot valdymo pultas -*Spring Boot Dashboard VS Code — paleiskite, stabdykite ir stebėkite visus modulius iš vienos vietos* +*Spring Boot Dashboard VS Code — paleiskite, sustabdykite ir stebėkite visus modulius vienoje vietoje* -**2 variantas: Naudojant shell skriptus** +**2 variantas: Naudojant shell scenarijus** -Paleiskite visas interneto programas (modulius 01-04): +Paleiskite visas interneto programas (1–4 moduliai): **Bash:** ```bash -cd .. # Iš šaknies katalogo +cd .. # Iš šakninių katalogų ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Iš šakninio katalogo +cd .. # Iš šakninių katalogų .\start-all.ps1 ``` @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Abu skriptai automatiškai įkelia aplinkos kintamuosius iš šakniniame kataloge esančio `.env` failo ir sukurs JAR failus, jei jų nėra. +Abu scenarijai automatiškai įkelia aplinkos kintamuosius iš pagrindinio `.env` failo ir sukurs JAR failus, jei jų nėra. -> **Pastaba:** Jei norite rankiniu būdu sukompiliuoti visus modulius prieš paleidimą: +> **Pastaba:** Jei norite visus modulius sukompiliuoti rankiniu būdu prieš paleidimą: > > **Bash:** > ```bash @@ -526,83 +526,83 @@ cd .. && ./stop-all.sh # Visi moduliai cd ..; .\stop-all.ps1 # Visi moduliai ``` -## Programos ekrano kopijos +## Programos ekrano vaizdai -Čia pagrindinė promptų kūrimo modulio sąsaja, kur galite eksperimentuoti su visais aštuoniais šablonais lygiagrečiai. +Čia pagrindinė promptų inžinerijos modulio sąsaja, kur galite eksperimentuoti su visais aštuoniais modeliais iš karto. -Dashboard Home +Pagrindinis pultas -*Pagrindinis valdymo skydelis, rodantis visus 8 promptų kūrimo šablonus su jų charakteristikomis ir panaudojimo atvejais* +*Pagrindinis pultas su visais 8 promptų inžinerijos modeliais ir jų savybėmis bei naudojimo atvejais* -## Šablonų tyrinėjimas +## Modelių tyrinėjimas -Interneto sąsaja leidžia eksperimentuoti su įvairiomis promptų strategijomis. Kiekvienas šablonas sprendžia skirtingas problemas – išbandykite ir pamatykite, kada kuris metodas yra efektyvus. +Žiniatinklio sąsaja leidžia eksperimentuoti su įvairiomis prašymų strategijomis. Kiekvienas modelis sprendžia skirtingas problemas – išbandykite, kad pamatytumėte, kada kuris metodas geriausiai tinka. -> **Pastaba: Srautinio duomenų perdavimo (Streaming) ir nesrautinio skirtumai** — Kiekvieno šablono puslapyje yra du mygtukai: **🔴 Srautinis atsakas (Realtime)** ir **Nesrautinės** versijos pasirinkimas. Srautinis perdavimas naudoja Server-Sent Events (SSE) ir rodo žodžius realiu laiku, kai modelis juos generuoja, tad matote progresą iš karto. Nesrautinė versija laukia viso atsakymo pabaigos. Gilų samprotavimą reikalaujančiose užklausose (pvz., Aukštas entuziazmas, Savianalizuojantis kodas) nesrautinės versijos kvietimas gali užtrukti ilgai – kartais kelias minutes – be jokios matomos informacijos. **Naudokite srautinį režimą sudėtingiems užklausimams,** kad matytumėte modelio darbą ir išvengtumėte įspūdžio, kad užklausa užstrigo. +> **Pastaba: Srautinė ir nesrautinė išvestis** — Kiekviename modelio puslapyje yra du mygtukai: **🔴 Stream Response (Live)** ir **Non-streaming** variantas. Srautinė išvestis naudoja Server-Sent Events (SSE) ir rodo žodžius realiuoju laiku, kai modelis juos generuoja, todėl iš karto matote progreso eigą. Nesrautinė išvestis laukia viso atsakymo pabaigos, kad jį parodytų. Modeliams, kuriuos verčia gilus mąstymas (pvz., High Eagerness, Self-Reflecting Code), nesrautinė išvestis gali užtrukti labai ilgai – kartais kelias minutes – be jokios matomos grįžtamosios informacijos. **Eksperimentuojant su sudėtingais prašymais naudokite srautinę išvestį**, kad matytumėte modelio veikimą ir išvengtumėte klaidingo įspūdžio, kad prašymas užstringa. > -> **Pastaba: Naršyklės reikalavimas** — Srautinio režimo funkcija naudoja Fetch Streams API (`response.body.getReader()`), kuri reikalinga pilnavertei naršyklei (Chrome, Edge, Firefox, Safari). Ji **nesuveikia** VS Code integruotoje Simple Browser, nes jos žiniatinklio vaizdas nepalaiko ReadableStream API. Naudojant Simple Browser, nesrautiniai mygtukai veiks normaliai – paveikti tik srautiniai mygtukai. Atidarykite `http://localhost:8083` išorinėje naršyklėje, kad gautumėte visą funkcionalumą. +> **Pastaba: Naršyklės reikalavimai** — Srautinė funkcija naudoja Fetch Streams API (`response.body.getReader()`), kurią palaiko pilnos naršyklės (Chrome, Edge, Firefox, Safari). Ji **neveikia** VS Code integruotoje Simple Browser, nes ši nepalaiko ReadableStream API. Jei naudojate Simple Browser, nesrautiniai mygtukai veiks įprastai – paveikti yra tik srautiniai. Norėdami pilnos patirties, atidarykite `http://localhost:8083` išorinėje naršyklėje. -### Žemas ir aukštas entuziazmas +### Mažas ir didelis entuziazmas (Low vs High Eagerness) -Užduokite paprastą klausimą, pvz., „Kiek yra 15% iš 200?“ naudodami Žemą entuziazmą. Gausite greitą ir tiesioginį atsakymą. Dabar paklauskite sudėtingesnio, pvz., „Sukurkite talpyklos strategiją didelio srauto API“, naudodami Aukštą entuziazmą. Spauskite **🔴 Srautinį atsaką (Realtime)** ir stebėkite, kaip modelis pateikia detalius samprotavimus žodis po žodžio. Tas pats modelis, ta pati klausimo struktūra – bet užklausa nurodo, kiek mąstymo reikia. +Uždėkite lengvą klausimą, pavyzdžiui „Kiek yra 15 % iš 200?“, naudodami Mažą entuziazmą. Gaunate greitą ir tiesioginį atsakymą. Dabar užduokite sudėtingesnį klausimą, pvz., „Sukurkite aukšto srauto API kešavimo strategiją“ naudodami Didelį entuziazmą. Paspauskite **🔴 Stream Response (Live)** ir stebėkite, kaip modelis žingsnis po žingsnio detalizuoja mintis. Tas pats modelis, ta pati klausimo struktūra – skiriasi tik prašymas, nurodantis kiek mąstyti. -### Užduočių vykdymas (įrankių pradžios tekstai) +### Užduočių vykdymas (Įrankių įvadai) -Daugiapakopiai procesai naudingesni, kai iškart suplanuojamas veiksmas ir aprašomas progresas. Modelis numato, ką darys, aprašo kiekvieną žingsnį, tada apibendrina rezultatus. +Daugiapakopiai darbo eiga naudoja išankstinį planavimą ir progreso aprašymą. Modelis apibendrina, ką darys, aprašo kiekvieną žingsnį, po to pateikia rezultatų santrauką. -### Savianalizuojantis kodas +### Savianalizės kodas (Self-Reflecting Code) -Išbandykite „Sukurti el. pašto validacijos paslaugą“. Modelis ne tik sugeneruoja kodą ir sustoja, bet ir vertina pagal kokybės kriterijus, identifikuoja trūkumus ir tobulina. Matysite, kaip modelis iteruoja tol, kol kodas tenkina gamybinius standartus. +Išbandykite „Sukurk el. pašto validacijos servisą“. Vietoj to, kad tik sugeneruotų kodą ir sustotų, modelis generuoja, vertina pagal kokybės kriterijus, identifikuoja trūkumus ir tobulina. Matysite, kaip jis kartoja procesą tol, kol kodas pasiekia gamybos lygį. -### Struktūruota analizė +### Strukturizuota analizė -Kodo peržiūros reikalauja pastovių vertinimo sistemų. Modelis analizuoja kodą pagal fiksuotas kategorijas (teisingumas, praktikos, našumas, saugumas) su rimtumo lygiais. +Kodo apžvalgoms reikia nuoseklių vertinimo kriterijų. Modelis analizuoja kodą pagal fiksuotas kategorijas (teisingumas, praktikos, našumas, saugumas) su skirtingais griežtumo lygiais. -### Daugiabutis pokalbis +### Daugkartinis pokalbis -Paklauskite „Kas yra Spring Boot?“ ir iškart po to klauskit „Parodyk man pavyzdį“. Modelis prisimena jūsų pirmą klausimą ir pateikia konkrečius Spring Boot pavyzdžius. Be atminties tas antras klausimas būtų pernelyg neaiškus. +Paklauskite „Kas yra Spring Boot?“ ir tuoj pat pridėkite „Parodyk pavyzdį“. Modelis atsimena pirmą klausimą ir pateikia būtent su Spring Boot susijusį pavyzdį. Be atminties antras klausimas būtų per daug bendras. ### Žingsnis po žingsnio mąstymas -Pasirinkite matematinę užduotį ir išbandykite su Žingsnis po žingsnio mąstymu bei Žemu entuziazmu. Žemas entuziazmas greitai pateikia tik atsakymą – greita, bet neaišku. Žingsnis po žingsnio rodo kiekvieną skaičiavimą ir sprendimą. +Pasirinkite matematinę užduotį ir išbandykite ją naudodami tiek Žingsnis po žingsnio mąstymą, tiek Mažą entuziazmą. Mažas entuziazmas greitai pateikia atsakymą – tačiau jis neaiškus. Žingsnis po žingsnio parodo kiekvieną skaičiavimą ir sprendimą. -### Apribota išvestis +### Apribotas išvesties formatas -Kai reikia konkrečių formatų ar žodžių skaičiaus, šis šablonas užtikrina griežtą taisyklių laikymąsi. Išbandykite generuoti santrauką tiksliu 100 žodžių skaičiumi sąrašo formatu. +Kai reikia konkrečių formatų ar žodžių skaičiaus, šis modelis užtikrina griežtą laikymąsi. Išbandykite sugeneruoti apibendrinimą tiksliai su 100 žodžių bulleted formatu. -## Ko jūs iš tikrųjų mokotės +## Ko išties išmokstate -**Samprotavimo pastangos keičia viską** +**Mąstymo pastangos lemia viską** -GPT-5.2 leidžia valdyti skaičiavimo pastangas per savo užklausas. Mažos pastangos reiškia greitus atsakymus su minimaliu nagrinėjimu. Didelės pastangos reiškia, kad modelis skiria laiko giliam mąstymui. Jūs mokotės pritaikyti pastangas užduoties sudėtingumui – neskubėkite su paprastais klausimais, bet ir neleiskite sudėtingoms užduotims būti sprendžiamoms per greitai. +GPT-5.2 leidžia valdyti skaičiavimo pastangas per prašymus. Mažos pastangos reiškia greitus atsakymus su minimalia paieška. Didelės pastangos reiškia, kad modelis skiria laiko giliau mąstyti. Mokotės pritaikyti pastangas uždavinio sudėtingumui – neskubinkite paprastų klausimų, bet ir nepraleiskite svarbių sudėtingų sprendimų. -**Struktūra nukreipia elgesį** +**Struktūra valdo elgesį** -Pastebėjote XML žymes promptuose? Jos ne vien dekoratyvios. Modeliai labiau patikimai laikosi struktūruotų nurodymų nei laisvo teksto. Kai reikia daug žingsnių ar sudėtingos logikos, struktūra padeda modeliui sekti, kur jis yra ir kas bus toliau. Žemiau pateikta diagrama rodo gerai struktūruoto sodo prompto anatomiją, kur žymos kaip ``, ``, ``, ``, ir `` organizuoja jūsų nurodymus aiškiomis dalimis. +Pastebėjote XML žymes prašymuose? Jos nėra dekoratyvios. Modeliai labiau seka struktūrizuotus nurodymus nei laisvą tekstą. Kai reikia daugiapakopių procesų ar sudėtingos logikos, struktūra padeda modeliui žinoti, kur yra ir kas toliau. Žemiau pateiktas paveikslėlis analizuoja gerai struktūruotą prašymą, parodant, kaip žymės ``, ``, ``, ``, ir `` organizuoja instrukcijas aiškiomis dalimis. -Prompt Structure +Prompto struktūra -*Gerai struktūruoto prompto anatomija su aiškiomis dalimis ir XML stiliaus organizacija* +*Gerai struktūruoto prašymo anatomija su aiškiomis dalimis ir XML stiliaus organizacija* **Kokybė per savianalizę** -Savianalizuojantys šablonai veikia nurodant kokybės kriterijus aiškiai. Vietoje to, kad tikėtumėtės, jog modelis „tai padarys gerai“, jūs tiesiogiai nurodote, ką reiškia „gerai“: teisinga logika, klaidų valdymas, našumas, saugumas. Tuomet modelis gali įvertinti savo išvestį ir tobulėti. Tai pokyčių kodų generavimą iš loterijos į procesą. +Savianalizės modeliai naudoja aiškius kokybės kriterijus. Vietoje to, kad tikėtumėtės, jog modelis „atliks teisingai“, jūs tiksliai nurodote, ką reiškia „teisingai“: taisyklinga logika, klaidų tvarkymas, našumas, saugumas. Modelis tada gali įvertinti savo išvestį ir patobulinti ją. Tai paverčia kodo generavimą ne loterija, o procesu. **Kontekstas yra ribotas** -Daugiabutis pokalbis veikia įtraukiant žinutės istoriją su kiekvienu užklausa. Bet yra ribos – kiekvienas modelis turi maksimalią žodžių/ženklų ribą. Augant pokalbiui, teks naudoti strategijas palaikyti aktualų kontekstą, nepersikeliant virš ribos. Šis modulis parodo, kaip veikia atmintis; vėliau sužinosite, kada apibendrinti, kada pamiršti ir kada atkurti informaciją. +Daugkartiniai pokalbiai veikia, kai kiekviename užklausoje siunčiate žinučių istoriją. Tačiau yra apribojimas – kiekvienas modelis turi maksimalų žodžių skaičių. Pokalbiui augant, jums reikės strategijų, kaip išlaikyti svarbų kontekstą, bet neviršyti ribos. Šis modulis parodo, kaip veikia atmintis; vėliau sužinosite, kada santrumpinti, kada pamiršti ir kada atsiminti. -## Tolimesni veiksmai +## Tolimesni žingsniai **Kitas modulis:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Naršymas:** [← Ankstesnis: Modulis 01 - Įvadas](../01-introduction/README.md) | [Grįžti į pagrindinį](../README.md) | [Kitas: Modulis 03 - RAG →](../03-rag/README.md) +**Navigacija:** [← Ankstesnis: 01 modulis – Įvadas](../01-introduction/README.md) | [Grįžti į pagrindinį](../README.md) | [Kitas: 03 modulis – RAG →](../03-rag/README.md) --- **Atsakomybės apribojimas**: -Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors stengiamės užtikrinti tikslumą, prašome atkreipti dėmesį, kad automatizuoti vertimai gali turėti klaidų arba netikslumų. Originalus dokumentas gimtąja kalba turėtų būti laikomas autoritetingu šaltiniu. Kritinei informacijai rekomenduojama naudoti profesionalų žmogaus vertimą. Mes neatsakome už jokius nesusipratimus ar klaidingas interpretacijas, kylančias dėl šio vertimo naudojimo. +Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojama naudoti profesionalų žmogiškąjį vertimą. Mes neatsakome už jokius nesusipratimus ar neteisingą interpretaciją, kilusią naudojantis šiuo vertimu. \ No newline at end of file diff --git a/translations/lt/03-rag/README.md b/translations/lt/03-rag/README.md index 5b32fddbd..ecd9a8aa7 100644 --- a/translations/lt/03-rag/README.md +++ b/translations/lt/03-rag/README.md @@ -2,143 +2,142 @@ ## Turinys -- [Vaizdo įrašo peržiūra](../../../03-rag) -- [Ko išmoksite](../../../03-rag) -- [Reikalavimai](../../../03-rag) -- [RAG supratimas](../../../03-rag) - - [Kurią RAG metodiką naudoja šis vadovas?](../../../03-rag) -- [Kaip tai veikia](../../../03-rag) - - [Dokumento apdorojimas](../../../03-rag) - - [Emboldavimo kūrimas](../../../03-rag) - - [Semantinė paieška](../../../03-rag) - - [Atsakymo generavimas](../../../03-rag) -- [Paleisti programą](../../../03-rag) -- [Programos naudojimas](../../../03-rag) - - [Įkelti dokumentą](../../../03-rag) - - [Užduoti klausimus](../../../03-rag) - - [Patikrinti šaltinių nuorodas](../../../03-rag) - - [Eksperimentuoti su klausimais](../../../03-rag) -- [Pagrindinės sąvokos](../../../03-rag) - - [Dalių segmentavimo strategija](../../../03-rag) - - [Panašumo balai](../../../03-rag) - - [Atminties saugykla](../../../03-rag) - - [Konteksto lango valdymas](../../../03-rag) -- [Kada RAG yra svarbus](../../../03-rag) -- [Kiti žingsniai](../../../03-rag) - -## Vaizdo įrašo peržiūra - -Žiūrėkite šį tiesioginį seansą, kuriame paaiškinama, kaip pradėti dirbti su šiuo moduliu: +- [Vaizdo įrašo vadovas](#vaizdo-įrašo-vadovas) +- [Ko Išmoksite](#ko-išmoksite) +- [Išankstiniai reikalavimai](#išankstiniai-reikalavimai) +- [RAG Suvokimas](#rag-suvokimas) + - [Kuri RAG Požiūrį Naudoja Šis Vadovėlis?](#kuri-rag-požiūrį-naudoja-šis-vadovėlis) +- [Kaip Tai Veikia](#kaip-tai-veikia) + - [Dokumento Apdorojimas](#dokumento-apdorojimas) + - [Įterpimų Kūrimas](#įterpimų-kūrimas) + - [Semantinė Paieška](#semantinė-paieška) + - [Atsakymo Generavimas](#atsakymo-generavimas) +- [Paleiskite Programą](#programos-paleidimas) +- [Programos Naudojimas](#programos-naudojimas) + - [Įkelti Dokumentą](#dokumento-įkėlimas) + - [Užduoti Klausimus](#užduokite-klausimus) + - [Patikrinti Šaltinių Nuorodas](#patikrinkite-šaltinių-nuorodas) + - [Eksperimentuoti su Klausimais](#eksperimentuokite-su-klausimais) +- [Svarbios Sąvokos](#pagrindinės-sąvokos) + - [Skirsniavimo Strategija](#ištraukų-skaidymo-strategija) + - [Panašumo Įvertinimai](#panašumo-balai) + - [Atminties Saugojimas](#atminties-naudojimas) + - [Konteksto Langų Valdymas](#konteksto-lango-valdymas) +- [Kada RAG Yra Svarbus](#kada-rag-yra-svarbus) +- [Kiti Žingsniai](#tolimesni-žingsniai) + +## Vaizdo įrašo vadovas + +Žiūrėkite šią tiesioginę sesiją, kurioje paaiškinama, kaip pradėti darbą su šiuo moduliu: RAG with LangChain4j - Live Session -## Ko išmoksite +## Ko Išmoksite -Ankstesniuose moduliuose sužinojote, kaip bendrauti su DI ir tinkamai struktūruoti savo užklausas. Tačiau yra esminė riba: kalbos modeliai žino tik tai, ką išmoko mokymosi metu. Jie negali atsakyti į klausimus apie jūsų įmonės politiką, jūsų projekto dokumentaciją ar bet kokią informaciją, kurios nebuvo mokomi. +Ankstesniuose moduliuose išmokote kaip bendrauti su DI ir efektyviai struktūruoti užklausas. Tačiau yra esminė apribojimas: kalbos modeliai žino tik tai, ką išmoko treniravimo metu. Jie negali atsakyti į klausimus apie jūsų įmonės politiką, jūsų projekto dokumentaciją ar bet kokią informaciją, kurios nebuvo mokomi. -RAG (Retrieval-Augmented Generation) sprendžia šią problemą. Vietoj to, kad modelį mokytumėte jūsų informacijos (kas yra brangu ir nepraktiška), jūs suteikiate jam galimybę ieškoti jūsų dokumentuose. Kai kažkas užduoda klausimą, sistema randa susijusią informaciją ir įtraukia ją į užklausą. Modelis tada atsako remdamasis tuo gautu kontekstu. +RAG (Retrieval-Augmented Generation) išsprendžia šią problemą. Vietoj to, kad bandytumėte mokyti modelį jūsų informacijos (kas yra brangu ir nepraktiška), jūs suteikiate jam galimybę ieškoti per jūsų dokumentus. Kai kas nors užduoda klausimą, sistema suranda svarbią informaciją ir įtraukia ją į užklausą. Modelis tada atsako remdamasis šiuo paimtu kontekstu. -Galvokite apie RAG kaip apie nuorodų biblioteką modeliui. Kai užduodate klausimą, sistema: +Galvokite apie RAG kaip apie tai, kad modelis gauna nuorodų biblioteką. Kai užduodate klausimą, sistema: -1. **Naudotojo užklausa** – jūs užduodate klausimą -2. **Emboldavimas** – jūsų klausimas paverčiamas vektoriaus forma -3. **Vektorinė paieška** – randamos panašios dokumentų dalys -4. **Konteksto surinkimas** – į užklausą įtraukiamos atitinkamos dalys -5. **Atsakymas** – LLM sugeneruoja atsakymą remdamasis kontekstu +1. **Vartotojo Užklausa** – jūs užduodate klausimą +2. **Įterpimas** – jūsų klausimas virsta vektoriumi +3. **Vektorinė Paieška** – randami panašūs dokumentų skirsniai +4. **Konteksto Surinkimas** – pridėti svarbūs skirsniai į užklausą +5. **Atsakymas** – LLM generuoja atsakymą remdamasis kontekstu -Tai pagrindžia modelio atsakymus jūsų tikrais duomenimis, o ne remiasi mokymosi žiniomis ar sugalvotais atsakymais. +Tai pagrindžia modelio atsakymus jūsų faktais, o ne pasikliauja jo treniravimo žiniomis ar sugalvotais atsakymais. -## Reikalavimai +## Išankstiniai reikalavimai -- Įveiktas [Modulis 00 - Greitas pradėjimas](../00-quick-start/README.md) (lengvam RAG pavyzdžiui šiame modulyje) -- Įveiktas [Modulis 01 - Įvadas](../01-introduction/README.md) (paleistos Azure OpenAI paskyros, įskaitant embedding modelį `text-embedding-3-small`) -- `.env` failas šakniniame kataloge su Azure kredencialais (sukurtas komandą `azd up` atlikus Modulyje 01) +- Baigtas [Modulis 01 - Įvadas](../01-introduction/README.md) (įdiegti Azure OpenAI ištekliai, įskaitant `text-embedding-3-small` įterpimo modelį) +- `.env` failas projekto šaknyje su Azure kredencialais (sukurtas komandą `azd up` modulyje 01) -> **Pastaba:** Jei dar neįveikėte Modulio 01, pirmiausia sekite ten pateiktas diegimo instrukcijas. Komanda `azd up` diegia tiek GPT pokalbių modelį, tiek embedding modelį, naudojamą šiame modulyje. +> **Pastaba:** Jei dar neužbaigėte Modulio 01, pirmiausia sekite ten esančias diegimo instrukcijas. Komanda `azd up` įdiegia tiek GPT pokalbių modelį, tiek įterpimo modelį, kurį naudoja šis modulis. -## RAG supratimas +## RAG Suvokimas -Toliau pateiktame diagramoje iliustruojama pagrindinė idėja: vietoje tik modelio mokymosi duomenų naudojimo, RAG suteikia jam nuorodų biblioteką jūsų dokumentų, kuriuos jis pagal poreikį pasikonsultuoja prieš generuodamas kiekvieną atsakymą. +Žemiau pateiktas diagramas iliustruoja pagrindinę idėją: vietoj to, kad pasikliautume tik modelio treniravimo duomenimis, RAG suteikia jam nuorodų biblioteką iš jūsų dokumentų, kad jis pasitikrintų prieš generuodamas atsakymą. -Kas yra RAG +What is RAG -*Ši schema parodo skirtumą tarp standartinio LLM (kuris spėja remdamasis mokymosi duomenimis) ir RAG papildyto LLM (kuris pirmiausia pasikonsultuoja su jūsų dokumentais).* +*Ši diagrama vaizduoja skirtumą tarp standartinio LLM (kuris spėlioja remdamasis treniravimo duomenimis) ir RAG patobulinto LLM (kuris pirmiausia pasitikrina jūsų dokumentus).* -Štai kaip atskiri komponentai sujungiami bendram procesui. Naudotojo klausimas eina per keturis etapus — embedding, vektorinių paiešką, konteksto surinkimą ir atsakymo generavimą — kiekvienas etapas statomas ant ankstesnio: +Štai kaip komponentai yra sujungti per visą procesą. Vartotojo klausimas teka per keturis etapus – įterpimą, vektorinę paiešką, konteksto sudarymą ir atsakymo generavimą – kiekvienas statomas ant ankstesnio: -RAG architektūra +RAG Architecture -*Ši schema parodo RAG pilną procesą — naudotojo užklausa eina per embedding, vektorinę paiešką, konteksto surinkimą ir atsakymo generavimą.* +*Ši diagrama rodo end-to-end RAG procesą — vartotojo užklausa praeina per įterpimą, vektorinę paiešką, konteksto sudarymą ir atsakymo generavimą.* -Likusi modulio dalis detaliai apžvelgia kiekvieną etapą su kodo pavyzdžiais, kuriuos galite paleisti ir keisti. +Likusi modulio dalis išsamiai paaiškina kiekvieną etapą su kodu, kurį galite paleisti ir modifikuoti. -### Kurią RAG metodiką naudoja šis vadovas? +### Kuri RAG Požiūrį Naudoja Šis Vadovėlis? -LangChain4j siūlo tris būdus įgyvendinti RAG, kiekvienas su skirtingu abstrakcijos lygiu. Toliau pateikta schema juos lygina šalia vienas kito: +LangChain4j siūlo tris būdus įgyvendinti RAG, kiekvienas su skirtingu abstrakcijos lygiu. Žemiau pateikta diagrama palygina juos šalia vienas kito: -Trys RAG metodikos LangChain4j +Three RAG Approaches in LangChain4j -*Ši schema palygina tris LangChain4j RAG metodikas — Easy, Native ir Advanced — rodydama pagrindinius komponentus ir kada jas naudoti.* +*Ši diagrama palygina tris LangChain4j RAG požiūrius – Easy, Native ir Advanced – rodydama jų pagrindinius komponentus ir kada naudoti kiekvieną.* -| Metodika | Ką ji daro | Kompromisas | +| Požiūris | Ką Atlieka | Kompromisas | |---|---|---| -| **Easy RAG** | Automatiškai sujungia viską per `AiServices` ir `ContentRetriever`. Jūs aprašote sąsają, pridedate retrieverį ir LangChain4j už nugaros atlieka embedding, paiešką ir užklausos surinkimą. | Mažai kodo, bet nematote kas vyksta žingsnis po žingsnio. | -| **Native RAG** | Patys iškviečiate embedding modelį, ieškote saugykloje, kuriate užklausą ir generuojate atsakymą – žingsnis po žingsnio. | Daugiau kodo, tačiau kiekvienas etapas matomas ir valdomas. | -| **Advanced RAG** | Naudoja `RetrievalAugmentor` sistemą su pritaikomais užklausų transformatoriais, maršrutizatoriais, persvertėjais ir turinio injektoriais gamybiniams sprendimams. | Didžiausias lankstumas, bet ženkliai sudėtingiau. | +| **Easy RAG** | Automatiškai apjungia viską per `AiServices` ir `ContentRetriever`. Aprašo sąsają, prideda paieškos įrankį ir LangChain4j užkulisiuose tvarko įterpimą, paiešką ir užklausos sudarymą. | Minimalus kodas, bet nematote, kas dedasi kiekviename žingsnyje. | +| **Native RAG** | Jūs tiesiogiai kviečiate įterpimo modelį, ieškote saugykloje, statote užklausą ir generuojate atsakymą — žingsnis po žingsnio. | Daugiau kodo, bet kiekvienas etapas matomas ir modifikuojamas. | +| **Advanced RAG** | Naudoja `RetrievalAugmentor` sistemą su integruojamais užklausų transformatoriais, maršrutizatoriais, reitinguotojais ir turinio injektoriais gamybinėms grandinėms. | Maksimali lankstumas, tačiau žymiai sudėtingesnė sistema. | -**Šis vadovas naudoja Native metodiką.** Kiekvienas RAG proceso žingsnis — užklausos embeddingas, vektorinė paieška, konteksto surinkimas ir atsakymo generavimas — detaliai parašytas faile [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Tai yra tyčia: kaip mokomoji medžiaga svarbiau, kad matytumėte ir suprastumėte kiekvieną etapą, o ne kad kodas būtų kuo trumpesnis. Kai gerai suprasite procesą, galėsite pereiti prie Easy RAG greitiems prototipams arba Advanced RAG gamybiniams projektams. +**Šis vadovėlis naudoja Native požiūrį.** Kiekvienas RAG proceso žingsnis – užklausos įterpimas, paieška vektoriniame saugykloje, konteksto sudarymas ir atsakymo generavimas – yra aiškiai parašyti faile [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Tai sąmoningas sprendimas: mokymo tikslais svarbiau, kad matytumėte ir suprastumėte kiekvieną etapą, nei kad kodas būtų maksimaliai sutrumpintas. Kai suprasite procesą, galėsite pereiti prie Easy RAG greitiems prototipams arba Advanced RAG gamybiniams sprendimams. -> **💡 Jau matėte Easy RAG veikimą?** Greito pradžios modulyje ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) yra pavyzdys, kuris naudoja Easy RAG metodiką – LangChain4j automatiškai atlieka embeddingą, paiešką ir užklausos surinkimą. Šis modulis imasi kito žingsnio - atveria tą procesą ir leidžia jums matyti bei valdyti kiekvieną etapą. +> **💡 Domina Easy RAG?** LangChain4j taip pat suteikia *Easy RAG* požiūrį, kur `AiServices` ir `ContentRetriever` automatiškai tvarko įterpimą, paiešką ir užklausos sudarymą. Šis modulis eina tiesesniu – išardantis procesą, kad matytumėte ir kontroliuotumėte kiekvieną etapą patys. -Toliau pateikta schema parodo Easy RAG procesą iš Greito pradžios pavyzdžio. Pastebėkite, kaip „AiServices“ ir „EmbeddingStoreContentRetriever“ slepia sudėtingumą – jūs įkeliat dokumentą, prijungiate retrieverį ir gaunate atsakymus. Native metodika šiame modulyje išplečia kiekvieną iš šių paslėptų žingsnių: +Žemiau pateikta schema parodo Easy RAG grandinę. Atkreipkite dėmesį, kaip `AiServices` ir `EmbeddingStoreContentRetriever` paslepia visą sudėtingumą – jūs įkeliat dokumentą, prijungiat paieškos įrankį ir gaunate atsakymus. Native požiūris šiame modulyje sulaužo šiuos paslėptus žingsnius: -Easy RAG Procesas - LangChain4j +Easy RAG Pipeline - LangChain4j -*Ši schema rodo Easy RAG procesą iš `SimpleReaderDemo.java`. Lyginkite su Native metodika šiame modulyje: Easy RAG užklausos embeddingą, paiešką ir surinkimą slepia po „AiServices“ ir „ContentRetriever“ – jūs įkeliat dokumentą, pridedate retrieverį ir gaunate atsakymus. Native metodika čia atveria šį procesą, kad patys iškviesite kiekvieną etapą (embed, search, assemble context, generate), suteikdama pilną matomumą ir kontrolę.* +*Ši diagrama rodo Easy RAG grandinę. Palyginkite su Native požiūriu, kuris naudojamas šiame modulyje: Easy RAG paslepia įterpimą, paiešką ir užklausos sudarymą už `AiServices` ir `ContentRetriever` — jūs įkeliat dokumentą, prijungiat ieškiklį ir gaunate atsakymus. Native požiūris šiuo moduliu atveria šią grandinę, todėl patys kviečiate kiekvieną etapą (įterpimas, paieška, konteksto sudarymas, generavimas) – suteikdamas visišką matomumą ir kontrolę.* -## Kaip tai veikia +## Kaip Tai Veikia -Šio modulio RAG procesas suskaidytas į keturis etapus, kurie vykdomi seka kiekvieną kartą, kai naudotojas užduoda klausimą. Pirmiausia įkeltas dokumentas yra **išanalizuojamas ir suskaidomas į dalis**. Tos dalys paverčiamos į **vektorinius embeddingus** ir saugomos, kad būtų galima jas matematiškai palyginti. Kai atkeliauja užklausa, sistema atlieka **semantinę paiešką**, kad rastų aktualiausias dalis ir galiausiai perduoda jas kaip kontekstą LLM atsakymų generavimui. Toliau pateiktos sekcijos detaliai aptaria kiekvieną etapą su faktiniu kodu ir schemomis. Pažiūrėkime pirmą žingsnį. +Šio modulio RAG grandinė suskaidoma į keturis etapus, kurie vykdomi iš eilės kiekvieną kartą, kai vartotojas užduoda klausimą. Pirmiausia įkeliamas dokumentas yra **nuskaitomas ir skaidomas** į valdomus gabalus. Tie gabalai tada paverčiami į **vektorinius įterpimus** ir saugomi, kad būtų galima matematiškai lyginti. Kai atvyksta užklausa, sistema atlieka **semantinę paiešką** surasti labiausiai susijusius gabalus, galiausiai perduodama juos kaip kontekstą LLM atsakymo **generavimui**. Žemiau pateiktose sekcijose praeisime per kiekvieną etapą su tikru kodu ir diagramomis. Pažiūrėkime pirmą veiksmą. -### Dokumento apdorojimas +### Dokumento Apdorojimas [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Kai įkeliat dokumentą, sistema jį analizuoja (PDF arba paprastas tekstas), prideda metaduomenis, tokius kaip failo pavadinimas, ir paskui suskaido į dalis – mažesnius gabalus, kurie patogiai tilptų į modelio konteksto langą. Šios dalys šiek tiek persidengia, kad kontekstas ties ribomis neprarastų svarbios informacijos. +Kai įkeliate dokumentą, sistema jį parsiunčia (PDF ar paprasto teksto formatu), prideda metaduomenis, tokius kaip failo pavadinimas, ir tada suskaido į gabalus – mažesnes dalis, kurios patogiai telpa modelio konteksto lange. Šie gabalai šiek tiek persidengia, kad neprarastumėte konteksto kraštuose. ```java -// Išanalizuokite įkeltą failą ir suvyniokite jį į LangChain4j dokumentą +// Išanalizuokite įkeltą failą ir įvyniokite jį į LangChain4j dokumentą Document document = Document.from(content, metadata); -// Padalykite į 300 žodžių skiltis su 30 žodžių persidengimu +// Padalykite į 300 ženklų dalis su 30 ženklų persidengimu DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Toliau pateikta schema vizualizuoja šį procesą. Pastebėkite, kaip kiekviena dalis dalinasi truputį simbolių su kaimyninėmis – 30 simbolių persidengimas užtikrina, kad svarbus kontekstas neprapuola per plyšius: +Žemiau pateikta diagrama vizualiai parodo, kaip tai veikia. Atkreipkite dėmesį, kaip kiekvienas gabalas dalijasi dalimi žodžių su kaimynais – 30 žodžių persidengimas užtikrina, kad svarbus kontekstas nepraslystų per plyšius: -Dokumento dalijimas į dalis +Document Chunking -*Ši schema rodo, kaip dokumentas skaidomas į 300 simbolių dalis su 30 simbolių persidengimu, išlaikant kontekstą ribose.* +*Ši diagrama parodo, kaip dokumentas skaidomas į 300 žodžių gabalus su 30 žodžių persidengimu, išlaikant kontekstą gabalų ribose.* -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) pokalbiu:** Atverkite [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ir paklauskite: -> - "Kaip LangChain4j dalija dokumentus į dalis ir kodėl persidengimas yra svarbus?" -> - "Koks optimalus dalies dydis skirtingiems dokumentų tipams ir kodėl?" -> - "Kaip tvarkyti daugiakalbius dokumentus arba özelėtu formatu?" +> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Pokalbių:** Atidarykite [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ir paklauskite: +> - "Kaip LangChain4j skaido dokumentus į gabalus ir kodėl persidengimas svarbus?" +> - "Koks yra optimalus gabalo dydis skirtingiems dokumentų tipams ir kodėl?" +> - "Kaip tvarkyti dokumentus keliomis kalbomis arba su specialiu formatavimu?" -### Embeddingų kūrimas +### Įterpimų Kūrimas [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Kiekviena dalis paverčiama skaitmenine reprezentacija, vadinama embeddingu – iš esmės tai yra teksto prasmės atvaizdavimas į skaičius. Embedding modelis nėra „išmanus“ kaip pokalbių modelis; jis negali vykdyti nurodymų, mąstyti ar atsakyti į klausimus. Jo užduotis – tekstą atvaizduoti į matematinę erdvę taip, kad panašios prasmės būtų arti viena kitos – „automobilis“ arti „mašina“, „grąžinimo politika“ arti „susigrąžink pinigus“. Galvokite apie pokalbių modelį kaip žmogų, su kuriuo galite kalbėtis; embedding modelis yra itin geras dokumentų rūšiavimo sistema. +Kiekvienas gabalas paverčiamas į skaitmeninį atvaizdą, vadinamą įterpimu – iš esmės tai pašnekovo „prasmės į skaičius“ konverteris. Įterpimo modelis nėra „protingas“ kaip pokalbių modelis; jis negali vykdyti nurodymų, mąstyti ar atsakyti į klausimus. Jis tik įžemina tekstą į matematinę erdvę, kur panašios prasmės dedamos arti viena kitos – „automobilis“ arti „mašina“, „grąžinimo politika“ arti „sugrąžink pinigus“. Galvokite apie pokalbių modelį kaip asmenį, su kuriuo galite kalbėtis; o įterpimo modelis yra itin geras archyvų tvarkytojas. -Toliau pateikta schema vizualizuoja šią koncepciją: įeina tekstas, išeina skaitmeniniai vektoriai, ir panašios prasmės generuoja vektorius, artimus vienas kitam: +Žemiau pateikta diagrama vizualizuoja šią sąvoką – tekstas patenka vidun, išeina skaitmeniniai vektoriai, o panašios prasmės sukurią artimus vektorius: -Embedding modelio koncepcija +Embedding Model Concept -*Ši schema rodo, kaip embedding modelis paverčia tekstą į skaitmeninius vektorius, kurios panašios reikšmės – pvz., „automobilis“ ir „mašina“ – vektorių erdvėje yra arti viena kitos.* +*Ši diagrama rodo, kaip įterpimo modelis paverčia tekstą į skaitmeninius vektorius, sudėdamas panašios prasmės – pvz., „automobilis“ ir „mašina“ – arti vienas kito vektorių erdvėje.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Toliau pateikta klasių schema rodo du atskirus srautus RAG procese ir LangChain4j klases, kurios juos įgyvendina. **Duomenų įkėlimo srautas** (įvyksta vieną kartą įkeliant) skaido dokumentą, atlieka embeddingą ir saugo duomenis per `.addAll()`. **Klausimų srautas** (veikia kiekvieną kartą užduodant klausimą) atlieka užklausos embeddingą, ieško per `.search()` ir perduoda atitinkamą kontekstą pokalbių modeliui. Abu srautai sujungiami per bendrą sąsają `EmbeddingStore`: +Klasės diagrama žemiau parodo dvi atskiras RAG grandinės srautus ir LangChain4j klases, kurios juos įgyvendina. **Įvedimo srautas** (vyksta vieną kartą įkeliant dokumentą) skaido dokumentą, įterpia gabalus ir saugo per `.addAll()`. **Užklausos srautas** (vyksta kiekvieną kartą, kai užduodamas klausimas) įterpia užklausą, ieško saugykloje per `.search()`, ir perduoda surinktą kontekstą pokalbių modeliui. Abu srautai susijungia bendroje `EmbeddingStore` sąsajoje: -LangChain4j RAG klasės +LangChain4j RAG Classes -*Ši schema rodo du srautus RAG procese – įkėlimą ir užklausas – ir kaip jie sujungiami per bendrą EmbeddingStore.* +*Ši diagrama rodo dvi RAG grandinės srautus – įvedimą ir užklausą – ir kaip jie jungiasi per bendrą EmbeddingStore.* -Įrašius embeddingus, panašus turinys natūraliai klasterizuojasi vektorinėje erdvėje. Toliau pateikta vizualizacija parodo, kaip dokumentai apie susijusias temas išsidėsto šalia vienas kito, leidžiant semantinei paieškai veikti efektyviai: +Kai įterpimai yra saugomi, panašus turinys natūraliai klasterizuojasi vektorinėje erdvėje. Žemiau pateikta vizualizacija rodo, kaip susiję dokumentai tampa artimais taškais, kas leidžia atlikti semantinę paiešką: -Vektorinių embeddingų erdvė +Vector Embeddings Space -*Ši vizualizacija rodo, kaip susiję dokumentai susikoncentruoja 3D vektorių erdvėje, o temos kaip Techniniai dokumentai, Verslo taisyklės ir DUK formuoja ryškias grupes.* +*Ši vizualizacija parodo, kaip susiję dokumentai grupuojasi 3D vektorinėje erdvėje, kur temos kaip Techniniai Dokumentai, Verslo Taisyklės ir DUK sudaro atskirus klasterius.* -Kai naudotojas atlieka paiešką, sistema vykdo keturis žingsnius: embeddinguoja dokumentus vieną kartą, embeddinguoja užklausą kiekvieną paiešką, lygina užklausos vektorių su visais saugomais vektoriais naudodama kosinuso panašumo metodą ir grąžina top-K geriausiai įvertintas dalis. Toliau pateikta schema apžvelgia kiekvieną žingsnį ir susijusias LangChain4j klases: +Kai vartotojas ieško, sistema vykdo keturis veiksmus: vieną kartą įterpia dokumentus, kiekvieną paiešką įterpia užklausą, lygina užklausos vektorių su visais saugomais vektoriais naudodama kosinuso panašumo matą ir grąžina top-K aukščiausio įvertinimo gabalus. Žemiau pateikta diagrama demonstruoja kiekvieną žingsnį ir susijusias LangChain4j klases: -Embedding paieškos žingsniai +Embedding Search Steps -*Ši schema iliustruoja keturių žingsnių embedding paieškos procesą: dokumentų embeddingą, užklausos embeddingą, vektorių palyginimą naudojant kosinuso panašumą ir top-K rezultatų pateikimą.* +*Ši diagrama rodo keturių žingsnių įterpimo paieškos procesą: įterpti dokumentus, įterpti užklausą, palyginti vektorius naudojant kosinuso panašumą ir grąžinti top-K rezultatus.* -### Semantinė paieška +### Semantinė Paieška [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Kai jūs užduodate klausimą, jūsų klausimas taip pat paverčiamas embeddingu. Sistema lygina jūsų klausimo embeddingą su visų dokumentų dalių embeddingais. Ji randa dalis, kurios turi artimiausias prasmes – ne tik atitinkamus raktinius žodžius, bet autentišką semantinį panašumą. +Kai užduodate klausimą, jūsų klausimas taip pat virsta įterpimu. Sistema lygina jūsų klausimo įterpimą su visais dokumentų gabalų įterpimais. Ji suranda gabalus su labiausiai panašiomis prasmėmis – ne tik pagal atitinkančius raktinius žodžius, bet tikrą semantinį panašumą. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Toliau pateikta schema kontrastuoja semantinę paiešką su tradicine raktinių žodžių paieška. Raktinių žodžių paieška „transportas“ praleidžia dalį apie „automobilius ir sunkvežimius“, tačiau semantinė paieška supranta, kad tai tas pats dalykas ir grąžina ją kaip aukštai vertinamą atitikmenį: +Diagrama žemiau lygina semantinę paiešką su tradicine raktinių žodžių paieška. Raktinių žodžių paieška „transporto priemonė“ nepaiso gabalo apie „automobilius ir sunkvežimius“, tačiau semantinė paieška supranta, kad tai tas pats dalykas ir grąžina ją kaip aukštos kokybės atitikmenį: -Semantinė paieška +Semantic Search -*Ši schema lygina raktinių žodžių pagrindu atliekamą paiešką su semantine paieška, rodydama, kaip semantinė paieška suranda konceptualiai susijusį turinį net jei tikslūs raktiniai žodžiai skiriasi.* -Po gaubtu panašumas matuojamas naudojant kosinuso panašumą — iš esmės klausiama „ar šie du rodyklės nukreiptos ta pačia kryptimi?“ Du tekstų fragmentai gali naudoti visiškai skirtingus žodžius, tačiau jei jie reiškia tą patį, jų vektoriai rodo ta pačia kryptimi ir įvertinimai artimi 1.0: +*Ši diagrama lygina raktinių žodžių paiešką su semantine paieška, rodydama, kaip semantinė paieška suranda konceptualiai susijusį turinį net jei raktiniai žodžiai nesutampa.* -Kosinuso Panašumas +Po gaubtu, panašumas matuojamas naudojant kosinuso panašumą – iš esmės klausiama „ar šie du strėlytės rodo ta pačia kryptimi?“ Du gabalai gali naudoti visiškai skirtingus žodžius, bet jei reiškia tą patį dalyką, jų vektoriai rodo tokia pačia kryptimi ir įvertinami artimai 1.0: -*Šiame diagramoje iliustruojamas kosinuso panašumas kaip kampas tarp įterpimo vektorių — kuo labiau suderinti vektoriai, tuo jų įvertinimai arčiau 1.0, rodantys didesnį semantinį panašumą.* +Cosine Similarity +*Ši schema iliustruoja kosinuso panašumą kaip kampą tarp įterptinių vektorių — kuo vektoriai labiau suderinti, tuo jų rezultatas arčiau 1.0, rodantis didesnį semantinį panašumą.* -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ir paklauskite: -> - „Kaip veikia panašumo paieška naudojant įterpimus ir kas lemia įvertinimą?“ -> - „Koks panašumo slenkstis turėtų būti naudojamas ir kaip jis veikia rezultatus?“ -> - „Kaip elgtis atvejais, kai nerandama susijusių dokumentų?“ +> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atverkite [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ir paklauskite: +> - „Kaip veikia panašumo paieška su įterpimais ir kas lemia balą?“ +> - „Kokį panašumo slenkstį turėčiau naudoti ir kaip tai veikia rezultatus?“ +> - „Kaip elgtis, kai nerandama susijusių dokumentų?“ -### Atsakymų generavimas +### Atsakymo generavimas [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Reikšmingiausi tekstų fragmentai surenkami į struktūrizuotą užklausą, kuri apima aiškias instrukcijas, surinktą kontekstą ir vartotojo klausimą. Modelis skaito tuos konkrečius fragmentus ir atsako remdamasis tuo — jis gali naudoti tik tai, kas prieš jį, tai padeda išvengti klaidų (halucinacijų). +Svarbiausios ištraukos surenkamos į struktūruotą užklausos šabloną, kuriame pateikiamos aiškios instrukcijos, gauta konteksto informacija ir vartotojo klausimas. Modelis skaito tik šias konkrečias ištraukas ir remiasi šiomis žiniomis — jis gali naudoti tik tai, kas yra priešais, kas padeda išvengti klaidų. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Žemiau pateikta diagrama rodo šį surinkimo procesą — paieškos žingsnio aukščiausiai įvertinti fragmentai įterpiami į užklausos šabloną, o `OpenAiOfficialChatModel` generuoja pagrįstą atsakymą: +Žemiau pateikta schema demonstruoja šį surinkimą — aukščiausiai įvertintos ištraukos iš paieškos žingsnio įdedamos į užklausos šabloną, o `OpenAiOfficialChatModel` generuoja pagrįstą atsakymą: -Konteksto Surinkimas +Context Assembly -*Ši diagrama parodo, kaip aukščiausiai įvertinti fragmentai surenkami į struktūrizuotą užklausą, leidžiančią modeliui sukurti pagrįstą atsakymą iš jūsų duomenų.* +*Ši schema rodo, kaip aukščiausiai įvertintos ištraukos surenkamos į struktūruotą užklausą, leidžiančią modeliui generuoti pagrįstą atsakymą iš jūsų duomenų.* -## Paleiskite programą +## Programos paleidimas **Patikrinkite diegimą:** -Įsitikinkite, kad šakniniame kataloge yra `.env` failas su Azure akreditacijomis (sukurtas 1 modulyje). Paleiskite šią komandą modulio kataloge (`03-rag/`): +Įsitikinkite, kad .env failas yra pagrindiniame kataloge su Azure kredencialais (sukurtais 1 modulyje). Paleiskite tai module kataloge (`03-rag/`): **Bash:** ```bash @@ -256,42 +255,42 @@ cat ../.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **PowerShell:** ```powershell -Get-Content ..\.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Turėtų parodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Pradėkite programą:** +**Paleiskite programą:** -> **Pastaba:** Jei jau pradėjote visas programas naudodami `./start-all.sh` iš šaknininio katalogo (kaip aprašyta 1 modulyje), šis modulis jau veikia 8081 prievade. Galite praleisti žemiau pateiktas paleidimo komandas ir eiti tiesiai į http://localhost:8081. +> **Pastaba:** Jei jau paleidote visas programas naudodami `./start-all.sh` pagrindiniame kataloge (kaip aprašyta 1 modulyje), šis modulis jau veikia prievade 8081. Galite praleisti paleidimo komandas žemiau ir tiesiogiai pereiti į http://localhost:8081. -**1 variantas: Naudojant Spring Boot Dashboard (rekomenduojama VS Code vartotojams)** +**1 variantas: naudojant Spring Boot Dashboard (Rekomenduojama VS Code naudotojams)** -Dev konteineryje įdiegta Spring Boot Dashboard plėtinys, kuris suteikia vizualią sąsają valdyti visas Spring Boot programas. Jį rasite Activity Bar kairėje VS Code pusėje (ieškokite Spring Boot piktogramos). +Dev container yra Spring Boot Dashboard plėtinys, kuris suteikia vizualią sąsają valdyti visas Spring Boot programas. Jį rasite kairėje pusėje esančioje veiklos juostoje VS Code (ieškokite Spring Boot ikonos). Iš Spring Boot Dashboard galite: -- Matyti visas Spring Boot programas darbo aplinkoje +- Matyti visas darbo vietoje esančias Spring Boot programas - Vienu paspaudimu paleisti/stabdyti programas -- Peržiūrėti programos žurnalus realiu laiku -- Stebėti programų būseną +- Realiai stebėti programų žurnalus +- Kontroliuoti programų būseną -Tiesiog spustelėkite paleidimo mygtuką šalia „rag“, kad paleistumėte šį modulį, arba paleiskite visus modulius iš karto. +Paprastai spustelėkite paleidimo mygtuką šalia „rag“, kad paleistumėte šį modulį arba paleiskite visus modulius vienu metu. Spring Boot Dashboard -*Ši ekrano kopija rodo Spring Boot Dashboard VS Code, kur galite vizualiai paleisti, sustabdyti ir stebėti programas.* +*Šis ekrano vaizdas rodo Spring Boot Dashboard VS Code, kur galite vizualiai paleisti, sustabdyti ir stebėti programas.* -**2 variantas: Naudojant shell skriptus** +**2 variantas: naudojant shell skriptus** -Paleiskite visas žiniatinklio programas (moduliai 01-04): +Paleiskite visas žiniatinklio programas (1–4 moduliai): **Bash:** ```bash -cd .. # Iš šakninio katalogo +cd .. # Iš pagrindinio katalogo ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Iš šaknininio katalogo +cd .. # Iš šakninių katalogų .\start-all.ps1 ``` @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Abu skriptai automatiškai įkelia aplinkos kintamuosius iš šakniniame kataloge esančio `.env` failo ir sukurs JAR failus, jei jų nėra. +Abu skriptai automatiškai įkrauna aplinkos kintamuosius iš pagrindinio .env failo ir sukurs JAR failus, jei jų nėra. -> **Pastaba:** Jei norite prieš paleidimą rankiniu būdu sukompiluoti visus modulius: +> **Pastaba:** Jei norite visus modulius sukompiliuoti rankiniu būdu prieš paleidžiant: > > **Bash:** > ```bash @@ -325,9 +324,9 @@ Abu skriptai automatiškai įkelia aplinkos kintamuosius iš šakniniame katalog > mvn clean package -DskipTests > ``` -Naršyklėje atidarykite http://localhost:8081. +Atidarykite naršyklėje http://localhost:8081. -**Norėdami sustabdyti:** +**Norint sustabdyti:** **Bash:** ```bash @@ -345,93 +344,93 @@ cd ..; .\stop-all.ps1 # Visi moduliai ## Programos naudojimas -Programa suteikia žiniatinklio sąsają dokumentų įkėlimui ir klausimams užduoti. +Programa suteikia internetinę sąsają dokumentų įkėlimui ir klausimams užduoti. -RAG Programos Sąsaja +RAG Application Interface -*Ši ekrano kopija rodo RAG programos sąsają, kur galite įkelti dokumentus ir užduoti klausimus.* +*Šiame ekrano vaizde matoma RAG programos sąsaja, kur įkeliate dokumentus ir užduodate klausimus.* -### Įkelkite dokumentą +### Dokumento įkėlimas -Pradėkite nuo dokumento įkėlimo — geriausiai tinka TXT failai testavimui. Šiame kataloge pateiktas `sample-document.txt`, kuriame yra informacija apie LangChain4j funkcijas, RAG diegimą ir geriausias praktikas — puikiai tinka sistemai išbandyti. +Pradėkite įkeldami dokumentą – TXT failai geriausiai tinka testavimui. Šiame kataloge pateiktas `sample-document.txt`, kuriame yra informacija apie LangChain4j funkcijas, RAG įgyvendinimą ir geriausias praktikas – puiku sistemos testavimui. -Sistema apdoroja jūsų dokumentą, jį suskaido į fragmentus ir sukurią įterpimus kiekvienam fragmentui. Tai vyksta automatiškai įkėlus. +Sistema apdoroja jūsų dokumentą, suskaido jį į ištraukas ir sukuria įterpimus kiekvienai ištrauka. Tai vyksta automatiškai įkeliant. ### Užduokite klausimus -Dabar užduokite konkrečius klausimus apie dokumentą. Pabandykite užduoti faktinius klausimus, aiškiai pateiktus dokumente. Sistema ieško tinkamų fragmentų, įtraukia juos į užklausą ir generuoja atsakymą. +Dabar užduokite specifinius klausimus apie dokumentą. Išbandykite faktinius dalykus, aiškiai išdėstytus dokumente. Sistema ieško tinkamų ištraukų, įtraukia jas į užklausą ir generuoja atsakymą. ### Patikrinkite šaltinių nuorodas -Atkreipkite dėmesį, kad kiekvienas atsakymas apima nuorodas į šaltinius su panašumo įvertinimais. Šie įvertinimai (nuo 0 iki 1) rodo, kiek kiekvienas fragmentas buvo susijęs su jūsų klausimu. Aukštesni įvertinimai reiškia geresnį atitikimą. Tai leidžia patikrinti atsakymą pagal šaltinį. +Pastebėsite, kad kiekviename atsakyme yra šaltinių nuorodos su panašumo balais. Šie balai (nuo 0 iki 1) parodo, kiek kiekviena ištrauka buvo susijusi su jūsų klausimu. Aukštesni balai reiškia geresnį atitikimą. Tai leidžia patikrinti atsakymą pagal šaltinį. -RAG Užklausos Rezultatai +RAG Query Results -*Ši ekrano kopija rodo užklausos rezultatus su sugeneruotu atsakymu, šaltinių nuorodomis ir kiekvieno rasto fragmento aktualumo įvertinimais.* +*Šis ekrano vaizdas rodo užklausos rezultatus su sugeneruotu atsakymu, šaltinių nuorodomis ir svarbos balais kiekvienai gautai ištraukai.* ### Eksperimentuokite su klausimais -Išbandykite skirtingų tipų klausimus: +Išbandykite skirtingus klausimų tipus: - Konkretūs faktai: „Kokia pagrindinė tema?“ - Palyginimai: „Kuo skiriasi X ir Y?“ -- Santraukos: „Apibendrinkite pagrindines Z temas“ +- Santraukos: „Apibendrinkite svarbiausius Z aspektus“ -Stebėkite, kaip keičiasi aktualumo įvertinimai, priklausomai nuo to, kaip gerai jūsų klausimas atitinka dokumentų turinį. +Sekite, kaip svarbos balai keičiasi, priklausomai nuo to, kaip gerai jūsų klausimas atitinka dokumentą. ## Pagrindinės sąvokos -### Fragmentavimo strategija +### Ištraukų skaidymo strategija -Dokumentai skaidomi į 300 žodžių fragmentus su 30 žodžių persidengimu. Šis balansas užtikrina, kad kiekvienas fragmentas turėtų pakankamai konteksto, kad būtų prasmingas, bet išliktų pakankamai mažas, kad būtų galima įtraukti kelis fragmentus į užklausą. +Dokumentai skaidomi į 300 žodžių ištraukas su 30 žodžių persidengimu. Toks balansas užtikrina, kad kiekviena ištrauka turėtų pakankamai konteksto, kad būtų prasminga, ir išliktų pakankamai maža, kad kelios ištraukos tilptų užklausoje. -### Panašumo įvertinimai +### Panašumo balai -Kiekvienas rastas fragmentas turi panašumo įvertinimą nuo 0 iki 1, rodantį, kaip gerai jis atitinka vartotojo klausimą. Žemiau pateikta diagrama vaizduoja įvertinimų diapazonus ir kaip sistema juos naudoja filtruodama rezultatus: +Kiekviena gauta ištrauka turi panašumo balą nuo 0 iki 1, rodantį, kaip tiksliai atitinka vartotojo klausimą. Žemiau pateikta schema vizualizuoja balų diapazonus ir kaip sistema juos naudoja rezultatų filtravimui: -Panašumo Įvertinimai +Similarity Scores -*Ši diagrama rodo įvertinimų diapazonus nuo 0 iki 1, su minimaliu 0,5 slenksčiu, kuris atfiltruoja nesusijusius fragmentus.* +*Ši schema rodo balų intervalo diapazonus nuo 0 iki 1, su minimaliu slenksčiu 0.5, kuris filtruoja nereikšmingas ištraukas.* -Įvertinimų diapazonas nuo 0 iki 1: -- 0,7–1,0: Labai reikšminga, tikslus atitikimas -- 0,5–0,7: Reikšminga, geras kontekstas -- Žemiau 0,5: Atfiltruota, pernelyg nesusiję +Balai svyruoja nuo 0 iki 1: +- 0.7–1.0: Labai svarbu, tikslus atitikimas +- 0.5–0.7: Svarbu, geras kontekstas +- Mažiau nei 0.5: Filtruojama, pernelyg nesutampa -Sistema gauna tik fragmentus, kurių įvertinimas viršija minimalų slenkstį, siekiant užtikrinti kokybę. +Sistema renka tik ištraukas, turinčias balą virš minimalaus slenksčio, užtikrindama kokybę. -Įterpimai veikia gerai, kai reikšmės aiškiai susikaupia, tačiau turi aklųjų zonų. Žemiau pateikta diagrama rodo dažniausias nesėkmių priežastis — per dideli fragmentai sukuria miglotus vektorius, per maži fragmentai neturi konteksto, dviprasmiai terminai nukreipia į kelis klasterius, o tikslių atitikimų paieška (ID, dalių numeriai) visiškai neveikia su įterpimais: +Įterpimai veikia gerai, kai prasmės klasteriai aiškūs, tačiau turi ribotumų. Žemiau schema rodo dažniausias klaidų formas — per didelės ištraukos kuria neaiškius vektorius, per mažos ištraukos neturi konteksto, dviprasmiški terminai rodo į kelis klasterius, o tikslūs paieškos atitikimai (ID, dalių numeriai) visai neveikia su įterpimais: -Įterpimų Klaidos Režimai +Embedding Failure Modes -*Ši diagrama rodo dažniausias įterpimų nesėkmių formas: per dideli fragmentai, per maži fragmentai, dviprasmiai terminai nukreipiantys į kelis klasterius ir tikslių atitikimų paieška kaip ID.* +*Ši schema rodo dažniausias įterpimų klaidų formas: per didelės ištraukos, per mažos ištraukos, dviprasmiški terminai rodo į kelis klasterius ir tikslūs paieškos atitikimai, pavyzdžiui ID.* -### Atminties saugykla +### Atminties naudojimas -Šis modulis naudoja atminties saugyklą paprastumui. Perkraunant programą, įkelti dokumentai prarandami. Gamybos sistemose naudojamos nuolatinės vektorinių duomenų bazės, tokios kaip Qdrant ar Azure AI Search. +Šis modulis naudoja atminties saugyklą dėl paprastumo. Perkraunant programą įkelti dokumentai prarandami. Produkcijos sistemose naudojamos nuolatinės vektorinių duomenų bazės, pavyzdžiui, Qdrant arba Azure AI Search. ### Konteksto lango valdymas -Kiekvienas modelis turi maksimalią konteksto lango apimtį. Negalite įtraukti kiekvieno fragmento iš didelio dokumento. Sistema parenka svarbiausius N fragmentų (pagal numatytuosius nustatymus 5), kad tilptų į ribas ir suteiktų pakankamą kontekstą tiksliesiems atsakymams. +Kiekvienas modelis turi maksimalų konteksto langą. Negalite įtraukti kiekvienos ištraukos iš didelio dokumento. Sistema gauna viršutinius N svarbiausių ištraukų (pagal numatytuosius nustatymus 5), kad tilptų į ribas ir suteiktų pakankamai konteksto tiksliems atsakymams. -## Kada svarbus RAG +## Kada RAG yra svarbus -RAG ne visada yra tinkamiausias metodas. Žemiau pateiktas sprendimo vadovas padeda nuspręsti, kada RAG prideda vertės, o kada pakanka paprastesnių metodų — kaip turinio tiesioginis įtraukimas į užklausą arba modelio įgimtos žinios: +RAG ne visada yra tinkamiausias pasirinkimas. Žemiau pateiktas sprendimų vadovas padeda nuspręsti, kada RAG prideda vertės, o kada paprastesni metodai — pavyzdžiui, tiesiog įtraukti turinį į užklausą ar pasikliauti modelio įmontuotomis žiniomis — yra pakankami: -Kada naudoti RAG +When to Use RAG -*Ši diagrama rodo sprendimo vadovą, kada RAG prideda vertės, o kada pakanka paprastesnių metodų.* +*Ši schema rodo sprendimų vadovą, kada RAG prideda vertės, o kada pakanka paprastesnių metodų.* ## Tolimesni žingsniai -**Kitas modulis:** [04-tools - AI Agentai su Įrankiais](../04-tools/README.md) +**Kitas modulis:** [04-tools - AI agentai su įrankiais](../04-tools/README.md) --- -**Naršymas:** [← Ankstesnis: 02 modulis - Užklausų konstravimas](../02-prompt-engineering/README.md) | [Atgal į pagrindinį](../README.md) | [Kitas: 04 modulis - Įrankiai →](../04-tools/README.md) +**Naršymas:** [← Ankstesnis: 02 modulis - Užklausų kūrimas](../02-prompt-engineering/README.md) | [Atgal į pagrindinį](../README.md) | [Kitas: 04 modulis - Įrankiai →](../04-tools/README.md) --- **Atsakomybės apribojimas**: -Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas gimtąja kalba turėtų būti laikomas autoritetingu šaltiniu. Kritinei informacijai rekomenduojama naudoti profesionalią žmogaus atliekamą vertimą. Mes neatsakingi už bet kokius nesusipratimus ar neteisingus aiškinimus, kylančius dėl šio vertimo naudojimo. +Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojama naudoti profesionalų žmogiškąjį vertimą. Mes neatsakome už jokius nesusipratimus ar neteisingą interpretaciją, kilusią naudojantis šiuo vertimu. \ No newline at end of file diff --git a/translations/lt/04-tools/README.md b/translations/lt/04-tools/README.md index f03773206..4df7955d5 100644 --- a/translations/lt/04-tools/README.md +++ b/translations/lt/04-tools/README.md @@ -1,76 +1,76 @@ -# Module 04: Dirbtinio Intelekto Agentai su Įrankiais +# Modulis 04: DI agentai su įrankiais ## Turinys -- [Vaizdo įrašo peržiūra](../../../04-tools) -- [Ką sužinosite](../../../04-tools) -- [Priešistorė](../../../04-tools) -- [Dirbtinio intelekto agentų su įrankiais supratimas](../../../04-tools) -- [Kaip veikia įrankių kvietimas](../../../04-tools) - - [Įrankių apibrėžimai](../../../04-tools) - - [Sprendimų priėmimas](../../../04-tools) - - [Vykdymas](../../../04-tools) - - [Atsakymo generavimas](../../../04-tools) - - [Architektūra: Spring Boot automatinis sujungimas](../../../04-tools) -- [Įrankių grandinėlės](../../../04-tools) -- [Programos paleidimas](../../../04-tools) -- [Programos naudojimas](../../../04-tools) - - [Išbandykite paprastą įrankių naudojimą](../../../04-tools) - - [Išbandykite įrankių grandinėlę](../../../04-tools) - - [Peržiūrėkite pokalbio eigą](../../../04-tools) - - [Eksperimentuokite su skirtingais užklausimais](../../../04-tools) -- [Pagrindinės sąvokos](../../../04-tools) - - [ReAct modelis (mąstymas ir veikimas)](../../../04-tools) - - [Įrankių aprašymai yra svarbūs](../../../04-tools) - - [Sesijos valdymas](../../../04-tools) - - [Klaidų tvarkymas](../../../04-tools) -- [Galimi įrankiai](../../../04-tools) -- [Kada naudoti agentus su įrankiais](../../../04-tools) -- [Įrankiai ir RAG](../../../04-tools) -- [Tolimesni žingsniai](../../../04-tools) +- [Vaizdo įrašo peržiūra](#vaizdo-įrašo-peržiūra) +- [Ką išmoksite](#ką-išmoksite) +- [Išankstiniai reikalavimai](#išankstiniai-reikalavimai) +- [Supratimas apie DI agentus su įrankiais](#supratimas-apie-di-agentus-su-įrankiais) +- [Kaip veikia įrankių kvietimas](#kaip-veikia-įrankių-kvietimas) + - [Įrankių apibrėžimai](#įrankių-apibrėžimai) + - [Sprendimų priėmimas](#sprendimų-priėmimas) + - [Vykdymas](#vykdymas) + - [Atsakymo generavimas](#atsakymo-generavimas) + - [Architektūra: Spring Boot automatinis sujungimas](#architektūra-spring-boot-automatinis-sujungimas) +- [Įrankių grandinavimas](#įrankių-grandinavimas) +- [Paleiskite programą](#paleiskite-programą) +- [Naudojimas](#kaip-naudotis-programa) + - [Išbandykite paprastą įrankio naudojimą](#išbandykite-paprastą-įrankių-naudojimą) + - [Išbandykite įrankių grandinavimą](#išbandykite-įrankių-grandinę) + - [Peržiūrėkite pokalbio eigą](#žiūrėkite-pokalbio-eigą) + - [Eksperimentuokite su skirtingais užklausimais](#eksperimentuokite-su-skirtingomis-užklausomis) +- [Pagrindinės sąvokos](#pagrindinės-sąvokos) + - [ReAct modelis (mąstymas ir veikimas)](#react-modelis-apsvarstymas-ir-veiksmas) + - [Įrankių aprašymai yra svarbūs](#įrankių-aprašymai-svarbūs) + - [Sesijų valdymas](#sesijų-valdymas) + - [Klaidų valdymas](#klaidos-tvarkymas) +- [Prieinami įrankiai](#galimi-įrankiai) +- [Kada naudoti įrankiais pagrįstus agentus](#kada-naudoti-įrankinius-agentus) +- [Įrankiai prieš RAG](#įrankiai-vs-rag) +- [Kiti žingsniai](#kiti-žingsniai) ## Vaizdo įrašo peržiūra -Peržiūrėkite šią tiesioginę sesiją, kurioje paaiškinama, kaip pradėti darbą su šiuo moduliu: +Peržiūrėkite šią tiesioginę sesiją, kuri paaiškina, kaip pradėti su šiuo moduliu: -AI Agents with Tools and MCP - Live Session +DI agentai su įrankiais ir MCP - tiesioginė sesija -## Ką sužinosite +## Ką išmoksite -Iki šiol jūs išmokote bendrauti su DI, efektyviai struktūruoti užklausas ir pagrįsti atsakymus savo dokumentais. Tačiau lieka pagrindinis apribojimas: kalbos modeliai gali tik generuoti tekstą. Jie negali patikrinti oro sąlygų, atlikti skaičiavimų, užklausti duomenų bazių ar sąveikauti su išorinėmis sistemomis. +Iki šiol jūs išmokote, kaip bendrauti su DI, efektyviai struktūruoti užklausas ir pagrįsti atsakymus savo dokumentuose. Tačiau yra esminė ribotybė: kalbos modeliai gali generuoti tik tekstą. Jie negali patikrinti orų, atlikti skaičiavimų, užklausti duomenų bazių ar sąveikauti su išorinėmis sistemomis. -Įrankiai tai keičia. Suteikdami modeliui funkcijų, kurias jis gali kviesti, jūs paverčiate jį iš teksto generatoriaus į agentą, kuris gali imtis veiksmų. Modelis pats nusprendžia, kada jam reikia įrankio, kurį įrankį naudoti ir kokius parametrus perduoti. Jūsų kodas vykdo funkciją ir grąžina rezultatą. Modelis įtraukia tą rezultatą į savo atsakymą. +Įrankiai tai keičia. Suteikdami modeliui prieigą prie funkcijų, kurias jis gali kviesti, jūs paverčiate jį iš teksto generatoriaus į agentą, kuris gali imtis veiksmų. Modelis nusprendžia, kada jam reikia įrankio, kurį įrankį naudoti ir kokius parametrus perduoti. Jūsų kodas vykdo funkciją ir grąžina rezultatą. Modelis įtraukia tą rezultatą į atsakymą. -## Priešistorė +## Išankstiniai reikalavimai -- Baigtas [Modulis 01 - Įvadas](../01-introduction/README.md) (Įdiegti Azure OpenAI resursai) -- Rekomenduojama baigti ankstesnius modulius (šis modulis nurodo [RAG sąvokas iš Modulis 03](../03-rag/README.md) įrankių ir RAG palyginime) -- Šakninėje direktorijoje yra `.env` failas su Azure kredencialais (sukurtas vykdant `azd up` Modulyje 01) +- Įvykdytas [Modulis 01 – Įvadas](../01-introduction/README.md) (Azure OpenAI ištekliai deploy‘inti) +- Rekomenduojama įvykdyti ankstesnius modulius (šis modulis remiasi [RAG sąvokomis iš Modulio 03](../03-rag/README.md) palyginime Įrankiai prieš RAG) +- Šakniniame kataloge turi būti `.env` failas su Azure kredencialais (sukurtas vykdant `azd up` Module 01 metu) -> **Pastaba:** Jeigu dar nebaigėte Modulio 01, pirmiausia sekite ten pateiktas diegimo instrukcijas. +> **Pastaba:** Jei dar nebaigėte Modulio 01, pirmiausia vykdykite ten pateiktas diegimo instrukcijas. -## Dirbtinio intelekto agentų su įrankiais supratimas +## Supratimas apie DI agentus su įrankiais -> **📝 Pastaba:** Šio modulio terminas „agentai“ reiškia DI asistentus patobulintus su įrankių kvietimo galimybėmis. Tai skiriasi nuo **Agentinio DI** modelių (autonominių agentų su planavimu, atmintimi ir kelių žingsnių mąstymu), kuriuos aptarsime [Modulis 05: MCP](../05-mcp/README.md). +> **📝 Pastaba:** Šio modulio terminas „agentai“ reiškia DI pagalbininkus, patobulintus įrankių kvietimo funkcionalumu. Tai skiriasi nuo **Agentinio DI** modelių (autonomi agentai su planavimu, atmintimi ir daugiapakopiu mąstymu), kuriuos apžvelgsime [Modulyje 05: MCP](../05-mcp/README.md). -Be įrankių kalbos modelis gali tik generuoti tekstą iš savo mokymosi duomenų. Paklauskite jo apie esamą orą, ir jis turi spėti. Pateikite įrankius, ir jis gali kviesti oro sąlygų API, atlikti skaičiavimus ar užklausti duomenų bazę — ir tuomet į savo atsakymą įtraukti tuos tikrus rezultatus. +Be įrankių kalbos modelis gali tik generuoti tekstą iš savo mokymosi duomenų. Klauskite, koks yra dabartinis oras, ir jis turi spėti. Suteikite įrankius, ir jis gali kviesti orų API, atlikti skaičiavimus arba užklausti duomenų bazę – tada įterpti tuos tikrus rezultatus į savo atsakymą. -Without Tools vs With Tools +Be įrankių vs Su įrankiais -*Be įrankių modelis tik spėlioja — su įrankiais jis gali kviesti API, atlikti skaičiavimus ir grąžinti realaus laiko duomenis.* +*Be įrankių modelis tik spėja – su įrankiais jis kviečia API, atlieka skaičiavimus ir pateikia realaus laiko duomenis.* -DI agentas su įrankiais seka **Mąstymo ir Veikimo (ReAct)** modelį. Modelis ne tik atsako — jis mąsto apie tai, ko jam reikia, veikia kviesdamas įrankį, stebi rezultatą ir tada sprendžia, ar veikti toliau, ar pateikti galutinį atsakymą: +DI agentas su įrankiais vykdo **Mąstymo ir Veikimo (ReAct)** ciklą. Modelis ne tik atsako – jis mąsto, ko jam reikia, veikia kviesdamas įrankį, stebi rezultatą ir tada sprendžia, ar daryti dar vieną veiksmą, ar pateikti galutinį atsakymą: -1. **Mąsto** — Agentas analizuojapro kalbėtojo klausimą ir nustato kokios informacijos jam reikia -2. **Veikia** — Agentas pasirenka tinkamą įrankį, sugeneruoja tinkamus parametrus ir jį kviečia -3. **Stebi** — Agentas gauna įrankio išvestį ir įvertina rezultatą -4. **Kartoja arba atsako** — Jei reikalinga daugiau duomenų, agentas kartoja ciklą; priešingu atveju sukuria natūralios kalbos atsakymą +1. **Mąstyti** — agentas analizuoja vartotojo klausimą ir nustato, kokios informacijos jam reikia +2. **Veikti** — agentas pasirenka tinkamą įrankį, sukuria teisingus parametrus ir jį kviečia +3. **Stebėti** — agentas gauna įrankio išvestį ir įvertina rezultatą +4. **Kartoti arba Atsakyti** — jei reikia daugiau duomenų, agentas sugrįžta į pradžią; jei ne – sudaro natūralios kalbos atsakymą -ReAct Pattern +ReAct modelis -*ReAct ciklas — agentas mąsto, ką daryti, veikia kviesdamas įrankį, stebi rezultatą ir kartoja, kol gali pateikti galutinį atsakymą.* +*ReAct ciklas – agentas mąsto, ką daryti, veikia kviesdamas įrankį, stebi rezultatą ir kartoja tol, kol gali pateikti galutinį atsakymą.* -Tai vyksta automatiškai. Jūs apibrėžiate įrankius ir jų aprašymus. Modelis priima sprendimus, kada ir kaip juos naudoti. +Tai vyksta automatiškai. Jūs apibrėžiate įrankius ir jų aprašymus. Modelis sprendžia, kada ir kaip juos naudoti. ## Kaip veikia įrankių kvietimas @@ -78,7 +78,7 @@ Tai vyksta automatiškai. Jūs apibrėžiate įrankius ir jų aprašymus. Modeli [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Jūs apibrėžiate funkcijas su aiškiais aprašymais ir parametrų specifikacijomis. Modelis mato šiuos aprašymus savo sistemos užklausoje ir supranta, ką kiekvienas įrankis atlieka. +Jūs apibrėžiate funkcijas su aiškiais aprašymais ir parametrų specifikacijomis. Modelis mato šiuos aprašymus sistemos užklausoje ir supranta, ką kiekvienas įrankis daro. ```java @Component @@ -96,139 +96,139 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Asistentas automatiškai sujungiamas per Spring Boot su: -// - ChatModel komponentu -// - Visais @Tool metodais iš @Component klasių +// Asistentas automatiškai sujungtas su Spring Boot: +// - ChatModel komponentas +// - Visos @Tool metodai iš @Component klasių // - ChatMemoryProvider sesijų valdymui ``` -Žemiau pateiktame diagramoje aiškinamos visos anotacijos ir kaip kiekvienas jų elementas padeda DI suprasti, kada kviečiama įrankį ir kokius argumentus perduoti: +Žemiau pateiktas diagrama išskaido kiekvieną anotaciją ir parodo, kaip kiekviena dalis padeda DI suprasti, kada kviesti įrankį ir kokius argumentus perduoti: -Anatomy of Tool Definitions +Įrankių apibrėžimų anatomija -*Įrankio apibrėžimo anatomija — @Tool nurodo DI, kada naudoti įrankį, @P aprašo kiekvieną parametrą, o @AiService sujungia viską paleidimo metu.* +*Įrankio apibrėžimo anatomija — @Tool nurodo DI, kada naudoti įrankį, @P aprašo kiekvieną parametrą, o @AiService automatiškai sujungia viską paleidimo metu.* -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ir paklauskite: -> - „Kaip integruočiau tikrą oro API, pvz., OpenWeatherMap, vietoj imitacinių duomenų?“ -> - „Kas sudaro gerą įrankio aprašymą, kuris padeda DI naudoti įrankį teisingai?“ -> - „Kaip tvarkyti API klaidas ir kvotų ribojimus įrankių įgyvendinime?“ +> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ir klauskite: +> - „Kaip integruočiau tikrą orų API, pvz., OpenWeatherMap, vietoje imituotų duomenų?“ +> - „Kas yra geras įrankio aprašymas, kuris padeda DI jį teisingai naudoti?“ +> - „Kaip tvarkyti API klaidas ir ribojimus įrankių implementacijoje?“ ### Sprendimų priėmimas -Kai vartotojas paklausia „Koks oras Sietle?“, modelis neatsitiktinai pasirenka įrankį. Jis lygina vartotojo intenciją su visų prieinamų įrankių aprašymais, vertina kiekvieno atitikimą ir pasirenka geriausiai tinkantį. Tuomet sugeneruoja struktūruotą funkcijos kvietimą su tinkamais parametrais — šiuo atveju, nustatydamas `location` į `"Seattle"`. +Kai vartotojas klausia „Koks oras Siatle?“, modelis nepasirenka įrankio atsitiktinai. Jis lygina vartotojo ketinimą su kiekvieno įrankio aprašymu, įvertina svarbą ir pasirenka geriausią atitikimą. Tada sugeneruoja struktūruotą funkcijos kvietimą su tinkamais parametrais – šiuo atveju nustatydamas `location` į `"Seattle"`. -Jei jokio įrankio neatitinka vartotojo užklausos, modelis grįžta prie atsakymo pagal savo žinias. Jei keli įrankiai atitinka, jis pasirenka konkretžiausią. +Jei jokio įrankio užklausa neatitinka, modelis grįžta prie atsakymo iš savo žinių. Jei keli įrankiai tinka, pasirenka patį specifiniausią. -How the AI Decides Which Tool to Use +Kaip DI nusprendžia, kurį įrankį naudoti -*Modelis įvertina kiekvieną prieinamą įrankį pagal vartotojo intenciją ir pasirenka geriausiai tinkantį — todėl aiškūs, konkretūs įrankių aprašymai yra labai svarbūs.* +*Modelis vertina visus galimus įrankius pagal vartotojo ketinimą ir pasirenka geriausią atitikmenį – todėl svarbu rašyti aiškius, konkrečius įrankių aprašymus.* ### Vykdymas [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot automatiškai sujungia deklaratyvų `@AiService` interfeisą su visais registruotais įrankiais, o LangChain4j vykdo įrankių kvietimus automatiškai. Užkulisiuose pilnas įrankio kvietimo procesas praeina per šešias stadijas — nuo vartotojo natūralios kalbos klausimo iki natūralaus atsakymo: +Spring Boot automatiškai susieja deklaratyvų `@AiService` interfeisą su visais registruotais įrankiais, o LangChain4j automatiškai vykdo įrankių kvietimus. Užkulisiuose viso įrankio kvietimo procesas vyksta per šešias stadijas – nuo vartotojo natūralios kalbos klausimo iki natūralaus kalbos atsakymo: -Tool Calling Flow +Įrankio kvietimo eiga -*Visas procesas — vartotojas užduoda klausimą, modelis pasirenka įrankį, LangChain4j jį vykdo, o modelis integruoja rezultatą į natūralų atsakymą.* +*Pilnas procesas – vartotojas užduoda klausimą, modelis pasirenka įrankį, LangChain4j jį vykdo, o modelis įtraukia rezultatą į natūralų atsakymą.* -Jeigu vykdėte [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) Modulyje 00, jau matėte šio modelio veikimą — „Calculator“ įrankiai buvo kviečiami taip pat. Žemiau pateiktame sekos diagramoje matyti, kas vyko užkulisiuose to demo metu: +Užkulisiuose `AiServices` vykdo tą patį įrankių kvietimo ciklą bet kuriam įrankiui – čia pavaizduota su paprastu `Calculator`. Sekos diagrama žemiau rodo, kas vyksta po gaubtu: -Tool Calling Sequence Diagram +Įrankio kvietimo sekos diagrama -*Įrankio kvietimo ciklas greitojo starto demo metu — `AiServices` siunčia jūsų žinutę ir įrankių schemas LLM, LLM atsako struktūruotu funkcijos kvietimu pavyzdžiui `add(42, 58)`, LangChain4j lokaliai vykdo `Calculator` metodą ir grąžina rezultatą galutiniam atsakymui.* +*Įrankių kvietimo ciklas – `AiServices` siunčia jūsų žinutę ir įrankių schemas LLM, LLM atsako funkcijos kvietimu pvz., `add(42, 58)`, LangChain4j vietoje vykdo `Calculator` metodą ir pateikia rezultatą atgal galutiniam atsakymui.* -> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ir paklauskite: +> **🤖 Išbandykite su [GitHub Copilot](https://github.com/features/copilot) Chat:** Atidarykite [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ir klauskite: > - „Kaip veikia ReAct modelis ir kodėl jis efektyvus DI agentams?“ > - „Kaip agentas nusprendžia, kurį įrankį naudoti ir kokia tvarka?“ -> - „Kas nutinka, jei įrankio vykdymas nepavyksta – kaip tinkamai tvarkyti klaidas?“ +> - „Kas nutinka, jei įrankio vykdymas nepavyksta – kaip tvarkingai tvarkyti klaidas?“ ### Atsakymo generavimas -Modelis gauna oro duomenis ir formatuoja juos į natūralios kalbos atsakymą vartotojui. +Modelis gauna orų duomenis ir suformuoja natūralios kalbos atsakymą vartotojui. ### Architektūra: Spring Boot automatinis sujungimas -Šis modulis naudoja LangChain4j integraciją su Spring Boot per deklaratyvius `@AiService` interfeisus. Paleidimo metu Spring Boot suranda kiekvieną `@Component`, kuriame yra `@Tool` metodai, jūsų `ChatModel` komponentą ir `ChatMemoryProvider`, ir sujungia juos į vieną `Assistant` interfeisą be jokio papildomo boilerplate kodo. +Šis modulis naudoja LangChain4j Spring Boot integraciją su deklaratyviais `@AiService` interfeisais. Paleidimo metu Spring Boot suranda kiekvieną `@Component`, kuriame yra `@Tool` metodų, jūsų `ChatModel` bean‘ą ir `ChatMemoryProvider` – ir visus juos sujungia į vieną `Assistant` interfeisą be jokio boilerplate kodo. -Spring Boot Auto-Wiring Architecture +Spring Boot automatinio sujungimo architektūra -*@AiService interfeisas sujungia ChatModel, įrankius ir atminties tiekėją — Spring Boot automatiškai atlieka visą sujungimą.* +*@AiService interfeisas jungia ChatModel, įrankių komponentus ir atminties tiekėją – Spring Boot automatiškai atlieka visą sujungimą.* -Toliau pateikta viso užklausos gyvenimo ciklo sekos diagrama — nuo HTTP užklausos per kontrolerį, servisą ir automatiškai sujungtą proxy, iki įrankio vykdymo ir atgal: +Štai pilnas užklausos gyvavimo ciklas sekos diagramoje – nuo HTTP užklausos per kontrolerį, servisą, auto-sujungtą proxy iki įrankio vykdymo ir atgal: -Spring Boot Tool Calling Sequence +Spring Boot įrankių kvietimo sekos diagrama -*Pilnas Spring Boot užklausos ciklas — HTTP užklausa praeina per kontrolerį ir servisą iki automatiškai sujungto Assistant proxy, kuris automatizuoja LLM ir įrankių kvietimus.* +*Pilnas Spring Boot užklausos gyvavimo ciklas – HTTP užklausa praeina per kontrolerį ir servisą iki auto-sujungto Assistant proxy, kuris koreliuoja LLM ir įrankių kvietimus automatiškai.* Pagrindiniai šio požiūrio privalumai: -- **Spring Boot automatinis sujungimas** — ChatModel ir įrankiai automatiškai įjungiami -- **@MemoryId modelis** — automatinis sesijos pagrindu veikiantis atminties valdymas -- **Vienas egzempliorius** — Assistant sukuriamas vieną kartą ir pakartotinai naudojamas geresniam našumui -- **Tipų saugus vykdymas** — Java metodai kviečiami tiesiogiai su tipų konvertavimu -- **Daugiaturninė orkestracija** — Automatiškai valdo įrankių grandinėlę -- **Nulinis boilerplate** — Nereikia rankiniu `AiServices.builder()` kvietimų arba atminties HashMap +- **Spring Boot automatinis sujungimas** – ChatModel ir įrankiai įterpiami automatiškai +- **@MemoryId modelis** – automatinis sesijos pagrindu valdomas atminties valdymas +- **Viena instancija** – Assistant sukuriamas vieną kartą ir naudojamas pakartotinai dėl geresnio našumo +- **Tipų saugus vykdymas** – Java metodai kviečiami tiesiogiai su tipo konvertacijomis +- **Daugiataukio valdymas** – automatiškai palaiko įrankių grandinavimą +- **Nulis boilerplate** – jokių rankinių `AiServices.builder()` kvietimų ar atminties HashMap -Alternatyvūs metodai (rankinis `AiServices.builder()`) reikalauja daugiau kodo ir neturi Spring Boot integracijos privalumų. +Alternatyvūs metodai (rankinis `AiServices.builder()`) reikalauja daugiau kodo ir neturi Spring Boot integracijos pranašumų. -## Įrankių grandinėlės +## Įrankių grandinavimas -**Įrankių grandinėlė** — Tikroji įrankiais pagrįstų agentų galia atsiskleidžia kai į vieną klausimą reikia kelių įrankių. Paklauskite „Koks oras Sietle pagal Farenheito skalę?“ ir agentas automatiškai sudaro grandinėlę iš dviejų įrankių: pirmiausia kviečia `getCurrentWeather`, kad gautų temperatūrą Celsijumi, tada perduoda tą reikšmę į `celsiusToFahrenheit` konvertavimui — visa tai viename pokalbio cikle. +**Įrankių grandinavimas** – tikroji įrankiais pagrįstų agentų galia pasireiškia tada, kai vienas klausimas reikalauja kelių įrankių. Paklauskite „Koks oras Siatle Fahrenheito laipsniais?“ ir agentas automatiškai sujungia du įrankius: pirmiausia kviečia `getCurrentWeather`, kad gautų temperatūrą Celsijumi, tada perduoda tą vertę `celsiusToFahrenheit` konvertavimui – visa tai per vieną pokalbio turą. -Tool Chaining Example +Įrankių grandinavimo pavyzdys -*Įrankių grandinėlės veikimas — agentas pirmiausia kviečia getCurrentWeather, tada persiunčia Celsijaus rezultatą į celsiusToFahrenheit ir pateikia jungtinį atsakymą.* +*Įrankių grandinavimas veiksme – agentas pirmiausia kviečia getCurrentWeather, tada perduoda Celsijaus rezultatą į celsiusToFahrenheit ir pateikia kombinuotą atsakymą.* -**Gražios gedimų tvarkymo reakcijos** — Paklauskite apie orą mieste, kuris nėra imitaciniuose duomenyse. Įrankis grąžina klaidos pranešimą, o DI paaiškina, kad negali padėti namiest to, kad programėlė sugestų. Įrankiai saugiai reaguoja į klaidas. Žemiau pateikta schema rodo skirtumą tarp dviejų požiūrių — tinkamai tvarkant klaidas agentas užfiksuoja išimtį ir atsako pagalbiniu pranešimu, o be to taikomoji programa sugenda: +**Tvarkingos klaidos** – paklauskite apie orą mieste, kuris nėra imituotuose duomenyse. Įrankis grąžina klaidos pranešimą, o DI aiškina, kad negali padėti, vietoje to, kad sužlugtų. Įrankiai saugiai tvarko klaidas. Žemiau diagrama lygina abi situacijas – su tinkamu klaidų apdorojimu agentas pagauna išimtį ir atsako pagalbingu paaiškinimu, o be jo visa programa sugenda: -Error Handling Flow +Klaidų valdymo eiga -*Kai įrankis sugenda, agentas užfiksuoja klaidą ir atsako naudingą paaiškinimą vietoje programos gedimo.* +*Kai įrankis nepavyksta, agentas pagauna klaidą ir atsako su pagalbingu paaiškinimu vietoje programos sutrikimo.* -Tai vyksta viename pokalbio cikle. Agentas automatiškai orkestruoja kelis įrankių kvietimus. +Tai įvyksta per vieną pokalbio turą. Agentas autonomiškai koordinuoja kelis įrankių kvietimus. -## Programos paleidimas +## Paleiskite programą **Patikrinkite diegimą:** -Įsitikinkite, kad `.env` faile šakninėje direktorijoje yra Azure kredencialai (sukurti Modulio 01 metu). Paleiskite tai iš šio modulio katalogo (`04-tools/`): +Įsitikinkite, kad root kataloge yra `.env` failas su Azure kredencialais (sukurtas Modulyje 01). Paleiskite šią komandą modulio kataloge (`04-tools/`): **Bash:** ```bash -cat ../.env # Turėtų parodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Turėtų parodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Turėtų rodyti AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Paleiskite programą:** -> **Pastaba:** Jeigu jau paleidote visas programas naudodami `./start-all.sh` iš šakninės direktorijos (kaip aprašyta Modulyje 01), šis modulis jau veikia 8084 porte. Galite praleisti paleidimo komandas ir nueiti tiesiai į http://localhost:8084. +> **Pastaba:** Jei jau paleidote visas programas naudodami `./start-all.sh` iš root katalogo (kaip aprašyta Modulyje 01), šis modulis jau veikia prievade 8084. Galite praleisti toliau pateiktas paleidimo komandas ir tiesiog nueiti į http://localhost:8084. -**1 variantas: naudoti Spring Boot Dashboard (rekomenduojama VS Code vartotojams)** +**1 variantas: naudokite Spring Boot Dashboard (rekomenduojama VS Code naudotojams)** -Dev konteineryje yra Spring Boot Dashboard plėtinys, suteikiantis vizualią sąsają visoms Spring Boot programoms valdyti. Jį rasite kairėje pusėje esančiame veiklų juostoje VS Code (pažymėkite Spring Boot piktogramą). +Dev container yra Spring Boot Dashboard plėtinys, suteikiantis vizualią sąsają valdyti visas Spring Boot programas. Jį rasite kairėje pusėje esančiame Activity Bar (ieškokite Spring Boot ikonėlės). -Iš Spring Boot Dashboard galite: -- Peržiūrėti visas prieinamas Spring Boot programas darbo aplinkoje +Per Spring Boot Dashboard galite: +- Matyti visas prieinamas Spring Boot programas darbo aplinkoje - Vienu paspaudimu paleisti / sustabdyti programas -- Matyti programų realaus laiko žurnalus -- Stebėti programos būseną -Tiesiog spustelėkite paleidimo mygtuką šalia „tools“, kad pradėtumėte šį modulį, arba paleiskite visus modulius vienu metu. +- Realizuoti programų žurnalų peržiūrą +- Stebėti programų būseną -Vaizdas, kaip atrodo Spring Boot valdymo skydelis VS Code: +Tiesiog spustelėkite paleidimo mygtuką šalia „tools“, kad paleistumėte šį modulį, arba paleiskite visus modulius vienu metu. -Spring Boot Dashboard +Štai kaip atrodo Spring Boot Dashboard VS Code aplinkoje: +Spring Boot Skydelis -*Spring Boot valdymo skydelis VS Code — paleiskite, sustabdykite ir stebėkite visus modulius iš vienos vietos* +*Spring Boot skydelis VS Code — paleiskite, sustabdykite ir stebėkite visus modulius vienoje vietoje* -**2 variantas: naudojant shell scenarijus** +**2 variantas: naudojant apvalkalo scenarijus** -Paleiskite visas žiniatinklio programas (modulius 01-04): +Paleiskite visas žiniatinklio programas (modulius 01–04): **Bash:** ```bash @@ -238,7 +238,7 @@ cd .. # Iš šaknininio katalogo **PowerShell:** ```powershell -cd .. # Iš root katalogo +cd .. # Iš šaknininio katalogo .\start-all.ps1 ``` @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Abu scenarijai automatiškai įkelia aplinkos kintamuosius iš pagrindinio `.env` failo ir sukompiliuos JAR failus, jei jų nėra. +Abu scenarijai automatiškai įkrauna aplinkos kintamuosius iš šakninio `.env` failo ir sukurs JAR failus, jei jų nėra. -> **Pastaba:** Jei norite prieš paleisdami rankiniu būdu sukompiliuoti visus modulius: +> **Pastaba:** jei norite prieš pradėdami rankiniu būdu sukompiliuoti visus modulius: > > **Bash:** > ```bash @@ -272,9 +272,9 @@ Abu scenarijai automatiškai įkelia aplinkos kintamuosius iš pagrindinio `.env > mvn clean package -DskipTests > ``` -Naršyklėje atidarykite http://localhost:8084. +Atidarykite naršyklėje http://localhost:8084. -**Norint sustabdyti:** +**Norėdami sustabdyti:** **Bash:** ```bash @@ -290,98 +290,98 @@ cd .. && ./stop-all.sh # Visi moduliai cd ..; .\stop-all.ps1 # Visi moduliai ``` -## Kaip naudoti programą +## Kaip naudotis programa -Programa siūlo žiniatinklio sąsają, kurioje galite bendrauti su AI agentu, turinčiu prieigą prie orų ir temperatūros konvertavimo įrankių. Štai kaip atrodo sąsaja — ji apima greito pradžios pavyzdžius ir pokalbių panelę užklausoms siųsti: +Programa siūlo žiniatinklio sąsają, kurioje galite bendrauti su DI agentu, turinčiu prieigą prie orų ir temperatūros konvertavimo įrankių. Štai kaip atrodo sąsaja — ji apima greituosius pavyzdžius ir pokalbių skydelį užklausoms siųsti: -AI Agent Tools Interface +DI Agentų Įrankių Sąsaja -*AI agento įrankių sąsaja – greiti pavyzdžiai ir pokalbių sąsaja darbui su įrankiais* +*DI agentų įrankių sąsaja – greiti pavyzdžiai ir pokalbių sąsaja įrankių naudojimui* -### Išbandykite paprastą įrankio naudojimą +### Išbandykite paprastą įrankių naudojimą -Pradėkite nuo paprastos užklausos: „Konvertuokite 100 laipsnių Farenheito į Celsijų“. Agentas supranta, kad reikia naudoti temperatūros konvertavimo įrankį, iškviečia jį su tinkamais parametrais ir pateikia rezultatą. Pastebėkite, kaip natūraliai tai jaučiasi — jūs nenurodėte, kurį įrankį naudoti ar kaip jį iškviesti. +Pradėkite nuo paprastos užklausos: „Konvertuokite 100 laipsnių Farenheito į Celsijų“. Agentas atpažįsta, kad jam reikia temperatūros konvertavimo įrankio, iškviečia jį su tinkamais parametrais ir pateikia rezultatą. Pastebėkite, kaip natūraliai tai veikia – jūs nenurodėte, kurį įrankį naudoti ar kaip jį iškviesti. -### Išbandykite įrankių grandinėlę +### Išbandykite įrankių grandinę -Dabar pabandykite kažką sudėtingesnio: „Koks oras Sietle ir konvertuokite jį į Farenheitą?“ Stebėkite, kaip agentas sprendžia žingsnis po žingsnio. Pirmiausia gauna orų prognozę (kuri pateikiama Celsijumi), supranta, kad reikia konvertuoti į Farenheitą, iškviečia konvertavimo įrankį ir sujungia abu rezultatus į vieną atsakymą. +Dabar pabandykite ką nors sudėtingesnio: „Koks oras Sietle ir konvertuokite jį į Farenheitą?“ Stebėkite, kaip agentas atlieka veiksmus žingsnis po žingsnio. Pirmiausia gauna orą (kuris pateikiamas Celsijais), supranta, kad reikia konvertuoti į Farenheitą, iškviečia konvertavimo įrankį ir sujungia abu rezultatus į vieną atsakymą. -### Peržiūrėkite pokalbio eigą +### Žiūrėkite pokalbio eigą -Pokalbių sąsaja saugo pokalbio istoriją, leidžiantį palaikyti kelių raundų sąveiką. Matote visas ankstesnes užklausas ir atsakymus, kas palengvina pokalbio stebėjimą ir leidžia suprasti, kaip agentas stato kontekstą per kelis keitimus. +Pokalbių sąsaja saugo pokalbio istoriją, leidžia turėti daugkartinius pokalbius. Matote visas ankstesnes užklausas ir atsakymus, todėl lengva sekti pokalbį ir suprasti, kaip agentas kuria kontekstą per kelis mainus. -Conversation with Multiple Tool Calls +Daugiapakopis pokalbis su kelių įrankių iškvietimais -*Daugiaraundis pokalbis, rodantis paprastus konvertavimus, orų paieškas ir įrankių grandinėlę* +*Daugiapakopis pokalbis, rodantis paprastas konvertacijas, orų tikrinimus ir įrankių grandinę* ### Eksperimentuokite su skirtingomis užklausomis Išbandykite įvairius derinius: -- Orų paieškos: „Koks oras Tokijuje?“ -- Temperatūros konvertavimas: „Kiek yra 25 °C kelvinuose?“ -- Kombinuotos užklausos: „Patikrink orą Paryžiuje ir pasakyk, ar temperatūra viršija 20 °C“ +- Orų patikrinimai: „Koks oras Tokijuje?“ +- Temperatūros konvertavimai: „Kokia yra 25 °C pagal kelviną?“ +- Derinamos užklausos: „Patikrink orą Paryžiuje ir pasakyk, ar temperatūra viršija 20 °C“ -Stebėkite, kaip agentas interpretuoja natūralią kalbą ir pritaiko tinkamus įrankių iškvietimus. +Pastebėkite, kaip agentas interpretuoja natūralią kalbą ir susieja ją su tinkamais įrankių iškvietimais. -## Esminės sąvokos +## Pagrindinės sąvokos -### ReAct modelis (mąstymas ir veikimas) +### ReAct modelis (Apsvarstymas ir Veiksmas) -Agentas kaitaliojasi tarp mąstymo (sprendžiant, ką daryti) ir veikimo (naudojant įrankius). Šis modelis leidžia autonomiškai spręsti problemas, o ne tik vykdyti komandas. +Agentas kinta tarp mąstymo (sprendimo, ką daryti) ir veikimo (įrankių naudojimo). Šis modelis leidžia autonomiškai spręsti problemas, o ne tik reaguoti į nurodymus. ### Įrankių aprašymai svarbūs -Jūsų įrankių aprašymų kokybė tiesiogiai lemia, kaip gerai agentas juos naudoja. Aiškūs, konkretūs aprašymai padeda modeliui suprasti, kada ir kaip iškviesti kiekvieną įrankį. +Įrankių aprašymų kokybė tiesiogiai veikia, kaip gerai agentas juos naudoja. Aiškūs, konkretūs aprašymai padeda modeliui suprasti, kada ir kaip iškviesti kiekvieną įrankį. -### Sesijos valdymas +### Sesijų valdymas -`@MemoryId` anotacija leidžia automatizuotą sesijų pagrindu veikiančią atminties valdymo funkciją. Kiekvienas sesijos ID gauna savo `ChatMemory` egzempliorių, kurį valdo `ChatMemoryProvider` servisas, todėl keli vartotojai gali bendrauti su agentu vienu metu, nesimaišant jų pokalbiams. Toliau pateiktas diagramas parodo, kaip keli vartotojai nukreipiami į atskiras atminties saugyklas pagal jų sesijos ID: +`@MemoryId` anotacija leidžia automatiškai valdyti atmintį pagal sesiją. Kiekvienam sesijos ID priskiriama atskira `ChatMemory` egzempliorius, kuriuo rūpinasi `ChatMemoryProvider` komponentas, todėl keli vartotojai gali bendrauti su agentu vienu metu, nesimaišant jų pokalbiams. Toliau pateikta diagrama rodo, kaip keli vartotojai nukreipiami į izoliuotas atminties saugyklas pagal savo sesijos ID: -Session Management with @MemoryId +Sesijų valdymas su @MemoryId -*Kiekvienas sesijos ID atitinka atskirą pokalbio istoriją — vartotojai niekada nemato vienas kito žinučių.* +*Kiekvienas sesijos ID atitinka izoliuotą pokalbio istoriją — vartotojai nemato vienas kito žinučių.* -### Klaidų tvarkymas +### Klaidos tvarkymas -Įrankiai gali sugesti — API neatsako, parametrai gali būti neteisingi, išorinės paslaugos gali neveikti. Produkcijos agentai turi apdoroti klaidas, kad modelis galėtų aiškinti problemas arba bandyti alternatyvas, o ne sugadinti visą programą. Kai įrankis meta išimtį, LangChain4j ją sugavęs perduoda klaidos žinutę modeliui, kuris gali natūralia kalba paaiškinti problemą. +Įrankiai gali sugesti — API laiko limitai, netinkami parametrai, išorinės paslaugos gali nutrūkti. Produkciniai agentai turi valdyti klaidas, kad modelis galėtų paaiškinti problemas arba bandyti alternatyvas, o ne sugadinti visą programą. Kai įrankis meta išimtį, LangChain4j ją pagauna ir grąžina klaidos pranešimą modeliui, kuris gali paaiškinti problemą natūralia kalba. ## Galimi įrankiai -Žemiau pateikta diagrama rodo platų įrankių ekosistemą, kurią galite kurti. Šis modulis demonstruoja orų ir temperatūros įrankius, tačiau tas pats `@Tool` modelis veikia bet kuriam Java metodui — nuo duomenų bazių užklausų iki mokėjimų apdorojimo. +Žemiau esanti diagrama parodo plačią įrankių ekosistemą, kurią galite sukurti. Šis modulis demonstruoja orų ir temperatūros įrankius, bet tas pats `@Tool` modelis veikia bet kuriai Java metodui — nuo duomenų bazių užklausų iki mokėjimų apdorojimo. -Tool Ecosystem +Įrankių Ekosistema -*Bet kuris Java metodas su `@Tool` anotacija tampa prieinamas AI — šis modelis taikomas duomenų bazėms, API, el. paštui, failų operacijoms ir kt.* +*Bet kuris Java metodas, pažymėtas @Tool, tampa prieinamas DI — modelis plečiasi iki duomenų bazių, API, el. pašto, failų operacijų ir daugiau.* -## Kada naudoti įrankiais pagrįstus agentus +## Kada naudoti įrankinius agentus -Ne kiekvienai užklausai reikia įrankių. Sprendimas priklauso nuo to, ar AI turi sąveikauti su išorinėmis sistemomis, ar gali atsakyti iš savo žinių. Toliau pateiktas gidas apibendrina, kada įrankiai pridės vertės, o kada jų nereikia: +Ne kiekvienai užklausai reikalingi įrankiai. Sprendimas priklauso nuo to, ar DI turi bendrauti su išorinėmis sistemomis, ar gali atsakyti remdamasis savo žiniomis. Toliau pateiktas vadovas apibendrina, kada įrankiai prideda vertės, o kada jų nereikia: -When to Use Tools +Kada naudoti įrankius -*Greitas sprendimų vadovas — įrankiai skirti realaus laiko duomenims, skaičiavimams ir veiksmams; bendros žinios ir kūrybinės užduotys jų nereikalauja.* +*Greitas sprendimų vadovas — įrankiai skirti realaus laiko duomenims, skaičiavimams ir veiksmams; bendrosioms žinioms ir kūrybingiems darbams jie nereikalingi.* -## Įrankiai prieš RAG +## Įrankiai vs RAG -Moduliai 03 ir 04 abu plečia AI galimybes, bet iš esmės skirtingais būdais. RAG suteikia modeliui prieigą prie **žinių**, gaunant dokumentus. Įrankiai suteikia modeliui galimybę imtis **veiksmų**, kviečiant funkcijas. Žemiau pateikta diagrama palygina šiuos du metodus šalia vienas kito — nuo veikimo principų iki kompromisų: +3 ir 4 moduliai abu plečia DI galimybes, bet fundamentaliai skirtingais būdais. RAG suteikia modeliui prieigą prie **žinių** per dokumentų gavimą. Įrankiai suteikia modeliui galimybę atlikti **veiksmus** iškviečiant funkcijas. Žemiau pateikta diagrama lygina šiuos du metodus šalia — nuo to, kaip veikia kiekviena darbo eiga, iki kompromisų tarp jų: -Tools vs RAG Comparison +Įrankių ir RAG palyginimas -*RAG ištraukia informaciją iš statinių dokumentų — įrankiai atlieka veiksmus ir gauna dinamiškus, realaus laiko duomenis. Daugelis produkcijos sistemų naudoja abu kartu.* +*RAG renka informaciją iš statinių dokumentų — įrankiai atlieka veiksmus ir gauna dinamiškus, realaus laiko duomenis. Daugelis gamybos sistemų naudoja abu.* -Praktikoje dauguma produkcinių sistemų derina abu metodus: RAG naudojamas atsakymams pagrįsti dokumentacijoje, o įrankiai – gyviems duomenims gauti arba operacijoms atlikti. +Praktikoje dauguma gamybos sistemų derina abu metodus: RAG atsakymų pagrindimui jūsų dokumentacijoje ir Įrankius gyvų duomenų gavimui arba operacijų vykdymui. -## Tolimesni veiksmai +## Kiti žingsniai -**Kitas modulis:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Kitas modulis:** [05-mcp - Modelio konteksto protokolas (MCP)](../05-mcp/README.md) --- -**Navigacija:** [← Ankstesnis: Modulis 03 - RAG](../03-rag/README.md) | [Atgal į pradžią](../README.md) | [Kitas: Modulis 05 - MCP →](../05-mcp/README.md) +**Navigacija:** [← Ankstesnis: Modulis 03 - RAG](../03-rag/README.md) | [Atgal į pradžią](../README.md) | [Toliau: Modulis 05 - MCP →](../05-mcp/README.md) --- -**Atsakomybės atsisakymas**: -Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatizuotuose vertimuose gali būti klaidų ar netikslumų. Originalus dokumentas gimtąja kalba turėtų būti laikomas autoritetingu šaltiniu. Esant svarbiai informacijai, rekomenduojama naudoti profesionalų žmogaus vertimą. Mes neatsakome už bet kokius nesusipratimus ar neteisingą interpretavimą, kylančius iš šio vertimo naudojimo. +**Atsakomybės apribojimas**: +Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojama naudoti profesionalų žmogiškąjį vertimą. Mes neatsakome už jokius nesusipratimus ar neteisingą interpretaciją, kilusią naudojantis šiuo vertimu. \ No newline at end of file diff --git a/translations/lt/README.md b/translations/lt/README.md index d88bad832..394028b86 100644 --- a/translations/lt/README.md +++ b/translations/lt/README.md @@ -2,18 +2,18 @@ # LangChain4j pradedantiesiems -Kursas kuriant AI programas su LangChain4j ir Azure OpenAI GPT-5.2, nuo paprasto pokalbio iki AI agentų. +Kursas dirbant su AI programomis naudojant LangChain4j ir Azure OpenAI GPT-5.2 – nuo pagrindinio pokalbio iki AI agentų. ### 🌐 Daugiakalbė palaikymas -#### Palaikoma per GitHub Action (automatizuota ir visada atnaujinta) +#### Palaikoma per GitHub Action (automatiškai ir visada atnaujinta) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](./README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Norite klonuoti vietoje?** +> **Norite kopijuoti vietoje?** > -> Šis saugykla apima daugiau nei 50 kalbų vertimų, todėl žymiai padidina atsisiuntimo dydį. Norėdami klonuoti be vertimų, naudokite sparse checkout: +> Šiame saugykloje yra daugiau nei 50 kalbų vertimų, dėl ko reikšmingai padidėja atsisiuntimo dydis. Norėdami kopijuoti be vertimų, naudokite laipsniuotą atsisiuntimą: > > **Bash / macOS / Linux:** > ```bash @@ -29,21 +29,20 @@ Kursas kuriant AI programas su LangChain4j ir Azure OpenAI GPT-5.2, nuo paprasto > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Tai suteikia viską, ko reikia kursui, ir atsisiunčia daug greičiau. +> Tai suteiks viską, ko reikia kursui baigti, ir žymiai pagreitins atsisiuntimą. ## Turinys -1. [Greitas pradžia](00-quick-start/README.md) - Pradėkite su LangChain4j -2. [Įvadas](01-introduction/README.md) - Sužinokite LangChain4j pagrindus -3. [Užklausų kūrimas](02-prompt-engineering/README.md) - Įvaldę efektyvų užklausų kūrimą -4. [RAG (Paieškos papildymo generavimas)](03-rag/README.md) - Kurkite protingas žinių sistemas -5. [Įrankiai](04-tools/README.md) - Integruokite išorinius įrankius ir paprastus padėjėjus -6. [MCP (Modelio konteksto protokolas)](05-mcp/README.md) - Dirbkite su Modelio konteksto protokolu (MCP) ir agentinėmis moduliais +1. [Įvadas](01-introduction/README.md) - Sužinokite LangChain4j pagrindus +2. [Užklausų kūrimas](02-prompt-engineering/README.md) - Įsisavinkite efektyvaus užklausų dizaino meną +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Kurkite išmanias žinių sistemas +4. [Įrankiai](04-tools/README.md) - Integruokite išorinius įrankius ir paprastus asistentus +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Dirbkite su Modelio konteksto protokolu (MCP) ir agentiniais moduliais -### Vaizdo įrašų gidai +### Vaizdo įrašų vedliai -Kiekvienas modulis turi tiesioginę sesiją, kurioje žingsnis po žingsnio aptariame koncepcijas ir kodą. +Kiekvienas modulis turi tiesioginę sesiją, kurioje žingsnis po žingsnio nagrinėjame sąvokas ir kodą. | Modulis | Vaizdo įrašas | |--------|-------| @@ -56,95 +55,96 @@ Kiekvienas modulis turi tiesioginę sesiją, kurioje žingsnis po žingsnio apta ## Mokymosi kelias -**Naujas LangChain4j?** Peržiūrėkite [Žodynėlį](docs/GLOSSARY.md), kad sužinotumėte svarbiausias sąvokas ir terminus. +**Naujokas LangChain4j?** Pažiūrėkite [Žodynėlį](docs/GLOSSARY.md) su pagrindinių terminų ir sąvokų apibrėžimais. -> **Greita pradžia** +> **Greitas pradžia** -1. Padarykite šios saugyklos forkʼą į savo GitHub paskyrą -2. Spauskite **Code** → skirtuką **Codespaces** → **...** → **New with options...** +1. Padarykite forką šiam saugyklai savo GitHub paskyroje +2. Spustelėkite **Code** → skirtuką **Codespaces** → **...** → **New with options...** 3. Naudokite numatytuosius nustatymus – bus pasirinktas šiam kursui sukurtas kūrimo konteineris -4. Spauskite **Create codespace** +4. Spustelėkite **Create codespace** 5. Palaukite 5-10 minučių, kol aplinka bus paruošta -6. Tiesiogiai eikite į [Greitą pradžią](./00-quick-start/README.md) ir pradėkite! +6. Tiesiai pereikite į [Įvadą](./01-introduction/README.md) ir pradėkite! -Baigę modulius, išbandykite [Testavimo vadovą](docs/TESTING.md), kad pamatytumėte LangChain4j testavimo koncepcijas veikime. +Baigę modulius, išbandykite [Testavimo vadovą](docs/TESTING.md), kad pamatytumėte LangChain4j testavimo koncepcijas veiksmuose. -> **Pastaba:** Šis mokymas naudoja tiek GitHub modelius, tiek Azure OpenAI. [Greito pradžios](00-quick-start/README.md) modulis naudoja GitHub modelius (nereikia Azure prenumeratos), o moduliai 1-5 naudoja Azure OpenAI. Jei neturite, pradėkite su [nemokama Azure paskyra](https://aka.ms/azure-free-account). +> **Pastaba:** Šis mokymas naudoja Azure OpenAI. Pradėkite su [NEMOKAMA Azure paskyra](https://aka.ms/azure-free-account), jei jos dar neturite. ## Mokymasis su GitHub Copilot -Norėdami greitai pradėti programavimą, atidarykite šį projektą GitHub Codespace arba savo vietinėje IDE su pateiktu devcontainer. Šiame kurse naudojamas devcontainer yra iš anksto sukonfigūruotas su GitHub Copilot AI porinio programavimo palaikymu. +Norėdami greitai pradėti programuoti, atidarykite šį projektą GitHub Codespace arba savo vietiniame IDE su pateiktu devcontainer. Šiame kurse naudojamas devcontainer jau iš anksto sukonfigūruotas su GitHub Copilot AI kartu programavimui. -Kiekviename kodo pavyzdyje yra siūlomų klausimų, kuriuos galite užduoti GitHub Copilot norėdami gilinti savo supratimą. Ieškokite 💡/🤖 paskatų: +Kiekviename kodo pavyzdyje yra pateikti klausimai, kuriuos galite užduoti GitHub Copilot, kad gilintumėte supratimą. Ieškokite 💡/🤖 raginimų: -- **Java failų antraštėse** – klausimai, specifiniai kiekvienam pavyzdžiui -- **Modulių README** – tyrimo paskatos po kodo pavyzdžių +- **Java failų antraštėse** – klausimai, skirti kiekvienam pavyzdžiui +- **Modulių README** – tyrimo raginimai po kodo pavyzdžių -**Kaip naudoti:** atidarykite bet kurį kodo failą ir užduokite Copilot siūlomus klausimus. Jis turi visą kodo bazės kontekstą ir gali paaiškinti, išplėsti ar pasiūlyti alternatyvas. +**Kaip naudoti:** Atidarykite bet kurį kodo failą ir užduokite Copilot pateiktus klausimus. Jis pilnai supranta kodo bazę, gali paaiškinti, pratęsti ir pasiūlyti alternatyvas. -Norite sužinoti daugiau? Peržiūrėkite [Copilot AI poriniam programavimui](https://aka.ms/GitHubCopilotAI). +Norite sužinoti daugiau? Pažiūrėkite [Copilot AI kartu programavimui](https://aka.ms/GitHubCopilotAI). -## Papildomi resursai +## Papildomi ištekliai ### LangChain -[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j pradedantiesiems](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js pradedantiesiems](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain pradedantiesiems](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- ### Azure / Edge / MCP / Agentai -[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AZD pradedantiesiems](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI pradedantiesiems](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP pradedantiesiems](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI agentai pradedantiesiems](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Generatyvinė AI serija -[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Generatyvioji AI serija +[![Generatyvioji AI pradedantiesiems](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generatyvioji AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generatyvioji AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generatyvioji AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- ### Pagrindinis mokymasis -[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![ML pradedantiesiems](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Duomenų mokslas pradedantiesiems](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI pradedantiesiems](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Kibernetinis saugumas pradedantiesiems](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Žiniatinklio kūrimas pradedantiesiems](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT pradedantiesiems](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR kūrimas pradedantiesiems](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Copilot serija -[![Copilot dirbant kartu su AI programavime](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot nuotykiai](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Pagalbos gavimas -Jei įstringate arba turite klausimų apie AI programų kūrimą, prisijunkite prie: +Jei užstrigsite arba turėsite klausimų apie AI programėlių kūrimą, prisijunkite prie: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Jei turite produktų atsiliepimų ar klaidų kūrimo metu, apsilankykite: +Jei turite produktų atsiliepimų arba gaunate klaidų kūrimo metu, apsilankykite: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licencija -MIT licencija - žr. [LICENSE](../../LICENSE) failą platesnei informacijai. +MIT Licencija - žiūrėkite [LICENSE](../../LICENSE) failą detaliau. --- -**Atsakomybės apribojimas**: -Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors stengiamės užtikrinti tikslumą, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas gimtąja kalba turėtų būti laikomas autoritetingu šaltiniu. Kritinei informacijai rekomenduojama naudoti profesionalų žmogaus vertimą. Mes neatsakome už bet kokius nesusipratimus ar neteisingus aiškinimus, atsiradusius dėl šio vertimo naudojimo. +**Atsakomybės apribojimas**: +Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojama naudoti profesionalų žmogiškąjį vertimą. Mes neatsakome už jokius nesusipratimus ar neteisingą interpretaciją, kilusią naudojantis šiuo vertimu. \ No newline at end of file diff --git a/translations/lt/docs/GLOSSARY.md b/translations/lt/docs/GLOSSARY.md index 1a26eac8e..c85e0debf 100644 --- a/translations/lt/docs/GLOSSARY.md +++ b/translations/lt/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j žodynas +# LangChain4j Žodynas ## Turinys -- [Pagrindinės sąvokos](../../../docs) -- [LangChain4j komponentai](../../../docs) -- [AI/ML sąvokos](../../../docs) -- [Apsauginiai barjerai](../../../docs) -- [Užklausų kūrimas](../../../docs) -- [RAG (paieškomoji papildyta generacija)](../../../docs) -- [Agentai ir įrankiai](../../../docs) -- [Agentų modulis](../../../docs) -- [Modelio konteksto protokolas (MCP)](../../../docs) -- [Azure paslaugos](../../../docs) -- [Testavimas ir vystymas](../../../docs) +- [Pagrindinės sąvokos](#pagrindinės-sąvokos) +- [LangChain4j komponentai](#langchain4j-komponentai) +- [AI/ML sąvokos](#aiml-sąvokos) +- [Saugumo priemonės](#saugumo-priemonės) +- [Užklausų kūrimas](#prompt-engineering---module-02) +- [RAG (paieškos praturtinta generacija)](#rag-retrieval-augmented-generation---module-03) +- [Agentai ir įrankiai](#agents-and-tools---module-04) +- [Agentinis modulis](#agentic-module---module-05) +- [Modelio konteksto protokolas (MCP)](#model-context-protocol-mcp---module-05) +- [Azure paslaugos](#azure-services---module-01) +- [Testavimas ir vystymas](#testing-and-development---testing-guide) -Greita terminų ir sąvokų, naudojamų visame kurse, nuoroda. +Greitos nuorodos terminams ir sąvokoms, naudojamoms viso kurso metu. ## Pagrindinės sąvokos -**AI agentas** – Sistema, kuri naudoja AI savarankiškiems sprendimams ir veiksmams atlikti. [Modulis 04](../04-tools/README.md) +**AI agentas** – sistema, kuri naudoja dirbtinį intelektą savarankiškai mąstyti ir veikti. [Modulis 04](../04-tools/README.md) -**Grandinė** – Operacijų seka, kurioje kiekvieno žingsnio išvestis perduodama kitam. +**Grandinė** – operacijų seka, kurioje kiekvieno žingsnio išvestis patenka į kitą žingsnį. -**Dalijimas** – Dokumentų skaidymas į mažesnes dalis. Įprasta: 300–500 žodžių su persidengimu. [Modulis 03](../03-rag/README.md) +**Dokumentų skaidymas** – dokumentų padalijimas į mažesnes dalis. Tipiškai: 300–500 žodžių su persidengimu. [Modulis 03](../03-rag/README.md) -**Konteksto langas** – Maksimalus modelio apdorojamų žodžių skaičius. GPT-5.2: 400 tūkst. žodžių (iki 272 tūkst. įvesties, 128 tūkst. išvesties). +**Konteksto langas** – maksimalus modelio apdorojamų žodžių skaičius. GPT-5.2: 400K žodžių (iki 272K įvesties, 128K išvesties). -**Įterpiniai (Embeddingai)** – Skaitmeniniai vektoriai, atspindintys teksto reikšmę. [Modulis 03](../03-rag/README.md) +**Įterpimai** – skaitmeniniai vektoriai, atspindintys teksto prasmę. [Modulis 03](../03-rag/README.md) -**Funkcijų kvietimas** – Modelis generuoja struktūruotas užklausas išoriniams funkcijų kvietimams atlikti. [Modulis 04](../04-tools/README.md) +**Funkcijų iškvietimas** – modelis generuoja struktūruotus prašymus iškviesti išorines funkcijas. [Modulis 04](../04-tools/README.md) -**Halucinacija** – Kai modeliai generuoja klaidingą, bet įtikinamą informaciją. +**Halucinacija** – kai modeliai generuoja neteisingą, bet įtikinamą informaciją. -**Užklausa (Promptas)** – Tekstinis įvesties duomenų į kalbos modelį formatas. [Modulis 02](../02-prompt-engineering/README.md) +**Užklausa** – teksto įvestis kalbos modeliui. [Modulis 02](../02-prompt-engineering/README.md) -**Semantinė paieška** – Paieška pagal reikšmę naudojant įterpinius, ne raktinius žodžius. [Modulis 03](../03-rag/README.md) +**Semantinė paieška** – paieška pagal reikšmę naudojant įterpimus, o ne raktinius žodžius. [Modulis 03](../03-rag/README.md) -**Būsena su atsiminimu ir be jo** – Be atsiminimo: be atminties. Su atsiminimu: išlaiko pokalbio istoriją. [Modulis 01](../01-introduction/README.md) +**Būsenoje laikomi prieš tai buvę duomenys (Stateful) prieš neprisimenančius (Stateless)** – Statelesni modeliai neturi atminties, stateful palaiko pokalbio istoriją. [Modulis 01](../01-introduction/README.md) -**Žodžiai (Tokens)** – Pagrindiniai teksto vienetai, kuriuos apdoroja modeliai. Įtakoja sąnaudas ir ribas. [Modulis 01](../01-introduction/README.md) +**Tokenai** – bazinės teksto vienetai, su kuriais modeliai dirba. Veikia kainas ir ribas. [Modulis 01](../01-introduction/README.md) -**Įrankių grandinimas** – Įrankių seka, kurioje išvestis naudojama kitam kvietimui. [Modulis 04](../04-tools/README.md) +**Įrankių grandinimas** – įrankių nuoseklus vykdymas, kur vieno išvestis informuoja kitą kvietimą. [Modulis 04](../04-tools/README.md) ## LangChain4j komponentai -**AiServices** – Kuria tipo saugius AI paslaugų sąsajas. +**AiServices** – kuria tipui saugias AI paslaugų sąsajas. -**OpenAiOfficialChatModel** – Vieningas klientas OpenAI ir Azure OpenAI modeliams. +**OpenAiOfficialChatModel** – vieningas klientas OpenAI ir Azure OpenAI modeliams. -**OpenAiOfficialEmbeddingModel** – Kuria įterpinius naudojant OpenAI oficialų klientą (palaiko tiek OpenAI, tiek Azure OpenAI). +**OpenAiOfficialEmbeddingModel** – kuria įterpimus naudodamas OpenAI oficialų klientą (palaiko tiek OpenAI, tiek Azure OpenAI). -**ChatModel** – Pagrindinė kalbos modelių sąsaja. +**ChatModel** – pagrindinė kalbos modelių sąsaja. -**ChatMemory** – Išlaiko pokalbio istoriją. +**ChatMemory** – palaiko pokalbio istoriją. -**ContentRetriever** – Suranda aktualias dokumentų dalis RAG procesui. +**ContentRetriever** – randa aktualius dokumentų gabalus RAG. -**DocumentSplitter** – Skaido dokumentus į dalis. +**DocumentSplitter** – padalija dokumentus į gabalus. -**EmbeddingModel** – Paverčia tekstą skaitmeniniais vektoriais. +**EmbeddingModel** – paverčia tekstą skaitmeniniais vektoriais. -**EmbeddingStore** – Saugo ir paima įterpinius. +**EmbeddingStore** – saugo ir gauna įterpimus. -**MessageWindowChatMemory** – Išlaiko naujausių pranešimų slenkamąjį langą. +**MessageWindowChatMemory** – palaiko ritinį iš naujausių žinučių. -**PromptTemplate** – Kuria pakartotinai naudojamas užklausas su `{{variable}}` vietos žymomis. +**PromptTemplate** – kuria pakartotinai naudojamas užklausas su `{{variable}}` vietų žymėmis. -**TextSegment** – Teksto dalis su metaduomenimis. Naudojama RAG. +**TextSegment** – teksto gabalas su metaduomenimis. Naudojamas RAG. -**ToolExecutionRequest** – Atspindi įrankio vykdymo užklausą. +**ToolExecutionRequest** – atvaizduoja įrankio vykdymo užklausą. -**UserMessage / AiMessage / SystemMessage** – Pokalbio pranešimų tipai. +**UserMessage / AiMessage / SystemMessage** – pokalbio žinučių tipai. ## AI/ML sąvokos -**Few-Shot mokymasis** – Pateikiami pavyzdžiai užklausose. [Modulis 02](../02-prompt-engineering/README.md) +**Few-Shot mokymas** – pateikiami pavyzdžiai užklausose. [Modulis 02](../02-prompt-engineering/README.md) -**Didelis kalbos modelis (LLM)** – AI modeliai, apmokyti pagal milžiniškus tekstų kiekius. +**Didelis kalbos modelis (LLM)** – DI modeliai, apmokyti dideliuose teksto duomenyse. -**Mąstymo pastangos** – GPT-5.2 parametras, valdantis mąstymo gylį. [Modulis 02](../02-prompt-engineering/README.md) +**Mąstymo intensyvumas** – GPT-5.2 parametras, reguliuojantis mąstymo gylį. [Modulis 02](../02-prompt-engineering/README.md) -**Temperatūra** – Valdo išvesties atsitiktinumą. Žema – deterministinė, aukšta – kūrybiška. +**Temperatūra** – reguliuoja išvesties atsitiktinumą. Žema = deterministinė, aukšta = kūrybiška. -**Vektorinė duomenų bazė** – Specializuota duomenų bazė įterpiniams. [Modulis 03](../03-rag/README.md) +**Vektorinė duomenų bazė** – specializuota duomenų bazė įterpimams. [Modulis 03](../03-rag/README.md) -**Zero-Shot mokymasis** – Užuot naudojant pavyzdžius, atliekant užduotis be jų. [Modulis 02](../02-prompt-engineering/README.md) +**Zero-Shot mokymas** – užduočių vykdymas be pavyzdžių. [Modulis 02](../02-prompt-engineering/README.md) -## Apsauginiai barjerai - [Modulis 00](../00-quick-start/README.md) +## Saugumo priemonės -**Gylio gynyba** – Daugiasluoksnė saugumo sistema, jungiant programos lygmens barjerus su paslaugų filtrais. +**Gynyba keliuose sluoksniuose** – daugiasluoksnė saugumo strategija, apjungianti programos lygio apsaugas su teikėjo saugumo filtrais. -**Stiprus blokavimas** – Paslaugos teikėjas meta HTTP 400 klaidą už griežtus turinio pažeidimus. +**Griežtas blokavimas** – teikėjas grąžina HTTP 400 klaidą už itin sunkius turinio pažeidimus. -**InputGuardrail** – LangChain4j sąsaja vartotojo įvesties patikrinimui prieš patekiant į LLM. Labai taupo išlaidas ir laiką, anksti blokuodama kenksmingas užklausas. +**InputGuardrail** – LangChain4j sąsaja vartotojo įvesties validavimui prieš perduodant LLM. Taupo kaštus ir vėlavimus anksčiau blokuojant kenksmingas užklausas. -**InputGuardrailResult** – Vartotojo įvesties saugumo grįžtamoji reikšmė: `success()` arba `fatal("priežastis")`. +**InputGuardrailResult** – saugumo validacijos rezultato tipas: `success()` arba `fatal("priežastis")`. -**OutputGuardrail** – Sąsaja AI atsakymų peržiūrai prieš pateikiant vartotojui. +**OutputGuardrail** – sąsaja AI atsakymų validavimui prieš grąžinant vartotojui. -**Paslaugų teikėjo saugumo filtrai** – AI paslaugų įmontuoti turinio filtrai (pvz., GitHub modeliai), susekiantys pažeidimus API lygyje. +**Teikėjo saugumo filtrai** – AI teikėjų (pvz., Azure OpenAI) įmontuoti turinio filtrai, kurie fiksuoja pažeidimus API lygyje. -**Minkštas atsisakymas** – Modelis mandagiai atsisako atsakyti, nekeldamas klaidos. +**Minkštas atsisakymas** – modelis mandagiai atsisako atsakyti, negrąžindamas klaidos. ## Užklausų kūrimas - [Modulis 02](../02-prompt-engineering/README.md) -**Grandininis mąstymas** – Žingsnis po žingsnio argumentavimas geresniam tikslumui. +**Minties grandinė (Chain-of-Thought)** – žingsnis po žingsnio mąstymas dėl geresnio tikslumo. -**Ribotas išvesties formatas** – Reikalavimo laikytis konkretaus formato ar struktūros. +**Apribota išvestis** – įvedamos specifinės formatavimo taisyklės ar struktūra. -**Didelis gatavumas** – GPT-5.2 šablonas išsamiai analizei. +**Didelis noras veikti** – GPT-5.2 modelio šablonas išsamiai analizei. -**Mažas gatavumas** – GPT-5.2 greitiems atsakymams. +**Mažas noras veikti** – GPT-5.2 šablonas greitiems atsakymams. -**Daugiapakopis pokalbis** – Konteksto palaikymas per kelias žinutes. +**Daugiarūšis pokalbis** – konteksto išlaikymas per keitimus. -**Vaidmens užklausų kūrimas** – Modelio personažo nustatymas per sistemos pranešimus. +**Vaidmens pagrindu užklausos** – modelio asmenybės nustatymas per sistemos žinutes. -**Savioverta** – Modelis vertina ir tobulina savo išvestį. +**Savarankiškas atspindys** – modelis vertina ir gerina savo išvestį. -**Struktūruota analizė** – Fiksuota vertinimo sistema. +**Struktūruota analizė** – fiksuotas vertinimo rėmėjas. -**Užduočių vykdymo modelis** – Planavimas → Vykdymas → Apibendrinimas. +**Užduočių vykdymo modelis** – planuoti → vykdyti → apibendrinti. -## RAG (paieškomoji papildyta generacija) - [Modulis 03](../03-rag/README.md) +## RAG (paieškos praturtinta generacija) - [Modulis 03](../03-rag/README.md) -**Dokumentų apdorojimo kanalas** – Įkėlimas → skaidymas → įterpimas → saugojimas. +**Dokumentų apdorojimo grandinė** – įkelti → padalyti → įterpti → saugoti. -**Atminties įterpinių saugykla** – Neišlaikoma atminties saugykla testavimui. +**Laikinas įterpimų saugyklos atmintyje variantas** – nepermanentiška saugykla testavimui. -**RAG** – Derina paiešką su generavimu, siekiant pagrįsti atsakymus. +**RAG** – kombinuoja paiešką su generavimu, pagrindžia atsakymus. -**Panašumo įvertinimas** – Matavimo skalė (0-1) semantiniam panašumui. +**Panašumo įvertis** – semantinio panašumo matas (0–1). -**Šaltinio nuoroda** – Paieškos turinio metaduomenys. +**Šaltinio nuoroda** – metaduomenys apie rastą turinį. ## Agentai ir įrankiai - [Modulis 04](../04-tools/README.md) -**@Tool anotacija** – Žymi Java metodus kaip AI kviečiamus įrankius. +**@Tool anotacija** – pažymi Java metodus kaip DI kviečiamus įrankius. -**ReAct modelis** – Mąstyti → veikti → stebėti → kartoti. +**ReAct modelis** – mąstyk → veik → stebėk → kartok. -**Seansų valdymas** – Atskiri kontekstai skirtingiems vartotojams. +**Sesijų valdymas** – atskiri kontekstai skirtingiems vartotojams. -**Įrankis** – Funkcija, kurią gali kviesti AI agentas. +**Įrankis** – funkcija, kurią gali kviesti DI agentas. -**Įrankio aprašymas** – Dokumentacija apie paskirtį ir parametrus. +**Įrankio aprašymas** – dokumentacija apie įrankio paskirtį ir parametrus. -## Agentų modulis - [Modulis 05](../05-mcp/README.md) +## Agentinis modulis - [Modulis 05](../05-mcp/README.md) -**@Agent anotacija** – Žymi sąsajas kaip AI agentus su deklaratyviu elgesio aprašymu. +**@Agent anotacija** – pažymi sąsajas kaip DI agentus su deklaratyviu elgesio aprašymu. -**Agentų klausytojas** – Priemonė stebėti agento vykdymą per `beforeAgentInvocation()` ir `afterAgentInvocation()`. +**Agentų klausytojas** – kabliukas stebėti agentų vykdymą per `beforeAgentInvocation()` ir `afterAgentInvocation()`. -**Agentinis kontekstas** – Bendroji atmintis, kur agentai saugo rezultatus naudodami `outputKey` tolimesniems agentams. +**Agentinis kontekstas** – bendra atmintis, kurioje agentai saugo rezultatus naudodami `outputKey`, kad kiti agentai galėtų juos panaudoti. -**AgenticServices** – Fabrikas agentams kurti naudojant `agentBuilder()` ir `supervisorBuilder()`. +**AgenticServices** – fabrikas agentams kurti naudojant `agentBuilder()` ir `supervisorBuilder()`. -**Sąlyginis darbo eigos valdymas** – Nukreipia pagal sąlygas skirtingiems specialistams. +**Sąlyginis darbo srautas** – maršrutas pagal sąlygas į skirtingus specialistų agentus. -**Žmogaus dalyvavimas** – Darbo modelis su žmonių patvirtinimu ar turinio peržiūra. +**Žmogiškasis įsiterpimas (Human-in-the-Loop)** – darbo srauto modelis, pridedantis žmonių patvirtinimo ar turinio peržiūros etapus. -**langchain4j-agentic** – Maven priklausomybė deklaratyviems agentams kurti (eksperimentinė). +**langchain4j-agentic** – Maven priklausomybė deklaratyviam agentų kūrimui (eksperimentinis). -**Ciklinis darbo eigos valdymas** – Kartojamas agentų vykdymas, kol įvykdoma sąlyga (pvz., kokybės įvertis ≥ 0.8). +**Ciklinis darbo srautas** – kartoti agento vykdymą, kol bus pasiektas sąlygos kriterijus (pvz., kokybės įvertis ≥ 0.8). -**outputKey** – Agentų anotacijos parametras, nurodantis, kur rezultatai saugomi agentiniame kontekste. +**outputKey** – agento anotacijos parametras, nurodantis, kur Agentiniame kontekste saugomi rezultatai. -**Paralelinis darbo eigos valdymas** – Kelis agentus vykdyti lygiagrečiai nepriklausomoms užduotims. +**Lygiagretus darbo srautas** – vienu metu vykdyti kelis agentus nepriklausomoms užduotims. -**Atsakymo strategija** – Kaip prižiūrėtojas formuluoja galutinį atsakymą: PASKUTINIS, SANTRAUKA ar ĮVERTINTAS. +**Atsako strategija** – kaip prižiūrėtojas formuluoja galutinį atsakymą: PASKUTINIS, SANTRAUKA arba ĮVERTINTAS. -**Sekveninis darbo eigos valdymas** – Vykdyti agentus iš eilės, išvestis perduodama kitam etapui. +**Nuoseklus darbo srautas** – vykdyti agentus iš eilės taip, kad vieno išvestis patenka į kitą žingsnį. -**Prižiūrėtojo agento modelis** – Pažangus agentinis modelis, kuriame prižiūrėtojas LLM dinamiškai nusprendžia, kuriuos subagentus kviesti. +**Prižiūrėtojo agento modelis** – pažangus agentinis modelis, kai prižiūrintysis LLM dinamiškai nusprendžia, kuriuos subagentus kviesti. ## Modelio konteksto protokolas (MCP) - [Modulis 05](../05-mcp/README.md) **langchain4j-mcp** – Maven priklausomybė MCP integracijai LangChain4j. -**MCP** – Modelio konteksto protokolas: standartas AI programoms susijungti su išoriniais įrankiais. Sukurk kartą, naudok visur. +**MCP** – Modelio konteksto protokolas: standartas, jungiantis DI programas su išoriniais įrankiais. Sukurk vieną kartą, naudok visur. -**MCP klientas** – Programa, jungiasi prie MCP serverių, ieško ir naudoja įrankius. +**MCP klientas** – programa, jungiantis prie MCP serverių ieškoti ir naudoti įrankius. -**MCP serveris** – Paslauga, viešoji įrankių per MCP su aiškiais aprašymais ir parametrų schemomis. +**MCP serveris** – paslauga, atverianti įrankius per MCP su aiškiais aprašymais ir parametrų schemomis. -**McpToolProvider** – LangChain4j komponentas, apgaubiantis MCP įrankius AI paslaugoms ir agentams. +**McpToolProvider** – LangChain4j komponentas, kuris apgaubia MCP įrankius, kad jie būtų panaudojami DI paslaugose ir agentuose. -**McpTransport** – Sąsaja MCP komunikacijai. Įgyvendinimai: Stdio ir HTTP. +**McpTransport** – sąsaja MCP komunikacijai. Implementacijos: Stdio ir HTTP. -**Stdio transportas** – Vietinis procesas per stdin/stdout. Naudinga failų sistema ar komandų eilutės įrankiams. +**Stdio transportas** – vietinis proceso transportas per stdin/stdout. Naudinga prieigai prie failų ar komandų eilutės įrankių. -**StdioMcpTransport** – LangChain4j įgyvendinimas, paleidžiantis MCP serverį kaip antrinį procesą. +**StdioMcpTransport** – LangChain4j įgyvendinimas, kuris paleidžia MCP serverį kaip pagalbinį procesą. -**Įrankių paieška** – Klientas užklausia serverį apie galimus įrankius su aprašymais ir schemomis. +**Įrankių atradimas** – klientas užklausia serverį apie turimus įrankius su aprašymais ir schemomis. ## Azure paslaugos - [Modulis 01](../01-introduction/README.md) -**Azure AI Search** – Debesų paieška su vektorinėmis galimybėmis. [Modulis 03](../03-rag/README.md) +**Azure AI Search** – debesų paieška su vektorinėmis galimybėmis. [Modulis 03](../03-rag/README.md) **Azure Developer CLI (azd)** – Azure išteklių diegimas. -**Azure OpenAI** – Microsoft įmonių lygmens AI paslauga. +**Azure OpenAI** – Microsoft įmonių DI paslauga. -**Bicep** – Azure infrastruktūros kaip kodo kalba. [Infrastruktūros gidas](../01-introduction/infra/README.md) +**Bicep** – Azure infrastruktūros kaip kodo kalba. [Infrastruktūros vadovas](../01-introduction/infra/README.md) -**Diegimo pavadinimas** – Modelio diegimo pavadinimas Azure. +**Diegimo pavadinimas** – modelio diegimo Azure pavadinimas. -**GPT-5.2** – Naujausias OpenAI modelis su mąstymo kontrolės funkcija. [Modulis 02](../02-prompt-engineering/README.md) +**GPT-5.2** – naujausias OpenAI modelis su mąstymo valdymu. [Modulis 02](../02-prompt-engineering/README.md) -## Testavimas ir vystymas - [Testavimo gidas](TESTING.md) +## Testavimas ir vystymas - [Testavimo vadovas](TESTING.md) -**Dev Container** – Kapsuliuota vystymo aplinka. [Konfigūracija](../../../.devcontainer/devcontainer.json) +**Dev Container** – containerizuota vystymo aplinka. [Konfigūracija](../../../.devcontainer/devcontainer.json) -**GitHub modeliai** – Nemokama AI modelių žaidimų aikštelė. [Modulis 00](../00-quick-start/README.md) +**Testavimas atmintyje** – testavimas naudojant laikiną atmintinę. -**Atminties testavimas** – Testavimas naudojant atminties saugyklą. +**Integracijos testavimas** – testavimas su realia infrastruktūra. -**Integracinis testavimas** – Testavimas su realia infrastruktūra. +**Maven** – Java automatizuoto išrinkimo įrankis. -**Maven** – Java kūrimo automatizavimo įrankis. +**Mockito** – Java imitavimo karkasas. -**Mockito** – Java imitavimo (mock) biblioteka. - -**Spring Boot** – Java programų karkasas. [Modulis 01](../01-introduction/README.md) +**Spring Boot** – Java taikomųjų programų karkasas. [Modulis 01](../01-introduction/README.md) --- **Atsakomybės apribojimas**: -Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors stengiamės užtikrinti tikslumą, atkreipkite dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas natūralia kalba turėtų būti laikomas pagrindiniu šaltiniu. Svarbiai informacijai rekomenduojamas profesionalus žmogiškasis vertimas. Mes neatsakome už bet kokius nesusipratimus ar neteisingus aiškinimus, kilusius naudojant šį vertimą. +Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojama naudoti profesionalų žmogiškąjį vertimą. Mes neatsakome už jokius nesusipratimus ar neteisingą interpretaciją, kilusią naudojantis šiuo vertimu. \ No newline at end of file diff --git a/translations/lt/docs/TESTING.md b/translations/lt/docs/TESTING.md index 38eb88318..a660fd34a 100644 --- a/translations/lt/docs/TESTING.md +++ b/translations/lt/docs/TESTING.md @@ -2,19 +2,19 @@ ## Turinys -- [Greitas pradėjimas](../../../docs) -- [Ką apima testai](../../../docs) -- [Testų vykdymas](../../../docs) -- [Testų vykdymas VS Code](../../../docs) -- [Testavimo modeliai](../../../docs) -- [Testavimo filosofija](../../../docs) -- [Kiti žingsniai](../../../docs) +- [Greitas pradžia](#greitas-pradžia) +- [Ką apima testai](#ką-apima-testai) +- [Testų vykdymas](#testų-vykdymas) +- [Testų vykdymas VS Code](#testų-vykdymas-vs-code) +- [Testavimo šablonai](#testavimo-šablonai) +- [Testavimo filosofija](#testavimo-filosofija) +- [Tolimesni žingsniai](#tolimesni-žingsniai) -Ši gidas jus supažindina su testais, kurie parodo, kaip testuoti DI programas nereikalaujant API raktų ar išorinių paslaugų. +Šis vadovas paaiškina, kaip atlikti testus, parodančius, kaip testuoti DI programas be API raktų ar išorinių paslaugų. -## Greitas pradėjimas +## Greitas pradžia -Paleiskite visus testus su vienu komandos įvedimu: +Paleiskite visus testus vienu komandos įrašu: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Kai visi testai sėkmingai praeina, turėtumėte matyti panašų rezultatą kaip žemiau esančioje ekrano nuotraukoje — testai vykdomi be klaidų. +Kai visi testai praeina, turėtumėte matyti rezultatą, kaip žemiau esančioje ekrano nuotraukoje — testai veikia be klaidų. Successful Test Results -*Sėkmingas testų vykdymas, rodantis, kad visi testai praeina be klaidų* +*Sėkmingo testo vykdymo rezultatai, rodantys, kad visi testai praeina be klaidų* ## Ką apima testai -Šis kursas orientuotas į **vienetinius testus**, kurie vykdomi lokaliai. Kiekvienas testas demonstruoja konkretų LangChain4j konceptą izoliacijoje. Toliau pateikta testavimo piramidė rodo, kur tinka vienetiniai testai — jie sudaro greitą, patikimą pagrindą, ant kurio statoma visa kita testavimo strategija. +Šis kursas orientuotas į **vienetinius testus**, vykdomus lokaliai. Kiekvienas testas demonstruoja konkretų LangChain4j konceptą izoliuotai. žemiau pateikta testavimo piramidė rodo, kur tilpa vienetiniai testai — jie yra greitas ir patikimas pagrindas, ant kurio statoma visa jūsų testavimo strategija. Testing Pyramid -*Testavimo piramidė rodanti balansą tarp vienetinių testų (greiti, izoliuoti), integracinių testų (tikri komponentai) ir pilno veikimo testų. Ši apmokyma apima vienetinius testus.* +*Testavimo piramidė rodanti balansą tarp vienetinių testų (greiti, izoliuoti), integracinių testų (tikros sudedamosios dalys) ir galutinio patikrinimo testų. Ši mokymo programa apima vienetinius testus.* -| Modulis | Testai | Fokusas | Svarbūs failai | +| Modulis | Testai | Fokusas | Pagrindiniai failai | |--------|-------|-------|-----------| -| **00 - Greitas pradėjimas** | 6 | Pavyzdžių šablonai ir kintamųjų pakeitimas | `SimpleQuickStartTest.java` | -| **01 - Įvadas** | 8 | Pokalbių atmintis ir būsenoje saugomi chat'ai | `SimpleConversationTest.java` | -| **02 - Pavyzdžių inžinerija** | 12 | GPT-5.2 modelių pavyzdžiai, entuziazmo lygiai, struktūruotas išvestis | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Dokumentų įvedimas, įterpimai, panašumo paieška | `DocumentServiceTest.java` | -| **04 - Įrankiai** | 12 | Funkcijų iškvietimas ir įrankių jungimas | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Modelio konteksto protokolas naudojant stdio | `SimpleMcpTest.java` | +| **01 - Įvadas** | 8 | Pokalbio atmintis ir būseninis pokalbis | `SimpleConversationTest.java` | +| **02 - Užklausų inžinerija** | 12 | GPT-5.2 šablonai, norų lygiai, struktūruotas išvestis | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Dokumentų gavimas, įterpimo vektoriai, panašumo paieška | `DocumentServiceTest.java` | +| **04 - Įrankiai** | 12 | Funkcijų kvietimas ir įrankių grandinavimas | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Modelio konteksto protokolas su stdio transportu | `SimpleMcpTest.java` | ## Testų vykdymas -**Paleisti visus testus iš pagrindinio katalogo:** +**Paleiskite visus testus iš root:** **Bash:** ```bash @@ -63,23 +62,23 @@ mvn test mvn --% test ``` -**Paleisti testus konkrečiam moduliui:** +**Paleiskite testus konkrečiam moduliui:** **Bash:** ```bash cd 01-introduction && mvn test -# Arba iš root +# Arba iš šaknies mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Arba iš šaknies +# Arba iš root mvn --% test -pl 01-introduction ``` -**Paleisti vieną testų klasę:** +**Paleiskite vieną testų klasę:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Paleisti konkretų testų metodą:** +**Paleiskite konkretų testų metodą:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#turėtųIšlaikytiPokALBIOIstoriją +mvn test -Dtest=SimpleConversationTest#ar reikia išlaikyti pokalbio istoriją ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#turėtųIšlaikytiPokalbioIstoriją +mvn --% test -Dtest=SimpleConversationTest#turėtųIšlaikytiPokalbiaiIstoriją ``` ## Testų vykdymas VS Code -Jei naudojate Visual Studio Code, Test Explorer suteikia grafinę sąsają testų vykdymui ir derinimui. +Jei naudojate Visual Studio Code, Testų naršyklė suteikia grafinę sąsają testams vykdyti ir derinti. VS Code Test Explorer -*VS Code testų naršyklė rodanti testų medį su visomis Java testų klasėmis ir atskirais testų metodais* +*VS Code Testų naršyklė rodanti testų medį su visomis Java testų klasėmis ir atskirais testų metodais* -**Norėdami paleisti testus VS Code:** +**Kaip vykdyti testus VS Code:** -1. Atidarykite Test Explorer paspausdami mėgintuvėlio ikoną Veiklos juostoje -2. Išskleiskite testų medį, kad pamatytumėte visus modulius ir testų klases -3. Spustelėkite paleidimo mygtuką prie bet kurio testo, kad paleistumėte jį atskirai -4. Spustelėkite "Run All Tests", kad paleistumėte visą testų rinkinį -5. Dešiniuoju pelės mygtuku spustelėkite bet kurį testą ir pasirinkite "Debug Test", kad nustatytumėte pertraukos taškus ir žingsniuotumėte per kodą +1. Atidarykite Testų naršyklę spustelėdami mėgintuvėlio piktogramą veiksmų juostoje +2. Išplėskite testų medį, kad matytumėte visus modulius ir testų klases +3. Spustelėkite paleidimo mygtuką šalia bet kurio testo, kad paleistumėte jį atskirai +4. Spustelėkite "Run All Tests", kad įvykdytumėte visą testų rinkinį +5. Dešiniuoju pelės mygtuku spustelėkite bet kurį testą ir pasirinkite "Debug Test", kad nustatytumėte pertraukos taškus ir žingsniuotumėte po kodą -Testų naršyklė rodo žalius varnele pažymėtus sėkmingus testus ir pateikia išsamius klaidų pranešimus, kai testai nepraeina. +Testų naršyklė rodo žalius varnelės ženklus sėkmingiems testams ir pateikia išsamius klaidų pranešimus, kai testai nepavyksta. -## Testavimo modeliai +## Testavimo šablonai -### Modelis 1: Pavyzdžių šablonų testavimas +### Šablonas 1: Užklausų šablonų testavimas -Paprastas modelis testuoja pavyzdžių šablonus neiškviečiant jokio DI modelio. Patikrinama, ar kintamųjų pakeitimas veikia teisingai ir ar pavyzdžiai suformuoti kaip tikimasi. +Paprastas šis šablonas testuoja užklausų šablonus be jokių DI modelio kvietimų. Patikrinama, ar kintamųjų pakeitimas veikia teisingai ir užklausos yra suformatuotos taip, kaip tikėtasi. Prompt Template Testing -*Pavyzdžių šablonų testavimas rodantis kintamųjų pakeitimo kelią: šablonas su vietos žymekliais → pritaikomi reikšmės → patvirtinama suformatuota išvestis* +*Užklausų šablonų testavimas rodant kintamųjų pakeitimo eigą: šablonas su vietomis → taikomos reikšmės → patvirtintas suformatuotas rezultatas* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Šis testas yra faile `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Paleiskite jį:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testuotiUžklausoŠablonoFormatavimą -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testuotiKlausimoŠablonoFormatavimą -``` +Šis šablonas patvirtina, kad kintamųjų pakeitimas veikia teisingai ir užklausos formatavimas yra tinkamas — nereikia API rakto ar modelio kvietimo. -### Modelis 2: Kalbos modelių maketavimas +### Šablonas 2: Kalbos modelių maketavimas -Testuojant pokalbių logiką, naudokite Mockito, kad sukurtumėte netikrus modelius, kurie grąžina iš anksto nustatytus atsakymus. Tai daro testus greitus, nemokamus ir deterministinius. +Testuojant pokalbio logiką, naudokite Mockito, kad sukurtumėte fiktyvius modelius, grąžinančius iš anksto nustatytus atsakymus. Tai daro testus greitus, nemokamus ir determinuotus. Mock vs Real API Comparison -*Palyginimas rodantis, kodėl maketai yra pageidautini testavimui: jie yra greiti, nemokami, deterministiniai ir nereikalauja API raktų* +*Palyginimas, kodėl maketavimai yra pageidaujami testuose: jie greiti, nemokami, determinuoti ir nereikalauja API raktų* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 vartotojo + 3 DI žinutės + assertThat(history).hasSize(6); // 3 naudotojo + 3 DI žinutės } } ``` -Šis modelis panaudotas faile `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Maketas užtikrina nuoseklią elgseną, todėl galima patikrinti teisingą atminties valdymą. +Šis šablonas yra faile `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Maketas užtikrina nuoseklų elgesį, todėl galite patikrinti, ar atminties valdymas veikia tinkamai. -### Modelis 3: Pokalbių izoliacijos testavimas +### Šablonas 3: Pokalbio izoliacijos testavimas -Pokalbių atmintis turi išlaikyti atskirus daugelio vartotojų kontekstus. Šis testas patikrina, ar pokalbiai nesimaišo. +Pokalbio atmintis turi atskirti kelis vartotojus. Šis testas patikrina, kad pokalbiai nesimaišo kontekstu. Conversation Isolation -*Pokalbių izoliacijos testavimas rodo atskirus atminties saugyklas skirtingiems vartotojams, kad būtų užkirstas kelias kontekstui maišytis* +*Pokalbio izoliacijos testavimas, rodantis atskirus atminties saugyklas skirtingiems vartotojams, kad būtų išvengta konteksto maišymo* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Kiekvienas pokalbis palaiko savo nepriklausomą istoriją. Gamybinėse sistemose ši izoliacija yra kritiškai svarbi daugiafunkcinei naudotojų aplikacijai. +Kiekvienas pokalbis palaiko savarankišką istoriją. Gamybos sistemose ši izoliacija yra būtina daugiafunkcėms programoms. -### Modelis 4: Įrankių testavimas atskirai +### Šablonas 4: Įrankių testavimas atskirai -Įrankiai yra funkcijos, kurias DI gali iškviesti. Testuokite juos tiesiogiai, kad įsitikintumėte, jog jie veikia teisingai nepriklausomai nuo DI sprendimų. +Įrankiai yra funkcijos, kurias DI gali kviesti. Testuokite jas tiesiogiai, kad įsitikintumėte, jog jos veikia teisingai nepriklausomai nuo DI sprendimų. Tools Testing -*Įrankių testavimas atskirai, rodantis maketuojamą įrankio vykdymą be DI kvietimų, patvirtina verslo logiką* +*Įrankių testavimas atskirai, rodantis maketuojamo įrankio vykdymą be DI kvietimų, kad patvirtintų verslo logiką* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Šie testai iš `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` tikrina įrankių logiką be DI įtraukimo. Grandinėlės pavyzdys rodo, kaip vieno įrankio išvestis įeina į kito įrankio įvestį. +Šie testai iš `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` patikrina įrankių logiką be DI dalyvavimo. Grandinavimo pavyzdys rodo, kaip vieno įrankio išvestis patenka kaip įvestis kitam. -### Modelis 5: RAG testavimas atmintyje +### Šablonas 5: Atminties viduje RAG testavimas -RAG sistemos tradiciškai reikalauja vektorių duomenų bazių ir įterpimų paslaugų. Modelis „atmintyje“ leidžia testuoti visą srautą be išorinių priklausomybių. +RAG sistemos tradiciškai reikalauja vektorių duomenų bazių ir įterpimo paslaugų. Šis atminties viduje šablonas leidžia testuoti visą procesą be išorinių priklausomybių. In-Memory RAG Testing -*RAG testavimo „atmintyje“ srautas, rodantis dokumentų analizę, įterpimų saugojimą ir panašumo paiešką be duomenų bazės* +*Atminties viduje vykdomas RAG testavimas, rodantis dokumentų analizę, įterpimo saugojimą ir panašumo paiešką be duomenų bazės* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Šis testas faile `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` sukuria dokumentą atmintyje ir patikrina jo dalijimąsi bei metaduomenų valdymą. +Šis testas iš `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` sukuria dokumentą atmintyje ir patikrina segmentavimą bei metaduomenų tvarkymą. -### Modelis 6: MCP integracinis testavimas +### Šablonas 6: MCP integracijos testavimas -MCP modulis tikrina Modelio konteksto protokolo integraciją naudojant stdio transportą. Šie testai patvirtina, kad jūsų programa gali sukurti ir bendrauti su MCP serveriais kaip pakomos procesais. +MCP modulis testuoja Modelio konteksto protokolo integraciją naudojant stdio transportą. Šie testai patikrina, ar jūsų programa gali kurti ir bendrauti su MCP serveriais kaip posistemiais. -Testai faile `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` vertina MCP kliento elgseną. +Testai faile `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` tikrina MCP kliento elgesį. **Paleiskite juos:** @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## Testavimo filosofija -Testuokite savo kodą, ne DI. Jūsų testai turėtų tikrinti jūsų parašytą kodą, kaip konstruojami pavyzdžiai, kaip valdoma atmintis ir kaip vykdomi įrankiai. DI atsakymai kinta ir neturėtų būti testų patvirtinimų dalis. Klausykite savęs, ar jūsų pavyzdžio šablonas tinkamai pakeičia kintamuosius, o ne ar DI pateikia teisingą atsakymą. +Testuokite savo kodą, o ne DI. Jūsų testai turėtų patikrinti jūsų parašytą kodą, kaip užklausos kuriamos, kaip valdoma atmintis ir kaip vykdomi įrankiai. DI atsakymai kinta, tad jų nereikėtų tikrinti testų teigimuose. Užduokite sau klausimą, ar jūsų užklausų šablonas teisingai pritaiko kintamuosius, o ne ar DI pateikia teisingą atsakymą. -Naudokite maketus kalbos modeliams. Tai išoriniai komponentai, kurie yra lėti, brangūs ir nedeterministiniai. Maketai leidžia testams būti greitiems (milisekundėmis vietoje sekundžių), nemokamiems (be API kaštų) ir deterministiniams (tą patį rezultatą kiekvieną kartą). +Naudokite maketus kalbos modeliams. Jie yra išoriniai priklausomybės, lėti, brangūs ir nenuoseklūs. Maketavimas daro testus greitus su milisekundžių trukme vietoje sekundžių, nemokamus be API išlaidų ir determinuotus su tuo pačiu rezultatu kiekvieną kartą. -Išlaikykite testus nepriklausomais. Kiekvienas testas turi paruošti savo duomenis, nereikėti kitų testų ir po savęs išvalyti. Testai turi praeiti nepriklausomai nuo vykdymo eiliškumo. +Išlaikykite testus nepriklausomais. Kiekvienas testas turi paruošti savus duomenis, nenaudoti kitų testų ir tvarkyti savo aplinką. Testai turėtų veikti nepriklausomai nuo vykdymo tvarkos. -Testuokite kraštutinius atvejus, o ne tik malonius srautus. Bandykite tuščius įvedimus, labai didelius įvedimus, specialiuosius simbolius, neteisingus parametrus ir ribines sąlygas. Dažnai tai išryškina klaidas, kurių įprastas naudojimas nerodo. +Testuokite ribinius atvejus, ne tik sklandų scenarijų. Išbandykite tuščias įvestis, labai dideles įvestis, specialius simbolius, netinkamus parametrus ir ribines sąlygas. Dažnai būtent šie atvejai atskleidžia klaidas, kurias įprasta naudojimo eiga nepastebi. -Naudokite aprašomuosius pavadinimus. Palyginkite `shouldMaintainConversationHistoryAcrossMultipleMessages()` su `test1()`. Pirmasis tiksliai nurodo, kas testuojama, kas palengvina gedimų derinimą. +Naudokite aprašomuosius pavadinimus. Palyginkite `shouldMaintainConversationHistoryAcrossMultipleMessages()` su `test1()`. Pirmasis tiksliai nurodo, kas testuojama, todėl gedimų atpažinimas yra daug paprastesnis. -## Kiti žingsniai +## Tolimesni žingsniai -Dabar kai suprantate testavimo modelius, gilinkitės į kiekvieną modulį: +Dabar, kai suprantate testavimo šablonus, gilinkitės į kiekvieną modulį: -- **[00 - Greitas pradėjimas](../00-quick-start/README.md)** - Pradėkite nuo pavyzdžių šablonų pagrindų -- **[01 - Įvadas](../01-introduction/README.md)** - Sužinokite pokalbių atminties valdymą -- **[02 - Pavyzdžių inžinerija](../02/prompt-engineering/README.md)** - Įvaldykite GPT-5.2 pavyzdžių modelius -- **[03 - RAG](../03-rag/README.md)** - Kurkite paieškos ir generavimo sistemas -- **[04 - Įrankiai](../04-tools/README.md)** - Įgyvendinkite funkcijų iškvietimus ir įrankių grandines +- **[01 - Įvadas](../01-introduction/README.md)** - Sužinokite apie pokalbio atminties valdymą +- **[02 - Užklausų inžinerija](../02/prompt-engineering/README.md)** - Išmokite GPT-5.2 užklausų šablonus +- **[03 - RAG](../03-rag/README.md)** - Kurkite paieškos palaikomų generavimo sistemų +- **[04 - Įrankiai](../04-tools/README.md)** - Įgyvendinkite funkcijų kvietimus ir įrankių grandines - **[05 - MCP](../05-mcp/README.md)** - Integruokite Modelio konteksto protokolą -Kiekvieno modulio README pateikia detalius šio mokymo metu testuojamų konceptų paaiškinimus. +Kiekvieno modulio README detalizuotai paaiškina čia testuotus konceptus. --- @@ -358,6 +344,6 @@ Kiekvieno modulio README pateikia detalius šio mokymo metu testuojamų koncept --- -**Atsakomybės apribojimas**: -Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba turėtų būti laikomas pagrindiniu šaltiniu. Svarbiai informacijai rekomenduojama naudoti profesionalų žmogišką vertimą. Mes neatsakome už jokių nesusipratimų ar neteisingų interpretacijų, kylančių naudojant šį vertimą. +**Atsakomybės apribojimas**: +Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą [Co-op Translator](https://github.com/Azure/co-op-translator). Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojama naudoti profesionalų žmogiškąjį vertimą. Mes neatsakome už jokius nesusipratimus ar neteisingą interpretaciją, kilusią naudojantis šiuo vertimu. \ No newline at end of file diff --git a/translations/ml/.co-op-translator.json b/translations/ml/.co-op-translator.json index 23ac08176..52eb1b354 100644 --- a/translations/ml/.co-op-translator.json +++ b/translations/ml/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ml" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T02:08:20+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T12:40:41+00:00", "source_file": "01-introduction/README.md", "language_code": "ml" }, @@ -18,20 +18,20 @@ "language_code": "ml" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T02:11:06+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T12:35:31+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ml" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T02:12:48+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T12:39:38+00:00", "source_file": "03-rag/README.md", "language_code": "ml" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:14:10+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T12:38:10+00:00", "source_file": "04-tools/README.md", "language_code": "ml" }, @@ -54,8 +54,8 @@ "language_code": "ml" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:17:09+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T12:34:02+00:00", "source_file": "README.md", "language_code": "ml" }, @@ -72,14 +72,14 @@ "language_code": "ml" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T02:16:35+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T12:36:06+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ml" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T02:17:32+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T12:36:44+00:00", "source_file": "docs/TESTING.md", "language_code": "ml" } diff --git a/translations/ml/00-quick-start/README.md b/translations/ml/00-quick-start/README.md deleted file mode 100644 index 149c0905d..000000000 --- a/translations/ml/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: ക്വിക്ക് സ്റ്റാർട്ട് - -## ഉള്ളടക്ക പട്ടിക - -- [പരിചയം](../../../00-quick-start) -- [LangChain4j എന്താണ്?](../../../00-quick-start) -- [LangChain4j ആശ്രിതവસ્તુകൾ](../../../00-quick-start) -- [ആവശ്യകതകൾ](../../../00-quick-start) -- [സജ്ജീകരിക്കൽ](../../../00-quick-start) - - [1. നിങ്ങളുടെ GitHub ടോക്കൺ എടുത്തെടുക്കുക](../../../00-quick-start) - - [2. നിങ്ങളുടെ ടോക്കൺ സജ്ജമാക്കുക](../../../00-quick-start) -- [ഉദാഹരണങ്ങൾ ഓടിക്കുക](../../../00-quick-start) - - [1. അടിസ്ഥാന ചാറ്റ്](../../../00-quick-start) - - [2. പ്രോംപ്റ്റ് പാറ്റേൺസ്](../../../00-quick-start) - - [3. ഫങ്ഷൻ കോളിംഗ്](../../../00-quick-start) - - [4. ഡോക്യുമെന്റ് Q&A (ഇസിയുടെ RAG)](../../../00-quick-start) - - [5. ഉത്തരവാദിത്വമുള്ള AI](../../../00-quick-start) -- [പ്രതിയേക ഉദാഹരണങ്ങൾ കാണിക്കുന്നത്](../../../00-quick-start) -- [അടുത്ത കാര്യങ്ങൾ](../../../00-quick-start) -- [പ്രശ്നനിവാരണങ്ങൾ](../../../00-quick-start) - -## പരിചയം - -ഈ ക്വിക്കും സ്റ്റാർട്ട് LangChain4j ഉപയോഗിച്ച് നിങ്ങൾക്ക് വേഗത്തിൽ ആരംഭിക്കാനാണ് ഉദ്ദേശിച്ചിരിക്കുന്നത്. ഇത് LangChain4j, GitHub Models എന്നിവ ഉപയോഗിച്ച് AI ആപ്ലിക്കേഷനുകൾ നിർമ്മിക്കൽ സംബന്ധിച്ച ഏറ്റവും അടിസ്ഥാനങ്ങൾ ഉൾക്കൊള്ളുന്നു. അടുത്ത മൊഡ്യൂളുകളിൽ നിങ്ങൾ Azure OpenAI, GPT-5.2 എന്നിവയിലേക്ക് മാറുകയും ഓരോ ആശയം depth ആയി പഠിക്കുകയും ചെയ്യും. - -## LangChain4j എന്താണ്? - -LangChain4j ഒരു ജാവ ലൈബ്രറിയാണ്, AI-ചാലിത ആപ്ലിക്കേഷനുകൾ നിർമ്മിക്കുന്നത് ലളിതമാക്കുന്നു. HTTP ക്ലയന്റുകളും JSON പാഴ്‌സിംഗും കൈകാര്യം ചെയ്യാൻ പകരം, നിങ്ങൾ സുതാര്യമായ ജാവ API-കൾ ഉപയോഗിക്കുന്നു. - -LangChain എന്ന പദം LangChain4j-യിലെ "ചെയിനിംഗ്" ആയി അന്വയം ചെയ്തിരിക്കുന്നു — നിരവധി ഘടകങ്ങൾ പരസ്പരം ബന്ധിപ്പിച്ച് പ്രവർത്തിക്കുന്നു - നിങ്ങൾ ഒരു പ്രോംപ്റ്റിൽ നിന്നും മോഡലിലേക്കും രൂപാന്തരിക്കാവുന്ന ഒരു പാഴ്സറിലേക്കും, അല്ലെങ്കിൽ ഒരൊറ്റ ഔട്ട്പുട്ട് അടുത്ത ഇൻപുട്ടിനു ഇടയായി പ്രവർത്തിക്കുന്ന AI കോളുകൾ പരമ്പരയായി ബന്ധിപ്പിക്കാം. ഈ ക്വിക്ക് സ്റ്റാർട്ട് അടിസ്ഥാനങ്ങൾക്കാണ് ഊന്നൽ നൽകുന്നത്, കൂടുതൽ സങ്കീർണ്ണമായ ചെയിനുകൾക്കു മുമ്പ്. - -LangChain4j Chaining Concept - -*LangChain4j-യിലെ ഘടകങ്ങൾ ചേർത്ത് ശക്തമായ AI പ്രവൃത്തികൾ സൃഷ്ടിക്കുന്നു* - -നാം മൂന്നു മുഖ്യ ഘടകങ്ങൾ ഉപയോഗിക്കും: - -**ChatModel** - AI മോഡൽ ഇടപെടലുകളുടെ ഇന്റർഫേസ്. `model.chat("prompt")` വിളിച്ച് ഒരു പ്രതികരണostring നേടാം. GitHub Models പോലുള്ള OpenAI- അനുയോജ്യ എൻഡ്‌പോയിന്റുകളുമായി പ്രവർത്തിക്കുന്ന `OpenAiOfficialChatModel` നാം ഉപയോഗിക്കുന്നു. - -**AiServices** - ടൈപ്-സേഫ് AI സർവ്വീസ് ഇന്റർഫേസ് സൃഷ്ടിക്കുന്നു. മെത്തഡുകൾ നിർവ്വചിച്ച്, അവ `@Tool` ഉപയോഗിച്ച് അണോട്ടേറ്റ് ചെയ്യുക; LangChain4j ഓർക്കസ്ട്രേഷനു ശ്രമിക്കുന്നു. ആവശ്യമായപ്പോൾ AI ആтоматമായി നിങ്ങളുടെ ജാവ മെത്തഡുകൾ വിളിക്കും. - -**MessageWindowChatMemory** - സംവാദ ചരിത്രം പരിരക്ഷിക്കുന്നു. ഇതില്ലാതെ, ഓരോ അഭ്യർത്ഥനയും സ്വതന്ത്രമാണ്. അതോടൊപ്പം, AI മുമ്പത്തെ സന്ദേശങ്ങൾ ഓർത്തുകൂടി പല തിരങ്ങളിലായി സന്ദർഭം നിലനിർത്തും. - -LangChain4j Architecture - -*LangChain4j ആർക്കിടെക്ചർ - AI ആപ്ലിക്കേഷനുകൾക്ക് ശക്തി നൽകുന്ന പ്രധാന ഘടകങ്ങളുടെ പ്രവർത്തനം* - -## LangChain4j ആശ്രിതവસ્તુകൾ - -ഈ ക്വിക്ക് സ്റ്റാർട്ട് മൂന്ന് മേവൻ ആശ്രിതവസ്തുക്കൾ [`pom.xml`](../../../00-quick-start/pom.xml) ല്‍ ഉപയോഗിക്കുന്നു: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` മോഡ്യൂൾ OpenAI-അനുരൂപ API-കളുമായി ബന്ധിപ്പിക്കുന്ന `OpenAiOfficialChatModel` ക്ലാസ് നൽകുന്നു. GitHub Models ഇതേ API ഫോർമാറ്റ് ഉപയോഗിക്കുന്നതിനാൽ പ്രത്യേക അഡാപ്പ്റ്റർ ആവശ്യമില്ല - അടിസ്ഥാന URL `https://models.github.ai/inference` ആയി സൂചിപ്പിക്കുക. - -`langchain4j-easy-rag` മോഡ്യൂൾ സ്വയം ഡോക്യുമെന്റ് വിഭജനം, എംബെഡ്ഡിങ്ങ്, വീണ്ടെടുക്കൽ എന്നിവ അതേത്തരം സജ്ജമാക്കുന്നു, അതുകൊണ്ടുതന്നെ നിങ്ങൾക്ക് RAG ആപ്ലിക്കേഷനുകൾ രൂപീകരിക്കാൻ യാതൊരു നിമിത് ക്രമീകരണവും ആവശ്യമില്ല. - -## ആവശ്യകതകൾ - -**Dev Container ഉപയോഗിച്ചാലോ?** ജാവയും മേവനും ഇതിനകം ഇൻസ്റ്റാൾ ചെയ്തിട്ടുണ്ട്. നിങ്ങൾക്ക് GitHub വ്യക്തിഗത ആക്‌സസ് ടോക്കൺ മാത്രം വേണം. - -**ലോകൽ ഡെവലപ്പ്മെന്റ്:** -- Java 21+, Maven 3.9+ -- GitHub വ്യക്തിഗത ആക്‌സസ് ടോക്കൺ (നൽകുന്ന നിർദേശങ്ങൾ താഴെ) - -> **ഗുരുതരം:** ഈ മഡ്‌യുല്‍ GitHub Models-നു വേണ്ടി `gpt-4.1-nano` മോഡൽ ഉപയോഗിക്കുന്നു. കോഡിൽ മോഡൽ പേരെ മാറ്റരുത് - അത് GitHub ലഭ്യമായ മോഡലുകളുമായി പ്രവർത്തിക്കുന്നതിന് ക്രമീകരിച്ചിരിക്കുന്നു. - -## സജ്ജീകരിക്കൽ - -### 1. നിങ്ങളുടെ GitHub ടോക്കൺ എടുത്തെടുക്കുക - -1. [GitHub സെറ്റിങ്ങുകൾ → Personal Access Tokens](https://github.com/settings/personal-access-tokens) കാണുക -2. "Generate new token" ക്ലിക് ചെയ്യുക -3. വ്യക്തമായ ഒരു പേര് നൽകുക (ഉദാഹരണത്തിന്, "LangChain4j Demo") -4. കാലഹരണ തിയതി നിശ്ചയിക്കൽ (7 ദിവസം ശിപാർശ) -5. "Account permissions" ൽ "Models" എടുക്കുക, "Read-only" ആയി സജ്ജമാക്കുക -6. "Generate token" ക്ലിക് ചെയ്യുക -7. ടോക്കൺ കോപ്പി ചെയ്ത് സൂക്ഷിക്കുക - പിന്നീട് കാണാനാകില്ല - -### 2. നിങ്ങളുടെ ടോക്കൺ സജ്ജമാക്കുക - -**വികസ്വിടെ (VS Code) ഉപയോഗിക്കൽ (ശിപാർശ):** - -VS Code ഉപയോഗിച്ചാൽ, പ്രോജക്റ്റ് റൂട്ട്-level `.env` ഫയലിൽ നിങ്ങളുടെ ടോക്കൺ ചേർക്കുക: - -`.env` ഫയൽ ഇല്ലെങ്കിൽ, `.env.example` കോപ്പി ചെയ്ത് `.env` ആക്കൂ അല്ലെങ്കിൽ പുതിയ `.env` ഫയൽ പ്രോജക്റ്റ് റൂട്ട്-ലേക്ക് സൃഷ്ടിക്കുക. - -**ഉദാഹരണ `.env` ഫയൽ:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env ഫയൽയിൽ -GITHUB_TOKEN=your_token_here -``` - -പിന്നീട്, എളുപ്പം Explorer-യിൽ ഏതെങ്കിലും ഡെമോ ഫയലിൽ (ഉദാ: `BasicChatDemo.java`) റൈറ്റ്-ക്ലിക്ക് ചെയ്ത് **"Run Java"** തിരഞ്ഞെടുക്കാം അല്ലെങ്കിൽ Run and Debug പാനലിലെ ലോഞ്ച് കോൺഫിഗറേഷനുകൾ ഉപയോഗിക്കുക. - -**ടെർമിനൽ ഉപയോഗിക്കൽ** - -ടോക്കൺ എൻവയോൺമെന്റ് വേരിയബിൾ ആയി സജ്ജമാക്കുക: - -**ബാഷ്:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**പവർഷെൽ:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## ഉദാഹരണങ്ങൾ ഓടിക്കുക - -**VS Code ഉപയോഗിച്ച്:** Explorer-ലേക്ക് ഏതെങ്കിലും ഡെമോ ഫയലിൽ റൈറ്റ്-ക്ലിക്ക് ചെയ്ത് **"Run Java"** തിരഞ്ഞെടുക്കുക, അല്ലെങ്കിൽ Run and Debug ല吤ഞ്ച് കോൺഫിഗറേഷനുകൾ ഉപയോഗിക്കാം (നിങ്ങളുടെ ടോക്കൺ `.env` ഫയലിൽ ചേർത്തിട്ടുണ്ടെന്ന് ഉറപ്പാക്കുക). - -**മേവൻ ഉപയോഗിച്ച്:** comando line-ൽ നിന്നും ഓടിക്കാം: - -### 1. അടിസ്ഥാന ചാറ്റ് - -**ബാഷ്:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**പവർഷെൽ:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. പ്രോംപ്റ്റ് പാറ്റേൺസ് - -**ബാഷ്:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**പവർഷെൽ:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -സീറോ ഷോട്ട്, ഫ്യൂ ഷോട്ട്, ചെയിൻ ഓഫ് തോട്ട്, റോള്ബേസ് പ്രോംപ്റ്റിംഗ് കാണിക്കുന്നു. - -### 3. ഫങ്ഷൻ കോളിംഗ് - -**ബാഷ്:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**പവർഷെൽ:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -ആവശ്യമായപ്പോൾ AI സ്വയം നിങ്ങളുടെ ജാവ മെത്തഡുകൾ വിളിക്കും. - -### 4. ഡോക്യുമെന്റ് Q&A (ഇസിയുടെ RAG) - -**ബാഷ്:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**പവർഷെൽ:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -സ്വയം എംബെഡിംഗ്, വീണ്ടെടുത്തൽ ഉപയോഗിച്ച് ഡോക്യുമെന്റുകൾക്കു പറ്റിയ ചോദ്യങ്ങൾ ചോദിക്കാം. - -### 5. ഉത്തരവാദിത്വമുള്ള AI - -**ബാഷ്:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**പവർഷെൽ:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -AI സുരക്ഷാ ഫിൽട്ടറുകൾ എങ്ങിനെ ഹാനികരമായ ഉള്ളടക്കം തടയുന്നു എന്ന് കാണുക. - -## പ്രതിയേക ഉദാഹരണങ്ങൾ കാണിക്കുന്നത് - -**അടിസ്ഥാന ചാറ്റ്** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -ഇവിടെ LangChain4j-ന്റെ ലളിതമായ രൂപം കാണാം. `OpenAiOfficialChatModel` സൃഷ്ടിച്ച് `.chat()` വഴി പ്രോംപ്റ്റ് അയച്ച് പ്രതികരണം നേടി. മോഡലുകൾ ഇനിഷ്യലൈസ് ചെയ്യൽ, കസ്റ്റം എൻഡ്‌പോയിന്റുകളും API കീകളും ഉപയോഗിച്ചുള്ള രീതികൾ ഇത് കാണിക്കുന്നു. ഇത് മനസ്സിലാക്കിയാൽ എല്ലാ മറ്റ് കാര്യങ്ങളും ഇതിന്റെ അടിസ്ഥാനത്തിലാണ്. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 GitHub Copilot [ചാറ്റുമായി പരീക്ഷിക്കുക](https://github.com/features/copilot):** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) തുറന്നിട്ട് ചോദിക്കുക: -> - "GitHub Models-ൽ നിന്ന് Azure OpenAI-ലേക്ക് ഈ കോഡ് എങ്ങനെ മാറ്റാം?" -> - "OpenAiOfficialChatModel.builder()-ൽ മറ്റേതെല്ലാം parameters ക്രമീകരിക്കാമ?" -> - "കൃത്യമായ പ്രതികരണം എത്തുന്നതുവരെ കാത്തിരിക്കാൻ പകരം സ്‌ട്രിമിംഗ് പ്രതികരണങ്ങൾ എങ്ങനെ ചേർക്കാം?" - -**പ്രോംപ്റ്റ് എൻജിനീയറിങ്** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -ഇപ്പോൾ മോഡലുമായി സംവേദനം എങ്ങനെ നടത്തണം എന്നത് പഠിച്ചു. ഇനി നിങ്ങൾ പറയുന്ന കാര്യങ്ങൾ പരിശോധിക്കും. ഈ ഡെമോ ആ_same_ മോഡൽ സജ്ജീകരണവും അഞ്ച് വ്യത്യസ്ത പ്രോംപ്റ്റിംഗ് മാതൃകകളും കാണിക്കുന്നു. നേരിട്ട് നിർദ്ദേശങ്ങൾക്കായി സീറോ ഷോട്ട്, ഉദാഹരണങ്ങളിൽ നിന്നു പഠിക്കാൻ few-shot, ചിന്താശൃംഖലയുമായി chain-of-thought, പരിസ്ബന്ദ്ധം നിശ്ചയിക്കുന്ന role-based prompting എന്നിവ പരീക്ഷിക്കുക. നിയമിത വിചാര സമ്പ്രദായത്തിൽ വ്യത്യസ്ത ഫലങ്ങൾ ലഭിക്കുന്നതും കാണാം. - -ഡെമോ പ്രോംപ്റ്റ് ടെംപ്ലേറ്റുകളും കാണിക്കുന്നു, പുനഃഉപയോഗയോഗ്യമായി വെറും മൂല്യങ്ങൾ പുറത്താക്കാൻ സഹായിക്കുന്നു. -താഴെയുള്ള ഉദാഹരണം LangChain4j `PromptTemplate` ഉപയോഗിച്ച് മൂല്യങ്ങൾ പൂരിപ്പിക്കുന്ന പ്രോംപ്റ്റ് കാണിക്കുന്നു. നൽകിയ ലക്ഷ്യസ്ഥലവും പ്രവർത്തനവും അടിസ്ഥാനമാക്കി AI മറുപടി നൽകും. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 GitHub Copilot [ചാറ്റുമായി പരീക്ഷിക്കുക](https://github.com/features/copilot):** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) തുറന്ന് ചോദിക്കുക: -> - "സീറോ ഷോട്ടും few-shot ഉം എന്ത് വ്യത്യാസമുള്ളതാണ്, എപ്പോൾ ഏത് ഉപയോഗിക്കണം?" -> - "ടെംപറേച്ചർ പാരാമീറ്റർ മോഡലിന്റെ പ്രതികരണങ്ങളിൽ എങ്ങനെ സ്വാധീനം ചെലുത്തുന്നു?" -> - "പ്രോംപ്റ്റ് ഇൻജെക്ഷൻ ആക്രമണങ്ങൾ തടയാൻ പ്രയോഗിക്കുന്ന രീതികൾ ഏതെല്ലാം?" -> - "സാധാരണ മാതൃകകൾക്കായി പുനഃഉപയോഗയോഗ്യമായ PromptTemplate ഓബ്‌ജെക്ടുകൾ എങ്ങനെ സൃഷ്ടിക്കാം?" - -**ടൂൾ ഇന്റഗ്രേഷൻ** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -ഇവിടെ LangChain4j ശക്തമായി മാറുന്നു. `AiServices` ഉപയോഗിച്ച് ജാവ മെത്തഡുകൾക്ക് കോളുകൾ ചെയ്യാവുന്ന AI അസിസ്റ്റന്റിനെ സൃഷ്ടിക്കും. മെത്തഡുകൾ `@Tool("വിവരണം")` ഉപയോഗിച്ച് അണോട്ടേറ്റ് ചെയ്യുക; LangChain4j ബാക്കി ഓർക്കസ്ട്രേഷൻ നടത്തും - ഉപയോക്താവ് ചോദിക്കുന്നതിനെ അടിസ്ഥാനമാക്കി AI യഥോചിതമായി ടൂളുകൾ ഉപയോഗിക്കുന്നതും കാണിക്കും. ഫങ്ഷൻ കോളിംഗ് വ്യക്തമാക്കുന്നു, AI ചോദ്യം മാത്രമല്ല പ്രവർത്തനങൾ ചെയ്യാനും കഴിയുമെന്നു കാണിക്കുന്നു. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 GitHub Copilot [ചാറ്റുമായി പരീക്ഷിക്കുക](https://github.com/features/copilot):** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) തുറന്ന് ചോദിക്കുക: -> - "@Tool അനോട്ടേഷൻ എങ്ങനെ പ്രവർത്തിക്കുന്നു? LangChain4j ഈ വിവരത്തോടു പിന്നോട്ട് എങ്ങനെ കൈകാര്യം ചെയ്യുന്നു?" -> - "സങ്കീര്‍ണ പ്രശ്നങ്ങൾ പരിഹരിക്കാൻ AI അനന്തരം പല ടൂളുകളും കോളുകൾ നടത്താമോ?" -> - "ടൂൾ ഒരു തെറ്റുചെയ്യുമ്പോൾ എങ്ങനെയാണ് അത് കൈകാര്യം ചെയ്യേണ്ടത്?" -> - "ഈ കാൽകുലേറ്റർ ഉദാഹരണത്തിന് പകരം യഥാർത്ഥ API എങ്ങനെ ഇന്റഗ്രേറ്റ് ചെയ്യാം?" - -**ഡോക്യുമെന്റ് Q&A (ഇസിയുടെ RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -ഇവിടെ LangChain4j-ന്റെ "ഇസിയുടെ RAG" ഉപയോഗiraju. ഡോക്യുമെന്റുകൾ ലോഡ് ചെയ്ത്, സ്വയം വിഭജിച്ച്, ഇൻ-മെമ്മറി സ്റ്റോറിൽ എംബഡ് ചെയ്തുകൊണ്ട്, AI ചോദിച്ചപ്പോൾ ബന്ധപ്പെട്ട ഭാഗങ്ങൾ ലഭിക്കുന്നു. AI പൊതുസമാഹാരം പകരം നിങ്ങളുടെ ഡോക്യുമെന്റുകൾ അടിസ്ഥാനമാക്കി മറുപടി നൽകുന്നു. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 GitHub Copilot [ചാറ്റുമായി പരീക്ഷിക്കുക](https://github.com/features/copilot):** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) തുറന്ന് ചോദിക്കുക: -> - "AI ഹാളുസിനേഷനുകൾ RAG ഉപയോഗിച്ച് മോഡലിന്റെ ട്രെയിനിംഗ് ഡാറ്റാ ഉപയോഗിക്കുന്നതുമായുള്ള വ്യത്യാസം എങ്ങനെയാണ്?" -> - "ഈ എളുപ്പമായ സമീപനം ഒരു കസ്റ്റം RAG പൈപ്പ്‌ലൈൻനോട് താരതമ്യം ചെയ്‌താൽ എന്ത് വ്യത്യാസം ഉണ്ടാക്കുന്നു?" -> - "പല ഡോക്യുമെന്റുകളും കൂടുതൽ വലിയ ജ്ഞാന വാസ്തവങ്ങളും കൈകാര്യം ചെയ്യാൻ ഇത് എങ്ങനെ സ്കെയിൽ ചെയ്യാം?" - -**ഉത്തരവാദിത്വമുള്ള AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -പ്രതിരോധത്തിലൂടെ AI സുരക്ഷ സ്ഥാപിക്കുക. ഈ ഡെമോ രണ്ട് സംരക്ഷണ പാളികൾ ഒന്നിച്ച് പ്രവർത്തിക്കുന്നതാണ്: - -**പാര്‍ട്ട് 1: LangChain4j ഇൻപുട്ട് ഗാർഡ്‌റെയിൽസ്** - LLM വരെ എത്തുന്നതിന് മുമ്പെ അപകടകരമായ പ്രോംപ്റ്റുകൾ തടയുക. നിഷേധിച്ചിരിക്കുന്ന കീവേർഡുകളും മാതൃകകളും പരിശോധിക്കുന്ന കസ്റ്റം ഗാർഡ്‌റെയിൽസ് സൃഷ്ടിക്കുക. ഇത് നിങ്ങളുടെ കോഡിൽ പ്രവർത്തിക്കുന്നതിനാൽ വേഗം കൂടിയിരിക്കുന്നു. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**പാര്‍ട്ട് 2: പ്രൊവൈഡർ സുരക്ഷാ ഫിൽട്ടറുകൾ** - GitHub Models-ന് ഉൾപ്പെടുത്തിയ ഫിൽട്ടറുകൾ നിങ്ങളുടെ ഗാർഡ്‌റെയിൽസ് കാണാതാക്കുന്നത് പിടിക്കും. ഗുരുതരമായ ലംഘനങ്ങൾക്കുള്ള കഠിന ബ്ലോക്കുകൾ (HTTP 400 പിശക്) കൂടാതെ AI വിനീതമായി നിരാകരിക്കുന്ന സോഫ്റ്റ് നിരാകരണങ്ങളും നിങ്ങൾ കാണും. - -> **🤖 GitHub Copilot [ചാറ്റുമായി പരീക്ഷിക്കുക](https://github.com/features/copilot):** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) തുറന്ന് ചോദിക്കുക: -> - "InputGuardrail എന്താണ്, എങ്ങനെ എന്റെ സ്വന്തം ഉണ്ടാക്കാം?" -> - "കഠിന ബ്ലോക്കും സോഫ്റ്റ് നിരാകരണവും തമ്മില有什么 വ്യത്യാസം?" -> - "ഗാർഡ്‌റെയിൽസും പ്രൊവൈഡർ ഫിൽട്ടറുകളും ഒരുമിച്ച് ഉപയോഗിക്കുന്നത് എന്തിനാണ്?" - -## അടുത്ത കാര്യങ്ങൾ - -**അടുത്ത മോദ്യൂൾ:** [01-പരിചയം - LangChain4j ഉപയോഗിച്ച് തുടങ്ങൽ](../01-introduction/README.md) - ---- - -**നാവിഗേഷൻ:** [← മെയിനിലേക്ക് മടങ്ങുക](../README.md) | [അടുത്തത്: Module 01 - Introduction →](../01-introduction/README.md) - ---- - -## പ്രശ്നനിവാരണങ്ങൾ - -### പ്രഥമമായ മേവൻ ബിൽഡ് - -**പ്രശ്നം:** ആദ്യ `mvn clean compile` അല്ലെങ്കിൽ `mvn package` വളരെ നീളുന്നു (10-15 മിനിറ്റ്) - -**കാരണങ്ങൾ:** മേവന് പ്രോജക്റ്റ് ആശ്രിതവസ്തുക്കൾ (Spring Boot, LangChain4j ലൈബ്രറികൾ, Azure SDK-കൾ മുതലായവ) ആദ്യമായി ഡൗൺലോഡ് ചെയ്യേണ്ടതുണ്ട്. - -**പരിഹാരം:** ഇത് അവശ്യമായ പ്രവർത്തനമാണ്. തുടര്‍ന്നുള്ള ബിൽഡുകൾ വേഗമേറിയതാണ്, ആവശ്യമായ ആശ്രിതവസ്തുക്കൾ ലോക്കൽ ആയി കാഷ് ചെയ്യും. ഡൗൺലോഡ് സമയത്ത് നിങ്ങളുടെ നെറ്റ്‌വർക്കിന്റെ വേഗത ആശ്രയിക്കും. - -### പവർഷെൽ Maven കമാൻഡ് സിന്റാക്സ് - -**പ്രശ്നം:** Maven കമാൻഡുകൾ `Unknown lifecycle phase ".mainClass=..."` എന്ന പിശക് കാണിക്കുന്നു -**കാരണം**: PowerShell `=` നെ വെരിയബിൾ അസൈൻമെന്റ് ഒപറേറ്ററായി വ്യാഖ്യാനിക്കുന്നു, Maven പ്രോപ്പർട്ടി സിന്റാക്സ് വീണ്ടും തകര്‍ക്കുന്നു - -**പരിഹാരം**: Maven കമാൻഡിന് മുമ്പ് സ്റ്റോപ്പ്-പാഴ്സിംഗ് ഓപ്പറേറ്റർ `--%` ഉപയോഗിക്കുക: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` ഓപ്പറേറ്റർ PowerShell-ന് ബാകിച്ചത് ലിറ്ററലി Maven-ന് നൽകണമെന്നാണ് without വാചക വ്യാഖ്യാനം. - -### Windows PowerShell Emoji പ്രദർശനം - -**പ്രശ്‌നം**: PowerShell-ൽ ഈമോജികളുടെ പകരം AI പ്രതികരണങ്ങൾ ചീഞ്ഞ കരക്ടറുകളായി കാണുന്നു (ഉദാഹരണം, `????` അല്ലെങ്കിൽ `â??`) - -**കാരണം**: PowerShell-ന്റെ ഡിഫോൾട്ട് എൻകോഡിംഗ് UTF-8 ഈമോജികളെ പിന്തുണയ്ക്കുന്നില്ല - -**പരിഹാരം**: ജावा ആപ്പ്‌സ് റൺ ചെയ്യുന്നതിന് മുമ്പായി ഈ കമാൻഡ് ഓടിക്കുക: -```cmd -chcp 65001 -``` - -ഇത് ടെർമിനലിൽ UTF-8 എൻകോഡിങ് നിർബന്ധിതമാക്കും. അല്ലെങ്കിൽ, യുണികോഡ് പിന്തുണ മികച്ച Windows ടർമിനൽ ഉപയോഗിക്കുക. - -### API കോളുകൾ ഡീബഗ്ഗിംഗ് - -**പ്രശ്‌നം**: ഓത്‌മെന്റിക്കേഷൻ പിശകുകൾ, റേറ്റ് ലിമിറ്റുകൾ, അല്ലെങ്കിൽ 예상ത്തിൻറെ പുറത്ത് ആയ AI മോഡൽ പ്രതികരണങ്ങൾ - -**പരിഹാരം**: ഉദാഹരണങ്ങളിൽ `.logRequests(true)`യും `.logResponses(true)`യും ഉൾപ്പെടുത്തിയിട്ടുണ്ട്, API കോളുകൾ കൺസോളിൽ കാണിക്കാൻ. ഇത് ഓത്‌മെന്റിക്കേഷൻ പിശകുകൾ, റേറ്റ് ലിമിറ്റുകൾ അല്ലെങ്കിൽ 예상ത്തിൻറെ വക പിശകുകൾ പരിഹരിക്കാൻ സഹായിക്കും. ലോങ് ധ്വനി കുറക്കാൻ പ്രൊഡക്ഷനിൽ ഈ ഫ്ലാഗുകൾ ഒഴിവാക്കുക. - ---- - - -**പരാമർശം**: -ഈ രേഖ AI വിവർത്തനസേവനമായ [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ചാണ് വിവർത്തനം ചെയ്തത്. നാം കാര്യക്ഷമതയ്ക്ക് ശ്രമിക്കുന്നതായിരുന്നാലും, സ്വയംകൃതമായ വിവർത്തനങ്ങളിൽ പിശകുകൾ അല്ലെങ്കിൽ തെറ്റുകൾ ഉണ്ടായേക്കാമെന്നതു ദയവായി ശ്രദ്ധിക്കുക. പ്രാഥമികഭാഷയിൽ ഉള്ള യഥാർത്ഥ രേഖയാണ് വിശ്വസനീയമായ ഉറവിടം. നിർണായക വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ വിവർത്തനം നിർദ്ദേശിക്കുന്നു. ഈ വിവർത്തനത്തിന് ആശയക്കുഴപ്പങ്ങൾ അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾ ഉണ്ടായാലും ഞങ്ങൾ ഉത്തരവാദികളല്ല. - \ No newline at end of file diff --git a/translations/ml/01-introduction/README.md b/translations/ml/01-introduction/README.md index 004f0b58b..cebf4c233 100644 --- a/translations/ml/01-introduction/README.md +++ b/translations/ml/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j ഉപയോഗിച്ച് പ്രഖ്യാപനം ആരംഭിക്കല്‍ +# Module 01: LangChain4j ഉപയോഗിച്ച് ആരംഭിക്കൽ ## ഉള്ളടക്ക പട്ടിക -- [വിഡിയോ വിശദീകരണം](../../../01-introduction) -- [നിങ്ങള്‍ പഠിക്കാനുള്ളത്](../../../01-introduction) -- [ആവശ്യകതകള്‍](../../../01-introduction) -- [പ്രധാന പ്രശ്നം മനസ്സിലാക്കല്‍](../../../01-introduction) -- [ടോക്കനുകള്‍ മനസ്സിലാക്കല്‍](../../../01-introduction) -- [മെമ്മറി എങ്ങനെ പ്രവര്‍ത്തിക്കുന്നു](../../../01-introduction) -- [ഇത് LangChain4j എങ്ങനെ ഉപയോഗിക്കുന്നു](../../../01-introduction) -- [Azure OpenAI ഇന്‍ഫ്രാസ്റ്റ്രക്ചര്‍ വിന്യസിക്കുക](../../../01-introduction) -- [പ്രയോഗം ലൊക്കലില്‍ ഓടിക്കുക](../../../01-introduction) -- [പ്രയോഗം ഉപയോഗിക്കല്‍](../../../01-introduction) - - [സ്ഥിതിവിശേഷമില്ലാത്ത ചാറ്റ് (ഇടത് പാനല്‍)](../../../01-introduction) - - [സ്ഥിതിവൈശേഷ്യമുള്ള ചാറ്റ് (വലതത് പാനല്‍)](../../../01-introduction) -- [അടുത്ത പൊരുളുകള്‍](../../../01-introduction) +- [വീഡിയോ നടത്തിപ്പ്](#വീഡിയോ-നടത്തിപ്പ്) +- [നിങ്ങൾ പഠിക്കു‍ന്നു്](#നിങ്ങൾ-പഠിക്കു‍ന്നു്) +- [അവസാന്റെ സാഹചര്യങ്ങൾ](#അവസാന്റെ-സാഹചര്യങ്ങൾ) +- [പ്രധാന പ്രശ്നം മനസിലാക്കല്‍](#പ്രധാന-പ്രശ്നം-മനസിലാക്കല്‍) +- [ടോക്കണുകൾ മനസിലാക്കുക](#ടോക്കണുകൾ-മനസിലാക്കുക) +- [മെമ്മറി എങ്ങനെ പ്രവർത്തിക്കുന്നു](#മെമ്മറി-എങ്ങനെ-പ്രവർത്തിക്കുന്നു) +- [ഇത് LangChain4j എങ്ങനെ ഉപയോഗിക്കുന്നു](#ഇത്-langchain4j-എങ്ങനെ-ഉപയോഗിക്കുന്നു) +- [Azure OpenAI ഇൻഫ്രാസ്ട്രക്ചർ വിന്യസിക്കുക](#azure-openai-ഇൻഫ്രാസ്ട്രക്ചർ-വിന്യാസം) +- [ആപ്ലിക്കേഷൻ ലോക്കലായി പ്രവർത്തിക്കുക](#ആപ്ലിക്കേഷൻ-ലോക്കലായി-പ്രവർത്തിക്കുക) +- [ആപ്ലിക്കേഷൻ ഉപയോഗിക്കൽ](#ആപ്ലിക്കേഷൻ-ഉപയോഗിക്കൽ) + - [സ്റ്റേറ്റ്‌ലെസ് ചാറ്റ് (ഇടത് പാനൽ)](#സ്റ്റേറ്റ്‌ലെസ്-چാറ്റ്-ഇടത്-പാനൽ) + - [സ്റ്റേറ്റ്‌ഫുൾ ചാറ്റ് (വലതു പാനൽ)](#സ്റ്റേറ്റ്‌ഫുൾ-ചാറ്റ്-വലതു-പാനൽ) +- [അടുത്ത ഘട്ടങ്ങൾ](#അടുത്ത-ഘട്ടങ്ങൾ) -## വീഡിയോ വിശദീകരണം +## വീഡിയോ നടത്തിപ്പ് -ഈ ലൈവ് സെഷന്‍ കാണുക, ഈ മൊഡ്യൂള്‍ എങ്ങനെ ആരംഭിക്കാമെന്ന് വിശദീകരിക്കുന്നതാണ്: +ഈ മോട്യൂളുമായി ആരംഭിക്കുന്നത് എങ്ങനെ എന്ന് വിശദീകരിക്കുന്ന ഈ ലൈവ് സെഷൻ കാണുക: Getting Started with LangChain4j - Live Session -## നിങ്ങള്‍ പഠിക്കാനുള്ളത് +## നിങ്ങൾ പഠിക്കു‍ന്നു് -ക്വിക്ക് സ്റ്റാര്‍ട്ടില്‍, നിങ്ങൾ GitHub മോഡലുകൾ ഉപയോഗിച്ച് പ്രോംപ്റ്റുകൾ അയച്ചു, ടൂളുകൾ വിളിച്ച്, RAG പൈപ്പ്ലൈൻ നിർമ്മിച്ച്, ഗാർഡ്‌റെയിലുകളും പരിശോധിച്ചു. ആ ഡെമോകൾ എന്ത് സാധ്യമാണ് എന്ന് കാണിച്ചു — ഇപ്പോൾ ഞങ്ങൾ Azure OpenAIയും GPT-5.2 ഉം ഉപയോഗിച്ച് ഉത്പാദന രീതിയിലെ അപ്ലിക്കേഷനുകൾ നിർമ്മിക്കാൻ തുടങ്ങുന്നു. ഈ മൊഡ്യൂള്‍ സന്ദർഭം ഓർക്കുകയും നില നിലനിര്‍ത്തുകയും ചെയ്യുന്ന സംഭാഷണ എഐ ആയി കേന്ദ്രീകരിക്കുന്നു — ആ ക്വിക്ക് സ്റ്റാർട്ട് ഡെമോകൾ പിന്തുണച്ച കല്പനകൾ ഞങ്ങള്‍ക്ക് വിശദീകരിക്കുന്നില്ലായിരുന്നു. +LangChain4j, Azure OpenAI എന്നിവെയുമായി ആരംഭിക്കുന്നതിന് ഇത് നിങ്ങളുടെ തുടക്കബിന്ദുവാണ്. നാം അടിസ്ഥാനങ്ങൾ പ്രാരംഭിച്, ഉൽപ്പാദനമാർഗ്ഗത്തിൽ പ്രയോഗങ്ങൾ നിർമ്മിക്കാൻ തുടങ്ങുന്നു. ഈ മോട്യൂൾ സംവാദ സൗഹൃദ AI-നെ കേന്ദ്രീകരിക്കുന്നു, അത് സന്ദർഭം ഓർമ്മിക്കുന്നു, സ്റ്റേറ്റ് നിലനിര്‍ത്തുന്നു - എല്ലാ പിന്നീട് വരുന്ന മോട്യൂളുകൾക്കും അടിസ്ഥാന ആശയങ്ങൾ. -ഈ ഗൈഡിൽ മുഴുവൻ Azure OpenAI-യുടെ GPT-5.2 ഉപയോഗിക്കും, കാരണം അതിന്റെ പുരോഗമനമായ റീസണിംഗ് ശേഷികൾ വ്യത്യസ്ത പാറ്റേണുകളുടെ പെരുമാറ്റം കൂടുതൽ വ്യക്തമായി കാണുകയും ചെയ്യുന്നു. നിങ്ങൾ മെമ്മറി ചേർക്കുമ്പോൾ വ്യത്യാസം വ്യക്തമായും കാണും. ഇത് ഓരോ ഘടകവും നിങ്ങളുടെ അപ്ലിക്കേഷനിലേക്ക് കൊണ്ട് വരുന്നവ മനസ്സിലാക്കാൻ എളുപ്പമാക്കുന്നു. +ഇവിടെ നാം Azure OpenAI-യുടെ GPT-5.2 ഉപയോഗിക്കും, അതിന്റെ ഉയർന്ന നിര്ണയപ്രവർത്തിത്വങ്ങൾ വിവിധ മാതൃകകളുടെ പെരുമാറ്റം വ്യക്തമായി കാണാൻ സഹായിക്കുന്നു. മെമ്മറി ചേർക്കുമ്പോൾ, വ്യത്യാസം വളരെ স্পഷ്ടമായിരിക്കും. ഇത് ഓരോ ഘടകവും നിങ്ങളുടെ ആപ്ലിക്കേഷനിൽ എന്ത് കൊണ്ടുവരിക എന്നതു എളുപ്പത്തിൽ മനസിലാക്കാൻ സഹായിക്കും. -നിങ്ങൾ രണ്ടു പാറ്റേണുകളും കാണിക്കുന്ന ഒരു അപ്ലിക്കേഷൻ നിർമ്മിക്കും: +നിങ്ങൾ രണ്ടെണ്ണം പ്രയോഗങ്ങൾ നിർമ്മിക്കും, ഓരോ മാതൃകയും പ്രതിപാദിക്കുന്ന: -**സ്ഥിതിവിശേഷമില്ലാത്ത ചാറ്റ്** - ഓരോ അഭ്യർത്ഥനയും സ്വതന്ത്രമാണ്. മോഡലിന് മുമ്പത്തെ സന്ദേശങ്ങളുടെ ഓർമയില്ല. ഇത് ക്വിക്ക് സ്റ്റാർട്ടിൽ നിങ്ങൾ ഉപയോഗിച്ച പാറ്റേണാണ്. +**സ്റ്റേറ്റ്‌ലെസ് ചാറ്റ്** - ഓരോ അഭ്യർത്ഥനയും സ്വതന്ത്രമാണ്. മോഡൽ മുമ്പത്തെ സന്ദേശങ്ങൾ ഓർമ്മിക്കുന്നില്ല. ഇത് ഏറ്റവും ലളിതമായ തുടക്കം. -**സ്ഥിതിവൈശേഷ്യമുള്ള സംഭാഷണം** - ഓരോ അഭ്യർത്ഥനയിലും സംഭാഷണ ചരിത്രം ഉള്‍പ്പെടുന്നു. മോഡൽ നിരവധി ഘട്ടങ്ങളിലായി കോൺടെക്സ്റ്റ് നിലനിര്‍ത്തുന്നു. ഉത്പാദന അപ്ലിക്കേഷനുകള്‍ക്ക് ഇതാണ് ആവശ്യം. +**സ്റ്റേറ്റ്‌ഫുൾ സംവാദം** - ഓരോ അഭ്യർത്ഥനയും സംവാദ ചരിത്രം ഉൾക്കൊള്ളുന്നു. മോഡൽ പല തിരിവുകളിലും സന്ദർഭം നിലനിർത്തുന്നു. ഉൽപ്പാദന പ്രയോഗങ്ങൾക്ക് ഇത് ആവശ്യമാണ്. -## ആവശ്യകതകള്‍ +## അവസാന്റെ സാഹചര്യങ്ങൾ -- Azure സബ്സ്ക്രിപ്ഷൻ Azure OpenAI ആക്‌സസ് ഉള്ളത് -- ജാവ 21, മേവൻ 3.9+ +- Azure സബ്സ്ക്രിപ്ഷൻ Azure OpenAI ആക്സസ് സഹിതം +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **കുറിപ്പ്:** ജാവ, മേവൻ, Azure CLI, Azure Developer CLI (azd) പൂർവ്വസ്ഥാപിതമാണ് സമർപ്പിച്ച devcontainer-ലിൽ. +> **ശ്രദ്ധിക്കുക:** Java, Maven, Azure CLI, Azure Developer CLI (azd) ലഭ്യമായ devcontainer-ൽ മുൻകൂട്ടியே സ്ഥാപിച്ചിരിക്കുന്നു. -> **കുറിപ്പ്:** ഈ മൊഡ്യൂള്‍ Azure OpenAI-ൽ GPT-5.2 ഉപയോഗിക്കുന്നു. `azd up` എന്നത് വിന്യാസം സ്വയം ക്രമീകരിക്കുന്നു - കോഡിലുള്ള മോഡല്‍ നാമം മാറ്റരുത്. +> **ശ്രദ്ധിക്കുക:** ഈ മോട്യൂൾ Azure OpenAI യിലെ GPT-5.2 ഉപയോഗിക്കുന്നു. വിന്യാസം സ്വയം `azd up` വഴിയാണ് നടത്തുന്നത് - കോഡിൽ മോഡൽ നാമം മാറ്റാൻ പാടില്ല. -## പ്രധാന പ്രശ്നം മനസ്സിലാക്കല്‍ +## പ്രധാന പ്രശ്നം മനസിലാക്കല്‍ -ഭാഷാ മോഡലുകൾ സ്ഥിതിവിശേഷമില്ലാത്തവയാണ്. ഓരോ API കോൾവും സ്വതന്ത്രമാണ്. നിങ്ങൾ "എന്റെ പേര് ജോൺ ആണ്" എന്ന് അയച്ചു ശേഷം "എന്റെ പേര് എന്ത്?" എന്ന് ചോദിച്ചാലും, മോഡലിന് നിനക്ക് ഇപ്പോൾ തന്നെ പരിചയപ്പെടുത്തിയില്ലെന്നൊരു ധാരണയില്ല. ഓരോ അഭ്യർത്ഥനയും നിങ്ങളുടെ ആദ്യ സംഭാഷണമെന്ന് കരുതുന്നു. +ഭാഷാ മാതൃകകൾ സ്റ്റേറ്റ്‌ലെസ്സാണ്. ഓരോ API കോളും സ്വതന്ത്രമാണു്. "എന്റെ പേര് ജോൺ ആണ്" എന്ന് അയച്ച ശേഷം "എന്റെ പേര് എന്താണ്?" എന്ന് ചോദിക്കുമ്പോൾ, മോഡലിന് നിങ്ങൾ അറിയിച്ചുവെന്ന് അറിയില്ല. അത് ഓരോ അഭ്യർത്ഥനയെ ആദ്യ സംവാദമെന്നു കരുതുന്നു. -ഇത് ലളിതമായ ചോദ്യോത്തരങ്ങൾക്ക് മതിയാകാം, പക്ഷേ യഥാർത്ഥ അപ്ലിക്കേഷനുകൾക്കായി അത് യാതൊരു പ്രയോജനവുമുള്ളതല്ല. കസ്റ്റമർ സർവീസ് ബോട്ടുകൾ നിങ്ങൾ പറഞ്ഞതെല്ലാം ഓർക്കണം. വ്യക്തിഗത സഹായികൾക്ക് കോൺടെക്സ്റ്റ് ആവശ്യമുണ്ട്. ഏതു മൾട്ടി-ടേൺ സംഭാഷണവും മെമ്മറി ആവശ്യമാണ്. +പൊതു ചോദ്യോത്തരങ്ങളിൽ ഇതു പൊരുത്തപ്പെടുമ്പോൾ, യഥാർഥ ആപ്പ്ലിക്കേഷനുകളിൽ ഇത് ഉപകാരപ്പെട്ടില്ല. കസ്റ്റമർ സർവീസ് ബോട്ടുകൾ നിങ്ങൾ പറഞ്ഞത് ഓർമ്മിക്കണം. പേഴ്സണൽ അസിസ്റ്റന്റുകൾക്ക് സന്ദർഭം ആവശ്യമാണ്. പല വട്ട സംവാദങ്ങൾ മെമ്മറി ആവശ്യപ്പെടുന്നു. -ഇതൊരു ചിത്രമാണ് രണ്ടു സമീപനങ്ങളുടെ ഭേദം പ്രത്യക്ഷപ്പെടുന്നത് — ഇടതു വശത്ത്, നിങ്ങളുടെ പേര് മറക്കുന്ന സ്ഥിതിവിശേഷമില്ലാത്ത കോൾ; വലതു വശത്ത്, ChatMemory പിന്തുണയാണ് നിലനിര്‍ത്തുന്നത്. +താഴെയുള്ള ചിത്രത്തിലെ ഇടത് ഭാഗത്ത്, നിങ്ങളുടെ പേരു് മറക്കുന്ന സ്റ്റേറ്റ്‌ലെസ് കോളും, വലത് ഭാഗത്ത് ChatMemory ഉപയോഗിച്ച് മറപ്പിക്കാതെ നിലനിർത്തുന്ന സ്റ്റേറ്റ്‌ഫുൾ കോളും കാണിക്കുന്നു. Stateless vs Stateful Conversations -*സ്ഥിതിവിശേഷമില്ലാത്ത (സ്വതന്ത്ര കോൾ) കൂടാതെ, നിലനിർ‍ത്തപെട്ട (കോൺടെക്സ്റ്റ് അറിയുക) സംഭാഷണങ്ങൾ തമ്മിലുള്ള വ്യത്യാസം* +*സ്റ്റേറ്റ്‌ലെസ് (സ്വതന്ത്ര കോളുകൾ) ഒപ്പം സ്റ്റേറ്റ്‌ഫുൾ (സന്ദർഭമറിയുന്ന) സംവാദങ്ങളുടെ വ്യത്യാസം* -## ടോക്കനുകള്‍ മനസ്സിലാക്കല്‍ +## ടോക്കണുകൾ മനസിലാക്കുക -സംഭാഷണത്തിലേക്ക് കയറുന്നതിന് മുമ്പ്, ടോക്കനുകൾ മനസ്സിലാക്കേണ്ടതാണ് — ഭാഷാ മോഡലുകൾ ടൃദക്ഷണം ചെയ്യുന്ന അടിസ്ഥാന എഴുത്തു ഘടകങ്ങൾ: +സംവാദങ്ങളിലേക്ക് പ്രവേശിക്കുന്ന മുൻപ്, ടോക്കണുകൾ മനസിലാക്കുന്നു - ഭാഷാമാതൃകകൾ ഇന്ത്യെക്‌സ് ചെയ്യുന്ന അടിസ്ഥാന യൂണിറ്റുകൾ: Token Explanation -*എന്തുകൊണ്ട് ഒരു പദം ടോക്കനുകളായി വിഭജിക്കപ്പെടുന്നു - "I love AI!" അതായത് 4 വ്യത്യസ്ത പ്രോസസ്സിംഗ് ഘടകങ്ങൾ* +*വാചകം എങ്ങനെ ടോക്കണുകളായി വിഭജിക്കപ്പെടുന്നു - "I love AI!" എങ്കിൽ 4 സ്വതന്ത്ര പ്രോസസ്സ് യൂണിറ്റുകളായി* -ടോക്കനുകൾ എഐ മോഡലുകൾക്ക് എഴുത്ത് അളക്കാനും പ്രോസസ്സുചെയ്യാനും സഹായിക്കുന്നു. വാക്കുകൾ, വിരാമচിഹ്നങ്ങൾ, ഇടവേളകളും ടോക്കനുകൾ ആകാം. നിങ്ങളുടെ മോഡലിന് ഒരേസമയം എത്രടോക്കനുകൾ പ്രോസസ്സ് ചെയ്യാമെന്നതിനുള്ള പരിധി ഉണ്ട് (GPT-5.2-ന് 400,000, അതിൽ 272,000 ഇൻപുട്ട് ടോക്കനുകൾക്കും 128,000 ഔട്ട്‌പുട്ട് ടോക്കനുകൾക്കുമാണ്). ടോക്കനുകൾ മനസ്സിലാക്കുന്നത് സംഭാഷണ ദൈര്‍ഘ്യവും ചെലവും നിയന്ത്രിക്കാന്‍ സഹായിക്കുന്നു. +ടോക്കണുകൾ എങ്ങനെ AI മാതൃകകൾ വാചകം അളക്കും, പ്രോസസ് ചെയ്യുമെന്നും എന്നതു Tomato. പദങ്ങൾ, വ്യാകരണരൂപങ്ങൾ, സ്ഥലങ്ങൾ പോലും ടോക്കണുകൾ ആകാം. മോഡലിന് ഒരാഴ്ചയിൽ എത്ര ടോക്കണുകൾ കൈകാര്യം ചെയ്യാമെന്ന് പരിധി ഉണ്ട് (GPT-5.2-നായി 400,000, എന്നാൽ ഇൻപുട്ട് ടോക്കണുകൾ 272,000 വരെ, ഔട്ട്പുട്ട് ടോക്കണുകൾ 128,000 വരെ). ടോക്കണുകൾ മനസിലാക്കുന്നത് സംവാദം നീളം‌, ചെലവ് എന്നിവ നിയന്ത്രിക്കാൻ സഹായിക്കും. ## മെമ്മറി എങ്ങനെ പ്രവർത്തിക്കുന്നു -ചാറ്റ് മെമ്മറി സ്ഥിതിവിശേഷ പ്രശ്നം പരിഹരിക്കുന്നു, സംഭാഷണ ചരിത്രം നിലനിർത്തുന്നു. മോഡലിലേക്ക് നിങ്ങളുടെ അഭ്യർത്ഥന അയയ്ക്കുന്നതിന് മുമ്പ് ഫ്രെയിംവർക്ക് അനുയോജ്യമായ മുൻ സന്ദേശങ്ങൾ ചേർക്കുന്നു. നിങ്ങൾ "എന്റെ പേര് എന്ത്?" എന്ന് ചോദിക്കുമ്പോൾ, സിസ്റ്റം യथാർത്ഥത്തിൽ മുഴുവൻ സംഭാഷണ ചരിത്രം അയയ്ക്കുന്നു, മോഡലിന് നിങ്ങൾ മുമ്പ് "എന്റെ പേര് ജോൺ ആണ്" എന്നു പറഞ്ഞതാണെന്ന് കാണാൻ കഴിയുന്നു. +ചാറ്റ് മെമ്മറി സ്റ്റേറ്റ്‌ലെസ് പ്രശ്നം പരിഹരിക്കുന്നു, ചാറ്റ് ചരിത്രം നിലനിർത്തുന്നു. മോഡലിന് അഭ്യർത്ഥനയ भेजുന്നതിന് മുൻപ്, ഫ്‌രെയിംവർക്ക് ആവശ്യമായ പഴയ സന്ദേശങ്ങൾ ചേർക്കുന്നു. നിങ്ങൾ "എന്റെ പേര് ജോൺ ആണ്" എന്നു പറഞ്ഞത് മോഡൽ കണ്ടിരിക്കുന്നത് ഉറപ്പാക്കുന്നു, "എന്റെ പേര് എന്താണ്?" എന്ന് ചോദിക്കുമ്പോൾ. -LangChain4j മെമ്മറി ഇൻപ്ലിമെന്റേഷൻസ് സ്വയം കൈകാര്യം ചെയ്യുന്നു. നിങ്ങൾ എത്ര സന്ദേശങ്ങൾ സൂക്ഷിക്കാമെന്ന് തിരഞ്ഞെടുക്കുന്നു, ഫ്രെയിംവർക്ക് കോൺടെക്സ്റ്റ് വിൻഡോ നിയന്ത്രിക്കുന്നു. താഴെയുള്ള ചിത്രത്തിൽ MessageWindowChatMemory എങ്ങനെ അടുത്തിടെ വന്ന സന്ദേശങ്ങളുടെ സ്ലൈഡിംഗ് വിൻഡോ നിലനിർത്തുന്നു എന്ന് കാണുന്നു. +LangChain4j ഓട്ടോമാറ്റിക്കായി ഇതു കൈകാര്യം ചെയ്യുന്ന മെമ്മറി ഇംപ്ലിമെന്റേഷനുകൾ നൽകുന്നു. നിങ്ങൾ എത്ര സന്ദേശങ്ങൾ നിലനിര്‍ത്തണമെന്ന് തിരഞ്ഞെടുക്കാം, ഫ്രെയിംവർക്ക് കോൺടെക്സ്‌റ്റ് വിൻഡോ നിയന്ത്രിക്കുന്നു. താഴെയുള്ള ചിത്രം MessageWindowChatMemory എങ്ങനെ അടുത്ത സന്ദേശങ്ങൾ ഒരുങ്ങിയ വിൻഡോയിൽ നിലനിർത്തുന്നു എന്നത് കാണിക്കുന്നു. Memory Window Concept -*MessageWindowChatMemory അടുത്തിടെ വന്ന സന്ദേശങ്ങളുടെ സ്ലൈഡിംഗ് വിൻഡോ നിലനിർത്തുന്നു, പഴയവ ത്വരിതമായി ഒഴിവാക്കുന്നു* +*MessageWindowChatMemory അടുത്ത സന്ദേശങ്ങളുടെ സ്ലൈഡിംഗ് വിൻഡോ സംരക്ഷിക്കുന്നു, പഴയ സന്ദേശങ്ങൾ സ്വയം ഒഴിവാക്കുന്നു* ## ഇത് LangChain4j എങ്ങനെ ഉപയോഗിക്കുന്നു -ഈ മൊഡ്യൂൾ ക്വിക്ക് സ്റ്റാർട്ട് വിപുലീകരിച്ച് Spring Boot ഒരുമിച്ച് സംഭാഷണ മെമ്മറി ചേർക്കുന്നു. ഭാഗങ്ങൾ ഇങ്ങനെ ബന്ധിക്കുന്നു: +ഈ മോട്യൂൾ സ്പ്രിങ് ബൂട്ട് സംയുക്തമാക്കി, സംവാദ മെമ്മറി ചേർത്തിരിക്കുന്നു. ചാരിതാർത്ഥ്യത ഇപ്രകാരമാണ്: -**ടെ depends ഏൻസി):** രണ്ട് LangChain4j ലൈബ്രറികൾ ചേർക്കുക: +**ആവശ്യങ്ങൾ** - രണ്ട് LangChain4j ലൈബ്രറികൾ ചേർക്കുക: ```xml @@ -94,7 +94,7 @@ LangChain4j മെമ്മറി ഇൻപ്ലിമെന്റേഷൻസ ``` -**ചാറ്റ് മോഡല്‍:** Azure OpenAI ഒരു സ്പ്രിംഗ് ബീന് ആയി ക്രമീകരിക്കുക ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**ചാറ്റ് മോഡൽ** - Azure OpenAI സ്പ്രിങ് ബീൻ ആയി ക്രമീകരിക്കുക ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -ബിൽഡർ `azd up` സെറ്റിംഗ് ചെയ്ത പൊരիպി environment variables-ലുള്ള ക്രഡന്‍ഷ്യലുകൾ വായിക്കുന്നു. Azure OpenAI ക്ലയന്റ് Azure എന്റ്പോയിന്റുമായി പ്രവർത്തിക്കാൻ `baseUrl` സജ്ജീകരിക്കുന്നു. +ബിൽഡർ `azd up` വഴി സജ്ജീകരിച്ച അന്തരീക്ഷ വ്യത്യാസങ്ങളിൽ നിന്നും ക്രെഡൻഷ്യലുകൾ വായിക്കുന്നു. `baseUrl` നിങ്ങളുടെ Azure എന്റ്പോയിന്റിലേക്ക് സജ്ജീകരിക്കുന്നത് OpenAI ക്ലയന്റ് Azure OpenAI-വുമായും പ്രവർത്തനക്ഷമമാക്കുന്നു. -**സംഭാഷണ മെമ്മറി:** MessageWindowChatMemory ഉപയോഗിച്ച് ചാറ്റ് ചരിത്രം ട്രാക്ക് ചെയ്യുക ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**സംവാദ മെമ്മറി** - MessageWindowChatMemory നിലവാരം ഉപയോഗിച്ച് ചാറ്റ് ചരിത്രം പിന്തുടരണു് ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,201 +124,207 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` ഉപയോഗിച്ച് അവസാന 10 സന്ദേശങ്ങൾ സൂക്ഷിക്കുന്ന മെമ്മറി സൃഷ്ടിക്കുക. Typed wrappers ഉപയോഗിച്ച് ഉപയോക്താവിന്റെയും AI-യുടെ സന്ദേശങ്ങൾ ചേർക്കുക: `UserMessage.from(text)` , `AiMessage.from(text)`. `memory.messages()` വഴി ചരിത്രം ലഭിക്കുകയും മോഡലിന് അയയ്ക്കുകയും ചെയ്യുക. സേവനം ഓരോ സംഭാഷണ ID-യ്ക്കും വ്യത്യസ്ത മെമ്മറി ഉദാഹരണങ്ങൾ സൂക്ഷിക്കുന്നു, അതിനാൽ ഒരേ സമയം നിരവധി ഉപയോക്താക്കൾ ചാറ്റ് ചെയ്യാം. +`withMaxMessages(10)` ഉപയോഗിച്ച് അവസാന 10 സന്ദേശങ്ങൾ സൂക്ഷിക്കാൻ മെമ്മറി സൃഷ്‌ടിക്കുക. Typed വ്രാപ്പറുകൾ ഉപയോഗിച്ച് യൂസർ, AI സന്ദേശങ്ങൾ ചേർക്കുക: `UserMessage.from(text)`, `AiMessage.from(text)`. `memory.messages()` വഴി ചരിത്രം എടുക്കുകയും മോഡലിലേക്ക് അയയ്ക്കുകയും ചെയ്യുക. സർവീസ് സംവാദം ID-പ്രകാരം പ്ര്യംക്രമം മെമ്മറി സൂക്ഷിക്കുന്നു, ഒരേ സമയം ബഹുഉപയോക്താക്കൾ ചാറ്റ് ചെയ്യാൻ അനുവദിക്കുന്നു. -> **🤖 GitHub Copilot Chat ഉപയോഗിച്ച് പരീക്ഷിക്കുക:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) തുറന്ന് ചോദിക്കുക: -> - "MessageWindowChatMemory വിൻഡോ പൂർണമായാൽ ഏത് സന്ദേശങ്ങൾ ഒഴിവാക്കുമെന്ന് എങ്ങനെ തീരുമാനിക്കുന്നു?" -> - "ഇൻ-മെമ്മറി പകരം ഡാറ്റാബേസ് ഉപയോഗിച്ച് കസ്റ്റം മെമ്മറി സംഭരണം എങ്ങനെ നടപ്പിലാക്കാം?" -> - "പഴയ സംഭാഷണ ചരിത്രം സംക്ഷിപ്തമാക്കാനായി സംഗ്രഹം ചേർക്കാൻ എങ്ങനെ ഇറക്കാമാ?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റിനൊപ്പം പരീക്ഷിക്കൂ:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) തുറന്ന് ചോദിക്കാം: +> - "MessageWindowChatMemory വിൻഡോ പൂർണ്ണമായാൽ ഏതാണ് സന്ദേശങ്ങൾ ഒഴിവാക്കുന്നത്?" +> - "സാവധി മെമ്മറി സ്റ്റോറേജ് ഡാറ്റാബേസിൽ നിന്നും നിർമ്മിക്കാമോ?" +> - "പഴയ സംവാദ ചരിത്രം സംഗ്രഹിക്കാൻ എങ്ങനെ ചേർക്കാം?" -സ്ഥിതിവിശേഷമില്ലാത്ത ചാറ്റ് എൻഡ്‌പോയിന്റ് മെമ്മറി ഉപയോഗിക്കുന്നില്ല - ക്വിക്ക് സ്റ്റാർട്ടിൽ പോലെ `chatModel.chat(prompt)` മാത്രം. നിലനിൽക്കുന്ന എൻഡ്‌പോയിന്റ് സന്ദേശങ്ങൾ മെമ്മറിയിലേക്ക് ചേർക്കുന്നു, ചരിത്രം എടുക്കുന്നു, കൂടാതെ ഓരോ അഭ്യർത്ഥനയോടും കൗൺടെക്സ്റ്റ് ചേര്‍ക്കുന്നു. മോഡൽ കൺഫിഗറേഷൻ സമാനമാണ്, പാറ്റേണുകള്‍വ്യത്യസ്തമാണ്. +സ്റ്റേറ്റ്‌ലെസ് ചാറ്റ് എൻഡ്‌പോയിന്റ് മെമ്മറി മുഴുവനും ഒഴിവാക്കുന്നു - `chatModel.chat(prompt)` വേഗം ആരംഭിക്കാൻ ഉള്ള രീതിയാണ്. സ്റ്റേറ്റ്‌ഫുൾ എൻഡ്‌പോയിന്റ് സന്ദേശങ്ങൾ മെമ്മറിയിൽ ചേർക്കുന്നു, ചരിത്രം തിരിച്ച് കൊണ്ടു വരുന്നു, ഓരോ അഭ്യർത്ഥനയ്ക്കും അത് ഉൾക്കൊള്ളുന്നു. ഒരു മോഡൽ ക്രമീകരണം, വ്യത്യസ്ത മാതൃകകൾ. -## Azure OpenAI ഇൻഫ്രാസ്ട്രക്ചർ വിന്യസിക്കുക +## Azure OpenAI ഇൻഫ്രാസ്ട്രക്ചർ വിന്യാസം -**ബാഷ്:** +**Bash:** ```bash cd 01-introduction -azd up # സബ്‌സ്‌ക്രിപ്ഷനും സ്ഥലവും തിരഞ്ഞെടുക്കുക (eastus2 ശിപാർശ ചെയ്യുന്നു) +azd up # സബ്സ്ക്രിപ്ഷനും സ്ഥലം (ഇസ്റ്റ്യൂഎസ്2 ശുപാർശ ചെയ്യുന്നു) തിരഞ്ഞെടുക്കുക ``` -**പവർഷെൽ:** +**PowerShell:** ```powershell cd 01-introduction -azd up # സബ്സ്ക്രിപ്ഷനും സ്ഥലം (പശ്ചിമus2 സിഫാരിസ്പെടുന്നു) തിരഞ്ഞെടുക്കുക +azd up # സബ്സ്ക്രിപ്ഷനും സ്ഥലവും തെരഞ്ഞെടുക്കുക (eastus2 ശുപാർശ ചെയ്യുന്നു) ``` -> **കുറിപ്പ്:** നിങ്ങൾക്ക് ടൈംഔട്ട്エറർ കിട്ടുകയാണെങ്കിൽ (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), സരളമായി വീണ്ടും `azd up` ഓടിക്കുക. Azure റിസോഴ്‌സുകൾ പിന്നിൽ ഇനിയും പ്രൊവൈസിന്ഗിൽ ആയിരിക്കാം, റിട്രൈ ചെയ്താൽ റിസോഴ്‌സുകൾ അവസാനാവസ്ഥയിലേക്കെത്തുമ്പോൾ വിന്യാസം പൂർണ്ണമാകും. + +> **ശ്രദ്ധിക്കുക:** റിസോഴ്സ് ടൈമൗട്ട് തെറ്റ് (RequestConflict: Cannot modify resource ... provisioning state is not terminal) അനുഭവപ്പെടുകയാണെങ്കിൽ, `azd up` വീണ്ടും പ്രവർത്തിപ്പിക്കുക. Azure റിസോഴ്സുകൾ പിന്നണിയിൽ തയാറാകുകയാണ് ആയതിനാൽ, രീ-ട്രൈ ചെയ്യുന്നത് വിന്യാസം പൂർത്തിയാക്കാൻ സഹായിക്കും. ഇത് ചെയ്യുന്നത്: -1. Azure OpenAI റിസോഴ്‌സ് GPT-5.2, text-embedding-3-small മോഡലുകളാൽ വിന്യാസിക്കുക -2. പ്രോജക്ട് റൂട്ടിൽ ക്രഡൻഷ്യലുകളോടെയുള്ള `.env` ഫയൽ സ്വയം ഉണ്ടാക്കുക -3. ആവശ്യമായ എല്ലാ എൻവയോൺമെന്റ് വേരിയബിളുകളും സജ്ജമാക്കുക +1. GPT-5.2, text-embedding-3-small മോഡലുകളോടെയുള്ള Azure OpenAI റിസോഴ്സ് വിന്യസിക്കുന്നു +2. അക്ഷരാര്‍ത്ഥത്തിൽ `.env` ഫയൽ സൃഷ്‌ടിക്കുന്നു, ക്രെഡൻഷ്യലോടെ +3. ആവശ്യമായ എല്ലാ എൻവയോൺമെന്റ് വ്യത്യാസങ്ങൾ ക്രമീകരിക്കുന്നു -**വിന്യാസ പ്രശ്നങ്ങളുണ്ടി?** [Infrastructure README](infra/README.md) കാണുക, സബ്ഡൊമെയിൻ പേരിന്റെ തർക്കങ്ങൾ, Azure പോർട്ടൽ വിന്യാസത്തിന്റെ മാനുവൽ ഘട്ടങ്ങൾ, മോഡൽ കോൺഫിഗറേഷൻ മാർഗ്ഗനിർദ്ദേശങ്ങൾ ഉൾപ്പെടെ വിശദമായി. +**വിന്യാസ പ്രശ്നങ്ങൾ ഉണ്ടെങ്കിൽ?** [ഇൻഫ്രാസ്ട്രക്ചർ README](infra/README.md)ൽ വിശദീകരണം, സബ്ഡൊമൈൻ നാമം സംഘർഷങ്ങൾ, മാനുവൽ Azure പോർട്ടൽ വിന്യാസം, മോഡൽ ക്രമീകരണ മാർഗ്ഗനിർദ്ദേശങ്ങൾ കാണുക. -**വിന്യാസം വിജയിച്ചതായി സ്ഥിരീകരിക്കുക:** +**വിന്യാസം വിജയമാണെന്ന് പരിശോധിക്കുക:** -**ബാഷ്:** +**Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, തുടങ്ങിയവ കാണിക്കേണ്ടതാണ്. +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY എന്നിവ കണ്ടിരിക്കണം. ``` -**പവർഷെൽ:** +**PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, മുതലായവ കാണിക്കണം. +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, എന്നിവ കാണിക്കേണ്ടത്. ``` -> **കുറിപ്പ്:** `azd up` കമാൻഡ് സ്വയം `.env` ഫയൽ ഉണ്ടാക്കുന്നു. ഇത് പിന്നീട് അപ്ഡേറ്റ് ചെയ്യേണ്ടി വന്നാൽ, `.env` ഫയൽ മാനുവലി എഡിറ്റ് ചെയ്യാം അല്ലെങ്കിൽ ഇത് വീണ്ടും ഉണ്ടാക്കാൻ താഴെ കാണിക്കുന്ന കമാൻഡ് ഉപയോഗിക്കാം: + +> **ശ്രദ്ധിക്കുക:** `azd up` കമാൻഡ് സ്വയം `.env` ഫയൽ സൃഷ്‌ടിക്കുന്നു. പിന്നീട് അപ്ഡേറ്റ് വേണമെങ്കിൽ, `.env` ഫയൽ കൈകാര്യം ചെയ്യാം അല്ലെങ്കിൽ വീണ്ടും: > -> **ബാഷ്:** +> **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` - > -> **പവർഷെൽ:** +> **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` -## പ്രയോഗം ലൊക്കലില്‍ ഓടിക്കുക -**വിന്യാസം സ്ഥിരീകരിക്കുക:** +## ആപ്ലിക്കേഷൻ ലോക്കലായി പ്രവർത്തിക്കുക + +**വിന്യാസം പരിശോധിക്കുക:** -Azure ക്രഡൻഷ്യലുകളുള്ള `.env` ഫയൽ റൂട്ട് ഡയറക്ടറിയിൽ ഉള്ളതായി ഉറപ്പാക്കുക. മോഡ്യൂൾ ഡയറക്ടറി (`01-introduction/`) ഉപയോഗിച്ച് ഇത് ഓടിക്കുക: +Azure ക്രെഡൻഷ്യലുകൾ അടങ്ങിയ `.env` ഫയൽ ഈ റൂട്ടിൽ ഉണ്ടെന്ന് ഉറപ്പാക്കുക. ഈ മോട്യൂള ഡയറക്ടറിയിൽ നിന്ന് (`01-introduction/`) ഇത് പ്രവർത്തിപ്പിക്കുക: -**ബാഷ്:** +**Bash:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്കണം ``` -**പവർഷെൽ:** +**PowerShell:** ```powershell Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്കണം ``` -**പ്രയോഗം ആരംഭിക്കുക:** -**ഓപ്‌ഷന്‍ 1: Spring Boot ഡാഷ്ബോർഡ് ഉപയോഗിച്ച് (VS Code ഉപയോഗിക്കുന്നവർക്ക് നിർദ്ദേശം)** +**ആപ്ലിക്കേഷനുകൾ തുടങ്ങുക:** -ഡെവ് കൺടെയ്‌നറിൽ Spring Boot ഡാഷ്‌ബോർഡ് എക്സ്റ്റൻഷൻ ഉൾപ്പെടുത്തിയിട്ടുണ്ട്, ഇത് എല്ലാ Spring Boot അപ്ലിക്കേഷനുകളും കാണാനും മാനേജുചെയ്യാനും ദൃശ്യ ഇന്റർഫേസ് നൽകുന്നു. അത് VS Code വലത് വശത്തു ഉള്ള ആക്ടിവിറ്റി ബാറിൽ(Spring Boot ഐക്കൺ കാണുക) കാണാനാകും. +**വികല്പം 1: Spring Boot ഡാഷ്ബോർഡ് ഉപയോഗിക്കുക (VS Code ഉപയോക്താക്കൾക്ക് ശുപാർശ)** -Spring Boot ഡാഷ്ബോർഡ് വഴി, നിങ്ങൾക്ക്: -- വർക്ക്സ്പേസിലെ എല്ലാ Spring Boot അപ്ലിക്കേഷനുകളും കാണാം -- ഒറ്റ ക്ലിക്കിൽ ആരംഭിക്കാനും നിർത്താനും കഴിയും -- അപ്ലിക്കേഷൻ ലോഗുകൾ യാഥാസ്ഥിതികമായി കാണാം -- അപ്ലിക്കേഷൻ നില നിരീക്ഷിക്കാം +ഡെവ് കണ്ടെയ്‌നറിൽ Spring Boot ഡാഷ്ബോർഡ് പകുതി ഉൾപ്പെടുത്തിയിട്ടുണ്ട്, ഇത് എല്ലാ Spring Boot ആപ്പ്ലിക്കേഷനുകളും ദൃശ്യമായി നിയന്ത്രിക്കാൻ സഹായിക്കുന്നു. ഇത് VS Code ൽ ഇടതുവശത്ത് പ്രവർത്തന ബാറിൽ (Spring Boot ചിഹ്നം നോക്കുക) കാണാം. -"introduction" ന്റെ പക്കൽ പ്ലേ ബട്ടൺ ക്ലിക്ക് ചെയ്താല്‍ ഈ മൊഡ്യൂൾ തുടങ്ങും, അല്ലെങ്കിൽ എല്ലാം ഒരുമിച്ച് ആരംഭിക്കാം. +ഡാഷ്ബോർഡിൽ നിന്ന്: +- പ്രവർത്തന സ്ഥലത്തു ലഭ്യമായ എല്ലാ Spring Boot ആപ്പ്ലിക്കേഷനുകൾ കാണാം +- ഒറ്റ ക്ലിക്കിൽ ആപ്പുകൾ സ്റ്റാർട്ട്/സ്റ്റോപ്പ് ചെയ്യാം +- ആപ്പ്ലിക്കേഷൻ ലോഗുകൾ സത്യകാലം കാണാം +- ആപ്പ്ലിക്കേഷൻ നില നിരീക്ഷിക്കാം + +"introduction" മുൻപിൽ പ്ലേ ബട്ടൺ അമർത്തി ഈ മോട്യൂൾ ആരംഭിക്കാം, അല്ലെങ്കിൽ എല്ലാ മോട്യൂളുകളും ഒരുമിച്ച് തുടങ്ങുക. Spring Boot Dashboard -*VS Code-ലെ Spring Boot ഡാഷ്ബോർഡ് — എല്ലാ മൊഡ്യൂളുകളും ഒരിടത്ത് നിന്ന് ആരംഭിക്കാം, നിർത്താം, നിരീക്ഷിക്കാം* +*VS Code ലെ Spring Boot ഡാഷ്ബോർഡ് — എല്ലാ മോട്യൂളുകളും ഒരേസമയം ആരംഭിക്കുക, നിർത്തുക, നിരീക്ഷിക്കുക* -**ഓപ്‌ഷന്‍ 2: ഷെല്ല് സ്‌ക്രിപ്റ്റുകൾ ഉപയോഗിച്ച്** +**വികല്പം 2: ഷെൽ സ്ക്രിപ്റ്റുകൾ ഉപയോഗിക്കുക** -എല്ലാ വെബ് ആപ്ലിക്കേഷനുകളും ആരംഭിക്കുക (മൊഡ്യൂള്‍ 01-04): +എല്ലാ വെബ് ആപ്പ്ലിക്കേഷനുകളും (മോട്യൂളുകൾ 01-04) ആരംഭിക്കുക: -**ബാഷ്:** +**Bash:** ```bash -cd .. # റൂട്ടി ഡയറക്ടറിയിൽ നിന്നുള്ളത് +cd .. # റൂട്ട് ഡിറക്ടറിയിൽ നിന്ന് ./start-all.sh ``` -**പവർഷെൽ:** +**PowerShell:** ```powershell cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്നാണ് .\start-all.ps1 ``` -അല്ലെങ്കിൽ ഈ മൊഡ്യൂൾ മാത്രം ആരംഭിക്കുക: -**ബാഷ്:** +അല്ലെങ്കിൽ ഈ മോട്യൂളിൽ മാത്രം ആരംഭിക്കുക: + +**Bash:** ```bash cd 01-introduction ./start.sh ``` -**പവർഷെൽ:** +**PowerShell:** ```powershell cd 01-introduction .\start.ps1 ``` -രണ്ട് സ്‌ക്രിപ്റ്റുകളും റൂട്ടിലെ `.env` ഫയലിൽ നിന്നുള്ള എൻവയോൺമെന്റ് വേരിയബിളുകൾ ലോഡു ചെയ്യും, ജയേഴ്സ് ഇല്ലെങ്കിൽ നിർമിക്കും. -> **കുറിപ്പ്:** നിങ്ങൾക്ക് തുടങ്ങുന്നതിനു മുൻപ് എല്ലാ മൊഡ്യൂളുകളും മാനുവലി നിർമ്മിക്കണമെന്ന് ഇഷ്ടമെങ്കിൽ: +രണ്ടും റൂട്ടിലെ `.env` ഫയൽ നിന്ന് എൻവയോൺമെന്റ് വ്യത്യാസങ്ങൾ സ്വയം ലോഡ് ചെയ്യും, JAR ഫയലുകൾ ഇല്ലെങ്കിൽ ബിൽഡ് ചെയ്യും. + +> **ശ്രദ്ധിക്കുക:** തുടങ്ങുന്നതിന് മുന്നേല്ലാം മോട്യൂളുകളും കൈകാര്യം ചെയ്യാൻ ആഗ്രഹിക്കുന്നവർക്ക്: > -> **ബാഷ്:** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - > -> **പവർഷെൽ:** +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -ബ്രൗസറിൽ http://localhost:8080 തുറക്കുക. -**ഒപ്പമാക്കാൻ:** +http://localhost:8080 ബ്രൗസറിൽ തുറക്കുക. + +**നിർത്താൻ:** -**ബാഷ്:** +**Bash:** ```bash -./stop.sh # ഈ മോഡ്യൂൾ മാത്രം -# അല്ലെങ്കിൽ -cd .. && ./stop-all.sh # എല്ലാ മോഡ്യൂളുകളും +./stop.sh # ഈ മൊഡ്യൂളിനുള്ളില്‍ മാത്രം +# അല്ലെങ്കില്‍ +cd .. && ./stop-all.sh # എല്ലാ മൊഡ്യൂളുകളും ``` -**പവർഷെൽ:** +**PowerShell:** ```powershell -.\stop.ps1 # ഈ മോഡ്യൂള്‍ മാത്രം -# അല്ലെങ്കില്‍ +.\stop.ps1 # ഈ മോഡ്യൂൾ മാത്രം +# അല്ലെങ്കിൽ cd ..; .\stop-all.ps1 # എല്ലാ മോഡ്യൂളുകളും ``` -## പ്രയോഗം ഉപയോഗിക്കല്‍ -ഈ അപ്ലിക്കേഷൻ വെബ് ഇന്റർഫേസോടെ രണ്ട് ചാറ്റ് ഇംപ്ലിമെന്റേഷനുകൾ പാർശ്വം-പാർശ്വം നൽകി. +## ആപ്ലിക്കേഷൻ ഉപയോഗിക്കൽ + +ഇത് രണ്ട് ചാറ്റ് നിർവഹണങ്ങൾന്തിരുവതാരം വെബ് ഇന്റർഫേസ് നിങ്ങൾക്കു് നൽകുന്നു. Application Home Screen -*ഡാഷ്ബോർഡ്, സിംപിൾ ചാറ്റ് (സ്ഥിതിവിശേഷമില്ലാത്ത) ഒപ്പം സംഭാഷണ ചാറ്റ് (സ്ഥിതിവൈശേഷ്യമുള്ള) ഓപ്ഷനുകൾ കാണിക്കുന്നു* +*ഡാഷ്ബോർഡ് - ലളിതമായ ചാറ്റ് (സ്റ്റേറ്റ്‌ലെസ്), സംവാദ ചാറ്റ് (സ്റ്റേറ്റ്‌ഫുൾ) തിരഞ്ഞെടുപ്പുകൾ* -###स्थित invokevirtual ചാറ്റ് (ഇടത് പാനല്‍) +### സ്റ്റേറ്റ്‌ലെസ് چാറ്റ് (ഇടത് പാനൽ) -മുൻപേ പരീക്ഷിക്കുക. "എന്റെ പേര് ജോൺ ആണ്" എന്ന് ചോദിച്ച് തുടർന്ന് "എന്റെ പേര് എന്ത്?" എന്നും ചോദിക്കൂ. മോഡൽ ഓർമ്മിക്കുന്നില്ല, കാരണം ഓരോ സന്ദേശവും സ്വതന്ത്രമാണ്. ഇത് അടിസ്ഥാന ഭാഷാ മോഡല്‍ സംയോജനത്തിലെ പ്രധാന പ്രശ്നം കാണിക്കുന്നു - പരമ്പരയായ കോൺടെക്സ്റ്റ് ഇല്ല. +ആദ്യം ഇതു് പരീക്ഷിക്കുക. "എന്റെ പേര് ജോൺ ആണ്" എന്നു പറയുക, ഉടനടി "എന്റെ പേര് എന്താണ്?" എന്നു ചോദിക്കുക. മോഡൽ ഓർമ്മിക്കില്ല, കാരണം ഓരോ സന്ദേശവും സ്വതന്ത്രമാണ്. അടിസ്ഥാന ഭാഷാ മാതൃക സംയോജനത്തിന് ഈ കാര്യം പ്രധാന പ്രശ്നമാണ് - സംവാദ ദുര്‍ഗമ്യം. Stateless Chat Demo -*എഐ മുമ്പത്തെ സന്ദേശത്തിൽ നിന്നുള്ള നിങ്ങളുടെ പേര് ഓർക്കുന്നില്ല* +*AI കഴിഞ്ഞ സന്ദേശത്തിൽ നിന്ന് നിങ്ങളുടെ പേര് ഓർമ്മിക്കുന്നില്ല* -### Stateful Chat (വലത് പാനൽ) +### സ്റ്റേറ്റ്‌ഫുൾ ചാറ്റ് (വലതു പാനൽ) -ഇപ്പോൾ ഇതിലേയ്ക്ക് അതേ ക്രമം പരീക്ഷിക്കുക. "എന്റെ പേര് ജോൺ ആണ്" എന്ന് ചോദിച്ച് തുടർന്ന് "എന്റെ പേര് എന്ത്?" ചോദിച്ചാൽ മോഡൽ അത് ഓർക്കും. വ്യത്യാസം MessageWindowChatMemory ആണെന്ന് മനസ്സിലാക്കുക - അത് സംഭാഷണ ചരിത്രം നിലനിർത്ത്, ഓരോ അഭ്യർത്ഥനയോടും അതു ചേർക്കുന്നു. ഉത്പാദന സംഭാഷണ എഐ ഇതിൽ പ്രവർത്തിക്കുന്നു. +ഇപ്പോഴിതേ പാറ്റേൺ ഇവിടെ പരീക്ഷിക്കുക. "എന്റെ പേര് ജോൺ ആണ്" എന്നു പറയുക, പിന്നെ "എന്റെ പേര് എന്താണ്?" ഇപ്പൊഴിതു ഓർമ്മിക്കുന്നു. വ്യത്യാസം MessageWindowChatMemory യാണ് - ഇത് സംവാദ ചരിത്രം നിലനിർത്തുന്നു, ഓരോ അഭ്യർത്ഥനയോടും അതു സമീപിക്കുന്നു. ഉൽപ്പാദന സംവാദ AI ഇതുപോലെയാണ് പ്രവർത്തിക്കുന്നത്. Stateful Chat Demo -*എഐ ഇടത്തിലുമുതൽ നിങ്ങളുടെ പേര് ഓർക്കുന്നു* +*AI സംഭാഷണത്തിൽ മുമ്പത്തെ സന്ദർഭത്തിൽ നിന്നു നിങ്ങളുടെ പേര് ഓർമ്മിക്കുന്നു* -രണ്ട് പാനലുകളും ഒരേ GPT-5.2 മോഡൽ ഉപയോഗിക്കുന്നു. വ്യത്യാസം മെമ്മറിയിലായിരുന്നു. ഇത് നിങ്ങളുടെ അപ്ലിക്കേഷനിലേക്ക് മെമ്മറി കൊണ്ടുവരുന്നതെന്തെന്നത് വ്യക്തമായി കാണിക്കുന്നു, അതും യഥാർത്ഥ ഉപയോഗത്തിനായി അത്യാവശ്യമാണ്. +രണ്ടു പാനലുകളും ഒരേ GPT-5.2 മോഡൽ ഉപയോഗിക്കുന്നു. ഒരു വ്യത്യാസം മെമ്മറിയാണ്. ഇത് മെമ്മറി നിങ്ങളുടെ ആപ്പിലേക്ക് എന്തു കൊണ്ടുവരിക, യഥാർത്ഥ ഉപയോഗത്തിന് അതെന്തിനെന്ന് വ്യക്തമാക്കുന്നു. -## അടുത്ത പൊരുളുകൾ +## അടുത്ത ഘട്ടങ്ങൾ -**അടുത്ത മൊഡ്യൂള്‍: [02-prompt-engineering - GPT-5.2 ഉപയോഗിച്ച് പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ്](../02-prompt-engineering/README.md)** +**അടുത്ത മോട്യൂൾ:** [02-prompt-engineering - GPT-5.2-യോടെ പ്രോംപ്റ്റ് എൻജിനീയറിംഗ്](../02-prompt-engineering/README.md) --- -**നാവിഗേഷൻ:** [← മുൻ: Module 00 - Quick Start](../00-quick-start/README.md) | [പ്രധാനത്തിലേക്ക് മടങ്ങുക](../README.md) | [അടുത്തത്: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**നാവിഗേഷൻ:** [← മുഖ്യത്തിലേക്ക് തിരിച്ചുവരിക](../README.md) | [അടുത്തത്: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- -**വിമർശന കുറിപ്പ്**: -ഈ രേഖ AI പരിഭാഷ സേവനമായ [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ചു പരിഭാഷപ്പെടുത്തിയതാണ്. പരിപൂർണ്ണതയ്ക്കായി ഞങ്ങൾ ശ്രമിച്ചിട്ടുണ്ടെങ്കിലും, ഓട്ടോമേറ്റഡ് പരിഭാഷയിൽ പിശകുകൾ അല്ലെങ്കിൽ അപാകതകൾ ഉണ്ടായിരിക്കാമെന്ന കാര്യം ദയവായി മനസ്സിലാക്കുക. അതിന്റെ ദേശീയഭാഷയിലുള്ള 원문 ദസ്താവേജാണ് കൃത്യമായ ഉറവിടമെന്ന് കണക്കാക്കേണ്ടത് മികച്ചതാണ്. നിർണായക വിവരങ്ങൾക്ക് പ്രൊഫഷണൽ മനുഷ്യപരിഭാഷ ശുപാർശ ചെയ്യുന്നു. ഈ പരിഭാഷ ഉപയോഗിച്ച് ഉണ്ടായേക്കാവുന്ന തെറ്റിദ്ധാരണകളോ അർത്ഥം തെറ്റിവെച്ചതിലോ ഞങ്ങൾ ഉത്തരവാദികളല്ല. +**അറിയിപ്പ്**: +ഈ രേഖ AI പരിഭാഷാ സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് പരിഭാഷപ്പെടുത്തിയതാണ്. ഞങ്ങൾ കൃത്യതയ്ക്കായി ശ്രമിക്കുന്നുവെങ്കിലും, ഓട്ടോമേറ്റഡ് പരിഭാഷകളിൽ പിഴവുകൾ അല്ലെങ്കിൽ തെറ്റായ വിവരങ്ങൾ ഉണ്ടാകാൻ സാധ്യതയുണ്ട്. അതിന്റെ സ്വാഭാവിക ഭാഷയിലുള്ള അസൽ രേഖയാണ് പ്രാമാണികമായ ഉറവിടമായി പരിഗണിക്കേണ്ടത്. നിർണായകമായ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ പരിഭാഷ ശുപാർശ ചെയ്യുന്നു. ഈ പരിഭാഷ ഉപയോഗിച്ച് ഉണ്ടാകുന്ന തെറ്റിദ്ധാരണകൾ അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾക്കായി ഞങ്ങൾ ഉത്തരവാദികളല്ല. \ No newline at end of file diff --git a/translations/ml/02-prompt-engineering/README.md b/translations/ml/02-prompt-engineering/README.md index 708b293de..7dd9a953c 100644 --- a/translations/ml/02-prompt-engineering/README.md +++ b/translations/ml/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Module 02: GPT-5.2 ഉപയോഗിച്ച് പ്രോംപ്‌ട്വേർക്ക് എൻജിനീയറിങ് - -## ഉള്ളടക്ക പട്ടിക - -- [വീഡിയോ വാക്ക്‌ത്രൂ](../../../02-prompt-engineering) -- [നിങ്ങൾ പഠിക്കാനിരിക്കുന്നതെന്ത്](../../../02-prompt-engineering) -- [ആവശ്യമായ മുൻ‌പരിചയം](../../../02-prompt-engineering) -- [പ്രോംപ്‌ട്വേർക്ക് എൻജിനീയറിങ് മനസിലാക്കുക](../../../02-prompt-engineering) -- [പ്രോംപ്‌ട്വേർക് എൻജിനീയറിങിന്റെ അടിസ്ഥാനങ്ങൾ](../../../02-prompt-engineering) - - [സീറോ-ഷോട്ട് പ്രോംപ്‌ടിംഗ്](../../../02-prompt-engineering) - - [ഫ്യൂ-ഷോട്ട് പ്രോംപ്‌ടിംഗ്](../../../02-prompt-engineering) - - [ചെയിൻ ഓഫ് തോട്ട്](../../../02-prompt-engineering) - - [റോൾ-ബേസ്‌ഡ് പ്രോംപ്‌ടിംഗ്](../../../02-prompt-engineering) - - [പ്രോംപ്‌റ്റ് ടെംപ്ലേറ്റുകൾ](../../../02-prompt-engineering) -- [ഉയർന്ന തലത്തിലുള്ള പാറ്റേൺസ്](../../../02-prompt-engineering) -- [അപ്ലിക്കേഷൻ പ്രവർത്തിപ്പിക്കുക](../../../02-prompt-engineering) -- [അപ്ലിക്കേഷൻ സ്‌ക്രീൻഷോട്ടുകൾ](../../../02-prompt-engineering) -- [പാറ്റേൺസ് പരിശോധിക്കുക](../../../02-prompt-engineering) - - [കുറഞ്ഞ-ഉത്സാഹവും ഉയർന്ന-ഉത്സാഹവും](../../../02-prompt-engineering) - - [ടാസ്‌ക് എക്സിക്യൂഷൻ (ടൂൾ പ്രീ എമ്പിൾസ്)](../../../02-prompt-engineering) - - [സ്വയം-പരിശോധന കോഡ്](../../../02-prompt-engineering) - - [സംരചിത വിശകലനം](../../../02-prompt-engineering) - - [മൾട്ടി-ടേൺ ചാറ്റ്](../../../02-prompt-engineering) - - [പടിയാനുസരിച്ച് വാദം](../../../02-prompt-engineering) - - [പരിമിത ഔട്ട്‌പുട്ട്](../../../02-prompt-engineering) -- [നിങ്ങൾക്ക് സത്യം പഠിക്കേണ്ടത്](../../../02-prompt-engineering) -- [അടുത്ത നടപടികൾ](../../../02-prompt-engineering) +# മോഡ്യൂൾ 02: GPT-5.2 ഉപയോഗിച്ച് പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗ് + +## വിഭവ സൂചിക + +- [വീഡിയോ വാക്ക്‌ത്രൂ](#വീഡിയോ-വാക്ക്‌ത്രൂ) +- [നീങ്ങൾ പഠിക്കുoennuൽത്](#നീങ്ങൾ-പഠിക്കുmennuൽത്) +- [അവശ്യ പ്രിവൃത്തി കാര്യങ്ങൾ](#അവശ്യ-പ്രിവൃത്തി-കാര്യങ്ങൾ) +- [പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗ് മനസ്സിലാക്കൽ](#പ്രോമ്പ്റ്റ്-എഞ്ചിനീയറിംഗ്-മനസ്സിലാക്കൽ) +- [പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗ് അടിസ്ഥാനങ്ങൾ](#പ്രോമ്പ്റ്റ്-എഞ്ചിനീയറിംഗ്-അടിസ്ഥാനങ്ങൾ) + - [സീറോ-ഷോട്ട് പ്രോമ്പ്റ്റിംഗ്](#സീറോ-ഷോട്ട്-പ്രോമ്പ്റ്റിംഗ്) + - [ഫ്യൂ-ഷോട്ട് പ്രോമ്പ്റ്റിംഗ്](#ഫ്യൂ-ഷോട്ട്-പ്രോമ്പ്റ്റിംഗ്) + - [ചെയിൻ ഓഫ് തോട്ട്](#ചെയിൻ-ഓഫ്-തോട്ട്) + - [റോൾ-ബേസ് പ്രോമ്പ്റ്റിംഗ്](#റോൾ-ബേസ്-പ്രോമ്പ്റ്റിംഗ്) + - [പ്രോമ്പ്റ്റ് ടെംപ്ലേറ്റുകൾ](#പ്രോമ്പ്റ്റ്-ടെംപ്ലേറ്റുകൾ) +- [അഗ്രഗതമായ രീതികൾ](#അഗ്രഗതമായ-രീതികൾ) +- [ആപ്ലിക്കേഷൻ ഓടിക്കുക](#അപ്ലിക്കേഷൻ-പ്രവർത്തിപ്പിക്കുക) +- [ആപ്ലിക്കേഷൻ സ്ക്രീൻഷോട്ടുകൾ](#അപ്ലിക്കേഷൻ-സ്ക്രീൻഷോട്ടുകൾ) +- [രീതികൾ അന്വേഷിക്കൽ](#പാറ്റേണുകൾ-പരിശോധിക്കൽ) + - [കുറഞ്ഞും ഉയർന്നും ഉത്സാഹം](#ലോ-vs-ഹൈ-ഈജർനെസ്) + - [ടാസ്ക് എക്സിക്യൂഷൻ (ടൂൾ പ്രീഅംബ്ലുകൾ)](#ടാസ്‌ക്-എക്സിക്യൂഷൻ-ടൂൾ-പ്രീാംബിളുകൾ) + - [സ്വയം-പരിശോധന കോഡ്](#സ്വയം-പരാമർശിക്കുന്ന-കോഡ്) + - [ഘടനാപരമായ വിശകലനം](#ഘടനാഭാഗങ്ങൾ-വീക്ഷണം) + - [മൾട്ടി-ടേൺ ചാറ്റ്](#മൾട്ടി-ടേൺ-ചാറ്റ്) + - [പടി-പടി ചിന്തനം](#ഘട്ടം-ഘട്ടം-ചിന്തിച്ചുള്ള-പരിഹാരം) + - [നിയന്ത്രിത ഔട്ട്പുട്ട്](#നിയന്ത്രിത-ഔട്ട്പുട്ട്) +- [നീങ്ങൾ വാസ്തവത്തിൽ എന്ത് പഠിക്കുന്നു](#നിങ്ങൾ-യാഥാർത്ഥ്യത്തിൽ-പഠിക്കുന്നത്) +- [അടുത്ത ഘട്ടങ്ങൾ](#വരും-ഘട്ടങ്ങൾ) ## വീഡിയോ വാക്ക്‌ത്രൂ -ഈ മാഡ്യൂളിൽ ആരംഭിക്കാനുളള രീതികൾ വിശദീകരിക്കുന്ന ലൈവ്സെഷൻ കാണുക: +ഈ മോഡ്യൂളുമായി ആരംഭിക്കുന്നതിന് എങ്ങനെ എന്നതു വിശദീകരിക്കുന്ന ഈ ലൈവ് സെഷൻ കാണുക: Prompt Engineering with LangChain4j - Live Session -## നിങ്ങൾ പഠിക്കാനിരിക്കുന്നതെന്ത് +## നീങ്ങൾ പഠിക്കുmennuൽത് -ഈ ചിത്രരേഖ ഈ മാഡ്യൂളിൽ നിങ്ങൾ വികസിപ്പിക്കவேണ്ട പ്രധാന വിഷയങ്ങളും കഴിയലുകളും — പ്രോംപ്‌റ്റ് മികച്ച രീതിയിൽ രൂപപ്പെടുത്താനുള്ള സാങ്കേതിക വിദ്യകളുടെ ആരംഭത്തിൽ നിന്നും നിങ്ങൾ അനുസരിക്കേണ്ട പടി-പടി പ്രവൃത്തി പ്രക്രിയ വരെ — അവലോകനം നൽകുന്നു. +താഴെ കൊടുത്തിരിക്കുന്ന ചിത്ര പരാമർശം ഈ മോഡ്യൂളിൽ നിങ്ങൾ വികസിപ്പിക്കുക സാധ്യമായ പ്രധാന വിഷയങ്ങളും കഴിവുകളും - പ്രോമ്പ്റ്റ് മെച്ചപ്പെടുത്തലിനുള്ള സാങ്കേതികവിദ്യകളിൽ നിന്നുകൂടെ, നീങ്ങുന്ന പ്രവൃത്തി രീതി വരെ — ഒരു അവലോകനം നൽകുന്നു. What You'll Learn -മുമ്പത്തെ മാഡ്യൂളുകളിൽ, GitHub മോഡലുകളുമായുള്ള LangChain4j അടിസ്ഥാന ഇന്ററാക്ഷനുകൾ നിങ്ങൾ അന്വേഷിച്ചു, Azure OpenAI-യുമായി സംഭാഷണ എഐ സൃഷ്ടിക്കുന്ന ഇന്ററാക്ടീവ് മെമ്മറി കാണിച്ചു. ഇപ്പോൾ, നിങ്ങൾ എങ്ങനെ ചോദ്യങ്ങൾ ചോദിക്കണം — പ്രോംപ്‌റുകളും തന്നെ — എന്നതിലേയ്ക്ക് ദൃഷ്ടി കേന്ദ്രീകരിക്കുന്നു, Azure OpenAIയുടെ GPT-5.2 ഉപയോഗിച്ച്. നിങ്ങൾ രൂപപ്പെടുത്തുന്ന പ്രോംപ്‌റുകളുടെ ഘടന നിങ്ങളുടെ ലഭിക്കുന്ന മറുപടികളുടെ ഗുണനിലവാരത്തിൽ വലിയ സ്വാധീനം ചെലുത്തും. ഞങ്ങൾ അടിസ്ഥാന പ്രോംപ്‌ട്ടിംഗ് സാങ്കേതിക വിദ്യകൾ അവലോകനം ചെയ്ത് തുടക്കം കുറിച്ച്, പിന്നെ GPT-5.2-യുടെ കഴിവുകൾ പൂർണ്ണമായും ഉപയോഗപ്പെടുത്തുന്ന 8 പ്രഗത്ഭമായ പാറ്റേണുകളിൽ പ്രവേശിക്കുന്നു. +മുൻ മോഡ്യൂളിൽ, നിങ്ങൾ ഓർമ്മ ഉപയോഗിച്ച് Azure OpenAI യുമായി സംഭാഷണ AI എങ്ങനെ പ്രവർത്തിക്കുന്നത് കണ്ടു. ഇപ്പോൾ നാം ശ്രദ്ധ കേന്ദ്രീകരിക്കുന്നു നിങ്ങൾ ചോദ്യങ്ങൾ എങ്ങനെ ചോദിക്കുകയെന്നതിൽ — പ്രോമ്പ്റ്റുകൾ സ്വയം — Azure OpenAI യുടെ GPT-5.2 ഉപയോഗിച്ച്. നിങ്ങൾ നിർമ്മിക്കുന്ന പ്രോമ്പ്റ്റുകളെ ഘടിപ്പിക്കുന്ന രീതി ലഭിക്കുന്ന പത്രങ്ങളുടെ ഗുണമേന്മയിൽ ശക്തമായ വ്യത്യാസം ഉണ്ടാക്കുന്നു. നാം അടിസ്ഥാന പ്രോമ്പ്റ്റിംഗ് സാങ്കേതികവിദ്യകളുടെ അവലോകനത്തോടെ ആരംഭിക്കും, പിന്നെ GPT-5.2 യുടെ കഴിവുകൾ പൂർണ്ണമായി പ്രയോജനപ്പെടുത്തുന്ന എട്ട് അഗ്രഗതമായ രീതികളിലേക്ക് നീങ്ങും. -GPT-5.2 തിരഞ്ഞെടുക്കുന്നുണ്ടെങ്കിൽ കാരണം അത് ചിന്താഗതിയുടെ നിയന്ത്രണം പരിചയപ്പെടുത്തുന്നു — മോഡലിന് മറുപടി നൽകുന്നതിന് മുൻപ് എത്ര തോതിൽ ചിന്തിക്കണമെന്നും നിങ്ങൾ പറയാം. ഇത് വ്യത്യസ്ത പ്രോംപ്‌റ്റിംഗ് തന്ത്രങ്ങളെ കൂടുതൽ വ്യക്തമായി കാണിക്കുകയും ഓരോ സമീപനം എപ്പോൾ ഉപയോഗിക്കാമെന്നും മനസ്സിലാക്കാൻ സഹായിക്കുകയും ചെയ്യും. GitHub മോഡലുകളുമായി താരതമ്യപ്പെടുത്തുമ്പോൾ Azureന് GPT-5.2ക്കുള്ള കുറവ് നിരക്കു പരിധികളും ഉപയോഗപ്രദമാണ്. +Reasoning control എന്ന പുതിയ സവിശേഷത GPT-5.2 ൽ ഉൾപ്പെടുത്തിയതിനാൽ നാം ഈ മോഡ്യൂൾ അതുപയോഗിച്ച് പ്രവർത്തിക്കും - നിങ്ങൾ മോഡലിന് ഉത്തരമടയ്ക്കുന്നതിനു മുൻപ് എത്ര ചിന്തിക്കണമെന്ന് പറയാം. ഇതു വ്യത്യസ്ത പ്രോമ്പ്റ്റിംഗ് തന്ത്രങ്ങൾ കൂടുതൽ വ്യക്തമാണ് ആകുന്നു, പൂർത്തിയായി ഓരോ സമീപനവും എപ്പോൾ ഉപയോഗിക്കേണ്ടതാണെന്നും മനസ്സിലാക്കാൻ സഹായിക്കുന്നു. -## ആവശ്യമായ മുൻ‌പരിചയം +## അവശ്യ പ്രിവൃത്തി കാര്യങ്ങൾ -- മാഡ്യൂൾ 01 പൂര്‍ത്തിയായിട്ടുണ്ടാകണം (Azure OpenAI വിഭവങ്ങൾ വിന്യസിച്ചു) -- റൂട്ടിലെ `.env` ഫയൽ Azure ക്രെഡൻഷ്യലുകളോടെ (മാഡ്യൂൾ 01ലെ `azd up` ഉപയോഗിച്ച് സൃഷ്ടിച്ചത്) +- Module 01 പൂര്‍ത്തിയാക്കിയിട്ടുണ്ട് (Azure OpenAI റെസോഴ്‌സസ് വിന്യസിച്ചിരിക്കുന്നു) +- റൂട്ട് ഡയറക്ടറിയിൽ `.env` ഫയൽ ഉണ്ടാകണം Azure പ്രശസ്തീകരണ വിവരങ്ങളോടുകൂടെ (`azd up` ഉപയോഗിച്ച് Module 01 ൽ സൃഷ്‌ടിച്ചത്) -> **കുറിപ്പ്:** മാഡ്യൂൾ 01 പൂർത്തിയാക്കിയിട്ടില്ലെങ്കിൽ, അവിടെ നൽകിയ വിന്യാസ നിർദ്ദേശങ്ങൾ ആദ്യം പാലിക്കുക. +> **കുറിപ്പ്:** Module 01 പൂർത്തിയാക്കിയിട്ടില്ല എങ്കിൽ, ആദ്യം അവിടെ കൊടുത്ത വിന്യാസ നിർദ്ദേശങ്ങൾ പാലിക്കുക. -## പ്രോംപ്‌റ്റ്വേർക്ക് എൻജിനീയറിങ് മനസിലാക്കുക +## പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗ് മനസ്സിലാക്കൽ -പ്രോംപ്‌റ്റ്വേർക്ക് എൻജിനീയറിങ്ങിന്റെ മിത്തിനെക്കുറിച്ച് താഴെ കാണുന്ന താരതമ്യം വ്യക്തമായി പറയുന്നു - അഭ്യസ്തവിദ്യശൂന്യമുള്ള നിർദ്ദേശങ്ങളും സൂക്ഷ്മമായ നിർദ്ദേശങ്ങളും തമ്മിലുള്ള വ്യത്യാസം. +അത്യാവശ്യമായി, പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗ് എന്നത് എങ്ങനെ വ്യക്തമായ, മിതമായ നിർദ്ദേശങ്ങളും കൃത്യമായ നിർദ്ദേശങ്ങളും തമ്മിലുള്ള വ്യത്യാസമാണ് എന്ന് താഴെ പരാമർശിക്കുന്നു. What is Prompt Engineering? -പ്രോംപ്‌റ്റ് എൻജിനീയറിങ് ആവശ്യമുള്ള ഫലം സ്ഥിരമായി ലഭിക്കുന്നതിന് എങ്ങനെ ഇൻപുട്ട് ടെക്സ്റ്റ് രൂപകൽപ്പന ചെയ്യാമെന്നതാണ്. ഇത് വെറും ചോദ്യങ്ങൾ ചോദിക്കുന്നതല്ല; മോഡൽ നിങ്ങൾക്ക് എന്ത് ആവശ്യമാണ്, അത് എങ്ങനെ നൽകണമെന്ന് കൃത്യമായി മനസ്സിലാക്കുക എന്നതിലാണു കേന്ദ്രീകരിക്കുന്നത്. +പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗ് എന്നത് നിങ്ങൾക്കു വേണ്ട ফলങ്ങൾ സ്ഥിരമായി നൽകുന്ന ഇൻപുട്ട് ടെക്‌സ്‌റ്റ് രൂപകല്പന ചെയ്യുന്നതാണ്. ഇത് ചോദ്യങ്ങൾ ചോദിക്കുന്നതിൽ മാത്രമല്ല - മോഡൽ നന്നായി മനസ്സിലാക്കാൻ കൂടത്തോളം നൽകുന്നതും എങ്ങനെ നൽകണമെന്ന് ഘടിപ്പിക്കുന്നതും ആണ്. -നിങ്ങളുടെ ഉടമസ്ഥന് നിർദ്ദേശങ്ങൾ നൽകുന്നതുപോലെ ഇതിനെ കരുതുക. "ബഗ്ഗ് фикс്ചെയ്ക്കുക" എന്ന് പറയുന്നത് അർത്ഥരഹിതമാണ്. "UserService.java-യുടെ 45-ആം ലൈനിൽ നൾ ചെക്കിംഗ് ചേർത്ത് നൾ പോയിന്റർ എക്സെപ്ഷൻ പരിഹരിക്കുക" എന്നത് വളരെ വ്യക്തമാണ്. ഭാഷാ മോഡലും ഇതുപോലെ പ്രവർത്തിക്കുന്നു — വിശദതയും ഘടനയും പ്രധാനമാണ്. +ഇതിനെ ഒരു സഹപ്രവർത്തകനെ നിർദ്ദേശങ്ങൾ നൽകുന്നതായി കരുതുക. "ബഗ് പരിഹരിക്കുക" എന്നത് മിതമായതാണ്. "UserService.java ലെ 45-ത്തെ ചൂണ്ടുന്ന നൾ പാസ്സ് നിർത്തൽ ചേർത്ത് നൾ പോയിന്റർ എക്സ്ട്രക്‌ഷൻ പരിഹരിക്കുക" എന്നത് കൃത്യമാണ്. ഭാഷാ മോഡലുകളും ഇതുപോലെ പ്രവർത്തിക്കുന്നു - കൃത്യതയും ഘടനയും ചെറുതായി പ്രാധാന്യമുള്ളവയാണ്. -താഴെ കാണുന്ന ചിത്രം LangChain4j ഈ കണ്ടക്ഷനിൽ എങ്ങനെ ഇടംപിടിച്ചിരിക്കുന്നുവെന്നു കാണിക്കുന്നു — നിങ്ങളുടെ പ്രോംപ് പാറ്റേണുകൾ SystemMessage, UserMessage എന്ന ഘടകങ്ങളിലൂടെ മോഡലുമായി ബന്ധിപ്പിക്കുന്നു. +താഴെ നൽകിയിരിക്കുന്ന ചിത്രത്തില് LangChain4j ഇങ്ങനെ ഈ ചിത്രംക്കുള്ളിൽ എങ്ങനെയാണ് ഉൾപ്പെടുന്നത് — SystemMessage, UserMessage എന്ന ഘടകങ്ങളിലൂടെ നിങ്ങളുടെ പ്രോമ്പ്റ്റ് മാതൃകകൾ മോഡലുമായി ബന്ധിപ്പിക്കുന്നു. How LangChain4j Fits -LangChain4j അടിസ്ഥാന സൗകര്യം നൽകുന്നു — മോഡൽ കണക്ഷനുകൾ, മെമ്മറി, മെസേജ് ടൈപ്പുകൾ — എന്നാൽ പ്രോംപ് പാറ്റേണുകൾ അതിലൂടെ അയക്കുന്ന സൂക്ഷ്മരൂപത്തിലുള്ള ടെക്സ്റ്റുകളാണ്. പ്രധാന ഘടകങ്ങൾ `SystemMessage` ആണ് (എഐയുടെ പെരുമാറ്റവും പങ്കും നിർണ്ണയിക്കുക) കൂടാതെ `UserMessage` (നിങ്ങളുടെ യഥാർത്ഥ അഭ്യർത്ഥന കൈകൊള്ളുന്നൂ). +LangChain4j മോഡൽ ബന്ധങ്ങൾ, ഓർമ്മ, സന്ദേശ തരം എന്നിവയ്ക്ക് അടിസ്ഥാന സൗകര്യങ്ങൾ നിർമിക്കുന്നു — അതേസമയം, പ്രോമ്പ്റ്റ് മാതൃകകൾ എന്നാൽ ഈ അടിസ്ഥാന സൗകര്യത്തിലൂടെ നിങ്ങൾ അയക്കുന്ന കൃത്യമായി ഘടിപ്പിച്ച ടെക്സ്റ്റുകൾ മാത്രമാണ്. മുഖ്യ ഘടകങ്ങൾ SystemMessage (AI ന്റെ സ്വഭാവവും പാത്രവും സജ്ജമാക്കുന്നു) , UserMessage (നിങ്ങളുടെ യഥാർത്ഥ അഭ്യർത്ഥനയും) എന്നിവയാണ്. -## പ്രോംപ്‌റ്റ് എൻജിനീയറിങ് അടിസ്ഥാനങ്ങൾ +## പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗ് അടിസ്ഥാനങ്ങൾ -താഴെ കാണുന്ന അഞ്ച് പ്രധാന സാങ്കേതിക വിദ്യകൾ ഫലപ്രദമായ പ്രോംപ്‌റ്റ് എൻജിനീയറിങ്ങിന്റെ അടിസ്ഥാനം ആണ്. ഓരോന്നും ഭാഷാ മോഡലുകളുമായുള്ള സമ്പർക്കത്തിന്റെ വ്യത്യസ്തമുളള അംശങ്ങളെ പരിഗണിക്കുന്നു. +താഴെ കാണുന്ന അഞ്ച് പ്രധാന സാങ്കേതിക വിദ്യകൾ ഫലപ്രദമായ പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗിന് അടിസ്ഥാനം ആണ്. ഓരോന്നും ഭാഷാ മോഡലുകളുമായുള്ള ആശയവിനിമയത്തിന്റെ വ്യത്യസ്ത അസ്പക്റ്റിനെ നേരിടുന്നു. Five Prompt Engineering Patterns Overview -ഈ മാഡ്യൂളിലെ ഉയർന്ന പാറ്റേൺസിലേക്ക് കടക്കുന്നതിന് മുമ്പ്, അഞ്ചുമുള്ള അടിസ്ഥാന പ്രോംപ്‌ടിംഗ് സാങ്കേതിക വിദ്യകൾ അവലോകനം ചെയ്യാം. എല്ലാ പ്രോംപ്‌റ്റ് എൻജിനീയറുമാർക്കും അറിഞ്ഞിരിക്കേണ്ട നിർമ്മാണഘടകങ്ങളാണ് ഇവ. നിങ്ങൾ [ക്വിക് സ്റ്റാർട്ട് മാഡ്യൂൾ](../00-quick-start/README.md#2-prompt-patterns) പരിശ്രമിച്ചിട്ടുണ്ടെങ്കിൽ, ഇവ പ്രവർത്തനത്തിൽ നിങ്ങൾക്കു കാണാം — ഇവയുടെ ആശയ മാതൃക ഇതാണ്. +ഈ മോഡ്യൂളിലെ അഗ്രഗതമായ മാതൃകകളിലേക്ക് കടക്കുന്നതിനു മുമ്പ്, ഒന്നിച്ച് അഞ്ച് അടിസ്ഥാന പ്രോമ്പ്റ്റിംഗ് സാങ്കേതിക വിദ്യകൾ അവലോകനം ചെയ്യാം. ഇവയാണ് ഓരോ പ്രോമ്പ്റ്റ് എഞ്ചിനീയർക്കും അറിവുള്ളതാകേണ്ട പടിപടിയുള്ള ഘടകങ്ങൾ. -### സീറോ-ഷോട്ട് പ്രോംപ്‌ടിംഗ് +### സീറോ-ഷോട്ട് പ്രോമ്പ്റ്റിംഗ് -ഏറ്റവും ലളിതമായ സമീപനം: ഉദാഹരണങ്ങളില്ലാതെ നേരിട്ട് മൃഗ്യമായ നിർദ്ദേശം നൽകുക. മോഡൽ ക്ലാസ്സിക്കമായി പരിശീലനം വഴി മാത്രമേ ടാസ്ക് മനസ്സിലാക്കി പ്രവർത്തിക്കു. പ്രതീക്ഷിക്കുന്ന പെരുമാറ്റം വ്യക്തമായ ഒരുതരം അപേക്ഷകൾക്ക് ഇത് നല്ലതാണ്. + ഏറ്റവും ലളിതമായ സമീപനം: ഉദാഹരണങ്ങളില്ലാതെ മോഡലിന് നേരിട്ടു നിർദ്ദേശങ്ങൾ നൽകുക. മോഡൽ തന്റെ പരിശീലനം മൂലം മാത്രം ടാസ്ക് മനസ്സിലാക്കി നിർവഹിക്കുന്നു. പ്രതീക്ഷിച്ച പ്രവൃത്തി വ്യക്തമായ അവസ്ഥകൾക്കു ഇത് നല്ല പ്രവർത്തനം നൽകുന്നു. Zero-Shot Prompting -*ഉദാഹരണങ്ങൾ ഇല്ലാതെ നേരിട്ട് നിർദ്ദേശം — ടാസ്ക് മോഡൽ നിർദ്ദേശം മാത്രം അടിസ്ഥാനമാക്കി സമർപ്പിക്കുന്നു* +*ഉദാഹരണമില്ലാതെ നേരിട്ടു നിർദ്ദേശം നൽകൽ — മോഡൽ നിർദ്ദേശം മാത്രം ആശ്രയിച്ച് ടാസ്ക് മനസ്സിലാക്കുന്നു* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// പ്രതികരണം: "സേവനപരമായ" +// പ്രതികരണം: "സAKERം" ``` + +**എപ്പോൾ ഉപയോഗിക്കണം:** ലളിതമായ വർഗ്ഗീകരണങ്ങൾ, നേരിട്ടുള്ള ചോദ്യങ്ങൾ, അനുവാദങ്ങൾ, അല്ലെങ്കിൽ കൂടുതൽ മാർഗ്ഗനിർദ്ദേശങ്ങൾ ആവശ്യപ്പെടാത്ത മറ്റ് എല്ലാ ടാസ്കുകൾക്കും. -**എപ്പോൾ ഉപയോഗിക്കണം:** ലളിതമായ വർഗ്ഗീകരണങ്ങൾ, നേരിട്ടുള്ള ചോദ്യങ്ങൾ, വിവർത്തനങ്ങൾ, അല്ലെങ്കിൽ ആവശ്യമില്ലാത്ത മാർഗ്ഗനിർദ്ദേശങ്ങളോടെ മോഡൽ കൈകാര്യം ചെയ്യുന്നത് സാധ്യമാകുന്ന ഏതെങ്കിലും ടാസ്കുകൾ. +### ഫ്യൂ-ഷോട്ട് പ്രോമ്പ്റ്റിംഗ് -### ഫ്യൂ-ഷോട്ട് പ്രോംപ്‌ടിംഗ് - -മോഡലിന് അനുസരണീയമായ പാറ്റേൺ എഴുതിയ ഉദാഹരണങ്ങൾ നൽകുക. മോഡൽ നിങ്ങളുടെ ഉദാഹരണങ്ങൾ നിന്നു പ്രതീക്ഷിക്കുന്ന ഇൻപുട്ട്-ഔട്ട്പുട്ട് ഫോർമാറ്റ് പഠിച്ച് പുതിയ ഇൻപുട്ടുകളിൽ പ്രയോഗിക്കും. ആ ആവശ്യകത വ്യക്തമായില്ലാത്ത ടാസ്കുകളിൽ പ്രവർത്തനം വളരെ മെച്ചപ്പെടുത്തുന്നു. +നീങ്ങൾ മോഡൽ അനുശ്രീതിപ്രകാരം പാലിക്കേണ്ട മാതൃക കാണിക്കുന്ന ഉദാഹരണങ്ങൾ നൽകുക. മോഡൽ നിങ്ങളുടെ ഉദാഹരണങ്ങളിൽ നിന്നു ഊഹാവകാശ ഫോർമാറ്റും സമീപനവും പഠിച്ച് പുതിയ ഇൻപുട്ടുകളിൽ പ്രയോഗിക്കുന്നു. ഇത് സംഭാവന ഫോർമാറ്റ് അല്ലെങ്കിൽ പെരുമാറ്റം വ്യക്തമല്ലാത്ത ടാസ്കുകൾക്കു സ്ഥിരത പെരുക്കുന്നു. Few-Shot Prompting -*ഉദാഹരണങ്ങളിൽ നിന്നും പഠിക്കൽ — മോഡൽ പാറ്റേൺ തിരിച്ചറിഞ്ഞ് പുതിയ ഇൻപുട്ടുകളിലേക്ക് പ്രയോഗിക്കുന്നു* +*ഉദാഹരണങ്ങളിൽ നിന്നു പഠിക്കൽ — മോഡൽ മാതൃക തിരിച്ചറിഞ്ഞ് പുതിയ ഇൻപുട്ടുകളിൽ പ്രയോഗിക്കുന്നു* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**എപ്പോൾ ഉപയോഗിക്കണം:** കസ്റ്റം വർഗ്ഗീകരണങ്ങൾ, സ്ഥിരമായ ഫോർമാറ്റിംഗ്, ഡൊമെയ്ൻ-നിഷ്ഠമായ ടാസ്കുകൾ, അല്ലെങ്കിൽ സീറോ-ഷോട്ട് ഫലങ്ങൾ ഒരേപോലെ ഇല്ലാത്തപ്പോൾ. + +**എപ്പോൾ ഉപയോഗിക്കണം:** ഇഷ്ടാനുസൃത വർഗ്ഗീകരണങ്ങൾ, സ്ഥിരമായ ഫോർമാറ്റിംഗ്, ഡൊമെയിൻ-സ്പെസിഫിക് ടാസ്കുകൾ, അല്ലെങ്കിൽ സീറോ-ഷോട്ട് ഫലങ്ങൾ മിതവുമായായിരിക്കുമ്പോൾ. ### ചെയിൻ ഓഫ് തോട്ട് -മോഡൽ തങ്ങളുടെ ചിന്താഗതിപ്രവൃത്തി ഘട്ടം ഘട്ടമായി കാണിക്കാൻ ആവശ്യപ്പെടുക. മറുപടി നേരിട്ട് കൊടുക്കുന്നതിനുപകരം, മോഡൽ പ്രശ്നം തകർക്കുകയും എല്ലാ ഘടകങ്ങളും വ്യക്തമായും വിശദമാക്കി പ്രവർത്തിക്കുകയും ചെയ്യുന്നു. ഇത് ഗണിതം, ലജിക്, ബഹു-ഘട്ട ചിന്താഗതികൾക്ക് ഉറപ്പുള്ളതാക്കുന്നു. +മോഡലിനെ അതിന്റെ ചിന്തനശേഷി പടി-പടി കാണിക്കാൻ അഭ്യർന്നിരിക്കുക. നേരിട്ട് ഉത്തരത്തിലേക്ക് ചാടാതെ മോഡൽ പ്രശ്നത്തെ പടിപടിയായി തകർത്തു തർക്ക നിയമപദ്ധതിയിൽ നിർവ്വഹിക്കുന്നു. ഇത് ഗണിതം, തർക്കം, ബഹുവിധ ചിന്തന ടാസ്കുകളിൽ മാങ്കഷ്ടി വർദ്ധിപ്പിക്കുന്നു. Chain of Thought Prompting -*ഘട്ടം ഘട്ടമായി വാദം — സങ്കീർണ്ണ പ്രശ്നങ്ങൾ വ്യക്തമായ ലജിക്കൽ ഘട്ടങ്ങളായി തകർക്കുന്നു* +*പടി-പടി ചിന്തനം — സങ്കീർണ്ണ പ്രശ്നങ്ങളെ ഗണിതപദവികൾ ആയി വിഭജിക്കൽ* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// മോഡല്‍ കാണിക്കുന്നു: 15 - 8 = 7, പിന്നീട് 7 + 12 = 19 ആപ്പിള്‍ +// മോഡൽ കാണിക്കുന്നു: 15 - 8 = 7, പിന്നെ 7 + 12 = 19 ആപ്പിളുകൾ ``` + +**എപ്പോൾ ഉപയോഗിക്കണം:** ഗണിത പ്രശ്നങ്ങൾ, ലാജിക് പസിലുകൾ, ഡീബഗിംഗ്, അല്ലെങ്കിൽ ചിന്തന പ്രക്രിയ കാണിക്കുന്നതുകൊണ്ട് മാങ്കഷ്ടിയും വിശ്വാസ്യതയും വർദ്ധിക്കുന്ന എല്ലാ ടാസ്കുകൾക്കും. -**എപ്പോൾ ഉപയോഗിക്കണം:** ഗണിത പ്രശ്നങ്ങൾ, ലജിക് പസിലുകൾ, പിശക് കണ്ടെത്തൽ, അല്ലെങ്കിൽ ചിന്താനിരീക്ഷണത്തെ മെച്ചപ്പെടുത്തുന്ന ഏത് ടാസ്കിനും. - -### റോൾ-ബേസ്‌ഡ് പ്രോംപ്‌ടിംഗ് +### റോൾ-ബേസ് പ്രോമ്പ്റ്റിംഗ് -ചോദ്യത്തിന് മുൻപ് എഐക്ക് വ്യക്തമായ ഒരു വ്യക്തിത്വം അല്ലെങ്കിൽ പദവി നിശ്ചയിക്കുക. ഇത് മറുപടികളുടെ ശൈലി, ആഴം, ലക്ഷ്യമിടൽ എന്നിവ രൂപപ്പെടുത്തുന്നു. "സോഫ്റ്റ്വെയർ ഒരു ആർകിടെക്റ്റ്" എന്നത് "ജൂനിയർ ഡെവലപ്പർ" അല്ലെങ്കിൽ "സുരക്ഷാ ഓഡിറ്റർ" എന്നതിനൊത്തു വ്യത്യസ്ത ഉപദേശം നൽകും. +ചോദ്യമോ ബോധിപ്പിക്കുന്നതിന് മുൻപ് AI നൊരു വ്യക്തിത്വം അല്ലെങ്കിൽ റോൾ സജ്ജീകരിക്കുക. ഇത് പ്രതികരണത്തിന്റെ ടോൺ, ആഴം, ധ്രുവീകരണം എന്നിവ ആകൃതീകരിക്കാൻ സായൂകരിക്കുന്നു. "സോഫ്റ്റ്വെയർ ആർകിടെക്റ്റ്" "ജൂനിയർ ഡവലപ്പർ" അല്ലെങ്കിൽ "സുരക്ഷാ ഓഡിറ്റർ" നു നൽകുന്ന ഉപദേശം വ്യത്യസ്തമാണ്. Role-Based Prompting -*സന്ദർഭവും വ്യക്തിത്വവും നിശ്ചയിക്കുക — കൊടുത്ത ഒരേ ചോദ്യത്തിനുള്ള മറുപടി തലം അനുസരിച്ച് മാറുന്നു* +*സന്ദർഭവും വ്യക്തിത്വവും നൽകൽ — ഒരേ ചോദ്യത്തിന് ബAssigned role പോലുള്ള വ്യത്യസ്ത പ്രതികരണങ്ങൾ കിട്ടുന്നു* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` + +**എപ്പോൾ ഉപയോഗിക്കണം:** കോഡ് റിവ്യൂ, പഠന സഹായം, ഡൊമെയിൻ-സ്പെസിഫിക് വിശകലനം, അല്ലെങ്കിൽ പ്രത്യേക വിദഗ്ധ തലത്തിൽ അല്ലെങ്കിൽ ദൃഷ്ടികോണത്തിൽCustomized response വേണ്ടവ. -**എപ്പോൾ ഉപയോഗിക്കണം:** കോഡ് റിവ്യൂസ്, ട്യൂട്ടറിങ്, ഡൊമെയിൻ-സവിശേഷ വിശകലനം, അല്ലെങ്കിൽ പ്രത്യേകം വിദഗ്ധതാ നില അല്ലെങ്കിൽ ദൃഷ്ടികോണം അനുസരിച്ചുള്ള മറുപടികൾ ആവശ്യമുള്ളപ്പോൾ. +### പ്രോമ്പ്റ്റ് ടെംപ്ലേറ്റുകൾ -### പ്രോംപ്‌റ്റ് ടെംപ്ലേറ്റുകൾ - -പരിഗണനാ സ്ഥാനങ്ങൾ ഉള്ള പുനരുപയോഗയോഗ്യമായ പ്രോംപ്‌റ്റുകൾ സൃഷ്ടിക്കുക. ഓരോ തവണ പുതിയ പ്രോംപ്‌റ് എഴുതി നൽകുന്നതിനുപകരം, ടെംപ്ലേറ്റ് ഒരിക്കൽ നിർവചിച്ച് ഒട്ടനവധി വ്യത്യസ്ത മൂല്യങ്ങളുമായി പൂരിപ്പിക്കുക. LangChain4j-യുടെ `PromptTemplate` ക്ലാസ്സ് `{{variable}}` സിന്ടാക്സുമായി ഇത് എളുപ്പമാണ്. +പരിവർത്തനശീല ഫിൽഹോബുത്തക്രകളുമായി പുനരുപയോഗ പ്രോമ്പ്റ്റുകൾ രൂപം നൽകുക. ഓരോ പ്രാവശ്യം പുതിയ പ്രോമ്പ്റ്റ് എഴുതാതെ ഒരു സദാ നിർവചിച്ച രീതി പ്രയോഗിക്കുക. LangChain4j യുടെ `PromptTemplate` ക്ലാസ് ഇത് `{{variable}}` സിന്തക്സിൽ എളുപ്പമാക്കുന്നു. Prompt Templates -*വ്യത്യസ്ത മൂല്യങ്ങളുള്ള പുനപ്രയോഗ സാധ്യമായ പ്രോംപ്‌റ്റുകൾ — ഒരു ടെംപ്ലേറ്റ്, അനേകം ഉപയോഗങ്ങൾ* +*പരിവർത്തനശീല ഫിൽഹോബുത്തക്രകളുള്ള പുനരുപയോഗ പ്രോമ്പ്റ്റ് — ഒരിക്കൽ രൂപം, അനേകം പ്രയോഗങ്ങൾ* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**എപ്പോൾ ഉപയോഗിക്കണം:** വ്യത്യസ്ത ഇൻപുട്ടുകളിൽ ഒരു പോലെ ആവർത്തിക്കുന്ന ചോദ്യങ്ങൾ, ബാച്ച് പ്രോസസ്സിങ്, പുനരുപയോഗയോഗ്യമായ എഐ പ്രവൃത്തി പ്രവാഹങ്ങൾ നിർമ്മിക്കുന്നത്, അല്ലെങ്കിൽ പ്രോംപ് ഘടന സ്ഥിരമായും ഡാറ്റ മാറുന്നതും ഉള്ള എല്ലാ സാഹചര്യങ്ങളിലും. + +**എപ്പോൾ ഉപയോഗിക്കണം:** വ്യത്യസ്ത ഇൻപുട്ടുകളോടുള്ള നിത്യ ചോദ്യം, ബാച്ച് പ്രോസസ്സിംഗ്, പുനരുപയോഗ യോഗ്യമായ AI പ്രവൃത്തി തന്ത്രങ്ങൾ നിർമ്മിക്കുക, അല്ലെങ്കിൽ പ്രോമ്പ്റ്റ് ഘടന തുടർച്ചയായും ഡാറ്റ മാറി വരുമ്പോഴും ഉപയോക്തൃ സാഹചര്യങ്ങളിൽ. --- -ഈ അഞ്ചു അടിസ്ഥാനങ്ങൾ നിങ്ങൾക്കു ഭീമാകാരമായ ടൂൾകിറ്റ് നൽകുന്നു. ബാക്കി ഈ മാഡ്യൂൾ ഇതിന്റെ മേൽ നിർമ്മിച്ച് **എട്ട് പ്രഗത്ഭ പാറ്റേണുകൾ** അവതരിപ്പിക്കുന്നു, GPT-5.2-യുടെ ചിന്തന നിയന്ത്രണവും സ്വയം മൂല്യനിർണയവും ഘടിത ഔട്ട്‌പുട്ടും ഉപയോഗപ്പെടുത്തി. +ഈ അഞ്ച് അടിസ്ഥാനങ്ങൾ നിങ്ങള്‍ക്കു വളരെ വ്യാപകമായ പ്രോമ്പ്റ്റിംഗ് ടാസ്കുകൾക്കുള്ള അടിസ്ഥാനം നൽകുന്നു. ബാക്കിയുള്ള ഭാഗം GPT-5.2 യുടെ reasoning control, സ്വയം-വിമർശനം, ഘടനാപരമായ ഔട്ട്പുട്ട് കഴിവുകൾ ഉപയോഗിച്ച് **എട്ട് അഗ്രഗതമായ രീതികളാൽ** വികസിപ്പിച്ചിരിക്കുന്നു. -## ഉയർന്ന തലത്തിലുള്ള പാറ്റേൺസ് +## അഗ്രഗതമായ രീതികൾ -അടിസ്ഥാനങ്ങൾ പൂർത്തിയാക്കിയ ശേഷം, ഈ മാഡ്യൂളിനെ പ്രത്യേകമാക്കുന്ന എട്ട് പ്രഗത്ഭ പാറ്റേണുകളിലേക്ക് നമുക്ക് നോക്കാം. എല്ലാ പ്രശ്നങ്ങൾക്കും ഒരേ സമീപനം ആവശ്യമായിട്ടില്ല. കുറച്ച് ചോദ്യങ്ങൾക്ക് വേഗത്തിലുള്ള മറുപടികൾ വേണ്ടിവരും, മറ്റു ചിലറക്ക് ഗഹന ചിന്തനം വേണ്ടത്. ചിലപ്പോൾ തെളിവുകളോടെ ചിന്താഗതിയിലാക്കേണ്ടിവരും, മറ്റു ചിലപ്പോൾ ഫലങ്ങൾ മാത്രം ആവശ്യമാകും. താഴെ കാണുന്ന ഓരോ പാറ്റേണും വ്യത്യസ്ത സാഹചര്യത്തിനായി പരിഷ്‌കരിച്ചിരിക്കുന്നു — GPT-5.2-യുടെ ചിന്തന നിയന്ത്രണം ഈ വ്യത്യാസങ്ങളെ കൂടുതല്‍ സൂക്ഷ്മമായി കാണിക്കുന്നു. +അടിസ്ഥാനങ്ങൾ കഴിഞ്ഞു, ഈ മോഡ്യൂലിന്റെ പ്രത്യേകതയുള്ള എട്ട് പ്രഗത്ഭമായ രീതികളിലേക്ക് നാം നീങ്ങാം. എല്ലാ പ്രശ്നങ്ങൾക്കും ഒരേ സമീപനം വേണ്ടതല്ല. ചില ചോദ്യങ്ങൾക്ക് വേഗം ഉത്തരം, മറ്റുള്ളവയ്ക്കു ആഴമുള്ള ചിന്തനം. ചിലയ്ക്കു ദൃശ്യമായ ചിന്തനം വേണം, മറ്റു കുറച്ചു മാത്രം. താഴെ കൊടുത്തിരിക്കുന്ന ഓരോ മാതൃകയും വ്യത്യസ്ത സാഹചര്യങ്ങൾക്ക് അനുയോജ്യമാണ് — GPT-5.2 യുടെ reasoning control ഈ വ്യത്യാസങ്ങൾ കൂടുതൽ വ്യക്തമാക്കുന്നു. Eight Prompting Patterns -*എട്ട് പ്രോംപ് എൻജിനീയറിങ് പാറ്റേണുകളുടെ അവലോകനം കൂടാതെ അവയുടെ ഉപയോഗ കേസുകൾ* +*എട്ട് പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗ് മാതൃകകളുടെയും അവയുടെ ഉപയോഗ സാഹചര്യങ്ങളുടെ അവലോകനം* -GPT-5.2 ഈ പാറ്റേണുകൾക്ക് മറ്റൊരു നിലയേകുന്നു: *ചിന്തന നിയന്ത്രണം*. താഴെയുള്ള സ്ലൈഡർ മോഡലിന്റെ ചിന്തന ശക്തി എത്രമാത്രം ആയിരിക്കണമെന്ന് നിങ്ങൾ ക്രമീകരിക്കാം — വേഗത്തിലുള്ള നേരിട്ട് മറുപടികളിൽ നിന്നു ഗഹനമായ വിശകലനത്തിലേക്ക്. +GPT-5.2 ഈ മാതൃകകളെ മറ്റൊരു അളവിലേക്ക് ഉയര്‍ത്തെറി: *reasoning control*. താഴെ സ്ക്രീന്ഷോട്ടിൽ കാണുന്ന സ്ലൈഡർ മോഡലിന്റെ ചിന്തനശേഷി ക്രമീകരിക്കാൻ സഹായിക്കുന്നു — വേഗത്തിൽ നേരിട്ടുള്ള ഉത്തരത്തിൽ നിന്നും ആഴത്തിൽ പൂർണ്ണമായ വിശകലനത്തിലേക്കും. Reasoning Control with GPT-5.2 -*GPT-5.2യുടെ ചിന്തന നിയന്ത്രണം മോഡലിനേയ്ക്ക് എത്ര ചിന്തിക്കാൻ ആഗ്രഹിക്കുന്നുവെന്നും തുറന്ന് പറയാം — വേഗവും നേരിട്ടുള്ള മറുപടികളിൽ നിന്നു ദീർഘവും ഗഹനമായ അന്വേഷനം വരെ* +*GPT-5.2 യുടെ reasoning control മോഡലിന് എത്ര ചിന്തനം നടത്തണമെന്ന് നിങ്ങൾ വ്യക്തമാക്കാം — വേഗം നേരിട്ടുള്ള മുതൽ ആഴത്തിൽ വിശദമായ വിശദീകരണം വരെ* -**കുറഞ്ഞ ഉത്സാഹം (വേഗവും കേന്ദ്രീകൃതവും)** - ലളിതമായ ചോദ്യങ്ങൾക്ക് വേഗത്തിൽ നേരിട്ട് മറുപടി വേണം. മോഡൽ കുറഞ്ഞ തോതിൽ മാത്രമേ ചിന്തിക്കുന്നത് — പരമാവധി 2 ഘട്ടം. കണക്കുകൂട്ടലുകൾ, തിരയൽ, അല്ലെങ്കിൽ നേരിട്ടുള്ള ചോദ്യങ്ങൾക്ക് ഇത് ഉപയോഗിക്കുക. +**കുറഞ്ഞ ഉത്സാഹം (വേഗവും കേന്ദ്രീകൃതവുമുള്ളത്)** - ലളിതമായ ചോദ്യങ്ങൾക്ക് വേഗത്തിലുള്ള ഏകദേശം സൂക്ഷ്മമായ ഉത്തരങ്ങൾ വേുമ്പോൾ. മോഡൽ നിസ్సഹായമായ reasoning - പരമാവധി 2 ചുവട്ടുകൾ മാത്രം നടത്തുന്നു. കണക്കുകൂട്ടൽ, തിരയൽ അല്ലെങ്കിൽ നേരിട്ട് ഉത്തരം ആവശ്യമായ ചോദ്യങ്ങൾക്ക് ഇത് ഉപയോഗിക്കുക. ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> 💡 **GitHub Copilot ഉപയോഗിച്ച് പരീക്ഷിക്കൂ:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) തുറന്ന് ചോദിക്കുക: +> - "കുറഞ്ഞ ഉത്സാഹവും ഉയർന്ന ഉത്സാഹവും ഉള്ള പ്രോമ്പ്റ്റിംഗ് മാതൃകകളിൽ有什么 വ്യത്യാസമാണ്?" +> - "പ്രോമ്പ്റ്റുകളിൽ ഉള്ള XML ടാഗുകൾ എങ്ങനെ AI യുടെ പ്രതികരണം ഘടിപ്പിക്കാൻ സഹായിക്കുന്നു?" +> - "സ്വയം-പരിശോധന മാതൃകകൾ VS നേരിട്ടുള്ള നിർദ്ദേശം എപ്പോൾ ഉപയോഗിക്കണം?" -> 💡 **GitHub Copilot ഉപയോഗിച്ച് പരീക്ഷിക്കുക:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) തുറന്ന് ചോദിക്കൂ: -> - "കുറഞ്ഞ ഉത്സാഹവും ഉയർന്ന ഉത്സാഹവും പ്രോംപ്‌ടിംഗ് പാറ്റേണുകൾ തമ്മിലുള്ള വ്യത്യാസം എന്താണ്?" -> - "പ്രോംപ്‌റുകളിൽ XML ടാഗുകൾ എഐയുടെ മറുപടി ഘടിപ്പിക്കാൻ എങ്ങനെ സഹായിക്കുന്നു?" -> - "സ്വയം-പരിശോധന പാറ്റേണുകൾ എപ്പോഴാണ് നേരിട്ട് നിർദ്ദേശം നൽകുന്നതിന്റെ പകരം ഉപയോഗിക്കേണ്ടത്?" - -**ഉയർന്ന ഉത്സാഹം (ഗഹനവും വിമാനപരിശോധനയും)** - സമ്പീഡിത പ്രശ്നങ്ങൾക്ക് സമഗ്രവും രൂപകല്പനാത്മകവും ആയ വിശകലനം വേണം. മോഡൽ ഗഹനമായി അന്വേഷിക്കുകയും വിശദമായ വാദം കാണിക്കുകയും ചെയ്യും. സിസ്റ്റം രൂപകൽപ്പന, ആർക്കിടെക്‌ചർ തീരുമാനങ്ങൾ, അല്ലെങ്കിൽ സമ്പീടിത ഗവേഷണത്തിന് ഇത് അനുയോജ്യം. +**ഉയർന്ന ഉത്സാഹം (ആഴവും സമഗ്രവുമായത്)** - സമ്പൂർണ വിശകലനത്തിനായി. മോഡൽ വിശദമായി പരിശ്രമിക്കുകയും വിശദമായ ചിന്തനം കാണിക്കുകയും ചെയ്യുന്നു. സിസ്റ്റം ഡിസൈൻ, ആർകിടെക്ചർ തീരുമാനങ്ങൾ, സങ്കീർണ്ണ ഗവേഷണം എന്നിവയ്ക്ക് ഇത് ഉപയോഗിക്കുക. ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**ടാസ്‌ക് എക്സിക്യൂഷൻ (പടി-പടിയായി പുരോഗതി)** - ബഹു-ഘട്ട പ്രവൃത്തികൾക്കായി. മോഡൽ മുൻകൂർ പദ്ധതി നൽകുകയും ഓരോ ഘട്ടം പ്രവർത്തിക്കുന്നതും വിവരിക്കുകയും പിന്നീട് ഏകദേശ സംഗ്രഹമനു നൽകുകയും ചെയ്യുന്നു. മൈഗ്രേഷനുകൾ, നടപ്പാക്കലുകൾ, അല്ലെങ്കിൽ ഏതെങ്കിലും ബഹു-ഘട്ട പ്രവർത്തനത്തിനും ഇത് ഉപയോഗിക്കുക. + +**ടാസ്ക് എക്സിക്യൂഷൻ (പടി-പടി പുരോഗതി)** - നിരവധി ഘട്ടങ്ങളുള്ള പ്രവൃത്തി രീതി. മോഡൽ ആദ്യം ഒരു പദ്ധതി നൽകുകയും, ഓരോ ഘട്ടവും പ്രവൃത്തി ചെയ്യുന്നപ്പോൾ വിവരിക്കുകയും, തുടർന്ന് സാമറി നൽകുകയും ചെയ്യുന്നു. മൈഗ്രേഷൻ, നടപ്പാക്കലുകൾ, അല്ലെങ്കിൽ ഏതെങ്കിലും ബഹു-ഘട്ട പ്രക്രിയയ്ക്ക് ഈ രീതി ഉപയോഗിക്കുക. ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +ചെയിൻ-ഓഫ്-തോട്ട് പ്രോമ്പ്റ്റിംഗ് മോഡലിൽ ചിന്തന പ്രക്രിയ വെളിപ്പെടുത്താൻ ആവശ്യപ്പെടുന്നു, സങ്കീർണ്ണ ടാസ്കുകളിൽ മാങ്കഷ്ടി വർദ്ധിപ്പിക്കുന്നു. പടി-പടി വിഭജനം മനുഷ്യരും AI യും ലൊജിക് മനസ്സിലാക്കാൻ സഹായിക്കുന്നു. -ചെയിൻ-ഓഫ്-തോട്ട് പ്രോംപ്‌ടിംഗ് മോഡലിനോട് അവരുടെ ചിന്തനപ്രവൃത്തി പ്രകടിപ്പിക്കാൻ ആവശ്യപ്പെടുന്നു, സങ്കീർണ്ണ ടാസ്കുകളിൽ കൃത്യത മെച്ചപ്പെടുത്തുന്നു. പടി-പടിയായി തകർത്തത് മനുഷ്യർക്കും എഐക്കും ലജിക് മനസ്സിലാക്കുവാനുള്ള സഹായമാണ്. +> **🤖 GitHub Copilot Chat ഉപയോഗിച്ച് ശ്രമിക്കൂ:** ഈ മാതൃകയെ കുറിച്ച് ചോദിക്കുക: +> - "നീണ്ടകാലത്തേക്ക് നടത്തുന്ന ഒപ്പറേഷനുകൾക്കായി ടാസ്ക് എക്സിക്യൂഷൻ മാതൃക എങ്ങനെ ക്രമീകരിക്കാം?" +> - "പ്രൊഡക്ഷൻ ആപ്ലിക്കേഷനുകളിൽ ടൂൾ പ്രീഅംബ്ലുകൾ ഘടിപ്പിക്കാനുള്ള മികച്ച പ്രവൃത്തികൾ എന്തൊക്കെ?" +> - "UI യിൽ ഇട ഇട അതിവേഗ പുരോഗതി അപ്ഡേറ്റുകൾ എങ്ങനെ പിടിച്ചു കാട്ടണമെന്ന്?" -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റിൽ ട്രൈ ചെയ്‌യൂ:** ഈ പാറ്റേണിനെക്കുറിച്ച് ചോദിക്കൂ: -> - "ദീർഘകാല പ്രവർത്തനങ്ങൾക്ക് ടാസ്‌ക് എക്സിക്യൂഷൻ പാറ്റേൺ എങ്ങനെ തുറന്ന് ക്രമീകരിക്കാം?" -> - "പ്രൊഡക്ഷൻ അപ്ലിക്കേഷനുകളിൽ ടൂൾ പ്രീംബിളുകൾ ഘടിപ്പിക്കുന്ന മികച്ച രീതികൾ എന്തെല്ലാമാണ്?" -> - "ഇന്റർമീഡിയറ്റ് പുരോഗതി അപ്ഡേറ്റുകൾ UI-യിൽ എങ്ങനെ പകര്‍ത്താൻ, പ്രദർശിപ്പിക്കാൻ കഴിയും?" - -താഴെ കാണുന്ന ചിത്രം Plan → Execute → Summarize പ്രവൃത്തി പ്രക്രിയയെ സാന്ദ്രിക്കുന്നു. +താഴെ കാണുന്ന ചിത്രത്തിൽ ഈ പദ്ധതി → നടപ്പാക്കൽ → സാമറി പ്രവൃത്തി രീതി കാണിക്കുന്നു. Task Execution Pattern -*ബഹു-ഘട്ട ടാസ്കിനുള്ള Plan → Execute → Summarize പ്രവൃത്തി പ്രക്രിയ* +*പദ്ധതി → നടപ്പാക്കൽ → സാമറി - നിരവധി ഘട്ടങ്ങളുള്ള ടാസ്ക്കുകളിലേക്കുള്ള പ്രവൃത്തി രീതി* -**സ്വയം-പരിശോധന കോഡ്** - പ്രൊഡക്ഷൻ നിലവാരത്തിലുള്ള കോഡ് സൃഷ്ടിക്കുന്നതിന്. മോഡൽ ഗുണനിലവാരം ഉറപ്പാക്കുന്നതിന് ഉചിതമായ പിശക് കൈകാര്യം समेत കോഡ് നിർമ്മിക്കുന്നു. പുതിയ ഫീച്ചറുകളും സർവീസുകളും തയ്യാറാക്കുമ്പോൾ ഇത് ഉപയോഗിക്കുക. +**സ്വയം-പരിശോധന കോഡ്** - പ്രൊഡക്ഷൻ നിലവാരമുള്ള കോഡ് സൃഷ്ടിക്കാൻ. മോഡൽ പ്രൊഡക്ഷൻ മാനദണ്ഡങ്ങൾ പാലിച്ചുകൊണ്ട്, ശരിയായ പിശക് കൈകാര്യംത്തോടു കൂടി കോഡ് ജനനമാക്കുന്നു. പുതിയ ഫീച്ചറുകൾ അല്ലെങ്കിൽ സർവീസുകൾ നിർമ്മിക്കുമ്പോൾ ഇത് ഉപയോഗിക്കുക. ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -താഴെയുള്ള ചിത്രം ഈ ആവർത്തന മെച്ചപ്പെടുത്തൽ ചക്രത്തെ കാണിക്കുന്നു — സൃഷ്ടിക്കുക, മൂല്യനിർണയം ചെയ്യുക, ദുർബലതകൾ തിരിച്ചറിയുക, മെച്ചപ്പെടുത്തുക, ആവർത്തിക്കുക - കോഡ് പ്രൊഡക്ഷൻ നിലവാരത്തിലെത്തുന്നതുവരെ. + +താഴിലെ ചിത്രത്തിൽ ഈ ആവർത്തന മെച്ചപ്പെടുത്തൽ ചക്രം കാണുന്നു - ജനനിക്കുക, വിലയിരുത്തുക, ദുർബലതകൾ തിരിച്ചറിഞ്ഞ് മെച്ചപ്പെടുത്തുക, പ്രൊഡക്ഷൻ നിലവാരമെത്തിയുവരെയും ആവർത്തിക്കുക. Self-Reflection Cycle -*ആവർത്തന മെച്ചപ്പെടുത്തൽ ചക്രം - സൃഷ്ടിക്കുക, മൂല്യനിർണയം, പ്രശ്നങ്ങൾ കണ്ടെത്തുക, മെച്ചപ്പെടുത്തുക, ആവർത്തിക്കുക* +*ആവർത്തന മെച്ചപ്പെടുത്തൽ ചക്രം - സൃഷ്ടിക്കുക, വിലയിരുത്തുക, പ്രശ്നങ്ങൾ തിരിച്ചറിഞ്ഞ് മെച്ചപ്പെടുത്തുക, ആവർത്തിക്കുക* -**സംരചിത വിശകലനം** - സ്ഥിരതയുള്ള മൂല്യനിർണയത്തിനായി. മോഡൽ ഒരു നിശ്ചിത ഫ്രെയിംവർക്ക് (ശുദ്ധിതി, പ്രാക്ടിസ്, പ്രകടനം, സുരക്ഷ, സംരക്ഷിക്കുന്നതിനുള്ള കഴിവ്) ഉപയോഗിച്ച് കോഡ് പരിശോധിക്കുന്നു. കോഡ് റിവ്യൂകൾക്കും ഗുണനിലവാര മാപ്പിനും ഇത് ഉപയോഗിക്കുക. +**ഘടനാപരമായ വിശകലനം** - സ്ഥിരമായ അവലോകനത്തിനായി. മോഡൽ കോഡ് പരിശോധിച്ചു നിർധാരിത ഘടനാപരമായ ഫ്രെയിമ്വർക്കിലൂടെ (ശുദ്ധത, പ്രാക്ടീസുകൾ, പ്രകടനം, സുരക്ഷ, പരിപാലനക്ഷമത) വിലയിരുത്തുന്നു. കോഡ് അവലോകനം അല്ലെങ്കിൽ ഗുണനിലവാര മാപ്പിംഗിനായി ഇത് ഉപയോഗിക്കുക. ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> **🤖 GitHub Copilot Chat ഉപയോഗിച്ച് പരീക്ഷിക്കൂ:** ഘടനാപരമായ വിശകലനം കുറിച്ച് ചോദിക്കുക: +> - "വ്യത്യസ്ത കോഡ് റിവ്യൂ തരം കാണുന്ന ഫ്രെയിമ്വർക്കുകൾ എങ്ങനെ ഇഷ്‌ടാനുസൃതമാക്കണം?" +> - "ഘടനാപരമായ ഔട്ട്പുട്ട് പ്രോഗ്രാമാറ്റിക്കായി പാഴ്‌സും ഉപയോഗവും എങ്ങനെ കാര്യക്ഷമമാക്കാം?" +> - "വിടവിട്ട അവലോകനങ്ങളിൽ സ്ഥിരമായ ഗുരുതരത തലങ്ങൾ എങ്ങനെ ഉറപ്പാക്കാം?" -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റിൽ പരീക്ഷിക്കുക:** സംരചിത വിശകലനം സംബന്ധിച്ച് ചോദിക്കൂ: -> - "വിവിധ തരത്തിലുള്ള കോഡ് റിവ്യൂകൾക്കായി വിശകലന ഫ്രെയിംവർക്ക് എങ്ങനെ ഇഷ്ടാനുസൃതമാക്കാം?" -> - "സംരചിത ഔട്ട്‌പട്ട് പ്രോഗ്രാമാറ്റിക്കായി പാഴ്സുചെയ്യുകയും പ്രതികരിക്കുകയും ചെയ്യുന്നതിനുള്ള മികച്ച മാർഗം എന്താണ്?" -> - "വിവിധ റിവ്യൂ സെഷനുകളിലും സ്ഥിരമായ ഗൗരവനിലകൾ എങ്ങനെ ഉറപ്പാക്കാം?" - -താഴെയുള്ള ചിത്രം ഈ സംരചിത ഫ്രെയിംവർക്ക് ഗൗരവനിലകളോടെ സ്ഥിരമായ കോഡ് റിവ്യൂ സെഗ്മെന്റുകളിൽ സംബന്ധിപ്പിക്കുന്നത് കാണിക്കുന്നു. +താഴെ നൽകിയിരിക്കുന്ന ചിത്രം ഈ ഘടനാപരമായ ഫ്രെയിംവർക്ക് കോഡ് റിവ്യൂ സ്ഥിരമായ വിഭാഗങ്ങളായി ഭേദിച്ച് ഗുരുതരത നിലയോടു കൂടെ എങ്ങനെ ക്രമീകരിക്കുന്നു എന്ന് കാണിക്കുന്നു. Structured Analysis Pattern -*ഗൗരവനിലകളോടെയുള്ള സ്ഥിരതയുള്ള കോഡ് റിവ്യൂസിനുള്ള ഫ്രെയിംവർക്ക്* +*ഗുരുതരത നിലയോടെയുള്ള സ്ഥിരമായ കോഡ് റിവ്യൂകൾക്ക് ഫ്രെയിമ്വർക്ക്* -**മൾട്ടി-ടേൺ ചാറ്റ്** - സന്ദർഭം ആവശ്യമായ സംഭാഷണങ്ങൾക്ക്. മോഡൽ മുൻ הודലുകൾ ഓർമ്മിച്ച് അവയിൽ കൂട്ടിച്ചേരുന്നു. ഇന്ററാക്ടീവ് സഹായ സെഷനുകൾക്കും സമ്പീഡിത Q&A-കൾക്കും ഇത് ഉപയോഗിക്കുക. +**മൾട്ടി-ടേൺ ചാറ്റ്** - സാഹചര്യമെന്നാൽ ആവശ്യമുള്ള സംഭാഷണങ്ങൾക്ക്. മോഡൽ മുൻകാല സന്ദേശങ്ങൾ ഓർത്തു അവയിൽ അധിഷ്ഠിതംയായി തുടരുന്നു. ഇന്ററാക്ടീവ് സഹായ സെഷനുകളോ സങ്കീര്‍ണ ചോദ്യോത്തരങ്ങളോ ആവശ്യമായപ്പോൾ ഇത് ഉപയോഗിക്കുക. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -താഴെയുള്ള ചിത്രം ചാറ്റിലെ സംഭാഷണ സന്ദർഭം ഓരോ തവണയും എങ്ങനെ ചുമത്തപ്പെടുന്നു എന്നും മോഡലിന്റെ ടോക്കൺ പരിധിയുമായി അതിന്റെ ബന്ധവും കാണിക്കുന്നു. + +താഴെയുള്ള ചിത്രം ഒരിക്കൽ കൂടുതൽ ഘട്ടങ്ങളിൽ സംഭാഷണത്തിന്റെ സാഹചര്യ എങ്ങനെ കൂട്ട് കൂട്ടുന്നു, മോഡലിന്റെ ടോക്കൺ പരിധിയുമായി ബന്ധിപ്പിക്കുന്ന വിധം കാണിക്കുന്നു. Context Memory -*തൊണ്ണൂറുമീറ്റർ പരിധി നിൽവയില്‍ വേറെവിരുതലുമില്ലാതെ ഒരേ സംഭാഷണ സന്ദർഭം എങ്ങനെ പകർന്ന് വളരുന്നു* -**പടി-പടി ലജിച്ചിന്തനം** - ദൃശ്യമായ തർക്കം ആവശ്യപ്പെട്ട പ്രശ്നങ്ങൾക്ക്. ഓരോ ഘട്ടത്തിനും മോഡൽ വ്യക്തമായ ലജിച്ചിന്തനം കാണിക്കുന്നു. ഇത് ഗണിത പ്രശ്നങ്ങൾ, ലജിക് പസിലുകൾ, അല്ലെങ്കിൽ നിങ്ങൾക്ക് ചിന്തന പ്രക്രിയ മനസ്സിലാക്കേണ്ടതുണ്ടെങ്കിൽ ഉപയോഗിക്കുക. +*ചർച്ചയുടെ സാഹചര്യ മൾട്ടി-ടേൺ കൈമാറ്റങ്ങൾ വഴി ടോക്കൺ പരിധി വരെ എങ്ങനെ കൂട്ടാളിക്കുന്നു* + +**പടി-പടി ചിന്തനം** - ദൃശ്യമായ ലജിക് ആവശ്യമായ പ്രശ്നങ്ങൾക്കു. മോഡൽ ഓരോ ഘട്ടത്തിന്റെയും സൂക്ഷ്മമായ ചിന്തനം കാണിക്കുന്നു. ഗണിത പ്രശ്നങ്ങൾ, തർക്കം പസിലുകൾ, അല്ലെങ്കിൽ ചിന്തന പ്രക്രിയ മനസ്സിലാക്കേണ്ടപ്പോൾ ഇത് ഉപയോഗിക്കുക. ```java String prompt = """ @@ -397,14 +398,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -താഴെയുള്ള ചിത്രത്തിൽ മോഡൽ പ്രശ്നങ്ങൾ വ്യക്തമായ, നമ്പർ ചെയ്ത ലജിക് ഘട്ടങ്ങളായി എങ്ങനെ വിഭജിക്കുന്നു എന്ന് കാണിക്കുന്നു. + +താഴെ ചേർന്നിരിക്കുന്ന ചിത്രത്തിൽ മോഡൽ പ്രശ്നങ്ങളെ സൂക്ഷ്മ, നൂമ്പർ ചെയ്ത ലജിക്കൽ ഘട്ടങ്ങളായി വിഭജിക്കുന്നതുണ്ടെന്ന് കാണിക്കുന്നു. Step-by-Step Pattern +*പ്രശ്‌നങ്ങളെ വ്യക്തമായ തത്വചിന്താ ഘട്ടങ്ങളായി വിഭജിക്കൽ* -*പ്രശ്നങ്ങളെ വ്യക്തമായ ലജിക്ക് ഘട്ടങ്ങളായി തകർത്ത് കാണിക്കൽ* - -**करीत_OUTPUT** - നിശ്ചിത ഫോർമാറ്റ് ആവശ്യമായ പ്രതികരണങ്ങൾക്ക്. മോഡൽ കഠിനമായ ഫോർമാറ്റ്, ദൈർഘ്യം നിയമങ്ങൾ പാലിക്കുന്നു. സംഗ്രഹങ്ങൾക്കോ കൃത്യമായ ഔട്ട്പുട്ട് ഘടന ആഗ്രഹിക്കുന്നപ്പോൾ ഇത് ഉപയോഗിക്കുക. +**നിയന്ത്രിത ഔട്ട്പുട്ട്** - പ്രത്യേക ഫോർമാറ്റ് ആവശ്യകതകളുള്ള പ്രതികരണങ്ങൾക്ക്. മോഡൽ കർശനമായി ഫോർമാറ്റും നീളവും പാലിക്കുന്നു. സംഗ്രഹങ്ങൾക്കോ നിർദ്ദിഷ്ട ഔട്ട്പുട്ട് ഘടന ആവശ്യമുള്ളപ്പോഴോ ഇത് ഉപയോഗിക്കുക. ```java String prompt = """ @@ -420,189 +420,189 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -താഴെയുള്ള ചിത്രത്തിൽ നിയന്ത്രണങ്ങൾ മോഡലിനെ നിശ്ചിത ഫോർമാറ്റ്, ദൈർഘ്യം മാനദണ്ഡങ്ങൾ പാലിക്കാൻ പ്രേരിപ്പിക്കുന്നതു കാണിക്കുന്നു. +താഴെ കൊടുത്തിരിക്കുന്ന രേഖാചിത്രം മോഡലിനെ നിങ്ങളുടെ ഫോർമാറ്റ്, നീളം എന്നിവ കർശനമായി പാലിക്കുന്ന ഔട്ട്പുട്ട് സൃഷ്ടിക്കാൻ എങ്ങനെ നിയന്ത്രണങ്ങൾ മാർഗ്ഗനിർദ്ദേശം നൽകുന്നു എന്ന് കാണിക്കുന്നു. -Constrained Output Pattern +നിയന്ത്രിത ഔട്ട്പുട്ട് പാറ്റേൺ -*നിശ്ചിത ഫോർമാറ്റ്, ദൈർഘ്യം, ഘടന മാനദണ്ഡങ്ങൾ പാലിക്കൽ* +*നിർദ്ദിഷ്ട ഫോർമാറ്റ്, നീളം, ഘടന ആവശ്യകതകൾ നടപ്പിലാക്കൽ* -## ആപ്ലിക്കേഷൻ ഓടിക്കുക +## അപ്ലിക്കേഷൻ പ്രവർത്തിപ്പിക്കുക -**ടെംപ്ലേറ്റിന്റെ ശരിതായ്ക്കുക:** +**നിയമാനുസൃത ഡിപ്ലോയ്മെന്റ് പരിശോധിക്കുക:** -റൂട്ട് ഡയറക്ടറിയിൽ `.env` ഫയൽ ആസ്യൂർ ക്രെഡൻഷ്യലുകളോടെ (Module 01 دوران സൃഷ്ടിച്ച) ഉറപ്പാക്കുക. മോഡ്യൂൾ ഡയറക്ടറിയിൽ നിന്നും (`02-prompt-engineering/`) ഇത് ഓടിക്കുക: +അഴുറ്റ് ക്രെഡൻഷ്യലുകളോടെ `.env` ഫയൽ റൂട്ടിലെ ഉള്ളതായി ഉറപ്പാക്കുക (Module 01-ൽ സൃഷ്ടിച്ചത്). ഇത് മോഡ്യൂൾ ഡയറക്ടറിയിൽ നിന്ന് പ്രവർത്തിപ്പിക്കുക (`02-prompt-engineering/`): -**Bash:** +**ബാഷ്:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്കണം ``` -**PowerShell:** +**പവർ ഷെൽ:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്കണം +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്കേണ്ടതാണ് ``` -**ആപ്ലിക്കേഷൻ ആരംഭിക്കുക:** +**അപ്ലിക്കേഷൻ ആരംഭിക്കുക:** -> **കുറിപ്പ്:** റൂട്ട് ഡയറക്ടറിയിൽ നിന്ന് `./start-all.sh` ഉപയോഗിച്ചു എല്ലാ ആപ്ലിക്കേഷനുകളും ആരംഭിച്ചിട്ടുണ്ടെങ്കിൽ (Module 01 ൽ വിവരിച്ച പോലെ), ഈ മോഡ്യൂൾ 8083 പോർട്ടിൽ ഇതിനകം ഓടുകയാണ്. താഴെയുള്ള സ്ടാർട്ട് കമാണ്ടുകൾ ഒഴിവാക്കി http://localhost:8083 ന് നേരിട്ട് പോകാം. +> **ഗൗരവമുള്ള കുറിപ്പ്:** റൂട്ട് ഡയറക്ടറിയിൽ നിന്ന് `./start-all.sh` എല്ലാ ആപ്ലിക്കേഷനുകളും നിങ്ങൾ മുമ്പ് ആരംഭിച്ചിട്ടുണ്ടെങ്കിൽ (Module 01-ൽ വിശദീകരിച്ചത് പോലെ), ഈ മോഡ്യൂൾ 8083 പോർട്ടിൽ ഇതിനകം പ്രവർത്തനസജ്ജമാണ്. താഴെ കൊടുത്തിരിക്കുന്ന ആരംഭിക്കാൻ വേണ്ട കമാൻഡുകൾ ഒഴിവാക്കി നേരിട്ട് http://localhost:8083 സന്ദർശിക്കാം. -**ഓപ്ഷൻ 1: Spring Boot ഡാഷ്ബോർഡ് ഉപയോഗിച്ച് (VS Code ഉപയോക്താക്കൾക്ക് ശുപാർശ ചെയ്യുന്നു)** +**ഓപ്ഷൻ 1: സ്‌പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് ഉപയോഗിക്കൽ (VS Code ഉപയോക്താക്കൾക്ക് ശിപാർശ ചെയ്‌തത്)** -ഡെവ് കൺറ്റെയ്നർ Spring Boot ഡാഷ്ബോർഡ് എക്സ്റ്റൻഷൻ ഉൾക്കൊള്ളുന്നു, ഇത് എല്ലാ Spring Boot ആപ്ലിക്കേഷനുകളും മാനേജ് ചെയ്യാനുള്ള കാഴ്ചപരമായ ഇന്റർഫേസ് നൽകുന്നു. ഇത് VS Code ലെ ഇടതു Activity Bar ലെ Spring Boot ഐക്കൺ കാണാം. +ഡെവ് കണ്ടെയ്‌നറിൽ സ്‌പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് എക്സ്റ്റൻഷൻ ഉൾപ്പെടുത്തപ്പെട്ടിരിക്കുന്നു, ഇത് എല്ലാ സ്‌പ്രിംഗ് ബൂട്ട് ആപ്ലിക്കേഷനുകളും ദൃശ്യപരമായി കൈകാര്യം ചെയ്യാൻ സഹായിക്കുന്നു. VS Code-യുടെ ഇടത്ത(js) Activity Bar-ൽ സ്പ്രിംഗ് ബൂട്ട് ഐക്കൺ കണ്ടെത്തുക. -Spring Boot ഡാഷ്ബോർഡിൽ നിന്നും, നിങ്ങൾക്ക്: -- ജോലിസ്ഥലത്തിലുള്ള എല്ലാ Spring Boot ആപ്ലിക്കേഷൻസും കാണാം -- ഒരിക്കൽ ക്ലിക്കു കൊണ്ട് ആപ്ലിക്കേഷനുകൾ സ്റ്റാർട്ട്/സ്റ്റോപ്പ് ചെയ്യാം -- ആപ്ലിക്കേഷൻ ലോഗുകൾ റിയൽ-ടൈമിൽ കാണാം -- ആപ്ലിക്കേഷൻ സ്ഥിതി നിരീക്ഷിക്കാം +സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡിൽ നിന്നു് നിങ്ങള്‍ക്കു ലഭ്യമായതു: +- വർക്ക്സ്പേസിലെ എല്ലാ സ്‌പ്രിംഗ് ബൂട്ട് ആപ്ലിക്കേഷനുകളും കാണുക +- സിംപിള്‍ ക്ലിക്കോടെ ആപ്ലിക്കേഷനുകൾ സ്റ്റാർട്ട്/സ്റ്റോപ്പ് ചെയ്യുക +- ആപ്ലിക്കേഷൻ ലോഗുകൾ സത്യസന്ധമായി കാണുക +- ആപ്ലിക്കേഷന്റെ നില നിരീക്ഷിക്കുക -"prompt-engineering" ന്റെ അടുത്ത് പ്ലേ ബട്ടൺ ക്ലിക്ക് ചെയ്ത് ഈ മോഡ്യൂൾ സ്റ്റാർട്ട് ചെയ്യുക, അല്ലെങ്കിൽ എല്ലാം ഒരുമിച്ച് സ്റ്റാർട്ട് ചെയ്യാം. +"prompt-engineering" ന്റെ അടുത്തുള്ള പ്ലേ ബട്ടൺ ക്ലിക്കുചെയ്ത് ഈ മോഡ്യൾ ആരംഭിക്കുക, അല്ലെങ്കിൽ എല്ലാ മോഡ്യൂളുകളും ഒരുമിച്ച് തുടങ്ങുക. Spring Boot Dashboard -*VS Codeയിലെ Spring Boot ഡാഷ്ബോർഡ് — ഒരിടത്തുനിന്ന് എല്ലാ മോഡ്യൂളുകളും ആരംഭിക്കുക, നിർത്തുക, നിരീക്ഷിക്കുക* +*VS Codeയിലെ സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് — ഒരു സ്ഥലം നിന്നും എല്ലാ മോഡ്യൂളുകളും ആരംഭിച്ച്‌ നിർത്തി, നിരീക്ഷിക്കുക* -**ഓപ്ഷൻ 2: ഷെൽ സ്‌ക്രിപ്റ്റുകൾ ഉപയോഗിച്ച്** +**ഓപ്ഷൻ 2: ഷെൽ സ്ക്രിപ്റ്റുകൾ ഉപയോഗിക്കല്‍** എല്ലാ വെബ് ആപ്ലിക്കേഷനുകളും (മോഡ്യൂളുകൾ 01-04) ആരംഭിക്കുക: -**Bash:** +**ബാഷ്:** ```bash cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്ന് ./start-all.sh ``` -**PowerShell:** +**പവർ ഷെൽ:** ```powershell -cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്നും +cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്ന് .\start-all.ps1 ``` -അതോ ഈ മോഡ്യൂളിനെയാണ് മാത്രം ആരംഭിക്കുക: +അല്ലെങ്കിൽ ഈ മോഡ്യൂളിനുതന്നെ ആരംഭിക്കുക: -**Bash:** +**ബാഷ്:** ```bash cd 02-prompt-engineering ./start.sh ``` -**PowerShell:** +**പവർ ഷെൽ:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` -രണ്ടും റൂട്ട് `.env` ഫയലിൽ നിന്നുള്ള പരിസ്ഥിതി വ്യത്യസ്തങ്ങൾ സ്വയമേധയാ ലോഡ് ചെയ്യുകയും, JAR ഫയലുകൾ ഇല്ലെങ്കിൽ നിർമ്മിക്കുകയും ചെയ്യും. +രണ്ടും സ്ക്രിപ്റ്റുകൾ സ്വയം റൂട്ടിലെ `.env` ഫയലിൽ നിന്ന് പരിസ്ഥിതി വെറിയബിളുകൾ ലോഡ് ചെയ്യും, JAR ഫയലുകൾ ഇല്ലാത്ത പക്ഷം നിർമിക്കും. -> **കുറിപ്പ്:** എല്ലാ മോഡ്യൂളുകളും മാനുവലായി ബിൽഡ് ചെയ്ത് തുടങ്ങാൻ ആഗ്രഹിക്കുന്നുവെങ്കിൽ: +> **കുറിപ്പ്:** തുടങ്ങുന്നതിന് മുമ്പ് എല്ലാ മോഡ്യൂളുകളും കൈമാന്വായി നിർമ്മിക്കാൻ നിങ്ങൾ ഇഷ്ടപ്പെടുന്നെങ്കിൽ: > -> **Bash:** +> **ബാഷ്:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell:** +> **പവർ ഷെൽ:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -ബ്രൗസറിൽ http://localhost:8083 തുറക്കുക. +http://localhost:8083 നിങ്ങളുടെ ബ്രൗസറിൽ തുറക്കുക. -**നിർത്തുവാൻ:** +**അപ്ലിക്കേഷൻ നിർത്താൻ:** -**Bash:** +**ബാഷ്:** ```bash -./stop.sh # ഈ മോഡ്യൂള് മാത്രം -# അല്ലെങ്കില് -cd .. && ./stop-all.sh # എല്ലാ മോഡ്യൂളുകളും +./stop.sh # ഈ മൂട്യൂൾ മാത്രം +# അല്ലെങ്കിൽ +cd .. && ./stop-all.sh # എല്ലാ മൂട്യൂളുകളും ``` -**PowerShell:** +**പവർ ഷെൽ:** ```powershell -.\stop.ps1 # ഈ മոդ്യൂളിൽ മാത്രം -# അല്ലെങ്കിൽ -cd ..; .\stop-all.ps1 # എല്ലാ മോട്യൂളുകളും +.\stop.ps1 # ഈ മൊഡ്യൂള്‍ മാത്രം +# അല്ലെങ്കില്‍ +cd ..; .\stop-all.ps1 # എല്ലാ മൊഡ്യൂളുകളും ``` -## ആപ്ലിക്കേഷൻ സ്ക്രീൻഷോട്ടുകൾ +## അപ്ലിക്കേഷൻ സ്ക്രീൻഷോട്ടുകൾ -ഇവിടെ പ്രാംപ്റ്റ് എൻജിനീയറിംഗ് മോഡ്യൂളിന്റെ പ്രധാന ഇന്റർഫേസ്, എട്ട് ഡിഫർന്റ് പാറ്റേണുകളും പാരിസ്റ്റിക്കൽസും വശ വെച്ചുനോക്കാം. +ഇവിടെ പ്രോമ്പ്റ്റ് എഞ്ചിനീയറിംഗ് മോഡ്യൂളിന്റെ പ്രധാന ഇന്റർഫേസ് കാണാം, എല്ലാവരും പത്തിരുപത് പാറ്റേണുകൾക്കൊപ്പം പരസ്പരം പരീക്ഷിക്കാവുന്നതാണ്. -Dashboard Home +ഡാഷ്ബോർഡ് ഹോം -*എട്ട് പ്രാംപ്റ്റ് എൻജിനീയറിംഗ് പാറ്റേണുകളും അവയുടെ സവിശേഷതകളും ഉപയോഗ സന്ദർഭങ്ങളും കാണിക്കുന്ന പ്രധാന ഡാഷ്ബോർഡ്* +*ഡാഷ്ബോർഡ് മുഖ്യപ്രവേശനം, എല്ലാ 8 പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ് പാറ്റേണുകളും അവരുടെ സവിശേഷതകളും ഉപയോഗകേസുകളും കാണിക്കുന്നു* -## പാറ്റേണുകൾ അനുഭവിക്കുക +## പാറ്റേണുകൾ പരിശോധിക്കൽ -വെബ് ഇന്റർഫേസ് വിവിധ പ്രാംപ്റ്റിംഗ് സ്ട്രാറ്റജികൾ പരീക്ഷിക്കാൻ അനുവദിക്കുന്നു. ഓരോ പാറ്റേണും വ്യത്യസ്ത പ്രശ്നങ്ങൾ പരിഹരിക്കുന്നു - അവ പരീക്ഷിച്ച് ഏത് സമീപനം എപ്പോൾ ഉത്തമം എന്നറിയുക. +വെബ് ഇന്റർഫേസ് വ്യത്യസ്ത പ്രോമ്പ്റ്റിംഗ് തന്ത്രങ്ങൾ പരീക്ഷിക്കാൻ സഹായിക്കുന്നു. ഓരോ പാറ്റേണും വ്യത്യസ്ത പ്രശ്നങ്ങൾ പരിഹരിക്കുന്നു - ഏതു സമീപനം എപ്പോൾ ഉത്തമമാണെന്ന് നോക്കൂ. -> **കുറിപ്പ്: സ്റ്റ്രീമിംഗ് vs നോൺ-സ്റ്റ്രീമിംഗ്** — ഓരോ പാറ്റേൺ പേജിലും രണ്ട് ബട്ടണുകൾക്കായി ഒരുക്കിയിട്ടുണ്ട്: **🔴 Stream Response (Live)**, ഒരു **Non-streaming** ഓപ്ഷൻ. സ്റ്റ്രീമിംഗ് Server-Sent Events (SSE) ഉപയോഗിച്ച് മോഡൽ ടോകനുകൾ റിയൽ-ടൈമിൽ ഉണ്ടാകുമ്പോൾ കാണിക്കുന്നു, അങ്ങനെ നിങ്ങള്‍ക്ക് പുരോഗതി ഉടനെ കാണാം. നോൺ-സ്റ്റ്രീമിംഗ് പൂർണ്ണ പ്രതികരണം ലഭിക്കുമ്പോൾ മാത്രമേ പ്രദർശിപ്പിക്കുകയുള്ളു. ദീർഘമായ വികാസം ആവശ്യമായ പ്രോമ്പ്റ്റുകൾക്ക് (ഉദാ. High Eagerness, Self-Reflecting Code) നോൺ-സ്റ്റ്രീമിംഗ് കോൾ ഏറെ വൈകാം — നിമിഷങ്ങൾക്കധികം — ദൃശ്യ ഫീഡ്ബാക്ക് ഒന്നുമില്ലാതെ. **സങ്കീർണ്ണ പ്രോമ്പ്റ്റുകൾ പരീക്ഷിക്കുമ്പോൾ സ്റ്റ്രീമിംഗ് ഉപയോഗിക്കുക** അതിലൂടെ മോഡൽ പ്രവർത്തിക്കുന്നത് കാണാനും റിക്വസ്റ്റ് ടൈം ഔട്ട് ആയെന്നതിന് തോന്നൽ ഒഴിവാക്കാനും കഴിയും. +> **കുറിപ്പ്: സ്ട്രീമിംഗ് vs നോണ്സ്ട്രീമിംഗ്** — ഓരോ പാറ്റേണിന്റെ പേജിലും രണ്ട് ബട്ടണുകൾ ഉണ്ട്: **🔴 Stream Response (Live)**, ഒപ്പം **നോൺ-സ്ട്രീമിംഗ്** ഓപ്‌ഷൻ. സ്ട്രീമിംഗ് Server-Sent Events (SSE) ഉപയോഗിച്ച് മോഡൽ ടോക്കൺ തിളക്കവഴി സൃഷ്ടിക്കുന്നതിനെ നേരിട്ട് വീക്ഷിക്കുന്നു, അതിൽ നിങ്ങൾക്ക് പുരോഗതി ഉടനെ കാണാം. നോൺ-സ്ട്രീമിംഗ് മുഴുവൻ പ്രതികരണം പ്രതീക്ഷിച്ചാണ് പ്രദർശിപ്പിക്കുന്നത്. ഗൗരവമുള്ള ചിന്ത ആവശ്യപ്പെടുന്ന പ്രോമ്പ്റ്റുകൾ (ഉദാ: High Eagerness, Self-Reflecting Code) നോൺ-സ്ട്രീമിംഗ് കാലാവധി വളരെ നീളാമാകാം - ചിലപ്പോൾ മിനിറ്റുകൾക്ക് വരെ - പ്രതികരണമില്ലാതെ. **സങ്കീർണ്ണ പ്രോമ്പ്റ്റുകൾ പരീക്ഷിക്കുമ്പോൾ സ്ട്രീമിംഗ് പ്രയോഗിക്കുക**; മോഡൽ പ്രവർത്തിക്കുന്നത് കാണുകയും അഭ്യർത്ഥന ടൈംസൗട്ടാകാത്തതിനുള്ള തെറ്റിദ്ധാരണ ഒഴിവാക്കുകയും ചെയ്യും. > -> **കുറിപ്പ്: ബ്രൗസർ ആവശ്യങ്ങൾ** — സ്റ്റ്രീമിംഗ് ഫീച്ചർ Fetch Streams API (`response.body.getReader()`) ഉപയോഗിക്കുന്നു, ഇത് കർശനമായ ബ്രൗസറുകൾ (Chrome, Edge, Firefox, Safari) ആവശ്യമാണ്. VS Code ലെ ഇൻബിൽറ്റ് സിംപിൾ ബ്രൗസറിൽ ഇത് പ്രവർത്തിക്കുന്നില്ല, കാരണം അതിന്റെ വെബ്‌വ്യൂ ReadableStream API പിന്തുണയ്‌ക്കുന്നില്ല. സിംപിൾ ബ്രൗസർ ഉപയോഗിക്കുമ്പോൾ നോൺ-സ്റ്റ്രീമിംഗ് ബട്ടണുകൾ സാധാരണ പ്രവർത്തിക്കും — സ്റ്റ്രീമിംഗ് ബട്ടണുകൾ മാത്രമാണ് ബാധിക്കപ്പെടുന്നത്. പൂർണ്ണ അനുഭവത്തിനായി http://localhost:8083 ഒരു പുറത്തുള്ള ബ്രൗസറിൽ തുറക്കുക. +> **കുറിപ്പ്: ബ്രൗസർ ആവശ്യകത** — സ്ട്രീമിംഗ് ഫീച്ചർ Fetch Streams API (`response.body.getReader()`) ഉപയോഗിക്കുന്നു, ഇത് പൂർണ്ണ ബ്രൗസറുകളിലാണ് പ്രവർത്തിക്കുന്നത് (ക്രോം, എഡ്ജ്, ഫയർഫോക്സ്, സഫാരി). VS Code-യിലെ ഇണങ്ങിയിട്ടുള്ള സിമ്പിൾ ബ്രൗസറിൽ ഇത് പ്രവർത്തിക്കില്ല, കാരണം അതിന്റെ വെബ്‌വ്യൂ ReadableStream API പിന്തുണക്കുന്നില്ല. സിമ്പിൾ ബ്രൗസർ ഉപയോഗിച്ചാലും നോൺ-സ്ട്രീമിംഗ് ബട്ടണുകൾ ശരിയായി പ്രവർത്തിക്കും - സ്ട്രീമിംഗ് ബട്ടണുകൾ മാത്രമാണ് ബാധിക്കപ്പെടുന്നത്. പൂർണ്ണ അനുഭവത്തിനായി http://localhost:8083 പുറത്തുള്ള ബ്രൗസറിൽ തുറക്കുക. -### തక్కువ vs ഉയർന്ന ആവേശം +### ലോ vs ഹൈ ഈജർനെസ് -തక్కువ ആവേശം ഉപയോഗിച്ച് "15% of 200 എന്താണ്?" എന്ന ഒരു ലളിതമായ ചോദ്യമുപയോഗിക്കുക. ഉടൻ തന്നെ നേരിട്ടുള്ള ഉത്തരം കിട്ടും. ഇപ്പോൾ "ഉയർന്ന ട്രാഫിക് APIക്ക് ഒരു കാഷിങ് സ്റ്റ്രാറ്റജി രൂപകൽപ്പന ചെയ്യുക" എന്ന സങ്കീർണ്ണമായ ചോദ്യത്തിന് ഉയർന്ന ആവേശം ഉപയോഗിക്കുക. **🔴 Stream Response (Live)** ക്ലിക്ക് ചെയ്ത് മോഡലിന്റെ വിശദമായ ലജിച്ചിന്തനം പദം-പദം കാണുക. ഒരേ മോഡൽ, ഒരേ ചോദ്യ ഘടന - പക്ഷേ പ്രോമ്പ്റ്റ് എത്രക്കൂട്ടം ചിന്തിക്കണമെന്ന് പറയുന്നു. +"200-ന്റെ 15% എന്താണ്?" എന്ന ലളിതമായ ചോദ്യം ലോ ഈജർനെസ് ഉപയോഗിച്ച് ചോദിക്കുക. ഉടൻ, നേരിട്ട് ഉത്തരം ലഭിക്കും. ഇപ്പോൾ "ഹൈ-ട്രാഫിക് API-യ്ക്കായി കാഷിംഗ് തന്ത്രം രൂപകൽപ്പന ചെയ്യുക" എന്നാണ് വലിയ കുറിപ്പുള്ള ചോദ്യമെങ്കിൽ, ഹൈ എജർനെസ് ഉപയോഗിക്കുക. **🔴 Stream Response (Live)** ക്ലിക്കുചെയ്യുക, മോഡലിന്റെ വിശദമായ ചിന്തകൾ ടോക്കൺവൈസ്കം പാളിച്ചുവെക്കുന്നതായി കാണുക. ഏകദേശം ഒരേ മോഡൽ, ഒരേ ചോദ്യ ഘടന - എന്നാൽ പ്രോമ്പ്റ്റ് എത്രയധികം ആഴത്തിലുള്ള ചിന്ത ആവശ്യമാണ് എന്ന് മോഡലിന് പറയുന്നു. -### ടാസ്ക് നിർവഹണവും (ടൂൾ പ്രീഅംബിൾസ്) +### ടാസ്‌ക് എക്സിക്യൂഷൻ (ടൂൾ പ്രീാംബിളുകൾ) -ബഹുഘട്ട പ്രവാഹങ്ങൾ മുൻകൂട്ടി പദ്ധതിയിടലും പുരോഗതി വിവരിക്കൽ അംഗീകരിക്കുന്നു. മോഡൽ ചെയ്യുകപോലുള്ള കാര്യങ്ങൾ വിവരിച്ച് ഓരോ ഘട്ടവും വിവരണം കൊടുക്കുകയും, ശേഷം ഫലങ്ങൾ സംഗ്രഹിക്കുകയും ചെയ്യും. +മൾട്ടി-സ്റ്റെപ്പ് പ്രവൃത്തികൾ മുൻകൂട്ടി പദ്ധതി തയ്യാറാക്കലും പുരോഗതി വിശദീകരണവുമാണ് പ്രയോജനം. മോഡൽ ചെയ്യേണ്ട കാര്യങ്ങൾ രേഖപ്പെടുത്തിയതും ഓരോ ഘട്ടവും വിശദീകരിച്ചതും, തുടർന്ന് ഫലങ്ങൾ സംഗ്രഹിച്ചതും കാണിക്കുന്നു. -### സ്വയം-പരിശോധന ചെയ്യുന്ന കോഡ് +### സ്വയം-പരാമർശിക്കുന്ന കോഡ് -"ഒരു ഇമെയിൽ പരിശോധന സർവീസ് സൃഷ്ടിക്കുക" എന്ന് ശ്രമിക്കുക. കോഡ് സൃഷ്ടിച്ച് നിർത്താതെ, മോഡൽ ഗുണനിലവാരcriterias പരീക്ഷിച്ച്, ദുർബലങ്ങൾ തിരിച്ചറിഞ്ഞ് മെച്ചപ്പെടുത്തുന്നു. കോഡ് ഉൽപാദന നിലവാരങ്ങൾ പാലിക്കുന്നവിടേയ്ക്കു വരെയുള്ള ആവർത്തനം കാണാം. +"ഇമെയിൽ സാധുത പരീക്ഷണ സേവനം സൃഷ്ടിക്കുക" എന്ന് ശ്രമിക്കുക. കോഡ് നിർമ്മിച്ച് നിർത്തുന്നതിന് പകരം, മോഡൽ കോഡ് സൃഷ്ടിക്കുകയും ഗുണനിലവാര മാനദണ്ഡങ്ങളിൽ വിലയിരുത്തുകയും ദുർബലതകൾ കണ്ടുപിടിച്ച് മെച്ചപ്പെടുത്തുകയും ചെയ്യും. കോഡ് ഉത്പാദന നിലവാരത്തിൽ എത്തിയപ്പോൾ വരെ അത് ആവർത്തിക്കുന്നു. -### ഘടനാപരമായ വിശകലനം +### ഘടനാഭാഗങ്ങൾ വീക്ഷണം -കോഡ് റിവ്യൂയ്ക്ക് സ്ഥിരമായ മൂല്യനിർണയ ഫ്രെയിംവർക്കുകൾ വേണ്ടിവരുന്നു. മോഡൽ നിർണയിക്കുമ്പോൾ സ്ഥിരം വിഭാഗങ്ങൾ (ശുദ്ധി, പണിപ്പാട്, പ്രകടനം, സുരക്ഷ) ഉപയോഗിച്ച് ഗുരുതരതാരലുകൾ ചേർത്ത് വിശകലനം ചെയ്യുന്നു. +കോഡ് റിവ്യൂകൾ സ്ഥിരം മൂല്യനിർണ്ണയ പാരിസ്ഥിതിക സംവിധാനങ്ങൾ ആവശ്യപ്പെടുന്നു. മോഡൽ നിർദ്ദിഷ്ട വിഭാഗങ്ങൾ (ശ്രദ്ധാപൂർവമായ പിഴവുകൾ, രീതികൾ, പ്രകടനം, സുരക്ഷ) ഉപയോഗിച്ച് കോഡ് വിശകലനം ചെയ്യുന്നു. -### ബഹു-ടേൺ ചാറ്റ് +### മൾട്ടി-ടേൺ ചാറ്റ് -"Spring Boot എന്താണ്?" എന്ന് ചോദിച്ച് ഉടൻ "എക്സാംപിള്‍ കാണിക്കൂ" എന്നു ചോദിക്കാം. മോഡൽ ആദ്യ ചോദ്യവും ഓർക്കുന്നു, പ്രത്യേകിച്ച് Spring Boot ഉദാഹരണം നൽകുന്നു. മെമ്മറി ഇല്ലെങ്കിൽ രണ്ടാം ചോദ്യവും വളരെ പൊറുതിമുട്ടും. +"സ്പ്രിംഗ് ബൂട്ട് എന്താണ്?" എന്ന് ചോദിച്ച് ഉടൻ തുടർന്നും "ഒരു ഉദാഹരണം കാണിക്കുക" എന്ന് ചോദിക്കുക. മോഡൽ നിങ്ങളുടെ ആദ്യ ചോദ്യം ഓർക്കുകയും പ്രത്യേകമായ സ്പ്രിംഗ് ബൂട്ട് ഉദാഹരണം നൽകുകയും ചെയ്യും. ഓർമയില്ലാതെ രണ്ടാം ചോദ്യവും അധികം വീക്ഷണരഹിതമായിരിക്കും. -### പടി-പടി ലജിച്ചിന്തനം +### ഘട്ടം-ഘട്ടം ചിന്തിച്ചുള്ള പരിഹാരം -ഒരു ഗണിത പ്രശ്നം എടുത്ത് പടി-പടി ലജിച്ചിന്തനവും തక్కువ ആവേശവും ഉപയോഗിച്ച് പരീക്ഷിക്കുക. തక్కువ ആവേശം വേഗത്തിലുള്ള മറുപടി നൽകുന്നു - എന്നാൽ സംവേദനസാധ്യത കുറവാണ്. പടി-പടി എല്ലാ കണക്കുകളും തീരുമാനങ്ങളും കാണിക്കുന്നു. +ഒരു ഗണിത പ്രശ്നം തെരഞ്ഞെടുത്ത് സ്റ്റെപ്പ്-ബൈ-സ്റ്റെപ്പ് റീസണിംഗ് ഉപയോഗിച്ച് ശ്രമിക്കുക, പിന്നെ ലോ ഈജർനെസ് ഉപയോഗി൯. ലോ ഈജർനെസ് അത്രയും വിസ്തൃതമായി ആശയവിനിമയം നൽകിയില്ല പരിശോധിക്കുന്നില്ല — വേഗത്തിൽ ഉത്തരം നൽകുന്നു. ഘട്ടം-ഘട്ടം കാണിച്ച് നൽകുന്നത് എല്ലാ കണക്കുകളും തീരുമാനങ്ങളും കാണിക്കുന്നു. ### നിയന്ത്രിത ഔട്ട്പുട്ട് -നിശ്ചിത ഫോർമാറ്റുകൾ അല്ലെങ്കിൽ വാക്കുകളുടെ എണ്ണം ആവശ്യമുള്ളപ്പോൾ, ഈ പാറ്റേൺ കഠിനമായി പാലിക്കുന്നു. വില്ലുകളായി 100 വാക്കുകളുള്ള ഒരു സംഗ്രഹം ഉദാഹരണമായി സൃഷ്ടിക്കുക. +നിർദ്ദിഷ്ട ഫോർമാറ്റ് അല്ലെങ്കിൽ വാക്കുകളുടെ എണ്ണം ആവശ്യമുണ്ടെങ്കിൽ, ഈ പാറ്റേൺ കർശനമായ പാലനം നിർബന്ധിക്കുന്നു. ബുള്ളറ്റ് പോയിന്റിൽ സമഗ്രം പൂർത്തിയായ 100 വാക്കുകളുള്ള ഒരു സംഗ്രഹം സൃഷ്ടിക്കാൻ ശ്രമിക്കുക. -## നിങ്ങൾ വാസ്തവത്തിൽ പഠിക്കുന്നത് +## നിങ്ങൾ യാഥാർത്ഥ്യത്തിൽ പഠിക്കുന്നത് -**ചിന്തയിലുള്ള ശ്രമം എല്ലാം മാറ്റുന്നു** +**ചിന്താപ്രവൃത്തിയുടെ പരിശ്രമം എല്ലാം മാറ്റും** -GPT-5.2 നിങ്ങളുടെ പ്രോമ്പ്റ്റുകൾ വഴി കംപ്യൂട്ടേഷണൽ ശ്രമം നിയന്ത്രിക്കാൻ അനുവദിക്കുന്നു. കുറവ് ശ്രമം വേഗത്തിലുള്ള മറുപടികൾക്കുംകുട്ടിയ അന്വേഷണങ്ങളും നൽകുന്നു. കൂടുതലുള്ള ശ്രമം മോഡൽ ഗഹനമായി ചിന്തനം ചെയ്ത് സമയം എടുക്കുന്നു. നിങ്ങൾ പ്രവർത്തി സങ്കീർണ്ണതക്ക് അനുയോജ്യം ആയ ശ്രമം തിരഞ്ഞെടുക്കണം - ലളിത ചോദ്യങ്ങൾക്ക് സമയം കളയാൻ വേണ്ട, സങ്കീർണ്ണ തീരുമാനം ദ്രുതമായി ഒഴിവാക്കാവുന്നതല്ല. +GPT-5.2 നിങ്ങളുടെ പ്രോമ്പ്റ്റുകൾ വഴി കണക്കാക്കലിന്റെ ശ്രമം നിയന്ത്രിക്കാൻ സഹായിക്കു്. കുറഞ്ഞ പരിശ്രമം വേഗത്തിലുള്ള, കുറഞ്ഞ അന്വേഷണം ഉള്ള പ്രതികരണങ്ങൾ നൽകുന്നു. ഉയർന്ന പരിശ്രമം മോഡലിന് കൂടുതൽ ആഴത്തിലുള്ള ചിന്തയ്ക്ക് സമയമെടുക്കാൻ ഉളവാക്കുന്നു. നിങ്ങൾ പഠിക്കുന്നത് പ്രവർത്തിയുടെ സങ്കീർണ്ണതയ്ക്ക് അനുയോജ്യമായ പരിശ്രമം തിരഞ്ഞെടുക്കുക എന്നതാണ് - ലളിതമായ ചോദ്യങ്ങളിൽ സമയവും ഊർജ്ജവും നഷ്ടപ്പെടുത്തരുത്, കടുത്ത തീരുമാനങ്ങളിൽ പെട്ടെന്ന് ഉപയോഗപ്പെടുത്തരുത്. -**ഘടന പെരുമാറ്റത്തെ നയിക്കുന്നു** +**ഘടന പെരുമാറ്റത്തെ മാർഗ്ഗനിർദ്ദേശം ചെയ്യുന്നു** -പ്രോമ്പ്റ്റുകളിൽ കാണുന്ന XML ടാഗുകൾ ശ്രദ്ധിക്കുക? അവ അലങ്കാരമല്ല. മോഡലുകൾ ഘടനാപരമായ നിർദ്ദേശങ്ങൾ കൂടുതൽ വിശ്വസ്തമായി പിന്തുടരുമെന്നർത്ഥം. ബഹുഘട്ട പ്രക്രിയകൾ അല്ലെങ്കിൽ സങ്കീർണ്ണ ലജിക് ആവശ്യമായപ്പോൾ, ഘടന മോഡൽക്ക് എവിടെ പോവുകയാണ്, അടുത്തത് എന്താണെന്നും ട്രാക്ക് ചെയ്യാൻ സഹായിക്കുന്നു. താഴെയുള്ള ചിത്രം മികച്ച ഘടനയുള്ള പ്രോമ്പ്റ്റിന്റെ ഭാഗങ്ങൾ, ``, ``, ``, ``, `` എന്നിവ നിങ്ങളുടെ നിർദ്ദേശങ്ങൾ വ്യക്തമാക്കിയ വിഭാഗങ്ങളായി എങ്ങനെ ക്രമീകരിക്കുന്നു എന്ന് കാണിക്കുന്നു. +പ്രോമ്പ്റ്റുകളിലെ XML ടാഗുകൾ ശ്രദ്ധിച്ചിട്ടുണ്ടോ? അവ അലങ്കാരമല്ല. മോഡലുകൾ ഘടനാപരമായ നിർദ്ദേശങ്ങൾ സൗകര്യപ്രദമായി പിന്തുടരുന്നു. മൾട്ടി-സ്റ്റെപ്പ് പ്രക്രിയകൾ അല്ലെങ്കിൽ സങ്കീർണ്ണ തർത്തമതങ്ങള്‍ ആവശ്യമായപ്പോൾ, ഘടന മോഡൽ എവിടെ എത്തി, എന്ത് വരാനിരിക്കുന്നുവെന്ന് ട്രാക്ക് ചെയ്യാൻ സഹായിക്കുന്നു. താഴെയുള്ള രേഖാചിത്രം ഘടനാപരമായ പ്രോമ്പ്റ്റിന്റെ ഭാഗങ്ങൾ ``, ``, ``, ``, `` എന്നിവ വിശദീകരിക്കുന്നു. -Prompt Structure +പ്രോമ്പ്റ്റ് ഘടന -*വ്യക്തമായ വിഭാഗങ്ങൾ ഉള്ള, XML പ്രദേശവത്കരണത്തിന് സാമാന്യമായ മികച്ച പ്രോമ്പ്റ്റിന്റെ ഘടനാനിക്* +*വ്യക്തമായ ഭാഗങ്ങളും XML ശൈലിയിലുള്ള ക്രമീകരണവുമുള്ള നല്ല ഘടനയുള്ള പ്രോംബ്‌റ്റ് അനാഡമിക്ക്* -**സ്വയം വിലയിരുത്തലിലൂടെ ഗുണമേന്മ** +**സ്വയം-പരീക്ഷണത്തിലൂടെ ഗുണമേൻമ** -സ്വയം-പരിശോധന മാതൃകകൾ ഗുണനിലവാരcriterias വ്യക്തമായി വ്യക്തമാക്കുകയാണ്. മോഡലിൽ "ശരി ചെയ്യുമോ" എന്ന് ആശിക്കുന്നു എന്ന പകരം, നിങ്ങൾ "ശരി" എന്ന് എന്ത് അർത്ഥമെന്ന് വ്യക്തമാക്കുന്നു: ശരിയായ ലജിക്, തെറ്റ് കൈകാര്യം, പ്രകടനം, സുരക്ഷ. മോഡൽ താനും തന്റെ output വിലയിരുത്തുകയും മെച്ചപ്പെടുത്തുകയും ചെയ്യുന്നു. ഇത് കോഡ് നിർമാണത്തെ ഭാഗ്യം പോലെ അല്ല, ഒരു പ്രക്രിയയാക്കുന്നു. +സ്വയം-പരാമർശിക്കുന്ന പാറ്റേണുകൾ ഗുണനിലവാര മാനദണ്ഡങ്ങൾ വ്യക്തമാക്കുന്നതിലൂടെ പ്രവർത്തിക്കുന്നു. മോഡൽ "ഇത്രെന്നും ശരിയായി ചെയ്യും" എന്ന് പ്രതീക്ഷിക്കാനാകാതെ, നിങ്ങൾക്ക് ശരിയായതു എന്താണെന്ന്: ശരിയായ തത്വം, പിഴവ് കൈകാര്യം, പ്രകടനം, സുരക്ഷ എന്നീ ക്രൈറ്റീരിയകൾ വ്യക്തമാക്കാം. മോഡൽ സ്വയം തന്നെ ആ ഉൽപ്പന്നം മൂല്യനിർണ്ണയം ചെയ്തു മെച്ചപ്പെടുത്താൻ കഴിയും. ഇത് കോഡ് നിർമ്മാണത്തെ ലോട്ടറിയിൽ നിന്ന് പ്രക്രിയയാക്കുന്നു. -**സന്ദർഭം പരിധിയുള്ളതാണ്** +**സന്ദർഭം പരിമിതമാണ്** -ബഹു-ടേൺ സംഭാഷണങ്ങൾ ഓരോ അഭ്യർത്ഥനയിലും സന്ദേശ ചരിത്രം ഉൾപ്പെടുത്തി പ്രവർത്തിക്കുന്നു. എന്നാൽ പരിധിയുണ്ട് - ഓരോ മോഡലിന്റെയും പരമാവധി ടോക്കൺ എണ്ണം. സംഭാഷണം വളരുമ്പോൾ, പ്രാധാന്യമുള്ള സന്ദർഭം പരിരക്ഷിക്കാൻ തന്ത്രങ്ങൾ ഉപയോഗിക്കണം, അതിന്റെ പരിധി മിർക്കും മുമ്പ്. ഈ മോഡ്യൂൾ മെമ്മറി എങ്ങനെ പ്രവർത്തിക്കുന്നു എന്ന് കാണിക്കുന്നു; പിന്നീട് എപ്പോൾ സംഗ്രഹിക്കണം, എപ്പോൾ മറക്കണം, എപ്പോൾ വീണ്ടെടുക്കണം എന്നതും പഠിക്കും. +മൾട്ടി-ടേൺ സംഭാഷണങ്ങൾ ഓരോ അഭ്യർത്ഥനയോടും സന്ദേശ ചരിത്രം ഉൾപ്പെടുത്തിയതിലൂടെ പ്രവർത്തിക്കുന്നു. പക്ഷെ അതിനൊരു പരിധിയുണ്ട് - എല്ലാ മോഡലുകൾക്കും ടോക്കൺ പരമാവധി എണ്ണം ഉണ്ട്. സംഭാഷണങ്ങൾ ഉയർന്നുപോകുമ്പോൾ, പ്രാസംഗിക സന്ദർഭം സൂക്ഷിക്കാൻ നിങ്ങൾ വഴികൾ കണ്ടെത്തണം, പരമാവധി പരിധി മറികടക്കാതെ. ഈ മോഡ്യൾ ഓർമ്മ എന്താണെന്നു നിങ്ങൾക്ക് കാണിക്കും; പിന്നീട് ഏതൊക്കെ സമയങ്ങളിൽ സംഗ്രഹിക്കണം, മറക്കണം, തിരികെ കണ്ടെത്തണം എന്നും പഠിപ്പിക്കും. -## അടുത്ത് ചോദ്യങ്ങൾ +## വരും ഘട്ടങ്ങൾ **അടുത്ത മോഡ്യൂൾ:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**നാവിഗേഷൻ:** [← മുന്‍: Module 01 - പരിചയം](../01-introduction/README.md) | [പ്രധാനത്തിലേക്ക് തിരിച്ചുപോവുക](../README.md) | [അടുത്തത്: Module 03 - RAG →](../03-rag/README.md) +**നാവിഗേഷൻ:** [← മുമ്പ്: മോഡ്യൂൾ 01 - പരിചയം](../01-introduction/README.md) | [പ്രധാനത്തിലേക്ക് തിരികെ](../README.md) | [അടുത്തത്: മോഡ്യൂൾ 03 - RAG →](../03-rag/README.md) --- -**മൊഴിമാറ്റം സംബന്ധിച്ച അറിയിപ്പ്**: -ഈ പ്രമാണം AI ഭാഷാന്തര സേവനമായ [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് ഭാഷാന്തരം ചെയ്യപ്പെട്ടതാണ്. ഞങ്ങൾ നിഷ്പക്ഷതയ്ക്ക് ശ്രമിക്കുന്നുണ്ടെങ്കിലും, യന്ത്രം വഴിയുള്ള ഭാഷാന്തരത്തിൽ പിശകുകൾ თუ തെറ്റിദ്ധാരണകൾ ഉണ്ടാകാമെന്ന് ദയവായി ശ്രദ്ധിക്കുക. പ്രമാണത്തിന്റെ ഒറിജിനൽ ഭാഷയിൽ ഉള്ള പതിപ്പ് മാത്രമേ അധികൃത ഉറവിടമാകൂ. നിർണ്ണായകമായ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ ഭാഷാന്തരം അനുശാസിക്കപ്പെടുന്നു. ഈ ഭാഷാന്തരവുമായി ബന്ധപ്പെട്ട് സംഭവിച്ച ഏതെങ്കിലും തെറ്റിദ്ധാരണകൾക്കും ഞങ്ങൾ ഉത്തരവാദികളല്ല. +**അറിയിപ്പ്**: +ഈ രേഖ AI പരിഭാഷാ സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് പരിഭാഷപ്പെടുത്തിയതാണ്. ഞങ്ങൾ കൃത്യതയ്ക്കായി ശ്രമിക്കുന്നുവെങ്കിലും, ഓട്ടോമേറ്റഡ് പരിഭാഷകളിൽ പിഴവുകൾ അല്ലെങ്കിൽ തെറ്റായ വിവരങ്ങൾ ഉണ്ടാകാൻ സാധ്യതയുണ്ട്. അതിന്റെ സ്വാഭാവിക ഭാഷയിലുള്ള അസൽ രേഖയാണ് പ്രാമാണികമായ ഉറവിടമായി പരിഗണിക്കേണ്ടത്. നിർണായകമായ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ പരിഭാഷ ശുപാർശ ചെയ്യുന്നു. ഈ പരിഭാഷ ഉപയോഗിച്ച് ഉണ്ടാകുന്ന തെറ്റിദ്ധാരണകൾ അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾക്കായി ഞങ്ങൾ ഉത്തരവാദികളല്ല. \ No newline at end of file diff --git a/translations/ml/03-rag/README.md b/translations/ml/03-rag/README.md index d0c00c02d..6c6c1f780 100644 --- a/translations/ml/03-rag/README.md +++ b/translations/ml/03-rag/README.md @@ -1,144 +1,145 @@ -# Module 03: RAG (Retrieval-Augmented Generation) - -## Table of Contents - -- [Video Walkthrough](../../../03-rag) -- [What You'll Learn](../../../03-rag) -- [Prerequisites](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Does This Tutorial Use?](../../../03-rag) -- [How It Works](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload a Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matters](../../../03-rag) -- [Next Steps](../../../03-rag) - -## Video Walkthrough - -ഈ മോഡ്യൂളുമായി തുടങ്ങുന്നത് എങ്ങനെ എന്നത് വിശദീകരിക്കുന്ന ലൈവ് സെഷൻ കാണുക: +# Module 03: RAG (റിട്രീവൽ-ഓഗ്മെന്റഡ് ജനറേഷൻ) + +## സൂചിക + +- [വിഡിയോ വോക്‌ത്രൂ](#വിഡിയോ-വോക്‌ത്രൂ) +- [നീ എന്തൊക്ക പഠിക്കുമെന്ന്](#നീ-എന്തൊക്ക-പഠിക്കുമെന്ന്) +- [പൂർവാവശ്യങ്ങൾ](#മുൻ‌ആവശ്യകതകൾ) +- [RAG മനസ്സിലാക്കൽ](#rag-മനസ്സിലാക്കൽ) + - [ഈ ടൂട്ടോറിയൽ ഉപയോഗിക്കുന്നത് ഏത് RAG സമീപനമാണ്?](#ഈ-ടൂട്ടോറിയൽ-ഉപയോഗിക്കുന്നത്-ഏത്-rag-സമീപനമാണ്) +- [ഇത് എങ്ങനെ പ്രവർത്തിക്കുന്നു](#ഇത്-എങ്ങനെ-പ്രവർത്തിക്കുന്നു) + - [ഡോക്യുമെന്റ് പ്രോസസ്സ് ചെയ്യൽ](#ഡോക്യുമെന്റ്-പ്രോസസ്സ്-ചെയ്യൽ) + - [എംബെഡ്ഡിംഗുകൾ സൃഷ്ടിക്കൽ](#എംബെഡ്ഡിംഗുകൾ-സൃഷ്ടിക്കൽ) + - [സെമാന്റിക് തിരയൽ](#സെമാന്റിക്-തിരയൽ) + - [ഉത്തരം സൃഷ്ടിക്കൽ](#ഉത്തര-വികസനം) +- [ആപ്ലിക്കേഷൻ പ്രവർത്തിപ്പിക്കുക](#ആപ്ലിക്കേഷൻ-പ്രവർത്തിപ്പിക്കുക) +- [ആപ്ലിക്കേഷൻ ഉപയോഗിക്കൽ](#ആപ്ലിക്കേഷൻ-ഉപയോഗിക്കൽ) + - [ഒരു ഡോക്യുമെന്റ് അപ്‌ലോഡ് ചെയ്യുക](#ഒരു-ഡോക്യുമെന്റ്-അപ്‌ലോഡ്-ചെയ്യുക) + - [ചോദ്യങ്ങൾ ചോദിക്കുക](#ചോദ്യങ്ങൾ-ചോദിക്കുക) + - [മൂല സ്രോത് റഫറൻസുകൾ പരിശോധിക്കുക](#ഉറവിട-സൂചനകൾ-പരിശോധിക്കുക) + - [ചോദ്യങ്ങളുമായി പരീക്ഷണം നടത്തുക](#ചോദ്യങ്ങളോടു-പരീക്ഷണം-നടത്തുക) +- [പ്രധാന ആശയങ്ങൾ](#പ്രധാന-ആശയങ്ങൾ) + - [ചങ്കിംഗ് സ്ട്രാറ്റജ PrizeX](#ഫക്സ്-ചെയ്യൽ-രീതി) + - [സാദൃശ്യ സ്കോറുകൾ](#സാദൃശ്യമാനങ്ങൾ) + - [ഇൻ-മെമ്മറി സ്റ്റോറേജ്](#ഇൻ-മെമ്മറി-സംഭരണം) + - [കോൺടെക്സ്‌ട് വിൻഡോ മാനേജ്‌മെന്റ്](#പരിസര-വിൻഡോ-മാനേജ്‌മെന്റ്) +- [എപ്പോൾ RAG പ്രധാനമാണ്](#rag-നല്ലപ്പോൾ) +- [മുന്നോട്ടുള്ള ചുവടുകൾ](#അടുത്തപടി) + +## വിഡിയോ വോക്‌ത്രൂ + +ഈ മോഡ്യൂളുമായി എങ്ങനെ ആരംഭിക്കാമെന്നു വിശദീകരിക്കുന്ന ലൈവ് സെഷൻ കാണുക: RAG with LangChain4j - Live Session -## What You'll Learn +## നീ എന്തൊക്ക പഠിക്കുമെന്ന് -മുന്‍ മോഡ്യൂളുകളില്‍,നിങ്ങള്‍ എഐയുമായി സംവാദം നടത്തുകയും നിങ്ങളുടെ പ്രാപ്തങ്ങള്‍ കാര്യക്ഷമമായി ഘടിപ്പിക്കാനും പഠിച്ചു. പക്ഷേ ഒരു അടിസ്ഥാനപരമായ പരിമിതി ഉണ്ട്: ഭാഷ മോഡലുകള്‍ക്ക് പരിശീലന സമയത്ത് അവര്‍ പഠിച്ച വസ്തുതകള്‍ മാത്രമേ അറിയാവൂ. നിങ്ങളുടെ കമ്പനിയുടെ നയങ്ങള്‍, നിങ്ങളുടെ പ്രോജക്ട് ഡോക്യുമെന്റേഷന്‍, അല്ലെങ്കിൽ അവര്‍ ട്രെയിൻ ചെയ്തിട്ടില്ലാത്ത ഏതെങ്കിലും വിവരങ്ങള്‍ സംബന്ധിച്ചുള്ള ചോദ്യങ്ങള്‍ക്ക് അവര്‍ ഉത്തരം നല്‍കാനാകില്ല. +മുൻവിട്ട മോഡ്യൂളുകളിൽ, നീ എഐയുമായി സംവദിക്കുന്നത് എങ്ങനെ പ്രാഖ്യാതമാക്കുകയും പ്രോമ്പ്റ്റുകൾ ഫലപ്രദമായി ഘടിപ്പിക്കയും ചെയ്യുവാൻ പഠിച്ചു. പക്ഷെ ഒരു മൗലികമായ പരിമിതമാണ്: ഭാഷ മോഡലുകൾ തങ്ങളിലേക്ക് പരിശീലന സമയത്ത് നേടിയ അറിവുകൾ മാത്രമേ അറിയൂ. നിങ്ങളുടെ കമ്പനി നയങ്ങൾ, പ്രോജക്റ്റ് ഡോക്യുമെന്റേഷൻ, അല്ലെങ്കിൽ പരിശീലനത്തിൽ ഉൾപ്പെടുത്തിയിട്ടില്ലാത്ത വിവരങ്ങളെക്കുറിച്ച് അവർക്ക് ചോദ്യങ്ങൾക്ക് ഉത്തരം നൽകാൻ സാധിക്കില്ല. -RAG (Retrieval-Augmented Generation) ഈ പ്രശ്‌നം പരിഹരിക്കുന്നു. മോഡലിനെ നിങ്ങളുടെ വിവരങ്ങള്‍ പഠിപ്പിക്കാന്‍ ശ്രമിക്കുന്നതിന് പകരം (അത് ചെലവേറിയതും യാഥാര്‍ത്ഥ്യവുമല്ലാത്തതും ആണ്), നിങ്ങള്‍ക്ക് നിങ്ങളുടെ ഡോക്യുമെന്റുകളില്‍ തിരയാനുള്ള കഴിവ് നല്‍കുന്നു. ആരെങ്കില്‍ ചോദിക്കുമ്പോളും, സിസ്റ്റം ബന്ധപ്പെട്ട വിവരങ്ങള്‍ കണ്ടെത്തുകയും അവ പ്രോംപ്റ്റിലൊടുക്കുകയും ചെയ്യും. മോഡല്‍ പിന്നീട് ആ തിരഞ്ഞെടുത്ത പശ്ചാത്തലത്തെ അടിസ്ഥാനമാക്കി ഉത്തരം നല്‍കുന്നു. +RAG (റിട്രീവൽ-ഓഗ്മെന്റഡ് ജനറേഷൻ) ഈ പ്രശ്നം പരിഹരിക്കുന്നു. മോഡലിനോട് നിങ്ങളുടെ വിവരങ്ങൾ പഠിപ്പിക്കാൻ ശ്രമിക്കുന്നതിന് പകരം (അതുകൂടാതെ അതിവ്യയംമാകുകയും പ്രായോഗികമല്ലാതാകുകയും ചെയ്യും), നിങ്ങൾ മോഡലിന് നിങ്ങളുടെ ഡോക്യുമെന്റുകൾ തിരയാനുള്ള കഴിവ് നൽകുന്നു. ആരെങ്കിലും ചോദ്യം ചേർത്താൽ, സിസ്റ്റം ബന്ധപ്പെട്ട വിവരങ്ങൾ കണ്ടെത്തി പ്രോമ്പ്റ്റിൽ ഉൾപ്പെടുത്തുന്നു. പിന്നീട് മോഡൽ ആ റിട്ട്രീവുചെയ്‌ത കോൺടെക്റ്റ് അടിസ്ഥാനമാക്കി ഉത്തരം നൽകുന്നു. -RAG-നെ മോഡലിന് ഒരു റഫറൻസ് ലൈബ്രറി നല്‍കുന്ന രീതിയെന്നായി ചിന്തിക്കുക. നിങ്ങൾ ചോദിക്കുന്നത്: +RAG നെ മോഡലിന് ഒരു റഫറൻസ് ലൈബ്രറിയായി ധരിപ്പിക്കുക. നിങ്ങൾ ചോദ്യം ചേർക്കുമ്പോൾ സിസ്റ്റം: -1. **User Query** - നിങ്ങൾ ചോദ്യമുയര്‍ത്തുന്നു -2. **Embedding** - നിങ്ങളുടെ ചോദ്യത്തെ വെക്ടറായി മാറ്റുന്നു -3. **Vector Search** - സമാനമായ ഡോക്യുമെന്റ് ചങ്കുകള്‍ കണ്ടെത്തുന്നു -4. **Context Assembly** - പ്രസക്തമായ ചങ്കുകള്‍ പ്രോംപ്റ്റിലേക്ക് കൂട്ടിച്ചേർക്കുന്നു -5. **Response** - LLM ആ പശ്ചാത്തലത്തെ അടിസ്ഥാനമാക്കി ഉത്തരം സൃഷ്ടിക്കുന്നു +1. **ഉപയോക്തൃ ചോദ്യങ്ങൾ** - നിങ്ങൾ ചോദ്യം ചേർക്കുന്നു +2. **എംബെഡ്ഡിംഗ്** - നിങ്ങളുടെ ചോദ്യത്തെ വെക്ടറിലാക്കി മാറ്റുന്നു +3. **വെക്ടർ തിരയൽ** - സമാന ഡോക്യുമെന്റ് ചങ്കുകൾ കണ്ടെത്തുന്നു +4. **കോൺടെക്സ്‌ട് അസംബ്ലി** - ബന്ധപ്പെട്ട ചങ്കുകൾ പ്രോമ്പ്റ്റിൽ ചേർക്കുന്നു +5. **പ്രതികരണം** - മോഡൽ കോൺടെക്റ്റ് അടിസ്ഥാനമാക്കി ഉത്തരം സൃഷ്ടിക്കുന്നു -ഇത് മോഡലിന്റെ പ്രതികരണങ്ങള്‍ പരിശീലന ജ്ഞാനത്തിലല്ല, നിങ്ങളുടെ യഥാർത്ഥ ഡാറ്റയിൽ നിശ്ചയിക്കുന്നു. +ഇത് മോഡലിന്റെ മറുപടികൾ പാരമ്പര്യ പരിശീലന അറിവിൽ ആശ്രയിക്കാതെ നിന്റെ യഥാർത്ഥ ഡാറ്റയിൽ ആസ്പദമാക്കുന്നു. -## Prerequisites +## മുൻ‌ആവശ്യകതകൾ -- പൂർത്തിയായി [Module 00 - Quick Start](../00-quick-start/README.md) (പിന്നീട് ഈ മോഡ്യൂളിൽ സന്ദർശിക്കുന്ന എസി RAG ഉദാഹരണത്തിന്) -- പൂർത്തിയായി [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI വിഭവങ്ങൾ താങ്കൾ വിന്യസിച്ചിരിക്കുന്നു, ഉൾപ്പെടെ `text-embedding-3-small` embedding മോഡൽ) -- റൂട്ടിലുള്ള `.env` ഫയൽ Azure ക്രെഡൻഷ്യലുകളോടെ (Module 01-ലുള്ള `azd up` കമ്മാൻഡ് സൃഷ്ടിച്ചത്) +- പൂർത്തിയാക്കിയ [Module 01 - നിർദ്ദേശം](../01-introduction/README.md) (Azure OpenAI റിസോഴ്‌സുകൾ വിന്യസിച്ചിട്ടുണ്ട്, `text-embedding-3-small` എമ്പെഡ്ഡിംഗ് മോഡൽ ഉൾപ്പെടെ) +- ആഴൂർ ക്രെഡൻഷ്യലുകൾ അടങ്ങിയ `.env` ഫയൽ റൂട്ടു ഡയറക്ടറിയിൽ (Module 01ൽ `azd up` കമാൻഡ് ഉപയോഗിച്ച് ഉണ്ടാക്കിയിരിക്കുന്നു) -> **Note:** നിങ്ങൾ Module 01 പൂർത്തിയാക്കിയിട്ടില്ലെങ്കിൽ, ആദ്യം അവിടെ നൽകിയ വിന്യാസ നിർദ്ദേശങ്ങൾ പിന്തുടരുക. `azd up` കമാൻഡ് ഈ മോഡ്യൂളിൽ ഉപയോഗിക്കുന്ന GPT ചാറ്റ് മോഡലും എम्बഡിംഗ് മോഡലും വിന്യസിക്കുന്നു. +> **കുറിപ്പ്:** Module 01 പൂർത്തിയാക്കിയിട്ടില്ലെങ്കിൽ əvvəl deployment നിർദ്ദേശങ്ങൾ അവിടെ തന്നെ പാലിക്കുക. `azd up` കമാൻഡ് GPT ചാറ്റ് മോഡലും ഈ മോഡ്യൂളിൽ ഉപയോഗിക്കുന്ന എമ്പെഡ്ഡിംഗ് മോഡലും വിതരണം ചെയ്യുന്നു. -## Understanding RAG +## RAG മനസ്സിലാക്കൽ -താഴെ കാണുന്ന ചിത്രരചന RAGയുടെ പ്രധാന ആശയം സാന്ദർഭ്യപ്പെടുത്തുന്നു: മോഡലിന്റെ പരിശീലന ഡാറ്റയ്ക്ക് മാത്രം ആശ്രയിക്കാതെ, RAG ഓരോ ഉത്തരം സൃഷ്ടിക്കുന്നതിന് മുമ്പായി നിങ്ങളുടെ ഡോക്യുമെന്റുകളുമായി ഉപദേശ ലൈബ്രറി പോലെയാണ് പ്രവർത്തിക്കുന്നത്. +താഴെ കാണുന്ന ഡിസൈഗ്രാം പ്രധാന ആശയം വ്യക്തമാക്കുന്നു: മോഡലിന്റെ പരിശീലന ഡാറ്റയിലേക്കു മാത്രമേ ആശ്രയിക്കുന്നുള്ളൂ എന്ന് പകരം, RAG നിങ്ങളുടെ ഡോക്യുമെന്റുകളുടെ റഫറൻസ് ലൈബ്രറി നൽകുന്നു അതിലൂടെ ഓരോ ഉത്തരം സൃഷ്ടിക്കുന്നതിന് മുമ്പായി പരിശോധിക്കാൻ. What is RAG -*ഈ ചിത്രരചന സാധാരണ LLM (പിന്നിലെ ഡാറ്റയിൽ നിന്നും ഗസ്സ് ചെയ്യുന്നവ)യും RAG-ഉൽപ്പന്ന LLM (ആദ്യം നിങ്ങളുടെ ഡോക്യുമെന്റുകള്‍ പരിശോധിക്കുന്നവ) തമ്മിലുള്ള വ്യത്യാസം കാണിക്കുന്നു.* +*ഈ ഡിസൈഗ്രാം സ്റ്റാൻഡേർഡ് LLM (പഠന ഡാറ്റയിൽ നിന്ന് അനുമാനിക്കുന്നത്) യും RAG-ഉം പിന്തുണയുള്ള LLM (നിങ്ങളുടെ ഡോക്യുമെന്റുകൾ ആദ്യം പരിശോധിക്കുന്നത്) തമ്മിലുള്ള വ്യത്യാസം കാണിക്കുന്നു.* -ഇപ്പോൾ, ഓരോ ഘട്ടവും എങ്ങനെ ബന്ധിപ്പിക്കപ്പെടുന്നു എന്ന് നോക്കൂ. ഒരു ഉപയോക്താവിന്റെ ചോദ്യമുട്ടി നാലു ഘട്ടങ്ങൾ വഴി സഞ്ചരിക്കുന്നു — embedding, vector search, context assembly, answer generation — ഓരോതും മുൻവഴികാട്ടലിന് തുടർച്ചയായാണ്: +ഇതാ മുഴുവൻ ഘടകങ്ങളുടെ എങ്ങനെ ബന്ധപ്പെട്ടിരിക്കുന്നു എന്നത്. ഒരു ഉപയോക്താവിന്റെ ചോദ്യത്തെ നാല് ഘട്ടങ്ങളിലൂടെ കടന്നുപോകുന്നു — എംബെഡ്ഡിംഗ്, വെക്ടർ തിരയൽ, കോൺടെക്സ്‌ട് അസംബ്ലി, ഉത്തരം സൃഷ്ടിക്കൽ — ഓരോന്നും മുന്‍ഗാമി ഘട്ടത്തെ അടിസ്ഥാനമാക്കിയുള്ളതാണ്: RAG Architecture -*ഈ ചിത്രരചന അവധാനം RAG പൈപ്പ്ലൈൻ കാണിക്കുന്നു — ഉപയോക്താവിന്റെ ചോദ്യം embedding, vector search, context assembly, answer generation എന്നിവ വഴി കടക്കുന്നു.* +*ഈ ഡിസൈഗ്രാം മുഴുവൻ RAG പൈപ്പ്ലൈൻ കാണിക്കുന്നു — ഉപയോക്തൃ ചോദ്യത്തെ എംബെഡ്ഡിംഗ്, വെക്ടർ തിരയൽ, കോൺടെക്സ്‌ട് അസംബ്ലി, ഉത്തരം സൃഷ്ടിക്കൽ വഴിയും കടന്നുപോകുന്നു.* -ഈ മോഡ്യൂള്‍ ബാക്കിയുള്ള വീതം ഓരോ ഘട്ടവും വിശദമായി കാണിക്കും, നിങ്ങൾക്ക് കോഡ് ഓടിച്ച് മാറ്റാം. +ഈ മോഡ്യൂളിൽ ശേഷിക്കുന്ന ഭാഗം ഓരോ ഘട്ടവും വിശദമായി പദതന്ത്രം കൊണ്ട് ഉളവാക്കുകയും നിങ്ങൾ പ്രവർത്തിപ്പിക്കാനും മാറ്റിസ്ഥാപിക്കാനും കഴിയുന്ന കോഡും ഉൾപ്പെടുന്നു. -### Which RAG Approach Does This Tutorial Use? +### ഈ ടൂട്ടോറിയൽ ഉപയോഗിക്കുന്നത് ഏത് RAG സമീപനമാണ്? -LangChain4j RAG നടപ്പാക്കാൻ മൂന്ന് രീതികൾ നൽകുന്നു, ഓരോതും വ്യത്യസ്ത ലെവൽ അപ്‌ട്രാക്‌ഷനോടൊപ്പം. താഴെ കാണുന്ന ചിത്രരചന അവ തമ്മിൽ താരതമ്യം ചെയ്യുന്നു: +LangChain4j RAG നടപ്പാക്കുന്നതിന് മൂന്ന് വഴികൾ വാഗ്ദാനം ചെയ്യുന്നു, ഓരോന്നും വ്യത്യസ്ത പരസ്യ നിലവാരങ്ങളുമായി. താഴെയുള്ള ഡിസൈഗ്രാം അവ താരതമ്യം ചെയ്യുന്നു: Three RAG Approaches in LangChain4j -*ഈ ചിത്രരചന LangChain4j-യിലെ മൂന്ന് RAG സമീപനങ്ങളെ — Easy, Native, Advanced — താരതമ്യം ചെയ്യുന്നു, അവയുടെ പ്രധാന ഘടകങ്ങളും ഉപയോഗസമയം.* +*ഈ ഡിസൈഗ്രാം LangChain4j-യിലെ മൂന്ന് RAG സമീപനങ്ങളും — എസി, നേറ്റീവ്, അഡ്വാൻസ്ഡ് — അവയുടെ പ്രധാന ഘടകങ്ങളോടൊപ്പം ഏത് സാഹചര്യത്തിൽ ഉപയോഗിക്കണമെന്നും കാണിക്കുന്നു.* -| Approach | എന്ത് ചെയ്യുന്നു | വാണിജ്യ തന്ത്രം | +| സമീപനം | Դաമയം | വ്യാപാരം | |---|---|---| -| **Easy RAG** | എല്ലാം സ്വയം `AiServices`-നും `ContentRetriever`-നും വഴി കൈകാര്യം ചെയ്യുന്നു. നിങ്ങൾ ഒരു ഇന്റർഫേസ് ചിലിട്ട്, റെട്രീവർ ചേർത്ത്, LangChain4j എമ്പഡ്ഡിംഗ്, തിരയൽ, പ്രോംപ്റ്റ് രചന പിന്നിൽ നിയന്ത്രിക്കുന്നു. | കുറഞ്ഞ കോഡ്, പക്ഷേ ഓരോ ഘട്ടവും കാണാനാകില്ല. | -| **Native RAG** | നിങ്ങൾ തന്നെ embedding മോഡൽ വിളിക്കുന്നു, സ്റ്റോർ തിരയുന്നു, പ്രോംപ്റ്റ് തയാറാക്കുന്നു, ഉത്തരം സൃഷ്ടിക്കുന്നു — ഓരോചടങ്ങും വ്യക്തമായി. | കൂടുതൽ കോഡ്, എന്നാൽ ഓരോ ഘട്ടവും ദൃശ്യമാണ്, മാറ്റം ചെയ്യാം. | -| **Advanced RAG** | `RetrievalAugmentor` ഫ്രെയിംവർക്കിനൊപ്പം ചേർക്കാവുന്ന ക്വറി ട്രാൻസ്ഫോർമേഴ്സ്, റൗട്ടേഴ്സ്, റീ-റാങ്കേഴ്‌സ്, കണ്ഠന്റ് ഇഞ്ചെക്ടർമാർ ഉപയോഗിച്ച് പ്രൊഡക്ഷൻ ഗ്രേഡ് പൈപ്പ്ലൈൻ. | അത്യധിക സ്വാതന്ത്ര്യം, എന്നാൽ വലിയ സങ്കീർണ്ണത. | +| **എസി RAG** | എല്ലാം ഓട്ടോമാറ്റിക്കായി `AiServices` ഉം `ContentRetriever` ഉം വഴി കണക്ട് ചെയ്യുന്നു. ഒരു ഇന്റർഫേസ് അനോട്ടേറ്റ് ചെയ്യുന്നു, ഒരു റിട്ട്രീവർ ചേർക്കുന്നു, LangChain4j എംബെഡ്ഡിംഗ്, തിരയൽ, പ്രോമ്പ്റ്റ് അസംബ്ലി എന്നിവ പിന്നിൽ കൈകാര്യം ചെയ്യുന്നു. | കുറഞ്ഞ കോഡ്, പക്ഷെ ഓരോ ഘട്ടവും നിങ്ങൾക്ക് കാണാനില്ല. | +| **നേറ്റീവ് RAG** | നിങ്ങൾ സ്വയം എംബെഡ്ഡിംഗ് മോഡൽ വിളിച്ച്, സ്റ്റോർ തിരഞ്ഞ്, പ്രോമ്പ്റ്റ് നിർമ്മിച്ച്, ഉത്തരം സൃഷ്ടിക്കുന്നു — ഓരോ ഘട്ടവും വ്യക്തമായതും തത്സമയം. | കൂടുതൽ കോഡ്, പക്ഷെ ഓരോ ഘട്ടവും കാണാനും എഡിറ്റും ചെയ്യാനുമാകും. | +| **അഡ്വാൻസ്ഡ് RAG** | `RetrievalAugmentor` ഫ്രെയിംവർക്ക് ഉപയോഗിച്ച് പ്ലഗ്ഗബിൽ ക്വറി ട്രാൻസ്ഫോർമറുകൾ, റൂട്ടറുകൾ, റീ-റാങ്കറുകൾ, ഉള്ളടക്ക ഇൻജക്ടർമാർ എന്നിവ ഉപയോഗിച്ച് ഉത്പാദന നിലവാര പൈപ്പ്ലൈനുകൾ. | അതിവിശാലമായ സൗകര്യം, എന്നാൽ കൂടുതൽ സങ്കീർണ്ണത. | -**ഈ ട്യൂട്ടോറിയൽ Native സമീപനം ഉപയോഗിക്കുന്നു.** RAG പൈപ്പ്ലൈനിലെ ഓരോ ഘട്ടവും — ക്വറിയെ എമ്പഡ് ചെയ്യുക, വെക്റ്റർ സ്റ്റോർ തേടുക, പശ്ചാത്തലം ഒരുക്കുക, ഉത്തരം സൃഷ്ടിക്കുക — വ്യത്യസ്തമായി [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) എന്ന ഫയലില്‍ എഴുതപ്പെട്ടിരിക്കുന്നു. ഇത് പഠനത്തിനായുള്ള കാരണം: ഓരോ ഘട്ടവും നിങ്ങൾക്കറിയാനും മനസ്സിലാക്കാനും വഴിയൊരുക്കാൻ. ഘടകങ്ങൾ എങ്ങനെ ചേർന്നു പ്രവർത്തിക്കുന്നത് മനസ്സിലാക്കിയ രോഗ, നിങ്ങൾക്ക് Easy RAG-ലേക്ക്, ത്വരിത പ്രോട്ടോട്ടൈപ്പുകളിൽ പോകാം, അല്ലെങ്കിൽ Advanced RAG പ്രൊഡക്ഷൻ സിസ്റ്റങ്ങൾക്കായി. +**ഈ ടൂട്ടോറിയൽ നേറ്റീവ് സമീപനം മാത്രം ഉപയോഗിക്കുന്നു.** RAG പൈപ്പ്ലൈന്റെ ഓരോ ഘട്ടവും — ക്വറി എംബെഡ്ഡ് ചെയ്യൽ, വെക്ടർ സ്റ്റോർ തിരയൽ, കോൺടെക്സ്‌ട് അസംബ്ലി, ഉത്തരം സൃഷ്ടിക്കൽ — എല്ലാം [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java)ൽ വ്യക്തമായും വ്യക്തമായും എഴുതിയിട്ടുള്ളതാണ്. പഠന സഹായമായി ഇത് ഉദ്ദേശിച്ചിരിക്കുന്നു: കോഡ് കുറയ്ക്കുന്നതിനേക്കാൾ എല്ലാ ഘട്ടവും കാണാനും മനസ്സിലാക്കാനും ഇത് കൂടുതൽ സഹായകരമാണ്. ഘടകങ്ങൾ എങ്ങനെ ചേർന്നിരിക്കുന്നുവെന്ന് ഞുറുക്കം പറ്റിയാൽ, എസി RAG-ലോ അഡ്വാൻസ്ഡ് RAG-ലോ തിരിച്ച് പ്രവർത്തിക്കാം. -> **💡 Easy RAG നിങ്ങൾക്ക് മുമ്പേ കാണാമോ?** [Quick Start module](../00-quick-start/README.md) ലെ ഒരു ഡോക്യുമെന്റ് Q&A ഉദാഹരണം ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) Easy RAG സമീപനമാണ് ഉപയോഗിക്കുന്നത് — LangChain4j എമ്പഡ്ഡിംഗ്, തിരയൽ, പ്രോംപ്റ്റ് രചന സ്വയം കൈകാര്യം ചെയ്യുന്നു. ഈ മോഡ്യൂള്‍ ആ പൈപ്പ്ലൈൻ തുറന്ന് ഓരോ ഘട്ടവും നിങ്ങൾ തന്നെ നിയന്ത്രിക്കാനുള്ള വഴി കാണിക്കുന്നു. +> **💡 എസി RAG-െ കുറിച്ച് അറിയാമോ?** LangChain4j-ൽ *Easy RAG* സമീപനവും ഉണ്ട്, ഇവിടെ `AiServices` ഉം `ContentRetriever` ഉം എംബെഡ്ഡിംഗും തിരയലും പ്രോമ്പ്റ്റ് നിർമാണവും സ്വയം കൈകാര്യം ചെയ്യുന്നു. ഈ മോഡ്യൂളിൽ നിങ്ങൾ ഓരോ ഘട്ടവും വ്യക്തമായി കാണാനും നിയന്ത്രിക്കാനും സാധിക്കുന്നതുകൊണ്ട് കൂടുതൽ വ്യക്തമായ മാർഗമാണ് സ്വീകരിച്ചിരിക്കുന്നത്. -താഴെ కనిపിക്കുന്നത് ആ Quick Start ഉദാഹരണത്തിലെ Easy RAG പൈപ്പ്ലൈൻ ആണ്. `AiServices` ഉം `EmbeddingStoreContentRetriever` ഉം എല്ലാ സങ്കീർണ്ണത മറയ്ക്കുന്നുവെന്ന് ശ്രദ്ധിക്കുക — നിങ്ങൾ ഡോക്യുമെന്റ് ലോഡ് ചെയ്യുന്നു, റെട്രീവർ ചേർക്കുന്നു, ഉത്തരം ലഭിക്കുന്നു. ഈ മോഡ്യൂളിലെ Native സമീപനം അവ മുഴുവൻ തുറക്കുന്നു: +താഴെയുള്ള ഡിസൈഗ്രാം എസി RAG പൈപ്പ്ലൈൻ കാണിക്കുന്നു. `AiServices` ഉം `EmbeddingStoreContentRetriever` ഉം സങ്കീർണ്ണത മുഴുവൻ മറച്ചുവെക്കുന്നു — നിങ്ങൾ ഒരു ഡോക്യുമെന്റ് ലോഡ് ചെയ്ത്, റിട്ട്രീവർ ചേർത്ത്, മറുപടികൾ നേടുന്നു. ഈ മോഡ്യൂളിലെ നേറ്റീവ് സമീപനം ആ മറച്ചിട്ട ഘട്ടങ്ങൾ പ്രത്യക്ഷപ്പെടുത്തുന്നു: Easy RAG Pipeline - LangChain4j -*ഈ ചിത്രരചന `SimpleReaderDemo.java`-ൽ നിന്നുള്ള Easy RAG പൈപ്പ്ലൈനാണ് കാണിക്കുന്നത്. ഇത് ഈ മോഡ്യൂളിൽ ഉപയോഗിച്ചിരിക്കുന്ന Native സമീപനത്തോടെ താരതമ്യം ചെയ്യുക: Easy RAG embedding, retrieval, പ്രോംപ്റ്റ് അസംബ്ലി `AiServices` ഉം `ContentRetriever` ഉം പിന്നിൽ മറയ്ക്കുന്നു — ഡോക്യുമെന്റ് ലോഡ് ചെയ്ത്, റെട്രീവർ ചേർത്ത്, ഉത്തരം നേടുക. ഈ മോഡ്യൂളിലെ Native സമീപനം ആ പൈപ്പ്ലൈൻ തുറന്ന് ഓരോ ഘട്ടവും (എമ്പഡ് ചെയ്യുക, തിരയുക, പശ്ചാത്തലം കൂട്ടിച്ചേർക്കുക, സൃഷ്ടിക്കുക) നിങ്ങൾക്ക് വ്യക്തമായി കാണിക്കുന്നു.* +*ഈ ഡിസൈഗ്രാം എസി RAG പൈപ്പ്ലൈൻ കാണിക്കുന്നു. ഈ മോഡ്യൂളിൽ ഉപയോഗിക്കുന്ന നേറ്റീവ് സമീപനത്തോട് താരതമ്യം ചെയ്യുക: എസി RAG എമ്പെഡ്ഡിംഗ്, റിട്ട്രീവൽ, പ്രോമ്പ്റ്റ് അസംബ്ലി എന്നിവ `AiServices` ഉം `ContentRetriever` ഉം പിന്നിൽ മറകോണ്ട് നടത്തുന്നു — നിങ്ങൾ ഡോക്യുമെന്റ് ലോഡ് ചെയ്ത്, റിട്ട്രീവർ ചേർക്കുന്നു, മറുപടി നേടുന്നു. നേറ്റീവ് സമീപനം ആ പൈപ്പ്ലൈൻ തുറന്ന് എങ്കിൽ എഞ്ചീൻറെ ഓരോ ഘട്ടവും (എംബെഡ് ചെയ്‌തൽ, തിരയൽ, കോൺടെക്സ്‌ട് അസംബ്ലി, ജനറേറ്റ്) നിങ്ങൾ തന്നെ വിളിച്ചു നിയന്ത്രിക്കാനാകും.* -## How It Works +## ഇത് എങ്ങനെ പ്രവർത്തിക്കുന്നു -ഈ മോഡ്യൂളിലെ RAG പൈപ്പ്ലൈൻ ഒരു ഉപയോക്താവ് ചോദ്യമുയർത്തിയാൽ നിരന്തരം പ്രവർത്തിക്കുന്ന നാല് ഘട്ടങ്ങളായി വിഭജിക്കുന്നു. ആദ്യം, അപ്‌ലോഡ് ചെയ്ത ഡോക്യുമെന്റ് **പരിശോധിക്കുകയും ചങ്കുകളാക്കി** ചെറിയ manageable ഭാഗങ്ങളാക്കി. ആ ചങ്കുകൾ പിന്നീട് **വെക്റ്റർ എംബഡിങ്ങുകളായി** മാറ്റി സൂക്ഷിക്കുന്നു, ഇപ്പോള്‍ ഗണിതപരമായി താരതമ്യം ചെയ്യാനാകും. ചോദ്യമെത്തുമ്പോൾ, ഒരു **സെമാന്റിക് തിരയൽ** നടത്തുകയും ഏറ്റവും പ്രസക്തമായ ചങ്കുകൾ കണ്ടെത്തി, അവ LLM-ന് **ഉത്തര സൃഷ്ടിക്കാനായി** പശ്ചാത്തലമായി നൽകുന്നു. താഴെ ഓരോ ഘട്ടവും കോഡുമായി വിശദമായി കാണാം. ആദ്യ ഘട്ടം നോക്കാം. +ഈ മോഡ്യൂളിലെ RAG പൈപ്പ്ലൈൻ ഓരോ തവണ ഉപയോക്താവ് ചോദ്യം ചേർത്താൽ തുടർന്നുള്ള നാല് ഘട്ടങ്ങളായി പ്രവർത്തിക്കുന്നു. ആദ്യം അപ്‌ലോഡ് ചെയ്ത ഡോക്യുമെന്റ് **പാർസ് ചെയ്ത് ചങ്കുകളായി വിഭജിക്കുന്നു** — മോഡലിന്റെ കോൺടെക്സ്‌ട് വിൻഡോയിൽ അധികം ചുരുങ്ങാതെ ഫിറ്റ് ആകുന്ന ചെറിയ തലകൾ. ആ ചങ്കുകൾ സമാനമായ ഭാഗങ്ങൾ പങ്കിടുന്നു അതിനാൽ കോൺടെക്സ്‌ട് അതിരുകളുടെ മുമ്പിലും പിന്നിലുമുള്ള പ്രശ്നങ്ങൾ ഒഴിവാക്കാൻ. -### Document Processing +ശേഷം ആ ചങ്കുകൾ **വെക്ടർ എംബെഡ്ഡിംഗുകളായി** മാറ്റിവെച്ച് സൂക്ഷിക്കുന്നു, അതിനാൽ അവയെ ഗണിത രീതിയിൽ താരതമ്യം ചെയ്യാം. ചോദ്യം വന്നപ്പോൾ, സിസ്റ്റം **സെമാന്റിക് തിരയൽ** നടത്തി ഏറ്റവും അനുയോജ്യമായ ചങ്കുകൾ കണ്ടെത്തുകയും അവ LLM-ന് **ഉത്തരം സൃഷ്ടിക്കാൻ** കോൺടെക്സ്‌ട് ആയി നൽകുകയും ചെയ്യുന്നു. താഴെ ഓരോ ഘട്ടവും അവയുടെ കോഡും ഡിസൈഗ്രാമുകളുമായി വിശദീകരിക്കുന്നു. ആദ്യം ഡോക്യുമെന്റ് പ്രോസസിംഗ് നോട്ടമിടാം. + +### ഡോക്യുമെന്റ് പ്രോസസ്സ് ചെയ്യൽ [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -നിങ്ങൾ ഒരു ഡോക്യുമെന്റ് അപ്‌ലോഡ് ചെയുമ്പോൾ, സിസ്റ്റം അതിനെ (PDF അല്ലെങ്കിൽ പ്ലെയിന്‍ ടെക്സ്റ്റ്) പാഴ്‌സുചെയ്ത്, ഫയൽനാമം പോലുള്ള മെറ്റാഡേറ്റ കൂടിയാക്കി, ചെറിയ ചങ്കുകളായി വിഭജിക്കും — മോഡലിന്റെ context window-യിൽ എളുപ്പത്തിൽ ഒതുക്കാവുന്ന ചെറിയ ഭാഗങ്ങൾ. ഈ ചങ്കുകൾ ഒറ്റപ്പെട്ടിടങ്ങളിൽ പശ്ചാത്തല നഷ്ടപ്പെടാതിരിക്കുവാനായി ചെറിയ മറുപടി പങ്ക് കൂട്ടായി. +നീ ഒരു ഡോക്യുമെന്റ് അപ്‌ലോഡ് ചെയ്തപ്പോൾ, സിസ്റ്റം അതിനെ (PDF അല്ലെങ്കിൽ പ്ലെയിൻ ടെക്സ്റ്റ്) പാർസ് ചെയ്യുന്നു, ഫയൽനാമം പോലുള്ള മെറ്റാഡേറ്റാ ചേർക്കുന്നു, പിന്നെ ചങ്കുകളായി വിഭജിക്കുന്നു — മോഡലിന്റെ കോൺടെക്സ്‌ട് വിൻഡോയിലേക്ക് സുഖമായി പൊരുത്തപ്പെടുന്ന ചെറിയ കഷണങ്ങൾ. ഈ ചങ്കുകൾ തമ്മിൽ ചെറുതായി ഒവർലാപ്പ് ഉള്ളതാണ്, അതിനാൽ അതിരുകളിലെ കോൺടെക്സ്‌ട് നഷ്ടപ്പെടുന്നില്ല. ```java -// അപ്ലോഡ് ചെയ്ത ഫയൽ പരീക്ഷിച്ച് അത് LangChain4j ഡോക്യുമെന്റായി മൂടുക +// അപ്ലോഡ് ചെയ്ത ഫയൽ പാഴ്‌സ്ചെയ്യുകയും LangChain4j ഡോക്യുമെന്റായി മൂടുകയും ചെയ്യുക Document document = Document.from(content, metadata); -// 30-ടോക്കൺ ഒവർലാപ്പോടെ 300-ടോക്കൺ ചുങ്കുകളിൽ വിഭജിക്കുക +// 30-ടോക്കൺ ഓവർലാപ്പോടെ 300-ടോക്കൺ കഷണങ്ങളായി വിഭജിക്കുക DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -താഴെ കാണുന്ന ചിത്രരചന ഇത് എങ്ങനെ പ്രവർത്തിക്കുന്നു വ്യക്തമാക്കുന്നു. ഓരോ ചങ്കും ചുറ്റുപാട് ചില ടോക്കണുകൾ പങ്കിടുന്നത് ശ്രദ്ധിക്കുക — 30-ടോക്കൺ ഓവർലാപ്പ് boundaries-ൽ പ്രാധാന്യമുള്ള പശ്ചാത്തലം നഷ്ടപ്പെടാതെ ഉറപ്പാക്കുന്നു: +താഴെയുള്ള ഡിസൈഗ്രാം ഇത് ദൃശ്യമായി കാണിക്കുന്നു. ഓരോ ചങ്കും അവരുടെ അയൽവാസികളുമായി കുറച്ച് ടോക്കൺ പങ്കുവെക്കുന്നു — 30-ടോക്കൺ ഒവർലാപ്പ് മുഖേന കോണ്സെപ്റ്റ് അതിരുകളില്ലാതെ നിലനടക്കുന്നു: Document Chunking -*ഈ ചിത്രരചന ഒരു ഡോക്യുമെന്റ് 300-ടോക്കൺ ചങ്കുകളായി 30-ടോക്കൺ ഓവർലാപ്പോടെ വിഭജിക്കുന്നതും ചങ്ക് ബൗണ്ടറികളിൽ പശ്ചാത്തലം സംരക്ഷിക്കുന്നതും കാണിക്കുന്നു.* +*ഈ ഡിസൈഗ്രാം ഒരു ഡോക്യുമെന്റ് 300-ടോക്കൺ ചങ്കുകളായി 30-ടോക്കൺ ഒവർലാപ്പുമായി വിഭജിക്കുന്ന രീതിയും അത് കോണ്സെപ്റ്റ് അതിരുകൾ എങ്ങനെ സംരക്ഷിക്കുന്നു എന്നും കാണിക്കുന്നു.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റിൽ ശ്രമിക്കുക:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) തുറന്നു ചോദിക്കുക: -> - "LangChain4j ഡോക്യുമെന്റുകള്‍ എങ്ങനെ ചങ്കുകളായി വിഭജിക്കുന്നു, ഓവർലാപ്പിന്റെ പ്രാധാന്യം എന്ത്?" -> - "വിവിധ ഡോക്യുമെന്റ് തരംകൾക്കുള്ള ഏറ്റവും ഉചിതമായ ചങ്ക് വലുപ്പം എന്താണ്, എന്തുകൊണ്ട്?" -> - "വിവിധ ഭാഷകളിൽ ഉള്ള ഡോക്യുമെന്റുകളും പ്രത്യേക ഫോർമാറ്റിംഗും എങ്ങനെ കൈകാര്യം ചെയ്യാം?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചേര്‍ന്ന് പരീക്ഷിക്കാം:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) തുറന്ന് ചോദിക്കുക: +> - "LangChain4j ഡോക്യുമെന്റുകൾ ചങ്കുകളായി എങ്ങനെ വിഭജിക്കുന്നു, ഒവർലാപ്പ് എന്തുകൊണ്ട് പ്രധാനമാണ്?" +> - "വിവിധ ഡോക്യുമെന്റ് തരംപ്രകാരം ഏറ്റവും അനുയോജ്യമായ ചങ്ക് വലുപ്പം എന്ത്, എന്തുകൊണ്ട്?" +> - "പലഭാഷകളും പ്രത്യേക ഫോർമാറ്റിംഗും ഉള്ള ഡോക്യുമെന്റുകൾ എങ്ങനെ കൈകാര്യം ചെയ്യാം?" -### Creating Embeddings +### എംബെഡ്ഡിംഗുകൾ സൃഷ്ടിക്കൽ [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -ഓരോ ചങ്കും embedding-എന്നറിയപ്പെടുന്ന ഒരു സംഖ്യാത്മക പ്രതിനിധാനമായി മാറ്റപ്പെടുന്നു — അര്‍ത്ഥം സംഖ്യകളായി മാറ്റുന്നൊരു സംവിധാനമാണ്. എമ്പഡിങ്ങ് മോഡല്‍ ഒരു ചാറ്റ് മോഡല് പോലെ "ബുദ്ധിമുട്ടുള്ള"തന്നെയല്ല; അത് നിർദ്ദേശങ്ങൾ പാലിക്കുകയോ, കാരണമൊടുക്കുകയോ, ചോദ്യങ്ങൾക്കു ഉത്തരം നൽകുകയോ ചെയ്യേണ്ട ആവശ്യമില്ല. അത് ചെയ്യുന്നത് എന്നത്: ഒരേ തരം അർത്ഥമുള്ള വാക്കുകൾ, ഒരു സമാനമായ ഗണിതാന്തരീക്ഷത്തിൽ അടുത്ത് വന്നു നിൽക്കുന്നു. "കാർ" "ഓട്ടോമൊബൈൽ"ക്ക് അടുത്ത്, "റീഫണ്ട് നയം" "പണം മടക്കുക"യ്ക്ക് അടുത്ത്. ചാറ്റ് മോഡല്‍ മനുഷ്യൻ പോലെ സംസാരിക്കാവുന്നതാണ്; എമ്പഡിങ്ങ് മോഡൽ അതിനേക്കാൾ മികച്ച ഫയൽ സംവിധാനമാണ്. +ഓരോ ചങ്കും എണ്ണം രൂപത്തിലുള്ള പ്രതിനിധാനത്തിലേക്ക് മാറ്റപ്പെടുന്നു, ഇത് "എംബെഡ്ഡിംഗ്" എന്ന് പറയും — അർത്ഥം നംબરുകളായി മാറ്റുന്ന ഒരു രൂപാന്തര രീതിയാണ്. ഈ എംബെഡ്ഡിംഗ് മോഡൽ ചാറ്റ് മോഡലിനെപ്പോലെ "ബുദ്ധിമടങ്ങിയ"തല്ല; ഇത് നിർദ്ദേശങ്ങൾ പാലിക്കുകയോ, കാരണം കാണിക്കുകയോ, ചോദ്യങ്ങൾക്ക് മറുപടി നൽകുകയോ ചെയ്യാൻ കഴിയില്ല. പകരം, ഈ ടൂൾ ടെക്സ്റ്റിനെ ഗണിത വാതിലിൽ മാറ്റുന്നു ഇങ്ങനെ സമാന അർത്ഥമുള്ള വാക്കുകൾ കണക്ക് കൂട്ടിക്കടുത്തുകൂടുന്നു — "കാർ" എന്ന വാക്കിനു "ഓട്ടോമൊബൈൽ" സമീപത്തായുള്ള സ്ഥാനം, "രീഫണ്ട് നയം" എന്ന പദം "പണം തിരിച്ചുകൊടുത്തിടലിന്റെ" അടുത്തിടം ഇങ്ങനെ. ചാറ്റ് മോഡൽ ഒരു സംവാദിയാണ്, എംബെഡ്ഡിംഗ് മോഡൽ അത്ഭുതകരമായ ഫയലിംഗ് സിസ്റ്റമാണ്. -താഴെ കാണുന്ന ചിത്രരചന ഈ ആശയം വിശദീകരിക്കുന്നു — ടെക്സ്റ്റ് പുറത്തേക്ക് യാഥാർഥഗണിത വക്ടറുകളിലേക്കുള്ള മാറ്റം, സമാന അർത്ഥങ്ങൾ അടുത്ത വക്ടറുകളായി വരുന്നു: +താഴെയുള്ള ഡിസൈഗ്രാം ഈ ആശയം ദൃശ്യവൽക്കരിക്കുന്നു — ടെക്സ്റ്റ് പ്രവേശിക്കുന്നു, നമ്പർ ശ്രേണികൾ പുറത്തിറക്കുന്നു, സമാന അർത്ഥമുള്ള വാക്കുകൾ അടുത്തിലേയ്ക്ക് വെക്ടറുകൾ‌കെ സമീപിക്കുന്നു: Embedding Model Concept -*ഈ ചിത്രരചന ഒരു എമ്പഡിങ്ങ് മോഡൽ ടെക്സ്റ്റ് സംഖ്യാത്മക വക്ടറുകളായി മാറ്റുന്നവിധം കാണിക്കുന്നു, സമാന അർത്ഥങ്ങള്‍ — "കാർ" & "ഓട്ടോമൊബൈൽ" പോലുള്ളവ — അടുത്ത് നില്‍ക്കുന്നു.* +*ഈ ഡിസൈഗ്രാം ടെക്സ്റ്റ് എങ്ങനെ സംഖ്യാത്മക വെക്ടറുകളായി മാറ്റുന്നു എന്ന് കാണിക്കുന്നു — "കാർ" എന്നതും "ഓട്ടോമൊബൈൽ" എന്നും സമാന അർത്ഥങ്ങൾ അടുത്തു വെക്ടർ സ്പേസിൽ വരുന്നു.* ```java @Bean @@ -154,29 +155,32 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -താഴെ കാണുന്ന ക്ലാസ് ചിത്രരചന RAG പൈപ്പ്ലൈനുകളിലെ രണ്ട് വ്യത്യസ്ത പ്രവാഹങ്ങളും അവ നടപ്പിലാക്കുന്ന LangChain4j ക്ലാസ്സുകളും കാണിക്കുന്നു. **ഇൻജെക്ഷൻ പ്രവാഹം** (അപ്‌ലോഡ് സമയത്ത് ഓടുക) ഡോക്യുമെന്റ് വിഭജിച്ച്, ചങ്കുകൾ എമ്പഡ് ചെയ്ത് `.addAll()` വഴി സൂക്ഷിക്കുന്നു. **ക്വറി പ്രവാഹം** (ഓരോ ചോദിച്ചപ്പോഴും ഓടുക) ചോദ്യത്തെ എമ്പഡ് ചെയ്ത് `.search()` വഴി സ്റ്റോർ തിരയുന്നു, ചേരുന്ന പശ്ചാത്തലം ചാറ്റ് മോഡലിലേക്ക് നൽകുന്നു. ഇരുവരും പങ്കുവച്ച `EmbeddingStore` ഇന്റർഫേസിൽ അപേക്ഷിച്ചു കൂടുന്നു: +താഴെയുള്ള ക്ലാസ് ഡിസൈഗ്രാം RAG പൈപ്പ്ലൈനിലെ രണ്ട് വ്യത്യസ്ത പ്രവാഹങ്ങളും അവ റിപ്പോുള്ള LangChain4j ക്ലാസ്സുകളും കാണിക്കുന്നു. +**ഇൻജെഷൻ പ്രവാഹം** (അപ്‌ലോഡ് സമയത്ത് ഒരു തവണ പ്രവർത്തിക്കുന്നു) ഡോക്യുമെന്റ് വിഭജിച്ച് ചങ്കിനെ എംബെഡ് ചെയ്ത് `.addAll()` വഴി സ്റ്റോർ ചെയ്യുന്നു. +**ക്വറി പ്രവാഹം** (ഓരോ ചോദ്യത്തിനും) ചോദ്യത്തെ എംബെഡ് ചെയ്ത് `.search()` വഴി സ്റ്റോർ തിരയുന്നു, കിട്ടിയ കോൺടെക്റ്റ് ചാറ്റ് മോഡലിന് നൽകുന്നു. +രണ്ടും പങ്കിട്ട `EmbeddingStore` ഇന്റർഫേസിൽ നിന്ന് ജടിൽമായി കണക്റ്റുചെയ്യുന്നു: LangChain4j RAG Classes -*ഈ ചിത്രരചന RAG പൈപ്പ്ലൈനിലെ ഇരട്ട പ്രവാഹങ്ങള്‍ — ingestion, query — എങ്ങനെ പങ്കുവച്ച EmbeddingStore വഴി ബന്ധപ്പെടുന്നു എന്ന് കാണിക്കുന്നു.* +*ഈ ഡിസൈഗ്രാം RAG പൈപ്പ്ലൈനിലെ രണ്ട് പ്രവാഹങ്ങൾ — ഇൻജെക്ഷനും ക്വറിയും — പരിചയപ്പെടുന്നു, ഇവ ധാരാളമുള്ള EmbeddingStore വഴിയും ബന്ധപ്പെടുന്നു.* -എംബഡിങ്ങുകൾ സൂക്ഷിച്ചശേഷം, സമാന ഉള്ളടക്കം സ്വാഭാവികമായി വെക്ടർ സ്പെയ്സിൽ കൂട്ടമായി നിൽക്കും. താഴെയുള്ള ദൃശ്യീകരണം ബന്ധപ്പെട്ട വിഷയം ഉള്ള ഡോക്യുമെന്റുകൾ സമീപവൃത്തങ്ങളിൽ കാണിക്കുന്നു, ഇത് സെമാന്റിക് തിരയൽ സാധ്യമാക്കുന്നു: +എംബെഡ്ഡിംഗ് സാധിച്ചാൽ, സമാന ഉള്ളടക്കം സ്വാഭാവികമായി വെക്ടർ സ്പേസിൽ ഒരുമിച്ചു കുഴഞ്ഞു നിൽക്കും. താഴെയുള്ള വിസ്വലൈസേഷൻ സമാന വിഷയങ്ങളുള്ള ഡോക്യുമെന്റുകൾ സമീപം പോയിന്റുകളായി ഗ്രൂപ്പ് ചെയ്യുന്നുവെന്ന് കാണിക്കുന്നു, ഇത് സെമാന്റിക് തിരയലിനെ സാധ്യമാക്കുന്നു: Vector Embeddings Space -*ഈ ദൃശ്യീകരണം ബന്ധപ്പെട്ട ഡോക്യുമെന്റുകൾ 3D വെക്ടർ സ്പെയ്സിൽ, ടെക്നിക്കൽ ഡോക്സ്, ബിസിനസ് റൂൾസ്, പ്രായോഗിക ചോദ്യങ്ങൾ എന്നീ വിഷയങ്ങൾ നൽകിയ ഗ്രൂപ്പുകളായി കാണിക്കുന്നു.* +*ഈ ദൃശ്യവൽക്കരണം ഉള്ളടക്ക വ്യാപകമായി ഡോക്യുമെന്റുകൾ 3D വെക്ടർ സ്പേസിൽ സോണ്ടിച്ച് ഗ്രൂപ്പായതായും, ടെക്‌നിക്കൽ ഡോക്സ്, ബിസിനസ് റൂൾസ്, FAQ എന്നിവ വ്യത്യസ്ത ഗ്രൂപ്പുകളായി രൂപം കൊണ്ടുവെന്ന് കാണിക്കുന്നു.* -ഉപയോക്താവ് തിരയുമ്പോൾ, സിസ്റ്റം നാല് ഘട്ടങ്ങൾ പാലിക്കുന്നു: ഡോക്യുമെന്റുകൾ ഒരിക്കൽ എമ്പഡ് ചെയ്യുക, ഓരോ തിരയലിനും ചോദ്യവും എമ്പഡ് ചെയ്യുക, കോസൈൻ സമാനതയിലൂടെ ചോദ്യ വെക്ടർ മുഴുവൻ സൂക്ഷിക്കപ്പെട്ട വെക്ടറുകളോട് താരതമ്യം ചെയ്യുക, ഏറ്റവും ഉയർന്ന സ്കോർ നേടിയ Top-K ചങ്കുകൾ തിരികെ നൽകുക. താഴെയുള്ള диаграм് ഓരോ ഘട്ടവും LangChain4j ക്ലാസ്സുകളെ ഉൾപ്പെടുത്തി കാണിക്കുന്നു: +ഉപയോക്താവ് തിരയുമ്പോൾ സിസ്റ്റം നാല് ഘട്ടങ്ങൾ പാലിക്കുന്നു: ഡോക്യുമെന്റുകൾ ഒരു തവണ എംബെഡുചെയ്യുക, ഓരോ തിരച്ചിലിലും ക്വറിയും എംബെഡുചെയ്യുക, കോസൈൻ സമാനത ഉപയോഗിച്ച് എല്ലാ വെക്ടറുകളെ താരതമ്യം ചെയ്യുക, ഏറ്റവും നല്ല K ചങ്കുകൾ തിരികെ നൽകുക. താഴെയുള്ള ഡിസൈഗ്രാം ഓരോ ഘട്ടവും LangChain4j ക്ലാസ്സുകളുമായി വിശദീകരിക്കുന്നു: Embedding Search Steps -*ഈ ചിത്രരചന നാല് ഘട്ടങ്ങളുള്ള എമ്പഡിങ്ങ് തിരയൽ പ്രക്രിയ കാണിക്കുന്നു: ഡോക്യുമെന്റ് എമ്പഡ് ചെയ്യുക, ചോദ്യവും എമ്പഡ് ചെയ്യുക, കോസൈൻ സമാനത ഉപയോഗിച്ച് വെക്ടറുകൾ താരതമ്യം ചെയ്യുക, Top-K ഫലം തിരികെ നൽകുക.* +*ഈ ഡിസൈഗ്രാം നാല് ഘട്ടങ്ങളുള്ള എംബെഡ്ഡിംഗ് തിരയൽ പ്രക്രിയ കാണിക്കുന്നു: ഡോക്യുമെന്റുകൾ എംബെഡ് ചെയ്യൽ, ക്വറി എംബെഡ് ചെയ്യൽ, കോസൈൻ സമാനത അടിസ്ഥാനമാക്കി താരതമ്യം, ഏറ്റവും മികച്ച ഫലം തിരികെ നൽകൽ.* -### Semantic Search +### സെമാന്റിക് തിരയൽ [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -നിങ്ങൾ ചോദ്യമുയർത്തുമ്പോൾ, ചോദ്യവും എമ്പഡിങ്ങായി മാറും. സിസ്റ്റം നിങ്ങളുടെ ചോദ്യം എമ്പഡിങ്ങും എല്ലാ ഡോക്യുമെന്റ് ചങ്കുകളുടെയും എമ്പഡിങ്ങുകളുമായും താരതമ്യം ചെയ്യുന്നു. ഏറ്റവും സമാന അർത്ഥമുളള ചങ്കുകൾ കണ്ടെത്തുന്നു — കീവേർഡുകൾ മാത്രമല്ല, യഥാർത്ഥ സെമാന്റിക് സമാനത. +നീ ചോദ്യം ചേർത്തപ്പോൾ, ആ ചോദ്യം ഒരു എംബെഡ്ഡിങും ആകുന്നു. സിസ്റ്റം നിന്റെ ചോദ്യം എംബെഡ്ഡിംഗ് എല്ലാ ഡോക്യുമെന്റ് ചങ്കുകളുടെ എംബെഡ്ഡിംഗുകളുമായി താരതമ്യം ചെയ്യുന്നു. ഏറ്റവും സമാനമായ അർത്ഥങ്ങൾ ഉള്ള ചങ്കുകൾ കണ്ടെത്തുന്നു - വെറും കീ-വേർഡ് പൊരുത്തം അല്ല, വാസ്തവ معنത്തത്തിൽ സമാനത. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +200,27 @@ for (EmbeddingMatch match : matches) { } ``` -താഴത്തെ ചിത്രരചന സെമാന്റിക് തിരയലും പരമ്പരാഗത കീവേഡ് തിരയലും തമ്മിലുള്ള വ്യത്യാസം കാണിക്കുന്നു. "വാഹനം" എന്ന കീവേഡ് തിരയൽ "കാറുകളും ട്രക്കുകളും" ഉള്ള ഒരു ചങ്ക് കാണിക്കാതെ പോവുമ്പോൾ, സെമാന്റിക് തിരയൽ അവ കടന്നുകാണുകയും ഉയർന്ന സ്‌കോറുള്ള ഫലം നൽകുകയും ചെയ്യുന്നു: +താഴെയുള്ള ഡിസൈഗ്രാം സെമാന്റിക് തിരയലും പരമ്പരാഗത കീ-വേർഡ് തിരയലും തമ്മിലുള്ള വ്യത്യാസം കാണിക്കുന്നു. "വാഹനം" എന്ന കീ-വേർഡ് തിരയലിൽ "കാർസ് ആൻഡ് ട്രക്സ്സ്" എന്ന ഒരു ചങ്ക് മിസ്സാകാം, പക്ഷെ സെമാന്റിക് തിരയൽ അവ രണ്ടും സമാനമെന്നു മനസ്സിലാക്കി അത് ഉയർന്ന സ്കോറോടെ തിരികെ നൽകുന്നു: Semantic Search -*ഈ ചിത്രരചന കീവേഡ് തിരയലും സെമാന്റിക് തിരയലും തമ്മിലുള്ള വ്യത്യാസം കാണിക്കുന്നു, സെമാന്റിക് തിരയൽ കീവേഡുകളിൽ വ്യത്യാസം ഉണ്ടായാലും ആശയപരമായി ബന്ധമുള്ള ഉള്ളടക്കം കണ്ടെത്തുന്നു.* -ഹുഡ് അണ്ടർ, സാദൃശ്യത കോസൈൻ സാദൃശ്യത ഉപയോഗിച്ച് അളക്കപ്പെടുന്നു — അതായത് "ഈ രണ്ട് അണക്കിഴകൾ ഒരേ ദിശയിലാണോ?" എന്ന ചോദ്യം. രണ്ടു ചങ്കുകൾ പൂർണമായും വ്യത്യസ്തമായ വാക്കുകൾ ഉപയോഗിക്കാം, പക്ഷെ അവയ്ക്ക് സമാനമായ അർത്ഥമുണ്ടെങ്കിൽ അവയുടെ വെക്ടറുകൾ ഒരേ ദിശയിലായിരിക്കും, സ്കോർ 1.0-ന് അടുത്ത് വരും: +*ഈ ഡിസൈഗ്രാം കീ-വേർഡ് അടിസ്ഥാനമാക്കിയുള്ള തിരയലും സെമാന്റിക് തിരയലും തമ്മിലുള്ള വ്യത്യാസം കാണിക്കുന്നു, സെമാന്റിക് തിരയൽ സിദ്ധാന്തപരമായ ബന്ധപ്പെട്ട ഉള്ളടക്കം കണ്ടെത്തുന്നു, കീവേഡ് വ്യത്യാസം ഉണ്ടായാലും.* -കോസൈൻ സാദൃശ്യത +വിവരിസ്ഥിതിയിൽ, സമാനത കോസൈൻ സമാനതയുടെ മാനത്തിൽ അളക്കുന്നു — "ഈ രണ്ട് സൂചികകൾ ഏകദിശയിലാണോ?" എന്ന് ചോദിക്കുന്നതുപോലെ. രണ്ട് ചങ്കുകൾ പൂർണമായും വ്യത്യസ്ത വാക്കുകൾ ഉപയോഗിച്ചാലും, അവയുടെ അർത്ഥം ഒരുപോലാകെയുള്ളപോലെ വെക്ടറുകൾ സമാനമായി ദിശാബോധം നടത്തുകയും സ്കോർ 1.0ലടക്കമാകുകയും ചെയ്യുന്നു: -*ഈ ഡിസൈനിൽ എൻബെഡിങ് വെക്ടറുകൾക്കിടയിൽ കോസൈൻ സാദൃശ്യത കോണം ആയി കാണിക്കുന്നു — കൂടുതല് സാമ്യമുള്ള വെക്ടറുകൾ 1.0-ന് അടുത്ത് സ്കോർ ചെയ്യുന്നു, ഉയർന്ന സമാനാർത്ഥ സാദൃശ്യത സൂചിപ്പിക്കുന്നു.* +Cosine Similarity +*ഈ ഡിസൈൻ കോസൈൻ സാദൃശ്യത്തെ എംബെഡിങ് വെക്ടറുകൾക്കിടയിലെ കോണായി ചിത്രീകരിക്കുന്നു — കൂടുതൽ നേരിയ വെക്ടറുകൾ 1.0 ലേക്കു സമീപം സ്കോർ ചെയ്യുന്നു, ഉദാരമാക്കുമ്പോൾ ഉയർന്ന അർത്ഥപരമായ സാദൃശ്യം സൂചിപ്പിക്കുന്നു.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റുമായി പരീക്ഷിക്കൂ:** തുറക്കുക [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) և ചോദിക്കുക: -> - "എൻബെഡിങ്സിനോടൊപ്പം സാദൃശ്യ തിരച്ചിൽ എങ്ങനെ പ്രവർത്തിക്കുന്നു, സ്കോർ എന്തുകൊണ്ട് നിർണയിക്കപ്പെടുന്നു?" -> - "എന്താണ് ഉപയോഗിക്കാൻ ഉചിതമായ സാദൃശ്യ ത്രെഷോള്‍ഡ്, അത് ഫലങ്ങളെ എങ്ങനെ ബാധിക്കുന്നു?" -> - "പ്രസക്ത ഡോക്യുമെന്റുകൾ കണ്ടെത്തില്ലെങ്കിൽ എങ്ങനെ കൈകാര്യം ചെയ്യാം?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റിനോടൊപ്പം പരീക്ഷിക്കാം:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) തുറന്ന് ചോദിക്കൂ: +> - "എംബെഡിങ്സുമായി സാദൃശ്യ അന്വേഷണം എങ്ങനെ പ്രവർത്തിക്കുന്നു, സ്കോർ എന്താണ് നിർണയിക്കുന്നത്?" +> - "എന്ത് സാദൃശ്യമാനം ഞാൻ ഉപയോഗിക്കണം, അത് ഫലങ്ങളിൽ എങ്ങനെ ബാധിക്കുന്നു?" +> - "സംബന്ധപ്പെട്ട ഡോക്യുമെന്റുകൾ കണ്ടെത്താൻ കഴിയാത്ത സാഹചര്യങ്ങൾ എങ്ങനെ കൈകാര്യം ചെയ്യണം?" -### ഉത്തരം സൃഷ്ടിക്കൽ +### ഉത്തര വികസനം [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -സബ്ബന്ധപ്പെട്ട ഏറ്റവും യോജിച്ച ചങ്കുകൾ വ്യക്തമായ നിർദേശങ്ങളും തിരിഞ്ഞു കിട്ടിയ ഉള്ളടക്കവും ഉപയോക്താവിന്റെ ചോദ്യം ഉൾപ്പെടുത്തിയ സ്റ്റ്രക്ചർ ചെയ്ത പ്രോംപ്റ്റായി സംയോജിപ്പിക്കപ്പെടുന്നു. മോഡൽ ആ പ്രത്യേക ചങ്കുകൾ വായിക്കുകയും അവ അടിസ്ഥാനമാക്കി ഉത്തരം നൽകുകയും ചെയ്യുന്നു — ഇത് മുന്നിൽ ഉള്ള കാര്യങ്ങൾ മാത്രം ഉപയോഗിക്കാൻ കഴിയും, കാരണത്താൽ ഹല്ലൂസിനേഷൻ തടയുകയും ചെയ്യുന്നു. +അതിൽ ഏറ്റവും ബന്ധപ്പെട്ട ഭാഗങ്ങൾ ദൃഢമായ പ്രോംപ്റ്റായി സമാഹരിക്കപ്പെടുന്നു, അതിൽ വ്യക്തമായ നിർദ്ദേശങ്ങളും, തിരികെ കിട്ടിയ പരിസരവും, ഉപയോക്താവിന്റെ ചോദ്യം ഉൾപ്പെടുന്നു. മോഡൽ ആ പ്രത്യേക ഭാഗങ്ങൾ വായിക്കുകയും അവ അടിസ്ഥാനമാക്കി മറുപടി നൽകുകയും ചെയ്യുന്നു — മുന്നിലിരിക്കുന്നതുപോലും മാത്രം ഉപയോഗിക്കുകയാണ്, ഇത് ഹാലൂചിനേഷൻ ഒഴിവാക്കുന്നു. ```java String context = matches.stream() @@ -237,17 +241,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -താഴെയുള്ള ഡിസൈനിൽ ഈ അസംബ്ലിയെ കാണിക്കുന്നു — തിരച്ചിൽ ഘട്ടത്തിൽ ഏറ്റവും ഉയർന്ന സ്കോർ നേടുന്ന ചങ്കുകൾ പ്രോംപ്റ്റ് ടെംപ്ലേറ്റിൽ ചേർക്കപ്പെടുകയും `OpenAiOfficialChatModel` ഒരു അടിത്തറയുള്ള ഉത്തരം സൃഷ്ടിക്കുകയും ചെയ്യുന്നു: +താഴെയുള്ള ചിത്രം ഈ സംയോജനം എങ്ങനെ നടക്കുന്നത് വ്യക്തമാക്കുന്നു — തിരച്ചിൽ ഘട്ടത്തിൽ ഏറ്റവും കൂടുതൽ സ്കോർ നേടിയ ഭാഗങ്ങൾ പ്രോംപ്റ്റ് ടെംപ്ലേറ്റിൽ ചേർക്കപ്പെടുന്നു, `OpenAiOfficialChatModel` ഒരു ഉറപ്പുള്ള മറുപടി സൃഷ്ടിക്കുന്നു: -_Context Assembly_ +Context Assembly -*ഈ ഡിസൈൻ ടോപ്-സ്കോറിങ് ചങ്കുകൾ എങ്ങനെ ഒരു ഘടനാപരമായ പ്രോംപ്റ്റിലേക്ക് ചേർത്ത് മോഡൽ നിങ്ങളുടെ ഡാറ്റയിൽ നിന്നൊരു പശ്ചാത്തലമുള്ള ഉത്തരം സൃഷ്ടിക്കുന്നുവെന്ന് കാണിക്കുന്നു.* +*ഈ ചിത്രം കാണിക്കുന്നു എങ്ങനെ ടോപ്പ്-സ്കോറുള്ള ഭാഗങ്ങൾ ദൃഢമായ പ്രോംപ്റ്റായി ചേർക്കപ്പെടുന്നു, മോഡലിന് നിങ്ങളുടെ ഡാറ്റയിൽ നിന്ന് ഉറപ്പുള്ള മറുപടി സൃഷ്ടിക്കാൻ കഴിയുകയും ചെയ്യുന്നു.* -## ആപ്ലിക്കേഷൻ ഓടിക്കുക +## ആപ്ലിക്കേഷൻ പ്രവർത്തിപ്പിക്കുക **ഡിപ്ലോയ്മെന്റ് സ്ഥിരീകരിക്കുക:** -റൂട്ട് ഡയറക്ടറിയിൽ Azure ക്രെഡൻഷ്യലുകളോടുകൂടിയ `.env` ഫയൽ ഉണ്ടെന്ന് ഉറപ്പാക്കുക (മോഡ്യൂൾ 01-ൽ സൃഷ്ടിച്ചത്). ഇത് മോഡ്യൂൾ ഡയറക്ടറിയിൽ നിന്നു (`03-rag/`) പ്രവർത്തിപ്പിക്കുക: +മൂല ഡയറക്ടറിയിൽ `.env` ഫയൽ ഉണ്ടായിരിക്കണം Azure സാക്ഷ്യപത്രങ്ങളുമായി (മോഡ്യൂൾ 01-ൽ സൃഷ്ടിച്ചത്). ഈ മോഡ്യൂൾ ഡയറക്ടറിയിൽ നിന്നും (`03-rag/`) ഇത് പ്രവർത്തിപ്പിക്കുക: **Bash:** ```bash @@ -256,46 +260,46 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്ക **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്കണം +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്കേണ്ടതാണ് ``` **ആപ്ലിക്കേഷൻ ആരംഭിക്കുക:** -> **ശ്രദ്ധിക്കുക:** മുൻപ് `./start-all.sh` റൂട്ട് ഡയറക്ടറിയിൽ നിന്നു ഓടിച്ചതെങ്കിൽ (മോഡ്യൂൾ 01-ൽ വിവരിച്ചതുപോലെ), ഈ മോഡ്യൂൾ 8081 പോർട്ടിൽ നിലവിലുണ്ട്. താഴെ കൊടുത്ത സ്റ്റാർട്ട് കമാൻഡുകൾ ഒഴിവാക്കി http://localhost:8081-ലേക്ക് നേരെ പോകാം. +> **ശ്രദ്ധിക്കുക:** നിങ്ങളുടെ എല്ലാ ആപ്ലിക്കേഷനുകളും താഴെയുള്ള കമാൻഡുകൾ ഒഴിവാക്കി, മൂല ഡയറക്ടറിയിൽ നിന്ന് `./start-all.sh` ഉപയോഗിച്ച് (മോഡ്യൂൾ 01-ൽ විവരിച്ചു) നിങ്ങൾ ഇതിനകം തന്നെ തുടങ്ങിയിട്ടുണ്ടെങ്കിൽ, ഈ മോഡ്യൂൾ 8081 പോർട്ടിൽ പ്രവർത്തിക്കുന്നു. താഴെയുള്ള പ്രാരംഭ കമാൻഡുകൾ ഒഴിവാക്കി നേരിട്ട് http://localhost:8081-ൽ പോക്കാം. -**പ്രവർത്തന പരിധി 1: സ്പ്രിംഗ് ബൂട്ടിലെ ഡാഷ്ബോർഡ് ഉപയോഗിക്കുക (VS കോഡ് ഉപയോക്താക്കൾക്ക് ശുപാർശചെയ്യുന്നു)** +**ഓപ്‌ഷൻ 1: Spring Boot ഡാഷ്ബോർഡ് ഉപയോഗിക്കുക (VS Code ഉപയോക്താക്കൾക്കു ശുപാർശ)** -ഡെവ് കണ്ടെയ്‌നറിൽ സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് എക്സ്റ്റൻഷൻ ഉൾപ്പെടുത്തിയിട്ടുണ്ട്, ഇത് എല്ലാ സ്പ്രിംഗ് ബൂട്ടു ആപ്ലിക്കേഷനുകളും വിസ്വാലായി കാണാനും നിയന്ത്രിക്കാനും ഉപയോഗിക്കുന്നു. VS കോഡിന്റെ ഇടതുവശമുള്ള ആക്ടിവിറ്റി ബാറിൽ (സ്പ്രിംഗ് ബൂട്ട് ഐക്കൺ നോക്കുക) ലഭ്യമാണ്. +ഡെവ് കണ്ടെയ്‌നറിൽ Spring Boot ഡാഷ്ബോർഡ് എക്സ്റ്റൻഷൻ ഉൾപ്പെടുത്തിയിട്ടുണ്ട്, ഇത് Spring Boot ആപ്ലിക്കേഷനുകൾക്കുള്ള ദൃശ്യ ഇന്റർഫേസ് നൽകുന്നു. ഇത് VS Code-ൽ ഇടതുവശത്തെ ആക്ടിവിറ്റി ബാറിൽ (Spring Boot ഐക്കൺ) കാണാം. -സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡിൽ നിന്നു നിങ്ങൾക്ക്: -- വർക്ക്‌സ്പേസിൽ ലഭ്യമായ എല്ലാ സ്പ്രിംഗ് ബൂട്ടു ആപ്ലിക്കേഷനുകളും കാണാം -- ഒറ്റ ക്ലിക്കിൽ ആപ്ലിക്കേഷനുകൾ ആരംഭിക്കുന്നതും നിർത്തുന്നതും -- ആപ്ലിക്കേഷൻ ലോഗുകൾ റിയൽ ടൈമിൽ കാണാം -- ആപ്ലിക്കേഷൻ നില നിരീക്ഷണം +Spring Boot ഡാഷ്ബോർഡിൽ നിന്ന് നിങ്ങൾക്ക്: +- available Spring Boot ആപ്ലിക്കേഷനുകൾ കാഴ്ചവെക്കാം +- ഒറ്റ ക്ലിക്കിൽ ആരംഭിപ്പിക്കുകയും നിർത്തുകയും ചെയ്യാം +- ആപ്ലിക്കേഷൻ ലോഗുകൾ യഥാർത്ഥ സമയത്തിൽ കാണാം +- ആപ്ലിക്കേഷൻ സ്റ്റാറ്റസ് നിരീക്ഷിക്കാം -"rag" ന്റെ അടുത്തുള്ള പ്ളേ ബട്ടൺ ക്ലിക്ക് ചെയ്താൽ ഈ മോഡ്യൂൾ ആരംഭിക്കും, അല്ലെങ്കിൽ എല്ലാ മോഡ്യൂളുകളും ഒരുമിച്ച് ആരംഭിക്കാം. +"rag" ഓപ്ഷന്റൊപ്പം പ്ലേ ബട്ടൺ അമർത്തി ഈ മോഡ്യൂൾ ആരംഭിക്കാം, അല്ലെങ്കിൽ എല്ലാം ഒരുമിച്ച് ആരംഭിക്കാം. -സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് +Spring Boot Dashboard -*ഈ സ്ക്രീൻഷോട്ടിൽ VS കോഡിൽ സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് കാണിക്കുന്നു, നിങ്ങൾക്ക് ആപ്ലിക്കേഷനുകൾ തുടങ്ങാനും നിർത്താനും നിയന്ത്രിക്കാനും സാധിക്കുന്നു.* +*ഈ സ്‌ക്രീൻഷോട്ട് VS Code-യിലെ Spring Boot ഡാഷ്ബോർഡ് കാണിക്കുന്നു, അറസ്റ്റ്, നിർത്തൽ, നിരീക്ഷണം എന്നിവ ദൃശ്യമായി ചെയ്യാൻ കഴിയുന്നു.* -**പ്രവർത്തന പരിധി 2: ഷെൽ സ്ക്രിപ്റ്റുകൾ ഉപയോഗിക്കുക** +**ഓപ്‌ഷൻ 2: ഷെൽ സ്ക്രിപ്റ്റുകൾ ഉപയോഗിക്കുക** -എല്ലാ വെബ് ആപ്ലിക്കേഷനുകൾ (മോഡ്യൂൾ 01-04) ആരംഭിക്കുക: +എല്ലാ വെബ് ആപ്ലിക്കേഷനുകളും (മോഡ്യൂളുകൾ 01-04): **Bash:** ```bash -cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്ന് +cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്നുള്ളത് ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # റൂട്ട് ഡയറക്റ്ററിയിൽ നിന്ന് +cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്ന് .\start-all.ps1 ``` -അല്ലെങ്കിൽ ഈ മോഡ്യൂളിൽ മാത്രം തുടങ്ങിയാൽ: +അല്ലെങ്കിൽ സോലമെന്ത് ഈ മോഡ്യൂളിന് മാത്രമായി തുടങ്ങുക: **Bash:** ```bash @@ -309,16 +313,16 @@ cd 03-rag .\start.ps1 ``` -രണ്ട് സ്ക്രിപ്റ്റുകൾ റൂട്ട് `.env` ഫയലിൽ നിന്നുള്ള പരിസ്ഥിതി ഘടകങ്ങൾ സ്വയം ലോഡ് ചെയ്യും, ജാറുകൾ ഇല്ലെങ്കിൽ നിർമ്മിക്കും. +രണ്ടു സ്ക്രിപ്റ്റുകളും സ്വയം `.env` ഫയലിൽ നിന്ന് എൻവയോൺമെന്റ് വ്യത്യാസങ്ങൾ ലോഡ് ചെയ്യുകയും, JARകൾ നിലവിലില്ലെങ്കിൽ നിർമ്മിക്കുകയും ചെയ്യുന്നു. -> **ശ്രദ്ധിക്കുക:** സ്റ്റാർട്ട് ചെയ്യുന്നതിനുമുമ്പ് എല്ലാ മോഡ്യൂളുകളും കൈമാറാൻ നിങ്ങൾ ഇഷ്ടപ്പെടുന്നതെങ്കിൽ: +> **ശ്രദ്ധിക്കുക:** സ്പോർട്ടായി എല്ലാ മോഡ്യൂളുകളും നിർമ്മിച്ച്‌ അതിനു ശേഷം തുടങ്ങാൻ ആഗ്രഹിക്കുന്നുവെങ്കിൽ: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -327,112 +331,111 @@ cd 03-rag നിങ്ങളുടെ ബ്രൗസറിൽ http://localhost:8081 തുറക്കുക. -**നിറുത്തുന്നതിന്:** +**സ്റ്റോപ്പ് ചെയ്യാൻ:** **Bash:** ```bash -./stop.sh # ഈ മോഡ്യൂളും മാത്രം -# അല്ലെങ്കിൽ +./stop.sh # ഈ മോഡ്യൂള് മാത്രം +# അല്ലെങ്കില് cd .. && ./stop-all.sh # എല്ലാ മോഡ്യൂളുകളും ``` **PowerShell:** ```powershell -.\stop.ps1 # ഈ മൊഡ്യൂള് മാത്രമേ -# അല്ലങ്കില് -cd ..; .\stop-all.ps1 # എല്ലാ മൊഡ്യൂളുകളും +.\stop.ps1 # ഈ മോഡ്യൂൾ മാത്രം +# അല്ലെങ്കിൽ +cd ..; .\stop-all.ps1 # എല്ലാ മോഡ്യൂളുകളും ``` -## ആപ്ലിക്കേഷൻ ഉപയോഗിക്കുക +## ആപ്ലിക്കേഷൻ ഉപയോഗിക്കൽ -ഡോക്യുമെന്റ് അപ്‌ലോഡ് ചെയ്യാനും ചോദ്യങ്ങൾ ചോദിക്കാനും വെബ് ഇന്റർഫേസ് ആപ്ലിക്കേഷൻ നൽകുന്നു. +ഡോക്യുമെന്റ് അപ്‌ലൊഡ് ചെയ്യാനും ചോദ്യങ്ങൾ ചോദിക്കാനും വെബ് ഇന്റർഫേസ് ആപ്ലിക്കേഷൻ നൽകുന്നു. -RAG ആപ്ലിക്കേഷൻ ഇന്റർഫേസ് +RAG Application Interface -*ഈ സ്ക്രീൻഷോട്ടിൽ RAG ആപ്ലിക്കേഷൻ ഇന്റർഫേസാണ് കാണുന്നത്, നിങ്ങൾ ഡോക്യുമെന്റുകൾ അപ്‌ലോഡ് ചെയ്ത് ചോദ്യങ്ങൾ ചോദിക്കാൻ സാധിക്കുന്നത്.* +*രോഗ്ഗ് ആപ്ലിക്കേഷൻ ഇന്റർഫേസ്, ഇവിടെ നിങ്ങൾ ഡോക്യുമെന്റുകൾ അപ്‌ലോഡ് ചെയ്യുകയും ചോദ്യങ്ങൾ ചോദിക്കുകയും ചെയ്യുന്നു.* -### ഡോക്യുമെന്റ് അപ്‌ലോഡ് ചെയ്യുക +### ഒരു ഡോക്യുമെന്റ് അപ്‌ലോഡ് ചെയ്യുക -ഒരു ഡോക്യുമെന്റ് അപ്‌ലോഡ് ചെയ്യുന്നതു മുതൽ ചെയ്യുക - പരീക്ഷണത്തിന് TXT ഫയലുകൾ വളരെ അനുയോജ്യമാണ്. ഈ ഡയറക്ടറിയിലാണ് `sample-document.txt` നൽകപ്പെട്ടിരിക്കുന്നത്, ഇതിൽ LangChain4j ഫീച്ചറുകൾ, RAG നടപ്പാക്കൽ, മികച്ച ശീലങ്ങൾ എന്നിവയുടെ വിവരങ്ങൾ അടങ്ങിയിരിക്കുന്നു - സിസ്റ്റം പരീക്ഷിക്കാൻ ഇത് അനുയോജ്യമാണ്. +ഡോക്യുമെന്റ് അപ്‌ലോഡ് ചെയ്യുന്നതോടെ ആരംഭിക്കുക - ടെക്സ്റ്റ് (.txt) ഫയലുകൾ ടെസ്റ്റ് ചെയ്യാൻ മികച്ചതാണ്. ഈ ഡയറക്ടറിയിൽ LangChain4j സവിശേഷതകൾ, RAG നടപ്പാക്കൽ, മികച്ച രീതികൾ തുടങ്ങി വിവരമുള്ള `sample-document.txt` ഫയൽ ലഭ്യമാണ്, അത് സിസ്റ്റം പരീക്ഷിക്കാൻ അനുയോജ്യമാണ്. -സിസ്റ്റം നിങ്ങളുടെ ഡോക്യുമെന്റ് പ്രോസസ്സ് ചെയ്ത്, ചങ്കുകളായി വിഭജിച്ച്, ഓരോ ചങ്കിനും എൻബെഡിങ്സ് സൃഷ്ടിക്കുന്നു. ഇത് നിങ്ങൾ അപ്‌ലോഡ് ചെയ്തപ്പോൾ തന്നെ സ്വയമെത്തിച്ചാക്കി നടക്കുന്നു. +സിസ്റ്റം നിങ്ങളുടെ ഡോക്യുമെന്റ് പ്രോസസ് ചെയ്യുകയും അത് ഭാഗങ്ങളായി വിഭജിക്കുകയും ഓരോ ഭാഗത്തിനും എംബെഡിങ് സൃഷ്ടിക്കുകയും ചെയ്യുന്നു. ഇത് സ്വയം നടക്കുന്നു നിങ്ങളുടെ അപ്‌ലോഡ് സമയത്ത്. ### ചോദ്യങ്ങൾ ചോദിക്കുക -ഇപ്പോൾ ഡോക്യുമെന്റ് ഉള്ളടക്കത്തെ സംബന്ധിച്ച വ്യക്തമായ ചോദ്യങ്ങൾ ചോദിക്കൂ. ഡോക്യുമെന്റിൽ വ്യക്തമായി പറഞ്ഞിട്ടുള്ള സത്യസന്ധമായ കാര്യങ്ങൾ ചോദിക്കുക. സിസ്റ്റം അനുയോജ്യമായ ചങ്കുകൾ തിരയുകയും അവ പ്രോംപ്റ്റിൽ ഉൾപ്പെടുത്തി ഉത്തരം നിർമ്മിക്കുകയും ചെയ്യും. +ഡോക്യുമെന്റ് ഉള്ളടക്കത്തെക്കുറിച്ച് പ്രത്യേകമായ ചോദ്യങ്ങൾ ചോദിക്കൂ. വ്യക്തമായ, ഡോക്യുമെന്റിൽ നേരിട്ട് പറഞ്ഞിട്ടുള്ള ഫാക്റ്റ് ചോദ്യങ്ങൾ പരീക്ഷിക്കുക. സിസ്റ്റം ബന്ധപ്പെട്ട ഭാഗങ്ങൾ തിരയുകയും അവ പ്രോംപ്റ്റിൽ ഉൾപ്പെടുത്തുകയും മറുപടി സൃഷ്ടിക്കുകയും ചെയ്യും. -### ഉറവിട റഫറൻസുകൾ പരിശോധിക്കുക +### ഉറവിട സൂചനകൾ പരിശോധിക്കുക -പ്രത്യേക ഉത്തരം ഓരോ ഉറവിട റഫറൻസുകളും സമാനത സ്കോറുകളുമായാണ് ലഭിക്കുന്നത്. ഈ സ്കോറുകൾ (0 മുതൽ 1 വരെയാണ്) നിങ്ങൾ ചോദിച്ച ചോദ്യത്തിനുള്ള അതിനൊത്ത ചങ്കുകളുടെ പ്രസക്തത കാണിക്കുന്നു. ഉയർന്ന സ്കോറുകൾ മികച്ച ഗുണമേന്മയുള്ള ചങ്കുകൾ സൂചിപ്പിക്കുന്നു. ഇതിലൂടെ നിങ്ങള്‍ ഉത്തരം ഉറവിടം പ്രമാണിച്ച് പരിശോദിക്കാം. +ഓരോ മറുപടിയും സാദൃശ്യമാനങ്ങൾ ഉൾക്കൊള്ളുന്ന ഉദ്ഗ്രന്ഥം സൂചനകൾ ഉണ്ട്. ഈ സ്കോറുകൾ (0 മുതൽ 1 വരെ) നിങ്ങളുടെ ചോദ്യവുമായി ഏത് ഭാഗം എത്രത്തോളം ബന്ധപ്പെട്ടു എന്ന് കാണിക്കുന്നു. ഉയർന്ന സ്കോർ ഉള്ളത് മികച്ച പൊരുത്തമാണെന്നു സൂചിപ്പിക്കുന്നു. ഇതിലൂടെ മറുപടി ഉറവിടാനുസൃതമാണെന്ന് പരിശോധന നടത്താം. -RAG ക്വറി ഫലങ്ങൾ +RAG Query Results -*ഈ സ്ക്രീൻഷോട്ട് ക്വറി ഫലങ്ങളും ഉത്തരം, ഉറവിട റഫറൻസുകളും, ഓരോ തിരഞ്ഞെടുത്ത ചങ്കിന്റെയും പ്രസക്തത സ്കോറുകളും കാണിക്കുന്നു.* +*ഈ സ്ക്രീൻഷോട്ട് ചോദ്യഫലം, സ്രോതസ്സ് സൂചനകൾ, തിരികെ കിട്ടിയ ഓരോ ഭാഗത്തിന്റെയും പ്രസക്തി സ്കോറുകൾ കാണിക്കുന്നു.* -### ചോദ്യങ്ങളുമായി പരീക്ഷണം നടത്തുക +### ചോദ്യങ്ങളോടു പരീക്ഷണം നടത്തുക -വിവിധ തരം ചോദ്യങ്ങൾ ചോദിച്ച് നോക്കൂ: -- പ്രത്യേക സത്യങ്ങൾ: "പ്രധാന വിഷയം എന്താണ്?" -- താരതമ്യങ്ങൾ: "X ഉം Y ഉമെന്നുള്ള വ്യത്യാസം എന്താണ്?" -- സംക്ഷേപങ്ങൾ: "Z സംബന്ധിച്ച പ്രധാനപ്പെട്ട കാര്യങ്ങൾ സംഗ്രഹിപ്പിക്കുക" +വിവിധ തരത്തിലുള്ള ചോദ്യങ്ങൾ പരീക്ഷിക്കുക: +- പ്രത്യേകമായ വസ്തുതകൾ: "പ്രധാന വിഷയമേന്താണ്?" +- താരതമ്യങ്ങൾ: "X-നും Y-ക്കും തമ്മിലുള്ള വ്യത്യാസം എന്താണ്?" +- സംഗ്രഹങ്ങൾ: "Z-യേക്കുറിച്ചുള്ള പ്രധാനപ്പെട്ട കാര്യങ്ങൾ സംഗ്രഹിക്കുക" -നിങ്ങളുടെ ചോദ്യത്തിന്റെ പ്രാസക്തി അടിസ്ഥാനമാക്കി പ്രസക്തത സ്കോറുകൾ എങ്ങനെ മാറുന്നു എന്നത് ശ്രദ്ധിക്കൂ. +നിങ്ങളുടെ ചോദ്യത്തിന്റെ ഡോക്യുമെന്റ് ഉള്ളടക്കവുമായി പൊരുത്തം പരിഗണിച്ച് പ്രസക്തി സ്കോറുകൾ എങ്ങനെ മാറുന്നു ശ്രദ്ധിക്കുക. ## പ്രധാന ആശയങ്ങൾ -### ചങ്കിംഗ് തന്ത്രം +### ഫക്സ് ചെയ്യൽ രീതി -ഡോക്യുമെന്റുകൾ 300-ടോക്കൺ ചങ്കുകളായി വിഭജിക്കുന്നുണ്ട്, 30 ടോക്കണുകൾ ഓവർലാപ്പുമായി. ഈ സാന്ദ്രമാണ്, ഓരോ ചങ്കിനും സാങ്കേതികമായി മതിയായ സവിശേഷതയും, ധാരണനിർണയവും ഉണ്ടാകുന്നതിനും ഒരേ പ്രൊംപ്റ്റിൽ നിരവധി ചങ്കുകൾ ഉൾപ്പെടുന്നതിനും. +ഡോക്യുമെന്റുകൾ 300-ടോക്കൺ ചങ്കുകളായി വിഭജിക്കുന്നു, 30 ടോക്കൺ ഓവർലാപ്പുപരിധിയോടെ. ഇത് ഒരു ചങ്കിന്റെയൊരു സാര്വത്രിക സമ്പ്രദായമുള്ള സാന്ദർശ്യം നൽകുകയും ഒരു പ്രോംപ്റ്റിൽ ഒന്നിലധികം ചങ്കുകൾ ഉൾക്കൊള്ളുന്നതിനായി ചെറിയ വലുപ്പത്തിൽ നിലനിർത്തുകയും ചെയ്യുന്നു. -### സമാനത സ്കോറുകൾ +### സാദൃശ്യമാനങ്ങൾ -തിരഞ്ഞെടുത്ത ഓരോ ചങ്കിനും 0 മുതൽ 1 വരെയുള്ള സാദൃശ്യ സ്കോർ ലഭിക്കുന്നു, ഇത് ഉപയോക്തൃ ചോദ്യത്തോട് എത്ര അടുത്താണെന്ന് സൂചിപ്പിക്കുന്നു. താഴെയുള്ള ഡിസൈനിൽ സ്കോർ പരിധികളും സിസ്റ്റം ഫലങ്ങൾ ഫിൽറ്റർ ചെയ്യാൻ അവ എങ്ങനെ ഉപയോഗിക്കുന്നത് എന്നതും കാണിക്കുന്നു: +ഓരോ തിരികെ കിട്ടിയ ചങ്കിനും 0 മുതൽ 1 വരെ സാദൃശ്യമാന മാർക്ക് നൽകുന്നു, ഉപയോക്താക്കളുടെ ചോദ്യവുമായി അവ എത്രത്തോളം മിണ്ടുന്നു എന്ന് കാണിക്കുന്ന. താഴെയുള്ള ചിത്രം സ്കോർ പരിധികളെ ദൃശ്യമായി പ്രതിപാദിക്കുന്നു, ഫലങ്ങൾ ഫിൽട്ടർ ചെയ്യാനുള്ള പ്രയോഗത്തിൽ: -സാദൃശ്യ സ്കോറുകൾ +Similarity Scores -*ഈ ഡിസൈൻ 0 മുതൽ 1 വരെ സ്കോർ പരിധികൾ കാണിക്കുന്നു, 0.5 എന്ന നിമ്നം ത്രെഷോൾഡ് ഉപയോഗിച്ച് പ്രാസക്തമല്ലാത്ത ചങ്കുകൾ അവഗണിക്കുന്നു.* +*0 മുതൽ 1 വരെയുള്ള സ്കോർ പരിധികളും, 0.5 എന്ന കേട് പരിധിയും കാണിക്കുന്നു, അതിനു താഴെയുള്ള ഭാഗങ്ങൾ ഫിൽട്ടർ ചെയ്യപ്പെടുന്നു.* -സ്കോറിന്റെ പരിധി: -- 0.7-1.0: വളരെ പ്രസക്തവും, കൃത്യമായ പൊരുത്തം -- 0.5-0.7: പ്രസക്തവും, നല്ല പബ്ലിക് സാന്റർ -- 0.5-ൽ താഴെ: ഫിൽറ്റർ ചെയ്ത, ഏറെ വ്യത്യസ്തം +സ്‌കോർ പരിധി: +- 0.7-1.0: വളരെ പ്രസക്തം, കൃത്യമായ പൊരുത്തം +- 0.5-0.7: പ്രസക്തം, നല്ല പരിസരം +- 0.5 താഴെ: ഫിൽട്ടർ ചെയ്ത, അശുദ്ധമായ -ഉയർന്ന നിലവാരത്തിനായി സിസ്റ്റം ഏറ്റവും കുറഞ്ഞ ത്രെഷോൾഡിന് മുകളിൽ ഉള്ള ചങ്കുകൾ മാത്രമേ തിരഞ്ഞെടുക്കുകയുള്ളു. +പ്രസക്തത ഉറപ്പാക്കാൻ സിസ്റ്റം കുറഞ്ഞത് ഒരു പ്രമാണത്തിനും 0.5 നും മുകളിൽ ഉള്ള ഭാഗങ്ങൾ മാത്രം തിരികെ ലഭിക്കുന്നു. -എൻബെഡിങ്സ് അർത്ഥം വ്യക്തമായി കിൽധിക്കുന്നിടത്താണ് നല്ലത്, എന്നാൽ അവയ്ക്ക് ചില ബില്ലൈൻഡ് സ്‌പോട്ടുകൾ ഉണ്ട്. താഴെയുള്ള ഡിസൈനിൽ പരാജയപ്പെട്ട പൊതുവായ സാഹചര്യങ്ങൾ കാണിച്ചired ചങ്കുകൾ വളരെ വലിയതും മഷിഞ്ഞ വെക്ടറുകൾ ഉല്പാദിപ്പിക്കുന്നു, വളരെ ചെറുതും പബ്ലിക് സാന്ററില്ലാത്തതും, ഒറ്റ അർത്ഥം കൊണ്ടhasilkan മതിയായ സന്ദർഭം ലഭിക്കാത്തതും, ഐഡികൾ പോലുള്ള കൃത്രിമ പൊരുത്തം കാണിക്കുന്നവർ ഉൾപ്പെടുന്നു: +एम्बെडिंगുകൾ മനസ്സിലാക്കലിന്റെ ക്ലസ്റ്ററിംഗിൽ നല്ലാൽ പ്രവർത്തിക്കുന്നു, എന്നാൽ അവയ്ക്ക് ചില അശ്രദ്ധാക്കാനിടയുണ്ട്. താഴെയുള്ള ചിത്രം സാധാരണ പരാജയ മോഡുകൾ ദൃശ്യപ്പെടുത്തി – വലിപ്പം വലിയ ചങ്കുകൾ മുരളി അനുഭവം തരും, ചിന്താഗതി കുറഞ്ഞ ചെറു ചങ്കുകൾ നിലവിലെ പരിസരക്കുറവ് ഉണ്ടാക്കും, അർത്ഥം വ്യക്തമല്ലാത്ത പദങ്ങൾ ഒരു പലയിടത്തേക്ക് സൂചിപ്പിക്കും, കൃത്യമായ പൊരുത്ത_LOOKUPS (IDകൾ, ഭാഗ നമ്പറുകൾ) എംബെഡിങ്സിൽ പ്രവർത്തിക്കുന്നില്ല: -എൻബെഡിങ്FAILറ_modes +Embedding Failure Modes -*ഈ ഡിസൈനിൽ പൊതുവായ എൻബെഡിങ് പരാജയ വിധികൾ കാണിക്കുന്നു: വലിയ ചങ്കുകൾ, ചെറു ചങ്കുകൾ, ഒരു പദം പല അർത്ഥങ്ങളിലേക്കും സൂചിപ്പിക്കുന്നത്, കൃത്യമായ പൊരുത്തം ഉറവിടങ്ങൾ പോലുള്ള ഐഡികളോടുകൂടെ പ്രവർത്തിക്കാത്തത്.* +*ഇത് സാധാരണ എംബെഡിംഗ് പരാജയ മോഡുകൾ: വളരെ വലിയ ചങ്കുകൾ, ചെറുതായ ചങ്കുകൾ, അനിശ്ചിത പദങ്ങൾ ഒന്നിലധികം ക്ലസ്റ്ററുകൾക്ക് സൂചന നൽകുന്നു, കൃത്യമായ പൊരുത്ത_LOOKUPS.* ### ഇൻ-മെമ്മറി സംഭരണം -മോഡ്യൂൾ ലളിതമായ ഇൻ-മെമ്മറി സംഭരണം ഉപയോഗിക്കുന്നു. ആപ്ലിക്കേഷൻ റീസ്റ്റാർട്ട് ചെയ്യുമ്പോൾ, അപ്‌ലോഡ് ചെയ്ത ഡോക്യുമെന്റുകൾ നഷ്ടപ്പെടും. പ്രൊഡക്ഷൻ സിസ്റ്റങ്ങളിൽ Qdrant അല്ലെങ്കിൽ Azure AI Search പോലെയുള്ള സ്ഥിരതയുള്ള വെക്റ്റർ ഡാറ്റാബേസുകൾ ഉപയോഗിക്കുന്നു. +ഈ മോഡ്യൂൾ ലളിതമായതിനായുള്ള ഇൻ-മെമ്മറി സ്റ്റോറേജ് ഉപയോഗിക്കുന്നു. ആപ്ലിക്കേഷൻ പുനരാരംഭിക്കുമ്പോൾ അപ്‌ലോഡ് ചെയ്ത ഡോക്യുമെന്റുകൾ നഷ്ടപ്പെടും. പ്രൊഡക്ഷൻ സിസ്റ്റങ്ങൾ Qdrant, Azure AI Search പോലുള്ള സ്ഥിരമായ വെക്ടർ ഡാറ്റാബേസുകൾ ഉപയോഗിക്കുന്നു. -### കോൺടെക്സ്റ്റ് വിൻഡോ മാനേജ്‌മെന്റ് +### പരിസര വിൻഡോ മാനേജ്‌മെന്റ് -ഓരോ മോഡലിനും പരമാവധി കോൺടെക്സ്റ്റ് വിൻഡോ പരിധി ഉണ്ട്. വലിയ ഡോക്യുമെന്റിലെ എല്ലാ ചങ്കുകളും ഉൾപ്പെടുത്താനാകില്ല. സിസ്റ്റം ഏറ്റവും പ്രസക്തമായ ടോപ്പ് N (ഡീഫോൾട്ട് 5) ചങ്കുകൾ തിരഞ്ഞെടുക്കുന്നു, അതിരുകൾക്കുള്ളിൽ ഉറപ്പു വരുത്തുകയും കൃത്യമായ ഉത്തരങ്ങൾക്കായി മതിയായ കോൺടെക്സ്റ്റ് നൽകുകയും ചെയ്യുന്നു. +ഓരോ മോഡലിനും പരമാവധി പരിസര വിൻഡോയുണ്ട്. വലിയ ഡോക്യുമെന്റിലെ എല്ലാ ചങ്കുകളും ഉൾപ്പെടുത്താൻ കഴിയില്ല. സിസ്റ്റം ഏറ്റവും പ്രസക്തമായ ടോപ്പ് N (ഡിഫോൾട്ട് 5) ചങ്കുകൾ തിരികെ കിട്ടുന്നു, പരിധിയിലുണ്ടാക്കുകയും കൃത്യമായ മറുപടിക്ക് മതിയായ പരിസരം നൽകുകയും ചെയ്യുന്നു. -## RAG കാര്യമുള്ളപ്പോൾ +## RAG നല്ലപ്പോൾ -RAG എല്ലാ സമയത്തും ശരിയായ സമീപനം അല്ല. താഴെയുള്ള തീരുമാന മാർഗ്ഗനിർദ്ദേശം RAG എപ്പോൾ മൂല്യം കൂട്ടും എന്നും ലളിതമായ സമീപനങ്ങൾ (പ്രോംപ്റ്റിലെ ഉള്ളടക്കമോ മോഡലിന്റെ സ്വപ്രജ്ഞാനമോ സഹായി ആയി ഉപയോഗിക്കുന്നത്) എപ്പോൾ മതിയാകും എന്നും വ്യക്തമാക്കുന്നു: +RAG എല്ലായ്പ്പോഴും ശരിയായ മാർഗം അല്ല. താഴെയുള്ള തീരുമാന മാർഗ്ഗനിർദ്ദേശം RAG മൂല്യം കൂട്ടുമ്പോൾ എപ്പോൾ എളുപ്പത്തിലുള്ള മാർഗങ്ങൾ - കരുതലിൽ ഉള്ളടക്കം നേരിട്ട് ഉൾപ്പെടുത്തൽ അല്ലെങ്കിൽ മോഡലിന്റെ നിർമിത അറിവിനാൽ അതുപോലെ - മതിയാകുമ്പോൾ കാണിച്ചുതരുന്നു: -RAG എപ്പോൾ ഉപയോഗിക്കാം +When to Use RAG -*ഈ ഡിസൈൻ RAG മൂല്യം കൂട്ടുന്നപ്പോൾ, ലളിതമായ സമീപനങ്ങൾ മതിയാകുന്നപ്പോൾ എന്നിവക്കുള്ള ഒരു തീരുമാന മാർഗ്ഗനിർദ്ദേശം കാണിക്കുന്നു.* +*RAG പ്രയോഗിക്കേണ്ട അവസ്ഥകളും എളുപ്പമുള്ള മാർഗങ്ങൾ മതിയാകുന്ന സമയങ്ങളും തീരുമാനിക്കാനായി തയ്യാറാക്കിയ മാർഗ്ഗരേഖ.* -## അടുത്ത ചുവടുകൾ +## അടുത്തപടി -**അടുത്ത മോഡ്യൂൾ:** [04-tools - ടൂൾസുകളുള്ള AI ഏജൻറുകൾ](../04-tools/README.md) +**അടുത്ത മോഡ്യൂൾ:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**നാവിഗേഷൻ:** [← മുൻപ്: മോഡ്യൂൾ 02 - പ്രോംപ്‌റ്റ് എഞ്ചിനീയറിങ്](../02-prompt-engineering/README.md) | [പ്രധാനത്തിലേക്ക് മടങ്ങുക](../README.md) | [അടുത്തത്: മോഡ്യൂൾ 04 - ടൂൾസ് →](../04-tools/README.md) +**നാവിഗേഷൻ:** [← മുമ്പത്തെ: മോഡ്യൂൾ 02 - പ്രോംപ്റ്റ് എൻജിനിയറിങ്ങ്](../02-prompt-engineering/README.md) | [പ്രധാനത്തിലേക്ക് മടങ്ങുക](../README.md) | [അടുത്തത്: മോഡ്യൂൾ 04 - ടൂൾസ് →](../04-tools/README.md) --- -**വ്യാഖ്യാനം**: -ഈ രേഖ AI വിവർത്തന സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് വിവർത്തനം ചെയ്തതാണ്. നമുക്ക് കൃത്യതയ്ക്കായി ശ്രമിച്ചുവെങ്കിലും, സ്വയം പ്രവർത്തിക്കുന്ന വിവർത്തനങ്ങളിൽ പിഴവുകളോ തെറ്റുകളോ ഉണ്ടാകാമെന്ന് ദയവായി ശ്രദ്ധിക്കുക.റോസ്രിജനം ദയവായി ശ്രദ്ധിക്കുക. -അതിന്റെ സ്വഭാവ ഭാഷയിലെ യാഥാർത്ഥ്യ രേഖ മാത്രമേ അതിന്റെ അതോറിറ്റേറ്റീവ് ഉറവിടമായി കരുതാവൂ. നിർണായക വിവരങ്ങൾക്കായി പ്രൊഫഷണൽ മനുഷ്യ വിവർത്തനം ശുപാർശ ചെയ്യപ്പെടുന്നു. ഈ വിവർത്തനം ഉപയോഗിച്ചുവിൽ സംഭവിക്കുന്ന ഭ്രമങ്ങൾക്കും തെറ്റിദ്ധാരണകൾക്കും ഞങ്ങൾ ഉത്തരവാദികളല്ല. +**അറിയിപ്പ്**: +ഈ രേഖ AI പരിഭാഷാ സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് പരിഭാഷപ്പെടുത്തിയതാണ്. ഞങ്ങൾ കൃത്യതയ്ക്കായി ശ്രമിക്കുന്നുവെങ്കിലും, ഓട്ടോമേറ്റഡ് പരിഭാഷകളിൽ പിഴവുകൾ അല്ലെങ്കിൽ തെറ്റായ വിവരങ്ങൾ ഉണ്ടാകാൻ സാധ്യതയുണ്ട്. അതിന്റെ സ്വാഭാവിക ഭാഷയിലുള്ള അസൽ രേഖയാണ് പ്രാമാണികമായ ഉറവിടമായി പരിഗണിക്കേണ്ടത്. നിർണായകമായ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ പരിഭാഷ ശുപാർശ ചെയ്യുന്നു. ഈ പരിഭാഷ ഉപയോഗിച്ച് ഉണ്ടാകുന്ന തെറ്റിദ്ധാരണകൾ അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾക്കായി ഞങ്ങൾ ഉത്തരവാദികളല്ല. \ No newline at end of file diff --git a/translations/ml/04-tools/README.md b/translations/ml/04-tools/README.md index 3dc8715eb..79ed3a3ab 100644 --- a/translations/ml/04-tools/README.md +++ b/translations/ml/04-tools/README.md @@ -1,84 +1,84 @@ -# മഡ്യൂൾ 04: ഉപകരണങ്ങളോടുകൂടിയ AI ഏജന്റുകൾ +# Module 04: ഓزارങ്ങളോടുകൂടിയ AI ഏജന്റുകൾ ## ഉള്ളടക്ക പട്ടിക -- [വീഡിയോ വാക്ക്‌ത്രൂ](../../../04-tools) -- [നിങ്ങൾ പഠിക്കുന്നതു](../../../04-tools) -- [ആവശ്യമായ മുൻ‌പരിചയം](../../../04-tools) -- [ഉപകരണങ്ങളോടുകൂടിയ AI ഏജന്റുകൾ മനസിലാക്കൽ](../../../04-tools) -- [ഉപകരണ കോൾ ചെയ്യൽ എങ്ങനെ പ്രവർത്തിക്കുന്നു](../../../04-tools) - - [ഉപകരണ നിർവചനങ്ങൾ](../../../04-tools) - - [തീരുമാനം എടുക്കൽ](../../../04-tools) - - [എക്സിക്യൂഷൻ](../../../04-tools) - - [പ്രതികരണം സൃഷ്ടിക്കൽ](../../../04-tools) - - [വാസ്തുവിദ്യ: സ്പ്രിംഗ് ബൂട്ട് ഓട്ടോ-വയർ](../../../04-tools) -- [ഉപകരണ ചെയിനിംഗ്](../../../04-tools) -- [അപ്ലിക്കേഷൻ പ്രവർത്തിപ്പിക്കുക](../../../04-tools) -- [അപ്ലിക്കേഷൻ ഉപയോഗിക്കൽ](../../../04-tools) - - [সরൾ ഉപകരണ ഉപയോഗം പരീക്ഷിക്കുക](../../../04-tools) - - [ഉപകരണ ചെയിനിംഗ് പരിശോധിക്കുക](../../../04-tools) - - [സംവാദ പ്രവാഹം കാണുക](../../../04-tools) - - [വിവിധ അഭ്യർത്ഥനകളുമായി പരീക്ഷണം നടത്തുക](../../../04-tools) -- [പ്രധാന ആശയങ്ങൾ](../../../04-tools) - - [ReAct മാതൃക (തീർച്ചയും പ്രവർത്തനവും)](../../../04-tools) - - [ഉപകരണ വിവരണങ്ങൾ പ്രാധാന്യം വഹിക്കുന്നു](../../../04-tools) - - [സെഷൻ മാനേജ്‌മെന്റ്](../../../04-tools) - - [പിഴവ് കൈകാര്യം ചെയ്യൽ](../../../04-tools) -- [ലഭ്യമായ ഉപകരണങ്ങൾ](../../../04-tools) -- [ഉപകരണഭാസ നിർവഹണ ഏജന്റുകൾ എപ്പോൾ ഉപയോഗിക്കണം](../../../04-tools) -- [ഉപകരണങ്ങൾ vs RAG](../../../04-tools) -- [അടുത്ത നടപടി](../../../04-tools) +- [വീഡിയോ വാക്ക്‌ത്രൂ](#വീഡിയോ-വാക്ക്‌ത്രൂ) +- [നിങ്ങൾ പഠിക്കുന്നത്](#നിങ്ങൾ-പഠിക്കുന്നത്) +- [അവശ്യപ്പെടുന്നതിന്റേതുകൾ](#ആവശ്യകതകൾ) +- [ഓजारങ്ങളോടുകൂടിയ AI ഏജന്റുകളെ അറിയുക](#ഓजारങ്ങളോടുകൂടിയ-ai-ഏജന്റുകൾ-അറിയുക) +- [ഓजारഭോഗം എങ്ങനെ പ്രവർത്തിക്കുന്നു](#ഓജാർ-വിളിക്കുന്ന-വിധം) + - [ഓജാര നിർവചനം](#ഓജാർ-നിർവചനം) + - [നിർണയമെടുക്കൽ](#നിർണയമെടുക്കൽ) + - [നടത്തൽ](#നടപ്പാക്കൽ) + - [പ്രതികരണം ഉണ്ടാക്കൽ](#മറുപടി-സൃഷ്ടിക്കൽ) + - [സാമ്പ്രദായിക ഘടകങ്ങൾ: സ്പ്രിംഗ് ബൂട്ട് ഓട്ടോ-വയരിംഗ്](#സാമ്പ്രദായിക-ഘടകങ്ങൾ-സ്പ്രിംഗ്-ബൂട്ട്-ഓട്ടോ-വയരിംഗ്) +- [ഓജാര ചൈൻ ചെയ്യൽ](#ഓജാര-ചൈൻ-ചെയ്യൽ) +- [ആപ്ലിക്കേഷൻ ഓടിക്കുക](#ആപ്ലിക്കേഷൻ-ഓടിക്കുക) +- [ആപ്ലിക്കേഷൻ ഉപയോഗിക്കൽ](#അപ്ലിക്കേഷൻ-ഉപയോഗിക്കൽ) + - [പൊതുവായ ഓജാര ഉപയോഗം ശ്രമിക്കുക](#ലളിതമായ-ഉപകരണം-ഉപയോഗിച്ച്-പരീക്ഷിക്കുക) + - [ഓജാര ചൈൻ പരിശോധന](#ഉപകരണങ്ങൾ-ബന്ധിപ്പിച്ച്-പരീക്ഷിക്കുക) + - [സംവാദ പ്രവാഹം കാണുക](#സംഭാഷണ-പ്രവാഹം-കാണുക) + - [വിവിധ അപേക്ഷകൾ പരീക്ഷിക്കുക](#വ്യത്യസ്ത-അഭ്യർത്ഥനകളോടൊപ്പം-പരീക്ഷിക്കുക) +- [പ്രധാന ആശയങ്ങൾ](#പ്രധാന-ആശയങ്ങൾ) + - [ReAct മാതൃക (ചിന്തനവും പ്രവർത്തനവും)](#react-പാറ്റേൺ-കാരണം-പറയൽ-കൂടാതെ-പ്രവർത്തിക്കുന്നു) + - [ഓജാര വിവരണങ്ങൾ പ്രാധാന്യം ഉള്ളവയാണ്](#ഉപകരണ-വിവരണങ്ങൾ-പ്രധാനമാണ്) + - [സെഷൻ മാനേജ്മെന്റ്](#സെഷൻ-മാനേജുമെന്റ്) + - [പിശക് കൈകാര്യംചെയ്യൽ](#പിഴവ്-കൈകാര്യംചെയ്യൽ) +- [ചില ഓജാരങ്ങൾ](#ലഭ്യമായ-ഉപകരണങ്ങൾ) +- [ഓജാര അടിസ്ഥാനമാക്കിയുള്ള ഏജന്റുകൾ ഉപയോഗിക്കേണ്ട സമയം](#ഉപകരണം-അടിസ്ഥാനമായ-ഏജന്റുകൾ-എப்போது-ഉപയോഗിക്കണമെന്ന്) +- [ഓജാരങ്ങൾ vs RAG](#ഉപകരണങ്ങൾ-vs-rag) +- [അടുത്ത ഘട്ടങ്ങൾ](#അടുത്ത-പടികൾ) ## വീഡിയോ വാക്ക്‌ത്രൂ -ഈ മഡ്യൂളിൽ എങ്ങനെ തുടങ്ങാമെന്ന് വിശദീകരിക്കുന്ന ലൈവ് സെഷൻ കാണുക: +ഈ ലൈവ് സെഷൻ കാണുക, ഈ മോഡ്യൂൾ ആരംഭിക്കുന്നത് എങ്ങനെ എന്നത് വിശദീകരിക്കുന്നു: -ഉപകരണങ്ങളോടുകൂടിയ AI ഏജന്റുകളും MCP - ലൈവ് സെഷൻ +ഓजारങ്ങളോടുകൂടിയ AI ഏജന്റുകളും MCP - ലൈവ് സെഷൻ -## നിങ്ങൾ പഠിക്കുന്നതു +## നിങ്ങൾ പഠിക്കുന്നത് -ഇതുവരിടെ, നിങ്ങൾ AI-യുമായി സംവദിക്കാനും, പ്രോംപ്റ്റുകൾ ഫലപ്രദമായി ഘടിപ്പിക്കാനും, നിങ്ങളുടെ ഡോക്യുമെന്റുകളുമായി പ്രതികരണങ്ങളെ മുടക്കി സംരക്ഷിക്കാനും പഠിച്ചു. പക്ഷേ ഒരു അടിസ്ഥാനപരമായ പരിമിതി ഉണ്ട്: ഭാഷാ മോഡലുകൾ ടെക്സ്റ്റ് മാത്രമേ സൃഷ്ടിക്കുകയുള്ളൂ. അവർ ധ്രുവീകരണം പരിശോധിക്കാനോ, കണക്കുകൾ നടത്താനോ, ഡാറ്റാബേസുകൾ ക്വറിയുചെയ്യാനോ, ബാഹ്യ സംവിധാനങ്ങളുമായി ഇടപഴകാനോ കഴിയുകയില്ല. +ഇത് വരെ, നിങ്ങൾ എഐയുമായി സംവദിക്കുന്നത്, പ്രോംപ്റ്റുകൾ ഫലപ്രദമായി ഘടിപ്പിക്കുന്നത്, മറുപടികൾ നിങ്ങളുടെ രേഖകളിൽ അടിസ്ഥാനം ചെയ്യുന്നത് തുടങ്ങിയവ പഠിച്ചു. എന്നാൽ ഒരു അടിസ്ഥാനപരമായ പരിമിതി ഇനിയും നിലനിൽക്കുന്നു: ഭാഷാ മോഡലുകൾക്ക് വെറും ടെക്സ്റ്റ് സൃഷ്ടിക്കാനാണ് കഴിവ്. അവ കാലാവസ്ഥ പരിശോധിക്കാനോ, കണക്കാക്കി പ്രവർത്തിക്കാനോ, ഡാറ്റാബേസുകൾ തിരയാനോ, ബാഹ്യ സംവിധാനങ്ങളുമായി ഇടപഴകാനോ കഴിയില്ല. -ഉപകരണങ്ങൾ ഇതു മാറ്റുന്നു. മോഡലിന് ആകെയുള്ള ഫംഗ്ഷനുകൾ ഉപയോഗിക്കാൻ സാധിക്കുന്നതായി നൽകുന്നത് വഴി അത് ടെക്സ്റ്റ് ജനറേറ്ററിൽ നിന്ന് പ്രവർത്തനം നടത്തുന്ന ഏജന്റായി മാറുന്നു. മോഡൽ എപ്പോൾ ഉപകരണമടങ്ങിയ താൽപര്യമുണ്ടെന്നും, ഏത് ഉപകരണമാണ് ഉപയോഗിക്കേണ്ടതെന്നും, ഏത് പാരാമീറ്ററുകൾ കൈമാറണമെന്ന് തീരുമാനിക്കുന്നു. നിങ്ങളുടെ കോഡ് ആ ഫംഗ്ഷൻ ആ 型ാന്ന് ഫലം തിരിച്ച് നൽകുന്നു. മോഡൽ ഇത് അതിന്റെ പ്രതികരണത്തിൽ ഉൾകൊള്ളിക്കുന്നു. +ഓജാരങ്ങൾ ഇതു മാറ്റുന്നു. മോഡലിന് വിളിക്കാനാകുന്ന ഫംഗ്ഷനുകൾ നൽകുമ്പോൾ, നിങ്ങൾ അതിനെ ഒരു ടെക്സ്റ്റ് ജനറേറ്റർ നിന്ന് പ്രവർത്തനശേഷിയുള്ള ഏജന്റായി മാറ്റുന്നു. മോഡൽ ഒരിക്കൽ ഓജാരത്തെ ആവശ്യക്കായി, ഏത് ഓജാരാണ് ഉപയോഗിക്കേണ്ടത്, ഏതെല്ലാം പാരാമീറ്ററുകൾ അയക്കേണ്ടത് എന്നിവ തീരുമാനിക്കുന്നു. നിങ്ങളുടെ കോഡ് ആ ഫംഗ്ഷൻ നടപ്പിലാക്കി ഫലം തിരിച്ച് നൽകും. മോഡൽ ആ ഫലം തന്റെ മറുപടിയിൽ ഉൾപ്പെടുത്തുന്നു. -## ആവശ്യമായ മുൻ‌പരിചയം +## ആവശ്യകതകൾ -- [Module 01 - പരിചയം](../01-introduction/README.md) പൂർത്തിയാക്കിയത് (Azure OpenAI സ്രോതസ്സുകൾ വിന്യസിച്ചത്) -- മുൻപ് നിർദ്ദേശിച്ച മഡ്യൂളുകൾ പൂർത്തിയാക്കിയിട്ടുണ്ടെന്ന് ഉറപ്പാക്കുക (ഈ മഡ്യൂൾ [Module 03 ന്റെ RAG ആശയങ്ങൾ](../03-rag/README.md) ഉപകരണങ്ങൾ vs RAG താരതമ്യത്തിൽ പരാമർശിക്കുന്നു) -- റൂട്ട് ഡയറക്ടറിയിൽ `.env` ഫയൽ Azure ക്രെഡൻഷ്യലുകളുമായി ഉണ്ടാകണം (Module 01-ൽ `azd up` ഉപയോഗിച്ചാണ് സൃഷ്ടിച്ചിരിക്കുന്നത്) +- പൂർത്തിയാക്കിയ [Module 01 - പരിചയം](../01-introduction/README.md) (Azure OpenAI സ്രോതസ്സുകൾ വിന്യസിച്ചിട്ടുണ്ട്) +- മുൻ മോഡ്യൂളുകൾ പൂർത്തിയാക്കിയിട്ടുണ്ടെങ്കിൽ ഉത്തമം (ഈ മോഡ്യൂൾ [Module 03 - RAG ആശയങ്ങൾ](../03-rag/README.md) -ൽ നിന്നുള്ള സാന്ദർഭികവിവരങ്ങളെ പരാമർശിക്കുന്നു ടൂളുകളും RAG ഉം തമ്മിലുള്ള താരതമ്യത്തിൽ) +- റൂട്ട് ഡയറക്ടറിയിൽ `.env` ഫയൽ Azure ക്രെഡൻഷ്യലുകളോടുകൂടി (Module 01 ൽ `azd up` സൃഷ്ടിച്ചത്) -> **കുറിപ്പ്:** Module 01 പൂർത്തിയാക്കിയിട്ടില്ല എങ്കിൽ ആദ്യം അവിടെയുള്ള വിന്യാസ നിർദ്ദേശങ്ങൾ പിന്തുടരുക. +> **കുറിപ്പ്:** Module 01 പൂർത്തിയാക്കാത്തവരാണ് ഇനിയും, ആദ്യം അവിടെ നൽകിയ വിന്യാസ നിർദ്ദേശങ്ങൾ പാലിക്കുക. -## ഉപകരണങ്ങളോടുകൂടിയ AI ഏജന്റുകൾ മനസിലാക്കൽ +## ഓजारങ്ങളോടുകൂടിയ AI ഏജന്റുകൾ അറിയുക -> **📝 കുറിപ്പ്:** ഈ മഡ്യൂളിലെ "ഏജന്റുകൾ" എന്ന പദം ഉപകരണം കോൾ ചെയ്യാനുള്ള ശേഷിയുള്ള AI അസിസ്റ്റന്റുകളെ സൂചിപ്പിക്കുന്നു. ഇത് [Module 05: MCP](../05-mcp/README.md) ല് കാണിക്കുന്ന **Agentic AI** മാതൃകകൾ (സ്വയം നയിക്കുന്ന, ഓർമ്മയുള്ള, ബഹു-ചുവട് റാസണിംഗ് ഉൾക്കൊള്ളുന്ന ഏജന്റുകൾ)താരതമ്യേന വ്യത്യസ്തമാണ്. +> **📝 കുറിപ്പ്:** ഈ മോഡ്യൂളിൽ "ഏജന്റുകൾ" എന്നു പറഞ്ഞാൽ ഓജാർ-കോൾ കഴിവുള്ള AI അസിസ്റ്റന്റുകളെയാണ് സൂചിപ്പിക്കുന്നത്. ഈ പാറ്റേണുകൾ [Module 05: MCP](../05-mcp/README.md) യിൽ കവർ ചെയ്യുന്ന ഓട്ടോണോമസ് ഏജന്റുകൾക്ക് വ്യത്യസ്തമാണ് (ആസൂത്രണം, മെമ്മറി, ബഹു-വഴിയുള്ള ചിന്തനം എന്നിവയുള്ള). -ഉപകരണങ്ങളില്ലാതെ, ഭാഷാ മോഡൽ അതിന്റെ പരിശീലന ഡാറ്റയിൽ നിന്നുള്ള ടെക്സ്റ്റ് മാത്രമേ സൃഷ്ടിക്കുകയുള്ളു. ഇപ്പോഴത്തെ കാലാവസ്ഥ ചോദിച്ചാൽ അനുഭവം കണക്കാക്കി ഉത്തരമാകും. ഉപകരണങ്ങൾ നൽകിയാൽ അത് കാലാവസ്ഥ API-നെ വിളിക്കാം, കണക്കുകൾ നടത്താം, അല്ലെങ്കിൽ ഡാറ്റാബേസ്‌ ക്വറി ചെയ്യാം — പിന്നീട് അവ യഥാർത്ഥ ഫലങ്ങളായി തിരിച്ചുവാങ്ങി അതിന്റെ പ്രതികരണത്തിൽ ചേർക്കും. +ഓജാരങ്ങൾ ഇല്ലാതെയുള്ള ഭാഷാ മോഡൽ വെറും ടെക്സ്റ്റാണ് സൃഷ്ടിക്കാൻ കഴിവുള്ളത്. ഇന്നത്തെ കാലാവസ്ഥ ചോദിച്ചാൽ, അത് ഗസ്സിക്കേണ്ടി വരും. ഓജാരങ്ങൾ നൽകി, അത് കാലാവസ്ഥ API-യെ വിളിക്കാനും കണക്കുകൾ നിർവഹിക്കാനും ഡാറ്റാബേസ് അന്വേഷിക്കാനും കഴിയും — ആ യഥാർത്ഥ ഫലങ്ങൾ തന്റെ മറുപടിയിൽ അടങ്ങിയിടും. -ഉപകരണങ്ങളില്ലാതെ vs ഉപകരണങ്ങളോടെ +ഓജാരങ്ങൾ ഇല്ലാതെയും ഓജാരങ്ങളോടും -*ഉപകരണങ്ങളില്ലാതെ മോഡൽ സാധാരണയായി പശ്ചാത്തല അവബോധം അനുസരിച്ച് നിഗമനം ചെയ്യുന്നുവെങ്കിലും, ഉപകരണങ്ങളോടെ അത് API കളെ വിളിച്ചു, കണക്കു നടത്തിയും യഥാർത്ഥ ധ്രുതമായ ഡാറ്റ നൽകുകയും ചെയ്യുന്നു.* +*ഓജാരമില്ലാതെ മോഡൽ ഗസ് ചെയ്യുമ്പോൾ മാത്രം കഴിയും — ഓജാരത്തോടൊപ്പം അത് APIs വിളിക്കാനും കണക്കുകൾ നിർവഹിക്കാനും യഥാർഥ സമയ ഡാറ്റ നൽകാനും കഴിയും.* -ഉപകരണങ്ങളോടുകൂടിയ AI ഏജന്റ് **ReAct** (Reasoning and Acting) മാതൃക പിന്തുടരുന്നു. മോഡൽ വെറും പ്രതികരണം നൽകാതെ, അതിന് എന്ത് വേണമെന്നു ആലോചിച്ച്, ഉപകരണം വിളിച്ച്, ഫലം നിരീക്ഷിച്ച്, പിന്നെ വീണ്ടും പ്രവർത്തിക്കണമോ അല്ലെങ്കിൽ അന്തിമ ഉത്തരം നൽകണമോയെന്ന് തീരുമാനിക്കുന്നു: +ഒരു ഓജാരങ്ങളുമായ AI ഏജന്റ് **ReAct** (ചിന്തനവും പ്രവർത്തനവും) പാറ്റേൺ പിന്തുടരുന്നു. മോഡൽ വെറും മറുപടി നൽകുന്നതല്ല - അതിന്റെ ആവശ്യം എന്താണെന്ന് ചിന്തിച്ച്, ഓജാരത്തെ വിളിച്ച് പ്രവർത്തിച്ച്, ഫലം നിരീക്ഷിച്ച്, വീണ്ടും പ്രവർത്തിക്കണമോ അവസാന മറുപടി നൽകണോ എന്നത് തീരുമാനിക്കുന്നു: -1. **ആലോചന** — ഉപയോക്താവിന്റെ ചോദ്യം വിശകലനം ചെയ്ത് ആവശ്യമായ വിവരങ്ങൾ തിരിച്ചറിഞ്ഞു -2. **പ്രവർത്തനം** — ശരിയായ ഉപകരണം തിരഞ്ഞെടുക്കുകയും, ശരിയായ പാരാമീറ്ററുകൾ സൃഷ്ടിച്ച് അതിനെ വിളിക്കുകയും ചെയ്യുന്നു -3. **നിരീക്ഷണം** — ഉപകരണത്തിന്റെ ഫലം സ്വീകരിച്ച് അവലോകനം ചെയ്യുന്നു -4. **പുനരാവൃത്തി അല്ലെങ്കിൽ പ്രതികരണം** — കൂടുതൽ ഡാറ്റ ആവശ്യമായെങ്കിൽ വീണ്ടും ലൂപ്പ് നടത്തുന്നു; ഇല്ലെങ്കിൽ സ്വാഭാവിക ഭാഷയിൽ ഉത്തരം നൽകുന്നു +1. **ചിന്തിക്കുക** — ഉപയോക്താവിന്റെ ചോദ്യം വിശകലനം ചെയ്ത് ആവശ്യമുള്ള വിവരങ്ങൾ നിശ്ചയിക്കുക +2. **പ്രവർത്തിക്കുക** — ശരിയായ ഓജാര തിരഞ്ഞെടുക്കുക, ശരിയായ പാരാമീറ്ററുകൾ സൃഷ്ടിച്ച് വിളിക്കുക +3. **നിരീക്ഷിക്കുക** — ഓജാറിന്റെ ഫലം ലഭിച്ച് വിലയിരുത്തുക +4. **പുനരാവൃത്തി അല്ലെങ്കിൽ മറുപടി നൽകുക** — കൂടുതൽ ഡാറ്റ ആവശ്യമുണ്ടെങ്കിൽ തിരികെ ചുഴലികാകും, അല്ലെങ്കിൽ സ്വാഭാവിക ഭാഷയിൽ മറുപടി തയ്യാറാക്കും ReAct മാതൃക -*ReAct ചക്രം — ഏജന്റ് എന്ത് ചെയ്യണം എന്ന് ആലോചിക്കുന്നു, ഉപകരണം വിളിച്ച് പ്രവർത്തിക്കുന്നു, ഫലം നിരീക്ഷിച്ച് ഫലം ലഭിച്ചശേഷം വേണമെങ്കിൽ വീണ്ടും പ്രവർത്തിക്കുന്നു.* +*ReAct ചക്രം — ഏജന്റ് ചെയ്യേണ്ടത് എന്തെന്ന് ചിന്തിച്ച്, ഓജാരം വിളിച്ച് പ്രവർത്തിച്ചും, ഫലം നിരീക്ഷിച്ചും, അവസാനം മറുപടി നൽകുന്നതുവരെ പുനരാവൃത്തിക്കും.* -ഇത് സ്വയം നടക്കുന്നു. നിങ്ങൾ ഉപകരണങ്ങളും അവയുടെ വിവരണങ്ങളും നിർവചിക്കുന്നു. മോഡൽ എപ്പോൾ എങ്ങനെ ഉപകരണങ്ങൾ ഉപയോഗിക്കണമെന്ന് തീരുമാനിക്കുന്നു. +ഇത് സ്വയം നടക്കുന്നു. നിങ്ങൾ ഓജാരങ്ങളും അവയുടെ വിവരണങ്ങളും നിർവചിക്കുന്നു. മോഡൽ അത് ഉപയോഗിക്കേണ്ട സമയവും വിധവും തീരുമാനിക്കുന്നു. -## ഉപകരണ കോൾ ചെയ്യൽ എങ്ങനെ പ്രവർത്തിക്കുന്നു +## ഓജാർ വിളിക്കുന്ന വിധം -### ഉപകരണ നിർവചനങ്ങൾ +### ഓജാർ നിർവചനം [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -നിർവചനങ്ങളോടെയും പാരാമീറ്റർ വിശദാംശങ്ങളോടെയും ഫംഗ്ഷനുകൾ നിർവ്വചിക്കുന്നു. മോഡൽ ഈ വിവരണങ്ങൾ സിസ്റ്റം പ്രോംപ്റ്റിൽ കാണുകയും ഓരോ ഉപകരണവും എന്ത് ചെയ്യുമെന്ന് മനസിലാക്കുകയും ചെയ്യുന്നു. +വ്യക്തമായ വിവരണങ്ങളോടും പാരാമീറ്റർ വിശദീകരണങ്ങളോടും കൂടിയ ഫംഗ്ഷനുകൾ നിങ്ങൾ നിർവചിക്കുന്നു. മോഡൽ ഈ വിവരണങ്ങൾ തന്റെ സിസ്റ്റം പ്രോംപ്റ്റിൽ കാണുകയും ഏത് ഓജാരാണ് എന്ത് ചെയ്യുന്നത് എന്നത് മനസ്സിലാക്കുകയും ചെയ്യും. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // നിങ്ങളുടെ കാലാവസ്ഥ നോക്കൽ ലാജിക് + // നിങ്ങളുടെ കാലാവസ്ഥാന്വേഷണം ലാജിക് return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,292 +96,292 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Spring Boot ഉപയോഗിച്ച് അസിസ്റ്റന്റ് സ്വയം സർവീസ് ചെയ്യപ്പെട്ടിരിക്കുന്നു: -// - ChatModel ബീൻ -// - @Component ക്ലാസുകളിൽ നിന്നുള്ള എല്ലാ @Tool മെത്തഡുകളും -// - സെഷൻ മാനേജ്മെന്റിന് ChatMemoryProvider +// അസിസ്റ്റന്റ് സ്വയമേവ സ്പ്രിംഗ് ബൂട്ട് ഉപയോഗിച്ച് വയർ ചെയ്യപ്പെട്ടിരിക്കുന്നു: +// - ചാറ്റ് മോഡൽ ബീൻ +// - @Component ക്ലാസ്സുകളിൽ നിന്നുള്ള എല്ലാ @Tool മെത്തഡ്‌സും +// - സെഷൻ മാനേജ്മെന്റിനായി ChatMemoryProvider ``` -നോട്ടം: താഴെയുള്ള രേഖാചിത്രം ഓരോ അനോട്ടേഷനും AI യെ എപ്പോൾ ഉപകരണം വിളിക്കണമെന്നു, ഏത് തർക്കങ്ങൾ കൈമാറണമെന്നു മനസിലാക്കുവാൻ എങ്ങനെ സഹായിക്കുന്നുവെന്നും വിശദീകരിക്കുന്നു: +താഴെയുള്ള ഡയഗ്രാം ഓരോ അനോട്ടേഷനും വിശദീകരിച്ച് എഐക്ക് എപ്പോൾ എങ്ങനെ ഓജാരിനെ വിളിക്കാമെന്നും ഏത് പാരാമീറ്ററുകൾ നൽകണമെന്നും മനസ്സിലാക്കാൻ സഹായിക്കുന്നു: -ഉപകരണ നിർവചനങ്ങളുടെ ഘടന +ഓജാർ നിർവചനങ്ങളുടെ ഘടകങ്ങൾ -*ഉപകരണ നിർവചനത്തിന്റെ ഘടന — @Tool AI-യ്ക്ക് ഉപയോഗിക്കേണ്ട സമയം പറയുന്നു, @P ഓരോ പാരാമീറ്ററിനെയും വിവരണം നൽകുന്നു, @AiService സ്റ്റാർട്ടപ്പിൽ എല്ലാം ബന്ധിപ്പിക്കുന്നു.* +*ഓജാർ നിർവചന ഘടകം — @Tool എഐക്ക് ഉപയോഗിക്കേണ്ട സമയമറിയിക്കുന്നു, @P ഓരോ പാരാമീറ്ററെയും വിവരണം നൽകുന്നു, @AiService സ്റ്റാർട്ടപ്പിൽ എല്ലാതാം പ്രവർത്തനങ്ങളും ബന്ധിപ്പിക്കുന്നു.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റിൽ പരീക്ഷിക്കുക:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) തുറന്ന് ചോദിക്കുക: -> - "ഓപ്പൺവെതറ്മാപ്പ് പോലുള്ള യഥാർഥ കാലാവസ്ഥ API എങ്ങനെ ഇന്റഗ്രേറ്റ് ചെയ്യാം?" -> - "AI യെ ശരിയായി ഉപയോഗിക്കാൻ സഹായിക്കുന്ന നല്ല ഉപകരണ വിവരണം എന്താണ്?" -> - "API പിഴവുകളും നിരക്കും നിയന്ത്രണങ്ങളും ഉപകരണ നടപ്പിലാക്കലിൽ എങ്ങനെ കൈകാര്യം ചെയ്യാം?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റിൽ ശ്രമിക്കുക:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) തുറന്ന് ചോദിക്കൂ: +> - "റെൽ വേതർ API പോലെ OpenWeatherMap ഇന്റഗ്രേറ്റ് ചെയ്യുന്നത് എങ്ങനെ?" +> - "എഐ കൃത്യമായി ഉപയോഗിക്കാൻ സഹായിക്കുന്ന നല്ല ഓജാർ വിവരണത്തിന്റെ പ്രത്യേകതകൾ എന്തെല്ലാം?" +> - "API പിശകുകളും നിരക്കും വിന്യാസവും എങ്ങനെ ഹൈാൻഡിൽ ചെയ്യാം?" -### തീരുമാനമെടുക്കൽ +### നിർണയമെടുക്കൽ -ഉപയോക്താവ് "സിയാറ്റിലിലെ കാലാവസ്ഥ എന്താണ്?" എന്ന് ചോദിക്കുമ്പോൾ, മോഡൽ വെറുതെ ഒരു ഉപകരണം തിരഞ്ഞടുക്കാൻ പോകുന്നില്ല. അത് ഉപയോക്താവിന്റെ ഉദ്ദേശ്യം എല്ലാ ഉപകരണ വിവരണങ്ങളുമായി താരതമ്യം ചെയ്യുന്നു, പ്രാധാന്യം അനുസരിച്ച് സ്കോർ ചെയ്ത് ഏറ്റവും അനുയോജ്യമായത് തിരഞ്ഞെടുക്കുന്നു. പിന്നെ ശരിയായ പാരാമീറ്ററുകളുമായി ഘടനാപരമായ ഫംഗ്ഷൻ കോൾ സൃഷ്ടിക്കുന്നു — ഈ സന്ദർഭത്തിൽ `location` `"Seattle"` ആക്കി സജ്ജമാക്കുന്നു. +ഉപയോക്താവ് "സിയാട്ടിലിലെ കാലാവസ്ഥ എന്താണ്?" ചോദിച്ചാൽ, മോഡൽ യാദൃച്ഛികമായി ഓജാർ തിരഞ്ഞെടുക്കുകയല്ല. ഉപയോക്താവിന്റെ ഉദ്ദേശ്യം എല്ലാ ഓജാര വിവരണങ്ങളിൽ നിന്ന് താരതമ്യം ചെയ്ത്, പ്രാധാന്യ സ്കോർ ആകർന്ന് ഏറ്റവും അനുയോജ്യമായ ഒന്ന് തിരയുകയും സേ463 ചികയി തരണവെള്ള 6605847്റി സൂ 816 4608 വീണ്ടും പ 565242 70674 പരിചയായി — ഇതിൽ `location` `"Seattle"` ആക്കുന്നതാണ് ഉദാഹരണം. -ഉപകരണങ്ങൾ ഒന്നും ഉപയോക്താവിന്റെ അഭ്യർത്ഥനയുമായി പൊരുത്തപ്പെടുന്നില്ലെങ്കിൽ, മോഡൽ അതിന്റെ സ്വന്തം അറിവിൽ നിന്നു മറുപടി നൽകും. ഒരേ സമയം ഒരു ബാധ്യതയുള്ള നിരവധി ഉപകരണങ്ങൾ ഉണ്ടായാൽ ഏറ്റവും സവിശേഷമായത് തിരഞ്ഞെടുക്കുന്നു. +ഉപയോഗംക്കാർക്കൊന്നും ഓജാർ വേണ്ടെന്ന് തോന്നാതിരുന്നാൽ, മോഡൽ സ്വന്തം അറിവിൽ നിന്നു മറുപടി നൽകും. ഒന്നിലധികം ഓജാരുകൾ പൊരുത്തപ്പെട്ടാൽ ഏറ്റവും പ്രത്യേകമായത് തിരഞ്ഞെടുക്കും. -എങ്ങനെ AI ഏജന്റ് ഏത് ഉപകരണം ഉപയോഗിക്കണമെന്ന് തീരുമാനിക്കുന്നു +മോഡൽ ഓജാർ തിരഞ്ഞെടുക്കുന്ന വിധം -*ഉപയോക്താവിന്റെ ഉദ്ദേശ്യവുമായി എല്ലാ ലഭ്യമായ ഉപകരണങ്ങളും താരതമ്യം ചെയ്ത് മോഡൽ ഏറ്റവും അനുയോജ്യമായത് തിരഞ്ഞെടുക്കുന്നു — അതിനാൽ വ്യക്തവും സവിശേഷവുമായ ഉപകരണ വിവരണങ്ങൾ എഴുതുന്നത് പ്രധാനമാണ്.* +*ഉപയോക്താവിന്റെ ഉദ്ദേശ്യത്തിന് എതിരായി എല്ലാ ഓജാരുകളും വിലയിരുത്തി മികച്ച ഒന്ന് മോഡൽ തിരഞ്ഞെടുത്തു — അതുകൊണ്ടുതന്നെ വ്യക്തമായ, പ്രത്യേകമായ ഓജാർ വിവരണങ്ങൾ എഴുതുക.* -### എക്സിക്യൂഷൻ +### നടപ്പാക്കൽ [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot ആദ്യ ഭാഗത്തുതന്നെ `@AiService` ഇന്റർഫേസ് എല്ലാ രജിസ്റ്റർ ചെയ്ത ഉപകരണങ്ങളുമായുയോജിപ്പിക്കുന്നു, LangChain4j ഓട്ടോമാറ്റിക്കായി ഉപകരണ കോൾസ് എക്സിക്യൂട്ട് ചെയ്യുന്നു. ഉപയോഗത്തിന്റെ സ്വഭാവവും ശേഷം ലാംഗ്വേജ് മോഡൽ മുതൽ സ്വാഭാവിക ഭാഷ ഉത്തരം വരെ ആറു ഘട്ടങ്ങളായി ഒരു പൂർണ്ണ ഉപകരണം കോൾ പ്രവാഹം സഞ്ചരിക്കുന്നു: +സ്പ്രിംഗ് ബൂട്ട് `@AiService` ഇൻറർഫെയ്‌സിനൊപ്പം എല്ലാ രജിസ്റ്റർ ചെയ്ത ഓജാരുകളും ഓട്ടോമാറ്റിക്കായി വയർ ചെയ്യുന്നു, LangChain4j ഓജാർ വിളിപ്പിക്കൽ സ്വയം നടത്തുന്നു. ഉപയോക്താവിന്റെ സ്വാഭാവിക ഭാഷാ ചോദ്യത്തിൽ നിന്നു മറുപടി വരെയുള്ള ആറ് ഘട്ടങ്ങളിൽ മുഴുവൻ ഓജാർ വിളിപ്പിക്കൽ പ്രവാഹം കടന്നു പോകുന്നു: -ഉപകരണ കോൾ പ്രവാഹം +ഓജാർ വിളിപ്പിക്കൽ പ്രവാഹം -*മൊത്തത്തിൽ, ഉപയോക്താവ് ചോദ്യം രേഖപ്പെടുത്തുന്നു, മോഡൽ ഒരു ഉപകരണം തിരഞ്ഞെടുക്കുന്നു, LangChain4j അത് എക്സിക്യൂട്ട് ചെയ്യുന്നു, പിന്നെ മോഡൽ ഫലത്തെ സ്വാഭാവിക ഭാഷയിൽ മറുപടിയാക്കുന്നു.* +*ആർഭാട മൊത്തം പ്രവാഹം — ഉപയോക്താവ് ചോദ്യം ചോദിക്കുന്നു, മോഡൽ ഓജാർ തിരഞ്ഞെടുക്കുന്നു, LangChain4j അത് നടപ്പിലാക്കുന്നു, മോഡൽ ഫലം സ്വാഭാവിക മറുപടിയാക്കി കാഴ്‌ചവയ്ക്കുന്നു.* -Module 00-ൽ [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) നിങ്ങൾ ഓടിച്ചിട്ടുണ്ടെങ്കിൽ, ഈ മാതൃക പ്രവർത്തിക്കുന്നതായി നിങ്ങൾ കണ്ടിട്ടുണ്ട് — `Calculator` ഉപകരണങ്ങൾ സമാനമായ രീതിയിൽ വിളിച്ചിരുന്നു. താഴെയുള്ള പരമ്പരാ രേഖാചിത്രം ആ ഡെമോയിയുടെ ഉൾക്കാഴ്ച്ച കൽപ്പിച്ചു: +`AiServices` ഏതെങ്കിലും ഓജാറിനും ഓരോ വിളിപ്പിക്കൽ ലൂപ്പ് ഓടിക്കുന്നുണ്ട് — ഇവിടെ ലളിതമായ `Calculator` ഉപയോഗിച്ചാണ് പ്രതിനിധാനം. താഴെയുള്ള പട്ടികയിൽ ആ കോഡ് എങ്ങനെ പ്രവർത്തിക്കുന്നു എന്ന് വ്യക്തമാക്കുന്നു: -ഉപകരണ കോൾ പരമ്പരാമാത്ര നിശ്ചയചിത്രം +ഓജാർ വിളനിരത്തി സീക്വൻസ് ഡയഗ്രാം -*പ്രാരംഭ ഡെമോയിൽ നിന്നുള്ള ഉപകരണ കോൾ ലൂപ്പ് — `AiServices` നിങ്ങളുടെ സന്ദേശവും ഉപകരണ സ്കീമകളും LLM-ലേക്ക് അയയ്ക്കുന്നു, LLM `add(42, 58)` പോലെയുള്ള ഫംഗ്ഷൻ കോൾ പിന്തുടരുന്നു, LangChain4j `Calculator` ഓപ്പോരി സംഗീതം പ്രാദേശികമായി പ്രവർത്തിപ്പിക്കുന്നു, ഫലം തിരിച്ചറിയിച്ച് അന്തിമ ഉത്തരത്തിന് നല്‍കുന്നു.* +*ഓജാർ വിളനിരത്ത് — `AiServices` നിങ്ങളുടെ സന്ദേശവും ഓജാർ സ്കീമകളും LLM-ലേക്ക് അയയ്ക്കുന്നു, LLM `add(42, 58)` പോലെയുള്ള ഫംഗ്ഷൻ കോളുമായി മറുപടി നൽകുന്നു, LangChain4j `Calculator` മെത്തഡ് പ്രാദേശികമായി പ്രവർത്തിപ്പിക്കുന്നു, ഫലം അവസാന മറുപടിക്ക് തരും.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റിൽ പരീക്ഷിക്കുക:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) തുറന്ന് ചോദിക്കുക: -> - "ReAct മാതൃക എങ്ങനെ പ്രവർത്തിക്കുന്നു, AI ഏജന്റുകൾക്കായി അത് എന്തുകൊണ്ട് ഫലപ്രദമാണ്?" -> - "ഏജന്റ് എങ്ങനെ ഏത് ഉപകരണം ഉപയോഗിക്കണമെന്ന്, യെന്ത് തോരണത്തിൽ തീരുമാനിക്കുന്നു?" -> - "ഒരു ഉപകരണ കോൾ പരാജയപ്പെട്ടാൽ എന്താകും - പിശക് മാനേജ്മെന്റ് എങ്ങനെ ശക്തമായി കൈകാര്യം ചെയ്യണം?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) ചാറ്റിൽ ശ്രമിക്കുക:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) തുറന്ന് ചോദിക്കൂ: +> - "ReAct മാതൃക എങ്ങനെ പ്രവർത്തിക്കുന്നു, ഇത് AI ഏജന്റിനായി എന്തുകൊണ്ട് ഫലപ്രദമാണ്?" +> - "ഏജന്റ് എങ്ങനെ ഓജാർ തിരഞ്ഞെടുക്കുന്നു, ഏതാണ്ടെന്ത് ക്രമത്തിൽ?" +> - "ഓജാർ പ്രവർത്തനം പരാജയപ്പെട്ടാൽ എന്താകും? പിശക് കൈകാര്യം ശക്തമായി എങ്ങനെ നടത്താം?" -### പ്രതികരണം സൃഷ്ടിക്കൽ +### മറുപടി സൃഷ്ടിക്കൽ -മോഡൽ കാലാവസ്ഥ ഡാറ്റ സ്വീകരിച്ച് ഉപയോക്താവിനുള്ള സ്വാഭാവിക ഭാഷാ മറുപടി രൂപപ്പെടുത്തുന്നു. +മോഡൽ കാലാവസ്ഥ ഡാറ്റ സ്വീകരിച്ച് ഉപയോക്താവിനായി സ്വാഭാവിക ഭാഷാ മറുപടിയാക്കി ഡാറ്റ ഫോർമാറ്റ് ചെയ്യുന്നു. -### വാസ്തുവിദ്യ: സ്പ്രിംഗ് ബൂട്ട് ഓട്ടോ-വയർ +### സാമ്പ്രദായിക ഘടകങ്ങൾ: സ്പ്രിംഗ് ബൂട്ട് ഓട്ടോ-വയരിംഗ് -ഈ മഡ്യൂൾ LangChain4j-യുടെ സ്പ്രിംഗ് ബൂട്ടിന്റെ `@AiService` ഇന്റർഫേസ് സംയോജനത്തെ ഉപയോഗിക്കുന്നു. സ്റ്റാർട്ടപ്പിൽ സ്പ്രിംഗ് ബൂട്ട് എല്ലാ `@Tool` രീതികളുള്ള `@Component`കളെ കണ്ടെത്തി, നിങ്ങളുടെ `ChatModel` ബീൻ, `ChatMemoryProvider` എന്നിവയെ ഒറ്റത്തവണ `Assistant` ഇന്റർഫേസിലേക്ക് തേക്കുകയും ബോയിൽറേറ്റ് ഇല്ലാതെ കണക്ഷൻ ചെയ്യുകയും ചെയ്യുന്നു. +ഈ മോഡ്യൂൾ LangChain4j-ന്റെ സ്പ്രിംഗ് ബൂട്ട് ഇന്റഗ്രേഷൻ ഉപയോഗിക്കുന്നു, `@AiService` ഡിക്ലറേറ്ററി ഇൻറർഫേസുകളോടെ. സ്പ്രിംഗ് ബൂട്ട് സ്റ്റാർട്ടപ്പിൽ എല്ലാ `@Component` കളെയും, `@Tool` മെത്തഡുകൾ ഉള്ളവയും, നിങ്ങളുടെ ChatModel ബീനും ChatMemoryProvider-ഉം കണ്ടെത്തി എല്ലാ കോമ്പോണന്റുകളും ഒറ്റ `Assistant` ഇൻറർഫേസിലേക്ക് വയർ ചെയ്യുന്നു. -സ്പ്രിംഗ് ബൂട്ട് ഓട്ടോ-വയർ വാസ്തുവിദ്യ +സ്പ്രിംഗ് ബൂട്ട് ഓട്ടോ വയരിംഗ് ആർക്കിടെക്ചർ -*എല്ലാ ഘടകങ്ങളും ChatModel, ഉപകരണങ്ങൾ, മെമ്മറി പ്രൊവൈഡർ ഒരുമിച്ച് `@AiService` ഇന്റർഫേസ് വഴി ബന്ധിപ്പിക്കുന്നു — സ്പ്രിംഗ് ബൂട്ട് ഇത് സ്വയമേവ കൈകാര്യം ചെയ്യുന്നു.* +*`@AiService` ഇൻറർഫേസ് ChatModel, ഓജാർ കോമ്പോണന്റുകൾ, മെമ്മറി പ്രൊവൈഡർ എന്നിവ ബന്ധിപ്പിക്കുന്നു — സ്പ്രിംഗ് ബൂട്ട് എല്ലാം സ്വയം വയർ ചെയ്യുന്നു.* -HTTP അഭ്യർത്ഥന മുതൽ നിയന്ത്രണകാരി, സർവീസ്, ഓട്ടോ-വയർഡ് പ്രോക്സി വഴിയുള്ള ഉപകരണ പ്രവർത്തനത്തിലും മറിച്ചുമുള്ള മുഴുവൻ അഭ്യർത്ഥന ജീവിതചക്രവ്യൂഹം ഒരു പരമ്പരാ രേഖാചിത്രം താഴെ: +HTTP അഭ്യർത്ഥന മുതൽ കൺട്രോളർ, സർവീസ്, ഓട്ടോ-വയർ ചെയ്ത് പ്രോക്സി വഴി ഓജാർ പ്രവർത്തനം വരെയുള്ള പൂർണ്ണ അഭ്യർത്ഥന ജീവിതചക്രം താഴെ SDD ആയി ലഭ്യമാണ്: -സ്പ്രിംഗ് ബൂട്ട് ഉപകരണ കോൾ പരമ്പര +സ്പ്രിംഗ് ബൂട്ട് ഓജാർ വിളിപ്പിക്കൽ സീക്വൻസ് -*മുഴുവൻ സ്പ്രിംഗ് ബൂട്ട് അഭ്യർത്ഥനയുടെ സഞ്ചാരം — HTTP അഭ്യർത്ഥനം നിയന്ത്രണകാരിയിലേക്കും സർവീസ് വഴി ഓട്ടോ-വയർഡ് അസിസ്റ്റന്റ് പ്രോക്സിയിലേക്കും കടന്നു, അത് LLM-ഉം ഉപകരണ കോൾസും ഓർക്കസ്ട്രേറ്റ് ചെയ്യുന്നു.* +*പിൂർണ്ണ സ്പ്രിംഗ് ബൂട്ട് അഭ്യർത്ഥന പ്രവാഹം — HTTP അഭ്യർത്ഥനം കൺട്രോളർ, സർവീസ്, ഓട്ടോ-വയർ ചെയ്ത Assistant പ്രോക്സിക്ക് കടന്നു LLM-നും ഓജാർ കോൾസിനും ഏകോപിപ്പിക്കും.* -ഈ സമീപനത്തിന്റെ പ്രധാന നേട്ടങ്ങൾ: +ഈ സമീപനത്തിന്റെ പ്രധാന ഗുണങ്ങൾ: -- **സ്പ്രിംഗ് ബൂട്ട് ഓട്ടോ-വയർ** — ChatModel, ഉപകരണങ്ങൾ സ്വയമേറ്റുവച്ചിരിക്കുന്നു -- **@MemoryId മാതൃക** — ആട്ടോമാറ്റിക് സെഷൻ അടിസ്ഥാനത്തിലുള്ള മെമ്മറി മാനേജ്‌മെന്റ് -- **ഏകഘടകം സൃഷ്ടിക്കൽ** — അസിസ്റ്റന്റ് ഒരിക്കൽ നേരിട്ട് സൃഷ്ടിച്ച് ഉയർന്ന പ്രകടനത്തിന് വീണ്ടും ഉപയോഗിക്കുന്നു -- **ടൈപ്പ്-സുരക്ഷിത എക്സിക്യൂഷൻ** — ജാവാ മെത്തഡുകൾ നേരിട്ട് ടൈപ്പ് പരിവർത്തനത്തോടെ വിളിക്കുന്നു -- **ബഹു-ടേൺ ഓർക്കസ്ട്രേഷൻ** — ഉപകരണ ചെയിനിംഗ് സ്വയം കൈകാര്യം ചെയ്യുന്നു -- **ബോയിൽറേറ്റ് ഇല്ലാതാക്കൽ** — കൈമാറ്റം ഇല്ലാത്ത `AiServices.builder()` കോൾസ് അല്ലെങ്കിൽ HashMap മെമ്മറി +- **സ്പ്രിംഗ് ബൂട്ട് ഓട്ടോ-വയരിംഗ്** — ChatModel ഉം ഓജാരുകളും സ്വയം ചേർക്കുന്നു +- **@MemoryId മാതൃക** — സ്വയം സെഷൻ അധിഷ്ഠിത മെമ്മറി മാനേജ്മെന്റ് +- **ഒറ്റ സംസ്‌ഥാനം** — Assistant ഒരിക്കൽ സൃഷ്ടിച്ച് മികച്ച പ്രകടനത്തിനായി വീണ്ടും ഉപയോഗിക്കുന്നു +- **ടൈപ്പ്-സേഫ് എക്സിക്യൂഷൻ** — ജാവ മെത്തഡുകൾ നേരിട്ടും ടൈപ്പ് കൺവർഷനോടെ വിളിക്കുന്നു +- **ബഹു-ടേൺ ഓർക്കസ്ട്രേഷൻ** — ഓജാർ ചൈൻ ചെയ്യൽ സ്വയമേവ കൈകാര്യം ചെയ്യുന്നു +- **മുടിച്ച് റെസ്പോൺസ് ഇല്ല** — 手动 `AiServices.builder()` കോളുകൾ അല്ല, മെമ്മറി ഹാഷ്മാപ് ഇല്ല -മാനുവൽ `AiServices.builder()` രീതികൾക്ക് കൂടുതൽ കോഡ് ആവശ്യമാണ്, എന് സ്പ്രിംഗ് ബൂട്ട് സംയോജനം കുറവാണ്. +മറ്റു സമീപനങ്ങൾ (`AiServices.builder()` മാനുവൽ) കൂടുതൽ കോഡ് ആവശ്യപ്പെടുകയും സ്പ്രിംഗ് ബൂട്ട് ഇന്റഗ്രേഷൻ ഗുണങ്ങൾ നഷ്ടപ്പെടുകയും ചെയ്യും. -## ഉപകരണ ചെയിനിംഗ് +## ഓജാര ചൈൻ ചെയ്യൽ -**ഉപകരണ ചെയിനിംഗ്** — ഉപകരണ സ്വഭാവമുള്ള ഏജന്റ് സിംഗിൾ ചോദ്യത്തിനായി ഒന്നിൽ കൂടുതൽ ഉപകരണങ്ങൾ ആവശ്യമുള്ളപ്പോൾ നൈസർഗ്ഗികമായ ശക്തി കാണിക്കുന്നു. "സിയാറ്റിലിലെ കാലാവസ്ഥ ഫാരൺഹീറ്റ് എങ്ങനെ ആണ്?" എന്ന ചോദ്യം ചോദിക്കുന്നുവെങ്കിൽ ഏജന്റ് രണ്ടു ഉപകരണങ്ങളും സ്വയം ചൈനുചെയ്യുന്നു: ആദ്യം `getCurrentWeather` വിളിച്ച് സെൽഷ്യസ് താപനില കണ്ടെത്തുന്നു, പിന്നെ ആ മൂല്യം `celsiusToFahrenheit`-ലേക്ക് നൽകുന്നു — എല്ലാം ഒരേ സംഭാഷണ ഘട്ടത്തിൽ. +**ഓജാർ ചൈൻ ചെയ്യൽ** — ടൂൾ അടിസ്ഥാനമാക്കിയുള്ള ഏജന്റുകളുടെ യഥാർത്ഥ ശക്തി ഒരു ചോദ്യം പല ഓജാരുകളും ആവശ്യപ്പെടുന്നപ്പോൾ പ്രകാശിക്കുന്നു. "സിയാട്ടിലിൽ ഫാരൻഹീറ്റിൽ കാലാവസ്ഥ എന്ത്?" എന്നു ചോദിച്ചാൽ ഏജന്റ് രണ്ട് ഓജാരുകൾ തോഴുകുന്നു: ആദ്യം `getCurrentWeather` വിളിച്ച് സെൽഷ്യസ് താപനില കണ്ടെത്തുന്നു, പിന്നെ അതു `celsiusToFahrenheit` കൊടുക്കുന്നു — ഇത് എല്ലാ സംവാദത്തിലേയ്ക്കും ഒറ്റ തിരിഞ്ഞിരുന്നു. -ഉപകരണ ചെയിനിംഗ് ഉദാഹരണം +ഓജാർ ചൈൻ ചെയ്ത് ഉദാഹരണം -*ഉപകരണ ചെയിനിംഗ് പ്രവർത്തനത്തിൽ — ഏജന്റ് ആദ്യം getCurrentWeather വിളിക്കുന്നുണ്ട്, പിന്നെ സെൽഷ്യസ് ഫലം celsiusToFahrenheit-ലേക്ക് പൈപ്പ് ചെയ്ത് സംയുക്ത ഉത്തരം നൽകുന്നു.* +*ഓജാർ ചൈൻ ചെയ്യുന്നതിന്റെ ഉദാഹരണം — ഏജന്റ് ആദ്യം getCurrentWeather വിളിക്കുന്നു, പിന്നീട് സെൽഷ്യസ് ഫലം celsiusToFahrenheit-ലേക്ക് അയക്കുന്നു, ഒടുവിൽ സംയോജിത മറുപടി നൽകുന്നു.* -**ഗ്രേസ്‌ഫുൾ പരാജയങ്ങൾ** — മോക്ക് ഡാറ്റയിൽ കിട്ടാത്ത നഗരത്തിലെ കാലാവസ്ഥ ചോദിക്കുമ്പോൾ, ഉപകരണം പിഴവ് സന്ദേശം തിരിച്ച് നൽകുന്നു, AI സഹായമാകാൻ കഴിയാത്തതായി വിശദീകരിക്കുന്നു, ആപ്ലിക്കേഷൻ ക്രാഷ് ചെയ്യേണ്ടതില്ല. ഉപകരണങ്ങൾ സുരക്ഷിതമായി പരാജയപ്പെടുന്നു. താഴെയുള്ള രേഖാചിത്രം രണ്ടു സമീപനങ്ങളെ താരതമ്യം ചെയ്യുന്നു — ശരിയായ പിഴവ് കൈകാര്യം ചെയ്താൽ ഏജന്റ് പ്രത്യേക പിഴവുകൾ പിടിച്ച് സഹായകരമായി മറുപടി നൽകുന്നു, ഇല്ലെങ്കിൽ മുഴുവൻ ആപ്ലിക്കേഷൻ ക്രാഷ് ചെയ്യുന്നു: +**ദയനീയമായ പരാജയങ്ങൾ** — മോക്ക് ഡാറ്റയിൽ ഇല്ലാത്ത നഗരത്തിലേക്ക് കാലാവസ്ഥ ചോദിക്കൂ. ഓജാർ ഒരു പിശക് സന്ദേശം നൽകുന്നു, AI സഹായിക്കുക കഴിയില്ല എന്ന് വിശദീകരിക്കുന്നു, എല്ലാവിധവും പൂട്ടണം എന്ന നില്ക്കുന്നില്ല. ഓജാർ സുരക്ഷിതമായി പരാജയപ്പെടും. താഴെയുള്ള ഡയഗ്രാം രണ്ടു മാർഗ്ഗങ്ങളും താരതമ്യം ചെയ്യുന്നു — ശരിയായ പിശക് കൈകാര്യം ചെയ്യലോടെ ഏജന്റ് ഇനം പിടിച്ച് സഹായക മറുപടി നൽകുന്നു; ഇല്ലെങ്കിൽ ആപ്ലിക്കേഷൻ പൂർണ്ണമായി ക്രാഷ് ചെയ്യും: -പിഴവ് കൈകാര്യം പ്രവാഹം +പിശക് കൈകാര്യം പ്രവാഹം -*ഉപകരണം പരാജയപ്പെടുമ്പോൾ, ഏജന്റ് പിഴവ് പിടിച്ച് സഹായകമായ വിശദീകരണം നൽകി മറുപടി നൽകുന്നു, ക്രാഷ് ചെയ്യാതെ.* +*ഒരു ഓജാർ പരാജയപ്പെടുമ്പോൾ, ഏജന്റ് പിശക് പിടിച്ച് ക്രാഷ് ചെയ്യാതെ സഹായകമായ വിശദീകരണം നൽകുന്നു.* -ഇത് ഒരേ സംഭാഷണ ഘട്ടത്തിൽ സംഭവിക്കുന്നു. ഏജന്റ് സ്വയം നിരവധി ഉപകരണ കോൾസ് ഏകോപിപ്പിക്കുന്നു. +ഇത് ഒറ്റ സംഭാഷണ തിരിഞ്ഞൽക്കുള്ളിലാണ്. ഏജന്റ് സ്വതന്ത്രമായി പല ഓജാറുകളുടെ വിളനിരത്തി ഏകോപിപ്പിക്കുന്നു. -## അപ്ലിക്കേഷൻ പ്രവർത്തിപ്പിക്കുക +## ആപ്ലിക്കേഷൻ ഓടിക്കുക -**ഡിപ്ളോയ്മെന്റ് പരിശോദിക്കുക:** +**വിന്യാസ സ്ഥിരീകരിക്കുക:** -റൂട്ട് ഡയറക്ടറിയിലെ `.env` ഫയൽ Azure ക്രെഡൻഷ്യലുകളുമായി ഉള്ളതായി ഉറപ്പാക്കുക (Module 01-ൽ സൃഷ്ടിച്ചത്). ഈ മഡ്യൂൾ ഡയറക്ടറിയിൽ നിന്ന് പ്രവർത്തിപ്പിക്കുക (`04-tools/`): +Azure ക്രെഡൻഷ്യലുകളോടെ `.env` ഫയൽ റൂട്ടിൽ ഉണ്ടെന്ന് ഉറപ്പാക്കുക (Module 01 ൽ സൃഷ്ടിച്ച). ഈ മോഡ്യൂൾ ഡയറക്ടറിയിൽ നിന്നും (`04-tools/`) ഓടിക്കുക: -**Bash:** +**ബാഷ്:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്കണം ``` -**PowerShell:** +**പവർഷെൽ:** ```powershell Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT കാണിക്കണം ``` -**അപ്ലിക്കേഷൻ തുടക്കം കുറിക്കുക:** +**ആപ്ലിക്കേഷൻ ആരംഭിക്കുക:** -> **കുറിപ്പ്:** നിങ്ങൾ മുമ്പ് റൂട്ട് ഡയറക്ടറിയിൽ നിന്നുള്ള `./start-all.sh` ഉപയോഗിച്ച് എല്ലാ അപ്ലിക്കേഷനുകളും ആരംഭിച്ചിരിക്കുകയാണെങ്കിൽ (Module 01-ൽ വിവരിച്ചതുപോലെ), ഈ മഡ്യൂൾ 8084 പോർ്റിൽ പ്രവർത്തിച്ചുകൊണ്ടിരിക്കുന്നു. താഴെ കൊടുത്ത ആരംഭം കമാൻഡുകൾ ഒഴിവാക്കിയാലും http://localhost:8084-ൽ നേരിട്ട് പോയി ഉപയോഗിക്കാം. +> **കുറിപ്പ്:** റൂട്ടിൽ നിന്ന് `./start-all.sh` ഉപയോഗിച്ചു എല്ലാ ആപ്ലിക്കേഷനുകളും നിങ്ങൾ ഇതിനകം ആരംഭിച്ചിട്ടുണ്ടെങ്കിൽ (Module 01 ൽ വിശദമായി), ഈ മോഡ്യൂൾ 8084 പോർട്ടിൽ പ്രവർത്തിക്കുന്നു. താഴെ കാണുന്ന സ്റ്റാർട്ട് കമാൻഡുകൾ ഒഴിവാക്കാം, നേരിട്ട് http://localhost:8084 സന്ദർശിക്കാം. -**ഓപ്ഷൻ 1: സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് ഉപയോഗിക്കൽ (VS കോഡ് ഉപയോക്താക്കൾക്കായി ശുപാർശ ചെയ്യുന്നു)** +**ഓപ്ഷൻ 1: സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് ഉപയോഗിക്കൽ (VS Code ഉപയോക്താക്കൾക്ക് ശുപാർശ)** -ഡെവ് കണ്ടെയ്നറിനൊപ്പം സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് വിപുലീകരണം ഉൾപ്പെടുത്തിയിട്ടുണ്ട്, ഇത് എല്ലാ സ്പ്രിംഗ് ബൂട്ട് അപ്ലിക്കേഷനുകളും ദൃശ്യമായി നിയന്ത്രിക്കാൻ സഹായിക്കുന്നു. VS കോഡിന്റെ ഇടതു Activity Bar ൽ സ്പ്രിംഗ് ബൂട്ട് ഐക്കൺ കണ്ടെത്താം. +ഡെവ് കണ്ടെയ്നറിൽ സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് എക്സ്റ്റെൻഷൻ ഉൾപ്പെടുത്തിയിട്ടുണ്ട്, എല്ലാ സ്പ്രിംഗ് ബൂട്ട് ആപ്ലിക്കേഷൻസ് നിയന്ത്രിക്കാൻ ദൃശ്യമാർഗം നൽകുന്നു. ഇത് VS Code Activity Bar-ൽ ഇടതുവശത്തായി സ്പ്രിംഗ് ബൂട്ട് ഐക്കണിൽ കാണാം. -സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡിൽ നിന്നും നിങ്ങൾക്ക്: -- വർക്ക്‌സ്പേസിലുള്ള എല്ലാ സ്പ്രിംഗ് ബൂട്ട് അപ്ലിക്കേഷനുകളും കാണാൻ -- ഒരു ക്ലിക്കിൽ അപ്ലിക്കേഷനുകൾ ആരംഭിപ്പിക്കാനും നിർത്താനും --リアൽ ടൈം ലോഗ്‌സ് കാണാനും -- അപ്ലിക്കേഷൻ സ്റ്റാറ്റസ് നിരീക്ഷിക്കാനും കഴിയും -"tools" എന്നതിന് പിന്നാലെ പ്ലേ ബട്ടൺ ക്ലിക്ക് ചെയ്ത് ഈ മോഡ്യൂള്‍ ആരംഭിക്കൂ, അല്ലെങ്കില്‍ എല്ലാ മോഡ്യൂളുകളും ഒരുതവണയില്‍ ആരംഭിക്കാം. +സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡിൽ നിന്നും: +- വർക്ക്സ്‌പേസിലെ എല്ലാ സ്പ്രിംഗ് ബൂട്ട് ആപ്ലിക്കേഷനുകളും കാണാം +- ക്ലിക്ക് മാത്രം കൊണ്ട് ആപ്ലിക്കേഷനുകൾ ആരംഭിക്കുക/നിർത്തുക +- റിയൽ-ടൈം ആപ്ലിക്കേഷൻ ലോഗുകൾ കാണുക +- ആപ്ലിക്കേഷൻ നില നിരീക്ഷിക്കുക -VS Code-ല്‍ Spring Boot ഡാഷ്ബോർഡ് ഈ രൂപത്തിലാണ്: +"tools" ന് അടുത്തുള്ള പ്ലേ ബട്ടൺ ക്ലിക്കുചെയ്ത് ഈ മോഡ്യൂൾ ആരംഭിക്കുക, അല്ലെങ്കിൽ എല്ലാ മോഡ്യൂളുകളെയും ഒരുമിച്ച് തുടങ്ങാം. -Spring Boot Dashboard +VS Code-ൽ സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് ഇങ്ങനെ കാണപ്പെടുന്നു: +സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് -*VS Code-യിലെ Spring Boot ഡാഷ്ബോർഡ് — എല്ലാ മോഡ്യൂളുകളും ഒരിടത്ത് നിന്നും തുടങ്ങി, നിർത്തി, നിരീക്ഷിക്കാം* +*VS കോഡിൽ സ്പ്രിംഗ് ബൂട്ട് ഡാഷ്ബോർഡ് — എല്ലാ മോഡ്യൂളുകളും ഒരു ഇടത്ത് നിന്നുതാൻ ആരംഭിക്കുക, നിർത്തുക, നിരീക്ഷിക്കുക* -**ഓപ്ഷൻ 2: shell script ഉപയോഗിച്ച്** +**അപ്ഷൻ 2: ഷെൽ സ്ക്രിപ്റ്റുകൾ ഉപയോഗിച്ച്** -എല്ലാ വെബ് ആപ്ലിക്കേഷനുകളും (മോഡ്യൂളുകൾ 01-04) ആരംഭിക്കുക: +എല്ലാ വെബ് അപ്ലിക്കേഷനുകളും (മുഖ്യമായ 01-04 മോഡ്യൂളുകൾ): -**Bash:** +**ബാഷ്:** ```bash -cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്ന് +cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്നാണ് ./start-all.sh ``` -**PowerShell:** +**പവർഷെൽ:** ```powershell -cd .. # റൂട്ട്ഡൈരക്ടറിയിൽ നിന്നുള്ളത് +cd .. # റൂട്ട് ഡയറക്ടറിയിൽ നിന്ന് .\start-all.ps1 ``` -അല്ലെങ്കിൽ ഈ മോഡ്യൂളും മാത്രം തുടങ്ങുക: +അല്ലെങ്കിൽ ഈ മോഡ്യൂളിനെ മാത്രം തുടങ്ങുക: -**Bash:** +**ബാഷ്:** ```bash cd 04-tools ./start.sh ``` -**PowerShell:** +**പവർഷെൽ:** ```powershell cd 04-tools .\start.ps1 ``` -രണ്ടും റൂട്ട് '.env' ഫയലിൽ നിന്നുള്ള പരിസ്ഥിതി വ്യത്യാസങ്ങൾ സ്വയമേ വാങ്ങുകയും ഇല്ലെങ്കിൽ JAR നിർമ്മിക്കുകയും ചെയ്യും. +രണ്ടു സ്ക്രിപ്റ്റുകളും സ്വയം റൂട്ടിലുള്ള `.env` ഫയൽ നിന്നുളള പരിസ്ഥിതി വ്യത്യാസങ്ങൾ ലോഡ് ചെയ്യുകയും If ഇൻജെക്‌ഷൻ ഉണ്ടാകാതെ ജാറുകൾ നിർമ്മിക്കും. -> **ഗమనിയ്ക്കുക:** എല്ലാ മോഡ്യൂളുകളുടെയും നിർമ്മാണം കൈകാര്യം ചെയ്ത് തുടങ്ങുവാൻ എങ്കിൽ: +> **കുറിപ്പ്:** നിങ്ങൾക്ക് മുന്നോടിയായി എല്ലാ മോഡ്യൂളുകളും മാനുവൽ ആയി നിർമ്മിച്ച് തുടങ്ങാൻ ആഗ്രഹിക്കുന്നുവെങ്കിൽ: > -> **Bash:** +> **ബാഷ്:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell:** +> **പവർഷെൽ:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -ബ്രൗസറിൽ http://localhost:8084 തുറക്കുക. +നിങ്ങളുടെ ബ്രൗസറിൽ http://localhost:8084 ഓപ്പൺ ചെയ്യുക. -**നിർത്താനായി:** +**നിർത്താൻ:** -**Bash:** +**ബാഷ്:** ```bash -./stop.sh # ഈ മോഡ്യൂള്‍ മാത്രം -# അല്ലെങ്കില്‍ +./stop.sh # ഈ മോഡ്യൂളിന് മാത്രം +# അല്ലെങ്കിൽ cd .. && ./stop-all.sh # എല്ലാ മോഡ്യൂളുകളും ``` -**PowerShell:** +**പവർഷെൽ:** ```powershell -.\stop.ps1 # ഈ മോഡ്യൂളിന് മാത്രം +.\stop.ps1 # ഈ മോഡ്യൂളിൽ മാത്രം # അല്ലെങ്കിൽ cd ..; .\stop-all.ps1 # എല്ലാ മോഡ്യൂളുകളും ``` -## ആപ്ലിക്കേഷന്‍ ഉപയോഗിക്കുക +## അപ്ലിക്കേഷൻ ഉപയോഗിക്കൽ -AI ഏജന്റിനോടുള്ള ഇന്റർഫേസ് ആണ് ആപ്ലിക്കേഷൻ നൽകുന്നത്, ഇത് കാലാവസ്ഥയും താപനില പരിവർത്തന ടൂളുകളും ഉപയോഗിക്കാൻ കഴിയുന്നുണ്ട്. ഇന്റർഫേസ് ഇതുപോലെയാണ് — ഇതിൽ വേഗത്തിൽ തുടങ്ങാൻ ഉദാഹരണങ്ങളും ആവശ്യങ്ങൾ അയയ്ക്കാൻ ചാറ്റ് പാനലും ഉൾപ്പെടുന്നു: +ഈ അപ്ലിക്കേഷൻ ഒരു വെബ് ഇന്റർഫെയ്‌സ് നൽകുന്നു, അവിടെ നിങ്ങൾക്ക് കാലാവസ്ഥയും താപനില പരിവർത്തന ഉപകരണങ്ങളും ഉപയോഗിച്ചാണ് AI ഏജന്റുമായി ഇടപഴകാനാകുക. ഇന്റർഫേസിന്റെ ദൃശ്യമാണ് — ഉടൻ തുടങ്ങാനുള്ള ഉദാഹരണങ്ങളും അഭ്യർത്ഥനകൾ അയക്കാനുള്ള ചാറ്റ് പാനലും ഉൾക്കൊള്ളുന്നു: -AI Agent Tools Interface +AI ഏജന്റ് ഉപകരണങ്ങളുടെ ഇന്റർഫേസ് -*AI ഏജന്റ് ടൂളുകളുടെ ഇന്റർഫേസ് - വേഗത്തിലുള്ള ഉദാഹരണങ്ങളും ടൂളുകളുമായി ഇടപഴകാനുള്ള ചാറ്റ് ഇന്റർഫേസും* +*AI ഏജന്റ് ഉപകരണങ്ങളുടെ ഇന്റർഫേസ് - ഉപകരണങ്ങളെക്കുറിച്ച് വളരെ പെട്ടെന്ന് തുടങ്ങാനുള്ള ഉദാഹരണങ്ങളും ചാറ്റ് ഇന്റർഫേസും* -### ലളിതമായ ടൂൾ ഉപയോഗം ശ്രമിക്കുക +### ലളിതമായ ഉപകരണം ഉപയോഗിച്ച് പരീക്ഷിക്കുക -"100 ഡിഗ്രി ഫാരൻഹീറ്റ് സെൽഷ്യസിലേക്ക് പരിവർത്തനം ചെയ്യുക" എന്ന ലളിതമായ അഭ്യർത്ഥനയുമായി ആരംഭിക്കുക. ഏജന്റ് താപനില പരിവർത്തന ടൂൾ ഉപയോഗിക്കേണ്ടതാണെന്ന് തിരിച്ചറിഞ്ഞ് ശരിയായ പാർമീറ്ററുകളോടെ വിളിച്ചു ഫലം തിരിച്ചു നൽകുന്നു. നിങ്ങൾക്ക് ഏത് ടൂൾ ഉപയോഗിക്കുന്നുവെന്ന് അല്ലെങ്കിൽ എങ്ങനെ വിളിക്കണമെന്ന് നിർദേശിക്കേണ്ടി വന്നില്ലെന്നും ശ്രദ്ധിക്കുക. +ഒരു நேர്ഗവം അഭ്യർത്ഥനയുമായി തുടങ്ങുക: "100 ഡിഗ്രി ഫാരൻഹീറ്റ് സെൽഷ്യസിലേക്ക് മാറ്റുക". ഏജന്റ് ഇതിന് താപനില പരിവർത്തന ഉപകരണം ആവശ്യമാണ് എന്ന് തിരിച്ചറിയുകയും ശരിയായ പാരാമീറ്ററുകളോടെ വിളിക്കുകയും ഫലം മറുപടി നൽകുകയും ചെയ്യും. നിങ്ങൾ ഉപകരണം ഉപയോഗിക്കേണ്ടെന്ന് അല്ലെങ്കിൽ എങ്ങനെ വിളിക്കാനെന്നത് വ്യക്തമാക്കിയില്ലെങ്കിലും എത്ര സ്വാഭാവികമായി ഇത് സംഭവിക്കുന്നു എന്ന് ശ്രദ്ധിക്കുക. -### ടൂൾ ചൈനിംഗ് പരീക്ഷിക്കുക +### ഉപകരണങ്ങൾ ബന്ധിപ്പിച്ച് പരീക്ഷിക്കുക -ഇപ്പോൾ ഏറെ സങ്കീർണ്ണമായ ഒന്നു ശ്രമിക്കുക: "സിയാട്ടിലിൽ കാലാവസ്ഥ എന്താണ്, അതിനെ ഫാരൻഹീറ്റിലേക്ക് പരിവർത്തനം ചെയ്യുക?" ഏജന്റ് ഇത് ഘട്ടങ്ങളായി നിർവഹിക്കുന്നു. ആദ്യം കാലാവസ്ഥ (സെൽഷ്യസ് ഫലം) നേടി, പിന്നീട് ഫാരൻഹീറ്റിലേക്ക് മാറ്റേണ്ടതുണ്ടെന്ന് തിരിച്ചറിഞ്ഞ് പരിവർത്തന ടൂൾ വിളിച്ച് രണ്ട് ഫലങ്ങളും ഒന്നിപ്പിച്ച് നൽകുന്നു. +ഇപ്പോൾ കുറച്ച്വരെ പ്രയാസമുള്ള കാര്യം ശ്രമിക്കുക: "സിയാറ്റിൽ എങ്ങനെ കാലാവസ്ഥ ഉണ്ട്, അതിനെ ഫാരൻഹീറ്റിലേക്കും മാറ്റുക?" ഏജന്റ് ഘട്ടപ്പെടുത്തി ജോലി ചെയ്യുന്നത് കാണുക. ഇത് ആദ്യം കാലാവസ്ഥ (സെൽഷ്യസ് നൽകുന്നു) നേടുകയും പിന്നീട് ഫാരൻഹീറ്റിലേക്കോ പരിവർത്തനം ചെയ്യാൻ ആവശ്യമായത് തിരിച്ചറിയുകയും, പരിവർത്തന ഉപകരണം വിളിക്കുകയും, രണ്ടിനും ഫലങ്ങൾ ഒരു മറുപടിയാക്കുകയും ചെയ്യുന്നു. ### സംഭാഷണ പ്രവാഹം കാണുക -ചാറ്റ് ഇന്റർഫേസ് സംഭാഷണത്തിന്റെ ചരിത്രം കൈവരിക്കുന്നു, നിങ്ങൾക്ക് ബഹുവട്ടം സംവാദങ്ങൾ നടത്താനാകും. മുൻപ് നൽകിയ എല്ലാ ചോദിച്ചലുകളും മറുപടികളും കാണാൻ കഴിയും, ഇത് സംഭാഷണം എങ്ങനെ തുടരുന്നു എന്നത് മനസ്സിലാക്കാൻ സഹായിക്കുന്നു. +ചാറ്റ് ഇന്റർഫേസ് സംഭാഷണ ചരിത്രം സൂക്ഷിക്കുന്നു, ഇത് നിങ്ങള്ക്ക് ഒട്ടേറെ ചുറ്റുവളർച്ചകളിൽ ഇടപഴകാൻ സഹായിക്കുന്നു. മുമ്പത്തെ എല്ലാ ചോദ്യങ്ങളും മറുപടികളും കാണാവുന്നതാണ്, ഇത് സംഭാഷണത്തെ പിന്തുടരാനും എങ്ങനെ ഏജന്റ് പല പരസ്പരം ചർച്ചകളിലൂടെ സാന്ദർഭ്യം ഒരുക്കുന്നു എന്നത് മനസ്സിലാക്കാനും സഹായിക്കുന്നു. -Conversation with Multiple Tool Calls +ജീവന്തമായ ഉപകരണങ്ങളുടെ നിരവധി വിളികളും ഉള്ള സംഭാഷണം -*ചില ലളിതമായ പരിവർത്തനങ്ങൾ, കാലാവസ്ഥ വിവരങ്ങൾ, ടൂൾ ചൈനിംഗ് ഉള്‍പെടെയുള്ള ബഹുവട്ട സംഭാഷണം* +*പല പ്രാവശ്യം ചർച്ചയിൽ ലളിതമായ പരിവർത്തനങ്ങൾ, കാലാവസ്ഥ പരിശോധിക്കൽ, ഉപകരണങ്ങൾ ബന്ധിപ്പിക്കൽ* -### വ്യത്യസ്ത അഭ്യർത്ഥനകൾ പരീക്ഷിക്കുക +### വ്യത്യസ്ത അഭ്യർത്ഥനകളോടൊപ്പം പരീക്ഷിക്കുക -വിവിധ സംയോജനങ്ങൾ ശ്രമിക്കുക: -- കാലാവസ്ഥ അന്വേഷിക്കുക: "ടോക്ക്യോയിലെ കാലാവസ്ഥ എന്താണ്?" -- താപനില പരിവർത്തനങ്ങൾ: "25°C കൽവിനിൽ എത്രയായിരിക്കും?" -- സംയുക്ത അഭ്യർത്ഥനകൾ: "പാരിസിലെ കാലാവസ്ഥ പരിശോധിച്ച്, 20°C-നുപുകളിലാണോ എന്ന് പറയൂ" +വിവിധ സംയോജിതങ്ങൾ ശ്രമിക്കുക: +- കാലാവസ്ഥ പരിശോധിക്കൽ: "ടോക്യോയിലുള്ള കാലാവസ്ഥ എന്താണ്?" +- താപനില പരിവർത്തനങ്ങൾ: "25°C എന്നത് കെൽവിനിൽ എത്ര?" +- സംയുക്ത ചോദ്യങ്ങൾ: "പാരിസിലെ കാലാവസ്ഥ പരിശോധിച്ച്, 20°C മുകളിലാണ് എങ്കിൽ പറയുക" -ഏജന്റ് സ്വാഭാവിക ഭാഷ പ്രത്യക്ഷപ്പെടുന്ന വിധം വ്യാഖ്യാനിക്കുകയും അതനുസരിച്ച് ടൂൾ വിളികൾ നടത്തുകയും ചെയ്യുന്നവിധം ശ്രദ്ധിക്കുക. +ഏജന്റ് പ്രകൃതിദത്ത ഭാഷയെ എങ്ങനെ വ്യാഖ്യാനിച്ച് അനുയോജ്യമായ ഉപകരണ വിളികളിലേക്കും മാറ്റുന്നതും ശ്രദ്ധിക്കുക. ## പ്രധാന ആശയങ്ങൾ -### ReAct പാറ്റേൺ (കാരണമിടലും പ്രവർത്തനവും) +### ReAct പാറ്റേൺ (കാരണം പറയൽ കൂടാതെ പ്രവർത്തിക്കുന്നു) -ഏജന്റ് കാരണവിധേയത്വവും (എന്ത് ചെയ്യണമെന്ന് തീരുമാനിക്കുക) പ്രവർത്തനവും (ടൂളുകൾ ഉപയോഗിക്കുക) ഇടയ്ക്കിടെ നടത്തുന്നുണ്ട്. ഇത് സ്വയം തീരുമാനങ്ങളെടുക്കാൻ സഹായിക്കുന്ന ഒരു മാതൃകയാണ്, നിർദ്ദേശങ്ങൾ പാലിക്കുന്നതിന് മാത്രം അല്ല. +ഏജന്റ് ചിന്തിക്കുന്ന (എന്തുചെയ്യണം എന്ന് തീരുമാനിക്കൽ) വൃത്താന്തവും പ്രവർത്തിക്കുന്ന (ഉപകരണങ്ങൾ ഉപയോഗിക്കൽ) വൃത്താന്തവും മാറിമാറി പ്രവർത്തിക്കുന്നു. ഇത് സ്വതന്ത്രമായി പ്രശ്ന പരിഹരിക്കാൻ സഹായിക്കുന്നു, നിർദ്ദേശങ്ങൾക്കുപകരം. -### ടൂൾ വിവരണങ്ങൾ പ്രധാനം +### ഉപകരണ വിവരണങ്ങൾ പ്രധാനമാണ് -ടൂൾ വിവരണങ്ങളുടെ ഗുണനിലവാരം ഏജന്റ് അവയെ എങ്ങനെ ഉപയോഗിക്കും എന്നതിൽ നേരിട്ട് ബാധിക്കുന്നു. പ്രത്യേകവും വ്യക്തവുമായ വിവരണങ്ങൾ മോഡലിന് ഏതു സാഹചര്യത്തിൽ ഒരു ടൂൾ വിളിക്കണം എന്ന് മനസ്സിലാക്കാൻ സഹായിക്കുന്നു. +നിങ്ങളുടെ ഉപകരണം വിവരണങ്ങളുടെ ഉത്ക്കൃഷ്ടത ഏജന്റ് അതിനെ എങ്ങനെ നല്ല വിധത്തിൽ ഉപയോഗിക്കുന്നു എന്നതിനെ നേരിട്ട് സ്വാധീനിക്കുന്നു. അർത്ഥപൂർണ്ണവും വ്യക്തമുമായ വിവരണങ്ങൾ മോഡലിന് ഉപകരണങ്ങൾ എപ്പോഴും എങ്ങനെയാണ് വിളിക്കേണ്ടത് എന്നത് മനസ്സിലാക്കാൻ സഹായിക്കുന്നു. -### സെഷൻ മാനേജ്മെന്റ് +### സെഷൻ മാനേജുമെന്റ് -`@MemoryId` അനോട്ടേഷൻ ഓട്ടോമാറ്റിക് സെഷൻ അടിസ്ഥാനമായ മെമ്മറി മാനേജ്മെന്റ് സജ്ജമാക്കുന്നു. ഓരോ സെഷൻ ഐഡിക്കും `ChatMemoryProvider` ബീൻ നിർത്തിച്ചിരിക്കുന്ന `ChatMemory` ഒരു ഉദാഹരണം ലഭിക്കുന്നു. അതുവഴി മള്‍ട്ടി-ഉപയോക്താക്കളും ഒരേ സമയം ഏജന്റുമായി സംവദിക്കാം, അവരുടെ സംഭാഷണങ്ങൾ ഇളക്കിവിടാതെ. താഴെയുള്ള ചിത്രത്തിൽ മൾട്ടി ഉപയോക്താക്കൾ സെഷൻ ഐഡികളുടെ അടിസ്ഥാനത്തിൽ എങ്ങനെ വേര്‍പ്പെട്ട് മെമ്മറി സ്റ്റോറുകളിൽ പോകുന്നതായി കാണിക്കുന്നു: +`@MemoryId` അനോട്ടേഷൻ സ്വയം സൈരണി അടിസ്ഥാനത്തിലുള്ള ഓർമ്മ മാനേജുമെന്റ് സജ്ജമാക്കുന്നു. ഓരോ സെഷൻ ഐഡിയ്ക്കും `ChatMemoryProvider` ബീൻ മാനേജു ചെയ്യുന്ന സ്വന്തം `ChatMemory` ഇൻസ്റ്റൻസ് ലഭിക്കുന്നു, അതിലൂടെ പല ഉപഭോക്താക്കളും ഒരേസമയം ഏജന്റുമായി ആശയവിനിമയം നടത്തുമ്പോഴും അവരുടെ സംഭാഷണങ്ങൾ പകർന്ന് പോകാറില്ല. താഴെ കാണുന്ന ചിത്രം പല ഉപയോക്താക്കൾ അവരുടെ സെഷൻ ഐഡിയ്ക്കനുസരിച്ച് വേർതിരിഞ്ഞ ഓർമ്മ സ്റ്റോറുകളിലേക്ക് бағытിക്കുന്നതിനെ കാണിക്കുന്നു: -Session Management with @MemoryId +@MemoryId ഉപയോഗിച്ച് സെഷൻ മാനേജുമെന്റ് -*ഓരോ സെഷൻ ഐഡി ഒരു വേർതിരിച്ച സംഭാഷണ ചരിത്രത്തോടെയാണ് ബന്ധിപ്പിച്ചിരിക്കുന്നത് — ഉപയോക്താക്കൾ birbirന്റെ സന്ദേശങ്ങൾ കാണില്ല.* +*ഓരോ സെഷൻ ഐഡിയും വേർതിരിഞ്ഞ സംഭാഷണ ചരിത്രത്തിലേക്ക് പരിശ്രമിക്കുന്നു — ഉപയോക്താക്കൾ ഒരുപരസ്പരം സന്ദേശങ്ങൾ കാണാറില്ല.* -### പിശകുകൾ കൈകാര്യം ചെയ്യൽ +### പിഴവ് കൈകാര്യംചെയ്യൽ -ടൂളുകൾ വിജയിക്കാതെ പോയേക്കാം — API ടൈംഔട്ട്, തെറ്റായ പാർമീറ്ററുകൾ, ബാഹ്യ സേവനങ്ങൾ ലഭ്യമാകില്ല. പ്രൊഡക്ഷൻ ഏജന്റുകൾക്ക് പിശകുകൾ കൈകാര്യം ചെയ്യേണ്ടതുണ്ട്. ടൂൾ ഒരു പിശക് കിളിച്ചതാൽ LangChain4j അതുചേർത്ത് മോഡലിന് പിശകിന്റെ സന്ദേശം നൽകും, മോഡൽ അത് സ്വാഭാവിക ഭാഷയിൽ വിശദീകരിക്കാൻ കഴിയും. +ഉപകരണങ്ങൾ പരാജയപ്പെടാറുണ്ട് — APIകൾ സമയംമീതിയാകാം, പാരാമീറ്ററുകൾ തെറ്റായിരിക്കാം, ബാഹ്യ സർവീസുകൾ അടഞ്ഞിരിക്കാൻ സാധ്യതയുണ്ട്. ഉത്പാദന ഏജന്റുകൾക്ക് പിഴവ് കൈകാര്യം ചെയ്യൽ ആവശ്യമുണ്ട്, അതുവഴി മോഡൽ പ്രശ്നങ്ങൾ വിശദീകരിക്കാൻ, അല്ലെങ്കിൽ പകരം മാർഗങ്ങൾ പരീക്ഷിക്കാൻ കഴിയും, ആപ്ലിക്കേഷൻ മുഴുവനായും തകർച്ചയുണ്ടാക്കാതെ. ഒരു ഉപകരണം തകരാറിലായാൽ, LangChain4j അതിനെ പിടിച്ച് പിഴവ് സന്ദേശം മോഡലിലേക്ക് Feeding ചെയ്തു, അത് പ്രകൃതിദത്ത ഭാഷയിൽ പ്രശ്നം വിശദീകരിക്കാനാകും. -## ലഭ്യമായ ടൂളുകൾ +## ലഭ്യമായ ഉപകരണങ്ങൾ -താഴെയുള്ള വരച്ചിങ്കൽ നിങ്ങൾ റെഡിയാക്കിയെടുക്കാൻ കഴിയുന്ന വിവിധ ടൂൾസുകളുടെ ഒറ്റനോട്ടം ആണ്. ഈ മോഡ്യൂളിൽ കാലാവസ്ഥയും താപനില ടൂളുകളും കാണിക്കുന്നുവെങ്കിലും, ആകെ `@Tool` പാറ്റേൺ ഏതൊരു ജാവാ മെഥഡിനും ഉപയോഗിക്കാം — ഡേറ്റാബേസിന്റെ ക്വറിയുകൾ മുതൽ പേയ്മെന്റ് പ്രോസസ്സിങ്ങ് വരെ. +താഴെയുള്ള ആകൃതിയിലെത്താം, നിങ്ങൾ നിർമ്മിക്കാവുന്ന ഉപകരണങ്ങളുടെ വിപുലമായ പരിസരത്തെ ഇത് കാണിക്കുന്നു. ഈ മോഡ്യൂൾ കാലാവസ്ഥയും താപനില സമ്പർക്കമുള്ള ഉപകരണങ്ങൾ പ്രദർശിപ്പിക്കുന്നു, പക്ഷേ ''@Tool'' പാറ്റേൺ ജാവ മെഥഡുകൾക്കായി നിത്യസാധ്യമാകുന്നു — ഡാറ്റാബേസ് ക്വെറിയിംഗിൽ നിന്ന് പേയ്മെന്റ് പ്രോസസ്സിംഗ് വരെ. -Tool Ecosystem +ഉപകരണങ്ങളുടെ പരിതസ്ഥിതി -*@Tool അടയാളപ്പെടുത്തിയ എല്ലാ ജാവാ മെഥഡുകളും AI-യ്ക്ക് ലഭ്യമാകും — മോഡൽ പാറ്റേൺ ഡേറ്റാബേസുകൾ, APIകൾ, ഇമെയിൽ, ഫയൽ ഓപ്പറേഷൻസ്, വളരെയധികം മേഖലകളിലേക്ക് വ്യാപിക്കുന്നു.* +*''@Tool'' എന്ന അനോട്ടേഷൻ ഉള്ള ജാവ മെഥഡുകൾ AI-യ്‌ക്ക് ലഭ്യമാകുന്നു — ഈ പാറ്റേൺ ഡാറ്റാബേസുകൾ, APIകൾ, ഇമെയിൽ, ഫയൽ പ്രവർത്തനങ്ങൾ മുതലായവയ്ക്കും വ്യാപിക്കുന്നു.* -## ടൂൾ അധിഷ്ഠിത ഏജന്റുകൾ ഉപയോഗിക്കേണ്ടപ്പോൾ +## ഉപകരണം അടിസ്ഥാനമായ ഏജന്റുകൾ എப்போது ഉപയോഗിക്കണമെന്ന് -എല്ലാ അഭ്യർത്ഥനകളും ടൂളുകൾ വേണ്ടതല്ല. നിർണ്ണയം AI മറ്റു ശൃംഖലകളുമായി സംവദിക്കാൻ ആവശ്യമാണോ അതോ തനിക്ക് ലഭ്യമായ അറിവിൽ നിന്നേ മറുപടി നല്‍കാമോ എന്നതിൽ ആണു. താഴെയുള്ള മാർഗ്ഗനിർദ്ദേശം ടൂളുകൾ ഉപയോഗിക്കുന്നത് വേഗം ആവശ്യമുള്ള ഡാറ്റ, കണക്കുകൾ, പ്രവർത്തനങ്ങൾക്കായി ഏറ്റവും ഗുണകരമാണെന്നും സാധാരണ അറിവിന് ടൂളുകൾ ആവശ്യമില്ലെന്നും പറയുന്നു: +എല്ലാ അഭ്യർത്ഥനക്കും ഉപകരണങ്ങൾ ആവശ്യമില്ല. തീരുമാനം AIക്ക് ബാഹ്യ സിസ്റ്റങ്ങൾ ഉപയോഗിക്കേണ്ടതുണ്ടോ അതോ അതിന്റെ സ്വന്തം ജ്ഞാനത്തിൽ നിന്നുമാണോ ഉത്തരം നൽകേണ്ടതെന്നതിൽ ആണ്. താഴെയുള്ള മാർഗ്ഗനിർദ്ദേശം ഉപകരണങ്ങൾ എന്തുചെയ്യുമ്പോൾ മൂല്യം കൂട്ടും, എന്തിൽ ആവശ്യമില്ല എന്നതിന്റെ സംഗ്രഹമാണ്: -When to Use Tools +ഉപകരണങ്ങൾ എപ്പോൾ ഉപയോഗിക്കണമെന്ന് -*ദ്രുത വിധി മാർഗ്ഗം — ടൂളുകൾ റിയൽ ടൈം ഡാറ്റ, കണക്കു ഗ്രഹണങ്ങൾ, പ്രവർത്തനങ്ങൾക്കായി ആണ്; പൊതുവായ അറിവും സൃഷ്ടിപരമായ പ്രവർത്തനങ്ങൾക്കും ആവശ്യമില്ല.* +*ഏറ്റവും പെട്ടെന്ന് തീരുമാനം - ഉപകരണങ്ങൾ സത്യകാല ഡാറ്റ, കണക്കുകൾ, പ്രവർത്തനങ്ങൾക്കായാണ്; പൊതുവായ ജ്ഞാനം, സൃഷ്ടിപരമായ ദൈനംദിന കാര്യങ്ങൾക്ക് വേണ്ടതല്ല.* -## ടൂളുകൾ vs RAG +## ഉപകരണങ്ങൾ vs RAG -മോഡ്യൂൾ 03, 04 ഇരண்டும் AI-യുടെ ശേഷി വർദ്ധിപ്പിക്കുന്നു, പക്ഷെ അടിസ്ഥാനപരമായ വ്യത്യസ്ത രീതിയിൽ. RAG മോഡലിന് **അറിയിപ്പ്** നൽകാൻ രേഖകൾ തിരയുന്നു. ടൂളുകൾ മോഡലിന് **പ്രവർത്തനങ്ങൾ** നടത്താൻ സൗകര്യം നൽകുന്നു. താഴെയുള്ള ചിത്രത്തിൽ ഈ രണ്ട് രീതികളുടെ പ്രവർത്തന രീതി, ആർക്കും കൊടുക്കുന്ന മേൽക്കോയ്മകൾ എന്നിവ താരതമ്യം ചെയ്തിരിക്കുന്നു: +മോഡ്യൂൾസ് 03, 04 രണ്ടും AI നൽകാനുള്ള കഴിവുകൾ വർദ്ധിപ്പിക്കുന്നു, എങ്കിലും അടിസ്ഥാനപരമായി വ്യത്യസ്ത മാർഗ്ഗത്തിലൂടെ. RAG മോഡലിന് **ജ്ഞാനം** നേടാൻ ഒരു സ്രോതസ്സ് നൽകുന്നു, അത് ഡോക്യുമെന്റുകൾ തിരയിയാണ്. ഉപകരണങ്ങൾ മോഡലിന് **പ്രവർത്തനങ്ങൾ** നടത്താൻ കഴിവ് നൽകുന്നു, ഫംഗ്ഷൻ വിളിക്കുന്നതിലൂടെ. താഴെയുള്ള ചിത്രത്തിൽ ഈ രണ്ട് ആശയങ്ങളെ തമ്മിൽ താരതമ്യം ചെയ്തിരിക്കുന്നു — ഓരോ പ്രവൃത്തിസംബന്ധിയായ പ്രവാഹം എങ്ങിനെയാണ് പ്രവർത്തിക്കുന്നത്, അവ തമ്മിലുള്ള ഇടപിശ്ചകളും: -Tools vs RAG Comparison +ഉപകരണങ്ങൾ vs RAG താരതമ്യം -*RAG സ്ഥിരം രേഖകളിൽ നിന്നും വിവരങ്ങൾ തിരഞ്ഞെടുക്കുന്നു — ടൂളുകൾ പ്രവർത്തനങ്ങൾ നടത്തുകയും गतിമയമായ, ന്റെ റിയൽ ടൈം ഡാറ്റ എല്ലാ സമയവും പകർന്നു നൽകുകയും ചെയ്യുന്നു. പല പ്രൊഡക്ഷൻ സിസ്റ്റങ്ങൾ ഇരട്ട രീതിയും ഒരുമിപ്പിച്ചിരിക്കുന്നു.* +*RAG സ്ഥിരമായ ഡോക്യുമെന്റുകളിൽനിന്നും വിവരങ്ങൾ നേടുന്നു — ഉപകരണങ്ങൾ പ്രവർത്തനങ്ങൾ നിർവഹിക്കുകയും സജീവ, യഥാർത്ഥകാല ഡാറ്റ കൈകാര്യം ചെയ്യുകയും ചെയ്യുന്നു. പല ഉത്‌പാദന സംവിധാനങ്ങളും ഈ രണ്ട് മാർഗ്ഗങ്ങൾ സംയോജിപ്പിക്കുന്നു.* -പ്രായോഗികമായി, പല പ്രൊഡക്ഷൻ സിസ്റ്റങ്ങളും ഇരട്ട രീതികൾ സംയോജിപ്പിക്കുന്നു: രേഖകളിൽ ഉത്തരം നിശ്ചയിക്കാൻ RAG, ജീവ ശരിയായ ഡാറ്റ എടുക്കാനും പ്രവർത്തനങ്ങൾ നടത്താനും ടൂളുകൾ. +പ്രായോഗികമായി, പല ഉൽപാദന സംവിധാനങ്ങളും രണ്ട് മാർഗ്ഗങ്ങളും ചേർന്ന് ഉപയോഗിക്കുന്നു: RAG നിങ്ങളുടെ ഡോക്യുമെന്റേഷനിൽ ഉത്തരങ്ങൾ ആസ്പദമാക്കാൻ, ഉപകരണങ്ങൾ സജീവ ഡാറ്റ പകർക്കുന്നല്ലാതെ പ്രവർത്തനങ്ങൾ നടത്താൻ. -## ഇനി ചെയ്യേണ്ടത് +## അടുത്ത പടികൾ -**അടുത്ത മോഡ്യൂൾ:** [05-mcp - മോഡൽ കോൺടെക്സ്റ്റ് പ്രോട്ടോക്കോൾ (MCP)](../05-mcp/README.md) +**അടുത്ത മോഡ്യൂൾ:** [05-mcp - മോഡൽ കോൺടക്സ്റ്റ് പ്രോട്ടോക്കോൾ (MCP)](../05-mcp/README.md) --- -**നാവിഗേഷൻ:** [← മുമ്പത്തെ: മോഡ്യൂൾ 03 - RAG](../03-rag/README.md) | [മെയിനിലേക്ക് മടങ്ങുക](../README.md) | [അടുത്തത്: മോഡ്യൂൾ 05 - MCP →](../05-mcp/README.md) +**നാവിഗേഷൻ:** [← മുൻപത്തെ: മോഡ്യൂൾ 03 - RAG](../03-rag/README.md) | [പ്രധാനത്തിലേക്ക് മടങ്ങുക](../README.md) | [അടുത്തത്: മോഡ്യൂൾ 05 - MCP →](../05-mcp/README.md) --- -**അസൂയാപത്രം**: -ഈ പ്രമാണം എ.ഐ. വിവർത്തന സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് വിവർത്തനം ചെയ്തതാണ്. നാം ശരിയായതാകാൻ പരിശ്രമിക്കുന്നുവെങ്കിലും, ഓട്ടോമേറ്റഡ് വിവർത്തനങ്ങളിൽ പിഴവുകൾ അല്ലെങ്കിൽ തെറ്റുകൾ ഉണ്ടാകാമെന്ന് ദയവായി മനസിലാക്കുക. പ്രാമാണിക ഉറവിടമായി മൊത്തത്തിലുള്ള പ്രമാണത്തിന്റെ നിധാനഭാഷ പരിഗണിക്കണമെന്ന് ശുപാർശ ചെയ്യുന്നു. അത്യാവശ്യ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മാനവ വിവർത്തനം നിർദ്ദേശിക്കുന്നതാണ്. ഈ വിവർത്തന ഉപയോഗത്തിൽ നിന്നുണ്ടാകാവുന്ന യാതൊരു ഗന്ധാഭാഷം അല്ലെങ്കിൽ തെറ്റിദ്ധാരണകൾക്കെതിരെ ഞങ്ങൾ ഉത്തരവാദിത്വം ഏറ്റടുക്കുന്നില്ല. +**അറിയിപ്പ്**: +ഈ രേഖ AI പരിഭാഷാ സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് പരിഭാഷപ്പെടുത്തിയതാണ്. ഞങ്ങൾ കൃത്യതയ്ക്കായി ശ്രമിക്കുന്നുവെങ്കിലും, ഓട്ടോമേറ്റഡ് പരിഭാഷകളിൽ പിഴവുകൾ അല്ലെങ്കിൽ തെറ്റായ വിവരങ്ങൾ ഉണ്ടാകാൻ സാധ്യതയുണ്ട്. അതിന്റെ സ്വാഭാവിക ഭാഷയിലുള്ള അസൽ രേഖയാണ് പ്രാമാണികമായ ഉറവിടമായി പരിഗണിക്കേണ്ടത്. നിർണായകമായ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ പരിഭാഷ ശുപാർശ ചെയ്യുന്നു. ഈ പരിഭാഷ ഉപയോഗിച്ച് ഉണ്ടാകുന്ന തെറ്റിദ്ധാരണകൾ അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾക്കായി ഞങ്ങൾ ഉത്തരവാദികളല്ല. \ No newline at end of file diff --git a/translations/ml/README.md b/translations/ml/README.md index 55fe012c0..b7690fc60 100644 --- a/translations/ml/README.md +++ b/translations/ml/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j ന്യൂബീസിനായി +# LangChain4j വേണ്ടി തുടക്കക്കാർക്ക് -മൂലീകരണ ചാറ്റിൽ നിന്ന് AI ഏജന്റുകളിലേക്കുള്ള LangChain4j ഉം Azure OpenAI GPT-5.2 ഉം ഉപയോഗിച്ച് AI അപ്ലിക്കേഷനുകൾ നിർമ്മിക്കാൻ ഒരു കോഴ്‌സ്. +LangChain4j കൂടാതെ Azure OpenAI GPT-5.2 ഉപയോഗിച്ച് എഐ ആപ്ലിക്കേഷനുകൾ നിർമ്മിക്കുന്ന കോഴ്സ്, അടിസ്ഥാന സംവാദത്തിൽ നിന്ന് എഐ ഏജൻറുകൾ വരെ. ### 🌐 ബഹുഭാഷാ പിന്തുണ -#### GitHub പ്രവർത്തനത്താൽ (സ്വയം ക്രമീകരിക്കപ്പെടുന്നും എപ്പോഴും പുതുക്കപ്പെടുന്നതും) പിന്തുണയ്ക്കുന്നു +#### GitHub Action വഴി പിന്തുണ (സ്വയംപ്രവർത്തിക്കുന്നതും എപ്പൊഴും പുതുക്കപ്പെട്ടതും) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](./README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **പ്രാദേശികമായി കോഡ് ക്ലോൺ ചെയ്യാനാഗ്രഹമുണ്ടോ?** +> **പ്രാദേശികമായി ക്ലോൺ ചെയ്യാൻ ഇഷ്ടപ്പെടുന്നുവോ?** > -> ഈ റെപ്പോസിറ്ററിയിൽ 50-ത്തിലധികം ഭാഷാ വിവർത്തനങ്ങൾ ഉൾക്കൊള്ളുന്നു, ഇത് ഡൗൺലോഡ് വലിപ്പം വലിയവുമാക്കുന്നു. വിവർത്തനങ്ങൾ ഇല്ലാതെ ക്ലോൺ ചെയ്യാൻ sparse checkout ഉപയോഗിക്കുക: +> ഈ റിപോസിറ്ററിൽ 50-ലധികം ഭാഷാ വിവർത്തനങ്ങൾ ഉൾപ്പെടുന്നു, ഇത് ഡൗൺലോഡ് വലുപ്പം വളരെ വലുതാക്കുന്നു. വിവർത്തനങ്ങൾ ഇല്ലാതെ ക്ലോൺ ചെയ്യാൻ sparse checkout ഉപയോഗിക്കുക: > > **Bash / macOS / Linux:** > ```bash @@ -29,64 +29,63 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> ഇതുവഴി നിങ്ങൾക്ക് കോഴ്‌സ് പൂര്‍ത്തിയാക്കുന്നതിന് ആവശ്യമായ എല്ലാ കാര്യങ്ങളും വളരെ വേഗത്തിൽ ഡൗൺലോഡ് ചെയ്യാം. +> കോഴ്സ് പൂർത്തിയാക്കാൻ ആവശ്യമുള്ള മുഴുവൻ ഫയലുകളും വളരെ വേഗത്തിൽ ഡൗൺലോഡ് ചെയ്യാൻ ഇത് സഹായിക്കും. -## ഉള്ളടക്കങ്ങളുടെ പട്ടിക +## ഉള്ളടക്ക പട്ടിക -1. [ഷീഘ്രം ആരംഭിക്കുക](00-quick-start/README.md) - LangChain4j ഉപയോഗിച്ച് ആരംഭിക്കുക -2. [പരിചയം](01-introduction/README.md) - LangChain4j യുടെ അടിസ്ഥാനങ്ങൾ പഠിക്കുക -3. [പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ്](02-prompt-engineering/README.md) - ഫലപ്രദമായ പ്രോംപ്റ്റ് രൂപകൽപ്പനയിൽ നിപുണത നേടുക -4. [RAG (റീട്രിവൽ-ഓഗ്മെന്റഡ് ജനറേഷൻ)](03-rag/README.md) - ബുദ്ധിമുട്ടുള്ള വിജ്ഞാന അധിഷ്ഠിത സിസ്റ്റങ്ങൾ നിർമ്മിക്കുക -5. [ടൂളുകൾ](04-tools/README.md) - ബാഹ്യ ഉപകരണങ്ങൾക്കും ലളിത സഹായി സംവിധാനങ്ങൾക്കും സംയോജിപ്പിക്കുക -6. [MCP (മോഡൽ കോൺടെക്സ്റ്റ് പ്രോട്ടോക്കോൾ)](05-mcp/README.md) - മോഡൽ കോൺടെക്സ്റ്റ് പ്രോട്ടോക്കോൾ (MCP) ഉം ഏജന്റിക് മൊഡ്യൂളുകളും ഉപയോഗിക്കുക +1. [ആമുഖം](01-introduction/README.md) - LangChain4j അടിസ്ഥാനങ്ങളെ പഠിക്കുക +2. [പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ്](02-prompt-engineering/README.md) - ഫലപ്രദമായ പ്രോംപ്റ്റ് ഡിസൈൻ അറിഞ്ഞെടുക്കുക +3. [RAG (റിട്രീവൽ-ഓഗ്മെന്റഡ് ജനറേഷൻ)](03-rag/README.md) - ബുദ്ധിമുട്ടുള്ള ജ്ഞാന അധിഷ്ഠിത സിസ്റ്റങ്ങൾ നിർമ്മിക്കുക +4. [ഉപകരണങ്ങൾ](04-tools/README.md) - ബാഹ്യ ഉപകരണങ്ങളും ലളിതമായ സഹായികളും സംയോജിപ്പിക്കുക +5. [MCP (മോഡൽ കോൺടെക്സ്റ്റ് പ്രോട്ടോക്കോൾ)](05-mcp/README.md) - മോഡൽ കോൺടെക്സ്റ്റ് പ്രോട്ടോക്കോൾ (MCP) ഉം ഏജന്റിക് മോഡ്യൂളുകളും ഉപയോഗിക്കുക -### വീഡിയോ മാർഗ്ഗനിർദ്ദേശങ്ങൾ +### വീഡിയോ അവലോകനങ്ങൾ -ഒരൊറ്റ മോട്യൂളിനും ലൈവ് സെഷൻ കൂടെ ഉണ്ട്, വളരെ വിശദമായി ആശയങ്ങളെയും കോഡിനെയും നാം പുറകോട്ട് ഉൾക്കാഴ്ച നടത്തുന്നു. +ഓരോ മോഡ്യൂളിനും അനുബന്ധമായുള്ള ലൈവ് സെഷൻ ഉണ്ട്, അവിടെ ആശയങ്ങളും കോഡും ഘട്ടം ഘട്ടമായി വിശദീകരിക്കുന്നു. -| മോട്യൂൾ | വീഡിയോ | +| മോഡ്യൂൾ | വീഡിയോ | |--------|-------| -| 01 - പരിചയം | [LangChain4j ഉപയോഗിച്ച് സ്റ്റാർട്ട് ചെയ്യുന്നു](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ് | [LangChain4j ഉള്ള പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ്](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [LangChain4j ഒപ്പം RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - ടൂളുകളും 05 - MCP | [ടൂളുകളും MCP ഉം ഉള്ള AI ഏജന്റുകൾ](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 01 - ആമുഖം | [LangChain4j ഉപയോഗിച്ച് ആരംഭിക്കൽ](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ് | [LangChain4j ഉപയോഗിച്ച് പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ്](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [LangChain4j ഉപയോഗിച്ച് RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 04 - ഉപകരണങ്ങൾ & 05 - MCP | [ഉപകരണങ്ങളും MCP യും ഉപയോഗിച്ചുള്ള AI ഏജന്റുകൾ](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## പഠന പാത +## പഠന വഴികാട്ടി -**LangChain4j പ്രാരംഭങ്ങളോ?** പ്രധാന തുടങ്ങിയ പദങ്ങളും ആശയങ്ങളും മനസിലാക്കാൻ [Glossary](docs/GLOSSARY.md) കാണുക. +**LangChain4j-ലേക്ക് പുതിയവർ?** പ്രധാന മുദ്രാവാക്യങ്ങളും ആശയങ്ങൾക്കും വേണ്ടി [Glossary](docs/GLOSSARY.md) കാണുക. -> **ഷീഘ്രം ആരംഭിക്കുക** +> **വേഗം ആരംഭിക്കുക** -1. ഈ റെപ്പോസിറിയി നിങ്ങളുടെ GitHub അക്കൗണ്ടിലേക്കു ഫോർക്കുചെയ്യുക -2. **Code** → **Codespaces** ടാബ് → **...** → **New with options...** ക്ലിക് ചെയ്യുക -3. ഡിഫോൾട്ട് സജ്ജീകരണങ്ങൾ ഉപയോഗിക്കുക – ഇത് ഈ കോഴ്‌സിനായി സജ്ജീകരിച്ച ഡെവലപ്പ്മെന്റ് കോൺടെയ്നർ തിരഞ്ഞെടുക്കും +1. ഈ റിപോസിറ്ററി നിങ്ങളുടെ GitHub അക്കൗണ്ടിലേക്ക് ഫോർക്കുചെയ്യുക +2. **Code** → **Codespaces** ടാബ് → **...** → **New with options...** ക്ലിക്കുചെയ്യുക +3. ഡിഫാൾട്ടുകൾ ഉപയോഗിക്കുക – കോഴ്സിനായി സൃഷ്ടിച്ച ഡവലപ്പ്മെന്റ് കൺറ്റെയ്‌നർ ഇതിലുള്ളതാണ് തിരഞ്ഞെടുക്കുന്നത് 4. **Create codespace** ക്ലിക്ക് ചെയ്യുക -5. പരിസ്ഥിതി സജ്ജമാകാൻ 5-10 മിനിറ്റ് കാത്തിരിക്കുക -6. ആരംഭിക്കാൻ [ഷീഘ്രം ആരംഭിക്കുക](./00-quick-start/README.md) കാണുക! +5. പരിസ്ഥിതി സജ്ജമാകാൻ 5-10 മിനിട്ടു കാത്തിരിക്കുക +6. ആരംഭിക്കാൻ വേണ്ടി നേരിട്ട് [ആമുഖം](./01-introduction/README.md) സന്ദർശിക്കുക! -മോട്യൂളുകൾ പൂർത്തിയാക്കിയ ശേഷം, LangChain4j ടസ്റ്റിങ് ആശയങ്ങൾ പ്രയോഗത്തിൽ കാണാൻ [Testing Guide](docs/TESTING.md) പരീക്ഷിക്കൂ. +മൊഡ്യൂളുകൾ പൂർത്തിയാക്കിയ ശേഷം, LangChain4j ടെസ്റ്റിംഗ് ആശയങ്ങൾ പ്രയോഗത്തിൽ കാണാൻ [ടസ്റ്റിംഗ് ഗൈഡ്](docs/TESTING.md) പഠിക്കുക. -> **കുറിപ്പ്:** ഈ പരിശീലനം GitHub മോഡലുകളും Azure OpenAI ഉം കൂട്ടിച്ച് ഉപയോഗിക്കുന്നു. [ഷീഘ്രം ആരംഭിക്കുക](00-quick-start/README.md) മോട്യൂളിൽ GitHub മോഡലുകൾ (Azure സബ്സ്ക്രിപ്ഷൻ ആവശ്യമില്ല) ആണ് ഉപയോഗിക്കുന്നത്, മോട്യൂളുകൾ 1-5 Azure OpenAI ഉപയോഗിക്കുന്നു. നിങ്ങൾക്ക് ഇല്ലെങ്കിൽ [നിയമിത Azure അക്കൗണ്ട്](https://aka.ms/azure-free-account) ഉപയോഗിച്ച് ആരംഭിക്കുക. +> **ഗൗരവമായി:** ഈ പരിശീലനം Azure OpenAI ഉപയോഗിക്കുന്നു. നിങ്ങൾക്കോ ഒരു അക്കൗണ്ട് ഇല്ലെങ്കിൽ [FREE Azure account](https://aka.ms/azure-free-account) ഉപയോഗിച്ച് തുടങ്ങിയോളൂ. ## GitHub Copilot ഉപയോഗിച്ച് പഠനം -ദ്രുതമായി കോഡിംഗ് തുടങ്ങാൻ, ഈ പ്രോജക്ട് GitHub Codespace ൽ അല്ലെങ്കിൽ നൽകിയ ഡെവ്‌കോൺടെയ്നർ ഉപയോഗിച്ച് നിങ്ങളുടെ ലോക്കൽ IDE യിൽ തുറക്കുക. ഈ കോഴ്‌സിലെ ഡെവ്‌കോൺടെയ്നർ GitHub Copilot ഉപയോഗിച്ച് AI കൂട്ടുപ്രോഗ്രാമിംഗിന് മുൻകൂട്ടി ക്രമീകരിച്ചിരിക്കുന്നതാണ്. +വേഗത്തിൽ കോഡുചെയ്യാൻ, ഈ പ്രോജക്ട് GitHub Codespace-ൽ അല്ലെങ്കിൽ നൽകപ്പെട്ട devcontainer ഉള്ള നിങ്ങളുടെ പ്രാദേശിക IDE-യിൽ തുറക്കുക. ഈ കോഴ്സിൽ ഉപയോഗിച്ച devcontainer GitHub Copilot AI കൂട്ടായ്മ പ്രോഗ്രാമിംഗിന് മുൻകൂർ ക്രമീകരിച്ചിരിക്കുന്നു. -ഓരോ കോഡ് ഉദാഹരണത്തിലും GitHub Copilot യിൽ ചോദിക്കാവുന്ന നിർദ്ദേശങ്ങൾക്ക് ചോദ്യങ്ങളും ഉൾപ്പെട്ടിരിക്കുന്നു, അത് നിങ്ങളുടെ മനസ്സിലാക്കലിനെ അടിതെറിക്കാൻ സഹായിക്കും. 💡/🤖 പ്രോംപ്റ്റുകൾ താഴെ കണ്ടു: +ഓരോ കോഡ് ഉദാഹരണത്തിലും GitHub Copilot-നോട് ചോദിക്കാവുന്ന നിർദ്ദേശിച്ച ചോദ്യങ്ങൾ ഉൾപ്പെടുത്തിയിട്ടുണ്ട്, നിങ്ങളുടെ ബോധം ഇതിലൂടെ കൂടുതൽ ശക്തമാക്കാം.💡/🤖 പ്രോമ്പ്റ്റുകൾ കാണാം: -- **ജാവാ ഫയൽ ഹെഡറുകൾ** - ഓരോ ഉദാഹരണത്തിന്റെയും പ്രത്യേക ചോദ്യങ്ങൾ -- **മൊഡ്യൂൾ READMEs** - കോഡ് ഉദാഹരണങ്ങളുടെയുശേഷം പരീക്ഷണ ചോദ്യങ്ങൾ +- **ജാവ ഫയൽ ഹെഡറുകളിൽ** – ഓരോ ഉദാഹരണത്തിനു പറ്റിയ ചോദ്യങ്ങൾ +- **മോഡ്യൂൾ README-കളിൽ** – കോഡ് ഉദാഹരണങ്ങൾക്കു ശേഷം പരസ്യ ചോദ്യങ്ങൾ -**ഉപയോഗวิതി:** ഏതെങ്കിലും കോഡ് ഫയൽ തുറന്ന് Copilot നു നിർദ്ദേശിച്ച ചോദ്യങ്ങൾ ചോദിക്കുക. കോഡ്ബേസ് യഥോചിതമായി മനസ്സിലാക്കാൻ കഴിയും, വിശദീകരിക്കുകയും, വിപുലീകരിക്കുകയും, ബദൽ നിർദ്ദേശങ്ങൾ നൽകുകയും ചെയ്യുന്നു. +**ഉപയോഗം എങ്ങനെ:** ഏതെങ്കിലും കോഡ് ഫയൽ തുറന്ന് നിർദ്ദേശിച്ച ചോദ്യങ്ങൾ Copilot-നോട് ചോദിക്കുക. ഇത് കോഡ് പൂർണ്ണമായി മനസ്സിലാകുന്നുണ്ട്, വിശദീകരിക്കുകയും, വിപുലമാക്കുകയും, മറ്റ് മാർഗ്ഗങ്ങൾ നിർദ്ദേശിക്കുകയും ചെയ്യും. -കൂടുതൽ അറിയാൻ താൽപര്യമുണ്ടോ? [GitHub Copilot AI കൂട്ടുപ്രോഗ്രാമിംഗിനായി](https://aka.ms/GitHubCopilotAI) കാണുക. +കൂടുതൽ അറിയാൻ [Copilot for AI Paired Programming](https://aka.ms/GitHubCopilotAI) സന്ദർശിക്കുക. -## അധിക സ്രോതസ്സ് +## അധികം അക്കൗണ്ടുകൾ ### LangChain @@ -111,40 +110,41 @@ --- -### കോർ ലേണിംഗ് +### കോർ പഠനം [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![സൈബർസെക്യൂരിറ്റി ഫോർ ബേഗിൻസേഴ്സ്](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![വേബ് ഡെവ് ഫോർ ബേഗിൻസേഴ്സ്](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![ഐഒടി ഫോർ ബേഗിൻസേഴ്സ്](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![എക്സ്‌ആർ ഡെവലപ്പ്മെന്റ് ഫോർ ബേഗിൻസേഴ്സ്](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) ---- +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +--- + ### കോപൈലറ്റ് പരമ്പര -[![എഐ കൂട്ടായ പ്രോഗ്രാമിങ്ങിനുള്ള കോപൈലറ്റ്](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET നുള്ള കോപൈലറ്റ്](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![കോപൈലറ്റ് അഡ്വഞ്ചർ](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## സഹായം നേടൽ -നിങ്ങൾ കുടുങ്ങുകയുണ്ടെങ്കിൽ അല്ലെങ്കിൽ എഐ ആപ്ലിക്കേഷനുകൾ നിർമ്മിക്കുമ്പോൾ ഏതെങ്കിലും ചോദ്യം ഉണ്ടെങ്കിൽ ചേരുക: +നിങ്ങൾ കുടുങ്ങിയാൽ അല്ലെങ്കിൽ AI ആപ്ലിക്കേഷനുകൾ നിർമ്മിക്കുന്നതിനെക്കുറിച്ച് ഏതെങ്കിലും ചോദ്യങ്ങൾ ഉണ്ടെങ്കിൽ, ചേരുക: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -ഉൽപ്പന്ന പ്രതികരണങ്ങൾ ഉണ്ടെങ്കിൽ അല്ലെങ്കിൽ നിർമ്മാണത്തിൽ പിഴവുകൾ ഉണ്ടെങ്കിൽ സന്ദർശിക്കുക: +നിങ്ങൾക്ക് ഉൽപ്പന്നമായുള്ള ഫീഡ്‌ബാക്ക് അല്ലെങ്കിൽ നിർമ്മാണത്തിൽ പിഴവുകൾ ഉണ്ടായാൽ സന്ദർശിക്കുക: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## ലൈസൻസ് -MIT ലൈസൻസ് - വിശദാംശങ്ങൾക്ക് [LICENSE](../../LICENSE) ഫയൽ കാണുക. +MIT ലൈസൻസ് - വിശദാംശങ്ങൾക്കായി [LICENSE](../../LICENSE) ഫയൽ കാണുക. --- -**പ്രതിജ്ഞ**: -ഈ പ്രമാണം AI പരിഭാഷാ സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് പരിഭാഷ ചെയ്തതാണ്. ഞങ്ങൾ കൃത്യതയ്ക്ക് ശ്രമിക്കുന്നതെങ്കിൽ, യാന്ത്രിക പരിഭാഷകൾ പിശകുകൾ അല്ലെങ്കിൽ അകാരണതകൾ ഉള്ളതായിരിക്കാമെന്നും ദയവായി ശ്രദ്ധിക്കുക. നിദ്ധീഷ്ട ഭാഷയിലെ യഥാർത്ഥ പ്രമാണം അതിന്റെ നിയമാനുസൃത ഉറവിടമായി പരിഗണിക്കപ്പെടണം. നിർണായക വിവരങ്ങൾക്ക്, വ്യവസായിക മനുഷ്യ പരിഭാഷ നിർദ്ദേശിക്കപ്പെടുന്നു. ഈ പരിഭാഷ ഉപയോഗിക്കുന്നതിൽ നിന്നുള്ള അസമജ്യം അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾക്ക് ഞങ്ങൾക്ക് ഉത്തരവാദിത്വം ഉണ്ടാകുന്നില്ല. +**അറിയിപ്പ്**: +ഈ രേഖ AI പരിഭാഷാ സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് പരിഭാഷപ്പെടുത്തിയതാണ്. ഞങ്ങൾ കൃത്യതയ്ക്കായി ശ്രമിക്കുന്നുവെങ്കിലും, ഓട്ടോമേറ്റഡ് പരിഭാഷകളിൽ പിഴവുകൾ അല്ലെങ്കിൽ തെറ്റായ വിവരങ്ങൾ ഉണ്ടാകാൻ സാധ്യതയുണ്ട്. അതിന്റെ സ്വാഭാവിക ഭാഷയിലുള്ള അസൽ രേഖയാണ് പ്രാമാണികമായ ഉറവിടമായി പരിഗണിക്കേണ്ടത്. നിർണായകമായ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ പരിഭാഷ ശുപാർശ ചെയ്യുന്നു. ഈ പരിഭാഷ ഉപയോഗിച്ച് ഉണ്ടാകുന്ന തെറ്റിദ്ധാരണകൾ അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾക്കായി ഞങ്ങൾ ഉത്തരവാദികളല്ല. \ No newline at end of file diff --git a/translations/ml/docs/GLOSSARY.md b/translations/ml/docs/GLOSSARY.md index 01a320d8d..64eb58ef6 100644 --- a/translations/ml/docs/GLOSSARY.md +++ b/translations/ml/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j ഗ്ലോസ്‌റിയ +# LangChain4j നിഘണ്ടു ## ഉള്ളടക്ക പട്ടിക -- [മുൻ കാര്യങ്ങൾ](../../../docs) -- [LangChain4j ഘടകങ്ങൾ](../../../docs) -- [AI/ML ആശയങ്ങൾ](../../../docs) -- [ഗാർഡ്റെയിൽസ്](../../../docs) -- [പ്രോംപ്റ്റ് എഞ്ചിനിയറിംഗ്](../../../docs) -- [RAG (റിട്രീവൽ-ഓഗ്മെന്റഡ് ജനറേഷൻ)](../../../docs) -- [എജന്റുകളും ടൂളുകളും](../../../docs) -- [എജന്റിക് മോഡ്യൂൾ](../../../docs) -- [മോഡല_Context_പ്രോട്ടോക്കോൾ (MCP)](../../../docs) -- [അസ്യൂർ സേവനങ്ങൾ](../../../docs) -- [പരീക്ഷണവും വികസനവും](../../../docs) +- [കോർ ആശയങ്ങൾ](#കോർ-ആശയങ്ങൾ) +- [LangChain4j ഘടകങ്ങൾ](#langchain4j-ഘടകങ്ങൾ) +- [AI/ML ആശയങ്ങൾ](#aiml-ആശയങ്ങൾ) +- [ഗാർഡ്രെയ്ൽസ്](#guardrails) +- [പ്രോംപ്‌റ് എഞ്ചിനീയറിംഗ്](#prompt-engineering---module-02) +- [RAG (റിട്രീവൽ-ഓഗ്മെന്റഡ് ജനറേഷൻ)](#rag-retrieval-augmented-generation---module-03) +- [ഏജന്റുകളും ഉപകരണങ്ങളും](#agents-and-tools---module-04) +- [ഏജന്റിക് മഡ്യൂൾ](#agentic-module---module-05) +- [മോഡൽ കോൺടെക്സ്‌റ്റ് പ്രോട്ടോക്കോൾ (MCP)](#model-context-protocol-mcp---module-05) +- [ആസ്യൂർ സേവനങ്ങൾ](#azure-services---module-01) +- [ടെസ്റ്റിംഗ് ആൻഡ് ഡെവലപ്പ്മെന്റ്](#testing-and-development---testing-guide) -പാഠ്യക്കൂടарെ വ്യാപിച്ച് ഉപയോഗിക്കുന്ന പദങ്ങളും ആശയങ്ങളും വേഗത്തിൽ പരിശോധിക്കാൻ. +പാഠ കോഴ്സിലുടനീളം ഉപയോഗിക്കുന്ന പദങ്ങളും ആശയങ്ങളും വേഗത്തിൽ റഫറൻസ് ചെയ്യുന്നതിനുള്ളതാണ്. -## മുൻ കാര്യങ്ങൾ +## കോർ ആശയങ്ങൾ -**AI Agent** - സ്വയം പരിഗണിക്കുകയും പ്രവർത്തിക്കുകയും ചെയ്യുന്ന AI-ഉപയോഗിക്കുന്ന സംവിധാനം. [മോഡ്യൂൾ 04](../04-tools/README.md) +**AI ഏജന്റ്** - സ്വയംകാരിത്വത്തോടെ തർക്കവും പ്രവർത്തനവും നടത്താൻ AI ഉപയോഗിക്കുന്ന സംവിധാനം. [മഡ്യൂൾ 04](../04-tools/README.md) -**Chain** - ഔട്ട്പുട്ട് അടുത്ത ഘട്ടത്തിലേക്ക് നൽകുന്ന നടപടികളുടെ ഘട്ടം. +**ചെയിൻ** - പുറപ്പ് അടുത്ത ഘട്ടത്തിലേക്ക് ഫീഡ് ചെയ്യുന്ന പ്രവർത്തനങ്ങളുടെ നിര. -**Chunking** - രേഖകൾ ചെറുതായി വിഭജിക്കൽ. സാധാരണ: 300-500 ടോകൺസ് ഓവർലാപ്പോടെ. [മോഡ്യൂൾ 03](../03-rag/README.md) +**Chunking** - ഡോക്യുമെന്റുകൾ ചെറുതായി വിഭജിക്കൽ. സാധാരണ: 300-500 ടോക്കണുകൾ ഒവർലാപ് സഹിതം. [മഡ്യൂൾ 03](../03-rag/README.md) -**Context Window** - ഒരു മോഡൽ പ്രോസസ് ചെയ്യാവുന്ന പരമാവധി ടോകൺസ്. GPT-5.2: 400K ടോകൺസ് (272K ഇൻപുട്ട് വരെ, 128K ഔട്ട്പുട്ട്). +**Context Window** - ഒരേസമയം ഒരു മോഡൽ പ്രോസസ്സ് ചെയ്യാവുന്ന പരമാവധി ടോക്കണുകൾ. GPT-5.2: 400K ടോക്കണുകൾ (272K ഇൻപുട്ട് വരെ, 128K ഔട്ട്പുട്ട്). -**Embeddings** - ടെക്സ്റ്റിന്റെ അർത്ഥം പ്രതിനിധാനം ചെയ്യുന്ന അക്കസംഖ്യാ വെക്ടറുകൾ. [മോഡ്യൂൾ 03](../03-rag/README.md) +**Embeddings** - ടെക്സ്റ്റിന്റെ അർത്ഥം പ്രതിനിധീകരിക്കുന്ന സംഖ്യാ ഭായകങ്ങളും. [മഡ്യൂൾ 03](../03-rag/README.md) -**Function Calling** - മോഡൽ ഘടിതമായ അഭ്യർത്ഥനകൾ സൃഷ്ടിച്ച് പുറംഫംഗ്ഷനുകൾ വിളിക്കുന്നു. [മോഡ്യൂൾ 04](../04-tools/README.md) +**Function Calling** - മോഡൽ ഘടനാപരമായ അഭ്യർത്ഥനകൾ സൃഷ്ടിച്ച് ബാഹ്യ ഫങ്ഷനുകൾ വിളിക്കുന്നു. [മഡ്യൂൾ 04](../04-tools/README.md) -**Hallucination** - മോഡലുകൾ തെറ്റായെങ്കിലും സാധാരണമെന്നു തോന്നുന്ന വിവരങ്ങൾ സൃഷ്ടിക്കുമ്പോൾ. +**Hallucination** - മോഡലുകൾ തെറ്റായെങ്കിലും വിശ്വസനീയമായ വിവരങ്ങൾ ഉദ്ഭവിപ്പിക്കുമ്പോൾ. -**Prompt** - ഭാഷാ മോഡലിലേക്ക് പാരായണാനുബന്ധമായ ടെക്സ്റ്റ്. [മോഡ്യൂൾ 02](../02-prompt-engineering/README.md) +**Prompt** - ഭാഷാ മോഡലിലേക്ക് നൽകിയ ടെക്സ്റ്റ് ഇൻപുട്ട്. [മഡ്യൂൾ 02](../02-prompt-engineering/README.md) -**Semantic Search** - കീവർഡുകൾക്കുപകരം embeddings ഉപയോഗിച്ച് അർത്ഥം അടിസ്ഥാനമാക്കി തിരയൽ. [മോഡ്യൂൾ 03](../03-rag/README.md) +**Semantic Search** - കീーワードുകൾക്കുപകരം എൻബെഡിംഗുകൾ ഉപയോഗിച്ച് അർത്ഥം വഴിയുള്ള തിരയൽ. [മഡ്യൂൾ 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: ഓർമയില്ല. Stateful: സംഭാഷണ ചരിത്രം നിലനിൽക്കുന്നു. [മോഡ്യൂൾ 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: ഓർമ്മശേഷി ഇല്ലാത്തത്. Stateful: സംഭാഷണ ചരിത്രം നിലനിർത്തുന്നത്. [മഡ്യൂൾ 01](../01-introduction/README.md) -**Tokens** - മോഡലുകൾ പ്രോസസ് ചെയ്യുന്ന അടിസ്ഥാന ടെക്സ്റ് യൂണിറ്റുകൾ. ചിലവുകളും പരിധികളും ബാധിക്കുന്നു. [മോഡ്യൂൾ 01](../01-introduction/README.md) +**Tokens** - മോഡലുകൾ പ്രോസസ്സ് ചെയ്യുന്ന അടിസ്ഥാന ടെക്സ്റ്റ് ഘടകങ്ങൾ. ചെലവും പരിധികളും ബാധിക്കുന്നു. [മഡ്യൂൾ 01](../01-introduction/README.md) -**Tool Chaining** - ഔട്ട്പുട്ട് അടുത്ത ടൂളിന്റെ ഉപയോഗം നിർണയിക്കുന്ന അനുക്രമ ടൂൾ പ്രവർത്തനം. [മോഡ്യൂൾ 04](../04-tools/README.md) +**Tool Chaining** - ഔട്ട്പുട്ട് അടുത്ത വിളിക്ക് വിവരം നൽകുന്ന തുടര്‍ന്നുള്ള ഉപകരണങ്ങൾ പ്രയോഗിക്കൽ. [മഡ്യൂൾ 04](../04-tools/README.md) ## LangChain4j ഘടകങ്ങൾ -**AiServices** - ടൈപ്പിന്റെ സുരക്ഷയുള്ള AI സേർവീസ് ഇന്റർഫേസുകൾ സൃഷ്ടിക്കുന്നു. +**AiServices** - ടൈപ്പ്-സേഫ് AI സേവന ഇന്റർഫേസുകൾ സൃഷ്ടിക്കുന്നു. -**OpenAiOfficialChatModel** - OpenAIയും Azure OpenAIയും മോഡലുകൾക്കുള്ള ഐക്യക്ലയന്റ്. +**OpenAiOfficialChatModel** - OpenAI, Azure OpenAI മോഡലുകൾക്കുള്ള ഐക്യക്ലയന്റ്. -**OpenAiOfficialEmbeddingModel** - OpenAI ഔദ്യോഗിക ക്ലയന്റ് ഉപയോഗിച്ച് embeddings സൃഷ്ടിക്കുന്നു (OpenAIയും Azure OpenAIയും പിന്തുണയുള്ളത്). +**OpenAiOfficialEmbeddingModel** - OpenAI ഔദ്യോഗിക ക്ലയന്റ് ഉപയോഗിച്ച് എൻബെഡിംഗുകൾ സൃഷ്ടിക്കുന്നു (OpenAI, Azure OpenAI സൗകര്യങ്ങൾ പിന്തുണയ്ക്കുന്നു). -**ChatModel** - ഭാഷാ മോഡലുകളുടെ പ്രധാനം ഇന്റർഫേസ്. +**ChatModel** - ഭാഷാ മോഡലുകൾക്കുള്ള പ്രാഥമിക ഇന്റർഫേസ്. -**ChatMemory** - സംഭാഷണ ചരിത്രം സൂക്ഷിക്കുന്നു. +**ChatMemory** - സംഭാഷണ ചരിത്രം നിലനിർത്തുന്നു. -**ContentRetriever** - RAG-ക്കായി അനുയോജ്യമായ രേഖചങ്കുകൾ കണ്ടെത്തുന്നു. +**ContentRetriever** - RAG നിമിത്തം പ്രസക്തമായ ഡോക്യുമെന്റ് ചങ്കുകൾ കണ്ടെത്തുന്നു. -**DocumentSplitter** - രേഖകൾ ചങ്കുകളായി വിഭജിക്കുന്നു. +**DocumentSplitter** - ഡോക്യുമെന്റുകൾ ചങ്കുകളായി വിഭജിക്കുന്നു. -**EmbeddingModel** - ടെക്സ്റ്റ് അക്കസംഖ്യാ വെക്ടറുകളാക്കി മാറ്റുന്നു. +**EmbeddingModel** - ടെക്സ്റ്റിനെ സംഖ്യാ ഭാവകങ്ങളാക്കുന്നു. -**EmbeddingStore** - embeddings സൂക്ഷിക്കുകയും പുനരുപയോഗിക്കുകയും ചെയ്യുന്നു. +**EmbeddingStore** - എൻബെഡിംഗുകൾ സൂക്ഷിക്കുകയും പുനഃപ്രാപിക്കുകയും ചെയ്യുന്നു. -**MessageWindowChatMemory** - ഒടുവിൽ വന്ന സന്ദേശങ്ങളുടെ സ്ലൈഡിംഗ് വിൻഡോ പാലിക്കുന്നു. +**MessageWindowChatMemory** - പുതിയ സന്ദേശങ്ങളുടെ സ്ലൈഡിംഗ് വിൻഡോകൾ നിലനിർത്തുന്നു. -**PromptTemplate** - `{{variable}}` പ്ലേസ്‌ഹോൾഡറുകൾ ഉപയോഗിച്ച് പുനരുപയോഗയോഗ്യമായ പ്രോംപ്റ്റുകൾ സൃഷ്ടിക്കുന്നു. +**PromptTemplate** - ചെറിയ കോഡ് `{{variable}}` സ്ഥലംധാരകകൾ ഉപയോഗിച്ച് വീണ്ടും ഉപയോഗിക്കാൻ സാധിക്കുന്ന പ്രോം‌പ്റ്റുകൾ സൃഷ്ടിക്കുന്നു. -**TextSegment** - മെറ്റാഡേറ്റാ ഉൾപ്പെട്ട ടെക്സ്റ്റ് ഘടകം. RAG-യിൽ ഉപയോഗിക്കുന്നു. +**TextSegment** - മെറ്റാഡാറ്റയോടുകൂടിയ ടെക്സ്റ്റ് ചങ്ക്. RAG-യിൽ ഉപയോഗിക്കുന്നു. -**ToolExecutionRequest** - ടൂൾ പ്രവർത്തന അഭ്യർത്ഥന പ്രതിനിധാനം ചെയ്യുന്നു. +**ToolExecutionRequest** - ഉപകരണ നിർവഹണ അഭ്യർത്ഥന പ്രതിനിധാനം ചെയ്യുന്നു. -**UserMessage / AiMessage / SystemMessage** - സംഭാഷണ സന്ദേശ തരംകൾ. +**UserMessage / AiMessage / SystemMessage** - സംഭാഷണ സന്ദേശ തരം. ## AI/ML ആശയങ്ങൾ -**Few-Shot Learning** - പ്രോംപ്റ്റുകളിൽ ഉദാഹരണങ്ങൾ നൽകൽ. [മോഡ്യൂൾ 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - പ്രോംപ്റ്റുകളിൽ ഉദാഹരണങ്ങൾ നൽകുന്നത്. [മഡ്യൂൾ 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - വൻ ടെക്സ്റ്റ് ഡാറ്റയിൽ പരിശീലിച്ച AI മോഡലുകൾ. +**Large Language Model (LLM)** - വിപുലമായ ടെക്സ്റ്റ് ഡാറ്റയിൽ പരിശീലിച്ച AI മോഡലുകൾ. -**Reasoning Effort** - ചിന്താ ആഴം നിയന്ത്രിക്കുന്ന GPT-5.2 പാരാമീറ്റർ. [മോഡ്യൂൾ 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - ആലോചന ഗഹനത നിയന്ത്രിക്കാൻ GPT-5.2 ൽ പാരാമീറ്റർ. [മഡ്യൂൾ 02](../02-prompt-engineering/README.md) -**Temperature** - ഔട്ട്പുട്ടിന്റെ അസാധാരണത്വം നിയന്ത്രിക്കുന്നു. കുറവ്=നിശ്ചിതം, ഉയരം=സൃഷ്ടിപരമായത്. +**Temperature** - ഔട്ട്പുട്ട് യാദൃച്ഛികത നിയന്ത്രിക്കുന്നു. കുറവ് = നിശ്ചിതം, ഉയർന്നത് = സൃഷ്‌ടിപരമായതു. -**Vector Database** - embeddings-ക്കായി പ്രത്യേകിച്ചുള്ള ഡാറ്റാബേസ്. [മോഡ്യൂൾ 03](../03-rag/README.md) +**Vector Database** - എൻബെഡിംഗുകൾക്കായി പ്രത്യേകിച്ചുള്ള ഡാറ്റാബേസ്. [മഡ്യൂൾ 03](../03-rag/README.md) -**Zero-Shot Learning** - ഉദാഹരണങ്ങൾ ഇല്ലാതെയൊരു ജോലികൾ പ്രാവർത്തികപ്പെടുത്തൽ. [മോഡ്യൂൾ 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - ഉദാഹരണങ്ങളില്ലാതെ പ്രവർത്തനങ്ങൾ നടത്തുന്നത്. [മഡ്യൂൾ 02](../02-prompt-engineering/README.md) -## ഗാർഡ്റെയിൽസ് - [മോഡ്യൂൾ 00](../00-quick-start/README.md) +## Guardrails -**Defense in Depth** - അപ്ലിക്കേഷൻ-തല ഗാർഡ്റെയിൽസും പ്രൊവൈഡർ സുരക്ഷാ ഫിൽറ്ററുകളും ചേർന്ന ബഹുഭാഗ സുസ്ഥിര സുരക്ഷ. +**Defense in Depth** - അഡ്മിനിസ്ട്രേഷൻ തല ഗാർഡ്രെയ്ൽസും പ്രൊവൈഡർ സുരക്ഷാ ഫിൽട്ടറുകളും ചേർന്ന മൾട്ടി-ലെയർ സുരക്ഷ. -**Hard Block** - ഗൗരവമായ ഉള്ളടക്ക ലംഘനങ്ങൾക്ക് പ്രൊവൈഡർ HTTP 400 പിശക് തള്ളി മറുപടി നൽകുന്നു. +**Hard Block** - ഗുരുതര ഉള്ളടക്ക ചിലവുകളിൽ പ്രൊവൈഡർ HTTP 400 പിശക് നൽകും. -**InputGuardrail** - LLM-നു മുന്നോടിയായി ഉപയോക്തൃ ഇൻപുട്ട് പരിശോദിക്കുവാൻ LangChain4j ഇന്റർഫേസ്. അപകടകാരി പ്രോംപ്റ്റുകൾ ഉണ്ടാകുന്നതും ചെലവും വൈകല്യവും കളയുന്നു. +**InputGuardrail** - LLM-ലേക്ക് പോവുന്നതിന് മുൻപ് LangChain4j ഉപയോക്താവ് ഇൻപുട്ട് കൃത്യമായി പരിശോധിക്കുന്ന ഇന്റർഫേസ്. ഹാനികര പ്രോംപ്റ്റ് നേരത്തെ തടയുന്നതിലൂടെ ചെലവും विलംബവും കുറയ്ക്കുന്നു. -**InputGuardrailResult** - ഗാർഡ്റെയിൽ പരിശോധനയ്ക്ക് `success()` അല്ലെങ്കിൽ `fatal("reason")` തരം. +**InputGuardrailResult** - ഗാർഡ്രെയ്ൽ പരിശോധനാ ഫലം: `success()` അല്ലെങ്കിൽ `fatal("കാരണങ്ങൾ")`. -**OutputGuardrail** - ഉപയോക്താക്കൾക്ക് മറുപടി നൽകുന്നതിന് മുൻപായി AI ഉത്തരം പരിശോധന ചെയ്യാനുള്ള ഇന്റർഫേസ്. +**OutputGuardrail** - ഉപയോക്താക്കൾക്ക് മറുപടി നൽകുന്നതിനുമുമ്പ് AI പ്രതികരണങ്ങൾ പരിശോധിക്കുന്ന ഇന്റർഫേസ്. -**Provider Safety Filters** - AI പ്രൊവൈഡർമാരുടെ സംയോജിത ഉള്ളടക്ക പരിശോധന ഫിൽറ്ററുകൾ (ഉദാ: GitHub മോഡലുകൾ), API തലത്തിൽ ലംഘനങ്ങൾ പിടികൂടുന്നു. +**Provider Safety Filters** - AI പ്രൊവൈഡർമാർ (ഉദാ: Azure OpenAI) API തലത്തിൽ നിയമലംഘനങ്ങൾ പിടികൂടുന്ന മുൻനിർമ്മിത ഉള്ളടക്ക ഫിൽട്ടറുകൾ. -**Soft Refusal** - പിശക് തരാതെ മോഡൽ മിനിമം ആദരത്തോടെ മറുപടി നൽകാൻ നിർവൃത്തിയാക്കുന്നു. +**Soft Refusal** - മോഡൽ പിശക് കാണിക്കാതെ നന്ദിപിടിക്കുന്നത്. -## പ്രോംപ്റ്റ് എഞ്ചിനിയറിംഗ് - [മോഡ്യൂൾ 02](../02-prompt-engineering/README.md) +## പ്രോംപ്‌റ് എഞ്ചിനീയറിംഗ് - [മഡ്യൂൾ 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - ഘട്ടം-പ്രതി നടപടി വഴി തെറ്റില്ലാത്ത നിർവ്വചനത്തിനായി. +**Chain-of-Thought** - മെച്ചപ്പെട്ട കൃത്യതയ്ക്കായി ഘട്ടംഘട്ടമായ തർക്കം. -**Constrained Output** - പ്രത്യേക ഫോർമാറ്റ് അല്ലെങ്കിൽ ഘടന നിർബന്ധിക്കുക. +**Constrained Output** - പ്രത്യേക ഫോർമാറ്റ് അല്ലെങ്കിൽ ഘടന നിർബന്ധിക്കൽ. -**High Eagerness** - സമഗ്ര ചിന്തയ്ക്കായി GPT-5.2 മാതൃക. +**High Eagerness** - വിശദമായ ചിന്തയ്ക്കുള്ള GPT-5.2 മാതൃക. -**Low Eagerness** - വേഗതയുള്ള മറുപടിയ്ക്കായി GPT-5.2 മാതൃക. +**Low Eagerness** - വേഗത്തിലുള്ള മറുപടികൾക്കുള്ള GPT-5.2 മാതൃക. -**Multi-Turn Conversation** - സംവാദങ്ങളിൽ തെളിവുള്ള പാരമ്പര്യം നിലനിർത്തൽ. +**Multi-Turn Conversation** - സ്വഭാവങ്ങൾ സംഭാഷണ കാലാവധിയിൽ നിലനിർത്തല്. -**Role-Based Prompting** - സിസ്റ്റം സന്ദേശങ്ങളിലൂടെ മോഡലിന്റെ വ്യക്തിത്വം ക്രമീകരിക്കൽ. +**Role-Based Prompting** - സിസ്റ്റം സന്ദേശം വഴി മോഡലിൻറെ വ്യക്തിത്വം ക്രമീകരിക്കൽ. -**Self-Reflection** - മോഡൽ തങ്ങളുടെ ഔട്ട്പുട്ട് വിലയിരുത്തുകയും മെച്ചപ്പെടുത്തുകയും ചെയ്യുന്നു. +**Self-Reflection** - മോഡൽ സ്വയം താല്പര്യമറിയുകയും ചെങ്കലിക്കുക. -**Structured Analysis** - നിയന്ത്രിത വിലയിരുത്തൽഘടകം. +**Structured Analysis** - സ്ഥിരം മൂല്യനിർണ്ണയ ഘടന. -**Task Execution Pattern** - പദ്ധതി → നടപ്പാക്കുക → സംഗ്രഹിക്കുക. +**Task Execution Pattern** - പദ്ധതിയിടുക → നടപ്പാക്കുക → സംഗ്രഹിക്കുക. -## RAG (റിട്ട്രീവൽ-ഓഗ്മെന്റഡ് ജനറേഷൻ) - [മോഡ്യൂൾ 03](../03-rag/README.md) +## RAG (റിട്രീവൽ-ഓഗ്മെന്റഡ് ജനറേഷൻ) - [മഡ്യൂൾ 03](../03-rag/README.md) -**Document Processing Pipeline** - ലോഡ് → ചങ്ക് ചെയ്യുക → എംബഡ് ചെയ്യുക → സൂക്ഷിക്കുക. +**Document Processing Pipeline** - ലോഡ് → ചങ്ക് → എൻബെഡ് → സൂക്ഷിക്കുക. -**In-Memory Embedding Store** - ടെസ്റ്റിങ്ങിനായി നിലവറിയാത്ത സ്റ്റോറേജ്. +**In-Memory Embedding Store** - ടെസ്റ്റിംഗിനായി നശിക്കുന്നതല്ലാത്ത സ്റ്റോറേജ്. -**RAG** - ഉത്തരം അടിസ്ഥാർത്ഥമാക്കാൻ റിട്ട്രീവലും ജനറേഷനും സംയോജിപ്പിക്കുന്നു. +**RAG** - തിരയലുകളും ജനറേഷനുകളും കൂട്ടിച്ചേർത്ത് മറുപടികൾ ഭൂമിയാക്കുന്നു. -**Similarity Score** - സിമാന്റിക് സാമ്യമുള്ളതിനുള്ള അളവ് (0-1). +**Similarity Score** - സാംഹതിമാനതയുടെ അളവ് (0-1). -**Source Reference** - റിട്ട്രീവുചെയ്‌ത ഉള്ളടക്കത്തിന്റെ മെറ്റാഡേറ്റ. +**Source Reference** - കിട്ടിയ ഉള്ളടക്കത്തിന്റെ മെറ്റാഡാറ്റ. -## എജന്റുകളും ടൂളുകളും - [മോഡ്യൂൾ 04](../04-tools/README.md) +## ഏജന്റുകളും ഉപകരണങ്ങളും - [മഡ്യൂൾ 04](../04-tools/README.md) -**@Tool Annotation** - ജാവ മെതഡുകൾ AI-കോളബിൾ ടൂളുകളായി അടയാളപ്പെടുത്തുന്നു. +**@Tool Annotation** - ജാവ മETHODസുകളെ AI-കൊല്ല വിളിക്കാവുന്ന ഉപകരണങ്ങളായി അടയാളപ്പെടുത്തുന്നു. -**ReAct Pattern** - തർക്കിക്കുക → പ്രവർത്തിക്കുക → നിരീക്ഷിക്കുക → ആവർത്തിക്കുക. +**ReAct Pattern** - തർക്കം → പ്രവർത്തനം → ശ്രദ്ധിക്കുക → ആവർത്തിക്കുക. -**Session Management** - വ്യത്യസ്ത ഉപയോക്താക്കൾക്ക് പ്രത്യേകം കോൺടെക്സ്റ്റുകൾ. +**Session Management** - വ്യത്യസ്ത ഉപയോക്താക്കൾക്കായി വ്യത്യസ്ത കോൺടെക്സ്‌റ്റ്. -**Tool** - AI എജന്റ് വിളിക്കാമെന്ന് ഫംഗ്ഷൻ. +**Tool** - AI ഏജന്റിന് വിളിക്കാവുന്ന ഫംഗ്ഷൻ. -**Tool Description** - ടൂളിന്റെ ഉദ്ദേശവും പാരാമീറ്ററുകളും രേഖപ്പെടുത്തൽ. +**Tool Description** - ഉപകരണത്തിന്റെ ഉദ്ദേശവും പാരാമീറ്ററുകളും രേഖപ്പെടുത്തൽ. -## എജന്റിക് മോഡ്യൂൾ - [മോഡ്യൂൾ 05](../05-mcp/README.md) +## ഏജന്റിക് മഡ്യൂൾ - [മഡ്യൂൾ 05](../05-mcp/README.md) -**@Agent Annotation** - AI എജന്റുകളായി ഇന്റർഫേസുകളെ മാർക്ക് ചെയ്യുന്നതും ഡിസ്ക്ലേരറ്റീവ് പെരുമാറ്റ നിർവചനവും. +**@Agent Annotation** - ഡിക്ലറേറ്റീവ് പെരുമാറ്റ നിർവചനത്തോടെ AI ഏജന്റുകളായി ഇന്റർഫേസുകൾ അടയാളപ്പെടുത്തുന്നു. -**Agent Listener** - `beforeAgentInvocation()` ഉം `afterAgentInvocation()` ഉം ഉപയോഗിച്ച് എജന്റ് പ്രവർത്തനം നിരീക്ഷിക്കാൻ ഹുക്ക്. +**Agent Listener** - `beforeAgentInvocation()` , `afterAgentInvocation()` വഴി ഏജന്റ് പ്രവർത്തനം നിരീക്ഷിക്കുന്ന ഹുക്ക്. -**Agentic Scope** - എജന്റുകൾ ഔട്ട്പുട് `outputKey` ഉപയോഗിച്ച് സംഭരിക്കുകയും അനന്തര എജന്റുകൾ ഉപയോഗിക്കാൻ പങ്കുവെക്കുകയും ചെയ്യുന്നതിന് പങ്കിട്ട ഓർമ്മ. +**Agentic Scope** - `outputKey` ഉപയോഗിച്ച് ഏജന്റുകൾ ഔട്ട്പുട്ടുകൾ സംഭരിച്ചു ഡൗൺസ്‌ട്രോം ഏജന്റുകൾ ഉപയോഗിക്കുന്ന പങ്കുവെച്ച ഓർമ്മ. -**AgenticServices** - `agentBuilder()` ഉം `supervisorBuilder()` ഉം ഉപയോഗിച്ച് എജന്റുകൾ സൃഷ്ടിക്കുന്ന ഫാക്ടറി. +**AgenticServices** - `agentBuilder()` , `supervisorBuilder()` ഉപയോഗിച്ച് ഏജന്റുകൾ സൃഷ്ടിക്കുന്ന ഫാക്ടറി. -**Conditional Workflow** - വ്യത്യസ്ത വിദഗ്ധ എജന്റുകളിലേക്ക് വ്യത്യസ്ത ചടുവടികൾ അടിസ്ഥാനമാക്കി പാത കണ്ടെത്തൽ. +**Conditional Workflow** - വ്യത്യസ്ത വിദഗ്ധ ഏജന്റുകൾക്ക് വ്യത്യസ്ത ഉപനിബന്ധം അടിസ്ഥാനമായി റൂട്ടിംഗ്. -**Human-in-the-Loop** - അംഗീകാരം അല്ലെങ്കിൽ ഉള്ളടക്ക പരിശോധനയ്ക്കായി മനുഷ്യ checkpoints ചേർക്കുന്ന പ്രവൃത്തി മാതൃക. +**Human-in-the-Loop** - അംഗീകാരം അല്ലെങ്കിൽ ഉള്ളടക്ക പരിശോധനയ്ക്കായി മനുഷ്യ പരിശോധന പോയിന്റുകൾ ഉൾക്കൊള്ളുന്ന പ്രവൃത്തി പാറ്റേൺ. -**langchain4j-agentic** - ഡിസ്ക്ലയറേറ്റീവ് എജന്റ് നിർമാണത്തിന് വേണ്ടി മേവൻ ഡിപ്പൻഡൻസി (പരീക്ഷണത്തിലുള്ളത്). +**langchain4j-agentic** - ഡിക്ലറേറ്റീവ് ഏജന്റ് നിർമ്മാണത്തിനുള്ള Maven ഡിപ്പൻഡൻസി (പ്രയോാഗപരിചയം). -**Loop Workflow** - ഒരു നിബന്ധന തികയ്ക്കുന്ന വരെ (ഉദാ: ക്വാളിറ്റി സ്കോർ ≥ 0.8) എജന്റ് പ്രവർത്തനം ആവർത്തിക്കൽ. +**Loop Workflow** - ഒരു നിബന്ധന പൂരിപ്പിക്കുന്നവരെ (ഉദാ: ഗുണമേൻമ സ്കോർ ≥ 0.8) വരെ ഏജന്റ് നിർവഹണം ആവർത്തിക്കൽ. -**outputKey** - എജന്റ് അന്നോട്ടേഷൻ പാരാമീറ്റർ, എജന്റിക് സ്‌കോപ്പിൽ ഫലങ്ങൾ സൂക്ഷിക്കുന്ന സ്ഥലം. +**outputKey** - Agentic Scope ൽ ഫലങ്ങൾ സംഭരിക്കാനുള്ള ഏജന്റ് അനോട്ടേഷൻ പാരാമീറ്റർ. -**Parallel Workflow** - സ്വതന്ത്ര ജോലികൾക്കായി ഒരേസമയം നിരവധി എജന്റുകൾ ഓടിക്കുക. +**Parallel Workflow** - സ്വതന്ത്ര പ്രവർത്തനങ്ങൾക്കായി ഒരേ സമയം പല ഏജന്റുകളും പ്രവർത്തിപ്പിക്കൽ. -**Response Strategy** - സൂപ്പർവൈസർ അന്തിമ ഉത്തരം രൂപപ്പെടുത്തുന്ന വിധം: അവസാനത്തെ(LAST), സംഗ്രഹം(SUMMARY), അല്ലെങ്കിൽ സ്കോർ ചെയ്തു(SCORED). +**Response Strategy** - സൂപ്പർവൈസർ അവസാന ഉത്തരം രൂപപ്പെടുത്തുന്ന വിധം: LAST, SUMMARY, അല്ലെങ്കിൽ SCORED. -**Sequential Workflow** - പരമ്പരാഗതമായി എജന്റുകൾ പ്രവർത്തിക്കുന്ന ഘടകം, ഔട്ട്പുട്ട് അടുത്ത ഘട്ടത്തിലേക്ക്. +**Sequential Workflow** - ഔട്ട്പുട്ട് അടുത്ത ഘട്ടത്തിലേക്ക് പോവുന്ന ക്രമത്തിൽ ഏജന്റുകൾ പ്രവർത്തിപ്പിക്കുക. -**Supervisor Agent Pattern** - ഒരു സൂപ്പർവൈസർ LLM ഡൈനാമിക് ആയി ഏത് സബ്-എജന്റുകളെ വിളിക്കണമെന്നു തീരുമാനിക്കുന്ന മുന്നേറ്റ എജന്റിക് മാതൃക. +**Supervisor Agent Pattern** - സൂപ്പർവൈസർ LLM ഗതിപാരമുള്ളതിലായ്കെ ഏജന്റുകൾ തിരഞ്ഞെടുക്കുന്ന പ്രഗതിശീലിത ഏജന്റിക് മാതൃക. -## മോഡൽ_Context_പ്രോട്ടോക്കോൾ (MCP) - [മോഡ്യൂൾ 05](../05-mcp/README.md) +## മോഡൽ കോൺടെക്സ്‌റ്റ് പ്രോട്ടോക്കോൾ (MCP) - [മഡ്യൂൾ 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j-യിൽ MCP സംയോജനത്തിന് മേവൻ ഡിപ്പൻഡൻസി. +**langchain4j-mcp** - LangChain4j ലെ MCP ഇന്റഗ്രേഷനിനുള്ള Maven ഡിപ്പൻഡൻസി. -**MCP** - മോഡൽ_Context_പ്രോട്ടോക്കോൾ: AI ആപ്പുകളെ പുറം ടൂളുകളുമായി ബന്ധിപ്പിക്കുന്ന സ്റ്റാൻഡേർഡ്. ഒരിക്കൽ രൂപീകരിക്കുക, എവിടെയും ഉപയോഗിക്കുക. +**MCP** - മോഡൽ കോൺടെക്സ്‌റ്റ് പ്രോട്ടോക്കോൾ: AI ആപ്പുകൾ ബാഹ്യ ഉപകരണങ്ങളുമായി ബന്ധിപ്പിക്കാൻ സാധാരണ സ്റ്റാൻഡേര്‍ഡ്. ഒറ്റ തവണ നിർമ്മിച്ച് എല്ലായിടവും ഉപയോഗിക്കുക. -**MCP Client** - MCP സെർവറുകളെ കണക്ട് ചെയ്ത് ടൂളുകൾ കണ്ടെത്താനും ഉപയോഗിക്കാനും ഉള്ള അപ്ലിക്കേഷൻ. +**MCP Client** - MCP സർവറുകളുമായി ബന്ധപ്പെടുന്ന, ഉപകരണങ്ങൾ തേടുകയും ഉപയോഗിക്കുകയും ചെയ്യാനുള്ള ആപ്പ്. -**MCP Server** - ടൂളുകൾ വ്യക്തമാക്കിയ വിവരണവും പാരാമീറ്റർ സ്കീമകളും സഹിതം MCP വഴി പ്രദർശിപ്പിക്കുന്ന സേവനം. +**MCP Server** - MCP വഴിയുള്ള ഉപകരണങ്ങൾ നിർവചിക്കുകയും പരാമീറ്റർ സ്കീമ സഹായത്തോടെ സേവനം നൽകുകയും ചെയ്യുന്നു. -**McpToolProvider** - MCP ടൂളുകൾ AI സേവനങ്ങളിലും എജന്റുകളിലും ഉപയോഗിക്കാൻ LangChain4j ഘടകം. +**McpToolProvider** - AI സേവനങ്ങൾക്കും ഏജന്റുകൾക്കുമുള്ള MCP ഉപകരണങ്ങൾ ലാങ്ക്ചെയിൻ4ജിൽ വ്രാപ്പ് ചെയ്യുന്ന ഘടകം. -**McpTransport** - MCP കമ്മ്യൂണിക്കേഷൻ ഇന്റർഫേസ്. നടപ്പിലാക്കലുകൾ: Stdio, HTTP. +**McpTransport** - MCP ആശയവിനിമയത്തിനുള്ള ഇന്റർഫേസ്. ഒരു ഘടനയും സ്‌ടാഡിയോ, HTTP ഉൾപ്പെടുന്നു. -**Stdio Transport** - stdin/stdout വഴി ലൊക്കൽ പ്രോസസ് ട്രാൻസ്പോർട്ട്. ഫയൽസിസ്റ്റം ആക്‌സസിനു അല്ലെങ്കിൽ കമാൻഡ്-ലൈൻ ടൂളുകൾക്കായി പ്രയോജനപ്പെടുന്നു. +**Stdio Transport** - stdin/stdout വഴിയുള്ള ലോക്കൽ പ്രക്രിയ ട്രാൻസ്പോർട്ട്. ഫയൽസിസ്റ്റം ആക്‌സസ് അല്ലെങ്കിൽ കമാൻഡ് ലൈൻ ഉപകരണങ്ങൾക്കായി ഉപയോഗപ്രദം. -**StdioMcpTransport** - MCP സെർവർ subprocess ആയി സ്രഷ്ടിക്കുന്ന LangChain4j നടപ്പാക്കൽ. +**StdioMcpTransport** - subprocess ആയി MCP സർവർ ഉണ്ടാക്കുന്ന LangChain4j നടപ്പാക്കൽ. -**Tool Discovery** - ക്ലയന്റ് ലഭ്യമായ ടൂളുകൾ വിവരണങ്ങളും സ്കീമകളും ചോദിക്കുന്നു. +**Tool Discovery** - ലഭ്യമായ ഉപകരണങ്ങൾ വിവരണങ്ങളും സ്കീമകളും കൂടി സെർവറിൽ നിന്ന് ക്ലയന്റ് ചോദിക്കുന്നത്. -## അസ്യൂർ സേവനങ്ങൾ - [മോഡ്യൂൾ 01](../01-introduction/README.md) +## ആസ്യൂർ സേവനങ്ങൾ - [മഡ്യൂൾ 01](../01-introduction/README.md) -**Azure AI Search** - വെക്ടർ ശേഷിയുള്ള ക്ലൗഡ് തിരയൽ. [മോഡ്യൂൾ 03](../03-rag/README.md) +**Azure AI Search** - വെക്ടർ സാദ്ധ്യതകളുള്ള ക്ലൗഡ് തിരയൽ. [മഡ്യൂൾ 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - അസ്യൂർ വസ്‌ഥകൾ വിന്യാസം ചെയ്യുന്നു. +**Azure Developer CLI (azd)** - ആസ്യൂർ റിസോഴ്സുകൾ നിയോഗിക്കുന്നു. **Azure OpenAI** - മൈക്രോസോഫ്റ്റിന്റെ എന്റർപ്രൈസ് AI സേവനം. -**Bicep** - അസ്യൂർ ഇൻഫ്രാസ്ട്രക്ചർ-ആസ്-കോഡ് ഭാഷ. [ഇൻഫ്രാസ്ട്രക്ചർ ഗൈഡ്](../01-introduction/infra/README.md) +**Bicep** - ആസ്യൂർ ഇൻഫ്രാസ്ട്രക്ചർ-എസ്-കോഡ് ഭാഷ. [ഇൻഫ്രാസ്ട്രക്ചർ ഗൈഡ്](../01-introduction/infra/README.md) -**Deployment Name** - അസ്യൂറിൽ മോഡൽ വിന്യാസത്തിനുള്ള പേര്. +**Deployment Name** - ആസ്യൂറിൽ മോഡൽ നിയോഗത്തിന് പേരിടൽ. -**GPT-5.2** - പരിഗണന നിയന്ത്രണയുള്ള ഏറ്റവും പുതിയ OpenAI മോഡൽ. [മോഡ്യൂൾ 02](../02-prompt-engineering/README.md) +**GPT-5.2** - ആലോചന നിയന്ത്രണവുമായി ഏറ്റവും പുതിയ OpenAI മോഡൽ. [മഡ്യൂൾ 02](../02-prompt-engineering/README.md) -## പരീക്ഷണവും വികസനവും - [Testing Guide](TESTING.md) +## ടെസ്റ്റിംഗ് ആൻഡ് ഡെവലപ്പ്മെന്റ് - [ടെസ്റ്റിംഗ് ഗൈഡ്](TESTING.md) -**Dev Container** - കണ്ടെയ്‌നറിൽ ഡവലപ്പ്മെന്റ് അന്തരീക്ഷം. [ക്രമീകരണം](../../../.devcontainer/devcontainer.json) +**Dev Container** - കണ്ടെയ്‌നറൈസ്ഡ് ഡെവലപ്പ്മെന്റ് പരിസരം. [കോൺഫിഗറേഷൻ](../../../.devcontainer/devcontainer.json) -**GitHub Models** - സൗജന്യ AI മോഡൽ പ്ലേഗ്രൗണ്ട്. [മോഡ്യൂൾ 00](../00-quick-start/README.md) +**In-Memory Testing** - മെമ്മോറിയിലുള്ള സ്റ്റോറേജ് ഉപയോഗിച്ച് ടെസ്റ്റിംഗ്. -**In-Memory Testing** - ഓർമ്മയിൽ നിന്ന് സ്റ്റോറേജ് ഉപയോഗിച്ച് പരീക്ഷണം. +**Integration Testing** - യഥാർത്ഥ ഇൻഫ്രാസ്ട്രക്ചർ ഉപയോഗിച്ച് ടെസ്റ്റ് നടത്തുന്നു. -**Integration Testing** - യഥാർത്ഥ ഇൻഫ്രാസ്ട്രക്ചർ ഉപയോഗിച്ച് പരീക്ഷണം. - -**Maven** - ജാവ ബിൽഡ് ഓട്ടോമേഷൻ ടൂൾ. +**Maven** - ജാവ ബിൽഡ് ഓട്ടോമേഷൻ ഉപകരണം. **Mockito** - ജാവ മോകിംഗ് ഫ്രെയിംവർക്ക്. -**Spring Boot** - ജാവ അപ്ലിക്കേഷൻ ഫ്രെയിംവർക്ക്. [മോഡ്യൂൾ 01](../01-introduction/README.md) +**Spring Boot** - ജാവ ആപ്പ്ലിക്കേഷൻ ഫ്രെയിംവർക്ക്. [മഡ്യൂൾ 01](../01-introduction/README.md) --- -**ഡിസ്ക്ലെയിമര്‍**: -ഈ ഡോക്യുമെന്റു AI പരിഭാഷ സർവീസ് [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് പരിഭാഷചെയ്തതാണ്. കൃത്യതയ്ക്കായി നാം ശ്രമിക്കുന്നുവെങ്കിലും, യന്ത്രപരിഭാഷകളിൽ പിശകുകളോ അപര്യാപ്തതകളോ ഉണ്ടാകാം എന്ന് ദയവായി ശ്രദ്ധിക്കുക. യഥാര്‍ഥ ഭാഷയിലെ ഒറിജിനല്‍ ഡോക്യുമെന്റ് അതിന്റെ പ്രാമാണിക സ്രോതസ്സായി പരിഗണിക്കപ്പെടണം. നിർണ്ണായക വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ പരിഭാഷ ശുപാർശ ചെയ്യും. ഈ പരിഭാഷയിലൂടെ ഉണ്ടായ എന്തെങ്കിലും തെറ്റിദ്ധാരണകൾക്ക് അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾക്ക് ഞങ്ങൾ ഉത്തരവാദികളല്ല. +**അറിയിപ്പ്**: +ഈ രേഖ AI പരിഭാഷാ സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് പരിഭാഷപ്പെടുത്തിയതാണ്. ഞങ്ങൾ കൃത്യതയ്ക്കായി ശ്രമിക്കുന്നുവെങ്കിലും, ഓട്ടോമേറ്റഡ് പരിഭാഷകളിൽ പിഴവുകൾ അല്ലെങ്കിൽ തെറ്റായ വിവരങ്ങൾ ഉണ്ടാകാൻ സാധ്യതയുണ്ട്. അതിന്റെ സ്വാഭാവിക ഭാഷയിലുള്ള അസൽ രേഖയാണ് പ്രാമാണികമായ ഉറവിടമായി പരിഗണിക്കേണ്ടത്. നിർണായകമായ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ പരിഭാഷ ശുപാർശ ചെയ്യുന്നു. ഈ പരിഭാഷ ഉപയോഗിച്ച് ഉണ്ടാകുന്ന തെറ്റിദ്ധാരണകൾ അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾക്കായി ഞങ്ങൾ ഉത്തരവാദികളല്ല. \ No newline at end of file diff --git a/translations/ml/docs/TESTING.md b/translations/ml/docs/TESTING.md index 6b26d61a4..d4832d4bb 100644 --- a/translations/ml/docs/TESTING.md +++ b/translations/ml/docs/TESTING.md @@ -1,20 +1,20 @@ -# LangChain4j ആപ്ലിക്കേഷനുകളുടെ പരിശോധന +# LangChain4j അപ്ലിക്കേഷനുകൾ ടെസ്റ്റുചെയ്യൽ -## ഉള്ളടക്ക പട്ടിക +## പാഠ്യക്രമം -- [വേഗത്തിലുള്ള തുടക്കം](../../../docs) -- [പരീക്ഷണങ്ങൾ എന്ത് ഉൾക്കൊണ്ടിരിക്കുന്നു](../../../docs) -- [പരീക്ഷണങ്ങൾ പ്രവർത്തിപ്പിക്കൽ](../../../docs) -- [VS കോഡിൽ പരീക്ഷണങ്ങൾ പ്രവർത്തിപ്പിക്കൽ](../../../docs) -- [പരീക്ഷണ മാതൃകകൾ](../../../docs) -- [പരിശോധന തത്ത്വം](../../../docs) -- [അടുത്ത ഘട്ടങ്ങൾ](../../../docs) +- [ദ്രുതാരംഭം](#ദ്രുതാരംഭം) +- [ടെസ്റ്റുകൾ പരിശോധിക്കുന്നത് എന്താണെന്ന്](#ടെസ്റ്റുകൾ-പരിശോധിക്കുന്നത്-എന്താണെന്ന്) +- [ടെസ്റ്റുകൾ നടത്തുന്നത്](#ടെസ്റ്റുകൾ-നടത്തുന്നത്) +- [VS കോഡിൽ ടെസ്റ്റുകൾ നടത്തുന്നത്](#vs-കോഡിൽ-ടെസ്റ്റുകൾ-നടത്തുന്നത്) +- [ടെസ്റ്റിംഗ് മാതൃകകൾ](#ടെസ്റ്റിംഗ്-മാതൃകകൾ) +- [ടെസ്റ്റിംഗ് തത്വചിന്ത](#ടെസ്റ്റിംഗ്-തത്വചിന്ത) +- [അടുത്ത ചുവട്](#അടുത്ത-ചുവട്) -ഈ ഗൈഡ് API കീകൾ അല്ലെങ്കിൽ പുറത്തെ സേവനങ്ങൾ ആവാശ്യമില്ലാതെ എങ്ങനെ AI ആപ്ലിക്കേഷനുകൾ പരിശോധിക്കാമെന്ന് കാണിക്കുന്ന പരീക്ഷണങ്ങളിലൂടെ നിങ്ങളെ നയിക്കുന്നു. +API കീകൾക്കോ ബാഹ്യ സേവനങ്ങൾക്കോ ആവശ്യമില്ലാതെ AI അപ്ലിക്കേഷനുകൾ എങ്ങനെ ടെസ്റ്റ് ചെയ്യാമെന്ന് കാണിക്കുന്ന ടെസ്റ്റുകൾ നിങ്ങൾക്ക് ഈ ഗൈഡ് വഴി കൈമാറുന്നു. -## വേഗത്തിലുള്ള തുടക്കം +## ദ്രുതാരംഭം -ഓർഡ് കമാൻഡ് ഉപയോഗിച്ച് എല്ലാ പരീക്ഷണങ്ങളും നടത്തുക: +ഒരു കമാൻഡ് കൊണ്ട് എല്ലാ ടെസ്റ്റുകളും ഓടിക്കുക: **Bash:** ```bash @@ -25,33 +25,32 @@ mvn test ```powershell mvn --% test ``` - -എല്ലാ പരീക്ഷണങ്ങളും വിജയകരമായി പാസായാൽ താഴെയുള്ള സ്ക്രീൻഷാട്ടിലെ പോലെ ഔട്ട്പുട്ട് കാണിക്കും — പരാജയങ്ങളില്ലാതെ പരീക്ഷണങ്ങൾ പ്രവർത്തിക്കും. + +എല്ലാ ടെസ്റ്റുകളും വിജയിച്ചാൽ, താഴെയുള്ള സ്ക്രീൻഷോട്ടിന് സമാനം ആവുന്ന ഔട്ട്‌പുട്ട് കാണാം — ടെസ്റ്റുകൾ വാറ്യമില്ലാതെ ഓടുന്നു. Successful Test Results -*സകല പരീക്ഷണങ്ങളും പരാജയങ്ങളില്ലാതെ പാസായതായി കാണിക്കുന്ന വിജയകരമായ പരീക്ഷണ നടപ്പാക്കൽ* +*വാറ്യമില്ലാതെ എല്ലാ ടെസ്റ്റുകളും വിജയിക്കുന്ന വിജയകരമായ ടെസ്റ്റിംഗ്* -## പരീക്ഷണങ്ങൾ എന്ത് ഉൾക്കൊണ്ടിരിക്കുന്നു +## ടെസ്റ്റുകൾ പരിശോധിക്കുന്നത് എന്താണെന്ന് -ഈ കോഴ്‌സ് **യൂണിറ്റ് പരീക്ഷണങ്ങൾ** എന്നവയിൽ കേന്ദ്രീകരിക്കുന്നു, അവ ലൊക്കലായി പ്രവർത്തിക്കുന്നു. ഓരോ പരീക്ഷണവും വ്യക്തമായ ഒരു LangChain4j ആശയം വേർതിരിച്ചുവച്ച് കാണിക്കുന്നു. താഴെയുള്ള പരീക്ഷണ പിരമിഡ് കാണിക്കുന്നത് യൂണിറ്റ് പരിശോധനകൾ എവിടെയാണ് അനുയോജ്യമായ സ്ഥാനം എന്നതാണ് — ഇത് നിങ്ങൾ നിർമ്മിക്കുന്ന മറ്റു പരീക്ഷണ തന്ത്രങ്ങൾക്ക് വേഗതയേകുകയും വിശ്വസനീയമായ അടിസ്ഥാനം നല്കുകയും ചെയ്യുന്നു. +ഈ കോഴ്സ് പ്രാദേശികമായി ഓടുന്ന **ഒക്ടൈറ്റ്സ് ടെസ്റ്റുകൾ**-ൽ കേന്ദ്രീകരിക്കുന്നു. ഓരോ ടെസ്റ്റ് LangChain4j കോൺസെപ്റ്റ് പ്രത്യേകിച്ച് പ്രദർശിപ്പിക്കുന്നു. താഴെയുള്ള ടെസ്റ്റിംഗ് പിരമിഡ് ഒക്ടൈറ്റ്സ് ടെസ്റ്റുകൾ എവിടെ പൊരുത്തപ്പെടുന്നു എന്ന് കാണിക്കുന്നു — ഇത് വേഗത്തിൽ, വിശ്വസനീയമായി പണി തുടങ്ങുന്ന അടിത്തറയാണ്, നിങ്ങളുടെ മറ്റ് ടെസ്റ്റ് തന്ത്രത്തിന് സഹായം നൽകുന്നു. Testing Pyramid -*യൂണിറ്റ് പരീക്ഷണങ്ങൾ (വേഗം, വേർതിരിഞ്ഞ) – ഇന്റഗ്രേഷൻ പരീക്ഷണങ്ങൾ (യഥാർത്ഥ ഘടകങ്ങൾ), എൻഡ്-ടു-എൻഡ് പരീക്ഷണങ്ങൾ എന്നവർ തമ്മിലുള്ള സാദൃശ്യം കാണിക്കുന്ന പരീക്ഷണ പിരമിഡ്. ഈ പരിശീലനത്തിൽ യൂണിറ്റ് ടെസ്റ്റിംഗ് ഉൾകാണിക്കുന്നു.* +*ഒക്ടൈറ്റ്സ് ടെസ്റ്റുകളുടെ സഞ്ചയമുണ്ട് (വേഗം, നിരന്തരമായ), സംയോജിത ടെസ്റ്റുകൾ (യഥാർത്ഥ ഘടകങ്ങൾ), ഒടുവിലത്തെ ടെസ്റ്റുകൾ എന്നിവയ്ക്കിടയിലുള്ള ബലം. ഈ പരിശീലനം ഒക്ടൈറ്റ്സ് ടെസ്റ്റിംഗിനെക്കുറിച്ചാണ്.* -| മോഡ്യൂൾ | പരീക്ഷണങ്ങൾ | ശ്രദ്ധ നൽക്കേണ്ടത് | പ്രധാന ഫയലുകൾ | -|--------|-------------|----------------|-----------------| -| **00 - വേഗത്തിലുള്ള തുടക്കം** | 6 | പ്രോംപ്റ്റ് ടെംപ്ലേറ്റുകളും ഭേദഗതി പദവങ്ങളുമ് | `SimpleQuickStartTest.java` | -| **01 - പരിചയം** | 8 | സംഭാഷണ ഓർമയും സ്റ്റേറ്റ്‌ഫുൾ ചാറ്റും | `SimpleConversationTest.java` | -| **02 - പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ്** | 12 | GPT-5.2 മാതൃകകൾ, ഉത്സാഹത നിലകൾ, ഘടനയിലുളള ഔട്ട്പുട്ട് | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | ഡോക്യുമെന്റ് ഇൻജെക്ഷൻ, എംബെഡിംഗുകൾ, സാമിത്ത്യമുള്ള തിരച്ചിൽ | `DocumentServiceTest.java` | -| **04 - ഉപകരണങ്ങൾ** | 12 | ഫംഗ്ഷൻ കോൾ ചെയ്യൽ, ഉപകരണം ചൈനിങ് | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | മോഡൽ കോൺടെക്സ് പ്രോട്ടോക്കോൾ സ്റ്റ്ഡിയോ ട്രാൻസ്പോർട്ട് ഉപയോഗിച്ച് | `SimpleMcpTest.java` | +| മോഡ്യൂൾ | ടെസ്റ്റുകൾ | ശ്രദ്ധ | പ്രധാന ഫയലുകൾ | +|--------|-------|-------|-----------| +| **01 - പരിചയം** | 8 | സംഭാഷണ മെമ്മറിയും സ്‌റ്റേറ്റ്ഫുൾ ചാറ്റും | `SimpleConversationTest.java` | +| **02 - പ്രൊംപ്റ്റ് എൻജിനീയറിംഗ്** | 12 | GPT-5.2 മാതൃകകൾ, ആഗ്രഹ നിലകൾ, ഘടനാബദ്ധമായ ഔട്ട്‌പുട്ട് | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | ഡോക്യുമെന്റ് ഇഞ്ചഷൻ, എംബെഡ്ഡിംഗുകൾ, സമാനതാ തിരയൽ | `DocumentServiceTest.java` | +| **04 - ഉപകരണങ്ങൾ** | 12 | ഫംഗ്ഷൻ കോൾ ചെയ്യൽ, ഉപകരണ ചൈനിംഗ് | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | മോഡൽ കോൺടക്സ് പ്രോട്ടോക്കോൾ സ്റ്റ്ഡിയോ ട്രാൻസ്പോർട്ടുമായി | `SimpleMcpTest.java` | -## പരീക്ഷണങ്ങൾ പ്രവർത്തിപ്പിക്കൽ +## ടെസ്റ്റുകൾ നടത്തുന്നത് -**റൂട്ട് നിന്ന് എല്ലാ പരീക്ഷണങ്ങളും നടത്തുക:** +**റൂട്ടിൽനിന്ന് എല്ലാ ടെസ്റ്റുകളും ഓടിക്കുക:** **Bash:** ```bash @@ -62,24 +61,24 @@ mvn test ```powershell mvn --% test ``` - -**ഏതെങ്കിലും പ്രത്യേക മോഡ്യൂളിനുള്ള പരീക്ഷണങ്ങൾ പ്രവർത്തിപ്പിക്കുക:** + +**ഒരു പ്രത്യേക മോഡ്യൂൾക്ക് ടെസ്റ്റുകൾ ഓടിക്കുക:** **Bash:** ```bash cd 01-introduction && mvn test -# അല്ലെങ്കിൽ റൂട്ട്‌ഇനു നിന്നുമായി +# അല്ലെങ്കിൽ റൂട്ടിൽ നിന്ന് mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# അല്ലെങ്കിൽ റൂട്ട് മുതൽ +# അല്ലെങ്കിൽ റൂട്ടിൽ നിന്ന് mvn --% test -pl 01-introduction ``` - -**ഒരു ടെസ്റ്റ് ക്ലാസ് മാത്രം പ്രവർത്തിപ്പിക്കുക:** + +**ഒരു ടെസ്റ്റ് ക്ലാസ് മാത്രം ഓടിക്കുക:** **Bash:** ```bash @@ -90,46 +89,46 @@ mvn test -Dtest=SimpleConversationTest ```powershell mvn --% test -Dtest=SimpleConversationTest ``` - -**ഒരു പ്രത്യേക ടെസ്റ്റ് മെഥഡ് പ്രവർത്തിപ്പിക്കുക:** + +**ഒരു പ്രത്യേക ടെസ്റ്റ് മെത്ത്‌ഡ്സ് ഓടിക്കുക:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#സംവാദ ചരിത്രം നിലനിർത്തേണ്ടതുണ്ടോ +mvn test -Dtest=SimpleConversationTest#സംഭാഷണ ചരിത്രം നിലനിർത്തണം ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#സംഭാഷണ ചരിത്രം നിലനിർത്തണം +mvn --% test -Dtest=SimpleConversationTest#സംഭാഷണ ചരിത്രം പരിപാലിക്കേണ്ടതാണ് ``` + +## VS കോഡിൽ ടെസ്റ്റുകൾ നടത്തുന്നത് -## VS കോഡിൽ പരീക്ഷണങ്ങൾ പ്രവർത്തിപ്പിക്കൽ - -നിങ്ങൾ Visual Studio Code ഉപയോഗിച്ചാൽ, ടെസ്റ്റ് എക്സ്പ്ലോറർ പരീക്ഷണങ്ങൾ പ്രവർത്തിപ്പിക്കാനും ഡീബഗ് ചെയ്യാനും ഗ്രാഫിക്കൽ ഇന്റർഫേസ് നൽകുന്നു. +Visual Studio Code ഉപയോഗിക്കുകയാണെങ്കിൽ, Test Explorer ടെസ്റ്റുകൾ ഓടിക്കാനും ഡീബഗ് ചെയ്യാനും ഗ്രാഫിക്കൽ ഇന്റർഫേസ് നൽകുന്നു. VS Code Test Explorer -*VS Code ടെസ്റ്റ് എക്സ്പ്ലോറർ മുഴുവൻ ജാവ ടെസ്റ്റ് ക്ലാസുകളും വ്യക്തിഗത ടെസ്റ്റ് മെഥഡുകളും ഉൾക്കൊള്ളുന്ന ടെസ്റ്റ് ട്രീ കാണിക്കുന്നു* +*VS Code Test Explorer Java ടെസ്റ്റ് ക്ലാസുകളുടെയും വ്യക്തിഗത ടെസ്റ്റ് മെത്തഡുകളുടെയും പരിശോധനാ വൃക്ഷം കാണിക്കുന്നു* -**VS കോഡിൽ ടെസ്റ്റുകൾ പ്രവർത്തിപ്പിക്കാൻ:** +**VS കോഡിൽ ടെസ്റ്റുകൾ ഓടിക്കാൻ:** -1. ഒരലയാളിയുള്ള അഭിനിവേശ ബാറിൽ കീമികോഷikon ക്ലിക്ക് ചെയ്ത് ടെസ്റ്റ് എക്സ്പ്ലോറർ തുറക്കുക -2. എല്ലാ മോഡ്യൂളുകളും ടെസ്റ്റ് ക്ലാസുകളും കാണാൻ ട്രീ വലിപ്പിപ്പിക്കുക -3. പ്രത്യേകമായി പ്രവർത്തിപ്പിക്കാൻ ഏതെങ്കിലും ടെസ്റ്റിന്റെ പക്കൽ പ്ലേ ബട്ടൺ ക്ലിക്ക് ചെയ്യുക -4. മുഴുവൻ സ്യൂട്ട് പ്രവർത്തിപ്പിക്കാൻ "Run All Tests" ക്ലിക്ക് ചെയ്യുക -5. ഏതെങ്കിലും ടെസ്റ്റ് റൈറ്റ്ക്ലിക്ക് ചെയ്ത് "Debug Test" തിരഞ്ഞെടുക്കുക, ബ്രേക്ക് പോയിന്റുകൾ സജ്ജമാക്കി കോഡിലൂടെ ഘട്ടം ചവിട്ടുന്നത്. +1. പ്രവർത്തന ബാറിൽ നിലവറിയുന്ന ബീക്കർ ഐക്കൺ ക്ലിക്ക് ചെയ്ത് Test Explorer തുറക്കുക +2. ടെസ്റ്റ് മൂലകം വ്യാപിപ്പിച്ച് എല്ലാ മോഡ്യൂളുകളും ടെസ്റ്റ് ക്ലാസുകളും കാണുക +3. ഏതെങ്കിലും ടെസ്റ്റ് തനിക്ക് കൂടെ പ്ലേ ബട്ടൺ ക്ലിക്ക് ചെയ്താൽ അത് ഒറ്റയായി ഓടും +4. "Run All Tests" ക്ലിക്ക് ചെയ്ത് മുഴുവൻ ടെസ്റ്റ് സ്യൂട്ട് പ്രവർത്തിപ്പിക്കുക +5. ഏതെങ്കിലും ടെസ്റ്റ് റൈറ്റ്-ക്ലിക്ക് ചെയ്ത് "Debug Test" തിരഞ്ഞെടുത്ത് ബ്രേക്‌പോയിന്റ് സെറ്റ് ചെയ്ത് കോഡ് ഘട്ടം ഘട്ടമായി പരിശോധിക്കുക -ടെസ്റ്റ് എക്സ്പ്ലോറർ വിജയിച്ച ടെസ്റ്റുക്കൾക്ക് പച്ച ടിക്കുകൾ കാണിക്കുകയും പരാജയപ്പെട്ടപ്പോൾ വിശദമായ പരാജയ സന്ദേശങ്ങൾ നൽകുകയും ചെയ്യുന്നു. +ടെസ്റ്റ് എക്സ്പ്ലോറർ വിജയിച്ച ടെസ്റ്റുകൾക്ക് പച്ച ചെക്ക് മാർക്കുകൾ കാണിക്കുന്നു, പരാജയപ്പെട്ടപ്പോൾ വിശദമായ ഫെയില്യർ വിവരം നൽകുന്നു. -## പരിശോധന മാതൃകകൾ +## ടെസ്റ്റിംഗ് മാതൃകകൾ -### മാതൃക 1: പ്രോംപ്റ്റ് ടെംപ്ലേറ്റുകൾ പരിശോധിക്കൽ +### മാതൃകം 1: പ്രൊംപ്റ്റ് ടെംപ്ലേറ്റുകൾ ടെസ്റ്റുചെയ്യല്‍ -ഏറ്റവും ലളിതമായ മാതൃക പ്രോംപ്റ്റ് ടെംപ്ലേറ്റുകൾ AI മോഡൽ ഉപയോഗിക്കാതെ പരിശോധിക്കുന്നു. വ്യത്യസ്ത പദങ്ങളുടെ സബ്സ്റ്റ്യൂഷൻ ശരിയാണോ എന്നും പ്രോംപ്റ്റുകൾ പ്രതീക്ഷിച്ചതുപോലെ ഫോർമാറ്റ് ചെയ്തിട്ടുളളതാണോ എന്നും നിങ്ങൾ உறപ്പാക്കുന്നു. +എളിപ്പെട്ട മാതൃകം പ്രൊംപ്റ്റ് ടെംപ്ലേറ്റുകൾ വേറെ എഐ മോഡൽ കോൾ ചെയ്യാതിരിക്കുകയാണ് ടെസ്റ്റ് ചെയ്യുന്നത്. സന്ദർഭഭാഗങ്ങൾ ശരിയായി വിപരീതപ്പെടുത്തിയിട്ടുണ്ടോ എന്നും പ്രൊംപ്റ്റുകൾ പ്രതീക്ഷിച്ചതുപോലെ ഫോർമാറ്റ് ചെയ്തിട്ടുണ്ടോ എന്നും പരിശോധിക്കുന്നു. Prompt Template Testing -*പ്രോംപ്റ്റ് ടെംപ്ലേറ്റ് ടെസ്റ്റിംഗ് കാണിക്കുന്ന സബ്സ്റ്റ്യൂഷൻ പ്രവാഹം: പ്ലേസ്ഹോൾഡറുകൾ ഉള്ള ടെംപ്ലേറ്റ് → മൂല്യങ്ങൾ പ്രയോഗിച്ചു → ഫോർമാറ്റ് ചെയ്ത ഔട്ട്പുട്ട് പരിശോദിച്ചു* +*പ്രൊംപ്റ്റ് ടെംപ്ലേറ്റുകൾ ടെസ്റ്റ് ചെയ്യുന്നതിൽ മാറ്റിസ്ഥാപിച്ച വേരിയബിളുകൾ: പ്ലെയ്സ്‌ഹോൾഡറുകൾ ഉള്ള ടെംപ്ലേറ്റ് → മൂല്യങ്ങൾ പ്രയോഗിച്ചത് → ഫോർമാറ്റ് ചെയ്ത ഔട്ട്‌പുട്ട് പരിശോധിച്ചത്* ```java @Test @@ -147,28 +146,16 @@ void testPromptTemplateFormatting() { assertThat(prompt.text()).isEqualTo("Best time to visit Paris for sightseeing?"); } ``` + +ഈ മാതൃക വേരിയബിളുകൾ ശരിയായി മാറ്റിസ്ഥാപിച്ചിട്ടുണ്ടെന്നും പ്രൊംപ്റ്റുകൾ പ്രതീക്ഷിച്ചതുപോലെ ഫോർമാറ്റ് ചെയ്തിട്ടുണ്ടെന്നും ഉറപ്പുവരുത്തുന്നു— API കീ യോ മോഡൽ കോൾ ആവശ്യമില്ല. -ഈ ടെസ്റ്റ് `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` എന്ന സ്ഥലം ഉപയോഗിക്കുന്നു. - -**നടത്തുക:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#ടെസ്റ്റ്‌പ്രാമ്പ്‌റൈലെറ്റ്‌ഫോർമാറ്റിംഗ് -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#പരിശോധന പ്രോംപ്റ്റ് ടെംപ്ലേറ്റ് ഫോർമാറ്റിംഗ് -``` - -### മാതൃക 2: ഭാഷാ മോഡലുകൾ മോക്ക് ചെയ്യൽ +### മാതൃകം 2: ഭാഷാ മോഡലുകൾ മോക്കിങ് -സംഭാഷണ ലജിക് പരിശോധിക്കുമ്പോൾ, മുൻകൂട്ടി നിശ്ചിത പ്രതികരണങ്ങൾ നൽകുന്ന ഫേക്ക് മോഡലുകൾ സൃഷ്ടിക്കാൻ Mockito ഉപയോഗിക്കുക. ഇത് പരീക്ഷണം വേഗത്തിലും സൗജന്യത്തിലും നിശ്ചിതാനുസൃതവുമാക്കി മാറ്റുന്നു. +സംഭാഷണ ലોજിക്ക് ടെസ്റ്റ് ചെയ്യുമ്പോൾ, ഫേക്ക് മോഡലുകൾ സൃഷ്ടിക്കാൻ Mockito ഉപയോഗിക്കുക, അവ നിർവ്വചിച്ച സാദ്ധ്യതകളും മറുപടികളും നൽകുന്നു. ഇത് ടെസ്റ്റുകൾ വേഗത്തിലും സൗജന്യത്തിലും നിർണായകവുമാക്കുന്നു. Mock vs Real API Comparison -*പരിശോധനയ്ക്കായി മോക്കുകൾ ഏത് കൊണ്ട് മേൽപ്പെട്ടതാണ് എന്ന് കാണിക്കുന്ന താരതമ്യം: അവ വേഗത, സൗജന്യം, നിശ്ചിതാനുസൃതത എന്നിവ ഉറപ്പാക്കുന്നു, API കീകൾ ആവശ്യമായില്ല.* +*എന്തുകൊണ്ട് മോക്കുകൾ ഉത്തമം ആണെന്ന് കാണിക്കുന്ന താരതമ്യം: ലളിതം, സൗജന്യം, നിർണായകവും API കീ ആവശ്യമില്ല* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 ഉപയോക്തൃ + 3 എഐ സന്ദേശങ്ങൾ + assertThat(history).hasSize(6); // 3 ഉപഭോക്താവും 3 AI സന്ദേശങ്ങളും } } ``` + +ഈ മാതൃകം `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` ൽ കാണാം. മൂക്ക് എന്നാൽ consistent പ്രവർത്തനം ഉറപ്പാക്കും, അതിനാൽ മെമ്മറി മാനേജ്മെന്റ് ശരിയായിട്ടാണ് എന്നത് പരിശോധിക്കാം. -ഈ മാതൃക `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` എന്നിൽ കാണാനാകും. മോക്ക് സ്ഥിരമായ പെരുമാറ്റം ഉറപ്പാക്കുന്നതുകൊണ്ട് ഓർമ ജനം ശരിയായി പ്രവർത്തിക്കുന്നുണ്ടോ എന്ന് പരിശോധിക്കാം. +### മാതൃകം 3: സംഭാഷണ വേർതിരിച്ചിടൽ പരീക്ഷണം -### മാതൃക 3: സംഭാഷണ വേർതിരിച്ചുവയ്കൽ പരിശോധിക്കൽ - -സംഭാഷണ ഓർമ പല ഉപയോക്താക്കളെയും പൂട്ടി വേർതിരിച്ചുവയ്ക്കണം. ഈ ടെസ്റ്റ് സംഭാഷണങ്ങൾ പരസ്പരം കൺടെക്സ്‌റ്റ് മിശ്രിതമാകാതിരിക്കണമെന്ന് ഉറപ്പാക്കുന്നു. +സംഭാഷണ മെമ്മറി പല ഉപയോക്താക്കളെ വേർതിരിച്ച് സൂക്ഷിക്കണം. ഈ ടെസ്റ്റ് സംസാരങ്ങൾ പരസ്പരം മിശ്രിതമാകുന്നതില്ലെന്നു ഉറപ്പുവരുത്തുന്നു. Conversation Isolation -*വേണ്ടുന്ന അനുഭവം വേർതിരിച്ച് പകർത്തുന്നതാകാൻ ഓരോ ഉപയോക്താവിനും വേറിട്ട ഓർമ്മ സ്റ്റോറുകൾ ഉള്ളതായി കാണിക്കുന്ന സംഭാഷണ വേർതിരിച്ചുവയ്കൽ പരിശോധന* +*വ്യത്യസ്ത ഉപയോക്താക്കൾക്ക് സ്വകാര്യമായ മെമ്മറി സ്റ്റോറുകൾ കാണിക്കുന്ന സംഭാഷണ വേർതിരിച്ചു സൂക്ഷിക്കൽ പരിശോധന* ```java @Test @@ -249,16 +236,16 @@ void shouldIsolateConversationsByid() { assertThat(history2).hasSize(2); } ``` + +എല്ലാ സംഭാഷണത്തിനും സ്വതന്ത്ര ചരിത്രം നിലനിർത്തണം. പ്രൊഡക്ഷൻ സിസ്റ്റങ്ങളിൽ, ഇത് മൾട്ടി യൂസർ അപ്ലിക്കേഷനുകൾക്ക് അനിവാര്യമാണ്. -ഓരോ സംഭാഷണവും സ്വതന്ത്രമായ ചരിത്രം സൂക്ഷിക്കുന്നു. ഉത്പാദന സംവിധാനങ്ങളിൽ ഈ വേർതിരിച്ചുവയ്കൽ ബഹു-ഉപയോക്തൃ ആപ്ലിക്കേഷനുകളിൽ അനിവാര്യമാണ്. - -### മാതൃക 4: ഉപകരണങ്ങൾ സ്വതന്ത്രമായി പരിശോധിക്കൽ +### മാതൃകം 4: ഉപകരണങ്ങൾ സ്വതന്ത്രമായി ടെസ്റ്റ് ചെയ്യൽ -ഉപകരണങ്ങൾ AI കോൾ ചെയ്യാവുന്ന ഫംഗ്ഷനുകളാണ്. AI തീരുമാനങ്ങളെ ബാധിക്കാതെ അവ ശരിയായി പ്രവർത്തിക്കുന്നുണ്ടോ എന്ന് നേരിട്ട് പരിശോധിക്കുക. +ഉപകരണങ്ങൾ എഐ വിളിക്കാവുന്ന ഫംഗ്ഷനുകളാണ്. അവ എഐ തീരുമാനം സ്വാധീനിക്കാതെ ശരിയായി പ്രവർത്തിക്കുന്നുവെന്ന് നേരിട്ട് പരിശോധിക്കുക. Tools Testing -*AI കോൾ ഇല്ലാതെ മൊക്ക് ഉപകരണം പ്രവർത്തന ഉദാഹരണങ്ങൾ ഉപയോഗിച്ച് ബിസിനസ് ലജിക് ശരിയാണോ എന്ന് പരിശോധിക്കൽ* +*എഐ കോൾ ഇല്ലാതെ മൊക്ക് ഉപകരണം പ്രവർത്തനം പരിശോദിക്കുന്ന ബിസിനസ് ലൊജിക് പരിശോധിക്കൽ* ```java @Test @@ -280,16 +267,16 @@ void shouldDemonstrateToolChaining() { assertThat(conversionResult).containsPattern("71[.,]6°F"); } ``` + +`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` എന്ന ഫയലിലെ ഈ ടെസ്റ്റുകൾ AI ഇടപെടൽ കൂടാതെ ഉപകരണങ്ങളുടെ ലൊജിക് പരിശോധിക്കുന്നു. ചൈനിംഗ് ഉദാഹരണം ഒരു ഉപകരണത്തിന്റെ ഔട്ട്‌പുട്ട് മറ്റൊന്നിന്റെ ഇൻപുട്ടാകുന്നത് കാണിക്കുന്നു. -`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` യിൽ നിന്നുള്ള ഈ ടെസ്റ്റുകൾ AI പങ്കാളിത്തമില്ലാതെ ഉപകരണ ലജിക് പരിശോധിക്കുന്നു. ചൈനിങ് ഉദാഹരണം ഒരു ഉപകരണത്തിന്റെ ഔട്ട്പുട്ട് മറ്റൊന്നിന്റെ ഇൻപുട്ടായി എങ്ങനെ സേവിക്കും എന്നും കാണിക്കുന്നു. - -### മാതൃക 5: ഇൻ-മെമ്മറി RAG പരിശോധന +### മാതൃകം 5: ഇൻ-മെമ്മറി RAG ടെസ്റ്റിംഗ് -RAG സിസ്റ്റങ്ങൾ സാധാരണയായി വെക്റ്റർ ഡാറ്റാബേസുകളും എംബെഡിംഗ് സേവനങ്ങളും ആവശ്യപ്പെടുന്നു. ഇൻ-മെമ്മറി മാതൃക പുറത്തെ ആശ്രിതങ്ങളില്ലാതെ മുഴുവൻ പൈപ്പ്ലൈൻ പരീക്ഷിക്കാൻ അനുമതി നൽകുന്നു. +RAG സംവിധാനം സാധാരണയായി വെക്ടർ ഡാറ്റാബേസുകളും എംബെഡ്ഡിംഗ് സേവനങ്ങളും ആവശ്യപ്പെടുന്നു. ഇൻ-മെമ്മറി മാതൃകയിൽ മുഴുവൻ പൈപ്പ്‌ലൈൻ ബാഹ്യ ആശ്രിതങ്ങളില്ലാതെ ടെസ്റ്റ് ചെയ്യാം. In-Memory RAG Testing -*ഡാറ്റാബേസ് ആവശ്യപ്പെടാതെ ഡോക്യുമെന്റ് പാഴ്സിംഗ്, എംബെഡിംഗ് സ്റ്റോറേജ്, സാമ്യതാ തിരച്ചിൽ എന്നിവയുടെ ഇൻ-മെമ്മറി RAG പരിശോധന പ്രവാഹം* +*ഡാറ്റാബേസ് ആവശ്യമില്ലാതെ ഡോക്യുമെന്റ് പാഴ്‌സിംഗ്, എംബഡ്ഡിംഗ് സംഭരണം, സമാനതാ തിരയൽ എന്നിവയുള്ള ഇൻ മെമ്മറി RAG ടെസ്റ്റിംഗ് പ്രവൃത്തി പ്രക്രിയ* ```java @Test @@ -305,16 +292,16 @@ void testProcessTextDocument() { assertEquals("test.txt", result.segments().get(0).metadata().getString("filename")); } ``` + +`03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`-ൽ നിന്നുള്ള ഈ ടെസ്റ്റ് ഒരു ഡോക്യുമെന്റ് മെമ്മറിയിൽ സൃഷ്ടിച്ച് ചങ്ക് ചെയ്യലും മെറ്റാഡേറ്റ ഹാൻഡ്ലിംഗും പരിശോധിക്കുന്നു. -`03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` എന്നിടത്തു നിന്നുള്ള ഈ ടെസ്റ്റ് ഓർമ്മയിൽ ഒരു ഡോക്യുമെന്റ് സൃഷ്ടിച്ച് ചങ്കിംഗ്, മെറ്റഡേറ്റ എൻട്രികൾ ശരിയായി കൈകാര്യം ചെയ്യുന്നതായി പരിശോധിക്കുന്നു. +### മാതൃകം 6: MCP സംയോജിത ടെസ്റ്റിംഗ് -### മാതൃക 6: MCP ഇന്റഗ്രേഷൻ പരീക്ഷണം +MCP മോഡ്യൂൾ സ്റ്റ്ഡിയൊ ഉപയോഗിച്ച് മോഡൽ കോൺടക്റ്റ് പ്രോട്ടോക്കോൾ സംയോജനം ടെസ്റ്റ് ചെയ്യുന്നു. ഈ ടെസ്റ്റുകൾ നിങ്ങളുടെ അപ്ലിക്കേഷൻ MCP സർവറുമായി subprocess ആയി spawn ചെയ്ത് ആശയവിനിമയം നടത്താൻ കഴിയുന്നതായിരിക്കണം ഉറപ്പാക്കുന്നു. -MCP മോഡ്യൂൾ stdio ട്രാൻസ്പോർട്ട് ഉപയോഗിച്ച് മോഡൽ കോൺടെക്സ് പ്രോട്ടോക്കോൾ ഇന്റഗ്രേഷൻ പരിശോധനകൾ നടത്തുന്നു. ഈ ടെസ്റ്റുകൾ നിങ്ങളുടെ ആപ്ലിക്കേഷൻ MCP സർവറുകൾ subprocess ആയി സ്ഫോണ് ചെയ്യുകയും സംവദിക്കുകയും ചെയ്യാൻ കഴിയും എന്ന് ഉറപ്പാക്കുന്നു. +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java`-ലെ ടെസ്റ്റുകൾ MCP ക്ലയന്റ് പ്രവർത്തനം പരിശോധിക്കുന്നു. -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` എന്നിടത്തെ ടെസ്റ്റുകൾ MCP ക്ലയന്റിന്റെ പെരുമാറ്റം സ്ഥിരീകരിക്കുന്നു. - -**നടത്തുക:** +**ഓടിക്കുക:** **Bash:** ```bash @@ -325,39 +312,38 @@ cd 05-mcp && mvn test ```powershell cd 05-mcp; mvn --% test ``` + +## ടെസ്റ്റിംഗ് തത്വചിന്ത -## പരിശോധന തത്ത്വം - -നിങ്ങളുടെ കോഡ് പരിശോധിക്കുക, AI അല്ല. നിങ്ങളുടെ പരീക്ഷണങ്ങൾ പ്രോംപ്റ്റുകൾ എങ്ങനെ സൃഷ്ടിക്കപ്പെടുന്നു, ഓർമ്മ എങ്ങനെ കൈകാര്യം ചെയ്യുന്നു, ഉപകരണങ്ങൾ എങ്ങനെ പ്രവർത്തിക്കുന്നു എന്നിവ പരിശോധിച്ച് എഴുത്തു കോഡ് ശരിയാണെന്ന് ഉറപ്പാക്കണം. AI പ്രതികരണങ്ങൾ വ്യത്യസ്തമായിരിക്കും, അവ പരിശോധനാ പ്രസ്താവനകളിൽ ഉൾപ്പെടുത്തിക്കരുത്. പ്രോംപ്റ്റ് ടെംപ്ലേറ്റ് ശരിയാണോ എന്നു മാത്രം പരിശോധിക്കുക, AI ശരിയായ ഉത്തരമാണ് നൽകുകയോ എന്നു അവലോകനം ചെയ്യരുത്. +AI-യെല്ലാം അല്ല, നിങ്ങൾ എഴുതുന്നത് പരീക്ഷിക്കുക. നിങ്ങളുടെ ടെസ്റ്റുകൾ എഴുതുന്ന കോഡ് ശരിയാണോ എന്ന് ഉറപ്പാക്കണം — പ്രൊംപ്റ്റുകൾ എങ്ങനെ നിർമ്മിക്കുന്നത്, മെമ്മറി എങ്ങനെ മാനേജ് ചെയ്യുന്നത്, ഉപകരണങ്ങൾ എങ്ങനെ പ്രവർത്തിക്കുന്നു എന്നിങ്ങനെ പരിശോധിക്കുക. AI മറുപടികൾ വ്യത്യസ്തമാണ്, അവ പ്രൂഫ് അനുവദിക്കരുത്. നിങ്ങളുടെ പ്രൊംപ്റ്റ് ടെംപ്ലേറ്റ് ശരിയായി വേരിയബിളുകൾ മാറ്റിസ്ഥാപിക്കുന്നുണ്ടോ എന്ന് ചോദിക്കുക, AI ശരിയായ മറുപടി നൽകുന്നുവോ എന്ന് അല്ല. -ഭാഷാ മോഡലുകൾക്ക് മോക്കുകൾ ഉപയോഗിക്കുക. അവ പുറം ആശ്രിതങ്ങളാണ്, മന്ദഗതിയുള്ളവ, ചെലവേറിയവ, അനിശ്ചിതപരമായവ. മോക്കിംഗ് പരീക്ഷണങ്ങൾ സെക്കന്റുകൾക്ക് പകരം അല്പം മില്ലി സെക്കന്റുകളിൽ വേഗത്തിലും സൗജന്യത്തിലും, ഒരുപോലാനുള്ള ഫലത്തോടെ നടത്താൻ സഹായിക്കുന്നു. +ഭാഷാ മോഡലുകൾക്കായി മോക്കുകൾ ഉപയോഗിക്കുക. അവ ബാഹ്യ ആശ്രിതങ്ങളാണ്, സ്ലോ ആയ, ചെലവുള്ള, നിരണായകമല്ലാത്തവ. മോക്കിംഗ് ടെസ്റ്റുകൾ സെക്കൻഡുകൾക്കുപകരം മില്ലിസെക്കൻഡ് വേഗതയിൽ, സൗജന്യമായി API ചെലവുകൾ ഇല്ലാതെ, എല്ലാ സമയം ഒരേ ഫലം നൽകിയാണ് നടത്തുന്നത്. -പരീക്ഷണങ്ങൾ സ്വതന്ത്രമാക്കുക. ഓരോ പരീക്ഷണവും സ്വന്തം ഡാറ്റ ഒരുക്കണം, മറ്റുള്ള പരീക്ഷണങ്ങളിൽ ആശ്രയിച്ചിരിക്കരുത്, പരീക്ഷണം കഴിഞ്ഞ് സ്വയം ക്ലീൻഅപ്പ് ചെയ്‌തെടുക്കണം. പരീക്ഷണങ്ങൾ എദ്ദേഹയുമായി പ്രവർത്തിക്കുന്നു. +ടെസ്റ്റുകൾ സ്വതന്ത്രമാക്കുക. ഓരോ ടെസ്റ്റ് വേണ്ടപ്പെട്ട ഡാറ്റയും സ്വയം സജ്ജമാക്കണം, മറ്റുള്ള ടെസ്റ്റുകളിൽ ആശ്രയിക്കരുത്, ടെസ്റ്റ് കഴിഞ്ഞ് സ്വയം ക്ലീൻ ആയിരിക്കണം. ഓട്ടോക്രമണത്തിനെങ്കിലും ടെസ്റ്റുകൾ വിജയിക്കണം. -സന്തോഷകരമായ വഴിയभन्दा അപ്പുറം മൂല്യങ്ങൾ പരീക്ഷിക്കുക. ശൂന്യ ഇൻപുട്ടുകൾ, വളരെ വലുതായ ഇൻപുട്ടുകൾ, പ്രത്യേക ചിഹ്നങ്ങൾ, അസാധുവായ പാരാമീറ്ററുകൾ, അതിരുകൾ തുടങ്ങിയവ പരിശോധിക്കുക. ഇവ സാധാരണ ഉപയോഗത്തിൽ കാണാത്ത പിശകുകൾ കണ്ടെത്താൻ സഹായിക്കാം. +ഹാപ്പി പാതയ്ക്ക് പുറമെ എഡ്ജ് കേസുകൾ ടെസ്റ്റ് ചെയ്യുക. ശൂന്യമായ ഇൻപുട്ടുകൾ, വലിയ ഇൻപുട്ടുകൾ, പ്രത്യേക അക്ഷരങ്ങൾ, അസാധുവായ പാരാമീറ്ററുകൾ, അതിരുകൾ അവസരങ്ങൾ എന്നിവ പരീക്ഷിക്കുക. ഇത് സാധാരണ ഉപയോഗം പുറത്തുപറയാത്ത പിശകുകൾ കണ്ടെത്താനാകും. -വിവരണപരമായ പേരുകൾ ഉപയോഗിക്കുക. `shouldMaintainConversationHistoryAcrossMultipleMessages()` എന്നത് `test1()`നെക്കാൾ നല്ലത്. ആദ്യത്തെ പേര് പരീക്ഷണം എന്താണെന്ന് സ്പഷ്ടമായി പറയുന്നു, പരാജയങ്ങൾ ന് ഡീബഗ്ഗ് ചെയ്യുന്നത് എളുപ്പമാക്കുന്നു. +വിവരണാത്മക നാമങ്ങൾ ഉപയോഗിക്കുക. `shouldMaintainConversationHistoryAcrossMultipleMessages()` എന്നത് `test1()`ക്കൊപ്പം താരതമ്യം ചെയ്യുക. മുമ്പുള്ളത് എന്താണെന്ന് വ്യക്തമാക്കുന്നു, പരാജയങ്ങൾ ഡീബഗ് ചെയ്യാൻ സഹായിക്കുന്നു. -## അടുത്ത ഘട്ടങ്ങൾ +## അടുത്ത ചുവട് -ഇപ്പോൾ നിങ്ങൾ പരീക്ഷണ മാതൃകകളും മനസ്സിലാക്കിയതിനാൽ ഓരോ മോഡ്യൂളിലും കൂടുതൽ കാൽവെക്കുക: +ടെസ്റ്റിംഗ് മാതൃകകൾ മനസ്സിലാക്കിയതിനു ശേഷം ഓരോ മോഡ്യൂളിലും ആഴത്തിൽ നോക്കാം: -- **[00 - വേഗത്തിലുള്ള തുടക്കം](../00-quick-start/README.md)** - പ്രോംപ്റ്റ് ടെംപ്ലേറ്റ് അടിസ്ഥാനങ്ങൾ ആരംഭിക്കുക -- **[01 - പരിചയം](../01-introduction/README.md)** - സംഭാഷണ ഓർമ്മ കൈകാര്യം ചെയ്യൽ പഠിക്കുക -- **[02 - പ്രോംപ്റ്റ് എഞ്ചിനീയറിംഗ്](../02-prompt-engineering/README.md)** - GPT-5.2 പ്രോംപ്റ്റിംഗ് മാതൃകകൾ അറിയുക -- **[03 - RAG](../03-rag/README.md)** - റീട്രീവൽ-ഓഗ്‌മെന്റഡ് ജനറേഷന്റെ സിസ്റ്റങ്ങൾ നിർമ്മിക്കുക -- **[04 - ഉപകരണങ്ങൾ](../04-tools/README.md)** - ഫംഗ്ഷൻ കോൾ ചെയ്യലും ഉപകരണം പരമ്പരകളും നടപ്പിലാക്കുക -- **[05 - MCP](../05-mcp/README.md)** - മോഡൽ കോൺടെക്സ് പ്രോട്ടോക്കോൾ ഇന്റഗ്രേറ്റ് ചെയ്യുക +- **[01 - പരിചയം](../01-introduction/README.md)** - സംഭാഷണ മെമ്മറി മാനേജ്മെന്റ് പഠിക്കുക +- **[02 - പ്രൊംപ്റ്റ് എൻജിനീയറിംഗ്](../02/prompt-engineering/README.md)** - GPT-5.2 പ്രൊംപ്റ്റിംഗ് മാതൃകകൾ റൂറുക +- **[03 - RAG](../03-rag/README.md)** - റെട്രീവൽ-ഓગുമെന്റഡ് ജനറേഷൻ системы നിർമ്മിക്കുക +- **[04 - ഉപകരണങ്ങൾ](../04-tools/README.md)** - ഫംഗ്ഷൻ കോൾ ചെയ്യലും ഉപകരണ ചൈനിംഗും നടപ്പിലാക്കുക +- **[05 - MCP](../05-mcp/README.md)** - മോഡൽ കോൺടക്സ് പ്രോട്ടോക്കോൾ സംയോജിപ്പിക്കുക -ഓരോ മോഡ്യൂളിന്റെ README ഇവിടെ പരിശോധിക്കുന്ന ആശയങ്ങൾ വിശദമായി വിശദീകരിക്കുന്നു. +ഓരോ മോഡ്യൂളിന്റെയും README ഇവിടെ പരിശോധിച്ച ആശയങ്ങളുടെ വിശദീകരണം നൽകുന്നു. --- -**നാവിഗേഷൻ:** [← മെയിനിലേക്കു മടങ്ങുക](../README.md) +**വഴികാട്ടി:** [← പ്രധാനത്തിലേക്ക് മടങ്ങാൻ](../README.md) --- -**പരിശോധനാ കുറിപ്പ്**: -ഈ രേഖ AI വിവർത്തന സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് വിവർത്തനം ചെയ്തതാണ്. ഞങ്ങൾ ശരിയായ വിവർത്തനത്തിനായി ശ്രമിക്കുന്നു എങ്കിലും, യന്ത്രം ചെയ്ത വിവർത്തനങ്ങളിൽ പിഴവുകളും അഥവാ തെറ്റുകളും ഉണ്ടാകാമെന്ന് ദയവായി ശ്രദ്ധിക്കുക. യഥാർത്ഥ രേഖ അതിന്റെ മാതൃഭാഷയിൽ തന്നെ അതിൻറെ പ്രാമാണിക ഉറവിടമായി കണക്കാക്കണം. ഏറ്റവും നിർണായകമായ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ വിവർത്തനം നിർദ്ദേശിക്കുന്നു. ഈ വിവർത്തനത്തിന്റെ ഉപയോഗം മൂലം ഉണ്ടാകുന്ന ഏതെങ്കിലും തെറ്റിദ്ധാരണകൾക്കോ അല്ലെങ്കിൽ വ്യാഖ്യാന പിശക്‌സിനും ഞങ്ങൾ ഉത്തരവാദികളല്ല. +**അറിയിപ്പ്**: +ഈ രേഖ AI പരിഭാഷാ സേവനം [Co-op Translator](https://github.com/Azure/co-op-translator) ഉപയോഗിച്ച് പരിഭാഷപ്പെടുത്തിയതാണ്. ഞങ്ങൾ കൃത്യതയ്ക്കായി ശ്രമിക്കുന്നുവെങ്കിലും, ഓട്ടോമേറ്റഡ് പരിഭാഷകളിൽ പിഴവുകൾ അല്ലെങ്കിൽ തെറ്റായ വിവരങ്ങൾ ഉണ്ടാകാൻ സാധ്യതയുണ്ട്. അതിന്റെ സ്വാഭാവിക ഭാഷയിലുള്ള അസൽ രേഖയാണ് പ്രാമാണികമായ ഉറവിടമായി പരിഗണിക്കേണ്ടത്. നിർണായകമായ വിവരങ്ങൾക്ക്, പ്രൊഫഷണൽ മനുഷ്യ പരിഭാഷ ശുപാർശ ചെയ്യുന്നു. ഈ പരിഭാഷ ഉപയോഗിച്ച് ഉണ്ടാകുന്ന തെറ്റിദ്ധാരണകൾ അല്ലെങ്കിൽ തെറ്റായ വ്യാഖ്യാനങ്ങൾക്കായി ഞങ്ങൾ ഉത്തരവാദികളല്ല. \ No newline at end of file diff --git a/translations/mr/.co-op-translator.json b/translations/mr/.co-op-translator.json index 06bdb7df8..bef5d9c13 100644 --- a/translations/mr/.co-op-translator.json +++ b/translations/mr/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "mr" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T21:08:36+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T13:15:13+00:00", "source_file": "01-introduction/README.md", "language_code": "mr" }, @@ -18,20 +18,20 @@ "language_code": "mr" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T21:11:06+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T13:11:22+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "mr" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T21:12:24+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T13:14:28+00:00", "source_file": "03-rag/README.md", "language_code": "mr" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:00:52+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T13:13:23+00:00", "source_file": "04-tools/README.md", "language_code": "mr" }, @@ -54,8 +54,8 @@ "language_code": "mr" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:47:34+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T13:10:08+00:00", "source_file": "README.md", "language_code": "mr" }, @@ -72,14 +72,14 @@ "language_code": "mr" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T21:15:27+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T13:11:47+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "mr" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T21:16:11+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T13:12:19+00:00", "source_file": "docs/TESTING.md", "language_code": "mr" } diff --git a/translations/mr/00-quick-start/README.md b/translations/mr/00-quick-start/README.md deleted file mode 100644 index 1b878cf39..000000000 --- a/translations/mr/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: जलद प्रारंभ - -## सामग्री सूची - -- [परिचय](../../../00-quick-start) -- [LangChain4j म्हणजे काय?](../../../00-quick-start) -- [LangChain4j अवलंबित्व](../../../00-quick-start) -- [पूर्वापेक्षिता](../../../00-quick-start) -- [सेटअप](../../../00-quick-start) - - [1. तुमचा GitHub टोकन मिळवा](../../../00-quick-start) - - [2. तुमचा टोकन सेट करा](../../../00-quick-start) -- [उदाहरणे चालवा](../../../00-quick-start) - - [1. मूलभूत संवाद](../../../00-quick-start) - - [2. प्रॉम्प्ट नमुने](../../../00-quick-start) - - [3. फंक्शन कॉलिंग](../../../00-quick-start) - - [4. दस्तऐवज प्रश्नोत्तरे (सोपे RAG)](../../../00-quick-start) - - [5. जबाबदार AI](../../../00-quick-start) -- [प्रत्येक उदाहरण काय दर्शवते](../../../00-quick-start) -- [पुढील टप्पे](../../../00-quick-start) -- [समस्या निवारण](../../../00-quick-start) - -## परिचय - -हा जलद प्रारंभ तुम्हाला LangChain4j सह शक्य तितक्या लवकर सुरू होण्यास मदत करतो. यामध्ये LangChain4j आणि GitHub मॉडेल्ससह AI अनुप्रयोग तयार करण्याच्या मूलभूत तत्त्वांचा समावेश आहे. पुढील मॉड्यूल्समध्ये तुम्ही Azure OpenAI आणि GPT-5.2 वर स्विच कराल आणि प्रत्येक संकल्पनेत अधिक खोलवर जाल. - -## LangChain4j म्हणजे काय? - -LangChain4j हा एक Java लायब्ररी आहे जो AI-शक्तीने चालणारे अनुप्रयोग तयार करणे सोपे बनवतो. HTTP क्लायंट्स आणि JSON पार्सिंग हाताळण्याऐवजी, तुम्ही स्वच्छ Java API सह काम करता. - -LangChain मधील "चेन" म्हणजे अनेक घटक एकत्र जोडणे - तुम्ही प्रॉम्प्टला मॉडेलशी, नंतर पार्सरशी किंवा एकाधिक AI कॉल्स एकमेकांशी जोडू शकता जिथे एक आउटपुट पुढील इनपुटसाठी वापरला जातो. हा जलद प्रारंभ मूलभूत गोष्टींकडे लक्ष केंद्रित करतो, जास्त गुंतागुंतीच्या चेनवर जाण्यापूर्वी. - -LangChain4j Chaining Concept - -*LangChain4j मधील घटक जोडणे - शक्तिशाली AI कार्यप्रवाह तयार करण्यासाठी ब्लॉक जोडले जातात* - -आपण तीन मुख्य घटक वापरणार आहोत: - -**ChatModel** - AI मॉडेलशी संवाद साधण्यासाठी इंटरफेस. `model.chat("prompt")` कॉल करा आणि प्रतिसाद स्ट्रिंग मिळवा. आपण `OpenAiOfficialChatModel` वापरतो जे GitHub मॉडेल्ससारख्या OpenAI-तंत्रज्ञानसह कार्य करतो. - -**AiServices** - टाइप-सेफ AI सेवा इंटरफेस तयार करतो. पद्धती परिभाषित करा, त्यावर `@Tool` अॅनोटेट करा, आणि LangChain4j व्यवस्थापन करते. AI आवश्यक तेव्हा आपोआप Java पद्धती कॉल करते. - -**MessageWindowChatMemory** - संवादाची मागील इतिहास सांभाळते. याशिवाय प्रत्येक विनंती स्वतंत्र असते. यासहित AI पूर्वीच्या संदेशांची आठवण ठेवतो आणि अनेक वळणांमध्ये संदर्भ जतन करतो. - -LangChain4j Architecture - -*LangChain4j आर्किटेक्चर - तुमच्या AI अनुप्रयोगांना सशक्त करण्यासाठी मुख्य घटक एकत्रित काम करतात* - -## LangChain4j अवलंबित्व - -हा जलद प्रारंभ [`pom.xml`](../../../00-quick-start/pom.xml) मध्ये तीन Maven अवलंबित्वे वापरतो: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` मॉड्यूल `OpenAiOfficialChatModel` वर्ग पुरवते जो OpenAI-सुसंगत API शी जोडतो. GitHub मॉडेल्स हेच API फॉरमॅट वापरतात, त्यामुळे कोणत्याही विशेष अडॅप्टरची गरज नाही - फक्त बेस URL `https://models.github.ai/inference` कडे निर्देश करा. - -`langchain4j-easy-rag` मॉड्यूल आपोआप दस्तऐवज विभागणी, एम्बेडिंग आणि पुनर्प्राप्ती प्रदान करते जेणेकरून तुम्ही प्रत्येक टप्पा मॅन्युअली कॉन्फिगर न करता RAG अनुप्रयोग तयार करू शकता. - -## पूर्वापेक्षिता - -**डेव्ह कंटेनर वापरत आहात?** Java आणि Maven आधीच स्थापित आहेत. तुम्हाला फक्त GitHub Personal Access Token ची आवश्यकता आहे. - -**स्थानिक विकासासाठी:** -- Java 21+, Maven 3.9+ -- GitHub व्यक्‍तिक टोकन (खालील सूचना पहा) - -> **टिप:** हा मॉड्यूल GitHub मॉडेल्समधून `gpt-4.1-nano` वापरतो. कोडमधील मॉडेल नाव बदलू नका - हे GitHub उपलब्ध मॉडेल्ससाठी कॉन्फिगर केलेले आहे. - -## सेटअप - -### 1. तुमचा GitHub टोकन मिळवा - -1. [GitHub सेटिंग्ज → Personal Access Tokens](https://github.com/settings/personal-access-tokens) येथे जा -2. "Generate new token" क्लिक करा -3. वर्णनात्मक नाव सेट करा (उदा. "LangChain4j Demo") -4. समाप्ती सेट करा (7 दिवस शिफारस केली) -5. "Account permissions" मध्ये "Models" शोधा आणि "Read-only" सेट करा -6. "Generate token" क्लिक करा -7. तुमचा टोकन कॉपी करा आणि जतन करा - तो पुन्हा दिसणार नाही - -### 2. तुमचा टोकन सेट करा - -**पर्याय 1: VS Code वापरून (शिफारस केली)** - -VS Code वापरत असल्यास, प्रकल्प मूळामध्ये `.env` फाइलमध्ये तुमचा टोकन जोडा: - -जर `.env` फाइल अस्तित्वात नसेल, तर `.env.example` ची कॉपी `.env` मध्ये करा किंवा नवीन `.env` फाइल तयार करा. - -**उदाहरण `.env` फाइल:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env मध्ये -GITHUB_TOKEN=your_token_here -``` - -नंतर तुम्ही एक्सप्लोररमध्ये कोणत्याही डेमो फाईलवर (उदा. `BasicChatDemo.java`) उजवे-क्लिक करून **"Run Java"** निवडू शकता किंवा रन आणि डिबग पॅनेलमधून लॉन्च कॉन्फिगरेशन्स वापरू शकता. - -**पर्याय 2: टर्मिनल वापरून** - -टोकन पर्यावरणीय चल म्हणून सेट करा: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## उदाहरणे चालवा - -**VS Code वापरत असल्यास:** एक्सप्लोररमधील कोणत्याही डेमो फाईलवर उजवे-क्लिक करा आणि **"Run Java"** निवडा, किंवा रन आणि डिबग पॅनेलमधून लॉन्च कॉन्फिगरेशन्स वापरा (पूर्वी तुमचा टोकन `.env` फाइलमध्ये जोडलेला असावा). - -**Maven वापरत असल्यास:** पर्यायीरित्या, तुम्ही कमांड लाइनवरून चालवू शकता: - -### 1. मूलभूत संवाद - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. प्रॉम्प्ट नमुने - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -शून्य-दावा, कमी-मधे, विचारांची साखळी आणि भूमिका-आधारित प्रॉम्प्टिंग दाखवते. - -### 3. फंक्शन कॉलिंग - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI आवश्यक तेव्हा आपोआप तुमच्या Java पद्धती कॉल करतो. - -### 4. दस्तऐवज प्रश्नोत्तरे (सोपे RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -आपल्या दस्तऐवजांविषयी प्रश्न विचारा Easy RAG वापरून ज्यामध्ये आपोआप एम्बेडिंग आणि पुनर्प्राप्ती होते. - -### 5. जबाबदार AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -पहा AI सुरक्षा फिल्टर्स चुकीचा किंवा हानिकारक सामग्री कशी ब्लॉक करतात. - -## प्रत्येक उदाहरण काय दर्शवते - -**मूलभूत संवाद** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -इथेून सुरू करा आणि LangChain4j सोप्या स्वरूपात पाहा. तुम्ही `OpenAiOfficialChatModel` तयार कराल, `.chat()` सह प्रॉम्प्ट पाठवाल आणि प्रतिसाद मिळवाल. यामुळे पाया समजतो: कस्टम एंडपॉइंट्स आणि API कींसह मॉडेल्स कसे प्रारंभ करायचे. या नमुन्याचे समजल्यावर, सर्व काही यावर आधारलेले आहे. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चॅटसह प्रयत्न करा:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) उघडा आणि विचार करा: -> - "या कोडमध्ये GitHub मॉडेल्सवरून Azure OpenAI वर कसे बदलायचे?" -> - "OpenAiOfficialChatModel.builder() मध्ये कोणती इतर पॅरामीटर्स सेट करू शकतो?" -> - "पूर्ण प्रतिसादाची वाट पाहण्याऐवजी स्ट्रीमिंग प्रतिसाद कसे जोडायचे?" - -**प्रॉम्प्ट इंजिनिअरिंग** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -आता तुम्हाला मॉडेलशी बोलायला येते, तर चला पाहूयात तुम्ही त्याला काय सांगता. या डेमोत समान मॉडेल सेटअप वापरले आहे पण पाच वेगवेगळे प्रॉम्प्टिंग नमुने दाखवले आहेत. थेट सूचनांसाठी शून्य-दावा प्रॉम्प्ट, उदाहरणांमधून शिकणारे कमी-मधे प्रॉम्प्ट, कारणसंगती टप्पे उघड करणारे विचारसाखळी प्रॉम्प्ट, आणि संदर्भ सेट करणारे भूमिका-आधारित प्रॉम्प्ट यांचा प्रयत्न करा. तुम्हाला दिसेल की तुम्ही तुमच्या विनंती कशी मांडता त्यानुसार समान मॉडेल कसे वेगवेगळे उत्तर देते. - -हा डेमो प्रॉम्प्ट टेम्पलेट्स देखील दाखवतो, जे चांगल्या पुनर्वापरयोग्य प्रॉम्प्टसाठी शक्तिशाली मार्ग आहे ज्यात चल (व्हेरिएबल) असतात. -खालील उदाहरणात LangChain4j `PromptTemplate` वापरून व्हेरिएबल भरणे दाखवले आहे. AI दिलेल्या गंतव्य आणि क्रियावर आधारित उत्तर देईल. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चॅटसह प्रयत्न करा:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) उघडा आणि विचार करा: -> - "शून्य-दावा आणि कमी-मधे प्रॉम्प्टिंगमध्ये काय फरक आहे, आणि कधी काय वापरावे?" -> - "उष्णता पॅरामीटर मॉडेलच्या प्रतिसादांवर कसा परिणाम करतो?" -> - "प्रॉम्प्ट इंजेक्शन हल्ले टाळण्यासाठी उत्पादनात काही तंत्र कसे वापरू शकतो?" -> - "सामान्य नमुन्यांसाठी पुनर्वापरयोग्य PromptTemplate वस्तू कशा तयार करायच्या?" - -**टूल इंटिग्रेशन** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -येथे LangChain4j शक्तिशाली होते. तुम्ही `AiServices` वापरून एक AI सहाय्यक तयार कराल जो तुमच्या Java पद्धती कॉल करू शकतो. फक्त पद्धतींवर `@Tool("description")` अॅनोटेट करा आणि LangChain4j बाकी सर्व व्यवस्थापित करते - AI वापरकर्त्याच्या विनंतीनुसार कोणते टूल वापरायचे ठरवतो. यामुळे फंक्शन कॉलिंगची झलक मिळते, जी AI कडे क्रिया घेण्याची क्षमता देते, फक्त प्रश्नांची उत्तरे देण्याऐवजी. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चॅटसह प्रयत्न करा:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) उघडा आणि विचार करा: -> - "@Tool अॅनोटेशन कसे कार्य करते आणि LangChain4j त्यास मागून कसे हाताळते?" -> - "AI अनेक टूल्स एकमेकांनंतर कॉल करून क्लिष्ट समस्या सोडवू शकतो का?" -> - "जर टूलने अपवाद फेकला तर काय होते - त्रुटी कशी हाताळायची?" -> - "या कॅल्क्युलेटर उदाहरणाऐवजी वास्तविक API कसे इंटिग्रेट करायचे?" - -**दस्तऐवज प्रश्नोत्तरे (सोपे RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -येथे तुम्हाला RAG (पुनर्प्राप्ती-समृद्ध जनरेशन) LangChain4j च्या "Easy RAG" पद्धतीने दाखवेल. दस्तऐवज लोड होतात, आपोआप विभागले जातात आणि एम्बेड केले जातात स्मृतीच्या संचयात, नंतर एक कंटेंट रिट्रीव्हर विचारणी वेळी AI ला संबंधित भाग पुरवतो. AI तुमच्या दस्तऐवजांवर आधारित उत्तर देते, त्याच्या सामान्य ज्ञानावर नाही. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चॅटसह प्रयत्न करा:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) उघडा आणि विचार करा: -> - "RAG AI भास टाळण्यास कसे मदत करते, मॉडेलच्या प्रशिक्षण डेटाच्या वापराच्या तुलनेत?" -> - "या सोपनंतर आणि सानुकूल RAG पाईपलाइनमध्ये काय फरक आहे?" -> - "कसे मी याला अनेक दस्तऐवज व मोठ्या ज्ञानसंचासाठी परिचालनक्षम करू?" - -**जबाबदार AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -गभरण्या सुरक्षेसाठी संरक्षण तयार करा. हा डेमो दोन संरक्षण थर दाखवतो जे एकत्र काम करतात: - -**भाग 1: LangChain4j इनपुट गार्डरेइल्स** - LLM पर्यंत पोहोचण्यापूर्वी धोकादायक प्रॉम्प्ट्स ब्लॉक करा. निषिद्ध कीवर्ड्स किंवा नमुन्यांसाठी सानुकूल गार्डरेइल्स तयार करा. हे तुमच्या कोडमध्ये चालतात, त्यामुळे ते जलद आणि विनामूल्य आहेत. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**भाग 2: प्रदाता सुरक्षा फिल्टर्स** - GitHub मॉडेल्समध्ये अंतर्निर्मित फिल्टर्स आहेत जे तुमच्या गार्डरेइल्स कमी पडतील ते पकडतात. तुम्हाला कडक प्रतिबंध (HTTP 400 त्रुटी) आणि नम्र नकारात्मक प्रतिसाद दिसतील जिथे AI सभ्यपणे नकार देतो. - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चॅटसह प्रयत्न करा:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) उघडा आणि विचार करा: -> - "InputGuardrail म्हणजे काय आणि स्वतःचे कसे तयार करायचे?" -> - "कडक प्रतिबंध आणि सौम्य नकार यामध्ये काय फरक आहे?" -> - "गार्डरेइल्स आणि प्रदाता फिल्टर्स एकत्र का वापरावेत?" - -## पुढील टप्पे - -**पुढील मॉड्यूल:** [01-परिचय - LangChain4j सह प्रारंभ](../01-introduction/README.md) - ---- - -**दिशा:** [← मुख्य पृष्ठाकडे परत](../README.md) | [पुढे: Module 01 - परिचय →](../01-introduction/README.md) - ---- - -## समस्या निवारण - -### पहिल्यांदाच्या Maven बिल्ड - -**समस्या:** प्रारंभिक `mvn clean compile` किंवा `mvn package` ला बराच वेळ (10-15 मिनिटे) लागू शकतो - -**कारण:** Maven ला सर्व प्रकल्प अवलंबित्वे (Spring Boot, LangChain4j लायब्ररी, Azure SDKs, इ.) प्रथम बिल्डवर डाउनलोड करावे लागतात. - -**उपाय:** हे सामान्य वर्तन आहे. पुढील बिल्ड्स जास्त जलद होतील कारण अवलंबित्वे स्थानिकरीत्या कॅश केली जातात. डाउनलोड वेळ तुमच्या नेटवर्क स्पीडवर अवलंबून असते. - -### PowerShell Maven कमांड सिंटॅक्स - -**समस्या:** Maven कमांड्स `Unknown lifecycle phase ".mainClass=..."` या त्रुटीने अयशस्वी होतात -**कारण**: PowerShell `=` या चिन्हाला व्हेरिएबल असाइनमेंट ऑपरेटर म्हणून समजते, ज्यामुळे Maven प्रॉपर्टी सिंटॅक्स तुटतो - -**सोल्यूशन**: Maven कमांडपूर्वी stop-parsing ऑपरेटर `--%` वापरा: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` ऑपरेटर PowerShell ला सांगतो की Maven कडे उरलेले सर्व अर्ग्युमेंट्स अक्षरशः पाठवायचे आहेत, व्याख्या न करता. - -### Windows PowerShell Emoji प्रदर्शन - -**समस्या**: PowerShell मध्ये AI प्रतिसादांमध्ये इमोजीऐवजी कचर्‍या अक्षरे (उदा., `????` किंवा `â??`) दिसतात - -**कारण**: PowerShell ची डीफॉल्ट एनकोडिंग UTF-8 इमोजींसाठी समर्थन करत नाही - -**सोल्यूशन**: Java ऍप्लिकेशन चालण्यापूर्वी हा कमांड चालवा: -```cmd -chcp 65001 -``` - -यामुळे टर्मिनलमध्ये UTF-8 एनकोडिंग लागू होते. पर्यायीरित्या, Windows Terminal वापरा ज्यामध्ये युनिकोड समर्थन अधिक चांगले आहे. - -### API कॉल्स डीबगिंग - -**समस्या**: Authentication त्रुटी, रेट लिमिट्स, किंवा AI मॉडेलकडून अनपेक्षित प्रतिसाद - -**सोल्यूशन**: उदाहरणांमध्ये `.logRequests(true)` आणि `.logResponses(true)` समाविष्ट आहेत ज्यामुळे API कॉल्स कन्सोलमध्ये दाखवले जातात. यामुळे authentication त्रुटी, रेट लिमिट्स किंवा अनपेक्षित प्रतिसाद शोधण्यात मदत होते. प्रॉडक्शनमध्ये या फ्लॅग्स काढा ज्यामुळे लॉगची गडबड कमी होईल. - ---- - - -**अस्वीकरण**: -हे दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) वापरून भाषांतरित केले आहे. आम्ही अचूकतेसाठी प्रयत्न करतो, तरी कृपया लक्षात ठेवा की स्वयंचलित भाषांतरांमध्ये चुका किंवा अचूकतेचे अभाव असू शकतात. मूळ दस्तऐवज त्याच्या स्वदेशी भाषेत अधिकृत स्रोत मानला जावा. महत्त्वाच्या माहितीसाठी व्यावसायिक मानवी भाषांतर करण्याचा सल्ला दिला आहे. या भाषांतराच्या वापरामुळे उद्भवलेल्या कोणत्याही गैरसमजुती किंवा चुकीच्या अर्थलागी आम्ही जबाबदार नाही. - \ No newline at end of file diff --git a/translations/mr/01-introduction/README.md b/translations/mr/01-introduction/README.md index 64c7bd8aa..6c816cfb7 100644 --- a/translations/mr/01-introduction/README.md +++ b/translations/mr/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j सह सुरूवात करणे - -## मजकूर सूची - -- [व्हिडिओ मार्गदर्शन](../../../01-introduction) -- [आपण काय शिकाल](../../../01-introduction) -- [पूर्वअट](../../../01-introduction) -- [मूलभूत समस्या समजून घेणे](../../../01-introduction) -- [टोकन समजून घेणे](../../../01-introduction) -- [मेमरी कशी कार्य करते](../../../01-introduction) -- [हे LangChain4j कसे वापरते](../../../01-introduction) -- [Azure OpenAI इन्फ्रास्ट्रक्चर तैनात करा](../../../01-introduction) -- [अ‍ॅप्लिकेशन स्थानिकपणे चालवा](../../../01-introduction) -- [अ‍ॅप्लिकेशन वापरणे](../../../01-introduction) - - [स्टेटलेस चॅट (डावी पॅनेल)](../../../01-introduction) - - [स्टेटफुल चॅट (उजवी पॅनेल)](../../../01-introduction) -- [पुढील पाऊले](../../../01-introduction) +# Module 01: LangChain4j सह प्रारंभ करणे + +## अनुक्रमणिका + +- [व्हिडिओ मार्गदर्शन](#व्हिडिओ-मार्गदर्शन) +- [आपण काय शिकाल](#आपण-काय-शिकाल) +- [पूर्वअट](#पूर्वअट) +- [मूलभूत समस्येचा समज](#मूलभूत-समस्येचा-समज) +- [टोकन समजणे](#टोकन्स-समजून-घेणे) +- [मेमरी कशी काम करते](#मेमरी-कशी-काम-करते) +- [LangChain4j कसे वापरते](#langchain4j-कसे-वापरते) +- [Azure OpenAI इन्फ्रास्ट्रक्चर तैनात करा](#azure-openai-इन्फ्रास्ट्रक्चर-तैनात-करा) +- [अर्ज स्थानिकपणे चालवा](#अर्ज-स्थानिकपणे-चालवा) +- [अर्जाचा वापर कसा करावा](#अर्जाचा-वापर-कसा-करावा) + - [स्टेटलेस चॅट (डावा पॅनेल)](#स्टेटलेस-चॅट-डावा-पॅनेल) + - [स्टेटफुल चॅट (उजवा पॅनेल)](#स्टेटफुल-चॅट-उजवा-पॅनेल) +- [पुढील टप्पे](#पुढील-टप्पे) ## व्हिडिओ मार्गदर्शन -हा लाईव्ह सत्र पाहा ज्यात या मोड्युलसह सुरूवात कशी करावी हे समजावले आहे: +हा थेट सत्र पहा जे तुम्हाला या मॉड्युलसह प्रारंभ करण्याचे मार्गदर्शन करते: -LangChain4j सह सुरूवात - लाईव्ह सत्र +Getting Started with LangChain4j - Live Session ## आपण काय शिकाल -त्वरित सुरुवात मध्ये, आपण GitHub मॉडेल्स वापरून प्रॉम्प्ट पाठवले, टूल्स कॉल केले, RAG पाईपलाइन तयार केली आणि गार्डरेल टेस्ट केली. त्या डेमोंनी काय शक्य आहे ते दाखवले — आता आपण Azure OpenAI आणि GPT-5.2 कडे वळतो आणि उत्पादन शैलीतील अ‍ॅप्लिकेशन्स तयार करण्यास सुरुवात करतो. हा मोड्युल संभाषणे AI वर लक्ष केंद्रित करतो जे संदर्भ लक्षात ठेवते आणि स्थिती राखते — जे संकल्पना त्या त्वरित सुरुवातीच्या डेमोंमध्ये वापरल्या गेल्या पण स्पष्ट केल्या गेलेल्या नाहीत. +हे LangChain4j आणि Azure OpenAI सह तुमचे प्रारंभिक ठिकाण आहे. आपण मूलभूत गोष्टींपासून सुरुवात करतो आणि उत्पादन-शैलीतील अनुप्रयोग तयार करतो. हा मॉड्युल संदर्भ लक्षात ठेवणारे आणि स्थिती जपणारे संभाषणात्मक AI यावर लक्ष केंद्रित करतो — हे प्रत्येक पुढील मॉड्युलसाठी मूलभूत संकल्पना आहेत. -या मार्गदर्शकात आपण संपूर्णपणे Azure OpenAI चा GPT-5.2 वापर करू कारण त्याच्या प्रगत विवेकबुद्धी क्षमतेमुळे वेगवेगळ्या पॅटर्न्सच्या वर्तनाचा स्पष्टपणे उल्लेख होतो. जेव्हा आपण मेमरी जोडता, तेव्हा फरक स्पष्ट दिसतो. यामुळे प्रत्येक घटक आपल्या अ‍ॅप्लिकेशनमध्ये काय आणतो हे समजणे सोपे होते. +या मार्गदर्शिकेत आपण Azure OpenAI च्या GPT-5.2 वापरू कारण त्याच्या प्रगत तर्कशक्तीमुळे वेगवेगळ्या नमुन्यांच्या वर्तनात स्पष्टता येते. जेव्हा तुम्ही मेमरी जोडता, तेव्हा फरक स्पष्टपणे दिसतो. त्यामुळे प्रत्येक घटक तुमच्या अनुप्रयोगासाठी काय आणतो हे समजणे सुलभ होते. -आपण एकच अ‍ॅप्लिकेशन तयार कराल जे दोन्ही पॅटर्न्स दाखवते: +आपण एक अनुप्रयोग तयार करणार आहोत जो दोन्ही नमुने दर्शवेल: -**स्टेटलेस चॅट** - प्रत्येक विनंती स्वतंत्र असते. मॉडेलला मागील संदेशाची कुठलीही आठवण नसते. हा तोच पॅटर्न आहे जो आपण त्वरित सुरुवातीमध्ये वापरला होता. +**स्टेटलेस चॅट** - प्रत्येक विनंती स्वतंत्र असते. मॉडेलला मागील संदेशांची कोणतीही आठवण नसते. हे सर्वात सोपे प्रारंभिक बिंदू आहे. -**स्टेटफुल संभाषण** - प्रत्येक विनंतीमध्ये संभाषणाचा इतिहास समाविष्ट असतो. मॉडेल अनेक टर्न्सच्या दरम्यान संदर्भ राखते. हे उत्पादन अ‍ॅप्लिकेशन्ससाठी आवश्यक आहे. +**स्टेटफुल संभाषण** - प्रत्येक विनंतीत संभाषणाचा इतिहास असतो. मॉडेल अनेक वळणांवर संदर्भ राखते. हे उत्पादन अनुप्रयोगासाठी आवश्यक आहे. ## पूर्वअट -- Azure सबस्क्रिप्शन ज्यात Azure OpenAI प्रवेश आहे +- Azure सदस्यता ज्यामध्ये Azure OpenAI प्रवेश आहे - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **टीप:** Java, Maven, Azure CLI आणि Azure Developer CLI (azd) दिलेल्या डेव्ह कंटेनरमध्ये पूर्वस्थापित आहेत. +> **टीप:** Java, Maven, Azure CLI आणि Azure Developer CLI (azd) पूर्व-स्थापित असतात दिलेल्या devcontainer मध्ये. -> **टीप:** हा मोड्युल Azure OpenAI वरील GPT-5.2 वापरतो. तैनाती `azd up` द्वारे स्वयंचलितपणे कॉन्फिगर होते — कोडमध्ये मॉडेल नावातील कोणतीही बदल करू नका. +> **टीप:** हा मॉड्युल Azure OpenAI वरील GPT-5.2 वापरतो. तैनात करण्यासाठी `azd up` द्वारे स्वयंचलितपणे कॉन्फिगर केले गेले आहे - कोडमधील मॉडेल नाव बदला नाही. -## मूलभूत समस्या समजून घेणे +## मूलभूत समस्येचा समज -भाषा मॉडेल्स स्टेटलेस असतात. प्रत्येक API कॉल स्वतंत्र असतो. जर आपण "माझं नाव जॉन आहे" असे पाठवलं आणि नंतर "माझं नाव काय आहे?" विचारलं, तर मॉडेलला कळत नाही की आपण नुकताच आपलं नाव सादर केलं आहे. ते प्रत्येक विनंती पहिल्या संभाषणासारखी मानते. +भाषा मॉडेल्स स्टेटलेस असतात. प्रत्येक API कॉल स्वतंत्र असतो. जर तुम्ही "माझं नाव जॉन आहे" पाठवलं आणि नंतर विचारलं "माझं नाव काय आहे?", तर मॉडेलला तुमच्या नावाची काहीही कल्पना नसते. ते प्रत्येक विनंती प्रथम संभाषण असल्यासारखे समजते. -सोपी प्रश्नोत्तरेसाठी हे ठीक आहे पण खर्‍या अ‍ॅप्लिकेशन्ससाठी उपयुक्त नाही. ग्राहक सेवा बॉटना आपल्याला काय सांगितलं ते आठवण ठेवणं गरजेचं असतं. वैयक्तिक सहाय्यकांना संदर्भ आवश्यक असतो. कोणत्याही बहु-टर्न संभाषणासाठी मेमरी आवश्यक आहे. +हे सोप्या Q&A साठी चालते पण खऱ्या अनुप्रयोगांसाठी उपयुक्त नाही. ग्राहक सेवा बोट्सना तुम्ही काय सांगितले ते आठवण ठेवायला हवे. वैयक्तिक सहाय्यकांना संदर्भ आवश्यक आहे. कोणताही बहु-टर्न संभाषण मेमरी वर अवलंबून असतो. -खालिल आकृती दोन दृष्टिकोन दाखवते — डावीकडील एक स्टेटलेस कॉल ज्याला आपलं नाव विसरलेलं आहे; उजवीकडील एक स्टेटफुल कॉल ज्याला ChatMemory द्वारे आधार दिलेला आहे आणि ते नाव लक्षात ठेवते. +खालिल चित्र दोन पद्धतींचा फरक दाखवते — डावीकडे, स्टेटलेस कॉल जो नाव विसरतो; उजवीकडे, ChatMemory-backed स्टेटफुल कॉल जो नाव लक्षात ठेवतो. -स्टेटलेस विरुद्ध स्टेटफुल संभाषणे +Stateless vs Stateful Conversations -*स्टेटलेस (स्वतंत्र कॉल्स) आणि स्टेटफुल (संदर्भ-आधारित) संभाषणांमधला फरक* +*स्टेटलेस (स्वतंत्र कॉल्स) आणि स्टेटफुल (संदर्भ-ज्ञानी) संभाषणांमधील फरक* ## टोकन्स समजून घेणे -संभाषणात खोलवर जाण्याआधी, टोकन्सची समज आवश्यक आहे — मजकूरातील मूलभूत घटक जे भाषा मॉडेल्स प्रक्रिया करतात: +संभाषणांमध्ये डुबल्यापूर्वी, टोकन्स समजून घेणे महत्त्वाचे आहे - बेसिक युनिट्स जे भाषा मॉडेल्स प्रक्रिया करतात: -टोकन स्पष्टीकरण +Token Explanation -*मजकूर टोकन्समध्ये कसा विभागला जातो याचे उदाहरण - "I love AI!" हे ४ वेगळ्या प्रक्रिया युनिट्स बनते* +*टेक्स्ट कसा टोकन्समध्ये विभागला जातो याचे उदाहरण - "I love AI!" ४ स्वतंत्र प्रक्रिया युनिट्समध्ये रूपांतरित होतो* -टोकन्स हे AI मॉडेल्सना मजकूर मोजण्यासाठी आणि प्रक्रिया करण्यासाठी वापरले जातात. शब्द, विरामचिन्हे, आणि अगदी जागाही टोकन्स असू शकतात. तुमच्या मॉडेलला एकावेळी किती टोकन्स प्रक्रिया करता येतील याची मर्यादा आहे (GPT-5.2 साठी ४००,०००, ज्यात २७२,००० इनपुट टोकन्स आणि १,२८,००० आउटपुट टोकन्स). टोकन्स समजल्याने संभाषणाची लांबी आणि खर्चे नियंत्रित करणे सहज होते. +टोकन्स हे AI मॉडेल्समधील टेक्स्ट मोजण्याचा आणि प्रक्रिया करण्याचा मार्ग आहे. शब्द, विरामचिन्हे, अगदी रिकाम्या जागाही टोकन्स असू शकतात. GPT-5.2 साठी एकाच वेळी प्रक्रिया करण्यास मॉडेलच्या क्षमता 400,000 टोकन्स पर्यंत आहेत (272,000 इनपुट टोकन्स आणि 128,000 आउटपुट टोकन्स). टोकन्स समजल्याने संभाषणाची लांबी आणि खर्च नियंत्रित करता येतो. -## मेमरी कशी कार्य करते +## मेमरी कशी काम करते -चॅट मेमरी स्टेटलेस समस्येचे निराकरण करते कारण ती संभाषणाचा इतिहास राखते. मॉडेलला विनंती पाठवण्याआधी, फ्रेमवर्कला संबंधित मागील संदेश जोडले जातात. जेव्हा आपण "माझं नाव काय आहे?" विचारता, तेव्हा सिस्टम प्रत्यक्षात सर्व संभाषण इतिहास पाठवते, ज्यामुळे मॉडेलला माहीत होते की आपण पूर्वी "माझं नाव जॉन आहे" असं सांगितलं होतं. +चॅट मेमरी स्टेटलेस समस्येवर उपाय आणते ज्यामुळे संभाषणाचा इतिहास जपला जातो. तुमची विनंती मॉडेलकडे पाठवण्यापूर्वी, फ्रेमवर्क संबंधित मागील संदेश जोडते. तुम्ही "माझं नाव काय आहे?" विचारल्यास, प्रणाली खरोखरच पूर्ण संभाषणाचा इतिहास पाठवते, ज्यामुळे मॉडेलला कळते की तुम्ही आधी "माझं नाव जॉन आहे" असं सांगितलं होतं. -LangChain4j मेमरी कार्यान्वयने प्रदान करते जी हे आपोआप हाताळतात. आपण किती संदेश ठेवायचे ते निवडता आणि फ्रेमवर्क संदर्भ विंडो व्यवस्थापित करते. खालील आकृती MessageWindowChatMemory कसे जवळील संदेशांची स्लायडिंग विंडो राखते ते दाखवते. +LangChain4j मेमरीच्या अंमलबजावणी प्रदान करते जी हे स्वयंचलित करते. तुम्ही किती संदेश ठेवायचे ते ठरवता आणि फ्रेमवर्क संदर्भ विंडो व्यवस्थापित करते. खालील चित्रात MessageWindowChatMemory कशी सध्याच्या संदेशांचा स्लायडिंग विंडो राखते हे दाखवले आहे. -मेमरी विंडो संकल्पना +Memory Window Concept -*MessageWindowChatMemory जवळील संदेशांची स्लायडिंग विंडो राखते, जुन्या संदेशांना आपोआप कमी करते* +*MessageWindowChatMemory सध्याच्या संदेशांचा स्लायडिंग विंडो राखते, जुने संदेश स्वयंचलितपणे काढून टाकते* -## हे LangChain4j कसे वापरते +## LangChain4j कसे वापरते -हा मोड्युल त्वरित सुरुवातीला Spring Boot एकत्रीकरण करून आणि संभाषण मेमरी वाढवून विस्तार करतो. भाग कसे जुळतात, हे खाली दिले आहे: +हा मॉड्युल Spring Boot सह समाकलित करतो आणि संभाषण मेमरी जोडतो. हे भाग कसे जुळतात: -**आधारभूत अवलंबन:** दोन LangChain4j लायब्ररी जोडा: +**अवलंबित्वे** - दोन LangChain4j लायब्ररी जोडा: ```xml @@ -94,7 +94,7 @@ LangChain4j मेमरी कार्यान्वयने प्रदा ``` -**चॅट मॉडेल** - Azure OpenAI ला Spring bean म्हणून कॉन्फिगर करा ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**चॅट मॉडेल** - Azure OpenAI ला एक Spring बीन्स म्हणून कॉन्फिगर करा ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -बिल्डर `azd up` द्वारे सेट केलेल्या पर्यावरण चलांमधून क्रेडेन्शियल्स वाचतो. `baseUrl` तुमच्या Azure एंडपॉइंटवर सेट केल्याने OpenAI क्लायंट Azure OpenAI सह कार्य करते. +बिल्डर `azd up` द्वारे सेट केलेल्या पर्यावरणीय चल कडून क्रेडेन्शियल वाचतो. `baseUrl` तुमच्या Azure एंडपॉइंटवर सेट केल्याने OpenAI क्लायंट Azure OpenAI सोबत काम करतो. -**संभाषण मेमरी** - MessageWindowChatMemory सह चॅट इतिहास ट्रॅक करा ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**संभाषण मेमरी** - MessageWindowChatMemory वापरून चॅट इतिहास ट्रॅक करा ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` सह मेमरी तयार करा ज्यामुळे शेवटचे १० संदेश ठेवले जातील. वापरकर्ता आणि AI संदेश `UserMessage.from(text)` आणि `AiMessage.from(text)` या टाइप केलेल्या रॅपरने जोडा. इतिहास `memory.messages()` ने मिळवा आणि मॉडेलला पाठवा. सेवा प्रत्येक संभाषण आयडी साठी स्वतंत्र मेमरी उदाहरणे संचयित करते, ज्यामुळे एकाधिक वापरकर्ते एकाचवेळी चॅट करू शकतात. +`withMaxMessages(10)` वापरून मेमरी तयार करा जे शेवटचे 10 संदेश ठेवते. वापरकर्ता आणि AI संदेश टाइप केलेल्या रॅपर्ससोबत जोडा: `UserMessage.from(text)` आणि `AiMessage.from(text)`. इतिहास `memory.messages()` ने मिळवा आणि तो मॉडेलला पाठवा. सेवा प्रत्येक संभाषण ID साठी स्वतंत्र मेमरी उदाहरणे साठवते, ज्यामुळे एकाच वेळी अनेक वापरकर्ते चॅट करू शकतात. -> **🤖 GitHub Copilot [https://github.com/features/copilot] चॅट वापरून प्रयत्न करा:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) उघडा आणि विचारा: -> - "MessageWindowChatMemory विंडो पूर्ण झाल्यावर कोणते संदेश टाकण्याचा निर्णय कसा घेतो?" -> - "मी मेमरी संग्रहीत करण्यासाठी इन-मेमरीऐवजी डेटाबेस वापरून सानुकूल मेमरी कशी अंमलात आणू शकतो?" -> - "जुन्या बातचीत इतिहासाचा संक्षेप करण्यासाठी संक्षेप जोडण्यासाठी मी काय करेल?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) चॅटसह प्रयत्न करा:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) उघडा आणि विचारा: +> - "MessageWindowChatMemory विंडो पूर्ण झाल्यावर कोणते संदेश काढते हे कसे ठरवते?" +> - "मी इन-मेमरीऐवजी डेटाबेस वापरून कस्टम मेमरी स्टोरेज कसे अंमलात आणू शकतो?" +> - "जुना संभाषणाचा इतिहास संक्षिप्त करण्यासाठी सारांश कसा जोडू?" -स्टेटलेस चॅट endpoint मेमरी पूर्णपणे सोडून देतो - फक्त `chatModel.chat(prompt)` जसे त्वरित सुरुवातीमध्ये होते. स्टेटफुल endpoint मेमरीमध्ये संदेश जोडतो, इतिहास प्राप्त करतो आणि प्रत्येक विनंतीसह तो संदर्भ जोडतो. त्याच मॉडेल कॉन्फिगरेशनसह वेगळ्या पॅटर्न्स. +स्टेटलेस चॅट एंडपॉइंट पूर्णपणे मेमरी वगळतो - फक्त `chatModel.chat(prompt)` प्रमाणे जलद सुरुवात. स्टेटफुल एंडपॉइंट मेमरीमध्ये संदेश जोडतो, इतिहास मिळवतो आणि प्रत्येक विनंतीसह संदर्भ सामील करतो. मॉडेल कॉन्फिगरेशन सारखेच, फक्त वेगवेगळे नमुने. ## Azure OpenAI इन्फ्रास्ट्रक्चर तैनात करा @@ -147,20 +147,20 @@ cd 01-introduction azd up # सदस्यता आणि स्थान निवडा (eastus2 शिफारस केलेले) ``` -> **टीप:** आपण टाईमआउट त्रुटी (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) याचा सामना करत असाल तर फक्त `azd up` पुन्हा चालवा. Azure संसाधने अजूनही बॅकग्राउंडमध्ये प्रोव्हिजनिंग चालू असू शकतात, आणि पुन्हा प्रयत्न केल्यावर संसाधने अंतिम स्थितीत आल्यावर तैनात प्रक्रिया पूर्ण होऊ शकते. +> **टीप:** जर तुम्हाला timeout त्रुटी येत असेल (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), तर फक्त `azd up` पुन्हा चालवा. Azure स्रोत अजूनही पार्श्वभूमीमध्ये तैनात होत असू शकतात आणि पुन्हा प्रयत्न केल्याने तैनाती पूर्ण होण्यास मदत होते. -यामुळे: -1. GPT-5.2 आणि text-embedding-3-small मॉडेल्ससह Azure OpenAI संसाधन तैनात होईल -2. प्रोजेक्ट रूटमध्ये क्रेडेन्शियल्ससह `.env` फाइल स्वयंचलितपणे तयार होईल -3. सर्व आवश्यक पर्यावरण चल सेट होणार +हे ते करेल: +1. GPT-5.2 आणि text-embedding-3-small मॉडेलसह Azure OpenAI संसाधन तैनात करा +2. क्रेडेन्शियल्ससह प्रोजेक्ट रूटमध्ये `.env` फाईल स्वयंचलितपणे तयार करा +3. सर्व आवश्यक पर्यावरणीय चल सेट करा -**तैनाती संदर्भात समस्या आहेत?** तपशीलवार त्रुटी निवारणासाठी [इन्फ्रास्ट्रक्चर README](infra/README.md) पहा ज्यात उपडोमेन नाव संघर्ष, चांगल्या Azure पोर्टलमधील तैनात चरण आणि मॉडेल कॉन्फिगरेशन मार्गदर्शन आहे. +**तैनाती करताना समस्या येत आहेत?** दृष्टी टाका [Infrastructure README](infra/README.md) मध्ये तपशीलवार तांत्रिक त्रुटी निवारणासाठी ज्यात उपडोमेन नाव संघर्ष, मॅन्युअल Azure पोर्टल तैनाती टप्पे आणि मॉडेल कॉन्फिगरेशन मार्गदर्शन आहे. -**तैनात यशस्वी झाले याची पुष्टी करा:** +**तैनात यशस्वीरित्या झाले आहे का तपासा:** **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, इत्यादी दाखवावे. +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, इत्यादी दाखवले पाहिजेत. ``` **PowerShell:** @@ -168,7 +168,7 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, इत्यादी दाख Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, इत्यादी दाखवले पाहिजेत. ``` -> **टीप:** `azd up` कमांड स्वयंचलितपणे `.env` फाइल तयार करते. नंतर अद्ययावत करायची असल्यास, आपण `.env` फाइल हाताने संपादित करू शकता किंवा खालीलप्रमाणे रीजनरेट करू शकता: +> **टीप:** `azd up` आदेश स्वयंचलितपणे `.env` फाईल तयार करतो. तुम्हाला नंतर ते अपडेट करायचे असल्यास, तुम्ही `.env` फाईल हाताने संपादित करू शकता किंवा पुढीलप्रमाणे पुन्हा त्याची निर्मिती करू शकता: > > **Bash:** > ```bash @@ -182,15 +182,15 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, इत्यादी द > .\.azd-env.ps1 > ``` -## अ‍ॅप्लिकेशन स्थानिकपणे चालवा +## अर्ज स्थानिकपणे चालवा **तैनातीची पुष्टी करा:** -Azure क्रेडेन्शियल्ससह `.env` फाइल रूट डायरेक्टरीत अस्तित्वात आहे याची खात्री करा. हे मोड्युल निर्देशिकेतून (`01-introduction/`) चालवा: +मुळ निर्देशिकेत Azure क्रेडेन्शियलसह `.env` फाईल आहे याची खात्री करा. हा कमांड मॉड्युल निर्देशिकेतून चालवा (`01-introduction/`): **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवायला पाहिजे +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दर्शवायला हवे ``` **PowerShell:** @@ -198,41 +198,41 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवायल Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवले पाहिजे ``` -**अ‍ॅप्लिकेशन्स सुरू करा:** +**अर्ज सुरू करा:** -**पर्याय 1: Spring Boot डॅशबोर्ड वापरणे (VS Code वापरकर्त्यांसाठी शिफारस केलेले)** +**पर्याय 1: Spring Boot डॅशबोर्ड वापरून (VS Code वापरकर्त्यांसाठी शिफारस)** -डेव्ह कंटेनरमध्ये Spring Boot डॅशबोर्ड विस्तार समाविष्ट आहे, जो सर्व Spring Boot अ‍ॅप्लिकेशन्सचे व्यवस्थापन करण्यासाठी दृश्य इंटरफेस पुरवतो. हा VS Code च्या डाव्या बाजूला असलेल्या Activity Bar मध्ये उपलब्ध आहे (Spring Boot चिन्ह पाहा). +devcontainer मध्ये Spring Boot डॅशबोर्ड एक्सटेंशन समाविष्ट आहे, जे सर्व Spring Boot अनुप्रयोग व्यवस्थापित करण्यासाठी व्हिज्युअल इंटरफेस प्रदान करतो. VS Code च्या डाव्या बाजूला Activity Bar मध्ये Spring Boot आयकॉन शोधा. -Spring Boot डॅशबोर्डमधून, आपण करू शकता: -- कार्यक्षेत्रातील सर्व उपलब्ध Spring Boot अ‍ॅप्लिकेशन्स पाहणे -- एक क्लिकमध्ये अ‍ॅप्लिकेशन्स सुरू/थांबवणे -- अ‍ॅप्लिकेशन लॉग्स प्रत्यक्ष पाहणे -- अ‍ॅप्लिकेशन स्थितीचे निरीक्षण करणे +Spring Boot डॅशबोर्ड मधून तुम्ही: +- वर्कस्पेस मधील सर्व उपलब्ध Spring Boot अनुप्रयोग पाहू शकता +- अनुप्रयोग एका क्लिकने सुरू किंवा थांबवू शकता +- अनुप्रयोग लॉग्स रिअल-टाईम मध्ये पाहू शकता +- अनुप्रयोग स्थिती निरीक्षण करू शकता -"introduction" जवळील प्ले बटणावर क्लिक करा हा मोड्युल सुरू करण्यासाठी किंवा एकदाच सर्व मोड्युल्स सुरू करा. +फक्त "introduction" च्या बाजूला प्ले बटणावर क्लिक करा हा मॉड्युल सुरू करण्यासाठी, किंवा सर्व मॉड्युल एकाच वेळी सुरू करा. -Spring Boot डॅशबोर्ड +Spring Boot Dashboard -*VS Code मधील Spring Boot डॅशबोर्ड — एकाच ठिकाणाहून सर्व मोड्युल्स सुरू, थांबवा आणि निरीक्षण करा* +*VS Code मधील Spring Boot डॅशबोर्ड — एकाच ठिकाणी सर्व मॉड्युल सुरू, थांबवून आणि निरीक्षण करा* -**पर्याय 2: शेल स्क्रिप्ट वापरणे** +**पर्याय 2: शेल स्क्रिप्ट वापरून** -सर्व वेब अ‍ॅप्लिकेशन्स (मोड्युल 01-04) सुरू करा: +सर्व वेब अनुप्रयोग (मॉड्युल 01-04) सुरू करा: **Bash:** ```bash -cd .. # रूट डिरेक्टरीमधून +cd .. # मुळ निर्देशिकेतून ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # रूट निर्देशिकेतून +cd .. # रूट संचिकास्थळावरून .\start-all.ps1 ``` -किंवा फक्त हा मोड्युल सुरू करा: +किंवा फक्त हा मॉड्युल सुरू करा: **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -दोन्ही स्क्रिप्ट्स स्वयंचलितपणे रूट `.env` फाइलमधून पर्यावरण चल लोड करतात आणि जर JAR फाईल्स अस्तित्वात नसेल तर त्या तयार करतात. +दोन्ही स्क्रिप्ट्स मुळ `.env` फाईलमधून पर्यावरणीय चल लोड करतात आणि JAR तयार करतात जर ते अस्तित्वात नसतील. -> **टीप:** आपण सर्व मोड्युल मॅन्युअली तयार करण्यास प्राधान्य देत असाल तर सुरू करण्यापूर्वी: +> **टीप:** जर तुम्हाला सर्व मॉड्युल्स आधी मॅन्युअली तयार करायचे असतील: > > **Bash:** > ```bash @@ -262,13 +262,13 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -ब्राउझरमध्ये http://localhost:8080 उघडा. +तुमच्या ब्राउझरमध्ये http://localhost:8080 उघडा. **थांबवण्यासाठी:** **Bash:** ```bash -./stop.sh # हे मॉड्यूल फक्त +./stop.sh # फक्त हा मॉड्यूल # किंवा cd .. && ./stop-all.sh # सर्व मॉड्यूल्स ``` @@ -277,46 +277,46 @@ cd .. && ./stop-all.sh # सर्व मॉड्यूल्स ```powershell .\stop.ps1 # हा फक्त मॉड्यूल # किंवा -cd ..; .\stop-all.ps1 # सर्व मॉड्यूल +cd ..; .\stop-all.ps1 # सर्व मॉड्यूल्स ``` -## अ‍ॅप्लिकेशन वापरणे +## अर्जाचा वापर कसा करावा -अ‍ॅप्लिकेशन दोन बाजूच्या चॅट अंमलबजावणींसह वेब इंटरफेस प्रदान करते. +हा अर्ज दोन वेगळ्या चॅट अंमलबजावण्या एकत्र वेब इंटरफेसवर दर्शवितो. -अ‍ॅप्लिकेशन होम स्क्रीन +Application Home Screen -*डॅशबोर्ड ज्यात साधा चॅट (स्टेटलेस) आणि संभाषणात्मक चॅट (स्टेटफुल) पर्याय दोन्ही दाखवले आहेत* +*डॅशबोर्ड ज्यात सोपी चॅट (स्टेटलेस) व संभाषणात्मक चॅट (स्टेटफुल) पर्याय दिसतात* -### स्टेटलेस चॅट (डावी पॅनेल) +### स्टेटलेस चॅट (डावा पॅनेल) -हे प्रथम प्रयत्न करा. विचार करा "माझं नाव जॉन आहे" आणि लगेच "माझं नाव काय आहे?" हे विचारा. मॉडेलला आठवत नाही कारण प्रत्येक संदेश स्वतंत्र असतो. हे मूलभूत भाषा मॉडेल एकत्रीकरणातील मुख्य समस्या दाखवते - संभाषणाचा संदर्भ नाही. +हे प्रथम वापरून पाहा. "माझं नाव जॉन आहे" असा संदेश द्या आणि लगेच "माझं नाव काय आहे?" विचारा. मॉडेल लक्षात ठेवणार नाही कारण प्रत्येक संदेश स्वतंत्र असतो. हे बेसिक भाषा मॉडेल एकत्रिकरणातील मुख्य समस्या दाखवते - संभाषणाचा कोणताही संदर्भ नाही. -स्टेटलेस चॅट डेमो +Stateless Chat Demo -*AI आपले नाव मागील संदेशापासून आठवत नाही* +*AI ला मागील संदेशातून तुमचं नाव आठवत नाही* -### स्टेटफुल चॅट (उजवी पॅनेल) +### स्टेटफुल चॅट (उजवा पॅनेल) -आता याच क्रमाने येथे प्रयत्न करा. विचार करा "माझं नाव जॉन आहे" आणि नंतर "माझं नाव काय आहे?" यावेळी ते लक्षात ठेवते. फरक MessageWindowChatMemory आहे — ते संभाषणाचा इतिहास राखते आणि प्रत्येक विनंतीसह तो संदर्भ समाविष्ट करते. हे उत्पादन संभाषणात्मक AI कसे कार्य करते. +आता त्याच क्रमाने येथे प्रयत्न करा. "माझं नाव जॉन आहे" आणि नंतर "माझं नाव काय आहे?" विचारले की यावेळी लक्षात ठेवते. फरक आहे MessageWindowChatMemory मध्ये - ते संभाषणाचा इतिहास टिकवते आणि प्रत्येक विनंतीसह तो संदर्भ देतो. उत्पादन संभाषणात्मक AI असाच काम करतो. -स्टेटफुल चॅट डेमो +Stateful Chat Demo -*AI संभाषणाच्या आधीच्या भागातून आपले नाव लक्षात ठेवते* +*AI ला आधीच्या संभाषणातून तुमचं नाव आठवतं* -दोन्ही पॅनेल समान GPT-5.2 मॉडेल वापरतात. एकमेव फरक म्हणजे मेमरी. हे स्पष्ट करते की मेमरी आपल्या अ‍ॅप्लिकेशनमध्ये काय आणते आणि ती प्रत्यक्ष वापरासाठी का आवश्यक आहे. +दोन्ही पॅनेल्समध्ये एकाच GPT-5.2 मॉडेलचा वापर आहे. फरक फक्त मेमरी आहे. यामुळे मेमरी तुमच्या अनुप्रयोगासाठी काय आणते आणि प्रत्यक्ष वापरासाठी का आवश्यक आहे हे स्पष्ट होते. -## पुढील पाऊले +## पुढील टप्पे -**पुढील मोड्युल:** [02-prompt-engineering - GPT-5.2 सह प्रॉम्प्ट इंजिनिअरिंग](../02-prompt-engineering/README.md) +**पुढील मॉड्युल:** [02-prompt-engineering - GPT-5.2 सह प्रॉम्प्ट अभियांत्रण](../02-prompt-engineering/README.md) --- -**नेव्हिगेशन:** [← मागील: Module 00 - Quick Start](../00-quick-start/README.md) | [मुख्य पृष्ठावर परत](../README.md) | [पुढे: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**नेव्हिगेशन:** [← मुख्य पृष्ठाकडे परत जा](../README.md) | [पुढील: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **अस्वीकरण**: -हा दस्तऐवज AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) वापरून अनुवादित केला आहे. आम्ही अचूकतेसाठी प्रयत्नशील असलो तरी, कृपया लक्षात ठेवा की स्वयंचलित अनुवादांमध्ये चुका किंवा अनुचितता असू शकतात. मूळ दस्तऐवज त्याच्या मूळ भाषेत अधिकृत स्रोत मानावा. महत्त्वाची माहिती असल्यास, व्यावसायिक मानवी अनुवाद करण्याची शिफारस केली जाते. या अनुवादाच्या वापरामुळे उद्भवलेल्या कोणत्याही गैरसमजुती किंवा चुकीच्या अर्थांचे आम्ही उत्तरदायी नाही. +हा दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) चा वापर करून अनुवादित केला आहे. जरी आम्ही अचूकतेसाठी प्रयत्न करतो, तरी कृपया लक्षात घ्या की स्वयंचलित भाषांतरांमध्ये त्रुटी किंवा अचूकतेची कमतरता असू शकते. मूळ दस्तऐवज त्याच्या मूळ भाषेत अधिकृत स्रोत मानला पाहिजे. महत्त्वाची माहिती असल्यास, व्यावसायिक मानवी भाषांतराची शिफारस केली जाते. या भाषांतराच्या वापरामुळे उद्भवणाऱ्या कोणत्याही गैरसमज किंवा चुकीच्या अर्थलावणीसाठी आम्ही जबाबदार नाही. \ No newline at end of file diff --git a/translations/mr/02-prompt-engineering/README.md b/translations/mr/02-prompt-engineering/README.md index 87150c910..19ef932af 100644 --- a/translations/mr/02-prompt-engineering/README.md +++ b/translations/mr/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Module 02: GPT-5.2 सह प्रॉम्प्ट अभियांत्रण +# Module 02: GPT-5.2 सह प्रॉम्प्ट अभियांत्रिकी ## अनुक्रमणिका -- [व्हिडिओ वॉकथ्रू](../../../02-prompt-engineering) -- [तुम्ही काय शिकाल](../../../02-prompt-engineering) -- [पूर्वअट](../../../02-prompt-engineering) -- [प्रॉम्प्ट अभियांत्रण समजून घेणे](../../../02-prompt-engineering) -- [प्रॉम्प्ट अभियांत्रण मूलतत्त्वे](../../../02-prompt-engineering) - - [झीरो-शॉट प्रॉम्प्टिंग](../../../02-prompt-engineering) - - [फ्यू-शॉट प्रॉम्प्टिंग](../../../02-prompt-engineering) - - [चेन ऑफ थॉट](../../../02-prompt-engineering) - - [भूमिका-आधारित प्रॉम्प्टिंग](../../../02-prompt-engineering) - - [प्रॉम्प्ट टेम्पलेट्स](../../../02-prompt-engineering) -- [प्रगत नमुने](../../../02-prompt-engineering) -- [अर्ज चालवा](../../../02-prompt-engineering) -- [अर्जाच्या स्क्रीनशॉट्स](../../../02-prompt-engineering) -- [नमुने एक्सप्लोर करणे](../../../02-prompt-engineering) - - [कमी विरघळणा विराम व उच्च विरघळणा विराम](../../../02-prompt-engineering) - - [कार्य अंमलबजावणी (टूल प्रीइम्बल्स)](../../../02-prompt-engineering) - - [स्वतःचे चिंतन करणारा कोड](../../../02-prompt-engineering) - - [संरचित विश्लेषण](../../../02-prompt-engineering) - - [अनेकच पर्यटन संवाद](../../../02-prompt-engineering) - - [पायरी-दर-पायरी विचारसरणी](../../../02-prompt-engineering) - - [बाधित आउटपुट](../../../02-prompt-engineering) -- [तुम्ही खरोखर काय शिकत आहात](../../../02-prompt-engineering) -- [पुढील टप्पे](../../../02-prompt-engineering) +- [व्हिडिओ वॉकथ्रू](#व्हिडिओ-वॉकथ्रू) +- [आपण काय शिकणार आहात](#आपण-काय-शिकणार-आहात) +- [पूर्वअटी](#पूर्वअटी) +- [प्रॉम्प्ट अभियांत्रिकी समजून घेणे](#प्रॉम्प्ट-अभियांत्रिकी-समजून-घेणे) +- [प्रॉम्प्ट अभियांत्रिकी मूलतत्त्वे](#प्रॉम्प्ट-अभियांत्रिकी-मूलतत्त्वे) + - [झीरो-शॉट प्रॉम्प्टिंग](#झीरो-शॉट-प्रॉम्प्टिंग) + - [फ्यू-शॉट प्रॉम्प्टिंग](#फ्यू-शॉट-प्रॉम्प्टिंग) + - [चेन ऑफ थॉट](#चेन-ऑफ-थॉट) + - [रोल-आधारित प्रॉम्प्टिंग](#रोल-आधारित-प्रॉम्प्टिंग) + - [प्रॉम्प्ट टेम्पलेट्स](#प्रॉम्प्ट-टेम्पलेट्स) +- [प्रगत नमुन्यांसाठी](#प्रगत-नमुने) +- [अॅप्लिकेशन चालवा](#अनुप्रयोग-चालवा) +- [अॅप्लिकेशन स्क्रीनशॉट्स](#अनुप्रयोगाचे-स्क्रीनशॉट) +- [नमुने एक्सप्लोर करणे](#पॅटर्न्सचे-अन्वेषण-करणे) + - [कमी विरुद्ध जास्त उत्सुकता](#low-vs-high-eagerness) + - [टास्क अंमलबजावणी (टूल प्रीअ‍ॅंबल्स)](#task-execution-tool-preambles) + - [स्वतःचे परावर्तन करणारा कोड](#self-reflecting-code) + - [रचनेत विश्लेषण](#structured-analysis) + - [मल्टी-टर्न चॅट](#multi-turn-chat) + - [टप्प्याटप्प्याने तर्क](#step-by-step-reasoning) + - [बाधित आउटपुट](#constrained-output) +- [आपण खरोखर काय शिकत आहात](#तुम्ही-खरोखर-काय-शिकत-आहात) +- [पुढील पावले](#पुढचे-टप्पे) ## व्हिडिओ वॉकथ्रू -या लाइव्ह सत्रात पाहा जे या मॉड्यूलसह कसे सुरुवात करावी हे स्पष्ट करते: +हा लायव्ह सत्र पहा जो या मॉड्यूलसह कसे प्रारंभ करायचे हे समजावून सांगतो: -Prompt Engineering with LangChain4j - Live Session +LangChain4j सह प्रॉम्प्ट अभियांत्रिकी - लाईव्ह सत्र -## तुम्ही काय शिकाल +## आपण काय शिकणार आहात -खालील आकृती या मॉड्यूलमध्ये तुम्ही विकसित कराल अशा प्रमुख विषयांचा आणि कौशल्यांचा आढावा देते — प्रॉम्प्ट सुधारणा तंत्रांपासून ते तुम्ही अनुसराल अशा टप्प्याटप्प्याने वर्कफ्लोपर्यंत. +खाली दिलेला आकृती या मॉड्युलमध्ये आपण विकसीत करणार असलेले मुख्य विषय आणि कौशल्यांचे आराखडा देतो — प्रॉम्प्ट सुधारणा तंत्रांपासून ते आपण अनुसरण करणार्‍या टप्प्याटप्प्यांच्या कार्यप्रवाहापर्यंत. -What You'll Learn +आपण काय शिकणार आहात -मागील मॉड्यूलमध्ये, तुम्ही GitHub मॉडेल्ससह LangChain4j च्या प्राथमिक संवादांची तपासणी केली आणि Azure OpenAI सोबत संवादात्मक AI साठी मेमरी कशी सक्षम होते हे पाहिले. आता आपण लक्ष केंद्रित करू की तुम्ही प्रश्न कसे विचारता — प्रॉम्प्ट्स स्वतः — Azure OpenAI च्या GPT-5.2 चा वापर करून. तुमचा प्रॉम्प्ट कसा रचला आहे यामुळे दिलेल्या प्रतिसादाची गुणवत्ता मोठ्या प्रमाणावर प्रभावित होते. आपण प्रॉम्प्टिंगच्या मूलभूत तंत्रांची पुनरावृत्ती करून सुरू करू, नंतर GPT-5.2 च्या क्षमतांचा पूर्ण फायदा घेणाऱ्या आठ प्रगत नमुन्यांमध्ये जाऊ. +पूर्वीच्या मॉड्यूलमध्ये, आपण पाहिले की मेमरी कशी Azure OpenAI सह संभाषणात्मक AI सक्षम करते. आता आपण प्रश्न कसे विचाराल यावर लक्ष देणार आहोत — प्रॉम्प्ट्स स्वतः — Azure OpenAI च्या GPT-5.2 वापरून. आपले प्रॉम्प्ट कसे संरचित केले जातात याचा प्रतिसादांची गुणवत्ता मोठ्या प्रमाणात परिणाम होतो. आपण मूलभूत प्रॉम्प्टिंग तंत्रांचे पुनरावलोकन करतो, मग पुढे चालून आठ प्रगत नमुन्यांकडे वळतो जे GPT-5.2 च्या क्षमतांचा पूर्ण फायदा घेतात. -आपण GPT-5.2 वापरू कारण यात विचार करण्याचे नियंत्रण आहे - तुम्ही मॉडेलला उत्तर देण्यापूर्वी किती विचार करायचा आहे ते सांगू शकता. यामुळे भिन्न प्रॉम्प्टिंग धोरणे अधिक स्पष्ट होतात आणि तुम्हाला कोणती पद्धत केव्हा वापरायची हे समजायला मदत होते. तसेच, GitHub मॉडेल्सच्या तुलनेत Azure चे GPT-5.2 साठी कमी दर मर्यादा ही उपयुक्त ठरतात. +आपण GPT-5.2 वापरणार आहोत कारण ते तर्क नियंत्रण आणते - आपण मॉडेलला सांगू शकता की उत्तर देण्यापूर्वी त्याने किती विचार करायचा आहे. यामुळे वेगवेगळ्या प्रॉम्प्टिंग रणनीती अधिक स्पष्ट होतात आणि आपल्याला प्रत्येक दृष्टिकोन कधी वापरायचा हे समजण्यास मदत होते. -## पूर्वअट +## पूर्वअटी -- मॉड्यूल 01 पूर्ण केलेले (Azure OpenAI संसाधने तैनात केलेली) -- मुख्य निर्देशिकेत `.env` फाइल Azure प्रमाणपत्रांसह (मॉड्यूल 01 मध्ये `azd up` द्वारा तयार केलेली) +- Module 01 पूर्ण (Azure OpenAI संसाधने तैनात केली) +- मूळ डिरेक्टरीमध्ये `.env` फाइल आहे ज्यात Azure क्रेडेन्शियल्स आहेत (Module 01 मध्ये `azd up` द्वारा तयार) -> **टीप:** जर तुम्ही मॉड्यूल 01 पूर्ण केले नसेल तर आधी तिथल्या तैनात सूचना अनुसरा. +> **नोट:** जर आपण Module 01 पूर्ण केले नसेल, तर तिथल्या तैनाती सूचना प्रथम पाळा. -## प्रॉम्प्ट अभियांत्रण समजून घेणे +## प्रॉम्प्ट अभियांत्रिकी समजून घेणे -मूळतः, प्रॉम्प्ट अभियांत्रण म्हणजे अस्पष्ट सूचनांमधून अचूक सूचनांपर्यंतचा फरक, खालील तुलनेत दाखवलेला आहे. +मुळत: प्रॉम्प्ट अभियांत्रिकी ही अस्पष्ट सूचना आणि अचूक सूचनेतील फरक आहे, खालील तुलना हे दर्शविते. -What is Prompt Engineering? +प्रॉम्प्ट अभियांत्रिकी म्हणजे काय? -प्रॉम्प्ट अभियांत्रण म्हणजे अशा इनपुट मजकुराची रचना करणे जी नियमितपणे तुम्हाला आवश्यक परिणाम मिळवून देते. हे केवळ प्रश्न विचारण्याबद्दल नाही - हे अशा विनंत्यांची रचना करण्याबद्दल आहे ज्यामुळे मॉडेलला नक्की काय हवे आहे आणि कसे प्रदान करायचे हे समजते. +प्रॉम्प्ट अभियांत्रिकी म्हणजे अशा इनपुट टेक्स्ट डिझाइन करणे जे सातत्याने आपल्याला आवश्यक परिणाम देते. हे फक्त प्रश्न विचारण्याबाबतच नाही - हे विनंतींची रचना करण्याबाबत आहे ज्यामुळे मॉडेल आपल्याला नेमकं काय पाहिजे हे समजते आणि कसे प्रदान करायचे ते कळते. -हे एखाद्या सहकाऱ्याला सूचना देण्यासारखे समजा. "बग दुरुस्त करा" ही अस्पष्ट सूचना आहे. "UserService.java ची ओळ 45 मध्ये null pointer exception सुधारण्यासाठी null चेक जोडा" ही विशिष्ट सूचना आहे. भाषा मॉडेल्ससाठीही तसंच लागू आहे - विशिष्टता आणि रचना महत्वाची आहे. +हे जसे आपण सहकाऱ्याला सूचना देतो तशासारखे विचार करा. "बग दुरुस्त करा" हा अस्पष्ट आहे. "UserService.java च्या ओळ 45 मधील नल पॉइंटर अपवाद दुरुस्त करा आणि नल तपासणी जोडा" हे विशिष्ट आहे. भाषा मॉडेल्स देखील तसेच काम करतात - विशिष्टता आणि रचना महत्त्वाची असते. -खालील आकृती LangChain4j कसे या चित्रात बसते हे दाखवते — तुमच्या प्रॉम्प्ट नमुन्यांना SystemMessage आणि UserMessage या संरचनात्मक घटकांमधून मॉडेलशी जोडते. +खालील आकृती दर्शविते की LangChain4j या चित्रात कसा बसतो — आपल्या प्रॉम्प्ट नमुन्यांना SystemMessage आणि UserMessage या बांधकाम ब्लॉक्सद्वारे मॉडेलशी जोडतो. -How LangChain4j Fits +LangChain4j कसा बसतो -LangChain4j ही आधारभूत तत्वं प्रदान करते — मॉडेल कनेक्शन, मेमरी, आणि संदेश प्रकार — तर प्रॉम्प्ट नमुने केवळ सावधगिरीने रचलेला मजकूर आहेत जो त्या बुनियादी संरचना मार्गे पाठविला जातो. मुख्य बांधणी घटक म्हणजे `SystemMessage` (जो AI ची वर्तन आणि भूमिका ठरवतो) आणि `UserMessage` (जो तुमच्या प्रत्यक्ष विनंतीचे वाहक असतो). +LangChain4j हे इन्फ्रास्ट्रक्चर पुरवते — मॉडेल कनेक्शन्स, मेमरी, आणि मेसेज प्रकार — तर प्रॉम्प्ट नमुने फक्त काळजीपूर्वक संरचित टेक्स्ट आहेत जे आपण त्या इन्फ्रास्ट्रक्चरमधून पाठवतो. मुख्य ब्लॉक्स म्हणजे `SystemMessage` (जो AI चे वर्तन आणि भूमिका सेट करतो) आणि `UserMessage` (जो आपली प्रत्यक्ष विनंती वाहक असतो). -## प्रॉम्प्ट अभियांत्रण मूलतत्त्वे +## प्रॉम्प्ट अभियांत्रिकी मूलतत्त्वे -खाली दाखवलेले पाच मुख्य तंत्र प्रभावी प्रॉम्प्ट अभियांत्रणाची पायाभूत संरचना तयार करतात. प्रत्येक वेगवेगळ्या प्रकारे भाषा मॉडेल्सशी संवाद साधण्याचा दृष्टिकोन सादर करते. +खाली दिलेले पाच कोर तंत्रज्ञान प्रभावी प्रॉम्प्ट अभियांत्रिकीचे मूलतत्त्व बनवतात. प्रत्येक वेगळ्या पैलूला सामोरे जाते ज्याद्वारे आपण भाषा मॉडेलशी संवाद साधता. -Five Prompt Engineering Patterns Overview +पाच प्रॉम्प्ट अभियांत्रिकी नमुन्यांचा आढावा -या मॉड्यूलमधील प्रगत नमुन्यांमध्ये प्रवेश करण्यापूर्वी, चलो पाच मूलभूत प्रॉम्प्टिंग तंत्रांची पुनरावृत्ती करू. हे त्या बांधणी घटक आहेत जे प्रत्येक प्रॉम्प्ट अभियंत्याने माहीत असावीत. जर तुम्ही आधीच [क्विक स्टार्ट मॉड्यूल](../00-quick-start/README.md#2-prompt-patterns) पार केला असेल तर तुम्हाला हे काम करताना पाहिले असेल — खाली त्यामागील संकल्पनात्मक चौकट. +या मॉडुलच्या प्रगत नमुन्यांमध्ये उतरल्यापूर्वी, चला पाच मूलभूत प्रॉम्प्टिंग तंत्रांचा पुनरावलोकन करू. हे त्या मूलभूत ब्लॉक्स आहेत जे प्रत्येक प्रॉम्प्ट अभियंता जाणून घेणे आवश्यक आहे. ### झीरो-शॉट प्रॉम्प्टिंग -सर्वात साधे दृष्टीकोन: कोणतेही उदाहरण न देता मॉडेलला थेट सूचना द्या. मॉडेल पूर्णपणे त्याच्या प्रशिक्षणावर अवलंबून असतो जेणेकरून तो काम समजून पार पाडू शकेल. हे सरळ विनंत्यांसाठी तयार आहे जिथे अपेक्षित वर्तन स्पष्ट असते. +सर्वात सोपा दृष्टिकोन: मॉडेलला थेट सूचना द्या, कोणतेही उदाहरणांशिवाय. मॉडेल पूर्णपणे त्याच्या प्रशिक्षणावर अवलंबून असते कार्य समजून घेण्यासाठी आणि अंमलात आणण्यासाठी. हे सोप्या विनंत्यांसाठी उत्तम काम करते जिथे अपेक्षित वर्तन स्पष्ट असते. -Zero-Shot Prompting +झीरो-शॉट प्रॉम्प्टिंग -*कोणतेही उदाहरण न देता थेट सूचना - मॉडेल फक्त सूचना वाचून कार्याला समजून घेतो* +*उदाहरणांशिवाय थेट सूचना — मॉडेल फक्त सूचनांपासून कार्याचा अर्थ निघवते* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// उत्तर: "सकारात्मक" +// प्रतिसाद: "सकारात्मक" ``` -**कधी वापरावे:** सोप्या वर्गीकरणासाठी, थेट प्रश्नांसाठी, भाषांतरांसाठी, किंवा अशी कोणतीही कामे ज्यासाठी अतिरिक्त मार्गदर्शन आवश्यक नाही. +**कधी वापरायचे:** सोप्या वर्गीकरणांसाठी, थेट प्रश्नांसाठी, भाषांतरांसाठी, किंवा कोणतेही कार्य जे मॉडेल अधिक मार्गदर्शनाशिवाय हाताळू शकते. ### फ्यू-शॉट प्रॉम्प्टिंग -तुम्हाला पाहिजे त्या नमुन्याचे उदाहरणे द्या ज्याचा आधारे मॉडेल शिकेल. मॉडेल तुमच्या उदाहरणांमधून अपेक्षित इनपुट-आउटपुट फॉरमॅट शिकते आणि नवीन इनपुट्सवर लागू करते. यामुळे त्या कामांसाठी सुसंगती सुधारते जिथे हवा असलेला फॉरमॅट किंवा वर्तन स्पष्ट नसते. +उदाहरणे द्या जी मॉडेलला आपण ज्या नमुन्याचे अनुसरण करावे असे दर्शवतात. मॉडेल आपल्याकडून दिलेल्या उदाहरणांमधून अपेक्षित इनपुट-आउटपुट स्वरूप शिकते आणि ते नवीन इनपुटवर लागू करते. हे सदृढतेत मोठ्या प्रमाणावर सुधारणा करते जिथे इच्छित स्वरूप किंवा वर्तन स्पष्ट नाही. -Few-Shot Prompting +फ्यू-शॉट प्रॉम्प्टिंग -*उदाहरणांमधून शिकणे - मॉडेल नमुना ओळखून नवीन इनपुटवर लागू करते* +*उदाहरणांमधून शिकणे — मॉडेल नमुना ओळखते आणि नवीन इनपुटवर लागू करते* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**कधी वापरावे:** सानुकूल वर्गीकरणासाठी, सुसंगत फॉरमॅटिंगसाठी, क्षेत्रविशिष्ट कामांसाठी, किंवा जेव्हा झीरो-शॉट निकाल सुसंगत नसतात. +**कधी वापरायचे:** सानुकूल वर्गीकरणांसाठी, सुसंगत स्वरूपासाठी, विशिष्ट क्षेत्रातील कार्यांसाठी, किंवा जेव्हा झीरो-शॉट निकाल अस्थिर असतात. ### चेन ऑफ थॉट -मॉडेलला त्याचे विचार टप्प्याटप्प्याने दाखवायला सांगा. सरळ उत्तर देण्याऐवजी, मॉडेल समस्येचे भाग वेगळे करते आणि प्रत्येक भाग स्पष्टपणे हाताळतो. गणित, तर्क, आणि अनेक-टप्प्यांच्या विचारसरणी कामांत याने अचूकता वाढते. +मॉडेलला त्याचे तर्क टप्प्याटप्प्याने दाखवण्यास सांगा. थेट उत्तर देण्याऐवजी, मॉडेल समस्या उलगडतो आणि प्रत्येक भाग स्पष्टपणे कार्यान्वित करतो. हे गणित, तर्क, आणि बहु-टप्प्याच्या तर्क कार्यांसाठी अचूकता वाढवते. -Chain of Thought Prompting +चेन ऑफ थॉट प्रॉम्प्टिंग -*पायरी-दर-पायरी विचारसरणी - जटिल समस्या स्पष्ट तर्कांनी विभागणे* +*टप्प्याटप्प्याने तर्क — गुंतागुंतीच्या समस्यांचे स्पष्ट लॉजिकल टप्पे करणे* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// मॉडेल दाखविते: 15 - 8 = 7, नंतर 7 + 12 = 19 सफरचंदे +// मॉडेल दर्शवितो: 15 - 8 = 7, नंतर 7 + 12 = 19 सफरचंदं ``` -**कधी वापरावे:** गणिती समस्या, तर्क विषयक कोडे, डिबगिंग, किंवा कोणतीही कामे जिथे विचारसरणी दाखवणे अचूकता आणि विश्वास वाढवते. +**कधी वापरायचे:** गणितीय समस्या, तर्क प्रश्न, डीबगिंग, किंवा कोणत्याही कार्यासाठी जिथे तर्क प्रक्रियेचे प्रदर्शन अचूकता आणि विश्वास वाढवते. -### भूमिका-आधारित प्रॉम्प्टिंग +### रोल-आधारित प्रॉम्प्टिंग -AI साठी प्रश्न विचारण्यापूर्वी व्यक्तिमत्व किंवा भूमिका निर्धारित करा. यामुळे प्रतिसादाचा स्वभाव, खोली, आणि लक्ष केंद्रित करण्यासाठी संदर्भ प्रदान होतो. "सॉफ्टवेअर आर्किटेक्ट" चा सल्ला "जूनियर डेव्हलपर" किंवा "सुरक्षा ऑडिटर" यांच्यापेक्षा वेगळा असतो. +AI साठी प्रश्न विचारण्यापूर्वी एक व्यक्तिरेखा किंवा भूमिका सेट करा. हे त्या प्रतिसादाचा टोन, सखोलता आणि फोकस घडवते. “सॉफ्टवेअर आर्किटेक्ट” या भूमिकेकडून वेगळे सल्ले मिळतात “जूनीअर डेव्हलपर” किंवा “सिक्युरिटी ऑडिटर” यांच्या तुलनेत. -Role-Based Prompting +रोल-आधारित प्रॉम्प्टिंग -*संदर्भ आणि व्यक्तिमत्व ठरवणे - एकच प्रश्न वेगवेगळ्या भूमिकांनुसार वेगळी उत्तरे मिळवतो* +*संदर्भ आणि व्यक्तिरेखा सेट करणे — दिलेला प्रश्न दिलेल्या भूमिकेनुसार वेगळ्या प्रकारे उत्तर देतो* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**कधी वापरावे:** कोड पुनरावलोकने, शिकवणी, क्षेत्रविशिष्ट विश्लेषणासाठी, किंवा जेव्हा तुम्हाला विशिष्ट कौशल्य पातळी किंवा दृष्टिकोनानुसार प्रतिसाद हवा असतो. +**कधी वापरायचे:** कोड पुनरावलोकनांसाठी, ट्यूटोरिंगसाठी, क्षेत्रविशिष्ट विश्लेषणासाठी, किंवा जेव्हा आपण परीक्षेची विशिष्ट पातळी किंवा दृष्टीकोन आवश्यक आहे. ### प्रॉम्प्ट टेम्पलेट्स -परिवर्तनीय सावलीसहित पुनरावृत्तीयोग्य प्रॉम्प्ट तयार करा. प्रत्येक वेळी नवा प्रॉम्प्ट लिहिण्याऐवजी एकदा टेम्पलेट तयार करा आणि वेगवेगळ्या मूल्यांने भरा. LangChain4j चा `PromptTemplate` वर्ग `{{variable}}` सिंटॅक्ससह हे सोपे करतो. +चल बदलांसाठी जागा असलेले पुन्हा वापरता येणारे प्रॉम्प्ट तयार करा. प्रत्येक वेळी नवीन प्रॉम्प्ट लिहिण्याऐवजी, एकदा टेम्पलेट तयार करा आणि त्यात वेगवेगळ्या मूल्यांची भर करा. LangChain4j चे `PromptTemplate` वर्ग हे `{{variable}}` सिंटॅक्स वापरून यास सोपे करते. -Prompt Templates +प्रॉम्प्ट टेम्पलेट्स -*परिवर्तनीय सावलीसहित पुनरावृत्तीयोग्य प्रॉम्प्ट - एक टेम्पलेट, अनेक उपयोग* +*चल बदलांसह पुन्हा वापरता येणारे प्रॉम्प्ट — एक टेम्पलेट, अनेक वापर* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**कधी वापरावे:** वेगवेगळ्या इनपुटसह पुनरावृत्ती प्रश्न, बॅच प्रक्रिया, पुनरावृत्तीयोग्य AI वर्कफ्लो बनवताना, किंवा जिथे प्रॉम्प्टची रचना सारखी राहते पण डेटा बदलतो. +**कधी वापरायचे:** वेगवेगळ्या इनपुटसह पुनरावृत्ती प्रश्नांसाठी, बॅच प्रक्रिया, पुन्हा वापरता येणारे AI कार्यप्रवाह तयार करण्यासाठी, किंवा कोणत्याही परिस्थितीत जिथे प्रॉम्प्ट रचना सारखी राहते परंतु डेटा बदलतो. --- -हे पाच मूलतत्त्वे तुम्हाला बहुतांश प्रॉम्प्टिंग कामांसाठी ठोस उपकरणे देतात. नंतरचे हे मॉड्यूल त्यांच्यावर आधारित आहे आठ प्रगत नमुन्यांसह जे GPT-5.2 च्या विचार नियंत्रण, आत्म-मूल्यांकन, आणि संरचित आउटपुट क्षमतांचा वापर करतात. +हे पाच मूलतत्त्वे आपल्याला बहुतेक प्रॉम्प्टिंग कृत्यांसाठी एक मजबूत साधनसामुग्री देतात. या मॉड्युलचा उर्वरित भाग **आठ प्रगत नमुन्यां**वर आधारित आहे जे GPT-5.2 च्या तर्क नियंत्रण, स्व-मूल्यमापन, आणि रचनेत पडण्यासाठी क्षमतेचा उपयोग करतात. ## प्रगत नमुने -मूलतत्त्वे समजून घेतल्यानंतर, चला या मॉड्यूलचे वैशिष्ट्य ठरणारे आठ प्रगत नमुन्यांकडे वळूया. सर्व समस्या समान दृष्टीकोनाची गरज नाही. काही प्रश्नांना जलद उत्तरे हवी असतात, काहींना खोल विचार आवश्यक असतो. काहींना स्पष्ट कारण दर्शवायचे असते, तर काहींना फक्त निकाल पाहिजे. खाली प्रत्येक नमुना वेगळ्या परिस्थितीसाठी अनुकूल केलेले आहे — आणि GPT-5.2 चा विचार नियंत्रण हे फरक अधिक स्पष्ट करतो. +मूलतत्त्वे झाकल्यानंतर, चला आठ प्रगत नमुन्यांकडे वळू जे या मॉड्युलला खास बनवतात. सर्व प्रश्नांसाठी समान दृष्टिकोन आवश्यक नसतो. काही प्रश्नांना वेगवान उत्तरे लागतात, तर काहीना सखोल विचार हवा असतो. काहींना दृश्यमान तर्क हवाअसतो, तर इतरांना फक्त निकाल हवेत. खालील प्रत्येक नमुना वेगळ्या परिस्थितीसाठी ऑप्टिमाइझ केलेले आहे — आणि GPT-5.2 चे तर्क नियंत्रण फरक आणखी स्पष्ट करते. -Eight Prompting Patterns +आठ प्रॉम्प्टिंग नमुने -*आठ प्रॉम्प्ट अभियांत्रण नमुन्यांचा आढावा आणि त्यांचे उपयोग प्रकरणे* +*आठ प्रॉम्प्ट अभियांत्रिकी नमुन्यांचा आढावा आणि त्यांचे उपयोग प्रकरणे* -GPT-5.2 या नमुन्यांना आणखी एक परिमाण देते: *विचार नियंत्रण*. खालील स्लायडर दाखवतो की तुम्ही मॉडेलच्या विचार करण्याच्या प्रयत्नाला कसे समायोजित करू शकता — जलद, थेट उत्तरांपासून खोल, सखोल विश्लेषणापर्यंत. +GPT-5.2 या नमुन्यांना आणखी एक परिमाण जोडते: *तर्क नियंत्रण*. खालील स्लायडर दाखवितो की आपण मॉडेलचा विचार करण्याचा प्रयत्न कसा समायोजित करू शकता — जलद, थेट उत्तरांपासून ते सखोल, पूर्ण विश्लेषणापर्यंत. -Reasoning Control with GPT-5.2 +GPT-5.2 सह तर्क नियंत्रण -*GPT-5.2 चा विचार नियंत्रण तुम्हाला सांगू देतो की मॉडेलने किती विचार करायचा - जलद थेट उत्तरांपासून खोल शोधापर्यंत* +*GPT-5.2 चे तर्क नियंत्रण आपल्याला मॉडेलने किती विचार करायचा हे निर्दिष्ट करण्याची परवानगी देते — जलद थेट उत्तरे ते सखोल शोध यामध्ये* -**कमी विरघळणा विराम (जलद आणि लक्ष केंद्रीत)** - सोप्या प्रश्नांसाठी जिथे तुम्हाला जलद, थेट उत्तरे हवी आहेत. मॉडेल केवळ कमीत कमी विचार करते - कमाल 2 टप्पे. गणना, शोध, किंवा सरळ प्रश्नांसाठी वापरा. +**कमी उत्सुकता (जलद आणि लक्ष केंद्रीत)** - सोप्या प्रश्नांसाठी जेथे आपल्याला जलद, थेट उत्तरे पाहिजेत. मॉडेल किमान तर्क वापरते - कमाल 2 टप्पे. गणना, शोध, किंवा सरळ प्रश्नांसाठी वापरा. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **GitHub Copilot सह एक्सप्लोर करा:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) उघडा आणि विचारा: -> - "कमी विरघळणा विराम आणि उच्च विरघळणा विराम प्रॉम्प्टिंग नमुन्यांमधला फरक काय आहे?" -> - "प्रॉम्प्टमधील XML टॅग्स AI च्या प्रतिसादाची रचना कशी मदत करतात?" -> - "स्वतःच्या परावर्तन नमुने आणि थेट सूचना यामध्ये कधी वापर करावा?" +> - "कमी उत्सुकता आणि जास्त उत्सुकता प्रॉम्प्टिंग नमुन्यांमध्ये काय फरक आहे?" +> - "प्रॉम्प्टमधील XML टॅग्स AI चा प्रतिसाद कसा रचतात?" +> - "स्व-परावर्तन नमुने आणि थेट सूचना कधी वापराव्यात?" -**उच्च विरघळणा विराम (गहन आणि सखोल)** - जटिल समस्यांसाठी जिथे तुम्हाला सखोल विश्लेषण हवे आहे. मॉडेल तपशीलवार विचार करून सविस्तर कारणे दाखवतो. सिस्टम डिझाइन, आर्किटेक्चर निर्णय, किंवा जटिल संशोधनासाठी वापरा. +**जास्त उत्सुकता (सखोल आणि पूर्ण)** - जटिल समस्यांसाठी जिथे आपल्याला सखोल विश्लेषण पाहिजे. मॉडेल सखोलपणे शोधतो आणि सविस्तर तर्क दाखवतो. सिस्टीम डिझाइन, आर्किटेक्चर निर्णय, किंवा जटिल संशोधनासाठी वापरा. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**कार्य अंमलबजावणी (पायरी-दर-पायरी प्रगती)** - अनेक टप्प्यांच्या वर्कफ्लोसाठी. मॉडेल अगोदरपर्यंत योजना देतो, काम करताना प्रत्येक टप्पा सांगतो, नंतर सारांश देतो. स्थलांतर, अंमलबजावणी, किंवा अनेक टप्प्यांच्या कोणत्याही प्रक्रियेसाठी वापरा. +**टास्क अंमलबजावणी (टप्प्याटप्प्याने प्रगती)** - बहु-टप्प्यांच्या कार्यप्रवाहांसाठी. मॉडेल एक आराखडा आधी देतो, प्रत्येक टप्पा काम करताना सांगतो, मग सारांश देतो. माइग्रेशन्स, अंमलबजावणींसाठी किंवा कोणत्याही बहु-टप्प्याच्या प्रक्रियेसाठी वापरा. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -चेन-ऑफ-थॉट प्रॉम्प्टिंग मॉडेलला त्याचा विचार प्रक्रिया स्पष्ट करण्यास सांगते, ज्यामुळे जटिल कामांचे अचूक परिणाम मिळतात. टप्प्याटप्प्याने विभागणे मानव आणि AI दोघांसाठीही तर्क समजून घेण्यास सोपे बनवते. +चेन-ऑफ-थॉट प्रॉम्प्टिंग स्पष्टपणे मॉडेलला त्याचा तर्क प्रक्रिया दर्शवण्यास सांगते, ज्यामुळे जटिल कार्यांवरील अचूकता सुधारते. टप्प्याटप्प्याने विघटन मानव आणि AI दोघांनाही लॉजिक समजण्यात मदत करते. -> **🤖 GitHub Copilot चॅटसह प्रयत्न करा:** या नमुन्याबद्दल विचारा: -> - "लाँग-रनिंग ऑपरेशन्ससाठी कार्य अंमलबजावणी नमुना कसा अनुकूल करेन?" -> - "उत्पादन अनुप्रयोगांमध्ये टूल प्रीइम्बल्स रचनेच्या सर्वोत्तम पद्धती काय आहेत?" -> - "UI मध्ये मध्ये प्रगती अद्यतने कशी टिपणे आणि दाखवणे शक्य आहे?" +> **🤖 GitHub Copilot चॅट सह प्रयत्न करा:** या नमुन्याबद्दल विचारा: +> - "लांब चालणाऱ्या ऑपरेशनसाठी टास्क अंमलबजावणी नमुना कसा जुळवेन?" +> - "प्रोडक्शन अॅप्लिकेशन्समध्ये टूल प्रीअ‍ॅंबल्सचे रचनेतील सर्वोत्तम पद्धती काय आहेत?" +> - "UI मध्ये मधल्या प्रगतीच्या अपडेट्स कसे कॅप्चर आणि प्रदर्शित करायचे?" -खालील आकृती या योजना → अंमलबजावणी → सारांश वर्कफ्लोचे चित्रण करते. +खालील आकृती हा Plan → Execute → Summarize कार्यप्रवाह दर्शविते. -Task Execution Pattern +टास्क अंमलबजावणी नमुना -*अनेक टप्प्यांच्या कामासाठी योजना → अंमलबजावणी → सारांश वर्कफ्लो* +*बहु-टप्प्यांच्या कार्यांसाठी Plan → Execute → Summarize कार्यप्रवाह* -**स्वतःचे चिंतन करणारा कोड** - उत्पादन-स्तरीय कोड तयार करण्यासाठी. मॉडेल उत्पादन मानकांचे पालन करत कोड निर्माण करतो ज्यामध्ये योग्य त्रुटी हाताळणी आहे. नवीन वैशिष्ट्ये किंवा सेवा तयार करताना वापरा. +**स्वतःचे परावर्तन करणारा कोड** - उत्पादन-गुणवत्तेचा कोड तयार करण्यासाठी. मॉडेल उत्पादन मानकांनुसार योग्य त्रुटी हाताळणीसह कोड तयार करतो. नवीन वैशिष्ट्ये किंवा सेवा तयार करताना वापरा. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -खालील आकृती हा पुनरावृत्ती सुधारणा लूप दाखवते — तयार करा, मूल्यमापन करा, कमकुवत भाग ओळखा, आणि कोड उत्पादन मानक पूर्ण करतो तोपर्यंत सुधारणा करा. +खालील आकृती हा पुनरावृत्ती सुधारणा चक्र दर्शविते — तयार करा, मूल्यमापन करा, कमकुवत बाजू शोधा, आणि कोड उत्पादन मानक पूर्ण होईपर्यंत सुधारणा करा. -Self-Reflection Cycle +स्व-परावर्तन चक्र -*पुनरावृत्ती सुधारणा लूप - तयार करा, मूल्यमापन करा, समस्या ओळखा, सुधारणा करा, पुनरावृत्ती करा* +*परावृत्ती सुधारणा चक्र - तयार करा, मूल्यमापन करा, समस्या ओळखा, सुधारणा करा, पुन्हा करा* -**संरचित विश्लेषण** - सुसंगत मूल्यमापनासाठी. मॉडेल कोडचे पुनरावलोकन निश्चित चौकटीतून करतो (योग्यता, सराव, कार्यक्षमता, सुरक्षा, देखरेख योग्यपणा). कोड पुनरावलोकने किंवा गुणवत्ता मूल्यांकनासाठी वापरा. +**रचनेत विश्लेषण** - सुसंगत मूल्यमापनासाठी. मॉडेल स्थिर फ्रेमवर्क (योग्यता, सराव, कार्यक्षमता, सुरक्षा, देखभालयोग्यता) वापरून कोड पुनरावलोकन करते. कोड पुनरावलोकन किंवा गुणवत्ता मूल्यांकनासाठी वापरा. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 GitHub Copilot चॅटसह प्रयत्न करा:** संरचित विश्लेषणाबद्दल विचारा: -> - "विविध प्रकारच्या कोड पुनरावलोकनांसाठी विश्लेषण चौकट कशी सानुकूल करावी?" -> - "संरचित आउटपुट प्रोग्रामॅटिकली कसे पार्स आणि वापरावे?" -> - "विभिन्न पुनरावलोकन सत्रांमध्ये सुसंगत गंभीरता पातळी कशी सुनिश्चित करावी?" +> **🤖 GitHub Copilot चॅट सह प्रयत्न करा:** रचनेत विश्लेषणाबद्दल विचारा: +> - "वेगवेगळ्या प्रकारच्या कोड पुनरावलोकनांसाठी विश्लेषण फ्रेमवर्क कसा सानुकूल करावा?" +> - "रचनेत आउटपुट प्रोग्रामॅटिकली पार्स व क्रियान्वित करण्याचा सर्वोत्तम मार्ग कोणता?" +> - "वेगवेगळ्या पुनरावलोकन सत्रांमध्ये गंभीरतेचे स्तर कसे सुसंगत ठेवायचे?" -खालील आकृती या संरचित चौकटीने गंभीरता पातळींसह कोड पुनरावलोकन कसे आयोजित होते हे दाखवते. +खालील आकृती दाखवते की ही रचनाबद्ध चौकट कशी कोड पुनरावलोकनाला सुसंगत श्रेण्यांमध्ये आणि गंभीरता स्तरांसह आयोजित करते. -Structured Analysis Pattern +रचनेत विश्लेषण नमुना -*सुसंगत कोड पुनरावलोकनांसाठी गंभीरता पातळींसह चौकट* +*गंभीरता स्तरांसह सुसंगत कोड पुनरावलोकनांसाठी फ्रेमवर्क* -**अनेकच पर्यटन संवाद** - संदर्भ आवश्यक असलेल्या संभाषणांसाठी. मॉडेल मागील संदेश लक्षात ठेवतो आणि त्यावर पुढे निर्माण करतो. संवादात्मक मदत सत्रे किंवा जटिल प्रश्न-उत्तरांसाठी वापरा. +**मल्टी-टर्न चॅट** - ज्यांना संदर्भाची गरज आहे अशा संवादांसाठी. मॉडेल मागील संदेश लक्षात ठेवते आणि त्यावर आधारित पुढे वाढवते. संवादात्मक मदत सत्रे किंवा जटिल प्रश्नोत्तरांसाठी वापरा. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -खालील आकृती दाखवते की संभाषण संदर्भ कसप्रकारे प्रत्येक टप्प्यात जमा होतो आणि तो मॉडेलच्या टोकन मर्यादेशी कसा संबंधित आहे. +खाली आकृती दाखवते की संवाद संदर्भ कसा अनेक टप्प्यांत जमा होतो आणि तो मॉडेलच्या टोकन मर्यादेशी कसा संबंधित आहे. -Context Memory +संदर्भ मेमरी -*अनेक टप्प्यांच्या संभाषण संदर्भाचा जमा होण्याचा प्रकार जोपर्यंत टोकन मर्यादेत पोहोचत नाही* -**पायरी-दर-पायरी तर्क** - दृश्यमान तर्क आवश्यक असलेल्या समस्या साठी. मॉडेल प्रत्येक टप्प्याकरिता स्पष्ट तर्क दर्शविते. गणिताच्या समस्या, तर्कशास्त्रीय कोडे, किंवा विचारांची प्रक्रिया समजून घेण्यासाठी याचा वापर करा. +*संवाद संदर्भ अनेक टप्प्यांमध्ये जमा होतो जोपर्यंत टोकन मर्यादेला पोहोचत नाही* + +**टप्प्याटप्प्याने तर्क** - दृश्यिय लॉजिकची आवश्यकता असलेल्या समस्या साठी. मॉडेल प्रत्येक टप्प्यासाठी स्पष्ट तर्क दाखवते. गणित समस्या, तर्क प्रश्न, किंवा विचार प्रक्रिया समजून घेण्याची गरज असेल तेव्हा वापरा. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -खालील आकृती दाखवते की मॉडेल समस्या कशा रीतीने स्पष्ट, नंबर दिलेल्या तर्कशुद्ध पावलांमध्ये विभागते. - -पायरी-दर-पायरी नमुना +खाली आकृती दाखवते की मॉडेल समस्या कशा स्पष्ट, क्रमांकित तर्क टप्प्यांमध्ये विभाजित करते. -*समस्यांचे स्पष्ट तर्कशुद्ध पावलांमध्ये विभागणी* +टप्प्याटप्प्याने नमुना +*समस्यांचे स्पष्ट तार्किक टप्प्यांमध्ये विभाजन करणे* -**बाध्य आउटपुट** - विशिष्ट फॉरमॅट आवश्यकतांसह प्रतिसादांसाठी. मॉडेल काटेकोरपणे फॉरमॅट आणि लांबी नियमांचे पालन करते. सारांशासाठी किंवा नेमकी आउटपुट संरचना हवी असेल तेव्हा याचा वापर करा. +**मर्यादित आउटपुट** - विशिष्ट फॉरमॅट आवश्यकता असलेल्या प्रतिसादांसाठी. मॉडेल फॉरमॅट आणि लांबी नियम काटेकोरपणे पाळते. सारांशांसाठी किंवा तुम्हाला अचूक आउटपुट रचना आवश्यक असल्यास याचा वापर करा. ```java String prompt = """ @@ -420,61 +420,61 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -खालील आकृती दर्शवते की प्रतिबंध मॉडेलला तुमच्या फॉरमॅट आणि लांबीच्या आवश्यकतांचे काटेकोर पालन करून आउटपुट तयार करायला कसे मार्गदर्शन करतात. +खालील आकृतीमध्ये दाखवले आहे की कसे बंधने मॉडेलला आउटपुट तयार करताना तुमच्या फॉरमॅट आणि लांबीच्या अटींचे काटेकोर पालन करण्यासाठी मार्गदर्शन करतात. -बाध्य आउटपुट नमुना +मर्यादित आउटपुट पॅटर्न -*विशिष्ट फॉरमॅट, लांबी, आणि संरचना आवश्यकतांचे पालन करणे* +*विशिष्ट फॉरमॅट, लांबी आणि रचना आवश्यकता लागू करणे* -## अॅप्लिकेशन चालवा +## अनुप्रयोग चालवा **तैनातीची पडताळणी करा:** -मुळे `.env` फाइल मुख्य निर्देशिकेत अस्तित्वात आहे याची खात्री करा ज्यात Azure क्रेडेंशियल्स असतात (Module 01 दरम्यान तयार केलेली). हे `02-prompt-engineering/` मॉड्यूल निर्देशिकेतून चालवा: +रूट डिरेक्टरीमध्ये `.env` फाइल अस्तित्वात आहे का याची खात्री करा ज्यात Azure क्रेडेन्शियल्स आहेत (Module 01 दरम्यान तयार केलेली). हे मॉड्यूल डिरेक्टरी (`02-prompt-engineering/`) मधून चालवा: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दर्शवावे +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवायला हवे ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवले पाहिजेत +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवले पाहिजे ``` -**अॅप्लिकेशन सुरू करा:** +**अनुप्रयोग सुरू करा:** -> **टीप:** जर तुम्ही मुख्य निर्देशिकेतून `./start-all.sh` वापरून आधीच सर्व अॅप्लिकेशन्स सुरू केले असतील (Module 01 मध्ये सांगितल्याप्रमाणे), तर हे मॉड्यूल पोर्ट 8083 वर आधीच चालू आहे. खालील सुरू करण्याच्या आदेशांना तुम्ही वगळू शकता आणि थेट http://localhost:8083 वर जाऊ शकता. +> **टीप:** जर तुम्ही आधीच सर्व अनुप्रयोग रूट डिरेक्टरीमधून `./start-all.sh` वापरून चालू केले असतील (Module 01 मध्ये वर्णन केल्याप्रमाणे), तर हे मॉड्यूल पोर्ट 8083 वर चालू आहे. तुम्ही खालील स्टार्ट आदेश विसरून थेट http://localhost:8083 वर जाऊ शकता. -**पर्याय 1: Spring Boot डॅशबोर्ड वापरून (VS Code वापरकर्त्यांसाठी शिफारसीय)** +**पर्याय 1: Spring Boot डॅशबोर्ड वापरून (VS Code वापरकर्त्यांसाठी शिफारस केलेले)** -डेव्ह कंटेनरमध्ये Spring Boot डॅशबोर्ड एक्स्टेंशन आहे, जे सर्व Spring Boot अॅप्लिकेशन्स व्यवस्थापित करण्यासाठी दृश्य इंटरफेस पुरवते. हे VS Code च्या डाव्या बाजूच्या Activity Bar मध्ये (Spring Boot चिन्ह शोधा) आढळू शकते. +डिव्ह कंटेनरमध्ये Spring Boot डॅशबोर्ड विस्तार समाविष्ट आहे, जो सर्व Spring Boot अनुप्रयोगांचे व्यवस्थापन करण्यासाठी दृश्य इंटरफेस पुरवतो. तुम्हाला तो VS Code च्या डाव्या बाजूच्या अॅक्टिव्हिटी बारमध्ये Spring Boot आयकॉन म्हणून दिसेल. Spring Boot डॅशबोर्डमधून तुम्ही: -- कार्यक्षेत्रातील सर्व उपलब्ध Spring Boot अॅप्लिकेशन्स पाहू शकता -- एका क्लिकने अॅप्लिकेशन्स सुरू/थांबवू शकता -- अॅप्लिकेशन लॉग्स वास्तविक वेळेत पाहू शकता -- अॅप्लिकेशनची स्थिती पाहू शकता +- वर्कस्पेसमधील सर्व उपलब्ध Spring Boot अनुप्रयोग पाहू शकता +- एकाच क्लिकने अनुप्रयोग सुरू/थांबवू शकता +- अनुप्रयोगाच्या लॉग्सचे रिअल-टाइममध्ये निरीक्षण करू शकता +- अनुप्रयोगाची स्थिती पाहू शकता -फक्त "prompt-engineering" पुढील प्ले बटणावर क्लिक करा आणि हे मॉड्यूल सुरू करा, किंवा सर्व मॉड्यूल एकवेळी सुरू करा. +सोप्या क्लिकने "prompt-engineering" च्या बाजूला प्ले बटण दाबून हे मॉड्यूल सुरू करा, किंवा एकाच वेळी सर्व मॉड्यूल सुरू करा. Spring Boot डॅशबोर्ड -*VS Code मधील Spring Boot डॅशबोर्ड — एका ठिकाणी सर्व मॉड्यूल सुरू, थांबवा, आणि निरीक्षण करा* +*VS Code मधील Spring Boot डॅशबोर्ड — एकाच ठिकाणी सर्व मॉड्यूल सुरू, थांबवा आणि निरीक्षण करा* -**पर्याय 2: शेल स्क्रिप्ट्स वापरून** +**पर्याय 2: शेल स्क्रिप्ट वापरून** -सर्व वेब अॅप्लिकेशन्स (modules 01-04) सुरू करा: +सर्व वेब अनुप्रयोग (मॉड्यूल 01-04) सुरू करा: **Bash:** ```bash -cd .. # मूळ निर्देशिका पासून +cd .. # रूट निर्देशिकेतून ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # मूळ संचिकालयातून +cd .. # रूट डिरेक्टरीमधून .\start-all.ps1 ``` @@ -492,16 +492,16 @@ cd 02-prompt-engineering .\start.ps1 ``` -दोन्ही स्क्रिप्ट्स स्वयंचलितपणे मुख्य `.env` फाइलमधील पर्यावरणीय चल लोड करतात आणि जर JAR अस्तित्वात नसेल तर तयार करतात. +दोन्ही स्क्रिप्ट रूट `.env` फाइलमधून स्वयंचलितपणे पर्यावरणीय चल लोड करतात आणि जर JARs अस्तित्वात नसतील तर तयार करतात. -> **टीप:** जर तुम्हाला सुरू करण्यापूर्वी सर्व मॉड्यूल्स मनुष्यबळाने तयार करायची असतील: +> **टीप:** तुम्हाला सर्व मॉड्यूल मॅन्युअली तयार करून सुरू करायचे असल्यास: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -514,95 +514,95 @@ cd 02-prompt-engineering **Bash:** ```bash -./stop.sh # हा फक्त मोड्यूल +./stop.sh # हे फक्त मॉड्यूल # किंवा -cd .. && ./stop-all.sh # सर्व मोड्यूल्स +cd .. && ./stop-all.sh # सर्व मॉड्यूल ``` **PowerShell:** ```powershell -.\stop.ps1 # हा फक्त मॉड्युल +.\stop.ps1 # ही फक्त मॉड्यूल # किंवा -cd ..; .\stop-all.ps1 # सर्व मॉड्युल्स +cd ..; .\stop-all.ps1 # सर्व मॉड्यूल्स ``` -## अॅप्लिकेशन स्क्रीनशॉट +## अनुप्रयोगाचे स्क्रीनशॉट -खाली दिलेला हा मुख्य इंटरफेस आहे जिथे तुम्ही सर्व आठ नमुने पॅरेलेलपणे प्रयोग करू शकता. +येथे हा prompt engineering मॉड्यूलचा मुख्य इंटरफेस आहे, जिथे तुम्ही एकाच वेळेस सर्व आठ पॅटर्नची चाचणी करू शकता. -डॅशबोर्ड मुख्यपृष्ठ +डॅशबोर्ड होम -*मुख्य डॅशबोर्ड जेथे सर्व 8 prompt engineering नमुने त्यांची वैशिष्ट्ये आणि उपयोगप्रकरणांसह दाखवले आहेत* +*मुख्य डॅशबोर्ड ज्यात सर्व 8 prompt engineering पॅटर्न, त्यांचे वैशिष्ट्ये आणि वापर प्रकरणे दाखवली आहेत* -## नमुन्यांच्या शोधाशोध +## पॅटर्न्सचे अन्वेषण करणे -वेब इंटरफेस तुम्हाला वेगवेगळ्या प्रॉम्प्टिंग धोरणांसह प्रयोग करण्याची परवानगी देते. प्रत्येकी नमुना वेगवेगळी समस्या सोडवतो - पाहा तेव्हा कोणता दृष्टिकोन कधी चमकतो. +वेब इंटरफेस तुम्हाला विविध प्रॉम्प्टिंग रणनीती वापरून पाहण्याची संधी देते. प्रत्येक पॅटर्न वेगवेगळ्या समस्या सोडवतो - ते वापरून पाहा आणि पाहा की कोणती पद्धत केव्हा चमकते. -> **टीप: स्ट्रीमिंग विरुद्ध नॉन-स्ट्रीमिंग** — प्रत्येक नमुन्याच्या पृष्ठावर दोन बटणे दिली आहेत: **🔴 Stream Response (Live)** आणि एक **Non-streaming** पर्याय. स्ट्रीमिंग सर्व्हर-सेंट इव्हेंट्स (SSE) वापरून टोकन्स वास्तविक वेळेत दाखवते कारण मॉडेल त्यांना तयार करते, म्हणून तुम्हाला प्रगती लगेच दिसते. नॉन-स्ट्रीमिंग पर्याय पूर्ण प्रतिसादाचा प्रतिक्षा करतो मग प्रदर्शन करतो. जर खोल reasoning आवश्यक असेल (उदा., High Eagerness, Self-Reflecting Code) तर नॉन-स्ट्रीमिंग कॉल खूप वेळ घेऊ शकतो — कधी कधी मिनिटे — कोणतीही दृश्यमान प्रतिक्रिया न येता. **जटिल प्रॉम्प्ट्ससाठी स्ट्रीमिंग वापरा** जेणेकरून तुम्हाला मॉडेल काम करताना दिसेल आणि विनंतीची वेळ संपल्याची भावना येणार नाही. +> **टीप: स्ट्रिमिंग विरुद्ध नॉन-स्ट्रिमिंग** — प्रत्येक पॅटर्न पेजवर दोन बटणे असतात: **🔴 Stream Response (Live)** आणि **Non-streaming** पर्याय. स्ट्रिमिंग Server-Sent Events (SSE) वापरून टोकन्स वास्तविक वेळेत दाखवते जसे मॉडेल तयार करत असते, त्यामुळे तुम्हाला प्रगती लगेच दिसते. नॉन-स्ट्रिमिंग पर्याय संपूर्ण प्रतिसाद येईपर्यंत वाट पाहतो. खोलगट विचार करणाऱ्या प्रॉम्प्टसाठी (उदा., High Eagerness, Self-Reflecting Code), नॉन-स्ट्रिमिंग कॉल खूप वेळ घेऊ शकतो — कधी कधी मिनिटे — आणि कोणताही दृश्य अभिप्राय नाही. **गुंतागुंतीच्या प्रॉम्प्टसह प्रयोग करताना स्ट्रिमिंग वापरा** जेणे करून तुम्हाला मॉडेलचे कार्य चालतेय हे दिसेल आणि विनंती वेळ संपल्याचा भास टळेल. > -> **टीप: ब्राउझर आवश्यकता** — स्ट्रीमिंग फिचर Fetch Streams API (`response.body.getReader()`) वापरते, जे पूर्ण ब्राउझरमध्ये (Chrome, Edge, Firefox, Safari) आवश्यक आहे. हे VS Code च्या अंगभूत Simple Browser मध्ये काम करत नाही कारण त्याचे वेबव्ह्यू ReadableStream API ला समर्थन देत नाही. Simple Browser वापरत असल्यास, नॉन-स्ट्रीमिंग बटणे नेहमीप्रमाणे कार्य करतील — फक्त स्ट्रीमिंग बटणे प्रभावित होतील. संपूर्ण अनुभवासाठी `http://localhost:8083` बाह्य ब्राउझरमध्ये उघडा. +> **टीप: ब्राउझरची गरज** — स्ट्रिमिंग वैशिष्ट्य Fetch Streams API (`response.body.getReader()`) वापरते, ज्यासाठी पूर्ण ब्राउझर (Chrome, Edge, Firefox, Safari) आवश्यक आहे. हे VS Code च्या अंगभूत Simple Browser मध्ये चालत नाही कारण त्याच्या वेबव्ह्यूमध्ये ReadableStream API ची समर्थन नाही. जर तुम्ही Simple Browser वापरत असाल तर नॉन-स्ट्रिमिंग बटणे नेहमीप्रमाणे काम करतील — फक्त स्ट्रिमिंग बटण प्रभावित राहील. पूर्ण अनुभवासाठी `http://localhost:8083` बाह्य ब्राउझरमध्ये उघडा. -### कमी विरुद्ध जास्त उत्सुकता +### Low vs High Eagerness -"200 चा 15% काय आहे?" अशी सोपी विचारणा कमी उत्सुकतेसह विचारा. तुम्हाला त्वरित, थेट उत्तर मिळेल. आता "उच्च-ट्रॅफिक API साठी कॅशिंग धोरण डिझाईन करा" अशी गुंतागुंतीची विचारणा जास्त उत्सुकतेसह विचारा. **🔴 Stream Response (Live)** क्लिक करा आणि मॉडेलचे तपशीलवार तर्क टोकननिहाय पाहा. एकच मॉडेल, एकच प्रश्न रचना पण प्रॉम्प्ट सुद्धा सांगते किती विचार करायचा. +Low Eagerness वापरून "15% of 200 काय आहे?" असा साधा प्रश्न विचारा. तुम्हाला त्वरीत, थेट उत्तर मिळेल. आता High Eagerness वापरून "उच्च ट्रॅफिक API साठी कॅशिंग धोरण डिझाइन करा" असा गुंतागुंतीचा प्रश्न विचारा. **🔴 Stream Response (Live)** क्लिक करा आणि मॉडेलचे सखोल चिंतन टोकन-दर-टोकन दिसेल. एकच मॉडेल, एकच प्रश्न रचना — परंतु प्रॉम्प्ट मॉडेलला किती विचार करायचा आहे ते सांगते. -### कार्य अंमलबजावणी (टूल प्रीअँबल्स) +### Task Execution (Tool Preambles) -बहु-टप्प्याच्या कार्यप्रवाहास आगाऊ योजना आणि प्रगती कथन फायदेशीर ठरते. मॉडेल काय करणार आहे ते अधोरेखित करते, प्रत्येक टप्पा वर्णन करते, मग निकाल सारांशित करते. +अनेक टप्प्यांचे वर्कफ्लोज अग्रिम योजना आणि प्रगती वर्णनातून लाभ घेतात. मॉडेल काय करणार आहे ते सांगते, प्रत्येक टप्पा वर्णन करते आणि नंतर निकाल सारांशित करते. -### आत्मतपासणी करणारा कोड +### Self-Reflecting Code -"ईमेल व्हॅलिडेशन सेवा तयार करा" असे प्रयत्न करा. फक्त कोड तयार करण्याऐवजी आणि थांबण्याऐवजी, मॉडेल कोड तयार करते, गुणवत्तेच्या निकषांनुसार मूल्यमापन करते, कमकुवतपणा शोधते, आणि सुधारणा करते. तुम्हाला ते कोड उत्पादन मानकांपर्यंत पोहोचवताना केसेस पाहायला मिळतील. +"Create an email validation service" चा प्रयत्न करा. फक्त कोड तयार करून थांबण्याऐवजी, मॉडेल तयार करते, गुणवत्ता निकषांवर मूल्यांकन करते, कमकुवत भाग ओळखते आणि सुधारणा करते. तुम्हाला ते पुनरावृत्ती करताना दिसेल जोपर्यंत कोड उत्पादन मानकांनुसार बना होत नाही. -### संरचित विश्लेषण +### Structured Analysis -कोड पुनरावलोकन सुसंगत मूल्यांकन चौकटीची गरज असते. मॉडेल कोडचे विश्लेषण निश्चित वर्गानुसार करते (बरोबरी, सराव, कार्यक्षमते, सुरक्षा) आणि गंभीरतेच्या स्तरांसह. +कोड पुनरावलोकनांसाठी सातत्यपूर्ण मूल्यांकन फ्रेमवर्क आवश्यक आहे. मॉडेल कोडचे विश्लेषण निश्चित विभागांमध्ये (योग्यता, पद्धती, कार्यक्षमता, सुरक्षा) आणि गंभीरतेच्या स्तरांसह करते. -### बहु-टर्न चॅट +### Multi-Turn Chat -"Spring Boot काय आहे?" असा प्रश्न विचारा आणि लगेच "उदाहरण दाखवा" असे मागणी करा. मॉडेल तुमचा पहिला प्रश्न लक्षात ठेवते आणि तुम्हाला विशेषतः Spring Boot चे उदाहरण देते. स्मृती नसेल तर दुसरा प्रश्न फारसा अस्पष्ट राहील. +"Spring Boot काय आहे?" असा प्रश्न विचारा आणि लगेच "मला उदाहरण दाखवा" असा पुढचा प्रश्न विचारा. मॉडेल तुमचा पहिला प्रश्न लक्षात ठेवतो आणि विशिष्ट Spring Boot उदाहरण देते. स्मृती नसेल तर दुसरा प्रश्न फार अस्पष्ट राहील. -### पायरी-दर-पायरी तर्क +### Step-by-Step Reasoning -गणिताचा प्रश्न निवडा आणि त्याला पायरी-दर-पायरी तर्क आणि कमी उत्सुकतेसह प्रयत्न करा. कमी उत्सुकता तुम्हाला फक्त उत्तर देते - जलद परंतु अस्पष्ट. पायरी-दर-पायरी तर्क प्रत्येक गणना आणि निर्णय दाखवते. +कोणीही गणिती समस्या निवडा आणि ती Step-by-Step Reasoning व Low Eagerness या दोन्हीने तपासा. Low eagerness फक्त उत्तर देते - जलद परंतु अस्पष्ट. Step-by-step तुम्हाला प्रत्येक गणना आणि निर्णय दाखवते. -### बाध्य आउटपुट +### Constrained Output -जेव्हा तुम्हाला विशिष्ट फॉरमॅट किंवा शब्दसंख्या आवश्यक असेल, तेव्हा हा नमुना काटेकोर पालन करतो. अचूक 100 शब्दांच्या बुलेट पॉइंट स्वरूपात सारांश तयार करण्याचा प्रयत्न करा. +ज्यावेळी तुम्हाला विशिष्ट फॉरमॅट किंवा शब्दसंख्या हवी असते, त्या वेळी हा पॅटर्न काटेकोर पालन करून आउटपुट देते. काढलेले सारांश नक्की 100 शब्दांत बुलेट पॉईंट स्वरुपात तयार करा. -## तुम्ही खरंच काय शिकत आहात +## तुम्ही खरोखर काय शिकत आहात -**तर्क करण्याचा प्रयत्न सर्वकाही बदलतो** +**चिंतन प्रयत्न सर्वकाही बदलतो** -GPT-5.2 तुम्हाला तुमच्या प्रॉम्प्ट्स द्वारे संगणकीय प्रयत्न नियंत्रित करण्याची अनुमती देते. कमी प्रयत्न म्हणजे जलद प्रतिसाद आणि कमी अन्वेषण. जास्त प्रयत्न म्हणजे मॉडेल काळ घालवून खोल विचार करते. तुम्ही प्रयत्न कार्याच्या गुंतागुंतीनुसार जुळवण्यास शिकत आहात - सोप्या प्रश्नांवर वेळ वाया घालवू नका, पण गुंतागुंतीच्या निर्णयांवरही घाई करू नका. +GPT-5.2 तुम्हाला तुमच्या प्रॉम्प्टद्वारे संगणकीय प्रयत्न नियंत्रित करण्याची मुभा देतो. कमी प्रयत्न म्हणजे त्वरीत प्रतिसाद कमी शोध घेऊन. जास्त प्रयत्न म्हणजे मॉडेल खोल विचार करण्यासाठी वेळ घेतो. तुम्ही शिकत आहात की प्रयत्न किती करायचा ते कामाच्या गुंतागुंतीनुसार ठरवा - सोप्या प्रश्नांवर वेळ वाया घालवू नका, पण जटिल निर्णयही घाईघोडीने करू नका. -**संरचना वर्तनाला मार्गदर्शित करते** +**रचना वर्तन मार्गदर्शन करते** -प्रॉम्प्टमधील XML टॅग्स लक्षात ठेवा? ते सजावटीसाठी नाहीत. मॉडेल्स संरचित सूचना मुक्तपणे दिलेल्या मजकूरत्या पेक्षा जास्त विश्वासार्हपणे पाळतात. जेव्हा बहु-टप्प्याचे प्रक्रिया किंवा गुंतागुंतीचा तर्क आवश्यक असेल, तेव्हा संरचना मॉडेलला त्याचा स्थान आणि पुढील काय करावे हे ट्रॅक करण्यात मदत करते. खालील आकृती एक नीट-संरचित प्रॉम्प्ट कसा दिसतो, त्यातील ``, ``, ``, ``, आणि `` सारखे टॅग कसे स्पष्ट विभाग करतात, हे दाखवते. +प्रॉम्प्टमधील XML टॅग्स तुम्हाला दिसलेत का? ते सजावटीसाठी नाहीत. मॉडेल मुक्त स्वरूपाच्या मजकूरापेक्षा संरचित सूचनांचे अधिक विश्वसनीयपणे पालन करतात. तुम्हाला अनेक टप्प्यांचे पद्धत किंवा गुंतागुंतीचे लॉजिक हवे असल्यास, रचना मॉडेलला त्याचा स्थिती आणि पुढे काय करायचे ते ट्रॅक करण्यास मदत करते. खालील आकृती एक चांगल्या रचनेच्या प्रॉम्प्टचे विहंगम दर्शन देते, ज्यात ``, ``, ``, ``, आणि `` सारखे टॅग्स चांगल्या विभागांमध्ये मार्गदर्शन करतात. -प्रॉम्प्ट स्ट्रक्चर +प्रॉम्प्ट रचना -*एक नीट-संरचित प्रॉम्प्टची रचना जी स्पष्ट विभाग आणि XML-शैली संरचना दाखवते* +*स्पष्ट विभागांसह आणि XML शैलीचे आयोजन असलेले उत्तम रचनेचे प्रॉम्प्टचे अॅनाटॉमी* -**गुणवत्तेचे स्व-मूल्यमापनाद्वारे आश्वासन** +**स्वतःच्या मूल्यांकनाद्वारे गुणवत्ता** -आत्मतपासणी करणारे नमुने गुणवत्तेचे निकष स्पष्टपणे मांडून कार्य करतात. मॉडेल "बरोबर करेल" अशी आशा ठेवण्याऐवजी तुम्ही त्याला नेमके काय "बरोबर" आहे ते सांगता: योग्य तर्क, त्रुटी हाताळणी, कार्यक्षमता, सुरक्षा. मग मॉडेल स्वतःचे आउटपुट मूल्यांकन करू शकते आणि सुधारू शकते. यामुळे कोड निर्मिती लॉटरीऐवजी प्रक्रियेत रूपांतरित होते. +स्वत:चं प्रतिबिंबित करणारे पॅटर्न explicit गुणवत्ता निकष ठरवून कार्य करतात. "मॉडेल बरोबर करेल" अशी अपेक्षा करण्याऐवजी, तुम्ही मॉडेलला नेमके काय बरोबर आहे ते सांगता: योग्य लॉजिक, त्रुटी हाताळणी, कार्यक्षमता, सुरक्षा. मॉडेल नंतर स्वतःच्या आउटपुटचे मूल्यांकन करू शकतो आणि सुधारणा करतो. त्यामुळे कोड निर्माण करणं लॉटरीसारखं नसून प्रक्रियेमध्ये रूपांतरित होते. **संदर्भ मर्यादित आहे** -बहु-टर्न संवाद प्रत्येक विनंती सोबत संदेश इतिहास समाविष्ट करतात. पण एक मर्यादा आहे - प्रत्येक मॉडेलचा कमाल टोकन मर्यादा असते. संवाद वाढत असल्यावर तुम्हाला संबंधित संदर्भ टिकवण्यासाठी धोरणे वापरावी लागतात, पण त्या मर्यादेत अडकल्या शिवाय. हे मॉड्यूल तुम्हाला स्मृती कशी कार्य करते हे दाखवते; नंतर तुम्ही कधी सारांश द्यायचा, कधी विसरायचे, आणि कधी पुनर्प्राप्त करायचे ते शिकाल. +अनेक टप्प्यांच्या संवादांमध्ये प्रत्येक विनंतीसोबत संदेश इतिहास असतो. पण सीमा आहे - प्रत्येक मॉडेलची टोकन मर्यादा आहे. संवाद वाढल्यावर संबंधित संदर्भ टिकवण्यासाठी तुम्हाला धोरणे वापरावी लागतील ज्यामुळे त्या मर्यादेपर्यंत पोहोचू नये. हे मॉड्यूल तुम्हाला स्मृती कशी काम करते हे दाखवते; नंतर तुम्हाला शिकायला मिळेल की केव्हा सारांश करायचा, केव्हा विसरायचं आणि केव्हा पुन्हा शोधायचं. -## पुढील टप्पे +## पुढचे टप्पे -**पुढील मॉड्यूल:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**पुढचे मॉड्यूल:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**नेव्हिगेशन:** [← मागील: Module 01 - परिचय](../01-introduction/README.md) | [मुख्यपृष्ठाकडे परत](../README.md) | [पुढील: Module 03 - RAG →](../03-rag/README.md) +**नेव्हिगेशन:** [← मागील: मॉड्यूल 01 - परिचय](../01-introduction/README.md) | [मुख्य पृष्ठावर परत या](../README.md) | [पुढचे: मॉड्यूल 03 - RAG →](../03-rag/README.md) --- -**免责声明**: -हा दस्तऐवज AI भाषांतर सेवेचा [Co-op Translator](https://github.com/Azure/co-op-translator) वापरून भाषांतरित करण्यात आला आहे. आम्ही अचूकतेसाठी प्रयत्न करत असलो तरी, कृपया लक्षात घ्या की स्वयंचलित भाषांतरांमध्ये चुका किंवा अप्रशुद्धता असू शकते. मूळ दस्तऐवज त्याच्या स्थानिक भाषेत अधिकृत स्त्रोत मानला पाहिजे. महत्वाच्या माहितीसाठी व्यावसायिक मानवी भाषांतर सुचवले आहे. या भाषांतराच्या वापरातून होणाऱ्या कोणत्याही गैरसमजुतीसाठी किंवा चुकीच्या समजुतीसाठी आम्ही जबाबदार नाही. +**अस्वीकरण**: +हा दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) चा वापर करून अनुवादित केला आहे. जरी आम्ही अचूकतेसाठी प्रयत्न करतो, तरी कृपया लक्षात घ्या की स्वयंचलित भाषांतरांमध्ये त्रुटी किंवा अचूकतेची कमतरता असू शकते. मूळ दस्तऐवज त्याच्या मूळ भाषेत अधिकृत स्रोत मानला पाहिजे. महत्त्वाची माहिती असल्यास, व्यावसायिक मानवी भाषांतराची शिफारस केली जाते. या भाषांतराच्या वापरामुळे उद्भवणाऱ्या कोणत्याही गैरसमज किंवा चुकीच्या अर्थलावणीसाठी आम्ही जबाबदार नाही. \ No newline at end of file diff --git a/translations/mr/03-rag/README.md b/translations/mr/03-rag/README.md index a4f245f26..534d594ff 100644 --- a/translations/mr/03-rag/README.md +++ b/translations/mr/03-rag/README.md @@ -1,144 +1,143 @@ -# मॉड्यूल 03: RAG (रिट्रीव्हल-ऑगमेंटेड जनरेशन) - -## मजकूर सामग्री - -- [व्हिडिओ वॉकथ्रू](../../../03-rag) -- [तुम्ही काय शिकाल](../../../03-rag) -- [पूर्वअटी](../../../03-rag) -- [RAG समजून घेणे](../../../03-rag) - - [हा ट्युटोरियल कोणता RAG दृष्टिकोन वापरतो?](../../../03-rag) -- [हे कसे कार्य करते](../../../03-rag) - - [डॉक्युमेंट प्रक्रिया](../../../03-rag) - - [एम्बेडिंग तयार करणे](../../../03-rag) - - [सेंमॅंटिक शोध](../../../03-rag) - - [उत्तर निर्मिती](../../../03-rag) -- [अ‍ॅप्लिकेशन चालवा](../../../03-rag) -- [अ‍ॅप्लिकेशन वापरणे](../../../03-rag) - - [डॉक्युमेंट अपलोड करा](../../../03-rag) - - [प्रश्न विचारा](../../../03-rag) - - [स्रोत संदर्भ तपासा](../../../03-rag) - - [प्रश्नांसह प्रयोग करा](../../../03-rag) -- [महेतवाचे संकल्पना](../../../03-rag) - - [चंकिंग धोरण](../../../03-rag) - - [समानता गुण](../../../03-rag) - - [इन-मेमरी स्टोरेज](../../../03-rag) - - [संदर्भ विंडो व्यवस्थापन](../../../03-rag) -- [जेव्हा RAG महत्वाचे असते](../../../03-rag) -- [पुढील पावले](../../../03-rag) +# Module 03: RAG (रिट्रीवल-अगमेंटेड जनरेशन) + +## Table of Contents + +- [व्हिडिओ वॉकथ्रू](#व्हिडिओ-वॉकथ्रू) +- [तुम्ही काय शिकाल](#तुम्ही-काय-शिकाल) +- [पूर्वअट](#पूर्वअट) +- [RAG समजून घेणे](#rag-समजून-घेणे) + - [या ट्युटोरियलमध्ये कोणता RAG दृष्टिकोन वापरला जातो?](#या-ट्युटोरियलमध्ये-कोणता-rag-दृष्टिकोन-वापरला-जातो) +- [हे कसे कार्य करते](#हे-कसे-कार्य-करते) + - [डॉक्युमेंट प्रक्रिया](#डॉक्युमेंट-प्रक्रिया) + - [एंबेडिंग्ज तयार करणे](#एंबेडिंग्ज-तयार-करणे) + - [सामांाजीक शोध](#सामांजिक-शोध) + - [उत्तर निर्मिती](#उत्तर-निर्मिती) +- [अॅप्लिकेशन चालवा](#अनुप्रयोग-चालवा) +- [अॅप्लिकेशन वापरणे](#अनुप्रयोग-वापरणे) + - [डॉक्युमेंट अपलोड करा](#दस्तऐवज-अपलोड-करा) + - [प्रश्न विचारा](#प्रश्न-विचारा) + - [स्त्रोत संदर्भ तपासा](#स्रोत-संदर्भ-तपासा) + - [प्रश्नांसह प्रयोग करा](#प्रश्नांबरोबर-प्रयोग-करा) +- [मुख्य संकल्पना](#मुख्य-संकल्पना) + - [चंकिंग धोरण](#तुकड्यांसाठी-धोरण) + - [सादृश्य गुणांकन](#सादृश्यता-स्कोअर्स) + - [मेमरीत संग्रहण](#इन-मेमरी-स्टोरेज) + - [संदर्भ विंडो व्यवस्थापन](#संदर्भ-विंडो-व्यवस्थापन) +- [RAG कुठे महत्वाचा असतो](#rag-कधी-महत्त्वाचा-आहे) +- [पुढील टप्पे](#पुढील-टप्पे) ## व्हिडिओ वॉकथ्रू -हा लाईव्ह सत्र पाहा जे या मॉड्यूलसह सुरू कसे करायचे हे स्पष्ट करते: +हा थेट सत्र पहा ज्यात या मॉड्यूलसह सुरुवात कशी करावी हे स्पष्ट केले आहे: RAG with LangChain4j - Live Session ## तुम्ही काय शिकाल -मागील मॉड्यूलमध्ये, तुम्ही AI सह संवाद साधणे आणि प्रभावीपणे प्रॉम्प्ट कसे रचायचे हे शिकलात. पण एक मूलभूत मर्यादा आहे: भाषा मॉडेल्सना फक्त त्यांच्या प्रशिक्षणादरम्यान काय शिकवले गेले आहे तेच माहिती असते. ते तुमच्या कंपनीच्या धोरणांबद्दल, प्रोजेक्ट दस्तऐवजांबद्दल किंवा त्यांना प्रशिक्षण दिलेल्या माहितीबाहेर असलेल्या कोणत्याही माहितीबद्दल प्रश्नांची उत्तरे देऊ शकत नाहीत. +मागील मॉड्यूलमध्ये, तुम्ही AI सोबत संवाद कसा साधायचा आणि तुम्ही तुमचे प्रॉम्प्ट कसे प्रभावीपणे रचाल हे शिकले आहे. पण एक मूलभूत मर्यादा आहे: भाषा मॉडेल्सना केवळ प्रशिक्षणादरम्यान जे शिकवले गेले तेच माहीत असते. ते तुमच्या कंपनीच्या धोरणांबद्दल, प्रकल्प दस्तऐवजाबद्दल किंवा जे माहिती त्यांनी शिकले नाही त्याबद्दल प्रश्नांची उत्तरे देऊ शकत नाहीत. -RAG (रिट्रीव्हल-ऑगमेंटेड जनरेशन) हा प्रश्न सोडवतो. मॉडेलला तुमची माहिती शिकवण्याचा प्रयत्न करण्याऐवजी (जो खर्चिक आणि अव्यवहार्य आहे), तुम्ही त्याला तुमचे दस्तऐवज शोधण्याची क्षमता देता. जेव्हा कोणी प्रश्न विचारतो, तेव्हा प्रणाली संबंधित माहिती मिळवते आणि ती प्रॉम्प्टमध्ये समाविष्ट करते. मॉडेल मग त्या प्राप्त संदर्भावर आधारित उत्तर देते. +RAG (रिट्रीवल-अगमेंटेड जनरेशन) हा समस्या सोडवतो. मॉडेलला तुमची माहिती शिकवण्याऐवजी (जो महागडा आणि प्रत्यक्षात तोडगा नाही), तुम्ही त्याला तुमच्या दस्तऐवजांमधून शोधण्याची क्षमता देता. जेव्हा कोणी प्रश्न विचारतो, तेव्हा प्रणाली संबंधित माहिती शोधते आणि त्या संदर्भासह प्रॉम्प्टमध्ये समाविष्ट करते. त्यानंतर मॉडेल प्राप्त केलेल्या संदर्भावर आधारित उत्तरे देते. -RAG ला मॉडेलसाठी संदर्भ ग्रंथालय देणे म्हणून विचार करा. जेव्हा तुम्ही प्रश्न विचारता, तेव्हा प्रणाली: +RAG म्हणजे मॉडेलला संदर्भ ग्रंथालय देणे मानू शकता. जेव्हा तुम्ही प्रश्न विचारता, प्रणाली: -1. **वापरकर्ता क्वेरी** - तुम्ही प्रश्न विचारता -2. **एम्बेडिंग** - तुमच्या प्रश्नाला एक व्हेक्टरमध्ये रूपांतरित करते -3. **व्हेक्टर शोध** - समान दस्तऐवज चंक शोधते -4. **संदर्भ संकलन** - संबंधित चंक प्रॉम्प्टमध्ये जोडते -5. **प्रतिसाद** - LLM त्या संदर्भावर आधारित उत्तर तयार करते +1. **वापरकर्ता प्रश्न** - तुम्ही प्रश्न विचारता +2. **एंबेडिंग** - तुमचा प्रश्न व्हेक्टरमध्ये रूपांतरित करतो +3. **व्हेक्टर शोध** - समान दस्तऐवज चंक शोधतो +4. **संदर्भ संकलन** - संबंधित चंक प्रॉम्प्टमध्ये जोडतो +5. **प्रतिसाद** - सर्व संदर्भावर आधारित LLM उत्तर तयार करतो -हे मॉडेलच्या प्रतिसादांना त्याच्या प्रशिक्षण ज्ञानावर अवलंबून राहण्याऐवजी तुमच्या खऱ्या डेटावर आधारित करते. +हे मॉडेलची उत्तरे तुमच्या वास्तविक डेटावर आधारित बनवते, त्याच्या प्रशिक्षण ज्ञानावर अवलंबून न राहता किंवा उत्तरे बनवून देण्याऐवजी. -## पूर्वअटी +## पूर्वअट -- पूर्ण केलेले [मॉड्यूल 00 - क्विक स्टार्ट](../00-quick-start/README.md) (सोप्या RAG उदाहरणासाठी जे या मॉड्यूलमध्ये नंतर संदर्भित केले आहे) -- पूर्ण केलेले [मॉड्यूल 01 - परिचय](../01-introduction/README.md) (Azure OpenAI संसाधने तैनात, ज्यात `text-embedding-3-small` एम्बेडिंग मॉडेलसह) -- मूळ फोल्डरमध्ये `.env` फाइल जिथे Azure प्रमाणपत्रे आहेत (मॉड्यूल 01 मध्ये `azd up` द्वारा तयार केलेली) +- पूर्ण केलेले [Module 01 - परिचय](../01-introduction/README.md) (Azure OpenAI स्रोतांसह, ज्यात `text-embedding-3-small` एंबेडिंग मॉडेल समाविष्ट आहे) +- रूट डायरेक्टरीमध्ये `.env` फाईल Azure क्रेडेन्शियल्ससह (Module 01 मध्ये `azd up` ने तयार केलेली) -> **टीप:** जर तुम्ही मॉड्यूल 01 पूर्ण केले नसेल, तर प्रथम तेथील डिप्लॉयमेंट सूचना पाळा. `azd up` आदेश GPT चॅट मॉडेल आणि या मॉड्यूलमध्ये वापरल्या जाणार्‍या एम्बेडिंग मॉडेल दोन्ही तैनात करतो. +> **टीप:** जर तुम्ही Module 01 पूर्ण केले नसेल, तर प्रथम तिथल्या तैनाती सूचना अनुसरा. `azd up` कमांड या मॉड्यूलमध्ये वापरल्या जाणार्‍या GPT चॅट मॉडेल आणि एंबेडिंग मॉडेल दोन्ही तैनात करतो. ## RAG समजून घेणे -खालील आकृती मुख्य संकल्पना दाखवते: फक्त मॉडेलच्या प्रशिक्षण डेटावर अवलंबून राहण्याऐवजी, RAG प्रत्येक उत्तर तयार करण्यापूर्वी तुमच्या दस्तऐवजांच्या संदर्भ ग्रंथालयाचा सल्ला देतो. +खालील आकृती मुख्य संकल्पना दर्शवते: मॉडेलच्या प्रशिक्षण डेटावर अवलंबून राहण्याऐवजी, RAG त्याला प्रत्येक उत्तर तयार करण्यापूर्वी तुमच्या दस्तऐवजांचा संदर्भ ग्रंथालय देते. What is RAG -*ही आकृती एक सामान्य LLM (जे प्रशिक्षण डेटावरून अंदाज लावते) आणि RAG-संवर्धित LLM (जे प्रथम तुमचे दस्तऐवज सल्ला करतो) यातील फरक दाखवते.* +*ही आकृती दर्शवते सामान्य LLM (जो प्रशिक्षण डेटावरून अंदाज घेतो) आणि RAG-युक्त LLM (जो प्रथम तुमच्या दस्तऐवजांचा संदर्भ घेतो) यातील फरक.* -येथे भाग कसे जोडलेले आहेत, पूर्ण प्रवाह. वापरकर्त्याचा प्रश्न चार टप्प्यांतून जातो — एम्बेडिंग, व्हेक्टर शोध, संदर्भ संकलन, आणि उत्तर निर्मिती — प्रत्येक टप्पा मागील टप्प्यावर आधारित आहे: +हे कसे जोडले आहे ते खालीलप्रमाणे. वापरकर्त्याचा प्रश्न चार टप्प्यांमधून जातो — एंबेडिंग, व्हेक्टर शोध, संदर्भ संकलन, आणि उत्तर निर्मिती — प्रत्येक मागील टप्प्यावर आधारित: RAG Architecture -*ही आकृती RAG संपूर्ण पाइपलाइन दाखवते — वापरकर्ता क्वेरी एम्बेडिंग, व्हेक्टर शोध, संदर्भ संकलन, आणि उत्तर निर्मितीतून जातो.* +*ही आकृती पूर्ण RAG पाइपलाइन दाखवते — वापरकर्ता प्रश्न एंबेडिंग, व्हेक्टर शोध, संदर्भ संकलन, आणि उत्तर निर्मिती यामधून जातो.* -या मॉड्यूलचे उर्वरित भाग प्रत्येक टप्प्यात तपशीलवार देखावा देतात, ज्यात तुम्ही चालवू आणि सुधारू शकणारा कोड आहे. +या मॉड्यूलमध्ये प्रत्येक टप्प्यातील तपशीलवार मार्गदर्शन आणि कोड उपलब्ध आहे ज्याचा तुम्ही वापर करू शकता आणि सुधारू शकता. -### हा ट्युटोरियल कोणता RAG दृष्टिकोन वापरतो? +### या ट्युटोरियलमध्ये कोणता RAG दृष्टिकोन वापरला जातो? -LangChain4j RAG अमलासाठी तीन मार्ग प्रदान करतो, प्रत्येक वेगवेगळ्या स्तरावरील अमूर्तता सह. खालील आकृती त्यांची बाजूने तुलना करते: +LangChain4j RAG अमलात आणण्यासाठी तीन मार्गांची ऑफर देते, प्रत्येक वेगवेगळ्या पातळीची सोपा करतो. खालील आकृती त्यांची बाजूने तुलना करते: Three RAG Approaches in LangChain4j -*ही आकृती तीन LangChain4j RAG दृष्टिकोनांची तुलना करते — सोपी, नैसर्गिक, आणि प्रगत — त्यांचे मुख्य घटक आणि वापरावे कधी ते दाखवते.* +*ही आकृती तीन LangChain4j RAG दृष्टिकोनांची तुलना करते — Easy, Native, आणि Advanced — त्यांचे मुख्य घटक आणि वापर कधी करायचा ते दाखवते.* -| दृष्टिकोन | काय करतो | उलाढाल | +| दृष्टिकोन | काय करतो | तोटा | |---|---|---| -| **सोप्या RAG** | `AiServices` आणि `ContentRetriever` द्वारे सर्व काही आपोआप वायर करते. तुम्ही इंटरफेसवर भाष्य करता, एक रिट्रीव्हर जोडता, आणि LangChain4j एम्बेडिंग, शोध आणि प्रॉम्प्ट संकलन पार्श्वभूमीत हाताळते. | कोड कमी, पण प्रत्येक टप्प्यावर काय होते ते दिसत नाही. | -| **नैसर्गिक RAG** | तुम्ही एम्बेडिंग मॉडेल कॉल करता, स्टोअर शोधता, प्रॉम्प्ट तयार करता, आणि उत्तर स्वतः तयार करता — एक स्पष्ट टप्पा एकावेळी. | अधिक कोड, पण प्रत्येक टप्पा दिसतो आणि सुधारता येतो. | -| **प्रगत RAG** | `RetrievalAugmentor` फ्रेमवर्क वापरते ज्यात प्लगबल क्वेरी ट्रान्सफॉर्मर, राऊटर, री-रँकर, आणि कंटेंट इंजेक्टर आहेत उत्पादन दर्जा पाइपलाइनसाठी. | जास्त लवचिकता, पण खूप जास्त गुंतागुंत. | +| **Easy RAG** | `AiServices` आणि `ContentRetriever` द्वारे सर्व काही आपोआप जोडतो. तुम्ही इंटरफेसला अ‍ॅनोटेट करता, रिट्रीव्हर जोडता, आणि LangChain4j एंबेडिंग, शोध आणि प्रॉम्प्ट संकलन पार्श्वभूमीवर हाताळतो. | किमान कोड पण प्रत्येक टप्प्यावर काय होत आहे ते दिसत नाही. | +| **Native RAG** | तुम्ही स्वतः एंबेडिंग मॉडेल कॉल करता, स्टोअर शोधता, प्रॉम्प्ट तयार करता, आणि उत्तर तयार करता — प्रत्येक टप्पा स्पष्टपणे. | अधिक कोड पण प्रत्येक टप्पा दिसतो आणि मोडिफाय करता येतो. | +| **Advanced RAG** | `RetrievalAugmentor` फ्रेमवर्क वापरतो ज्यात क्वेरी ट्रान्सफॉर्मर्स, राउटर्स, री-रँकर्स, आणि कंटेंट इंजेक्टर असतात, प्रॉडक्शन-ग्रेड पाइपलाइनसाठी. | जास्तीत जास्त लवचिकता पण फार अधिक गुंतागुंत. | -**हा ट्युटोरियल नैसर्गिक दृष्टिकोन वापरतो.** RAG पाइपलाइनचा प्रत्येक टप्पा — क्वेरीचे एम्बेडिंग, व्हेक्टर स्टोअर शोध, संदर्भ संकलन, आणि उत्तर निर्मिती — हे [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) मध्ये स्पष्टपणे लिहिलेले आहे. हे जाणून घेण्यासाठी केलेले आहे: शिकत असताना प्रत्येक टप्पा तुम्हाला दिसायलाच हवा, कोड कमी करण्यापेक्षा समजून घेणे जास्त महत्वाचे आहे. एकदा तुम्हाला संपूर्ण प्रक्रिया कळली की, तुम्ही पटकन प्रोटोटाइपसाठी सोप्या RAG कडे किंवा उत्पादनासाठी प्रगत RAG कडे जाऊ शकता. +**हा ट्युटोरियल Native दृष्टिकोन वापरतो.** RAG पाइपलाइनच्या प्रत्येक टप्प्याचे — क्वेरी एंबेड करणे, व्हेक्टर स्टोअर शोधणे, संदर्भ संकलन करणे, आणि उत्तर तयार करणे — स्पष्टपणे [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) मध्ये लिहिलेले आहे. हे उद्देशपूर्ण आहे: शिकण्याच्या स्रोत म्हणून, प्रत्येक टप्पा तुम्हाला दिसणे आणि समजणे महत्त्वाचे आहे, कोड कमी करण्यापेक्षा. एकदा तुम्हाला ते कसे काम करतात हे समजले की, तुम्ही त्वरित प्रोटोटाइपसाठी Easy RAG किंवा उत्पादन प्रणाल्यांसाठी Advanced RAG कडे जाऊ शकता. -> **💡 आधीच सोपा RAG पाहिला आहे का?** [क्विक स्टार्ट मॉड्यूल](../00-quick-start/README.md) मध्ये Document Q&A उदाहरण ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) सोपा RAG दृष्टिकोन वापरते — LangChain4j एम्बेडिंग, शोध आणि प्रॉम्प्ट संकलन आपोआप हाताळतो. हा मॉड्यूल पुढील पावलाने ते पाइपलाइन उघडतो जेणेकरून तुम्ही प्रत्येक टप्पा पाहू आणि नियंत्रित करू शकाल. +> **💡 Easy RAG बद्दल उत्सुक आहात का?** LangChain4j मध्ये *Easy RAG* असा दृष्टिकोन देखील आहे जिथे `AiServices` आणि `ContentRetriever` एंबेडिंग, शोध, आणि प्रॉम्प्ट संकलन आपोआप हाताळतात. हे मॉड्यूल अधिक स्पष्ट मार्ग घेतो — त्या पाइपलाइनचे उघडपणे विश्लेषण करून तुम्हाला प्रत्येक टप्पा पाहता आणि नियंत्रित करता येतो. -खालील आकृती क्विक स्टार्टमधील सोप्या RAG पाइपलाइन दाखवते. लक्षात घ्या कसे `AiServices` आणि `EmbeddingStoreContentRetriever` सर्व गुंतागुंती लपवतात — तुम्ही दस्तऐवज लोड करता, रिट्रीव्हर जोडता, आणि उत्तरे मिळवता. या मॉड्यूलमधील नैसर्गिक दृष्टिकोन त्या सर्व गुपित टप्पे उघडतो: +खालील आकृती Easy RAG पाइपलाइन दाखवते. येथे दिसते की `AiServices` आणि `EmbeddingStoreContentRetriever` सर्व गुंतागुंत लपवतात — तुम्ही दस्तऐवज लोड करता, रिट्रीव्हर जोडता, आणि उत्तरे मिळवता. या मॉड्यूलमधील Native दृष्टिकोन त्या लपलेल्या टप्प्यांनाही उघड करतो: Easy RAG Pipeline - LangChain4j -*ही आकृती `SimpleReaderDemo.java` मधील सोप्या RAG पाइपलाइन दाखवते. या मॉड्यूलमधील नैसर्गिक दृष्टिकोनशी तुलना करा: सोपा RAG एम्बेडिंग, रिट्रीव्हल, आणि प्रॉम्प्ट संकलन `AiServices` आणि `ContentRetriever` मागे लपवतो — तुम्ही दस्तऐवज लोड करता, रिट्रीव्हर जोडता, आणि उत्तरे मिळवता. नैसर्गिक दृष्टिकोन मध्ये तुम्ही प्रत्येक टप्पा थेट कॉल करता (एम्बेड, शोध, संदर्भ संकलन, उत्तर तयार) जे पूर्ण नियंत्रण आणि दृश्यता देते.* +*ही आकृती Easy RAG पाइपलाइन दाखवते. याची तुलना Native दृष्टिकोनाशी करा: Easy RAG मध्ये एंबेडिंग, रिट्रीवल, आणि प्रॉम्प्ट संकलन `AiServices` आणि `ContentRetriever` मागे लपलेले असते — तुम्ही दस्तऐवज लोड करता, रिट्रीव्हर जोडता, आणि उत्तरे मिळवता. Native दृष्टिकोन त्या पाइपलाइनचे उघड करून प्रत्येक टप्पा (एंबेड, शोध, संदर्भ संकलन, तयार करणे) स्वतः कॉल करण्याची पूर्ण पारदर्शकता आणि नियंत्रण देतो.* ## हे कसे कार्य करते -या मॉड्यूलमधील RAG पाइपलाइन चार टप्पे मोडते जे प्रत्येकी वापरकर्त्याचा प्रश्न विचारल्यावर अनुक्रमे चालतात. प्रथम, एक अपलोड केलेला दस्तऐवज **पार्स आणि चंक केली जाते** ज्याने हाताळण्यासाठी सोप्या तुकड्यांत विभागले जाते. त्या चंकना नंतर **व्हेक्टर एम्बेडिंग्स** मध्ये रूपांतरित केले जाते आणि साठवले जाते ज्याने गणितीय तुलना शक्य होते. जेव्हा क्वेरी येते, प्रणाली **सेंमॅंटिक शोध** करते सर्वात संबंधित चंक शोधण्यासाठी, आणि शेवटी LLM ला **उत्तर निर्मितीसाठी** संदर्भ म्हणून पुरवते. खालील विभाग प्रत्येक टप्पा कोड आणि आकृतींसह दाखवतात. पहिला टप्पा पाहूया. +या मॉड्यूलमधील RAG पाइपलाइन चार टप्प्यांमध्ये विभागलेली आहे जी वापरकर्ता प्रश्न विचारल्यावर क्रमाने चालतात. प्रथम, अपलोड केलेला दस्तऐवज **पार्स आणि चंक केला जातो**, म्हणजे छोटे व्यवस्थापनीय तुकडे केले जातात. नंतर त्या चंकना **व्हेक्टर एंबेडिंग्जमध्ये** रूपांतरित करून संग्रहित केले जाते, जेणेकरून त्यांची गणिती तुलना करता येईल. जेव्हा क्वेरी येते, तेव्हा प्रणाली **सामांजिक शोध** करते ज्यामुळे संबंधित चंक सापडतात, आणि शेवटी त्यांना संदर्भ म्हणून LLM कडे **उत्तर निर्मितीसाठी** देण्यात येते. खालील विभाग प्रत्येक टप्पा कोड व आकृतीसह समजावतात. पहिल्या टप्प्याकडे पाहूया. ### डॉक्युमेंट प्रक्रिया [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -जेव्हा तुम्ही दस्तऐवज अपलोड करता, तेव्हा प्रणाली तो पार्स करते (PDF किंवा साधा मजकूर), फाईलनेम सारखी मेटाडेटा जोडते, आणि नंतर तो चंकमध्ये विभागते — छोटे तुकडे जे मॉडेलच्या संदर्भ विंडोत सहज येतात. हे चंक थोडे ओव्हरलॅप होतात जेणेकरून सीमारेषेवरील संदर्भ हरवू नये. +जेव्हा तुम्ही दस्तऐवज अपलोड करता, तेव्हा प्रणाली तो पार्स करते (PDF किंवा साधा मजकूर), फाईल नावासारखी मेटाडेटा जोडते, आणि नंतर तो दस्तऐवज लहान चंकमध्ये विभागतो — जे मॉडेलच्या संदर्भ विंडोमध्ये सहज बसतात. हे चंक थोडेसे ओव्हरलॅप करतात ज्यामुळे सीमा भागातील संदर्भ गमावला जात नाही. ```java -// अपलोड केलेली फाईल पार्स करा आणि त्याला LangChain4j दस्तऐवजात गुंडाळा +// अपलोड केलेल्या फाइलचे पार्सिंग करा आणि ती LangChain4j दस्तऐवजामध्ये वेढा Document document = Document.from(content, metadata); -// 300-टोकनच्या तुकड्यांमध्ये विभाजित करा ज्यात 30-टोकनचे ओव्हरलॅप आहे +// 300-टोकनच्या तुकड्यांमध्ये विभाजित करा ज्यात 30-टोकनचे ओव्हरलॅप असेल DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -खालील आकृती हे कसे दृश्यात्मकपणे कार्य करते ते दाखवते. प्रत्येक चंक जवळच्या शेजाऱ्यांबरोबर काही टोकन्स शेअर करतो — ३० टोकन ओव्हरलॅपमुळे महत्त्वाचा संदर्भ दरम्यान गहाळ न राहतो: +खालील आकृती याचे दृश्यमान स्पष्टीकरण देते. प्रत्येक चंक शेजारील टोकन्ससह काही भाग सामायिक करतो — 30-टोकन ओव्हरलॅपमुळे महत्त्वाचा संदर्भ कधीही गमावला जात नाही: Document Chunking -*ही आकृती दाखवते की दस्तऐवज ३० टोकन ओव्हरलॅप सह ३००-टोकन चंकमध्ये कसे विभागला जातो, सीमारेषेवरील संदर्भ जपताना.* +*ही आकृती दर्शवते की डॉक्युमेंट 300-टोकन चंकमध्ये विभाजित केले जाते, ज्यात 30-टोकन ओव्हरलॅप आहे, तसेच चंक सीमांवरील संदर्भ राखला जातो.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) चॅटसह प्रयत्न करा:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) उघडा आणि विचारा: -> - "LangChain4j दस्तऐवज चंकमध्ये कसे विभागतो आणि ओव्हरलॅप का महत्त्वाचा आहे?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) चॅटसह प्रयत्न करा:** उघडा [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) आणि विचारा: +> - "LangChain4j कसे दस्तऐवज चंकमध्ये विभागतो आणि ओव्हरलॅप का महत्त्वाचा आहे?" > - "वेगवेगळ्या दस्तऐवज प्रकारांसाठी आदर्श चंक आकार काय आहे आणि का?" -> - "कृपया मल्टीलिंग्वल किंवा विशेष फॉरमॅटिंग असलेले दस्तऐवज कसे हाताळायचे?" +> - "मी कसे मल्टीलँग्वेज किंवा विशेष स्वरूप असलेले दस्तऐवज हाताळू शकतो?" -### एम्बेडिंग तयार करणे +### एंबेडिंग्ज तयार करणे [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -प्रत्येक चंक एक संख्यात्मक प्रतिनिधित्वात रूपांतरित केला जातो ज्याला एम्बेडिंग म्हणतात — मूलत: अर्थ ते संख्यांचा कन्व्हर्टर. एम्बेडिंग मॉडेल चॅट मॉडेलसारखे "बुद्धिमान" नसते; ते सूचनांचे पालन करू शकत नाही, तार्किक विचार करू शकत नाही किंवा प्रश्नांना उत्तरे देऊ शकत नाही. ते काय करू शकते ते म्हणजे मजकूराला अशा गणितीय अवकाशात नकाशा करणे जिथे समान अर्थ जवळजवळ येतात — "कार" जवळ "ऑटोमोबाईल," "रिफंड धोरण" जवळ "माझे पैसे परत करा." चॅट मॉडेलला तुम्ही ज्याच्याशी बोलू शकता असा एखादा व्यक्ती समजा; एम्बेडिंग मॉडेल ही अल्ट्रा-चांगली फाइलिंग प्रणाली आहे. +प्रत्येक चंक संख्यात्मक रूपांतरणात बदलला जातो ज्याला एंबेडिंग म्हणतात — प्रत्यक्षात अर्थ-ते-संख्यांमध्ये रूपांतर करणारा कन्व्हर्टर. एंबेडिंग मॉडेल चॅट मॉडेलप्रमाणे बुद्धिमान नाही; ते सूचना पाळू शकत नाही, तर्क करू शकत नाही, किंवा प्रश्नांना उत्तर देऊ शकत नाही. मुलत: हे मजकूराला गणिती जागेत नकाशित करते जिथे समान अर्थ जवळचे स्थाने घेतात — "कार" जवळ "ऑटोमोबाईल," "परतावा धोरण" जवळ "माझी पैसे परत करा." चॅट मॉडेल म्हणजे व्यक्तीशी संवाद करणारा, तर एंबेडिंग मॉडेल एक अत्यंत चांगली वर्गीकरण यंत्रणा आहे. -खालील आकृती हा संकल्पना दर्शवते — मजकूर आत जातो, संख्यात्मक व्हेक्टर बाहेर येतात, आणि समान अर्थ जवळचे व्हेक्टर तयार करतात: +खालील आकृती ही संकल्पना दृश्यमान करते — मजकूर इनपुट म्हणून जातो, संख्यात्मक व्हेक्टर बाहेर येतात, आणि समान अर्थ जवळच्या व्हेक्टर रूपात उत्पन्न होतो: Embedding Model Concept -*ही आकृती दाखवते की एम्बेडिंग मॉडेल मजकूर कसा संख्यात्मक व्हेक्टरमध्ये रूपांतरित करतो, ज्यात समान अर्थ — जसे "कार" आणि "ऑटोमोबाईल" — व्हेक्टर स्पेसमध्ये एकमेकांच्या जवळ येतात.* +*ही आकृती दर्शवते की एंबेडिंग मॉडेल कसे मजकूराला संख्यात्मक व्हेक्टरमध्ये रूपांतरित करतं, जिथे "कार" आणि "ऑटोमोबाईल" सारखे समान अर्थ जवळपास व्हेक्टर स्पेसमध्ये राहतात.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -खालील वर्ग आकृती एक RAG पाइपलाइनमधील दोन वेगळ्या प्रवाह आणि LangChain4j वर्ग दर्शवते. **इंजेस्टिंग प्रवाह** (एकदा अपलोडवेळी चालणारा) दस्तऐवज विभागतो, चंक एम्बेड करतो, आणि `.addAll()` द्वारे साठवतो. **क्वेरी प्रवाह** (प्रत्येक वेळी वापरकर्ता प्रश्न विचारतो तेव्हा चालणारा) प्रश्न एम्बेड करतो, `.search()` द्वारे स्टोअर शोधतो, आणि जुळलेला संदर्भ चॅट मॉडेलला पाठवतो. दोन्ही प्रवाह सामान्य `EmbeddingStore` इंटरफेसवर भेटतात: +खालील वर्ग आकृती RAG पाइपलाइनमधील दोन वेगळ्या प्रवाहांचे आणि LangChain4j वर्गांचे दर्शन करते जे त्यांना अंमलात आणतात. **इंगेस्टन प्रवाह** (प्रत्येक वेळा अपलोड केल्यावर चालतो) दस्तऐवज विभागतो, चंक एंबेड करतो, आणि `.addAll()` द्वारे संग्रहित करतो. **क्वेरी प्रवाह** (प्रत्येक वेळी वापरकर्ता प्रश्न विचारल्यावर चालतो) प्रश्न एंबेड करतो, `.search()` ने स्टोअर शोधतो, आणि मिळालेले संदर्भ चॅट मॉडेलला पास करतो. दोन्ही प्रवाह सामायिक `EmbeddingStore` इंटरफेसवर भेटतात: LangChain4j RAG Classes -*ही आकृती RAG पाइपलाइनमधील दोन प्रवाह दाखवते — इंजेस्टिंग आणि क्वेरी — आणि ते सामान्य EmbeddingStore द्वारे कसे जोडलेले आहेत.* +*ही आकृती RAG पाइपलाइनमधील दोन प्रवाह — इंगेस्टन आणि क्वेरी — आणि ते कसे सामायिक एंबेडिंग स्टोअरद्वारे जोडलेले आहेत ते दाखवते.* -एकदा एम्बेडिंग साठवले गेल्यावर, समान सामग्री नैसर्गिकरित्या व्हेक्टर स्पेसमध्ये एकत्र जमते. खालील दृष्टीकोन दाखवतो की संबंधित विषयांच्या दस्तऐवज कसे पुढच्या-अगोदरच्या बिंदू म्हणून येतात, जे सेंमॅंटिक शोध शक्य बनवते: +एकदा एंबेडिंग्ज संग्रहित केल्या की, समान सामग्री नैसर्गिकरित्या व्हेक्टर स्पेसमध्ये एकत्र गुच्छबद्ध होते. खाली दिलेली दृश्ये दर्शवतात की संबंधित विषयांचे दस्तऐवज जवळजवळ बिंदू म्हणून कसे दाखवले जातात, ज्यामुळे सामांजिक शोध शक्य होतो: Vector Embeddings Space -*ही दृष्टीकोन दर्शवते की संबंधित दस्तऐवज 3D व्हेक्टर स्पेसमध्ये एकत्र जमतात, ज्यात टेक्निकल डॉक्स, बिझनेस नियम, आणि FAQ सारखे वेगळे समूह तयार होतात.* +*ही दृश्ये दाखवतात की तांत्रिक दस्तऐवज, व्यवसाय नियम, आणि FAQ सारखे विषय 3D व्हेक्टर स्पेसमध्ये स्वतंत्र गटांमध्ये कसे समोडलेले आहेत.* -जेव्हा वापरकर्ता शोध करतो, प्रणाली चार टप्पे पार पाडते: एकदा दस्तऐवज एम्बेड करणे, प्रत्येक शोधावर क्वेरी एम्बेड करणे, क्वेरी व्हेक्टर आणि साठवलेल्या सर्व व्हेक्टरशी कोसाईन सादृश्यता वापरून तुलना करणे, आणि टॉप-K उच्चगुणांक मिळालेल्या चंक परत करणे. खालील आकृती प्रत्येक टप्पा आणि त्यात समाविष्ट LangChain4j वर्ग दाखवते: +जेव्हा वापरकर्ता शोधतो, तेव्हा प्रणाली चार पावले पार करते: दस्तऐवजांची एकदा एंबेडिंग करणे, प्रत्येक शोधामध्ये क्वेरीला एंबेडिंग करणे, क्वेरी व्हेक्टरची साठवलेल्या सर्व व्हेक्टरशी कोसाईन सादृश्यतेने तुलना करणे, आणि सर्वोच्च-गुणांकन करणाऱ्या टॉप-K चंक परत करणे. खालील आकृती प्रत्येक टप्पा आणि संबंधित LangChain4j वर्ग दाखवते: Embedding Search Steps -*ही आकृती चार टप्प्यांत एम्बेडिंग शोध प्रक्रिया दाखवते: दस्तऐवज एम्बेड करा, क्वेरी एम्बेड करा, व्हेक्टर कोसाईन सादृश्यतेने तुलना करा, आणि टॉप-K निकाल परत करा.* +*ही आकृती चार टप्प्यांचा एंबेडिंग शोध प्रक्रिया दाखवते: दस्तऐवज एंबेड करणे, क्वेरी एंबेड करणे, कोसाईन सादृश्यतेने व्हेक्टर तुलना करणे, आणि टॉप-K परिणाम परत करणे.* -### सेंमॅंटिक शोध +### सामांजिक शोध [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -जेव्हा तुम्ही प्रश्न विचारता, तुमचा प्रश्न देखील एम्बेडिंगमध्ये बदलतो. प्रणाली तुमच्या प्रश्नाच्या एम्बेडिंगची तुलना सर्व दस्तऐवज चंकच्या एम्बेडिंगशी करते. ती असे चंक शोधते ज्याचं अर्थ सर्वाधिक समान आहे - केवळ कीवर्ड जुळणारे नव्हे, तर खरी संमॅंटिक समानता असलेले. +जेव्हा तुम्ही प्रश्न विचारता, तुमचा प्रश्नही एंबेडिंगमध्ये रूपांतरित होतो. प्रणाली तुमच्या प्रश्नाच्या एंबेडिंगची तुलना सर्व दस्तऐवज चंकच्या एंबेडिंगशी करते. ती चंक शोधते ज्याचा अर्थ सर्वाधिक समान असतो - फक्त कीवर्ड नाही परंतु खरा सामांजिक सादृश्यता. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -खालील आकृती पारंपरिक कीवर्ड शोधाशी तुलना करते. "व्हेहिकल" साठी कीवर्ड शोध "कार आणि ट्रक्स" बद्दलचा चंक चुकतो, पण सेंमॅंटिक शोध त्यांचा समान अर्थ समजून तो उच्च गुण मिळवलेल्या जुळणारा म्हणून परत करतो: +खालील आकृती सामांजिक शोध आणि पारंपरिक कीवर्ड शोध यातील फरक दाखवते. "vehicle" या कीवर्डसाठी केलेल्या शोधात "cars and trucks" विषयी एक चंक चुकतो, पण सामांजिक शोध ते समजतो आणि ते उच्च गुणांकनाने परत करतो: Semantic Search -*ही आकृती कीवर्ड-आधारित शोध आणि सेंमॅंटिक शोध यांची तुलना करते, जे दाखवते की सेंमॅंटिक शोध कसे संकल्पनात्मकदृष्ट्या संबंधित सामग्री परत करतो जरी नेमके कीवर्ड वेगळे असतील.* -खालील तत्त्वाधारावर, सादृश्यता कॉसाईन सादृश्यता वापरून मोजली जाते — मूलत: "हे दोन बाण एकाच दिशेने दर्शवत आहेत का?" असं विचारत आहे. दोन भागांमध्ये पूर्णपणे वेगवेगळे शब्द असू शकतात, पण जर त्यांचा अर्थ सारखा असेल तर त्यांच्या व्हेक्टरची दिशा सारखी असते आणि त्यांची स्कोअर 1.0 च्या जवळ असते: +*ही आकृती कीवर्ड-आधारित शोध आणि सामांजिक शोधाची तुलना करते, पाहवयासाठी की सामांजिक शोध संकल्पनात्मक दृष्टिकोनातून संबंधित सामग्री देखील शोधून काढतो जरी तपशिलनुसार कीवर्ड निराळे असले तरी.* -कॉसाईन सादृश्यता +आतल्या प्रक्रियेत, सादृश्यता कोसाईन सादृश्यतेने मोजली जाते — म्हणजे "हे दोन बाण सारखेच दिशेकडे आहेत का?" विचारणे. दोन चंक पूर्णपणे वेगळ्या शब्दांचा वापर करू शकतात, पण जर त्यांचा अर्थ सारखाच असेल तर त्यांचे व्हेक्टर समान दिशेत असतील आणि 1.0 जवळ गुणांकन करतील: -*हे आकृती एम्बेडिंग व्हेक्टरमधील कोन म्हणून कॉसाईन सादृश्यता दर्शवते — जास्त संरेखित व्हेक्टरचे स्कोर 1.0 च्या जवळ असते, जे उच्चसंदर्भित सादृश्यता सूचित करते.* +Cosine Similarity +*हा आकृती एनबेडिंग व्हेक्टरमधील कोसाइन सादृश्यता म्हणून कोन दर्शवितो — अधिक संरेखित व्हेक्टर 1.0 च्या जवळील स्कोअर प्राप्त करतात, ज्याचा अर्थ जास्त सेमँटिक सादृश्यता.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat सह प्रयत्न करा:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) उघडा आणि विचारा: -> - "एम्बेडिंगसह सादृश्यता शोध कसा कार्य करतो आणि स्कोअर काय ठरवतो?" -> - "मला कोणता सादृश्यता थ्रेशोल्ड वापरायचा आणि तो निकालांवर कसा परिणाम करतो?" -> - "जर कोणतेही संबंधित दस्तऐवज सापडले नाहीत तर मी कसे हाताळू?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) चॅटसह प्रयत्न करा:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) उघडा आणि विचारा: +> - "एंबेडिंग्ससह सादृश्यता शोध कसा कार्य करतो आणि स्कोअर काय ठरवते?" +> - "मी कोणता सादृश्यता थ्रेशोल्ड वापरावा आणि त्याचा परिणाम कसा होतो?" +> - "जेव्हा संबंधित दस्तऐवज आढळत नाहीत तेव्हा मी कसे हाताळू?" ### उत्तर निर्मिती [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -सर्वाधिक संबंधित भाग सुसंगत सूचना, प्राप्त संदर्भ आणि वापरकर्त्याच्या प्रश्नासह एक संरचित प्रॉम्प्टमध्ये एकत्र केले जातात. मॉडेल त्या विशिष्ट भागांना वाचते आणि त्या माहितीवर आधारित उत्तर देते — ते फक्त समोर असलेल्या माहितीचा वापर करू शकते, ज्यामुळे भासवटा होत नाही. +सर्वात संबंधित तुकडे एक संरचित प्रॉम्प्टमध्ये एकत्र केले जातात ज्यात स्पष्ट निर्देश, प्राप्त संदर्भ, आणि वापरकर्त्याचा प्रश्न समाविष्ट आहे. मॉडेल त्या विशिष्ट तुकड्यांना वाचतो आणि त्या माहितीच्या आधारे उत्तर देते — ते समोर काय आहे तेच वापरू शकते, ज्यामुळे भ्रम निर्माण होण्यापासून टाळला जातो. ```java String context = matches.stream() @@ -237,55 +236,55 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -खालील आकृती या संकलनाची क्रिया दर्शवते — शोध टप्प्यातील सर्वोच्च स्कोअर असलेले भाग प्रॉम्प्ट टेम्पलेटमध्ये टाकले जातात, आणि `OpenAiOfficialChatModel` एक आधारभूत उत्तर तयार करते: +खालील आकृती या एकत्रिकरणाची क्रिया दर्शविते — शोध टप्प्यातून सर्वोच्च स्कोअर असलेले तुकडे प्रॉम्प्ट टेम्प्लेटमध्ये ऑटोपायलट केले जातात, आणि `OpenAiOfficialChatModel` एक आधारित उत्तर तयार करतो: -संदर्भ संकलन +Context Assembly -*ही आकृती दाखवते की कशी सर्वोच्च स्कोअर असलेले भाग संरचित प्रॉम्प्टमध्ये एकत्र केले जातात, ज्यामुळे मॉडेल आपल्या डेटावरून एक आधारभूत उत्तर देऊ शकते.* +*ही आकृती दर्शवते की सर्वोच्च स्कोअर असलेले तुकडे कसे संरचित प्रॉम्प्टमध्ये एकत्रित होतात, ज्यामुळे मॉडेल तुमच्या डेटावरून आधारित उत्तर तयार करू शकते.* ## अनुप्रयोग चालवा -**परिनियोजन तपासा:** +**डिप्लॉयमेंट तपासा:** -रूट डिरेक्टरीमध्ये `.env` फाइल असल्याची खात्री करा ज्यात Azure क्रेडेन्शियल्स आहेत (Module 01 मध्ये तयार केलेली). हे चालवा ते मॉड्यूल डिरेक्टरीतून (`03-rag/`): +मूल निर्देशिकेत `.env` फाइल अस्तित्वात आहे याची खात्री करा ज्यात Azure क्रेडेन्शियल्स असतील (Module 01 मध्ये तयार केलेले). हा कमांड मॉड्यूल निर्देशिकेतून (`03-rag/`) चालवा: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवायला हवे +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवावे ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवावे +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवले पाहिजे ``` **अनुप्रयोग सुरू करा:** -> **टीप:** जर तुम्ही आधीच सर्व अनुप्रयोग `./start-all.sh` वापरून रूट डिरेक्टरीतून सुरू केले असाल (Module 01 मध्ये वर्णन केलेले), तर हा मॉड्युल आधीच पोर्ट 8081 वर चालू आहे. तुम्ही खालील सुरुवात आदेश वगळून थेट http://localhost:8081 वर जाऊ शकता. +> **नोट:** जर तुम्ही आधीच रूट निर्देशिकेतून `./start-all.sh` वापरून सर्व अनुप्रयोग सुरू केले असल्यास (जसे Module 01 मध्ये सांगितले आहे), तर हा मॉड्यूल पोर्ट 8081 वर चालू आहे. तुम्ही खालील स्टार्ट कमांड टाळू शकता आणि थेट http://localhost:8081 वर जाऊ शकता. -**पर्याय 1: Spring Boot डॅशबोर्ड वापरून (VS Code वापरकर्त्यांसाठी शिफारसीय)** +**पर्याय 1: Spring Boot Dashboard वापरून (VS Code वापरकर्त्यांसाठी शिफारसीय)** -डेव्ह कंटेनरमध्ये Spring Boot डॅशबोर्ड विस्तार आहे, जो सर्व Spring Boot अनुप्रयोगांचे व्यवस्थापन करण्यासाठी दृश्यात्मक इंटरफेस प्रदान करतो. तुम्ही ते VS Code च्या Activity Bar मध्ये डाव्या बाजूला (Spring Boot आयकॉन शोधा) पाहू शकता. +डेव्ह कंटेनरमध्ये Spring Boot Dashboard विस्तार समाविष्ट आहे, जो सर्व Spring Boot अनुप्रयोगांचे व्हिज्युअल व्यवस्थापन सुविधा पुरवतो. तो VS Code च्या डाव्या बाजूच्या अ‍ॅक्टिव्हिटी बारमध्ये (Spring Boot आयकॉन पहा) मिळेल. -Spring Boot डॅशबोर्डमधून तुम्ही: -- कार्यक्षेत्रातील सर्व उपलब्ध Spring Boot अनुप्रयोग पाहू शकता -- एक क्लिकने अनुप्रयोग सुरू/थांबवू शकता -- अनुप्रयोग लॉग रिअल-टाइममध्ये पाहू शकता -- अनुप्रयोग स्थिती मॉनिटर करू शकता +Spring Boot Dashboard मधून तुम्ही: +- वर्कस्पेसमधील सर्व उपलब्ध Spring Boot अनुप्रयोग पाहू शकता +- एका क्लिकने अनुप्रयोग सुरू / थांबवू शकता +- रिअल-टाइम मध्ये अनुप्रयोगाचे लॉग पाहू शकता +- अनुप्रयोग स्थिती पाहू शकता -"rag" च्या बाजूला प्ले बटणावर क्लिक करून हा मॉड्युल सुरू करा, किंवा एकावेळी सर्व मॉड्यूल सुरू करा. +फक्त "rag" समोरील प्ले बटण क्लिक करा तो मॉड्यूल सुरू करण्यासाठी, किंवा सर्व मॉड्यूल एकदम सुरू करा. -Spring Boot डॅशबोर्ड +Spring Boot Dashboard -*ही स्क्रीनशॉट VS Code मधील Spring Boot डॅशबोर्ड दाखवते, जिथे तुम्ही अनुप्रयोग दृश्यात्मक रीतीने सुरू, थांबवू आणि मॉनिटर करू शकता.* +*ही स्क्रीनशॉट VS Code मधील Spring Boot Dashboard दाखवते, जिथे तुम्ही अनुप्रयोग व्हिज्युअली सुरू, थांबवू आणि मॉनिटर करू शकता.* **पर्याय 2: शेल स्क्रिप्ट वापरून** -सर्व वेब अनुप्रयोग सुरू करा (मॉड्यूल 01-04): +सर्व वेब अनुप्रयोग (मॉड्यूल 01-04) सुरू करा: **Bash:** ```bash -cd .. # मूळ निर्देशिकेतून +cd .. # रूट निर्देशिकेकडून ./start-all.sh ``` @@ -295,7 +294,7 @@ cd .. # रूट निर्देशिकेपासून .\start-all.ps1 ``` -किंवा केवळ हा मॉड्युल सुरू करा: +किंवा फक्त हा मॉड्यूल सुरू करा: **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -दोन्ही स्क्रिप्ट रूट `.env` फाइलमधून पर्यावरण चल आपोआप लोड करतात आणि जर JAR अस्तित्वात नसल्यास ती तयार करतील. +दोन्ही स्क्रिप्ट्स स्वयंचलितपणे मूळ `.env` फाइलमधून पर्यावरण चल लोड करतात आणि जर JAR अस्तित्वात नसतील तर तयार करतात. -> **टीप:** सर्व मॉड्यूल स्वतःहून तयार करून नंतर सुरू करायचे असल्यास: +> **नोट:** जर तुम्हाला सर्व मॉड्यूल्स मॅन्युअली बिल्ड करायचे असतील तर ते सुरू करण्यापूर्वी: > > **Bash:** > ```bash @@ -325,113 +324,113 @@ cd 03-rag > mvn clean package -DskipTests > ``` -तुमच्या ब्राउजरमध्ये http://localhost:8081 उघडा. +ब्राउझरमध्ये http://localhost:8081 उघडा. **थांबवण्यासाठी:** **Bash:** ```bash -./stop.sh # हा मॉड्यूल फक्त +./stop.sh # फक्त हा मॉड्यूल # किंवा -cd .. && ./stop-all.sh # सर्व मॉड्यूल्स +cd .. && ./stop-all.sh # सर्व मॉड्यूल ``` **PowerShell:** ```powershell -.\stop.ps1 # हा मॉड्यूल फक्त +.\stop.ps1 # हा फक्त मॉड्यूल # किंवा cd ..; .\stop-all.ps1 # सर्व मॉड्यूल्स ``` ## अनुप्रयोग वापरणे -हा अनुप्रयोग दस्तऐवज अपलोड करण्यासाठी आणि प्रश्न विचारण्यासाठी एक वेब इंटरफेस प्रदान करतो. +हा अनुप्रयोग दस्तऐवज अपलोड आणि प्रश्न विचारण्यासाठी वेब इंटरफेस प्रदान करतो. -RAG अनुप्रयोग इंटरफेस +RAG Application Interface -*ही स्क्रीनशॉट RAG अनुप्रयोग इंटरफेस दाखवते जिथे तुम्ही दस्तऐवज अपलोड करता आणि प्रश्न विचारता.* +*ही स्क्रीनशॉट RAG अनुप्रयोग इंटरफेस दाखवते जिथे तुम्ही दस्तऐवज अपलोड करू शकता आणि प्रश्न विचारू शकता.* ### दस्तऐवज अपलोड करा -दस्तऐवज अपलोड करून सुरुवात करा — TXT फाईल्स चाचणीसाठी उत्तम काम करतात. या डिरेक्टरीमध्ये `sample-document.txt` उपलब्ध आहे ज्यात LangChain4j वैशिष्ट्ये, RAG अंमलबजावणी आणि उत्तम पद्धतींबद्दल माहिती आहे — प्रणालीची चाचणीसाठी उत्तम. +दस्तऐवज अपलोड करून सुरू करा - TXT फाइल्स चाचणीसाठी सर्वोत्तम आहेत. या निर्देशिकेत `sample-document.txt` आहे ज्यात LangChain4j वैशिष्ट्ये, RAG अंमलबजावणी, आणि सर्वोत्तम सरावांची माहिती आहे - सिस्टम चाचणीसाठी परिपूर्ण. -प्रणाली तुमचा दस्तऐवज प्रक्रिया करते, त्याला भागांमध्ये विभागते, आणि प्रत्येक भागासाठी एम्बेडिंग तयार करते. हे तुम्ही अपलोड करताच स्वयंचलितपणे होते. +सिस्टम तुमचा दस्तऐवज प्रक्रिया करते, तुकड्यांमध्ये विभागते, आणि प्रत्येक तुकड्याचे एंबेडिंग तयार करते. हे आपोआपच तुम्ही अपलोड केल्यानंतर होते. ### प्रश्न विचारा -आता दस्तऐवजातील विशिष्ट प्रश्न विचारा. दस्तऐवजामध्ये स्पष्टपणे नमूद केलेलं काहीतरी तथ्याचा प्रश्न विचारा. प्रणाली संबंधित भाग शोधते, त्यांना प्रॉम्प्टमध्ये समाविष्ट करते आणि उत्तर निर्माण करते. +आता दस्तऐवजाच्या सामग्रीबाबत विशिष्ट प्रश्न विचारा. असे तथ्य विचारा जे ठळकपणे दस्तऐवजात दिलेले आहे. सिस्टम संबंधित तुकडे शोधते, त्यांना प्रॉम्प्टमध्ये समाविष्ट करते आणि उत्तर तयार करते. ### स्रोत संदर्भ तपासा -प्रत्येक उत्तरासह स्रोत संदर्भ आणि सादृश्यता स्कोअर दिले जातात. हे स्कोअर (0 ते 1) दाखवतात की प्रत्येक भाग तुमच्या प्रश्नाशी किती संबंधित होता. जास्त स्कोअर म्हणजे उत्तम जुळणी. या द्वारे तुम्ही उत्तर स्रोत सामग्रीशी तपासू शकता. +प्रत्येक उत्तरास सोबत स्रोत संदर्भ आणि सादृश्यता स्कोअर्स असतात. हे स्कोअर्स (0 ते 1) दर्शवतात की प्रत्येक तुकडा तुमच्या प्रश्नाशी कितपत संबंधित होता. जास्त स्कोअर्स म्हणजे चांगला जुळवापठव. यातून तुम्ही उत्तराची तुलना मूळ सामग्रीशी करू शकता. -RAG क्वेरी निकाल +RAG Query Results -*ही स्क्रीनशॉट क्वेरी निकाल दाखवते, ज्यामध्ये तयार केलेले उत्तर, स्रोत संदर्भ आणि प्रत्येक मिळवलेल्या भागासाठी सादृश्यता स्कोअर आहे.* +*ही स्क्रीनशॉट क्वेरी निकाल दाखवते ज्यात तयार केलेले उत्तर, स्रोत संदर्भ, आणि प्रत्येक प्राप्त तुकड्याचा सादृश्यता स्कोअर समाविष्ट आहे.* -### प्रश्नांसह प्रयोग करा +### प्रश्नांबरोबर प्रयोग करा -वेगवेगळ्या प्रकारचे प्रश्न विचारून पहा: -- विशिष्ट तथ्य: "मुख्य विषय काय आहे?" -- तुलना: "X आणि Y मधील फरक काय आहे?" -- सारांश: "Z बद्दल मुख्य मुद्दे सारांश करा" +वेगवेगळ्या प्रकारचे प्रश्न विचारा: +- विशिष्ट तथ्ये: "मुख्य विषय काय आहे?" +- तुलना: "X आणि Y यामध्ये काय फरक आहे?" +- सारांश: "Z विषयी महत्त्वाचे मुद्दे संक्षेप करा" -प्रश्नाच्या दस्तऐवजाशी जुळण्यानुसार सादृश्यता स्कोअर कसे बदलतात ते पाहा. +तुमच्या प्रश्नाशी दस्तऐवजाचा कितपत सुसंगतता आहे यावर सादृश्यता स्कोअर कसे बदलतात हे पहा. ## मुख्य संकल्पना -### भागांमध्ये विभागणी धोरण +### तुकड्यांसाठी धोरण -दस्तऐवज 300-टोकन च्या भागांमध्ये विभागले जातात ज्यात 30 टोकन ओव्हरलॅप असतो. हे संतुलन सुनिश्चित करते की प्रत्येक भागात पुरेसा संदर्भ आहे जेणेकरून तो अर्थपूर्ण राहतो आणि तो इतका लहान आहे की अनेक भाग प्रॉम्प्टमध्ये समाविष्ट करता येतात. +दस्तऐवज 300-टोकन तुकड्यांमध्ये विभागलेले आहेत ज्यात 30 टोकन ओव्हरलॅप आहे. या संतुलनामुळे प्रत्येक तुकड्याला अर्थपूर्ण संदर्भ मिळतो आणि प्रॉम्प्टमध्ये अनेक तुकडे समाविष्ट करता येतात. -### सादृश्यता स्कोअर +### सादृश्यता स्कोअर्स -प्रत्येक मिळालेला भाग 0 ते 1 दरम्यान सादृश्यता स्कोअर सह येतो जो वापरकर्त्याच्या प्रश्नाशी त्याची जुळणारी सादृश्यता दर्शवतो. खालील आकृती स्कोअर श्रेणी आणि त्यांचा उपयोग निकाल फिल्टर करण्यासाठी कसा होतो हे दर्शवते: +प्रत्येक प्राप्त तुकड्याला 0 ते 1 दरम्यान सादृश्यता स्कोअर असतो जो वापरकर्त्याच्या प्रश्नाशी कितपत जुळतो ते दर्शवतो. खाली आकृती स्कोअर श्रेणी दर्शवते आणि सिस्टम त्या वापरून निकाल कसे फिल्टर करते: -सादृश्यता स्कोअर +Similarity Scores -*ही आकृती 0 ते 1 पर्यंतची स्कोअर श्रेणी दाखवते, ज्यात किमान थ्रेशोल्ड 0.5 आहे जे अवांछित भाग फिल्टर करते.* +*ही आकृती 0 ते 1 पर्यंत स्कोअर श्रेणी दाखवते, ज्यात किमान थ्रेशोल्ड 0.5 आहे जो असंबंधित तुकडे काढून टाकतो.* -स्कोअर रेंज: -- 0.7-1.0: अत्यंत संबंधित, अचूक जुळणी +स्कोअर्स श्रेणीमध्ये: +- 0.7-1.0: अत्यंत संबंधित, अचूक जुळवापठव - 0.5-0.7: संबंधित, चांगला संदर्भ -- 0.5 खाली: फिल्टर केलेले, फारसी वेगळे +- 0.5 खाली: काढून टाकलेले, फारसे भिन्न -प्रणाली गुणवत्ता सुनिश्चित करण्यासाठी फक्त किमान थ्रेशोल्ड पेक्षा जास्त स्कोअर असलेले भाग परत करते. +सिस्टम केवळ किमान थ्रेशोल्डवरील तुकडे प्राप्त करते जेणेकरून गुणवत्ता सुनिश्चित होते. -एम्बेडिंग्स तेव्हा चांगले कार्य करतात जेव्हा अर्थाने क्लस्टर स्वच्छ असतात, पण त्यात अडचणी देखील असतात. खालील आकृती सामान्य त्रुटीचे प्रकार दाखवते — खूप मोठे भाग अस्पष्ट व्हेक्टर तयार करतात, खूप लहान भागांना संदर्भ नसतो, अस्पष्ट संज्ञा अनेक क्लस्टर्सकडे निर्देश करतात, आणि अचूक-जुळणी शोध (IDs, भाग क्रमांक) एमबेडिंग्जशी नसतात: +एंबेडिंग्स चांगले कार्य करतात जेव्हा अर्थ क्लस्टर्समध्ये स्वच्छपणे विभागला जातो, पण त्यातही त्रुटी असतात. खाली आकृती सामान्य दोष दाखवते — फार मोठे तुकडे असलेले अवघड व्हेक्टर तयार करतात, फार छोटे तुकडे संदर्भ कमी करतात, अस्पष्ट अटी अनेक क्लस्टर्सकडे निर्देश करतात, आणि अचूक जुळवापठव शोध (IDs, भाग क्रमांक) एंबेडिंग्ससाठी कार्य करत नाहीत: -एम्बेडिंग त्रुटी प्रकार +Embedding Failure Modes -*ही आकृती सामान्य एम्बेडिंग त्रुटी प्रकार दाखवते: खूप मोठे भाग, खूप लहान भाग, बहुउद्देशीय संज्ञा जी विविध क्लस्टर्स दाखवतात, आणि अचूक-जुळणी शोध (IDs) जे एम्बेडिंग्जशी जुळत नाहीत.* +*ही आकृती सामान्य embedding दोष दाखवते: फार मोठे तुकडे, फार छोटे तुकडे, अस्पष्ट अटी ज्यामुळे अनेक क्लस्टर्स दर्शवतात, आणि अचूक जुळवापठव शोध जसे IDs.* -### इन-मेमरी संचयन +### इन-मेमरी स्टोरेज -सोपेसाठी हा मॉड्युल इन-मेमरी संचयन वापरतो. अनुप्रयोग पुन्हा सुरू केल्यास अपलोड केलेली दस्तऐवज गहाळ होतात. व्यावसायिक प्रणाली Qdrant किंवा Azure AI Search सारख्या कायमस्वरूपी व्हेक्टर डेटाबेस वापरतात. +हा मॉड्यूल साधेपणासाठी इन-मेमरी स्टोरेज वापरतो. अनुप्रयोग पुन्हा सुरू केल्यावर अपलोड केलेले दस्तऐवज हरवतात. उत्पादन पद्धतीत Qdrant किंवा Azure AI Search सारखे सतत व्हेक्टर डेटाबेस वापरले जातात. ### संदर्भ विंडो व्यवस्थापन -प्रत्येक मॉडेलची कमाल संदर्भ विंडो असते. तुम्ही मोठ्या दस्तऐवजातील प्रत्येक भाग समाविष्ट करू शकत नाही. प्रणाली शीर्ष N सर्वाधिक संबंधित भाग (डिफॉल्ट 5) शोधते जेणेकरून मर्यादांमध्ये राहून अचूक उत्तरासाठी पुरेसा संदर्भ दिला जातो. +प्रत्येक मॉडेलचा जास्तीत जास्त संदर्भ विंडो आकार असतो. मोठ्या दस्तऐवजातून प्रत्येक तुकडा समाविष्ट करता येत नाही. सिस्टम टॉप N सर्वात संबंधित तुकडे (मूलतः 5) मिळवते जेणेकरून मर्यादेत राहून अचूक उत्तरे देता येतील. ## RAG कधी महत्त्वाचा आहे -RAG नेहमीच योग्य पद्धत नाही. खालील निर्णय मार्गदर्शक तुम्हाला ठरवण्यास मदत करतो की RAG कधी मूल्य वाढवतो आणि कधी सोप्प्या पद्धती जसे की थेट प्रॉम्प्टमध्ये सामग्री समाविष्ट करणे किंवा मॉडेलच्या अंतर्निर्मित ज्ञानावर अवलंबून राहणे पुरेसे असतात: +RAG नेहमीच योग्य उपाय नाही. खाली निर्णय मार्गदर्शक आहे जो RAG कधी मूल्य वाढवतो आणि कधी सोपे उपाय (जसे थेट कंटेंट समाविष्ट करणे किंवा मॉडेलच्या अंगभूत ज्ञानावर अवलंबून राहणे) पुरेसे असतात हे ठरवतो: -RAG कधी वापरायचा +When to Use RAG -*ही आकृती दाखवते की RAG कधी मूल्य वाढवतो आणि कधी सोप्या पद्धती पुरेसे असतात.* +*ही आकृती निर्णय मार्गदर्शक दाखवते की RAG कधी मूल्य वाढवते आणि कधी सोपे उपाय पुरेसे असतात.* -## पुढील पावले +## पुढील टप्पे -**पुढील मॉड्युल:** [04-tools - AI एजंट्स विथ टूल्स](../04-tools/README.md) +**पुढील मॉड्यूल:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**नेव्हिगेशन:** [← मागील: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [मुख्यपृष्ठावर परत](../README.md) | [पुढे: Module 04 - Tools →](../04-tools/README.md) +**नॅव्हिगेशन:** [← मागील: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [मुख्यपृष्ठाकडे](../README.md) | [पुढे: Module 04 - Tools →](../04-tools/README.md) --- **अस्वीकरण**: -हा दस्तऐवज AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) वापरून अनुवादित केला आहे. आम्ही अचूकतेसाठी प्रयत्न करतो, तरी कृपया लक्षात ठेवा की स्वयंचलित अनुवादांमध्ये चुका किंवा अचूकतेतील त्रुटी असू शकतात. मूळ दस्तऐवज त्याच्या स्थानिक भाषेत अधिकृत स्रोत म्हणून मानला जावा. महत्त्वाच्या माहितीच्या बाबतीत व्यावसायिक मानवी अनुवाद करण्याचा सल्ला दिला जातो. या अनुवादाच्या वापरामुळे उद्भवणाऱ्या कुठल्याही गैरसमज किंवा चुकीच्या अर्थलावासाठी आम्ही जबाबदार नाही. +हा दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) चा वापर करून अनुवादित केला आहे. जरी आम्ही अचूकतेसाठी प्रयत्न करतो, तरी कृपया लक्षात घ्या की स्वयंचलित भाषांतरांमध्ये त्रुटी किंवा अचूकतेची कमतरता असू शकते. मूळ दस्तऐवज त्याच्या मूळ भाषेत अधिकृत स्रोत मानला पाहिजे. महत्त्वाची माहिती असल्यास, व्यावसायिक मानवी भाषांतराची शिफारस केली जाते. या भाषांतराच्या वापरामुळे उद्भवणाऱ्या कोणत्याही गैरसमज किंवा चुकीच्या अर्थलावणीसाठी आम्ही जबाबदार नाही. \ No newline at end of file diff --git a/translations/mr/04-tools/README.md b/translations/mr/04-tools/README.md index c1dd5db2d..149556bc7 100644 --- a/translations/mr/04-tools/README.md +++ b/translations/mr/04-tools/README.md @@ -1,84 +1,84 @@ -# Module 04: टूल्ससह AI एजंट्स +# Module 04: टूलसह AI एजंट्स ## अनुक्रमणिका -- [व्हिडिओ वॉकथ्रू](../../../04-tools) -- [तुम्हाला काय शिकायला मिळेल](../../../04-tools) -- [पूर्वअट](../../../04-tools) -- [टूल्ससह AI एजंट्स समजून घेणे](../../../04-tools) -- [टूल कॉलिंग कसे कार्य करते](../../../04-tools) - - [टूल व्याख्या](../../../04-tools) - - [निर्णय घेणे](../../../04-tools) - - [अमलबजावणी](../../../04-tools) - - [प्रत्युत्तर निर्मिती](../../../04-tools) - - [आर्किटेक्चर: स्प्रिंग बूट ऑटो-वायरिंग](../../../04-tools) -- [टूल चेनिंग](../../../04-tools) -- [अ‍ॅप्लिकेशन चालवा](../../../04-tools) -- [अ‍ॅप्लिकेशन वापरणे](../../../04-tools) - - [सोप्या टूलच्या वापराचा प्रयत्न करा](../../../04-tools) - - [टूल चेनिंगची चाचणी करा](../../../04-tools) - - [संवाद फ्लो पाहा](../../../04-tools) - - [वेगवेगळ्या विनंत्यांसोबत प्रयोग करा](../../../04-tools) -- [महत्वाच्या संकल्पना](../../../04-tools) - - [ReAct पॅटर्न (तर्कवितर्क आणि कृती)](../../../04-tools) - - [टूल वर्णने महत्त्वाची आहेत](../../../04-tools) - - [सत्र व्यवस्थापन](../../../04-tools) - - [त्रुटी हाताळणी](../../../04-tools) -- [उपलब्ध टूल्स](../../../04-tools) -- [टूल-आधारित एजंट्स कधी वापरावेत](../../../04-tools) -- [टूल्स vs RAG](../../../04-tools) -- [पुढील पायऱ्या](../../../04-tools) +- [व्हिडिओ वॉकथ्रू](#व्हिडिओ-वॉकथ्रू) +- [तुम्हाला काय शिकायला मिळेल](#तुम्हाला-काय-शिकायला-मिळेल) +- [पूर्वअटी](#पूर्वअटी) +- [टूलसह AI एजंट्स समजून घेणे](#टूलसह-ai-एजंट्स-समजून-घेणे) +- [टूल कॉल कसे कार्य करते](#टूल-कॉल-कसे-कार्य-करते) + - [टूल व्याख्या](#टूल-व्याख्या) + - [निर्णय घेणे](#निर्णय-घेणे) + - [अंमलबजावणी](#अंमलबजावणी) + - [प्रतिसाद निर्मिती](#प्रतिसाद-निर्मिती) + - [आर्किटेक्चर: स्प्रिंग बूट ऑटो-वाईरिंग](#आर्किटेक्चर-स्प्रिंग-बूट-ऑटो-वाईरिंग) +- [टूल चेनिंग](#टूल-चेनिंग) +- [अ‍ॅप्लिकेशन चालवा](#अ‍ॅप्लिकेशन-चालवा) +- [अ‍ॅप्लिकेशन वापरणे](#अनुप्रयोग-वापरणे) + - [साध्या टूल वापराचा प्रयत्न करा](#सोप्या-उपकरणाचा-वापर-करा) + - [टूल चेनिंग चाचणी करा](#टूल-चेनिंगची-चाचणी-करा) + - [संवाद प्रवाह पहा](#संवाद-प्रवाह-पहा) + - [विभिन्न विनंत्यांशी प्रयोग करा](#विविध-विनंत्यांसह-प्रयोग-करा) +- [महत्वाची संकल्पना](#मुख्य-संकल्पना) + - [ReAct पॅटर्न (कारण आणि क्रिया)](#react-पॅटर्न-तर्क-आणि-क्रिया) + - [टूल वर्णने महत्त्वाची](#टूल-वर्णनांचा-महत्त्व) + - [सत्र व्यवस्थापन](#सत्र-व्यवस्थापन) + - [त्रुटी हाताळणी](#त्रुटी-हाताळणी) +- [उपलब्ध टूल्स](#उपलब्ध-टूल्स) +- [टूल-आधारित एजंट्स कधी वापरावे](#टूल-आधारित-एजंट्स-वापरण्याची-वेळ) +- [टूल्स विरुद्ध RAG](#टूल्स-विरुद्ध-rag) +- [पुढील टप्पे](#पुढील-पावले) ## व्हिडिओ वॉकथ्रू -हा लाईव्ह सत्र पहा जे सांगते की या मॉड्यूलसह कसे सुरुवात करायची: +हा लाईव्ह सत्र पाहा जो तुम्हाला या मॉड्युलबरोबर सुरुवात कशी करायची ते समजावतो: AI Agents with Tools and MCP - Live Session ## तुम्हाला काय शिकायला मिळेल -आत्तापर्यंत, तुम्ही AI सोबत संवाद कसा साधायचा, प्रभावीपणे प्रॉम्प्ट्स कसे रचायचे, आणि तुमच्या दस्तऐवजांमध्ये प्रतिक्रिया आधारित कशी ठेवायची हे शिकले आहे. पण अजूनही एक मूलभूत मर्यादा आहे: भाषा मॉडेल्स फक्त टेक्स्ट तयार करू शकतात. ते हवामान तपासू शकत नाहीत, गणना करू शकत नाहीत, डेटाबेस चौकशी करू शकत नाहीत किंवा बाह्य प्रणालींबरोबर संवाद करू शकत नाहीत. +आत्ता पर्यंत, तुम्ही AI सोबत संवाद साधण्याचे, प्रभावीप्रकारे प्रॉम्प्ट कसे तयार करायचे आणि तुमच्या दस्तऐवजांमध्ये उत्तरे आधारलेली कशी ठेवायची हे शिकलात. पण अजून एक मूलभूत मर्यादा आहे: भाषा मॉडेल केवळ मजकूर निर्माण करू शकतात. ते हवामान तपासू शकत नाहीत, गणना करू शकत नाहीत, डेटाबेस क्वेरी करू शकत नाहीत किंवा बाह्य प्रणालींसोबत संवाद साधू शकत नाहीत. -टूल्स हे बदलतात. मॉडेलला कॉल करू शकणाऱ्या फंक्शन्सची परवानगी देऊन, तुम्ही ते टेक्स्ट जनरेटरमधून एक एजंटमध्ये रूपांतरित करता जो क्रिया करू शकतो. मॉडेल ठरवते की कधी टूल पाहिजे, कोणते टूल वापरायचे आहे, आणि कोणते पॅरामीटर्स द्यायचे. तुमचा कोड फंक्शन चालवतो आणि निकाल परत करतो. मॉडेल त्या निकालाला त्याच्या प्रतिक्रिया मध्ये समाविष्ट करते. +टूल्स हे बदलतात. मॉडेलला फंक्शन्स वापरण्यास परवानगी देऊन, तुम्ही त्याला एक मजकूर जनरेटरपासून एक एजंटमध्ये बदलता जो क्रिया करू शकतो. मॉडेल ठरवते की त्याला कधी टूल पाहिजे आहे, कोणता टूल वापरायचा आहे, आणि कोणते पॅरामीटर्स द्यायचे आहेत. तुमचा कोड फंक्शन चालवतो आणि निकाल परत करतो. मॉडेल हा निकाल त्याच्या प्रतिक्रियेत समाविष्ट करतो. -## पूर्वअट +## पूर्वअटी -- पूर्ण [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI संसाधने तैनात केली आहेत) -- मागील मॉड्यूल्स पूर्ण केल्या असल्याची शिफारस केली आहे (हा मॉड्यूल [RAG संकल्पना Module 03 येथून](../03-rag/README.md) संदर्भित करतो Tools vs RAG तुलनेत) -- रूट directory मध्ये `.env` फाइल Azure क्रेडेन्शियल्ससह (Module 01 मध्ये `azd up` ने तयार केलेली) +- पूर्ण केलेले [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI संसाधने लागू केलीली) +- मागील मॉड्युल्स पूर्ण केलेले शिफारस केलेले (हा मॉड्युल [RAG संकल्पना Module 03 मधून](../03-rag/README.md) संदर्भित करतो Tools vs RAG तुलना मध्ये) +- मूळ डिरेक्टरीमध्ये `.env` फाइल असावी ज्यात Azure प्रमाणपत्रे असतील (Module 01 मध्ये `azd up` द्वारे तयार केलेली) -> **टीप:** जर तुम्ही Module 01 पूर्ण केला नसेल, तर तिथल्या तैनाती सूचना प्रथम पाळा. +> **टीप:** जर तुम्ही Module 01 पूर्ण केले नसेल, तर प्रथम तिथले तैनाती सूचनांचे पालन करा. -## टूल्ससह AI एजंट्स समजून घेणे +## टूलसह AI एजंट्स समजून घेणे -> **📝 टीप:** या मॉड्यूलमध्ये "एजंट्स" हा शब्द टूल-कॉलिंग क्षमता वाढवलेल्या AI सहाय्यकांना सूचित करतो. हे वेगळे आहे **Agentic AI** पॅटर्न्सपासून (स्वायत्त एजंट्स ज्यामध्ये नियोजन, स्मृती आणि बहु-चरण तर्क आहे) जे आपण [Module 05: MCP](../05-mcp/README.md) मध्ये पाहणार आहोत. +> **📝 टीप:** या मॉड्युलमध्ये "एजंट्स" या संज्ञेचा अर्थ AI सहाय्यक असा आहे ज्यात टूल-कॉल करण्याची क्षमता आहे. हे वेगळे आहे **Agentic AI** पॅटर्नपासून (स्वयंचलित एजंट्स ज्यात नियोजन, आठवण आणि बहु-चरणीय तर्कशक्ती असते) ज्या आपण [Module 05: MCP](../05-mcp/README.md) मध्ये पाहणार आहोत. -टूलशिवाय, भाषा मॉडेल फक्त आपल्या प्रशिक्षण डेटावरून टेक्स्ट तयार करू शकतो. हवामान विचारले तरी, ते अंदाज काढते. टूल्स दिल्यास, ते हवामान API कॉल करू शकतो, गणना करू शकतो, किंवा डेटाबेस चौकशी करू शकतो — मग त्या प्रत्यक्ष निकालांना त्याच्या प्रतिक्रियेत गुंफतो. +टूलशिवाय, एखादे भाषा मॉडेल केवळ त्याच्या प्रशिक्षण डेटापासून मजकूर निर्माण करू शकते. ज्यावेळी तुम्ही त्याला हवामान विचारता, ते अंदाज बांधावे लागते. टूल दिले की, ते हवामान API कॉल करू शकते, गणना करू शकते, डेटाबेस क्वेरी करू शकते — नंतर त्या वास्तविक निकालांना त्याच्या उत्तरात गुंफते. -टूलशिवाय vs टूल्ससह +Without Tools vs With Tools -*टूलशिवाय मॉडेल फक्त अंदाज करतो — टूल्ससह ते API कॉल करू शकते, गणना करू शकते, आणि रिअल-टाइम डेटा परत करू शकते.* +*टूलशिवाय मॉडेल केवळ अंदाज लावते — टूलसह ते API कॉल करू शकते, गणना चालवू शकते आणि रिअल-टाइम डेटा परत करू शकते.* -टूल्ससह AI एजंट **ReAct (Reasoning and Acting)** पॅटर्नचे पालन करतो. मॉडेल फक्त प्रतिसाद करत नाही — ते काय हवे आहे याचा विचार करते, टूल कॉल करून क्रिया करते, निकाल पाहते, आणि मग पुन्हा क्रिया करायची की अंतिम उत्तर द्यायचे हे ठरवते: +टूलसह AI एजंट एक **ReAct (Reasoning and Acting)** पॅटर्नचा अवलंब करतो. मॉडेल फक्त उत्तर देत नाही — ते विचार करते की त्याला काय आवश्यक आहे, त्या टूलला कॉल करते, निकालाचे निरीक्षण करते आणि मग ठरवते की पुन्हा काही करायचे की अंतिम उत्तर द्यायचे. -1. **Reason (तर्क करा)** — एजंट वापरकर्त्याच्या प्रश्नाचा विश्लेषण करतो आणि कोणती माहिती हवी ते ठरवतो -2. **Act (क्रिया करा)** — एजंट योग्य टूल निवडतो, बरोबर पॅरामीटर्स तयार करतो, आणि कॉल करतो -3. **Observe (निरीक्षण करा)** — एजंट टूलचा आउटपुट घेतो आणि निकालाची तपासणी करतो -4. **Repeat or Respond (पुनरावृत्ती करा किंवा उत्तर द्या)** — अधिक माहिती हवी असल्यास एजंट पुन्हा लूपमध्ये जातो; अन्यथा, तो नैसर्गिक भाषेतील उत्तर रचतो +1. **तर्क करा** — एजंट वापरकर्त्याच्या प्रश्नाचे विश्लेषण करतो आणि त्याला कोणती माहिती हवी आहे ते ठरवतो +2. **क्रिया करा** — एजंट योग्य टूल निवडतो, योग्य पॅरामीटर्स तयार करतो आणि कॉल करतो +3. **निरीक्षण करा** — एजंट टूलचा आउटपुट प्राप्त करतो आणि निकालाचे मूल्यांकन करतो +4. **पुन्हा करा किंवा प्रतिसाद द्या** — अधिक डेटा आवश्यक असल्यास, एजंट लूपमध्ये परततो; अन्यथा, नैसर्गिक भाषेत उत्तर तयार करतो -ReAct पॅटर्न +ReAct Pattern -*ReAct चक्र — एजंट काय करायचे ते विचारतो, टूल कॉल करते, निकाल पाहते, आणि अंतिम उत्तर देईपर्यंत लूप करते.* +*ReAct सायकल — एजंट काय करायचे हे विचार करतो, टूल कॉल करतो, निकाल पाहतो आणि तोपर्यंत लूप करतो जोपर्यंत तो अंतिम उत्तर देऊ शकतो.* -हे सर्व स्वयंचलितपणे होते. तुम्ही टूल्स आणि त्यांच्या वर्णनांची व्याख्या करता. मॉडेल ठरवते की कधी आणि कसे टूल वापरायचे. +हे सर्व आपोआप होते. तुम्ही टूल्स आणि त्यांचे वर्णन परिभाषित करता. मॉडेल ठरवते की ते कधी आणि कसे वापरायचे. -## टूल कॉलिंग कसे कार्य करते +## टूल कॉल कसे कार्य करते ### टूल व्याख्या [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -तुम्ही फंक्शन्स स्पष्ट वर्णन आणि पॅरामीटर निर्दिष्टीसह व्याख्यित करता. मॉडेल या वर्णनांना त्याच्या सिस्टम प्रॉम्प्टमध्ये पाहते आणि प्रत्येक टूल काय करते ते समजते. +तुम्ही फंक्शन्स स्पष्ट वर्णनांसह आणि पॅरामीटर विशिष्ट करून परिभाषित करता. मॉडेल या वर्णनांना त्याच्या सिस्टम प्रॉम्प्टमध्ये पाहते आणि प्रत्येक टूल काय करते हे समजते. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // आपले हवामान शोध लॉजिक + // तुमचे हवामान शोधणे लॉजिक return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,153 +96,153 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// सहाय्यक स्वयंचलितपणे Spring Boot ने वायर्ड केला आहे: -// - ChatModel bean +// सहाय्यक स्वयंचलितपणे Spring Boot ने जोडलेले आहे: +// - ChatModel बीन // - @Component वर्गांमधील सर्व @Tool पद्धती // - सत्र व्यवस्थापनासाठी ChatMemoryProvider ``` -खालील आकृती प्रत्येक अॅनोटेशन कसे कार्य करते आणि AI ला कधी टूल कॉल करायचा आणि कोणते अर्ग्युमेंट्स द्यायचे हे कसे समजते ते दाखवते: +खालील आकृती प्रत्येक अ‍ॅनोटेशनचे विश्लेषण करते आणि दर्शवते की AI कधी टूल कॉल करायचे आहे आणि कोणते आर्ग्युमेंट्स द्यायचे आहेत हे कसे समजते: -टूल व्याख्यांचे शरीररचना +Anatomy of Tool Definitions -*टूल व्याख्येचे शरीररचना — @Tool AI ला कधी वापरायचे ते सांगते, @P प्रत्येक पॅरामीटरचे वर्णन करते, आणि @AiService स्टार्टअपमध्ये सर्व काही जोडते.* +*टूल व्याख्येचे रचना — @Tool AI ला सांगते की कधी वापरायचे, @P प्रत्येक पॅरामीटरचे वर्णन करते, आणि @AiService सर्व काही स्टार्टअपवर वायर्स करते.* > **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat सोबत प्रयत्न करा:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) उघडा आणि विचारा: -> - "मॉक डेटाऐवजी OpenWeatherMap सारखा रिअल वेदर API कसा जोडायचा?" -> - "योग्य टूल वर्णन काय असावे जे AI योग्यरित्या वापरू शकेल?" -> - "API त्रुटी आणि रेट लिमिट्स टूल अंमलबजावणीत कशा हाताळाव्यात?" +> - "How would I integrate a real weather API like OpenWeatherMap instead of mock data?" +> - "What makes a good tool description that helps the AI use it correctly?" +> - "How do I handle API errors and rate limits in tool implementations?" ### निर्णय घेणे -जेव्हा वापरकर्ता विचारतो "Seattle मध्ये हवामान काय आहे?", तेव्हा मॉडेल अपप्रमाणितपणे टूल निवडत नाही. ते वापरकर्त्याच्या हेतूची तुलना प्रत्येक टूलच्या वर्णनाशी करते, संबंधिततेसाठी स्कोअर करते, आणि सर्वोत्तम जुळणारे निवडते. मग योग्य पॅरामीटर्ससह संरचित फंक्शन कॉल तयार करते — या बाबतीत `location` ला `"Seattle"` सेट करते. +जेव्हा वापरकर्ता विचारतो "Seattle मध्ये हवामान काय आहे?", तेव्हा मॉडेल अनियमितपणे टूल निवडत नाही. ते वापरकर्त्याच्या उद्देशाचा प्रत्येक टूलच्या वर्णनांसोबत तुलना करते, संबंधासाठी स्कोअरिंग करते आणि सर्वोत्तम जुळणी निवडते. मग ते योग्य पॅरामीटर्ससह संरचित फंक्शन कॉल तयार करते — या प्रकरणात, `location` ला `"Seattle"` सेट करते. -जर कोणताही टूल वापरकर्त्याच्या विनंतीशी जुळत नसेल, तर मॉडेल स्वतःच्या ज्ञानावरून उत्तर देते. जर एकाधिक टूल जुळले, तर सर्वात विशेष टूल निवडते. +जर कोणताही टूल वापरकर्त्याच्या विनंतीशी जुळत नसेल, तर मॉडेल आपले ज्ञान वापरून उत्तर देते. जर अनेक टूल जुळले, तर ते सर्वात विशिष्ट निवडते. -AI कसे ठरवते कोणते टूल वापरायचे +How the AI Decides Which Tool to Use -*मॉडेल प्रत्येक उपलब्ध टूल वापरकर्त्याच्या हेतूसमोर तपासते आणि सर्वोत्तम जुळणारे निवडते — म्हणून स्पष्ट, विशिष्ट टूल वर्णने लिहिणे महत्त्वाचे आहे.* +*मॉडेल प्रत्येक उपलब्ध टूल वापरकर्त्याच्या उद्देशासोबत तुलना करून सर्वोत्तम निवड करते — म्हणून स्पष्ट, विशिष्ट टूल वर्णने लिहिणे महत्त्वाचे आहे.* -### अमलबजावणी +### अंमलबजावणी [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -स्प्रिंग बूट `@AiService` इंटरफेससह सर्व नोंदणीकृत टूल्ज ऑटो-वायर करते, आणि LangChain4j टूल कॉल आपोआप अंमलात आणते. मागच्या बाजूने, टूल कॉल सहा टप्प्यांमध्ये जाते — वापरकर्त्याच्या नैसर्गिक भाषेतील प्रश्नापासून ते परत नैसर्गिक भाषेतील उत्तरापर्यंत: +स्प्रिंग बूट डिक्लेरेटिव्ह `@AiService` इंटरफेस सर्व नोंदणीकृत टूलसह ऑटो-वायर करते, आणि LangChain4j टूल कॉल्स आपोआप चालवतो. दृश्यामागे, संपूर्ण टूल कॉल सहा टप्प्यांतून प्रवाहित होतो — वापरकर्त्याच्या नैसर्गिक भाषेच्या प्रश्नापासून नैसर्गिक भाषेत उत्तर मिळेपर्यंत: -टूल कॉलिंग फ्लो +Tool Calling Flow -*एकंदरीत प्रवाह — वापरकर्ता प्रश्न विचारतो, मॉडेल टूल निवडते, LangChain4j त्याचे अमलबजावणी करते, आणि मॉडेल निकाल नैसर्गिक प्रतिसादात गुंफते.* +*एकूण प्रवास — वापरकर्ता प्रश्न विचारतो, मॉडेल टूल निवडते, LangChain4j ते चालवते, आणि मॉडेल निकाल नैसर्गिक प्रतिक्रियेत गुंफते.* -जर तुम्ही [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) Module 00 मध्ये चालवले असेल, तर तुम्हाला हा पॅटर्न पहिलेच दिसला असेल — `Calculator` टूल्सदेखील त्याच पद्धतीने कॉल केले गेले होते. खालील अनुक्रम आकृती दाखवते की त्या डेमो दरम्यान काय घडले: +दृश्यामागे, `AiServices` कोणत्याही टूलसाठी समान टूल-कॉल लूप चालवते — येथे एक साध्या `Calculator` सह दाखवले आहे. खाली दिलेला सिक्वेन्स डाग्राम अचूक काय घडते ते दर्शवतो: -टूल कॉलिंग सिक्वेन्स डायग्राम +Tool Calling Sequence Diagram -*क्विक स्टार्ट डेमोमधील टूल कॉलिंग लूप — `AiServices` तुमचा मेसेज आणि टूल स्कीमाज LLM कडे पाठवते, LLM `add(42, 58)` सारखा फंक्शन कॉल उत्तर देते, LangChain4j `Calculator` मेथड लोकली अंमलात आणते, आणि अंतिम उत्तरासाठी निकाल परत करतो.* +*टूल-कॉलिंग लूप — `AiServices` तुमचा मेसेज आणि टूल स्कीमास LLM कडे पाठवते, LLM `add(42, 58)` सारखा फंक्शन कॉल परत देते, LangChain4j `Calculator` मेथड स्थानिकरित्या चालवते, आणि निकाल परत अंतिम उत्तरासाठी पुरवते.* > **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat सोबत प्रयत्न करा:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) उघडा आणि विचारा: -> - "ReAct पॅटर्न कसा कार्य करतो आणि AI एजंट्ससाठी का प्रभावी आहे?" -> - "एजंट कसा ठरवतो कोणते टूल वापरायचे आणि कोणत्या क्रमाने?" -> - "जर टूल अंमलबजावणी अयशस्वी झाली तर काय होते - मी त्रुटी कशा बरोबरीनं हाताळू?" +> - "How does the ReAct pattern work and why is it effective for AI agents?" +> - "How does the agent decide which tool to use and in what order?" +> - "What happens if a tool execution fails - how should I handle errors robustly?" -### प्रत्युत्तर निर्मिती +### प्रतिसाद निर्मिती -मॉडेल हवामान डेटा प्राप्त करतो आणि वापरकर्त्यासाठी नैसर्गिक भाषेतील उत्तर तयार करतो. +मॉडेल हवामान माहिती प्राप्त करते आणि वापरकर्त्यासाठी नैसर्गिक भाषेत प्रतिसाद स्वरूपात तयार करते. -### आर्किटेक्चर: स्प्रिंग बूट ऑटो-वायरिंग +### आर्किटेक्चर: स्प्रिंग बूट ऑटो-वाईरिंग -हा मॉड्यूल LangChain4j चा स्प्रिंग बूट समाकलन वापरतो ज्यामध्ये उद्घोषित `@AiService` इंटरफेस असतात. स्टार्टअपमध्ये स्प्रिंग बूट प्रत्येक `@Component` शोधतो ज्यात `@Tool` पद्धती असतात, तुमचा `ChatModel` बीन, आणि `ChatMemoryProvider` — आणि त्यानंतर त्यांना सिंगल `Assistant` इंटरफेसमध्ये जोडतो कोणताही बोइलरप्लेटशिवाय. +हा मॉड्युल LangChain4j चा स्प्रिंग बूट एकत्रीकरण वापरतो डिक्लेरेटिव्ह `@AiService` इंटरफेसेससह. स्टार्टअपवर स्प्रिंग बूट प्रत्येक `@Component` जो `@Tool` मेथड्स असलेला असतो, तुमचा `ChatModel` बीन, आणि `ChatMemoryProvider` शोधून सर्व एकत्र एक `Assistant` इंटरफेस मध्ये वायर्स करतो, कोणताही कोड न लिहिता. -स्प्रिंग बूट ऑटो-वायरिंग आर्किटेक्चर +Spring Boot Auto-Wiring Architecture -*@AiService इंटरफेस ChatModel, टूल कंपोनेंट्स, आणि मेमरी प्रोव्हायडर एकत्र करतो — स्प्रिंग बूट सर्व वायरिंग आपोआप करते.* +*@AiService इंटरफेस ChatModel, टूल कंपोनेंट्स, आणि मेमरी प्रोव्हायडर एकत्र करतो — स्प्रिंग बूट सर्व वायरींग आपोआप हाताळते.* -इथे पूर्ण विनंती जीवनचक्र आहे एक सिक्वेन्स डायग्राममध्ये — HTTP विनंती कडून कंट्रोलर, सर्व्हिस, ऑटो-वायरड प्रॉक्सी पर्यंत, आणि नंतर टूलच्या अंमलबजावणीपर्यंत: +आहे पूर्ण विनंती जीवनचक्र सिक्वेन्स डाग्राम मध्ये — HTTP विनंती कंट्रोलर, सर्व्हिस, आणि ऑटो-वायर्ड प्रॉक्सीमधून टूल अंमलबजावणीपर्यंत आणि परत: -स्प्रिंग बूट टूल कॉलिंग सिक्वेन्स +Spring Boot Tool Calling Sequence -*पूर्ण स्प्रिंग बूट विनंती जीवनचक्र — HTTP विनंती कंट्रोलर आणि सर्व्हिसमधून ऑटो-वायरड Assistant प्रॉक्सीपर्यंत जाते, जो LLM आणि टूल कॉल्स आपोआप नियोजित करतो.* +*पूर्ण स्प्रिंग बूट विनंती जीवनचक्र — HTTP विनंती कंट्रोलर आणि सर्व्हिस मधून ऑटो-वायर्ड Assistant प्रॉक्सीपर्यंत जाते, जो LLM आणि टूल कॉल्स आपोआप समन्वयित करतो.* या दृष्टिकोनाचे मुख्य फायदे: -- **स्प्रिंग बूट ऑटो-वायरिंग** — ChatModel आणि टूल्स आपोआप इंजेक्ट होतात -- **@MemoryId पॅटर्न** — स्वयंचलित सत्र-आधारित मेमरी व्यवस्थापन -- **सिंगल इन्स्टन्स** — Assistant एकदा तयार होतो आणि परफॉर्मन्ससाठी पुनर्वापर होतो -- **टाईप-सेफ अंमलबजावणी** — Java मेथड्स थेट टाईप कन्व्हर्शनसह कॉल होतात -- **मल्टि-टर्न ऑर्केस्ट्रेशन** — टूल चेनिंग आपोआप हाताळतो -- **शून्य बोइलरप्लेट** — कोणताही हाताने `AiServices.builder()` कॉल किंवा मेमरी HashMap नाही +- **स्प्रिंग बूट ऑटो-वायरींग** — ChatModel आणि टूल्स आपोआप इंजेक्ट होतात +- **@MemoryId पॅटर्न** — ऑटोमॅटिक सत्र-आधारित मेमरी व्यवस्थापन +- **सिंगल इन्स्टन्स** — Assistant एकदाच तयार होत राहतो आणि चांगल्या प्रदर्शनासाठी पुनर्वापर होतो +- **टाइप-सेफ अंमलबजावणी** — Java मेथड्स थेट टाइप रूपांतरणासह कॉल केल्या जातात +- **मल्टि-टर्न ऑर्केस्ट्रेशन** — टूल चेनिंग आपोआप हाताळते +- **झिरो बॉयलरप्लेट** — मॅन्युअल `AiServices.builder()` कॉल्स किंवा मेमरी HashMap नाही -वैकल्पिक पद्धत (हाताने `AiServices.builder()` वापरणे) अधिक कोडची गरज असते आणि स्प्रिंग बूट समाकलन फायदे गमावते. +अल्टरनेटिव्ह पद्धती (मॅन्युअल `AiServices.builder()`) मध्ये अधिक कोड लागतो आणि स्प्रिंग बूट एकत्रीकरणाचे फायदे मिळत नाहीत. ## टूल चेनिंग -**टूल चेनिंग** — टूल्सवर आधारित एजंट्सची खरी ताकद तेव्हा दिसते जेव्हा एका प्रश्नासाठी अनेक टूल्सची गरज असते. "Seattle मध्ये हवामान फॅरेनहाइटमध्ये काय आहे?" विचारल्यास एजंट आपोआप दोन टूल्सची चेन तयार करतो: प्रथम `getCurrentWeather` कॉल करतो तापमान सेल्यिअस मध्ये मिळवण्यासाठी, मग तो मूल्य `celsiusToFahrenheit` मध्ये रूपांतरासाठी देतो — हे सगळं एका संवाद टर्नमध्ये होते. +**टूल चेनिंग** — टूल-आधारित एजंट्सची खरी ताकद तेव्हा दिसते जेव्हा एकाच प्रश्नाला अनेक टूल्सची गरज असते. विचार करा "Seattle मध्ये हवामान Fahrenheit मध्ये काय आहे?" आणि एजंट आपोआप दोन टूल्सला चेन करतो: प्रथम ते `getCurrentWeather` कॉल करते जे Celsius मध्ये तापमान देते, नंतर तो तो मूल्य `celsiusToFahrenheit` मध्ये रुपांतरासाठी पाठवते — हा सगळा एकाच संवादात. -टूल चेनिंग उदाहरण +Tool Chaining Example -*टूल चेनिंग क्रियेत — एजंट प्रथम getCurrentWeather कॉल करतो, मग सेल्यिअस निकाल celsiusToFahrenheit मध्ये पाठवतो, आणि एकत्रित उत्तर देतो.* +*कार्यक्षम टूल चेनिंग — एजंट प्रथम getCurrentWeather कॉल करतो, मग Celsius निकाल celsiusToFahrenheit मध्ये पाठवतो, आणि एकत्रित उत्तर देते.* -**सुगम अपयश** — मॉक डेटामध्ये नसलेल्या शहराचा हवामान विचारल्यास टूल त्रुटी संदेश देतो, आणि AI सांगते की ते मदत करू शकत नाही, अ‍ॅप क्रॅश होणार नाही. टूल्स सुरक्षितपणे अयशस्वी होतात. खालील आकृती दोन पद्धतींचा फरक दाखवते — योग्य त्रुटी हाताळणीने एजंट अपवाद पकडतो आणि उपयुक्त प्रतिक्रिया देतो, तर न हाताळल्यास संपूर्ण अ‍ॅप्लिकेशन क्रॅश होते: +**सुसंवेदनशील अपयश** — तुमची विनंती अशी करा की ती मॉक डेटामध्ये नसलेल्या शहराची हवामान मागते. टूल त्रुटी संदेश परत करते, आणि AI सांगते की ती मदत करू शकत नाही, संपूर्ण अ‍ॅप्लिकेशन क्रॅश होत नाही. टूल सुरक्षितरित्या अपयशी ठरतात. खालील आकृती दोन दृष्टिकोन दाखवते — योग्य त्रुटी हाताळणीसह एजंट अपवाद पकडतो आणि सहाय्यक स्पष्टीकरण देतो, तर त्रुटीशिवाय संपूर्ण अ‍ॅप्लिकेशन क्रॅश होते: -त्रुटी हाताळणी प्रवाह +Error Handling Flow -*जेव्हा टूल अयशस्वी होते, एजंट त्रुटी पकडतो आणि क्रॅश न करता उपयुक्त स्पष्टीकरणासह प्रतिसाद देतो.* +*टूल अपयशी ठरल्यास, एजंट त्रुटी पकडतो आणि क्रॅश न होता सहाय्यक स्पष्टीकरण देतो.* -हे सर्व एका संवाद टर्नमध्ये होते. एजंट अनेक टूल कॉल आपोआप नियोजित करतो. +हे सर्व एका संवादात होते. एजंट स्वायत्तपणे अनेक टूल कॉल्स समन्वयित करतो. ## अ‍ॅप्लिकेशन चालवा -**तैनातीची पुष्टी करा:** +**तैनात केले आहे याची खात्री करा:** -रूट directory मध्ये `.env` फाइल आहे याची खात्री करा ज्यात Azure क्रेडेन्शियल्स आहेत (Module 01 दरम्यान तयार केलेली). मॉड्यूल डायरेक्टरी (`04-tools/`) मधून हे चालवा: +मूल डिरेक्टरीमध्ये `.env` फाइल आहे ज्यात Azure क्रेडेन्शियल्स आहेत (Module 01 मध्ये तयार केलेली). मॉड्युल डिरेक्टरी (`04-tools/`) मधून खालीलपैकी चालवा: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवले पाहिजे +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवले पाहिजेत ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवायला हवे +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT दाखवायला हवेत ``` -**अ‍ॅप्लिकेशन सुरू करा:** +**अ‍ॅप्लिकेशन सुरु करा:** -> **टीप:** जर तुम्ही आधीच `./start-all.sh` वापरून सर्व अ‍ॅप्लिकेशन्स सुरू केली असतील रूट directory मधून (Module 01 मध्ये वर्णन केलेले), तर हा मॉड्यूल पोर्ट 8084 वर आधीच चालू आहे. तुम्ही पुढील स्टार्ट कमांड टाळून थेट http://localhost:8084 वर जाऊ शकता. +> **टीप:** जर तुम्ही मूळ डिरेक्टरीतून (`./start-all.sh`) सर्व अ‍ॅप्लिकेशन्स आधीच सुरू केले असतील (Module 01 मध्ये वर्णन केलेले), तर हा मॉड्युल आधीच पोर्ट 8084 वर चालू आहे. तुम्ही खालील स्टार्ट कमांड स्किप करू शकता आणि थेट http://localhost:8084 वर प्रवेश करू शकता. -**पर्याय 1: स्प्रिंग बूट डॅशबोर्ड वापरणे (VS Code वापरकर्त्यांसाठी शिफारस केलेले)** +**पर्याय 1: स्प्रिंग बूट डॅशबोर्ड वापरणे (VS कोड वापरकर्त्यांसाठी शिफारस)** -डेव्ह कंटेनरमध्ये स्प्रिंग बूट डॅशबोर्ड विस्तार समाविष्ट आहे, जो सर्व स्प्रिंग बूट अ‍ॅप्लिकेशन्सची दृष्यात्मक नियंत्रण प्रदान करतो. तुम्हाला ते VS Code मधल्या Activity Bar मध्ये डाव्या बाजूला (स्प्रिंग बूट आयकॉन शोधा) सापडेल. +डेव्ह कंटेनर मध्ये स्प्रिंग बूट डॅशबोर्ड विस्तार समाविष्ट आहे, जो सर्व स्प्रिंग बूट अ‍ॅप्लिकेशन्सचा व्हिज्युअल इंटरफेस पुरवतो. तुम्ही ते VS कोड च्या डाव्या बाजूला असलेल्या अ‍ॅक्टिव्हिटी बार मध्ये शोधू शकता (स्प्रिंग बूट चिह्नाचा शोध घ्या). -स्प्रिंग बूट डॅशबोर्डमधून तुम्ही: +स्प्रिंग बूट डॅशबोर्ड मधून, तुम्ही: - वर्कस्पेसमधील सर्व उपलब्ध स्प्रिंग बूट अ‍ॅप्लिकेशन्स पाहू शकता -- एक क्लिकने अ‍ॅप्लिकेशन्स सुरू/थांबवू शकता -- रिअल-टाइममध्ये अ‍ॅप्लिकेशन लॉग पाहू शकता -- अ‍ॅप्लिकेशन स्थिती देखरेख करू शकता -“tools” च्या बाजूला प्ले बटणावर क्लिक करा हा मोड्यूल सुरू करण्यासाठी, किंवा सर्व मोड्यूल एकाच वेळी सुरू करा. +- एका क्लिकमध्ये अ‍ॅप्लिकेशन्स सुरू / थांबवू शकता +- अ‍ॅप्लिकेशन लॉग्स वास्तविक वेळेत पाहू शकता +- अ‍ॅप्लिकेशन स्थितीवर नजर ठेवू शकता -VS Code मधील Spring Boot डॅशबोर्ड कसा दिसतो ते येथे आहे: +फक्त "tools" समोर असलेला प्ले बटण क्लिक करा हा मॉड्युल सुरू करण्यासाठी, किंवा सर्व मॉड्युल्स एकत्र सुरू करा. +स्प्रिंग बूट डॅशबोर्ड VS कोड मध्ये असे दिसतो: Spring Boot Dashboard -*VS Code मधील Spring Boot डॅशबोर्ड — सर्व मोड्यूल एका ठिकाणी सुरू करा, थांबवा आणि निरीक्षण करा* +*VS कोडमधील Spring Boot डॅशबोर्ड — सर्व मॉड्यूल एका ठिकाणाहून सुरु करा, थांबवा आणि निरीक्षण करा* -**पर्याय 2: शेल स्क्रिप्ट वापरणे** +**पर्याय 2: shell स्क्रिप्ट्स वापरणे** -सर्व वेब अनुप्रयोग (मोड्यूल 01-04) सुरू करा: +सर्व वेब अनुप्रयोग सुरु करा (मॉड्यूल 01-04): **Bash:** ```bash -cd .. # रूट डिरेक्टरी मधून +cd .. # मूळ निर्देशिकेतून ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # मूळ निर्देशिकेतून +cd .. # रूट निर्देशिका पासून .\start-all.ps1 ``` -किंवा फक्त हा मोड्यूल सुरू करा: +किंवा फक्त हा मॉड्यूल सुरु करा: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -दोन्ही स्क्रिप्ट्स आपोआप रूट `.env` फाईलमधून पर्यावरण चल लोड करतात आणि जर JAR अस्तित्वात नसतील तर त्यांना तयार करतात. +दोन्ही स्क्रिप्ट्स आपोआप मूळ `.env` फाइलमधील पर्यावरण चल (environment variables) लोड करतात आणि JAR फाइल्स अस्तित्वात नसेल तर तयार करतात. -> **टीप:** जर तुम्हाला सर्व मोड्यूल्स मॅन्युअली तयार करायची असतील तर सुरू करण्यापूर्वी: +> **टीप:** तुम्हाला सर्व मॉड्यूल्स मॅन्युअली तयार करायचे असतील: > > **Bash:** > ```bash @@ -272,116 +272,116 @@ cd 04-tools > mvn clean package -DskipTests > ``` -http://localhost:8084 तुमच्या ब्राउझरमध्ये उघडा. +http://localhost:8084 तुमच्या ब्राऊजरमध्ये उघडा. -**थांबवण्यासाठी:** +**थांबविण्यासाठी:** **Bash:** ```bash ./stop.sh # हा मॉड्यूल फक्त # किंवा -cd .. && ./stop-all.sh # सर्व मॉड्यूल्स +cd .. && ./stop-all.sh # सर्व मॉड्यूल ``` **PowerShell:** ```powershell -.\stop.ps1 # फक्त हे मॉड्यूल +.\stop.ps1 # हे फक्त मॉड्यूल # किंवा -cd ..; .\stop-all.ps1 # सर्व मॉड्यूल +cd ..; .\stop-all.ps1 # सर्व मॉड्यूल्स ``` ## अनुप्रयोग वापरणे -अनुप्रयोग वेब इंटरफेस प्रदान करतो जिथे तुम्ही हवामान आणि तापमान रूपांतर साधने उपलब्ध असलेल्या AI एजंटशी संवाद करू शकता. इंटरफेस कसे दिसतो ते येथे आहे — यामध्ये जलद सुरुवातीसाठी उदाहरणे आणि विनंत्या पाठवण्यासाठी चॅट पॅनेल असते: +अॅप्लिकेशन वेब इंटरफेस प्रदान करते जिथे तुम्ही हवामान आणि तापमान रूपांतरण उपकरणांपर्यंत प्रवेश असलेल्या AI एजंटशी संवाद साधू शकता. इंटरफेस असे दिसते — त्यात त्वरीत सुरूवातीचे उदाहरणे आणि विनंत्या पाठवण्यासाठी चॅट पॅनेल आहे: AI Agent Tools Interface -*AI एजंट टूल्स इंटरफेस - साधे उदाहरणे आणि उपकरणांसह संवादासाठी चॅट इंटरफेस* +*AI एजंट टूल्स इंटरफेस - त्वरीत उदाहरणे आणि टूल्सशी संवादासाठी चॅट इंटरफेस* -### साधे टूल वापर प्रयत्न करा +### सोप्या उपकरणाचा वापर करा -एका सोप्या विनंतीने सुरुवात करा: "100 डिग्री फारेनहाइट ते सेल्सियस रूपांतर करा". एजंट ओळखतो की त्याला तापमान रूपांतर साधन वापरायचे आहे, योग्य पॅरामीटर्ससह ते कॉल करतो आणि निकाल परत करतो. हे नैसर्गिक कसे वाटते ध्यान द्या - तुम्ही कोणते टूल वापरायचे आहे किंवा कसे कॉल करायचे आहे ते सांगितले नाही. +सरळ विनंतीने प्रारंभ करा: "100 डिग्री फॅरेनहाइट ते सेल्सिअस मध्ये रूपांतरित करा". एजंट ओळखतो की तापमान रूपांतरण टूलची आवश्यकता आहे, योग्य पारामीटरांसह कॉल करतो आणि परिणाम परत करतो. हे नैसर्गिक कसे वाटते लक्षात घ्या - तुम्ही कोणते टूल वापरायचे किंवा कसे कॉल करायचे ते निर्दिष्ट केले नव्हते. -### टूल साखळी तपासा +### टूल चेनिंगची चाचणी करा -आता थोडे जास्त जटिल प्रयत्न करा: "सिएटलमधील हवामान काय आहे आणि ते फारेनहाइटमध्ये रूपांतर करा?" पहा एजंट हे कोणत्या पायऱ्यांमध्ये हाताळतो. तो प्रथम हवामान घेतो (जे सेल्सियसमध्ये परतते), नंतर रूपांतरासाठी फारेनहाइटमध्ये रूपांतर साधन वापरतो, आणि दोन्ही निकाल एकत्र करून परत करतो. +आता काही अधिक गुंतागुंतीचे प्रयत्न करा: "सिएटलमधील हवामान काय आहे आणि ते फॅरेनहाइटमध्ये रूपांतरित करा?" एजंटने हे टप्प्याटप्प्याने कसे हाताळले ते पाहा. प्रथम हवामान मिळवतो (जो सेल्सिअसमध्ये परत करतो), नंतर ते फॅरेनहाइटमध्ये रूपांतरित करण्याची गरज ओळखतो, रूपांतरण टूल कॉल करतो आणि दोन्ही निकाल एकत्र करून उत्तर देतो. -### संभाषण प्रवाह बघा +### संवाद प्रवाह पहा -चॅट इंटरफेस संभाषण इतिहास ठेवतो, ज्यामुळे तुम्ही अनेक टप्प्यांमध्ये संवाद करू शकता. तुम्ही सर्व मागील प्रश्न आणि उत्तरे पाहू शकता, ज्यामुळे संभाषणाचा मागोवा ठेवणे आणि एजंट कसे संदर्भ तयार करतो ते समजणे सोपे होते. +चॅट इंटरफेस संभाषण इतिहास सांभाळतो, जेणेकरून तुम्हाला बहु-फेरींच्या संवादाचा अनुभव घेता येतो. तुम्ही मागील सर्व प्रश्न आणि उत्तरे पाहू शकता, जे संभाषणाचा मागोवा ठेवणे आणि एजंट कसा संदर्भ तयार करतो हे समजण्यास मदत करते. Conversation with Multiple Tool Calls -*बहु-पटक संभाषण जेथे साधे रूपांतर, हवामान शोध आणि टूल साखळी दाखवली आहे* +*सोप्या रूपांतरणांपासून हवामान तपासणीपर्यंत आणि टूल चेनिंगपर्यंत बहु-फेरींचे संभाषण* -### वेगवेगळ्या विनंत्यांसह प्रयोग करा +### विविध विनंत्यांसह प्रयोग करा -विविध संयोजन प्रयत्न करा: -- हवामान शोध: "टोकियोमधील हवामान काय आहे?" -- तापमान रूपांतर: "25°C किती केल्विनमध्ये आहे?" -- संयुक्त प्रश्न: "पॅरिसमधील हवामान तपासा आणि मला सांगा ते 20°C पेक्षा जास्त आहे का" +विविध संयोजने प्रयत्न करा: +- हवामान तपासणी: "टोकियोमधील हवामान काय आहे?" +- तापमान रूपांतरण: "25°C काय केल्विनमध्ये आहे?" +- एकत्रित प्रश्न: "पॅरिसमध्ये हवामान तपासा आणि ते 20°C पेक्षा जास्त आहे का ते सांगा" -एजंट नैसर्गिक भाषा कशी समजतो आणि योग्य टूल कॉलशी कसा जुळवतो हे लक्षात घ्या. +एजंट नैसर्गिक भाषा कशी समजतो आणि योग्य टूल कॉल्सशी नकाशा कसा तयार करतो हे लक्षात घ्या. ## मुख्य संकल्पना -### ReAct पॅटर्न (विचार आणि क्रिया) +### ReAct पॅटर्न (तर्क आणि क्रिया) -एजंट विचार (काय करायचे ते ठरवणे) आणि क्रिया (टूल्स वापरणे) मध्ये बदल करतो. हा पॅटर्न केवळ सूचना न मानता स्वयंचलित समस्या सोडवण्यास सक्षम करतो. +एजंट तर्क (काय करावे हे ठरवणे) आणि क्रिया (टूल्स वापरणे) यामध्ये परस्पर बदलतो. हा पॅटर्न स्वयंपूर्ण समस्या सोडवण्यास मदत करतो, केवळ सूचना पाळण्यापेक्षा. -### टूल वर्णने महत्त्वाची आहेत +### टूल वर्णनांचा महत्त्व -टूल्सच्या वर्णनांची गुणवत्ता थेट एजंट कसे त्यांचा वापर करतो यावर परिणाम करते. स्पष्ट, विशिष्ट वर्णने मॉडेलला कधी आणि कसे टूल कॉल करायचे ते समजायला मदत करतात. +तुमच्या टूलचे वर्णन किती स्पष्ट आहे हे थेट एजंटच्या टूल वापरावर परिणाम करते. स्पष्ट आणि ठराविक वर्णने मॉडेलला कधी आणि कसे टूल कॉल करायचे समजावतात. ### सत्र व्यवस्थापन -`@MemoryId` अ‍ॅनोटेशन स्वयंचलित सत्र-आधारित मेमरी व्यवस्थापन सक्षम करते. प्रत्येक सत्र आयडीला त्याचा स्वतःचा `ChatMemory` उदाहरण `ChatMemoryProvider` बीनद्वारे व्यवस्थापित केला जातो, त्यामुळे एकापेक्षा जास्त वापरकर्ते एजंटशी एकाच वेळी संवाद साधू शकतात आणि त्यांचे संभाषण मिळून जात नाही. खालील रेखाचित्र दर्शवते की कसे अनेक वापरकर्ते त्यांच्या सत्र आयडीवर आधारित वेगळ्या स्मृती साठ्यांमध्ये पाठवले जातात: +`@MemoryId` अ‍ॅनोटेशन स्वयंचलित सत्र-आधारित मेमरी व्यवस्थापन सक्षम करते. प्रत्येक सत्र ID ला `ChatMemory` उदाहरण मिळते जे `ChatMemoryProvider` बीन्सने व्यवस्थापित केली जाते, त्यामुळे अनेक वापरकर्ते एजंटशी एकाच वेळी संवाद साधू शकतात, परस्पर संभाषण मिसळत नाही. खालील आकृती दाखवते की अनेक वापरकर्ते त्यांच्या सत्र ID च्या आधारे वेगळ्या मेमरी स्टोअरकडे कसे निर्देशित होतात: Session Management with @MemoryId -*प्रत्येक सत्र आयडी वेगळ्या संभाषण इतिहासाशी जुळतो — वापरकर्ते एकमेकांच्या संदेशांना कधीही पाहू शकत नाहीत.* +*प्रत्येक सत्र ID वेगळ्या संभाषण इतिहासाशी नकाशित होतो — वापरकर्ते एकमेकांचे संदेश पाहू शकत नाहीत.* ### त्रुटी हाताळणी -टूल्स अयशस्वी होऊ शकतात — API टाइमआउट, पॅरामीटर्स चुकीचे असू शकतात, बाह्य सेवा गहाळ होऊ शकतात. उत्पादन एजंटसाठी त्रुटी हाताळणी गरजेची आहे जेणेकरून मॉडेल समस्या समजावून सांगू शकेल किंवा पर्यायी उपाय वापरू शकेल, पूर्ण अनुप्रयोग कोसळणार नाही. जेव्हा टूल अपवाद उडवते, तेव्हा LangChain4j ते पकडते आणि त्रुटी संदेश मॉडेलकडे परत पाठवते, जे नंतर नैसर्गिक भाषेत समस्या समजावते. +टूल्स अपयशी ठरू शकतात — API टाइमआउट होते, पारामीटर चुकीचे असू शकतात, बाह्य सेवा बंद होतात. उत्पादन एजंट्सकडे त्रुटी हाताळणी असावी जेणेकरून मॉडेल समस्या समजावून सांगू शकेल किंवा पर्यायी उपाय करू शकेल, पूर्ण अनुप्रयोग क्रॅश न होऊ देत. टूलने अपवाद फेकल्यास, LangChain4j तो पकडतो आणि त्रुटी संदेश मॉडेलपर्यंत पाठवतो जे निसर्ग भाषेत समस्या समजावते. ## उपलब्ध टूल्स -खालील आकृती टूल्सच्या विस्तृत परिसंस्थेचे दर्शन घडवते ज्यात तुम्ही तयार करू शकता. हा मोड्यूल हवामान आणि तापमान टूल्स दाखवतो, पण त्याच `@Tool` पॅटर्नने कोणतीही Java मेथड - डेटाबेस क्वेरीजपासून पेमेंट प्रोसेसिंगपर्यंत वापरता येते. +खालील आकृती तुम्ही तयार करू शकणाऱ्या टूल्सच्या विस्तृत परिसंस्थेचा दाखला देते. हा मॉड्यूल हवामान आणि तापमान टूल्स दाखवतो, पण तोच `@Tool` पॅटर्न कोणत्याही Java पद्धतीसाठी वापरू शकतो — डेटाबेस क्वेरीज ते पेमेंट प्रक्रिया पर्यंत. Tool Ecosystem -*@Tool ने अ‍ॅनोट केलेली कोणतीही Java मेथड AI साठी उपलब्ध होते — हा पॅटर्न डेटाबेस, API, ईमेल, फाईल ऑपरेशन्स आणि बरेच काही यांपर्यंत विस्तारतो.* +*`@Tool` अ‍ॅनोटेशन असलेली कोणतीही Java पद्धत AI साठी उपलब्ध होते — हा पॅटर्न डेटाबेस, API, ईमेल, फाइल ऑपरेशन्स आणि बरेच काही विस्तारतो.* -## टूल-आधारित एजंट कधी वापरायचे +## टूल-आधारित एजंट्स वापरण्याची वेळ -प्रत्येक विनंतीस टूल्सची गरज नसते. निर्णय हा असतो की AI ला बाह्य प्रणालींशी संवाद साधायचा आहे का किंवा स्वतःच्या ज्ञानावरून उत्तर देता येते का. खालील मार्गदर्शकमध्ये कधी टूल्स उपयोगी ठरतात आणि केव्हा ते टाळावेत याचे सारांश दिले आहे: +प्रत्येक विनंतीसाठी टूल्स आवश्यक नाहीत. निर्णय यावर अवलंबून आहे की AI ला बाह्य प्रणालींसोबत संवाद करायचा आहे की नाही किंवा ते स्वतःच्या ज्ञानावरून उत्तर देऊ शकतो. खालील मार्गदर्शक सादर करतो की टूल्स कधी फायदेशीर आहेत आणि कधी गरजेचे नाहीत: When to Use Tools -*जलद निर्णयासाठी मार्गदर्शक — टूल्स रिअल-टाइम डेटा, गणनांसाठी आणि क्रियांसाठी; सामान्य ज्ञान आणि सर्जनशील कार्यासाठी आवश्यक नाहीत.* +*त्वरीत निर्णय घेण्यासाठी मार्गदर्शक — टूल्स वास्तविक वेळ डेटा, गणना आणि क्रिया साठी; सामान्य ज्ञान आणि सर्जनशील कामांसाठी आवश्यक नाहीत.* ## टूल्स विरुद्ध RAG -मोड्यूल 03 आणि 04 हे AI काय करू शकतो यामध्ये सुधारणा करतात, पण मूलभूतपणे वेगळ्या प्रकारे. RAG मॉडेलला **ज्ञान** वापरण्याची संधी देते कागदपत्रे शोधून. टूल्स मॉडेलला **क्रिया** पार पाडण्याची क्षमता देतात फंक्शन्स कॉल करून. खालील आकृती या दोन दृष्टिकोनांची तुलना करतात — कसे कार्यप्रवाह चालवितात आणि त्यांच्यातील ट्रेड-ऑफ काय आहेत: +मॉड्यूल 03 आणि 04 दोन्ही AI काय करू शकतो हे वाढवतात, पण मूलत: वेगळ्या मार्गांनी. RAG मॉडेलला **ज्ञान** देते, दस्तऐवज पुन्हा मिळवून. टूल्स मॉडेलला **क्रिया** घेण्याची क्षमता देतात, फंक्शन्स कॉल करून. खालील आकृती दोन्ही पद्धतींचे एकमेकांच्या समोर तुलनात्मक दाखले देते — प्रत्येक कार्यप्रवाह कसे चालतो आणि दोघांतील फरक कसे आहेत: Tools vs RAG Comparison -*RAG स्थिर कागदपत्रांमधून माहिती शोधतो — टूल्स क्रिया पार पाडतात आणि डायनॅमिक, रिअल-टाइम डेटा आणतात. अनेक उत्पादन प्रणाली दोन्हींचा संगम करतात.* +*RAG स्थिर दस्तऐवजांमधून माहिती मिळवते — टूल्स क्रिया करतात आणि गतिशील, वास्तविक-वेळ डेटा मिळवतात. अनेक उत्पादन प्रणाली दोन्ही पद्धती एकत्र वापरतात.* -वास्तविक, अनेक उत्पादन प्रणाली दोन्ही दृष्टिकोन एकत्र करतात: RAG तुमच्या दस्तऐवजांमध्ये उत्तर तयार करण्यासाठी आणि टूल्स थेट डेटा आणण्यासाठी किंवा ऑपरेशन्ससाठी. +प्रत्यक्षात, अनेक उत्पादन प्रणाली दोन्ही पद्धती वापरतात: RAG तुमच्या दस्तऐवजातून उत्तरांचे आधार मिळवण्यासाठी, आणि टूल्स लाइव्ह डेटा मिळवण्यासाठी किंवा ऑपरेशन्स करण्यासाठी. ## पुढील पावले -**पुढील मोड्यूल:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**पुढील मॉड्यूल:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**नेव्हिगेशन:** [← मागील: मोड्यूल 03 - RAG](../03-rag/README.md) | [मुख्यपृष्ठाकडे परत](../README.md) | [पुढे: मोड्यूल 05 - MCP →](../05-mcp/README.md) +**नेव्हिगेशन:** [← मागील: मॉड्यूल 03 - RAG](../03-rag/README.md) | [मुख्य पानावर परत जा](../README.md) | [पुढील: मॉड्यूल 05 - MCP →](../05-mcp/README.md) --- **अस्वीकरण**: -हा दस्तऐवज AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) चा वापर करून अनुवादित केला आहे. आम्ही अचूकतेसाठी प्रयत्नशील असलो तरी, कृपया लक्षात ठेवा की स्वयंचलित अनुवादांमध्ये चुका किंवा अचूकतेची कमतरता असू शकते. मूळ कागदपत्र त्याच्या स्थानिक भाषेत अधिकृत स्रोत समजले पाहिजे. महत्त्वपूर्ण माहिती साठी व्यावसायिक मानव अनुवाद करणे शिफारसीय आहे. या अनुवादाच्या वापरामुळे निर्माण झालेल्या कोणत्याही गैरसमज किंवा चुकीच्या अर्थलाव्यांसाठी आम्ही जबाबदार नाही. +हा दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) चा वापर करून अनुवादित केला आहे. जरी आम्ही अचूकतेसाठी प्रयत्न करतो, तरी कृपया लक्षात घ्या की स्वयंचलित भाषांतरांमध्ये त्रुटी किंवा अचूकतेची कमतरता असू शकते. मूळ दस्तऐवज त्याच्या मूळ भाषेत अधिकृत स्रोत मानला पाहिजे. महत्त्वाची माहिती असल्यास, व्यावसायिक मानवी भाषांतराची शिफारस केली जाते. या भाषांतराच्या वापरामुळे उद्भवणाऱ्या कोणत्याही गैरसमज किंवा चुकीच्या अर्थलावणीसाठी आम्ही जबाबदार नाही. \ No newline at end of file diff --git a/translations/mr/README.md b/translations/mr/README.md index 55b00b6dd..9dcd6c597 100644 --- a/translations/mr/README.md +++ b/translations/mr/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j सुरुवातीसाठी +# LangChain4j प्रारंभिकांसाठी -LangChain4j आणि Azure OpenAI GPT-5.2 वापरून AI अनुप्रयोग तयार करण्यासाठी एक कोर्स, मूलभूत चॅटपासून AI एजंट्सपर्यंत. +LangChain4j आणि Azure OpenAI GPT-5.2 सह AI अनुप्रयोग निर्माण करण्यासाठी एक अभ्यासक्रम, मूलभूत चॅट ते AI एजंटपर्यंत. ### 🌐 बहुभाषिक समर्थन -#### GitHub क्रिया द्वारे समर्थित (स्वयंचलित आणि नेहमी अद्ययावत) +#### GitHub Action द्वारे समर्थित (स्वयंचलित आणि नेहमी अद्ययावत) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](./README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **स्थानिक क्लोन प्राधान्य देता?** +> **स्थानिकपणे क्लोन करणे प्राधान्य द्यायचे आहे?** > -> या रेपॉजिटरीमध्ये 50+ भाषांमध्ये भाषांतर केले आहे ज्यामुळे डाउनलोड आकार मोठा होतो. भाषांतरांशिवाय क्लोन करण्यासाठी sparse checkout वापरा: +> या संग्रहात 50+ भाषा भाषांतर समाविष्ट आहेत ज्यामुळे डाउनलोडचा आकार लक्षणीय वाढतो. भाषांतरांशिवाय क्लोन करण्यासाठी sparse checkout वापरा: > > **Bash / macOS / Linux:** > ```bash @@ -29,61 +29,60 @@ LangChain4j आणि Azure OpenAI GPT-5.2 वापरून AI अनुप् > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> यात तुम्हाला कोर्स पूर्ण करण्यासाठी आवश्यक सर्व काही खूप गतिमान डाउनलोडसह मिळेल. +> यामुळे तुम्हाला अभ्यासक्रम पूर्ण करण्यासाठी आवश्यक सर्वकाही खूप वेगाने डाउनलोड होईल. -## अनुक्रमणिका +## मजकूर सूची -1. [त्वरित सुरुवात](00-quick-start/README.md) - LangChain4j सह सुरुवात करा -2. [परिचय](01-introduction/README.md) - LangChain4j चे मूलतत्त्व जाणून घ्या -3. [प्रॉम्प्ट अभियांत्रिकी](02-prompt-engineering/README.md) - प्रभावी प्रॉम्प्ट डिझाइनमध्ये पारंगत व्हा -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - बुद्धिमान ज्ञानाधारित प्रणाली तयार करा -5. [टूल्स](04-tools/README.md) - बाह्य साधने आणि सोप्या सहाय्यकांसह एकत्रित करा -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Model Context Protocol (MCP) आणि Agentic मॉड्यूलसह काम करा +1. [परिचय](01-introduction/README.md) - LangChain4j चे मूलभूत तत्त्वे शिका +2. [प्रॉम्प्ट अभियांत्रिकी](02-prompt-engineering/README.md) - प्रभावी प्रॉम्प्ट डिझाइनमध्ये पारंगत व्हा +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - बुद्धिमान ज्ञानाधारित सिस्टम तयार करा +4. [टूल्स](04-tools/README.md) - बाह्य टूल्स आणि सोप्या सहाय्यकांशी एकत्रीकरण करा +5. [MCP (मॉडेल संदर्भ प्रोटोकॉल)](05-mcp/README.md) - Model Context Protocol (MCP) आणि Agentic मॉड्यूल्ससह काम करा -### व्हिडिओ वॉकथ्रू +### व्हिडीओ मार्गदर्शने -प्रत्येक मॉड्यूलसाठी एक सत्र आहे जिथे आपण संकल्पना आणि कोड टप्प्याटप्प्याने पाहतो. +प्रत्येक मॉड्यूलसाठी एक साथीदार थेट सत्र असते जिथे आपण संकल्पना आणि कोड टप्प्याटप्प्याने समजून घेऊ. -| मॉड्यूल | व्हिडिओ | +| मॉड्यूल | व्हिडीओ | |--------|-------| | 01 - परिचय | [LangChain4j सह सुरुवात](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - प्रॉम्प्ट अभियांत्रिकी | [LangChain4j सह प्रॉम्प्ट अभियांत्रिकी](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [LangChain4j सह RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - टूल्स & 05 - MCP | [टूल्स आणि MCP सह AI एजंट्स](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - टूल्स & 05 - MCP | [टूल्स आणि MCP सह AI एजंट](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## शिक्षण मार्ग +## शिकण्याचा मार्ग -**LangChain4j मध्ये नवीन आहात का?** महत्त्वाच्या संकल्पनांसाठी [शब्दसंग्रह](docs/GLOSSARY.md) पहा. +**LangChain4j मध्ये नवीन आहात?** महत्त्वाच्या संज्ञा आणि संकल्पनांसाठी [शब्दसंचय](docs/GLOSSARY.md) पहा. -> **त्वरित सुरुवात** +> **जलद प्रारंभ** -1. ही रेपॉजिटरी तुमच्या GitHub खात्यावर Fork करा -2. **Code** → **Codespaces** टॅब → **...** → **New with options...** क्लिक करा -3. डीफॉल्ट्स वापरा – यामुळे या कोर्ससाठी तयार केलेले विकास कंटेनर निवडले जाईल -4. **Create codespace** क्लिक करा -5. वातावरण तयार होण्यासाठी 5-10 मिनिटे प्रतीक्षा करा -6. थेट [त्वरित सुरुवात](./00-quick-start/README.md) येथे जा आणि सुरू करा! +1. हा संग्रह तुमच्या GitHub खात्यावर Fork करा +2. क्लिक करा **Code** → **Codespaces** टॅब → **...** → **New with options...** +3. पूर्वनिर्धारित सेटिंग्ज वापरा – हे या अभ्यासक्रमासाठी तयार केलेल्या Development container निवडेल +4. क्लिक करा **Create codespace** +5. पर्यावरण तयार होण्यासाठी 5-10 मिनिटे थांबा +6. थेट [परिचय](./01-introduction/README.md) कडे जा आणि सुरुवात करा! -मॉड्यूल पूर्ण केल्यानंतर, LangChain4j च्या टेस्टिंग संकल्पना पहाण्यासाठी [टेस्टिंग मार्गदर्शक](docs/TESTING.md) एक्सप्लोर करा. +मॉड्यूल पूर्ण केल्यानंतर, LangChain4j च्या चाचणी संकल्पनांचा प्रत्यक्ष अनुभव घेण्यासाठी [चाचणी मार्गदर्शिका](docs/TESTING.md) एक्सप्लोर करा. -> **नोट:** हे प्रशिक्षण GitHub मॉडेल्स आणि Azure OpenAI दोन्ही वापरते. [त्वरित सुरुवात](00-quick-start/README.md) मॉड्यूल GitHub मॉडेल्स वापरते (Azure सदस्यता आवश्यक नाही), तर मॉड्यूल 1-5 मध्ये Azure OpenAI वापरले जाते. जर तुमच्याकडे नसेल तर [मोफत Azure खाते](https://aka.ms/azure-free-account) वापरून सुरू करा. +> **टीप:** हा प्रशिक्षण Azure OpenAI वापरतो. तुमच्याकडे नसेल तर [मुफत Azure खाते](https://aka.ms/azure-free-account) घेऊन सुरुवात करा. -## GitHub Copilot सह शिक्षण +## GitHub Copilot सह शिकणे -कोडिंग लवकर सुरू करण्यासाठी, हा प्रकल्प GitHub Codespace मध्ये किंवा दिलेल्या devcontainer सह तुमच्या स्थानिक IDE मध्ये उघडा. या कोर्समध्ये वापरलेला devcontainer GitHub Copilot सह पूर्व-संरचीत केलेला आहे, जो AI आधारित जोडीदार प्रोग्रामिंगसाठी आहे. +त्वरित कोडिंग सुरू करण्यासाठी, GitHub Codespace किंवा स्थानिक IDE मध्ये दिलेला devcontainer वापरून हा प्रकल्प उघडा. या अभ्यासक्रमात वापरलेला devcontainer GitHub Copilot ने पूर्व-निर्धारित आहे, ज्यामुळे AI जोडलेले प्रोग्रामिंग सोपे होते. -प्रत्येक कोड उदाहरणात GitHub Copilot कडे विचारू शकणारे सुचवलेले प्रश्न समाविष्ट आहेत ज्यामुळे तुमची समज वाढेल. 💡/🤖 प्रॉम्प्टसाठी पाहा: +प्रत्येक कोड उदाहरणासह GitHub Copilot कडे विचारण्यासाठी सुचवलेले प्रश्न असतात, जे तुमची समज अधिक खोल करण्यात मदत करतात. 💡/🤖 या सुचनांवर लक्ष ठेवा: -- **Java फाइलच्या हेडर** - प्रत्येक उदाहरणासाठी विशिष्ट प्रश्न -- **मॉड्यूल README** - कोड उदाहरणांनंतरच्या शोध प्रश्न +- **Java फाइल हेडर्स** - प्रत्येक उदाहरणासंबंधित प्रश्न +- **मॉड्यूल README** - कोड उदाहरणानंतरच्या अन्वेषणासाठी प्रॉम्प्ट -**कसे वापरायचे:** कोणतीही कोड फाइल उघडा आणि Copilot कडे सुचवलेले प्रश्न विचारा. त्याला संपूर्ण कोडबेसची पार्श्वभूमी असते आणि तो समजावून सांगू शकतो, विस्तारित करू शकतो, आणि पर्याय सुचवू शकतो. +**कसे वापरायचे:** कोणतीही कोड फाइल उघडा आणि Copilot ला सुचवलेले प्रश्न विचारा. त्याच्याकडे संपूर्ण कोड बेसचा संदर्भ आहे आणि तो स्पष्टीकरण, विस्तार आणि पर्याय सुचवू शकतो. -आणि अधिक शिकायचे आहे का? पाहा [Copilot for AI Paired Programming](https://aka.ms/GitHubCopilotAI). +अधिक जाणून घ्यायचं? [AI जोडलेले प्रोग्रामिंगसाठी Copilot](https://aka.ms/GitHubCopilotAI) पहा. ## अतिरिक्त संसाधने @@ -111,40 +110,41 @@ LangChain4j आणि Azure OpenAI GPT-5.2 वापरून AI अनुप् --- -### कोर शिक्षण +### Core Learning [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![सुरक्षितता सुरुवातीसाठी](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![वेब विकास सुरुवातीसाठी](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT सुरुवातीसाठी](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR विकास सुरुवातीसाठी](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### कॉपायलट मालिका -[![AI जोडलेल्या प्रोग्रामिंगसाठी कॉपायलट](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET साठी कॉपायलट](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![कॉपायलट साहस](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +### Copilot मालिक +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## मदत घेणे -जर तुम्ही अडकले असाल किंवा AI अॅप्स तयार करताना काही प्रश्न असतील तर सामील व्हा: +जर आपण अडकलात किंवा AI अॅप्स तयार करण्याबाबत कोणतेही प्रश्न असतील, तर सामील व्हा: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -जर तुमच्याकडे उत्पादन संदर्भात अभिप्राय किंवा त्रुटी असतील तर येथे भेट द्या: +जर आपल्याकडे उत्पादनावर प्रतिसाद किंवा त्रुटी असतील तर भेट द्या: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## परवाना -MIT परवाना - तपशीलांसाठी [LICENSE](../../LICENSE) फाइल पहा. +MIT परवाना - तपशीलांसाठी [LICENSE](../../LICENSE) फाईल पहा. --- -**सवालाखालील सूचना**: -हा दस्तऐवज AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) वापरून अनुवादित केला आहे. आम्ही अचूकतेसाठी प्रयत्न करतो, कृपया लक्षात ठेवा की स्वयंचलित अनुवादांमध्ये चुका किंवा अचूकतेत त्रुटी असू शकतात. मूळ दस्तऐवज त्याच्या देशी भाषेत अधिकृत स्रोत म्हणून विचारात घ्यावा. महत्त्वपूर्ण माहितीच्या बाबतीत व्यावसायिक मानवी अनुवादाची शिफारस केली जाते. या अनुवादाच्या वापरामुळे होणाऱ्या कोणत्याही गैरसमजुती किंवा चुकीच्या अर्थ लावण्याबद्दल आम्ही जबाबदार नाही. +**अस्वीकरण**: +हा दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) चा वापर करून अनुवादित केला आहे. जरी आम्ही अचूकतेसाठी प्रयत्न करतो, तरी कृपया लक्षात घ्या की स्वयंचलित भाषांतरांमध्ये त्रुटी किंवा अचूकतेची कमतरता असू शकते. मूळ दस्तऐवज त्याच्या मूळ भाषेत अधिकृत स्रोत मानला पाहिजे. महत्त्वाची माहिती असल्यास, व्यावसायिक मानवी भाषांतराची शिफारस केली जाते. या भाषांतराच्या वापरामुळे उद्भवणाऱ्या कोणत्याही गैरसमज किंवा चुकीच्या अर्थलावणीसाठी आम्ही जबाबदार नाही. \ No newline at end of file diff --git a/translations/mr/docs/GLOSSARY.md b/translations/mr/docs/GLOSSARY.md index c7e8ff379..e7c270999 100644 --- a/translations/mr/docs/GLOSSARY.md +++ b/translations/mr/docs/GLOSSARY.md @@ -1,72 +1,72 @@ -# LangChain4j शब्दसंग्रह +# LangChain4j शब्दकोश -## अनुक्रमणिका +## विषय सूची -- [मूल संकल्पना](../../../docs) -- [LangChain4j घटक](../../../docs) -- [AI/ML संकल्पना](../../../docs) -- [गार्डरेल्स](../../../docs) -- [प्रॉम्प्ट अभियांत्रण](../../../docs) -- [RAG (रिट्रीव्हल-अगमेंटेड जनरेशन)](../../../docs) -- [एजंट्स आणि साधने](../../../docs) -- [एजंटिक मॉड्यूल](../../../docs) -- [मॉडेल संदर्भ प्रोटोकॉल (MCP)](../../../docs) -- [Azure सेवा](../../../docs) -- [चाचणी आणि विकास](../../../docs) +- [कोर संकल्पना](#कोर-संकल्पना) +- [LangChain4j घटक](#langchain4j-घटक) +- [AI/ML संकल्पना](#aiml-संकल्पना) +- [गार्डरेल्स](#गार्डरेल्स) +- [प्रॉम्प्ट अभियांत्रिकी](#प्रॉम्प्ट-अभियांत्रिकी---मॉड्यूल-02) +- [RAG (रिट्रीव्हल-ऑगमेंटेड जनरेशन)](#rag-रिट्रीव्हल-ऑगमेंटेड-जनरेशन---मॉड्यूल-03) +- [एजंट आणि टूल्स](#एजंट-आणि-टूल्स---मॉड्यूल-04) +- [एजंटिक मॉड्यूल](#एजंटिक-मॉड्यूल---मॉड्यूल-05) +- [मॉडेल कॉन्टेक्स्ट प्रोटोकॉल (MCP)](#मॉडेल-कॉन्टेक्स्ट-प्रोटोकॉल-mcp---मॉड्यूल-05) +- [Azure सेवा](#azure-सेवा---मॉड्यूल-01) +- [चाचणी आणि विकास](#चाचणी-आणि-विकास---चाचणी-मार्गदर्शक) -कोर्समध्ये वापरल्या जाणाऱ्या संज्ञा आणि संकल्पनांसाठी जलद संदर्भ. +पूर्ण अभ्यासक्रमात वापरलेल्या शब्दांसाठी व संकल्पनांसाठी जलद संदर्भ. -## मूल संकल्पना +## कोर संकल्पना -**AI एजंट** - एखादी प्रणाली जी AI वापरून स्वयंचलित विचार आणि कृती करते. [मॉड्यूल 04](../04-tools/README.md) +**AI एजंट** - AI वापरून स्वायत्त विचार करणारी व कृती करणारी प्रणाली. [मॉड्यूल 04](../04-tools/README.md) -**चेन** - क्रियांचा अनुक्रम ज्यामध्ये आउटपुट पुढील टप्प्यासाठी इनपुट म्हणून वापरले जाते. +**चेन** - ऑपरेशन्सची साखळी ज्यात आउटपुट पुढील स्टेपमध्ये जाते. -**चंकिंग** - दस्तऐवज छोटे तुकडे करण्याची प्रक्रिया. सामान्यतः: 300-500 टोकन ओव्हरलॅपसह. [मॉड्यूल 03](../03-rag/README.md) +**चंकिंग** - दस्तऐवज छोटे भागांमध्ये विभाजित करणे. सामान्य: 300-500 टोकनसह ओव्हरलॅप. [मॉड्यूल 03](../03-rag/README.md) -**संदर्भ विंडो** - जास्तीत जास्त टोकन्स जे मॉडेल प्रक्रिया करू शकते. GPT-5.2: 400K टोकन्स (272K इनपुटपर्यंत, 128K आउटपुटपर्यंत). +**कॉन्टेक्स्ट विंडो** - मॉडेल प्रक्रिया करू शकणाऱ्या टोकन्सचा कमाल मार्जिन. GPT-5.2: 400K टोकन्स (जास्तीत जास्त 272K इनपुट, 128K आउटपुट). -**एम्बेडिंग्ज** - मजकूराचा अर्थ दर्शवणारे संख्यात्मक वेक्टर. [मॉड्यूल 03](../03-rag/README.md) +**एम्बेडिंग्ज** - मजकुराचा अर्थ दर्शवणारे संख्यात्मक वेक्टर. [मॉड्यूल 03](../03-rag/README.md) -**फंक्शन कॉलिंग** - मॉडेल बाह्य फंक्शन्स कॉल करण्यासाठी संरचित विनंत्या निर्माण करते. [मॉड्यूल 04](../04-tools/README.md) +**फंक्शन कॉलिंग** - मॉडेल बाह्य फंक्शन्स कॉल करण्यासाठी रचनेत विनंत्या तयार करते. [मॉड्यूल 04](../04-tools/README.md) -**हल्लुसीनेशन** - जेव्हा मॉडेल चुकीची पण शक्य तितकी माहिती निर्माण करतात. +**हेलुसिनेशन** - जेव्हा मॉडेल चुकीची पण संभाव्य माहिती निर्माण करतात. -**प्रॉम्प्ट** - भाषिक मॉडेलसाठी मजकूर इनपुट. [मॉड्यूल 02](../02-prompt-engineering/README.md) +**प्रॉम्प्ट** - भाषेच्या मॉडेलनुसार इनपुट मजकूर. [मॉड्यूल 02](../02-prompt-engineering/README.md) -**सिमॅंटिक सर्च** - कीवर्ड नाही तर एम्बेडिंग्ज वापरून अर्थानुसार शोध. [मॉड्यूल 03](../03-rag/README.md) +**सिमँटिक सर्च** - एम्बेडिंग्ज वापरून अर्थानुसार शोध, कीवर्ड न वापरता. [मॉड्यूल 03](../03-rag/README.md) -**स्टेटफुल विरुद्ध स्टेटलेस** - स्टेटलेस: स्मृती नाही. स्टेटफुल: संभाषणाचा इतिहास राखतो. [मॉड्यूल 01](../01-introduction/README.md) +**स्टेटफुल विरुद्ध स्टेटलेस** - स्टेटलेस: स्मृती नाही. स्टेटफुल: संभाषण इतिहास राखतो. [मॉड्यूल 01](../01-introduction/README.md) -**टोकन्स** - मूलभूत मजकूर युनिट्स जे मॉडेल प्रक्रिया करतात. खर्च आणि मर्यादा यावर परिणाम करतात. [मॉड्यूल 01](../01-introduction/README.md) +**टोकन्स** - मॉडेल प्रक्रिया करणारे मूलभूत मजकूर घटक. खर्च आणि मर्यादा प्रभावित करतात. [मॉड्यूल 01](../01-introduction/README.md) -**टूल चेनिंग** - साखळीवार टूल अंमलबजावणी जेथे आउटपुट पुढील कॉलसाठी माहिती देते. [मॉड्यूल 04](../04-tools/README.md) +**टूल चेनिंग** - एकाप्रमाणे टूल्सच्या अनुक्रमे अंमलबजावणी ज्यात आउटपुट पुढील कॉलसाठी वापरले जाते. [मॉड्यूल 04](../04-tools/README.md) ## LangChain4j घटक -**AiServices** - प्रकार-सुरक्षित AI सेवा इंटरफेस तयार करतो. +**AiServices** - प्रकार-सुरक्षित AI सेवा इंटरफेसेस तयार करतो. -**OpenAiOfficialChatModel** - OpenAI आणि Azure OpenAI मॉडेलसाठी एकात्मिक क्लायंट. +**OpenAiOfficialChatModel** - OpenAI आणि Azure OpenAI मॉडेल्ससाठी एकात्मिक क्लायंट. -**OpenAiOfficialEmbeddingModel** - OpenAI अधिकृत क्लायंट वापरून एम्बेडिंग्ज तयार करतो (दोन्ही OpenAI आणि Azure OpenAI साठी समर्थन). +**OpenAiOfficialEmbeddingModel** - OpenAI अधिकृत क्लायंट वापरून एम्बेडिंग्ज तयार करतो (दोन्ही OpenAI आणि Azure OpenAI समर्थित). **ChatModel** - भाषिक मॉडेलसाठी मुख्य इंटरफेस. -**ChatMemory** - संभाषण इतिहास राखते. +**ChatMemory** - संभाषण इतिहास टिकवून ठेवतो. -**ContentRetriever** - RAG साठी संबंधित दस्तऐवज चंक शोधतो. +**ContentRetriever** - RAG साठी संबंधित दस्तऐवज चंक्स शोधतो. -**DocumentSplitter** - दस्तऐवज चंकमध्ये विभाजित करतो. +**DocumentSplitter** - दस्तऐवज चंक्समध्ये विभाजित करतो. **EmbeddingModel** - मजकूर संख्यात्मक वेक्टरमध्ये रूपांतरित करतो. -**EmbeddingStore** - एम्बेडिंग्ज संग्रहित व प्राप्त करतो. +**EmbeddingStore** - एम्बेडिंग्ज साठवतो आणि पुनर्प्राप्त करतो. -**MessageWindowChatMemory** - अलीकडील संदेशांचा स्लाइडिंग विंडो राखतो. +**MessageWindowChatMemory** - अलीकडील संदेशांचे स्लायडिंग विंडो राखतो. -**PromptTemplate** - `{{variable}}` प्लेसहोल्डर वापरून पुनर्निर्मित करण्यायोग्य प्रॉम्प्ट तयार करतो. +**PromptTemplate** - `{{variable}}` प्लेसहोल्डरसह पुनर्वापरयोग्य प्रॉम्प्ट तयार करतो. -**TextSegment** - मेटाडेटासह मजकूराचा तुकडा. RAG मध्ये वापरला जातो. +**TextSegment** - मेटाडेटा असलेला मजकूर चंक. RAG मध्ये वापरला जातो. **ToolExecutionRequest** - टूल अंमलबजावणीची विनंती दर्शवतो. @@ -76,157 +76,155 @@ **फ्यू-शॉट लर्निंग** - प्रॉम्प्टमध्ये उदाहरणे देणे. [मॉड्यूल 02](../02-prompt-engineering/README.md) -**लार्ज लँग्वेज मॉडेल (LLM)** - प्रचंड मजकूर डेटावर प्रशिक्षित AI मॉडेल्स. +**लार्ज लँग्वेज मॉडेल (LLM)** - मोठ्या प्रमाणावर मजकूर डेटा वापरून AI मॉडेल्स. -**रिझनिंग प्रयास** - GPT-5.2 चे पॅरामीटर जे विचार करण्याची खोली नियंत्रित करते. [मॉड्यूल 02](../02-prompt-engineering/README.md) +**रिझनिंग एफर्ट** - GPT-5.2 मध्ये विचार करण्याची खोली नियंत्रित करणारा पॅरामिटर. [मॉड्यूल 02](../02-prompt-engineering/README.md) -**टेम्परेचर** - आउटपुटची अनियमितता नियंत्रित करते. कमी = निश्चित, जास्त = सर्जनशील. +**टेम्परेचर** - आउटपुट विरुद्ध यादृच्छिकतेवर नियंत्रण ठेवतो. कमी=नियत, जास्त=सर्जनशील. **व्हेक्टर डेटाबेस** - एम्बेडिंग्जसाठी खास डेटाबेस. [मॉड्यूल 03](../03-rag/README.md) -**झिरो-शॉट लर्निंग** - उदाहरणांशिवाय कार्ये करणे. [मॉड्यूल 02](../02-prompt-engineering/README.md) +**झिरो-शॉट लर्निंग** - कोणतीही उदाहरणे न देता कामे करणं. [मॉड्यूल 02](../02-prompt-engineering/README.md) -## गार्डरेल्स - [मॉड्यूल 00](../00-quick-start/README.md) +## गार्डरेल्स -**डिफेन्स इन डेप्थ** - मल्टी-लेयर सुरक्षा पद्धत ज्यात अनुप्रयोग-स्तरीय गार्डरेल्स आणि प्रदाता सुरक्षा फिल्टर्स यांचा समावेश आहे. +**डीफेन्स इन डेप्थ** - मल्टी-लेयर सुरक्षा दृष्टीकोन ज्यात अ‍ॅप्लिकेशन-लेव्हल गार्डरेल्स आणि प्रदाता सुरक्षा फिल्टर्स यांचा समावेश आहे. -**हार्ड ब्लॉक** - गंभीर सामग्री उल्लंघनांसाठी प्रदाता HTTP 400 त्रुटी देतो. +**हार्ड ब्लॉक** - गंभीर सामग्री उल्लंघनांसाठी प्रदाता HTTP 400 त्रुटी देते. -**InputGuardrail** - LLM पर्यंत पोहोचण्याआधी वापरकर्त्याचा इनपुट सत्यापित करणारा LangChain4j इंटरफेस. हानिकारक प्रॉम्प्ट्स लवकर ब्लॉक करून खर्च आणि विलंब कमी करतो. +**InputGuardrail** - LangChain4j इंटरफेस जे वापरकर्त्याचा इनपुट LLM पर्यंत पोहोचण्यापूर्वी वैधता तपासते. हानिकारक प्रॉम्प्ट्स लवकर ब्लॉक करून खर्च आणि विलंब कमी करते. -**InputGuardrailResult** - गार्डरेल सत्यापनासाठी परतावा प्रकार: `success()` किंवा `fatal("कारण")`. +**InputGuardrailResult** - गार्डरेल वैधतेसाठी परतावा प्रकार: `success()` किंवा `fatal("कारण")`. -**OutputGuardrail** - AI उत्तरे वापरकर्त्यांकडे परत देण्याआधी सत्यापित करण्याचे इंटरफेस. +**OutputGuardrail** - AI प्रतिसादांना वापरकर्त्यांना परत देण्यापूर्वी वैध करण्यासाठी इंटरफेस. -**Provider Safety Filters** - AI प्रदात्यांकडून अंतर्भूत सामग्री फिल्टर्स (उदा., GitHub मॉडेल्स) जे API स्तरावर उल्लंघने पकडतात. +**Provider Safety Filters** - AI प्रदात्यांकडून (उदा. Azure OpenAI) अंगभूत कंटेंट फिल्टर्स जे API स्तरावर उल्लंघने पकडतात. -**Soft Refusal** - मॉडेल विनम्रपणे उत्तर देण्यास नकार देते पण त्रुटी थोडक्यात न दाखवते. +**Soft Refusal** - मॉडेल आदरपूर्वक उत्तर देण्यास नकार देते पण त्रुटी टाकत नाही. -## प्रॉम्प्ट अभियांत्रण - [मॉड्यूल 02](../02-prompt-engineering/README.md) +## प्रॉम्प्ट अभियांत्रिकी - [मॉड्यूल 02](../02-prompt-engineering/README.md) -**चेन-ऑफ-थॉट** - अधिक अचूकतेसाठी टप्प्याटप्प्याने विचार प्रक्रिया. +**चेन-ऑफ-थॉट** - चांगल्या अचूकतेसाठी टप्प्याटप्प्याने कारणं समजावणं. -**बांधलेले आउटपुट** - विशिष्ट स्वरूप किंवा रचना लागू करणे. +**कॉनस्ट्रेन्ड आउटपुट** - विशिष्ट फॉर्मॅट किंवा रचना लागू करणे. -**हाय ईगरनेस** - सखोल विचारासाठी GPT-5.2 नमुना. +**हाय ईगरनेस** - GPT-5.2 नमूना ज्यामध्ये सखोल विचार केला जातो. -**लो ईगरनेस** - जलद उत्तरांसाठी GPT-5.2 नमुना. +**लो ईगरनेस** - GPT-5.2 नमूना ज्यामध्ये जलद उत्तरे दिली जातात. -**मल्टी-टर्न संभाषण** - विनिमयांदरम्यान संदर्भ राखणे. +**मल्टी-टर्न संभाषण** - विनिमयांमध्ये कॉन्टेक्स्ट राखणे. -**भूमिकेनिहाय प्रॉम्प्टिंग** - सिस्टम संदेशांद्वारे मॉडेलची व्यक्तिरेखा सेट करणे. +**रोल-आधारित प्रॉम्प्टिंग** - सिस्टम संदेशाद्वारे मॉडेल व्यक्तिमत्व सेट करणे. -**स्व-परावर्तन** - मॉडेल आपले आउटपुट मूल्यांकन करते व सुधारते. +**सेल्फ-रिफ्लेक्शन** - मॉडेल स्वतःच्या आउटपुटचे मूल्यांकन व सुधारणा करतो. -**संरचित विश्लेषण** - निश्चित मूल्यमापन चौकट. +**संरचित विश्लेषण** - ठराविक मूल्यांकन फ्रेमवर्क. -**कार्य अंमलबजावणी नमुना** - योजना → अंमलबजावणी → सारांश. +**टास्क एक्झिक्युशन पॅटर्न** - योजना → अंमलबजावणी → सारांश. -## RAG (रिट्रीव्हल-अगमेंटेड जनरेशन) - [मॉड्यूल 03](../03-rag/README.md) +## RAG (रिट्रीव्हल-ऑगमेंटेड जनरेशन) - [मॉड्यूल 03](../03-rag/README.md) **दस्तऐवज प्रक्रिया पाइपलाइन** - लोड → चंक → एम्बेड → संचयित करा. -**इन-मेमरी एम्बेडिंग स्टोअर** - तपासणीसाठी अस्थायी संग्रहण. +**इन-मेमरी एम्बेडिंग स्टोर** - तपासणीसाठी अस्थायी संचयन. -**RAG** - उत्तरांना आधार देण्यासाठी रिट्रीव्हल आणि जनरेशन एकत्रित करणे. +**RAG** - प्रतिसादांना आधार देण्यासाठी रिट्रीव्हल आणि जनरेशन एकत्र करते. -**समानता गुणांकन** - सैमान्यतेचे मापन (0-1). +**समानता स्कोअर** - सिमँटिक समानतेचे मापक (0-1). -**स्रोत संदर्भ** - मिळालेल्या सामग्रीचा मेटाडेटा. +**स्रोत संदर्भ** - प्राप्त कंटेंटचे मेटाडेटा. -## एजंट्स आणि साधने - [मॉड्यूल 04](../04-tools/README.md) +## एजंट आणि टूल्स - [मॉड्यूल 04](../04-tools/README.md) -**@Tool अ‍ॅनोटेशन** - Java पद्धतींना AI-कॉल करण्यायोग्य साधन म्हणून मार्क करते. +**@Tool अनुलेखन** - Java पद्धतींना AI-कॉल करण्यायोग्य टूल्स म्हणून चिन्हांकित करते. -**ReAct नमुना** - विचार करा → कृती करा → निरीक्षण करा → पुनरावृत्ती करा. +**ReAct पॅटर्न** - विचार करा → कृती करा → निरीक्षण करा → पुनरावृत्ती करा. -**सत्र व्यवस्थापन** - वेगवेगळ्या वापरकर्त्यांसाठी वेगळे संदर्भ. +**सेशन व्यवस्थापन** - वेगवेगळ्या वापरकर्त्यांसाठी वेगळे कॉन्टेक्स्ट. -**साधन** - एखादा AI एजंट कॉल करू शकतो असा फंक्शन. +**टूल** - AI एजंट कॉल करू शकणारे फंक्शन. -**साधन वर्णन** - साधनाचा हेतू आणि पॅरामीटर्स यांचे दस्तऐवजीकरण. +**टूल वर्णन** - टूलच्या उद्देश आणि पॅरामीटर्सचे दस्तऐवजीकरण. ## एजंटिक मॉड्यूल - [मॉड्यूल 05](../05-mcp/README.md) -**@Agent अ‍ॅनोटेशन** - AI एजंट्ससाठी इंटरफेस मार्क करते ज्यात घोषणा प्रकारचे वर्तन संज्ञापित केले आहे. +**@Agent अनुलेखन** - इंटरफेसेसना AI एजंट्स म्हणून चिन्हांकित करते ज्यात घोषणात्मक वर्तन परिभाषित आहे. -**Agent Listener** - `beforeAgentInvocation()` आणि `afterAgentInvocation()` द्वारे एजंट अंमलबजावणी निरीक्षणासाठी हुक. +**एजंट लिसनर** - `beforeAgentInvocation()` आणि `afterAgentInvocation()` द्वारे एजंट अंमलबजावणी निरीक्षणासाठी हुक. -**Agentic Scope** - संयुक्त स्मृती ज्यात एजंट आउटपुट `outputKey` वापरून संग्रहित करतात, पुढील एजंटसाठी उपभोगात्मक. +**एजंटिक स्कोप** - सामायिक स्मृती जिथे एजंट आउटपुट `outputKey` वापरून साठवतात ज्याचा वापर जवळच्या एजंट्स करतात. -**AgenticServices** - `agentBuilder()` आणि `supervisorBuilder()` वापरून एजंट तयार करण्यासाठी कारखाना. +**AgenticServices** - `agentBuilder()` आणि `supervisorBuilder()` वापरून एजंट तयार करण्यासाठी फॅक्टरी. -**शर्तीपर आधारावर कार्यप्रवाह** - अटींवर आधारित भिन्न तज्ञ एजंट्स कडे मार्गदर्शन. +**कंडिशनल वर्कफ्लो** - भिन्न विशेषज्ञ एजंटना परिस्थितीनुसार मार्गदर्शन. -**मानव-इन-द-लूप** - मानवी तपासणीसाठी माणसाला संधी देणारा कार्यप्रवाह नमुना. +**मानव-मध्यस्त** - मानवी तपासणी व मंजुरीसाठी मानवी तपासणी टप्पा असलेला वर्कफ्लो. -**langchain4j-agentic** - घोषणात्मक एजंट बांधणीसाठी Maven अवलंबित्व (प्रायोगिक). +**langchain4j-agentic** - घोषणात्मक एजंट बनवण्यासाठी मावेन डिपेंडेंसी (प्रायोगिक). -**लूप कार्यप्रवाह** - एखादी अट पूर्ण होईपर्यंत एजंटची पुनरावृत्ती (उदा., गुणवत्ता गुण ≥ 0.8). +**लूप वर्कफ्लो** - एखादी अट पूर्ण होईपर्यंत एजंट पुनरावृत्ती (उदा. गुणवत्ता स्कोअर ≥ 0.8). -**outputKey** - एजंट अ‍ॅनोटेशन पॅरामीटर जो Agentic Scope मध्ये निकाल कुठे साठवायचा ते दर्शवतो. +**outputKey** - एजंट अनुलेखन पॅरामीटर जे एजंटिक स्कोपमध्ये निकाल कसे साठवायचे ते सांगते. -**सामांतर कार्यप्रवाह** - स्वतंत्र कार्यांसाठी एकाच वेळी अनेक एजंट चालवणे. +**पॅरेलल वर्कफ्लो** - स्वतंत्र कामांसाठी एकाच वेळी अनेक एजंट्स चालवा. -**उत्तर धोरण** - पर्यवेक्षक अंतिम उत्तर कसे तयार करतो: LAST, SUMMARY, किंवा SCORED. +**प्रतिक्रिया धोरण** - सुपरवायझर अंतिम उत्तर कसे तयार करतो: LAST, SUMMARY, किंवा SCORED. -**क्रमवार कार्यप्रवाह** - एजंट्स क्रमाने चालवणे ज्यात आउटपुट पुढील टप्प्यावर प्रवाहित होते. +**अनुक्रमे वर्कफ्लो** - एजंट्स क्रमाने चालवा ज्यात आउटपुट पुढच्या स्टेपसाठी जाते. -**सुपरवायझर एजंट नमुना** - प्रगत एजंटिक नमुना ज्यात सुपरवायझर LLM गतिशीलपणे कोणते उपएजंट कॉल करायचे हे ठरवते. +**सुपरवायझर एजंट पॅटर्न** - प्रगत एजंटिक नमुना जेथे सुपरवायझर LLM गतिशीलपणे कोणते उप-एजंट्स कॉल करायचे ठरवतो. -## मॉडेल संदर्भ प्रोटोकॉल (MCP) - [मॉड्यूल 05](../05-mcp/README.md) +## मॉडेल कॉन्टेक्स्ट प्रोटोकॉल (MCP) - [मॉड्यूल 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j मध्ये MCP एकत्रिकरणासाठी Maven अवलंबित्व. +**langchain4j-mcp** - LangChain4j मध्ये MCP एकत्रीकरणासाठी मावेन डिपेंडेंसी. -**MCP** - मॉडेल संदर्भ प्रोटोकॉल: AI अ‍ॅप्सना बाह्य साधनांशी जोडण्यासाठी मानक. एकदाच बांधा, सर्वत्र वापर करा. +**MCP** - मॉडेल कॉन्टेक्स्ट प्रोटोकॉल: AI ऍप्सना बाह्य टूल्सशी जोडण्यासाठी मानक. एकदा बनवा, सगळीकडे वापरा. -**MCP क्लायंट** - MCP सर्व्हरशी कनेक्ट होऊन साधने शोधून वापरणारे अ‍ॅप. +**MCP क्लायंट** - MCP सर्वरशी जोडणारा ऍप्लिकेशन जो टूल्स शोधतो व वापरतो. -**MCP सर्व्हर** - साधने स्पष्ट वर्णने आणि पॅरामीटर स्कीमांसह MCP द्वारे एक्सपोज करणारी सेवा. +**MCP सर्व्हर** - MCP द्वारे टूल्स स्पष्ट वर्णन आणि पॅरामीटर स्कीमासह उपलब्ध करून देणारी सेवा. -**McpToolProvider** - LangChain4j घटक जे MCP साधने AI सेवा आणि एजंटसाठी तयार करते. +**McpToolProvider** - LangChain4j घटक जो MCP टूल्सना AI सेवा व एजंट्समध्ये वापरण्यासाठी वापरतो. -**McpTransport** - MCP कम्युनिकेशनसाठी इंटरफेस. अंमलबजावणीत Stdio आणि HTTP समाविष्ट. +**McpTransport** - MCP संवादासाठी इंटरफेस. अंमलबजावणीमध्ये Stdio आणि HTTP समाविष्ट. -**Stdio ट्रान्सपोर्ट** - लोकल प्रक्रिया stdin/stdout द्वारे ट्रान्सपोर्ट. फाइलसिस्टम किंवा कमांड-लाइन टूल्ससाठी उपयुक्त. +**Stdio ट्रान्सपोर्ट** - stdin/stdout द्वारे लोकल प्रोसस ट्रान्सपोर्ट. फाइलसिस्टम प्रवेश किंवा कमांड-लाइन टूलसाठी उपयुक्त. -**StdioMcpTransport** - LangChain4j अंमलबजावणी जी MCP सर्व्हर उपप्रक्रिया म्हणून सुरू करते. +**StdioMcpTransport** - LangChain4j अंमलबजावणी जी MCP सर्व्हर उपप्रक्रिया म्हणून चालवते. -**साधन शोध** - क्लायंट साधने सर्व्हरकडे वर्णने आणि स्कीमांसह विचारतो. +**टूल शोध** - क्लायंट उपलब्ध टूल्ससाठी वर्णन आणि स्कीमांसह सर्व्हरला क्वेरी करतो. ## Azure सेवा - [मॉड्यूल 01](../01-introduction/README.md) **Azure AI Search** - व्हेक्टर क्षमतांसह क्लाउड शोध. [मॉड्यूल 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Azure संसाधने तैनात करते. +**Azure Developer CLI (azd)** - Azure संसाधने डिप्लॉय करते. -**Azure OpenAI** - मायक्रोसॉफ्टची एंटरप्राइझ AI सेवा. +**Azure OpenAI** - Microsoft ची उद्यम AI सेवा. -**Bicep** - Azure इन्फ्रास्ट्रक्चर-एज-कोड भाषा. [इन्फ्रास्ट्रक्चर मार्गदर्शक](../01-introduction/infra/README.md) +**Bicep** - Azure इन्फ्रास्ट्रक्चर-ऐज-कोड भाषा. [इन्फ्रास्ट्रक्चर मार्गदर्शक](../01-introduction/infra/README.md) **डिप्लॉयमेंट नाव** - Azure मध्ये मॉडेल डिप्लॉयमेंटसाठी नाव. -**GPT-5.2** - विचार नियंत्रणासह नवीनतम OpenAI मॉडेल. [मॉड्यूल 02](../02-prompt-engineering/README.md) +**GPT-5.2** - ताजे OpenAI मॉडेल ज्यात विचार नियंत्रण आहे. [मॉड्यूल 02](../02-prompt-engineering/README.md) ## चाचणी आणि विकास - [चाचणी मार्गदर्शक](TESTING.md) -**Dev कंटेनर** - कंटेनरयुक्त विकास वातावरण. [रचना](../../../.devcontainer/devcontainer.json) +**Dev कंटेनर** - कंटेनरयुक्त विकास वातावरण. [कॉन्फिगरेशन](../../../.devcontainer/devcontainer.json) -**GitHub मॉडेल्स** - मोफत AI मॉडेल प्लेग्राउंड. [मॉड्यूल 00](../00-quick-start/README.md) +**इन-मेमरी चाचणी** - स्मृतीतील संचयने वापरून तपासणी. -**इन-मेमरी चाचणी** - इन-मेमरी स्टोरेजसह चाचणी. +**इंटिग्रेशन चाचणी** - प्रत्यक्ष इन्फ्रास्ट्रक्चरसह तपासणी. -**इंटीग्रेशन चाचणी** - वास्तविक इन्फ्रास्ट्रक्चरसह चाचणी. - -**Maven** - Java बिल्ड ऑटोमेशन साधन. +**मावेन** - Java बिल्ड ऑटोमेशन साधन. **Mockito** - Java मॉकिंग फ्रेमवर्क. -**Spring Boot** - Java अ‍ॅप्लिकेशन फ्रेमवर्क. [मॉड्यूल 01](../01-introduction/README.md) +**Spring Boot** - Java ऍप्लिकेशन फ्रेमवर्क. [मॉड्यूल 01](../01-introduction/README.md) --- -**अस्वीकरण**: -हा दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) चा वापर करून भाषांतरित केला आहे. आम्ही अचूकतेसाठी प्रयत्नशील आहोत, तरी कृपया लक्षात ठेवा की स्वयंचलित भाषांतरांमध्ये चुका किंवा अचूकतेच्या त्रुटी असू शकतात. मूळ दस्तऐवज त्याच्या मूळ भाषेत अधिकृत स्रोत मानला जावा. महत्त्वाची माहिती असल्यास व्यावसायिक मानवी भाषांतर घेणे शिफारसीय आहे. या भाषांतराच्या वापराने झालेल्या कोणत्याही गैरसमजुतीs किंवा चुकीच्या अर्थसंग्रहांसाठी आम्ही जबाबदार नाही. +**अस्वीकरण**: +हा दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) चा वापर करून अनुवादित केला आहे. जरी आम्ही अचूकतेसाठी प्रयत्न करतो, तरी कृपया लक्षात घ्या की स्वयंचलित भाषांतरांमध्ये त्रुटी किंवा अचूकतेची कमतरता असू शकते. मूळ दस्तऐवज त्याच्या मूळ भाषेत अधिकृत स्रोत मानला पाहिजे. महत्त्वाची माहिती असल्यास, व्यावसायिक मानवी भाषांतराची शिफारस केली जाते. या भाषांतराच्या वापरामुळे उद्भवणाऱ्या कोणत्याही गैरसमज किंवा चुकीच्या अर्थलावणीसाठी आम्ही जबाबदार नाही. \ No newline at end of file diff --git a/translations/mr/docs/TESTING.md b/translations/mr/docs/TESTING.md index dfc67462b..1f3b4ea1d 100644 --- a/translations/mr/docs/TESTING.md +++ b/translations/mr/docs/TESTING.md @@ -1,20 +1,20 @@ -# LangChain4j अनुप्रयोगांची चाचणी +# LangChain4j अनुप्रयोगांची चाचणी करणे -## अनुक्रमणिका +## विषयोपक्रम सारांश -- [जलद प्रारंभ](../../../docs) -- [चाचणी काय झाकतात](../../../docs) -- [चाचण्या चालविणे](../../../docs) -- [VS कोडमध्ये चाचण्या चालविणे](../../../docs) -- [चाचणी नमुने](../../../docs) -- [चाचणी तत्त्वज्ञान](../../../docs) -- [पुढील पाउले](../../../docs) +- [लवकर सुरूवात](#लवकर-सुरूवात) +- [चाचण्यांमध्ये काय समाविष्ट आहे](#चाचण्यांमध्ये-काय-समाविष्ट-आहे) +- [चाचण्या कश्या चालवाव्यात](#चाचण्या-कश्या-चालवाव्यात) +- [VS कोड मध्ये चाचण्या चालवणे](#vs-कोड-मध्ये-चाचण्या-चालवणे) +- [चाचणीचे नमुने](#चाचणीचे-नमुने) +- [चाचणी तत्वज्ञान](#चाचणी-तत्वज्ञान) +- [पुढील पावले](#पुढील-पावले) -हा मार्गदर्शक आपल्याला API की किंवा बाह्य सेवा न वापरता AI अनुप्रयोग कसे चाचणी करायच्या याचे उदाहरण देणाऱ्या चाचण्या कशा चालवायच्या हे सांगतो. +हा मार्गदर्शक तुम्हाला अशा चाचण्या कशा करायच्या ते दाखवतो ज्या एपीआय कीज किंवा बाह्य सेवा न वापरता AI अनुप्रयोगांची तपासणी करतात. -## जलद प्रारंभ +## लवकर सुरूवात -सर्व चाचण्या एकाच आज्ञेत चालवा: +सर्व चाचण्या एकाच आदेशाने चालवा: **Bash:** ```bash @@ -26,30 +26,29 @@ mvn test mvn --% test ``` -सर्व चाचण्या यशस्वी झाल्यावर तुमच्याकडे खालीलप्रमाणे स्क्रीनशॉटसारखे आउटपुट दिसेल — चाचण्या शून्य चुका न करता चालतात. +जेव्हा सर्व चाचण्या यशस्वी पार पडतात, तेव्हा तुम्हाला खालील स्क्रीनशॉट प्रमाणे आउटपुट दिसेल — एकाही अपयशाशिवाय चाचण्या चालवल्या जातात. -यशस्वी चाचणी परिणाम +Successful Test Results -*सर्व चाचण्या यशस्वी झाल्याचे दर्शविणारे चाचणी निष्पादन* +*सर्व चाचण्या यशस्वी पार पडल्या असल्याचे दर्शविणारे यशस्वी चाचणी कार्यान्वयन* -## चाचणी काय झाकतात +## चाचण्यांमध्ये काय समाविष्ट आहे -हा अभ्यासक्रम मुख्यतः **युनिट चाचण्यांवर** लक्ष केंद्रित करतो जे स्थानिकरित्या चालतात. प्रत्येक चाचणी स्वतंत्रपणे LangChain4j संकल्पना दाखवते. खालील चाचणी पिरॅमिड दर्शवतो की युनिट चाचण्या कुठे बसतात — त्या वेगवान आणि विश्वासार्ह पाया तयार करतात ज्यावर तुमच्या इतर चाचणी धोरणाची पायाभरणी असते. +हा अभ्यासक्रम स्थानिक पद्धतीने चालणाऱ्या **युनिट टेस्ट्स** वर केंद्रित आहे. प्रत्येक चाचणी वेगळ्या LangChain4j संकल्पनेची स्वतंत्रपणे माहिती देते. खालील चाचणी पिरामिडमध्ये युनिट टेस्ट्सचा समावेश दर्शवलेला आहे — त्या वेगवान, विश्वासार्ह पाया तयार करतात ज्यावर तुमचा संपूर्ण चाचणी धोरण आधारित आहे. -चाचणी पिरॅमिड +Testing Pyramid -*युनिट चाचणी (वेगवान, स्वतंत्र), इंटीग्रेशन चाचणी (खऱ्या घटकांसह), आणि एंड-टू-एंड चाचणी यांच्यातील संतुलन दर्शवते. हा प्रशिक्षण युनिट चाचणीवर आधारित आहे.* +*युनिट चाचण्या (वेगवान, स्वतंत्र), एकत्रीकरण चाचण्या (खरे घटक), आणि एंड-टू-एंड चाचण्यांमधील संतुलन दाखवणारा चाचणी पिरामिड. हा प्रशिक्षण कोर्स युनिट टेस्टिंगवर केंद्रित आहे.* -| मॉड्यूल | चाचण्या | लक्ष केंद्रित | मुख्य फायली | -|--------|---------|-------------|-------------| -| **00 - जलद प्रारंभ** | 6 | प्रॉम्प्ट साचे आणि व्हेरीएबल सबस्टिट्यूशन | `SimpleQuickStartTest.java` | -| **01 - परिचय** | 8 | संभाषण स्मृती आणि Stateful चॅट | `SimpleConversationTest.java` | -| **02 - प्रॉम्प्ट अभियांत्रिकी** | 12 | GPT-5.2 नमुने, उत्कटता स्तर, संरचित आउटपुट | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | दस्तऐवज आंतरभूत करणे, एम्बेडिंग्ज, सादृश्य शोध | `DocumentServiceTest.java` | -| **04 - साधने** | 12 | फंक्शन कॉलिंग आणि टूल चेनिंग | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | मॉडेल संदर्भ प्रोटोकॉल Stdio ट्रान्सपोर्टसह | `SimpleMcpTest.java` | +| मॉड्यूल | चाचण्या | लक्ष केंद्रित | प्रमुख फायली | +|--------|-------|-------|-----------| +| **01 - प्रस्तावना** | 8 | संभाषण स्मृती आणि स्थितीवार चॅट | `SimpleConversationTest.java` | +| **02 - प्रॉम्प्ट अभियांत्रिकी** | 12 | GPT-5.2 नमुने, उत्कटता स्तर, रचनेत आउटपुट | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | दस्तऐवज अंतर्भवन, एम्बेडिंग्ज, सादृश्यता शोध | `DocumentServiceTest.java` | +| **04 - साधने** | 12 | फंक्शन कॉलिंग आणि साधने साखळी | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Stdio ट्रान्सपोर्टसहित मॉडेल संदर्भ प्रोटोकॉल | `SimpleMcpTest.java` | -## चाचण्या चालविणे +## चाचण्या कश्या चालवाव्यात **रूटमधून सर्व चाचण्या चालवा:** @@ -75,11 +74,11 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# किंवा मूळ पासून +# किंवा मूळपासून mvn --% test -pl 01-introduction ``` -**एकल चाचणी वर्ग चालवा:** +**एकच चाचणी वर्ग चालवा:** **Bash:** ```bash @@ -95,41 +94,41 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#संभाषण इतिहास राखावा +mvn test -Dtest=SimpleConversationTest#संभाषणाचा इतिहास राखावा ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#संभाषण इतिहास राखला पाहिजे +mvn --% test -Dtest=SimpleConversationTest#संभाषणाचा इतिहास ठेवावा का ``` -## VS कोडमध्ये चाचण्या चालविणे +## VS कोड मध्ये चाचण्या चालवणे -जर तुम्ही Visual Studio Code वापरत असाल, तर Test Explorer चाचण्या चालविण्यासाठी आणि डिबग करण्यासाठी ग्राफिकल इंटरफेस उपलब्ध करतो. +जर तुम्ही Visual Studio Code वापरत असाल, तर Test Explorer चाचण्या चालवण्यासाठी आणि डीबग करण्यासाठी ग्राफिकल इंटरफेस पुरवतो. -VS कोड टेस्ट एक्सप्लोरर +VS Code Test Explorer -*VS कोड टेस्ट एक्सप्लोरर सर्व Java चाचणी वर्ग आणि स्वतंत्र चाचणी पद्धतींसह चाचणी वृक्ष दाखवत आहे* +*VS Code Test Explorer मध्ये सर्व Java चाचणी वर्ग आणि वैयक्तिक चाचणी पद्धतींचे टेस्ट ट्री दाखवित आहे* -**VS कोडमध्ये चाचण्या चालवण्यासाठी:** +**VS कोड मध्ये चाचण्या चालवण्यासाठी:** 1. Activity Bar मध्ये बीकर चिन्हावर क्लिक करून Test Explorer उघडा -2. सर्व मॉड्यूल आणि चाचणी वर्ग पाहण्यासाठी चाचणी वृक्ष विस्तृत करा -3. कोणतीही चाचणी एकट्यासाठी चालविण्यासाठी प्ले बटण क्लिक करा -4. संपूर्ण संच चालवण्यासाठी "Run All Tests" क्लिक करा -5. कोणतीही चाचणी वर उजवे क्लिक करून "Debug Test" निवडा, ब्रेकपॉइंट सेट करा आणि कोड स्टेप करा +2. सर्व मॉड्यूल्स आणि चाचणी वर्ग पाहण्यासाठी टेस्ट ट्री विस्तृत करा +3. एखादी चाचणी स्वतंत्रपणे चालवण्यासाठी तिच्या जवळील प्ले बटणावर क्लिक करा +4. संपूर्ण सूट चालवण्यासाठी "Run All Tests" क्लिक करा +5. कुठल्याही चाचणीवर उजवी क्लिक करून "Debug Test" निवडा, ब्रेकपॉइंट सेट करा आणि कोड शोधा -Test Explorer चाचणी पास झाल्यास हिरव्या चेकमार्क्स दाखवतो आणि चाचणी अयशस्वी झाल्यास तपशीलवार त्रुटी संदेश प्रदान करतो. +Test Explorer यशस्वी झालेल्या चाचण्यांसाठी हिरव्या तपास चिन्हे दाखवतो आणि अपयशी झाल्यास तपशीलवार त्रुटी संदेश देतो. -## चाचणी नमुने +## चाचणीचे नमुने ### नमुना 1: प्रॉम्प्ट टेम्पलेट्सची चाचणी -सर्वात सोपा नमुना AI मॉडेल कॉल न करता प्रॉम्प्ट टेम्पलेट्सची चाचणी करतो. यात व्हेरीएबल सबस्टिट्यूशन योग्यप्रकारे होते आणि प्रॉम्प्ट अपेक्षित स्वरूपात तयार होतात हे तपासले जाते. +सर्वात सोपा नमुना कोणतेही AI मॉडेल कॉल न करता प्रॉम्प्ट टेम्पलेट्सची चाचणी करतो. तुम्ही तपासता की चल प्रविष्ट्या योग्यरित्या बदलत आहेत आणि प्रॉम्प्ट अपेक्षेनुसार फॉरमॅट केले आहेत. -प्रॉम्प्ट टेम्पलेट चाचणी +Prompt Template Testing -*व्हेरीएबल सबस्टिट्यूशन प्रवाह दाखविणारे प्रॉम्प्ट टेम्पलेट चाचणी: प्लेसहोल्डर्ससह टेम्पलेट → मूल्ये लागू केली → स्वरूपित आउटपुट पडताळले* +*चल प्रविष्ट्यांचे बदल होणे दर्शविणारे प्रॉम्प्ट टेम्पलेट टेस्टिंग: प्लेसहोल्डर्स असलेले टेम्पलेट→आवक मूल्यमापन→फॉरमॅटेड आउटपुट पडताळणी* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -ही चाचणी `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` मध्ये आहे. +हा नमुना तपासतो की चल प्रविष्ट्या योग्य प्रकारे बदलल्या गेल्या आहेत आणि प्रॉम्प्ट अपेक्षेनुसार फॉरमॅट केले आहेत — कोणतीही API की किंवा मॉडेल कॉल आवश्यक नाही. -**चालवा:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#चाचणीप्रॉम्प्टसाचा टेम्पलेट स्वरूपांकन -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#चाचणीप्रॉम्प्टटेम्पलेटफॉरमॅटिंग -``` - -### नमुना 2: भाषा मॉडेल्सचे मॉकिंग +### नमुना 2: भाषा मॉडेल्सची मॉकिंग -संभाषण लॉजिकची चाचणी करताना Mockito वापरून ठरवलेले प्रतिसाद देणारी खोटी मॉडेल तयार करा. यामुळे चाचण्या वेगवान, विनामूल्य आणि निश्चित होतात. +संभाषण तार्किकतेची चाचणी करताना, Mockito वापरून नकली मॉडेल तयार करा जे आधीच सांगितलेली उत्तरे परत करतात. यामुळे चाचण्या जलद, मोफत आणि ठराविक होतात. -मॉक विरुद्ध वास्तविक API तुलना +Mock vs Real API Comparison -*चाचणीसाठी मॉक का प्राधान्य दिले जाते हे दाखवते: ते वेगवान, विनामूल्य, निश्चित आणि API कीची गरज नसलेले असतात* +*मॉक वापरण्याचे फायदे दाखवणारी तुलना: ते वेगवान, मोफत, ठराविक, आणि API कीशिवाय असतात* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 वापरकर्ता + 3 AI संदेश + assertThat(history).hasSize(6); // 3 वापरकर्ता + 3 एआय संदेशे } } ``` -हा नमुना `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` मध्ये आढळतो. मॉक सुनिश्चित करतो की वागणूक सुसंगत राहील ज्यामुळे स्मृती व्यवस्थापन योग्य कार्य करतो हे तपासता येते. +हा नमुना `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` मध्ये आहे. मॉक स्थिर वर्तन सुनिश्चित करतो जेणेकरून तुम्ही स्मृती व्यवस्थापन योग्य आहे का ते तपासू शकता. -### नमुना 3: संभाषण वेगळेपणा चाचणी +### नमुना 3: संभाषण पृथक्करणाची चाचणी -संभाषण स्मृतीने अनेक वापरकर्ते स्वतंत्र ठेवले पाहिजेत. ही चाचणी तपासते की संभाषणे एकमेकाचा संदर्भ मिसळत नाहीत. +संभाषण स्मृतीने अनेक वापरकर्त्यांना वेगळे ठेवणे आवश्यक आहे. ही चाचणी पुष्टी करते की संभाषणे संदर्भ मिसळत नाहीत. -संभाषण वेगळेपणा +Conversation Isolation -*वेगळ्या वापरकर्त्यांसाठी स्वतंत्र स्मृती संच दर्शविणारे संभाषण वेगळेपणा चाचणी स्पष्टीकरण* +*संभाषण पृथक्करण दाखविते वेगळे स्मृती संच वेगळ्या वापरकर्त्यांसाठी संदर्भ मिसळू नयेत म्हणून* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -प्रत्येक संभाषणाची स्वतंत्र इतिहास ठेवली जातो. उत्पादन प्रणालींमध्ये हा वेगळेपणा बहु-वापरकर्ता अनुप्रयोगांसाठी अत्यंत महत्वाचा असतो. +प्रत्येक संभाषणाची स्वतःची स्वतंत्र इतिहास राखली जाते. उत्पादन प्रणालींमध्ये, हे पृथक्करण बहु-वापरकर्ता अनुप्रयोगांसाठी अत्यंत महत्त्वाचे आहे. -### नमुना 4: साधने स्वतंत्र चाचणी +### नमुना 4: साधने स्वतंत्रपणे चाचणी करणे -साधने AI कॉल करू शकणाऱ्या फंक्शन्स आहेत. ते थेट चाचणी करून खात्री करा की ते AI निर्णयांपासून स्वतंत्रपणे नीट कार्य करतात. +साधने म्हणजे AI कॉल करू शकणारे फंक्शन्स. त्यांना थेट चाचणी द्या जेणेकरून ते AI निर्णयांपासून स्वतंत्रपणे योग्य काम करतात. -साधने चाचणी +Tools Testing -*AI कॉलशिवाय मॉक साधन कार्यान्वयन दर्शविणारे स्वतंत्र साधन चाचणी, व्यावसायिक लॉजिक तपासते* +*AI कॉल न करता मॉक साधनांचे प्रदर्शन करून व्यावसायिक लॉजिक तपासणारी साधने स्वतंत्रपणे चाचणी* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -ही चाचणी `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` मधून साधन लॉजिक AI शिवाय तपासते. चेनिंग उदाहरण दाखवते की एका साधनाचा आउटपुट दुसर्‍या साधनाच्या इनपुटमध्ये कसा जाईल. +हे चाचणी `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` मधून आहेत. साखळीकरणाचा नमुना दाखवितो की एका साधनाचे उत्पादन दुसऱ्या साधनाच्या इनपुटमध्ये कसे जाते. -### नमुना 5: इन-मेमरी RAG चाचणी +### नमुना 5: इन-मेमोरी RAG चाचणी -RAG प्रणाली पारंपरिकरीत्या व्हेक्टर डेटाबेस आणि एम्बेडिंग सेवा आवश्यक असतात. इन-मेमरी नमुना पूर्ण पाईपलाइन बाह्य अवलंबित्वांशिवाय टेस्ट करण्यास अनुमती देतो. +RAG प्रणाली सामान्यतः व्हेक्टर डेटाबेस आणि एम्बेडिंग सेवा आवश्यक असतात. इन-मेमोरी नमुना संपूर्ण पाइपलाइन बाह्य अवलंबित्वांशिवाय तपासण्यास परवानगी देतो. -इन-मेमरी RAG चाचणी +In-Memory RAG Testing -*डॉक्युमेंट पार्सिंग, एम्बेडिंग स्टोरेज, आणि सादृश्य शोध दाखवणारा इन-मेमरी RAG चाचणी कार्यप्रवाह* +*इन-मेमोरी RAG टेस्टिंग कार्यप्रवाह दाखविते दस्तऐवज पार्सिंग, एम्बेडिंग संचयन, आणि सादृश्यता शोध डेटाबेसशिवाय* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -ही चाचणी `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` मध्ये आहे. डॉक्युमेंट इन-मेमरी तयार करते आणि चंकिंग व मेटाडेटा हँडलिंग पडताळते. +`03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` मधून ही चाचणी दस्तऐवज मेमरीमध्ये तयार करून चंकिंग आणि मेटाडेटा हाताळणी तपासते. -### नमुना 6: MCP इंटीग्रेशन चाचणी +### नमुना 6: MCP एकत्रीकरण चाचणी -MCP मॉड्यूल Model Context Protocol इंटीग्रेशन stdio ट्रान्सपोर्ट वापरते. ही चाचणी तपासते की तुमचा अनुप्रयोग MCP सर्व्हर सबप्रोसेस म्हणून उभारू आणि संवाद साधू शकतो. +MCP मॉड्यूल मॉडेल संदर्भ प्रोटोकॉलचे stdio ट्रान्सपोर्ट वापर करून एकत्रीकरण तपासते. ही चाचणी तुमचा अनुप्रयोग MCP सर्वर्स म्हणून उपप्रक्रिया सुरू करू शकतो आणि संवाद साधू शकतो हे खात्री करते. -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` मधील चाचण्या MCP क्लायंटचे वर्तन पडताळतात. +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` मधील चाचण्या MCP क्लायंट वर्तनाची पडताळणी करतात. **चालवा:** @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## चाचणी तत्त्वज्ञान +## चाचणी तत्वज्ञान -तुमचा कोड चाचणी करा, AI नाही. तुमच्या चाचण्यांनी तुम्ही लिहिलेला कोड पडताळला पाहिजे, जसे प्रॉम्प्ट कसे तयार होतात, स्मृती कशी व्यवस्थापित होते, आणि साधने कशी कार्यान्वित होतात. AI प्रतिसाद वेगवेगळे असतात आणि चाचणी दावे भाग नसावे. स्वतःला विचारा, तुमचा प्रॉम्प्ट टेम्पलेट व्हेरीएबल योग्य पद्धतीने बदलतो का, AI बरोबर उत्तर देते की नाही नाही. +तुमचा कोड तपासा, AI नाही. तुमच्या चाचण्यांनी तुम्ही लिहिलेले कोड कसे तयार होते, स्मृती कशी व्यवस्थापित होते, आणि साधने कशी कार्यान्वित होतात हेच पडताळले पाहिजे. AI उत्तरे बदलतात आणि ती चाचणी पुरावे भाग नसावेत. विचार करा की तुमचा प्रॉम्प्ट टेम्पलेट योग्यरित्या चल प्रविष्ट्या बदलतो का, AI बरोबर उत्तर देते का हे नाही. -भाषा मॉडेलसाठी मॉक वापरा. ते बाह्य अवलंबित्वे आहेत जे धीमे, महागडे, आणि निश्चित नाहीत. मॉकिंग मुळे चाचण्या मिलीसेकंदांत वेगवान, विनामूल्य आणि कायमस्वरूपी परिणामांसह होतात. +भाषा मॉडेलसाठी मॉक वापरा. हे बाह्य अवलंबित्व आहेत जे मंद, महाग आणि ठराविक नसतात. मॉकिंगमुळे चाचण्या सेकंदांऐवजी मिलीसेकंदांत जलद, मोफत आणि ठराविक बनतात. -चाचण्या स्वतंत्र ठेवा. प्रत्येक चाचणीने स्वतःची डेटा तयार करावी, इतर चाचण्यांवर अवलंबून राहू नये, आणि नंतर स्वच्छ करावे. चाचण्या कोणत्याही क्रमाने चालल्या तरी यशस्वी होतात. +चाचण्या स्वतंत्र ठेवा. प्रत्येक चाचणीने स्वतःचे डेटा सेट करावे, इतर चाचण्यांवर अवलंबून राहू नये, आणि स्वच्छता करावी. चाचण्या चालण्याच्या क्रमावरील निर्भर नसाव्यात. -आनंददायक मार्गाव्यतिरिक्त सीमांत परिस्थिती चाचणी करा. रिक्त इनपुट, अतिशय मोठे इनपुट, विशेष चिन्हे, अवैध पॅरामीटर्स आणि बाउंडरी कंडिशन्स तपासा. या अनेकदा अशा बग उघड करतात जे सामान्य वापर करताना दिसत नाहीत. +आनंदी मार्गापलीकडे सीमेच्या प्रकरणांची चाचणी करा. रिकामे इनपुट, फार मोठे इनपुट, विशेष वर्ण, अवैध पॅरामीटर्स आणि सीमा परिस्थिती तपासा. अनेकदा या त्रुटी उघड करतात ज्या सामान्य वापर दर्शवत नाही. -वर्णनात्मक नावे वापरा. `shouldMaintainConversationHistoryAcrossMultipleMessages()` ची तुलना `test1()` शी करा. पहिल्या नावाने तुम्हाला नक्की काय चाचणी केली जात आहे हे स्पष्ट सांगते, ज्यामुळे अपयशाचे निराकरण खूप सोपे होते. +स्पष्ट नावे वापरा. `shouldMaintainConversationHistoryAcrossMultipleMessages()` हे `test1()` पेक्षा तुलनेत खूप अधिक सांगते. पहिले नक्की काय तपासत आहे हे सांगते ज्यामुळे अपयशाचे डीबगिंग सोपे होते. -## पुढील पाउले +## पुढील पावले -चाचणी नमुने समजल्यावर प्रत्येक मॉड्यूलमध्ये सखोल जाता: +आता जेव्हा तुम्हाला चाचणी नमुने समजले आहेत, तर प्रत्येक मॉड्यूलमध्ये अधिक खोलात जाऊन पहा: -- **[00 - जलद प्रारंभ](../00-quick-start/README.md)** - प्रॉम्प्ट टेम्पलेट मूलभूत गोष्टींसह प्रारंभ करा -- **[01 - परिचय](../01-introduction/README.md)** - संभाषण स्मृती व्यवस्थापन शिका -- **[02 - प्रॉम्प्ट अभियांत्रिकी](../02-prompt-engineering/README.md)** - GPT-5.2 प्रॉम्प्टिंग नमुने आत्मसात करा -- **[03 - RAG](../03-rag/README.md)** - पुनर्प्राप्ती-आधारित जनरेशन सिस्टिम तयार करा -- **[04 - साधने](../04-tools/README.md)** - फंक्शन कॉलिंग आणि टूल चेन लागू करा -- **[05 - MCP](../05-mcp/README.md)** - मॉडेल संदर्भ प्रोटोकॉल इंटीग्रेट करा +- **[01 - प्रस्तावना](../01-introduction/README.md)** - संभाषण स्मृती व्यवस्थापन शिका +- **[02 - प्रॉम्प्ट अभियांत्रिकी](../02-prompt-engineering/README.md)** - GPT-5.2 प्रॉम्प्टिंग नमुने पारंगत व्हा +- **[03 - RAG](../03-rag/README.md)** - पुनर्प्राप्ति-संगृहीत जनरेशन प्रणाली तयार करा +- **[04 - साधने](../04-tools/README.md)** - फंक्शन कॉलिंग आणि साधने साखळी लागू करा +- **[05 - MCP](../05-mcp/README.md)** - मॉडेल संदर्भ प्रोटोकॉल एकत्रित करा -प्रत्येक मॉड्यूलचे README येथे चाचणी केलेल्या संकल्पनांचे तपशीलवार स्पष्टीकरण देते. +प्रत्येक मॉड्यूलची README येथे तपासलेल्या संकल्पनांचे सविस्तर स्पष्टीकरण देते. --- -**नेव्हिगेशन:** [← मुख्यांकडे परत](../README.md) +**नेव्हिगेशन:** [← मुख्याकडे परत जा](../README.md) --- -**अस्वीकरण**: -हा दस्तऐवज AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) वापरून भाषांतरित केला आहे. आम्ही अचूकतेसाठी प्रयत्नशील आहोत, तरी कृपया लक्षात ठेवा की स्वयंचलित अनुवादांमध्ये चूक किंवा अचूकतेची कमतरता असू शकते. मूळ दस्तऐवज त्याच्या स्थानिक भाषेत अधिकारप्राप्त स्रोत मानला जावा. महत्त्वपूर्ण माहितींसाठी व्यावसायिक मानवी अनुवादाची शिफारस केली जाते. या अनुवादाच्या वापरामुळे उद्भवणाऱ्या कोणत्याही गैरसमजुती किंवा चुकीच्या समजुतीबद्दल आम्ही जबाबदार नाही. +**अस्वीकरण**: +हा दस्तऐवज AI भाषांतर सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) चा वापर करून अनुवादित केला आहे. जरी आम्ही अचूकतेसाठी प्रयत्न करतो, तरी कृपया लक्षात घ्या की स्वयंचलित भाषांतरांमध्ये त्रुटी किंवा अचूकतेची कमतरता असू शकते. मूळ दस्तऐवज त्याच्या मूळ भाषेत अधिकृत स्रोत मानला पाहिजे. महत्त्वाची माहिती असल्यास, व्यावसायिक मानवी भाषांतराची शिफारस केली जाते. या भाषांतराच्या वापरामुळे उद्भवणाऱ्या कोणत्याही गैरसमज किंवा चुकीच्या अर्थलावणीसाठी आम्ही जबाबदार नाही. \ No newline at end of file diff --git a/translations/ms/.co-op-translator.json b/translations/ms/.co-op-translator.json index 1ed1b2702..5f0b69327 100644 --- a/translations/ms/.co-op-translator.json +++ b/translations/ms/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ms" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T20:33:50+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T10:16:56+00:00", "source_file": "01-introduction/README.md", "language_code": "ms" }, @@ -18,20 +18,20 @@ "language_code": "ms" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T20:36:07+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T10:12:30+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ms" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T20:37:41+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T10:16:06+00:00", "source_file": "03-rag/README.md", "language_code": "ms" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T12:37:55+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T10:14:55+00:00", "source_file": "04-tools/README.md", "language_code": "ms" }, @@ -54,8 +54,8 @@ "language_code": "ms" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:12:36+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T10:10:55+00:00", "source_file": "README.md", "language_code": "ms" }, @@ -72,14 +72,14 @@ "language_code": "ms" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T20:40:39+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T10:13:04+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ms" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T20:41:24+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T10:13:45+00:00", "source_file": "docs/TESTING.md", "language_code": "ms" } diff --git a/translations/ms/00-quick-start/README.md b/translations/ms/00-quick-start/README.md deleted file mode 100644 index d6c2653f8..000000000 --- a/translations/ms/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Mula Cepat - -## Table of Contents - -- [Pengenalan](../../../00-quick-start) -- [Apakah LangChain4j?](../../../00-quick-start) -- [Kebergantungan LangChain4j](../../../00-quick-start) -- [Prasyarat](../../../00-quick-start) -- [Persediaan](../../../00-quick-start) - - [1. Dapatkan Token GitHub Anda](../../../00-quick-start) - - [2. Tetapkan Token Anda](../../../00-quick-start) -- [Jalankan Contoh](../../../00-quick-start) - - [1. Sembang Asas](../../../00-quick-start) - - [2. Corak Prompt](../../../00-quick-start) - - [3. Panggilan Fungsi](../../../00-quick-start) - - [4. Soal Jawab Dokumen (Easy RAG)](../../../00-quick-start) - - [5. AI Bertanggungjawab](../../../00-quick-start) -- [Apa yang Ditunjukkan oleh Setiap Contoh](../../../00-quick-start) -- [Langkah Seterusnya](../../../00-quick-start) -- [Penyelesaian Masalah](../../../00-quick-start) - -## Pengenalan - -Mula cepat ini bertujuan untuk membantu anda memulakan LangChain4j dengan cepat. Ia merangkumi asas membina aplikasi AI menggunakan LangChain4j dan Model GitHub. Dalam modul berikutnya, anda akan beralih ke Azure OpenAI dan GPT-5.2 serta mendalami setiap konsep. - -## Apakah LangChain4j? - -LangChain4j adalah perpustakaan Java yang memudahkan pembangunan aplikasi yang dikuasakan oleh AI. Daripada mengurus klien HTTP dan penguraian JSON, anda bekerja dengan API Java yang kemas. - -"Rantai" dalam LangChain merujuk kepada penggabungan beberapa komponen — anda mungkin mengaitkan satu prompt dengan model, dengan parser, atau mengaitkan beberapa panggilan AI di mana satu output menjadi input seterusnya. Mula cepat ini menumpukan kepada asas sebelum meneroka rantai yang lebih kompleks. - -Konsep Pengaitan LangChain4j - -*Mengaitkan komponen dalam LangChain4j - blok binaan menyambung untuk mencipta aliran kerja AI yang kuat* - -Kami akan menggunakan tiga komponen teras: - -**ChatModel** - Antara muka untuk interaksi model AI. Panggil `model.chat("prompt")` dan dapatkan rentetan respons. Kami menggunakan `OpenAiOfficialChatModel` yang berfungsi dengan titik akhir yang serasi OpenAI seperti Model GitHub. - -**AiServices** - Mewujudkan antara muka perkhidmatan AI yang selamat jenis. Takrifkan kaedah, hias dengan `@Tool`, dan LangChain4j mengaturkan orchestration. AI secara automatik memanggil kaedah Java anda apabila diperlukan. - -**MessageWindowChatMemory** - Mengekalkan sejarah perbualan. Tanpa ini, setiap permintaan berdiri sendiri. Dengan ini, AI mengingati mesej sebelumnya dan mengekalkan konteks merentasi beberapa pusingan. - -Seni Bina LangChain4j - -*Seni bina LangChain4j - komponen teras bekerjasama untuk menggerakkan aplikasi AI anda* - -## Kebergantungan LangChain4j - -Mula cepat ini menggunakan tiga kebergantungan Maven dalam [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modul `langchain4j-open-ai-official` menyediakan kelas `OpenAiOfficialChatModel` yang menyambung ke API yang serasi OpenAI. Model GitHub menggunakan format API yang sama, jadi tiada penyesuai khas diperlukan — cuma tetapkan URL asas kepada `https://models.github.ai/inference`. - -Modul `langchain4j-easy-rag` menyediakan pemecahan dokumen automatik, penyematan, dan pengambilan supaya anda boleh membina aplikasi RAG tanpa konfigurasi manual setiap langkah. - -## Prasyarat - -**Menggunakan Dev Container?** Java dan Maven sudah dipasang. Anda hanya memerlukan Token Akses Peribadi GitHub. - -**Pembangunan Tempatan:** -- Java 21+, Maven 3.9+ -- Token Akses Peribadi GitHub (arahan di bawah) - -> **Nota:** Modul ini menggunakan `gpt-4.1-nano` dari Model GitHub. Jangan ubah nama model dalam kod — ia dikonfigurasi untuk berfungsi dengan model yang tersedia di GitHub. - -## Persediaan - -### 1. Dapatkan Token GitHub Anda - -1. Pergi ke [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Klik "Generate new token" -3. Tetapkan nama yang deskriptif (contoh, "LangChain4j Demo") -4. Tetapkan tarikh luput (7 hari disyorkan) -5. Di bawah "Account permissions", cari "Models" dan tetapkan kepada "Read-only" -6. Klik "Generate token" -7. Salin dan simpan token anda — anda tidak akan melihatnya lagi - -### 2. Tetapkan Token Anda - -**Pilihan 1: Menggunakan VS Code (Disyorkan)** - -Jika anda menggunakan VS Code, tambahkan token anda ke fail `.env` di akar projek: - -Jika fail `.env` tidak wujud, salin `.env.example` ke `.env` atau cipta fail `.env` baru di akar projek. - -**Contoh fail `.env`:** -```bash -# Dalam /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Kemudian anda hanya perlu klik kanan pada mana-mana fail demo (contoh, `BasicChatDemo.java`) di Explorer dan pilih **"Run Java"** atau gunakan konfigurasi pelancaran dari panel Run and Debug. - -**Pilihan 2: Menggunakan Terminal** - -Tetapkan token sebagai pembolehubah persekitaran: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Jalankan Contoh - -**Menggunakan VS Code:** Klik kanan sahaja pada mana-mana fail demo di Explorer dan pilih **"Run Java"**, atau gunakan konfigurasi pelancaran dari panel Run and Debug (pastikan anda telah menambah token ke fail `.env` terlebih dahulu). - -**Menggunakan Maven:** Sebagai alternatif, anda boleh jalankan dari baris arahan: - -### 1. Sembang Asas - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Corak Prompt - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Menunjukkan zero-shot, few-shot, chain-of-thought, dan role-based prompting. - -### 3. Panggilan Fungsi - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI secara automatik memanggil kaedah Java anda apabila diperlukan. - -### 4. Soal Jawab Dokumen (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Tanya soalan tentang dokumen anda menggunakan Easy RAG dengan penyematan dan pengambilan automatik. - -### 5. AI Bertanggungjawab - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Lihat bagaimana penapis keselamatan AI menyekat kandungan berbahaya. - -## Apa yang Ditunjukkan oleh Setiap Contoh - -**Sembang Asas** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Mula di sini untuk melihat LangChain4j pada tahap paling asas. Anda akan mencipta `OpenAiOfficialChatModel`, hantar prompt dengan `.chat()`, dan dapatkan respons. Ini menunjukkan asas: cara menginisialisasi model dengan titik akhir dan kunci API tersuai. Setelah anda faham corak ini, segala yang lain dibina di atasnya. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) dan tanya: -> - "Bagaimana saya tukar dari Model GitHub ke Azure OpenAI dalam kod ini?" -> - "Apakah parameter lain yang boleh saya konfigurasi dalam OpenAiOfficialChatModel.builder()?" -> - "Bagaimana saya tambah respons penstriman dan bukannya tunggu respons lengkap?" - -**Kejuruteraan Prompt** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Sekarang anda tahu cara bercakap dengan model, mari teroka apa yang anda katakan kepadanya. Demo ini menggunakan tetapan model yang sama tetapi menunjukkan lima corak prompt yang berbeza. Cuba zero-shot untuk arahan terus, few-shot yang belajar dari contoh, chain-of-thought yang mendedahkan langkah rasional, dan role-based yang menetapkan konteks. Anda akan lihat bagaimana model yang sama memberikan hasil berbeza bergantung pada cara anda membingkai permintaan. - -Demo juga menunjukkan templat prompt, cara yang kuat untuk cipta prompt boleh guna semula dengan pembolehubah. -Contoh di bawah menunjukkan prompt menggunakan `PromptTemplate` LangChain4j untuk mengisi pembolehubah. AI akan menjawab berdasarkan destinasi dan aktiviti yang diberikan. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) dan tanya: -> - "Apakah perbezaan antara zero-shot dan few-shot prompting, dan bila saya harus guna masing-masing?" -> - "Bagaimana parameter suhu mempengaruhi respons model?" -> - "Apakah teknik untuk elakkan serangan suntikan prompt dalam pengeluaran?" -> - "Bagaimana saya cipta objek PromptTemplate boleh guna semula untuk corak biasa?" - -**Integrasi Alat** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Di sinilah LangChain4j menjadi hebat. Anda akan menggunakan `AiServices` untuk mewujudkan pembantu AI yang boleh memanggil kaedah Java anda. Cuma hias kaedah dengan `@Tool("penerangan")` dan LangChain4j mengurus selebihnya — AI secara automatik memutuskan bila guna setiap alat berdasarkan apa yang pengguna minta. Ini menunjukkan panggilan fungsi, teknik utama membina AI yang boleh bertindak, bukan sekadar menjawab soalan. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) dan tanya: -> - "Bagaimana anotasi @Tool berfungsi dan apa yang LangChain4j buat dengannya di belakang tabir?" -> - "Bolehkah AI memanggil pelbagai alat secara berurutan untuk selesaikan masalah kompleks?" -> - "Apa jadi jika alat membuang pengecualian — bagaimana saya hendak tangani ralat?" -> - "Bagaimana saya integrasi API sebenar bukan contoh kalkulator ini?" - -**Soal Jawab Dokumen (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Di sini anda akan lihat RAG (retrieval-augmented generation) menggunakan pendekatan "Easy RAG" LangChain4j. Dokumen dimuat, secara automatik dipecah dan disemat ke dalam stor memori, kemudian pengambil kandungan membekalkan pecahan berkaitan kepada AI semasa waktu soal. AI menjawab berdasarkan dokumen anda, bukan pengetahuan umum. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) dan tanya: -> - "Bagaimana RAG mengelakkan halusinasi AI berbanding menggunakan data latihan model?" -> - "Apakah perbezaan antara pendekatan mudah ini dan saluran RAG khusus?" -> - "Bagaimana saya skala ini untuk urus pelbagai dokumen atau pangkalan pengetahuan lebih besar?" - -**AI Bertanggungjawab** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Bina keselamatan AI dengan pertahanan berlapis. Demo ini tunjuk dua lapisan perlindungan bekerja bersama: - -**Bahagian 1: LangChain4j Input Guardrails** - Sekat prompt bahaya sebelum sampai ke LLM. Cipta guardrail tersuai yang periksa kata kunci atau corak dilarang. Ini dijalankan dalam kod anda, jadi pantas dan percuma. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Bahagian 2: Penapis Keselamatan Penyedia** - Model GitHub ada penapis terbina yang tangkap apa guardrail mungkin terlepas. Anda akan lihat sekatan keras (ralat HTTP 400) untuk pelanggaran teruk dan penolakan lembut di mana AI menolak dengan sopan. - -> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) dan tanya: -> - "Apakah InputGuardrail dan bagaimana saya cipta sendiri?" -> - "Apakah perbezaan antara sekatan keras dan penolakan lembut?" -> - "Kenapa gunakan kedua-dua guardrail dan penapis penyedia bersama?" - -## Langkah Seterusnya - -**Modul Seterusnya:** [01-pengenalan - Mula dengan LangChain4j](../01-introduction/README.md) - ---- - -**Navigasi:** [← Kembali ke Utama](../README.md) | [Seterusnya: Modul 01 - Pengenalan →](../01-introduction/README.md) - ---- - -## Penyelesaian Masalah - -### Kompilasi Maven Kali Pertama - -**Isu**: `mvn clean compile` atau `mvn package` pertama kali mengambil masa lama (10-15 minit) - -**Sebab**: Maven perlu muat turun semua kebergantungan projek (Spring Boot, perpustakaan LangChain4j, SDK Azure, dan lain-lain) pada binaan pertama. - -**Penyelesaian**: Ini adalah tingkah laku normal. Binaan seterusnya akan lebih pantas kerana kebergantungan sudah disimpan secara tempatan. Masa muat turun bergantung pada kelajuan rangkaian anda. - -### Syntax Arahan Maven PowerShell - -**Isu**: Arahan Maven gagal dengan ralat `Unknown lifecycle phase ".mainClass=..."` -**Punca**: PowerShell mentafsir `=` sebagai operator penetapan pembolehubah, yang memecahkan sintaks harta Maven - -**Penyelesaian**: Gunakan operator hentikan-penafsiran `--%` sebelum arahan Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operator `--%` memberitahu PowerShell untuk menyerahkan semua argumen yang tinggal secara literal kepada Maven tanpa tafsiran. - -### Paparan Emoji Windows PowerShell - -**Isu**: Respons AI memaparkan aksara sampah (contohnya, `????` atau `â??`) dan bukannya emoji dalam PowerShell - -**Punca**: Pengekodan lalai PowerShell tidak menyokong emoji UTF-8 - -**Penyelesaian**: Jalankan arahan ini sebelum melaksanakan aplikasi Java: -```cmd -chcp 65001 -``` - -Ini memaksa pengekodan UTF-8 dalam terminal. Sebagai alternatif, gunakan Windows Terminal yang mempunyai sokongan Unicode yang lebih baik. - -### Menyahpepijat Panggilan API - -**Isu**: Ralat pengesahan, had kadar, atau respons tidak dijangka daripada model AI - -**Penyelesaian**: Contoh ini termasuk `.logRequests(true)` dan `.logResponses(true)` untuk memaparkan panggilan API dalam konsol. Ini membantu menyelesaikan ralat pengesahan, had kadar, atau respons tidak dijangka. Buang bendera ini dalam pengeluaran untuk mengurangkan bunyi log. - ---- - - -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat yang kritikal, penterjemahan profesional oleh manusia adalah disyorkan. Kami tidak bertanggungjawab atas sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. - \ No newline at end of file diff --git a/translations/ms/01-introduction/README.md b/translations/ms/01-introduction/README.md index 057853840..8b52d9e59 100644 --- a/translations/ms/01-introduction/README.md +++ b/translations/ms/01-introduction/README.md @@ -1,85 +1,85 @@ -# Modul 01: Memulakan dengan LangChain4j +# Modul 01: Bermula dengan LangChain4j ## Jadual Kandungan -- [Video Panduan](../../../01-introduction) -- [Apa yang Anda Akan Pelajari](../../../01-introduction) -- [Prasyarat](../../../01-introduction) -- [Memahami Masalah Teras](../../../01-introduction) -- [Memahami Token](../../../01-introduction) -- [Bagaimana Memori Berfungsi](../../../01-introduction) -- [Bagaimana Ini Menggunakan LangChain4j](../../../01-introduction) -- [Menguruskan Infrastruktur Azure OpenAI](../../../01-introduction) -- [Jalankan Aplikasi Secara Tempatan](../../../01-introduction) -- [Menggunakan Aplikasi](../../../01-introduction) - - [Sembang Tanpa Keadaan (Panel Kiri)](../../../01-introduction) - - [Sembang Berkeadaan (Panel Kanan)](../../../01-introduction) -- [Langkah Seterusnya](../../../01-introduction) +- [Video Panduan](#video-panduan) +- [Apa Yang Akan Anda Pelajari](#apa-yang-akan-anda-pelajari) +- [Prasyarat](#prasyarat) +- [Memahami Masalah Teras](#memahami-masalah-teras) +- [Memahami Token](#memahami-token) +- [Bagaimana Memori Berfungsi](#bagaimana-memori-berfungsi) +- [Bagaimana Ini Menggunakan LangChain4j](#bagaimana-ini-menggunakan-langchain4j) +- [Menyebarkan Infrastruktur Azure OpenAI](#menyebarkan-infrastruktur-azure-openai) +- [Jalankan Aplikasi Secara Tempatan](#jalankan-aplikasi-secara-tempatan) +- [Menggunakan Aplikasi](#menggunakan-aplikasi) + - [Sembang Tanpa Keadaan (Panel Kiri)](#sembang-tanpa-keadaan-panel-kiri) + - [Sembang Berkeadaan (Panel Kanan)](#sembang-berkeadaan-panel-kanan) +- [Langkah Seterusnya](#langkah-seterusnya) ## Video Panduan -Tonton sesi langsung ini yang menerangkan cara untuk memulakan modul ini: +Tonton sesi langsung ini yang menerangkan cara untuk bermula dengan modul ini: -Memulakan dengan LangChain4j - Sesi Langsung +Getting Started with LangChain4j - Live Session -## Apa yang Anda Akan Pelajari +## Apa Yang Akan Anda Pelajari -Dalam permulaan pantas, anda menggunakan Model GitHub untuk menghantar permintaan, memanggil alat, membina saluran RAG, dan menguji kawalan keselamatan. Demo tersebut menunjukkan apa yang mungkin — kini kami berpindah kepada Azure OpenAI dan GPT-5.2 dan mula membina aplikasi gaya pengeluaran. Modul ini menumpukan pada AI perbualan yang mengingati konteks dan mengekalkan keadaan — konsep yang digunakan dalam demo permulaan pantas tetapi tidak diterangkan. +Ini adalah titik permulaan anda dengan LangChain4j dan Azure OpenAI. Kami bermula dengan asas-asas dan mula membina aplikasi gaya pengeluaran. Modul ini menumpukan kepada AI perbualan yang mengingati konteks dan mengekalkan keadaan — konsep asas yang dibina oleh setiap modul kemudian. -Kami akan menggunakan GPT-5.2 Azure OpenAI sepanjang panduan ini kerana kebolehannya dalam penalaran yang maju menjadikan tingkah laku corak yang berbeza lebih jelas. Apabila anda menambah memori, anda akan lihat perbezaannya dengan jelas. Ini memudahkan untuk memahami apa yang dibawa oleh setiap komponen kepada aplikasi anda. +Kami akan menggunakan GPT-5.2 Azure OpenAI sepanjang panduan ini kerana keupayaan penaakulan lanjutan menjadikan tingkah laku pola yang berbeza lebih nyata. Apabila anda menambah memori, anda akan jelas melihat perbezaannya. Ini memudahkan untuk memahami apa yang setiap komponen bawa ke aplikasi anda. -Anda akan membina satu aplikasi yang menunjukkan kedua-dua corak: +Anda akan membina satu aplikasi yang menunjukkan kedua-dua pola: -**Sembang Tanpa Keadaan** - Setiap permintaan adalah bebas. Model tidak mengingati mesej sebelumnya. Ini adalah corak yang anda gunakan dalam permulaan pantas. +**Sembang Tanpa Keadaan** - Setiap permintaan adalah berdikari. Model tidak mempunyai memori mesej sebelumnya. Ini adalah titik permulaan paling mudah. -**Perbualan Berkeadaan** - Setiap permintaan termasuk sejarah perbualan. Model mengekalkan konteks merentas beberapa gelung. Ini adalah yang diperlukan oleh aplikasi pengeluaran. +**Perbualan Berkeadaan** - Setiap permintaan merangkumi sejarah perbualan. Model mengekalkan konteks merentasi pelbagai giliran. Ini adalah apa yang diperlukan oleh aplikasi pengeluaran. ## Prasyarat - Langganan Azure dengan akses Azure OpenAI -- Java 21, Maven 3.9+ +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Nota:** Java, Maven, Azure CLI dan Azure Developer CLI (azd) telah dipasang dalam devcontainer yang disediakan. +> **Nota:** Java, Maven, Azure CLI dan Azure Developer CLI (azd) telah dipasang terlebih dahulu dalam devcontainer yang disediakan. -> **Nota:** Modul ini menggunakan GPT-5.2 di Azure OpenAI. Penyebaran dikonfigurasi secara automatik melalui `azd up` - jangan ubah nama model dalam kod. +> **Nota:** Modul ini menggunakan GPT-5.2 pada Azure OpenAI. Penyebaran dikonfigurasi secara automatik melalui `azd up` - jangan ubah nama model dalam kod. ## Memahami Masalah Teras -Model bahasa adalah tanpa keadaan. Setiap panggilan API adalah bebas. Jika anda menghantar "Nama saya John" dan kemudian bertanya "Siapakah nama saya?", model tidak tahu anda baru saja memperkenalkan diri. Ia menganggap setiap permintaan seperti perbualan pertama anda sekali. +Model bahasa adalah tanpa keadaan. Setiap panggilan API berdikari. Jika anda menghantar "Nama saya John" dan kemudian bertanya "Siapa nama saya?", model tidak tahu anda baru memperkenalkan diri. Ia menganggap setiap permintaan seolah-olah itu adalah perbualan pertama yang anda pernah lakukan. -Ini sesuai untuk soal jawab mudah tetapi tidak berguna untuk aplikasi sebenar. Bot perkhidmatan pelanggan perlu mengingati apa yang anda beritahu mereka. Pembantu peribadi memerlukan konteks. Apa-apa perbualan berbilang gelung memerlukan memori. +Ini sesuai untuk Q&A mudah tetapi tidak berguna untuk aplikasi sebenar. Bot perkhidmatan pelanggan perlu mengingati apa yang anda beritahu mereka. Pembantu peribadi memerlukan konteks. Apa-apa perbualan berbilang giliran memerlukan memori. -Rajah berikut membezakan dua pendekatan — di kiri, panggilan tanpa keadaan yang melupakan nama anda; di kanan, panggilan berkeadaan yang disokong oleh ChatMemory yang mengingatinya. +Rajah berikut membezakan dua pendekatan — di kiri, panggilan tanpa keadaan yang lupa nama anda; di kanan, panggilan berkeadaan dengan sokongan ChatMemory yang mengingatinya. -Perbualan Tanpa Keadaan vs Berkeadaan +Stateless vs Stateful Conversations -*Perbezaan antara perbualan tanpa keadaan (panggilan bebas) dan berkeadaan (sadar konteks)* +*Perbezaan antara perbualan tanpa keadaan (panggilan berdikari) dan berkeadaan (sedar konteks)* ## Memahami Token -Sebelum menyelami perbualan, penting untuk memahami token - unit asas teks yang diproses oleh model bahasa: +Sebelum meneroka perbualan, penting untuk memahami token - unit asas teks yang diproses oleh model bahasa: -Penjelasan Token +Token Explanation -*Contoh bagaimana teks dipecah menjadi token - "I love AI!" menjadi 4 unit pemprosesan berasingan* +*Contoh bagaimana teks dipecahkan kepada token - "I love AI!" menjadi 4 unit pemprosesan berasingan* -Token adalah cara model AI mengukur dan memproses teks. Perkataan, tanda baca, dan bahkan ruang boleh menjadi token. Model anda mempunyai had berapa banyak token yang boleh diproses sekali gus (400,000 untuk GPT-5.2, dengan sehingga 272,000 token input dan 128,000 token output). Memahami token membantu anda mengurus panjang perbualan dan kos. +Token adalah cara model AI mengukur dan memproses teks. Perkataan, tanda baca, dan bahkan ruang boleh menjadi token. Model anda mempunyai had berapa banyak token yang boleh diproses sekaligus (400,000 untuk GPT-5.2, dengan sehingga 272,000 token input dan 128,000 token output). Memahami token membantu anda mengurus panjang perbualan dan kos. ## Bagaimana Memori Berfungsi -Memori sembang menyelesaikan masalah tanpa keadaan dengan mengekalkan sejarah perbualan. Sebelum menghantar permintaan anda ke model, rangka kerja menambahkan mesej sebelumnya yang relevan terlebih dahulu. Apabila anda bertanya "Siapakah nama saya?", sistem sebenarnya menghantar keseluruhan sejarah perbualan, membolehkan model melihat anda sebelum ini berkata "Nama saya John." +Memori sembang menyelesaikan masalah tanpa keadaan dengan mengekalkan sejarah perbualan. Sebelum menghantar permintaan anda ke model, rangka kerja akan menambah mesej sebelumnya yang relevan. Apabila anda bertanya "Siapa nama saya?", sistem sebenarnya menghantar keseluruhan sejarah perbualan, membolehkan model melihat anda telah berkata "Nama saya John." -LangChain4j menyediakan pelaksanaan memori yang mengendalikannya secara automatik. Anda memilih berapa banyak mesej untuk disimpan dan rangka kerja menguruskan tetingkap konteks. Rajah di bawah menunjukkan bagaimana MessageWindowChatMemory mengekalkan tetingkap gelungsur mesej terkini. +LangChain4j menyediakan pelaksanaan memori yang mengendalikannya secara automatik. Anda pilih berapa banyak mesej untuk disimpan dan rangka kerja menguruskan tetingkap konteks. Rajah di bawah menunjukkan bagaimana MessageWindowChatMemory mengekalkan tetingkap gelongsor mesej terkini. -Konsep Tetingkap Memori +Memory Window Concept -*MessageWindowChatMemory mengekalkan tetingkap gelungsur mesej terkini, secara automatik membuang mesej lama* +*MessageWindowChatMemory mengekalkan tetingkap gelongsor mesej terkini, secara automatik membuang yang lama* ## Bagaimana Ini Menggunakan LangChain4j -Modul ini mengembangkan permulaan pantas dengan mengintegrasikan Spring Boot dan menambah memori perbualan. Berikut adalah cara komponen disusun: +Modul ini mengintegrasikan Spring Boot dan menambah memori perbualan. Begini cara bahagian-bahagian berfungsi bersama: **Pergantungan** - Tambah dua perpustakaan LangChain4j: @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder membaca kelayakan dari pembolehubah persekitaran yang ditetapkan oleh `azd up`. Menetapkan `baseUrl` ke titik akhir Azure anda membuat klien OpenAI berfungsi dengan Azure OpenAI. +Builder membaca kelayakan dari pembolehubah alam sekitar yang ditetapkan oleh `azd up`. Menetapkan `baseUrl` ke titik akhir Azure anda menjadikan klien OpenAI berfungsi dengan Azure OpenAI. **Memori Perbualan** - Jejaki sejarah sembang dengan MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,16 +124,16 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Buat memori dengan `withMaxMessages(10)` untuk menyimpan 10 mesej terakhir. Tambah mesej pengguna dan AI dengan pembalut berjenis: `UserMessage.from(text)` dan `AiMessage.from(text)`. Dapatkan sejarah dengan `memory.messages()` dan hantar ke model. Perkhidmatan menyimpan instans memori yang berasingan bagi setiap ID perbualan, membolehkan pelbagai pengguna berbual serentak. +Cipta memori dengan `withMaxMessages(10)` untuk menyimpan 10 mesej terakhir. Tambah mesej pengguna dan AI dengan pembungkus berjenis: `UserMessage.from(text)` dan `AiMessage.from(text)`. Dapatkan sejarah dengan `memory.messages()` dan hantar ke model. Perkhidmatan menyimpan instans memori berasingan setiap ID perbualan, membolehkan pelbagai pengguna berbual serentak. -> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Sembang:** Buka [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) dan tanya: -> - "Bagaimana MessageWindowChatMemory memutuskan mesej mana yang akan dibuang apabila tetingkap penuh?" -> - "Bolehkah saya melaksanakan penyimpanan memori khusus menggunakan pangkalan data dan bukannya dalam memori?" +> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) dan tanya: +> - "Bagaimana MessageWindowChatMemory memutuskan mesej mana yang dibuang apabila tetingkap penuh?" +> - "Bolehkah saya melaksanakan penyimpanan memori tersuai menggunakan pangkalan data dan bukan dalam memori?" > - "Bagaimana saya menambah ringkasan untuk memampatkan sejarah perbualan lama?" -Akhir sembang tanpa keadaan tidak menggunakan memori sama sekali - cuma `chatModel.chat(prompt)` seperti permulaan pantas. Akhir berkeadaan menambah mesej ke memori, mengambil sejarah, dan memasukkan konteks itu dengan setiap permintaan. Konfigurasi model sama, corak berbeza. +Endpoint sembang tanpa keadaan melangkau memori sama sekali - cuma `chatModel.chat(prompt)` seperti permulaan pantas. Endpoint berkeadaan menambah mesej ke memori, mengambil sejarah, dan menyertakan konteks itu dengan setiap permintaan. Konfigurasi model sama, pola berbeza. -## Menguruskan Infrastruktur Azure OpenAI +## Menyebarkan Infrastruktur Azure OpenAI **Bash:** ```bash @@ -147,14 +147,14 @@ cd 01-introduction azd up # Pilih langganan dan lokasi (eastus2 disyorkan) ``` -> **Nota:** Jika anda menghadapi ralat masa tamat (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), jalankan semula `azd up`. Sumber Azure mungkin masih dalam proses penyediaan di belakang tabir, dan cuba semula membenarkan penyebaran selesai apabila sumber mencapai keadaan terminal. +> **Nota:** Jika anda menghadapi ralat tamat masa (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), sila jalankan `azd up` sekali lagi. Sumber Azure mungkin masih sedang disediakan di latar belakang, dan cubaan semula membenarkan penyebaran selesai apabila sumber mencapai keadaan terminal. Ini akan: 1. Menyebarkan sumber Azure OpenAI dengan model GPT-5.2 dan text-embedding-3-small -2. Menjana fail `.env` secara automatik di akar projek dengan kelayakan -3. Menyediakan semua pembolehubah persekitaran yang diperlukan +2. Menjana secara automatik fail `.env` di akar projek dengan kelayakan +3. Mengatur semua pembolehubah alam sekitar yang diperlukan -**Mengalami masalah penyebaran?** Lihat [README Infrastruktur](infra/README.md) untuk penyelesaian terperinci termasuk konflik nama subdomain, langkah penyebaran manual di Portal Azure, dan panduan konfigurasi model. +**Mengalami masalah penyebaran?** Lihat [README Infrastruktur](infra/README.md) untuk penyelesaian masalah terperinci termasuk konflik nama subdomain, langkah penyebaran manual di Azure Portal, dan panduan konfigurasi model. **Sahkan penyebaran berjaya:** @@ -165,10 +165,10 @@ cat ../.env # Patut menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, dan lain-lain. **PowerShell:** ```powershell -Get-Content ..\.env # Patut menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, dan lain-lain. +Get-Content ..\.env # Perlu menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, dan lain-lain. ``` -> **Nota:** Perintah `azd up` menjana fail `.env` secara automatik. Jika anda perlu mengemas kini fail itu kemudian, anda boleh sunting fail `.env` secara manual atau hasilkan semula dengan menjalankan: +> **Nota:** Perintah `azd up` menjana fail `.env` secara automatik. Jika anda perlu kemaskini kemudian, anda boleh sama ada edit fail `.env` secara manual atau menjana semula dengan menjalankan: > > **Bash:** > ```bash @@ -190,31 +190,31 @@ Pastikan fail `.env` wujud di direktori akar dengan kelayakan Azure. Jalankan in **Bash:** ```bash -cat ../.env # Perlu menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Patut menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Patut menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Perlu menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Mulakan aplikasi:** **Pilihan 1: Menggunakan Spring Boot Dashboard (Disyorkan untuk pengguna VS Code)** -Kontena dev termasuk peluasan Spring Boot Dashboard, yang menyediakan antara muka visual untuk mengurus semua aplikasi Spring Boot. Anda boleh menjumpainya di Bar Aktiviti di sebelah kiri VS Code (cari ikon Spring Boot). +Dev container termasuk sambungan Spring Boot Dashboard yang menyediakan antara muka visual untuk mengurus semua aplikasi Spring Boot. Anda boleh menemuinya di Bar Aktiviti di sebelah kiri VS Code (carilah ikon Spring Boot). -Dari Spring Boot Dashboard, anda boleh: -- Lihat semua aplikasi Spring Boot yang tersedia dalam ruang kerja -- Mulakan/berhenti aplikasi dengan satu klik +Daripada Spring Boot Dashboard, anda boleh: +- Lihat semua aplikasi Spring Boot tersedia dalam ruang kerja +- Mulakan/hentikan aplikasi dengan satu klik - Lihat log aplikasi secara masa nyata - Pantau status aplikasi -Klik butang main di sebelah "introduction" untuk memulakan modul ini, atau mulakan semua modul sekaligus. +Klik butang main di sebelah "introduction" untuk mulakan modul ini, atau mula semua modul serentak. Spring Boot Dashboard -*Spring Boot Dashboard di VS Code — mulakan, berhenti, dan pantau semua modul dari satu tempat* +*Spring Boot Dashboard di VS Code — mula, hentikan, dan pantau semua modul dari satu tempat* **Pilihan 2: Menggunakan skrip shell** @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Kedua-dua skrip secara automatik memuat pembolehubah persekitaran dari fail `.env` akar dan akan membina JAR jika belum ada. +Kedua-dua skrip secara automatik memuat pembolehubah alam sekitar dari fail `.env` akar dan akan membina JAR jika belum wujud. -> **Nota:** Jika anda lebih suka membina semua modul secara manual sebelum memulakan: +> **Nota:** Jika anda lebih suka membina semua modul secara manual sebelum mula: > > **Bash:** > ```bash @@ -264,7 +264,7 @@ Kedua-dua skrip secara automatik memuat pembolehubah persekitaran dari fail `.en Buka http://localhost:8080 dalam pelayar anda. -**Untuk berhenti:** +**Untuk hentikan:** **Bash:** ```bash @@ -284,27 +284,27 @@ cd ..; .\stop-all.ps1 # Semua modul Aplikasi menyediakan antara muka web dengan dua pelaksanaan sembang berdampingan. -Skrin Utama Aplikasi +Application Home Screen *Papan pemuka menunjukkan pilihan Sembang Mudah (tanpa keadaan) dan Sembang Perbualan (berkeadaan)* ### Sembang Tanpa Keadaan (Panel Kiri) -Cuba ini dahulu. Tanyakan "Nama saya John" dan kemudian segera tanya "Siapakah nama saya?" Model tidak akan ingat kerana setiap mesej adalah bebas. Ini menunjukkan masalah teras dengan integrasi model bahasa asas - tiada konteks perbualan. +Cuba ini dahulu. Tanya "Nama saya John" dan kemudian terus tanya "Siapa nama saya?" Model tidak akan ingat kerana setiap mesej berdikari. Ini menunjukkan masalah asas pengintegrasian model bahasa - tiada konteks perbualan. -Demo Sembang Tanpa Keadaan +Stateless Chat Demo *AI tidak mengingati nama anda dari mesej sebelumnya* ### Sembang Berkeadaan (Panel Kanan) -Sekarang cuba urutan yang sama di sini. Tanya "Nama saya John" dan kemudian "Siapakah nama saya?" Kali ini ia ingat. Perbezaannya adalah MessageWindowChatMemory - ia mengekalkan sejarah perbualan dan memasukkannya dengan setiap permintaan. Ini cara AI perbualan pengeluaran berfungsi. +Sekarang cuba urutan yang sama di sini. Tanya "Nama saya John" dan kemudian "Siapa nama saya?" Kali ini ia mengingatnya. Bezanya ialah MessageWindowChatMemory - ia mengekalkan sejarah perbualan dan menyertakannya dengan setiap permintaan. Begitulah AI perbualan pengeluaran berfungsi. -Demo Sembang Berkeadaan +Stateful Chat Demo *AI mengingati nama anda dari awal perbualan* -Kedua-dua panel menggunakan model GPT-5.2 yang sama. Satu-satunya perbezaan adalah memori. Ini menunjukkan dengan jelas apa yang dibawa oleh memori kepada aplikasi anda dan mengapa ia penting untuk kes penggunaan sebenar. +Kedua-dua panel menggunakan model GPT-5.2 yang sama. Perbezaan satu-satunya ialah memori. Ini menjelaskan apa yang dibawa oleh memori ke aplikasi anda dan mengapa ia penting untuk kes penggunaan sebenar. ## Langkah Seterusnya @@ -312,11 +312,11 @@ Kedua-dua panel menggunakan model GPT-5.2 yang sama. Satu-satunya perbezaan adal --- -**Navigasi:** [← Sebelumnya: Modul 00 - Permulaan Pantas](../00-quick-start/README.md) | [Kembali ke Utama](../README.md) | [Seterusnya: Modul 02 - Kejuruteraan Prompt →](../02-prompt-engineering/README.md) +**Navigasi:** [← Kembali ke Utama](../README.md) | [Seterusnya: Modul 02 - Kejuruteraan Prompt →](../02-prompt-engineering/README.md) --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan profesional oleh manusia adalah disyorkan. Kami tidak bertanggungjawab atas sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/ms/02-prompt-engineering/README.md b/translations/ms/02-prompt-engineering/README.md index 67169a67b..f2624fd50 100644 --- a/translations/ms/02-prompt-engineering/README.md +++ b/translations/ms/02-prompt-engineering/README.md @@ -2,84 +2,84 @@ ## Jadual Kandungan -- [Panduan Video](../../../02-prompt-engineering) -- [Apa yang Akan Anda Pelajari](../../../02-prompt-engineering) -- [Prasyarat](../../../02-prompt-engineering) -- [Memahami Kejuruteraan Prompt](../../../02-prompt-engineering) -- [Asas Kejuruteraan Prompt](../../../02-prompt-engineering) - - [Prompt Tanpa Contoh](../../../02-prompt-engineering) - - [Prompt Dengan Beberapa Contoh](../../../02-prompt-engineering) - - [Rantaian Pemikiran](../../../02-prompt-engineering) - - [Prompt Berdasarkan Peranan](../../../02-prompt-engineering) - - [Templat Prompt](../../../02-prompt-engineering) -- [Corak Lanjutan](../../../02-prompt-engineering) -- [Jalankan Aplikasi](../../../02-prompt-engineering) -- [Tangkapan Skrin Aplikasi](../../../02-prompt-engineering) -- [Meneroka Corak](../../../02-prompt-engineering) - - [Keghairahan Rendah vs Tinggi](../../../02-prompt-engineering) - - [Pelaksanaan Tugas (Preambul Alat)](../../../02-prompt-engineering) - - [Kod Reflektif Diri](../../../02-prompt-engineering) - - [Analisis Berstruktur](../../../02-prompt-engineering) - - [Cakap Bergilir Pelbagai Pusingan](../../../02-prompt-engineering) - - [Penalaran Langkah demi Langkah](../../../02-prompt-engineering) - - [Output Terhad](../../../02-prompt-engineering) -- [Apa yang Anda Benar-Benar Pelajari](../../../02-prompt-engineering) -- [Langkah Seterusnya](../../../02-prompt-engineering) - -## Panduan Video +- [Video Walkthrough](#video-walkthrough) +- [Apa yang Anda Akan Pelajari](#apa-yang-anda-akan-pelajari) +- [Prasyarat](#prasyarat) +- [Memahami Kejuruteraan Prompt](#memahami-kejuruteraan-prompt) +- [Asas Kejuruteraan Prompt](#asas-kejuruteraan-prompt) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Corak Lanjutan](#corak-lanjutan) +- [Jalankan Aplikasi](#jalankan-aplikasi) +- [Tangkapan Skrin Aplikasi](#tangkapan-skrin-aplikasi) +- [Meneroka Corak](#meneroka-corak) + - [Rendah vs Tinggi Semangat](#low-vs-high-eagerness) + - [Pelaksanaan Tugas (Preambule Alat)](#pelaksanaan-tugas-preambul-alat) + - [Kod Refleksi Diri](#kod-refleksi-diri) + - [Analisis Berstruktur](#analisis-berstruktur) + - [Chat Pelbagai Giliran](#sembang-multi-turn) + - [Penalaran Langkah demi Langkah](#pemikiran-langkah-demi-langkah) + - [Output Terhad](#keluaran-terhad) +- [Apa yang Anda Sebenarnya Pelajari](#apa-yang-anda-sebenarnya-belajar) +- [Langkah Seterusnya](#langkah-seterusnya) + +## Video Walkthrough Tonton sesi langsung ini yang menerangkan cara memulakan modul ini: -Kejuruteraan Prompt dengan LangChain4j - Sesi Langsung +Prompt Engineering with LangChain4j - Live Session -## Apa yang Akan Anda Pelajari +## Apa yang Anda Akan Pelajari -Rajah berikut memberikan gambaran tentang topik utama dan kemahiran yang anda akan kembangkan dalam modul ini — daripada teknik penambahbaikan prompt kepada aliran kerja langkah demi langkah yang akan anda ikuti. +Rajah berikut menyediakan gambaran keseluruhan topik utama dan kemahiran yang anda akan bangunkan dalam modul ini — daripada teknik penambahbaikan prompt hingga aliran kerja langkah demi langkah yang akan anda ikuti. -Apa yang Akan Anda Pelajari +Apa yang Anda Akan Pelajari -Dalam modul sebelumnya, anda meneroka interaksi asas LangChain4j dengan Model GitHub dan melihat bagaimana ingatan membolehkan AI perbualan dengan Azure OpenAI. Sekarang kita akan fokus pada cara anda mengajukan soalan — prompt itu sendiri — menggunakan GPT-5.2 Azure OpenAI. Cara anda menyusun prompt secara dramatik mempengaruhi kualiti respons yang anda terima. Kita mulakan dengan ulasan teknik prompting asas, kemudian beralih ke lapan corak lanjutan yang memanfaatkan sepenuhnya kebolehan GPT-5.2. +Dalam modul sebelum ini, anda melihat bagaimana memori membolehkan AI perbualan dengan Azure OpenAI. Kini kita akan fokus pada cara anda bertanya soalan — prompt itu sendiri — menggunakan GPT-5.2 Azure OpenAI. Cara anda menyusun prompt anda secara dramatik mempengaruhi kualiti jawapan yang anda peroleh. Kita mulakan dengan ulang kaji teknik prompting asas, kemudian bergerak ke lapan corak lanjutan yang memanfaatkan sepenuhnya keupayaan GPT-5.2. -Kita gunakan GPT-5.2 kerana ia memperkenalkan kawalan penalaran - anda boleh memberitahu model berapa banyak pemikiran yang perlu dilakukan sebelum menjawab. Ini membuatkan strategi prompting yang berbeza lebih jelas dan membantu anda memahami bila untuk menggunakan setiap pendekatan. Kita juga akan mendapat manfaat dari had kadar yang lebih sedikit Azure untuk GPT-5.2 berbanding Model GitHub. +Kita menggunakan GPT-5.2 kerana ia memperkenalkan kawalan penalaran - anda boleh memberitahu model berapa banyak pemikiran yang perlu dilakukan sebelum menjawab. Ini menjadikan strategi prompting yang berbeza lebih jelas dan membantu anda memahami bila untuk menggunakan setiap pendekatan. ## Prasyarat -- Menyelesaikan Modul 01 (sumber Azure OpenAI telah diterapkan) -- Fail `.env` di direktori root dengan kelayakan Azure (dibuat oleh `azd up` dalam Modul 01) +- Modul 01 sudah selesai (sumber Azure OpenAI dipasang) +- Fail `.env` di direktori akar dengan kelayakan Azure (dicipta oleh `azd up` dalam Modul 01) -> **Nota:** Jika anda belum menyelesaikan Modul 01, ikut arahan penyebaran di sana dahulu. +> **Nota:** Jika anda belum menyelesaikan Modul 01, ikut arahan pemasangan di sana terlebih dahulu. ## Memahami Kejuruteraan Prompt -Pada intinya, kejuruteraan prompt adalah perbezaan antara arahan samar dan arahan tepat, seperti yang ditunjukkan dalam perbandingan di bawah. +Pada asasnya, kejuruteraan prompt adalah perbezaan antara arahan yang samar dan yang tepat, seperti yang ditunjukkan dalam perbandingan di bawah. -Apakah Itu Kejuruteraan Prompt? +Apa itu Kejuruteraan Prompt? -Kejuruteraan prompt adalah tentang mereka bentuk teks input yang sentiasa memberikan hasil yang anda perlukan. Ia bukan sekadar bertanya soalan - ia tentang menyusun permintaan supaya model benar-benar faham apa yang anda mahu dan bagaimana untuk menyampaiinya. +Kejuruteraan prompt adalah tentang mereka bentuk teks input yang sentiasa memberikan hasil yang anda perlukan. Ia bukan sahaja mengenai bertanya soalan - ia tentang struktur permintaan supaya model memahami dengan tepat apa yang anda mahu dan bagaimana untuk menyampaikannya. -Fikirkan ia seperti memberi arahan kepada rakan sekerja. "Betulkan pepijat" adalah samar. "Betulkan pengecualian penunjuk kosong di UserService.java baris 45 dengan menambah semakan null" adalah spesifik. Model bahasa berfungsi sama — kekhususan dan struktur penting. +Fikirkan ia seperti memberi arahan kepada rakan sekerja. "Betulkan pepijat" adalah samar. "Betulkan pengecualian null pointer dalam UserService.java baris 45 dengan menambah cek null" adalah spesifik. Model bahasa berfungsi dengan cara yang sama - kekhususan dan struktur adalah penting. -Rajah di bawah menunjukkan bagaimana LangChain4j sesuai dalam gambaran ini — menghubungkan corak prompt anda ke model melalui blok binaan SystemMessage dan UserMessage. +Rajah di bawah menunjukkan bagaimana LangChain4j sesuai dalam gambaran ini — menghubungkan corak prompt anda kepada model melalui blok binaan SystemMessage dan UserMessage. Bagaimana LangChain4j Sesuai -LangChain4j menyediakan infrastruktur — sambungan model, memori, dan jenis mesej — sementara corak prompt hanyalah teks yang disusun dengan teliti yang anda hantar melalui infrastruktur itu. Blok bina utama adalah `SystemMessage` (yang menetapkan tingkah laku dan peranan AI) dan `UserMessage` (yang membawa permintaan sebenar anda). +LangChain4j menyediakan infrastruktur — sambungan model, memori, dan jenis mesej — manakala corak prompt hanyalah teks yang disusun dengan teliti yang anda hantar melalui infrastruktur itu. Blok binaan utama adalah `SystemMessage` (yang menetapkan kelakuan dan peranan AI) dan `UserMessage` (yang membawa permintaan sebenar anda). ## Asas Kejuruteraan Prompt Lima teknik teras yang ditunjukkan di bawah membentuk asas kejuruteraan prompt yang berkesan. Setiap satu menangani aspek berbeza bagaimana anda berkomunikasi dengan model bahasa. -Tinjauan Lima Corak Kejuruteraan Prompt +Gambaran Keseluruhan Lima Corak Kejuruteraan Prompt -Sebelum menyelami corak lanjutan dalam modul ini, mari kita ulas lima teknik prompting asas. Ini adalah blok bina yang setiap jurutera prompt harus tahu. Jika anda telah mengikuti modul [Mula Cepat](../00-quick-start/README.md#2-prompt-patterns), anda sudah melihatnya beraksi — ini adalah kerangka konsep di sebaliknya. +Sebelum menyelami corak lanjutan dalam modul ini, mari kita ulang kaji lima teknik prompting asas. Ini adalah blok binaan yang perlu diketahui oleh setiap jurutera prompt. -### Prompt Tanpa Contoh +### Zero-Shot Prompting -Pendekatan paling mudah: beri model arahan langsung tanpa contoh. Model bergantung sepenuhnya pada latihan untuk memahami dan melaksanakan tugas. Ini berkesan untuk permintaan mudah di mana tingkah laku yang diharapkan jelas. +Pendekatan paling mudah: beri model arahan langsung tanpa contoh. Model bergantung sepenuhnya pada latihannya untuk memahami dan melaksanakan tugas. Ini berkesan untuk permintaan yang mudah di mana tingkah laku yang dijangka jelas. -Prompt Tanpa Contoh +Zero-Shot Prompting -*Arahan langsung tanpa contoh — model menyerlahkan tugas hanya dari arahan* +*Arahan langsung tanpa contoh — model membuat inferens tugas hanya dari arahan* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Respons: "Positif" ``` -**Bila digunakan:** Klasifikasi mudah, soalan langsung, terjemahan, atau mana-mana tugas yang model boleh kendalikan tanpa panduan tambahan. +**Bila digunakan:** Pengelasan mudah, soalan langsung, terjemahan, atau mana-mana tugas yang model boleh kendalikan tanpa panduan tambahan. -### Prompt Dengan Beberapa Contoh +### Few-Shot Prompting -Berikan contoh yang menunjukkan corak yang anda mahu model ikuti. Model mempelajari format input-output yang dijangka dari contoh anda dan menerapkannya kepada input baru. Ini secara dramatik meningkatkan konsistensi untuk tugas di mana format atau tingkah laku yang dikehendaki tidak jelas. +Sediakan contoh yang menunjukkan corak yang anda mahu model ikuti. Model belajar format input-output yang dijangka dari contoh anda dan memohon pada input baru. Ini meningkatkan konsistensi dengan ketara untuk tugas di mana format atau tingkah laku yang dikehendaki tidak jelas. -Prompt Dengan Beberapa Contoh +Few-Shot Prompting -*Belajar dari contoh — model mengenal pasti corak dan menerapkannya pada input baru* +*Belajar dari contoh — model mengenal pasti corak dan memohon pada input baru* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Bila digunakan:** Klasifikasi tersuai, pemformatan konsisten, tugas domain khusus, atau bila hasil zero-shot tidak konsisten. +**Bila digunakan:** Pengelasan khusus, pemformatan konsisten, tugasan khusus domain, atau apabila hasil zero-shot tidak konsisten. -### Rantaian Pemikiran +### Chain of Thought -Minta model menunjukkan penalaran langkah demi langkah. Daripada terus menjawab, model memecahkan masalah dan mengerjakan setiap bahagian dengan jelas. Ini meningkatkan ketepatan dalam tugasan matematik, logik, dan penalaran berbilang langkah. +Minta model menunjukkan penalarannya langkah demi langkah. Daripada terus ke jawapan, model memecahkan masalah dan bekerja melalui setiap bahagian secara eksplisit. Ini meningkatkan ketepatan pada matematik, logik, dan tugasan penalaran berbilang langkah. -Prompt Rantaian Pemikiran +Chain of Thought Prompting -*Penalaran langkah demi langkah — memecah masalah kompleks kepada langkah logik yang jelas* +*Penalaran langkah demi langkah — memecahkan masalah kompleks kepada langkah logik yang jelas* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Model menunjukkan: 15 - 8 = 7, kemudian 7 + 12 = 19 epal ``` -**Bila digunakan:** Masalah matematik, teka-teki logik, penyahpepijatan, atau mana-mana tugasan di mana menunjukkan proses penalaran meningkatkan ketepatan dan kepercayaan. +**Bila digunakan:** Masalah matematik, teka-teki logik, penyahpepijatan, atau mana-mana tugas di mana menunjukkan proses penalaran meningkatkan ketepatan dan kepercayaan. -### Prompt Berdasarkan Peranan +### Role-Based Prompting -Tetapkan persona atau peranan untuk AI sebelum mengajukan soalan anda. Ini menyediakan konteks yang membentuk nada, kedalaman, dan fokus respons. "Arkitek perisian" memberi nasihat berbeza daripada "pembangun junior" atau "juruaudit keselamatan". +Tetapkan persona atau peranan untuk AI sebelum mengemukakan soalan anda. Ini memberi konteks yang membentuk nada, kedalaman, dan fokus jawapan. Seorang "arkitek perisian" memberikan nasihat berbeza daripada seorang "pembangun junior" atau "juruaudit keselamatan". -Prompt Berdasarkan Peranan +Role-Based Prompting -*Menetapkan konteks dan persona — soalan yang sama mendapat respons berbeza bergantung pada peranan yang diberikan* +*Menetapkan konteks dan persona — soalan yang sama mendapat jawapan berbeza mengikut peranan yang ditetapkan* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Bila digunakan:** Ulasan kod, pembelajaran, analisis domain khusus, atau bila anda memerlukan respons yang disesuaikan dengan tahap kepakaran atau perspektif tertentu. +**Bila digunakan:** Ulasan kod, pembelajaran, analisis khusus domain, atau apabila anda perlukan jawapan yang disesuaikan dengan tahap kepakaran atau perspektif tertentu. -### Templat Prompt +### Prompt Templates -Cipta prompt yang boleh digunakan semula dengan tempat letak pembolehubah. Daripada menulis prompt baru setiap kali, tentukan templatenya sekali dan isi nilai berlainan. Kelas `PromptTemplate` LangChain4j memudahkan ini dengan sintaks `{{variable}}`. +Buat prompt yang boleh digunakan semula dengan ruang letak pembolehubah. Daripada menulis prompt baru setiap kali, definisikan templat sekali dan isi dengan nilai berbeza. Kelas `PromptTemplate` LangChain4j memudahkan ini dengan sintaks `{{variable}}`. -Templat Prompt +Prompt Templates -*Prompt guna semula dengan tempat letak pembolehubah — satu template, banyak guna* +*Prompt boleh guna semula dengan ruang letak pembolehubah — satu templat, banyak kegunaan* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Bila digunakan:** Pertanyaan ulangan dengan input berbeza, pemprosesan batch, membina aliran kerja AI guna semula, atau sebarang situasi di mana struktur prompt kekal sama tetapi datanya berubah. +**Bila digunakan:** Pertanyaan berulang dengan input berbeza, pemprosesan batch, membina aliran kerja AI boleh guna semula, atau mana-mana senario di mana struktur prompt tetap sama tetapi data berubah. --- -Lima asas ini memberi anda set alat yang kukuh untuk kebanyakan tugasan prompting. Selebihnya modul ini membina di atasnya dengan **lapan corak lanjutan** yang memanfaatkan kawalan penalaran GPT-5.2, penilaian kendiri, dan kebolehan output berstruktur. +Lima asas ini memberi anda set alat yang kukuh untuk kebanyakan tugasan prompting. Selebihnya modul ini dibina di atasnya dengan **lapan corak lanjutan** yang memanfaatkan kawalan penalaran, penilaian sendiri, dan kebolehan output berstruktur GPT-5.2. ## Corak Lanjutan -Setelah asas diliputi, mari beralih kepada lapan corak lanjutan yang menjadikan modul ini unik. Tidak semua masalah memerlukan pendekatan yang sama. Sesetengah soalan memerlukan jawapan cepat, yang lain memerlukan pemikiran mendalam. Ada yang memerlukan penalaran jelas, ada yang hanya perlukan hasil. Setiap corak di bawah dioptimumkan untuk senario berbeza — dan kawalan penalaran GPT-5.2 menjadikan perbezaannya lebih ketara. +Dengan asas yang diliputi, mari beralih ke lapan corak lanjutan yang menjadikan modul ini unik. Tidak semua masalah memerlukan pendekatan yang sama. Sesetengah soalan memerlukan jawapan cepat, yang lain memerlukan pemikiran mendalam. Ada yang memerlukan penalaran yang kelihatan, ada pula hanya memerlukan keputusan. Setiap corak di bawah dioptimumkan untuk senario yang berbeza — dan kawalan penalaran GPT-5.2 menjadikan perbezaan ini lebih ketara. Lapan Corak Prompting -*Tinjauan lapan corak kejuruteraan prompt dan kes penggunaan mereka* +*Gambaran keseluruhan lapan corak kejuruteraan prompt dan kes penggunaannya* -GPT-5.2 menambah dimensi lain kepada corak ini: *kawalan penalaran*. Gelangsar di bawah menunjukkan bagaimana anda boleh laraskan usaha pemikiran model — daripada jawapan pantas, langsung ke analisis mendalam dan menyeluruh. +GPT-5.2 menambah dimensi lain kepada corak ini: *kawalan penalaran*. Peluncur di bawah menunjukkan bagaimana anda boleh laraskan usaha pemikiran model — daripada jawapan cepat dan langsung ke analisis mendalam dan teliti. Kawalan Penalaran dengan GPT-5.2 -*Kawalan penalaran GPT-5.2 membolehkan anda tetapkan berapa banyak pemikiran model perlu lakukan — daripada jawapan langsung laju ke penerokaan mendalam* +*Kawalan penalaran GPT-5.2 membolehkan anda tentukan berapa banyak pemikiran yang model harus lakukan — daripada jawapan pantas terus ke penerokaan mendalam* -**Keghairahan Rendah (Cepat & Fokus)** - Untuk soalan mudah di mana anda mahukan jawapan cepat, terus. Model melakukan sedikit penalaran - maksimum 2 langkah. Gunakan ini untuk pengiraan, pencarian, atau soalan mudah. +**Semangat Rendah (Cepat & Fokus)** - Untuk soalan mudah di mana anda mahu jawapan pantas dan langsung. Model melakukan penalaran minimum - maksimum 2 langkah. Gunakan ini untuk pengiraan, carian, atau soalan langsung. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Terokai dengan GitHub Copilot:** Buka [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) dan tanya: -> - "Apa perbezaan antara corak prompting keghairahan rendah dan tinggi?" -> - "Bagaimana tag XML dalam prompt membantu struktur respons AI?" -> - "Bilakah saya patut guna corak refleksi diri berbanding arahan langsung?" +> 💡 **Jelajah dengan GitHub Copilot:** Buka [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) dan tanya: +> - "Apakah perbezaan antara corak prompting semangat rendah dan tinggi?" +> - "Bagaimana tag XML dalam prompt membantu menyusun jawapan AI?" +> - "Bilakah saya harus menggunakan corak refleksi diri berbanding arahan langsung?" -**Keghairahan Tinggi (Mendalam & Teliti)** - Untuk masalah kompleks di mana anda mahukan analisis menyeluruh. Model meneroka dengan teliti dan menunjukkan penalaran terperinci. Gunakan ini untuk reka bentuk sistem, keputusan seni bina, atau penyelidikan rumit. +**Semangat Tinggi (Mendalam & Teliti)** - Untuk masalah kompleks di mana anda mahu analisis menyeluruh. Model meneroka dengan teliti dan menunjukkan penalaran terperinci. Gunakan ini untuk reka bentuk sistem, keputusan seni bina, atau penyelidikan kompleks. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Pelaksanaan Tugas (Kemajuan Langkah demi Langkah)** - Untuk aliran kerja berbilang langkah. Model menyediakan pelan awal, menceritakan setiap langkah semasa bekerja, kemudian memberi ringkasan. Gunakan ini untuk migrasi, pelaksanaan, atau mana-mana proses berbilang langkah. +**Pelaksanaan Tugas (Kemajuan Langkah demi Langkah)** - Untuk aliran kerja berbilang langkah. Model memberikan pelan awal, menceritakan setiap langkah semasa melaksanakan, kemudian memberikan ringkasan. Gunakan ini untuk migrasi, pelaksanaan, atau mana-mana proses berbilang langkah. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Prompt rantai pemikiran secara jelas meminta model menunjukkan proses penalaran, meningkatkan ketepatan untuk tugasan kompleks. Pemecahan langkah demi langkah membantu manusia dan AI memahami logik. +Prompt Chain-of-Thought secara jelas meminta model menunjukkan proses penalarannya, meningkatkan ketepatan untuk tugasan kompleks. Pecahan langkah demi langkah membantu manusia dan AI memahami logik. -> **🤖 Cuba dengan Sembang [GitHub Copilot](https://github.com/features/copilot):** Tanya tentang corak ini: -> - "Bagaimana saya boleh sesuaikan corak pelaksanaan tugas untuk operasi yang berjalan lama?" -> - "Apakah amalan terbaik untuk menyusun preambul alat dalam aplikasi produksi?" -> - "Bagaimana saya boleh menangkap dan memaparkan kemas kini kemajuan antara dalam UI?" +> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Tanyakan tentang corak ini: +> - "Bagaimana saya menyesuaikan corak pelaksanaan tugas untuk operasi jangka panjang?" +> - "Apakah amalan terbaik untuk menyusun preambule alat dalam aplikasi produksi?" +> - "Bagaimana saya boleh menangkap dan memaparkan kemas kini kemajuan pertengahan dalam UI?" -Rajah di bawah menggambarkan aliran kerja Pelan → Laksana → Rumus. +Rajah di bawah menggambarkan aliran kerja Pelan → Laksanakan → Rumus. Corak Pelaksanaan Tugas -*Aliran kerja Pelan → Laksana → Rumus untuk tugasan berbilang langkah* +*Aliran kerja Pelan → Laksanakan → Rumus untuk tugasan berbilang langkah* -**Kod Reflektif Diri** - Untuk menjana kod berkualiti produksi. Model menjana kod mengikut piawaian produksi dengan pengendalian ralat yang betul. Gunakan ini bila membina ciri atau perkhidmatan baru. +**Kod Refleksi Diri** - Untuk menjana kod berkualiti produksi. Model menjana kod mengikut piawaian produksi dengan pengendalian ralat yang betul. Gunakan ini apabila membina ciri atau perkhidmatan baru. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Rajah di bawah menunjukkan kitaran peningkatan berulang ini — menjana, menilai, kenal pasti kelemahan, dan haluskan sehingga kod memenuhi piawaian produksi. +Rajah di bawah menunjukkan kitaran penambahbaikan berulang ini — jana, nilaikan, kenal pasti kelemahan, dan perbaiki sehingga kod memenuhi piawaian produksi. Kitaran Refleksi Diri -*Kitaran peningkatan berulang - menjana, menilai, kenal pasti isu, perbaiki, ulang* +*Kitaran penambahbaikan berulang - jana, nilaikan, kenal pasti isu, perbaiki, ulang* -**Analisis Berstruktur** - Untuk penilaian konsisten. Model mengulas kod menggunakan rangka kerja tetap (ketepatan, amalan, prestasi, keselamatan, penyelenggaraan). Gunakan ini untuk ulasan kod atau penilaian kualiti. +**Analisis Berstruktur** - Untuk penilaian konsisten. Model mengulas kod menggunakan kerangka tetap (ketepatan, amalan, prestasi, keselamatan, penyelenggaraan). Gunakan ini untuk ulasan kod atau penilaian kualiti. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Cuba dengan Sembang [GitHub Copilot](https://github.com/features/copilot):** Tanya tentang analisis berstruktur: -> - "Bagaimana saya boleh menyesuaikan rangka kerja analisis untuk jenis ulasan kod yang berbeza?" -> - "Apakah cara terbaik untuk mengurai dan bertindak balas terhadap output berstruktur secara programatik?" -> - "Bagaimana saya memastikan tahap keseriusan konsisten merentas sesi ulasan berlainan?" +> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Tanyakan tentang analisis berstruktur: +> - "Bagaimana saya boleh sesuaikan kerangka analisis untuk pelbagai jenis ulasan kod?" +> - "Apakah cara terbaik untuk mengurai dan bertindak atas output berstruktur secara programatik?" +> - "Bagaimana saya pastikan tahap keterukan konsisten dalam sesi ulasan berlainan?" -Rajah berikut menunjukkan bagaimana rangka kerja berstruktur ini mengatur ulasan kod dalam kategori konsisten dengan tahap keseriusan. +Rajah berikut menunjukkan bagaimana kerangka berstruktur ini mengatur ulasan kod ke dalam kategori konsisten dengan tahap keterukan. Corak Analisis Berstruktur -*Rangka kerja untuk ulasan kod konsisten dengan tahap keseriusan* +*Kerangka untuk ulasan kod konsisten dengan tahap keterukan* -**Cakap Bergilir Pelbagai Pusingan** - Untuk perbualan yang memerlukan konteks. Model mengingati mesej sebelumnya dan membina ke atasnya. Gunakan ini untuk sesi bantuan interaktif atau soal jawab kompleks. +**Chat Pelbagai Giliran** - Untuk perbualan yang memerlukan konteks. Model mengingati mesej sebelumnya dan membinanya. Gunakan ini untuk sesi bantuan interaktif atau Q&A kompleks. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Rajah di bawah memvisualisasikan bagaimana konteks perbualan terkumpul dengan setiap pusingan dan bagaimana ia berkaitan dengan had token model. +Rajah di bawah menggambarkan bagaimana konteks perbualan terkumpul dengan setiap giliran dan bagaimana ia berhubung dengan had token model. Memori Konteks -*Bagaimana konteks perbualan terkumpul sepanjang beberapa pusingan sehingga mencapai had token* -**Penalaran Langkah demi Langkah** - Untuk masalah yang memerlukan logik yang jelas. Model menunjukkan penalaran eksplisit untuk setiap langkah. Gunakan ini untuk masalah matematik, teka-teki logik, atau apabila anda perlu memahami proses pemikiran. +*Bagaimana konteks perbualan terkumpul sepanjang banyak giliran sehingga mencapai had token* + +**Penalaran Langkah demi Langkah** - Untuk masalah yang memerlukan logik yang jelas. Model menunjukkan penalaran secara eksplisit untuk setiap langkah. Gunakan ini untuk masalah matematik, teka-teki logik, atau apabila anda perlu memahami proses pemikiran. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Rajah di bawah menunjukkan bagaimana model memecahkan masalah kepada langkah-langkah logik yang eksplisit dan bernombor. +Rajah di bawah menunjukkan bagaimana model memecahkan masalah kepada langkah logik bernombor yang jelas. Corak Langkah demi Langkah +*Memecahkan masalah menjadi langkah logik yang jelas* -*Memecahkan masalah kepada langkah-langkah logik yang eksplisit* - -**Output Terhad** - Untuk jawapan dengan keperluan format khusus. Model mengikuti peraturan format dan panjang dengan ketat. Gunakan ini untuk ringkasan atau apabila anda memerlukan struktur output yang tepat. +**Keluaran Terhad** - Untuk respons dengan keperluan format tertentu. Model mematuhi peraturan format dan panjang dengan ketat. Gunakan ini untuk ringkasan atau apabila anda memerlukan struktur keluaran yang tepat. ```java String prompt = """ @@ -420,21 +420,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Rajah berikut menunjukkan bagaimana kekangan membimbing model untuk menghasilkan output yang mematuhi format dan keperluan panjang anda dengan ketat. +Rajah berikut menunjukkan bagaimana kekangan membimbing model untuk menghasilkan keluaran yang mematuhi sepenuhnya keperluan format dan panjang anda. -Corak Output Terhad +Corak Keluaran Terhad -*Menguatkuasakan format, panjang, dan keperluan struktur yang spesifik* +*Melaksanakan keperluan format, panjang, dan struktur tertentu* ## Jalankan Aplikasi **Sahkan pelaksanaan:** -Pastikan fail `.env` wujud di direktori akar dengan kelayakan Azure (dicipta semasa Modul 01). Jalankan ini dari direktori modul (`02-prompt-engineering/`): +Pastikan fail `.env` wujud di direktori utama dengan kelayakan Azure (dicipta semasa Modul 01). Jalankan ini dari direktori modul (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Perlu menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Patut menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -444,23 +444,23 @@ Get-Content ..\.env # Perlu menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Mulakan aplikasi:** -> **Nota:** Jika anda sudah memulakan semua aplikasi menggunakan `./start-all.sh` dari direktori akar (seperti yang diterangkan dalam Modul 01), modul ini sudah berjalan pada port 8083. Anda boleh langkau arahan mula di bawah dan terus ke http://localhost:8083. +> **Nota:** Jika anda sudah memulakan semua aplikasi menggunakan `./start-all.sh` dari direktori utama (seperti yang diterangkan dalam Modul 01), modul ini sudah berjalan di port 8083. Anda boleh langkau perintah mula di bawah dan terus ke http://localhost:8083. **Pilihan 1: Menggunakan Spring Boot Dashboard (Disyorkan untuk pengguna VS Code)** -Kontena dev termasuk sambungan Spring Boot Dashboard, yang menyediakan antara muka visual untuk mengurus semua aplikasi Spring Boot. Anda boleh menemuinya di Bar Aktiviti di sebelah kiri VS Code (cari ikon Spring Boot). +Bekas dev termasuk sambungan Spring Boot Dashboard, yang menyediakan antara muka visual untuk mengurus semua aplikasi Spring Boot. Anda boleh menjumpainya di Bar Aktiviti di sebelah kiri VS Code (cari ikon Spring Boot). Dari Spring Boot Dashboard, anda boleh: - Melihat semua aplikasi Spring Boot yang tersedia dalam ruang kerja -- Mulakan/henti aplikasi dengan satu klik +- Mulakan/hentikan aplikasi dengan satu klik - Lihat log aplikasi secara masa nyata - Pantau status aplikasi -Cuma klik butang main di sebelah "prompt-engineering" untuk memulakan modul ini, atau mulakan semua modul sekali gus. +Cuma klik butang main di sebelah "prompt-engineering" untuk memulakan modul ini, atau mula semua modul sekaligus. Spring Boot Dashboard -*Spring Boot Dashboard dalam VS Code — mula, hentikan, dan pantau semua modul dari satu tempat* +*Spring Boot Dashboard dalam VS Code — mulakan, berhenti, dan pantau semua modul dari satu tempat* **Pilihan 2: Menggunakan skrip shell** @@ -468,7 +468,7 @@ Mulakan semua aplikasi web (modul 01-04): **Bash:** ```bash -cd .. # Dari direktori root +cd .. # Dari direktori akar ./start-all.sh ``` @@ -478,7 +478,7 @@ cd .. # Dari direktori akar .\start-all.ps1 ``` -Atau mulakan hanya modul ini: +Atau mula hanya modul ini: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Kedua-dua skrip secara automatik memuatkan pembolehubah persekitaran dari fail `.env` akar dan akan membina JAR jika belum ada. +Kedua-dua skrip secara automatik memuatkan pembolehubah persekitaran dari fail `.env` utama dan akan membina JAR jika ia belum wujud. -> **Nota:** Jika anda lebih suka membina semua modul secara manual sebelum memulakan: +> **Nota:** Jika anda lebih suka membina semua modul secara manual sebelum mula: > > **Bash:** > ```bash @@ -508,7 +508,7 @@ Kedua-dua skrip secara automatik memuatkan pembolehubah persekitaran dari fail ` > mvn clean package -DskipTests > ``` -Buka http://localhost:8083 di pelayar anda. +Buka http://localhost:8083 dalam pelayar anda. **Untuk berhenti:** @@ -528,81 +528,81 @@ cd ..; .\stop-all.ps1 # Semua modul ## Tangkapan Skrin Aplikasi -Berikut ialah antara muka utama modul kejuruteraan prompt, di mana anda boleh bereksperimen dengan semua lapan corak secara berdampingan. +Ini adalah antara muka utama modul kejuruteraan prompt, di mana anda boleh bereksperimen dengan semua lapan corak sebelah-menyebelah. -Paparan Utama Dashboard +Laman Utama Dashboard -*Paparan utama yang menunjukkan semua 8 corak kejuruteraan prompt dengan ciri-ciri dan kes penggunaan mereka* +*Dashboard utama yang menunjukkan kesemua 8 corak kejuruteraan prompt dengan ciri dan kes guna mereka* -## Meneroka Corak-corak +## Meneroka Corak -Antara muka web membenarkan anda bereksperimen dengan strategi prompting yang berbeza. Setiap corak menyelesaikan masalah yang berbeza - cubalah untuk melihat bila setiap pendekatan menjadi cemerlang. +Antara muka web membolehkan anda mencuba pelbagai strategi prompting. Setiap corak menyelesaikan masalah berbeza - cuba untuk melihat bila setiap pendekatan bersinar. -> **Nota: Streaming vs Non-Streaming** — Setiap halaman corak menawarkan dua butang: **🔴 Alir Respons (Siang)** dan pilihan **Non-streaming**. Streaming menggunakan Server-Sent Events (SSE) untuk memaparkan token secara masa nyata semasa model menjana, jadi anda dapat melihat kemajuan dengan segera. Pilihan non-streaming menunggu keseluruhan respons sebelum memaparkannya. Untuk prompt yang mencetuskan penalaran mendalam (contohnya, High Eagerness, Self-Reflecting Code), panggilan non-streaming boleh mengambil masa yang sangat lama — kadang-kadang minit — tanpa maklum balas yang nampak. **Gunakan streaming apabila bereksperimen dengan prompt yang kompleks** supaya anda dapat melihat model berkerja dan elakkan kesan bahawa permintaan telah tamat masa. +> **Nota: Penstriman vs Bukan Penstriman** — Setiap halaman corak menawarkan dua butang: **🔴 Jawapan Penstriman (Langsung)** dan satu pilihan **Bukan penstriman**. Penstriman menggunakan Server-Sent Events (SSE) untuk memaparkan token secara masa nyata semasa model menjana, jadi anda melihat kemajuan dengan segera. Pilihan bukan penstriman menunggu keseluruhan jawapan sebelum memaparkannya. Untuk prompt yang memerlukan pemikiran mendalam (contohnya, High Eagerness, Kod Refleksi Diri), panggilan bukan penstriman boleh mengambil masa yang sangat lama — kadang-kadang minit — tanpa maklum balas yang ketara. **Gunakan penstriman apabila bereksperimen dengan prompt yang kompleks** supaya anda boleh melihat model berfungsi dan mengelakkan tanggapan bahawa permintaan telah tamat masa. > -> **Nota: Keperluan Pelayar** — Ciri streaming menggunakan Fetch Streams API (`response.body.getReader()`) yang memerlukan pelayar penuh (Chrome, Edge, Firefox, Safari). Ia **tidak** berfungsi dalam Simple Browser terbina dalam VS Code, kerana webviewnya tidak menyokong ReadableStream API. Jika anda menggunakan Simple Browser, butang non-streaming masih berfungsi secara normal — hanya butang streaming yang terhad. Buka `http://localhost:8083` dalam pelayar luar untuk pengalaman penuh. +> **Nota: Keperluan Pelayar** — Ciri penstriman menggunakan Fetch Streams API (`response.body.getReader()`) yang memerlukan pelayar penuh (Chrome, Edge, Firefox, Safari). Ia **tidak** berfungsi dalam Simple Browser terbina VS Code, kerana webview-nya tidak menyokong API ReadableStream. Jika anda menggunakan Simple Browser, butang bukan penstriman masih berfungsi seperti biasa — cuma butang penstriman yang terjejas. Buka `http://localhost:8083` di pelayar luar untuk pengalaman penuh. -### Eagerness Rendah vs Tinggi +### Low vs High Eagerness -Tanya soalan mudah seperti "Apakah 15% daripada 200?" menggunakan Eagerness Rendah. Anda akan mendapat jawapan segera dan terus. Sekarang tanya sesuatu yang kompleks seperti "Reka strategi caching untuk API trafik tinggi" menggunakan Eagerness Tinggi. Klik **🔴 Alir Respons (Siang)** dan tonton penalaran terperinci model muncul token demi token. Model sama, struktur soalan sama - tetapi prompt memberitahu berapa banyak pemikiran yang perlu dilakukan. +Tanya soalan mudah seperti "Berapakah 15% daripada 200?" menggunakan Low Eagerness. Anda akan mendapat jawapan segera dan langsung. Sekarang tanya sesuatu yang kompleks seperti "Rancang strategi cache untuk API trafik tinggi" menggunakan High Eagerness. Klik **🔴 Jawapan Penstriman (Langsung)** dan saksikan pemikiran terperinci model muncul token demi token. Model sama, struktur soalan sama - tetapi prompt memberitahu berapa banyak pemikiran yang perlu dibuat. -### Pelaksanaan Tugasan (Preambles Alat) +### Pelaksanaan Tugas (Preambul Alat) -Aliran kerja berbilang langkah memanfaatkan perancangan awal dan narasi kemajuan. Model menggariskan apa yang akan dilakukannya, menceritakan setiap langkah, kemudian meringkaskan hasil. +Aliran kerja berbilang langkah mendapat manfaat daripada perancangan awal dan narasi kemajuan. Model menggariskan apa yang akan dilakukan, menceritakan setiap langkah, kemudian merumuskan hasil. ### Kod Refleksi Diri -Cuba "Cipta perkhidmatan pengesahan emel". Daripada hanya menjana kod dan berhenti, model menjana, menilai berdasarkan kriteria kualiti, mengenal pasti kelemahan, dan memperbaiki. Anda akan lihat ia mengulang sehingga kod memenuhi piawaian pengeluaran. +Cuba "Cipta perkhidmatan pengesahan emel". Bukannya hanya menjana kod dan berhenti, model menjana, menilai berdasarkan kriteria kualiti, mengenal pasti kelemahan, dan memperbaiki. Anda akan melihat ia mengulangi sehingga kod memenuhi piawaian produksi. ### Analisis Berstruktur -Ulasan kod memerlukan rangka kerja penilaian yang konsisten. Model menganalisis kod menggunakan kategori tetap (ketepatan, amalan, prestasi, keselamatan) dengan tahap keterukan. +Kajian kod memerlukan kerangka penilaian yang konsisten. Model menganalisis kod menggunakan kategori tetap (ketepatan, amalan, prestasi, keselamatan) dengan tahap keterukan. -### Sembang Pelbagai Giliran +### Sembang Multi-Turn -Tanya "Apa itu Spring Boot?" kemudian teruskan dengan "Tunjukkan contoh". Model mengingati soalan pertama anda dan memberikan contoh Spring Boot yang spesifik. Tanpa ingatan, soalan kedua itu akan terlalu samar. +Tanya "Apa itu Spring Boot?" kemudian segera ikuti dengan "Tunjukkan saya contoh". Model mengingati soalan pertama anda dan memberi contoh Spring Boot khusus. Tanpa ingatan, soalan kedua itu akan terlalu samar. -### Penalaran Langkah demi Langkah +### Pemikiran Langkah-demi-Langkah -Pilih satu masalah matematik dan cuba dengan Penalaran Langkah demi Langkah dan Eagerness Rendah. Eagerness rendah hanya memberi jawapan - cepat tetapi sukar difahami. Penalaran langkah demi langkah menunjukkan setiap pengiraan dan keputusan. +Pilih masalah matematik dan cuba dengan kedua-dua Pemikiran Langkah-demi-Langkah dan Low Eagerness. Low eagerness hanya memberi jawapan - cepat tapi tidak telus. Langkah demi langkah menunjukkan setiap pengiraan dan keputusan. -### Output Terhad +### Keluaran Terhad -Apabila anda memerlukan format atau jumlah perkataan tertentu, corak ini menguatkuasakan pematuhan ketat. Cubalah menjana ringkasan dengan tepat 100 perkataan dalam format poin peluru. +Apabila anda memerlukan format atau bilangan perkataan tertentu, corak ini menguatkuasakan pematuhan ketat. Cuba jana rumusan dengan tepat 100 perkataan dalam format titik peluru. -## Apa yang Anda Betul-betul Pelajari +## Apa Yang Anda Sebenarnya Belajar -**Usaha Penalaran Mengubah Segalanya** +**Usaha Pemikiran Mengubah Segalanya** -GPT-5.2 membolehkan anda kawal usaha pengiraan melalui prompt anda. Usaha rendah bermakna respons cepat dengan penerokaan minimum. Usaha tinggi bermakna model mengambil masa untuk berfikir dengan mendalam. Anda belajar padankan usaha dengan kerumitan tugasan - jangan bazirkan masa pada soalan mudah, tapi jangan terburu-buru buat keputusan kompleks juga. +GPT-5.2 membolehkan anda mengawal usaha pengiraan melalui prompt anda. Usaha rendah bermakna respons pantas dengan penerokaan minimum. Usaha tinggi bermakna model mengambil masa untuk berfikir secara mendalam. Anda belajar untuk memadankan usaha dengan kerumitan tugas - jangan bazir masa dengan soalan mudah, tetapi jangan tergesa-gesa dalam keputusan kompleks juga. **Struktur Membimbing Tingkah Laku** -Perasan tag XML dalam prompt? Ia bukan hiasan. Model mengikuti arahan berstruktur dengan lebih boleh dipercayai daripada teks bebas. Apabila anda memerlukan proses berbilang langkah atau logik kompleks, struktur membantu model jejak di mana ia berada dan apa seterusnya. Rajah di bawah memecahkan prompt berstruktur baik, menunjukkan bagaimana tag seperti ``, ``, ``, ``, dan `` menyusun arahan anda menjadi bahagian yang jelas. +Perasan tag XML dalam prompt? Ia bukan hiasan. Model mengikuti arahan berstruktur dengan lebih boleh dipercayai berbanding teks bebas. Apabila anda memerlukan proses berbilang langkah atau logik kompleks, struktur membantu model menjejak lokasi dan apa yang seterusnya. Rajah di bawah memecahkan prompt berstruktur baik, menunjukkan bagaimana tag seperti ``, ``, ``, ``, dan `` menyusun arahan anda menjadi seksyen jelas. Struktur Prompt -*Anatomi prompt berstruktur dengan bahagian jelas dan organisasi gaya XML* +*Anatomi prompt berstruktur baik dengan seksyen jelas dan organisasi gaya XML* -**Kualiti Melalui Penilaian Diri** +**Kualiti Melalui Penilaian Kendiri** -Corak refleksi diri berfungsi dengan menjadikan kriteria kualiti eksplisit. Daripada berharap model "buat dengan betul", anda beritahu ia dengan tepat apa maksud "betul": logik tepat, pengendalian ralat, prestasi, keselamatan. Model kemudian boleh menilai output sendiri dan memperbaiki. Ini menjadikan penjanaan kod dari loteri kepada proses. +Corak refleksi diri berfungsi dengan menjadikan kriteria kualiti nyata. Daripada berharap model "melakukannya dengan betul", anda beritahu apa maksud "betul": logik tepat, pengendalian ralat, prestasi, keselamatan. Model kemudian boleh menilai keluaran sendiri dan memperbaiki. Ini menjadikan penjanaan kod satu proses, bukan loteri. -**Konteks adalah Terhad** +**Konteks Itu Terhad** -Perbualan berbilang giliran berfungsi dengan memasukkan sejarah mesej pada setiap permintaan. Tetapi ada had - setiap model ada bilangan token maksimum. Apabila perbualan berkembang, anda perlukan strategi untuk menyimpan konteks relevan tanpa mencapai had itu. Modul ini menunjukkan cara ingatan berfungsi; kemudian anda akan belajar bila untuk meringkaskan, bila untuk lupa, dan bila untuk mengambil semula. +Perbualan berbilang giliran berfungsi dengan memasukkan sejarah mesej setiap permintaan. Tapi ada had - setiap model ada had token maksimum. Apabila perbualan berkembang, anda perlukan strategi untuk mengekalkan konteks relevan tanpa melepasi had tersebut. Modul ini menunjukkan bagaimana ingatan berfungsi; kemudian anda akan belajar bila untuk meringkaskan, bila untuk melupakan, dan bila untuk mengambil semula. ## Langkah Seterusnya -**Modul Seterusnya:** [03-rag - RAG (Generasi Diperkaya Pengambilan)](../03-rag/README.md) +**Modul Seterusnya:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigasi:** [← Sebelumnya: Modul 01 - Pengenalan](../01-introduction/README.md) | [Kembali ke Utama](../README.md) | [Seterusnya: Modul 03 - RAG →](../03-rag/README.md) +**Navigasi:** [← Sebelum: Modul 01 - Pengenalan](../01-introduction/README.md) | [Kembali ke Utama](../README.md) | [Seterusnya: Modul 03 - RAG →](../03-rag/README.md) --- **Penafian**: -Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil perhatian bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber rujukan yang sahih. Untuk maklumat penting, terjemahan profesional oleh manusia adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. +Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/ms/03-rag/README.md b/translations/ms/03-rag/README.md index 06c9822d7..cc7e7c20d 100644 --- a/translations/ms/03-rag/README.md +++ b/translations/ms/03-rag/README.md @@ -2,143 +2,142 @@ ## Jadual Kandungan -- [Video Walkthrough](../../../03-rag) -- [Apa Yang Anda Akan Pelajari](../../../03-rag) -- [Prasyarat](../../../03-rag) -- [Memahami RAG](../../../03-rag) - - [Pendekatan RAG Mana Yang Digunakan Oleh Tutorial Ini?](../../../03-rag) -- [Bagaimana Ia Berfungsi](../../../03-rag) - - [Pemprosesan Dokumen](../../../03-rag) - - [Mewujudkan Embedding](../../../03-rag) - - [Carian Semantik](../../../03-rag) - - [Penjanaan Jawapan](../../../03-rag) -- [Jalankan Aplikasi](../../../03-rag) -- [Menggunakan Aplikasi](../../../03-rag) - - [Muat Naik Dokumen](../../../03-rag) - - [Tanya Soalan](../../../03-rag) - - [Semak Sumber Rujukan](../../../03-rag) - - [Eksperimen Dengan Soalan](../../../03-rag) -- [Konsep Utama](../../../03-rag) - - [Strategi Pemecahan (Chunking)](../../../03-rag) - - [Skor Kesamaan](../../../03-rag) - - [Penyimpanan Dalam Memori](../../../03-rag) - - [Pengurusan Tetingkap Konteks](../../../03-rag) -- [Bilakah RAG Penting](../../../03-rag) -- [Langkah Seterusnya](../../../03-rag) - -## Video Walkthrough - -Tonton sesi langsung ini yang menerangkan cara untuk memulakan modul ini: - -RAG with LangChain4j - Live Session - -## Apa Yang Anda Akan Pelajari - -Dalam modul-modul sebelum ini, anda telah belajar cara untuk berbual dengan AI dan menyusun prompt anda dengan berkesan. Tetapi terdapat had asas: model bahasa hanya tahu apa yang mereka pelajari semasa latihan. Mereka tidak dapat menjawab soalan mengenai polisi syarikat anda, dokumentasi projek anda, atau maklumat yang mereka tidak dilatih. - -RAG (Retrieval-Augmented Generation) menyelesaikan masalah ini. Daripada cuba mengajar model maklumat anda (yang mahal dan tidak praktikal), anda memberikannya keupayaan untuk mencari dalam dokumen anda. Apabila seseorang bertanya soalan, sistem akan mencari maklumat yang berkaitan dan menyertakannya dalam prompt. Model kemudian menjawab berdasarkan konteks yang diperoleh itu. - -Fikirkan RAG sebagai memberikan model sebuah perpustakaan rujukan. Apabila anda bertanya soalan, sistem: - -1. **Pertanyaan Pengguna** - Anda bertanya soalan -2. **Embedding** - Menukar soalan anda kepada vektor -3. **Carian Vektor** - Mencari kepingan dokumen yang serupa -4. **Penggabungan Konteks** - Menambah kepingan yang berkaitan ke dalam prompt -5. **Respons** - LLM menjana jawapan berdasarkan konteks - -Ini menjadikan respons model berasaskan data sebenar anda dan bukan bergantung pada pengetahuan latihan atau menjana jawapan rekaan. +- [Video Panduan](#video-panduan) +- [Apa yang Anda Akan Pelajari](#apa-yang-anda-akan-pelajari) +- [Prasyarat](#prasyarat) +- [Memahami RAG](#memahami-rag) + - [Pendekatan RAG Mana yang Digunakan Tutorial Ini?](#pendekatan-rag-mana-yang-digunakan-tutorial-ini) +- [Bagaimana Ia Berfungsi](#bagaimana-ia-berfungsi) + - [Pemprosesan Dokumen](#pemprosesan-dokumen) + - [Membuat Embedding](#membuat-embedding) + - [Carian Semantik](#carian-semantik) + - [Penjanaan Jawapan](#penjanaan-jawapan) +- [Jalankan Aplikasi](#jalankan-aplikasi) +- [Menggunakan Aplikasi](#menggunakan-aplikasi) + - [Muat Naik Dokumen](#muat-naik-dokumen) + - [Tanya Soalan](#tanyakan-soalan) + - [Periksa Rujukan Sumber](#semak-rujukan-sumber) + - [Eksperimen dengan Soalan](#eksperimen-dengan-soalan) +- [Konsep Utama](#konsep-utama) + - [Strategi Memecah Bahagian](#strategi-pemecahan-kepingan-chunking) + - [Skor Kesamaan](#skor-kesamaan) + - [Simpanan Dalam Memori](#penyimpanan-dalam-memori) + - [Pengurusan Tetingkap Konteks](#pengurusan-tetingkap-konteks) +- [Bila RAG Penting](#bila-rag-penting) +- [Langkah Seterusnya](#langkah-seterusnya) + +## Video Panduan + +Tonton sesi langsung ini yang menerangkan cara memulakan modul ini: + +RAG dengan LangChain4j - Sesi Langsung + +## Apa yang Anda Akan Pelajari + +Dalam modul sebelumnya, anda belajar cara berinteraksi dengan AI dan menyusun prompt anda dengan berkesan. Tetapi ada had asas: model bahasa hanya tahu apa yang mereka pelajari semasa latihan. Mereka tidak boleh menjawab soalan mengenai polisi syarikat anda, dokumentasi projek anda, atau apa-apa maklumat yang mereka tidak dilatih. + +RAG (Retrieval-Augmented Generation) menyelesaikan masalah ini. Daripada cuba mengajar model maklumat anda (yang mahal dan tidak praktikal), anda memberinya keupayaan untuk mencari dokumen anda. Apabila seseorang bertanya soalan, sistem mencari maklumat yang relevan dan memasukkannya dalam prompt. Model kemudian menjawab berdasarkan konteks yang diperoleh tersebut. + +Fikirkan RAG sebagai memberikan model perpustakaan rujukan. Apabila anda bertanya soalan, sistem: + +1. **Pertanyaan Pengguna** - Anda bertanya soalan +2. **Embedding** - Menukar soalan anda menjadi vektor +3. **Carian Vektor** - Mencari pecahan dokumen yang serupa +4. **Penyusunan Konteks** - Menambah pecahan yang relevan ke dalam prompt +5. **Respons** - LLM menjana jawapan berdasarkan konteks tersebut + +Ini menjadikan jawapan model berasaskan data sebenar anda dan bukan bergantung pada pengetahuan latihan atau mereka jawapan. ## Prasyarat -- Menyelesaikan [Modul 00 - Quick Start](../00-quick-start/README.md) (untuk contoh Easy RAG yang dirujuk kemudian dalam modul ini) -- Menyelesaikan [Modul 01 - Pengenalan](../01-introduction/README.md) (sumber Azure OpenAI telah ditempatkan, termasuk model embedding `text-embedding-3-small`) -- Fail `.env` di direktori root dengan kelayakan Azure (dicipta oleh `azd up` dalam Modul 01) +- Menyelesaikan [Modul 01 - Pengenalan](../01-introduction/README.md) (sumber Azure OpenAI telah dideploy, termasuk model embedding `text-embedding-3-small`) +- Fail `.env` dalam direktori root dengan kelayakan Azure (dibuat oleh `azd up` dalam Modul 01) -> **Nota:** Jika anda belum menyelesaikan Modul 01, ikut arahan pelaksanaan di situ dahulu. Perintah `azd up` akan melaksanakan kedua-dua model chat GPT dan model embedding yang digunakan oleh modul ini. +> **Nota:** Jika anda belum menyelesaikan Modul 01, ikuti arahan deployment di sana terlebih dahulu. Perintah `azd up` akan mendeply kedua-dua model chat GPT dan model embedding yang digunakan oleh modul ini. ## Memahami RAG -Rajah di bawah menggambarkan konsep utama: daripada bergantung hanya pada data latihan model, RAG memberikan perpustakaan rujukan dokumen anda untuk dirujuk sebelum menjana setiap jawapan. +Rajah di bawah menggambarkan konsep utama: bukannya hanya bergantung pada data latihan model, RAG memberinya perpustakaan rujukan dokumen anda untuk dirujuk sebelum menjana setiap jawapan. -What is RAG +Apa itu RAG -*Rajah ini menunjukkan perbezaan antara LLM standard (yang meneka berdasarkan data latihan) dan LLM yang diperkuat RAG (yang merujuk dokumen anda terlebih dahulu).* +*Rajah ini menunjukkan perbezaan antara LLM standard (yang membuat tekaan dari data latihan) dan LLM yang dipertingkatkan RAG (yang merujuk dokumen anda terlebih dahulu).* -Ini adalah bagaimana komponen-komponen itu bersambung dari hujung ke hujung. Soalan pengguna mengalir melalui empat peringkat — embedding, carian vektor, penggabungan konteks, dan penjanaan jawapan — setiap satu membina atas yang sebelumnya: +Berikut adalah bagaimana komponen-komponen tersebut bersambung dari hujung ke hujung. Soalan pengguna mengalir melalui empat tahap — embedding, carian vektor, penyusunan konteks, dan penjanaan jawapan — setiap satu membina berdasarkan yang sebelumnya: -RAG Architecture +Senibina RAG -*Rajah ini menunjukkan pipeline RAG dari hujung ke hujung — pertanyaan pengguna mengalir melalui embedding, carian vektor, penggabungan konteks, dan penjanaan jawapan.* +*Rajah ini menunjukkan saluran RAG dari hujung ke hujung — pertanyaan pengguna mengalir melalui embedding, carian vektor, penyusunan konteks, dan penjanaan jawapan.* -Selepas itu, modul ini menerangkan setiap peringkat secara terperinci, dengan kod yang boleh anda jalankan dan ubah suai. +Selepas ini, modul ini menerangkan setiap peringkat dengan terperinci, lengkap dengan kod yang anda boleh jalankan dan ubah suai. -### Pendekatan RAG Mana Yang Digunakan Oleh Tutorial Ini? +### Pendekatan RAG Mana yang Digunakan Tutorial Ini? -LangChain4j menawarkan tiga cara untuk melaksanakan RAG, masing-masing dengan tahap abstraksi yang berbeza. Rajah di bawah membandingkannya secara berdampingan: +LangChain4j menawarkan tiga cara untuk melaksanakan RAG, setiap satu dengan tahap abstraksi yang berbeza. Rajah di bawah membandingkannya secara sebelah menyebelah: -Three RAG Approaches in LangChain4j +Tiga Pendekatan RAG dalam LangChain4j -*Rajah ini membandingkan tiga pendekatan RAG LangChain4j — Easy, Native, dan Advanced — menunjukkan komponen utama mereka dan bila untuk menggunakan setiap satu.* +*Rajah ini membandingkan tiga pendekatan RAG LangChain4j — Mudah, Asli, dan Lanjutan — menunjukkan komponen utama mereka dan bila hendak guna setiap satu.* -| Pendekatan | Apa Yang Dilakukan | Timbangan | +| Pendekatan | Apa yang Dilakukan | Penukaran | |---|---|---| -| **Easy RAG** | Menghubungkan semuanya secara automatik melalui `AiServices` dan `ContentRetriever`. Anda mentanda sebuah antaramuka, lampirkan retriever, dan LangChain4j mengurus embedding, pencarian, dan pemasangan prompt secara belakang tabir. | Kod minimum, tetapi anda tidak nampak apa yang berlaku pada setiap langkah. | -| **Native RAG** | Anda panggil model embedding, cari stor, bina prompt, dan jana jawapan sendiri — satu langkah jelas pada satu masa. | Lebih banyak kod, tetapi setiap peringkat jelas dan boleh diubah. | -| **Advanced RAG** | Menggunakan rangka kerja `RetrievalAugmentor` dengan transformer pertanyaan boleh sambung, penentu laluan, penilaian semula, dan penyuntik kandungan untuk talian produksi. | Fleksibiliti maksimum, tetapi dengan kerumitan yang jauh lebih tinggi. | +| **Easy RAG** | Menyusun semua secara automatik melalui `AiServices` dan `ContentRetriever`. Anda anotasi antara muka, lampirkan retriever, dan LangChain4j mengendalikan embedding, carian, dan penyusunan prompt di belakang tabir. | Kod minimum, tetapi anda tidak nampak apa yang berlaku pada setiap langkah. | +| **Native RAG** | Anda memanggil model embedding, mencari stor, membina prompt, dan menjana jawapan sendiri — satu langkah eksplisit pada satu masa. | Kod lebih banyak, tetapi setiap tahap nampak dan boleh diubah suai. | +| **Advanced RAG** | Menggunakan kerangka `RetrievalAugmentor` dengan transformer pertanyaan boleh dipasang, router, re-ranker, dan content injector untuk saluran pengeluaran kelas tinggi. | Fleksibiliti maksimum, tetapi dengan kerumitan yang lebih besar. | -**Tutorial ini menggunakan pendekatan Native.** Setiap langkah pipeline RAG — embedding pertanyaan, carian stor vektor, penggabungan konteks, dan penjanaan jawapan — ditulis dengan jelas dalam [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Ini memang disengajakan: sebagai sumber pembelajaran, lebih penting anda lihat dan faham setiap peringkat daripada kod diperkecilkan. Setelah anda selesa dengan bagaimana komponen-komponen itu bersambung, anda boleh beralih ke Easy RAG untuk prototaip cepat atau Advanced RAG untuk sistem produksi. +**Tutorial ini menggunakan pendekatan Native.** Setiap langkah saluran RAG — embedding pertanyaan, mencari dalam stor vektor, menyusun konteks, dan menjana jawapan — ditulis secara jelas dalam [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Ini disengajakan: sebagai sumber pembelajaran, lebih penting anda melihat dan memahami setiap peringkat daripada mengurangkan kod. Setelah anda selesa dengan bagaimana bahagian-bahagian bersambung, anda boleh beralih ke Easy RAG untuk prototaip cepat atau Advanced RAG untuk sistem pengeluaran. -> **💡 Sudah lihat Easy RAG beraksi?** Modul [Quick Start](../00-quick-start/README.md) termasuk contoh Soal Jawab Dokumen ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) yang menggunakan pendekatan Easy RAG — LangChain4j mengendalikan embedding, pencarian, dan pemasangan prompt secara automatik. Modul ini membawa langkah seterusnya dengan membuka pipeline itu supaya anda dapat melihat dan kawal setiap peringkat sendiri. +> **💡 Tertanya-tanya tentang Easy RAG?** LangChain4j juga menawarkan pendekatan *Easy RAG* di mana `AiServices` dan `ContentRetriever` mengendalikan embedding, carian, dan penyusunan prompt secara automatik. Modul ini mengambil laluan yang lebih eksplisit — membuka saluran tersebut supaya anda boleh lihat dan kawal setiap peringkat sendiri. -Rajah di bawah menunjukkan pipeline Easy RAG daripada contoh Quick Start itu. Perhatikan bagaimana `AiServices` dan `EmbeddingStoreContentRetriever` menyembunyikan semua kerumitan — anda memuat naik dokumen, lampirkan retriever, dan dapat jawapan. Pendekatan Native dalam modul ini memecahkan setiap langkah tersembunyi itu: +Rajah di bawah menunjukkan saluran Easy RAG. Perhatikan bagaimana `AiServices` dan `EmbeddingStoreContentRetriever` menyembunyikan semua kerumitan — anda muat naik dokumen, lampirkan retriever, dan dapatkan jawapan. Pendekatan Native dalam modul ini membuka setiap langkah tersembunyi tersebut: -Easy RAG Pipeline - LangChain4j +Saluran Easy RAG - LangChain4j -*Rajah ini menunjukkan pipeline Easy RAG dari `SimpleReaderDemo.java`. Bandingkan dengan pendekatan Native yang digunakan dalam modul ini: Easy RAG menyembunyikan embedding, pengambilan, dan pemasangan prompt di belakang `AiServices` dan `ContentRetriever` — anda muat naik dokumen, lampirkan retriever, dan dapat jawapan. Pendekatan Native dalam modul ini membuka pipeline itu supaya anda panggil setiap peringkat (embed, cari, gabung konteks, jana) sendiri, memberi anda keterlihatan dan kawalan penuh.* +*Rajah ini menunjukkan saluran Easy RAG. Bandingkan dengan pendekatan Native yang digunakan dalam modul ini: Easy RAG menyembunyikan embedding, pencarian, dan penyusunan prompt di belakang `AiServices` dan `ContentRetriever` — anda muat naik dokumen, lampirkan retriever, dan terima jawapan. Pendekatan Native dalam modul ini membuka saluran tersebut supaya anda memanggil setiap peringkat (embed, cari, susun konteks, jana) sendiri, memberi anda kawalan dan keterlihatan penuh.* ## Bagaimana Ia Berfungsi -Pipeline RAG dalam modul ini terbahagi kepada empat peringkat yang dijalankan secara berurutan setiap kali pengguna bertanya soalan. Pertama, dokumen yang dimuat naik **ditafsir dan dipecah** kepada kepingan yang boleh diurus. Kepingan-kepingan itu kemudiannya ditukar menjadi **embedding vektor** dan disimpan supaya dapat dibandingkan secara matematik. Apabila pertanyaan masuk, sistem melaksanakan **carian semantik** untuk mencari kepingan yang paling relevan, dan akhirnya menggunakannya sebagai konteks kepada LLM untuk **penjanaan jawapan**. Bahagian-bahagian berikut menerangkan setiap peringkat dengan kod sebenar dan rajah. Mari lihat peringkat pertama. +Saluran RAG dalam modul ini dibahagikan kepada empat tahap yang berjalan secara berurutan setiap kali pengguna bertanya soalan. Pertama, dokumen yang dimuat naik **diparse dan dipecah** menjadi bahagian mudah urus. Bahagian-bahagian tersebut ditukar menjadi **embedding vektor** dan disimpan supaya boleh dibandingkan secara matematik. Apabila pertanyaan diterima, sistem menjalankan **carian semantik** untuk mencari bahagian paling relevan, dan akhirnya menghantar ia sebagai konteks kepada LLM untuk **penjanaan jawapan**. Bahagian-bahagian berikut membahas setiap tahap dengan kod sebenar dan rajah. Mari lihat langkah pertama. ### Pemprosesan Dokumen [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Apabila anda memuat naik dokumen, sistem akan menafsirkannya (PDF atau teks biasa), melampirkan metadata seperti nama fail, dan kemudian memecahkannya menjadi kepingan — bahagian lebih kecil yang sesuai dengan tetingkap konteks model. Kepingan itu bertindih sedikit supaya konteks penting tidak hilang di sempadan. +Apabila anda memuat naik dokumen, sistem memparsenya (PDF atau teks biasa), melampir metadata seperti nama fail, dan kemudian memecahkannya kepada bahagian kecil — pecahan yang lebih kecil yang sesuai dengan tetingkap konteks model. Bahagian ini bertindih sedikit supaya konteks pada sempadan tidak hilang. ```java -// Huraikan fail yang dimuat naik dan bungkus dalam Dokumen LangChain4j +// Huraikan fail yang dimuat naik dan bungkus ia dalam Dokumen LangChain4j Document document = Document.from(content, metadata); -// Bahagikan kepada cebisan 300-token dengan pertindihan 30-token +// Bahagikan kepada kepingan 300 token dengan tumpang tindih 30 token DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -Rajah di bawah menunjukkan bagaimana ia berfungsi secara visual. Perhatikan bagaimana setiap kepingan berkongsi sebahagian token dengan jiran-jirannya — pertindihan 30 token memastikan tiada konteks penting yang terlepas: -Document Chunking +Rajah di bawah menunjukkan bagaimana ini berfungsi secara visual. Perhatikan bagaimana setiap pecahan berkongsi beberapa token dengan jirannya — lebihan token sebanyak 30 memastikan tiada konteks penting yang hilang di antara sempadan: -*Rajah ini menunjukkan dokumen dipecah kepada kepingan 300-token dengan pertindihan 30-token, mengekalkan konteks di sempadan kepingan.* +Memecah Dokumen kepada Bahagian -> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) dan tanya: -> - "Bagaimana LangChain4j memecahkan dokumen kepada kepingan dan mengapa pertindihan penting?" -> - "Apakah saiz kepingan optimum untuk jenis dokumen yang berlainan dan kenapa?" -> - "Bagaimana saya mengendalikan dokumen dalam pelbagai bahasa atau dengan format khas?" +*Rajah ini menunjukkan dokumen dibahagi kepada pecahan 300-token dengan lebihan 30-token, mengekalkan konteks pada sempadan pecahan.* -### Mewujudkan Embedding +> **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) dan tanya: +> - "Bagaimana LangChain4j membahagi dokumen kepada bahagian dan mengapa lebihan penting?" +> - "Apakah saiz pecahan optimum untuk jenis dokumen berbeza dan mengapa?" +> - "Bagaimana saya mengendalikan dokumen pelbagai bahasa atau dengan format khas?" + +### Membuat Embedding [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Setiap kepingan ditukar menjadi representasi nombor yang dipanggil embedding — secara asasnya penukar makna kepada nombor. Model embedding bukan "cerdik" seperti model chat; ia tidak boleh ikut arahan, membuat penalaran, atau menjawab soalan. Apa yang boleh dilakukan ialah memetakan teks ke ruang matematik di mana makna yang serupa terletak berhampiran antara satu sama lain — "kereta" dekat dengan "automobil", "dasar bayaran balik" dekat dengan "pulangkan wang saya." Anggap model chat sebagai orang yang boleh anda ajak berbual; model embedding adalah sistem pengarkiban yang sangat bagus. +Setiap pecahan ditukar menjadi representasi berangka yang dipanggil embedding — secara asasnya penukar makna kepada nombor. Model embedding ini tidak "bijak" seperti model chat; ia tidak boleh mengikuti arahan, berfikir logik, atau menjawab soalan. Apa yang boleh ia lakukan adalah memetakan teks ke ruang matematik di mana makna serupa berhampiran — "kereta" berhampiran "automobil," "polisi pulangan" berhampiran "pulangkan wang saya." Fikirkan model chat sebagai orang yang anda boleh bercakap; model embedding adalah sistem fail yang sangat baik. -Rajah di bawah memvisualisasikan konsep ini — teks masuk, vektor nombor keluar, dan makna serupa menghasilkan vektor yang berhampiran: +Rajah di bawah memvisualkan konsep ini — teks masuk, vektor berangka keluar, dan makna yang serupa menghasilkan vektor berhampiran: -Embedding Model Concept +Konsep Model Embedding -*Rajah ini menunjukkan bagaimana model embedding menukar teks menjadi vektor nombor, meletakkan makna serupa — seperti "kereta" dan "automobil" — berhampiran antara satu sama lain dalam ruang vektor.* +*Rajah ini menunjukkan bagaimana model embedding menukar teks menjadi vektor berangka, meletakkan makna serupa — seperti "kereta" dan "automobil" — berhampiran satu sama lain dalam ruang vektor.* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -Rajah kelas di bawah menunjukkan dua aliran berasingan dalam pipeline RAG dan kelas LangChain4j yang melaksanakannya. **Aliran ingest** (dijalankan sekali semasa muat naik) memecahkan dokumen, menghasilkan embedding untuk kepingan, dan menyimpan melalui `.addAll()`. **Aliran pertanyaan** (dijalankan setiap kali pengguna bertanya) menghasilkan embedding untuk soalan, mencari dalam stor melalui `.search()`, dan menyerahkan konteks yang dipadankan ke model chat. Kedua-dua aliran bertemu pada antaramuka `EmbeddingStore` yang dikongsi: -LangChain4j RAG Classes +Rajah kelas di bawah menunjukkan dua aliran berasingan dalam saluran RAG dan kelas LangChain4j yang melaksanakannya. **Aliran pengambilan** (berjalan sekali ketika muat naik) memecah dokumen, membuat embedding pecahan, dan menyimpannya melalui `.addAll()`. **Aliran pertanyaan** (berjalan setiap kali pengguna bertanya) membuat embedding soalan, mencari dalam stor melalui `.search()`, dan menghantar konteks yang sesuai ke model chat. Kedua-dua aliran bertemu pada antara muka `EmbeddingStore` yang dikongsi: + +Kelas LangChain4j RAG -*Rajah ini menunjukkan dua aliran dalam pipeline RAG — ingest dan pertanyaan — dan bagaimana mereka bersambung melalui EmbeddingStore yang dikongsi.* +*Rajah ini menunjukkan dua aliran dalam saluran RAG — pengambilan dan pertanyaan — dan bagaimana mereka bersambung melalui EmbeddingStore yang dikongsi.* -Setelah embedding disimpan, kandungan serupa secara semulajadi mengelompok bersama dalam ruang vektor. Visualisasi di bawah menunjukkan bagaimana dokumen berkaitan topik berkumpul sebagai titik berdekatan, yang membolehkan carian semantik: +Setelah embedding disimpan, kandungan yang serupa secara semula jadi berkumpul dalam ruang vektor. Visualisasi di bawah menunjukkan bagaimana dokumen bertema berkaitan berakhir sebagai titik berhampiran, yang membolehkan carian semantik: -Vector Embeddings Space +Ruang Vektor Embedding -*Visualisasi ini menunjukkan bagaimana dokumen berkaitan berkumpul bersama dalam ruang vektor 3D, dengan topik seperti Dokumen Teknikal, Peraturan Perniagaan, dan Soalan Lazim membentuk kelompok berbeza.* +*Visualisasi ini menunjukkan bagaimana dokumen berkaitan berkumpul dalam ruang vektor 3D, dengan topik seperti Dokumen Teknikal, Peraturan Perniagaan, dan FAQ membentuk kumpulan berbeza.* -Apabila pengguna mencari, sistem mengikuti empat langkah: embedkan dokumen sekali sahaja, embedkan pertanyaan pada setiap carian, bandingkan vektor pertanyaan dengan semua vektor yang disimpan menggunakan persamaan kosinus, dan pulangkan top-K kepingan dengan skor tertinggi. Rajah di bawah menerangkan setiap langkah dan kelas LangChain4j yang terlibat: +Apabila pengguna mencari, sistem mengikuti empat langkah: membuat embedding dokumen sekali, membuat embedding pertanyaan setiap kali cari, membandingkan vektor pertanyaan dengan semua vektor disimpan menggunakan kesamaan kosinus, dan mengembalikan pecahan top-K dengan skor tertinggi. Rajah di bawah menerangkan setiap langkah dan kelas LangChain4j yang terlibat: -Embedding Search Steps +Langkah Carian Embedding -*Rajah ini menunjukkan empat langkah proses carian embedding: embed dokumen, embed pertanyaan, bandingkan vektor dengan persamaan kosinus, dan pulangkan hasil top-K.* +*Rajah ini menunjukkan proses carian embedding empat langkah: embed dokumen, embed pertanyaan, bandingkan vektor dengan kesamaan kosinus, dan pulangkan hasil top-K.* ### Carian Semantik [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Apabila anda bertanya soalan, soalan anda juga ditukar menjadi embedding. Sistem membandingkan embedding soalan anda dengan semua embedding kepingan dokumen. Ia mencari kepingan yang mempunyai makna paling serupa — bukan sahaja berdasarkan kata kunci yang sepadan, tetapi kesamaan semantik sebenar. +Apabila anda bertanya soalan, soalan anda juga ditukar jadi embedding. Sistem membandingkan embedding soalan anda dengan semua embedding pecahan dokumen. Ia mencari pecahan dengan makna paling serupa — bukan hanya padanan kata kunci, tetapi kesamaan semantik yang sebenar. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -Rajah di bawah membezakan carian semantik dengan carian kata kunci tradisional. Carian kata kunci untuk "vehicle" terlepas kepingan mengenai "kereta dan trak," tetapi carian semantik faham mereka bermaksud perkara yang sama dan mengembalikannya sebagai padanan skor tinggi: -Semantic Search +Rajah di bawah membezakan carian semantik dengan carian kata kunci tradisional. Carian kata kunci untuk "kenderaan" terlepas pecahan mengenai "kereta dan lori," tetapi carian semantik faham ia bermaksud sama dan mengembalikannya sebagai padanan skor tinggi: -*Rajah ini membandingkan carian berdasarkan kata kunci dengan carian semantik, menunjukkan bagaimana carian semantik mengambil kandungan berkaitan konsep walaupun kata kunci tepat berbeza.* -Di sebalik tabir, kesamaan diukur menggunakan kesamaan kosinus — secara asasnya bertanya "adakah kedua-dua anak panah ini menunjuk ke arah yang sama?" Dua potongan boleh menggunakan perkataan yang berbeza sama sekali, tetapi jika maksudnya sama, vektor mereka menunjuk ke arah yang sama dan skor hampir kepada 1.0: +Carian Semantik -Kesamaan Kosinus +*Rajah ini membandingkan carian berasaskan kata kunci dengan carian semantik, menunjukkan bagaimana carian semantik mendapat kandungan berkonsep berkaitan walaupun kata kunci sebenar berbeza.* -*Rajah ini menggambarkan kesamaan kosinus sebagai sudut antara vektor pelampaan — vektor yang lebih selari memberikan skor hampir kepada 1.0, yang menunjukkan kesamaan semantik yang lebih tinggi.* +Di belakang tabir, kesamaan diukur menggunakan kesamaan kosinus — secara asasnya bertanya "adakah dua anak panah ini menunjuk ke arah sama?" Dua pecahan boleh menggunakan perkataan berbeza sepenuhnya, tetapi jika ia bermaksud sama, vektornya akan menunjuk ke arah sama dan mendapat skor hampir 1.0: + +Kesamaan Kosinus +*Rajah ini menggambarkan kesamaan kosinus sebagai sudut antara vektor embedding — vektor yang lebih sejajar mendapat skor lebih dekat dengan 1.0, menunjukkan kesamaan semantik yang lebih tinggi.* > **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) dan tanya: -> - "Bagaimanakah carian kesamaan berfungsi dengan pelampaan dan apakah yang menentukan skor?" -> - "Apakah ambang kesamaan yang harus saya gunakan dan bagaimana ia mempengaruhi keputusan?" -> - "Bagaimana saya mengendalikan kes apabila tiada dokumen yang berkaitan ditemui?" +> - "Bagaimana caranya pencarian kesamaan menggunakan embeddings dan apa yang menentukan skor?" +> - "Apa ambang kesamaan yang harus saya gunakan dan bagaimana ia mempengaruhi hasil?" +> - "Bagaimana saya mengendalikan kes di mana tiada dokumen relevan dijumpai?" ### Penjanaan Jawapan [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Potongan paling relevan akan disusun menjadi arahan berstruktur yang merangkumi arahan eksplisit, konteks yang diperolehi, dan soalan pengguna. Model membaca potongan khusus tersebut dan menjawab berdasarkan maklumat itu — ia hanya boleh menggunakan apa yang ada di hadapannya, yang mencegah halusinasi. +Kepingan paling relevan dikumpulkan ke dalam prompt berstruktur yang merangkumi arahan eksplisit, konteks yang diperoleh, dan soalan pengguna. Model membaca kepingan khusus itu dan menjawab berdasarkan maklumat tersebut — ia hanya boleh menggunakan apa yang ada di hadapannya, yang mengelakkan halusinasi. ```java String context = matches.stream() @@ -237,47 +236,47 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Rajah di bawah menunjukkan penyusunan ini dalam tindakan — potongan dengan skor tertinggi dari langkah carian disisipkan ke dalam templat arahan, dan `OpenAiOfficialChatModel` menjana jawapan berasaskan bukti: +Rajah di bawah menunjukkan tindakan pengumpulan ini — kepingan dengan skor tertinggi dari langkah pencarian dimasukkan ke dalam templat prompt, dan `OpenAiOfficialChatModel` menjana jawapan berasaskan fakta: -Penyusunan Konteks +Context Assembly -*Rajah ini menunjukkan bagaimana potongan dengan skor tertinggi disusun menjadi arahan berstruktur, membolehkan model menjana jawapan berasaskan data anda.* +*Rajah ini menunjukkan bagaimana kepingan dengan skor tertinggi dikumpulkan ke dalam prompt berstruktur, membolehkan model menghasilkan jawapan berasaskan data anda.* ## Jalankan Aplikasi **Sahkan penyebaran:** -Pastikan fail `.env` wujud di direktori akar dengan kelayakan Azure (dibuat semasa Modul 01). Jalankan dari direktori modul (`03-rag/`): +Pastikan fail `.env` wujud di direktori akar dengan kelayakan Azure (dicipta semasa Modul 01). Jalankan ini dari direktori modul (`03-rag/`): **Bash:** ```bash -cat ../.env # Harus menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Perlu menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Perlu memaparkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Harus menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Mulakan aplikasi:** -> **Nota:** Jika anda sudah memulakan semua aplikasi menggunakan `./start-all.sh` dari direktori akar (seperti yang diterangkan dalam Modul 01), modul ini sudah berjalan di port 8081. Anda boleh abaikan arahan mula di bawah dan terus ke http://localhost:8081. +> **Nota:** Jika anda sudah memulakan semua aplikasi menggunakan `./start-all.sh` dari direktori akar (seperti yang diterangkan dalam Modul 01), modul ini sudah berjalan pada port 8081. Anda boleh langkau arahan mula di bawah dan terus ke http://localhost:8081. -**Pilihan 1: Menggunakan Spring Boot Dashboard (Disyorkan untuk pengguna VS Code)** +**Pilihan 1: Menggunakan Spring Boot Dashboard (Disarankan untuk pengguna VS Code)** -Kontena dev termasuk sambungan Spring Boot Dashboard, yang menyediakan antara muka visual untuk mengurus semua aplikasi Spring Boot. Anda boleh menemukannya di Bar Aktiviti di sebelah kiri VS Code (cari ikon Spring Boot). +Kontena pembangunan termasuk sambungan Spring Boot Dashboard, yang menyediakan antara muka visual untuk mengurus semua aplikasi Spring Boot. Anda boleh menjumpainya di Bar Aktiviti di sebelah kiri VS Code (carilah ikon Spring Boot). -Daripada Spring Boot Dashboard, anda boleh: +Dari Spring Boot Dashboard, anda boleh: - Melihat semua aplikasi Spring Boot yang tersedia dalam ruang kerja -- Mula/hentikan aplikasi dengan satu klik +- Mulakan/berhentikan aplikasi dengan satu klik - Lihat log aplikasi secara masa nyata - Pantau status aplikasi -Klik butang main di sebelah "rag" untuk mula modul ini, atau mula semua modul sekaligus. +Klik butang main di sebelah "rag" untuk memulakan modul ini, atau mulakan semua modul sekaligus. Spring Boot Dashboard -*Tangkapan skrin ini menunjukkan Spring Boot Dashboard dalam VS Code, di mana anda boleh mula, hentikan, dan pantau aplikasi secara visual.* +*Tangkapan skrin ini menunjukkan Spring Boot Dashboard di VS Code, di mana anda boleh memulakan, menghentikan, dan memantau aplikasi secara visual.* **Pilihan 2: Menggunakan skrip shell** @@ -285,7 +284,7 @@ Mulakan semua aplikasi web (modul 01-04): **Bash:** ```bash -cd .. # Dari direktori akar +cd .. # Dari direktori root ./start-all.sh ``` @@ -295,7 +294,7 @@ cd .. # Dari direktori root .\start-all.ps1 ``` -Atau mulakan hanya modul ini sahaja: +Atau mulakan hanya modul ini: **Bash:** ```bash @@ -311,7 +310,7 @@ cd 03-rag Kedua-dua skrip secara automatik memuatkan pembolehubah persekitaran dari fail `.env` akar dan akan membina JAR jika belum wujud. -> **Nota:** Jika anda lebih suka membina semua modul secara manual sebelum mula: +> **Nota:** Jika anda lebih suka membina semua modul secara manual sebelum memulakan: > > **Bash:** > ```bash @@ -325,9 +324,9 @@ Kedua-dua skrip secara automatik memuatkan pembolehubah persekitaran dari fail ` > mvn clean package -DskipTests > ``` -Buka http://localhost:8081 dalam pelayar anda. +Buka http://localhost:8081 di pelayar anda. -**Untuk hentikan:** +**Untuk berhenti:** **Bash:** ```bash @@ -345,81 +344,81 @@ cd ..; .\stop-all.ps1 # Semua modul ## Menggunakan Aplikasi -Aplikasi menyediakan antara muka web untuk muat naik dokumen dan soal jawab. +Aplikasi menyediakan antara muka web untuk muat naik dokumen dan bertanya soalan. -Antara Muka Aplikasi RAG +RAG Application Interface -*Tangkapan skrin ini menunjukkan antara muka aplikasi RAG di mana anda memuat naik dokumen dan mengemukakan soalan.* +*Tangkapan skrin ini menunjukkan antara muka aplikasi RAG di mana anda memuat naik dokumen dan bertanya soalan.* ### Muat Naik Dokumen -Mula dengan memuat naik dokumen - fail TXT paling sesuai untuk ujian. Sebuah `sample-document.txt` disediakan dalam direktori ini yang mengandungi maklumat tentang ciri LangChain4j, pelaksanaan RAG, dan amalan terbaik - sesuai untuk menguji sistem. +Mulakan dengan memuat naik dokumen - fail TXT paling sesuai untuk ujian. Fail `sample-document.txt` disediakan dalam direktori ini yang mengandungi maklumat mengenai ciri LangChain4j, pelaksanaan RAG, dan amalan terbaik - sesuai untuk menguji sistem. -Sistem memproses dokumen anda, memecahnya menjadi potongan, dan mencipta pelampaan untuk setiap potongan. Ini berlaku secara automatik apabila anda memuat naik. +Sistem memproses dokumen anda, memecahkannya kepada kepingan, dan mencipta embeddings untuk setiap kepingan. Ini berlaku secara automatik apabila anda memuat naik. ### Tanyakan Soalan -Sekarang tanya soalan khusus tentang kandungan dokumen. Cuba sesuatu yang faktual yang diterangkan dengan jelas dalam dokumen. Sistem mencari potongan yang berkaitan, memasukkannya dalam arahan, dan menjana jawapan. +Kini tanya soalan khusus tentang kandungan dokumen. Cuba sesuatu yang faktual yang dinyatakan dengan jelas dalam dokumen. Sistem mencari kepingan relevan, menyertakannya dalam prompt, dan menjana jawapan. ### Semak Rujukan Sumber -Perhatikan setiap jawapan termasuk rujukan sumber dengan skor kesamaan. Skor ini (0 hingga 1) menunjukkan betapa relevannya setiap potongan dengan soalan anda. Skor lebih tinggi bermakna padanan lebih baik. Ini membolehkan anda mengesahkan jawapan berdasarkan bahan sumber. +Perhatikan setiap jawapan termasuk rujukan sumber dengan skor kesamaan. Skor ini (0 hingga 1) menunjukkan seberapa relevan setiap kepingan terhadap soalan anda. Skor lebih tinggi bermakna padanan lebih baik. Ini membolehkan anda mengesahkan jawapan terhadap bahan sumber. -Keputusan Pertanyaan RAG +RAG Query Results -*Tangkapan skrin ini menunjukkan keputusan pertanyaan dengan jawapan yang dijana, rujukan sumber, dan skor relevansi untuk setiap potongan yang diperoleh.* +*Tangkapan skrin ini menunjukkan hasil pertanyaan dengan jawapan yang dijana, rujukan sumber, dan skor relevan untuk setiap kepingan yang diperoleh.* ### Eksperimen dengan Soalan -Cuba jenis soalan yang berbeza: -- Fakta khusus: "Apakah topik utama?" +Cuba pelbagai jenis soalan: +- Fakta spesifik: "Apakah topik utama?" - Perbandingan: "Apakah perbezaan antara X dan Y?" - Ringkasan: "Ringkaskan perkara utama tentang Z" -Perhatikan bagaimana skor relevansi berubah berdasarkan sejauh mana soalan anda padan dengan kandungan dokumen. +Perhatikan bagaimana skor relevan berubah berdasarkan seberapa baik soalan anda padan dengan kandungan dokumen. ## Konsep Utama -### Strategi Penyusunan Potongan +### Strategi Pemecahan Kepingan (Chunking) -Dokumen dibahagikan kepada potongan 300 token dengan tumpang tindih 30 token. Keseimbangan ini memastikan setiap potongan mempunyai konteks cukup untuk bermakna sambil cukup kecil untuk memasukkan beberapa potongan dalam satu arahan. +Dokumen dibahagi kepada kepingan 300-tanda dengan tumpang tindih 30 tanda. Imbangan ini memastikan setiap kepingan mempunyai cukup konteks untuk bermakna sambil kekal kecil supaya banyak kepingan boleh dimasukkan dalam prompt. ### Skor Kesamaan -Setiap potongan yang diperoleh datang dengan skor kesamaan antara 0 dan 1 yang menunjukkan betapa rapatnya ia padan dengan soalan pengguna. Rajah di bawah memvisualisasikan julat skor dan bagaimana sistem menggunakannya untuk menapis keputusan: +Setiap kepingan yang diambil datang dengan skor kesamaan antara 0 dan 1 yang menunjukkan seberapa rapat ia padan dengan soalan pengguna. Rajah di bawah memvisualisasikan julat skor dan bagaimana sistem menggunakannya untuk menapis hasil: -Skor Kesamaan +Similarity Scores -*Rajah ini menunjukkan julat skor dari 0 hingga 1, dengan ambang minimum 0.5 yang menapis potongan yang tidak relevan.* +*Rajah ini menunjukkan julat skor dari 0 hingga 1, dengan ambang minimum 0.5 yang menapis keluar kepingan yang tidak relevan.* -Skor dari 0 hingga 1: +Skor berkisar dari 0 hingga 1: - 0.7-1.0: Sangat relevan, padanan tepat - 0.5-0.7: Relevan, konteks baik -- Kurang dari 0.5: Ditapis keluar, terlalu tidak serupa +- Di bawah 0.5: Ditapis keluar, terlalu tak serupa -Sistem hanya memperoleh potongan di atas ambang minimum untuk memastikan kualiti. +Sistem hanya mengambil kepingan di atas ambang minimum untuk memastikan kualiti. -Pelampaan berfungsi dengan baik apabila makna berkumpulan dengan jelas, tetapi ia mempunyai kekurangan. Rajah di bawah menunjukkan mod kegagalan biasa — potongan yang terlalu besar menghasilkan vektor tidak jelas, potongan terlalu kecil kurang konteks, istilah kabur menunjuk kepada pelbagai kelompok, dan pencarian padanan tepat (ID, nombor bahagian) tidak berfungsi dengan pelampaan sama sekali: +Embeddings berfungsi baik apabila makna terkumpul dengan jelas, tetapi ia ada kekurangan. Rajah di bawah menunjukkan mod kegagalan biasa — kepingan yang terlalu besar menghasilkan vektor kabur, kepingan terlalu kecil kekurangan konteks, istilah samar menunjuk ke pelbagai kluster, dan carian padanan tepat (ID, nombor bahagian) langsung tidak dapat menggunakan embeddings: -Mod Kegagalan Pelampaan +Embedding Failure Modes -*Rajah ini menunjukkan mod kegagalan pelampaan biasa: potongan terlalu besar, potongan terlalu kecil, istilah kabur yang menunjuk ke beberapa kelompok, dan carian padanan tepat seperti ID.* +*Rajah ini menunjukkan mod kegagalan embedding biasa: kepingan terlalu besar, kepingan terlalu kecil, istilah samar yang menunjuk ke pelbagai kluster, dan carian padanan tepat seperti ID.* ### Penyimpanan Dalam Memori -Modul ini menggunakan penyimpanan dalam memori untuk kesederhanaan. Apabila anda mulakan semula aplikasi, dokumen yang dimuat naik akan hilang. Sistem produksi menggunakan pangkalan data vektor kekal seperti Qdrant atau Azure AI Search. +Modul ini menggunakan penyimpanan dalam memori untuk kesederhanaan. Apabila anda mulakan semula aplikasi, dokumen yang dimuat naik akan hilang. Sistem pengeluaran menggunakan pangkalan data vektor kekal seperti Qdrant atau Azure AI Search. ### Pengurusan Tetingkap Konteks -Setiap model mempunyai tetingkap konteks maksimum. Anda tidak boleh memasukkan semua potongan dari dokumen besar. Sistem memperoleh N potongan paling relevan (lalai 5) untuk kekal dalam had sambil menyediakan konteks cukup untuk jawapan tepat. +Setiap model mempunyai tetingkap konteks maksimum. Anda tidak boleh memasukkan setiap kepingan dari dokumen besar. Sistem mengambil kepingan N teratas yang paling relevan (lalai 5) untuk kekal dalam had sambil menyediakan cukup konteks untuk jawapan tepat. ## Bila RAG Penting -RAG tidak selalu pendekatan yang betul. Panduan keputusan di bawah membantu anda menentukan bila RAG menambah nilai berbanding bila pendekatan lebih mudah — seperti memasukkan kandungan terus dalam arahan atau bergantung pada pengetahuan terbina dalam model — cukup: +RAG tidak selalu kaedah yang betul. Panduan keputusan di bawah membantu anda menentukan bila RAG menambah nilai berbanding bila pendekatan lebih mudah — seperti memasukkan kandungan terus dalam prompt atau bergantung pada pengetahuan terbina dalam model — sudah mencukupi: -Bila Menggunakan RAG +When to Use RAG -*Rajah ini menunjukkan panduan keputusan untuk bila RAG menambah nilai berbanding pendekatan lebih mudah sudah mencukupi.* +*Rajah ini menunjukkan panduan keputusan bila RAG menambah nilai berbanding bila pendekatan lebih mudah sudah mencukupi.* ## Langkah Seterusnya @@ -427,11 +426,11 @@ RAG tidak selalu pendekatan yang betul. Panduan keputusan di bawah membantu anda --- -**Navigasi:** [← Sebelumnya: Modul 02 - Rekabentuk Arahan](../02-prompt-engineering/README.md) | [Kembali ke Utama](../README.md) | [Seterusnya: Modul 04 - Alat →](../04-tools/README.md) +**Navigasi:** [← Sebelumnya: Modul 02 - Kejuruteraan Prompt](../02-prompt-engineering/README.md) | [Kembali ke Utama](../README.md) | [Seterusnya: Modul 04 - Alat →](../04-tools/README.md) --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila maklum bahawa terjemahan automatik mungkin mengandungi ralat atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan profesional oleh manusia adalah disyorkan. Kami tidak bertanggungjawab atas sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/ms/04-tools/README.md b/translations/ms/04-tools/README.md index f9c7aa380..f675f5dab 100644 --- a/translations/ms/04-tools/README.md +++ b/translations/ms/04-tools/README.md @@ -1,33 +1,33 @@ # Modul 04: Ejen AI dengan Alat -## Kandungan - -- [Video Panduan](../../../04-tools) -- [Apa yang Anda Akan Pelajari](../../../04-tools) -- [Prasyarat](../../../04-tools) -- [Memahami Ejen AI dengan Alat](../../../04-tools) -- [Bagaimana Panggilan Alat Berfungsi](../../../04-tools) - - [Definisi Alat](../../../04-tools) - - [Pengambilan Keputusan](../../../04-tools) - - [Pelaksanaan](../../../04-tools) - - [Penjanaan Respons](../../../04-tools) - - [Senibina: Auto-Wiring Spring Boot](../../../04-tools) -- [Rantaian Alat](../../../04-tools) -- [Jalankan Aplikasi](../../../04-tools) -- [Menggunakan Aplikasi](../../../04-tools) - - [Cuba Penggunaan Alat Mudah](../../../04-tools) - - [Uji Rantaian Alat](../../../04-tools) - - [Lihat Aliran Perbualan](../../../04-tools) - - [Eksperimen dengan Permintaan Berbeza](../../../04-tools) -- [Konsep Utama](../../../04-tools) - - [Corak ReAct (Penalaran dan Bertindak)](../../../04-tools) - - [Deskripsi Alat Penting](../../../04-tools) - - [Pengurusan Sesi](../../../04-tools) - - [Pengendalian Ralat](../../../04-tools) -- [Alat Tersedia](../../../04-tools) -- [Bilakah Menggunakan Ejen Berasaskan Alat](../../../04-tools) -- [Alat vs RAG](../../../04-tools) -- [Langkah Seterusnya](../../../04-tools) +## Jadual Kandungan + +- [Video Panduan](#video-panduan) +- [Apa yang Anda Akan Pelajari](#apa-yang-anda-akan-pelajari) +- [Prasyarat](#prasyarat) +- [Memahami Ejen AI dengan Alat](#memahami-ejen-ai-dengan-alat) +- [Bagaimana Panggilan Alat Berfungsi](#bagaimana-panggilan-alat-berfungsi) + - [Definisi Alat](#definisi-alat) + - [Pengambilan Keputusan](#pengambilan-keputusan) + - [Pelaksanaan](#pelaksanaan) + - [Penciptaan Respons](#penciptaan-respons) + - [Seni Bina: Auto-Wiring Spring Boot](#seni-bina-auto-wiring-spring-boot) +- [Rantaian Alat](#rantaian-alat) +- [Jalankan Aplikasi](#jalankan-aplikasi) +- [Menggunakan Aplikasi](#menggunakan-aplikasi) + - [Cuba Penggunaan Alat Ringkas](#cuba-penggunaan-alat-mudah) + - [Uji Rantaian Alat](#uji-rantaian-alat) + - [Lihat Aliran Perbualan](#lihat-aliran-perbualan) + - [Eksperimen dengan Permintaan Berbeza](#cuba-permintaan-berbeza) +- [Konsep Utama](#konsep-utama) + - [Corak ReAct (Berfikir dan Bertindak)](#corak-react-penalaran-dan-tindakan) + - [Penerangan Alat Penting](#penerangan-alat-penting) + - [Pengurusan Sesi](#pengurusan-sesi) + - [Pengendalian Ralat](#pengendalian-ralat) +- [Alat yang Tersedia](#alat-tersedia) +- [Bila Menggunakan Ejen Berasaskan Alat](#bila-perlu-guna-ejen-berasaskan-alat) +- [Alat vs RAG](#alat-vs-rag) +- [Langkah Seterusnya](#langkah-seterusnya) ## Video Panduan @@ -37,40 +37,40 @@ Tonton sesi langsung ini yang menerangkan cara memulakan modul ini: ## Apa yang Anda Akan Pelajari -Sehingga kini, anda telah belajar bagaimana untuk berkomunikasi dengan AI, menyusun arahan dengan berkesan, dan menjadikan respons berasaskan dokumen anda. Tetapi masih ada kekangan asas: model bahasa hanya boleh menghasilkan teks. Ia tidak boleh memeriksa cuaca, melakukan pengiraan, membuat pertanyaan pangkalan data, atau berinteraksi dengan sistem luaran. +Setakat ini, anda telah belajar bagaimana mengadakan perbualan dengan AI, menyusun prompt dengan berkesan, dan mengikat respons dalam dokumen anda. Tetapi masih terdapat had asas: model bahasa hanya boleh menjana teks. Ia tidak boleh menyemak cuaca, melakukan pengiraan, membuat pertanyaan pangkalan data, atau berinteraksi dengan sistem luaran. -Alat mengubah ini. Dengan memberikan model akses kepada fungsi yang boleh ia panggil, anda menukar ia daripada penjana teks kepada ejen yang boleh mengambil tindakan. Model memutuskan bila ia memerlukan alat, alat mana yang hendak digunakan, dan parameter apa yang perlu dihantar. Kod anda melaksanakan fungsi itu dan mengembalikan hasil. Model memasukkan hasil tersebut ke dalam responsnya. +Alat mengubah ini. Dengan memberi model akses kepada fungsi yang boleh dipanggil, anda menukarnya dari penjana teks menjadi ejen yang boleh bertindak. Model menentukan bila ia memerlukan alat, alat mana yang akan digunakan, dan parameter apa untuk dihantar. Kod anda melaksanakan fungsi itu dan memulangkan hasilnya. Model menggabungkan hasil itu ke dalam responsnya. ## Prasyarat -- Telah menyiapkan [Modul 01 - Pengenalan](../01-introduction/README.md) (sumber Azure OpenAI telah diterapkan) -- Disyorkan telah melengkapkan modul-modul sebelumnya (modul ini merujuk [konsep RAG dari Modul 03](../03-rag/README.md) dalam perbandingan Alat vs RAG) -- Fail `.env` di direktori utama dengan kredensial Azure (dicipta oleh `azd up` dalam Modul 01) +- Telah menyelesaikan [Modul 01 - Pengenalan](../01-introduction/README.md) (sumber Azure OpenAI telah dikerahkan) +- Modul terdahulu disyorkan diselesaikan (modul ini merujuk [konsep RAG dari Modul 03](../03-rag/README.md) dalam perbandingan Alat vs RAG) +- Fail `.env` di direktori akar dengan kredensial Azure (dicipta oleh `azd up` dalam Modul 01) -> **Nota:** Jika anda belum menyiapkan Modul 01, ikut arahan penerapan di sana dahulu. +> **Nota:** Jika anda belum menyelesaikan Modul 01, ikuti arahan penerapan di sana terlebih dahulu. ## Memahami Ejen AI dengan Alat -> **📝 Nota:** Istilah "ejen" dalam modul ini merujuk kepada pembantu AI yang dipertingkatkan dengan kemampuan memanggil alat. Ini berbeza dari pola **Agentic AI** (ejen autonomi dengan perancangan, memori, dan penalaran berlapis-lapis) yang akan kami bahas dalam [Modul 05: MCP](../05-mcp/README.md). +> **📝 Nota:** Istilah "ejen" dalam modul ini merujuk kepada pembantu AI yang dipertingkatkan dengan kemampuan panggilan alat. Ini berbeza dengan corak **Agentic AI** (ejen autonomi dengan perancangan, ingatan, dan penaakulan berbilang langkah) yang akan kita bincangkan dalam [Modul 05: MCP](../05-mcp/README.md). -Tanpa alat, model bahasa hanya boleh menghasilkan teks daripada data latihannya. Tanyakan cuaca semasa, dan ia terpaksa meneka. Berikan ia alat, dan ia boleh memanggil API cuaca, melakukan pengiraan, atau bertanya pangkalan data — kemudian membina hasil sebenar itu ke dalam responsnya. +Tanpa alat, model bahasa hanya boleh menjana teks berdasarkan data latihannya. Tanya cuaca semasa, ia terpaksa mengagak. Beri alat, ia boleh memanggil API cuaca, melakukan pengiraan, atau bertanya pangkalan data — kemudian mengaitkan keputusan sebenar itu ke dalam responsnya. Tanpa Alat vs Dengan Alat -*Tanpa alat model hanya boleh meneka — dengan alat ia boleh memanggil API, menjalankan pengiraan, dan mengembalikan data masa nyata.* +*Tanpa alat model hanya mengagak — dengan alat ia boleh memanggil API, menjalankan pengiraan, dan memulangkan data masa nyata.* -Ejen AI dengan alat mengikuti corak **Reasoning and Acting (ReAct)**. Model tidak hanya membalas — ia berfikir apa yang diperlukan, bertindak dengan memanggil alat, memerhati hasil, kemudian memutuskan sama ada hendak bertindak lagi atau menyampaikan jawapan akhir: +Ejen AI dengan alat mengikuti corak **Berfikir dan Bertindak (ReAct)**. Model bukan sekadar memberi respons — ia memikirkan apa yang diperlukan, bertindak dengan memanggil alat, memerhati hasil, dan kemudian memutuskan sama ada bertindak lagi atau memberikan jawapan akhir: 1. **Berfikir** — Ejen menganalisis soalan pengguna dan menentukan maklumat yang diperlukan 2. **Bertindak** — Ejen memilih alat yang tepat, menjana parameter yang betul, dan memanggilnya -3. **Memerhati** — Ejen menerima output alat dan menilai hasil -4. **Ulang atau Balas** — Jika data lebih diperlukan, ejen mengulangi; jika tidak, ia menyusun jawapan bahasa semula jadi +3. **Memerhati** — Ejen menerima output alat dan menilai hasilnya +4. **Ulang atau Respons** — Jika data lebih diperlukan, ejen mengulangi; jika tidak, ia menyusun jawapan dalam bahasa semula jadi Corak ReAct -*Kitaran ReAct — ejen berfikir tentang apa yang perlu dilakukan, bertindak dengan memanggil alat, memerhati hasil, dan mengulangi sehingga dapat memberikan jawapan akhir.* +*Kitaran ReAct — ejen berfikir tentang apa yang perlu dilakukan, bertindak dengan memanggil alat, memerhati hasil, dan mengulangi sehingga boleh memberikan jawapan akhir.* -Ini berlaku secara automatik. Anda tetapkan alat dan deskripsinya. Model mengendalikan pengambilan keputusan bila dan bagaimana untuk menggunakannya. +Ini berlaku secara automatik. Anda mentakrifkan alat dan penerangannya. Model mengurus pengambilan keputusan bila dan bagaimana menggunakannya. ## Bagaimana Panggilan Alat Berfungsi @@ -78,7 +78,7 @@ Ini berlaku secara automatik. Anda tetapkan alat dan deskripsinya. Model mengend [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Anda mentakrifkan fungsi dengan deskripsi jelas dan spesifikasi parameter. Model melihat deskripsi ini dalam sistem arahan dan memahami apa yang setiap alat lakukan. +Anda mentakrifkan fungsi dengan penerangan jelas dan spesifikasi parameter. Model melihat penerangan ini dalam prompt sistemnya dan memahami apa yang dilakukan oleh setiap alat. ```java @Component @@ -96,135 +96,135 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Pembantu disambungkan secara automatik oleh Spring Boot dengan: +// Pembantu secara automatik dihubungkan oleh Spring Boot dengan: // - Bean ChatModel // - Semua kaedah @Tool dari kelas @Component // - ChatMemoryProvider untuk pengurusan sesi ``` -Rajah di bawah memecahkan setiap anotasi dan menunjukkan bagaimana setiap bahagiannya membantu AI memahami bila untuk memanggil alat dan argumen apa yang hendak diberi: +Rajah di bawah memperincikan setiap anotasi dan menunjukkan bagaimana setiap bahagian membantu AI memahami bila untuk memanggil alat dan argumen apa yang perlu dihantar: Anatomi Definisi Alat -*Anatomi definisi alat — @Tool memberitahu AI bila menggunakannya, @P menerangkan setiap parameter, dan @AiService menghubungkan semuanya semasa permulaan.* +*Anatomi definisi alat — @Tool memberitahu AI bila menggunakannya, @P menerangkan setiap parameter, dan @AiService menghubungkan semuanya semasa startup.* > **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) dan tanya: -> - "Bagaimana saya boleh mengintegrasi API cuaca sebenar seperti OpenWeatherMap berbanding data rekaan?" -> - "Apa yang menjadikan deskripsi alat baik yang membantu AI menggunakannya dengan betul?" +> - "Bagaimana saya mengintegrasikan API cuaca sebenar seperti OpenWeatherMap menggantikan data tiruan?" +> - "Apakah yang menjadikan penerangan alat yang baik supaya AI menggunakannya dengan betul?" > - "Bagaimana saya mengendalikan ralat API dan had kadar dalam pelaksanaan alat?" ### Pengambilan Keputusan -Apabila pengguna bertanya "Bagaimana cuaca di Seattle?", model tidak memilih alat secara rawak. Ia membandingkan niat pengguna dengan setiap deskripsi alat yang boleh diakses, menilai setiap satu dari segi kaitan, dan memilih yang paling sesuai. Kemudian ia menjana panggilan fungsi berstruktur dengan parameter yang betul — dalam kes ini, menetapkan `location` kepada `"Seattle"`. +Apabila pengguna bertanya "Bagaimana cuaca di Seattle?", model tidak memilih alat secara rawak. Ia membandingkan niat pengguna dengan setiap penerangan alat yang ada, memberikan skor kepentingan, dan memilih padanan terbaik. Model kemudian menjana panggilan fungsi berstruktur dengan parameter tepat — dalam kes ini, menetapkan `location` kepada `"Seattle"`. -Jika tiada alat yang sesuai dengan permintaan pengguna, model akan menjawab berdasarkan pengetahuannya sendiri. Jika beberapa alat sesuai, ia memilih yang paling spesifik. +Jika tiada alat sesuai dengan permintaan pengguna, model kembali menjawab berdasarkan pengetahuannya sendiri. Jika beberapa alat sesuai, ia memilih yang paling khusus. -Bagaimana AI Memutuskan Alat Yang Digunakan +Bagaimana AI Memutuskan Alat Mana untuk Digunakan -*Model menilai setiap alat tersedia mengikut niat pengguna dan memilih padanan terbaik — sebab itulah penulisan deskripsi alat yang jelas dan spesifik adalah penting.* +*Model menilai setiap alat tersedia berbanding niat pengguna dan memilih padanan terbaik — sebab itulah menulis penerangan alat yang jelas dan spesifik adalah penting.* ### Pelaksanaan [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot secara automatik menghubungkan antara muka deklaratif `@AiService` dengan semua alat yang didaftarkan, dan LangChain4j melaksanakan panggilan alat secara automatik. Di belakang tabir, satu panggilan alat lengkap mengalir melalui enam tahap — dari soalan bahasa semula jadi pengguna hingga ke jawapan bahasa semula jadi: +Spring Boot auto-wire antara muka deklaratif `@AiService` dengan semua alat berdaftar, dan LangChain4j melaksanakan panggilan alat secara automatik. Di belakang tabir, panggilan alat lengkap melalui enam peringkat — dari soalan bahasa semula jadi pengguna kembali ke jawapan bahasa semula jadi: Aliran Panggilan Alat -*Aliran hujung-ke-hujung — pengguna bertanya soalan, model memilih alat, LangChain4j melaksanakannya, dan model menggabungkan hasil ke dalam respons alami.* +*Aliran hujung ke hujung — pengguna bertanya soalan, model memilih alat, LangChain4j melaksanakan, dan model menganyam hasilnya ke dalam respons semula jadi.* -Jika anda menjalankan [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) dalam Modul 00, anda sudah melihat corak ini berfungsi — alat `Calculator` dipanggil dengan cara yang sama. Rajah urutan di bawah menunjukkan dengan tepat apa yang berlaku di belakang tabir semasa demo itu: +Di belakang tabir, `AiServices` menjalankan gelung panggilan alat yang sama untuk mana-mana alat — di sini digambarkan dengan `Calculator` yang ringkas. Rajah susunan di bawah menunjukkan dengan tepat apa yang berlaku di belakang tabir: -Rajah Urutan Panggilan Alat +Rajah Susunan Panggilan Alat -*Kitaran panggilan alat dari demo Permulaan Pantas — `AiServices` menghantar mesej anda dan skema alat kepada LLM, LLM membalas dengan panggilan fungsi seperti `add(42, 58)`, LangChain4j melaksanakan kaedah `Calculator` secara setempat, dan memberi keputusan kembali untuk jawapan akhir.* +*Gulung panggilan alat — `AiServices` menghantar mesej anda dan skema alat ke LLM, LLM membalas dengan panggilan fungsi seperti `add(42, 58)`, LangChain4j melaksanakan metod `Calculator` secara tempatan, dan memulangkan hasil untuk jawapan akhir.* > **🤖 Cuba dengan [GitHub Copilot](https://github.com/features/copilot) Chat:** Buka [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) dan tanya: -> - "Bagaimana corak ReAct berfungsi dan kenapa ia berkesan untuk ejen AI?" -> - "Bagaimana ejen menentukan alat mana untuk digunakan dan dalam susunan apa?" -> - "Apa yang berlaku jika pelaksanaan alat gagal - bagaimana saya harus mengendalikan ralat dengan kukuh?" +> - "Bagaimana corak ReAct berfungsi dan mengapa ia berkesan untuk ejen AI?" +> - "Bagaimana ejen menentukan alat mana yang hendak digunakan dan dalam susunan apa?" +> - "Apa yang berlaku jika pelaksanaan alat gagal - bagaimana saya hendak mengendalikan ralat secara kukuh?" -### Penjanaan Respons +### Penciptaan Respons -Model menerima data cuaca dan memformatkannya menjadi respons bahasa semula jadi untuk pengguna. +Model menerima data cuaca dan memformatnya ke dalam respons bahasa semula jadi untuk pengguna. -### Senibina: Auto-Wiring Spring Boot +### Seni Bina: Auto-Wiring Spring Boot -Modul ini menggunakan integrasi LangChain4j dengan Spring Boot dengan antara muka deklaratif `@AiService`. Semasa permulaan, Spring Boot mengesan setiap `@Component` yang mengandungi kaedah `@Tool`, bean `ChatModel` anda, dan `ChatMemoryProvider` — kemudian menghubungkan semuanya ke dalam satu antara muka `Assistant` tanpa kod boilerplate. +Modul ini menggunakan integrasi Spring Boot LangChain4j dengan antara muka deklaratif `@AiService`. Semasa startup, Spring Boot menemui setiap `@Component` yang mengandungi metod `@Tool`, bean `ChatModel` anda, dan `ChatMemoryProvider` — kemudian menghubungkannya semuanya ke dalam satu antara muka `Assistant` tanpa sebarang kod boilerplate. -Senibina Auto-Wiring Spring Boot +Seni Bina Auto-Wiring Spring Boot -*Antara muka @AiService menghubungkan ChatModel, komponen alat, dan penyedia memori — Spring Boot mengendalikan semua sambungan secara automatik.* +*Antara muka @AiService mengikat bersama ChatModel, komponen alat, dan penyedia memori — Spring Boot menguruskan semua wiring secara automatik.* -Berikut adalah hayat permintaan penuh sebagai rajah urutan — dari permintaan HTTP melalui pengawal, perkhidmatan, dan proksi auto-wired, sehingga pelaksanaan alat dan kembali: +Berikut adalah kitaran hidup permintaan penuh sebagai rajah susunan — dari permintaan HTTP melalui controller, service, dan proksi auto-wired, hingga pelaksanaan alat dan kembali: -Rajah Urutan Panggilan Alat Spring Boot +Susunan Panggilan Alat Spring Boot -*Hayat permintaan lengkap Spring Boot — permintaan HTTP mengalir melalui pengawal dan perkhidmatan ke proksi Assistant auto-wired, yang mengatur LLM dan panggilan alat secara automatik.* +*Kitaran hidup permintaan Spring Boot lengkap — permintaan HTTP mengalir melalui controller dan service ke proksi Assistant auto-wired, yang mengatur LLM dan panggilan alat secara automatik.* -Manfaat utama kaedah ini: +Manfaat utama pendekatan ini: -- **Auto-wiring Spring Boot** — ChatModel dan alat dimasukkan secara automatik -- **Corak @MemoryId** — Pengurusan memori berasaskan sesi automatik -- **Satu contoh** — Assistant dicipta sekali dan digunakan semula untuk prestasi lebih baik -- **Pelaksanaan type-safe** — Kaedah Java dipanggil terus dengan penukaran jenis -- **Orkestrasi pelbagai giliran** — Mengendalikan rantaian alat secara automatik +- **Auto-wiring Spring Boot** — ChatModel dan alat disuntik secara automatik +- **Corak @MemoryId** — Pengurusan memori berasaskan sesi secara automatik +- **Instans tunggal** — Assistant dicipta sekali dan digunakan semula untuk prestasi lebih baik +- **Pelaksanaan selamat jenis** — Metod Java dipanggil terus dengan penukaran jenis +- **Orkestrasi berbilang giliran** — Mengawal rantaian alat secara automatik - **Tiada boilerplate** — Tiada panggilan manual `AiServices.builder()` atau HashMap memori -Pendekatan alternatif (manual `AiServices.builder()`) memerlukan kod lebih banyak dan tidak mendapat manfaat integrasi Spring Boot. +Pendekatan alternatif (manual `AiServices.builder()`) memerlukan lebih banyak kod dan tidak mendapat manfaat integrasi Spring Boot. ## Rantaian Alat -**Rantaian Alat** — Kuasa sebenar ejen berasaskan alat muncul apabila satu soalan memerlukan beberapa alat. Tanyakan "Bagaimana cuaca di Seattle dalam Fahrenheit?" dan ejen secara automatik mengaitkan dua alat: pertama ia memanggil `getCurrentWeather` untuk dapatkan suhu dalam Celsius, kemudian ia menghantar nilai itu ke `celsiusToFahrenheit` untuk penukaran — semua dalam satu giliran perbualan. +**Rantaian Alat** — Kuasa sebenar ejen berasaskan alat muncul apabila satu soalan memerlukan pelbagai alat. Tanya "Bagaimana cuaca di Seattle dalam Fahrenheit?" dan ejen secara automatik menyambungkan dua alat: pertama ia memanggil `getCurrentWeather` untuk mendapatkan suhu dalam Celsius, kemudian menghantar nilai itu ke `celsiusToFahrenheit` untuk penukaran — semuanya dalam satu giliran perbualan. Contoh Rantaian Alat -*Rantaian alat dalam tindakan — ejen memanggil getCurrentWeather terlebih dahulu, kemudian menyalurkan hasil Celsius ke celsiusToFahrenheit, dan memberikan jawapan gabungan.* +*Rantaian alat dalam tindakan — ejen memanggil getCurrentWeather dahulu, kemudian menyalurkan hasil Celsius ke celsiusToFahrenheit, dan memberikan jawapan gabungan.* -**Kegagalan Yang Sopan** — Minta cuaca di bandar yang tiada dalam data rekaan. Alat mengembalikan mesej ralat, dan AI menerangkan yang ia tidak dapat membantu daripada aplikasi crash. Alat gagal dengan selamat. Rajah di bawah membezakan dua pendekatan — dengan pengendalian ralat yang betul, ejen menangkap pengecualian dan memberi respons yang membantu, tanpa itu aplikasi keseluruhan crash: +**Kegagalan Anggun** — Tanya cuaca di bandar yang tiada dalam data tiruan. Alat memulangkan mesej ralat, dan AI menerangkan ia tidak boleh membantu daripada aplikasi terhenti. Alat gagal dengan selamat. Rajah di bawah membezakan dua pendekatan — dengan pengendalian ralat yang betul, ejen menangkap pengecualian dan menjawab dengan bantuan, manakala tanpa ia aplikasi keseluruhan terhenti: Aliran Pengendalian Ralat -*Apabila alat gagal, ejen menangkap ralat dan memberikan penjelasan berguna daripada aplikasi crash.* +*Apabila alat gagal, ejen menangkap ralat dan memberi penjelasan berguna berbanding aplikasi yang terhenti.* -Ini berlaku dalam satu giliran perbualan. Ejen mengatur banyak panggilan alat secara autonomi. +Ini berlaku dalam satu giliran perbualan. Ejen mengatur panggilan pelbagai alat secara autonomi. ## Jalankan Aplikasi **Sahkan penerapan:** -Pastikan fail `.env` wujud di direktori utama dengan kredensial Azure (dicipta semasa Modul 01). Jalankan ini dari direktori modul (`04-tools/`): +Pastikan fail `.env` wujud di direktori akar dengan kredensial Azure (dicipta semasa Modul 01). Jalankan ini dari direktori modul (`04-tools/`): **Bash:** ```bash -cat ../.env # Harus menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Patut menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Harus menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Patut menunjukkan AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Mulakan aplikasi:** -> **Nota:** Jika anda sudah memulakan semua aplikasi menggunakan `./start-all.sh` dari direktori utama (seperti yang diterangkan dalam Modul 01), modul ini sudah berjalan pada port 8084. Anda boleh langkau arahan mulakan di bawah dan pergi terus ke http://localhost:8084. +> **Nota:** Jika anda sudah memulakan semua aplikasi menggunakan `./start-all.sh` dari direktori akar (seperti yang diterangkan dalam Modul 01), modul ini sudah berjalan di port 8084. Anda boleh langkau arahan mula di bawah dan terus ke http://localhost:8084. **Pilihan 1: Menggunakan Spring Boot Dashboard (Disyorkan untuk pengguna VS Code)** -Kontena pembangunan termasuk pelanjutan Spring Boot Dashboard, yang menyediakan antara muka visual untuk mengurus semua aplikasi Spring Boot. Anda boleh mencarinya di Bar Aktiviti di sebelah kiri VS Code (cari ikon Spring Boot). +Bekas pembangunan (dev container) menyertakan peluasan Spring Boot Dashboard, yang menyediakan antaramuka visual untuk mengurus semua aplikasi Spring Boot. Anda boleh menjumpainya di Bar Aktiviti di sebelah kiri VS Code (cari ikon Spring Boot). Daripada Spring Boot Dashboard, anda boleh: -- Melihat semua aplikasi Spring Boot tersedia dalam ruang kerja -- Mulakan/henti aplikasi dengan satu klik -- Lihat log aplikasi secara masa nyata -- Pantau status aplikasi -Klik sahaja butang main di sebelah "tools" untuk memulakan modul ini, atau mulakan semua modul sekaligus. +- Melihat semua aplikasi Spring Boot yang tersedia dalam workspace +- Mula/berhenti aplikasi dengan satu klik +- Melihat log aplikasi secara masa nyata +- Memantau status aplikasi -Ini rupa Spring Boot Dashboard dalam VS Code: +Cukup klik butang main di sebelah "tools" untuk memulakan modul ini, atau mulakan semua modul sekaligus. -Spring Boot Dashboard +Ini rupa Spring Boot Dashboard dalam VS Code: +Papan Pemuka Spring Boot -*Spring Boot Dashboard dalam VS Code — mulakan, hentikan, dan pantau semua modul dari satu tempat* +*Papan Pemuka Spring Boot dalam VS Code — mula, berhenti, dan pantau semua modul dari satu tempat* **Pilihan 2: Menggunakan skrip shell** @@ -232,17 +232,17 @@ Mulakan semua aplikasi web (modul 01-04): **Bash:** ```bash -cd .. # Dari direktori akar +cd .. # Dari direktori root ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Dari direktori akar +cd .. # Dari direktori root .\start-all.ps1 ``` -Atau mulakan hanya modul ini: +Atau mulakan modul ini sahaja: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Kedua-dua skrip secara automatik memuatkan pemboleh ubah persekitaran dari fail `.env` akar dan akan membina JAR jika ia tidak wujud. +Kedua-dua skrip secara automatik memuatkan pembolehubah persekitaran dari fail `.env` di akar dan akan membina JAR jika ia tidak wujud. -> **Nota:** Jika anda lebih suka membina semua modul secara manual sebelum memulakan: +> **Nota:** Jika anda lebih suka membina semua modul secara manual sebelum mula: > > **Bash:** > ```bash @@ -272,9 +272,9 @@ Kedua-dua skrip secara automatik memuatkan pemboleh ubah persekitaran dari fail > mvn clean package -DskipTests > ``` -Buka http://localhost:8084 dalam pelayar web anda. +Buka http://localhost:8084 dalam pelayar anda. -**Untuk hentikan:** +**Untuk berhenti:** **Bash:** ```bash @@ -292,88 +292,88 @@ cd ..; .\stop-all.ps1 # Semua modul ## Menggunakan Aplikasi -Aplikasi ini menyediakan antara muka web di mana anda boleh berinteraksi dengan ejen AI yang mempunyai akses kepada alat cuaca dan penukaran suhu. Ini rupa antara mukanya — ia termasuk contoh permulaan pantas dan panel sembang untuk menghantar permintaan: +Aplikasi ini menyediakan antara muka web di mana anda boleh berinteraksi dengan ejen AI yang mempunyai akses kepada alat cuaca dan penukaran suhu. Inilah rupa antara muka itu — ia termasuk contoh permulaan cepat dan panel sembang untuk menghantar permintaan: -AI Agent Tools Interface +Antara Muka Alat Ejen AI -*Antara muka Alat Ejen AI - contoh pantas dan antara muka sembang untuk berinteraksi dengan alat* +*Antara Muka Alat Ejen AI - contoh pantas dan antara muka sembang untuk berinteraksi dengan alat* ### Cuba Penggunaan Alat Mudah -Mulakan dengan permintaan mudah: "Tukar 100 darjah Fahrenheit ke Celsius". Ejen mengenali ia memerlukan alat penukaran suhu, memanggilnya dengan parameter yang betul, dan mengembalikan hasilnya. Perhatikan betapa semulajadinya ini dirasakan - anda tidak menyatakan alat mana yang hendak digunakan atau bagaimana memanggilnya. +Mulakan dengan permintaan mudah: "Tukar 100 darjah Fahrenheit kepada Celsius". Ejen mengenal pasti ia memerlukan alat penukaran suhu, memanggilnya dengan parameter yang betul, dan mengembalikan hasilnya. Perhatikan betapa semulajadinya ini - anda tidak menentukan alat mana yang perlu digunakan atau bagaimana memanggilnya. ### Uji Rantaian Alat -Sekarang cuba sesuatu yang lebih kompleks: "Cuaca di Seattle dan tukar ke Fahrenheit?" Perhatikan ejen melakukan ini secara langkah demi langkah. Pertama ia mendapat cuaca (yang mengembalikan Celsius), mengenal pasti ia perlu menukar ke Fahrenheit, memanggil alat penukaran, dan menggabungkan kedua-dua hasil ke satu jawapan. +Sekarang cuba sesuatu yang lebih kompleks: "Apa cuaca di Seattle dan tukar ke Fahrenheit?" Tonton ejen melaluinya secara berperingkat. Ia mula-mula mendapatkan cuaca (yang mengembalikan Celsius), mengenal pasti ia perlu menukar ke Fahrenheit, memanggil alat penukaran, dan menggabungkan kedua-dua hasil menjadi satu respons. ### Lihat Aliran Perbualan -Antara muka sembang mengekalkan sejarah perbualan, membolehkan anda mempunyai interaksi berbilang giliran. Anda boleh melihat semua pertanyaan dan jawapan terdahulu, menjadikannya mudah untuk mengesan perbualan dan memahami bagaimana ejen membina konteks dalam beberapa pertukaran. +Antara muka sembang mengekalkan sejarah perbualan, membolehkan anda mempunyai interaksi berturutan. Anda boleh melihat semua pertanyaan dan jawapan sebelumnya, memudahkan menjejak perbualan dan memahami bagaimana ejen membina konteks dalam beberapa pertukaran. -Conversation with Multiple Tool Calls +Perbualan dengan Pelbagai Panggilan Alat -*Perbualan berbilang giliran menunjukkan penukaran mudah, semakan cuaca, dan rantaian alat* +*Perbualan berturutan menunjukkan penukaran mudah, carian cuaca, dan rantaian alat* -### Eksperimen dengan Permintaan Berbeza +### Cuba Permintaan Berbeza Cuba pelbagai gabungan: -- Semakan cuaca: "Cuaca di Tokyo?" -- Penukaran suhu: "Berapa 25°C dalam Kelvin?" -- Pertanyaan gabungan: "Periksa cuaca di Paris dan beritahu jika suhu melebihi 20°C" +- Carian cuaca: "Apa cuaca di Tokyo?" +- Penukaran suhu: "Berapakah 25°C dalam Kelvin?" +- Pertanyaan gabungan: "Semak cuaca di Paris dan beritahu saya jika melebihi 20°C" -Perhatikan bagaimana ejen mentafsir bahasa semulajadi dan memetakan kepada panggilan alat yang sesuai. +Perhatikan bagaimana ejen mentafsir bahasa semula jadi dan memetakannya kepada panggilan alat yang sesuai. ## Konsep Utama -### Corak ReAct (Berfikir dan Bertindak) +### Corak ReAct (Penalaran dan Tindakan) -Ejen bergilir-gilir antara berfikir (memutuskan apa yang perlu dilakukan) dan bertindak (menggunakan alat). Corak ini membolehkan penyelesaian masalah secara autonomi dan bukan sekadar bertindak balas kepada arahan. +Ejen bergilir-gilir antara penalaran (memutuskan apa yang perlu dilakukan) dan tindakan (menggunakan alat). Corak ini membolehkan penyelesaian masalah secara autonomi dan bukan sekadar membalas arahan. ### Penerangan Alat Penting -Kualiti penerangan alat anda secara langsung mempengaruhi betapa baiknya ejen menggunakannya. Penerangan yang jelas dan khusus membantu model memahami bila dan bagaimana untuk memanggil setiap alat. +Kualiti penerangan alat anda secara langsung mempengaruhi bagaimana ejen menggunakannya. Penerangan jelas dan spesifik membantu model memahami bila dan bagaimana memanggil setiap alat. ### Pengurusan Sesi -Anotasi `@MemoryId` membolehkan pengurusan ingatan berasaskan sesi secara automatik. Setiap ID sesi mendapat instans `ChatMemory` sendiri yang diuruskan oleh bean `ChatMemoryProvider`, supaya pelbagai pengguna boleh berinteraksi dengan ejen serentak tanpa perbualan mereka bercampur. Rajah berikut menunjukkan bagaimana pelbagai pengguna diarahkan ke stor ingatan yang terasing berdasarkan ID sesi mereka: +Anotasi `@MemoryId` membolehkan pengurusan memori berasaskan sesi secara automatik. Setiap ID sesi mendapat contoh `ChatMemory` sendiri yang diuruskan oleh bean `ChatMemoryProvider`, jadi pelbagai pengguna boleh berinteraksi dengan ejen secara serentak tanpa perbualan mereka bercampur. Rajah berikut menunjukkan bagaimana pelbagai pengguna dihala ke stor memori yang terasing berdasarkan ID sesi mereka: -Session Management with @MemoryId +Pengurusan Sesi dengan @MemoryId -*Setiap ID sesi memetakan kepada sejarah perbualan yang terasing — pengguna tidak pernah melihat mesej antara satu sama lain.* +*Setiap ID sesi dipetakan kepada sejarah perbualan yang terasing — pengguna tidak pernah melihat mesej antara satu sama lain.* -### Pengurusan Ralat +### Pengendalian Ralat -Alat boleh gagal — API tamat masa, parameter mungkin tidak sah, perkhidmatan luaran tergendala. Ejen produksi memerlukan pengurusan ralat supaya model boleh menerangkan masalah atau cuba alternatif daripada menyebabkan aplikasi lumpuh sepenuhnya. Apabila alat melemparkan pengecualian, LangChain4j menangkapnya dan menghantar mesej ralat balik kepada model, yang kemudian boleh menerangkan masalah dalam bahasa semulajadi. +Alat boleh gagal — API tamat masa, parameter mungkin tidak sah, perkhidmatan luaran tidak berfungsi. Ejen produksi memerlukan pengendalian ralat supaya model boleh menerangkan masalah atau cuba alternatif dan bukannya merosakkan seluruh aplikasi. Apabila alat melemparkan pengecualian, LangChain4j menangkapnya dan memberi balik mesej ralat kepada model, yang kemudian boleh menerangkan masalah dalam bahasa semula jadi. ## Alat Tersedia -Rajah di bawah menunjukkan ekosistem luas alat yang boleh anda bina. Modul ini mempamerkan alat cuaca dan suhu, tetapi corak `@Tool` yang sama berfungsi untuk mana-mana kaedah Java — daripada pertanyaan pangkalan data hingga pemprosesan pembayaran. +Rajah di bawah menunjukkan ekosistem luas alat yang boleh anda bina. Modul ini menunjukkan alat cuaca dan suhu, tetapi corak `@Tool` yang sama berfungsi untuk mana-mana kaedah Java — dari pertanyaan pangkalan data hingga pemprosesan pembayaran. -Tool Ecosystem +Ekosistem Alat -*Mana-mana kaedah Java yang dianotasikan dengan @Tool akan tersedia kepada AI — corak ini meluas kepada pangkalan data, API, emel, operasi fail, dan banyak lagi.* +*Mana-mana kaedah Java yang dianotasi dengan @Tool menjadi tersedia untuk AI — corak ini meluas ke pangkalan data, API, emel, operasi fail, dan banyak lagi.* -## Bila Menggunakan Ejen Berasaskan Alat +## Bila Perlu Guna Ejen Berasaskan Alat -Tidak semua permintaan memerlukan alat. Keputusan bergantung sama ada AI perlu berinteraksi dengan sistem luaran atau boleh menjawab daripada pengetahuannya sendiri. Panduan berikut merumuskan bila alat menambah nilai dan bila ia tidak diperlukan: +Tidak semua permintaan memerlukan alat. Keputusan bergantung kepada sama ada AI perlu berinteraksi dengan sistem luaran atau boleh memberi jawapan dari pengetahuannya sendiri. Panduan berikut meringkaskan bila alat menambah nilai dan bila ia tidak perlu: -When to Use Tools +Bila Perlu Guna Alat -*Panduan keputusan pantas — alat untuk data masa nyata, pengiraan, dan tindakan; pengetahuan umum dan tugas kreatif tidak memerlukannya.* +*Panduan keputusan cepat — alat untuk data masa nyata, pengiraan, dan tindakan; pengetahuan umum dan tugas kreatif tidak memerlukannya.* ## Alat vs RAG -Modul 03 dan 04 kedua-duanya memperluas kemampuan AI, tetapi dengan cara yang berbeza secara asas. RAG memberi model akses kepada **pengetahuan** dengan mengambil dokumen. Alat memberi model kebolehan melakukan **tindakan** dengan memanggil fungsi. Rajah di bawah membandingkan kedua-dua pendekatan secara berdampingan — daripada cara setiap workflow beroperasi hingga pertukaran antara keduanya: +Modul 03 dan 04 kedua-duanya memperluas apa yang AI boleh lakukan, tetapi dengan cara yang berbeza secara mendasar. RAG memberi model akses kepada **pengetahuan** dengan mendapatkan dokumen. Alat memberi model kebolehan untuk mengambil **tindakan** dengan memanggil fungsi. Rajah di bawah membandingkan kedua-dua pendekatan ini sebelah menyebelah — dari bagaimana setiap aliran kerja beroperasi hingga pertukaran antara keduanya: -Tools vs RAG Comparison +Perbandingan Alat vs RAG -*RAG mengambil maklumat dari dokumen statik — Alat melaksanakan tindakan dan mengambil data dinamik masa nyata. Banyak sistem produksi menggabungkan kedua-duanya.* +*RAG mendapatkan maklumat dari dokumen statik — Alat melaksanakan tindakan dan mendapatkan data dinamik masa nyata. Banyak sistem produksi menggabungkan kedua-duanya.* -Dalam praktik, banyak sistem produksi menggabungkan kedua-dua pendekatan: RAG untuk mendasari jawapan dalam dokumentasi anda, dan Alat untuk mengambil data langsung atau menjalankan operasi. +Dalam praktik, banyak sistem produksi menggabungkan kedua-dua pendekatan: RAG untuk mendasari jawapan dalam dokumentasi anda, dan Alat untuk mendapatkan data langsung atau menjalankan operasi. ## Langkah Seterusnya -**Modul Seterusnya:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Modul Seterusnya:** [05-mcp - Protokol Konteks Model (MCP)](../05-mcp/README.md) --- @@ -382,6 +382,6 @@ Dalam praktik, banyak sistem produksi menggabungkan kedua-dua pendekatan: RAG un --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya hendaklah dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/ms/README.md b/translations/ms/README.md index c86d941df..382120534 100644 --- a/translations/ms/README.md +++ b/translations/ms/README.md @@ -6,14 +6,14 @@ Kursus untuk membina aplikasi AI dengan LangChain4j dan Azure OpenAI GPT-5.2, da ### 🌐 Sokongan Pelbagai Bahasa -#### Disokong melalui GitHub Action (Automatik & Sentiasa Dikemaskini) +#### Disokong melalui GitHub Action (Automatik & Sentiasa Dikemas Kini) -[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](./README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) +[Arab](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgaria](../bg/README.md) | [Burma (Myanmar)](../my/README.md) | [Cina (Ringkas)](../zh-CN/README.md) | [Cina (Tradisional, Hong Kong)](../zh-HK/README.md) | [Cina (Tradisional, Macau)](../zh-MO/README.md) | [Cina (Tradisional, Taiwan)](../zh-TW/README.md) | [Kroasia](../hr/README.md) | [Ceko](../cs/README.md) | [Denmark](../da/README.md) | [Belanda](../nl/README.md) | [Estonia](../et/README.md) | [Finland](../fi/README.md) | [Perancis](../fr/README.md) | [Jerman](../de/README.md) | [Greek](../el/README.md) | [Ibrani](../he/README.md) | [Hindi](../hi/README.md) | [Hungary](../hu/README.md) | [Indonesia](../id/README.md) | [Itali](../it/README.md) | [Jepun](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korea](../ko/README.md) | [Lithuania](../lt/README.md) | [Melayu](./README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Pidgin Nigeria](../pcm/README.md) | [Norway](../no/README.md) | [Parsi (Farsi)](../fa/README.md) | [Poland](../pl/README.md) | [Portugis (Brazil)](../pt-BR/README.md) | [Portugis (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romania](../ro/README.md) | [Rusia](../ru/README.md) | [Serbia (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenia](../sl/README.md) | [Sepanyol](../es/README.md) | [Swahili](../sw/README.md) | [Sweden](../sv/README.md) | [Tagalog (Filipina)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turki](../tr/README.md) | [Ukraine](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnam](../vi/README.md) > **Lebih Suka Klon Secara Tempatan?** > -> Repositori ini termasuk terjemahan dalam lebih 50 bahasa yang secara signifikan meningkatkan saiz muat turun. Untuk klon tanpa terjemahan, gunakan sparse checkout: +> Repositori ini merangkumi 50+ terjemahan bahasa yang secara ketara meningkatkan saiz muat turun. Untuk klon tanpa terjemahan, gunakan sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,21 +29,20 @@ Kursus untuk membina aplikasi AI dengan LangChain4j dan Azure OpenAI GPT-5.2, da > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Ini memberikan anda segala-galanya yang anda perlukan untuk menyelesaikan kursus dengan muat turun yang lebih cepat. +> Ini memberikan anda semua yang anda perlukan untuk menyelesaikan kursus dengan muat turun yang lebih pantas. ## Jadual Kandungan -1. [Mula Pantas](00-quick-start/README.md) - Mulakan dengan LangChain4j -2. [Pengenalan](01-introduction/README.md) - Pelajari asas-asas LangChain4j -3. [Reka Bentuk Prompt](02-prompt-engineering/README.md) - Kuasai reka bentuk prompt yang berkesan -4. [RAG (Generasi Berasaskan Pengambilan)](03-rag/README.md) - Bina sistem berasaskan pengetahuan yang pintar -5. [Alat](04-tools/README.md) - Integrasi alat luaran dan pembantu mudah -6. [MCP (Protokol Konteks Model)](05-mcp/README.md) - Bekerja dengan Protokol Konteks Model (MCP) dan modul Agentic +1. [Pengenalan](01-introduction/README.md) - Pelajari asas LangChain4j +2. [Reka Bentuk Prompt](02-prompt-engineering/README.md) - Kuasai reka bentuk prompt yang berkesan +3. [RAG (Penjanaan Beraugmen Pencarian)](03-rag/README.md) - Bina sistem berasaskan pengetahuan yang pintar +4. [Alat](04-tools/README.md) - Integrasi alat luaran dan pembantu mudah +5. [MCP (Protokol Konteks Model)](05-mcp/README.md) - Bekerja dengan Protokol Konteks Model (MCP) dan modul Agentik ### Video Panduan -Setiap modul mempunyai sesi langsung pendamping di mana kami menerangkan konsep dan kod langkah demi langkah. +Setiap modul mempunyai sesi langsung sebagai teman yang menerangkan konsep dan kod langkah demi langkah. | Modul | Video | |--------|-------| @@ -56,35 +55,33 @@ Setiap modul mempunyai sesi langsung pendamping di mana kami menerangkan konsep ## Laluan Pembelajaran -**Baru dalam LangChain4j?** Lihat [Glosari](docs/GLOSSARY.md) untuk definisi terma dan konsep utama. +**Baru dalam LangChain4j?** Lihat [Glosari](docs/GLOSSARY.md) untuk definisi istilah dan konsep utama. -> **Mula Pantas** +> **Mula dengan Cepat** 1. Fork repositori ini ke akaun GitHub anda -2. Klik **Code** → tab **Codespaces** → **...** → **New with options...** -3. Gunakan tetapan lalai – ini akan memilih kontena Pembangunan yang dicipta untuk kursus ini -4. Klik **Create codespace** -5. Tunggu 5-10 minit untuk persekitaran bersedia -6. Terus lompat ke [Mula Pantas](./00-quick-start/README.md) untuk mula! +2. Klik **Code** → tab **Codespaces** → **...** → **Baru dengan pilihan...** +3. Gunakan seting lalai – ini akan memilih kontena Pembangunan yang dibuat untuk kursus ini +4. Klik **Buat codespace** +5. Tunggu 5-10 minit untuk persekitaran sedia +6. Terus ke [Pengenalan](./01-introduction/README.md) untuk bermula! -Selepas menamatkan modul, terokai [Panduan Ujian](docs/TESTING.md) untuk melihat konsep ujian LangChain4j dalam tindakan. - -> **Nota:** Latihan ini menggunakan kedua-dua Model GitHub dan Azure OpenAI. Modul [Mula Pantas](00-quick-start/README.md) menggunakan Model GitHub (tiada langganan Azure diperlukan), manakala modul 1-5 menggunakan Azure OpenAI. Mulakan dengan [akaun Azure PERCUMA](https://aka.ms/azure-free-account) jika anda belum mempunyainya. +Selepas melengkapkan modul, terokai [Panduan Ujian](docs/TESTING.md) untuk melihat konsep ujian LangChain4j beraksi. +> **Catatan:** Latihan ini menggunakan Azure OpenAI. Mulakan dengan [akaun Azure PERCUMA](https://aka.ms/azure-free-account) jika anda belum ada. ## Pembelajaran dengan GitHub Copilot -Untuk mula menulis kod dengan cepat, buka projek ini dalam GitHub Codespace atau IDE tempatan anda dengan devcontainer yang disediakan. Devcontainer yang digunakan dalam kursus ini telah dikonfigurasi terlebih dahulu dengan GitHub Copilot untuk pengaturcaraan AI secara berpasangan. +Untuk mulakan pengekodan dengan cepat, buka projek ini dalam GitHub Codespace atau IDE tempatan anda dengan devcontainer yang disediakan. Devcontainer yang digunakan dalam kursus ini telah dikonfigurasikan dengan GitHub Copilot untuk pengaturcaraan berpasangan AI. Setiap contoh kod termasuk soalan yang dicadangkan yang boleh anda tanya kepada GitHub Copilot untuk memperdalam pemahaman anda. Cari isyarat 💡/🤖 dalam: - **Header fail Java** - Soalan khusus untuk setiap contoh -- **README modul** - Cadangan terokai selepas contoh kod - -**Cara menggunakan:** Buka mana-mana fail kod dan tanya Copilot soalan yang dicadangkan. Ia mempunyai konteks penuh kod dan boleh menjelaskan, memanjangkan, dan mencadangkan alternatif. +- **README modul** - Cadangan penerokaan selepas contoh kod -Ingin belajar lebih? Lihat [Copilot untuk Pengaturcaraan Berpasangan AI](https://aka.ms/GitHubCopilotAI). +**Cara guna:** Buka mana-mana fail kod dan tanya Copilot soalan yang dicadangkan. Ia mempunyai konteks penuh kod dan boleh terangkan, kembangkan, dan cadangkan alternatif. +Ingin belajar lebih lanjut? Lihat [Copilot untuk Pengaturcaraan Berpasangan AI](https://aka.ms/GitHubCopilotAI). ## Sumber Tambahan @@ -104,10 +101,10 @@ Ingin belajar lebih? Lihat [Copilot untuk Pengaturcaraan Berpasangan AI](https:/ --- ### Siri AI Generatif -[![AI Generatif untuk Pemula](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Generatif (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![AI Generatif (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![AI Generatif (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +[![Generative AI untuk Pemula](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- @@ -116,21 +113,21 @@ Ingin belajar lebih? Lihat [Copilot untuk Pengaturcaraan Berpasangan AI](https:/ [![Sains Data untuk Pemula](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI untuk Pemula](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Keselamatan Siber untuk Pemula](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Pembangunan Web untuk Pemula](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT untuk Pemula](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![Pembangunan XR untuk Pemula](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Siri Copilot -[![Copilot untuk Pengaturcaraan Berpasangan AI](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot untuk C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Pengembaraan Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Mendapatkan Bantuan -Jika anda tersekat atau mempunyai sebarang soalan tentang membina aplikasi AI, sertailah: +Jika anda tersekat atau mempunyai sebarang pertanyaan tentang membina aplikasi AI, sertai: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) @@ -140,11 +137,11 @@ Jika anda mempunyai maklum balas produk atau ralat semasa membina, lawati: ## Lesen -Lesen MIT - Lihat fail [LICENSE](../../LICENSE) untuk butiran. +Lesen MIT - Lihat fail [LICENSE](../../LICENSE) untuk maklumat lanjut. --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat kritikal, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/ms/docs/GLOSSARY.md b/translations/ms/docs/GLOSSARY.md index 8f652708c..0107d2978 100644 --- a/translations/ms/docs/GLOSSARY.md +++ b/translations/ms/docs/GLOSSARY.md @@ -1,70 +1,70 @@ -# Glosari LangChain4j +# Kamus Istilah LangChain4j ## Jadual Kandungan -- [Konsep Teras](../../../docs) -- [Komponen LangChain4j](../../../docs) -- [Konsep AI/ML](../../../docs) -- [Guardrails](../../../docs) -- [Kejuruteraan Prompt](../../../docs) -- [RAG (Generasi Beraugmen Ambilan)](../../../docs) -- [Ejen dan Alat](../../../docs) -- [Modul Agentik](../../../docs) -- [Protokol Konteks Model (MCP)](../../../docs) -- [Perkhidmatan Azure](../../../docs) -- [Ujian dan Pembangunan](../../../docs) +- [Konsep Teras](#konsep-teras) +- [Komponen LangChain4j](#komponen-langchain4j) +- [Konsep AI/ML](#konsep-aiml) +- [Penjagaan Keselamatan](#penjagaan-keselamatan) +- [Kejuruteraan Prompt](#prompt-engineering---module-02) +- [RAG (Penjanaan Diperkuatkan Pengambilan)](#rag-retrieval-augmented-generation---module-03) +- [Ejen dan Alat](#agents-and-tools---module-04) +- [Modul Agentic](#agentic-module---module-05) +- [Protokol Konteks Model (MCP)](#model-context-protocol-mcp---module-05) +- [Perkhidmatan Azure](#azure-services---module-01) +- [Ujian dan Pembangunan](#testing-and-development---testing-guide) -Rujukan pantas untuk terma dan konsep yang digunakan sepanjang kursus. +Rujukan pantas untuk istilah dan konsep yang digunakan sepanjang kursus. ## Konsep Teras **Ejen AI** - Sistem yang menggunakan AI untuk berfikir dan bertindak secara autonomi. [Modul 04](../04-tools/README.md) -**Rantaian** - Urutan operasi di mana output menjadi input ke langkah seterusnya. +**Rantaian** - Urutan operasi di mana output menjadi input untuk langkah seterusnya. -**Pengpecahan** - Memecah dokumen menjadi bahagian yang lebih kecil. Biasanya: 300-500 token dengan tumpang tindih. [Modul 03](../03-rag/README.md) +**Penggubahan** - Memecahkan dokumen kepada bahagian yang lebih kecil. Biasa: 300-500 token dengan pertindihan. [Modul 03](../03-rag/README.md) -**Tingkap Konteks** - Maksimum token yang boleh diproses oleh model. GPT-5.2: 400K token (hingga 272K input, 128K output). +**Tetingkap Konteks** - Maksimum token yang model boleh proses. GPT-5.2: 400K token (sehingga 272K input, 128K output). -**Penempatan** - Vektor angka yang mewakili maksud teks. [Modul 03](../03-rag/README.md) +**Penyerlahan** - Vektor berangka yang mewakili maksud teks. [Modul 03](../03-rag/README.md) -**Panggilan Fungsi** - Model menjana permintaan berstruktur untuk memanggil fungsi luaran. [Modul 04](../04-tools/README.md) +**Panggilan Fungsi** - Model menghasilkan permintaan berstruktur untuk memanggil fungsi luar. [Modul 04](../04-tools/README.md) -**Halusinasi** - Apabila model menjana maklumat yang salah tetapi munasabah. +**Halusinasi** - Apabila model menghasilkan maklumat yang salah tetapi nampak munasabah. **Prompt** - Input teks kepada model bahasa. [Modul 02](../02-prompt-engineering/README.md) -**Carian Semantik** - Carian berdasarkan makna menggunakan penempatan, bukan kata kunci. [Modul 03](../03-rag/README.md) +**Carian Semantik** - Carian berdasarkan maksud menggunakan penyerlahan, bukan kata kunci. [Modul 03](../03-rag/README.md) -**Bersifat Stateful vs Stateless** - Stateless: tiada memori. Stateful: mengekalkan sejarah perbualan. [Modul 01](../01-introduction/README.md) +**Berdepan Status vs Tanpa Status** - Stateless: tiada memori. Stateful: mengekalkan sejarah perbualan. [Modul 01](../01-introduction/README.md) -**Token** - Unit asas teks yang diproses model. Mempengaruhi kos dan had. [Modul 01](../01-introduction/README.md) +**Token** - Unit asas teks yang model proses. Mempengaruhi kos dan had. [Modul 01](../01-introduction/README.md) -**Rantaian Alat** - Pelaksanaan alat berturutan di mana output memaklumkan panggilan seterusnya. [Modul 04](../04-tools/README.md) +**Rantaian Alat** - Pelaksanaan alat secara berurutan di mana output memaklumkan panggilan seterusnya. [Modul 04](../04-tools/README.md) ## Komponen LangChain4j -**AiServices** - Mencipta antara muka perkhidmatan AI yang selamat jenis. +**AiServices** - Mencipta antara muka perkhidmatan AI jenis-selamat. -**OpenAiOfficialChatModel** - Pelanggan sekata untuk model OpenAI dan Azure OpenAI. +**OpenAiOfficialChatModel** - Klien bersatu untuk model OpenAI dan Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Mencipta penempatan menggunakan pelanggan Rasmi OpenAI (menyokong OpenAI dan Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Mencipta penyerlahan menggunakan klien rasmi OpenAI (menyokong OpenAI dan Azure OpenAI). **ChatModel** - Antara muka teras untuk model bahasa. **ChatMemory** - Mengekalkan sejarah perbualan. -**ContentRetriever** - Mencari bahagian dokumen yang relevan untuk RAG. +**ContentRetriever** - Mencari bahagian dokumen yang berkaitan untuk RAG. -**DocumentSplitter** - Memecah dokumen kepada bahagian. +**DocumentSplitter** - Memecahkan dokumen kepada bahagian. -**EmbeddingModel** - Menukar teks ke vektor angka. +**EmbeddingModel** - Menukar teks kepada vektor berangka. -**EmbeddingStore** - Menyimpan dan mengambil penempatan. +**EmbeddingStore** - Menyimpan dan mengambil penyerlahan. -**MessageWindowChatMemory** - Mengekalkan tetingkap gelongsor mesej terkini. +**MessageWindowChatMemory** - Mengekalkan tetingkap gelangsar mesej terkini. -**PromptTemplate** - Mencipta prompt boleh guna semula dengan ruang letak `{{variable}}`. +**PromptTemplate** - Mencipta prompt boleh guna semula dengan tempat letak `{{variable}}`. **TextSegment** - Segmen teks dengan metadata. Digunakan dalam RAG. @@ -74,159 +74,157 @@ Rujukan pantas untuk terma dan konsep yang digunakan sepanjang kursus. ## Konsep AI/ML -**Pembelajaran Few-Shot** - Memberi contoh dalam prompt. [Modul 02](../02-prompt-engineering/README.md) +**Pembelajaran Few-Shot** - Memberikan contoh dalam prompt. [Modul 02](../02-prompt-engineering/README.md) -**Model Bahasa Besar (LLM)** - Model AI yang dilatih pada data teks besar. +**Model Bahasa Besar (LLM)** - Model AI yang dilatih menggunakan data teks yang sangat banyak. **Usaha Penalaran** - Parameter GPT-5.2 yang mengawal kedalaman pemikiran. [Modul 02](../02-prompt-engineering/README.md) -**Suhu** - Mengawal rawak output. Rendah=deterministik, tinggi=kreatif. +**Suhu** - Mengawal kebarangkalian output. Rendah=deterministik, tinggi=kreatif. -**Pangkalan Data Vektor** - Pangkalan data khusus untuk penempatan. [Modul 03](../03-rag/README.md) +**Pangkalan Data Vektor** - Pangkalan data khusus untuk penyerlahan. [Modul 03](../03-rag/README.md) **Pembelajaran Zero-Shot** - Melaksanakan tugasan tanpa contoh. [Modul 02](../02-prompt-engineering/README.md) -## Guardrails - [Modul 00](../00-quick-start/README.md) +## Penjagaan Keselamatan -**Pertahanan Bertingkat** - Pendekatan keselamatan berlapis yang menggabungkan guardrails pada tingkat aplikasi dengan penapis keselamatan penyedia. +**Pertahanan Berlapis** - Pendekatan keselamatan berbilang lapisan menggabungkan penjagaan di peringkat aplikasi dengan penapis keselamatan penyedia. -**Sekatan Keras** - Penyedia membuang ralat HTTP 400 untuk pelanggaran kandungan yang serius. +**Halangan Keras** - Penyedia mengembalikan ralat HTTP 400 untuk pelanggaran kandungan yang serius. **InputGuardrail** - Antara muka LangChain4j untuk mengesahkan input pengguna sebelum sampai ke LLM. Menjimatkan kos dan kelewatan dengan menyekat prompt berbahaya awal. -**InputGuardrailResult** - Jenis pulangan untuk pengesahan guardrail: `success()` atau `fatal("reason")`. +**InputGuardrailResult** - Jenis pulangan untuk pengesahan penjagaan: `success()` atau `fatal("reason")`. **OutputGuardrail** - Antara muka untuk mengesahkan respons AI sebelum dikembalikan kepada pengguna. -**Penapis Keselamatan Penyedia** - Penapis kandungan terbina dalam daripada penyedia AI (contoh: GitHub Models) yang mengesan pelanggaran pada tahap API. +**Penapis Keselamatan Penyedia** - Penapis kandungan terbina dalam dari penyedia AI (contohnya, Azure OpenAI) yang mengesan pelanggaran di peringkat API. -**Penolakan Lembut** - Model dengan sopan menolak menjawab tanpa membuang ralat. +**Penolakan Lembut** - Model dengan sopan enggan menjawab tanpa menghasilkan ralat. ## Kejuruteraan Prompt - [Modul 02](../02-prompt-engineering/README.md) **Rantaian Pemikiran** - Penalaran langkah demi langkah untuk ketepatan lebih baik. -**Output Terhad** - Memaksa format atau struktur tertentu. +**Output Terhad** - Menguatkuasakan format atau struktur tertentu. -**Keghairahan Tinggi** - Corak GPT-5.2 untuk penalaran menyeluruh. +**Semangat Tinggi** - Corak GPT-5.2 untuk penalaran teliti. -**Keghairahan Rendah** - Corak GPT-5.2 untuk jawapan cepat. +**Semangat Rendah** - Corak GPT-5.2 untuk jawapan pantas. -**Perbualan Berbilang Giliran** - Mengekalkan konteks sepanjang pertukaran. +**Perbualan Berbilang Giliran** - Mengekalkan konteks merentas pertukaran. -**Prompt Berdasarkan Peranan** - Menetapkan persona model melalui mesej sistem. +**Prompt berdasarkan Peranan** - Menetapkan persona model melalui mesej sistem. **Refleksi Diri** - Model menilai dan memperbaiki outputnya. -**Analisis Berstruktur** - Rangka penilaian tetap. +**Analisis Berstruktur** - Rangka kerja penilaian tetap. -**Corak Pelaksanaan Tugasan** - Rancang → Laksanakan → Rumuskan. +**Corak Pelaksanaan Tugasan** - Rancang → Laksanakan → Rumus. -## RAG (Generasi Beraugmen Ambilan) - [Modul 03](../03-rag/README.md) +## RAG (Penjanaan Diperkuatkan Pengambilan) - [Modul 03](../03-rag/README.md) -**Laluan Pemprosesan Dokumen** - Muat → pecah → tanam → simpan. +**Saluran Pemprosesan Dokumen** - Muat → pecah → serlah → simpan. -**Kedai Penempatan Dalam Memori** - Penyimpanan tidak kekal untuk ujian. +**Kedai Penyerlahan Dalam-Memori** - Penyimpanan tidak kekal untuk ujian. -**RAG** - Menggabungkan ambilan dengan generasi untuk mendasari jawapan. +**RAG** - Menggabungkan pengambilan dengan penjanaan untuk mendasari jawapan. **Skor Kesamaan** - Ukuran (0-1) kesamaan semantik. -**Rujukan Sumber** - Metadata tentang kandungan yang diambil. +**Rujukan Sumber** - Metadata tentang kandungan yang diperoleh. ## Ejen dan Alat - [Modul 04](../04-tools/README.md) -**@Tool Annotation** - Menandakan kaedah Java sebagai alat yang boleh dipanggil AI. +**@Tool Annotation** - Menandakan kaedah Java sebagai alat boleh panggil AI. -**Corak ReAct** - Berfikir → Bertindak → Memerhati → Ulang. +**Corak ReAct** - Berfikir → Bertindak → Perhatikan → Ulang. -**Pengurusan Sesi** - Konteks berasingan untuk pengguna berbeza. +**Pengurusan Sesi** - Konteks berasingan untuk pengguna berlainan. **Alat** - Fungsi yang boleh dipanggil oleh ejen AI. -**Penerangan Alat** - Dokumentasi tujuan dan parameter alat. +**Deskripsi Alat** - Dokumentasi tujuan dan parameter alat. -## Modul Agentik - [Modul 05](../05-mcp/README.md) +## Modul Agentic - [Modul 05](../05-mcp/README.md) -**@Agent Annotation** - Menandakan antara muka sebagai ejen AI dengan definisi kelakuan deklaratif. +**@Agent Annotation** - Menandakan antara muka sebagai ejen AI dengan definisi tingkah laku deklaratif. **Pendengar Ejen** - Hook untuk memantau pelaksanaan ejen melalui `beforeAgentInvocation()` dan `afterAgentInvocation()`. -**Skop Agentik** - Memori dikongsi di mana ejen menyimpan output menggunakan `outputKey` untuk diproses ejen hiliran. +**Skop Agentic** - Memori bersama di mana ejen menyimpan hasil menggunakan `outputKey` untuk digunakan oleh ejen seterusnya. **AgenticServices** - Kilang untuk mencipta ejen menggunakan `agentBuilder()` dan `supervisorBuilder()`. -**Aliran Kerja Bersyarat** - Laluan berdasarkan syarat ke ejen pakar berbeza. +**Aliran Kerja Bersyarat** - Laluan berdasarkan syarat kepada ejen pakar yang berbeza. -**Manusia Dalam Gelung** - Corak aliran kerja menambah titik pemeriksaan manusia untuk kelulusan atau semakan kandungan. +**Manusia dalam Gelung** - Corak aliran kerja menambah titik semak manusia untuk kelulusan atau semakan kandungan. -**langchain4j-agentic** - Kebergantungan Maven untuk pembinaan ejen deklaratif (eksperimen). +**langchain4j-agentic** - Kebergantungan Maven untuk binaan ejen deklaratif (eksperimen). **Aliran Kerja Gelung** - Ulang pelaksanaan ejen sehingga syarat dipenuhi (contoh: skor kualiti ≥ 0.8). -**outputKey** - Parameter pengecaman ejen yang menentukan di mana keputusan disimpan dalam Skop Agentik. +**outputKey** - Parameter anotasi ejen yang menentukan tempat penyimpanan hasil dalam Skop Agentic. -**Aliran Kerja Selari** - Jalankan beberapa ejen serentak untuk tugasan bebas. +**Aliran Kerja Selari** - Jalankan pelbagai ejen serentak untuk tugasan bebas. -**Strategi Respons** - Cara penyelia merumuskan jawapan akhir: TERAKHIR, RINGKASAN, atau BOARD. +**Strategi Respons** - Cara penyelia merumus jawapan akhir: TERAKHIR, RINGKASAN, atau BERI SKOR. -**Aliran Kerja Bersiri** - Laksanakan ejen mengikut urutan di mana output mengalir ke langkah seterusnya. +**Aliran Kerja Berurutan** - Laksanakan ejen mengikut turutan di mana output mengalir ke langkah seterusnya. -**Corak Ejen Penyelia** - Corak agentik canggih di mana LLM penyelia menentukan secara dinamik sub-ejen yang akan dipanggil. +**Corak Ejen Penyelia** - Corak agentic lanjutan di mana LLM penyelia memutuskan secara dinamik ejen sub mana yang dipanggil. ## Protokol Konteks Model (MCP) - [Modul 05](../05-mcp/README.md) **langchain4j-mcp** - Kebergantungan Maven untuk integrasi MCP dalam LangChain4j. -**MCP** - Protokol Konteks Model: standard untuk menyambungkan aplikasi AI kepada alat luaran. Bina sekali, guna di mana sahaja. +**MCP** - Protokol Konteks Model: piawaian untuk menyambungkan aplikasi AI ke alat luaran. Bina sekali, guna di mana-mana. -**Pelanggan MCP** - Aplikasi yang menyambung ke pelayan MCP untuk menemui dan menggunakan alat. +**Klien MCP** - Aplikasi yang menyambung ke pelayan MCP untuk mencari dan menggunakan alat. -**Pelayan MCP** - Perkhidmatan yang mendedahkan alat melalui MCP dengan penerangan jelas dan skema parameter. +**Pelayan MCP** - Perkhidmatan yang mendedahkan alat melalui MCP dengan deskripsi jelas dan skema parameter. -**McpToolProvider** - Komponen LangChain4j yang membalut alat MCP untuk digunakan dalam perkhidmatan dan ejen AI. +**McpToolProvider** - Komponen LangChain4j yang membungkus alat MCP untuk digunakan dalam perkhidmatan AI dan ejen. **McpTransport** - Antara muka untuk komunikasi MCP. Implementasi termasuk Stdio dan HTTP. -**Pengangkutan Stdio** - Pengangkutan proses tempatan melalui stdin/stdout. Berguna untuk akses sistem fail atau alat baris arahan. +**Pengangkutan Stdio** - Pengangkutan proses tempatan melalui stdin/stdout. Berguna untuk akses sistem fail atau alat baris perintah. -**StdioMcpTransport** - Pelaksanaan LangChain4j yang memulakan pelayan MCP sebagai proses sub. +**StdioMcpTransport** - Implementasi LangChain4j yang memulakan pelayan MCP sebagai subproses. -**Penemuan Alat** - Pelanggan bertanya pelayan tentang alat tersedia dengan penerangan dan skema. +**Penemuan Alat** - Klien membuat pertanyaan kepada pelayan untuk alat yang tersedia dengan deskripsi dan skema. ## Perkhidmatan Azure - [Modul 01](../01-introduction/README.md) **Azure AI Search** - Carian awan dengan keupayaan vektor. [Modul 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Mengedar sumber Azure. +**CLI Pembangun Azure (azd)** - Melaksanakan sumber Azure. **Azure OpenAI** - Perkhidmatan AI perusahaan Microsoft. **Bicep** - Bahasa infrastruktur sebagai kod Azure. [Panduan Infrastruktur](../01-introduction/infra/README.md) -**Nama Pengedaran** - Nama untuk pengedaran model di Azure. +**Nama Pelaksanaan** - Nama bagi pelaksanaan model dalam Azure. **GPT-5.2** - Model OpenAI terkini dengan kawalan penalaran. [Modul 02](../02-prompt-engineering/README.md) ## Ujian dan Pembangunan - [Panduan Ujian](TESTING.md) -**Dev Container** - Persekitaran pembangunan berasaskan kontena. [Konfigurasi](../../../.devcontainer/devcontainer.json) +**Kontena Dev** - Persekitaran pembangunan berkontena. [Konfigurasi](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Tapak percubaan model AI percuma. [Modul 00](../00-quick-start/README.md) - -**Ujian Dalam Memori** - Ujian dengan storan dalam memori. +**Ujian Dalam-Memori** - Ujian dengan penyimpanan dalam memori. **Ujian Integrasi** - Ujian dengan infrastruktur sebenar. **Maven** - Alat automasi binaan Java. -**Mockito** - Kerangka kerja pemalsuan Java. +**Mockito** - Rangka kerja pemalsuan Java. -**Spring Boot** - Rangka aplikasi Java. [Modul 01](../01-introduction/README.md) +**Spring Boot** - Rangka kerja aplikasi Java. [Modul 01](../01-introduction/README.md) --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk memberikan ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan profesional oleh manusia adalah disyorkan. Kami tidak bertanggungjawab atas sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/ms/docs/TESTING.md b/translations/ms/docs/TESTING.md index bbc9bc19e..9cca7316b 100644 --- a/translations/ms/docs/TESTING.md +++ b/translations/ms/docs/TESTING.md @@ -1,18 +1,18 @@ -# Menguji Aplikasi LangChain4j +# Ujian Aplikasi LangChain4j -## Kandungan +## Jadual Kandungan -- [Mula Pantas](../../../docs) -- [Apa yang Diuji](../../../docs) -- [Menjalankan Ujian](../../../docs) -- [Menjalankan Ujian dalam VS Code](../../../docs) -- [Corak Pengujian](../../../docs) -- [Falsafah Pengujian](../../../docs) -- [Langkah Seterusnya](../../../docs) +- [Mula Cepat](#mula-cepat) +- [Apa yang Diliputi oleh Ujian](#apa-yang-diliputi-oleh-ujian) +- [Menjalankan Ujian](#menjalankan-ujian) +- [Menjalankan Ujian dalam VS Code](#menjalankan-ujian-dalam-vs-code) +- [Corak Ujian](#corak-ujian) +- [Falsafah Ujian](#falsafah-ujian) +- [Langkah Seterusnya](#langkah-seterusnya) -Panduan ini membimbing anda melalui ujian yang menunjukkan cara menguji aplikasi AI tanpa memerlukan kunci API atau perkhidmatan luar. +Panduan ini membimbing anda melalui ujian yang menunjukkan cara menguji aplikasi AI tanpa memerlukan kunci API atau perkhidmatan luaran. -## Mula Pantas +## Mula Cepat Jalankan semua ujian dengan satu arahan: @@ -26,26 +26,25 @@ mvn test mvn --% test ``` -Apabila semua ujian lulus, anda akan melihat output seperti tangkapan skrin di bawah — ujian dijalankan tanpa kegagalan. +Apabila semua ujian lulus, anda akan melihat output seperti tangkapan skrin di bawah — ujian dijalankan dengan sifar kegagalan. Keputusan Ujian Berjaya -*Pelaksanaan ujian berjaya menunjukkan semua ujian lulus tanpa kegagalan* +*Pelaksanaan ujian berjaya menunjukkan semua ujian lulus dengan sifar kegagalan* -## Apa yang Diuji +## Apa yang Diliputi oleh Ujian -Kursus ini memfokuskan pada **ujian unit** yang dijalankan secara tempatan. Setiap ujian menunjukkan konsep LangChain4j tertentu secara terpencil. Piramid pengujian di bawah menunjukkan di mana ujian unit sesuai — ia membentuk asas yang pantas dan boleh dipercayai yang dibina strategi ujian anda yang lain. +Kursus ini memberi tumpuan kepada **ujian unit** yang dijalankan secara setempat. Setiap ujian menunjukkan konsep LangChain4j tertentu secara berasingan. Piramid ujian di bawah menunjukkan di mana ujian unit sesuai — ia membentuk asas yang pantas dan boleh dipercayai yang dibina oleh strategi ujian anda yang lain. -Piramid Pengujian +Piramid Ujian -*Piramid pengujian menunjukkan keseimbangan antara ujian unit (pantas, terasing), ujian integrasi (komponen sebenar), dan ujian hujung ke hujung. Latihan ini merangkumi ujian unit.* +*Piramid ujian menunjukkan keseimbangan antara ujian unit (cepat, terasing), ujian integrasi (komponen sebenar), dan ujian hujung-ke-hujung. Latihan ini meliputi ujian unit.* | Modul | Ujian | Fokus | Fail Utama | |--------|-------|-------|-----------| -| **00 - Mula Pantas** | 6 | Templat rangsangan dan penggantian pembolehubah | `SimpleQuickStartTest.java` | -| **01 - Pengenalan** | 8 | Memori perbualan dan sembang berstatus | `SimpleConversationTest.java` | -| **02 - Kejuruteraan Rangsangan** | 12 | Corak GPT-5.2, tahap kesungguhan, output berstruktur | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Penyepaduan dokumen, embedding, carian persamaan | `DocumentServiceTest.java` | +| **01 - Pengenalan** | 8 | Memori perbualan dan chat berkeadaan | `SimpleConversationTest.java` | +| **02 - Kejuruteraan Prompt** | 12 | Corak GPT-5.2, tahap kesungguhan, output berstruktur | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Pengambilan dokumen, penanaman, carian persamaan | `DocumentServiceTest.java` | | **04 - Alat** | 12 | Panggilan fungsi dan rantaian alat | `SimpleToolsTest.java` | | **05 - MCP** | 8 | Protokol Konteks Model dengan pengangkutan Stdio | `SimpleMcpTest.java` | @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Jalankan satu kelas ujian:** +**Jalankan kelas ujian tunggal:** **Bash:** ```bash @@ -95,17 +94,17 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#harusMenjagaSejarahPerbualan +mvn test -Dtest=SimpleConversationTest#harusMengekalkanSejarahPerbualan ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#harusMenjagaSejarahPerbualan +mvn --% test -Dtest=SimpleConversationTest#perluMengekalkanSejarahPerbualan ``` ## Menjalankan Ujian dalam VS Code -Jika anda menggunakan Visual Studio Code, Test Explorer menyediakan antara muka grafik untuk menjalankan dan menyahpepijat ujian. +Jika anda menggunakan Visual Studio Code, Penjelajah Ujian menyediakan antara muka grafik untuk menjalankan dan debug ujian. Penjelajah Ujian VS Code @@ -113,23 +112,23 @@ Jika anda menggunakan Visual Studio Code, Test Explorer menyediakan antara muka **Untuk menjalankan ujian dalam VS Code:** -1. Buka Test Explorer dengan mengklik ikon bekas kimia di Bar Aktiviti +1. Buka Penjelajah Ujian dengan mengklik ikon tabung uji dalam Bar Aktiviti 2. Kembangkan pokok ujian untuk melihat semua modul dan kelas ujian 3. Klik butang main di sebelah mana-mana ujian untuk menjalankannya secara individu -4. Klik "Run All Tests" untuk melaksanakan keseluruhan set ujian -5. Klik kanan mana-mana ujian dan pilih "Debug Test" untuk menetapkan titik pecah dan langkah melalui kod +4. Klik "Jalankan Semua Ujian" untuk melaksanakan keseluruhan suite +5. Klik kanan mana-mana ujian dan pilih "Debug Ujian" untuk menetapkan titik henti dan langkah melalui kod -Penjelajah Ujian menunjukkan tanda semak hijau untuk ujian yang lulus dan memberikan mesej kegagalan terperinci apabila ujian gagal. +Penjelajah Ujian menunjukkan tanda cek hijau untuk ujian yang lulus dan menyediakan mesej kegagalan terperinci apabila ujian gagal. -## Corak Pengujian +## Corak Ujian -### Corak 1: Menguji Templat Rangsangan +### Corak 1: Menguji Templat Prompt -Corak paling mudah menguji templat rangsangan tanpa memanggil mana-mana model AI. Anda memeriksa bahawa penggantian pembolehubah dilakukan dengan betul dan rangsangan diformatkan seperti yang dijangka. +Corak paling mudah menguji templat prompt tanpa memanggil mana-mana model AI. Anda mengesahkan bahawa penggantian pembolehubah berfungsi dengan betul dan prompt diformat seperti yang dijangka. -Pengujian Templat Rangsangan +Ujian Templat Prompt -*Pengujian templat rangsangan yang menunjukkan aliran penggantian pembolehubah: templat dengan tempat letak → nilai digunakan → output yang diformat disahkan* +*Ujian templat prompt menunjukkan aliran penggantian pembolehubah: templat dengan tempat letak → nilai diterapkan → output diformat disahkan* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Ujian ini terletak di `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Jalankan:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#ujianFormatTemplatArahan -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#formatTemplatPromptUjian -``` +Corak ini mengesahkan bahawa penggantian pembolehubah berfungsi dengan betul dan prompt diformat seperti yang dijangka — tiada kunci API atau panggilan model diperlukan. ### Corak 2: Memalsukan Model Bahasa -Apabila menguji logik perbualan, gunakan Mockito untuk mencipta model palsu yang mengembalikan respons yang telah ditentukan. Ini menjadikan ujian pantas, percuma, dan deterministik. +Apabila menguji logik perbualan, gunakan Mockito untuk mencipta model palsu yang mengembalikan respons yang telah ditentukan. Ini menjadikan ujian cepat, percuma, dan deterministik. -Perbandingan Palsu vs API Sebenar +Perbandingan Mock vs API Sebenar -*Perbandingan menunjukkan mengapa palsu lebih disukai untuk pengujian: ia pantas, percuma, deterministik, dan tidak memerlukan kunci API* +*Perbandingan menunjukkan mengapa mock lebih disukai untuk ujian: ia pantas, percuma, deterministik, dan tidak memerlukan kunci API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Corak ini muncul dalam `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Palsu memastikan tingkah laku konsisten supaya anda boleh mengesahkan pengurusan memori berfungsi dengan betul. +Corak ini muncul dalam `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock memastikan tingkah laku konsisten supaya anda boleh mengesahkan pengurusan memori berfungsi dengan betul. ### Corak 3: Menguji Pengasingan Perbualan -Memori perbualan mesti memisahkan beberapa pengguna. Ujian ini memeriksa bahawa perbualan tidak mencampur konteks. +Memori perbualan mesti memisahkan pelbagai pengguna. Ujian ini mengesahkan perbualan tidak mencampurkan konteks. Pengasingan Perbualan -*Pengujian pengasingan perbualan menunjukkan stor memori berasingan untuk pengguna yang berbeza bagi mengelakkan pencampuran konteks* +*Ujian pengasingan perbualan menunjukkan stor memori berasingan untuk pengguna berbeza bagi mengelakkan pencampuran konteks* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Setiap perbualan menyimpan sejarahnya sendiri secara bebas. Dalam sistem produksi, pengasingan ini kritikal untuk aplikasi berbilang pengguna. +Setiap perbualan mengekalkan sejarahnya sendiri secara berdikari. Dalam sistem pengeluaran, pengasingan ini kritikal untuk aplikasi berbilang pengguna. -### Corak 4: Menguji Alat Secara Berasingan +### Corak 4: Menguji Alat Secara Bebas -Alat adalah fungsi yang boleh dipanggil oleh AI. Uji mereka secara langsung untuk memastikan ia berfungsi walaupun tanpa keputusan AI. +Alat adalah fungsi yang boleh dipanggil AI. Uji mereka terus untuk memastikan mereka berfungsi dengan betul tanpa mengira keputusan AI. -Pengujian Alat +Ujian Alat -*Pengujian alat secara berasingan menunjukkan pelaksanaan alat palsu tanpa panggilan AI untuk mengesahkan logik perniagaan* +*Ujian alat secara bebas menunjukkan pelaksanaan alat palsu tanpa panggilan AI untuk mengesahkan logik perniagaan* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Ujian ini dari `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` mengesahkan logik alat tanpa penglibatan AI. Contoh rantaian menunjukkan bagaimana output satu alat memberi makan kepada input alat lain. +Ujian-ujian ini dari `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` mengesahkan logik alat tanpa penglibatan AI. Contoh rantaian menunjukkan bagaimana output satu alat menjadi input alat lain. -### Corak 5: Pengujian RAG Dalam Memori +### Corak 5: Ujian RAG Dalam Memori -Sistem RAG tradisional memerlukan pangkalan data vektor dan perkhidmatan embedding. Corak dalam memori membolehkan anda menguji seluruh saluran tanpa pergantungan luar. +Sistem RAG secara tradisional memerlukan pangkalan data vektor dan perkhidmatan penanaman. Corak dalam memori membolehkan anda menguji keseluruhan saluran tanpa kebergantungan luaran. -Pengujian RAG Dalam Memori +Ujian RAG Dalam Memori -*Aliran kerja pengujian RAG dalam memori menunjukkan pengecaman dokumen, penyimpanan embedding, dan carian persamaan tanpa memerlukan pangkalan data* +*Aliran kerja ujian RAG dalam memori menunjukkan penguraian dokumen, penyimpanan penanaman, dan carian persamaan tanpa memerlukan pangkalan data* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -Ujian ini dari `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` mencipta dokumen dalam memori dan memeriksa pemecahan serta pengendalian metadata. +Ujian ini dari `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` mencipta dokumen dalam memori dan mengesahkan pengpecahan dan pengendalian metadata. -### Corak 6: Pengujian Integrasi MCP +### Corak 6: Ujian Integrasi MCP -Modul MCP menguji integrasi Protokol Konteks Model menggunakan pengangkutan stdio. Ujian ini mengesahkan aplikasi anda boleh menjana dan berkomunikasi dengan pelayan MCP sebagai proses bawah. +Modul MCP menguji integrasi Protokol Konteks Model menggunakan pengangkutan stdio. Ujian-ujian ini mengesahkan aplikasi anda boleh memulakan dan berkomunikasi dengan pelayan MCP sebagai proses anak. Ujian dalam `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` mengesahkan tingkah laku klien MCP. -**Jalankan:** +**Jalankan mereka:** **Bash:** ```bash @@ -326,30 +313,29 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## Falsafah Pengujian +## Falsafah Ujian -Uji kod anda, bukan AI. Ujian anda harus mengesahkan kod yang anda tulis dengan memeriksa bagaimana rangsangan dibina, bagaimana memori diurus, dan bagaimana alat dilaksanakan. Respons AI berubah-ubah dan tidak sepatutnya menjadi sebahagian daripada penegasan ujian. Tanyakan pada diri anda sama ada templat rangsangan anda menggantikan pembolehubah dengan betul, bukan sama ada AI memberikan jawapan yang betul. +Uji kod anda, bukan AI. Ujian anda harus mengesahkan kod yang anda tulis dengan memeriksa cara prompt dibina, bagaimana memori diuruskan, dan bagaimana alat dilaksanakan. Respons AI berbeza-beza dan tidak sepatutnya menjadi sebahagian daripada kenyataan ujian. Tanya diri anda sama ada templat prompt anda menggantikan pembolehubah dengan betul, bukan sama ada AI memberi jawapan yang betul. -Gunakan palsu untuk model bahasa. Mereka adalah kebergantungan luaran yang perlahan, mahal, dan tidak deterministik. Memalsukan menjadikan ujian pantas dalam milisaat, percuma tanpa kos API, dan deterministik dengan keputusan sama setiap kali. +Gunakan mock untuk model bahasa. Ia adalah kebergantungan luaran yang lambat, mahal, dan tidak deterministik. Mocking menjadikan ujian pantas dengan milisaat bukannya saat, percuma tanpa kos API, dan deterministik dengan hasil yang sama setiap kali. -Pastikan ujian berdikari. Setiap ujian harus menyediakan data sendiri, tidak bergantung pada ujian lain, dan membersihkan selepas dirinya. Ujian harus lulus tanpa mengira urutan pelaksanaan. +Kekalkan ujian bebas. Setiap ujian harus menyediakan data sendiri, tidak bergantung pada ujian lain, dan membersihkan selepas dirinya. Ujian harus lulus tanpa mengira susunan pelaksanaan. -Uji kes luar selain jalan gembira. Cuba input kosong, input sangat besar, aksara khas, parameter tidak sah, dan syarat sempadan. Ini sering mendedahkan pepijat yang penggunaan normal tidak dedahkan. +Uji kes tepi di luar laluan biasa. Cuba input kosong, input sangat besar, aksara khas, parameter tidak sah, dan keadaan sempadan. Ini sering mendedahkan pepijat yang tidak didedahkan penggunaan biasa. -Gunakan nama deskriptif. Bandingkan `shouldMaintainConversationHistoryAcrossMultipleMessages()` dengan `test1()`. Yang pertama memberitahu anda dengan tepat apa yang diuji, memudahkan debug kegagalan. +Gunakan nama yang deskriptif. Bandingkan `shouldMaintainConversationHistoryAcrossMultipleMessages()` dengan `test1()`. Yang pertama memberitahu anda dengan tepat apa yang diuji, menjadikannya lebih mudah untuk mengesan ralat. ## Langkah Seterusnya -Kini anda memahami corak pengujian, terokai lebih mendalam setiap modul: +Sekarang anda memahami corak ujian, selami lebih mendalam setiap modul: -- **[00 - Mula Pantas](../00-quick-start/README.md)** - Mulakan dengan asas templat rangsangan - **[01 - Pengenalan](../01-introduction/README.md)** - Pelajari pengurusan memori perbualan -- **[02 - Kejuruteraan Rangsangan](../02/prompt-engineering/README.md)** - Kuasai corak rangsangan GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Bangunkan sistem penghasilan diperkuatkan pengambilan -- **[04 - Alat](../04-tools/README.md)** - Laksanakan panggilan fungsi dan rantai alat +- **[02 - Kejuruteraan Prompt](../02/prompt-engineering/README.md)** - Kuasai corak prompting GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Bina sistem retrieval-augmented generation +- **[04 - Alat](../04-tools/README.md)** - Laksanakan panggilan fungsi dan rantaian alat - **[05 - MCP](../05-mcp/README.md)** - Integrasi Protokol Konteks Model -README setiap modul menyediakan penjelasan terperinci konsep yang diuji di sini. +README setiap modul menyediakan penjelasan terperinci tentang konsep yang diuji di sini. --- @@ -358,6 +344,6 @@ README setiap modul menyediakan penjelasan terperinci konsep yang diuji di sini. --- -**Penafian**: -Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, harap maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya hendaklah dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan manusia profesional adalah disyorkan. Kami tidak bertanggungjawab atas sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. +**Penafian**: +Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini. \ No newline at end of file diff --git a/translations/my/.co-op-translator.json b/translations/my/.co-op-translator.json index 87d13d0c6..459eed3f4 100644 --- a/translations/my/.co-op-translator.json +++ b/translations/my/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "my" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T19:46:09+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T13:42:06+00:00", "source_file": "01-introduction/README.md", "language_code": "my" }, @@ -18,20 +18,20 @@ "language_code": "my" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T19:50:12+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T13:36:41+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "my" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T19:52:40+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T13:41:03+00:00", "source_file": "03-rag/README.md", "language_code": "my" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:33:35+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T13:39:37+00:00", "source_file": "04-tools/README.md", "language_code": "my" }, @@ -54,8 +54,8 @@ "language_code": "my" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:55:07+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T13:34:57+00:00", "source_file": "README.md", "language_code": "my" }, @@ -72,14 +72,14 @@ "language_code": "my" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T19:57:32+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T13:37:24+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "my" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T19:58:41+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T13:38:11+00:00", "source_file": "docs/TESTING.md", "language_code": "my" } diff --git a/translations/my/00-quick-start/README.md b/translations/my/00-quick-start/README.md deleted file mode 100644 index a69d3438a..000000000 --- a/translations/my/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: အချိန်တိုအရင်စတင်မှု - -## အကြောင်းအရာ - -- [မိတ်ဆက်](../../../00-quick-start) -- [LangChain4j ဆိုတာဘာလဲ?](../../../00-quick-start) -- [LangChain4j မှာလိုအပ်ချက်များ](../../../00-quick-start) -- [လိုအပ်ချက်များ](../../../00-quick-start) -- [တပ်ဆင်ခြင်း](../../../00-quick-start) - - [1. မိမိ GitHub Token ကိုရယူခြင်း](../../../00-quick-start) - - [2. မိမိ Token ကိုသတ်မှတ်ခြင်း](../../../00-quick-start) -- [နမူနာများကိုပြေးစမ်းပါ](../../../00-quick-start) - - [1. အခြေခံ စကားပြော](../../../00-quick-start) - - [2. Prompt ပုံစံများ](../../../00-quick-start) - - [3. Function ခေါ်ဆိုခြင်း](../../../00-quick-start) - - [4. စာရွက်စာတမ်း Q&A (လွယ်ကူသော RAG)](../../../00-quick-start) - - [5. တာဝန်ရှိသော AI](../../../00-quick-start) -- [နမူနာတိုင်းပြသသည့်အရာ](../../../00-quick-start) -- [နောက်တန်းအဆင့်များ](../../../00-quick-start) -- [ပြဿနာဖြေရှင်းခြင်း](../../../00-quick-start) - -## မိတ်ဆက် - -ဒီ quickstart သည် LangChain4j နှင့် မြန်ဆန်စွာ စတင်အသုံးပြုနိုင်ရန် ရည်ရွယ်သည်။ LangChain4j နှင့် GitHub Models အသုံးပြု၍ AI အသုံးပြု application များ တည်ဆောက်ရာတွင် အခြေခံများကိုဖော်ပြထားသည်။ နောက်ပိုင်း Modules များတွင် Azure OpenAI နှင့် GPT-5.2 သို့ ပစ်လွှတ်ကြပြီး concepts တစ်ခုချင်းစီကို ပိုမိုနက်ရှိုင်းစွာ လေ့လာသွားမည်ဖြစ်သည်။ - -## LangChain4j ဆိုတာဘာလဲ? - -LangChain4j သည် AI ပါဝင်သော applications များ တည်ဆောက်ရာတွင် အလွယ်တကူလုပ်ဆောင်ခွင့်ပေးသည့် Java စာကြည့်တိုက်ဖြစ်သည်။ HTTP clients နှင့် JSON parsing ကိုကိုင်တွယ်ရန်မလိုပဲ သင်သည် သန့်ရှင်းသော Java APIs ဖြင့်သာ အလုပ်လုပ်နိုင်သည်။ - -LangChain4j မှာ "chain" ဆိုသည်မှာ စိတ်ကြိုက် chain များကို ဆက်ထားခြင်းဖြစ်ပြီး - တစ်ခုချင်းစီ prompt ကို model နှင့် parser နှင့် ချိတ်ဆက်ဖို့ဖြစ်နိုင်သည်၊ သို့မဟုတ် AI ခေါ်ဆိုမှု များအားလုံး output ကို နောက် input သို့ ပစ်ပေးလည်းဖြစ်နိုင်သည်။ ဒီ quick start သည် အခြေခံများနဲ့ စတင်ပြီး ထပ်ဆင့် အကြီးစား chain များကို ပြန်လည်လေ့လာမည်။ - -LangChain4j Chaining Concept - -*LangChain4j မှာ components များကို ချိတ်ဆက်သည့် စဉ်ဆက်များ - အခြေခံ အပိုင်းအစများက အကြီးစား AI workflows တွေ တည်ဆောက်သည်* - -သုံးတဲ့ အခြေခံ component ငါးခု: - -**ChatModel** - AI model နှင့် ဆက်သွယ်ရန် interface ဖြစ်သည်။ `model.chat("prompt")` ကို ခေါ်၍ string response ရသည်။ သင်သည် `OpenAiOfficialChatModel` ကို အသုံးပြုသည်၊ GitHub Models စသည့် OpenAI-ကိုက်ညီသော endpoint များနှင့်အတူ အလုပ်လုပ်သည်။ - -**AiServices** - type-safe AI service interfaces ကို ဖန်တီးသည်။ method များကို သတ်မှတ်ပြီး `@Tool` ဖြင့် အမှတ်အသား ပြုလုပ်ပါက LangChain4j သည် orchestration ကို ကိုင်တွယ်သည်။ AI သည် လိုအပ်သည့်အချိန်တွင် သင့် Java method များကို အလိုအလျောက် ခေါ်ဆိုသည်။ - -**MessageWindowChatMemory** - စကားပြောမှတ်တမ်း ထိန်းသိမ်းထားသည်။ ၎င်းမရှိပါက မေးသော တောင်းဆိုချက်တိုင်းသည် လွတ်လပ်ပြီးပြားသည်။ ၎င်းဖြင့် AI သည် မေးခွန်းများနှင့် context ကို သိမ်းဆည်းထားနိုင်မည်။ - -LangChain4j Architecture - -*LangChain4j architecture - core components များသည် သင့် AI applications များအတွက် အလုပ်လုပ်ပေးသည်* - -## LangChain4j မှာလိုအပ်ချက်များ - -ဒီ quick start သည် Maven မှ အောက်ပါ dependency သုံးခုကို [`pom.xml`](../../../00-quick-start/pom.xml) ထဲတွင် သုံးသည် - - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` module သည် `OpenAiOfficialChatModel` class ကို ပံ့ပိုးသည်၊ OpenAI-ကိုက်ညီသော APIs နှင့် ချိတ်ဆက်ပေးသည်။ GitHub Models သည် သာမန် API ပုံစံကို အသုံးပြုသောကြောင့် အထူး adapter မလိုအပ်ပဲ base URL ကို `https://models.github.ai/inference` သို့ ချိတ်ဆက်နိုင်သည်။ - -`langchain4j-easy-rag` module သည် စာရွက်စာတမ်းများကို အလိုအလျောက် ခြားနားခြင်း ၊ embedding နှင့် retrieval ကို ပံ့ပိုးပေးပြီး သင်သည် RAG applications များကို လက်မလုပ်ဆောင်ဘဲ တည်ဆောက်နိုင်သည်။ - -## လိုအပ်ချက်များ - -**Dev Container ဖြင့်သုံးပါသလား?** Java နှင့် Maven သည် ရှိပြီးဖြစ်သည်။ သင်တွင် GitHub Personal Access Token လုံလောက်သည်။ - -**ပြည်တွင်းဖွံ့ဖြိုးတိုးတက်မှု:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (အောက်တွင်အနည်းငယ်လမ်းညွှန်ပါ) - -> **မှတ်ချက်:** ဒီ module သည် GitHub Models မှ `gpt-4.1-nano` ကို အသုံးပြုသည်။ ဤ code အတွင်းမှာ model နာမည် မပြောင်းလဲရ။ GitHub models တွေရဲ့ရရှိနိုင်မှုနှင့် ကိုက်ညီအောင် သတ်မှတ်ထားသည်။ - -## တပ်ဆင်ခြင်း - -### 1. မိမိ GitHub Token ကိုရယူခြင်း - -1. [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) သို့ သွားပါ -2. "Generate new token" ကိုနှိပ်ပါ -3. အမည် ရွေးချယ်ပါ (ဥပမာ - "LangChain4j Demo") -4. သက်တမ်းသတ်မှတ်ပါ (၇ ရက် မျှဆက်လက်သုံးရန် အကြံပြု) -5. "Account permissions" အောက်မှ "Models" ကိုရွေး၍ "Read-only" ခွင့်ပြုပါ -6. "Generate token" နှိပ်ပါ -7. မိမိ token ကို မျက်နှာမကြည့်ခင် ကူးယူပြီးထားရှိပါ - -### 2. မိမိ Token ကိုသတ်မှတ်ခြင်း - -**ရွေးချယ်မှု ၁: VS Code ဖြင့်အသုံးပြုခြင်း (အကြံပြုသည်)** - -VS Code အသုံးပြုပါက၊ project root တွင် `.env` ဖိုင်ထဲသို့ token ထည့်သွင်းပါ: - -`.env` ဖိုင် မရှိပါက `.env.example` ကို `.env` အဖြစ် ကူးယူပါ၊ ဒါမှမဟုတ် နေရာသစ် `.env` ဖိုင်တစ်ခု ဖန်တီးပါ။ - -**ဥပမာ `.env` ဖိုင်:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env တွင် -GITHUB_TOKEN=your_token_here -``` - -ထို့နောက် Explorer မှ တစ်ခုခု demo ဖိုင် (ဥပမာ `BasicChatDemo.java`) ကို right-click ပြုလုပ်ပြီး **"Run Java"** ကိုရွေးပါ သို့မဟုတ် Run and Debug panel မှ launch configurations များကို သုံးနိုင်သည်။ - -**ရွေးချယ်မှု ၂: Terminal ဖြင့်သုံးခြင်း** - -Environment variable အဖြစ် token ကို သတ်မှတ်ပါ: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## နမူနာများကိုပြေးစမ်းပါ - -**VS Code အသုံးပြုခြင်း:** Explorer ထဲမှ demo ဖိုင်အားလုံးကို right-click ပြုလုပ်ပြီး **"Run Java"** ရွေးခြင်းဖြင့် သို့မဟုတ် Run and Debug panel မှ launch configurations အသုံးပြု၍ token ကို `.env` မှ ထည့်သွင်းထားမှသာ။ - -**Maven အသုံးပြုခြင်း:** command line မှ run နိုင်ပါသည် - - -### 1. အခြေခံ စကားပြော - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Prompt ပုံစံများ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Zero-shot, few-shot, chain-of-thought, နှင့် role-based prompting များကို ပြသသည်။ - -### 3. Function ခေါ်ဆိုခြင်း - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI သည် လိုအပ်သည့်အချိန်တွင် Java method များကို အလိုအလျောက် ခေါ်ဆိုသည်။ - -### 4. စာရွက်စာတမ်း Q&A (လွယ်ကူသော RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Easy RAG ဖြင့် စာရွက်စာတမ်းအကြောင်း မေးခွန်းများကို အလိုအလျောက် embedding နှင့် retrieval အားဖြင့် မေးမြန်းနိုင်သည်။ - -### 5. တာဝန်ရှိသော AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -AI သည် အန္တရာယ်ရှိသော အကြောင်းအရာများကို စိတ်ရှုပ်ဖြေရှင်းမှု ကာကွယ်ရေး filter များဖြင့် တားဆီးသည်။ - -## နမူနာတိုင်းပြသသည့်အရာ - -**အခြေခံ စကားပြော** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -LangChain4j ကို အလွယ်တကူ စတင်အသုံးပြုမှုကို ဒီနေရာမှ ကြည့်ရှုနိုင်သည်။ သင်သည် `OpenAiOfficialChatModel` ဖန်တီးပြီး `.chat()` ဖြင့် prompt ပေး၍ response ရရှိမည်။ ဤသည်မှာ စတင်သည့် အခြေခံအဆောက်အအုံဖြစ်သည်။ သင်သည် custom endpoint နှင့် API key များဖြင့် မော်ဒယ်များကို စတင်ပါကဒီနည်းပညာကို နားလည်ထားရန်လိုသည်။ ၎င်းနောက် အခြား function များကို တည်ဆောက်နိုင်မည်။ - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ဖြင့် စမ်းပါ:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) ကိုဖွင့်ပြီး မေးပါ - -> - "GitHub Models မှ Azure OpenAI သို့ ဘယ်လို အစားထိုးမှုပြုလုပ်မလဲ?" -> - "OpenAiOfficialChatModel.builder() မှာ ဘယ် parameter တွေ ပြောင်းလဲချင်ရဲ့?" -> - "Response ပြန်လာတာ စောင့်ရန်မလိုဘဲ streaming ပုံစံဖြင့် သုံးချင်ရင် ဘယ်လိုလုပ်မလဲ?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Model နှင့် ဒိုင်ရက် ပြောဆိုနည်းကို သိရှိပြီးနောက် အခုတော့ ပြောတဲ့ စကားလုံးများကို လေ့လာကြမယ်။ ဒီနမူနာသည် မော်ဒယ်တူတူသာ သုံးပေမဲ့ prompt ပုံစံ ၅ မျိုးကို ပြသသည်။ Zero-shot prompt များဖြင့် တိုက်ရိုက်ညွှန်ကြားချက်များ၊ few-shot prompts ဖြင့် ဥပမာများမှ သင်ယူခြင်း၊ chain-of-thought prompts ဖြင့် အတွေးခင်းများဖော်ပြခြင်းနှင့် role-based prompts ဖြင့် context သတ်မှတ်ခြင်းတွေကို စမ်းသပ်ကြည့်နိုင်ပါသည်။ မည်သည့် prompt ဖြင့် ဖိတ်ခေါ်သည်ကိုအပေါ် မော်ဒယ်၏ ထွက်ရှိမှုက မတူကွဲပြားစေသည်။ - -ဒီနမူနာသည် prompt templates ကိုလည်း ပြသသည်၊ ၎င်းသည် variables ဖြင့် ပြန်လည်အသုံးပြုနိုင်သော prompts ဖန်တီးရန် ဂီတမြောက်ပြုလုပ်ပုံ ဖြစ်သည်။ -အောက်တွင် LangChain4j `PromptTemplate` ကို အသုံးပြုပြီး variable များ ဖြည့်စွက်ထားသော prompt လုပ်နည်းကို ပြထားသည်။ AI သည် destination နှင့် activity အပေါ်မူတည်၍ ဖြေကြားမည်။ - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ဖြင့် စမ်းပါ:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) ကို ဖွင့်ပြီး မေးပါ - -> - "Zero-shot နှင့် few-shot prompting ၏ ကွဲပြားချက်ဘာလဲ? ဘယ်အခါမှာ ဘယ်မှာသုံးရမလဲ?" -> - "Temperature parameter က မော်ဒယ်ဖြေကြားမှုကို ဘယ်လို သက်ေရာက်အကျိုးသက်ရောက်မှုရှိသလဲ?" -> - "Production တွင် prompt injection attacks မှကာကွယ်ရန် နည်းလမ်းများ ဘာများ ရှိသလဲ?" -> - "ပုံမှန် သုံးသော PromptTemplate objects များ ကို မည်သို့ ပြန်လည်အသုံးပြုနိုင်မလဲ?" - -**Tool Integration** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -ဒီနေရာက LangChain4j ကျယ်ပြန့်သောစွမ်းဆောင်ရည်က ပြသသည်။ သင်သည် `AiServices` ကို အသုံးပြု၍ သင့် Java method များကိုခေါ်နိုင်သော AI အကူအညီကို ဖန်တီးမည်။ Method များကို `@Tool("description")` ဖြင့် အမှတ်အသားပြုပါက LangChain4j သည် ဆက်စပ်ပုံစံအားလုံးကို ကိုင်တွယ်ပေးသည်။ AI သည် user ၏ မေးခွန်းအပေါ် အလိုအလျောက် ဖုန်းခေါ်ခြင်းများ ဆောင်ရွက်နိုင်ပါသည်။ ဒီနမူနာက တာဝန်ယူပါးပြောင်မှု (function calling) ကို ပြသသည်၊ အဓိက AI က ဖော်ပြချက်ပေးသည့် နည်းလမ်း ဖြစ်သည်။ - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ဖြင့် စမ်းပါ:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ကို ဖွင့်ပြီး မေးပါ - -> - "@Tool annotation က ဘယ်လို အလုပ်လုပ်သလဲ? LangChain4j က ယင်းနောက်မှာ ဘာလုပ်ပါသလဲ?" -> - "AI သည် လုပ်ငန်းခွဲများကို စဉ်လိုက်ခေါ်ဆိုပေးနိုင်ပါသလား?" -> - "Tool တစ်ခုမှ exception ပေါ်လာပါက ဘာဖြစ်မလဲ? အမှားများကို ယခင်တွင် ဘယ်လို ကိုင်တွယ်သင့်သလဲ?" -> - "ဒီ calculator ဥပမာ မဟုတ်ဘဲ တကယ့် API integration ဘယ်လိုလုပ်မလဲ?" - -**Document Q&A (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -ဒီမှာ LangChain4j ၏ "Easy RAG" နည်းလမ်းဖြင့် RAG (retrieval-augmented generation) ကို တွေ့မြင်ရမည်။ စာရွက်စာတမ်းများကို ဖတ်ရှု၊ အလိုအလျောက် ခြားနား၊ embedding လုပ်ပြီး memory store ထဲသို့သိမ်းဆည်းသည်။ ပြီးနောက် ရှာဖွေမှုစနစ်က AI ကို query အချိန်တွင် သင့်စာရွက်စာတမ်းများမှ အကြောင်းအရာဆက်စပ် ယူပေးသည်။ AI သည် ပုံမှန်သိမှတ်ချက်မဟုတ်ဘဲ သင့်စာရွက်စာတမ်းများအပေါ် မူတည်၍ ဖြေကြားသည်။ - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ဖြင့် စမ်းပါ:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) ကိုဖွင့်ပြီး မေးပါ - -> - "RAG သည် AI hallucination ကို မော်ဒယ် သင်ကြားမှုအချက်အလက်နှင့် မတူဘဲ မည်သို့ ကာကွယ်သနည်း?" -> - "ဒီလွယ်ကူသောနည်းလမ်းနှင့် စိတ်ကြိုက် RAG pipeline ကြားက ဘာကွာခြားမှုရှိသနည်း?" -> - "စာရွက်စာတမ်းများ များပြားသည့်အခါ သို့မဟုတ် သိမှတ်မှတ်တမ်းကြီးများကို မည်သို့ တိုးချဲ့ စီမံမည်နည်း?" - -**တာဝန်ရှိသော AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -AI လုံခြုံရေးကို အဆင့်မြှင့်တင်ဖန်တီးပါ။ ဒီနမူနာမှာ ကာကွယ်မှု အဆင့် ၂ ဆင့် တွဲဖက်သုံးထားသည်။ - -**အပိုင်း ၁: LangChain4j Input Guardrails** - LLM သို့ ရောက်ခင် စကားပြော ပြပွဲများအ၊သိမ်းထိန်းခြင်း။ တားမြစ်ရမည့် စကားလုံးနဲ့ ပုံတူ pattern များကို စစ်ကြည့်ရန် စိတ်ကြိုက် guardrails ဖန်တီးနိုင်သည်။ ၎င်းသည် သင့်ကုဒ်ထဲတွင် ပြေးသောကြောင့် အလျင်မြန်ပြီး အခမဲ့ဖြစ်သည်။ - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**အပိုင်း ၂: Provider Safety Filters** - GitHub Models သည် သင့် guardrails မမြင်နိုင်ပေမယ့် စုံစမ်းစစ်ဆေးမှု filter များပါရှိသည်။ ပြင်းထန်သောချို့ယွင်းချက်များအတွက် (HTTP 400 အမှား) တားဆီးမှုများ ရှိပြီး ရှင်းလင်း ညှိနှိုင်းခြင်းများတွင် AI သည် ရိုးသားစွာ ငြင်းဆန်ပါသည်။ - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ဖြင့် စမ်းပါ:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) ကိုဖွင့်ပြီး မေးပါ - -> - "InputGuardrail ဆိုတာဘာလဲ? ကိုယ့်ကိုယ်ကိုဘယ်လို ဖန်တီးမလဲ?" -> - "Hard block နှင့် soft refusal ကြားက ခြားနားချက် ဘာလဲ?" -> - "Guardrails နဲ့ provider filters ကို ဘယ်လိုတူတူအသုံးပြုသင့်သလဲ?" - -## နောက်တန်းအဆင့်များ - -**နောက်တန်း Module:** [01-introduction - LangChain4j နဲ့ စတင်တည်ဆောက်ခြင်း](../01-introduction/README.md) - ---- - -**သွားလာရန်:** [← ပြန်သွား မူလစာမျက်နှာ](../README.md) | [နောက်တစ်ပိုင်း: Module 01 - မိတ်ဆက် →](../01-introduction/README.md) - ---- - -## ပြဿနာဖြေရှင်းခြင်း - -### ပထမဆုံး Maven Build - -**ပြဿနာ:** ပထမဆုံး `mvn clean compile` သို့မဟုတ် `mvn package` သည် ကြာမြင့်သည် (10-15 မိနစ်) - -**အကြောင်း:** Maven သည် ပထမဆုံး build အတွက် အားလုံး project dependency များ (Spring Boot, LangChain4j libraries, Azure SDKs စသည်) ကို ဒေါင်းလုပ်ချရန် လိုအပ်သည်။ - -**ဖြေရှင်းနည်း:** ၎င်းသည် ပုံမှန် ဖြစ်စဉ်ဖြစ်သည်။ နောက်ထပ် build များတွင် ဒေတာများကို local ထဲတွင် သိမ်းဆည်းပြီးဖြစ်သဖြင့် လျှင်မြန်သွားမည်။ ဒေါင်းလုပ်နှုန်းသည် သင့်ကွန်ရက်အမြန်နှုန်းပေါ်မူတည်သည်။ - -### PowerShell Maven Command Syntax - -**ပြဿနာ:** Maven command များတွင် `Unknown lifecycle phase ".mainClass=..."` အမှားဖြစ်ပေါ်သည်။ -**အကြောင်းအရင်း**: PowerShell သည် `=` ကို မိမိ၏ အသုံးပြုထားသော မော်တင်အဖြေပိုင်း ဒေတာပေးလမ်းပြ မှာပုံမှန် မဟုတ်သည့် ပုံစံများအတွက် ရည်ညွှန်းချက်အဖြစ် မျှော်လင့်ခြင်း၊ Maven property syntax ကို ကွဲသွားစေသည်။ - -**ဖြေရှင်းချက်**: Maven command မတည့်ခင် `--%` ဆိုသော stop-parsing operator ကို အသုံးပြုမည်။ - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` operator သည် PowerShell ကို Maven သို့ အကျန်အမြစ်အားလုံးကို အဓိပ္ပါယ်မပြောင်းဘဲ များစွာသော argument များကို တိုက်ရိုက်ပေးပို့ရန် ပြောဆိုသည်။ - -### Windows PowerShell Emoji ပြသမှု - -**ပြဿနာ**: PowerShell မှာ AI အဖြေများကို emoji များထုတ်မထားဘဲ ကပ်ဖတ်စာလုံးများ (ဥပမာ `????` သို့မဟုတ် `â??`) ပုံစံဖြင့် ပြသခြင်း။ - -**အကြောင်းအရင်း**: PowerShell ၏ ပုံမှန် encoding သည် UTF-8 emojis မကိုင်တွယ်နိုင်ပါ။ - -**ဖြေရှင်းချက်**: Java application မတည့်ခင် ဤ command ကို run ပြီးတာ။ -```cmd -chcp 65001 -``` - -တစ်ကား UTF-8 encoding ကို terminal တည်အောင်လုပ်ပေးသည်။ တခြားနည်းလမ်းအဖြစ် Windows Terminal ကိုအသုံးပြုပါ၊ Unicode ကိုပိုမိုထောက်ပံ့သည်။ - -### API Call များ Debugging - -**ပြဿနာ**: Authentication error များ၊ rate limit များ သို့မဟုတ် AI မော်ဒယ်ထံမှ မမျှော်လင့်ထားသော တုံ့ပြန်မှုများ - -**ဖြေရှင်းချက်**: ဥပမာများတွင် `.logRequests(true)` နှင့် `.logResponses(true)` ကို console တွင် API call များကို ပေါ်လာစေဖို့ စိစစ်သုံးသပ်မှုအတွက် ထည့်ထားသည်။ ဤအရာများသည် authentication errors, rate limits, သို့မဟုတ် မမျှော်လင့်ထားသော တုံ့ပြန်ချက်များကို ပြန်လည်ရှာဖွေရာတွင် ကူညီပေးနိုင်သည်။ Production မှာ အဲ့ဒီ flag များကို ဖယ်ရှား၍ log ရုပ်သိမ်းလိုစရာနည်းစေသည်။ - ---- - - -**တရားဝင်မှတ်ချက်** -ဤစာရွက်စာတမ်းကို AI ဘာသာပြန်မှုဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) ကို အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ တိကျမှုအတွက် ကြိုးပမ်းသည်ဖြစ်သော်လည်း အော်တိုမိတက် ဘာသာပြန်မှုများတွင် အမှားများ သို့မဟုတ် မမှန်ကန်မှုများ ပါဝင်နိုင်သည်ကို သိရှိထားပါ။ မူလစာရွက်စာတမ်းကို မူရင်းဘာသာဖြင့် စစ်မှန်သော အတည်ပြုအရင်းအမြစ်အဖြစ် သတ်မှတ်စဉ်းစားသင့်သည်။ မဟာဗျူဟာဆိုင်ရာ သတင်းအချက်အလက်များအတွက် ဖြစ်ပါက ပညာရှင် များဖြင့် လူကြီးမင်း လက်တွေ့ ဘာသာပြန်ခြင်းကို အကြံပြုပါသည်။ ဤဘာသာပြန်မှုကို အသုံးပြုရာမှ ဖြစ်ပေါ်နိုင်သော မေးမြန်းမှားប្រစ်မှုများ သို့မဟုတ် နားလည်မှုပျက်ပြားမှုများအတွက် ကျွန်ုပ်တို့ တာဝန်မရှိကြောင်း သတိပေးအပ်ပါသည်။ - \ No newline at end of file diff --git a/translations/my/01-introduction/README.md b/translations/my/01-introduction/README.md index 3c4208063..a9d492382 100644 --- a/translations/my/01-introduction/README.md +++ b/translations/my/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j ဖြင့် စတင်အသုံးပြုခြင်း +# Module 01: LangChain4j နှင့် စတင်လေ့လာခြင်း -## အကြောင်းအရာ ဇယား +## အကြောင်းအရာ အပေါ်အနေနှင့် -- [ဗွီဒီယို လမ်းညွှန်](../../../01-introduction) -- [သင်ယူမည့်အကြောင်းအရာများ](../../../01-introduction) -- [လိုအပ်ချက်များ](../../../01-introduction) -- [အဓိကပြဿနာနားလည်ခြင်း](../../../01-introduction) -- [တိုးကင်များနားလည်ခြင်း](../../../01-introduction) -- [မှတ်ဉာဏ်လုပ်ဆောင်ပုံ](../../../01-introduction) -- [LangChain4j ကို ဘယ်လိုအသုံးပြုသည်](../../../01-introduction) -- [Azure OpenAI အခြေခံအဆောက်အအုံ တပ်ဆင်ခြင်း](../../../01-introduction) -- [လက်ရှိ စက်ပေါ်တွင် အပလီကေးရှင်း ကို run ချခြင်း](../../../01-introduction) -- [အပလီကေးရှင်းအသုံးပြုခြင်း](../../../01-introduction) - - [Stateless Chat (ဘယ်ဘက် Panel)](../../../01-introduction) - - [Stateful Chat (ညာဘက် Panel)](../../../01-introduction) -- [နောက်တစ်ဆင့်](../../../01-introduction) +- [ဗီဒီယို လမ်းညွှန်](#ဗီဒီယို-လမ်းညွှန်) +- [သင်လေ့လာရန် မျှော်မှန်းချက်များ](#သင်လေ့လာရန်-မျှော်မှန်းချက်များ) +- [လိုအပ်သော ရှေ့ဆက်ချက်များ](#လိုအပ်သော-ရှေ့ဆက်ချက်များ) +- [အဓိက ပြဿနာကိုနားလည်ခြင်း](#အဓိက-ပြဿနာကိုနားလည်ခြင်း) +- [တိုးကင်များကိုနားလည်ခြင်း](#တိုးကင်များကိုနားလည်ခြင်း) +- [မှတ်ဉာဏ်က 어떻게 လုပ်ဆောင်သည်](#မှတ်ဉာဏ်က-어떻게-လုပ်ဆောင်သည်) +- [LangChain4j ကိုဘယ်လို သုံးထားသလဲ](#langchain4j-ကို-ဘယ်လို-သုံးထားသလဲ) +- [Azure OpenAI အပြည့်အစုံစုစည်းမှု တပ်ဆင်ခြင်း](#azure-openai-အပြည့်အစုံစုစည်းမှု-တပ်ဆင်ခြင်း) +- [အက်ပ်လီကေးရှင်းကို ဒေသတွင်း လည်ပတ်ခြင်း](#အက်ပ်လီကေးရှင်းကို-ဒေသတွင်း-လည်ပတ်ခြင်း) +- [အက်ပ်လီကေးရှင်း အသုံးပြုခြင်း](#အက်ပ်လီကေးရှင်း-အသုံးပြုခြင်း) + - [Stateless Chat ( ဘယ်ဘက် Panel)](#stateless-chat-ဘယ်ဘက်-panel) + - [Stateful Chat ( ညာဘက် Panel)](#stateful-chat-ညာဘက်-panel) +- [နောက်တည့်ခြင်း လမ်းကြောင်း](#နောက်တည့်ခြင်း-လမ်းကြောင်း) -## ဗွီဒီယို လမ်းညွှန် +## ဗီဒီယို လမ်းညွှန် -ဒီ module ကို စတင်အသုံးပြုနည်းကိုရှင်းပြထားတဲ့ လက်တွေ့မှတ်တမ်းကို ကြည့်ပါ။ +ဒီ Live session ကို ကြည့်ရှုပါ၊ ဒီ module နဲ့ ဘယ်လို စတင်ရမယ်ဆိုတာ ရှင်းပြထားပါတယ်။ Getting Started with LangChain4j - Live Session -## သင်ယူမည့်အကြောင်းအရာများ +## သင်လေ့လာရန် မျှော်မှန်းချက်များ -Quick start မှာ GitHub Models ကို prompt ပေးခြင်း၊ tools ခေါ်သုံးခြင်း၊ RAG pipeline တည်ဆောက်ခြင်းနှင့် guardrails စမ်းသပ်ခြင်းများကို သုံးခဲ့ပါတယ်။ ဒီ demos တွေက ဖြစ်နိုင်တာတွေကို ပြသထားသော်လည်း ယခုနေရာမှာ Azure OpenAI နဲ့ GPT-5.2 ကို သုံးပြီး ထုတ်လုပ်မှုစတိုင်းပုံစံ application တွေဖန်တီးမယ်။ ဒီ module က context ကို မှတ်မိထားပြီး state ကို ထိန်းသိမ်းထားတဲ့ စကားပြော AI အပေါ် အာရုံစိုက်ထားပါတယ်။ quick start demos တွေမှာ သုံးခဲ့တဲ့ concept တွေအကြောင်း ရှင်းပြခြင်းမရှိခဲ့ပါ။ +ဒါဟာ LangChain4j နဲ့ Azure OpenAI ကို စတင်သုံးစွဲနိုင်ဖို့ အစဖြစ်ပါတယ်။ အခြေခံတွေကနေ စတင်ပြီး ထုတ်လုပ်မှု အဆင့်ဆိုင်ရာ အက်ပ်များ ပြုလုပ်သွားမှာဖြစ်ပါတယ်။ ဒီ module က context ကို မှတ်မိပြီး state ကို ထိန်းသိမ်းထားတဲ့ စကားပြော AI ကို အဓိကထားပါသည် — နောက်ပိုင်း module တစ်ခုချင်းစီ အခြေခံ သဘောတရားတွေ ဖြစ်ပါတယ်။ -ဒီအတွက် Azure OpenAI ရဲ့ GPT-5.2 ကို လမ်းညွှန်မှုတစ်လျှောက်လုံး သုံးမှာဖြစ်ပြီး ၎င်းရဲ့ မြင့်မားတဲ့ ယူဆချက်များကြောင့် မတူညီတဲ့ pattern များ၏ သဘောထားတွေ ပိုထင်ရှားစေပါတယ်။ မှတ်ဉာဏ် ပါဝင်လာတဲ့အခါ သင်မြင်နိုင်ပါလိမ့်မယ်။ ဒါဟာ သင့် application မှာ ဘာတွေ တင်ဆက်ပေးထားကြောင်း နားလည်ရခက်မယုံလောက်သေးတဲ့ ပြသာနာများကို ရှင်းလင်းဖို့ လွယ်ကူစေပါတယ်။ +ဒီလမ်းညွှန်မှာ Azure OpenAI ရဲ့ GPT-5.2 ကို စဉ်ဆက်အသုံးပြုပါမယ်၊ ရှေ့ပြေး အဆင့်မြှင့် သုံးသပ်နိုင်စွမ်းကြောင့် မတူညီတဲ့ ပုံစံတွေ၏ အပြုအမူကို ပိုရှင်းလင်းစေပါတယ်။ မှတ်ဉာဏ်ကို ထည့်လိုက်ရင် အနည်းငယ်ကွာခြားချက်တွေ မျှတစွာ မြင်တွေ့နိုင်မှာဖြစ်ပါတယ်။ ဒါကြောင့် တစ်စိတ်တစ်ပိုင်းစီဟာ သင့်အက်ပ်လီကေးရှင်းမှာ ဘာတွေလုပ်ဆောင်ပေးနေသလဲ နားလည်ရလွယ်ကူပါတယ်။ -သင်တစ်ခုတည်းသော application တည်ဆောက်မှာဖြစ်ပြီး အောက်ပါနှစ်မျိုးသော pattern ကို ပြသပါမည်- +သင် တစ်ခုသော အက်ပ်လီကေးရှင်းကို တည်ဆောက်ပါမယ်၊ နှစ်ခုအမျိုးအစား ဆက်ပြသမယ်။ -**Stateless Chat** - တစ်ခုချင်းစီသော တောင်းဆိုမှုမှာ လွတ်လပ်ပြီး အချို့သော ပြန်လည်မှတ်မိမှုမရှိပါ။ ၎င်းသည် quick start မှာ သုံးခဲ့သော pattern ဖြစ်သည်။ +**Stateless Chat** - တောင်းဆိုမှုတစ်ခုချင်းစီဟာ လွတ်လပ်စွာ ရှိပါတယ်။ မော်ဒယ်က စကားပြော မက်ဆေ့ဂ်အရင်ဆုကို မှတ်မိထားခြင်းမရှိပါ။ အခြေခံဆုံး စတင်မှုဖြစ်ပါတယ်။ -**Stateful Conversation** - တောင်းဆိုမှုတိုင်းတွင်စကားဝိုင်း ပုံပြင်ကိုပါ ပါဝင်သည်။ စက်ပညာသည် ပြန်ကြားသော turns များ တွင် context ကို ထိန်းသိမ်းထားသည်။ ၎င်းမှာ ထုတ်လုပ်မှု application များအတွက် လိုအပ်သည်။ +**Stateful Conversation** - တောင်းဆိုမှုတစ်ခုချင်းစီမှာ စကားပြော သမိုင်းကြောင်း ပါဝင်သည်။ မော်ဒယ်က အကြိမ်ကြိမ် ဆက်သွယ်မှုများအတွက် context ကို ထိန်းသိမ်းပါသည်။ ထိုအရာသည် ထုတ်လုပ်မှု အက်ပ်လီကေးရှင်းများတွင် လိုအပ်သည်။ -## လိုအပ်ချက်များ +## လိုအပ်သော ရှေ့ဆက်ချက်များ -- Azure subscription နှင့် Azure OpenAI ဝင်ခွင့် +- Azure subscription နဲ့ Azure OpenAI အတွေ့အကြုံရှိရမည် - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **မှတ်ချက်။** Java, Maven, Azure CLI နဲ့ Azure Developer CLI (azd) များကို ပေးထားသော devcontainer မှာ ကြိုတင် ထည့်သွင်းပြီးပြီဖြစ်သည်။ +> **မှတ်ချက်**: မိမိသုံးနေသော devcontainer ထဲတွင် Java, Maven, Azure CLI နဲ့ Azure Developer CLI (azd) များ ကြိုတင်တပ်ဆင်ထားသည်။ -> **မှတ်ချက်။** ဒီ module ဟာ Azure OpenAI ပေါ်မှာ GPT-5.2 ကို အသုံးပြုသည်။ deployment ကို `azd up` နဲ့ အလိုအလျောက်ပြုလုပ်ထားတာဖြစ်တဲ့အတွက် ကုဒ်အတွင်း model နာမည်ကို တည်းဖြတ်မသွားပါနဲ့။ +> **မှတ်ချက်**: ဒီ module သည် Azure OpenAI မှ GPT-5.2 ကို သုံးထားပါသည်။ Deployment သည် `azd up` မှတစ်ဆင့် မော်ဒယ်နာမည်ကို ကုဒ်အတွင်း ပြင်ဆင်ပေးရန် မလိုအပ်ပါ။ -## အဓိက ပြဿနာနားလည်ခြင်း +## အဓိက ပြဿနာကိုနားလည်ခြင်း -ဘာသာစကား မော်ဒယ်များသည် stateless ဖြစ်သည်။ API ခေါ်ဆိုမှုတစ်ခုစီ မတူညီမှုရှိသည်။ "ကျွန်တော့်နာမည်က John ပါ" လို့ ပေးပို့ပြီးနောက် "ကျွန်တော့်နာမည် ဘာလဲ?" ဟု မေးလျှင် မော်ဒယ်သည် မင်းနာမည် မသိအောင် ဖြစ်မနေခင် မိတ်ဆက်ချက်ကို မသတိရပါ။ တောင်းဆိုမှုတိုင်းကို ပထမဆုံး စကားပြောမှုလို မျှအောင် ပြုလုပ်သည်။ +ဘာသာစကားပုံစံများဟာ stateless ဖြစ်ပါတယ်။ API ခေါ်ဆိုမှု တစ်ချက်ချင်းစီဟာ လွတ်လပ်မှုရှိသည်။ "My name is John" လို့ ပေးပို့ပြီးနောက် "What's my name?" လို့မေးလျှင်၊ မော်ဒယ်က မိမိနာမည်ကို မသိနိုင်ပါဘူး။ တောင်းဆိုချက်တိုင်းကို ပထမဆုံး စကားပြောရေးရာလို့ ထင်မြင်ကြည့်နေသလို ဖြစ်ပါတယ်။ -ဒါဟာ ရိုးရှင်းသော Q&A များအတွက် ပြဿနာမရှိပေမယ့် စတင်ကျောင်း application များအတွက် မသုံးနိုင်ပါ။ ဖောက်သည်ဝန်ဆောင်မှု bot များသည် သင့်ပြောသည်ကို မှတ်မိရန်လိုအပ်သည်။ ကိုယ်ပိုင် အကူအညီလက်ထောက်များတွင် သတင်းအချက်အလက်လိုအပ်သလိုပါ။ turn အနည်းငယ်ရှိသော စကားပြောမှုများတွင် မှတ်ဉာဏ်လိုအပ်ပါသည်။ +ဒီအနေအထားက အရိုးရှင်း Q&A မှာ ကောင်းသောတစ်ခု ဖြစ်ပေမယ့် ဆောင်ရွက်ရန် ရည်ရွယ်ချက်များတွင် အကျိုးမရှိပါဘူး။ ဖောက်သည်ဝန်ဆောင်မှုပေးရေး စက်ရုပ်များဟာ အသုံးပြုသူပြောသောအရာများကို မှတ်သားထားရမည်။ လူရေးကူညီသူတွေမှာ context လိုအပ်သည်။ စကားပြောအကြိမ်များ အတူတူ လို့ဆိုရင် မှတ်ဉာဏ် လိုအပ်ပါသည်။ -အောက်ဖော်ပြပါ ရုပ်ပုံသည် နှစ်မျိုးသောနည်းလမ်းများနှိုင်းယှဉ်သည်- ဘယ်ဘက်တွင် stateless အခေါ်ဆိုမှုဖြစ်၍ နာမည် မမှတ်မိဘဲဖြစ်သည်။ ညာဘက်တွင် ChatMemory ဖြင့် မှတ်သားထားသော stateful call ဖြစ်သည်။ +အောက်ပါ ပုံပြင်မှာ နှစ်မျိုးကြား ကွာခြားချက်ကို ပြသထားသည် - ဘယ်ဘက်တွင် stateless ခေါ်ဆိုမှုဖြစ်ပြီး သင့်နာမည် မေ့နေသည်၊ ညာဘက်တွင် stateful ခေါ်ဆိုမှု၊ ChatMemory မှ ကူညီထားသည်။ Stateless vs Stateful Conversations -*Stateless (လွတ်လပ်ခေါ်ဆိုမှု) နှင့် Stateful (context သတိထားရှိမှု) စကားပြောမှုများအကြား ကွာခြားချက်* +*Stateless (အမဲလိုက်ခေါ်ဆိုမှု) နှင့် Stateful (context သိပြီး ခေါ်ဆိုမှု) စကားပြောများကြား ကွာခြားချက်များ* -## တိုးကင်များနားလည်ခြင်း +## တိုးကင်များကိုနားလည်ခြင်း -စကားပြောမှုများကို ရိုက်ကူးမတိုင်မီ token များကို နားလည်ရန် လိုအပ်သည် - ဘာသာစကား မော်ဒယ်များ လုပ်ဆောင်ရာတွင် သုံးသော စာသား ကဏ္ဍရပ်များဖြစ်သည်- +စကားပြောတွေထဲ ဝင်မတိုင်မီ၊ tokens ဆိုတာကို နားလည်ရမည် - ဘာသာစကားပိုင်းဆိုင်ရာ မော်ဒယ်များ လုပ်ငန်းဖြစ်စဉ်အတွက် အခြေခံ အဖွဲ့အစည်းများဖြစ်သည်။ Token Explanation -*စာသားကို token အဖြစ် ခွဲထုတ်ညွှန်းနှိပ်ထားသော နမူနာ - "I love AI!" သည် ၄ ထပ်ခွဲစီသော တိုးကင်အဖြစ် ဖြစ်သည်* +*စာသားများကို tokens အဖြစ် ခွဲခြားသုံးသပ်မှု ဥပမာ - "I love AI!" သည် ၄ ခုအသီးအသီး တစ်ခုချင်းစီ လုပ်ငန်းယူနစ်များဖြစ်သည်* -Tokens တွေဟာ AI မော်ဒယ်များက စာသားကို တိုင်းတာသုံးသပ်ရာမှာ အသုံးပြုသောအရာ ဖြစ်ပါသည်။ စကားလုံးများ၊ ကန့်သတ်ချက်များနဲ့ နေရာများပါ token ဖြစ်သည့်အတွက် သင့်မော်ဒယ်တွင် တစ်ခုပြီးတစ်ခု စာသားကို တစ်ကြိမ်တည်းPROCESS လုပ်နိုင်မည့် token အရေအတွက် (GPT-5.2 အတွက် ၄သိန်းခန့်၊ input 272,000 နှင့် output 128,000 token ထိ) ရှိသည်။ token တွေက conversation ရဲ့ အရှည်နဲ့ ကုန်ကျစရိတ်ကို သုံးစွဲမြင်သာစေပါတယ်။ +Tokens များသည် AI မော်ဒယ်များအတွက် စာသားတိုင်းကို တိုင်းတာထား၊ လုပ်ဆောင်ရာတွင် အသုံးပြုသည်။ စကားလုံးများ၊ ကြိယာပေါင်းချုပ်များ၊ နေရာများစသည်တို့သည် token ဖြစ်နိုင်သည်။ မော်ဒယ်တွင် ရုပ်ပိုင်းဆိုင်ရာ သတ်မှတ်ချက်ရှိသည် (GPT-5.2 အတွက် token များ ၄၀၀,၀၀၀ အထိ၊ ၂၇၂,၀၀၀ input token နှင့် ၁၂၈,၀၀၀ output token အထိ)။ Token များကို နားလည်ထားခြင်းအားဖြင့် စကားပြော အရှည်နှင့် ကုန်ကျစရိတ်ကို ထိန်းချုပ်နိုင်သည်။ -## မှတ်ဉာဏ်လုပ်ဆောင်ပုံ +## မှတ်ဉာဏ်က 어떻게 လုပ်ဆောင်သည် -Chat memory က stateless ပြဿနာကို ဖျောက်ပစ်ပေးပြီး စကားပြောမှုမှတ်တမ်းကို ထိန်းသိမ်းပါသည်။ မော်ဒယ်ကို တောင်းဆိုရန် မတိုင်မှီ framework သည် အရေးကြီးသော ယခင် စကားများကို နောက်တစ်ကြိမ် ပေါင်းထည့်လိမ့်မယ်။ "ကျွန်တော့်နာမည် ဘာလဲ?" ဟု မေးလျှင် စနစ်က စကားပြောမှတ်တမ်းအပြည့်အစုံကို ပေးပို့လိမ့်မယ်။ အဲနဲ့ မော်ဒယ်က မင်းဟာ "ကျွန်တော့်နာမည်က John ပါ" လို့ စကားပြောခဲ့တာကို မြင်ရမယ်။ +Chat memory က stateless ပြဿနာကို ဖြေရှင်းပေးပြီး စကားပြော သမိုင်းကြောင်းကို ထိန်းသိမ်းထားသည်။ မော်ဒယ်ထံ သို့ တောင်းဆိုမှု ပေးပို့ခေါ်ဆိုမှီ framework က မသက်ဆိုင်မှီ မက်ဆေ့ဂ်များကို တပ်ဆင်ပေးပါသည်။ သင် "What's my name?" လို့ မေးလျှင် စနစ်က စကားပြော သမိုင်းကြောင်း အားလုံးကို ပေးပို့နေပြီး မော်ဒယ်က "My name is John" လို့ လွန်ခဲ့သောအကြိမ် ပြောထားတာ မြင်ရှုနိုင်သည်။ -LangChain4j က အဲ့ဒီ memory ကို အလိုအလျောက် ကိုင်တွယ်ပေးတဲ့ implementation များပေးထားပါတယ်။ သင် user message ယူရမယ့် အနည်းဆုံး အရေအတွက်ကို ရွေးချယ်ပြီး framework က context window ကို ကိုင်တွယ်ပေးတယ်။ အောက်ပါ ပုံတွင် MessageWindowChatMemory သည် မကြာသေးမီ message တွေကို sliding window နည်းဖြင့် ထိန်းထားပုံကို ရှင်းပြထားသည်။ +LangChain4j သည် မှတ်ဉာဏ်ပြီး စနစ်များကို အလိုအလျောက် စီမံခန့်ခွဲပေးနိုင်တဲ့ memory implementation များ ပေးဆောင်သည်။ သင် သို့မဟုတ် မက်ဆေ့ဂ် များ အများအပြား သိုလှောင်ထားလိုပါက framework က context အား ထိန်းသိမ်းပေးပါသည်။ အောက်ပါ ပုံတွင် MessageWindowChatMemory သည် စမ်းသပ်သိမ်းဆည်းထားသော မက်ဆေ့ဂ်များ အနောက်တံခါး တဲ့ ပြတင်းပေါက်နည်းလမ်းကို ဖော်ပြထားသည်။ Memory Window Concept -*MessageWindowChatMemory သည် မကြာသေးတဲ့ message တွေကို sliding window နည်းဖြင့် ထိန်းသိမ်းရာ ဆိုးရွားသော message များကို အလိုအလျှောက် ဖြတ်တောက်ပေးသည်* +*MessageWindowChatMemory သည် မက်ဆေ့ဂ်များကို ယခုနောက်ဆုံး သုံးသပ်ပေးပြီး အဟောင်းများကို အလိုအလျောက် လျှော့ချပေးသည့် sliding window ကို ထိန်းသိမ်းသည်* -## LangChain4j ကို ဘယ်လိုအသုံးပြုသည် +## LangChain4j ကို ဘယ်လို သုံးထားသလဲ -ဒီ module က quick start ကို တိုးချဲ့ပြီး Spring Boot ကို ပေါင်းထည့်၊ စကားပြောမှု မှတ်ဉာဏ်ကို စွဲထိုးသည်။ အပိုင်းအစတွေ ဘယ်လိုပေါင်းသင့်ကြောင်း ဒီမှာရှင်းပြထားသည်- +ဒီ module မှာ Spring Boot နဲ့ conversation memory ကို ပေါင်းစည်းအသုံးပြုထားပါတယ်။ အပိုင်းများ မည်သို့ အတူတကွ လုပ်ဆောင်သလဲ ဆိုတာ: -**Dependencies** - LangChain4j library နှစ်ခု ထည့်သွင်းပါ: +**Dependencies** - LangChain4j ပိုင်းနှစ်ခုကို ထည့်သွင်းပါ: ```xml @@ -94,7 +94,7 @@ LangChain4j က အဲ့ဒီ memory ကို အလိုအလျောက ``` -**Chat Model** - Azure OpenAI ကို Spring bean အဖြစ် ပြင်ဆင်ပါ ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chat Model** - Azure OpenAI ကို Spring bean အနေနှင့် အောက်ပါအတိုင်း ဖွဲ့စည်းပါ ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder က `azd up` မှ လက်တွေ့သတ်မှတ်ထားသော environment variable က credential များကို ဖတ်ရှုသည်။ `baseUrl` ကို သင်ရဲ့ Azure endpoint သို့ သတ်မှတ်ခြင်းဟာ OpenAI client ကို Azure OpenAI နဲ့ သင့်ကိုက်ညီစေပါတယ်။ +Builder က `azd up` မှ သတ်မှတ်ထားသော environment variable များမှ အတည်ပြုပြီး ဖတ်ယူသည်။ `baseUrl` ကို Azure endpoint သတ်မှတ်ခြင်းဖြင့် OpenAI client ကို Azure OpenAI နဲ့ အသုံးပြုနိုင်သည်။ -**Conversation Memory** - စကားပြောမှုသမိုင်းကို MessageWindowChatMemory ဖြင့် ပြုစုပါ ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Conversation Memory** - MessageWindowChatMemory အသုံးပြုပြီး စကားပြောသမိုင်းကြောင်း ပြန်လည် မှတ်သားခြင်း ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,51 +124,51 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` ဖြင့် မှတ်ဉာဏ်ကို တည်ဆောက်ကာ နောက်ဆုံး message ၁၀ ခုကို သိမ်းဆည်းပါ။ user message နဲ့ AI message တို့ကို အမျိုးအစားတိကျစွာ စာရွက်စာတမ်းပုံစံဖြင့် ထည့်ပါ- `UserMessage.from(text)` နဲ့ `AiMessage.from(text)` အသုံးပြုပြီး။ သမိုင်းဇာတ်ကောင်ကို `memory.messages()` ဖြင့် ရယူပြီး model ထံ ပို့ပါ။ service က စကားပြောမှု ID တိုင်းအတွက် အထူးသီးသန့် မှတ်ဉာဏ် instance များသိမ်းဆည်းလို့ အသုံးပြုသူ အများကြီး အချိန်တစ်ပြိုင်တည်း စကားပြောနိုင်သည်။ +`withMaxMessages(10)` ဖြင့် နောက်ဆုံး message ၁၀ ခုသာ သိမ်းဆည်းရန် ဖန်တီးသည်။ user နှင့် AI မှ မက်ဆေ့ဂ်များကို `UserMessage.from(text)`, `AiMessage.from(text)` များဖြင့် ထည့်သွင်းသည်။ သမိုင်းကြောင်းကို `memory.messages()` ဖြင့် ရယူပြီး မော်ဒယ်ထံ ပို့သည်။ ရှေ့ဆက် ID တစ်ခုစီအလိုက် memory instance များကို ဝန်ဆောင်မှု မှ ထိန်းသိမ်းသည်၊ ထိုကြောင့် အများများသော အသုံးပြုသူများ တပြိုင်နက် ချက်ချင်း စကားပြောနိုင်ပါသည်။ -> **🤖 GitHub Copilot Chat ဖြင့် စမ်းသပ်ပါ:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ဖွင့်ပြီးမေးပါ- -> - "MessageWindowChatMemory က window ပြည့်သောအခါ မက်ဆေ့ခ်ျတွေ ဘယ်လို ရွေးချယ် ဖယ်ရှားသလဲ?" -> - "In-memory မဟုတ်ဘဲ database ကို အသုံးပြုပြီး သေချာသော memory storage ကို ဖန်တီးနိုင်မလား?" -> - "ဟောင်းပြီး စကားပြောမှုသမိုင်း စုစည်းဖို့ သေချာတဲ့ စာရင်းချုပ်လုပ်ခြင်း (summarization) ထည့်နိုင်မလား?" +> **🤖 GitHub Copilot Chat နဲ့ စမ်းကြည့်ပါ:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ဖိုင်ကို ဖွင့်ပြီး မေးမြန်းနိုင်သော မေးခွန်းများ - +> - "MessageWindowChatMemory က ပြတင်းပေါက် ပြည့်နက်မှုအချိန် မက်ဆေ့ဂ်တွေ ဘယ်လို ရွေးချယ် ချွတ်ထုတ်သလဲ?" +> - "In-memory ထားခြင်း မဟုတ်ဘဲ database အသုံးပြု၍ custom memory storage ကို ဘယ်လို တည်ဆောက်မလဲ?" +> - "ဟောင်းသော စကားပြော သမိုင်းကြောင်းကို အနှောင့်အယှက် ဖျတ်ရေး အတွက် summary ရေး ထည့်ပြုလုပ်နိုင်မလား?" -Stateless chat endpoint မှာ မှတ်ဉာဏ် မပါဝင်ပါ - quick start ကဲ့သို့ `chatModel.chat(prompt)` သာ အသုံးပြုသည်။ Stateful endpoint မှာ messages တွေကို memory ထဲထည့်ပြီး သမိုင်း ရယူကာ တောင်းဆိုမှုတိုင်းနှင့် context ပေါင်းထည့်သည်။ model setup တူပြီး pattern မတူပါ။ +Stateless chat endpoint က memory မထည့်ပဲ `chatModel.chat(prompt)` လုပ်ဆောင်ပြီး quick start နည်းလမ်းဖြစ်သည်။ Stateful endpoint က memory ထဲ message တွေ ထည့်ပြီး သမိုင်းကြောင်း ရယူကာ request တစ်ခုချင်းစီနဲ့ context တစ်ရပ်ကို လည်း ထည့်ပေးပါသည်။ မော်ဒယ် configuration တူညီပေမဲ့ ပုံစံ ကွာခြားသည်။ -## Azure OpenAI အခြေခံအဆောက်အအုံ တပ်ဆင်ခြင်း +## Azure OpenAI အပြည့်အစုံစုစည်းမှု တပ်ဆင်ခြင်း **Bash:** ```bash cd 01-introduction -azd up # စာရင်းသွင်းခြင်းနှင့် တည်နေရာကို ရွေးချယ်ပါ (eastus2 အကြံပြုချက်) +azd up # စာရင်းသွင်းမှုနှင့် တည်နေရာ ရွေးချယ်ပါ (eastus2 သင်ကြားမှုအတွက် အကြံပြုသည်) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # အသင်းဝင်ပြီး တည်နေရာ (eastus2 အကြံပြုသည်) ရွေးချယ်ပါ။ +azd up # စာရင်းသွင်းခြင်းနှင့် တည်နေရာကို ရွေးချယ်ပါ (eastus2 အကြံပြုသည်) ``` -> **မှတ်ချက်:** timeout ပြဿနာတက်ရင် (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) `azd up` ကို ထပ်မံ Run ပါ။ Azure resource များ နောက်ခံမှာ တပ်ဆင်နေဆဲဖြစ်တာကြောင့် retry လုပ်တာနဲ့ deployment အချိန်ပြီးသွားလိမ့်မယ်။ +> **မှတ်ချက်:** အချိန်လွန်ခြင်းမှားယွင်းမှု `RequestConflict: Cannot modify resource ... provisioning state is not terminal` စသဖြင့် ဖြစ်ပါက `azd up` ကို ထပ်မံ ရှိုးရိုက်ပါ။ Azure ကို အရင်းအမြစ်များ နောက်ခံတွင် ပယုဇနာရှိနေတာ တစ်ခါတလေဖြစ်ပြီး စခန်းမှ အဆင့်ဆင့် ပြီးဆုံးချိန်သို့ ရောက်သည်မှ deployment ပြီးပါသည်။ -ဒီသည်များကို လုပ်ဆောင်ပါမည်- -1. GPT-5.2 နှင့် text-embedding-3-small မော်ဒယ်ပါ Azure OpenAI resource တပ်ဆင်ခြင်း -2. Credentials ပါ `.env` ဖိုင်ကို project root တွင် အလိုအလျောက် ထုတ်ပေးခြင်း -3. လိုအပ်သော environment variable အားလုံး စုပြီးသတ်မှတ်ခြင်း +ဒါတွေနဲ့ - +1. Azure OpenAI အရင်းအမြစ် (GPT-5.2 နှင့် text-embedding-3-small မော်ဒယ်) ကို တပ်ဆင်ပါမယ်။ +2. Project root တွင် `.env` ဖိုင်ကို အလိုအလျောက် ဖန်တီးပါမယ်။ +3. လိုအပ်သော environment variable များအားလုံး သတ်မှတ်ပေးပါမယ်။ -**Deployment ပြဿနာရှိကျပါသလား?** subdomain မျိုးတွဲ အမည်ဖော်စားမှု၊ အက်မင်ကောင့် မှတဆင့် မန်နွယ် deployment လုပ်နည်းများနှင့် model setting လမ်းညွှန်ချက်များကို လေ့လာချင်ရင် [Infrastructure README](infra/README.md) ကို ကြည့်ပါ။ +**Deployment ပြဿနာ ရှိလား?** [Infrastructure README](infra/README.md) တွင် အနက်ရှိုင်း အသေးစိတ် ပြဿနာဖြေရှင်းနည်း၊ subdomain နာမည် တွန်းရှားမှု၊ လက်အပ် Azure Portal မှ deploymentနည်းလမ်းများ၊ မော်ဒယ်ဖောင်ကြိး များ ပါဝင်သည်။ -**Deployment ကအောင်မြင်သည်ကို သေချာစစ်ဆေးရန် -** +**Deployment ပြီးစီးဖြစ်သည်ကို စစ်ဆေးရန်:** **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY စသည်တို့ကို ပြသသင့်သည်။ +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY နှင့် အခြားများကိုပြသသင့်သည်။ ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY စသည့် အချက်အလက်များကို ပြသသင့်သည်။ +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY နှင့် အခြားများကို ပြသသင့်သည်။ ``` -> **မှတ်ချက်:** `azd up` က `.env` ဖိုင်ကို အလိုအလျောက် ပြုလုပ်ပေးသည်။ အချိန်ကြာပြီးနောက် update လုပ်ရန်လိုတယ်ဆိုရင် `.env` ဖိုင်ကိုလက်ဖြင့် ပြင်ဆင်နိုင်ပါသည်၊ ဒါမှမဟုတ် အောက်ပါ command များကို ပြန်လည် เรียပေးနိုင်ပါသည်- +> **မှတ်ချက်:** `azd up` မှ `.env` ဖိုင်ကို အလိုအလျောက် ဖန်တီးပေးပါသည်။ ပြန်လည်ပြင်ဆင်လိုပါက `.env` ဖိုင်ကို မန်ယွက် ပြုပြင်နိုင်သလို မိတ်ဆက် command ကို ထပ်မံ အသုံးပြုနိုင်သည်။ > > **Bash:** > ```bash @@ -182,57 +182,57 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY စသည့် အချ > .\.azd-env.ps1 > ``` -## လက်ရှိ စက်ပေါ်တွင် အပလီကေးရှင်း ကို run ချခြင်း +## အက်ပ်လီကေးရှင်းကို ဒေသတွင်း လည်ပတ်ခြင်း -**Deployment အောင်မြင်မှုကိုအတည်ပြုရန်:** +**Deployment ပြီးစစ်ဆေးရန်** -`.env` ဖိုင်သည် လက်ရှိ directory ထဲမှာ ရှိပြီး Azure credential များ ပါဝင်သည်ဟု သေချာစေပါ။ Module directory (`01-introduction/`) မှ run ပါ- +Project root သို့ Azure အသုံးပြုခွင့် အချက်အလက်သည် `.env` ဖိုင် တွင် ရှိပြီးသား ဖြစ်ရန် လိုအပ်ပါသည်။ Module လမ်းကြောင်း (`01-introduction/`) မှ လည်ပတ်ပါ။ **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကိုပြသသင့်သည် +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကို ပြရန် ဖြစ်ပါသည်။ ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကိုပြသသင့်သည် +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT၊ API_KEY၊ DEPLOYMENT ကို ပြသသင့်သည် ``` -**Applications များစတင်ရန်:** +**အက်ပ်များ စတင်ခြင်း** -**နည်းလမ်း ၁: Spring Boot Dashboard အသုံးပြုခြင်း (VS Code အသုံးပြုသူများအတွက် အကြံပြုချက်)** +**ရွေးချယ်မှု ၁: Spring Boot Dashboard အသုံးပြုခြင်း (VS Code အသုံးပြုသူများအတွက် အကြံပြုသည်)** -Dev container တွင် Spring Boot Dashboard extension ပါဝင်ပြီး၊ VS Code မှာ ဘယ်ဘက် Activity Bar တွင် Spring Boot icon မှတဆင့် မျက်နှာပြင် ထိန်းချုပ်နိုင်သည်။ +Dev container ထဲ၌ Spring Boot Dashboard extension ပါဝင်သည်၊ ၎င်းက Spring Boot အက်ပ်အလုံးစုံကို GUI ဖြစ်စေသည်။ VS Code ၏ ဘယ်ဘက် ဘားတွင် (Activity Bar မှာ) Spring Boot အိုင်ကွန်း ကို ရှာ၍ သွားရောက်နိုင်သည်။ -Spring Boot Dashboard မှ -- Workspace ရှိ Spring Boot applications အားလုံးကိုကြည့်ရှုနိုင်သည် -- အပလီကေးရှင်းများကို တစ်ချက်အတွင်း Start/Stop နိုင်သည် -- လက်ရှိ အလုပ်လုပ်မှု log များကို real-time ကြည့်ရှုနိုင်သည် -- Application အခြေအနေကို စောင့်ကြည့်နိုင်သည် +Dashboard မှ +- Workspace တွင် ရှိသမျှ Spring Boot အက်ပ်များကို မြင်ကြရမှာဖြစ်သည် +- တစ်ချက်နှိပ်ပဲဖြင့် စတင်/ရပ်နား စေရန် မဖြစ်မနေတာ +- အက်ပ် log များကို အချိန်နဲ့တပြေးညီ ကြည့်ရှုနိုင်သည် +- အက်ပ်အလုံးစုံ၏ အနေအထားကို စောင့်ကြည့်နိုင်သည် -"introduction" module အတွက် play ခလုတ်ကို click နှိပ်၍ စတင်ပါ၊ ဒါမှမဟုတ် အားလုံးသော modules များကို တပြိုင်နက် စတင်နိုင်သည်။ +"introduction" အတွက် play ခလုတ်ကို နှိပ်ပြီး module ကို စတင်နိုင်သည်၊ သို့မဟုတ် module အားလုံးကို တပြိုင်နက် စတင်ရန်လည်း ရနိုင်သည်။ Spring Boot Dashboard -*VS Code မှ Spring Boot Dashboard — module အားလုံးကို တစ်နေရာမှ စတင်၊ ရပ်နား နှင့် စောင့်ကြည့်ပေးခြင်း* +*VS Code ရှိ Spring Boot Dashboard — အားလုံး module များကို တစ်နေရာက စတင်၊ ရပ်နား၊ နှင့် စောင့်ကြည့်နိုင်သည်* -**နည်းလမ်း ၂: shell scripts အသုံးပြုခြင်း** +**ရွေးချယ်မှု ၂: shell script အသုံးပြုခြင်း** -Web applications များအားလုံး စတင်ရန် (module 01 မှ 04 အထိ) - +Web แอปများအားလုံးကို စတင် (modules 01-04): **Bash:** ```bash -cd .. # root ဂိုဏ်းမှ +cd .. # အမြစ်ဖိုလ်ဒါမှ ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # မူလဖိုင်လမ်းကြောင်းမှ +cd .. # မူလအမည်အတိုင်းဆိုင်ရာဒိုင်respectတွင်မှ .\start-all.ps1 ``` -သို့မဟုတ် ဤ module ကိုသာ စတင်ရန်- +သို့မဟုတ် ဒီ module ကိုသာ စတင်ပါ: **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -script နှစ်ခုလုံးသည် root `.env` ဖိုင်ထဲက environment variable များကို သိမ်းဆည်းပြီး jar မရှိပါက build လုပ်ပေးပါသည်။ +၂ script အားလုံးသည် root `.env` ဖိုင်မှ environment variable များကို လိုအပ်သလို ထည့်သွင်းပြီး JAR မရှိလျှင် ဆောက်လုပ်ပေးပါသည်။ -> **မှတ်ချက်:** မတိုင်မှီ မော်ဂျူးများအားလုံးကို လက်ဖြင့် build လုပ်ဖို့ စိတ်ဝင်စားတယ်ဆိုရင်- +> **မှတ်ချက်:** module အားလုံးကို မီနူးတွေ စတင်မတိုင်မီ ကိုယ်တိုင် ဆောက်လုပ်ချင်ပါက - > > **Bash:** > ```bash @@ -262,61 +262,61 @@ script နှစ်ခုလုံးသည် root `.env` ဖိုင်ထဲ > mvn clean package -DskipTests > ``` -http://localhost:8080 ကို browser မှ ဖွင့်ပါ။ +Browser တွင် http://localhost:8080 ကို ဖွင့်ကြည့်ပါ။ **ရပ်ရန်:** **Bash:** ```bash -./stop.sh # ဒီမော်ဂျူးသာ -# ဒါမှမဟုတ် -cd .. && ./stop-all.sh # အားလုံးမော်ဂျူးများ +./stop.sh # ယခုမော်ဂျူးသာ +# သို့မဟုတ် +cd .. && ./stop-all.sh # မော်ဂျူးအားလုံး ``` **PowerShell:** ```powershell -.\stop.ps1 # ဒီမော်ဂျူးသာ +.\stop.ps1 # ဤမော်ဒျူးသာ # ဒါမှမဟုတ် -cd ..; .\stop-all.ps1 # မော်ဂျူးအားလုံး +cd ..; .\stop-all.ps1 # မော်ဒျူးအားလုံး ``` -## အပလီကေးရှင်း အသုံးပြုခြင်း +## အက်ပ်လီကေးရှင်း အသုံးပြုခြင်း -အဆိုပါ application သည် နှစ်မျိုးသော chat implementation များ ရှိသည့် ဝက်ဘ် UI တစ်ခုကို ပေးသည်။ +အက်ပ်သည် ဝဘ်လက်မျက်နှာပြင်တွင် နှစ်ခုသော chat အမျိုးအစားများကို ဘေးတန်းတူ ပြထားသည်။ Application Home Screen -*Simple Chat (stateless) နှင့် Conversational Chat (stateful) ပါဝင်သည့် Dashboard* +*Dashboard တွင် Simple Chat (stateless) နှင့် Conversational Chat (stateful) ရွေးချယ်မှုများ ပြသသည်* ### Stateless Chat (ဘယ်ဘက် Panel) -ဤကို ပထမဆုံး စမ်းသပ်ပါ။ "ကျွန်တော့်နာမည်က John ပါ" ဟု ပြောပြီးနောက် "ကျွန်တော့်နာမည် ဘာလဲ?" ဟု မေးပါ။ မော်ဒယ်သည် မှတ်မိမရှိကာ တစ်ခုချင်းစီ ခွဲခြားသော message အနေနှင့် ၎င်းကိုဆင်ခြင်ပါသည်। ဤသည်သည် အခြေခံ language model integration တွင် ရရှိသော အဓိက ပြဿနာကို ပြသသည်- စကားပြောမှု context မပါခြင်း။ +အစပိုင်း အဖြစ် သုံးကြည့်ပါ။ "My name is John" လို့ တင်ပြပြီးနောက်၊ ချက်ချင်း "What's my name?" လို့ မေးပါ။ မော်ဒယ်က မှတ်မိမည် မဟုတ်ပါ၊ အကြောင်းအရာတိုင်းအနေနှင့် လွတ်လပ်သည်။ ဒါက အခြေခံ မော်ဒယ် များတွင် conversation context မရှိမှု၏ ပြဿနာကို ပြသပါသည်။ Stateless Chat Demo -*AI မှ မင်းနာမည်ကို ယခင် message မှ မမှတ်မိပါ* +*AI က သင့်နာမည်ကို ယခင်မက်ဆေ့ဂ်မှ မှတ်မိပေးခြင်း မရှိပါ* ### Stateful Chat (ညာဘက် Panel) -ယခုတစ်ချက်မှာ အလားတူ စမ်းသပ်ပါ။ "ကျွန်တော့်နာမည်က John ပါ"၊ "ကျွန်တော့်နာမည် ဘာလဲ?" မေးလိုက်သည်။ ဒီအကြိမ်မှာ မှတ်သားရပါသည်။ ကွာခြားချက်မှာ MessageWindowChatMemory ဖြစ်ပြီး စကားပြောမှတ်တမ်း ဖြစ်စဉ်ကို ထိန်းသိမ်းကာ တောင်းဆိုမှုတိုင်းတွင် ထည့်သွင်းသည်။ ထုတ်လုပ်မှု conversational AI များသည် ပုံမှန် အသုံးပြုနည်းဖြစ်သည်။ +ယခု အစဉ်တူ စမ်းသပ်ပါ။ "My name is John" လို့ ပြောပြီးနောက် "What's my name?" ကို မေးပါ။ အခုတော့ မှတ်ထားနိုင်ပါတယ်။ ကွာခြားချက်က MessageWindowChatMemory ဖြစ်သည် - စကားပြော သမိုင်းကြောင်းကို ထိန်းသိမ်းပြီး request တစ်ခုချင်းစီနှင့် context ကို ထည့်ပါသည်။ ဒီလိုပဲ ထုတ်လုပ်မှု conversational AI များ အလုပ်လုပ်လေ့ရှိသည်။ Stateful Chat Demo -*AI သည် စကားပြောမှု အစောပိုင်းက မင်းနာမည်ကို မှတ်သားထားသည်* +*AI က စကားပြောအလယ်က သင့်နာမည်ကို မှတ်သားထားသည်* -Panel နှစ်ခုစလုံးတွင် GPT-5.2 ကို အသုံးပြုသည်။ ကွာခြားချက်တစ်ခုတည်းမှာ မှတ်ဉာဏ်ဖြစ်သည်။ ၎င်းဟာ သင်၏ application တည်ဆောက်မှုကို ဘာတွေ ပေးရုံပဲ ဖြစ်စေ အရေးကြီးတယ်ဆိုတာ မျက်မှောက်ရှင်းပြပေးသည်။ +နှစ်ခုစလုံးသည် GPT-5.2 မော်ဒယ်တူညီ အသုံးပြုသည်။ ကွာခြားချက်တစ်ခုသာ memory ရှိ/မရှိဖြစ်သည်။ ဒါက memory က သင့်အက်ပ်ကို ဘယ်လို တိုးတက်စေသည်၊ အဖိုးတန်မှု ဘယ်လောက်ရှိသလဲကို ရှင်းလင်းပေးသည်။ -## နောက်တစ်ဆင့် +## နောက်တည့်ခြင်း လမ်းကြောင်း **နောက် Module:** [02-prompt-engineering - GPT-5.2 ဖြင့် Prompt Engineering](../02-prompt-engineering/README.md) --- -**Navigation:** [← ယခင်: Module 00 - Quick Start](../00-quick-start/README.md) | [ပင်မစာမျက်နှာသို့ ပြန်မည်](../README.md) | [နောက်တစ်ခု: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigation:** [← ပြန်သွား Main ဆီ](../README.md) | [ရှေ့သို့: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- -**သတိပြုကြောင်း** -ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှုဖြစ်သော [Co-op Translator](https://github.com/Azure/co-op-translator) အား အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ ငါတို့သည် တိကျမှုအတွက် ကြိုးပမ်းသော်လည်း၊ စက်ရုပ်ဘာသာပြန်ခြင်းအတွက် မှားယွင်းမှုများ သို့မဟုတ် မတိကျမှုများ ပါဝင်နိုင်သည်ကို ကျေးဇူးပြု၍ သိရှိထားပါရန်။ မူရင်းစာတမ်းကို တိုင်းရင်းဘာသာဖြင့် အာမခံ စာရွက်စာတမ်းအဖြစ် ကြည့်ရန် သင့်တော်ပါသည်။ အရေးကြီးသတင်းအချက်အလက်များအတွက် မိမိလူ့ဘာသာပြန်သူ ပရော်ဖက်ရှင်နယ်က ဘာသာပြန်ခြင်း အကြံပြုပါသည်။ ဤဘာသာပြန်ချက် အသုံးပြုခြင်းမှ ဖြစ်ပေါ်လာနိုင်သည့် မစိမ်းမဒြပ်နားလည်မှုများ သို့မဟုတ် မှားလှည့်နားလည်မှုများအတွက် ကျွန်ုပ်တို့သည် တာဝန်မယူပါကြောင်း သတိပေးအပ်ပါသည်။ +**ပြောကြားချက်** +ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှန်ကန်မှုအတွက် ကြိုးပမ်းနေသော်လည်း၊ စက်ကိရိယာဘာသာပြန်ခြင်းများတွင် အမှားများ သို့မဟုတ် မှားယွင်းချက်များ ပါဝင်နိုင်ကြောင်း သတိပြုပါရန် လိုအပ်ပါသည်။ မူလစာတမ်းကို မူရင်းဘာသာဖြင့်သာ ယုံကြည်စိတ်ချရသော အချက်အလက်အဖြစ် သတ်မှတ်သင့်သည်။ အရေးကြီးသည့် သတင်းအချက်အလက်များအတွက် ပရော်ဖက်ရှင်နယ် လူသားဘာသာပြန်သူဝန်ဆောင်မှုကို အကြံပြုပါသည်။ ဤဘာသာပြန်ချက်ကို အသုံးပြုခြင်းမှ ဖြစ်ပေါ်လာသော နားလည်မှုကွာခြားမှုများ သို့မဟုတ် မမှန်ကန်သော အသုံးပြုမှုများအတွက် ကျွန်ုပ်တို့ တာဝန်မခံပါ။ \ No newline at end of file diff --git a/translations/my/02-prompt-engineering/README.md b/translations/my/02-prompt-engineering/README.md index 1009c6f75..b438e17e6 100644 --- a/translations/my/02-prompt-engineering/README.md +++ b/translations/my/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Module 02: GPT-5.2 ဖြင့် Prompt Engineering - -## Table of Contents - -- [ဗီဒီယို လမ်းညွှန်](../../../02-prompt-engineering) -- [သင်လေ့လာမည့်အရာများ](../../../02-prompt-engineering) -- [လိုအပ်သောအကြောင်းအရာများ](../../../02-prompt-engineering) -- [Prompt Engineering ကို နားလည်ခြင်း](../../../02-prompt-engineering) -- [Prompt Engineering အခြေခံများ](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Templates](../../../02-prompt-engineering) -- [အဆင့်မြင့် ပုံစံများ](../../../02-prompt-engineering) -- [အပလီကေးရှင်းကို စတင် လုပ်ဆောင်ခြင်း](../../../02-prompt-engineering) -- [အပလီကေးရှင်း ဖန်တီးမှုများ](../../../02-prompt-engineering) -- [ပုံစံများကို ရှာဖွေခြင်း](../../../02-prompt-engineering) - - [နိမ့်သော စိတ်အားထက်သန်မှုနဲ့ မြင့်သော စိတ်အားထက်သန်မှု](../../../02-prompt-engineering) - - [တာဝန် အဆင့်ဆင့် လုပ်ဆောင်ခြင်း (ကိရိယာစတင်အပိုင်းများ)](../../../02-prompt-engineering) - - [ကိုယ်တိုင် သုံးသပ်သော ကုဒ်](../../../02-prompt-engineering) - - [ဖွဲ့စည်းထားသည့် ချဉ်းကပ်ချက်](../../../02-prompt-engineering) - - [အကြိမ်ရေ များသော စကားပြော](../../../02-prompt-engineering) - - [အဆင့်ဆင့် ဟန်ချက်ညီသော စဉ်းစားခြင်း](../../../02-prompt-engineering) - - [ကန့်သတ်ထားသော အထွက်](../../../02-prompt-engineering) -- [သင် တကယ်မြင်သာလေ့လာနေသည်များ](../../../02-prompt-engineering) -- [နောက်တစ်ဆင့်များ](../../../02-prompt-engineering) - -## ဗီဒီယို လမ်းညွှန် - -ဤ module ကို စတင်သည့် နည်းလမ်းကို ရှင်းပြသည့် live session ကို ကြည့်ပါ။ +# Module 02: GPT-5.2 နှင့် Prompt Engineering + +## မဂ္ဂဇင်း + +- [ဗီဒီယို လမ်းညွှန်ချက်](#ဗီဒီယို-လမ်းညွှန်ချက်) +- [သင်လေ့လာမည့်အရာများ](#သင်လေ့လာမည့်အရာများ) +- [လိုအပ်ချက်များ](#လိုအပ်ချက်များ) +- [Prompt Engineering ကိုနားလည်ခြင်း](#prompt-engineering-ကို-နားလည်ခြင်း) +- [Prompt Engineering အခြေခံများ](#prompt-engineering-အခြေခံများ) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [အဆင့်မြင့် ပုံစံများ](#အဆင့်မြင့်-ပုံစံများ) +- [အပ်ပလီကေးရှင်း ပြေးရန်](#အပလီကေးရှင်းကို-လည်ပတ်ပါ) +- [အပ်ပလီကေးရှင်း အကြေကွင်းများ](#အပလီကေးရှင်း-screenshot-များ) +- [ပုံစံများကို စူးစမ်းရှင်းလင်းခြင်း](#ပုံစံများကို-စူးစမ်းလေ့လာခြင်း) + - [နိမ့်သော စိတ်အားထက်သန်မှုနှင့် မြင့်မားသော စိတ်အားထက်သန်မှု](#low-eagerness-နှင့်-high-eagerness) + - [Task Execution (ကိရိယာ အစောင့်အရှောက်များ)](#ရည်မှန်းချက်ဖြင့်-လုပ်ငန်းဆောင်ရွက်ခြင်း-tool-preambles) + - [ကိုယ်တိုင် သုံးသပ်ခြင်း ကုဒ်](#ကိုယ်တိုင်-သုံးသပ်သော-ကုဒ်) + - [ဖွဲ့စည်းထားသော သုံးသပ်ချက်](#ဖွဲ့စည်းမှုတကျ-သုံးသပ်ခြင်း) + - [အကြိမ်ကြိမ် စကားပြောခြင်း](#မလှုပ်မရှား-စကားပြောဆိုမှု) + - [ခြေလှမ်းခြေလှမ်း နည်းလမ်းဖြင့် မှတ်ချက်ပြုခြင်း](#အဆင့်လိုက်-အတွေးအမြင်) + - [ကန့်သတ်ထားသော ထုတ်လွှင့်ချက်](#အကန့်အသတ်ထားသည့်-အထွက်အဖြေ) +- [သင်တကယ် သင်ယူနေသည့်အရာ](#သင်ဘာတွေ-စစ်မှန်ပြီး-လေ့လာနေပါသလဲ) +- [နောက်တိုးမှုများ](#နောက်တစ်ဆင့်များ) + +## ဗီဒီယို လမ်းညွှန်ချက် + +ဒီ module ကို စတင်အသုံးပြုနည်းကို ရှင်းပြထားသော တိုက်ရိုက်အစည်းအဝေးကို ကြည့်ရှုနိုင်ပါသည်။ Prompt Engineering with LangChain4j - Live Session ## သင်လေ့လာမည့်အရာများ -အောက်ပါ ပုံက ဤ module တွင် သင် မြင်သာသည့် အဓိက ခေါင်းစဉ်များနှင့် ကျွမ်းကျင်မှုများ၏ ပြည့်စုံ ပြထားသည် - prompt ပြုပြင်မှုနည်းလမ်းများမှ စ၍ သင် လိုက်နာရမည့် အဆင့်ဆင့် လုပ်ငန်းစဉ်အထိ။ +အောက်ပါ ပုံကြမ်းသည် ဒီ module မှာ သင်တိုးတက်လာမည့် အဓိက အခန်းကဏ္ဍများနှင့် ကျွမ်းကျင်မှုများကို ရှုမြင်နိုင်စေသည် — prompt refine နည်းပညာများမှ စ၍၊ သွားဆောင်ရမည့် ခြေလှမ်း-ခြေလှမ်း လုပ်ငန်းစဉ်အထိ။ What You'll Learn -ယခင် modules များတွင် LangChain4j ၏ ဘေစစ် အင်တာလုပ်ရှင်းများကို GitHub Models နှင့် တွဲဖက် လေ့လာပြီး၊ Azure OpenAI ဖြင့် စကားပြော AI ကို ထောက်ပံ့သော မှတ်ဉာဏ်ကို မြင်တွေ့ခဲ့သည်။ ယခုမှာ သင်မေးမြန်းတဲ့ ပြဿနာများ --- prompt များကို Azure OpenAI ၏ GPT-5.2 နှင့် ဘယ်လို တင်သွင်းမလဲတွင် အာရုံစိုက်မည်။ သင်၏ prompt ဖွဲ့စည်းပုံသည် မျှော်မှန်းထားသော အဖြေ၏ အရည်အသွေးကို ထိခိုက်စေသည်။ အခြေခံ prompting နည်းလမ်းများကို ပြန်လည်ဆွေးနွေးပြီးနောက် GPT-5.2 ၏ ချောမွေ့မှုများကို အသုံးချအသေးစိတ် ဖော်ပြသည့် အဆင့်မြင့် ပုံစံ အရှစ်ခုသို့ ရောက်ရှိမည်။ +ယခင် module တွင် Azure OpenAI ဖြင့် စကားပြော AI အကြောင်းကို မေ့မွတ်မှုဖြင့် ချိတ်ဆက်နည်းကို ကြည့်ရှုခဲ့ပြီးဖြစ်သည်။ ယခုမှာတော့၊ Azure OpenAI ၏ GPT-5.2 ကို အသုံးပြု၍ မေးခွန်းများကို မည်သို့ မေးမည် (prompts) ဖြစ်သည်ကို ဦးစားပေးထားသည်။ သင်တို့၏ prompt ဖွဲ့စည်းပုံသည် တုံ့ပြန်မှုအရည်အသွေးကို အလွန် သက်ရောက်သည့် အချက်ဖြစ်သည်။ အရင်းခံ prompting နည်းပညာများကို ပြန်လည်သုံးသပ်ပြီးနောက် GPT-5.2 ၏ စွမ်းရည်ကို အပြည့်အဝ အသုံးပြုနိုင်သည့် အဆင့်မြင့် ပုံစံ ၈ မျိုးကို တက်ကြွစွာ လေ့လာသွားမည်။ -GPT-5.2 ကို အသုံးပြုသည့်အကြောင်းက reasoning control ကို မိတ်ဆက်ပေးခြင်းဖြစ်ပြီး model ကို စဉ်းစားမှု အဆင့်ကို ထိန်းချုပ်နိုင်ပါသည်။ ၎င်းသည် အမျိုးမျိုးသော prompting များကို သက်ရောက်မှုကို ကြည်နူးစေပြီး ဘယ်အချိန် မည်သည့်နည်းလမ်းကို အသုံးပြုသင့်ကြောင်း နားလည် မိစေပါသည်။ GitHub Models နှင့် နှိုင်းယှဉ်လျှင် Azure ၏ GPT-5.2 အတွက် ကန့်သတ်ချက် နည်းပါးမှုများမှ အကျိုးတိုးရရှိမည်။ +GPT-5.2 ကို အသုံးပြုခြင်းမှာ သင်၏ စဉ်းစားရာကို ထိန်းချုပ်နိုင်သည့် reasoning control ကို စတင်တင်ဆက်ထားခြင်းကြောင့် ဖြစ်သည် - မေးခွန်းဖြေရှင်းမှုမတိုင်မီ မော်ဒယ်ကို ဘယ်လောက် စဉ်းစားစေမလဲ သတ်မှတ်နိုင်သည်။ ၎င်းကြောင့် prompt မျိုးစုံ၏ထူးခြားမှုများ ပိုမို ထင်ထွက်လာပြီး မည်သည့်ပုံစံကို ဘယ်အချိန်တွင် သုံးသင့်သည်ကို နားလည်ရန် အထောက်အကူ ဖြစ်စေသည်။ -## လိုအပ်သောအကြောင်းအရာများ +## လိုအပ်ချက်များ -- Module 01 ပြီးစီးထားခြင်း (Azure OpenAI အရင်းအမြစ်များ တပ်ဆင်ထားသည်) -- `.env` ဖိုင်ကို root directory တွင် Azure အတည်ပြုချက်များဖြင့် စီစဉ်ထားခြင်း (`azd up` ကဲ့သို့ Module 01 တွင် ဖန်တီးထားသည်) +- Module 01 ကို ပြီးစီးထားရန် (Azure OpenAI အရင်းအမြစ်များ တပ်ဆင်ထားသည်) +- Root directory တွင် `.env` ဖိုင်ရှိရမည် (Module 01 တွင် `azd up` ဖြင့် ဖန်တီးထားသည်) -> **မှတ်ချက်:** Module 01 ကို မပြီးစီးသေးပါက အရင်ဆုံး ၎င်းအပိုင်းတွင် ဖော်ပြထားသည့် တပ်ဆင်ခြင်း လမ်းညွှန်ချက်များကို လိုက်နာပါ။ +> **မှတ်ချက်:** Module 01 မပြီးသောသူများသည် ကျင်းပချက်များကို ကြိုတင် လိုက်နာပြီး စတင်ပါ။ ## Prompt Engineering ကို နားလည်ခြင်း -Prompt engineering သည် ရှင်းလင်းမှု မရှိသော အမှာစကားနှင့် တိကျသည့် အမှာစကားတို့အကြား ခြားနားချက် ဖြစ်ပြီး အောက်ပါ ဥပမာက ဖြင့် ရှင်းပြထားသည်။ +prompt engineering ၏ အဓိကမှာ မရိုးရိုးဖြစ်သော ညွှန်ကြားချက်နှင့် တိကျမှန်ကန်သော ညွှန်ကြားချက်နှင့် ကြားက ကွာခြားချက်ကို ဖော်ပြသည်။ What is Prompt Engineering? -Prompt engineering ဆိုသည်မှာ သင်လိုအပ်သော အဖြေများကို တိတိကျကျ ရရှိစေရန် ထည့်သွင်းသော စာသားကို ဒီဇိုင်းဆွဲခြင်းဖြစ်သည်။ မေးခွန်းမေးခြင်း မဟုတ်ဘဲ မော်ဒယ်က သင့်လိုချင်သည့်အရာကို တိတိကျကျ နားလည်ပြီး ဘယ်လို ဖြေဆိုရမည်ကို ဆောင်ရွက်ရန် ကြိုးပမ်းခြင်းဖြစ်သည်။ +prompt engineering သည် သင့် လိုအပ်ချက်နှင့် ညီညွတ်သော ရလဒ်များကို မျှော်လင့်၍ အရေးပါသော input စာသားကို ဒီဇိုင်းဆွဲခြင်းဖြစ်သည်။ မေးခွန်းများ မေးခြင်း အထက်အပေါ်သာမက မော်ဒယ်မှ သင်လိုရာကို ချိန်ညှိပေးနိုင်ရန် structure ဖန်တီးပေးခြင်း ဖြစ်သည်။ -၎င်းက ကိုယ်စားလှယ်း တစ်ဦးအား ညွှန်ကြားချက် ပေးသလိုဖြစ်သည်။ "ဘတ်တွေကို ပြင်ပါ" ဆိုသည်မှာ မရှင်းလင်းပေ။ "UserService.java ၏ ၄၅ လိုင်းမှ null pointer exception ကို null check ထည့်ပြီး ပြင်ပါ" ဆိုသည်မှာ တိတိကျကျ ဖြစ်သည်။ ဘာသာစကား မော်ဒယ်များကိုလည်း အတူတူပါပဲ - တိတိကျကျ ဖြစ်ရမည်။ +အလုပ်ဖော်အား ညွှန်ကြားချက်ပေးသည့်အတိုင်း ယူဆပါ။ “Bug ပြင်ပါ” ဆိုသည်မှာ မဖော်ပြချက်မပြည့်စုံပါ။ “UserService.java ရဲ့ line 45 မှာ null pointer exception ကို null check ဖြင့် ပြင်ပေးပါ” ဆိုသည်မှာ တိကျသည်။ ဘာသာစကား မော်ဒယ်များသည် ထိုကဲ့သို့ အတိအကျပုံစံနှင့် ဖွဲ့စည်းမှုကို အလေးထားသည်။ -အောက်ပါတို့ ပုံက LangChain4j ကို ပုံမှာ ဘယ်လို သွင်ပြင်မှုရှိသနည်း ဆိုတာကို ပြသသည် - SystemMessage နှင့် UserMessage စိတ်ကြိုက် block များဖြင့် prompt အား မော်ဒယ်သို့ ချိတ်ဆက်ပေးခြင်း။ +အောက်ပါ ပုံမှာ LangChain4j ကို ဒီကိစ္စတွင် ဘယ်လို လုပ်ဆောင်ခဲ့သည်ကို ရှင်းပြသည် — prompt ပုံစံများကို SystemMessage နှင့် UserMessage များဖြင့် မော်ဒယ်သို့ ချိတ်ဆက်ပေးသည်။ How LangChain4j Fits -LangChain4j သည် အခြေခံ အဆောက်အအုံ (model များချိတ်ဆက်ခြင်း၊ မှတ်ဉာဏ်၊ နှင့် စာတိုက်ပို့နည်းများ) ပံ့ပိုးပေးပြီး prompt ပုံစံများဟာ တိတိကျကျဖွဲ့စည်းထားသော စာသားများဖြစ်ပြီး လမ်းကြောင်းအတိုင်းပို့ခြင်းဖြစ်သည်။ အဓိက Block များမှာ AI ၏ ပြုမူနှင့် အခန်းကဏ္ဍ သတ်မှတ်သည့် `SystemMessage` နှင့် သင့်တောင်းဆိုချက်ကို သိမ်းဆည်းသည့် `UserMessage` တို့ ဖြစ်သည်။ +LangChain4j သည် တည်ဆောက်ပုံ၊ မေမရီနှင့် မက်ဆေ့ချ်အမျိုးအစားများကို ပံ့ပိုးပေးသည့် အဆောက်အအုံဖြစ်ပြီး၊ prompt ပုံစံများမှာ ၎င်းဖွဲ့စည်းမှုကို အသုံးပြု၍ သင့်ရဲ့ စိတ်ကူးအတိုင်း ဖော်ပြသော စာသားများဖြစ်သည်။ အဓိက အဆောက်အအုံဖြစ်သော `SystemMessage` သည် AI ၏ အပြုအမူ နှင့် အခန်းကဏ္ဍကို သတ်မှတ်ပြီး၊ `UserMessage` သည် သင့် တောင်းဆိုချက်ကို ပါဝင်သည်။ ## Prompt Engineering အခြေခံများ -အောက်တွင် ဖော်ပြထားသော prompt engineering ၏ အဓိကနည်းလမ်းငါးမျိုးသည် ထိရောက်သော prompt ဖွဲ့စည်းမှုပုံစံ၏ အခြေခံဖြစ်သည်။ မည်သည့်နည်းဖြင့် ဘာသာစကား မော်ဒယ်များနှင့် ဆက်သွယ်မလဲဆိုတာအား အကွာအဝေးကွဲပြားသော အချက်များကို ကွက်တိအနှိပ် ဖြေရှင်းပေးသည်။ +အောက်ပါ ငါး မူလနည်းလမ်းများမှာ ထိရောက်သော prompt engineering ၏ အခြေခံဖြစ်သည်။ တစ်ခုချင်းစီသည် ဘာသာစကား မော်ဒယ်များနှင့် ဆက်သွယ်ရာတွင် ကွဲပြားသော ဦးတည်ချက်များကို ဖြေရှင်းပေးသည်။ Five Prompt Engineering Patterns Overview -ဤ module ၌ အဆင့်မြင့် ပုံစံများသို့ ဝင်ကြမည်မတိုင်မီ အခြေခံ prompting နည်းလမ်းငါးခုကို ပြန်လည်သုံးသပ်ကြပါစို့။ ၎င်းများသည် prompt engineering ၏ အခြေခံ ပလက်ဖောင်းဖြစ်ပြီး prompt engineer တစ်ဦးစီ ကျွမ်းကျင်သင့်သည်။ သင်သည် ပြီးခဲ့သော [Quick Start module](../00-quick-start/README.md#2-prompt-patterns) ကို လေ့လာပြီးဖြစ်လျှင် ဤနည်းလမ်းများ၏ မှန်ကန်မှုကို သဘောပေါက်ထားသည်။ +ဒီ module ၏ အဆင့်မြင့် ပုံစံများသို့ ဝင်ရောက်မီ၊ အခြေခံ prompting နည်းလမ်း ၅ မျိုးကို ပြန်လည်သုံးသပ်ကြမည်။ ၎င်းတို့သည် prompt engineer တစ်ဦးအတွက် မဖြစ်မနေ သိထားသင့်သည့် အခြေခံကားများ ဖြစ်သည်။ ### Zero-Shot Prompting -အလွန်လွယ်ကူသောနည်းလမ်း - တစ်ခုခုနေရာပေးခြင်း မပါဘဲ တိုက်ရိုက် ညွှန်ကြားချက်ပေးခြင်း ဖြစ်သည်။ မော်ဒယ်သည် ရှေ့အစီအစဉ်ကျမှ သင်၏လုပ်ငန်းကို နားလည်ပြီး ဆောင်ရွက်တော့သည်။ ရိုးရှင်းသော တောင်းဆိုမှုများအတွက် အသုံးဝင်သည်။ +အလွယ်ဆုံး နည်းလမ်း - မော်ဒယ်ကို ဥပမာအားမပေးဘဲ တိုက်ရိုက်ညွှန့်ကြားချက်ပေးသည်။ မော်ဒယ်သည် သင်္ချာ၏ အသိပညာအားသာ အားဖြင့် လုပ်ငန်းကို နားလည် ဆောင်ရွက်သည်။ များသောအားဖြင့် ရိုးရှင်းသော တောင်းဆိုချက်များတွင် အဆင်ပြေသည်။ Zero-Shot Prompting -*နမူနာမပါဘဲ တိုက်ရိုက် ညွှန်ကြားချက်ပေးခြင်း - မော်ဒယ်သည် ညွှန်ကြားချက်မှသာ သတိပြုကာ တာဝန်တင်ယူသည်* +*ဥပမာမပါဘဲ တိုတိုတို instruction ပေးခြင်း — မော်ဒယ်သည် instruction ကနေ လိုအပ်ချက်ကို ဆင်ခြင်* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// တုံ့ပြန်ချက်: "အနာဂတ်ချက်" +// တုံ့ပြန်ချက်: "ပေါ်တီဗ်" ``` - -**အသုံးပြုသင့်သည့် အချိန်:** ရိုးရာသတ်မှတ်ချက်များ၊ တိုက်ရိုက်မေးခွန်းများ၊ ဘာသာပြန်ခြင်းများ၊ သို့မဟုတ် အပိုအကူအညီမလိုအပ်သော တာဝန်များ။ + +**သင့်လျော်သည့် အခါ:** ရိုးရှင်းသော အမျိုးအစား သတ်မှတ်ခြင်းများ၊ တိုက်ရိုက် မေးခွန်းများ၊ ဘာသာပြန်လုပ်ခြင်းများ၊ သို့မဟုတ် မော်ဒယ်က အခြား ညွှန်ကြားချက် မလိုအပ်ပဲ ကိုင်တွယ်နိုင်သော လုပ်ငန်းများ။ ### Few-Shot Prompting -မော်ဒယ်ကို လိုလားသော ပုံစံကို ပြသသော နမူနာများ ပေးသည်။ မော်ဒယ်သည် သင်ပေးထားသော နမူနာများမှ အသုံးပြုရမည့် input-output ပုံစံကို သိရှိ၍ နောက်ထပ် input များတွင်လည်း သက်ဆိုင်စေရန် အသုံးပြုသည်။ ဒီနည်းလမ်းသည် ပုံစံ ပိုမိုတိကျမှုရှိရာမှာ အထောက်အကူပြုသည်။ +မော်ဒယ်သည် လိုအပ်သော ပုံစံကို လေ့လာရန် ဥပမာများကို ပံ့ပိုးပေးခြင်းဖြစ်သည်။ မော်ဒယ်သည် သင်ပေးထားသော ဥပမာများမှ input-output ပုံစံကို ရယူပြီး အသစ်တိုးလာသော အရေးအသားများတွင် အသုံးပြုသည်။ မည်သို့ဖွဲ့စည်းရမည် နှင့် အပြုအမူ အဆက်မပြတ်ရှိရန် အထူးအကျိုးရှိသည်။ Few-Shot Prompting -*နမူနာများမှ လေ့လာခြင်း - မော်ဒယ်သည် ပုံစံသတ်မှတ်ချက်ကို ဖော်ထုတ်၍ အသစ်များတွင် ကျင့်သုံးသည်* +*ဥပမာများမှ စာရင်းသွင်းခြင်း — မော်ဒယ်သည် ပုံစံကို သိပြီး အသစ်အကြောင်းများမှာ အသုံးပြုသည်* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**အသုံးပြုသင့်သည့် အချိန်:** ကိုယ်ပိုင်သတ်မှတ်ချက်များ၊ တိုးတက်မြှင့်တင်သော ဖော်မတ်များ၊ ဆိုင်ရာနယ်ပယ်အတွင်းတာဝန်များ၊ Zero-Shot ၏ ရလဒ် မတည်ငြိမ်သော အခါ။ + +**သင့်လျော်သည့် အခါ:** ပုံစံထားသော အမျိုးအစားသတ်မှတ်ခြင်းများ၊ တည်ငြိမ်သော ဖော်မက်များ၊ အထူးသတ်မှတ် domain များ၊ သို့မဟုတ် zero-shot မှ အစဉ်အဆက် မတည်ငြိမ်သော ရလဒ်များ။ ### Chain of Thought -မော်ဒယ်အား တည်ရှိသော အစိတ်အပိုင်းများကို အဆင့်ဆင့်ဖော်ပြတိုက်ရိုက် နည်းလမ်းဖြင့် တင်ပြရန် တောင်းဆိုသည်။ တုံ့ပြန်ချက်ကို တုံ့ပြန်ခြင်းမပြုမီ မြန်မာနိုင်ငံ ရှင်းလင်းမှုနှင့် တိကျမှု ပြုလုပ်သည်။ ဂဏန်း၊ သရုပ်ပြ ရည်ရွယ်ချက်များတွင် ထူးခြားစွာ အသုံးဝင်သည်။ +မော်ဒယ်ကို ခြေလှမ်းခြေလှမ်း အတိအကျ စဉ်းစားမှုပြသရန် တောင်းဆိုခြင်းဖြစ်သည်။ တုံ့ပြန်ချက်ကို တိုက်ရိုက် မပေးဘဲ ပြဿနာကို ခွဲခြမ်းစိတ်ဖြာပြီး လုပ်ဆောင်ချက် တစ်ခုချင်းဆီ အတိအကျရှင်းပြသည်။ သင်္ချာ၊ သင်္ချာရေး မတိကျမှုများနှင့် အဆင့်မြင့်စဉ်းစားမှုများတွင် တိကျမှန်ကန်မှု မြင့်စေသည်။ Chain of Thought Prompting -*အဆင့်ဆင့် စဉ်းစားခြင်း - ရှင်းလင်းထားသည့် အချက်အလက်အစိတ်အပိုင်းများကို ခွဲခြား ပြသခြင်း* +*ခြေလှမ်းခြေလှမ်း စဉ်းစားမှု — ရှုပ်ထွေးသည့် ပြဿနာများကို တိကျသော အဆင့်ဖြင့် ခွဲခြမ်း* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// မော်ဒယ်မှာပြပါတယ် - ၁၅ - ၈ = ၇, ထို့နောက် ၇ + ၁၂ = ၁၉ စိပ်ပန်းသီးများ။ +// မော်ဒယ်ကပြပါတယ် - ၁၅ မှ ၈ လျော့လိုက်ရင် ၇ ဖြစ်ပြီး၊ အဲဒီ ၇ ကို ၁၂ နဲ့ ပေါင်းလိုက်ရင် ၁၉ ပန်းသီးရပါတယ်။ ``` - -**အသုံးပြုသင့်သည့် အချိန်:** သင်္ချာပြဿနာများ၊ တရားဟောင်း ပဟေဠိများ၊ အမှားရှာဖွေခြင်း၊ သို့မဟုတ် စဉ်းစားမှုကို ထည့်သွင်းရန် လိုသော တာဝန်များတွင်။ + +**သင့်လျော်သည့် အခါ:** သင်္ချာမေးခွန်းများ၊ မှန်ကန်မှုစစ်ဆေးခြင်း၊ ပြဿနာရှာဖွေခြင်း၊ သို့မဟုတ် စဉ်းစားမှုအစဉ်အလာပြသခြင်းဖြင့် တိကျမှန်ကန်မှု တိုးတက်စေလိုသော လုပ်ငန်းများ။ ### Role-Based Prompting -မေးခွန်းမေးခြင်းမပြုမီ AI အတွက် သရုပ်သမား သတ်မှတ်မှု ပေးသည်။ ၎င်းသည် အကြောင်းအနက်ပြုလုပ်ခြင်း၊ အကြောင်းအရာအခြေခံ အဖြေအား ဖွဲ့စည်းပေးသည်။ "software architect" နှင့် "junior developer" သို့မဟုတ် "security auditor" တို့ ဆွေးနွေးချက် တစ်ခုရဲ့ အတုအယောင် ကွာခြားမှု ရှိသည်။ +မေးခွန်းမေးရန် မတိုင်မီ AI အတွက် ကိုယ်စားလှယ် သို့မဟုတ် အခန်းကဏ္ဍ တစ်ခုသတ်မှတ်ပေးခြင်းဖြစ်သည်။ ၎င်းသည် တုံ့ပြန်မှု၏ အသံ၊ နက်ရှိုင်းမှုနှင့် အာရုံစူးစိုက်မှုကို ပုံသေသည်။ "ဆော့ဖ်ဝဲ အင်ဂျင်နီယာ" နှင့် "Junior Developer" သို့မဟုတ် "လုံခြုံရေး စစ်ဆေးသူ" တို့၏ အကြံပြုချက် မတူကြပုံကို ဖြစ်စေသည်။ Role-Based Prompting -*အကွက်အတိအကျ သတ်မှတ်ခြင်း - တူညီသောမေးခွန်းက သတ်မှတ်ထားသော အခန်းကဏ္ဍပြီးနောက် မတူညီသော တုံ့ပြန်မှုရရှိသည်* +*Context နှင့် ကိုယ်စားလှယ် အခန်းကဏ္ဍ သတ်မှတ်ခြင်း — တူညီသော မေးခွန်းတစ်ခုအတွက် တုံ့ပြန်မှုကွဲပြားမှုရှိသည်* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**အသုံးပြုသင့်သည့် အချိန်:** ကုဒ် သုံးသပ်ခြင်း၊ သင်ကြားမှု၊ နယ်ပယ်ပေါ် မူတည်သည့် စာရင်းစစ်ခြင်း၊ အသေးစိတ် ဦးစားပေးမှု လိုအပ်သော အခါ။ + +**သင့်လျော်သည့် အခါ:** ကုဒ်သုံးသပ်ခြင်းများ၊ သင်ကြားရေး၊ domain-specific ခေတ်သစ်အတွေ့အကြုံများ၊ သို့မဟုတ် သတ်မှတ်ထားသော ကျွမ်းကျင်မှု အဆင့် သို့မဟုတ် ရှုထောင့်ဖြင့် ပြန်ကြားမှုလိုအပ်သော အခါ။ ### Prompt Templates -ပြန်လည် အသုံးပြုနိုင်သော prompt များကို မတူညီသောတန်ဖိုးများ ဖြည့်၍ ဖန်တီးသည်။ တစ်ခါတည်း ဖန်တီးပြီး မတူညီသော တန်ဖိုးများဖြင့် အသုံးပြုလိုသည်။ LangChain4j ၏ `PromptTemplate` အတန်းသည် `{{variable}}` စနစ်ဖြင့် ထိန်းချုပ်ရန် လွယ်ကူစေသည်။ +ပြောင်းလဲနိုင်သော placeholder များပါရှိသော ပုံစံ prompt များ ပြုလုပ်ခြင်းဖြစ်သည်။ မကြာခဏ prompt အသစ်ရေးရန်မလိုဘဲ template တစ်ခုအတိုင်း သတ်မှတ်ပြီး မတူညီသောတန်ဖိုးများဖြည့်စွက်အသုံးပြုသည်။ LangChain4j ၏ `PromptTemplate` class သည် `{{variable}}` syntax ဖြင့် လွယ်ကူစေသည်။ Prompt Templates -*ပြန်လည် အသုံးပြုနိုင်သော prompt များ - တစ်ခုတည်းသော template၊ အသုံးများစွာ* +*အကြိမ်ကြိမ် အသုံးပြုနိုင်သော prompt များ — တစ်ခုတည်းသော template နှင့် အသုံးစွဲ အမျိုးမျိုး* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**အသုံးပြုသင့်သည့် အချိန်:** မတူညီသော input များဖြင့် မေးခွန်းများ ထပ်ဖန်တီး၊ စုစည်းဖြတ်တောက်ခြင်းလုပ်ငန်းများ၊ ပြန်လည်အသုံးပြုနိုင်သော AI လုပ်ငန်းစဉ်တည်ဆောက်ရာ၌ တည်ငြိမ်သော ဖွဲ့စည်းပုံပြောင်းလဲခြင်းမရှိသောအခါ။ + +**သင့်လျော်သည့် အခါ:** input မတူသည့် တောင်းဆိုချက်များ၊ စုစုပေါင်းလုပ်ငန်းများ၊ ပြန်လည်အသုံးပြုနိုင်သော AI workflow များ ဖန်တီးရာ၊ prompt အဖွဲ့အစည်းတူနေပါက ဒေတာပြောင်းလဲရာတွင်။ --- -ဤနည်းလမ်းငါးခုသည် prompt များအတွက် ထိရောက်စွာ အသုံးပြုနိုင်သော ကိရိယာပရိသတ် တစ်ခုကို ပေးသည်။ ကျန်ပိုင်းကို GPT-5.2 ၏ reasoning control၊ ကိုယ်တိုင် သုံးသပ်မှုနှင့် ဖွဲ့စည်းထားသော output ကြောင့် အသုံးချနိုင်သော **အဆင့်မြင့် ပုံစံ အရှစ်ခု** နဲ့ ဆက်လက်တည်ဆောက်မည်။ +ဤငါးခုအခြေခံကိရိယာများသည် များသော prompting လုပ်ငန်းများအတွက် သေချာသော ကိရိယာများ ဖြစ်သည်။ ကွင်းဆက် အမှုထမ်း ၈ ခုအဆင့်မြင့်ပုံစံများအား GPT-5.2 ၏ reasoning control၊ ကိုယ်တိုင် သုံးသပ်ခြင်းနှင့် ဖွဲ့စည်းထားသော ထွက်ရှိမှုများနှင့် တွဲဖက်အသုံးပြုမည်။ ## အဆင့်မြင့် ပုံစံများ -အခြေခံများ ပြီးဆုံးသွားသောအခါ ဒီ module ကို ထူးခြားတဲ့အရာကြောင့် အဆင့်မြင့် ပုံစံအရှစ်ခုဆီ သွားကြမယ်။ ပြဿနာတိုင်းမှာ နည်းလမ်းတူညီမှု မရှိပါ။ ဒီမေးခွန်းတချို့သည် အမြန်ဖြေကြားမှု လိုအပ်သည်၊ အခြားတချို့က အကြောင်းအရာ တွေးတောမှုမပြတ်ဖို့လိုသည်။ လက်တွေ့ သက်ရှိ reasoning လိုအပ်သောနည်းလမ်းများ၊ တခြား ကိစ္စတွင် တုံ့ပြန်ချက်ချက်ရ ဖြစ်သော်လည်း အဖြေများ လိုအပ်သည်။ အောက်ပါ အတိုင်းပုံစံနှင့် GPT-5.2 ၏ reasoning control ဖြစ်စဉ်ကြောင့် ကွဲပြားချက်များ ပိုသိသာသွားသည်။ +အခြေခံနည်းလမ်းများကို ဆောင်ရွက်ပြီးနောက်ဒီ module သ၏ ထူးခြားချက် ဖြစ်သော အဆင့်မြင့် pattern ၈ မျိုးသို့ ဝင်ရောက်မည်။ ပြဿနာများအားလုံးသည် တစ်ခုတည်းသော နည်းလမ်း မလိုအပ်ပါ။ မေးခွန်းတချို့နှင့် လွယ်ကူမြန်ဆန်သော ဖြေရှင်းချက်လိုအပ်သည်၊ အချို့အတွက် နက်ရှိုင်း၍ အတွေးအခေါ်များလိုအပ်သည်။ reasoning control ကို GPT-5.2 ဖြင့် သင်နှင့်ကိုက်ညီမှု ရရှိစေရန် အောက်ပါ pattern တစ်ခုချင်းစီသည် သင့်တော်မှုကို ထိန်းသိမ်းထားသည်။ Eight Prompting Patterns -*ပုံစံ အရှစ်ခု၏ အနှစ်ချုပ်နှင့် အသုံးပြုမှု* +*prompt engineering pattern အသုံးပြုမှုနှင့် အသုံးချမှု ကဏ္ဍများ အနှစ်ချုပ် ရှင်းလင်းချက်* -GPT-5.2 သည် ပုံစံများတွင် အခြား အတိုင်းအတာတစ်ခုဖြစ်သည်။ *reasoning control* ဖြစ်ပြီး စက်ရုပ်၏ စဉ်းစားမှုအား အောက်ပါ slider မှ ဖြင့် ချိန်ညှိနိုင်သည် - မြန်ဆန် တိုက်ရိုက်ဖြေချင်ခြင်းမှ စ၍ နက်နက်ရှိုင်းရှိုင်း စဉ်းစားမှုအထိ။ +GPT-5.2 သည် အောက်တွင် ဖော်ပြထားသည့် *reasoning control* ကို ပေးသည်။ မော်ဒယ်၏ စဉ်းစားမှုအား ကိုသင် တိုက်ရိုက် ပြင်ဆင်နိုင်ပြီး၊ မြန်ဆန်ပြီး တိုတိုဖြေကြားခြင်းမှ နက်ရှိုင်း၍ ကြိုးစားစူးစမ်းခြင်းအထိ ရွေးချယ်နိုင်သည်။ Reasoning Control with GPT-5.2 -*GPT-5.2 ၏ reasoning control သုံး၍ စက်ရုပ် စဉ်းစားမှု အရည်အချင်းကို မြန်မြန် ဆုံဆန်နှင့် နက်နက်ရှိုင်းရှိုင်းအထိ ချိန်ညှိခြင်း* +*GPT-5.2 ၏ reasoning control သည် မော်ဒယ်ကို ဘယ်လောက် စဉ်းစားစေမည်ကို သတ်မှတ်နိုင်ခြင်း - မြန်ဆန်သော ဖြေကြားချက်မှ နက်ရှိုင်း ဗဟုသုတ ရှာဖွေရာအထိ* -**နိမ့်သော စိတ်အားထက်သန်မှု (မြန်နှုန်းမြန်ပြီး အာရုံစူးစိုက်မှုနည်း)** - ရိုးရှင်းသောမေးခွန်းများအတွက် မြန်ဆန်၍ တိုက်ရိုက်ဖြေချင်သောအခါ အသုံးပြုရန်။ စက်ရုပ်သည် reasoning ကို အနည်းဆုံး လုပ်ဆောင် - အဆင့် ၂ ထိသာ ဖြစ်သည်။ ကိန်းဂဏန်းတွက်ချက်ခြင်း၊ စစ်ဆေးခြင်း သို့မဟုတ် ရိုးရှင်းသော ပြဿနာများအတွက် သုံးပါ။ +**နိမ့်သော စိတ်အားထက်သန်မှု (မြန်ဆန်ပြီး အာရုံစူးစိုက်)** - ရိုးရှင်းပြီး မြန်ဆန်သည့် တုံ့ပြန်ချက်လိုအပ်သော မေးခွန်းများအတွက် ဖြစ်သည်။ မော်ဒယ်သည် reasoning အနည်းဆုံး ပြုလုပ်ပြီး အရှိန်အဟုန် ၂ ချက် ထက်မပိုရန် သတ်မှတ်ထားသည်။ ဂဏန်းတွက်ချက်၊ ရှာဖွေမှု သို့မဟုတ် ရိုးရွင်းသော မေးခွန်းများတွင် အသုံးပြုရန် သင့်တော်သည်။ ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> 💡 **GitHub Copilot ဖြင့် ရှာဖွေကြည့်ပါ:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ဖိုင်ကို ဖွင့်ပြီး မေးခွန်းများ မေးပါ။ -> - "နိမ့်စိတ်အားထက်သန်မှုနဲ့ မြင့်စိတ်အားထက်သန်မှု prompting ပုံစံများကြား ရှားနည်းခြားနားချက် ဘာလဲ?" -> - "Prompt များမှ XML များက AI ၏ တုံ့ပြန်မှု ဖွဲ့စည်းပုံကို ဘယ်လို ကူညီသလဲ?" -> - "ကိုယ်တိုင် သုံးသပ်မှု pattern များ နဲ့ တိုက်ရိုက် ညွှန်ကြားခြင်း pattern များ ဘယ်အချိန်သုံးသင့်သလဲ?" -**မြင့်သော စိတ်အားထက်သန်မှု (နက်နက်ရှိုင်းရှိုင်း & သေချာသပ်ရပ်စွာ)** - ပြဿနာရှုပ်ထွေးသော အခါ ဝေဖန်စိတ်ရှုမောင်းပြီး ဂရုတစိုက် စိစစ်လိုသောအခါ အသုံးပြုပါ။ စက်ရုပ်သည် အပြည့်အစုံ ဖြေရှင်းမှုနှင့် အသေးစိတ် reasoning ပြသသည်။ စနစ်ဒီဇိုင်း၊ အဆောက်အအုံ ဆုံးဖြတ်ချက်များ၊ ရှုပ်ထွေးသော သုတေသနများအတွက် သင့်တော်သည်။ +> 💡 **GitHub Copilot နဲ့ စူးစမ်းကြည့်ပါ:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ဖိုင်ကိုဖွင့်၍ မေးပါ - +> - "နိမ့်စိတ်အားထက်သန်မှုနှင့် မြင့်စိတ်အားထက်သန်မှု prompting pattern များတွင် မတူကွဲပြားချက်များသည် ဘာတွေလဲ?" +> - "prompt များထဲရှိ XML tags များက AI ၏ ဖြေကြားချက် ဖွဲ့စည်းပုံကို မည်သို့ကူညီသနည်း?" +> - "ကိုယ်တိုင် သုံးသပ်မှု pattern များနှင့် တိုက်ရိုက် instruction များကို ဘယ်အချိန်တွင် အသုံးပြုသင့်သနည်း?" + +**မြင့်သော စိတ်အားထက်သန်မှု (နက်ရှိုင်း၍ ကြိုးစားစွာ)** - အတိအကျ ခွဲခြမ်းစိတ်ဖြာလိုသော ပြဿနာများအတွက်ဖြစ်သည်။ မော်ဒယ်သည် နက်ရှိုင်းစွာ စူးစမ်းပြီး အသေးစိတ် reasoning များ ပြသသည်။ စနစ်ဒီဇိုင်း၊ ဖွဲ့စည်းမှု ဆုံးဖြတ်ချက်များသို့မဟုတ် ရှုပ်ထွေးသော သုတေသနများတွင် သင့်တော်သည်။ ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**တာဝန် အဆင့်ဆင့် လုပ်ဆောင်ခြင်း (ခြေလှမ်းအလိုက် တိုးတက်မှု)** - အဆင့်များစွာပါတဲ့ workflow များအတွက်။ စက်ရုပ်သည် အစီအစဉ်တစ်ခုကို ရှေ့တ’avance ပြသပြီး လုပ်ဆောင်ချက် တစ်ခုချင်းစီကို ဖော်ပြခြင်း၊ နောက်ဆုံးတွင် သရုပ်ပြချက် ပေးသည်။ ကျယ်ပြန့်သော ပြောင်းရွှေ့ရေး၊ တည်ဆောက်ခြင်း စနစ်များအတွက် အသုံးပြုသည်။ + +**Task Execution (ခြေလှမ်းခြေလှမ်း တိုးတက်မှု)** - အဆင့်ပိုင်းလုပ်ငန်းစဉ်များအတွက်ဖြစ်သည်။ မော်ဒယ်သည် ကြိုတင်အစီအစဉ် တင်ပြပြီး လုပ်ဆောင်ချိန် တစ်ခြေလှမ်းစီ ရှင်းပြသည်၊ နောက်တစ်တွဲ အကျဉ်းချုပ် ပါဝင်သည်။ ကူးပြောင်းမှု၊ အကောင်အထည်ဖော်မှုများ နှင့် အဆင့်ပိုင်းလုပ်ငန်းများတွင် သုံးရန်။ ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -Chain-of-Thought prompting သည် မော်ဒယ်ကို reasoning လုပ်ဆောင်ရန် တောင်းဆိုခြင်းဖြစ်ပြီး ရှုပ်ထွေးသော တာဝန်များ၌ တိကျမှန်ကန်မှု ကို တိုးတက်စေသည်။ အဆင့်အလိုက် ပိုင်းခြားထားခြင်းသည် လူနှင့် AI နှစ်ဖက်လုံးအတွက် ရိုးရှင်းစေသည်။ -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ဖြင့် စမ်းသပ်ကြည့်ပါ။** ဤပုံစံအကြောင်း မေးရန် -> - "ရှည်လျားစွာ ကြာမြင့်သော လုပ်ငန်းဆောင်တာများတွင် task execution pattern ကို မည်သို့ သုံးမည်နည်း?" -> - "ထုတ်လုပ်မှု အပလီကေးရှင်းများတွင် ကိရိယာ preamble များ စနစ်တကျ အဖွဲ့ဖွဲ့ခြင်းအတွက် အကောင်းဆုံး လုပ်နည်းများဘာတွေလဲ?" -> - "UI တွင် အလယ်အလတ် တိုးတက်မှုများကို တွဲဖက် ဖော်ပြရန် မည်သို့ ဖမ်းဆီးထိန်းသိမ်းသနည်း?" +Chain-of-Thought prompting သည် မော်ဒယ်အား စဉ်းစားမှုကို ပြသရန် တိုက်ရိုက်တောင်းဆိုခြင်းဖြစ်ပြီး ရှုပ်ထွေးသော လုပ်ငန်းများတွင် တိကျမှန်ကန်မှုကို မြှင့်တင်ပေးသည်။ ခြေလှမ်းခြေလှမ်း ခွဲခြမ်းပြခြင်းသည် လူနှင့် AI နှစ်ဦးစလုံးအတွက် အတွေးအခေါ်ကို နားလည်နိုင်စေသည်။ -အောက်ပါ ဓာတ်ပုံသည် Plan → Execute → Summarize workflow ကို ရှင်းပြထားသည်။ +> **🤖 GitHub Copilot chat ဖြင့် စမ်းသပ်ရန်:** ဒီ pattern အကြောင်း မေးပါ - +> - "Task execution pattern ကို ကြာရှည်စေရန် လုပ်ငန်းများအတွက် မည်သို့ လိုက်လျောညီထွေ ပြုလုပ်မလဲ?" +> - "ထုတ်လုပ်မှု အပ်ပလီကေးရှင်းများတွင် tool preamble များ ဖွဲ့စည်းမှုအတွက် အေကာင္းဆုံး လေ့ကျင့်မှုများက ဘာတွေလဲ?" +> - "UI အတွက် အလယ်အလတ် တိုးတက်မှု အစီရင်ခံချက်များ ကို မည်သို့ ဖော်ပြ မရယူမလဲ?" + +အောက်ပါ ပုံသည် Plan → Execute → Summarize အစီအစဉ်ကို ဖော်ပြသည်။ Task Execution Pattern -*အဆင့်များစွာ တာဝန်များအတွက် Plan → Execute → Summarize workflow* +*ခြေလှမ်းပိုင်းဆိုင်ရာ လုပ်ငန်းများအတွက် Plan → Execute → Summarize စဉ်ဆက်* -**ကိုယ်တိုင် သုံးသပ်သော ကုဒ်** - ထုတ်လုပ်မှု အရည်အသွေးမြင့် ကုဒ် ဖန်တီးရာတွင် အသုံးပြုသည်။ စက်ရုပ်သည် သင့်တော်သော အမှားအသိပေးများနှင့်အတူ ထုတ်လုပ်မှု စံနှုန်းများနှင့် ကိုက်ညီသည့် ကုဒ် ထုတ်လုပ်သည်။ အသစ်သော features သို့ ဝန်ဆောင်မှုများ တည်ဆောက်ရာ၌ သုံးပါ။ +**ကိုယ်တိုင် သုံးသပ်သည့် ကုဒ်** - ထုတ်လုပ်မှုအဆင့် အရည်အသွေးမြင့် ကုဒ်ဖန်တီးရန် မော်ဒယ်သည် ထုတ်လုပ်မှုစံထားများနှင့် ကိုက်ညီသော error handling ပါဝင်သည်။ ဖန်တီးတိုးတက်မှုများ သို့မဟုတ် ဝန်ဆောင်မှုအသစ်များတွင် အသုံးပြုရန်။ ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -အောက်ပါ ဒီဇိုင်းက ဒီ iterative တိုးတက်မှု လည်ပတ်မှု - ဖန်တီးသည်၊ သုံးသပ်သည်၊ အားနည်းချက်များ ရှာဖွေသည်၊ ထပ်တိုးသည် (code ကို ထုတ်လုပ်မှု စံနှုန်းသို့ ညှိညွတ်သည်) ကို ပြသသည်။ + +အောက်ပါ ပုံသည် ဒီ ရှုပ်ကွေးမှု ပြန်လည်တိုးတက်မှု စက်ဝိုင်းကို ပြသသည် — ဖန်တီး၊ သုံးသပ်၊ အားနည်းချက်တွေရှာဖွေ၊ ပြုပြင်၍ ကုဒ်သည် ထုတ်လုပ်မှု စံချိန်နှုန်းကို ထိန်းသိမ်းသည်။ Self-Reflection Cycle -*တိုးတက်မှု လည်ပတ်မှု - ဖန်တီး၊ သုံးသပ်၊ ပြဿနာ ရှာဖွေ၊ တိုးတက်* +*မျှတစွာ တိုးတက်မှု ဘက်စုံ - ဖန်တီး၊ သုံးသပ်၊ ပြဿနာတွေ ရှာဖွေ၊ တိုးတက်စေမှု၊ ထပ်တလဲလဲ* -**ဖွဲ့စည်းထားသည့် ချဉ်းကပ်ချက်** - အတိအကျ သုံးသပ်မှုအတွက်။ စက်ရုပ်သည် ကုဒ်အတွက် တိတိကျကျ ဖော်ကြားချက်များ (မှန်ကန်မှု၊ လေ့ကျင့်မှုများ၊ တုံ့ပြန်မှု၊ လုံခြုံမှု၊ ထိန်းသိမ်းမှု) နဲ့ အတူ ပြန်လည်သုံးသပ်သည်။ ကုဒ် သုံးသပ်မှု သို့မဟုတ် အရည်အသွေး သုံးသပ်ရာတွင် သုံးပါ။ +**ဖွဲ့စည်းထားသော သုံးသပ်ချက်** - တိကျစွာ အကဲဖြတ်ရန် ဖြစ်သည်။ မော်ဒယ်သည် fixed framework (မှန်ကန်မှု၊ လေ့လာမှုစနစ်များ၊ လုပ်ဆောင်မှု၊ လုံခြုံရေး၊ ပြုပြင်န်းထိန်းသိမ်းမှု) အတိုင်း ကုဒ်ကို သုံးသပ်သည်။ ကုဒ်သုံးသပ်မှု သို့မဟုတ် အရည်အသွေး သတ်မှတ်မှုများတွင် သုံးရန်။ ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ဖြင့် စမ်းသပ်ကြည့်ပါ။** ဖွဲ့စည်းထားသော ချဉ်းကပ်ချက်အကြောင်း မေးရန် -> - "ကုဒ် သုံးသပ်ခြင်း အမျိုးအစားများအတွက် သုံးသပ်မှု ဖွဲ့စည်းပုံကို မည်သို့ ကိုယ်တိုင် သတ်မှတ်နိုင်သနည်း?" -> - "ဖွဲ့စည်းထားသော အထွက် output ကို ပရိုဂရမ်မာတစ်ယောက် အနေဖြင့် အကောင်အထည်ဖော်မှု မြင့်မားစေရန် နည်းလမ်းများ?" -> - "ကွဲပြားသော သုံးသပ်မှု အစည်းအဝေးများတွင် တူညီသော အလေးအနက် အဆင့်ကို မည်သို့ သေချာ ထိန်းသိမ်းနိုင်သနည်း?" -အောက်ပါ ပုံသည် ဖွဲ့စည်းထားသည့် framework ဖြင့် တိကျစွာ ဖြစ်စေရန် ဒါနဲ့ severity အဆင့်များဖြင့် ကုဒ် သုံးသပ်ခြင်းကို စီမံပုံ ကို ဖော်ပြသည်။ +> **🤖 GitHub Copilot chat ဖြင့် စမ်းသပ်ရန်:** ဖွဲ့စည်းထားသော သုံးသပ်ချက်အကြောင်း မေးပါ - +> - "အမျိုးအစားကွဲပြားသော ကုဒ်သုံးသပ်မှုများအတွက် သုံးသပ်မှု framework ကို မည်သို့ စိတ်တိုင်းကျ ပြောင်းလဲနိုင်မလဲ?" +> - "ဖွဲ့စည်းထားသော ထွက်ရှိမှုကို ပရိုဂရမ်အဆင့် မည်သို့ pars လုပ်ပြီး လုပ်ဆောင်မလဲ?" +> - "ကွဲပြားနေသော သုံးသပ်မှု အစည်းအဝေးများတွင် တင်းကြပ်ချိန်များကို မည်သို့ တည်ငွိမ်ထားမလဲ?" + +အောက်ပါ ပုံသည် ဒီ framework သည် severity အဆင့်များနှင့်အတူ တင်းကြပ်သော ကုဒ်သုံးသပ်မှုကို ဘယ်လို စီမံမှုလုပ်ငန်းခွဲ သနည်းကို ပြသသည်။ Structured Analysis Pattern -*အတိအကျ သုံးသပ်မှုများအတွက် framework နှင့် severity အဆင့်များ* +*severity အဆင့်များဖြင့် တင်းကြပ်သော ကုဒ်သုံးသပ်မှု framework* -**အကြိမ်ရေ များသော စကားပြော** - Context များလိုအပ်သော စကားပြော တွေအတွက်။ စက်ရုပ်သည် ယခင်စာတိုက်ပို့မှုများကို မှတ်မိပြီး တိုးချဲ့ပြောဆိုသည်။ ဖော်ပြချက် ကူညီမှု၊ ရှုပ်ထွေးသော Q&A အတွက် သုံးပါ။ +**အကြိမ်ကြိမ် စကားပြောခြင်း** - Context လိုအပ်သော စကားပြောမှုများအတွက် ဖြစ်သည်။ မော်ဒယ်သည် ယခင် မက်ဆေ့ချ်များကို နှစ်သက်၍ မှတ်ယူပြီး ဆက်လက်တိုးတက်လာစေသည်။ အကူအညီ အစည်းအဝေးများ သို့မဟုတ် ရှုပ်ထွေးသော Q&A များတွင် အသုံးပြုရန်။ ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -အောက်ပါ ပုံက စကားပြော context သည် အကြိမ်များစွာ မိတ်ဆက်မှုဖြင့် တိုးတက်လာပြီး model ၏ token ကန့်သတ်မှုနှင့် မည်သို့ ဆက်နွယ်မှု ရှိသနည်းကို ပြသသည်။ + +အောက်ပါ ပုံသည် စကားပြော context များ မည်သို့ အဆက်မပြတ် စုဆောင်းပြီး မော်ဒယ်၏ token ကန့်သတ်မှုနှင့် သက်ဆိုင်မှုရှိသော အတိုင်း ပြသသည်။ Context Memory -*စကားပြော context သည် ကျယ်ပြန့်စွာ ကြာရှည်မှုသို့ တိုးတက်လာသည့် ဂရုစိုက်မှု* -**အဆင့်စီ အတွေးအခေါ်** - မြင်သာတဲ့ လူ့သဘောထား လိုအပ်တဲ့ ပြဿနာများအတွက်။ မော်ဒယ်သည် အဆင့်တိုင်းအတွက် သေချာ လေ့လာရှုမှုပြုသည်။ ဤသည်ကို သင်္ချာပြဿနာများ၊ အတွေးအခေါ် ပဟေဋိများ သို့မဟုတ် စဉ်းစားမှု လုပ်ပုံကို နားလည်ရန် အသုံးပြုပါ။ +*စကားပြော context သည် ချိန်တိုးချိန်လျှင် token ကန့်သတ်မှုထိ မည်သို့ စုဆောင်းမလဲ* + +**ခြေလှမ်းခြေလှမ်း မှတ်ချက်ပြုခြင်း** - မြင်သာသော အတွေးအခေါ်လိုသော ပြဿနာများအတွက်ဖြစ်သည်။ မော်ဒယ်သည် တစ်ခြေလှမ်းချင်းစီအတွက် တိကျသော reasoning ပြသသည်။ သင်္ချာမေးခွန်းများ၊ မှန်ကန်မှု၊ သို့မဟုတ် စဉ်းစားခြင်းစဉ်ကို နားလည်ရန်လိုသော အခါအသုံးပြုရန်။ ```java String prompt = """ @@ -397,14 +398,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -အောက်ပါ ပုံက မော်ဒယ်သည် ပြဿနာများကို သေချာ၍ နံပါတ်စဉ်တိကျသော အဖြေရှာချက် အဆင့်များအဖြစ် မျှဝေသည့် မျက်နှာပြင်ကို ဖော်ပြသည်။ -Step-by-Step Pattern +အောက်ပါပုံသည် မော်ဒယ်သည် ပြဿနာများကို တိကျသောနံပါတ်စဉ် logical ခြေလှမ်းများအားဖြင့် ခွဲခြမ်းသည်ကို ပြသထားသည်။ -*ပြဿနာများကို သေချာသော အတွေးအခေါ်ခြေလှမ်းများသို့ ခွဲထုတ်ခြင်း* +Step-by-Step Pattern +*ပြဿနာများကို သတိပေးရှင်းလင်းသော သဒ္ဒါဆိုင်ရာ ဘက်စုံအဆင့်များသို့ ခွဲခြမ်းစိတ်ဖြာခြင်း* -**ကန့်သတ်ထားသော အထွက်** - အကြောင်းအရာသတ်မှတ်ချက်နှင့် အရွယ်အစားလိုအပ်ချက်ရှိသော တုံ့ပြန်ချက်များအတွက်။ မော်ဒယ်သည် ပုံစံနှင့် အရွယ်အစား စည်းကမ်းများကို တိကျစွာလိုက်နာသည်။ အကျဉ်းချုပ်များ သို့မဟုတ် တိကျသော အထွက်ဖွဲ့စည်းပုံလိုအပ်သော စဉ်ဆက် ရေးရာတွင် အသုံးပြုပါ။ +**အကန့်အသတ်ထားသည့် အထွက်အဖြေ** - အထူးအမျိုးအစားမူပိုင်ခွင့်ရှိသည့် ဖော်မတ်လိုအပ်ချက်များနှင့်အတူ တုံ့ပြန်ချက်များအတွက်။ မော်ဒယ်သည် ဖော်မတ်နှင့် အရှည်အညွှန်းစည်းကမ်းများကို တင်းကြပ်စွာလိုက်နာသည်။ အကျဉ်းချုပ်များသို့မဟုတ် တိကျသည့် ထုတ်လွှင့်ဖွဲ့စည်းပုံလိုအပ်သောအခါ၌ ယင်းကိုအသုံးပြုပါ။ ```java String prompt = """ @@ -419,190 +419,190 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -အောက်ပါ ပုံက ကန့်သတ်ချက်များက မော်ဒယ်အား သင့်ဖွဲ့စည်းပုံနှင့် အရွယ်အစား အတက်လျော်အောင် ထုတ်လုပ်ရန် ဦးတည်ပေးသည့် ပုံစံကို ပြသည်။ -Constrained Output Pattern +အောက်ပါ ပုံစံကတော့ မော်ဒယ်ကို သင်၏ ဖော်မတ်နှင့် အရှည်လိုအပ်ချက်များကို တင်းကြပ်စွာလိုက်နာပြီး ထုတ်လွှင့်ရန် ဘယ်လို အကန့်အသတ်များသည် လမ်းညွန်သလဲ ဆိုတာကိုပြထားသည်။ -*ပုံစံ၊ အရွယ်အစား၊ ဖွဲ့စည်းမှုလိုအပ်ချက်များကို ကန့်သတ်အားပေးခြင်း* +အကန့်အသတ်ထားသည့် အထွက်အဖြေ ပုံစံ -## အပလီကေးရှင်း စတင်မယ် +*အထူးဖော်မတ်၊ အရှည်နှင့် ဖွဲ့စည်းမှုလိုအပ်ချက်များကို တင်းကြပ်စွာ ဖော်ဆောင်ခြင်း* -**ဖြန့်ဖြူးမှုကို အတည်ပြုပါ။** +## အပလီကေးရှင်းကို လည်ပတ်ပါ -`.env` ဖိုင်သည် အမျိုးအစားတစ်ခုအနေဖြင့် မူလညွှန်ကြားထားသည့် ဒါရိုက်ထရီအတွင်း၊ Azure အတည်ပြုချက်များနှင့် တည်ရှိမှုရှိကြောင်း သေချာပါစေ (Module 01 တြင် ဖန်တီးထားသည်)။ ဤတွင် မော်ဒယ် ဒါရိုက်ထရီ (`02-prompt-engineering/`) မှ စတင်ဆောင်ရွက်ပါ။ +**ဖြန့်ချိမှုကို စစ်ဆေးပါ။** -**Bash:** +Module 01 တွင် ဖန်တီးထားသည့် Azure အတည်ပြုချက်များပါသည့် `.env` ဖိုင်ကို ရှေ့ဆုံးဌာနတွင် ရှိနေကြောင်း သေချာစေပါ။ ဒီဇိုင်နာ မော်ဒူလာဒိုင်းရိုက်ထရီမှ (`02-prompt-engineering/`) အောက်ဖော်ပြပါအတိုင်း လည်ပတ်ပါ။ + +**Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကို ပြရန်ဖြစ်သည်။ +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကို ပြသသင့်သည် ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကို ပြသသင့်သည်။ +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကိုပြရန်လိုသည်။ ``` - + **အပလီကေးရှင်းကို စတင်ပါ။** -> **မှတ်ချက်။** မူရင်း ဒါရိုက်ထရီမှ `./start-all.sh` အသုံးပြုကာ အပလီကေးရှင်းအားလုံးကို ရှေ့မှ စတင်ထားပြီးဖြစ်ပါက (Module 01 တွင် ဖော်ပြထားသလို) ဤမော်ဒယ်သည် 8083 ဆိပ်ကမ်းတွင် လည်ပတ်နေပါပြီ။ အောက်တွင် ဖော်ပြထားသည့် စတင်ရန် မှတ်တမ်းကို ကျော်သွားကာ တိုက်ရိုက် http://localhost:8083 သို့ သွားပါ။ +> **မှတ်ချက်။** ပြည့်စုံအားဖြင့် root directory ကနေ `./start-all.sh` ဖြင့် application အားလုံးကို စတင်ထားပြီးသားဖြစ်ပါက (Module 01 တွင်ဖော်ပြထားသည့်အတိုင်း), ဤမော်ဒူးသည် 8083 port တွင် လည်ပတ်နေပါပြီ။ အောက်ဖော်ပြပါ စတင်ရေးနှိပ်ကလစ်များကို ဖယ်ရှားပြီး http://localhost:8083 သို့ တိုက်ရိုက်သွားနိုင်သည်။ -**ရွေးချယ်စရာ ၁: Spring Boot Dashboard အသုံးပြုခြင်း (VS Code အသုံးပြုသူများအတွက် အကြံပြုသည်)** +**ရွေးချယ်စရာ ၁: Spring Boot Dashboard အသုံးပြုခြင်း (VS Code အသုံးပြုသူများအတွက် အကြံပြု)** -Dev container တွင် Spring Boot Dashboard extension ပါရှိပြီး ယင်းက Spring Boot အပလီကေးရှင်းများအားလုံးကို မျက်နှာကြောင်းဖြင့် စီမံခန့်ခွဲရန် အဆင့်မြှင့် အင်တာဖေ့စ် ပေးသည်။ VS Code ဘယ်ဘက်က Activity Bar တွင် (Spring Boot အိုင်ကွန်ကို ကြည့်ပါ) တွေ့နိုင်သည်။ +Dev container တွင် Spring Boot Dashboard extension ပါဝင်သည်။ ၎င်းသည် Spring Boot အပလီကေးရှင်းများအား စီမံခန့်ခွဲရန် မြင်သာသော အင်တာဖေ့စ်ကို ပေးသည်။ VS Code ဘာသာရပ်၏ ဘယ်ဘက်ဘက် Activity Bar တွင် Spring Boot icon ကို ကြည့်ရှုနိုင်သည်။ -Spring Boot Dashboard မှ အောက်ပါအရာများကို ပြုလုပ်နိုင်ပါသည် - -- စာကြည့်တိုက်အတွင်းရှိ Spring Boot အပလီကေးရှင်းများအားလုံးကို ကြည့်ရှုနိုင်သည် -- အသုံးပြုသူတစ်ဦးတည်း နှိပ်ခြင်းဖြင့် အပလီကေးရှင်းများကို စတင်/ရပ်ဆိုင်းနိုင်သည် -- အပလီကေးရှင်းမှတ်တမ်းများကို တိုက်ရိုက် ကြည့်ရှုနိုင်သည် -- အပလီကေးရှင်း အခြေအနေများကို စောင့်ကြည့်နိုင်သည် +Spring Boot Dashboard မှ သင်အောက်ပါအရာများကို ဆောင်ရွက်နိုင်သည်- +-လုပ်ငန်းနယ်ပယ်ရှိ Spring Boot အပလီကေးရှင်း အားလုံးကို ကြည့်ရူရန် +-တစ်ချက်နှိပ်ပြီး application များကို စတင်/ရပ်ဆိုင်းရန် +-အပလီကေးရှင်း၏ log များကို တိုက်ရိုက်ကြည့်ရှုရန် +-application အခြေအနေကို စောင့်ကြည့်ရန် -"prompt-engineering" ထံတွင်ရှိသော play ခလုတ်ကို နှိပ်ကာ မော်ဒယ်ကို စတင်ပါ၊ ဒါမှမဟုတ် အားလုံးကို တစ်ပြိုင်တည်း စတင်နိုင်ပါသည်။ +"prompt-engineering" အနီးတွင် အားကစားခလုတ်ကို နှိပ်ခြင်းဖြင့် လက်ရှိမော်ဒူကို စတင်နိုင်သည်၊ ဟုတ်တော့ မော်ဒူးအားလုံးကိုတစ်ပြိုင်နက်စတင်ခြင်းလည်း ဆောင်ရွက်နိုင်သည်။ Spring Boot Dashboard -*VS Code တွင် Spring Boot Dashboard — မော်ဒယ်အားလုံးကို တစ်နေရာက စတင်၊ ရပ်ဆိုင်း၊ စောင့်ကြည့်နိုင်သည်* +*VS Code တွင် Spring Boot Dashboard — မော်ဒူးအားလုံးအား တစ်နေရာမှ စတင်၊ ရပ်တန့်၊ စောင့်ကြည့်ရန်* -**ရွေးချယ်စရာ ၂: Shell script များ အသုံးပြုခြင်း** +**ရွေးချယ်စရာ ၂: Shell စာသားများအသုံးပြုခြင်း** -ဝက်ဘ်အပလီကေးရှင်းများအားလုံး (Modules 01-04) ကို စတင်ပါ - +Web application များအားလုံး (မော်ဒူး 01-04) ကို စတင်ခြင်း။ -**Bash:** +**Bash:** ```bash -cd .. # အမြစ်ဖိုင်တိုက်မှနေ၍ +cd .. # အမြစ်ဖိုင်ဒိုရီမှ ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell -cd .. # အမြစ်ဖိုင်လ်ဒ်တွင်းမှ +cd .. # မူရင်းဖိုင်လ် ဒိုင်ရေးတရီမှ .\start-all.ps1 ``` - -သို့မဟုတ် ဤ မော်ဒယ်ကို သီးသန့် စတင်ပါ - -**Bash:** +သို့မဟုတ် ဒီမော်ဒူးကိုသာ စတင်ပါ။ + +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` - -ကလစ်တိုင်းမှာ Root `.env` ဖိုင်မှ ပတ်ဝန်းကျင် အပြောင်းအလဲများကို အလိုအလျောက် Load လုပ်ပြီး JAR မရှိလျှင် ကောက်နှိပ်ပေးပါမည်။ -> **မှတ်ချက်။** စတင်မပြုမီ မော်ဒယ်အားလုံးကို လက်စွဲ အသုံးပြုကောက်နှိပ်လိုပါက - +Shell စာသားနှစ်ခုစလုံးသည် root `.env` ဖိုင်မှ environment variable များကို အလိုအလျောက်သွင်းပြီး၊ JAR မရှိပါက တည်ဆောက်ပေးမည်။ + +> **မှတ်ချက်။** မော်ဒူးအားလုံးကို လက်ဖြင့်တည်ဆောက်ပြီးမှ စတင်လိုပါက - > -> **Bash:** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -> **PowerShell:** + +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -http://localhost:8083 ကို ဘရောက်ဇာတွင် ဖွင့်ပါ။ -**ရပ်ရန် -** +သင့် browser တွင် http://localhost:8083 ကိုဖွင့်ပါ။ + +**ရပ်တန့်ရန်:** -**Bash:** +**Bash:** ```bash -./stop.sh # ဤမော်ဂျုမ်းတစ်ခုသာ -# သို့မဟုတ် -cd .. && ./stop-all.sh # မော်ဂျုမ်းအားလုံး +./stop.sh # ဤမော်ဒျူးသာ +# ဒါမှမဟုတ် +cd .. && ./stop-all.sh # မော်ဒျူးအားလုံး ``` - -**PowerShell:** + +**PowerShell:** ```powershell -.\stop.ps1 # ဒီမော်ဂျူးသာ +.\stop.ps1 # ဒီမော်ဒูลကိုသာ # ဒါမှမဟုတ် -cd ..; .\stop-all.ps1 # မော်ဂျူးအားလုံး +cd ..; .\stop-all.ps1 # မော်ဒူးအားလုံး ``` - -## အပလီကေးရှင်း မျက်နှာကြည့်ကွက်များ -ဒီမှာ prompt engineering မော်ဒယ်၏ ပင်မ အင်တာဖေ့စ်ဖြစ်ပြီး Pattern ၈ မျိုးကို တစ်ပြိုင်နက်တည်း စမ်းသပ်နိုင်သည်။ +## အပလီကေးရှင်း Screenshot များ + +ဒါက prompt engineering မော်ဒူး၏ အဓိက user interface ဖြစ်ပြီး ပုံစံ ၈ မျိုးအား လက်တူတက်စွာ စမ်းသပ်နိုင်သည်။ Dashboard Home -*prompt engineering pattern အားလုံး၊ သူတို့၏ အင်္ဂါရပ်များနှင့် အသုံးချမှုကို ပြသသည့် ပင်မ Dashboard* +*prompt engineering ပုံစံ ၈ မျိုး အားလုံး၏ အင်္ဂါရပ်များနှင့် အသုံးပြုမှုဖြစ်ရပ်များကို ပြသသည့် အဓိက dashboard* -## Pattern များ ကို စူးစမ်းဖြေရှင်းခြင်း +## ပုံစံများကို စူးစမ်းလေ့လာခြင်း -ဝက်ဘ်အင်တာဖေ့စ်က တိုက်ရိုက် ဖေါ်ပြချက် များကို စမ်းသပ်ခွင့်ပြုသည်။ Pattern တစ်ခုခြင်းသည် မတူညီသော ပြဿနာများကို ဖြေရှင်းသည် အသုံးပြုကြည့်ပါ၊ ဘယ်အခါ pattern တစ်ခု ဖြစ်တည်မှုအား ရယူမည်ကို သေချာနားမလည်နိုင်ပါ။ +ဝက်ဘ်အင်တာဖေ့စ်သည် prompting မဟာဗျူဟာပေါင်းစုံကို စမ်းသပ်ရန် ခွင့်ပြုသည်။ အမှားအယွင်းများစွာကို အမျိုးအစားအလိုက် ဖြေရှင်းပေးသည့် ပုံစံတစ်ခုချင်းစီကို စမ်းပါ။ -> **မှတ်ချက်။ Streaming နှင့် Non-Streaming** — Pattern များ စာမျက်နှာ တစ်ခုရဲ့ နောက်ဆုံးမှာ နှစ်ချက်ခလုတ်များရှိသည်။ **🔴 Stream Response (Live)** နှင့် **Non-streaming** ရွေးချယ်စရာ။ Streaming သည် Server-Sent Events (SSE) အသုံးပြုကာ မော်ဒယ် ဖန်တီးနေစဉ် တိုက်ရိုက် token များကို ကြည့်ရှုနိုင်သည်။ Non-streaming သည် တုံ့ပြန်ချက် ပြည့်စုံမှ ကြည့်ရှုရန် စောင့်ဆိုင်းလျက်ရှိသည်။ အတွေးပညာ အတက်လျော်များအတွက် (ဥပမာ - High Eagerness, Self-Reflecting Code) Non-streaming ကို ခါတလေ အချိန်ကြာမြင့်နိုင်ပြီး မည်သည့် တုံ့ပြန်မှုမှ မကြည့်ရနိုင်ပါ။ **ရှုပ်ထွေးသော prompt များတွင် streaming ကို အသုံးပြုပါ**၊ မော်ဒယ် လုပ်ဆောင်နေပြီးကြောင်း ကို မြင်နိုင်ပြီး တောင်းဆိုချက် တားကွယ်ခံရသည်ဟု ထင်မှားမှုကို လျော့နည်းစေပါသည်။ -> -> **မှတ်ချက်။ ဘရောက်ဇာ လိုအပ်ချက်** — Streaming ဟာ Fetch Streams API (`response.body.getReader()`) ကိုအသုံးပြုသည်၊ ဤသည်သည် Chrome, Edge, Firefox, Safari ကဲ့သို့ ပြည့်စုံသော ဘရောက်ဇာလိုအပ်သည်။ VS Code built-in Simple Browser တွင် မလုပ်ဆောင်ပါခြင်း၊ ၎င်း၏ webview တွင် ReadableStream API အတွက် မပံ့ပိုးပါ။ Simple Browser အသုံးပြုလျှင် Non-streaming ခလုတ်များ ပုံမှန် လုပ်ဆောင်သော်လည်း Streaming ခလုတ်တွေ အလုပ်မလုပ်ပါ။ ပြည့်စုံသော အတွင်းခံအတွေ့အကြုံအတွက် `http://localhost:8083` ကို ပြင်ပ ဘရောက်ဇာတွေတွင် ဖွင့်ပါ။ +> **မှတ်ချက်: Streaming နှင့် Non-Streaming** — ပုံစံမူပိုင်ခွင့်တည်းနေရာတွင် နှစ်မျိုးသော ခလုတ်များရှိသည်။ **🔴 Stream Response (Live)** နှင့် **Non-streaming** ရွေးချယ်စရာပါရှိသည်။ Streaming သည် Server-Sent Events (SSE) ကိုအသုံးပြုကာ မော်ဒယ်က token များဖန်တီးသည့်အတိုင်း ချက်ချင်းပြသသည်။ Non-streaming သည် အဖြေတစ်ခုလုံးရရန် မစောင့်သည်။ အလွန်စိတ်ရှုပ်ထဲသွင်းသော prompt များ (ဥပမာ - High Eagerness, Self-Reflecting Code) အတွက် non-streaming ကို များစွာစောင့်ရသည်၊ မိနစ်များကြာနိုင်ပြီး ပြသခြင်းမရှိတော့ပါ။ **ရှုပ်ထွေးသော prompt များကို စမ်းသပ်ရာ၌ streaming ကို အသုံးပြုပါ**၊ မော်ဒယ်လည်ပတ်နေသည်ကို မြင်ရပြီး အချိန်ကုန်တာ တွေ့ခံရမှုမှ ကာကွယ်သည်။ +> +> **မှတ်ချက်: Browser လိုအပ်ချက်** — streaming လုပ်ဆောင်မှုသည် Fetch Streams API (`response.body.getReader()`) ကိုအသုံးပြုသည်၊ မူလ browser များ (Chrome, Edge, Firefox, Safari) နှင့်သာ လက်ခံသည်။ VS Code ၏ ဖွင့်ထားသော Simple Browser မီးပျက်ထဲတွင် မအလုပ်လုပ်ပါ၊ Simple Browser ၏ webview သည် ReadableStream API ကို မထောက်ပံ့ပါ။ Simple Browser အသုံးပြုပြီးလျှင် non-streaming ခလုတ်များ ရိုးရိုးအတိုင်း အလုပ်လုပ်လိမ့်မည် — streaming ခလုတ်များသာ ထိခိုက်မှုရှိသည်။ ပုံမှန်အသုံးပြုရန် `http://localhost:8083` ကို အပြင် browser တစ်ခုတွင် ဖွင့်ပါ။ -### အနိမ့် နှင့် အမြင့် စိတ်အားထက်သန်မှု (Eagerness) +### Low Eagerness နှင့် High Eagerness -"200 ၏ 15% ဘာလဲ?" ဆိုပြီး အနိမ့် စိတ်အားထက်သန်မှု ဖြင့် မေးပါ။ အလျင်အမြန် တိုတိုတောင်းသော တုံ့ပြန်ချက်ကို ရယူမည်။ အခုတော့ "အမြင့် လှုပ်ရှားမှု API အတွက် cache မဟာဗျူဟာ တစ်ခု အပြည့်အစုံ အကြံပြုပါ" ကို အမြင့် စိတ်အားထက်သန်မှုဖြင့် မေးပါ။ **🔴 Stream Response (Live)** ခလုတ်ကို နှိပ်ပြီး မော်ဒယ်၏ အသေးစိတ် ဆန်းစစ်ချက်များကို token တစ်ခုချင်း ပြသမှုဖြင့်ကြည့်ပါ။ မော်ဒယ်တစ်ခုတည်း၊ မေးခွန်းမျိုးနှုန်း တူညီသော်လည်း နောက်ခံ prompt က ဟောရန် စိတ်အတက်အကျကို သတ်မှတ်ပေးသည်။ +"200 ရဲ့ 15% ဘာလဲ?" ဟု Low Eagerness ဖြင့် မေးပါ။ ချက်ချင်း တိုက်ရိုက်ဖြေကြားပါလိမ့်မည်။ "High-Traffic API အတွက် caching မူဝါဒဖန်တီးပါ" ဟု High Eagerness ဖြင့် မေးပါ။ **🔴 Stream Response (Live)** ကို နှိပ်၍ မော်ဒယ်၏ အသေးစိတ် အတွေးအမြင်များကို token အလိုက် ကြည့်ရှုနိုင်ပါသည်။ မော်ဒယ်တူ၊ မေးခွန်းပုံစံတူ - သို့သော် prompt က သူမလုပ်ပုံကို မည်မျှ အတွေးကြိုးစားရန် ပြောပြသည်။ -### တာဝန် ဆောင်ရွက်ခြင်း (ကိရိယာ မူရင်းများ) +### ရည်မှန်းချက်ဖြင့် လုပ်ငန်းဆောင်ရွက်ခြင်း (Tool Preambles) -အဆင့်စဉ်များ ပါဝင်သည့် စီးဆင်းမှုများသည် မျှော်မှန်းချက် နှင့် တိုးတက်မှု ရေးရာ ပြောပြချက်များ ပါဝင်သင့်သည်။ မော်ဒယ်သည် ဘာလုပ်မည်ကို မရှင်းလင်း၍ ပြောကြားပြီး၊ အဆင့်တိုင်းကို ဖော်ပြ၊ နောက်ဆုံးတွင် ရလဒ် အကျဉ်းချုပ် ထုတ်ပြန်သည်။ +အဆင့်ဆင့် လုပ်ငန်းစဉ်များသည် အစပျိုးစီမံချက်နှင့် တိုးတက်မှုကို ဖော်ပြခြင်းကို အကျိုးရှိစွာတိုးတက်စေသည်။ မော်ဒယ်သည် လုပ်ဆောင်မည့်အရာကို တင်ပြပြီး အဆင့်တစ်ဆင့်စီ ဖော်ပြသည်။ ထို့နောက် ရလဒ်ကို အကျဉ်းချုပ်ပြန်လည် ဆန်းစစ်သည်။ -### ကိုယ်တိုင် သုံးသပ်ခြင်း(Coding) +### ကိုယ်တိုင် သုံးသပ်သော ကုဒ် -"အီးမေးလ် မှားချက်သတ်မှတ်သူ ဝန်ဆောင်မှု တည်ဆောက်ပါ" ဟုပြောရင်း စမ်းကြည့်ပါ။ ကုဒ် ဖန်တီးခြင်းဖြင့် ပြတ်တောက်ခြင်း မဟုတ်ပဲ မော်ဒယ်သည် ဖန်တီးပြီးနောက် အရည်အသွေး စံများနှင့် နှိုင်းယှဥ်၊ အားနည်းချက်များ ရှာဖွေပြီး တိုးတက်အောင် လုပ်ဆောင်သည်။ မော်ဒယ်သည် အင်မတန် iteration ဖြင့် ကုဒ်သည် ထုတ်လုပ်မှု စံနှင့် ချိန်ညှိသည်ထိ လုပ်ဆောင်သည်။ +"Email ဂဏန်းစစ်ဆေးရေး ဝန်ဆောင်မှု ဖန်တီးပါ" ဟု စမ်းသပ်ပါ။ ကုဒ်တစ်ခု တည်း မဟုတ်ပဲ ထုတ်လုပ်ပြီးရပ်နားမှုမရှိဘဲ မော်ဒယ်သည် သတ်မှတ်ချက်အရ မှန်ကန်မှု၊ အားနည်းချက်ရှာဖွေမှုနှင့် တိုးတက်မှုအား အဆင့်ဆင့် ပြုလုပ်ပြီး ဂုဏ်သတ်မှတ်ချက်ကျူးလွန်သည်အထိ ပြန်လည်ပြင်ဆင်ပေးသည်။ -### ဖွဲ့စည်းမှုပုံစံ သုံးသပ်ခြင်း +### ဖွဲ့စည်းမှုတကျ သုံးသပ်ခြင်း -ကုဒ် ပြန်လည်စစ်ဆေးခြင်းသည် တူညီသော သုံးသပ်မှုဖြစ်ရမည်။ မော်ဒယ်သည် ကုဒ်အား တိတိကျကျ အမျိုးအစားများဖြင့် ဆန်းစစ်သည် (တိကျမှု၊ လေ့လာမှု၊ စွမ်းဆောင်မှု၊ လုံခြုံမှု) နှင့် ပြင်းထန်မှု အဆင့်များဖြင့် သုံးသပ်သည်။ +ကုဒ်စစ်ဆေးမှုများအတွက် ထိထိရောက်ရောက် သုံးသပ်မှု မဟာဗျူဟာရှိရမည်။ မော်ဒယ်သည် တိတိကျကျ အမျိုးအစားများဖြင့် (မှန်ကန်မှု၊ လုပ်ထုံးလုပ်နည်းများ၊ ဆောင်ရွက်မှု၊ လုံခြုံမှု) နိုင်ငံတကာအဆင့်နှင့်အတူ သုံးသပ်ပေးသည်။ -### Multi-Turn စကားပြောခြင်း +### မလှုပ်မရှား စကားပြောဆိုမှု -"Spring Boot ဆိုတာ ဘာလဲ?" ဟုပြောပြီးနောက် "ဥပမာ တစ်ခု ပြပါ" ဟု ချက်ချင်း မေးပါ။ မော်ဒယ်သည် သင်မေးခွန်း ပထမအကြိမ်ကို သတိရပြီး Spring Boot ပုံစံကို တိတိကျကျ ပေးပါတယ်။ မှတ်ဉာဏ်မရှိလျှင် ဒုတိယ မေးခွန်းသည် မသေချာသည့် စကားလုံးဖြစ်မည်။ +"Spring Boot ဆိုတာဘာလဲ?" ဟု မေးပြီးနောက် "ဥပမာတစ်ခု ပြပါ" ဟု ညနေပိုင်း၌ ဆက်လက်မေးမြန်းသည်။ မော်ဒယ်သည် သင့်ပထမ မေးခွန်းကို မှတ်မိပြီး အထူး Spring Boot ဥပမာကို ပေးသည်။ စွဲမိမှုမရှိပါက ဒုတိယ မေးခွန်းသည် ပုံမှန် မရှင်းလင်းမရှိပါ။ -### အဆင့်စီ အတွေးအခေါ် +### အဆင့်လိုက် အတွေးအမြင် -သင်္ချာပြဿနာတစ်ခု ချမ်းသာစွာ ဖော်ပြခြင်းနှင့်အတူ အဆင့်စီအတွေးအခေါ်နှင့် အနိမ့်စိတ်အားထက်သန်မှု နှစ်မျိုးစမ်းပါ။ အနိမ့် စိတ်အားထက်သန်မှုသည် အဖြေကို ဆုံးဖြတ်ပြီး ပေးသည် - မြန်ဆန်ပေမယ့် ရှင်းလင်းမှုမရှိ။ အဆင့်စီသည် ဂဏန်းတွက်ချက်မှုနှင့် ဆုံးဖြတ်ချက်အားလုံးကို ပြသကာ တိကျစွာ သိရှိစေသည်။ +သင် သင်ကြိုက်သော သင်္ချာပြဿနာတစ်ခုကို Step-by-Step Reasoning နှင့် Low Eagerness တို့နှစ်မျိုးဖြင့် စမ်းသပ်ပါ။ Low eagerness သည် ဖြေချက်ကို မြန်ဆန်စွာပေးသည် - သို့သော် မတိကျပါ။ Step-by-step သည် အနည်းငယ်တွက်ချက်ခြင်းနှင့် ဆုံးဖြတ်ချက်များအားလုံးကို ပြသသည်။ -### ကန့်သတ်ထားသော အထွက် +### အကန့်အသတ်ထားသည့် အထွက်အဖြေ -သတ်မှတ်ထားသော ပုံစံများ သို့မဟုတ် စာလုံး အရေအတွက်လိုအပ်သောအခါ ဤ pattern သည် စည်းကမ်းများကို တင်းကျပ်စွာ လိုက်နာရန် ကြိုးပမ်းသည်။ အစီအစဉ်တစ်ခုမှာ ပြီးပြည့်စုံသော စာလုံး ၁၀၀ ကို bullet point ပုံစံဖြင့် ထုတ်ပေးရန် မျှော်လင့်ပါ။ +ဖော်မတ် သို့မဟုတ် စာလုံးအရေအတွက် အတိအကျလိုအပ်သောအခါ ဤပုံစံသည် တင်းကြပ်စွာလိုက်နာမှုကို အာမခံပေးသည်။ ဘူးလက်မှတ်ပုံစံဖြင့် တိတိကျကျ 100 စာလုံးပါအကျဉ်းချုပ်တစ်ခု ဖန်တီးဖို့ စမ်းသပ်ပါ။ -## သင် သင်ယူနေတာ က ဘာလဲ? +## သင်ဘာတွေ စစ်မှန်ပြီး လေ့လာနေပါသလဲ -**အတွေးပညာ ကြိုးပမ်းမှု တစ်ခုလုံးကို ပြောင်းလဲသည်** +**အတွေးအမြင် ကြိုးစားမှု ပြောင်းလဲမှု အားလုံးကို ထိန်းချုပ်တယ်** -GPT-5.2 သည် သင်၏ prompt များမှတဆင့် ကွန်ပြူတာ ကြိုးပမ်းမှုကို ထိန်းချုပ်နိုင်စေသည်။ အနိမ့် ကြိုးပမ်းမှုသည် အမြန်တုံ့ပြန်မှုဖြင့် အနည်းငယ် စူးစမ်းသုံးသပ်မှုသာ ပါဝင်သည်။ အမြင့် ကြိုးပမ်းမှုသည် မော်ဒယ်ကို နက်ရှိုင်းစွာ စဉ်းစားရန် အချိန်ယူစေသည်။ သင်သည် တာဝန်၏ ပြဿနာရှင်းလင်းမှုအပေါ် မျှတသည့် ကြိုးပမ်းမှုနှင့် ကိုက်ညီတတ်တော့မည် - ရိုးရိုး မေးခွန်းများကို အချိန်ဖြုန်းမထား၊ ရှုပ်ထွေးသော ဆုံးဖြတ်ချက်များကို ကာလမတိုအောင် မျာဖြတ်။ +GPT-5.2 သည် prompt များဖြင့် တွက်ချက်ခွန်အားကို ထိန်းချုပ်ခွင့်ပြုသည်။ ကြိုးစားမှုနည်းနည်းဟာ မြန်မြန် ပြန်လည်တုံ့ပြန်မှုဖြစ်ပြီး ကြိုးစားမှုအနည်းငယ်ဖြင့်ဖြစ်သည်။ ကြိုးစားမှုများစွာဟာ မော်ဒယ်ကို နက်နက်ရှိုင်းရှိုင်း စဉ်းစားခိုင်းတယ်။ သင့်ဆန့်အချက်နှင့် ဘာသာရပ်အခက်အခဲကို ရောထွေးပြီး သင် စိတ်ရှင်းစေတယ် - ရိုးရှင်းသောမေးခွန်းပေါ်မှာ မအလွန်ကြိုးစားပါနှင့်၊ ပြဿနာရှုပ်ထွေးတွေမှာလည်း အလျင်အမြန် သွားလုပ်ရန် မလိုပါ။ -**ဖွဲ့စည်းမှုသည် လုပ်ဆောင်မှုကို ဦးတည်သည်** +**ဖွဲ့စည်းခြင်းသည် အပြုအမူလမ်းညွန်ပေးသည်** -Prompt များရှိ XML tag များကို သတိပြုပါ။ ၎င်းတို့သည် အလှအပ မဟုတ်ပါ။ မော်ဒယ်များသည် ဖွဲ့စည်းမှုရှိသော အညွှန်းများကို လွယ်ကူစွာ လိုက်နာနိုင်ကြသည်။ အဆင့်စီလုပ်ငန်းစဉ်များ သို့မဟုတ် ရှုပ်ထွေးသော သဘောထားများ လိုအပ်လျှင် ဖွဲ့စည်းမှုက မော်ဒယ်ကို ၎င်း၏ မည်သည့်အဆင့်တွင် ရှိသည်နဲ့ မည်သည့်အဆင့်သို့ သွားမည်ကို သေချာ ပြီးမြောက်စေသည်။ အောက်ပါ ပုံက အဆင့်မြင့် ဖွဲ့စည်းထားသော prompt တစ်ခုကို မျက်နှာပြထားပြီး ``, ``, ``, ``, နှင့် `` ကဲ့သို့ XML ပုံစံ tag များဖြင့် သင်၏ အညွှန်းများကို ပိုမိုရှင်းလင်းသော အပိုင်းများသို့ ဖွဲ့စည်းပုံကို ပြသည်။ +prompt များတွင် XML tag များကို မှတ်ထားပါက စိတ်ဝင်စားစရာကောင်းသည်။ ၎င်းတို့သည် အလှဆင်ခြင်းမဟုတ်ပါဘူး။ မော်ဒယ်များသည် အဖွဲ့အစည်းတကျ ညွှန်ကြားချက်များကို လိုက်နာမှု မြင့်မားသည်။ အဆင့်လိုက်လုပ်ငန်းစဉ် သို့မဟုတ် နက်ရှိုင်းသော တရားတော်များ လိုသည့်အခါ ဖွဲ့စည်းခြင်းက မော်ဒယ်အနေဖြင့် ဒီဇိုင်နာဘယ်မှာရှိတယ်၊ နောက်တစ်ဆင့် ဘာလုပ်မလဲ ဆိုတာကို ကောင်းစွာဆီလျော်စေသည်။ အောက်ပါ ပုံကတော့ ဖြေဆိုရာ prompt ရဲ့ ဖွဲ့စည်းမှုက xml tag များဖြင့် ``, ``, ``, ``, နှင့် `` တို့အား ပိုင်းခြားထားကာ ညွှန်ကြားချက်ကို ရိုးရှင်း၍ မေးမြန်းထားသည်ကို ပြသသည်။ Prompt Structure -*ဖွဲ့စည်းမှုတိကျသည့် prompt ၏ ခေါင်းစဉ်များနှင့် XML ပုံစံအဖွဲ့အစည်း* +*အဆင့်များနှင့် XML ပုံစံ ဖွဲ့စည်းထားသော prompt တစ်ခု၏ အသွင်အပြင်* -**ကိုယ်တိုင် သုံးသပ်ခြင်းမှ အရည်အသွေး** +**ကိုယ်တိုင် သုံးသပ်ခြင်းမှတဆင့် အရည်အသွေး** -ကိုယ်တိုင် သုံးသပ်ခြင်းပုံစံများသည် အရည်အသွေး စံနှုန်းများကို တိတိကျကျ ဖော်ပြထားသည်။ မော်ဒယ်သည် "မှန်ကန်သည်" ဟု မျှော်လင့်ခြင်းမပြုဘဲ၊ "မှန်ကန်ခြင်း" ဆိုသည်မှာ မည်သည်ကို ရည်ညွှန်းသနည်း (တိကျသော စဉ်းစားမှု၊ အမှား ကျော်လွှားမှု၊ စွမ်းဆောင်မှု၊ လုံခြုံမှု) ကို တိကျစွာ ပြောပြသည်။ ထို့နောက် မော်ဒယ်သည် ၎င်း၏ ထုတ်လွှတ်ချက်ကို သုံးသပ်ပြီး တိုးတက်စေသွားသည်။ ၎င်းသည် ကုဒ် ဖန်တီးမှုကို လောင်းကစားကွင်းမှ လုပ်ငန်းစဉ် တစ်ခုသို့ ပြောင်းလဲစေသည်။ +ကိုယ်တိုင် သုံးသပ်မှု ပုံစံများသည် အရည်အသွေး သတ်မှတ်ချက်များကို ထင်ဟပ်စေသည်။ မော်ဒယ်ကို "မှန်ကန်ကြောင်း မျှော်လင့်" နေထိုင်ခြင်းမဟုတ်ပဲ "မှန်ကန်သည်" ဆိုသည်မှာ ဘာလဲ ဆိုတာကို တိတိကျကျ ပြောပြပေးသည်။ မှန်ကန်မှု၊ အမှားစစ်ဆေးမှု၊ စွမ်းဆောင်ရည်နှင့် လုံခြုံမှုများကို တိတိကျကျသတ်မှတ်ပြီး မော်ဒယ်မှာ သူ့ရဲ့ ထုတ်လွှင့်ချက်ကို ကိုယ်တိုင် သုံးသပ်နိုင်ပြီး တိုးတက်မှု ခံယူနိုင်တယ်။ ၎င်းက ကုဒ်ထုတ်လုပ်ခြင်းကို ကံလောင်းကစားမှုမှ လုပ်ငန်းစဉ်တစ်ခုဖြစ်စေသည်။ -**အခြေအနေ သတ်မှတ်ချက်သည် အကန့်အသတ် ရှိသည်** +**သြဇာကန့်သတ်မှု ရှိတယ်** -Multi-turn စကားဝိုင်းများသည် တောင်းဆိုချက်တစ်ခုစီနှင့် စကားမှတ်တမ်း သမိုင်းကို ပါဝင်ပေးမှုကြောင့် လုပ်ဆောင်သည်။ သို့သော် အကန့်အသတ် ရှိသည် - မော်ဒယ်တစ်ခုလုံးတွင် token အများဆုံး ရှိနိုင်မှု ဖြစ်သည်။ စကားနှင့် ပြည့်စုံမှု မြင့်မားလာသည့်အခါ လိုအပ်သော အကြောင်းအရာကို သိမ်းဆည်းထားခြင်းနှင့် အကန့်အသတ်မထိခိုက်စေရန် မူဝါဒများ လိုအပ်ပါသည်။ ဤမော်ဒယ်သည် သင်အား မှတ်ဉာဏ် အလုပ်လုပ်ပုံကို ပြသည်၊ နောက်ဆုံးတွင် ရှင်းလင်းချက် မည်သည့်အခါ၊ မေ့တမ်းမည်၊ ထုတ်ယူမည်ကို သင် သင်ယူမည်ဖြစ်သည်။ +မလှုပ်မရှား စကားပြောဆိုမှုသည် မက်ဆေ့ခ်ျသမိုင်းကို ထည့်သွင်းညွှန်းတမ်း ပြုလုပ်ခြင်းဖြင့် လည်ပတ်သည်။ သို့သော် ကန့်သတ်ချက် ရှိသည် - မော်ဒယ်အားလုံးမှာ token အများဆုံးပါဝင်နိုင်သည်။ စကားဝိုင်း မြင့်လာသည့်အခါ သင် ပတ်သက်မှုရှိသော သြဇာကို ကုသရန် မဟာဗျူဟာများ လိုအပ်သည်။ ဤမော်ဒူးသည် သင်ကို မှတ်ဉာဏ် (memory) မည်သို့ လည်ပတ်သည်ကို ပြသပြီး နောက်ပိုင်းတွင် စုစည်းမှု၊ မေ့ရန်နှင့် ထုတ်ယူရန်အချိန်များကို သင်ယူမည်။ ## နောက်တစ်ဆင့်များ -**နောက်တစ်ပြည့် Modules:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**နောက်ထပ် မော်ဒူး:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**လမ်းညွှန်မှု:** [← နောက်တစ်ခု: Module 01 - အနှောက်အယှက်ကင်း ရောက်ရှိမှု](../01-introduction/README.md) | [ပင်မသို့ ပြန်သွားရန်](../README.md) | [နောက်တစ်ခု: Module 03 - RAG →](../03-rag/README.md) +**နည်းလမ်းဆွဲချက်:** [← ယခင်တစ်ခု: မော်ဒူး 01 - မိတ်ဆက်](../01-introduction/README.md) | [အဓိကပင်မသို့ ပြန်သွားရန်](../README.md) | [နောက်တစ်ခု: မော်ဒူး 03 - RAG →](../03-rag/README.md) --- -**ထုတ်ပြန်ချက်** -ဤစာတမ်းကို AI ဘာသာပြန်မှု 서비스ဖြစ်သည့် [Co-op Translator](https://github.com/Azure/co-op-translator) ဖြင့် ဘာသာပြန်ထားပါသည်။ တိကျမှုအတွက် ကြိုးစားနေပြီးဖြစ်သော်လည်း၊ အလိုအလျောက် ဘာသာပြန်မှုများတွင် အမှားများ သို့မဟုတ် မှန်ကန်မှုနည်းပါးမှုများ ရှိနိုင်သည်ကို သတိပြုပါရန် တိုက်တွန်းပါသည်။ မူလစာတမ်းကို မူရင်းဘာသာစကားဖြင့်သာ တရားဝင်အမြင်ခံယူသင့်ပါသည်။ အရေးကြီးသော အချက်အလက်များအတွက်မှ ဖြစ်ပါက ပညာရှင်လက်ထောက် ဘာသာပြန်သူ၏ ဘာသာပြန်ချက်ကိုသာ အကြံပြုပါသည်။ ဤဘာသာပြန်မှုကို အသုံးပြု၍ ဖြစ်ပေါ်လာနိုင်သည့် နားမြင်မှု ခြွင်းချက်များ သို့မဟုတ် မှားယွင်းချက်များအတွက် ကျွန်ုပ်တို့ ဘာသာမပြုပါ။ +**ပြောကြားချက်** +ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှန်ကန်မှုအတွက် ကြိုးပမ်းနေသော်လည်း၊ စက်ကိရိယာဘာသာပြန်ခြင်းများတွင် အမှားများ သို့မဟုတ် မှားယွင်းချက်များ ပါဝင်နိုင်ကြောင်း သတိပြုပါရန် လိုအပ်ပါသည်။ မူလစာတမ်းကို မူရင်းဘာသာဖြင့်သာ ယုံကြည်စိတ်ချရသော အချက်အလက်အဖြစ် သတ်မှတ်သင့်သည်။ အရေးကြီးသည့် သတင်းအချက်အလက်များအတွက် ပရော်ဖက်ရှင်နယ် လူသားဘာသာပြန်သူဝန်ဆောင်မှုကို အကြံပြုပါသည်။ ဤဘာသာပြန်ချက်ကို အသုံးပြုခြင်းမှ ဖြစ်ပေါ်လာသော နားလည်မှုကွာခြားမှုများ သို့မဟုတ် မမှန်ကန်သော အသုံးပြုမှုများအတွက် ကျွန်ုပ်တို့ တာဝန်မခံပါ။ \ No newline at end of file diff --git a/translations/my/03-rag/README.md b/translations/my/03-rag/README.md index a3f081d71..b3707a009 100644 --- a/translations/my/03-rag/README.md +++ b/translations/my/03-rag/README.md @@ -1,144 +1,143 @@ -# Module 03: RAG (ရယူမှုဖြင့် တိုးမြှင့်သော မူရင်း ဖြန့်ဖြူးခြင်း) - -## ဇယားအကြောင်းအရာ - -- [ဗီဒီယို လမ်းညွှန်](../../../03-rag) -- [သင်ယူရမည့်အရာများ](../../../03-rag) -- [လိုအပ်ချက်များ](../../../03-rag) -- [RAG ကို နားလည်ခြင်း](../../../03-rag) - - [ဒီ သင်ခန်းစာသည် ဘယ် RAG နည်းလမ်းကို အသုံးပြုပါသလဲ?](../../../03-rag) -- [ဘယ်လို အလုပ်လုပ်သလဲ](../../../03-rag) - - [စာရွက်စာတမ်း ပစ္စည်းစီမံခြင်း](../../../03-rag) - - [အင်ဘက်ဒင်း ရေးဆွဲခြင်း](../../../03-rag) - - [အဓိပ္ပါယ်ရှာဖွေခြင်း](../../../03-rag) - - [ဖြေကြားချက် ထုတ်ပေးခြင်း](../../../03-rag) -- [လျှောက်လွှာကို စမ်းသပ်ခြင်း](../../../03-rag) -- [လျှောက်လွှာ အသုံးပြုခြင်း](../../../03-rag) - - [စာရွက်စာတမ်း တင်ခြင်း](../../../03-rag) - - [မေးခွန်း မေးခြင်း](../../../03-rag) - - [အရင်းအမြစ် ကိုးကားချက် စစ်ဆေးခြင်း](../../../03-rag) - - [မေးခွန်းများဖြင့် စမ်းသပ်ခြင်း](../../../03-rag) -- [အဓိက သဘောတရားများ](../../../03-rag) - - [ချန့်ကင်း နည်းလမ်း](../../../03-rag) - - [ဆက်ဆံမှု အဆင့်သတ်မှတ်ချက်များ](../../../03-rag) - - [မှတ်ဉာဏ် စတိုးဆိုင်](../../../03-rag) - - [အကြောင်းအရာ ပြတင်းပေါက် စီမံခန့်ခွဲမှု](../../../03-rag) -- [RAG အရေးကြီးသော အချိန်](../../../03-rag) -- [နောက်တစ်ဆင့်များ](../../../03-rag) +# Module 03: RAG (အချက်အလက် ရှာဖွေထောက်ပံ့မှုနှင့် ထုတ်ပေးမှု) + +## အညွှန်းစာရင်း + +- [ဗီဒီယို လမ်းညွှန်](#ဗီဒီယို-လမ်းညွှန်) +- [သင်တတ်မယ့်အရာများ](#သင်တတ်မယ့်အရာများ) +- [လိုအပ်ချက်များ](#လိုအပ်ချက်များ) +- [RAG ကို နားလည်ခြင်း](#rag-ကို-နားလည်ခြင်း) + - [ဒီ သင်ခန်းစာမှာ ဘယ် RAG နည်းလမ်းကို အသုံးပြုသလဲ?](#ဒီ-သင်ခန်းစာမှာ-ဘယ်-rag-နည်းလမ်းကို-အသုံးပြုသလဲ) +- [မည်သို့ လုပ်ဆောင်သနည်း](#မည်သို့-လုပ်ဆောင်သနည်း) + - [စာရွက်စာတမ်း ပြုလုပ်ခြင်း](#စာရွက်စာတမ်း-ပြုလုပ်ခြင်း) + - [Embedding များ ဖန်တီးခြင်း](#embedding-များ-ဖန်တီးခြင်း) + - [Semantic ရှာဖွေမှု](#semantic-ရှာဖွေမှု) + - [အဖြေ ဖန်တီးခြင်း](#ဖြေဆိုမှု-ထုတ်လုပ်ခြင်း) +- [အပလီကေးရှင်း လည်ပတ်စေတယ်](#application-ကို-chạy-လုပ်ခြင်း) +- [အပလီကေးရှင်းကို အသုံးပြုခြင်း](#application-အသုံးပြုမှု) + - [စာရွက်စာတမ်း တင်ခြင်း](#စာရွက်စာတမ်း-တင်ခြင်း) + - [မေးခွန်း မေးခြင်း](#မေးခွန်း-မေးခြင်း) + - [အရင်းအမြစ် ရည်ညွှန်းချက်များ စစ်ဆေးခြင်း](#အရင်းအမြစ်ကို-စစ်ဆေးခြင်း) + - [မေးခွန်းများဖြင့် စမ်းသပ်ခြင်း](#မေးခွန်း-အမျိုးမျိုးဖြင့်-စမ်းသပ်ရန်) +- [အဓိက သိကောင်းစရာများ](#အဓိက-အတွေးအခေါ်များ) + - [Chunking မဟာဗျူဟာ](#chunking-strategy) + - [ဆင်တူမှု အဆင့်များ](#similarity-scores) + - [အမှတ်ဉာဏ် သိုလှောင်မှု](#in-memory-storage) + - [Context Window စီမံခန့်ခွဲမှု](#context-window-management) +- [RAG လိုအပ်တဲ့အချိန်](#rag-ကို-ဘယ်ကို-အသုံးပြုသင့်သလဲ) +- [နောက်တစ်ဆင့်များ](#နောက်တစ်ဆင့်များ) ## ဗီဒီယို လမ်းညွှန် -ဒီ မော်ဂျူးနှင့် ပတ်သက်ပြီး စတင်လုပ်ဆောင်နည်းကိုရှင်းပြသည့် တိုက်ရိုက်အစီအစဉ်ကို ကြည့်ရှုပါ။ +ဒီ module နှင့် စတင်မည့်နည်းလမ်းကို ရှင်းပြသည့် အသက်သွင်းတိုက်ရိုက်ပွဲကို ကြည့်ရှုပါ။ RAG with LangChain4j - Live Session -## သင်ယူရမည့်အရာများ +## သင်တတ်မယ့်အရာများ -ယခင် မော်ဂျူးများတွင်၊ AI နှင့် ဆွေးနွေးပွဲများပြုလုပ်နည်းနှင့် မေးမြန်းချက်များကို ထိရောက်စွာ ဖွဲ့စည်းပုံကို လေ့လာသင်ယူခဲ့ပါသည်။ သို့သော် အခြေခံ ကန့်သတ်ချက်တစ်ခုရှိသည်။ ဘာသာစကားမော်ဒယ်များသည် သင်ကြားမှုအတွင်း သင်ယူထားသည့် အချက်အလက်များကိုသာ သိရှိ နိုင်ပါသည်။ သင်၏ကုမ္ပဏီ မူဝါဒများ၊ စီမံကိန်း စာရွက်စာတမ်းများ သို့မဟုတ် မသင်ကြားသည့် အချက်အလက်များအကြောင်း မဖြေကြားနိုင်ပါ။ +ယခင်ပုံစံ modules များတွင် AI နှင့် စကားဝိုင်းပြုလုပ်နိုင်ခြင်းနှင့် prompt များကို အကျိုးသက်ရောက်စွာ ဖွဲ့စည်းပုံကို သင်ယူခဲ့ပါသည်။ သို့သော် ရှိသော အခြေခံကန့်သတ်ချက်တစ်ခုမှာဘာဆိုသော်၊ ဘာသာစကား မော်ဒယ်များသည် မိမိများ သင်ကြားခဲ့သော ဒေတာတွင်သာ သိရှိပြီးဖြစ်သဖြင့်၊ လူမှုကုမ္ပဏီလိုင်စင် မူဝါဒများ၊ စီမံကိန်း စာရွက်စာတမ်းများ သို့မဟုတ် မသင်ကြားခဲ့သည့် အချက်အလက်များအပေါ်မေးခွန်းများကို ဖြေဆိုနိုင်ခြင်းမရှိပါ။ -RAG (ရယူမှုဖြင့် တိုးမြှင့်သော မူရင်း ဖြန့်ဖြူးခြင်း) သည် ဒီပြသနာကို ဖြေရှင်းပေးသည်။ မော်ဒယ်အား သင်၏ အချက်အလက်များကို သင်ကြားရန် ကြိုးစားခြင်း (ဒါဟာ ကြီးမားသောကုန်ကျစရိတ် ပါပြီး မအဆင်ပြေသော နည်း) ထက် မဟုတ်ဘဲ၊ စာရွက်စာတမ်းများမှ ရှာဖွေစစ်ဆေးနိုင်စွမ်းကို ပေးသည်။ မေးခွန်းတစ်ခု မေးလာသောအခါ စနစ်သည် သက်ဆိုင်ရာ အချက်အလက်များကို ရှာဖွေပြီး မေးမြန်းချက်အတွင်း ထည့်သွင်းပေးသည်။ ထို့နောက် မော်ဒယ်သည် ရရှိပြီးသော အကြောင်းအရာကို အခြေခံ၍ ဖြေကြားသည်။ +RAG (Retrieval-Augmented Generation) သည် ဒီ ပြဿနာကို ဖြေရှင်းပေးသည်။ မော်ဒယ်ကို သင်ယူစေမည်မဟုတ်ဘဲ (ဈေးကြီးပြီး လက်တွေ့မဖြစ်နိုင်), မော်ဒယ်တွင် စာရွက်စာတမ်းများကို ရှာဖွေစစ်ဆေးနိုင်စေရန် စွမ်းရည် ပေးသည်။ မေးခွန်းတစ်ခု မေးလျှင် စနစ်သည် သက်ဆိုင်ရာ အချက်အလက်ကို ရှာဖွေပြီး prompt တွင် ထည့်သွင်းပေးသည်။ ထိုနောက် မော်ဒယ်သည် ထိုရရှိလာသော context အပေါ်မူတည်ကာ အဖြေထုတ်ပေးသည်။ -RAG ကို မော်ဒယ်အား ကိုးကားစာကြည့်တိုက် တစ်ခု ပေးခြင်းအဖြစ် တွေးပါ။ မေးလျှင် စနစ်သည် - +RAG ကို မော်ဒယ်တစ်ခုအတွက် အညွန်းစာကြောင်းစာကြည့်တိုက်ပေးခြင်းဟု ယူဆပါ။ မေးခွန်းမေးသောအားဖြင့် စနစ်သည်- -1. **အသုံးပြုသူ မေးခွန်း** - သင်မေးပါသည် -2. **အင်ဘက်ဒင်း** - မေးခွန်းကို ဗက်တာသို့ပြောင်းသည် -3. **ဗက်တာ ရှာဖွေမှု** - သက်ဆိုင်ရာ စာရွက်အပိုင်းများကို ရှာရှာသည် -4. **အကြောင်းအရာ စုစည်းခြင်း** - သက်ဆိုင်ရာ များကို မေးမြန်းချက်ထဲ ထည့်သွင်းသည် -5. **တုံ့ပြန်ချက်** - LLM သည် အခြေအနေ ပေါ်မူတည်၍ ဖြေကြားသည် +1. **အသုံးပြုသူ မေးခွန်း** - မေးခွန်း မေးသည် +2. **Embedding** - မေးခွန်းကို vector အဖြစ် ပြောင်းလဲသည် +3. **Vector ရှာဖွေမှု** - ဆင်တူသော စာရွက်စာတမ်း parçသာအပိုင်းများ ရှာသည် +4. **Context စုစည်းခြင်း** - သက်ဆိုင်ရာ paragraph များကို prompt ထဲထည့်သည် +5. **အဖြေ** - LLM သည် context ကို အခြေခံကာ အဖြေထုတ်ပေးသည် -ဤကဲ့သို့ မော်ဒယ်၏ တုံ့ပြန်ချက်များကို ၎င်း၏ သင်ကြားမှုပညာရပ် များမှ မျှော်လင့်ခြင်း မဲထက် သင်၏ အချက်အလက်များအေပၚ အခြေခံပေးသည်။ +ဤကဲ့သို့ မော်ဒယ်အဖြေများကို သင်၏ အချက်အလက်နှင့် အတည်ပြုခြင်းဖြင့် အတူတကွ ဆောင်ရွက်သည်။ ## လိုအပ်ချက်များ -- [Module 00 - Quick Start](../00-quick-start/README.md) ပြီးမြောက်ရန် (နောက်ပိုင်း မော်ဂျူးတွင် ကိုးကားသော Easy RAG ဥပမာအတွက်) -- [Module 01 - Introduction](../01-introduction/README.md) ပြီးမြောက်ရန် (Azure OpenAI အရင်းအမြစ်များ တပ်ဆင်ပြီး၊ `text-embedding-3-small` embedding မော်ဒယ် ပါဝင်သည်) -- အခြေခံ ဖိုင်ဒေါင်းတွင် `.env` ဖိုင်တည်ရှိရန် (Module 01 တွင် `azd up` ဖြင့် ဖန်တီးထားသော Azure ယူဇာမှတ်ပုံတင်) +- [Module 01 - နိဒါန်း](../01-introduction/README.md) (Azure OpenAI အရင်းအမြစ်များ တပ်ဆင်ပြီး၊ `text-embedding-3-small` embedding မော်ဒယ်ပါဝင်သည်) ပြီးစီးထားခြင်း +- မူလ ဒါအို(ဒိုင်ရက်ထရီ)တွင် `.env` ဖိုင်ရှိပြီး Azure အတည်ပြုချက်များပါရှိခြင်း (`azd up` ကိရိယာဖြင့် Module 01 မှ တည်ဆောက်) -> **မှတ်ချက်:** Module 01 မပြီးမြောက်ရသေးပါက အရင်ဆုံး ထို module ၏ တပ်ဆင်ရေး လမ်းညွှန်ချက်များကို လိုက်နာပါ။ `azd up` အမိန့်သည် GPT chat မော်ဒယ်နှင့် embedding မော်ဒယ်နှစ်ခုစလုံးကို ဒီမိန့်တယ်။ +> **မှတ်ချက်:** Module 01 မပြီးစီးသေးလျှင် ပထမဆုံးမှာ ထို၃ယ်ပါလုပ်ဆောင်မှုများကို လိုက်နာပါ။ `azd up` ကိရိယာသည် GPT စကားဝိုင်းမော်ဒယ်နှင့် embedding မော်ဒယ် နှစ်ခုလုံးကို တပ်ဆင်ပေးသည်။ ## RAG ကို နားလည်ခြင်း -အောက်ဖေါ်ပြပါ ဇယားသည် အဓိက အကြောင်းအရာကို ထင်ဟပ်ပြသည်။ မော်ဒယ်၏ သင်ကြားမှုပညာပင် မူတည်ခြင်း မဟုတ်ဘဲ၊ RAG သည် မည်သည့် ဖြေကြားချက်မဆို မတိုင်မှီ သင့်စာရွက်စာတမ်းများကို ကိုးကားစာကြည့်တိုက်အဖြစ် ပေးသည်။ +အောက်ဖော်ပြထားသည့် ပုံသည် အဓိကအယူအဆကို ပြသည်။ မော်ဒယ်၏ သင်ကြားမှုဒေတာအပေါ် အခြေခံခြင်းမဟုတ်ဘဲ၊ RAG သည် သင်၏ စာရွက်စာတမ်းများ အညွန်းစာကြောင်းစာကြည့်တိုက်အဖြစ် ထည့်သွင်းပေးကာ မေးခွန်းများကို ဖြေဆိုရာ မတိုင်မီ စာရွက်စာတမ်းများနှင့် ဆက်သွယ်စေလိမ့်မည်။ What is RAG -*ဒီဇယားသည် ပုံမှန် LLM (သင်ကြားမှုပညာမှ ခန့်မှန်းခြေ) နှင့် RAG ဖြင့် တိုးမြှင့်ထားသော LLM (သင့်စာရွက်စာတမ်းများကို ဦးစွာ ကိုးကားသည်) ကြားကွာခြားချက်ကို ပြသည်။* +*ဒီပုံတွင် ပုံမှန် LLM (သင်ကြားမှုဒေတာမှ အတုယူသည့်) နှင့် RAG ပါဝင်သော LLM (စာရွက်စာတမ်းများကို အရင်ကြည့်ရှုသည့်) မတူညီခြင်းကို ပြသသည်။* -ကဲ အစိတ်အပိုင်းများသည် အဆုံးသတ်ရန် ဘယ်လို ချိတ်ဆက်ထားသည်ဆိုသည်ကို ကြည့်ပါ။ အသုံးပြုသူ မေးခွန်းသည် အဆင့်လေးဆင့်ဖြင့် ဆက်သွယ်သည် — embedding, vector ရှာဖွေမှု, အကြောင်းအရာ စုစည်းခြင်း, နှင့် ဖြေကြားချက် ထုတ်ပေးခြင်း: +user မေးခွန်းသည် ရှင်းလင်းမှုပြုခြင်း၊ vector search, context စုစည်းခြင်း နှင့် အဖြေဖန်တီးခြင်း ဆိုသည့် လေးဆင့်ဖြတ်သည့် ရွေ့လျားမှုဖြစ်သည်- RAG Architecture -*ဒီဇယားသည် RAG pipeline အဆုံးသတ်အားပြသည် — အသုံးပြုသူ မေးခွန်းသည် embedding, vector ရှာဖွေမှု, အကြောင်းအရာ စုစည်းခြင်း၊ ဖြေဆိုခြင်းဆီ ဆက်သွယ်သွားသည်။* +*ဤပုံတွင် RAG pipeline လုံးလုံးကို ပြသသည် - user မေးထားသော query သည် embedding, vector search, context စုစည်းခြင်း နှင့် အဖြေဖန်တီးခြင်း ဖြတ်သန်းသည်။* -ဒီမော်ဂျူးက ဘယ်ဆင့်တွေကို အကြမ်းဖျင်းရှင်းပြပြီး အရင်နဲ့ ပြင်နိုင်မည့် ကိုဒ်များပါဝင်သည်။ +ဤ module မှာ တစ်ဆင့်ချင်းစီကို အောက်တွင် ရေးသားထားသော ကုဒ်နှင့် အကြောင်းအရာအတတ်နိုင်စွမ်းရှိသည်။ -### ဒီသင်ခန်းစာသည် ဘယ် RAG နည်းလမ်းကို အသုံးပြုပါသလဲ? +### ဒီ သင်ခန်းစာမှာ ဘယ် RAG နည်းလမ်းကို အသုံးပြုသလဲ? -LangChain4j သည် RAG ကို ထည့်သွင်းဆောင်ရွက်ရန် နည်းလမ်း သုံးမျိုးရှိသည်၊ အမျိုးအစားအသီးသီး သဘောပေါက်မှု အဆင့်ကွဲရှိသည်။ အောက်ပါ ဇယားသည် ၎င်းကို နှိုင်းယှဉ်ပြသည်။ +LangChain4j သည် RAG ကို သုံးမျိုးဖြင့် ကျင်းပနိုင်သည်၊ abstraction အခြေအနည်းအနှစ်တစ်ခုစီရှိသည်။ အောက်တွင် ဝှေ့ထားသော ပုံများသည် တစ်ချောင်းချောင်း အချိုးစပ်ထားသည်- Three RAG Approaches in LangChain4j -*ဒီဇယားသည် LangChain4j ရဲ့ Easy, Native, Advanced RAG နည်းလမ်း သုံးမျိုးကို နှိုင်းယှဉ်ပြသည် — အရေးပါသော အစိတ်အပိုင်းများနှင့် အသုံးပြုသင့် အချိန်များ။* +*ဤပုံတွင် LangChain4j ၏ RAG နည်းလမ်း သုံးမျိုး Easy, Native, Advanced တို့ကို တူညီဘက်တွင် နှိုင်းယှဉ် ပြထားသည်။* -| နည်းလမ်း | ဘာလုပ်သလဲ | အကျိုးဆက် | +| နည်းလမ်း | အလုပ်လုပ်ပုံ | အကောက်ချမှု | |---|---|---| -| **Easy RAG** | `AiServices` နှင့် `ContentRetriever` မှတဆင့် အားလုံးကို အလိုအလျောက် တွဲဆက်ပေးသည်။ interface တစ်ခုကို အမှတ်အသားရေးပြီး retriever တပ်ဆင်လိုက်ပါက LangChain4j သည် embedding, ရှာဖွေခြင်းနှင့် မေးမြန်းချက် စုစည်းပြီး အကြောင်းအရာများကို ပြင်ဆင်ပေးသည်။ | ကုဒ်နည်းပါးစေသော်လည်း အဆင့်နှစ်ခုစီတွင် ဘာဖြစ်နေသည် မမြင်ရပါ။ | -| **Native RAG** | ကိုယ်တိုင် embedding မော်ဒယ်ကို ခေါ်ယူ၊ ဆိုင်တည်းကို ရှာ၊ မေးမြန်းချက် တည်ဆောက်ပြီး ဖြေကြားချက်ထုတ်ယူသည် — တစ်ဆင့်ချင်းစီ အတိအကျ ရေးသားသည်။ | ကုဒ်ပိုများသော်လည်း ဆင့်တိုင်းကို ရှုမြင် နားလည်နိုင်ပြီး ပြင်ဆင်နိုင်သည်။ | -| **Advanced RAG** | `RetrievalAugmentor` ဖရိမ်းဝပ်ကို အသုံးပြုပြီး မေးခွန်းပြောင်းလဲသူများ၊ လမ်းညွှန်သူများ၊ ပြန်လည်အဆင့်သတ်မှတ်သူများနှင့် အသုံးပြုမှု ထည့်သွင်းသူများပါဝင်သော ထုတ်လုပ်ရေး စနစ်များအတွက် အသုံးပြုသည်။ | အသုံးပြုရန် လွယ်ကူချောမွေ့မှု အများဆုံး သို့သော် ဖွဲ့စည်းမှု အလွန်ရှုပ်ထွေးသည်။ | +| **Easy RAG** | `AiServices` နှင့် `ContentRetriever` မှ တစ်ဆင့် အလိုအလျောက် လုပ်ဆောင်သည်။ သင် facet ကို အကြောင်းအရာကောင်းစွာ တပ်ဆင်ပြီး LangChain4j မှ embedding, ရှာဖွေရေး နှင့် prompt စုစည်းမှုကို စီမံပေးသည်။ | ကုဒ်အနည်းငယ်, သို့သော် တစ်ဆင့်ချင်း ဘာဖြစ်နေသည်ကို မမြင်ရ။ | +| **Native RAG** | မေးခွန်းEmbedding ကို ခေါ်၊ data store ကို ရှာဖွေ၍ prompt ကို တည်ဆောက်ပြီး အဖြေထုတ်။ တစ်ဆင့်ချင်း တိကျစွာ စီမံနိုင်သည်။ | ပိုမိုကုဒ် သို့သော် အဆင့်တိုင်း ကို မျှော်မှန်းခြင်းနှင့် ပြင်ဆင်နိုင်မှုရှိသည်။ | +| **Advanced RAG** | `RetrievalAugmentor` framework ကို အသုံးပြု၍ query transformer, router, re-ranker, injectors များ ထည့်သွင်းရန် အသုံးပြု၍ ပစ္စည်းထုတ်လုပ်မှုအဆင့် pipeline များထောက်ပံ့သည်။ | အများဆုံး လွတ်လပ်မှု, သို့သော် အဆင့်မြင့် နှင့် ကုန်ကျစရိတ်ကြီး။ | -**ဒီသင်ခန်းစာသည် Native နည်းလမ်းကို အသုံးပြုသည်။** RAG pipeline ၏ ရှုထောင့်တိုင်း — မေးခွန်းအား embedding လုပ်ခြင်း၊ vector ဆိုင်တည်း ရှာဖွေရေး, အကြောင်းအရာ စုစည်းခြင်းနှင့် ဖြေကြားချက် ထုတ်ပေးခြင်း — ကို [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) တွင် တိတိကျကျ ရေးသားထားသည်။ ဒါဟာ သင်ယူမှုအရင်းအမြစ်အနေဖြင့် ကျယ်ပြန့်စွာ ခွဲခြမ်း သိမြင်ရန် အရေးကြီးတာဖြစ်ပြီး ကုဒ်ကို အနည်းဆုံး ပမာဏဖြစ်စေလိုမှုထက် ပိုလေ့လာ နားလည်နိုင်ခြင်းကို ဦးစားပေးထားပါသည်။ မိတ်ဆက်ပြီးနောက် Easy RAG သို့ သွားရန် သို့မဟုတ် ထုတ်လုပ်မှုပြုလုပ်စဉ် Advanced RAG သို့ ညွှန်ပြသည်။ +**ဤ သင်ခန်းစာတွင် Native နည်းလမ်းကို အသုံးပြုသည်။** RAG pipeline ၏ တစ်ဆင့်ချင်း - query hine embedding, vector store ရှာဖွေမှု, context စုစည်းခြင်း၊ နှင့် အဖြေဖန်တီးမှု ကို [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) မှာ တိကျထုတ်ဖော်ထားသည်။ သင်ယူမှုအရ အဆင့်တိုင်းကို သိရှိနားလည်ရန် အရည်အသွေးထိန်းကြီးမှုအတွက် ဆိုးရွားမှုရှိသော ကုဒ် များကို မျှော်မျှော် တင်ပြထားခြင်း ဖြစ်သည်။ မိတ်ဆွေဆikwတတ်လာပါက Easy RAG သို့မဟုတ် Advanced RAG သို့ တိုးတက်ပြောင်းလဲစေရန် အဆင့်ရောက်မြောက်နိုင်ပါသည်။ -> **💡 Easy RAG ကို ရှေ့ပြီးကြည့်ထားပါသလား?** [Quick Start module](../00-quick-start/README.md) တွင် Document Q&A ဥပမာ တစ်ခုပါဝင်သည် ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java))။ ဤအဖြစ် Easy RAG ကို အသုံးပြုချိန် LangChain4j သည် embedding, ရှာဖွေခြင်း၊ မေးမြန်းချက် စုစည်းမှု စနစ်အား လက်လုပ်ပေးသည်။ ဒီမော်ဂျူးသည် pipeline ထဲကို အနက်စိတ်ဝင်စားစွာ ဖြုတ် ဆင့်ခြား ပြသ၍ မိတ်ဆက်ထားသည်။ +> **💡 Easy RAG စိတ်ဝင်စားပါသလား?** LangChain4j သည် `AiServices` နှင့် `ContentRetriever` ဖြင့် embedding, ရှာဖွေမှု၊ prompt စုစည်းမှုအား အလိုအလျောက် စီမံပေးသည့် *Easy RAG* ကိုလည်း ပံ့ပိုးပေးသည်။ ဤ module တွင် ပိုမိုတိကျဖော်ပြပြီး user အနေဖြင့် တစ်ဆင့်ချင်းကို ထိန်းချုပ်နိုင်ရန် အတွက် မျက်နှာဖုံး ဖွင့်ထားသည်။ -အောက်ဖော်ပြပါ ဇယားသည် Easy RAG pipeline ကို Quick Start ဥပမာမှ ပြသသည်။ `AiServices` နှင့် `EmbeddingStoreContentRetriever` က ပြဿနာရှုပ်ထွေးမှုအားလုံးကို ဖုံးကွယ်ပေးသည်။ သင်သည် စာရွက်တင်ပြီး retriever တပ်ဆင်ကာ ဖြေကြားချက်ရရှိသည်။ ဒီမော်ဂျူးမှ Native နည်းလမ်းသည် ထိုအဖုံးဖုံးထားသော အဆင့်တိုင်းကို ဖြုတ်ပြီး ဖော်ပြသည်။ +အောက်တွင် Easy RAG pipeline ကို ပြထားသည်။ `AiServices` နှင့် `EmbeddingStoreContentRetriever` が ကိစ္စရပ်အားလုံးကို ဖုံးကွယ်ထားပြီး၊ စာရွက်စာတမ်း တင်ပြီး retriever နဲ့ ချိတ်ဆက်ပြီး အဖြေများ ရပါတယ်။ ဒီ module မှ Native ကုဒ်သည် လျှို့ဝှက်ထားသော အဆင့်များအားလုံး ဖြုတ်ထားသည်။ Easy RAG Pipeline - LangChain4j -*ဒီဇယားသည် `SimpleReaderDemo.java` မှ Easy RAG pipeline ကိုပြသသည်။ ဒီ module ၌ တိုးတက်သုံးထားသည့် Native နည်းလမ်းနှင့် နှိုင်းယှဉ်ပါ — Easy RAG သည် embedding, ရှာဖွေခြင်း၊ မေးမြန်းချက်စုစည်းခြင်း အား `AiServices` နှင့် `ContentRetriever` ဖြင့် ဖုံးကွယ်သည်။ စာရွက်တင်ပြီး retriever တပ်ပြီး ဖြေကြားချက်ရသည်။ Native နည်းလမ်းသည် pipeline ကို ပြန်ဖွင့်၍ သင့်ကို အဆင့်တိုင်းကို ကိုယ်တိုင် ခေါ်ယူနိုင်စေပါသည်။ +*ဒီပုံသည် Easy RAG pipeline ကို ပြသည်။ Native နည်းလမ်းနှင့် နှိုင်းယှဉ်ပါ။ Easy RAG သည် `AiServices` နှင့် `ContentRetriever` က အမှတ်တံဆိပ်အတိုင်း embedding, ရှာဖွေရေး နှင့် prompt စုစည်းမှုအနောက်ခံလုပ်ငန်းစဉ်များကို ဖုံးကွယ်ထားသည်။ Native နည်းလမ်းသည် တစ်ဆင့်ချင်း - embedding, ရှာဖွေမှု, context စုစည်းမှုနှင့် generator ခေါ်ဆိုမှုများအား user ကိုယ်တိုင် ထိန်းချုပ်၍ မြင်သာရန် လမ်းဖြင့် ဖော်ပြထားသည်။* -## ဘယ်လို အလုပ်လုပ်သလဲ +## မည်သို့ လုပ်ဆောင်သနည်း -ဒီမော်ဂျူးရှိ RAG pipeline သည် အသုံးပြုသူ မေးခွန်းတစ်ခုစဉ်စဉ် မေးလာတိုင်း လုပ်ဆောင်သည့် အဆင့်လေးဆင့်ရှိသည်။ ပထမ အဆင့်မှာ တင်သွင်းသော စာရွက်စာတမ်းကို **ခွဲခြမ်း ဖော်ထုတ်ခြင်း နှင့် ချန့်ခွဲခြင်း** ဖြစ်သည်။ ထိုချန့်အစိတ်အပိုင်းများကို **ဗက်တာ embedding** များသို့ ပြောင်းပြီး သိပ္ပံနည်းကျ သတ်မှတ်ထားသည့်သော စက်တင်ထဲသို့ သိမ်းဆည်းထားသည်။ မေးခွန်းတစ်ခု ရောက်လာသည့်အခါ၊ စနစ်သည် **အဓိပ္ပါယ်အလားအလာ ရှာဖွေမှု** ကို ကျင်းပပြီး အထုတ်ချန့်များကို LLM အတွက် **ဖြေကြားချက် ထုတ်ပေးမှု** အတွက် အကြောင်းအရာအဖြစ် ပို့သည်။ အောက်တိုဘာရာတွင် တစ်ဆင့်စီကို ကိုဒ်နှင့် ဇယားဖြင့် ရှင်းလင်းထားသည်။ ပထမအဆင့်ကို ကြည့်ကြရအောင်။ +ဒီ module ၏ RAG pipeline သည် user မေးခွန်းတိုင်း ဖြည့်ဆည်းရာ အဆင့်လေးဆင့်စီစဉ်ကာ လည်ပတ်သည်။ ပထမဦးဆုံးမှာ တင်ထားသော စာရွက်စာတမ်းကို **ဖော်ထုတ်နှင့် ခွဲခြမ်း** လုပ်သည်။ ထို့နောက် chunk များကို **vector embedding** ပြုလုပ်၍ သိပ္ပံဖြင့် နှိုင်းယှဥ်နိုင်သော အနေအထားတွင် သိုလှောင်သည်။ မေးခွန်းရောက်လာသည့်အခါ သက်ဆိုင်ရာ chunks ကို ရှာဖွေရေးလုပ်၍ LLM သို့ context အဖြစ် ပေးပို့ကာ **အဖြေဖန်တီးမှု** ပြုလုပ်သည်။ အောက်တွင် အဆင့်တိုင်းအား ကုဒ်နမူနာနှင့်ပုံများဖြင့် လမ်းပြထားသည်။ ပထမအဆင့်ကို ကြည့်ကြရအောင်။ -### စာရွက်စာတမ်း ပစ္စည်းစီမံခြင်း +### စာရွက်စာတမ်း ပြုလုပ်ခြင်း [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -စာရွက်တင်သွင်းသောအခါ စနစ်သည် ၎င်းကို ကောက်နှုတ်သည် (PDF သို့မဟုတ် အဆိုဖြစ်သော စာသား)၊ ဖိုင်နာမည် ကဲ့သို့ အချက်အလက်ဖြည့်သွင်းပြီး ချန့်ခွဲသည် — မော်ဒယ်၏ အကြောင်းအရာ စာမျက်နှာထဲ သက်တော်စွာ ထည့်နိုင်မည့် အစိတ်အပိုင်းများ သေးငယ်အောင် ခြားခြားနားနား ချိတ်ဆက်ထားသည်။ ဤချန့်ခွဲမှုသည် အနည်းငယ် တစ်ချောင်းချောင်း ထပ်ဆင့်တက်ကြောင်း ဖြစ်၍ အကြောင်းအရာ ဆက်စပ်မှု မပျောက်ပျောက်ဆုံး။ +စာရွက်စာတမ်းတင်လျှင် စနစ်သည် အဆိုပါစာရွက်စာတမ်း (PDF သို့မဟုတ် ပုံမှန်စာသား) ကို ဖော်ထုတ်ပြီး ဖိုင်နာမည်ကဲ့သို့ မီတာဒေတာတွေနဲ့ချိတ်ဆက်သည်။ ထို့နောက် ရိုးရှင်းသည့် chunks အဖြစ် ခွဲထုတ်သည် - မော်ဒယ်၏ context window ထဲသို့ ကောင်းမွန်စွာ ထည့်သွင်းနိုင်ရန် အတိုအပိုင်းများဖြစ်သည်။ ဤ chunks များသည် နယ်နိမိတ်များတွင် context ပျောက်ဆုံးခြင်း မရှိစေရေးအတွက် အနည်းငယ်ထပ်တိုးခြင်းရှိသည်။ ```java -// အပ်လုဒ်လုပ်ထားသောဖိုင်ကို ဖြေဆိုပြီး LangChain4j Document ထဲသို့ထည့်ပါ +// တင်သွင်းထားသောဖိုင်ကိုပေါင်းထည့်ပြီး LangChain4j Document ထဲတွင်ထုပ်ပိုးပါ Document document = Document.from(content, metadata); -// ၃၀၀-တိုးကင်အပိုင်းများသို့ ခွဲပြီး ၃၀-တိုးကင်သွင်းမှုပါရှိစေပါ +// ၃၀ တိုးကင် Token ဖြင့် 겹치는 ၃၀၀ Token အပိုင်းများသို့ခွဲခြားပါ DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -အောက်ပါ ဇယားတွင် ဒီလုပ်ငန်းစဉ်အား မျက်နှာကြက်ပြုထားသည်။ တစ်ချောင်းချောင်းနှင့် အနီးအနားရှိ ချောင်းပေါင်းများ၌ တူညီသော token အချို့ ညှိရန် ၃၀ token ထပ်ဆင့်ရှိသည် — အဓိကအကြောင်းအရာများ ချန်ပစ်မပျောက်သည့်အထိ ကာကွယ်ထားသည်။ + +အောက်ဖော်ပြပါ diagram သည် အကြောင်းအရာကို ထင်ဟပ်ဖော်ပြသည်။ chunks တစ်ခုချင်းစီတွင် သူ၏ အနီးအနား chunks များနှင့် 30 token လောက် တစ်ချိန်တည်းဖြစ်နေသည်၊ ၎င်းဖြင့် မညီညာသော context အပိုင်းများမှ လုံးလုံးလျက်နေခြင်း မရှိပါ။ Document Chunking -*အဆိုပါဇယားသည် စာရွက်စာတမ်းကို ၃၀ token ထပ်ဆင့်နှင့် ၃၀၀ token လောက် ချန့်ခွဲထားသည့် အခြေအနေကို ပြသသည်။* +*ဒီပုံသည် စာရွက်စာတမ်းကို 300-token chunk များသို့ ခွဲခြမ်းပြီး 30-token overlap ရှိ၍ chunk နယ်နိမိတ်တွင် context ပျောက်ဆုံးမှု မဖြစ်စေရန် ပြထားသည်။* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ဖြင့် စမ်းကြည့်ပါ:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ဖိုင်ကို ဖွင့်ပြီး မေးပါ- -> - "LangChain4j သည် စာရွက်စာတမ်းများကို ချန့်ခွဲခြင်းအတွက် မည်သို့ လုပ်ဆောင်ပြီး ထပ်ဆင့်ခြင်းဟာ အရေးကြီးသနည်း?" -> - "စာရွက်စာတမ်း အမျိုးအစားအလိုက် အကောင်းဆုံး ချန့်အရွယ်ပိုင်းက ဘယ်လောက်ဖြစ်သင့်သလဲ၊ ဘာကြောင့်လဲ?" -> - "ဘာသာစကားများစုံပါသည့် စာရွက်စာတမ်းများ သို့မဟုတ် အထူး ဖော်မတ်ပြုထားသော စာရွက်စာတမ်းများကို မည်သို့ ကာကွယ်သင့်သလဲ?" +> **🤖 GitHub Copilot Chat ဖြင့် စမ်းကြည့်ပါ:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ဖိုင်ကို ဖွင့်ပြီး မေးပါ။ +> - "LangChain4j သည် စာရွက်စာတမ်းများကို ဘာကြောင့် နှင့် မည်သို့ ခွဲထုတ်သနည်း?" +> - "စာရွက်စာတမ်း အမျိုးအစား များအတွက် အကောင်းဆုံး chunk အရွယ်အစား ဘာဖြစ်သနည်း?" +> - "ဘာသာစကားစုံ သို့မဟုတ် အထူး formatting ပါသော စာရွက်များကို မည်သို့ ကိုင်တွယ်မလဲ?" -### အင်ဘက်ဒင်း ရေးဆွဲခြင်း +### Embedding များ ဖန်တီးခြင်း [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -ချောင်းတိုင်းကို အရေအတွက်ပြထားသည့် ကိုယ်စားပြုမှုတစ်ခု သို့ ပြောင်းသည်။ ဒါက အဓိပ္ပါယ်-ကို သင်္ချာနယ်ပယ်တွင် ပြောင်းထားသည်။ embedding မော်ဒယ်သည် chat မော်ဒယ်ကဲ့သို့ "အသိအမြင်" မရှိပါ။ ညွှန်ကြားချက် လိုက်နာခြင်း၊ စဉ်းစားထောက်ထားခြင်း သို့မဟုတ် မေးခွန်းဖြေခြင်း မပြုနိုင်ပါ။ ဒါပေမဲ့ စာသားများကို သင်္ချာနယ်ပယ်တစ်ခုသို့ ဖွင့်လှစ်ရာ၌ တူညီသော အဓိပ္ပါယ်ရှိသည့် စကားလုံးများ၊ စကားစုများကို နီးစပ်စွာ တည်နေရာ ယူစေသည်။ chat မော်ဒယ်ကို ပြောဆိုနိုင်မည့် လူတစ်ယောက်ဟု သတ်မှတ်ပါ၊ embedding မော်ဒယ်ကတော့ အထူးကောင်းမွန်သော စာရွက်စာတမ်း စနစ်ကဲ့သို့ ဖြစ်ပါသည်။ +chunk တစ်ခုချင်းစီကို embedding ဆို၍ နံပါတ်ပြောင်းစနစ်အဖြစ် ပြောင်းလဲသည် - အဓိပ္ပါယ်နေရာမှ နံပါတ်ရပ်တည်ရာနေရာသို့ ကိုယ်စားပြုသည်။ embedding မော်ဒယ်သည် chat မော်ဒယ်ကဲ့သို့ ပညာရည်မဟုတ်ပေမယ့်၊ စကားလုံးများကို နီးစပ်မိသော နံပါတ် vector များအဖြစ် လွှဲပြောင်းသည်။ ဥပမာ -"ကား" ဟုဆိုလျှင် "ကားမောင်းယာဉ်" နီးကျယ်ရာနေရာတွင်၊ "ပြန်အမ်းမူဝါဒ" ဟုဆိုလျှင် "ငွေပြန်ပေးသွင်းပါ" နှင့် နီးစပ်သောနေရာတွင် ထားရှိသည်။ Chat model သည် လူတစ်ယောက်နှင့် စကားပြောသည့်သူဖြစ်ပြီး embedding မော်ဒယ်သည် အကြောင်းပြန်တင်ခြင်းစနစ်တစ်ခုတည်းဖြစ်သည်။ -အောက်ပါဇယားတွင် ဒီအယူအဆအား မှတ်တမ်းပြထားသည် — စာသားထဲသို့ ထည့်ပြီး၊ အရေအတွက်ဗက်တာများ ထွက်လာပြီး၊ အဓိပ္ပါယ်နီးစပ်သော အရာများ သကြားနေရာတွင် တွေ့ရသည်။ +အောက်ဖော်ပြပါပုံသည် ဤအယူအဆကို ပြသည် - စာသားဝင်ပြီးနောက် နံပါတ် vector များထွက်သည်၊ ဆင်တူသော အဓိပ္ပါယ်မှတ်ဉာဏ်များသည် vector လယ်ဒေသတွင် နီးကပ်စွာ တည်ရှိသည်။ Embedding Model Concept -*ဒီဇယားသည် embedding မော်ဒယ်သည် စာသားများကို အရေအတွက်ဗက်တာသို့ ပြောင်းရာအခြေအနေကို ပြသည်၊ "ကား" နှင့် "ယာဉ်" တို့ကဲ့သို့ တူညီသော အဓိပ္ပါယ် အရာများကို vector space တွင် နီးစပ်စေသည်။* +*ပုံသည် embedding မော်ဒယ်သည် စာသားကို နံပါတ် vector များသို့ ပြောင်းလဲပေးကာ ဆင်တူသော အဓိပ္ပါယ်များမှ နီးစပ်သော vector များကို တည်ဆောက်ပေးသည်။* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -အောက်ပါ class ဇယားသည် RAG pipeline ၏ ဆားချက်နှစ်ခု နှင့် LangChain4j အတူတူ အတည်ပြုထားသည့် class များကို ပြပါသည်။ **ကြိုတင် ထည့်သွင်းမှု လမ်းစဉ်** (တစ်ကြိမ် တင်သွင်းသည်) သည် စာရွက်များ ခွဲခြမ်း၍ embedding ပြုလုပ်ပြီး `.addAll()` ဖြင့် သိမ်းဆည်းသည်။ **မေးမြန်းမှု လမ်းစဉ်** (အသုံးပြုသူ မေးတိုင်း သုံးသည်) သည် မေးခွန်းကို embedding ပြုလုပ်ပြီး `.search()` ဖြင့် ဆိုင်တည်းရှာပြီး မတူညီသော အကြောင်းအရာများကို chat မော်ဒယ်သို့ လွှဲပြောင်းသည်။ နှစ်ခုလုံးသည် `EmbeddingStore` interface တစ်ခုအောက်တွင် တွဲဆက်သည်။ + +အောက်တွင် RAG pipeline နှစ်ခုဖြတ်သန်းမှုနှင့် LangChain4j class များကို ပြထားသည်။ ingestion flow မှာ စာရွက်စာတမ်းကို ခွဲထုတ်ပြီး chunk များကို embedded နှစ်ပြောင်းကာ `.addAll()` ဖြင့် သိမ်းဆည်း ထားသည်။ query flow မှာ မေးခွန်းကို embedded ပြုလုပ်ကာ `.search()` ဖြင့် ရှာဖွေပြီး ရလဒ်ကို chat model သို့ ပေးပို့သည်။ နှစ် flow ၏ အချက်မှာ ကိုယ်ပိုင် `EmbeddingStore` အင်တာဖေ့စ်ကို သုံးသည်။ LangChain4j RAG Classes -*ဒီဇယားသည် RAG pipeline ၏ နှစ်ခုလမ်းစဉ်ကို ပြသသည် — ကြိုတင် ထည့်သွင်းမှု နှင့် မေးမြန်းမှု ရှုပ်ဆွဲမှုရှိပြီး EmbeddingStore မှတဆင့် ချိတ်ဆက်သည်။* +*ဤပုံသည် RAG pipeline ၏ ingestion နှင့် query flow များကို ပြ၍ အတူတူ သုံးသော EmbeddingStore ဖြင့် ဆက်သွယ်ကြောင်း ဖြတ်ပြသည်။* -embedding များ သိမ်းဆည်းပြီးနောက် ပါဝင်သော အကြောင်းအရာများသည် vector space တွင် သဘာဝကျကျ အုပ်စုသိမ်းလိုက်သည်။ အောက်ဖော်ပြပါ visualization တွင် ဆက်စပ် သည့် စာရွက်စာတမ်းများသည် နီးစပ်နေရာများအဖြစ် အပေါ်တန်း သို့ စစ်ဆေးရှာဖွေရန် ဖြစ်စေသည်။ +embedding များ သိမ်းထားပြီးနောက် ဆင်တူသော အကြောင်းအရာများသည် vector နီးစပ်သော နေရာများတွင် cluster ဖြစ်တည်လာသည်။ အောက်ဖော်ပြထားသည့် ပုံက စာရွက်စာတမ်းများသည် ဆက်နွယ်မှုရှိသော ခေါင်းစဉ်ကဏ္ဍများဖြင့် နီးစပ်သော နေရာများတွင် အစုတစ်စုအဖြစ် သတ်မှတ်ကြောင်း ပြသည်။ ၎င်းသည် semantic ရှာဖွေမှုလုပ်ဆောင်နိုင်စေသည်။ Vector Embeddings Space -*ဒီ visualization သည် ဆက်စပ်စာရွက်စာတမ်းများကို ၃D vector နယ်ပယ်တွင် အုပ်စုသိမ်းထားသည်ကို ပြသည်၊ အကြောင်းအရာများအား စနစ်တကျ စုစည်းထားသည်။* +*ပုံတွင် ဆက်စပ်နယ်ပယ်များရှိ စာရွက်စာတမ်းများသည် 3D vector နေရာတွင် အစုတစ်စုအဖြစ် တည်ရှိကြောင်း ပြသည်။ ဥပမာ- နည်းပညာစာရွက်များ၊ စီးပွားရေးစည်းမျဉ်းများနှင့် မေးခွန်းများအဖြေများစသည်ဖြင့် ကွဲပြားခြားနားသည်။* -အသုံးပြုသူ ရှာဖွေနေစဉ်၊ စနစ်သည် အဆင့်လေးဆင့် လုပ်ဆောင်သည် သင့်စာရွက်များကို တစ်ကြိမ်သာ embedding ပြုလုပ်သည်၊ မေးခွန်းကို တစ်ကြိမ်စဉ် embedding ပြုလုပ်သည်၊ cosine similarity သုံးပြီး မေးခွန်းဝက်တာနှင့် သိမ်းဆည်းထားသော ဗက်တာ အားလုံးကို နှိုင်းယှဉ်သည်၊ ထိပ်ဆုံး K အပိုင်းများကို ပြန်လည်ပေးပို့သည်။ အောက်ပါ ဇယားတွင် အဆင့်တိုင်းနှင့် LangChain4j class များကို ပြသသည်။ +user မေးခွန်း ရောက်ရှိသည်နှင့် စနစ်သည် အောက်ပါ လေးဆင့် နည်းလမ်းဖြင့် လမ်းလျှောက်သည် - စာရွက်စာတမ်းများကို တစ်ကြိမ် embedding လုပ်၊ မေးခွန်းကို ရှာဖွေရာ embedded လုပ်ခြင်း၊ cosine similarity ဖြင့် မေးခွန်း vector ကို သိမ်းဆည်း vector များနှင့် နှိုင်းယှဥ်၊ အကောင်းဆုံး chunks များကို ပြန်လည်ထုတ်ပေးခြင်း။ အောက်ပါ ပုံသည် အဆင့်တိုင်းနှင့် လုပ်ဆောင်ချက်များကို ဖော်ပြထားသည်။ Embedding Search Steps -*ဒီဇယားသည် embedding ရှာဖွေမှု လုပ်ငန်းစဉ် လေးဆင့်ကို ပြသည်။ - စာရွက်စာတမ်း embed လုပ်ခြင်း၊ မေးခွန်း embed လုပ်ခြင်း၊ cosine similarity ဖြင့် ဗက်တာများနှိုင်းယှဉ်ခြင်း၊ ထိပ်ဆုံး ရလဒ်များ ပြန်ပေးခြင်း။* +*ဤပုံသည် embedding ရှာဖွေမှု လုပ်ငန်းစဉ် လေးဆင့် ဖော်ပြထားသည် - စာရွက်စာတမ်း embedding, မေးခွန်း embedding, vectors ကို cosine similarity နဲ့ နှိုင်းယှဥ်ခြင်း၊ ထိပ်ဆုံး ရလဒ်များ ထုတ်ပေးခြင်း။* -### အဓိပ္ပါယ်ရှာဖွေခြင်း +### Semantic ရှာဖွေမှု [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -သင်မေးခွန်း မေးသောအခါ၊ မေးခွန်းကိုလည်း အင်ဘက်ဒ် လုပ်သည်။ စနစ်သည် မေးခွန်း၏ embedding ကို စာရွက်စာတမ်း ချန့်များ၏ embedding များနှင့် နှိုင်းယှဉ်သည်။ အဓိပ္ပါယ်တူညီမှု မြင့်မားသော ချန့်များကို ရှာပေးခြင်းဖြစ်သည် — သာမန် စကားလုံးကို ကိုက်ညီခြင်းသာမက မူလ အဓိပ္ပါယ်ကိုနားလည်၍ ရှာဖွေသည်။ +မေးခွန်းမေးလျှင် မေးခွန်းကို embedding ပြုလုပ်သည်။ စနစ်သည် မေးခွန်း embedding ကို စာရွက်စာတမ်း chunks embedding များနှင့် နှိုင်းယှဥ်သည်။ keyword ကိုသာ မဟုတ်၊ အဓိပ္ပါယ် ဆိုင်ရာ ဆင်တူမှုအပေါ် အခြေခံပြီး အလွန်နီးကပ်သော chunks များ ရှာဖွေသည်။ ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -အောက်ပါ ဇယားသည် အဓိပ္ပါယ်အလားအလာရှာဖွေမှု နှင့် ရိုးရိုး စကားလုံး အခြေပြု ရှာဖွေမှု မတူညီမှုကို ပြသသည်။ "vehicle" စကားလုံးဖြင့် ရှာဖွေခြင်းသည် "cars and trucks" ဆိုသော ချန့်များကို မတွေ့နိုင်သော်လည်း အဓိပ္ပါယ်ရှာဖွေမှုသည် ဤနှစ်ခုသည် တူညီကြောင်း နားလည်ကာ ထိပ်တန်း တွေ့ဆုံမှုအဖြစ် ပြန်ပေးသည်။ + +အောက်ဖော်ပြပါ ပုံသည် semantic ရှာဖွေမှုနှင့် ရိုးရာ keyword ရှာဖွေမှုများကို နှိုင်းယှဥ်ထားသည်။ "vehicle" ဆို keyword ရှာဖွေမှုပုံစံသည် "cars and trucks" ပါသော chunk ကို မတိုက်ဆိုင်နိုင်သော်လည်း semantic search အနေနဲ့ ၎င်း၏ အဓိပ္ပါယ်ကို နားလည်၍ ထို chunk ကို အမြင့်ဆုံး အဆင့် တင်ပေးသည်။ Semantic Search -*ဒီဇယားသည် စကားလုံးအခြေပြု ရှာဖွေမှုနှင့် အဓိပ္ပါယ်အလားအလာ ရှာဖွေမှုများကို နှိုင်းယှဉ်ပြသသည် — ဂလိုက်ဂိုက် မတူသော စကားလုံးများကို သဘောတူကြောင်း နားလည်၍ စပ်ဆိုင်ရာ အကြောင်းအရာကို ရှာမဟုတ်ပါ.* -ခေါင်းဆောင်အောက်တွင်၊ ဆွဲဆောင်မှုကို cosine similarity အသုံးပြုထားသည် — အဓိကအားဖြင့် "ဤနှစ်မြင်းသည် တူညီသောလမ်းကြောင်းသို့ညွှန်ပြနေသလား?" ဟူသော မေးခွန်းကိုမေးတာပဲဖြစ်သည်။ နှစ်ခုသော ခွဲထုတ်ချက်များသည် စကားလုံးများကို မတူညီဘဲ အသုံးပြုနိုင်သော်လည်း အဓိပ္ပာယ်တူမယ်ဆိုရင် ၎င်းတို့၏ဗက်တာများ သဘောတူညီသောလမ်းကြောင်းသို့ ညွှန်ပြပြီး မျှသံမဟုတ်နှုန်းသည် 1.0 အနီးတွင်ရှိသည်။ +*ဤပုံက keyword ရှာဖွေမှုနှင့် semantic ရှာဖွေမှုကို နှိုင်းယှဉ်ပြထားသည်။ semantic ရှာဖွေမှုက အဓိပ္ပါယ်အလိုက် ဆင်တူသော အကြောင်းအရာများကို မှီငြမ်းပြီး keyword မတူခဲ့လည်း ရလဒ်ပေးသည်။* -Cosine Similarity +နောက်ကြောင်းအဖြစ် similarity ကို cosine similarity ဖြင့် တိုင်းတာသည်။ ၎င်းမှာ "ဤ နှစ်ခု မြှားများသည် အတူတည်နေရာ ဆန့်ကျင်ဘက်သို့ မညီနေပါက?" ဟူသော မေးခွန်းမေးခြင်းအတှင်းဖြစ်ပြီး တစ်ခုချင်းစီ ထုံးစံအသုံးအနှုန်း မတူ၍ပါက vector များသည် တူညီသော ဦးတည်ချက်အား ထောက်လှမ်း၍ 1.0 အနီးဆုံး အဆင့်တန်ဖိုး ရရှိသည်။ -*ဤပုံဆွဲက cosine similarity ကို embedding vectors များအကြားထောင့်အဖြစ်ဖော်ပြသည် — ပို၍ညီသောဗက်တာများမှာ 1.0 အနီးသို့ အမှတ်ယူကာ သင်္ချာနှင့်အဓိပ္ပာယ်တူဆက်စပ်မှုမြင့်မားခြင်းကို ပြသသည်။* +Cosine Similarity +*ဒီပုံပြင်ကတော့ cosine similarity ကို embedding vectors တွေရဲ့ ငယ်မှု အနားအနီးအဖြစ် ဖော်ပြထားပါတယ် — ပိုတူညီတဲ့ vectors တွေဟာ 1.0 နီးပါးရောက်ပြီး semantic similarity မြင့်မားကြောင်း ပြသပါတယ်။* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ဖြင့် စမ်းသပ်ပါ:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ဖိုင်ကိုဖွင့်ပြီး အောက်ပါမေးခွန်းများကို မေးပါ- -> - "similarity search သည် embeddings များနှင့် ဘယ်လို အလုပ်လုပ်ပြီး အမှတ်ကို ဘယ်လိုဆုံးဖြတ်ပါသလဲ?" -> - "similarity threshold ဘယ်လို သတ်မှတ်သင့်ပြီး ၎င်းသည် ရလဒ်များကို ဘယ်လို သက်ရောက်ပါသလဲ?" -> - "သင့်မေးခွန်းနှင့်သင်္ကေတ တိုက်ညီမှုမရှိသော စာရွက်များမတွေ့ပါက ဘယ်လို ကိုင်တွယ်ရမလဲ?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat နဲ့ စမ်းသပ်ကြည့်ပါ:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ဖိုင်ကိုဖွင့်ပြီးမေးမြန်းပါ - +> - "embedding တွေနဲ့ similarity search ဘယ်လိုအလုပ်လုပ်ပြီး score ကို ဘာတွေဆုံးဖြတ်သလဲ?" +> - "Similarity threshold ဘယ်လိုသတ်မှတ်ရမလဲ၊ ရလဒ်တွေကို ဘယ်လိုသက်ရောက်သလဲ?" +> - "သက်ဆိုင်ရာစာရွက်စာတမ်းတွေမတွေ့ရင် ဘာလုပ်ဆောင်ရမလဲ?" -### အဖြေထုတ်လုပ်မှု +### ဖြေဆိုမှု ထုတ်လုပ်ခြင်း [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -အရေးပါဆုံး ခွဲထုတ်ချက်များကို သတ်မှတ်ချက်ပြည့်ဝသော prompt တစ်ခုတည်းအဖြစ် စုပေါင်းထားပြီး၊ ထို prompt တွင် အသိပေးချက်များ၊ ရှာဖွေဖော်ပြချက်များနှင့် အသုံးပြုသူ၏မေးခွန်းပါဝင်သည်။ မော်ဒယ်သည် ထိုအချက်အလက်များအပေါ် မူတည်၍သာ အဖြေထုတ်ပေးသည် — ၎င်းသည် မတိရစ္ဆာန်ပြုမှုမှ ကာကွယ်ပေးနိုင်သည်။ +အဆင့်မြင့်ဆုံး သက်ဆိုင်ရာchunks များကို explicit အညွှန်းများ၊ ရယူထားသော context နှင့် အသုံးပြုသူ၏မေးခွန်းတို့ ပါဝင်သော စနစ်တကျ prompt တစ်ခုအဖြစ်စုစည်းသည်။ မော်ဒယ်သည် အဆိုပါ chunks များကိုဖတ်ပြီး အချက်အလက်အပေါ်အခြေခံ၍ဖြေဆိုသည် — မော်ဒယ်သည် မျက်နှာချင်းဆိုင်ရှိသည့် အချက်အလက်များကိုသာအသုံးပြုနိုင်ခြင်းကြောင့် မဟုတ်မှားခြင်းကို တားဆီးပေးသည်။ ```java String context = matches.stream() @@ -237,65 +236,65 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -အောက်ပါပုံရိပ်သည် ဤ စုပေါင်းခြင်းလုပ်ငန်းကို ဖေါ်ပြထားသည် — ရှာဖွေရေးအဆင့်မှ ထိပ်တန်းအမှတ်ရ ခွဲထုတ်ချက်များကို prompt ပုံစံအား ထည့်သွင်းပြီး `OpenAiOfficialChatModel` သည် အခြေခံထားသော အဖြေကို ထုတ်ပေးသည်။ +အောက်ပါပုံကတော့ဤစုစည်းမှုကို ပြသထားပြီး — ရှာဖွေမှုအဆင့်မှ အကောင်းဆုံး score ရရှိသော chunks များကို prompt အစီအစဉ်ထဲ ထည့်သွင်းပြီး `OpenAiOfficialChatModel` က အခြေခံထားသောဖြေဆိုချက်တစ်ခု ထုတ်ပေးသည်။ Context Assembly -*ဤပုံရိပ်က ထိပ်တန်းအမှတ်ရ ခွဲထုတ်ချက်များကို သတ်မှတ်ချက်ပြည့်ဝသော prompt အဖြစ် စုပေါင်းထားပုံကို ပြသပြီး မော်ဒယ်အား သင်၏ဒေတာမှ အခြေခံအဖြေထုတ်ပေးရန် ခွင့်ပြုသည်။* +*ဒီပုံရိပ်ကတော့ အကောင်းဆုံး score ရရှိသော chunks များကို စနစ်တကျ prompt မှာ စုစည်းပေးခြင်းအားဖြင့် မော်ဒယ်မှ သင့်ဒေတာမှ အခြေခံသောဖြေဆိုချက် ထုတ်ပေးပုံကို ပြထားသည်။* -## အပ်्लီကေးရှင်းကို ရုပ်သိမ်းအသုံးပြုခြင်း +## Application ကို chạy လုပ်ခြင်း -**တပ်ဆင်မှုအတည်ပြုခြင်း-** +**စတင်အသုံးပြုနိုင်မှု စစ်ဆေးမှု:** -`.env` ဖိုင်ကို root directory မှာ Azure ခြံ့ချက်များဖြင့် ရှိနေသည်ဟု အတည်ပြုပါ (Module 01 တွင် ဖန်တီးထားသော)။ ကွက်တွင်း မှာ (`03-rag/`) အောက်ပါကို ရိုက်ထုတ်ပါ- +Module 01 မှာပြုလုပ်ထားတဲ့ Azure ခံစားခွင့်အချက်အလက်ဖြင့် `.env` ဖိုင် ရှိ/မရှိ စစ်ဆေးပါ။ ဒီ module directory (`03-rag/`) မှာ အောက်ပါအတိုင်း chạy လုပ်ပါ။ **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကိုပြသသင့်သည်။ +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကိုပြသသင့်သည် ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT တို့ကို ပြသသင့်သည်။ +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ဖေါ်ပြသင့်သည်။ ``` -**အပ်လီကေးရှင်း စတင်ခြင်း-** +**Application စတင်ခြင်း:** -> **မှတ်ချက်-** သင်သည် ရှိပြီးသား အပ်လီကေးရှင်းအားလုံးကို root directory မှ `./start-all.sh` ဖြင့် စတင်ထားပြီး (Module 01 တွင် ဖော်ပြထားသည့်အတိုင်း) ဤကွက်တွင်းသည် port 8081 ပေါ်တွင် ရပ်တည်နေပါသည်။ အောက်ပါ စတင်ပေးစနစ်များကို ကျော်လွှားပြီး http://localhost:8081 သို့ တိုက်ရိုက် ဆက်သွယ်နိုင်သည်။ +> **မှတ်ချက်:** အကယ်၍ root directory မှ `./start-all.sh` ကို အသုံးပြုပြီး application များအားလုံးအား စတင်ခဲ့ပြီးဖြစ်ပါက (Module 01 မှ ဖေါ်ပြထားသည့်အတိုင်း) ဒီ module ဟာ အခု port 8081 မှာ ရပ်တည်ပြီးဖြစ်ပါတယ်။ အောက်ပါ စတင်ရေးမေးခွန်းများကို ချန်ထားနိုင်ပြီး တိုက်ရိုက် http://localhost:8081 ကို သွားနိုင်ပါသည်။ -**ရွေးချယ်မှု ၁: Spring Boot Dashboard အသုံးပြုမှု (VS Code အသုံးပြုသူများအတွက် အကြံပြုသည်)** +**နည်းလမ်း 1: Spring Boot Dashboard ကို အသုံးပြုခြင်း (VS Code အသုံးပြုသူများအတွက် အကြံပြုချက်)** -Dev container တွင် Spring Boot Dashboard extension ပါဝင်သည်၊ ၎င်းသည် Spring Boot အပ်လီကေးရှင်းအားလုံးကို visual interface ဖြင့် စီမံခန့်ခွဲနိုင်သည်။ VS Code ၏ မြို့တော်ဘား (Activity Bar) ၏ ဘေးကို စမ်းသပ်ပါ (Spring Boot သင်္ကေတ). +Dev container တွင် Spring Boot Dashboard extension ပါဝင်ပြီး၊ အဲဒီနေရာမှ Spring Boot applications များကို ရှုမြင်၊ စီမံခန့်ခွဲနိုင်ပါသည်။ VS Code ၏ ဘယ်ဘက် Activity Bar ထဲမှာ Spring Boot အိုင်ကွန်ကို တွေ့ရပါမည်။ -Spring Boot Dashboard မှ- -- Workspace အတွင်းရှိ Spring Boot အပ်လီကေးရှင်းအားလုံးကို ကြည့်ရှုနိုင်သည် -- အပ်ဴလီကေးရှင်းများကို တစ်ချက်နှိပ်၍ စတင်/ ရပ်ဆိုင်းနိုင်သည် -- အပ်လီကေးရှင်းမှတ်တမ်းများကို အချိန်နှင့်တပြေးညီ ကြည့်ရှုနိုင်သည် -- အပ်လီကေးရှင်းအခြေအနေ ကြည့်ရှုနိုင်သည် +Spring Boot Dashboard မှာ လုပ်နိုင်တာများ - +- Workspace ထဲရှိ Spring Boot applications အားလုံးကို ကြည့်ရှုနိုင်ခြင်း +- Application များကို တစ်ချက်နှိပ်ပြီး စတင်/ရပ်နားနိုင်ခြင်း +- Application အမှတ်တရများကို Real-time တွင် ကြည့်ရှုနိုင်ခြင်း +- Application အခြေအနေ ကို မျက်မြင် စောင့်ကြည့်နိုင်ခြင်း -"rag" အတွက် play ခလုတ်ကိုနှိပ်၍ module ကို စတင်ပါ၊ သို့မဟုတ် အားလုံးကို တပြိုင်နက် စတင်နိုင်ပါသည်။ +"rag" အနားရှိ play button ကို နှိပ်၍ ဒီ module ကို စတင်ပါ၊ ဒါမှမဟုတ် module အားလုံးကို တပြိုင်နက် စတင်နိုင်သည်။ Spring Boot Dashboard -*ဤ screenshot သည် VS Code တွင် Spring Boot Dashboard ကို ပြသ၍ အပ်လီကေးရှင်းများကို visual ဖြင့် စတင်၊ ရပ်ဆိုင်း၊ နေရပ်ကြည့်ရန် ခွင့်ပြုသည်။* +*ဒီ screenshot က VS Code မှာ Spring Boot Dashboard ကို ပြထားပြီး application များကို စတင်၊ ရပ်နား နှင့် စောင့်ကြည့်ရန် လွယ်ကူအောင် ပံ့ပိုးနေသည်။* -**ရွေးချယ်မှု ၂: shell scripts အသုံးပြုမှု** +**နည်းလမ်း ၂: shell script များ အသုံးပြုခြင်း** -ဝဘ်အပ်လီကေးရှင်းအားလုံး (module 01-04) စတင်ခြင်း- +ဝက်ဘ် applications အားလုံး (modules 01-04) ကို စတင်ရန်: **Bash:** ```bash -cd .. # အရင်းမြစ်ဖိုင်လမ်းကြောင်းမှ +cd .. # စနစ်ရဲ့အမြစ်ဖိုင်တွဲမှ ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # မူလဖိုင်တိုက်မှ +cd .. # မူရင်းဖိုင်လမ်းကြောင်းမှ .\start-all.ps1 ``` -သို့မဟုတ် ဤ module ကိုသာ စတင်ခြင်း- +သို့မဟုတ် ဒီ module ကိုသာ စတင်ရန် - **Bash:** ```bash @@ -309,129 +308,129 @@ cd 03-rag .\start.ps1 ``` -တစ်ခုချင်းစီ၏ script များသည် အော်တိုမက်တစ် `.env` ဖိုင်မှ environment variables များအား ပြီးပြည့်စုံစွာ load ပြုလုပ်ပြီး JAR မရှိပါက တည်ဆောက်ပေးသည်။ +အဆိုပါ script ၂ မျိုးစလုံးဟာ root ဖိုင်ထဲ `.env` ဖိုင်မှ ပတ်ဝန်းကျင်မူလအပြောင်းအလဲများကို အလိုအလျောက် ဖတ်ယူပြီး JAR ဖိုင်များ မရှိပါက တည်ဆောက်ပေးပါသည်။ -> **မှတ်ချက်:** စတင်မှုမပြုမီ အားလုံးကို manual ဖြင့် တည်ဆောက်လိုပါက- +> **မှတ်ချက်:** စတင်မလုပ်မီ module များအားလုံးကို လက်ဖြင့် တည်ဆောက်ချင်လျှင် - > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -သင်၏ browser တွင် http://localhost:8081 ကို ဖွင့်ပါ။ +http://localhost:8081 ကို သင့် browser တွင်ဖွင့်ပါ။ -**ရပ်တန့်ရန်-** +**ရပ်တန့်ရန်:** **Bash:** ```bash -./stop.sh # ဤမော်ဂျူးလ်တည်းတင် +./stop.sh # ဤမော်ဂျူးသည်သာ # သို့မဟုတ် -cd .. && ./stop-all.sh # မော်ဂျူးလ်အားလုံး +cd .. && ./stop-all.sh # မော်ဂျူးအားလုံး ``` **PowerShell:** ```powershell -.\stop.ps1 # ဒီမော်ဂျူးသာ -# ဒါမှမဟုတ် +.\stop.ps1 # ဒီမော်ဂျူးတစ်ခုတည်း +# သို့မဟုတ် cd ..; .\stop-all.ps1 # မော်ဂျူးအားလုံး ``` -## အပ်လီကေးရှင်းအသုံးပြုပုံ +## Application အသုံးပြုမှု -အပ်လီကေးရှင်းသည် စာရွက်များ တင်သွင်းခြင်းနှင့် မေးခွန်းမေးခြင်းများအတွက် web interface ပေးသည်။ +Application ကစာရွက်စာတမ်းတင်ခြင်းနဲ့ မေးခွန်းမေးခွင့်ကို ဝက်ဘ် အင်တာဖေ့စ်ပေးသည်။ RAG Application Interface -*ဤ screenshot တွင် RAG application interface ကို ဖော်ပြထားသည်၊ ၎င်းတွင် သင်သည် စာရွက်များကို တင်သွင်းပြီး မေးခွန်းမေးနိုင်သည်။* +*ဒီ screenshot က RAG application အင်တာဖေ့စ်အားပြထားပြီး ကိုယ့်စာရွက်စာတမ်းတင်ပြီး မေးခွန်းမေးနိုင်မှုပေးသည်။* -### စာရွက်တင်ခြင်း +### စာရွက်စာတမ်း တင်ခြင်း -စာရွက်တင်ခြင်းဖြင့် စတင်ပါ - စမ်းသပ်ရန် TXT ဖိုင်များ ဆောင်းပါးသည်။ ဤ directory တွင် `sample-document.txt` ဖိုင် တစ်ခု ပါဝင်ပြီး ပို၍ သေချာစွာ စမ်းသပ်နိုင်ရန် LangChain4j features, RAG implementation နှင့် အကောင်းဆုံး အသုံးပြုမှုများအကြောင်း ပါဝင်သည်။ +အစပြုသောအခါ စာရွက်စာတမ်းတင်ပါ - စမ်းသပ်ရန် TXT ဖိုင်များက အသင့်တော်ဆုံး ဖြစ်ပါသည်။ ဒီ directory ထဲမှာ `sample-document.txt` တစ်ခု ပေးထားပြီး LangChain4j ပါဝင်မှု, RAG အကောင်အထည်ဖော်ခြင်းနှင့် အကောင်းဆုံးလေ့လာမှုများ ပါဝင်သည် - စနစ်ကို စမ်းသပ်ရန် သင့်တော်မည်။ -စနစ်သည် သင်၏ စာရွက်ကို ကောက်နှုတ်ပြီး chunks များခွဲထုတ်ကာ အပိုင်းတိုင်းအတွက် embedding များ ဖန်တီးသည်။ ၎င်းသည် ဖိုင်တင်ပြီး မျက်နှာသစ်အလိုအလျောက်ဖြစ်ပေါ်သည်။ +စနစ်က သင့်စာရွက်စာတမ်းကို ပြုလုပ်၊ ဖတ်တိုက်တိုက် ခွဲခြားပြီး chunks များဖန်တီး၊ ဖိုင်တစ်ခုစီအတွက် embedding များ ဖန်တီးပေးသည်။ အကြောင်းအရာ upload ဖြစ်ချင်း ကိုယ်တိုင်ဖြစ်ပေါ်သည်။ -### မေးခွန်းမေးရန် +### မေးခွန်း မေးခြင်း -ယခု စာရွက် အကြောင်းအရာနှင့်ပတ်သက်၍ အသေးစိတ် မေးခွန်းများ မေးပါ။ စာရွက်တွင်ပုံမှန်ထုတ်ပြန်ထားသော မှန်ကန်သော အချက်အလက်များ မေးခြင်းကို စမ်းသပ်ကြည့်ပါ။ စနစ်သည် သင့်မေးခွန်းနှင့် ဆက်စပ်သော chunk များကို ရှာဖွေ၍ prompt ထဲမှာထည့်သွင်းကာ အဖြေထုတ်ပေးသည်။ +ယခု စာရွက်စာတမ်းအကြောင်းအရာကို သတ်မှတ်ထားသော မေးခွန်းများ မေးပါ။ စာရွက်စာတမ်းထဲမှာ သက်သေပြထားသော အချက်အလက်တစ်ခုခုကို စမ်းသပ် ကြည့်ပါ။ စနစ်က သက်ဆိုင်ရာ chunks များကို ရှာဖွေပြီး prompt ထဲ ထည့်သွင်း၊ ဖြေဆိုချက်ထုတ်ပေးသည်။ -### မူရင်းရင်းမြစ် ကို ရှာဖွေစစ်ဆေးခြင်း +### အရင်းအမြစ်ကို စစ်ဆေးခြင်း -မည်သည့်အဖြေမျှ မူရင်းရင်းမြစ်အားနှင့် အညီ similarity score များနှင့်အတူ မူရင်းကို ရည်ညွှန်းချက်များ ပါဝင်သည်။ ဒီ score များ (0 မှ 1 အထိ) သည် သင်၏မေးခွန်းနှင့် ထားရှိ သော chunk တစ်ခုချင်းစီ၏ ဆက်စပ်မှုအရည်အသွေးကို ပြသည်။ score မြင့်များမှာ ပိုပြီး ကိုက်ညီမှုရှိသည်။ ၎င်းသည် မူရင်းအချက်အလက်နှင့် အဖြေကို နှိုင်းယှဉ်စစ်ဆေးရန် ခွင့်ပြုသည်။ +တိုက်ရိုက်ဖြေဆိုချက်တိုင်းမှာ similarity score နဲ့ source references ပါဝင်သည်။ score များ(0 မှ 1 အထိ)ဟာ မေးခွန်းနဲ့ သက်ဆိုင်မှု အတိအကျကို ပြသသည်။ score မြင့်သည်မှာ ပို၍ မေးခွန်းနဲ့ ညီညွတ်သည်ဟု ဆိုလိုသည်။ ဒါက သင့်ရဲ့ ဖြေဆိုချက်ကို အရင်းအမြစ်နှင့် တင်ပြရန် အကူအညီပေးပါသည်။ RAG Query Results -*ဤ screenshot တွင် မေးခွန်း ရလဒ်များကို generated အဖြေ၊ ရင်းမြစ်များနှင့် တစ်ခုချင်းစီ ရှာဖွေဖော်ပြချက်အတွက် ဆက်စပ်မှုအမှတ်များနှင့် ပြသထားသည်။* +*ဒီ screenshot က query ရလဒ်များကို ပြထားပြီး စဖြေပေါ်ပြီးတဲ့ ဖြေချက်၊ source reference နှင့် အချင်းချင်း ညီမှု score များ ပါဝင်သည်။* -### မေးခွန်း မျိုးစုံ နှင့် စမ်းသပ်ကြည့်ပါ +### မေးခွန်း အမျိုးမျိုးဖြင့် စမ်းသပ်ရန် -မေးခွန်း အမျိုးအစားမျိုးစုံအား try ကြည့်ပါ- -- အသေးစိတ် အချက်အလက်များ: "အဓိက အကြောင်းအရာကဘာလဲ?" -- နှိုင်းယှဉ်ချက်များ: "X နဲ့ Y ကြားက ကွာခြားချက်ဘာလဲ?" -- အကျဉ်းချုပ်များ: "Z အကြောင်း အဓိကအချက်များကို အကျဉ်းချုပ်ပါ" +မေးခွန်း အမျိုးအစားများကို ကြိုးစားစမ်းပါ - +- သတ်မှတ်ချက် အချက်အလက်: "အဓိက ခေါင်းစဉ် ဘာလဲ?" +- နှိုင်းယှဉ်ချက်များ: "X နဲ့ Y ရဲ့ ကွာခြားချက်က ဘာလဲ?" +- အကျဉ်းအနှုတ်: "Z အကြောင်း အဓိကအချက်များ အကျဉ်းချုပ်ပါ" -မေးခွန်းသည် စာရွက်အကြောင်းအရာနှင့် မှန်ကန်စွာ ကိုက်ညီသည့်အတိုင်း ဆက်စပ်မှု အမှတ်များ ပြောင်းလဲမှုကို ကြည့်ပါ။ +မေးခွန်းနဲ့စာသားအကြောင်းအရာညီညာမှုပေါ်မူတည်ပြီး score များ ဘယ်လို ပြောင်းလဲသလဲ ကြည့်ပါ။ -## အဓိကသင်ခန်းစာများ +## အဓိက အတွေးအခေါ်များ -### Chunking မဟာဗျူဟာ +### Chunking Strategy -စာရွက်များကို ၃၀၀ token အသုံးပြု၍ ခွဲထုတ်ပြီး နောက်တချက်နှင့် ၃၀ token တပြန် overlap ဖြစ်သည်။ ဤနည်းလမ်းသည် ချ်န့် တစ်ခုချင်းစီမှာ အဓိပ္ပာယ်ရှိရာ သဘောတရားပါဝင်စေရန်ရှေ့နောက် context လုံလောက်နေစေပြီး prompt ထဲတွင် ချ်န့်များစွာ ထည့်သွင်းနိုင်စေရန် အရွယ်အစား သေးငယ်စေသည်။ +စာရွက်စာတမ်းများကို 300-token အသီးသီးဖြင့် ခွဲထုတ်ပြီး 30 tokens overlap ပါရှိသည်။ ဒီပမာဏဟာ chunks တစ်ခုလျှင် အဓိကအချက်များ ပါဝင်ရန်နှင့် prompt တစ်ခုထဲမှာ chunks များစွာ ထည့်သွင်းနိုင်ရန် ကြားလမ်းတစ်ခုဖြစ်ပါသည်။ -### ဆွဲဆောင်မှု တန်ဖိုးများ +### Similarity Scores -ရှာဖွေပြီး ချ်န့်တစ်ခုချင်းစီသည် အသုံးပြုသူမေးခွန်းနှင့် ဘယ်လောက်ဆက်စပ်သလဲကို ပြသသည့် ၀ မှ ၁ အထိ similarity score နှင့် လာသည်။ အောက်ပါပုံသည် score အတတ်အနည်းများနှင့် စနစ်မှ ၎င်းတို့ကို ရလဒ်များစစ်ထုတ်ရာတွင် ဘယ်လိုအသုံးပြုသလဲကို ဖော်ပြသည်- +ရယူထားသော chunks တစ်ခုချင်းစီမှာ 0 နဲ့ 1 အကြား similarity score ပါဝင်ပြီး မေးခွန်းနဲ့ အနီးကပ်ပမာဏကို ဖော်ပြသည်။ အောက်ပါပုံက score ရှုထောင့်များနှင့် စနစ်၏ ရလဒ်ချင်းစစ်ထုတ်မှုကို ပြပြထားသည်။ Similarity Scores -*ဤပုံအရ စနစ်အရ လုံးဝမဆက်စပ်သောချ်န့်များကို ဖယ်ရှားရန် 0.5 ဆွဲဆောင်မှုနိမ့်ဆုံးမာတိကာထားရှိသည်။* +*ဒီပုံက score 0 မှ 1 အထိရှိခြင်းကို ပြပြီး အနိမ့်ဆုံး threshold 0.5 က သက်ဆိုင်မဲ့ chunks မဟုတ်တာတွေကို ဖြုတ်ချခြင်းထင်ရှားစေသည်။* -score များသည် ၀ မှ ၁ အထိ ရှိသည်- -- 0.7-1.0: အလွန်ဆက်စပ်မှုမြင့်မား၍ တိတိကျကျ ကိုက်ညီသည် -- 0.5-0.7: ဆက်စပ်မှုရှိပြီး သဘောတရားကောင်းသည် -- 0.5 အောက်: ပြွတ်လပ်၍ ဆက်စပ်မှုမရှိသော +Score များသည် - +- 0.7-1.0: အရမ်းသက်ဆိုင်ပြီး အတိအကျကြောင်း မြင်သာသည် +- 0.5-0.7: သက်ဆိုင်ပြီး ကောင်းမွန်သော context ရှိသည် +- 0.5 အောက်: ဖြုတ်ထုတ်သည်၊ မတူညီခြင်းများ -စနစ်သည် အရည်အသွေး အထူးသတ္တိရှိရန် မီးပေါ် threshold အထက်ရှိ ချ်န့်များကိုသာ ရယူသည်။ +စနစ်သည် အနိမ့်ဆုံး threshold များကို ကျော်လွန်သော chunks များကို တင်ပြသည့်အတွက် အရည်အသွေးရှိစေသည်။ -Embedding များသည် အဓိပ္ပာယ် cluster များအား ရှင်းလင်းစွာ ခြေရာခံနိုင်သော်လည်း မာနော့ချက်ချက်များရှိသည်။ အောက်ပါ ပုံသည် ပြဿနာများ ဖြစ်ပေါ်လေ့ရှိသော နေရာများဖြစ်သည် — ချ်န့်များ အရွယ်အစားကြီးလွန်းသောကြောင့် မပေါ့မပါတဲ့ဗက်တာများ ဖြစ်လာခြင်း၊ ချ်န့်များသေးလွန်း၍ context မရှိခြင်း၊ မပြတ်သားသော စကားလုံးများသည် cluster များစွာသို့ ညွှန်ပြခြင်း၊ နှင့် နိုင်ငံတကာနေစဉ်အမှတ် အခြား ပစ္စည်းအပိုင်းစနစ်များအား embedding များနှင့် ကိုက်ညီစေခြင်းမရှိခြင်းများပါဝင်သည်။ +Embeddings များသည် အဓိပ္ပာယ်တူ cluster များရှိလျှင် ကောင်းစွာ လုပ်ဆောင်ရာမှ ခွဲခြားနိုင်ခြင်းများ ရှိသော်လည်း blind spots လည်းရှိသည်။ အောက်ပါပုံကတော့ ပျက်ကွက်မှုများ လူသုံးများ ပြထားပြီး — chunks များသောကြာ ကြီးလွန်းလျှင် vectors သွင်းမှု မရှင်းလင်း၊ chunks သေးလွန်းရင် context မရှိ၊ မရှင်းလင်းသော ဖြစ်စဉ်များက cluster များသို့ မြှောင်းပြောခြင်း ၊ တိတိကျကျ ပြန်လည်ရှာဖွေခြင်း (ID, part numbers) တွေဟာ embedding နဲ့ မလုပ်နိုင်ကြောင်း ပြသသည်။ Embedding Failure Modes -*ဤပုံသည် embedding ပျက်ကွက်မှုအမျိုးမျိုးကို ဖော်ပြထားသည် - ချ်န့်များကြီးလုံးဝန်းခြင်း၊ ချ်န့်များသေးလွန်းခြင်း၊ မပြတ်သားသော စကားများ cluster များစွာကို ညွှန်ပြခြင်းနှင့် တိတိကျကျ ထိုးထားသော lookup များ (ID များ၊ အပိုင်းနံပါတ်များ) မပေးနိုင်ခြင်းတို့ ပါဝင်သည်။* +*ဒီပုံက embedding ပျက်ကွက်မှုများဖြစ်ပုံများကို ပြထားပြီး — chunks ကြီးတယ်၊ chunks သေးတယ်၊ မရှင်းလင်းသော စကားလုံးများက cluster များသို့ ရည်ညွှန်းသည်၊ ID လိုအတိအကျရှာဖွေမှုမျိုးတွေ မလုပ်ဆောင်နိုင်ကြောင်း ဖော်ပြထားသည်။* -### In-Memory သိမ်းဆည်းချက် +### In-Memory Storage -ဤ module သည် ရိုးရှင်းမှုအတွက် in-memory storage ကို အသုံးပြုသည်။ အပ်လီကေးရှင်းကို ပိတ်ပြီး ပြန်ဖွင့်သည်နှင့် အပ်โหลดလုပ်ထားသောစာရွက်များ ပျောက်ဆုံးသွားသည်။ ထုတ်လုပ်ရေး စနစ်များတွင် Qdrant သို့မဟုတ် Azure AI Search ကဲ့သို့သော ထာမာမည့် vector database များကို အသုံးပြုကြသည်။ +ဒီ module က အလွယ်တကူ အသုံးပြုနိုင်ရန် in-memory storage ကိုအသုံးပြုသည်။ Application ကို ပြန်စတင်သည်နှင့်တစ်ပြေးညီ၊ upload လုပ်ထားသော စာရွက်စာတမ်းများ သွားဆုံးပါသည်။ ထုတ်လုပ်မှုစနစ်များမှာ Qdrant သို့မဟုတ် Azure AI Search ကဲ့သို့ အမြဲတမ်း vector database များ အသုံးပြုကြသည်။ -### Context Window စီမံခြင်း +### Context Window Management -မော်ဒယ်တစ်ခုအတိုင်း context window အများဆုံးရှိသည်။ စာရွက် ကြီးများမှ ချ်န့်အားလုံးကို ရှုမနိုင်ပါ။ စနစ်သည် ဖြစ်နိုင်စွမ်းအကာအရ ထိပ်တန်း N ချ်န့်များ (default 5) ကိုသာ ရယူပြီး တိကျမှုရှိသော အဖြေထုတ်ရန် လုံလောက်သော context ပေးနိုင်ရန် ထိန်းသိမ်းသည်။ +Model တစ်ခုချင်းစီမှာ context window အများဆုံးပမာဏ ရှိသည်။ ကျယ်ပြန့်သော စာရွက်စာတမ်းမှ chunks အားလုံးမထည့်နိုင်ပါ။ စနစ်က သက်ဆိုင်ရာ chunks အများဆုံသာ (default ၅) ကို ရွေးပြီး မိမိအတွက် လိုအပ်သည့် context ကို အတိအကျပေးနိုင်စေရန် စီမံသည်။ -## RAG အရေးကြီးသော အခြေအနေများ +## RAG ကို ဘယ်ကို အသုံးပြုသင့်သလဲ -RAG သည် နေရာတိုင်းတွင် သင့်တော်သောနည်းလမ်းမဟုတ်ပါ။ အောက်ပါ ဆုံးဖြတ်ချက်လမ်းညွန်သည် RAG သုံးစွဲသောအခါ နှင့် လွယ်ကူသော နည်းလမ်းများကို တိုက်ရိုက်ထည့်သွင်းခြင်း သို့မဟုတ် မော်ဒယ်၏ အတွင်းခံအသိပညာကို ကိုင်တွယ်ခြင်းတို့အကြား မည်သည့်အခါ RAG အရေးကြီးသည်ကို ဆုံးဖြတ်ရာတွင် ကူညီပေးသည်- +RAG ဟာ အမြဲတမ်း အကောင်းဆုံး နည်းလမ်းမဟုတ်ပါဘူး။ အောက်ပါဆုံးဖြတ်မှု လမ်းညွှန်က RAG က သင့်တော်ခြင်းသို့မဟုတ် ပိုရိုးရှင်းသောနည်းလမ်းများ(ပြောရင် prompt ထဲ content ထည့်ခြင်း များ သို့မဟုတ် မော်ဒယ်၏ထည့်သွင်းထားသော အသိပညာ အားသာချက်များအား အားထားခြင်း) မှန်ကန်မှုအတွက် ကူညီပြုလုပ်ပေးသည်။ When to Use RAG -*ဤပုံသည် RAG သုံးစွဲသင့်သည့်အခါ နှင့် လွယ်ကူသောနည်းလမ်းများဖြင့်လည်းကောင်း သင့်လျော်သည့်အခါဆိုင်ရာ ဆုံးဖြတ်ချက်လမ်းညွန်ဖြစ်သည်။* +*ဒီပုံက RAG သုံးသင့်သောအချိန်နှင့် ရိုးရှင်းသောနည်းလမ်း အသုံးပြုသင့်သောအချိန်ကို ဖော်ပြထားသည်။* -## အဆင့်ဆက်လှမ်းခြင်းများ +## နောက်တစ်ဆင့်များ -**အောက်တန်း Module:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**နောက် Module:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**လမ်းညွန်:** [← ယခင် - Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [မူလစာမျက်နှာသို့ ပြန်သွားရန်](../README.md) | [နောက်တန်း - Module 04 - Tools →](../04-tools/README.md) +**အကွက်ရှေ့သို့ရှေ့ပြေးလှည့်ခြင်း:** [← ယခင်: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [နောက်သို့ပြန်သွားရန်](../README.md) | [ရှေ့တိုးရန်: Module 04 - Tools →](../04-tools/README.md) --- -**အငြင်းပွားချက်** -ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) အသုံးပြု၍ ဘာသာပြန်ထားခြင်းဖြစ်ပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှန်ကန်မှုအတွက် ကြိုးစားတတ်ပါသည် သော်လည်း အလိုအလျောက်ဘာသာပြန်ချက်များတွင် အမှားများ သို့မဟုတ် မှားယွင်းမှုများ ပါဝင်နိုင်ကြောင်း မျှော်လင့်ထားပါ။ မူရင်းစာရွက်စာတမ်းကို မူလဘာသာဖြင့် အာဏာပိုင် ရင်းမြစ်အနေဖြင့် တွင်မြင်စဉ်းစားသင့်ပါသည်။ အရေးကြီးသည့် သတင်းအချက်အလက်များအတွက် ဖြစ်ပါက လုပ်ငန်းအတွေ့အကြုံရှိ လူသား ဘာသာပြန်သူများ၏ ဘာသာပြန်ချက်ကို အကြံပြုပါသည်။ ဤဘာသာပြန်မှု အသုံးပြုမှုကြောင့် ဖြစ်ပေါ်နိုင်သည့် မသဘောတူမှုများ သို့မဟုတ် မှားယွင်းသောဖော်ပြချက်များအတွက် ကျွန်ုပ်တို့ တာဝန်မရှိပါ။ +**ပြောကြားချက်** +ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှန်ကန်မှုအတွက် ကြိုးပမ်းနေသော်လည်း၊ စက်ကိရိယာဘာသာပြန်ခြင်းများတွင် အမှားများ သို့မဟုတ် မှားယွင်းချက်များ ပါဝင်နိုင်ကြောင်း သတိပြုပါရန် လိုအပ်ပါသည်။ မူလစာတမ်းကို မူရင်းဘာသာဖြင့်သာ ယုံကြည်စိတ်ချရသော အချက်အလက်အဖြစ် သတ်မှတ်သင့်သည်။ အရေးကြီးသည့် သတင်းအချက်အလက်များအတွက် ပရော်ဖက်ရှင်နယ် လူသားဘာသာပြန်သူဝန်ဆောင်မှုကို အကြံပြုပါသည်။ ဤဘာသာပြန်ချက်ကို အသုံးပြုခြင်းမှ ဖြစ်ပေါ်လာသော နားလည်မှုကွာခြားမှုများ သို့မဟုတ် မမှန်ကန်သော အသုံးပြုမှုများအတွက် ကျွန်ုပ်တို့ တာဝန်မခံပါ။ \ No newline at end of file diff --git a/translations/my/04-tools/README.md b/translations/my/04-tools/README.md index a7f6ef3b8..150345f09 100644 --- a/translations/my/04-tools/README.md +++ b/translations/my/04-tools/README.md @@ -2,75 +2,75 @@ ## Table of Contents -- [Video Walkthrough](../../../04-tools) -- [What You'll Learn](../../../04-tools) -- [Prerequisites](../../../04-tools) -- [Understanding AI Agents with Tools](../../../04-tools) -- [How Tool Calling Works](../../../04-tools) - - [Tool Definitions](../../../04-tools) - - [Decision Making](../../../04-tools) - - [Execution](../../../04-tools) - - [Response Generation](../../../04-tools) - - [Architecture: Spring Boot Auto-Wiring](../../../04-tools) -- [Tool Chaining](../../../04-tools) -- [Run the Application](../../../04-tools) -- [Using the Application](../../../04-tools) - - [Try Simple Tool Usage](../../../04-tools) - - [Test Tool Chaining](../../../04-tools) - - [See Conversation Flow](../../../04-tools) - - [Experiment with Different Requests](../../../04-tools) -- [Key Concepts](../../../04-tools) - - [ReAct Pattern (Reasoning and Acting)](../../../04-tools) - - [Tool Descriptions Matter](../../../04-tools) - - [Session Management](../../../04-tools) - - [Error Handling](../../../04-tools) -- [Available Tools](../../../04-tools) -- [When to Use Tool-Based Agents](../../../04-tools) -- [Tools vs RAG](../../../04-tools) -- [Next Steps](../../../04-tools) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding AI Agents with Tools](#understanding-ai-agents-with-tools) +- [How Tool Calling Works](#how-tool-calling-works) + - [Tool Definitions](#tool-definitions) + - [Decision Making](#decision-making) + - [Execution](#execution) + - [Response Generation](#response-generation) + - [Architecture: Spring Boot Auto-Wiring](#architecture-spring-boot-auto-wiring) +- [Tool Chaining](#tool-chaining) +- [Run the Application](#run-the-application) +- [Using the Application](#အက်ပလီကေးရှင်း-အသုံးပြုခြင်း) + - [Try Simple Tool Usage](#ပထမဆုံး-ကိရိယာ-အသုံးပြုကြည့်ရန်) + - [Test Tool Chaining](#ကိရိယာ-ချဲ့ထွင်ခြင်း-စမ်းသပ်ရန်) + - [See Conversation Flow](#စကားပြော-ရှေ့ပြေးကို-ကြည့်ရန်) + - [Experiment with Different Requests](#မတူညီသော-တောင်းဆိုချက်များကို-စမ်းသပ်ရန်) +- [Key Concepts](#အဓိကအယူအဆများ) + - [ReAct Pattern (Reasoning and Acting)](#react-ပုံစံ-စဉ်းစားခြင်းနှင့်-လုပ်ဆောင်ခြင်း) + - [Tool Descriptions Matter](#ကိရိယာဖော်ပြချက်များ-အရေးကြီးသည်) + - [Session Management](#ဆက်သွယ်မှုစီမံခန့်ခွဲမှု) + - [Error Handling](#အမှားကိုင်တွယ်ခြင်း) +- [Available Tools](#အသုံးပြုနိုင်သော-ကိရိယာများ) +- [When to Use Tool-Based Agents](#ဘယ်အချိန်မှာ-tool-based-agents-ကို-အသုံးပြုမလဲ) +- [Tools vs RAG](#tools-နှင့်-rag-ကြား-ကွာခြားချက်) +- [Next Steps](#နောက်တစ်ဆင့်များ) ## Video Walkthrough -ဒီ module ကိုဘယ်လိုစတင်ဖွင့်မယ်ဆိုတာ ရှင်းပြထားတဲ့ လိုင်း live video ကို ကြည့်ပါ။ +ဒီ module နဲ့ စတင်ရောက်ရှိဖို့ဘယ်လိုလုပ်ရမယ်ဆိုတာ ရှင်းပြထားတဲ့ live အစီအစဉ်ကို ကြည့်ရှုနိုင်ပါသည်။ AI Agents with Tools and MCP - Live Session ## What You'll Learn -အခုတစ်ချိန်ထိ AI နဲ့ စကားပြောနည်း၊ prompt တွေကို သေချာဖန်တီးနည်း၊ နှင့် မေးချက်တွေကို သင့်စာရွက်နဲ့ချိတ်ဆက်ပြီးဖြေကြားပေးနည်းတွေကို သင်ယူခဲ့ပြီဖြစ်ပါတယ်။ ဒါပေမဲ့ အခြေခံကန့်သတ်ချက်တစ်ခု ရှိတယ်၊ ဘာလဲဆိုတော့ ဘာသာစကားမော်ဒယ်တွေက စာသားပဲ ထုတ်လွှင့်နိုင်တယ်။ ရာသီဥတု စစ်ဆေးခြင်း၊ တွက်ချက်ခြင်း၊ ဒေတာဘေ့စ်ကို ရှာဖွေရန်၊ အပြင်စနစ်တွေနဲ့ အလုပ်လုပ်ခြင်း တွေကို မလုပ်နိုင်ပါဘူး။ +ယနေ့အထိ သင်တို့သည် AI နဲ့ စကားပြောဆိုနည်း၊ prompt များကို ထိထိရောက်ရောက် အစီအစဉ်တကျ ဖွဲ့စည်းနည်း၊ နှင့် မိမိစာရွက်စာတမ်းများအခြေခံ၍ တုံ့ပြန်ချက်များကို ချထားနည်းတို့ကို သင်ယူပြီးသားဖြစ်သည်။ သို့သော် အခြေခံကန့်သတ်ချက်တစ်ခုရှိသည်မှာ - language model များသည် စာသားသာဖန်တီးနိုင်ပြီး ရာသီဥတုစစ်ဆေးခြင်း၊ တွက်ချက်မှုများပြုလုပ်ခြင်း၊ ဒေတာဘေ့စ်များကို စစ်မယ်၊ အပြင်မှစနစ်များနှင့် လုပ်ဆောင်ခြင်း မပြုနိုင်ပါ။ -Tools တွေက အဲဒီကို ပြောင်းလဲပေးတယ်။ မော်ဒယ်ကို function တွေကို ခေါ်နိုင်ဖို့ လက်လှမ်းပေးခြင်းဖြင့်၊ စာသားထုတ်လုပ်သူကနေ နောက်ထပ် လုပ်ဆောင်မှုယူနိုင်တဲ့ agent အဖြစ် ပြောင်းလဲသွားတယ်။ မော်ဒယ်က တိတိကျကျ ဘယ် tool လိုအပ်မယ်၊ ဘယ် tool ကိုသုံးမယ်၊ parameter များကို ဘယ်လိုပေးမယ်ဆိုတာ ဆုံးဖြတ်တယ်။ သင့်ကုဒ်က function ကို ဖုန်းခေါ်ပြီး ရလာဒ်ကို ပြန်ပေးတယ်။ မော်ဒယ်က အဲဒီရလဒ်ကို မေးခွန်းဖြေဆိုချက်ထဲ ထည့်သွင်းပေးတယ်။ +Tools များက ဒီအတားအဆီးကို ပြောင်းလဲပေးသည်။ model ကို function များခေါ်သုံးနိုင်ရန်ခွင့်ပြုခြင်းဖြင့် text ဖန်တီးသူမှ ဝါရင့် agent ဖြစ်လာစေသည်။ model သည် tool လိုအပ်သည့်အချိန်၊ ဘယ် tool ကိုသုံးရမည်၊ ဘယ် parameter များ ပေးပို့ရမည်ဆိုတာ ဆုံးဖြတ်သည်။ သင်၏ ကုတ်တွင် function ကို အကောင်အထည်ဖော်ပြီး ရလဒ်ကို ပြန်ပေးသည်။ model သည် ထိုရလဒ်ကို သူ၏ တုံ့ပြန်ချက်တွင် ထည့်သွင်းစီစဉ်ပေးသည်။ ## Prerequisites -- [Module 01 - Introduction](../01-introduction/README.md) ကိုပြီးစီးထားပြီးဖြစ်ရပါမယ် (Azure OpenAI resource တွေ deploy လုပ်ထားပြီး) -- လက်တလော အခြေခံ modules များကို အကြံပြုထားပြီးဖြစ်ရမယ် (ဒီ module က [Module 03 RAG concepts](../03-rag/README.md) ကို Tools vs RAG ကို နှိုင်းယှဉ်ရာမှာ အသုံးပြုထားပါတယ်) -- `.env` ဖိုင်ကို root directory မှာ Azure credentials နဲ့ရှိပြီးဖြစ်ရမယ် (Module 01 မှာ `azd up` နဲ့ ဖန်တီးထားတာ) +- [Module 01 - Introduction](../01-introduction/README.md) ကိုပြီးစွာ ဖြေရှင်းထားဖို့ (Azure OpenAI resource များ deploy ပြီးသားဖြစ်ရန်) +- ယခင် module များကို အကြံပြုအတိုင်း ပြီးစီးထားရန် (ဒီ module မှာ Tools vs RAG နှိုင်းယှဉ်မှုအတွက် [Module 03](../03-rag/README.md) ရဲ့ RAG အတွေးအခေါ်များကို ရည်ညွှန်းထားသည်) +- ရှေ့စာမျက်နှာမြောက် `.env` ဖိုင်တွင် Azure သုံး ဝင်ခွင့် အချက်အလက်များပါရှိရန် (Module 01 တွင် `azd up` ဖြင့် ဖန်တီးထားသည်) -> **Note:** Module 01 ကို မပြီးဆိုရင် အရင်ဆုံး deployment လုပ်ရန် ညွှန်ကြားချက်များကို လိုက်နာပါ။ +> **Note:** Module 01 မပြီးသေးပါက အဲဒီမှာပထမဦးဆုံး deployment လမ်းညွှန်ချက်များကို လိုက်နာပါ။ ## Understanding AI Agents with Tools -> **📝 Note:** ဒီ module မှာ "agents" ဆိုသည့် ဝေါဟာရသည် tool-calling နည်းပညာဖြင့်တိုးမြှင့်ထားသော AI အကူအညီပေးများကို ဆိုလိုသည်။ ဒါဟာ [Module 05: MCP](../05-mcp/README.md) မှာ အသုံးပြုမယ့် **Agentic AI** တွင်ပါဝင်သည့် (အစီအစဉ်ရေးဆွဲခြင်း၊ မှတ်ဉာဏ်၊ နှင့် မျိုးစုံ reasoning နည်းစနစ်) autonomous agents ကွဲပြားခြားနားနေတာ ဖြစ်ပါတယ်။ +> **📝 Note:** ဒီ module မှာ "agents" ဆိုသောစကားလုံးသည် tool calling စွမ်းရည်မြှင့်တင်ထားသော AI အကူအညီသူများကို ဆိုလိုဖြစ်သည်။ ၎င်းသည် [Module 05: MCP](../05-mcp/README.md) မှ ကျွန်ုပ်တို့ အကောင်အထည်ဖော်မည့် **Agentic AI** ပုံစံများ (အစီအစဉ်ရေးဆွဲခြင်း၊ မှတ်ဉာဏ်နှင့် အဆင့်မြင့် စဉ်းစားမှုပါဝင်သော autonomous agent များ) ထက် ကွဲပြားသည်။ -Tools မပါသည့်အခါ၊ ဘာသာစကားမော်ဒယ်က သူ့ training data မှာမလိုက်လျောညီထွေ စာသားပဲ ထုတ်လုပ်နိုင်မှာ ဖြစ်တယ်။ ယနေ့ရက် ရာသီဥတု တွေလေးကို မေးရင် ခန့်မှန်းပဲ ပြောနိုင်ပါတယ်။ Tools တွေ ပေးလိုက်ရင်တော့ ရာသီ API ကို ခေါ်လိုက်နိုင်တယ်၊ တွက်ချက်လုပ်နိုင်တယ်၊ ဒေတာဘေ့စ်ကိုအရောင်းအဝယ် ဆောင်ရွက်နိုင်တယ်၊ ထိုရမှန်သော အချက်အလတ်များကို ဖြေကြားချက်ထဲ ထည့်ပေးနိုင်ပါတယ်။ +tools မရှိပါက language model သည် ၎င်း၏_training_ဒေတာအပေါ်မှ စာသား များကို တုန့်ပြန်ပေးနိုင်သည်။ ရာသီဥတုပြောပါက မှန်မှန်ကန်ကန် မပြောနိုင်ဘဲ ခန့်မှန်းရမည်။ tools များပေးပါက weather API ခေါ်နိုင်၊ တွက်ချက်ချက်နိုင်၊ ဒေတာဘေ့စ်ကိုရှာဖွေစစ်ဆေးနိုင်တော့သည်၊ ထိုစစ်မှန်သော ရလဒ်များကို ၎င်း၏ တုံ့ပြန်ချက်ထဲတွင် ပေါင်းထည့်တင်ပြနိုင်သည်။ Without Tools vs With Tools -*Tools မပါလျှင် မော်ဒယ်က ခန့်မှန်းချက်ပဲ ပေးနိုင်ပါတယ် — Tools များဖြင့် API များ ခေါ်နိုင်ပြီး တွက်ချက်ပြီး အချိန်နှင့်တပြေးညီ ဒေတာပေးနိုင်ပါတယ်။* +*tools မပါက model သည် ခန့်မှန်းမှသာ ပြုလုပ်ရ; tools မပါမဖြစ် API များခေါ်အသုံးပြု၍ တွက်ချက်၍ အချိန်နှင့်တပြေးညီ ဒေတာ ပြန်လည်ပေးနိုင်သည်။* -AI agent ရှိတယ်ဆိုရင် ReAct pattern (Reasoning and Acting) ကို လိုက်နာတယ်။ မော်ဒယ်က တုံ့ပြန်ခြင်းပြင် မဟုတ်ဘဲ ကောင်းသော ဖော်ပြချက်အတွက် လိုအပ်သည့် အချက်အလက်ကို စဉ်းစားပြီး tool ကို ခေါ်ဆိုခြင်း၊ ရလဒ်ကို သတိထား စစ္ဆေးခြင်း၊ ပြန်လုပ်ဆောင်ခြင်း သို့မဟုတ် နောက်ဆုံးဖြေကြားချက် မပေးမီ ဆုံးဖြတ်ခြင်းတို့ကို လုပ်ဆောင်တယ်။ +AI agent with tools သည် **Reasoning and Acting (ReAct)** ပုံစံကို လိုက်နာသည်။ model သည် တုံ့ပြန်ခြင်းသာ မလုပ်ပဲ — မည်သည့်အရာလိုအပ်သည်ကို စဉ်းစားခြင်း၊ tool တစ်ခုခေါ်ခြင်း၊ ရလဒ်ကို သတိထားကြည့်ခြင်းနှင့် ထပ်မံ လုပ်ဆောင်မည် မလားသို့မဟုတ် နောက်ဆုံးဖြေချက် ပေးမည်ကို ဆုံးဖြတ်သည်။ -1. **Reason** — အသုံးပြုသူမေးခွန်းကို စူးစမ်းပြီး လိုအပ်တဲ့ အချက်အလက်နဲ့ ဆိုက်ထားတယ် -2. **Act** — တိကျတဲ့ tool ကို ရွေးချယ်ပြီး parameter တွေ ကို စနစ်တကျ ထုတ်လုပ်ကာ ခေါ်ဆိုတယ် -3. **Observe** — tool က ပြန်လာတဲ့ output ကို ရယူပြီး သုံးသပ်တယ် -4. **Repeat or Respond** — ဒေတာပိုမိုလိုအပ်နေဆဲဆိုရင် ချိတ်ဆက်ပြန်လုပ်; မဟုတ်ရင် သဘာဝဘာသာစကားဖြင့် ပြန်ဖြေတယ် +1. **Reason** — အသုံးပြုသူမေးခွန်းကို ဖြေရှင်း၍ မည်သည့်သတင်းအချက်အလက် လိုအပ်သည်ကို သတ်မှတ်ခြင်း +2. **Act** — မှန်ကန်သော tool ကို ရွေးချယ်ပြီး parameter များထုတ်ဖော်၍ ခေါ်ဆိုခြင်း +3. **Observe** — tool အထွက်ရလဒ်ကို လက်ခံ၍ အကဲဖြတ်ခြင်း +4. **Repeat or Respond** — သတင်းအချက်အလက် ထပ်မံလိုအပ်ပါက ထပ်ခေါ်လုပ်ဆောင်ခြင်းမဟုတ်လျှင် သဘာဝဘာသာဖြင့် ဖြေကြားခြင်း ReAct Pattern -*ReAct စနစ်အတိုင်း — အေးဂျင့်သည် အလုပ်လုပ်ရန် ထိုက်တန်မှုကို ဆုံးဖြတ်၊ tool ကို ခေါ်ဆိုပြီး ရလဒ်ကတော့ စစ်ဆေးသည်။ ပြီးရင် ထပ်လုပ်မလုပ် ဆုံးဖြတ်ပြီး အဆုံးဖြင့် သဘာဝဘာသာဖြင့် ဖြေဆိုသည်။* +*ReAct လည်ပတ်မှု — agent သည် စဉ်းစား၍ tool ခေါ်ကာ ရလဒ်ကို သတိထားကြည့်ပြီး နောက်ဆုံးဖြေချက်ပေးသည်အထိ ဆက်လက်လုပ်ဆောင်သည်။* -ဒီလုပ္ငန္းစဥ္ဟာ အလိုအေလ်ာက္ျဖစ္ၿပီး သင္က tool မ်ားနဲ႔ ၎တို႔၏ ဖေါ်ပြချက်ေတြကို သတ်မှတ်ပေးရုံပါပဲ။ မော်ဒယ်က ဘယ် tool ကို ဘယ်အချိန် သုံးမယ် ဆိုတာကို ကိုယ်တိုင် အာရုံစိုက်မှု ယူပါတယ်။ +ဒီလုပ်ငန်းစဥ်သည် အလိုအလျောက်ဖြစ်ပွားပါသည်။ သင်သည် tools များနှင့် ၎င်းတို့ ဖော်ပြချက်များကို သတ်မှတ်ပေးသည်။ model မှ tool များကို ဘယ်အချိန်၊ မည်သို့သုံးရမည်ကို ဆုံးဖြတ်ဖြစ်စေသည်။ ## How Tool Calling Works @@ -78,7 +78,7 @@ AI agent ရှိတယ်ဆိုရင် ReAct pattern (Reasoning and Actin [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -သင်၏ function များကို ဖော်ပြချက်ပုံစံနဲ့ parameter သတ်မှတ်ချက်ဖြင့် ကောင်းကောင်း မျှတစွာ ဖန်တီးရပါမယ်။ မော်ဒယ်က ဒီဖေါ်ပြချက်တွေကို system prompt မှာ မြင်ရပြီး ဘယ် tool က ဘာလုပ်တယ်ဆိုတာ နားလည်တယ်။ +သင်သည် ဖန်တီးလိုသော function များကို ရှင်းလင်းတဲ့ ဖော်ပြချက်များနှင့် parameter ကို သတ်မှတ်ပေးပါသည်။ model သည် သင့် system prompt တွင် ဖော်ပြချက်များကို ကြည့်ပြီး ကင်းစင် tool တစ်ခုချင်းဆီ၏ ကိုယ်ရည်ကိုယ်သွေးကို နားလည်နိင်သည်။ ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // သင့်ရာသီဥတု ရှာဖွေရေး အတွေးအခေါ် + // သင့်၏ရာသီဥတုပြန်ကြားချက်လောဂျစ် return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,154 +96,153 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// အကူအညီပေးသည်ကို Spring Boot မှ အလိုအလျောက် ချိတ်ဆက်ပေးသည် - +// အကူအညီပေးသူကို Spring Boot မှ အလိုအလျောက်ချိတ်ဆက်ပေးသည်။ // - ChatModel bean -// - @Component တို့မှ @Tool နည်းလမ်းများအားလုံး +// - @Component ကလပ်များမှ @Tool နည်းလမ်းများအားလုံး // - အစည်းအဝေး စီမံခန့်ခွဲမှုအတွက် ChatMemoryProvider ``` -အောက်ကပုံက annotation တစ်ခုချင်းစီ၏ အဓိပ္ပါယ် ပုံဖော်ထားပြီး AI ကို ဘယ်အချိန် tool ခေါ်မလဲ၊ ဘယ် parameter များ ထည့်ပေးမလဲ ဆိုတာ နားလည်စေဖို့ ဘယ်လို အကူအညီဖြစ်ပေးတယ်ဆိုတာ ပြထားပါတယ်။ +အောက်ဖော်ပြပါ ပုံသည် annotation တစ်ခုချင်းစီ၏ ရည်ရွယ်ချက်များကို ဖော်ပြပြီး AI အတွက် tool ခေါ်သုံးရမည့် အချိန်နှင့် ပေးပို့ရန် argument များကို နားလည်စေရန်ဘာကြောင့်အရေးကြီးကြောင်းရှင်းပြသည်။ Anatomy of Tool Definitions -*Tool အဓိပ္ပါယ်ပုံဖော်ခြင်း — @Tool က AI ကို ဘယ်အချိန်သုံးမလဲ ပြောပြ၊ @P က parameter တစ်ခုချင်းဖေါ်ပြပြီး၊ @AiService က စနစ်အလုပ်စတင်တဲ့အခါ ဆက်စပ်ပေးတယ်။* +*tool definition ရဲ့ anatomy — @Tool သည် AI ကို ဘယ်အချိန်သုံးရမည် ဆိုတာပြောပြ၊ @P သည် parameter တစ်ခုချင်း ရှင်းပြ၊ @AiService သည် စတင်ချိန်တွင် အားလုံးကို ဆက်သွယ်ပေးသည်။* -> **🤖 GitHub Copilot Chat နဲ့ လေ့လာကြည့်ပါ။** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ဖိုင်ကို ဖွင့်ပြီး မေးမြန်းပါ - -> - "OpenWeatherMap ကဲ့သို့ရော မော်ဒယ်မှာ မိတျ data မဟုတ်ဘဲ တကယ့် ရာသီ API ကို ဘယ်လို ပေါင်းစပ်မလဲ။" -> - "AI အကောင်းဆုံးသုံးစွဲဖို့ ကောင်းမွန်တဲ့ tool ဖေါ်ပြချက်ရဲ့ အရေးအကြောင်းပါလား?" -> - "API error များနှင့် rate limit များကို tool ျပုလုပ်ရာတွင် ဘယ်လို ကိုင်တွယ်ရမလဲ?" +> **🤖 GitHub Copilot Chat ဖြင့် စမ်းကြည့်ပါ:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ကိုဖွင့်ပြီး ဤမေးခွန်းများမေးပါ။ +> - "mock data အစား အမှန်တကယ် weather API ဖြစ်တဲ့ OpenWeatherMap ကိုဘယ်လိုပေါင်းစည်းမလဲ?" +> - "AI များ tool ကိုမှန်ကန်စွာသုံးရန် နောက်ကွယ်က နားလည်မှုရရှိစေရန် ကောင်းမွန်သော tool ဖော်ပြချက် များက ဘာများပါသင့်သလဲ?" +> - "tool implementation များတွင် API error သို့ rate limit များကို ဘယ်လိုကောင်းစွာ ချုပ်ချယ်မလဲ?" ### Decision Making -အသုံးပြုသူက "Seattle ရာသီဥတုဘာလဲ?" မေးတဲ့အခါ မော်ဒယ်က မတွန်းတင်ပစ်လို့ မဟုတ်ဘဲ သုံးစွဲသူရဲ့ ရည်ရွယ်ချက်နဲ့ သူ့စနစ်ထဲရှိ တစ်ချက်ချင်း tool ဖော်ပြချက်များကို နှိုင်းယှဉ်၊ သင့်တော်မှုအဆင့်သတ်မှတ်ပြီး အကောင်းဆုံးကို ရွေးချယ်တယ်။ ပြီးရင် function call ကို บาคาร่า parameter ကို `"Seattle"` လို့ သတ်မှတ်ပြီး ဖန်တီးပြသတယ်။ +အသုံးပြုသူက "Seattle ရဲ့ ရာသီဥတု ဘာလဲ?" ဟု မေးလာခဲ့ပါက model သည် ယိုယွင်းစွာ tool တစ်ခုရွေးမထားဘဲ user ရဲ့ ရည်ရွယ်ချက်အား နောက်ဆုံး tool သာမက အားလုံး tool ဖော်ပြချက်များနှင့် နှိုင်းယှဉ်ပြီး အနီးကပ်ဆုံး ကိုယ်စားပြု tool ကို ရွေးချယ်သည်။ ထိုနောက် `location` ကို `"Seattle"` ဟူ၍ သတ်မှတ်ပြီး စနစ်တကျ function call ဖန်တီးသည်။ -အသုံးပြုသူ မေးချက်နဲ့ ကိုက်တာ tool မရှိရင် မော်ဒယ်ဟာ သူ့ရဲ့ ဆောင်ရွက်ရမယ့် အချက်အလက်လွှမ်းခြုံ မူရင်းအရ ပြန်ဖြေဆိုတယ်။ တင့်ကား tool အများကြီးကိုက်ရင်တော့ အတိအကျဆုံးကို သတ်မှတ်တယ်။ +အသုံးပြုသူ အမိန့်နှင့် ကိုက်ညီသော tool မရှိပါက model သည် ကျွန်ုပ်၏အသိပညာထဲမှ တုံ့ပြန် မှာဖြေသည်။ ဟုတ်သော tools များအများအပြားရှိပါက နောက်ထပ် သီးသန့် tool ကို ရွေးချယ်သည်။ How the AI Decides Which Tool to Use -*မော်ဒယ်က အသုံးပြုသူ ရည်ရွယ်ချက်ကို နားလည်သဘောပေါက်ကာ ကျွန်မတွေ ပေးထားတဲ့ tool တစ်ခုချင်းစီနှင့် နှိုင်းယှဉ်ပြီး အကောင်းဆုံးကို ရွေးချယ်တယ်။ ဒါကြောင့် စာသား ဖေါ်ပြချက် တိကျ မှန်ကန်ဖို့ အရေးကြီးတယ်။* +*model သည် အသုံးပြုသူ ရည်ရွယ်ချက်အား အားလုံး tool များနှိုင်းယှဉ် ရှေးရှုပြီး အကောင်းဆုံးကို ရွေးချယ်သည် — ဒီမှာ ရှင်းလင်းပြီး အထူးသဖြင့် ဖော်ပြချက်ရေးသားခြင်းဇယားများ အရေးကြီးသည်။* ### Execution [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot က declarative `@AiService` interface ကို register လုပ်ထားတဲ့ tool များနဲ့ အလိုအလျောက် ချိတ်ဆက်လိုက်တယ်။ LangChain4j က tool ခေါ်ဆိုမှုတွေကို အလိုအလျောက် ဆောင်ရွက်တယ်။ နောက်ကြောင်းမှာ အသုံးပြုသူ မေးခွန်းကနေ စပြီး tool ကို ရွေးချယ်ခြင်း၊ ကုဒ်ပြန်လည်ရေးဆွဲခြင်း မှ tool ဖိတ်ခေါ်မှု အဆင့်ခြောက်ခုဖြတ်ပြီး ပြန်ဖြေသောက်မှုသို့ ရောက်ရှိတယ်။ +Spring Boot သည် `@AiService` interface အသုံးပြု၍ register လုပ်ထားသည့် tools များကို auto-wire ပြီး LangChain4j သည် tool call များကို အလိုအလျောက် ကျင်းပပေးသည်။ နောက်ခံ၌ tool call တစ်ခုလုံးကို အဆင့်ခြားခြား ခွဲ၍ user ၏ သဘာဝဘာသာမေးခွန်းမှ သဘာဝဘာသာ အဖြေထုတ်သဘောသို့ တစ်လျှောက်လွှားစဥ်ဖြစ်သည်။ Tool Calling Flow -* အသုံးပြုသူမေးရင် မော်ဒယ်က tool ရွေးချယ်၊ LangChain4j က tool ကို တည်ဆောက်ပြီး ပြန်လာသောရလဒ်ကို မော်ဒယ်က ဖြေကြားချက်ထဲ ထည့်ပေးတာ မျက်နှာဖုံးအားလုံးနှင့်အတူ ဦးတည်ချက်* +*စာလုံးတပ်စဥ်၊ user မေးခွန်းဖြေ၊ model သတ်မှတ် tool, LangChain4j က tool တက်ဖို့ အကောင်အထည်ဖော်, model သည် ရလဒ်ကို သဘာဝဘာသာဖြင့် ပြန်လည်ပေးသည်။* -[Module 00 - Quick Start](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ကို ပြေးချိန်မှာ ဒီတူသာပုံစံကို တွေ့မယ် — Calculator tool များကို အဲဒီလို တူတူ ခေါ်လိုက်တယ်။ အောက်မှာ ဆက်ခံ ပုံပြင်နဲ့ tool ခေါ်သုံးမှုကို သရုပ်ဖော်ထားသည်။ +နောက်ခံတွင် `AiServices` သည် tool calling loop ကို အားလုံး tool များ အတွက် လုပ်ဆောင်သည် — ဤမှာ အလွယ်ကူဆုံး `Calculator` ဖြင့် ဖော်ပြထားသည်။ အောက်ပါ sequence diagram သည် နောက်ကွယ်တွင် ဖြစ်တတ်သည်များကို တိတိကျကျ ပြသသည်။ Tool Calling Sequence Diagram -*Quick Start demo က tool ခေါ်မှု တစ်ကြိမ်ကျရင် loop ပတ်တာ — `AiServices` က message နဲ့ tool schema များကို LLM သို့ ပို့ပြီး LLM က `add(42, 58)`လို function call ပြန်တယ်၊ LangChain4j က Calculator method ကို locally ထုတ်ဆောင်ကာ ပြန်လည် ဖြေကြားတယ်။* +*tool calling loop — `AiServices` သည် သင့် message နှင့် tool schema များကို LLM သို့ ပို့သည်၊ LLM သည် `add(42, 58)` ကဲ့သို့ function call ဖြင့် ပြန်ကြား၊ LangChain4j က `Calculator` method ကို ဒေသတွင်းမှာ အကောင်အထည်ဖော်ပြီး ရလဒ်ကို နောက်ဆုံး ဖြေ ပြန်ရန် ထည့်ပေးသည်။* -> **🤖 GitHub Copilot Chat နဲ့ လေ့လာကြည့်ပါ။** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ဖိုင်ကို ဖွင့်ပြီး မေးမြန်းပါ - -> - "ReAct pattern ဘယ်လို အလုပ်လုပ်ပြီး AI agents အတွက် ဘာကြောင့် ထိရောက်လဲ?" -> - "Agent က ဘယ် tool ကို ဘယ်လို နှုန်းအတိုင်း သုံးမလဲ ဆုံးဖြတ်မလဲ?" -> - "Tool execution ပျက်ကွက်ခဲ့ရင် ဘာဖြစ်မလဲ - error တွေကို ဘယ်လို ပြန်ကြားရမလဲ?" +> **🤖 GitHub Copilot Chat ဖြင့် စမ်းကြည့်ပါ:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ဖိုင်ကိုဖွင့်ကာ မေးပါ။ +> - "ReAct pattern ဟာ ဘယ်လိုအလုပ်လုပ်ပြီး AI agents များအတွက် ဘာကြောင့် ထိရောက်သနည်း?" +> - "Agent သည် tool ကို မည်သို့ နှင့် ဘယ်အဆင့်များတွင် သုံးရမည်ကို ဘယ်လိုဆုံးဖြတ်သနည်း?" +> - "tool execution ဖျက်ယွင်းသွားပါက ဘာဖြစ်မလဲ - error များကို ခိုင်ခံ့စွာ မည်သို့ ကိုင်တွယ်မလဲ?" ### Response Generation -မော်ဒယ်က ရာသီဥတုဒေတာကို လက်ခံပြီး အသုံးပြုသူအတွက် သဘာဝဘာသာစကားဖြင့် ဖြေကြားချက် တစ်ခု ဖန်တီးတယ်။ +model သည် weather data ကို လက်ခံကာ သဘာဝဘာသာဖြင့် အသုံးပြုသူအား ပြန်တုံ့ပြန်သည်။ ### Architecture: Spring Boot Auto-Wiring -ဒီ module မှာ LangChain4j ရဲ့ Spring Boot ပေါင်းစည်းမှုကို အသုံးပြုပြီး declarative `@AiService` interface တွေနဲ့ စနစ်တကျဆက်စပ်တယ်။ စတင်တဲ့အခါမှာ Spring Boot က `@Tool` methods ပါဝင်တဲ့ `@Component` တွေ၊ သင့်ရဲ့ `ChatModel` bean နဲ့ `ChatMemoryProvider` ကို ရှာဖွေထားပြီး အားလုံးကို `Assistant` interface တစ်ခုထဲ ချိတ်ဆက်ပေးတယ်၊ manual boilerplate အလုံးစုံကင်းစင်စေပါတယ်။ +ဒီ module မှာ LangChain4j ၏ Spring Boot integration ကို declarative `@AiService` interface များဖြင့် အသုံးပြုသည်။ စတင်လုပ်ဆောင်ချိန်တွင် Spring Boot သည် `@Tool` method များပါဝင်သော `@Component` အားလုံး၊ သင့် `ChatModel` bean နှင့် `ChatMemoryProvider` ကို ရှာဖွေပြီး လူနှစ်ဆယ့်ဖို့အတွက် `Assistant` interface အဖြစ် တိုက်ရိုက် သွယ်ဆက်ပေးသည်။ Spring Boot Auto-Wiring Architecture -*@AiService interface က ChatModel၊ tool components နဲ့ memory provider တွေကို ဆက်သွယ်ပြီး Spring Boot က အလိုအလျောက် wiring တာဝန်ယူပေးတယ်။* +*`@AiService` interface သည် ChatModel၊ tool component များနှင့် memory provider များကို တစ်နှင့်တည်း ဆက်သွယ်ပေးပြီး Spring Boot နည်းလမ်းအားလုံးကို အလိုအလျောက် ကိုင်တွယ်ပေးသည်။* -HTTP request ကနေ controller၊ service၊ auto-wired proxy ကနေ tool execution အပြီး မပြန်တတ်ချိုင့် အားလုံးရဲ့ request life cycle ကို sequence diagram သရုပ်ဖော်ထားပါတယ်။ +Request lifecycle အပြည့်အစုံကို sequence diagram အဖြစ် ဖော်ပြထားသည် — HTTP request မှ controller, service, auto-wired proxy စတင်, tool execution ပြီး ပြန်ရာအထိ။ Spring Boot Tool Calling Sequence -*Complete Spring Boot request life cycle — HTTP request ကနေ controller ဟာ service က auto-wired Assistant proxy ကိုဖြတ်ပြီး LLM နဲ့ tool calls ကို အလိုအလျောက် စီမံထိန်းချုပ်ပေးတယ်။* +*Spring Boot request lifecycle ပြည့်စုံသော လမ်းကြောင်း — HTTP request သည် controller နှင့် service ကို ဖြတ်ကူး၍ auto-wired Assistant proxy ထိ ရောက်ပြီး LLM နှင့် tool ခေါ်မှုများကို အလိုအလျောက် စီမံပေးသည်။* -ဒီဟာရဲ့ အားသာချက်အချို့ - +ဒီနည်းလမ်း၏ အဓိကအားသာချက်များ - -- **Spring Boot auto-wiring** — ChatModel နဲ့ tool များကို အလိုအလျောက် ထည့်သွင်းပေးတယ် -- **@MemoryId pattern** — session အခြေခံ memory ကို အလိုအလျောက် စီမံပေးတယ် -- **Single instance** — Assistant ကို တစ်ကြိမ်ဖန်တီးပြီး ပြန်လည်သုံးစွဲခြင်းဖြင့် ပေးဆောင်မှု မြန်ဆန်စေတယ် -- **Type-safe execution** — Java method များကို တိုက်ရိုက် call ပြုလုပ်ကာ type conversion ဖြင့် အမှားကင်းစေတယ် -- **Multi-turn orchestration** — tool chaining ကို အသုံးပြုမှု အလိုအလျောက်စီမံတယ် -- **Zero boilerplate** — manual `AiServices.builder()` ယူဆောင်မှု၊ memory HashMap ကင်းစင်တယ် +- **Spring Boot auto-wiring** — ChatModel နှင့် tool များကို အလိုအလျောက် ထည့်သွင်းခြင်း +- **@MemoryId pattern** — အလိုအလျောက် session အခြေခံ memory စီမံခန့်ခွဲမှု +- **Single instance** — Assistant ကို တစ်ချက်ဖန်တီးပြီး ဂရုတစိုက် အသုံးပြုခြင်း +- **Type-safe execution** — Java method များကို အမျိုးအစားမှန်ကန်စွာ တိုက်ရိုက်ခေါ်နိုင်ခြင်း +- **Multi-turn orchestration** — tool chaining ကို အလိုအလျောက် ကိုင်တွယ်ခြင်း +- **Zero boilerplate** — ကိုယ့်လက်ဖြင့် `AiServices.builder()` သို့မဟုတ် memory HashMap ကို မရေးသားရ -Manual `AiServices.builder()` အသုံးပြုမှုကတော့ပိုကုဒ်တွေ လိုအပ်ပြီး Spring Boot ပေါင်းစည်းမှုကအကျိုးအမြတ်တွေ မရနိုင်ပါ။ +အခြားနည်းလမ်းများမှာ (manual `AiServices.builder()`) ကုတ်ပိုများပြီး Spring Boot integration ၏ အားသာချက်များကို လျော့နည်းစေသည်။ ## Tool Chaining -**Tool Chaining** — Tool-based agents တွေဘယ်တော့ အချစ်ဆုံး ပါဝင်တာလဲ ဆိုတော့ single question တစ်ခု လည်း multiple tools လိုအပ်တဲ့အခါပါ။ "Seattle ရာသီဥတု Fahrenheit ဘယ်လောက်လဲ?" ဆိုလိုက်ရင် agent က tools နှစ်ခုလိုက်ပြီး ခေါ်တယ် — ပထမဆုံးမှာ `getCurrentWeather` ကို Celsius အပူချိန်ယူဖို့ခေါ်၊ ပြီးရင် အဲဒီ result ကို `celsiusToFahrenheit` ကို ပြောင်းရေးဖို့ ပေးတယ် — တစ်ချက် ပြောဆိုမှုတစ်ခုထဲမှာပဲ ဖြစ်တယ်။ +**Tool Chaining** — မေးခွန်းတစ်ခုအတွက် tool များစွာ လိုအပ်ပါက tool-based agents ၏ တကယ့်အားသာချက် ဖော်ပြသည်။ "Seattle ရဲ့ ရာသီဥတုကို ဖာရင်ဟိုက် (Fahrenheit) ဖြင့် ဖော်ပြပါ။" ဟု မေးပါက agent သည် နှစ်ခု tool ကို ဆက်တိုက် ခေါ်ရမည်ဖြစ်ပြီး - ပထမဆုံး `getCurrentWeather` ကို ကယ်လ်ဆီးယပ်ဖြင့် အအေးချိန်ယူကာ ထိုအချက်ကို `celsiusToFahrenheit` သို့ လွှဲပြောင်းကာ နောက်ဆုံးမှာ တစ်ဆက်တည်း အဖြေ တင်ပြပေးသည်။ Tool Chaining Example -*Tool chaining အသုံးပြုမှု — getCurrentWeather ကို ခေါ်ပြီး Celsius result ကို celsiusToFahrenheit သို့ ပေးပို့၊ နှစ်ခုရဲ့ ဖြေချက် ပေါင်းစပ်ဖေါ်ပြသည်။* +*Tool chaining လက်တွေ့ - agent သည် getCurrentWeather အရင်ခေါ်ပြီးနောက် ကယ်လ်ဆီးယပ် အရေအတွက်ကို celsiusToFahrenheit ဆီပို့၍ ပြောင်းလဲကာ အဖြေ ပေးသည်။* -**Graceful Failures** — mock data မပါတဲ့မြို့တစ်မြို့ ရာသီကို မေးလိုက်ရင် tool က error message ပြန်ပေးတယ်၊ AI ကလည်း မဖြစ်နိုင်ပါဘူး လို့ ရိုးရှင်းပြောတယ်၊ အရေပြားကျဆင်းခြင်းမရှိပါဘူး။ Tool မအောင်မြင်တဲ့အခါ agent က ထိန်းသိမ်းခြင်း လုပ်တယ်။ အောက်ဖော်ပြထားသလို error ကိုင်တွယ်မှုရှိသလို၊ ကျန်မရှိဘဲ crash ဖြစ်နေတာ မဟုတ်ဘူး။ +**Graceful Failures** — mock data တွင်မပါသော မြို့တစ်မြို့၏ ရာသီဥတုကို မေးပါက tool သည် error message ပြန်ပေးပြီး AI သည် နားလည်ချက်ပြုပြီး ကူညီ၍မရကြောင်းရှင်းပြသည်။ tools များသည် ဘေးကင်းသေချာစွာ မအောင်မြင်မှု များကို ကိုင်တွယ်ပေးသည်။ အောက်ပုံသည် error handling မပါသောနည်းနှင့် error handling ပြည့်စုံသော နည်းကို နှိုင်းယှဉ်ပြထားသည်။ ကောင်းမွန်သော error handling ပါပါက agent သည် exception ကို ဖမ်းပြီး အကူအညီဖြေကြားပေးသော်လည်း မပါက app တစ်ခုလုံး ကျရှုံးခြင်း ဖြစ်ပေါ်ကြသည်။ Error Handling Flow -*Tool မှားယွင်းရင် agent က error ကို ဖမ်းပြီး အကူအညီလိုအပ်လို့ ဖြစ်တယ်လို့ ရှင်းပြပြီး crash မဖြစ်စေပါ။* +*tool များ failure ဖြစ်လျှင် agent သည် error ကို ဖမ်း ၿပီး ကူညီ၀န္ေဆာင္မႈ ေပးျပီး app crash မျဖစ္ေစပါ။* -ဒီအရာတွေ တစ်ခါတည်း စကားပြောနေစဉ် ပြုလုပ်တယ်။ Agent က tools အများအပြားကို ကိုယ်တိုင်စီမံခိုင်းပေးတယ်။ +ဒီလုပ်ငန်းစဉ်မှာ တစ်ကြိမ်သာတုံ့ပြန်ရန် လုပ်ဆောင်သည်။ agent သည် tool calls များစွာကို အလိုအလျောက် စီမံပေးသည်။ ## Run the Application -**Deployment စစ်ဆေးခြင်း:** +**Deployment အတည်ပြုရန်:** -Module 01 မှာ `.env` ဖိုင် Azure credentials တွေအပါအဝင် ကို root directory မှာ ဖန်တီးပြီးသား ဖြစ်မှသာ အတည်ပြုပါ။ ဒီ module folder ကနေ (`04-tools/`) ဒီ command တွေကို လည်ပတ်ပါ။ +Module 01 တွင် `.env` ဖိုင် တည်ရှိပြီး Azure credential များပါရှိသည်ကို သေချာစေပါ။ Module directory (`04-tools/`) မှ run ပါ။ **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကိုပြသသင့်သည်။ +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကို ဖေါ်ပြသင့်သည် ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကို ပြရန် လိုသည်။ +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ကိုပြသသင့်သည်။ ``` -**Application စတင်ခြင်း:** +**Application စတင်ရန်:** -> **Note:** မီတာ root directory မှာ `./start-all.sh` ပေးပြီး applications အားလုံးကို စတင်ပြီးသားဆိုရင် Module 04 က http://localhost:8084 မှာ စတင်ပြင်ဆင်ပီးဖြစ်ပါတယ်။ အောက်မှာ စတင် commands မလိုတော့ပါ၊ တိုက်ရိုက် အဲဒီလိပ်စာသို့ သွားလို့ရပါတယ်။ +> **မှတ်ချက်:** root directory မှ `./start-all.sh` ဖြင့် အားလုံး app များ စတင်ပြီးသားဆိုပါက ဒီ module သည် ပေါ့(Port) 8084 တွင် ရပ်တည်နေပါသည်။ အောက်ပါ စတင် command များဖြတ်သိပါက http://localhost:8084 သို့ တိုက်ရိုက် ဝင်ရောက်နိုင်သည်။ -**Option 1: Spring Boot Dashboard အသုံးပြုခြင်း (VS Code အသုံးပြုသူများအတွက် အကြံပြုချက်)** +**ရွေးချယ်စရာ ၁: Spring Boot Dashboard အသုံးပြုခြင်း (VS Code အသုံးပြုသူများအတွက် အကြံပြုချက်)** -Dev container ထဲမှာ Spring Boot Dashboard extension ပါပြီး၊ တစ်နေရာတည်းက Spring Boot application တွေကို ကြည့်ရှု စီမံနို်င်ပါတယ်။ VS Code ရဲ့ ဘယ်ဘက် Activity Bar မှာ (Spring Boot အစီအစဉ် icon) ရှာနိုင်ပါတယ်။ +Development container မှာ Spring Boot Dashboard extension ပါပြီး Spring Boot application များအားလုံးကို ရှာဖွေ စီမံနိုင်သော အမြင် interface ကို ပေးဆောင်ပေးသည်။ VS Code ၏ ဘယ်ဘက် Activity Bar တွင် Spring Boot အိုင်ကွန်ကို ရှာနိုင်သည်။ -Spring Boot Dashboard က - +Spring Boot Dashboard မှ တဆင့် +- workspace တွင် ရရှိနိုင်သော Spring Boot app များအားလုံး ကြည့်ရှုနိုင်သည်။ +- Single click ဖြင့် app များ စတင်/ရပ်ဆိုင်းနိုင်သည်။ +- application log များကို တိုက်ရိုက် ကြည့်ရှုနိုင်သည်။ +- application အခြေအနေ စောင့်ကြည့်နိုင်သည်။ -- Workspace ထဲရှိ Spring Boot application အားလုံးကို ပြောပြပေးတယ် -- တစ်နှိပ်နဲ့ application အားလုံးကို စတင်/ရပ်တန့် စေတယ် -- Application log များကို real-time ထွက်ပေါ်မှုကြည့်ရှုနိုင် -- Application အခြေအနေသေပွဲကို စောင့်ကြည့်နို်င်စေတယ် -တစ်ခါတည်း ဒီမော်ဂျူးအား စတင်ရန် "tools" အနားရှိ play ခလုတ်ကို နှိပ်လိုက်ပါ၊ 又သိုတစ်ခါတည်း အားလုံးအတွက် မော်ဂျူးများအား စတင်နိုင်သည်။ - -VS Code တွင် Spring Boot Dashboard ယခုကဲ့သို့ ပေါ်ပေါက်ပါသည် - +"tools" module ကို စတင်ရန် play button ကို နှိပ်ပြီး စတင်နိုင်သလို module အားလုံးကို 一ခါတည်းစတင်လည်း ရသည်။ +VS Code တွင် Spring Boot Dashboard ပြသပုံ - Spring Boot Dashboard -*VS Code တွင် Spring Boot Dashboard — မော်ဂျူးအားလုံးကို တစ်နေရာကနေ စတင်၊ တားမြစ် နှင့် စောင့်ကြည့်နိုင်ပါသည်* +*VS Code မှာ Spring Boot Dashboard — အားလုံးသော module များကို တစ်နေရာက စတင်၊ ရပ်နား၊ နှင့် စောင့်ကြည့်နိုင်သည်* -**နည်းလမ်း ၂: shell scripts အသုံးပြုမှု** +**နည်းလမ်း ၂: Shell script များ အသုံးပြုခြင်း** -ဝက်ဘ်အပလီကေးရှင်းများအားလုံး စတင်ပါ (module 01-04): +ဝဘ်အက်ပလီကေးရှင်းများအားလုံးကို စတင်ပါ (modules 01-04): **Bash:** ```bash -cd .. # ရူ့တ် ဒါရက်ထရီမှ +cd .. # အကြောင်းအရာ မူလ ဒါရိုက်တာရီမှ ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # အမြစ် ဖိုလ်ဒါမှ +cd .. # မူလအညွှန်းတိုက်မှ .\start-all.ps1 ``` -သို့မဟုတ် ဒီမော်ဂျူးပဲ စတင်ရန်: +ဒါမှမဟုတ် ဒီတစ်ခုတည်း module ကို စတင်ပါ: **Bash:** ```bash @@ -257,132 +256,132 @@ cd 04-tools .\start.ps1 ``` -နှစ်ခုစလုံးစစ်ဆေးသည့် shell script များသည် အေရာင်းလုပ်မြင်သူ .env ဖိုင်မှ ပတ်ဝန်းကျင်တွင်ရှိသည့်ပြောင်းလဲမှုများကို အလိုအလျောက်โหลดပြီး JAR မရှိပါက တည်ဆောက်ပေးပါမည်။ +နှစ်ခုလုံး script များသည် root `.env` ဖိုင်မှ environment variable များကို အလိုအလျောက် load လုပ်ပြီး JAR မတွေ့ရင် တည်ဆောက်ပါလိမ့်မယ်။ -> **မှတ်ချက်:** မည်သည့်အချိန်တွင် မော်ဂျူးအားလုံးကို စခဲ့ရန် မျှော်လင့်လျှင်: +> **မှတ်ချက်:** စတင်ခါနီးမှာ module များအားလုံးကို ကိုယ်တိုင်တည်ဆောက်ချင်ရင်: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -http://localhost:8084 ကို မိုဘိုင်း browser တွင် ဖွင့်ပါ။ +http://localhost:8084 ကို ဘရောက်ဇာမှာဖွင့်လိုက်ပါ။ -**ရပ်စဲရန်:** +**ရပ်ရန်:** **Bash:** ```bash -./stop.sh # ဤမော်ဒျူးသာ +./stop.sh # ဤမော်ဂျူးလ်ထဲမှသာ # သို့မဟုတ် -cd .. && ./stop-all.sh # မော်ဒျူးအားလုံး +cd .. && ./stop-all.sh # မော်ဂျူးလ်အားလုံး ``` **PowerShell:** ```powershell -.\stop.ps1 # ဤမော်ဂျူးလ်သာ -# သို့မဟုတ် -cd ..; .\stop-all.ps1 # မော်ဂျူးလ်အားလုံး +.\stop.ps1 # ဒီမော်ဂျူးသာ +# မဟုတ်ရင် +cd ..; .\stop-all.ps1 # မော်ဂျူးအားလုံး ``` -## အပလီကေးရှင်းအသုံးပြုခြင်း +## အက်ပလီကေးရှင်း အသုံးပြုခြင်း -အပလီကေးရှင်းတွင် AI agent အား အသုံးပြု၍ ရေရှည်ရာသီအခြေအနေများနှင့် အပူချိန်ပြောင်းလဲခြင်း ကိရိယာများသုံးနိုင်သော ဝက်ဘ်အင်တာဖေ့စ်ပါဝင်ပါတယ်။ အင်တာဖေ့စ်မှာ လျင်မြန်စတင်အသုံးပြုနိုင်သော ဥပမာများနှင့် ဂျုံပြန်ပေးပို့ရန် ချက်ပြား ပါဝင်ပါတယ် - +အက်ပလီကေးရှင်းမှာ AI အေဂျင့်နှင့် တွုံ့ဆုံနိုင်သော ဝဘ်အင်တာဖေ့စ် ရှိပြီး ရာသီဥတုနှင့် အပူချိန်ပြောင်းလဲသည့် ကိရိယာများကို အသုံးပြုနိုင်သည်။ အောက်တွင် အင်တာဖေ့စ်ပုံစံပြထားပြီး၊ မြန်ဆန်စတင်အသုံးပြုရန် ဥပမာများနှင့် စကားပြော panel ပါဝင်သည်။ AI Agent Tools Interface -*AI Agent Tools အင်တာဖေ့စ် - စတင်လျင်မြန်သောဥပမာများ နှင့် ကိရိယာများနှင့် ဆက်သွယ်ရန် ချက်ပြား* +*AI Agent Tools အင်တာဖေ့စ် - မြန်ဆန်စတင် ဥပမာများနှင့် ကိရိယာများနှင့် ဆက်သွယ်ဖို့ စကားပြောအင်တာဖေ့စ်* -### ရိုးရိုးလေး ကိရိယာအသုံးပြုမှု စမ်းသပ်ကြည့်ပါ +### ပထမဆုံး ကိရိယာ အသုံးပြုကြည့်ရန် -ရိုးရိုးလေးတောင်းဆိုမှုဖြင့် စတင်ပါ - "100 ဒီဂရီ Fahrenheit ကို Celsius သို့ ပြောင်းပါ" AI agent သည် အပူချိန်ပြောင်းလဲခြင်းအတွက် ကိရိယာတောင်းခံရန် လိုအပ်ကြောင်း သတိပြု၍ အထောက်အထားများနှင့် အတူ အသုံးပြု၍ ရလဒ်ပြန်လာသည်။ ရိုးရိုးစွာ ဘာ့လဲဆိုရင် သင်မှန်းဖြစ်သော ကိရိယာကို ဘယ်လိုသွားခေါ်မလဲဆိုတာကို မလုပ်ပေးပဲ သဘာဝကျစွာ ခံစားရပါလိမ့်မယ်။ +ရိုးရိုးရှင်းရှင်း တောင်းဆိုချက်နဲ့ စတင်ပါ — "100 ဒီဂရီ Fahrenheit ကို Celsius သို့ ပြောင်းပါ"။ agent သည် အပူချိန်ပြောင်းလဲကိရိယာ လိုအပ်ကြောင်း တွေ့ရှိပြီး ကျရောက်ချက်နဲ့တူလို့ ထိုကိရိယာကို ခေါ်ယူကာ ရလဒ်ပြန်ပေးပါမည်။ သဘာဝဘာသာစကားနဲ့ မည်သည့်ကိရိယာကို အသုံးပြုမည်ဆိုတာ မသတ်မှတ်ဘဲ မည်သို့ ခေါ်ယူမှုပြုမည်ကို သုံးသပ်နိုင်ခြင်းကို တွေ့ရပါမည်။ -### ကိရိယာချိတ်ဆက်မှု စမ်းသပ်ကြည့်ပါ +### ကိရိယာ ချဲ့ထွင်ခြင်း စမ်းသပ်ရန် -အခုတော့ ပိုရှုပ်ထွေးအောင် စမ်းပါ -"Seattle ရဲ့ ရာသီဥတု ဘာလိုရာ နဲ့ Fahrenheit သို့ ပြောင်းပါ" AI agent သည် အဆင့်ဆင့် လုပ်ဆောင်နှင့် ရာသီဥတုရဲ့ Celsius အချက်အလက်ကိုရရှိပြီး Fahrenheit သို့ ပြောင်းရန်လိုအပ်ကြောင်း သတိပြု၊ ပြောင်းလဲခြင်းကိရိယာကိုခေါ်ယူပြီး နှစ်ခု ဒေတာကိုပေါင်းစပ်ထားသော တုံ့ပြန်မှုတစ်ခုအဖြစ် ထုတ်ပေးသည်။ +ပိုခက်ခဲသော တောင်းဆိုချက် — "Seattle ရဲ့ ရာသီဥတု ဘာလဲ၊ ဒီအပူချိန်ကို Fahrenheit အဖြစ် ပြောင်းပါ" ကို စမ်းကြည့်ပါ။ agent သည် အဆင့်ဆင့်လုပ်ဆောင်ရာတွင် ပထမဆုံး ရာသီဥတုကို ရယူသော (Celsius နှင့် ပြန်ပေး)၊ ပြီးမှ Fahrenheit သို့ ပြောင်းရန် ကိုသိပြီး ပြောင်းလဲသည့် ကိရိယာ ကို ခေါ်ယူကာ နှစ်ခု၏ ရလဒ်ကို ပေါင်းပြီး တစ်ခုတည်းဖြင့် ဖြေရှင်းပါသည်။ -### စကားပြောဆက်ဆံမှု လည်ပတ်ပုံ ကြည့်ရှုပါ +### စကားပြော ရှေ့ပြေးကို ကြည့်ရန် -ချက်ပြားအင်တာဖေ့စ်သည် စကားပြောမှတ်တမ်းကို ထိန်းသိမ်းထားပြီး မကြာခဏပြန်လည်ဆက်ဆံမှုများလုပ်နိုင်စေပါသည်။ ယခင်မေးခွန်းများနှင့် တုံ့ပြန်ချက်များအားလုံး ပြသထားပြီး သက်ဆိုင်ရာ အကြောင်းအရာကို လေ့လာသိရှိနားလည်ရန် လွယ်ကူစေပါသည်။ +စကားပြော အင်တာဖေ့စ်သည် စကားပြော သမိုင်းကို သိမ်းဆည်းထားကာ မကြာခဏ ပြန်ကြားမှုများ ပြုလုပ်နိုင်သည်။ များစွာသော စကားပြောများအတွက် ကိစ္စအချက်အလက်များကို တွေ့မြင်နိုင်ပြီး AI အေဂျင့်သည် ဘယ်လို context ဖွဲ့တည်သည်ဆိုတာ လွယ်ကူစေပါသည်။ Conversation with Multiple Tool Calls -*အဆင့်မြင့်စကားပြောဆက်ဆံမှု - ရိုးရှင်းသော ပြောင်းလဲမှုများ၊ ရာသီဥတုသိရှိမှုများနှင့် ကိရိယာချိတ်ဆက်မှုများ* +*တစ်ခါတလေ ပြန်ကြားမှုများနှင့် ရိုးရှင်းဆုံးပြောင်းလဲမှုများ၊ ရာသီဥတု၊ ကိရိယာ ချိတ်ဆက်မှု တို့ ပါ၀င်သည့် စကားပြော* -### မကွက်မဆပ် မေးခွန်းများစမ်းသပ်ပါ +### မတူညီသော တောင်းဆိုချက်များကို စမ်းသပ်ရန် -အမျိုးမျိုးဖြင့် စမ်းသပ်ကြည့်ပါ - -- ရာသီဥတုစစ်ဆေးခြင်း: "Tokyo ရဲ့ ရာသီဥတု ဘာလဲ?" -- အပူချိန်ပြောင်းလဲခြင်း: "25°C သည် Kelvin ဘယ်လောက်လဲ?" -- ပေါင်းစပ်မေးခွန်းများ: "Paris ရဲ့ ရာသီဥတုကိုစစ်ပြီး 20°C ထက် အပူဆုံးလား ပြောပါ" +အမျိုးမျိုးသော ပေါင်းစပ်ချက်များ စမ်းကြည့်ပါ - +- ရာသီဥတု ရှာဖွေခြင်း: "Tokyo ရဲ့ ရာသီဥတု ဘာလဲ?" +- အပူချိန်ပြောင်းလဲခြင်း: "25°C က Kelvin ဘယ်လောက်လဲ?" +- ပေါင်းစပ်မေးခွန်းများ: "Paris ရဲ့ ရာသီဥတု စစ်ဆေးပြီး 20°C အထက်နေရင် ပြောပါ" -AI agent သည် သဘာဝဘာသာစကားကို ဖြေလျှော့၍ သင့်တော်သော ကိရိယာခေါ်ယူမှုများဖြင့် အတူတကွ လုပ်ဆောင်ပေးပါသည်။ +agent သည် သဘာဝဘာသာစကားကို ဖော်ထုတ်ပြီး သင့်တော်သော ကိရိယာ ခေါ်ဆိုမှုများနှင့် ကိုက်ညီမှု ရှိသည်ကို သတိပြုပါ။ -## အဓိက စကားဝိုင်းများ +## အဓိကအယူအဆများ -### ReAct အေကြာင်းအရင်း (စဉ်းစားခြင်း နှင့် လုပ်ဆောင်ခြင်း) +### ReAct ပုံစံ (စဉ်းစားခြင်းနှင့် လုပ်ဆောင်ခြင်း) -AI agent သည် ဆုံးဖြတ်ချက်ချခြင်း (ဘာကိုလုပ်မလဲ) နှင့် ကိရိယာအသုံးပြုခြင်းမှ လှမ်းတန်းပြန်လည်သွားလာပါသည်။ ဒီစနစ်ဖြင့် AI သည် ညွှန်ကြားချက်များကို ကျရောက်ခြင်းမဟုတ်ဘဲ ကိုယ်ပိုင်ဖြေရှင်းနိုင်မှု ရရှိပါသည်။ +agent သည် စဉ်းစား၍ ဆုံးဖြတ်ခြင်း (ဘာလုပ်မလဲ) နှင့် လုပ်ဆောင်ခြင်း (ကိရိယာများကို အသုံးပြုခြင်း) တို့အကြား အလွှဲပြောင်း လိုက်နာသည်။ ဤပုံစံသည် ညွှန်ကြားချက် များကိုသာ အဖြေမပေးဘဲ ကိုယ်ပိုင်ဖြေရှင်းနိုင်စွမ်း တိုးတက်စေသည်။ -### ကိရိယာဖော်ပြချက်များ အရေးကြီး +### ကိရိယာဖော်ပြချက်များ အရေးကြီးသည် -သင့်ကိရိယာ ဖော်ပြချက်များ၏ အရည်အသွေးသည် AI agent ၏ အသုံးပြုမှုကို တိုက်ရိုက် သက်သာစေသည်။ ပြတ်သားသပ်ရပ်အောင် ဖော်ပြချက်များမှာ သတ်မှတ်ထားသောအချိန်မှာ မည်သည့်ကိရိယာကို ဘယ်လိုခေါ်မလဲကို ပြတ်သားသေချာနားလည်စေသည်။ +ကိရိယာ ဖော်ပြချက်များ၏ အရည်အသွေးသည် agent ကျွမ်းကျင်စွာ အသုံးပြုနိုင်မှုကို သက်ရောက်စေသည်။ သေချာပြီး တိကျသော ဖော်ပြချက်များသည် မော်ဒယ်အား မည်သည့်အချိန် နှင့် မည်သို့ ကိရိယာကို ခေါ်ဆိုရမည်ကို နားလည်စေရန် ကူညီသည်။ -### အစည်းအဝေးစီမံခန့်ခွဲမှု +### ဆက်သွယ်မှုစီမံခန့်ခွဲမှု -`@MemoryId` @သတ်မှတ်ချက်သည် အလိုအလျောက် အစည်းအဝေးအလိုက် မှတ်ဉာဏ်စီမံခန့်ခွဲမှုကို အတည်ပြုသည်။ တစ်ခုစီ Session ID အလိုက် `ChatMemory` အကွန်ရက်များကို `ChatMemoryProvider` ဝန်ဆောင်မှုခွဲကတည်းက စီမံပေးပြီး အသုံးပြုသူများ မတူညီသော စကားပြောမှတ်တမ်း ဖြစ်ရန် အလိုအလျောက် သတ်မှတ်ထားသည်။ အောက်ပါ အစားထိုးပုံက အမျိုးမျိုးအသုံးပြုသူများကို သီးခြားမှတ်ဉာဏ်နေရာများသို့ ခွဲပေးနေသည်ကို ပြသသည်။ +`@MemoryId` အမည်ပေးချက်သည် ဆက်သွယ်မှုအလိုက် အလိုအလျောက် မှတ်ဉာဏ်စီမံမှုကို အထောက်အကူပြုသည်။ ဆက်သွယ်မှုများအလိုက် `ChatMemory` instance ကို `ChatMemoryProvider` bean မှ စီမံသည်၊ ဒါကြောင့် အသုံးပြုသူများစွာသည် တစ်ပြိုင်နက်တည်း agent နှင့် စကားပြောနေစဉ်တွေ့ဆုံမှုများ မရောနှောနိုင်ပါ။ အောက်တွင် အသုံးပြုသူများစွာမှ session ID အလိုက် မတူညီသော မှတ်ဉာဏ်ဆိုင်ရာ တည်နေရာများသို့ လမ်းညွှန်ခြင်းကို ဖော်ပြထားသည်။ Session Management with @MemoryId -*တစ်ဦးချင်းစီ Session ID သည် အထူးသီးသန့် စကားပြောမှတ်တမ်းများကို ပြန်လည်စီမံ — အသုံးပြုသူများသည် တစ်ဦးမှ တစ်ဦး၏ သတင်းစာ မမြင်ရပါ။* +*ဆက်သွယ်မှု ID တစ်ခုချင်းစီသည် မူကားသီးခြားသော စကားပြောသမိုင်းသို့ များစွာသော အသုံးပြုသူများ၏ စကားပြောများကို တစ်ဦးသီးသန့် မမြင်ရဟု သေချာစေသည်။* ### အမှားကိုင်တွယ်ခြင်း -ကိရိယာများ မအောင်မြင်နိုင်ခြင်း ရှိသည် — API မတုံ့ပြန်နိုင်ခြင်း၊ အချက်အလက်များမှားယွင်းခြင်း၊ ပြင်ပ ဝန်ဆောင်မှုများ ပျက်ကွက်ခြင်း စတာတွေ ဖြစ်နိုင်ပါသည်။ အမှည့်များကို လက်ခံနိုင်ခြင်းသည် ထုတ်လုပ်ရေး AI agent များအတွက် မရှိမဖြစ်လိုအပ်ပါသည်။ ကိရိယာတစ်ခုမှ exception ပစ်ချခဲ့ပါက LangChain4j သည် ထို error မက်ဆေ့ချ်ကို မော်ဒယ်ထံပြန်ပို့ပြီး သဘာဝဘာသာဖြင့် ပြဿနာကို ဖော်ပြပေးနိုင်သည်။ +ကိရိယာများသည် လုပ်ဆောင်ရာတွင် အမှားများ ပြန်လာနိုင်သည် — API များ timeout တတ်ခြင်း၊ parameter မမှန်ကန်ခြင်း၊ services ပြတ်တောက်ခြင်း စသည်ဖြင့်။ မွန်မြတ်သော agent များသည် အမှားကိစ္စများကို မှတ်ယူပြီး၊ ကိရိယာမှ သွားရောက် ကူညီပြုလုပ်ခြင်းကြောင့် အက်ပလီကေးရှင်းလုံးဝ ပျက်စီးခြင်း မဖြစ်စေရန် လုပ်ဆောင်ရမည်။ ကိရိယာမှ အမှားဖြစ်လျှင် LangChain4j မှ ယင်းအမှားစကားကို ကိုယ်စားပြု မော်ဒယ်ထံ ပြန်လည်ပေးပို့ကာ သဘာဝဘာသာနဲ့ အပြစ်တင်ပါသည်။ -## ရနိုင်သော ကိရိယာများ +## အသုံးပြုနိုင်သော ကိရိယာများ -အောက်ပါကိရိယာ များအား သုံး၍ ဖန်တီးနိုင်သော ရိုးရာ ပတ်ဝန်းကျင်တစ်ခုကို တူညီ ပုံစံကနေ ပြသထားသည်။ ဒီမော်ဂျူးတွင် ရာသီဥတုနှင့် အပူချိန်ကိရိယာများကို ဖေါ်ပြထားပေမယ့် `@Tool` ပုံစံသည် Java Method များအားလုံးသုံးနိုင်သည် - ဒေတာဘေ့စ်မေးခွန်းမှ စ၍ ငွေပေးချေမှုဆိုင်ရာ တာဝန်များထိ။ +အောက်တွင် သင်တည်ဆောက်နိုင်သော ကိရိယာအမျိုးအစား ကြီးမားသော ပုံမှန်ဖော်ပြချက်ရှိသည်။ ဒီ module တွင် ရာသီဥတုနှင့် အပူချိန်ကိရိယာများကို ပြသထားသော်လည်း `@Tool` ပုံစံကို Java method များအတွက် အသုံးပြုနိုင်သည် — ဒေတာဘေ့စ် မေးခွန်းများမှ စပြီး ငွေပေးချေမှုလုပ်ငန်းစဉ်များအထိ။ Tool Ecosystem -*Java method တစ်ခုချင်းစီကို @Tool ဖြင့် အမှတ်အသားပြု၍ AI အသုံးပြုနိုင် - ဒီပုံစံသည် ဒေတာဘေ့စ်များ၊ API များ၊ အီးမေးလ်၊ ဖိုင်လုပ်ဆောင်မှုများအထိ ထပ်မံသုံးနိုင်သည်။* +*Java method များအားလုံးကို `@Tool` သတ်မှတ်ချက်ဖြင့် AI အတွက် အသုံးပြုနိုင်သည် — ပုံစံသည် ဒေတာဘေ့စ်များ၊ API များ၊ အီးမေးလ်၊ ဖိုင်လုပ်ငန်းစဉ်များ နှင့် အခြားများအတွင်း ချဲ့ထွင်နိုင်သည်။* -## မည်သည့်အခါ ကိရိယာအခြေခံ AI agent များအသုံးပြုမလဲ +## ဘယ်အချိန်မှာ Tool-Based Agents ကို အသုံးပြုမလဲ -လွှဲမှားမှု မရှိစေမည့် အကြောင်းအရာများအတွက် မလိုအပ်ပါ။ ဆုံးဖြတ်ချက်မှာ AI သည် ပြင်ပစနစ်များနှင့် အပြန်အလှန်ဆက်သွယ်ရမည်လား သို့မဟုတ် ကိုယ်ပိုင်မင်္ဂလာမေးချင်းဖြင့် ဖြေကြားနိုင်မလားအပေါ် ဆုံးဖြတ်သည်။ အောက်ပါလမ်းညွှန်သည် ကိရိယာ အသုံးပြုသင့်သည့် အခါများနှင့် မလိုအပ်ဘဲဖြစ်သည့် အခါများကို လေ့လာစေပါသည်။ +တောင်းဆိုချက်အားလုံးအတွက် ကိရိယာများ မလိုအပ်ပါ။ ဆုံးဖြတ်ချက်မှာ AI သည် ပြင်ပစနစ်များနှင့် ဆက်သွယ်ရမည်လား၊ မဖြစ်နိုင်သော သူ၏ ဒေတာမှ ဖြေဆိုနိုင်မည်လား ဖြစ်သည်။ အောက်တွင် ကိရိယာများ အသုံးဝင်စေသော အချိန်နှင့် မလိုအပ်သော အချိန်ကို စုစည်းဖော်ပြထားသည်။ When to Use Tools -*စိတ်ရှည်စွမ်းဆောင်မှု လမ်းညွှန် — ကိရိယာများမှာ ကိုင်တွယ်သောအချိန်မှာ အချိန်နဲ့ တွက်ချက်ချက်ချက်နှင့် လုပ်ဆောင်မှု အတွက်သာ အရေးပါသည်။ စိတ်ကူးစိတ်သန်းနှင့် စာရင်းပေးမေးခွန်းများတွင် မလိုအပ်ပါ။* +*အမြန်ဆုံး ဆုံးဖြတ်ရန် လမ်းညွှန်ချက် — ကိရိယာများသည် အချိန်နဲ့တပြေးညီ ဒေတာ၊ တွက်ချက်မှုနှင့် လုပ်ငန်းများအတွက်ဖြစ်သည်။ ပုံမှန်အသိပညာ နှင့် ဖန်တီးမှုလုပ်ငန်းများအတွက် မလိုအပ်ပါ။* -## ကိရိယာများ နှင့် RAG +## Tools နှင့် RAG ကြား ကွာခြားချက် -Module 03 နှင့် 04 မှာ AI ၏ လုပ်နိုင်စွမ်းများကို တိုးမြှင့်ပေးရန် ခြားနားသည့် နည်းလမ်းချင်းဖြစ်ပါသည်။ RAG သည် မော်ဒယ်အား **နည်းပညာ** ကို ဖတ်ယူနိုင်စွမ်းပေးသည်။ ကိရိယာများသည် မော်ဒယ်အား **လှုပ်ရှားမှုများ** ခေါ်ယူနိုင်စွမ်း ပေးသည်။ အောက်ပါပုံသည် နှစ်ခုကို နှိုင်းယှဉ်ပြီး လုပ်ငန်းစဉ်နည်းလမ်းများနှင့် ကန့်သတ်ချက်များကို ဖော်ပြထားပါသည်။ +Modules 03 နှင့် 04 နှစ်ခုလုံးသည် AI ၏ စွမ်းဆောင်ရည်ကိုတိုးတက်စေသော် ဗဟိုကျပြီး မတူကွဲပြားသော နည်းလမ်းများဖြစ်သည်။ RAG သည် မော်ဒယ်အား **အသိပညာ** ရရှိစေခြင်းဖြင့် စာရွက်စာတမ်းများရှာဖွေသည်။ Tools သည် မော်ဒယ်အား **လုပ်ဆောင်မှုများ** ဆောင်ရွက်စေနိုင်ရန် function များခေါ်ယူသည်။ အောက်ပါပုံသည် ဤနည်းလမ်းနှစ်ခု၏ လုပ်ငန်းစဉ်နှင့် အားနည်းချက်များကို နှိုင်းယှဉ်ပြထားသည်။ Tools vs RAG Comparison -*RAG သည် တည်ငြိမ်သော စာရွက်စာတမ်းများထံမှ သတင်းအချက်အလက် ရယူပေးသည် - ကိရိယာများ သည် လှုပ်ရှားမှုများ အကောင်အထည်ဖော်ပြီး တိုက်ရိုက်ဒေတာကို ရယူပေးသည်။ ထုတ်လုပ်ရေးစနစ်များအများစု ကိုယ်ပိုင်အဆင့်နှစ်ခုလုံး ပေါင်းစပ်အသုံးပြုကြသည်။* +*RAG က စာရွက်အချက်အလက်များမှ ထောက်ခံချက် ရယူကာ Tools က လုပ်ဆောင်ချက်များလုပ်ကာ မြန်ဆန်ပြောင်းလဲမှု ရယူသည်။ စက်မှုလုပ်ငန်းများစွာမှာ နှစ်ခုကို ပေါင်းစပ်အသုံးပြုကြသည်။* -အလေ့အကျင့်အဖြစ် ထုတ်လုပ်ရေးစနစ်များမှာ RAG ကို စာရွက်စာတမ်းအတွက် အသုံးပြု၍ အဖြေများအာရုံစူးစိုက်ခြင်း၊ Tools များကို သက်ဆိုင်ရာ ဒေတာများရယူခြင်း သို့မဟုတ် လုပ်ဆောင်မှုများအတွက် ပေါင်းစပ်အသုံးပြုသည်။ +လက်တွေ့လုပ်ငန်းများတွင် RAG ကို သင်၏စာရွက်စာတမ်းများအတွက် အဖြေ မှီခိုရန် အသုံးပြုသည်။ Tools ကို နို်ငးတယ် ဒေတာ ရယူခြင်း သို့မဟုတ် လုပ်ငန်းများ ဆောင်ရွက်ရာတွင် အသုံးပြုသည်။ ## နောက်တစ်ဆင့်များ -**နောက်တစ်ခဏ: [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md)** +**နောက် Module:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**သွားရာလမ်းညွှန်:** [← ယခင်: Module 03 - RAG](../03-rag/README.md) | [ထိပ်သို့ ပြန်သွားရန်](../README.md) | [နောက်: Module 05 - MCP →](../05-mcp/README.md) +**လမ်းညွှန်:** [← ယခင်: Module 03 - RAG](../03-rag/README.md) | [ပင်မသို့ ပြန်သွားရန်](../README.md) | [နောက်: Module 05 - MCP →](../05-mcp/README.md) --- -**အကြောင်းကြားချက်** -ဒီစာရွက်စာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) ဖြင့် ဘာသာပြန်ထားခြင်းဖြစ်ပါသည်။ တိကျမှုအတွက် ကြိုးပမ်းဆောင်ရွက်သော်လည်း အလိုအလျောက်ဘာသာပြန်ခြင်းမှ အမှားများ သို့မဟုတ် ဖြစ်နိုင်သောမှားယွင်းချက်များ ပါရှိနိုင်ကြောင်း သတိပြုလိုပါသည်။ မူရင်းစာရွက်စာတမ်းကို လူမှုဘာသာဖြင့်သာ ဉပဒေရေးရာအတိုင်း အတည်ပြုရမည့်အရင်းအမြစ်အဖြစ် ယူဆရန် လိုအပ်ပါသည်။ အရေးကြီးသော သတင်းအချက်အလက်များအတွက် လူကြီးမင်းတရားဝင် လုပ်သက်ရှိ ဘာသာပြန်သူများ၏ ဘာသာပြန်ချက်ကို အသုံးပြုရန် အကြံပြုပါသည်။ ဤဘာသာပြန်ချက် အသုံးပြုမှုကြောင့် ဖြစ်ပေါ်နိုင်သည့် နားလည်မှုမှားယွင်းခြင်းများမှ ကျွန်ုပ်တို့ တာဝန်မယူပါ။ +**ပြောကြားချက်** +ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှန်ကန်မှုအတွက် ကြိုးပမ်းနေသော်လည်း၊ စက်ကိရိယာဘာသာပြန်ခြင်းများတွင် အမှားများ သို့မဟုတ် မှားယွင်းချက်များ ပါဝင်နိုင်ကြောင်း သတိပြုပါရန် လိုအပ်ပါသည်။ မူလစာတမ်းကို မူရင်းဘာသာဖြင့်သာ ယုံကြည်စိတ်ချရသော အချက်အလက်အဖြစ် သတ်မှတ်သင့်သည်။ အရေးကြီးသည့် သတင်းအချက်အလက်များအတွက် ပရော်ဖက်ရှင်နယ် လူသားဘာသာပြန်သူဝန်ဆောင်မှုကို အကြံပြုပါသည်။ ဤဘာသာပြန်ချက်ကို အသုံးပြုခြင်းမှ ဖြစ်ပေါ်လာသော နားလည်မှုကွာခြားမှုများ သို့မဟုတ် မမှန်ကန်သော အသုံးပြုမှုများအတွက် ကျွန်ုပ်တို့ တာဝန်မခံပါ။ \ No newline at end of file diff --git a/translations/my/README.md b/translations/my/README.md index 1056274e3..099955bd2 100644 --- a/translations/my/README.md +++ b/translations/my/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j အတွက် စတင်သူများ +# LangChain4j ကို စတင်လေ့လာသူများအတွက် -LangChain4j နှင့် Azure OpenAI GPT-5.2 ကို အသုံးပြု၍ အခြေခံစကားပြောမှ AI ကိုယ်စားလှယ်များအထိ AI application များဖန်တီးခြင်း သင်တန်း။ +LangChain4j နှင့် Azure OpenAI GPT-5.2 ကို အသုံးပြု၍ AI application များ ဖန်တီးခြင်း၏ သင်တန်း၊ မိန့်ခွန်းမူအဆင့်မှ AI အေးဂျင့်များထိ။ -### 🌐 ဘာသာစကား မျိုးစုံထောက်ပံ့မှု +### 🌐 ဘာသာစကားစုံ ပံ့ပိုးမှု -#### GitHub Action မှတဆင့် ထောက်ပံ့ (အလိုအလျောက် နှင့် အမြဲတမ်းအပ်ဒိတ်ဖြစ်နေသည်) +#### GitHub Action မှတစ်ဆင့် ပံ့ပိုးထားခြင်း (အလိုအလျောက်နှင့် အမြဲတမ်းလန်းဆန်းသည်) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](./README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **ဒေသိယ မိတ္တူကူးယူချင်ပါသလား?** +> **ဒေသတွင်းမိတ္တူယူလိုပါသလား?** > -> ဒီ repository က ဘာသာစကား ၅၀+ အတွက် ဘာသာပြန်နဲ့ အတူ ပါဝင်ထားပြီး ဒေါင်းလုဒ်အရွယ်အစားကို အလွန်မြင့်တက်စေပါတယ်။ ဘာသာပြန်ချက်များ မပါဘဲ မိတ္တူကူးရန် sparse checkout ကို အသုံးပြုပါ။ +> ဤ repository တွင် ဘာသာစကား ၅၀ ကျော် ရှိသော ဘာသာပြန်ပုံစံများပါဝင်သည်၊ ၎င်းသည် ဒေါင်းလုပ်အရွယ်အစားကိုမြှင့်တင်သည်။ ဘာသာပြန်များမပါဝင်ပဲ မိတ္တူယူရန် sparse checkout ကို သုံးပါ။ > > **Bash / macOS / Linux:** > ```bash @@ -29,62 +29,61 @@ LangChain4j နှင့် Azure OpenAI GPT-5.2 ကို အသုံးပြ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> ဒါက သင်တန်း ပြီးစီးရန် လိုအပ်သည့် အရာအားလုံးကို ပိုမိုလျင်မြန်စွာ ဒေါင်းလုဒ်ပေးပါလိမ့်မယ်။ +> ၎င်းက သင်တန်းပြီးမြောက်ရန် လိုအပ်သော အရာအားလုံးကို အလျင်အမြန် ဒေါင်းလုပ်လုပ်နိုင်စေရန် ဖြစ်ပါသည်။ -## အကြောင်းအရာဇယား +## အကြောင်းအရာ စာရင်း -1. [အရှိန်အဟုန်စတင်ခြင်း](00-quick-start/README.md) - LangChain4j အစပြုခြင်း -2. [နိဒါန်း](01-introduction/README.md) - LangChain4j အခြေခံများ သင်ယူရန် -3. [Prompt အင်ဂျင်နီယာနင်း](02-prompt-engineering/README.md) - ထိရောက်သော prompt ဒီဇိုင်းကျွမ်းကျင်ခြင်း -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - အဖွဲ့လိုက် ဗဟုသုတအခြေခံ စနစ်များ ဖန်တီးခြင်း -5. [ကိရိယာများ](04-tools/README.md) - ပြင်ပကိရိယာများနှင့် ရိုးရှင်းသော အကူအညီပေးများ ပေါင်းစပ်ခြင်း -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Model Context Protocol (MCP) နှင့် Agentic modules ကို အသုံးပြုခြင်း +1. [မိတ်ဆက်](01-introduction/README.md) - LangChain4j ၏ အခြေခံများ လေ့လာရန် +2. [Prompt အင်ဂျင်နီယာ링](02-prompt-engineering/README.md) - ထိရောက်သော prompt ဒီဇိုင်း သင်ယူရန် +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - သိပ္ပံပညာအခြေခံ စနစ်များ ဖန်တီးရန် +4. [ကိရိယာများ](04-tools/README.md) - ပြင်ပကိရိယာများနှင့် ရိုးရှင်းသော အကူအညီပေးများ ထည့်သွင်းရန် +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Model Context Protocol (MCP) နှင့် Agentic မော်ဂျူးများ ဖြင့် လုပ်ဆောင်ရန် -### ဗွီဒီယိုလမ်းညွှန်များ +### ဗီဒီယို လမ်းညွှန်များ -အပိုင်းတိုင်းတွင် live session တစ်ခုရှိပြီး အယူအဆများနှင့် ကုဒ်ကို တစ်ဆင့်ခြင်း လမ်းညွှန်ဖော်ပြဆွေးနွေးသည်။ +တိုင်းမော်ဂျူးလ်နှင့်အတူ အကြောင်းအရာများနှင့် ကုဒ်အဆင့်ဆင့်လမ်းညွှန်မှု Live session ပါရှိသည်။ -| အပိုင်း | ဗွီဒီယို | +| မော်ဂျူး | ဗီဒီယို | |--------|-------| -| 01 - နိဒါန်း | [LangChain4j ဖြင့် စတင်ခြင်း](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Prompt အင်ဂျင်နီယာနင်း | [LangChain4j ဖြင့် Prompt အင်ဂျင်နီယာနင်း](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [LangChain4j နှင့် RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - ကိရိယာများ & 05 - MCP | [ကိရိယာများနှင့် MCP ပါ AI ကိုယ်စားလှယ်များ](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 01 - မိတ်ဆက် | [LangChain4j ဖြင့် စတင်ခြင်း](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Prompt အင်ဂျင်နီယာ링 | [LangChain4j ဖြင့် Prompt အင်ဂျင်နီယာ링](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [LangChain4j ဖြင့် RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 04 - ကိရိယာများ & 05 - MCP | [ကိရိယာများနှင့် MCP နှင့် AI အေးဂျင့်များ](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## သင်ယူမှု လမ်းကြောင်း +## သင်ကြားရေး လမ်းကြောင်း -**LangChain4j အသစ်လား?** အဓိပ္ပါယ်နှင့် အယူအဆများအတွက် [အသုံးအနှုန်းစာရင်း](docs/GLOSSARY.md) ကို ကြည့်ပါ။ +**LangChain4j အသစ်ဖြစ်ပါသလား?** အဓိကသတ်မှတ်ချက်များနှင့် အကြောင်းအရာများကို [Glossary](docs/GLOSSARY.md) တွင် ကြည့်ရှုပါ။ -> **အရှိန်အဟုန် စတင်ခြင်း** +> **လျင်မြန်စတင်ရန်** -1. ဒီ repository ကို သင့် GitHub အကောင့်သို့ Fork ပြုလုပ်ပါ -2. **Code** → **Codespaces** tab → **...** → **New with options...** ကိုနှိပ်ပါ -3. မရပ်တန့်ပဲ ရွေးချယ်မှုများကို သုံးပါ – ဒီသင်တန်းအတွက် ဖန်တီးထားသော Development container ကို ရွေးယူပါလိမ့်မယ် -4. **Create codespace** ကိုနှိပ်ပါ -5. ပတ်ဝန်းကျင် ပြင်ဆင်ပြီးရန် ၅-၁၀ မိနစ် စောင့်ပါ -6. တိုက်ရိုက် [အရှိန်အဟုန် စတင်ခြင်း](./00-quick-start/README.md) သို့ ရောက်ရှိပါ! +1. ဤ repository ကို သင်၏ GitHub အကောင့်သို့ Fork လုပ်ပါ။ +2. **Code** → **Codespaces** tab → **...** → **New with options...** ကို Click နှိပ်ပါ။ +3. ကန့်သတ်မှုအတိုင်း အသုံးပြုပါ – ဤသင်တန်းအတွက် ဖန်တီးထားသော Development container ကို ရွေးချယ်မည်။ +4. **Create codespace** ကို နှိပ်ပါ။ +5. ပတ်ဝန်းကျင် ပြင်ဆင်ပြီး ဖေါ်ဆောင်ရန် ၅-၁၀ မိနစ် ခဏ ရွေ့ပါ။ +6. စတင်ရန် [မိတ်ဆက်](./01-introduction/README.md) သို့ တိုက်ရိုက်ဝင်ပါ။ -အပိုင်းများပြီးပါက [စမ်းသပ်မှုလမ်းညွှန်](docs/TESTING.md) ကို ရှာဖွေကြည့်ပါ၊ LangChain4j စမ်းသပ်ဖော်ပြချက်များကိုကြည့်ရှုနိုင်သည်။ +မော်ဂျူးများပြီးဆုံးပါက LangChain4j စမ်းသပ်ခြင်းဆိုင်ရာ အကြောင်းအရာများကို လေ့လာရန် [Testing Guide](docs/TESTING.md) ကို ကြည့်ရှုပါ။ -> **မွတ္ခ်က္။** ဒီသင်ခန်းစာမှာ GitHub Models နှင့် Azure OpenAI နှစ်မျိုးကို အသုံးပြုသည်။ [အရှိန်အဟုန် စတင်ခြင်း](00-quick-start/README.md) အပိုင်းမှာ GitHub Models ကိုသုံးပြီး (Azure subscription မလိုအပ်ပါ), ၁ မှ ၅ အပိုင်းများမှာ Azure OpenAI ကို သုံးသည်။ Azure အကောင့် မရှိသေးပါက [အခမဲ့ Azure အကောင့်](https://aka.ms/azure-free-account) ဖြင့် စတင်ပါ။ +> **မှတ်ချက်။** ဤလေ့လာမှုတွင် Azure OpenAI ကို အသုံးပြုသည်။ အကောင့် မရှိသေးပါက [အခမဲ့ Azure အကောင့်](https://aka.ms/azure-free-account) ဖြင့် စတင်ပါ။ -## GitHub Copilot နှင့် သင်ယူခြင်း +## GitHub Copilot ဖြင့် သင်ယူခြင်း -အမြန်ဆုံး ကုဒ်ရေးရန် ဤ project ကို GitHub Codespace သို့မဟုတ် သင့်ရဲ့ ဒေသတွင်း IDE တွင် devcontainer ဖြင့် ဖွင့်ပါ။ ဒီ သင်တန်းအတွက် အသုံးပြုထားသော devcontainer သည် AI တွဲဖက်ရေးသားရေးအတွက် GitHub Copilot နဲ့ ကြိုတင်ပြင်ဆင်ထားပါသည်။ +အမြန် အကောင်အထည်ဖော်ရန်အတွက်၊ GitHub Codespace သို့မဟုတ် သင့်ဒေသခံ IDE တွင် provided devcontainer ဖြင့် ဤ project ကို ဖွင့်ပါ။ ဤသင်တန်းတွင် အသုံးပြုသော devcontainer တွင် AI ပေါင်းစပ်ရေးသားမှုအတွက် GitHub Copilot ရရှိထားသည်။ -ကုဒ်မူလပုံစံ တစ်ခုချင်းစီတွင် GitHub Copilot ကို မေးနိုင်သော အကြံပြုမေးခွန်းများ ပါဝင်သည်။ 💡/🤖 ခြင်းများကို အောက်ပါနေရာများတွင် ကြည့်ရှုပါ- +အထူးကုသည့် မေးခွန်းများသည် GitHub Copilot ကို ကူညီစွာ မေးမြန်းနိုင်ပါသည်။ 💡/🤖 prompts များကို အောက်ပါနေရာများတွင် ရှာရန် - -- **Java ဖိုင်ခေါင်းစီးများ** - ပုံစံတိုင်းအတွက် မေးခွန်းများ -- **Module README များ** - ကုဒ်နမူနာပြီးနောက် စူးစမ်းမေးမြန်းမှုများ +- **Java ဖိုင်ခေါင်းစဉ်များ** - ကွဲပြားသော ဥပမာများအတွက် မေးခွန်းများ +- **မော်ဂျူး README များ** - ကုဒ်နောက်တွင် လေ့လာစူးစမ်းရန် ပြည့်စုံသော မေးခွန်းများ -**ဘယ်လိုအသုံးပြုမလဲ။** ဖိုင် ဖွင့်ပြီး Copilot ကို အကြံပြုမေးခွန်းများကို မေးပါ။ ၎င်းတွင် ကုဒ်အခြေခံအားလုံးနားလည်မှုရှိပြီး ရှင်းပြပေးနိုင်၊ ဖွံ့ဖြိုးတိုးချဲ့နှင့် အခြားရွေးချယ်စရာများကို အကြံပြုနိုင်သည်။ +**အသုံးပြုနည်း** - ဖိုင်မဆို ဖွင့်၍ Copilot ကို အဆိုပြုထားသည့် မေးခွန်းများ မေးပါ။ ၎င်းသည် ကုဒ်အခြေခံအချက်အလက်များအားလုံးကို သိရှိပြီး ရှင်းလင်းနိုင်ခြင်း၊ တိုးချဲ့စရာနှင့် အခြားအကြံပေးမှုများ ပါရှိသည်။ -ပိုမိုသိလိုပါသလား? [AI တွဲဖက်ရေးသားရေးအတွက် Copilot](https://aka.ms/GitHubCopilotAI) ကိုကြည့်ပါ။ +ပိုမိုသိရှိလိုပါက [AI ပေါင်းစပ်ရေးသားခြင်းအတွက် Copilot](https://aka.ms/GitHubCopilotAI) ကို ကြည့်ရှုပါ။ -## ထပ်မံရရှိနိုင်သော အရင်းအမြစ်များ +## ပိုမိုအတတ်ပညာရရှိရေး အရင်းအမြစ်များ ### LangChain @@ -109,40 +108,41 @@ LangChain4j နှင့် Azure OpenAI GPT-5.2 ကို အသုံးပြ --- -### Core Learning +### အခြေခံ သင်ယူမှု [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![စိုက်အာမခံရေးအတွက်စ Anfänger](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![ဝဘ်ဖွံ့ဖြိုးမှုအတွက်စ Anfänger](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT အတွက်စ Anfänger](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR ဖွံ့ဖြိုးမှုအတွက်စ Anfänger](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- - + ### Copilot စီးရီး -[![AI နှင့်တွဲဖက်အစီအစဉ်ရေးသားမှုအတွက် Copilot](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET အတွက် Copilot](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot စွန့်စားခန်း](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## ကူညီမှုရရှိခြင်း +## ကူညီရန် -AI အက်ပ်များကို တည်ဆောက်ရာတွင် မသေချာမဖြစ် ရင်ဆိုင်ရပါက ဒေါ်: +AI အက်ပ်များ တည်ဆောက်ရာတွင် ထိပ်တန်းမရောက်ခဲ့ပါက သို့မဟုတ် မေးခွန်းများရှိပါက: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -ထုတ်ကုန်တိုးတက်မှု သို့မဟုတ် အမှားများရှိပါက မည်သည့်အခါမျှ ဖိုရမ်သို့ လည်းကောင်း ဆက်သွယ်နိုင်ပါသည်- +ကုန်ပစ္စည်းအကြံပြုချက်များ သို့မဟုတ် အမှားများ ရှိပါက သင်တည်ဆောက်နေစဉ် အောက်ပါလင့်ခ်သို့ ဝင်ကြည့်ပါ။ [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) -## ကိုင်စင် +## လိုင်စင် -MIT ကိုင်စင် - အသေးစိတ်ကို [LICENSE](../../LICENSE) ဖိုင်တွင်ကြည့်ရန်။ +MIT လိုင်စင် - အသေးစိတ်အချက်အလက်များအတွက် [LICENSE](../../LICENSE) ဖိုင်ကို ကြည့်ပါ။ --- -**ဂရုတစိုက်ချက်ချက်** -ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှုဖြစ်သည့် [Co-op Translator](https://github.com/Azure/co-op-translator) အသုံးပြု၍ ဘာသာပြန်ထားခြင်းဖြစ်သည်။ ကျွန်ုပ်တို့သည် တိကျမှုအတွက် ကြိုးပမ်းဆောင်ရွက်ပေမယ့် အလိုအလျောက်ဘာသာပြန်ချက်များတွင် အမှားများ သို့မဟုတ် မှားယွင်းချက်များ ဖြစ်ပေါ်နိုင်ကြောင်း သတိပြုပါရန် ဖိတ်ခေါ်အပ်ပါသည်။ မူရင်းစာတမ်းကို ယင်း၏ မူလဘာသာဖြင့် စံပြအဖြစ် သတ်မှတ်သင့်ပါသည်။ အရေးကြီးသော အချက်အလက်များအတွက်တော့ အင်္ဂါရပ်နယ်ကျွမ်းကျင်သော လူသားဘာသာပြန်ဖြစ်စေရန် အကြံပြုပါသည်။ ဤဘာသာပြန်ခြင်းကို အသုံးပြုမှုမှ ဖြစ်ပေါ်နိုင်သည့် ငြင်းဆိုမှုများ သို့မဟုတ် မှားဖတ်ခြင်းများအတွက် ကျွန်ုပ်တို့သည် တာဝန်မခံပါ။ +**ပြောကြားချက်** +ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှန်ကန်မှုအတွက် ကြိုးပမ်းနေသော်လည်း၊ စက်ကိရိယာဘာသာပြန်ခြင်းများတွင် အမှားများ သို့မဟုတ် မှားယွင်းချက်များ ပါဝင်နိုင်ကြောင်း သတိပြုပါရန် လိုအပ်ပါသည်။ မူလစာတမ်းကို မူရင်းဘာသာဖြင့်သာ ယုံကြည်စိတ်ချရသော အချက်အလက်အဖြစ် သတ်မှတ်သင့်သည်။ အရေးကြီးသည့် သတင်းအချက်အလက်များအတွက် ပရော်ဖက်ရှင်နယ် လူသားဘာသာပြန်သူဝန်ဆောင်မှုကို အကြံပြုပါသည်။ ဤဘာသာပြန်ချက်ကို အသုံးပြုခြင်းမှ ဖြစ်ပေါ်လာသော နားလည်မှုကွာခြားမှုများ သို့မဟုတ် မမှန်ကန်သော အသုံးပြုမှုများအတွက် ကျွန်ုပ်တို့ တာဝန်မခံပါ။ \ No newline at end of file diff --git a/translations/my/docs/GLOSSARY.md b/translations/my/docs/GLOSSARY.md index 1228edd8c..4f2531dda 100644 --- a/translations/my/docs/GLOSSARY.md +++ b/translations/my/docs/GLOSSARY.md @@ -1,224 +1,222 @@ -# LangChain4j အဓိပ္ပာယ်ရှင်းလင်းချက် +# LangChain4j အသုံးအနှုန်းစာအုပ် -## အကြောင်းအရာဇယား +## အကြောင်းအရာစာရင်း -- [အခြေခံ အတွေးအခေါ်များ](../../../docs) -- [LangChain4j အစိတ်အပိုင်းများ](../../../docs) -- [AI/ML အတွေးအခေါ်များ](../../../docs) -- [အသုံးတားရေး](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agents နှင့် Tools](../../../docs) -- [Agentic Module](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure ဝန်ဆောင်မှုများ](../../../docs) -- [စမ်းသပ်ခြင်းနှင့် ဖွံ့ဖြိုးတိုးတက်မှု](../../../docs) +- [အဓိကအယူအဆများ](#အဓိကအယူအဆများ) +- [LangChain4j အစိတ်အပိုင်းများ](#langchain4j-အစိတ်အပိုင်းများ) +- [AI/ML အယူအဆများ](#aiml-အယူအဆများ) +- [လုံခြုံရေးစနစ်များ](#လုံခြုံရေးစနစ်များ) +- [Prompt Engineering](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agents နှင့် Tools](#agents-and-tools---module-04) +- [Agentic Module](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure ဝန်ဆောင်မှုများ](#azure-services---module-01) +- [စမ်းသပ်ခြင်းနှင့် ဖွံ့ဖြိုးတိုးတက်မှု](#testing-and-development---testing-guide) -သင်ကြားမှုအားလုံးတွင် အသုံးပြုသော စကားလုံးများနှင့် အတွေးအခေါ်များအတွက် အလျင်အမြန် ရှာဖွေရန်။ +သင်တန်းအတွင်း အသုံးပြုသော အသုံးအနှုန်းများနှင့် အယူအဆများအတွက် အရှိန်အဟုန်မြန်စွာ ရှာဖွေရန်။ -## အခြေခံ အတွေးအခေါ်များ +## အဓိကအယူအဆများ -**AI Agent** - AI ကို အသုံးပြုကာ ကိုယ်တိုင် အတွေးထုတ်လုပ်ပြီး ရပ်တည်ဆောင်ရွက်သော စနစ်။ [Module 04](../04-tools/README.md) +**AI Agent** - AI ကို အသုံးပြုပြီး အလိုက်သင့်စိတ်ဖြင့် စဉ်းစား၍ လုပ်ဆောင်နိုင်သော စနစ်။ [Module 04](../04-tools/README.md) -**Chain** - လုပ်ဆောင်ချက်စီးရီးတစ်ခုမဟုတ်ပါက နောက်တစ်ဆင့်အဖြစ် ထွက်ရှိမှု ရသည်။ +**Chain** - အဆင့်ဆင့် လုပ်ဆောင်ချက်များစဉ်မှာ ထုတ်လွှင့်ချက်သည် နောက်တစ်ဆင့်တွင် သုံးစွဲသည်။ -**Chunking** - စာရွက်များကို အပိုင်းပိုင်း သို့ ခွဲခြားခြင်း။ မကြာခဏ: ၃၀၀-၅၀၀ တokens နှင့် အနှောင့်အယှက်။ [Module 03](../03-rag/README.md) +**Chunking** - စာရွက်စာတမ်းများကို အစိတ်အပိုင်းသေးသည်အထိ ခွဲခြားခြင်း။ ပုံမှန်: ၃၀၀-၅၀၀ token အတွင်း overlap ဖြင့်။ [Module 03](../03-rag/README.md) -**Context Window** - မော်ဒယ်အတွက် အမြင့်ဆုံး တokens အရေအတွက်။ GPT-5.2: 400K တokens (ဝင်ပေါက် ၂၇၂K, ထွက်ပေါက် ၁၂၈K)။ +**Context Window** - မော်ဒယ်တစ်ခု လက်ခံနိုင်သည့် အများဆုံး tokens အရေအတွက်။ GPT-5.2: ၄၀၀K tokens (အထိ ၂၇၂K input, ၁၂၈K output)။ -**Embeddings** - စာသား၏ အဓိပ္ပာယ်ကို ကိုယ်စားပြုပြတဲ့ နံပါတ် vectors။ [Module 03](../03-rag/README.md) +**Embeddings** - စာသား အဓိပ္ပာယ်ကို သရုပ်ဖော်သည့် ကိန်းရေဗက်တာများ။ [Module 03](../03-rag/README.md) -**Function Calling** - မော်ဒယ်က ပြင်ပ function များကို ခေါ်ရန် ဖွဲ့စည်းထားသော အကောင်အထည်တစ်ခု ဖန်တီးခြင်း။ [Module 04](../04-tools/README.md) +**Function Calling** - မော်ဒယ်က ဂဏန်းပုံစံ အတောင်းခံချက်များဖန်တီး၍ ပြင်ပ function များကို ခေါ်ဆောင်သည်။ [Module 04](../04-tools/README.md) -**Hallucination** - မော်ဒယ်များမှ မှားယွင်းသော်လည်း လူမှတ်မီနိုင်သော အချက်အလက်များ ထုတ်ပေးခြင်း။ +**Hallucination** - မော်ဒယ်မှ မှားယွင်းသည့် သို့သော် ယုံကြည်နိုင်သော အချက်အလက်ကို ဖန်တီးခြင်း။ -**Prompt** - ဘာသာစကားမော်ဒယ်ထံ ရိုက်ထည့်သော စာသား။ [Module 02](../02-prompt-engineering/README.md) +**Prompt** - ဘာသာစကားမော်ဒယ်ထံစာသားထည့်သွင်းချက်။ [Module 02](../02-prompt-engineering/README.md) -**Semantic Search** - keywords မဟုတ်ပဲ embedding ကို အသုံးပြု၍ အဓိပ္ပာယ် အလိုက် ရှာဖွေခြင်း။ [Module 03](../03-rag/README.md) +**Semantic Search** - keywords မဟုတ်ဘဲ အဓိပ္ပာယ်အရ ရှာဖွေမှု။ [Module 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: မှတ်ဉာဏ်မရှိ။ Stateful: ပြောဆိုမှု သမိုင်းကို ထိန်းသိမ်းထားသည်။ [Module 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: မှတ်ဉာဏ်မရှိပါ။ Stateful: စကားပြောဆိုမှုပြီးခဲ့သည်များကို ထိန်းသိမ်းသည်။ [Module 01](../01-introduction/README.md) -**Tokens** - မော်ဒယ်များ အလုပ်လုပ်ရာတွင် အခြေခံ စာသားအပိုင်းများ။ ကုန်ကျစရိတ်နှင့် ကန့်သတ်ချက်များကို ထိခိုက်စေသည်။ [Module 01](../01-introduction/README.md) +**Tokens** - မော်ဒယ်များက လုပ်ဆောင်သော အခြေခံစာသားအချက်များ။ ကုန်ကျစရိတ်နှင့် ကန့်သတ်ချက်များကို သက်ရောက်စေသည်။ [Module 01](../01-introduction/README.md) -**Tool Chaining** - အသုံးပြုရန် သတ်မှတ်ထားသော tools များကို တစ်ခုချင်းဆက်တိုက် အသုံးပြုခြင်း။ [Module 04](../04-tools/README.md) +**Tool Chaining** - တစ်ခုချင်းစီ တိုးတက်အောင်သုံးသည့် tools များကို စဉ်ဆက်မပြတ် ချိတ်ဆက်အသုံးပြုခြင်း။ [Module 04](../04-tools/README.md) ## LangChain4j အစိတ်အပိုင်းများ -**AiServices** - အမျိုးအစားလုံခြုံသော AI ဝန်ဆောင်မှု အင်တာဖေ့စ်များ ဖန်တီးသော အစိတ်အပိုင်း။ +**AiServices** - Type-safe AI ဝန်ဆောင်မှု အင်တာဖေ့စ်များ ဖန်တီးသည်။ -**OpenAiOfficialChatModel** - OpenAI နှင့် Azure OpenAI မော်ဒယ်များ အတွက် စုပေါင်း ဖောက်သည်။ +**OpenAiOfficialChatModel** - OpenAI နှင့် Azure OpenAI မော်ဒယ်များအတွက် အမျိုးသား client တစ်ခု။ -**OpenAiOfficialEmbeddingModel** - OpenAI Official client ကို အသုံးပြုကာ embedding များ ဖန်တီးခြင်း (OpenAI နှင့် Azure OpenAI နှစ်ခုလုံး ပံ့ပိုးသည့်)။ +**OpenAiOfficialEmbeddingModel** - OpenAI Official client ဖြင့် embeddings ဖန်တီးသည် (OpenAI နှင့် Azure OpenAI နှစ်မျိုးလုံးကို ထောက်ပံ့သည်)။ **ChatModel** - ဘာသာစကားမော်ဒယ်များအတွက် အဓိက အင်တာဖေ့စ်။ -**ChatMemory** - ပြောဆိုမှု သမိုင်းကို ထိန်းသိမ်းထားသည်။ +**ChatMemory** - စကားပြောဆိုမှုမှတ်တမ်း ထိန်းသိမ်းသည်။ -**ContentRetriever** - RAG အတွက် သက်ဆိုင်ရာ စာရွက် အပိုင်းများ ရှာဖွေသွားသော ကိရိယာ။ +**ContentRetriever** - RAG အတွက် သက်ဆိုင်ရာ စာရွက်စာတမ်း အစိတ်အပိုင်းများ ရှာဖွေသည်။ -**DocumentSplitter** - စာရွက်များကို အပိုင်းသိုက်သိုက် ခွဲခြားမှု။ +**DocumentSplitter** - စာရွက်စာတမ်းများကို ခွဲခြားသည်။ -**EmbeddingModel** - စာသားကို နံပါတ် vectors သို့ ပြောင်းလဲခြင်း။ +**EmbeddingModel** - စာသားကို ကိန်းရေဗက်တာများသို့ ပြောင်းလဲသည်။ -**EmbeddingStore** - Embeddings များကို သိမ်းဆည်းနှင့် ရယူခြင်း။ +**EmbeddingStore** - Embeddings များကို သိမ်းဆည်းပြီး ပြန်လည် ရယူနိုင်သည်။ -**MessageWindowChatMemory** - နောက်ဆုံးစာသေးများ မှ တစ်ဆင့် Sliding Window ကို ထိန်းသိမ်းခြင်း။ +**MessageWindowChatMemory** - နောက်ဆုံးပို့သော စာတိုများကို စိမ့်ကပ်ထားသော အပြေးအစီအစဉ်။ -**PromptTemplate** - `{{variable}}` နေရာမှတ်တမ်းများဖြင့် ထပ်မံအသုံးပြုနိုင်သော prompt များ ဖန်တီးခြင်း။ +**PromptTemplate** - `{{variable}}` ထည့်သွင်းထားသော ပြန်လည်အသုံးပြုနိုင်သော prompt များ ဖန်တီးသည်။ -**TextSegment** - RAG တွင် အသုံးပြုသော စာသား အပိုင်းနှင့် မီတာဒေတာ။ +**TextSegment** - metadata ပါသော စာသားအစိတ်အပိုင်း။ RAG တွင် အသုံးပြုသည်။ -**ToolExecutionRequest** - Tool အကောင်အထည်ဖော်ရန် တောင်းဆိုမှု ကို ကိုယ်စားပြုမှု။ +**ToolExecutionRequest** - tool အသုံးပြုမှု အတွက် တင်သွင်းချက်ကို ဖော်ပြသည်။ -**UserMessage / AiMessage / SystemMessage** - ပြောဆိုစကားသွားအမျိုးအစားများ။ +**UserMessage / AiMessage / SystemMessage** - စကားပြောဆိုမှု သတင်းပို့အစုံ။ -## AI/ML အတွေးအခေါ်များ +## AI/ML အယူအဆများ -**Few-Shot Learning** - Prompt များတွင် နမူနာများ ပေးသွင်းခြင်း။ [Module 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Prompt များတွင် ဥပမာများ ထည့်သွင်းပေးခြင်း။ [Module 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - မြောက်မားသော စာသားဒေတာဖြင့် လေ့ကျင့်ထားသော AI မော်ဒယ်များ။ +**Large Language Model (LLM)** - စာသားကြီးများအားပေါင်းစည်း၍ လေ့ကျင့်ထားသော AI မော်ဒယ်များ။ -**Reasoning Effort** - GPT-5.2 ၏ စဉ်းစားပထမအဆင့် ထိန်းချုပ်မှု ပြားမီတာ။ [Module 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - GPT-5.2 ၏ စဉ်းစားနက်ရှိုင်းမှု ထိန်းချုပ်ရန် ပါရာမီတာ။ [Module 02](../02-prompt-engineering/README.md) -**Temperature** - ထွက်ရှိမှု အလွတ်တမ်းအတုအယောင် ထိန်းညှိမှု။ အနိမ့်= သတ်မှတ်ထားသော၊ အမြင့်= ဖန်တီးမှုအမြင့်။ +**Temperature** - ထွက်ရှိမည့် အချက်အလက် အမှားလွတ်နည်းသတ်မှတ်ချက်။ နိမ့်ရင် စနစ်တကျ၊ မြင့်ရင် ဖန်တီးမှုမြင့်။ -**Vector Database** - Embeddings များအတွက် အထူးပြု ဒေတာအချက်အလက် တိုက်ဆိုင်ရာသိုလှောင်မှု။ [Module 03](../03-rag/README.md) +**Vector Database** - Embeddings များ အတွက် အထူးသီးသန့်ဒေတာဘေ့စ်။ [Module 03](../03-rag/README.md) -**Zero-Shot Learning** - နမူနာ အသုံးပြုခြင်းမဟုတ်ဘဲ အလုပ်များ ဆောင်ရွက်ခြင်း။ [Module 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - ဥပမာများ မပါဘဲ အလုပ်လုပ်ဆောင်နိုင်ခြင်း။ [Module 02](../02-prompt-engineering/README.md) -## အသုံးတားရေး - [Module 00](../00-quick-start/README.md) +## လုံခြုံရေးစနစ်များ -**Defense in Depth** - ဝန်ဆောင်မှုနှင့် ပေးသူ လုံခြုံရေးထိန်းသိမ်းမှုများ ပေါင်းစပ်ထားသော စွဲမြဲသော ခြုံငုံကာကွယ်ရေး။ +**Defense in Depth** - အလွှာအနှစ်သာရများဖြင့် အလုံအလောက် လုံခြုံရေးတန်ခိုးတိုးမြှင့်ခြင်း။ -**Hard Block** - အကြမ်းဖက်သော အကြောင်းအရာ များဖြစ်လာလျှင် ပေးသူမှ HTTP 400 error ပေးပိတ်တားဆီးခြင်း။ +**Hard Block** - ပြင်းထန်သော အကြောင်းပြချက်များအတွက် ကုန်ကြမ်း HTTP 400 အမှားပစ်ခြင်း။ -**InputGuardrail** - LangChain4j LLM ထံ ရောက်ရှိမီ အသုံးပြုသူ input ကို စစ်ဆေးသွားသော အင်တာဖေ့စ်။ မကောင်းသော prompt များကို စောင့်ပိတ်ကြောင်း ကုန်ကျစရိတ်နှင့် နောက်နှောင့်နှေးမှု ကို လျော့ချတယ်။ +**InputGuardrail** - LangChain4j ၏ interface တစ်ခုဖြစ်ပြီး၊ LLM တွင် ကြိုတင်ရောက်မည့် အသုံးပြုသူ input များကို အတည်ပြုမှုလုပ်သည်။ ဒါမှတဆင့် ကုန်ကျစရိတ်နှင့် ကြာချိန်လျော့ကြေးတယ်။ -**InputGuardrailResult** - guardrail စစ်ဆေးမှု ရလဒ်: `success()` သို့မဟုတ် `fatal("reason")`။ +**InputGuardrailResult** - guardrail အတည်ပြုမှု အမျိုးအစား။ `success()` သို့မဟုတ် `fatal("reason")` ဖြင့် ပြန်လည်ထုတ်ပေးသည်။ -**OutputGuardrail** - အသုံးပြုသူထံ ပြန်ပေးရန် မတိုင်မီ AI တုံ့ပြန်ချက်များကို စစ်ဆေးသော အင်တာဖေ့စ်။ +**OutputGuardrail** - AI အဖြေများ အသုံးပြုသူထံ ပေးပို့ရန်မတိုင်မှီ စစ်ဆေးခြင်းအတွက် interface။ -**Provider Safety Filters** - AI ပေးသူများထံမှ အကြောင်းအရာ စစ်ထုတ်မှုများ API အဆင့်တွင် ဖမ်းဆီးထားသည်။ +**Provider Safety Filters** - AI ပံ့ပိုးသူများ (ဥပမာ Azure OpenAI) မှ ဆက်သွယ်မှု API အဆင့်တွင် ချုပ်ဆိုထားသော အကြောင်းအရာ စစ်တမ်းများ။ -**Soft Refusal** - မော်ဒယ် အမှားမထုတ်ဘဲ ရှင်းပြ၍ ဖြေကြားရန် ဖျက်ပယ်ခြင်း။ +**Soft Refusal** - မော်ဒယ်က အမှားမဖြစ်ပေါ်ဘဲ စိတ်ညစ်ဓာတ်မပေးဘဲ ဖြေရှင်းပေးတယ်။ ## Prompt Engineering - [Module 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - မြန်ဆန်စွာ မှန်ကန်မှုရရှိစေရန် တစ်ဆင့်ချင်း စဉ်းစားခြင်း။ +**Chain-of-Thought** - တဆင့်ဆင့် စဉ်းစားချက် များဖြင့် တိကျမှန်ကန်မှုပိုမိုရရှိစေခြင်း။ -**Constrained Output** - သတ်မှတ်ထားသော ပုံစံ သို့မဟုတ် ဖွဲ့စည်းမှု အပ်နာခြင်း။ +**Constrained Output** - အတိုးစနစ်တကျ အသုံးပြုရန် ပုံစံသတ်မှတ်ခြင်း။ -**High Eagerness** - GPT-5.2 မှ ခွဲခြမ်းစိတ်ဖြာမှု ပြည့်စုံသော ပုံစံ။ +**High Eagerness** - GPT-5.2 ၏ နက်ရှိုင်းစွာ စဉ်းစားမှုပုံစံ။ -**Low Eagerness** - GPT-5.2 မှ လျင်မြန်သော ဖြေကြားချက်ပုံစံ။ +**Low Eagerness** - GPT-5.2 ၏ မြန်ဆန်စွာ ဖြေကြားပုံ။ -**Multi-Turn Conversation** - လွှဲပြောင်းဆက်ဆံမှုများအတွင်း စပ်ဆိုင်မှုပေးခြင်း။ +**Multi-Turn Conversation** - ဆက်လက်အောင် တုံ့ပြန်မှုရှိရန် သတင်းအချက်အလက် ထိန်းသိမ်းခြင်း။ -**Role-Based Prompting** - စနစ် သတင်းအချက်အလက်ဖြင့် မော်ဒယ်ဘာသာရပ်ကို သတ်မှတ်ခြင်း။ +**Role-Based Prompting** - မော်ဒယ်ကို အမျိုးအစားသတ်မှတ်ရန် system messages ဖြင့် သတ်မှတ်ခြင်း။ -**Self-Reflection** - မော်ဒယ်က ကိုယ့်ရလဒ်ကို သုံးသပ် လှှိမ့်ပြောင်းခြင်း။ +**Self-Reflection** - မော်ဒယ်သည် မိမိ၏ထွက်ရှိမှုကို စစ်ဆေး၊ တိုးတက်စေရန် ကြိုးစားခြင်း။ -**Structured Analysis** - သတ်မှတ်ထားသော သုံးသပ်မှု ပြုလုပ်ပုံ။ +**Structured Analysis** - ကန့်သတ်ထားသော အကဲဖြတ်စနစ်။ -**Task Execution Pattern** - အစီအစဉ် → အကောင်အထည် → အနှစ်ချုပ်။ +**Task Execution Pattern** - အစီအစဉ်ရေးဆွဲ → လုပ်ဆောင် → အကျဉ်းချုပ်။ ## RAG (Retrieval-Augmented Generation) - [Module 03](../03-rag/README.md) -**Document Processing Pipeline** - အသုံးပြုလိုက်ပါ → အပိုင်းခွဲ → embedding ထည့် → သိမ်းဆည်း။ +**Document Processing Pipeline** - တွဲဆက်: ယူရန် → အစိတ်အပိုင်း ခွဲရန် → Embed ဆွဲရန် → သိမ်းဆည်းရန်။ -**In-Memory Embedding Store** - စမ်းသပ်မှုအတွက် မဟုတ်သော သိမ်းဆည်းမှု။ +**In-Memory Embedding Store** - စမ်းသပ်မှုအတွက် ထိန်းသိမ်းမှု မရှိသော ဒေတာသိုလှောင်ခြင်း။ -**RAG** - ရှာဖွေရေးနှင့် ထုတ်လုပ်ခြင်း ဆက်စပ်ပေးသည်။ +**RAG** - ရှာဖွေမှုနှင့် ဖန်တီးမှုကို ပေါင်းစပ်၍ တုံ့ပြန်ချက်အခြေခံမှု ပေးသည်။ -**Similarity Score** - အဓိပ္ပာယ်ဆက်နွယ်မှု တိုင်းတာမှု (0-1)။ +**Similarity Score** - Semantic တူညီမှု ရမှတ် (0-1)။ -**Source Reference** - ရှာဖွေတွေ့ရှိသောအရာ၏ မီတာဒေတာ။ +**Source Reference** - ရရှိသော အကြောင်းအရာ metadata။ ## Agents နှင့် Tools - [Module 04](../04-tools/README.md) -**@Tool Annotation** - Java ဗဟိုများကို AI မှ ခေါ်နိုင်သည့် tool အဖြစ် သတ်မှတ်ခြင်း။ +**@Tool Annotation** - Java နည်းစနစ်များအား AI ခေါ်နိုင်သော tools အဖြစ် သတ်မှတ်သည်။ -**ReAct Pattern** - စဉ်းစားပါ → လုပ်ဆောင်ပါ → လေ့လာခြင်း → ထပ်လုပ်ပါ။ +**ReAct Pattern** - စဉ်းစား → လုပ်ဆောင် → လေ့လာ → ထပ်မံလုပ်ဆောင်ခြင်း။ -**Session Management** - အသုံးပြုသူ သီးခြား context များ ထိန်းသိမ်းခြင်း။ +**Session Management** - အသုံးပြုသူများအလိုက် ဖွင့်ထားသော context များကို သီးခြားထားပေးခြင်း။ -**Tool** - AI agent က ခေါ်နိုင်သော လုပ်ဆောင်ချက်။ +**Tool** - AI agent တိုက်ရိုက်ခေါ်နိုင်သော function တစ်ခု။ -**Tool Description** - ကိရိယာရဲ့ ရည်ရွယ်ချက်နှင့် ပာရမီတာများ အကြောင်း ဖော်ပြချက်။ +**Tool Description** - tool ၏ ရည်ရွယ်ချက် နှင့် ပါရာမီတာ ဖော်ပြချက်။ ## Agentic Module - [Module 05](../05-mcp/README.md) -**@Agent Annotation** - AI agent များကို အပြောအဆို သတ်မှတ်မှုဖြင့် သတ်မှတ်ခြင်း။ +**@Agent Annotation** - AI agent များအဖြစ် interface များ သတ်မှတ်ပြီး ချကောင်းပြုမူ အကျဉ်းဖော်ခြင်း။ -**Agent Listener** - `beforeAgentInvocation()` နှင့် `afterAgentInvocation()` ဖြင့် agent လုပ်ဆောင်မှု ကြည့်ရှုခံစားခြင်း။ +**Agent Listener** - Agent လုပ်ငန်းစဉ်ကို `beforeAgentInvocation()` နှင့် `afterAgentInvocation()` မှတဆင့် ကြည့်လိုက်ခြင်း။ -**Agentic Scope** - agents များ ရလာဒ်များ သိမ်းဆည်းပါသော မျှဝေရန် memory နေရာ။ +**Agentic Scope** - agent များ output ကို သိမ်းဆည်းထားသော memory ပိုင်း။ -**AgenticServices** - `agentBuilder()` နှင့် `supervisorBuilder()` ဖြင့် agent များ ဖန်တီးရန် factory။ +**AgenticServices** - `agentBuilder()` နှင့် `supervisorBuilder()` ဖြင့် agent ဖန်တီးရာ factory။ -**Conditional Workflow** - ကန့်သတ်ချက်များအရ အထူးပြု agent များသို့ လမ်းညွှန်ခြင်း။ +**Conditional Workflow** - အခြေအနေများပေါ်မူတည်၍ သီးခြား agent များဖွင့်သုံးခြင်း။ -**Human-in-the-Loop** - လူ ဆန်းစစ်အတည်ပြုချက် သို့မဟုတ် အကြောင်းအရာ သုံးသပ်ခြင်း အပြင်အဆင်။ +**Human-in-the-Loop** - အတည်ပြုခြင်း သို့မဟုတ် အကြောင်းအရာ ကြည့်ရှုရန် လူကို ထည့်သွင်းသည့် workflow ပုံစံ။ -**langchain4j-agentic** - 선언형 agent building အတွက် Maven dependency (စမ်းသပ်မှုအဆင့်)။ +**langchain4j-agentic** - Declarative agent ဖန်တီးရေးရန် Maven သတ်မှတ်ချက် (စမ်းသပ်မှုအစိတ်အပိုင်း)။ -**Loop Workflow** - ချက်ချင်းလိုအပ်ချက် ပြည့်မှ မျှောက်တိုက် agent လုပ်ငန်းစဉ်။ +**Loop Workflow** - အခြေအနေဖြစ်တဲ့အထိ agent များ တစ်ကြိမ်ပြီးတစ်ကြိမ် ဆက်လုပ်ခြင်း (ဥပမာ quality score ≥ 0.8)။ -**outputKey** - Agent များ ရယ်ငယ်ရာ Agentic Scope သို့ ရလဒ် သိုလှောင်ရာ ချက်။ +**outputKey** - Agent annotation parameter ဖြစ်ပြီး agentic Scope တွင် ပြန်သိမ်းရာများ။ -**Parallel Workflow** - လွတ်လပ်စွာ လုပ်ငန်းကို ဘာသာရေး agent များအပြား အချိန်တစ်ပြိုင်နက်မှာ လုပ်ခြင်း။ +**Parallel Workflow** - လွတ်လပ်သော အလုပ်များအတွက် agent များကို တပြိုင်နက် ဆောင်ရွက်ခြင်း။ -**Response Strategy** - Supervisor က နောက်ဆုံးဖြေရှင်းချက် အကြောင်း ရေးဆွဲပုံ - LAST, SUMMARY, သို့မဟုတ် SCORED။ +**Response Strategy** - supervisor သည် နောက်ဆုံးဖြေချက်ကို LAST, SUMMARY, သို့မဟုတ် SCORED အနေနှင့် ဖော်ပြခြင်း။ -**Sequential Workflow** - Agent အလိုက် တစ်ဆင့်ဆက်တိုက်ဆောင်ရွက်ခြင်း။ +**Sequential Workflow** - အဆင့်လိုက် agent များကို ဆောင်ရွက်၍ outputသည် နောက်တစ်ဆင့်သို့ စီးဆင်းမှု။ -**Supervisor Agent Pattern** - Supervisor LLM ထံမှ အခြေခံ၍ sub-agent များ ရွေးချယ်ခေါ်ယူစေသော agentic အဆင့်မြင့် ပုံစံ။ +**Supervisor Agent Pattern** - တိုးတက်သော agentic ပုံစံဖြစ်ပြီး supervisor LLM သည် စိတ်ကြိုက် sub-agent များခေါ်ယူခြင်း။ ## Model Context Protocol (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j အတွက် MCP တွဲဖက်အသုံးပြုရန် Maven dependency။ +**langchain4j-mcp** - LangChain4j ထဲတွင် MCP ပေါင်းစည်းမှုအတွက် Maven သတ်မှတ်ချက်။ -**MCP** - Model Context Protocol: AI app များနှင့် ပြင်ပ Tools များ ဆက်သွယ်ရန် စံချိန်တစ်ခု။ တစ်ကြိမ်တည်ဆောက်၍ မည်နေရာတွင်မဆို အသုံးပြုရန်။ +**MCP** - Model Context Protocol: AI အပ်ပလီကေးရှင်းများကို ပြင်ပ tools နှင့် ချိတ်ဆက်မှုစံကြားစနစ်။ တစ်ကြိမ်တည်ဆောက်၍ အားလုံးတွင် အသုံးပြုနိုင်သည်။ -**MCP Client** - MCP server များဆီ သွား၍ Tools ရှာဖွေ အသုံးပြုနိုင်သော app။ +**MCP Client** - MCP server များနှင့် ချိတ်ဆက်၍ tool များ ရှာဖွေ သုံးစွဲသည့် အက်ပ်။ -**MCP Server** - MCP ဖြင့် Tool များကို ဖော်ပြထားပြီး parameter schemas ဖြင့် ဝန်ဆောင်မှုပေးသည့် ဆာဗာ။ +**MCP Server** - Tool များကို MCP ဖြင့် ထုတ်ဖေါ်ထားသော ဝန်ဆောင်မှု။ ဖော်ပြချက်နှင့် ပြင္ပ parameter schema ပါရှိသည်။ -**McpToolProvider** - MCP tools များကို AI ဝန်ဆောင်မှုများနှင့် agent များတွင် အသုံးပြုရန် LangChain4j အစိတ်အပိုင်း။ +**McpToolProvider** - AI ဝန်ဆောင်မှုများနှင့် agent များတွင် MCP tools အသုံးပြုရန် LangChain4j အစိတ်အပိုင်း။ -**McpTransport** - MCP ဆက်သွယ်မှု အင်တာဖေ့စ်။ Stdio နှင့် HTTP ကဲ့သို့ ထုတ်ဖော်ချက် ရှိသည်။ +**McpTransport** - MCP ဆက်သွယ်ရေး interface။ စနစ်အသုံးချချက်များတွင် Stdio နှင့် HTTP ပါဝင်သည်။ -**Stdio Transport** - stdin/stdout ဖြင့် ဒေသတွင်း လုပ်ထုံးလုပ်နည်း။ ဖိုင်စနစ် ဝင်ရောက်မှု သို့မဟုတ် command-line tool များအတွက် အသုံးပြုသည်။ +**Stdio Transport** - ဒေသန္တရ လုပ်ငန်းစဉ်များအတွက် stdin/stdout ဖြင့် ဆက်သွယ်သော транспорт။ -**StdioMcpTransport** - MCP ဆာဗာ ကို subprocess အနေနှင့် အလုပ်လုပ်စေရန် LangChain4j က အကောင်အထည် ဖော်ထားသည်။ +**StdioMcpTransport** - MCP server ကို subprocess အဖြစ် ဖန်တီးသော LangChain4j အကောင်အထည်ဖော်မှု။ -**Tool Discovery** - Client က server ဆီသို့ လက်ရှိ အသုံးပြုနိုင်သော tools များအား ဖော်ပြချက်နှင့် schemas အပါအဝင် မေးမြန်းရှာဖွေခြင်း။ +**Tool Discovery** - Client သည် မြှင့်တင်မှု နှင့် schemas များနဲ့ tool များ ရှာဖွေမေးမြန်းခြင်း။ ## Azure ဝန်ဆောင်မှုများ - [Module 01](../01-introduction/README.md) -**Azure AI Search** - vector စွမ်းရည်ပါဝင်သည့် မိုးကောင်းကင် ရှာဖွေမှု။ [Module 03](../03-rag/README.md) +**Azure AI Search** - vector ဆိုင်ရာ လက္ခဏာဖြင့် cloud search။ [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Azure အရင်းအမြစ်များ ထည့်သွင်းပေးသည်။ +**Azure Developer CLI (azd)** - Azure အရင်းအမြစ်များ ထုတ်လုပ်ခြင်း။ -**Azure OpenAI** - Microsoft ၏ စီးပွားဖြစ် AI ဝန်ဆောင်မှု။ +**Azure OpenAI** - Microsoft ၏ စီးပွားရေး AI ဝန်ဆောင်မှု။ -**Bicep** - Azure အောက်ခံ အဆောက်အအုံ ကုဒ်ရေးခြင်း ဘာသာစကား။ [Infrastructure Guide](../01-introduction/infra/README.md) +**Bicep** - Azure အခြေခံအချက်အလက်-ကုဒ် ဘာသာစကား။ [Infrastructure Guide](../01-introduction/infra/README.md) -**Deployment Name** - Azure တွင် မော်ဒယ် deployment အတွက် အမည်။ +**Deployment Name** - Azure တွင် မော်ဒယ် deployment အမည်။ -**GPT-5.2** - Reasoning ထိန်းချုပ်မှု ပါရှိသည့် နောက်ဆုံးပေါ် OpenAI မော်ဒယ်။ [Module 02](../02-prompt-engineering/README.md) +**GPT-5.2** - reasoning ထိန်းချုပ်မှုပါသော နောက်ဆုံး OpenAI မော်ဒယ်။ [Module 02](../02-prompt-engineering/README.md) ## စမ်းသပ်ခြင်းနှင့် ဖွံ့ဖြိုးတိုးတက်မှု - [Testing Guide](TESTING.md) -**Dev Container** - ကုဒ်ဖန်တီးရေးအတွက် container ပတ်ဝန်းကျင်။ [Configuration](../../../.devcontainer/devcontainer.json) +**Dev Container** - ကွန်တိန်နာ အခြေပြု ဖွံ့ဖြိုးရေး ပတ်ဝန်းကျင်။ [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - အခမဲ့ AI မော်ဒယ် ကစားကွင်း။ [Module 00](../00-quick-start/README.md) +**In-Memory Testing** - မွမ်းမံထားသော မှတ်ဉာဏ်တွင် စမ်းသပ်ခြင်း။ -**In-Memory Testing** - မီမာရီ သိုလှောင်မှု ဖြင့် စမ်းသပ်ခြင်း။ +**Integration Testing** - တကယ့် အခြေခံအဆောက်အအုံဖြင့် စမ်းသပ်ခြင်း။ -**Integration Testing** - ပိုင်းစပ်နှင့်အတူ စမ်းသပ်ခြင်း။ - -**Maven** - Java ဖန်တီးမှု အလိုအလျောက် ကိရိယာ။ +**Maven** - Java build automation မော်ဂျူး။ **Mockito** - Java mocking framework။ @@ -227,6 +225,6 @@ --- -**စည်းမျဉ်းချက်** -ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှုဖြစ်သည့် [Co-op Translator](https://github.com/Azure/co-op-translator) ကို အသုံးပြုပြီး ဘာသာပြန်ထားပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှန်ကန်မှုအတွက် ကြိုးစားသော်လည်း အလိုအလျောက် ဘာသာပြန်ခြင်းသည် အမှားများ သို့မဟုတ် မှားယွင်းမှုများ ပါဝင်နိုင်ကြောင်း ကျေးဇူးပြု၍ လေးစားရရှိပါ။ မူလစာတမ်းကို မိမိဘာသာစကားဖြင့် အမှန်တကယ် အရာဦးတည်ချက်အဖြစ် ယူဆရန် အကြံပြုပါသည်။ အရေးပါသည့် အချက်အလက်များအတွက် မူရင်း လူတစ်ဦးချင်း ဘာသာပြန်ခြင်းကို သင့်တော်ပါသည်။ ဤဘာသာပြန်ချက်အသုံးပြုမှုကြောင့် ဖြစ်ပေါ်လာသော နားမလည်မှုများ သို့မဟုတ် မှားယွင်း ဖတ်ရှုမှုများအတွက် ကျွန်ုပ်တို့သည် တာဝန်မယူပါ။ +**ပြောကြားချက်** +ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှန်ကန်မှုအတွက် ကြိုးပမ်းနေသော်လည်း၊ စက်ကိရိယာဘာသာပြန်ခြင်းများတွင် အမှားများ သို့မဟုတ် မှားယွင်းချက်များ ပါဝင်နိုင်ကြောင်း သတိပြုပါရန် လိုအပ်ပါသည်။ မူလစာတမ်းကို မူရင်းဘာသာဖြင့်သာ ယုံကြည်စိတ်ချရသော အချက်အလက်အဖြစ် သတ်မှတ်သင့်သည်။ အရေးကြီးသည့် သတင်းအချက်အလက်များအတွက် ပရော်ဖက်ရှင်နယ် လူသားဘာသာပြန်သူဝန်ဆောင်မှုကို အကြံပြုပါသည်။ ဤဘာသာပြန်ချက်ကို အသုံးပြုခြင်းမှ ဖြစ်ပေါ်လာသော နားလည်မှုကွာခြားမှုများ သို့မဟုတ် မမှန်ကန်သော အသုံးပြုမှုများအတွက် ကျွန်ုပ်တို့ တာဝန်မခံပါ။ \ No newline at end of file diff --git a/translations/my/docs/TESTING.md b/translations/my/docs/TESTING.md index 7b72f0351..9b5e73891 100644 --- a/translations/my/docs/TESTING.md +++ b/translations/my/docs/TESTING.md @@ -1,20 +1,20 @@ -# LangChain4j Applications စမ်းသပ်ခြင်း +# LangChain4j အပလီကေးရှင်းများ စမ်းသပ်ခြင်း -## မူကြောင်းဇယား +## အကြောင်းအရာ စာရင်း -- [အမြန်စတင်မှု](../../../docs) -- [စမ်းသပ်မှုများ ဘာတွေ ပါဝင်သလဲ](../../../docs) -- [စမ်းသပ်မှုများကို ပြုလုပ်ခြင်း](../../../docs) -- [VS Code မှာ စမ်းသပ်မှုများ ပြုလုပ်ခြင်း](../../../docs) -- [စမ်းသပ်မှု ပုံစံများ](../../../docs) -- [စမ်းသပ်မှု အယူအဆ](../../../docs) -- [နောက်တစ်ဆင့်](../../../docs) +- [လျင်မြန်စွာ စတင်မှု](#လျင်မြန်စွာ-စတင်မှု) +- [စမ်းသပ်မှုတွင် ဖုံးအုပ်ထားသည့် အကြောင်းအရာများ](#စမ်းသပ်မှုတွင်-ဖုံးအုပ်ထားသည့်-အကြောင်းအရာများ) +- [စမ်းသပ်မှုများ ပြုလုပ်ခြင်း](#စမ်းသပ်မှုများ-ပြုလုပ်ခြင်း) +- [VS Code တွင် စမ်းသပ်မှုများ ပြုလုပ်ခြင်း](#vs-code-တွင်-စမ်းသပ်မှု-ပြုလုပ်ခြင်း) +- [စမ်းသပ်မှု ပုံစံများ](#စမ်းသပ်မှု-ပုံစံများ) +- [စမ်းသပ်မှု နည်းဗျူဟာ](#စမ်းသပ်မှု-နည်းဗျူဟာ) +- [နောက်ဆုံး လှုပ်ရှားမှုများ](#နောက်ဆုံး-လှုပ်ရှားမှုများ) -ဤလမ်းညွှန်သည် API key မလိုအပ်ဘဲ သို့မဟုတ် အပြင်စနစ်များမလိုအပ်ဘဲ AI applications များကို စမ်းသပ်နည်းများကို ပြသသော စမ်းသပ်မှုများကို ရှင်းပြသည်။ +ဤလမ်းညွှန်သည် API key မလိုအပ်ဘဲ သို့မဟုတ် အပြင်ဘက်ဝန်ဆောင်မှုများ မလိုအပ်ဘဲ AI အပလီကေးရှင်းများကို ဘယ်လို စမ်းသပ်ရမည်ကို ပြသသည့် စမ်းသပ်မှုများနှင့် သင်ကို လမ်းညွှန်ပေးပါသည်။ -## အမြန်စတင်မှု +## လျင်မြန်စွာ စတင်မှု -အဘယ်သူမျှမ စမ်းသပ်မှုများအားလုံးကို အမိန့်တစ်ခုဖြင့် ပြုလုပ်ပါ။ +တစ်ချက်ချင်းသာဖြင့် စမ်းသပ်မှုအားလုံးကို လုပ်ဆောင်ပါ။ **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -စမ်းသပ်မှုအားလုံး ပြီးဆုံးသွားပါက အောက်တွင် ပြထားသည့် screenshot ကဲ့သို့ output တွေ့ပါမည် — စမ်းသပ်မှုများ ကွဲလွှတ်မှုမရှိပေါင်းလုံးပြီးလုပ်ဆောင်သည်။ +စမ်းသပ်မှုအားလုံး အောင်မြင်ပါက အောက်ပါ screenshot များကဲ့သို့ အထွက်များကို မြင်ရမည် — စမ်းသပ်မှုများ ၀ မှတ်ချက်ဖြင့် ပြေးလျက်ရှိသည်။ Successful Test Results -*စမ်းသပ်မှု အောင်မြင်စွာ ပြုလုပ်ခြင်းနှင့် စမ်းသပ်မှုအားလုံးကွဲလွှတ်မှုမရှိဖြင့် ပြပွဲ* +*အောင်မြင်သော စမ်းသပ်မှု ညွှန်ပြချက် - စမ်းသပ်မှုအားလုံး အောင်မြင်စွာ ပြေးနေခြင်း* -## စမ်းသပ်မှုများ ဘာတွေ ပါဝင်သလဲ +## စမ်းသပ်မှုတွင် ဖုံးအုပ်ထားသည့် အကြောင်းအရာများ -ဤသင်တန်းသည် **unit tests** အား အခြေပြုသည်။ စမ်းသပ်မှု တစ်ခုချင်းစီသည် LangChain4j အဆောက်အအုံတစ်ခုကို အထူးသဖြင့် မဟာဗျူဟာ တစ်ခုအဖြစ် မူတည်ကာ လုပ်ဆောင်သည်။ အောက်ပါ စမ်းသပ်မှု ပီရမစ်သည် unit test များ၏ တည်ရှိရာနေရာကို ဖော်ပြသည် — ၎င်းတို့သည် သင့်တစ်ခုချင်း test မဟာဗျူဟာ အခြေခံ သာမာန်၊ အမြန်နှင့် ယုံကြည်စိတ်ချရသော အခြေခံဖြစ်သည်။ +ဤသင်တန်းမှာ ဒေသတွင်းတွင် ပြေးနေသော **ယူနစ်စမ်းသပ်မှုများ** ကို အလေးထားပါသည်။ တစ်ခုချင်းစမ်းသပ်မှုသည် LangChain4j အယူအဆ တစ်ရပ်ကို သီးခြားပြသပေးသည်။ အောက်ပါ စမ်းသပ်မှု ပန်နစ်ရမ်သည် ယူနစ်စမ်းသပ်မှုများ၏ တည်နေရာကို ပြသထားပြီး — ၎င်းသည် သင်၏ စမ်းသပ်မှု နည်းဗျူဟာကျစ်လစ်ပြီး ယုံကြည်စိတ်ချရသော အခြေခံအဖြစ် ဆောက်လုပ်ပေးသည်။ Testing Pyramid -*Unit tests (မြန်ဆန်ပြီး ပိတ်ဆို့ခြင်းမရှိသော), integration tests (အမှန်တကယ် ကိရိယာများဖြင့်), နှင့် end-to-end tests တို့အကြား ကျိုးကြောင်းဆက်နွယ်မှုအချိုးအစား ကို ဖော်ပြထားသည်။ ဤသင်တန်းသည် unit testing ကို ဖော်ပြသည်။* +*ယူနစ်စမ်းသပ်မှုများ (မြန်ဆန်ပြီး သီးခြားထားသည်), ပေါင်းစပ်စမ်းသပ်မှုများ (အမည်မှန် တွဲဖက်ပစ္စည်းများ), နှင့် အဆုံး-to-အဆုံးစမ်းသပ်မှုများအကြား သင့်တန်းညှိမှုရှိမှုကို ပြသသော စမ်းသပ်မှု ပန်နစ်ရမ်။ ဤသင်တန်းသည် ယူနစ်စမ်းသပ်မှုကို ဖုံးအုပ်သည်။* -| Module | Tests | အာရုံစိုက်ချက် | အဓိကဖိုင်များ | -|--------|-------|-----------------|----------------| -| **00 - Quick Start** | 6 | Prompt နမူနာများနှင့် အစားထိုးခြင်း | `SimpleQuickStartTest.java` | -| **01 - Introduction** | 8 | စကားပြောမှတ်ဉာဏ်နှင့် အခြေအနေရှိသော စကားဝိုင်း | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | GPT-5.2 ပုံစံများ၊ စိတ်အားထက်သန်မှု အဆင့်များ၊ ဖွဲ့စည်းတည့်သော output | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | စာရွက်စာတမ်း ရယူခြင်း၊ embedding များ၊ ဆင်တူမှု ရှာဖွေမှု | `DocumentServiceTest.java` | -| **04 - Tools** | 12 | ဖွင့်ဆိုမှုလုပ်ဆောင်ခြင်းနှင့် ကိရိယာလိုက်လိုက်မှု | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol နှင့် Stdio မောင်းနှင်မှု | `SimpleMcpTest.java` | +| Module | စမ်းသပ်မှုများ | အာရုံစိုက်ချက် | အဓိက ဖိုင်များ | +|--------|---------------|----------------|------------------| +| **01 - နိဒါန်း** | ၈ | စကားပြောမှတ်ဉာဏ်နှင့် အခြေအနေပြောင်းလဲမှု | `SimpleConversationTest.java` | +| **02 - Prompt Engineering** | ၁၂ | GPT-5.2 ပုံစံများ၊ စိတ်အားထက်သန်မှုအဆင့်များ၊ ဖွဲ့စည်းထားသော ထွက်ရှိမှု | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | ၁၀ | စာရွက်စာတမ်း စိမ့်နှင့် ထည့်သွင်းခြင်း၊ embedding များ၊ သက်ဆိုင်ရာ ရှာဖွေမှု | `DocumentServiceTest.java`` | +| **04 - Tools** | ၁၂ | ဖန်တီးမှုခေါ်ဆိုခြင်းနှင့် ကိရိယာ ဆက်သွယ်ခြင်း | `SimpleToolsTest.java` | +| **05 - MCP** | ၈ | Model Context Protocol နှင့် Stdio ပို့ဆောင်မှု | `SimpleMcpTest.java` | -## စမ်းသပ်မှုများကို ပြုလုပ်ခြင်း +## စမ်းသပ်မှုများ ပြုလုပ်ခြင်း -**root directory မှ စမ်းသပ်မှုအားလုံးကို ပြုလုပ်ရန်:** +**Root မှ စမ်းသပ်မှုအားလုံး ဖျော်ဖြေပါ:** **Bash:** ```bash @@ -63,23 +62,23 @@ mvn test mvn --% test ``` -**အထူးသတ်မှတ် module အတွက် စမ်းသပ်မှုများပြုလုပ်ရန်:** +**Module ဂဏန်းအလိုက် စမ်းသပ်မှုများ ဖျော်ဖြေချင်ပါက:** **Bash:** ```bash cd 01-introduction && mvn test -# မူလမှ သို့မဟုတ် +# သို့မဟုတ် ရုတ်မှ mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# ဒါမှမဟုတ် root မှာနေရာယူပါ +# ဒါမှမဟုတ် root မှစပြီး mvn --% test -pl 01-introduction ``` -**Test class တစ်ခုလုံးကို ပြုလုပ်ရန်:** +**Test class တစ်ခုကို ဖျော်ဖြေချင်သောအခါ:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**အထူးသတ်မှတ် စမ်းသပ်မှုနည်းလမ်းတစ်ခုကို ပြုလုပ်ရန်:** +**Test method တစ်ခုစီကို ဖျော်ဖြေချင်သောအခါ:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#စကားပြောဆိုမှုမှတ်တမ်းကို ထိန်းသိမ်းထားသင့်သည် +mvn test -Dtest=SimpleConversationTest#စကားပြောလမ်းကြောင်းမှတ်တမ်းကို ထောက်ထားသင့်သည် ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#စကားပြောသမိုင်းကို ထိန်းသိမ်းထားသင့်သည်။ +mvn --% test -Dtest=SimpleConversationTest#စကားပြောဆိုမှုမှတ်တမ်းကို ထိန်းသိမ်းဆောင်ရမည် ``` -## VS Code တွင် စမ်းသပ်မှုများ ပြုလုပ်ခြင်း +## VS Code တွင် စမ်းသပ်မှု ပြုလုပ်ခြင်း -Visual Studio Code သုံးပါက Test Explorer သည် စမ်းသပ်မှုများကို အကြမ်းဖျဉ်မှု ပြုလုပ်ရန် နှင့် debug ပြုလုပ်ရန် ဂရပ်ဖစ်နယ်အင်တာဖေ့စ် ဖြစ်သည်။ +Visual Studio Code ကိုသုံးနေပါက Test Explorer သည် စမ်းသပ်မှုများ ဖျော်ဖြေခြင်းနှင့် debug လုပ်ခြင်းများအတွက် ဂရပ်ဖစ် အင်တာဖေ့စ်ကို ပေးသည်။ VS Code Test Explorer -*VS Code Test Explorer သည် Java test class အားလုံးနှင့် တစ်ကိုယ်ရည် စမ်းသပ်မှု နည်းလမ်းများကို ပြသနေသည်* +*VS Code Test Explorer မှာ Java test class အကုန်လုံးနှင့် တစ်ခုချင်းစီ test method များကို ပြသထားခြင်း* -**VS Code တွင် စမ်းသပ်မှုများပြုလုပ်ရန်:** +**VS Code မှာ စမ်းသပ်မှုများ ဖျော်ဖြေရန်:** -1. Activity Bar တွင် Beaker အိုင်ကွန်ကိုနှိပ်ကာ Test Explorer ကိုဖွင့်ပါ -2. စမ်းသပ်မှု အဖွဲ့အစည်းနှင့် test classes အားလုံးကို ကြည့်ရှုရန် စမ်းသပ်မှု ထောက်ပံ့ပွားမှု များကို ကျယ်ပြန့်စွာ ဖွင့်ပါ -3. စမ်းသပ်မှု တစ်ခုချင်းကို လုပ်ဆောင်ရန် ဘေးရှိ play အိုင်ကွန်ကို နှိပ်ပါ -4. စမ်းသပ်မှုအားလုံးကို လုပ်ဆောင်ရန် "Run All Tests" ကို နှိပ်ပါ -5. စမ်းသပ်မှု တစ်ခုကိုညာခလုတ်နှိပ်ပြီး "Debug Test" ကို ရွေးချယ်ကာ breakpoint များ ထားပြီး ကုဒ်ကို အဆင့်လိုက် မိတ်ဆက်ကြည့်ပါ +1. Activity Bar မှ beaker icon ကို ကလစ်ပြီး Test Explorer ကို ဖွင့်ပါ +2. စမ်းသပ်မှု ပင်လယ်တော်ပင်ကို ဖြံ့ဖြိုး၍ module အားလုံးနှင့် test class များကို ကြည့်ပါ +3. တစုံတရာ စမ်းသပ်မှုကို တစ်ခုချင်းစီ ဖျော်ဖြေရန် play ခလုတ်ကို နှိပ်ပါ +4. "Run All Tests" ကို နှိပ်၍ စမ်းသပ်မှုအားလုံးကို ဖျော်ဖြေပါ +5. စမ်းသပ်မှုတစ်ခုခုကို right-click ပြီး "Debug Test" ရွေးပြီး breakpoints သတ်မှတ်ပြီး စမ်းသပ်မှုကို စီမံပါ -Test Explorer တွင် အောင်မြင်သော စမ်းသပ်မှုများအတွက် အစိမ်းရောင်ကွင်းကပ် အတည်ပြုချက်များ ပြသပြီး စမ်းသပ်မှု မအောင်မြင်ပါက အသေးစိတ် အရှုံးရှာမှု မက်ဆေ့များ ထောက်ပြသည်။ +Test Explorer မှ အောင်မြင်သော စမ်းသပ်မှုများအတွက် အစိမ်းရောင် မှတ်ချက်များကို ပြသပြီး၊ မအောင်မြင်သော စမ်းသပ်မှုများအတွက် အသေးစိတ် ဖော်ပြချက်များ ပေးသည်။ ## စမ်းသပ်မှု ပုံစံများ ### ပုံစံ ၁: Prompt Template စမ်းသပ်ခြင်း -အလွယ်ဆုံး ပုံစံမှာ AI မော်ဒယ် မခေါ်ဘဲ prompt template များကို စမ်းသပ်သည်။ ခေါင်းစဉ်အစားထိုးမှုမှန်ကန်စွာ လုပ်ဆောင်သည်ဟု အတည်ပြုခြင်းနှင့် ပုံစံတည့်တည့်ဖြင့် ဖော်ပြခြင်းကို လုပ်ဆောင်သည်။ +နည်းလမ်းလွယ်ဆုံးမှာ AI မော်ဒယ်ကို မခေါ်ဘဲ prompt template များကို စမ်းသပ်ခြင်းဖြစ်သည်။ မူလကွန်ဗားရှင်းများအထိ ပြောင်းလဲမှုများမှန်ကန်မှုနှင့် prompt များ ဖော်စပ်မှု့မှန်ကန်မှုကို အတည်ပြုသည်။ Prompt Template Testing -*Prompt template စမ်းသပ်မှု ဖော်ပြချက်: နမူနာဖြင့် အစားထိုးမှု → တန်ဖိုးများ ထည့်သွင်း → ဖော်ပြမှု အောင်မြင်သည်ဟု စစ်ဆေးခြင်း* +*Prompt template စမ်းသပ်မှု တွင် ပုံစံအသစ်များ → တန်ဖိုးများ ထည့်သွင်းခြင်း → ဖော်စပ်မှု အတည်ပြုပြီးဖြစ်လာသည်။* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -ဤစမ်းသပ်မှုသည် `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` တွင် အားကျဆုံးခြင်း။ +ဤပုံစံတွင် variable substitution မှန်ကန်စွာ လုပ်ဆောင်ပြီး prompt များ ပြန်တွေ့ရသည်မှာ အတည်ပြုသည် - API key သို့မဟုတ် မော်ဒယ်ခေါ်ဆိုမှု လိုအပ်မှု မရှိပါ။ -**ပြုလုပ်ရန်:** +### ပုံစံ ၂: Language Model များ Mock လုပ်ခြင်း -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#စမ်းသပ်မေးခွန်းပုံစံဖော်ပြချက်အတန်းစဉ်ရေးဆွဲခြင်း -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#စမ်းသပ်မည့် Prompt Template ပုံစံရေးဆွဲခြင်း -``` - -### ပုံစံ ၂: Language Model များ ကို Mock လုပ်ခြင်း - -စကားပြောထိန်းချုပ်မှု မြန်နှုန်းနှင့် ပေါ့ပါးစေသည့် စမ်းသပ်မှုများအတွက် Mockito ကိုအသုံးပြုပြီး အတုမော်ဒယ်များဖန်တီးကြသည်။ ဤနည်းလမ်းသည် စမ်းသပ်မှုများအား မြန်ဆန်၊ အခမဲ့နှင့် ရလဒ်တည်ငြိမ်စေသည်။ +စကားပြောပုံစံ စမ်းသပ်သောအခါ Mockito ကို အသုံးပြုကာ ကြိုတင်သတ်မှတ်ထားသော ဖြေကြားချက်များ ကို ပြန်လည်ထုတ်ပေးသော မော်ဒယ်များ ဖန်တီးပါ။ ၎င်းသည် စမ်းသပ်မှုကို မြန်ဆန်ပြီး အခမဲ့၊ သတ်မှတ်ထားနိုင်သည့် ပုံစံဖြစ်စေသည်။ Mock vs Real API Comparison -*စမ်းသပ်ရန် mocks များကို ဘာကြောင့် မော်ဒယ်အသုံးချခြင်းထက် မတူညီကြောင်းဖော်ပြသည်: မြန်ဆန်, အခမဲ့, ရလဒ်တည်ငြိမ်, API key မလိုအပ်* +*စမ်းသပ်မှုအတွက် mock မော်ဒယ်များ၏ အားသာချက်များ – အမြန်၊ အခမဲ့၊ သတ်မှတ်နိုင်၍ API Key မလိုအပ်သည်။ ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // အသုံးပြုသူ ၃ ဦး + AI မက်ဆေ့ခ်ျ ၃ ခု + assertThat(history).hasSize(6); // 3 ယူဇာ + 3 AI စာတိုများ } } ``` -ဤပုံစံသည် `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` တွင် ပါဝင်သည်။ Mock မော်ဒယ်သည် ရေရှည်တည်ငြိမ်တည်ရှိမှုရှိစေရန် memory management မှန်ကန်မှုကို စစ်ဆေးနိုင်စေရန် ဖြစ်သည်။ +ဤ ပုံစံသည် `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` တွင် တွေ့နိုင်သည်။ mock မော်ဒယ်သည် သတိမှတ်ဉာဏ်စီမံခန့်ခွဲမှု လုပ်ဆောင်မှုအား တည်ငြိမ်စေရန် သေချာစေသည်။ -### ပုံစံ ၃: စကားပြောတည်ငြိမ်မှု စမ်းသပ်ခြင်း +### ပုံစံ ၃: စကားပြောခွဲခြားမှု စမ်းသပ်ခြင်း -စကားပြောမှတ်ဉာဏ်သည် အသုံးပြုသူများ အရေအတွက် များစွာရှိခြင်းကွဲလွဲသည့် စနစ်ဖြစ်ရန် လိုအပ်သည်။ ဤစမ်းသပ်မှုသည် စကားပြောများ၏ context မတူမတူ လွှဲပြောင်းမှု မဖြစ်စေရန် စစ်ဆေးသည်။ +စကားပြောမှတ်ဉာဏ်သည် အသုံးပြုသူများစွာ အကွာအဝေးထားရပါမည်။ ဤစမ်းသပ်မှုသည် စကားပြောများ သီးခြားထားသည်ကို အတည်ပြုသည်။ Conversation Isolation -*တစ်ဦးချင်းစကားပြောမှတ်ဉာဏ် store များကား။ အသုံးပြုသူ မတူကွဲပြားမှု မိမိ Context မမှားခန့်မှန်းပေးသည်* +*တစ်ဦးချင်း အသုံးပြုသူများအတွက် သီးခြားသော မှတ်ဉာဏ် စုစည်းမှုများရှိခြင်းကို ပြသ၍ context မပေါင်းစပ်ဘဲ ဖြစ်စေရန် စမ်းသပ်ခြင်း* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -စကားပြောတစ်ခုစီသည် အလိုအလျောက် သီးခြားမှတ်တမ်းထားသည်။ ထုတ်လုပ်ရေးစနစ်များတွင် ဤကွဲပြားမှု ဖြစ်ရပ်သည် များစွာသော အသုံးပြုသူများအတွက် အရေးကြီးသည်။ +တစ်စကားပြောတိုင်းသည် သီးခြား လွတ်လပ်သည့် သမိုင်းစာမျက်နှာကို ထိန်းသိမ်းထားသည်။ ထုတ်လုပ်မှုစနစ်များတွင် ၎င်းသည် ပိုမိုအရေးကြီးသည်။ -### ပုံစံ ၄: Tools များကို သီးခြား စမ်းသပ်ခြင်း +### ပုံစံ ၄: Tools များကို သီးခြားစမ်းသပ်ခြင်း -Tools များသည် AI ကခေါ်ယူသည့် function များဖြစ်သည်။ AI ဆုံးဖြတ်ချက်မလိုအပ်ဘဲ တိုက်ရိုက် စမ်းသပ်ခြင်းဖြင့် ကောင်းမွန်စွာလုပ်ဆောင်နေသော tool များဖြစ်ကြောင်း သေချာစေရန် ရည်ရွယ်သည်။ +Tools ဆိုသည်မှာ AI သုံးနိုင်သော function များဖြစ်သည်။ AI ဆုံးဖြတ်ချက်မလိုပဲ မျက်နှာတိုက်စမ်းသပ်မှုများပြုလုပ်ပါ။ Tools Testing -*AI မပါသော mock tool အကောင်အထည်ဖော်ခြင်းမှ စီးပွားရေး ဒေတာလုပ်ငန်းကိုစစ်ဆေးခြင်း* +*AI ခေါ်ဆိုမှုမရှိပဲ လုပ်ငန်းသဘောတရားများကို အတည်ပြုရန် mock tool များဖြင့် tools စမ်းသပ်ခြင်း* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ထဲမှ ဤစမ်းသပ်မှုများမှာ AI ပါဝင်ခြင်းမရှိဘဲ tool များ၏လုပ်ဆောင်မှုအဆင့်မြှင့်သုံးသပ်ပုံဖြစ်သည်။ ထို chaining ဥပမာသည် tool တစ်ခု၏ output သည် နောက် tool တစ်ခုရဲ့ input အဖြစ် အသုံးပြုသည်ကို ဖော်ပြသည်။ +ဤ စမ်းသပ်မှုများသည် `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` မှဖြစ်ပြီး AI ပါဝင်မှုမရှိဘဲ tool logic များကို စစ်ဆေးသည်။ chaining ပုံစံမှာ tool တစ်ခုထွက်ရှိသော ထွက်ရှိမှုကို နောက်တစ်ခုထဲ ထည့်သွင်းသည်ကို ပြသသည်။ ### ပုံစံ ၅: In-Memory RAG စမ်းသပ်ခြင်း -RAG စနစ်များသည် ပုံမှန်အားဖြင့် vector database နှင့် embedding service များ လိုအပ်သည်။ In-memory ပုံစံသည် အပြင်မဟုတ်သော ဆက်စပ်မှုများ မလိုအပ်ဘဲ စစ်ဆေးနိုင်ခြင်းကို ခွင့်ပြုသည်။ +RAG စနစ်များသည် ရောနှောသိမ်းဆည်းမှု ဒေတာဘေ့စ်များနှင့် embedding ဝန်ဆောင်မှုများလိုအပ်သည်။ In-memory ပုံစံဖြင့် အပြင်ဘက် မလိုအပ်ဘဲ pipeline အားလုံးကို စမ်းသပ်နိုင်သည်။ In-Memory RAG Testing -*စာရွက်စာတမ်း ဖြတ်တိုက်ခြင်း embedding သိုလှောင်မှုနှင့် ဆင်တူရှာဖွေမှုကို database မပါဘဲ ပြုလုပ်ခြင်း ပုံစံ* +*ဒေတာဘေ့စ် မလိုအပ်ပဲ စာရွက်စာတမ်း ဖတ်ထုတ်ခြင်း၊ embedding သိမ်းဆည်းခြင်းနှင့် သက်ဆိုင်ရာ ရှာဖွေမှုများ ပြုလုပ်နည်း စမ်းသပ်ခြင်း* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -ဤစမ်းသပ်မှုသည် `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` မှဖြစ်ပြီး memory တွင် စာရွက်စာတမ်းတည်ဆောက်ခြင်း၊ ခွဲခြမ်းခြင်းနှင့် မီတာဒေတာ ကို စစ်ဆေးသည်။ +ဤစမ်းသပ်မှုကို `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` တွင် တွေ့နိုင်ပြီး စာရွက်စာတမ်းတစ်စောင်ကို မှတ်ဉာဏ်ထဲတွင် ဖန်တီးကာ ချန်ကွတ်မှု နှင့် ပြည့်စုံမှုနှင့် metadata ကို အတည်ပြုသည်။ -### ပုံစံ ၆: MCP ပေါင်းစည်း စမ်းသပ်ခြင်း +### ပုံစံ ၆: MCP ပေါင်းစည်းစမ်းသပ်ခြင်း -MCP module သည် stdio transport ကို အသုံးပြု Model Context Protocol ပေါင်းစည်းခြင်း စမ်းသပ်မှုများ ဖြစ်သည်။ ဤစမ်းသပ်မှုများသည် MCP servers များကို subprocess အနေဖြင့်ဖန်တီးပြီး ဆက်သွယ်နိုင်ခြေရှိမှုကို အတည်ပြုသည်။ +MCP module သည် Model Context Protocol ပေါင်းစည်းမှုကို stdio ပို့ဆောင်မှုဖြင့် စမ်းသပ်သည်။ ဤစမ်းသပ်မှုများသည် သင့်အပလီကေးရှင်းသည် MCP server များကို subprocess အဖြစ် spawn ပြီး ဆက်သွယ်နိုင်မှုကို အတည်ပြုသည်။ -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` တွင် MCP client အပြုအမူကို စစ်ဆေးသည်။ +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` တွင် စမ်းသပ်မှုများရှိသည်။ -**စမ်းသပ်ရန်:** +**ရိုက်ထည့်ရန်:** **Bash:** ```bash @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## စမ်းသပ်မှု အယူအဆ +## စမ်းသပ်မှု နည်းဗျူဟာ -AI ကို မစမ်းသပ်ပါနဲ့၊ သင့်ကုဒ်ကို စမ်းသပ်ပါ။ သင့်စမ်းသပ်မှုများသည် prompt များ စတင်ဖန်တီးပုံ၊ မှတ်ဉာဏ် ကမ်းလှမ်းပုံနှင့် tools များ လုပ်ဆောင်မှုကို မှန်ကန်စွာ အသုံးပြုမှု အတည်ပြုရန် ရည်ရွယ်သည်။ AI ရဲ့ဖြေဆိုချက်များသည် မတည်ငြိမ်သည့် အချက်များဖြင့် စမ်းသပ်မှုများတွင် ပါဝင်သင့်ခြင်းမဟုတ်ပါ။ prompt template တွင် အစားထိုးမှုများ မွန်ကန်စွာဖြစ်သည်ဟု စစ်ဆေးပါ၊ AI မှ တုံ့ပြန်ချက် မှန်ကန်သည်ဟု မမေးပါနှင့်။ +AI ကိုမစမ်းသပ်ပါနဲ့၊ သင်ရေးသားထားသော code ကို စမ်းသပ်ပါ။ သင့်စမ်းသပ်မှုများသည် prompt များ ဘယ်လို ဖွဲ့စည်းထားသည်၊ မှတ်ဉာဏ်ကို မည်သို့ စီမံထားသည်၊ ကိရိယာများက ဘယ်လို လုပ်ဆောင်သည်ကို စစ်ဆေးခြင်းဖြင့် သင်ရေးသော code ကို တိုက်ရိုက်အတည်ပြုသင့်သည်။ AI ဖြေကြားမှုများက မတည်ငြိမ်ပြီး စမ်းသပ်မှု သတ်မှတ်ချက်၏ အပိုင်းမဖြစ်သင့်ပါ။ ၎င်း၏ prompt template သည် variable များကို မှန်ကန်စွာ ဖြည့်တင်းနိုင်မှုကိုသာ စစ်ဆေးပါ၊ AI မှ မှန်ကန်သောဖြေကြားချက်ရသည်ဟု မေးလိုက်ပါနှင့်။ -Language model များအတွက် mocks ကို အသုံးပြုပါ။ ဤကိစ္စများသည် ပင်မ အဆင့်သည် ငြင်းဆန်၊ အရမ်းကြီးသော ကုန်ကျစရိတ်ရှိသည်နှင့် ရလဒ် မတူညီနိုင်သော အပြင် ပျင်းရိစေပါသည်။ Mocking က စမ်းသပ်မှုများကို စက္ကန့်များ အစား မီလီစက္ကန့် အတွင်း အမြန်ဆုံး ပြုလုပ်နိုင်စေပြီး၊ အခမဲ့ဖြစ်စေပြီး၊ တစ်ကြိမ်တည်း ရလဒ်သန့်ရှင်းစေသည်။ +Language model များအတွက် mock များကို သုံးပါ။ ၎င်းတို့မှာ အပြင်ဘက်ရင်းမြစ်များဖြစ်ပြီး နှေးကာ၊ စျေးကြီးကာ၊ သတ်မှတ်နိုင်မှု မရှိပါ။ Mocking သည် စမ်းသပ်မှုများသို့မဟုတ် စက္ကန့်အစား မီလီစက္ကန့်အတွင်း မြန်ဆန်စေပြီး၊ အခမဲ့ဖြစ်ကာ၊ တစ်ကြိမ်တိုင်း အတူတူရလဒ် ပေးနိုင်စေသည်။ -စမ်းသပ်မှုများကို လွတ်လပ်နေသည်စေပါ။ စမ်းသပ်မှု တစ်ခုချင်းစီသည် မိမိအချက်အလက်ကို သီးသန့်ပြင်ဆင်ပြီး၊ အခြား စမ်းသပ်မှုများကို မူတည်ခြင်းမရှိဘဲ ပြုလုပ်ရန်နှင့် ပြီးနောက် ကိုယ်ပိုင် သန့်ရှင်းမှု လုပ်သင့်သည်။ စမ်းသပ်မှုများသည် လည်ပတ်မှု အတွ Reihenfolge ဖျက်ပစ်ခြင်းမရှိဘဲ အောင်မြင်ရမည်။ +စမ်းသပ်မှုများကို သီးခြားထားပါ။ တစ်ခုချင်းစမ်းသပ်မှုသည် ကိုယ်ပိုင် data ကို ပြင်ဆင်ပြီး၊ အခြားစမ်းသပ်မှုများ မပေါ်တွင် အခြေခံခြင်းမရှိဘဲ၊ ကိုယ်တိုင် ပြင်ဆင်ပြီး ပြီးနောက် ရှင်းလင်းသင့်သည်။ စမ်းသပ်မှုများသည် လုပ်ဆောင်မှု အ ဆင့်လျော်ခြင်းမရှိပဲ အောင်မြင်သင့်သည်။ -ပျော်မွေ့မှု လမ်းကြောင်း မကျော်လွှားသော အခြေအနေများကို စမ်းသပ်ပါ။ ပျက်စီးသော input များ၊ အလွန်ကြီးသော input များ၊ အထူးသဏ္ဍာန်များ၊ မမှန်ကန်သော ပါရာမီတာများ နှင့် အကန့်အသတ် အခြေအနေများ ကို စမ်းသပ်ပါ။ ဤအခြေအနေများမှာ မကြာခဏအဖောင်းပိုက်များကို ဖော်ထုတ်ပေးသည်။ +စမ်းသပ်မှုများကို "happy path" ကျော်လွန် ပိုမို အပိုင်းခွဲစမ်းသပ်ပါ။ ဝင်ရိုးအချင်းအဆက် မရှိ၊ အလွန်ကြီးမားသော input များ၊ အထူးလက္ခဏာများ၊ မှားနေတာ parameter များနှင့် နယ်နိမိတ် အခြေအနေများကို စမ်းသပ်ပါ။ အများအားဖြင့် ၎င်းတို့သည် ပုံမှန်အသုံးပြုမှုတွင် မတွေ့ရသည့် အမှားများကို ဖော်ထုတ်ပေးပါသည်။ -ဖော်ပြချက် နာမည်များ အသုံးပြုပါ။ `shouldMaintainConversationHistoryAcrossMultipleMessages()` နှင့် `test1()` ကို နှိုင်းယှဉ်ပါ။ ပထမအချက်သည် သတ်မှတ်ထားသည့် စမ်းသပ်မှုအကြောင်းကို တိတိကျကျ ဖော်ပြပေးကာ ပြန်လည်စစ်ဆေးရာတွင် ပိုမိုလွယ်ကူစေသည်။ +ဖော်ပြချက်အမည်များကို အသုံးပြုပါ။ `shouldMaintainConversationHistoryAcrossMultipleMessages()` နှင့် `test1()` ကို နှိုင်းယှဥ်ကြည့်ပါ။ ပထမဆုံးမှာ အသေးစိတ် စမ်းသပ်မှုအကြောင်းကို ပြောပြသည့်အတွက် မျှတစွာ အမှားပြေရှင်းရလွယ်ကူသည်။ -## နောက်တစ်ဆင့် +## နောက်ဆုံး လှုပ်ရှားမှုများ -စမ်းသပ်မှုပုံစံများကို နားလည်ပြီးနောက် အုပ်စုတစ်ခုချင်းစီရှင်းလင်းစွာ လေ့လာပါ။ +စမ်းသပ်မှု ပုံစံများကို နားလည်သွားပါက၊ အောက်ပါ module တစ်ခုချင်းစီကို ပိုမို ကျယ်ကျယ်ပြန့်ပြန့် လေ့လာပါ။ -- **[00 - Quick Start](../00-quick-start/README.md)** - Prompt template အခြေခံများဖြင့် စတင်ပါ -- **[01 - Introduction](../01-introduction/README.md)** - စကားပြောမှတ်ဉာဏ် စီမံခန့်ခွဲမှု သင်ယူပါ -- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - GPT-5.2 prompt patterns ကိုကျွမ်းကျင်ပါ -- **[03 - RAG](../03-rag/README.md)** - Retrieval-augmented generation စနစ်များ တည်ဆောက်ပါ -- **[04 - Tools](../04-tools/README.md)** - ဖွင့်ဆိုမှုနှင့် ကိရိယာလိုက်လိုက်မှု ကို တည်ဆောက်ပါ -- **[05 - MCP](../05-mcp/README.md)** - Model Context Protocol ပေါင်းစပ်ပါ +- **[01 - နိဒါန်း](../01-introduction/README.md)** - စကားပြောမှတ်ဉာဏ် စီမံခန့်ခွဲမှု သင်ယူပါ +- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - GPT-5.2 prompt ပုံစံများ ကျွမ်းကျင်ပါ +- **[03 - RAG](../03-rag/README.md)** - retrieval-augmented generation စနစ်များ တည်ဆောက်ပါ +- **[04 - Tools](../04-tools/README.md)** - function calling နှင့် tool chaining ကို အကောင်အထည် ဖော်ပါ +- **[05 - MCP](../05-mcp/README.md)** - Model Context Protocol ပေါင်းစည်းမှု -အုပ်စုတိုင်း၏ README တွင် ဤတွင် စမ်းသပ်ထားသည့် အယူအဆအသေးစိတ်ကို ဖော်ပြထားသည်။ +တစ်ခုချင်း စာမျက်နှာများတွင် ယင်းတို့တွင် စမ်းသပ်မှု ပညာရပ်များကို အသေးစိတ် ရှင်းလင်းထားပါသည်။ --- -**လမ်းညွှန်:** [← နောက်သို့](../README.md) +**လမ်းညွှန်မှု:** [← နောက်သို့ သွားရန်](../README.md) --- -**အချက်ပြချက်** -ဤစာရွက်ကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) ဖြင့် ဘာသာပြန်ထားပါသည်။ တိကျမှုအတွက် ကြိုးစားသည်ဖြစ်သော်လည်း ကွန်ပျူတာအလိုအလျောက် ဘာသာပြန်ချက်များတွင် အမှားများ သို့မဟုတ် မှန်ကန်မှုမရှိမှုများ ဖြစ်ပေါ်နိုင်ကြောင်း သတိပြုပါရန် လိုအပ်ပါသည်။ မူရင်းစာရွက်ကို ဒေသဆိုင်ရာဘာသာဖြင့်သာ တရားဝင်အရင်းအမြစ်အဖြစ် ယူဆရန် ပိုမို အရေးကြီးပါသည်။ အရေးကြီးသော အချက်အလက်များအတွက် လူ့ဘာသာပြန်ပညာရှင်ဖြင့် ဘာသာပြန်ခြင်းကို အကြံပြုပါသည်။ ဤဘာသာပြန်ချက်ကို အသုံးပြုရာမှ ဖြစ်ပေါ်သော နားလည်မှုမှားခြင်းများ သို့မဟုတ် မှားဖတ်ခြင်းများအတွက် ကျွန်ုပ်တို့ တာဝန်မခံပါ။ +**ပြောကြားချက်** +ဤစာတမ်းကို AI ဘာသာပြန်ဝန်ဆောင်မှု [Co-op Translator](https://github.com/Azure/co-op-translator) အသုံးပြု၍ ဘာသာပြန်ထားပါသည်။ ကျွန်ုပ်တို့သည် တိကျမှန်ကန်မှုအတွက် ကြိုးပမ်းနေသော်လည်း၊ စက်ကိရိယာဘာသာပြန်ခြင်းများတွင် အမှားများ သို့မဟုတ် မှားယွင်းချက်များ ပါဝင်နိုင်ကြောင်း သတိပြုပါရန် လိုအပ်ပါသည်။ မူလစာတမ်းကို မူရင်းဘာသာဖြင့်သာ ယုံကြည်စိတ်ချရသော အချက်အလက်အဖြစ် သတ်မှတ်သင့်သည်။ အရေးကြီးသည့် သတင်းအချက်အလက်များအတွက် ပရော်ဖက်ရှင်နယ် လူသားဘာသာပြန်သူဝန်ဆောင်မှုကို အကြံပြုပါသည်။ ဤဘာသာပြန်ချက်ကို အသုံးပြုခြင်းမှ ဖြစ်ပေါ်လာသော နားလည်မှုကွာခြားမှုများ သို့မဟုတ် မမှန်ကန်သော အသုံးပြုမှုများအတွက် ကျွန်ုပ်တို့ တာဝန်မခံပါ။ \ No newline at end of file diff --git a/translations/ne/.co-op-translator.json b/translations/ne/.co-op-translator.json index 395a6d78b..69e0240c6 100644 --- a/translations/ne/.co-op-translator.json +++ b/translations/ne/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ne" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T21:17:27+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T13:23:12+00:00", "source_file": "01-introduction/README.md", "language_code": "ne" }, @@ -18,20 +18,20 @@ "language_code": "ne" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T21:20:31+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T13:17:41+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ne" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T21:22:30+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T13:22:12+00:00", "source_file": "03-rag/README.md", "language_code": "ne" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:08:38+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T13:20:36+00:00", "source_file": "04-tools/README.md", "language_code": "ne" }, @@ -54,8 +54,8 @@ "language_code": "ne" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:48:46+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T13:16:02+00:00", "source_file": "README.md", "language_code": "ne" }, @@ -72,14 +72,14 @@ "language_code": "ne" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T21:26:57+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T13:18:22+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ne" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T21:27:48+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T13:19:07+00:00", "source_file": "docs/TESTING.md", "language_code": "ne" } diff --git a/translations/ne/00-quick-start/README.md b/translations/ne/00-quick-start/README.md deleted file mode 100644 index f24ee5ece..000000000 --- a/translations/ne/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# मोड्युल 00: छिटो सुरु - -## सामग्री तालिका - -- [परिचय](../../../00-quick-start) -- [LangChain4j के हो?](../../../00-quick-start) -- [LangChain4j निर्भरता](../../../00-quick-start) -- [आवश्यकताहरू](../../../00-quick-start) -- [सेटअप](../../../00-quick-start) - - [1. आफ्नो GitHub टोकन प्राप्त गर्नुहोस्](../../../00-quick-start) - - [2. आफ्नो टोकन सेट गर्नुहोस्](../../../00-quick-start) -- [उदाहरणहरू चलाउनुहोस्](../../../00-quick-start) - - [1. आधारभूत कुरा](../../../00-quick-start) - - [2. प्रॉम्प्ट ढाँचा](../../../00-quick-start) - - [3. फंक्शन कलिङ](../../../00-quick-start) - - [4. कागजात प्रश्नोत्तर (Easy RAG)](../../../00-quick-start) - - [5. जिम्मेवार AI](../../../00-quick-start) -- [हरेक उदाहरणले के देखाउँछ](../../../00-quick-start) -- [अर्को कदमहरू](../../../00-quick-start) -- [समस्या समाधान](../../../00-quick-start) - -## परिचय - -यो छिटो सुरु तपाईंलाई LangChain4j सँग छिटो काम सुरु गर्नका लागि बनाइएको हो। यसले LangChain4j र GitHub मोडलहरूसँग AI अनुप्रयोगहरू निर्माण गर्ने आधारभूत कुराहरू समेट्छ। अर्को मोड्युलहरूमा तपाईं Azure OpenAI र GPT-5.2 मा स्विच गर्नुहुनेछ र प्रत्येक अवधारणामा गहिराइमा जानुहुनेछ। - -## LangChain4j के हो? - -LangChain4j एक जाभा लाइब्रेरी हो जसले AI चलित अनुप्रयोगहरू बनाउन सजिलो बनाउँछ। HTTP क्लाइन्ट र JSON पार्सिङ गर्नुपर्ने ठाउँमा तपाईं सफा जाभा API हरूसँग काम गर्नुहुन्छ। - -LangChain मा "चेन" ले धेरै कम्पोनेन्टहरू जोड्ने प्रक्रिया जनाउँछ - तपाईं एउटा प्रॉम्प्टलाई मोडलमा, त्यसपछि पार्सरमा जोड्न सक्नुहुन्छ, वा धेरै AI कलहरूलाई एकआपसमा श्रृंखलाबद्ध गर्न सक्नुहुन्छ जहाँ एउटा आउटपुट अर्को इनपुटमा जान्छ। यो छिटो सुरु आधारभूत कुरामा केन्द्रित छ र जटिल श्रृंखलाहरू अन्वेषण गर्नु अघि। - -LangChain4j Chaining Concept - -*LangChain4j मा कम्पोनेन्टहरू श्रृंखला - निर्माण ब्लकहरूलाई जोडेर शक्तिशाली AI वर्कफ्लोहरू सिर्जना* - -हामी तीन मुख्य कम्पोनेन्टहरू प्रयोग गर्नेछौं: - -**ChatModel** - AI मोडलसँग अन्तरक्रिया गर्ने इन्टरफेस। `model.chat("prompt")` कल गरेर प्रतिक्रिया स्ट्रिङ प्राप्त गर्नुहोस्। हामी `OpenAiOfficialChatModel` प्रयोग गर्छौं जुन OpenAI-अनुकूल API अन्तर्वर्तीहरूसँग काम गर्छ जस्तै GitHub Models। - -**AiServices** - प्रकार-सुरक्षित AI सेवा इन्टरफेसहरू सिर्जना गर्छ। मेथडहरू परिभाषित गर्नुहोस्, तिनीहरूलाई `@Tool` ले एनोटेट गर्नुहोस् र LangChain4j सञ्चालन सम्हाल्छ। आवश्यक पर्दा AI ले तपाईंका Java मेथडहरू स्वचालित रूपमा कल गर्छ। - -**MessageWindowChatMemory** - संवाद इतिहास राख्छ। यसको बिना, प्रत्येक अनुरोध स्वतन्त्र हुन्छ। यसको साथमा, AI ले पहिलेका सन्देशहरू सम्झन्छ र धेरै पटकको कुराकानीमा सन्दर्भ कायम राख्छ। - -LangChain4j Architecture - -*LangChain4j संरचना - मुख्य कम्पोनेन्टहरू मिलेर तपाईंको AI अनुप्रयोगहरूलाई शक्ति दिँदै* - -## LangChain4j निर्भरता - -यो छिटो शुरू [`pom.xml`](../../../00-quick-start/pom.xml) मा तीन Maven निर्भरता प्रयोग गर्दछ: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` मोड्युल `OpenAiOfficialChatModel` वर्ग प्रदान गर्छ जुन OpenAI अनुकूल API सँग जडान गर्छ। GitHub Models ले त्यहि API ढाँचा प्रयोग गर्दछ, त्यसैले कुनै विशेष एडाप्टर आवश्यक छैन - मात्र बेस URL लाई `https://models.github.ai/inference` मा सेट गर्नुहोस्। - -`langchain4j-easy-rag` मोड्युलले स्वचालित रूपमा कागजात छुट्याउने, एम्बेड गर्ने, र पुनःप्राप्ति गर्ने सुविधा दिन्छ ताकि तपाईं RAG अनुप्रयोगहरू म्यानुअली सेट अप नगरी बनाउन सक्नुहुन्छ। - -## आवश्यकताहरू - -**डेभ कन्टेनर प्रयोग गर्दै हुनुहुन्छ?** Java र Maven पहिले नै स्थापना गरिएको छ। तपाईंलाई केवल GitHub Personal Access Token चाहिए। - -**स्थानीय विकास:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (निर्देश तल) - -> **ध्यान दिनुहोस्:** यो मोड्युलले GitHub Models बाट `gpt-4.1-nano` प्रयोग गर्छ। कोडमा मोडल नाममा परिवर्तन नगर्नुहोस् - यो GitHub को उपलब्ध मोडलहरूसँग काम गर्न कन्फिगर गरिएको छ। - -## सेटअप - -### 1. आफ्नो GitHub टोकन प्राप्त गर्नुहोस् - -1. [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) मा जानुहोस् -2. "Generate new token" मा क्लिक गर्नुहोस् -3. वर्णनात्मक नाम दिनुहोस् (जस्तै, "LangChain4j Demo") -4. समाप्ति अवधि सेट गर्नुहोस् (७ दिन सिफारिस गरिएको) -5. "Account permissions" अन्तर्गत "Models" खोज्नुहोस् र "Read-only" मा सेट गर्नुहोस् -6. "Generate token" मा क्लिक गर्नुहोस् -7. टोकन कपी गरी सुरक्षित राख्नुहोस् - यसलाई फेरि हेर्न सकिन्न - -### 2. आफ्नो टोकन सेट गर्नुहोस् - -**विकल्प 1: VS Code प्रयोग गर्दै (सिफारिस गरिएको)** - -यदि तपाईं VS Code प्रयोग गर्दै हुनुहुन्छ भने, आफ्नो टोकन परियोजना मूलमा `.env` फाइलमा राख्नुहोस्: - -यदि `.env` फाइल छैन भने, `.env.example` बाट `.env` मा कपी गर्नुहोस् वा नयाँ `.env` फाइल सिर्जना गर्नुहोस्। - -**उदाहरण `.env` फाइल:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env मा -GITHUB_TOKEN=your_token_here -``` - -त्यसपछि तपाईं कुनै पनि डेमो फाइल (जस्तै, `BasicChatDemo.java`) मा राइट-क्लिक गरी **"Run Java"** चयन गर्न सक्नुहुन्छ वा Run र Debug प्यानलबाट लन्च कन्फिगरेसन प्रयोग गर्न सक्नुहुन्छ। - -**विकल्प 2: टर्मिनल प्रयोग गर्दै** - -टोकनलाई वातावरण चर रूपमा सेट गर्नुहोस्: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## उदाहरणहरू चलाउनुहोस् - -**VS Code प्रयोग गरी:** कुनै पनि डेमो फाइलमा राइट-क्लिक गरी **"Run Java"** चयन गर्नुहोस्, वा Run र Debug प्यानलबाट लन्च कन्फिगरेसन प्रयोग गर्नुहोस् (पहिले `.env` फाइलमा टोकन थपिएको हुनुपर्छ)। - -**Maven प्रयोग गरी:** वा तपाईं कमाण्ड लाइनबाट चलाउन सक्नुहुन्छ: - -### 1. आधारभूत कुरा - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. प्रॉम्प्ट ढाँचा - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -जिरो-शट, फ्यु-शट, चेन-ऑफ-थट र रोल-आधारित प्रॉम्प्टिङ देखाउँछ। - -### 3. फंक्शन कलिङ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI आवश्यक पर्दा स्वचालित रूपमा तपाईंका Java मेथडहरू कल गर्छ। - -### 4. कागजात प्रश्नोत्तर (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Easy RAG प्रयोग गरेर तपाईंका कागजातहरूको बारेमा प्रश्न सोध्नुहोस् - स्वचालित एम्बेडिङ र पुनःप्राप्ति सहित। - -### 5. जिम्मेवार AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -AI सुरक्षा फिल्टरहरूले हानिकारक सामग्री कसरी रोक्छन् हेर्नुहोस्। - -## हरेक उदाहरणले के देखाउँछ - -**आधारभूत कुरा** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -यहाँबाट सुरु गर्नुहोस् र LangChain4j को आधारभूत परिचय पाउनुहोस्। तपाईं `OpenAiOfficialChatModel` सिर्जना गर्नुहुनेछ, `.chat()` मार्फत प्रॉम्प्ट पठाउनुहुनेछ, र प्रतिक्रिया पाउनुहुनेछ। यसले आधारभूत कुरा देखाउँछ: कसरी कस्टम अन्तर्वर्ती र API कुञ्जीहरूसँग मोडल आरम्भ गर्ने। जब तपाईं यो प्रक्रिया बुझ्नुहुन्छ, बाँकी सबै त्यही आधारमा निर्माण हुन्छ। - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 GitHub Copilot संग प्रयास गर्नुहोस्:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) खोल्नुहोस् र सोध्नुहोस्: -> - "यस कोडमा GitHub Models बाट Azure OpenAI मा कसरि स्विच गर्ने?" -> - "OpenAiOfficialChatModel.builder() मा अरु के-के प्यारामिटरहरू सेट गर्न सकिन्छ?" -> - "पूर्ण प्रतिक्रिया कुर्नुको सट्टा स्ट्रीमिङ प्रतिक्रिया कसरी थप्ने?" - -**प्रॉम्प्ट इन्जिनियरिङ** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -अब तपाईं मोडलसँग कसरी कुरा गर्ने बुझ्नुभएपछि, हामी हेर्ने छौं के तपाईं मोडललाई भन्नुहुन्छ। यो डेमोले तिनै मोडल सेटअप प्रयोग गरेर पाँच फरक प्रॉम्प्ट ढाँचाहरू देखाउँछ। सिधा निर्देशनका लागि जिरो-शट प्रॉम्प्ट, उदाहरणबाट सिक्न फ्यु-शट, कारण देखाउने चेन-ऑफ-थट, र सन्दर्भ सेट गर्ने रोल-आधारित प्रॉम्प्ट प्रयास गर्नुहोस्। तपाईं देख्नुहुनेछ कि एउटै मोडलले अनुरोध राख्ने तरिकामा धेरै भिन्न नतिजा दिन्छ। - -डेमोले प्रॉम्प्ट टेम्प्लेटहरू पनि देखाउँछ, जुन चलायमान भेरिएबलहरू सहित पुन: प्रयोग गर्न मिल्ने प्रॉम्प्टहरू बनाउने शक्तिशाली विधि हो। -तलको उदाहरणले LangChain4j `PromptTemplate` प्रयोग गरेर भेरिएबलहरू भर्ने तरिका देखाउँछ। AI ले दिएका गन्तव्य र गतिविधिको आधारमा उत्तर दिन्छ। - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 GitHub Copilot सँग प्रयास गर्नुहोस्:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) खोल्नुहोस् र सोध्नुहोस्: -> - "जिरो-शट र फ्यु-शट प्रॉम्प्टिङमा के फरक छ र कुन बेला कुन प्रयोग गर्ने?" -> - "मोडलका प्रतिक्रियामा तापक्रम प्यारामिटरले कसरि असर गर्छ?" -> - "उत्पादनमा प्रॉम्प्ट इन्जेक्सन आक्रमण रोक्न के-के प्रविधिहरू छन्?" -> - "साझा प्रॉम्प्ट ढाँचाहरूका लागि कसरी पुन: प्रयोगयोग्य PromptTemplate वस्तुहरू बनाउन सकिन्छ?" - -**टूल एकीकरण** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -यहाँ LangChain4j शक्ति देखाइन्छ। तपाईं `AiServices` प्रयोग गरेर यस्तो AI सहायक बनाउन सक्नुहुन्छ जसले तपाईंका Java मेथडहरू कल गर्न सक्छ। मेथडहरूलाई `@Tool("description")` ले एनोटेट गर्नुहोस् र बाँकी LangChain4j ले सँभाल्छ - AI प्रयोगकर्ताले के सोध्छन् अनुसार कुन टूल प्रयोग गर्ने निर्णय स्वतः गर्छ। यसले फंक्शन कलिङ देखाउँछ, जुन AI लाई क्रियाकलाप गर्न सक्षम बनाउने मुख्य प्रविधि हो, मात्र प्रश्नको उत्तर दिन मात्र होइन। - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 GitHub Copilot सँग प्रयास गर्नुहोस्:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) खोल्नुहोस् र सोध्नुहोस्: -> - "@Tool एनोटेशन कसरी काम गर्छ र LangChain4j ले यसलाई पछाडि कसरी ह्यान्डल गर्छ?" -> - "के AI ले जटिल समस्याहरू समाधान गर्न धेरै टूलहरू अनुक्रममा कल गर्न सक्छ?" -> - "यदि कुनै टूलले अपवाद फ्याँक्छ भने के हुन्छ - त्रुटिहरू कसरी ह्यान्डल गर्ने?" -> - "यस क्याल्कुलेटर उदाहरणको सट्टा वास्तविक API कसरी एकीकृत गर्ने?" - -**कागजात प्रश्नोत्तर (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -यहाँ LangChain4j को "Easy RAG" विधि प्रयोग गरेर RAG (retrieval-augmented generation) देख्नुहुनेछ। कागजातहरू लोड गरिन्छ, स्वचालित रूपमा भागमा विभाजित हुँदै इन-मेमोरी स्टोरमा एम्बेड गरिन्छ, अनि सामग्री पुनःप्राप्तिकर्ता सोधपुछको समयमा AI लाई सान्दर्भिक भागहरू आपूर्ति गर्छ। AI तपाईंका कागजातहरूमा आधारित जवाफ दिन्छ, सामान्य ज्ञानमा होइन। - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 GitHub Copilot सँग प्रयास गर्नुहोस्:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) खोल्नुहोस् र सोध्नुहोस्: -> - "RAG ले मोडलको तालिम डाटाको सट्टा AI भ्रमलाई कसरी रोक्छ?" -> - "यस सजिलो विधि र कस्टम RAG पाइपलाइनमा के फरक छ?" -> - "धेरै कागजातहरू वा ठूलो ज्ञान आधारको लागि यसलाई कसरी मापन गर्ने?" - -**जिम्मेवार AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -सुरक्षा मा गहिराइ सहित AI सुरक्षा बनाउनुहोस्। यो डेमोले दुई तहको सुरक्षात्मक उपायहरू देखाउँछ: - -**भाग 1: LangChain4j इनपुट गार्डरेल्स** - खतरनाक प्रॉम्प्टहरूलाई LLM मा पुग्नु अघि रोक्नुहोस्। प्रतिबन्धित कीवर्ड वा ढाँचाहरू जाँच गर्न कस्टम गार्डरेलहरू बनाउनुहोस्। यी तपाईंको कोडमा चल्छन्, त्यसैले छिटो र निःशुल्क छन्। - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**भाग 2: प्रदायक सुरक्षा फिल्टरहरू** - GitHub Models मा निर्मित फिल्टरहरू छन् जसले तपाईंको गार्डरेलहरूले छुटाउन सक्ने कुराहरू समात्छ। तपाईं कडाइका कारण कडा ब्लकहरू (HTTP 400 त्रुटिहरू) र नम्र अस्वीकृतिहरू जहाँ AI विनम्रतापूर्वक अस्वीकार्छ, दुवै देख्नुहुनेछ। - -> **🤖 GitHub Copilot सँग प्रयास गर्नुहोस्:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) खोल्नुहोस् र सोध्नुहोस्: -> - "InputGuardrail के हो र म कसरी आफ्नो बनाउने?" -> - "कडा ब्लक र नम्र अस्वीकृतिमा के फरक छ?" -> - "किन दुवै गार्डरेल र प्रदायक फिल्टर एकसाथ प्रयोग गर्ने?" - -## अर्को कदमहरू - -**अर्को मोड्युल:** [01-परिचय - LangChain4j सँग सुरु](../01-introduction/README.md) - ---- - -**नेभिगेसन:** [← मुख्य पृष्ठमा फर्कनुहोस्](../README.md) | [अर्को: मोड्युल 01 - परिचय →](../01-introduction/README.md) - ---- - -## समस्या समाधान - -### पहिलोपटक Maven बिल्ड - -**समस्या:** प्रारम्भिक `mvn clean compile` वा `mvn package` धेरै समय लिन्छ (१०-१५ मिनेट) - -**कारण:** Maven ले पहिलोपटक सबै परियोजना निर्भरता (Spring Boot, LangChain4j लाइब्रेरीहरू, Azure SDKs, आदि) डाउनलोड गर्नुपर्छ। - -**समाधान:** यो सामान्य हुन्छ। अर्को बिल्डहरू धेरै छिटो हुनेछ, किनभने निर्भरता स्थानीय रूपमा क्यास हुन्छन्। डाउनलोड समय तपाईंको इन्टरनेट स्पीडमा निर्भर गर्दछ। - -### PowerShell Maven कमाण्ड सिन्ट्याक्स - -**समस्या:** Maven कमाण्डहरूले `Unknown lifecycle phase ".mainClass=..."` त्रुटि दिन्छ। -**कारण**: PowerShell ले `=` लाई भेरिएबल असाइनमेन्ट अपरेटरको रूपमा व्याख्या गर्छ, जसले Maven प्रोपर्टी सिन्ट्याक्सलाई तोड्छ - -**समाधान**: Maven कमाण्ड अघि स्टप-पार्सिङ अपरेटर `--%` प्रयोग गर्नुहोस्: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` अपरेटरले PowerShell लाई बाँकी सबै आर्गुमेन्टहरू Maven लाइ उद्धृत नगरिकन सिधा पास गर्न निर्देशन दिन्छ। - -### Windows PowerShell इमोजी प्रदर्शन - -**समस्या**: PowerShell मा AI प्रतिक्रियाहरूमा इमोजीको सट्टा बेकार पात्रहरू (जस्तै `????` वा `â??`) देखिन्छ - -**कारण**: PowerShell को डिफल्ट एन्कोडिङ UTF-8 इमोजी समर्थन गर्दैन - -**समाधान**: Java एप्लिकेसनहरू चलाउन अघिल्लो यो कमाण्ड चलाउनुहोस्: -```cmd -chcp 65001 -``` - -यसले टर्मिनलमा UTF-8 एन्कोडिङ बलियो बनाउँछ। विकल्पका रूपमा, Windows Terminal प्रयोग गर्नुहोस् जुन राम्रो युनिकोड समर्थन छ। - -### API कलहरू डिबग गर्ने - -**समस्या**: प्रमाणिकरण त्रुटिहरू, रेट लिमिटहरू, वा AI मोडलबाट अप्रत्याशित प्रतिक्रिया - -**समाधान**: उदाहरणहरूमा `.logRequests(true)` र `.logResponses(true)` समावेश छन् जसले कन्सोलमा API कलहरू देखाउँछ। यसले प्रमाणिकरण त्रुटि, रेट लिमिट, वा अप्रत्याशित प्रतिक्रियाहरू ट्रबलशूट गर्न मद्दत गर्छ। उत्पादनमा यी फ्ल्यागहरू हटाएर लगिङ आवाज कम गर्न सकिन्छ। - ---- - - -**अस्वीकरण**: -यस दस्तावेजलाई AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरी अनुवाद गरिएको हो। हामी शुद्धताका लागि प्रयासरत छौं भने पनि, कृपया बुझ्नुहोस् कि स्वचालित अनुवादहरूमा त्रुटि वा असत्यता हुन सक्छ। मूल दस्तावेज यसको स्वदेशी भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलत बुझाइ वा गलत व्याख्याप्रति हामी जिम्मेवार छैनौं। - \ No newline at end of file diff --git a/translations/ne/01-introduction/README.md b/translations/ne/01-introduction/README.md index 68bc2f78d..48be610fb 100644 --- a/translations/ne/01-introduction/README.md +++ b/translations/ne/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j सँग सुरूवात गर्ने +# मोड्युल ०१: LangChain4j सँग सुरु गर्दै -## सामग्री सूचि +## सामग्री तालिका -- [भिडियो वाकथ्रू](../../../01-introduction) -- [तपाईंले के सिक्नुहुनेछ](../../../01-introduction) -- [पूर्वआवश्यकताहरू](../../../01-introduction) -- [मुख्य समस्यालाई बुझ्नुहोस्](../../../01-introduction) -- [टोकनहरू बुझ्नुहोस्](../../../01-introduction) -- [मेमोरी कसरी काम गर्छ](../../../01-introduction) -- [यसले LangChain4j कसरी प्रयोग गर्छ](../../../01-introduction) -- [Azure OpenAI पूर्वाधार परिनियोजन गर्नुहोस्](../../../01-introduction) -- [एप्लिकेशन स्थानीय रूपमा चलाउनुहोस्](../../../01-introduction) -- [एप्लिकेशन प्रयोग गर्दै](../../../01-introduction) - - [Stateless Chat (बायाँ प्यानल)](../../../01-introduction) - - [Stateful Chat (दायाँ प्यानल)](../../../01-introduction) -- [अर्को कदमहरू](../../../01-introduction) +- [भिडियो वाकथ्रु](#भिडियो-वाकथ्रु) +- [तपाईंले के सिक्नुहुनेछ](#तपाईंले-के-सिक्नुहुनेछ) +- [अग्रिम आवश्यकताहरू](#अग्रिम-आवश्यकताहरू) +- [मुख्य समस्यालाई बुझ्दै](#मुख्य-समस्यालाई-बुझ्दै) +- [टोकनहरू बुझ्दै](#टोकनहरू-बुझ्दै) +- [मेमोरी कसरी काम गर्छ](#मेमोरी-कसरी-काम-गर्छ) +- [यसले LangChain4j कसरी प्रयोग गर्छ](#यसले-langchain4j-कसरी-प्रयोग-गर्छ) +- [Azure OpenAI पूर्वाधार डिप्लोय गर्नुहोस्](#azure-openai-पूर्वाधार-डिप्लोय-गर्नुहोस्) +- [एप्लिकेशन स्थानीय रूपमा चलाउनुहोस्](#एप्लिकेशन-स्थानीय-रूपमा-चलाउनुहोस्) +- [एप्लिकेशन प्रयोग गर्दै](#एप्लिकेशन-प्रयोग-गर्दै) + - [स्टेटलेस च्याट (बायाँ प्यानल)](#स्टेटलेस-च्याट-बायाँ-प्यानल) + - [स्टेटफुल च्याट (दायाँ प्यानल)](#स्टेटफुल-च्याट-दायाँ-प्यानल) +- [अगला कदमहरू](#अगला-कदमहरू) -## भिडियो वाकथ्रू +## भिडियो वाकथ्रु -यो प्रत्यक्ष सत्र हेरौं जसले यस मोड्युलसँग कसरी सुरु गर्ने व्याख्या गर्दछ: +यो जीवन्त सत्र हेर्नुहोस् जसले यस मोड्युलसँग कसरी सुरु गर्ने बताउँछ: Getting Started with LangChain4j - Live Session ## तपाईंले के सिक्नुहुनेछ -छिटो शुरुवातमा, तपाईंले GitHub मोडेलहरूको प्रयोग गरेर प्रॉम्प्ट पठाउन, उपकरणहरू कल गर्न, RAG पाइपलाइन बनाउने र गार्डरिल परीक्षण गर्नुभयो। ती डेमोले सम्भावनाहरू देखाए — अब हामी Azure OpenAI र GPT-5.2 मा सर्न्छौं र उत्पादन-शैली एप्लिकेशनहरू बनाउन थाल्छौं। यो मोड्युलले तदारुकता र राज्य कायम राख्ने संवादात्मक AI मा केन्द्रित छ — ती अवधारणाहरू जुन ती छिटो शुरुवात डेमोहरूले पर्दा पछाडि प्रयोग गरे तर व्याख्या गरेनन्। +यो LangChain4j र Azure OpenAI सँग तपाईंको सुरुवाती बिन्दु हो। हामी आधारभूत कुराहरूबाट सुरु गर्छौं र उत्पादन-शैलीका अनुप्रयोगहरू निर्माण गर्न थाल्छौं। यो मोड्युल सन्दर्भ सम्झने र स्थिति कायम राख्ने संवादात्मक AI मा केन्द्रित छ — प्रत्येक पछि आएका मोड्युलले उभिएको आधारभूत अवधारणा। -हामी यस गाइडभरि Azure OpenAI को GPT-5.2 प्रयोग गर्नेछौं किनभने यसको उन्नत तर्क क्षमताले विभिन्न ढाँचाहरूको व्यवहार स्पष्ट बनाउँछ। जब तपाईं मेमोरी थप्नुहुन्छ, तपाईंले फरक स्पष्ट देख्नुहुनेछ। यसले तपाईंको एप्लिकेशनमा प्रत्येक कम्पोनेन्ट के ल्याउँछ बुझ्न सजिलो बनाउँछ। +हामी यस मार्गदर्शनमा Azure OpenAI को GPT-5.2 प्रयोग गर्नेछौं किनकि यसको उन्नत तर्क क्षमताहरूले विभिन्न ढाँचाहरूको व्यवहार स्पष्ट बनाउँछन्। जब तपाईंले मेमोरी थप्नुहुन्छ, तपाईंलाई फरक स्पष्ट देखिनेछ। यसले तपाईंको अनुप्रयोगमा प्रत्येक कम्पोनेन्ट के ल्याउँछ बुझ्न सजिलो बनाउँछ। -तपाईं एक एप्लिकेशन बनाउनुहुनेछ जसले दुवै ढाँचाहरू देखाउँछ: +तपाईंले एउटा अनुप्रयोग निर्माण गर्नु हुनेछ जुन दुवै ढाँचाहरू देखाउँछ: -**Stateless Chat** - हरेक अनुरोध स्वतन्त्र हुन्छ। मोडेलले अघिल्लो सन्देशहरूको कुनै मेमोरी राख्दैन। यो बजार्ने क्रममा तपाईंले प्रयोग गरेको ढाँचा हो। +**स्टेटलेस च्याट** - प्रत्येक अनुरोध स्वतन्त्र हुन्छ। मोडेललाई अघि भएका सन्देशहरूको कुनै सम्झना हुँदैन। यो सबैभन्दा सरल सुरुवात हो। -**Stateful Conversation** - हरेक अनुरोधले संवाद इतिहास समावेश गर्दछ। मोडेलले धेरै पल्टको सन्दर्भ कायम राख्छ। उत्पादन एप्लिकेशनहरूलाई यही आवश्यक पर्छ। +**स्टेटफुल संवाद** - प्रत्येक अनुरोधले संवाद इतिहास समावेश गर्दछ। मोडेल धेरै पालोमा सन्दर्भ कायम राख्छ। यो उत्पादन अनुप्रयोगहरूले चाहिने कुरा हो। -## पूर्वआवश्यकताहरू +## अग्रिम आवश्यकताहरू -- Azure सदस्यता जसमा Azure OpenAI पहुँच छ +- Azure सदस्यता Azure OpenAI पहुँच सहित - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **सूचना:** Java, Maven, Azure CLI र Azure Developer CLI (azd) दिइएको devcontainer मा पहिले नै इन्स्टल गरिएका छन्। +> **सूचना:** प्रदान गरिएको devcontainer मा Java, Maven, Azure CLI र Azure Developer CLI (azd) पूर्व-स्थापित छन्। -> **सूचना:** यस मोड्युलले Azure OpenAI मा GPT-5.2 प्रयोग गर्छ। परिनियोजन `azd up` प्रयोग गरेर स्वतः कन्फिगर हुन्छ - कोडमा मोडेल नाम परिवर्तन नगर्नुहोस्। +> **सूचना:** यो मोड्युलले Azure OpenAI मा GPT-5.2 प्रयोग गर्छ। `azd up` मार्फत स्वचालित रूपमा डिप्लोय गरिएको छ - कोडमा मोडेल नाम परिवर्तन नगर्नुहोस्। -## मुख्य समस्यालाई बुझ्नुहोस् +## मुख्य समस्यालाई बुझ्दै -भाषा मोडेलहरू stateless हुन्छन्। हरेक API कल स्वतन्त्र हुन्छ। तपाईंले "मेरो नाम जोन हो" पठाउनु भयो र त्यसपछि "मेरो नाम के हो?" सोध्नु भयो भने, मोडेललाई तपाईंले आफूलाई चिनाउनु भएको थाहा हुँदैन। यसले प्रत्येक अनुरोधलाई तपाईंले कहिल्यै गरेको पहिलो संवाद जस्तै व्यवहार गर्छ। +भाषा मोडेलहरू स्टेटलेस हुन्छन्। प्रत्येक API कल स्वतन्त्र हुन्छ। तपाईंले "मेरो नाम जोन हो" पठाउनुभएको र त्यसपछि सोध्नु भयो "मेरो नाम के हो?", मोडेललाई थाहा हुँदैन तपाईंले परिचय गराउनुभयो। यसले प्रत्येक अनुरोधलाई पहिलो संवादजस्तो व्यवहार गर्छ। -यो सरल Q&A का लागि ठीक छ तर वास्तविक एप्लिकेशनका लागि बेकार हो। ग्राहक सेवा बोटहरूले तपाईंले भनेका कुराहरू सम्झिनु पर्छ। व्यक्तिगत सहायकहरूले सन्दर्भ चाहिन्छ। कुनै पनि बहु-पल्ट संवादलाई मेमोरी आवश्यक हुन्छ। +यो सरल प्रश्नोत्तरको लागि ठीक छ तर वास्तविक अनुप्रयोगहरूको लागि बेकार हो। ग्राहक सेवा बोटहरूले तपाईंले उनलाई के भन्नुभयो सम्झनु पर्छ। व्यक्तिगत सहायकहरूले सन्दर्भ चाहिन्छ। कुनै पनि बहुपालो संवादले मेमोरी चाहिन्छ। -तलको चित्रले दुई उपायहरू तुलना गर्दछ — बायाँतर्फ stateless कल जसले तपाईंको नाम बिर्सिन्छ; दायाँतर्फ ChatMemory द्वारा समर्थित stateful कल जसले नाम सम्झन्छ। +तलको चित्रले दुईवटा दृष्टिकोणहरूको तुलना गर्छ — बायाँमा, नाम बिर्सने स्टेटलेस कल; दायाँमा, ChatMemory द्वारा समर्थन गरिएको स्टेटफुल कल जसले याद राख्छ। Stateless vs Stateful Conversations -*stateless (स्वतन्त्र कलहरू) र stateful (सन्दर्भ-बोध गर्ने) संवादहरूको भेद* +*स्टेटलेस (स्वतन्त्र कलहरू) र स्टेटफुल (सन्दर्भ-अनुभवी) संवादहरू बीचको फरक* -## टोकनहरू बुझ्नुहोस् +## टोकनहरू बुझ्दै -संवादहरूमा जाने अघि, टोकनहरू बुझ्न महत्त्वपूर्ण छ - भाषा मोडेलहरूले प्रक्रिया गर्ने पाठका आधारभूत एकाइहरू: +संवादहरूमा डुब्नुअघि, टोकनहरू बुझ्न जरुरी छ — भाषा मोडेलहरूले प्रशोधन गर्ने मूल पाठ इकाइहरू: Token Explanation -*टेक्स्ट कसरी टोकनहरूमा विभाजित हुन्छ - "I love AI!" ले ४ अलग प्रोसेसिङ युनिटमा परिणत हुन्छ* +*टेक्स्टलाई कसरी टोकनहरूमा विभाजित गरिन्छ उदाहरण - "म AI लाई माया गर्छु!" चार छुट्टाछुट्टै प्रशोधन इकाइहरूमा परिणत हुन्छ* -टोकनहरूले AI मोडेलहरूले पाठ मापन र प्रक्रिया गर्दछन्। शब्दहरू, विरामचिन्हहरू, र खाली ठाउँहरू पनि टोकन हुन सक्छन्। तपाईंको मोडेलसँग एक समयमा कति टोकन प्रक्रिया गर्न सक्छ भन्ने सीमा हुन्छ (GPT-5.2 का लागि ४००,०००, जसमा २७२,००० इनपुट र १२८,००० आउटपुट टोकन सम्म)। टोकन बुझ्नाले संवादको लम्बाइ र लागत व्यवस्थापन गर्न सजिलो हुन्छ। +टोकनहरू AI मोडेलहरूले पाठ मापन र प्रशोधन गर्ने तरिका हुन्। शब्दहरू, विरामचिह्नहरू र खाली ठाउँहरू पनि टोकन हुन सक्छन्। तपाईंको मोडेलसँग एक पटकमा प्रशोधन गर्न सकिने टोकनहरूको सीमा हुन्छ (GPT-5.2 को लागि ४००,०००, जसमा २७२,००० इनपुट टोकन र १२८,००० आउटपुट टोकनसम्म)। टोकन बुझ्नाले तपाईंलाई संवादको लम्बाई र लागत व्यवस्थापन गर्न सहयोग गर्छ। ## मेमोरी कसरी काम गर्छ -च्याट मेमोरीले stateless समस्यालाई संवाद इतिहास कायम गरेर समाधान गर्छ। मोडेलमा अनुरोध पठाउनु अघि, फ्रेमवर्कले सान्दर्भिक अघिल्लो सन्देशहरू अगाडि राख्छ। जब तपाईं "मेरो नाम के हो?" सोध्नुहुन्छ, सिस्टमले सम्पूर्ण संवाद इतिहास पठाउँछ, जसले मोडेललाई थाहा हुन्छ तपाईंले पहिले "मेरो नाम जोन हो" भन्नुभएको छ। +च्याट मेमोरी स्टेटलेस समस्यालाई समाधान गर्छ संवाद इतिहास कायम गरेर। तपाईँको अनुरोध मोडेलमा पठाउनु अघि, फ्रेमवर्कले सान्दर्भिक अघिल्ला सन्देशहरू थप्छ। जब तपाईं "मेरो नाम के हो?" भन्छौ, प्रणालीले वास्तवमा सम्पूर्ण संवाद इतिहास पठाउँछ, जसले मोडेललाई देखाउँछ कि तपाईंले पहिले "मेरो नाम जोन हो" भन्नुभएको थियो। -LangChain4j ले मेमोरी कार्यान्वयनहरू प्रदान गर्छ जुन यो स्वतः व्यवस्थापन गर्दछ। तपाईं चाहिएको सन्देश संख्या चयन गर्नुहुन्छ र फ्रेमवर्कले सन्दर्भ विन्डो व्यवस्थापन गर्छ। तलको चित्रले MessageWindowChatMemory कसरी हालसालैका सन्देशहरूको स्लाइडिङ विन्डो कायम राख्छ देखाउँछ। +LangChain4j ले मेमोरी कार्यान्वयनहरू प्रदान गर्छ जुन यसलाई स्वचालित रूपमा व्यवस्थापन गर्छ। तपाईं कति सन्देशहरू राख्ने निर्णय गर्नुहुन्छ र फ्रेमवर्क सन्दर्भ विन्डो व्यवस्थित गर्छ। तलको चित्रले देखाउँछ कसरी MessageWindowChatMemory ले भर्खरका सन्देशहरूको स्लाइडिङ विन्डो कायम गर्छ। Memory Window Concept -*MessageWindowChatMemory ले हालसालैका सन्देशहरूको स्लाइडिङ विन्डो कायम राख्छ, पुराना स्वतः हटाउँदै* +*MessageWindowChatMemory ले भर्खरका सन्देशहरूको स्लाइडिङ विन्डो राख्छ, पुराना सन्देशहरू स्वचालित रूपमा हटाउँदै* ## यसले LangChain4j कसरी प्रयोग गर्छ -यो मोड्युलले छिटो सुरु सँग Spring Boot एकीकृत गरेर र संवाद मेमोरी थपेर विस्तार गर्दछ। भागहरू कसरी जोडिन्छन्: +यो मोड्युलले Spring Boot एकीकृत गर्दछ र संवाद मेमोरी थप्छ। यहाँ कम्पोनेन्टहरूले कसरि मिल्छन्: -**निर्भरता** - दुई LangChain4j पुस्तकालयहरू थप्नुहोस्: +**निर्भरता** - दुई LangChain4j लाइब्रेरीहरू थप्नुहोस्: ```xml @@ -94,7 +94,7 @@ LangChain4j ले मेमोरी कार्यान्वयनहरू ``` -**च्याट मोडेल** - Azure OpenAI लाई Spring bean को रूपमा कन्फिगर गर्नुहोस् ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**च्याट मोडेल** - Azure OpenAI लाई Spring bean रूपमा कन्फिगर गर्नुहोस् ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -बिल्डरले `azd up` द्वारा सेट गरिएको वातावरण चरहरूबाट प्रमाणपत्रहरू पढ्छ। `baseUrl` लाई तपाईंको Azure अन्तबिन्दुमा सेट गर्दा OpenAI क्लाएन्ट Azure OpenAI सँग काम गर्दछ। +बिल्डरले `azd up` द्वारा सेट गरिएको वातावरण परिवर्तनीयहरूबाट प्रमाणपत्र पढ़्छ। `baseUrl` तपाईंको Azure अन्तबिन्दुमा सेट गर्दा OpenAI क्लाएन्ट Azure OpenAI सँग काम गर्दछ। -**संवाद मेमोरी** - MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)) प्रयोग गरेर च्याट इतिहास ट्र्याक गर्नुहोस्: +**संवाद मेमोरी** - MessageWindowChatMemory सँग च्याट इतिहास ट्र्याक गर्नुहोस् ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,21 +124,21 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` सँग मेमोरी बनाउनुहोस् जसले पछिल्ला १० सन्देशहरू राख्छ। प्रयोगकर्ता र AI सन्देशहरू `UserMessage.from(text)` र `AiMessage.from(text)` सहित थप्नुहोस्। इतिहास `memory.messages()` बाट प्राप्त गरी मोडेलमा पठाउनुहोस्। सेवा प्रत्येक संवाद ID का लागि अलग मेमोरी उदाहरणहरू भण्डारण गर्छ, जसले एकै साथ बहु प्रयोगकर्ताहरूलाई च्याट गर्न अनुमति दिन्छ। +`withMaxMessages(10)` प्रयोग गरेर मेमोरी सिर्जना गर्नुहोस् जसले अन्तिम १० सन्देशहरू राख्छ। प्रयोगकर्ता र AI सन्देशहरू `UserMessage.from(text)` र `AiMessage.from(text)` टाइप गरिएको र्‍यापरहरूसँग थप्नुहोस्। इतिहास `memory.messages()` बाट प्राप्त गरेर मोडेलमा पठाउनुहोस्। सेवा प्रत्येक संवाद ID का लागि अलग मेमोरी उदाहरणहरू भण्डारण गर्छ, जसले धेरै प्रयोगकर्ताहरूलाई एउटै समयमा च्याट गर्न अनुमति दिन्छ। -> **🤖 GitHub Copilot सँग प्रयास गर्नुहोस्:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) खोल्नुहोस् र सोध्नुहोस्: -> - "MessageWindowChatMemory ले विन्डो पुरा हुँदा कुन सन्देशहरू हटाउने निर्णय कसरी गर्छ?" -> - "के म इन-मेमोरीको सट्टा डेटाबेस प्रयोग गरेर कस्टम मेमोरी भण्डारण लागू गर्न सक्छु?" -> - "पुराना संवाद इतिहास सङ्कुचित गर्न संक्षेपण कसरी थप्ने?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) च्याट संग प्रयास गर्नुहोस्:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) खोल्नुहोस् र सोध्नुहोस्: +> - "MessageWindowChatMemory कुन सन्देशहरू ड्रप गर्ने निर्णय कसरी गर्छ जब विन्डो पूर्ण हुन्छ?" +> - "मेमोरी स्टोर गर्न कस्टम डेटाबेस प्रयोग गरेर कसरी कार्यान्वयन गर्न सक्छु?" +> - "पुरानो संवाद इतिहास संक्षेप गर्न कसरी समरी जोड्न सकिन्छ?" -stateless च्याट endpoints मेमोरीलाई पूर्ण रूपमा बाइपास गर्छ - जस्तै छिटो शुरुवातमा `chatModel.chat(prompt)` मात्र। stateful endpoint ले मेमोरीमा सन्देशहरू थप्छ, इतिहास पुन:प्राप्त गर्छ, र हरेक अनुरोधसँग त्यस सन्दर्भ समावेश गर्दछ। मोडेल कन्फिगरेसन समान छ, तर फरक ढाँचाहरू। +स्टेटलेस च्याट अन्तबिन्दु मेमोरी सम्पूर्ण रूपमा छोड्छ - छिटो सुरु गर्न जस्तै `chatModel.chat(prompt)` मात्र हुन्छ। स्टेटफुल अन्तबिन्दुले सन्देशहरू मेमोरीमा थप्छ, इतिहास प्राप्त गर्छ र प्रत्येक अनुरोधसँग त्यो सन्दर्भ समावेश गर्दछ। एउटै मोडेल कन्फिगरेसन, फरक ढाँचाहरू। -## Azure OpenAI पूर्वाधार परिनियोजन गर्नुहोस् +## Azure OpenAI पूर्वाधार डिप्लोय गर्नुहोस् **Bash:** ```bash cd 01-introduction -azd up # सदस्यता र स्थान छान्नुहोस् (eastus2 सिफारिश गरिन्छ) +azd up # सदस्यता र स्थान छनौट गर्नुहोस् (eastus2 सिफारिस गरिएको) ``` **PowerShell:** @@ -147,16 +147,16 @@ cd 01-introduction azd up # सदस्यता र स्थान चयन गर्नुहोस् (eastus2 सिफारिस गरिएको) ``` -> **सूचना:** यदि तपाईंले Timeout त्रुटि (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) सामना गर्नुहुन्छ भने, `azd up` पुन: चलाउनुहोस्। Azure स्रोतहरू अझै पृष्ठभूमिमा प्रावधान भइरहेको हुन सक्छ, र पुन: प्रयासले स्रोतहरू टर्मिनल अवस्थामा पुगेपछि परिनियोजन पूरा गर्न मद्दत गर्दछ। +> **सूचना:** यदि तपाईलाई टाइमआउट त्रुटि (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) आउँछ भने, `azd up` पुनः चलाउनुहोस्। Azure स्रोतहरू पृष्ठभूमिमा अझै प्राविधिक अवस्थामा हुन सक्छन्, र पुनः प्रयासले डिप्लोयमेन्ट पूरा हुन मद्दत गर्छ जब स्रोतहरू अन्तिम अवस्थामा पुग्छन्। -यसले गर्नेछ: -1. GPT-5.2 र text-embedding-3-small मोडेलहरू सहित Azure OpenAI स्रोत परिनियोजन -2. परियोजना मूलीमा प्रमाणपत्रहरूको साथ `.env` फाइल स्वचालित रूपमा सिर्जना -3. सबै आवश्यक वातावरण चरहरू सेटअप +यसले: +1. GPT-5.2 र text-embedding-3-small मोडेलहरूसँग Azure OpenAI स्रोत डिप्लोय गर्छ +2. परियोजना रूटमा स्वचालित रूपमा `.env` फाइल बनाउँछ प्रमाणपत्रहरू सहित +3. सबै आवश्यक वातावरण चरहरू सेटअप गर्छ -**परिनियोजन समस्याहरू छन्?** विस्तृत समस्यासमाधानका लागि [Infrastructure README](infra/README.md) हेर्नुहोस्, जहाँ सबडोमेन नाम द्वन्द्व, Azure Portal मा म्यानुअल परिनियोजन चरणहरू, र मोडेल कन्फिगरेसन सल्लाह छन्। +**डिप्लोयमेन्टमा समस्याहरू छ?** विस्तृत समस्या समाधानका लागि [पूर्वाधार README](infra/README.md) हेर्नुहोस् जसमा उपडोमेन नाम द्वन्द्व, Azure पोर्टलमा म्यानुअल डिप्लोयमेन्ट चरणहरू, र मोडेल कन्फिगरेसन मार्गनिर्देशन छ। -**परिनियोजन सफल भयो भनी जाँच गर्नुहोस्:** +**डिप्लोयमेन्ट सफल भयो भनी जाँच गर्नुहोस्:** **Bash:** ```bash @@ -165,10 +165,10 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, आदि देखाउनु **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, आदिलाई देखाउनु पर्दछ। +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, आदि देखाउनु पर्छ। ``` -> **सूचना:** `azd up` कमाण्डले `.env` फाइल स्वचालित रूपमा बनाउँछ। पछि यसलाई अपडेट गर्न आवश्यक भएमा, तपाईंले `.env` फाइल म्यानुअली सम्पादन गर्न सक्नुहुन्छ वा पुन:निर्माण गर्न: +> **सूचना:** `azd up` आदेशले स्वचालित रूपमा `.env` फाइल सिर्जना गर्छ। यदि पछि यसलाई अपडेट गर्न आवश्यक भए: > > **Bash:** > ```bash @@ -184,13 +184,13 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, आदिलाई दे ## एप्लिकेशन स्थानीय रूपमा चलाउनुहोस् -**परिनियोजन जाँच गर्नुहोस्:** +**डिप्लोयमेन्ट जाँच गर्नुहोस्:** -Azure प्रमाणपत्रहरूसँग `.env` फाइल मूली निर्दिष्टामा अवश्य छ। यसलाई मोड्युल डिरेक्टरी (`01-introduction/`) बाट चलाउनुहोस्: +मूल निर्देशिकामा `.env` फाइल Azure प्रमाणपत्रहरूसहित अवस्थित छ सुनिश्चित गर्नुहोस्। यसलाई मोड्युल निर्देशिका (`01-introduction/`) बाट चलाउनुहोस्: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनु पर्छ +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनु पर्नेछ ``` **PowerShell:** @@ -198,27 +198,27 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनु Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनु पर्छ ``` -**एप्लिकेशनहरू सुरु गर्नुहोस्:** +**एप्लिकेशनहरू शुरू गर्नुहोस्:** -**विकल्प १: Spring Boot Dashboard प्रयोग गर्दै (VS Code प्रयोगकर्ताहरूका लागि सिफारिस गरिएको)** +**विकल्प १: Spring Boot ड्यासबोर्ड प्रयोग गर्दै (VS Code प्रयोगकर्ताहरूका लागि सिफारिस गरिएको)** -डिभ कन्टेनरमा Spring Boot Dashboard एक्सटेन्सन समावेश गरिएको छ, जसले सबै Spring Boot एप्लिकेशनहरूलाई दृश्यात्मक रूपमा व्यवस्थापन गर्न सक्षम पार्दछ। VS Code को बाँया पट्टि Activity Bar मा Spring Boot आइकन खोज्नुहोस्। +डिभ कन्टेनरमा Spring Boot ड्यासबोर्ड एक्सटेन्सन समावेश छ, जसले सबै Spring Boot एप्लिकेशनहरू प्रबन्ध गर्न दृश्य इन्टरफेस दिन्छ। VS Code को बायाँपट्टि एक्टिभिटी बारमा (Spring Boot आइकन हेर्नुहोस्) पाउन सकिन्छ। -Spring Boot Dashboard बाट तपाईंले: -- कार्यक्षेत्रका सबै Spring Boot एप्लिकेशनहरू हेर्न सक्नुहुन्छ -- एप्लिकेशनहरू एक क्लिकले सुरू / रोक्न सक्नुहुन्छ +Spring Boot ड्यासबोर्डबाट तपाईं: +- सबै उपलब्ध Spring Boot एपहरू कार्यक्षेत्रमा देख्न सक्नुहुन्छ +- एक क्लिकमा एपहरू सुरु/रोक्न सक्नुहुन्छ - एप्लिकेशन लगहरू वास्तविक समयमा हेर्न सक्नुहुन्छ - एप्लिकेशन स्थिति अनुगमन गर्न सक्नुहुन्छ -सिर्फ "introduction" छेउमा प्ले बटन क्लिक गर्नुहोस् वा सबै मोड्युलहरू एकैपटक सुरु गर्नुहोस्। +"introduction" को छेउमा प्ले बटन क्लिक गरी यो मोड्युल सुरु गर्नुहोस्, वा सबै मोड्युलहरू एकै पटक सुरु गर्नुहोस्। Spring Boot Dashboard -*VS Code मा Spring Boot Dashboard — सबै मोड्युलहरू एकत्रित स्थानबाट सुरु, रोक्न र अनुगमन गर्न* +*VS Code मा Spring Boot ड्यासबोर्ड — सबै मोड्युलहरू एकै ठाउँबाट शुरू, बन्द र अनुगमन गर्न* -**विकल्प २: shell script प्रयोग गरेर** +**विकल्प २: shell स्क्रिप्ट प्रयोग गर्दै** -सबै वेब एप्लिकेशनहरू सुरु गर्नुहोस् (मोदुल ०१-०४): +सबै वेब एपहरू सुरु गर्नुहोस् (मोड्युल ०१-०४): **Bash:** ```bash @@ -228,11 +228,11 @@ cd .. # मूल निर्देशिका बाट **PowerShell:** ```powershell -cd .. # रूट डाइरेक्टरीबाट +cd .. # रुट निर्देशिकाबाट .\start-all.ps1 ``` -वा केवल यो मोड्युल सुरु गर्नुहोस्: +वा यो मोड्युल मात्र सुरु गर्नुहोस्: **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -दुवै स्क्रिप्टहरूले मूली `.env` फाइलबाट वातावरण चरहरू स्वतः लोड गर्छन् र JAR नहुँदा निर्माण गर्छन्। +दुवै स्क्रिप्टहरूले मूल `.env` फाइलबाट वातावरण चरहरू स्वचालित रूपमा लोड गर्छन् र यदि JAR फाइलहरू अवस्थित छैनन् भने निर्माण पनि गर्छन्। -> **सूचना:** सबै मोडुलहरूलाई म्यानुअली बनाएर सुरु गर्न मन परे: +> **सूचना:** यदि सुरु गर्नु अघि सबै मोड्युलहरू म्यानुअली बनाउने चाहनुहुन्छ भने: > > **Bash:** > ```bash @@ -262,7 +262,7 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -तपाईंको ब्राउजरमा http://localhost:8080 खोल्नुहोस्। +http://localhost:8080 तपाईंको ब्राउजरमा खोल्नुहोस्। **रोक्न:** @@ -275,48 +275,48 @@ cd .. && ./stop-all.sh # सबै मोड्युलहरू **PowerShell:** ```powershell -.\stop.ps1 # यो मोड्युल मात्र +.\stop.ps1 # केवल यो मोड्युल # वा cd ..; .\stop-all.ps1 # सबै मोड्युलहरू ``` ## एप्लिकेशन प्रयोग गर्दै -एप्लिकेशनले दुवै तर्फ दुई च्याट कार्यान्वयनहरू सहित वेब इन्टरफेस प्रदान गर्दछ। +एपले दुईवटा च्याट कार्यान्वयनहरू प्रदर्शित गर्ने वेब इन्टरफेस प्रदान गर्छ साइड-बाट-साइडमा। Application Home Screen -*ड्यासबोर्ड जसले Simple Chat (stateless) र Conversational Chat (stateful) विकल्पहरू देखाउँछ* +*ड्यासबोर्डले Simple Chat (स्टेटलेस) र Conversational Chat (स्टेटफुल) विकल्पहरू देखाउँछ* -### Stateless Chat (बायाँ प्यानल) +### स्टेटलेस च्याट (बायाँ प्यानल) -यसलाई पहिलो प्रयास गर्नुहोस्। "मेरो नाम जोन हो" भनी सोध्नुहोस् र तुरुन्तै "मेरो नाम के हो?" प्रश्न गर्नुहोस्। मोडेलले सम्झनेछैन किनभने प्रत्येक सन्देश स्वतन्त्र छ। यो आधारभूत भाषा मोडेल एकीकरणसँग मुख्य समस्या देखाउँछ - कुनै संवाद सन्दर्भ छैन। +यसलाई पहिले प्रयास गर्नुहोस्। "मेरो नाम जोन हो" भनिरहेका बेला तुरुन्तै "मेरो नाम के हो?" सोध्नुहोस्। मोडेलले सम्झने छैन किनभने प्रत्येक सन्देश स्वतन्त्र हुन्छ। यो भाषा मोडेल एकीकरणमा प्रमुख समस्या देखाउँछ - संवाद सन्दर्भ छैन। Stateless Chat Demo *AI ले अघिल्लो सन्देशबाट तपाईंको नाम सम्झँदैन* -### Stateful Chat (दायाँ प्यानल) +### स्टेटफुल च्याट (दायाँ प्यानल) -अब यहाँ उस्तै अनुक्रम प्रयास गर्नुहोस्। "मेरो नाम जोन हो" र त्यसपछि "मेरो नाम के हो?" सोध्नुहोस्। यस पटक यसले सम्झन्छ। भिन्नता MessageWindowChatMemory हो - यसले संवाद इतिहास कायम राख्छ र प्रत्येक अनुरोधमा समावेश गर्दछ। यस्तै उत्पादन संवादात्मक AI काम गर्छ। +अहिले त्यही अनुक्रम यहाँ प्रयास गर्नुहोस्। "मेरो नाम जोन हो" र पछि "मेरो नाम के हो?" यस पटक यो सम्झन्छ। फरक MessageWindowChatMemory हो - यसले संवाद इतिहास राख्छ र प्रत्येक अनुरोधमा समावेश गर्दछ। यही उत्पादन संवादात्मक AI को काम गर्ने तरिका हो। Stateful Chat Demo -*AI ले संवादको प्रारम्भमा भनेको तपाईंको नाम सम्झन्छ* +*AIले पहिलेको संवादबाट तपाईंको नाम सम्झन्छ* -दुबै प्यानलले उही GPT-5.2 मोडेल प्रयोग गर्छन्। फरक मात्र मेमोरी हो। यसले तपाईंको एप्लिकेशनमा मेमोरी के ल्याउँछ र किन यो वास्तविक प्रयोगका लागि अत्यावश्यक छ स्पष्ट पार्दछ। +दुवै प्यानलले एउटै GPT-5.2 मोडेल प्रयोग गर्छन्। मात्र फरक मेमोरी हो। यसले के मेमोरीले तपाईंको अनुप्रयोगमा ल्याउँछ र किन यो वास्तविक प्रयोगका लागि अपरिहार्य छ बुझ्न सजिलो बनाउँछ। -## अर्को कदमहरू +## अगला कदमहरू -**अर्को मोड्युल:** [02-prompt-engineering - GPT-5.2 सँग प्रॉम्प्ट इन्जिनियरिङ](../02-prompt-engineering/README.md) +**अर्को मोड्युल:** [०२-प्रम्प्ट-इन्जिनियरिङ - GPT-5.2 सँग प्रम्प्ट इन्जिनियरिङ](../02-prompt-engineering/README.md) --- -**नेभिगेसन:** [← अघिल्लो: Module 00 - Quick Start](../00-quick-start/README.md) | [मुख्यमा फर्किनुहोस्](../README.md) | [अर्को: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**नेभिगेसन:** [← मुख्यमा फर्कनुहोस्](../README.md) | [अर्को: मोड्युल ०२ - प्रम्प्ट इन्जिनियरिङ →](../02-prompt-engineering/README.md) --- **अस्वीकरण**: -यो दस्तावेज AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी शुद्धताका लागि प्रयासरत छौं भनेपनि, कृपया ध्यान दिनुहोस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धता हुनसक्छ। मूल दस्तावेज यसको मूल भाषामै आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि पेशेवर मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनैपनि गलतफहमी वा गलत व्याख्याका लागि हामी जिम्मेवार छैनौं। +यो दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी सही हुन प्रयास गर्छौं, तर कृपया जानकार हुनुस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छन्। मूल दस्तावेज़ यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलत बुझाइ वा त्रुटिको लागि हामी जिम्मेवार छैनौं। \ No newline at end of file diff --git a/translations/ne/02-prompt-engineering/README.md b/translations/ne/02-prompt-engineering/README.md index 561c05a1a..2ff5cb27b 100644 --- a/translations/ne/02-prompt-engineering/README.md +++ b/translations/ne/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Module 02: GPT-5.2 सँग प्रम्प्ट इञ्जिनियरिङ - -## Table of Contents - -- [भिडियो हिँडाइ](../../../02-prompt-engineering) -- [तपाईंले के सिक्नुहुनेछ](../../../02-prompt-engineering) -- [आवश्यकताहरू](../../../02-prompt-engineering) -- [प्रम्प्ट इञ्जिनियरिङ बुझ्न](../../../02-prompt-engineering) -- [प्रम्प्ट इञ्जिनियरिङ आधारहरू](../../../02-prompt-engineering) - - [शून्य-शट प्रम्प्टिङ](../../../02-prompt-engineering) - - [थोरै-शट प्रम्प्टिङ](../../../02-prompt-engineering) - - [सोचको शृंखला](../../../02-prompt-engineering) - - [भूमिका-आधारित प्रम्प्टिङ](../../../02-prompt-engineering) - - [प्रम्प्ट टेम्प्लेटहरू](../../../02-prompt-engineering) -- [शाखागत ढाँचाहरू](../../../02-prompt-engineering) -- [एप्लिकेशन चलाउनुहोस्](../../../02-prompt-engineering) -- [एप्लिकेशन स्क्रिनसटहरू](../../../02-prompt-engineering) -- [ढाँचाहरू अन्वेषण गर्दै](../../../02-prompt-engineering) - - [कम बनाम उच्च उत्साह](../../../02-prompt-engineering) - - [कार्य सञ्चालन (टुल प्राम्बल्स)](../../../02-prompt-engineering) - - [आत्म-प्रतिबिम्बित कोड](../../../02-prompt-engineering) - - [संरचित विश्लेषण](../../../02-prompt-engineering) - - [धेरै पटकको कुरा](../../../02-prompt-engineering) - - [क्रमिक विचार प्रक्रिया](../../../02-prompt-engineering) - - [सीमित नतिजा](../../../02-prompt-engineering) -- [तपाईं साँच्चिकै के सिक्दै हुनुहुन्छ](../../../02-prompt-engineering) -- [अगाडि के गर्ने](../../../02-prompt-engineering) - -## Video Walkthrough - -यो लाइभ सेसन हेर्नुहोस् जसले यो मोड्युल कसरी सुरु गर्ने भनेर व्याख्या गर्छ: +# Module 02: GPT-5.2 सँग प्रॉम्प्ट इन्जिनियरिङ + +## टेबल अफ कन्टेन्ट्स + +- [भिडियो वाकथ्रू](#भिडियो-वाकथ्रू) +- [तपाईंले के सिक्नुहुनेछ](#तपाईंले-के-सिक्नुहुनेछ) +- [पूर्वशर्तहरू](#पूर्वशर्तहरू) +- [प्रॉम्प्ट इन्जिनियरिङ बुझ्न](#प्रॉम्प्ट-इन्जिनियरिङ-बुझ्न) +- [प्रॉम्प्ट इन्जिनियरिङका आधारभूत तत्वहरू](#प्रॉम्प्ट-इन्जिनियरिङका-आधारभूत-तत्वहरू) + - [शून्य-शट प्रॉम्प्टिङ](#शून्य-शट-प्रॉम्प्टिङ) + - [केही-शट प्रॉम्प्टिङ](#केही-शट-प्रॉम्प्टिङ) + - [चेन अफ थट](#चेन-अफ-थट) + - [भूमिका-आधारित प्रॉम्प्टिङ](#भूमिका-आधारित-प्रॉम्प्टिङ) + - [प्रॉम्प्ट टेम्प्लेटहरू](#प्रॉम्प्ट-टेम्प्लेटहरू) +- [उन्नत ढाँचाहरू](#उन्नत-ढाँचाहरू) +- [एप्लिकेसन चलाउनुहोस्](#अनुप्रयोग-चलाउनुहोस्) +- [एप्लिकेसन स्क्रीनशटहरू](#अनुप्रयोग-स्क्रिनशटहरू) +- [ढाँचाहरू अन्वेषण गर्दै](#ढाँचाहरू-अन्वेषण-गर्दै) + - [कम बनाम उच्च उत्साह](#low-बनाम-high-eagerness) + - [कार्य निष्पादन (टूल प्रीएम्बलहरू)](#कार्यान्वयन-कार्य-टुल-प्रिप्रेबल्स) + - [आत्म-प्रतिबिम्बन गर्ने कोड](#self-reflecting-code) + - [संरचित विश्लेषण](#संरचित-विश्लेषण) + - [बहु-टर्न च्याट](#बहु-टर्न-संवाद) + - [क्रमबद्ध तर्क](#चरण-द्वारा-चरण-तर्क) + - [संयमित आउटपुट](#सीमित-आउटपुट) +- [तपाईं साँच्चिकै के सिक्दै हुनुहुन्छ](#साँच्चिकै-तपाइँ-के-सिक्दै-हुनुहुन्छ) +- [अर्को चरणहरू](#अर्को-कदमहरू) + +## भिडियो वाकथ्रू + +यो लाइभ सेसन हेरौं जसले यो मोड्युल कसरी सुरु गर्ने भन्ने कुरा व्याख्या गर्छ: Prompt Engineering with LangChain4j - Live Session -## What You'll Learn +## तपाईंले के सिक्नुहुनेछ -तलको चित्रले यस मोड्युलमा तपाईंले विकास गर्ने मुख्य विषयहरू र सीपहरूको अवलोकन प्रदान गर्दछ — प्रम्प्ट सुधार प्रविधिहरूबाट लिएर तपाईंले पछ्याउने चरण-द्वारा-चरण कार्यप्रवाहसम्म। +तलको चित्रले यस मोड्युलमा तपाईंले विकास गर्ने मुख्य विषयहरू र सीपहरू — प्रॉम्प्ट सुधार प्रविधिहरू देखि चरण-द्वारा-चरण कार्यप्रवाहसम्म — को अवलोकन प्रदान गर्दछ। What You'll Learn -अघिल्लो मोड्युलहरूमा, तपाईंले GitHub मोडेलहरूसँग आधारभूत LangChain4j अन्तरक्रियाहरू अन्वेषण गर्नुभयो र मेमोरीले कसरी Azure OpenAI सँग संवादात्मक AI सक्षम गर्छ हेर्नुभयो। अब हामी कसरी प्रश्न सोध्ने — प्रम्प्टहरू आफैं — Azure OpenAI को GPT-5.2 प्रयोग गरी केन्द्रित हुने छौं। तपाईंको प्रम्प्टहरूको संरचना तपाईंले पाउने प्रतिक्रिया को गुणस्तरमा ठूलो प्रभाव पार्छ। हामी मूल प्रम्प्टिङ प्रविधिहरूको समीक्षा गर्दा सुरु गर्छौं, त्यसपछि आठ वटा उन्नत ढाँचाहरूमा जान्छौं जसले GPT-5.2 को क्षमताहरू पूर्ण रूपमा उपयोग गर्छन्। +अघिल्लो मोड्युलमा, तपाईंले हेर्नुभयो कसरी मेमोरीले Azure OpenAI सँग संवादात्मक AI सुसज्जित गर्छ। अब हामी केन्द्रित हुनेछौं प्रश्नहरू सोध्ने — प्रॉम्प्टहरू आफैं — Azure OpenAI को GPT-5.2 प्रयोग गरेर। तपाईंले प्रॉम्प्ट संरचना गर्ने तरिका जवाफहरूको गुणस्तरलाई निकै प्रभाव पार्छ। हामी आधारभूत प्रॉम्प्टिङ प्रविधिहरूको समीक्षा गर्दै सुरुवात गर्छौं, त्यसपछि आठ उन्नत ढाँचाहरूमा जान्छौं जसले GPT-5.2 का क्षमताहरूको पूर्ण फाइदा उठाउँछन्। -हामी GPT-5.2 प्रयोग गर्नेछौं किनकि यसले तर्क नियन्त्रण परिचय गराउँछ - तपाईं मोडेललाई कति सोच्नुपर्ने हो भन्ने भन्न सक्नुहुन्छ। यसले विभिन्न प्रम्प्टिङ रणनीतिहरू अझ स्पष्ट बनाउँछ र तपाईंलाई कुन दृष्टिकोण कहिले प्रयोग गर्ने बुझ्न मद्दत गर्छ। हामीले Azure को GPT-5.2 का लागि कम दर सीमा पनि GitHub मोडेलहरूको तुलनामा लाभ उठाउनेछौं। +हामी GPT-5.2 प्रयोग गर्नेछौं किनभने यसले तर्क नियन्त्रण प्रस्तुत गर्छ - तपाईं मोडेललाई उत्तर दिनुअघि कति सोच्ने भनेको निर्देशन दिन सक्नुहुन्छ। यसले विभिन्न प्रॉम्प्टिङ रणनीतिहरू अझ स्पष्ट बनाउँछ र तपाईंलाई कुन तरिका कहिले प्रयोग गर्ने बुझाउन मद्दत गर्छ। -## Prerequisites +## पूर्वशर्तहरू -- Module 01 पुरा गरिएको (Azure OpenAI स्रोतहरू परिनियोजित) -- मूल फोल्डरमा `.env` फाइल Azure प्रमाणपत्रहरू सहित (Module 01 मा `azd up` द्वारा सिर्जना गरिएको) +- मोड्युल 01 पुरा गरिएको (Azure OpenAI स्रोतहरू तैनाथ गरिएको) +- मुप्रमुख निर्देशिकामा `.env` फाइल Azure प्रमाणपत्रहरूसहित (मोड्युल 01 मा `azd up` द्वारा सिर्जना गरिएको) -> **Note:** यदि तपाईंले Module 01 पुरा गर्नुभएको छैन भने, त्यहाँ पहिले परिनियोजन निर्देशनहरू पालना गर्नुहोस्। +> **टिप्पणी:** यदि तपाईंले मोड्युल 01 पूरा गर्नुभएन भने, पहिले त्यहाँको तैनाथीकरण निर्देशनहरू पालना गर्नुहोस्। -## Understanding Prompt Engineering +## प्रॉम्प्ट इन्जिनियरिङ बुझ्न -आधारमा, प्रम्प्ट इञ्जिनियरिङ अस्पष्ट निर्देशन र सटीक निर्देशन बीचको फरक हो, तलको तुलना देखाउँछ। +मूल रूपमा, प्रॉम्प्ट इन्जिनियरिङ अस्पष्ट निर्देशन र स्पष्ट निर्देशनको फरक हो, जस्तो तलको तुलना देखाउँछ। What is Prompt Engineering? -प्रम्प्ट इञ्जिनियरिङ यस्तो इनपुट पाठ डिजाइन गर्न बारेमा हो जसले निरन्तर तपाईंलाई आवश्यक परिणाम दिन्छ। यो केवल प्रश्न सोध्ने विषय होइन - यो अनुरोधहरू यस्तो संरचना गर्ने विषय हो ताकि मोडेल ठीकै बुझोस् कि तपाईं के चाहनुहुन्छ र यसलाई कसरी उपलब्ध गराउनु पर्छ। +प्रॉम्प्ट इन्जिनियरिङ भनेको यस्ता इनपुट पाठ डिजाइन गर्ने प्रक्रिया हो जुन तपाईंले आवश्यक परिणामहरू निरन्तर प्राप्त गर्न सक्नुहुनेछ। यो केवल प्रश्न सोध्ने कुरा मात्रै होइन - यो अनुरोधहरू संरचना गर्ने कुरा हो ताकि मोडेलले तपाईंले के चाहनुहुन्छ र कसरी दिनुहुन्छ भनेर ठीकसँग बुझ्न सकोस्। -यसलाई एउटा सहकर्मीलाई निर्देशन दिने रूपमा सोच्नुहोस्। "बग ठिक पार" अस्पष्ट छ। "UserService.java को लाइन 45 मा नल प्वाइन्टर एक्सेप्सन ठिक पार्न नल जाँच थप" विशिष्ट छ। भाषा मोडेलहरू पनि यस्तै हुन्छन् - विशिष्टता र संरचनाले महत्त्व राख्छ। +योलाई सहकर्मीलाई निर्देशन दिने जस्तो सोच्नुहोस्। "बग ठीक गर" अस्पष्ट छ। "UserService.java लाइन 45 मा नल चेक थपेर नल पोइन्टर एक्सेप्सन ठीक गर" भनेको विशिष्ट छ। भाषा मोडेलहरू पनि त्यही तरिकाले काम गर्छन् - स्पष्टता र संरचनाले महत्व राख्छ। -तलको चित्रले देखाउँछ कि LangChain4j यस चित्रमा कसरी फिट हुन्छ — SystemMessage र UserMessage बिल्डिङ ब्लकहरू मार्फत तपाईंको प्रम्प्ट ढाँचाहरूलाई मोडेलसँग जोड्दै। +तलको चित्रले LangChain4j यस सन्दर्भमा कसरी मेल खान्छ भनेर देखाउँछ — तपाईंका प्रॉम्प्ट ढाँचाहरूसँग मोडेललाई SystemMessage र UserMessage निर्माण ब्लकमार्फत जडान गर्दै। How LangChain4j Fits -LangChain4jले पूर्वाधार प्रदान गर्छ — मोडेल कनेक्शनहरू, मेमोरी, र सन्देश प्रकारहरू — जबकि प्रम्प्ट ढाँचाहरू केवल सावधानीपूर्वक संरचित पाठहरू हुन् जुन तपाईं त्यस पूर्वाधार मार्फत पठाउनुहुन्छ। मुख्य बिल्डिङ ब्लकहरू `SystemMessage` (जो AI को व्यवहार र भूमिका सेट गर्छ) र `UserMessage` (जो तपाईंको वास्तविक अनुरोध बोक्छ) हुन्। +LangChain4j ले पूर्वाधार प्रदान गर्छ — मोडेल जडानहरू, मेमोरी, र सन्देश प्रकारहरू — जबकि प्रॉम्प्ट ढाँचाहरू ती पूर्वाधारमार्फत पठाइने सावधानीपूर्वक संरचित पाठ मात्रै हुन्। प्रमुख निर्माण ब्लकहरू हुन् `SystemMessage` (जसले AI को व्यवहार र भूमिका सेट गर्दछ) र `UserMessage` (जसले तपाईंको वास्तविक अनुरोध बोक्दछ)। -## Prompt Engineering Fundamentals +## प्रॉम्प्ट इन्जिनियरिङका आधारभूत तत्वहरू -तल देखाइएका पाँच प्रमुख प्रविधिहरू प्रभावकारी प्रम्प्ट इञ्जिनियरिङको आधार हुन्। प्रत्येकले भाषा मोडेलहरूसँग तपाईं कसरी सञ्चार गर्नुहुन्छ भन्ने फरक पक्षसँग सम्बोधन गर्छ। +तल देखाइएका पाँच मुख्य प्रविधिहरू प्रभावकारी प्रॉम्प्ट इन्जिनियरिङको आधार हुन्। प्रत्येकले भाषा मोडेलहरूसँग तपाईं कसरी संवाद गर्नुहुन्छ भन्ने फरक पक्ष सम्बोधन गर्दछ। Five Prompt Engineering Patterns Overview -यस मोड्युलका उन्नत ढाँचाहरूमा जानुअघि, पाँच आधारभूत प्रम्प्टिङ प्रविधिहरूको समीक्षा गरौं। यी ती बिल्डिङ ब्लकहरू हुन् जुन प्रत्येक प्रम्प्ट इञ्जिनियरले जान्नुपर्छ। यदि तपाईंले पहिले नै [चाँडो सुरु मोड्युल](../00-quick-start/README.md#2-prompt-patterns) प्रयोग गर्नुभएको छ भने, तपाईंले तिनीहरूलाई प्रयोगमा देख्नु भएको छ — यहाँ तिनीहरूको अवधारणात्मक आधार छ। +यस मोड्युलका उन्नत ढाँचाहरूमा डुब्नु अघि, पाँच आधारभूत प्रॉम्प्टिङ प्रविधिहरूको समीक्षा गरौं। यी सबै प्रॉम्प्ट इन्जिनियरहरूले जान्नुपर्ने निर्माण ब्लकहरू हुन्। -### Zero-Shot Prompting +### शून्य-शट प्रॉम्प्टिङ -सबसम्म सरल दृष्टिकोण: मोडेललाई कुनै उदाहरण बिना सिधा निर्देशन दिनु। मोडेलले प्रशिक्षणमा मात्र भर पर्छ कार्य बुझ्न र सम्पादन गर्न। यो सोझो अनुरोधहरूका लागि राम्रो काम गर्छ जहाँ अपेक्षित व्यवहार स्पष्ट छ। +सबैभन्दा सरल तरिका: मोडेललाई कुनै उदाहरण बिना सिधा निर्देशन दिनुहोस्। मोडेलले काम बुझ्न र कार्यान्वयन गर्न आफ्नै प्रशिक्षणमा पूर्ण रूपमा निर्भर गर्दछ। यो तिनी कार्यहरूका लागि राम्रो हुन्छ जहाँ अपेक्षित व्यवहार स्पष्ट हुन्छ। Zero-Shot Prompting -*उदाहरण बिना सिधा निर्देशन — मोडेलले निर्देशनबाट मात्र कार्य अनुमान लगाउँछ* +*उदाहरण बिना सिधा निर्देशन — मोडेलले निर्देशनबाट मात्र कार्य बुझ्छ* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// प्रतिक्रिया: "सकारात्मक" +// प्रतिक्रिया: "धनात्मक" ``` + +**कहिले प्रयोग गर्ने:** साधारण वर्गीकरणहरू, सिधा प्रश्नहरू, अनुवादहरू, वा कुनै पनि कार्य जसलाई मोडेलले अतिरिक्त मार्गदर्शन बिना सम्भाल्न सक्छ। -**कहिले प्रयोग गर्ने:** सरल वर्गीकरणहरू, सिधा प्रश्नहरू, अनुवादहरू, वा कुनै पनि कार्य जसलाई मोडेलले अतिरिक्त मार्गदर्शन बिना पनि सम्हाल्न सक्छ। +### केही-शट प्रॉम्प्टिङ -### Few-Shot Prompting - -तपाईंले चाहेको ढाँचाको नमूना उदाहरणहरू दिनुहोस्। मोडेलले तपाईंका उदाहरणहरूबाट अपेक्षित इनपुट-आउटपुट स्वरूप सिक्छ र नयाँ इनपुटहरूमा लागू गर्छ। यो अझ सुसंगतता ल्याउँछ जहाँ चाहिएको ढाँचा वा व्यवहार स्पष्ट छैन। +मोडेलले अनुसरण गर्ने ढाँचा देखाउने उदाहरणहरू प्रदान गर्नुहोस्। मोडेलले तपाईंका उदाहरणहरूबाट अपेक्षित इनपुट-आउटपुट ढाँचा सिक्छ र नयाँ इनपुटहरूमा लागू गर्छ। यो त्यस्तो कार्यका लागि स्थिरता निकै सुधार गर्छ जहाँ इच्छित स्वरूप वा व्यवहार स्पष्ट हुँदैन। Few-Shot Prompting -*उदाहरणबाट सिक्ने — मोडेलले ढाँचालाई चिन्न र नयाँ इनपुटमा लागू गर्न सक्षम हुन्छ* +*उदाहरणबाट सिक्ने — मोडेलले ढाँचालाई पहिचान गरी नयाँ इनपुटमा लागू गर्छ* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` + +**कहिले प्रयोग गर्ने:** कस्टम वर्गीकरणहरू, सुसँगत फर्म्याटिङ, डोमेन-विशिष्ट कार्यहरू, वा जब शून्य-शट नतिजाहरू अस्थिर हुन्छन्। -**कहिले प्रयोग गर्ने:** अनुकूल वर्गीकरणहरू, सुसंगत स्वरूप, डोमेन-विशेष कार्यहरू, वा जब शून्य-शट नतिजाहरू असंगत हुन्छन्। - -### Chain of Thought +### चेन अफ थट -मोडेललाई त्यसको तर्कलाई चरण-द्वारा-चरण देखाउन भन्नुहोस्। सिधै जवाफमा नलफ्टेर, मोडेल समस्यालाई टुक्राहरूमा विभाजन गरेर स्पष्ट रूपमा समाधान प्रक्रिया देखाउँछ। यसले गणित, तर्कशक्ति, र बहु-चरण तर्कहरुको सटीकता सुधार्छ। +मोडेललाई आफ्नो तर्क चरण-द्वारा-चरण देखाउन भन्नुहोस्। सिधा उत्तरमा पुग्नुको सट्टा, मोडेलले समस्या विखण्डन गरी प्रत्येक भाग स्पष्ट रूपमा सञ्चाल गर्छ। यसले गणित, तर्क, र बहु-चरण तर्क कार्यहरूमा शुद्धता सुधार गर्छ। Chain of Thought Prompting -*चरण-द्वारा-चरण तर्क — जटिल समस्याहरूलाई स्पष्ट तर्कका चरणहरूमा विभाजित गर्दै* +*चरण-द्वारा-चरण तर्क — जटिल समस्याहरूलाई स्पष्ट तार्किक चरणहरूमा विभाजन गर्ने* ```java String prompt = """ @@ -132,16 +132,16 @@ String prompt = """ String response = model.chat(prompt); // मोडेलले देखाउँछ: १५ - ८ = ७, त्यसपछि ७ + १२ = १९ स्याउहरू ``` + +**कहिले प्रयोग गर्ने:** गणित समस्याहरू, तर्क पहेलीहरू, डिबगिङ, वा जहाँ तर्क प्रक्रिया देखाउनुले शुद्धता र विश्वास बढाउँछ। -**कहिले प्रयोग गर्ने:** गणित समस्या, तर्क पहेलीहरू, डिबगिङ, वा कुनै पनि कार्य जहाँ तर्क प्रक्रिया देखाउँदा सटीकता र विश्वास बढ्छ। +### भूमिका-आधारित प्रॉम्प्टिङ -### Role-Based Prompting - -तपाईंको प्रश्न सोध्नुअघि AI को लागि एउटा पात्र वा भूमिका सेट गर्नुहोस्। यसले सन्दर्भ प्रदान गर्छ जसले जवाफको शैली, गहिराई, र फोकस निर्धारण गर्छ। "सफ्टवेयर वास्तुकार" ले "जुनियर विकासकर्ता" वा "सुरक्षा अडिटर" भन्दा फरक सल्लाह दिन्छ। +तपाईंको प्रश्न सोध्नुअघि AI को एउटा पात्र वा भूमिका सेट गर्नुहोस्। यसले जवाफको स्वर, गहिराइ, र ध्यानलाई सन्दर्भ दिन्छ। "सफ्टवेयर आर्किटेक्ट" बाट फरक सल्लाह आउँछ "जुनियर डेभलपर" वा "सुरक्षा अडिटर" भन्दा। Role-Based Prompting -*सन्दर्भ र पात्र निर्धारण — एउटै प्रश्नलाई दिइने जवाफ भूमिका अनुसार फरक पर्छ* +*सन्दर्भ र पात्र सेट गर्दै — एउटै प्रश्नलाई भूमिका अनुसार फरक जवाफ प्राप्त* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` + +**कहिले प्रयोग गर्ने:** कोड समीक्षा, ट्युटोरिङ, डोमेन-विशिष्ट विश्लेषण, वा जब तपाईंलाई कुनै विशिष्ट विशेषज्ञता स्तर वा दृष्टिकोणअनुसार जवाफ चाहिन्छ। -**कहिले प्रयोग गर्ने:** कोड समीक्षा, ट्युटरिङ, डोमेन-विशेष विश्लेषण, वा जब तपाईंलाई निश्चित विशेषज्ञताको स्तर वा दृष्टिकोण अनुरूप जवाफ चाहिन्छ। - -### Prompt Templates +### प्रॉम्प्ट टेम्प्लेटहरू -पुन: प्रयोगयोग्य प्रम्प्टहरू variable placeholder हरू सहित सिर्जना गर्नुहोस्। प्रत्येक पटक नयाँ प्रम्प्ट लेख्नुभन्दा, एक पटक टेम्प्लेट परिभाषित गरेर फरक मानहरू भर्नुहोस्। LangChain4j को `PromptTemplate` क्लासले `{{variable}}` सिन्ट्याक्सलाई सहज बनाउँछ। +चर प्रतिस्थापनहरूसहित पुनः प्रयोग गर्न मिल्ने प्रॉम्प्टहरू बनाउनुहोस्। प्रत्येक पटक नयाँ प्रॉम्प्ट लेख्ने सट्टा, एउटा टेम्प्लेट परिभाषित गर्नुहोस् र फरक मानहरू भर्नुहोस्। LangChain4j को `PromptTemplate` वर्गले `{{variable}}` सिंट्याक्ससँग यो सजिलो बनाउँछ। Prompt Templates -*पुन: प्रयोगयोग्य प्रम्प्टहरू variable placeholder सहित — एउटा टेम्प्लेट, धेरै प्रयोग* +*चर प्रतिस्थापनहरूसहित पुन: प्रयोगयोग्य प्रॉम्प्टहरू — एउटा टेम्प्लेट, धेरै प्रयोगहरू* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**कहिले प्रयोग गर्ने:** फरक इनपुटहरूसँग पुनरावृत्त प्रश्नहरू, ब्याच प्रशोधन, पुन: प्रयोग योग्य AI कार्यप्रवाह निर्माण, वा कुनै पनि अवस्थामा जहाँ प्रम्प्ट संरचना उस्तै हुन्छ तर डाटा फरक हुन्छ। + +**कहिले प्रयोग गर्ने:** फरक इनपुटहरूसँग बारम्बार सोधिने प्रश्नहरू, ब्याच प्रसोधन, पुनः प्रयोगयोग्य AI कार्यप्रवाहहरू निर्माण गर्दा, वा कुनै पनि यस्तो परिदृश्य जहाँ प्रॉम्प्ट संरचना उस्तै हुन्छ तर डाटा फरक हुन्छ। --- -यी पाँच आधारभूतहरूले तपाईंलाई धेरै प्रम्प्टिङ कार्यहरूको लागि बलियो उपकरण सेट दिन्छ। यस मोड्युलको बाँकी भागले तीमा **आठ उन्नत ढाँचाहरू** थप्छ जुन GPT-5.2 को तर्क नियन्त्रण, आत्म-मूल्याङ्कन, र संरचित नतिजा क्षमताहरूलाई उपयोग गर्छ। +यी पाँच आधारभूतहरूले तपाईंलाई अधिकांश प्रॉम्प्टिङ कार्यहरूको लागि मजबूत उपकरण पछ्याउने मौका दिन्छ। बाँकी मोड्युल यीमा आधारित भएर **आठ उन्नत ढाँचाहरू** प्रस्तुत गर्छ जुन GPT-5.2 को तर्क नियन्त्रण, आत्म-मूल्याङ्कन, र संरचित आउटपुट क्षमताहरूलाई फाइदा लिन्छ। -## Advanced Patterns +## उन्नत ढाँचाहरू -आधारहरू कभर भएपछि, अब ती आठ उन्नत ढाँचाहरूमा जानुहोस् जुन यस मोड्युललाई विशेष बनाउँछ। सबै समस्याहरूलाई एउटै दृष्टिकोण चाहिँदैन। केही प्रश्नहरू छिटो जवाफ चाहिन्छ, काहीं गहिरो सोच आवश्यक छ। केहीले तर्क देखाउनुपर्छ, केहीले मात्र नतिजा चाहिन्छ। तलका प्रत्येक ढाँचा फरक परिदृश्यका लागि अनुकूलित छन् — र GPT-5.2 को तर्क नियन्त्रणले यी फरकहरू अझ स्पष्ट बनाउँछ। +आधारभूत कुराहरू समेटिसकेपछि, अब यी आठ उन्नत ढाँचाहरूमा जान्छौं जुन यो मोड्युललाई विशिष्ट बनाउँछन्। सबै समस्याहरू एउटै शैली माग्दैनन्। केही प्रश्नहरूमा छिटो उत्तर चाहिन्छ, अर्काहरूमा गहिरो सोच। केहीमा देखिने तर्क चाहिन्छ, अरूमा मात्र परिणाम। प्रत्येक तलको ढाँचा फरक परिदृश्यका लागि अनुकूलित छ — र GPT-5.2 को तर्क नियन्त्रणले यी भिन्नताहरू अझै प्रस्ट बनाउँछ। Eight Prompting Patterns -*आठ प्रम्प्ट इञ्जिनियरिङ ढाँचाहरू र तिनीहरूका प्रयोग केसहरूको अवलोकन* +*आठ प्रॉम्प्ट इन्जिनियरिङ ढाँचाहरू र तिनीहरूको प्रयोग केसहरूको अवलोकन* -GPT-5.2 ले यी ढाँचाहरूमा अर्को आयाम थप्छ: *तर्क नियन्त्रण*। तलको स्लाइडरले देखाउँछ कि तपाईं कसरी मोडेलको सोचाई प्रयास समायोजन गर्न सक्नुहुन्छ — छिटो, सिधा जवाफबाट गहिरो, विस्तृत विश्लेषणसम्म। +GPT-5.2 ले यी ढाँचाहरूमा अर्को आयाम थप्छ: *तर्क नियन्त्रण*। तलको स्लाइडरले देखाउँछ तपाईं मोडेलको सोचाइ प्रयास कसरी समायोजन गर्न सक्नुहुन्छ — छिटो, सिधा उत्तरदेखि गहिरो, विस्तारपूर्ण विश्लेषणसम्म। Reasoning Control with GPT-5.2 -*GPT-5.2 को तर्क नियन्त्रणले तपाईंलाई मोडेलले कति सोच्नु पर्छ — छिटो सिधा जवाफदेखि गहिरो अन्वेषणसम्म निर्धारण गर्न दिन्छ* +*GPT-5.2 को तर्क नियन्त्रणले तपाईंलाई मोडेलको कति सोच्नु पर्ने भनेर निर्दिष्ट गर्न दिन्छ — छिटो सिधा उत्तरदेखि गहिरो अन्वेषणसम्म* -**कम उत्साह (छिटो र केन्द्रीत)** - सरल प्रश्नहरूसँग छिटो, सिधा जवाफ चाहिँदा। मोडेलले न्यूनतम तर्क गर्छ - अधिकतम २ चरण। गणना, खोज, वा सोझो प्रश्नहरूको लागि प्रयोग गर्नुहोस्। +**कम उत्साह (छिटो & केन्द्रित)** - साधारण प्रश्नहरूका लागि जहाँ तपाईं छिटो, सिधा उत्तर चाहनुहुन्छ। मोडेल न्यूनतम तर्क गर्दछ - अधिकतम २ चरणहरू। गणना, खोज, वा सिधा प्रश्नहरूका लागि प्रयोग गर्नुहोस्। ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> 💡 **GitHub Copilot सँग अन्वेषण गर्नुहोस्:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) खोल्नुहोस् र सोध्नुहोस्: +> - "कम उत्साह र उच्च उत्साह प्रॉम्प्टिङ ढाँचाहरूमा के भिन्नता छ?" +> - "प्रॉम्प्टहरूमा XML ट्यागहरूले AI को जवाफलाई कसरी संरचना गर्छ?" +> - "कुन बेला आत्म-प्रतिबिम्बन ढाँचाहरू र सिधा निर्देशन प्रयोग गर्ने?" -> 💡 **GitHub Copilot सँग अन्वेषण गर्नुहोस्:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) खोल्नुहोस् र सोध्नुहोस्: -> - "कम उत्साह र उच्च उत्साह प्रम्प्टिङ ढाँचाहरूबीच के फरक छ?" -> - "प्रम्प्टहरूमा XML ट्यागहरूले AI को प्रतिक्रिया कसरी संरचना गर्न मद्दत गर्छ?" -> - "कहिले मैले आत्म-प्रतिबिम्ब ढाँचाहरू र कहिले सिधा निर्देशन प्रयोग गर्ने?" - -**उच्च उत्साह (गहिरो र विस्तृत)** - जटिल समस्याहरू जहाँ पूर्ण विश्लेषण चाहिन्छ। मोडेलले विस्तारमा अन्वेषण गर्छ र विस्तृत तर्क देखाउँछ। प्रणाली डिजाइन, वास्तुकला निर्णय, वा जटिल अनुसन्धानको लागि प्रयोग गर्नुहोस्। +**उच्च उत्साह (गहिरो & विस्तारपूर्ण)** - जटिल समस्याहरूका लागि जहाँ तपाईं समग्र विश्लेषण चाहानुहुन्छ। मोडेलले गहिरो अनुसन्धान गर्छ र विस्तारपूर्वक तर्क देखाउँछ। प्रणाली डिजाइन, वास्तुकला निर्णय, वा जटिल अनुसन्धानका लागि प्रयोग गर्नुहोस्। ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**कार्य सञ्चालन (चरण-द्वारा-चरण प्रगति)** - बहु-चरण कार्यप्रवाहहरूको लागि। मोडेलले प्रारम्भमा योजना दिन्छ, प्रत्येक चरणमा काम गर्दा वर्णन गर्छ, र अन्तमा सारांश दिन्छ। माइग्रेशन, कार्यान्वयन, वा कुनै पनि बहु-चरण प्रक्रियाको लागि प्रयोग गर्नुहोस्। + +**कार्य निष्पादन (चरण-द्वारा-चरण प्रगति)** - बहु-चरण कार्यप्रवाहहरूका लागि। मोडेलले पहिले योजना बनाउँछ, प्रत्येक चरणसँगै वर्णन गर्छ, अनि सारांश दिन्छ। माइग्रेशन, कार्यान्वयन, वा कुनै पनि बहु-चरण प्रक्रियामा प्रयोग गर्नुहोस्। ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +चेन-अफ-थट प्रॉम्प्टिङले स्पष्ट रूपमा मोडेललाई आफ्नो तर्क प्रक्रिया देखाउन भन्छ, जटिल कार्यहरूको लागि सही नतिजा ल्याउँछ। चरण-द्वारा-चरण विखण्डनले मानव र AI दुवैलाई तर्क बुझ्न मद्दत गर्छ। -Chain-of-Thought प्रम्प्टिङले मोडेललाई स्पष्ट रूपमा तर्क प्रक्रिया देखाउन भन्छ, जटिल कार्यहरूको सटीकता सुधार्न। चरण-द्वारा-चरण विभाजनले मानिस र AI दुवैलाई तर्क बुझ्न मद्दत गर्छ। - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat सँग प्रयास गर्नुहोस्:** यो ढाँचाबारे सोध्नुहोस्: -> - "म लामो समयमा चल्ने अपरेसनका लागि कार्य सञ्चालन ढाँचा कसरी अनुकूल गर्छु?" -> - "उत्पादन अनुप्रयोगहरूमा टुल प्राम्बलहरू संरचना गर्ने उत्तम अभ्यास के हुन्?" -> - "म UI मा माध्यमिक प्रगति अपडेटहरू कसरी कैद र प्रदर्शन गर्न सक्छु?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) च्याटसँग प्रयास गर्नुहोस्:** यस ढाँचाबारे सोध्नुहोस्: +> - "दीर्घकालीन अपरेसनहरूको लागि कार्य निष्पादन ढाँचालाई कसरी अनुकूल बनाउने?" +> - "उत्पादन एपहरूमा टूल प्रीएम्बलहरूको संरचना गर्न सर्वोत्तम अभ्यासहरू के के हुन्?" +> - "UI मा मध्यवर्ती प्रगति अपडेटहरू कसरी समात्ने र प्रदर्शन गर्ने?" -तलको चित्रले यो योजना → कार्यान्वयन → सारांश कार्यप्रवाह देखाउँछ। +तलको चित्रले यस योजना → कार्यान्वयन → सारांश कार्यप्रवाहलाई देखाउँछ। Task Execution Pattern *बहु-चरण कार्यहरूको लागि योजना → कार्यान्वयन → सारांश कार्यप्रवाह* -**आत्म-प्रतिबिम्बित कोड** - उत्पादन-स्तरको कोड सिर्जना गर्न। मोडेलले उत्पादन मापदण्ड अनुरूप त्रुटि ह्यान्डलिङ सहित कोड उत्पादन गर्छ। नयाँ सुविधाहरू वा सेवाहरू बनाउने बेला प्रयोग गर्नुहोस्। +**आत्म-प्रतिबिम्बन गर्ने कोड** - उत्पादन गुणस्तरीय कोड सिर्जना गर्न। मोडेलले उत्पादन मानकहरू अनुसार कोड जनरेट गर्छ र उचित त्रुटि व्यवस्थापन गर्छ। नयाँ सुविधाहरू वा सेवा निर्माण गर्दा प्रयोग गर्नुहोस्। ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -तलको चित्रले यस पुनरावृत्ति सुधार लूप देखाउँछ — कोड उत्पन्न गर्नुहोस्, मूल्यांकन गर्नुहोस्, कमजोरीहरू पहिचान गर्नुहोस्, र सुधार गर्दै उत्पादन स्तरसम्म पुग्नुहोस्। + +तलको चित्रले यो पुनरावृत्त सुधार चक्र देखाउँछ — निर्माण, मूल्याङ्कन, कमजोरी पहिचान, र सुधार जबसम्म कोड उत्पादन मानक पूरा गर्दैन। Self-Reflection Cycle -*पुनरावृत्ति सुधार लूप - उत्पन्न, मूल्याङ्कन, समस्याहरू चिन्हित, सुधार, पुनरावृत्ति* +*पुनरावृत्त सुधार चक्र - सिर्जना, मूल्याङ्कन, समस्या पहिचान, सुधार, दोहोर्याउनुहोस्* -**संरचित विश्लेषण** - निरन्तर मूल्याङ्कनका लागि। मोडेलले कोडलाई निश्चित ढाँचा (सहीपन, अभ्यासहरू, प्रदर्शन, सुरक्षा, मर्मतयोग्यता) अनुसार समीक्षा गर्छ। कोड समीक्षा वा गुणस्तर मूल्याङ्कनमा प्रयोग गर्न। +**संरचित विश्लेषण** - स्थिर मूल्याङ्कनका लागि। मोडेलले कोडलाई निश्चित फ्रेमवर्क (सहीपन, अभ्यासहरू, प्रदर्शन, सुरक्षा, मर्मतयोग्यता) प्रयोग गरी समीक्षा गर्छ। कोड समीक्षा वा गुणस्तर मूल्याङ्कनमा प्रयोग गर्नुहोस्। ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> **🤖 [GitHub Copilot](https://github.com/features/copilot) च्याटसँग प्रयास गर्नुहोस्:** संरचित विश्लेषणबारे सोध्नुहोस्: +> - "भिन्न प्रकारका कोड समीक्षाहरूका लागि विश्लेषण फ्रेमवर्क कसरी अनुकूल बनाउने?" +> - "संरचित आउटपुट प्रोग्रामेटिक रूपमा पार्स र कार्यान्वयन गर्ने उत्तम तरिका के हो?" +> - "विभिन्न समीक्षा सेसनहरूमा स्थिर गंभीरता स्तर कसरी सुनिश्चित गर्ने?" -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat सँग प्रयास गर्नुहोस्:** संरचित विश्लेषणबारे सोध्नुहोस्: -> - "म फरक प्रकारका कोड समीक्षा लागि विश्लेषण ढाँचा कसरी अनुकूल गर्न सक्छु?" -> - "संरचित नतिजालाई प्रोग्रामिङ रूपमा पार्स र प्रयोग गर्ने उत्तम तरिका के हो?" -> - "म विभिन्न समीक्षा सत्रहरूमा निरन्तर गम्भीरता स्तर कसरी सुनिश्चित गर्छु?" - -तलको चित्रले यो संरचित फ्रेमवर्क कसरी कोड समीक्षा निरन्तर वर्गीकरण र गम्भीरता स्तरहरूसँग व्यवस्थित गर्छ देखाउँछ। +तलको चित्रले कसरी यो संरचित फ्रेमवर्कले कोड समीक्षा स्थिर वर्गहरूमा र गंभीरता स्तरसहित व्यवस्थित गर्छ देखाउँछ। Structured Analysis Pattern -*गम्भीरता स्तरहरूसहित निरन्तर कोड समीक्षा फ्रेमवर्क* +*गंभीरता स्तर सहित स्थिर कोड समीक्षा फ्रेमवर्क* -**धेरै पटकको कुरा** - सन्दर्भ चाहिने संवादहरूको लागि। मोडेलले अघिल्लो सन्देशहरू सम्झन्छ र त्यसमा आधारित प्रतिक्रिया निर्माण गर्छ। अन्तर्क्रियात्मक सहायता सत्र वा जटिल Q&A का लागि प्रयोग गर्नुहोस्। +**बहु-टर्न च्याट** - सन्दर्भको आवश्यकता हुने संवादहरूका लागि। मोडेलले पहिलाका सन्देशहरू सम्झन्छ र तिनमा आधारित उत्तर दिन्छ। अन्तरक्रियात्मक सहयोग सत्र वा जटिल प्रश्नोत्तरका लागि प्रयोग गर्नुहोस्। ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -तलको चित्रले देखाउँछ कि कुरा सन्दर्भ कसरी प्रत्येक चरणसँग सङ्ग्रह हुन्छ र यो कत्तिको मोडेलको टोकन सीमासँग सम्बन्धित छ। + +तलको चित्रले संवाद सन्दर्भ कसरी अनेकौं टर्नमा जम्मा हुन्छ र मोडेलको टोकन सिमासँग कसरी सम्बन्धित छ देखाउँछ। Context Memory -*कसरी कुरा सन्दर्भ धेरै पटकहरूमा सङ्ग्रह भएर टोकन सीमा पुर्‍याउँछ* -**क्रमबद्ध तर्क** - दृश्य तर्क आवश्यक पर्ने समस्याहरूका लागि। मोडेल प्रत्येक चरणको स्पष्ट तर्क प्रदर्शन गर्छ। गणित समस्याहरू, तर्क पहेलीहरू, वा सोच्ने प्रक्रिया बुझ्न आवश्यक पर्दा यसलाई प्रयोग गर्नुहोस्। +*संवाद सन्दर्भ धेरै टर्नमा जम्मा हुँदै टोकन सीमा पुग्ने अवस्था* + +**क्रमबद्ध तर्क** - देख्न सकिने तार्किकता आवश्यक पर्ने समस्याहरूका लागि। मोडेलले प्रत्येक चरणको स्पष्ट तर्क देखाउँछ। गणित समस्याहरू, तर्क पहेलीहरू, वा सोच प्रक्रिया बुझ्न आवश्यक पर्दा प्रयोग गर्नुहोस्। ```java String prompt = """ @@ -397,14 +398,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -तलको चित्रले मोडेलले समस्याहरूलाई स्पष्ट, क्रमांकित तार्किक चरणहरूमा कसरी विभाजन गर्छ भनी देखाउँछ। + +तलको चित्रले मोडेलले समस्याहरू कसरी स्पष्ट, क्रमाङ्कित तार्किक चरणहरूमा विभाजन गर्छ देखाउँछ। Step-by-Step Pattern +*समस्या लाई स्पष्ट तार्किक चरणहरूमा तोड्ने* -*समस्याहरूलाई स्पष्ट तार्किक चरणहरूमा विभाजन गर्ने प्रक्रिया* - -**सीमित आउटपुट** - विशिष्ट ढाँचा आवश्यकताहरूका लागि जवाफहरू। मोडेलले ढाँचा र लम्बाइ नियमहरू कडाइका साथ पालन गर्छ। सारांशहरू वा सावधानीपूर्वक संरचना आवश्यक पर्दा यसको प्रयोग गर्नुहोस्। +**सीमित आउटपुट** - विशेष ढाँचा आवश्यकताहरू सहितका प्रतिक्रियाहरूका लागि। मोडेल कडाइका साथ ढाँचा र लम्बाइका नियमहरू पालना गर्छ। यसको प्रयोग सारांशहरूका लागि वा जब तपाईँलाई सटीक आउटपुट संरचना चाहिन्छ तब गर्नुहोस्। ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -तलको चित्रले कसरि सीमाहरू मोडेललाई तपाईंको ढाँचा र लम्बाइ आवश्यकताहरूको कडाईसँग पालन गर्न निर्देश गर्छ देखाउँछ। +तलको योजनाले देखाउँछ कसरी प्रतिबन्धहरूले मोडेललाई तपाईँको ढाँचा र लम्बाइ आवश्यकताहरूमा कडाइका साथ पालन गर्ने आउटपुट उत्पादन गर्न मार्गदर्शन गर्छ। -Constrained Output Pattern +सीमित आउटपुट ढाँचा -*विशिष्ट ढाँचा, लम्बाइ, र संरचना आवश्यकताहरूको पालन गर्ने* +*विशिष्ट ढाँचा, लम्बाइ, र संरचना आवश्यकताहरू लागू गर्दै* -## एप्लिकेशन चलाउनुहोस् +## अनुप्रयोग चलाउनुहोस् -**स्थापना पुष्टि गर्नुहोस्:** +**Deployment पुष्टि गर्नुहोस्:** -रुट डाइरेक्टरीमा `.env` फाइल अवश्य छ भन्ने सुनिश्चित गर्नुहोस् जसमा Azure क्रेडेन्सियलहरू छन् (Module 01 मा सिर्जना गरिएको)। यो मोड्युल डाइरेक्टरी (`02-prompt-engineering/`) बाट चलाउनुहोस्: +`.env` फाइल जडान डिरेक्टरीमा Azure प्रमाणपत्रहरूका साथ अवश्य हुनु पर्छ (Module 01 मा सिर्जना गरिएको)। यसलाई मोड्युल डिरेक्टरीबाट चलाउनुहोस् (`02-prompt-engineering/`): **Bash:** ```bash @@ -442,33 +442,33 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनु Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनु पर्छ ``` -**एप्लिकेशन सुरु गर्नुहोस्:** +**अनुप्रयोग सुरु गर्नुहोस्:** -> **सूचना:** यदि तपाईंले पहिले नै रुट डाइरेक्टरीबाट `./start-all.sh` प्रयोग गरी सबै एप्लिकेशनहरू सुरु गर्नुभएको छ (Module 01 मा वर्णन गरिएको), यो मोड्युल पोर्ट 8083 मा पहिले नै चलिरहेको छ। तपाईंले तलका सुरु गर्ने कमाण्डहरू छोडेर सिधै http://localhost:8083 मा जान सक्नुहुन्छ। +> **टीपा:** यदि तपाईँले पहिले नै सबै अनुप्रयोगहरूलाई `./start-all.sh` मार्फत रुट डिरेक्टरीबाट सुरु गर्नुभएको छ (Module 01 मा वर्णन गरिएको), यो मोड्युल पोर्ट 8083 मा पहिले नै चलिरहेको छ। तलका सुरु गर्ने आदेशहरू छोडेर सिधै http://localhost:8083 मा जान सक्नुहुन्छ। -**विकल्प 1: Spring Boot Dashboard प्रयोग गरेर (VS Code प्रयोगकर्ताहरूका लागि सिफारिस गरिएको)** +**विकल्प 1: Spring Boot Dashboard प्रयोग गर्दै (VS Code प्रयोगकर्ताहरुका लागि सिफारिश गरिन्छ)** -Dev container मा Spring Boot Dashboard एक्सटेन्शन समावेश गरिएको छ, जसले सबै Spring Boot एप्लिकेशनहरू व्यवस्थापन गर्न भिजुअल इन्टरफेस प्रदान गर्छ। VS Code को बाँया पट्टि Activity Bar मा यो फेला पार्न सकिन्छ (Spring Boot आइकन खोज्नुहोस्)। +डेभ कन्टेनरमा Spring Boot Dashboard विस्तार समावेश छ, जसले सबै Spring Boot अनुप्रयोगहरूलाई व्यवस्थापन गर्न भिजुअल इंटरफेस प्रदान गर्दछ। यसलाई VS Code को Activity Bar को बाँया तर्फ Spring Boot आइकनमा पत्ता लगाउन सकिन्छ। -Spring Boot Dashboard बाट तपाईंसँग के गर्न सकिन्छ: -- कार्यक्षेत्रमा सबै उपलब्ध Spring Boot एप्लिकेशनहरू हेर्नुहोस् -- एप्लिकेशनहरू एक क्लिकले सुरु/रोक्नुहोस् -- एप्लिकेशन लगहरू रियल-टाइममा हेर्नुहोस् -- एप्लिकेशन स्थिति अनुगमन गर्नुहोस् +Spring Boot Dashboard बाट तपाईं: +- कार्यस्थलमा उपलब्ध सबै Spring Boot अनुप्रयोगहरू देख्न सक्नुहुन्छ +- एउटै क्लिकले अनुप्रयोगहरू सुरु/रोक्न सक्नुहुन्छ +- अनुप्रयोग लगहरू वास्तविक समयमा हेर्न सक्नुहुन्छ +- अनुप्रयोग स्थिति अनुगमन गर्न सक्नुहुन्छ -"prompt-engineering" को छेउमा प्ले बटनमा क्लिक गरी यो मोड्युल सुरु गर्नुहोस्, वा सबै मोड्युलहरू एकैपटक सुरु गर्नुहोस्। +"prompt-engineering" को छेउमा प्ले बटन क्लिक गरेर यो मोड्युल सुरु गर्नुहोस्, वा सबै मोड्युलहरू एकै पटक सुरु गर्नुहोस्। Spring Boot Dashboard -*VS Code मा Spring Boot Dashboard — सबै मोड्युलहरू एकै ठाउँबाट सुरु, रोक, र अनुगमन गर्नुहोस्* +*VS Code मा Spring Boot Dashboard — सबै मोड्युलहरूलाई एउटै ठाउँबाट सुरु, रोक्न, र अनुगमन गर्नुहोस्* -**विकल्प २: shell scripts प्रयोग गरेर** +**विकल्प 2: Shell स्क्रिप्टहरू प्रयोग गर्दै** -सबै वेब एप्लिकेशनहरू (मोड्युल ०१-०४) सुरु गर्नुहोस्: +सबै वेब अनुप्रयोगहरू (मोड्युल 01-04): **Bash:** ```bash -cd .. # मूल निर्देशिका बाट +cd .. # रुट निर्देशिकाबाट ./start-all.sh ``` @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -दुवै स्क्रिप्टहरूले रुट `.env` फाइलबाट वातावरण सञ्झ्याल स्वतः लोड गर्छन् र जाभा JAR फाइलहरू नहुँदा बनाउँछन्। +दुवै स्क्रिप्टहरू स्वतः रुट `.env` फाइलबाट वातावरण चरहरू लोड गर्छन् र यदि JAR हरू छैनन् भने तिनीहरूलाई निर्माण गर्छन्। -> **सूचना:** यदि तपाईं सुरु गर्नु अघि सबै मोड्युलहरू म्यानुअली निर्माण गर्न चाहनुहुन्छ भने: +> **टीपा:** यदि तपाइँ सुरु गर्नु अघि सबै मोड्युलहरू म्यानुअली निर्माण गर्न चाहानुहुन्छ भने: > > **Bash:** > ```bash @@ -510,7 +510,7 @@ cd 02-prompt-engineering तपाईंको ब्राउजरमा http://localhost:8083 खोल्नुहोस्। -**रोक्नका लागि:** +**रोक्न:** **Bash:** ```bash @@ -526,71 +526,71 @@ cd .. && ./stop-all.sh # सबै मोड्युलहरू cd ..; .\stop-all.ps1 # सबै मोड्युलहरू ``` -## एप्लिकेशन स्क्रीनसटहरू +## अनुप्रयोग स्क्रिनशटहरू -यो "prompt engineering" मोड्युलको मुख्य ईन्टरफेस हो जहाँ तपाईं आठवटा पैटर्नहरू एकै साथ प्रयोग गर्न सक्नुहुन्छ। +यहाँ prompt engineering मोड्युलको मुख्य इन्टरफेस छ, जहाँ तपाइँले आठवटा ढाँचा सबै साइडमा राखेर प्रयोग गर्न सक्नुहुन्छ। -Dashboard Home +ड्यासबोर्ड होम -*मुख्य ड्यासबोर्ड जसले सबै ८ prompt engineering पैटर्नहरू उनीहरूको विशेषताहरू र प्रयोग केसहरूसहित देखाउँछ* +*मुख्य ड्यासबोर्ड जसले सबै ८ prompt engineering ढाँचाहरू देखाउँछ तिनका विशेषताहरू र प्रयोग केससँग* -## पैटर्नहरू अन्वेषण गर्दै +## ढाँचाहरू अन्वेषण गर्दै -वेब इन्टरफेसले तपाईंलाई विभिन्न prompting रणनीतिहरू प्रयोग गर्न दिन्छ। प्रत्येक पैटर्नले फरक-फरक समस्याहरू समाधान गर्छ - प्रयोग गरेर हेर्नुहोस् कुन तरिका कहिले राम्रो हुन्छ। +वेब इन्टरफेसले तपाइँलाई विभिन्न प्रवचिगर्मी रणनीतिहरूमा प्रयोग गर्ने मौका दिन्छ। प्रत्येक ढाँचाले फरक-फरक समस्याहरू समाधान गर्छ - कुन समयमा कुन विधि चम्किन्छ हेर्न प्रयास गर्नुहोस्। -> **सूचना: Streaming vs Non-Streaming** — सबै पैटर्न पृष्ठमा दुईवटा बटनहरू उपलब्ध छन्: **🔴 Stream Response (Live)** र **Non-streaming** विकल्प। Streaming ले Server-Sent Events (SSE) प्रयोग गरी मोडेलले टोकनहरू उत्पादन गर्दा तुरुन्त देखाउँछ, यसैले तपाईं प्रगति तुरुन्तै हेर्न सक्नुहुन्छ। Non-streaming विकल्पले पूरा जवाफ आएपछि मात्र देखाउँछ। गहिरो तर्क आवश्यक पर्ने प्रम्प्टहरूमा (जस्तै High Eagerness, Self-Reflecting Code) non-streaming धेरै समय लाग्न सक्छ — कहिलेकाहीं मिनेटौं — र कुनै दृश्य प्रतिक्रिया नआउन सक्छ। **जटिल प्रम्प्टहरूसँग प्रयोग गर्दा streaming प्रयोग गर्नुहोस्** ताकि तपाईं मोडेलको काम देख्न सक्नुहुनेछ र ढुक्क हुनुहुनेछ कि अनुरोध टाइमआउट भएको छैन। +> **टीपा: Streaming बनाम Non-Streaming** — प्रत्येक ढाँचाको पृष्ठले दुई बटनहरू प्रदान गर्छ: **🔴 Stream Response (Live)** र **Non-streaming** विकल्प। Streaming ले Server-Sent Events (SSE) प्रयोग गरेर टोकनहरू मोडलले सिर्जना गर्दै गरेको बखत वास्तविक समयमा देखाउँछ, जसले गर्दा तपाईँले प्रगति तुरुन्तै देख्नुहुन्छ। Non-streaming विकल्पले सबै प्रतिक्रिया आएपछि मात्र देखाउँछ। गहिरो विचार आवश्यक हुने प्रोत्साहन (जस्तै, High Eagerness, Self-Reflecting Code) को लागि, non-streaming कल निकै लामो समय लिन सक्छ — कहिलेकाहीँ मिनेटसम्म — बिना कुनै देखिने प्रतिक्रिया। **जटिल प्रोत्साहनमा प्रयोग गर्दा streaming प्रयोग गर्नुहोस्** ताकि मोडल काम गरिरहेको देख्न सक्नुहोस् र अनुरोध समय समाप्त भएको भ्रमबाट बच्न सक्नुहोस्। > -> **सूचना: ब्राउजर आवश्यकताहरू** — streaming सुविधाले Fetch Streams API (`response.body.getReader()`) प्रयोग गर्छ जुन पूर्ण ब्राउजर (Chrome, Edge, Firefox, Safari) मा मात्र काम गर्छ। VS Code को इन-बिल्ट Simple Browser मा यो काम गर्दैन किनकि यसको वेभ्भ्युले ReadableStream API समर्थन गर्दैन। यदि तपाईं Simple Browser प्रयोग गर्नुहुन्छ भने, non-streaming बटनहरूले सामान्य रूपमा काम गर्छन् - केवल streaming बटनहरू प्रभावित हुन्छन्। पूर्ण अनुभवका लागि `http://localhost:8083` बाह्य ब्राउजरमा खोल्नुहोस्। +> **टीपा: ब्राउजर आवश्यकताः** Streaming सुविधा Fetch Streams API (`response.body.getReader()`) प्रयोग गर्छ जुन पूर्ण ब्राउजर (Chrome, Edge, Firefox, Safari) मा मात्र काम गर्छ। VS Code को बिल्ट-इन Simple Browser मा काम गर्दैन, किनकि त्यहाँ ReadableStream API समर्थन छैन। यदि Simple Browser प्रयोग गर्नुहुन्छ भने non-streaming बटनहरू सामान्य रूपमा काम गर्नेछन् — केवल streaming बटनहरू प्रभावित हुन्छन्। पूर्ण अनुभवका लागि बाहिरी ब्राउजरमा `http://localhost:8083` खोल्नुहोस्। -### Low vs High Eagerness +### Low बनाम High Eagerness -"200 को 15% कति हो?" जस्तो सरल प्रश्न Low Eagerness प्रयोग गरेर सोध्नुहोस्। तपाईंलाई छिटो, सिधा जवाफ प्राप्त हुनेछ। अब "High-traffic API का लागि caching रणनीति डिजाइन गर्नुहोस्" जस्तो जटिल प्रश्न High Eagerness प्रयोग गरेर सोध्नुहोस्। **🔴 Stream Response (Live)** क्लिक गरी मोडेलको विस्तृत तर्क टोकन बट टोकन देख्नुहोस्। एउटै मोडेल, एउटै प्रश्न संरचना - तर प्रॉम्प्टले कति सोच्ने भनी निर्देशन दिन्छ। +"२०० को १५% के हो?" जस्तो सरल प्रश्न Low Eagerness प्रयोग गरेर सोध्नुहोस्। तपाईंलाई तुरुन्त, प्रत्यक्ष उत्तर प्राप्त हुनेछ। अब "उच्च Traffic API का लागि caching रणनीति डिजाइन गर्नुहोस्" जस्तो जटिल प्रश्न High Eagerness प्रयोग गरेर सोध्नुहोस्। **🔴 Stream Response (Live)** क्लिक गर्नुहोस् र मोडलका विस्तृत तार्किक विकास टोकन-द्वारा-टोकन हेर्नुहोस्। एउटै मोडल, एउटै प्रश्न संरचना - तर प्रोत्साहनले सोच्ने गहिराइ निर्देशन दिन्छ। -### कार्य निष्पादन (Tool Preambles) +### कार्यान्वयन कार्य (टुल प्रिप्रेबल्स) -धेरै चरण भएका कार्यहरू लागि पूर्व योजना र प्रगति विवरण फाइदाजनक हुन्छ। मोडेलले के गर्नेछ भनेर रूपरेखा बनाउँछ, प्रत्येक चरण वर्णन गर्छ, र परिणाम सारांश गर्छ। +बहु-चरण कार्यप्रवाहहरूले आरम्भिक योजना र प्रगति व्याख्या बाट फाइदा पाउँछन्। मोडलले के गर्नेछ भनेर झलक दिन्छ, प्रत्येक चरण भन्छ, अनि नतिजा सारांश गर्छ। ### Self-Reflecting Code -"इमेल मान्यकरण सेवा बनाउनुहोस्" प्रयास गर्नुहोस्। केवल कोड सिर्जना गरेर बन्द नगर्ने, मोडेल गुणस्तर मापदण्डअनुसार मूल्यांकन गर्दै, कमजोरी पहिचान गर्दै, र सुधार गर्दै जान्छ। तपाईंले उत्पादन स्तरसम्म कोड पुनरावृत्ति हुँदै जान्छ देख्नुहुनेछ। +"इमेल भ्यालिडेसन सेवा सिर्जना गर्नुहोस्" प्रयास गर्नुहोस्। कोड मात्र सिर्जना गरेर रोक्नुको सट्टा, मोडलले कोड सिर्जना गर्छ, गुणस्तर मापदण्डहरूसँग मूल्याङ्कन गर्छ, कमजोरीहरू पहिचान गर्छ, र सुधार गर्छ। तपाईंले देख्नुहुनेछ यो दोहोर्याउँदै उत्पादन स्तरसम्म आउँछ। ### संरचित विश्लेषण -कोड समीक्षा निरन्तर मूल्यांकन ढाँचा आवश्यक हुन्छ। मोडेलले कोडलाई निश्चित वर्गीकरण (ठीक हुनु, अभ्यासहरू, प्रदर्शन, सुरक्षा) र गम्भीरता स्तरहरूसहित विश्लेषण गर्छ। +कोड समीक्षा लागि स्थिर मूल्यांकन ढाँचाहरू आवश्यक हुन्छ। मोडलले कोडलाई निश्चित वर्गहरू (ठीकता, अभ्यास, प्रदर्शन, सुरक्षा) र गम्भीरता स्तरहरू सहित विश्लेषण गर्छ। -### मल्टि-टर्न च्याट +### बहु-टर्न संवाद -"Spring Boot के हो?" सोध्नुहोस् र तुरुन्त "उदाहरण देखाउ" सोध्नुहोस्। मोडेलले पहिलो प्रश्न सम्झिन्छ र तपाईंलाई Spring Boot को विशेष उदाहरण दिन्छ। सम्झनाहीन अवस्थामा दोस्रो प्रश्न धेरै अस्पष्ट हुन्छ। +"Spring Boot के हो?" सोध्नुहोस् र तुरुन्तै "मलाई एउटा उदाहरण देखाउनुहोस्" सोध्नुहोस्। मोडलले तपाईँको पहिलो प्रश्न सम्झन्छ र विशेष रूपमा Spring Boot को उदाहरण दिन्छ। सम्झना नहुँदा दोस्रो प्रश्न अस्पष्ट हुन्थ्यो। -### क्रमबद्ध तर्क +### चरण-द्वारा-चरण तर्क -गणितको समस्या रोजेर Step-by-Step Reasoning र Low Eagerness दुबै प्रयोग गर्नुहोस्। Low eagerness ले उत्तर मात्र दिन्छ - छिटो तर अस्पष्ट। Step-by-step ले प्रत्येक गणना र निर्णय देखाउँछ। +कुनै गणितको समस्या छनौट गर्नुहोस् र यसलाई चरण-द्वारा-चरण तर्क र Low Eagerness दुबै प्रयोग गरेर प्रयास गर्नुहोस्। Low eagerness यहाँ जवाफ तुरुन्त दिन्छ - छिटो तर अस्पष्ट। चरण-द्वारा-चरणले प्रत्येक गणना र निर्णय देखाउँछ। ### सीमित आउटपुट -विशिष्ट ढाँचा वा शब्द गणना आवश्यक पर्दा, यो पैटर्नले कडाइका साथ पालन गराउँछ। १०० शब्दको बुलेट पोइन्ट सारांश बनाउन प्रयास गर्नुहोस्। +जब तपाईँलाई विशेष ढाँचा वा शब्द गणना चाहिन्छ, यो ढाँचाले कडाइका साथ पालना गर्छ। ठीक १०० शब्दमा बुलेट बिन्दु ढाँचामा सारांश उत्पादन गर्ने प्रयास गर्नुहोस्। -## तपाईं के सिक्दै हुनुहुन्छ +## साँच्चिकै तपाइँ के सिक्दै हुनुहुन्छ **तर्क प्रयासले सबै कुरा परिवर्तन गर्छ** -GPT-5.2 ले तपाईंलाई प्रम्प्ट मार्फत कम्प्युटेशन प्रयास नियन्त्रण गर्न दिन्छ। कम प्रयासले छिटो उत्तर दिन्छ तर न्यूनतम अन्वेषण गर्छ। उच्च प्रयासले मोडेललाई गहिरो सोच्न समय दिन्छ। तपाईं कार्यको जटिलता अनुसार प्रयास मिलाउन सिक्दै हुनुहुन्छ - साधारण प्रश्नमा समय नबर्बाद गर्नुहोस्, तर जटिल निर्णयहरू तुरुन्त नगर्नुहोस्। +GPT-5.2 ले तपाइँलाई कम्प्युटेशनल प्रयासलाई तपाइँका प्रोत्साहनहरू मार्फत नियन्त्रण गर्न दिन्छ। कम प्रयासले छिटो प्रतिक्रिया र न्यूनतम अन्वेषण दिन्छ। उच्च प्रयासले मोडललाई गहिरो सोच्न समय दिन्छ। तपाइँ जटिलता अनुसार प्रयास म्याच गर्न सिक्दै हुनुहुन्छ - साधारण प्रश्नमा समय फाल्न नहोस्, तर जटिल निर्णयहरूमा पनि हतार नगर्नुहोस्। -**संरचनाले व्यवहार निर्देशित गर्छ** +**संरचनाले व्यवहार मार्गदर्शन गर्छ** -प्रम्प्टमा XML ट्यागहरूलाई ध्यान दिनुहोस? ती सजावट मात्र होइनन्। मोडेलहरू विनियोजित निर्देशनहरूलाई स्वतः पालन गर्छन्। मल्टि-स्टेप प्रक्रियाहरू वा जटिल तर्क आवश्यक पर्दा, संरचनाले मोडेललाई कहाँ छ र के गर्ने बताउँछ। तलको चित्रले राम्ररी संरचित प्रम्प्टलाई देखाउँछ जसमा ``, ``, ``, ``, और `` जस्ता ट्यागहरूले निर्देशनहरू स्पष्ट खण्डहरूमा व्यवस्थित गर्छन्। +प्रोत्साहनहरूमा XML ट्यागहरू देख्नुभयो? ती सजावट होइनन्। मोडेलहरू संरचित निर्देशनहरूलाई स्वतन्त्र पाठभन्दा बढी विश्वसनीय रूपमा पालन गर्छन्। जब तपाईँलाई बहु-चरण प्रक्रिया वा जटिल तर्क चाहिन्छ, संरचनाले मोडललाई थाहा दिन्छ यो कहाँ छ र के आउनेछ। तलको योजनाले राम्रो संरचित प्रोत्साहन कसरि ट्यागहरू ``, ``, ``, ``, र `` उपयोग गरेर स्पष्ट खण्डमा हरेक निर्देशनहरू विभाजन गर्छ देखाउँछ। -Prompt Structure +प्रोत्साहन संरचना -*स्पष्ट खण्डहरू र XML-शैली संगठनसहितको राम्ररी संरचित प्रम्प्टको बनावट* +*राम्रो संरचित प्रोत्साहनको शारीरिक संरचना जसमा स्पष्ट खण्डहरू र XML-जस्तो संगठन छ* -**गुणस्तर स्व-मूल्यांकनबाट हुन्छ** +**स्व-मूल्याङ्कनबाट गुणस्तर** -Self-reflecting पैटर्नहरूले गुणस्तर मापदण्ड स्पष्ट राख्छन्। मोडेललाई "सही" भन्नको सट्टा तपाईँले ठ्याक्कै के "सही" हो भनी बताउनुहुन्छ: सही तर्क, त्रुटि ह्यान्डलिङ, प्रदर्शन, सुरक्षा। त्यसपछि मोडेल आफ्नै आउटपुट मूल्यांकन गरी सुधार गर्छ। यसले कोड निर्माणलाई अनौठो प्रक्रियाबाट व्यवस्थित प्रक्रियामा बदल्छ। +स्व-प्रतिबिम्ब ढाँचाहरूले गुणस्तर मापदण्डहरू स्पष्ट पारेर काम गर्छन्। मोडलले "सही गरी गर्दछ" भन्ने आशामा नबसि तपाइँ यसलाई "सही" के हो ठ्याक्कै बताउनुहुन्छ: सही तर्क, त्रुटि व्यवस्थापन, प्रदर्शन, सुरक्षा। त्यसपछि मोडलले आफैंको आउटपुट मूल्याङ्कन गरेर सुधार्न सक्छ। यसले कोड उत्पादनलाई लट्री भन्दा प्रक्रिया बनाउँछ। **सन्दर्भ सीमित छ** -मल्टि-टर्न कुराकानी प्रत्येक अनुरोधसँग सन्देश इतिहास समेटेर काम गर्छ। तर सिमा हुन्छ - हरेक मोडेलसँग अधिकतम टोकन गणना हुन्छ। जति कुरा बढ्छ, तपाईंले सान्दर्भिक सन्दर्भ कायम राख्ने तर हद नाघ्ने छैन भन्ने रणनीति अपनाउनु पर्नेछ। यो मोड्युलले तपाईंलाई सम्झनाको काम सिकाउँछ; पछि तपाईंलाई जब सारांश बनाउन, कहिले बिर्सन, र कहिले पुनः प्राप्त गर्न भनेर सिकाइनेछ। +बहु-टर्न संवाद प्रत्येक अनुरोधसँग सन्देश इतिहास समावेश गरेर काम गर्दछ। तर सीमा छ - प्रत्येक मोडलको अधिकतम टोकन संख्या हुन्छ। संवाद बढ्दै जाँदा, तपाईँले सान्दर्भिक सन्दर्भलाई उक्त सीमा नछुने गरी राख्ने रणनीति आवश्यक पर्छ। यस मोड्युलले तपाईँलाई सम्झना कसरी काम गर्छ देखाउँछ; पछि तपाईँले कहिले सारांश गर्ने, कहिले बिर्सने, र कहिले पुनः प्राप्त गर्ने सिक्नुहुनेछ। ## अर्को कदमहरू @@ -598,11 +598,11 @@ Self-reflecting पैटर्नहरूले गुणस्तर मा --- -**नेभिगेसन:** [← अघिल्लो: Module 01 - परिचय](../01-introduction/README.md) | [मुख्यमा फर्कनुहोस्](../README.md) | [अर्को: Module 03 - RAG →](../03-rag/README.md) +**नेभिगेसन:** [← अघिल्लो: मोड्युल 01 - परिचय](../01-introduction/README.md) | [मुख्यमा फर्कनुहोस्](../README.md) | [अर्को: मोड्युल 03 - RAG →](../03-rag/README.md) --- **अस्वीकरण**: -यस दस्तावेजलाई AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरी अनुवाद गरिएको हो। हामी पूर्ण शुद्धताको प्रयास गरिरहेका छौं, तर कृपया ध्यान दिनुहोस् कि स्वचालित अनुवादमा त्रुटिहरू वा गल्तीहरू हुन सक्छन्। मूल दस्तावेजलाई त्यसको मूल भाषामा नै अधिकारसम्पन्न स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलतफहमी वा गलत व्याख्याको लागि हामी उत्तरदायी हौंन। +यो दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी सही हुन प्रयास गर्छौं, तर कृपया जानकार हुनुस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छन्। मूल दस्तावेज़ यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलत बुझाइ वा त्रुटिको लागि हामी जिम्मेवार छैनौं। \ No newline at end of file diff --git a/translations/ne/03-rag/README.md b/translations/ne/03-rag/README.md index 633537dc3..304049f7d 100644 --- a/translations/ne/03-rag/README.md +++ b/translations/ne/03-rag/README.md @@ -2,143 +2,142 @@ ## Table of Contents -- [Video Walkthrough](../../../03-rag) -- [What You'll Learn](../../../03-rag) -- [Prerequisites](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Does This Tutorial Use?](../../../03-rag) -- [How It Works](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload a Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matters](../../../03-rag) -- [Next Steps](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding RAG](#understanding-rag) + - [Which RAG Approach Does This Tutorial Use?](#which-rag-approach-does-this-tutorial-use) +- [How It Works](#how-it-works) + - [Document Processing](#document-processing) + - [Creating Embeddings](#creating-embeddings) + - [Semantic Search](#semantic-search) + - [Answer Generation](#उत्तर-सिर्जना) +- [Run the Application](#अनुप्रयोग-चलाउनुहोस्) +- [Using the Application](#अनुप्रयोग-प्रयोग-गर्दै) + - [Upload a Document](#कागजात-अपलोड-गर्नुहोस्) + - [Ask Questions](#प्रश्न-सोध्नुहोस्) + - [Check Source References](#स्रोत-संदर्भहरू-जाँच्नुहोस्) + - [Experiment with Questions](#प्रश्नहरूसँग-प्रयोग-गरेर-परीक्षण-गर्नुहोस्) +- [Key Concepts](#प्रमुख-अवधारणाहरू) + - [Chunking Strategy](#खण्ड-विभाजन-रणनीति) + - [Similarity Scores](#समानता-स्कोरहरू) + - [In-Memory Storage](#इन-मेमोरी-स्टोरेज) + - [Context Window Management](#सन्दर्भ-विन्डो-व्यवस्थापन) +- [When RAG Matters](#rag-कहिले-महत्वपूर्ण-हुन्छ) +- [Next Steps](#आगामी-चरणहरू) ## Video Walkthrough -यस मोड्युलसँग कसरी सुरु गर्ने भनेर व्याख्या गर्ने यो प्रत्यक्ष सत्र हेरौं: +यस मोड्युलसँग कसरी सुरु गर्ने भनेर व्याख्या गर्ने यो प्रत्यक्ष सत्र हेर्नुहोस्: RAG with LangChain4j - Live Session ## What You'll Learn -अघिल्ला मोड्युलहरूमा, तपाईंले एआईसँग कुराकानी कसरी गर्ने र आफ्नो प्रॉम्प्टहरूलाई प्रभावकारी रूपमा संरचना गर्ने सिक्नुभयो। तर एउटा मौलिक सीमा छ: भाषा मोडेलहरूले केवल प्रशिक्षणको क्रममा सिकेको कुरा मात्र जान्नेछन्। यी मोडेलहरूले तपाईंको कम्पनीका नीतिहरू, तपाईंको परियोजना कागजातहरू, वा जुनसुकै जानकारीमा तिनीहरूले प्रशिक्षण पाएका थिएनन् त्यस्ता प्रश्नहरूको जवाफ दिन सक्दैनन्। +अघिल्लो मोड्युलहरूमा, तपाईले AI सँग संवाद कसरी गर्ने र प्रभावकारी रूपमा तपाइँका प्रॉम्प्टहरू संरचना गर्ने तरिका सिक्नुभयो। तर एउटा मौलिक सीमितता छ: भाषा मोडेलहरूले केवल तिनीहरूले प्रशिक्षणका समयमा सिकेका कुराहरू मात्र जान्दछन्। तिनीहरूले तपाइँको कम्पनीको नीतिहरू, तपाइँको परियोजना कागजातहरू, वा कुनै पनि जानकारी जुन तिनीहरूले प्रशिक्षण पाएका थिएनन्, त्यस बारे प्रश्नहरूको उत्तर दिन सक्दैनन्। -RAG (Retrieval-Augmented Generation) ले यो समस्या समाधान गर्दछ। मोडेललाई तपाईंको जानकारी सिकाउन प्रयास गर्नुपर्ने सट्टा (जुन महँगो र अप्रयाप्त छ), तपाईंले यसलाई आफ्नो कागजातहरूमा खोजी गर्ने क्षमता दिनुहुन्छ। जब कसैले प्रश्न सोध्छ, प्रणाली सम्बन्धित जानकारी फेला पार्छ र त्यसलाई प्रॉम्प्टमा समावेश गर्दछ। त्यसपछि मोडेलले उठाइएको सन्दर्भको आधारमा जवाफ दिन्छ। +RAG (Retrieval-Augmented Generation) ले यो समस्या समाधान गर्छ। मोडेललाई तपाइँको जानकारी सिकाउने प्रयास गर्ने सट्टा (जुन महँगो र अप्रयोज्य छ), तपाईले यसलाई तपाइँका कागजातहरूमा खोजी गर्ने क्षमता दिनुहुन्छ। कसैले प्रश्न सोध्दा, सिस्टमले सान्दर्भिक जानकारी पत्ता लगाउँछ र प्रॉम्प्टमा समावेश गर्छ। त्यसपछि मोडेलले त्यो प्राप्त सन्दर्भको आधारमा उत्तर दिन्छ। -RAG लाई मोडेललाई एउटा सन्दर्भ पुस्तकालय दिने जस्तो सोच्नुहोस्। जब तपाईं प्रश्न सोध्नुहुन्छ, प्रणाली: +RAG लाई मोडेललाई एउटा सन्दर्भ पुस्तकालय दिने कामको रूपमा सोच्नुहोस्। जब तपाईले प्रश्न सोध्नुहुन्छ, सिस्टमले: -1. **प्रयोगकर्ता प्रश्न** - तपाईं प्रश्न सोध्नुहुन्छ -2. **इम्बेडिङ** - तपाईंको प्रश्नलाई भेक्टरमा रूपान्तरण गर्छ -3. **भेक्टर खोज** - मिल्दोजुल्दो कागजात टुक्राहरू फेला पार्छ -4. **सन्दर्भ संयोजन** - सम्बन्धित टुक्राहरू प्रॉम्प्टमा थप्छ -5. **उत्तर** - LLM ले सन्दर्भको आधारमा उत्तर उत्पादन गर्छ +1. **प्रयोगकर्ता सोधपुछ** - तपाईले प्रश्न सोध्नुहुन्छ +2. **एम्बेडिङ** - तपाईको प्रश्नलाई भेक्टरमा परिणत गर्दछ +3. **भेक्टर खोज** - समान कागजात टुक्राहरू पत्ता लगाउँछ +4. **सन्दर्भ विन्यास** - सम्बन्धित टुक्राहरू प्रॉम्प्टमा थप्दछ +5. **प्रतिक्रिया** - LLM ले सन्दर्भमा आधारित उत्तर उत्पन्न गर्दछ -यसले मोडेलका प्रतिक्रियाहरूलाई यसको प्रशिक्षण ज्ञानमा निर्भर नगरी तपाईंको वास्तविक डाटामा आधारित बनाउँछ। +यसले मोडेलको प्रतिक्रियाहरूलाई यसको प्रशिक्षण ज्ञानमा निर्भर नगरी तपाइँको वास्तविक डाटामा आधारित बनाउँछ। ## Prerequisites -- पूरा गरिसकिएको [Module 00 - Quick Start](../00-quick-start/README.md) (यो मोड्युलमा पछि उल्लेख गरिएको Easy RAG को उदाहरणका लागि) -- पूरा गरिसकिएको [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI स्रोतहरू तैनाथ गरिएको, जसमा `text-embedding-3-small` इम्बेडिङ मोडेल पनि समावेश छ) -- रूट डाइरेक्टरीमा `.env` फाइल जसमा Azure प्रमाणपत्रहरू छन् (Module 01 मा `azd up` द्वारा सिर्जना गरिएको) +- पूरा गरेको [Module 01 - परिचय](../01-introduction/README.md) (Azure OpenAI स्रोतहरू परिनियोजित, जसमा `text-embedding-3-small` एम्बेडिङ मोडेल समावेश छ) +- रूट डाइरेक्टरीमा `.env` फाइल Azure प्रमाणपत्रहरूसहित (Module 01 मा `azd up` द्वारा सिर्जित) -> **Note:** यदि तपाईंले Module 01 पूरा गर्नुभएन भने, पहिले त्यहाँका तैनाथी निर्देशनहरू पालना गर्नुहोस्। `azd up` आदेशले GPT च्याट मोडेल र यस मोड्युलमा प्रयोग गरिएको इम्बेडिङ मोडेल दुवै तैनाथ गर्दछ। +> **सूचना:** यदि तपाइँले Module 01 पूरा गर्नुभएन भने, पहिले त्यहाँको परिनियोजन निर्देशहरू पालना गर्नुहोस्। `azd up` कमाण्डले GPT च्याट मोडेल र यस मोड्युलद्वारा प्रयोग गरिएको एम्बेडिङ मोडेल दुवै परिनियोजित गर्दछ। ## Understanding RAG -तलको चित्रले मुख्य अवधारणा देखाउँछ: मोडेलको प्रशिक्षण डाटामा मात्र निर्भर नगरी, RAG ले यसलाई प्रत्येक उत्तर उत्पादन गर्नु अघि तपाईंका कागजातहरूको सन्दर्भ पुस्तकालय दिन्छ। +तलको चित्रले मूल अवधारणा देखाउँछ: मोडेलको प्रशिक्षण डाटा मात्रमा निर्भर नगरी, RAG ले प्रत्येक उत्तर उत्पन्न गर्ने अघि यसको सल्लाहका लागि तपाईका कागजातहरूको सन्दर्भ पुस्तकालय दिन्छ। What is RAG -*यो चित्रले पारम्परिक LLM (जसले प्रशिक्षण डाटाबाट अनुमान लगाउँछ) र RAG-संवर्धित LLM (जसले पहिलो तपाईंका कागजातहरू सल्लाह लिन्छ) बीचको भिन्नता देखाउँछ।* +*यो चित्रले मानक LLM (जो प्रशिक्षण डाटाबाट अनुमान लगाउँछ) र RAG-संवर्धित LLM (जो पहिलो पटक तपाईंका कागजातहरू सल्लाह गर्छ) बीचको फरक देखाउँछ।* -यहाँ टुक्राहरू कसरी अन्त्यदेखि अन्त्यसम्म जडान हुन्छन्। प्रयोगकर्ताको प्रश्न चार चरणमा बग्छ — इम्बेडिङ, भेक्टर खोज, सन्दर्भ संयोजन, र उत्तर उत्पादन — प्रत्येक अघिल्लो चरणमा आधारित: +यहाँ टुक्राहरू अन्त्यदेखि अन्त्यसम्म कसरी जडान हुन्छन् भन्ने वर्णन छ। प्रयोगकर्ताको प्रश्न चार चरणहरूमा बग्छ — एम्बेडिङ, भेक्टर खोज, सन्दर्भ विन्यास, र उत्तर उत्पन्न — जसले क्रमशः अघिल्लो चरणमा आधारित हुन्छ: RAG Architecture -*यो चित्रले अन्त्यदेखि अन्त्य RAG पाइपलाइन देखाउँछ — प्रयोगकर्ता प्रश्न इम्बेडिङ, भेक्टर खोज, सन्दर्भ संयोजन, र उत्तर उत्पादनबाट बग्छ।* +*यो चित्रले अन्त्यदेखि अन्त्य RAG पाइपलाइन देखाउँछ — प्रयोगकर्ता सोधपुछ एम्बेडिङ, भेक्टर खोज, सन्दर्भ विन्यास, र उत्तर उत्पन्न हुँदै जान्छ।* -यो मोड्युलको बाँकी भागले प्रत्येक चरणलाई विवरणसहित, तपाईंले चलाउन र परिमार्जन गर्न सक्ने कोडसहित प्रस्तुत गर्दछ। +यस मोड्युलको बाँकी भागले प्रत्येक चरणलाई विस्तृत रूपमा हिड्छ, जसमा तपाइँले चलाउन र परिमार्जन गर्न सक्ने कोडहरू हुन्छन्। ### Which RAG Approach Does This Tutorial Use? -LangChain4j ले RAG कार्यान्वयनका तीन तरिका प्रस्ताव गर्दछ, प्रत्येकमा फरक स्तरको अमूर्तता हुन्छ। तलको चित्रले तिनीहरूलाई सँगसँगै तुलना गर्दछ: +LangChain4j ले RAG लागू गर्न तीन तरिकाहरू प्रस्ताव गर्छ, प्रत्येक फरक स्तरको अमूर्तता संग। तलको चित्रले ती तीनलाई साइड-बाइ-साइड तुलना गर्दछ: Three RAG Approaches in LangChain4j -*यो चित्रले तीन LangChain4j RAG दृष्टिकोणहरू — Easy, Native, र Advanced — तुलना गर्दछ, तिनीहरूको मुख्य कम्पोनेन्टहरू र प्रयोग गर्ने बेला देखाउँदै।* +*यो चित्रले तीन LangChain4j RAG पहुँचहरू — Easy, Native, र Advanced — को तुलना गर्छ, तिनीहरूको प्रमुख कम्पोनेन्टहरू र कहिले प्रयोग गर्ने भनेर देखाउँछ।* -| दृष्टिकोण | के गर्छ | ट्रेड-अफ | +| Approach | के गर्छ | व्यापार-आफ | |---|---|---| -| **Easy RAG** | सबै कुरा `AiServices` र `ContentRetriever` मार्फत स्वतः तारिन्छ। तपाईं एउटा इन्टरफेस एनोटेट गर्नुहुन्छ, एक रिट्रीभर जोड्नुहुन्छ, र LangChain4j ले इम्बेडिङ, खोज र प्रॉम्प्ट संयोजन पछाडि ह्यान्डल गर्छ। | न्यूनतम कोड, तर तपाईंले प्रत्येक चरणमा के हुँदैछ त्यो देख्नुहुन्न। | -| **Native RAG** | तपाईं आफैंले इम्बेडिङ मोडेल कल गर्नुहुन्छ, स्टोर खोज्नुहुन्छ, प्रॉम्प्ट निर्माण गर्नुहुन्छ, र जवाफ उत्पन्न गर्नुहुन्छ — एक पटकमा एक स्पष्ट चरण। | बढी कोड, तर प्रत्येक चरण देखिने र परिमार्जन गर्न सकिने। | -| **Advanced RAG** | `RetrievalAugmentor` फ्रेमवर्क प्रयोग गर्छ, जससँग प्लग्गेबल क्वेरी ट्रान्सफर्मरहरू, राउटरहरू, पुनः रैंक गर्ने र कन्टेन्ट इन्जेक्टरहरू छन्, उत्पादन ग्रेड पाइपलाइनहरूको लागि। | अधिकतम लचिलोपन, तर धेरै जटिलता। | +| **Easy RAG** | सबै कुरा स्वतः `AiServices` र `ContentRetriever` मार्फत जडान गर्दछ। तपाईंले एउटा इन्टरफेस एनोटेट गर्नुहुन्छ, रिट्रिभर संलग्न गर्नुहुन्छ, र LangChain4j ले एम्बेडिङ, खोजी, र प्रॉम्प्ट विन्यास पछाडि ह्याण्डल गर्दछ। | न्यूनतम कोड, तर प्रत्येक चरण के भइरहेको छ देखिन्न। | +| **Native RAG** | तपाइँ आफैं एम्बेडिङ मोडेल कल गर्नुहुन्छ, स्टोर खोज्नुहुन्छ, प्रॉम्प्ट बनाउनुहुन्छ, र उत्तर उत्पन्न गर्नुहुन्छ — एउटा स्पष्ट चरणमा एक पटक। | बढी कोड, तर प्रत्येक चरण देखिन सक्ने र परिमार्जनयोग्य। | +| **Advanced RAG** | `RetrievalAugmentor` फ्रेमवर्क प्रयोग गरेर प्लगयोग्य क्वेरी ट्रान्सफर्मरहरू, राउटरहरू, रि-र्याङ्करहरू, र कन्टेन्ट इन्जेक्टरहरू उत्पादन-ग्रेड पाइपलाइनहरूको लागि। | अधिकतम लचकता, तर धेरै जटिलता। | -**यस ट्यutorial ले Native दृष्टिकोण प्रयोग गर्दछ।** RAG पाइपलाइनका प्रत्येक चरण — क्वेरी इम्बेडिङ, भेक्टर स्टोर खोज, सन्दर्भ संयोजन, र उत्तर उत्पादन — स्पष्ट रूपमा [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) मा लेखिएको छ। यो सचेत रूपमा गरिएको हो: सिक्नका लागि स्रोतको रूपमा, प्रत्येक चरण देख्न र बुझ्नुपर्ने कुराको महत्त्व बढी छ भने कोड कम गर्नु भन्दा। जब तपाईंलाई टुक्राहरू कसरी फिचर हुने सिक्न सहज हुन्छ, तब तपाईं छिटो प्रोटोटाइपहरूका लागि Easy RAG वा उत्पादन प्रणालीहरूको लागि Advanced RAG मा बढ्न सक्नुहुन्छ। +**यस ट्यूटोरियलले Native 접근 प्रयोग गर्दछ।** RAG पाइपलाइनको प्रत्येक चरण — प्रश्नलाई एम्बेडिङ, भेक्टर स्टोर खोज, सन्दर्भ विन्यास, र उत्तर उत्पन्न — स्पष्ट रूपमा [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) मा लेखिएको छ। यो जानाजानी गरिएको छ: सिकाइ स्रोतका रूपमा, प्रत्येक चरण देख्न र बुझ्न महत्वपूर्ण छ, कोडलाई कम गर्ने भन्दा। जब तपाईंलाई टुक्राहरू कसरी मेल खान्छ थाहा हुन्छ, तपाईं छिटो प्रोटोटाइपका लागि Easy RAG वा उत्पादन प्रणालीहरूको लागि Advanced RAG मा जान सक्नुहुन्छ। -> **💡 पहिले देखि Easy RAG देख्नुभएको छ?** [Quick Start मोड्युल](../00-quick-start/README.md) मा Document Q&A उदाहरण ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) छ जसले Easy RAG दृष्टिकोण प्रयोग गर्छ — LangChain4j ले स्वतः इम्बेडिङ, खोज र प्रॉम्प्ट संयोजन ह्यान्डल गर्छ। यो मोड्युलले त्यो पाइपलाइन खुलेर तपाईं आफैंले प्रत्येक चरण नियन्त्रण गर्न सक्ने बनाएर अर्को स्तरमा लैजान्छ। +> **💡 Easy RAG बारे जिज्ञासु?** LangChain4j ले एउटा *Easy RAG* पहुँच पनि प्रस्ताव गर्छ जहाँ `AiServices` र `ContentRetriever` एम्बेडिङ, खोजी, र प्रॉम्प्ट विन्यास स्वचालित रूपमा ह्याण्डल गर्छन्। यो मोड्युलले बढी स्पष्ट मार्ग लिन्छ — त्यो पाइपलाइन खोल्छ जहाँ तपाईं प्रत्येक चरण आफैं देख्न र नियन्त्रण गर्न सक्नुहुन्छ। -तलको चित्रले Quick Start उदाहरणबाट Easy RAG पाइपलाइन देखाउँछ। `AiServices` र `EmbeddingStoreContentRetriever` ले सबै जटिलता लुकाएका छन् — तपाईं कागजात लोड गर्नुहुन्छ, रिट्रीभर जोड्नुहुन्छ, र उत्तर प्राप्त गर्नुहुन्छ। यस मोड्युलको Native दृष्टिकोणले ती लुकिएका चरणहरू खोल्छ: +तल दिइएको चित्रले Easy RAG पाइपलाइन देखाउँछ। ध्यान दिनुहोस् कसरी `AiServices` र `EmbeddingStoreContentRetriever` सबै जटिलता लुकाउँछन्—तपाईँ कागजात लोड गर्नुहुन्छ, रिट्रिभर संलग्न गर्नुहुन्छ, र उत्तर प्राप्त गर्नुहुन्छ। यस मोड्युलको Native दृष्टिकोणले ती सबै लुकाएका चरणहरू फोड्छ: Easy RAG Pipeline - LangChain4j -*यो चित्र `SimpleReaderDemo.java` को Easy RAG पाइपलाइन देखाउँछ। यसलाई यस मोड्युलमा प्रयोग भएको Native दृष्टिकोणसँग तुलना गर्नुहोस्: Easy RAG ले `AiServices` र `ContentRetriever` पछाडि इम्बेडिङ, पुनःप्राप्ति र प्रॉम्प्ट संयोजन लुकाउँछ — तपाईं कागजात लोड गर्नुहुन्छ, रिट्रीभर जोड्नुहुन्छ, र उत्तर प्राप्त गर्नुहुन्छ। यो मोड्युलको Native दृष्टिकोणले ती पाइपलाइन खोल्छ र तपाईं आफैंले प्रत्येक चरण (इम्बेड, खोज, सन्दर्भ जोर्नु, उत्तर दिनु) कल गर्नुहुन्छ, यसले पूर्ण दृश्यता र नियन्त्रण दिन्छ।* +*यो चित्रले Easy RAG पाइपलाइन देखाउँछ। यसलाई यस मोड्युलमा प्रयोग गरिएको Native दृष्टिकोणसँग तुलना गर्नुहोस्: Easy RAG ले एम्बेडिङ, रिट्रिभल, र प्रॉम्प्ट विन्यासलाई `AiServices` र `ContentRetriever` पछाडि लुकाउँछ — तपाईंले कागजात लोड गर्नुहुन्छ, रिट्रिभर संलग्न गर्नुहुन्छ, र उत्तर पाउनुहुन्छ। यस मोड्युलको Native दृष्टिकोणले त्यो पाइपलाइन खोल्छ जहाँ तपाईं आफैं प्रत्येक चरण (एम्बेड, खोज, सन्दर्भ विन्यास, उत्पन्न) कल गर्नुहुन्छ, पूर्ण दृश्यता र नियन्त्रण प्राप्त गरिँदै।* ## How It Works -यस मोड्युलको RAG पाइपलाइन चार चरणहरूमा विभाजित हुन्छ जुन हरेक पटक प्रयोगकर्ताले प्रश्न सोध्दा क्रमिक रूपमा चल्छ। पहिलो, अपलोड गरिएको कागजातलाई **पार्स र टुक्र्याइन्छ** — व्यवस्थापन योग्य भागहरूमा। ती टुक्राहरूलाई त्यसपछि **भेक्टर इम्बेडिङहरू**मा रूपान्तरण गरिन्छ र भण्डारण गरिन्छ ताकि गणितीय रूपमा तुलना गर्न सकियोस्। जब प्रश्न आउँछ, प्रणाली सबैभन्दा सम्बन्धित टुक्राहरू फेला पार्न **सामान्य अर्थ खोज** गर्छ, र अन्तमा ती टुक्राहरूलाई सन्दर्भका रूपमा LLM लाई पठाइन्छ **उत्तर उत्पादन**का लागि। तलको अनुभागहरूले प्रत्येक चरणलाई वास्तविक कोड र चित्रहरूसहित व्याख्या गर्छ। पहिलो कदम हेरौं। +यस मोड्युलमा RAG पाइपलाइन चार चरणहरूमा विभाजित छ जुन प्रत्येक पटक प्रयोगकर्ताले प्रश्न सोध्दा क्रमिक रूपमा चल्छ। पहिले, अपलोड गरिएको कागजातलाई **पार्स र टुक्रा पारिन्छ** सजिलै व्यवस्थापन गर्न सकिने भागहरूमा। ती टुक्राहरूलाई त्यसपछि **भेक्टर एम्बेडिङहरू** मा परिणत गरी राखिन्छ ताकि गणितीय रूपमा तुलना गर्न सकिन्छ। जब एउटा सोधपुछ आउँछ, सिस्टमले सबैभन्दा सान्दर्भिक टुक्राहरू फेला पार्न **सामान्तरिक खोज** गर्छ, र अन्ततः तीलाई सन्दर्भका रूपमा LLM लाई पठाइन्छ **उत्तर उत्पन्न गर्न**। तलका अनुभागहरूले प्रत्येक चरणलाई वास्तविक कोड र चित्रहरूसँग हिड्छन्। पहिलो चरण हेरौं। ### Document Processing [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -जब तपाईं कागजात अपलोड गर्नुहुन्छ, प्रणालीले यसलाई (PDF वा साधारण पाठ) पार्स गर्छ, फाइलनाम जस्ता मेटाडेटा जोड्छ, र त्यसपछि टुक्र्याउँछ — सानाठुला भागहरू जसले मोडेलको सन्दर्भ विन्डोमा सहजै फिट हुन्छन्। ती टुक्राहरू सिमानामा सन्दर्भ नहराउने गरी हल्का ओभरल्याप गर्छन्। +जब तपाईं कागजात अपलोड गर्नुहुन्छ, सिस्टमले यसलाई पार्स गर्छ (PDF वा सामान्य पाठ), फाइलनाम जस्ता मेटाडाटा जोड्छ, र त्यसपछि टुक्रामा तोड्छ — स-साना भागहरू जुन मोडेलको सन्दर्भ विन्डोमा सहजै फिट हुन्छन्। ती टुक्राहरू थोरै ओभरलैप हुन्छन् ताकि सन्दर्भ सीमाहरूमा सन्दर्भ नखोउन। ```java -// अपलोड गरिएको फाइललाई पार्स गर्नुहोस् र LangChain4j Document मा र्याप गर्नुहोस् +// अपलोड गरिएको फाइल पार्स गर्नुहोस् र यसलाई LangChain4j डक्युमेन्टमा समेट्नुहोस् Document document = Document.from(content, metadata); -// ३० टोकन ओभरलैप सहित ३००-टोकन टुक्राहरूमा विभाजन गर्नुहोस् +// ३० टोकन ओभरलैप सहित ३००-टोकन खण्डहरूमा विभाजन गर्नुहोस् DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -तलको चित्रले यसलाई दृश्यात्मक रूपमा देखाउँछ। प्रत्येक टुक्राले आफ्नो छिमेकीसँग केहि टोकन साझा गर्छ — ३०-टोकन ओभरल्यापले कुनै पनि महत्त्वपूर्ण सन्दर्भ छुट्न नदिन्छ: +तलको चित्रले यसलाई दृश्यात्मक रूपमा देखाउँछ। ध्यान दिनुहोस् कसरी प्रत्येक टुक्राले आफ्नो छिमेकीहरूसँग केही टोकन साझा गर्छ — ३० टोकन ओभरलैपले कुनै महत्वपूर्ण सन्दर्भ बीचमा नपरोस् सुनिश्चित गर्छ: Document Chunking -*यो चित्रले एउटा कागजातलाई ३०0-टोकन टुक्राहरूमा ३०-टोकन ओभरल्यापका साथ विभाजित गरिरहेको देखाउँछ, टुक्राको सिमानामा सन्दर्भ संरक्षण गर्दै।* +*यो चित्रले कागजातलाई ३००-टोकन टुक्राहरूमा ३०-टोकन ओभरलैपसहित कसरी टुक्रा पारिन्छ भनेर देखाउँछ, टुक्राको सीमामा सन्दर्भ सुरक्षित गर्दै।* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat संग प्रयास गर्नुहोस्:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) खोल्नुहोस् र सोध्नुहोस्: -> - "LangChain4j ले कागजातलाई कसरी टुक्र्याउँछ र किन ओभरल्याप महत्वपूर्ण छ?" -> - "विभिन्न कागजात प्रकारहरूको लागि उत्तम टुक्रा आकार के हो र किन?" -> - "म कसरी बहुभाषिक वा विशेष स्वरूप भएका कागजातहरूलाई व्यवस्थापन गर्न सक्छु?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) च्याटसँग प्रयास गर्नुहोस्:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) खोल्नुहोस् र सोध्नुहोस्: +> - "LangChain4j कागजातहरूलाई टुक्रामा कसरी विभाजन गर्छ र किन ओभरलैप महत्वपूर्ण छ?" +> - "विभिन्न कागजात प्रकारका लागि उत्तम टुक्रा आकार के हो र किन?" +> - "मैले बहुभाषी कागजातहरू वा विशेष स्वरूपण भएका कागजातहरू कसरी व्यवस्थापन गर्ने?" ### Creating Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -प्रत्येक टुक्रालाई एउटा संख्यात्मक प्रतिनिधित्वमा रूपान्तरण गरिन्छ जुन इम्बेडिङ भनिन्छ — मूलत: अर्थ-देखि-संख्यामा रूपान्तरण। इम्बेडिङ मोडेल "बुद्धिमान" छैन जस्तो कि च्याट मोडेल हो; यो निर्देशनहरू पालना गर्न, तर्क गर्न, वा प्रश्नहरूको जवाफ दिन सक्दैन। यसले गर्नु पर्ने कार्य भनेको पाठलाई यति एक गणितीय स्थानमा नक्साङ्कन गर्नु हो जहाँ समान अर्थहरू नजिकै हुन्छन् — जस्तै "कार" र "ऑटोमोबाइल" नजिकै हुन्छन्, "रिफन्ड नीति" र "मेरो पैसा फिर्ता" नजिकै हुन्छन्। एक च्याट मोडेललाई तपाईंले कुरा गर्न सक्ने व्यक्तिको रुपमा सोच्नुहोस्; भने इम्बेडिङ मोडेल एउटा अत्यन्त राम्रो फाइलिङ प्रणाली हो। +प्रत्येक टुक्रालाई संख्यात्मक प्रतिनिधित्वमा परिणत गरिन्छ जसलाई एम्बेडिङ भनिन्छ — आधारभूत रूपमा अर्थ-देखि-संख्यामा रूपान्तरणकर्ता। एम्बेडिङ मोडेल "बुद्धिमान" च्याट मोडेल जस्तो होइन; यसले निर्देशन पालन गर्न, तर्क गर्न, वा प्रश्नहरूको उत्तर दिन सक्दैन। यसले केवल पाठलाई एउटा गणितीय स्थानमा नक्शांकन गर्छ जहाँ समान अर्थहरू नजिकै हुन्छन् — "कार" नजिक "अटोमोबाइल," "रिफन्ड नीति" नजिक "पैसा फिर्ता।" च्याट मोडेललाई एक व्यक्तिको रूपमा सोच्नुस् जससँग तपाईं कुरा गर्न सक्नुहुन्छ; एम्बेडिङ मोडेल भने एक अत्यन्त राम्रो फाइलिङ प्रणाली हो। -तलको चित्रले यो अवधारणा कल्पनात्मक रूपमा देखाउँछ — पाठ भित्र जान्छ, संख्यात्मक भेक्टरहरू बाहिर आउँछन्, र समान अर्थ भएका शब्दहरूले नजिकैका भेक्टरहरू उत्पादन गर्छन्: +तलको चित्रले यस अवधारणालाई दृश्यात्मक रूपमा देखाउँछ — पाठ भित्र जान्छ, संख्यात्मक भेक्टरहरू बाहिर आउँछन्, र समानार्थक अर्थहरू नजिकै हुने भेक्टरहरू उत्पादन गर्छ: Embedding Model Concept -*यो चित्रले कसरी इम्बेडिङ मोडेलले पाठलाई संख्यात्मक भेक्टरमा परिवर्तन गर्छ, र "कार" र "ऑटोमोबाइल" जस्ता समान अर्थलाई नजिकै राख्छ, देखाउँछ।* +*यो चित्रले कसरी एम्बेडिङ मोडेलले पाठलाई संख्यात्मक भेक्टरहरूमा परिणत गर्छ भनेर देखाउँछ, समान अर्थहरू - जस्तै "कार" र "अटोमोबाइल" - लाई भेक्टर स्पेसमा नजिक राख्दै।* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -तलको क्लास चित्रले RAG पाइपलाइनका दुई अलग बग्ने मार्गहरू देखाउँछ र LangChain4j का क्लासहरू जुन तिनीहरूलाई लागू गर्छन्। **इन्टेक प्रवाह** (अपलोड समयमा एक पटक चल्छ) ले कागजात फुटाउँछ, टुक्राहरू इम्बेड गर्छ, र `.addAll()` मार्फत भण्डारण गर्छ। **प्रश्न प्रवाह** (प्रत्येक पटक प्रयोगकर्ताले सोध्दा चल्छ) ले प्रश्न इम्बेड गर्छ, भण्डारणमा `.search()` मार्फत खोजी गर्छ, र मिल्ने सन्दर्भलाई च्याट मोडेलमा पठाउँछ। दुवै प्रवाहहरू साझा `EmbeddingStore` इन्टरफेसमा जडान हुन्छन्: +तलको कक्षा चित्रले RAG पाइपलाइनका दुई अलग-अलग प्रवाहहरू र तिनीहरूलाई कार्यान्वयन गर्ने LangChain4j कक्षाहरू देखाउँछ। **इंजेसन प्रवाह** (अपलोडको समयमा एक पटक चल्ने) कागजातलाई टुक्रा पार्छ, टुक्राहरूलाई एम्बेड गर्छ, र ती `.addAll()` मार्फत स्टोर गर्छ। **प्रश्न प्रवाह** (प्रत्येक पटक प्रयोगकर्ताले सोध्दा चल्ने) प्रश्नलाई एम्बेड गर्छ, `.search()` मार्फत स्टोर खोज्छ, र मेल खाने सन्दर्भलाई च्याट मोडेलमा पठाउँछ। दुबै प्रवाह साझा `EmbeddingStore` इन्टरफेसमा भेटिन्छन्: LangChain4j RAG Classes -*यो चित्रले RAG पाइपलाइनका दुई प्रवाहहरू — इन्टेक र प्रश्न — र कसरी साझा EmbeddingStore मार्फत जडान हुन्छन् देखाउँछ।* +*यो चित्रले RAG पाइपलाइनका दुई प्रवाहहरू — इंजेसन र प्रश्न — र कसरी तिनीहरू साझा EmbeddingStore मार्फत जडान हुन्छन् देखाउँछ।* -एक पटक इम्बेडिङहरू भण्डारण भएपछि, समान सामग्री स्वाभाविक रूपमा भेक्टर स्पेसमा समूहबद्ध हुन्छ। तलको दृष्यले देखाउँछ कि सम्बन्धित विषयहरूका कागजातहरू कसरी नजिकैका बिन्दुहरूमा परिणत हुन्छन्, जसले semantic search सम्भव बनाउँछ: +एक पटक एम्बेडिङहरू स्टोर भएपछि, समान सामग्री स्वाभाविक रूपमा भेक्टर स्पेसमा समूहबद्ध हुन्छ। तलको दृश्यले देखाउँछ कसरी सम्बन्धित विषयहरूबारे कागजातहरू नजिकै पोइन्टहरूमा परिणत हुन्छन्, जसले सामान्तरिक खोज सम्भव बनाउँछ: Vector Embeddings Space -*यो दृष्यले देखाउँछ कसरी प्राविधिक कागजात, व्यवसाय नियमहरू, र FAQs जस्ता विषयहरू 3D भेक्टर स्पेसमा अलग-अलग समूहहरूमा विभाग हुन्छन्।* +*यो दृश्यले देखाउँछ कसरी सम्बन्धित कागजातहरू ३D भेक्टर स्पेसमा समूहित हुन्छन्, जस्तै प्राविधिक कागजातहरू, व्यापार नियमहरू, र FAQs अलग-अलग समूहहरू बनाउँदै।* -जब प्रयोगकर्ताले खोजी गर्छ, प्रणालीले चार चरणहरूमा काम गर्छ: कागजातहरूलाई एक पटक इम्बेड गर्छ, प्रत्येक खोजीमा प्रश्न इम्बेड गर्छ, प्रश्न भेक्टरलाई सबै भण्डारण भेक्टरहरूसँग कोसाइन सादृश्यता प्रयोग गरेर तुलना गर्छ, र शीर्ष-K उच्च स्कोर भएका टुक्राहरू फर्काउँछ। तलको चित्रले प्रत्येक चरण र LangChain4j क्लासहरू देखाउँछ: +जब प्रयोगकर्ताले खोजी गर्छ, प्रणालीले चार चरणहरू पालना गर्छ: कागजातहरूलाई एक पटक एम्बेड गर्छ, प्रत्येक खोजमा प्रश्न एम्बेड गर्छ, प्रश्न भेक्टरलाई सबै स्टोर गरिएका भेक्टरहरूसँग कोसाइन समानताले तुलना गर्छ, र शिर्ष-K सबैभन्दा उच्च स्कोर गरिएका टुक्राहरू फिर्ता गर्छ। तलको चित्रले प्रत्येक चरण र यसमा संलग्न LangChain4j कक्षाहरू देखाउँछ: Embedding Search Steps -*यो चित्रले चार चरणको इम्बेडिङ खोज प्रक्रियालाई देखाउँछ: कागजातहरू इम्बेड गर्नु, प्रश्न इम्बेड गर्नु, कोसाइन सादृश्यता संग भेक्टरहरू तुलना गर्नु, र शीर्ष-K परिणामहरू फर्काउनु।* +*यो चित्रले चार-चरणको एम्बेडिङ खोज प्रक्रिया देखाउँछ: कागजातहरू एम्बेड, प्रश्न एम्बेड, कोसाइन समानतासँग भेक्टर तुलना, र शीर्ष-K नतिजा फिर्ता।* ### Semantic Search [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -जब तपाईं प्रश्न सोध्नुहुन्छ, तपाईंको प्रश्न पनि इम्बेडिङमा परिणत हुन्छ। प्रणालीले तपाईंको प्रश्नको इम्बेडिङ सबै कागजात टुक्राहरूको इम्बेडिङसँग तुलना गर्छ। यसले सबैभन्दा समान अर्थ भएका टुक्राहरू फेला पार्छ — केवल समान कुञ्जीशब्द मात्र होइन, वास्तविक सान्दर्भिक समानता। +जब तपाईले प्रश्न सोध्नुहुन्छ, तपाइँको प्रश्न पनि एम्बेडिङ बन्छ। प्रणालीले तपाइँको प्रश्नको एम्बेडिङलाई सबै कागजात टुक्राहरूको एम्बेडिङसँग तुलना गर्छ। यो सबैभन्दा समानार्थक अर्थ भएका टुक्राहरू फेला पार्छ - मात्र मिल्दोजुल्दो कुञ्जीशब्दहरू होइन, तर वास्तविक सामान्तरिक समानता। ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -तलको चित्रले semantic search र पारम्परिक कुञ्जीशब्द खोजी विरोधाभास देखाउँछ। "vehicle" शब्दको कुञ्जीशब्द खोजीले "cars and trucks" को एउटा टुक्रा छुटाउँछ, तर semantic search ले बुझ्छ कि तिनीहरू एउटै कुरा हुन् र यसलाई उच्च स्कोर दिने मिल्दोजुल्दो परिणामको रूपमा फर्काउँछ: +तलको चित्रले सामान्तरिक खोजलाई परम्परागत कुञ्जीशब्द खोजसँग तुलना गर्छ। "vehicle" को लागि कुञ्जीशब्द खोजले "cars and trucks" बारेको टुक्रा छुटाउँछ, तर सामान्तरिक खोजले बुझ्छ कि तिनीहरूको अर्थ उस्तै हो र यसलाई उच्च स्कोरसहित फिर्ता ल्याउँछ: Semantic Search -*यो चित्रले कुञ्जीशब्द आधारित खोज र semantic खोजको तुलना गर्दछ, देखाउँदै कि semantic खोजले अवधारणा अनुसार सम्बन्धित सामग्री पुनःप्राप्त गर्दछ भले नै ठ्याक्कै कुञ्जीशब्दहरू फरक किन नहुन्।* -अन्तर्भागमा, समानता कोसाइन समानता प्रयोग गरेर मापन गरिन्छ — सैद्धान्तिक रूपमा सोधिन्छ "के यी दुई तीरहरू एउटै दिशामा संकेत गर्दैछन्?" दुई टुक्राहरूले पूरै फरक शब्दहरू प्रयोग गर्न सक्छन्, तर यदि तिनीहरूको अर्थ एउटै हो भने तिनीहरूको भेक्टरहरू एउटै दिशामा संकेत गर्छन् र स्कोर 1.0 नजिक हुन्छ: +*यो चित्रले कुञ्जीशब्द-आधारित खोज र सामान्तरिक खोजको तुलना गर्छ, देखाउँदै कसरी सामान्तरिक खोजले विचारसंग सम्बन्धित सामग्री फिर्ता ल्याउँछ जब कि सटीक कुञ्जीशब्दहरू फरक हुन्छन्।* -Cosine Similarity +भित्री रूपमा, समानता मापन गर्न कोसाइन समानता प्रयोग गरिन्छ — मूलत: सोध्दैछ "यी दुई तीरहरू एउटै दिशामा छन् कि छैनन्?" दुई टुक्राहरूले पूर्ण रूपमा फरक शब्दहरू प्रयोग गर्न सक्छन्, तर यदि तिनीहरूको अर्थ उस्तै छ भने तिनीहरूको भेक्टरहरू एउटै दिशातर्फ संकेत गर्छन् र 1.0 नजिक स्कोर गर्छन्: -*यो चित्रले एम्बेडिङ भेक्टरहरू बीचको कोणको रूपमा कोसाइन समानता देखाउँछ — अधिक सटिक भएका भेक्टरहरू 1.0 नजिकको स्कोर पाउँछन्, जसले उच्च सेम्यान्टिक समानता जनाउँछ।* +Cosine Similarity +*यस आलेखले कसमाइन समानताका रूपमा एम्बेडिङ वेक्टरहरूबीचको कोण देखाउँछ — अधिक सुसंगत वेक्टरहरूले 1.0 नजिक स्कोर प्राप्त गर्छन्, जसले उच्च सिमान्टिक समानता जनाउँछ।* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) च्याटसँग प्रयास गर्नुहोस्:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) खोल्नुस् र सोध्नुस्: -> - "एम्बेडिङ्ससँग समानता खोज कसरी काम गर्छ र स्कोर के निर्धारण गर्छ?" -> - "कस्तो समानता थ्रेसहोल्ड प्रयोग गर्नु पर्छ र यसले नतिजामा कसरी प्रभाव पार्छ?" -> - "जहाँ कुनै सान्दर्भिक कागजात भेटिंदैन, त्यस्ता केसहरू कसरी ह्यान्डल गर्ने?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat सँग प्रयास गर्नुहोस्:** खुला गर्नुहोस् [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) र सोध्नुहोस्: +> - "एम्बेडिङहरूसँग समानता खोज कसरी काम गर्छ र स्कोर के द्वारा निर्धारण हुन्छ?" +> - "म कस्तो समानता थ्रेसहोल्ड प्रयोग गर्ने र यसले नतिजामा कसरी असर गर्छ?" +> - "जब कुनै सान्दर्भिक कागजातहरू फेला पर्दैनन् भने म कसरी व्यवहार गर्ने?" -### उत्तर निर्माण +### उत्तर सिर्जना [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -सबैभन्दा सान्दर्भिक टुक्राहरू संरचित प्रॉम्प्टमा सङ्कलन गरिन्छ जसले स्पष्ट निर्देशनहरू, प्राप्त सन्दर्भ, र प्रयोगकर्ताको प्रश्न समावेश गर्दछ। मोडेलले ती विशिष्ट टुक्राहरू पढ्छ र त्यहि जानकारीको आधारमा जवाफ दिन्छ — यो केवल यसको अघि रहेको जानकारी मात्र प्रयोग गर्न सक्छ, जसले भ्रान्तिलाई रोक्छ। +सबैभन्दा सान्दर्भिक खण्डहरूलाई स्पष्ट निर्देशनहरू, प्राप्त सन्दर्भ, र प्रयोगकर्ताको प्रश्न समावेश गरिएको संरचित प्रॉम्प्टमा सङ्गठित गरिन्छ। मोडेलले ती विशेष खण्डहरू पढ्छ र सो जानकारीको आधारमा उत्तर दिन्छ — यसले केवल सामु जानकारिलाई मात्र प्रयोग गर्न सक्छ, जसले भ्रम टार्छ। ```java String context = matches.stream() @@ -237,95 +236,95 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -तलको चित्रले यस सङ्ग्रह प्रक्रिया देखाउँछ — खोज चरणबाट सबैभन्दा उच्च स्कोर भएका टुक्राहरू प्रॉम्प्ट टेम्प्लेटमा राखिन्छन्, र `OpenAiOfficialChatModel` एक आधारभूत जवाफ तयार गर्छ: +तलको चित्रले यस सङ्गठनलाई देखाउँछ — खोज चरणबाट शीर्ष स्कोर प्राप्त खण्डहरू प्रॉम्प्ट टेम्प्लेटमा थपिन्छन्, र `OpenAiOfficialChatModel` ले आधारभूत उत्तर उत्पन्न गर्छ: Context Assembly -*यो चित्रले देखाउँछ कसरी सबैभन्दा उच्च स्कोर टुक्राहरू संरचित प्रॉम्प्टमा सङ्ग्रह गरिन्छ, जसले मोडेललाई तपाईँको डेटा बाट एक आधारभूत उत्तर उत्पादन गर्न अनुमति दिन्छ।* +*यस चित्रले देखाउँछ कि शीर्ष स्कोर प्राप्त खण्डहरू कसरी संरचित प्रॉम्प्टमा सङ्गठित गरिन्छन्, जसले मोडेललाई तपाईंको डाटाबाट आधारभूत उत्तर दिन सक्षम बनाउँछ।* -## अनुप्रयोग चलाउने +## अनुप्रयोग चलाउनुहोस् -**परिनियोजन सुनिश्चित गर्नुहोस्:** +**परिनियोजन जाँच गर्नुहोस्:** -रुट डाइरेक्टरीमा `.env` फाइल हुनु पर्छ जुन Azure प्रमाणपत्रहरू राख्छ (मोड्युल ०१ मा बनाइयो)। यसलाई मोड्युल डाइरेक्टरी (`03-rag/`) बाट चलाउनुहोस्: +मोड्युल ०१ मा सिर्जना गरिएको Azure प्रमाणपत्रहरू सहितको `.env` फाइल मूल डाइरेक्टरीमा रहेको सुनिश्चित गर्नुहोस्। यो मोड्युल डाइरेक्टरी (`03-rag/`) मा यो कमाण्ड चलाउनुहोस्: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनु पर्छ +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनुपर्छ ``` - + **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनु पर्छ +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनुपर्छ ``` - -**अनुप्रयोग सुरु गर्न:** -> **नोट:** यदि तपाईंले पहिले नै `./start-all.sh` प्रयोग गरेर सबै अनुप्रयोगहरू सुरु गरिसक्नुभएको छ भने (जसरी मोड्युल ०१ मा वर्णन गरिएको छ), यो मोड्युल पोर्ट ८०८१ मा पहिले नै चलिरहेको छ। तपाईँ तलका सुरु गर्ने कमाण्डहरू छोडेर सिधा http://localhost:8081 मा जान सक्नुहुन्छ। +**अनुप्रयोग सुरू गर्नुहोस्:** -**विकल्प १: Spring Boot ड्यासबोर्ड प्रयोग गर्नुहोस् (VS Code प्रयोगकर्ताहरूको लागि सिफारिस गरिएको)** +> **सूचना:** यदि तपाईंले पहिले नै सबै अनुप्रयोगहरू `./start-all.sh` प्रयोग गरेर मूल डाइरेक्टरीबाट सुरु गर्नुभएको छ भने (जसरी मोड्युल ०१ मा वर्णन गरिएको छ), यो मोड्युल पोर्ट 8081 मा पहिले नै चलिरहेको हुन्छ। तपाईंले तलका सुरु आदेशहरू स्किप गर्न सक्नुहुन्छ र सिधै http://localhost:8081 मा जान सक्नुहुन्छ। -डेभ कन्टेनरमा Spring Boot Dashboard एक्सटेन्सन समावेश छ, जसले सबै Spring Boot अनुप्रयोगहरू व्यवस्थापन गर्न दृश्यात्मक इन्टरफेस प्रदान गर्दछ। यो VS Code को बाँया छेउको Activity Bar मा पाउन सकिन्छ (Spring Boot आइकन हेर्नुहोस्)। +**विकल्प १: Spring Boot ड्यासबोर्ड प्रयोग गर्दै (VS Code प्रयोगकर्ताहरूका लागि सिफारिस गरिएको)** -Spring Boot Dashboard बाट तपाईं: -- कार्यक्षेत्रका सबै उपलब्ध Spring Boot अनुप्रयोगहरू हेर्न सक्नुहुन्छ -- एक क्लिकमा अनुप्रयोग सुरु/रोक्न सक्नुहुन्छ -- अनुप्रयोगको लगहरू वास्तविक समयमा हेर्न सक्नुहुन्छ +डिभ कन्टेनरमा Spring Boot ड्यासबोर्ड एक्सटेन्सन समावेश छ, जसले सबै Spring Boot अनुप्रयोगहरूलाई दृश्यात्मक इन्टरफेसबाट व्यवस्थापन गर्न सुविधा दिन्छ। तपाईं यसलाई VS Code को बायाँ तर्फ Activity Bar मा Spring Boot आइकनमा देख्न सक्नुहुन्छ। + +Spring Boot ड्यासबोर्डबाट, तपाईंले: +- कार्यक्षेत्रमा उपलब्ध सबै Spring Boot अनुप्रयोगहरू देख्न सक्नुहुन्छ +- एक क्लिकमा अनुप्रयोगहरू सुरु/रोक्न सक्नुहुन्छ +- अनुप्रयोग लगहरू वास्तविक समयमा हेर्न सक्नुहुन्छ - अनुप्रयोगको स्थिति अनुगमन गर्न सक्नुहुन्छ -"rag" को छेउमा प्ले बटन क्लिक गरी यो मोड्युल सुरु गर्नुस्, वा सबै मोड्युलहरू एकै पटक सुरु गर्न सक्नुहुन्छ। +"rag" को छेउमा प्ले बटन क्लिक गरेर यो मोड्युल सुरु गर्नुहोस्, वा सबै मोड्युलहरू एकैपटक सुरु गर्नुहोस्। Spring Boot Dashboard -*यो स्क्रिनसटले VS Code मा Spring Boot Dashboard देखाउँछ, जहाँ तपाईं अनुप्रयोगहरू सुरु, रोक्न र अनुगमन गर्न सक्नुहुन्छ।* +*यस स्क्रिनशटले VS Code मा Spring Boot ड्यासबोर्ड देखाउँछ, जहाँ तपाईं अनुप्रयोगहरू सुरु, रोक्न र अनुगमन गर्न सक्नुहुन्छ।* -**विकल्प २: शेल स्क्रिप्टहरू प्रयोग गर्नुहोस्** +**विकल्प २: शेल स्क्रिप्टहरू प्रयोग गर्दै** -सबै वेब अनुप्रयोगहरू (मोड्युल ०१-०४) सुरु गर्न: +सबै वेब अनुप्रयोगहरू (मोड्युल ०१-०४): **Bash:** ```bash cd .. # रुट डाइरेक्टरीबाट ./start-all.sh ``` - + **PowerShell:** ```powershell -cd .. # रूट निर्देशिका बाट +cd .. # रुट निर्देशिकाबाट .\start-all.ps1 ``` - -वा यो मोड्युल मात्र सुरु गर्न: + +वा केवल यो मोड्युल सुरु गर्नुहोस्: **Bash:** ```bash cd 03-rag ./start.sh ``` - + **PowerShell:** ```powershell cd 03-rag .\start.ps1 ``` - -दुबै स्क्रिप्टहरूले स्वतः रुट `.env` फाइलबाट वातावरण चरहरू लोड गर्छन् र यदि JAR फाइलहरू छैनन् भने तिनीहरू बनाउँछन्। -> **नोट:** यदि तपाईंले सबै मोड्युलहरू म्यान्युअली बिल्ड गर्न चाहनुहुन्छ भने सुरु गर्नु अघि: +दुवै स्क्रिप्टहरूले मूल `.env` फाइलबाट वातावरण चरहरू स्वचालित रूपमा लोड गर्छन् र JAR फाइलहरू अवस्थित नभए निर्माण गर्नेछन्। + +> **सूचना:** यदि तपाईंले सबै मोड्युलहरू म्यानुअली निर्माण गरेर सुरु गर्न चाहनुहुन्छ भने: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -ब्राउजरमा http://localhost:8081 खोल्नुस्। + +तपाईंको ब्राउजरमा http://localhost:8081 खोल्नुहोस्। **रोक्न:** @@ -335,103 +334,103 @@ cd 03-rag # वा cd .. && ./stop-all.sh # सबै मोड्युलहरू ``` - + **PowerShell:** ```powershell .\stop.ps1 # यो मोड्युल मात्र # वा cd ..; .\stop-all.ps1 # सबै मोड्युलहरू ``` - -## अनुप्रयोग प्रयोग -अनुप्रयोगले कागजात अपलोड र प्रश्न सोध्नको लागि वेब इन्टरफेस प्रदान गर्छ। +## अनुप्रयोग प्रयोग गर्दै + +एउटा वेब इन्टरफेस कागजात अपलोड र प्रश्न सोध्नको लागि उपलब्ध छ। RAG Application Interface -*यो स्क्रिनसटले RAG अनुप्रयोगको इन्टरफेस देखाउँछ जहाँ तपाईं कागजातहरू अपलोड गरेर प्रश्न सोध्न सक्नुहुन्छ।* +*यस स्क्रिनशटले RAG अनुप्रयोग इन्टरफेस देखाउँछ जहाँ तपाईंले कागजातहरू अपलोड गर्न र प्रश्न सोध्न सक्नुहुन्छ।* ### कागजात अपलोड गर्नुहोस् -एक कागजात अपलोड गरेर सुरु गर्नुहोस् - TXT फाइलहरू परीक्षणका लागि उत्तम हुन्छन्। यस डाइरेक्टरीमा `sample-document.txt` प्रदान गरिएको छ जसमा LangChain4j सुविधाहरू, RAG कार्यान्वयन, र उत्तम अभ्यासहरू सम्बन्धी जानकारी हुन्छ - प्रणाली परीक्षणका लागि उपयुक्त। +कागजात अपलोड गरेर सुरु गर्नुहोस् - TXT फाइलहरू परीक्षणका लागि उत्तम छन्। यस डाइरेक्टरीमा एउटा `sample-document.txt` उपलब्ध छ जसमा LangChain4j सुविधाहरू, RAG कार्यान्वयन, र उत्कृष्ट अभ्यासहरूको जानकारी समावेश छ - प्रणाली परीक्षणका लागि उपयुक्त। -प्रणालीले तपाईंको कागजात प्रक्रिया गर्छ, यसलाई टुक्रामा विभाजन गर्छ र प्रत्येक टुक्राको लागि एम्बेडिङ सिर्जना गर्छ। यो स्वचालित रूपमा अपलोड गर्दा हुन्छ। +प्रणालीले तपाईंको कागजात प्रशोधन गर्छ, यसलाई खण्डहरूमा विभाजित गर्छ, र हरेक खण्डका लागि एम्बेडिङहरू सिर्जना गर्छ। यो स्वचालित रूपमा तपाईले अपलोड गर्दा हुन्छ। ### प्रश्न सोध्नुहोस् -अब कागजातको सामग्री सम्बन्धी विशिष्ट प्रश्नहरू सोध्नुस्। केही यस्ता तथ्यहरू प्रयास गर्नुहोस् जुन कागजातमा स्पष्ट उल्लेखित छन्। प्रणाली सान्दर्भिक टुक्राहरू खोज्छ, तिनीहरूलाई प्रॉम्प्टमा समावेश गर्छ र उत्तर तयार पार्छ। +अब कागजात सामग्रीबारे विशिष्ट प्रश्नहरू सोध्नुहोस्। त्यस्तो तथ्यात्मक प्रश्न प्रयास गर्नुहोस् जुन कागजातमा स्पष्ट रूपमा उल्लेख गरिएको हो। प्रणालीले सान्दर्भिक खण्डहरू खोज्छ, ती प्रॉम्प्टमा समावेश गर्छ, र उत्तर उत्पादन गर्छ। -### स्रोत सन्दर्भ जाँच गर्नुहोस् +### स्रोत संदर्भहरू जाँच्नुहोस् -प्रत्येक उत्तरमा समानता स्कोर सहित स्रोत सन्दर्भहरू समावेश हुन्छन्। यी स्कोरहरू (० देखि १ सम्म) देखाउँछन् कस्तो मापनले प्रत्येक टुक्रा तपाईंको प्रश्नसँग सान्दर्भिक थियो। उच्च स्कोरहरू राम्रो मेल भएको जनाउँछन्। यसले तपाईंलाई उत्तरलाई स्रोत सामग्रीसँग जाँच गर्ने अनुमति दिन्छ। +प्रत्येक उत्तरसँग स्रोत संदर्भहरू समावेश हुन्छन् जसमा समानता स्कोरहरू हुन्छन्। यी स्कोरहरू (० देखि १ सम्म) देखाउँछन् कि प्रश्नसँग हरेक खण्ड कति सान्दर्भित थियो। उच्च स्कोरले राम्रो मेल जनाउँछ। यसले तपाईंलाई जवाफलाई स्रोत सामग्रीसँग प्रमाणित गर्न मद्दत गर्छ। RAG Query Results -*यो स्क्रिनसटले प्रश्न नतिजाहरू देखाउँछ जसमा तयार गरिएका उत्तरहरू, स्रोत सन्दर्भहरू, र प्रत्येक पुन: प्राप्त टुक्राको सान्दर्भिकता स्कोरहरू छन्।* +*यस स्क्रिनशटले सोधपुछ परिणामहरू देखाउँछ जसमा उत्पादित उत्तर, स्रोत संदर्भहरू, र हरेक प्राप्त खण्डको सान्दर्भिकता स्कोरहरू समावेश छन्।* -### प्रश्नसँग प्रयोग गरेर प्रयोग गर्नुहोस् +### प्रश्नहरूसँग प्रयोग गरेर परीक्षण गर्नुहोस् -फरक प्रकारका प्रश्नहरू प्रयास गर्नुहोस्: +विभिन्न प्रकारका प्रश्नहरू प्रयास गर्नुहोस्: - विशिष्ट तथ्यहरू: "मुख्य विषय के हो?" - तुलना: "X र Y बीच के फरक छ?" -- सारांशहरू: "Z का मुख्य बुँदाहरू सारांश गर्नुहोस्" +- सारांश: "Z का मुख्य बुँदाहरू सारांश गर्नुहोस्" -हेर्नुस् कसरी सान्दर्भिकता स्कोरले तपाईंको प्रश्न कति राम्रोसँग कागजात सामग्रीसँग मेल खान्छ भन्ने आधारमा परिवर्तन हुन्छ। +हेर्नुहोस् कसरी सान्दर्भिकता स्कोरहरूले परिवर्तन गर्छ जब तपाईंको प्रश्नले कागजात सामग्रीसँग कति राम्रो मेल खान्छ। -## मुख्य अवधारणाहरू +## प्रमुख अवधारणाहरू -### टुक्रा प्रबन्धन रणनीति +### खण्ड विभाजन रणनीति -कागजातहरू ३० टोकन ओभरलैपसहित ३००-टोकन टुक्रामा विभाजित गरिन्छ। यो सन्तुलनले प्रत्येक टुक्रालाई पर्याप्त सन्दर्भ दिन्छ जुन अर्थपूर्ण हुन्छ र त्यति ठूलो हुँदैन कि प्रॉम्प्टमा धेरै टुक्रा समावेश गर्न सकिंदैन। +कागजातहरूलाई ३०० टोकनका खण्डहरूमा विभाजन गरिन्छ जुन ३० टोकनले ओभरलैप हुन्छ। यसले प्रत्येक खण्डमा पर्याप्त सन्दर्भ सुनिश्चित गर्छ जुन अर्थपूर्ण हुन्छ तर धेरै ठूलो नहुनुपर्दछ, ताकि एकै प्रॉम्प्टमा धेरै खण्डहरू समावेश गर्न सकियोस्। ### समानता स्कोरहरू -हरेक पुन: प्राप्त टुक्रा ० देखि १ को समानता स्कोरसहित आउँछ जसले देखाउँछ त्यो कति नजिक प्रश्नसँग मेल खान्छ। तलको चित्रले स्कोर दायराहरू देखाउँछ र प्रणाली तिनीहरूलाई कसरी फिल्टरको लागि प्रयोग गर्छ: +प्रत्येक प्राप्त खण्डसँग ० देखि १ सम्मको समानता स्कोर सामेल हुन्छ जसले प्रयोगकर्ताको प्रश्नसँग कत्तिको नजिक मेल खान्छ भन्ने संकेत गर्दछ। तलको चित्रले स्कोर दायरा र प्रणालीले तिनीहरूलाई परिणाम छनोटमा कसरी प्रयोग गर्छ देखाउँछ: Similarity Scores -*यो चित्र स्कोर दायराहरू ० देखि १ देखाउँछ, जहाँ न्यूनतम थ्रेसहोल्ड ०.५ छ जसले अप्रासंगिक टुक्राहरूलाई हटाउँछ।* +*यस चित्रले ० देखि १ सम्मको स्कोर दायराहरू देखाउँछ, जहाँ न्यूनतम थ्रेसहोल्ड ०.५ छ जसले असम्बन्धित खण्डहरू फिल्टर गर्छ।* -स्कोर दायराहरू: -- ०.७-१.०: अत्यधिक सान्दर्भिक, पूर्ण मेल +स्कोरहरू दायरा: +- ०.७-१.०: अत्यन्त सान्दर्भिक, बिल्कुल मेल - ०.५-०.७: सान्दर्भिक, राम्रो सन्दर्भ -- ०.५ भन्दा तल: हटाइएका, धेरै भिन्न +- ०.५ भन्दा तल: फिल्टर गरिएको, धेरै भिन्न -प्रणालीले केवल न्यूनतम थ्रेसहोल्ड माथिका टुक्राहरू मात्र निकाल्छ ताकि गुणस्तर सुनिश्चित होस्। +प्रणालीले गुणस्तर सुनिश्चित गर्न न्यूनतम थ्रेसहोल्ड माथिका खण्डहरू मात्र प्राप्त गर्छ। -एम्बेडिङहरू तब राम्रो काम गर्छन् जब अर्थ क्लस्टरहरूले सफा विभाजन गर्छन्, तर तिनीहरूसँग सीमितताहरू छन्। तलको चित्रले सामान्य असफलता मोडहरू देखाउँछ — ठूलो टुक्राहरूले धुँधला भेक्टरहरू उत्पादन गर्छन्, साना टुक्राहरूमा सन्दर्भ कम हुन्छ, अस्पष्ट शब्दहरूले विभिन्न क्लस्टरहरूमा संकेत गर्छन्, र ठ्याक्कै मेल लगाउने खोजहरू (आईडीहरू, पार्ट नम्बरहरू) एम्बेडिङ्ससँग काम गर्दैनन्: +एम्बेडिङहरू राम्रो काम गर्छन् जब अर्थ क्लस्टर स्पष्ट हुन्छ, तर यसमा केही कमजोरीहरू छन्। तलको चित्रले सामान्य असफलता मोडहरू देखाउँछ — धेरै ठूलो खण्डले अस्पष्ट वेक्टरहरू उत्पादन गर्छ, साना खण्डले सन्दर्भ अभाव हुन्छ, अस्पष्ट शब्दहरूले धेरै क्लस्टरहरू बताउँछन्, र बिल्कुल मेल हुने खोज (IDs, भाग नम्बरहरूसँग) एम्बेडिङहरूमा काम गर्दैन: Embedding Failure Modes -*यो चित्रले सामान्य एम्बेडिङ असफलता मोडहरू देखाउँछ: धेरै ठूलो टुक्राहरू, धेरै साना टुक्राहरू, अस्पष्ट शब्दहरू जो धेरै क्लस्टरहरूमा संकेत गर्छन्, र ठ्याक्कै मेल लगाउने खोजहरू जस्तै आईडीहरू।* +*यस चित्रले सामान्य एम्बेडिङ असफलता मोडहरू देखाउँछ: धेरै ठूलो खण्ड, धेरै सानो खण्ड, अस्पष्ट शब्दहरू जुन धेरै क्लस्टरहरूलाई संकेत गर्छ, र IDs जस्ता बिल्कुल मेल हुने खोज।* ### इन-मेमोरी स्टोरेज -यो मोड्युलले सरलताको लागि इन-मेमोरी स्टोरेज प्रयोग गर्छ। अनुप्रयोग पुन: सुरु गर्दा अपलोड गरिएका कागजातहरू हराइहाल्छन्। उत्पादन प्रणालीहरूले Qdrant वा Azure AI Search जस्ता स्थायी भेक्टर डेटाबेसहरू प्रयोग गर्छन्। +यो मोड्युल सरलताका लागि इन-मेमोरी स्टोरेज प्रयोग गर्छ। जब तपाईं अनुप्रयोग पुनः सुरु गर्नुहुन्छ, तब अपलोड गरिएका कागजातहरू हराउँछन्। उत्पादन प्रणालीहरूले Qdrant वा Azure AI Search जस्ता स्थायी भेक्टर डेटाबेसहरू प्रयोग गर्छन्। ### सन्दर्भ विन्डो व्यवस्थापन -प्रत्येक मोडेलसँग अधिकतम सन्दर्भ विन्डो हुन्छ। तपाईं ठूलो कागजातका सबै टुक्रा समावेश गर्न सक्नुहुन्न। प्रणाली शीर्ष N सबैभन्दा सान्दर्भिक टुक्राहरू (डिफल्ट ५) निकाल्छ ताकि सीमा भित्र रहँदा पनि पर्याप्त सन्दर्भ दिएर सही उत्तर दिन सकियोस्। +हरेक मोडेलसँग अधिकतम सन्दर्भ विन्डो हुन्छ। तपाईं ठूलो कागजातका सबै खण्डहरू समावेश गर्न सक्नुहुन्न। प्रणालीले शीर्ष N सबैभन्दा सान्दर्भिक खण्डहरू (पूर्वनिर्धारित ५) प्राप्त गर्छ ताकि सीमा भित्र रहँदै व्यावहारिक उत्तर प्रदान गर्न पर्याप्त सन्दर्भ दिन सकोस्। -## कहिले RAG महत्त्वपूर्ण हुन्छ +## RAG कहिले महत्वपूर्ण हुन्छ -RAG सधैँ उपयुक्त तरिका हुँदैन। तलको निर्णय मार्गदर्शकले तपाईंलाई कहिले RAG ले मूल्य थप्छ र कहिले सरल तरिकाहरू — जस्तै सिधै प्रॉम्प्टमा सामग्री समावेश गर्ने वा मोडेलको बिल्ट-इन ज्ञानमा भर पर्ने — पर्याप्त हुन्छ भन्ने निर्णय गर्न मद्दत गर्छ: +RAG सधैं सही विकल्प हुँदैन। तलको निर्णय मार्गनिर्देशले तपाईंलाई जब RAG ले मूल्य थप्छ र कहिले सिधै प्रॉम्प्टमा सामग्री समावेश गर्ने वा मोडेलको आन्तरिक ज्ञानमा निर्भर हुने सरल विधिहरू पर्याप्त हुन्छन् भन्ने निर्धारण गर्न मद्दत गर्छ: When to Use RAG -*यो चित्रले निर्णय मार्गदर्शक देखाउँछ कि कहिले RAG ले मूल्य थप्छ र कहिले सरल तरिकाहरू पर्याप्त हुन्छन्।* +*यस चित्रले देखाउँछ कब RAG ले मूल्य थप्छ र कब सरल विधिहरू पर्याप्त हुन्छन् भन्ने निर्णय मार्गनिर्देश।* -## अर्को कदमहरू +## आगामी चरणहरू -**अर्को मोड्युल:** [04-tools - उपकरणहरूसहित AI एजेन्टहरू](../04-tools/README.md) +**अर्को मोड्युल:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**नेभिगेसन:** [← अघिल्लो: मोड्युल 02 - प्रॉम्प्ट इञ्जिनियरिङ](../02-prompt-engineering/README.md) | [मुख्य पृष्ठमा फर्किनुहोस्](../README.md) | [अर्को: मोड्युल 04 - उपकरणहरू →](../04-tools/README.md) +**नेभिगेसन:** [← अघिल्लो: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [मुख्यमा फर्किनुहोस्](../README.md) | [अर्को: Module 04 - Tools →](../04-tools/README.md) --- -**अपवाद**: -यस दस्तावेजलाई AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरी अनुवाद गरिएको हो। हामी शुद्धताका लागि प्रयासरत छौं भने पनि, कृपया जानकार हुनुहोस् कि स्वचालित अनुवादमा त्रुटि वा असम्बद्धता हुन सक्छ। मूल दस्तावेज यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलतफहमी वा गलत व्याख्याको लागि हामी जिम्मेवार छैनौं। +**अस्वीकरण**: +यो दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी सही हुन प्रयास गर्छौं, तर कृपया जानकार हुनुस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छन्। मूल दस्तावेज़ यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलत बुझाइ वा त्रुटिको लागि हामी जिम्मेवार छैनौं। \ No newline at end of file diff --git a/translations/ne/04-tools/README.md b/translations/ne/04-tools/README.md index deea66a67..87bf93e45 100644 --- a/translations/ne/04-tools/README.md +++ b/translations/ne/04-tools/README.md @@ -1,76 +1,76 @@ -# Module 04: उपकरणहरूसँग AI एजेन्टहरू - -## तालिका - -- [भिडियो वाकथ्रु](../../../04-tools) -- [तिमीले के सिक्नेछौ](../../../04-tools) -- [पूर्वआवश्यकताहरू](../../../04-tools) -- [उपकरणहरूसँग AI एजेन्टहरू बुझ्नु](../../../04-tools) -- [उपकरण कल गर्ने तरिका](../../../04-tools) - - [उपकरण परिभाषाहरू](../../../04-tools) - - [निर्णय लिने प्रक्रिया](../../../04-tools) - - [कार्यान्वयन](../../../04-tools) - - [प्रतिक्रिया सिर्जना](../../../04-tools) - - [आर्किटेक्चर: स्प्रिङ बुट स्वत: वायरिङ](../../../04-tools) -- [उपकरण श्रृंखला](../../../04-tools) -- [एप्लिकेसन चलाउनुहोस्](../../../04-tools) -- [एप्लिकेसन प्रयोग](../../../04-tools) - - [सरल उपकरण प्रयोग प्रयास गर्नुहोस्](../../../04-tools) - - [उपकरण श्रृंखला परीक्षण गर्नुहोस्](../../../04-tools) - - [संवाद प्रवाह हेर्नुहोस्](../../../04-tools) - - [भिन्न अनुरोधहरू प्रयोग गर्नुहोस्](../../../04-tools) -- [महत्त्वपूर्ण अवधारणाहरू](../../../04-tools) - - [ReAct ढाँचा (तर्क र क्रियाशीलता)](../../../04-tools) - - [उपकरण विवरणहरू महत्वपूर्ण छन्](../../../04-tools) - - [सेसन व्यवस्थापन](../../../04-tools) - - [त्रुटि ह्यान्डलिङ](../../../04-tools) -- [उपलब्ध उपकरणहरू](../../../04-tools) -- [कहिले उपकरण-आधारित एजेन्टहरू प्रयोग गर्ने](../../../04-tools) -- [उपकरणहरू बनाम RAG](../../../04-tools) -- [अर्को कदमहरू](../../../04-tools) - -## भिडियो वाकथ्रु - -यस लाइभ सत्रलाई हेर्नुहोस् जुन यो मोड्युलसँग कसरी सुरु गर्ने भनेर व्याख्या गर्दछ: +# Module 04: उपकरणहरूसँग एआई एजेन्टहरू + +## सामग्री तालिका + +- [भिडियो वाकथ्रू](#भिडियो-वाकथ्रू) +- [तपाईंले के सिक्नुहुनेछ](#तपाईंले-के-सिक्नुहुनेछ) +- [पूर्व आवश्यकताहरू](#पूर्व-आवश्यकताहरू) +- [उपकरणहरू सहित एआई एजेन्टहरू बुझ्ने](#उपकरणहरूसँग-एआई-एजेन्टहरू-बुझ्न) +- [उपकरण कल कसरी काम गर्छ](#उपकरण-कल-कसरी-काम-गर्छ) + - [उपकरण परिभाषाहरू](#उपकरण-परिभाषाहरू) + - [निर्णय लिनु](#निर्णय-लिनु) + - [कार्यन्वयन](#कार्यान्वयन) + - [प्रतिक्रिया उत्पादन](#प्रतिक्रिया-उत्पादन) + - [वास्तुकला: स्प्रिंग बूट ऑटो-वारिङ](#वास्तुकला-स्प्रिंग-बूट-ऑटो-वारिङ) +- [उपकरण चेनिङ](#उपकरण-चेनिङ) +- [एप्लिकेसन चलाउनुहोस्](#एप्लिकेसन-चलाउनुहोस्) +- [एप्लिकेसन प्रयोग गर्दै](#एप्लिकेशन-प्रयोग-गर्दै) + - [साधारण उपकरण प्रयोग कोशिश गर्नुहोस्](#साधारण-उपकरण-प्रयोग-प्रयास-गर्नुहोस्) + - [उपकरण चेनिङ परीक्षण गर्नुहोस्](#उपकरण-श्रृंखला-परीक्षण-गर्नुहोस्) + - [वार्तालाप प्रवाह हेर्नुहोस्](#कुराकानी-प्रवाह-हेर्नुहोस्) + - [विभिन्न अनुरोधहरूसँग प्रयोग गर्नुहोस्](#विभिन्न-अनुरोधहरूसँग-प्रयोग-गर्नुहोस्) +- [मुख्य अवधारणाहरू](#प्रमुख-अवधारणाहरू) + - [ReAct ढाँचा (तर्क र कार्य)](#react-ढाँचा-कारण-र-कार्य) + - [उपकरण विवरणहरूको महत्व](#उपकरणको-विवरण-महत्त्वपूर्ण-छ) + - [सेसन व्यवस्थापन](#सत्र-व्यवस्थापन) + - [त्रुटि ह्यान्डलिङ](#त्रुटि-व्यवस्थापन) +- [उपलब्ध उपकरणहरू](#उपलब्ध-उपकरणहरू) +- [कहिले उपकरण आधारित एजेन्टहरू प्रयोग गर्ने](#कहिले-उपकरण-आधारित-एजेन्टहरू-प्रयोग-गर्ने) +- [उपकरणहरू विरुद्ध RAG](#उपकरणहरू-बनाम-rag) +- [अर्को कदमहरू](#अर्को-कदम) + +## भिडियो वाकथ्रू + +यस लाइभ सत्रलाई हेर्नुहोस् जसले यो मोड्युल कसरी सुरु गर्ने भनेर व्याख्या गर्छ: AI Agents with Tools and MCP - Live Session -## तिमीले के सिक्नेछौ +## तपाईंले के सिक्नुहुनेछ -अहिले सम्म, तिमीले AI सँग संवाद कसरी गर्ने, प्रभावकारी रूपमा प्रॉम्प्ट बनाउन, र तिम्रा दस्तावेजहरूमा आधारित प्रतिक्रिया दिन सिक्यौ। तर एक मौलिक सीमितता अझै छ: भाषा मोडेलहरूले केवल पाठ मात्र उत्पन्न गर्न सक्छन्। तिनीहरूले मौसम जाँच्न, गणना गर्न, डाटाबेस सोध्न, वा बाह्य प्रणालीहरूसँग अन्तरक्रिया गर्न सक्दैनन्। +अहिलेसम्म तपाईंले एआईसँग कसरी कुराकानी गर्ने, प्रभावकारी रूपमा प्रॉम्प्ट कसरी निर्माण गर्ने, र प्रतिक्रियाहरूलाई तपाईंका कागजातहरूमा कसरी आधार गर्ने सिक्नुभयो। तर अझै एउटा आधारभूत सिमाना छ: भाषा मोडेलहरूले मात्र पाठ उत्पादन गर्न सक्छन्। तिनीहरू मौसम जाँच गर्न, गणना गर्न, डेटा बेस सोध्न वा बाह्य प्रणालीहरूसँग अन्तरक्रिया गर्न सक्दैनन्। -उपकरणहरूले यो परिवर्तन गर्छन्। मोडेललाई कल गर्न मिल्ने कार्यहरू दिनाले, तिमी यसलाई एउटा एजेन्टमा परिवर्तन गर्‍यौ जुन क्रियाहरू गर्न सक्छ। मोडेलले कहिले उपकरण चाहिन्छ, कुन उपकरण प्रयोग गर्ने, र कुन प्यारामिटरहरू पठाउने निर्णय गर्छ। तिम्रो कोडले त्यो कार्यलाई कार्यान्वयन गर्छ र परिणाम फर्काउँछ। मोडेलले त्यो परिणामलाई आफ्नो प्रतिक्रियामा समावेश गर्छ। +उपकरणहरूले यसलाई परिवर्तन गर्छन्। मोडेललाई कल गर्न सकिने कार्यहरू उपलब्ध गराएर, तपाईं यसलाई पाठ उत्पादन गर्ने यन्त्रबाट कार्य गर्न सक्ने एजेन्टमा परिणत गर्नुहुन्छ। मोडेलले कहिले उपकरण चाहिन्छ, कुन उपकरण प्रयोग गर्ने, र कुन प्यारामिटरहरू पास गर्ने निर्णय गर्छ। तपाईंको कोडले त्यो कार्य सञ्चालन गर्छ र नतिजा फर्काउँछ। मोडेल त्यो नतिजा आफ्नो प्रतिक्रियामा समावेश गर्छ। -## पूर्वआवश्यकताहरू +## पूर्व आवश्यकताहरू -- पूर्ण [Module 01 - परिचय](../01-introduction/README.md) (Azure OpenAI स्रोतहरू तैनाथ गरिएको) -- पूर्वका मोड्युलहरू पूरा गरेको सिफारिस गरिएको (यो मोड्युलले [Module 03 बाट RAG अवधारणाहरू](../03-rag/README.md) उपकरणहरू बनाम RAG तुलना मा उल्लेख गरेको छ) -- रूट निर्देशिकामा `.env` फाइल Azure प्रमाणपत्रसहित (Module 01 मा `azd up` द्वारा सिर्जना गरिएको) +- [मोड्युल ०१ - परिचय](../01-introduction/README.md) पूरा भएको (Azure OpenAI स्रोतहरू तैनाथ गरिएको) +- सिफारिस गरिएको अघिल्लो मोड्युलहरू पूरा गरिएको (यो मोड्युलले [मोड्युल ०३ बाट RAG अवधारणाहरू](../03-rag/README.md) लाई उपकरणहरू विरुद्ध RAG तुलनामा सन्दर्भ गर्दछ) +- मूल डाइरेक्टरीमा `.env` फाइल Azure प्रमाणपत्रहरू सहित (मोड्युल ०१ मा `azd up` द्वारा सिर्जना गरिएको) -> **टिप्पणी:** यदि तिमीले Module 01 पूरा गर्नुभएको छैन भने, पहिले त्यहाँका तैनाथ निर्देशनहरू पालना गर। +> **टिप्पणी:** यदि तपाईंले मोड्युल ०१ पूरा गर्नुभएको छैन भने, पहिले त्यहाँका तैनाती निर्देशनहरू पालना गर्नुहोस्। -## उपकरणहरूसँग AI एजेन्टहरू बुझ्नु +## उपकरणहरूसँग एआई एजेन्टहरू बुझ्न -> **📝 नोट:** यस मोड्युलमा "एजेन्टहरू" भन्नाले उपकरण कल गर्ने क्षमताले सुसज्जित AI सहायकहरूलाई जनाउँछ। यो प턴हरूबाट फरक छ जुन हामी [Module 05: MCP](../05-mcp/README.md) मा चर्चा गर्नेछौं, जसमा स्वायत्त एजेन्टहरू छन् जसले योजना, स्मृति, र बहु-चरण तर्क गर्छन्। +> **📝 नोट:** यस मोड्युलमा "एजेन्टहरू" भनी जनाइएको छ एआई सहायकहरूलाई जसले उपकरण कल गर्ने क्षमता वृद्धि गरिएको छ। यो [मोड्युल ०५: MCP](../05-mcp/README.md) मा समेटिने **एजेन्सिक AI** ढाँचाहरू (स्वायत्त एजेन्टहरू जसमा योजना, सम्झना, र बहु-चरण तर्क हुन्छ) भन्दा फरक छ। -उपकरण नहुँदा, भाषा मोडेलले केवल आफ्नो प्रशिक्षित डाटाबाट पाठ उत्पन्न गर्न सक्छ। अहिलेको मौसम सोध्ने हो भने, यसले अनुमान लगाउनै पर्छ। तर उपकरण दिएर, यसले मौसम API कल गर्न सक्छ, गणना गर्न सक्छ, वा डाटाबेस सोध्न सक्छ — र तिन वास्तविक नतिजा आफ्ना प्रतिक्रियामा समेट्न सक्छ। +उपकरण बिना, भाषा मोडेलले केवल यसको प्रशिक्षण डेटाबाट पाठ मात्र उत्पादन गर्न सक्छ। वर्तमान मौसम सोध्नुहोस्, र त्यसले केवल अनुमान लगाउँछ। उपकरणहरू उपलब्ध गराउँदा, यसले मौसम API कल गर्न सक्छ, गणना गर्न सक्छ वा डेटाबेस सोध्न सक्छ — अनि ती वास्तविक नतिजाहरू आफ्ना प्रतिक्रियामा जोड्न सक्छ। Without Tools vs With Tools -*उपकरण बिना मोडेलले केवल अनुमान लगाउँछ — उपकरणले API कल गर्न, गणना गर्न, र वास्तविक समय डेटा फर्काउन सक्छ।* +*उपकरण बिना मोडेलले मात्र अनुमान लगाउँछ — उपकरणहरूसँग यो API कल गर्न, गणना गर्न र वास्तविक-समय डेटा फिर्ता गर्न सक्छ।* -उपकरणहरू भएका AI एजेन्टहरूले **Reasoning and Acting (ReAct)** ढाँचा प्रयोग गर्छ। मोडेलले केवल प्रतिक्रिया दिन्छ भनी हुँदैन — यसले के चाहिन्छ सोच्दछ, उपकरण कल गरेर कार्य गर्छ, परिणाम अवलोकन गर्छ, अनि फेरि कार्य गर्ने वा अन्तिम उत्तर दिने निर्णय गर्छ: +उपकरण भएको एआई एजेन्टले **तर्क र कार्य (ReAct)** ढाँचा अनुसरण गर्छ। मोडेलले मात्र जवाफ दिँदैन — यसले के चाहिन्छ भनी सोच्छ, उपकरण कल गरेर कार्य गर्छ, नतिजा अवलोकन गर्छ, अनि फेरि कार्य गर्ने वा अन्तिम उत्तर दिने निर्णय गर्छ: -1. **विचार गर्नुहोस्** — एजेन्टले प्रयोगकर्ताको प्रश्न विश्लेषण गरी के जानकारी चाहिन्छ निर्धारण गर्छ -2. **कार्य गर्नुहोस्** — एजेन्ट सही उपकरण छान्छ, सही प्यारामिटरहरू उत्पन्न गर्छ, र उपकरण कल गर्छ -3. **परिणाम अवलोकन गर्नुहोस्** — एजेन्टले उपकरणको आउटपुट प्राप्त गरी मूल्याङ्कन गर्छ -4. **दोहोर्याउनुहोस् वा प्रतिक्रिया दिनुहोस्** — यदि थप डाटा चाहिन्छ भने फेरि लूप गर्छ; नभए प्राकृतिक भाषा जवाफ तयार गर्दछ +1. **तर्क गर्नुहोस्** — एजेन्ट प्रयोगकर्ताको प्रश्न विश्लेषण गर्छ र के सूचना चाहिन्छ निर्धारण गर्छ +2. **कार्य गर्नुहोस्** — एजेन्ट सही उपकरण छान्छ, सहि प्यारामिटरहरू उत्पादन गर्छ, र कल गर्छ +3. **अवलोकन गर्नुहोस्** — एजेन्टले उपकरणबाट प्राप्त नतिजा पाउँछ र मूल्याङ्कन गर्छ +4. **दोहर्याउनुहोस् वा प्रतिक्रिया दिनुहोस्** — यदि थप डाटा चाहिन्छ भने पुनः लूप हुन्छ; नभए, प्राकृतिक भाषा जवाफ तयार गर्छ ReAct Pattern -*ReAct चक्र — एजेन्टले के गर्ने भनेर सोच्दछ, उपकरण कल गरेर कार्य गर्छ, परिणाम देख्छ, र अन्तिम उत्तर दिनसम्म लूप गर्दछ।* +*ReAct चक्र — एजेन्टले के गर्ने भनी तर्क गर्छ, उपकरण कल गरेर कार्य गर्छ, नतिजा अवलोकन गर्छ, र अन्तिम उत्तर दिन लूप गर्दै जान्छ।* -यो स्वतः हुन्छ। तिमीले उपकरण र ती विवरणहरू परिभाषित गर्छौ। मोडेलले कहिले र कसरी उपकरण प्रयोग गर्ने निर्णय गर्छ। +यसले स्वचालित रूपमा हुन्छ। तपाईंले उपकरणहरू र तिनका विवरणहरू परिभाषित गर्नुहुन्छ। मोडेलले कहिले र कसरी प्रयोग गर्ने निर्णय गर्छ। ## उपकरण कल कसरी काम गर्छ @@ -78,7 +78,7 @@ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -तिमीले स्पष्ट विवरण र प्यारामिटर विनिर्देशहरू सहित फङ्क्शनहरू परिभाषित गर्छौ। मोडेलले आफ्नो सिस्टम प्रॉम्प्टमा ती विवरणहरू देख्छ र कुन उपकरण के गर्छ बुझ्छ। +तपाईं स्पष्ट विवरणहरू र प्यारामिटर निर्दिष्टहरूसँग कार्यहरू परिभाषित गर्नुहुन्छ। मोडेलले यी विवरणहरू सिस्टम प्रॉम्प्टमा हेर्छ र बुझ्छ कि प्रत्येक उपकरण के गर्छ। ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // तपाइँको मौसम खोजी तर्क + // तपाईंको मौसम खोज्ने तर्क return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// सहायक Spring Boot द्वारा स्वचालित रूपमा जडित गरिएको छ: +// असिस्टेन्ट स्वचालित रूपमा Spring Boot द्वारा जोडिएको छ: // - ChatModel बीन -// - @Component कक्षाहरूका सबै @Tool विधिहरू -// - सत्र व्यवस्थापनका लागि ChatMemoryProvider +// - @Component वर्गहरूबाट सबै @Tool विधिहरू +// - सत्र व्यवस्थापनको लागि ChatMemoryProvider ``` -तलको चित्रले प्रत्येक एनोटेशन विश्लेषण गरी देखाउँछ कि कसरी AI लाई कहिले उपकरण कल गर्ने र कुन आर्गुमेन्ट्सा पठाउने बुझाउन मद्दत गर्छ: +तलको चित्रले प्रत्येक एनोटेशनलाई तोड्छ र देखाउँछ कसरी प्रत्येक भागले एआईलाई उपकरण कहिले कल गर्ने र के तर्कहरू पास गर्ने बुझ्न सहयोग गर्छ: Anatomy of Tool Definitions -*उपकरण परिभाषाको संरचना — @Tool ले AI लाई कहिले प्रयोग गर्ने भन्छ, @P प्रत्येक प्यारामिटर वर्णन गर्छ, र @AiService सबैलाई सुरूमा जोड्छ।* +*उपकरण परिभाषाको संरचना — @Tool ले एआईलाई कहिले प्रयोग गर्ने बताउँछ, @P प्रत्येक प्यारामिटरको विवरण दिन्छ, र @AiService सबैलाई सुरुमा जोड्छ।* > **🤖 [GitHub Copilot](https://github.com/features/copilot) च्याटसँग प्रयास गर्नुहोस्:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) खोल्नुहोस् र सोध्नुहोस्: -> - "कसरी वास्तविक मौसम API जस्तै OpenWeatherMap सङ्ग मक्स्य डेटा सट्टा इंटिग्रेट गर्न सकिन्छ?" -> - "के राम्रो उपकरण विवरण हुन्छ जसले AI लाई त्यसलाई ठीक तरिकाले प्रयोग गर्न मद्दत गर्छ?" -> - "API त्रुटि र रेट लिमिटहरूलाई उपकरण लागू गर्दा कसरी ह्यान्डल गर्ने?" +> - "मक डाटा सट्टा वास्तविक OpenWeatherMap जस्तो वास्तविक मौसम API कसरी समावेश गर्ने?" +> - "एआईलाई सहि तरिकाले प्रयोग गर्न मद्दत गर्ने राम्रो उपकरण विवरण के हो?" +> - "उपकरण कार्यान्वयनमा API त्रुटि र दर सीमाहरू कसरी ह्यान्डल गर्ने?" -### निर्णय लिने प्रक्रिया +### निर्णय लिनु -जब प्रयोगकर्ताले सोध्छ "सिएटलको मौसम कस्तो छ?", मोडेलले कुनै उपकरण यादृच्छिक रूपमा छान्दैन। यसले प्रयोगकर्ताको उद्देश्य हरेक उपकरण विवरणसँग तुलना गर्छ, प्रासंगिकता अनुसार स्कोर गर्छ, र सबैभन्दा उपयुक्त चयन गर्छ। त्यसपछि सही प्यारामिटरहरूसहित संरचित फङ्क्शन कल उत्पादन गर्छ — यस केसमा, `location` लाई `"Seattle"` सेट गर्छ। +जब प्रयोगकर्ताले "सिएटलमा मौसम कस्तो छ?" भन्छ, मोडेलले मनमानी रूपमा उपकरण छान्दैन। यसले प्रयोगकर्ताको अभिप्राय प्रत्येक उपकरण विवरणसँग तुलना गर्छ, सम्बन्धितताको आधारमा स्कोर गर्छ, र सबैभन्दा उपयुक्त छान्छ। त्यसपछि सही प्यारामिटरहरू सहित संरचित कार्य कल सिर्जना गर्छ — यस अवस्थामा, `location` लाई `"Seattle"` सेट गरेर। -यदि कुनै उपकरण अनुरोधसँग मेल खाँदैन भने, मोडेल आफ्नो ज्ञानबाट जवाफ दिन्छ। यदि धेरै उपकरण मिल्छन् भने, सबैभन्दा विशिष्ट छान्छ। +यदि कुनै उपकरण प्रयोगकर्ताको अनुरोधसँग मेल खाँदैन भने, मोडेल आफ्नै ज्ञानबाट जवाफ दिन्छ। यदि धेरै उपकरण मेल खान्छ भने, सबैभन्दा विशिष्ट उपकरण चयन गरिन्छ। How the AI Decides Which Tool to Use -*मोडेलले प्रत्येक उपलब्ध उपकरण प्रयोगकर्ताको उद्देश्य विरुद्ध मूल्याङ्कन गरेर सबैभन्दा उपयुक्त चयन गर्छ — त्यसैले स्पष्ट, विशिष्ट उपकरण विवरण लेख्नु महत्त्वपूर्ण हुन्छ।* +*मोडेलले उपलब्ध प्रत्येक उपकरणलाई प्रयोगकर्ताको अभिप्रायसँग तुलना गरेर सबैभन्दा उपयुक्त छनोट गर्छ — त्यसैले स्पष्ट र विशिष्ट उपकरण विवरण लेख्नु महत्त्वपूर्ण हुन्छ।* ### कार्यान्वयन [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -स्प्रिङ बुटले `@AiService` इन्टरफेसलाई सबै दर्ता भएका उपकरणहरूसँग स्वतः वायर गर्छ, र LangChain4j ले उपकरण कलहरू स्वचालित रूपमा कार्यान्वयन गर्छ। पृष्ठभूमिमा, उपकरण कल छ चरणबाट पूर्ण रूपमा बहन्छ — प्रयोगकर्ताको प्राकृतिक भाषा प्रश्नदेखि अन्तिम प्राकृतिक भाषा उत्तरसम्म: +स्प्रिंग बुटले घोषणा गरिएको `@AiService` इन्टरफेसलाई सबै दर्ता भएका उपकरणहरूसँग स्वचालित रूपमा जोड्दछ, र LangChain4j ले उपकरण कलहरू स्वचालित रूपमा सञ्चालन गर्छ। पछाडि, एक पूर्ण उपकरण कल प्रयोगकर्ताको प्राकृतिक भाषाको प्रश्नदेखि प्राकृतिक भाषाको जवाफसम्म छेउछाउ छः Tool Calling Flow -*अन्त-देखि-अन्त प्रवाह — प्रयोगकर्ताले प्रश्न सोध्छ, मोडेलले उपकरण चयन गर्छ, LangChain4j ले कार्यान्वयन गर्छ, र मोडेलले नतिजा प्रतिक्रिया बनाउन समेट्छ।* +*अन्त-देखि-अन्त प्रवाह — प्रयोगकर्ताले प्रश्न सोध्छ, मोडेलले उपकरण छान्छ, LangChain4j कार्यान्वयन गर्छ, र मोडेल नतिजालाई प्राकृतिक जवाफमा बुन्छ।* -यदि तिमीले Module 00 मा [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) चलाएको छौ भने, यस ढाँचालाई पहिले देखिसकेको छौ — `Calculator` उपकरणहरू पनि यस्तै कल भएका थिए। तलको अनुक्रमिक चित्रले त्यो डेमोको दौरान के भयो देखाउँछ: +पछाडि, `AiServices` ले जुनसुकै उपकरणका लागि समान उपकरण-कल लूप चलाउँछ — यहाँ एक साधारण `Calculator` साथ उदाहरण देखाइएको छ। तलको सिक्वेन्स डाइग्रामले ठीक के हुन्छ देखाउँछ: Tool Calling Sequence Diagram -*द्रुत शुरु डेमोबाट उपकरण कल लूप — `AiServices` ले तिमीले दिएको सन्देश र उपकरण स्कीमाहरू LLM लाई पठाउँछ, LLM ले `add(42, 58)` जस्तो फङ्क्शन कल फर्काउँछ, LangChain4j ले स्थानीयरूपमा `Calculator` विधि चलाउँछ, र परिणाम अन्तिम उत्तरका लागि फिर्ता गर्छ।* +*उपकरण-कल लूप — `AiServices` ले तपाईंको सन्देश र उपकरण स्किमा LLM लाई पठाउँछ, LLM ले `add(42, 58)` जस्तो कार्य कल जवाफ दिन्छ, LangChain4j ले `Calculator` मेथड स्थानीय रूपमा चलाउँछ, र नतिजा फिर्ता गर्दै अन्तिम उत्तर दिन्छ।* > **🤖 [GitHub Copilot](https://github.com/features/copilot) च्याटसँग प्रयास गर्नुहोस्:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) खोल्नुहोस् र सोध्नुहोस्: -> - "ReAct ढाँचाले कसरी काम गर्छ र किन AI एजेन्टहरूका लागि प्रभावकारी छ?" -> - "एजेन्टले कुन उपकरण कसरी र कुन क्रममा प्रयोग गर्ने निर्णय कसरी गर्छ?" -> - "यदि उपकरण कार्यान्वयन असफल भयो भने के हुन्छ - मैले कसरी त्रुटि समस्याहरूसँग मजबुत व्यवहार गर्ने?" +> - "ReAct ढाँचाले कसरी काम गर्छ र किन यो एआई एजेन्टहरूका लागि प्रभावकारी छ?" +> - "एजेन्टले कुन उपकरण प्रयोग गर्ने र कुन क्रममा प्रयोग गर्ने कसरी निर्णय गर्छ?" +> - "यदि उपकरण कार्यान्वयन असफल भयो भने के हुन्छ - त्रुटिहरूलाई कसरी मजबुदीले ह्यान्डल गर्ने?" -### प्रतिक्रिया सिर्जना +### प्रतिक्रिया उत्पादन -मोडेलले मौसम डाटा प्राप्त गर्छ र प्रयोगकर्ताका लागि प्राकृतिक भाषा प्रतिक्रिया स्वरूप फर्म्याट गर्छ। +मोडेलले मौसम डाटा प्राप्त गर्छ र प्रयोगकर्ताको लागि प्राकृतिक भाषामा प्रतिक्रिया तयार गर्छ। -### आर्किटेक्चर: स्प्रिङ बुट स्वत: वायरिङ +### वास्तुकला: स्प्रिंग बूट ऑटो-वारिङ -यस मोड्युलले LangChain4j को स्प्रिङ बुट इंटिग्रेशन प्रयोग गर्छ जुन `@AiService` इण्टरफेसहरू बाक्लो रूपमा प्रयोग हुने उपकरणहरूसँग जोडिन्छन्। स्टार्टअपमा स्प्रिङ बुटले `@Tool` मेथड भएका सबै `@Component` हरू, तिम्रो `ChatModel` बीन र `ChatMemoryProvider` पत्ता लगाएर सबैलाई एउटै `Assistant` इण्टरफेसमा जोड्छ — र बोइलरप्लेट शून्य बनाउँछ। +यो मोड्युलले LangChain4j को स्प्रिंग बूट इन्टिग्रेसन प्रयोग गर्छ जुन घोषणा गरिएको `@AiService` इन्टरफेसहरूसँग छ। सुरुमा स्प्रिंग बुटले प्रत्येक `@Component` जुन `@Tool` मेथडहरू समावेश गर्छ पत्ता लगाउँछ, तपाईंको `ChatModel` बीन, र `ChatMemoryProvider` — अनि सबैलाई एउटै `Assistant` इन्टरफेसमा जोड्छ, कुनै बोइलरप्लेट बिना। Spring Boot Auto-Wiring Architecture -*@AiService इण्टरफेसले ChatModel, उपकरण कम्पोनेन्टहरू, र मेमोरी प्रदायकलाई जोड्छ — स्प्रिङ बुटले सबै वायरिङ स्वतः गर्छ।* +*@AiService इन्टरफेसले ChatModel, उपकरण कम्पोनेंटहरू, र मेमोरी प्रदायकलाई जोड्छ — स्प्रिंग बुटले पूरै वारिङ स्वचालित रूपमा व्यवस्थापन गर्छ।* -HTTP अनुरोधबाट सुरु गरी कन्ट्रोलर, सेवा, र स्वत: वायर गरिएको प्रोक्सीबाट उपकरण कार्यान्वयनसम्मको पूर्ण अनुरोध जीवनचक्र तल अनुक्रम चित्रमा छ: +यहाँ पूर्ण अनुरोध जीवनचक्र छ सिक्वेन्स डाइग्राममा — HTTP अनुरोधबाट कन्ट्रोलर, सर्भिस, र ऑटो-वार्ड प्रोक्सी हुँदै, उपकरण कार्यान्वयन सम्म र फिर्तासम्म: Spring Boot Tool Calling Sequence -*पूर्ण स्प्रिङ बुट अनुरोध जीवनचक्र — HTTP अनुरोध कन्ट्रोलर र सेवाबाट स्वत: वायर गरिएको सहायक प्रोक्सीसम्म बहन्छ, जसले LLM र उपकरण कलहरू स्वचालित रूपमा समन्वय गर्दछ।* +*पूर्ण स्प्रिंग बुट अनुरोध जीवनचक्र — HTTP अनुरोध कन्ट्रोलर र सर्भिसबाट ऑटो-वार्डेड Assistant प्रोसीमा जान्छ, जसले LLM र उपकरण कलहरू स्वचालित रूपमा समन्वय गर्छ।* यस दृष्टिकोणका मुख्य फाइदाहरू: -- **स्प्रिङ बुट स्वत: वायरिङ** — ChatModel र उपकरणहरू स्वचालित रूपमा इन्जेक्ट हुन्छन् -- **@MemoryId ढाँचाले** — स्वचालित सेसन-आधारित मेमोरी व्यवस्थापन गर्छ -- **एकल उदाहरण** — सहायक एक पटक सिर्जना गरिन्छ र राम्रो प्रदर्शनका लागि पुन: प्रयोग गरिन्छ -- **प्रकार-सुरक्षित कार्यान्वयन** — Java विधिहरू प्रत्यक्ष प्रकार रूपान्तरणसहित कल हुन्छन् -- **बहु-पटक समन्वय** — उपकरण श्रृंखला स्वचालित रूपमा व्यवस्थापन गर्छ -- **बोइलरप्लेट शून्य** — कुनै म्यानुअल `AiServices.builder()` कल वा मेमोरी ह्यासम्याप छैन +- **स्प्रिंग बुट ऑटो-वारिङ** — ChatModel र उपकरणहरू स्वचालित इंजेक्ट गरिएको +- **@MemoryId ढाँचा** — स्वचालित सेसन-आधारित मेमोरी व्यवस्थापन +- **एकल उदाहरण** — Assistant एकपटक सिर्जना गरिन्छ र पुन: प्रयोग गरिन्छ प्रदर्शन सुधारका लागि +- **टाइप-सेफ कार्यान्वयन** — Java मेथडहरू प्रत्यक्ष प्रकार रूपान्तरणसहित कल गरिन्छ +- **बहु-चरण समन्वय** — उपकरण चेनिङ स्वचालित रूपमा ह्यान्डल गर्छ +- **शून्य बोइलरप्लेट** — कुनै म्यानुअल `AiServices.builder()` कल वा मेमोरी ह्यास म्याप आवश्यक छैन -वैकल्पिक विधिहरू (म्यानुअल `AiServices.builder()`) बढी कोड आवश्यक पर्छ र स्प्रिङ बुट इंटिग्रेशनका फाइदाहरू हराउँछन्। +वैकल्पिक दृष्टिकोणहरू (म्यानुअल `AiServices.builder()`) मा बढी कोड चाहिन्छ र स्प्रिंग बूट इन्टिग्रेसन फाइदाहरू मिस हुन्छन्। -## उपकरण श्रृंखला +## उपकरण चेनिङ -**उपकरण श्रृंखला** — उपकरण-आधारित एजेन्टहरूको वास्तविक शक्ति तब देखिन्छ जब एउटै प्रश्नलाई धेरै उपकरणहरू चाहिन्छ। "सिएटलको मौसम फरनहाइटमा कस्तो छ?" सोध्दा एजेन्टले आफैं दुई उपकरण श्रृंखलाबद्ध गर्छ: पहिले `getCurrentWeather` कल गरेर सेल्सियसमा तापक्रम पाउँछ, त्यसपछि `celsiusToFahrenheit` कलमा सो मान पास गर्छ — यो सबै एउटै संवाद मोडमा हुन्छ। +**उपकरण चेनिङ** — उपकरण-आधारित एजेन्टहरूको वास्तविक शक्ति तब प्रकट हुन्छ जब एक प्रश्नले धेरै उपकरणहरू प्रयोग गर्नुपर्छ। "सिएटलको मौसम फर्नहाइटमा कस्तो छ?" सोध्दा, एजेन्टले स्वचालित रूपमा दुई उपकरणहरू जडान गर्छ: पहिले `getCurrentWeather` कल गरेर सेल्सियसमा तापक्रम पाउँछ, त्यसपछि त्यो मान `celsiusToFahrenheit` लाई पास गरेर रूपान्तरण गर्छ — सबै एकै वार्तालाप चरणमा। Tool Chaining Example -*उपकरण श्रृंखला क्रियामा — एजेन्टले पहिले getCurrentWeather कल गर्छ, त्यसपछि सेल्सियस नतिजा celsiusToFahrenheit मा पठाउँछ, र संयुक्त उत्तर दिन्छ।* +*उपकरण चेनिङ क्रियाको अवस्था — एजेन्टले पहिले getCurrentWeather कल गर्छ, त्यसपछि सेल्सियस नतिजा celsiusToFahrenheit मा पठाउँछ, र मिलाइएको उत्तर दिन्छ।* -**सुन्तला फेल्योरहरू** — मक्स्य डेटा नभएको शहरको मौसम सोध्दा, उपकरणले त्रुटि सन्देश फर्काउँछ र AI ले भन्न सक्छ कि मद्दत गर्न सक्दैन — भङ्ग हुँदैन। उपकरणहरू सुरक्षित रूपमा असफल हुन्छन्। तलको चित्रले दुई विधिहरू तुलना गर्दछ — उचित त्रुटि ह्यान्डलिङ हुँदा एजेन्टले अपवाद समात्छ र मद्दतपूर्ण जवाफ दिन्छ, नभए पुरै एप्लिकेसन क्र्यास हुन्छ: +**सहनशील असफलताहरू** — नकली डाटामा नभएको शहरको मौसम सोध्दा उपकरणले त्रुटि सन्देश फर्काउँछ, र एआईले सहयोग गर्न नसक्ने व्याख्या गर्छ, क्र्यासिंग हुँदैन। उपकरणहरू सुरक्षित रूपमा असफल हुन्छन्। तलको चित्रले दुबै दृष्टिकोणको तुलना गर्छ — सहि त्रुटि ह्यान्डलिङमा एजेन्टले अपवाद समात्छ र सहयोगी प्रतिक्रिया दिन्छ, नभए पूरै एप्लिकेसन क्र्यास हुन्छ: Error Handling Flow -*जब उपकरण असफल हुन्छ, एजेन्टले त्रुटि समात्छ र दुर्घटना नहुने गरी उपयोगी व्याख्या दिन्छ।* +*जब उपकरण असफल हुन्छ, एजेन्टले त्रुटि समात्छ र क्र्यास नगरी सहयोगी व्याख्या सहित प्रतिक्रिया दिन्छ।* -यो सबै एउटै संवाद चरणमा हुन्छ। एजेन्टले धेरै उपकरण कलहरू स्वचालित रूपमा समन्वय गर्छ। +यो एकै वार्तालाप चरणमा हुन्छ। एजेन्टले स्वतन्त्र रूपमा धेरै उपकरण कलहरू समन्वय गर्छ। ## एप्लिकेसन चलाउनुहोस् -**तैनाथ पुष्टि गर्नुहोस्:** +**तैनाती पुष्टि गर्नुहोस्:** -रूट निर्देशिकामा `.env` फाइल Azure प्रमाणपत्रसहित हुनु पर्छ (Module 01 को समयमा सिर्जना गरिएको)। यो मोड्युलको निर्देशिकाबाट (`04-tools/`) यो चलाउनुहोस्: +मूल डाइरेक्टरीमा Azure प्रमाणपत्रहरू सहित `.env` फाइल छ भनेर सुनिश्चित गर्नुहोस् (मोड्युल ०१ मा सिर्जना गरिएको)। मोड्युल डाइरेक्टरीबाट यसलाई चलाउनुहोस् (`04-tools/`): **Bash:** ```bash @@ -202,47 +202,47 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनु **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT देखाउनुपर्छ +Get-Content ..\.env # Azure_OpenAI_Endpoint, API_KEY, DEPLOYMENT देखाउनु पर्छ ``` **एप्लिकेसन सुरु गर्नुहोस्:** -> **टिप्पणी:** यदि तिमीले पहिले नै रूट निर्देशिकाबाट `./start-all.sh` प्रयोग गरी सबै एप्लिकेसन सुरु गरिसकेको छौं (जस्तै Module 01 मा वर्णन), यो मोड्युल पहिले नै पोर्ट 8084 मा चलिरहेको छ। तिम्रो सुरु आदेशहरू छोडेर सिधै http://localhost:8084 मा जान सकिन्छ। +> **टिप्पणी:** यदि तपाईंले पहिले नै मूल डाइरेक्टरीबाट `./start-all.sh` चलाएर सबै एप्लिकेसनहरू सुरु गर्नुभएको छ (जसरी मोड्युल ०१ मा वर्णन गरिएको), यो मोड्युल पोर्ट 8084 मा चलिरहेको छ। तलका सुरु आदेशहरू छोडेर सिधै http://localhost:8084 जानुहोस्। -**विकल्प १: Spring Boot Dashboard प्रयोग (VS Code प्रयोगकर्ताका लागि सिफारिस गरिएको)** +**विकल्प १: स्प्रिंग बुट ड्यासबोर्ड प्रयोग गरी (VS Code प्रयोगकर्ताहरूका लागि सिफारिस गरिएको)** -डिभ कन्टेनरमा Spring Boot Dashboard एक्सटेन्सन समावेश छ, जुन सबै Spring Boot एप्लिकेसनहरूलाई व्यवस्थापन गर्न दृश्यात्मक इन्टरफेस प्रदान गर्छ। VS Code को बायाँपट्टि Activity Bar मा Spring Boot आइकन खोज्नुहोस्। +डेभ कन्टेनरमा स्प्रिंग बुट ड्यासबोर्ड विस्तार समावेश छ, जुन सबै स्प्रिंग बुट एप्लिकेसनहरू व्यवस्थापन गर्न दृश्यात्मक इन्टरफेस प्रदान गर्दछ। तपाईं यसलाई VS Code को Activity Bar मा बायाँतिर स्प्रिंग बुट आइकनमा फेला पार्न सक्नुहुन्छ। -Spring Boot Dashboard बाट तिमीले: -- कार्यक्षेत्रमा सबै उपलब्ध Spring Boot एप्लिकेसनहरू देख्न सक्नेछौ -- एप्लिकेसनहरूलाई एक क्लिकमा सुरु/रोक्न सक्नेछौ -- रियल-टाइम एप्लिकेसन लगहरू हेर्न सक्नेछौ -- एप्लिकेसनको स्थिति ट्रयाक गर्न सक्नेछौ -सिधै "tools" को छेउमा प्ले बटन क्लिक गर्दै यो मोड्युल सुरू गर्नुहोस्, वा सबै मोड्युलहरू एकैपटक सुरू गर्नुहोस्। +स्प्रिंग बुट ड्यासबोर्डबाट तपाईं: +- कार्यक्षेत्रमा सबै उपलब्ध स्प्रिंग बुट एप्लिकेसनहरू देख्न सक्नुहुन्छ +- एक क्लिकमा एप्लिकेसनहरू सुरु/रोक्न सक्नुहुन्छ +- एप्लिकेसन लगहरू वास्तविक समयमा हेर्न सक्नुहुन्छ +- एप्लिकेसनको स्थिति अनुगमन गर्न सक्नुहुन्छ -VS Code मा Spring Boot Dashboard यस्तो देखिन्छ: +"tools" का छेउ प्ले बटन क्लिक गरेर यस मोड्युल सुरु गर्नुहोस्, वा सबै मोड्युलहरू सँगै सुरु गर्न सक्नुहुन्छ। -Spring Boot Dashboard +VS Code मा स्प्रिंग बुट ड्यासबोर्ड कस्तो देखिन्छ त्यो यहाँ छ: +स्प्रिंग बुट ड्यासबोर्ड -*VS Code मा Spring Boot Dashboard — सबै मोड्युलहरू एकै ठाउँबाट सुरू, रोकथाम र अनुगमन गर्नुहोस्* +*VS Code मा स्प्रिंग बुट ड्यासबोर्ड — सबै मोड्युलहरू एकै स्थानबाट सुरु, रोकथाम, र अनुगमन गर्नुहोस्* -**विकल्प २: शेल स्क्रिप्टहरू प्रयोग गर्ने** +**विकल्प २: Shell स्क्रिप्टहरू प्रयोग गर्दै** -संसारभरका सबै वेब अनुप्रयोगहरू (मोड्युल ०१-०४) सुरू गर्नुहोस्: +सबै वेब एप्लिकेशनहरू (मोड्युल ०१-०४) सुरु गर्नुहोस्: **Bash:** ```bash -cd .. # मूल निर्देशिका बाट +cd .. # रुट निर्देशिका बाट ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # रूट निर्देशिका बाट +cd .. # रुट निर्देशिकाबाट .\start-all.ps1 ``` -वा मात्र यो मोड्युल सुरू गर्नुहोस्: +वा यो मोड्युल मात्र सुरु गर्नुहोस्: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -दुवै स्क्रिप्टहरूले स्वतः रूपमा बडा `.env` फाइलबाट वातावरण चरहरू लोड गर्छन् र JAR हरु नभएमा निर्माण गर्नेछन्। +दुवै स्क्रिप्टहरूले स्वतः रुट `.env` फाइलबाट वातावरणीय भेरिएबलहरू लोड गर्छन् र यदि JAR हरू छैनन् भने निर्माण गर्नेछन्। -> **नोट:** यदि तपाईं सबै मोड्युलहरू म्यानुअली निर्माण गर्न चाहनुहुन्छ भने सुरू गर्नु अघि: +> **टिप्पणी:** यदि तपाईं सबै मोड्युलहरू सुरु गर्नु अघि म्यानुअली निर्माण गर्न चाहनुहुन्छ भने: > > **Bash:** > ```bash @@ -272,116 +272,116 @@ cd 04-tools > mvn clean package -DskipTests > ``` -आफ्नो ब्राउजरमा http://localhost:8084 खोल्नुहोस्। +तपाईंको ब्राउजरमा http://localhost:8084 खोल्नुहोस्। -**रोक्न:** +**रोक्नका लागि:** **Bash:** ```bash -./stop.sh # यो मोड्युल मात्रै +./stop.sh # यो मोड्युल मात्र # वा cd .. && ./stop-all.sh # सबै मोड्युलहरू ``` **PowerShell:** ```powershell -.\stop.ps1 # यो मोड्युल मात्र +.\stop.ps1 # यो मोड्यूल मात्र # वा -cd ..; .\stop-all.ps1 # सबै मोड्युलहरू +cd ..; .\stop-all.ps1 # सबै मोड्यूलहरू ``` -## अनुप्रयोग प्रयोग गर्दै +## एप्लिकेशन प्रयोग गर्दै -अनुप्रयोगले वेब इन्टरफेस प्रदान गर्दछ जहाँ तपाईं एउटा AI एजेन्टसँग अन्तरक्रिया गर्न सक्नुहुन्छ जसले मौसम र तापक्रम रूपान्तरण उपकरणहरूमा पहुँच राख्छ। इन्टरफेस यस्तो देखिन्छ — यसमा छिटो सुरू गर्ने उदाहरणहरू र अनुरोधहरू पठाउन च्याट प्यानल समावेश छन्: +एप्लिकेशनले एक वेब इन्टरफेस प्रदान गर्दछ जहाँ तपाईं जलवायु र तापक्रम रूपान्तरण उपकरणहरू पहुँच भएको एआई एजेन्टसँग अन्तरक्रिया गर्न सक्नुहुन्छ। यस्तो देखिन्छ इन्टरफेस — यसमा द्रुत-शुरुवाती उदाहरणहरू र अनुरोध पठाउनको लागि च्याट प्यानल समावेश छ: -AI Agent Tools Interface +एआई एजेन्ट उपकरण इन्टरफेस -*AI एजेन्ट टुल्स इन्टरफेस - उपकरणहरूसँग अन्तरक्रिया गर्न छिटो उदाहरणहरू र च्याट अन्तरफलक* +*एआई एजेन्ट उपकरण इन्टरफेस - उपकरणहरूसँग अन्तरक्रिया गर्ने द्रुत उदाहरणहरू र च्याट इन्टरफेस* ### साधारण उपकरण प्रयोग प्रयास गर्नुहोस् -सरल अनुरोधबाट शुरू गर्नुहोस्: "100 डिग्री फेरनहाइटलाई सेल्सियसमा रूपान्तरण गर्नुहोस्"। एजेन्टले यो बुझ्छ कि तापक्रम रूपान्तरण उपकरण चाहिन्छ, सही प्यारामिटरहरू सहित कल गर्छ र परिणाम फर्काउँछ। ध्यान दिनुहोस् कत्तिको प्राकृतिक महसुस हुन्छ - तपाईंले कुन उपकरण प्रयोग गर्ने वा कसरी कल गर्ने निर्दिष्ट गर्नुपर्ने थिएन। +सिधा अनुरोधबाट सुरु गर्नुहोस्: "१०० डिग्री फारेनहाइटलाई सेल्सियसमा रूपान्तरण गर्नुहोस्"। एजेन्टले चिन्ह लगाउँछ कि तापक्रम रूपान्तरण उपकरण आवश्यक छ, त्यसलाई सही प्यारामिटरहरूका साथ कल गर्छ र परिणाम फर्काउँछ। यो कति प्राकृतिक लाग्छ हेर्नुहोस् — तपाईंले कुन उपकरण प्रयोग गर्ने वा कसरी कल गर्ने भन्ने निर्दिष्ट गर्नुभएको थिएन। ### उपकरण श्रृंखला परीक्षण गर्नुहोस् -अहिले केहि बढी जटिल प्रयास गर्नुहोस्: "सिएटलको मौसम कस्तो छ र यसलाई फेरनहाइटमा रूपान्तरण गर्नुहोस्?" एजेन्टले यसलाई चरणहरूमा काम गर्छ। यसले पहिला मौसम पाउँछ (जसले सेल्सियसमा परिणाम दिन्छ), रूपान्तरण गर्नुपर्ने बुझ्छ, रूपान्तरण उपकरण कल गर्छ, र दुवै परिणामहरूलाई एउटै जवाफमा समेट्छ। +अब केही बढी जटिल प्रयास गर्नुहोस्: "सिएटलको मौसम कस्तो छ र यसलाई फारेनहाइटमा रूपान्तरण गर्नुहोस्?" एजेन्टले यो कदमहरूमार्फत काम गर्छ। पहिलो मौसम पाउँछ (जसले सेल्सियस फर्काउँछ), यो देख्छ कि फारेनहाइटमा रूपान्तरण गर्न आवश्यक छ, रूपान्तरण उपकरण कल गर्छ, र दुई परिणामहरूलाई एउटै प्रतिक्रिया मा जोड्छ। -### संवाद प्रवाह हेर्नुहोस् +### कुराकानी प्रवाह हेर्नुहोस् -च्याट इन्टरफेसले संवाद इतिहास कायम राख्छ, जसले तपाईंलाई बहु-चरण अन्तरक्रियाहरू गर्न अनुमति दिन्छ। तपाईंले सबै अघिल्ला प्रश्नहरू र जवाफहरू देख्न सक्नुहुन्छ, जसले संवाद ट्र्याक गर्न र एजेन्टले कसरी धेरै विनिमयहरूमा सन्दर्भ बनाउँछ बुझ्न सजिलो बनाउँछ। +च्याट इन्टरफेसले कुराकानी इतिहास कायम राख्छ, जसले तपाईंलाई बहु-पटक अन्तरक्रियाहरू गर्न अनुमति दिन्छ। तपाईं सबै अघिल्ला प्रश्न र प्रतिक्रिया हेर्न सक्नुहुन्छ, यसले कुराकानीलाई ट्र्याक गर्न र कसरी एजेन्टले धेरै आदानप्रदानमा सन्दर्भ निर्माण गर्छ बुझ्न सजिलो बनाउँछ। -Conversation with Multiple Tool Calls +वार्तालापमा बहु उपकरण कलहरू -*साधारण रूपान्तरणहरू, मौसम खोजहरू र उपकरण श्रृंखला देखाउने बहु-चरण संवाद* +*साधारण रूपान्तरण, मौसम खोजीहरू, र उपकरण श्रृंखला देखाउँदै बहु-पटकको कुराकानी* -### विभिन्न अनुरोधहरू प्रयोग गरेर प्रयास गर्नुहोस् +### विभिन्न अनुरोधहरूसँग प्रयोग गर्नुहोस् विभिन्न संयोजनहरू प्रयास गर्नुहोस्: -- मौसम खोजहरू: "टोकियोमा मौसम कस्तो छ?" -- तापक्रम रूपान्तरण: "२५°C कति केल्भिन हो?" -- संयुक्त प्रश्नहरू: "पेरिसमा मौसम जाँच गर्नुहोस् र मलाई बताउनुहोस् कि यो २०°C भन्दा माथि छ कि छैन" +- मौसम खोजी: "टोकियोमा मौसम कस्तो छ?" +- तापक्रम रूपान्तरण: "२५°C कति केल्विन हुन्छ?" +- संयुक्त प्रश्नहरू: "पेरिसमा मौसम जाँच्नुहोस् र यदि यो २०°C भन्दा माथि छ भने भन्नुहोस्" -ध्यान दिनुहोस् एजेन्ट कसरी प्राकृतिक भाषालाई बुझ्छ र उपयुक्त उपकरण कलहरूमा नक्सांकन गर्छ। +एजेन्टले प्राकृतिक भाषा कसरी व्याख्या गर्छ र उपयुक्त उपकरण कलहरूमा कसरी नक्शा बनाउँछ ध्यान दिनुहोस्। -## मुख्य अवधारणाहरू +## प्रमुख अवधारणाहरू -### ReAct ढाँचा (तर्क र क्रिया) +### ReAct ढाँचा (कारण र कार्य) -एजेन्टले तर्क गर्ने (के गर्ने निर्णय गर्ने) र क्रिया गर्ने (उपकरणहरू प्रयोग गर्ने) बीचमा पालो पालो काम गर्छ। यस ढाँचाले मात्र निर्देशनमा प्रतिक्रिया दिनुभन्दा स्वतन्त्र समस्या समाधान सक्षम बनाउँछ। +एजेन्टले कारण (के गर्ने निर्णय) र कार्य (उपकरणहरू प्रयोग गर्ने) बिच बारी-बारीले काम गर्छ। यस ढाँचाले स्वतन्त्र समस्या समाधान सक्षम बनाउँछ, केवल निर्देशनहरूको प्रतिक्रिया मात्र नभई। -### उपकरण विवरणले महत्त्व राख्छ +### उपकरणको विवरण महत्त्वपूर्ण छ -तपाईंले दिएको उपकरण विवरणको गुणस्तरले एजेन्टले तिनीहरूको उपयोग कत्तिको राम्रो गर्छ निर्धारण गर्छ। स्पष्ट र विशेष विवरणले मोडेललाई जब र कसरी प्रत्येक उपकरण कल गर्ने बुझ्न मद्दत गर्छ। +तपाईंको उपकरणको वर्णनको गुणस्तरले एजेन्टले ती उपकरणहरू कति राम्ररी प्रयोग गर्छ भन्ने प्रत्यक्ष प्रभाव पार्छ। स्पष्ट, विशिष्ट विवरणहरूले मोडेललाई जब र कसरी प्रत्येक उपकरण कल गर्ने बुझ्न मद्दत गर्दछ। ### सत्र व्यवस्थापन -`@MemoryId` एनोटेशनले स्वतः सत्र-आधारित मेमोरी व्यवस्थापन सक्षम पार्दछ। प्रत्येक सत्र ID लाई यसको आफ्नै `ChatMemory` उदाहरण प्राप्त हुन्छ जुन `ChatMemoryProvider` बीनले व्यवस्थापन गर्छ, जसले गर्दा धेरै प्रयोगकर्ताहरूले एजेन्टसँग एकैसाथ अन्तरक्रिया गर्दा संवादहरु मिसिन हुँदैनन्। तलको चित्रले देखाउँछ कसरी धेरै प्रयोगकर्ताहरूलाई उनीहरूको सत्र ID आधारमा अलग-अलग मेमोरी स्टोरमा पठाइन्छ: +`@MemoryId` एनोटेसनले स्वचालित सत्र-आधारित मेमोरी व्यवस्थापन सक्षम बनाउँछ। प्रत्येक सत्र ID लाई यसको आफ्नै `ChatMemory` इन्स्टेन्स मिल्छ जुन `ChatMemoryProvider` bean द्वारा व्यवस्थापन गरिन्छ, जसले धेरै प्रयोगकर्ताहरूलाई एजेन्टसँग समानान्तर अन्तरक्रिया गर्न अनुमति दिन्छ बिना उनीहरूको कुराकानी मिश्रण हुने। तलको चित्रले देखाउँछ कसरी धेरै प्रयोगकर्ताहरूलाई उनीहरूको सत्र ID अनुसार अलग-अलग मेमोरी स्टोरहरूमा रूट गरिन्छ: Session Management with @MemoryId -*प्रत्येक सत्र ID ले अलग संवाद इतिहाससँग मेल खान्छ — प्रयोगकर्ताहरूले एकअर्काका सन्देशहरू कहिल्यै देख्दैनन्।* +*प्रत्येक सत्र ID अलग कुराकानी इतिहाससँग मेल खान्छ — प्रयोगकर्ताहरू कहिल्यै अरूका सन्देशहरू देख्दैनन्।* ### त्रुटि व्यवस्थापन -उपकरणहरू असफल हुन सक्छन् — API हरू समयावधि पार हुन सक्छ, प्यारामिटरहरू अमान्य हुन सक्छन्, बाह्य सेवा बन्द हुन सक्छ। उत्पादन एजेन्टहरूले त्रुटि व्यवस्थापन आवश्यक छ जसले मोडेललाई समस्याहरू व्याख्या गर्न वा विकल्पहरू प्रयास गर्न दिन्छ, सम्पूर्ण अनुप्रयोग क्र्यास नगर्न। जब कुनै उपकरणले अपवाद फाल्छ, LangChain4j ले यसलाई समातेर त्रुटि सन्देश मोडेलमा फिर्ता पठाउँछ, जसले त्यसपछि प्राकृतिक भाषामा समस्या व्याख्या गर्न सक्छ। +उपकरणहरू असफल हुन सक्छन् — API हरूको समय समाप्त हुन सक्छ, प्यारामिटरहरू अमान्य हुन सक्छन्, बाह्य सेवाहरू बन्द हुन सक्छन्। उत्पादन एजेन्टहरूले त्रुटि व्यवस्थापन आवश्यक हुन्छ ताकि मोडेलले समस्या व्याख्या गर्न वा विकल्पहरू प्रयास गर्न सकून्, सम्पूर्ण एप्लिकेशन क्र्यास नगरोस्। जब उपकरणले अपवाद फ्याँक्छ, LangChain4j ले यसलाई समात्छ र त्रुटि सन्देश मोडेलमा फिडब्याक गर्छ, जसले त्यसपछि प्राकृतिक भाषामा समस्या व्याख्या गर्न सक्छ। ## उपलब्ध उपकरणहरू -तलको चित्रले तपाईंले निर्माण गर्न सक्ने विभिन्न उपकरणहरूको व्यापक पारिस्थितिकी प्रणाली देखाउँछ। यस मोड्युलले मौसम र तापक्रम उपकरणहरू देखाउँछ, तर उस्तै `@Tool` ढाँचाले कुनै पनि Java मेथडसँग काम गर्छ — डाटाबेस सोधहरूदेखि भुक्तानी प्रक्रिया सम्म। +तलको चित्रले तपाईंले बनाउन सक्ने उपकरणहरूको व्यापक पारिस्थितिकी देखाउँछ। यस मोड्युलले मौसम र तापक्रम उपकरणहरू देखाउँछ, तर त्यही `@Tool` ढाँचा कुनै पनि Java मेथडमा लागू हुन्छ — डेटाबेस क्वेरीहरूदेखि भुक्तानी प्रक्रिया सम्म। -Tool Ecosystem +उपकरण पारिस्थितिकी -*@Tool एनोटेसन भएका कुनै पनि Java मेथड AI को लागि उपलब्ध हुन्छन् — यस ढाँचाले डाटाबेस, API, इमेल, फाइल अपरेसन र अन्यलाई विस्तार गर्छ।* +*कुनै पनि Java मेथड `@Tool` संग एनोटेट गरिएको छ भने AI को लागि उपलब्ध हुन्छ — यो ढाँचा डेटाबेस, API, इमेल, फाइल अपरेसनहरू र अझ धेरैमा फैलिएको छ।* -## उपकरण-आधारित एजेन्टहरू कहिले प्रयोग गर्ने +## कहिले उपकरण आधारित एजेन्टहरू प्रयोग गर्ने -सबै अनुरोधहरूलाई उपकरणहरू आवश्यक पर्दैनन्। निर्णय त्योमा निर्भर गर्दछ कि AI ले बाह्य प्रणालीहरूसँग अन्तरक्रिया गर्न आवश्यक छ वा आफ्नै ज्ञानबाट उत्तर दिन सक्छ। तलको मार्गदर्शकले संवाद गर्छ कहिले उपकरणहरूले मूल्य थप्छ र कहिले आवश्यक हुँदैन: +हरेक अनुरोधलाई उपकरणहरू चाहिँदैन। निर्णय यसमा निर्भर गर्दछ कि AI लाई बाह्य प्रणालीहरूसँग अन्तरक्रिया गर्नु आवश्यक छ वा त्यो आफ्नै ज्ञानबाट उत्तर दिन सक्छ। तलको मार्गदर्शकले सारांश गर्छ कहिले उपकरणले मूल्य थप्छ र कहिले आवश्यक हुँदैन: -When to Use Tools +कहिले उपकरण प्रयोग गर्ने -*छिटो निर्णय मार्गदर्शक — उपकरणहरू वास्तविक-समय डेटा, गणना र क्रियाकलापका लागि; सामान्य ज्ञान र सिर्जनात्मक कार्यहरूका लागि आवश्यक छैनन्।* +*छिटो निर्णय मार्गदर्शक — उपकरणहरू वास्तविक-समय डाटा, गणना, र कार्यहरूका लागि; सामान्य ज्ञान र सिर्जनात्मक कार्यहरूलाई आवश्यकता छैन।* ## उपकरणहरू बनाम RAG -मोड्युल ०३ र ०४ दुबै AI ले के गर्ने क्षमता विस्तार गर्छन्, तर आधारभूत रूपमा फरक तरिकाले। RAG मोडेललाई **ज्ञान** पहुँच दिन्छ कागजातहरू पुन: प्राप्त गरेर। उपकरणहरूले मोडेललाई **क्रियाकलापहरू** गर्न सक्षम बनाउँछन् फंक्शनहरू कल गरेर। तलको चित्रले यी दुई दृष्टिकोणहरू साइड बाई साइड तुलना गर्दछ — कसरी प्रत्येक वर्कफ्लो सञ्चालन गर्छ र तिनीहरूबीचको व्यापारिक पक्षहरू देखाएर: +मोड्युल ०३ र ०४ ले दुबै AI ले के गर्न सक्छ भन्दार विस्तार गर्छ, तर मौलिक रूपमा फरक तरिकाले। RAG ले मोडेललाई **ज्ञान** प्रदान गर्छ दस्तावेजहरू पुन: प्राप्त गरेर। उपकरणहरूले मोडेललाई **कार्यहरू** गर्न अनुमति दिन्छ फंक्शनहरू कल गरेर। तलको चित्रले यी दुई दृष्टिकोणहरू साइड-बाइ-साइड तुलना गर्छ — प्रत्येक कार्यप्रवाह कसरी चल्छ र तिनीहरूबीचको साटासाटहरू: -Tools vs RAG Comparison +उपकरणहरू बनाम RAG तुलना -*RAG स्थिर कागजातहरूबाट जानकारी पुन: प्राप्त गर्छ — उपकरणहरूले क्रियाकलापहरू कार्यान्वयन गर्छन् र गतिशील, वास्तविक-समय डेटा ल्याउँछन्। धेरै उत्पादन प्रणालीहरूले दुबै संयोजन गर्छन्।* +*RAG ले स्थिर दस्तावेजहरूबाट जानकारी ल्याउँछ — उपकरणहरूले कार्यहरू कार्यान्वयन गर्छन् र गतिशील, वास्तविक-समय डाटा फेच गर्छन्। धेरै उत्पादन प्रणालीहरूले दुबै संयोजन गर्छन्।* -व्यावहारिक रूपमा, धेरै उत्पादन प्रणालीहरूले दुबै दृष्टिकोणहरू संयोजन गर्छन्: RAG द्वारा तपाईंको कागजातहरूमा उत्तरहरू आधारित गर्ने, र उपकरणहरू द्वारा प्रत्यक्ष डेटा ल्याउने वा सञ्चालन गर्ने। +व्यावहारिक रूपमा, धेरै उत्पादन प्रणालीहरूले दुबै दृष्टिकोण संयोजन गर्छन्: RAG लाई तपाईंको कागजातहरूमा उत्तरहरू आधारभूत बनाउन, र उपकरणहरूलाई प्रत्यक्ष डाटा ल्याउन वा अपरेशनहरू प्रदर्शन गर्न। -## आगामी चरणहरू +## अर्को कदम -**अर्को मोड्युल:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**अर्को मोड्युल:** [05-mcp - मोडेल सन्दर्भ प्रोटोकॉल (MCP)](../05-mcp/README.md) --- -**नेभीगेसन:** [← अघिल्लो: मोड्युल ०३ - RAG](../03-rag/README.md) | [मुख्य पृष्ठमा फर्कनुहोस्](../README.md) | [अर्को: मोड्युल ०५ - MCP →](../05-mcp/README.md) +**नेभिगेसन:** [← अघिल्लो: मोड्युल ०३ - RAG](../03-rag/README.md) | [मुख्यमा फर्कनुहोस्](../README.md) | [अर्को: मोड्युल ०५ - MCP →](../05-mcp/README.md) --- -**अस्वीकरण**: -यो दस्तावेज् AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरी अनुवाद गरिएको हो। हामी शुद्धताको लागि प्रयासरत छौं, तर कृपया ध्यान दिनुहोस् कि स्वचालित अनुवादहरूमा त्रुटि वा असत्यता हुन सक्दछ। मूल दस्तावेज आफ्नो मातृ भाषामा नै आधिकारिक स्रोत मान्नुपर्छ। महत्वपूर्ण जानकारीको लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलतफहमी वा गलत व्याख्या को लागि हाम्रो जिम्मेवारी हुँदैन। +**अस्वीकरण**: +यो दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी सही हुन प्रयास गर्छौं, तर कृपया जानकार हुनुस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छन्। मूल दस्तावेज़ यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलत बुझाइ वा त्रुटिको लागि हामी जिम्मेवार छैनौं। \ No newline at end of file diff --git a/translations/ne/README.md b/translations/ne/README.md index 6b1bdfb2e..600f1d0eb 100644 --- a/translations/ne/README.md +++ b/translations/ne/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j शुरु गर्नेहरूका लागि +# LangChain4j आरम्भकर्ताहरूका लागि -LangChain4j र Azure OpenAI GPT-5.2 सँग एआई अनुप्रयोगहरू बनाउनको लागि कोर्स, आधारभूत च्याटदेखि एआई एजेन्टहरू सम्म। +LangChain4j र Azure OpenAI GPT-5.2 सँग AI अनुप्रयोगहरू निर्माण गर्ने पाठ्यक्रम, आधारभूत च्याटदेखि AI एजेन्टहरू सम्म। -### 🌐 बहुभाषी समर्थन +### 🌐 बहुभाषिक समर्थन -#### GitHub Action मार्फत समर्थित (स्वचालित र सधैं अपडेट भइरहने) +#### GitHub Action मार्फत समर्थन गरिएको (स्वचालित र सँधै अद्यावधिक) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](./README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **स्थानीय रूपमा क्लोन गर्न रुचाउनुहुन्छ?** +> **स्थानीय रूपमा क्लोन गर्न मन छ?** > -> यो रिपोजिटरीमा ५०+ भाषाका अनुवादहरू समावेश छन् जसले डाउनलोड साइजलाई उल्लेखनीय रूपमा बढाउँछ। अनुवादहरू बिना क्लोन गर्न, sparse checkout प्रयोग गर्नुहोस्: +> यो रिपोजिटरीमा ५०+ भाषा अनुवादहरू समावेश गरिएको छ जसले डाउनलोड आकारलाई उल्लेखनीय रूपमा बढाउँछ। अनुवादहरू बिना क्लोन गर्नको लागि, sparse checkout प्रयोग गर्नुहोस्: > > **Bash / macOS / Linux:** > ```bash @@ -29,60 +29,61 @@ LangChain4j र Azure OpenAI GPT-5.2 सँग एआई अनुप्रय > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> यसले तपाईंलाई कोर्स पूरा गर्न आवश्यक सबै कुराहरू द्रुत डाउनलोडसँग प्रदान गर्छ। +> यसले तपाईंलाई कोर्स पूरा गर्न आवश्यक सबै कुरा छिटो डाउनलोडको साथ दिन्छ। -## सामग्री तालिका +## विषय सूची -1. [द्रुत सुरु](00-quick-start/README.md) - LangChain4j संग सुरु गर्ने -2. [परिचय](01-introduction/README.md) - LangChain4j का आधारहरू सिक्नुहोस् -3. [प्रॉम्प्ट इन्जिनियरिङ](02-prompt-engineering/README.md) - प्रभावकारी प्रॉम्प्ट डिजाइन मास्टर गर्नुहोस् -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - बुद्धिमान ज्ञान आधारित प्रणालीहरू निर्माण गर्नुहोस् -5. [उपकरणहरू](04-tools/README.md) - बाह्य उपकरणहरू र सरल सहायकहरू समाहित गर्नुहोस् -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Model Context Protocol (MCP) र Agentic मोड्युलहरूसँग काम गर्नुहोस् +1. [परिचय](01-introduction/README.md) - LangChain4j का आधारभूत कुरा सिक्नुहोस् +2. [प्रॉम्प्ट इन्जिनियरिङ](02-prompt-engineering/README.md) - प्रभावकारी प्रॉम्प्ट डिजाइनमा दक्षता हासिल गर्नुहोस् +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - बुद्धिमान ज्ञान-आधारित प्रणालीहरू निर्माण गर्नुहोस् +4. [साधनहरू](04-tools/README.md) - बाह्य उपकरण र सरल सहायकहरू एकीकृत गर्नुहोस् +5. [MCP (मोडेल सन्दर्भ प्रोटोकल)](05-mcp/README.md) - मोडेल सन्दर्भ प्रोटोकल (MCP) र एजेन्टिक मोड्युलहरूसँग काम गर्नुहोस् -### भिडियो मार्गदर्शनहरू +### भिडियो वाकथ्रु -हरेक मोड्युलमा सहायक प्रत्यक्ष सत्र छ जहाँ हामी चरण-दर-चरण अवधारणाहरू र कोडहरू सम्झाउँछौं। +हरेक मोड्युलसँगसँगै एकप्रत्यक्ष सत्र हुन्छ जहाँ हामी अवधारणाहरू र कोडलाई चरण-द्वारा-चरण हिँडाउँछौं। -| Module | Video | +| मोड्युल | भिडियो | |--------|-------| -| 01 - Introduction | [LangChain4j संग सुरु गर्नुहोस्](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Prompt Engineering | [LangChain4j संग प्रॉम्प्ट इन्जिनियरिङ](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [LangChain4j संग RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Tools & 05 - MCP | [उपकरणहरू र MCP सहित AI एजेन्टहरू](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 01 - परिचय | [LangChain4j सँग सुरु गर्दै](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - प्रॉम्प्ट इन्जिनियरिङ | [LangChain4j सँग प्रॉम्प्ट इन्जिनियरिङ](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [LangChain4j सँग RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 04 - उपकरण र 05 - MCP | [उपकरण र MCP सँग AI एजेन्टहरू](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## सिक्ने बाटो +## सिक्ने मार्ग -**LangChain4j नयाँ हुनुहुन्छ?** मुख्य शब्दहरू र अवधारणाहरूका लागि [शब्द सूची](docs/GLOSSARY.md) जाँच गर्नुहोस्। +**LangChain4j मा नयाँ हुनुहुन्छ?** मुख्य शब्दहरू र अवधारणा हरूका परिभाषाहरूको लागि [शब्द सूची](docs/GLOSSARY.md) हेरौं। -> **द्रुत सुरु** +> **छिटो सुरु गर्न** -1. यो रिपोजिटरीलाई आफ्नो GitHub खातामा Fork गर्नुहोस् +1. यो रिपोजिटरी तपाईंको GitHub खातामा Fork गर्नुहोस् 2. क्लिक गर्नुहोस् **Code** → **Codespaces** ट्याब → **...** → **New with options...** -3. पूर्वनिर्धारितहरू प्रयोग गर्नुहोस् – यसले यस कोर्सका लागि सिर्जना गरिएको Development कन्टेनर चयन गर्नेछ +3. डिफल्टहरू प्रयोग गर्नुहोस् – यसले यस पाठ्यक्रमको लागि बनाइएको Development container चयन गर्नेछ 4. क्लिक गर्नुहोस् **Create codespace** -5. वातावरण तयार हुन ५-१० मिनेट कुर्नुहोस् -6. सिधा [द्रुत सुरु](./00-quick-start/README.md) मा जानुहोस् र सुरु गर्नुहोस्! +5. वातावरण तयार हुन ५-१० मिनेट पर्खनुहोस् +6. सुरूवात गर्न [परिचय](./01-introduction/README.md) सँग सिधै जानुहोस्! -मोड्युलहरू पूरा गरेपछि, [परीक्षण मार्गदर्शन](docs/TESTING.md) अन्वेषण गर्नुहोस् जसले LangChain4j परीक्षण अवधारणाहरूलाई क्रियाशील रूपमा देखाउँछ। +मोड्युलहरू पूरा गरेपछि, LangChain4j परीक्षण अवधारणाहरूलाई क्रियामा हेर्न [परीक्षण मार्गदर्शिका](docs/TESTING.md) अन्वेषण गर्नुहोस्। -> **ध्यान:** यो तालिमले GitHub मोडेल र Azure OpenAI दुवै प्रयोग गर्छ। [द्रुत सुरु](00-quick-start/README.md) मोड्युल GitHub मोडेलहरू प्रयोग गर्छ (Azure सदस्यता आवश्यक छैन), जबकि मोड्युल १-५ Azure OpenAI प्रयोग गर्छ। निसुल्क Azure खाता नभए [यहाँबाट पाउनुहोस्](https://aka.ms/azure-free-account)। +> **सुझाव:** यो प्रशिक्षण Azure OpenAI प्रयोग गर्दछ। तपाइंसँग नभएमा [FREE Azure account](https://aka.ms/azure-free-account) बाट शुरू गर्नुहोस्। -## GitHub Copilot सँग सिकाइ -छिटो कोडिङ सुरु गर्न, यस प्रोजेक्टलाई GitHub Codespace वा प्रदान गरिएको devcontainer सँग तपाईंको स्थानीय IDE मा खोल्नुहोस्। यस कोर्समा प्रयोग गरिएको devcontainer पहिले नै GitHub Copilot सँग पूर्व-कन्फिगर गरिएको छ जुन AI जोडी प्रोग्रामिङका लागि आवश्यक छ। +## GitHub Copilot सङ्ग सिकाई -हरेक कोड उदाहरणमा GitHub Copilot लाई सोध्न सक्ने सल्लाहसहितका प्रश्नहरू समावेश छन् जुन तपाईंको बुझाइलाई गहिरो बनाउनेछ। यी माथि 💡/🤖 संकेतहरूमा हेर्नुहोस्: +छिटो कोडिङ सुरु गर्न, यस परियोजनालाई GitHub Codespace मा वा तपाईंको स्थानीय IDE मा devcontainer सहित खोल्नुहोस्। यस कोर्समा प्रयोग गरिएको devcontainer मा AI जोडी प्रोग्रामिङका लागि GitHub Copilot पहिले देखि नै कन्फिगर गरिएको छ। + +हरेक कोड उदाहरणमा GitHub Copilot सँग तपाईंले सोध्न सक्ने सुझाइएको प्रश्नहरू समावेश छन् जसले तपाईंको बुझाइलाई गहिरो बनाउँछन्। 💡/🤖 संकेतहरू हेर्नुहोस्: - **Java फाइल हेडरहरू** - प्रत्येक उदाहरणका लागि विशेष प्रश्नहरू -- **मोड्युल READMEs** - कोड उदाहरण पछिका अन्वेषण प्रॉम्प्टहरू +- **मोड्युल READMEहरू** - कोड उदाहरण पछिको अन्वेषण प्रश्नहरू + +**कसरी प्रयोग गर्ने:** कुनै पनि कोड फाइल खोल्नुहोस् र सुझाइएको प्रश्नहरू Copilot लाई सोध्नुहोस्। यसलाई कोडबेसको पूर्ण सन्दर्भ छ र यो व्याख्या, विस्तार, र वैकल्पिक सुझाव दिन सक्छ। -**कसरी प्रयोग गर्ने:** कुनै पनि कोड फाइल खोल्नुहोस् र Copilot लाई सुझाव गरिएको प्रश्नहरू सोध्नुहोस्। यसले कोडबेसको पूर्ण सन्दर्भ बुझेको हुन्छ र व्याख्या, विस्तार र विकल्पहरू सुझाव दिन सक्छ। +थप जान्न चाहनुहुन्छ? [AI जोडी प्रोग्रामिङका लागि Copilot](https://aka.ms/GitHubCopilotAI) हेरौं। -थप जान्न चाहनुहुन्छ? [AI जोडी प्रोग्रामिङको लागि Copilot](https://aka.ms/GitHubCopilotAI) जाँच गर्नुहोस्। ## थप स्रोतहरू @@ -109,40 +110,41 @@ LangChain4j र Azure OpenAI GPT-5.2 सँग एआई अनुप्रय --- -### Core Learning +### मूल सिकाइ [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Copilot श्रृंखला +### कोपायलट सिरिज [![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## मद्दत प्राप्त गर्दै +## सहायता प्राप्त गर्नुहोस् -यदि तपाईं अड्किनुभयो वा AI अनुप्रयोगहरू निर्माण गर्ने बारे कुनै प्रश्न छ भने, सामेल हुनुहोस्: +यदि तपाईं अड्किनुभयो वा AI एपहरू निर्माण गर्दा कुनै प्रश्नहरू छन् भने, सम्मिलित हुनुहोस्: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -यदि तपाईंलाई उत्पादन प्रतिक्रिया वा निर्माण गर्ने क्रममा त्रुटिहरू छन् भने भ्रमण गर्नुहोस्: +यदि तपाईंलाई उत्पादन प्रतिक्रिया वा त्रुटिहरू छन् भने, भ्रमण गर्नुहोस्: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) -## लाइसेन्स +## अनुज्ञा पत्र MIT License - विवरणहरूको लागि [LICENSE](../../LICENSE) फाइल हेर्नुहोस्। --- -**अस्वीकरण**: -यो दस्तावेज AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) को उपयोग गरेर अनुवाद गरिएको हो। हामी शुद्धताका लागि प्रयासरत छौं भने पनि, कृपया ध्यान दिनुहोस् कि स्वत: अनुवादमा त्रुटिहरू वा अशुद्धिहरू हुन सक्छन्। मूल दस्तावेज यसको मातृभाषामा नै अधिकारिक स्रोत मानिनु पर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलतफहमि वा गलत व्याख्याबारे हामी जिम्मेवार हुने छैनौं। +**अस्वीकरण**: +यो दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी सही हुन प्रयास गर्छौं, तर कृपया जानकार हुनुस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छन्। मूल दस्तावेज़ यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलत बुझाइ वा त्रुटिको लागि हामी जिम्मेवार छैनौं। \ No newline at end of file diff --git a/translations/ne/docs/GLOSSARY.md b/translations/ne/docs/GLOSSARY.md index 76c315f6f..3eccf69f3 100644 --- a/translations/ne/docs/GLOSSARY.md +++ b/translations/ne/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## सामग्री तालिका -- [मुख्य अवधारणाहरू](../../../docs) -- [LangChain4j कम्पोनेन्टहरू](../../../docs) -- [AI/ML अवधारणाहरू](../../../docs) -- [गार्डरेइलहरू](../../../docs) -- [प्रम्प्ट इन्जिनियरिङ](../../../docs) -- [RAG (पुन:प्राप्ति-सहायता उत्पादन)](../../../docs) -- [एजेण्टहरू र उपकरणहरू](../../../docs) -- [एजेण्टिक मोड्युल](../../../docs) -- [मोडेल सन्दर्भ प्रोटोकल (MCP)](../../../docs) -- [एजुर सेवाहरू](../../../docs) -- [परीक्षण र विकास](../../../docs) - -कोर्सभर प्रयोग भएका पदहरू र अवधारणाहरूको छिटो सन्दर्भ। +- [मुख्य अवधारणाहरू](#मुख्य-अवधारणाहरू) +- [LangChain4j कम्पोनेन्टहरू](#langchain4j-कम्पोनेन्टहरू) +- [AI/ML अवधारणाहरू](#aiml-अवधारणाहरू) +- [गार्डरेलहरू](#गार्डरेलहरू) +- [प्रॉम्प्ट इन्जिनियरिङ](#prompt-engineering---module-02) +- [RAG (प्राप्ति-सशक्त पीढी)](#rag-retrieval-augmented-generation---module-03) +- [एजेण्टहरू र उपकरणहरू](#agents-and-tools---module-04) +- [एजेण्टिक मोड्युल](#agentic-module---module-05) +- [मोडेल सन्दर्भ प्रोटोकल (MCP)](#model-context-protocol-mcp---module-05) +- [एज्योर सेवा](#azure-services---module-01) +- [परीक्षण र विकास](#testing-and-development---testing-guide) + +पाठ्यक्रमभर प्रयोग भएका शब्दहरू र अवधारणाहरूको छिटो सन्दर्भ। ## मुख्य अवधारणाहरू -**AI Agent** - यस्तो प्रणाली जुन AI प्रयोग गरेर तर्क गर्छ र स्वायत्त रूपमा कार्य गर्दछ। [मोड्युल ०४](../04-tools/README.md) +**AI एजेन्ट** - स्वायत्त रूपमा तर्क गर्न र कार्य गर्न AI प्रयोग गर्ने प्रणाली। [मोड्युल 04](../04-tools/README.md) -**Chain** - अपरेसनहरूको अनुक्रम जसमा आउटपुट अर्को चरणमा जाँछ। +**चेन** - अपरेसनहरूको श्रृंखला जहाँ आउटपुट अर्को चरणलाई फिड हुन्छ। -**Chunking** - कागजातहरू साना भागहरूमा तोड्ने। सामान्य: ३००-५०० टोकनहरू ओभरलैप सहित। [मोड्युल ०३](../03-rag/README.md) +**चंकिङ** - दस्तावेजहरूलाई साना भागहरूमा तोड्ने। सामान्य: ३००-५०० टोकनहरू ओभरल्याप सहित। [मोड्युल 03](../03-rag/README.md) -**Context Window** - मोडेलले प्रक्रिया गर्न सक्ने अधिकतम टोकनहरू। GPT-5.2: ४००K टोकनहरू (२७२K इन्पुट सम्म, १२८K आउटपुट)। +**सन्दर्भ विन्डो** - मोडेलले प्रक्रिया गर्न सक्ने अधिकतम टोकनहरू। GPT-5.2: ४००K टोकन (२७२K इनपुट सम्म, १२८K आउटपुट)। -**Embeddings** - पाठको अर्थ प्रतिनिधित्व गर्ने सङ्ख्यात्मक भेक्टरहरू। [मोड्युल ०३](../03-rag/README.md) +**एम्बेडिङहरू** - पाठको अर्थ प्रतिनिधित्व गर्ने संख्यात्मक वेक्टरहरू। [मोड्युल 03](../03-rag/README.md) -**Function Calling** - मोडेलले बाह्य कार्यहरू कल गर्न संरचित अनुरोधहरू उत्पादन गर्छ। [मोड्युल ०४](../04-tools/README.md) +**फंक्शन कलिङ** - मोडेलले संरचित अनुरोधहरू सिर्जना गरेर बाह्य फंक्शनहरू कल गर्छ। [मोड्युल 04](../04-tools/README.md) -**Hallucination** - मोडेलहरूले गलत तर सम्भावित जानकारी उत्पादन गर्ने घटना। +**हल्युसिनेसन** - मोडेलहरूले गलत तर सम्भाव्य जानकारी उत्पादन गर्दा। -**Prompt** - भाषा मोडेलमा दिइने पाठ इनपुट। [मोड्युल ०२](../02-prompt-engineering/README.md) +**प्रॉम्प्ट** - भाषा मोडेलमा टेक्स्ट इनपुट। [मोड्युल 02](../02-prompt-engineering/README.md) -**Semantic Search** - अर्थ अनुसार खोज्ने, कुञ्जीशब्द होइन, embeddings प्रयोग गरेर। [मोड्युल ०३](../03-rag/README.md) +**सेम्यान्टिक खोज** - कीवर्ड होइन, अर्थ प्रयोग गरेर खोज्न embeddings प्रयोग। [मोड्युल 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: कुनै मेमोरी हुँदैन। Stateful: कुराकानी इतिहास राख्छ। [मोड्युल ०१](../01-introduction/README.md) +**स्टेटफुल बनाम स्टेटलेस** - स्टेटलेस: कुनै स्मृति छैन। स्टेटफुल: संवाद इतिहास राख्छ। [मोड्युल 01](../01-introduction/README.md) -**Tokens** - मोडेलले प्रक्रिया गर्ने आधारभूत पाठ इकाइहरू। लागत र सीमाहरूमा असर गर्छ। [मोड्युल ०१](../01-introduction/README.md) +**टोकनहरू** - मोडेलहरूले प्रशोधन गर्ने आधारभूत टेक्स्ट इकाइहरू। लागत र सीमामा प्रभाव पार्ने। [मोड्युल 01](../01-introduction/README.md) -**Tool Chaining** - उपकरणहरूको अनुक्रमिक कार्यान्वयन जहाँ आउटपुटले अर्को कललाई सूचना दिन्छ। [मोड्युल ०४](../04-tools/README.md) +**टुल चेनिङ** - क्रमागत रूपमा उपकरणहरूको क्रियान्वयन जहाँ आउटपुटले अर्को कल जानकारी दिन्छ। [मोड्युल 04](../04-tools/README.md) ## LangChain4j कम्पोनेन्टहरू -**AiServices** - प्रकार-सुरक्षित AI सेवा अन्तरफेसहरू सिर्जना गर्छ। +**AiServices** - प्रकार-सुरक्षित AI सेवा इन्टरफेसहरू सिर्जना गर्छ। -**OpenAiOfficialChatModel** - OpenAI र Azure OpenAI मोडेलहरूको एकीकृत क्लाइन्ट। +**OpenAiOfficialChatModel** - OpenAI र Azure OpenAI मोडेलहरूका लागि एकीकृत क्लाइन्ट। -**OpenAiOfficialEmbeddingModel** - OpenAI आधिकारिक क्लाइन्ट प्रयोग गरेर embeddings सिर्जना गर्छ (OpenAI र Azure OpenAI दुवै समर्थन गर्दछ)। +**OpenAiOfficialEmbeddingModel** - OpenAI Official क्लाइन्ट प्रयोग गरेर embeddings सिर्जना गर्छ (OpenAI र Azure OpenAI दुइटै समर्थन गर्दछ)। -**ChatModel** - भाषा मोडेलहरूको मुख्य अन्तरफेस। +**ChatModel** - भाषा मोडेलहरूको मुख्य इन्टरफेस। -**ChatMemory** - कुराकानी इतिहास कायम राख्छ। +**ChatMemory** - संवाद इतिहास राख्छ। -**ContentRetriever** - RAG का लागि सान्दर्भिक कागजातका टुक्राहरू फेला पार्छ। +**ContentRetriever** - RAG का लागि सान्दर्भिक दस्तावेज चंकहरू खोज्छ। -**DocumentSplitter** - कागजातहरूलाई टुक्राहरूमा तोड्छ। +**DocumentSplitter** - दस्तावेजहरूलाई चंकहरूमा तोड्छ। -**EmbeddingModel** - पाठलाई सङ्ख्यात्मक भेक्टरहरूमा रूपान्तरण गर्छ। +**EmbeddingModel** - टेक्स्टलाई संख्यात्मक वेक्टरहरूमा रूपान्तरण गर्छ। -**EmbeddingStore** - embeddings भण्डारण र पुन:प्राप्ति गर्छ। +**EmbeddingStore** - embeddings भण्डार र पुनः प्राप्त गर्छ। -**MessageWindowChatMemory** - भर्खरका सन्देशहरूको स्लाइडिङ विन्डो कायम राख्छ। +**MessageWindowChatMemory** - हालसालैका सन्देशहरू को स्लाइडिङ विन्डो राख्छ। -**PromptTemplate** - `{{variable}}` प्लेसहोल्डरहरूसहित पुन: प्रयोगयोग्य प्रम्प्टहरू सिर्जना गर्छ। +**PromptTemplate** - `{{variable}}` प्लेसहोल्डरहरू सहित पुन: प्रयोगयोग्य प्रॉम्प्टहरू सिर्जना गर्छ। -**TextSegment** - मेटाडेटा सहितको पाठ टुक्रा। RAG मा प्रयोग हुन्छ। +**TextSegment** - मेटाडाटा सहितको टेक्स्ट चंक। RAG मा प्रयोग गरिन्छ। **ToolExecutionRequest** - उपकरण कार्यान्वयन अनुरोध प्रतिनिधित्व गर्छ। -**UserMessage / AiMessage / SystemMessage** - कुराकानी सन्देश प्रकारहरू। +**UserMessage / AiMessage / SystemMessage** - संवाद सन्देश प्रकारहरू। ## AI/ML अवधारणाहरू -**Few-Shot Learning** - प्रम्प्टहरूमा उदाहरणहरू प्रदान गर्ने। [मोड्युल ०२](../02-prompt-engineering/README.md) +**फ्यु-शट लर्निङ** - प्रॉम्प्टहरूमा उदाहरणहरू समावेश गर्ने। [मोड्युल 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - विशाल पाठ डाटामा तालिम प्राप्त AI मोडेलहरू। +**लार्ज ल्याङ्ग्वेज मोडेल (LLM)** - व्यापक टेक्स्ट डाटामा प्रशिक्षित AI मोडेलहरू। -**Reasoning Effort** - GPT-5.2 को सोच्ने गहिराइ नियन्त्रण गर्ने प्यारामिटर। [मोड्युल ०२](../02-prompt-engineering/README.md) +**तर्क प्रयास** - GPT-5.2 को तर्क गहिराइ नियन्त्रण गर्ने प्यारामिटर। [मोड्युल 02](../02-prompt-engineering/README.md) -**Temperature** - आउटपुट अनियमितता नियन्त्रण गर्छ। कम=नियतात्मक, उच्च=सृजनात्मक। +**टेम्परेचर** - आउटपुटको यादृच्छिकता नियन्त्रण गर्छ। कम=नियतात्मक, उच्च=रचनात्मक। -**Vector Database** - embeddings को लागि विशेष डेटाबेस। [मोड्युल ०३](../03-rag/README.md) +**भेक्टर डेटाबेस** - embeddings का लागि विशेष डेटाबेस। [मोड्युल 03](../03-rag/README.md) -**Zero-Shot Learning** - उदाहरण बिना कार्यहरू गर्ने। [मोड्युल ०२](../02-prompt-engineering/README.md) +**जीरो-शट लर्निङ** - उदाहरण बिना कार्यहरू प्रदर्शन गर्ने। [मोड्युल 02](../02-prompt-engineering/README.md) -## गार्डरेइलहरू - [मोड्युल ००](../00-quick-start/README.md) +## गार्डरेलहरू -**Defense in Depth** - बहु-स्तर सुरक्षा दृष्टिकोण जसले एप्लिकेसन-स्तर गार्डरेइलहरू र प्रदायक सुरक्षा फिल्टरहरू संयोजन गर्छ। +**डीफेन्स इन डेप्थ** - एप्लिकेशन-स्तर गार्डरेलहरू र प्रदायक सुरक्षा फिल्टरहरू सम्मिलित बहु-परत सुरक्षा उपाय। -**Hard Block** - गम्भीर सामग्री उल्लंघनमा प्रदायकले HTTP 400 त्रुटि फ्याँक्छ। +**हार्ड ब्लक** - गम्भीर सामग्री उल्लङ्घनहरूमा प्रदायकले HTTP 400 त्रुटि फाल्छ। -**InputGuardrail** - LLM सम्म पुग्नु अघि प्रयोगकर्ता इनपुट जाँच गर्न LangChain4j को इन्टरफेस। हानिकारक प्रम्प्टहरूलाई छिटो रोक्दै लागत र विलम्बता बचत गर्छ। +**InputGuardrail** - LLM सम्म पुग्नु अघि प्रयोगकर्ता इनपुट जाँच्ने LangChain4j इन्टरफेस। हानिकारक प्रॉम्प्टहरू चाँडो ब्लक गरेर लागत र ढिलाइ बचत गर्छ। -**InputGuardrailResult** - गार्डरेइल मान्यता फिर्ता प्रकार: `success()` वा `fatal("reason")`। +**InputGuardrailResult** - गार्डरेल मान्यकरणको लागि रिटर्न प्रकार: `success()` वा `fatal("reason")`। -**OutputGuardrail** - प्रयोगकर्तालाई फिर्ता गर्ने अघि AI प्रतिक्रियाहरू मान्य गर्ने इन्टरफेस। +**OutputGuardrail** - AI प्रतिक्रियाहरू प्रयोगकर्तालाई फर्काउनु अघि मान्य गर्ने इन्टरफेस। -**Provider Safety Filters** - AI प्रदायकहरू (जस्तै GitHub Models) बाट निर्मित सामग्री फिल्टरहरू जसले API स्तरमा उल्लंघनहरू पत्ता लगाउँछन्। +**Provider Safety Filters** - API स्तरमा उल्लङ्घनहरू पत्ता लगाउन AI प्रदायकहरू (जस्तै Azure OpenAI) द्वारा निर्मित सामग्री फिल्टरहरू। -**Soft Refusal** - मोडेलले शिष्टतापूर्वक उत्तर दिन अस्वीकृत गर्छ तर त्रुटि फ्याँक्दैन। +**Soft Refusal** - मोडेलले त्रुटि नफालेर शिष्टताका साथ जवाफ दिन अस्वीकार गर्दछ। -## प्रम्प्ट इन्जिनियरिङ - [मोड्युल ०२](../02-prompt-engineering/README.md) +## प्रॉम्प्ट इन्जिनियरिङ - [मोड्युल 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - राम्रो शुद्धताको लागि चरण-दर-चरण तर्क। +**चेन-ऑफ-थट** - राम्रो सटीकताको लागि चरण-दर-चरण तर्क। -**Constrained Output** - विशेष ढाँचा वा संरचना लागू गर्ने। +**सीमित आउटपुट** - विशेष फारम्याट वा संरचना अनिवार्य पार्ने। -**High Eagerness** - GPT-5.2 को गहिरो तर्कको ढाँचा। +**उच्च उत्साह** - GPT-5.2 को गहिरो तर्क गर्ने ढाँचा। -**Low Eagerness** - GPT-5.2 को छिटो उत्तरको ढाँचा। +**कम उत्साह** - GPT-5.2 को तुरुन्त उत्तर दिने ढाँचा। -**Multi-Turn Conversation** - आदानप्रदानहरूमा सन्दर्भ कायम राख्ने। +**बहु-पटक संवाद** - आदान प्रदानमा सन्दर्भ कायम राख्ने। -**Role-Based Prompting** - प्रणाली सन्देशहरू मार्फत मोडेलको व्यक्तित्व सेट गर्ने। +**भूमिका-आधारित प्रॉम्प्टिङ** - प्रणाली सन्देशहरूद्वारा मोडेलको व्यक्तित्व सेट गर्ने। -**Self-Reflection** - मोडेलले आफ्नो आउटपुट मूल्याङ्कन र सुधार गर्ने। +**आत्म-प्रतिक्रिया** - मोडेलले आफ्नो आउटपुट मूल्यांकन गरी सुधार गर्ने। -**Structured Analysis** - निश्चित मूल्याङ्कन फ्रेमवर्क। +**संरचित विश्लेषण** - निश्चित मूल्यांकन फ्रेमवर्क। -**Task Execution Pattern** - योजना → कार्यान्वयन → सारांश। +**कार्य कार्यान्वयन ढाँचा** - योजना → कार्यान्वयन → सारांश। -## RAG (पुन:प्राप्ति-सहायता उत्पादन) - [मोड्युल ०३](../03-rag/README.md) +## RAG (प्राप्ति-सशक्त पीढी) - [मोड्युल 03](../03-rag/README.md) -**Document Processing Pipeline** - लोड → टुक्रा → एम्बेड → भण्डारण। +**दस्तावेज प्रसोधन पाइपलाइन** - लोड → चंक → एम्बेड → स्टोर। -**In-Memory Embedding Store** - परीक्षणका लागि गैर-स्थायी भण्डारण। +**इन-मेमोरी एम्बेडिङ स्टोर** - परीक्षणका लागि अस्थायी भण्डारण। -**RAG** - प्रतिक्रियाहरूलाई आधार दिने पुन:प्राप्ति र उत्पादनलाई संयोजन गर्दछ। +**RAG** - प्रतिक्रियालाई आधार दिने गरी प्राप्ति र पीढी संयोजन। -**Similarity Score** - सिमेन्टिक समानताको मापन (०-१)। +**समानता स्कोर** - सेम्यान्टिक समानताको मापन (०-१)। -**Source Reference** - पुन:प्राप्त सामग्रीको मेटाडेटा। +**स्रोत सन्दर्भ** - प्राप्त सामग्रीको मेटाडाटा। -## एजेण्टहरू र उपकरणहरू - [मोड्युल ०४](../04-tools/README.md) +## एजेन्टहरू र उपकरणहरू - [मोड्युल 04](../04-tools/README.md) -**@Tool Annotation** - Java विधिहरूलाई AI-कॉलयोग्य उपकरणहरूका रूपमा चिन्ह लगाउने। +**@Tool एनोटेसन** - Java विधिहरूलाई AI-कॉल गर्न मिल्ने उपकरणहरू रूपमा चिन्हित गर्छ। -**ReAct Pattern** - तर्क → कार्य → अवलोकन → दोहोर्याउने। +**ReAct ढाँचा** - तर्क → कार्य → अनुगमन → दोहोर्याउने। -**Session Management** - फरक प्रयोगकर्ताहरूका लागि अलग सन्दर्भहरू। +**सेसन व्यवस्थापन** - फरक प्रयोगकर्ताहरूका लागि अलग सन्दर्भहरू। -**Tool** - AI एजेण्टले कल गर्न सक्ने कार्य। +**उपकरण** - AI एजेन्टले कल गर्न सक्ने फंक्शन। -**Tool Description** - उपकरणको उद्देश्य र प्यारामिटरहरूको दस्तावेज। +**उपकरण वर्णन** - उपकरणको उद्देश्य र प्यारामिटरहरूको दस्तावेजीकरण। -## एजेण्टिक मोड्युल - [मोड्युल ०५](../05-mcp/README.md) +## एजेन्टिक मोड्युल - [मोड्युल 05](../05-mcp/README.md) -**@Agent Annotation** - इन्टरफेसहरूलाई AI एजेण्टको रूपमा चिन्ह लगाउने जसमा व्यवहार घोषणात्मक रूपमा परिभाषित हुन्छ। +**@Agent एनोटेसन** - डिक्लेरेटिभ व्यवहार परिभाषा सहित AI एजेन्टहरूका इन्टरफेसहरू चिन्हित गर्छ। -**Agent Listener** - `beforeAgentInvocation()` र `afterAgentInvocation()` मार्फत एजेण्ट कार्यान्वयनको अनुगमनका लागि हुक। +**एजेन्ट लिस्नर** - `beforeAgentInvocation()` र `afterAgentInvocation()` मार्फत एजेन्ट कार्यान्वयनको निगरानी गर्ने हुक। -**Agentic Scope** - साझा मेमोरी जहाँ एजेण्टहरूले `outputKey` प्रयोग गरी आउटपुटहरू भण्डारण गर्छन् र त्यसलाई अन्य एजेण्टहरूले प्रयोग गर्छन्। +**एजेन्टिक स्कोप** - साझा स्मृति जहाँ एजेन्टहरूले आउटपुटहरू `outputKey` प्रयोग गरी संग्रह गर्छन्, अन्य एजेन्टहरूका लागि उपभोगयोग्य। -**AgenticServices** - `agentBuilder()` र `supervisorBuilder()` प्रयोग गरी एजेण्टहरू सिर्जना गर्नको लागि कारखाना। +**AgenticServices** - `agentBuilder()` र `supervisorBuilder()` प्रयोग गरी एजेन्टहरू सिर्जना गर्ने फैक्ट्री। -**Conditional Workflow** - सर्तहरूमा आधारित फरक विशेषज्ञ एजेण्टहरूमा मार्ग निर्धारण। +**सशर्त कार्यप्रवाह** - अवस्थाहरूमा आधारित फरक विशेषज्ञ एजेन्टहरूमा रुटिङ। -**Human-in-the-Loop** - स्वीकृति वा सामग्री समीक्षा लागि मानव चेकपोइन्टहरू थप्ने कार्यप्रवाह ढाँचा। +**मानव-इन-द-लूप** - स्वीकृति वा सामग्री समीक्षणका लागि मानव checkpoints थप्ने कार्यप्रवाह ढाँचा। -**langchain4j-agentic** - घोषणात्मक एजेण्ट निर्माणको लागि Maven निर्भरता (प्रयोगात्मक)। +**langchain4j-agentic** - डिक्लेरेटिभ एजेन्ट निर्माणका लागि Maven निर्भरता (प्रयोगात्मक)। -**Loop Workflow** - कुनै सर्त पूरा नभएसम्म (जस्तै गुणस्तर स्कोर ≥ 0.8) एजेण्ट कार्यान्वयन दोहोर्याउने। +**लूप कार्यप्रवाह** - एउटा अवस्था पूरा नभएसम्म एजेन्ट कार्यान्वयन दोहोर्याउने (जस्तै गुणस्तर स्कोर ≥ ०.८)। -**outputKey** - Agentic Scope मा परिणामहरू कहाँ भण्डारण गर्ने भन्ने एजेण्ट टिप्पणी प्यारामिटर। +**outputKey** - एजेन्ट एनोटेसन प्यारामिटर जसले परिणामहरू एजेन्टिक स्कोपमा कहाँ संग्रह गर्ने जनाउँछ। -**Parallel Workflow** - स्वतन्त्र कार्यहरूको लागि एकै समयमा धेरै एजेण्टहरू चलाउने। +**पारालल कार्यप्रवाह** - स्वतन्त्र कार्यहरूका लागि एकैचोटि धेरै एजेन्टहरू चलाउने। -**Response Strategy** - सुपरभाइजरले अन्तिम उत्तर निर्माण गर्ने तरिका: LAST, SUMMARY, वा SCORED। +**प्रतिक्रिया रणनीति** - सुपरवाइजरले अन्तिम जवाफ कसरी तयार पार्छ: LAST, SUMMARY, वा SCORED। -**Sequential Workflow** - एजेण्टहरूलाई क्रमबद्ध रूपमा चलाउने जहाँ आउटपुट अर्को चरणमा जान्छ। +**क्रमागत कार्यप्रवाह** - एजेन्टहरूलाई आदेशमा कार्यान्वयन गर्ने जहाँ आउटपुट अर्को चरणमा जान्छ। -**Supervisor Agent Pattern** - एक परिष्कृत एजेण्टिक ढाँचा जहाँ एक सुपरभाइजर LLM गतिशील रूपमा कुन उप-एजेण्टहरू कल गर्ने निर्णय गर्छ। +**सुपरवाइजर एजेन्ट ढाँचा** - उन्नत एजेन्टिक ढाँचा जहाँ सुपरवाइजर LLMले कुन उप-एजेन्टहरू कल गर्ने गतिशील निर्णय गर्दछ। -## मोडेल सन्दर्भ प्रोटोकल (MCP) - [मोड्युल ०५](../05-mcp/README.md) +## मोडेल सन्दर्भ प्रोटोकल (MCP) - [मोड्युल 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j मा MCP एकीकरणको लागि Maven निर्भरता। +**langchain4j-mcp** - LangChain4j मा MCP एकीकरणका लागि Maven निर्भरता। -**MCP** - मोडेल सन्दर्भ प्रोटोकल: AI अनुप्रयोगहरूलाई बाह्य उपकरणहरूसँग जडान गर्ने मानक। एक पटक बनाउनुहोस्, हरेक ठाउँमा प्रयोग गर्नुहोस्। +**MCP** - मोडेल सन्दर्भ प्रोटोकल: AI एपहरू बाह्य उपकरणहरूसँग जडान गर्ने मापदण्ड। एक पटक निर्माण, सबै ठाउँमा प्रयोग। -**MCP Client** - MCP सर्भरहरूमा जडान गरी उपकरणहरू पत्ता लगाउने र प्रयोग गर्ने अनुप्रयोग। +**MCP क्लाइन्ट** - MCP सर्भरहरूमा जडान गरी उपकरणहरू पत्ता लगाउने र प्रयोग गर्ने आवेदन। -**MCP Server** - उपकरणहरूलाई स्पष्ट विवरणहरू र प्यारामिटर स्कीमा सहित MCP मार्फत एक्सपोज गर्ने सेवा। +**MCP सर्भर** - उपकरणहरू स्पष्ट वर्णन र प्यारामिटर स्किमासँग MCP मार्फत प्रस्तुत गर्ने सेवा। -**McpToolProvider** - LangChain4j कम्पोनेन्ट जसले MCP उपकरणहरूलाई AI सेवा र एजेण्टहरूमा प्रयोगका लागि र्याप गर्छ। +**McpToolProvider** - LangChain4j कम्पोनेन्ट जसले MCP उपकरणहरूलाई AI सेवा र एजेन्टहरूमा प्रयोग गर्न रैप गर्छ। -**McpTransport** - MCP संवादका लागि इन्टरफेस। कार्यान्वयनहरूमा Stdio र HTTP समावेश छन्। +**McpTransport** - MCP सञ्चारको लागि इन्टरफेस। कार्यान्वयनहरूमा Stdio र HTTP समावेश। -**Stdio Transport** - stdin/stdout मार्फत स्थानीय प्रक्रिया ट्रान्सपोर्ट। फाइल सिस्टम पहुँच वा आदेश-लाइन उपकरणहरूको लागि उपयोगी। +**Stdio ट्रान्सपोर्ट** - stdin/stdout मार्फत स्थानीय प्रक्रिया ट्रान्सपोर्ट। फाइलसिस्टम पहुँच वा कमाण्ड-लाइन उपकरणहरूका लागि उपयोगी। -**StdioMcpTransport** - LangChain4j कार्यान्वयन जसले MCP सर्भरलाई एक उप-प्रक्रियाको रूपमा सुरु गर्दछ। +**StdioMcpTransport** - LangChain4j कार्यान्वयन जसले MCP सर्भरलाई subprocess को रूपमा स्पाउन गर्छ। -**Tool Discovery** - क्लाइन्टले उपलब्ध उपकरणहरूको लागि विवरणहरू र स्कीमासहित सर्भरलाई सोधपुछ गर्छ। +**उपकरण पत्ता लगाउने** - क्लाइन्टले सर्भरलाई उपलब्ध उपकरणहरूको वर्णन र स्किमासहित सोध्छ। -## एजुर सेवाहरू - [मोड्युल ०१](../01-introduction/README.md) +## एज्योर सेवा - [मोड्युल 01](../01-introduction/README.md) -**Azure AI Search** - भेक्टर क्षमताहरू सहित क्लाउड खोज। [मोड्युल ०३](../03-rag/README.md) +**Azure AI Search** - भेक्टर क्षमताहरू सहितको क्लाउड खोज। [मोड्युल 03](../03-rag/README.md) **Azure Developer CLI (azd)** - Azure स्रोतहरू तैनाथ गर्छ। **Azure OpenAI** - Microsoft को एंटरप्राइज AI सेवा। -**Bicep** - Azure पूर्वाधार-कोड भाषाशैली। [पूर्वाधार गाइड](../01-introduction/infra/README.md) +**Bicep** - Azure इन्फ्रास्ट्रक्चर-एज-कोड भाषा। [Infrastructure Guide](../01-introduction/infra/README.md) -**Deployment Name** - Azure मा मोडेल तैनाथीकरणको नाम। +**तैनाथी नाम** - Azure मा मोडेल तैनाथीको नाम। -**GPT-5.2** - reasoning नियन्त्रणसहितको नयाँ OpenAI मोडेल। [मोड्युल ०२](../02-prompt-engineering/README.md) +**GPT-5.2** - reasoning नियन्त्रण सहितको नवीनतम OpenAI मोडेल। [मोड्युल 02](../02-prompt-engineering/README.md) -## परीक्षण र विकास - [परीक्षण मार्गदर्शिका](TESTING.md) +## परीक्षण र विकास - [परीक्षण गाइड](TESTING.md) -**Dev Container** - कन्टेनराइज्ड विकास वातावरण। [कन्फिगरेसन](../../../.devcontainer/devcontainer.json) +**Dev Container** - कन्टेनराइज्ड विकास वातावरण। [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - निःशुल्क AI मोडेल खेल्ने ठाउँ। [मोड्युल ००](../00-quick-start/README.md) +**इन-मेमोरी परीक्षण** - इन-मेमोरी भण्डारणसँग परीक्षण। -**In-Memory Testing** - इन-मेमोरी भण्डारणसहित परीक्षण। +**इन्टिग्रेशन परीक्षण** - वास्तविक पूर्वाधारसँग परीक्षण। -**Integration Testing** - वास्तविक पूर्वाधारसहित परीक्षण। - -**Maven** - Java बिल्ड अटोमेसन उपकरण। +**Maven** - Java निर्माण स्वचालन उपकरण। **Mockito** - Java मोकिङ फ्रेमवर्क। -**Spring Boot** - Java एप्लिकेसन फ्रेमवर्क। [मोड्युल ०१](../01-introduction/README.md) +**Spring Boot** - Java अनुप्रयोग फ्रेमवर्क। [मोड्युल 01](../01-introduction/README.md) --- **अस्वीकरण**: -यो दस्तावेज AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी सटीकताको प्रयास गर्छौं भने पनि, कृपया ध्यान दिनुहोस् कि स्वचालित अनुवादमा त्रुटि वा अशुद्धता हुन सक्छ। मौलिक दस्तावेज यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलतफहमी वा गलत व्याख्याको लागि हामी जिम्मेवार छैनौं। +यो दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी सही हुन प्रयास गर्छौं, तर कृपया जानकार हुनुस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छन्। मूल दस्तावेज़ यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलत बुझाइ वा त्रुटिको लागि हामी जिम्मेवार छैनौं। \ No newline at end of file diff --git a/translations/ne/docs/TESTING.md b/translations/ne/docs/TESTING.md index 60cf8bd39..0c43aa5d9 100644 --- a/translations/ne/docs/TESTING.md +++ b/translations/ne/docs/TESTING.md @@ -1,16 +1,16 @@ -# LangChain4j अनुप्रयोगहरू परीक्षण +# LangChain4j अनुप्रयोगहरू परीक्षण गर्दै ## सामग्री तालिका -- [छिटो सुरु](../../../docs) -- [परीक्षणहरूले के समेट्छन्](../../../docs) -- [परीक्षणहरू चलाउने](../../../docs) -- [VS कोडमा परीक्षणहरू चलाउने](../../../docs) -- [परीक्षण ढाँचा](../../../docs) -- [परीक्षण दर्शनशास्त्र](../../../docs) -- [अगाडि के गर्ने](../../../docs) +- [छिटो सुरु](#छिटो-सुरु) +- [परीक्षणहरूले कभर गर्ने कुरा](#परीक्षणहरूले-कभर-गर्ने-कुरा) +- [परीक्षणहरू चलाउँदै](#परीक्षणहरू-चलाउँदै) +- [VS कोडमा परीक्षणहरू चलाउँदै](#vs-कोडमा-परीक्षणहरू-चलाउँदै) +- [परीक्षण ढाँचाहरू](#परीक्षण-ढाँचाहरू) +- [परीक्षण दर्शन](#परीक्षण-दर्शन) +- [अर्को चरणहरू](#अर्को-चरणहरू) -यो मार्गनिर्देशनले तपाईंलाई ती परीक्षणहरू मार्फत लैजान्छ जसले देखाउँछन् कसरी API कुञ्जीहरू वा बाह्य सेवाहरू बिना AI अनुप्रयोगहरू परीक्षण गर्ने। +यो मार्गदर्शनले तपाईंलाई API कुञ्जी वा बाह्य सेवाहरू आवश्यक नपर्ने तरिकाले AI अनुप्रयोगहरू कसरी परीक्षण गर्ने भनेर देखाउने परीक्षणहरू मार्फत लैजान्छ। ## छिटो सुरु @@ -26,30 +26,29 @@ mvn test mvn --% test ``` -सबै परीक्षणहरू पास भएपछि, तलको स्क्रिनशट जस्तो आउटपुट देख्नुपर्नेछ — परीक्षणहरू बिना कुनै फेलियर चल्दछन्। +जब सबै परीक्षणहरू पास हुन्छन्, तपाईंले तलको स्क्रिनशट जस्तो आउटपुट देख्नुपर्छ — परीक्षणहरू शून्य असफलतासँग चल्नेछन्। Successful Test Results -*सफल परीक्षण कार्यान्वयन देखाउँदै सबै परीक्षणहरू शून्य असफलतासँग पास भएका छन्* +*शून्य असफलता सहित सबै परीक्षणहरू पास भएको सफल परीक्षण निष्पादन देखाउँदै* -## परीक्षणहरूले के समेट्छन् +## परीक्षणहरूले कभर गर्ने कुरा -यो कोर्षले **स्थानिय रूपमा चल्ने एकाई परीक्षणहरू** मा ध्यान केन्द्रित गर्दछ। प्रत्येक परीक्षणले एक विशिष्ट LangChain4j अवधारणा अलग्गै देखाउँछ। परीक्षण पिरामिडले देखाउँछ कहाँ एकाई परीक्षणहरू फिट हुन्छन् — ती छिटो, भरपर्दो आधार बनाउँछन् जुन तपाईको परीक्षण रणनीतिमा बाँकी सबैले निर्माण गर्छ। +यो कोर्सले स्थानीय चल्ने **युनिट परीक्षणहरू** मा केन्द्रित छ। प्रत्येक परीक्षणले एक विशिष्ट LangChain4j अवधारणालाई अलग्गै देखाउँछ। तलको परीक्षण पिरामिडले देखाउँछ युनिट परीक्षणहरूले कहाँ फिट हुन्छन् — यी छिटो, भरपर्दो आधार हुन् जसको आधारमा तपाईंको परीक्षण रणनीतिले निर्माण गर्छ। Testing Pyramid -*परीक्षण पिरामिड जसले एकाई परीक्षणहरू (छिटो, अलग्गै), एकीकरण परीक्षणहरू (वास्तविक कम्पोनेन्टहरू), र अन्त्य-देखि-अन्त्य परीक्षणहरू बीचको सन्तुलन देखाउँछ। यो तालिमले एकाई परीक्षणलाई समेट्छ।* +*परीक्षण पिरामिडले युनिट परीक्षणहरू (छिटो, अलग), एकीकरण परीक्षणहरू (सचोटा कम्पोनेन्टहरू), र अन्त-देखि-अन्त परीक्षणहरू बीचको सन्तुलन देखाउछ। यो तालिम युनिट परीक्षण कभर गर्छ।* -| मोड्युल | परीक्षणहरू | केन्द्रित विषय | मुख्य फाइलहरू | +| मोड्युल | परीक्षणहरू | केन्द्रित क्षेत्र | प्रमुख फाईलहरू | |--------|-------|-------|-----------| -| **00 - छिटो सुरु** | 6 | प्रॉम्प्ट टेम्प्लेट र भेरिएबल प्रतिस्थापन | `SimpleQuickStartTest.java` | -| **01 - परिचय** | 8 | संवाद मेमोरी र अवस्थात्मक च्याट | `SimpleConversationTest.java` | -| **02 - प्रॉम्प्ट इन्जिनियरिङ** | 12 | GPT-5.2 ढाँचाहरू, तत्परता स्तरहरू, संरचित आउटपुट | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | कागजात समावेशन, एम्बेडिङ, समानता खोज | `DocumentServiceTest.java` | -| **04 - उपकरणहरू** | 12 | फङ्क्शन कलिङ र उपकरण श्रृंखला | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | मोडेल कन्टेक्स्ट प्रोटोकल stdio ट्रान्सपोर्टसहित | `SimpleMcpTest.java` | +| **01 - परिचय** | 8 | संवाद मेमोरी र अवस्थावान च्याट | `SimpleConversationTest.java` | +| **02 - प्रम्प्ट इन्जिनियरिङ** | 12 | GPT-5.2 ढाँचाहरू, उत्साह स्तरहरू, संरचित आउटपुट | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | दस्तावेज़ इन्टेक, एम्बेडिङ, समानता खोज | `DocumentServiceTest.java` | +| **04 - उपकरणहरू** | 12 | फङ्क्शन कलिंग र उपकरण श्रृंखला | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | मोडेल कन्टेक्स्ट प्रोटोकल स्टडियो ट्रान्सपोर्टसँग | `SimpleMcpTest.java` | -## परीक्षणहरू चलाउने +## परीक्षणहरू चलाउँदै **रुटबाट सबै परीक्षणहरू चलाउनुहोस्:** @@ -63,12 +62,12 @@ mvn test mvn --% test ``` -**विशिष्ट मोड्युलका लागि परीक्षणहरू चलाउने:** +**विशिष्ट मोड्युलको परीक्षणहरू चलाउनुहोस्:** **Bash:** ```bash cd 01-introduction && mvn test -# वा रुटबाट +# वा मूलबाट mvn test -pl 01-introduction ``` @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**एकल परीक्षण क्लास चलाउने:** +**एकल परीक्षण क्लास चलाउनुहोस्:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**विशिष्ट परीक्षण मेथड चलाउने:** +**विशिष्ट परीक्षण विधि चलाउनुहोस्:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#कुराकानी इतिहास राख्नुपर्छ +mvn test -Dtest=SimpleConversationTest#संवाद इतिहास कायम राख्नुपर्छ ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#कुराकानी इतिहास राख्नुपर्छ +mvn --% test -Dtest=SimpleConversationTest#कुराकानीको इतिहास कायम राख्नुपर्छ ``` -## VS कोडमा परीक्षणहरू चलाउने +## VS कोडमा परीक्षणहरू चलाउँदै -यदि तपाईं Visual Studio Code प्रयोग गर्दै हुनुहुन्छ भने, टेस्ट एक्सप्लोररले परीक्षणहरू चलाउन र डीबग गर्न ग्राफिकल इन्टरफेस प्रदान गर्छ। +Visual Studio Code प्रयोग गरीरहनुभएको भए, Test Explorer ले परीक्षणहरू चलाउन र डिबग गर्न ग्राफिकल इन्टरफेस प्रदान गर्छ। VS Code Test Explorer -*VS कोड टेस्ट एक्सप्लोररले सबै Java परीक्षण क्लासहरू र व्यक्तिगत परीक्षण मेथडहरूको परीक्षण रूख देखाउँछ* +*VS Code Test Explorer ले सबै Java परीक्षण क्लासहरू र व्यक्तिगत परीक्षण विधिहरू सहित परीक्षण रूख देखाउँदै* -**VS कोडमा परीक्षणहरू चलाउन:** +**VS Code मा परीक्षणहरू चलाउन:** -1. एक्टिभिटी बारमा बीकर आइकनमा क्लिक गरेर टेस्ट एक्सप्लोरर खोल्नुहोस् -2. सबै मोड्युलहरू र परीक्षण क्लासहरू हेर्न रूख विस्तार गर्नुहोस् -3. व्यक्तिगत परीक्षण चलाउन कुनै पनि परीक्षणको छेउमा प्ले बटन क्लिक गर्नुहोस् -4. पूरै सेटप चलाउन "Run All Tests" मा क्लिक गर्नुहोस् -5. कुनै पनि परीक्षणमा राइट-क्लिक गरेर "Debug Test" छान्नुहोस् ब्रेकपोइन्ट सेट गर्न र कोडमा स्टेप गर्न +1. Activity Bar मा रहेको बेकเกอร์ आइकनमा क्लिक गरी Test Explorer खोल्नुहोस् +2. सबै मोड्युलहरू र परीक्षण क्लासहरू हेर्न परीक्षण रूख विस्तार गर्नुहोस् +3. कुनै पनि परीक्षणको छेउमा प्ले बटनमा क्लिक गरी व्यक्तिगत रूपमा चलाउनुहोस् +4. "Run All Tests" क्लिक गरी पूर्ण सूट execute गर्नुहोस् +5. कुनै पनि परीक्षणमा राइट-क्लिक गरी "Debug Test" छान्नुहोस् जसले ब्रेकप्वाइन्ट सेट गरी कोड हिँड्न दिन्छ -टेस्ट एक्सप्लोररले पास भएका परीक्षणहरूका लागि हरियो टिक देखाउँछ र फेल हुनेबित्तिकै विस्तृत त्रुटि सन्देश प्रदान गर्छ। +Test Explorer ले पास भएका परीक्षणहरूको लागि हरियो चेकमार्क देखाउँछ र असफल भएका परीक्षणहरूको लागि विस्तारपूर्वक त्रुटि सन्देश प्रदान गर्छ। -## परीक्षण ढाँचा +## परीक्षण ढाँचाहरू -### ढाँचा 1: प्रॉम्प्ट टेम्प्लेट परीक्षण +### ढाँचा १: प्रम्प्ट टेम्प्लेट परीक्षण -सरलतम ढाँचाले AI मोडेल कल नगरी प्रॉम्प्ट टेम्प्लेटहरू परीक्षण गर्छ। तपाईंले भेरिएबल प्रतिस्थापन सहि भईरहेको छ कि छैन र प्रॉम्प्टहरू अपेक्षाकृत ढाँचामा छन् कि छैनन् भनी जाँच गर्नुहुन्छ। +सर्वाधिक सरल ढाँचाले कुनै AI मोडेल कल नगरी प्रम्प्ट टेम्प्लेटहरू परीक्षण गर्छ। तपाईं परिवर्तनशील प्रतिस्थापन सही छ कि छैन र प्रम्प्टहरू अपेक्षाअनुसार स्वरूपित छन् कि छैनन् भनेर प्रमाणित गर्नुहुन्छ। Prompt Template Testing -*प्रॉम्प्ट टेम्प्लेट परीक्षण देखाउँदै भेरिएबल प्रतिस्थापन प्रवाह: प्लेसहोल्डर भएको टेम्प्लेट → मानहरू लागू गरिएका → स्वरूपित आउटपुट पुष्टि गरियो* +*प्रम्प्ट टेम्प्लेट परीक्षणले परिवर्तनशील प्रतिस्थापन प्रवाह देखाउँछ: प्लेसहोल्डर भएको टेम्प्लेट → मानहरू लागू → स्वरूपित आउटपुट प्रमाणित* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -यो परीक्षण `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` मा छ। - -**चलाउन:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#परीक्षणप्रॉम्प्टढाँचासज्जा -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#परीक्षणप्रॉम्प्टटेम्प्लेटफर्म्याटिङ -``` +यस ढाँचाले परिवर्तनशील प्रतिस्थापन सही छ कि छैन र प्रम्प्टहरू अपेक्षाअनुसार स्वरूपित छन् कि छैनन् भनेर पुष्टि गर्छ — कुनै API कुञ्जी वा मोडेल कल आवश्यक छैन। -### ढाँचा 2: भाषा मोडेलहरूको मॉकिङ +### ढाँचा २: भाषा मोडेलहरूको मोकिंग -संवाद तर्क परीक्षण गर्दा, Mockito प्रयोग गरेर अघोषित प्रतिक्रिया दिने गलत मोडेलहरू सिर्जना गर्नुहोस्। यसले परीक्षणहरूलाई छिटो, निःशुल्क र निर्धारणयोग्य बनाउँछ। +संवाद तार्किकताको परीक्षण गर्दा Mockito प्रयोग गरी नकली मोडेलहरू बनाइन्छ जुन पूर्वनिर्धारित जवाफहरू फर्काउँछन्। यसले परीक्षणहरू छिटो, निःशुल्क, र निर्णयात्मक बनाउँछ। Mock vs Real API Comparison -*परीक्षणका लागि मॉकहरू किन मनपर्छन् भन्ने तुलना: ती छिटो, निःशुल्क, निर्धारणयोग्य, र API कुञ्जीहरू आवश्यक पर्दैनन्* +*परीक्षणका लागि मोकहरू किन प्राथमिकता दिइन्छ भन्ने तुलना: ती छिटो, निःशुल्क, निर्णयात्मक र API कुञ्जीहरू आवश्यक गर्दैनन्* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 प्रयोगकर्ता + 3 AI सन्देशहरू + assertThat(history).hasSize(6); // ३ प्रयोगकर्ता + ३ एआई सन्देशहरू } } ``` -यो ढाँचाले `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` मा देखिन्छ। मॉकले निश्चित व्यवहार सुनिश्चित गर्छ ताकि मेमोरी व्यवस्थापन सहि छ कि होइन जाँच्न सकियोस्। +यो ढाँचा `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` मा देख्न सकिन्छ। मोकले निरन्तर व्यवहार सुनिश्चित गर्छ ताकि तपाईं मेमोरी व्यवस्थापन सही छ कि छैन भनेर प्रमाणित गर्न सक्नुहुन्छ। -### ढाँचा 3: संवाद अलगाव परीक्षण +### ढाँचा ३: संवाद अलगाव परीक्षण -संवाद मेमोरीले धेरै प्रयोगकर्ता अलग्गै राख्नुपर्छ। यो परीक्षणले संवादहरूले सन्दर्भ नमिलाउने सुनिश्चित गर्छ। +संवाद मेमोरीले धेरै प्रयोगकर्ताहरूलाई अलग्गै राख्नुपर्छ। यो परीक्षणले प्रमाणित गर्छ कि संवादहरू सन्दर्भ मिक्स गर्दैनन्। Conversation Isolation -*संवाद अलगाव परीक्षण देखाउँदै फरक प्रयोगकर्ताहरूका लागि अलग मेमोरी स्टोरहरूले सन्दर्भ नमिल्ने गर्छ* +*संवाद अलगाव परीक्षणले फरक-फरक प्रयोगकर्ताहरूको लागि अलग्गै मेमोरी स्टोर देखाउँछ जसले सन्दर्भ मिक्सिंग रोक्छ* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -प्रत्येक संवादले आफ्नै स्वतन्त्र इतिहास राख्दछ। उत्पादन प्रणालीहरूमा, यो अलगाव बहु-प्रयोगकर्ता अनुप्रयोगहरूमा अतिप्रधान हुन्छ। +प्रत्येक संवादले आफ्नै स्वतन्त्र इतिहास राख्छ। उत्पादन प्रणालीहरूमा, यो अलगाव बहुपयोगकर्ता अनुप्रयोगहरूका लागि अत्यावश्यक हुन्छ। -### ढाँचा 4: उपकरणहरू स्वतन्त्र रूपमा परीक्षण +### ढाँचा ४: उपकरणहरू स्वतन्त्र रूपमा परीक्षण गर्दै -उपकरणहरू फङ्क्सनहरू हुन् जुन AI ले कल गर्न सक्छ। AI निर्णय बिना नै उनीहरूलाई सिधा परीक्षण गरेर निश्चित गर्नुहोस् कि काम गरिरहेका छन्। +उपकरणहरू त्यस्ता फङ्क्शनहरू हुन् जसलाई AI ले कल गर्न सक्छ। उनीहरूलाई सोझै परीक्षण गर्नुहोस् ताकि ती AI निर्णयसँग कुनै सम्बन्ध नभए पनि सहीसँग काम गर्छन् भनेर निश्चित होस्। Tools Testing -*उपकरणहरू स्वतन्त्र रुपमा परीक्षण गर्दै मॉक उपकरण निष्पादन देखाउँदै ब्यापार तर्क पुष्टि गर्न, AI कल बिना* +*उपकरणहरू स्वतन्त्र रूपमा परीक्षण गर्दै मोक उपकरण कार्यान्वयन बिना AI कलहरू देखाउँदै व्यावसायिक तर्क प्रमाणित* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -यी परीक्षणहरू `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` बाट छन् जसले उपकरण तर्क AI संलग्नता बिना प्रमाणित गर्छ। चेनिङ उदाहरणले देखाउँछ कसरी एउटा उपकरणको आउटपुट अर्कोको इनपुटमा जान्छ। +यी परीक्षणहरू `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` बाट हुन् जसले AI सम्मिलित नभई उपकरण तर्क प्रमाणीकरण गर्छ। श्रृंखला उदाहरणले कसरी एउटा उपकरणको आउटपुट अर्कोको इनपुटमा जान्छ देखाउँछ। -### ढाँचा 5: मेमोरी भित्रको RAG परीक्षण +### ढाँचा ५: इन-मेमोरी RAG परीक्षण -RAG प्रणालीहरूले सामान्यतया भेक्टर डाटाबेस र एम्बेडिङ सेवाहरूको आवश्यकता पर्दछ। इन-मेमोरी ढाँचाले सम्पूर्ण पाइपलाइन बाह्य आश्रय बिना परीक्षण गर्न दिन्छ। +RAG प्रणालीहरूले सामान्यतया भेक्टर डाटाबेस र एम्बेडिङ सेवाहरू चाहिन्छ। इन-मेमोरी ढाँचाले तपाईंलाई बाह्य निर्भरता बिना पुरै पाइपलाइन परीक्षण गर्न अनुमति दिन्छ। In-Memory RAG Testing -*इन-मेमोरी RAG परीक्षण कार्यप्रवाह देखाउँदै कागजात पार्सिङ, एम्बेडिङ स्टोरेज, र समानता खोज बिना डेटाबेस आवश्यकताको* +*इन-मेमोरी RAG परीक्षण कार्यप्रवाहले दस्तावेज पार्सिङ, एम्बेडिङ भण्डारण, र समानता खोज देखाउँछ जुन डाटाबेस आवश्यक पर्दैन* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -यो परीक्षण `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` बाट हो जसले कागजात मेमोरीमा बनाउँछ र चंकिङ र मेटाडाटा ह्यान्डलिङ पुष्टि गर्छ। +यो परीक्षण `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` बाट छ जसले स्मृतिमा दस्तावेज बनाउँछ र चंकिङ तथा मेटाडाटा ह्यान्डलिङ प्रमाणित गर्छ। -### ढाँचा 6: MCP एकीकरण परीक्षण +### ढाँचा ६: MCP एकीकरण परीक्षण -MCP मोड्युलले stdio ट्रान्सपोर्ट प्रयोग गरी मोडेल कन्टेक्स्ट प्रोटोकलको एकीकरण परीक्षण गर्छ। यी परीक्षणहरूले पुष्टि गर्छन् तपाईंको अनुप्रयोग MCP सर्भरहरूलाई subprocess रूपमा उत्पन्न गरी संवाद गर्न सक्षम छ। +MCP मोड्युलले स्टडियो ट्रान्सपोर्ट प्रयोग गरेर मोडेल कन्टेक्स्ट प्रोटोकल एकीकरण परीक्षण गर्छ। यी परीक्षणहरूले तपाईंको अनुप्रयोगले MCP सर्भरहरूलाई सबप्रोसेसको रूपमा सुरु र सञ्‍चार गर्न सक्ने सुनिश्चित गर्छ। -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` मा परीक्षणहरूले MCP क्लाइन्ट व्यवहार प्रमाणित गर्छ। +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` मा रहेका परीक्षणहरूले MCP क्लाइन्ट व्यवहार प्रमाणीकरण गर्छन्। -**चलाउन:** +**चलाउनुहोस्:** **Bash:** ```bash @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## परीक्षण दर्शनशास्त्र +## परीक्षण दर्शन -तपाईंको कोड परीक्षण गर्नुहोस्, AI होइन। तपाईंका परीक्षणहरूले तपाईंले लेखेको कोडलाई प्रमाणीकरण गर्नुपर्छ, जस्तै कसरी प्रॉम्प्टहरू बनाउनुभयो, कसरी मेमोरी व्यवस्थापन भयो, र कसरी उपकरणहरूले काम गरे। AI प्रतिक्रियाहरू फरक फरक हुन्छन् र परीक्षण दावीहरूको भाग हुनु हुँदैन। आफैंलाई सोध्नुहोस् कि तपाईंको प्रॉम्प्ट टेम्प्लेटले सहि रूपमा भेरिएबलहरू प्रतिस्थापन गर्यो कि गरेन, AI ले सही जवाफ दियो कि दिएन होइन। +तपाईंको कोडलाई परीक्षण गर्नुहोस्, AI लाई होइन। तपाईंको परीक्षणहरूले तपाईं लेखेको कोडलाई प्रमाणित गर्नुपर्छ — कसरि प्रम्प्टहरू बनाइन्छ, मेमोरी कसरी व्यवस्थापन हुन्छ, र उपकरणहरू कसरी कार्यान्वित हुन्छन् जाँच गरेर। AI प्रतिक्रियाहरू फरक-फरक हुन्छन् र परीक्षण दावीहरूको भाग हुनुहुँदैन। आफ्नो प्रम्प्ट टेम्प्लेटले सही तरिकाले परिवर्तनशीलहरू प्रतिस्थापन गर्छ कि गर्दैन सोध्नुहोस्, AI ले सहि उत्तर दिन्छ कि दिमाग गढ्नु होइन। -भाषा मोडेलहरूका लागि मॉकहरू प्रयोग गर्नुहोस्। तिनीहरू बाह्य आश्रय हुन् जुन सुस्त, महँगो, र निर्धारण नभएका हुन्छन्। मॉकिङले परीक्षणहरूलाई सेकन्डको सट्टा मिलिसेकेन्डमा छिटो, निःशुल्क API लागत बिना, र हरेक पटक एउटै नतिजामा निर्धारणयोग्य बनाउँछ। +भाषा मोडेलहरूको लागि मोकहरू प्रयोग गर्नुहोस्। ती बाह्य निर्भरताहरू हुन् जुन सुस्त, महँगो, र गैर-निर्णायक हुन्छन्। मोकिंगले परीक्षणलाई छिटो बनाउँछ (सेकेन्डको सट्टा मिलिसेकेन्ड), निःशुल्क बनाउँछ (API शुल्क बिना), र निर्णयात्मक बनाउँछ (हरेक पटक उस्तै परिणाम)। -परीक्षणहरू स्वतन्त्र राख्नुहोस्। प्रत्येक परीक्षणले आफ्नै डाटा सेट अप गर्नुपर्छ, अरू परीक्षणहरूमा निर्भर हुनु हुँदैन र आफैं सफा गर्नुपर्छ। परीक्षणहरूले चलाउने क्रम जे भए पनि पास हुनुपर्छ। +परीक्षणहरू स्वतन्त्र राख्नुहोस्। प्रत्येक परीक्षणले आफ्नै डेटा सेटअप गर्नुपर्छ, अन्य परीक्षणमा निर्भर हुनु हुँदैन, र आफै सफा गर्नुपर्छ। परीक्षण सञ्चालनको क्रममा निर्भर नगरी पास हुनुपर्छ। -खुसी मार्ग भन्दा बाहिरका सीमाहरू परीक्षण गर्नुहोस्। खाली इनपुट, धेरै ठूला इनपुटहरू, विशेष अक्षरहरू, अमान्य प्यारामिटरहरू, र सिमानाहरू प्रयास गर्नुहोस्। यी प्रायः त्यस्ता बगहरू पत्ता लगाउँछन् जुन सामान्य प्रयोगले देखाउँदैन। +खुसी मार्ग (happy path) भन्दा बाहिरका केसहरू पनि परीक्षण गर्नुहोस्। खाली इनपुट, धेरै ठूलो इनपुट, विशेष वर्णहरू, अमान्य पैरामीटरहरू, र सिमानाका अवस्थाहरू प्रयास गर्नुहोस्। यी प्रायः सामान्य प्रयोगले देखाउन नसक्ने बगहरू खुलाउँछन्। -वर्णनात्मक नामहरू प्रयोग गर्नुहोस्। `shouldMaintainConversationHistoryAcrossMultipleMessages()` लाई `test1()` सँग तुलना गर्नुहोस्। पहिलोले कुन कुरा परीक्षण हुँदैछ स्पष्ट पार्छ, जसले नभएको बेला डिबग गर्ने काम सजिलो बनाउँछ। +वर्णनात्मक नामहरू प्रयोग गर्नुहोस्। `shouldMaintainConversationHistoryAcrossMultipleMessages()` सँग `test1()` तुलना गर्नुहोस्। पहिलोले के परीक्षण भइरहेको छ ठ्याक्कै बताउँछ, जसले असफलता डिबग गर्न सजिलो बनाउँछ। -## अगाडि के गर्ने +## अर्को चरणहरू -अब तपाईं परीक्षण ढाँचाहरू बुझ्नु भयो, प्रत्येक मोड्युलमा बढी गहिराईमा जानुहोस्: +अब जब तपाईं परीक्षण ढाँचाहरू बुझ्नुभयो, प्रत्येक मोड्युलमा गहिराईमा जानुहोस्: -- **[00 - छिटो सुरु](../00-quick-start/README.md)** - प्रॉम्प्ट टेम्प्लेट मूल कुरा सुरु गर्नुहोस् - **[01 - परिचय](../01-introduction/README.md)** - संवाद मेमोरी व्यवस्थापन सिक्नुहोस् -- **[02 - प्रॉम्प्ट इन्जिनियरिङ](../02-prompt-engineering/README.md)** - GPT-5.2 प्रॉम्प्टिङ ढाँचामा मास्टर गर्नुहोस् -- **[03 - RAG](../03-rag/README.md)** - रिट्रिभल-अग्मेन्टेड जेनेरेशन प्रणालीहरू बनाउनुहोस् -- **[04 - उपकरणहरू](../04-tools/README.md)** - फङ्क्शन कलिङ र उपकरण श्रृंखला कार्यान्वयन गर्नुहोस् +- **[02 - प्रम्प्ट इन्जिनियरिङ](../02/prompt-engineering/README.md)** - GPT-5.2 प्रम्प्टिङ ढाँचाहरू मास्टर गर्नुहोस् +- **[03 - RAG](../03-rag/README.md)** - पुनः प्राप्ति-वृद्धि उत्पादन प्रणालीहरू निर्माण गर्नुहोस् +- **[04 - उपकरणहरू](../04-tools/README.md)** - फङ्क्शन कलिंग र उपकरण श्रृंखलाहरू लागू गर्नुहोस् - **[05 - MCP](../05-mcp/README.md)** - मोडेल कन्टेक्स्ट प्रोटोकल एकीकरण गर्नुहोस् -प्रत्येक मोड्युलको README यहाँ परीक्षण गरिएका अवधारणाहरूको विस्तृत व्याख्या प्रदान गर्छ। +हरेक मोड्युलको README यहाँ परीक्षण गरिएका अवधारणाहरूको विस्तृत व्याख्या प्रदान गर्छ। --- -**नेभिगेसन:** [← मुख्यमा फर्कनुहोस्](../README.md) +**नेभिगेशन:** [← मुख्यमा फर्कनुहोस्](../README.md) --- -**अपवाद**: -यस दस्तावेजलाई AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरी अनुवाद गरिएको हो। हामी सटीकताको लागि प्रयासरत छौं, तर कृपया ध्यान दिनुहोस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धिहरू हुन सक्छन्। मूल दस्तावेज यसको मूल भाषामा आधिकारिक स्रोत मान्नुपर्छ। महत्वपूर्ण जानकारीको लागि, व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलतफहमी वा गलत व्याख्याका लागि हामी जिम्मेवार छैनौं। +**अस्वीकरण**: +यो दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी सही हुन प्रयास गर्छौं, तर कृपया जानकार हुनुस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छन्। मूल दस्तावेज़ यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलत बुझाइ वा त्रुटिको लागि हामी जिम्मेवार छैनौं। \ No newline at end of file diff --git a/translations/nl/.co-op-translator.json b/translations/nl/.co-op-translator.json index 2e12590d2..f814c10a2 100644 --- a/translations/nl/.co-op-translator.json +++ b/translations/nl/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "nl" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T03:06:16+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T08:24:22+00:00", "source_file": "01-introduction/README.md", "language_code": "nl" }, @@ -18,20 +18,20 @@ "language_code": "nl" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T03:08:00+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T08:19:40+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "nl" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T03:09:07+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T08:23:26+00:00", "source_file": "03-rag/README.md", "language_code": "nl" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:53:50+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T08:22:06+00:00", "source_file": "04-tools/README.md", "language_code": "nl" }, @@ -54,8 +54,8 @@ "language_code": "nl" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:10:50+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T08:18:16+00:00", "source_file": "README.md", "language_code": "nl" }, @@ -72,14 +72,14 @@ "language_code": "nl" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T03:12:27+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T08:20:12+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "nl" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T03:13:04+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T08:20:52+00:00", "source_file": "docs/TESTING.md", "language_code": "nl" } diff --git a/translations/nl/00-quick-start/README.md b/translations/nl/00-quick-start/README.md deleted file mode 100644 index eba490f5b..000000000 --- a/translations/nl/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Snel Aan de Slag - -## Inhoudsopgave - -- [Introductie](../../../00-quick-start) -- [Wat is LangChain4j?](../../../00-quick-start) -- [LangChain4j-afhankelijkheden](../../../00-quick-start) -- [Vereisten](../../../00-quick-start) -- [Installatie](../../../00-quick-start) - - [1. Verkrijg je GitHub-token](../../../00-quick-start) - - [2. Stel je token in](../../../00-quick-start) -- [Voer de voorbeelden uit](../../../00-quick-start) - - [1. Basis Chat](../../../00-quick-start) - - [2. Promptpatronen](../../../00-quick-start) - - [3. Functie-aanroepen](../../../00-quick-start) - - [4. Document Q&A (Easy RAG)](../../../00-quick-start) - - [5. Verantwoorde AI](../../../00-quick-start) -- [Wat elk voorbeeld laat zien](../../../00-quick-start) -- [Volgende stappen](../../../00-quick-start) -- [Probleemoplossing](../../../00-quick-start) - -## Introductie - -Deze snelstart is bedoeld om je zo snel mogelijk aan de slag te krijgen met LangChain4j. Het behandelt de absolute basis van het bouwen van AI-toepassingen met LangChain4j en GitHub Models. In de volgende modules ga je over op Azure OpenAI en GPT-5.2 en duik je dieper in elk concept. - -## Wat is LangChain4j? - -LangChain4j is een Java-bibliotheek die het bouwen van AI-aangedreven toepassingen vereenvoudigt. In plaats van te werken met HTTP-clients en JSON-parsing werk je met schone Java-API's. - -De "keten" in LangChain verwijst naar het aaneenschakelen van meerdere componenten - je kunt een prompt aan een model ketenen aan een parser, of meerdere AI-aanroepen aan elkaar koppelen waarbij de output van de ene invoer wordt voor de volgende. Deze snelstart richt zich op de fundamenten voordat we complexere ketens verkennen. - -LangChain4j Chaining Concept - -*Keten van componenten in LangChain4j - bouwstenen verbinden om krachtige AI-workflows te creëren* - -We gebruiken drie kerncomponenten: - -**ChatModel** - De interface voor AI-modelinteracties. Roep `model.chat("prompt")` aan en krijg een response string terug. We gebruiken `OpenAiOfficialChatModel` dat werkt met OpenAI-compatibele endpoints zoals GitHub Models. - -**AiServices** - Maakt type-veilige AI service interfaces. Definieer methoden, annoteer ze met `@Tool`, en LangChain4j regelt de orkestratie. De AI roept automatisch je Java-methoden aan indien nodig. - -**MessageWindowChatMemory** - Houdt de gespreksgeschiedenis bij. Zonder dit is elke aanvraag onafhankelijk. Met deze geheugenfunctie onthoudt de AI eerdere berichten en behoudt context over meerdere interacties. - -LangChain4j Architecture - -*LangChain4j architectuur - kerncomponenten die samenwerken om je AI-toepassingen aan te drijven* - -## LangChain4j-afhankelijkheden - -Deze snelstart gebruikt drie Maven-afhankelijkheden in de [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -De `langchain4j-open-ai-official` module levert de `OpenAiOfficialChatModel` klasse die verbinding maakt met OpenAI-compatibele API's. GitHub Models gebruikt hetzelfde API-formaat, dus een speciale adapter is niet nodig - verwijs gewoon de basis-URL naar `https://models.github.ai/inference`. - -De `langchain4j-easy-rag` module zorgt voor automatische documentopsplitsing, embedding en ophalen zodat je RAG-toepassingen kunt bouwen zonder elke stap handmatig te configureren. - -## Vereisten - -**Gebruik je de Dev Container?** Java en Maven zijn al geïnstalleerd. Je hebt alleen een GitHub Personal Access Token nodig. - -**Lokale ontwikkeling:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (instructies hieronder) - -> **Opmerking:** Deze module gebruikt `gpt-4.1-nano` van GitHub Models. Wijzig de modelnaam niet in de code - deze is geconfigureerd om te werken met de beschikbare modellen van GitHub. - -## Installatie - -### 1. Verkrijg je GitHub-token - -1. Ga naar [GitHub Instellingen → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Klik op "Generate new token" -3. Geef een beschrijvende naam (bijv. "LangChain4j Demo") -4. Stel een vervaldatum in (7 dagen aanbevolen) -5. Onder "Account permissions", zoek "Models" en stel in op "Read-only" -6. Klik op "Generate token" -7. Kopieer en bewaar je token - je ziet het daarna niet meer terug - -### 2. Stel je token in - -**Optie 1: Gebruik VS Code (Aanbevolen)** - -Als je VS Code gebruikt, voeg je je token toe aan het `.env` bestand in de projectroot: - -Als het `.env` bestand niet bestaat, kopieer dan `.env.example` naar `.env` of maak een nieuw `.env` bestand aan in de projectroot. - -**Voorbeeld `.env` bestand:** -```bash -# In /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Dan kun je eenvoudig met de rechtermuisknop op een demo-bestand klikken (bijv. `BasicChatDemo.java`) in de Verkenner en **"Run Java"** selecteren of de launchconfiguraties gebruiken via het Run en Debug paneel. - -**Optie 2: Gebruik de Terminal** - -Stel de token in als een omgevingsvariabele: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Voer de voorbeelden uit - -**Met VS Code:** Klik met de rechtermuisknop op een demo-bestand in de Verkenner en kies **"Run Java"**, of gebruik de launchconfiguraties vanuit het Run en Debug paneel (zorg dat het `.env` bestand met je token eerst is toegevoegd). - -**Met Maven:** Je kunt ook vanaf de commandoregel draaien: - -### 1. Basis Chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Promptpatronen - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Toont zero-shot, few-shot, chain-of-thought en rol-gebaseerde prompts. - -### 3. Functie-aanroepen - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -De AI roept automatisch je Java-methoden aan indien nodig. - -### 4. Document Q&A (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Stel vragen over je documenten met Easy RAG via automatische embedding en ophalen. - -### 5. Verantwoorde AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Zie hoe AI-veiligheidsfilters schadelijke inhoud blokkeren. - -## Wat elk voorbeeld laat zien - -**Basis Chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Begin hier om LangChain4j in zijn eenvoudigste vorm te zien. Je maakt een `OpenAiOfficialChatModel`, stuurt een prompt met `.chat()`, en ontvangt een antwoord. Dit toont de basis: hoe je modellen initialiseert met aangepaste endpoints en API-sleutels. Als je dit patroon begrijpt, bouwt alles daarop voort. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) en vraag: -> - "Hoe schakel ik in deze code over van GitHub Models naar Azure OpenAI?" -> - "Welke andere parameters kan ik configureren in OpenAiOfficialChatModel.builder()?" -> - "Hoe voeg ik streaming responses toe in plaats van te wachten op het complete antwoord?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Nu je weet hoe je met een model praat, laten we verkennen wat je zegt. Deze demo gebruikt dezelfde modelconfiguratie maar toont vijf verschillende promptpatronen. Probeer zero-shot prompts voor directe instructies, few-shot prompts die leren van voorbeelden, chain-of-thought prompts die redeneerstappen onthullen, en rol-gebaseerde prompts die context instellen. Je zult zien hoe hetzelfde model dramatisch verschillende resultaten geeft op basis van hoe je je verzoek formuleert. - -De demo toont ook prompttemplates, een krachtige manier om herbruikbare prompts met variabelen te maken. -Het onderstaande voorbeeld toont een prompt die de LangChain4j `PromptTemplate` gebruikt om variabelen in te vullen. De AI zal antwoorden op basis van de opgegeven bestemming en activiteit. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) en vraag: -> - "Wat is het verschil tussen zero-shot en few-shot prompting, en wanneer gebruik ik welke?" -> - "Hoe beïnvloedt de temperatuurparameter de reacties van het model?" -> - "Welke technieken zijn er om promptinjectie-aanvallen in productie te voorkomen?" -> - "Hoe maak ik herbruikbare PromptTemplate-objecten voor veelvoorkomende patronen?" - -**Tool Integratie** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Hier wordt LangChain4j krachtig. Je gebruikt `AiServices` om een AI-assistent te maken die je Java-methoden kan aanroepen. Annoteer gewoon methoden met `@Tool("beschrijving")` en LangChain4j regelt de rest - de AI beslist automatisch wanneer elke tool te gebruiken op basis van wat de gebruiker vraagt. Dit demonstreert functie-aanroepen, een sleuteltechniek voor het bouwen van AI die acties kan ondernemen, niet alleen vragen beantwoorden. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) en vraag: -> - "Hoe werkt de @Tool-annotatie en wat doet LangChain4j ermee achter de schermen?" -> - "Kan de AI meerdere tools achter elkaar aanroepen om complexe problemen op te lossen?" -> - "Wat gebeurt er als een tool een uitzondering gooit - hoe moet ik fouten afhandelen?" -> - "Hoe integreer ik een echte API in plaats van dit rekenvoorbeeld?" - -**Document Q&A (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Hier zie je RAG (retrieval-augmented generation) met LangChain4j's "Easy RAG"-aanpak. Documenten worden geladen, automatisch gesplitst en embedded in een in-memory opslag, waarna een content retriever relevante fragmenten aan de AI levert bij een vraag. De AI antwoordt op basis van je documenten, niet op algemene kennis. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) en vraag: -> - "Hoe voorkomt RAG AI-hallucinaties in vergelijking met het gebruik van de trainingsdata van het model?" -> - "Wat is het verschil tussen deze makkelijke aanpak en een aangepaste RAG-pijplijn?" -> - "Hoe schaal ik dit op om meerdere documenten of grotere kennisbases te verwerken?" - -**Verantwoorde AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Bouw AI-veiligheid met defense in depth. Deze demo toont twee beschermingslagen die samenwerken: - -**Deel 1: LangChain4j Input Guardrails** - Blokkeer gevaarlijke prompts voordat ze de LLM bereiken. Maak aangepaste guardrails die zoeken naar verboden sleutelwoorden of patronen. Deze draaien in je code, dus ze zijn snel en gratis. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Deel 2: Provider Safety Filters** - GitHub Models heeft ingebouwde filters die opvangen wat je guardrails misschien missen. Je ziet harde blokkades (HTTP 400 errors) voor ernstige overtredingen en zachte weigeringen waarbij de AI beleefd weigert. - -> **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) en vraag: -> - "Wat is InputGuardrail en hoe maak ik mijn eigen guardrails?" -> - "Wat is het verschil tussen een harde blokkade en een zachte weigering?" -> - "Waarom gebruik je guardrails en provider-filters samen?" - -## Volgende stappen - -**Volgende Module:** [01-introductie - Aan de slag met LangChain4j](../01-introduction/README.md) - ---- - -**Navigatie:** [← Terug naar Hoofd](../README.md) | [Volgende: Module 01 - Introductie →](../01-introduction/README.md) - ---- - -## Probleemoplossing - -### Eerste Maven-build - -**Probleem:** Eerste `mvn clean compile` of `mvn package` duurt lang (10-15 minuten) - -**Oorzaak:** Maven moet alle projectafhankelijkheden downloaden (Spring Boot, LangChain4j-bibliotheken, Azure SDK's, enz.) bij de eerste build. - -**Oplossing:** Dit is normaal gedrag. Volgende builds zijn veel sneller omdat afhankelijkheden lokaal worden gecachet. Downloadtijd hangt af van je netwerksnelheid. - -### PowerShell Maven-commando syntax - -**Probleem:** Maven-commando's mislukken met fout `Unknown lifecycle phase ".mainClass=..."` -**Oorzaak**: PowerShell interpreteert `=` als een toewijzingsoperator voor variabelen, waardoor de Maven-syntaxis voor eigenschappen wordt verbroken - -**Oplossing**: Gebruik de stop-parsing-operator `--%` vóór het Maven-commando: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -De `--%`-operator vertelt PowerShell om alle resterende argumenten letterlijk door te geven aan Maven zonder interpretatie. - -### Windows PowerShell Emoji-weergave - -**Probleem**: AI-responses tonen vreemde tekens (bijv. `????` of `â??`) in plaats van emoji's in PowerShell - -**Oorzaak**: De standaardcodering van PowerShell ondersteunt geen UTF-8 emoji's - -**Oplossing**: Voer dit commando uit voordat je Java-toepassingen start: -```cmd -chcp 65001 -``` - -Dit dwingt UTF-8-codering af in de terminal. Gebruik eventueel Windows Terminal, dat betere Unicode-ondersteuning heeft. - -### Debuggen van API-aanroepen - -**Probleem**: Authenticatiefouten, snelheidslimieten of onverwachte reacties van het AI-model - -**Oplossing**: De voorbeelden bevatten `.logRequests(true)` en `.logResponses(true)` om API-aanroepen in de console te tonen. Dit helpt bij het oplossen van authenticatiefouten, snelheidslimieten of onverwachte reacties. Verwijder deze vlaggen in productie om minder loggeluid te hebben. - ---- - - -**Disclaimer**: -Dit document is vertaald met behulp van de AI-vertalingsservice [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, moet u er rekening mee houden dat automatische vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal dient als de gezaghebbende bron beschouwd te worden. Voor cruciale informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. - \ No newline at end of file diff --git a/translations/nl/01-introduction/README.md b/translations/nl/01-introduction/README.md index 4d9565a56..91c9ecebc 100644 --- a/translations/nl/01-introduction/README.md +++ b/translations/nl/01-introduction/README.md @@ -2,86 +2,86 @@ ## Inhoudsopgave -- [Video Walkthrough](../../../01-introduction) -- [Wat Je Zal Leren](../../../01-introduction) -- [Vereisten](../../../01-introduction) -- [De Kern van het Probleem Begrijpen](../../../01-introduction) -- [Tokens Begrijpen](../../../01-introduction) -- [Hoe Geheugen Werkt](../../../01-introduction) -- [Hoe Dit LangChain4j Gebruikt](../../../01-introduction) -- [Azure OpenAI Infrastructuur Uitrollen](../../../01-introduction) -- [De Applicatie Lokaal Uitvoeren](../../../01-introduction) -- [De Applicatie Gebruiken](../../../01-introduction) - - [Stateless Chat (Linker Paneel)](../../../01-introduction) - - [Stateful Chat (Rechter Paneel)](../../../01-introduction) -- [Volgende Stappen](../../../01-introduction) +- [Video Walkthrough](#video-walkthrough) +- [Wat Je Zal Leren](#wat-je-zal-leren) +- [Vereisten](#vereisten) +- [Begrijpen van het Kernprobleem](#begrijpen-van-het-kernprobleem) +- [Begrijpen van Tokens](#begrijpen-van-tokens) +- [Hoe Geheugen Werkt](#hoe-geheugen-werkt) +- [Hoe Dit LangChain4j Gebruikt](#hoe-dit-langchain4j-gebruikt) +- [Azure OpenAI Infrastructuur Implementeren](#azure-openai-infrastructuur-implementeren) +- [De Applicatie Lokaal Uitvoeren](#de-applicatie-lokaal-uitvoeren) +- [De Applicatie Gebruiken](#de-applicatie-gebruiken) + - [Stateless Chat (Linker Paneel)](#stateless-chat-linker-paneel) + - [Stateful Chat (Rechter Paneel)](#stateful-chat-rechter-paneel) +- [Volgende Stappen](#volgende-stappen) ## Video Walkthrough -Bekijk deze live sessie die uitlegt hoe je aan de slag gaat met deze module: +Bekijk deze live sessie die uitlegt hoe je met deze module aan de slag gaat: Getting Started with LangChain4j - Live Session ## Wat Je Zal Leren -In de quick start gebruikte je GitHub Models om prompts te versturen, tools aan te roepen, een RAG-pijplijn te bouwen en guardrails te testen. Die demo’s lieten zien wat mogelijk is — nu schakelen we over naar Azure OpenAI en GPT-5.2 en beginnen we productieachtige applicaties te bouwen. Deze module richt zich op conversationele AI die context onthoudt en toestand behoudt — de concepten die die quick start demo’s achter de schermen gebruikten maar niet uitlegden. +Dit is je startpunt met LangChain4j en Azure OpenAI. We beginnen met de basisprincipes en bouwen productie-achtige applicaties. Deze module richt zich op conversational AI die context onthoudt en staat behoudt — dit zijn de fundamentele concepten waar alle latere modules op voortbouwen. -We gebruiken Azure OpenAI's GPT-5.2 door deze gids heen omdat zijn geavanceerde redeneervermogen het gedrag van verschillende patronen duidelijker maakt. Als je geheugen toevoegt, zie je het verschil scherp. Dit maakt het gemakkelijker te begrijpen wat elk onderdeel aan je applicatie bijdraagt. +We gebruiken Azure OpenAI's GPT-5.2 door deze hele gids omdat de geavanceerde redeneer-mogelijkheden van dit model het gedrag van verschillende patronen duidelijker maken. Wanneer je geheugen toevoegt, zie je het verschil glashelder. Dit maakt het gemakkelijker om te begrijpen wat elke component voor je applicatie doet. Je bouwt één applicatie die beide patronen demonstreert: -**Stateless Chat** - Elke aanvraag is onafhankelijk. Het model heeft geen geheugen van eerdere berichten. Dit is het patroon dat je in de quick start gebruikte. +**Stateless Chat** – Elk verzoek is onafhankelijk. Het model heeft geen geheugen van eerdere berichten. Dit is het eenvoudigste startpunt. -**Stateful Conversation** - Elke aanvraag bevat de gespreksgeschiedenis. Het model behoudt context over meerdere beurten. Dit is wat productieapplicaties vereisen. +**Stateful Conversation** – Elk verzoek bevat het gesprekshistorie. Het model behoudt context over meerdere beurten. Dit is wat productieapplicaties vereisen. ## Vereisten -- Azure-abonnement met toegang tot Azure OpenAI -- Java 21, Maven 3.9+ +- Azure-abonnement met Azure OpenAI-toegang +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) > **Opmerking:** Java, Maven, Azure CLI en Azure Developer CLI (azd) zijn vooraf geïnstalleerd in de meegeleverde devcontainer. -> **Opmerking:** Deze module gebruikt GPT-5.2 op Azure OpenAI. De uitrol is automatisch geconfigureerd via `azd up` - wijzig de modelnaam in de code niet. +> **Opmerking:** Deze module gebruikt GPT-5.2 op Azure OpenAI. De deployment wordt automatisch geconfigureerd via `azd up` - wijzig de modelnaam niet in de code. -## De Kern van het Probleem Begrijpen +## Begrijpen van het Kernprobleem -Taalmodellen zijn stateless. Elke API-aanroep is onafhankelijk. Als je "Mijn naam is John" stuurt en daarna vraagt "Wat is mijn naam?", dan weet het model niet dat je jezelf zojuist hebt voorgesteld. Het behandelt elke aanvraag alsof het de eerste conversatie ooit is. +Taalmodellen zijn stateless. Elke API-aanroep is onafhankelijk. Als je zegt "Mijn naam is John" en daarna vraagt "Wat is mijn naam?", weet het model niet dat je jezelf zojuist hebt voorgesteld. Het behandelt elk verzoek alsof het de eerste keer is dat je praat. -Dit is prima voor eenvoudige Q&A, maar nutteloos voor echte applicaties. Klantenservicebots moeten onthouden wat je hen vertelde. Persoonlijke assistenten hebben context nodig. Elke multi-turn gesprek vereist geheugen. +Dit is prima voor eenvoudige Q&A, maar nutteloos voor echte applicaties. Klantenservice-bots moeten onthouden wat je ze vertelde. Persoonlijke assistenten hebben context nodig. Elke multi-turn conversatie vereist geheugen. -Het onderstaande diagram vergelijkt de twee benaderingen — links een stateless oproep die je naam vergeet; rechts een stateful oproep ondersteund door ChatMemory die het onthoudt. +Het volgende diagram zet de twee benaderingen tegenover elkaar — links een stateless aanroep die je naam vergeet; rechts een stateful aanroep ondersteund door ChatMemory die het onthoudt. Stateless vs Stateful Conversations -*Het verschil tussen stateless (onafhankelijke oproepen) en stateful (contextbewuste) gesprekken* +*Het verschil tussen stateless (onafhankelijke aanroepen) en stateful (contextbewuste) gesprekken* -## Tokens Begrijpen +## Begrijpen van Tokens -Voordat je in gesprekken duikt, is het belangrijk tokens te begrijpen - de basiseenheden tekst die taalmodellen verwerken: +Voordat we in gesprekken duiken, is het belangrijk om tokens te begrijpen – de basiseenheden van tekst die taalmodellen verwerken: Token Explanation -*Voorbeeld van hoe tekst wordt opgesplitst in tokens - "I love AI!" wordt 4 aparte verwerkingsunits* +*Voorbeeld van hoe tekst in tokens wordt opgedeeld - "I love AI!" wordt 4 aparte verwerkingsunits* -Tokens zijn hoe AI-modellen tekst meten en verwerken. Woorden, interpunctie en zelfs spaties kunnen tokens zijn. Je model heeft een limiet van hoeveel tokens het tegelijk kan verwerken (400.000 voor GPT-5.2, met maximaal 272.000 inputtokens en 128.000 outputtokens). Tokens begrijpen helpt je om de lengte van gesprekken en kosten te beheren. +Tokens zijn hoe AI-modellen tekst meten en verwerken. Woorden, leestekens en zelfs spaties kunnen tokens zijn. Je model heeft een limiet aan hoeveel tokens het tegelijk kan verwerken (400.000 voor GPT-5.2, met maximaal 272.000 inputtokens en 128.000 outputtokens). Tokens begrijpen helpt je de lengte van het gesprek en kosten te beheren. ## Hoe Geheugen Werkt -Chatgeheugen lost het stateless probleem op door de gespreksgeschiedenis te bewaren. Voordat je je verzoek naar het model stuurt, voegt het framework relevante eerdere berichten toe. Wanneer je vraagt “Wat is mijn naam?”, verstuurt het systeem feitelijk de hele gespreksgeschiedenis, waardoor het model kan “zien” dat je eerder zei "Mijn naam is John." +Chatgeheugen lost het stateless probleem op door gesprekshistorie te behouden. Voordat je je verzoek naar het model stuurt, voegt het framework relevante vorige berichten toe. Wanneer je vraagt "Wat is mijn naam?", stuurt het systeem daadwerkelijk de hele gesprekshistorie mee, zodat het model ziet dat je eerder zei "Mijn naam is John." -LangChain4j biedt geheugenimplementaties die dit automatisch afhandelen. Je kiest hoeveel berichten behouden blijven en het framework beheert het contextvenster. Het onderstaande diagram toont hoe MessageWindowChatMemory een schuifvenster van recente berichten behoudt. +LangChain4j biedt geheugenimplementaties die dit automatisch afhandelen. Je kiest hoeveel berichten je wil bewaren en het framework beheert het contextvenster. Het onderstaande diagram toont hoe MessageWindowChatMemory een schuivend venster van recente berichten onderhoudt. Memory Window Concept -*MessageWindowChatMemory behoudt een schuifvenster van recente berichten door automatisch oude te verwijderen* +*MessageWindowChatMemory onderhoudt een schuivend venster van recente berichten en verwijdert automatisch oude* ## Hoe Dit LangChain4j Gebruikt -Deze module breidt de quick start uit door Spring Boot te integreren en gespreksgeheugen toe te voegen. Zo passen de onderdelen samen: +Deze module integreert Spring Boot en voegt gesprekgeheugen toe. Zo passen de onderdelen samen: -**Dependencies** - Voeg twee LangChain4j bibliotheken toe: +**Dependencies** – Voeg twee LangChain4j-bibliotheken toe: ```xml @@ -94,7 +94,7 @@ Deze module breidt de quick start uit door Spring Boot te integreren en gespreks ``` -**Chat Model** - Configureer Azure OpenAI als een Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chat Model** – Configureer Azure OpenAI als een Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -De builder leest credentials uit omgevingsvariabelen die door `azd up` zijn gezet. Het instellen van `baseUrl` naar je Azure eindpunt maakt de OpenAI client compatibel met Azure OpenAI. +De builder leest de credentials uit omgevingsvariabelen die door `azd up` zijn gezet. Het instellen van `baseUrl` op je Azure endpoint laat de OpenAI client met Azure OpenAI werken. -**Gespreksgeheugen** - Houd de chatgeschiedenis bij met MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Gesprekgeheugen** – Houd chatgeschiedenis bij met MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,51 +124,51 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Maak geheugen aan met `withMaxMessages(10)` om de laatste 10 berichten vast te houden. Voeg gebruikers- en AI-berichten toe met getypte wrappers: `UserMessage.from(text)` en `AiMessage.from(text)`. Haal de geschiedenis op met `memory.messages()` en stuur die naar het model. De service slaat voor elke gesprek-ID aparte geheugeninstellingen op, zodat meerdere gebruikers tegelijk kunnen chatten. +Maak geheugen aan met `withMaxMessages(10)` om de laatste 10 berichten te bewaren. Voeg gebruiker- en AI-berichten toe met getypeerde wrappers: `UserMessage.from(text)` en `AiMessage.from(text)`. Haal de geschiedenis op met `memory.messages()` en stuur die naar het model. De service slaat per gesprek-ID afzonderlijke geheugeninstanties op, wat meerdere gebruikers tegelijk laat chatten. > **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) en vraag: -> - "Hoe bepaalt MessageWindowChatMemory welke berichten verwijderd worden als het venster vol is?" -> - "Kan ik aangepaste geheugentoegang implementeren met een database in plaats van in-memory?" -> - "Hoe zou ik samenvatting toevoegen om oude gespreksgeschiedenis te comprimeren?" +> - "Hoe beslist MessageWindowChatMemory welke berichten worden verwijderd als het venster vol is?" +> - "Kan ik eigen geheugentoegang implementeren met een database in plaats van in-memory?" +> - "Hoe voeg ik samenvatting toe om oude gesprekshistorie te comprimeren?" -Het stateless chat endpoint slaat geheugen helemaal over — gewoon `chatModel.chat(prompt)` zoals in de quick start. Het stateful endpoint voegt berichten toe aan geheugen, haalt geschiedenis op en voegt die context toe aan elke aanvraag. Zelfde modelconfiguratie, andere patronen. +De stateless chat endpoint slaat geheugen helemaal over – gewoon `chatModel.chat(prompt)` zoals de snelle start. De stateful endpoint voegt berichten toe aan geheugen, haalt de geschiedenis op en voegt die context toe aan elk verzoek. Zelfde modelconfiguratie, andere patronen. -## Azure OpenAI Infrastructuur Uitrollen +## Azure OpenAI Infrastructuur Implementeren **Bash:** ```bash cd 01-introduction -azd up # Selecteer abonnement en locatie (aanbevolen: eastus2) +azd up # Selecteer abonnement en locatie (aanbevolen is eastus2) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Selecteer abonnement en locatie (aanbevolen is eastus2) +azd up # Selecteer abonnement en locatie (eastus2 aanbevolen) ``` -> **Opmerking:** Als je een time-out fout tegenkomt (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), voer dan gewoon `azd up` opnieuw uit. Azure resources kunnen nog bezig zijn met provisie, en een retry zorgt dat de uitrol voltooid wordt zodra resources een eindtoestand bereiken. +> **Opmerking:** Als je een time-out fout krijgt (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), voer dan gewoon opnieuw `azd up` uit. Azure resources kunnen nog worden ingericht op de achtergrond, en opnieuw proberen laat de deployment voltooien zodra de resources een eindtoestand bereiken. Dit zal: -1. Azure OpenAI resource uitrollen met GPT-5.2 en text-embedding-3-small modellen +1. De Azure OpenAI resource uitrollen met GPT-5.2 en text-embedding-3-small modellen 2. Automatisch een `.env` bestand genereren in de projectroot met credentials 3. Alle benodigde omgevingsvariabelen instellen -**Problemen met uitrol?** Zie de [Infrastructure README](infra/README.md) voor gedetailleerde troubleshooting waaronder subdomeinnaam conflicten, handmatige Azure Portal uitrolstappen en modelconfiguratie-advies. +**Problemen met deployment?** Bekijk de [Infrastructure README](infra/README.md) voor gedetailleerde troubleshooting waaronder subdomeinnaam-conflicten, handmatige Azure Portal deployment stappen en modelconfiguratie richtlijnen. -**Controleer of de uitrol gelukt is:** +**Controleer of deployment is gelukt:** **Bash:** ```bash -cat ../.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, enz. weergeven. +cat ../.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, enz. tonen ``` **PowerShell:** ```powershell -Get-Content ..\.env # Zou AZURE_OPENAI_ENDPOINT, API_KEY, enz. moeten laten zien. +Get-Content ..\.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, enz. tonen. ``` -> **Opmerking:** Het commando `azd up` genereert automatisch het `.env` bestand. Als je dat later moet bijwerken, kun je het `.env` bestand handmatig aanpassen of opnieuw laten genereren met: +> **Opmerking:** Het `azd up` commando genereert automatisch het `.env` bestand. Als je het later moet bijwerken, kun je het `.env` bestand handmatig aanpassen of opnieuw genereren door: > > **Bash:** > ```bash @@ -184,13 +184,13 @@ Get-Content ..\.env # Zou AZURE_OPENAI_ENDPOINT, API_KEY, enz. moeten laten zie ## De Applicatie Lokaal Uitvoeren -**Controleer uitrol:** +**Controleer de deployment:** -Zorg dat het `.env` bestand in de hoofdmap staat met Azure credentials. Voer dit uit vanuit de moduledirectory (`01-introduction/`): +Zorg dat het `.env` bestand aanwezig is in de root map met Azure-gegevens. Voer dit uit vanuit de module-directory (`01-introduction/`): **Bash:** ```bash -cat ../.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT tonen +cat ../.env # Zou AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT moeten tonen ``` **PowerShell:** @@ -202,27 +202,27 @@ Get-Content ..\.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT weergeven **Optie 1: Gebruik Spring Boot Dashboard (Aanbevolen voor VS Code gebruikers)** -De devcontainer bevat de Spring Boot Dashboard-extensie, die een visuele interface biedt voor het beheren van alle Spring Boot applicaties. Je vindt het in de Activiteitenbalk aan de linkerkant van VS Code (zoek naar het Spring Boot icoon). +De devcontainer bevat de Spring Boot Dashboard extensie, die een visuele interface biedt om alle Spring Boot applicaties te beheren. Je vindt deze in de Activity Bar aan de linkerkant in VS Code (zoek naar het Spring Boot icoon). -Vanuit het Spring Boot Dashboard kun je: +Vanaf het Spring Boot Dashboard kun je: - Alle beschikbare Spring Boot applicaties in de workspace zien - Applicaties starten/stoppen met één klik -- Applicatielogs in real-time bekijken +- Applicatielogs realtime bekijken - Applicatiestatus monitoren -Klik simpelweg op de afspeelknop naast "introduction" om deze module te starten, of start alle modules tegelijk. +Klik simpelweg op de play-knop naast "introduction" om deze module te starten, of start alle modules tegelijk. Spring Boot Dashboard *Het Spring Boot Dashboard in VS Code — start, stop en monitor alle modules vanaf één plek* -**Optie 2: Gebruik shell scripts** +**Optie 2: Gebruik shell-scripts** Start alle webapplicaties (modules 01-04): **Bash:** ```bash -cd .. # Vanuit de hoofdmap +cd .. # Vanuit de root directory ./start-all.sh ``` @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Beide scripts laden automatisch omgevingvariabelen uit het root `.env` bestand en bouwen de JARs als ze nog niet bestaan. +Beide scripts laden automatisch omgevingsvariabelen vanuit de root `.env` en bouwen de JARs als die nog niet bestaan. -> **Opmerking:** Als je liever alle modules handmatig bouwt voordat je start: +> **Opmerking:** Wil je liever eerst zelf alle modules handmatig bouwen voordat je start: > > **Bash:** > ```bash @@ -286,25 +286,25 @@ De applicatie biedt een webinterface met twee chatimplementaties naast elkaar. Application Home Screen -*Dashboard met zowel Simple Chat (stateless) als Conversational Chat (stateful) opties* +*Dashboard toont zowel Simple Chat (stateless) als Conversational Chat (stateful) opties* ### Stateless Chat (Linker Paneel) -Probeer dit eerst. Vraag "Mijn naam is John" en vraag dan direct "Wat is mijn naam?" Het model zal het niet herinneren omdat elk bericht onafhankelijk is. Dit toont het kernprobleem van eenvoudige integratie met taalmodellen - geen context in het gesprek. +Probeer dit eerst. Vraag "Mijn naam is John" en vraag dan meteen "Wat is mijn naam?" Het model zal het niet onthouden omdat elk bericht onafhankelijk is. Dit toont het kernprobleem van basisintegratie met taalmodellen - geen gesprekcontext. Stateless Chat Demo -*AI herinnert zich je naam niet van het vorige bericht* +*AI onthoudt je naam niet van het vorige bericht* ### Stateful Chat (Rechter Paneel) -Probeer nu dezelfde reeks hier. Vraag "Mijn naam is John" en daarna "Wat is mijn naam?" Dit keer onthoudt het. Het verschil is MessageWindowChatMemory — het onderhoudt de gespreksgeschiedenis en voegt die toe aan elke aanvraag. Zo werkt productionele conversatie-AI. +Probeer nu dezelfde volgorde hier. Vraag "Mijn naam is John" en daarna "Wat is mijn naam?" Deze keer herinnert het zich dat wel. Het verschil is MessageWindowChatMemory - het onderhoudt gesprekshistorie en voegt die met elk verzoek mee. Zo werkt conversatie-AI in productie. Stateful Chat Demo -*AI herinnert zich je naam van eerder in het gesprek* +*AI onthoudt je naam van eerder in het gesprek* -Beide panelen gebruiken hetzelfde GPT-5.2 model. Het enige verschil is geheugen. Dit maakt duidelijk wat geheugen aan je applicatie toevoegt en waarom het essentieel is voor echte toepassingen. +Beide panelen gebruiken hetzelfde GPT-5.2 model. Het enige verschil is geheugen. Dit maakt duidelijk wat geheugen voor je applicatie betekent en waarom het essentieel is voor echte toepassingen. ## Volgende Stappen @@ -312,11 +312,11 @@ Beide panelen gebruiken hetzelfde GPT-5.2 model. Het enige verschil is geheugen. --- -**Navigatie:** [← Vorige: Module 00 - Quick Start](../00-quick-start/README.md) | [Terug naar Hoofdmenu](../README.md) | [Volgende: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigatie:** [← Terug naar Hoofdmenu](../README.md) | [Volgende: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **Disclaimer**: -Dit document is vertaald met behulp van de AI vertaaldienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het oorspronkelijke document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. +Dit document is vertaald met behulp van de AI vertaaldienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. \ No newline at end of file diff --git a/translations/nl/02-prompt-engineering/README.md b/translations/nl/02-prompt-engineering/README.md index ffebde79a..5e4eb5658 100644 --- a/translations/nl/02-prompt-engineering/README.md +++ b/translations/nl/02-prompt-engineering/README.md @@ -2,80 +2,80 @@ ## Inhoudsopgave -- [Video Walkthrough](../../../02-prompt-engineering) -- [Wat Je Zal Leren](../../../02-prompt-engineering) -- [Vereisten](../../../02-prompt-engineering) -- [Begrip van Prompt Engineering](../../../02-prompt-engineering) -- [Basisprincipes van Prompt Engineering](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Rolgebaseerd Prompting](../../../02-prompt-engineering) - - [Prompt Sjablonen](../../../02-prompt-engineering) -- [Geavanceerde Patronen](../../../02-prompt-engineering) -- [De Applicatie Uitvoeren](../../../02-prompt-engineering) -- [Applicatie Screenshots](../../../02-prompt-engineering) -- [De Patronen Verkennen](../../../02-prompt-engineering) - - [Lage vs Hoge Begeerte](../../../02-prompt-engineering) - - [Taakuitvoering (Tool Intro's)](../../../02-prompt-engineering) - - [Zelfreflecterende Code](../../../02-prompt-engineering) - - [Gestructureerde Analyse](../../../02-prompt-engineering) - - [Multi-Turn Chat](../../../02-prompt-engineering) - - [Stap-voor-Stap Redeneren](../../../02-prompt-engineering) - - [Beperkte Output](../../../02-prompt-engineering) -- [Wat Je Echt Leren](../../../02-prompt-engineering) -- [Volgende Stappen](../../../02-prompt-engineering) +- [Video Walkthrough](#video-walkthrough) +- [Wat je zult leren](#wat-je-zult-leren) +- [Vereisten](#vereisten) +- [Begrijpen van Prompt Engineering](#begrijpen-van-prompt-engineering) +- [Fundamenten van Prompt Engineering](#fundamenten-van-prompt-engineering) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Geavanceerde Patronen](#geavanceerde-patronen) +- [Start de Applicatie](#start-de-applicatie) +- [Applicatie Screenshots](#applicatie-screenshots) +- [Patronen Verkennen](#patronen-verkennen) + - [Lage vs Hoge Enthousiasme](#lage-vs-hoge-enthousiasme) + - [Taakuitvoering (Tool Preambles)](#taakuitvoering-tool-preambles) + - [Zelfreflecterende Code](#zelfreflecterende-code) + - [Gestructureerde Analyse](#gestructureerde-analyse) + - [Multi-Turn Chat](#meertraps-chat) + - [Stap-voor-Stap Redenering](#stap-voor-stap-redenering) + - [Beperkte Output](#beperkte-output) +- [Wat je echt leert](#wat-je-echt-leert) +- [Volgende stappen](#volgende-stappen) ## Video Walkthrough Bekijk deze live sessie waarin wordt uitgelegd hoe je aan deze module kunt beginnen: -Prompt Engineering met LangChain4j - Live Sessie +Prompt Engineering met LangChain4j - Live Sessies -## Wat Je Zal Leren +## Wat je zult leren Het volgende diagram geeft een overzicht van de belangrijkste onderwerpen en vaardigheden die je in deze module ontwikkelt — van prompt verfijningstechnieken tot de stap-voor-stap workflow die je volgt. -Wat Je Zal Leren +Wat je zult leren -In eerdere modules heb je basisinteracties met LangChain4j en GitHub Modellen onderzocht en gezien hoe geheugen gesprek-KI met Azure OpenAI mogelijk maakt. Nu richten we ons op de vragen die je stelt — de prompts zelf — met behulp van Azure OpenAI's GPT-5.2. De manier waarop je prompts structureert, bepaalt in hoge mate de kwaliteit van de antwoorden die je krijgt. We beginnen met een overzicht van de fundamentele prompting technieken en gaan vervolgens over op acht geavanceerde patronen die de volledige mogelijkheden van GPT-5.2 benutten. +In de vorige module zag je hoe geheugen conversatie-AI met Azure OpenAI mogelijk maakt. Nu richten we ons op hoe je vragen stelt — de prompts zelf — met behulp van Azure OpenAI’s GPT-5.2. De manier waarop je je prompts structureert, beïnvloedt drastisch de kwaliteit van de antwoorden die je ontvangt. We beginnen met een herziening van de fundamentele prompting technieken, en gaan vervolgens over naar acht geavanceerde patronen die optimaal gebruikmaken van de mogelijkheden van GPT-5.2. -We gebruiken GPT-5.2 omdat het redeneerscontrole introduceert - je kunt het model vertellen hoeveel het moet nadenken voordat het antwoord geeft. Dit maakt verschillende prompting strategieën duidelijker en helpt je begrijpen wanneer je welke aanpak moet gebruiken. Bovendien profiteren we van de minder strikte snelheidslimieten van Azure voor GPT-5.2 vergeleken met GitHub Modellen. +We gebruiken GPT-5.2 omdat het redeneersturing introduceert - je kunt het model vertellen hoeveel het moet nadenken voor het antwoorden. Dit maakt verschillende prompting strategieën duidelijker en helpt je begrijpen wanneer je welke aanpak moet gebruiken. ## Vereisten -- Module 01 voltooid (Azure OpenAI bronnen gedeployed) -- `.env` bestand in de hoofdmap met Azure-gegevens (aangemaakt door `azd up` in Module 01) +- Module 01 voltooid (Azure OpenAI resources gedeployed) +- `.env` bestand in de root directory met Azure credentials (gemaakt door `azd up` in Module 01) -> **Opmerking:** Als je Module 01 nog niet hebt afgerond, volg dan eerst de deployment instructies daar. +> **Opmerking:** Als je Module 01 nog niet hebt voltooid, volg dan eerst de implementatie-instructies daar. -## Begrip van Prompt Engineering +## Begrijpen van Prompt Engineering -In de kern is prompt engineering het verschil tussen vage en precieze instructies, zoals de vergelijking hieronder laat zien. +In de kern is prompt engineering het verschil tussen vage instructies en precieze instructies, zoals de onderstaande vergelijking illustreert. Wat is Prompt Engineering? -Prompt engineering gaat over het ontwerpen van invoertekst die consequent de resultaten oplevert die je nodig hebt. Het gaat niet alleen om het stellen van vragen — het gaat om het structureren van verzoeken zodat het model precies begrijpt wat je wilt en hoe het geleverd moet worden. +Prompt engineering gaat over het ontwerpen van invoertekst die consequent de resultaten oplevert die je nodig hebt. Het gaat niet alleen om het stellen van vragen - het gaat om het structureren van verzoeken zodat het model precies begrijpt wat je wilt en hoe het dat moet leveren. -Denk erover als het geven van instructies aan een collega. "Los de bug op" is vaag. "Los de null pointer exception op in UserService.java regel 45 door een null check toe te voegen" is specifiek. Taalmodellen werken op precies dezelfde manier — specificiteit en structuur zijn belangrijk. +Denk eraan als het geven van instructies aan een collega. "Los de bug op" is vaag. "Los de null pointer exception op in UserService.java regel 45 door een null-check toe te voegen" is specifiek. Taalmodellen werken op dezelfde manier - specificiteit en structuur zijn van belang. -Het onderstaande diagram toont hoe LangChain4j in dit plaatje past — het koppelt je prompt patronen aan het model via SystemMessage en UserMessage bouwstenen. +Het onderstaande diagram toont hoe LangChain4j in dit plaatje past — door je promptpatronen via bouwstenen SystemMessage en UserMessage te verbinden met het model. -Hoe LangChain4j Passen +Hoe LangChain4j past -LangChain4j levert de infrastructuur — modelverbindingen, geheugen en berichttypes — terwijl prompt patronen gewoon zorgvuldig gestructureerde tekst zijn die je via die infrastructuur verstuurt. De belangrijkste bouwstenen zijn `SystemMessage` (dat het gedrag en de rol van de AI bepaalt) en `UserMessage` (dat je daadwerkelijke verzoek draagt). +LangChain4j biedt de infrastructuur — modelverbindingen, geheugen en berichttypen — terwijl promptpatronen simpelweg zorgvuldig gestructureerde tekst zijn die je door die infrastructuur stuurt. De belangrijkste bouwstenen zijn `SystemMessage` (die het gedrag en de rol van de AI bepaalt) en `UserMessage` (die je daadwerkelijke verzoek draagt). -## Basisprincipes van Prompt Engineering +## Fundamenten van Prompt Engineering -De vijf kerntechnieken hieronder vormen de basis van effectieve prompt engineering. Elk adresseert een ander aspect van hoe je met taalmodellen communiceert. +De vijf kerntechnieken hieronder vormen de basis van effectieve prompt engineering. Elk adresseren een ander aspect van hoe je met taalmodellen communiceert. -Overzicht Vijf Prompt Engineering Patronen +Overzicht van vijf Prompt Engineering Patronen -Voordat we ingaan op de geavanceerde patronen in deze module, laten we vijf fundamentele prompting technieken herzien. Dit zijn de bouwstenen die elke prompt engineer zou moeten kennen. Als je de [Quick Start module](../00-quick-start/README.md#2-prompt-patterns) al hebt doorlopen, heb je deze al in actie gezien — hier is het conceptuele raamwerk erachter. +Voordat we ingaan op de geavanceerde patronen in deze module, herzien we vijf fundamentele prompting technieken. Dit zijn de bouwstenen die elke prompt engineer moet kennen. ### Zero-Shot Prompting -De eenvoudigste aanpak: geef het model een directe instructie zonder voorbeelden. Het model vertrouwt volledig op zijn training om de taak te begrijpen en uit te voeren. Dit werkt goed voor eenvoudige verzoeken waarbij het verwachte gedrag duidelijk is. +De eenvoudigste aanpak: geef het model een directe instructie zonder voorbeelden. Het model vertrouwt volledig op zijn training om de taak te begrijpen en uit te voeren. Dit werkt goed voor rechttoe rechtaan verzoeken waarbij het verwachte gedrag duidelijk is. Zero-Shot Prompting @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Antwoord: "Positief" ``` -**Wanneer te gebruiken:** Simpele classificaties, directe vragen, vertalingen of elke taak die het model zonder extra begeleiding aankan. +**Wanneer te gebruiken:** Simpele classificaties, directe vragen, vertalingen, of elke taak die het model zonder extra aanwijzingen kan uitvoeren. ### Few-Shot Prompting -Geef voorbeelden die het patroon tonen dat je wilt dat het model volgt. Het model leert het verwachte invoer-uitvoerformaat van je voorbeelden en past dat toe op nieuwe invoer. Dit verbetert de consistentie aanzienlijk voor taken waarbij het gewenste formaat of gedrag niet vanzelfsprekend is. +Geef voorbeelden die het patroon aantonen dat je wilt dat het model volgt. Het model leert het verwachte input-output formaat van je voorbeelden en past dit toe op nieuwe inputs. Dit verbetert de consistentie enorm voor taken waarbij het gewenste formaat of gedrag niet duidelijk is. Few-Shot Prompting -*Leren van voorbeelden — het model herkent het patroon en past het toe op nieuwe invoer* +*Leren van voorbeelden — het model herkent het patroon en past het toe op nieuwe inputs* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Wanneer te gebruiken:** Aangepaste classificaties, consistente opmaak, domeinspecifieke taken of wanneer zero-shot resultaten inconsistent zijn. +**Wanneer te gebruiken:** Maatwerk classificaties, consistente formatting, domeinspecifieke taken, of wanneer zero-shot resultaten inconsistent zijn. ### Chain of Thought -Vraag het model zijn redenering stap voor stap te laten zien. In plaats van direct een antwoord te geven, breekt het model het probleem af en werkt het expliciet door elke stap heen. Dit verbetert de nauwkeurigheid bij wiskunde, logica en meerstaps redeneertaken. +Vraag het model om zijn redenering stap voor stap te tonen. In plaats van direct met een antwoord te komen, breekt het model het probleem op en werkt elk deel expliciet uit. Dit verhoogt de nauwkeurigheid bij wiskundige, logische en meervoudige stap redeneringstaken. Chain of Thought Prompting -*Stap-voor-stap redeneren — complexe problemen opdelen in expliciete logische stappen* +*Stap-voor-stap redenering — complexe problemen opdelen in expliciete, logische stappen* ```java String prompt = """ @@ -130,16 +130,16 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Het model toont: 15 - 8 = 7, dan 7 + 12 = 19 appels +// Het model laat zien: 15 - 8 = 7, daarna 7 + 12 = 19 appels ``` -**Wanneer te gebruiken:** Wiskundeproblemen, logische puzzels, debugging of elke taak waarbij het tonen van de redeneercyclus de nauwkeurigheid en vertrouwen verhoogt. +**Wanneer te gebruiken:** Wiskundeproblemen, logische puzzels, debugging, of elke taak waarbij het tonen van het redeneerproces de nauwkeurigheid en het vertrouwen verbetert. -### Rolgebaseerd Prompting +### Role-Based Prompting -Stel een persona of rol in voor de AI voordat je je vraag stelt. Dit geeft context die de toon, diepgang, en focus van het antwoord vormgeeft. Een "software-architect" geeft anders advies dan een "junior developer" of een "security auditor". +Stel een persona of rol in voor de AI voordat je je vraag stelt. Dit biedt context die de toon, diepte en focus van het antwoord vormt. Een "software architect" geeft andere adviezen dan een "junior developer" of een "security auditor". -Rolgebaseerd Prompting +Role-Based Prompting *Context en persona instellen — dezelfde vraag krijgt een ander antwoord afhankelijk van de toegewezen rol* @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Wanneer te gebruiken:** Code-reviews, tutoring, domeinspecifieke analyse of wanneer je antwoorden wilt afgestemd op een bepaald expertise niveau of perspectief. +**Wanneer te gebruiken:** Code reviews, tutoring, domeinspecifieke analyses, of wanneer je antwoorden wilt die zijn afgestemd op een bepaald expertise niveau of perspectief. -### Prompt Sjablonen +### Prompt Templates -Maak herbruikbare prompts met variabele placeholders. In plaats van elke keer een nieuwe prompt te schrijven, definieer je één sjabloon en vul je verschillende waardes in. De `PromptTemplate` klasse van LangChain4j maakt dit eenvoudig met `{{variable}}` syntax. +Maak herbruikbare prompts met variabele placeholders. In plaats van elke keer een nieuwe prompt te schrijven, definieer je eenmaal een template en vul je verschillende waarden in. De `PromptTemplate` klasse van LangChain4j maakt dit gemakkelijk met `{{variable}}` syntaxis. -Prompt Sjablonen +Prompt Templates -*Herbruikbare prompts met variabele placeholders — één sjabloon, vele toepassingen* +*Herbruikbare prompts met variabele placeholders — één template, veel toepassingen* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Wanneer te gebruiken:** Herhaalde vragen met verschillende invoeren, batchverwerking, het bouwen van herbruikbare AI workflows, of elk scenario waarbij de promptstructuur hetzelfde blijft maar de data verandert. +**Wanneer te gebruiken:** Herhaalde queries met verschillende inputs, batch processing, het bouwen van herbruikbare AI workflows, of elke situatie waarin de promptstructuur hetzelfde blijft maar de data verandert. --- -Deze vijf fundamenten geven je een solide toolkit voor de meeste prompting taken. De rest van deze module bouwt daarop voort met **acht geavanceerde patronen** die de redeneerscontrole, zelfevaluatie en gestructureerde output capaciteiten van GPT-5.2 benutten. +Deze vijf fundamenten geven je een stevige toolkit voor de meeste prompting taken. De rest van deze module bouwt hierop voort met **acht geavanceerde patronen** die gebruikmaken van GPT-5.2’s redeneersturing, zelfevaluatie en gestructureerde output mogelijkheden. ## Geavanceerde Patronen -Met de fundamenten behandeld, gaan we nu naar de acht geavanceerde patronen die deze module uniek maken. Niet alle vraagstukken vereisen dezelfde aanpak. Sommige vragen hebben snelle antwoorden nodig, andere diepgaand denken. Sommige vragen vergen zichtbare redenering, andere alleen resultaten. Elk patroon hieronder is geoptimaliseerd voor een verschillend scenario — en de redeneerscontrole van GPT-5.2 maakt de verschillen nog duidelijker. +Met de fundamenten behandeld, gaan we naar de acht geavanceerde patronen die deze module uniek maken. Niet alle problemen vragen om dezelfde aanpak. Sommige vragen hebben snelle antwoorden nodig, andere diepgaande reflectie. Sommige vragen hebben zichtbare redenering nodig, andere alleen resultaten. Elk patroon hieronder is geoptimaliseerd voor een andere situatie — en GPT-5.2’s redeneersturing maakt de verschillen nog duidelijker. -Acht Prompt Engineering Patronen +Acht Prompting Patronen -*Overzicht van de acht prompt engineering patronen en hun gebruikssituaties* +*Overzicht van acht prompt engineering patronen en hun toepassingen* -GPT-5.2 voegt een extra dimensie toe aan deze patronen: *redeneerscontrole*. De schuifregelaar hieronder laat zien hoe je het denkvermogen van het model kunt aanpassen — van snelle, directe antwoorden tot diepe, grondige analyse. +GPT-5.2 voegt een extra dimensie toe aan deze patronen: *redeneersturing*. De schuifregelaar hieronder laat zien hoe je de denkinspanning van het model kunt aanpassen — van snelle, directe antwoorden tot diepgaande, grondige analyses. -Redeneerscontrole met GPT-5.2 +Redeneersturing met GPT-5.2 -*De redeneerscontrole van GPT-5.2 laat je specificeren hoeveel het model moet nadenken — van snel directe antwoorden tot diepgaande exploratie* +*GPT-5.2’s redeneersturing stelt je in staat te specificeren hoeveel het model moet nadenken — van snelle directe antwoorden tot diepgaande exploratie* -**Lage Begeerte (Snel & Gefocust)** - Voor eenvoudige vragen waar je snelle, directe antwoorden wilt. Het model doet minimale redenering - maximaal 2 stappen. Gebruik dit voor berekeningen, opzoeken of rechttoe rechtaan vragen. +**Lage Enthousiasme (Snel & Gericht)** - Voor eenvoudige vragen waarbij je snelle, directe antwoorden wilt. Het model doet minimale redenering - maximaal 2 stappen. Gebruik dit voor berekeningen, opzoeken of eenvoudige vragen. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Verken met GitHub Copilot:** Open [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) en vraag: -> - "Wat is het verschil tussen lage en hoge begeerte prompting patronen?" -> - "Hoe helpen de XML-tags in prompts om de reactie van de AI te structureren?" -> - "Wanneer gebruik ik zelfreflectie patronen versus directe instructie?" +> - "Wat is het verschil tussen lage en hoge enthousiasme promptpatronen?" +> - "Hoe helpen de XML-tags in prompts bij het structureren van het AI-antwoord?" +> - "Wanneer moet ik zelfreflectiepatronen gebruiken versus directe instructie?" -**Hoge Begeerte (Diep & Grondig)** - Voor complexe problemen waar je een uitgebreide analyse wilt. Het model onderzoekt grondig en toont gedetailleerde redenering. Gebruik dit voor systeemuontwerp, architectuurbeslissingen of diepgaand onderzoek. +**Hoge Enthousiasme (Diepgaand & Grondig)** - Voor complexe problemen waarbij je een uitgebreide analyse wilt. Het model onderzoekt grondig en toont gedetailleerde redenering. Gebruik dit voor systeemontwerp, architectuurbeslissingen of complex onderzoek. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Taakuitvoering (Stap-voor-Stap Voortgang)** - Voor meerstaps workflows. Het model geeft een upfront plan, beschrijft elke stap terwijl het werkt, en geeft een samenvatting. Gebruik dit voor migraties, implementaties, of elk meerstaps proces. +**Taakuitvoering (Stap-voor-stap voortgang)** - Voor workflows met meerdere stappen. Het model geeft eerst een plan, bespreekt elke stap tijdens uitvoering, en geeft een samenvatting aan het einde. Gebruik dit voor migraties, implementaties of elk multi-stap proces. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Chain-of-Thought prompting vraagt het model expliciet zijn redeneercyclus te tonen, wat de nauwkeurigheid bij complexe taken verbetert. De stap-voor-stap opsplitsing helpt zowel mensen als AI om de logica te begrijpen. +Chain-of-Thought prompting vraagt expliciet aan het model om het redeneerproces te tonen, wat de nauwkeurigheid bij complexe taken verbetert. De stap-voor-stap opsplitsing helpt zowel mensen als AI om de logica te begrijpen. > **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Vraag over dit patroon: > - "Hoe pas ik het taakuitvoeringspatroon aan voor langlopende operaties?" -> - "Wat zijn best practices voor het structureren van tool intro's in productieomgevingen?" +> - "Wat zijn best practices voor het structureren van tool-preambles in productieapplicaties?" > - "Hoe kan ik tussentijdse voortgangsupdates vastleggen en tonen in een UI?" Het onderstaande diagram illustreert deze Plan → Uitvoeren → Samenvatten workflow. Taakuitvoeringspatroon -*Plan → Uitvoeren → Samenvatten workflow voor meerstaps taken* +*Plan → Uitvoeren → Samenvatten workflow voor multi-stap taken* -**Zelfreflecterende Code** - Voor het genereren van productiekwaliteit code. Het model genereert code volgens productiestandaarden met correcte foutafhandeling. Gebruik dit bij het bouwen van nieuwe features of services. +**Zelfreflecterende Code** - Voor het genereren van code van productiekwaliteit. Het model genereert code volgens productiestandaarden met degelijke foutafhandeling. Gebruik dit bij het bouwen van nieuwe features of services. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Het onderstaande diagram toont deze iteratieve verbetercyclus — genereren, evalueren, zwakke punten identificeren, en verfijnen totdat de code voldoet aan de productiestandaarden. +Het onderstaande diagram toont deze iteratieve verbeterlus — genereren, evalueren, zwakke punten identificeren, en verfijnen totdat de code aan productiestandaarden voldoet. Zelfreflectiecyclus -*Iteratieve verbetercyclus - genereren, evalueren, problemen identificeren, verbeteren, herhalen* +*Iteratieve verbeterlus - genereren, evalueren, problemen identificeren, verbeteren, herhalen* -**Gestructureerde Analyse** - Voor consistente evaluatie. Het model beoordeelt code volgens een vast kader (correctheid, praktijken, prestaties, veiligheid, onderhoudbaarheid). Gebruik dit voor code reviews of kwaliteitsbeoordelingen. +**Gestructureerde Analyse** - Voor consistente evaluatie. Het model beoordeelt code aan de hand van een vast framework (correctheid, praktijken, prestaties, beveiliging, onderhoudbaarheid). Gebruik dit voor code reviews of kwaliteitsbeoordelingen. ```java String prompt = """ @@ -355,17 +355,17 @@ String response = chatModel.chat(prompt); ``` > **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Vraag over gestructureerde analyse: -> - "Hoe kan ik het analyse raamwerk aanpassen voor verschillende typen code reviews?" -> - "Wat is de beste manier om gestructureerde output programmatisch te parsen en erop te reageren?" -> - "Hoe zorg ik voor consistente ernstniveaus over verschillende review sessies heen?" +> - "Hoe kan ik het analyseframework aanpassen voor verschillende soorten code reviews?" +> - "Wat is de beste manier om gestructureerde output programmatisch te parseren en te verwerken?" +> - "Hoe zorg ik voor consistente ernstniveaus over verschillende review sessies?" -Het volgende diagram toont hoe dit gestructureerde kader een code review ordent in consistente categorieën met ernstniveaus. +Het volgende diagram toont hoe dit gestructureerde framework een code review organiseert in consistente categorieën met ernstniveaus. Gestructureerd Analysepatroon -*Kader voor consistente code reviews met ernstniveaus* +*Framework voor consistente code reviews met ernstniveaus* -**Multi-Turn Chat** - Voor gesprekken die context nodig hebben. Het model onthoudt eerdere berichten en bouwt daarop voort. Gebruik dit voor interactieve hulpsessies of complexe vraag & antwoord. +**Multi-Turn Chat** - Voor gesprekken die context nodig hebben. Het model onthoudt eerdere berichten en bouwt daarop voort. Gebruik dit voor interactieve hulpsessies of complexe Q&A. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Het onderstaande diagram visualiseert hoe de context van het gesprek zich opstapelt bij elke beurt en hoe dit relateert aan de tokenlimiet van het model. +Het onderstaande diagram visualiseert hoe gesprekscontext zich opbouwt met elke beurt en hoe dit zich verhoudt tot de tokenlimiet van het model. Contextgeheugen -*Hoe gesprekcontext zich opstapelt over meerdere beurten tot aan de tokenlimiet* -**Stapsgewijze Uitleg** - Voor problemen die zichtbare logica vereisen. Het model toont expliciete redenering voor elke stap. Gebruik dit voor wiskundige problemen, logische puzzels, of wanneer je het denkproces wilt begrijpen. +*Hoe gesprekcontext zich ophoopt over meerdere beurten tot het tokenlimiet wordt bereikt* + +**Stap-voor-Stap Redenering** - Voor problemen die zichtbare logica vereisen. Het model toont expliciete redenering voor elke stap. Gebruik dit voor wiskundeproblemen, logische puzzels, of wanneer je het denkproces wilt begrijpen. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Het onderstaande diagram illustreert hoe het model problemen opsplitst in expliciete, genummerde logische stappen. - -Stapsgewijs Patroon +Het onderstaande diagram toont hoe het model problemen opsplitst in expliciete, genummerde logische stappen. -*Problemen opsplitsen in expliciete logische stappen* +Stap-voor-Stap Patroon +*Problemen ontleden in expliciete logische stappen* -**Beperkte Output** - Voor antwoorden met specifieke formatteervereisten. Het model volgt strikt de format- en lengteregels. Gebruik dit voor samenvattingen of wanneer je een nauwkeurige outputstructuur nodig hebt. +**Beperkte output** - Voor reacties met specifieke formatteervereisten. Het model volgt strikt de format- en lengteregels. Gebruik dit voor samenvattingen of wanneer je een precies outputformaat nodig hebt. ```java String prompt = """ @@ -420,21 +420,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Het volgende diagram toont hoe beperkingen het model sturen om output te produceren die strikt voldoet aan jouw format- en lengtevereisten. +Het onderstaande diagram toont hoe beperkingen het model sturen om output te genereren die strikt voldoet aan jouw format- en lengteeisen. -Beperkt Output Patroon +Geconstrain Patternvoor Output -*Specifieke eisen aan format, lengte en structuur afdwingen* +*Het afdwingen van specifieke format-, lengte- en structuureisen* -## De Applicatie uitvoeren +## Start de applicatie -**Verifieer de deployment:** +**Controleer de deployment:** -Zorg ervoor dat het `.env` bestand aanwezig is in de hoofdmap met Azure-gegevens (gemaakt tijdens Module 01). Voer dit uit vanuit de modulemap (`02-prompt-engineering/`): +Zorg ervoor dat het `.env`-bestand aanwezig is in de hoofdmap met Azure-referenties (gemaakt tijdens Module 01). Voer dit uit vanuit de modulemap (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT tonen +cat ../.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT weergeven ``` **PowerShell:** @@ -444,16 +444,16 @@ Get-Content ..\.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT tonen **Start de applicatie:** -> **Opmerking:** Als je alle applicaties al gestart hebt met `./start-all.sh` vanuit de hoofdmap (zoals beschreven in Module 01), draait deze module al op poort 8083. Je kunt de onderstaande startopdrachten overslaan en direct naar http://localhost:8083 gaan. +> **Opmerking:** Als je alle applicaties al gestart hebt met `./start-all.sh` vanuit de hoofdmap (zoals beschreven in Module 01), draait deze module al op poort 8083. Je kunt de startcommando's hieronder overslaan en direct naar http://localhost:8083 gaan. -**Optie 1: Gebruik van Spring Boot Dashboard (Aanbevolen voor VS Code gebruikers)** +**Optie 1: Gebruik van Spring Boot Dashboard (Aanbevolen voor VS Code-gebruikers)** -De dev container bevat de Spring Boot Dashboard extensie, die een visuele interface biedt om alle Spring Boot applicaties te beheren. Je vindt deze in de Activity Bar aan de linkerkant van VS Code (zoek naar het Spring Boot icoon). +De dev container bevat de Spring Boot Dashboard-extensie, die een visuele interface biedt om alle Spring Boot-applicaties te beheren. Je vindt deze in de Activiteitenbalk aan de linkerkant van VS Code (zoek naar het Spring Boot-pictogram). -Vanuit het Spring Boot Dashboard kun je: -- Alle beschikbare Spring Boot applicaties in de werkruimte zien -- Applicaties starten/stoppen met één klik -- Applicatielogs in real-time bekijken +Vanaf het Spring Boot Dashboard kun je: +- Alle beschikbare Spring Boot-applicaties in de werkruimte zien +- Applicaties met één klik starten/stoppen +- Applicatielogs realtime bekijken - Applicatiestatus monitoren Klik simpelweg op de afspeelknop naast "prompt-engineering" om deze module te starten, of start alle modules tegelijk. @@ -462,13 +462,13 @@ Klik simpelweg op de afspeelknop naast "prompt-engineering" om deze module te st *Het Spring Boot Dashboard in VS Code — start, stop en monitor alle modules vanaf één plek* -**Optie 2: Gebruik van shell scripts** +**Optie 2: Gebruik van shell-scripts** -Start alle webapplicaties (modules 01-04): +Start alle webapplicaties (modules 01–04): **Bash:** ```bash -cd .. # Vanuit de root directory +cd .. # Vanaf de rootdirectory ./start-all.sh ``` @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Beide scripts laden automatisch omgevingsvariabelen uit het `.env` bestand in de hoofdmap en bouwen de JAR bestanden als deze nog niet bestaan. +Beide scripts laden automatisch omgevingsvariabelen vanuit het root `.env`-bestand en bouwen de JARs indien deze nog niet bestaan. -> **Opmerking:** Als je alle modules liever handmatig bouwt voordat je start: +> **Opmerking:** Als je de voorkeur geeft aan handmatig bouwen van alle modules vóór het starten: > > **Bash:** > ```bash @@ -526,83 +526,83 @@ cd .. && ./stop-all.sh # Alle modules cd ..; .\stop-all.ps1 # Alle modules ``` -## Applicatie Screenshots +## Applicatieschermen -Hier is de hoofdinterface van de prompt engineering module, waar je met alle acht patronen tegelijk kunt experimenteren. +Hier is de hoofdinterface van de prompt engineering-module, waar je met alle acht patronen naast elkaar kunt experimenteren. Dashboard Home -*Het hoofd dashboard toont alle 8 prompt engineering patronen met hun kenmerken en gebruikssituaties* +*Het hoofd dashboard met alle 8 prompt engineering-patronen met hun kenmerken en toepassingsgevallen* -## Het verkennen van de Patronen +## Patronen verkennen -De webinterface laat je experimenteren met verschillende prompting strategieën. Elk patroon lost andere problemen op – probeer ze uit om te zien wanneer elke aanpak uitblinkt. +De webinterface laat je experimenteren met verschillende promptstrategieën. Elk patroon lost andere problemen op – probeer ze om te zien wanneer welk patroon het beste werkt. -> **Opmerking: Streaming versus Non-Streaming** — Elke patroonpagina biedt twee knoppen: **🔴 Stream Response (Live)** en een **Non-streaming** optie. Streaming gebruikt Server-Sent Events (SSE) om tokens in real-time weer te geven terwijl het model ze genereert, zodat je direct voortgang ziet. De non-streaming optie wacht totdat de hele reactie compleet is voordat deze getoond wordt. Voor prompts die diepgaande redenering triggeren (bijv. High Eagerness, Self-Reflecting Code) kan de non-streaming oproep erg lang duren – soms minuten – zonder zichtbare feedback. **Gebruik streaming bij experimenteren met complexe prompts** zodat je het model aan het werk ziet en de indruk van een time-out voorkomt. +> **Opmerking: Streaming versus niet-streaming** — Elke patroonpagina biedt twee knoppen: **🔴 Stream Response (Live)** en een **Niet-streaming** optie. Streaming gebruikt Server-Sent Events (SSE) om tokens realtime te tonen terwijl het model ze genereert, zodat je direct voortgang ziet. De niet-streaming optie wacht op het volledige antwoord voordat het wordt weergegeven. Voor prompts die diep redeneren vereisen (bijv. Hoge Enthousiasme, Zelfreflecterende Code), kan de niet-streaming call erg lang duren — soms minutenlang — zonder zichtbare feedback. **Gebruik streaming bij experimenteren met complexe prompts** zodat je het model ziet werken en niet de indruk krijgt dat het verzoek is verlopen. > -> **Opmerking: Browservereiste** — De streaming functie gebruikt de Fetch Streams API (`response.body.getReader()`) die een volledige browser vereist (Chrome, Edge, Firefox, Safari). Het werkt **niet** in de ingebouwde Simple Browser van VS Code, omdat de webview de ReadableStream API niet ondersteunt. Als je de Simple Browser gebruikt, werken de non-streaming knoppen wel normaal — alleen de streaming knoppen niet. Open `http://localhost:8083` in een externe browser voor de volledige ervaring. +> **Opmerking: Browservereiste** — De streamingfunctie gebruikt de Fetch Streams API (`response.body.getReader()`), welke een volledige browser vereist (Chrome, Edge, Firefox, Safari). Het werkt **niet** in de ingebouwde Simple Browser van VS Code, omdat de webview de ReadableStream API niet ondersteunt. Als je de Simple Browser gebruikt, werken de niet-streaming knoppen normaal — alleen de streamingknoppen zijn beperkt. Open `http://localhost:8083` in een externe browser voor de volledige ervaring. -### Lage versus Hoge Bereidheid +### Lage versus Hoge Enthousiasme -Stel een simpele vraag zoals "Wat is 15% van 200?" met Lage Bereidheid. Je krijgt een direct, snel antwoord. Stel nu iets complexers zoals "Ontwerp een caching strategie voor een drukke API" met Hoge Bereidheid. Klik op **🔴 Stream Response (Live)** en volg hoe het model gedetailleerde redeneringen token-voor-token laat zien. Zelfde model, zelfde vraagstructuur - maar de prompt vertelt hoeveel het moet nadenken. +Stel een eenvoudige vraag zoals "Wat is 15% van 200?" met Lage Enthousiasme. Je krijgt een direct, onmiddellijk antwoord. Stel nu iets complexers als "Ontwerp een cachingstrategie voor een drukbezochte API" met Hoge Enthousiasme. Klik op **🔴 Stream Response (Live)** en kijk hoe het model uitgebreid redeneert, token voor token. Zelfde model, zelfde vraagstructuur – maar de prompt vertelt hoeveel denkwerk het moet doen. ### Taakuitvoering (Tool Preambles) -Meerstaps workflows profiteren van vooraf plannen en voortgangsnarratie. Het model schetst wat het gaat doen, vertelt elke stap, en vat daarna de resultaten samen. +Workflows met meerdere stappen profiteren van vooraf plannen en voortgangsnarratie. Het model schetst wat het gaat doen, vertelt elke stap en vat de resultaten samen. ### Zelfreflecterende Code -Probeer "Maak een e-mail validatieservice". In plaats van alleen code te genereren en te stoppen, genereert het model, evalueert op kwaliteitseisen, identificeert zwaktes en verbetert. Je ziet hoe het iteratief doorgaat tot de code voldoet aan productie-eisen. +Probeer "Maak een e-mailvalidatieservice". In plaats van alleen code te genereren en te stoppen, genereert het model, beoordeelt op kwaliteitscriteria, identificeert zwakke punten en verbetert. Je ziet het itereren totdat de code aan productienormen voldoet. ### Gestructureerde Analyse -Code reviews vragen om consistente evaluatiekaders. Het model analyseert code met vaste categorieën (correctheid, praktijken, prestaties, beveiliging) met ernstniveaus. +Code reviews hebben consistente beoordelingskaders nodig. Het model analyseert code met vaste categorieën (correctheid, praktijk, prestaties, beveiliging) en ernstniveaus. -### Meerstaps Chat +### Meertraps Chat -Vraag "Wat is Spring Boot?" en volg meteen op met "Laat me een voorbeeld zien". Het model onthoudt je eerste vraag en geeft een voorbeeld dat bij Spring Boot past. Zonder geheugen zou die tweede vraag te vaag zijn. +Vraag "Wat is Spring Boot?" en volg direct op met "Geef mij een voorbeeld". Het model onthoudt je eerste vraag en geeft je specifiek een Spring Boot voorbeeld. Zonder geheugen zou die tweede vraag te vaag zijn. -### Stapsgewijze Redenering +### Stap-voor-stap Redenering -Kies een wiskundeprobleem en probeer het met Stapsgewijze Redenering en Lage Bereidheid. Lage bereidheid geeft alleen het antwoord – snel maar ondoorzichtig. Stapsgewijs laat elke berekening en beslissing zien. +Kies een wiskundig probleem en probeer het met zowel Stap-voor-stap Redenering als Lage Enthousiasme. Lage enthousiasme geeft alleen het antwoord – snel maar ondoorzichtig. Stap-voor-stap laat elke berekening en beslissing zien. ### Beperkte Output -Als je specifieke formaten of woordenaantallen nodig hebt, dwingt dit patroon strikte naleving af. Probeer een samenvatting te genereren van precies 100 woorden in bullet points. +Als je specifieke formaten of woordenaantallen nodig hebt, zorgt dit patroon voor strikte naleving. Probeer een samenvatting te genereren met precies 100 woorden in bulletpoints. -## Wat je Echt Leert +## Wat Je Eigenlijk Leert -**Redeneringsinspanning Verandert Alles** +**Redeneerinspanning Verandert Alles** -GPT-5.2 laat je de rekeninspanning sturen via je prompts. Lage inspanning betekent snelle reacties met minimale exploratie. Hoge inspanning betekent dat het model de tijd neemt om diep na te denken. Je leert de inspanning afstemmen op de taakcomplexiteit - verspil geen tijd aan simpele vragen, maar haast complexe beslissingen ook niet. +GPT-5.2 laat je de rekeninspanning sturen via je prompts. Lage inspanning betekent snelle antwoorden met minimale exploratie. Hoge inspanning betekent dat het model veel tijd neemt om diep te denken. Je leert de inspanning af te stemmen op de complexiteit van de taak – verspil geen tijd aan simpele vragen, maar wees ook niet gehaast bij complexe beslissingen. **Structuur Stuurt Gedrag** -Valt het je op dat prompts XML-tags bevatten? Die zijn niet decoratief. Modellen volgen gestructureerde instructies betrouwbaarder dan vrije tekst. Als je meerstaps processen of complexe logica nodig hebt, helpt structuur het model bij te houden waar het is en wat volgt. Het diagram hieronder ontleedt een goed gestructureerde prompt met tags zoals ``, ``, ``, ``, en `` die je instructies in duidelijke secties ordenen. +Zie je de XML-tags in de prompts? Die zijn niet decoratief. Modellen volgen gestructureerde instructies betrouwbaarder dan vrije tekst. Als je meerstapsprocessen of complexe logica nodig hebt, helpt structuur het model te volgen waar het is en wat erna komt. Het onderstaande diagram analyseert een goed gestructureerde prompt, waarin tags als ``, ``, ``, ``, en `` je instructies in duidelijke secties organiseren. -Prompt Structuur +Promptstructuur -*Anatomie van een goed gestructureerde prompt met duidelijke secties en XML-stijl organisatie* +*Anatomie van een goed gestructureerde prompt met duidelijke secties en XML-achtige organisatie* **Kwaliteit Door Zelfevaluatie** -De zelfreflecterende patronen maken kwaliteitscriteria expliciet. In plaats van te hopen dat het model "het goed doet", vertel je precies wat "goed" betekent: correcte logica, foutafhandeling, prestaties, beveiliging. Het model kan zo zijn eigen output evalueren en verbeteren. Dit maakt codegeneratie van een loterij tot een proces. +De zelfreflecterende patronen werken door kwaliteitscriteria expliciet te maken. In plaats van te hopen dat het model "het goed doet", vertel je precies wat "goed" betekent: correcte logica, foutafhandeling, prestaties, beveiliging. Het model kan dan zijn eigen output beoordelen en verbeteren. Dit verandert codegeneratie van een loterij in een proces. -**Context is Beperkt** +**Context Is Beperkt** -Meerstapsgesprekken werken door het opnemen van berichtgeschiedenis bij elke aanvraag. Maar er is een limiet – elk model heeft een maximum aantal tokens. Naarmate gesprekken groeien, heb je strategieën nodig om relevante context te bewaren zonder dat plafond te raken. Deze module laat zien hoe geheugen werkt; later leer je wanneer samenvatten, wanneer vergeten, en wanneer ophalen nodig is. +Meertrapsgesprekken werken door de berichtgeschiedenis bij elke aanvraag te voegen. Maar er is een limiet – elk model heeft een maximum aantal tokens. Naarmate gesprekken langer worden, heb je strategieën nodig om relevante context te behouden zonder die limiet te overschrijden. Deze module laat je zien hoe geheugen werkt; later leer je wanneer samenvatten, vergeten en ophalen zinvol is. ## Volgende Stappen -**Volgende Module:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**Volgende module:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigatie:** [← Vorige: Module 01 - Introductie](../01-introduction/README.md) | [Terug naar Main](../README.md) | [Volgende: Module 03 - RAG →](../03-rag/README.md) +**Navigatie:** [← Vorige: Module 01 - Introductie](../01-introduction/README.md) | [Terug naar Hoofdmenu](../README.md) | [Volgende: Module 03 - RAG →](../03-rag/README.md) --- -**Disclaimer**: -Dit document is vertaald met behulp van de AI-vertalingsdienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal dient als de gezaghebbende bron te worden beschouwd. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties voortvloeiend uit het gebruik van deze vertaling. +**Disclaimer**: +Dit document is vertaald met behulp van de AI vertaaldienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. \ No newline at end of file diff --git a/translations/nl/03-rag/README.md b/translations/nl/03-rag/README.md index 9c90f6562..c7c988398 100644 --- a/translations/nl/03-rag/README.md +++ b/translations/nl/03-rag/README.md @@ -2,143 +2,142 @@ ## Inhoudsopgave -- [Video Walkthrough](../../../03-rag) -- [Wat Je Zal Leren](../../../03-rag) -- [Vereisten](../../../03-rag) -- [RAG Begrijpen](../../../03-rag) - - [Welke RAG Benadering Gebruikt Deze Tutorial?](../../../03-rag) -- [Hoe Het Werkt](../../../03-rag) - - [Documentverwerking](../../../03-rag) - - [Embeddings Maken](../../../03-rag) - - [Semantische Zoekopdracht](../../../03-rag) - - [Antwoordsynthese](../../../03-rag) -- [De Applicatie Uitvoeren](../../../03-rag) -- [De Applicatie Gebruiken](../../../03-rag) - - [Upload een Document](../../../03-rag) - - [Stel Vragen](../../../03-rag) - - [Controleer Bronverwijzingen](../../../03-rag) - - [Experimenteer met Vragen](../../../03-rag) -- [Belangrijke Concepten](../../../03-rag) - - [Chunking Strategie](../../../03-rag) - - [Gelijkenisscores](../../../03-rag) - - [In-Memory Opslag](../../../03-rag) - - [Contextvensterbeheer](../../../03-rag) -- [Wanneer RAG Relevant Is](../../../03-rag) -- [Volgende Stappen](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [Wat Je Zal Leren](#wat-je-zal-leren) +- [Vereisten](#vereisten) +- [RAG Begrijpen](#rag-begrijpen) + - [Welke RAG Aanpak Gebruikt Deze Tutorial?](#welke-rag-aanpak-gebruikt-deze-tutorial) +- [Hoe Het Werkt](#hoe-het-werkt) + - [Documentverwerking](#documentverwerking) + - [Embeddings Maken](#embeddings-maken) + - [Semantisch Zoeken](#semantisch-zoeken) + - [Antwoordgeneratie](#antwoord-generatie) +- [De Applicatie Uitvoeren](#de-applicatie-starten) +- [De Applicatie Gebruiken](#de-applicatie-gebruiken) + - [Upload Een Document](#upload-een-document) + - [Stel Vragen](#stel-vragen) + - [Controleer Bronverwijzingen](#controleer-bronverwijzingen) + - [Experimenteer met Vragen](#experimenteer-met-vragen) +- [Belangrijke Concepten](#kernconcepten) + - [Chunking Strategie](#chunking-strategie) + - [Similariteit Scores](#similariteitscores) + - [In-Memory Opslag](#in-memory-opslag) + - [Contextvenster Beheer](#contextvensterbeheer) +- [Wanneer RAG Belangrijk Is](#wanneer-rag-belangrijk-is) +- [Volgende Stappen](#volgende-stappen) ## Video Walkthrough -Bekijk deze live sessie die uitlegt hoe te beginnen met deze module: +Bekijk deze live sessie die uitlegt hoe je aan de slag gaat met deze module: -RAG met LangChain4j - Live Sessie +RAG with LangChain4j - Live Session ## Wat Je Zal Leren -In de vorige modules leerde je hoe je gesprekken met AI voert en je prompts effectief structureert. Maar er is een fundamentele beperking: taalmodellen kennen alleen wat ze tijdens het trainen leerden. Ze kunnen geen vragen beantwoorden over het beleid van jouw bedrijf, je projectdocumentatie of informatie waar ze niet op getraind zijn. +In de vorige modules heb je geleerd hoe je gesprekken voert met AI en je prompts effectief structureert. Maar er is een fundamentele beperking: taalmodellen weten alleen wat ze tijdens de training geleerd hebben. Ze kunnen geen vragen beantwoorden over het beleid van je bedrijf, je projectdocumentatie of enige informatie waarop ze niet getraind zijn. -RAG (Retrieval-Augmented Generation) lost dit probleem op. In plaats van het model jouw informatie te proberen leren (wat duur en onpraktisch is), geef je het de mogelijkheid om door je documenten te zoeken. Wanneer iemand een vraag stelt, vindt het systeem relevante informatie en voegt die toe aan de prompt. Het model geeft vervolgens een antwoord op basis van die opgehaalde context. +RAG (Retrieval-Augmented Generation) lost dit probleem op. In plaats van te proberen het model je informatie te leren (wat duur en onpraktisch is), geef je het de mogelijkheid om door je documenten te zoeken. Wanneer iemand een vraag stelt, vindt het systeem relevante informatie en voegt die toe aan de prompt. Het model beantwoordt dan op basis van die opgehaalde context. -Zie RAG als het geven van een referentiebibliotheek aan het model. Wanneer je een vraag stelt, doet het systeem: +Zie RAG als het geven van een referentiebibliotheek aan het model. Wanneer je een vraag stelt, doet het systeem het volgende: -1. **Gebruikersvraag** – Je stelt een vraag -2. **Embedding** – Zet je vraag om in een vector -3. **Vectorzoekopdracht** – Vindt vergelijkbare documentstukken -4. **Context Samenstelling** – Voegt relevante stukken toe aan de prompt -5. **Respons** – Het LLM genereert een antwoord gebaseerd op de context +1. **Gebruikersvraag** - Je stelt een vraag +2. **Embedding** - Zet je vraag om in een vector +3. **Vectorzoektocht** - Vindt vergelijkbare documentstukken +4. **Context Samenstellen** - Voegt relevante stukken toe aan de prompt +5. **Antwoord** - LLM genereert een antwoord op basis van de context -Dit zorgt ervoor dat de antwoorden van het model zijn geworteld in je eigen data in plaats van te vertrouwen op de kennis uit de training of zelf verzonnen antwoorden. +Dit baseert de antwoorden van het model op jouw daadwerkelijke data in plaats van te vertrouwen op trainingskennis of zelf antwoorden te verzinnen. ## Vereisten -- Voltooide [Module 00 - Snelle Start](../00-quick-start/README.md) (voor het Easy RAG voorbeeld dat later in deze module wordt genoemd) -- Voltooide [Module 01 - Introductie](../01-introduction/README.md) (Azure OpenAI bronnen gedeployed, inclusief het `text-embedding-3-small` embedding model) -- `.env` bestand in de rootmap met Azure referenties (gemaakt door `azd up` in Module 01) +- Voltooide [Module 01 - Introductie](../01-introduction/README.md) (Azure OpenAI resources gedeployed, inclusief het `text-embedding-3-small` embedding model) +- `.env` bestand in de rootmap met Azure-gegevens (aangemaakt door `azd up` in Module 01) -> **Opmerking:** Als je Module 01 nog niet hebt voltooid, volg dan eerst de deploy-instructies daar. Het commando `azd up` deployt zowel het GPT chatmodel als het embeddingmodel dat in deze module gebruikt wordt. +> **Opmerking:** Als je Module 01 niet hebt voltooid, volg dan eerst de implementatie-instructies daar. Het `azd up` commando zet zowel het GPT chatmodel als het embedding model, gebruikt in deze module, uit. ## RAG Begrijpen -De onderstaande afbeelding illustreert het kernconcept: in plaats van alleen te vertrouwen op de trainingsdata van het model, geeft RAG het een referentiebibliotheek van jouw documenten om te raadplegen voordat het een antwoord genereert. +De onderstaande afbeelding illustreert het kernconcept: in plaats van alleen te vertrouwen op de trainingsdata van het model, geeft RAG het een referentiebibliotheek van je documenten om te raadplegen voordat het een antwoord genereert. -Wat is RAG +What is RAG -*Dit diagram toont het verschil tussen een standaard LLM (dat gokt op basis van trainingsdata) en een RAG-versterkt LLM (dat eerst je documenten raadpleegt).* +*Deze afbeelding toont het verschil tussen een standaard LLM (die gokt op basis van trainingsdata) en een RAG-verbeterd LLM (die eerst je documenten raadpleegt).* -Hier zie je hoe de onderdelen end-to-end met elkaar verbonden zijn. De vraag van een gebruiker doorloopt vier fasen — embedding, vectorzoekopdracht, contextsamenstelling en antwoordsynthese — die elk voortbouwen op de vorige: +Hier zie je hoe de onderdelen end-to-end verbonden zijn. De vraag van een gebruiker stroomt door vier fasen — embedding, vectorzoektocht, contextsamenstelling en antwoordgeneratie — elk bouwt voort op de vorige: -RAG Architectuur +RAG Architecture -*Dit diagram toont de end-to-end RAG pipeline — een gebruikersvraag doorloopt embedding, vectorzoekopdracht, contextsamenstelling en antwoordsynthese.* +*Deze afbeelding toont de end-to-end RAG-pijplijn — een gebruikersvraag stroomt door embedding, vectorzoektocht, contextsamenstelling en antwoordgeneratie.* -De rest van deze module behandelt elke fase in detail, met code die je kunt uitvoeren en aanpassen. +De rest van deze module doorloopt elke fase in detail, met code die je kunt uitvoeren en aanpassen. -### Welke RAG Benadering Gebruikt Deze Tutorial? +### Welke RAG Aanpak Gebruikt Deze Tutorial? LangChain4j biedt drie manieren om RAG te implementeren, elk met een ander abstractieniveau. De onderstaande afbeelding vergelijkt ze naast elkaar: -Drie RAG Benaderingen in LangChain4j +Three RAG Approaches in LangChain4j -*Dit diagram vergelijkt de drie LangChain4j RAG benaderingen — Easy, Native, en Advanced — en toont hun belangrijkste componenten en wanneer je ze gebruikt.* +*Deze afbeelding vergelijkt de drie LangChain4j RAG-aanpakken — Easy, Native en Advanced — met hun belangrijkste componenten en wanneer je ze gebruikt.* -| Benadering | Wat Het Doet | Afweging | +| Aanpak | Wat Het Doet | Afweging | |---|---|---| -| **Easy RAG** | Verbindt alles automatisch via `AiServices` en `ContentRetriever`. Je annoteert een interface, koppelt een retriever, en LangChain4j verzorgt embedding, zoeken en prompt samenstelling achter de schermen. | Minimale code, maar je ziet niet wat er in elke stap gebeurt. | -| **Native RAG** | Je roept zelf het embeddingmodel aan, zoekt in de opslag, bouwt de prompt en genereert het antwoord — expliciet stap voor stap. | Meer code, maar elke fase is zichtbaar en aanpasbaar. | -| **Advanced RAG** | Gebruikt het `RetrievalAugmentor` framework met inplugbare querytransformators, routers, herordenaars en inkjes van content voor productieklare pipelines. | Maximale flexibiliteit, maar aanzienlijk complexer. | +| **Easy RAG** | Verbindt alles automatisch via `AiServices` en `ContentRetriever`. Je annoteert een interface, koppelt een retriever en LangChain4j handelt embedding, zoeken en promptopbouw achter de schermen af. | Minimaal code, maar je ziet niet wat er bij elke stap gebeurt. | +| **Native RAG** | Je roept het embeddingmodel aan, zoekt in de opslag, bouwt de prompt en genereert zelf het antwoord — expliciet stap voor stap. | Meer code, maar elke fase is zichtbaar en aanpasbaar. | +| **Advanced RAG** | Gebruikt het `RetrievalAugmentor`-framework met inplugbare querytransformers, routers, herbeoordelaars en inhoudsinjectoren voor productieklare pijplijnen. | Maximale flexibiliteit, maar aanzienlijk meer complexiteit. | -**Deze tutorial gebruikt de Native benadering.** Elke stap van de RAG pipeline — embedding van de query, zoeken in de vectoropslag, samenstellen van de context en antwoorden genereren — wordt expliciet geschreven in [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Dit is bewust: als leerbron is het belangrijker dat je elke stap ziet en begrijpt dan dat de code zo kort mogelijk is. Zodra je vertrouwd bent met hoe de onderdelen samenwerken, kun je overstappen op Easy RAG voor snelle prototypes of Advanced RAG voor productiesystemen. +**Deze tutorial gebruikt de Native aanpak.** Elke stap van de RAG-pijplijn — het embedden van de query, zoeken in de vectoropslag, assembleren van de context en genereren van het antwoord — is expliciet uitgeschreven in [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Dit is bewust zo: als leerresource is het belangrijker dat je elke fase ziet en begrijpt dan dat de code minimaal is. Zodra je vertrouwd bent met hoe de onderdelen samenwerken, kun je overstappen naar Easy RAG voor snelle prototypes of Advanced RAG voor productiesystemen. -> **💡 Easy RAG al eens gezien?** De [Snelle Start module](../00-quick-start/README.md) bevat een Document Q&A voorbeeld ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) dat Easy RAG gebruikt — LangChain4j verzorgt embedding, zoeken en prompt assemblage automatisch. Deze module gaat een stap verder door die pipeline open te breken zodat je elke fase ziet en zelf beheert. +> **💡 Benieuwd naar Easy RAG?** LangChain4j biedt ook een *Easy RAG* aanpak waarbij `AiServices` en een `ContentRetriever` automatisch embedding, zoeken en promptopbouw beheren. Deze module kiest de expliciete weg — waarbij die pijplijn wordt opengemaakt zodat je elke fase zelf kunt zien en aansturen. -De onderstaande afbeelding toont de Easy RAG pipeline van dat Quick Start voorbeeld. Let op hoe `AiServices` en `EmbeddingStoreContentRetriever` alle complexiteit verbergen — je laadt een document, koppelt een retriever, en krijgt antwoorden. De Native benadering in deze module breekt elk van die verborgen stappen open: +De onderstaande afbeelding toont de Easy RAG-pijplijn. Let op hoe `AiServices` en `EmbeddingStoreContentRetriever` alle complexiteit verbergen — je laadt een document, koppelt een retriever en krijgt antwoorden. De Native aanpak in deze module maakt elk van die verborgen stappen open: Easy RAG Pipeline - LangChain4j -*Dit diagram toont de Easy RAG pipeline uit `SimpleReaderDemo.java`. Vergelijk dit met de Native benadering in deze module: Easy RAG verbergt embedding, ophalen en promptassemblage achter `AiServices` en `ContentRetriever` — je laadt een document, koppelt een retriever en krijgt antwoorden. De Native benadering breekt die pipeline open zodat je elke fase zelf aanroept (embed, zoek, context samenstellen, genereer), wat vol zichtbaarheid en controle geeft.* +*Deze afbeelding toont de Easy RAG-pijplijn. Vergelijk dit met de Native aanpak gebruikt in deze module: Easy RAG verbergt embedding, ophalen en promptopbouw achter `AiServices` en `ContentRetriever` — je laadt een document, koppelt een retriever en krijgt antwoorden. De Native aanpak in deze module maakt die pijplijn open zodat je elke stap (embed, zoek, stel context samen, genereer) zelf aanroept, wat volledige zichtbaarheid en controle geeft.* ## Hoe Het Werkt -De RAG pipeline in deze module is opgedeeld in vier fasen die achtereenvolgens lopen elke keer dat een gebruiker een vraag stelt. Eerst wordt een geüpload document **geparsed en gefragmenteerd** in hanteerbare stukken. Die stukken worden vervolgens omgezet in **vector-embeddings** en opgeslagen zodat ze wiskundig vergeleken kunnen worden. Wanneer een query binnenkomt, voert het systeem een **semantische zoekopdracht** uit om de meest relevante stukken te vinden, en tenslotte geeft het die als context mee aan het LLM voor **antwoordsynthese**. Hieronder lopen we elke fase door met de werkelijke code en diagrammen. Laten we eerst stap één bekijken. +De RAG-pijplijn in deze module bestaat uit vier fasen die telkens opeenvolgend lopen als een gebruiker een vraag stelt. Eerst wordt een geüpload document **geparseerd en opgedeeld** in hanteerbare stukken. Die stukken worden vervolgens omgezet in **vectorembeddings** en opgeslagen zodat ze wiskundig vergeleken kunnen worden. Wanneer een vraag binnenkomt, voert het systeem een **semantische zoekopdracht** uit om de meest relevante stukken te vinden, en geeft die tenslotte door als context aan de LLM voor **antwoordgeneratie**. De onderstaande secties doorlopen elke fase met daadwerkelijke code en diagrammen. Laten we naar de eerste stap kijken. ### Documentverwerking [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Wanneer je een document uploadt, wordt het geparsed (PDF of platte tekst), worden er metadata toegevoegd zoals de bestandsnaam, en breekt het systeem het op in stukken — kleinere delen die comfortabel in het contextvenster van het model passen. Deze stukken overlappen iets zodat je geen context verliest op de grenzen. +Wanneer je een document uploadt, parsed het systeem dit (PDF of platte tekst), voegt metadata toe zoals de bestandsnaam, en verdeelt het document in stukken — kleinere segmenten die comfortabel in het contextvenster van het model passen. Deze stukken overlappen licht zodat er geen context verloren gaat op de grenzen. ```java -// Analyseer het geüploade bestand en wikkel het in een LangChain4j Document +// Parse het geüploade bestand en verpak het in een LangChain4j Document Document document = Document.from(content, metadata); -// Verdeel in stukken van 300 tokens met 30 tokens overlap +// Splits in stukken van 300 tokens met een overlap van 30 tokens DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -De onderstaande afbeelding toont hoe dit visueel werkt. Let op hoe elk stuk wat tokens deelt met zijn buren — de overlap van 30 tokens zorgt ervoor dat er geen belangrijke context tussen de kieren valt: +De onderstaande afbeelding toont hoe dit visueel werkt. Let op hoe elk stuk enkele tokens deelt met zijn buren — de overlap van 30 tokens zorgt ervoor dat geen belangrijke context tussen de mazen valt: -Document Fragmentatie +Document Chunking -*Dit diagram toont een document dat wordt verdeeld in 300-token stukken met 30-token overlap, waarbij de context bij de stukgrenzen behouden blijft.* +*Deze afbeelding toont een document opgesplitst in stukken van 300 tokens met 30 tokens overlap, die context aan de chunkgrenzen behoudt.* > **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) en vraag: -> - "Hoe splits LangChain4j documenten in stukken en waarom is overlap belangrijk?" -> - "Wat is de optimale stukgrootte voor verschillende documenttypen en waarom?" +> - "Hoe splitst LangChain4j documenten in stukken en waarom is overlap belangrijk?" +> - "Wat is de optimale chunksize voor verschillende documenten en waarom?" > - "Hoe ga ik om met documenten in meerdere talen of met speciale opmaak?" ### Embeddings Maken [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Elk stuk wordt omgezet in een numerieke representatie genaamd embedding — eigenlijk een converter van betekenis naar getallen. Het embeddingmodel is niet "intelligent" zoals een chatmodel; het kan geen instructies opvolgen, redeneren of vragen beantwoorden. Wat het wel kan, is tekst mappen naar een wiskundige ruimte waarin vergelijkbare betekenissen dicht bij elkaar liggen — "auto" dichtbij "voertuig", "terugbetalingsbeleid" dichtbij "geld terug". Zie een chatmodel als een persoon met wie je praat; een embeddingmodel is een supersnel archiveringssysteem. +Elk stuk wordt omgezet in een numerieke representatie, een embedding genoemd — in wezen een betekenis-naar-getallen-omzetter. Het embeddingmodel is niet “intelligent” zoals een chatmodel; het kan geen instructies volgen, redeneren of vragen beantwoorden. Wat het wel kan, is tekst in een wiskundige ruimte plaatsen waar vergelijkbare betekenissen dicht bij elkaar liggen — “auto” dicht bij “voertuig,” “terugbetalingsbeleid” dicht bij “mijn geld terug.” Zie een chatmodel als een persoon met wie je praat; een embeddingmodel is een extreem goed archiefsysteem. -De onderstaande afbeelding visualiseert dit concept — tekst gaat erin, numerieke vectoren komen eruit, en vergelijkbare betekenissen produceren nabijgelegen vectoren: +De onderstaande afbeelding visualiseert dit concept — tekst gaat erin, numerieke vectoren komen eruit, en gelijke betekenissen produceren nabijgelegen vectoren: -Concept Embedding Model +Embedding Model Concept -*Dit diagram toont hoe een embeddingmodel tekst omzet in numerieke vectoren, waarbij vergelijkbare betekenissen — zoals "auto" en "voertuig" — dicht bij elkaar liggen in vectorruimte.* +*Deze afbeelding toont hoe een embeddingmodel tekst omzet in numerieke vectoren, waarbij gelijke betekenissen — zoals "auto" en "voertuig" — dicht bij elkaar in de vectorruimte geplaatst worden.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Het klassendiagram hieronder toont de twee aparte stromen in een RAG pipeline en de LangChain4j klassen die ze implementeren. De **inname-stroom** (loopt één keer bij upload) splitst het document, embedt de stukken en slaat ze op via `.addAll()`. De **query-stroom** (loopt elke keer een gebruiker iets vraagt) embedt de vraag, zoekt in de opslag via `.search()`, en geeft de gevonden context door aan het chatmodel. Beiden komen samen bij de gedeelde `EmbeddingStore` interface: +Het klassendiagram hieronder toont de twee aparte stromen in een RAG-pijplijn en de LangChain4j-klassen die ze implementeren. De **inname-stroom** (loopt één keer bij upload) splitst het document, embedt de chunks en slaat ze op via `.addAll()`. De **query-stroom** (loopt elke keer als een gebruiker vraagt) embedt de vraag, zoekt in de opslag via `.search()`, en geeft de bijpassende context door aan het chatmodel. Beide stromen komen samen bij de gedeelde `EmbeddingStore` interface: -LangChain4j RAG Klassen +LangChain4j RAG Classes -*Dit diagram toont de twee stromen in een RAG pipeline — inname en query — en hoe ze verbonden zijn via een gedeelde EmbeddingStore.* +*Deze afbeelding toont de twee stromen in een RAG-pijplijn — inname en query — en hoe ze via een gedeelde EmbeddingStore verbonden zijn.* -Zodra embeddings opgeslagen zijn, clustert gelijkaardige inhoud vanzelf samen in vectorruimte. De onderstaande visualisatie toont hoe documenten over verwante onderwerpen als nabijgelegen punten eindigen, wat semantisch zoeken mogelijk maakt: +Zodra embeddings zijn opgeslagen, clustert vergelijkbare inhoud natuurlijk samen in vectorruimte. De onderstaande visualisatie toont hoe documenten over gerelateerde onderwerpen bijeen komen als nabijgelegen punten, wat semantisch zoeken mogelijk maakt: -Vector Embeddings Ruimte +Vector Embeddings Space -*Deze visualisatie toont hoe gerelateerde documenten clusteren in 3D vectorruimte, met onderwerpen als Technische Documentatie, Bedrijfsregels en FAQ's die aparte groepen vormen.* +*Deze visualisatie toont hoe gerelateerde documenten samenklonteren in 3D vectorruimte, met onderwerpen zoals Technische Docs, Bedrijfsregels en Veelgestelde Vragen als afzonderlijke groepen.* -Wanneer een gebruiker zoekt, doorloopt het systeem vier stappen: embed de documenten één keer, embed de query bij iedere zoekopdracht, vergelijk de queryvector met alle opgeslagen vectoren via cosinus gelijkenis, en retourneer de top-K hoogst scorende stukken. Het onderstaande diagram licht elke stap en de betrokken LangChain4j klassen toe: +Wanneer een gebruiker zoekt, volgt het systeem vier stappen: embed de documenten één keer, embed de query bij elke zoekopdracht, vergelijk de queryvector met alle opgeslagen vectoren met behulp van cosine similarity, en retourneer de top-K hoogst scorende stukken. De onderstaande afbeelding doorloopt elke stap en de betrokken LangChain4j-klassen: -Stappen Embed Ophalen +Embedding Search Steps -*Dit diagram toont het vier-stappen proces van embedding zoeken: embed documenten, embed de query, vergelijk vectoren met cosinus gelijkenis, en retourneer top-K resultaten.* +*Deze afbeelding toont het vierstappenproces van embedding search: embed documenten, embed de query, vergelijk vectoren met cosine similarity en geef de top-K resultaten terug.* -### Semantische Zoekopdracht +### Semantisch Zoeken [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Wanneer je een vraag stelt, wordt die vraag ook een embedding. Het systeem vergelijkt de embedding van je vraag met die van alle documentstukken. Het vindt de stukken met de meest vergelijkbare betekenissen — niet alleen exacte trefwoorden, maar echte semantische gelijkenis. +Wanneer je een vraag stelt, wordt die vraag ook omgezet in een embedding. Het systeem vergelijkt de embedding van je vraag met alle embeddings van de documentstukken. Het vindt de stukken met de meest vergelijkbare betekenissen - niet alleen hetzelfde zoekwoord, maar daadwerkelijke semantische gelijkenis. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Het onderstaande diagram vergelijkt semantisch zoeken met traditionele trefwoordzoekopdrachten. Een trefwoordzoekopdracht op "voertuig" mist een stuk over "auto's en vrachtwagens," maar semantisch zoeken begrijpt dat het hetzelfde betekent en geeft het als hoge-score resultaat terug: +De onderstaande afbeelding vergelijkt semantisch zoeken met traditioneel zoeken op sleutelwoorden. Een zoekopdracht op “voertuig” mist een stuk over “auto’s en vrachtwagens,” maar semantisch zoeken begrijpt dat ze hetzelfde betekenen en geeft het als een hoog scorende match terug: -Semantisch Zoeken +Semantic Search -*Dit diagram vergelijkt trefwoordgebaseerd zoeken met semantisch zoeken, en toont hoe semantisch zoeken conceptueel gerelateerde inhoud terugvindt, zelfs als precieze trefwoorden verschillen.* -Onder de motorkap wordt gelijkenis gemeten met behulp van cosinusgelijkenis — in wezen de vraag gesteld "wijzen deze twee pijlen in dezelfde richting?" Twee stukken kunnen totaal verschillende woorden gebruiken, maar als ze hetzelfde betekenen wijzen hun vectoren dezelfde kant op en scoren ze dicht bij 1,0: +*Deze afbeelding vergelijkt zoeken op sleutelwoorden met semantisch zoeken, waarbij semantisch zoeken conceptueel gerelateerde inhoud teruggeeft ook als exacte sleutelwoorden verschillen.* -Cosine Similarity +Onder de motorkap wordt gelijkenis gemeten met cosine similarity — in feite wordt gevraagd "wijzen deze twee pijlen in dezelfde richting?" Twee stukken kunnen totaal verschillende woorden gebruiken, maar als ze hetzelfde betekenen wijzen hun vectoren in dezelfde richting en scoren ze dicht bij 1.0: -*Dit diagram illustreert cosinusgelijkenis als de hoek tussen embedding-vectoren — meer uitgelijnde vectoren scoren dichter bij 1,0, wat duidt op hogere semantische gelijkenis.* +Cosine Similarity +*Dit diagram illustreert cosine similarity als de hoek tussen embedding-vectoren — meer uitgelijnde vectoren scoren dichter bij 1.0, wat een hogere semantische gelijkenis aangeeft.* > **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) en vraag: -> - "Hoe werkt gelijkenis zoeken met embeddings en wat bepaalt de score?" -> - "Welke gelijkenisdrempel moet ik gebruiken en hoe beïnvloedt dat de resultaten?" -> - "Hoe ga ik om met gevallen waarin geen relevante documenten worden gevonden?" +> - "Hoe werkt similarity search met embeddings en wat bepaalt de score?" +> - "Welke similariteitsdrempel moet ik gebruiken en hoe beïnvloedt dit de resultaten?" +> - "Hoe handel ik gevallen af waarin geen relevante documenten worden gevonden?" ### Antwoord Generatie [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -De meest relevante stukken worden samengevoegd in een gestructureerde prompt die expliciete instructies, de opgehaalde context en de vraag van de gebruiker bevat. Het model leest die specifieke stukken en geeft antwoord op basis van die informatie — het kan alleen gebruiken wat voor zich ligt, wat hallucinaties voorkomt. +De meest relevante chunks worden samengevoegd tot een gestructureerde prompt die expliciete instructies, de opgehaalde context en de vraag van de gebruiker bevat. Het model leest deze specifieke chunks en antwoordt op basis van die informatie — het kan alleen gebruiken wat voor hem ligt, wat hallucinaties voorkomt. ```java String context = matches.stream() @@ -237,21 +236,21 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Het onderstaande diagram toont deze samenstelling in actie — de best scorende stukken van de zoekstap worden ingevoegd in het prompttemplate, en het `OpenAiOfficialChatModel` genereert een gebaseerd antwoord: +Het onderstaande diagram toont deze samenstelling in actie — de chunks met de hoogste score uit de zoekstap worden geïnjecteerd in de promptsjabloon, en het `OpenAiOfficialChatModel` genereert een onderbouwd antwoord: Context Assembly -*Dit diagram laat zien hoe de best scorende stukken worden samengevoegd in een gestructureerde prompt, waardoor het model een op feiten gebaseerd antwoord uit jouw data kan genereren.* +*Dit diagram toont hoe de chunks met de hoogste score worden samengevoegd tot een gestructureerde prompt, zodat het model een onderbouwd antwoord kan genereren vanuit jouw data.* -## Start de Applicatie +## De Applicatie Starten -**Controleer de implementatie:** +**Controleer de deployment:** -Zorg dat het `.env`-bestand aanwezig is in de hoofdmap met Azure-inloggegevens (gemaakt tijdens Module 01). Voer dit uit vanuit de modulemap (`03-rag/`): +Zorg dat het `.env` bestand in de hoofdmap bestaat met Azure-gegevens (aangemaakt tijdens Module 01). Voer het volgende uit vanuit de modulemap (`03-rag/`): **Bash:** ```bash -cat ../.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT tonen +cat ../.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT weergeven ``` **PowerShell:** @@ -261,37 +260,37 @@ Get-Content ..\.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT tonen **Start de applicatie:** -> **Opmerking:** Als je alle applicaties al gestart hebt met `./start-all.sh` vanuit de hoofdmap (zoals beschreven in Module 01), draait deze module al op poort 8081. Je kunt de startcommando’s hieronder overslaan en direct naar http://localhost:8081 gaan. +> **Opmerking:** Als je alle applicaties al gestart hebt via `./start-all.sh` vanuit de hoofdmap (zoals beschreven in Module 01), draait deze module al op poort 8081. Je kunt de onderstaande startcommando's overslaan en direct naar http://localhost:8081 gaan. -**Optie 1: Gebruik Spring Boot Dashboard (Aanbevolen voor VS Code gebruikers)** +**Optie 1: Spring Boot Dashboard gebruiken (aanbevolen voor VS Code-gebruikers)** -De devcontainer bevat de Spring Boot Dashboard-extensie, die een visuele interface biedt om alle Spring Boot-applicaties te beheren. Je vindt deze in de Activiteitenbalk aan de linkerkant van VS Code (zoek naar het Spring Boot-icoon). +De devcontainer bevat de Spring Boot Dashboard-extensie, die een visuele interface biedt om alle Spring Boot-applicaties te beheren. Je vindt deze in de Activiteitenbalk links in VS Code (zoek het Spring Boot-icoon). -Vanaf het Spring Boot Dashboard kun je: -- Alle beschikbare Spring Boot-applicaties in de werkruimte zien -- Applicaties met één klik starten/stoppen +Via het Spring Boot Dashboard kun je: +- Alle beschikbare Spring Boot-applicaties in de workspace zien +- Applicaties starten/stoppen met één klik - Applicatielogs realtime bekijken - Applicatiestatus monitoren -Klik simpelweg op de afspeelknop naast "rag" om deze module te starten, of start alle modules tegelijk. +Klik simpelweg op de afspeelknop naast “rag” om deze module te starten, of start alle modules tegelijk. Spring Boot Dashboard *Deze schermafbeelding toont het Spring Boot Dashboard in VS Code, waar je applicaties visueel kunt starten, stoppen en monitoren.* -**Optie 2: Gebruik shell-scripts** +**Optie 2: Shell scripts gebruiken** Start alle webapplicaties (modules 01-04): **Bash:** ```bash -cd .. # Vanaf de root-directory +cd .. # Vanuit de hoofdmap ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Vanaf de root directory +cd .. # Vanaf rootdirectory .\start-all.ps1 ``` @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Beide scripts laden automatisch de omgevingsvariabelen uit het root `.env`-bestand en bouwen de JARs als deze nog niet bestaan. +Beide scripts laden automatisch omgevingsvariabelen uit het `.env` bestand in de hoofdmap en bouwen de JAR’s indien die nog niet bestaan. -> **Opmerking:** Als je liever handmatig alle modules bouwt vóór het starten: +> **Opmerking:** Als je liever alle modules handmatig bouwt voordat je start: > > **Bash:** > ```bash @@ -343,95 +342,95 @@ cd .. && ./stop-all.sh # Alle modules cd ..; .\stop-all.ps1 # Alle modules ``` -## Gebruik van de Applicatie +## De Applicatie Gebruiken De applicatie biedt een webinterface voor het uploaden van documenten en het stellen van vragen. RAG Application Interface -*Deze schermafbeelding toont de RAG-applicatie-interface waar je documenten uploadt en vragen stelt.* +*Deze schermafbeelding toont de RAG applicatie-interface waar je documenten uploadt en vragen stelt.* ### Upload een Document -Begin met het uploaden van een document — TXT-bestanden werken het beste voor testen. Er is een `sample-document.txt` beschikbaar in deze map met informatie over LangChain4j-functionaliteiten, RAG-implementatie en best practices — perfect om het systeem te testen. +Begin met het uploaden van een document - TXT-bestanden zijn het beste voor testen. Er is een `sample-document.txt` beschikbaar in deze map met informatie over LangChain4j features, RAG implementatie, en best practices - perfect om het systeem te testen. -Het systeem verwerkt je document, verdeelt het in stukken en maakt embeddings voor elk stuk. Dit gebeurt automatisch bij uploaden. +Het systeem verwerkt je document, splitst het in chunks en maakt embeddings voor elke chunk. Dit gebeurt automatisch bij het uploaden. ### Stel Vragen -Stel nu specifieke vragen over de inhoud van het document. Probeer iets feitelijk dat duidelijk in het document staat. Het systeem zoekt naar relevante stukken, voegt deze toe aan de prompt en genereert een antwoord. +Stel nu specifieke vragen over de inhoud van het document. Probeer iets feitelijks wat duidelijk in het document staat. Het systeem zoekt naar relevante chunks, verwerkt die in de prompt en genereert een antwoord. -### Controleer Bronnen +### Controleer Bronverwijzingen -Let erop dat elk antwoord bronverwijzingen bevat met gelijkenisscores. Deze scores (0 tot 1) tonen hoe relevant elk stuk was voor jouw vraag. Hogere scores betekenen betere overeenkomsten. Dit stelt je in staat het antwoord te verifiëren aan de hand van de bronmaterialen. +Merk op dat elk antwoord bronverwijzingen bevat met similariteitsscores. Deze scores (0 tot 1) tonen hoe relevant elke chunk was voor je vraag. Hogere scores betekenen betere overeenkomsten. Zo kun je het antwoord verifiëren met het bronmateriaal. RAG Query Results -*Deze schermafbeelding toont queryresultaten met het gegenereerde antwoord, bronverwijzingen en relevantiescores voor elk opgehaald stuk.* +*Deze screenshot toont queryresultaten met het gegenereerde antwoord, bronverwijzingen, en relevantiescores voor elke opgehaalde chunk.* ### Experimenteer met Vragen Probeer verschillende soorten vragen: -- Specifieke feiten: "Wat is het hoofdonderwerp?" -- Vergelijkingen: "Wat is het verschil tussen X en Y?" -- Samenvattingen: "Vat de belangrijkste punten over Z samen" +- Specifieke feiten: “Wat is het hoofdt onderwerp?” +- Vergelijkingen: “Wat is het verschil tussen X en Y?” +- Samenvattingen: “Vat de belangrijkste punten over Z samen” -Kijk hoe de relevantiescores veranderen op basis van hoe goed jouw vraag overeenkomt met de inhoud van het document. +Bekijk hoe de relevantiescores veranderen afhankelijk van hoe goed je vraag aansluit bij de documentinhoud. -## Kernbegrippen +## Kernconcepten ### Chunking Strategie -Documenten worden opgesplitst in stukken van 300 tokens met 30 tokens overlap. Deze balans zorgt ervoor dat elk stuk voldoende context heeft om betekenisvol te zijn en toch klein genoeg blijft om meerdere stukken in een prompt op te nemen. +Documenten worden opgedeeld in chunks van 300 tokens met een overlap van 30 tokens. Deze balans zorgt ervoor dat elke chunk voldoende context bevat om betekenisvol te zijn, terwijl ze klein genoeg blijven om meerdere chunks in een prompt op te nemen. -### Gelijkenisscores +### Similariteitscores -Elk opgehaald stuk heeft een gelijkenisscore tussen 0 en 1 die aangeeft hoe goed het aansluit op de vraag van de gebruiker. Het onderstaande diagram visualiseert de score-interval en hoe het systeem deze gebruikt om resultaten te filteren: +Elke opgehaalde chunk bevat een similariteitsscore tussen 0 en 1 die aangeeft hoe nauw deze overeenkomt met de vraag van de gebruiker. Het onderstaande diagram visualiseert de scorebereiken en hoe het systeem deze gebruikt om resultaten te filteren: Similarity Scores -*Dit diagram toont scorebereiken van 0 tot 1, met een minimumdrempel van 0,5 die irrelevante stukken filtert.* +*Dit diagram toont scorebereiken van 0 tot 1, met een minimumdrempel van 0.5 die irrelevante chunks filtert.* -Scores variëren van 0 tot 1: -- 0,7-1,0: Zeer relevant, exacte overeenkomst -- 0,5-0,7: Relevant, goede context -- Onder 0,5: Gefilterd, te verschillend +Scores lopen van 0 tot 1: +- 0.7-1.0: Zeer relevant, exacte match +- 0.5-0.7: Relevant, goede context +- Lager dan 0.5: Gefilterd, te verschillend -Het systeem haalt alleen stukken boven de minimale drempel op om kwaliteit te garanderen. +Het systeem haalt alleen chunks op boven de minimumdrempel om kwaliteit te waarborgen. -Embeddings werken goed wanneer betekenissen duidelijk clusteren, maar ze hebben blinde vlekken. Het onderstaande diagram toont de veelvoorkomende faalwijzen — stukken die te groot zijn produceren vage vectoren, stukken die te klein zijn missen context, dubbelzinnige termen wijzen naar meerdere clusters, en exacte-match zoekacties (IDs, serienummers) werken helemaal niet met embeddings: +Embeddings werken goed wanneer betekenissen duidelijk clusteren, maar hebben blinde vlekken. Het onderstaande diagram toont veelvoorkomende faalwijzen — te grote chunks produceren vage vectoren, te kleine chunks missen context, ambiguë termen wijzen naar meerdere clusters, en exact-match zoekopdrachten (ID’s, onderdelen nummers) werken helemaal niet met embeddings: Embedding Failure Modes -*Dit diagram toont veel voorkomende embedding-fouten: stukken die te groot zijn, stukken die te klein zijn, dubbelzinnige termen die naar meerdere clusters wijzen en exacte-match zoekacties zoals IDs.* +*Dit diagram toont veelvoorkomende faalwijzen bij embeddings: chunks zijn te groot, chunks zijn te klein, ambiguïteit verwijst naar meerdere clusters, en exact-match zoekopdrachten zoals ID’s.* ### In-Memory Opslag -Deze module gebruikt voor eenvoud in-memory opslag. Bij het herstarten van de applicatie gaan geüploade documenten verloren. Productiesystemen gebruiken persistente vectordatabases zoals Qdrant of Azure AI Search. +Deze module gebruikt geheugenopslag voor eenvoud. Bij herstart van de applicatie gaan geüploade documenten verloren. Productiesystemen gebruiken persistente vectordatabases zoals Qdrant of Azure AI Search. -### Context Window Beheer +### Contextvensterbeheer -Elk model heeft een maximale contextomvang. Je kunt niet elk stuk uit een groot document meenemen. Het systeem haalt de top N meest relevante stukken op (standaard 5) om binnen de limieten te blijven en toch voldoende context te bieden voor accurate antwoorden. +Elk model heeft een maximaal contextvenster. Je kunt niet elke chunk van een groot document in de prompt opnemen. Het systeem haalt de top N meest relevante chunks op (standaard 5) om binnen de limieten te blijven en toch voldoende context voor accurate antwoorden te bieden. -## Wanneer RAG Belangrijk is +## Wanneer RAG Belangrijk Is -RAG is niet altijd de juiste aanpak. De onderstaande beslisgids helpt bepalen wanneer RAG waarde toevoegt versus wanneer eenvoudigere benaderingen — zoals het direct opnemen van inhoud in de prompt of vertrouwen op de ingebouwde kennis van het model — volstaan: +RAG is niet altijd de juiste aanpak. De onderstaande beslisgids helpt te bepalen wanneer RAG waarde toevoegt versus wanneer simpelere methodes — zoals content direct in de prompt opnemen of vertrouwen op ingebouwde kennis van het model — voldoende zijn: When to Use RAG -*Dit diagram toont een beslisgids voor wanneer RAG waarde toevoegt tegenover wanneer eenvoudigere benaderingen voldoende zijn.* +*Dit diagram toont een beslisgids voor wanneer RAG waarde toevoegt versus wanneer simpelere benaderingen volstaan.* ## Volgende Stappen -**Volgende Module:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Volgende Module:** [04-tools - AI Agents met Tools](../04-tools/README.md) --- -**Navigatie:** [← Vorige: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Terug naar Hoofdmenu](../README.md) | [Volgende: Module 04 - Tools →](../04-tools/README.md) +**Navigatie:** [← Vorige: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Terug naar Hoofd](../README.md) | [Volgende: Module 04 - Tools →](../04-tools/README.md) --- **Disclaimer**: -Dit document is vertaald met behulp van de AI-vertalingsservice [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel wij streven naar nauwkeurigheid, dient u zich ervan bewust te zijn dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet als de gezaghebbende bron worden beschouwd. Voor cruciale informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. +Dit document is vertaald met behulp van de AI vertaaldienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. \ No newline at end of file diff --git a/translations/nl/04-tools/README.md b/translations/nl/04-tools/README.md index 10ec594ca..2aecde522 100644 --- a/translations/nl/04-tools/README.md +++ b/translations/nl/04-tools/README.md @@ -2,83 +2,83 @@ ## Inhoudsopgave -- [Video Walkthrough](../../../04-tools) -- [Wat je zult leren](../../../04-tools) -- [Vereisten](../../../04-tools) -- [Begrip van AI-agenten met Tools](../../../04-tools) -- [Hoe Tool-aanroepen werken](../../../04-tools) - - [Tooldefinities](../../../04-tools) - - [Besluitvorming](../../../04-tools) - - [Uitvoering](../../../04-tools) - - [Antwoordgeneratie](../../../04-tools) - - [Architectuur: Spring Boot Auto-Wiring](../../../04-tools) -- [Toolketting](../../../04-tools) -- [Start de applicatie](../../../04-tools) -- [Het gebruik van de applicatie](../../../04-tools) - - [Probeer eenvoudig toolgebruik](../../../04-tools) - - [Test toolketting](../../../04-tools) - - [Bekijk het conversatiestroom](../../../04-tools) - - [Experimenteer met verschillende verzoeken](../../../04-tools) -- [Belangrijke concepten](../../../04-tools) - - [ReAct-patroon (Redeneren en Handelen)](../../../04-tools) - - [Toolbeschrijvingen zijn belangrijk](../../../04-tools) - - [Sessiebeheer](../../../04-tools) - - [Foutafhandeling](../../../04-tools) -- [Beschikbare tools](../../../04-tools) -- [Wanneer gebruik je tool-gebaseerde agenten](../../../04-tools) -- [Tools versus RAG](../../../04-tools) -- [Volgende stappen](../../../04-tools) +- [Video Walkthrough](#video-walkthrough) +- [Wat je zult leren](#wat-je-zult-leren) +- [Vereisten](#vereisten) +- [Begrip van AI-agenten met Tools](#begrip-van-ai-agenten-met-tools) +- [Hoe Tool Calling Werkt](#hoe-tool-calling-werkt) + - [Tooldefinities](#tooldefinities) + - [Besluitvorming](#besluitvorming) + - [Uitvoering](#uitvoering) + - [Responsegeneratie](#responsegeneratie) + - [Architectuur: Spring Boot Auto-Wiring](#architectuur-spring-boot-auto-wiring) +- [Tool Chaining](#tool-chaining) +- [De Applicatie Uitvoeren](#de-applicatie-uitvoeren) +- [Gebruik van de Applicatie](#gebruik-van-de-applicatie) + - [Probeer simpele toolgebruik](#probeer-simpele-toolgebruik) + - [Test tool chaining](#test-tool-koppeling) + - [Bekijk het gesprekverloop](#bekijk-het-gesprekverloop) + - [Experimenteer met verschillende verzoeken](#experimenteer-met-verschillende-verzoeken) +- [Belangrijke Concepten](#belangrijke-concepten) + - [ReAct-patroon (Redeneren en Handelen)](#react-patroon-redeneren-en-handelen) + - [Beschrijvingen van Tools zijn Belangrijk](#beschrijvingen-van-tools-zijn-belangrijk) + - [Sessiebeheer](#sessiebeheer) + - [Foutenafhandeling](#foutenafhandeling) +- [Beschikbare Tools](#beschikbare-tools) +- [Wanneer te Gebruiken Tool-gebaseerde Agenten](#wanneer-te-gebruiken-tool-gebaseerde-agenten) +- [Tools vs RAG](#tools-versus-rag) +- [Volgende Stappen](#volgende-stappen) ## Video Walkthrough -Bekijk deze live sessie die uitlegt hoe je met deze module aan de slag gaat: +Bekijk deze live sessie die uitlegt hoe je aan de slag gaat met deze module: AI Agents with Tools and MCP - Live Session ## Wat je zult leren -Tot nu toe heb je geleerd hoe je gesprekken met AI voert, effectieve prompts structureert en antwoorden baseert op je documenten. Maar er is nog een fundamentele beperking: taalmodellen kunnen alleen tekst genereren. Ze kunnen het weer niet controleren, geen berekeningen uitvoeren, geen databases raadplegen of communiceren met externe systemen. +Tot nu toe heb je geleerd hoe je gesprekken voert met AI, prompts effectief structureert en antwoorden baseert op jouw documenten. Maar er is nog een fundamentele beperking: taalmodellen kunnen alleen tekst genereren. Ze kunnen het weer niet checken, geen berekeningen uitvoeren, geen databases bevragen of interacteren met externe systemen. -Tools veranderen dit. Door het model toegang te geven tot functies die het kan aanroepen, transformeer je het van een tekstgenerator naar een agent die acties kan ondernemen. Het model bepaalt wanneer het een tool nodig heeft, welke tool te gebruiken en welke parameters mee te geven. Jouw code voert de functie uit en geeft het resultaat terug. Het model verwerkt dat resultaat in zijn antwoord. +Tools veranderen dit. Door het model toegang te geven tot functies die het kan aanroepen, verander je het van een tekstgenerator in een agent die acties kan ondernemen. Het model besluit wanneer het een tool nodig heeft, welke tool te gebruiken en welke parameters te geven. Jouw code voert de functie uit en retourneert het resultaat. Het model verwerkt dat resultaat in zijn antwoord. ## Vereisten - Voltooide [Module 01 - Introductie](../01-introduction/README.md) (Azure OpenAI-resources gedeployed) -- Voltooide eerdere modules aanbevolen (deze module verwijst naar [RAG-concepten uit Module 03](../03-rag/README.md) in de Tools vs RAG vergelijking) -- `.env` bestand in de hoofdmap met Azure-gegevens (gemaakt met `azd up` in Module 01) +- Voltooide vorige modules aanbevolen (deze module verwijst naar [RAG-concepten uit Module 03](../03-rag/README.md) in de vergelijking Tools vs RAG) +- `.env` bestand in de rootmap met Azure-gegevens (aangemaakt door `azd up` in Module 01) -> **Opmerking:** Als je Module 01 nog niet hebt voltooid, volg dan eerst de implementatie-instructies daar. +> **Opmerking:** Als je Module 01 niet hebt voltooid, volg dan eerst de deploymentinstructies daar. ## Begrip van AI-agenten met Tools -> **📝 Opmerking:** De term "agenten" in deze module verwijst naar AI-assistenten die zijn uitgebreid met tool-aanroepmogelijkheden. Dit verschilt van de **Agentic AI**-patronen (autonome agenten met planning, geheugen en meervoudige redeneerstappen) die we behandelen in [Module 05: MCP](../05-mcp/README.md). +> **📝 Opmerking:** De term "agenten" in deze module verwijst naar AI-assistenten die zijn uitgebreid met tool-aanroep-mogelijkheden. Dit is anders dan de **Agentic AI** patronen (autonome agenten met planning, geheugen en meerstaps redenering) die we behandelen in [Module 05: MCP](../05-mcp/README.md). -Zonder tools kan een taalmodel alleen tekst genereren op basis van zijn trainingsdata. Vraag het naar het huidige weer en het moet raden. Geef het tools en het kan een weer-API aanroepen, berekeningen uitvoeren of een database raadplegen — en die echte resultaten verweven in zijn antwoord. +Zonder tools kan een taalmodel alleen tekst genereren uit zijn trainingsdata. Vraag het om het huidige weer, en het moet raden. Geef het tools, en het kan een weer-API aanroepen, berekeningen uitvoeren of een database raadplegen – en die echte resultaten verwerken in zijn antwoord. Zonder Tools vs Met Tools -*Zonder tools kan het model alleen raden — met tools kan het API's aanroepen, berekeningen uitvoeren en realtime data teruggeven.* +*Zonder tools kan het model alleen gokken – met tools kan het API’s aanroepen, berekeningen uitvoeren en realtime data retourneren.* -Een AI-agent met tools volgt een **Reasoning and Acting (ReAct)** patroon. Het model reageert niet alleen — het denkt na over wat het nodig heeft, handelt door een tool aan te roepen, observeert het resultaat, en besluit dan of het opnieuw moet handelen of het eindantwoord moet geven: +Een AI-agent met tools volgt een **Redeneren en Handelen (ReAct)** patroon. Het model reageert niet alleen — het denkt na over wat het nodig heeft, handelt door een tool aan te roepen, observeert het resultaat, en beslist dan of het opnieuw moet handelen of het finale antwoord geeft: -1. **Redeneren** — De agent analyseert de vraag van de gebruiker en bepaalt welke informatie nodig is -2. **Handelen** — De agent kiest de juiste tool, genereert de juiste parameters en roept deze aan -3. **Observeren** — De agent ontvangt de output van de tool en evalueert het resultaat -4. **Herhalen of beantwoorden** — Indien meer data nodig is, begint de agent een nieuwe cyclus; anders stelt hij een natuurlijk taalantwoord samen +1. **Redeneer** — De agent analyseert de vraag van de gebruiker en bepaalt welke informatie het nodig heeft +2. **Handel** — De agent kiest de juiste tool, genereert correcte parameters en roept deze aan +3. **Observeer** — De agent ontvangt de output van de tool en evalueert het resultaat +4. **Herhaal of Reageer** — Als meer data nodig is, herhaalt de agent; anders stelt het een natuurlijk antwoord samen ReAct-patroon -*De ReAct-cyclus — de agent overweegt wat te doen, handelt door een tool aan te roepen, observeert het resultaat en herhaalt tot het een eindantwoord kan geven.* +*De ReAct-cyclus — de agent redeneert over wat te doen, handelt door een tool aan te roepen, observeert het resultaat, en herhaalt totdat het het uiteindelijke antwoord kan geven.* -Dit gebeurt automatisch. Jij definieert de tools en hun beschrijvingen. Het model regelt zelf wanneer en hoe deze te gebruiken. +Dit gebeurt automatisch. Jij definieert de tools en hun beschrijvingen. Het model bepaalt wanneer en hoe ze te gebruiken. -## Hoe Tool-aanroepen werken +## Hoe Tool Calling Werkt ### Tooldefinities [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Je definieert functies met duidelijke beschrijvingen en parameter-specificaties. Het model ziet deze beschrijvingen in zijn systeem-prompt en begrijpt wat elke tool doet. +Je definieert functies met duidelijke beschrijvingen en parameterspecificaties. Het model ziet deze beschrijvingen in zijn systeem-prompt en begrijpt wat elke tool doet. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Uw logica voor het opzoeken van het weer + // Je weeropzoeklogica return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Assistent wordt automatisch verbonden door Spring Boot met: +// Assistant is automatisch verbonden door Spring Boot met: // - ChatModel bean // - Alle @Tool-methoden van @Component-klassen // - ChatMemoryProvider voor sessiebeheer ``` -Het onderstaande diagram breekt elke annotatie af en laat zien hoe elk onderdeel de AI helpt te begrijpen wanneer de tool moet worden aangeroepen en welke argumenten meegegeven moeten worden: +Het onderstaande diagram breekt elke annotatie af en laat zien hoe elk onderdeel de AI helpt begrijpen wanneer de tool aan te roepen en welke argumenten mee te geven: Anatomie van Tooldefinities -*Anatomie van een tooldefinitie — @Tool vertelt de AI wanneer het te gebruiken, @P beschrijft elke parameter, en @AiService verbindt alles bij de startup.* +*Anatomie van een tooldefinitie — @Tool vertelt de AI wanneer het te gebruiken, @P beschrijft elke parameter, en @AiService verbindt alles bij de start.* > **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) en vraag: -> - "Hoe integreer ik een echte weer-API zoals OpenWeatherMap in plaats van mockdata?" -> - "Wat maakt een goede toolbeschrijving die de AI helpt de tool correct te gebruiken?" -> - "Hoe ga ik om met API-fouten en rate limits in toolimplementaties?" +> - "Hoe integreer ik een echte weer-API zoals OpenWeatherMap in plaats van mock-gegevens?" +> - "Wat maakt een goede toolbeschrijving die de AI helpt het correct te gebruiken?" +> - "Hoe behandel ik API-fouten en ratelimieten in toolimplementaties?" ### Besluitvorming -Wanneer een gebruiker vraagt "Wat is het weer in Seattle?", kiest het model niet willekeurig een tool. Het vergelijkt de bedoeling van de gebruiker met elke beschikbare toolbeschrijving, scoort ze op relevantie en selecteert de beste match. Het genereert dan een gestructureerde functie-aanroep met de juiste parameters – in dit geval `location` ingesteld op `"Seattle"`. +Wanneer een gebruiker vraagt "Wat is het weer in Seattle?", kiest het model niet willekeurig een tool. Het vergelijkt de intentie van de gebruiker met elke toolbeschrijving waar het toegang toe heeft, scoort ze op relevantie, en selecteert de beste match. Vervolgens genereert het een gestructureerde functieroep met de juiste parameters – in dit geval `location` op `"Seattle"` gezet. -Als geen enkele tool overeenkomt met het verzoek van de gebruiker, valt het model terug op het beantwoorden vanuit zijn eigen kennis. Bij meerdere matches kiest het de meest specifieke. +Als geen enkele tool bij het verzoek past, valt het model terug op kennis uit eigen database. Als er meerdere tools passen, kiest het de meest specifieke. Hoe de AI beslist welke tool te gebruiken -*Het model beoordeelt elke beschikbare tool ten opzichte van de intentie van de gebruiker en selecteert de beste match — daarom zijn duidelijke en specifieke toolbeschrijvingen belangrijk.* +*Het model evalueert elke beschikbare tool op basis van de intentie van de gebruiker en selecteert de beste match — daarom zijn duidelijke, specifieke toolbeschrijvingen belangrijk.* ### Uitvoering [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot auto-wiret de declaratieve `@AiService` interface met alle geregistreerde tools, en LangChain4j voert tool-aanroepen automatisch uit. Achter de schermen doorloopt een volledige tool-aanroep zes fasen — van de natuurlijke taalvraag van de gebruiker tot een natuurlijk taalantwoord terug: +Spring Boot auto-wiret de declaratieve `@AiService` interface met alle geregistreerde tools, en LangChain4j voert tool-aanroepen automatisch uit. Achter de schermen verloopt een volledige tool-aanroep via zes stadia — van de natuurlijke taalvraag van de gebruiker tot een natuurlijk taalantwoord: -Tool-aanroepproces +Tool Calling Flow -*De end-to-end flow — de gebruiker stelt een vraag, het model selecteert een tool, LangChain4j voert deze uit, en het model verwerkt het resultaat in een natuurlijk antwoord.* +*De end-to-end flow — de gebruiker stelt een vraag, het model selecteert een tool, LangChain4j voert deze uit, en het model verweeft het resultaat in een natuurlijk antwoord.* -Als je de [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) in Module 00 hebt uitgevoerd, heb je dit patroon al gezien — de `Calculator` tools werden op dezelfde manier aangeroepen. Het onderstaande sequentiediagram toont precies wat er achter de schermen gebeurde tijdens die demo: +Achter de schermen voert `AiServices` dezelfde tool-aanroep lus voor elke tool uit — hier geïllustreerd met een simpele `Calculator`. Het onderstaande sequentiediagram laat precies zien wat er onderhuids gebeurt: -Sequentiediagram Tool-aanroepen +Tool Calling Sequencediagram -*De tool-aanroeplus uit de Quick Start demo — `AiServices` stuurt je bericht en toolschemas naar de LLM, de LLM antwoordt met een functie-aanroep zoals `add(42, 58)`, LangChain4j voert de `Calculator` methode lokaal uit en geeft het resultaat terug voor het eindantwoord.* +*De tool-aanroep lus — `AiServices` stuurt jouw bericht en toolschema’s naar de LLM, de LLM antwoordt met een functieroep zoals `add(42, 58)`, LangChain4j voert de `Calculator` methode lokaal uit, en geeft het resultaat terug voor het finale antwoord.* > **🤖 Probeer met [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) en vraag: > - "Hoe werkt het ReAct-patroon en waarom is het effectief voor AI-agenten?" -> - "Hoe besluit de agent welke tool te gebruiken en in welke volgorde?" -> - "Wat gebeurt er als een tool-executie mislukt – hoe kan ik fouten robuust afhandelen?" +> - "Hoe beslist de agent welke tool te gebruiken en in welke volgorde?" +> - "Wat gebeurt er als een tool-uitvoering faalt - hoe behandel ik fouten robuust?" -### Antwoordgeneratie +### Responsegeneratie -Het model ontvangt de weersgegevens en formatteert deze in een natuurlijk taalantwoord voor de gebruiker. +Het model ontvangt de weerdata en formatteert het tot een natuurlijk taalantwoord aan de gebruiker. ### Architectuur: Spring Boot Auto-Wiring -Deze module gebruikt LangChain4j's Spring Boot-integratie met declaratieve `@AiService` interfaces. Bij het opstarten ontdekt Spring Boot elke `@Component` die `@Tool` methoden bevat, je `ChatModel` bean en de `ChatMemoryProvider` — en verbindt ze allemaal in één `Assistant` interface zonder enige overhead. +Deze module gebruikt LangChain4j’s Spring Boot-integratie met declaratieve `@AiService` interfaces. Bij het opstarten ontdekt Spring Boot elke `@Component` met `@Tool`-methoden, jouw `ChatModel` bean en de `ChatMemoryProvider` — en verbindt ze allemaal in één `Assistant` interface zonder boilerplate. -Architectuur Spring Boot Auto-Wiring +Spring Boot Auto-Wiring Architectuur -*De @AiService interface koppelt ChatModel, toolcomponenten en geheugenprovider — Spring Boot regelt alle koppelingen automatisch.* +*De @AiService interface verbindt ChatModel, toolcomponenten en memory provider — Spring Boot regelt alle wiring automatisch.* -Hier is de volledige levenscyclus van een verzoek als sequentiediagram — van het HTTP-verzoek via controller, service en automatisch gekoppelde proxy, helemaal tot de tool-uitvoering en terug: +Hier is de volledige request lifecycle als sequentiediagram — van de HTTP-aanvraag via controller, service, en auto-wired proxy tot aan de tooluitvoering en terug: -Sequentie Spring Boot Tool-aanroepen +Spring Boot Tool Calling Sequentie -*De complete Spring Boot request levenscyclus — HTTP-verzoek stroomt via controller en service naar de automatisch gekoppelde Assistant proxy, die LLM en tool-aanroepen automatisch orkestreert.* +*De complete Spring Boot request lifecycle — HTTP-verzoek stroomt via controller en service naar de auto-wired Assistant proxy, die de LLM- en tool-aanroepen automatisch orkestreert.* Belangrijke voordelen van deze aanpak: -- **Spring Boot auto-wiring** — ChatModel en tools worden automatisch geïnjecteerd -- **@MemoryId patroon** — Automatisch sessiegebaseerd geheugenbeheer -- **Een enkele instantie** — Assistant wordt één keer gecreëerd en hergebruikt voor betere prestaties -- **Typesafe uitvoering** — Java-methoden worden direct aangeroepen met typeconversie -- **Multi-turn orkestratie** — Behandelt toolketting automatisch -- **Geen boilerplate** — Geen handmatige `AiServices.builder()` oproepen of geheugen-HashMap nodig +- **Spring Boot auto-wiring** — ChatModel en tools automatisch geïnjecteerd +- **@MemoryId-patroon** — Automatisch sessiegebaseerd geheugenbeheer +- **Enkele instantie** — Assistant wordt één keer gemaakt en hergebruikt voor betere prestaties +- **Type-veilige uitvoering** — Java-methoden worden direct aangeroepen met typeconversie +- **Multi-turn orkestratie** — Handelt tool chaining automatisch af +- **Zero boilerplate** — Geen handmatige `AiServices.builder()` aanroepen of geheugen HashMap -Alternatieve benaderingen (handmatige `AiServices.builder()`) vereisen meer code en missen de voordelen van Spring Boot-integratie. +Alternatieve benaderingen (handmatige `AiServices.builder()`) vergen meer code en missen de voordelen van Spring Boot-integratie. -## Toolketting +## Tool Chaining -**Toolketting** — De werkelijke kracht van tool-gebaseerde agenten blijkt als een enkele vraag meerdere tools vereist. Vraag "Wat is het weer in Seattle in Fahrenheit?" en de agent koppelt automatisch twee tools: eerst roept hij `getCurrentWeather` aan voor de temperatuur in Celsius, vervolgens geeft hij die waarde door aan `celsiusToFahrenheit` voor conversie — allemaal in één gespreksronde. +**Tool chaining** — De echte kracht van tool-gebaseerde agenten blijkt wanneer een enkele vraag meerdere tools vereist. Vraag "Wat is het weer in Seattle in Fahrenheit?" en de agent schakelt automatisch twee tools aan: eerst roept hij `getCurrentWeather` aan om de temperatuur in Celsius op te halen, daarna geeft hij die waarde door aan `celsiusToFahrenheit` voor conversie — alles in één gespreksturn. -Voorbeeld Toolketting +Voorbeeld Tool Chaining -*Toolketting in actie — de agent roept eerst getCurrentWeather aan, pipeert het Celsius-resultaat door naar celsiusToFahrenheit en levert een gecombineerd antwoord.* +*Tool chaining in actie — de agent roept eerst getCurrentWeather aan, geeft het Celsius-resultaat door aan celsiusToFahrenheit, en levert een gecombineerd antwoord.* -**Gracieus Falen** — Vraag naar het weer in een stad die niet in de mockdata zit. De tool retourneert een foutmelding, en de AI legt uit dat het niet kan helpen in plaats van te crashen. Tools falen veilig. Het onderstaande diagram vergelijkt de twee benaderingen — met correcte foutafhandeling vangt de agent de uitzondering op en reageert behulpzaam, zonder dat de hele applicatie crasht: +**Graceful Failures** — Vraag naar het weer in een stad die niet in de mockdata staat. De tool retourneert een foutmelding, en de AI legt uit dat het niet kan helpen in plaats van te crashen. Tools falen veilig. Het onderstaande diagram toont het verschil tussen beide benaderingen — met correcte foutenafhandeling vangt de agent de exceptie op en reageert behulpzaam, zonder daarvan crasht de hele applicatie: -Foutafhandelingsstroom +Foutenafhandeling Flow *Wanneer een tool faalt, vangt de agent de fout op en reageert met een behulpzame uitleg in plaats van te crashen.* -Dit gebeurt in één gespreksronde. De agent orkestreert meerdere tool-aanroepen autonoom. +Dit gebeurt in één gespreksturn. De agent orkestreert meerdere tool-aanroepen autonoom. -## Start de applicatie +## De Applicatie Uitvoeren **Controleer deployment:** -Zorg dat het `.env` bestand bestaat in de hoofdmap met Azure-gegevens (aangemaakt tijdens Module 01). Voer dit uit vanuit de module-map (`04-tools/`): +Zorg dat het `.env` bestand aanwezig is in de rootmap met Azure-gegevens (aangemaakt tijdens Module 01). Voer dit uit vanuit de modulemap (`04-tools/`): **Bash:** ```bash @@ -202,37 +202,37 @@ cat ../.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT weergeven **PowerShell:** ```powershell -Get-Content ..\.env # Moet AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT tonen +Get-Content ..\.env # Zou AZURE_OPENAI_ENDPOINT, API_SLEUTEL, IMPLEMENTATIE moeten tonen ``` **Start de applicatie:** -> **Opmerking:** Als je al alle applicaties hebt gestart met `./start-all.sh` vanuit de hoofdmap (zoals beschreven in Module 01), dan draait deze module al op poort 8084. Je kunt de startcommando's hieronder dan overslaan en direct naar http://localhost:8084 gaan. +> **Opmerking:** Als je al alle applicaties hebt gestart met `./start-all.sh` vanuit de rootmap (zoals beschreven in Module 01), draait deze module al op poort 8084. Je kunt onderstaande startcommando’s overslaan en direct naar http://localhost:8084 gaan. -**Optie 1: Gebruik van Spring Boot Dashboard (aanbevolen voor VS Code gebruikers)** +**Optie 1: Gebruik Spring Boot Dashboard (aanbevolen voor VS Code-gebruikers)** -De dev container bevat de Spring Boot Dashboard-extensie, die een visuele interface biedt om alle Spring Boot-applicaties te beheren. Je vindt deze in de Activiteitenbalk aan de linkerkant van VS Code (zoek naar het Spring Boot-pictogram). +De dev container bevat de Spring Boot Dashboard extensie, die een visuele interface biedt om alle Spring Boot-applicaties te beheren. Je vindt het in de Activity Bar links in VS Code (zoek naar het Spring Boot-icoon). -In het Spring Boot Dashboard kun je: +Vanaf het Spring Boot Dashboard kun je: - Alle beschikbare Spring Boot-applicaties in de workspace zien - Applicaties starten/stoppen met één klik -- Applicatielogs real-time bekijken +- Applicatielogs in realtime bekijken - Applicatiestatus monitoren -Klik gewoon op de afspeelknop naast "tools" om dit module te starten, of start alle modules tegelijk. -Dit is hoe het Spring Boot Dashboard eruitziet in VS Code: +Klik gewoon op de afspeelknop naast "tools" om deze module te starten, of start alle modules tegelijk. +Zo ziet het Spring Boot Dashboard eruit in VS Code: Spring Boot Dashboard -*Het Spring Boot Dashboard in VS Code — start, stop en monitor alle modules vanaf één plek* +*Het Spring Boot Dashboard in VS Code — start, stop en beheer alle modules vanaf één plek* -**Optie 2: Gebruik maken van shell scripts** +**Optie 2: Shell-scripts gebruiken** Start alle webapplicaties (modules 01-04): **Bash:** ```bash -cd .. # Vanuit de hoofdmap +cd .. # Vanuit de root directory ./start-all.sh ``` @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Beide scripts laden automatisch omgevingsvariabelen uit het root `.env` bestand en bouwen de JARs als deze niet bestaan. +Beide scripts laden automatisch omgeving variabelen uit het root `.env`-bestand en bouwen de JARs als ze niet bestaan. -> **Opmerking:** Als je alle modules liever handmatig bouwt vóór het starten: +> **Opmerking:** Als je alle modules liever handmatig bouwt voordat je ze start: > > **Bash:** > ```bash @@ -292,84 +292,84 @@ cd ..; .\stop-all.ps1 # Alle modules ## De Applicatie Gebruiken -De applicatie biedt een webinterface waarmee je kunt communiceren met een AI-agent die toegang heeft tot weer- en temperatuurconversietools. Dit is hoe de interface eruitziet — het bevat snelstartvoorbeelden en een chatpaneel voor het versturen van verzoeken: +De applicatie biedt een webinterface waar je kunt communiceren met een AI-agent die toegang heeft tot weer- en temperatuurconversietools. Zo ziet de interface eruit — met snelstartvoorbeelden en een chatpaneel om verzoeken te verzenden: AI Agent Tools Interface -*De AI Agent Tools-interface - snelle voorbeelden en chatinterface om met tools te communiceren* +*De AI Agent Tools-interface - snelle voorbeelden en chatinterface voor interactie met tools* -### Probeer Eenvoudig Tool Gebruik +### Probeer Eenvoudig Toolgebruik -Begin met een eenvoudige opdracht: "Zet 100 graden Fahrenheit om naar Celsius". De agent herkent dat hij de temperatuurconversietool moet gebruiken, roept deze aan met de juiste parameters en geeft het resultaat terug. Merk op hoe natuurlijk dit aanvoelt - je hoefde niet aan te geven welke tool te gebruiken of hoe deze aan te roepen. +Begin met een eenvoudige opdracht: "Converteer 100 graden Fahrenheit naar Celsius". De agent herkent dat hij de temperatuurconversietool nodig heeft, roept deze op met de juiste parameters en retourneert het resultaat. Merk op hoe natuurlijk dit aanvoelt - je hoefde niet aan te geven welke tool te gebruiken of hoe die aan te roepen. ### Test Tool Koppeling -Probeer nu iets complexers: "Wat is het weer in Seattle en zet het om naar Fahrenheit?" Kijk hoe de agent dit in stappen afhandelt. Eerst haalt hij het weer op (in Celsius), herkent dat omrekenen naar Fahrenheit nodig is, roept de conversietool aan en combineert beide resultaten in één antwoord. +Probeer nu iets complexers: "Wat is het weer in Seattle en converteer het naar Fahrenheit?" Kijk hoe de agent dit in stappen uitwerkt. Eerst haalt hij het weer op (wat Celsius teruggeeft), herkent dat het moet worden omgezet naar Fahrenheit, roept de conversietool aan en combineert beide resultaten in één antwoord. -### Zie het Gespreksverloop +### Zie Het Gespreksverloop -De chatinterface bewaart de gespreksgeschiedenis, zodat je een dialoog met meerdere beurten kunt voeren. Je kunt alle eerdere vragen en antwoorden zien, waardoor je het gesprek gemakkelijk kunt volgen en begrijpen hoe de agent context opbouwt over meerdere uitwisselingen. +De chatinterface bewaart de geschiedenis van het gesprek, waardoor je meerdere beurten kunt voeren. Je ziet alle eerdere vragen en antwoorden, wat het makkelijk maakt het gesprek te volgen en te begrijpen hoe de agent context opbouwt over meerdere uitwisselingen. Conversation with Multiple Tool Calls -*Een meerturn-gesprek dat eenvoudige conversies, weeropvragingen en toolkoppelingen laat zien* +*Meerdere beurten gesprek met eenvoudige conversies, weeropvragingen en toolkoppelingen* ### Experimenteer met Verschillende Verzoeken Probeer verschillende combinaties: - Weeropvragingen: "Wat is het weer in Tokio?" - Temperatuurconversies: "Wat is 25°C in Kelvin?" -- Gecombineerde vragen: "Controleer het weer in Parijs en vertel me of het boven de 20°C is" +- Gecombineerde vragen: "Check het weer in Parijs en vertel me of het boven de 20°C is" -Let erop hoe de agent natuurlijke taal interpreteert en vertaalt naar passende tool-aanroepen. +Let op hoe de agent natuurlijke taal interpreteert en vertaalt naar passende tool-aanroepen. ## Belangrijke Concepten -### ReAct Patroon (Redeneren en Handelen) +### ReAct-patroon (Redeneren en Handelen) -De agent wisselt af tussen redeneren (beslissen wat te doen) en handelen (tools gebruiken). Dit patroon maakt autonome probleemoplossing mogelijk in plaats van alleen maar reageren op instructies. +De agent wisselt af tussen redeneren (beslissen wat te doen) en handelen (tools gebruiken). Dit patroon maakt autonome probleemoplossing mogelijk in plaats van alleen reageren op opdrachten. -### Tool Beschrijvingen Zijn Belangrijk +### Toolbeschrijvingen Zijn Belangrijk -De kwaliteit van je toolbeschrijvingen beïnvloedt direct hoe goed de agent ze gebruikt. Duidelijke, specifieke beschrijvingen helpen het model te begrijpen wanneer en hoe elke tool aangeroepen moet worden. +De kwaliteit van je toolbeschrijvingen beïnvloedt direct hoe goed de agent ze gebruikt. Duidelijke, specifieke beschrijvingen helpen het model te begrijpen wanneer en hoe elke tool aan te roepen. ### Sessiebeheer -De `@MemoryId` annotatie maakt automatisch sessie-gebaseerd geheugenbeheer mogelijk. Elke sessie-ID krijgt een eigen `ChatMemory` instantie die door de `ChatMemoryProvider` bean wordt beheerd, zodat meerdere gebruikers gelijktijdig met de agent kunnen communiceren zonder dat hun gesprekken door elkaar lopen. In het volgende diagram zie je hoe meerdere gebruikers worden gekoppeld aan geïsoleerde geheugenopslag op basis van hun sessie-IDs: +De `@MemoryId`-annotatie maakt automatische sessiegebaseerde geheugenbeheer mogelijk. Elke sessie-ID krijgt een eigen `ChatMemory`-instantie beheerd door de `ChatMemoryProvider` bean, zodat meerdere gebruikers tegelijk met de agent kunnen communiceren zonder dat hun gesprekken in elkaar overlopen. Het volgende diagram toont hoe meerdere gebruikers worden gerouteerd naar geïsoleerde geheugenopslag gebaseerd op hun sessie-IDs: Session Management with @MemoryId -*Elke sessie-ID wordt gekoppeld aan een geïsoleerde gespreksgeschiedenis — gebruikers zien nooit elkaars berichten.* +*Elke sessie-ID correspondeert met een geïsoleerde gesprekshistorie — gebruikers zien nooit elkaars berichten.* ### Foutafhandeling -Tools kunnen falen — API's kunnen time-outs geven, parameters kunnen ongeldig zijn, externe diensten kunnen uitvallen. Productie-agents hebben foutafhandeling nodig zodat het model problemen kan uitleggen of alternatieven kan proberen in plaats van de hele applicatie te laten crashen. Wanneer een tool een uitzondering gooit, vangt LangChain4j die op en geeft de foutmelding terug aan het model, dat het probleem dan in natuurlijke taal kan uitleggen. +Tools kunnen falen — API’s kunnen time-outs geven, parameters kunnen ongeldig zijn, externe diensten kunnen uitvallen. Productie-agents hebben foutafhandeling nodig zodat het model problemen kan uitleggen of alternatieven kan proberen in plaats van de hele applicatie te laten crashen. Wanneer een tool een uitzondering gooit, vangt LangChain4j die op en geeft het foutbericht terug aan het model, dat vervolgens het probleem in natuurlijke taal kan uitleggen. ## Beschikbare Tools -Het onderstaande diagram toont het brede ecosysteem van tools die je kunt bouwen. Dit module demonstreert weer- en temperatuurtools, maar hetzelfde `@Tool` patroon werkt voor elke Java-methode — van databasequery's tot betalingsverwerking. +Het onderstaande diagram toont het brede ecosysteem van tools die je kunt bouwen. Deze module demonstreert weer- en temperatuurtools, maar hetzelfde `@Tool` patroon werkt voor elke Java-methode — van databasequeries tot betalingsverwerking. Tool Ecosystem -*Elke Java-methode die met @Tool is geannoteerd wordt beschikbaar voor de AI — het patroon breidt zich uit naar databases, API's, e-mail, bestandsbewerkingen en meer.* +*Elke Java-methode geannoteerd met @Tool wordt beschikbaar voor de AI — het patroon breidt zich uit naar databases, API’s, e-mail, bestandsoperaties en meer.* -## Wanneer Tool-Gebaseerde Agents Te Gebruiken +## Wanneer Gebruik Je Tool-gebaseerde Agents -Niet elk verzoek heeft tools nodig. De keuze hangt af van of de AI met externe systemen moet communiceren of kan antwoorden uit eigen kennis. De onderstaande gids geeft aan wanneer tools waarde toevoegen en wanneer ze onnodig zijn: +Niet elk verzoek heeft tools nodig. De beslissing hangt af van of de AI met externe systemen moet communiceren of de vraag uit zijn eigen kennis kan beantwoorden. De volgende gids vat samen wanneer tools waarde toevoegen en wanneer ze onnodig zijn: When to Use Tools -*Een snelle beslisgids — tools zijn voor realtime data, berekeningen en acties; algemene kennis en creatieve taken niet.* +*Een snelle beslissingsgids — tools zijn voor realtime data, berekeningen en acties; algemene kennis en creatieve taken hebben ze niet nodig.* -## Tools vs RAG +## Tools versus RAG -Modules 03 en 04 breiden beide uit wat de AI kan doen, maar op fundamenteel verschillende manieren. RAG geeft het model toegang tot **kennis** door documenten op te halen. Tools geven het model de mogelijkheid om **acties** uit te voeren door functies aan te roepen. Het onderstaande diagram vergelijkt deze twee benaderingen naast elkaar — van hoe elke workflow werkt tot de afwegingen ertussen: +Modules 03 en 04 breiden beiden uit wat de AI kan, maar op fundamenteel verschillende manieren. RAG geeft het model toegang tot **kennis** door documenten op te halen. Tools geven het model de mogelijkheid om **acties** uit te voeren door functies aan te roepen. Het onderstaande diagram vergelijkt deze twee benaderingen naast elkaar — van hoe elke workflow werkt tot de voor- en nadelen: Tools vs RAG Comparison *RAG haalt informatie op uit statische documenten — Tools voeren acties uit en halen dynamische, realtime data op. Veel productiesystemen combineren beide.* -In de praktijk combineren veel productiesystemen beide benaderingen: RAG om antwoorden te funderen op je documentatie en Tools om live data op te halen of bewerkingen uit te voeren. +In de praktijk combineren veel productiesystemen beide benaderingen: RAG voor het onderbouwen van antwoorden met je documentatie, en Tools om live data op te halen of bewerkingen uit te voeren. ## Volgende Stappen @@ -382,6 +382,6 @@ In de praktijk combineren veel productiesystemen beide benaderingen: RAG om antw --- -**Disclaimer**: -Dit document is vertaald met behulp van de AI-vertalingsdienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel wij streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet als de gezaghebbende bron worden beschouwd. Voor kritieke informatie wordt een professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. +**Disclaimer**: +Dit document is vertaald met behulp van de AI vertaaldienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. \ No newline at end of file diff --git a/translations/nl/README.md b/translations/nl/README.md index 5a0ca9e1a..7dbcfc5cb 100644 --- a/translations/nl/README.md +++ b/translations/nl/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j voor Beginners +# LangChain4j voor beginners -Een cursus voor het bouwen van AI-toepassingen met LangChain4j en Azure OpenAI GPT-5.2, van basale chat tot AI-agenten. +Een cursus voor het bouwen van AI-toepassingen met LangChain4j en Azure OpenAI GPT-5.2, van eenvoudige chat tot AI-agents. -### 🌐 Meertalige Ondersteuning +### 🌐 Meertalige ondersteuning -#### Ondersteund via GitHub Action (Automatisch & Altijd Up-to-Date) +#### Ondersteund via GitHub Action (Geautomatiseerd & Altijd up-to-date) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](./README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Lieber lokal klonen?** +> **Liever lokaal klonen?** > -> Deze repository bevat meer dan 50 taalvertalingen wat de downloadgrootte aanzienlijk vergroot. Om te klonen zonder vertalingen, gebruik sparse checkout: +> Deze repository bevat meer dan 50 taalvertalingen die de downloadgrootte aanzienlijk vergroten. Om zonder vertalingen te klonen, gebruik sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -34,59 +34,58 @@ Een cursus voor het bouwen van AI-toepassingen met LangChain4j en Azure OpenAI G ## Inhoudsopgave -1. [Snel aan de slag](00-quick-start/README.md) - Begin met LangChain4j -2. [Introductie](01-introduction/README.md) - Leer de basisprincipes van LangChain4j -3. [Prompt Engineering](02-prompt-engineering/README.md) - Beheers effectief promptontwerp -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Bouw intelligente kennisgebaseerde systemen -5. [Tools](04-tools/README.md) - Integreer externe tools en eenvoudige assistenten -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Werk met het Model Context Protocol (MCP) en Agentic modules +1. [Introductie](01-introduction/README.md) - Leer de basisbeginselen van LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Beheers effectief promptontwerp +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Bouw intelligente kennisgebaseerde systemen +4. [Tools](04-tools/README.md) - Integreer externe tools en eenvoudige assistenten +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Werk met het Model Context Protocol (MCP) en Agentic-modules -### Video Walkthroughs +### Videohandleidingen -Elke module heeft een bijbehorende live sessie waarin we de concepten en code stap voor stap doorlopen. +Elke module heeft een begeleidende live sessie waarin we stap voor stap de concepten en code doornemen. | Module | Video | |--------|-------| | 01 - Introductie | [Aan de slag met LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - Prompt Engineering | [Prompt Engineering met LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG met LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Tools & 05 - MCP | [AI-Agenten met Tools en MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Tools & 05 - MCP | [AI Agents met Tools en MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## Leertraject -**Nieuw bij LangChain4j?** Bekijk de [Glossary](docs/GLOSSARY.md) voor definities van belangrijke termen en concepten. +**Nieuw met LangChain4j?** Bekijk de [Glossary](docs/GLOSSARY.md) voor definities van belangrijke termen en concepten. -> **Snel aan de slag** +> **Snel starten** 1. Fork deze repository naar je GitHub-account 2. Klik op **Code** → tabblad **Codespaces** → **...** → **Nieuw met opties...** -3. Gebruik de standaardinstellingen – dit selecteert de ontwikkelcontainer die voor deze cursus is gemaakt +3. Gebruik de standaardinstellingen – deze selecteren de ontwikkelcontainer die voor deze cursus is gemaakt 4. Klik op **Codespace maken** 5. Wacht 5-10 minuten tot de omgeving klaar is -6. Ga direct naar [Snel aan de slag](./00-quick-start/README.md) om te beginnen! +6. Ga direct naar [Introductie](./01-introduction/README.md) om te beginnen! -Na het voltooien van de modules, verken de [Testgids](docs/TESTING.md) om de testconcepten van LangChain4j in actie te zien. +Na het voltooien van de modules, verken de [Testgids](docs/TESTING.md) om LangChain4j-testconcepten in actie te zien. -> **Opmerking:** Deze training gebruikt zowel GitHub Models als Azure OpenAI. De module [Snel aan de slag](00-quick-start/README.md) gebruikt GitHub Models (geen Azure-abonnement nodig), terwijl modules 1-5 Azure OpenAI gebruiken. Begin met een [GRATIS Azure-account](https://aka.ms/azure-free-account) als je er nog geen hebt. +> **Opmerking:** Deze training gebruikt Azure OpenAI. Begin met een [GRATIS Azure-account](https://aka.ms/azure-free-account) als je er nog geen hebt. ## Leren met GitHub Copilot -Om snel te beginnen met coderen, open dit project in een GitHub Codespace of je lokale IDE met de meegeleverde devcontainer. De devcontainer die in deze cursus wordt gebruikt, is vooraf geconfigureerd met GitHub Copilot voor AI-gepaard programmeren. +Om snel te beginnen met coderen, open je dit project in een GitHub Codespace of je lokale IDE met de meegeleverde devcontainer. De devcontainer die in deze cursus wordt gebruikt, is vooraf geconfigureerd met GitHub Copilot voor AI-gestuurde paired programming. -Elk codevoorbeeld bevat voorgestelde vragen die je aan GitHub Copilot kunt stellen om je begrip te verdiepen. Let op de 💡/🤖 prompts in: +Elk codevoorbeeld bevat voorgestelde vragen die je aan GitHub Copilot kunt stellen om je begrip te verdiepen. Let op de 💡/🤖-prompts in: -- **Java-bestandskoppen** - Vragen specifiek voor elk voorbeeld -- **Module READMEs** - Verkenningsprompts na codevoorbeelden +- **Java-bestandsheaders** - Vragen specifiek voor elk voorbeeld +- **Module-READMEs** - Verkenningsprompts na codevoorbeelden -**Hoe te gebruiken:** Open een willekeurig codebestand en stel Copilot de voorgestelde vragen. Hij heeft volledige context van de codebasis en kan uitleggen, uitbreiden en alternatieven voorstellen. +**Hoe te gebruiken:** Open een willekeurig codebestand en stel Copilot de voorgestelde vragen. Het heeft de volledige context van de codebasis en kan uitleg geven, uitbreiden en alternatieven voorstellen. -Wil je meer leren? Bekijk [Copilot voor AI-gepaard programmeren](https://aka.ms/GitHubCopilotAI). +Wil je meer leren? Bekijk [Copilot voor AI Paired Programming](https://aka.ms/GitHubCopilotAI). -## Aanvullende Bronnen +## Aanvullende bronnen ### LangChain @@ -95,19 +94,19 @@ Wil je meer leren? Bekijk [Copilot voor AI-gepaard programmeren](https://aka.ms/ [![LangChain voor Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agenten +### Azure / Edge / MCP / Agents [![AZD voor Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) [![Edge AI voor Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) [![MCP voor Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agenten voor Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI Agents voor Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Generatieve AI Reeks -[![Generatieve AI voor Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generatieve AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generatieve AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generatieve AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Generative AI-serie +[![Generative AI voor Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- @@ -116,35 +115,36 @@ Wil je meer leren? Bekijk [Copilot voor AI-gepaard programmeren](https://aka.ms/ [![Data Science voor Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI voor Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Cybersecurity voor Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Webontwikkeling voor Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT voor Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR Ontwikkeling voor Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Copilot Serie -[![Copilot voor AI Gepaarde Programmering](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot voor C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot Avontuur](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +### Copilot-serie +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## Hulp Krijgen +## Hulp krijgen -Als je vastloopt of vragen hebt over het bouwen van AI-apps, sluit dan aan bij: +Als je vastloopt of vragen hebt over het bouwen van AI-apps, sluit je aan bij: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Als je productfeedback hebt of fouten tegenkomt tijdens het bouwen, bezoek dan: +Als je productfeedback of fouten tegenkomt tijdens het bouwen, bezoek dan: -[![Microsoft Foundry Ontwikkelaarsforum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) +[![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licentie -MIT-licentie - Zie [LICENSE](../../LICENSE) bestand voor details. +MIT-licentie - Zie het bestand [LICENSE](../../LICENSE) voor details. --- -**Disclaimer**: -Dit document is vertaald met behulp van de AI-vertalingsdienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het oorspronkelijke document in de oorspronkelijke taal geldt als de gezaghebbende bron. Voor kritieke informatie wordt een professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. +**Disclaimer**: +Dit document is vertaald met behulp van de AI vertaaldienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. \ No newline at end of file diff --git a/translations/nl/docs/GLOSSARY.md b/translations/nl/docs/GLOSSARY.md index 01f717a22..18d7acb8c 100644 --- a/translations/nl/docs/GLOSSARY.md +++ b/translations/nl/docs/GLOSSARY.md @@ -1,18 +1,18 @@ -# LangChain4j Woordenlijst +# LangChain4j Verklarende Woordenlijst ## Inhoudsopgave -- [Kernconcepten](../../../docs) -- [LangChain4j Componenten](../../../docs) -- [AI/ML Concepten](../../../docs) -- [Guardrails](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agenten en Tools](../../../docs) -- [Agentic Module](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure Diensten](../../../docs) -- [Testen en Ontwikkeling](../../../docs) +- [Kernconcepten](#kernconcepten) +- [LangChain4j Componenten](#langchain4j-componenten) +- [AI/ML Concepten](#aiml-concepten) +- [Beveiligingsmaatregelen](#beveiligingsmaatregelen) +- [Prompt Engineering](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agenten en Tools](#agenten-en-tools---module-04) +- [Agentic Module](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure Diensten](#azure-diensten---module-01) +- [Testen en Ontwikkeling](#testen-en-ontwikkeling---testing-guide) Snelle referentie voor termen en concepten die door de cursus heen worden gebruikt. @@ -20,207 +20,205 @@ Snelle referentie voor termen en concepten die door de cursus heen worden gebrui **AI Agent** - Systeem dat AI gebruikt om autonoom te redeneren en te handelen. [Module 04](../04-tools/README.md) -**Chain** - Reeks bewerkingen waarbij output de volgende stap voedt. +**Chain** - Reeks bewerkingen waarbij uitgang gebruikt wordt als invoer voor de volgende stap. -**Chunking** - Documenten opdelen in kleinere stukken. Typisch: 300-500 tokens met overlap. [Module 03](../03-rag/README.md) +**Chunking** - Documenten opdelen in kleinere stukjes. Typisch: 300-500 tokens met overlap. [Module 03](../03-rag/README.md) **Context Window** - Maximale tokens die een model kan verwerken. GPT-5.2: 400K tokens (tot 272K input, 128K output). -**Embeddings** - Numerieke vectoren die tekstbetekenis representeren. [Module 03](../03-rag/README.md) +**Embeddings** - Numerieke vectoren die de betekenis van tekst representeren. [Module 03](../03-rag/README.md) **Function Calling** - Model genereert gestructureerde verzoeken om externe functies aan te roepen. [Module 04](../04-tools/README.md) -**Hallucinatie** - Wanneer modellen incorrecte maar plausibele informatie genereren. +**Hallucinatie** - Wanneer modellen onjuiste maar geloofwaardige informatie genereren. -**Prompt** - Tekstinput voor een taalmodel. [Module 02](../02-prompt-engineering/README.md) +**Prompt** - Tekstinvoer voor een taalmodel. [Module 02](../02-prompt-engineering/README.md) -**Semantisch Zoeken** - Zoeken op betekenis met behulp van embeddings, niet sleutelwoorden. [Module 03](../03-rag/README.md) +**Semantisch Zoeken** - Zoeken op betekenis met embeddings, niet met trefwoorden. [Module 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: geen geheugen. Stateful: onderhoudt gespreksgeschiedenis. [Module 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: geen geheugen. Stateful: houdt gesprekshistorie bij. [Module 01](../01-introduction/README.md) -**Tokens** - Basis tekstunits die modellen verwerken. Beïnvloeden kosten en limieten. [Module 01](../01-introduction/README.md) +**Tokens** - Basiseenheden van tekst die modellen verwerken. Beïnvloeden kosten en limieten. [Module 01](../01-introduction/README.md) -**Tool Chaining** - Opeenvolgende uitvoering van tools waarbij output de volgende aanroep informeert. [Module 04](../04-tools/README.md) +**Tool Chaining** - Aaneenschakeling van tools waarbij output invoer is voor de volgende tool. [Module 04](../04-tools/README.md) ## LangChain4j Componenten -**AiServices** - Maakt type-veilige AI service interfaces. +**AiServices** - Maakt type-veilige AI service interfaces aan. -**OpenAiOfficialChatModel** - Geünificeerde client voor OpenAI en Azure OpenAI modellen. +**OpenAiOfficialChatModel** - Gefedereerde client voor OpenAI en Azure OpenAI modellen. **OpenAiOfficialEmbeddingModel** - Maakt embeddings met OpenAI Official client (ondersteunt OpenAI en Azure OpenAI). **ChatModel** - Kerninterface voor taalmodellen. -**ChatMemory** - Onderhoudt gespreksgeschiedenis. +**ChatMemory** - Houdt de gesprekshistorie bij. **ContentRetriever** - Vindt relevante documentstukken voor RAG. -**DocumentSplitter** - Splitst documenten in stukken. +**DocumentSplitter** - Verdeelt documenten in stukken. **EmbeddingModel** - Zet tekst om in numerieke vectoren. **EmbeddingStore** - Slaat embeddings op en haalt ze op. -**MessageWindowChatMemory** - Onderhoudt schuivend venster van recente berichten. +**MessageWindowChatMemory** - Houdt een schuifvenster bij van recente berichten. -**PromptTemplate** - Maakt herbruikbare prompts met `{{variable}}` placeholders. +**PromptTemplate** - Maakt herbruikbare prompts met `{{variable}}`-plaatsen. **TextSegment** - Tekststuk met metadata. Gebruikt in RAG. -**ToolExecutionRequest** - Vertegenwoordigt verzoek tot uitvoering van een tool. +**ToolExecutionRequest** - Vertegenwoordigt een tooluitvoeringsverzoek. -**UserMessage / AiMessage / SystemMessage** - Gespreksberichttypen. +**UserMessage / AiMessage / SystemMessage** - Gesprekstypen berichten. ## AI/ML Concepten -**Few-Shot Learning** - Voorbeelden geven in prompts. [Module 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Voorzien van voorbeelden in prompts. [Module 02](../02-prompt-engineering/README.md) -**Groot Taalmodel (LLM)** - AI modellen getraind op enorme hoeveelheden tekstdata. +**Large Language Model (LLM)** - AI-modellen getraind op enorme hoeveelheden tekst. -**Redeneerinspanning** - GPT-5.2 parameter die diepgang van denken aanstuurt. [Module 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - GPT-5.2 parameter die de diepte van het denken regelt. [Module 02](../02-prompt-engineering/README.md) -**Temperatuur** - Stuurt de willekeurigheid van output. Laag=deterministisch, hoog=creatief. +**Temperatuur** - Stuurt de willekeurigheid van output aan. Laag=deterministisch, hoog=creatief. **Vector Database** - Gespecialiseerde database voor embeddings. [Module 03](../03-rag/README.md) **Zero-Shot Learning** - Taken uitvoeren zonder voorbeelden. [Module 02](../02-prompt-engineering/README.md) -## Guardrails - [Module 00](../00-quick-start/README.md) +## Beveiligingsmaatregelen -**Defense in Depth** - Meerlaagse beveiligingsaanpak die guardrails op applicatieniveau combineert met provider veiligheidsfilters. +**Defense in Depth** - Meerdere beveiligingslagen die applicatiebeveiliging combineren met provider veiligheidsfilters. -**Hard Block** - Provider gooit HTTP 400 fout bij ernstige inhoudsovertredingen. +**Hard Block** - Provider geeft HTTP 400 fout bij ernstige inhoudsovertredingen. -**InputGuardrail** - LangChain4j interface om gebruikersinput te valideren voordat het LLM bereikt. Bespaart kosten en latency door schadelijke prompts vroeg te blokkeren. +**InputGuardrail** - LangChain4j interface voor validatie van gebruikersinvoer voordat die bij het LLM terechtkomt. Bespaart kosten en vertraging door schadelijke prompts vroeg te blokkeren. -**InputGuardrailResult** - Retourtype voor guardrail validatie: `success()` of `fatal("reden")`. +**InputGuardrailResult** - Retourtype voor beveiligingsvalidatie: `success()` of `fatal("reden")`. -**OutputGuardrail** - Interface om AI-antwoorden te valideren voordat ze aan gebruikers teruggegeven worden. +**OutputGuardrail** - Interface voor het valideren van AI-antwoorden voordat ze aan gebruikers worden teruggegeven. -**Provider Safety Filters** - Ingebouwde inhoudsfilters van AI providers (bijv. GitHub Models) die overtredingen afvangen op API niveau. +**Provider Safety Filters** - Ingebouwde inhoudsfilters van AI-providers (zoals Azure OpenAI) die overtredingen op API-niveau onderscheppen. -**Soft Refusal** - Model weigert beleefd te antwoorden zonder foutmelding. +**Soft Refusal** - Model weigert beleefd om te antwoorden zonder een foutmelding te geven. ## Prompt Engineering - [Module 02](../02-prompt-engineering/README.md) **Chain-of-Thought** - Stapsgewijze redenatie voor betere nauwkeurigheid. -**Beperkte Output** - Het afdwingen van specifiek formaat of structuur. +**Constrained Output** - Afdwingen van een specifiek formaat of structuur. -**Hoge Eifories** - GPT-5.2 patroon voor grondige redenering. +**High Eagerness** - GPT-5.2 patroon voor grondige redenering. -**Lage Eifories** - GPT-5.2 patroon voor snelle antwoorden. +**Low Eagerness** - GPT-5.2 patroon voor snelle antwoorden. -**Multi-Turn Conversatie** - Context behouden over meerdere uitwisselingen. +**Multi-Turn Conversation** - Context behouden over meerdere uitwisselingen. -**Rolgebaseerde Prompting** - Instellen van modelpersona via system berichten. +**Role-Based Prompting** - Modelpersoon instellen via systeemberichten. -**Zelfreflectie** - Model evalueert en verbetert zijn output. +**Self-Reflection** - Model evalueert en verbetert zijn eigen output. -**Gestructureerde Analyse** - Vaste evaluatiekader. +**Structured Analysis** - Vast evaluatiekader. -**Taakuitvoeringspatroon** - Plannen → Uitvoeren → Samenvatten. +**Task Execution Pattern** - Plannen → Uitvoeren → Samenvatten. ## RAG (Retrieval-Augmented Generation) - [Module 03](../03-rag/README.md) -**Documentverwerkingspipeline** - Laden → opdelen → embedden → opslaan. +**Document Processing Pipeline** - Laden → opdelen → embedden → opslaan. -**In-Memory Embedding Store** - Niet-persistent opslag voor testen. +**In-Memory Embedding Store** - Niet-persistente opslag voor testen. -**RAG** - Combineert ophalen met generatie om antwoorden te funderen. +**RAG** - Combineert ophalen met genereren om antwoorden te funderen. -**Gelijkenisscore** - Maat (0-1) van semantische gelijkenis. +**Similarity Score** - Maat (0-1) van semantische gelijkenis. -**Bronvermelding** - Metadata over opgehaalde inhoud. +**Source Reference** - Metadata over opgehaalde inhoud. ## Agenten en Tools - [Module 04](../04-tools/README.md) -**@Tool Annotatie** - Markeert Java methoden als AI-oproepbare tools. +**@Tool Annotatie** - Markeert Java-methoden als AI-oproepbare tools. -**ReAct Patroon** - Redeneer → Handel → Observeer → Herhaal. +**ReAct Pattern** - Redeneren → Handelen → Observeren → Herhalen. -**Sessiebeheer** - Gescheiden contexten voor verschillende gebruikers. +**Session Management** - Gescheiden contexten voor verschillende gebruikers. -**Tool** - Functie die een AI agent kan aanroepen. +**Tool** - Functie die een AI-agent kan aanroepen. -**Tool Beschrijving** - Documentatie van tool doel en parameters. +**Tool Description** - Documentatie over doel en parameters van tool. ## Agentic Module - [Module 05](../05-mcp/README.md) -**@Agent Annotatie** - Markeert interfaces als AI agenten met declaratieve gedragsdefinitie. +**@Agent Annotatie** - Markeert interfaces als AI-agenten met declaratieve gedragsdefinitie. **Agent Listener** - Hook voor monitoring van agentuitvoering via `beforeAgentInvocation()` en `afterAgentInvocation()`. -**Agentic Scope** - Gedeeld geheugen waar agenten output opslaan met `outputKey` voor andere agenten. +**Agentic Scope** - Gedeeld geheugen waar agenten uitvoer opslaan met `outputKey` voor andere agenten om te gebruiken. -**AgenticServices** - Factory voor creëren van agenten via `agentBuilder()` en `supervisorBuilder()`. +**AgenticServices** - Fabriek voor het maken van agenten met `agentBuilder()` en `supervisorBuilder()`. -**Conditionele Workflow** - Route op basis van condities naar verschillende specialistagenten. +**Conditional Workflow** - Routeren naar verschillende specialistische agenten op basis van voorwaarden. -**Human-in-the-Loop** - Workflowpatroon met menselijke checkpoints voor goedkeuring of inhoudscontrole. +**Human-in-the-Loop** - Workflow patroon met menselijke controlepunten voor goedkeuring of inhoudsbeoordeling. -**langchain4j-agentic** - Maven dependency voor declaratief agentbouw (experimenteel). +**langchain4j-agentic** - Maven dependency voor declaratief agenten bouwen (experimenteel). -**Loop Workflow** - Itereer agentuitvoering tot aan een conditie voldaan is (bijv. kwaliteitscore ≥ 0.8). +**Loop Workflow** - Agent-uitvoering herhalen tot aan een voorwaarde is voldaan (bijv. kwaliteitscore ≥ 0.8). -**outputKey** - Agent annotatieparameter die aangeeft waar resultaten in Agentic Scope worden opgeslagen. +**outputKey** - Agentannotatieparameter die aangeeft waar resultaten in de Agentic Scope worden opgeslagen. -**Parallel Workflow** - Meerdere agenten tegelijk uitvoeren voor onafhankelijke taken. +**Parallel Workflow** - Meerdere agenten gelijktijdig laten draaien voor onafhankelijke taken. -**Responsstrategie** - Hoe supervisor het eindantwoord formuleert: LAST, SUMMARY, of SCORED. +**Response Strategy** - Hoe de supervisor het eindantwoord formuleert: LAATSTE, SAMENVATTING, of SCORE. -**Sequentiële Workflow** - Agenten in volgorde uitvoeren waarbij output naar volgende stap stroomt. +**Sequential Workflow** - Agenten opeenvolgend uitvoeren waarbij output gebruikt wordt voor de volgende stap. -**Supervisor Agent Patroon** - Geavanceerd agentic patroon waar een supervisor LLM dynamisch beslist welke sub-agenten aan te roepen. +**Supervisor Agent Pattern** - Geavanceerd agentisch patroon waarbij een supervisor LLM dynamisch bepaalt welke sub-agenten worden aangeroepen. ## Model Context Protocol (MCP) - [Module 05](../05-mcp/README.md) **langchain4j-mcp** - Maven dependency voor MCP integratie in LangChain4j. -**MCP** - Model Context Protocol: standaard voor koppeling van AI-apps aan externe tools. Eénmaal bouwen, overal gebruiken. +**MCP** - Model Context Protocol: standaard voor het koppelen van AI-apps aan externe tools. Eenmaal bouwen, overal gebruiken. -**MCP Client** - Applicatie die verbinding maakt met MCP servers om tools te ontdekken en te gebruiken. +**MCP Client** - Applicatie die verbinding maakt met MCP-servers om tools te ontdekken en gebruiken. -**MCP Server** - Dienst die tools via MCP aanbiedt met duidelijke beschrijvingen en parameterschema's. +**MCP Server** - Dienst die tools via MCP blootstelt met duidelijke beschrijvingen en parameterschema’s. -**McpToolProvider** - LangChain4j component die MCP tools wrappet voor gebruik in AI services en agenten. +**McpToolProvider** - LangChain4j component die MCP-tools verpakt voor gebruik in AI-services en agenten. -**McpTransport** - Interface voor MCP communicatie. Implementaties omvatten Stdio en HTTP. +**McpTransport** - Interface voor MCP-communicatie. Implementaties omvatten Stdio en HTTP. -**Stdio Transport** - Lokale procestransport via stdin/stdout. Handig voor bestandsysteemtoegang of commandoregeltools. +**Stdio Transport** - Lokale procestransport via stdin/stdout. Handig voor bestandssysteemtoegang of commandoregeltools. -**StdioMcpTransport** - LangChain4j implementatie die MCP server als subprocess start. +**StdioMcpTransport** - LangChain4j-implementatie die MCP-server als subprocess opstart. -**Tool Discovery** - Client vraagt server om beschikbare tools met beschrijvingen en schema's. +**Tool Discovery** - Client vraagt server om beschikbare tools met beschrijvingen en schema’s. ## Azure Diensten - [Module 01](../01-introduction/README.md) -**Azure AI Search** - Cloud-zoekdienst met vectormogelijkheden. [Module 03](../03-rag/README.md) +**Azure AI Search** - Cloud-zoekdienst met vectorfunctionaliteit. [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Zet Azure resources uit. +**Azure Developer CLI (azd)** - Zet Azure-resources uit. -**Azure OpenAI** - Microsoft's enterprise AI-dienst. +**Azure OpenAI** - Enterprise AI-dienst van Microsoft. -**Bicep** - Azure infrastructuur-als-code taal. [Infrastructure Guide](../01-introduction/infra/README.md) +**Bicep** - Azure infrastructuur-als-code taal. [Infrastructuurhandleiding](../01-introduction/infra/README.md) -**Deployment Naam** - Naam voor modeldeployment in Azure. +**Deployment Name** - Naam voor modelimplementatie in Azure. -**GPT-5.2** - Laatste OpenAI model met redeneersturing. [Module 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Nieuwste OpenAI-model met redeneerbesturing. [Module 02](../02-prompt-engineering/README.md) -## Testen en Ontwikkeling - [Testing Guide](TESTING.md) +## Testen en Ontwikkeling - [Testhandleiding](TESTING.md) -**Dev Container** - Containerized ontwikkelomgeving. [Configuratie](../../../.devcontainer/devcontainer.json) +**Dev Container** - Gecontaineriseerde ontwikkelomgeving. [Configuratie](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Gratis AI model playground. [Module 00](../00-quick-start/README.md) - -**In-Memory Testing** - Testen met in-memory opslag. +**In-Memory Testing** - Testen met geheugenopslag. **Integratietesten** - Testen met echte infrastructuur. -**Maven** - Java build automatiseringstool. +**Maven** - Java bouwautomatiseringstool. -**Mockito** - Java mocking framework. +**Mockito** - Java mocking-framework. **Spring Boot** - Java applicatiekader. [Module 01](../01-introduction/README.md) @@ -228,5 +226,5 @@ Snelle referentie voor termen en concepten die door de cursus heen worden gebrui **Disclaimer**: -Dit document is vertaald met behulp van de AI vertaaldienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal wordt beschouwd als de gezaghebbende bron. Voor cruciale informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. +Dit document is vertaald met behulp van de AI vertaaldienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. \ No newline at end of file diff --git a/translations/nl/docs/TESTING.md b/translations/nl/docs/TESTING.md index ceb1e3f2c..4fb944dcc 100644 --- a/translations/nl/docs/TESTING.md +++ b/translations/nl/docs/TESTING.md @@ -1,20 +1,20 @@ -# LangChain4j-toepassingen testen +# Testen van LangChain4j-toepassingen ## Inhoudsopgave -- [Snel aan de slag](../../../docs) -- [Wat de tests omvatten](../../../docs) -- [De tests uitvoeren](../../../docs) -- [Tests uitvoeren in VS Code](../../../docs) -- [Testpatronen](../../../docs) -- [Testfilosofie](../../../docs) -- [Volgende stappen](../../../docs) +- [Snel aan de slag](#snel-aan-de-slag) +- [Wat de tests dekken](#wat-de-tests-dekken) +- [De tests uitvoeren](#de-tests-uitvoeren) +- [Tests uitvoeren in VS Code](#tests-uitvoeren-in-vs-code) +- [Testpatronen](#testpatronen) +- [Testfilosofie](#testfilosofie) +- [Volgende stappen](#volgende-stappen) -Deze gids begeleidt je door de tests die laten zien hoe je AI-toepassingen test zonder API-sleutels of externe diensten. +Deze gids begeleidt je door de tests die aantonen hoe je AI-toepassingen kunt testen zonder API-sleutels of externe services. ## Snel aan de slag -Voer alle tests uit met één opdracht: +Voer alle tests uit met één commando: **Bash:** ```bash @@ -26,28 +26,27 @@ mvn test mvn --% test ``` -Wanneer alle tests slagen, zie je een uitvoer zoals de onderstaande schermafbeelding — tests lopen zonder fouten. +Als alle tests slagen, zie je output zoals in de onderstaande schermafbeelding — tests worden uitgevoerd zonder fouten. Successful Test Results -*Succesvol testresultaat waarbij alle tests slagen zonder fouten* +*Succesvolle testuitvoering waarbij alle tests zonder fouten slagen* -## Wat de tests omvatten +## Wat de tests dekken -Deze cursus richt zich op **unittests** die lokaal draaien. Elke test toont een specifiek LangChain4j-concept geïsoleerd aan. De onderstaande testpiramide laat zien waar unittests passen — zij vormen de snelle, betrouwbare basis waarop de rest van je teststrategie is gebouwd. +Deze cursus richt zich op **unittests** die lokaal draaien. Elke test demonstreert een specifiek LangChain4j-concept geïsoleerd. De onderstaande testpiramide toont waar unittests passen — ze vormen de snelle, betrouwbare basis waarop de rest van je teststrategie is gebouwd. Testing Pyramid -*Testpiramide die het evenwicht toont tussen unittests (snel, geïsoleerd), integratietests (echte componenten) en end-to-end tests. Deze training behandelt unittests.* +*Testpiramide die de balans toont tussen unittests (snel, geïsoleerd), integratietests (echte componenten) en end-to-end tests. Deze training behandelt unittesten.* -| Module | Tests | Focus | Belangrijke Bestanden | -|--------|-------|-------|-----------------------| -| **00 - Snel aan de slag** | 6 | Prompttemplates en variabelensubstitutie | `SimpleQuickStartTest.java` | -| **01 - Introductie** | 8 | Gesprekgeheugen en stateful chat | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | GPT-5.2-patronen, eagerness-niveaus, gestructureerde output | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Documentinname, embeddings, gelijkeniszoektocht | `DocumentServiceTest.java` | -| **04 - Tools** | 12 | Functieaanroepen en ketting van tools | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol met Stdio-transport | `SimpleMcpTest.java` | +| Module | Tests | Focus | Belangrijke bestanden | +|--------|-------|-------|---------------------| +| **01 - Introductie** | 8 | Gespreksgeheugen en stateful chat | `SimpleConversationTest.java` | +| **02 - Prompt Engineering** | 12 | GPT-5.2-patronen, zorgvuldigheidsniveaus, gestructureerde output | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Documentinname, embeddings, zoekopdracht op gelijkenis | `DocumentServiceTest.java` | +| **04 - Tools** | 12 | Functie-aanroepen en het ketenen van tools | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol met Stdio transport | `SimpleMcpTest.java` | ## De tests uitvoeren @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Tests uitvoeren voor een specifieke module:** +**Tests uitvoeren voor een specifiek module:** **Bash:** ```bash @@ -75,7 +74,7 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Of vanaf root +# Of vanuit root mvn --% test -pl 01-introduction ``` @@ -95,41 +94,41 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#gesprekgeschiedenis behouden +mvn test -Dtest=SimpleConversationTest#gesprekshistorie behouden ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#moetHetGespreksverledenBewaren +mvn --% test -Dtest=SimpleConversationTest#moetGespreksgeschiedenisBehouden ``` ## Tests uitvoeren in VS Code -Als je Visual Studio Code gebruikt, biedt de Test Explorer een grafische interface om tests uit te voeren en te debuggen. +Als je Visual Studio Code gebruikt, biedt de Test Explorer een grafische interface voor het uitvoeren en debuggen van tests. VS Code Test Explorer -*VS Code Test Explorer toont de testboom met alle Java-testklassen en individuele testmethoden* +*VS Code Test Explorer die de teststructuur toont met alle Java-testklassen en individuele testmethodes* **Tests uitvoeren in VS Code:** -1. Open de Test Explorer door op het bekerglas-icoon in de activiteitenbalk te klikken -2. Vouw de testboom uit om alle modules en testklassen te zien -3. Klik op de afspeelknop naast een test om deze individueel uit te voeren -4. Klik op "Run All Tests" om de gehele suite uit te voeren -5. Klik met de rechtermuisknop op een test en selecteer "Debug Test" om breakpoints te zetten en stap voor stap door de code te lopen +1. Open de Test Explorer door op het bekerglas-icoon in de Activiteitenbalk te klikken +2. Vouw de teststructuur uit om alle modules en testklassen te zien +3. Klik op de afspeelknop naast een test om die afzonderlijk uit te voeren +4. Klik op "Run All Tests" om de volledige suite uit te voeren +5. Klik rechts op een test en selecteer "Debug Test" om breakpoints te zetten en door de code te stappen -De Test Explorer toont groene vinkjes bij geslaagde tests en geeft gedetailleerde foutmeldingen als tests falen. +De Test Explorer toont groene vinkjes bij geslaagde tests en geeft uitgebreide foutmeldingen wanneer tests mislukken. ## Testpatronen -### Patroon 1: Prompttemplates testen +### Patroon 1: Testen van prompttemplates -Het eenvoudigste patroon test prompttemplates zonder enig AI-model aan te roepen. Je controleert of variabelensubstitutie correct werkt en prompts zoals verwacht worden opgemaakt. +Het eenvoudigste patroon test prompttemplates zonder een AI-model aan te roepen. Je controleert dat variabelen correct worden vervangen en prompts juist zijn opgemaakt. Prompt Template Testing -*Prompttemplates testen die de stroom van variabelensubstitutie laten zien: template met placeholders → toegepaste waarden → geformatteerde output gecontroleerd* +*Testen van prompttemplates waarbij de variabelenvervanging wordt doorlopen: template met placeholders → waarden toegepast → geformatteerde output gecontroleerd* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Deze test staat in `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Voer uit:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testPromptTemplateOpmaak -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatteren -``` +Dit patroon controleert dat variabelen correct worden vervangen en prompts correct worden opgemaakt — er is geen API-sleutel of model-aanroep nodig. -### Patroon 2: Taalmodellen mocken +### Patroon 2: Mocken van taalmodellen -Bij het testen van conversatielogica gebruik je Mockito om nepmodellen te maken die vooraf bepaalde antwoorden teruggeven. Dit maakt tests snel, gratis en deterministisch. +Bij het testen van conversatielogica gebruik je Mockito om nepmodellen te maken die van tevoren bepaalde antwoorden teruggeven. Dit maakt tests snel, gratis en deterministisch. Mock vs Real API Comparison -*Vergelijking waarom mocks de voorkeur hebben voor testen: ze zijn snel, gratis, deterministisch en vereisen geen API-sleutels* +*Vergelijking die laat zien waarom mocks de voorkeur hebben voor testen: ze zijn snel, gratis, deterministisch en vereisen geen API-sleutels* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 gebruikers + 3 AI-berichten + assertThat(history).hasSize(6); // 3 gebruikers + 3 AI berichten } } ``` -Dit patroon verschijnt in `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. De mock zorgt voor consistent gedrag zodat je kunt verifiëren dat geheugenbeheer correct werkt. +Dit patroon wordt gebruikt in `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. De mock zorgt voor consistent gedrag zodat geheugenbeheer correct kan worden geverifieerd. -### Patroon 3: Gespreksisolatie testen +### Patroon 3: Testen van conversatie-isolatie -Gesprekgeheugen moet meerdere gebruikers gescheiden houden. Deze test controleert dat gesprekken geen contexten vermengen. +Gespreksgeheugen moet meerdere gebruikers gescheiden houden. Deze test controleert dat gesprekken geen contexten door elkaar halen. Conversation Isolation -*Gespreksisolatie testen waarbij aparte geheugens voor verschillende gebruikers worden getoond om contextvermenging te voorkomen* +*Testen van conversatie-isolatie waarbij aparte geheugens voor verschillende gebruikers worden gebruikt om contextverwarring te voorkomen* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Elk gesprek onderhoudt zijn eigen onafhankelijke geschiedenis. In productieomgevingen is deze isolatie cruciaal voor multi-gebruikersapplicaties. +Elk gesprek behoudt zijn eigen onafhankelijke geschiedenis. In productiesystemen is deze isolatie cruciaal voor multi-gebruikertoepassingen. ### Patroon 4: Tools onafhankelijk testen -Tools zijn functies die de AI kan aanroepen. Test ze direct om te zorgen dat ze correct werken, ongeacht AI-beslissingen. +Tools zijn functies die de AI kan aanroepen. Test ze rechtstreeks om zeker te zijn dat ze correct werken, onafhankelijk van AI-beslissingen. Tools Testing -*Tools onafhankelijk testen waarbij nepuitvoering van tools is afgebeeld zonder AI-aanroepen om bedrijfslogica te controleren* +*Onafhankelijk testen van tools waarbij een nep-uitvoering van tools wordt getoond zonder AI-aanroepen om de bedrijfslogica te verifiëren* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Deze tests uit `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` valideren toollogica zonder AI-betrokkenheid. Het kettingvoorbeeld toont hoe de output van de ene tool als input van een andere wordt gebruikt. +Deze tests uit `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` valideren tool-logica zonder AI-betrokkenheid. Het ketenvoorbeeld laat zien hoe de output van de ene tool de input van een andere voedt. -### Patroon 5: RAG testen in het geheugen +### Patroon 5: In-memory RAG-testen -RAG-systemen vereisen traditioneel vectordatabases en embeddingdiensten. Het in-geheugen-patroon maakt het mogelijk om de hele pijplijn te testen zonder externe afhankelijkheden. +RAG-systemen vereisen traditioneel vectordatabases en embeddingservices. Het in-memory-patroon laat je de volledige pipeline testen zonder externe afhankelijkheden. In-Memory RAG Testing -*RAG-testworkflow in het geheugen met documentanalyse, embeddingopslag en gelijkeniszoektocht zonder dat een database nodig is* +*In-memory RAG-testworkflow die documentparsing, embedding-opslag, en gelijkeniszoeken toont zonder databasevereisten* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Deze test van `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` maakt een document in het geheugen en controleert chunking en metadata-afhandeling. +Deze test uit `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` maakt een document in het geheugen en controleert chunking en metadata-afhandeling. ### Patroon 6: MCP-integratietesten -De MCP-module test de Model Context Protocol-integratie met stdio-transport. Deze tests verifiëren dat je applicatie MCP-servers kan starten en ermee kan communiceren als subprocessen. +De MCP-module test de Model Context Protocol-integratie met stdio transport. Deze tests verifiëren dat je applicatie MCP-servers als subprocessen kan starten en ermee kan communiceren. -De tests in `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` valideren het MCP-clientgedrag. +De tests in `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` valideren het gedrag van de MCP-client. **Voer ze uit:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Testfilosofie -Test je code, niet de AI. Je tests moeten de code valideren die je schrijft door te controleren hoe prompts worden geconstrueerd, hoe geheugen wordt beheerd en hoe tools worden uitgevoerd. AI-antwoorden variëren en horen geen deel uit te maken van testasserties. Vraag jezelf af of je prompttemplate variabelen correct vervangt, niet of de AI het juiste antwoord geeft. +Test je code, niet de AI. Je tests moeten de code die je schrijft valideren door te controleren hoe prompts worden opgebouwd, hoe geheugen wordt beheerd en hoe tools worden uitgevoerd. AI-antwoorden variëren en mogen geen onderdeel van testasserties zijn. Vraag jezelf af of je prompttemplate correct variabelen vervangt, niet of de AI het juiste antwoord geeft. -Gebruik mocks voor taalmodellen. Dit zijn externe afhankelijkheden die traag, duur en niet-deterministisch zijn. Mocken maakt tests snel met milliseconden in plaats van seconden, gratis zonder API-kosten, en deterministisch met steeds hetzelfde resultaat. +Gebruik mocks voor taalmodellen. Ze zijn externe afhankelijkheden die traag, duur en niet-deterministisch zijn. Mocking maakt tests snel met milliseconden in plaats van seconden, gratis zonder API-kosten, en deterministisch met steeds hetzelfde resultaat. -Houd tests onafhankelijk. Elke test moet eigen data opzetten, niet afhankelijk zijn van andere tests, en zichzelf opruimen. Tests moeten slagen ongeacht de uitvoervolgorde. +Houd tests onafhankelijk. Elke test moet zijn eigen data opzetten, niet afhankelijk zijn van andere tests, en opruimen na zichzelf. Tests moeten slagen ongeacht de uitvoeringsvolgorde. -Test randgevallen buiten het gelukkige pad. Probeer lege inputs, zeer grote inputs, speciale tekens, ongeldige parameters en grenswaarden. Deze onthullen vaak bugs die normaal gebruik niet laat zien. +Test randgevallen buiten het gelukkige pad. Probeer lege invoer, zeer grote invoer, speciale tekens, ongeldige parameters en grensvoorwaarden. Deze onthullen vaak bugs die normaal gebruik niet blootlegt. -Gebruik beschrijvende namen. Vergelijk `shouldMaintainConversationHistoryAcrossMultipleMessages()` met `test1()`. De eerste vertelt precies wat getest wordt, wat debuggen veel makkelijker maakt. +Gebruik beschrijvende namen. Vergelijk `shouldMaintainConversationHistoryAcrossMultipleMessages()` met `test1()`. De eerste vertelt precies wat er getest wordt en maakt het debuggen van fouten veel eenvoudiger. ## Volgende stappen Nu je de testpatronen begrijpt, duik dieper in elke module: -- **[00 - Snel aan de slag](../00-quick-start/README.md)** - Begin met de basis van prompttemplates - **[01 - Introductie](../01-introduction/README.md)** - Leer gesprekgeheugenbeheer -- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Beheers GPT-5.2 promptpatronen -- **[03 - RAG](../03-rag/README.md)** - Bouw retrieval-augmented generation-systemen -- **[04 - Tools](../04-tools/README.md)** - Implementeer functieaanroepen en toolketens -- **[05 - MCP](../05-mcp/README.md)** - Integreer Model Context Protocol +- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Beheers GPT-5.2-promptpatronen +- **[03 - RAG](../03-rag/README.md)** - Bouw retrieval-augmented generation systemen +- **[04 - Tools](../04-tools/README.md)** - Implementeer functie-aanroepen en toolketens +- **[05 - MCP](../05-mcp/README.md)** - Integreer het Model Context Protocol -De README van elke module biedt gedetailleerde uitleg over de concepten die hier getest worden. +De README van elke module biedt gedetailleerde uitleg over de concepten die hier worden getest. --- -**Navigatie:** [← Terug naar hoofdmenu](../README.md) +**Navigatie:** [← Terug naar Hoofdmenu](../README.md) --- **Disclaimer**: -Dit document is vertaald met behulp van de AI-vertalingsdienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat automatische vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het oorspronkelijke document in de originele taal dient als gezaghebbende bron te worden beschouwd. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. +Dit document is vertaald met behulp van de AI vertaaldienst [Co-op Translator](https://github.com/Azure/co-op-translator). Hoewel we streven naar nauwkeurigheid, dient u er rekening mee te houden dat geautomatiseerde vertalingen fouten of onnauwkeurigheden kunnen bevatten. Het originele document in de oorspronkelijke taal moet worden beschouwd als de gezaghebbende bron. Voor kritieke informatie wordt professionele menselijke vertaling aanbevolen. Wij zijn niet aansprakelijk voor eventuele misverstanden of verkeerde interpretaties die voortvloeien uit het gebruik van deze vertaling. \ No newline at end of file diff --git a/translations/no/.co-op-translator.json b/translations/no/.co-op-translator.json index ba46025fb..71ff097a3 100644 --- a/translations/no/.co-op-translator.json +++ b/translations/no/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "no" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T23:27:10+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T12:15:59+00:00", "source_file": "01-introduction/README.md", "language_code": "no" }, @@ -18,20 +18,20 @@ "language_code": "no" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T23:29:08+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T12:11:13+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "no" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T23:30:41+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T12:15:06+00:00", "source_file": "03-rag/README.md", "language_code": "no" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:20:03+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T12:13:42+00:00", "source_file": "04-tools/README.md", "language_code": "no" }, @@ -54,8 +54,8 @@ "language_code": "no" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:07:41+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T12:09:54+00:00", "source_file": "README.md", "language_code": "no" }, @@ -72,14 +72,14 @@ "language_code": "no" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T23:33:49+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T12:11:48+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "no" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T23:34:30+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T12:12:27+00:00", "source_file": "docs/TESTING.md", "language_code": "no" } diff --git a/translations/no/00-quick-start/README.md b/translations/no/00-quick-start/README.md deleted file mode 100644 index 05e781ad0..000000000 --- a/translations/no/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modul 00: Rask Start - -## Innholdsfortegnelse - -- [Introduksjon](../../../00-quick-start) -- [Hva er LangChain4j?](../../../00-quick-start) -- [LangChain4j Avhengigheter](../../../00-quick-start) -- [Forutsetninger](../../../00-quick-start) -- [Oppsett](../../../00-quick-start) - - [1. Skaff GitHub-tokenet ditt](../../../00-quick-start) - - [2. Sett tokenet ditt](../../../00-quick-start) -- [Kjør Eksemplene](../../../00-quick-start) - - [1. Grunnleggende Chat](../../../00-quick-start) - - [2. Prompt Mønstre](../../../00-quick-start) - - [3. Funksjonskall](../../../00-quick-start) - - [4. Dokument Spørsmål & Svar (Easy RAG)](../../../00-quick-start) - - [5. Ansvarlig AI](../../../00-quick-start) -- [Hva Hvert Eksempel Viser](../../../00-quick-start) -- [Neste Steg](../../../00-quick-start) -- [Feilsøking](../../../00-quick-start) - -## Introduksjon - -Denne raske starten er ment å komme i gang med LangChain4j så raskt som mulig. Den dekker det absolutte grunnlaget for å bygge AI-applikasjoner med LangChain4j og GitHub Models. I de neste modulene vil du bytte til Azure OpenAI og GPT-5.2 og gå dypere inn i hvert konsept. - -## Hva er LangChain4j? - -LangChain4j er et Java-bibliotek som forenkler bygging av AI-drevne applikasjoner. I stedet for å håndtere HTTP-klienter og JSON-parsing, jobber du med rene Java-APIer. - -"Chain" i LangChain refererer til å koble sammen flere komponenter – du kan kjede en prompt til en modell til en parser, eller kjede flere AI-kall sammen hvor ett output mates inn som input til det neste. Denne raske starten fokuserer på det grunnleggende før du utforsker mer komplekse kjeder. - -LangChain4j Chaining Concept - -*Kjede av komponenter i LangChain4j – byggesteiner kobles sammen for å skape kraftige AI-arbeidsflyter* - -Vi bruker tre kjernekomponenter: - -**ChatModel** – Grensesnittet for AI-modellinteraksjoner. Kall `model.chat("prompt")` og få en responsstreng. Vi bruker `OpenAiOfficialChatModel` som fungerer med OpenAI-kompatible endepunkter som GitHub Models. - -**AiServices** – Lager typesikre AI-tjenestegrensesnitt. Definer metoder, annoter dem med `@Tool`, og LangChain4j håndterer orkestreringen. AI-en kaller automatisk Java-metodene dine når det trengs. - -**MessageWindowChatMemory** – Opprettholder samtalehistorikk. Uten dette er hver forespørsel uavhengig. Med dette husker AI tidligere meldinger og opprettholder kontekst over flere turer. - -LangChain4j Architecture - -*LangChain4j arkitektur – kjernekomponenter som samarbeider for å styrke AI-applikasjonene dine* - -## LangChain4j Avhengigheter - -Denne raske starten bruker tre Maven-avhengigheter i [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modulen `langchain4j-open-ai-official` tilbyr klassen `OpenAiOfficialChatModel` som kobler til OpenAI-kompatible APIer. GitHub Models bruker samme API-format, så det trengs ingen spesiell adapter – bare pek base-URL til `https://models.github.ai/inference`. - -Modulen `langchain4j-easy-rag` tilbyr automatisk dokumentdeling, embedding, og henting slik at du kan bygge RAG-applikasjoner uten manuelt oppsett av hvert steg. - -## Forutsetninger - -**Bruker du Dev Container?** Java og Maven er allerede installert. Du trenger kun en GitHub Personal Access Token. - -**Lokal utvikling:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (instruksjoner nedenfor) - -> **Merk:** Denne modulen bruker `gpt-4.1-nano` fra GitHub Models. Ikke endre modellnavnet i koden – det er konfigurert til å fungere med GitHubs tilgjengelige modeller. - -## Oppsett - -### 1. Skaff GitHub-tokenet ditt - -1. Gå til [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Klikk "Generate new token" -3. Sett et beskrivende navn (f.eks. "LangChain4j Demo") -4. Sett utløpstid (7 dager anbefales) -5. Under "Account permissions", finn "Models" og sett til "Read-only" -6. Klikk "Generate token" -7. Kopier og lagre tokenet – du får ikke se det igjen - -### 2. Sett tokenet ditt - -**Alternativ 1: Bruke VS Code (Anbefalt)** - -Hvis du bruker VS Code, legg tokenet ditt i `.env`-filen i prosjektets rotmappe: - -Hvis `.env`-filen ikke finnes, kopier `.env.example` til `.env` eller opprett en ny `.env`-fil i prosjektets rotmappe. - -**Eksempel på `.env`-fil:** -```bash -# I /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Da kan du enkelt høyreklikke på en demo-fil (f.eks. `BasicChatDemo.java`) i Explorer og velge **"Run Java"** eller bruke oppstartskonfigurasjonene fra Run and Debug-panelet. - -**Alternativ 2: Bruke Terminal** - -Sett tokenet som en miljøvariabel: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Kjør Eksemplene - -**Bruke VS Code:** Høyreklikk på en demo-fil i Explorer og velg **"Run Java"**, eller bruk oppstartskonfigurasjonene fra Run and Debug-panelet (sørg for at du har lagt til tokenet i `.env`-filen først). - -**Bruke Maven:** Alternativt kan du kjøre fra kommandolinjen: - -### 1. Grunnleggende Chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Prompt Mønstre - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Viser zero-shot, few-shot, chain-of-thought og rollebasert prompting. - -### 3. Funksjonskall - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI-en kaller automatisk Java-metodene dine når det trengs. - -### 4. Dokument Spørsmål & Svar (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Still spørsmål om dokumentene dine ved hjelp av Easy RAG med automatisk embedding og gjenfinning. - -### 5. Ansvarlig AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Se hvordan AI-sikkerhetsfiltre blokkerer skadelig innhold. - -## Hva Hvert Eksempel Viser - -**Grunnleggende Chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Start her for å se LangChain4j på sitt enkleste. Du lager en `OpenAiOfficialChatModel`, sender en prompt med `.chat()`, og får tilbake et svar. Dette viser grunnlaget: hvordan initialisere modeller med egendefinerte endepunkter og API-nøkler. Når du forstår dette mønsteret, bygger alt annet på det. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) og spør: -> - "Hvordan bytter jeg fra GitHub Models til Azure OpenAI i denne koden?" -> - "Hvilke andre parametere kan jeg konfigurere i OpenAiOfficialChatModel.builder()?" -> - "Hvordan legger jeg til streaming-respons i stedet for å vente på hele responsen?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Nå som du vet hvordan du snakker med en modell, la oss utforske hva du sier til den. Denne demoen bruker samme modelloppsett, men viser fem forskjellige prompting-mønstre. Prøv zero-shot prompts for direkte instruksjoner, few-shot prompts som lærer fra eksempler, chain-of-thought prompts som viser resonnementstrinn, og rollebaserte prompts som setter kontekst. Du vil se hvordan samme modell gir dramatisk forskjellige resultater basert på hvordan du formulerer forespørselen din. - -Demoen viser også prompt-maler, som er en kraftig måte å lage gjenbrukbare prompts med variabler. -Eksemplet nedenfor viser en prompt som bruker LangChain4j `PromptTemplate` til å fylle inn variabler. AI-en vil svare basert på gitt destinasjon og aktivitet. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) og spør: -> - "Hva er forskjellen på zero-shot og few-shot prompting, og når bør jeg bruke hver?" -> - "Hvordan påvirker temperaturparameter modellens svar?" -> - "Hva er noen teknikker for å forhindre prompt injection-angrep i produksjon?" -> - "Hvordan kan jeg lage gjenbrukbare PromptTemplate-objekter for vanlige mønstre?" - -**Verktøyintegrasjon** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Her blir LangChain4j kraftig. Du bruker `AiServices` for å lage en AI-assistent som kan kalle dine Java-metoder. Bare annoter metoder med `@Tool("beskrivelse")` og LangChain4j tar seg av resten – AI-en bestemmer automatisk når hver verktøy skal brukes basert på hva brukeren spør om. Dette demonstrerer funksjonskall, en nøkkelteknikk for å bygge AI som kan utføre handlinger, ikke bare svare på spørsmål. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) og spør: -> - "Hvordan fungerer @Tool-annotasjonen og hva gjør LangChain4j med den bak kulissene?" -> - "Kan AI kalle flere verktøy i rekkefølge for å løse komplekse problemer?" -> - "Hva skjer hvis et verktøy kaster en unntak – hvordan bør jeg håndtere feil?" -> - "Hvordan integrerer jeg en ekte API i stedet for dette kalkulator-eksempelet?" - -**Dokument Spørsmål & Svar (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Her ser du RAG (retrieval-augmented generation) ved hjelp av LangChain4js "Easy RAG"-metode. Dokumenter lastes inn, deles automatisk opp, og embedes i et minnelager. Deretter leverer en innholdshenter relevante biter til AI-en ved spørringstid. AI-en svarer basert på dokumentene dine, ikke på generell kunnskap. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) og spør: -> - "Hvordan hindrer RAG AI-hallusinasjoner sammenlignet med å bruke modellens treningsdata?" -> - "Hva er forskjellen på denne enkle metoden og en tilpasset RAG-pipeline?" -> - "Hvordan skalerer jeg dette til å håndtere flere dokumenter eller større kunnskapsbaser?" - -**Ansvarlig AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Bygg AI-sikkerhet med forsvar i dybden. Denne demoen viser to beskyttelseslag som samarbeider: - -**Del 1: LangChain4j Input Guardrails** – Blokker farlige prompts før de når LLM. Lag egne guardrails som sjekker for forbudte nøkkelord eller mønstre. Disse kjøres i koden din, så de er raske og gratis. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Del 2: Leverandørsikkerhetsfiltre** – GitHub Models har innebygde filtre som fanger opp det guardrails kanskje overser. Du vil se harde blokker (HTTP 400-feil) for alvorlige brudd og myke refusjoner hvor AI høflig avstår. - -> **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) og spør: -> - "Hva er InputGuardrail og hvordan lager jeg min egen?" -> - "Hva er forskjellen på en hard blokk og en myk refusjon?" -> - "Hvorfor bruke både guardrails og leverandørfiltre sammen?" - -## Neste Steg - -**Neste Modul:** [01-introduction - Komme i gang med LangChain4j](../01-introduction/README.md) - ---- - -**Navigasjon:** [← Tilbake til Hoved](../README.md) | [Neste: Modul 01 - Introduksjon →](../01-introduction/README.md) - ---- - -## Feilsøking - -### Første Maven Build - -**Problem:** Første `mvn clean compile` eller `mvn package` tar lang tid (10-15 minutter) - -**Årsak:** Maven må laste ned alle prosjektavhengigheter (Spring Boot, LangChain4j-biblioteker, Azure SDK-er, osv.) ved første bygg. - -**Løsning:** Dette er normal oppførsel. Etterfølgende bygg er mye raskere da avhengigheter caches lokalt. Nedlastningstid avhenger av nettverkshastighet. - -### PowerShell Maven Kommando-syntaks - -**Problem:** Maven-kommandoer feiler med feilmeldingen `Unknown lifecycle phase ".mainClass=..."` -**Årsak**: PowerShell tolker `=` som en variabeltilordningsoperator, noe som bryter Maven-egenskapssyntaksen - -**Løsning**: Bruk stopp-parsing-operatoren `--%` før Maven-kommandoen: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%`-operatoren forteller PowerShell å sende alle resterende argumenter bokstavelig til Maven uten tolkning. - -### Windows PowerShell Emoji-visning - -**Problem**: AI-svar viser søppelkarakterer (f.eks. `????` eller `â??`) i stedet for emojis i PowerShell - -**Årsak**: PowerShells standardkoding støtter ikke UTF-8-emoji - -**Løsning**: Kjør denne kommandoen før du kjører Java-applikasjoner: -```cmd -chcp 65001 -``` - -Dette tvinger UTF-8-koding i terminalen. Alternativt kan du bruke Windows Terminal som har bedre Unicode-støtte. - -### Feilsøking av API-kall - -**Problem**: Autentiseringsfeil, ratebegrensninger, eller uventede svar fra AI-modellen - -**Løsning**: Eksemplene inkluderer `.logRequests(true)` og `.logResponses(true)` for å vise API-kall i konsollen. Dette hjelper med å feilsøke autentiseringsfeil, ratebegrensninger eller uventede svar. Fjern disse flaggene i produksjon for å redusere loggstøy. - ---- - - -**Ansvarsfraskrivelse**: -Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vennligst vær oppmerksom på at automatiserte oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på dets opprinnelige språk skal betraktres som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. - \ No newline at end of file diff --git a/translations/no/01-introduction/README.md b/translations/no/01-introduction/README.md index 7000ba63b..1023d5801 100644 --- a/translations/no/01-introduction/README.md +++ b/translations/no/01-introduction/README.md @@ -1,38 +1,38 @@ -# Module 01: Komme i gang med LangChain4j +# Modul 01: Komme i gang med LangChain4j ## Innholdsfortegnelse -- [Video Gjennomgang](../../../01-introduction) -- [Hva Du Vil Lære](../../../01-introduction) -- [Forutsetninger](../../../01-introduction) -- [Forstå Kjernesproblemet](../../../01-introduction) -- [Forstå Token](../../../01-introduction) -- [Hvordan Minne Fungerer](../../../01-introduction) -- [Hvordan Dette Bruker LangChain4j](../../../01-introduction) -- [Distribuer Azure OpenAI Infrastruktur](../../../01-introduction) -- [Kjør Applikasjonen Lokalt](../../../01-introduction) -- [Bruke Applikasjonen](../../../01-introduction) - - [Stateless Chat (Venstre Panel)](../../../01-introduction) - - [Stateful Chat (Høyre Panel)](../../../01-introduction) -- [Neste Steg](../../../01-introduction) +- [Video Gjennomgang](#video-gjennomgang) +- [Det du vil lære](#det-du-vil-lære) +- [Forutsetninger](#forutsetninger) +- [Forstå kjernen i problemet](#forstå-kjernen-i-problemet) +- [Forstå tokens](#forstå-tokens) +- [Hvordan minnet fungerer](#hvordan-minnet-fungerer) +- [Hvordan dette bruker LangChain4j](#hvordan-dette-bruker-langchain4j) +- [Distribuer Azure OpenAI-infrastruktur](#distribuer-azure-openai-infrastruktur) +- [Kjør applikasjonen lokalt](#kjør-applikasjonen-lokalt) +- [Bruke applikasjonen](#bruke-applikasjonen) + - [Stateless Chat (venstre panel)](#stateless-chat-venstre-panel) + - [Stateful Chat (høyre panel)](#stateful-chat-høyre-panel) +- [Neste steg](#neste-steg) ## Video Gjennomgang -Se denne live-økten som forklarer hvordan du kommer i gang med denne modulen: +Se denne livesesjonen som forklarer hvordan du kommer i gang med denne modulen: -Getting Started with LangChain4j - Live Session +Komme i gang med LangChain4j - Livesesjon -## Hva Du Vil Lære +## Det du vil lære -I hurtigstarten brukte du GitHub-modeller for å sende forespørsler, kalle verktøy, bygge en RAG-pipeline, og teste vernesperrer. De demoene viste hva som er mulig — nå bytter vi til Azure OpenAI og GPT-5.2 og begynner å bygge produksjonsstil applikasjoner. Denne modulen fokuserer på samtale-AI som husker kontekst og opprettholder tilstand — konseptene som hurtigstartdemoene brukte bak kulissene, men ikke forklarte. +Dette er ditt startpunkt med LangChain4j og Azure OpenAI. Vi begynner med det grunnleggende og starter byggingen av produksjonslignende applikasjoner. Denne modulen fokuserer på konversasjons-AI som husker kontekst og opprettholder tilstand — de grunnleggende konseptene alle senere moduler bygger videre på. -Vi bruker Azure OpenAI sin GPT-5.2 gjennom denne veiledningen fordi dens avanserte resonneringsevner gjør at oppførselen til forskjellige mønstre blir mer tydelig. Når du legger til minne, vil du klart se forskjellen. Dette gjør det lettere å forstå hva hver komponent tilfører applikasjonen din. +Vi bruker Azure OpenAI sin GPT-5.2 gjennom hele denne guiden fordi dens avanserte resonneringsevner gjør oppførselen til forskjellige mønstre mer tydelig. Når du legger til minne, vil du klart se forskjellen. Dette gjør det enklere å forstå hva hver komponent tilfører applikasjonen din. -Du vil bygge en applikasjon som demonstrerer begge mønstrene: +Du vil bygge én applikasjon som demonstrerer begge mønstrene: -**Stateless Chat** - Hver forespørsel er uavhengig. Modellen har ikke noe minne om tidligere meldinger. Dette er mønsteret du brukte i hurtigstarten. +**Stateless Chat** - Hver forespørsel er uavhengig. Modellen har ikke noe minne om tidligere meldinger. Dette er det enkleste startpunktet. -**Stateful Conversation** - Hver forespørsel inkluderer samtalehistorikk. Modellen opprettholder kontekst over flere utsagn. Dette er hva produksjonsapplikasjoner krever. +**Stateful Conversation** - Hver forespørsel inkluderer samtalehistorikk. Modellen opprettholder kontekst over flere runder. Dette er hva produksjonsapplikasjoner krever. ## Forutsetninger @@ -45,41 +45,41 @@ Du vil bygge en applikasjon som demonstrerer begge mønstrene: > **Merk:** Denne modulen bruker GPT-5.2 på Azure OpenAI. Distribusjonen konfigureres automatisk via `azd up` - ikke endre modellnavnet i koden. -## Forstå Kjernesproblemet +## Forstå kjernen i problemet -Språkmodeller er stateless. Hver API-kall er uavhengig. Hvis du sender "Mitt navn er John" og deretter spør "Hva heter jeg?", har modellen ingen anelse om at du nettopp introduserte deg selv. Den behandler hver forespørsel som om det er den første samtalen du noen gang har hatt. +Språkmodeller er stateless. Hver API-kall er uavhengig. Hvis du sender "Mitt navn er John" og så spør "Hva heter jeg?", har ikke modellen noe anelse om at du nettopp presenterte deg. Den behandler hver forespørsel som om det er den første samtalen du noensinne har hatt. -Dette går fint for enkle spørsmål og svar, men er ubrukelig for ekte applikasjoner. Kundeserviceboter må huske hva du har fortalt dem. Personlige assistenter trenger kontekst. Enhver samtale med flere runder krever minne. +Dette går bra for enkle spørsmål og svar, men er ubrukelig for reelle applikasjoner. Kundeserviceboter må huske hva du fortalte dem. Personlige assistenter trenger kontekst. Enhver samtale med flere runder krever minne. -Følgende diagram kontrasterer de to tilnærmingene — til venstre et stateless kall som glemmer navnet ditt; til høyre et stateful kall støttet av ChatMemory som husker det. +Diagrammet nedenfor kontrasterer de to tilnærmingene — til venstre, en stateless kall som glemmer navnet ditt; til høyre, et stateful kall med ChatMemory som husker det. Stateless vs Stateful Conversations *Forskjellen mellom stateless (uavhengige kall) og stateful (kontekstbevisste) samtaler* -## Forstå Token +## Forstå tokens -Før du dykker inn i samtaler, er det viktig å forstå tokens - de grunnleggende tekst-enhetene som språkmodeller prosesserer: +Før du dykker inn i samtaler, er det viktig å forstå tokens - de grunnleggende enhetene av tekst som språkmodeller prosesserer: -Token Explanation +Token Forklaring *Eksempel på hvordan tekst deles opp i tokens - "I love AI!" blir til 4 separate prosesseringsenheter* -Tokens er hvordan AI-modeller måler og prosesserer tekst. Ord, skilletegn, og til og med mellomrom kan være tokens. Modellen din har en grense for hvor mange tokens den kan prosessere samtidig (400,000 for GPT-5.2, med opptil 272,000 input-tokens og 128,000 output-tokens). Å forstå tokens hjelper deg med å styre samtalelengde og kostnader. +Tokens er hvordan AI-modeller måler og prosesserer tekst. Ord, tegnsetting og til og med mellomrom kan være tokens. Modellen din har en grense for hvor mange tokens den kan prosessere samtidig (400 000 for GPT-5.2, med opptil 272 000 input tokens og 128 000 output tokens). Å forstå tokens hjelper deg å styre samtalelengde og kostnader. -## Hvordan Minne Fungerer +## Hvordan minnet fungerer -Samtale-minne løser det stateless problemet ved å opprettholde samtalehistorikk. Før du sender forespørselen til modellen, legger rammeverket til relevante tidligere meldinger foran. Når du spør "Hva heter jeg?", sender systemet faktisk hele samtalehistorikken, slik at modellen kan se at du tidligere sa "Mitt navn er John." +Chat-minne løser det stateless problemet ved å opprettholde samtalehistorikk. Før du sender forespørselen til modellen, legger rammeverket til relevante tidligere meldinger foran. Når du spør "Hva heter jeg?", sender systemet faktisk hele samtalehistorikken, slik at modellen ser at du tidligere sa "Mitt navn er John." -LangChain4j tilbyr minneimplementasjoner som håndterer dette automatisk. Du velger hvor mange meldinger som skal beholdes, og rammeverket styrer kontekstvinduet. Diagrammet nedenfor viser hvordan MessageWindowChatMemory opprettholder et glidende vindu av nylige meldinger. +LangChain4j tilbyr minneimplementasjoner som håndterer dette automatisk. Du velger hvor mange meldinger som skal beholdes, og rammeverket styrer kontekstvinduet. Diagrammet under viser hvordan MessageWindowChatMemory opprettholder et glidevindu av nylige meldinger. Memory Window Concept -*MessageWindowChatMemory opprettholder et glidende vindu av nylige meldinger, og fjerner automatisk gamle* +*MessageWindowChatMemory opprettholder et glidevindu av nylige meldinger, og fjerner automatisk eldre* -## Hvordan Dette Bruker LangChain4j +## Hvordan dette bruker LangChain4j -Denne modulen utvider hurtigstarten ved å integrere Spring Boot og legge til samtale-minne. Slik passer delene sammen: +Denne modulen integrerer Spring Boot og legger til samtaleminne. Slik passer delene sammen: **Avhengigheter** - Legg til to LangChain4j-biblioteker: @@ -94,7 +94,7 @@ Denne modulen utvider hurtigstarten ved å integrere Spring Boot og legge til sa ``` -**Chat Modell** - Konfigurer Azure OpenAI som en Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chat-modell** - Konfigurer Azure OpenAI som en Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builderen leser legitimasjon fra miljøvariabler satt av `azd up`. Å sette `baseUrl` til Azure-endepunktet ditt gjør at OpenAI-klienten fungerer med Azure OpenAI. +Builderen leser legitimasjon fra miljøvariabler som settes av `azd up`. Å sette `baseUrl` til din Azure-endepunkt gjør at OpenAI-klienten fungerer med Azure OpenAI. -**Samtale-minne** - Spor chatthistorikk med MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Samtaleminne** - Spor chatthistorikk med MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,37 +124,37 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Opprett minnet med `withMaxMessages(10)` for å beholde de siste 10 meldingene. Legg til bruker- og AI-meldinger med typer: `UserMessage.from(text)` og `AiMessage.from(text)`. Hent historikk med `memory.messages()` og send den til modellen. Tjenesten lagrer separate minneinstanser per samtale-ID, slik at flere brukere kan chatte samtidig. +Lag minnet med `withMaxMessages(10)` for å holde de siste 10 meldingene. Legg til bruker- og AI-meldinger med typed wrappers: `UserMessage.from(text)` og `AiMessage.from(text)`. Hent historien med `memory.messages()` og send det til modellen. Tjenesten lagrer separate minneinstanser per samtale-ID, slik at flere brukere kan chatte samtidig. > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) og spør: -> - "Hvordan bestemmer MessageWindowChatMemory hvilke meldinger som skal droppes når vinduet er fullt?" +> - "Hvordan bestemmer MessageWindowChatMemory hvilke meldinger som fjernes når vinduet er fullt?" > - "Kan jeg implementere egendefinert minnelagring ved å bruke en database i stedet for minne?" > - "Hvordan kan jeg legge til oppsummering for å komprimere gammel samtalehistorikk?" -Stateless chat-endepunktet hopper over minne helt - bare `chatModel.chat(prompt)` som i hurtigstart. Stateful endepunkt legger til meldinger i minnet, henter historikk, og inkluderer den konteksten med hver forespørsel. Samme modellkonfigurasjon, forskjellige mønstre. +Stateless chat-endepunktet hopper helt over minnet - bare `chatModel.chat(prompt)` som i rask start. Stateful endepunktet legger meldinger til minnet, henter historikk, og inkluderer den konteksten for hver forespørsel. Samme modellkonfigurasjon, forskjellige mønstre. -## Distribuer Azure OpenAI Infrastruktur +## Distribuer Azure OpenAI-infrastruktur **Bash:** ```bash cd 01-introduction -azd up # Velg abonnement og plassering (eastus2 anbefalt) +azd up # Velg abonnement og plassering (eastus2 anbefales) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Velg abonnement og plassering (anbefalt østus2) +azd up # Velg abonnement og plassering (eastus2 anbefales) ``` -> **Merk:** Hvis du får en tidsavbrudds-feil (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), kjør bare `azd up` på nytt. Azure-ressurser kan fortsatt provisjoneres i bakgrunnen, og en ny forsøk lar distribusjonen fullføres når ressursene når en terminal tilstand. +> **Merk:** Hvis du møter en timeout-feil (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), kjør bare `azd up` igjen. Azure-ressurser kan fortsatt holde på å bli opprettet i bakgrunnen, og ny kjøring lar distribusjonen fullføre når ressursene når en terminal tilstand. Dette vil: -1. Distribuere Azure OpenAI-ressurs med GPT-5.2 og text-embedding-3-small modeller +1. Distribuere Azure OpenAI-ressursen med GPT-5.2 og text-embedding-3-small modeller 2. Automatisk generere `.env`-fil i prosjektrot med legitimasjon 3. Sette opp alle nødvendige miljøvariabler -**Har du problemer med distribusjon?** Se [Infrastructure README](infra/README.md) for detaljert feilsøking inkludert subdomene-navnkonflikter, manuelle trinn for Azure Portal distribusjon, og modellkonfigurasjonsveiledning. +**Har du problemer med distribusjon?** Se [Infrastructure README](infra/README.md) for detaljert feilsøking inkludert konflikter med subdomener, manuelle steg for deploy i Azure-portalen, og retningslinjer for modell-konfigurasjon. **Verifiser at distribusjonen lyktes:** @@ -168,7 +168,7 @@ cat ../.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, osv. Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, osv. ``` -> **Merk:** `azd up`-kommandoen genererer automatisk `.env`-filen. Hvis du trenger å oppdatere den senere, kan du enten redigere `.env`-filen manuelt eller generere den på nytt ved å kjøre: +> **Merk:** `azd up`-kommandoen genererer automatisk `.env`-filen. Hvis du trenger å oppdatere den senere, kan du enten redigere `.env`-filen manuelt eller regenerere den ved å kjøre: > > **Bash:** > ```bash @@ -182,11 +182,11 @@ Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, osv. > .\.azd-env.ps1 > ``` -## Kjør Applikasjonen Lokalt +## Kjør applikasjonen lokalt -**Verifiser distribusjon:** +**Verifiser distribusjonen:** -Sørg for at `.env`-filen finnes i rotmappen med Azure-legitimasjon. Kjør dette fra modulmappen (`01-introduction/`): +Sørg for at `.env`-filen finnes i rotkatalogen med Azure-legitimasjon. Kjør dette fra modulkatalogen (`01-introduction/`): **Bash:** ```bash @@ -200,17 +200,17 @@ Get-Content ..\.env # Bør vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Start applikasjonene:** -**Alternativ 1: Bruke Spring Boot Dashboard (Anbefalt for VS Code brukere)** +**Alternativ 1: Bruke Spring Boot Dashboard (Anbefalt for VS Code-brukere)** -Devcontaineren inkluderer Spring Boot Dashboard-utvidelsen som gir et visuelt grensesnitt for å administrere alle Spring Boot-applikasjoner. Du finner det i Aktivitetslinjen på venstre side i VS Code (se etter Spring Boot-ikonet). +Devcontaineren inkluderer Spring Boot Dashboard-utvidelsen, som gir et visuelt grensesnitt for å håndtere alle Spring Boot-applikasjoner. Du finner den i Aktivitetslinjen på venstre side i VS Code (se etter Spring Boot-ikonet). Fra Spring Boot Dashboard kan du: - Se alle tilgjengelige Spring Boot-applikasjoner i arbeidsområdet -- Starte/stoppe applikasjoner med ett enkelt klikk +- Starte/stoppe applikasjoner med ett klikk - Se applikasjonslogger i sanntid - Overvåke applikasjonsstatus -Klikk bare på play-knappen ved siden av "introduction" for å starte denne modulen, eller start alle moduler samtidig. +Klikk bare på play-knappen ved siden av "introduction" for å starte denne modulen, eller start alle modulene samtidig. Spring Boot Dashboard @@ -232,7 +232,7 @@ cd .. # Fra rotkatalogen .\start-all.ps1 ``` -Eller start bare denne modulen: +Eller start kun denne modulen: **Bash:** ```bash @@ -246,7 +246,7 @@ cd 01-introduction .\start.ps1 ``` -Begge skriptene laster automatisk miljøvariabler fra rotens `.env`-fil og vil bygge JARs hvis de ikke eksisterer. +Begge skriptene laster automatisk miljøvariabler fra rotens `.env`-fil og bygger JAR-filene hvis de ikke finnes. > **Merk:** Hvis du foretrekker å bygge alle moduler manuelt før oppstart: > @@ -268,7 +268,7 @@ Begge skriptene laster automatisk miljøvariabler fra rotens `.env`-fil og vil b **Bash:** ```bash -./stop.sh # Kun denne modulen +./stop.sh # Bare denne modulen # Eller cd .. && ./stop-all.sh # Alle moduler ``` @@ -280,43 +280,43 @@ cd .. && ./stop-all.sh # Alle moduler cd ..; .\stop-all.ps1 # Alle moduler ``` -## Bruke Applikasjonen +## Bruke applikasjonen -Applikasjonen gir et webgrensesnitt med to chat-implementasjoner side om side. +Applikasjonen tilbyr et nettgrensesnitt med to chat-implementeringer side om side. -Application Home Screen +Applikasjonens startsider -*Dashboard som viser både Enkel Chat (stateless) og Samtale Chat (stateful) alternativer* +*Dashboard som viser både Simple Chat (stateless) og Conversational Chat (stateful) alternativer* -### Stateless Chat (Venstre Panel) +### Stateless Chat (venstre panel) -Prøv denne først. Spør "Mitt navn er John" og deretter umiddelbart "Hva heter jeg?" Modellen vil ikke huske fordi hver melding er uavhengig. Dette demonstrerer kjernesproblemet med grunnleggende språkmodell-integrasjon - ingen samtalekontekst. +Prøv dette først. Spør "Mitt navn er John" og spør så umiddelbart "Hva heter jeg?" Modellen vil ikke huske fordi hver melding er uavhengig. Dette demonstrerer kjerneproblemet med enkel språkmodell-integrasjon - ingen samtalekontekst. -Stateless Chat Demo +Demo av Stateless Chat *AI husker ikke navnet ditt fra forrige melding* -### Stateful Chat (Høyre Panel) +### Stateful Chat (høyre panel) -Prøv nå samme sekvens her. Spør "Mitt navn er John" og deretter "Hva heter jeg?" Denne gangen husker den. Forskjellen er MessageWindowChatMemory - den opprettholder samtalehistorikk og inkluderer den med hver forespørsel. Slik fungerer AI i produksjonssamtaler. +Prøv nå samme sekvens her. Spør "Mitt navn er John" og så "Hva heter jeg?" Denne gangen husker den det. Forskjellen er MessageWindowChatMemory - den opprettholder samtalehistorikk og inkluderer den med hver forespørsel. Slik fungerer produksjonsklar konversasjons-AI. -Stateful Chat Demo +Demo av Stateful Chat *AI husker navnet ditt fra tidligere i samtalen* -Begge paneler bruker samme GPT-5.2-modell. Den eneste forskjellen er minnet. Dette gjør det tydelig hva minne tilfører applikasjonen din og hvorfor det er essensielt for ekte bruksområder. +Begge panelene bruker samme GPT-5.2-modell. Den eneste forskjellen er minnet. Dette gjør det tydelig hva minnet tilfører applikasjonen din og hvorfor det er essensielt for reelle bruksområder. -## Neste Steg +## Neste steg -**Neste Modul:** [02-prompt-engineering - Prompt Engineering with GPT-5.2](../02-prompt-engineering/README.md) +**Neste modul:** [02-prompt-engineering - Prompt Engineering med GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigasjon:** [← Forrige: Module 00 - Quick Start](../00-quick-start/README.md) | [Tilbake til Hoved](../README.md) | [Neste: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigasjon:** [← Tilbake til hovedside](../README.md) | [Neste: Modul 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **Ansvarsfraskrivelse**: -Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vennligst vær oppmerksom på at automatiserte oversettelser kan inneholde feil eller unøyaktigheter. Det originale dokumentet på det opprinnelige språket skal anses som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. +Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket skal betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. \ No newline at end of file diff --git a/translations/no/02-prompt-engineering/README.md b/translations/no/02-prompt-engineering/README.md index 48de1531f..c4fe29430 100644 --- a/translations/no/02-prompt-engineering/README.md +++ b/translations/no/02-prompt-engineering/README.md @@ -2,84 +2,84 @@ ## Innholdsfortegnelse -- [Video Gjennomgang](../../../02-prompt-engineering) -- [Hva du vil lære](../../../02-prompt-engineering) -- [Forutsetninger](../../../02-prompt-engineering) -- [Forstå prompt engineering](../../../02-prompt-engineering) -- [Grunnleggende om prompt engineering](../../../02-prompt-engineering) - - [Zero-Shot prompting](../../../02-prompt-engineering) - - [Few-Shot prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Rollebasert prompting](../../../02-prompt-engineering) - - [Prompt maler](../../../02-prompt-engineering) -- [Avanserte mønstre](../../../02-prompt-engineering) -- [Kjør applikasjonen](../../../02-prompt-engineering) -- [Skjermbilder fra applikasjonen](../../../02-prompt-engineering) -- [Utforske mønstrene](../../../02-prompt-engineering) - - [Lav vs høy iver](../../../02-prompt-engineering) - - [Oppgaveutførelse (Verktøy-preambler)](../../../02-prompt-engineering) - - [Selvreflekterende kode](../../../02-prompt-engineering) - - [Strukturert analyse](../../../02-prompt-engineering) - - [Samtale med mange runder](../../../02-prompt-engineering) - - [Trinnvis resonnering](../../../02-prompt-engineering) - - [Begrenset output](../../../02-prompt-engineering) -- [Hva du egentlig lærer](../../../02-prompt-engineering) -- [Neste steg](../../../02-prompt-engineering) +- [Video Gjennomgang](#video-gjennomgang) +- [Hva Du Vil Lære](#hva-du-vil-lære) +- [Forutsetninger](#forutsetninger) +- [Forstå Prompt Engineering](#forstå-prompt-engineering) +- [Grunnleggende om Prompt Engineering](#grunnleggende-om-prompt-engineering) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Rollebasert Prompting](#rollebasert-prompting) + - [Prompt Maler](#prompt-maler) +- [Avanserte Mønstre](#avanserte-mønstre) +- [Kjør Applikasjonen](#kjør-applikasjonen) +- [Applikasjonsskjermbilder](#applikasjonsbilder) +- [Utforske Mønstrene](#utforske-mønstrene) + - [Lav vs Høy Iver](#lav-vs-høy-ivrighet) + - [Oppgaveutførelse (Verktøypreambler)](#oppgaveutførelse-verktøysintroduksjoner) + - [Selvreflekterende Kode](#selvreflekterende-kode) + - [Strukturert Analyse](#strukturert-analyse) + - [Fler-Turn Chat](#flerstegssamtale) + - [Steg-for-Steg Resonnering](#trinnvis-resonering) + - [Begrenset Utdata](#begrenset-output) +- [Hva Du Egentlig Lærer](#hva-du-virkelig-lærer) +- [Neste Steg](#neste-steg) ## Video Gjennomgang Se denne livesesjonen som forklarer hvordan du kommer i gang med denne modulen: -Prompt Engineering with LangChain4j - Live Session +Prompt Engineering med LangChain4j - Livesesjon -## Hva du vil lære +## Hva Du Vil Lære -Følgende diagram gir en oversikt over hovedtemaene og ferdighetene du vil utvikle i denne modulen — fra teknikker for promptforfining til den trinnvise arbeidsflyten du vil følge. +Følgende diagram gir en oversikt over nøkkeltemaene og ferdighetene du vil utvikle i denne modulen — fra teknikker for forbedring av prompts til steg-for-steg arbeidsflyten du vil følge. -What You'll Learn +Hva Du Vil Lære -I tidligere moduler har du utforsket grunnleggende LangChain4j-interaksjoner med GitHub-modeller og sett hvordan minne muliggjør konverserende AI med Azure OpenAI. Nå vil vi fokusere på hvordan du stiller spørsmål — selve promptene — ved å bruke Azure OpenAIs GPT-5.2. Måten du strukturerer promptene dine på påvirker dramatisk kvaliteten på svarene du får. Vi starter med en gjennomgang av grunnleggende promptingsteknikker, og går deretter videre til åtte avanserte mønstre som utnytter GPT-5.2 sine kapasiteter fullt ut. +I forrige modul så du hvordan minne muliggjør konversasjonell AI med Azure OpenAI. Nå skal vi fokusere på hvordan du stiller spørsmål — selve promptene — ved bruk av Azure OpenAI sin GPT-5.2. Måten du strukturerer promptene på påvirker kvaliteten på svarene du får dramatisk. Vi starter med en gjennomgang av grunnleggende prompting-teknikker, før vi går videre til åtte avanserte mønstre som utnytter GPT-5.2 sine muligheter fullt ut. -Vi bruker GPT-5.2 fordi den introduserer kontroll over resonnementet – du kan fortelle modellen hvor mye den skal tenke før den svarer. Dette gjør ulike promptingstrategier mer tydelige og hjelper deg å forstå når du bør bruke hver tilnærming. Vi drar også nytte av Azures færre ratebegrensninger for GPT-5.2 sammenlignet med GitHub-modeller. +Vi bruker GPT-5.2 fordi den introduserer resonnementskontroll - du kan fortelle modellen hvor mye tenking den skal gjøre før den svarer. Dette gjør forskjellige prompting-strategier mer tydelige og hjelper deg å forstå når du bør bruke hver tilnærming. ## Forutsetninger -- Fullført Modul 01 (Azure OpenAI-ressurser deployert) -- `.env`-fil i rotkatalogen med Azure-legitimasjon (opprettet med `azd up` i Modul 01) +- Fullført Modul 01 (Azure OpenAI ressurser deployert) +- `.env`-fil i rotkatalogen med Azure-legitimasjon (laget av `azd up` i Modul 01) -> **Merk:** Hvis du ikke har fullført Modul 01, følg deploy-instruksjonene der først. +> **Merk:** Hvis du ikke har fullført Modul 01, følg deployeringsinstruksjonene der først. -## Forstå prompt engineering +## Forstå Prompt Engineering -I kjernen av prompt engineering ligger forskjellen mellom vage og presise instruksjoner, som illustrert i sammenligningen under. +I kjernen handler prompt engineering om forskjellen mellom vage og presise instruksjoner, som sammenligningen nedenfor illustrerer. -What is Prompt Engineering? +Hva er Prompt Engineering? -Prompt engineering handler om å utforme inndata som konsekvent gir deg de resultatene du trenger. Det handler ikke bare om å stille spørsmål – det handler om å strukturere forespørsler slik at modellen forstår nøyaktig hva du ønsker og hvordan den skal levere det. +Prompt engineering handler om å designe inngangstekst som konsekvent gir deg resultater du trenger. Det handler ikke bare om å stille spørsmål - men om å strukturere forespørsler slik at modellen forstår nøyaktig hva du vil ha og hvordan det skal leveres. -Tenk på det som å gi instrukser til en kollega. "Fiks feilen" er vagt. "Fiks null pointer exception i UserService.java linje 45 ved å legge til en null-sjekk" er spesifikt. Språkmodeller fungerer på samme måte – spesifisitet og struktur teller. +Tenk på det som å gi instruksjoner til en kollega. "Fiks feilen" er vagt. "Fiks nullpointer-feilen i UserService.java linje 45 ved å legge til en nullsjekk" er spesifikt. Språkmodeller fungerer på samme måte - spesifisitet og struktur betyr noe. -Diagrammet under viser hvordan LangChain4j passer inn i bildet — ved å koble dine prompt-mønstre til modellen gjennom byggeklossene SystemMessage og UserMessage. +Diagrammet nedenfor viser hvordan LangChain4j passer inn i bildet — og kobler prompt-mønstrene dine til modellen via SystemMessage og UserMessage byggesteiner. -How LangChain4j Fits +Hvordan LangChain4j Passer Inn -LangChain4j tilbyr infrastrukturen — modellforbindelser, minne og meldingstyper — mens prompt-mønstrene bare er nøye strukturerte tekster du sender gjennom den infrastrukturen. De viktige byggeklossene er `SystemMessage` (som setter AIens oppførsel og rolle) og `UserMessage` (som bærer den faktiske forespørselen din). +LangChain4j leverer infrastrukturen — modellkoblinger, minne og meldingstyper — mens prompt-mønstrene er bare nøye strukturerte tekster du sender gjennom infrastrukturen. De viktigste byggesteinene er `SystemMessage` (som setter AI-ens atferd og rolle) og `UserMessage` (som bærer den faktiske forespørselen din). -## Grunnleggende om prompt engineering +## Grunnleggende om Prompt Engineering -De fem kjerne-teknikkene vist under danner fundamentet for effektiv prompt engineering. Hver av dem adresserer en forskjellig side av hvordan du kommuniserer med språkmodeller. +De fem kjerne-teknikkene vist nedenfor danner grunnlaget for effektiv prompt engineering. Hver adresserer en forskjellig del av hvordan du kommuniserer med språkmodeller. -Five Prompt Engineering Patterns Overview +Oversikt over Fem Prompt Engineering-Mønstre -Før vi går inn på de avanserte mønstrene i denne modulen, la oss se på fem grunnleggende promptingsteknikker. Dette er byggeklossene som enhver prompt-ingeniør bør kjenne til. Har du allerede jobbet gjennom [Rask start-modulen](../00-quick-start/README.md#2-prompt-patterns), har du sett disse i praksis – her er det konseptuelle rammeverket bak dem. +Før vi dykker ned i de avanserte mønstrene i denne modulen, la oss gå gjennom fem grunnleggende prompting-teknikker. Disse er byggesteinene enhver prompt-ingeniør bør kjenne til. -### Zero-Shot prompting +### Zero-Shot Prompting -Den enkleste tilnærmingen: gi modellen en direkte instruksjon uten eksempler. Modellen baserer seg fullt ut på sin trening for å forstå og utføre oppgaven. Dette fungerer godt for enkle forespørsler der forventet oppførsel er åpenbar. +Den enkleste tilnærmingen: gi modellen en direkte instruksjon uten eksempler. Modellen baserer seg helt på sin trening for å forstå og utføre oppgaven. Dette fungerer godt for enkle forespørsler der forventet oppførsel er opplagt. Zero-Shot Prompting -*Direkte instruksjon uten eksempler — modellen utleder oppgaven kun fra instruksjonen* +*Direkte instruksjon uten eksempler — modellen tolker oppgaven ut fra instruksjonen alene* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Svar: "Positiv" ``` -**Når bruke:** Enkle klassifiseringer, direkte spørsmål, oversettelser eller enhver oppgave modellen kan håndtere uten ytterligere veiledning. +**Når du bør bruke det:** Enkle kategoriseringer, direkte spørsmål, oversettelser, eller oppgaver modellen kan håndtere uten tilleggsveiledning. -### Few-Shot prompting +### Few-Shot Prompting -Gi eksempler som demonstrerer mønsteret du ønsker modellen skal følge. Modellen lærer det forventede inn-data/ut-data-formatet fra eksemplene og anvender det på nye innspill. Dette forbedrer konsistensen dramatisk for oppgaver der ønsket format eller oppførsel ikke er innlysende. +Gi eksempler som demonstrerer mønsteret du ønsker modellen skal følge. Modellen lærer forventet input-output-format fra eksemplene og anvender det på nye inputs. Dette forbedrer konsistensen dramatisk for oppgaver hvor ønsket format eller oppførsel ikke er opplagt. Few-Shot Prompting -*Lære fra eksempler — modellen identifiserer mønsteret og bruker det på nye innspill* +*Lærer fra eksempler — modellen identifiserer mønsteret og anvender det på nye inputs* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Når bruke:** Tilpassede klassifiseringer, konsistent formatering, domene-spesifikke oppgaver, eller når zero-shot-resultater er inkonsistente. +**Når du bør bruke det:** Tilpassede kategoriseringer, konsistent formatering, domene-spesifikke oppgaver, eller når zero-shot resultater er inkonsistente. ### Chain of Thought -Be modellen vise sitt resonnement steg-for-steg. I stedet for å hoppe rett til et svar, bryter modellen ned problemet og jobber gjennom hvert delsteg eksplisitt. Dette øker nøyaktigheten på matematikk, logikk og komplekse resonneringsoppgaver. +Be modellen vise sitt resonnement steg-for-steg. I stedet for å hoppe rett til et svar, bryter modellen ned problemet og går gjennom hvert delsteg eksplisitt. Dette forbedrer nøyaktigheten på matte-, logikk- og fler-stegs resonneringsoppgaver. Chain of Thought Prompting -*Trinnvis resonnering — bryter komplekse problemer ned i eksplisitte logiske steg* +*Steg-for-steg resonnement — deler komplekse problemer inn i eksplisitte logiske trinn* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Modellen viser: 15 - 8 = 7, deretter 7 + 12 = 19 epler +// Modellen viser: 15 - 8 = 7, så 7 + 12 = 19 epler ``` -**Når bruke:** Matematikkoppgaver, logikkpuslespill, debugging, eller enhver oppgave der visning av resonnement prosessen øker nøyaktighet og tillit. +**Når du bør bruke det:** Matematikkoppgaver, logikkpuslespill, debugging, eller oppgaver hvor det å vise resonnementet øker nøyaktighet og tillit. -### Rollebasert prompting +### Rollebasert Prompting -Sett en persona eller rolle for AI før du stiller spørsmålet ditt. Dette gir kontekst som former tonen, dybden og fokuset i svaret. En "programvarearkitekt" gir annerledes råd enn en "juniorutvikler" eller en "sikkerhetsrevisor". +Sett en persona eller rolle for AI før du stiller spørsmålet. Dette gir kontekst som former tonen, dybden og fokuset i svaret. En "programvarearkitekt" gir annerledes råd enn en "juniorutvikler" eller en "sikkerhetsrevisor". -Role-Based Prompting +Rollebasert Prompting -*Setter kontekst og persona — samme spørsmål får ulik respons avhengig av tildelt rolle* +*Setter kontekst og persona — samme spørsmål gir forskjellig svar avhengig av tildelt rolle* ```java String prompt = """ @@ -157,13 +157,13 @@ String prompt = """ String response = model.chat(prompt); ``` -**Når bruke:** Kodegjennomganger, veiledning, domene-spesifikk analyse, eller når du trenger svar skreddersydd til et bestemt ekspertisenivå eller perspektiv. +**Når du bør bruke det:** Kodegjennomganger, veiledning, domene-spesifikk analyse, eller når du trenger svar skreddersydd til et bestemt ekspertisenivå eller perspektiv. -### Prompt maler +### Prompt Maler -Lag gjenbrukbare prompts med variable plassholdere. I stedet for å skrive en ny prompt hver gang, definer en mal én gang og fyll inn forskjellige verdier. LangChain4js `PromptTemplate`-klasse gjør dette enkelt med `{{variable}}`-syntaks. +Lag gjenbrukbare prompts med variable plassholdere. I stedet for å skrive en ny prompt hver gang, definer en mal en gang og fyll inn forskjellige verdier. LangChain4j sin `PromptTemplate` klasse gjør dette enkelt med `{{variable}}` syntaks. -Prompt Templates +Prompt Maler *Gjenbrukbare prompts med variable plassholdere — én mal, mange bruksområder* @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Når bruke:** Gjentatte henvendelser med ulike innspill, batch-prosessering, bygge gjenbrukbare AI-arbeidsflyter, eller enhver situasjon der prompt-strukturen er konstant men data endres. +**Når du bør bruke det:** Gjentatte forespørsler med ulik input, batch-behandling, bygge gjenbrukbare AI-arbeidsflyter, eller situasjoner hvor promptstrukturen er lik men dataene endres. --- -Disse fem grunnleggende teknikkene gir deg et solid verktøysett for de fleste prompting-oppgaver. Resten av denne modulen bygger på dem med **åtte avanserte mønstre** som utnytter GPT-5.2 sin kontroll over resonnering, selvevaluering og strukturerte output-muligheter. +Disse fem grunnleggende gir deg et solid verktøysett for de fleste prompting-oppgaver. Resten av denne modulen bygger videre på dem med **åtte avanserte mønstre** som utnytter GPT-5.2 sin resonnementskontroll, selv-evaluering, og strukturerte utdata. -## Avanserte mønstre +## Avanserte Mønstre -Med de grunnleggende på plass, går vi videre til de åtte avanserte mønstrene som gjør denne modulen unik. Ikke alle problemer trenger samme tilnærming. Noen spørsmål trenger raske svar, andre trenger dyp tenking. Noen krever synlig resonnement, andre bare resultater. Hvert mønster under er optimalisert for et forskjellig scenario — og GPT-5.2 sin resonneringskontroll gjør forskjellene enda mer tydelige. +Med det grunnleggende på plass går vi videre til de åtte avanserte mønstrene som gjør denne modulen unik. Ikke alle problemer trenger samme tilnærming. Noen spørsmål trenger raske svar, andre trenger dyp tenking. Noen trenger synlig resonnement, andre bare resultater. Hvert mønster nedenfor er optimalisert for en annen situasjon — og GPT-5.2 sin resonnementskontroll gjør forskjellene enda tydeligere. -Eight Prompting Patterns +Åtte Prompting-Mønstre -*Oversikt over de åtte promptengineering-mønstrene og deres bruksområder* +*Oversikt over de åtte prompt engineering-mønstrene og deres bruksområder* -GPT-5.2 tilfører en ny dimensjon til disse mønstrene: *kontroll over resonnering*. Skyveknappen under viser hvordan du kan justere modellens tankeinnsats — fra raske, direkte svar til dyp, grundig analyse. +GPT-5.2 tilfører et nytt lag til disse mønstrene: *resonnementskontroll*. Slideren nedenfor viser hvordan du kan justere modellens tenkningsinnsats — fra raske, direkte svar til dyp og grundig analyse. -Reasoning Control with GPT-5.2 +Resonnementskontroll med GPT-5.2 -*GPT-5.2 sin resonneringskontroll lar deg spesifisere hvor mye modellens tenkning skal være — fra raske direkte svar til dyp utforskning* +*GPT-5.2 sin resonnementskontroll lar deg spesifisere hvor mye tenking modellen skal gjøre — fra raske, direkte svar til dyp utforskning* -**Lav iver (Rask & fokusert)** - For enkle spørsmål der du vil ha raske, direkte svar. Modellen gjør minimal resonnement - maks 2 steg. Bruk dette til beregninger, oppslag eller enkle spørsmål. +**Lav Iver (Rask & Fokusert)** - For enkle spørsmål hvor du ønsker hurtige, direkte svar. Modellen gjør minimal tenking - maks 2 steg. Bruk dette for beregninger, oppslag, eller enkle spørsmål. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Utforsk med GitHub Copilot:** Åpne [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) og spør: -> - "Hva er forskjellen mellom lav og høy iver i prompting-mønstre?" -> - "Hvordan hjelper XML-taggene i prompts til med å strukturere AI-ens svar?" -> - "Når bør jeg bruke selvrefleksjon-mønstre kontra direkte instruksjoner?" +> - "Hva er forskjellen mellom lav iver og høy iver i prompting-mønstre?" +> - "Hvordan hjelper XML-taggene i promptene med å strukturere AI-svaret?" +> - "Når bør jeg bruke selvrefleksjonsmønstre kontra direkte instruksjon?" -**Høy iver (Dyp & grundig)** - For komplekse problemer der du ønsker omfattende analyse. Modellen utforsker grundig og viser detaljert resonnement. Bruk dette til systemdesign, arkitekturvalg eller omfattende forskning. +**Høy Iver (Dyp & Grundig)** - For komplekse problemer hvor du vil ha omfattende analyse. Modellen utforsker grundig og viser detaljert resonnement. Bruk dette for systemdesign, arkitekturvalg, eller kompleks forskning. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Oppgaveutførelse (Trinnvis progresjon)** - For arbeidsflyter med flere trinn. Modellen gir en plan på forhånd, forteller om hvert trinn underveis, og gir til slutt en oppsummering. Bruk dette til migrasjoner, implementeringer eller øvrige flertrinnsprosesser. +**Oppgaveutførelse (Steg-for-Steg Fremdrift)** - For fler-stegs arbeidsflyter. Modellen gir en plan på forhånd, forteller hva den gjør for hvert steg, og avslutter med en oppsummering. Bruk dette for migrasjoner, implementasjoner, eller fler-stegs prosesser. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Chain-of-Thought prompting ber uttrykkelig modellen om å vise sitt resonnement, noe som øker nøyaktigheten for komplekse oppgaver. Den trinnvise oppdelingen hjelper både mennesker og AI til å forstå logikken. +Chain-of-Thought prompting ber eksplisitt modellen vise sitt resonnement, noe som forbedrer nøyaktigheten for komplekse oppgaver. Steg-for-steg gjennomgangen hjelper både mennesker og AI å forstå logikken. > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Spør om dette mønsteret: > - "Hvordan kan jeg tilpasse oppgaveutførelsesmønsteret for langvarige operasjoner?" -> - "Hva er beste praksis for å strukturere verktøy-preambler i produksjonsapplikasjoner?" -> - "Hvordan kan jeg fange og vise mellomliggende fremdriftsoppdateringer i et brukergrensesnitt?" +> - "Hva er beste praksis for å strukturere verktøypreambler i produksjonsapplikasjoner?" +> - "Hvordan kan jeg fange og vise mellomliggende fremdriftsoppdateringer i UI?" -Diagrammet under illustrerer denne Plan → Utfør → Oppsummer arbeidsflyten. +Diagrammet nedenfor illustrerer denne Plan → Utfør → Oppsummer arbeidsflyten. -Task Execution Pattern +Oppgaveutførelsesmønster -*Plan → Utfør → Oppsummer arbeidsflyt for flertrinnsoppgaver* +*Plan → Utfør → Oppsummer arbeidsflyt for fler-stegs oppgaver* -**Selvreflekterende kode** - For å generere produksjonsklar kode. Modellen genererer kode i henhold til produksjonsstandarder med korrekt feilhåndtering. Bruk dette ved utvikling av nye funksjoner eller tjenester. +**Selvreflekterende Kode** - For å generere kode av produksjonskvalitet. Modellen genererer kode som følger produksjonsstandarder med riktig feilhåndtering. Bruk dette når du bygger nye funksjoner eller tjenester. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagrammet under viser denne iterative forbedringssløyfen — generer, evaluer, identifiser svakheter, og forbedre til koden møter produksjonsstandarder. +Diagrammet nedenfor viser denne iterative forbedringssløyfen — generer, evaluer, identifiser svakheter, og forbedre til koden møter produksjonsstandarder. -Self-Reflection Cycle +Selvrefleksjonssyklus *Iterativ forbedringssløyfe - generer, evaluer, identifiser problemer, forbedre, gjenta* -**Strukturert analyse** - For konsistent evaluering. Modellen gjennomgår kode med et fast rammeverk (korrrekthet, praksis, ytelse, sikkerhet, vedlikeholdbarhet). Bruk dette til kodegjennomganger eller kvalitetsvurderinger. +**Strukturert Analyse** - For konsistent evaluering. Modellen gjennomgår kode med et fast rammeverk (korrekthet, praksis, ytelse, sikkerhet, vedlikeholdbarhet). Bruk dette for kodegjennomganger eller kvalitetsvurderinger. ```java String prompt = """ @@ -356,16 +356,16 @@ String response = chatModel.chat(prompt); > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Spør om strukturert analyse: > - "Hvordan kan jeg tilpasse analyse-rammeverket for ulike typer kodegjennomganger?" -> - "Hva er beste måten å analysere og handle på strukturert output programmessig?" -> - "Hvordan sikrer jeg konsistente alvorlighetsgrader på tvers av ulike gjennomgangssessioner?" +> - "Hva er beste måten å analysere og bruke strukturerte utdata programmatisk?" +> - "Hvordan sikrer jeg konsistente alvorlighetsnivåer på tvers av ulike gjennomgangssesjoner?" -Diagrammet under viser hvordan dette strukturerte rammeverket organiserer en kodegjennomgang i konsistente kategorier med alvorlighetsnivåer. +Følgende diagram viser hvordan dette strukturerte rammeverket organiserer en kodegjennomgang i konsistente kategorier med alvorlighetsnivåer. -Structured Analysis Pattern +Strukturert Analyse Mønster *Rammeverk for konsistente kodegjennomganger med alvorlighetsnivåer* -**Samtale med mange runder** - For samtaler som trenger kontekst. Modellen husker tidligere meldinger og bygger videre på dem. Bruk dette til interaktive hjelpesesjoner eller komplekse spørsmål og svar. +**Fler-Turn Chat** - For samtaler som trenger kontekst. Modellen husker tidligere meldinger og bygger videre på dem. Bruk dette for interaktive hjelpesesjoner eller komplekse spørsmål og svar. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Diagrammet under visualiserer hvordan samtalekontekst akkumuleres med hver runde og hvordan det relaterer til modellens token-grense. +Diagrammet nedenfor visualiserer hvordan samtalekontekst akkumuleres over flere runder og hvordan det relaterer til modellens token-grense. -Context Memory +Kontekstminne -*Hvordan samtalekontekst akkumuleres over flere runder til token-grensen nås* -**Trinnvis resonnement** - For problemer som krever synlig logikk. Modellen viser eksplisitt resonnement for hvert trinn. Bruk dette for matematikkoppgaver, logikkpuslespill eller når du trenger å forstå tankegangen. +*Hvordan samtalekontekst akkumuleres over flere runder inntil token-grensen nås* + +**Steg-for-Steg Resonnering** - For problemer som krever synlig logikk. Modellen viser eksplisitt resonnement for hvert steg. Bruk dette for matteoppgaver, logikkpuslespill, eller når du trenger å forstå tenkeprosessen. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagrammet nedenfor illustrerer hvordan modellen bryter ned problemer i eksplisitte, nummererte logiske trinn. - -Step-by-Step Pattern +Diagrammet nedenfor illustrerer hvordan modellen deler opp problemer i eksplisitte, nummererte logiske steg. -*Nedbryting av problemer i eksplisitte logiske trinn* +Steg-for-Steg Mønster +*Bryte ned problemer i eksplisitte logiske steg* -**Begrenset utdata** - For svar med spesifikke formatkrav. Modellen følger strengt format- og lengderegler. Bruk dette for sammendrag eller når du trenger presis outputstruktur. +**Begrenset Output** - For svar med spesifikke formatkrav. Modellen følger strengt format- og lengderegler. Bruk dette for sammendrag eller når du trenger presis outputstruktur. ```java String prompt = """ @@ -420,43 +420,43 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Følgende diagram viser hvordan begrensninger styrer modellen til å produsere utdata som strengt følger dine format- og lengdekrav. +Følgende diagram viser hvordan begrensninger styrer modellen til å produsere output som strengt overholder dine format- og lengdekrav. -Constrained Output Pattern +Begrenset Output Mønster -*Håndhever spesifikke krav til format, lengde og struktur* +*Håndheve spesifikke format-, lengde- og strukturkrav* -## Kjør applikasjonen +## Kjør Applikasjonen -**Verifiser distribusjon:** +**Bekreft distribusjon:** -Sørg for at `.env`-filen finnes i rotkatalogen med Azure-legitimasjon (laget under Modul 01). Kjør dette fra modulkatalogen (`02-prompt-engineering/`): +Sørg for at `.env`-filen finnes i rotmappen med Azure-legitimasjon (opprettet under Modul 01). Kjør dette fra modulkatalogen (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Bør vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Bør vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Start applikasjonen:** -> **Merk:** Hvis du allerede har startet alle applikasjoner med `./start-all.sh` fra rotkatalogen (som beskrevet i Modul 01), kjører denne modulen allerede på port 8083. Du kan hoppe over startkommandoene nedenfor og gå direkte til http://localhost:8083. +> **Merk:** Hvis du allerede har startet alle applikasjoner med `./start-all.sh` fra rotmappen (som beskrevet i Modul 01), kjører denne modulen allerede på port 8083. Du kan hoppe over startkommandoene nedenfor og gå direkte til http://localhost:8083. **Alternativ 1: Bruke Spring Boot Dashboard (Anbefalt for VS Code-brukere)** -Dev-containeren inkluderer Spring Boot Dashboard-utvidelsen, som gir et visuelt grensesnitt for å administrere alle Spring Boot-applikasjoner. Du finner den i Aktivitetslinjen på venstre side av VS Code (se etter Spring Boot-ikonet). +Dev-containeren inkluderer Spring Boot Dashboard-utvidelsen, som gir et visuelt grensesnitt for å administrere alle Spring Boot-applikasjoner. Du finner den i Aktivitetslinjen på venstre side i VS Code (se etter Spring Boot-ikonet). Fra Spring Boot Dashboard kan du: - Se alle tilgjengelige Spring Boot-applikasjoner i arbeidsområdet -- Starte/stanse applikasjoner med ett klikk +- Starte/stoppe applikasjoner med ett klikk - Se applikasjonslogger i sanntid - Overvåke applikasjonsstatus -Klikk enkelt på play-knappen ved siden av "prompt-engineering" for å starte denne modulen, eller start alle moduler samtidig. +Klikk bare på play-knappen ved siden av "prompt-engineering" for å starte denne modulen, eller start alle moduler samtidig. Spring Boot Dashboard @@ -464,7 +464,7 @@ Klikk enkelt på play-knappen ved siden av "prompt-engineering" for å starte de **Alternativ 2: Bruke shell-skript** -Start alle nettapplikasjoner (moduler 01-04): +Start alle webapplikasjoner (moduler 01-04): **Bash:** ```bash @@ -474,11 +474,11 @@ cd .. # Fra rotkatalogen **PowerShell:** ```powershell -cd .. # Fra rotkatalog +cd .. # Fra rotkatalogen .\start-all.ps1 ``` -Eller start kun denne modulen: +Eller start bare denne modulen: **Bash:** ```bash @@ -492,7 +492,7 @@ cd 02-prompt-engineering .\start.ps1 ``` -Begge skriptene laster automatisk miljøvariabler fra rotens `.env`-fil og bygger JAR-filene om de ikke finnes. +Begge skriptene laster automatisk miljøvariabler fra rotens `.env`-fil og bygger JAR-filene hvis de ikke finnes. > **Merk:** Hvis du foretrekker å bygge alle moduler manuelt før oppstart: > @@ -514,7 +514,7 @@ Begge skriptene laster automatisk miljøvariabler fra rotens `.env`-fil og bygge **Bash:** ```bash -./stop.sh # Denne modulen kun +./stop.sh # Denne modulen bare # Eller cd .. && ./stop-all.sh # Alle moduler ``` @@ -526,83 +526,83 @@ cd .. && ./stop-all.sh # Alle moduler cd ..; .\stop-all.ps1 # Alle moduler ``` -## Applikasjonsskjermbilder +## Applikasjonsbilder -Her er hovedgrensesnittet til prompt engineering-modulen, hvor du kan eksperimentere med alle åtte mønstrene side om side. +Her er hovedgrensesnittet til prompt engineering-modulen, hvor du kan eksperimentere med alle åtte mønstre side om side. -Dashboard Home +Dashboard Hjem -*Hoveddashbord som viser alle 8 prompt engineering-mønstre med deres egenskaper og bruksområder* +*Hoveddashbordet som viser alle 8 prompt engineering-mønstre med deres egenskaper og bruksområder* -## Utforske mønstrene +## Utforske Mønstrene -Nettgrensesnittet lar deg eksperimentere med ulike prompting-strategier. Hvert mønster løser forskjellige problemer – prøv dem for å se når hver tilnærming fungerer best. +Nettgrensesnittet lar deg eksperimentere med ulike promptstrategier. Hvert mønster løser forskjellige problemer – prøv dem for å se når hver tilnærming fungerer best. -> **Merk: Streaming vs Ikke-streaming** — Hver mønsterside tilbyr to knapper: **🔴 Stream Response (Live)** og et **Ikke-streaming** alternativ. Streaming bruker Server-Sent Events (SSE) for å vise tokens i sanntid mens modellen genererer dem, slik at du ser fremdriften umiddelbart. Ikke-streaming venter på hele svaret før det vises. For forespørsler som utløser dypt resonnement (f.eks. High Eagerness, Self-Reflecting Code), kan ikke-streaming-kallet ta veldig lang tid — noen ganger minutter — uten synlig tilbakemelding. **Bruk streaming når du eksperimenterer med komplekse prompts** så du kan se modellen jobbe og unngå å få inntrykk av at forespørselen har gått ut på tid. +> **Merk: Streaming vs Ikke-streaming** — Hver mønsterside tilbyr to knapper: **🔴 Stream Response (Live)** og et **Ikke-streaming**-alternativ. Streaming bruker Server-Sent Events (SSE) for å vise tokens i sanntid mens modellen genererer dem, slik at du ser fremdriften umiddelbart. Ikke-streaming-alternativet venter på hele svaret før det vises. For prompts som utløser dyp tenkning (f.eks. High Eagerness, Self-Reflecting Code), kan ikke-streaming kallet ta svært lang tid – noen ganger minutter – uten synlig tilbakemelding. **Bruk streaming når du eksperimenterer med komplekse prompts** slik at du kan se modellen arbeide og unngå inntrykk av at forespørselen har tidsavbrutt. > -> **Merk: Nettleserkrav** — Streaming-funksjonen bruker Fetch Streams API (`response.body.getReader()`) som krever en full nettleser (Chrome, Edge, Firefox, Safari). Det fungerer **ikke** i VS Codes innebygde Simple Browser, da webviewen ikke støtter ReadableStream API. Hvis du bruker Simple Browser, vil ikke-streaming-knappene fortsatt fungere som normalt — bare streaming-knappene påvirkes. Åpne `http://localhost:8083` i en ekstern nettleser for full opplevelse. +> **Merk: Nettleserkrav** — Streaming-funksjonen bruker Fetch Streams API (`response.body.getReader()`) som krever en fullverdig nettleser (Chrome, Edge, Firefox, Safari). Den fungerer **ikke** i VS Codes innebygde Simple Browser, da dens webview ikke støtter ReadableStream API. Hvis du bruker Simple Browser, vil ikke-streaming-knappene fortsatt fungere normalt – bare streaming-knappene påvirkes. Åpne `http://localhost:8083` i en ekstern nettleser for full opplevelse. -### Lav vs Høy entusiasme +### Lav vs Høy Ivrighet -Still et enkelt spørsmål som "Hva er 15 % av 200?" med Lav entusiasme. Du får et raskt, direkte svar. Still så noe komplisert som "Design en caching-strategi for et høytrafikkert API" med Høy entusiasme. Klikk **🔴 Stream Response (Live)** og se modellens detaljerte resonnement komme token for token. Samme modell, samme spørsmålsstruktur – men prompten forteller hvor mye tenking som skal gjøres. +Still et enkelt spørsmål som "Hva er 15 % av 200?" med Lav Ivrighet. Du får et umiddelbart, direkte svar. Still nå noe komplekst som "Design en caching-strategi for en høytrafikk-API" med Høy Ivrighet. Klikk **🔴 Stream Response (Live)** og se modellens detaljerte resonnering komme frem token-for-token. Samme modell, samme spørrestruktur – men prompten forteller hvor mye tenking som skal til. -### Oppgaveutførelse (Verktøypreambler) +### Oppgaveutførelse (Verktøysintroduksjoner) -Flerskritt arbeidsflyter drar nytte av forhåndsplanlegging og progresjonsfortelling. Modellen skisserer hva den skal gjøre, forteller hvert trinn, og oppsummerer deretter resultatene. +Flerstegs arbeidsflyter drar nytte av planlegging på forhånd og fremdriftsnarrering. Modellen skisserer hva den vil gjøre, forteller om hvert steg, og oppsummerer resultatene. -### Selvreflekterende kode +### Selvreflekterende Kode -Prøv "Lag en e-postvalideringstjeneste". I stedet for bare å generere kode og stoppe, genererer modellen, vurderer den opp mot kvalitetskriterier, identifiserer svakheter og forbedrer. Du ser at den itererer til koden møter produksjonsstandarder. +Prøv "Lag en e-postvalideringstjeneste". I stedet for bare å generere kode og stoppe, genererer modellen, vurderer mot kvalitetskriterier, identifiserer svakheter, og forbedrer. Du vil se den iterere til koden møter produksjonsstandarder. -### Strukturert analyse +### Strukturert Analyse -Kodegjennomganger trenger konsekvente evalueringsrammer. Modellen analyserer kode med faste kategorier (riktighet, praksis, ytelse, sikkerhet) med alvorlighetsnivåer. +Kodegjennomganger trenger konsistente evalueringsrammer. Modellen analyserer kode med faste kategorier (korrekthet, praksis, ytelse, sikkerhet) med alvorlighetsnivåer. -### Fler-trinns chat +### Flerstegssamtale -Spør "Hva er Spring Boot?" og følg straks opp med "Vis meg et eksempel". Modellen husker ditt første spørsmål og gir deg et Spring Boot-eksempel spesifikt. Uten hukommelse ville det andre spørsmålet vært for vagt. +Spør "Hva er Spring Boot?" og følg opp umiddelbart med "Vis meg et eksempel". Modellen husker ditt første spørsmål og gir deg et Spring Boot-eksempel spesielt. Uten minne ville det andre spørsmålet vært for vagt. -### Trinnvis resonnement +### Trinnvis Resonering -Velg et mattespørsmål og prøv det med både Trinnvis resonnement og Lav entusiasme. Lav entusiasme gir deg bare svaret – raskt men uklart. Trinnvis viser hver beregning og avgjørelse. +Velg et matteproblem og prøv det med både Trinnvis Resonering og Lav Ivrighet. Lav ivrighet gir deg bare svaret – raskt, men utydelig. Trinnvis viser deg hver beregning og avgjørelse. -### Begrenset utdata +### Begrenset Output -Når du trenger spesifikke formater eller ordtall, håndhever dette mønsteret streng etterlevelse. Prøv å generere et sammendrag med nøyaktig 100 ord i punktlisteformat. +Når du trenger spesifikke formater eller ordtellinger, håndhever dette mønsteret streng overholdelse. Prøv å generere et sammendrag med nøyaktig 100 ord i punktlisteformat. -## Hva du virkelig lærer +## Hva Du Virkelig Lærer -**Resonnementets innsats endrer alt** +**Resonneringsinnsats Endrer Alt** -GPT-5.2 lar deg styre beregningsinnsatsen gjennom promptene dine. Lav innsats betyr raske svar med minimal utforskning. Høy innsats betyr at modellen tar seg tid til å tenke dypt. Du lærer å matche innsats med oppgavens kompleksitet – ikke kast bort tid på enkle spørsmål, men ikke skyv gjennom komplekse avgjørelser heller. +GPT-5.2 lar deg styre beregningsinnsats gjennom dine prompts. Lav innsats betyr raske svar med minimal utforskning. Høy innsats betyr at modellen tar seg tid til å tenke dypt. Du lærer å matche innsats til oppgavens kompleksitet – ikke kast bort tid på enkle spørsmål, men ikke forhast komplekse beslutninger heller. -**Struktur styrer atferd** +**Struktur Leder Adferd** -Legg merke til XML-taggene i promptene? De er ikke dekorative. Modeller følger strukturerte instrukser mer pålitelig enn fri tekst. Når du trenger flertrinnsprosesser eller kompleks logikk, hjelper struktur modellen å holde styr på hvor den er og hva som kommer neste. Diagrammet nedenfor bryter ned en velstrukturert prompt, og viser hvordan tagger som ``, ``, ``, ``, og `` organiserer instruksjonene dine i klare seksjoner. +Legg merke til XML-taggene i promptene? De er ikke dekorative. Modeller følger strukturerte instruksjoner mer pålitelig enn fri tekst. Når du trenger flerstegs prosesser eller kompleks logikk, hjelper struktur modellen å holde oversikt over hvor den er og hva som kommer neste. Diagrammet nedenfor bryter ned en godt strukturert prompt, og viser hvordan tagger som ``, ``, ``, ``, og `` organiserer instruksjonene dine i klare seksjoner. -Prompt Structure +Prompt Struktur -*Anatomi av en velstrukturert prompt med klare seksjoner og XML-stil organisering* +*Anatomi av en godt strukturert prompt med klare seksjoner og XML-stil organisering* -**Kvalitet gjennom selvevaluering** +**Kvalitet Gjennom Selvevaluering** -De selvreflekterende mønstrene fungerer ved å gjøre kvalitetskriterier eksplisitte. I stedet for å håpe modellen "gjør det riktig", forteller du nøyaktig hva "riktig" betyr: korrekt logikk, feilhåndtering, ytelse, sikkerhet. Modellen kan så evaluere sitt eget output og forbedre seg. Dette forvandler kodegenerering fra et lotteri til en prosess. +De selvreflekterende mønstrene fungerer ved å gjøre kvalitetskriterier eksplisitte. I stedet for å håpe at modellen "gjør det riktig", forteller du den nøyaktig hva "riktig" betyr: korrekt logikk, feilhåndtering, ytelse, sikkerhet. Modellen kan da evaluere sin egen output og forbedre seg. Dette gjør kodegenerering fra et lotteri til en prosess. -**Kontekst er begrenset** +**Kontekst Er Begrenset** -Flertrinnssamtaler fungerer ved å inkludere meldingshistorikk med hver forespørsel. Men det finnes en grense – hver modell har et maksimalt antall tokens. Når samtaler vokser, trenger du strategier for å beholde relevant kontekst uten å nå denne grensen. Denne modulen viser deg hvordan minne fungerer; senere lærer du når du skal oppsummere, når du skal glemme, og når du skal hente. +Flerstegssamtaler fungerer ved å inkludere meldingshistorikk med hver forespørsel. Men det er en grense – hver modell har et maksimalt tokenantall. Etter hvert som samtalene vokser, trenger du strategier for å beholde relevant kontekst uten å nå denne grensen. Denne modulen viser deg hvordan minne fungerer; senere lærer du når du skal oppsummere, når du skal glemme, og når du skal hente frem. -## Neste steg +## Neste Steg -**Neste modul:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**Neste Modul:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigasjon:** [← Forrige: Modul 01 - Introduksjon](../01-introduction/README.md) | [Tilbake til hovedmeny](../README.md) | [Neste: Modul 03 - RAG →](../03-rag/README.md) +**Navigasjon:** [← Forrige: Modul 01 - Introduksjon](../01-introduction/README.md) | [Tilbake til Hoved](../README.md) | [Neste: Modul 03 - RAG →](../03-rag/README.md) --- **Ansvarsfraskrivelse**: -Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vennligst vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det originale dokumentet på det opprinnelige språket bør betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. +Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket skal betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. \ No newline at end of file diff --git a/translations/no/03-rag/README.md b/translations/no/03-rag/README.md index e2385f5be..12d45a30a 100644 --- a/translations/no/03-rag/README.md +++ b/translations/no/03-rag/README.md @@ -2,143 +2,142 @@ ## Innholdsfortegnelse -- [Video gjennomgang](../../../03-rag) -- [Hva du vil lære](../../../03-rag) -- [Forutsetninger](../../../03-rag) -- [Forstå RAG](../../../03-rag) - - [Hvilken RAG-tilnærming bruker denne opplæringen?](../../../03-rag) -- [Hvordan det fungerer](../../../03-rag) - - [Dokumentbehandling](../../../03-rag) - - [Opprette embeddings](../../../03-rag) - - [Semantisk søk](../../../03-rag) - - [Svargenerering](../../../03-rag) -- [Kjør applikasjonen](../../../03-rag) -- [Bruke applikasjonen](../../../03-rag) - - [Last opp et dokument](../../../03-rag) - - [Still spørsmål](../../../03-rag) - - [Sjekk kildehenvisninger](../../../03-rag) - - [Eksperimenter med spørsmål](../../../03-rag) -- [Nøkkelbegreper](../../../03-rag) - - [Chunking-strategi](../../../03-rag) - - [Likhetspoeng](../../../03-rag) - - [Mellomlager i minnet](../../../03-rag) - - [Håndtering av kontekstvindu](../../../03-rag) -- [Når RAG er viktig](../../../03-rag) -- [Neste steg](../../../03-rag) - -## Video gjennomgang - -Se denne livesesjonen som forklarer hvordan du kommer i gang med denne modulen: - -RAG med LangChain4j - Live Session +- [Video-gjennomgang](#video-gjennomgang) +- [Hva du vil lære](#hva-du-vil-lære) +- [Forutsetninger](#forutsetninger) +- [Forstå RAG](#forstå-rag) + - [Hvilken RAG-tilnærming bruker denne opplæringen?](#hvilken-rag-tilnærming-bruker-denne-opplæringen) +- [Hvordan det fungerer](#hvordan-det-fungerer) + - [Dokumentbehandling](#dokumentbehandling) + - [Opprette innebygde representasjoner](#opprette-innebygde-representasjoner) + - [Semantisk søk](#semantisk-søk) + - [Svar-generering](#svar-generering) +- [Kjør applikasjonen](#kjør-applikasjonen) +- [Bruke applikasjonen](#bruke-applikasjonen) + - [Last opp et dokument](#last-opp-et-dokument) + - [Still spørsmål](#still-spørsmål) + - [Sjekk kildehenvisninger](#sjekk-kildehenvisninger) + - [Eksperimenter med spørsmål](#eksperimenter-med-spørsmål) +- [Nøkkelbegreper](#nøkkelkonsepter) + - [Chunking-strategi](#bitdeling-strategi) + - [Likhetspoeng](#likhetspoeng) + - [Minnebasert lagring](#minnebasert-lagring) + - [Håndtering av kontekstvindu](#kontekstvindu-håndtering) +- [Når RAG er viktig](#når-rag-er-viktig) +- [Neste steg](#neste-steg) + +## Video-gjennomgang + +Se denne live-sesjonen som forklarer hvordan du kommer i gang med denne modulen: + +RAG with LangChain4j - Live Session ## Hva du vil lære -I de forrige modulene lærte du hvordan du kan ha samtaler med AI og strukturere promptene dine effektivt. Men det finnes en grunnleggende begrensning: språkmodeller vet bare det de lærte under treningen. De kan ikke svare på spørsmål om firmaets retningslinjer, prosjektets dokumentasjon eller annen informasjon de ikke ble trent på. +I de forrige modulene lærte du hvordan du kan ha samtaler med AI og strukturere promptene dine effektivt. Men det finnes en grunnleggende begrensning: språkmodeller vet bare det de lærte under treningen. De kan ikke svare på spørsmål om selskapets retningslinjer, prosjekt-dokumentasjon eller annen informasjon de ikke ble trent på. -RAG (Retrieval-Augmented Generation) løser dette problemet. I stedet for å prøve å lære modellen informasjonen din (noe som er dyrt og upraktisk), gir du den muligheten til å søke i dokumentene dine. Når noen stiller et spørsmål, finner systemet relevant informasjon og inkluderer det i prompten. Modellen svarer da basert på denne innhentede konteksten. +RAG (Retrieval-Augmented Generation) løser dette problemet. I stedet for å prøve å lære modellen informasjonen din (noe som er dyrt og upraktisk), gir du den mulighet til å søke gjennom dokumentene dine. Når noen stiller et spørsmål, finner systemet relevant informasjon og inkluderer den i prompten. Modellen svarer så basert på denne hentede konteksten. -Tenk på RAG som å gi modellen et referansebibliotek. Når du stiller et spørsmål, gjør systemet følgende: +Tenk på RAG som å gi modellen et referansebibliotek. Når du stiller et spørsmål, gjør systemet: -1. **Brukerspørsmål** – Du stiller et spørsmål -2. **Embedding** – Konverterer spørsmålet til en vektor -3. **Vektorsøk** – Finner lignende dokumentbiter -4. **Kontekstsammensetning** – Legger relevante biter til prompten -5. **Svar** – LLM genererer et svar basert på konteksten +1. **Brukerspørsmål** - Du stiller et spørsmål +2. **Embedding** - Konverterer spørsmålet ditt til en vektor +3. **Vektorsøk** - Finner lignende dokumentbiter +4. **Kontekstsammensetning** - Legger relevante biter til prompten +5. **Svar** - LLM genererer et svar basert på konteksten -Dette forankrer modellens svar i dine faktiske data i stedet for å stole på treningsdata eller å finne på svar. +Dette forankrer modellens svar i dine faktiske data i stedet for å stole på treningskunnskap eller dikte opp svar. ## Forutsetninger -- Fullført [Modul 00 - Rask start](../00-quick-start/README.md) (for Eksempel på Easy RAG som refereres til senere i denne modulen) -- Fullført [Modul 01 - Introduksjon](../01-introduction/README.md) (Azure OpenAI-ressurser distribuert, inkludert `text-embedding-3-small` embedding-modellen) -- `.env`-fil i rotkatalogen med Azure-legitimasjon (opprettet via `azd up` i Modul 01) +- Fullført [Modul 01 - Introduksjon](../01-introduction/README.md) (Azure OpenAI-ressurser distribuert, inkludert `text-embedding-3-small` embedding-modell) +- `.env`-fil i rotmappen med Azure-legitimasjon (opprettet av `azd up` i Modul 01) -> **Merk:** Hvis du ikke har fullført Modul 01, følg distribusjonsinstruksjonene der først. Kommandoen `azd up` distribuerer både GPT-chat-modellen og embedding-modellen som denne modulen bruker. +> **Merk:** Hvis du ikke har fullført Modul 01, følg distribusjonsinstruksjonene der først. `azd up`-kommandoen distribuerer både GPT-chatmodellen og embedding-modellen som brukes i denne modulen. ## Forstå RAG -Diagrammet under illustrerer kjernen: i stedet for å bare stole på modellens treningsdata, gir RAG den et referansebibliotek med dokumentene dine som den kan konsultere før den genererer hvert svar. +Diagrammet nedenfor illustrerer kjernen i konseptet: i stedet for å bare stole på modellens treningsdata, gir RAG den et referansebibliotek av dokumentene dine å konsultere før hvert svar genereres. -Hva er RAG +What is RAG -*Dette diagrammet viser forskjellen mellom en standard LLM (som gjetter basert på treningsdata) og en RAG-forbedret LLM (som først konsulterer dokumentene dine).* +*Dette diagrammet viser forskjellen mellom en standard LLM (som gjetter fra treningsdata) og en RAG-forsterket LLM (som først konsulterer dokumentene dine).* -Slik kobler delene sammen hele veien. Et brukerspørsmål går gjennom fire trinn — embedding, vektorsøk, kontekstsammensetning og svargenerering — der hvert trinn bygger på det forrige: +Slik henger delene sammen ende-til-ende. Et brukerspørsmål går gjennom fire trinn — embedding, vektorsøk, kontekstsammensetning og svar-generering — der hvert bygger på det forrige: -RAG Arkitektur +RAG Architecture -*Dette diagrammet viser hele RAG-pipelinen — et brukerspørsmål går gjennom embedding, vektorsøk, kontekstsammensetning og svargenerering.* +*Dette diagrammet viser hele RAG-pipelinen — et brukerspørsmål går gjennom embedding, vektorsøk, kontekstsammensetning og svar-generering.* -Resten av denne modulen går gjennom hvert trinn i detalj, med kode du kan kjøre og endre. +Resten av denne modulen går gjennom hvert trinn i detalj, med kode du kan kjøre og modifisere. ### Hvilken RAG-tilnærming bruker denne opplæringen? -LangChain4j tilbyr tre måter å implementere RAG på, hver med et ulikt abstraksjonsnivå. Diagrammet under sammenligner disse side om side: +LangChain4j tilbyr tre måter å implementere RAG på, hver med ulik abstraksjonsgrad. Diagrammet nedenfor sammenligner dem side om side: -Tre RAG-tilnærminger i LangChain4j +Three RAG Approaches in LangChain4j -*Dette diagrammet sammenligner de tre LangChain4j RAG-tilnærmingene — Easy, Native og Advanced — og viser nøkkelkomponentene deres, samt når man bør bruke hver.* +*Dette diagrammet sammenligner de tre LangChain4j RAG-tilnærmingene — Easy, Native og Advanced — og viser hovedkomponentene og når man bør bruke hver.* | Tilnærming | Hva den gjør | Avveining | |---|---|---| -| **Easy RAG** | Kobler alt automatisk gjennom `AiServices` og `ContentRetriever`. Du merker et grensesnitt, kobler til en retriever, og LangChain4j håndterer embedding, søk og promptsamling i bakgrunnen. | Minimalt med kode, men du ser ikke hva som skjer i hvert trinn. | -| **Native RAG** | Du kaller embedding-modellen, søker i lagringen, bygger prompten og genererer svaret selv — ett eksplisitt trinn av gangen. | Mer kode, men hvert steg er synlig og kan endres. | -| **Advanced RAG** | Bruker `RetrievalAugmentor` med pluggbare spørringstransformatorer, rutere, rangering og innholdsinnsprøytning for produksjons-grade pipelines. | Maksimal fleksibilitet, men betydelig mer kompleksitet. | +| **Easy RAG** | Knytter alt automatisk via `AiServices` og `ContentRetriever`. Du merker et grensesnitt, kobler til en retriever, og LangChain4j håndterer embedding, søk og prompt-sammensetning bak kulissene. | Minimalt med kode, men du ser ikke hva som skjer på hvert trinn. | +| **Native RAG** | Du kaller embedding-modellen, søker i lagringen, bygger prompten og genererer svaret selv — ett eksplisitt trinn om gangen. | Mer kode, men hvert steg er synlig og modifiserbart. | +| **Advanced RAG** | Bruker `RetrievalAugmentor`-rammeverket med pluggbare spørringstransformatorer, rutere, re-rankere og innholdsinnsprøytninger for produksjonsklare pipelines. | Maksimal fleksibilitet, men langt mer kompleksitet. | -**Denne opplæringen bruker Native-tilnærmingen.** Hvert steg i RAG-pipelinen — embedding av spørsmålet, søk i vektorlageret, sammensetning av konteksten og generering av svaret — er skrevet eksplisitt i [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Dette er bevisst: som læringsressurs er det viktigere at du ser og forstår hvert trinn enn at koden er minimalisert. Når du er komfortabel med hvordan delene henger sammen, kan du gå videre til Easy RAG for raske prototyper eller Advanced RAG for produksjonssystemer. +**Denne opplæringen bruker Native-tilnærmingen.** Hvert trinn i RAG-pipelinen — embedding av spørsmålet, søk i vektorlagring, sammensetning av kontekst og generering av svar — er skrevet eksplisitt ut i [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Dette er gjort med vilje: som et læringsverktøy er det viktigere at du ser og forstår hvert steg enn at koden er mest mulig komprimert. Når du er komfortabel med hvordan delene henger sammen, kan du gå videre til Easy RAG for raske prototyper eller Advanced RAG for produksjonssystemer. -> **💡 Har du allerede sett Easy RAG i praksis?** [Rask Start-modulen](../00-quick-start/README.md) inkluderer et Dokument Q&A-eksempel ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) som bruker Easy RAG-tilnærmingen — LangChain4j håndterer embedding, søk og promptsamling automatisk. Denne modulen tar neste steg ved å åpne denne pipelinen så du kan se og kontrollere hvert trinn selv. +> **💡 Nysgjerrig på Easy RAG?** LangChain4j tilbyr også en *Easy RAG*-tilnærming hvor `AiServices` og en `ContentRetriever` håndterer embedding, søk og prompt-sammensetning automatisk. Denne modulen tar den mer eksplisitte veien — den bryter opp pipelinen slik at du kan se og kontrollere hvert steg selv. -Diagrammet under viser Easy RAG-pipelinen fra det eksemplet for rask start. Legg merke til hvordan `AiServices` og `EmbeddingStoreContentRetriever` skjuler all kompleksitet — du laster inn et dokument, kobler til en retriever, og får svar. Native-tilnærmingen i denne modulen åpner opp hvert av de skjulte trinnene: +Diagrammet nedenfor viser Easy RAG-pipelinen. Legg merke til hvordan `AiServices` og `EmbeddingStoreContentRetriever` skjuler all kompleksitet — du laster opp et dokument, kobler til en retriever og får svar. Native-tilnærmingen bryter opp alle disse skjulte trinnene: -Easy RAG Pipelinen - LangChain4j +Easy RAG Pipeline - LangChain4j -*Dette diagrammet viser Easy RAG-pipelinen fra `SimpleReaderDemo.java`. Sammenlign med Native-tilnærmingen brukt i denne modulen: Easy RAG skjuler embedding, innhenting og promptsamling bak `AiServices` og `ContentRetriever` — du laster inn et dokument, kobler til en retriever og får svar. Native-tilnærmingen i denne modulen åpner opp den pipelinen slik at du kaller hvert trinn (embed, søk, samle kontekst, generer) selv, og får full oversikt og kontroll.* +*Dette diagrammet viser Easy RAG-pipelinen. Sammenlign med Native-tilnærmingen som brukes i denne modulen: Easy RAG skjuler embedding, henting og prompt-sammensetning bak `AiServices` og `ContentRetriever` — du laster opp et dokument, kobler til en retriever og får svar. Native-tilnærmingen åpner opp denne pipelinen slik at du selv kaller hvert trinn (embed, søk, sett sammen kontekst, generer), noe som gir full synlighet og kontroll.* ## Hvordan det fungerer -RAG-pipelinen i denne modulen deles opp i fire trinn som kjører sekvensielt hver gang en bruker stiller et spørsmål. Først **parses og deles det opplastede dokumentet opp** i håndterbare biter. Disse bitene konverteres deretter til **vektor-embeddings** og lagres slik at de kan sammenlignes matematisk. Når en forespørsel kommer, utfører systemet et **semantisk søk** for å finne de mest relevante bitene, og til sist sender dem som kontekst til LLM-en for **svargenerering**. Avsnittene under går gjennom hvert trinn med faktisk kode og diagrammer. La oss se på første steg. +RAG-pipelinen i denne modulen deles opp i fire trinn som kjøres i rekkefølge hver gang en bruker stiller et spørsmål. Først blir et opplastet dokument **parsede og delt opp i biter** som er håndterbare. Disse bitene konverteres så til **vektor-embeddings** og lagres slik at de kan sammenlignes matematisk. Når et spørsmål kommer inn, utfører systemet et **semantisk søk** for å finne de mest relevante bitene, og til slutt sender dem som kontekst til LLM-en for **svar-generering**. Delene nedenfor går gjennom hvert trinn med faktisk kode og diagrammer. La oss se på det første trinnet. ### Dokumentbehandling [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Når du laster opp et dokument, parses det (PDF eller ren tekst), metadata som filnavn knyttes til, og det deles opp i biter — mindre deler som passer komfortabelt i modellens kontekstvindu. Disse bitene overlapper litt slik at du ikke mister kontekst ved grenseflatene. +Når du laster opp et dokument, parser systemet det (PDF eller ren tekst), legger til metadata som filnavn, og deler det i biter — mindre deler som passer komfortabelt i modellens kontekstvindu. Disse bitene overlapper litt slik at du ikke mister kontekst ved kantene. ```java // Analyser den opplastede filen og pakk den inn i et LangChain4j-dokument Document document = Document.from(content, metadata); -// Del opp i 300-token biter med 30-token overlapping +// Del opp i 300-token biter med 30-token overlapp DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Diagrammet under viser hvordan dette fungerer visuelt. Legg merke til hvordan hver bit deler noen få tokens med naboene — 30-token overlapp sikrer at ingen viktig kontekst faller mellom sprekkene: +Diagrammet nedenfor viser hvordan dette fungerer visuelt. Legg merke til hvordan hver bit deler noen tokens med naboene sine — 30 tokens overlapp sikrer at ingen viktig kontekst faller mellom sprekkene: -Dokumentdeling i biter +Document Chunking -*Dette diagrammet viser et dokument som deles i 300-token biter med 30-token overlapp, som bevarer kontekst ved bit-grensene.* +*Dette diagrammet viser et dokument som deles opp i 300-token biter med 30-token overlapp for å bevare kontekst ved kantene.* > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) og spør: > - "Hvordan deler LangChain4j dokumenter i biter og hvorfor er overlapp viktig?" -> - "Hva er optimal biter-størrelse for ulike dokumenttyper og hvorfor?" +> - "Hva er optimal bit-størrelse for ulike dokumenttyper og hvorfor?" > - "Hvordan håndterer jeg dokumenter på flere språk eller med spesiell formatering?" -### Opprette embeddings +### Opprette innebygde representasjoner [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Hver bit konverteres til en numerisk representasjon kalt embedding — i praksis en betydning-til-tall-omformer. Embedding-modellen er ikke «intelligent» slik en chatmodell er; den kan ikke følge instruksjoner, resonnere eller svare på spørsmål. Det den kan gjøre, er å kartlegge tekst i et matematisk rom hvor like betydninger havner nær hverandre — «bil» nær «automobil», «refusjonspolitikk» nær «få pengene tilbake». Tenk på chatmodellen som en person du kan snakke med; embedding-modellen er et svært godt arkivsystem. +Hver bit konverteres til en numerisk representasjon kalt en embedding — i praksis en menings-til-tall-konverterer. Embedding-modellen er ikke "intelligent" slik en chat-modell er; den kan ikke følge instrukser, resonnere eller svare på spørsmål. Den kan derimot mappe tekst til et matematisk rom der lignende meninger havner nær hverandre — "bil" nær "automobil", "refusjonspolicy" nær "få pengene tilbake". Tenk på en chatmodell som en person du kan snakke med; embedding-modellen er et superstort arkivsystem. -Diagrammet under visualiserer dette konseptet — tekst går inn, numeriske vektorer kommer ut, og like betydninger gir nærliggende vektorer: +Diagrammet nedenfor visualiserer dette konseptet — tekst går inn, numeriske vektorer kommer ut, og lignende meninger gir nærliggende vektorer: -Embedding-modell-konsept +Embedding Model Concept -*Dette diagrammet viser hvordan en embedding-modell konverterer tekst til numeriske vektorer, og plasserer like betydninger — som «bil» og «automobil» — nær hverandre i vektorrommet.* +*Dette diagrammet viser hvordan en embedding-modell konverterer tekst til numeriske vektorer, og plasserer lignende betydninger — som "bil" og "automobil" — nær hverandre i vektorrommet.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Klassediagrammet under viser de to separate flytene i en RAG-pipeline og LangChain4j-klassene som implementerer dem. **Inntaksflyten** (kjører én gang ved opplasting) deler dokumentet, embedder bitene og lagrer dem via `.addAll()`. **Spørringsflyten** (kjører hver gang en bruker spør) embedder spørsmålet, søker i lagringen via `.search()` og sender den matchede konteksten til chatmodellen. Begge flytene møtes i det delte `EmbeddingStore`-grensesnittet: +Klassediagrammet nedenfor viser de to separate flytene i en RAG-pipeline og LangChain4j-klassene som implementerer dem. **Inntaksflyten** (kjøres én gang ved opplasting) deler dokumentet, embedder bitene og lagrer dem via `.addAll()`. **Spørringsflyten** (kjøres hver gang en bruker spør) embedder spørsmålet, søker i lagringen via `.search()`, og sender den matchede konteksten til chatmodellen. Begge flyter møtes ved det delte grensesnittet `EmbeddingStore`: -LangChain4j RAG-klasser +LangChain4j RAG Classes -*Dette diagrammet viser de to flytene i en RAG-pipeline — inntak og spørring — og hvordan de kobles via et delt EmbeddingStore.* +*Dette diagrammet viser de to flytene i en RAG-pipeline — inntak og spørring — og hvordan de kobles sammen gjennom en delt EmbeddingStore.* -Når embeddings er lagret, klustrer lignende innhold naturlig sammen i vektorrommet. Visualiseringen under viser hvordan dokumenter om relaterte temaer ender som nærliggende punkter, noe som gjør semantisk søk mulig: +Når embeddings er lagret, naturlig grupperes lignende innhold sammen i vektorrommet. Visualiseringen nedenfor viser hvordan dokumenter om relaterte tema ender som nærliggende punkter, noe som muliggjør semantisk søk: -Vektor-embedding-rom +Vector Embeddings Space -*Denne visualiseringen viser hvordan relaterte dokumenter klustrer sammen i 3D vektorrom, med tema som Tekniske Dokumenter, Forretningsregler og FAQ som separate grupper.* +*Denne visualiseringen viser hvordan relaterte dokumenter kluster sammen i 3D-vektorrom, med temaer som teknisk dokumentasjon, forretningsregler og ofte stilte spørsmål som egen grupper.* -Når en bruker søker, følger systemet fire trinn: embed dokumentene en gang, embed spørsmålet ved hvert søk, sammenligne spørsmålsvektoren mot alle lagrede vektorer med cosinuslikhet, og returnere topp-K høyest scorende biter. Diagrammet under viser hvert trinn og involverte LangChain4j-klasser: +Når en bruker søker, følger systemet fire trinn: embedder dokumentene én gang, embedder spørsmålet for hvert søk, sammenligner spørsmålsvektoren mot alle lagrede vektorer ved hjelp av cosinuslikhet, og returnerer de topp-K høyest rangerte bitene. Diagrammet nedenfor viser hvert trinn og LangChain4j-klassene involvert: -Trinn i embedding-søk +Embedding Search Steps -*Dette diagrammet viser fire-trinns embed-søkeprosess: embed dokumenter, embed spørring, sammenlign vektorer med cosinuslikhet, og returner topp-K resultater.* +*Dette diagrammet viser den fire-trinns embedding-søkeprosessen: embedde dokumenter, embedde spørsmål, sammenligne vektorer med cosinuslikhet, og returnere topp-K resultater.* ### Semantisk søk [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Når du stiller et spørsmål, blir også spørsmålet ditt konvertert til en embedding. Systemet sammenligner embedding av spørsmålet ditt med embeddings av alle dokumentbitene. Det finner bitene med mest lignende betydninger — ikke bare samsvarende nøkkelord, men faktisk semantisk likhet. +Når du stiller et spørsmål, blir spørsmålet også gjort om til en embedding. Systemet sammenligner spørsmålets embedding med alle embeddingene til dokumentbitene. Det finner bitene med de mest like betydningene — ikke bare samsvarende nøkkelord, men faktisk semantisk likhet. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Diagrammet under sammenligner semantisk søk med tradisjonelt nøkkelordssøk. Et nøkkelordssøk på "kjøretøy" overser en bit om "biler og lastebiler", men semantisk søk forstår at de betyr det samme og returnerer det med høyt resultat: +Diagrammet nedenfor sammenligner semantisk søk med tradisjonelt nøkkelordssøk. Et nøkkelordssøk etter "kjøretøy" overser biter om "biler og lastebiler", men semantisk søk forstår at de betyr det samme og returnerer det som et høyt scorende treff: -Semantisk søk +Semantic Search -*Dette diagrammet sammenligner nøkkelordsøk med semantisk søk, og viser hvordan semantisk søk henter fram konseptuelt relatert innhold selv når eksakte nøkkelord er forskjellige.* -Under panseret blir likhet målt ved hjelp av cosinuslikhet — i hovedsak spørres det "peker disse to pilene i samme retning?" To biter kan bruke helt forskjellige ord, men hvis de betyr det samme, peker vektorene deres i samme retning og får en poengsum nær 1.0: +*Dette diagrammet sammenligner nøkkelord-basert søk med semantisk søk, og viser hvordan semantisk søk henter fram konseptuelt relatert innhold selv om de eksakte nøkkelordene er forskjellige.* -Cosine Similarity +Under panseret måles likhet ved hjelp av cosinuslikhet — i praksis spør man "peker disse to pilene i samme retning?" To biter kan bruke helt forskjellige ord, men hvis de betyr det samme peker vektorene i samme retning og scorer nær 1,0: -*Dette diagrammet illustrerer cosinuslikhet som vinkelen mellom innebygde vektorer — mer justerte vektorer får en poengsum nærmere 1.0, noe som indikerer høyere semantisk likhet.* +Cosine Similarity +*Dette diagrammet illustrerer cosinuslikhet som vinkelen mellom innebyggingsvektorer — mer justerte vektorer får poeng nærmere 1.0, noe som indikerer høyere semantisk likhet.* > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) og spør: -> - "Hvordan fungerer søk etter likhet med innebygde representasjoner og hva bestemmer poengsummen?" -> - "Hvilken terskel for likhet bør jeg bruke og hvordan påvirker det resultatene?" +> - "Hvordan fungerer likhetssøk med embeddings og hva bestemmer poengsummen?" +> - "Hvilken likhetsterskel bør jeg bruke og hvordan påvirker det resultatene?" > - "Hvordan håndterer jeg tilfeller der ingen relevante dokumenter blir funnet?" -### Svargenerering +### Svar Generering [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -De mest relevante bitene settes sammen til en strukturert prompt som inkluderer eksplisitte instruksjoner, den hentede konteksten og brukerens spørsmål. Modellen leser disse spesifikke bitene og svarer basert på denne informasjonen — den kan bare bruke det som er foran den, noe som forhindrer hallusinasjoner. +De mest relevante delene settes sammen til en strukturert prompt som inkluderer eksplisitte instruksjoner, den hentede konteksten og brukerens spørsmål. Modellen leser disse spesifikke delene og svarer basert på den informasjonen — den kan kun bruke det som er foran seg, noe som forhindrer hallusinasjoner. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Diagrammet under viser denne sammensetningen i praksis — de høyest rangerte bitene fra søketrinnet settes inn i prompt-malen, og `OpenAiOfficialChatModel` genererer et forankret svar: +Diagrammet nedenfor viser denne sammensettingen i praksis — de høyest vurderte delene fra søketrinnet injiseres inn i promptmalen, og `OpenAiOfficialChatModel` genererer et forankret svar: Context Assembly -*Dette diagrammet viser hvordan de høyest rangerte bitene settes sammen til en strukturert prompt, slik at modellen kan generere et forankret svar basert på dataene dine.* +*Dette diagrammet viser hvordan de høyest vurderte delene settes sammen til en strukturert prompt, slik at modellen kan generere et forankret svar basert på dine data.* -## Kjør applikasjonen +## Kjør Applikasjonen -**Verifiser distribusjon:** +**Bekreft distribusjon:** -Sørg for at `.env`-filen finnes i rotmappen med Azure-legitimasjon (opprettet under Modul 01). Kjør dette fra modulkatalogen (`03-rag/`): +Sørg for at `.env`-filen finnes i rotkatalogen med Azure-legitimasjon (opprettet under Modul 01). Kjør dette fra modulkatalogen (`03-rag/`): **Bash:** ```bash @@ -256,16 +255,17 @@ cat ../.env # Bør vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **PowerShell:** ```powershell -Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Bør vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` + **Start applikasjonen:** -> **Merk:** Hvis du allerede har startet alle applikasjonene ved bruk av `./start-all.sh` fra rotmappen (som beskrevet i Modul 01), kjører denne modulen allerede på port 8081. Du kan hoppe over startkommandoene under og gå direkte til http://localhost:8081. +> **Merk:** Hvis du allerede startet alle applikasjonene med `./start-all.sh` fra rotkatalogen (som beskrevet i Modul 01), kjører denne modulen allerede på port 8081. Du kan hoppe over startkommandoene nedenfor og gå direkte til http://localhost:8081. **Alternativ 1: Bruke Spring Boot Dashboard (Anbefalt for VS Code-brukere)** -Dev-containeren inkluderer Spring Boot Dashboard-utvidelsen, som gir et visuelt grensesnitt for å administrere alle Spring Boot-applikasjoner. Du finner den i aktivitetslinjen til venstre i VS Code (se etter Spring Boot-ikonet). +Dev-containeren inkluderer Spring Boot Dashboard-utvidelsen, som gir et visuelt grensesnitt for administrasjon av alle Spring Boot-applikasjoner. Du finner det i Aktivitetslinjen på venstre side i VS Code (se etter Spring Boot-ikonet). Fra Spring Boot Dashboard kan du: - Se alle tilgjengelige Spring Boot-applikasjoner i arbeidsområdet @@ -273,15 +273,15 @@ Fra Spring Boot Dashboard kan du: - Se applikasjonslogger i sanntid - Overvåke applikasjonsstatus -Klikk på avspillingsknappen ved siden av "rag" for å starte denne modulen, eller start alle moduler samtidig. +Klikk ganske enkelt på play-knappen ved siden av "rag" for å starte denne modulen, eller start alle moduler samtidig. Spring Boot Dashboard -*Dette skjermbildet viser Spring Boot Dashboard i VS Code, hvor du visuelt kan starte, stoppe og overvåke applikasjoner.* +*Dette skjermbildet viser Spring Boot Dashboard i VS Code, hvor du kan starte, stoppe og overvåke applikasjoner visuelt.* **Alternativ 2: Bruke shell-skript** -Start alle webapplikasjoner (moduler 01-04): +Start alle web-applikasjoner (moduler 01-04): **Bash:** ```bash @@ -291,11 +291,11 @@ cd .. # Fra rotkatalogen **PowerShell:** ```powershell -cd .. # Fra rotdirektoriet +cd .. # Fra rotkatalogen .\start-all.ps1 ``` -Eller start bare denne modulen: +Eller start kun denne modulen: **Bash:** ```bash @@ -309,22 +309,23 @@ cd 03-rag .\start.ps1 ``` -Begge skriptene laster automatisk miljøvariabler fra rotens `.env`-fil og vil bygge JAR-filer om de ikke allerede finnes. +Begge skriptene laster automatisk miljøvariablene fra rotens `.env`-fil og bygger JAR-filene hvis de ikke finnes. -> **Merk:** Hvis du heller vil bygge alle moduler manuelt før oppstart: -> +> **Merk:** Hvis du foretrekker å bygge alle modulene manuelt før start: +> > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` + Åpne http://localhost:8081 i nettleseren din. **For å stoppe:** @@ -343,95 +344,95 @@ cd .. && ./stop-all.sh # Alle moduler cd ..; .\stop-all.ps1 # Alle moduler ``` -## Bruke applikasjonen +## Bruke Applikasjonen Applikasjonen tilbyr et webgrensesnitt for dokumentopplasting og spørsmål. RAG Application Interface -*Dette skjermbildet viser RAG-applikasjonens grensesnitt hvor du laster opp dokumenter og stiller spørsmål.* +*Dette skjermbildet viser RAG-applikasjonsgrensesnittet hvor du kan laste opp dokumenter og stille spørsmål.* -### Last opp et dokument +### Last opp et Dokument -Start med å laste opp et dokument - TXT-filer fungerer best for testing. En `sample-document.txt` er inkludert i denne katalogen som inneholder informasjon om LangChain4j-funksjoner, RAG-implementering og beste praksis - perfekt for systemtesting. +Start med å laste opp et dokument - TXT-filer fungerer best til testing. En `sample-document.txt` er inkludert i denne mappen som inneholder informasjon om LangChain4j-funksjoner, RAG-implementasjon og beste praksis - perfekt for å teste systemet. -Systemet behandler dokumentet ditt, deler det opp i biter og lager innebygde representasjoner for hver bit. Dette skjer automatisk ved opplasting. +Systemet behandler dokumentet ditt, deler det i biter og lager embeddings for hver bit. Dette skjer automatisk når du laster opp. -### Still spørsmål +### Still Spørsmål -Still nå spesifikke spørsmål om dokumentinnholdet. Prøv noe faktabasert som tydelig står i dokumentet. Systemet søker etter relevante biter, inkluderer dem i prompten, og genererer et svar. +Still nå spesifikke spørsmål om dokumentinnholdet. Prøv noe faktabasert som tydelig er uttrykt i dokumentet. Systemet søker etter relevante biter, inkluderer dem i prompten og genererer et svar. -### Sjekk kildereferanser +### Sjekk Kildehenvisninger -Merk at hvert svar inkluderer kildehenvisninger med likhetspoeng. Disse poengene (0 til 1) viser hvor relevante hver bit var for spørsmålet ditt. Høyere poeng betyr bedre treff. Dette lar deg verifisere svaret mot kildematerialet. +Merk at hvert svar inkluderer kildehenvisninger med likhetspoeng. Disse poengene (0 til 1) viser hvor relevant hver bit var i forhold til spørsmålet ditt. Høyere poeng betyr bedre treff. Dette lar deg verifisere svaret opp mot kildematerialet. RAG Query Results -*Dette skjermbildet viser resultater for spørring med generert svar, kildereferanser og relevanspoeng for hver hentede bit.* +*Dette skjermbildet viser spørringsresultater med generert svar, kildehenvisninger og relevanspoeng for hver hentede bit.* -### Eksperimenter med spørsmål +### Eksperimenter med Spørsmål Prøv ulike typer spørsmål: - Spesifikke fakta: "Hva er hovedtemaet?" - Sammenligninger: "Hva er forskjellen mellom X og Y?" -- Oppsummeringer: "Oppsummer hovedpunktene om Z" +- Sammendrag: "Oppsummer hovedpunktene om Z" -Se hvordan relevanspoengene endrer seg basert på hvor bra spørsmålet ditt matcher dokumentets innhold. +Se hvordan relevanspoengene endrer seg basert på hvor godt spørsmålet ditt matcher dokumentinnholdet. ## Nøkkelkonsepter -### Chunking-strategi +### Bitdeling Strategi -Dokumenter deles opp i 300-token biter med 30 tokens overlapp. Denne balansen sikrer at hver bit har nok kontekst til å være meningsfull samtidig som de er små nok til at flere biter kan inkluderes i en prompt. +Dokumenter deles i 300-token biter med 30 token overlapp. Denne balansen sikrer at hver bit har nok kontekst til å være meningsfull, samtidig som den er liten nok til å inkludere flere biter i en prompt. ### Likhetspoeng -Hver hentet bit kommer med en likhetspoengsum mellom 0 og 1 som angir hvor nært den matcher brukerens spørsmål. Diagrammet nedenfor visualiserer poengområdene og hvordan systemet bruker dem til å filtrere resultater: +Hver hentede bit har et likhetspoeng mellom 0 og 1 som indikerer hvor nært det matcher brukerens spørsmål. Diagrammet nedenfor visualiserer poengintervallene og hvordan systemet bruker dem til å filtrere resultater: Similarity Scores -*Dette diagrammet viser poengområder fra 0 til 1, med en minimumsterskel på 0.5 som filtrerer bort irrelevante biter.* +*Dette diagrammet viser poengintervaller fra 0 til 1, med en minimumsterskel på 0,5 som filtrerer bort irrelevante biter.* -Poeng varierer fra 0 til 1: -- 0.7-1.0: Svært relevante, eksakt treff -- 0.5-0.7: Relevante, god kontekst -- Under 0.5: Filtrert bort, for ulik +Poengene varierer fra 0 til 1: +- 0,7-1,0: Svært relevant, eksakt treff +- 0,5-0,7: Relevant, god kontekst +- Under 0,5: Filtrert ut, for ulikt Systemet henter kun biter over minimumsterskelen for å sikre kvalitet. -Innebygde representasjoner fungerer godt når mening samler seg klart, men har blinde soner. Diagrammet under viser vanlige feilmåter — biter som er for store gir uklare vektorer, biter som er for små mangler kontekst, tvetydige begreper peker til flere klynger, og eksakte oppslag (IDer, delenummer) fungerer ikke med innebygde representasjoner i det hele tatt: +Embeddings fungerer godt når meningen klynger seg tydelig, men har blinde flekker. Diagrammet nedenfor viser vanlige feilmåter — biter som er for store gir uklare vektorer, biter som er for små mangler kontekst, tvetydige termer peker til flere klynger, og eksakte oppslag (IDer, delenummer) fungerer ikke med embeddings i det hele tatt: Embedding Failure Modes -*Dette diagrammet viser vanlige feilmoduser for innebygde representasjoner: biter som er for store, biter som er for små, tvetydige begreper som peker til flere klynger og eksakte oppslag som IDer.* +*Dette diagrammet viser vanlige feil ved embedding: biter for store, biter for små, tvetydige termer som peker til flere klynger, og eksakte oppslag som IDer.* -### Lagring i minnet +### Minnebasert Lagring -Denne modulen bruker lagring i minnet for enkelhetens skyld. Når du starter applikasjonen på nytt, går opplastede dokumenter tapt. Produksjonssystemer bruker persistente vektor-databaser som Qdrant eller Azure AI Search. +Denne modulen bruker minnelagring for enkelhetens skyld. Når du starter applikasjonen på nytt, tapes opplastede dokumenter. Produksjonssystemer bruker vedvarende vektordatabaser som Qdrant eller Azure AI Search. -### Håndtering av kontekstvindu +### Kontekstvindu Håndtering -Hver modell har et maksimalt kontekstvindu. Du kan ikke inkludere alle biter fra et stort dokument. Systemet henter de N mest relevante bitene (standard 5) for å holde seg innenfor grenser samtidig som det gir nok kontekst for korrekte svar. +Hver modell har et maksimalt kontekstvindu. Du kan ikke inkludere alle biter fra et stort dokument. Systemet henter de øverste N mest relevante bitene (standard 5) for å holde seg innenfor grensen og samtidig gi nok kontekst for nøyaktige svar. -## Når RAG er viktig +## Når RAG Er Viktig -RAG er ikke alltid riktig tilnærming. Beslutningsguiden under hjelper deg å avgjøre når RAG tilfører verdi versus når enklere tilnærminger — som å inkludere innhold direkte i prompten eller stole på modellens innebygde kunnskap — er tilstrekkelige: +RAG er ikke alltid den riktige tilnærmingen. Beslutningsguiden nedenfor hjelper deg å avgjøre når RAG tilfører verdi kontra når enklere tilnærminger — som å inkludere innhold direkte i prompten eller stole på modellens innebygde kunnskap — er tilstrekkelig: When to Use RAG -*Dette diagrammet viser en beslutningsguide for når RAG tilfører verdi versus når enklere metoder er tilstrekkelige.* +*Dette diagrammet viser en beslutningsguide for når RAG tilfører verdi kontra når enklere tilnærminger er tilstrekkelig.* -## Neste steg +## Neste Steg -**Neste modul:** [04-tools - AI Agents med verktøy](../04-tools/README.md) +**Neste Modul:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**Navigasjon:** [← Forrige: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Tilbake til hoved](../README.md) | [Neste: Modul 04 - Verktøy →](../04-tools/README.md) +**Navigasjon:** [← Forrige: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Tilbake til Hoved](../README.md) | [Neste: Modul 04 - Verktøy →](../04-tools/README.md) --- **Ansvarsfraskrivelse**: -Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vennligst vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det originale dokumentet på det opprinnelige språket skal betraktes som den autoritative kilden. For viktig informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. +Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket skal betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. \ No newline at end of file diff --git a/translations/no/04-tools/README.md b/translations/no/04-tools/README.md index 7e7f910a9..24d315510 100644 --- a/translations/no/04-tools/README.md +++ b/translations/no/04-tools/README.md @@ -2,83 +2,83 @@ ## Innholdsfortegnelse -- [Video Gjennomgang](../../../04-tools) -- [Hva du vil lære](../../../04-tools) -- [Forutsetninger](../../../04-tools) -- [Forstå AI-agenter med verktøy](../../../04-tools) -- [Hvordan verktøyring fungerer](../../../04-tools) - - [Verktøydefinisjoner](../../../04-tools) - - [Beslutningstaking](../../../04-tools) - - [Utførelse](../../../04-tools) - - [Responsgenerering](../../../04-tools) - - [Arkitektur: Spring Boot Auto-Wiring](../../../04-tools) -- [Verktøykjeding](../../../04-tools) -- [Kjør applikasjonen](../../../04-tools) -- [Bruk applikasjonen](../../../04-tools) - - [Prøv enkel bruk av verktøy](../../../04-tools) - - [Test verktøykjeding](../../../04-tools) - - [Se samtaleflyt](../../../04-tools) - - [Eksperimenter med ulike forespørsler](../../../04-tools) -- [Viktige konsepter](../../../04-tools) - - [ReAct-mønsteret (resonnering og handling)](../../../04-tools) - - [Verktøybeskrivelser betyr noe](../../../04-tools) - - [Sesjonshåndtering](../../../04-tools) - - [Feilhåndtering](../../../04-tools) -- [Tilgjengelige verktøy](../../../04-tools) -- [Når bruke verktøybaserte agenter](../../../04-tools) -- [Verktøy vs RAG](../../../04-tools) -- [Neste steg](../../../04-tools) - -## Video Gjennomgang - -Se denne live-økten som forklarer hvordan du kommer i gang med denne modulen: +- [Video-gjennomgang](#video-gjennomgang) +- [Hva du vil lære](#hva-du-vil-lære) +- [Forutsetninger](#forutsetninger) +- [Forstå AI-agenter med verktøy](#forstå-ai-agenter-med-verktøy) +- [Hvordan verktøysanrop fungerer](#hvordan-verktøysanrop-fungerer) + - [Verktøydefinisjoner](#verktøydefinisjoner) + - [Beslutningstaking](#beslutningstaking) + - [Utførelse](#utførelse) + - [Generering av svar](#generering-av-svar) + - [Arkitektur: Spring Boot Auto-Wiring](#arkitektur-spring-boot-auto-wiring) +- [Verktøykjeding](#verktøykjeding) +- [Kjør applikasjonen](#kjør-applikasjonen) +- [Bruke applikasjonen](#bruke-applikasjonen) + - [Prøv enkel verktøybruk](#prøv-enkel-bruk-av-verktøy) + - [Test verktøykjeding](#test-kjeding-av-verktøy) + - [Se samtaleflyt](#se-samtaleflyt) + - [Eksperimenter med forskjellige spørsmål](#eksperimenter-med-forskjellige-forespørsler) +- [Nøkkelkonsepter](#nøkkelkonsepter) + - [ReAct-mønsteret (resonnering og handling)](#react-mønsteret-resonnering-og-handling) + - [Verktøybeskrivelser betyr noe](#verktøybeskrivelser-er-viktige) + - [Sesjonshåndtering](#sesjonshåndtering) + - [Feilhåndtering](#feilhåndtering) +- [Tilgjengelige verktøy](#tilgjengelige-verktøy) +- [Når bør man bruke verktøybaserte agenter](#når-bruke-verktøybaserte-agenter) +- [Verktøy vs RAG](#verktøy-vs-rag) +- [Neste steg](#neste-steg) + +## Video-gjennomgang + +Se denne livesesjonen som forklarer hvordan du kommer i gang med denne modulen: AI Agents with Tools and MCP - Live Session ## Hva du vil lære -Så langt har du lært hvordan du har samtaler med AI, strukturerer prompts effektivt, og kobler svar til dokumentene dine. Men det er fortsatt en grunnleggende begrensning: språkmodeller kan kun generere tekst. De kan ikke sjekke været, utføre beregninger, spørre databaser eller samhandle med eksterne systemer. +Så langt har du lært hvordan du kan føre samtaler med AI, strukturere prompt effektivt, og forankre svar i dokumentene dine. Men det finnes fortsatt en grunnleggende begrensning: språkmodeller kan bare generere tekst. De kan ikke sjekke været, utføre beregninger, spørringer i databaser, eller samhandle med eksterne systemer. -Verktøy endrer dette. Ved å gi modellen tilgang til funksjoner den kan kalle, forvandler du den fra en tekstgenerator til en agent som kan utføre handlinger. Modellen bestemmer når den trenger et verktøy, hvilket verktøy den skal bruke, og hvilke parametere den skal sende med. Koden din utfører funksjonen og returnerer resultatet. Modellen inkorporerer deretter resultatet i sitt svar. +Verktøy endrer dette. Ved å gi modellen tilgang til funksjoner den kan kalle, forvandler du den fra en tekstgenerator til en agent som kan utføre handlinger. Modellen bestemmer når den trenger et verktøy, hvilket verktøy den skal bruke og hvilke parametere som skal sendes. Koden din utfører funksjonen og returnerer resultatet. Modellen integrerer resultatet i svaret. ## Forutsetninger - Fullført [Modul 01 - Introduksjon](../01-introduction/README.md) (Azure OpenAI-ressurser distribuert) -- Anbefalt å ha fullført tidligere moduler (denne modulen refererer til [RAG-konsepter fra Modul 03](../03-rag/README.md) i sammenligningen Verktøy vs RAG) -- `.env`-fil i rotkatalogen med Azure-legitimasjon (opprettet via `azd up` i Modul 01) +- Det anbefales å ha fullført tidligere moduler (denne modulen refererer til [RAG-konsepter fra Modul 03](../03-rag/README.md) i sammenligningen mellom Verktøy vs RAG) +- `.env`-fil i rotmappen med Azure-legitimasjon (opprettet med `azd up` i Modul 01) -> **Merk:** Hvis du ikke har fullført Modul 01, følg distribusjonsinstruksjonene der først. +> **Merk:** Hvis du ikke har fullført Modul 01, følg først distribusjonsinstruksjonene der. ## Forstå AI-agenter med verktøy -> **📝 Merk:** Begrepet "agenter" i denne modulen refererer til AI-assistenter med forbedret funksjonalitet for å kalle verktøy. Dette er forskjellig fra **Agentic AI**-mønstrene (autonome agenter med planlegging, hukommelse og flerstegs resonnering) som vi skal dekke i [Modul 05: MCP](../05-mcp/README.md). +> **📝 Merknad:** Begrepet "agenter" i denne modulen refererer til AI-assistenter utvidet med muligheter for å kalle verktøy. Dette er forskjellig fra **Agentic AI**-mønstrene (autonome agenter med planlegging, minne og flertrinns resonnering) som vi dekker i [Modul 05: MCP](../05-mcp/README.md). -Uten verktøy kan en språkmodell bare generere tekst basert på treningsdataene sine. Spør om været i dag, og den må gjette. Gi den verktøy, og den kan kalle en vær-API, utføre beregninger eller spørre en database — og deretter flette de reelle resultatene inn i svaret sitt. +Uten verktøy kan en språkmodell bare generere tekst basert på treningsdataene sine. Spør den om været, og den må gjette. Gi den verktøy, og den kan kalle en vær-API, utføre beregninger, eller søke i en database — og deretter veve disse virkelige resultatene inn i svaret sitt. Without Tools vs With Tools -*Uten verktøy kan modellen bare gjette — med verktøy kan den kalle APIer, kjøre beregninger og returnere sanntidsdata.* +*Uten verktøy kan modellen bare gjette — med verktøy kan den kalle API-er, regne ut og returnere data i sanntid.* -En AI-agent med verktøy følger et **Reasoning and Acting (ReAct)**-mønster. Modellen svarer ikke bare — den tenker på hva den trenger, handler ved å kalle et verktøy, observerer resultatet, og bestemmer så om den skal handle igjen eller levere det endelige svaret: +En AI-agent med verktøy følger et **Reasoning and Acting (ReAct)**-mønster. Modellen bare svarer ikke — den tenker over hva den trenger, handler ved å kalle et verktøy, observerer resultatet, og bestemmer så om den skal handle igjen eller gi endelig svar: -1. **Resonner** — Agenten analyserer brukerens spørsmål og bestemmer hvilken informasjon den trenger -2. **Handle** — Agenten velger riktig verktøy, genererer riktige parametere og kaller det -3. **Observer** — Agenten mottar verktøyets output og evaluerer resultatet -4. **Gjenta eller Svar** — Om mer data trengs, gjentas prosessen; ellers komponerer den et svar på naturlig språk +1. **Resonner** — Agenten analyserer brukerens spørsmål og finner ut hvilken informasjon den trenger +2. **Handle** — Agenten velger riktig verktøy, genererer korrekte parametere og kaller det +3. **Observer** — Agenten mottar verktøyets resultat og vurderer det +4. **Gjenta eller svar** — Hvis mer data trengs, går agenten tilbake; ellers setter den sammen et naturlig språk-svar ReAct Pattern -*ReAct-syklusen — agenten resonnerer over hva den skal gjøre, handler ved å kalle et verktøy, observerer resultatet og gjentar til den kan levere et endelig svar.* +*ReAct-syklusen — agenten resonerer om hva den skal gjøre, handler ved å kalle et verktøy, observerer resultatet, og gjentar til den kan gi endelig svar.* -Dette skjer automatisk. Du definerer verktøyene og beskrivelsene deres. Modellen håndterer beslutningene om når og hvordan de skal brukes. +Dette skjer automatisk. Du definerer verktøyene og beskrivelsene deras. Modellen håndterer beslutningstaking om når og hvordan de skal brukes. -## Hvordan verktøyring fungerer +## Hvordan verktøysanrop fungerer ### Verktøydefinisjoner [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Du definerer funksjoner med klare beskrivelser og parametere. Modellen ser disse beskrivelsene i systemprompten sin og forstår hva hvert verktøy gjør. +Du definerer funksjoner med klare beskrivelser og parameter-spesifikasjoner. Modellen ser disse beskrivelsene i systemprompten sin og forstår hva hvert verktøy gjør. ```java @Component @@ -102,98 +102,98 @@ public interface Assistant { // - ChatMemoryProvider for øktadministrasjon ``` -Diagrammet under forklarer hver annotasjon og viser hvordan hver del hjelper AI til å forstå når den skal kalle verktøyet og hvilke argumenter den skal sende: +Diagrammet nedenfor bryter ned hver annotasjon og viser hvordan hver del hjelper AI til å forstå når den skal kalle verktøyet og hvilke argumenter som skal gis: Anatomy of Tool Definitions -*Anatomi av en verktøydefinisjon — @Tool forteller AI når verktøyet brukes, @P beskriver hver parameter, og @AiService kobler alt sammen ved oppstart.* +*Anatomi av en verktøydefinisjon — @Tool forteller AI når den skal bruke det, @P beskriver hver parameter, og @AiService kobler alt sammen ved oppstart.* > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) og spør: -> - "Hvordan integrerer jeg en ekte vær-API som OpenWeatherMap i stedet for mock-data?" -> - "Hva gjør en god verktøybeskrivelse som hjelper AI å bruke det korrekt?" -> - "Hvordan håndterer jeg API-feil og rate limits i verktøyimplementasjoner?" +> - "Hvordan kan jeg integrere en ekte vær-API som OpenWeatherMap i stedet for mockdata?" +> - "Hva kjennetegner en god verktøybeskrivelse som hjelper AI å bruke det korrekt?" +> - "Hvordan håndterer jeg API-feil og rate limits i implementasjon av verktøy?" ### Beslutningstaking -Når en bruker spør "Hva er været i Seattle?", velger ikke modellen et verktøy tilfeldig. Den sammenligner brukerens intensjon med alle verktøybeskrivelser den har tilgang til, scorer relevansen for hver, og velger det beste treffet. Den genererer så et strukturert funksjonskall med riktige parametere — i dette tilfellet setter den `location` til `"Seattle"`. +Når en bruker spør "Hva er været i Seattle?", velger ikke modellen verktøy tilfeldig. Den sammenligner brukerens intensjon med alle verktøybeskrivelser den har tilgang til, scorer relevans for hvert, og velger det beste treffet. Den genererer så et strukturert funksjonsanrop med riktige parametere — her settes `location` til `"Seattle"`. -Hvis ingen verktøy passer brukerens forespørsel, svarer modellen basert på egen kunnskap. Hvis flere verktøy matcher, velger den det mest spesifikke. +Hvis ingen verktøy matcher brukerens forespørsel, faller modellen tilbake på å svare fra sin egen kunnskap. Hvis flere verktøy matcher, velger den det mest spesifikke. How the AI Decides Which Tool to Use -*Modellen evaluerer hvert tilgjengelige verktøy mot brukerens intensjon og velger den beste matchen — derfor er klare, spesifikke verktøybeskrivelser viktige.* +*Modellen vurderer hvert tilgjengelige verktøy mot brukerens intensjon og velger beste match — derfor er det viktig å skrive klare, spesifikke verktøybeskrivelser.* ### Utførelse [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot autoinjiserer det deklarative `@AiService`-grensesnittet med alle registrerte verktøy, og LangChain4j utfører verktøykall automatisk. Bak kulissene går et fullstendig verktøykall gjennom seks stadier — fra brukerens spørsmål på naturlig språk helt tilbake til et svar på naturlig språk: +Spring Boot kobler automatisk det deklarative `@AiService`-grensesnittet med alle registrerte verktøy, og LangChain4j utfører verktøysanrop automatisk. Bak kulissene flyter et komplett verktøysanrop gjennom seks stadier — fra brukerens naturlige språk-spørsmål helt tilbake til et svar i naturlig språk: Tool Calling Flow -*Hele flyten — brukeren stiller et spørsmål, modellen velger et verktøy, LangChain4j utfører det, og modellen fletter resultatet inn i et naturlig svar.* +*Ende-til-ende-flyt — brukeren stiller et spørsmål, modellen velger et verktøy, LangChain4j utfører det, og modellen vever resultatet inn i et naturlig svar.* -Hvis du kjørte [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) i Modul 00, har du allerede sett dette mønsteret i aksjon — `Calculator`-verktøyene ble kalt på samme måte. Sekvensdiagrammet under viser nøyaktig hva som skjedde under demoen: +Bak kulissene kjører `AiServices` samme verktøysanrop-løkke for hvilket som helst verktøy — her illustrert med en enkel `Calculator`. Sekvensdiagrammet under viser nøyaktig hva som skjer under panseret: Tool Calling Sequence Diagram -*Verktøykallsløyfen fra Quick Start-demoen — `AiServices` sender meldingen og verktøyskjemaene til LLM-en, LLM-en svarer med et funksjonskall som `add(42, 58)`, LangChain4j kjører `Calculator`-metoden lokalt og sender resultatet tilbake for det endelige svaret.* +*Verktøysanrop-løkka — `AiServices` sender meldingen og verktøyskjemadefinisjoner til LLM, LLM svarer med et funksjonskall som `add(42, 58)`, LangChain4j utfører `Calculator`-metoden lokalt, og leverer resultatet tilbake for endelig svar.* > **🤖 Prøv med [GitHub Copilot](https://github.com/features/copilot) Chat:** Åpne [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) og spør: > - "Hvordan fungerer ReAct-mønsteret og hvorfor er det effektivt for AI-agenter?" -> - "Hvordan bestemmer agenten hvilket verktøy som skal brukes og i hvilken rekkefølge?" -> - "Hva skjer hvis utførelsen av et verktøy feiler – hvordan håndterer jeg feil på en robust måte?" +> - "Hvordan avgjør agenten hvilket verktøy den skal bruke og i hvilken rekkefølge?" +> - "Hva skjer om utføring av et verktøy feiler - hvordan håndterer jeg robust feilhåndtering?" -### Responsgenerering +### Generering av svar -Modellen mottar værdataene og formaterer dem til et svar på naturlig språk til brukeren. +Modellen mottar værdataene og formaterer dem til et svar i naturlig språk for brukeren. ### Arkitektur: Spring Boot Auto-Wiring -Denne modulen bruker LangChain4j sin Spring Boot-integrasjon med deklarative `@AiService` grensesnitt. Ved oppstart oppdager Spring Boot alle `@Component` som inneholder `@Tool`-metoder, din `ChatModel` bean, og `ChatMemoryProvider` — og kobler dem sammen i et enkelt `Assistant`-grensesnitt med null boilerplate. +Denne modulen bruker LangChain4j sin Spring Boot-integrasjon med deklarative `@AiService`-grensesnitt. Ved oppstart oppdager Spring Boot hver `@Component` som inneholder `@Tool`-metoder, beanen din for `ChatModel`, og `ChatMemoryProvider` — og kobler dem sammen til et enkelt `Assistant`-grensesnitt uten behov for boilerplate. Spring Boot Auto-Wiring Architecture -*@AiService-grensesnittet binder sammen ChatModel, verktøyskomponenter og minneprovider — Spring Boot håndterer all kobling automatisk.* +*@AiService-grensesnittet binder sammen ChatModel, verktøykomponenter og minnetilbyder — Spring Boot håndterer hele koblingen automatisk.* -Her er hele forespørselslivssyklusen som sekvensdiagram — fra HTTP-forespørselen gjennom controller, service og autoinjisert proxy, hele veien til verktøyutførelse og tilbake: +Her er hele forespørselslivssyklusen som et sekvensdiagram — fra HTTP-forespørselen gjennom controller, service og auto-koble proxy, helt til verktøyutførelse og tilbake: Spring Boot Tool Calling Sequence -*Hele Spring Boot forespørselslivssyklusen — HTTP-forespørselen går gjennom controller og service til den autoinjiserte Assistant-proxyen som orkestrerer LLM og verktøykall automatisk.* +*Fullstendig Spring Boot-forespørselslivssyklus — HTTP-forespørsel går gjennom controller og service til auto-koble Assistant-proxy, som orkestrerer LLM og verktøysanrop automatisk.* Viktige fordeler med denne tilnærmingen: - **Spring Boot auto-wiring** — ChatModel og verktøy injiseres automatisk -- **@MemoryId-mønster** — Automatisk sesjonsbasert minnehåndtering +- **@MemoryId-mønster** — Automatisk minnehåndtering per sesjon - **Enkelt instans** — Assistant opprettes én gang og gjenbrukes for bedre ytelse - **Typesikker utførelse** — Java-metoder kalles direkte med typekonvertering -- **Orkestrering med flere steg** — Håndterer verktøykjeding automatisk -- **Null boilerplate** — Ingen manuelle `AiServices.builder()`-kall eller minne-HashMap +- **Orkestrering med flere trinn** — Håndterer verktøykjeding automatisk +- **Ingen boilerplate** — Ingen manuelle `AiServices.builder()`-kall eller memory HashMap -Alternative tilnærminger (manuell `AiServices.builder()`) krever mer kode og mangler Spring Boot-integrasjonens fordeler. +Alternative tilnærminger (manuelle `AiServices.builder()`) krever mer kode og mangler Spring Boot-integrasjonsfordelene. ## Verktøykjeding -**Verktøykjeding** — Den virkelige styrken med verktøybaserte agenter viser seg når ett enkelt spørsmål krever flere verktøy. Spør "Hva er været i Seattle i Fahrenheit?" og agenten kjeder automatisk to verktøy: først kaller den `getCurrentWeather` for å få temperaturen i Celsius, deretter sender den den verdien til `celsiusToFahrenheit` for konvertering — alt i en enkelt samtalerunde. +**Verktøykjeding** — Den virkelige kraften i verktøybaserte agenter vises når ett enkelt spørsmål trenger flere verktøy. Spør "Hva er været i Seattle i Fahrenheit?" og agenten kjeder automatisk sammen to verktøy: først kaller den `getCurrentWeather` for å få temperaturen i Celsius, deretter sender den den verdien til `celsiusToFahrenheit` for konvertering — alt i én enkelt samtaleomgang. Tool Chaining Example -*Verktøykjeding i aksjon — agenten kaller getCurrentWeather først, pipeliner Celsius-resultatet inn i celsiusToFahrenheit, og gir et kombinert svar.* +*Verktøykjeding i praksis — agenten kaller først getCurrentWeather, deretter sender den Celsius-resultatet videre til celsiusToFahrenheit, og leverer et kombinert svar.* -**Graceful Failures** — Spør etter været i en by som ikke finnes i mock-data. Verktøyet returnerer en feilmelding, og AI forklarer at det ikke kan hjelpe i stedet for å krasje. Verktøy feiler trygt. Diagrammet under sammenligner de to tilnærmingene — med riktig feilhåndtering fanger agenten opp unntaket og svarer hjelpsomt, uten det krasjer hele applikasjonen: +**Grasiøse feil** — Be om vær i en by som ikke finnes i mock-dataene. Verktøyet returnerer en feilmelding, og AI forklarer at det ikke kan hjelpe i stedet for å krasje. Verktøy feiler trygt. Diagrammet under kontrasterer de to tilnærmingene — med skikkelig feilhåndtering fanger agenten unntaket og svarer hjelpsomt, uten håndtering krasjer hele applikasjonen: Error Handling Flow -*Når et verktøy feiler, fanger agenten opp feilen og svarer med en hjelpsom forklaring i stedet for å krasje.* +*Når et verktøy feiler, fanger agenten feilen og svarer med en hjelpsom forklaring i stedet for at det krasjer.* -Dette skjer i en enkelt samtalerunde. Agenten orkestrerer flere verktøykall autonomt. +Dette skjer i én enkelt samtalerunde. Agenten orkestrerer flere verktøysanrop autonomt. ## Kjør applikasjonen -**Bekreft distribusjon:** +**Verifiser distribusjon:** -Sørg for at `.env`-filen finnes i rotkatalogen med Azure-legitimasjon (opprettet i Modul 01). Kjør dette fra modulmappen (`04-tools/`): +Sørg for at `.env`-filen finnes i rotmappen med Azure-legitimasjon (opprettet under Modul 01). Kjør dette fra modulkatalogen (`04-tools/`): **Bash:** ```bash @@ -207,26 +207,26 @@ Get-Content ..\.env # Skal vise AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Start applikasjonen:** -> **Merk:** Hvis du allerede startet alle applikasjoner med `./start-all.sh` fra rotkatalogen (som beskrevet i Modul 01), kjører denne modulen allerede på port 8084. Du kan hoppe over startkommandoene under og gå direkte til http://localhost:8084. +> **Merk:** Hvis du allerede startet alle applikasjoner med `./start-all.sh` i rotmappen (som beskrevet i Modul 01), kjører denne modulen allerede på port 8084. Da kan du hoppe over startkommandoene nedenfor og gå rett til http://localhost:8084. -**Alternativ 1: Bruke Spring Boot Dashboard (Anbefalt for VS Code-brukere)** +**Alternativ 1: Bruke Spring Boot Dashboard (anbefalt for VS Code-brukere)** -Dev-containeren inkluderer Spring Boot Dashboard-utvidelsen, som gir et visuelt grensesnitt for å administrere alle Spring Boot-applikasjoner. Du finner det i Aktivitetsfeltet til venstre i VS Code (se etter Spring Boot-ikonet). +Dev-containeren inkluderer Spring Boot Dashboard-utvidelsen, som gir et visuelt grensesnitt for å administrere alle Spring Boot-applikasjoner. Du finner det i aktivitetsbaren til venstre i VS Code (se etter Spring Boot-ikonet). Fra Spring Boot Dashboard kan du: - Se alle tilgjengelige Spring Boot-applikasjoner i arbeidsområdet - Starte/stoppe applikasjoner med ett klikk - Se applikasjonslogger i sanntid - Overvåke applikasjonsstatus -Klikk ganske enkelt på avspillingsknappen ved siden av "tools" for å starte denne modulen, eller start alle moduler på en gang. -Slik ser Spring Boot Dashboard ut i VS Code: +Klikk bare på spill-knappen ved siden av "tools" for å starte denne modulen, eller start alle moduler samtidig. +Slik ser Spring Boot Dashboard ut i VS Code: Spring Boot Dashboard *Spring Boot Dashboard i VS Code — start, stopp og overvåk alle moduler fra ett sted* -**Alternativ 2: Bruke shell-skript** +**Valg 2: Bruke shell-skript** Start alle webapplikasjoner (moduler 01-04): @@ -256,7 +256,7 @@ cd 04-tools .\start.ps1 ``` -Begge skriptene laster automatisk miljøvariabler fra rotens `.env`-fil og bygger JAR-filene hvis de ikke finnes. +Begge skriptene laster automatisk miljøvariabler fra rot-`.env`-filen og bygger JAR-filene hvis de ikke eksisterer. > **Merk:** Hvis du foretrekker å bygge alle moduler manuelt før oppstart: > @@ -265,7 +265,7 @@ Begge skriptene laster automatisk miljøvariabler fra rotens `.env`-fil og bygge > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -292,36 +292,36 @@ cd ..; .\stop-all.ps1 # Alle moduler ## Bruke applikasjonen -Applikasjonen gir et nettgrensesnitt der du kan samhandle med en AI-agent som har tilgang til vær- og temperaturkonverteringsverktøy. Slik ser grensesnittet ut — det inkluderer raske start-eksempler og et chattepanel for å sende forespørsler: +Applikasjonen tilbyr et nettgrensesnitt hvor du kan samhandle med en AI-agent som har tilgang til verktøy for vær og temperaturkonvertering. Slik ser grensesnittet ut — det inkluderer rask-starter eksempler og en samtalepanel for å sende forespørsler: AI Agent Tools Interface -*AI Agent Tools-grensesnittet - raske eksempler og chattegrensesnitt for samhandling med verktøy* +*AI Agent Tools-grensesnittet - raske eksempler og chattegrensesnitt for verktøysamhandling* ### Prøv enkel bruk av verktøy -Start med en enkel forespørsel: "Konverter 100 grader Fahrenheit til Celsius". Agenten forstår at den trenger temperaturkonverteringsverktøyet, kaller det med riktige parametere og returnerer resultatet. Legg merke til hvor naturlig dette føles – du spesifiserte ikke hvilket verktøy som skulle brukes eller hvordan det skulle kalles. +Start med en enkel forespørsel: "Konverter 100 grader Fahrenheit til Celsius". Agenten skjønner at den trenger temperaturkonverteringsverktøyet, kaller det med riktige parametere og returnerer resultatet. Legg merke til hvor naturlig dette føles - du spesifiserte ikke hvilket verktøy som skulle brukes eller hvordan det skulle kalles. -### Test verktøykjededannelse +### Test kjeding av verktøy -Prøv nå noe mer komplekst: "Hvordan er været i Seattle, og konverter det til Fahrenheit?" Se agenten jobbe gjennom dette i steg. Den henter først været (som returnerer Celsius), skjønner at den må konvertere til Fahrenheit, kaller konverteringsverktøyet, og kombinerer begge resultater til ett svar. +Prøv nå noe mer komplekst: "Hvordan er været i Seattle og konverter det til Fahrenheit?" Se agenten jobbe steg for steg. Først henter den været (som returnerer i Celsius), forstår at den må konvertere til Fahrenheit, kaller konverteringsverktøyet, og kombinerer begge resultater til ett svar. ### Se samtaleflyt -Chattegrensesnittet opprettholder samtalehistorikk, slik at du kan ha interaksjoner over flere turer. Du kan se alle tidligere spørsmål og svar, noe som gjør det enkelt å følge samtalen og forstå hvordan agenten bygger kontekst over flere utvekslinger. +Chattesystemet bevarer samtalehistorikken, slik at du kan ha flertrinns interaksjoner. Du kan se alle tidligere forespørsler og svar, noe som gjør det enkelt å følge samtalen og forstå hvordan agenten bygger kontekst over flere utvekslinger. Conversation with Multiple Tool Calls -*Fleromgangssamtale som viser enkle konverteringer, væroppslag og verktøykjededannelse* +*Flertrinns samtale som viser enkle konverteringer, værspørringer og kjeding av verktøy* ### Eksperimenter med forskjellige forespørsler Prøv ulike kombinasjoner: -- Væroppslag: "Hvordan er været i Tokyo?" +- Værspørringer: "Hvordan er været i Tokyo?" - Temperaturkonverteringer: "Hva er 25°C i Kelvin?" -- Kombinerte spørringer: "Sjekk været i Paris og fortell meg om det er over 20°C" +- Kombinerte forespørsler: "Sjekk været i Paris og fortell meg om det er over 20°C" -Legg merke til hvordan agenten tolker vanlig språk og mapper det til passende verktøykall. +Legg merke til hvordan agenten tolker naturlig språk og oversetter det til korrekte verktøys-kall. ## Nøkkelkonsepter @@ -329,21 +329,21 @@ Legg merke til hvordan agenten tolker vanlig språk og mapper det til passende v Agenten veksler mellom å resonnere (bestemme hva som skal gjøres) og å handle (bruke verktøy). Dette mønsteret muliggjør autonom problemløsning i stedet for bare å svare på instruksjoner. -### Verktøybeskrivelser betyr noe +### Verktøybeskrivelser er viktige -Kvaliteten på dine verktøybeskrivelser påvirker direkte hvor godt agenten bruker dem. Klare, spesifikke beskrivelser hjelper modellen med å forstå når og hvordan hvert verktøy skal kalles. +Kvaliteten på verktøybeskrivelsene dine påvirker hvor godt agenten bruker dem. Klare, spesifikke beskrivelser hjelper modellen å vite når og hvordan hvert verktøy skal kalles. ### Sesjonshåndtering -`@MemoryId`-annotasjonen muliggjør automatisk minnehåndtering basert på økter. Hver sesjons-ID får sin egen `ChatMemory`-instans som håndteres av `ChatMemoryProvider`-beanen, slik at flere brukere kan samhandle med agenten samtidig uten at samtalene blander seg. Følgende diagram viser hvordan flere brukere rutes til isolerte minnelagre basert på deres sesjons-IDer: +`@MemoryId`-annotasjonen gjør det mulig å håndtere minne basert på økter automatisk. Hver økt-ID får sin egen `ChatMemory`-instans som administreres av `ChatMemoryProvider`-bean, slik at flere brukere kan samhandle med agenten samtidig uten at samtalene blandes. Følgende diagram viser hvordan flere brukere blir rutet til isolerte minnelagre basert på sesjons-IDer: Session Management with @MemoryId -*Hver sesjons-ID kobles til en isolert samtalehistorikk — brukere ser aldri hverandres meldinger.* +*Hver sesjons-ID kartlegges til en isolert samtalehistorikk — brukere ser aldri hverandres meldinger.* ### Feilhåndtering -Verktøy kan feile — APIer kan tidsavslutte, parametere kan være ugyldige, eksterne tjenester kan gå ned. Produksjonsagenter trenger feilhåndtering slik at modellen kan forklare problemer eller prøve alternativer i stedet for å krasje hele applikasjonen. Når et verktøy kaster en unntak, fanger LangChain4j det og sender feilmeldingen tilbake til modellen, som deretter kan forklare problemet på naturlig språk. +Verktøy kan feile — API-er kan time ut, parametere kan være ugyldige, eksterne tjenester kan være nede. Produksjonsagenter trenger feilhåndtering slik at modellen kan forklare problemer eller prøve alternativer i stedet for å krasje hele applikasjonen. Når et verktøy kaster en unntak, fanger LangChain4j det og sender feilmeldingen tilbake til modellen, som deretter kan forklare problemet på naturlig språk. ## Tilgjengelige verktøy @@ -351,25 +351,25 @@ Diagrammet nedenfor viser det brede økosystemet av verktøy du kan bygge. Denne Tool Ecosystem -*Enhver Java-metode merket med @Tool blir tilgjengelig for AI — mønsteret strekker seg til databaser, APIer, e-post, filoperasjoner og mer.* +*Enhver Java-metode annotert med @Tool blir tilgjengelig for AI — mønsteret strekker seg til databaser, API-er, e-post, filoperasjoner og mer.* ## Når bruke verktøybaserte agenter -Ikke alle forespørsler trenger verktøy. Beslutningen handler om AI-en må samhandle med eksterne systemer eller kan svare basert på egen kunnskap. Følgende guide oppsummerer når verktøy tilfører verdi og når de er unødvendige: +Ikke alle forespørsler trenger verktøy. Beslutningen handler om AI-en må samhandle med eksterne systemer eller kan svare ut fra egen kunnskap. Guiden nedenfor oppsummerer når verktøy tilfører verdi og når de ikke er nødvendige: When to Use Tools -*En rask beslutningsguide — verktøy brukes for sanntidsdata, beregninger og handlinger; generell kunnskap og kreative oppgaver trenger ikke dem.* +*En rask beslutningsguide — verktøy er for sanntidsdata, beregninger og handlinger; generell kunnskap og kreative oppgaver trenger dem ikke.* ## Verktøy vs RAG -Modulene 03 og 04 utvider begge hva AI kan gjøre, men på fundamentalt forskjellige måter. RAG gir modellen tilgang til **kunnskap** ved å hente dokumenter. Verktøy gir modellen mulighet til å utføre **handlinger** ved å kalle funksjoner. Diagrammet nedenfor sammenligner disse to tilnærmingene side om side — fra hvordan hver arbeidsflyt opererer til kompromisene mellom dem: +Modulene 03 og 04 utvider begge hva AI-en kan gjøre, men på fundamentalt forskjellige måter. RAG gir modellen tilgang til **kunnskap** ved å hente dokumenter. Verktøy gir modellen muligheten til å utføre **handlinger** ved å kalle funksjoner. Diagrammet nedenfor sammenligner disse to tilnærmingene side om side — fra hvordan hver arbeidsflyt opererer til kompromissene mellom dem: Tools vs RAG Comparison -*RAG henter informasjon fra statiske dokumenter — verktøy utfører handlinger og henter dynamiske, sanntidsdata. Mange produksjonssystemer kombinerer begge.* +*RAG henter informasjon fra statiske dokumenter — Verktøy utfører handlinger og henter dynamiske sanntidsdata. Mange produksjonssystemer kombinerer begge.* -I praksis kombinerer mange produksjonssystemer begge tilnærminger: RAG for å forankre svar i dokumentasjonen din, og verktøy for å hente live data eller utføre operasjoner. +I praksis kombinerer mange produksjonssystemer begge tilnærminger: RAG for å forankre svar i dokumentasjonen din, og Verktøy for å hente levende data eller utføre operasjoner. ## Neste steg @@ -377,11 +377,11 @@ I praksis kombinerer mange produksjonssystemer begge tilnærminger: RAG for å f --- -**Navigasjon:** [← Forrige: Modul 03 - RAG](../03-rag/README.md) | [Tilbake til hovedmenyen](../README.md) | [Neste: Modul 05 - MCP →](../05-mcp/README.md) +**Navigasjon:** [← Forrige: Modul 03 - RAG](../03-rag/README.md) | [Tilbake til hovedside](../README.md) | [Neste: Modul 05 - MCP →](../05-mcp/README.md) --- **Ansvarsfraskrivelse**: -Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vennligst vær klar over at automatiserte oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på dets morsmål bør betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. +Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket skal betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. \ No newline at end of file diff --git a/translations/no/README.md b/translations/no/README.md index ebe9fe3b4..51c0c71fd 100644 --- a/translations/no/README.md +++ b/translations/no/README.md @@ -2,18 +2,18 @@ # LangChain4j for nybegynnere -Et kurs for å bygge AI-applikasjoner med LangChain4j og Azure OpenAI GPT-5.2, fra grunnleggende chat til AI-agenter. +Et kurs for å bygge AI-applikasjoner med LangChain4j og Azure OpenAI GPT-5.2, fra enkel chat til AI-agenter. ### 🌐 Flerspråklig støtte -#### Støttes via GitHub Action (Automatisert og alltid oppdatert) +#### Støttet via GitHub Action (Automatisert og alltid oppdatert) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](./README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) > **Foretrekker du å klone lokalt?** > -> Dette depotet inkluderer oversettelser til 50+ språk, noe som øker nedlastingsstørrelsen betydelig. For å klone uten oversettelser, bruk sparsjekontroll: +> Dette depotet inkluderer over 50 språkoversettelser som øker nedlastingsstørrelsen betydelig. For å klone uten oversettelser, bruk sparsommelig utsjekking: > > **Bash / macOS / Linux:** > ```bash @@ -29,92 +29,91 @@ Et kurs for å bygge AI-applikasjoner med LangChain4j og Azure OpenAI GPT-5.2, f > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Dette gir deg alt du trenger for å fullføre kurset med mye raskere nedlasting. +> Dette gir deg alt du trenger for å fullføre kurset med en mye raskere nedlasting. ## Innholdsfortegnelse -1. [Kom i gang](00-quick-start/README.md) - Kom i gang med LangChain4j -2. [Innledning](01-introduction/README.md) - Lær det grunnleggende om LangChain4j -3. [Prompt Engineering](02-prompt-engineering/README.md) - Mestre effektiv promptdesign -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Bygg intelligente kunnskapsbaserte systemer -5. [Verktøy](04-tools/README.md) - Integrer eksterne verktøy og enkle assistenter -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Arbeid med Model Context Protocol (MCP) og Agentiske moduler +1. [Introduksjon](01-introduction/README.md) - Lær det grunnleggende om LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Mestre effektiv promptdesign +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Bygg intelligente kunnskapsbaserte systemer +4. [Verktøy](04-tools/README.md) - Integrer eksterne verktøy og enkle assistenter +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Arbeid med Model Context Protocol (MCP) og Agentiske moduler -### Videogjennomganger +### Video-gjennomganger -Hvert modul har en tilhørende direktesending der vi går gjennom konseptene og koden trinn for trinn. +Hvert modul har en tilhørende live-økt der vi går gjennom konsepter og kode steg for steg. | Modul | Video | |--------|-------| -| 01 - Innledning | [Kom i gang med LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 01 - Introduksjon | [Kom i gang med LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - Prompt Engineering | [Prompt Engineering med LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG med LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Verktøy & 05 - MCP | [AI-agenter med verktøy og MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Læringssti +## Læringsvei -**Ny med LangChain4j?** Sjekk ut [Ordlisten](docs/GLOSSARY.md) for definisjoner av nøkkelbegreper og konsepter. +**Ny til LangChain4j?** Sjekk ut [ordlisten](docs/GLOSSARY.md) for definisjoner av nøkkelbegreper og konsepter. -> **Kom raskt i gang** +> **Rask start** 1. Fork dette depotet til din GitHub-konto -2. Klikk **Code** → fanen **Codespaces** → **...** → **Ny med alternativer...** -3. Bruk standardinnstillinger – dette vil velge utviklingscontaineren opprettet for dette kurset +2. Klikk på **Code** → fanen **Codespaces** → **...** → **Ny med alternativer...** +3. Bruk standardvalgene – dette vil velge utviklingscontaineren opprettet for dette kurset 4. Klikk **Opprett codespace** 5. Vent 5-10 minutter til miljøet er klart -6. Gå rett til [Kom i gang](./00-quick-start/README.md) for å starte! +6. Gå rett til [Introduksjon](./01-introduction/README.md) for å komme i gang! -Etter å ha fullført modulene, utforsk [Testveiledningen](docs/TESTING.md) for å se LangChain4j testkonsepter i praksis. +Etter fullførte moduler, utforsk [testingsveiledningen](docs/TESTING.md) for å se LangChain4j testing i praksis. -> **Merk:** Denne opplæringen bruker både GitHub-modeller og Azure OpenAI. Modulen [Kom i gang](00-quick-start/README.md) bruker GitHub-modeller (ingen Azure-abonnement kreves), mens modul 1-5 bruker Azure OpenAI. Kom i gang med en [GRATIS Azure-konto](https://aka.ms/azure-free-account) hvis du ikke har en. +> **Merk:** Denne opplæringen bruker Azure OpenAI. Kom i gang med en [GRATIS Azure-konto](https://aka.ms/azure-free-account) hvis du ikke har en. ## Læring med GitHub Copilot -For å raskt komme i gang med koding, åpne dette prosjektet i en GitHub Codespace eller din lokale IDE med den medfølgende devcontaineren. Devcontaineren som brukes i dette kurset kommer forhåndskonfigurert med GitHub Copilot for AI-parprogrammering. +For å komme raskt i gang med koding, åpne dette prosjektet i en GitHub Codespace eller din lokale IDE med den medfølgende devcontaineren. Devcontaineren som brukes i dette kurset kommer forhåndskonfigurert med GitHub Copilot for AI-parprogrammering. -Hvert kodeeksempel inkluderer foreslåtte spørsmål du kan stille GitHub Copilot for å utdype din forståelse. Se etter 💡/🤖 hint i: +Hvert kodeeksempel inkluderer foreslåtte spørsmål du kan stille GitHub Copilot for å utdype forståelsen din. Se etter 💡/🤖 oppmuntringene i: - **Java-filoverskrifter** - Spørsmål spesifikke for hvert eksempel - **Modul-READMEer** - Utforskningsspørsmål etter kodeeksempler -**Hvordan bruke:** Åpne en hvilken som helst kodefil og spør Copilot de foreslåtte spørsmålene. Den har full kontekst for kodebasen og kan forklare, utvide og foreslå alternativer. +**Slik bruker du:** Åpne en vilkårlig kodefil og spør Copilot de foreslåtte spørsmålene. Den har full kontekst av kodebasen og kan forklare, utvide og foreslå alternativer. -Vil du lære mer? Sjekk ut [Copilot for AI Paired Programming](https://aka.ms/GitHubCopilotAI). +Vil du lære mer? Se [Copilot for AI-parprogrammering](https://aka.ms/GitHubCopilotAI). -## Tilleggsressurser +## Ytterligere ressurser ### LangChain -[![LangChain4j for nybegynnere](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for nybegynnere](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for nybegynnere](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- ### Azure / Edge / MCP / Agenter -[![AZD for nybegynnere](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for nybegynnere](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for nybegynnere](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI-agenter for nybegynnere](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Generativ AI-serie -[![Generativ AI for nybegynnere](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generativ AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generativ AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generativ AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Kjerneopplæring -[![ML for nybegynnere](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for nybegynnere](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for nybegynnere](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +### Kjerne-læring +[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) @@ -122,7 +121,7 @@ Vil du lære mer? Sjekk ut [Copilot for AI Paired Programming](https://aka.ms/Gi --- -### Copilot-serie +### Copilot-serien [![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) @@ -130,11 +129,11 @@ Vil du lære mer? Sjekk ut [Copilot for AI Paired Programming](https://aka.ms/Gi ## Få hjelp -Hvis du står fast eller har spørsmål om å bygge AI-apper, bli med: +Hvis du sitter fast eller har spørsmål om å bygge AI-apper, bli med: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Hvis du har produktinnspill eller opplever feil under utvikling, besøk: +Hvis du har produktfeedback eller feil mens du bygger, besøk: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) @@ -146,5 +145,5 @@ MIT-lisens - Se [LICENSE](../../LICENSE) filen for detaljer. **Ansvarsfraskrivelse**: -Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vennligst vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det originale dokumentet på sitt opprinnelige språk skal betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi påtar oss ikke ansvar for misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. +Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket skal betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. \ No newline at end of file diff --git a/translations/no/docs/GLOSSARY.md b/translations/no/docs/GLOSSARY.md index 4652f7e9a..19e4b0144 100644 --- a/translations/no/docs/GLOSSARY.md +++ b/translations/no/docs/GLOSSARY.md @@ -2,53 +2,53 @@ ## Innholdsfortegnelse -- [Kjernebegreper](../../../docs) -- [LangChain4j Komponenter](../../../docs) -- [AI/ML Begreper](../../../docs) -- [Guardrails](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agenter og Verktøy](../../../docs) -- [Agentmodul](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure Tjenester](../../../docs) -- [Testing og Utvikling](../../../docs) - -Rask referanse for termer og konsepter brukt gjennom hele kurset. +- [Kjernebegreper](#kjernebegreper) +- [LangChain4j-komponenter](#langchain4j-komponenter) +- [AI/ML-begreper](#aiml-begreper) +- [Guardrails](#guardrails) +- [Prompt Engineering](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agenter og Verktøy](#agents-and-tools---module-04) +- [Agentmodul](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure-tjenester](#azure-services---module-01) +- [Testing og Utvikling](#testing-and-development---testing-guide) + +Raske referanser for begreper og konsepter brukt gjennom hele kurset. ## Kjernebegreper -**AI Agent** - System som bruker AI til å resonnere og handle autonomt. [Modul 04](../04-tools/README.md) +**AI-agent** - System som bruker AI for å resonnere og handle autonomt. [Modul 04](../04-tools/README.md) -**Kjede** - Sekvens av operasjoner hvor output mates inn i neste steg. +**Kjede** - Sekvens av operasjoner der output går videre til neste steg. -**Chunking** - Dele dokumenter opp i mindre biter. Typisk: 300-500 tokens med overlapp. [Modul 03](../03-rag/README.md) +**Chunking** - Dele dokumenter i mindre deler. Typisk: 300-500 tokens med overlapp. [Modul 03](../03-rag/README.md) -**Kontekstvindu** - Maksimalt antall tokens en modell kan prosessere. GPT-5.2: 400K tokens (opptil 272K input, 128K output). +**Kontekstvindu** - Maksimalt antall tokens en modell kan prosessere. GPT-5.2: 400K tokens (inntil 272K input, 128K output). -**Inbaking (Embeddings)** - Numeriske vektorer som representerer tekstens mening. [Modul 03](../03-rag/README.md) +**Inbeddinger** - Numeriske vektorer som representerer tekstens betydning. [Modul 03](../03-rag/README.md) **Funksjonskalling** - Modell genererer strukturerte forespørsler for å kalle eksterne funksjoner. [Modul 04](../04-tools/README.md) **Hallusinasjon** - Når modeller genererer feilaktig men plausibel informasjon. -**Prompt** - Tekstinput til en språkmodell. [Modul 02](../02-prompt-engineering/README.md) +**Prompt** - Tekstinput til et språkmodell. [Modul 02](../02-prompt-engineering/README.md) -**Semantisk Søking** - Søk basert på mening ved hjelp av inbaking, ikke nøkkelord. [Modul 03](../03-rag/README.md) +**Semantisk søk** - Søk basert på mening ved hjelp av inbeddinger, ikke nøkkelord. [Modul 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: ingen minne. Stateful: opprettholder samtalehistorikk. [Modul 01](../01-introduction/README.md) +**Tilstandsbasert vs Tilstandsløs** - Tilstandsløs: uten minne. Tilstandsbasert: opprettholder samtalehistorikk. [Modul 01](../01-introduction/README.md) -**Tokens** - Grunnenheter tekstmodeller prosesserer. Påvirker kostnader og begrensninger. [Modul 01](../01-introduction/README.md) +**Tokens** - Grunnenheter tekst som modeller prosesserer. Påvirker kostnader og grenser. [Modul 01](../01-introduction/README.md) -**Verktøykjedning** - Sekvensiell verktøyutførelse hvor output informerer neste kall. [Modul 04](../04-tools/README.md) +**Verktøykjedning** - Sekvensiell verktøyutførelse hvor output påvirker neste kall. [Modul 04](../04-tools/README.md) -## LangChain4j Komponenter +## LangChain4j-komponenter **AiServices** - Lager typesikre AI-tjenestegrensesnitt. -**OpenAiOfficialChatModel** - Forent klient for OpenAI og Azure OpenAI modeller. +**OpenAiOfficialChatModel** - Enhetlig klient for OpenAI og Azure OpenAI-modeller. -**OpenAiOfficialEmbeddingModel** - Lager inbakinger med OpenAI Official-klient (støtter både OpenAI og Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Lager inbeddinger ved bruk av OpenAI Official-klient (støtter både OpenAI og Azure OpenAI). **ChatModel** - Kjernegrensesnitt for språkmodeller. @@ -56,177 +56,175 @@ Rask referanse for termer og konsepter brukt gjennom hele kurset. **ContentRetriever** - Finner relevante dokumentbiter for RAG. -**DocumentSplitter** - Deler dokumenter opp i biter. +**DocumentSplitter** - Deler dokumenter i biter. **EmbeddingModel** - Konverterer tekst til numeriske vektorer. -**EmbeddingStore** - Lagrer og henter inbakinger. +**EmbeddingStore** - Lagrer og henter inbeddinger. -**MessageWindowChatMemory** - Opprettholder glidende vindu av nylige meldinger. +**MessageWindowChatMemory** - Opprettholder et skyvbart vindu med nylige meldinger. -**PromptTemplate** - Lager gjenbrukbare prompts med `{{variable}}`-plasser. +**PromptTemplate** - Lager gjenbrukbare prompts med `{{variabel}}`-plassholdere. **TextSegment** - Tekstbit med metadata. Brukes i RAG. **ToolExecutionRequest** - Representerer verktøyutførelsesforespørsel. -**UserMessage / AiMessage / SystemMessage** - Samtalemeldingstyper. +**UserMessage / AiMessage / SystemMessage** - Samtale meldings-typer. -## AI/ML Begreper +## AI/ML-begreper -**Few-Shot Learning** - Å gi eksempler i prompts. [Modul 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Gir eksempler i prompts. [Modul 02](../02-prompt-engineering/README.md) **Large Language Model (LLM)** - AI-modeller trent på store mengder tekstdata. -**Resonnementinnsats** - GPT-5.2 parameter som styrer hvor dypt modellen tenker. [Modul 02](../02-prompt-engineering/README.md) +**Resonneringsinnsats** - GPT-5.2-parameter som kontrollerer tenkedybde. [Modul 02](../02-prompt-engineering/README.md) -**Temperatur** - Styrer output-randomness. Lav=deteriministisk, høy=kreativ. +**Temperatur** - Styrer utdataens tilfeldighet. Lav=deterministisk, høy=kreativ. -**Vektor Database** - Spesialisert database for inbakinger. [Modul 03](../03-rag/README.md) +**Vektor Database** - Spesialisert database for inbeddinger. [Modul 03](../03-rag/README.md) -**Zero-Shot Learning** - Utføre oppgaver uten eksempler. [Modul 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Utfører oppgaver uten eksempler. [Modul 02](../02-prompt-engineering/README.md) -## Guardrails - [Modul 00](../00-quick-start/README.md) +## Guardrails -**Defense in Depth** - Flersjikts sikkerhetstilnærming som kombinerer applikasjonsnivå guardrails med leverandørsikkerhetsfiltre. +**Forsvar i dypet** - Flerlags sikkerhetstilnærming som kombinerer applikasjonsnivå guardrails med leverandørsikkerhetsfiltre. -**Hard Block** - Leverandør kaster HTTP 400-feil ved alvorlige innholdsbrudd. +**Hard blokkering** - Leverandør gir HTTP 400-feil for alvorlige innholdsbrudd. -**InputGuardrail** - LangChain4j-grensesnitt for validering av brukerinput før den når LLM. Spar kostnad og ventetid ved å blokkere skadelige prompts tidlig. +**InputGuardrail** - LangChain4j-grensesnitt for validering av brukerinput før det når LLM. Spar kostnader og ventetid ved å blokkere skadelige prompts tidlig. -**InputGuardrailResult** - Returtype for guardrail-validering: `success()` eller `fatal("reason")`. +**InputGuardrailResult** - Returtype for guardrail-validering: `success()` eller `fatal("årsak")`. -**OutputGuardrail** - Grensesnitt for validering av AI-svar før de returneres til brukere. +**OutputGuardrail** - Grensesnitt for å validere AI-responser før de returneres til brukere. -**Leverandørsikkerhetsfiltre** - Innebygde innholdsfiltre fra AI-leverandører (f.eks. GitHub Models) som fanger brudd på API-nivå. +**Leverandørsikkerhetsfiltre** - Innebygde innholdsfiltre fra AI-leverandører (f.eks. Azure OpenAI) som fanger brudd på API-nivå. -**Soft Refusal** - Modell høflig avslår å svare uten å kaste feil. +**Myk avvisning** - Modell høflig nekter å svare uten å kaste feil. ## Prompt Engineering - [Modul 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Stegvis resonnement for bedre nøyaktighet. +**Chain-of-Thought** - Trinnvis resonnement for bedre nøyaktighet. -**Constraining Output** - Håndheve spesifikt format eller struktur. +**Begrenset utdata** - Påtvinge spesifikt format eller struktur. -**Høy Iver** - GPT-5.2 mønster for grundig resonnement. +**Høy ivrighet** - GPT-5.2-mønster for grundig resonnering. -**Lav Iver** - GPT-5.2 mønster for raske svar. +**Lav ivrighet** - GPT-5.2-mønster for raske svar. **Multi-Turn Conversation** - Opprettholde kontekst over flere utvekslinger. -**Rollebasert Prompting** - Sette modellpersonlighet via systemmeldinger. +**Rollebasert prompting** - Sette modellpersonlighet via systemmeldinger. -**Selvrefleksjon** - Modell evaluerer og forbedrer egen output. +**Selvrefleksjon** - Modell evaluerer og forbedrer sin utdata. -**Strukturert Analyse** - Fast evalueringsrammeverk. +**Strukturert analyse** - Fast evalueringsrammeverk. -**Oppgaveutførelsesmønster** - Planlegge → Utføre → Oppsummere. +**Oppgaveutførelsesmønster** - Planlegg → Utfør → Oppsummer. ## RAG (Retrieval-Augmented Generation) - [Modul 03](../03-rag/README.md) -**Dokumentprosesspipeline** - Last → del opp → lag inbaking → lagre. +**Dokumentbehandlingspipeline** - Last inn → chunk → embed → lagre. -**In-Memory Embedding Store** - Ikke-persistent lagring for testing. +**I-Minne Embedding Store** - Ikke-persistente lagring for testing. -**RAG** - Kombinerer innhenting med generering for å forankre svar. +**RAG** - Kombinerer henting med generering for å forankre svar. -**Likhetspoeng** - Mål (0-1) på semantisk likhet. +**Lignende poengsum** - Måling (0-1) av semantisk likhet. -**Kildehenvisning** - Metadata om hentet innhold. +**Kilderreferanse** - Metadata om hentet innhold. ## Agenter og Verktøy - [Modul 04](../04-tools/README.md) -**@Tool Annotasjon** - Marker Java-metoder som AI-kallbare verktøy. +**@Tool-annotasjon** - Marker Java-metoder som AI-kallbare verktøy. -**ReAct Mønster** - Resonner → Handle → Observer → Gjenta. +**ReAct-mønster** - Resonner → Aksjoner → Observer → Gjenta. -**Sesjonshåndtering** - Separate kontekster for ulike brukere. +**Sesjonsstyring** - Separate kontekster for forskjellige brukere. **Verktøy** - Funksjon en AI-agent kan kalle. -**Verktøybeskrivelse** - Dokumentasjon av verktøyets formål og parametre. +**Verktøybeskrivelse** - Dokumentasjon av verktøyets formål og parametere. ## Agentmodul - [Modul 05](../05-mcp/README.md) -**@Agent Annotasjon** - Marker grensesnitt som AI-agenter med deklarativ adferdsdefinisjon. +**@Agent-annotasjon** - Marker grensesnitt som AI-agenter med deklarativ atferdsdefinisjon. -**Agent Listener** - Hook for overvåking av agentutførelse via `beforeAgentInvocation()` og `afterAgentInvocation()`. +**Agentlytter** - Krok for overvåkning av agentutførelse via `beforeAgentInvocation()` og `afterAgentInvocation()`. -**Agentic Scope** - Delt minne der agenter lagrer output ved bruk av `outputKey` for at downstream agenter skal konsumere. +**Agentisk omfang** - Delt minne hvor agenter lagrer output med `outputKey` for at downstream-agenter skal bruke. **AgenticServices** - Fabrikk for å lage agenter ved bruk av `agentBuilder()` og `supervisorBuilder()`. -**Betinget Arbeidsflyt** - Rute basert på betingelser til ulike spesialistagenter. +**Betinget arbeidsflyt** - Ruteføring basert på betingelser til ulike spesialistagenter. -**Human-in-the-Loop** - Arbeidsflytmønster som legger til menneskelige kontrollpunkter for godkjenning eller innholdsgranskning. +**Mennesket-i-loopen** - Arbeidsflytmønster som legger til menneskelige sjekkpunkter for godkjenning eller innholdsgranskning. **langchain4j-agentic** - Maven-avhengighet for deklarativ agentbygging (eksperimentell). -**Løkkearbeidsflyt** - Iterer agentutførelse til en betingelse er oppfylt (f.eks. kvalitets-score ≥ 0.8). +**Loop-arbeidsflyt** - Iterer agentutførelse til betingelse er oppfylt (f.eks. kvalitetspoeng ≥ 0.8). -**outputKey** - Agentannotasjonsparameter som spesifiserer hvor resultater lagres i Agentic Scope. +**outputKey** - Agent-annotasjonsparameter som spesifiserer hvor resultater lagres i Agentisk omfang. -**Parallell Arbeidsflyt** - Kjør flere agenter samtidig for uavhengige oppgaver. +**Parallell arbeidsflyt** - Kjøre flere agenter samtidig for uavhengige oppgaver. -**Responsstrategi** - Hvordan supervisor formulerer endelig svar: SISTE, OPPSUMMERING, eller SCORET. +**Responsstrategi** - Hvordan veilederen formulerer endelig svar: SISTE, SAMMENDRAG eller POENGSATT. -**Sekvensiell Arbeidsflyt** - Utfør agenter i rekkefølge hvor output flyter til neste steg. +**Sekvensiell arbeidsflyt** - Utfør agenter i rekkefølge der output går til neste steg. -**Supervisor Agent Mønster** - Avansert agentisk mønster hvor en supervisor LLM dynamisk bestemmer hvilke sub-agenter som skal kalles. +**Veilederagentmønster** - Avansert agentisk mønster der en veileder-LLM dynamisk bestemmer hvilke sub-agenter som skal kalles. ## Model Context Protocol (MCP) - [Modul 05](../05-mcp/README.md) **langchain4j-mcp** - Maven-avhengighet for MCP-integrasjon i LangChain4j. -**MCP** - Model Context Protocol: standard for å koble AI-applikasjoner til eksterne verktøy. Bygg én gang, bruk overalt. +**MCP** - Model Context Protocol: standard for å koble AI-apper til eksterne verktøy. Bygg én gang, bruk overalt. -**MCP Klient** - Applikasjon som kobler til MCP-servere for å oppdage og bruke verktøy. +**MCP-klient** - Applikasjon som kobler til MCP-servere for å oppdage og bruke verktøy. -**MCP Server** - Tjeneste som eksponerer verktøy via MCP med klare beskrivelser og parameterskjemaer. +**MCP-server** - Tjeneste som eksponerer verktøy via MCP med klare beskrivelser og parameterskjemaer. **McpToolProvider** - LangChain4j-komponent som pakker MCP-verktøy for bruk i AI-tjenester og agenter. **McpTransport** - Grensesnitt for MCP-kommunikasjon. Implementasjoner inkluderer Stdio og HTTP. -**Stdio Transport** - Lokal prosess-transport via stdin/stdout. Nyttig for filsystemtilgang eller kommandolinjeverktøy. +**Stdio Transport** - Lokalt prosess-transport via stdin/stdout. Nyttig for filsystemtilgang eller kommandolinjeverktøy. -**StdioMcpTransport** - LangChain4j-implementasjon som starter MCP-server som underprosess. +**StdioMcpTransport** - LangChain4j-implementering som starter MCP-server som underprosess. -**Verktøyoppdagelse** - Klient spørrer server om tilgjengelige verktøy med beskrivelser og skjemaer. +**Verktøyoppdagelse** - Klient spør server om tilgjengelige verktøy med beskrivelser og skjemaer. -## Azure Tjenester - [Modul 01](../01-introduction/README.md) +## Azure-tjenester - [Modul 01](../01-introduction/README.md) -**Azure AI Search** - Skytjeneste for søk med vektorfunktioner. [Modul 03](../03-rag/README.md) +**Azure AI Search** - Skybasert søk med vektorkapasiteter. [Modul 03](../03-rag/README.md) **Azure Developer CLI (azd)** - Distribuerer Azure-ressurser. **Azure OpenAI** - Microsofts bedrifts-AI-tjeneste. -**Bicep** - Azure infrastruktur-som-kode språk. [Infrastrukturguide](../01-introduction/infra/README.md) +**Bicep** - Azures infrastruktur-som-kode-språk. [Infrastrukturveiledning](../01-introduction/infra/README.md) -**Deploy-navn** - Navn for modellutplassering i Azure. +**Distribusjonsnavn** - Navn for modellutplassering i Azure. -**GPT-5.2** - Nyeste OpenAI-modell med resonnementskontroll. [Modul 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Siste OpenAI-modell med resonneringskontroll. [Modul 02](../02-prompt-engineering/README.md) -## Testing og Utvikling - [Testingguide](TESTING.md) +## Testing og Utvikling - [Testing Guide](TESTING.md) -**Dev Container** - Containerisert utviklingsmiljø. [Konfigurasjon](../../../.devcontainer/devcontainer.json) +**Dev Container** - Kontainerisert utviklingsmiljø. [Konfigurasjon](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Gratis AI-modell lekeplass. [Modul 00](../00-quick-start/README.md) - -**In-Memory Testing** - Test med minnebasert lagring. +**Testing i minnet** - Testing med minnelagring. **Integrasjonstesting** - Testing med ekte infrastruktur. -**Maven** - Java byggverktøy. +**Maven** - Java-byggverktøy. **Mockito** - Java mocking-rammeverk. -**Spring Boot** - Java applikasjonsrammeverk. [Modul 01](../01-introduction/README.md) +**Spring Boot** - Java-applikasjonsrammeverk. [Modul 01](../01-introduction/README.md) --- **Ansvarsfraskrivelse**: -Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vennligst vær oppmerksom på at automatiserte oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket skal anses som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. +Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket skal betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. \ No newline at end of file diff --git a/translations/no/docs/TESTING.md b/translations/no/docs/TESTING.md index 8a07442f5..3f9df575d 100644 --- a/translations/no/docs/TESTING.md +++ b/translations/no/docs/TESTING.md @@ -2,17 +2,17 @@ ## Innholdsfortegnelse -- [Rask start](../../../docs) -- [Hva testene dekker](../../../docs) -- [Kjøre testene](../../../docs) -- [Kjøre tester i VS Code](../../../docs) -- [Testingmønstre](../../../docs) -- [Testingsfilosofi](../../../docs) -- [Neste steg](../../../docs) +- [Kjappstart](#kjappstart) +- [Hva testene dekker](#hva-testene-dekker) +- [Kjøre testene](#kjøre-testene) +- [Kjøre tester i VS Code](#kjøre-tester-i-vs-code) +- [Testmønstre](#testmønstre) +- [Testfilosofi](#testfilosofi) +- [Neste steg](#neste-steg) Denne guiden går gjennom testene som demonstrerer hvordan man tester AI-applikasjoner uten å kreve API-nøkler eller eksterne tjenester. -## Rask start +## Kjappstart Kjør alle tester med en enkelt kommando: @@ -26,28 +26,27 @@ mvn test mvn --% test ``` -Når alle testene er bestått, bør du se output som skjermbildet under — tester kjører uten feil. +Når alle tester passerer, bør du se output som skjermbildet nedenfor — alle tester kjører uten feil. Successful Test Results -*Vellykket testruting som viser at alle tester passerer uten feil* +*Vel­lykket test­kjøring som viser at alle tester passerer uten feil* ## Hva testene dekker -Dette kurset fokuserer på **enhetstester** som kjører lokalt. Hver test demonstrerer et spesifikt LangChain4j-konsept isolert. Testpyramiden under viser hvor enhetstester passer inn — de utgjør det raske og pålitelige fundamentet som resten av teststrategien bygger på. +Dette kurset fokuserer på **enhetstester** som kjøres lokalt. Hver test demonstrerer et spesifikt LangChain4j-konsept isolert. Testpyramiden nedenfor viser hvor enhetstester passer inn — de utgjør det raske, pålitelige grunnlaget som resten av teststrategien bygger på. Testing Pyramid -*Testpyramide som viser balansen mellom enhetstester (raskt, isolert), integrasjonstester (ekte komponenter) og ende-til-ende-tester. Dette kurset dekker enhetstesting.* +*Testpyramide som viser balansen mellom enhetstester (raske, isolerte), integrasjonstester (ekte komponenter) og ende-til-ende tester. Denne opplæringen dekker enhetstesting.* -| Modul | Tester | Fokus | Nøkkelfiler | -|--------|-------|-------|------------| -| **00 - Rask start** | 6 | Promptmaler og variabelsubstitusjon | `SimpleQuickStartTest.java` | -| **01 - Introduksjon** | 8 | Samtalehukommelse og tilstandsstyrt chat | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | GPT-5.2-mønstre, ivrighetsnivåer, strukturert output | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Dokumentinngestion, innebygging, likhetssøk | `DocumentServiceTest.java` | -| **04 - Verktøy** | 12 | Funksjonskalling og verktøykjeder | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol med Stdio-transport | `SimpleMcpTest.java` | +| Modul | Tester | Fokus | Viktige filer | +|--------|-------|-------|-----------| +| **01 - Introduksjon** | 8 | Samtale-minne og statefull chat | `SimpleConversationTest.java` | +| **02 - Prompt engineering** | 12 | GPT-5.2-mønstre, entusiastnivåer, strukturert output | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Dokumentinnhenting, embeddings, likhetssøk | `DocumentServiceTest.java` | +| **04 - Verktøy** | 12 | Funksjonskall og verktøykjeder | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol med Stdio transport | `SimpleMcpTest.java` | ## Kjøre testene @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Kjør tester for en bestemt modul:** +**Kjør tester for en spesifikk modul:** **Bash:** ```bash @@ -95,12 +94,12 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#børBeholdeSamtalehistorikk +mvn test -Dtest=SimpleConversationTest#børOpprettholdeSamtaleHistorikk ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#børOpprettholdeSamtalehistorikk +mvn --% test -Dtest=SimpleConversationTest#skalOpprettholdeSamtalehistorikk ``` ## Kjøre tester i VS Code @@ -109,27 +108,27 @@ Hvis du bruker Visual Studio Code, gir Test Explorer et grafisk grensesnitt for VS Code Test Explorer -*VS Code Test Explorer som viser testtreet med alle Java testklasser og individuelle testmetoder* +*VS Code Test Explorer som viser testtre med alle Java testklasser og individuelle testmetoder* -**For å kjøre tester i VS Code:** +**Slik kjører du tester i VS Code:** -1. Åpne Test Explorer ved å klikke på kolbeikonet i aktivitetslinjen +1. Åpne Test Explorer ved å klikke på kolbe-ikonet i aktivitetslinjen 2. Utvid testtreet for å se alle moduler og testklasser -3. Klikk på avspillingsknappen ved siden av en test for å kjøre den individuelt -4. Klikk "Run All Tests" for å kjøre hele settet -5. Høyreklikk på en test og velg "Debug Test" for å sette brytepunkter og trinnvise kjøringer +3. Klikk på avspillingsknappen ved en test for å kjøre den individuelt +4. Klikk "Run All Tests" for å kjøre hele testpakken +5. Høyreklikk en test og velg "Debug Test" for å sette breakpoints og trinnvise kjøringer -Test Explorer viser grønne avkrysningsmerker for beståtte tester og gir detaljerte feilmeldinger ved testfeil. +Test Explorer viser grønne haker for beståtte tester og detaljerte feilmeldinger hvis tester feiler. -## Testingmønstre +## Testmønstre ### Mønster 1: Testing av promptmaler -Det enkleste mønsteret tester promptmaler uten å kalle noen AI-modell. Du verifiserer at variabelsubstitusjon fungerer korrekt og at prompts formateres som forventet. +Det enkleste mønsteret tester promptmaler uten å kalle noe AI-modell. Du verifiserer at variabelsubstitusjon fungerer riktig og at promptene formateres som forventet. Prompt Template Testing -*Testing av promptmaler som viser flyten: mal med plassholdere → verdier anvendt → formatert output verifisert* +*Testing av promptmaler som viser flyten for variabelsubstitusjon: mal med plassholdere → verdier anvendt → formatert output verifisert* ```java @Test @@ -148,23 +147,11 @@ void testPromptTemplateFormatting() { } ``` -Denne testen ligger i `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Kjør den:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testPromptMalFormatering -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptMalingsformatering -``` +Dette mønsteret bekrefter at variabelsubstitusjon fungerer som den skal, og at promptene formateres korrekt — ingen API-nøkkel eller modellkall kreves. ### Mønster 2: Mocking av språkmodeller -Når man tester samtalelogikk, bruk Mockito for å lage falske modeller som returnerer forhåndsbestemte svar. Dette gjør testene raske, gratis og deterministiske. +Når du tester konversasjonslogikk, bruk Mockito for å lage falske modeller som returnerer forhåndsbestemte svar. Dette gjør testene raske, gratis og deterministiske. Mock vs Real API Comparison @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Dette mønsteret finnes i `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mocken sikrer konsekvent oppførsel slik at du kan verifisere at hukommelsesadministrasjon fungerer riktig. +Dette mønsteret finnes i `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mocken sikrer konsistent oppførsel slik at du kan verifisere at håndtering av minnet fungerer korrekt. -### Mønster 3: Testing av samtaleisolasjon +### Mønster 3: Testing av isolasjon i samtaler -Samtalehukommelsen må holde flere brukere adskilt. Denne testen verifiserer at samtaler ikke blander sammen kontekster. +Samtaleminne må holde flere brukere adskilt. Denne testen verifiserer at samtaler ikke blander kontekster. Conversation Isolation -*Testing av samtaleisolasjon som viser separate hukommelseslagre for ulike brukere for å hindre kontekstblanding* +*Testing av samtaleisolasjon som viser separate minnelagre for ulike brukere for å hindre kontekstblanding* ```java @Test @@ -250,7 +237,7 @@ void shouldIsolateConversationsByid() { } ``` -Hver samtale opprettholder sin egen uavhengige historikk. I produksjonssystemer er denne isolasjonen kritisk for multi-brukerapplikasjoner. +Hver samtale opprettholder sin egen uavhengige historie. I produksjonssystemer er denne isolasjonen kritisk for flerbrukerapplikasjoner. ### Mønster 4: Testing av verktøy uavhengig @@ -258,7 +245,7 @@ Verktøy er funksjoner AI kan kalle. Test dem direkte for å sikre at de fungere Tools Testing -*Testing av verktøy uavhengig ved å vise kjøring av mock-verktøy uten AI-kall for å verifisere forretningslogikk* +*Testing av verktøy uavhengig med mock-verktøyutførelse uten AI-kall for å verifisere forretningslogikk* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Disse testene fra `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validerer verktøylogikk uten AI-involvering. Kjedereferanseeksempelet viser hvordan output fra ett verktøy mates inn i input til et annet. +Disse testene fra `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validerer verktøylogikk uten AI-involvering. Kjedeneksempelet viser hvordan output fra ett verktøy mates inn som input til et annet. -### Mønster 5: I-minnet RAG-testing +### Mønster 5: Testing av RAG i minnet -RAG-systemer krever tradisjonelt vektordatabaser og embeddingtjenester. I-minnet-mønsteret lar deg teste hele pipeline uten eksterne avhengigheter. +RAG-systemer krever tradisjonelt vektordatabaser og embeddingtjenester. Minnebasert mønster lar deg teste hele kjeden uten eksterne avhengigheter. In-Memory RAG Testing -*I-minnet RAG testflyt som viser dokumentparsing, embeddinglagring og likhetssøk uten krav til database* +*Minnebasert RAG-testarbeidsflyt som viser dokumentparsing, embeddinglagring og likhetssøk uten behov for database* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Denne testen fra `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` oppretter et dokument i minnet og verifiserer chunking og metadatahåndtering. +Denne testen fra `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` lager et dokument i minnet og verifiserer oppdeling og metadatahåndtering. ### Mønster 6: MCP-integrasjonstesting -MCP-modulen tester Model Context Protocol-integrasjon ved å bruke stdio-transport. Disse testene verifiserer at applikasjonen din kan starte og kommunisere med MCP-servere som underprosesser. +MCP-modulen tester Model Context Protocol-integrasjonen ved bruk av stdio transport. Disse testene verifiserer at applikasjonen din kan starte og kommunisere med MCP-servere som underprosesser. -Testene i `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validerer MCP-klientatferd. +Testene i `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validerer MCP-klientoppførsel. **Kjør dem:** @@ -326,26 +313,25 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## Testingsfilosofi +## Testfilosofi -Test koden din, ikke AI-en. Testene dine skal validere koden du skriver ved å sjekke hvordan prompts konstrueres, hvordan hukommelsen administreres, og hvordan verktøy utføres. AI-svar varierer og bør ikke være del av testassertioner. Spør deg om promptmalen riktig erstatter variabler, ikke om AI gir det riktige svaret. +Test koden din, ikke AI-en. Testene dine bør validere koden du skriver ved å sjekke hvordan promptene konstrueres, hvordan minnet håndteres, og hvordan verktøy utføres. AI-responser varierer og bør ikke inngå i testpåstander. Spør deg selv om promptmalen din riktig erstatter variabler, ikke om AI gir riktig svar. -Bruk mocks for språkmodeller. De er eksterne avhengigheter som er trege, kostbare og ikke-deterministiske. Mocking gjør tester raske med millisekunder i stedet for sekunder, gratis uten API-kostnader, og deterministiske med samme resultat hver gang. +Bruk mocks for språkmodeller. De er eksterne avhengigheter som er trege, kostbare og ikke-deterministiske. Mocking gjør testene raske med millisekunder istedenfor sekunder, gratis uten API-kostnader, og deterministiske med samme resultat hver gang. -Hold tester uavhengige. Hver test bør sette opp sine egne data, ikke stole på andre tester, og rydde opp etter seg. Tester skal passere uavhengig av kjørerekkefølge. +Hold testene uavhengige. Hver test bør sette opp sine egne data, ikke stole på andre tester, og rydde opp etter seg. Tester skal passere uansett rekkefølge. -Test kanttilfeller utover den glade stien. Prøv tomme input, veldig store input, spesialtegn, ugyldige parametere og grenseverdier. Disse avslører ofte feil som vanlig bruk ikke eksponerer. +Test kanttilfeller i tillegg til idealveien. Prøv tomme input, svært store input, spesialtegn, ugyldige parametere, og grensetilfeller. Disse avdekker ofte feil som normalt bruk ikke eksponerer. -Bruk beskrivende navn. Sammenlign `shouldMaintainConversationHistoryAcrossMultipleMessages()` med `test1()`. Det førstnevnte forteller deg eksakt hva som testes, noe som gjør feilsøking mye enklere. +Bruk beskrivende navn. Sammenlign `shouldMaintainConversationHistoryAcrossMultipleMessages()` med `test1()`. Det første forteller deg nøyaktig hva som testes, noe som gjør feilsøking langt enklere. ## Neste steg -Nå som du forstår testingmønstrene, dykk dypere inn i hver modul: +Nå som du forstår testmønstrene, dykk dypere inn i hver modul: -- **[00 - Rask start](../00-quick-start/README.md)** - Start med grunnleggende promptmaler -- **[01 - Introduksjon](../01-introduction/README.md)** - Lær samtalehukommelsesadministrasjon -- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Mestre GPT-5.2 promptmønstre -- **[03 - RAG](../03-rag/README.md)** - Bygg systemer for generering med oppslag +- **[01 - Introduksjon](../01-introduction/README.md)** - Lær samtaleminnehåndtering +- **[02 - Prompt engineering](../02-prompt-engineering/README.md)** - Mestre GPT-5.2-promptmønstre +- **[03 - RAG](../03-rag/README.md)** - Bygg retrieval-augmented generasjonssystemer - **[04 - Verktøy](../04-tools/README.md)** - Implementer funksjonskall og verktøykjeder - **[05 - MCP](../05-mcp/README.md)** - Integrer Model Context Protocol @@ -353,11 +339,11 @@ Hver moduls README gir detaljerte forklaringer av konseptene som testes her. --- -**Navigasjon:** [← Tilbake til hovedsiden](../README.md) +**Navigasjon:** [← Tilbake til hovedside](../README.md) --- **Ansvarsfraskrivelse**: -Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vennligst vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket bør betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. +Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten [Co-op Translator](https://github.com/Azure/co-op-translator). Selv om vi streber etter nøyaktighet, vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket skal betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen. \ No newline at end of file diff --git a/translations/pa/.co-op-translator.json b/translations/pa/.co-op-translator.json index 17fc0923c..fd7ef4718 100644 --- a/translations/pa/.co-op-translator.json +++ b/translations/pa/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "pa" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T18:47:20+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T11:49:59+00:00", "source_file": "01-introduction/README.md", "language_code": "pa" }, @@ -18,20 +18,20 @@ "language_code": "pa" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T18:51:40+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T11:43:10+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "pa" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T18:54:31+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T11:48:51+00:00", "source_file": "03-rag/README.md", "language_code": "pa" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:42:30+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T11:46:52+00:00", "source_file": "04-tools/README.md", "language_code": "pa" }, @@ -54,8 +54,8 @@ "language_code": "pa" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:51:08+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T11:41:11+00:00", "source_file": "README.md", "language_code": "pa" }, @@ -72,14 +72,14 @@ "language_code": "pa" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T19:00:24+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T11:43:59+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "pa" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T19:01:10+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T11:44:58+00:00", "source_file": "docs/TESTING.md", "language_code": "pa" } diff --git a/translations/pa/00-quick-start/README.md b/translations/pa/00-quick-start/README.md deleted file mode 100644 index b6034bdf3..000000000 --- a/translations/pa/00-quick-start/README.md +++ /dev/null @@ -1,388 +0,0 @@ -# Module 00: Quick Start - -## Table of Contents - -- [Introduction](../../../00-quick-start) -- [What is LangChain4j?](../../../00-quick-start) -- [LangChain4j Dependencies](../../../00-quick-start) -- [Prerequisites](../../../00-quick-start) -- [Setup](../../../00-quick-start) - - [1. Get Your GitHub Token](../../../00-quick-start) - - [2. Set Your Token](../../../00-quick-start) -- [Run the Examples](../../../00-quick-start) - - [1. Basic Chat](../../../00-quick-start) - - [2. Prompt Patterns](../../../00-quick-start) - - [3. Function Calling](../../../00-quick-start) - - [4. Document Q&A (Easy RAG)](../../../00-quick-start) - - [5. Responsible AI](../../../00-quick-start) -- [What Each Example Shows](../../../00-quick-start) -- [Next Steps](../../../00-quick-start) -- [Troubleshooting](../../../00-quick-start) - -## Introduction - -ਇਹ quickstart ਤੁਹਾਨੂੰ LangChain4j ਨਾਲ ਜਲਦੀ ਤੋਂ ਜਲਦੀ ਚਾਲੂ ਕਰਨ ਲਈ ਬਣਾਇਆ ਗਿਆ ਹੈ। ਇਹ LangChain4j ਅਤੇ GitHub ਮਾਡਲਾਂ ਨਾਲ AI ਐਪਲੀਕੇਸ਼ਨਾਂ ਬਣਾਉਣ ਦੀ ਬੁਨਿਆਦੀ ਜਾਣਕਾਰੀ ਨੂੰ ਕਵਰ ਕਰਦਾ ਹੈ। ਅਗਲੇ ਮੋਡੀਊਲਾਂ ਵਿੱਚ ਤੁਸੀਂ Azure OpenAI ਅਤੇ GPT-5.2 ਵਿੱਚ ਘੁੱਸੋਗੇ ਅਤੇ ਹਰ ਇਕ ਧਾਰਨਾ ਨੂੰ ਹੋਰ ਗਹਿਰਾਈ ਨਾਲ ਸਮਝੋਗੇ। - -## What is LangChain4j? - -LangChain4j ਇੱਕ ਜਾਵਾ ਲਾਇਬ੍ਰੇਰੀ ਹੈ ਜੋ AI-ਪાવਰਡ ਐਪਲੀਕੇਸ਼ਨਾਂ ਬਣਾਉਣਾ ਆਸਾਨ ਬਣਾਦੀ ਹੈ। HTTP ਕਲਾਇਟਾਂ ਅਤੇ JSON ਪਾਰਸਿੰਗ ਨਾਲ ਜੂਝਣ ਦੀ ਬਜਾਏ, ਤੁਸੀਂ ਸਾਫ ਪਵਿੱਤਰ ਜਾਵਾ APIs ਨਾਲ ਕੰਮ ਕਰਦੇ ਹੋ। - -LangChain ਵਿੱਚ "ਚੇਨ" ਮਤਲਬ ਹੈ ਕਈ ਕੰਪੋਨੈਂਟਾਂ ਨੂੰ ਜੋੜਨਾ - ਤੁਸੀਂ ਇੱਕ ਪ੍ਰੌਂਪਟ ਨੂੰ ਮਾਡਲ ਨਾਲ, ਮਾਡਲ ਤੋਂ ਪਾਰਸਰ ਨਾਲ ਜੋੜ ਸਕਦੇ ਹੋ, ਜਾਂ ਕਈ AI ਕਾਲਾਂ ਨੂੰ ਇਕੱਠੇ ਲੈ ਕੇ ਜਿੱਥੇ ਇੱਕ ਔਟਪੁੱਟ ਦੂਜੇ ਇਨਪੁੱਟ ਲਈ ਹੈ। ਇਹ quickstart ਮੂਲ ਤੱਥਾਂ 'ਤੇ ਕੇਂਦਰਿਤ ਹੈ ਪਹਿਲਾਂ ਕਿ ਹੋਰ ਜਟਿਲ ਚੇਨਾਂ ਨੂੰ ਚਰਚਾ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ। - -LangChain4j Chaining Concept - -*LangChain4j ਵਿੱਚ ਕੰਪੋਨੈਂਟਾਂ ਨੂੰ ਚੇਨ ਕਰਨਾ - ਸ਼ਕਤੀਸ਼ালী AI ਵਣਜਿਹਾਂ ਬਣਾਉਣ ਲਈ ਬਿਲਡਿੰਗ ਬਲਾਕਾਂ ਨੂੰ ਜੋੜਦੇ ਹੋਏ* - -ਅਸੀਂ ਤਿੰਨ ਮੁੱਖ ਕੰਪੋਨੈਂਟਾਂ ਨੂੰ ਵਰਤਾਂਗੇ: - -**ChatModel** - AI ਮਾਡਲ ਇੰਟਰੈਕਸ਼ਨਾਂ ਲਈ ਇੰਟਰਫੇਸ। `model.chat("prompt")` ਨੂੰ ਕਾਲ ਕਰੋ ਅਤੇ ਇਕ ਜਵਾਬਦਾਰ ਸਟਰਿੰਗ ਪ੍ਰਾਪਤ ਕਰੋ। ਅਸੀਂ `OpenAiOfficialChatModel` ਵਰਤਦੇ ਹਾਂ ਜੋ GitHub ਮਾਡਲਾਂ ਵਰਗੇ OpenAI-ਅਨੁਕੂਲ ਐਂਡਪੁਆਇੰਟਸ ਨਾਲ ਕੰਮ ਕਰਦਾ ਹੈ। - -**AiServices** - ਟਾਈਪ-ਸੇਫ AI ਸੇਵਾ ਇੰਟਰਫੇਸ ਬਣਾਉਂਦਾ ਹੈ। ਮੈਥਡ ਡਿਫਾਈਨ ਕਰੋ, ਉਨ੍ਹਾਂ ਨੂੰ `@Tool` ਨਾਲ ਅਨੋਟੇਟ ਕਰੋ, ਅਤੇ LangChain4j ਆਟੋਮੈਟਿਕ ਤੌਰ 'ਤੇ ਸਹਿਯੋਗ ਕਰਦਾ ਹੈ। ਜਦੋਂ ਲੋੜ ਪਵੇ ਤਾਂ AI ਤੁਹਾਡੇ ਜਾਵਾ ਮੈਥਡਾਂ ਨੂੰ ਕਾਲ ਕਰਦਾ ਹੈ। - -**MessageWindowChatMemory** - ਗੱਲਬਾਤ ਦਾ ਇਤਿਹਾਸ ਸੰਭਾਲਦਾ ਹੈ। ਇਸ ਦੇ ਬਿਨਾ, ਹਰ ਰਿਕਵੇਸਟ ਸੁਤੰਤਰ ਹੁੰਦੀ ਹੈ। ਇਸ ਨਾਲ, AI ਪਿਛਲੇ ਸੁਨੇਹਿਆਂ ਨੂੰ ਯਾਦ ਕਰਦਾ ਹੈ ਅਤੇ ਕਈ ਵਾਰੀ ਗੱਲਬਾਤ ਦੇ ਸੰਦਰਭ ਨੂੰ ਬਣਾਈ ਰੱਖਦਾ ਹੈ। - -LangChain4j Architecture - -*LangChain4j ਵਿਆਸਰਚਨਾ - ਮੁੱਖ ਕੰਪੋਨੈਂਟ ਇਕੱਠੇ ਕੰਮ ਕਰ ਕੇ ਤੁਹਾਡੇ AI ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਸਸ਼ਕਤ ਬਣਾਉਂਦੇ ਹਨ* - -## LangChain4j Dependencies - -ਇਹ quickstart [`pom.xml`](../../../00-quick-start/pom.xml) ਫਾਈਲ ਵਿੱਚ ਤਿੰਨ Maven ਡਿਪੈਂਡੇਸੀਜ਼ ਵਰਤਦਾ ਹੈ: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` ਮੋਡੀਊਲ `OpenAiOfficialChatModel` ਕਲਾਸ ਦਿੰਦਾ ਹੈ ਜੋ OpenAI-ਅਨੁਕੂਲ APIਜ਼ ਨਾਲ ਜੁੜਦਾ ਹੈ। GitHub ਮਾਡਲ ਵੀ ਇਸੇ API ਫਾਰਮੈਟ ਨੂੰ ਵਰਤਦੇ ਹਨ, ਇਸ ਲਈ ਕੋਈ ਖਾਸ ਐਡਾਪਟਰ ਦੀ ਲੋੜ ਨਹੀਂ — ਸਿਰਫ ਬੇਸ URL ਨੂੰ `https://models.github.ai/inference` ਤੇ ਸੈੱਟ ਕਰੋ। - -`langchain4j-easy-rag` ਮੋਡੀਊਲ ਆਟੋਮੈਟਿਕ ਡੌਕਯੂਮੈਂਟ ਸਪਲਿੱਟਿੰਗ, ਇੰਬੈੱਡਿੰਗ, ਅਤੇ ਰੀਟ੍ਰੀਵਲ ਮੁਹੱਈਆ ਕਰਵਾਉਂਦਾ ਹੈ ਤਾਂ ਜੋ ਤੁਸੀਂ ਹਰ ਕਦਮ ਨੂੰ ਮੈਨੂਅਲ ਤੌਰ 'ਤੇ ਸੰਰਚਿਤ ਕਰਨ ਦੇ ਬਿਨਾ RAG ਐਪਲੀਕੇਸ਼ਨਾਂ ਬਣਾ ਸਕੋ। - -## Prerequisites - -**Dev Container ਵਰਤ ਰਹੇ ਹੋ?** Java ਅਤੇ Maven ਪਹਿਲਾਂ ਹੀ ਇੰਸਟਾਲ ਕੀਤੇ ਹੋਏ ਹਨ। ਤੁਸੀਂ ਸਿਰਫ ਇੱਕ GitHub Personal Access Token ਦੀ ਲੋੜ ਹੈ। - -**ਲੋਕਲ ਡਿਵੈਲਪਮੈਂਟ ਲਈ:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (ਹੇਠਾਂ ਦਿੱਤੇ ਹੁਕਮਾਂ ਦੇ ਅਨੁਸਾਰ) - -> **ਨੋਟ:** ਇਹ ਮੋਡੀਊਲ GitHub Models ਵਿੱਚੋਂ `gpt-4.1-nano` ਵਰਤਦਾ ਹੈ। ਕੋਡ ਵਿੱਚ ਮਾਡਲ ਦਾ ਨਾਮ ਨਾ ਬਦਲੋ - ਇਹ ਵਰਤਮਾਨ GitHub ਦੇ ਉਪਲਬਧ ਮਾਡਲਾਂ ਨਾਲ ਕੰਮ ਕਰਨ ਲਈ ਸੰਰਚਿਤ ਹੈ। - -## Setup - -### 1. ਆਪਣਾ GitHub ਟੋਕਨ ਪ੍ਰਾਪਤ ਕਰੋ - -1. ਜਾਓ [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. "Generate new token" ਤੇ ਕਲਿੱਕ ਕਰੋ -3. ਇੱਕ ਵਰਨਨਾਤਮਕ ਨਾਮ ਦੇਵੋ (ਜਿਵੇਂ "LangChain4j Demo") -4. ਸਮਾਪਤੀ ਸਮਾਂ ਸੈੱਟ ਕਰੋ (7 ਦਿਨਾਂ ਦੀ ਸਿਫਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ) -5. "Account permissions" ਦੇ ਹੇਠਾਂ "Models" ਨੂੰ "Read-only" ਸੈੱਟ ਕਰੋ -6. "Generate token" ਤੇ ਕਲਿੱਕ ਕਰੋ -7. ਆਪਣਾ ਟੋਕਨ ਕਾਪੀ ਕਰੋ ਅਤੇ ਸੁਰੱਖਿਅਤ ਰੱਖੋ - ਮੁੜ ਨਹੀਂ ਮਿਲੇਗਾ - -### 2. ਆਪਣਾ ਟੋਕਨ ਸੈੱਟ ਕਰੋ - -**ਵਿਕਲਪ 1: VS Code ਵਰਤ ਕੇ (ਸਿਫਾਰਸ਼ੀ)** - -ਜੇ ਤੁਸੀਂ VS Code ਵਰਤ ਰਹੇ ਹੋ, ਤਾਂ ਆਪਣਾ ਟੋਕਨ ਪ੍ਰਾਜੈਕਟ ਦੀ ਰੂਟ ਵਿੱਚ `.env` ਫਾਈਲ ਵਿੱਚ ਸ਼ਾਮਲ ਕਰੋ: - -ਜੇ `.env` ਫਾਈਲ ਮੌਜੂਦ ਨਹੀਂ, ਤਾਂ `.env.example` ਨੂੰ `.env` ਵਿੱਚ ਕਾਪੀ ਕਰੋ ਜਾਂ ਨਵੀਂ `.env` ਫਾਈਲ ਪੈਦਾ ਕਰੋ। - -**ਨਮੂਨਾ `.env` ਫਾਈਲ:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env ਵਿੱਚ -GITHUB_TOKEN=your_token_here -``` - -ਫਿਰ ਤੁਸੀਂ ਸਿੱਧਾ ਕਿਥੇ ਵੀ ਕੋਈ ਡੈਮੋ ਫਾਈਲ (ਜਿਵੇਂ `BasicChatDemo.java`) ਤੇ ਰਾਈਟ-ਕਲਿੱਕ ਕਰਕੇ **"Run Java"** ਚੁਣ ਸਕਦੇ ਹੋ ਜਾਂ Run ਅਤੇ Debug ਪੈਨਲ ਦੇ ਲਾਂਚ ਕੰਫਿਗਰੇਸ਼ਨਾਂ ਦੀ ਵਰਤੋਂ ਕਰ ਸਕਦੇ ਹੋ। - -**ਵਿਕਲਪ 2: ਟਰਮੀਨਲ ਵਰਤ ਕੇ** - -ਟੋਕਨ ਨੂੰ ਵਾਤਾਵਰਣ ਚਲ ਉਤਰਾ ਵੈਰੀਏਬਲ ਵਜੋਂ ਸੈੱਟ ਕਰੋ: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Run the Examples - -**VS Code ਵਰਤਦੇ ਹੋਏ:** ਸਿੱਧਾ Explorer ਵਿੱਚ ਕਿਸੇ ਵੀ ਡੈਮੋ ਫਾਈਲ ਤੇ ਰਾਈਟ-ਕਲਿੱਕ ਕਰੋ ਅਤੇ **"Run Java"** ਚੁਣੋ, ਜਾਂ Run ਅਤੇ Debug ਪੈਨਲ ਤੋਂ ਲਾਂਚ ਕੰਫਿਗਰੇਸ਼ਨ ਸੈੱਟਿੰਗਜ਼ ਦੀ ਵਰਤੋਂ ਕਰੋ (ਪਹਿਲਾਂ ਇਹ ਯਕੀਨੀ ਬਣਾਓ ਕਿ ਤੁਸੀਂ `.env` ਵਿੱਚ ਆਪਣਾ ਟੋਕਨ ਜੋੜਿਆ ਹੈ)। - -**Maven ਵਰਤ ਕੇ:** ਵਿਕਲਪ ਵਜੋਂ, ਤੁਸੀਂ ਕਮਾਂਡ ਲਾਈਨ ਤੋਂ ਵੀ ਚਲਾ ਸਕਦੇ ਹੋ: - -### 1. Basic Chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Prompt Patterns - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -ਜ਼ੀਰੋ-ਸ਼ਾਟ, ਫਿਊ-ਸ਼ਾਟ, ਚੇਨ-ਆਫ-ਥਾਟ, ਅਤੇ ਰੋਲ-ਅਧਾਰਿਤ ਪ੍ਰੌਂਪਟਿੰਗ ਦਿਖਾਉਂਦਾ ਹੈ। - -### 3. Function Calling - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -ਜਦੋਂ ਲੋੜ ਹੋਵੇ ਤਾਂ AI ਆਪਣੇ ਆਪ ਤੁਹਾਡੇ ਜਾਵਾ ਮੈਥਡਾਂ ਨੂੰ ਕਾਲ ਕਰਦਾ ਹੈ। - -### 4. Document Q&A (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -ਆਪਣੇ ਡੌਕਯੂਮੈਂਟਾਂ ਬਾਰੇ ਸਵਾਲ ਪੁੱਛੋ Easy RAG ਨਾਲ ਆਟੋਮੈਟਿਕ ਇੰਬੈੱਡਿੰਗ ਤੇ ਰੀਟ੍ਰੀਵਲ ਵਰਤ ਕੇ। - -### 5. Responsible AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -ਵੇਖੋ ਕਿ AI ਸੁਰੱਖਿਆ ਫਿਲਟਰ ਕਿਵੇਂ ਹਾਨਿਕਾਰਕ ਸਮੱਗਰੀ ਨੂੰ ਬਲਾਕ ਕਰਦੇ ਹਨ। - -## What Each Example Shows - -**Basic Chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -ਇੱਥੇ ਸ਼ੁਰੂ ਕਰੋ ਤਾਂ ਕਿ LangChain4j ਨੂੰ ਸਭ ਤੋਂ ਸਧਾਰਨ ਰੂਪ ਵਿੱਚ ਵੇਖ ਸਕੋ। ਤੁਸੀਂ ਇਕ `OpenAiOfficialChatModel` ਬਣਾਉਗੇ, `.chat()` ਨਾਲ ਇੱਕ ਪ੍ਰੌਂਪਟ ਭੇਜੋਗੇ ਅਤੇ ਜਵਾਬ ਪ੍ਰਾਪਤ ਕਰੋਗੇ। ਇਹ ਮੁੱਢਲੇ ਤੌਰ 'ਤੇ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਕਿਵੇਂ ਮਾਡਲਾਂ ਨੂੰ ਕਸਟਮ ਐਂਡਪੁਆਇੰਟ ਤੇ API ਕੁੰਜੀਆਂ ਨਾਲ ਇਨਿਸ਼ੀਏਟ ਕੀਤਾ ਜਾਂਦਾ ਹੈ। ਇਸ ਪਰਿਬਾਧਾ ਨੂੰ ਸਮਝਣ ਦੇ ਬਾਅਦ ਬਾਕੀ ਸਾਰੀ ਚੀਜ਼ਾਂ ਇਸ 'ਤੇ ਅਧਾਰਿਤ ਬਣਦੀਆਂ ਹਨ। - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "ਮੈਂ ਇਸ ਕੋਡ ਵਿੱਚ GitHub Models ਤੋਂ Azure OpenAI ਵਿੱਚ ਕਿਵੇਂ ਬਦਲ ਕਰਾਂ?" -> - "OpenAiOfficialChatModel.builder() ਵਿੱਚ ਹੋਰ ਕਿਹੜੇ ਪੈਰਾਮੀਟਰ ਮੈਂ ਸੈੱਟ ਕਰ ਸਕਦਾ ਹਾਂ?" -> - "ਮੈਂ ਪੂਰਾ ਜਵਾਬ ਦੇਖਣ ਦੀ ਬਜਾਏ ਸਟ੍ਰੀਮਿੰਗ ਜਵਾਬ ਕਿਵੇਂ ਸ਼ਾਮਲ ਕਰਾਂ?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -ਹੁਣ ਜਦੋਂ ਤੁਸੀਂ ਮਾਡਲ ਨਾਲ ਗੱਲ ਕਰਨਾ ਜਾਣਦੇ ਹੋ, ਤਾਂ ਆਓ ਵੇਖੀਏ ਕਿ ਤੁਸੀਂ ਇਸ ਨੂੰ ਕੀ ਕਹਿੰਦੇ ਹੋ। ਇਹ ਡੈਮੋ ਵੱਖ-ਵੱਖ ਪ੍ਰੌਂਪਟਿੰਗ ਪੈਟਰਨ ਦਿਖਾਉਂਦਾ ਹੈ। ਜਿਵੇਂ: -ਜ਼ੀਰੋ-ਸ਼ਾਟ ਪ੍ਰੌਂਪਟ ਸਿੱਧੇ ਹੁਕਮਾਂ ਲਈ, ਫਿਊ-ਸ਼ਾਟ ਜਿਹੜੇ ਉਦਾਹਰਣਾਂ ਤੋਂ ਸਿੱਖਦੇ ਹਨ, ਚੇਨ-ਆਫ-ਥਾਟ ਜੋ ਤਰਕਬੱਧ ਕਦਮ ਪ੍ਰਗਟ ਕਰਦੇ ਹਨ, ਅਤੇ ਰੋਲ-ਅਧਾਰਿਤ ਪ੍ਰੌਂਪਟ ਜਿਹੜੇ ਸੰਦਰਭ ਸੈੱਟ ਕਰਦੇ ਹਨ। ਤੁਸੀਂ ਦੇਖੋਗੇ ਕਿ ਇੱਕੋ ਮਾਡਲ ਕਿਵੇਂ ਵੱਖਰੇ ਨਤੀਜੇ ਦਿੰਦਾ ਹੈ ਜਿਸ ਤਰ੍ਹਾਂ ਤੁਸੀਂ ਆਪਣੀ ਮੰਗ ਨੂੰ ਰੂਪ ਦੇਂਦੇ ਹੋ। - -ਡੈਮੋ ਵਿੱਚ ਪ੍ਰੌਂਪਟ ਟੈਂਪਲੇਟ ਵੀ ਦਿਖਾਉਂਦਾ ਹੈ, ਜੋ ਵੈਰੀਏਬਲਾਂ ਨਾਲ ਦੁਬਾਰਾ ਵਰਤੋਂਯੋਗ ਪ੍ਰੌਂਪਟ ਬਣਾਉਣ ਦਾ ਸ਼ਕਤੀਸ਼ালী ਤਰੀਕਾ ਹੈ। -ਹੇਠਾਂ ਦਿੱਤਾ ਉਦਾਹਰਣ LangChain4j ਦੇ `PromptTemplate` ਨੂੰ ਵਰਤ ਕੇ ਵੈਰੀਏਬਲ ਭਰਨ ਦਾ ਦਿਖਾਵਾ ਕਰਦਾ ਹੈ। AI ਪ੍ਰਦਾਨ ਕੀਤੇ ਗੰਤੀਨ ਅਤੇ ਸਰਗਰਮੀ ਦੇ ਆਧਾਰ 'ਤੇ ਜਵਾਬ ਦੇਵੇਗਾ। - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "ਜ਼ੀਰੋ-ਸ਼ਾਟ ਅਤੇ ਫਿਊ-ਸ਼ਾਟ ਪ੍ਰੌਂਪਟਿੰਗ ਵਿੱਚ ਕੀ ਫਰਕ ਹੈ ਅਤੇ ਮੈਂ ਇਹਨਾਂ ਵਿੱਚੋਂ ਕਦੋਂ ਵਰਤਾਂ?" -> - "ਆਪਣੇ ਮਾਡਲ ਦੇ ਜਵਾਬਾਂ 'ਤੇ ਤੇਮਪਰੇਚਰ ਪੈਰਾਮੀਟਰ ਦਾ ਕੀ ਅਸਰ ਹੁੰਦਾ ਹੈ?" -> - "ਪ੍ਰੌਂਪਟ ਇੰਜੈਕਸ਼ਨ ਹਮਲਿਆਂ ਤੋਂ ਕਿਵੇਂ ਬਚਿਆ ਜਾ ਸਕਦਾ ਹੈ?" -> - "ਆਮ ਪੈਟਰਨਾਂ ਲਈ ਦੁਬਾਰਾ ਵਰਤੋਂਯੋਗ `PromptTemplate` ਆਬਜੈਕਟ ਕਿਵੇਂ ਬਣਾਉਂਦਾ ਹਾਂ?" - -**Tool Integration** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -ਇੱਥੇ LangChain4j ਸ਼ਕਤੀਸ਼ਾਲੀ ਹੁੰਦਾ ਹੈ। ਤੁਸੀਂ `AiServices` ਨਾਲ ਇੱਕ AI ਸਹਾਇਕ ਬਣਾਉਗੇ ਜੋ ਤੁਹਾਡੇ ਜਾਵਾ ਮੈਥਡਾਂ ਨੂੰ ਕਾਲ ਕਰ ਸਕਦਾ ਹੈ। ਸਿਰਫ `@Tool("description")` ਨਾਲ ਮੈਥਡਾਂ ਨੂੰ ਅਨੋਟੇਟ ਕਰੋ ਅਤੇ LangChain4j ਬਾਕੀ ਕੰਮ ਸੰਭਾਲਦਾ ਹੈ - AI ਆਪਣੇ ਆਪ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕਦੋਂ ਕਿਹੜਾ ਟੂਲ ਵਰਤਣਾ ਹੈ। ਇਹ ਫੰਕਸ਼ਨ ਕਾਲਿੰਗ ਦੀ ਵਰਤੋਂ ਦਿਖਾਉਂਦਾ ਹੈ, ਜੋ ਕਿ AI ਬਣਾਉਣ ਲਈ ਇੱਕ ਅਹਮ ਤਕਨੀਕ ਹੈ ਜੋ ਸਿਰਫ ਸਵਾਲਾਂ ਦੇ ਜਵਾਬ ਨਹੀਂ ਦਿੰਦਾ, ਬਲਕਿ ਕਾਰਵਾਈਆਂ ਵੀ ਕਰਦਾ ਹੈ। - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "@Tool ਅਨੋਟੇਸ਼ਨ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ ਅਤੇ LangChain4j ਇਸਦੇ ਨਾਲ ਅੰਦਰੋਂ ਕੀ ਕਰਦਾ ਹੈ?" -> - "ਕੀ AI ਕਈ ਟੂਲਾਂ ਨੂੰ ਲੜੀਵਾਰ ਕਾਲ ਕਰਕੇ ਪੇਚੀਦਾ ਸਮੱਸਿਆ ਹੱਲ ਕਰ ਸਕਦਾ ਹੈ?" -> - "ਜੇ ਕੋਈ ਟੂਲ ਇਕਸਪਸ਼ਨ ਸੁੱਟੇ, ਤਾਂ ਮੈਂ ਏਰਰ ਨੂੰ ਕਿਵੇਂ ਹੈਂਡਲ ਕਰਾਂ?" -> - "ਇਸ ਕੈਲਕੂਲੇਟਰ ਉਦਾਹਰਣ ਦੀ ਥਾਂ ਤੇ ਮੈਂ ਅਸਲੀ API ਕਿਵੇਂ ਇੰਟੀਗ੍ਰੇਟ ਕਰਾਂ?" - -**Document Q&A (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -ਇੱਥੇ ਤੁਸੀਂ LangChain4j ਦੇ "Easy RAG" ਪਹੁੰਚ ਨਾਲ RAG (retrieval-augmented generation) ਦੇਖੋਗੇ। ਡੌਕਯੂਮੈਂਟ ਲੋਡ ਕੀਤੇ ਜਾਂਦੇ ਹਨ, ਆਟੋਮੈਟਿਕ ਤੌਰ 'ਤੇ ਵੰਡੇ ਜਾਂਦੇ ਹਨ ਅਤੇ ਇਨ-ਮੇਮੋਰੀ ਸਟੋਰ ਵਿੱਚ ਇੰਬੈੱਡ ਕੀਤੇ ਜਾਂਦੇ ਹਨ, ਫਿਰ ਇਕ ਸੰਬੰਧਿਤ ਸਮੱਗਰੀ ਲੈਣ ਵਾਲਾ AI ਨੂੰ ਸਵਾਲ ਸਮੇਂ ਉਚਿਤ ਟੁਕੜੇ ਪਰਦਾਨ ਕਰਦਾ ਹੈ। AI ਤੁਹਾਡੇ ਡੌਕਯੂਮੈਂਟਾਂ ਦੇ ਆਧਾਰ 'ਤੇ ਜਵਾਬ ਦਿੰਦਾ ਹੈ, ਨਾ ਕਿ ਇਸ ਦੀ ਆਮ ਜਾਣਕਾਰੀ ਤੇ। - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "RAG ਕਿਸ ਤਰ੍ਹਾਂ ਮਾਡਲ ਦੀ ਟ੍ਰੇਨਿੰਗ ਜਾਣਕਾਰੀ ਦੀ ਤੁਲਨਾ ਵਿੱਚ AI ਹੁੱਛ ਕਹਾਣੀਆਂ ਨੂੰ ਰੋਕਦਾ ਹੈ?" -> - "ਇਸ ਆਸਾਨ ਪਹੁੰਚ ਅਤੇ ਕਸਟਮ RAG ਪਾਈਪਲਾਈਨ ਵਿੱਚ ਕੀ ਫਰਕ ਹੈ?" -> - "ਮੈਂ ਕਿਵੇਂ ਇਸ ਨੂੰ ਕਈ ਡੌਕਯੂਮੈਂਟਾਂ ਜਾਂ ਵੱਡੇ ਗਿਆਨ ਭੰਡਾਰਾਂ ਉੱਤੇ ਫੈਲਾ ਸਕਦਾ ਹਾਂ?" - -**Responsible AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -ਗਹਿਰਾਈ ਨਾਲ AI ਸੁਰੱਖਿਆ ਬਣਾਓ। ਇਹ ਡੈਮੋ ਦੋ ਸਤਰਾਂ ਦੀ ਸੁਰੱਖਿਆ ਦੇਖਾਉਂਦਾ ਹੈ ਜੋ ਇਕੱਠੇ ਕੰਮ ਕਰਦੀਆਂ ਹਨ: - -**ਭਾਗ 1: LangChain4j ਇਨਪੁੱਟ ਗਾਰਡਰੇਲਜ਼** - ਖ਼ਤਰਨਾਕ ਪ੍ਰੌਂਪਟਾਂ ਨੂੰ LLM ਤਕ ਪਹੁੰਚਣ ਤੋਂ ਪਹਿਲਾਂ ਰੋਕਦਾ ਹੈ। ਕਸਟਮ ਗਾਰਡਰੇਲ ਬਣਾਓ ਜੋ ਮਨਾਹੀ ਸ਼ਬਦਾਂ ਜਾਂ ਪੈਟਰਨਾਂ ਨੂੰ ਜਾਂਚਦੇ ਹਨ। ਇਹ ਤੁਹਾਡੇ ਕੋਡ ਵਿੱਚ ਚਲਦੇ ਹਨ, ਇਸ ਲਈ ਤੇਜ਼ ਅਤੇ ਮੁਫਤ ਹਨ। - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**ਭਾਗ 2: ਪ੍ਰੋਵਾਈਡਰ ਸੇਫਟੀ ਫਿਲਟਰ** - GitHub Models ਵਿੱਚ ਪਹਿਲਾਂ ਤੋਂ ਫਿਲਟਰ ਹਨ ਜੋ ਤੁਹਾਡੇ ਗਾਰਡਰੇਲਾਂ ਤੋਂ ਬਚ ਸਕਣ ਵਾਲੀਆਂ ਚੀਜ਼ਾਂ ਨੂੰ ਫੜਦੇ ਹਨ। ਤੁਸੀਂ ਭਿਆਨਕ ਉਲੰਘਣਾਂ ਲਈ ਕਠੋਰ ਬਲਾਕ (HTTP 400 ਐਰਰ) ਅਤੇ ਨਰਮ ਇਨਕਾਰ ਦੇਖੋਗੇ ਜਿੱਥੇ AI ਸਨਮਾਨਪੂਰਵਕ ਇਨਕਾਰ ਕਰਦਾ ਹੈ। - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "InputGuardrail ਕੀ ਹੈ ਅਤੇ ਮੈਂ ਆਪਣਾ ਕਿਵੇਂ ਬਣाऊਂ?" -> - "ਕਠੋਰ ਬਲਾਕ ਤੇ ਨਰਮ ਇਨਕਾਰ ਵਿੱਚ ਕੀ ਫਰਕ ਹੈ?" -> - "ਗਾਰਡਰੇਲ ਅਤੇ ਪ੍ਰੋਵਾਈਡਰ ਫਿਲਟਰ ਦੋਹਾਂ ਨੂੰ ਇਕੱਠੇ ਵਰਤਣ ਦਾ ਕੀ ਲਾਭ ਹੈ?" - -## Next Steps - -**ਅਗਲਾ ਮੋਡੀਊਲ:** [01-introduction - Getting Started with LangChain4j](../01-introduction/README.md) - ---- - -**ਨੈਵੀਗੇਸ਼ਨ:** [← ਮੁੱਖ ਪੇਜ ਤੇ ਵਾਪਸ](../README.md) | [ਅਗਲਾ: Module 01 - Introduction →](../01-introduction/README.md) - ---- - -## Troubleshooting - -### ਪਹਿਲੀ ਵਾਰੀ Maven ਬਿਲਡ - -**ਮਸਲਾ**: ਪਹਿਲੀ ਵਾਰੀ `mvn clean compile` ਜਾਂ `mvn package` 10-15 ਮਿੰਟ ਲੱਗਦੇ ਹਨ - -**ਕਾਰਨ**: Maven ਨੂੰ ਸਾਰੇ ਪ੍ਰਾਜੈਕਟ ਡਿਪੈਂਡੇਸੀਜ਼ (Spring Boot, LangChain4j ਲਾਇਬ੍ਰੇਰੀਆਂ, Azure SDK ਆਦਿ) ਪਹਿਲੀ ਵਾਰੀ ਡਾਊਨਲੋਡ ਕਰਨੀਆਂ ਪੈਂਦੀਆਂ ਹਨ। - -**ਸਮਾਧਾਨ**: ਇਹ ਆਮ ਗੱਲ ਹੈ। ਅਗਲੀ ਵਾਰ ਬਿਲਡ ਬਹੁਤ ਜਲਦੀ ਹੋਵੇਗੀ ਕਿਉਂਕਿ ਡਿਪੈਂਡੇਸੀਜ਼ ਲੋਕਲ ਕੈਸ਼ ਹੋ ਜਾਨਗੀਆਂ। ਡਾਊਨਲੋਡ ਸਮਾਂ ਤੁਹਾਡੇ ਨੈੱਟਵਰਕ ਦੀ ਗਤੀ 'ਤੇ ਨਿਰਭਰ ਕਰਦਾ ਹੈ। - -### PowerShell Maven ਕਮਾਂਡ ਸਿੰਟੈਕਸ - -**ਮਸਲਾ**: Maven ਕਮਾਂਡ `Unknown lifecycle phase ".mainClass=..."` ਨਾਲ ਫੇਲ ਹੋ ਜਾਂਦੇ ਹਨ -**ਕਾਰਣ**: PowerShell `=` ਨੂੰ ਵੈਰੀਏਬਲ ਅਸਾਈਨਮੈਂਟ ਆਪਰੇਟਰ ਵਜੋਂ ਸਮਝਦਾ ਹੈ, ਜਿਸ ਨਾਲ Maven ਦੀ ਪ੍ਰਾਪਰਟੀ ਸਿੰਟੈਕਸ ਟੁੱਟ ਜਾਂਦੀ ਹੈ - -**ਸਮਾਧਾਨ**: Maven ਕਮਾਂਡ ਤੋਂ ਪਹਿਲਾਂ stop-parsing آپਰੇਟਰ `--%` ਦੀ ਵਰਤੋਂ ਕਰੋ: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` آپਰੇਟਰ PowerShell ਨੂੰ ਕਹਿੰਦਾ ਹੈ ਕਿ ਬਾਕੀ ਬਚੇ ਹੋਏ ਸਾਰੇ ਆਰਗੁਮੈਂਟਸ ਬਿਨਾਂ ਕਿਸੇ ਵਿਆਖਿਆ ਦੇ Maven ਨੂੰ ਸਿੱਧੇ ਪਾਸ ਕਰ ਦੇਵੇ। - -### ਵਿੰਡੋਜ਼ PowerShell Emoji ਡਿਸਪਲੇ - -**ਮੁੱਦਾ**: PowerShell ਵਿੱਚ AI ਜਵਾਬਾਂ emoji ਦੀ ਥਾਂ ਕੂੜਾਹਟ ਵਰਗੀਆਂ ਕਿਰਦਾਰ (`????` ਜਾਂ `â??`) ਦਿਖਾਉਂਦੇ ਹਨ - -**ਕਾਰਣ**: PowerShell ਦੀ ਡਿਫਾਲਟ ਇੰਕੋਡਿੰਗ UTF-8 emojis ਦਾ ਸਮਰਥਨ ਨਹੀਂ ਕਰਦੀ - -**ਸਮਾਧਾਨ**: ਜਾਵਾ ਐਪਲੀਕੇਸ਼ਨ ਚਲਾਉਣ ਤੋਂ ਪਹਿਲਾਂ ਇਹ ਕਮਾਂਡ ਚਲਾਓ: -```cmd -chcp 65001 -``` - -ਇਸ ਨਾਲ ਟਰਮੀਨਲ ਵਿੱਚ UTF-8 ਇੰਕੋਡਿੰਗ ਮੁਕੰਮਲ ਹੋ ਜਾਂਦੀ ਹੈ। ਵਿਸ਼ਵਾਸਯੋਗ ਵਿਕਲਪ ਵਜੋਂ Windows Terminal ਦੀ ਵਰਤੋਂ ਕਰੋ ਜਿਸ ਵਿੱਚ Unicode ਲਈ ਵਧੀਆ ਸਮਰਥਨ ਹੈ। - -### API ਕਾਲਾਂ ਦਾ ਡੀਬੱਗਿੰਗ - -**ਮੁੱਦਾ**: AI ਮਾਡਲ ਤੋਂ ਪ੍ਰਮਾਣਿਕਤਾ ਦੀਆਂ ਗਲਤੀਆਂ, ਰੇਟ ਸੀਮਾਵਾਂ ਜਾਂ ਅਣਛਾਹੀਆਂ ਜਵਾਬ - -**ਸਮਾਧਾਨ**: ਉਦਾਹਰਣਾਂ `.logRequests(true)` ਅਤੇ `.logResponses(true)` ਸ਼ਾਮਿਲ ਕਰਦੀਆਂ ਹਨ ਜੋ API ਕਾਲਾਂ ਨੂੰ ਕੰਸੋਲ ਵਿੱਚ ਵੇਖਾਉਂਦੀਆਂ ਹਨ। ਇਹ ਪ੍ਰਮਾਣਿਕਤਾ ਗਲਤੀਆਂ, ਰੇਟ ਸੀਮਾਵਾਂ ਜਾਂ ਅਣਛਾਹੀਆਂ ਜਵਾਬਾਂ ਦਾ ਪਤਾ ਲਗਾਉਣ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ। ਪ੍ਰੋਡਕਸ਼ਨ ਵਿੱਚ ਲੋਗ ਸ਼ੋਰ ਘਟਾਉਣ ਲਈ ਇਹ ਝੰਡੇ ਹਟਾਓ। - ---- - - -**ਅਸਵੀਕਾਰਨ**: -ਇਹ ਦਸਤਾਵੇਜ਼ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਅਨੁਵਾਦਿਤ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾ ਲਈ ਕੋਸ਼ਿਸ਼ ਕਰਦੇ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਵਿੱਚ ਰੱਖੋ ਕਿ ਆਟੋਮੈਟਿਕ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਣਸਹੀਤੀਆਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਅਧਿਕਾਰਿਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਜ਼ਰੂਰੀ ਜਾਣਕਾਰੀ ਲਈ, ਮਾਹਿਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਇਸ ਅਨੁਵਾਦ ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਭ੍ਰਮਾਂ ਲਈ ਅਸੀਂ ਜ਼ਿੰਮੇਵਾਰ ਨਹੀਂ ਹਾਂ। - \ No newline at end of file diff --git a/translations/pa/01-introduction/README.md b/translations/pa/01-introduction/README.md index 8f40b378b..09a6c1f7a 100644 --- a/translations/pa/01-introduction/README.md +++ b/translations/pa/01-introduction/README.md @@ -1,87 +1,87 @@ -# ਮੋਡੀਊਲ 01: LangChain4j ਨਾਲ ਸ਼ੁਰੂਆਤ ਕਰਨਾ +# ਮੋਡੀਊਲ 01: LangChain4j ਨਾਲ ਸ਼ੁਰੂਆਤ -## ਸਮਗਰੀ ਸੂਚੀ +## ਸਮੱਗਰੀ ਦੀ ਸੂਚੀ -- [ਵੀਡੀਓ ਵਾਕਥਰੂ](../../../01-introduction) -- [ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ](../../../01-introduction) -- [ਪੂਰਵ ਸ਼ਰਤਾਂ](../../../01-introduction) -- [ਮੁੱਖ ਸਮੱਸਿਆ ਨੂੰ ਸਮਝਣਾ](../../../01-introduction) -- [ਟੋਕਨਸ ਨੂੰ ਸਮਝਣਾ](../../../01-introduction) -- [ਮੈਮੋਰੀ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ](../../../01-introduction) -- [ਇਹ LangChain4j ਨੂੰ ਕਿਵੇਂ ਵਰਤਦਾ ਹੈ](../../../01-introduction) -- [Azure OpenAI ਢਾਂਚਾ ਤਿਆਰ ਕਰੋ](../../../01-introduction) -- [ਐਪਲੀਕੇਸ਼ਨ ਨੂੰ ਲੋਕਲ ਚਲਾਓ](../../../01-introduction) -- [ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਵਰਤੋਂ](../../../01-introduction) - - [ਬਿਨਾਂ ਸਟੇਟ ਵਾਲਾ ਚੈਟ (ਖੱਬਾ ਪੈਨਲ)](../../../01-introduction) - - [ਸਟੇਟਫੁਲ ਚੈਟ (ਸੱਜਾ ਪੈਨਲ)](../../../01-introduction) -- [ਅਗਲੇ ਕਦਮ](../../../01-introduction) +- [ਵੇਡੀਓ ਵਾਕਥਰੂ](#ਵੇਡੀਓ-ਵਾਕਥਰੂ) +- [ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ](#ਤੁਸੀਂ-ਕੀ-ਸਿੱਖੋਗੇ) +- [ਪੂਰਵਾਪੇਸ਼ਾ](#ਪੂਰਵਾਪੇਸ਼ਾ) +- [ਮੁੱਖ ਸਮੱਸਿਆ ਨੂੰ ਸਮਝਣਾ](#ਮੁੱਖ-ਸਮੱਸਿਆ-ਨੂੰ-ਸਮਝਣਾ) +- [ਟੋਕਨ ਨੂੰ ਸਮਝਣਾ](#ਟੋਕਨ-ਨੂੰ-ਸਮਝਣਾ) +- [ਮੈਮੋਰੀ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ](#ਮੈਮੋਰੀ-ਕਿਵੇਂ-ਕੰਮ-ਕਰਦੀ-ਹੈ) +- [ਇਹ LangChain4j ਕਿਵੇਂ ਵਰਤੀ ਜਾਂਦੀ ਹੈ](#ਇਹ-langchain4j-ਕਿਵੇਂ-ਵਰਤੀ-ਜਾਂਦੀ-ਹੈ) +- [Azure OpenAI ਇੰਫ੍ਰਾਸਟ੍ਰੱਕਚਰ ਨਿਯੁਕਤ ਕਰੋ](#azure-openai-ਇੰਫ੍ਰਾਸਟ੍ਰੱਕਚਰ-ਨਿਯੁਕਤ-ਕਰੋ) +- [ਐਪਲੀਕੇਸ਼ਨ ਨੂੰ ਲੋਕਲ ਰਣ ਕਰੋ](#ਐਪਲੀਕੇਸ਼ਨ-ਨੂੰ-ਲੋਕਲ-ਰਣ-ਕਰੋ) +- [ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਵਰਤੋਂ](#ਐਪਲੀਕੇਸ਼ਨ-ਦੀ-ਵਰਤੋਂ) + - [ਸਟੇਟਲੈੱਸ ਚੈਟ (ਖੱਬਾ ਪੈਨਲ)](#ਸਟੇਟਲੈੱਸ-ਚੈਟ-ਖੱਬਾ-ਪੈਨਲ) + - [ਸਟੇਟਫੁਲ ਚੈਟ (ਸੱਜਾ ਪੈਨਲ)](#ਸਟੇਟਫੁਲ-ਚੈਟ-ਸੱਜਾ-ਪੈਨਲ) +- [ਅਗਲੇ ਕਦਮ](#ਅਗਲੇ-ਕਦਮ) -## ਵੀਡੀਓ ਵਾਕਥਰੂ +## ਵੇਡੀਓ ਵਾਕਥਰੂ -ਇਸ ਲਾਈਵ ਸੈਸ਼ਨ ਨੂੰ ਵੇਖੋ ਜੋ ਦੱਸਦਾ ਹੈ ਕਿ ਇਸ ਮੋਡੀਊਲ ਨਾਲ ਕਿਵੇਂ ਸ਼ੁਰੂਆਤ ਕਰਨੀ ਹੈ: +ਇਸ ਲਾਇਵ ਸੈਸ਼ਨ ਨੂੰ ਦੇਖੋ ਜੋ ਦੱਸਦਾ ਹੈ ਕਿ ਇਸ ਮੋਡੀਊਲ ਨਾਲ ਕਿਵੇਂ ਸ਼ੁਰੂ ਕਰਨਾ ਹੈ: -LangChain4j ਨਾਲ ਸ਼ੁਰੂਆਤ - ਲਾਈਵ ਸੈਸ਼ਨ +LangChain4j ਨਾਲ ਸ਼ੁਰੂਆਤ - ਲਾਇਵ ਸੈਸ਼ਨ ## ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ -ਇਸ ਕਵਿਕ ਸਟਾਰਟ ਵਿੱਚ, ਤੁਸੀਂ GitHub ਮਾਡਲਾਂ ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਪ੍ਰਾਂਪਟ ਭੇਜੇ, ਟੂਲ ਕਾਲ ਕੀਤੇ, ਇੱਕ RAG ਪਾਈਪਲਾਈਨ ਬਣਾਈ ਅਤੇ ਗਾਰਡਰੇਲਜ਼ ਦੀ ਜਾਂਚ ਕੀਤੀ। ਉਹਨਾਂ ਡੈਮੋਜ਼ ਨੇ ਦਿਖਾਇਆ ਕਿ ਕੀ ਸੰਭਵ ਹੈ — ਹੁਣ ਅਸੀਂ Azure OpenAI ਅਤੇ GPT-5.2 ਦੇ ਨਾਲ ਬਦਲਦੇ ਹਾਂ ਅਤੇ ਉਤਪਾਦਨ-ਸ਼ੈਲੀ ਦੀਆਂ ਐਪਲੀਕੇਸ਼ਨਾਂ ਬਣਾਉਣਾ ਸ਼ੁਰੂ ਕਰਦੇ ਹਾਂ। ਇਹ ਮੋਡੀਊਲ ਗੱਲਬਾਤੀ AI 'ਤੇ ਕੇਂਦਰਿਤ ਹੈ ਜੋ ਸੰਦਰਭ ਯਾਦ ਰੱਖਦਾ ਹੈ ਅਤੇ ਸਟੇਟ ਬਰਕਰਾਰ ਰੱਖਦਾ ਹੈ — ਉਹ ਸਮਝਾਵਟਾਂ ਜੋ ਕਵਿਕ ਸਟਾਰਟ ਡੈਮੋਜ਼ ਨੇ ਪਿਛੋਕੜ ਵਿੱਚ ਵਰਤੀਆਂ ਪਰ ਵੇਖਾਈਆਂ ਨਹੀਂ। +ਇਹ ਤੁਹਾਡਾ LangChain4j ਅਤੇ Azure OpenAI ਨਾਲ ਸ਼ੁਰੂਆਤੀ ਬਿੰਦੂ ਹੈ। ਅਸੀਂ ਮੂਲ ਵਸਤਾਂ ਤੋਂ ਸ਼ੁਰੂ ਕਰਦੇ ਹਾਂ ਅਤੇ ਪ੍ਰੋਡਕਸ਼ਨ-ਸਟਾਈਲ ਐਪਲੀਕੇਸ਼ਨਾਂ ਬਣਾਉਣਾ ਸਿਖਦੇ ਹਾਂ। ਇਹ ਮੋਡੀਊਲ ਗੱਲਬਾਤੀ AI ’ਤੇ ਧਿਆਨ ਕੇਂਦ੍ਰਿਤ ਕਰਦਾ ਹੈ ਜੋ ਸੰਦਰਭ ਯਾਦ ਰੱਖਦਾ ਹੈ ਅਤੇ ਸਥਿਤੀ ਨੂੰ ਬਣਾਈ ਰੱਖਦਾ ਹੈ — ਬੁਨਿਆਦੀ ਧਾਰਣਾ ਜਿਸ ’ਤੇ ਹਰ ਅਗਲਾ ਮੋਡੀਊਲ ਨਿਰਭਰ ਕਰਦਾ ਹੈ। -ਅਸੀਂ ਇਸ ਮਾਰਗਦਰਸ਼ਕ ਵਿੱਚ ਸਾਰਾ ਸਮਾਂ Azure OpenAI ਦੇ GPT-5.2 ਦੀ ਵਰਤੋਂ ਕਰਾਂਗੇ ਕਿਉਂਕਿ ਇਸ ਦੀ ਉੰਨੀਕ ਸੂਝਬੂਝ ਵੱਖ-ਵੱਖ ਪੈਟਰਨ ਦੇ ਵਿਹਾਰ ਨੂੰ ਵੱਧ ਸਪੱਸ਼ਟ ਕਰਦੀ ਹੈ। ਜਦੋਂ ਤੁਸੀਂ ਮੈਮੋਰੀ ਨੂੰ ਸ਼ਾਮਲ ਕਰੋਗੇ, ਤਦ ਤੁਹਾਨੂੰ ਫਰਕ ਸਾਫ਼-ਸੁਧਰ ਜੀਵੰਤ ਪਤਾ ਲੱਗੇਗਾ। ਇਹ ਸਮਝਣਾ ਆਸਾਨ ਹੋ ਜਾਵੇਗਾ ਕਿ ਹਰ ਹਿੱਸਾ ਤੁਹਾਡੇ ਐਪਲੀਕੇਸ਼ਨ ਲਈ ਕੀ ਲਿਆਉਂਦਾ ਹੈ। +ਅਸੀਂ ਇਸ ਮਾਰਗਦਰਸ਼ਕ ਵਿਚ Azure OpenAI ਦਾ GPT-5.2 ਵਰਤਾਂਗੇ ਕਿਉਂਕਿ ਇਸ ਦੀਆਂ ਉੱਨਤ ਤਰਕਸ਼ੀਲਤਾ ਖਾਸ ਤੌਰ ’ਤੇ ਵੱਖ-ਵੱਖ ਪੈਟਰਨਾਂ ਦੇ ਵਰਤਾਅ ਨੂੰ ਵਧੀਆ ਸਮਝਾਉਂਦੀ ਹੈ। ਜਦੋਂ ਤੁਸੀਂ ਮੈਮੋਰੀ ਸ਼ਾਮਲ ਕਰਦੇ ਹੋ, ਤਾਂ ਤੁਸੀਂ ਫਰਕ ਸਪਸ਼ਟ ਤੌਰ ’ਤੇ ਵੇਖੋਗੇ। ਇਹ ਤੁਹਾਡੇ ਐਪਲੀਕੇਸ਼ਨ ਵਿਚ ਹਰ ਭਾਗ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ ਇਹ ਸਮਝਣਾ ਆਸਾਨ ਬਣਾਉਂਦਾ ਹੈ। -ਤੁਸੀਂ ਇੱਕ ਐਪਲੀਕੇਸ਼ਨ ਬਣਾਉਗੇ ਜੋ ਦੋਨੋਂ ਪੈਟਰਨਸ ਨੂੰ ਦਰਸਾਉਂਦੀ ਹੈ: +ਤੁਸੀਂ ਇੱਕ ਐਪਲੀਕੇਸ਼ਨ ਬਣਾਉਂਦੇ ਹੋ ਜੋ ਦੋਹਾਂ ਪੈਟਰਨਾਂ ਨੂੰ ਦਰਸਾਉਂਦੀ ਹੈ: -**ਬਿਨਾਂ ਸਟੇਟ ਵਾਲਾ ਚੈਟ** - ਹਰ ਬੇਨਤੀ ਸਵਤੰਤਰ ਹੈ। ਮਾਡਲ ਨੂੰ ਪਹਿਲਾਂ ਦੇ ਸੁਨੇਹਿਆਂ ਦੀ ਕੋਈ ਮੈਮੋਰੀ ਨਹੀਂ ਹੁੰਦੀ। ਇਹ ਪੈਟਰਨ ਤੁਸੀਂ ਕਵਿਕ ਸਟਾਰਟ ਵਿੱਚ ਵਰਤੀ। +**ਸਟੇਟਲੈੱਸ ਚੈਟ** - ਹਰ ਬੇਨਤੀ ਸਵਤੰਤਰ ਹੁੰਦੀ ਹੈ। ਮਾਡਲ ਨੂੰ ਪਿਛਲੇ ਸੁਨੇਹਿਆਂ ਦੀ ਕੋਈ ਮੈਮੋਰੀ ਨਹੀਂ ਹੁੰਦੀ। ਇਹ ਸਭ ਤੋਂ ਸਧਾਰਣ ਸ਼ੁਰੂਆਤ ਹੈ। -**ਸਟੇਟਫੁਲ ਗੱਲਬਾਤ** - ਹਰ ਬੇਨਤੀ ਵਿੱਚ ਗੱਲਬਾਤ ਦਾ ਇਤਿਹਾਸ ਸ਼ਾਮਲ ਹੁੰਦਾ ਹੈ। ਮਾਡਲ ਕਈ ਮੁੜ-ਮੁੜਲੇ ਬੋਲਚਾਲ 'ਚ ਸੰਦਰਭ ਨੂੰ ਬਰਕਰਾਰ ਰੱਖਦਾ ਹੈ। ਇਹ ਉਹ ਹੈ ਜੋ ਉਤਪਾਦਨ ਐਪਲੀਕੇਸ਼ਨਾਂ ਲਈ ਜ਼ਰੂਰੀ ਹੁੰਦਾ ਹੈ। +**ਸਟੇਟਫੁਲ ਗੱਲਬਾਤ** - ਹਰ ਬੇਨਤੀ ਵਿੱਚ ਗੱਲਬਾਤ ਇਤਿਹਾਸ ਸ਼ਾਮਿਲ ਹੁੰਦੀ ਹੈ। ਮਾਡਲ ਕਈ ਬਾਰ ਦੀ ਗੱਲਬਾਤ ਦਾ ਸੰਦਰਭ ਨਿਭਾਂਦਾ ਹੈ। ਇਹ ਉਹ ਹੈ ਜੋ ਪ੍ਰੋਡਕਸ਼ਨ ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਚਾਹੀਦਾ ਹੈ। -## ਪੂਰਵ ਸ਼ਰਤਾਂ +## ਪੂਰਵਾਪੇਸ਼ਾ -- Azure ਸਬਸਕ੍ਰਿਪਸ਼ਨ ਜਿਸ ਵਿੱਚ Azure OpenAI ਦੀ ਪਹੁੰਚ ਹੋਵੇ -- ਜਾਵਾ 21, Maven 3.9+ +- Azure ਦੀ ਸਬਸਕ੍ਰਿਪਸ਼ਨ ਜਿਸਦੇ ਨਾਲ Azure OpenAI ਐਕਸੈਸ ਹੋਵੇ +- ਜਾਵਾ 21, ਮਾਵਨ 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **ਨੋਟ:** ਜਾਵਾ, Maven, Azure CLI ਅਤੇ Azure Developer CLI (azd) ਪ੍ਰਦਾਨ ਕੀਤੇ ਗਏ devcontainer ਵਿੱਚ ਪਹਿਲਾਂ ਹੀ ਇੰਸਟਾਲ ਹਨ। +> **ਨੋਟ:** ਜਾਵਾ, ਮਾਵਨ, Azure CLI ਅਤੇ Azure Developer CLI (azd) ਪਹਿਲਾਂ ਹੀ ਦਿੱਤੇ ਗਏ devcontainer ਵਿੱਚ ਇੰਸਟਾਲ ਹਨ। -> **ਨੋਟ:** ਇਹ ਮੋਡੀਊਲ Azure OpenAI ਦੇ GPT-5.2 ਨੂੰ ਵਰਤਦਾ ਹੈ। `azd up` ਰਾਹੀਂ ਤੈਨਾਤ ਕੀਤਾ ਗਿਆ ਹੈ — ਕੋਡ ਵਿੱਚ ਮਾਡਲ ਦਾ ਨਾਮ ਬਦਲੋ ਨਾ। +> **ਨੋਟ:** ਇਹ ਮੋਡੀਊਲ Azure OpenAI ਤੇ GPT-5.2 ਵਰਤਦਾ ਹੈ। ਡਿਪਲੋਇਮੈਂਟ `azd up` ਰਾਹੀਂ ਆਪਣੇ ਆਪ ਸੰਰਚਿਤ ਹੁੰਦਾ ਹੈ - ਕੋਡ ਵਿੱਚ ਮਾਡਲ ਨਾਮ ਨੂੰ ਬਦਲੋ ਨਾ। ## ਮੁੱਖ ਸਮੱਸਿਆ ਨੂੰ ਸਮਝਣਾ -ਭਾਸ਼ਾ ਮਾਡਲ ਸਟੇਟਲੈੱਸ ਹਨ। ਹਰ API ਕਾਲ ਸਵਤੰਤਰ ਹੁੰਦੀ ਹੈ। ਜੇ ਤੁਸੀਂ ਕਹਿੰਦੇ ਹੋ "ਮੇਰਾ ਨਾਮ ਜॉन ਹੈ" ਅਤੇ ਫਿਰ ਪੁੱਛਦੇ ਹੋ "ਮੇਰਾ ਨਾਮ ਕੀ ਹੈ?", ਮਾਡਲ ਨੂੰ ਕੋਈ ਖਿਆਲ ਨਹੀਂ ਹੁੰਦਾ ਕਿ ਤੁਸੀਂ ਹੁਣੇ ਆਪਣਾ ਪਰਚਯ ਦਿਨਾਇਆ ਹੈ। ਇਹ ਹਰ ਬੇਨਤੀ ਨੂੰ ਪਹਿਲੀ ਗੱਲਬਾਤ ਵਾਂਗ ਲੈਂਦਾ ਹੈ ਜੋ ਤੁਸੀਂ ਕਦੇ ਕੀਤੀ ਹੈ। +ਭਾਸ਼ਾ ਮਾਡਲ ਸਟੇਟਲੈੱਸ ਹੁੰਦੇ ਹਨ। ਹਰ API ਕਾਲ ਅਜ਼ਾਦ ਹੁੰਦੀ ਹੈ। ਜੇ ਤੁਸੀਂ "ਮੇਰਾ ਨਾਮ ਜੌਨ ਹੈ" ਭੇਜਦੇ ਹੋ ਅਤੇ ਤਦ ਪੁੱਛਦੇ ਹੋ "ਮੇਰਾ ਨਾਮ ਕੀ ਹੈ?", ਮਾਡਲ ਨੂੰ ਇਸ ਦੀ ਜਾਣਕਾਰੀ ਨਹੀਂ ਹੁੰਦੀ ਕਿ ਤੁਸੀਂ ਆਪਣੇ ਆਪ ਨੂੰ ਪਹਿਲਾਂ ਹੀ ਪਹਚਾਣ ਕਰਵਾਇਆ ਹੈ। ਇਹ ਹਰ ਬੇਨਤੀ ਨੂੰ ਪਹਿਲੀ ਵਾਰ ਦੀ ਗੱਲਬਾਤ ਵਾਂਗੁ ਲੈਂਦਾ ਹੈ। -ਸਧਾਰਨ ਪ੍ਰਸ਼ਨ-ਉੱਤਰ ਲਈ ਇਹ ਠੀਕ ਹੈ ਪਰ ਅਸਲੀ ਐਪਲੀਕੇਸ਼ਨਾਂ ਲਈ ਬੇਕਾਰ। ਗਾਹਕ ਸੇਵਾ ਬੋਟਾਂ ਨੂੰ ਉਹ ਯਾਦ ਰੱਖਣਾ ਪੈਂਦਾ ਹੈ ਜੋ ਤੁਸੀਂ ਦੱਸਿਆ। ਨਿੱਜੀ ਸਹਾਇਕਾਂ ਨੂੰ ਸੰਦਰਭ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ। ਕਿਸੇ ਵੀ ਬਹੁ-ਝੁੜੀ ਗੱਲਬਾਤ ਲਈ ਮੈਮੋਰੀ ਜ਼ਰੂਰੀ ਹੈ। +ਸਧਾਰਣ ਸਵਾਲ-ਜਵਾਬ ਲਈ ਇਹ ਠੀਕ ਹੈ ਪਰ ਵਾਸਤਵਿਕ ਐਪਲੀਕੇਸ਼ਨਾਂ ਲਈ ਬੇਕਾਰ ਹੈ। ਗ੍ਰਾਹਕ ਸੇਵਾ ਬੋਟਾਂ ਨੂੰ ਇਹ ਯਾਦ ਰਹਿਣਾ ਚਾਹੀਦਾ ਹੈ ਕਿ ਤੁਸੀਂ ਕੀ ਦੱਸਿਆ ਹੈ। ਨਿੱਜੀ ਸਹਾਇਕਾਂ ਨੂੰ ਸੰਦਰਭ ਚਾਹੀਦਾ ਹੈ। ਕਈ ਵਾਰੀ ਦੀ ਗੱਲਬਾਤ ਲਈ ਮੈਮੋਰੀ ਲਾਜ਼ਮੀ ਹੈ। -ਹੇਠਾਂ ਦਿੱਤਾ ਚਿੱਤਰ ਦੋਹਾਂ ਤਰੀਕਿਆਂ ਵਿੱਚ ਫਰਕ ਦਿਖਾਉਂਦਾ ਹੈ — ਖੱਬੇ ਪਾਸੇ ਇੱਕ ਸਟੇਟਲੈੱਸ ਕਾਲ ਜੋ ਤੁਹਾਡਾ ਨਾਮ ਭੁੱਲ ਜਾਂਦਾ ਹੈ; ਸੱਜੇ ਪਾਸੇ ਇੱਕ ਸਟੇਟਫੁਲ ਕਾਲ ਜੋ ChatMemory ਨਾਲ ਸਮਰਥਿਤ ਹੈ ਅਤੇ ਨਾਮ ਯਾਦ ਰੱਖਦਾ ਹੈ। +ਹੇਠਾਂ ਦਿੱਤੇ ਚਿੱਤਰ ਵਿੱਚ ਦੋ ਤਰੀਕਿਆਂ ਦਾ ਤੱਪੜ ਕੀਤੀ ਗਈ ਹੈ — ਖੱਬੇ ਪਾਸੇ ਸਟੇਟਲੈੱਸ ਕਾਲ ਜੋ ਤੁਹਾਡਾ ਨਾਮ ਭੁੱਲ ਜਾਂਦਾ ਹੈ; ਸੱਜੇ ਪਾਸੇ ਸਟੇਟਫੁਲ ਕਾਲ ਜੋ ChatMemory ਨਾਲ ਸਮਰਥਿਤ ਹੈ ਅਤੇ ਨਾਮ ਯਾਦ ਰੱਖਦਾ ਹੈ। -ਬਿਨਾਂ ਸਟੇਟ ਵਰਕਾਬਲ (ਸਵਤੰਤਰ ਕਾਲਾਂ) ਅਤੇ ਸਟੇਟਵਾਲ (ਸੰਦਰਭ-ਜਾਣੂ) ਗੱਲਬਾਤਾਂ ਦਾ ਤਫਾਵਤ +ਸਟੇਟਲੈੱਸ ਵਿਰੁੱਧ ਸਟੇਟਫੁਲ ਗੱਲਬਾਤ -*ਬਿਨਾਂ ਸਟੇਟ (ਸਵਤੰਤਰ ਕਾਲਾਂ) ਅਤੇ ਸਟੇਟਫੁਲ (ਸੰਦਰਭ-ਜਾਣੂੰ) ਗੱਲਬਾਤਾਂ ਵਿਚਕਾਰ ਫਰਕ* +*ਸਟੇਟਲੈੱਸ (ਸਵਤੰਤਰ ਕਾਲ) ਅਤੇ ਸਟੇਟਫੁਲ (ਸੰਦਰਭ-ਜਾਣੂ) ਗੱਲਬਾਤਾਂ ਵਿੱਚ ਫਰਕ* -## ਟੋਕਨਸ ਨੂੰ ਸਮਝਣਾ +## ਟੋਕਨ ਨੂੰ ਸਮਝਣਾ -ਗੱਲਬਾਤਾਂ ਵਿੱਚ ਦਾਖਲ ਹੋਣ ਤੋਂ ਪਹਿਲਾਂ, ਇਹ ਸਮਝਣਾ ਜ਼ਰੂਰੀ ਹੈ ਕਿ ਟੋਕਨ ਕੀ ਹੁੰਦੇ ਹਨ - ਉਹ ਮੂਲ ਇਕਾਈਆਂ ਜਿਹੜੀਆਂ ਭਾਸ਼ਾ ਮਾਡਲ ਪ੍ਰੋਸੈਸ ਕਰਦੇ ਹਨ: +ਗੱਲਬਾਤ ਵਿੱਚ ਡੁਬਕੀ ਲਗਾਉਣ ਤੋਂ ਪਹਿਲਾਂ ਟੋਕਨਾਂ ਨੂੰ ਸਮਝਣਾ ਜ਼ਰੂਰੀ ਹੈ — ਉਹ ਮੂਲ ਇਕਾਈਆਂ ਜਿਨ੍ਹਾਂ ਨੂੰ ਭਾਸ਼ਾ ਮਾਡਲ ਪ੍ਰਕਿਰਿਆ ਕਰਦੇ ਹਨ: -ਟੋਕਨ ਦੀ ਵਿਆਖਿਆ +ਟੋਕਨ ਵਿਆਖਿਆ -*ਉਦਾਹਰਨ ਕਿ ਕਿਵੇਂ ਪਾਠ ਟੋਕਨ ਸਮੂਹਾਂ ਵਿੱਚ ਵੰਡਿਆ ਜਾਂਦਾ ਹੈ - "I love AI!" ਚਾਰ ਵੱਖ-ਵੱਖ ਪ੍ਰੋਸੈਸਿੰਗ ਇਕਾਈਆਂ ਬਣ ਜਾਂਦੀਆਂ ਹਨ* +*"I love AI!" - ਟੈਕਸਟ ਨੂੰ ਕਿਵੇਂ ਵਰਗ-ਵਰਗ ਟੋਕਨਾਂ ਵਿੱਚ ਤੋੜਿਆ ਜਾਂਦਾ ਹੈ - 4 ਵੱਖਰੇ ਪ੍ਰਕਿਰਿਆ ਇਕਾਈਆਂ ਬਣਦੀਆਂ ਹਨ* -ਟੋਕਨਸ ਦੁਆਰਾ AI ਮਾਡਲ ਪਾਠ ਦੀ ਮਾਪ ਅਤੇ ਪ੍ਰਕਿਰਿਆ ਕਰਦੇ ਹਨ। ਸ਼ਬਦ, ਵਿਸ਼੍ਰਾਮ-ਚਿੰਨ੍ਹ ਅਤੇ ਖਾਲੀਆਂ ਜਗ੍ਹਾਂ ਭੀ ਟੋਕਨਸ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਤੁਹਾਡੇ ਮਾਡਲ ਦੀ ਕੁੱਲ ਪ੍ਰਕਿਰਿਆ ਯੋਗਤਾ ਸੀਮਿਤ ਹੈ (GPT-5.2 ਲਈ 400,000 ਟੋਕਨ, ਜਿਸ ਵਿੱਚ 272,000 ਇਨਪੁਟ ਅਤੇ 128,000 ਆਉਟਪੁਟ ਟੋਕਨ ਹੋ ਸਕਦੇ ਹਨ)। ਟੋਕਨਸ ਨੂੰ ਸਮਝਣਾ ਗੱਲਬਾਤ ਦੀ ਲੰਬਾਈ ਅਤੇ ਲਾਗਤਾਂ ਨੂੰ ਸੰਭਾਲਣ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ। +ਟੋਕਨ AI ਮਾਡਲ ਟੈਕਸਟ ਨੂੰ ਅੰਦਰੂਨੀ ਤੌਰ ’ਤੇ ਮਾਪਦੇ ਅਤੇ ਪ੍ਰਕਿਰਿਆ ਕਰਦੇ ਹਨ। ਸ਼ਬਦ, ਅੰਤਰਵਿਰਾਮ ਅਤੇ ਖਾਲੀ ਥਾਵਾਂ ਵੀ ਟੋਕਨ ਹਨ। ਤੁਹਾਡੇ ਮਾਡਲ ਦੀ ਸੀਮਾ ਹੁੰਦੀ ਹੈ ਕਿ ਕਿੰਨੇ ਟੋਕਨ ਇੱਕ ਵਾਰ ਵਿੱਚ ਪ੍ਰਕਿਰਿਆ ਕਰ ਸਕਦਾ ਹੈ (GPT-5.2 ਲਈ 400,000 ਟੋਕਨ, ਜਿਸ ਵਿੱਚ 272,000 ਇਨਪੁੱਟ ਅਤੇ 128,000 ਆਉਟਪੁੱਟ ਟੋਅਕਨ ਸ਼ਾਮਿਲ ਹਨ)। ਟੋਕਨਾਂ ਦੀ ਸਮਝ ਗੱਲਬਾਤ ਦੀ ਲੰਬਾਈ ਅਤੇ ਲਾਗਤ ਨੂੰ ਚੰਗੀ ਤਰ੍ਹਾਂ ਪ੍ਰਬੰਧਿਤ ਕਰਨ ਵਿੱਚ ਮਦਦ ਕਰਦੀ ਹੈ। ## ਮੈਮੋਰੀ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ -ਚੈਟ ਮੈਮੋਰੀ ਸਟੇਟਲੈੱਸ ਸਮੱਸਿਆ ਨੂੰ ਇਸ ਤਰੀਕੇ ਨਾਲ حل ਕਰਦਾ ਹੈ ਕਿ ਗੱਲਬਾਤ ਦੇ ਇਤਿਹਾਸ ਨੂੰ ਬਰਕਰਾਰ ਰੱਖਦਾ ਹੈ। ਤੁਹਾਡੀ ਬੇਨਤੀ ਮਾਡਲ ਨੂੰ ਭੇਜਣ ਤੋਂ ਪਹਿਲਾਂ, ਫਰੇਮਵਰਕ ਸਬੰਧਿਤ ਪਿਛਲੇ ਸੁਨੇਹਿਆਂ ਨੂੰ ਜੋੜਦਾ ਹੈ। ਜਦੋਂ ਤੁਸੀਂ ਪੁੱਛਦੇ ਹੋ "ਮੇਰਾ ਨਾਮ ਕੀ ਹੈ?", ਸਿਸਟਮ ਅਸਲ ਵਿੱਚ ਪੂਰੀ ਗੱਲਬਾਤ ਦਾ ਇਤਿਹਾਸ ਭੇਜਦਾ ਹੈ, ਜਿਸ ਨਾਲ ਮਾਡਲ ਨੂੰ ਪਤਾ ਲੱਗਦਾ ਹੈ ਕਿ ਤੁਸੀਂ ਪਹਿਲਾਂ "ਮੇਰਾ ਨਾਮ ਜੋਂ ਹੈ" ਕਿਹਾ ਸੀ। +ਚੈਟ ਮੈਮੋਰੀ ਸਟੇਟਲੈੱਸ ਸਮੱਸਿਆ ਨੂੰ ਗੱਲਬਾਤ ਇਤਿਹਾਸ ਨੂੰ ਸਾਂਭ ਕੇ ਹੱਲ ਕਰਦੀ ਹੈ। ਮਾਡਲ ਨੂੰ ਤੁਸੀਂ ਆਪਣੀ ਬੇਨਤੀ ਭੇਜਣ ਤੋਂ ਪਹਿਲਾਂ, ਫਰੇਮਵਰਕ ਸੰਬੰਧਿਤ ਪਿਛਲੇ ਸੁਨੇਹਿਆਂ ਨੂੰ ਜੋੜ ਦਿੰਦਾ ਹੈ। ਜਦੋਂ ਤੁਸੀਂ "ਮੇਰਾ ਨਾਮ ਕੀ ਹੈ?" ਪੁੱਛਦੇ ਹੋ, ਤੁਹਾਡੀ ਗੱਲਬਾਤ ਦਾ ਸਾਰਾ ਇਤਿਹਾਸ ਭੇਜਿਆ ਜਾਂਦਾ ਹੈ, ਇਸ ਨਾਲ ਮਾਡਲ ਵੇਖ ਸਕਦਾ ਹੈ ਕਿ ਤੁਸੀਂ ਪਹਿਲਾਂ "ਮੇਰਾ ਨਾਮ ਜੌਨ ਹੈ" ਕਿਹਾ ਸੀ। -LangChain4j ਮੈਮੋਰੀ ਦੇ ਅਮਲ ਸ਼ੁਦ ਕਰਨ ਵਾਲੀਆਂ ਵਰਜਨਾਂ ਮੁਹੱਈਆ ਕਰਵਾਉਂਦਾ ਹੈ ਜੋ ਇਹ ਆਟੋਮੈਟਿਕ ਕਰਦੇ ਹਨ। ਤੁਸੀਂ ਨਿਰਧਾਰਤ ਕਰਦੇ ਹੋ ਕਿ ਕਿੰਨੇ ਸੁਨੇਹੇ ਰੱਖਣੇ ਹਨ ਅਤੇ ਫਰੇਮਵਰਕ ਸੰਦਰਭ ਵਿੰਡੋ ਦਾ ਪ੍ਰਬੰਧ ਕਰਦਾ ਹੈ। ਹੇਠਾਂ ਦਿੱਤੇ ਚਿੱਤਰ ਵਿੱਚ MessageWindowChatMemory ਤਾਜ਼ਾ ਸੁਨੇਹਿਆਂ ਦੀ ਸਲਾਈਡਿੰਗ ਵਿੰਡੋ ਕਿਵੇਂ ਰੱਖਦੀ ਹੈ, ਇਹ ਦਿਖਾਇਆ ਗਿਆ ਹੈ। +LangChain4j ਇਸ ਲਈ ਮੈਮੋਰੀ ਕੀਮਤਵਾਨ ਇੰਪਲੀਮੈਂਟੇਸ਼ਨਾਂ ਦਿੰਦਾ ਹੈ ਕਿ ਜੋ ਇਹ ਸਾਰਾ ਕੰਮ ਆਪਣੇ ਆਪ ਸਾਂਭਦਾ ਹੈ। ਤੁਸੀਂ ਫੈਸਲਾ ਕਰਦੇ ਹੋ ਕਿ ਕਿੰਨੇ ਸੁਨੇਹੇ ਰੱਖਣ ਹੈ ਅਤੇ ਫਰੇਮਵਰਕ ਸੰਦਰਭ ਵਿੰਡੋ ਨਿਭਾਉਂਦਾ ਹੈ। ਹੇਠਾਂ ਦਿੱਤੇ ਚਿੱਤਰ ਵਿੱਚ MessageWindowChatMemory ਕਿਵੇਂ ਇੱਕ ਸਲਾਈਡਿੰਗ ਵਿੰਡੋ ਚਲਾਉਂਦਾ ਹੈ ਜੋ ਹਾਲੀਆ ਸੁਨੇਹਿਆਂ ਨੂੰ ਰੱਖਦਾ ਹੈ। -ਮੈਮੋਰੀ ਵਿੰਡੋ ਧਾਰਣਾ +ਮੈਮੋਰੀ ਵਿੰਡੋ ਸੰਕਲਪ -*MessageWindowChatMemory ਇਤਿਹਾਸਿਕ ਸੁਨੇਹਿਆਂ ਦੀ ਇੱਕ ਸਲਾਈਡਿੰਗ ਵਿੰਡੋ ਸੰਭਾਲਦਾ ਹੈ, ਆਟੋਮੈਟਿਕ ਤੌਰ 'ਤੇ ਪੁਰਾਣੇ ਸੁਨੇਹੇ ਹਟਾ ਦਿੰਦਾ ਹੈ* +*MessageWindowChatMemory ਹਾਲੀਆ ਸੁਨੇਹਿਆਂ ਲਈ ਇੱਕ ਸਲਾਈਡਿੰਗ ਵਿੰਡੋ ਭਾਲ ਕੇ ਪੁਰਾਣੇ ਸੁਨੇਹੇ ਆਪਣੇ ਆਪ ਹਟਾਉਂਦਾ ਹੈ* -## ਇਹ LangChain4j ਨੂੰ ਕਿਵੇਂ ਵਰਤਦਾ ਹੈ +## ਇਹ LangChain4j ਕਿਵੇਂ ਵਰਤੀ ਜਾਂਦੀ ਹੈ -ਇਹ ਮੋਡੀਊਲ ਕਵਿਕ ਸਟਾਰਟ ਨੂੰ ਫੈਲਾਉਂਦਾ ਹੈ ਸਪ੍ਰਿੰਗ ਬੂਟ ਨਾਲ ਇੰਟਿਗ੍ਰੇਸ਼ਨ ਅਤੇ ਗੱਲਬਾਤ ਮੈਮੋਰੀ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ। ਹੇਠਾਂ ਹਿੱਸਿਆਂ ਦੀ ਮਿਲੌਤ ਦਰਸਾਈ ਗਈ ਹੈ: +ਇਹ ਮੋਡੀਊਲ Spring Boot ਨਾਲ ਜੁੜਦਾ ਹੈ ਅਤੇ ਗੱਲਬਾਤ ਮੈਮੋਰੀ ਸ਼ਾਮਿਲ ਕਰਦਾ ਹੈ। ਇਹ ਹੈ ਕਿ ਹਿੱਸੇ ਕਿਵੇਂ ਇੱਕਠੇ ਕੰਮ ਕਰਦੇ ਹਨ: -**ਨਿਰਭਰਤਾਵਾਂ** - ਦੋ LangChain4j ਲਾਇਬ੍ਰੇਰੀਆਂ ਸ਼ਾਮਲ ਕਰੋ: +**ਡਿਪੈਂਡੈਂਸੀਜ਼** - ਦੋ LangChain4j ਲਾਇਬ੍ਰੇਰੀਆਂ ਸ਼ਾਮਲ ਕਰੋ: ```xml @@ -94,7 +94,7 @@ LangChain4j ਮੈਮੋਰੀ ਦੇ ਅਮਲ ਸ਼ੁਦ ਕਰਨ ਵਾਲ ``` -**ਚੈਟ ਮਾਡਲ** - Azure OpenAI ਨੂੰ ਸਪ੍ਰਿੰਗ ਬੀਨ ਵਜੋਂ ਕਾਂਫਿਗਰ ਕਰੋ ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**ਚੈਟ ਮਾਡਲ** - Azure OpenAI ਨੂੰ ਇੱਕ Spring ਬੀਨ ਵਜੋਂ ਸੰਰਚਿਤ ਕਰੋ ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -ਬਿਲਡਰ `azd up` ਦੁਆਰਾ ਸੈੱਟ ਕੀਤੀਆਂ ਵਾਤਾਵਰਣ ਚਲ 변수 ਤੋਂ ਕ੍ਰੈਡੈਂਸ਼ਲ ਲੈਂਦਾ ਹੈ। `baseUrl` ਤੁਹਾਡੇ Azure ਐਂਡਪਾਇੰਟ ਨੂੰ ਸੈੱਟ ਕਰਕੇ OpenAI ਕਲੀਏਂਟ Azure OpenAI ਨਾਲ ਕੰਮ ਕਰਦਾ ਹੈ। +ਬਿਲਡਰ ਕਰੋੜਲੀਆਂ ਨੂੰ `azd up` ਰਾਹੀਂ ਸੈੱਟ ਕੀਤੀਆਂ ਵਾਤਾਵਰਣ ਵੈਰੀਏਬਲਾਂ ਤੋਂ ਪੜ੍ਹਦਾ ਹੈ। ਤੁਹਾਡੇ Azure ਐਂਡਪੌਇੰਟ ਨੂੰ `baseUrl` ਦੇ ਕੇ OpenAI ਕਲਾਇੰਟ ਨੂੰ Azure OpenAI ਨਾਲ ਕੰਮ ਕਰਨ ਦੇ ਯੋਗ ਬਣਾਓ। **ਗੱਲਬਾਤ ਮੈਮੋਰੀ** - MessageWindowChatMemory ਨਾਲ ਗੱਲਬਾਤ ਇਤਿਹਾਸ ਟਰੈਕ ਕਰੋ ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,205 +124,199 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` ਨਾਲ ਮੈਮੋਰੀ ਬਣਾਓ ਤਾਂ ਕਿ ਆਖਰੀ 10 ਸੁਨੇਹੇ ਰੱਖੇ ਜਾ ਸਕਣ। ਯੂਜ਼ਰ ਅਤੇ AI ਸੁਨੇਹੇ ਕਈਪੜਤਾਲ ਵਾਲੇ ਰੈਪਰਜ਼ ਨਾਲ ਜੋੜੋ: `UserMessage.from(text)` ਅਤੇ `AiMessage.from(text)`. ਮੈਮੋਰੀ ਦੀ ਬੇਨਤੀ `memory.messages()` ਨਾਲ ਕਰੋ ਅਤੇ ਮਾਡਲ ਨੂੰ ਭੇਜੋ। ਸੇਵਾ ਹਰ ਗੱਲਬਾਤ ID ਲਈ ਵੱਖਰੀਆਂ ਮੈਮੋਰੀਆਂ ਰੱਖਦੀ ਹੈ, ਜਿਸ ਨਾਲ ਕਈ ਯੂਜ਼ਰ ਇਕੱਠੇ ਗੱਲਬਾਤ ਕਰ ਸਕਦੇ ਹਨ। +ਮੈਮੋਰੀ ਬਣਾਓ `withMaxMessages(10)` ਨਾਲ ਜੋ ਆਖਰੀ 10 ਸੁਨੇਹਿਆਂ ਨੂੰ ਰੱਖੇ। ਯੂਜ਼ਰ ਅਤੇ AI ਸੁਨੇਹੇ ਜਿਵੇਂ `UserMessage.from(text)` ਅਤੇ `AiMessage.from(text)` ਨਾਲ ਜੋੜੋ। ਇਤਿਹਾਸ ਪ੍ਰਾਪਤ ਕਰਨ ਲਈ `memory.messages()` ਦੀ ਵਰਤੋਂ ਕਰੋ ਅਤੇ ਇਸਨੂੰ ਮਾਡਲ ਨੂੰ ਭੇਜੋ। ਸਰਵਿਸ ਹਰ ਗੱਲਬਾਤ ID ਲਈ ਵੱਖਰੀ ਮੈਮੋਰੀ ਸੰਭਾਲਦੀ ਹੈ, ਜਿਸ ਨਾਲ ਕਈ ਯੂਜ਼ਰਾਂ ਇੱਕੋ ਸਮੇਂ ਗੱਲਬਾਤ ਕਰ ਸਕਦੇ ਹਨ। -> **🤖 GitHub Copilot ਚੈਟ ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "MessageWindowChatMemory ਕਿਵੇਂ ਤੈਅ ਕਰਦਾ ਹੈ ਕਿ ਵਿੰਡੋ ਭਰ ਜਾਣ 'ਤੇ ਕਿਹੜੇ ਸੁਨੇਹੇ ਡ੍ਰਾਪ ਕਰਨੇ ਹਨ?" -> - "ਕੀ ਮੈਂ ਇਨ-ਮੇਮੋਰੀ ਦੀ ਥਾਂ ਡੈਟਾਬੇਸ ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਆਪਣੇ ਮੈਮੋਰੀ ਸਟੋਰੇਜ ਨੂੰ ਲਾਗੂ ਕਰ ਸਕਦਾ ਹਾਂ?" -> - "ਪੁਰਾਣੇ ਗੱਲਬਾਤ ਇਤਿਹਾਸ ਨੂੰ ਸੰਖੇਪ ਕਰਨ ਲਈ ਕਿੱਕਰੇ ਵਾਲਾ ਸੰਖੇਪ ਸ਼ਾਮਲ ਕਿਵੇਂ ਕਰਾਂ?" +> **🤖 GitHub Copilot ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: +> - "MessageWindowChatMemory ਪੂਰੀ ਵਿੰਡੋ ਹੋਣ 'ਤੇ ਕਿਹੜੇ ਸੁਨੇਹੇ ਹਟਾਉਂਦਾ ਹੈ?" +> - "ਕੀ ਮੈਂ ਮੈਮੋਰੀ ਨੂੰ ਇਨ-ਮੈਮੋਰੀ ਦੀ ਥਾਂ ਡੇਟਾਬੇਸ ਵਰਤ ਕੇ ਸਟੋਰ ਕਰ ਸਕਦਾ ਹਾਂ?" +> - "ਪੁਰਾਣੇ ਗੱਲਬਾਤ ਇਤਿਹਾਸ ਦੀ ਸੰਘਣੀ ਕਰਨ ਲਈ ਕਿਵੇਂ ਸਮਰੀ ਬਣਾਈ ਜਾਵੇ?" -ਬਿਨਾਂ ਸਟੇਟ ਵਾਲਾ ਚੈਟ ਐਂਡਪਾਇੰਟ ਪੂਰੀ ਤਰ੍ਹਾਂ ਮੈਮੋਰੀ ਨੂੰ ਛੱਡ ਦਿੰਦਾ ਹੈ - ਸਿਰਫ਼ `chatModel.chat(prompt)` ਜਿਵੇਂ ਕਿ ਕਵਿਕ ਸਟਾਰਟ ਵਿੱਚ ਸੀ। ਸਟੇਟਫੁਲ ਐਂਡਪਾਇੰਟ ਸੁਨੇਹੇ ਮੈਮੋਰੀ ਵਿੱਚ ਜੋੜਦਾ ਹੈ, ਇਤਿਹਾਸ ਲੈਂਦਾ ਹੈ, ਅਤੇ ਹਰ ਬੇਨਤੀ ਨਾਲ ਉਹ ਸੰਦਰਭ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ। ਵਿਭਿੰਨ ਮਾਡਲ ਵਿਵਸਥਾ, ਭਿੰਨ ਪੈਟਰਨ। +ਸਟੇਟਲੈੱਸ ਚੈਟ ਐਂਡਪੌਇੰਟ ਮੈਮੋਰੀ ਨੂੰ ਪੂਰੀ ਤਰ੍ਹਾਂ ਛੱਡ ਦਿੰਦਾ ਹੈ - ਸਿਰਫ `chatModel.chat(prompt)` ਜਿਵੇਂ ਕਿ ਕਿਕ-ਸਟਾਰਟ। ਸਟੇਟਫੁਲ ਐਂਡਪੌਇੰਟ ਗੱਲਬਾਤ ਸੁਨੇਹਿਆਂ ਨੂੰ ਮੈਮੋਰੀ ਵਿੱਚ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ, ਇਤਿਹਾਸ ਨੂੰ ਲੈ ਕੇ ਆਉਂਦਾ ਹੈ ਅਤੇ ਹਰ ਬੇਨਤੀ ਨਾਲ ਉਹ ਸੰਦਰਭ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ। ਇੱਕੋ ਮਾਡਲ ਸੰਰਚਨਾ, ਵੱਖ-ਵੱਖ ਪੈਟਰਨ। -## Azure OpenAI ਢਾਂਚਾ ਤਿਆਰ ਕਰੋ +## Azure OpenAI ਇੰਫ੍ਰਾਸਟ੍ਰੱਕਚਰ ਨਿਯੁਕਤ ਕਰੋ -**ਬੈਸ਼:** +**Bash:** ```bash cd 01-introduction -azd up # ਸਬਸਕ੍ਰਿਪਸ਼ਨ ਅਤੇ ਸਥਾਨ ਚੁਣੋ (eastus2 ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ) +azd up # ਸਬਸਕ੍ਰਿਪਸ਼ਨ ਅਤੇ ਸਥਾਨ ਚੁਣੋ (eastus2 ਸੋਝੀ ਹੋਈ) ``` -**ਪਾਵਰਸ਼ੈਲ:** +**PowerShell:** ```powershell cd 01-introduction -azd up # ਸਬਸਕ੍ਰਿਪਸ਼ਨ ਅਤੇ ਸਥਾਨ ਚੁਣੋ (eastus2 ਦੀ ਸਿਫਾਰਿਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ) +azd up # ਸਬਸਕ੍ਰਿਪਸ਼ਨ ਅਤੇ ਸਥਾਨ ਚੁਣੋ (eastus2 ਦੀ ਸਿਫਾਰਿਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ) ``` -> **ਨੋਟ:** ਜੇ ਤੁਹਾਨੂੰ timeout ਦੀ ਗਲਤੀ ਆਏ (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), ਤਾਂ ਸਿਰਫ `azd up` ਨੂੰ ਦੁਬਾਰਾ ਚਲਾਓ। ਫਿਰ ਵੀ ਬੈਕਗ੍ਰਾਊਂਡ ਵਿੱਚ Azure ਸਰੋਤ ਤਿਆਰ ਹੋ ਰਹੇ ਹੋ ਸਕਦੇ ਹਨ, ਅਤੇ ਦੁਬਾਰਾ ਕੋਸ਼ਿਸ਼ ਕਰਨ ਨਾਲ ਤੈਨਾਤ ਕਾਮਯਾਬ ਹੋ ਜਾਂਦੀ ਹੈ ਜਦੋਂ ਸਰੋਤ ਟਰਮੀਨਲ ਸਥਿਤੀ ਵਿੱਚ ਪਹੁੰਚਦੇ ਹਨ। +> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ timeout ਦੀ ਤਰੁੱਟੀ ਦਾ ਸਾਹਮਣਾ ਕਰੋ (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), ਤਾਂ ਸਿਰਫ ਦੁਬਾਰਾ `azd up` ਚਲਾਓ। Azure ਸਰਵਿਸਜ਼ ਪਿੱਛੋਂ ਪ੍ਰੋਵੀਜ਼ਨ ਹੋ ਰਹੇ ਹੋ ਸਕਦੇ ਹਨ, ਅਤੇ ਦੁਬਾਰਾ ਕੋਸ਼ਿਸ਼ ਕਰਨ ਨਾਲ ਡਿਪਲੋਇਮੈਂਟ ਪੂਰਾ ਹੋ ਜਾਵੇਗਾ ਜਦੋਂ ਸਰਵਿਸਜ਼ ਟਰਮੀਨਲ ਸਥਿਤੀ ’ਚ ਪਹੁੰਚਦੇ ਹਨ। -ਇਹ: -1. GPT-5.2 ਅਤੇ text-embedding-3-small ਮਾਡਲਾਂ ਨਾਲ Azure OpenAI ਸਰੋਤ ਤੈਨਾਤ ਕਰੇਗਾ -2. ਸਰੋਤ ਖੇੜਾ ਵਿੱਚ `.env` ਫਾਈਲ ਆਟੋਮੈਟਿਕ ਤੌਰ 'ਤੇ ਬਣਾਏਗਾ ਜਿਸ ਵਿੱਚ ਕ੍ਰੈਡੇਂਸ਼ਲ ਹਨ -3. ਸਾਰੇ ਲੋੜੀਂਦੇ ਵਾਤਾਵਰਣ ਚਲ ਬਦਲ ਨੂੰ ਸੈੱਟ ਕਰੇਗਾ +ਇਹ ਕਮਾਂਡ ਕਰੇਗਾ: +1. GPT-5.2 ਅਤੇ text-embedding-3-small ਮਾਡਲਾਂ ਨਾਲ Azure OpenAI ਸਰਵਿਸ ਨਿਯੁਕਤ ਕਰਨਾ +2. ਪ੍ਰੋਜੈਕਟ ਰੂਟ ਵਿੱਚ ਕ੍ਰੇਡੈਂਸ਼ੀਅਲਾਂ ਨਾਲ `.env` ਫਾਇਲ ਆਪਣੇ ਆਪ ਬਣਾਉਣਾ +3. ਸਾਰੇ ਜ਼ਰੂਰੀ ਵਾਤਾਵਰਨ ਵੈਰੀਏਬਲ ਸੈਟ ਕਰਨਾ -**ਤੈਨਾਤ ਕਰਨ ਵਿੱਚ ਸਮੱਸਿਆ?** ਮਿਸ਼ਨ-ਅਧਾਰਿਤ ਮੁੜਪੜਤਾਲ ਲਈ [Infrastructure README](infra/README.md) ਵੇਖੋ ਜਿਸ ਵਿੱਚ ਸਬਡੋਮੇਨ ਨਾਂ ਵਾਲੇ ਟੱਕਰ, ਮੈਨੂਅਲ Azure ਪੋਰਟਲ ਤੈਨਾਤ ਕਦਮ ਅਤੇ ਮਾਡਲ ਵਿਵਸਥਾ ਮਦਦ। +**ਡਿਪਲੋਇਮੈਂਟ ਵਿੱਚ ਸਮੱਸਿਆਵਾਂ?** [Infrastructure README](infra/README.md) ਵਿੱਚ ਵੇਰਵਾ ਜੋ ਕਿ ਸਬਡੋਮੇਨ ਨਾਮ ਟਕਰਾਅ, ਮੈਨੂਅਲ Azure Portal ਡਿਪਲੋਇਮੈਂਟ ਕਦਮ, ਅਤੇ ਮਾਡਲ ਸੰਰਚਨਾ ਗਾਈਡ ਨੂੰ ਸ਼ਾਮਿਲ ਕਰਦਾ ਹੈ। -**ਤੈਨਾਤ ਹੋਣ ਦੀ ਜਾਂਚ ਕਰੋ:** +**ਡਿਪਲੋਇਮੈਂਟ ਸਫਲਤਾ ਦੀ ਜਾਂਚ ਕਰੋ:** -**ਬੈਸ਼:** +**Bash:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, ਆਦਿ ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ। ``` -**ਪਾਵਰਸ਼ੈਲ:** +**PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, ਆਦਿ ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ। +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY ਆਦਿ ਦਿਖਾਏ ਜਾਣੇ ਚਾਹੀਦੇ ਹਨ। ``` -> **ਨੋਟ:** `azd up` ਕਮਾਂਡ `.env` ਫਾਈਲ ਨੂੰ ਆਟੋਮੈਟਿਕ ਬਣਾਉਂਦਾ ਹੈ। ਜੇ ਬਾਅਦ ਵਿੱਚ ਇਸਨੂੰ ਅੱਪਡੇਟ ਕਰਨਾ ਹੋਵੇ ਤਾਂ ਤੁਸੀਂ `.env` ਨੂੰ ਮੈਨੂਅਲੀ ਤੌਰ 'ਤੇ ਸੰਪਾਦਿਤ ਕਰ ਸਕਦੇ ਹੋ ਜਾਂ ਇਸਨੂੰ ਮੁੜ ਬਣਾਉਣ ਲਈ ਚਲਾ ਸਕਦੇ ਹੋ: +> **ਨੋਟ:** `azd up` ਕਮਾਂਡ ਆਪਣੇ-ਆਪ `.env` ਫਾਇਲ ਬਣਾਕੇ ਭੇਜਦਾ ਹੈ। ਜੇ ਤੁਹਾਨੂੰ ਇਸਨੂੰ ਬਾਅਦ ਵਿੱਚ ਅੱਪਡੇਟ ਕਰਨਾ ਹੋਵੇ, ਤਾਂ ਤਸੀਂ ਮੈਨੁਅਲੀ ਤੌਰ ਤੇ `.env` ਫਾਇਲ ਨੂੰ ਸੋਧ ਸਕਦੇ ਹੋ ਜਾਂ ਦੁਬਾਰਾ ਬਣਾਉਣ ਲਈ ਇਨ੍ਹਾਂ ਕਮਾਂਡਾਂ ਚਲਾ ਸਕਦੇ ਹੋ: > -> **ਬੈਸ਼:** +> **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` > -> **ਪਾਵਰਸ਼ੈਲ:** +> **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` +## ਐਪਲੀਕੇਸ਼ਨ ਨੂੰ ਲੋਕਲ ਰਣ ਕਰੋ -## ਐਪਲੀਕੇਸ਼ਨ ਨੂੰ ਲੋਕਲ ਚਲਾਓ +**ਡਿਪਲੋਇਮੈਂਟ ਦੀ ਜਾਂਚ ਕਰੋ:** -**ਤੈਨਾਤ ਹੋਣ ਦੀ ਜਾਂਚ ਕਰੋ:** +ਸुनਿਸ਼ਚਿਤ ਕਰੋ ਕਿ `.env` ਫਾਇਲ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ Azure ਕ੍ਰੇਡੈਂਸ਼ੀਅਲਾਂ ਨਾਲ ਮੌਜੂਦ ਹੈ। ਮੋਡੀਊਲ ਡਾਇਰੈਕਟਰੀ (`01-introduction/`) ਤੋਂ ਇਹ ਚਲਾਓ: -ਯਕੀਨੀ ਬਣਾਓ ਕਿ `.env` ਫਾਈਲ ਪ੍ਰੋਜੈਕਟ ਦੀ ਮੁਖ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ ਮੌਜੂਦ ਹੈ ਜਿਸ ਵਿੱਚ Azure ਕ੍ਰੈਡੈਂਸ਼ਲ ਹਨ। ਮੋਡੀਊਲ ਡਾਇਰੈਕਟਰੀ (`01-introduction/`) ਤੋਂ ਚਲਾਓ: - -**ਬੈਸ਼:** +**Bash:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ ``` -**ਪਾਵਰਸ਼ੈਲ:** +**PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦਿਖਾਇਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦੇਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ ``` +**ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਚਾਲੂ ਕਰੋ:** -**ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਸ਼ੁਰੂ ਕਰੋ:** - -**ਵਿਕਲਪ 1: ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਦੀ ਵਰਤੋਂ (VS ਕੋਡ ਵਾਲਿਆਂ ਲਈ ਸਿਫ਼ਾਰਸ਼)** +**ਵਿਕਲਪ 1: Spring Boot ਡੈਸ਼ਬੋਰਡ ਦੀ ਵਰਤੋਂ (VS Code ਵਰਤੋਂਕਾਰਾਂ ਲਈ ਸਿਫ਼ਾਰਸ਼ੀ)** -devcontainer ਵਿੱਚ Spring Boot Dashboard ਵਿਸਥਾਰ ਸ਼ਾਮਲ ਹੈ, ਜੋ ਸਾਰੇ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਵਿਜ਼ੂਅਲ ਤਰੀਕੇ ਨਾਲ ਮੈਨੇਜ ਕਰਨ ਲਈ ਏਕ ਇੰਟਰਫੇਸ ਦਿੰਦਾ ਹੈ। ਤੁਹਾਨੂੰ ਇਹ VS ਕੋਡ ਦੇ ਖੱਬੇ ਪਾਸੇ Activity Bar ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਅਈਕਨ ਦੇ ਨਾਲ ਮਿਲ ਜਾਵੇਗਾ। +devcontainer ਵਿੱਚ Spring Boot ਡੈਸ਼ਬੋਰਡ ਐਕਸਟੈਂਸ਼ਨ ਸ਼ਾਮਿਲ ਹੈ, ਜੋ ਸਾਰੇ Spring Boot ਐਪਲੀਕੇਸ਼ਨਾਂ ਦਾ ਵਿਜ਼ੂਅਲ ਇੰਟਰਫੇਸ ਦਿੰਦਾ ਹੈ। ਤੁਸੀਂ ਇਸਨੂੰ VS Code ਦੇ ਖੱਬੇ ਪਾਸੇ ਐਕਟੀਵਿਟੀ ਬਾਰ ਵਿੱਚ Spring Boot ਆਈਕਨ ਦੇ ਰੂਪ ਵਿੱਚ ਦੇਖ ਸਕਦੇ ਹੋ। -Spring Boot Dashboard ਤੋਂ ਤੁਹਾਨੂੰ ਮਿਲਦਾ ਹੈ: -- ਵਰਕਸਪੇਸ ਵਿੱਚ ਸਾਰੇ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨ ਵੇਖਣ ਦੇ ਯੋਗ -- ਸਿਰਫ ਇੱਕ ਕਲਿੱਕ ਨਾਲ ਐਪਲੀਕੇਸ਼ਨ ਸ਼ੁਰੂ/ਰੋਕੋ -- ਐਪਲੀਕੇਸ਼ਨ ਲੌਗਜ਼ ਨੂੰ ਰੀਅਲ-ਟਾਈਮ ਦੇਖੋ -- ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਸਥਿਤੀ ਮਾਨੀਟਰ ਕਰੋ +Spring Boot ਡੈਸ਼ਬੋਰਡ ਤੋਂ ਤੁਸੀਂ: +- ਵਰਕਸਪੇਸ ਵਿੱਚ ਸਾਰੇ ਉਪਲਬਧ Spring Boot ਐਪਲੀਕੇਸ਼ਨ ਵੇਖ ਸਕਦੇ ਹੋ +- ਇੱਕ ਕਲਿੱਕ ਨਾਲ ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਸ਼ੁਰੂ/ਰੋਕੇ +- ਰੀਅਲ-ਟਾਈਮ ਵਿੱਚ ਐਪਲੀਕੇਸ਼ਨ ਲੌਗਸ ਵੇਖੋ +- ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਸਥਿਤੀ ਦੀ ਨਿਗਰਾਨੀ ਕਰੋ -ਸਿਰਫ "introduction" ਦੇ ਬੱਜੂ ਵਿੱਚ ਪਲੇਅ ਬਟਨ 'ਤੇ ਕਲਿੱਕ ਕਰੋ ਇਸ ਮੋਡੀਊਲ ਨੂੰ ਸ਼ੁਰੂ ਕਰਨ ਲਈ, ਜਾਂ ਸਾਰੇ ਮੋਡੀਊਲਜ਼ ਇਕੱਠੇ ਸ਼ੁਰੂ ਕਰੋ। +ਸਿਰਫ਼ "introduction" ਦੇ ਨਾਲ ਖੇਡ ਬਟਨ ਤੇ ਕਲਿੱਕ ਕਰੋ ਜਾਂ ਸਾਰੇ ਮੋਡੀਊਲ ਇੱਕ ਵਾਰੀ ਚਾਲੂ ਕਰੋ। -ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ +Spring Boot ਡੈਸ਼ਬੋਰਡ -*VS ਕੋਡ ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ — ਸਭ ਮੋਡੀਊਲ ਇਕੱਠੇ ਸ਼ੁਰੂ, ਰੋਕੋ ਅਤੇ ਮਾਨੀਟਰ ਕਰੋ* +*VS Code ਵਿੱਚ Spring Boot ਡੈਸ਼ਬੋਰਡ — ਇੱਕ ਥਾਂ ਤੋਂ ਸਾਰੇ ਮੋਡੀਊਲ ਚਾਲੂ, ਰੋਕੋ, ਅਤੇ ਨਿਗਰਾਨੀ ਕਰੋ* -**ਵਿਕਲਪ 2: ਸ਼ੈੱਲ ਸਕ੍ਰਿਪਟ ਦੀ ਵਰਤੋਂ** +**ਵਿਕਲਪ 2: shell ਸਕ੍ਰਿਪਟ ਦੀ ਵਰਤੋਂ** -ਸਾਰੇ ਵੈੱਬ ਐਪਲੀਕੇਸ਼ਨ (ਮੋਡੀਊਲ 01-04) ਸ਼ੁਰੂ ਕਰੋ: +ਸਾਰੇ ਵੈੱਬ ਐਪਲੀਕੇਸ਼ਨਾਂ (ਮੋਡੀਊਲ 01-04) ਨੂੰ ਚਾਲੂ ਕਰੋ: -**ਬੈਸ਼:** +**Bash:** ```bash cd .. # ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ ./start-all.sh ``` -**ਪਾਵਰਸ਼ੈਲ:** +**PowerShell:** ```powershell -cd .. # ਮੂਲ ਡਾਇਰੇਕਟਰੀ ਤੋਂ +cd .. # ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ .\start-all.ps1 ``` +ਜਾਂ ਸਿਰਫ਼ ਇਹ ਮੋਡੀਊਲ ਚਾਲੂ ਕਰੋ: -ਯਾ ਸਿਰਫ ਇਹ ਮੋਡੀਊਲ ਸ਼ੁਰੂ ਕਰੋ: - -**ਬੈਸ਼:** +**Bash:** ```bash cd 01-introduction ./start.sh ``` -**ਪਾਵਰਸ਼ੈਲ:** +**PowerShell:** ```powershell cd 01-introduction .\start.ps1 ``` +ਦੋਹਾਂ ਸਕ੍ਰਿਪਟ ਆਪਣੇ ਆਪ ਰੂਟ `.env` ਫਾਇਲ ਤੋਂ ਵਾਤਾਵਰਨ ਵੈਰੀਏਬਲ ਲੋਡ ਕਰਦੇ ਹਨ ਅਤੇ ਜੇ JAR ਫਾਇਲਾਂ ਮੌਜੂਦ ਨਹੀਂ ਹਨ ਤਾਂ ਬਣਾਉਂਦੇ ਹਨ। -ਦੋਹਾਂ ਸਕ੍ਰਿਪਟਾਂ root `.env` ਫਾਈਲ ਤੋਂ ਵਾਤਾਵਰਣ ਚਲ ਬਦਲਾਂ ਨੂੰ ਆਟੋਮੈਟਿਕ ਲੋਡ ਕਰਦੀਆਂ ਹਨ ਅਤੇ ਜਰੂਰੀ ਹੋਣ 'ਤੇ JAR ਫਾਈਲਾਂ ਬਿਲਡ ਕਰਦੀਆਂ ਹਨ। - -> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਸ਼ੁਰੂ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਸਾਰੇ ਮੋਡੀਊਲਾਂ ਨੂੰ ਹੱਥੋਂ ਬਿਲਡ ਕਰਨਾ ਪਸੰਦ ਕਰਦੇ ਹੋ: +> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਸ਼ੁਰੂ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਸਾਰੇ ਮੋਡੀਊਲ ਹੱਥੋਂ-ਹੱਥ ਬਣਾਉਣਾ ਪਸੰਦ ਕਰਦੇ ਹੋ: > -> **ਬੈਸ਼:** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **ਪਾਵਰਸ਼ੈਲ:** +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -ਆਪਣੇ ਬ੍ਰਾਊਜ਼ਰ ਵਿੱਚ http://localhost:8080 ਖੋਲ੍ਹੋ। +ਆਪਣਾ ਬ੍ਰਾਉਜ਼ਰ ਵਿੱਚ http://localhost:8080 ਖੋਲ੍ਹੋ। **ਰੋਕਣ ਲਈ:** -**ਬੈਸ਼:** +**Bash:** ```bash -./stop.sh # ਇਹ ਮੌਡੀਊਲ ਸਿਰਫ +./stop.sh # ਇਹ ਸਿਰਫ ਮੋਡੀਊਲ # ਜਾਂ -cd .. && ./stop-all.sh # ਸਾਰੇ ਮੌਡੀਊਲ +cd .. && ./stop-all.sh # ਸਾਰੇ ਮੋਡੀਊਲ ``` -**ਪਾਵਰਸ਼ੈਲ:** +**PowerShell:** ```powershell -.\stop.ps1 # ਇਹ ਮੋਡੀਊਲ ਸਿਰਫ +.\stop.ps1 # ਇਹ ਮਾਡਿਊਲ ਹੀ # ਜਾਂ -cd ..; .\stop-all.ps1 # ਸਾਰੇ ਮੋਡੀਊਲ +cd ..; .\stop-all.ps1 # ਸਾਰੇ ਮਾਡਿਊਲ ``` - ## ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਵਰਤੋਂ -ਐਪਲੀਕੇਸ਼ਨ ਇੱਕ ਵੈੱਬ ਇੰਟਰਫੇਸ ਦਿੰਦਾ ਹੈ ਜਿਸ ਵਿੱਚ ਦੋ ਚੈਟ ਇੰਪਲੀਮੇੰਟੇਸ਼ਨ ਸਾਈਡ-ਬਾਈ-ਸਾਈਡ ਹਨ। +ਐਪਲੀਕੇਸ਼ਨ ਇੱਕ ਵੈੱਬ ਇੰਟਰਫੇਸ ਦਿੰਦਾ ਹੈ ਜਿਸ ਵਿੱਚ ਦੋ ਚੈਟ ਇੰਪਲੀਮੈਂਟੇਸ਼ਨ ਸਾਈਡ-ਬਾਈ-ਸਾਈਡ ਹਨ। -ਐਪਲੀਕੇਸ਼ਨ ਹੋਮ ਸਕਰੀਨ +ਐਪਲੀਕੇਸ਼ਨ ਦੇ ਘਰ ਸਕਰੀਨ -*ਡੈਸ਼ਬੋਰਡ ਜੋ ਸਧਾਰਨ ਚੈਟ (ਬਿਨਾਂ ਸਟੇਟ ਵਾਲਾ) ਅਤੇ ਗੱਲਬਾਤੀ ਚੈਟ (ਸਟੇਟਫੁਲ) ਵਿਕਲਪ ਦਿਖਾ ਰਿਹਾ ਹੈ* +*ਡੈਸ਼ਬੋਰਡ ਜਿਸ ਵਿੱਚ ਸਧਾਰਣ ਚੈਟ (ਸਟੇਟਲੈੱਸ) ਅਤੇ ਗੱਲਬਾਤੀ ਚੈਟ (ਸਟੇਟਫੁਲ) ਵਿਕਲਪ ਦਿਖਾਏ ਗਏ ਹਨ* -### ਬਿਨਾਂ ਸਟੇਟ ਵਾਲਾ ਚੈਟ (ਖੱਬਾ ਪੈਨਲ) +### ਸਟੇਟਲੈੱਸ ਚੈਟ (ਖੱਬਾ ਪੈਨਲ) -ਪਹਿਲਾਂ ਇਹਨਾਂ ਕੋਸ਼ਿਸ਼ ਕਰੋ। ਪੁੱਛੋ "ਮੇਰਾ ਨਾਮ ਜੌਨ ਹੈ" ਅਤੇ ਤੁਰੰਤ "ਮੇਰਾ ਨਾਮ ਕੀ ਹੈ?" ਮਾਡਲ ਮੈਮੋਰੀ ਨਾ ਹੋਣ ਕਰਕੇ ਯਾਦ ਨਹੀਂ ਕਰੇਗਾ। ਇਹ ਸਧਾਰਨ ਭਾਸ਼ਾ ਮਾਡਲ ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਦੀ ਮੁੱਖ ਸਮੱਸਿਆ ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ - ਕੋਈ ਗੱਲਬਾਤ ਸੰਦਰਭ ਨਹੀਂ। +ਸਭ ਤੋਂ ਪਹਿਲਾਂ ਇਹ ਕੋਸ਼ਿਸ਼ ਕਰੋ। ਪੁੱਛੋ "ਮੇਰਾ ਨਾਮ ਜੌਨ ਹੈ" ਅਤੇ ਫਿਰ ਤੁਰੰਤ ਪੁੱਛੋ "ਮੇਰਾ ਨਾਮ ਕੀ ਹੈ?" ਮਾਡਲ ਯਾਦ ਨਹੀਂ ਰੱਖੇਗਾ ਕਿਉਂਕਿ ਹਰ ਸੁਨੇਹਾ ਸਵਤੰਤਰ ਹੈ। ਇਹ ਸਧਾਰਣ ਭਾਸ਼ਾ ਮਾਡਲ ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਦੀ ਮੁੱਖ ਸਮੱਸਿਆ ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ - ਕੋਈ ਗੱਲਬਾਤ ਸੰਦਰਭ ਨਹੀਂ। -ਬਿਨਾਂ ਸਟੇਟ ਵਾਲੇ ਚੈਟ ਦਾ ਡੈਮੋ +ਸਟੇਟਲੈੱਸ ਚੈਟ ਡੈਮੋ -*AI ਤੁਹਾਡੇ ਪਹਿਲਾਂ ਦੇ ਸੁਨੇਹੇ ਤੋਂ ਨਾਮ ਯਾਦ ਨਹੀਂ ਕਰਦਾ* +*AI ਪਿਛਲੇ ਸੁਨੇਹੇ ਤੋਂ ਤੁਹਾਡੇ ਨਾਮ ਨੂੰ ਯਾਦ ਨਹੀਂ ਰੱਖਦਾ* ### ਸਟੇਟਫੁਲ ਚੈਟ (ਸੱਜਾ ਪੈਨਲ) -ਹੁਣ ਇੱਥੇ ਉਹੀ ਕ੍ਰਮ ਦੁਹਰਾਓ। ਪੁੱਛੋ "ਮੇਰਾ ਨਾਮ ਜੌਨ ਹੈ" ਅਤੇ ਫਿਰ "ਮੇਰਾ ਨਾਮ ਕੀ ਹੈ?" ਇਸ ਵਾਰ ਇਹ ਯਾਦ ਰੱਖਦਾ ਹੈ। ਫਰਕ MessageWindowChatMemory ਹੈ - ਜੋ ਗੱਲਬਾਤ ਇਤਿਹਾਸ ਨੂੰ ਸੰਭਾਲਦਾ ਹੈ ਅਤੇ ਹਰ ਬੇਨਤੀ ਨਾਲ ਉਹ ਸੰਦਰਭ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ। ਇਹ ਉਤਪਾਦਨ ਗੱਲਬਾਤੀ AI ਦਾ ਤਰੀਕਾ ਹੈ। +ਹੁਣ ਇੱਥੇ ਉਹੀ ਕ੍ਰਮ ਪਰਖੋ। "ਮੇਰਾ ਨਾਮ ਜੌਨ ਹੈ" ਪੁੱਛੋ ਅਤੇ ਤਦ "ਮੇਰਾ ਨਾਮ ਕੀ ਹੈ?" ਇਹ ਵਾਰ ਇਹ ਯਾਦ ਕਰਦਾ ਹੈ। ਫਰਕ MessageWindowChatMemory ਹੈ - ਇਹ ਗੱਲਬਾਤ ਇਤਿਹਾਸ ਨਿਭਾਂਦਾ ਹੈ ਅਤੇ ਹਰ ਬੇਨਤੀ ਨਾਲ ਸੰਦਰਭ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ। ਇਸ ਤਰ੍ਹਾਂ ਪ੍ਰੋਡਕਸ਼ਨ ਗੱਲਬਾਤੀ AI ਕੰਮ ਕਰਦੀ ਹੈ। -ਸਟੇਟਫੁਲ ਚੈਟ ਦਾ ਡੈਮੋ +ਸਟੇਟਫੁਲ ਚੈਟ ਡੈਮੋ -*AI ਗੱਲਬਾਤ ਦੇ ਪਹਿਲਾਂ ਦੇ ਹਿੱਸੇ ਤੋਂ ਤੁਹਾਡੇ ਨਾਮ ਨੂੰ ਯਾਦ ਰੱਖਦਾ ਹੈ* +*AI ਪਿਛਲੇ ਗੱਲਬਾਤ ਵਿੱਚ ਤੁਹਾਡੇ ਨਾਮ ਨੂੰ ਯਾਦ ਕਰਦਾ ਹੈ* -ਦੋਹਾਂ ਪੈਨਲ ਇੱਕੋ GPT-5.2 ਮਾਡਲ ਦੀ ਵਰਤੋਂ ਕਰਦੇ ਹਨ। ਸਿਰਫ ਮੈਮੋਰੀ ਵਿੱਚ ਫਰਕ ਹੈ। ਇਹ ਸਪੱਸ਼ਟ ਕਰਦਾ ਹੈ ਕਿ ਮੈਮੋਰੀ ਤੁਹਾਡੇ ਐਪਲੀਕੇਸ਼ਨ ਲਈ ਕੀ ਲਿਆਉਂਦੀ ਹੈ ਅਤੇ ਕਿਉਂ ਇਹ ਅਸਲੀ ਵਰਤੋਂ ਲਈ ਲਾਜ਼ਮੀ ਹੈ। +ਦੋਹਾਂ ਪੈਨਲਾਂ ਵਿੱਚ ਇੱਕੋ GPT-5.2 ਮਾਡਲ ਵਰਤੀ ਜਾਂਦੀ ਹੈ। ਇਕੱਲਾ ਅੰਤਰ ਮੈਮੋਰੀ ਹੈ। ਇਹ ਸਪਸ਼ਟ ਕਰਦਾ ਹੈ ਕਿ ਮੈਮੋਰੀ ਤੁਹਾਡੇ ਐਪਲੀਕੇਸ਼ਨ ਨੂੰ ਕੀ ਕੁਝ ਦਿੰਦੀ ਹੈ ਅਤੇ ਕਿਉਂ ਇਹ ਹਕੀਕਤੀ ਵਰਤੋਂ ਲਈ ਲਾਜ਼ਮੀ ਹੈ। ## ਅਗਲੇ ਕਦਮ -**ਅਗਲਾ ਮੋਡੀਊਲ:** [02-prompt-engineering - GPT-5.2 ਨਾਲ ਪ੍ਰਾਂਪਟ ਐਂਜੀਨੀਅਰਿੰਗ](../02-prompt-engineering/README.md) +**ਅਗਲਾ ਮੋਡੀਊਲ:** [02-prompt-engineering - GPT-5.2 ਨਾਲ ਪ੍ਰੰਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](../02-prompt-engineering/README.md) --- -**ਨੈਵੀਗੇਸ਼ਨ:** [← ਪਹਿਲਾਂ: ਮੋਡੀਊਲ 00 - ਕਵਿਕ ਸਟਾਰਟ](../00-quick-start/README.md) | [ਮੁੱਖ ਥਾਂ ਤੇ ਵਾਪਸ](../README.md) | [ਅਗਲਾ: ਮੋਡੀਊਲ 02 - ਪ੍ਰਾਂਪਟ ਐਂਜੀਨੀਅਰਿੰਗ →](../02-prompt-engineering/README.md) +**ਨੈਵੀਗੇਸ਼ਨ:** [← ਮੁੱਖ 'ਤੇ ਵਾਪਸ](../README.md) | [ਅੱਗੇ: ਮੋਡੀਊਲ 02 - ਪ੍ਰੰਪਟ ਇੰਜੀਨੀਅਰਿੰਗ →](../02-prompt-engineering/README.md) --- -**ਸਮੀਖਿਆ ਛੋੜ**: -ਇਸ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਅਨੁਵਾਦ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਿੱਥੇ ਅਸੀਂ ਸ਼ੁੱਧਤਾ ਲਈ ਕੋਸ਼ਿਸ਼ ਕਰਦੇ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਪਸ਼ਟਤਾਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਇਸ ਦੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਅਧਿਕਾਰਿਤ ਸੱਤਰ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਅਹਿਮ ਜਾਣਕਾਰੀ ਲਈ, ਪ੍ਰੋਫੈਸ਼ਨਲ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੇ ਉਪਯੋਗ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਗਲਤ ਵਿਅਖਿਆਵਾਂ ਲਈ ਜ਼ਿੰਮੇਵਾਰ ਨਹੀਂ ਹਾਂ। +**ਅਸਵੀਕਾਰੋਪਣ**: +ਇਸ ਦਸਤਾਵੇਜ਼ ਦਾ ਅਨੁਵਾਦ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾਵਾਂ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਮੱਤਿਆਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਜਰੂਰੀ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੇ ਉਪਯੋਗ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਗਲਤ ਵਿਆਖਿਆਵਾਂ ਲਈ ਜਵਾਬਦੇਹ ਨਹੀਂ ਹਾਂ। \ No newline at end of file diff --git a/translations/pa/02-prompt-engineering/README.md b/translations/pa/02-prompt-engineering/README.md index 3144e8bb8..414412e20 100644 --- a/translations/pa/02-prompt-engineering/README.md +++ b/translations/pa/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ # ਮਾਡਿਊਲ 02: GPT-5.2 ਨਾਲ ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ -## ਸਮੱਗਰੀ ਦੀ ਸੂਚੀ - -- [ਵੀਡੀਓ ਵਾਕਥਰੂ](../../../02-prompt-engineering) -- [ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ](../../../02-prompt-engineering) -- [ਪੂਰਵ-ਸ਼ਰਤਾਂ](../../../02-prompt-engineering) -- [ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਨੂੰ ਸਮਝਣਾ](../../../02-prompt-engineering) -- [ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਦੇ ਮੂਲ ਤੱਤ](../../../02-prompt-engineering) - - [ਜ਼ੀਰੋ-ਸ਼ਾਟ ਪ੍ਰਾਂਪਟਿੰਗ](../../../02-prompt-engineering) - - [ਫਿਊ-ਸ਼ਾਟ ਪ੍ਰਾਂਪਟਿੰਗ](../../../02-prompt-engineering) - - [ਚੇਨ ਆਫ ਥੌਟ](../../../02-prompt-engineering) - - [ਰੋਲ-ਅਧਾਰਿਤ ਪ੍ਰਾਂਪਟਿੰਗ](../../../02-prompt-engineering) - - [ਪ੍ਰਾਂਪਟ ਟੈਮਪਲੇਟ](../../../02-prompt-engineering) -- [ਉਨੱਤ ਪੈਟਰਨ](../../../02-prompt-engineering) -- [ਐਪਲੀਕੇਸ਼ਨ ਚਲਾਉਣਾ](../../../02-prompt-engineering) -- [ਐਪਲੀਕੇਸ਼ਨ ਸਕ੍ਰੀਨਸ਼ਾਟ](../../../02-prompt-engineering) -- [ਪੈਟਰਨ ਦੀ ਖੋਜ](../../../02-prompt-engineering) - - [ਘੱਟ ਬਨਾਮ ਜ਼ਿਆਦਾ ਉਤਸ਼ਾਹ](../../../02-prompt-engineering) - - [ਕਾਰਜ ਨਿਰਵਾਹ (ਟੂਲ ਪ੍ਰੀਐਮਬਲ)](../../../02-prompt-engineering) - - [ਆਪਣੇ ਆਪ ਦੀ ਪਰਖ ਕਰੋਡ](../../../02-prompt-engineering) - - [ਸੰਰਚਿਤ ਵਿਸ਼ਲੇਸ਼ਣ](../../../02-prompt-engineering) - - [ਬਹੁ-ਚਿਰ ਚੈਟ](../../../02-prompt-engineering) - - [ਕਦਮ ਦਰ ਕਦਮ ਤਰਕ](../../../02-prompt-engineering) - - [ਸੰਕੁਚਿਤ ਆਉਟਪੁਟ](../../../02-prompt-engineering) -- [ਤੁਸੀਂ ਅਸਲ ਵਿੱਚ ਕੀ ਸਿੱਖ ਰਹੇ ਹੋ](../../../02-prompt-engineering) -- [ਅਗਲੇ ਕਦਮ](../../../02-prompt-engineering) +## ਸਮੱਗਰੀ ਸੂਚੀ + +- [ਵੀਡੀਓ ਵਾਕਥਰੂ](#ਵੀਡੀਓ-ਵਾਕਥਰੂ) +- [ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ](#ਤੁਸੀਂ-ਕੀ-ਸਿੱਖੋਗੇ) +- [ਪূর্বਆਵਸ਼ਕਤਾਵਾਂ](#ਪੂਰਵਆਵਸ਼ਕਤਾਵਾਂ) +- [ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਨੂੰ ਸਮਝਣਾ](#ਪ੍ਰਾਂਪਟ-ਇੰਜੀਨੀਅਰਿੰਗ-ਨੂੰ-ਸਮਝਣਾ) +- [ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਮੁਢਲੇ ਤੱਤ](#ਪ੍ਰਾਂਪਟ-ਇੰਜੀਨੀਅਰਿੰਗ-ਮੁਢਲੇ-ਤੱਤ) + - [ਜੀਰੋ-ਸ਼ਾਟ ਪ੍ਰਾਂਪਟਿੰਗ](#ਜੀਰੋ-ਸ਼ਾਟ-ਪ੍ਰਾਂਪਟਿੰਗ) + - [ਫਿਊ-ਸ਼ਾਟ ਪ੍ਰਾਂਪਟਿੰਗ](#ਫਿਊ-ਸ਼ਾਟ-ਪ੍ਰਾਂਪਟਿੰਗ) + - [ਚੇਨ ਆਫ ਥੌਟ](#ਚੇਨ-ਆਫ-ਥੌਟ) + - [ਰੋਲ-ਆਧਾਰਿਤ ਪ੍ਰਾਂਪਟਿੰਗ](#ਰੋਲ-ਆਧਾਰਿਤ-ਪ੍ਰਾਂਪਟਿੰਗ) + - [ਪ੍ਰਾਂਪਟ ਟੈਮਪਲੇਟਸ](#ਪ੍ਰਾਂਪਟ-ਟੈਮਪਲੇਟਸ) +- [ਅਡਵਾਂਸ ਪੈਟਰਨਸ](#ਅਡਵਾਂਸ-ਪੈਟਰਨਸ) +- [ਐਪਲਿਕੇਸ਼ਨ ਚਲਾਓ](#ਐਪਲੀਕੇਸ਼ਨ-ਚਲਾਓ) +- [ਐਪਲਿਕੇਸ਼ਨ ਸਕ੍ਰੀਨਸ਼ਾਟ](#ਐਪਲੀਕੇਸ਼ਨ-ਸਕ੍ਰੀਨਸ਼ਾਟ) +- [ਪੈਟਰਨਸ ਦੀ ਖੋਜ](#ਪੈਟਰਨਾਂ-ਦੀ-ਖੋਜ) + - [ਘੱਟ ਵਰਗੇ ਬਨਾਮ ਉੱਚ ਵਰਗੇ ਉਤਸ਼ਾਹ](#ਘੱਟ-ਅਤੇ-ਜ਼ਿਆਦਾ-ਉਤਸ਼ਾਹ) + - [ਕੰਮ ਦੀ ਕਾਰਗੁਜ਼ਾਰੀ (ਟੂਲ ਪ੍ਰੀਐਂਬਲ)](#ਟਾਸਕ-ਐਗਜ਼ਿਕਿਊਸ਼ਨ-ਟੂਲ-ਪ੍ਰੀਐਮਬਲ) + - [ਆਪਣੇ ਆਪ 'ਤੇ ਵਿਚਾਰ ਕਰਨ ਵਾਲਾ ਕੋਡ](#ਸੈਲਫ-ਰਿਫਲੈਕਟਿੰਗ-ਕੋਡ) + - [ਸੰਰਚਿਤ ਵਿਸ਼ਲੇਸ਼ਣ](#ਸੰਰਚਿਤ-ਵਿਸ਼ਲੇਸ਼ਣ) + - [ਮਲਟੀ-ਟਰਨ ਚੈਟ](#ਮਲਟੀ-ਟਰਨ-ਚੈਟ) + - [ਕਦਮ-ਦਰ-ਕਦਮ ਤਰਕ](#ਕਦਮ-ਦਰ-কਦਮ-ਤਰਕਸ਼ੀਲਤਾ) + - [ਸੀਮਿਤ ਆਉਟਪੁੱਟ](#ਸੀਮਿਤ-ਆਉਟਪੁੱਟ) +- [ਤੁਸੀਂ ਅਸਲ ਵਿੱਚ ਕੀ ਸਿੱਖ ਰਹੇ ਹੋ](#ਤੁਸੀਂ-ਅਸਲ-ਵਿੱਚ-ਕੀ-ਸਿੱਖ-ਰਹੇ-ਹੋ) +- [ਅਗਲੇ ਕਦਮ](#ਅਗਲੇ-ਕਦਮ) ## ਵੀਡੀਓ ਵਾਕਥਰੂ -ਇਸ ਲਾਈਵ ਸੈਸ਼ਨ ਨੂੰ ਵੇਖੋ ਜੋ ਦੱਸਦਾ ਹੈ ਕਿ ਇਸ ਮਾਡਿਊਲ ਨਾਲ ਕਿਵੇਂ ਸ਼ੁਰੂ ਕਰਨਾ ਹੈ: +ਇਸ ਲਾਈਵ ਸੈਸ਼ਨ ਨੂੰ ਦੇਖੋ ਜੋ ਦੱਸਦਾ ਹੈ ਕਿ ਇਸ ਮਾਡਿਊਲ ਨਾਲ ਕਿਸ ਤਰ੍ਹਾਂ ਸ਼ੁਰੂਆਤ ਕਰਨੀ ਹੈ: Prompt Engineering with LangChain4j - Live Session ## ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਇਸ ਮਾਡਿਊਲ ਵਿੱਚ ਤੁਸੀਂ ਵਿਕਸਤ ਕਰਨ ਵਾਲੇ ਮੁੱਖ ਵਿਸ਼ੇ ਅਤੇ ਕੌਸ਼ਲਾਂ ਦਾ ਇੱਕ ਝਲਕ ਦਿੰਦਾ ਹੈ — ਪ੍ਰਾਂਪਟ ਸੁਧਾਰ ਤਕਨੀਕਾਂ ਤੋਂ ਲੈ ਕੇ ਕਦਮ ਦਰ ਕਦਮ ਵਰਕਫਲੋ ਤੱਕ ਜੋ ਤੁਸੀਂ ਪਾਲਣ ਕਰੋਗੇ। +ਹੇਠਾਂ ਦਿੱਤਾ ਗ੍ਰਾਫਿਕ ਇਸ ਮਾਡਿਊਲ ਵਿੱਚ ਵਿਕਸਿਤ ਕਰਨ ਵਾਲੇ ਮੁੱਖ ਵਿਸ਼ਿਆਂ ਅਤੇ ਹੁਨਰਾਂ ਦਾ ਸੰਖੇਪ ਦਿੰਦਾ ਹੈ — ਪ੍ਰਾਂਪਟ ਸੁਧਾਰ ਤਕਨੀਆਂ ਤੋਂ ਲੈ ਕੇ ਕਦਮ-ਦਰ-ਕਦਮ ਕਾਰਜ ਪ੍ਰਵਾਹ ਤੱਕ ਜੋ ਤੁਸੀਂ ਅਨੁਸਰਣ ਕਰੋਗੇ। What You'll Learn -ਪਿਛਲੇ ਮਾਡਿਊਲਾਂ ਵਿੱਚ, ਤੁਸੀਂ GitHub ਮਾਡਲਾਂ ਨਾਲ ਬੁਨਿਆਦੀ LangChain4j ਇੰਟਰੈਕਸ਼ਨਾਂ ਦੀ ਜਾਂਚ ਕੀਤੀ ਅਤੇ ਵੇਖਿਆ ਕਿ ਕਿਵੇਂ Azure OpenAI ਨਾਲ ਮੈਮੋਰੀ ਸੰਵਾਦਾਤਮਕ AI ਨੂੰ ਸਮਰੱਥ ਬਣਾਉਂਦੀ ਹੈ। ਹੁਣ ਅਸੀਂ ਧਿਆਨ ਦੇਵਾਂਗੇ ਕਿ ਤੁਸੀਂ ਕਿਵੇਂ ਸਵਾਲ ਕਰਦੇ ਹੋ — ਮਤਲਬ ਪ੍ਰਾਂਪਟ ਖੁਦ — Azure OpenAI ਦੇ GPT-5.2 ਦੀ ਵਰਤੋਂ ਕਰਦੇ ਹੋਏ। ਤੁਸੀਂ ਜੋ ਪ੍ਰਾਂਪਟ ਬਣਾਉਂਦੇ ਹੋ ਉਸਦਾ ਢਾਂਚਾ ਬੋਲੇ ਗਏ ਜਵਾਬਾਂ ਦੀ ਗੁਣਵੱਤਾ ਨੂੰ ਬਹੁਤ ਪ੍ਰਭਾਵਤ ਕਰਦਾ ਹੈ। ਅਸੀਂ ਮੂਲ ਪ੍ਰਾਂਪਟਿੰਗ ਤਕਨੀਕਾਂ ਦੀ ਸਮੀਖਿਆ ਕਰਾਂਗੇ, ਫਿਰ GPT-5.2 ਦੀਆਂ ਪੂਰਨ ਖੂਬੀਆਂ ਦੀ ਬਹਾਲੀ ਲਈ ਅੱਠ ਉਨੱਤ ਪੈਟਰਨਾਂ ਵੱਲ ਅੱਗੇ ਵਧਾਂਗੇ। +ਪਿਛਲੇ ਮਾਡਿਊਲ ਵਿੱਚ, ਤੁਸੀਂ ਵੇਖਿਆ ਕਿ ਕਿਵੇਂ ਮੈਮਰੀ Azure OpenAI ਨਾਲ ਸੰਵਾਦਾਤਮਕ AI ਨੂੰ ਯੋਗ ਬਣਾਉਂਦੀ ਹੈ। ਹੁਣ ਅਸੀਂ ਧਿਆਨ ਦੇਵਾਂਗੇ ਕਿ ਤੁਸੀਂ ਪ੍ਰਸ਼ਨ ਕਿਵੇਂ ਪੁੱਛਦੇ ਹੋ — ਖੁਦ ਪ੍ਰਾਂਪਟ — Azure OpenAI ਦੇ GPT-5.2 ਦੀ ਵਰਤੋਂ ਕਰਦੇ ਹੋਏ। ਤੁਸੀਂ ਆਪਣੇ ਪ੍ਰਾਂਪਟ ਕਿਸ ਤਰ੍ਹਾਂ ਬਣਾਓਗੇ ਇਸ ਨਾਲ ਤੁਹਾਨੂੰ ਮਿਲਣ ਵਾਲੇ ਜਵਾਬਾਂ ਦੀ ਗੁਣਵੱਤਾ ਵੱਡਾ ਪ੍ਰਭਾਵਿਤ ਹੁੰਦੀ ਹੈ। ਅਸੀਂ ਬੁਨਿਆਦੀ ਪ੍ਰਾਂਪਟ ਤਕਨੀਆਂ ਦੀ ਸਮੀਖਿਆ ਨਾਲ ਸ਼ੁਰੂ ਕਰਦੇ ਹਾਂ, ਫਿਰ ਐਠ ਅਡਵਾਂਸ ਪੈਟਰਨਾਂ ਵਿੱਚ ਜਾਣਕਾਰੀ ਕਰਦੇ ਹਾਂ ਜੋ GPT-5.2 ਦੀਆਂ ਸਮਰੱਥਾਵਾਂ ਦਾ ਪੂਰਾ ਲਾਭ ਲੈਂਦੇ ਹਨ। -ਅਸੀਂ GPT-5.2 ਦੀ ਵਰਤੋਂ ਕਰਾਂਗੇ ਕਿਉਂਕਿ ਇਹ ਤਰਕ ਵਿੱਚ ਕੰਟਰੋਲ ਪਰਵਾਨਗੀ ਦਿੰਦਾ ਹੈ - ਤੁਸੀਂ ਮਾਡਲ ਨੂੰ ਦੱਸ ਸਕਦੇ ਹੋ ਕਿ ਜਵਾਬ ਦੇਣ ਤੋਂ ਪਹਿਲਾਂ ਕਿੰਨਾ ਸੋਚਣਾ ਹੈ। ਇਹ ਵੱਖ-ਵੱਖ ਪ੍ਰਾਂਪਟਿੰਗ ਰਣਨੀਤੀਆਂ ਨੂੰ ਹੋਰ ਪ੍ਰਗਟ ਕਰਦਾ ਹੈ ਅਤੇ ਤੁਹਾਨੂੰ ਸਿੱਖਣ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ ਕਿ ਕਦੋਂ ਕਿਹੜੀ ਪদ্ধਤੀ ਵਰਤਣੀ ਹੈ। ਨਾਲ ਹੀ ਅਸੀਂ GitHub ਮਾਡਲਾਂ ਨਾਲੋਂ ਘੱਟ ਦਰ ਸੀਮਾਵਾਂ ਵਾਲੇ Azure ਦੇ ਜੀਪੀਟੀ-5.2 ਦੇ ਫਾਇਦੇ ਲੈ ਸਕਦੇ ਹਾਂ। +ਅਸੀਂ GPT-5.2 ਦੀ ਵਰਤੋਂ ਕਰਾਂਗੇ ਕਿਉਂਕਿ ਇਹ ਤਰਕ ਨੂੰ ਨਿਯੰਤਰਿਤ ਕਰਨ ਦੀ ਸ਼ਕਤੀ ਲਿਆਉਂਦਾ ਹੈ - ਤੁਸੀਂ ਮਾਡਲ ਨੂੰ ਦੱਸ ਸਕਦੇ ਹੋ ਕਿ ਜਵਾਬ ਦੇਣ ਤੋਂ ਪਹਿਲਾਂ ਕਿੰਨੀ ਸੋਚਣੀ ਹੈ। ਇਸ ਨਾਲ ਵੱਖ-ਵੱਖ ਪ੍ਰਾਂਪਟਿੰਗ ਤਰੀਕੇ ਵੱਧ ਸਰਲਤਾ ਨਾਲ ਸਮਝ ਆਉਂਦੇ ਹਨ ਅਤੇ ਤੁਸੀਂ ਜਾਣ ਸਕਦੇ ਹੋ ਕਿ ਕਿਸ ਵੇਲੇ ਕਿਹੜੀ ਤਕਨੀਕ ਵਰਤਣੀ ਹੈ। -## ਪੂਰਵ-ਸ਼ਰਤਾਂ +## ਪੂਰਵਆਵਸ਼ਕਤਾਵਾਂ -- ਮਾਡਿਊਲ 01 ਪੂਰਾ ਕੀਤਾ ਹੋਇਆ (Azure OpenAI ਸਰੋਤ ਤਾਇਨਾਤ) -- ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ `.env` ਫਾਇਲ ਜਿਸ ਵਿੱਚ Azure ਦੀਆਂ ਪ੍ਰਮਾਣਿਕਤਾਵਾਂ ਹਨ (ਮਾਡਿਊਲ 01 ਵਿੱਚ `azd up` ਦੁਆਰਾ ਬਣਾਇਆ ਗਿਆ) +- ਮਾਡਿਊਲ 01 ਪੂਰਾ ਕੀਤਾ ਹੋਇਆ (Azure OpenAI ਸਰੋਤ ਤਿਆਰ ਕੀਤੇ ਹੋਏ) +- `.env` ਫਾਈਲ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ Azure ਪ੍ਰਮਾਣਿਕਤਾ ਸਮੇਤ (ਮਾਡਿਊਲ 01 ਵਿੱਚ `azd up` ਦੁਆਰਾ ਬਣਾਈ ਗਈ) -> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਮਾਡਿਊਲ 01 ਨਹੀਂ ਕੀਤਾ, ਤਾਂ ਪਹਿਲਾਂ ਉਥੇ ਦਿੱਤੀਆਂ ਤਾਇਨਾਤ ਹਦਾਇਤਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ। +> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਮਾਡਿਊਲ 01 ਪੂਰਾ ਨਹੀਂ ਕੀਤਾ, ਤਾਂ ਪਹਿਲਾਂ ਉੱਥੇ ਦਿੱਤੇ ਡਿਪਲੋਇਮੈਂਟ ਨਿਰਦੇਸ਼ਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ। ## ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਨੂੰ ਸਮਝਣਾ -ਮੂਲ ਤੌਰ ਤੇ, ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਅਸਪੱਸ਼ਟ ਹਦਾਇਤਾਂ ਅਤੇ ਸਹੀ ਹਦਾਇਤਾਂ ਵਿਚਕਾਰ ਫਰਕ ਹੁੰਦਾ ਹੈ, ਜਿਵੇਂ ਹੇਠਾਂ ਦਿੱਤਾ ਤੁਲਨਾ ਦਿਖਾਉਂਦੀ ਹੈ। +ਮੂਲ ਰੂਪ ਵਿੱਚ, ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਗੁੰਝਲਦਾਰ ਹਦਾਇਤਾਂ ਅਤੇ ਸਪਸ਼ਟ ਹਦਾਇਤਾਂ ਵਿੱਚ ਫਰਕ ਹੈ, ਜਿਵੇਂ ਹੇਠਾਂ ਦਿੱਤੀ ਤੁਲਨਾ ਦਰਸਾਉਂਦੀ ਹੈ। What is Prompt Engineering? -ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਇਸ ਗੱਲ ਬਾਰੇ ਹੈ ਕਿ ਇਸ ਤਰ੍ਹਾਂ ਦਾ ਇਨਪੁਟ ਟੈਕਸਟ ਬਣਾਇਆ ਜਾਵੇ ਜੋ ਲਗਾਤਾਰ ਤੁਹਾਨੂੰ ਚਾਹੀਦਾ ਨਤੀਜਾ ਦੇਵੇ। ਇਹ ਸਿਰਫ ਸਵਾਲ ਪੁੱਛਣ ਬਾਰੇ ਨਹੀਂ ਹੈ — ਇਹ ਬੇਨਤੀ ਰਚਨਾ ਬਾਰੇ ਹੈ ਤਾਂ ਜੋ ਮਾਡਲ ਬਿਲਕੁਲ ਸਮਝ ਸਕੇ ਕਿ ਤੁਸੀਂ ਕੀ ਚਾਹੁੰਦੇ ਹੋ ਅਤੇ ਕਿਵੇਂ ਪੇਸ਼ ਕਰਨਾ ਹੈ। +ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਇੰਪੁਟ ਟੈਕਸਟ ਡਿਜ਼ਾਈਨ ਕਰਨਾ ਹੈ ਜੋ ਲਗਾਤਾਰ ਤੁਸੀਂ ਚਾਹੁੰਦੇ ਨਤੀਜੇ ਦਿੰਦਾ ਹੈ। ਇਹ ਸਿਰਫ਼ ਪ੍ਰਸ਼ਨ ਪੁੱਛਣ ਦੇ ਬਾਰੇ ਨਹੀਂ ਹੈ - ਇਹ ਬੇਨਤੀ ਇਸ ਤਰ੍ਹਾਂ ਬਣਾਉਣ ਦੇ ਬਾਰੇ ਹੈ ਕਿ ਮਾਡਲ ਪੂਰੀ ਤਰ੍ਹਾਂ ਸਮਝੇ ਕਿ ਤੁਸੀਂ ਕੀ ਚਾਹੁੰਦੇ ਹੋ ਅਤੇ ਕਿਵੇਂ ਦਿੱਤਾ ਜਾਵੇ। -ਇਸਨੂੰ ਆਪਣੇ ਸਾਥੀ ਨੂੰ ਹਦਾਇਤ ਦੇਣ ਵਾਂਗ ਸੋਚੋ। "ਬੱਗ ਦੁਰਸਤ ਕਰੋ" ਅਸਪੱਸ਼ਟ ਹੈ। "UserService.java ਲਾਈਨ 45 ਵਿੱਚ null pointer exception ਦੀ ਮੁਰੰਮਤ ਲਈ null ਚੈੱਕ ਸ਼ਾਮਿਲ ਕਰੋ" ਵਿਸ਼ੇਸ਼ ਹੈ। ਭਾਸ਼ਾ ਮਾਡਲ ਵਿਆਹ ਇਸੇ ਤਰ੍ਹਾਂ ਕੰਮ ਕਰਦੇ ਹਨ - ਵਿਸ਼ੇਸ਼ਤਾ ਅਤੇ ਢਾਂਚਾ ਮਹੱਤਵਪੂਰਣ ਹਨ। +ਇਸਨੂੰ ਕਾਲੀਗ ਨੂੰ ਹਦਾਇਤ ਦੇਣ ਵਾਂਗ ਸੋਚੋ। "ਬਗ ਠੀਕ ਕਰੋ" ਧੁੰਦਲੀ ਗੱਲ ਹੈ। "UserService.java ਦੀ ਲਾਈਨ 45 'ਚ ਨੱਲ ਪੌਇੰਟਰ ਇ਼ਕਸੈਪਸ਼ਨ ਨੂੰ ਨੱਲ ਚੈਕ ਨਾਲ ਠੀਕ ਕਰੋ" ਵਿਸ਼ੇਸ਼ ਤੌਰ 'ਤੇ ਹੈ। ਭਾਸ਼ਾ ਮਾਡਲ ਭੀ ਉਸੇ ਤਰ੍ਹਾਂ ਕੰਮ ਕਰਦੇ ਹਨ — ਵਿਸ਼ੇਸ਼ਤਾ ਅਤੇ ਬਣਤਰ ਮਹੱਤਵਪੂਰਨ ਹਨ। -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਕਿਵੇਂ LangChain4j ਇਸ ਤਸਵੀਰ ਵਿੱਚ ਫਿੱਟ ਹੁੰਦਾ ਹੈ — ਤੁਹਾਡੇ ਪ੍ਰਾਂਪਟ ਪੈਟਰਨਾਂ ਨੂੰ SystemMessage ਅਤੇ UserMessage ਬਿਲਡਿੰਗ ਬਲਾਕਾਂ ਰਾਹੀਂ ਮਾਡਲ ਨਾਲ ਜੋੜਦਾ ਹੈ। +ਹੇਠਾਂ ਦਿੱਤੀ ਗ੍ਰਾਫਿਕ ਦਰਸਾਉਂਦੀ ਹੈ ਕਿ LangChain4j ਇਸ ਤਸਵੀਰ ਵਿੱਚ ਕਿਵੇਂ ਫਿੱਟ ਹੁੰਦਾ ਹੈ — ਤੁਹਾਡੇ ਪ੍ਰਾਂਪਟ ਪੈਟਰਨਾਂ ਨੂੰ ਮਾਡਲ ਨਾਲ SystemMessage ਅਤੇ UserMessage ਬਣਤਰਾਂ ਰਾਹੀਂ ਜੋੜਦਾ ਹੈ। How LangChain4j Fits -LangChain4j ਢਾਂਚਾ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ — ਮਾਡਲ ਕਨੈਕਸ਼ਨ, ਮੈਮੋਰੀ ਅਤੇ ਸੁਨੇਹਾ ਕਿਸਮਾਂ — ਜਦਕਿ ਪ੍ਰਾਂਪਟ ਪੈਟਰਨ ਸਿਰਫ ਧਿਆਨ ਨਾਲ ਬਣਾਏ ਗਏ ਲਿਖਤੀ ਟੈਕਸਟ ਹਨ ਜੋ ਉਸ ਢਾਂਚੇ ਰਾਹੀਂ ਭੇਜੇ ਜਾਂਦੇ ਹਨ। ਮੁੱਖ ਬਿਲਡਿੰਗ ਬਲਾਕ `SystemMessage` (ਜੋ AI ਦੇ ਵਿਵਹਾਰ ਅਤੇ ਭੂਮਿਕਾ ਵੱਖੁ ਕਰਦਾ ਹੈ) ਅਤੇ `UserMessage` (ਜੋ ਤੁਹਾਡੇ ਅਸਲ ਬੇਨਤੀ ਲਿਆਉਂਦਾ ਹੈ) ਹਨ। +LangChain4j ਢਾਂਚਾ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ — ਮਾਡਲ ਕਨੇਕਸ਼ਨ, ਮੈਮੋਰੀ, ਅਤੇ ਸੁਨੇਹੇ ਪ੍ਰਕਾਰ — ਜਦਕਿ ਪ੍ਰਾਂਪਟ ਪੈਟਰਨ ਸਿਰਫ ਕਾਨੂੰਨਬੱਧ ਟੈਕਸਟ ਹੁੰਦੇ ਹਨ ਜਿਸਨੂੰ ਤੁਸੀਂ ਉਸ ਢਾਂਚੇ ਰਾਹੀਂ ਭੇਜਦੇ ਹੋ। ਮੁੱਖ ਬਣਤਰਾਂ ਹਨ `SystemMessage` (ਜੋ AI ਦਾ ਵਿਹਾਰ ਅਤੇ ਭੂਮਿਕਾ ਸੈਟ ਕਰਦਾ ਹੈ) ਅਤੇ `UserMessage` (ਜੋ ਤੁਹਾਡੀ ਅਸਲ ਬੇਨਤੀ ਲੈ ਕੇ ਜਾਂਦਾ ਹੈ)। -## ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਦੇ ਮੂਲ ਤੱਤ +## ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਮੁਢਲੇ ਤੱਤ -ਹੇਠਾਂ ਦਿੱਤੇ ਪੰਜ ਮੁੱਖ ਤਕਨੀਕਾਂ ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਦਾ ਆਧਾਰ ਬਣਾਉਂਦੀਆਂ ਹਨ। ਹਰ ਇੱਕ ਵੱਖਰੇ ਪਹਿਲੂ ਦਾ ਹੱਲ ਕਰਦੀ ਹੈ ਕਿ ਤੁਸੀਂ ਭਾਸ਼ਾ ਮਾਡਲ ਨਾਲ ਕਿਵੇਂ ਸੰਚਾਰ ਕਰਦੇ ਹੋ। +ਹੇਠਾਂ ਦਿਖਾਈ ਪੰਜ ਮੁੱਖ ਤਕਨੀਆਂ ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਦੀ ਬੁਨਿਆਦ ਬਣਾਉਂਦੀਆਂ ਹਨ। ਹਰ ਇੱਕ ਬੋਲਚਾਲ ਵਿੱਚ ਭਾਸ਼ਾ ਮਾਡਲ ਨਾਲ ਸੰਚਾਰ ਕਰਨ ਦੇ ਵੱਖਰੇ ਪਹਿਲੂ ਨੂੰ ਸੰਬੋਧਦਾ ਹੈ। Five Prompt Engineering Patterns Overview -ਇਸ ਮਾਡਿਊਲ ਵਿੱਚ ਉਨੱਤ ਪੈਟਰਨਾਂ ਵਿੱਚ ਡੁੱਬਕੀ ਲਗਾਉਣ ਤੋਂ ਪਹਿਲਾਂ, ਆਓ ਪੰਜ ਬੁਨਿਆਦੀ ਪ੍ਰਾਂਪਟਿੰਗ ਤਕਨੀਕਾਂ ਦੀ ਸਮੀਖਿਆ ਕਰੀਏ। ਇਹ ਉਹ ਨਿਰਮਾਣ ਬਲਾਕ ਹਨ ਜੋ ਹਰ ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰ ਨੂੰ ਜਾਣਣੇ ਚਾਹੀਦੇ ਹਨ। ਜੇ ਤੁਸੀਂ ਪਹਿਲਾਂ ਹੀ [ਕੁਇੱਕ ਸਟਾਰਟ ਮਾਡਿਊਲ](../00-quick-start/README.md#2-prompt-patterns) ਦੇਖ ਚੁੱਕੇ ਹੋ, ਤਾਂ ਤੁਸੀਂ ਉਨ੍ਹਾਂ ਨੂੰ ਕਾਰਜਕਾਰੀ ਰੂਪ ਵਿੱਚ ਦੇਖਿਆ ਹੈ — ਇਹਾੱਁ ਉਸ ਦੇ ਪਿੱਛੇ ਦਾ ਧਾਰਨਾਤਮਕ ਢਾਂਚਾ ਹੈ। +ਇਸ ਮਾਡਿਊਲ ਵਿੱਚ ਅਡਵਾਂਸ ਪੈਟਰਨਾਂ ਵਿੱਚ ਜਾਣ ਤੋਂ ਪਹਿਲਾਂ, ਆਓ ਪੰਜ ਬੁਨਿਆਦੀ ਪ੍ਰਾਂਪਟਿੰਗ ਤਕਨੀਆਂ ਦੀ ਸਮੀਖਿਆ ਕਰੀਏ। ਇਹ ਉਸ ਟੂਲਕਿਟ ਦੀਆਂ ਚਾਬੀਆਂ ਹਨ ਜਿਸ ਨੂੰ ਹਰ ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰ ਨੇ ਜਾਣਣਾ ਲਾਜ਼ਮੀ ਹੈ। -### ਜ਼ੀਰੋ-ਸ਼ਾਟ ਪ੍ਰਾਂਪਟਿੰਗ +### ਜੀਰੋ-ਸ਼ਾਟ ਪ੍ਰਾਂਪਟਿੰਗ -ਸਭ ਤੋਂ ਸਧਾਰਣ ਤਰੀਕਾ: ਮਾਡਲ ਨੂੰ ਬਿਨਾਂ ਉਦਾਹਰਨਾਂ ਦੇ ਸਿੱਧੀ ਹੁਕਮ ਦਿਓ। ਮਾਡਲ ਮੁਕੰਮਲ ਤੌਰ 'ਤੇ ਆਪਣੀ ਟ੍ਰੇਨਿੰਗ 'ਤੇ ਨਿਰਭਰ ਕਰਦਾ ਹੈ ਕੰਮ ਸਮਝਣ ਅਤੇ ਪੂਰਾ ਕਰਨ ਲਈ। ਇਹ ਸਧਾਰਣ ਬੇਨਤੀਆਂ ਲਈ ਚੰਗਾ ਕੰਮ ਕਰਦਾ ਹੈ ਜਿੱਥੇ ਉਮੀਦ ਕੀਤੀ ਹੁੰਦੀ ਹੈ ਕਿ ਮਾਡਲ ਆਪਣਾ ਰਵੱਈਆ ਸਪੱਸ਼ਟ ਰਖੇਗਾ। +ਸਰਲ ਤਰੀਕਾ: ਮਾਡਲ ਨੂੰ ਸਿੱਧੀ ਹੁਕਮ ਦਿਓ ਬਿਨਾਂ ਕਿਸੇ ਉਦਾਹਰਣ ਦੇ। ਮਾਡਲ ਆਪਣੇ ਟ੍ਰੇਨਿੰਗ ਤੇ ਹੀ ਨਿਰਭਰ ਕਰਦਾ ਹੈ ਕੰਮ ਨੂੰ ਸਮਝਣ ਅਤੇ ਅੰਜਾਮ ਦੇਣ ਲਈ। ਇਹ ਸਧਾਰਣ ਬੇਨਤੀਆਂ ਲਈ ਚੰਗਾ ਕੰਮ ਕਰਦਾ ਹੈ ਜਿੱਥੇ ਉਮੀਦ ਕੀਤੀ ਗਈ ਵਰਤੋਂ ਸਪਸ਼ਟ ਹੈ। Zero-Shot Prompting -*ਉਦਾਹਰਨਾਂ ਬਿਨਾਂ ਸਿੱਧੀ ਹੁਕਮ — ਮਾਡਲ ਕਿਸੇ ਵੀ ਸਿੱਧੇ ਹੁਕਮ ਤੋਂ ਕਾਰਜ ਨੁਅਮਾਨਦਾ ਹੈ* +*ਕਿਸੇ ਉਦਾਹਰਣ ਤੋਂ ਬਿਨਾਂ ਸਿੱਧੀ ਹੁਕਮ — ਮਾਡਲ ਸਿਰਫ ਹੁਕਮ ਤੋਂ ਕੰਮ ਦੀ ਸੂਝ ਲੈਂਦਾ ਹੈ* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // ਜਵਾਬ: "ਸਕਾਰਾਤਮਕ" ``` -**ਕਦੋਂ ਵਰਤਣਾ:** ਸਧਾਰਣ ਵਰਗੀਕਰਨ, ਸਿੱਧੇ ਸਵਾਲ, ਅਨੁਵਾਦ, ਜਾਂ ਕੋਈ ਵੀ ਕਾਰਜ ਜੋ ਮਾਡਲ ਨੂੰ ਵਾਧੂ ਰਹਿਨੁਮਾ ਦੀ ਲੋੜ ਨਹੀਂ। +**ਕਦੋਂ ਵਰਤਣਾ ਹੈ:** ਸਰਲ ਵਰਗੀਕਰਨ, ਸਿੱਧੇ ਪ੍ਰਸ਼ਨ, ਅਨੁਵਾਦ, ਜਾਂ ਕੋਈ ਵੀ ਕੰਮ ਜਿਸਨੂੰ ਮਾਡਲ ਅਤਿਰਿਕਤ ਦਿਸ਼ਾ-ਨਿਰਦੇਸ਼ ਦੇ ਬਿਨਾਂ ਸੰਭਾਲ ਸਕਦਾ ਹੈ। ### ਫਿਊ-ਸ਼ਾਟ ਪ੍ਰਾਂਪਟਿੰਗ -ਉਦਾਹਰਨਾਂ ਦਿਓ ਜਿਹੜੀਆਂ ਮਾਡਲ ਨੂੰ ਦਿਖਾਅਉਂਦੀਆਂ ਹਨ ਕਿ ਤੁਸੀਂ ਕਿਹੜਾ ਪੈਟਰਨ ਫਾਲੋ ਕਰਨਾ ਚਾਹੁੰਦੇ ਹੋ। ਮਾਡਲ ਤੁਹਾਡੇ ਉਦਾਹਰਨਾਂ ਤੋਂ ਇਨਪੁੱਟ-ਆਉਟਪੁੱਟ ਫਾਰਮੈਟ ਸਿੱਖਦਾ ਹੈ ਅਤੇ ਨਵੇਂ ਇਨਪੁੱਟ 'ਤੇ ਲਾਗੂ ਕਰਦਾ ਹੈ। ਇਹ ਉਹਨਾਂ ਕਾਰਜਾਂ ਲਈ ਲਗਾਤਾਰਤਾ ਬੇਹਤਰ ਬਣਾਉਂਦਾ ਹੈ ਜਿੱਥੇ ਮਨਚਾਹਾ ਫਾਰਮੈਟ ਜਾਂ ਰਵੱਈਆ ਸਪੱਸ਼ਟ ਨਹੀਂ ਹੁੰਦਾ। +ਉਦਾਹਰਣ ਦਿਓ ਜੋ ਮਾਡਲ ਨੂੰ ਉਹ ਪੈਟਰਨ ਦਿਖਾਉਂਦੇ ਹਨ ਜਿਸਨੂੰ ਉਹ ਮਾਡਲ ਅਨੁਸਰਣ ਕਰੇ। ਮਾਡਲ ਤੁਹਾਡੇ ਉਦਾਹਰਣਾਂ ਤੋਂ ਇਨਪੁਟ-ਆਉਟਪੁੱਟ ਫਾਰਮੈਟ ਸਿੱਖਦਾ ਹੈ ਅਤੇ ਨਵੇਂ ਇਨਪੁੱਟਾਂ ਤੇ ਪ੍ਰਭਾਵ ਸ਼ੁਰੂ ਕਰਦਾ ਹੈ। ਇਸ ਨਾਲ ਉਹ ਕੰਮ ਜਿੱਥੇ ਚਾਹੀਦਾ ਫਾਰਮੈਟ ਜਾਂ ਵਰਤੋਂ ਸਪਸ਼ਟ ਨਹੀਂ ਹੁੰਦਾ, ਉਨ੍ਹਾਂ ਵਿੱਚ ਲਗਾਤਾਰਤਾ ਵੱਧਦੀ ਹੈ। Few-Shot Prompting -*ਉਦਾਹਰਨਾਂ ਤੋਂ ਸਿੱਖਣਾ — ਮਾਡਲ ਪੈਟਰਨ ਪਛਾਣਦਾ ਹੈ ਅਤੇ ਨਵੇਂ ਇਨਪੁੱਟ 'ਤੇ ਲਾਗੂ ਕਰਦਾ ਹੈ* +*ਉਦਾਹਰਣਾਂ ਤੋਂ ਸਿੱਖਿਅਾ — ਮਾਡਲ ਪੈਟਰਨ ਪਛਾਣਦਾ ਹੈ ਅਤੇ ਨਵੀਆਂ ਐਂਪੁੱਟਾਂ 'ਤੇ ਲਾਗੂ ਕਰਦਾ ਹੈ* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**ਕਦੋਂ ਵਰਤਣਾ:** ਕਸਟਮ ਵਰਗੀਕਰਨ, ਨਿਯਮਤ ਫਾਰਮੈਟਿੰਗ, ਖੇਤਰ-ਨਿਰਧਾਰਿਤ ਕਾਰਜ ਜਾਂ ਜਦੋਂ ਜ਼ੀਰੋ-ਸ਼ਾਟ ਨਤੀਜੇ ਅਸਮਰਥ ਹੋਣ। +**ਕਦੋਂ ਵਰਤਣਾ ਹੈ:** ਕਸਟਮ ਵਰਗੀਕਰਨ, ਲਗਾਤਾਰ ਫਾਰਮੈਟਿੰਗ, ਖੇਤਰ-ਨਿਰਧਾਰਿਤ ਕੰਮ, ਜਾਂ ਜਦੋਂ ਜੀਰੋ-ਸ਼ਾਟ ਨਤੀਜੇ ਅਸਪਸ਼ਟ ਜਾਂ ਅਸਥਿਰ ਹੁੰਦੇ ਹਨ। ### ਚੇਨ ਆਫ ਥੌਟ -ਮਾਡਲ ਨੂੰ ਕਦਮ ਦਰ ਕਦਮ ਆਪਣਾ ਤਰਕ ਦਿਖਾਉਣ ਲਈ ਕਹੋ। ਜਵਾਬ 'ਤੇ ਸਿੱਧਾ ਛਾਲ ਮਾਰਨ ਦੀ ਬਜਾਇ, ਮਾਡਲ ਸਮੱਸਿਆ ਨੂੰ ਤੋੜ ਕੇ ਹਰ ਹਿੱਸਾ ਵਿਸ਼ੇਸ਼ ਤੌਰ 'ਤੇ ਕੰਮ ਕਰਦਾ ਹੈ। ਇਹ ਗਣਿਤ, ਤਰਕ, ਅਤੇ ਬਹੁ-ਕਦਮ ਤਰਕ ਕਾਰਜਾਂ ਲਈ ਸਹੀ ਪ੍ਰਾਪਤੀ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ। +ਮਾਡਲ ਨੂੰ ਕਦਮ-ਦਰ-ਕਦਮ ਆਪਣੀ ਤਰਕਸ਼ੀਲਤਾ ਦਿਖਾਉਣ ਲਈ ਕਹੋ। ਜਵਾਬ 'ਤੇ ਸਿੱਧਾ ਛਾਲ ਮਾਰਨ ਦੀ ਬਜਾਏ, ਮਾਡਲ ਸਮੱਸਿਆ ਨੂੰ ਟੁਕੜਿਆਂ ਵਿੱਚ ਵੰਡਦਾ ਹੈ ਅਤੇ ਹਰ ਹਿੱਸੇ 'ਤੇ ਖੁਲ ਕੇ ਕੰਮ ਕਰਦਾ ਹੈ। ਇਸ ਨਾਲ ਗਣਿਤ, ਤਰਕ, ਅਤੇ ਬਹੁ-ਕਦਮੀ ਤਰਕਸੰਗਤੀ ਵਾਲੇ ਕੰਮਾਂ ਵਿੱਚ ਸਹੀਤਾਵਾ ਵੱਧਦੀ ਹੈ। Chain of Thought Prompting -*ਕਦਮ ਦਰ ਕਦਮ ਤਰਕ — ਜਟਿਲ ਸਮੱਸਿਆਵਾਂ ਨੂੰ ਸਪੱਸ਼ਟ ਤਰਕਸ਼ੀਲ ਕਦਮਾਂ ਵਿੱਚ ਤੋੜਣਾ* +*ਕਦਮ-ਦਰ-ਕਦਮ ਤਰਕ — ਜਟਿਲ ਮੁੱਦਿਆਂ ਨੂੰ ਖੁਲ ਕੇ ਲਾਜ਼ਮੀ ਕਦਮਾਂ ਵਿੱਚ ਵੰਡਨਾ* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // ਮਾਡਲ ਦਿਖਾਉਂਦਾ ਹੈ: 15 - 8 = 7, ਫਿਰ 7 + 12 = 19 ਸੇਬ ``` -**ਕਦੋਂ ਵਰਤਣਾ:** ਗਣਿਤ ਸਮੱਸਿਆਵਾਂ, ਤਰਕ ਪਜ਼ਲ, ਡਿਬੱਗਿੰਗ, ਜਾਂ ਕੋਈ ਵੀ ਕਾਰਜ ਜਿੱਥੇ ਤਰਕ ਪ੍ਰਕਿਰਿਆ ਦਿਖਾਣਾ ਸਹੀਤਾ ਅਤੇ ਭਰੋਸਾ ਵਿੱਚ ਸੁਧਾਰ ਲਿਆਉਂਦਾ ਹੈ। +**ਕਦੋਂ ਵਰਤਣਾ ਹੈ:** ਗਣਿਤ ਸਮੱਸਿਆਵਾਂ, ਤਰਕ ਦਿਲਚਸਪੀ ਦੇ ਮੁੱਦੇ, ਡੀਬੱਗਿੰਗ, ਜਾਂ ਕੋਈ ਵੀ ਕੰਮ ਜਿੱਥੇ ਤਰਕਸ਼ੀਲ ਪ੍ਰਕਿਰਿਆ ਦਰਸਾਉਣ ਨਾਲ ਸਹੀਤਾ ਅਤੇ ਭਰੋਸਾ ਵੱਧਦਾ ਹੈ। -### ਰੋਲ-ਅਧਾਰਿਤ ਪ੍ਰਾਂਪਟਿੰਗ +### ਰੋਲ-ਆਧਾਰਿਤ ਪ੍ਰਾਂਪਟਿੰਗ -ਪ੍ਰਸ਼ਨ ਪੁੱਛਣ ਤੋਂ ਪਹਿਲਾਂ AI ਲਈ ਕਿਰਦਾਰ ਜਾਂ ਭੂਮਿਕਾ ਸੈੱਟ ਕਰੋ। ਇਹ ਸੰਦਰਭ ਦਿੰਦਾ ਹੈ ਜੋ ਜਵਾਬ ਦੇ ਰੂਪ, ਗਹਿਰਾਈ ਅਤੇ ਕੇਂਦ੍ਰਿਤਾ ਨੂੰ ਸ਼ਕਲ ਦਿੰਦਾ ਹੈ। "ਸੌਫਟਵੇਅਰ ਆਰਕੀਟੈਕਟ" ਵੱਖਰਾ ਸਲਾਹ ਦਿੰਦਾ ਹੈ ਬਨਾਮ "ਜੂਨੀਅਰ ਡਿਵੈਲਪਰ" ਜਾਂ "ਸੁਰੱਖਿਆ ਆਡੀਟਰ"। +ਸਵਾਲ ਪੁੱਛਣ ਤੋਂ ਪਹਿਲਾਂ AI ਲਈ ਕੋਈ ਭੂਮਿਕਾ ਜਾਂ ਪਹਚਾਨ ਸੈਟ ਕਰੋ। ਇਹ ਸੰਦਰਭ ਮੁਹੱਈਆ ਕਰਵਾਉਂਦਾ ਹੈ ਜੋ ਜਵਾਬ ਦੇ ਅੰਦਾਜ਼, ਗਹਿਰਾਈ ਅਤੇ ਧਿਆਨ ਨੂੰ ਧਾਰਿਤ ਕਰਦਾ ਹੈ। "ਸੋਫਟਵੇਅਰ ਆਰਕੀਟੈਕਟ" "ਜੂਨੀਅਰ ਡਿਵੈਲਪਰ" ਜਾਂ "ਸੁਰੱਖਿਆ ਆਡੀਟਰ" ਨਾਲੋਂ ਵੱਖਰਾ ਸਲਾਹ ਦਿੰਦਾ ਹੈ। Role-Based Prompting -*ਸੰਦਰਭ ਅਤੇ ਭੂਮਿਕਾ ਸੈੱਟ ਕਰਨਾ — ਇੱਕੋ ਸਵਾਲ ਨੂੰ ਸੌਂਪੇ ਗਏ ਰੋਲ ਮੁਤਾਬਕ ਵੱਖਰੇ ਜਵਾਬ ਮਿਲਦੇ ਹਨ* +*ਸੰਦਰਭ ਅਤੇ ਭੂਮਿਕਾ ਸੈਟ ਕਰਨਾ — ਇੱਕੋ ਸਵਾਲ ਨੂੰ ਸੌਂਪੀ ਗਈ ਭੂਮਿਕਾ ਦੇ ਅਨੁਸਾਰ ਵੱਖਰਾ ਜਵਾਬ ਮਿਲਦਾ ਹੈ* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**ਕਦੋਂ ਵਰਤਣਾ:** ਕੋਡ ਰਿਵਿਊ, ਟਿਊਟਰਨਿੰਗ, ਖੇਤਰ-ਨਿਰਧਾਰਿਤ ਵਿਸ਼ਲੇਸ਼ਣ ਜਾਂ ਜਦ ਤੁਹਾਨੂੰ ਖਾਸ ਮਾਹਿਰਤਾ ਪੱਧਰ ਜਾਂ ਨਜ਼ਰੀਏ ਲਈ ਜਵਾਬ ਚਾਹੀਦੇ ਹੋ। +**ਕਦੋਂ ਵਰਤਣਾ ਹੈ:** ਕੋਡ ਸਮੀਖਿਆ, ਟਿਊਟੋਰਿੰਗ, ਖੇਤਰ-ਵਿਸ਼ਲੇਸ਼ਣ, ਜਾਂ ਜਦੋਂ ਤੁਹਾਨੂੰ ਕਿਸੇ ਮਾਹਿਰ ਦਰਜੇ ਜਾਂ ਦ੍ਰਿਸ਼ਟੀਕੋਣ ਲਈ ਟੇਲਰ ਕੀਤੇ ਜਵਾਬ ਚਾਹੀਦੇ ਹਨ। -### ਪ੍ਰਾਂਪਟ ਟੈਮਪਲੇਟ +### ਪ੍ਰਾਂਪਟ ਟੈਮਪਲੇਟਸ -ਵੈਰੀਏਬਲ ਪਲੇਸਹੋਲਡਰਾਂ ਨਾਲ ਮੁੜ ਵਰਤਣਯੋਗ ਪ੍ਰਾਂਪਟ ਬਣਾਓ। ਹਰ ਵਾਰੀ ਨਵਾਂ ਪ੍ਰਾਂਪਟ ਲਿਖਣ ਦੀ ਬਜਾਇ, ਇਕ ਵਾਰ ਟੈਮਪਲੇਟ ਤਿਆਰ ਕਰੋ ਅਤੇ ਵੱਖ-ਵੱਖ ਕਦਰਾਂ ਨਾਲ ਭਰੋ। LangChain4j ਦੀ `PromptTemplate` ਕਲਾਸ ਇਸਨੂੰ `{{variable}}` ਸੰਟੈਕਸ ਨਾਲ ਆਸਾਨ ਬਣਾਉਂਦੀ ਹੈ। +ਵੈਰੀਏਬਲ ਪਲੇਸਹੋਲਡਰਾਂ ਨਾਲ ਮੁੜ-ਵਰਤੋਂ ਯੋਗ ਪ੍ਰਾਂਪਟ ਬਣਾਓ। ਹਰ ਵਾਰੀ ਨਵਾਂ ਪ੍ਰਾਂਪਟ ਲਿਖਣ ਦੀ ਬਜਾਏ ਇੱਕ ਵਾਰੀ ਟੈਮਪਲੇਟ ਬਣਾਓ ਅਤੇ ਵੱਖਰੇ ਮੁੱਲ ਭਰੋ। LangChain4j ਦੀ `PromptTemplate` ਕਲਾਸ {{variable}} ਵੱਲੇ ਸਿੰਟੈਕਸ ਨਾਲ ਇਹ ਸੌਖਾ ਕਰਦੀ ਹੈ। Prompt Templates -*ਵੈਰੀਏਬਲ ਪਲੇਸਹੋਲਡਰਾਂ ਵਾਲੇ ਮੁੜ ਵਰਤਣਯੋਗ ਪ੍ਰਾਂਪਟ — ਇੱਕ ਟੈਮਪਲੇਟ, ਬਹੁਤ ਸਾਰੀਆਂ ਵਰਤੋਂ* +*ਵੈਰੀਏਬਲ ਪਲੇਸਹੋਲਡਰਾਂ ਵਾਲੇ ਮੁੜ-ਵਰਤੋਂ ਯੋਗ ਪ੍ਰਾਂਪਟ — ਇੱਕ ਹੀ ਟੈਮਪਲੇਟ, ਕਈ ਵਰਤੋਂਵਾਂ* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**ਕਦੋਂ ਵਰਤਣਾ:** ਵੱਖ-ਵੱਖ ਇਨਪੁੱਟਾਂ ਨਾਲ ਦੁਹਰਾਈ ਗਈ ਪੁੱਛਗਿੱਛ, ਬੈਚ ਪ੍ਰੋਸੈਸਿੰਗ, ਮੁੜ ਵਰਤਣਯੋਗ AI ਵਰਕਫਲੋ ਬਨਾਉਣ ਜਾਂ ਕੋਈ ਵੀ ਸਥਿਤੀ ਜਿੱਥੇ ਪ੍ਰਾਂਪਟ ਕੀ ਢਾਂਚਾ ਇੱਕੋ ਰਹਿੰਦਾ ਪਰ ਡੇਟਾ ਬਦਲਦਾ ਰਹਿੰਦਾ ਹੈ। +**ਕਦੋਂ ਵਰਤਣਾ ਹੈ:** ਵੱਖਰੇ ਇਨਪੁੱਟਾਂ ਨਾਲ ਦੁਹਰਾਏ ਜਾਣ ਵਾਲੇ ਪ੍ਰਸ਼ਨਾਂ ਲਈ, ਬੈਚ ਪ੍ਰੋਸੈਸਿੰਗ, ਮੁੜ ਵਰਤੋਂਯੋਗ AI ਵਰਕਫਲੋਜ਼ ਬਣਾਉਣ ਲਈ, ਜਾਂ ਕੋਈ ਵੀ ਸਥਿਤੀ ਜਿੱਥੇ ਪ੍ਰਾਂਪਟ ਸਟ੍ਰਕਚਰ ਇਕੋ ਜਿਹਾ ਰਹਿੰਦਾ ਪਰ ਡੇਟਾ ਵੱਧਦਾ-ਘਟਦਾ ਹੈ। --- -ਇਹ ਪੰਜ ਮੂਲ ਤੱਤ ਤੁਹਾਨੂੰ ਅਕਸਰ ਵਰਤੇ ਜਾਣ ਵਾਲੇ ਜ਼ਿਆਦातर ਕਾਰਜਾਂ ਲਈ ਮਜ਼ਬੂਤ ਟੂਲਕਿਟ ਦਿੰਦੇ ਹਨ। ਇਸ ਮਾਡਿਊਲ ਦਾ ਬਾਕੀ ਹਿੱਸਾ ਇਨ੍ਹਾਂ 'ਤੇ ਅੱਠ ਉਨੱਤ ਪੈਟਰਨਾਂ ਦਾ ਨਿਰਮਾਣ ਕਰਦਾ ਹੈ ਜੋ GPT-5.2 ਦੀ ਤਰਕ ਕੰਟਰੋਲ, ਸੁਆਤਮ ਮੁਲਾਂਕਣ, ਅਤੇ ਸੰਰਚਿਤ ਆਉਟਪੁੱਟ ਖੂਬੀਆਂ ਦਾ ਲਾਹਾ ਉਠਾਉਂਦੇ ਹਨ। +ਇਹ ਪੰਜ ਮੁਢਲੇ ਤੱਤ ਤੁਹਾਨੂੰ ਅਕਸਰ ਪ੍ਰਾਂਪਟਿੰਗ ਕੰਮਾਂ ਲਈ ਦ੍ਰਿੜ ਟੂਲਕਿਟ ਦੇਂਦੇ ਹਨ। ਇਸ ਮਾਡਿਊਲ ਦਾ ਬਾਕੀ ਹਿਸਾ GPT-5.2 ਦੀ ਤਰਕ ਨਿਯੰਤਰਣ, ਸਵੈ-ਮੁਲਾਂਕਣ ਅਤੇ ਸੰਰਚਿਤ ਆਉਟਪੁੱਟ ਸਮਰੱਥਾਵਾਂ ਨਾਲ ਲੈਵਰੇਜ ਕਰਨ ਵਾਲੇ **ਅੱਠ ਅਡਵਾਂਸ ਪੈਟਰਨਾਂ** ਤੇ ਕਰਦਾ ਹੈ। -## ਉਨੱਤ ਪੈਟਰਨ +## ਅਡਵਾਂਸ ਪੈਟਰਨਸ -ਮੂਲ ਤੱਤ ਕਵਰ ਕਰਨ ਤੋਂ ਬਾਅਦ, ਆਓ ਉਨ੍ਹਾਂ ਅੱਠ ਉਨੱਤ ਪੈਟਰਨਾਂ ਤੇ ਜਾਏ ਜੋ ਇਸ ਮਾਡਿਊਲ ਨੂੰ ਵਿਲੱਖਣ ਬਣਾਉਂਦੇ ਹਨ। ਸਾਰੀਆਂ ਸਮੱਸਿਆਵਾਂ ਲਈ ਇੱਕੋ ਜਿਹੀ ਪদ্ধਤੀ ਦੀ ਲੋੜ ਨਹੀਂ ਹੁੰਦੀ। ਕੁਝ ਸਵਾਲਾਂ ਨੂੰ ਤੇਜ਼ ਜਵਾਬ ਚਾਹੀਦੇ ਹਨ, ਕੁਝ ਨੂੰ ਡੂੰਘੀ ਸੋਚ। ਕੁਝ ਨੂੰ ਦਿਖਾਈ ਦੇਣ ਵਾਲਾ ਤਰਕ ਚਾਹੀਦਾ ਹੈ, ਕੁਝ ਸਿਰਫ ਨਤੀਜੇ। ਹੇਠਾਂ ਦਿੱਤੇ ਹਰ ਪੈਟਰਨ ਨੂੰ ਕਿਸੇ ਵਿਸ਼ੇਸ਼ ਸੰਦਰਭ ਲਈ ਅਨੁਕੂਲ ਕੀਤਾ ਗਿਆ ਹੈ — ਅਤੇ GPT-5.2 ਦੀ ਤਰਕ ਕੰਟਰੋਲ ਇਹ ਵੱਖਰਾ ਹੋਰ ਵੱਧ ਪ੍ਰਗਟ ਕਰਦਾ ਹੈ। +ਮੁਢਲੇ ਤੱਤ ਕਵਰ ਹੋ ਗਏ ਹਨ, ਹੁਣ ਅਸੀਂ ਕੁਝ ਨਾ ਜੁੜੇ ਅੱਠ ਅਡਵਾਂਸ ਪੈਟਰਨਾਂ ਵਿੱਚ ਜਾਵਾਂਗੇ ਜੋ ਇਸ ਮਾਡਿਊਲ ਨੂੰ ਵਿਸ਼ੇਸ਼ ਬਣਾਉਂਦੇ ਹਨ। ਸਾਰੇ ਸਮੱਸਿਆਵਾਂ ਲਈ ਇੱਕੋ ਤਰੀਕਾ ਜ਼ਰੂਰੀ ਨਹੀਂ। ਕੁਝ ਪ੍ਰਸ਼ਨਾਂ ਲਈ ਤੇਜ਼ ਜਵਾਬ ਚਾਹੀਦਾ ਹੈ, ਕੁਝ ਲਈ ਗਹਿਰਾਈ ਨਾਲ ਸੋਚ। ਕੁਝ ਲਈ ਤਰਕ ਸਪਸ਼ਟ ਹੋਣੀ ਚਾਹੀਦੀ ਹੈ, ਕੁਝ ਲਈ ਸਿਰਫ ਨਤੀਜੇ ਚਾਹੀਦੇ ਹਨ। ਹੇਠਾਂ ਹਰ ਪੈਟਰਨ ਵੱਖਰੇ ਸਥਿਤੀ ਲਈ ਸੁਚੱਜਾ ਕੀਤਾ ਗਿਆ ਹੈ — ਅਤੇ GPT-5.2 ਦਾ ਤਰਕ ਨਿਯੰਤਰਣ ਇਹ ਫਰਕ ਹੋਰ ਸਪਸ਼ਟ ਕਰਦਾ ਹੈ। Eight Prompting Patterns -*ਅੱਠ ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਪੈਟਰਨ ਅਤੇ ਉਨ੍ਹਾਂ ਦੇ ਵਰਤੋਂ ਦੇ ਮਾਮਲੇ* +*ਅੱਠ ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਪੈਟਰਨਾਂ ਅਤੇ ਉਹਨਾਂ ਦੇ ਵਰਤੋਂ ਦੇ ਕੇਸਾਂ ਦਾ ਸਾਰਾਂਸ਼* -GPT-5.2 ਇਨ੍ਹਾਂ ਪੈਟਰਨਾਂ ਵਿਚ ਇੱਕ ਹੋਰ ਪਰਤ ਜੋੜਦਾ ਹੈ: *ਤਰਕ ਕੰਟਰੋਲ*। ਹੇਠਾਂ ਦਿੱਤਾ ਸਲਾਈਡਰ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਤੁਸੀਂ ਮਾਡਲ ਦੀ ਸੋਚਣ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਿਵੇਂ ਸਮੱਝ ਸਕਦੇ ਹੋ — ਤੇਜ਼, ਸਿੱਧੇ ਜਵਾਬਾਂ ਤੋਂ ਲੈ ਕੇ ਡੂੰਘੀ, ਵਿਆਪਕ ਵਿਸ਼ਲੇਸ਼ਣ ਤੱਕ। +GPT-5.2 ਇਨ੍ਹਾਂ ਪੈਟਰਨਾਂ ਵਿੱਚ ਹੋਰ ਇੱਕ ਪਰਤ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ: *ਤਰਕ ਨਿਯੰਤਰਣ*। ਹੇਠਾਂ ਦਿਤਾ ਸਲਾਈਡਰ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਅਸੀਂ ਮਾਡਲ ਦੀ ਸੋਚ ਵਾਲੀ ਮਿਹਨਤ ਕਿਵੇਂ ਸੈਟ ਕਰ ਸਕਦੇ ਹਾਂ — ਤੇਜ਼, ਸਿੱਧਾ ਜਵਾਬ ਤੋਂ ਲੈ ਕੇ ਗਹਿਰਾਈ ਨਾਲ ਵਿਸ਼ਲੇਸ਼ਣ ਤੱਕ। Reasoning Control with GPT-5.2 -*GPT-5.2 ਦਾ ਤਰਕ ਕੰਟਰੋਲ ਤੁਹਾਨੂੰ ਦੱਸਦਾ ਹੈ ਕਿ ਮਾਡਲ ਨੂੰ ਕਿੰਨੀ ਸੋਚਣਾ ਚਾਹੀਦਾ ਹੈ — ਤੇਜ਼ ਸਿੱਧੇ ਜਵਾਬਾਂ ਤੋਂ ਲੈ ਕੇ ਡੂੰਘੀ ਖੋਜ ਤੱਕ* +*GPT-5.2 ਦਾ ਤਰਕ ਨਿਯੰਤਰਣ ਤੁਹਾਨੂੰ ਦੱਸਣ ਦਿੰਦਾ ਹੈ ਕਿ ਮਾਡਲ ਕਿੰਨੀ ਸੋਚਣਾ ਚਾਹੀਦਾ ਹੈ — ਤੇਜ਼ ਸਿੱਧੇ ਜਵਾਬ ਤੋਂ ਲੈ ਕੇ ਗਹਿਰੇ ਅਨੁਸੰਧਾਨ ਤੱਕ* -**ਘੱਟ ਉਤਸ਼ਾਹ (ਤੇਜ਼ ਅਤੇ ਕੇਂਦਰਿਤ)** - ਸਧਾਰਣ ਸਵਾਲਾਂ ਲਈ ਜਿੱਥੇ ਤੁਸੀਂ ਤੇਜ਼, ਸਿੱਧਾ ਜਵਾਬ ਚਾਹੁੰਦੇ ਹੋ। ਮਾਡਲ ਘੱਟ ਤਰਕ ਕਰਦਾ ਹੈ - ਵੱਧ ਤੋਂ ਵੱਧ 2 ਕਦਮ। ਇਸਨੂੰ ਗਣਨਾ, ਲੁਕਪ, ਜਾਂ ਸਿੱਧੇ ਸਵਾਲਾਂ ਲਈ ਵਰਤੋ। +**ਘੱਟ ਉਤਸ਼ਾਹ (ਤੇਜ਼ ਅਤੇ ਕੇਂਦਰਿਤ)** - ਸਧਾਰਣ ਸਵਾਲਾਂ ਲਈ ਜਿੱਥੇ ਤੁਸੀਂ ਤੇਜ਼ ਅਤੇ ਸਿੱਧੇ ਜਵਾਬ ਚਾਹੁੰਦੇ ਹੋ। ਮਾਡਲ ਘੱਟ ਤਰਕ ਕਰਦਾ ਹੈ - ਵੱਧ ਤੋਂ ਵੱਧ 2 ਕਦਮ। ਗਣਨਾ, ਲੁੱਕਅੱਪ, ਜਾਂ ਸਧਾਰਣ ਸਵਾਲਾਂ ਲਈ ਵਰਤੋਂ ਕਰੋ। ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **GitHub Copilot ਨਾਲ ਖੋਜੋ:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "ਘੱਟ ਉਤਸ਼ਾਹ ਅਤੇ ਜ਼ਿਆਦਾ ਉਤਸ਼ਾਹ ਵਾਲੇ ਪ੍ਰਾਂਪਟ ਪੈਟਰਨਾਂ ਵਿੱਚ ਕੀ ਫਰਕ ਹੈ?" -> - "ਪ੍ਰਾਂਪਟਾਂ ਵਿੱਚ XML ਟੈਗਸ AI ਦੇ ਜਵਾਬ ਦੇ ਢਾਂਚੇ ਵਿੱਚ ਕਿਵੇਂ ਮਦਦ ਕਰਦੇ ਹਨ?" -> - "ਮੈਂ ਕਦੋਂ ਸਵੈ-ਪਰਖ ਪੈਟਰਨ ਵਰਤਾਂ ਅਤੇ ਕਦੋਂ ਸਿੱਧਾ ਹੁਕਮ ਦਿਆਂ?" +> 💡 **GitHub Copilot ਨਾਲ ਖੋਜ ਕਰੋ:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: +> - "ਘੱਟ ਉਤਸ਼ਾਹ ਅਤੇ ਉੱਚ ਉਤਸ਼ਾਹ ਪ੍ਰਾਂਪਟਿੰਗ ਪੈਟਰਨਾਂ ਵਿੱਚ ਕੀ ਫਰਕ ਹੈ?" +> - "ਪ੍ਰਾਂਪਟਾਂ ਵਿੱਚ XML ਟੈਗ AI ਦੇ ਜਵਾਬ ਨੂੰ ਕਿਵੇਂ ਬਣਾਉਂਦੇ ਹਨ?" +> - "ਮੈਂ ਸਵੈ-ਚਿੰਤਨ ਵਾਲੇ ਪੈਟਰਨ ਕਿਵੇਂ ਅਤੇ ਕਦੋਂ ਵਰਤਾਂ ਬਨਾਮ ਸਿੱਧੇ ਹੁਕਮ?" -**ਜ਼ਿਆਦਾ ਉਤਸ਼ਾਹ (ਡੂੰਘੀ ਅਤੇ ਵਿਆਪਕ)** - ਜਟਿਲ ਸਮੱਸਿਆਵਾਂ ਲਈ ਜਿੱਥੇ ਤੁਸੀਂ ਵਿਆਪਕ ਵਿਸ਼ਲੇਸ਼ਣ ਚਾਹੁੰਦੇ ਹੋ। ਮਾਡਲ ਬਾਰੀਕੀ ਨਾਲ ਸਮਗਤਾ ਬਣਾਂਦਾ ਹੈ ਅਤੇ ਤਰਕ ਨੂੰ ਵੇਖਾਉਂਦਾ ਹੈ। ਇਸਨੂੰ ਸਿਸਟਮ ਡਿਜ਼ਾਈਨ, ਆਰਕੀਟੈਕਚਰ ਫੈਸਲੇ ਜਾਂ ਜਟਿਲ ਖੋਜ ਲਈ ਵਰਤੋਂ। +**ਉੱਚ ਉਤਸ਼ਾਹ (ਗਹਿਰਾਈ ਨਾਲ ਅਤੇ ਵਿਸਥਾਰ ਵਿੱਚ)** - ਜਟਿਲ ਸਮੱਸਿਆਵਾਂ ਲਈ ਜਿੱਥੇ ਤੁਸੀਂ ਵਿਸਥਾਰਪੂਰਵਕ ਵਿਸ਼ਲੇਸ਼ਣ ਚਾਹੁੰਦੇ ਹੋ। ਮਾਡਲ ਗਭੀਰਤਾ ਨਾਲ ਪ੍ਰਗਟਾਊਂਦਾ ਹੈ ਅਤੇ ਵਿਸ਼ਤਰੀਤ ਤਰਕ ਦਿਖਾਉਂਦਾ ਹੈ। ਸਿਸਟਮ ਡਿਜ਼ਾਈਨ, ਆਰਕੀਟੈਕਚਰ ਫੈਸਲੇ, ਜਾਂ ਗੁੰਝਲਦਾਰ ਖੋਜਾਂ ਲਈ ਵਰਤੋਂ ਕਰੋ। ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**ਕਾਰਜ ਨਿਰਵਾਹ (ਕਦਮ ਦਰ ਕਦਮ ਪ੍ਰਗਤੀ)** - ਬਹੁ-ਕਦਮ ਵਰਕਫਲੋਜ਼ ਲਈ। ਮਾਡਲ ਪਹਿਲਾਂ ਹੀ ਇੱਕ ਯੋਜਨਾ ਦਿੰਦਾ ਹੈ, ਹਰ ਕਦਮ ਨੂੰ ਕੰਮ ਕਰਦਿਆਂ ਦਰਸਾਉਂਦਾ ਹੈ, ਫਿਰ ਸੰਖੇਪ ਦਿੰਦਾ ਹੈ। ਇਸਨੂੰ ਮਾਈਗ੍ਰੇਸ਼ਨ, ਲਾਗੂ ਕਰਨ ਜਾਂ ਕਿਸੇ ਵੀ ਬਹੁ-ਕਦਮ ਪ੍ਰਕਿਰਿਆ ਲਈ ਵਰਤੋਂ। +**ਕੰਮ ਦੀ ਕਾਰਗੁਜ਼ਾਰੀ (ਕਦਮ-ਦਰ-ਕਦਮ ਪ੍ਰਗਟਾਊ)** - ਬਹੁ-ਕਦਮੀ ਕਾਰਜ ਪ੍ਰਕਿਰਿਆਵਾਂ ਲਈ। ਮਾਡਲ ਪਹਿਲਾਂ ਇੱਕ ਯੋਜਨਾ ਦਿੰਦਾ ਹੈ, ਹਰ ਕਦਮ ਨੂੰ ਕਹਾਣੀ ਵਾਂਗ ਕਵਰ ਕਰਦਾ ਹੈ, ਫਿਰ ਸੰਖੇਪ ਦਿੰਦਾ ਹੈ। ਮਾਈਗ੍ਰੇਸ਼ਨ, ਲਾਗੂ ਕਰਨ, ਜਾਂ ਕੋਈ ਵੀ ਬਹੁ-ਕਦਮੀ ਪ੍ਰਕਿਰਿਆ ਲਈ ਵਰਤੋਂ ਕਰੋ। ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ਚੇਨ-ਆਫ-ਥੌਟ ਪ੍ਰਾਂਪਟਿੰਗ ਖੁਲ ਕੇ ਮਾਡਲ ਨੂੰ ਆਪਣੇ ਤਰਕ ਪ੍ਰਕਿਰਿਆ ਨੂੰ ਦਿਖਾਉਣ ਲਈ ਕਹਿੰਦਾ ਹੈ, ਜੋ ਕਿ ਜਟਿਲ ਕਾਰਜਾਂ ਲਈ ਸਹੀਤਾ ਵਿੱਚ ਸੁਧਾਰ ਲਿਆਉਂਦਾ ਹੈ। ਕਦਮਾਂ ਦਾ ਇਹ ਵਿਸ਼ਲੇਸ਼ਣ ਮਨੁੱਖਾਂ ਅਤੇ AI ਦੋਹਾਂ ਨੂੰ ਤਰਕ ਸਮਝਣ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ। +ਚੇਨ-ਆਫ-ਥੌਟ ਪ੍ਰਾਂਪਟਿੰਗ ਮਾਡਲ ਨੂੰ ਆਪਣੇ ਤਰਕ ਪ੍ਰਕਿਰਿਆ ਨੂੰ ਦਰਸਾਉਣ ਲਈ ਵੱਖਰੇ ਕਦਮਾਂ 'ਚ ਵਿਭਾਜਿਤ ਕਰਨ ਲਈ ਕਹਿੰਦੀ ਹੈ, ਜਿਸ ਨਾਲ ਜਟਿਲ ਕਾਰਜਾਂ ਵਿੱਚ ਸਹੀਤਾ ਵੱਧਦੀ ਹੈ। ਕਦਮ-ਦਰ-ਕਦਮ ਖੰਡਾਂ ਮਨੁੱਖਾਂ ਅਤੇ AI ਦੋਹਾਂ ਨੂੰ ਤਰਕ ਸਮਝਣ ਵਿੱਚ ਮਦਦ ਕਰਦੀਆਂ ਹਨ। -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ਚੈਟ ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** ਇਸ ਪੈਟਰਨ ਬਾਰੇ ਪੁੱਛੋ: -> - "ਮੈਂ ਲੰਬੇ ਸਮੇਂ ਵਾਲੇ ਪ੍ਰਕਿਰਿਆਵਾਂ ਲਈ ਕਾਰਜ ਨਿਰਵਾਹ ਪੈਟਰਨ ਕਿਵੇਂ ਅਨੁਕੂਲਿਤ ਕਰ ਸਕਦਾ ਹਾਂ?" -> - "ਉਤਪਾਦਨ ਐਪਲੀਕੇਸ਼ਨਾਂ ਵਿੱਚ ਟੂਲ ਪ੍ਰੀਐਮਬਲਾਂ ਦਾ ਢਾਂਚਾ ਬਣਾਉਣ ਲਈ ਕੀ ਬਿਹਤਰ ਅਭਿਆਸ ਹਨ?" -> - "ਮੈਂ ਮੱਧਵਰਤੀ ਪ੍ਰਗਤੀ ਅੱਪਡੇਟਾਂ UI ਵਿੱਚ ਕਿਵੇਂ ਕੈਪਚਰ ਅਤੇ ਦਰਸਾ ਸਕਦਾ ਹਾਂ?" +> **🤖 GitHub Copilot [ਚੈਟ](https://github.com/features/copilot) ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** ਇਸ ਪੈਟਰਨ ਬਾਰੇ ਪੁੱਛੋ: +> - "ਲੰਬੇ ਸਮੇ ਤਕ ਚੱਲ ਰਹੀਆਂ ਕਾਰਵਾਈਆਂ ਲਈ ਕਾਰਜ ਪ੍ਰਦਰਸ਼ਨ ਪੈਟਰਨ ਨੂੰ ਕਿਵੇਂ ਢਾਲਾਂ?" +> - "ਪ੍ਰੋਡਕਸ਼ਨ ਐਪਲੀਕੇਸ਼ਨਾਂ ਵਿੱਚ ਟੂਲ ਪ੍ਰੀਐਂਬਲਾਂ ਦੇ ਲਈ ਸੁਰੱਖਿਅਤ ਰੂਪ-ਰੇਖਾ ਕੀ ਹੈ?" +> - "UI ਵਿੱਚ ਮਧਿਆਨ ਤਰੱਕੀ ਅੱਪਡੇਟ ਕਿਵੇਂ ਕੈਪਚਰ ਅਤੇ ਦਿਖਾਈ ਜਾ ਸਕਦੀ ਹੈ?" -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਇਸ ਯੋਜਨਾ → ਨਿਰਵਾਹ → ਸੰਖੇਪ ਵਰਕਫਲੋ ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ। +ਹੇਠਾਂ ਦਿੱਤੀ ਚਿੱਤਰਕਲਾ ਇਸ ਯੋਜਨਾ → ਅਮਲ → ਸੰਖੇਪ ਕਰਨ ਵਾਲੇ ਵਰਕਫਲੋ ਨੂੰ ਦਰਸਾਉਂਦੀ ਹੈ। Task Execution Pattern -*ਬਹੁ-ਕਦਮੀ ਕਾਰਜਾਂ ਲਈ ਯੋਜਨਾ → ਨਿਰਵਾਹ → ਸੰਖੇਪ ਵਰਕਫਲੋ* +*ਬਹੁ-ਕਦਮੀ ਕਾਰਜਾਂ ਲਈ ਯੋਜਨਾ → ਅਮਲ → ਸੰਖੇਪ ਵਰਕਫਲੋ* -**ਆਪਣੇ ਆਪ ਦੀ ਪਰਖ ਕਰਨ ਵਾਲਾ ਕੋਡ** - ਉਤਪਾਦਨ ਮਿਆਰਾਂ ਦੇ ਅਨੁਸਾਰ ਕੋਡ ਬਣਾਉਣ ਲਈ। ਮਾਡਲ ਧੁਰਪੂਰਨ ਐਰਰ ਯੋਜਨਾ ਅਤੇ ਸਹੀ ਵਿਸ਼ੇਸ਼ਤਾਂ ਦੇ ਨਾਲ ਕੋਡ ਤਿਆਰ ਕਰਦਾ ਹੈ। ਇਸਨੂੰ ਨਵੀਂ ਵਿਸ਼ੇਸ਼ਤਾਂ ਜਾਂ ਸੇਵਾਵਾਂ ਬਣਾਉਂਦੇ ਸਮੇਂ ਵਰਤੋ। +**ਆਪਣੇ ਆਪ 'ਤੇ ਵਿਚਾਰ ਕਰਨ ਵਾਲਾ ਕੋਡ** - ਉਤਪਾਦਨ-ਗੁਣਵੱਤਾ ਵਾਲਾ ਕੋਡ ਤਿਆਰ ਕਰਨ ਲਈ। ਮਾਡਲ ਉਤਪਾਦਨ ਮਿਆਰਾਂ ਅਨੁਸਾਰ ਕੋਡ ਤਿਆਰ ਕਰਦਾ ਹੈ ਜਿਸ ਵਿੱਚ ਸਹੀ ਤਰ੍ਹਾਂ ਲਈ ਏਰਰ ਹੈਂਡਲਿੰਗ ਵੀ ਹੁੰਦੀ ਹੈ। ਨਵੀ ਫੀਚਰ ਜਾਂ ਸੇਵਾਵਾਂ ਬਣਾਉਂਦੇ ਸਮੇਂ ਵਰਤੋਂ ਕਰੋ। ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਇਸ ਆਵਰਤੀ ਸੁਧਾਰ ਲੂਪ ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ — ਤਿਆਰ ਕਰੋ, ਮੁਲਾਂਕਣ ਕਰੋ, ਕਮਜ਼ੋਰੀਆਂ ਪਛਾਣੋ, ਅਤੇ ਜਦ ਤੱਕ ਕੋਡ ਉਤਪਾਦਨ ਮਿਆਰ ਨੂੰ ਪੂਰਾ ਨਹੀਂ ਕਰਦਾ ਸੁਧਾਰ ਕਰਦੇ ਰਹੋ। +ਹੇਠਾਂ ਦਿੱਤਾ ਚਿੱਤਰ ਇਸ ਦੁਹਰਾਏ ਜਾਂਦੇ ਸੁਧਾਰ ਚੱਕਰ ਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ — ਤਿਆਰ ਕਰੋ, ਮੂਲਾਂਕਣ ਕਰੋ, ਕਮਜ਼ੋਰੀਆਂ ਪਛਾਣੋ ਅਤੇ ਮਿਆਰਾਂ ਵਧਾਉਂਦੇ ਜਾਓ ਜਦ ਤੱਕ ਕੋਡ ਉਤਪਾਦਨ ਮਿਆਰਾਂ 'ਤੇ ਖਰਾ ਨਾ ਉਤਰ ਜਾਏ। Self-Reflection Cycle -*ਆਵਰਤੀ ਸੁਧਾਰ ਲੂਪ - ਤਿਆਰ ਕਰੋ, ਮੁਲਾਂਕਣ ਕਰੋ, ਮੁੱਦੇ ਪਛਾਣੋ, ਸੁਧਾਰ ਕਰੋ, ਦੁਹਰਾਓ* +*ਦੁਹਰਾਉਂਦਾ ਸੁਧਾਰ ਚੱਕਰ - ਤਿਆਰ ਕਰੋ, ਅੰਕੜਾ ਲਗਾਓ, ਮੁੱਦੇ ਪਛਾਣੋ, ਸੁਧਾਰੋ, ਦੁਹਰਾਓ* -**ਸੰਰਚਿਤ ਵਿਸ਼ਲੇਸ਼ਣ** - ਲਗਾਤਾਰ ਮੁਲਾਂਕਣ ਲਈ। ਮਾਡਲ ਕੋਡ ਦੀ ਸਮੀਖਿਆ ਇੱਕ ਨਿਰਧਾਰਤ ਫਰੇਮਵਰਕ ਨਾਲ (ਸਹੀਤਾ, ਅਭਿਆਸ, ਪ੍ਰਦਰਸ਼ਨ, ਸੁਰੱਖਿਆ, ਬਰਕਰਾਰਤਾ) ਕਰਦਾ ਹੈ। ਇਸਨੂੰ ਕੋਡ ਰਿਵੀਉ ਜਾਂ ਮਿਆਰੀਕਰਨ ਲਈ ਵਰਤੋ। +**ਸੰਰਚਿਤ ਵਿਸ਼ਲੇਸ਼ਣ** - ਲਗਾਤਾਰ ਮੁਲਾਂਕਣ ਲਈ। ਮਾਡਲ ਕੋਡ ਦਾ ਸਮੀਖਿਆ ਕਰਦਾ ਹੈ ਇੱਕ ਫਿਕਸਡ ਫਰੇਮਵਰਕ ਨਾਲ (ਸਹੀਤਾ, ਅਮਲ, ਕਾਰਗੁਜ਼ਾਰੀ, ਸੁਰੱਖਿਆ, ਸਮਭਾਲਯੋਗਤਾ)। ਕੋਡ ਸਮੀਖਿਆ ਜਾਂ ਗੁਣਵੱਤਾ ਮੂਲਾਂਕਣ ਲਈ ਵਰਤੋ। ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 [GitHub Copilot](https://github.com/features/copilot) ਚੈਟ ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** ਸੰਰਚਿਤ ਵਿਸ਼ਲੇਸ਼ਣ ਬਾਰੇ ਪੁੱਛੋ: -> - "ਮੈਂ ਵੱਖ-ਵੱਖ ਕਿਸਮਾਂ ਦੇ ਕੋਡ ਰਿਵੀਉ ਲਈ ਵਿਸ਼ਲੇਸ਼ਣ ਫਰੇਮਵਰਕ ਕਿਵੇਂ ਕਸਟਮਾਈਜ਼ ਕਰ ਸਕਦਾ ਹਾਂ?" -> - "ਕਾਰਜਕਾਰੀ ਤਰੀਕੇ ਨਾਲ ਸੰਰਚਿਤ ਆਉਟਪੁੱਟ ਨੂੰ ਕਿਵੇਂ ਵਿਖੇੜਾ ਅਤੇ ਕਾਰਵਾਈ ਕਰਨੀ ਹੈ?" -> - "ਮੈਂ ਵੱਖ-ਵੱਖ ਰਿਵਿਊ ਸੈਸ਼ਨਾਂ ਵਿੱਚ ਲਗਾਤਾਰ ਗੰਭੀਰਤਾ ਪੱਧਰ ਕਿਵੇਂ ਯਕੀਨੀ ਬਣਾਉਂਦਾ ਹਾਂ?" +> **🤖 GitHub Copilot [ਚੈਟ](https://github.com/features/copilot) ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** ਸੰਰਚਿਤ ਵਿਸ਼ਲੇਸ਼ਣ ਬਾਰੇ ਪੁੱਛੋ: +> - "ਵੱਖ-ਵੱਖ ਕਿਸਮਾਂ ਦੀਆਂ ਕੋਡ ਸਮੀਖਿਆਵਾਂ ਲਈ ਵਿਸ਼ਲੇਸ਼ਣ ਫਰੇਮਵਰਕ ਕਿਵੇਂ ਕਸਟਮਾਈਜ਼ ਕਰਾਂ?" +> - "ਸੰਰਚਿਤ ਆਉਟਪੁੱਟ ਨੂੰ ਪ੍ਰੋਗਰਾਮੈਟਿਕ ਤਰੀਕੇ ਨਾਲ ਕਿਵੇਂ ਪਾਰਸ ਅਤੇ ਕਾਰਵਾਈ ਕਰਾਂ?" +> - "ਲਗਾਤਾਰ ਸਮੀਖਿਆ ਸੈਸ਼ਨਾਂ ਦੌਰਾਨ ਸਖ਼ਤੀ ਦੀ ਸਤਰ ਕਿਵੇਂ ਯਕੀਨੀ ਬਣਾਈ ਜਾ ਸਕਦੀ ਹੈ?" -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਇਹ ਸੰਰਚਿਤ ਫਰੇਮਵਰਕ ਸਖਤ ਸ਼੍ਰੇਣੀਆਂ ਨਾਲ ਕੋਡ ਰਿਵੀਉ ਕਿਵੇਂ ਸੰਗਠਿਤ ਕਰਦਾ ਹੈ। +ਹੇਠਾਂ ਦਿੱਤਾ ਗ੍ਰਾਫਿਕ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਇਹ ਫਰੇਮਵਰਕ ਕਿਵੇਂ ਇੱਕ ਕੋਡ ਸਮੀਖਿਆ ਨੂੰ ਲਗਾਤਾਰ ਸ਼੍ਰੇਣੀਆਂ ਅਤੇ ਸਖ਼ਤੀ ਸਤਰਾਂ ਵਿੱਚ ਵੰਡਦਾ ਹੈ। Structured Analysis Pattern -*ਗੰਭੀਰਤਾ ਪੱਧਰਾਂ ਨਾਲ ਸਤਤ ਕੋਡ ਰਿਵਿਊ ਲਈ ਫਰੇਮਵਰਕ* +*ਲਗਾਤਾਰ ਕੋਡ ਸਮੀਖਿਆਆਂ ਲਈ ਫਰੇਮਵਰਕ ਸਖ਼ਤੀ ਸਤਰਾਂ ਸਹਿਤ* -**ਬਹੁ-ਚਿਰ ਚੈਟ** - ਸੰਵਾਦਾਂ ਲਈ ਜਿਨ੍ਹਾਂ ਨੂੰ ਸੰਦਰਭ ਦੀ ਲੋੜ ਹੈ। ਮਾਡਲ ਪਹਿਲੀਆਂ ਸੁਨੇਹਿਆਂ ਨੂੰ ਯਾਦ ਰੱਖਦਾ ਹੈ ਅਤੇ ਉਨ੍ਹਾਂ ਦੇ ਆਧਾਰ 'ਤੇ ਬੱਲੇ ਅਤੇ ਵਧਾਉਂਦਾ ਹੈ। ਇਸਨੂੰ ਇੰਟਰਐਕਟਿਵ ਸਹਾਇਤਾ ਸੈਸ਼ਨਾਂ ਜਾਂ ਜਟਿਲ ਪੁੱਛਗਿੱਛ ਲਈ ਵਰਤੋਂ। +**ਮਲਟੀ-ਟਰਨ ਚੈਟ** - ਗੱਲਬਾਤਾਂ ਲਈ ਜੋ ਸੰਦਰਭ ਦੀ ਲੋੜ ਰੱਖਦੀਆਂ ਹਨ। ਮਾਡਲ ਪਹਿਲਾਂ ਦੇ ਸੁਨੇਹਿਆਂ ਨੂੰ ਯਾਦ ਰੱਖਦਾ ਹੈ ਅਤੇ ਉਹਨਾਂ 'ਤੇ ਬਣਦਾ ਹੈ। ਇੰਟਰਐਕਟਿਵ ਸਹਾਇਤਾ ਸੈਸ਼ਨਾਂ ਜਾਂ ਜਟਿਲ ਸਵਾਲ-ਜਵਾਬ ਲਈ ਵਰਤੋਂ ਕਰੋ। ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਦਰਸਾਉਂਦਾ ਹੈ ਕਿ ਕਿਵੇਂ ਗੱਲਬਾਤ ਦਾ ਸੰਦਰਭ ਹਰ ਵਾਰੀ ਵਧਦਾ ਹੈ ਅਤੇ ਇਹ ਮਾਡਲ ਦੇ ਟੋਕਨ ਸੀਮਾ ਨਾਲ ਕਿਵੇਂ ਸੰਬੰਧਿਤ ਹੈ। +ਹੇਠਾਂ ਦਿੱਤਾ ਚਿੱਤਰ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਗੱਲਬਾਤ ਦਾ ਸੰਦਰਭ ਕਿਵੇਂ ਬਹੁ-ਟਰਨ ਵਿੱਚ ਇਕੱਠਾ ਹੁੰਦਾ ਹੈ ਅਤੇ ਇਸ ਦਾ ਮਾਡਲ ਦੇ ਟੋਕਨ ਸੀਮਾ ਨਾਲ ਕਿਵੇਂ ਸਬੰਧ ਹੈ। Context Memory -*ਕਿਵੇਂ ਗੱਲਬਾਤ ਦਾ ਸੰਦਰਭ ਕਈ ਵਾਰਾਂ ਲਈ ਇਕੱਤਰ ਹੁੰਦਾ ਹੈ ਜੋ ਟੋਕਨ ਸੀਮਾ ਤੱਕ ਪਹੁੰਚਦਾ ਹੈ* -**ਕਦਮ-ਦਰ-ਕਦਮ ਤਰਕਸ਼ੀਲਤਾ** - ਉਹਨਾਂ ਮੁੱਦਿਆਂ ਲਈ ਜਿਨ੍ਹਾਂ ਨੂੰ ਵਿਖਾਈ ਦੇਣ ਵਾਲੀ ਤਰਕ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ। ਮਾਡਲ ਹਰ ਕਦਮ ਲਈ ਸਵਤੰਤਰ ਤਰਕ ਦਰਸਾਉਂਦਾ ਹੈ। ਇਸਨੂੰ ਗਣਿਤ ਦੇ ਪ੍ਰਸ਼ਨਾਂ, ਤਰਕ ਚਤੁਰਾਈ ਲਈ ਉੱਤਰ ਲੱਭਣ ਲਈ ਜਾਂ ਜਦੋਂ ਤੁਸੀਂ ਸੋਚਣ ਦੀ ਪ੍ਰਕਿਰਿਆ ਨੂੰ ਸਮਝਣਾ ਚਾਹੁੰਦੇ ਹੋ ਤਦ ਵਰਤੋਂ ਕਰੋ। +*ਕਿਵੇਂ ਗੱਲਬਾਤ ਦਾ ਸੰਦਰਭ ਕਈ ਕਦਮਾਂ ਵਿੱਚ ਇਕੱਤਰ ਹੁੰਦਾ ਹੈ ਜਦ ਤੱਕ ਟੋਕਨ ਸੀਮਾ ਪਹੁੰਚਦੀ ਹੈ* + +**ਕਦਮ-ਦਰ-ਕਦਮ ਤਰਕ** - ਉਹ ਸਮੱਸਿਆਵਾਂ ਜਿਨ੍ਹਾਂ ਲਈ ਤਰਕ ਰਾਹੀਂ ਵੇਖਣਾ ਚਾਹੀਦਾ ਹੈ। ਮਾਡਲ ਹਰ ਕਦਮ ਲਈ ਖੁਲ ਕੇ ਤਰਕ ਦਿਖਾਉਂਦਾ ਹੈ। ਗਣਿਤ ਸਮੱਸਿਆਵਾਂ, ਤਰਕ ਬੁਝਾਰੇ, ਜਾਂ ਜਦੋਂ ਤੁਸੀਂ ਸੋਚਣ ਦੇ ਤਰੀਕੇ ਨੂੰ ਸਮਝਣਾ ਚਾਹੁੰਦੇ ਹੋ ਵਰਤੋਂ ਕਰੋ। ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ਹੇਠਾਂ ਦਿੱਤੀ ਡਾਇਗਰਾਮ ਦਿਖਾਉਂਦੀ ਹੈ ਕਿ ਮਾਡਲ ਪ੍ਰਸ਼ਨਾਂ ਨੂੰ ਸਵਤੰਤਰ, ਗਿਣਤੀਵਾਰ ਤਰਕਸ਼ੀਲ ਕਦਮਾਂ ਵਿੱਚ ਕਿਵੇਂ ਵੰਡਦਾ ਹੈ। +ਹੇਠਾਂ ਦਿੱਤਾ ਚਿੱਤਰ ਇਹ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਮਾਡਲ ਸਮੱਸਿਆਵਾਂ ਨੂੰ ਖੁੱਲ੍ਹੇ, ਨੰਬਰਵਾਰ, ਲਾਜ਼ਮੀ ਕਦਮਾਂ ਵਿੱਚ ਕਿਵੇਂ ਵੰਡਦਾ ਹੈ। Step-by-Step Pattern +*ਮੁੱਦਿਆਂ ਨੂੰ ਸਪਸ਼ਟ ਤਰਕਸ਼ੀਲ ਕਦਮਾਂ ਵਿੱਚ ਵੰਡਣਾ* -*ਸਪਸ਼ਟ ਤਰਕਸ਼ੀਲ ਕਦਮਾਂ ਵਿੱਚ ਮੁੱਦਿਆਂ ਦਾ ਵਿਸਥਾਰ* - -**ਸੀਮਿਤ ਨਿਰਗਮ** - ਜਿਹੜੇ ਉੱਤਰਾਂ ਲਈ ਖਾਸ ਫਾਰਮੈਟ ਦੀਆਂ ਮਿਆਰਾਂ ਲੋੜੀਂਦੀਆਂ ਹਨ। ਮਾਡਲ ਪੂਰੀ ਤਰ੍ਹਾਂ ਫਾਰਮੈਟ ਅਤੇ ਲੰਬਾਈ ਦੇ ਨਿਯਮਾਂ ਦੀ ਪਾਲਣਾ ਕਰਦਾ ਹੈ। ਇਸਨੂੰ ਸਾਰਾਂਸ਼ਾਂ ਲਈ ਜਾਂ ਜਦੋਂ ਤੁਹਾਨੂੰ ਠੀਕ ਨਿਰਗਮ ਸੰਰਚਨਾ ਦੀ ਲੋੜ ਹੋਵੇ, ਤਾਂ ਵਰਤੋਂ ਕਰੋ। +**ਸੀਮਿਤ ਆਉਟਪੁੱਟ** - ਖਾਸ ਫਾਰਮੈਟ ਦੀਆਂ ਲੋੜਾਂ ਵਾਲੇ ਜਵਾਬਾਂ ਲਈ। ਮਾਡਲ ਸਖਤੀ ਨਾਲ ਫਾਰਮੈਟ ਅਤੇ ਲੰਬਾਈ ਦੇ ਕਾਇਦੇ ਮੰਨਦਾ ਹੈ। ਸਮਰੀਆਂ ਲਈ ਜਾਂ ਜਦੋਂ ਤੁਹਾਨੂੰ ਪੱਕੀ ਆਉਟਪੁੱਟ ਸੰਗਠਨਾ ਦੀ ਲੋੜ ਹੋਵੇ ਤਾਂ ਇਹ ਵਰਤੋਂ ਕਰੋ। ```java String prompt = """ @@ -420,189 +420,189 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ਹੇਠਾਂ ਦਿੱਤੀ ਡਾਇਗਰਾਮ ਦਿਖਾਉਂਦੀ ਹੈ ਕਿ ਸੀਮਾਵਾਂ ਮਾਡਲ ਨੂੰ ਤੁਹਾਡੇ ਫਾਰਮੈਟ ਅਤੇ ਲੰਬਾਈ ਦੀਆਂ ਮਿਆਰਾਂ ਦੀ ਕੜੀ ਪਾਲਣਾ ਕਰਵਾਉਂਦੀਆਂ ਹਨ। +ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਆਗ੍ਰਾਮ ਦਰਸਾਉਂਦਾ ਹੈ ਕਿ ਕਿਵੇਂ ਪਾਬੰਦੀਆਂ ਮਾਡਲ ਨੂੰ ਤੁਹਾਡੇ ਫਾਰਮੈਟ ਅਤੇ ਲੰਬਾਈ ਦੀਆਂ ਲੋੜਾਂ ਦਾ ਕੜਾਈ ਨਾਲ ਪਾਲਣ ਕਰਨ ਵਾਲੀ ਆਊਟਪੁੱਟ ਬਣਾਉਣ ਲਈ ਮਾਰੀਦਾਰ ਕਰਦੀਆਂ ਹਨ। -Constrained Output Pattern +ਸੀਮਿਤ ਆਉਟਪੁੱਟ ਪੈਟਰਨ -*ਖਾਸ ਫਾਰਮੈਟ, ਲੰਬਾਈ ਅਤੇ ਸੰਰਚਨਾ ਦੀਆਂ ਮੰਗਾਂ ਦੀ ਪਾਲਣਾ ਕਰਨਾ* +*ਖਾਸ ਫਾਰਮੈਟ, ਲੰਬਾਈ ਅਤੇ ਸੰਰਚਨਾ ਦੀਆਂ ਲੋੜਾਂ ਨੂੰ ਲਾਗੂ ਕਰਨਾ* ## ਐਪਲੀਕੇਸ਼ਨ ਚਲਾਓ -**ਡਿਪਲੋਇਮੈਂਟ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ:** +**ਡਿਪਲੋਯਮੈਂਟ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ:** -ਇਹ ਯਕੀਨੀ ਬਣਾਓ ਕਿ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ `.env` ਫਾਇਲ ਮੌਜੂਦ ਹੈ ਜਿਸ ਵਿੱਚ Azure ਕ੍ਰੈਡੈਂਸ਼ਲਜ਼ ਹਨ (Module 01 ਦੌਰਾਨ ਬਣਾਈ ਗਈ)। ਇਸਨੂੰ ਮਾਡਿਊਲ ਡਾਇਰੈਕਟਰੀ (`02-prompt-engineering/`) ਤੋਂ ਚਲਾਓ: +ਨਿਸ਼ਚਤ ਕਰੋ ਕਿ ਰੂਟ ਡਾਈਰੈਕਟਰੀ ਵਿੱਚ `.env` ਫਾਇਲ ਮੌਜੂਦ ਹੈ ਜਿਸ ਵਿੱਚ Azure ਦੇ ਪ੍ਰਮਾਣ ਪੱਤਰ ਹਨ (ਜੋ ਮੌਡੀਊਲ 01 ਦੌਰਾਨ ਬਣਾਈ ਗਈ ਸੀ)। ਇਸ ਨੂੰ ਮੌਡੀਊਲ ਡਾਈਰੈਕਟਰੀ (`02-prompt-engineering/`) ਤੋਂ ਚਲਾਓ: -**Bash:** +**ਬੈਸ਼:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ ``` -**PowerShell:** +**ਪਾਵਰਸ਼ੈੱਲ:** ```powershell Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ ``` **ਐਪਲੀਕੇਸ਼ਨ ਸ਼ੁਰੂ ਕਰੋ:** -> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਪਹਿਲਾਂ ही ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ `./start-all.sh` ਵਰਤ ਕੇ ਸਾਰੇ ਐਪਲੀਕੇਸ਼ਨ ਚਲਾਏ ਹੋ (ਜਿਵੇਂ Module 01 ਵਿੱਚ ਵਰਣਨ ਕੀਤਾ ਗਿਆ ਹੈ), ਤਾਂ ਇਹ ਮਾਡਿਊਲ ਪਹਿਲਾਂ ਹੀ ਪੋਰਟ 8083 'ਤੇ ਚੱਲ ਰਿਹਾ ਹੈ। ਤੁਸੀਂ ਹੇਠਾਂ ਦਿੱਤੇ ਸ਼ੁਰੂ ਕਰਨ ਦੇ ਹੁਕਮ ਛੱਡ ਕੇ ਸਿੱਧਾ http://localhost:8083 'ਤੇ ਜਾ ਸਕਦੇ ਹੋ। +> **ਟਿੱਪਣੀ:** ਜੇ ਤੁਸੀਂ ਪਹਿਲਾਂ ਹੀ ਸਾਰੇ ਐਪਲੀਕੇਸ਼ਨ `./start-all.sh` ਨਾਲ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ ਚਲਾ ਲਈ ਹੈ (ਜੋ ਮੌਡੀਊਲ 01 ਵਿੱਚ ਦਿੱਤਾ ਗਿਆ ਸੀ), ਤਾਂ ਇਹ ਮੌਡੀਊਲ ਪਹਿਲਾਂ ਹੀ ਪੋਰਟ 8083 ਤੇ ਚੱਲ ਰਿਹਾ ਹੈ। ਤੁਸੀਂ ਹੇਠਾਂ ਦਿੱਤੇ ਸ਼ੁਰੂ ਕਰਨ ਦੇ ਹੁਕਮ ਬਿਨਾਂ ਦੇਖੇ ਸਿੱਧਾ http://localhost:8083 'ਤੇ ਜਾ ਸਕਦੇ ਹੋ। -**ਵਿਕਲਪ 1: Spring Boot ਡੈਸ਼ਬੋਰਡ ਵਰਤਨਾ (VS Code ਵਰਤੋਂਕਾਰਾਂ ਲਈ ਸਿਫਾਰਸੀ)** +**ਵਿਕਲਪ 1: ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਦੀ ਵਰਤੋਂ (VS ਕੋਡ ਉਪਭੋਗਤਾਵਾਂ ਲਈ ਸਿਫਾਰਸ਼ੀ)** -ਡੈਵ ਕੰਟੇਨਰ ਵਿੱਚ Spring Boot ਡੈਸ਼ਬੋਰਡ ਐਕਸਟੈਂਸ਼ਨ ਸ਼ਾਮਿਲ ਹੈ, ਜੋ ਸਾਰੇ Spring Boot ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਸੰਭਾਲਣ ਲਈ ਦ੍ਰਿਸ਼ਟੀਗੋਚਰ ਇੰਟਰਫੇਸ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ। ਤੁਹਾਨੂੰ ਇਹ VS Code ਦੀ ਖੱਬੀ ਵੱਲ ਐਕਟਿਵਿਟੀ ਬਾਰ ਵਿੱਚ Spring Boot ਆਈਕਨ ਦੇ ਰੂਪ ਵਿੱਚ ਮਿਲੇਗਾ। +ਡੈਵ ਕੰਟੇਨਰ ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਐਕਸਟੈਂਸ਼ਨ ਸ਼ਾਮਲ ਹੈ, ਜੋ ਸਾਰੇ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਪ੍ਰਬੰਧਿਤ ਕਰਨ ਲਈ ਇੱਕ ਵਿਜ਼ੂਅਲ ਇੰਟਰਫੇਸ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ। ਇਸਨੂੰ VS ਕੋਡ ਦੇ ਖੱਬੇ ਪਾਸੇ ਮੌਜੂਦ ਐਕਟੀਵਿਟੀ ਬਾਰ ਵਿੱਚ ਲੱਭੋ (ਸਪ੍ਰਿੰਗ ਬੂਟ ਆਈਕਨ ਲਈ ਦੇਖੋ)। -Spring Boot ਡੈਸ਼ਬੋਰਡ ਤੋਂ ਤੁਸੀਂ: -- ਵਰਕਸਪੇਸ ਵਿੱਚ ਸਾਰੇ ਉਪਲਬਧ Spring Boot ਐਪਲੀਕੇਸ਼ਨ ਵੇਖ ਸਕਦੇ ਹੋ -- ਇੱਕ ਕਲਿੱਕ ਨਾਲ ਐਪਲੀਕੇਸ਼ਨ ਸ਼ੁਰੂ/ਰੋਕ ਸਕਦੇ ਹੋ -- ਲਾਈਵ ਭਾਸ਼ਾ ਵਿੱਚ ਐਪਲੀਕੇਸ਼ਨ ਲੌਗ ਦੇਖ ਸਕਦੇ ਹੋ -- ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਸਥਿਤੀ 'ਤੇ ਨਜ਼ਰ ਰੱਖ ਸਕਦੇ ਹੋ +ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਤੋਂ, ਤੁਸੀਂ: +- ਵਰਕਸਪੇਸ ਵਿੱਚ ਸਾਰੇ ਉਪਲਬਧ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨ ਵੇਖ ਸਕਦੇ ਹੋ +- ਸਿੰਗਲ ਕਲਿੱਕ ਨਾਲ ਐਪਲੀਕੇਸ਼ਨ ਸ਼ੁਰੂ/ਰੋਕ ਸਕਦੇ ਹੋ +- ਐਪਲੀਕੇਸ਼ਨ ਲੌਗ ਰੀਅਲ-ਟਾਈਮ ਵਿੱਚ ਦੇਖ ਸਕਦੇ ਹੋ +- ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਸਥਿਤੀ ਦੀ ਨਿਗਰਾਨੀ ਕਰ ਸਕਦੇ ਹੋ -ਸਿਰਫ "prompt-engineering" ਦੇ ਨਾਲ ਪਲੇ ਬਟਨ 'ਤੇ ਕਲਿੱਕ ਕਰੋ ਇਸ ਮਾਡਿਊਲ ਨੂੰ ਸ਼ੁਰੂ ਕਰਨ ਲਈ, ਜਾਂ ਇਕ ਵਾਰੀ ਵਿੱਚ ਸਾਰੇ ਮਾਡਿਊਲ ਚਾਲੂ ਕਰੋ। +ਸਿਰਫ "prompt-engineering" ਦੇ ਨਾਲ ਪਲੇ ਬਟਨ 'ਤੇ ਕਲਿੱਕ ਕਰੋ ਇਸ ਮੌਡੀਊਲ ਨੂੰ ਸ਼ੁਰੂ ਕਰਨ ਲਈ, ਜਾਂ ਸਾਰੇ ਮੌਡੀਊਲ ਇੱਕ ਨਾਲ ਸ਼ੁਰੂ ਕਰੋ। -Spring Boot Dashboard +ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ -*VS Code ਵਿੱਚ Spring Boot ਡੈਸ਼ਬੋਰਡ — ਇੱਕ ਥਾਂ ਤੋਂ ਸਾਰੇ ਮਾਡਿਊਲ ਚਾਲੂ ਕਰੋ, ਰੋਕੋ, ਅਤੇ ਮਾਨੀਟਰ ਕਰੋ* +*VS ਕੋਡ ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ — ਸਭ ਮੌਡੀਊਲ ਇਕੱਠੇ ਸ਼ੁਰੂ, ਰੋਕ ਅਤੇ ਨਿਗਰਾਨੀ ਕਰੋ* -**ਵਿਕਲਪ 2: ਸ਼ੈੱਲ ਸਕ੍ਰਿਪਟਾਂ ਦੀ ਵਰਤੋਂ** +**ਵਿਕਲਪ 2: ਸ਼ੈੱਲ ਸਕ੍ਰਿਪਟਸ ਦੀ ਵਰਤੋਂ** -ਸਾਰੇ ਵੈੱਬ ਐਪਲੀਕੇਸ਼ਨ (ਮਾਡਿਊਲ 01-04) ਸ਼ੁਰੂ ਕਰੋ: +ਸਾਰੇ ਵੈੱਬ ਐਪਲੀਕੇਸ਼ਨ (ਮੌਡੀਊਲ 01-04) ਸ਼ੁਰੂ ਕਰੋ: -**Bash:** +**ਬੈਸ਼:** ```bash -cd .. # ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ +cd .. # ਮੂਲ ਡਾਇਰੈਕਟਰੀ ਤੋਂ ./start-all.sh ``` -**PowerShell:** +**ਪਾਵਰਸ਼ੈੱਲ:** ```powershell -cd .. # ਮੂਲ ਡਾਇਰੈਕਟਰੀ ਤੋਂ +cd .. # ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ .\start-all.ps1 ``` -ਜਾਂ ਸਿਰਫ ਇਸ ਮਾਡਿਊਲ ਨੂੰ ਸ਼ੁਰੂ ਕਰੋ: +ਯਾ ਸਿਰਫ ਇਸ ਮੌਡੀਊਲ ਨੂੰ ਸ਼ੁਰੂ ਕਰੋ: -**Bash:** +**ਬੈਸ਼:** ```bash cd 02-prompt-engineering ./start.sh ``` -**PowerShell:** +**ਪਾਵਰਸ਼ੈੱਲ:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` -ਦੋਹਾਂ ਸਕ੍ਰਿਪਟ ਰੂਟ `.env` ਫਾਇਲ ਤੋਂ ਮਾਹੌਲ ਦੇ ਚਲਨਸ਼ੀਲ ਤੱਤਾਂ ਨੂੰ ਆਪਣੇ ਆਪ ਲੋਡ ਕਰ ਲੈਂਦੇ ਹਨ ਅਤੇ ਜੇ ਜਾਰ ਫਾਇਲਾਂ ਮੌਜੂਦ ਨਹੀਂ ਹਨ ਤਾਂ ਬਿਲਡ ਕਰਦੇ ਹਨ। +ਦੋਵੇਂ ਸਕ੍ਰਿਪਟ ਆਟੋਮੈਟਿਕਲੀ ਰੂਟ `.env` ਫਾਇਲ ਤੋਂ ਵਾਤਾਵਰਣੱਲੀਯਾਂ ਲੋਡ ਕਰਦੇ ਹਨ ਅਤੇ ਜੇ ਜਾਰ ਮੌਜੂਦ ਨਹੀਂ ਹਨ ਤਾਂ ਉਸਨੂੰ ਬਿਲਡ ਕਰਦੇ ਹਨ। -> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਚਾਹੁੰਦੇ ਹੋ ਕਿ ਸਾਰੇ ਮਾਡਿਊਲ ਮੈਨুਅਲੀ ਤੌਰ 'ਤੇ ਬਣਾਓ ਫਿਰ ਸ਼ੁਰੂ ਕਰੋ: +> **ਟਿੱਪਣੀ:** ਜੇ ਤੁਸੀਂ ਸਾਰੇ ਮੌਡੀਊਲ ਹੱਥੋਂ ਬਿਲਡ ਕਰਨਾ ਜ਼ਿਆਦਾ ਚਾਹੁੰਦੇ ਹੋ ਸ਼ੁਰੂ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ: > -> **Bash:** +> **ਬੈਸ਼:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell:** +> **ਪਾਵਰਸ਼ੈੱਲ:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -ਆਪਣਾ ਬ੍ਰਾਉਜ਼ਰ ਵਿੱਚ http://localhost:8083 ਖੋਲ੍ਹੋ। +ਆਪਣੇ ਬ੍ਰਾਊਜ਼ਰ ਵਿੱਚ http://localhost:8083 ਖੋਲ੍ਹੋ। **ਰੋਕਣ ਲਈ:** -**Bash:** +**ਬੈਸ਼:** ```bash -./stop.sh # ਇਹ ਸਿਰਫ ਮੋਡੀਊਲ +./stop.sh # ਸਿਰਫ ਇਹ ਮਾਡਿਊਲ # ਜਾਂ -cd .. && ./stop-all.sh # ਸਾਰੇ ਮੋਡੀਊਲ +cd .. && ./stop-all.sh # ਸਾਰੇ ਮਾਡਿਊਲ ``` -**PowerShell:** +**ਪਾਵਰਸ਼ੈੱਲ:** ```powershell -.\stop.ps1 # ਇਹ ਮੌਡਿਊਲ ਸਿਰਫ +.\stop.ps1 # ਇਹ ਮੌਡੀਊਲ ਸਿਰਫ # ਜਾਂ -cd ..; .\stop-all.ps1 # ਸਾਰੇ ਮੌਡਿਊਲ +cd ..; .\stop-all.ps1 # ਸਾਰੇ ਮੌਡੀਊਲ ``` -## ਐਪਲੀਕੇਸ਼ਨ ਸਕਰੀਨਸ਼ਾਟ +## ਐਪਲੀਕੇਸ਼ਨ ਸਕ੍ਰੀਨਸ਼ਾਟ -ਇੱਥੇ prompt engineering ਮਾਡਿਊਲ ਦਾ ਮੁੱਖ ਇੰਟਰਫੇਸ ਹੈ, ਜਿੱਥੇ ਤੁਸੀਂ ਸਾਰੇ 8 ਪੈਟਰਨ ਇਕੱਠੇ ਅਜ਼ਮਾ ਸਕਦੇ ਹੋ। +ਇਹਪ੍ਰੰਪਟ ਇੰਜੀਨੀਅਰੀ ਮੌਡੀਊਲ ਦੀ ਮੁੱਖ ਇੰਟਰਫੇਸ ਹੈ, ਜਿੱਥੇ ਤੁਸੀਂ ਸਾਰੇ 8 ਪੈਟਰਨ ਸਾਥ-ਸਾਥ ਪਰਖ ਸਕਦੇ ਹੋ। -Dashboard Home +ਡੈਸ਼ਬੋਰਡ ਹੋਮ -*ਮੁੱਖ ਡੈਸ਼ਬੋਰਡ ਜੋ ਸਾਰੇ 8 prompt engineering ਪੈਟਰਨ ਦੇ ਵਿਸ਼ੇਸ਼ਤਾ ਅਤੇ ਵਰਤੋਂ ਮਾਮਲੇ ਦਿਖਾਉਂਦਾ ਹੈ* +*ਮੁੱਖ ਡੈਸ਼ਬੋਰਡ ਜੋ ਸਾਰੇ 8 ਪ੍ਰੰਪਟ ਇੰਜੀਨੀਅਰਿੰਗ ਪੈਟਰਨਾਂ ਨੂੰ ਉਹਨਾਂ ਦੀਆਂ ਖੂਬੀਆਂ ਅਤੇ ਵਰਤੋਂ ਕੇਸਾਂ ਨਾਲ ਦਿਖਾਉਂਦਾ ਹੈ* ## ਪੈਟਰਨਾਂ ਦੀ ਖੋਜ -ਵੈੱਬ ਇੰਟਰਫੇਸ ਤੁਹਾਨੂੰ ਵੱਖ-ਵੱਖ ਪ੍ਰੋਮਪਟਿੰਗ ਰਣਨੀਤੀਆਂ ਨਾਲ ਅਜ਼ਮਾਇਸ਼ ਕਰਨ ਦੇ ਯੋਗ ਬਣਾਉਂਦਾ ਹੈ। ਹਰ ਪੈਟਰਨ ਵੱਖ-ਵੱਖ ਮੁੱਦਿਆਂ ਦਾ ਹੱਲ ਕਰਦਾ ਹੈ - ਜਦੋਂ ਹਰ ਪ੍ਰਵਾਨਗੀ ਚਮਕਦੀ ਹੈ, ਦੇਖਣ ਲਈ ਉਨ੍ਹਾਂ ਨੂੰ ਪਰਖੋ। +ਵੈੱਬ ਇੰਟਰਫੇਸ ਤੁਹਾਨੂੰ ਵੱਖ-ਵੱਖ ਪ੍ਰੰਪਟਿੰਗ ਰਣਨੀਤੀਆਂ ਨਾਲ ਪ੍ਰਯੋਗ ਕਰਨ ਦਿੰਦਾ ਹੈ। ਹਰ ਇੱਕ ਪੈਟਰਨ ਵੱਖਰੇ ਮੁੱਦੇ ਹੱਲ ਕਰਦਾ ਹੈ - ਇਹਨਾਂ ਨੂੰ ਕੋਸ਼ਿਸ਼ ਕਰੋ ਤਾਂ ਜੋ ਤੁਹਾਨੂੰ ਪਤਾ ਲੱਗੇ ਕਿ ਕਿਹੜੀ ਪন্থ ਕਦੋਂ ਚਮਕਦੀ ਹੈ। -> **ਨੋਟ: ਸਟ੍ਰੀਮਿੰਗ ਵਿਰੁੱਧ ਨਾਨ-ਸਟ੍ਰੀਮਿੰਗ** — ਹਰ ਪੈਟਰਨ ਪੇਜ 'ਤੇ ਦੋ ਬਟਨ ਹਨ: **🔴 Stream Response (Live)** ਅਤੇ ਇੱਕ **Non-streaming** ਵਿਕਲਪ। ਸਟ੍ਰੀਮਿੰਗ Server-Sent Events (SSE) ਦੀ ਵਰਤੋਂ ਕਰਦੀ ਹੈ ਤਾਂ ਜੋ ਮਾਡਲ ਜਿਵੇਂ ਹੀ ਟੋਕਨ ਬਣਾਉਂਦਾ ਹੈ ਤੁਸੀਂ ਤੁਰੰਤ ਪ੍ਰਗਟੀ ਦੇਖ ਸਕੋ। ਨਾਨ-ਸਟ੍ਰੀਮਿੰਗ ਪੂਰਾ ਜਵਾਬ ਆਉਣ ਤੱਕ ਇੰਤਜ਼ਾਰ ਕਰਦੀ ਹੈ। ਓਹਨਾਂ ਪ੍ਰੋਮਪਟਾਂ ਲਈ ਜੋ ਗਹਿਰੀ ਤਰਕਸ਼ੀਲਤਾ ਨੂੰ ਪ੍ਰੇਰਤ ਕਰਦੇ ਹਨ (ਜਿਵੇਂ High Eagerness, Self-Reflecting Code), ਨਾਨ-ਸਟ੍ਰੀਮਿੰਗ ਕਾਲ ਬੜੀ ਲੰਮੀ ਹੋ ਸਕਦੀ ਹੈ – ਕਈ ਵਾਰੀ ਮਿੰਟਾਂ – ਬਿਨਾਂ ਕੋਈ ਲਾਈਵ ਪ੍ਰਤੀਕਿਰਿਆ ਦੇ। **ਝੰਝਟਦਾਰ ਪ੍ਰੋਮਪਟਾਂ 'ਤੇ ਅਜ਼ਮਾਉਣ ਲਈ ਸਟ੍ਰੀਮਿੰਗ ਵਰਤੋਂ ਤਾਂ ਜੋ ਤੁਰੰਤ ਮਾਡਲ ਕੰਮ ਕਰਦੇ ਵੇਖ ਸਕੋ ਅਤੇ ਲੱਗੇ ਨਾ ਕਿ ਬੇਨਤੀ ਟਾਈਮ ਆਉਟ ਹੋ ਗਈ ਹੈ।** +> **ਟਿੱਪਣੀ: ਸਟ੍ਰੀਮਿੰਗ ਅਤੇ ਨਾਨ-ਸਟ੍ਰੀਮਿੰਗ** — ਹਰ ਪੈਟਰਨ ਪੇਜ ਤੇ ਦੋ ਬਟਨ ਹੁੰਦੇ ਹਨ: **🔴 ਸਟ੍ਰੀਮ ਰਿਸਪਾਂਸ (লাইਵ)** ਅਤੇ **ਨਾਨ-ਸਟ੍ਰੀਮਿੰਗ** ਵਿਕਲਪ। ਸਟ੍ਰੀਮਿੰਗ ਸਰਵਰ-ਸੈਂਟ ਇਵੈਂਟਸ (SSE) ਵਰਤਦਾ ਹੈ, ਜੋ ਮਾਡਲ ਲਈ ਟੋਕਨ ਜਿੰਨ੍ਹਾਂ ਨੂੰ ਉਹ ਬਣਾਉਂਦਾ ਹੈ ਤੁਰੰਤ ਦਰਸਾਉਂਦਾ ਹੈ, ਇਸ ਲਈ ਤੁਸੀਂ ਤੁਰੰਤ ਪ੍ਰਗਟ ਦੀ ਵੇਖ ਸਕਦੇ ਹੋ। ਨਾਨ-ਸਟ੍ਰੀਮਿੰਗ ਸਾਰੇ ਜਵਾਬ ਦਾ ਇੰਤਜ਼ਾਰ ਕਰਦਾ ਹੈ ਫਿਰ ਦਿਖਾਉਂਦਾ ਹੈ। ਜਿਹੜੇ ਪ੍ਰੰਪਟ ਡੂੰਘੀ ਵਿਚਾਰ ਧਾਰਾ ਚਲਾਉਂਦੇ ਹਨ (ਜਿਵੇਂ ਕਿ ਹਾਈ ਇਗਰਨੈਸ, ਸੈਲਫ-ਰਿਫਲੈਕਟਿੰਗ ਕੋਡ) ਲਈ ਨਾਨ-ਸਟ੍ਰੀਮਿੰਗ ਕਾਲ ਬਹੁਤ ਲੰਮੀ ਸਮੇਂ ਲਈ ਹੋ ਸਕਦੀ ਹੈ — ਕਈ ਵਾਰੀ ਮਿੰਟਾਂ ਤੱਕ — ਬਿਨਾਂ ਕੋਈ ਵਿਜ਼ੂਅਲ ਫੀਡਬੈੱਕ। **褓ਹੜੀ ਜਾਂਦੀ ਹੈ ਕਿ ਤੁਸੀਂ ਜਟਿਲ ਪ੍ਰੰਪਟਾਂ ਵਾਲੇ ਪ੍ਰਯੋਗਾਂ ਲਈ ਸਟ੍ਰੀਮਿੰਗ ਵਰਤੋਂ ਤਾਂ ਜੋ ਤੁਹਾਡੇ ਕੋਲ ਮਾਡਲ ਕੰਮ ਕਰਦਾ ਹੋਇਆ ਵੇਖਣ ਦਾ ਮੌਕਾ ਹੋਵੇ ਅਤੇ ਲੱਗਣ ਨਾ ਦੇਵੇ ਕਿ ਬੇਨਤੀ ਟਾਈਮਆਉਟ ਹੋ ਗਈ ਹੈ।** > -> **ਨੋਟ: ਬ੍ਰਾਊਜ਼ਰ ਦੀ ਲੋੜ** — ਸਟ੍ਰੀਮਿੰਗ ਫੀਚਰ Fetch Streams API (`response.body.getReader()`) ਦੀ ਵਰਤੋਂ ਕਰਦਾ ਹੈ ਜੋ ਪੂਰੇ ਬ੍ਰਾਊਜ਼ਰ (Chrome, Edge, Firefox, Safari) 'ਚ ਹੀ ਚੱਲਦਾ ਹੈ। ਇਹ VS Code ਦੇ ਬਿਲਟ-ਇਨ Simple Browser ਵਿੱਚ ਨਹੀਂ ਚੱਲਦਾ, ਕਿਉਂਕਿ ਇਸ ਦਾ webview ReadableStream API ਨੂੰ ਸਪੋਰਟ ਨਹੀਂ ਕਰਦਾ। ਜੇ ਤੁਸੀਂ Simple Browser ਵਰਤਦੇ ਹੋ ਤਾਂ ਨਾਨ-ਸਟ੍ਰੀਮਿੰਗ ਬਟਨ ਆਮ ਤੌਰ 'ਤੇ ਕੰਮ ਕਰਨਗੇ – ਸਿਰਫ ਸਟ੍ਰੀਮਿੰਗ ਬਟਨ ਪ੍ਰਭਾਵਿਤ ਹਨ। ਸਮੱਗਰੀ ਦਿੱਤਾ ਗਿਆ http://localhost:8083 ਕਿਸੇ ਬਾਹਰੀ ਬ੍ਰਾਊਜ਼ਰ ਵਿੱਚ ਖੋਲ੍ਹੋ ਪੂਰੇ ਅਨੁਭਵ ਲਈ। +> **ਟਿੱਪਣੀ: ਬ੍ਰਾਊਜ਼ਰ ਦੀ ਲੋੜ** — ਸਟ੍ਰੀਮਿੰਗ ਫੀਚਰ Fetch Streams API (`response.body.getReader()`) ਵਰਤਦਾ ਹੈ ਜੋ ਪੂਰੇ ਬ੍ਰਾਊਜ਼ਰਾਂ (Chrome, Edge, Firefox, Safari) ਵਿੱਚ ਚੱਲਦਾ ਹੈ। ਇਹ VS ਕੋਡ ਦੇ ਬਿਲਟ-ਇਨ Simple Browser ਵਿੱਚ ਕੰਮ ਨਹੀਂ ਕਰਦਾ, ਕਿਉਂਕਿ ਇਸਦੀ ਵੈੱਬਵਿਊ ReadableStream API ਦਾ ਸਮਰਥਨ ਨਹੀਂ ਕਰਦੀ। ਜੇ ਤੁਸੀਂ Simple Browser ਵਰਤੋਂਗੇ ਤਾਂ ਨਾਨ-ਸਟ੍ਰੀਮਿੰਗ ਬਟਨ ਅਜੇ ਵੀ ਆਮ ਤਰ੍ਹਾਂ ਕੰਮ ਕਰਨਗੇ — ਕੇਵਲ ਸਟ੍ਰੀਮਿੰਗ ਬਟਨ ਪ੍ਰਭਾਵਿਤ ਹੋਣਗੇ। ਪੂਰੇ ਤਜਰਬੇ ਲਈ http://localhost:8083 ਨੂੰ ਕਿਸੇ ਬਾਹਰੀ ਬ੍ਰਾਊਜ਼ਰ ਵਿੱਚ ਖੋਲ੍ਹੋ। -### Low ਅਤੇ High Eagerness +### ਘੱਟ ਅਤੇ ਜ਼ਿਆਦਾ ਉਤਸ਼ਾਹ -ਕਿਸੇ ਸਧਾਰਣ ਪ੍ਰਸ਼ਨ ਜਿਵੇਂ "200 ਦਾ 15% ਕੀ ਹੈ?" ਨੂੰ Low Eagerness ਨਾਲ ਪੁੱਛੋ। ਤੁਹਾਨੂੰ ਫੌਰਤ, ਸਿੱਧਾ ਜਵਾਬ ਮਿਲੇਗਾ। ਹੁਣ ਕਦੇ "ਉੱਚ-ਟਰੈਫਿਕ API ਲਈ ਕੈਸ਼ੀੰਗ ਰਣਨੀਤੀ ਡਿਜ਼ਾਇਨ ਕਰੋ" ਨੂੰ High Eagerness ਨਾਲ ਪੁੱਛੋ। **🔴 Stream Response (Live)** 'ਤੇ ਕਲਿੱਕ ਕਰੋ ਅਤੇ ਮਾਡਲ ਦੀ ਵਿਸਥਾਰਪੂਰਕ ਤਰਕਸ਼ੀਲਤਾ ਟੋਕਨ-ਦਰ-ਟੋਕਨ ਵੇਖੋ। ਇੱਕੋ ਮਾਡਲ, ਇੱਕੋ ਪ੍ਰਸ਼ਨ ਪਰੰਪਰਾ - ਪਰ ਪ੍ਰੋਮਪਟ ਦੱਸਦਾ ਹੈ ਕਿੰਨੀ ਸੋਚ ਜਰੂਰੀ ਹੈ। +ਇਕ ਸਧਾਰਣ ਸਵਾਲ ਪੁੱਛੋ ਜਿਵੇਂ "200 ਦਾ 15% ਕੀ ਹੈ?" ਘੱਟ ਉਤਸ਼ਾਹ ਨਾਲ। ਤੁਹਾਨੂੰ ਤੁਰੰਤ ਅਤੇ ਸਿੱਧਾ ਜਵਾਬ ਮਿਲੇਗਾ। ਹੁਣ ਕੁਝ ਜਟਿਲ ਪੁੱਛੋ ਜਿਵੇਂ "ਉੱਚ-ਟ੍ਰੈਫਿਕ API ਲਈ ਕੈਸ਼ਿੰਗ ਰਣਨੀਤੀ ਡਿਜ਼ਾਇਨ ਕਰੋ" ਜ਼ਿਆਦਾ ਉਤਸ਼ਾਹ ਨਾਲ। **🔴 ਸਟ੍ਰੀਮ ਰਿਸਪਾਂਸ (লাইਵ)** ਤੇ ਕਲਿੱਕ ਕਰੋ ਅਤੇ ਮਾਡਲ ਦੀ ਵਿਸਥਾਰਵਾਦੀ ਵਿਚਾਰ-ਧਾਰਾ ਟੋਕਨ ਬਾਈ ਟੋਕਨ ਵੱਖਰੇ-ਵੱਖਰੇ ਆਉਂਦੀ ਦੇਖੋ। ਇਕੋ ਮਾਡਲ, ਇਕੋ ਸਵਾਲ ਦੀ ਬਣਤਰ — ਪਰ ਪ੍ਰੰਪਟ ਦੱਸਦਾ ਹੈ ਕਿ ਇਹਨੂੰ ਕਿੰਨਾ ਸੋਚਣਾ ਹੈ। -### Task Execution (ਟੂਲ ਪ੍ਰੀਐਮਬਲ) +### ਟਾਸਕ ਐਗਜ਼ਿਕਿਊਸ਼ਨ (ਟੂਲ ਪ੍ਰੀਐਮਬਲ) -ਮਲਟੀ-ਸਟੈਪ ਵਰਕਫਲੋਅਜ਼ ਸ਼ੁਰੂਆਤੀ ਯੋਜਨਾ ਅਤੇ ਤਰੱਕੀ ਬਿਆਨਕਰਨ ਨਾਲ ਲਾਭਕਾਰੀ ਹੁੰਦੇ ਹਨ। ਮਾਡਲ ਵਿਆਖਿਆ ਕਰਦਾ ਹੈ ਕਿ ਉਹ ਕੀ ਕਰੇਗਾ, ਹਰ ਕਦਮ ਦਾ ਵਰਣਨ ਕਰਦਾ ਹੈ, ਫਿਰ ਨਤੀਜੇ ਸਾਰਾਂਸ਼ਿਤ ਕਰਦਾ ਹੈ। +ਮਲਟੀ-ਸਟੈਪ ਵਰਕਫਲੋਅ ਸੰਰਚਿਤ ਯੋਜਨਾ ਅਤੇ ਪ੍ਰਗਟਿ ਵਰਨਣ ਤੋਂ ਲਾਭਾਨਵਿਤ ਹੁੰਦੇ ਹਨ। ਮਾਡਲ ਦੱਸਦਾ ਹੈ ਕਿ ਇਹ ਕੀ ਕਰਨ ਜਾ ਰਿਹਾ ਹੈ, ਹਰ ਕਦਮ ਨੂੰ ਵਰਨਨ ਕਰਦਾ ਹੈ, ਫਿਰ ਨਤੀਜਿਆਂ ਦਾ ਸਾਰ ਸਾਂਝਾ ਕਰਦਾ ਹੈ। -### Self-Reflecting Code +### ਸੈਲਫ-ਰਿਫਲੈਕਟਿੰਗ ਕੋਡ -“ਇਮੇਲ ਵੈਲਿਡੇਸ਼ਨ ਸਰਵਿਸ ਬਣਾਓ” ਕੋਸ਼ਿਸ਼ ਕਰੋ। ਸਿਰਫ ਕੋਡ ਬਣਾਉਣ ਅਤੇ ਰੁਕਣ ਦੀ ਬਜਾਏ, ਮਾਡਲ ਬਣਾਉਂਦਾ ਹੈ, ਗੁਣਵੱਤਾ ਮਾਪਦੰਡਾਂ ਵਿਰੁੱਧ ਜਾਚ ਕਰਦਾ ਹੈ, ਕਮਜ਼ੋਰੀਆਂ ਪਛਾਣਦਾ ਹੈ, ਅਤੇ ਸੁਧਾਰ ਕਰਦਾ ਹੈ। ਤੁਸੀਂ ਦੇਖੋਗੇ ਕਿ ਇਹ ਕਿਵੇਂ ਦੁਹਰਾਅ ਕਰਦਾ ਹੈ ਜਦ ਤੱਕ ਕੋਡ ਉਤਪਾਦਨ ਮਾਪਦੰਡਾਂ 'ਤੇ ਖਰਾ ਨਹੀਂ ਉਤਰਦਾ। +"ਇੱਕ ਈਮੇਲ ਪਰਖ ਸੇਵਾ ਬਣਾਓ" ਕੋਸ਼ਿਸ਼ ਕਰੋ। ਸਿਰਫ ਕੋਡ ਬਣਾਉਣ ਅਤੇ ਰੁਕਣ ਦੀ ਥਾਂ, ਮਾਡਲ ਬਣਾਉਂਦਾ ਹੈ, ਗੁਣਵੱਤਾ ਮਾਪਦੰਡਾਂ ਮੁਤਾਬਕ ਇਸਦੇ ਖਿਲਾਫ ਮੂਲਾਂਕਣ ਕਰਦਾ ਹੈ, ਕਮਜ਼ੋਰੀਆਂ ਲੱਭਦਾ ਹੈ ਅਤੇ ਸੁਧਾਰ ਕਰਦਾ ਹੈ। ਤੁਸੀਂ ਵੇਖੋਗੇ ਕਿ ਇਹ ਜਦ ਤੱਕ ਕੋਡ ਉਤਪਾਦਨ ਮਿਆਰਾਂ ਨਾਲ ਨਾ ਮਿਲੇ ਤਦ ਤੱਕ ਕਈ ਵਾਰ ਦੁਹਰਾਉਂਦਾ ਹੈ। -### Structured Analysis +### ਸੰਰਚਿਤ ਵਿਸ਼ਲੇਸ਼ਣ -ਕੋਡ ਸਮੀਖਿਆ ਲਈ ਸਥਿਰ ਮੁਲਾਂਕਣ ਫਰੇਮਵਰਕ ਲਾਜ਼ਮੀ ਹੈ। ਮਾਡਲ ਕੋਡ ਦਾ ਵਿਸ਼ਲੇਸ਼ਣ ਸਥਾਈ ਸ਼੍ਰੇਣੀਆਂ (ਸਹੀਪਣ, ਅਮਲ, ਕਾਰਗੁਜ਼ਾਰੀ, ਸੁਰੱਖਿਆ) ਦੇ ਅਧਾਰ 'ਤੇ ਕਰਦਾ ਹੈ ਜਿਨ੍ਹਾਂ ਦੀ ਸੰਭਾਲ ਸਖਤਤਾ ਦੀ ਪੱਧਰ ਨਾਲ ਹੁੰਦੀ ਹੈ। +ਕੋਡ ਸਮੀਖਿਆਆਂ ਲਈ ਸਥਿਰ ਮੂਲਾਂਕਣ ਢਾਂਚੇ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ। ਮਾਡਲ ਕੋਡ ਨੂੰ ਨਿਰਧਾਰਿਤ ਸ਼੍ਰੇਣੀਆਂ (ਸਹੀਤਾ, ਅਭਿਆਸ, ਕਾਰਕਗੁਜ਼ਾਰੀ, ਸੁਰੱਖਿਆ) ਦੇ ਨਾਲ ਤੇਜੀ ਦਰਜਿਆਂ ਨਾਲ ਵਿਸ਼ਲੇਸ਼ਣ ਕਰਦਾ ਹੈ। -### Multi-Turn Chat +### ਮਲਟੀ-ਟਰਨ ਚੈਟ -“Spring Boot ਕੀ ਹੈ?” ਪੁੱਛੋ ਫਿਰ ਤੁਰੰਤ “ਮੈਨੂੰ ਉਦਾਹਰਣ ਦਿਖਾਓ” ਕਰਕੇ ਫਾਲੋਅਪ ਕਰੋ। ਮਾਡਲ ਤੁਹਾਡੇ ਪਹਿਲੇ ਸਵਾਲ ਨੂੰ ਯਾਦ ਰੱਖਦਾ ਹੈ ਅਤੇ ਵਿਸ਼ੇਸ਼ ਤੌਰ ‘ਤੇ Spring Boot ਦੀ ਉਦਾਹਰਣ ਦਿੰਦਾ ਹੈ। ਬਿਨਾਂ ਯਾਦਦਾਸ਼ਤ ਦੇ ਦੂਜਾ ਸਵਾਲ ਬਹੁਤ ਅਸਪਸ਼ਟ ਹੁੰਦਾ। +"Spring Boot ਕੀ ਹੈ?" ਪੁੱਛੋ ਫਿਰ ਤੁਰੰਤ "ਮੈਨੂੰ ਇੱਕ ਉਦਾਹਰਨ ਦਿਖਾਓ" ਪੁੱਛੋ। ਮਾਡਲ ਤੁਹਾਡੇ ਪਹਿਲੇ ਸਵਾਲ ਨੂੰ ਯਾਦ ਰੱਖਦਾ ਹੈ ਅਤੇ ਖਾਸ ਤੌਰ 'ਤੇ ਤੁਹਾਨੂੰ Spring Boot ਦੀ ਉਦਾਹਰਨ ਦਿੰਦਾ ਹੈ। ਬਿਨਾਂ ਮੈਮੋਰੀ, ਦੂਜਾ ਸਵਾਲ ਬਹੁਤ ਜ਼ਿਆਦਾ ਅਸਪਸ਼ਟ ਹੁੰਦਾ। -### Step-by-Step Reasoning +### ਕਦਮ-ਦਰ-কਦਮ ਤਰਕਸ਼ੀਲਤਾ -ਕਿਸੇ ਗਣਿਤ ਦੇ ਮੁੱਦੇ ਨੂੰ ਚੁਣੋ ਅਤੇ ਇਸਨੂੰ Step-by-Step Reasoning ਅਤੇ Low Eagerness ਦੋਹਾਂ ਨਾਲ ਅਜ਼ਮਾਓ। Low eagerness ਸਿਰਫ ਜਵਾਬ ਦਿੰਦਾ ਹੈ - ਤੇਜ਼ ਪਰ ਅਸਪਸ਼ਟ। Step-by-step ਤੁਹਾਨੂੰ ਹਰੇਕ ਗਣਨਾ ਅਤੇ ਫੈਸਲਾ ਦਿਖਾਉਂਦਾ ਹੈ। +ਕੋਈ ਗਣਿਤ ਦਾ ਮੁੱਦਾ ਚੁਣੋ ਅਤੇ ਦੋਹਰਾਈ ਨਾਲ ਦਰਜੇ-ਦਰ-ਦਰ ਕਦਮ ਅਤੇ ਘੱਟ ਉਤਸ਼ਾਹ ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ। ਘੱਟ ਉਤਸ਼ਾਹ ਤੁਹਾਨੂੰ ਸਿਰਫ ਜਵਾਬ ਦੇਂਦਾ ਹੈ - ਤੇਜ਼ ਪਰ ਅਸਪਸ਼ਟ। ਕਦਮ-ਦਰ-ਕਦਮ ਹਰ ਗਣਨਾ ਅਤੇ ਫੈਸਲੇ ਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ। -### Constrained Output +### ਸੀਮਿਤ ਆਉਟਪੁੱਟ -ਜਦੋਂ ਤੁਹਾਨੂੰ ਖਾਸ ਫਾਰਮੈਟ ਜਾਂ ਸ਼ਬਦ ਗਿਣਤੀ ਦੀ ਲੋੜ ਹੋਵੇ, ਇਹ ਪੈਟਰਨ ਕਠੋਰ ਪਾਲਣਾ ਕਰਵਾਉਂਦਾ ਹੈ। 100 ਸ਼ਬਦਾਂ ਦੇ ਬੁਲਿਟ ਪੁਆਇੰਟ ਫਾਰਮੈਟ ਵਿੱਚ ਇਕ ਸਾਰ ਬਣਾਉਣ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰੋ। +ਜਦੋਂ ਤੁਸੀਂ ਖਾਸ ਫਾਰਮੈਟ ਜਾਂ ਸ਼ਬਦ ਗਿਣਤੀ ਦੀ ਲੋੜ ਰੱਖਦੇ ਹੋ, ਇਹ ਪੈਟਰਨ ਕੜਾਈ ਨਾਲ ਪਾਲਣਾ ਕਰਵਾਉਂਦਾ ਹੈ। ਬਿਲਕੁਲ 100 ਸ਼ਬਦਾਂ ਵਿੱਚ ਗੋਲੀਆਂ ਵਾਲਾ ਸਾਰ ਬਣਾ ਕੇ ਦੇਖੋ। ## ਤੁਸੀਂ ਅਸਲ ਵਿੱਚ ਕੀ ਸਿੱਖ ਰਹੇ ਹੋ -**ਤਰਕਸ਼ੀਲ ਪ੍ਰਯਾਸ ਹਰ ਚੀਜ਼ ਬਦਲਦਾ ਹੈ** +**ਤਰਕਸ਼ੀਲ ਕੋਸ਼ਿਸ਼ ਸਭ ਕੁਝ ਬਦਲ ਦਿੰਦੀ ਹੈ** -GPT-5.2 ਤੁਹਾਨੂੰ ਆਪਣੇ ਪ੍ਰੋਮਪਟਾਂ ਰਾਹੀਂ ਗਣਨਾਤਮਿਕ ਪ੍ਰਯਾਸ ਕੰਟਰੋਲ ਕਰਨ ਦੀ ਆਗਿਆ ਦਿੰਦਾ ਹੈ। ਘੱਟ ਪ੍ਰਯਾਸ ਦਾ ਅਰਥ ਫਟਾਫਟ ਜਵਾਬ ਬਿਨਾਂ ਬਹੁਤ ਖੋਜ ਦੇ ਹੁੰਦਾ ਹੈ। ਉੱਚ ਪ੍ਰਯਾਸ ਮਾਡਲ ਨੂੰ ਗਹਿਰਾਈ ਨਾਲ ਸੋਚਣ ਲਈ ਸਮਾਂ ਲੈਂਦਾ ਹੈ। ਤੁਸੀਂ ਪ੍ਰਯਾਸ ਨੂੰ ਕੰਮ ਦੀ ਜਟਿਲਤਾ ਨਾਲ ਮੇਲ ਖਾਣਾ ਸਿੱਖ ਰਹੇ ਹੋ - ਸਧਾਰਣ ਪ੍ਰਸ਼ਨਾਂ 'ਤੇ ਸਮਾਂ ਬਰਬਾਦ ਨਾ ਕਰੋ, ਪਰ ਜਟਿਲ ਫੈਸਲਿਆਂ ਨੂੰ ਵੀ ਜਲਦੀ ਨਾ ਲਵੋ। +GPT-5.2 ਤੁਹਾਨੂੰ ਆਪਣੇ ਪ੍ਰੰਪਟਾਂ ਰਾਹੀਂ ਗਣਨਾਤਮਕ ਕੋਸ਼ਿਸ਼ ਨੂੰ ਨਿਯੰਤਰਿਤ ਕਰਨ ਦਿੰਦਾ ਹੈ। ਘੱਟ ਕੋਸ਼ਿਸ਼ ਦਾ ਮਤਲਬ ਹੈ ਤੇਜ਼ ਜਵਾਬਾਂ ਅਤੇ ਘੱਟ ਜਾਂਚ। ਜ਼ਿਆਦਾ ਕੋਸ਼ਿਸ਼ ਦਾ ਮਤਲਬ ਹੈ ਕਿ ਮਾਡਲ ਡੂੰਘਾਈ ਨਾਲ ਸੋਚਦਾ ਹੈ। ਤੁਸੀਂ ਸਿੱਖ ਰਹੇ ਹੋ ਕਿ ਕੋਸ਼ਿਸ਼ ਨੂੰ ਟਾਸਕ ਦੀ ਜਟਿਲਤਾ ਨਾਲ ਮਿਲਾਇਆ ਜਾਵੇ - ਸਧਾਰਨ ਸਵਾਲਾ 'ਤੇ ਸਮਾਂ ਬਰਬਾਦ ਨਾ ਕਰੋ, ਪਰ ਜਟਿਲ ਫੈਸਲਿਆਂ ਨੂੰ ਵੀ ਜਲਦੀ ਵਿੱਚ ਨਾ ਬਣਾਓ। -**ਸੰਰਚਨਾ ਰਵੱਈਏ ਨੂੰ ਗਾਈਡ ਕਰਦੀ ਹੈ** +**ਸੰਰਚਨਾ ਵਰਤਾਰ ਨੂੰ ਸਹੀ ਢੰਗ ਨਾਲ ਦਿਸ਼ਾ ਦਿੰਦੀ ਹੈ** -ਪ੍ਰੋਮਪਟਾਂ ਵਿੱਚ XML ਟੈਗਾਂ ਨੂੰ ਧਿਆਨ ਨਾਲ ਦੇਖੋ? ਉਹ ਸਿਰਫ ਸਜਾਵਟੀ ਨਹੀਂ ਹਨ। ਮਾਡਲ ਆਰਡਰਵਾਰ ਹੁਕਮਾਂ ਦੀ ਅੱਛੀ ਤਰ੍ਹਾਂ ਪਾਲਣਾ ਕਰਦੇ ਹਨ। ਜਦੋਂ ਤੁਹਾਨੂੰ ਬਹੁ-ਕਦਮੀ ਪ੍ਰਕਿਰਿਆ ਜਾਂ ਜਟਿਲ ਤਰਕ ਦੀ ਲੋੜ ਹੋਵੇ, ਤਬ ਸੰਰਚਨਾ ਮਾਡਲ ਨੂੰ ਟ੍ਰੈਕ ਕਰਨ ਵਿੱਚ ਮਦਦ ਕਰਦੀ ਹੈ ਕਿ ਉਹ ਕਿੱਥੇ ਹੈ ਅਤੇ ਅਗਲਾ ਕਦਮ ਕੀ ਹੈ। ਹੇਠਾਂ ਦਿੱਤੀ ਡਾਇਗਰਾਮ ਇੱਕ ਵਧੀਆ ਸੰਰਚਿਤ ਪ੍ਰੋਮਪਟ ਨੂੰ ਦਰਸਾਉਂਦੀ ਹੈ ਜਿਸ ਵਿੱਚ ``, ``, ``, ``, ਅਤੇ `` ਵਰਗੇ ਟੈਗ ਸਪਸ਼ਟ ਹਿੱਸਿਆਂ ਵਿੱਚ ਤੁਹਾਡੇ ਹੁਕਮਾਂ ਨੂੰ ਵਿਭਾਜਿਤ ਕਰਦੇ ਹਨ। +ਕੀ ਤੁਸੀਂ ਪ੍ਰੰਪਟਾਂ ਵਿੱਚ XML ਟੈਗਾਂ ਨੂੰ ਨੋਟ ਕਰਦੇ ਹੋ? ਇਹ ਸਿਰਫ ਸ਼ਿੰਗਾਰ ਨਹੀਂ ਹਨ। ਮਾਡਲ ਸੰਰਚਿਤ ਹੁਕਮਾਂ ਨੂੰ ਮੁਕਤ ਪਾਠ ਨਾਲੋਂ ਜ਼ਿਆਦਾ ਭਰੋਸੇਯੋਗਤਾ ਨਾਲ ਮੰਨਦੇ ਹਨ। ਜਦੋਂ ਤੁਹਾਨੂੰ ਕਈ ਕਦਮਾਂ ਵਾਲੇ ਪ੍ਰਕਿਰਿਆਵਾਂ ਜਾਂ ਜਟਿਲ ਲਾਜ਼ਿਕ ਦੀ ਲੋੜ ਹੋਵੇ, ਤਾਂ ਸੰਰਚਨਾ ਮਾਡਲ ਨੂੰ ਯਾਦ ਰੱਖਣ ਵਿੱਚ ਮਦਦ ਕਰਦੀ ਹੈ ਕਿ ਇਹ ਕਿੱਥੇ ਹੈ ਅਤੇ ਅੱਗੇ ਕੀ ਆਉਣਾ ਹੈ। ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਆਗ੍ਰਾਮ ਇਕ ਚੰਗੀ ਸੰਰਚਿਤ ਪ੍ਰੰਪਟ ਨੂੰ ਕਦਮ-ਦਰ-ਕਦਮ ਵਿਖਾਉਂਦਾ ਹੈ, ਜਿੱਥੇ ``, ``, ``, ``, ਅਤੇ `` ਵਰਗੇ ਟੈਗ ਤੁਹਾਡੇ ਹੁਕਮਾਂ ਨੂੰ ਸਾਫ ਖੰਡਾਂ ਵਿੱਚ ਵੰਡਦੇ ਹਨ। -Prompt Structure +ਪ੍ਰੰਪਟ ਸੰਰਚਨਾ -*ਵਧੀਆ ਸੰਰਚਿਤ ਪ੍ਰੋਮਪਟ ਦੀ ਰਚਨਾ ਜਿਸ ਵਿੱਚ ਸਪਸ਼ਟ ਹਿੱਸੇ ਅਤੇ XML-ਨੁਸਖਾ ਸੰਗਠਨ ਹੈ* +*ਇਕ ਚੰਗੀ ਸੰਰਚਿਤ ਪ੍ਰੰਪਟ ਦੀ ਬਣਤਰ ਜਿਸ ਵਿੱਚ ਸਾਫ਼-ਸੁਥਰੇ ਭਾਗ ਅਤੇ XML-ਸਟਾਈਲ ਸੰਗਠਨ ਹੈ* -**ਸੁਧਾਰ ਗੁਣਵੱਤਾ ਦੇ ਸਵੈ-ਮੁਲਾਂਕਣ ਰਾਹੀਂ** +**ਗੁਣਵੱਤਾ ਸਵੈ-ਮੂਲਾਂਕਣ ਰਾਹੀ** -Self-reflecting ਪੈਟਰਨ ਗੁਣਵੱਤਾ ਮਾਪਦੰਡਾਂ ਨੂੰ ਜਨਕਾਰੀ ਵਜੋਂ ਰੱਖਦੇ ਹਨ। ਮਾਡਲ "ਸਹੀ" ਕਰਨ ਦੀ ਉਮੀਦ ਕਰਨ ਦੀ ਬਜਾਇ ਤੁਹਾਨੂੰ ਸਪਸ਼ਟ ਦੱਸਣਾ ਪੈਂਦਾ ਹੈ ਕਿ "ਸਹੀ" ਦਾ ਕੀ ਮਤਲਬ ਹੈ: ਸਹੀ ਤਰਕ, ਠੀਕ ਵਿਕਲਪ, ਕਾਰਗੁਜ਼ਾਰੀ, ਸੁਰੱਖਿਆ। ਮਾਡਲ ਆਪਣੀ ਨਿਰਗਮ ਦੀ ਵਿਸ਼ਲੇਸ਼ਣ ਕਰਕੇ ਇਸ ਨੂੰ ਸੁਧਾਰ ਸਕਦਾ ਹੈ। ਇਹ ਕੋਡ ਬਨਾਉਣ ਨੂੰ ਬੈਠਣ ਦੀ ਖੇਡ ਤੋਂ ਇਕ ਪ੍ਰਕਿਰਿਆ ਵਿੱਚ ਬਦਲਦਾ ਹੈ। +ਸੈਲਫ-ਰਿਫਲੈਕਟਿੰਗ ਪੈਟਰਨਾਂ ਗੁਣਵੱਤਾ ਮਾਪਦੰਡਾਂ ਨੂੰ ਸਪਸ਼ਟ ਬਣਾ ਕੇ ਕੰਮ ਕਰਦੇ ਹਨ। ਮਾਡਲ ਤੋਂ ਉਮੀਦ ਕਰਨ ਦੀ ਥਾਂ ਕਿ "ਇਹ ਸਹੀ ਕਰਦਾ ਹੈ", ਤੁਸੀਂ ਇਸਨੂੰ ਸਾਫ-ਸੁਥਰੇ ਦੱਸਦੇ ਹੋ ਕਿ "ਸਹੀ" ਦਾ ਕੀ ਮਤਲਬ ਹੈ: ਸਹੀ ਤਰਕ, ਗਲਤੀ ਹੈਂਡਲਿੰਗ, ਕਾਰਕਗੁਜ਼ਾਰੀ, ਸੁਰੱਖਿਆ। ਫਿਰ ਮਾਡਲ ਆਪਣੇ ਨਤੀਜੇ ਦਾ ਮੂਲਾਂਕਣ ਕਰਦਾ ਹੈ ਅਤੇ ਸੁਧਾਰ ਖੜਾ ਕਰਦਾ ਹੈ। ਇਸ ਨਾਲ ਕੋਡ ਤਿਆਰ ਕਰਨ ਦੀ ਪ੍ਰਕਿਰਿਆ ਇੱਕ ਲਾਟਰੀ ਤੋਂ ਇਕ ਪ੍ਰਕਿਰਿਆ ਵਿੱਚ ਬਦਲ ਜਾਂਦੀ ਹੈ। -**ਸੰਦਰਭ ਸੀਮਿਤ ਹੈ** +**ਸੰਦੇਸ਼ ਦਾ ਸੰਦਰਭ ਸੀਮਤ ਹੈ** -ਮਲਟੀ-ਟਰਨ ਗੱਲਬਾਤ ਹਰ ਬੇਨਤੀ ਨਾਲ ਸੰਦਰਭ ਇਤਿਹਾਸ ਸ਼ਾਮਿਲ ਕਰਕੇ ਕੰਮ ਕਰਦੀ ਹੈ। ਪਰ ਇਕ ਸੀਮਾ ਹੈ - ਹਰ ਮਾਡਲ ਦਾ ਪ੍ਰਮੁੱਖ ਟੋਕਨ ਲਿਮਿਟ ਹੁੰਦਾ ਹੈ। ਗੱਲਬਾਤ ਵਧਣ ਨਾਲ, ਤੁਹਾਨੂੰ ਸੰਬੰਧਤ ਸੰਦਰਭ ਜੇਤੂ ਬਿਨਾਂ ਸੀਮਾ ਨੂੰ ਛੇੜੇ ਰੱਖਣ ਲਈ ਰਣਨੀਤੀਆਂ ਦੀ ਲੋੜ ਪੈਣੀ ਹੈ। ਇਹ ਮਾਡਿਊਲ ਤੁਹਾਨੂੰ ਯਾਦਦਾਸ਼ਤ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ ਦਿਖਾਉਂਦਾ ਹੈ; ਬਾਅਦ ਵਿੱਚ ਤੁਸੀਂ ਸਿੱਖੋਂਗੇ ਕਦੋਂ ਸਾਰਾਂਸ਼ ਬਣਾਉਣਾ ਹੈ, ਕਦੋਂ ਭੁੱਲਣਾ ਹੈ, ਅਤੇ ਕਦੋਂ ਹਾਸਲ ਕਰਨਾ ਹੈ। +ਮਲਟੀ-ਟਰਨ ਗੱਲਬਾਤ ਪਰਤੀਕ੍ਰਿਆਅਾਂ ਦੇ ਇਤਿਹਾਸ ਨਾਲ ਚੱਲਦੀਆਂ ਹਨ। ਪਰ ਇਸਦੀ ਹੱਦ ਹੁੰਦੀ ਹੈ - ਹਰ ਮਾਡਲ ਦੀ ਟੋਕਨ ਗਿਣਤੀ ਦੀ ਵੱਧ ਤੋਂ ਵੱਧ ਸੀਮਾ ਹੁੰਦੀ ਹੈ। ਗੱਲਬਾਤਾਂ ਵਧਣ ਨਾਲ, ਤੁਹਾਨੂੰ ਅਜਿਹੀਆਂ ਰਣਨੀਤੀਆਂ ਦੀ ਲੋੜ ਪਵੇਗੀ ਜੋ ਜਰੂਰੀ ਸੰਦਰਭ ਨੂੰ ਬਿਨਾ ਸੀਮਾ ਨੂੰ ਛੂਹੇ, ਸੁਰੱਖਿਅਤ ਰੱਖਣ। ਇਹ ਮੌਡੀਊਲ ਤੁਹਾਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਮੈਮੋਰੀ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ; ਅੱਗੇ ਤੁਸੀਂ ਸਿੱਖੋਗੇ ਕਿ ਕਦੋਂ ਸਾਰ ਬਣਾਉਣਾ ਹੈ, ਕਦੋਂ ਭੁੱਲਣਾ ਹੈ, ਅਤੇ ਕਦੋਂ ਪ੍ਰਾਪਤ ਕਰਨਾ ਹੈ। ## ਅਗਲੇ ਕਦਮ -**ਅਗਲਾ ਮਾਡਿਊਲ:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**ਅਗਲਾ ਮੌਡੀਊਲ:** [03-rag - RAG (ਰੀਟ੍ਰੀਵਲ-ਆਗਮੈਂਟਡ ਜੈਨਰੇਸ਼ਨ)](../03-rag/README.md) --- -**ਨੈਵੀਗੇਸ਼ਨ:** [← ਪਿਛਲਾ: Module 01 - ਪਰਿਚਯ](../01-introduction/README.md) | [ਮੁੱਖ ਵਾਪਸ](../README.md) | [ਅੱਗੇ: Module 03 - RAG →](../03-rag/README.md) +**ਨੇਵੀਗੇਸ਼ਨ:** [← ਪਹਿਲਾਂ: ਮੌਡੀਊਲ 01 - ਪਰਿਚਯ](../01-introduction/README.md) | [ਮੁੱਖ ਪੰਨਾ](../README.md) | [ਅਗਲਾ: ਮੌਡੀਊਲ 03 - RAG →](../03-rag/README.md) --- -**ਇਸਤਿਆਰਨਾਮਾ**: -ਇਹ ਦਸਤਾਵੇਜ਼ AI ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਅਨੁਵਾਦ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਅਤ ਲਈ ਕੋਸ਼ਿਸ਼ ਕਰਦੇ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਰਹੇ ਕਿ ਆਟੋਮੇਟਿਕ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸੁਚਿਤਾਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੇ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਪ੍ਰਮਾਣਿਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਮਹੱਤਵਪੂਰਨ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਪੈਦਾ ਹੋਣ ਵਾਲੇ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਭਵਿੱਖਦਾਂ ਲਈ ਜਿੰਮੇਵਾਰ ਨਹੀਂ ਹਾਂ। +**ਅਸਵੀਕਾਰੋਪਣ**: +ਇਸ ਦਸਤਾਵੇਜ਼ ਦਾ ਅਨੁਵਾਦ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾਵਾਂ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਮੱਤਿਆਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਜਰੂਰੀ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੇ ਉਪਯੋਗ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਗਲਤ ਵਿਆਖਿਆਵਾਂ ਲਈ ਜਵਾਬਦੇਹ ਨਹੀਂ ਹਾਂ। \ No newline at end of file diff --git a/translations/pa/03-rag/README.md b/translations/pa/03-rag/README.md index b3fc74d51..b9271a65c 100644 --- a/translations/pa/03-rag/README.md +++ b/translations/pa/03-rag/README.md @@ -1,144 +1,143 @@ -# ਮੋਡੀਊਲ 03: RAG (ਰਿਟਰੀਵਲ-ਆਗਮੈਂਟਡ ਜਨਰੇਸ਼ਨ) - -## ਸੂਚੀ - -- [ਵੀਡੀਓ ਵਾਕਥਰੂ](../../../03-rag) -- [ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ](../../../03-rag) -- [ਪੂਰਵ-ਆਵਸ਼ਕਤਾ](../../../03-rag) -- [RAG ਨੂੰ ਸਮਝਣਾ](../../../03-rag) - - [ਇਸ ਟਿਊਟੋਰਿਅਲ ਵਿੱਚ ਕਿਹੜਾ RAG ਪਹੁੰਚ ਵਰਤੀ ਜਾਂਦੀ ਹੈ?](../../../03-rag) -- [ਇਹ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ](../../../03-rag) - - [ਦਸਤਾਵੇਜ਼ ਪ੍ਰਕਿਰਿਆ](../../../03-rag) - - [ਐਮਬੈੱਡਿੰਗ ਬਣਾਉਣਾ](../../../03-rag) - - [ਸੇਮੈਂਟਿਕ ਖੋਜ](../../../03-rag) - - [ਜਵਾਬ ਤਿਆਰ ਕਰਨਾ](../../../03-rag) -- [ਐਪਲੀਕੇਸ਼ਨ ਚਲਾਓ](../../../03-rag) -- [ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਵਰਤੋਂ](../../../03-rag) - - [ਦਸਤਾਵੇਜ਼ ਅਪਲੋਡ ਕਰੋ](../../../03-rag) - - [ਸਵਾਲ ਪੁੱਛੋ](../../../03-rag) - - [ਸਰੋਤ ਸੰਦਰਭ ਜਾਂਚੋ](../../../03-rag) - - [ਸਵਾਲਾਂ ਨਾਲ ਪ੍ਰਯੋਗ ਕਰੋ](../../../03-rag) -- [ਮੁੱਖ ਵਿਸ਼ੇਸ਼ਤਾਵਾਂ](../../../03-rag) - - [ਚੰਕਿੰਗ ਰਣਨੀਤੀ](../../../03-rag) - - [ਸਪਸ਼ਟਤਾ ਸਕੋਰ](../../../03-rag) - - [ਇਨ-ਮੇਮੋਰੀ ਸਟੋਰੇਜ](../../../03-rag) - - [ਸੰਦਰਭ ਵਿੰਡੋ ਪ੍ਰਬੰਧਨ](../../../03-rag) -- [ਕਦੋਂ RAG ਮਹੱਤਵਪੂਰਨ ਹੁੰਦਾ ਹੈ](../../../03-rag) -- [ਅਗਲੇ ਕਦਮ](../../../03-rag) - -## ਵੀਡੀਓ ਵਾਕਥਰੂ - -ਇਸ ਲਾਈਵ ਸੈਸ਼ਨ ਨੂੰ ਦੇਖੋ ਜੋ ਇਸ ਮੋਡੀਊਲ ਨਾਲ ਸ਼ੁਰੂਆਤ ਕਰਨ ਦਾ ਤਰੀਕਾ ਸਮਝਾਂਦਾ ਹੈ: - -RAG with LangChain4j - Live Session +# ਮੌਡੀਊਲ 03: RAG (ਰ retrieval-ਵਧੀਆ ਜਨਰੇਸ਼ਨ) + +## ਸੂਚੀ ਸਾਰਣੀ + +- [ਵਿਡੀਓ ਵਾਕਥਰੂ](#ਵਿਡੀਓ-ਵਾਕਥਰੂ) +- [ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ](#ਤੁਸੀਂ-ਕੀ-ਸਿੱਖੋਗੇ) +- [ਪੂਰਵਜਾਣਕਾਰੀ](#ਪੂਰਵਜਾਣਕਾਰੀ) +- [RAG ਨੂੰ ਸਮਝਣਾ](#rag-ਨੂੰ-ਸਮਝਣਾ) + - [ਇਸ ਟਿਊਟੋਰੀਅਲ ਲਈ ਕਿਹੜਾ RAG ਤਰੀਕਾ ਵਰਤਿਆ ਗਿਆ ਹੈ?](#ਇਸ-ਟਿਊਟੋਰੀਅਲ-ਵਿੱਚ-ਕਿਹੜਾ-rag-ਤਰੀਕਾ-ਵਰਤਿਆ-ਜਾਂਦਾ-ਹੈ) +- [ਇਹ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ](#ਇਹ-ਕਿਵੇਂ-ਕੰਮ-ਕਰਦਾ-ਹੈ) + - [ਦਸਤਾਵੇਜ਼ ਪ੍ਰੋਸੈਸਿੰਗ](#ਦਸਤਾਵੇਜ਼-ਪ੍ਰੋਸੈਸਿੰਗ) + - [ਐਮਬੈਡਿੰਗ ਬਣਾਉਣਾ](#ਐਮਬੈਡਿੰਗ-ਬਣਾਉਣਾ) + - [ਸਮਾਂਤਰੀ ਖੋਜ](#ਸਮਾਂਤਰੀ-ਖੋਜ) + - [ਜਵਾਬ ਜਨਰੇਸ਼ਨ](#ਜਵਾਬ-ਤਿਆਰ-ਕਰਨਾ) +- [ਐਪਲੀਕੇਸ਼ਨ ਚਲਾਉਣਾ](#ਐਪਲੀਕੇਸ਼ਨ-ਚਲਾਓ) +- [ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਵਰਤੋਂ](#ਐਪਲੀਕੇਸ਼ਨ-ਦੀ-ਵਰਤੋਂ) + - [ਇੱਕ ਦਸਤਾਵੇਜ਼ ਅਪਲੋਡ ਕਰੋ](#ਦਸਤਾਵੇਜ਼-ਅਪਲੋਡ-ਕਰੋ) + - [ਸਵਾਲ ਪੁੱਛੋ](#ਸਵਾਲ-ਪੁੱਛੋ) + - [ਸੋਰਸ ਸੰਦਰਭ ਦੀ ਜਾਂਚ ਕਰੋ](#ਸਰੋਤ-ਸੰਦਰਭ-ਜਾਂਚੋ) + - [ਸਵਾਲਾਂ ਨਾਲ ਪ੍ਰਯੋਗ ਕਰੋ](#ਸਵਾਲਾਂ-ਨਾਲ-ਪ੍ਰਯੋਗ-ਕਰੋ) +- [ਮੁੱਖ ਧਾਰਣਾਂ](#ਮੁੱਖ-ਧਾਰਨਾਵਾਂ) + - [ਚੰਕਿੰਗ ਰਣਨੀਤੀ](#ਟੁਕੜਾ-ਬਣਾਉਣ-ਦੀ-ਰਣਨੀਤੀ) + - [ਸਮਾਨਤਾ ਸਕੋਰ](#ਸਮਾਨਤਾ-ਸਕੋਰ) + - [ਮੇਮੋਰੀ ਵਿੱਚ ਸਟੋਰੇਜ](#ਇਨ-ਮੇਮੋਰੀ-ਸਟੋਰੇਜ) + - [ਸੰਦਰਭ ਵਿੰਡੋ ਪ੍ਰਬੰਧਨ](#ਸੰਦਰਭ-ਵਿਂਡੋ-ਪ੍ਰਬੰਧਨ) +- [ਜਦੋਂ RAG ਮਹੱਤਵਪੂਰਨ ਹੈ](#ਜਦੋਂ-rag-ਅਹਮ-ਹੁੰਦਾ-ਹੈ) +- [ਅਗਲੇ ਕਦਮ](#ਅਗਲਾ-ਕਦਮ) + +## ਵਿਡੀਓ ਵਾਕਥਰੂ + +ਇਸ ਲਾਈਵ ਸੈਸ਼ਨ ਨੂੰ ਦੇਖੋ ਜੋ ਇਸ ਮੌਡੀਊਲ ਨਾਲ ਸ਼ੁਰੂਆਤ ਕਰਨ ਦਾ ਤਰੀਕਾ ਸਮਝਾਉਂਦਾ ਹੈ: + +LangChain4j ਨਾਲ RAG - ਲਾਈਵ ਸੈਸ਼ਨ ## ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ -ਪਿਛਲੇ ਮੋਡੀਊਲਾਂ ਵਿੱਚ, ਤੁਸੀਂ AI ਨਾਲ ਗੱਲਬਾਤ ਕਰਨਾ ਅਤੇ ਆਪਣੇ ਪ੍ਰਾਂਪਟਸ ਨੂੰ ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਢੰਗ ਨਾਲ ਢਾਂਚਾ ਕਰਨਾ ਸਿੱਖਿਆ ਸੀ। ਪਰ ਇੱਕ ਬੁਨਿਆਦੀ ਸੀਮਾ ਹੈ: ਭਾਸ਼ਾ ਮਾਡਲ ਸਿਰਫ ਉਹੀ ਜਾਣਦੇ ਹਨ ਜੋ ਉਹਨਾਂ ਨੇ ਟ੍ਰੇਨਿੰਗ ਦੌਰਾਨ ਸਿੱਖਿਆ। ਉਹ ਤੁਹਾਡੀ ਕੰਪਨੀ ਦੀਆਂ ਨੀਤੀਆਂ, ਪ੍ਰੋਜੈਕਟ ਡੌਕੂਮੈਂਟੇਸ਼ਨ ਜਾਂ ਕਿਸੇ ਐਸੀ ਜਾਣਕਾਰੀ ਬਾਰੇ ਸਵਾਲ ਦੇ ਜਵਾਬ ਨਹੀਂ ਦੇ ਸਕਦੇ ਜੋ ਉਹਨਾਂ ਨੂੰ ਟ੍ਰੇਨਿੰਗ ਨਹੀਂ ਮਿਲੀ। +ਪਿਛਲੇ ਮੌਡੀਊਲਾਂ ਵਿੱਚ, ਤੁਸੀਂ AI ਨਾਲ ਗੱਲਬਾਤ ਕਰਨਾ ਅਤੇ ਆਪਣੇ ਪ੍ਰਾਂਪਟਸ ਨੂੰ ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਢੰਗ ਨਾਲ ਬਣਾਉਣਾ ਸਿੱਖਿਆ। ਪਰ ਇਸ ਵਿੱਚ ਇੱਕ ਮੁੱਢਲਾ ਸੀਮਾ ਹੈ: ਭਾਸ਼ਾ ਮਾਡਲ ਆਪ ਲਗਾਤਾਰ ਸਿਖਾਈ ਗਈ ਜਾਣਕਾਰੀ ਤੋਂ ਹੀ ਜਾਣਦੇ ਹਨ। ਉਹ ਤੁਹਾਡੇ ਕੰਪਨੀ ਦੀਆਂ ਨੀਤੀਆਂ, ਪ੍ਰੋਜੈਕਟ ਦਸਤਾਵੇਜ਼ ਜਾਂ ਕੋਈ ਐਸੀ ਜਾਣਕਾਰੀ ਜਿਸ 'ਤੇ ਉਹ ਸਿਖਾਏ ਨਹੀਂ ਗਏ, ਉਨ੍ਹਾਂ ਬਾਰੇ ਸਵਾਲਾਂ ਦੇ ਜਵਾਬ ਨਹੀਂ ਦੇ ਸਕਦੇ। -RAG (ਰਿਟਰੀਵਲ-ਆਗਮੈਂਟਡ ਜਨਰੇਸ਼ਨ) ਇਸ ਸਮੱਸਿਆ ਨੂੰ ਹੱਲ ਕਰਦਾ ਹੈ। ਮਾਡਲ ਨੂੰ ਤੁਹਾਡੀ ਜਾਣਕਾਰੀ ਸਿਖਾਉਣ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰਨ ਦੀ ਬਜਾਏ (ਜੋ ਮਹਿੰਗਾ ਅਤੇ ਅਪਰਭਾਵੀ ਹੈ), ਤੁਸੀਂ ਇਸਨੂੰ ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ਾਂ ਵਿੱਚ ਖੋਜ ਕਰਨ ਦੀ ਸਮਰੱਥਾ ਦਿੰਦੇ ਹੋ। ਜਦੋਂ ਕੋਈ ਸਵਾਲ ਪੁੱਛਦਾ ਹੈ, ਸਿਸਟਮ ਸੰਬੰਧਿਤ ਜਾਣਕਾਰੀ ਲੱਭਦਾ ਹੈ ਅਤੇ ਉਸ ਨੂੰ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ। ਫਿਰ ਮਾਡਲ ਉਸ ਪ੍ਰਾਪਤ ਸੰਦਰਭ ਦੇ ਅਧਾਰ 'ਤੇ ਜਵਾਬ ਦਿੰਦਾ ਹੈ। +RAG (ਰ retrieval-ਵਧੀਆ ਜਨਰੇਸ਼ਨ) ਇਸ ਸਮੱਸਿਆ ਨੂੰ ਹੱਲ ਕਰਦਾ ਹੈ। ਮਾਡਲ ਨੂੰ ਆਪਣੀ ਜਾਣਕਾਰੀ ਸਿੱਖਾਉਣ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰਨ ਦੀ ਬਜਾਏ (ਜੋ ਮਹਿੰਗੀ ਤੇ ਅਪਰਿਆਪਤ ਹੈ), ਤੁਸੀਂ ਇਸਨੂੰ ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ਾਂ ਵਿੱਚ ਖੋਜ ਕਰਨ ਦੀ ਸਮਰੱਥਾ ਦਿੰਦੇ ਹੋ। ਜਦੋਂ ਕੋਈ ਸਵਾਲ ਪੁੱਛਦਾ ਹੈ, ਤਰਤੀਬ ਬਰਾਬਰ ਜਾਣਕਾਰੀ ਲੱਭਦਾ ਹੈ ਅਤੇ ਉਸਨੂੰ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ। ਮਾਡਲ ਫਿਰ ਉਸ ਪ੍ਰਾਪਤ ਸੰਦਰਭ ਦੇ ਆਧਾਰ 'ਤੇ ਜਵਾਬ ਦਿੰਦਾ ਹੈ। -RAG ਨੂੰ ਮਾਡਲ ਨੂੰ ਇੱਕ ਸੰਦਰਭ ਲਾਇਬ੍ਰੇਰੀ ਦੇਣ ਵਾਂਗੋਂ ਸੋਚੋ। ਜਦੋਂ ਤੁਸੀਂ ਸਵਾਲ ਪੁੱਛਦੇ ਹੋ, ਸਿਸਟਮ: +RAG ਨੂੰ ਮਾਡਲ ਨੂੰ ਇੱਕ ਸੰਦਰਭ ਲਾਇਬ੍ਰੇਰੀ ਦਿੱਤੀ ਜਾਣ ਵਾਂਗ ਸੋਚੋ। ਜਦੋਂ ਤੁਸੀਂ ਸਵਾਲ ਪੁੱਛਦੇ ਹੋ, ਸਿਸਟਮ: -1. **ਉਪਭੋਗਤਾ ਕਵੇਰੀ** - ਤੁਸੀਂ ਸਵਾਲ ਪੁੱਛਦੇ ਹੋ -2. **ਐਮਬੈੱਡਿੰਗ** - ਤੁਹਾਡਾ ਸਵਾਲ ਵੈਕਟਰ ਵਿੱਚ ਬਦਲਦਾ ਹੈ -3. **ਵੈਕਟਰ ਖੋਜ** - ਮਿਲਦੇ ਜੁਲਦੇ ਦਸਤਾਵੇਜ਼ਾਂ ਦੇ ਟੁਕੜੇ ਲੱਭਦਾ ਹੈ -4. **ਸੰਦਰਭ ਇਕੱਠਾ ਕਰਨਾ** - ਸੰਬੰਧਿਤ ਟੁਕੜੇ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ -5. **ਜਵਾਬ** - LLM ਉਸ ਸੰਦਰਭ ਦੇ ਅਧਾਰ 'ਤੇ ਜਵਾਬ ਤਿਆਰ ਕਰਦਾ ਹੈ +1. **ਯੂਜ਼ਰ ਪੁੱਛਤਾਛ** - ਤੁਸੀਂ ਸਵਾਲ ਕਰਦੇ ਹੋ +2. **ਐਮਬੈਡਿੰਗ** - ਤੁਹਾਡੇ ਸਵਾਲ ਨੂੰ ਇੱਕ ਵੇਕਟਰ ਵਿੱਚ ਬਦਲਦਾ ਹੈ +3. **ਵੇਕਟਰ ਖੋਜ** - ਸਮਾਨ ਦਸਤਾਵੇਜ਼ ਚੰਕ ਲੱਭਦਾ ਹੈ +4. **ਸੰਦਰਭ ਇਕੱਤਰਕਰਨ** - ਸੰਬੰਧਿਤ ਚੰਕ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਜੋੜਦਾ ਹੈ +5. **ਜਵਾਬ** - LLM ਸੰਦਰਭ ਦੇ ਆਧਾਰ ‘ਤੇ ਜਵਾਬ ਜਨਰੇਟ ਕਰਦਾ ਹੈ -ਇਸ ਨਾਲ ਮਾਡਲ ਦੇ ਜਵਾਬ ਤੁਹਾਡੇ ਅਸਲੀ ਡੇਟਾ 'ਤੇ ਅਧਾਰਿਤ ਹੁੰਦੇ ਹਨ ਨਾ ਕਿ ਉਸ ਦੀ ਟ੍ਰੇਨਿੰਗ ਜਾਣਕਾਰੀ ਜਾਂ ਜਵਾਬ ਬਣਾਉਣ 'ਤੇ। +ਇਸ ਨਾਲ ਮਾਡਲ ਦੇ ਜਵਾਬ ਤੁਹਾਡੇ ਅਸਲੀ ਡੇਟੇ 'ਤੇ ਅਧਾਰਤ ਹੋ ਜਾਂਦੇ ਹਨ ਨਾਂ ਕਿ ਸਿਖਿਆ ਜਾਂ ਮਿਤੀ ਕਹਾਣੀ ਤੇ। -## ਪੂਰਵ-ਆਵਸ਼ਕਤਾ +## ਪੂਰਵਜਾਣਕਾਰੀ -- ਪੂਰਾ ਕੀਤਾ [ਮੋਡੀਊਲ 00 - ਤੇਜ਼ ਸ਼ੁਰੂਆਤ](../00-quick-start/README.md) (ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ ਬਾਅਦ ਵਿੱਚ ਹਵਾਲਾ ਦਿੱਤਾ ਗਿਆ ਆਸਾਨ RAG ਉਦਾਹਰਨ ਲਈ) -- ਪੂਰਾ ਕੀਤਾ [ਮੋਡੀਊਲ 01 - ਜਾਣ-ਪਛਾਣ](../01-introduction/README.md) (Azure OpenAI ਸਰੋਤ ਤੈਅ ਹੋਏ, ਜਿਸ ਵਿੱਚ `text-embedding-3-small` ਐਮਬੈੱਡਿੰਗ ਮਾਡਲ ਸ਼ਾਮਲ ਹੈ) -- ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ `.env` ਫਾਇਲ Azure ਪ੍ਰਮਾਣ ਪੱਤਰਾਂ ਨਾਲ (ਮੋਡੀਊਲ 01 ਵਿੱਚ `azd up` ਦੁਆਰਾ ਬਣਾਈ ਗਈ) +- [Module 01 - ਪਰਿਚਯ](../01-introduction/README.md) ਮੁਕੰਮਲ ਕੀਤਾ ਹੋਇਆ (Azure OpenAI ਸਰੋਤ ਤੈਅਰ ਕੀਤੇ, ਜਿਸ ਵਿੱਚ `text-embedding-3-small` ਐਮਬੈਡਿੰਗ ਮਾਡਲ ਸ਼ਾਮਿਲ ਹੈ) +- ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ `.env` ਫਾਈਲ ਜਿਸ ਵਿੱਚ Azure ਵਿਵਰਣ ਹੈ (Module 01 ਵਿੱਚ `azd up` ਨਾਲ ਬਣਾਈ ਗਈ) -> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਮੋਡੀਊਲ 01 ਪੂਰਾ ਨਹੀਂ ਕੀਤਾ, ਤਾਂ ਪਹਿਲਾਂ ਉਥੇ ਦਿੱਤੇ ਡਿਪਲੋਇਮੈਂਟ ਹਦਾਇਤਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ। `azd up` ਕਮਾਂਡ GPT ਚੈਟ ਮਾਡਲ ਅਤੇ ਐਮਬੈੱਡਿੰਗ ਮਾਡਲ ਦੋਹਾਂ ਨੂੰ ਡਿਪਲੋਇ ਕਰਦਾ ਹੈ ਜੋ ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ ਵਰਤੇ ਜਾਂਦੇ ਹਨ। +> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ Module 01 ਮੁਕੰਮਲ ਨਹੀਂ ਕੀਤਾ, ਤਾਂ ਸਭ ਤੋਂ ਪਹਿਲਾਂ ਉਥੇ ਦਿੱਤੇ ਡਿਪਲੋਇਮੈਂਟ ਨਿਰਦੇਸ਼ਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ। `azd up` ਕਮਾਂਡ GPT ਚੈਟ ਮਾਡਲ ਅਤੇ ਇਸ ਮੌਡੀਊਲ ਦੇ ਐਮਬੈਡਿੰਗ ਮਾਡਲ ਦੋਹਾਂ ਨੂੰ ਡਿਪਲੋਇ ਕਰਦਾ ਹੈ। ## RAG ਨੂੰ ਸਮਝਣਾ -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਯਾਗ੍ਰਾਮ ਮੁੱਖ ਧਾਰਨਾ ਦਿਖਾਉਂਦਾ ਹੈ: ਸਿਰਫ ਮਾਡਲ ਦੀ ਟ੍ਰੇਨਿੰਗ ਡੇਟਾ 'ਤੇ ਨਿਰਭਰ ਕਰਨ ਦੀ ਬਜਾਏ, RAG ਇਸਨੂੰ ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ਾਂ ਦੀ ਇੱਕ ਸੰਦਰਭ ਲਾਇਬ੍ਰੇਰੀ ਦਿੰਦਾ ਹੈ ਜੋ ਹਰ ਜਵਾਬ ਪੈਦਾ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਸਲਾਹ ਲਈ ਜਾਂਦੀ ਹੈ। +ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਮੁੱਖ ਧਾਰਨਾ ਦਿਖਾਉਂਦਾ ਹੈ: ਮਾਡਲ ਦੀ ਸਿਰਫ ਸਿਖਲਾਈ ਡੇਟਾ 'ਤੇ ਭਰੋਸਾ ਕਰਨ ਦੀ ਥਾਂ, RAG ਇਸਨੂੰ ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ਾਂ ਦੀ ਰੇਫਰੈਂਸ ਲਾਇਬ੍ਰੇਰੀ ਦਿੰਦਾ ਹੈ ਜਿਸਨੂੰ ਇਹ ਹਰ ਜਵਾਬ ਦੇਣ ਤੋਂ ਪਹਿਲਾਂ ਵੇਖ ਸਕਦਾ ਹੈ। -What is RAG +RAG ਕੀ ਹੈ -*ਇਹ ਡਾਯਾਗ੍ਰਾਮ ਇੱਕ ਸਧਾਰਣ LLM (ਜੋ ਟ੍ਰੇਨਿੰਗ ਡੇਟਾ ਵਿੱਚੋਂ ਅਨੁਮਾਨ ਲਗਾਉਂਦਾ ਹੈ) ਅਤੇ RAG-ਵਧੀਤ LLM (ਜੋ ਪਹਿਲਾਂ ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਸਲਾਹ ਦਿੰਦਾ ਹੈ) ਵਿੱਚ ਫਰਕ ਦਿਖਾਉਂਦਾ ਹੈ।* +*ਇਹ ਡਾਇਗ੍ਰਾਮ ਇੱਕ ਮਿਆਰੀ LLM (ਜੋ ਸਿਖਲਾਈ ਡੇਟਾ ਤੋਂ ਅਨੁਮਾਨ ਲਗਾਉਂਦਾ ਹੈ) ਅਤੇ RAG-ਸੰਵਰਧਿਤ LLM (ਜੋ ਪਹਿਲਾਂ ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਸਲਾਹ-ਮਸ਼ਵਰਾ ਕਰਦਾ ਹੈ) ਵਿੱਚ ਅੰਤਰ ਦਿਖਾਉਂਦਾ ਹੈ।* -ਇੱਥੇ ਦੇਖੋ ਕਿ ਕਿਵੇਂ ਟੁਕੜੇ ਅੰਤ-ਅੰਤ ਕਨੈਕਟ ਹੁੰਦੇ ਹਨ। ਇੱਕ ਉਪਭੋਗਤਾ ਦਾ ਸਵਾਲ ਚਾਰ ਕਦਮਾਂ ਰਾਹੀਂ ਜਾਂਦਾ ਹੈ — ਐਮਬੈੱਡਿੰਗ, ਵੈਕਟਰ ਖੋਜ, ਸੰਦਰਭ ਇਕੱਠਾ ਕਰਨਾ, ਅਤੇ ਜਵਾਬ ਤਿਆਰ ਕਰਨਾ — ਜੋ ਹਰੇਕ ਪਿਛਲੇ 'ਤੇ ਨਿਰਭਰ ਹੁੰਦੇ ਹਨ: +ਇਹ ਫੇਰ ਬਿਆਨ ਕਰਦਾ ਹੈ ਕਿ ਇਹ ਟੁਕੜੇ ਕਿਵੇਂ ਅੰਤ ਤੋਂ ਅੰਤ ਨੂੰ ਜੁੜਦੇ ਹਨ। ਇੱਕ ਯੂਜ਼ਰ ਦਾ ਸਵਾਲ ਚਾਰ ਚਰਣਾਂ ਵਿੱਚੋਂ ਵਗਦਾ ਹੈ — ਐਮਬੈਡਿੰਗ, ਵੇਕਟਰ ਖੋਜ, ਸੰਦਰਭ ਇਕੱਠਾ ਕਰਨ ਅਤੇ ਜਵਾਬ ਜਨਰੇਸ਼ਨ — ਹਰ ਇੱਕ ਪਿਛਲੇ ਤੇ ਆਧਾਰਿਤ: -RAG Architecture +RAG ਢਾਂਚਾ -*ਇਹ ਡਾਯਾਗ੍ਰਾਮ ਸੰਪੂਰਨ RAG ਪਾਈਪਲਾਈਨ ਦਿਖਾਉਂਦਾ ਹੈ — ਇੱਕ ਉਪਭੋਗਤਾ ਕਵੇਰੀ ਐਮਬੈੱਡਿੰਗ, ਵੈਕਟਰ ਖੋਜ, ਸੰਦਰਭ ਇਕੱਠਾ ਕਰਨ ਅਤੇ ਜਵಾಬ ਤਿਆਰ ਕਰਨ ਰਾਹੀਂ ਜਾਂਦਾ ਹੈ।* +*ਇਹ ਡਾਇਗ੍ਰਾਮ ਅੰਤ ਤੱਕ RAG ਪਾਈਪਲਾਈਨ ਦਿਖਾਉਂਦਾ ਹੈ — ਇੱਕ ਯੂਜ਼ਰ ਪੁੱਛਤਾਛ ਐਮਬੈਡਿੰਗ, ਵੇਕਟਰ ਖੋਜ, ਸੰਦਰਭ ਇਕੱਤਰਕਰਨ, ਅਤੇ ਜਵਾਬ ਜਨਰੇਸ਼ਨ ਵਿੱਚੋਂ ਵਗਦੀ ਹੈ।* -ਬਾਕੀ ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ ਹਰ ਕਦਮ ਦਾ ਵਿਸਥਾਰ ਨਾਲ ਵਰਣਨ ਕੀਤਾ ਗਿਆ ਹੈ, ਜਿਸ ਵਿੱਚ ਤੁਹਾਡੇ ਲਈ ਕੋਡ ਦਿੱਤਾ ਗਿਆ ਹੈ ਜੋ ਤੁਸੀਂ ਚਲਾ ਸਕਦੇ ਹੋ ਅਤੇ ਸੋਧ ਸਕਦੇ ਹੋ। +ਬਾਕੀ ਇਸ ਮੌਡੀਊਲ ਵਿੱਚ ਹਰੇਕ ਚਰਣ ਨੂੰ ਵਿਸਥਾਰ ਨਾਲ ਵਿਆਖਿਆ ਕੀਤਾ ਗਿਆ ਹੈ, ਜਿਸ ਨੂੰ ਤੁਸੀਂ ਚਲਾ ਸਕਦੇ ਹੋ ਅਤੇ ਸੋਧ ਕਰ ਸਕਦੇ ਹੋ। -### ਇਸ ਟਿਊਟੋਰਿਅਲ ਵਿੱਚ ਕਿਹੜਾ RAG ਪਹੁੰਚ ਵਰਤੀ ਜਾਂਦੀ ਹੈ? +### ਇਸ ਟਿਊਟੋਰੀਅਲ ਵਿੱਚ ਕਿਹੜਾ RAG ਤਰੀਕਾ ਵਰਤਿਆ ਜਾਂਦਾ ਹੈ? -LangChain4j RAG ਨੂੰ ਲਾਗੂ ਕਰਨ ਲਈ ਤਿੰਨ ਢੰਗ ਦਿੰਦਾ ਹੈ, ਹਰ ਇੱਕ ਵੱਖਰੇ ਮੈਪਿੰਗ ਪੱਧਰ ਨਾਲ। ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਯਾਗ੍ਰਾਮ ਉਹਨਾਂ ਦੀ ਤੁਲਨਾ ਕਰਦਾ ਹੈ: +LangChain4j RAG ਨੂੰ ਲਾਗੂ ਕਰਨ ਲਈ ਤਿੰਨ ਤਰੀਕੇ ਦਿੰਦਾ ਹੈ, ਹਰ ਇਕ ਵੱਖ-ਵੱਖ ਪੱਧਰ ਦੀ ਅਬੱਸਟ੍ਰੈਕਸ਼ਨ ਨਾਲ। ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਉਹਨਾਂ ਨੂੰ ਇਕ-ਦੂਜੇ ਦੇ ਨਾਲ ਚੁੱਕ ਕੇ ਦਿਖਾਉਂਦਾ ਹੈ: -Three RAG Approaches in LangChain4j +LangChain4j ਵਿੱਚ ਤਿੰਨ RAG ਤਰੀਕੇ -*ਇਹ ਡਾਯਾਗ੍ਰਾਮ ਤਿੰਨ LangChain4j RAG ਪਹੁੰਚਾਂ — ਆਸਾਨ, ਘਰੇਲੂ, ਅਤੇ ਉੱਚ ਪੱਧਰੀ — ਦੀ ਤੁਲਨਾ ਕਰਦਾ ਹੈ, ਉਹਨਾਂ ਦੇ ਮੁੱਖ ਹਿੱਸਿਆਂ ਅਤੇ ਵਰਤੋਂ ਲਈ ਪ੍ਰਸੰਗ ਦਿਖਾਉਂਦਾ ਹੈ।* +*ਇਹ ਡਾਇਗ੍ਰਾਮ ਤਿੰਨ LangChain4j RAG ਤਰੀਕਿਆਂ — ਆਸਾਨ, ਦੇਸੀ, ਅਤੇ ਅਡਵਾਂਸਡ — ਦੀ ਤੁਲਨਾ ਕਰਦਾ ਹੈ, ਉਹਨਾਂ ਦੇ ਮੁੱਖ ਅੰਗ ਅਤੇ ਕਿਸ ਸਮੇਂ ਵਰਤਣੇ ਹਨ ਦਿਖਾਉਂਦਾ ਹੈ।* -| ਪਹੁੰਚ | ਕੀ ਕਰਦੀ ਹੈ | ਤਜਰਬਾ | +| ਤਰੀਕਾ | ਇਹ ਕੀ ਕਰਦਾ ਹੈ | ਤਕਸਤੀ | |---|---|---| -| **ਆਸਾਨ RAG** | ਸਾਰਾ ਕੰਮ `AiServices` ਅਤੇ `ContentRetriever` ਰਾਹੀਂ ਆਪਣੇ ਆਪ ਕनेकਟ ਕਰਦਾ ਹੈ। ਤੁਸੀਂ ਇੰਟਰਫੇਸ ਨੂੰ ਐਨੋਟੇਟ ਕਰਦੇ ਹੋ, ਇੱਕ ਰਿਟਰੀਵਰ ਲਗਾਉਂਦੇ ਹੋ, ਤੇ LangChain4j ਐਮਬੈੱਡਿੰਗ, ਖੋਜ ਅਤੇ ਪ੍ਰਾਂਪਟ ਇਕੱਠਾ ਕਰਨ ਦਾ ਕੰਮ ਪਿੱਛੇ ਕਰਦਾ ਹੈ। | ਘੱਟ ਕੋਡ, ਪਰ ਹਰ ਕਦਮ ਤੇ ਕੀ ਕਿੰਝ ਹੋ ਰਿਹਾ ਹੈ ਇਹ ਨਹੀਂ ਵੇਖਦੇ। | -| **ਘਰੇਲੂ RAG** | ਤੁਸੀਂ ਆਪਣੇ ਆਪ ਐਮਬੈੱਡਿੰਗ ਮਾਡਲ ਨੂੰ ਕਾਲ ਕਰਦੇ ਹੋ, ਸਟੋਰ ਵਿੱਚ ਖੋਜ ਕਰਦੇ ਹੋ, ਪ੍ਰਾਂਪਟ ਤਿਆਰ ਕਰਦੇ ਹੋ, ਅਤੇ ਜਵਾਬ ਉਤਪੰਨ ਕਰਦੇ ਹੋ — ਹਰ ਇਕ ਕਦਮ ਵਿਸਥਾਰ ਨਾਲ। | ਵੱਧ ਕੋਡ, ਪਰ ਹਰ ਪੜਾਅ ਨੂੰ ਵੇਖਣਾ ਅਤੇ ਸੋਧਣਾ ਮੁਮਕਿਨ। | -| **ਉੱਚ ਪੱਧਰੀ RAG** | `RetrievalAugmentor` ਫਰੇਮਵਰਕ ਵਰਤਦਾ ਹੈ ਜਿਸ ਵਿੱਚ ਕਵੈਰੀ ਟ੍ਰਾਂਸਫਾਰਮਰ, ਰਾਉਟਰ, ਰੀ-ਰੈਂਕਰ, ਅਤੇ ਸਮੱਗਰੀ ਇੰਜੈਕਟਰ ਸ਼ਾਮਲ ਹਨ ਪ੍ਰੋਡਕਸ਼ਨ-ਗਰੇਡ ਪਾਈਪਲਾਈਨਾਂ ਲਈ। | ਬਹੁਤ ਲਚਕੀਲਾ, ਪਰ ਕਾਫੀ ਜਟਿਲ। | +| **ਆਸਾਨ RAG** | ਸਾਰੇ ਕੰਮ `AiServices` ਅਤੇ `ContentRetriever` ਰਾਹੀਂ ਆਪਣੇ-ਆਪ ਹੀ ਕਰ ਦਿੰਦਾ ਹੈ। ਤੁਸੀਂ ਇੱਕ ਇੰਟਰਫੇਸ ਨੂੰ ਅਨੋਟੇਟ ਕਰਦੇ ਹੋ, ਇੱਕ ਰਿਟਰੀਵਰ ਜੋੜਦੇ ਹੋ, ਅਤੇ LangChain4j ਐਮਬੈਡਿੰਗ, ਖੋਜ, ਅਤੇ ਪ੍ਰਾਂਪਟ ਤਿਆਰ ਕਰਨ ਦਾ ਕੰਮ ਆਪਣੇ ਆਪ ਕਰਦਾ ਹੈ। | ਸਭ ਤੋਂ ਘੱਟ ਕੋਡ ਲੱਗਦਾ ਹੈ, ਪਰ ਹਰ ਕਦਮ ਤੇ ਕੀ ਹੋ ਰਿਹਾ ਹੈ ਵਿਖਾਈ ਨਹੀਂ ਦਿੰਦਾ। | +| **ਦੇਸੀ RAG** | ਤੁਸੀਂ ਐਮਬੈਡਿੰਗ ਮਾਡਲ ਨੂੰ ਕਾਲ ਕਰਦੇ ਹੋ, ਸਟੋਰ ਖੋਜਦੇ ਹੋ, ਪ੍ਰਾਂਪਟ ਬਣਾਉਂਦੇ ਹੋ, ਅਤੇ ਜਵਾਬ ਆਪਣੇ ਆਪ ਜਨਰੇਟ ਕਰਦੇ ਹੋ — ਇੱਕ-ਇੱਕ ਕਦਮ ਖੁੱਲ੍ਹਾ ਤੇ ਸਪਸ਼ਟ। | ਹੋਰ ਕੋਡ ਲੱਗਦਾ ਹੈ, ਪਰ ਹਰ ਚਰਣ ਮੁੱਖ ਅਤੇ ਸੋਧਯੋਗ ਹੈ। | +| **ਅਡਵਾਂਸਡ RAG** | `RetrievalAugmentor` ਫਰੇਮਵਰਕ ਵਰਤਦਾ ਹੈ ਜਿਸ ਵਿੱਚ ਪੁਲੱਗਿੰਗ ਯੋਗ ਕਵੇਰੀ ਟ੍ਰਾਂਸਫਾਰਮਰ, ਰਾਊਟਰ, ਰੀ-ਰੈਂਕਰ, ਅਤੇ ਕੰਟੈਂਟ ਇੰਜੈਕਟਰ ਸ਼ਾਮਿਲ ਹਨ ਪ੍ਰੋਡਕਸ਼ਨ-ਗਰੇਡ ਪਾਈਪਲਾਈਨ ਲਈ। | ਸਭ ਤੋਂ ਜ਼ਿਆਦਾ ਲਚੀਲਾਪਣ, ਪਰ ਖਾਸ ਤੌਰ ਤੇ ਜਟਿਲਤਾ ਵੀ। | -**ਇਹ ਟਿਊਟੋਰਿਅਲ ਘਰੇਲੂ ਪਹੁੰਚ ਵਰਤਦਾ ਹੈ।** RAG ਪਾਈਪਲਾਈਨ ਦਾ ਹਰ ਕਦਮ — ਕਵੇਰੀ ਨੂੰ ਐਮਬੈੱਡ ਕਰਨਾ, ਵੈਕਟਰ ਸਟੋਰ ਖੋਜਣਾ, ਸੰਦਰਭ ਇਕੱਠਾ ਕਰਨਾ, ਅਤੇ ਜਵਾਬ ਬਣਾਉਣਾ — ਸਪੱਸ਼ਟ ਤੌਰ 'ਤੇ [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ਵਿੱਚ ਲਿਖਿਆ ਗਿਆ ਹੈ। ਇਹ ਜਾਣ-ਪਹਿਚਾਣ ਵਾਲਾ ਕੰਮ ਹੈ: ਇੱਕ ਸਿੱਖਣ ਵਾਲਾ ਸਰੋਤ ਹੋਣ ਕਰਕੇ, ਇਹ ਜ਼ਿਆਦਾ ਜਰੂਰੀ ਹੈ ਕਿ ਤੁਸੀਂ ਹਰ ਪੜਾਅ ਨੂੰ ਵੇਖੋ ਅਤੇ ਸਮਝੋ, ਨਾ ਕਿ ਕੋਡ ਘੱਟ ਕਰਨਾ। ਜਦੋਂ ਤੁਸੀਂ ਸਮਝ ਜਾਂਦੇ ਹੋ ਕਿ ਸਾਰੇ ਹਿੱਸੇ ਕਿਵੇਂ ਜੁੜਦੇ ਹਨ, ਤਾਂ ਤੁਸੀਂ ਤੇਜ਼ ਮਿਸ਼ਾਲਾਂ ਲਈ ਆਸਾਨ RAG ਜਾਂ ਪ੍ਰੋਡਕਸ਼ਨ ਸਿਸਟਮ ਲਈ ਉੱਚ ਪੱਧਰੀ RAG ਵਰਤ ਸਕਦੇ ਹੋ। +**ਇਹ ਟਿਊਟੋਰੀਅਲ ਦੇਸੀ ਤਰੀਕੇ ਨੂੰ ਵਰਤਦਾ ਹੈ।** RAG ਪਾਈਪਲਾਈਨ ਦਾ ਹਰ ਕਦਮ — ਕਵੇਰੀ ਦਾ ਐਮਬੈਡਿੰਗ, ਵੇਕਟਰ ਸਟੋਰ ਖੋਜ, ਸੰਦਰਭ ਇਕੱਤਰਕਰਨ, ਅਤੇ ਜਵਾਬ ਜਨਰੇਸ਼ਨ — ਸਪਸ਼ਟ ਤੌਰ 'ਤੇ [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ਵਿੱਚ ਲਿਖਿਆ ਗਿਆ ਹੈ। ਇਹ ਜਰੂਰੀ ਹੈ: ਸਿੱਖਣ ਵਾਲੇ ਸਰੋਤ ਵਜੋਂ, ਇਹ ਜ਼ਿਆਦਾ ਮਹੱਤਵਪੂਰਨ ਹੈ ਕਿ ਤੁਸੀਂ ਹਰ ਇੱਕ ਚਰਣ ਨੂੰ ਵੇਖੋ ਅਤੇ ਸਮਝੋ ਨਾ ਕਿ ਕੋਡ ਘੱਟ ਤੋਂ ਘੱਟ ਕੀਤਾ ਜਾਵੇ। ਜਦੋਂ ਤੁਸੀਂ ਇਹ ਜਾਣ ਲਵੋ ਕਿ ਟੁਕੜੇ ਕਿਵੇਂ ਜੁੜਦੇ ਹਨ, ਤਾੰ ਤੁਸੀਂ ਆਸਾਨ RAG ਜਾਂ ਅਡਵਾਂਸਡ RAG ਉਪਯੋਗ ਕਰ ਸਕਦੇ ਹੋ। -> **💡 ਪਹਿਲਾਂ ਹੀ ਆਸਾਨ RAG ਵੇਖਿਆ ਹੈ?** [ਤੀਜ਼ ਸ਼ੁਰੂਆਤ ਮੋਡੀਊਲ](../00-quick-start/README.md) ਵਿੱਚ ਇੱਕ ਦਸਤਾਵੇਜ਼ Q&A ਉਦਾਹਰਨ ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) ਹੈ ਜੋ ਆਸਾਨ RAG ਪਹੁੰਚ ਵਰਤਦਾ ਹੈ — LangChain4j ਆਪਣੇ ਆਪ ਐਮਬੈੱਡਿੰਗ, ਖੋਜ, ਅਤੇ ਪ੍ਰਾਂਪਟ ਇਕੱਠਾ ਕਰਦਾ ਹੈ। ਇਹ ਮੋਡੀਊਲ ਉਸ ਪਾਈਪਲਾਈਨ ਨੂੰ ਖੋਲ੍ਹ ਕੇ ਦਿਖਾਉਂਦਾ ਹੈ ਤਾਂ ਜੋ ਤੁਸੀਂ ਹਰ ਪੜਾਅ ਨੂੰ ਦੇਖ ਸਕੋ ਅਤੇ ਕਾਬੂ ਕਰ ਸਕੋ। +> **💡 ਆਸਾਨ RAG ਬਾਰੇ ਜਿਵੇਂ ਜਾਣਨਾ ਚਾਹੁੰਦੇ ਹੋ?** LangChain4j ਵਿੱਚ ਇੱਕ *ਆਸਾਨ RAG* ਤਰੀਕਾ ਵੀ ਹੈ ਜਿੱਥੇ `AiServices` ਅਤੇ `ContentRetriever` ਆਪਣੇ ਆਪ ਐਮਬੈਡਿੰਗ, ਖੋਜ, ਅਤੇ ਪ੍ਰਾਂਪਟ ਤਿਆਰ ਕਰਦੇ ਹਨ। ਇਹ ਮੌਡੀਊਲ ਇਸ ਤੋਂ ਵੱਖਰਾ ਹੈ — ਹਰ ਚਰਣ ਨੂੰ ਖੋਲ੍ਹ ਕੇ ਤੁਹਾਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ ਅਤੇ ਕਾਬੂ ਦੇਣ ਲਈ। -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਉਸ ਆਸਾਨ RAG ਪਾਈਪਲਾਈਨ ਨੂੰ ਦਿਖਾਉਂਦਾ ਜੋ ਤੇਜ਼ ਸ਼ੁਰੂਆਤ ਦੇ ਉਦਾਹਰਨ ਵਿਚ ਵਰਤਿਆ ਗਿਆ ਸੀ। ਧਿਆਨ ਦਿਓ ਕਿ `AiServices` ਅਤੇ `EmbeddingStoreContentRetriever` ਸਾਰੀ ਜਟਿਲਤਾ ਲੁਕਾਉਂਦੇ ਹਨ — ਤੁਸੀਂ ਦਸਤਾਵੇਜ਼ ਲੋਡ ਕਰਦੇ ਹੋ, ਰਿਟਰੀਵਰ ਲਗਾਉਂਦੇ ਹੋ, ਅਤੇ ਜਵਾਬ ਪ੍ਰਾਪਤ ਕਰਦੇ ਹੋ। ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ ਘਰੇਲੂ ਪਹੁੰਚ ਉਹਨਾਂ ਲੁਕੇ ਹੋਏ ਕਦਮਾਂ ਨੂੰ ਖੋਲ੍ਹਦਾ ਹੈ: +ਹੇਠਾਂ Easy RAG ਦੀ ਪਾਈਪਲਾਈਨ ਦਿਖਾਈ ਗਈ ਹੈ। ਧਿਆਨ ਦਿਓ ਕਿ `AiServices` ਅਤੇ `EmbeddingStoreContentRetriever` ਸਾਰੀ ਜਟਿਲਤਾ ਲੁਕਾਉਂਦੇ ਹਨ — ਤੁਸੀਂ ਦਸਤਾਵੇਜ਼ ਲੋਡ ਕਰਦੇ ਹੋ, ਇੱਕ ਰਿਟਰੀਵਰ ਜੋੜਦੇ ਹੋ, ਅਤੇ ਜਵਾਬ ਪ੍ਰਾਪਤ ਕਰਦੇ ਹੋ। ਇਸ ਮੌਡੀਊਲ ਵਿੱਚ ਦੇਸੀ ਤਰੀਕਾ ਇਹਨਾਂ ਲੁਕੇ ਹੋਏ ਚਰਣਾਂ ਨੂੰ ਖੋਲ੍ਹਦਾ ਹੈ: -Easy RAG Pipeline - LangChain4j +LangChain4j ਦਾ ਆਸਾਨ RAG ਪਾਈਪਲਾਈਨ -*ਇਹ ਡਾਇਗ੍ਰਾਮ `SimpleReaderDemo.java` ਤੋਂ ਆਸਾਨ RAG ਪਾਈਪਲਾਈਨ ਦਿਖਾਉਂਦਾ ਹੈ। ਇਸ ਨੂੰ ਘਰੇਲੂ ਪਹੁੰਚ ਨਾਲ ਤੁਲਨਾ ਕਰੋ ਜੋ ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ ਵਰਤੀ ਜਾਂਦੀ ਹੈ: ਆਸਾਨ RAG ਐਮਬੈੱਡਿੰਗ, ਰਿਟਰੀਵਲ, ਅਤੇ ਪ੍ਰਾਂਪਟ ਇਕੱਠਾ ਕਰਨ ਨੂੰ `AiServices` ਅਤੇ `ContentRetriever` ਦੇ ਪਿੱਛੇ ਲੁਕਾ ਦਿੰਦਾ ਹੈ — ਤੁਸੀਂ ਦਸਤਾਵੇਜ਼ ਲੋਡ ਕਰਦੇ ਹੋ, ਰਿਟਰੀਵਰ ਲਗਾਉਂਦੇ ਹੋ, ਅਤੇ ਜਵਾਬ ਲੈਂਦੇ ਹੋ। ਘਰੇਲੂ ਪਹੁੰਚ ਉਹ ਪਾਈਪਲਾਈਨ ਖੋਲ੍ਹ ਕੇ ਹਰ ਕਦਮ (ਐਮਬੈੱਡ ਕਰਨ, ਖੋਜ ਕਰਨ, ਸੰਦਰਭ ਇਕੱਠਾ ਕਰਨ, ਜਨਰੇਟ ਕਰਨ) ਨੂੰ ਆਪਣੇ ਆਪ ਕਾਲ ਕਰਦਾ ਹੈ, ਤੁਹਾਨੂੰ ਪੂਰੀ ਨਜ਼ਰ ਅਤੇ ਕਾਬੂ ਦਿੰਦਾ ਹੈ।* +*ਇਹ ਡਾਇਗ੍ਰਾਮ ਆਸਾਨ RAG ਪਾਈਪਲਾਈਨ ਦਿਖਾਉਂਦਾ ਹੈ। ਤੁਲਨਾ ਇਸ ਮੌਡੀਊਲ ਵਿੱਚ ਵਰਤੇ ਗਏ ਦੇਸੀ ਤਰੀਕੇ ਨਾਲ ਕਰੋ: Easy RAG ਪ੍ਰਾਂਪਟ ਤਿਆਰ ਕਰਨ, ਖੋਜ ਅਤੇ ਐਮਬੈਡਿੰਗ ਨੂੰ ਲੁਕਾਉਂਦਾ ਹੈ, ਪਰ ਦੇਸੀ ਤਰੀਕੇ ਵਿੱਚ ਤੁਸੀਂ ਖੁਦ ਹਰ ਕਦਮ ਨੂੰ ਕਾਲ ਕਰਦੇ ਹੋ ਅਤੇ ਪੂਰਾ ਨਿ‍यੰਤਰਣ ਰੱਖਦੇ ਹੋ।* ## ਇਹ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ -ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ RAG ਪਾਈਪਲਾਈਨ ਚਾਰ ਕਦਮਾਂ ਵਿੱਚ ਵੰਡਿਆ ਗਿਆ ਹੈ ਜੋ ਹਰ ਵਾਰੀ ਉਪਭੋਗਤਾ ਸਵਾਲ ਪੁੱਛਣ ਤੇ ਇਕ-ਇਕ ਕਰਕੇ ਚੱਲਦੇ ਹਨ। ਪਹਿਲਾਂ, ਅਪਲੋਡ ਕੀਤਾ ਦਸਤਾਵੇਜ਼ **ਪਾਰਸ ਅਤੇ ਚੰਕ ਕੀਤਾ** ਜਾਂਦਾ ਹੈ ਜੋ ਸੰਭਾਲਣ ਯੋਗ ਹਿੱਸਿਆਂ ਵਿੱਚ ਵੰਡਦਾ ਹੈ। ਫਿਰ ਉਹ ਟੁਕੜੇ **ਵੈਕਟਰ ਐਮਬੈੱਡਿੰਗ** ਵਿੱਚ ਬਦਲ ਕੇ ਸਟੋਰ ਕੀਤੇ ਜਾਂਦੇ ਹਨ ਤਾਂ ਜੋ ਉਹਨਾਂ ਦੀ ਗਣਿਤੀਕ ਤੁਲਨਾ ਕੀਤੀ ਜਾ ਸਕੇ। ਜਦੋਂ ਕੋਈ ਕਵੇਰੀ ਆਉਂਦੀ ਹੈ, ਸਿਸਟਮ ਸਭ ਤੋਂ ਸੰਬੰਧਿਤ ਟੁਕੜੇ ਲੱਭਣ ਲਈ **ਸੇਮੈਂਟਿਕ ਖੋਜ** ਕਰਦਾ ਹੈ, ਅਤੇ ਆਖਰ ਵਿੱਚ ਉਹਨਾਂ ਨੂੰ ਸੰਦਰਭ ਵਜੋਂ LLM ਨੂੰ **ਜਵਾਬ ਤਿਆਰ ਕਰਨ** ਲਈ ਦੇ ਦਿੰਦਾ ਹੈ। ਹੇਠਾਂ ਦਿੱਤੇ ਅਧਿਆਇ ਵਿੱਚ ਹਰ ਕਦਮ ਦੀ ਵਿਆਖਿਆ ਹੈ, ਕੋਡ ਅਤੇ ਡਾਇਗ੍ਰਾਮ ਸਮੇਤ। ਆਓ ਪਹਿਲਾ ਕਦਮ ਵੇਖੀਏ। +ਇਸ ਮੌਡੀਊਲ ਵਿੱਚ RAG ਪਾਈਪਲਾਈਨ ਚਾਰ ਚਰਣਾਂ ਵਿੱਚ ਤੋੜੀ ਗਈ ਹੈ ਜੋ ਹਰ ਵਾਰੀ ਯੂਜ਼ਰ ਸਵਾਲ ਪੁੱਛਣ 'ਤੇ ਲਗਾਤਾਰ ਚਲਦੀਆਂ ਹਨ। ਪਹਿਲਾਂ, ਅਪਲੋਡ ਕੀਤਾ ਦਸਤਾਵੇਜ਼ **ਪਾਰਸ ਅਤੇ ਚੰਕ ਕੀਤਾ** ਜਾਂਦਾ ਹੈ ਜੋ ਸਹੂਲਤਯੋਗ ਹਿੱਸਿਆਂ ਵਿੱਚ ਟੁਟਦਾ ਹੈ। ਫਿਰ ਉਹ ਚੰਕ **ਵੇਕਟਰ ਐਮਬੈਡਿੰਗ** ਵਿੱਚ ਬਦਲੇ ਜਾਂਦੇ ਹਨ ਤੇ ਸਟੋਰ ਕੀਤੇ ਜਾਂਦੇ ਹਨ ਤਾਂ ਜੋ ਗਣਿਤੀ ਤੌਰ 'ਤੇ ਤੁਲਨਾ ਕੀਤੀ ਜਾ ਸਕੇ। ਜਦੋਂ ਸਵਾਲ ਆਉਂਦਾ ਹੈ, ਸਿਸਟਮ ਸਭ ਤੋਂ ਸੰਬੰਧਿਤ ਚੰਕਾਂ ਨੂੰ ਲੱਭਣ ਲਈ **ਸਮਾਂਤਰੀ ਖੋਜ** ਕਰਦਾ ਹੈ ਅਤੇ ਆਖਿਰ ਨੂੰ ਉਨ੍ਹਾਂ ਨੂੰ ਸੰਦਰਭ ਵਜੋਂ LLM ਨੂੰ ਦੇ ਕੇ **ਜਵਾਬ ਜਨਰੇਟ** ਕਰਵਾਉਂਦਾ ਹੈ। ਹੇਠਾਂ ਹਰ ਚਰਣ ਨਾਲ ਜੁੜੇ ਕੋਡ ਅਤੇ ਡਾਇਗ੍ਰਾਮ ਦਿੱਤੇ ਗਏ ਹਨ। ਪਹਿਲੇ ਕਦਮ ਨੂੰ ਦੇਖੋ। -### ਦਸਤਾਵੇਜ਼ ਪ੍ਰਕਿਰਿਆ +### ਦਸਤਾਵੇਜ਼ ਪ੍ਰੋਸੈਸਿੰਗ [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -ਜਦੋਂ ਤੁਸੀਂ ਦਸਤਾਵੇਜ਼ ਅਪਲੋਡ ਕਰਦੇ ਹੋ, ਸਿਸਟਮ ਇਸਨੂੰ ਪਾਰਸ ਕਰਦਾ ਹੈ (PDF ਜਾਂ ਸਧਾਰਣ ਟੈਕਸਟ), ਫਾਇਲ ਨਾਂ ਵਰਗਾ ਮੈਟਾਡੇਟਾ ਜੋੜਦਾ ਹੈ, ਅਤੇ ਫਿਰ ਇਸਨੂੰ ਛੋਟੇ-ਛੋਟੇ ਟੁਕੜਿਆਂ ਵਿੱਚ ਵੰਡਦਾ ਹੈ — ਉਹ ਟੁਕੜੇ ਮਾਡਲ ਦੀ ਸੰਦਰਭ ਵਿੰਡੋ ਵਿੱਚ ਆਰਾਮਦਾਇਕ ਬੈਠਦੇ ਹਨ। ਇਹ ਟੁਕੜੇ ਹਲਕੇ ਨਾਲ ਆਪਸੀ ਓਵਰਲੈਪ ਕਰਦੇ ਹਨ ਤਾਂ ਜੋ ਸੰਦਰਭ ਬਾਊਂਡਰੀ ਤੇ ਨਾ ਗੁੰਮ ਹੋਵੇ। +ਜਦੋਂ ਤੁਸੀਂ ਦਸਤਾਵੇਜ਼ ਅਪਲੋਡ ਕਰਦੇ ਹੋ, ਸਿਸਟਮ ਇਸਨੂੰ (PDF ਜਾਂ ਸਾਫ਼ ਟੈਕਸਟ) ਪਾਰਸ ਕਰਦਾ ਹੈ, ਫਾਈਲ ਨਾਮ ਵਰਗੀ ਮੈਟਾਡੇਟਾ ਜੋੜਦਾ ਹੈ ਅਤੇ ਫਿਰ ਇਸ ਨੂੰ ਚੰਕਾਂ ਵਿੱਚ ਤੋੜਦਾ ਹੈ — ਛੋਟੇ-ਛੋਟੇ ਹਿੱਸੇ ਜੋ ਮਾਡਲ ਦੇ ਸੰਦਰਭ ਵਿੰਡੋ ਵਿੱਚ ਆਸਾਨੀ ਨਾਲ ਆ ਜਾਂਦੇ ਹਨ। ਇਹ ਚੰਕ ਹਲਕੇ-ফुल्कੇ ਢੰਗ ਨਾਲ ਇੱਕ-ਦੂਜੇ ਨਾਲ ਓਵਰਲੈਪ ਕਰਦੇ ਹਨ ਤਾਂ ਕਿ ਬਾਰਡਰ ਤੇ ਕੋਈ ਸੰਦਰਭ ਨਾ ਗੁੰਮ ਹੋਵੇ। ```java -// ਅਪਲੋਡ ਕੀਤੀ ਫਾਇਲ ਨੂੰ ਪਾਰਸ ਕਰੋ ਅਤੇ ਇਸ ਨੂੰ ਇਕ LangChain4j ਡੌਕਯੂਮੈਂਟ ਵਿੱਚ ਲਪੇਟੋ +// ਅਪਲੋਡ ਕੀਤੀ ਫਾਈਲ ਨੂੰ ਪਾਰਸ ਕਰੋ ਅਤੇ ਇਸਨੂੰ LangChain4j ਡੌਕਯੂਮੈਂਟ ਵਿੱਚ ਲਪੇਟੋ Document document = Document.from(content, metadata); -// 300-ਟੋਕਨ ਹਿੱਸਿਆਂ ਵਿੱਚ ਵੰਡੋ ਜਿਸ ਵਿੱਚ 30-ਟੋਕਨ ਦਾ ਓਵਰਲੈਪ ਹੋਵੇ +// 300-ਟੋਕਨ ਵਾਲੇ ਹਿੱਸਿਆਂ ਵਿੱਚ ਵੰਡੋ ਜਿਨ੍ਹਾਂ ਵਿੱਚ 30-ਟੋਕਨ ਦਾ ਅਤਰਿਕਤ ਸਾਂਝਾ ਹੋਵੇ DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਇਹ ਵਿਜ਼ੂਅਲ ਤੌਰ ਤੇ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਜਿਵੇਂ ਹਰ ਟੁਕੜਾ ਆਪਣੇ ਗੁਆਂਢੀਆਂ ਨਾਲ ਕੁਝ ਟੋਕਨ ਸਾਂਝੇ ਕਰਦਾ ਹੈ - 30-ਟੋਕਨ ਓਵਰਲੈਪ ਇਹ ਯਕੀਨੀ ਬਣਾਉਂਦਾ ਹੈ ਕਿ ਕੋਈ ਮਹੱਤਵਪੂਰਕ ਸੰਦਰਭ ਦਰਾਰ ਵਿੱਚ ਨਾ ਜਾਵੇ: -Document Chunking +ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਇਹ ਕਿਵੇਂ दृਸ਼ਮਾਨ ਹੁੰਦਾ ਹੈ। ਹਰ ਚੰਕ ਕੁਝ ਟੋਕਨ ਆਪਣੇ ਗੁਆਂਢੀਆਂ ਨਾਲ ਸਾਂਝੇ ਕਰਦਾ ਹੈ — 30-ਟੋਕਨ ਓਵਰਲੈਪ ਇਹ ਯਕੀਨੀ ਬਣਾਉਂਦਾ ਹੈ ਕਿ ਕੋਈ ਮਹੱਤਵਪੂਰਨ ਸੰਦਰਭ ਚੂਕਦਾ ਨਹੀਂ: + +ਦਸਤਾਵੇਜ਼ ਚੰਕਿੰਗ -*ਇਹ ਡਾਇਗ੍ਰਾਮ ਇੱਕ ਦਸਤਾਵੇਜ਼ ਨੂੰ 300-ਟੋਕਨ ਚੰਕਾਂ ਵਿੱਚ ਵੰਡਦਾ ਹੈ ਜਿਸ ਵਿੱਚ 30-ਟੋਕਨ ਓਵਰਲੈਪ ਹੁੰਦਾ ਹੈ, ਚੰਕ ਬਾਊਂਡਰੀ ਦੇ ਨੇੜੇ ਸੰਦਰਭ ਨੂੰ ਸੁਰੱਖਿਅਤ ਕਰਦਾ ਹੈ।* +*ਇਹ ਡਾਇਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਇਕ ਦਸਤਾਵੇਜ਼ ਨੂੰ 300-ਟੋਕਨ ਚੰਕਾਂ ਵਿੱਚ ਤੋੜਿਆ ਜਾਂਦਾ ਹੈ ਜਿਸ ਵਿੱਚ 30-ਟੋਕਨ ਓਵਰਲੈਪ ਹੁੰਦਾ ਹੈ, ਚੰਕ ਸੂਤਰਾਂ ਤੇ ਸੰਦੇਸ਼ ਨੂੰ ਬਚਾਉਂਦਾ ਹੈ।* > **🤖 [GitHub Copilot](https://github.com/features/copilot) ਚੈਟ ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "LangChain4j ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਕਿਵੇਂ ਚੰਕ ਕਰਦਾ ਹੈ ਅਤੇ ਓਵਰਲੈਪ ਕਿਉਂ ਮਹੱਤਵਪੂਰਕ ਹੈ?" -> - "ਵੱਖ-ਵੱਖ ਦਸਤਾਵੇਜ਼ ਕਿਸਮਾਂ ਲਈ ਸਭ ਤੋਂ ਵਧੀਆ ਚੰਕ ਸਾਈਜ਼ ਕੀ ਹੈ ਅਤੇ ਕਿਉਂ?" -> - "ਮੈਂ ਕਈ ਭਾਸ਼ਾਵਾਂ ਜਾਂ ਖਾਸ ਫਾਰਮੈਟਿੰਗ ਵਾਲੇ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਕਿਵੇਂ ਸੰਭਾਲਾਂ?" +> - "LangChain4j ਕਿਵੇਂ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਚੰਕਾਂ ਵਿੱਚ ਤੋੜਦਾ ਹੈ ਅਤੇ ਓਵਰਲੈਪ ਕਿਉਂ ਮਹੱਤਵਪੂਰਨ ਹੈ?" +> - "ਵੱਖ-ਵੱਖ ਦਸਤਾਵੇਜ਼ ਕਿਸਮਾਂ ਲਈ ਸਭ ਤੋਂ ਵਧੀਆ ਚੰਕ ਆਕਾਰ ਕਿਹੜਾ ਹੈ ਅਤੇ ਕਿਉਂ?" +> - "ਮੈਂ ਕਿਵੇਂ ਕਈ ਬੋਲੀਆਂ ਜਾਂ ਵਿਸ਼ੇਸ਼ ਫਾਰਮੈਟ ਵਾਲੇ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਸੰਭਾਲ ਸਕਦਾ ਹਾਂ?" -### ਐਮਬੈੱਡਿੰਗ ਬਣਾਉਣਾ +### ਐਮਬੈਡਿੰਗ ਬਣਾਉਣਾ [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -ਹਰ ਚੰਕ ਨੂੰ ਇੱਕ ਗਿਣਤੀਮਾਤਰ ਪ੍ਰਤੀਨਿਧিত্ব ਵਿੱਚ ਬਦਲਿਆ ਜਾਂਦਾ ਹੈ ਜਿਸਨੂੰ ਐਮਬੈੱਡਿੰਗ ਕਹਿੰਦੇ ਹਨ — ਅਰਥਾਤ ਅਰਥ ਤੋਂ ਗਿਣਤੀ 'ਚ ਬਦਲਣ ਵਾਲਾ। ਐਮਬੈੱਡਿੰਗ ਮਾਡਲ "ਸਮਝਦਾਰ" (ਚੈਟ ਮਾਡਲ ਵਰਗਾ) ਨਹੀਂ ਹੁੰਦਾ; ਇਹ ਹਦਾਇਤਾਂ ਦਾ ਪਾਲਣ ਨਹੀਂ ਕਰਦਾ, ਸੂਝ-ਬੂਝ ਨਹੀਂ ਕਰਦਾ, ਨਾ ਸਵਾਲਾਂ ਦੇ ਜਵਾਬ ਦਿੰਦਾ ਹੈ। ਇਹ ਸਿਰਫ ਲਿਖਤ ਨੂੰ ਇੱਕ ਗਣਿਤੀਈ ਸਪੇਸ ਵਿੱਚ ਨਕਸ਼ਾ ਬਣਾਉਂਦਾ ਹੈ ਜਿੱਥੇ ਮਿਲਦੇ-ਜੁਲਦੇ ਅਰਥ ਨੇੜੇ-ਨੇੜੇ ਪੈਂਦੇ ਹਨ — "ਕਾਰ" "ਆਟੋਮੋਬਾਈਲ" ਕੋਲ, "ਵਾਪਸੀ ਨੀਤੀ" "ਮੇਰੇ ਪੈਸੇ ਵਾਪਸ" ਕੋਲ। ਟਿੱਪਣੀ ਮਾਡਲ ਇੱਕ ਬੰਦੇ ਵਾਂਗ ਹੈ ਜਿਸ ਨਾਲ ਤੁਸੀਂ ਗੱਲਬਾਤ ਕਰ ਸਕਦੇ ਹੋ; ਐਮਬੈੱਡਿੰਗ ਮਾਡਲ ਵਧੀਆ ਫਾਇਲਿੰਗ ਸਿਸਟਮ ਹੈ। +ਹਰ ਚੰਕ ਨੂੰ ਸੰਖਿਆਤਮਕ ਪ੍ਰਤੀਨਿਧੀਤਾ ਵਿੱਚ ਬਦਲਿਆ ਜਾਂਦਾ ਹੈ ਜਿਸ ਨੂੰ ਐਮਬੈਡਿੰਗ ਕਹਿੰਦੇ ਹਨ — ਅਰਥਾਤ ਇੱਕ ਅਰਥ ਤੋਂ ਸੰਖਿਆਵਾਂ ਵਿੱਚ ਬਦਲਨ ਵਾਲਾ ਸਿਸਟਮ। ਐਮਬੈਡਿੰਗ ਮਾਡਲ "ਚੈਟ ਮਾਡਲ" ਵਾਂਗ "ਸਮਝਦਾਰ" ਨਹੀਂ ਹੁੰਦਾ; ਇਹ ਹੁਕਮਾਂ ਦੀ ਪਾਲਣਾ, ਤਰਕ, ਜਾਂ ਸਵਾਲਾਂ ਦੇ ਜਵਾਬ ਨਹੀਂ ਦੇ ਸਕਦਾ। ਇਸਨੂੰ ਜੋ ਕੁਝ ਆਉਂਦਾ ਹੈ ਉਹ ਟੈਕਸਟ ਨੂੰ ਗਣਿਤੀ ਜਗ੍ਹਾ ਵਿੱਚ ਅਜਿਹਾ ਮੈਪ ਕਰਨਾ ਹੁੰਦਾ ਹੈ, ਜਿੱਥੇ ਸਮਾਨ ਅਰਥ ਦਰਦਰ ਪਾਸੇ ਆ ਜਾਂਦੇ ਹਨ — "ਗੱਡੀ" ਅਤੇ "ਕਾਰ", "ਰਿਫੰਡ ਪॉलਿਸੀ" ਅਤੇ "ਮੇਰੇ ਪੈਸੇ ਵਾਪਸ"। ਚੈਟ ਮਾਡਲ ਨੂੰ ਇੱਕ ਬੰਦੇ ਵਾਂਗ ਸੋਚੋ ਜਿਸ ਨਾਲ ਤੁਸੀਂ ਗੱਲ ਕਰਦੇ ਹੋ; ਐਮਬੈਡਿੰਗ ਮਾਡਲ ਵਧੀਆ ਫਾਈਲਿੰਗ ਸਿਸਟਮ ਹੈ। -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਇਹ ਧਾਰਨਾ ਵਿਜ਼ੂਅਲਾਈਜ਼ ਕਰਦਾ ਹੈ — ਟੈਕਸਟ ਇੱਜ਼ਤ ਕੀਤਾ ਜਾਂਦਾ ਹੈ, ਗਿਣਤੀਮਾਤਰ ਵੈਕਟਰ ਵੱਢੇ ਜਾਂਦੇ ਹਨ, ਅਤੇ ਵਧਦੇ ਅਰਥ ਨੇੜਲੇ ਵੈਕਟਰ ਬਣਾਉਂਦੇ ਹਨ: +ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਇਸ ਧਾਰਨਾ ਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ — ਟੈਕਸਟ ਦਾਖਲ ਹੁੰਦਾ ਹੈ, ਸੰਖਿਆਤਮਕ ਵੇਕਟਰ ਨਿਕਲਦੇ ਹਨ, ਅਤੇ ਸਮਾਨ ਅਰਥ ਨੇੜਲੇ ਵੇਕਟਰ ਉਤਪੰਨ ਕਰਦੇ ਹਨ: -Embedding Model Concept +ਐਮਬੈਡਿੰਗ ਮਾਡਲ ਦੀ ਧਾਰਨਾ -*ਇਹ ਡਾਇਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਇੱਕ ਐਮਬੈੱਡਿੰਗ ਮਾਡਲ ਕਿਵੇਂ ਟੈਕਸਟ ਨੂੰ ਗਿਣਤੀਮਾਤਰ ਵੈਕਟਰਾਂ ਵਿੱਚ ਬਦਲਦਾ ਹੈ, ਜਿੱਥੇ ਮਿਲਦੇ-ਜੁਲਦੇ ਅਰਥ — ਜਿਵੇਂ "ਕਾਰ" ਅਤੇ "ਆਟੋਮੋਬਾਈਲ" — ਨੇੜਲੇ ਰਹਿੰਦੇ ਹਨ।* +*ਇਹ ਡਾਇਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਐਮਬੈਡਿੰਗ ਮਾਡਲ ਟੈਕਸਟ ਨੂੰ ਸੰਖਿਆਤਮਕ ਵੇਕਟਰਾਂ ਵਿੱਚ ਬਦਲਦਾ ਹੈ, ਸਮਾਨ ਅਰਥਾਂ — ਜਿਵੇਂ "ਕਾਰ" ਅਤੇ "ਗੱਡੀ" — ਨੂੰ ਵੇਕਟਰ ਸਪੇਸ ਵਿੱਚ ਨੇੜੇ ਲਿਆਉਂਦਾ ਹੈ।* ```java @Bean @@ -154,29 +153,31 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -ਹੇਠਾਂ ਦਿੱਤੇ ਕਲਾਸ ਡਾਇਗ੍ਰਾਮ ਵਿੱਚ RAG ਪਾਈਪਲਾਈਨ ਦੇ ਦੋ ਵੱਖਰੇ ਪ੍ਰਵਾਹਾਂ ਅਤੇ LangChain4j ਕਲਾਸਾਂ ਨੂੰ ਦਿਖਾਇਆ ਗਿਆ ਹੈ ਜੋ ਉਹਨਾਂ ਨੂੰ ਲਾਗੂ ਕਰਦੀਆਂ ਹਨ। **ਇੰਗੈਸ਼ਨ ਪ੍ਰਵਾਹ** (ਅਪਲੋਡ ਵੇਲੇ ਇੱਕ ਵਾਰੀ ਚੱਲਦਾ ਹੈ) ਦਸਤਾਵੇਜ਼ ਨੂੰ ਵੰਡਦਾ ਹੈ, ਚੰਕਾਂ ਨੂੰ ਐਮਬੈੱਡ ਕਰਦਾ ਹੈ ਅਤੇ `.addAll()` ਰਾਹੀਂ ਸਟੋਰ ਕਰਦਾ ਹੈ। **ਕਵੇਰੀ ਪ੍ਰਵਾਹ** (ਹਰ ਵਾਰੀ ਉਪਭੋਗਤਾ ਪੁੱਛਦਾ ਹੈ) ਸਵਾਲ ਨੂੰ ਐਮਬੈੱਡ ਕਰਦਾ ਹੈ, `.search()` ਰਾਹੀਂ ਸਟੋਰ ਵਿੱਚ ਖੋਜ ਕਰਦਾ ਹੈ, ਅਤੇ ਮਿਲਦੇ ਸੰਦਰਭ ਨੂੰ ਚੈਟ ਮਾਡਲ ਨੂੰ ਪਾਸ ਕਰਦਾ ਹੈ। ਦੋਹਾਂ ਪ੍ਰਵਾਹਾਂ ਦਾ ਮਿਲਣ ਬਿੰਦੂ ਸਾਂਝਾ `EmbeddingStore` ਇੰਟਰਫੇਸ ਹੈ: +ਹੇਠਾਂ ਕਲਾਸ ਡਾਇਗ੍ਰਾਮ RAG ਪਾਈਪਲਾਈਨ ਦੇ ਦੋ ਵੱਖਰੇ ਪ੍ਰਵਾਹ ਅਤੇ LangChain4j ਕਲਾਸਾਂ ਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ ਜੋ ਉਹ ਲਾਗੂ ਕਰਦੀਆਂ ਹਨ। +**ਇੰਜੈਸ਼ਨ ਫਲੋ** (ਅਪਲੋਡ ਸਮੇਂ ਇੱਕ ਵਾਰੀ ਚੱਲਦਾ ਹੈ) ਦਸਤਾਵੇਜ਼ ਨੂੰ ਤੋੜਦਾ ਹੈ, ਚੰਕਾਂ ਦੀ ਐਮਬੈਡਿੰਗ ਕਰਦਾ ਹੈ, ਅਤੇ ਉਨ੍ਹਾਂ ਨੂੰ `.addAll()` ਰਾਹੀਂ ਸਟੋਰ ਕਰਦਾ ਹੈ। +**ਕਵੇਰੀ ਫਲੋ** (ਹਰ ਵਾਰੀ ਯੂਜ਼ਰ ਪੁੱਛਣ 'ਤੇ ਚੱਲਦਾ ਹੈ) ਸਵਾਲ ਦੀ ਐਮਬੈਡਿੰਗ ਕਰਦਾ ਹੈ, `.search()` ਰਾਹੀਂ ਸਟੋਰ ਖੋਜਦਾ ਹੈ, ਅਤੇ ਮਿਲੇ ਹੋਏ ਸੰਦਰਭ ਨੂੰ ਚੈਟ ਮਾਡਲ ਨੂੰ ਪਾਸ ਕਰਦਾ ਹੈ। ਦੋਹਾਂ ਫਲੋਜ਼ ਇੱਕ ਸਾਂਝੇ `EmbeddingStore` ਇੰਟਰਫੇਸ 'ਤੇ ਮਿਲਦੀਆਂ ਹਨ: -LangChain4j RAG Classes +LangChain4j RAG ਕਲਾਸਾਂ -*ਇਹ ਡਾਇਗ੍ਰਾਮ RAG ਪਾਈਪਲਾਈਨ ਦੇ ਦੋ ਪ੍ਰਵਾਹ — ਇੰਗੈਸ਼ਨ ਅਤੇ ਕਵੇਰੀ — ਅਤੇ ਉਹਨਾਂ ਦੇ ਮਿਲਣ ਬਿੰਦੂ EmbeddingStore ਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ।* +*ਇਹ ਡਾਇਗ੍ਰਾਮ RAG ਪਾਈਪਲਾਈਨ ਦੇ ਦੋ ਫਲੋਜ਼ — ਇੰਜੈਸ਼ਨ ਅਤੇ ਕਵੇਰੀ — ਅਤੇ ਉਹ ਕਿਵੇਂ ਸਾਂਝੇ EmbeddingStore ਰਾਹੀਂ ਜੁੜਦੇ ਹਨ, ਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ।* -ਜਦੋਂ ਐਮਬੈੱਡਿੰਗ ਸਟੋਰ ਕੀਤੇ ਜਾਂਦੇ ਹਨ, ਤਾਂ ਮਿਲਦੇ ਸੰਦਰਭ ਆਟੋਮੈਟਿਕ ਤੌਰ 'ਤੇ ਵੈਕਟਰ ਸਪੇਸ ਵਿੱਚ ਇਕੱਠੇ ਹੋ ਜਾਂਦੇ ਹਨ। ਹੇਠਾਂ ਦਿੱਤੀ ਵਿਜ਼ੂਅਲਾਈਜ਼ੇਸ਼ਨ ਦਿਖਾਉਂਦੀ ਹੈ ਕਿ ਵੱਖ-ਵੱਖ ਵਿਸ਼ਿਆਂ ਦੇ ਦਸਤਾਵੇਜ਼ ਨੇੜਲੇ ਬਿੰਦੂਆਂ ਵਾਂਗ ਬਣਦੇ ਹਨ, ਜੋ ਸੇਮੈਂਟਿਕ ਖੋਜ ਨੂੰ ਸੰਭਵ ਬਣਾਉਂਦਾ ਹੈ: +ਇੱਕ ਵਾਰੀ ਐਮਬੈਡਿੰਗ ਸਟੋਰ ਹੋ ਜਾਣ ਤੇ, ਸਮਾਨ ਸਮੱਗਰੀ ਨੈਚਰਲ ਤੌਰ ਤੇ ਵੇਕਟਰ ਸਪੇਸ ਵਿੱਚ ਇਹ ਵਿੱਚ ਗੁੱਛੇ ਬਣਦੀ ਹੈ। ਹੇਠਾਂ ਦਿੱਤੀ ਵਿਜ਼ੁਅਲਾਈਜ਼ੇਸ਼ਨ ਵੇਖਾਉਂਦੀ ਹੈ ਕਿ ਜੁੜੇ ਹੋਏ ਵਿਸ਼ੇ ਲਈ ਦਸਤਾਵੇਜ਼ ਨੇੜਲੇ ਬਿੰਦੂਆਂ ਵਾਂਗੋਂ ਕਿਵੇਂ ਹੁੰਦੇ ਹਨ, ਜੋ ਸਮਾਂਤਰੀ ਖੋਜ ਨੂੰ ਸੰਭਵ ਬਣਾਉਂਦਾ ਹੈ: -Vector Embeddings Space +ਵੇਕਟਰ ਐਮਬੈਡਿੰਗ ਸਪੇਸ -*ਇਹ ਵਿਜ਼ੂਅਲੀਜ਼ੇਸ਼ਨ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਸੰਬੰਧਿਤ ਦਸਤਾਵੇਜ਼ 3D ਵੈਕਟਰ ਸਪੇਸ ਵਿੱਚ ਇੱਕੱਠੇ ਕਿਵੇਂ ਕਲੱਸਟਰ ਕਰਦੇ ਹਨ, ਅਤੇ ਤਕਨੀਕੀ ਡੌਕਸ, ਵਪਾਰ ਨਿਯਮ, ਅਤੇ FAQ ਵਾਂਗ ਵਿਸ਼ਿਆਂ ਦੇ ਵੱਖਰੇ ਗਰੁੱਪ ਬਣਦੇ ਹਨ।* +*ਇਹ ਵਿਜ਼ੁਅਲਾਈਜ਼ੇਸ਼ਨ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਜੁੜੇ ਹੋਏ ਦਸਤਾਵੇਜ਼ 3D ਵੇਕਟਰ ਸਪੇਸ ਵਿੱਚ ਕਿਵੇਂ ਗੁੱਛੇ ਬਣਾਉਂਦੇ ਹਨ, ਜਿਸ ਵਿੱਚ ਟੈਕਨੀਕਲ ਦਸਤਾਵੇਜ਼, ਕਾਰੋਬਾਰੀ ਨਿਯਮ, ਅਤੇ ਪ੍ਰਚਲਿਤ ਸਵਾਲ ਵੱਖਰਾ ਸਮੂਹ ਬਣਾਉਂਦੇ ਹਨ।* -ਜਦੋਂ ਉਪਭੋਗਤਾ ਖੋਜ ਕਰਦਾ ਹੈ, ਸਿਸਟਮ ਚਾਰ ਕਦਮ ਲੈਂਦਾ ਹੈ: ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਇੱਕ ਵਾਰੀ ਐਮਬੈੱਡ ਕਰਨਾ, ਹਰ ਖੋਜ ਤੇ ਕਵੇਰੀ ਨੂੰ ਐਮਬੈੱਡ ਕਰਨਾ, ਸਾਰੇ ਸਟੋਰ ਕੀਤੇ ਵੈਕਟਰਾਂ ਨਾਲ ਕਵੇਰੀ ਵੈਕਟਰ ਦੀ ਕੋਸਾਈਨ ਸਮਾਨਤਾ ਨਾਲ ਤੁਲਨਾ ਕਰਨਾ, ਅਤੇ ਸਭ ਤੋਂ ਉੱਚੇ ਸਕੋਰ ਵਾਲੇ ਕ-ਟੁਕੜੇ ਵਾਪਸ ਕਰਨਾ। ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਹਰ ਕਦਮ ਅਤੇ ਜੁੜੀਆਂ LangChain4j ਕਲਾਸਾਂ ਨੂੰ ਵਿਸਥਾਰ ਨਾਲ ਦਿਖਾਉਂਦਾ ਹੈ: +ਜਦੋਂ ਯੂਜ਼ਰ ਖੋਜ ਕਰਦਾ ਹੈ, ਸਿਸਟਮ ਚਾਰ ਕਦਮ ਸਮਝਦਾ ਹੈ: ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਇੱਕ ਵਾਰੀ ਐਮਬੈਡ ਕਰਨਾ, ਹਰ ਖੋਜ ਤੇ ਕਵੇਰੀ ਦੀ ਐਮਬੈਡਿੰਗ ਕਰਨਾ, ਕਵੇਰੀ ਵੇਕਟਰ ਨੂੰ ਸਭ ਸਟੋਰ ਕੀਤੇ ਵੇਕਟਰਾਂ ਨਾਲ ਕੋਸਾਈਨ ਸਮਾਨਤਾ ਨਾਲ ਤੁਲਨਾ ਕਰਨਾ, ਅਤੇ ਸਰਵੋਚ K ਉੱਚ ਸਕੋਰ ਵਾਲੇ ਚੰਕਾਂ ਨੂੰ ਵਾਪਸ ਕਰਨਾ। ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਹਰ ਕਦਮ ਅਤੇ LangChain4j ਕਲਾਸਾਂ ਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ: -Embedding Search Steps +ਐਮਬੈਡਿੰਗ ਖੋਜ ਚਰਣ -*ਇਹ ਡਾਇਗ੍ਰਾਮ ਚਾਰ ਕਦਮਾਂ ਵਾਲੀ ਐਮਬੈੱਡਿੰਗ ਖੋਜ ਪ੍ਰਕਿਰਿਆ ਦਿਖਾਉਂਦਾ ਹੈ: ਦਸਤਾਵੇਜ਼ ਐਮਬੈੱਡ ਕਰੋ, ਕਵੇਰੀ ਐਮਬੈੱਡ ਕਰੋ, ਵੈਕਟਰਾਂ ਦੀ ਕੋਸਾਈਨ ਸਮਾਨਤਾ ਨਾਲ ਤੁਲਨਾ ਕਰੋ, ਅਤੇ ਊਪਰੀ K ਨਤੀਜਿਆਂ ਨੂੰ ਵਾਪਸ ਕਰੋ।* +*ਇਹ ਡਾਇਗ੍ਰਾਮ ਚਾਰ ਕਦਮਾਂ ਵਾਲੀ ਐਮਬੈਡਿੰਗ ਖੋਜ ਪ੍ਰਕਿਰਿਆ ਦਿਖਾਉਂਦਾ ਹੈ: ਦਸਤਾਵੇਜ਼ ਐਮਬੈਡ ਕਰੋ, ਕਵੇਰੀ ਐਮਬੈਡ ਕਰੋ, ਕੋਸਾਈਨ ਸਮਾਨਤਾ ਨਾਲ ਵੇਕਟਰ ਤੁਲਨਾ ਕਰੋ, ਅਤੇ ਸਿਖਰ-ਕੇ ਨਤੀਜੇ ਵਾਪਸ ਕਰੋ।* -### ਸੇਮੈਂਟਿਕ ਖੋਜ +### ਸਮਾਂਤਰੀ ਖੋਜ [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -ਜਦੋਂ ਤੁਸੀਂ ਸਵਾਲ ਪੁੱਛਦੇ ਹੋ, ਤੁਹਾਡਾ ਸਵਾਲ ਵੀ ਐਮਬੈੱਡਿੰਗ ਵਿੱਚ ਬਦਲ ਜਾਂਦਾ ਹੈ। ਸਿਸਟਮ ਤੁਹਾਡੇ ਸਵਾਲ ਦੀ ਐਮਬੈੱਡਿੰਗ ਨੂੰ ਸਾਰੇ ਦਸਤਾਵੇਜ਼ ਚੰਕਾਂ ਦੀਆਂ ਐਮਬੈੱਡਿੰਗ ਨਾਲ ਤੁਲਨਾ ਕਰਦਾ ਹੈ। ਇਹ ਚੰਕ ਲੱਭਦਾ ਹੈ ਜਿੰਨ੍ਹਾਂ ਦੇ ਅਰਥ ਸਭ ਤੋਂ ਵੱਧ ਮਿਲਦੇ ਹਨ - ਸਿਰਫ਼ ਕੀਵਰਡ ਮੇਲ ਰਾਖਣ ਜਾਂ ਇੱਕੋ ਸ਼ਬਦਾਂ ਤੇ ਅਧਾਰਿਤ ਨਹੀਂ, ਪਰ ਅਸਲ ਸੇਮੈਂਟਿਕ ਸਮਾਨਤਾ ਨਾਲ। +ਜਦੋਂ ਤੁਸੀਂ ਸਵਾਲ ਪੁੱਛਦੇ ਹੋ, ਤੁਹਾਡਾ ਸਵਾਲ ਵੀ ਐਮਬੈਡਿੰਗ ਬਣ ਜਾਂਦਾ ਹੈ। ਸਿਸਟਮ ਤੁਹਾਡੇ ਸਵਾਲ ਦੀ ਐਮਬੈਡਿੰਗ ਨੂੰ ਸਾਰੇ ਦਸਤਾਵੇਜ਼ ਚੰਕ ਦੀ ਐਮਬੈਡਿੰਗ ਨਾਲ ਤੁਲਨਾ ਕਰਦਾ ਹੈ। ਇਹ ਉਹ ਚੰਕ ਲੱਭਦਾ ਹੈ ਜੋ ਸਭ ਤੋਂ ਵਧੀਆ ਸਮਾਨ ਅਰਥ ਰੱਖਦੇ ਹਨ - ਸਿਰਫ ਕੀਵਰਡ ਮਿਲਾਉਣ ਨਾਹੀ, ਪਰ ਅਸਲ ਸਮਾਂਤਰੀ ਸਮਾਨਤਾ। ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +197,27 @@ for (EmbeddingMatch match : matches) { } ``` -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਸੇਮੈਂਟਿਕ ਖੋਜ ਨੂੰ ਰਵਾਇਤੀ ਕੀਵਰਡ ਖੋਜ ਨਾਲ ਤੁਲਨਾ ਕਰਦਾ ਹੈ। "ਵਾਹਨ" ਲਈ ਕੀਵਰਡ ਖੋਜ "ਕਾਰਾਂ ਅਤੇ ਟਰੱਕਾਂ" ਬਾਰੇ ਚੰਕ ਨਹੀਂ ਲੱਭਦੀ, ਪਰ ਸੇਮੈਂਟਿਕ ਖੋਜ ਸਮਝਦੀ ਹੈ ਕਿ ਦੋਵਾਂ ਦਾ ਅਰਥ ਇੱਕੋ ਹੈ ਅਤੇ ਇਸਨੂੰ ਉੱਚ ਸਕੋਰ ਵਾਲਾ ਮਿਲਦੇ ਜੁਲਦੇ ਕੇਸ ਵਜੋਂ ਦਿਖਾਉਂਦੀ ਹੈ: +ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਗ੍ਰਾਮ ਸਮਾਂਤਰੀ ਖੋਜ ਨੂੰ ਰਵਾਇਤੀ ਕੀਵਰਡ ਖੋਜ ਨਾਲ ਵੱਖ ਕਰਦਾ ਹੈ। "ਵਾਹਨ" ਲਈ ਕੀਵਰਡ ਖੋਜ "ਕਾਰਾਂ ਅਤੇ ਟਰੱਕਾਂ" ਬਾਰੇ ਚੰਕ ਨੂੰ ਛੱਡ ਦਿੰਦੀ ਹੈ, ਪਰ ਸਮਾਂਤਰੀ ਖੋਜ ਸਮਝਦੀ ਹੈ ਕਿ ਉਹਨਾਂ ਦੋਨਾਂ ਦੇ ਅਰਥ ਇੱਕੋ ਹਨ ਅਤੇ ਇਸਨੂੰ ਉੱਚ ਸਕੋਰ ਵਾਲਾ ਮਿਲਾਪ ਵਜੋਂ ਵਾਪਸ ਕਰਦੀ ਹੈ: -Semantic Search +ਸਮਾਂਤਰੀ ਖੋਜ -*ਇਹ ਡਾਇਗ੍ਰਾਮ ਕੀਵਰਡ-ਆਧਾਰਿਤ ਖੋਜ ਅਤੇ ਸੇਮੈਂਟਿਕ ਖੋਜ ਦੀ ਤੁਲਨਾ ਕਰਦਾ ਹੈ, ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਸੇਮੈਂਟਿਕ ਖੋਜ ਕਿਵੇਂ ਖ਼ਾਸ ਸ਼ਬਦਾਂ ਤੋਂ ਬਿਨਾਂ ਸੰਕਲਪਕ ਮੁਆਫਿਖ ਸਮੱਗਰੀ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ।* -ਹੇਠਾਂ, ਸਮਾਨਤਾ ਦਾ ਮਾਪਣ ਕੋਸਾਈਨ ਸਮਾਨਤਾ (cosine similarity) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਕੀਤਾ ਜਾਂਦਾ ਹੈ — ਮੁੱਖ ਰੂਪ ਵਿੱਚ ਇਹ ਪੁੱਛਦਾ ਹੈ "ਕੀ ਇਹ ਦੋ ਤੀਰ ਇੱਕੋ ਦਿਸ਼ਾ ਵੱਲ ਇشارة ਕਰ ਰਹੇ ਹਨ?" ਦੋ ਟੁਕੜੇ ਬਿਲਕੁਲ ਵੱਖ-ਵੱਖ ਸ਼ਬਦ ਵਰਤ ਸਕਦੇ ਹਨ, ਪਰ ਜੇ ਉਹਨਾਂ ਦਾ ਅਰਥ ਇੱਕੋ ਹੈ ਤਾਂ ਉਹਨਾਂ ਦੇ ਵੇਕਟਰ ਇੱਕੋ ਤਰ੍ਹਾਂ ਇشارة ਕਰਦੇ ਹਨ ਅਤੇ ਸਕੋਰ 1.0 ਦੇ ਨੇੜੇ ਹੁੰਦਾ ਹੈ: +*ਇਹ ਡਾਇਗ੍ਰਾਮ ਕੀਵਰਡ-ਆਧਾਰਿਤ ਖੋਜ ਨਾਲ ਸਮਾਂਤਰੀ ਖੋਜ ਦੀ ਤੁਲਨਾ ਕਰਦਾ ਹੈ, ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਸਮਾਂਤਰੀ ਖੋਜ ਵਿਚਾਰਧਾਰਾ ਦੇ ਸੰਬੰਧਤ ਸਮੱਗਰੀ ਨੂੰ ਕਿਵੇਂ ਲੱਭਦੀ ਹੈ ਭਾਵੇਂ ਸਹੀ ਕੀਵਰਡ ਵੱਖਰੇ ਹੋਣ।* -ਕੋਸਾਈਨ ਸਮਾਨਤਾ +ਅੰਦਰਲੇ ਤੌਰ ਤੇ, ਸਮਾਨਤਾ ਕੋਸਾਈਨ ਸਮਾਨਤਾ ਨਾਲ ਮਾਪੀ ਜਾਂਦੀ ਹੈ — ਅਰਥਾਤ ਪੁੱਛਿਆ ਜਾਂਦਾ ਹੈ "ਕੀ ਇਹ ਦੋ ਤੀਰ ਇੱਕੋ ਹੀ ਦਿਸ਼ਾ ਵੱਲ ਇਸ਼ਾਰਾ ਕਰ ਰਹੇ ਹਨ?" ਦੋ ਚੰਕ ਬਿਲਕੁਲ ਵੱਖਰੇ ਸ਼ਬਦ ਵਰਤ ਸਕਦੇ ਹਨ, ਪਰ ਜੇ ਉਹਨਾਂ ਦਾ ਅਰਥ ਇੱਕੋ ਹੀ ਹੈ, ਤਾਂ ਉਹਨਾਂ ਦੇ ਵੇਕਟਰ ਇੱਕੋ ਦਿਸ਼ਾ ਵੱਲ ਅਤੇ 1.0 ਦੇ ਨੇੜੇ ਸਕੋਰ ਕਰਦੇ ਹਨ: -*ਇਹ ਆਕਰਸ਼ਣ ਵੇਕਟਰਾਂ ਦਰਮਿਆਨ ਕੋਸਾਈਨ ਸਮਾਨਤਾ ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ — ਜਿੰਨੇ ਜ਼ਿਆਦਾ ਕਨੈਕਟਡ ਵੇਕਟਰ ਹੋਣਗੇ ਉਨ੍ਹਾਂ ਦਾ ਸਕੋਰ 1.0 ਦੇ ਨੇੜੇ ਹੋਵੇਗਾ, ਜੋ ਵੱਧ ਸੰਵੇਦਨਾਤਮਕ ਸਮਾਨਤਾ ਦਰਸਾਉਂਦਾ ਹੈ।* +ਕੋਸਾਈਨ ਸਮਾਨਤਾ +*ਇਹ ਆਕਰਸ਼ਣ ਐਮਬੈੱਡਿੰਗ ਵੇਕਟਰਾਂ ਦਰਮਿਆਨ ਕੋਸਾਈਨ ਸਮਾਨਤਾ ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ — ਜ਼ਿਆਦਾ ਸੰਗਤ ਵੇਕਟਰ 1.0 ਦੇ ਨੇੜੇ ਸਕੋਰ ਕਰਦੇ ਹਨ, ਜਿਸਦਾ ਅਰਥ ਹੈ ਵਧੀਕ ਸੈਮਾਂਟਿਕ ਸਮਾਨਤਾ।* > **🤖 [GitHub Copilot](https://github.com/features/copilot) ਚੈਟ ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** ਖੋਲ੍ਹੋ [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ਅਤੇ ਪੁੱਛੋ: -> - "ਐਮਬੈਡਿੰਗਜ਼ ਨਾਲ ਸਮਾਨਤਾ ਖੋਜ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ ਅਤੇ ਕੀ ਤੈਅ ਕਰਦਾ ਹੈ ਸਕੋਰ?" -> - "ਕਿਹੜਾ ਸਮਾਨਤਾ ਸੀਮਾ ਮੈਂ ਵਰਤਾਂ ਅਤੇ ਇਹ ਨਤੀਜੇ ਨੂੰ ਕਿਵੇਂ ਪ੍ਰਭਾਵਿਤ ਕਰਦੀ ਹੈ?" -> - "ਜਦੋਂ ਕੋਈ ਸੰਬੰਧਿਤ ਦਸਤਾਵੇਜ਼ ਨਹੀਂ ਮਿਲਦਾ ਤਾਂ ਮੈਂ ਕਿਵੇਂ ਨਿਪਟਾਰਾ ਕਰਾਂ?" +> - "ਐਮਬੈੱਡਿੰਗ ਨਾਲ ਸਮਾਨਤਾ ਖੋਜ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ ਅਤੇ ਸਕੋਰ ਨੂੰ ਕੀ ਤੈਅ ਕਰਦਾ ਹੈ?" +> - "ਮੈਨੂੰ ਕਿਹੜੀ ਸਮਾਨਤਾ ਸੀਮਾ ਵਰਤਣੀ ਚਾਹੀਦੀ ਹੈ ਅਤੇ ਇਹ ਨਤੀਜਿਆਂ 'ਤੇ ਕਿਵੇਂ ਪ੍ਰਭਾਵ ਪਾਉਂਦੀ ਹੈ?" +> - "ਜਦੋਂ ਕੋਈ ਸਬੰਧਤ ਦਸਤਾਵੇਜ਼ ਨਹੀਂ ਮਿਲਦੇ ਤਾਂ ਮੈਂ ਕਿਵੇਂ ਨਿਭਾਵਾਂ?" -### ਜਵਾਬ ਜਨਰੇਸ਼ਨ +### ਜਵਾਬ ਤਿਆਰ ਕਰਨਾ [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -ਸਭ ਤੋਂ ਸੰਬੰਧਿਤ ਟੁਕੜੇ ਇੱਕ ਸੰਰਚਿਤ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਜੋੜੇ ਜਾਂਦੇ ਹਨ ਜਿਸ ਵਿੱਚ ਸਪਸ਼ਟ ਹੁਕਮ, ਪ੍ਰਾਪਤ ਸੰਦਰਭ, ਅਤੇ ਯੂਜ਼ਰ ਦਾ ਸਵਾਲ ਸ਼ਾਮਲ ਹੁੰਦਾ ਹੈ। ਮਾਡਲ ਉਹ ਖਾਸ ਟੁਕੜੇ ਪੜ੍ਹਦਾ ਹੈ ਅਤੇ ਉਸ ਜਾਣਕਾਰੀ ਦੇ ਅਧਾਰ 'ਤੇ ਜਵਾਬ ਦਿੰਦਾ ਹੈ — ਇਹ ਸਿਰਫ਼ ਉਸ ਆਗੇ ਮੌਜੂਦ ਚੀਜ਼ਾਂ ਦੀ ਵਰਤੋਂ ਕਰ ਸਕਦਾ ਹੈ, ਜੋ ਹਲੂਸੀਨੇਸ਼ਨ ਨੂੰ ਰੋਕਦਾ ਹੈ। +ਸਭ ਤੋਂ ਸਬੰਧਤ ਟੁਕੜੇ ਇਕਠੇ ਕਰਕੇ ਇੱਕ ਗਠਿਤ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਬੰਨ੍ਹੇ ਜਾਂਦੇ ਹਨ ਜਿਸ ਵਿੱਚ ਸਪੱਸ਼ਟ ਹੁਕਮ, ਪ੍ਰਾਪਤ ਸੰਦਰਭ, ਅਤੇ ਵਰਤੋਂਕਾਰ ਦਾ ਸਵਾਲ ਸ਼ਾਮਿਲ ਹੁੰਦਾ ਹੈ। ਮਾਡਲ ਉਹ ਟੁਕੜੇ ਪੜ੍ਹਦਾ ਹੈ ਅਤੇ ਉਸ ਜਾਣਕਾਰੀ ਦੇ ਆਧਾਰ 'ਤੇ ਜਵਾਬ ਦਿੰਦਾ ਹੈ — ਇਹ ਸਿਰਫ ਉਹੀ ਵਰਤ ਸਕਦਾ ਹੈ ਜੋ ਸਾਹਮਣੇ ਹੈ, ਜਿਸ ਨਾਲ ਭਰਮਿਟੀ ਰੋਕੀ ਜਾਂਦੀ ਹੈ। ```java String context = matches.stream() @@ -237,51 +238,51 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -ਹੇਠਾਂ ਦਿੱਤੀ ਆਕਰਸ਼ਣ ਇਹ ਕਾਰਜ ਦਰਸਾਉਂਦੀ ਹੈ — ਖੋਜ ਕਦਮ ਤੋਂ ਸਭ ਤੋਂ ਉੱਚਾ ਸਕੋਰ ਪ੍ਰਾਪਤ ਟੁਕੜੇ ਪ੍ਰਾਂਪਟ ਟੈਮਪਲੇਟ ਵਿੱਚ ਡਾਲੇ ਜਾਂਦੇ ਹਨ, ਅਤੇ `OpenAiOfficialChatModel` ਮੂਲ ਸਟੇਟ ਵਾਲਾ ਜਵਾਬ ਤਿਆਰ ਕਰਦਾ ਹੈ: +ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਅਗ੍ਰਾਮ ਇਸ ਸੰਰਚਨਾ ਨੂਂ ਕਾਰਗਰਤਾ ਵਿੱਚ ਦਰਸਾਉਂਦਾ ਹੈ — ਖੋਜ ਕਦਮ ਤੋਂ ਟਾਪ-ਸਕੋਰਿੰਗ ਟੁਕੜੇ ਪ੍ਰਾਂਪਟ ਟੈਮਪਲੇਟ ਵਿੱਚ ਸ਼ਾਮਿਲ ਕੀਤੇ ਜਾਂਦੇ ਹਨ, ਅਤੇ `OpenAiOfficialChatModel` ਇੱਕ ਅਧਾਰਿਤ ਜਵਾਬ ਤਿਆਰ ਕਰਦਾ ਹੈ: -ਸੰਦਰਭ ਅਸੈਂਬਲੀ +Context Assembly -*ਇਹ ਆਕਰਸ਼ਣ ਦਿਖਾਉਂਦੀ ਹੈ ਕਿ ਕਿਵੇਂ ਸਭ ਤੋਂ ਉੱਚੇ ਸਕੋਰ ਵਾਲੇ ਟੁਕੜੇ ਇੱਕ ਸੰਰਚਿਤ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਜੋੜੇ ਜਾਂਦੇ ਹਨ, ਜਿਸ ਨਾਲ ਮਾਡਲ ਤੁਹਾਡੇ ਡੇਟਾ ਤੋਂ ਇੱਕ ਮੂਲ ਸਟੇਟ ਵਾਲਾ ਜਵਾਬ ਤਿਆਰ ਕਰ ਸਕਦਾ ਹੈ।* +*ਇਹ ਡਾਇਅਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਟਾਪ-ਸਕੋਰਿੰਗ ਟੁਕੜੇ ਕਿਸ ਤਰ੍ਹਾਂ ਗਠਿਤ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਇਕੱਠੇ ਕੀਤੇ ਜਾਂਦੇ ਹਨ, ਤਾਂ ਜੋ ਮਾਡਲ ਤੁਹਾਡੇ ਡੇਟਾ ਤੋਂ ਅਧਾਰਿਤ ਜਵਾਬ ਤਿਆਰ ਕਰ ਸਕੇ।* ## ਐਪਲੀਕੇਸ਼ਨ ਚਲਾਓ -**ਡਿਪਲੋਇਮੈਂਟ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ:** +**ਤਾਇਨਾਤੀ ਜाँचੋ:** -ਸੁਨਿਸ਼ਚਿਤ ਕਰੋ ਕਿ `.env` ਫਾਇਲ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ ਹੈ ਜਿਸ ਵਿੱਚ ਐਜ਼ਯੂਰ ਪ੍ਰਮਾਣਪੱਤਰ (Module 01 ਦੌਰਾਨ ਬਣਾਈ ਗਈ) ਹਨ। ਇਹ ਮੋਡੀਊਲ ਡਾਇਰੈਕਟਰੀ (`03-rag/`) ਤੋਂ ਚਲਾਓ: +ਪੱਕਾ ਕਰੋ ਕਿ ਮੁਲ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ `.env` ਫਾਈਲ ਮੌਜੂਦ ਹੈ ਜਿਸ ਵਿੱਚ Azure ਕ੍ਰੈਡੈਂਸ਼ਲ ਹਨ (Module 01 ਦੌਰਾਨ ਬਣਾਈ ਗਈ)। ਇਸਨੂੰ ਮોડીਊਲ ਡਾਇਰੈਕਟਰੀ ਤੋਂ ਚਲਾਓ (`03-rag/`): **ਬੈਸ਼:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦਿਖਾਣਾ ਚਾਹੀਦਾ ਹੈ +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦਰਸਾਉਣੇ ਚਾਹੀਦੇ ਹਨ ``` **ਪਾਵਰਸ਼ੈੱਲ:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਨੂੰ ਦਿਖਾਇਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ ``` -**ਐਪਲੀਕੇਸ਼ਨ ਚਾਲੂ ਕਰੋ:** +**ਐਪਲੀਕੇਸ਼ਨ ਸ਼ੁਰੂ ਕਰੋ:** -> **ਧਿਆਨ:** ਜੇ ਤੁਸੀਂ ਪਹਿਲਾਂ ਤੋਂ ਹੀ ਸਾਰੇ ਐਪਲੀਕੇਸ਼ਨ `./start-all.sh` ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ ਚਲਾ ਚੁੱਕੇ ਹੋ (ਜਿਵੇਂ Module 01 ਵਿੱਚ ਵਰਨਿਤ ਹੈ), ਇਹ ਮੋਡੀਊਲ ਪਹਿਲਾਂ ਹੀ ਪੋਰਟ 8081 'ਤੇ ਚੱਲ ਰਿਹਾ ਹੈ। ਤੁਸੀਂ ਹੇਠਾਂ ਦਿੱਤੇ ਸ਼ੁਰੂਆਤੀ ਕਮਾਂਡਾਂ ਨੂੰ ਛੱਡ ਕੇ ਸਿੱਧਾ http://localhost:8081 'ਤੇ ਜਾ ਸਕਦੇ ਹੋ। +> **ਨੋਟ:** ਜੇਕਰ ਤੁਸੀਂ ਪਹਿਲਾਂ ਹੀ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ `./start-all.sh` ਚਲਾ ਕੇ ਸਾਰੇ ਐਪਲੀਕੇਸ਼ਨ ਸ਼ੁਰੂ ਕਰ ਚੁੱਕੇ ਹੋ (ਜਿਵੇਂ Module 01 ਵਿੱਚ ਦੱਸਿਆ ਗਿਆ), ਤਾਂ ਇਹ ਮੋਡੀਊਲ ਪਹਿਲਾਂ ਹੀ ਪੋਰਟ 8081 'ਤੇ ਚੱਲ ਰਿਹਾ ਹੈ। ਤੁਸੀਂ ਹੇਠਾਂ ਦਿੱਤੀਆਂ ਸ਼ੁਰੂਆਤੀ ਕਮਾਂਡਾਂ ਛੱਡ ਸਕਦੇ ਹੋ ਅਤੇ ਸਿੱਧਾ http://localhost:8081 'ਤੇ ਜਾ ਸਕਦੇ ਹੋ। -**ਵਿਕਲਪ 1: ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਦੀ ਵਰਤੋਂ (VS Code ਯੂਜ਼ਰਾਂ ਲਈ ਸਿਫਾਰਸ਼ੀ)** +**ਵਿਕਲਪ 1: ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਦੀ ਵਰਤੋਂ ਕਰਨਾ (VS ਕੋਡ ਉਪਭੋਗਤਿਆਂ ਲਈ ਸੁਝਾਇਆ ਜਾਂਦਾ ਹੈ)** -ਡੈਵ ਕਂਟੇਨਰ ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਐਕਸਟੇੰਸ਼ਨ ਸ਼ਾਮਲ ਹੈ, ਜੋ ਕਿ ਸਾਰੇ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨਜ਼ ਦੀ ਪ੍ਰਬੰਧਕੀ ਲਈ ਇੱਕ ਵਿਜ਼ੂਅਲ ਇੰਟਰਫੇਸ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ। ਤੁਸੀਂ ਇਹ VS Code ਦੀ ਬਾਈਆਂ ਪਾਸੇ ਐਕਟਿਵਿਟੀ ਬਾਰ ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਆਈਕਨ 'ਤੇ ਕਲਿੱਕ ਕਰਕੇ ਫੜ ਸਕਦੇ ਹੋ। +ਡੈਵ ਕੰਟੇਨਰ ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਐਕਸਟੈਂਸ਼ਨ ਸ਼ਾਮਿਲ ਹੈ, ਜੋ ਸਾਰੇ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਵਿਜ਼ੂਅਲ ਇੰਟਰਫੇਸ ਰਾਹੀਂ ਪ੍ਰਬੰਧਿਤ ਕਰਨ ਦੀ ਸਹੂਲਤ ਦਿੰਦਾ ਹੈ। ਤੁਸੀਂ ਇਸਨੂੰ VS ਕੋਡ ਦੇ ਖੱਬੇ ਪਾਸੇ ਕੰਮ ਕਾਰ ਬਾਰ ਵਿੱਚ ਲੱਭ ਸਕਦੇ ਹੋ (ਸਪ੍ਰਿੰਗ ਬੂਟ ਆਈਕਨ ਵੇਖੋ)। -ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਵਿੱਚੋਂ, ਤੁਸੀਂ: -- ਵਰਕਸਪੇਸ ਵਿੱਚ ਸਾਰੇ ਉਪਲੱਬਧ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨਜ਼ ਦੇਖ ਸਕਦੇ ਹੋ -- ਇੱਕ ਕਲਿੱਕ ਨਾਲ ਐਪਲੀਕੇਸ਼ਨ ਸ਼ੁਰੂ/ਰੋਕ ਸਕਦੇ ਹੋ -- ਐਪਲੀਕੇਸ਼ਨ ਲਾਗਜ਼ ਨੂੰ ਤੁਰੰਤ ਦੇਖ ਸਕਦੇ ਹੋ -- ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਸਥਿਤੀ ਦੀ ਨਿਗਰਾਨੀ ਕਰ ਸਕਦੇ ਹੋ +ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਵਿਚੋਂ ਤੁਸੀਂ: +- ਵਰਕਸਪੇਸ ਵਿੱਚ ਸਾਰੇ ਉਪਲੱਬਧ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨ ਦੇਖ ਸਕਦੇ ਹੋ +- ਇੱਕ ਕਲਿੱਕ ਨਾਲ ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਸ਼ੁਰੂ/ਬੰਦ ਕਰ ਸਕਦੇ ਹੋ +- ਐਪਲੀਕੇਸ਼ਨ ਲਾਗਸ ਰੀਅਲ-ਟਾਈਮ ਵਿੱਚ ਵੇਖ ਸਕਦੇ ਹੋ +- ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਸਥਿਤੀ ਮਾਨੀਟਰ ਕਰ ਸਕਦੇ ਹੋ -ਸਿਰਫ "rag" ਦੇ ਨਾਲ ਪਲੇ ਬਟਨ 'ਤੇ ਕਲਿੱਕ ਕਰੋ ਇਸ ਮੋਡੀਊਲ ਨੂੰ ਚਾਲੂ ਕਰਨ ਲਈ, ਜਾਂ ਸਾਰੇ ਮੋਡੀਊਲ ਇੱਕ ਵਾਰੀ ਚਾਲੂ ਕਰੋ। +ਸਿਰਫ "rag" ਦੇ ਨਾਲ ਖੇਡ ਬਟਨ 'ਤੇ ਕਲਿੱਕ ਕਰੋ ਮੋਡੀਊਲ ਚਲਾਉਣ ਲਈ, ਜਾਂ ਇੱਕ ਵਾਰੀ ਤੇ ਸਾਰੇ ਮੋਡੀਊਲ ਸ਼ੁਰੂ ਕਰੋ। -ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ +Spring Boot Dashboard -*ਇਹ ਸਕਰੀਨਸ਼ਾਟ VS Code ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਦਿਖਾਉਂਦਾ ਹੈ, ਜਿੱਥੇ ਤੁਸੀਂ ਐਪਲੀਕੇਸ਼ਨਜ਼ ਨੂੰ ਵਿਜ਼ੂਅਲੀ ਤੌਰ 'ਤੇ ਚਾਲੂ, ਰੋਕ, ਅਤੇ ਨਿਗਰਾਨੀ ਕਰ ਸਕਦੇ ਹੋ।* +*ਇਹ ਸਕਰੀਨਸ਼ਾਟ VS ਕੋਡ ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਨੂੰ ਦਿਖਾਉਂਦਾ ਹੈ, ਜਿੱਥੇ ਤੁਸੀਂ ਵਿਜ਼ੂਅਲ ਤੌਰ 'ਤੇ ਐਪਲੀਕੇਸ਼ਨ ਸ਼ੁਰੂ, ਬੰਦ ਅਤੇ ਮਾਨੀਟਰ ਕਰ ਸਕਦੇ ਹੋ।* -**ਵਿਕਲਪ 2: ਸ਼ੈੱਲ ਸਕ੍ਰਿਪਟਸ ਦੀ ਵਰਤੋਂ** +**ਵਿਕਲਪ 2: ਸ਼ੈੱਲ ਸਕ੍ਰਿਪਟ ਵਰਤਣਾ** -ਸਾਰੇ ਵੈਬ ਐਪਲੀਕੇਸ਼ਨ (ਮੋਡੀਊਲ 01-04) ਸ਼ੁਰੂ ਕਰੋ: +ਸਾਰੇ ਵੈੱਬ ਐਪਲੀਕੇਸ਼ਨ (ਮੋਡੀਊਲ 01-04) ਸ਼ੁਰੂ ਕਰੋ: **ਬੈਸ਼:** ```bash @@ -291,11 +292,11 @@ cd .. # ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ **ਪਾਵਰਸ਼ੈੱਲ:** ```powershell -cd .. # ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ +cd .. # ਪ੍ਰਧਾਨ ਡਾਇਰੈਕਟਰੀ ਤੋਂ .\start-all.ps1 ``` -ਜਾਂ ਸਿਰਫ ਇਸ ਮੋਡੀਊਲ ਨੂੰ ਚਾਲੂ ਕਰੋ: +ਜਾਂ ਸਿਰਫ ਇਹ ਮੋਡੀਊਲ ਸ਼ੁਰੂ ਕਰੋ: **ਬੈਸ਼:** ```bash @@ -309,9 +310,9 @@ cd 03-rag .\start.ps1 ``` -ਦੋਹਾਂ ਸਕ੍ਰਿਪਟਾਂ ਆਪਣੇ ਆਪ ਮੂਲ `.env` ਫਾਇਲ ਤੋਂ ਵਾਤਾਵਰਣ ਚਰ (environment variables) ਲੋਡ ਕਰਦੀਆਂ ਹਨ ਅਤੇ ਜੇ JAR ਫਾਇਲਾਂ ਮੌਜੂਦ ਨਹੀਂ ਹਨ ਤਾਂ ਉਸ ਨੂੰ ਬਣਾ ਲੈਂਦੀਆਂ ਹਨ। +ਦੋਹਾਂ ਸਕ੍ਰਿਪਟਾਂ ਨੂੰ ਮੂਲ `.env` ਫਾਈਲ ਵਿਚੋਂ ਆਟੋਮੈਟਿਕ ਵਾਤਾਵਰਨ ਵੈਰੀਏਬਲ ਲੋਡ ਹੁੰਦੇ ਹਨ ਅਤੇ ਜੇ ਜਾਰ ਮੌਜੂਦ ਨਾ ਹੋਣ ਤਾਂ ਉਹਨੂੰ ਬਣਾ ਲੈਂਦੇ ਹਨ। -> **ਧਿਆਨ:** ਜੇ ਤੁਸੀਂ ਸਾਰੇ ਮੋਡੀਊਲਾਂ ਨੂੰ ਹੱਥੋਂ ਹੱਥ ਬਣਾਉਣਾ ਚਾਹੁੰਦੇ ਹੋ ਪਹਿਲਾਂ: +> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਸਾਰੇ ਮੋਡੀਊਲ ਹੱਥੋਂ ਬਣਾਉਣਾ ਪਸੰਦ ਕਰਦੇ ਹੋ, ਤਾਂ ਕਿਰਪਾ ਕਰਕੇ ਸ਼ੁਰੂ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਇਹ ਕਮਾਂਡਾਂ ਚਲਾਓ: > > **ਬੈਸ਼:** > ```bash @@ -325,113 +326,113 @@ cd 03-rag > mvn clean package -DskipTests > ``` -ਆਪਣੇ ਬਰਾਊਜ਼ਰ ਵਿੱਚ http://localhost:8081 ਖੋਲ੍ਹੋ। +ਆਪਣੇ ਬ੍ਰਾਉਜ਼ਰ ਵਿੱਚ http://localhost:8081 ਖੋਲ੍ਹੋ। **ਰੋਕਣ ਲਈ:** **ਬੈਸ਼:** ```bash -./stop.sh # ਇਹ ਮਾਡਯੂਲ ਸਿਰਫ +./stop.sh # ਸਿਰਫ ਇਹ ਮੌਡੀਊਲ # ਜਾਂ -cd .. && ./stop-all.sh # ਸਾਰੇ ਮਾਡਯੂਲ +cd .. && ./stop-all.sh # ਸਾਰੇ ਮੌਡੀਊਲ ``` **ਪਾਵਰਸ਼ੈੱਲ:** ```powershell -.\stop.ps1 # ਇਹ ਸਿਰਫ ਮੋਡੀਊਲ +.\stop.ps1 # ਸਿਰਫ ਇਹ ਮੋਡੀਊਲ # ਜਾਂ cd ..; .\stop-all.ps1 # ਸਾਰੇ ਮੋਡੀਊਲ ``` ## ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਵਰਤੋਂ -ਐਪਲੀਕੇਸ਼ਨ ਦਸਤਾਵੇਜ਼ ਅੱਪਲੋਡ ਅਤੇ ਸਵਾਲ ਪੁੱਛਣ ਲਈ ਵੈੱਬ ਇੰਟਰਫੇਸ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ। +ਐਪਲੀਕੇਸ਼ਨ ਇੱਕ ਵੈੱਬ ਇੰਟਰਫੇਸ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ ਦਸਤਾਵੇਜ਼ ਅਪਲੋਡ ਕਰਨ ਅਤੇ ਸਵਾਲ ਪੁੱਛਣ ਲਈ। -RAG ਐਪਲੀਕੇਸ਼ਨ ਇੰਟਰਫੇਸ +RAG Application Interface -*ਇਹ ਸਕਰੀਨਸ਼ਾਟ RAG ਐਪਲੀਕੇਸ਼ਨ ਇੰਟਰਫੇਸ ਦਿਖਾਉਂਦਾ ਹੈ ਜਿੱਥੇ ਤੁਸੀਂ ਦਸਤਾਵੇਜ਼ ਅੱਪਲੋਡ ਕਰਦੇ ਹੋ ਅਤੇ ਸਵਾਲ ਪੁੱਛਦੇ ਹੋ।* +*ਇਹ ਸਕਰੀਨਸ਼ਾਟ RAG ਐਪਲੀਕੇਸ਼ਨ ਇੰਟਰਫੇਸ ਦਿਖਾਉਂਦਾ ਹੈ ਜਿੱਥੇ ਤੁਸੀਂ ਦਸਤਾਵੇਜ਼ ਅਪਲੋਡ ਕਰਦੇ ਹੋ ਅਤੇ ਸਵਾਲ ਪੁੱਛਦੇ ਹੋ।* -### ਦਸਤਾਵੇਜ਼ ਅੱਪਲੋਡ ਕਰੋ +### ਦਸਤਾਵੇਜ਼ ਅਪਲੋਡ ਕਰੋ -ਸ਼ੁਰੂਆਤ ਦਸਤਾਵੇਜ਼ ਅੱਪਲੋਡ ਕਰਕੇ ਕਰੋ - TXT ਫਾਇਲਾਂ ਟੈਸਟਿੰਗ ਲਈ ਸਭ ਤੋਂ ਵਧੀਆ ਹਨ। ਇਸ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ ਇਕ `sample-document.txt` ਪ੍ਰਦਾਨ ਕੀਤੀ ਗਈ ਹੈ ਜਿਸ ਵਿੱਚ LangChain4j ਦੀਆਂ ਵਿਸ਼ੇਸ਼ਤਾਵਾਂ, RAG ਇੰਪਲੀਮੈਂਟੇਸ਼ਨ ਅਤੇ ਸਭ ਤੋਂ ਵਧੀਆ ਅਭਿਆਸਾਂ ਬਾਰੇ ਜਾਣਕਾਰੀ ਹੈ - ਸਿਸਟਮ ਦੀ ਟੈਸਟਿੰਗ ਲਈ ਵਿਖੇ ਸਦਨ ਹੈ। +ਦਸਤਾਵੇਜ਼ ਅਪਲੋਡ ਕਰਨਾ ਸ਼ੁਰੂ ਕਰੋ - TXT ਫਾਈਲਾਂ ਪਰਖ ਲਈ ਵਧੀਆ ਹਨ। ਇਸ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ ਇੱਕ `sample-document.txt` ਮੁਹੱਈਆ ਹੈ, ਜਿਸ ਵਿੱਚ LangChain4j ਵਿਸ਼ੇਸ਼ਤਾਵਾਂ, RAG ਕਾਰਗੁਜ਼ਾਰੀ, ਅਤੇ ਸ੍ਰੇਸ਼ਠ ਪ੍ਰਥਾਵਾਂ ਬਾਰੇ ਜਾਣਕਾਰੀ ਹੈ - ਜੋ ਸਿਸਟਮ ਨੂੰ ਇਮਤਿਹਾਨ ਕਰਨ ਲਈ ਬਹੁਤ ਉਚਿਤ ਹੈ। -ਸਿਸਟਮ ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਪ੍ਰਕਿਰਿਆ ਕਰਦਾ ਹੈ, ਇਸਨੂੰ ਟੁਕੜਿਆਂ ਵਿੱਚ ਵੰਡਦਾ ਹੈ, ਅਤੇ ਹਰ ਟੁਕੜੇ ਲਈ ਐਮਬੈਡਿੰਗਸ ਬਣਾਉਂਦਾ ਹੈ। ਇਹ ਸਾਰਾ ਕੰਮ ਤੁਹਾਡੇ ਅੱਪਲੋਡ ਕਰਨ ਤੇ ਸਵੈਚਾਲਿਤ ਤੌਰ 'ਤੇ ਹੁੰਦਾ ਹੈ। +ਸਿਸਟਮ ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਪ੍ਰਕਿਰਿਆ ਕਰਦਾ ਹੈ, ਇਸਨੂੰ ਟੁਕੜਿਆਂ ਵਿੱਚ ਵੰਡਦਾ ਹੈ, ਅਤੇ ਹਰ ਟੁਕੜੇ ਲਈ ਐਮਬੈੱਡਿੰਗ ਤਿਆਰ ਕਰਦਾ ਹੈ। ਇਹ ਪ੍ਰਕਿਰਿਆ ਆਪਣੇ ਆਪ ਹੀ ਅਪਲੋਡ ਹੋਣ 'ਤੇ ਚੱਲਦੀ ਹੈ। ### ਸਵਾਲ ਪੁੱਛੋ -ਹੁਣ ਦਸਤਾਵੇਜ਼ ਸਮੱਗਰੀ ਬਾਰੇ ਵਿਸ਼ੇਸ਼ ਸਵਾਲ ਪੁੱਛੋ। ਕੁਝ ਐਸਾ ਕੋਸ਼ਿਸ਼ ਕਰੋ ਜੋ ਦਸਤਾਵੇਜ਼ ਵਿੱਚ ਸਪਸ਼ਟ ਤੌਰ 'ਤੇ ਦਰਸਾਇਆ ਹੋਵੇ। ਸਿਸਟਮ ਸੰਬੰਧਿਤ ਟੁਕੜਿਆਂ ਦੀ ਖੋਜ ਕਰਦਾ ਹੈ, ਉਹਨਾਂ ਨੂੰ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਸ਼ਾਮਲ ਕਰਦਾ ਹੈ ਅਤੇ ਜਵਾਬ ਤਿਆਰ ਕਰਦਾ ਹੈ। +ਹੁਣ ਦਸਤਾਵੇਜ਼ ਦੇ ਸਮੱਗਰੀ ਬਾਰੇ ਵਿਸ਼ੇਸ਼ ਸਵਾਲ ਪੁੱਛੋ। ਕੋਈ ਸਪੱਸ਼ਟ ਤੱਥੀ ਸਵਾਲ ਜਿਹੜਾ ਸਪਸ਼ਟ ਤੌਰ 'ਤੇ ਦਸਤਾਵੇਜ਼ ਵਿੱਚ ਦਿੱਤਾ ਗਿਆ ਹੋਵੇ, ਕੋਸ਼ਿਸ਼ ਕਰੋ। ਸਿਸਟਮ ਸਬੰਧਤ ਟੁਕੜਿਆਂ ਦੀ ਖੋਜ ਕਰਦਾ ਹੈ, ਉਨ੍ਹਾਂ ਨੂੰ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਸ਼ਾਮਿਲ ਕਰਦਾ ਹੈ, ਅਤੇ ਜਵਾਬ ਤਿਆਰ ਕਰਦਾ ਹੈ। ### ਸਰੋਤ ਸੰਦਰਭ ਜਾਂਚੋ -ਹਰ ਜਵਾਬ ਵਿੱਚ ਸਰੋਤ ਸੰਦਰਭ ਅਤੇ ਸਮਾਨਤਾ ਸਕੋਰ ਸ਼ਾਮਲ ਹੁੰਦੇ ਹਨ। ਇਹ ਸਕੋਰ (0 ਤੋਂ 1 ਤੱਕ) ਦਰਸਾਉਂਦੇ ਹਨ ਕਿ ਹਰ ਟੁਕੜਾ ਤੁਹਾਡੇ ਸਵਾਲ ਲਈ ਕਿੰਨਾ ਸਬੰਧਿਤ ਸੀ। ਉੱਚ ਸਕੋਰ ਬਿਹਤਰ ਮੇਲ ਦੇ ਹਨ। ਇਸ ਨਾਲ ਤੁਸੀਂ ਜਵਾਬ ਨੂੰ ਸਰੋਤ ਸਮੱਗਰੀ ਨਾਲ ਮਤਾਬਕ ਜਾਂਚ ਸਕਦੇ ਹੋ। +ਹਰੇਕ ਜਵਾਬ ਨਾਲ ਸਰੋਤ ਸੰਦਰਭ ਹੁੰਦੇ ਹਨ ਜਿਨ੍ਹਾਂ 'ਚ ਸਮਾਨਤਾ ਸਕੋਰ ਸ਼ਾਮਿਲ ਹੁੰਦਾ ਹੈ। ਇਹ ਸਕੋਰ (0 ਤੋਂ 1 ਤੱਕ) ਦਿਖਾਉਂਦੇ ਹਨ ਕਿ ਹਰ ਟੁਕੜਾ ਤੁਹਾਡੇ ਸਵਾਲ ਨਾਲ ਕਿੰਨਾ ਸਬੰਧਤ ਸੀ। ਵਧੀਆ ਸਕੋਰ ਦੇ ਮਤਲਬ ਹਨ ਚੰਗੇ ਮਿਲਾਪ। ਇਸ ਨਾਲ ਤੁਸੀਂ ਜਵਾਬ ਨੂੰ ਸਰੋਤ ਸਮੱਗਰੀ ਨਾਲ ਤੁਲਨਾ ਕਰ ਸਕਦੇ ਹੋ। -RAG ਪੁੱਛੜੀ ਨਤੀਜੇ +RAG Query Results -*ਇਹ ਸਕਰੀਨਸ਼ਾਟ ਵਿਖਾਉਂਦਾ ਹੈ ਕਿ ਪੁੱਛੜੀ ਨਤੀਜੇ ਵਿੱਚ ਜਨਰੇਟ ਕੀਤਾ ਜਵਾਬ, ਸਰੋਤ ਸੰਦਰਭ ਅਤੇ ਪ੍ਰਾਪਤ ਹਰ ਟੁਕੜੇ ਲਈ ਸਬੰਧਿਤਤਾ ਸਕੋਰ ਕਿਵੇਂ ਹਨ।* +*ਇਹ ਸਕਰੀਨਸ਼ਾਟ ਪੁੱਛੇ ਗਿਆ ਸਵਾਲ, ਤਿਆਰ ਕੀਤਾ ਜਵਾਬ, ਸਰੋਤ ਸੰਦਰਭ, ਅਤੇ ਪ੍ਰਤੀ ਟੁਕੜਾ ਪ੍ਰਾਪਤ ਕੀਤੀ ਨਤੀਜਿਆਂ ਦੀ ਸਮਾਨਤਾ ਸਕੋਰ ਦਿਖਾਉਂਦਾ ਹੈ।* -### ਸਵਾਲਾਂ ਨਾਲ ਪਰਖੋ +### ਸਵਾਲਾਂ ਨਾਲ ਪ੍ਰਯੋਗ ਕਰੋ -ਵੱਖ-ਵੱਖ ਕਿਸਮਾਂ ਦੇ ਸਵਾਲਾਂ ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ: -- ਖਾਸ ਤੱਥ: "ਮੁੱਖ ਵਿਸ਼ਾ ਕੀ ਹੈ?" -- ਤੁਲਨਾ: "X ਅਤੇ Y ਵਿੱਚ ਕੀ ਫਰਕ ਹੈ?" -- ਸਾਰ: "Z ਬਾਰੇ ਮੁੱਖ ਬਿੰਦੂ ਸਾਰਾਂਸ਼ ਕਰੋ" +ਵੱਖ-ਵੱਖ ਕਿਸਮ ਦੇ ਸਵਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ: +- ਵਿਸ਼ੇਸ਼ ਤੱਥ: "ਮੁੱਖ ਵਿਸ਼ਾ ਕੀ ਹੈ?" +- ਤੁਲਨਾਤਮਕ: "X ਅਤੇ Y ਵਿੱਚ ਕੀ ਫਰਕ ਹੈ?" +- ਸੰਖੇਪ: "Z ਬਾਰੇ ਮੁੱਖ ਬਿੰਦੂ ਸੰਗ੍ਰਿਹਤ ਕਰੋ" -ਦੇਖੋ ਕਿ ਸਬੰਧਿਤਤਾ ਸਕੋਰ ਕਿਵੇਂ ਬਦਲਦੇ ਹਨ ਇਹ ਨਿਰਭਰ ਕਰਦਾ ਹੈ ਕਿ ਤੁਹਾਡਾ ਸਵਾਲ ਦਸਤਾਵੇਜ਼ ਦੀ ਸਮੱਗਰੀ ਨਾਲ ਕਿੰਨਾ ਮੇਲ ਖਾਂਦਾ ਹੈ। +ਦੇਖੋ ਕਿ ਕਿਵੇਂ ਸਮਾਨਤਾ ਸਕੋਰ ਬਦਲਦੇ ਹਨ ਇਸ ਗੱਲ 'ਤੇ ਨਿਰਭਰ ਕਰਕੇ ਕਿ ਤੁਹਾਡਾ ਸਵਾਲ ਦਸਤਾਵੇਜ਼ ਸਮੱਗਰੀ ਨਾਲ ਕਿੰਨਾ ਮਿਲਦਾ ਹੈ। -## ਮੁੱਖ ਧਾਰਨਾ +## ਮੁੱਖ ਧਾਰਨਾਵਾਂ -### ਟੁਕੜੇ ਬਣਾਉਣ ਦੀ ਰਣਨੀਤੀ +### ਟੁਕੜਾ ਬਣਾਉਣ ਦੀ ਰਣਨੀਤੀ -ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ 300-ਟੋਕਨ ਵਾਲੇ ਟੁਕੜਿਆਂ ਵਿੱਚ ਵੰਡਿਆ ਜਾਂਦਾ ਹੈ ਜਿਸ ਵਿੱਚ 30 ਟੋਕਨਾਂ ਦੀ ਅਤਿਰਿਕਤ ਓਵਰਲੈਪ ਹੁੰਦੀ ਹੈ। ਇਹ ਸੰਤੁਲਨ ਇਹ ਸੁਨਿਸ਼ਚਿਤ ਕਰਦਾ ਹੈ ਕਿ ਹਰ ਟੁਕੜਾ ਕਾਫ਼ੀ ਸੰਦਰਭ ਰੱਖਦਾ ਹੈ ਪਰ ਛੋਟਾ ਰੱਖਿਣ ਲਈ ਕਈ ਟੁਕੜੇ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਸ਼ਾਮਲ ਕੀਤੇ ਜਾ ਸਕਦੇ ਹਨ। +ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ 300-ਟੋਕਨ ਦੇ ਟੁਕੜਿਆਂ ਵਿੱਚ ਵੰਡਿਆ ਜਾਂਦਾ ਹੈ, ਜਿਨ੍ਹਾਂ ਵਿੱਚ 30 ਟੋਕਨ ਦੀ ਓਵਰਲੈਪ ਹੁੰਦੀ ਹੈ। ਇਹ ਸੰਤੁਲਨ ਇਹ ਯਕੀਨੀ ਬਣਾਉਂਦਾ ਹੈ ਕਿ ਹਰ ਟੁਕੜਾ ਕਾਫੀ ਸੰਦਰਭ ਰੱਖਦਾ ਹੈ ਤਾਂ ਜੋ ਉਹ ਮਾਨੇ ਜਾ ਸਕੇ, ਪਰ ਉਨ੍ਹਾਂ ਦਾ ਆਕਾਰ ਛੋਟਾ ਰੱਖ ਕੇ ਇੱਕ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਕਈ ਟੁਕੜੇ ਸ਼ਾਮਿਲ ਕੀਤੇ ਜਾ ਸਕਣ। ### ਸਮਾਨਤਾ ਸਕੋਰ -ਹਰ ਪ੍ਰਾਪਤ ਟੁਕੜਾ 0 ਤੋਂ 1 ਦੇ ਦਰਮਿਆਨ ਸਮਾਨਤਾ ਸਕੋਰ ਨਾਲ ਹੁੰਦਾ ਹੈ ਜੋ ਦਰਸਾਉਂਦਾ ਹੈ ਕਿ ਇਹ ਯੂਜ਼ਰ ਦੇ ਸਵਾਲ ਨਾਲ ਕਿੰਨਾ ਮੇਲ ਖਾਂਦਾ ਹੈ। ਹੇਠਾਂ ਦਿੱਤਾ ਆਕਰਸ਼ਣ ਸਕੋਰ ਦੀਆਂ ਸੀਮਾਵਾਂ ਦਿਖਾਉਂਦਾ ਹੈ ਅਤੇ ਸਿਸਟਮ ਇਨ੍ਹਾਂ ਨੂੰ ਨਤੀਜਿਆਂ ਨੂੰ ਛਾਂਟਣ ਲਈ ਕਿਵੇਂ ਵਰਤਦਾ ਹੈ: +ਹਰੇਕ ਲੱਭਿਆ ਟੁਕੜਾ 0 ਤੋਂ 1 ਤੱਕ ਦੇ ਸਮਾਨਤਾ ਸਕੋਰ ਨਾਲ ਆਉਂਦਾ ਹੈ ਜੋ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਉਹ ਵਰਤੋਂਕਾਰ ਦੇ ਸਵਾਲ ਨਾਲ ਕਿੰਨਾ ਨੇੜਲਾ ਸੀ। ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਇਅਗ੍ਰਾਮ ਸਕੋਰ ਰੇਂਜ ਅਤੇ ਕੰਮ ਕਰਨ ਦਾ ਤਰੀਕਾ ਦਰਸਾਉਂਦਾ ਹੈ: -ਸਮਾਨਤਾ ਸਕੋਰ +Similarity Scores -*ਇਹ ਆਕਰਸ਼ਣ ਦਰਸਾਉਂਦਾ ਹੈ ਕਿ 0 ਤੋਂ 1 ਤੱਕ ਕੀ ਸਕੋਰ ਸੀਮਾ ਹੈ, ਜਿਸ ਵਿੱਚ ਘੱਟੋ-ਘੱਟ ਸੀਮਾ 0.5 ਹੈ ਜੋ අਸੰਬੰਧਿਤ ਟੁਕੜਿਆਂ ਨੂੰ ਬਾਹਰ ਕਰਦਾ ਹੈ।* +*ਇਹ ਡਾਇਅਗ੍ਰਾਮ 0 ਤੋਂ 1 ਦੇ ਸਕੋਰ ਰੇਂਜ ਦਿਖਾਉਂਦਾ ਹੈ, ਜਿਸ ਵਿੱਚ 0.5 ਦਾ ਘੱਟੋ-ਘੱਟ ਸੀਮਾ ਹੈ ਜੋ ਗ਼ੈਰ-ਸਬੰਧਤ ਟੁਕੜਿਆਂ ਨੂੰ ਫਿਲਟਰ ਕਰਦਾ ਹੈ।* -ਸਕੋਰਾਂ ਦੀ ਸੀਮਾ 0 ਤੋਂ 1 ਤੱਕ: -- 0.7-1.0: ਬਹੁਤ ਸੰਬੰਧਿਤ, ਸਹੀ ਮੇਲ -- 0.5-0.7: ਸੰਬੰਧਿਤ, ਵਧੀਆ ਸੰਦਰਭ -- 0.5 ਤੋਂ ਘੱਟ: ਛਾਨਿਆ ਹੋਇਆ, ਬਹੁਤ ਵੱਖਰਾ +ਸਕੋਰ ਰੇਂਜ 0 ਤੋਂ 1: +- 0.7-1.0: ਬਹੁਤ ਸਬੰਧਤ, ਬਿਲਕੁਲ ਮਿਲਦਾ ਜੁਲਦਾ +- 0.5-0.7: ਸਬੰਧਤ, ਵਧੀਆ ਸੰਦਰਭ +- 0.5 ਤੋਂ ਘੱਟ: ਫਿਲਟਰ ਕੀਤੇ ਗਏ, ਬਹੁਤ ਵੱਖਰੇ -ਸਿਸਟਮ ਸਿਰਫ ਘੱਟੋ-ਘੱਟ ਮਿਆਰ ਤੋਂ ਉੱਪਰ ਵਾਲੇ ਟੁਕੜਿਆਂ ਨੂੰ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ ਜਿਸ ਨਾਲ ਗੁਣਵੱਤਾ ਯਕੀਨੀ ਬਣਾਈ ਜਾਂਦੀ ਹੈ। +ਸਿਸਟਮ ਗੁਣਵੱਤਾ ਯਕੀਨੀ ਬਣਾਉਣ ਲਈ ਘੱਟੋ-ਘੱਟ ਸੀਮਾ ਤੋਂ ਉਪਰ ਵਾਲੇ ਟੁਕੜੇ ਹੀ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ। -ਐਮਬੈਡਿੰਗਸ ਵਧੀਆ ਕੰਮ ਕਰਦੇ ਹਨ ਜਦੋਂ ਅਰਥ ਸਾਫ਼-ਸੁਥਰਾ ਕਲੱਸਟਰ ਬਣਾਉਂਦਾ ਹੈ, ਪਰ ਉਹ ਅੰਧੇਰਾ ਸਥਾਨ ਵੀ ਹੁੰਦੇ ਹਨ। ਹੇਠਾਂ ਦਿੱਤੀ ਆਕਰਸ਼ਣ ਆਮ ਅਸਫਲਤਾ ਮੋਡ ਦਰਸਾਉਂਦਾ ਹੈ — ਬਹੁਤ ਵੱਡੇ ਟੁਕੜੇ ਬਦਤਰੇ ਵੇਕਟਰ ਬਣਾਉਂਦੇ ਹਨ, ਬਹੁਤ ਛੋਟੇ ਟੁਕੜੇ ਸੰਦਰਭ ਘੱਟ ਹੁੰਦੇ ਹਨ, ਅਸਪਸ਼ਟ ਸ਼ਬਦ ਕਈ ਕਲੱਸਟਰਾਂ ਵੱਲ ਇਸ਼ਾਰਾ ਕਰਦੇ ਹਨ, ਅਤੇ ਸਹੀ ਮੇਲ ਲੁਕਅਪ (IDs, ਹਿੱਸਾ ਨੰਬਰ) ਐਮਬੈਡਿੰਗਸ ਨਾਲ ਬਿਲਕੁਲ ਕੰਮ ਨਹੀਂ ਕਰਦੇ: +ਐਮਬੈੱਡਿੰਗਸ ਵਧੀਆ ਕੰਮ ਕਰਦੀਆਂ ਹਨ ਜਦੋਂ ਅਰਥ ਸੁਚੱਜੇ ਢੰਗ ਨਾਲ ਕਲੱਸਟਰ ਹੁੰਦੇ ਹਨ, ਪਰ ਉਨ੍ਹਾਂ ਦੀਆਂ ਕਈ ਅੜਚਣਾਂ ਹਨ। ਹੇਠਾਂ ਡਾਇਅਗ੍ਰਾਮ ਆਮ ਅਸਫਲਤਾ ਮੋਡ ਦਰਸਾਉਂਦਾ ਹੈ — ਵੱਡੇ ਟੁਕੜੇ ਗੰਦੇ ਵੇਕਟਰ ਬਣਾਉਂਦੇ ਹਨ, ਛੋਟੇ ਟੁਕੜਿਆਂ ਵਿੱਚ ਸੰਦਰਭ ਘੱਟ ਹੁੰਦਾ ਹੈ, ਦੁਅਰਥੀ ਸ਼ਬਦ ਕਈ ਕਲੱਸਟਰਾਂ ਦੀ ਪਿਛਾਣ ਕਰਦੇ ਹਨ, ਅਤੇ ਬਿਲਕੁਲ ਮਿਲਦੇ-ਜੁਲਦੇ ਲੁੱਕਅੱਪ (IDs, ਭਾਗ ਨੰਬਰ) ਐਮਬੈੱਡਿੰਗ ਨਾਲ ਕੰਮ ਨਹੀਂ ਕਰਦੇ: -ਐਮਬੈਡਿੰਗ ਅਸਫਲਤਾ ਮੋਡ +Embedding Failure Modes -*ਇਹ ਆਕਰਸ਼ਣ ਆਮ ਐਮਬੈਡਿੰਗ ਅਸਫਲਤਾ ਮੋਡ ਦਿਖਾਉਂਦਾ ਹੈ: ਬਹੁਤ ਵੱਡੇ ਟੁਕੜੇ, ਬਹੁਤ ਛੋਟੇ ਟੁਕੜੇ, ਅਸਪਸ਼ਟ ਟਰਮ ਜੋ ਕਈ ਕਲੱਸਟਰਾਂ ਵੱਲ ਇਸ਼ਾਰਾ ਕਰਦੇ ਹਨ, ਅਤੇ ਸਹੀ ਮੇਲ ਲੁਕਅਪ ਜਿਵੇਂ IDs।* +*ਇਹ ਡਾਇਅਗ੍ਰਾਮ ਆਮ ਐਮਬੈੱਡਿੰਗ ਅਸਫਲਤਾ ਮੋਡ ਦਿਖਾਉਂਦਾ ਹੈ: ਵੱਡੇ ਟੁਕੜੇ, ਛੋਟੇ ਟੁਕੜੇ, ਅਸਪਸ਼ਟ ਸ਼ਬਦ ਜੋ ਕਈ ਕਲੱਸਟਰਾਂ ਨੂੰ ਦਰਸਾਉਂਦੇ ਹਨ, ਅਤੇ ਬਿਲਕੁਲ ਮਿਲਦੇ-ਜੁਲਦੇ ਲੁੱਕਅੱਪ ਜਿਵੇਂ IDs।* ### ਇਨ-ਮੇਮੋਰੀ ਸਟੋਰੇਜ -ਇਹ ਮੋਡੀਊਲ ਸਾਦਗੀ ਲਈ ਇਨ-ਮੇਮੋਰੀ ਸਟੋਰੇਜ ਦੀ ਵਰਤੋਂ ਕਰਦਾ ਹੈ। ਜਦੋਂ ਤੁਸੀਂ ਐਪਲੀਕੇਸ਼ਨ ਨੂੰ ਦੁਬਾਰਾ ਚਾਲੂ ਕਰਦੇ ਹੋ, ਅੱਪਲੋਡ ਕੀਤੇ ਦਸਤਾਵੇਜ਼ ਖੋ ਜਾਂਦੇ ਹਨ। ਪ੍ਰੋਡਕਸ਼ਨ ਸਿਸਟਮ ਕਾਇਮ ਰੱਖਣ ਵਾਲੇ ਵੈਕਟਰ ਡਾਟਾਬੇਸ ਜਿਵੇਂ Qdrant ਜਾਂ Azure AI Search ਦੀ ਵਰਤੋਂ ਕਰਦੇ ਹਨ। +ਇਹ ਮੋਡੀਊਲ ਸਾਦਗੀ ਲਈ ਇਨ-ਮੇਮੋਰੀ ਸਟੋਰੇਜ ਵਰਤਦਾ ਹੈ। ਜਦੋਂ ਤੁਸੀਂ ਐਪਲੀਕੇਸ਼ਨ ਨੂੰ ਰੀਸਟਾਰਟ ਕਰਦੇ ਹੋ, ਤਾਂ ਅਪਲੋਡ ਕੀਤੇ ਦਸਤਾਵੇਜ਼ ਖੋ ਜਾਂਦੇ ਹਨ। ਪ੍ਰੋਡਕਸ਼ਨ ਸਿਸਟਮ Qdrant ਜਾਂ Azure AI Search ਵਰਗੇ ਪਾਇਦਾਰ ਵੇਕਟਰ ਡੇਟਾਬੇਸ ਵਰਤਦੇ ਹਨ। -### ਸੰਦਰਭ ਵਿੰਡੋ ਪ੍ਰਬੰਧਨ +### ਸੰਦਰਭ ਵਿਂਡੋ ਪ੍ਰਬੰਧਨ -ਹਰ ਮਾਡਲ ਦੀ ਆਪਣੇ ਤੱਕਸਾਲੀ ਸੰਦਰਭ ਵਿੰਡੋ ਹੁੰਦੀ ਹੈ। ਤੁਸੀਂ ਵੱਡੇ ਦਸਤਾਵੇਜ਼ ਦੇ ਹਰ ਟੁਕੜੇ ਸ਼ਾਮਲ ਨਹੀਂ ਕਰ ਸਕਦੇ। ਸਿਸਟਮ ਸਭ ਤੋਂ ਸੰਬੰਧਿਤ 5 (ਡਿਫਾਲਟ) ਟੁਕੜੇ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ ਤਾਂ ਜੋ ਸੀਮਾਵਾਂ ਦੇ ਅੰਦਰ ਰਹਿੰਦਾ ਹੋਵੇ ਅਤੇ ਸਹੀ ਜਵਾਬ ਦੇਣ ਲਈ ਕਾਫ਼ੀ ਸੰਦਰਭ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੋਵੇ। +ਹਰ ਮਾਡਲ ਦੀ ਇੱਕ ਵੱਧ ਤੋਂ ਵੱਧ ਸੰਦਰਭ ਖਿੜਕੀ ਹੁੰਦੀ ਹੈ। ਤੁਸੀਂ ਵੱਡੇ ਦਸਤਾਵੇਜ਼ ਦੇ ਸਾਰੇ ਟੁਕੜੇ ਸ਼ਾਮਿਲ ਨਹੀਂ ਕਰ ਸਕਦੇ। ਸਿਸਟਮ ਸਭ ਤੋਂ ਸਬੰਧਤ N (ਡਿਫਾਲਟ 5) ਟੁਕੜੇ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ ਤਾਂ ਜੋ ਹੱਦਾਂ ਵਿੱਚ ਰਹਿੰਦੇ ਹੋਏ ਕਾਫੀ ਸੰਦਰਭ ਦਿੱਤਾ ਜਾ ਸਕੇ ਜੋ ਸਹੀ ਜਵਾਬ ਲਈ ਜ਼ਰੂਰੀ ਹੈ। -## ਜਦ RAG ਮਹੱਤਵਪੂਰਣ ਹੈ +## ਜਦੋਂ RAG ਅਹਮ ਹੁੰਦਾ ਹੈ -RAG ਹਮੇਸ਼ਾ ਸਹੀ ਤਰੀਕਾ ਨਹੀਂ ਹੁੰਦਾ। ਹੇਠਾਂ ਦਿੱਤਾ ਫੈਸਲਾ ਗਾਈਡ ਤੁਹਾਡੇ ਲਈ ਇਹ ਤੈਅ ਕਰਦਾ ਹੈ ਕਿ ਕਦੋਂ RAG ਵਧੀਆ ਹੈ ਅਤੇ ਕਦੋਂ ਸਿੱਧੇ ਤੌਰ 'ਤੇ ਸਮੱਗਰੀ ਨੂੰ ਪ੍ਰਾਂਪਟ ਵਿਚ ਸ਼ਾਮਲ ਕਰਨਾ ਜਾਂ ਮਾਡਲ ਦੇ ਅੰਦਰੂਨੀ ਗਿਆਨ 'ਤੇ اعتماد ਕਰਨਾ ਕਾਫ਼ੀ ਹੈ: +RAG ਸਦਾ ਸਹੀ ਵਿਧੀ ਨਹੀਂ ਹੁੰਦੀ। ਹੇਠਾਂ ਦਿੱਤਾ ਗਇਆ ਫੈਸਲਾ ਮਦਦਗਾਰ ਹੈ ਇਹ ਨਿਰਧਾਰਿਤ ਕਰਨ ਲਈ ਕਿ RAG ਕਦੋਂ ਕਦਰ ਵਧਾਉਂਦਾ ਹੈ ਅਤੇ ਕਦੋਂ ਸਿੱਧਾ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਸਮੱਗਰੀ ਸ਼ਾਮਿਲ ਕਰਨ ਜਾਂ ਮਾਡਲ ਦੇ ਅੰਦਰੂਨੀ ਗਿਆਨ ਤੇ ਨਿਰਭਰ ਰਹਿਣਾ ਕਾਫੀ ਹੁੰਦਾ ਹੈ: -ਜਦੋਂ RAG ਵਰਤਣਾ ਚਾਹੀਦਾ ਹੈ +When to Use RAG -*ਇਹ ਆਕਰਸ਼ਣ ਇੱਕ ਫੈਸਲਾ ਗਾਈਡ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਕਦੋਂ RAG ਮੁੱਲ ਵਧਾਉਂਦਾ ਹੈ ਅਤੇ ਕਦੋਂ ਸਧਾਰਨ ਤਰੀਕੇ ਕਾਫ਼ੀ ਹੁੰਦੇ ਹਨ।* +*ਇਹ ਡਾਇਅਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਦੋਂ RAG ਵਧੀਆ ਹੈ ਅਤੇ ਕਦੋਂ ਸਧਾਰਨ ਤਰੀਕੇ ਕਾਫੀ ਹਨ।* -## ਅਗਲੇ ਕਦਮ +## ਅਗਲਾ ਕਦਮ -**ਅਗਲਾ ਮੋਡੀਊਲ:** [04-tools - ਟੂਲਜ਼ ਨਾਲ AI ਏਜੰਟ](../04-tools/README.md) +**ਅਗਲਾ ਮੋਡੀਊਲ:** [04-tools - ਟੂਲਜ਼ ਨਾਲ AI ਏਜੰਟ](../04-tools/README.md) --- -**ਨੈਵੀਗੇਸ਼ਨ:** [← ਪਹਿਲਾ: ਮੋਡੀਊਲ 02 - ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](../02-prompt-engineering/README.md) | [ਮੁੱਖ ਵਾਪਸ](../README.md) | [ਅਗਲਾ: ਮੋਡੀਊਲ 04 - ਟੂਲਜ਼ →](../04-tools/README.md) +**ਨੈਵੀਗੇਸ਼ਨ:** [← ਪਿਛਲਾ: ਮੋਡੀਊਲ 02 - ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](../02-prompt-engineering/README.md) | [ਮੁੱਖ ਪੰਨਾ](../README.md) | [ਅੱਗੇ: ਮੋਡੀਊਲ 04 - ਟੂਲਜ਼ →](../04-tools/README.md) --- -**ਅਸਪਸ਼ਟੀਕਰਨ**: -ਇਹ ਦਸਤਾਵੇਜ਼ AI ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਅਨੁਵਾਦ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਯਾਦ ਰੱਖੋ ਕਿ ਸੁਚਾਰੂ ਤੌਰ ‘ਤੇ ਬਣਾਈ ਗਈਆਂ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਵੀ ਗਲਤੀਆਂ ਜਾਂ ਅਸਪਸ਼ਟਤਾਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਇਸਦੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਹੀ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਮਹੱਤਵਪੂਰਨ ਜਾਣਕਾਰੀ ਲਈ, ਵਿਸ਼ੇਸ਼ਜ ਢੰਗ ਨਾਲ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫਾਰਿਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੇ ਉਪਯੋਗ ਨਾਲ ਪੈਦਾਵਾਰ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਭ੍ਰਮਾਂ ਲਈ ਜ਼ਿੰਮੇਵਾਰ ਨਹੀਂ ਹਾਂ। +**ਅਸਵੀਕਾਰੋਪਣ**: +ਇਸ ਦਸਤਾਵੇਜ਼ ਦਾ ਅਨੁਵਾਦ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾਵਾਂ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਮੱਤਿਆਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਜਰੂਰੀ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੇ ਉਪਯੋਗ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਗਲਤ ਵਿਆਖਿਆਵਾਂ ਲਈ ਜਵਾਬਦੇਹ ਨਹੀਂ ਹਾਂ। \ No newline at end of file diff --git a/translations/pa/04-tools/README.md b/translations/pa/04-tools/README.md index d4bb614f1..ac515d0ba 100644 --- a/translations/pa/04-tools/README.md +++ b/translations/pa/04-tools/README.md @@ -1,84 +1,84 @@ -# Module 04: AI Agents with Tools - -## Table of Contents - -- [Video Walkthrough](../../../04-tools) -- [What You'll Learn](../../../04-tools) -- [Prerequisites](../../../04-tools) -- [Understanding AI Agents with Tools](../../../04-tools) -- [How Tool Calling Works](../../../04-tools) - - [Tool Definitions](../../../04-tools) - - [Decision Making](../../../04-tools) - - [Execution](../../../04-tools) - - [Response Generation](../../../04-tools) - - [Architecture: Spring Boot Auto-Wiring](../../../04-tools) -- [Tool Chaining](../../../04-tools) -- [Run the Application](../../../04-tools) -- [Using the Application](../../../04-tools) - - [Try Simple Tool Usage](../../../04-tools) - - [Test Tool Chaining](../../../04-tools) - - [See Conversation Flow](../../../04-tools) - - [Experiment with Different Requests](../../../04-tools) -- [Key Concepts](../../../04-tools) - - [ReAct Pattern (Reasoning and Acting)](../../../04-tools) - - [Tool Descriptions Matter](../../../04-tools) - - [Session Management](../../../04-tools) - - [Error Handling](../../../04-tools) -- [Available Tools](../../../04-tools) -- [When to Use Tool-Based Agents](../../../04-tools) -- [Tools vs RAG](../../../04-tools) -- [Next Steps](../../../04-tools) - -## Video Walkthrough - -ਇਸ ਜੀਵੰਤ ਸੈਸ਼ਨ ਨੂੰ ਦੇਖੋ ਜੋ ਦੱਸਦਾ ਹੈ ਕਿ ਇਸ ਮੋਡੀਊਲ ਨਾਲ ਕਿਵੇਂ ਸ਼ੁਰੂਆਤ ਕਰਨੀ ਹੈ: +# ਮੋਡੀਊਲ 04: ਔਜ਼ਾਰਾਂ ਵਾਲੇ AI ਏਜੰਟ + +## ਸਮਗਰੀ ਦੀ ਸੂਚੀ + +- [ਵੀਡੀਓ ਵਾਕਥਰੂ](#ਵੀਡੀਓ-ਵਾਕਥਰੂ) +- [ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ](#ਤੁਸੀਂ-ਕੀ-ਸਿੱਖੋਗੇ) +- [ਪੂਰਵ ਸ਼ਰਤਾਂ](#ਪੂਰਵ-ਸ਼ਰਤਾਂ) +- [ਔਜ਼ਾਰਾਂ ਵਾਲੇ AI ਏਜੰਟ ਸਮਝਣਾ](#ਔਜ਼ਾਰਾਂ-ਵਾਲੇ-ai-ਏਜੰਟ-ਸਮਝਣਾ) +- [ਔਜ਼ਾਰ ਕਾਲਿੰਗ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ](#ਔਜ਼ਾਰ-ਕਾਲਿੰਗ-ਕਿਵੇਂ-ਕੰਮ-ਕਰਦੀ-ਹੈ) + - [ਔਜ਼ਾਰ ਪਰਿਭਾਸ਼ਾਵਾਂ](#ਔਜ਼ਾਰ-ਪਰਿਭਾਸ਼ਾਵਾਂ) + - [ਫੈਸਲਾ ਲੈਣਾ](#ਫੈਸਲਾ-ਲੈਣਾ) + - [ਕਾਰਜਾਨਵਣ](#ਕਾਰਜਾਨਵਣ) + - [ਪ੍ਰਤੀਕਿਰਿਆ ਬਣਾਉਣਾ](#ਪ੍ਰਤੀਕਿਰਿਆ-ਬਣਾਉਣਾ) + - [ਆਰਕੀਟੈਕਚਰ: ਸਪ੍ਰਿੰਗ ਬੂਟ ਆਟੋ-ਵਾਇਰਿੰਗ](#ਆਰਕੀਟੈਕਚਰ-ਸਪ੍ਰਿੰਗ-ਬੂਟ-ਆਟੋ-ਵਾਇਰਿੰਗ) +- [ਔਜ਼ਾਰ ਚੇਨਿੰਗ](#ਔਜ਼ਾਰ-ਚੇਨਿੰਗ) +- [ਐਪਲੀਕੇਸ਼ਨ ਚਲਾਉਣਾ](#ਐਪਲੀਕੇਸ਼ਨ-ਚਲਾਉਣਾ) +- [ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਵਰਤੋਂ](#ਐਪਲੀਕੇਸ਼ਨ-ਦੀ-ਵਰਤੋਂ) + - [ਸਰਲ ਔਜ਼ਾਰ ਵਰਤੋਂ ਟਰਾਈ ਕਰੋ](#ਸੌਖੇ-ਸੰਦ-ਦੀ-ਵਰਤੋਂ-آزਮਾਓ) + - [ਔਜ਼ਾਰ ਚੇਨਿੰਗ ਟੈਸਟ ਕਰੋ](#ਸੰਦਾਂ-ਦੀ-ਲੜੀਖੇਪ-ਦੀ-ਟੈਸਟਿੰਗ-ਕਰੋ) + - [ਗੱਲਬਾਤ ਦਾ ਪ੍ਰਵਾਹ ਵੇਖੋ](#ਗੱਲਬਾਤ-ਦਾ-ਪ੍ਰਵੇਹ-ਵੇਖੋ) + - [ਵੱਖ-ਵੱਖ ਬੇਨਤੀਆਂ ਨਾਲ ਪ੍ਰਯੋਗ ਕਰੋ](#ਵੱਖ-ਵੱਖ-ਬੇਨਤੀਆਂ-ਨਾਲ-ਪ੍ਰਯੋਗ-ਕਰੋ) +- [ਮੁੱਖ ਸੰਕਲਪ](#ਮੁੱਖ-ਧਾਰਾਵਾਂ) + - [ReAct ਪੈਟਰਨ (ਤਰਕ ਅਤੇ ਕਾਰਵਾਈ)](#react-ਪੈਟਰਨ-ਤਰੱਕੀ-ਅਤੇ-ਕਾਰਵਾਈ) + - [ਔਜ਼ਾਰ ਵੇਰਵੇ ਮਹੱਤਵਪੂਰਨ ਹਨ](#ਸੰਦਾਂ-ਦਾ-ਵਰਣਨ-ਮਹੱਤਵਪੂਰਨ-ਹੈ) + - [ਸੈਸ਼ਨ ਪ੍ਰਬੰਧਨ](#ਸੈਸ਼ਨ-ਪ੍ਰਬੰਧਨ) + - [ਗਲਤੀ ਸੰਭਾਲ](#ਗਲਤੀ-ਸੰਭਾਲਣਾ) +- [ਉਪਲਬਧ ਔਜ਼ਾਰ](#ਉਪਲੱਬਧ-ਸੰਦ) +- [ਕਦੋਂ ਔਜ਼ਾਰ-ਆਧਾਰਿਤ ਏਜੰਟ ਵਰਤਣੇ](#ਕਦੋਂ-ਸੰਦ-ਆਧਾਰਿਤ-ਏਜੰਟ-ਵਰਤਣੇ) +- [ਔਜ਼ਾਰਾਂ ਅਤੇ RAG ਦੇ ਵਿਚਕਾਰ](#ਸੰਦ-ਬਨਾਮ-rag) +- [ਅੱਗੇ ਕਦਮ](#ਅਗਲੇ-ਕਦਮ) + +## ਵੀਡੀਓ ਵਾਕਥਰੂ + +ਇਸ ਲਾਈਵ ਸੈਸ਼ਨ ਨੂੰ ਦੇਖੋ ਜੋ ਇਸ ਮੋਡੀਊਲ ਨਾਲ ਸ਼ੁਰੂਆਤ ਕਰਨ ਬਾਰੇ ਸਮਝਾਉਂਦਾ ਹੈ: AI Agents with Tools and MCP - Live Session -## What You'll Learn +## ਤੁਸੀਂ ਕੀ ਸਿੱਖੋਗੇ -ਹੁਣ ਤੱਕ, ਤੁਸੀਂ ਸਿੱਖਿਆ ਹੈ ਕਿ ਕਿਵੇਂ ਏਆਈ ਨਾਲ ਗੱਲਬਾਤ ਕਰਨੀ ਹੈ, ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਤਰੀਕੇ ਨਾਲ ਪ੍ਰਾਂਪਟ ਤਿਆਰ ਕਰਨੇ ਹਨ, ਅਤੇ ਆਪਣੇ ਦਸਤਾਵੇਜ਼ਾਂ ਵਿੱਚ ਜਵਾਬਾਂ ਨੂੰ ਅਧਾਰਿਤ ਕਰਨਾ ਹੈ। ਪਰ ਇੱਕ ਬੁਨਿਆਦੀ ਸੀਮਾ ਹੈ: ਭਾਸ਼ਾ ਮਾਡਲ ਸਿਰਫ ਟੈਕਸਟ ਹੀ ਬਣਾ ਸਕਦੇ ਹਨ। ਉਹ ਮੌਸਮ ਜਾਂਚ ਨਹੀਂ ਕਰ ਸਕਦੇ, ਗਣਨਾ ਨਹੀਂ ਕਰ ਸਕਦੇ, ਡੇਟਾਬੇਸਾਂ ਨੂੰ ਕਵੈਰੀ ਨਹੀਂ ਕਰ ਸਕਦੇ, ਜਾਂ ਬਾਹਰੀ ਸਿਸਟਮਾਂ ਨਾਲ ਵਪਾਰ ਨਹੀਂ ਕਰ ਸਕਦੇ। +ਇਸ ਤੱਕ, ਤੁਸੀਂ ਸਿੱਖਿਆ ਹੈ ਕਿ AI ਨਾਲ ਗੱਲਬਾਤ ਕਿਵੇਂ ਕਰਨੀ ਹੈ, ਪ੍ਰਾਂਪਟ ਨੂੰ ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਢੰਗ ਨਾਲ ਬਣਾਉਣਾ ਅਤੇ ਆਪਣੇ ਦਸਤਾਵੇਜ਼ਾਂ 'ਚ ਜਵਾਬਾਂ ਨੂੰ ਅਧਾਰਿਤ ਕਰਨਾ। ਪਰ ਇੱਕ ਮੂਲ ਸੀਮਾ ਹੁਣ ਵੀ ਮੌਜੂਦ ਹੈ: ਭਾਸ਼ਾ ਮਾਡਲ ਸਿਰਫ ਲਿਖਤ ਤਿਆਰ ਕਰ ਸਕਦੇ ਹਨ। ਇਹ ਮੌਸਮ ਜਾਂਚ ਨਹੀਂ ਕਰ ਸਕਦੇ, ਗਣਨਾ ਨਹੀਂ ਕਰ ਸਕਦੇ, ਡਾਟਾਬੇਸਾਂ ਦਾ ਪੁੱਛ-ਗਿੱਛ ਨਹੀਂ ਕਰ ਸਕਦੇ ਜਾਂ ਬਾਹਰੀ ਸਿਸਟਮਾਂ ਨਾਲ ਸੰਚਾਰ ਨਹੀਂ ਕਰ ਸਕਦੇ। -ਓਜ਼ਾਰ ਇਸਨੂੰ ਬਦਲ ਦਿੰਦੇ ਹਨ। ਮਾਡਲ ਨੂੰ ਫੰਕਸ਼ਨਾਂ ਤੱਕ ਪਹੁੰਚ ਦੇ ਕੇ ਜਿਸਨੂੰ ਇਹ ਕਾਲ ਕਰ ਸਕਦਾ ਹੈ, ਤੁਸੀਂ ਇਸਨੂੰ ਇੱਕ ਟੈਕਸਟ ਜਨਰੇਟਰ ਤੋਂ ਇੱਕ ਐਜੈਂਟ ਵਿੱਚ ਬਦਲ ਦਿੰਦੇ ਹੋ ਜੋ ਕਾਰਵਾਈ ਕਰ ਸਕਦਾ ਹੈ। ਮਾਡਲ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕਦੋਂ ਇਸਨੂੰ ਔਜ਼ਾਰ ਦੀ ਲੋੜ ਹੈ, ਕਿਹੜਾ ਟੂਲ ਵਰਤਣਾ ਹੈ, ਅਤੇ ਕਿਹੜੇ ਪੈਰਾਮੀਟਰ ਭੇਜਣੇ ਹਨ। ਤੁਹਾਡਾ ਕੋਡ ਉਸ ਫੰਕਸ਼ਨ ਨੂੰ ਚਲਾਉਂਦਾ ਹੈ ਅਤੇ ਨਤੀਜਾ ਵਾਪਸ ਕਰਦਾ ਹੈ। ਮਾਡਲ ਉਸ ਨਤੀਜੇ ਨੂੰ ਆਪਣੇ ਜਵਾਬ ਵਿੱਚ ਸ਼ਾਮਲ ਕਰ ਲੈਂਦਾ ਹੈ। +ਔਜ਼ਾਰ ਇਸ ਨੂੰ ਬਦਲਦੇ ਹਨ। ਮਾਡਲ ਨੂੰ ਫੰਕਸ਼ਨਾਂ ਤੱਕ ਪਹੁੰਚ ਦੇ ਕੇ ਜੋ ਇਹ ਕਾਲ ਕਰ ਸਕਦਾ ਹੈ, ਤੁਸੀਂ ਇਸ ਨੂੰ ਲਿਖਤ ਜਨਰੇਟਰ ਤੋਂ ਇੱਕ ਏਜੰਟ ਵਿਚ ਬਦਲ ਦਿੰਦੇ ਹੋ ਜੋ ਕਾਰਵਾਈ ਕਰ ਸਕਦਾ ਹੈ। ਮਾਡਲ ਫ਼ੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕਿਸ ਵੇਲੇ ਔਜ਼ਾਰ ਚਾਹੀਦਾ ਹੈ, ਕਿਹੜਾ ਔਜ਼ਾਰ ਵਰਤਣਾ ਹੈ, ਅਤੇ ਕਿਹੜੇ ਪੈਰਾਮੀਟਰ ਦਿੱਤੇ ਜਾਣ। ਤੁਹਾਡੇ ਕੋਡ ਨੇ ਫੰਕਸ਼ਨ ਨੂੰ ਚਲਾਉਂਦਾ ਹੈ ਅਤੇ ਨਤੀਜਾ ਵਾਪਸ ਕਰਦਾ ਹੈ। ਮਾਡਲ ਉਸ ਨਤੀਜੇ ਨੂੰ ਆਪਣੇ ਜਵਾਬ ਵਿੱਚ ਸ਼ਾਮِل ਕਰਦਾ ਹੈ। -## Prerequisites +## ਪੂਰਵ ਸ਼ਰਤਾਂ -- ਮੁਕੰਮਲ ਕੀਤਾ [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI ਸਰੋਤ ਤਿਆਰ ਹੋਏ) -- ਪਿਛਲੇ ਮੋਡੀਊਲ ਦੀ ਸਿਫਾਰਸ਼ ਕੀਤੀ ਗਈ ਹੈ (ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ ਟੂਲਜ਼ ਵਿਰੁੱਧ RAG ਮੁਕਾਬਲੇ ਵਿੱਚ [Module 03 ਦੇ RAG ਔਰ ਸਿਧਾਂਤ](../03-rag/README.md) ਦਾ ਹਵਾਲਾ ਹੈ) -- ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ `.env` ਫਾਈਲ Azure ਪ੍ਰਮਾਣਿਕਤਾ ਨਾਲ (Module 01 ਵਿੱਚ `azd up` ਦੁਆਰਾ ਬਣਾਈ ਗਈ) +- [ਮੋਡੀਊਲ 01 - ਪ੍ਰਾਰੰਭਿਕ ਜਾਣਕਾਰੀ](../01-introduction/README.md) ਪੂਰਾ ਕੀਤਾ ਹੋਇਆ (ਐਜ਼ੂਰ OpenAI ਸਰੋਤ ਤਿਆਰ ਕੀਤੇ ਹੋਏ) +- ਪਹਿਲਾਂ ਦੇ ਮੋਡੀਊਲ ਪੂਰੇ ਹੋਏ, ਜੋ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੇ ਗਏ ਹਨ (ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ ਔਜ਼ਾਰਾਂ ਅਤੇ RAG ਤੁਲਨਾ ਵਿੱਚ [ਮੋਡੀਊਲ 03 ਤੋਂ RAG ਸੰਕਲਪ](../03-rag/README.md) ਦਾ ਹਵਾਲਾ ਹੈ) +- ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ `.env` ਫਾਇਲ ਐਜ਼ੂਰ ਪ੍ਰਮਾਣ ਪੱਤਰਾਂ ਨਾਲ (ਮੋਡੀਊਲ 01 ਵਿੱਚ `azd up` ਦੁਆਰਾ ਬਣਾਈ ਗਈ) -> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ Module 01 ਮੁਕੰਮਲ ਨਹੀਂ ਕੀਤਾ, ਪਹਿਲਾਂ ਉਥੇ ਦਿੱਤੇ ਡਿਪਲੋਇਮੈਂਟ ਦਿਸ਼ਾ-ਨਿਰਦੇਸ਼ਾਂ ਦੇ ਪਾਲਣ ਕਰੋ। +> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਮੋਡੀਊਲ 01 ਨਹੀਂ ਕੀਤਾ, ਤਾਂ ਪਹਿਲਾਂ ਉੱਥੇ ਦਿੱਤੇ ਗਏ ਤੈਅਕਰਨ ਨਿਰਦੇਸ਼ਾਂ ਦੀ ਪਾਲਣਾ ਕਰੋ। -## Understanding AI Agents with Tools +## ਔਜ਼ਾਰਾਂ ਵਾਲੇ AI ਏਜੰਟ ਸਮਝਣਾ -> **📝 ਨੋਟ:** ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ "ਏਜੈਂਟ" ਸ਼ਬਦ ਦਾ ਅਰਥ ਹੈ ਉਹ AI ਸਹਾਇਕ ਜੋ ਟੂਲ ਕਾਲ ਕਰਨ ਵਾਲੀਆਂ ਯੋਗਤਾਵਾਂ ਨਾਲ ਵਧਾਏ ਗਏ ਹਨ। ਇਹ ਭਿੰਨ ਹੈ ਉਹਨਾਂ **Agentic AI** ਪੈਟਰਨਾਂ ਤੋਂ (ਆਟੋਨੋਮਸ ਏਜੈਂਟ, ਜੋ ਯੋਜਨਾ, ਯਾਦ, ਅਤੇ ਕਈ ਕਦਮ ਵਾਲੀ ਸੋਚ ਸਮੇਤ ਹਨ) ਜੋ ਅਸੀਂ [Module 05: MCP](../05-mcp/README.md) ਵਿੱਚ ਕਵਰ ਕਰਾਂਗੇ। +> **📝 ਨੋਟ:** ਇਸ ਮੋਡੀਊਲ ਵਿੱਚ "ਏਜੰਟ" ਸ਼ਬਦ ਉਹ AI ਸਹਾਇਕ ਹਨ ਜਿਹੜੇ ਔਜ਼ਾਰ ਕਾਲ ਕਰਨ ਵਾਲੀ ਸਮਰੱਥਾ ਨਾਲ ਬੜ੍ਹਾਏ ਗਏ ਹਨ। ਇਹ ਉਸ ਤੋਂ ਵੱਖਰਾ ਹੈ ਜੋ ਅਸੀਂ [ਮੋਡੀਊਲ 05: MCP](../05-mcp/README.md) ਵਿੱਚ ਕਵਰ ਕਰਾਂਗੇ — "ਏਜੰਟਿਕ AI" ਪੈਟਰਨ (ਆਤਮਨਿਰਭਰ ਏਜੰਟ ਜਿਸ ਵਿੱਚ ਯੋਜਨਾ, ਯਾਦ, ਅਤੇ ਬਹੁ-ਕਦਮੀ ਤਰਕ ਸ਼ਾਮਿਲ ਹੈ)। -ਬਿਨਾਂ ਔਜ਼ਾਰਾਂ ਦੇ, ਇੱਕ ਭਾਸ਼ਾ ਮਾਡਲ ਸਿਰਫ ਆਪਣੇ ਟ੍ਰੇਨਿੰਗ ਡੇਟਾ ਤੋਂ ਟੈਕਸਟ ਤਿਆਰ ਕਰ ਸਕਦਾ ਹੈ। ਮੌਜੂਦਾ ਮੌਸਮ ਬਾਰੇ ਪੁੱਛੋ, ਤਾਂ ਇਹ ਅਨੁਮਾਨ ਲਗਾਉਂਦਾ ਹੈ। ਇਸਨੂੰ ਟੂਲ ਤੇ ਦਿਓ, ਤਾਂ ਇਹ ਮੌਸਮ API ਕਾਲ ਕਰ ਸਕਦਾ ਹੈ, ਗਣਨਾ ਕਰ ਸਕਦਾ ਹੈ, ਜਾਂ ਡੇਟਾਬੇਸ ਕਵੈਰੀ ਕਰ ਸਕਦਾ ਹੈ — ਅਤੇ ਫਿਰ ਉਹ ਅਸਲੀ ਨਤੀਜੇ ਆਪਣੇ ਜਵਾਬ ਵਿੱਚ ਜੋੜਦਾ ਹੈ। +ਬਿਨਾਂ ਔਜ਼ਾਰਾਂ ਦੇ, ਭਾਸ਼ਾ ਮਾਡਲ ਸਿਰਫ ਆਪਣੀ ਸਿਖਲਾਈ ਡਾਟਾ ਵਿੱਚੋਂ ਲਿਖਤ ਤਿਆਰ ਕਰ ਸਕਦਾ ਹੈ। ਮੌਜੂਦਾ ਮੌਸਮ ਬਾਰੇ ਪੁੱਛੋ, ਤਾਂ ਇਹ ਅੰਦਾਜ਼ਾ ਲੱਗਾਉਂਦਾ ਹੈ। ਪਰ ਜੇ ਤੁਸੀਂ ਇਸ ਨੂੰ ਔਜ਼ਾਰ ਦਿੰਦੇ ਹੋ, ਤਾਂ ਇਹ ਮੌਸਮ API ਕਾਲ ਕਰ ਸਕਦਾ ਹੈ, ਗਣਨਾ ਕਰ ਸਕਦਾ ਹੈ, ਜਾਂ ਡਾਟਾਬੇਸ ਨੂੰ ਪੁੱਛ ਸਕਦਾ ਹੈ — ਫਿਰ ਉਹ ਅਸਲੀ ਨਤੀਜੇ ਆਪਣੇ ਜਵਾਬ ਵਿੱਚ ਗੂੰਦਦਾ ਹੈ। Without Tools vs With Tools -*ਬਿਨਾਂ ਟੂਲਾਂ ਦੇ ਮਾਡਲ ਸਿਰਫ ਅਨੁਮਾਨ ਲਗਾ ਸਕਦਾ ਹੈ — ਟੂਲਾਂ ਨਾਲ ਇਹ API ਕਾਲ ਕਰਦਾ ਹੈ, ਗਣਨਾ ਕਰਦਾ ਹੈ, ਅਤੇ ਤਾਜ਼ਾ ਡਾਟਾ ਵਾਪਸ ਦਿੰਦਾ ਹੈ।* +*ਬਿਨਾਂ ਔਜ਼ਾਰਾਂ ਦੇ ਮਾਡਲ ਸਿਰਫ ਅੰਦਾਜ਼ਾ ਲਗਾ ਸਕਦਾ ਹੈ — ਔਜ਼ਾਰਾਂ ਨਾਲ ਇਹ API ਕਾਲ ਕਰ ਸਕਦਾ ਹੈ, ਗਣਤੀਆਂ ਚਲਾ ਸਕਦਾ ਹੈ ਅਤੇ ਹਕੀਕਤੀ ਸਮਾਂ ਡਾਟਾ ਵਾਪਸ ਕਰ ਸਕਦਾ ਹੈ।* -ਟੂਲਜ਼ ਵਾਲਾ ਏਆਈ ਏਜੈਂਟ ਇੱਕ **Reasoning and Acting (ReAct)** ਪੈਟਰਨ ਨੂੰ ਫਾਲੋ ਕਰਦਾ ਹੈ। ਮਾਡਲ ਸਿਰਫ ਜਵਾਬ ਨਹੀਂ ਦਿੰਦਾ — ਇਹ ਸੋਚਦਾ ਹੈ ਕਿ ਉਸਨੂੰ ਕੀ ਚਾਹੀਦਾ ਹੈ, ਟੂਲ ਕਾਲ ਕਰਕੇ ਕਾਰਵਾਈ ਕਰਦਾ ਹੈ, ਨਤੀਜੇ ਦਾ ਨਿਰੀਖਣ ਕਰਦਾ ਹੈ, ਅਤੇ ਫਿਰ ਇਹ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਦੁਬਾਰਾ ਕਾਰਵਾਈ ਕਰਨੀ ਹੈ ਜਾਂ ਅਸਲ ਜਵਾਬ ਦੇਣਾ ਹੈ: +ਔਜ਼ਾਰਾਂ ਵਾਲਾ AI ਏਜੰਟ ਇੱਕ **ਤਰਕਸ਼ੀਲ ਅਤੇ ਕਾਰਵਾਈ (ReAct)** ਪੈਟਰਨ ਨੂੰ ਫਾਲੋ ਕਰਦਾ ਹੈ। ਮਾਡਲ ਸਿਰਫ ਜਵਾਬ ਨਹੀਂ ਦਿੰਦਾ — ਇਹ ਸੋਚਦਾ ਹੈ ਕਿ ਉਸਨੂੰ ਕੀ ਚਾਹੀਦਾ ਹੈ, ਕੰਮ ਕਰਦਾ ਹੈ ਔਜ਼ਾਰ ਕਾਲ ਕਰਕੇ, ਨਤੀਜਾ ਦੇਖਦਾ ਹੈ, ਅਤੇ ਫਿਰ ਫ਼ੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਦੁਬਾਰਾ ਕਾਰਵਾਈ ਕਰਨੀ ਹੈ ਜਾਂ ਅੰਤਿਮ ਜਵਾਬ ਦੇਣਾ ਹੈ: -1. **Reason** — ਏਜੈਂਟ ਉਪਭੋਗਤਾ ਦੇ ਸਵਾਲ ਨੂੰ ਵਿਸ਼ਲੇਸ਼ਣ ਕਰਦਾ ਹੈ ਅਤੇ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਇਸਨੂੰ ਕਿਹੜੀ ਜਾਣਕਾਰੀ ਦੀ ਲੋੜ ਹੈ -2. **Act** — ਏਜੈਂਟ ਸਹੀ ਟੂਲ ਚੁਣਦਾ ਹੈ, ਸਹੀ ਪੈਰਾਮੀਟਰ ਤਿਆਰ ਕਰਦਾ ਹੈ, ਅਤੇ ਉਸਨੂੰ ਕਾਲ ਕਰਦਾ ਹੈ -3. **Observe** — ਏਜੈਂਟ ਟੂਲ ਦੇ ਨਤੀਜੇ ਨੂੰ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ ਅਤੇ ਉਸਦਾ ਮੁਲਾਂਕਣ ਕਰਦਾ ਹੈ -4. **Repeat or Respond** — ਜੇ ਹੋਰ ਡਾਟਾ ਦੀ ਲੋੜ ਹੈ, ਤਾਂ ਏਜੈਂਟ ਵਾਪਸ ਚੱਕਰ ਲਾਉਂਦਾ ਹੈ; ਨਹੀਂ ਤਾਂ ਇਕ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਵਿਚ ਜਵਾਬ ਦਿੰਦਾ ਹੈ +1. **ਤਰਕਸ਼ੀਲਤਾ** — ਏਜੰਟ ਯੂਜ਼ਰ ਦੇ ਸਵਾਲ ਦੀ ਵਿਸ਼ਲੇਸ਼ਣਾ ਕਰਦਾ ਹੈ ਅਤੇ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕੀ ਜਾਣਕਾਰੀ ਚਾਹੀਦੀ ਹੈ +2. **ਕਾਰਵਾਈ** — ਏਜੰਟ ਸਹੀ ਔਜ਼ਾਰ ਚੁਣਦਾ ਹੈ, ਸਹੀ ਪੈਰਾਮੀਟਰ ਤਿਆਰ ਕਰਦਾ ਹੈ ਅਤੇ ਉਸਨੂੰ ਕਾਲ ਕਰਦਾ ਹੈ +3. **ਅਵਲੋਕਨ** — ਏਜੰਟ ਔਜ਼ਾਰ ਦਾ ਨਤੀਜਾ ਲੈਂਦਾ ਹੈ ਅਤੇ ਉਸਦੀ ਮੁਲਾਂਕਣ ਕਰਦਾ ਹੈ +4. **ਦੋਹਰਾਵਟ ਜਾਂ ਜਵਾਬ** — ਹੋਰ ਡਾਟਾ ਚਾਹੀਦਾ ਹੋਵੇ ਤਾਂ ਲੂਪ ਵਾਪਸ ਕਰਦਾ ਹੈ, ਨਹੀਂ ਤਾਂ ਫਿਰ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਦਾ ਜਵਾਬ ਤਿਆਰ ਕਰਦਾ ਹੈ ReAct Pattern -*ReAct ਚੱਕਰ — ਏਜੈਂਟ ਸੋਚਦਾ ਹੈ ਕਿ ਕੀ ਕਰਨਾ ਹੈ, ਟੂਲ ਕਾਲ ਕਰਕੇ ਅਮਲ ਕਰਦਾ ਹੈ, ਨਤੀਜਾ ਵੇਖਦਾ ਹੈ, ਅਤੇ ਆਖਰੀ ਜਵਾਬ ਦੇਣ ਤੱਕ ਚੱਕਰ ਲਾਉਂਦਾ ਹੈ।* +*ReAct ਚਕਰ — ਏਜੰਟ ਸੋਚਦਾ ਹੈ ਕਿ ਕੀ ਕਰਨਾ ਹੈ, ਔਜ਼ਾਰ ਕਾਲ ਕਰਕੇ ਕਾਰਵਾਈ ਕਰਦਾ ਹੈ, ਨਤੀਜਾ ਵੇਖਦਾ ਹੈ, ਅਤੇ ਲੂਪ ਕਰਦਾ ਹੈ ਜਦ ਤੱਕ ਅੰਤਿਮ ਜਵਾਬ ਦੇ ਸਕੇ।* -ਇਹ ਸਾਰਾ ਪ੍ਰਕਿਰਿਆ ਖੁਦਕਾਰ ਹੈ। ਤੁਸੀਂ ਟੂਲਜ਼ ਅਤੇ ਉਹਨਾਂ ਦੀ ਵਿਆਖਿਆ ਨੂੰ ਪਰਿਭਾਸ਼ਿਤ ਕਰਦੇ ਹੋ। ਮਾਡਲ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਟੂਲ ਕਿਸ ਤਰ੍ਹਾਂ ਤੇ ਕਦੋਂ ਵਰਤਣਾ ਹੈ। +ਇਹ ਸਾਰਾ ਪ੍ਰਕਿਰਿਆ ਸਵੈਚਾਲਿਤ ਹੁੰਦੀ ਹੈ। ਤੁਸੀਂ ਔਜ਼ਾਰਾਂ ਅਤੇ ਉਹਨਾਂ ਦੇ ਵੇਰਵੇ ਤਿਆਰ ਕਰਦੇ ਹੋ। ਮਾਡਲ ਇਹ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕਦੋਂ ਤੇ ਕਿਵੇਂ ਉਨ੍ਹਾਂ ਨੂੰ ਵਰਤਣਾ ਹੈ। -## How Tool Calling Works +## ਔਜ਼ਾਰ ਕਾਲਿੰਗ ਕਿਵੇਂ ਕੰਮ ਕਰਦੀ ਹੈ -### Tool Definitions +### ਔਜ਼ਾਰ ਪਰਿਭਾਸ਼ਾਵਾਂ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -ਤੁਸੀਂ ਫੰਕਸ਼ਨਾਂ ਨੂੰ ਸਾਫ ਵਿਆਖਿਆਵਾਂ ਅਤੇ ਪੈਰਾਮੀਟਰ ਸਪੈਕਿਫਿਕੇਸ਼ਨ ਨਾਲ ਪਰਿਭਾਸ਼ਿਤ ਕਰਦੇ ਹੋ। ਮਾਡਲ ਆਪਣੀ ਸਿਸਟਮ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਇਹ ਵਿਆਖਿਆਵਾਂ ਵੇਖਦਾ ਹੈ ਅਤੇ ਸਮਝਦਾ ਹੈ ਕਿ ਹਰ ਟੂਲ ਕੀ ਕਰਦਾ ਹੈ। +ਤੁਸੀਂ ਫੰਕਸ਼ਨਾਂ ਨੂੰ ਸਾਫ਼-ਸੁਥਰੇ ਵੇਰਵਿਆਂ ਅਤੇ ਪੈਰਾਮੀਟਰ ਨਿਰਧਾਰਣਾਂ ਦੇ ਨਾਲ ਪਰਿਭਾਸ਼ਿਤ ਕਰਦੇ ਹੋ। ਮਾਡਲ ਇਹ ਵੇਰਵੇ ਆਪਣੀ ਸਿਸਟਮ ਪ੍ਰਾਂਪਟ ਵਿੱਚ ਵੇਖਦਾ ਹੈ ਅਤੇ ਸਮਝਦਾ ਹੈ ਕਿ ਹਰ ਇੱਕ ਔਜ਼ਾਰ ਕੀ ਕਰਦਾ ਹੈ। ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // ਤੁਹਾਡੀ ਮੌਸਮ ਲੁੱਕਅੱਪ ਲੋਜਿਕ + // ਤੁਹਾਡਾ ਮੌਸਮ ਲੁੱਕਅਪ ਲੋਜਿਕ return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,177 +96,177 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// ਸਹਾਇਕ ਸਵੈਚਲਿਤ ਤੌਰ 'ਤੇ Spring Boot ਨਾਲ ਵਾਇਰ ਕੀਤਾ ਜਾਂਦਾ ਹੈ: -// - ChatModel ਬੀਨ -// - ਸਾਰੇ @Tool ਮੇਥਡ @Component ਕਲਾਸਾਂ ਤੋਂ -// - ਸੈਸ਼ਨ ਪ੍ਰਬੰਧਨ ਲਈ ChatMemoryProvider +// ਸਹਾਇਕ ਆਪੋ-ਆਪਣੇ ਸਪ੍ਰਿੰਗ ਬੂਟ ਨਾਲ ਜੁੜਿਆ ਹੁੰਦਾ ਹੈ: +// - ਚੈਟਮੌਡਲ ਬੀਨ +// - ਸਾਰੇ @Component ਕਲਾਸਾਂ ਤੋਂ @Tool ਵਿਧੀਆਂ +// - ਸੈਸ਼ਨ ਪ੍ਰਬੰਧਨ ਲਈ ChatMemoryProvider ``` -ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਯਾਗ੍ਰਾਮ ਹਰ ਐਨੋਟੇਸ਼ਨ ਨੂੰ ਵੇਖਾਉਂਦਾ ਹੈ ਅਤੇ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਹਰ ਹਿੱਸਾ AI ਨੂੰ ਟੂਲ ਕਦੋਂ ਕਾਲ ਕਰਨਾ ਹੈ ਅਤੇ ਕਿਹੜੇ ਤਰਕ ਭੇਜਣੇ ਹਨ ਇਹ ਸਮਝਣ ਵਿੱਚ ਕਿਵੇਂ ਮਦਦ ਕਰਦਾ ਹੈ: +ਹੇਠਾਂ ਦਿੱਤਾ ਚਿੱਤਰ ਉਨ੍ਹਾਂ ਹਰ ਇਸ਼ਾਰੇ ਨੂੰ ਵੰਡਦਾ ਹੈ ਅਤੇ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਹਰ ਹਿੱਸਾ AI ਨੂੰ ਕਿਵੇਂ ਸਮਝਾਉਂਦਾ ਹੈ ਕਿ ਕਦੋਂ ਔਜ਼ਾਰ ਕਾਲ ਕਰਨਾ ਹੈ ਅਤੇ ਕਿਹੜੇ ਆਰਗੁਮੈਂਟ ਪਾਸ ਕਰਨੇ ਹਨ: Anatomy of Tool Definitions -*ਟੂਲ ਡਿਫਿਨੀਸ਼ਨ ਦੀ ਬਣਤਰ — @Tool AI ਨੂੰ ਦੱਸਦਾ ਹੈ ਕਿ ਕਦੋਂ ਇਸਨੂੰ ਵਰਤਣਾ ਹੈ, @P ਹਰ ਪੈਰਾਮੀਟਰ ਨੂੰ ਵੇਖਾਉਂਦਾ ਹੈ, ਅਤੇ @AiService ਸ਼ੁਰੂਆਤੀ ਸਮੇਂ ਸਾਰਾ ਕੁਝ ਜੋੜਦਾ ਹੈ।* +*ਔਜ਼ਾਰ ਪਰਿਭਾਸ਼ਾ ਦਾ ਡਾਂਚਾ — @Tool AI ਨੂੰ ਦੱਸਦਾ ਹੈ ਕਦੋਂ ਇਸਨੂੰ ਵਰਤਣਾ ਹੈ, @P ਹਰ ਪੈਰਾਮੀਟਰ ਨੂੰ ਵੇਖਾਉਂਦਾ ਹੈ, ਅਤੇ @AiService ਸਾਰਾ ਕੁਝ ਸਟਾਰਟਅਪ 'ਤੇ ਜੋੜਦਾ ਹੈ।* > **🤖 [GitHub Copilot](https://github.com/features/copilot) ਚੈਟ ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "ਮੈਂ ਮૉਕ ਡੇਟਾ ਦੀ ਜਗ੍ਹਾ ਕਿਸ ਤਰ੍ਹਾਂ ਅਸਲ ਵੇਦਰ API ਜਿਵੇਂ OpenWeatherMap ਨੂੰ ਜੋੜਾਂ?" -> - "ਇੱਕ ਚੰਗੀ ਟੂਲ ਵੇਰਵਾ ਕੀ ਹੈ ਜੋ AI ਨੂੰ ਇਸਦੀ ਸਹੀ ਵਰਤੋਂ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ?" -> - "ਟੂਲ ਤੇ ਛੁੱਟਣ ਵਾਲੀਆਂ API ਗਲਤੀਆਂ ਅਤੇ ਰੇਟ ਲਿਮਿਟਾਂ ਦਾ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਸੰਭਾਲ ਕਿਵੇਂ ਕਰੀਏ?" +> - "ਮੈਂ ਕਿਵੇਂ ਮੌਸਮ ਲਈ ਅਸਲ OpenWeatherMap API ਨੂੰ ਮੌਕ ਡਾਟਾ ਦੀ ਥਾਂ ਇੰਟਿਗ੍ਰੇਟ ਕਰਾਂ?" +> - "ਇੱਕ ਚੰਗਾ ਔਜ਼ਾਰ ਵੇਰਵਾ ਕੀ ਹੈ ਜੋ AI ਨੂੰ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਵਰਤਣ ਵਿੱਚ ਮਦਦ ਕਰਦਾ ਹੈ?" +> - "ਮੈਂ ਔਜ਼ਾਰ ਵਿਚ API ਗਲਤੀਆਂ ਅਤੇ ਦਰ ਸੀਮਾਵਾਂ ਨੂੰ ਕਿਵੇਂ ਸੰਭਾਲਾਂ?" -### Decision Making +### ਫੈਸਲਾ ਲੈਣਾ -ਜਦੋਂ ਯੂਜ਼ਰ ਪੁੱਛਦਾ ਹੈ "ਸੀਅਟਲ ਵਿੱਚ ਮੌਸਮ ਕਿਵੇਂ ਹੈ?", ਮਾਡਲ ਬੇਤਰਤੀਬੀ ਨਾਲ ਕੋਈ ਟੂਲ ਨਹੀਂ ਚੁਣਦਾ। ਇਹ ਯੂਜ਼ਰ ਦੀ ਇरਾਦਾ ਦੀ ਤੁਲਨਾ ਸਭ ਟੂਲ ਦੀਆਂ ਵਿਆਖਿਆਵਾਂ ਨਾਲ ਕਰਦਾ ਹੈ ਜੋ ਇਸਨੂੰ ਉਪਲਬਧ ਹਨ, ਹਰ ਇੱਕ ਲਈ ਲਾਗੂਪਨ ਦੇ ਅੰਕ ਮਪਦਾ ਹੈ, ਅਤੇ ਵਧੀਆ ਮੇਲ ਚੁਣਦਾ ਹੈ। ਫਿਰ ਇਹ ਸਹੀ ਪੈਰਾਮੀਟਰਾਂ ਨਾਲ ਸਰਚਿੰਨ ਫੰਕਸ਼ਨ ਕਾਲ ਬਣਾਉਂਦਾ ਹੈ — ਇਸ ਮਾਮਲੇ ਵਿੱਚ `location` ਨੂੰ `"Seattle"` ਸੈਟ ਕਰਦਾ ਹੈ। +ਜਦੋਂ ਯੂਜ਼ਰ ਪੁੱਛਦਾ ਹੈ "ਸੀਅਟਲ ਵਿੱਚ ਮੌਸਮ ਕੀ ਹੈ?", ਮਾਡਲ ਬੇਤਕਲੀਫ਼ੀ ਨਾਲ ਕੋਈ ਔਜ਼ਾਰ ਨਹੀਂ ਚੁਣਦਾ। ਇਹ ਯੂਜ਼ਰ ਦੇ ਮਨਸੂਬੇ ਦੀ ਤੁਲਨਾ ਹਰ ਇੱਕ ਔਜ਼ਾਰ ਦੇ ਵੇਰਵੇ ਨਾਲ ਕਰਦਾ ਹੈ ਜੋ ਉਸਨੂੰ ਮਿਲਦਾ ਹੈ, ਹਰ ਇੱਕ ਦੀ ਸੰਬੰਧਿਤਤਾ ਅਨੁਸਾਰ ਸਕੋਰ ਕਰਦਾ ਹੈ, ਅਤੇ ਸਭ ਤੋਂ ਵਧੀਆ ਹੀ ਚੁਣਦਾ ਹੈ। ਫਿਰ ਇਹ ਸਹੀ ਪੈਰਾਮੀਟਰਾਂ ਨਾਲ ਮਿਲ ਕੇ ਇੱਕ ਸੰਰਚਿਤ ਫੰਕਸ਼ਨ ਕਾਲ ਬਣਾਉਂਦਾ ਹੈ — ਇਸ ਮਾਮਲੇ ਵਿੱਚ, `location` ਨੂੰ `"Seattle"` ਸੈੱਟ ਕਰਦਾ ਹੈ। -ਜੇ ਕਿਸੇ ਵੀ ਟੂਲ ਦਾ ਯੂਜ਼ਰ ਦੀ ਲੋੜ ਨਾਲ ਮੇਲ ਨਹੀਂ ਬਠਦਾ, ਤਾਂ ਮਾਡਲ ਆਪਣੀ ਜਾਣਕਾਰੀ ਤੋਂ ਜਵਾਬ ਦੇਦਾ ਹੈ। ਜੇ ਕਈ ਟੂਲ ਮੇਲ ਖਾਂਦੇ ਹਨ, ਤਾਂ ਸਭ ਤੋਂ ਵਿਸ਼ੇਸ਼ ਟੂਲ ਚੁਣਦਾ ਹੈ। +ਜੇ ਕੋਈ ਔਜ਼ਾਰ ਯੂਜ਼ਰ ਦੀ ਬੇਨਤੀ ਨਾਲ ਮਿਲਦਾ ਨਹੀਂ, ਤਾਂ ਮਾਡਲ ਆਪਣੇ ਗਿਆਨ ਤੋਂ ਜਵਾਬ ਦਿੰਦਾ ਹੈ। ਜੇ ਕਈ ਔਜ਼ਾਰ ਮਿਲਦੇ ਹਨ, ਮਾਡਲ ਸਭ ਤੋਂ ਖਾਸ ਉਪਯੋਗ ਚੁਣਦਾ ਹੈ। How the AI Decides Which Tool to Use -*ਮਾਡਲ ਹਰ ਉਪਲਬਧ ਟੂਲ ਨੂੰ ਯੂਜ਼ਰ ਦੀ ਇਰਾਦੇ ਨਾਲ ਤੁਲਨਾ ਕਰਦਾ ਹੈ ਅਤੇ ਵਧੀਆ ਮੇਲ ਚੁਣਦਾ ਹੈ — ਇਸ ਲਈ ਸਾਫ਼, ਵਿਸ਼ੇਸ਼ ਟੂਲ ਵੇਰਵਿਆਂ ਦੀ ਲਿਖਾਈ ਮਹੱਤਵਪੂਰਨ ਹੈ।* +*ਮਾਡਲ ਹਰ ਉਪਲਬਧ ਔਜ਼ਾਰ ਨੂੰ ਯੂਜ਼ਰ ਦੇ ਮਨਸੂਬੇ ਦੇ ਮੁਕਾਬਲੇ ਦਾ ਮੁਆਇਨਾ ਕਰਦਾ ਹੈ ਅਤੇ ਸਭ ਤੋਂ ਵਧੀਆ ਮੇਲ ਚੁਣਦਾ ਹੈ — ਇਸ ਲਈ ਸਾਫ਼ ਅਤੇ ਖਾਸ ਔਜ਼ਾਰ ਵੇਰਵੇ ਲਿਖਣਾ ਮਹੱਤਵਪੂਰਨ ਹੈ।* -### Execution +### ਕਾਰਜਾਨਵਣ [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot ਘੋਸ਼ਣਾਤਮਕ `@AiService` ਇੰਟਰਫੇਸ ਨੂੰ ਸਾਰੇ ਦਰਜ ਟੂਲਾਂ ਨਾਲ ਆਪਣੇ ਆਪ ਜ਼ੁੜਦਾ ਹੈ, ਅਤੇ LangChain4j ਅਟੋਮੈਟਿਕ ਟੂਲ ਕਾਲਾਂ ਚਲਾਉਂਦਾ ਹੈ। ਪਿਛੇ ਦ੍ਰਿਸ਼ ਵਿੱਚ, ਇੱਕ ਪੂਰੀ ਟੂਲ ਕਾਲ ਛੇ ਪੜਾਵਾਂ ਵਿੱਚ ਹੁੰਦੀ ਹੈ — ਉਪਭੋਗਤਾ ਦੇ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਸਵਾਲ ਤੋਂ ਲੈ ਕੇ ਮੁੜ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਜਵਾਬ ਤੱਕ: +ਸਪ੍ਰਿੰਗ ਬੂਟ ਡਿਕਲੇਅਰਟਿਵ `@AiService` ਇੰਟਰਫੇਸ ਨੂੰ ਸਾਰੇ ਰਜਿਸਟਰਡ ਔਜ਼ਾਰਾਂ ਨਾਲ ਆਟੋ-ਵਾਇਰ ਕਰਦਾ ਹੈ, ਅਤੇ LangChain4j ਆਪਣੇ ਆਪ ਔਜ਼ਾਰਾਂ ਦੀ ਕਾਲ ਕਰਦਾ ਹੈ। ਪਿੱਛੇ ਦੇ ਮੰਜਰ ਵਿੱਚ, ਇੱਕ ਪੂਰਾ ਔਜ਼ਾਰ ਕਾਲ ਛੇ ਮੰਚਾਂ ਰਾਹੀਂ ਲੰਘਦਾ ਹੈ — ਯੂਜ਼ਰ ਦੇ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਸਵਾਲ ਤੋਂ ਲੈ ਕੇ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਜਵਾਬ ਤੱਕ: Tool Calling Flow -*ਪੀੜ੍ਹੀ ਦਰ ਪੀੜ੍ਹੀ ਪ੍ਰਕਿਰਿਆ — ਉਪਭੋਗਤਾ ਸਵਾਲ ਪੁੱਛਦਾ ਹੈ, ਮਾਡਲ ਟੂਲ ਚੁਣਦਾ ਹੈ, LangChain4j ਉਸਨੂੰ ਚਲਾਉਂਦਾ ਹੈ, ਅਤੇ ਮਾਡਲ ਨਤੀਜੇ ਨੂੰ ਜਵਾਬ ਵਿੱਚ ਜੋੜਦਾ ਹੈ।* +*ਐਂਡ-ਟੂ-ਐਂਡ ਫਲੋ — ਯੂਜ਼ਰ ਸਵਾਲ ਪੁੱਛਦਾ ਹੈ, ਮਾਡਲ ਔਜ਼ਾਰ ਚੁਣਦਾ ਹੈ, LangChain4j ਨੂੰ ਚਲਾਉਂਦਾ ਹੈ, ਅਤੇ ਮਾਡਲ ਨਤੀਜਾ ਕੁਦਰਤੀ ਜਵਾਬ ਵਿੱਚ ਗੂੰਦਦਾ ਹੈ।* -ਜੇ ਤੁਸੀਂ Module 00 ਵਿੱਚ [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ਚਲਾਇਆ ਸੀ, ਤਾਂ ਤੁਸੀਂ ਇਸ ਪੈਟਰਨ ਨੂੰ ਪਹਿਲਾਂ ਹੀ ਦੇਖਿਆ — `Calculator` ਟੂਲਾਂ ਇਹੀ ਤਰੀਕੇ ਨਾਲ ਕਾਲ ਕੀਤੇ ਗਏ। ਹੇਠਾਂ ਦਿੱਤਾ ਸੀਕੈਂਸ ਡਾਇਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਉਸ ਡੈਮੋ ਵਿੱਚ ਕੀ ਹੋਇਆ: +ਪਿੱਛੇ, `AiServices` ਕਿਸੇ ਵੀ ਔਜ਼ਾਰ ਲਈ ਇਸੇ ਔਜ਼ਾਰ-ਕਾਲ ਲੂਪ ਨੂੰ ਦੌੜਾਉਂਦਾ ਹੈ — ਇੱਥੇ ਇੱਕ ਸਧਾਰਣ `Calculator` ਨਾਲ ਦਰਸਾਇਆ ਗਿਆ ਹੈ। ਹੇਠਾਂ ਦਿੱਤਾ ਸੀਕੁਂਸ ਡਾਇਗ੍ਰਾਮ ਦਿਖਾਉਂਦਾ ਹੈ ਕਿ ਛੱਡੇ ਪੱਧਰ 'ਤੇ ਕੀ ਹੁੰਦਾ ਹੈ: Tool Calling Sequence Diagram -*Quick Start ਡੈਮੋ ਤੋਂ ਟੂਲ ਕਾਲ ਲੂਪ — `AiServices` ਤੁਹਾਡਾ ਸੁਨੇਹਾ ਅਤੇ ਟੂਲ ਸਕੀਮਾਂ LLM ਨੂੰ ਭੇਜਦਾ ਹੈ, LLM ਇੱਕ ਫੰਕਸ਼ਨ ਕਾਲ ਜਿਵੇਂ `add(42, 58)` ਨਾਲ ਜਵਾਬ ਦਿੰਦਾ ਹੈ, LangChain4j `Calculator` ਮੈਥਡ ਸਥਾਨਕ ਤੌਰ ਤੇ ਚਲਾਉਂਦਾ ਹੈ, ਅਤੇ ਨਤੀਜਾ ਮੁੜ ਅਖੀਰਲੇ ਜਵਾਬ ਲਈ ਭੇਜਦਾ ਹੈ।* +*ਔਜ਼ਾਰ ਕਾਲ ਲੂਪ — `AiServices` ਤੁਹਾਡਾ ਸੰਦੇਸ਼ ਅਤੇ ਔਜ਼ਾਰ ਸਕੀਮਾਂ LLM ਨੂੰ ਭੇਜਦਾ ਹੈ, LLM ਨੇ `add(42, 58)` ਵਰਗਾ ਫੰਕਸ਼ਨ ਕਾਲ ਜਵਾਬ ਦਿੰਦਾ ਹੈ, LangChain4j `Calculator` ਥਾਂ-ਥਾਂ ਚਲਾਉਂਦਾ ਹੈ, ਅਤੇ ਨਤੀਜਾ ਵਾਪਸ ਭੇਜਦਾ ਹੈ ਅੰਤਿਮ ਜਵਾਬ ਲਈ।* > **🤖 [GitHub Copilot](https://github.com/features/copilot) ਚੈਟ ਨਾਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ਖੋਲ੍ਹੋ ਅਤੇ ਪੁੱਛੋ: -> - "ReAct ਪੈਟਰਨ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ ਅਤੇ ਇਹ AI ਏਜੈਂਟਾਂ ਲਈ ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਕਿਵੇਂ ਹੈ?" -> - "ਏਜੈਂਟ ਕਿਵੇਂ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕਿਹੜਾ ਟੂਲ ਵਰਤਣਾ ਹੈ ਅਤੇ ਕਿਸ ਕ੍ਰਮ ਵਿੱਚ?" -> - "ਜੇ ਟੂਲ ਚਲਾਉਣ ਸਮੇਂ ਗਲਤੀ ਆਉਂਦੀ ਹੈ - ਮੈਨੂੰ ਅਮਲ ਵਿੱਚ ਗਲਤੀਆਂ ਨੂੰ ਕਿਵੇਂ ਮਜ਼ਬੂਤੀ ਨਾਲ ਸੰਭਾਲਣਾ ਚਾਹੀਦਾ ਹੈ?" +> - "ReAct ਪੈਟਰਨ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ ਅਤੇ AI ਏਜੰਟ ਲਈ ਇਹ ਕਿਉਂ ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਹੈ?" +> - "ਏਜੰਟ ਕਿਵੇਂ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕਿਹੜਾ ਔਜ਼ਾਰ ਅਤੇ ਕਿਸ ਕ੍ਰਮ ਵਿੱਚ ਵਰਤਣਾ ਹੈ?" +> - "ਜੇ ਕੋਈ ਔਜ਼ਾਰ ਕਾਰਜਾਨਵਣ ਅਸਫਲ ਹੁੰਦਾ ਹੈ ਤਾਂ ਕੀ ਹੁੰਦਾ ਹੈ - ਮੈਂ ਗਲਤੀਆਂ ਨੂੰ ਕਿਵੇਂ ਮਜ਼ਬੂਤੀ ਨਾਲ ਸੰਭਾਲਾਂ?" -### Response Generation +### ਪ੍ਰਤੀਕਿਰਿਆ ਬਣਾਉਣਾ -ਮਾਡਲ ਮੌਸਮ ਡੇਟਾ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ ਅਤੇ ਉਪਭੋਗਤਾ ਲਈ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਵਿੱਚ ਜਵਾਬ ਤਿਆਰ ਕਰਦਾ ਹੈ। +ਮਾਡਲ ਮੌਸਮ ਡਾਟਾ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ ਅਤੇ ਯੂਜ਼ਰ ਲਈ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਵਿੱਚ ਜਵਾਬ ਤਿਆਰ ਕਰਦਾ ਹੈ। -### Architecture: Spring Boot Auto-Wiring +### ਆਰਕੀਟੈਕਚਰ: ਸਪ੍ਰਿੰਗ ਬੂਟ ਆਟੋ-ਵਾਇਰਿੰਗ -ਇਹ ਮੋਡੀਊਲ LangChain4j ਦੀ Spring Boot ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਵਰਤਦਾ ਹੈ ਜਿਸ ਵਿੱਚ ਘੋਸ਼ਣਾਤਮਕ `@AiService` ਇੰਟਰਫੇਸ ਹਨ। ਸ਼ੁਰੂਆਤ ਸਮੇਂ Spring Boot ਹਰ ਉਸ `@Component` ਨੂੰ ਲੱਭਦਾ ਹੈ ਜਿਸਦਾ `@Tool` ਮੈਥਡ ਹੁੰਦਾ ਹੈ, ਤੁਹਾਡਾ `ChatModel` ਬੀਨ, ਅਤੇ `ChatMemoryProvider` — ਫਿਰ ਸਾਰਿਆਂ ਨੂੰ ਇੱਕ ਇਕੱਲੇ `Assistant` ਇੰਟਰਫੇਸ ਵਿੱਚ ਜੋੜਦਾ ਹੈ ਬਿਨਾਂ ਕਿਸੇ ਬੋਇਲਰਪਲੇਟ ਕੋਡ ਦੇ। +ਇਹ ਮੋਡੀਊਲ LangChain4j ਦੀ ਸਪ੍ਰਿੰਗ ਬੂਟ ਇੰਟੀਗਰੇਸ਼ਨ ਨੂੰ ਡਿਕਲੇਅਰਟਿਵ `@AiService` ਇੰਟਰਫੇਸਾਂ ਨਾਲ ਵਰਤਦਾ ਹੈ। ਸਟਾਰਟਅਪ 'ਤੇ ਸਪ੍ਰਿੰਗ ਬੂਟ ਹਰ `@Component` ਜੋ `@Tool` ਮੈਥਡ ਸਮੇਤ ਹੁੰਦਾ ਹੈ, ਤੁਹਾਡਾ `ChatModel` ਬੀਨ, ਅਤੇ `ChatMemoryProvider` ਨੂੰ ਖੋਜਦਾ ਹੈ — ਫਿਰ ਸਾਰੇ ਨੂੰ ਇੱਕ ਇੱਕਲ `Assistant` ਇੰਟਰਫੇਸ ਵਿੱਚ ਜੁੜਦਾ ਹੈ ਬਿਨਾਂ ਕਿਸੇ ਸਰਕਾਰੀ ਕੋਡ ਦੇ। Spring Boot Auto-Wiring Architecture -*@AiService ਇੰਟਰਫੇਸ ChatModel, ਟੂਲ ਕੰਪੋਨੈਂਟ ਅਤੇ ਮੈਮੋਰੀ ਪ੍ਰੋਵਾਈਡਰ ਨੂੰ ਜੋੜਦਾ ਹੈ — Spring Boot ਸਾਰਾ ਵਾਇਰਿੰਗ ਆਪਣੇ ਆਪ ਕਰਦਾ ਹੈ।* +*@AiService ਇੰਟਰਫੇਸ ChatModel, ਔਜ਼ਾਰ ਸੰਘਟਕ, ਅਤੇ ਮੈਮੋਰੀ ਪ੍ਰੋਵਾਈਡਰ ਨਾਲ ਜੋੜਦਾ ਹੈ — ਸਪ੍ਰਿੰਗ ਬੂਟ ਸਾਰਾ ਵਾਇਰਿੰਗ ਖੁਦ ਕਰ ਲੈਂਦਾ ਹੈ।* -ਹੇਠਾਂ HTTP ਅਰਜ਼ੀ ਤੋਂ ਲੈ ਕੇ ਕੰਟਰੋਲਰ, ਸਰਵਿਸ, ਅਤੇ ਆਟੋ-ਵਾਇਰਡ ਪ੍ਰੋਕਸੀ ਤੱਕ, ਫਿਰ ਟੂਲ ਟ_rੂ_ਤਰੱਕੀ ਅਤੇ ਵਾਪਸੀ ਦਾ ਪੂਰਾ ਜੀਵਨ ਚੱਕਰ ਹੈ: +ਹੇਠਾਂ ਪੂਰੀ ਬੇਨਤੀ ਜੀਵਨਚੱਕਰ ਹੈ ਪ੍ਰਦਰਸ਼ਿਤ ਇੱਕ ਸੀਕੁਂਸ ਡਾਇਗ੍ਰਾਮ ਵਜੋਂ — HTTP ਬੇਨਤੀ ਤੋਂ ਲੈ ਕੇ ਕੰਟਰੋਲਰ, ਸਰਵਿਸ, ਅਤੇ ਆਟੋ-ਵਾਇਰਡ ਪ੍ਰਾਕਸੀ, ਔਜ਼ਾਰ ਕਾਰਜਾਨਵਣ ਤੱਕ ਅਤੇ ਵਾਪਸ: Spring Boot Tool Calling Sequence -*ਪੂਰਾ Spring Boot ਅਰਜ਼ੀ ਜੀਵਨ ਚੱਕਰ — HTTP ਅਰਜ਼ੀ ਕੰਟਰੋਲਰ ਤੇ ਸਰਵਿਸ ਰਾਹੀਂ ਆਟੋ-ਵਾਇਰਡ Assistant ਪ੍ਰਾਕਸੀ ਤੱਕ ਜਾਂਦੀ ਹੈ ਜੋ LLM ਅਤੇ ਟੂਲ ਕਾਲਾਂ ਨੂੰ ਆਪਣੇ ਆਪ ਸੰਚਾਲਿਤ ਕਰਦਾ ਹੈ।* +*ਪੂਰੀ ਸਪ੍ਰਿੰਗ ਬੂਟ ਬੇਨਤੀ ਜੀਵਨਚੱਕਰ — HTTP ਬੇਨਤੀ ਕੰਟਰੋਲਰ ਤੇ ਸਰਵਿਸ ਰਾਹੀਂ ਆਟੋ-ਵਾਇਰਡ Assistant ਪ੍ਰਾਕਸੀ ਤੱਕ ਜਾਂਦੀ ਹੈ, ਜੋ ਕਿ LLM ਅਤੇ ਔਜ਼ਾਰ ਕਾਲਾਂ ਨੂੰ ਆਪਣੇ ਆਪ ਕਾਬੂ ਕਰਦਾ ਹੈ।* -ਇਸ ਤਰੀਕੇ ਦੇ ਮੁੱਖ ਫਾਇਦੇ: +ਇਸ ਤਰੀਕੇ ਦੇ ਮੁੱਖ ਲਾਭ: -- **Spring Boot auto-wiring** — ChatModel ਅਤੇ ਟੂਲ ਆਪ ਹੀ ਜੁੜ ਜਾਂਦੇ ਹਨ -- **@MemoryId ਪੈਟਰਨ** — ਆਪਣੇ ਆਪ ਸੈਸ਼ਨ-ਆਧਾਰਿਤ ਮੈਮੋਰੀ ਪ੍ਰਬੰਧ -- **ਇੱਕੋ ਉਮੀਦ** — Assistant ਇਕ ਵਾਰੀ ਬਣਾਇਆ ਜਾਂਦਾ ਹੈ ਅਤੇ ਵਧੀਆ ਪ੍ਰਦਰਸ਼ਨ ਲਈ ਦੁਬਾਰਾ ਵਰਤਿਆ ਜਾਂਦਾ ਹੈ -- **ਟਾਈਪ-ਸੁਰੱਖਿਅਤ ਅਮਲ** — ਜਾਵਾ ਮੈਥਡ ਸਿੱਧਾ ਟਾਈਪ ਕੁਨਵਰਜ਼ਨ ਨਾਲ ਕਾਲ ਹੁੰਦੇ ਹਨ -- **ਬਹੁ-ਚੱਕਰ ਸੰਚਾਲਨ** — ਆਟੋਮੈਟਿਕ ਟੂਲ ਚੈਨਿੰਗ ਨਿਭਾਈ ਜਾਂਦੀ ਹੈ -- **ਜ਼ੀਰੋ ਬੋਇਲਰਪਲੇਟ** — ਕੋਈ ਮੈਨੁਅਲ `AiServices.builder()` ਕਾਲ ਨਹੀਂ ਜਾਂ ਮੈਮੋਰੀ HashMap ਨਹੀਂ +- **ਸਪ੍ਰਿੰਗ ਬੂਟ ਆਟੋ-ਵਾਇਰਿੰਗ** — ChatModel ਅਤੇ ਔਜ਼ਾਰਾਂ ਨੂੰ ਆਪਣੇ ਆਪ ਇੰਜੈਕਟ ਕਰਦਾ ਹੈ +- **@MemoryId ਪੈਟਰਨ** — ਆਪਣੇ ਆਪ ਸੈਸ਼ਨ-ਆਧਾਰਿਤ ਯਾਦ ਪ੍ਰਬੰਧਨ +- **ਇੱਕਲ ਦਰਜਾ** — ਇੱਕ ਵਾਰੀ Assistant ਬਣਾਇਆ ਜਾਂਦਾ ਹੈ ਅਤੇ ਬਿਹਤਰ ਪ੍ਰਦਰਸ਼ਨ ਲਈ ਵਾਰ-ਵਾਰ ਵਰਤਿਆ ਜਾਂਦਾ ਹੈ +- **ਟਾਈਪ-ਸੁਰੱਖਿਅਤ ਕਾਰਜਾਨਵਣ** — ਜਾਵਾ ਮੈਥਡ ਸਿੱਧੇ ਤੌਰ ਤੇ ਟਾਈਪ ਰੂਪਾਂਤਰ ਕਰਕੇ ਕੂਲ੍ਹੇ ਜਾਂਦੇ ਹਨ +- **ਬਹੁ-ਮੁੜ ਘੁੰਮਾਵਾ ਅਯੋਜਨ** — ਔਜ਼ਾਰ ਚੇਨਿੰਗ ਨੂੰ ਆਪਣੇ ਆਪ ਹੈਂਡਲ ਕਰਦਾ ਹੈ +- **ਕੋਈ ਬੋਰਡ ਕੋਡ ਨਹੀਂ** — ਕੋਈ ਹੱਥੋਂ `AiServices.builder()` ਕਾਲ ਜਾਂ ਯਾਦ HashMap ਨਹੀਂ -ਵਿਕਲਪਕ ਤਰੀਕੇ (ਮੈਨੂਅਲ `AiServices.builder()`) ਵੱਧ ਕੋਡ ਦੀ ਮੰਗ ਕਰਦੇ ਹਨ ਅਤੇ Spring Boot ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਦੇ ਫਾਇਦੇ ਨਹੀਂ ਦਿੰਦੇ। +ਵਿਕਲਪੀ ਤਰੀਕੇ (ਹੱਥੋਂ `AiServices.builder()`) ਵਿੱਚ ਵਧ ਕੋਡ ਲੱਗਦਾ ਹੈ ਤੇ ਸਪ੍ਰਿੰਗ ਬੂਟ ਇੰਟੀਗਰੇਸ਼ਨ ਲਾਭ ਧੁੰਦਲੇ ਹੋ ਜਾਂਦੇ ਹਨ। -## Tool Chaining +## ਔਜ਼ਾਰ ਚੇਨਿੰਗ -**Tool Chaining** — ਟੂਲ-ਆਧਾਰਤ ਏਜੈਂਟਾਂ ਦੀ ਅਸਲ ਤਾਕਤ ਉਸ ਵੇਲੇ ਵੇਖਣ ਨੂੰ ਮਿਲਦੀ ਹੈ ਜਦੋਂ ਇਕ ਸਵਾਲ ਲਈ ਕਈ ਟੂਲ ਚਾਹੀਦੇ ਹੋਣ। ਪੁੱਛੋ "ਸੀਅਟਲ ਵਿੱਚ ਮੌਸਮ ਫੈਰਨਹਾਈਟ ਵਿੱਚ ਕਿਵੇਂ ਹੈ?" ਅਤੇ ਏਜੈਂਟ ਆਪ-ਆਪ ਨੂੰ ਦੋ ਟੂਲ ਜੁੜਦੇ ਦੇਖਾਵੇਗਾ: ਪਹਿਲਾਂ ਇਹ `getCurrentWeather` ਕਾਲ ਕਰਦਾ ਹੈ, ਜਿਹੜਾ ਸੈਲਸੀਅਸ ਵਿੱਚ ਤਾਪਮਾਨ ਲਿਆਉਂਦਾ ਹੈ, ਫਿਰ ਇਸ ਮੁੱਲ ਨੂੰ `celsiusToFahrenheit` ਨੂੰ ਪਾਸ ਕਰਦਾ ਹੈ ਤਬਦੀਲੀ ਲਈ — ਸਾਰੇ ਇੱਕ ਗੱਲਬਾਤੇ ਕਦਮ ਵਿੱਚ। +**ਔਜ਼ਾਰ ਚੇਨਿੰਗ** — ਔਜ਼ਾਰ-ਆਧਾਰਿਤ ਏਜੰਟਾਂ ਦੀ ਅਸਲੀ ਤਾਕਤ ਤਦ ਵੇਖਣ ਨੂੰ ਮਿਲਦੀ ਹੈ ਜਦੋਂ ਕਿਸੇ ਇੱਕ ਸਵਾਲ ਲਈ ਕਈ ਔਜ਼ਾਰਾਂ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ। ਪੁੱਛੋ "ਸੀਅਟਲ ਦਾ ਮੌਸਮ ਫੈਰਨਹਾਈਟ ਵਿੱਚ ਕੀ ਹੈ?" ਅਤੇ ਏਜੰਟ ਖੁਦ ਬ-ਖੁਦ ਦੋ ਔਜ਼ਾਰ ਬੰਨ੍ਹਦਾ ਹੈ: ਪਹਿਲਾਂ `getCurrentWeather` ਨੂੰ ਕਾਲ ਕਰਦਾ ਹੈ ਤਾਂ ਜੋ ਸੈਲਸਿਅਸ ਵਿੱਚ ਤਾਪਮਾਨ ਮਿਲੇ, ਫਿਰ ਉਸ ਮੁੱਲ ਨੂੰ `celsiusToFahrenheit` ਨੂੰ ਦਿੰਦਾ ਹੈ ਤਬਦੀਲੀ ਲਈ — ਇਹ ਸਾਰਾ ਇੱਕ ਗੱਲਬਾਤ ਵਿੱਚ ਹੁੰਦਾ ਹੈ। Tool Chaining Example -*ਟੂਲ ਚੈਨਿੰਗ ਕਾਰਜ ਵਿੱਚ — ਏਜੈਂਟ ਪਹਿਲਾਂ getCurrentWeather ਕਾਲ ਕਰਦਾ ਹੈ, ਫਿਰ ਸੈਲਸੀਅਸ ਨਤੀਜੇ ਨੂੰ celsiusToFahrenheit ਵਿੱਚ ਪਾਸ ਕਰਦਾ ਹੈ, ਅਤੇ ਮਿਲੀ-ਝੁਲੀ ਜਵਾਬ ਦਿੰਦਾ ਹੈ।* +*ਔਜ਼ਾਰ ਚੇਨਿੰਗ ਕਾਰਵਾਈ ਵਿੱਚ — ਏਜੰਟ ਪਹਿਲਾਂ getCurrentWeather ਕਾਲ ਕਰਦਾ ਹੈ, ਫਿਰ ਸੈਲਸਿਅਸ ਨਤੀਜੇ ਨੂੰ celsiusToFahrenheit ਵਿੱਚ ਪਾਈਪ ਕਰਦਾ ਹੈ, ਅਤੇ ਮਿਲੀ ਜੁਲੀ ਜਵਾਬ ਦਿੰਦਾ ਹੈ।* -**ਸੌਖੇ ਅਸਫਲਤਾ (Graceful Failures)** — ਕਿਸੇ ਐਸੇ ਸ਼ਹਿਰ ਦਾ ਮੌਸਮ ਪੁੱਛੋ ਜੋ ਮੌਕ ਡਾਟਾ ਵਿੱਚ ਨਹੀਂ ਹੈ। ਟੂਲ ਇੱਕ ਤਰੁਟ 메시ਜ ਵਾਪਸ ਕਰਦਾ ਹੈ, ਅਤੇ AI ਦੱਸਦਾ ਹੈ ਕਿ ਉਹ ਮਦਦ ਨਹੀਂ ਕਰ ਸਕਦਾ ਬਜਾਏ ਪਲੱਟਣ ਦੇ। ਟੂਲ ਸੁਰੱਖਿਅਤ ਤਰੀਕੇ ਨਾਲ ਅਸਫਲ ਹੁੰਦੇ ਹਨ। ਹੇਠਾਂ ਦਿੱਤਾ ਡਾਯਾਗ੍ਰਾਮ ਦੋ ਤਰੀਕਿਆਂ ਨੂੰ ਵੇਖਾਉਂਦਾ ਹੈ — ਠੀਕ ਤਰਤੀਬ ਨਾਲ ਗਲਤੀ ਸੰਭਾਲਣ ਨਾਲ, ਏਜੈਂਟ ਐਕਸਪਸ਼ਨ ਫੜ ਕੇ ਮਦਦਗਾਰ ਜਵਾਬ ਦਿੰਦਾ ਹੈ, ਪਰ ਬਿਨਾਂ ਇਸਦੇ ਪੂਰਾ ਐਪੜੀਕੇਸ਼ਨ ਕਰੈਸ਼ ਕਰ ਜਾਂਦਾ ਹੈ: +**ਸੁਮਝਦਾਰ ਗਲਤੀ ਸੰਭਾਲ:** ਕਿਸੇ ਅਜਿਹਾ ਸ਼ਹਿਰ ਪੁੱਛੋ ਜਿਹੜਾ ਮੌਕ ਡਾਟਾ ਵਿੱਚ ਨਾ ਹੋਵੇ। ਔਜ਼ਾਰ ਗਲਤੀ ਸੁਨੇਹਾ ਵਾਪਸ ਕਰਦਾ ਹੈ, ਅਤੇ AI ਸਮਝਾਉਂਦਾ ਹੈ ਕਿ ਉਹ ਮਦਦ ਨਹੀਂ ਕਰ ਸਕਦਾ ਬਜਾਏ ਕਿ ਐਪ्लਿਕੇਸ਼ਨ ਕ੍ਰੈਸ਼ ਹੋ ਜਾਵੇ। ਔਜ਼ਾਰ ਸੁਰੱਖਿਅਤ ਤਰੀਕੇ ਨਾਲ ਫੇਲ ਹੁੰਦੇ ਹਨ। ਹੇਠਾਂ ਦਿੱਤਾ ਚਿੱਤਰ ਦੋਹਾਂ ਢੰਗਾਂ ਦਾ ਤુલਨਾਤਮਕ ਦਰਸ਼ਨ ਦਿੰਦਾ ਹੈ — ਠੀਕ ਗਲਤੀ ਸੰਭਾਲ ਨਾਲ ਏਜੰਟ ਅਪਵਾਦ ਫੜਦਾ ਹੈ ਅਤੇ ਮਦਦਗਾਰ ਜਵਾਬ ਦਿੰਦਾ ਹੈ, ਬਿਨਾਂ ਇਸ ਦੇ ਸਾਰੀ ਐਪ crash ਹੋ ਜਾਂਦੀ ਹੈ: Error Handling Flow -*ਜਦੋਂ ਟੂਲ ਅਸਫਲ ਹੁੰਦਾ ਹੈ, ਏਜੈਂਟ ਗਲਤੀ ਫੜਦਾ ਹੈ ਅਤੇ ਟੁੱਟਣ ਬਜਾਏ ਮਦਦਗਾਰ ਵਿਆਖਿਆ ਦੇਦਾ ਹੈ।* +*ਜਦੋਂ ਔਜ਼ਾਰ ਫੇਲ ਹੁੰਦਾ ਹੈ, ਏਜੰਟ ਗਲਤੀ ਫੜਦਾ ਹੈ ਅਤੇ ਕ੍ਰੈਸ਼ ਹੋਣ ਦੀ ਥਾਂ ਮਦਦਗਾਰ ਵਰਣਨ ਦਿੰਦਾ ਹੈ।* -ਇਹ ਸਾਰੇ ਇੱਕ ਹੀ ਗੱਲਬਾਤੇ ਕਦਮ ਵਿੱਚ ਹੁੰਦਾ ਹੈ। ਏਜੈਂਟ ਕਈ ਟੂਲ ਕਾਲਾਂ ਨੂੰ ਖੁਦ ਚਲਾਉਂਦਾ ਹੈ। +ਇਹ ਸਾਰਾ ਇੱਕ ਗੱਲਬਾਤ ਵਿੱਚ ਹੁੰਦਾ ਹੈ। ਏਜੰਟ ਖੁਦ-ਮੁਖਤਿਆਰ ਤੌਰ ਤੇ ਕਈ ਔਜ਼ਾਰਾਂ ਦੀ ਕਾਲਾਂ ਸੰਚਾਲਿਤ ਕਰਦਾ ਹੈ। -## Run the Application +## ਐਪਲੀਕੇਸ਼ਨ ਚਲਾਉਣਾ -**ਡਿਪਲੋਇਮੈਂਟ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ:** +**ਤੈਅਕਰਨ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ:** -ਪੱਕਾ ਕਰੋ ਕਿ `.env` ਫਾਈਲ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ Azure ਪ੍ਰਮਾਣਿਕਤਾ ਨਾਲ ਮੌਜੂਦ ਹੈ (Module 01 ਦੌਰਾਨ ਬਣਾਈ ਗਈ)। ਇਸਨੂੰ ਮੋਡੀਊਲ ਡਾਇਰੈਕਟਰੀ (`04-tools/`) ਤੋਂ ਚਲਾਓ: +ਸੁਨਿਸ਼ਚਿਤ ਕਰੋ ਕਿ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਵਿੱਚ `.env` ਫਾਇਲ ਹੈ ਜੋ ਐਜ਼ੂਰ ਪ੍ਰਮਾਣ ਪੱਤਰਾਂ ਨਾਲ ਹੈ (ਮੋਡੀਊਲ 01 ਦੌਰਾਨ ਬਣਾਈ ਗਈ)। ਇਸਨੂੰ ਮੋਡੀਊਲ ਡਾਇਰੈਕਟਰੀ (`04-tools/`) ਤੋਂ ਚਲਾਓ: -**Bash:** +**ਬੈਸ਼:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ ``` -**PowerShell:** +**ਪਾਵਰਸ਼ੈੱਲ:** ```powershell Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ ``` **ਐਪਲੀਕੇਸ਼ਨ ਸ਼ੁਰੂ ਕਰੋ:** -> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਪਹਿਲਾਂ ਹੀ ਸਾਰੇ ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ `./start-all.sh` ਨਾਲ ਚਾਲੂ ਕੀਤਾ ਹੈ (ਜਿਵੇਂ Module 01 ਵਿੱਚ ਵਰਨਿਤ ਹੈ), ਤਾਂ ਇਹ ਮੋਡੀਊਲ ਪਹਿਲਾਂ ਹੀ ਪੋਰਟ 8084 'ਤੇ ਚਲ ਰਿਹਾ ਹੈ। ਤੁਸੀਂ ਹੇਠਾਂ ਦਿੱਤੇ ਸਟਾਰਟ ਕਮਾਂਡਾਂ ਨੂੰ ਛੱਡ ਕੇ ਸਿੱਧਾ http://localhost:8084 ਤੇ ਜਾ ਸਕਦੇ ਹੋ। +> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਪਹਿਲਾਂ ਹੀ ਸਾਰੇ ਐਪਲੀਕੇਸ਼ਨ `./start-all.sh` ਨਾਲ ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ ਚਲਾ ਰਹੇ ਹੋ (ਜਿਵੇਂ ਮੋਡੀਊਲ 01 ਵਿੱਚ ਵੇਖਾਇਆ), ਤਾਂ ਇਹ ਮੋਡੀਊਲ ਪਹਿਲਾਂ ਹੀ ਪੋਰਟ 8084 'ਤੇ ਚੱਲ ਰਿਹਾ ਹੈ। ਤੁਸੀਂ ਨੀਚੇ ਦਿੱਤੇ ਕਮਾਂਡਾਂ ਨੂੰ ਛੱਡ ਕੇ ਸਿੱਧਾ http://localhost:8084 ਤੇ ਜਾ ਸਕਦੇ ਹੋ। -**ਵਿਕਲਪ 1: Spring Boot ਡੈਸ਼ਬੋਰਡ ਵਰਤਣਾ (VS Code ਉਪਭੋਗਤਿਆਂ ਲਈ ਸੁਝਾਅ)** +**ਚੋਣ 1: ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਵਰਤੋਂ (ਵਿਏਸ ਕੋਡ ਯੂਜ਼ਰਾਂ ਲਈ ਸਿਫਾਰਸ਼)** -ਡਿਵ контейਨਰ ਵਿੱਚ Spring Boot Dashboard ਐਕਸਟੇੰਸ਼ਨ ਸ਼ਾਮਿਲ ਹੈ, ਜੋ ਸਾਰੇ Spring Boot ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਮੈਨੇਜ਼ ਕਰਨ ਲਈ ਇੱਕ ਦ੍ਰਿਸ਼ਯ ਇੰਟਰਫੇਸ ਦਿੰਦਾ ਹੈ। ਤੁਸੀਂ ਇਸਨੂੰ VS Code ਦੇ ਖੱਬੇ ਪਾਸੇ ਐਕਟਿਵਿਟੀ ਬਾਰ ਵਿਚ ਲੱਭ ਸਕਦੇ ਹੋ (Spring Boot ਆਈਕਨ ਵੇਖੋ)। +ਡੈਵ ਕੰਟੇਨਰ ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਐਕਸਟੈਂਸ਼ਨ ਸ਼ਾਮਿਲ ਹੈ, ਜੋ ਸਾਰੇ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਪ੍ਰਬੰਧਿਤ ਕਰਨ ਲਈ ਵਿਜ਼ੂਅਲ ਇੰਟਰਫੇਸ ਦਿੰਦਾ ਹੈ। ਤੁਸੀਂ ਇਸਨੂੰ VS ਕੋਡ ਦੇ ਖੱਬੇ ਪਾਸੇ ਐਕਟੀਵਿਟੀ ਬਾਰ ਵਿੱਚ (ਸਪ੍ਰਿੰਗ ਬੂਟ ਆਈਕਨ ਵੇਖੋ) ਲੱਭ ਸਕਦੇ ਹੋ। -Spring Boot ਡੈਸ਼ਬੋਰਡ ਤੋਂ, ਤੁਸੀਂ: -- ਕਾਰਜ ਸਥਾਨ ਵਿੱਚ ਸਾਰੇ ਉਪਲਬਧ Spring Boot ਐਪਲੀਕੇਸ਼ਨ ਵੇਖ ਸਕਦੇ ਹੋ -- ਸਿੰਗਲ ਕਲਿੱਕ ਨਾਲ ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਸ਼ੁਰੂ/ਰੋਕ ਸਕਦੇ ਹੋ -- ਰੀਅਲ-ਟਾਈਮ ਐਪਲੀਕੇਸ਼ਨ ਲੌਗਸ ਵੇਖ ਸਕਦੇ ਹੋ -- ਐਪਲੀਕੇਸ਼ਨ ਸਥਿਤੀ ਦੀ ਮਾਨੀਟਰਿੰਗ ਕਰ ਸਕਦੇ ਹੋ -ਸਿਰਫ "tools" ਕੋਲ ਖੇਡਣ ਦਾ ਬਟਨ ਕਲਿੱਕ ਕਰੋ ਇਸ ਮੋਡੀਊਲ ਨੂੰ ਸ਼ੁਰੂ ਕਰਨ ਲਈ, ਜਾਂ ਸਾਰੇ ਮੋਡੀਊਲ ਇਕੱਠੇ ਸ਼ੁਰੂ ਕਰੋ। +ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਤੋਂ, ਤੁਸੀਂ: +- ਵਰਕਸਪੇਸ ਵਿੱਚ ਸਾਰੇ ਉਪਲਬਧ ਸਪ੍ਰਿੰਗ ਬੂਟ ਐਪਲੀਕੇਸ਼ਨ ਵੇਖ ਸਕਦੇ ਹੋ +- ਇੱਕ ਕਲਿੱਕ ਨਾਲ ਐਪਲੀਕੇਸ਼ਨਾਂ ਸ਼ੁਰੂ/ਰੋਕ ਸਕਦੇ ਹੋ +- ਐਪਲੀਕੇਸ਼ਨ ਲਾਗਜ਼ ਨੂੰ ਲਾਈਵ ਵੇਖ ਸਕਦੇ ਹੋ +- ਐਪਲੀਕੇਸ਼ਨ ਸਥਿਤੀ ਦੀ ਨਿਗਰਾਨੀ ਕਰ ਸਕਦੇ ਹੋ -ਇੱਥੇ VS ਕੋਡ ਵਿੱਚ Spring Boot ਡੈਸ਼ਬੋਰਡ ਕਿਵੇਂ ਲੱਗਦਾ ਹੈ: +"tools" ਦੇ ਨਾਲ ਖੇਡ ਬਟਨ ਤੇ ਕਲਿੱਕ ਕਰਕੇ ਇਸ ਮੋਡੀਊਲ ਨੂੰ ਚਾਲੂ ਕਰੋ, ਜਾਂ ਸਾਰੇ ਮੋਡੀਊਲ ਇਕੱਠੇ ਸ਼ੁਰੂ ਕਰੋ। -Spring Boot Dashboard +VS ਕੋਡ ਵਿਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ ਇਸ ਤਰ੍ਹਾਂ ਦਿੱਖਦਾ ਹੈ: +ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ -*VS ਕੋਡ ਵਿੱਚ Spring Boot ਡੈਸ਼ਬੋਰਡ — ਸਾਰੇ ਮੋਡੀਊਲ ਇੱਕ ਥਾਂ ਤੋਂ ਸ਼ੁਰੂ, ਰੋਕੋ, ਅਤੇ ਮਾਨੀਟਰ ਕਰੋ* +*VS ਕੋਡ ਵਿੱਚ ਸਪ੍ਰਿੰਗ ਬੂਟ ਡੈਸ਼ਬੋਰਡ — ਸਭ ਮੋਡੀਊਲਾਂ ਨੂੰ ਇੱਕ ਥਾਂ ਤੋਂ ਸ਼ੁਰੂ, ਰੋਕੋ ਅਤੇ ਨਿਗਰਾਨੀ ਕਰੋ* -**ਵਿਕਲਪ 2: shell ਸਕ੍ਰਿਪਟਾਂ ਦੀ ਵਰਤੋਂ** +**ਵਿਕਲਪ 2: ਸ਼ੈੱਲ ਸਕ੍ਰਿਪਟਾਂ ਦੀ ਵਰਤੋਂ ਕਰਕੇ** -ਸਭ ਵੈੱਬ ਐਪਲੀਕੇਸ਼ਨਾਂ (ਮੋਡੀਊਲ 01-04) ਸ਼ੁਰੂ ਕਰੋ: +ਸਭ ਵੈੱਬ ਐਪਲੀਕੇਸ਼ਨਾਂ (ਮੋਡੀਊਲ 01-04) ਨੂੰ ਸ਼ੁਰੂ ਕਰੋ: -**Bash:** +**ਬੈਸ਼:** ```bash cd .. # ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ ./start-all.sh ``` -**PowerShell:** +**ਪਾਵਰਸ਼ੈੱਲ:** ```powershell cd .. # ਰੂਟ ਡਾਇਰੈਕਟਰੀ ਤੋਂ .\start-all.ps1 ``` -ਜਾਂ ਸਿਰਫ ਇਸ ਮੋਡੀਊਲ ਨੂੰ ਸ਼ੁਰੂ ਕਰੋ: +ਜਾਂ ਕੇਵਲ ਇਸ ਮੋਡੀਊਲ ਨੂੰ ਸ਼ੁਰੂ ਕਰੋ: -**Bash:** +**ਬੈਸ਼:** ```bash cd 04-tools ./start.sh ``` -**PowerShell:** +**ਪਾਵਰਸ਼ੈੱਲ:** ```powershell cd 04-tools .\start.ps1 ``` -ਦੋਹਾਂ ਸਕ੍ਰਿਪਟ ਸਵੈਚਾਲਿਤ ਤੌਰ 'ਤੇ ਰੂਟ `.env` ਫਾਇਲ ਤੋਂ ਵਾਤਾਵਰਨ ਵੈਰੀਏਬਲ ਲੋਡ ਕਰਦੇ ਹਨ ਅਤੇ ਜੇ JAR ਫਾਇਲ ਮੌਜੂਦ ਨਹੀਂ ਹੋਂਦੀਆਂ ਤਾਂ ਉਹਨਾਂ ਨੂੰ ਬਣਾਉਂਦੇ ਹਨ। +ਦੋਹਾਂ ਸਕ੍ਰਿਪਟਾਂ ਆਟੋਮੈਟਿਕ ਤੌਰ 'ਤੇ ਰੂਟ `.env` ਫਾਇਲ ਤੋਂ ਵਾਤਾਵਰਣ ਤੱਤ ਲੋਡ ਕਰਦੀਆਂ ਹਨ ਅਤੇ ਜੇ JARs ਮੌਜੂਦ ਨਹੀਂ ਹਨ ਤਾਂ ਉਹਨਾਂ ਨੂੰ ਬਣਾਉਂਦੀਆਂ ਹਨ। -> **ਨੋਟ:** ਜੇ ਤੁਸੀਂ ਸਾਰੇ ਮੋਡੀਊਲ ਮੈਨੂਅਲ ਤੌਰ 'ਤੇ ਬਣਾਉਣਾ ਚਾਹੁੰਦੇ ਹੋ ਸ਼ੁਰੂ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ: +> **ਟਿੱਪਣੀ:** ਜੇ ਤੁਸੀਂ ਸ਼ੁਰੂ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਸਭ ਮੋਡੀਊਲਾਂ ਨੂੰ ਹੱਥੋਂ ਬਣਾਉਣਾ ਪਸੰਦ ਕਰਦੇ ਹੋ: > -> **Bash:** +> **ਬੈਸ਼:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell:** +> **ਪਾਵਰਸ਼ੈੱਲ:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests @@ -276,100 +276,100 @@ cd 04-tools **ਰੋਕਣ ਲਈ:** -**Bash:** +**ਬੈਸ਼:** ```bash -./stop.sh # ਸਿਰਫ ਇਹ ਮੋਡੀਊਲ +./stop.sh # ਇਸ ਮੋਡੀਊਲ ਤੋਂ ਸਿਰਫ਼ # ਜਾਂ -cd .. && ./stop-all.sh # ਸਾਰੇ ਮੋਡੀਊਲ +cd .. && ./stop-all.sh # ਸਾਰੇ ਮੋਡੀਊਲਸ ``` -**PowerShell:** +**ਪਾਵਰਸ਼ੈੱਲ:** ```powershell -.\stop.ps1 # ਇਹ ਮਾਡਿਊਲ ਸਿਰਫ +.\stop.ps1 # ਇਹ ਮੌਡੀਊਲ ਸਿਰਫ # ਜਾਂ -cd ..; .\stop-all.ps1 # ਸਾਰੇ ਮਾਡਿਊਲ +cd ..; .\stop-all.ps1 # ਸਾਰੇ ਮੌਡੀਊਲਾਂ ``` -## ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਵਰਤੋਂ +## ਐਪਲੀਕੇਸ਼ਨ ਦੀ ਵਰਤੋਂ -ਐਪਲੀਕੇਸ਼ਨ ਇੱਕ ਵੈੱਬ ਇੰਟਰਫੇਸ ਮੁਹੱਈਆ ਕਰਵਾਉਂਦਾ ਹੈ ਜਿੱਥੇ ਤੁਸੀਂ ਇੱਕ AI ਏਜੰਟ ਨਾਲ ਗੱਲਬਾਤ ਕਰ ਸਕਦੇ ਹੋ ਜਿਸ ਨੂੰ ਮੌਸਮ ਅਤੇ ਤਾਪਮਾਨ ਰੂਪਾਂਤਰਨ ਟੂਲਾਂ ਤੱਕ ਪਹੁੰਚ ਹੈ। ਇੱਥੇ ਇੰਟਰਫੇਸ ਕਿਵੇਂ ਲੱਗਦਾ ਹੈ — ਇਸ ਵਿੱਚ ਤੁਰੰਤ ਸ਼ੁਰੂਆਤ ਲਈ ਉਦਾਹਰਣਾਂ ਅਤੇ ਬੇਨਤੀ ਭੇਜਣ ਲਈ ਚੈਟ ਪੈਨਲ ਸ਼ਾਮਿਲ ਹੈ: +ਐਪਲੀਕੇਸ਼ਨ ਇੱਕ ਵੈੱਬ ਇੰਟਰਫੇਸ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ ਜਿੱਥੇ ਤੁਸੀਂ ਇੱਕ ਏਆਈ ਏਜੰਟ ਨਾਲ ਇੰਟਰਐਕਟ ਕਰ ਸਕਦੇ ਹੋ ਜਿਸ ਨੂੰ ਮੌਸਮ ਅਤੇ ਤਾਪਮਾਨ ਰੂਪਾਂਤਰਣ ਉਪਕਰਣਾਂ ਤੱਕ ਪਹੁੰਚ ਹੈ। ਇੱਥੇ ਇੰਟਰਫੇਸ ਕਿਵੇਂ ਦਿਖਦਾ ਹੈ — ਇਸ ਵਿੱਚ ਤਿਆਰ ਉਦਾਹਰਣਾਂ ਅਤੇ ਬੇਨਤੀਆਂ ਭੇਜਣ ਲਈ ਚੈਟ ਪੈਨਲ ਸ਼ਾਮਿਲ ਹੈ: -AI Agent Tools Interface +ਏਆਈ ਏਜੰਟ ਉਪਕਰਣ ਇੰਟਰਫੇਸ -*AI ਏਜੰਟ ਟੂਲ ਇੰਟਰਫੇਸ - ਤੁਰੰਤ ਉਦਾਹਰਣਾਂ ਅਤੇ ਟੂਲਾਂ ਨਾਲ ਗੱਲਬਾਤ ਲਈ ਚੈਟ ਇੰਟਰਫੇਸ* +*ਏਆਈ ਏਜੰਟ ਸੰਦਾਂ ਦਾ ਇੰਟਰਫੇਸ - ਤੁਰੰਤ ਉਦਾਹਰਣ ਅਤੇ ਸੰਦਾਂ ਨਾਲ ਇੰਟਰਐਕਟ ਕਰਨ ਲਈ ਚੈਟ ਇੰਟਰਫੇਸ* -### ਸਧਾਰਣ ਟੂਲ ਵਰਤੋਂ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰੋ +### ਸੌਖੇ ਸੰਦ ਦੀ ਵਰਤੋਂ آزਮਾਓ -ਇੱਕ ਸਿੱਧਾ ਬੇਨਤੀ ਨਾਲ ਸ਼ੁਰੂ ਕਰੋ: "100 ਡਿਗਰੀ ਫੈਰਨਹਾਈਟ ਨੂੰ ਸੈਲਸੀਅਸ ਵਿੱਚ ਬਦਲੋ"। ਏਜੰਟ ਸਮਝਦਾ ਹੈ ਕਿ ਇਸ ਨੂੰ ਤਾਪਮਾਨ ਰੂਪਾਂਤਰਨ ਟੂਲ ਦੀ ਲੋੜ ਹੈ, ਸਹੀ ਪੈਰਾਮੀਟਰਾਂ ਨਾਲ ਇਸਨੂੰ ਕਾਲ ਕਰਦਾ ਹੈ ਅਤੇ ਨਤੀਜਾ ਵਾਪਸ ਕਰਦਾ ਹੈ। ਧਿਆਨ ਦਿਓ ਕਿ ਇਹ ਪ੍ਰਕਿਰਿਆ ਕਿੰਨੀ ਕੁ ਕੁਦਰਤੀ ਮਹਿਸੂਸ ਹੁੰਦੀ ਹੈ - ਤੁਸੀਂ ਨਹੀਂ ਦੱਸਿਆ ਕਿ ਕਿਹੜਾ ਟੂਲ ਵਰਤਣਾ ਹੈ ਜਾਂ ਕਿਵੇਂ ਕਾਲ ਕਰਨਾ ਹੈ। +ਇੱਕ ਸਿੱਧਾ ਬੇਨਤੀ ਨਾਲ ਸ਼ੁਰੂ ਕਰੋ: "100 ਡਿਗਰੀ ਫੈਰਨਹਾਈਟ ਨੂੰ ਸੈਲਸਿਅਸ ਵਿੱਚ ਬਦਲੋ"। ਏਜੰਟ ਸਮਝਦਾ ਹੈ ਕਿ ਇਸਨੂੰ ਤਾਪਮਾਨ ਰੂਪਾਂਤਰਣ ਸੰਦ ਦੀ ਲੋੜ ਹੈ, ਉਹ ਸਹੀ ਪੈਰਾਮੀਟਰਾਂ ਨਾਲ ਕਾਲ ਕਰਦਾ ਹੈ ਅਤੇ ਨਤੀਜਾ ਵਾਪਸ ਕਰਦਾ ਹੈ। ਵੇਖੋ ਇਹ ਕਿੰਨਾ ਕੁ ਪ੍ਰਾਕ੍ਰਿਤਿਕ ਲੱਗਦਾ ਹੈ - ਤੁਸੀਂ ਨਹੀਂ ਦੱਸਿਆ ਕਿ ਕਿਹੜਾ ਸੰਦ ਵਰਤਣਾ ਹੈ ਜਾਂ ਕਿਵੇਂ ਕਾਲ ਕਰਨੀ ਹੈ। -### ਟੂਲ ਚੇਨਿੰਗ ਦੀ ਜਾਂਚ ਕਰੋ +### ਸੰਦਾਂ ਦੀ ਲੜੀਖੇਪ ਦੀ ਟੈਸਟਿੰਗ ਕਰੋ -ਹੁਣ ਕੁਝ ਹੋਰ ਜਟਿਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ: "ਸੀਏਟਲ ਵਿੱਚ ਮੌਸਮ ਕੀ ਹੈ ਅਤੇ ਇਸਨੂੰ ਫੈਰਨਹਾਈਟ ਵਿੱਚ ਬਦਲੋ?" ਵੇਖੋ ਕਿ ਏਜੰਟ ਕਿਵੇਂ ਕਦਮ ਬਦਲ ਕੇ ਕੰਮ ਕਰਦਾ ਹੈ। ਪਹਿਲਾਂ ਇਹ ਮੌਸਮ ਲੈਂਦਾ ਹੈ (ਜੋ ਸੈਲਸੀਅਸ ਵਿੱਚ ਹੁੰਦਾ ਹੈ), ਫਿਰ ਸਮਝਦਾ ਹੈ ਕਿ ਫੈਰਨਹਾਈਟ ਵਿੱਚ ਬਦਲਣਾ ਪਵੇਗਾ, ਰੂਪਾਂਤਰਨ ਟੂਲ ਕਾਲ ਕਰਦਾ ਹੈ, ਅਤੇ ਦੋਹਾਂ ਨਤੀਜਿਆਂ ਨੂੰ ਇਕੱਠਾ ਕਰਕੇ ਇਕ ਜਵਾਬ ਦਿੰਦਾ ਹੈ। +ਹੁਣ ਕੁਝ ਵੱਧ ਜਟਿਲ ਕੋਸ਼ਿਸ਼ ਕਰੋ: "ਸੀਏਟਲ ਵਿੱਚ ਮੌਸਮ ਕੀ ਹੈ ਅਤੇ ਇਹਨੂੰ ਫੈਰਨਹਾਈਟ ਵਿੱਚ ਬਦਲੋ?" ਦੇਖੋ ਕਿ ਏਜੰਟ ਕਿਵੇਂ ਕਦਮ ਬਦ ਕਦਮ ਕੰਮ ਕਰਦਾ ਹੈ। ਸਭ ਤੋਂ ਪਹਿਲਾਂ ਇਹ ਮੌਸਮ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ (ਜੋ ਸੈਲਸਿਅਸ ਵਾਪਸ ਕਰਦਾ ਹੈ), ਫਿਰ ਇਹ ਸਮਝਦਾ ਹੈ ਕਿ ਇਸਨੂੰ ਫੈਰਨਹਾਈਟ ਵਿੱਚ ਬਦਲਣਾ ਹੈ, ਰੂਪਾਂਤਰਣ ਸੰਦ ਕਾਲ ਕਰਦਾ ਹੈ, ਅਤੇ ਦੋਵੇਂ ਨਤੀਜੇ ਇਕੱਠੇ ਕਰਕੇ ਇਕ ਜਵਾਬ ਦਿੰਦਾ ਹੈ। -### ਗੱਲਬਾਤ ਦਾ ਪ੍ਰਵੇਹ ਦੇਖੋ +### ਗੱਲਬਾਤ ਦਾ ਪ੍ਰਵੇਹ ਵੇਖੋ -ਚੈਟ ਇੰਟਰਫੇਸ ਗੱਲਬਾਤ ਦਾ ਇਤਿਹਾਸ ਸਾਂਭਦਾ ਹੈ, ਜਿਸ ਨਾਲ ਤੁਸੀਂ ਕਈ ਮੋਰਚਿਆਂ ਦੀ ਗੱਲਬਾਤ ਕਰ ਸਕਦੇ ਹੋ। ਤੁਸੀਂ ਸਾਰੇ ਪਿਛਲੇ ਸਵਾਲ ਅਤੇ ਜਵਾਬ ਵੇਖ ਸਕਦੇ ਹੋ, ਜੋ ਗੱਲਬਾਤ ਨੂੰ ਟ੍ਰੈਕ ਕਰਨ ਅਤੇ ਸਮਝਣ ਵਿੱਚ ਅਸਾਨੀ ਹੁੰਦੀ ਹੈ ਕਿ ਏਜੰਟ ਕਿਵੇਂ ਵੱਖ-ਵੱਖ ਮੋੜਾਂ 'ਤੇ ਸੰਦਰਭ ਬਣਾ ਰਿਹਾ ਹੈ। +ਚੈਟ ਇੰਟਰਫੇਸ ਗੱਲਬਾਤ ਦੇ ਇਤਿਹਾਸ ਨੂੰ ਰੱਖਦਾ ਹੈ, ਜੋ ਤੁਹਾਨੂੰ ਬਹੁ-ਮੁੜ ਅਦਾਨ-ਪ੍ਰਦਾਨ ਕਰਨ ਦੀ ਆਗਿਆ ਦਿੰਦਾ ਹੈ। ਤੁਸੀਂ ਸਾਰੀ ਪਿਛਲੀ ਬੇਨਤੀਆਂ ਅਤੇ ਜਵਾਬ ਵੇਖ ਸਕਦੇ ਹੋ, ਜਿਸ ਨਾਲ ਗੱਲਬਾਤ ਦਾ ਟਰੈਕ ਰੱਖਣਾ ਅਤੇ ਏਜੰਟ ਕਿਵੇਂ ਬਹੁ-ਵਾਰੀ ਸੰਦਰਭ ਬਣਾਉਂਦਾ ਹੈ, ਆਸਾਨ ਹੁੰਦਾ ਹੈ। -Conversation with Multiple Tool Calls +ਕਈ ਸੰਦ ਕਾਲਾਂ ਨਾਲ ਗੱਲਬਾਤ -*ਕਈ ਮੋੜਾਂ ਦੀ ਗੱਲਬਾਤ ਜਿਸ ਵਿੱਚ ਸਧਾਰਣ ਰੂਪਾਂਤਰਨ, ਮੌਸਮ ਦੀ ਜਾਂਚ ਅਤੇ ਟੂਲ ਚੇਨਿੰਗ ਦਰਸਾਈ ਗਈ ਹੈ* +*ਸੌਖੀਆਂ ਬਦਲਾਵਾਂ, ਮੌਸਮ ਦੀਆਂ ਲੁਕਪਾਂ ਅਤੇ ਸੰਦਾਂ ਦੀ ਲੜੀਖੇਪ ਦਿਖਾਉਂਦੀ ਬਹੁ-ਮੁੜ ਗੱਲਬਾਤ* -### ਵੱਖ-ਵੱਖ ਬੇਨਤੀਆਂ ਨਾਲ ਅਜ਼ਮਾਇਸ਼ ਕਰੋ +### ਵੱਖ-ਵੱਖ ਬੇਨਤੀਆਂ ਨਾਲ ਪ੍ਰਯੋਗ ਕਰੋ -ਕਈ ਕਿਸਮਾਂ ਦੀਆਂ ਬੇਨਤੀਆਂ ਕੋਸ਼ਿਸ਼ ਕਰੋ: -- ਮੌਸਮ ਦੀ ਜਾਂਚ: "ਟੋਕੀਓ ਵਿੱਚ ਮੌਸਮ ਕੀ ਹੈ?" -- ਤਾਪਮਾਨ ਰੂਪਾਂਤਰਨ: "25°C ਕਿਵਲਿਨ ਵਿੱਚ ਕਿੰਨਾ ਹੈ?" -- ਮਿਲੀਆਂ ਜੁਲੀਆਂ ਬੇਨਤੀਆਂ: "ਪੈਰਿਸ ਵਿੱਚ ਮੌਸਮ ਦੀ ਜਾਂਚ ਕਰੋ ਅਤੇ ਦੱਸੋ ਕਿ ਕੀ ਇਹ 20°C ਤੋਂ ਉੱਪਰ ਹੈ" +ਵਿਭਿੰਨ ਸੰਯੋਜਨਾਂ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰੋ: +- ਮੌਸਮ ਦੀ ਜਾਣਕਾਰੀ: "ਟੋਕਿਓ ਵਿੱਚ ਮੌਸਮ ਕੀ ਹੈ?" +- ਤਾਪਮਾਨ ਰੂਪਾਂਤਰਣ: "25°C ਕੈਲਵਿਨ ਵਿੱਚ ਕਿੰਨਾ ਹੈ?" +- ਜੋੜੀਆਂ ਬੇਨਤੀਆਂ: "ਪੈਰਿਸ ਵਿੱਚ ਮੌਸਮ ਦੀ ਜਾਂਚ ਕਰੋ ਅਤੇ ਦੱਸੋ ਕਿ ਕੀ ਇਹ 20°C ਤੋਂ ਵੱਧ ਹੈ" -ਧਿਆਨ ਦਿਓ ਕਿ ਏਜੰਟ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਨੂੰ ਕਿਵੇਂ ਸਮਝਦਾ ਹੈ ਅਤੇ ਸਹੀ ਟੂਲ ਕਾਲਾਂ ਨਾਲ ਜੋੜਦਾ ਹੈ। +ਵੇਖੋ ਕਿ ਏਜੰਟ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਨੂੰ ਕਿਵੇਂ ਸਮਝਦਾ ਹੈ ਅਤੇ ਉਚਿਤ ਸੰਦ ਕਾਲਾਂ ਨਾਲ ਮੈਪ ਕਰਦਾ ਹੈ। -## ਮੁੱਖ ਧਾਰਣਾਵਾਂ +## ਮੁੱਖ ਧਾਰਾਵਾਂ -### ReAct ਪੈਟਰਨ (ਸੋਚਣ ਅਤੇ ਕਰਵਾਈ) +### ReAct ਪੈਟਰਨ (ਤਰੱਕੀ ਅਤੇ ਕਾਰਵਾਈ) -ਏਜੰਟ ਸੋਚ-ਵਿਚਾਰ (ਕੀ ਕਰਨਾ ਹੈ) ਅਤੇ ਕਾਰਵਾਈ (ਟੂਲਾਂ ਦੀ ਵਰਤੋਂ) ਵਿਚਕਾਰ ਪਰਿਵਰਤਨ ਕਰਦਾ ਹੈ। ਇਹ ਡਿੱਗਰੀਆ-ਸਮੱਸਿਆ ਹੱਲ ਕਰਨ ਸਮਰੱਥਾ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ ਨਾ ਕਿ ਸਿਰਫ ਹੁਕਮਾਂ 'ਤੇ ਜਵਾਬ ਦੇਣਾ। +ਏਜੰਟ ਸੋਚ (ਇਹ ਕਰਨ ਦਾ ਫ਼ੈਸਲਾ ਕਰਨਾ) ਅਤੇ ਕਾਰਵਾਈ (ਸੰਦਾਂ ਦੀ ਵਰਤੋਂ) ਵਿੱਚ ਬਦਲਦਾ ਰਹਿੰਦਾ ਹੈ। ਇਹ ਪੈਟਰਨ ਸਿਰਫ ਹੁਕਮਾਂ ਦਾ ਉੱਤਰ ਦੇਣ ਦੀ ਬਜਾਏ ਸਵੈ-ਨਿਰਭਰ ਸਮੱਸਿਆ ਸਮਾਧਾਨ ਕਰਨ ਦੀ ਯੋਗਤਾ ਦਿੰਦਾ ਹੈ। -### ਟੂਲ ਵਰਣਨਾਂ ਮਹੱਤਵਪੂਰਨ ਹੁੰਦੀਆਂ ਹਨ +### ਸੰਦਾਂ ਦਾ ਵਰਣਨ ਮਹੱਤਵਪੂਰਨ ਹੈ -ਟੂਲ ਦੀਆਂ ਵਰਣਨਾਂ ਦੀ ਗੁਣਵੱਤਾ ਇਹ ਦਰਸਾਉਂਦੀ ਹੈ ਕਿ ਏਜੰਟ ਕਿਵੇਂ ਬਿਹਤਰ ਇਸਨੂੰ ਵਰਤਦਾ ਹੈ। ਸਾਫ਼ ਅਤੇ ਵਿਸ਼ੇਸ਼ ਵਰਣਨਾਂ ਮਾਡਲ ਨੂੰ ਸਮਝਾਉਂਦੀਆਂ ਹਨ ਕਿ ਕਦੋਂ ਤੇ ਕਿਵੇਂ ਹਰ ਟੂਲ ਕਾਲ ਕਰਨੀ ਹੈ। +ਤੁਹਾਡੇ ਸੰਦਾਂ ਦੇ ਵਰਣਨ ਦੀ ਗੁਣਵੱਤਾ ਸੀਧਾ ਪ੍ਰਭਾਵ ਪਾਉਂਦੀ ਹੈ ਕਿ ਏਜੰਟ ਉਹਨਾਂ ਨੂੰ ਕਿਵੇਂ ਵਰਤਦਾ ਹੈ। ਸਾਫ਼, ਵਿਸ਼ੇਸ਼ ਵਰਣਨਾਂ ਮਾਡਲ ਨੂੰ ਸਮਝਣ ਵਿੱਚ ਮਦਦ ਕਰਦੀਆਂ ਹਨ ਕਿ ਕਦੋਂ ਅਤੇ ਕਿਵੇਂ ਹਰ ਸੰਦ ਨੂੰ ਕਾਲ ਕਰਨਾ ਹੈ। ### ਸੈਸ਼ਨ ਪ੍ਰਬੰਧਨ -`@MemoryId` ਐਨੋਟੇਸ਼ਨ ਆਟੋਮੈਟਿਕ ਸੈਸ਼ਨ-ਅਧਾਰਿਤ ਯਾਦਦਾਸ਼ਤ ਪ੍ਰਬੰਧਨ ਯੋਗ ਬਣਾਉਂਦਾ ਹੈ। ਪ੍ਰਤੀਕ ਸੈਸ਼ਨ ID ਦਾ ਇੱਕ ਵਿਲੱਖਣ `ChatMemory` ਇਨਸਟੈਂਸ ਹੁੰਦਾ ਹੈ ਜੋ `ChatMemoryProvider` ਬੀਨ ਵੱਲੋਂ ਪ੍ਰਬੰਧਿਤ ਹੁੰਦਾ ਹੈ, ਜਿਸ ਨਾਲ ਕਈ ਯੂਜ਼ਰ ਇਕੱਠੇ ਏਜੰਟ ਨਾਲ ਗੱਲਬਾਤ ਕਰ ਸਕਦੇ ਹਨ ਬਿਨਾਂ ਇੱਕ ਦੂਜੇ ਦੀ ਗੱਲਬਾਤ ਮਿਲੇ। ਹੇਠਾਂ ਦਿੱਤੀ ਚਿੱਤਰਕਲਾ ਦਿਖਾਉਂਦੀ ਹੈ ਕਿ ਕਿਵੇਂ ਕਈ ਯੂਜ਼ਰਾਂ ਨੂੰ ਵੱਖ-ਵੱਖ ਯਾਦਦਾਸ਼ਤ ਸਟੋਰਾਂ 'ਚ ਭੇਜਿਆ ਜਾਂਦਾ ਹੈ ਉਹਨਾਂ ਦੇ ਸੈਸ਼ਨ ID ਦੇ ਅਧਾਰ 'ਤੇ: +`@MemoryId` ਐਨੋਟੇਸ਼ਨ ਆਟੋਮੈਟਿਕ ਸੈਸ਼ਨ-ਆਧਾਰਿਤ ਮੈਮੋਰੀ ਪ੍ਰਬੰਧਨ ਯੋਗ ਬਣਾਉਂਦਾ ਹੈ। ਹਰ ਸੈਸ਼ਨ ID ਨੂੰ ਆਪਣਾ `ChatMemory` ਸਥਾਪਿਤ ਕੀਤਾ ਜਾਂਦਾ ਹੈ ਜੋ `ChatMemoryProvider` ਬੀਨ ਦੁਆਰਾ ਪ੍ਰਬੰਧਿਤ ਹੁੰਦਾ ਹੈ, ਤਾਂ ਕਿ ਕਈ ਯੂਜ਼ਰ ਇਕੱਠੇ ਏਜੰਟ ਨਾਲ ਗੱਲਬਾਤ ਕਰ ਸਕਣ ਬਿਨਾਂ ਆਪਣੀਆਂ ਗੱਲਾਂ ਨੂੰ ਮਿਲਾਏ। ਹੇਠਾਂ ਦਿੱਤਾ ਪ੍ਰਣਾਲੀ ਦਰਸਾਉਂਦਾ ਹੈ ਕਿ ਕਿਵੇਂ ਕਈ ਯੂਜ਼ਰਾਂ ਨੂੰ ਉਹਨਾ ਦੀਆਂ ਸੈਸ਼ਨ ID ਦੇ ਆਧਾਰ 'ਤੇ ਇਸੋਲੇਟਡ ਮੈਮੋਰੀ ਸਟੋਰਾਂ ਵੱਲ ਰੂਟ ਕੀਤਾ ਜਾਂਦਾ ਹੈ: -Session Management with @MemoryId +@MemoryId ਨਾਲ ਸੈਸ਼ਨ ਪ੍ਰਬੰਧਨ -*ਹਰ ਸੈਸ਼ਨ ID ਇੱਕ ਵੱਖਰੀ ਗੱਲਬਾਤ ਇਤਿਹਾਸ ਨਾਲ ਜੋੜੀ ਜਾਂਦੀ ਹੈ — ਯੂਜ਼ਰ ਕਦੇ ਇੱਕ ਦੂਜੇ ਦੇ ਸੁਨੇਹੇ ਨਹੀਂ ਵੇਖਦੇ।* +*ਹਰ ਸੈਸ਼ਨ ID ਇੱਕ ਅਲੱਗ ਗੱਲਬਾਤ ਇਤਿਹਾਸ ਨਾਲ ਜੁੜਿਆ ਹੁੰਦਾ ਹੈ — ਯੂਜ਼ਰ ਕਦੇ ਵੀ ਦੂਜੇ ਦੇ ਸੁਨੇਹੇ ਨਹੀਂ ਵੇਖਦੇ।* ### ਗਲਤੀ ਸੰਭਾਲਣਾ -ਟੂਲ ਫੇਲ ਹੋ ਸਕਦੇ ਹਨ — API ਸਮੇਂ ਤੋਂ ਬਾਅਦ ਬੰਦ ਹੋ ਸਕਦੇ ਹਨ, ਪੈਰਾਮੀਟਰ ਗਲਤ ਹੋ ਸਕਦੇ ਹਨ, ਬਾਹਰੀ ਸੇਵਾਵਾਂ ਡਾਊਨ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਪ੍ਰੋਡਕਸ਼ਨ ਏਜੰਟਾਂ ਲਈ ਗਲਤੀ ਸੰਭਾਲਣ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ ਤਾਂ ਜੋ ਮਾਡਲ ਸਮੱਸਿਆ ਨੂੰ ਸਮਝਾ ਸਕੇ ਜਾਂ ਵਿਕਲਪਾਂ ਦੀ ਕੋਸ਼ਿਸ਼ ਕਰ ਸਕੇ ਨਾ ਕਿ ਸਾਰੇ ਐਪਲੀਕੇਸ਼ਨ ਨੂੰ ਬੰਧ ਕਰ ਦੇਵੇ। ਜਦੋਂ ਕੋਈ ਟੂਲ(exception) ਛੱਡਦਾ ਹੈ, LangChain4j ਉਸ ਨੂੰ ਫੜਦਾ ਹੈ ਅਤੇ ਗਲਤੀ ਦਾ ਸੁਨੇਹਾ ਮਾਡਲ ਨੂੰ ਦੇ ਦਿੰਦਾ ਹੈ, ਜੋ ਫਿਰ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਵਿੱਚ ਸਮੱਸਿਆ ਦਰਸਾ ਸਕਦਾ ਹੈ। +ਸੰਦ ਅਸਫਲ ਹੋ ਸਕਦੇ ਹਨ — APIs ਸਮਾਂ ਸੀਮਾ ਤੋਂ ਬਾਹਰ ਹੋ ਜاندੀਆਂ ਹਨ, ਪੈਰਾਮੀਟਰ ਗਲਤ ਹੋ ਸਕਦੇ ਹਨ, ਬਾਹਰੀ ਸੇਵਾਵਾਂ ਡਾਊਨ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਉਤਪਾਦਕ ਏਜੰਟਾਂ ਨੂੰ ਗਲਤੀ ਸੰਭਾਲਣ ਦੀ ਲੋੜ ਹੁੰਦੀ ਹੈ ਤਾਂ ਜੋ ਮਾਡਲ ਸਮੱਸਿਆਵਾਂ ਨੂੰ ਸਮਝਾ ਸਕੇ ਜਾਂ ਵਿਕਲਪਾਂ ਕੋਸ਼ਿਸ਼ ਕਰ ਸਕੇ ਬਿਨਾਂ ਸਾਰੀ ਐਪਲੀਕੇਸ਼ਨ ਨੂੰ ਡਿੱਗਾਏ। ਜਦੋਂ ਕੋਈ ਸੰਦ ਐਕਸੈਪਸ਼ਨ ਸੁੱਟਦਾ ਹੈ, ਤਾਂ LangChain4j ਇਸਨੂੰ ਫੜਦਾ ਹੈ ਅਤੇ ਗਲਤੀ ਸੁਨੇਹਾ ਮਾਡਲ ਨੂੰ ਵਾਪਸ ਭੇਜਦਾ ਹੈ, ਜੋ ਫਿਰ ਕੁਦਰਤੀ ਭਾਸ਼ਾ ਵਿੱਚ ਸਮੱਸਿਆ ਦਾ ਵਿਵਰਣ ਕਰ ਸਕਦਾ ਹੈ। -## ਉਪਲਬਧ ਟੂਲ +## ਉਪਲੱਬਧ ਸੰਦ -ਹੇਠਾਂ ਦਿੱਤੀ ਚਿੱਤਰਕਲਾ ਤੁਹਾਨੂੰ ਇਮਕਾਨ ਦਿੱਤੀ ਟੂਲਾਂ ਦਾ ਵਿਆਪਕ ਪਰਿਚਯ ਦਿੰਦੀ ਹੈ। ਇਹ ਮੋਡੀਊਲ ਮੌਸਮ ਅਤੇ ਤਾਪਮਾਨ ਟੂਲਾਂ ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ, ਪਰ ਉਹੀ `@Tool` ਪੈਟਰਨ ਕਿਸੇ ਵੀ ਜਾਵਾ ਵਿਧੀ ਲਈ ਕੰਮ ਕਰਦਾ ਹੈ — ਡੇਟਾਬੇਸ ਕੁਐਰੀ ਤੋਂ लेकर ਭੁਗਤਾਨ ਪ੍ਰਕਿਰਿਆ ਤੱਕ। +ਹੇਠਾਂ ਦਿੱਤੀ ਪ੍ਰਣਾਲੀ ਸੰਦਾਂ ਦੇ ਵਿਸ਼ਾਲ ਪਰਿਵਰਤਨ ਨੂੰ ਦਰਸਾਉਂਦੀ ਹੈ ਜੋ ਤੁਸੀਂ ਬਣਾ ਸਕਦੇ ਹੋ। ਇਹ ਮੋਡੀਊਲ ਮੌਸਮ ਅਤੇ ਤਾਪਮਾਨ ਸੰਦ ਦਿਖਾਉਂਦਾ ਹੈ, ਪਰ ਉਹੀ `@Tool` ਪੈਟਰਨ ਕਿਸੇ ਵੀ ਜਾਵਾ ਮੈਥਡ ਲਈ ਕੰਮ ਕਰਦਾ ਹੈ — ਡੇਟਾਬੇਸ ਪੁੱਛਗਿੱਛ ਤੋਂ ਲੈ ਕੇ ਭੁਗਤਾਨ ਪ੍ਰਕਿਰਿਆ ਤਕ। -Tool Ecosystem +ਸੰਦ ਪਰਿਵਰਤਨ -*ਕੋਈ ਵੀ ਜਾਵਾ ਵਿਧੀ ਜਿਸ ਨਾਲ @Tool ਐਨੋਟੇਟ ਕੀਤੀ ਗਈ ਹੋਏ, AI ਲਈ ਉਪਲਬਧ ਹੋ ਜਾਂਦੀ ਹੈ — ਪੈਟਰਨ ਡੇਟਾਬੇਸ, API, ਈਮੇਲ, ਫਾਇਲ ਆਪਰੇਸ਼ਨਜ਼ ਅਤੇ ਹੋਰ ਲਈ ਵਧਦਾ ਹੈ।* +*ਕੋਈ ਵੀ ਜਾਵਾ ਮੈਥਡ ਜਿਹੜਾ @Tool ਨਾਲ ਐਨੋਟੇਟ ਕੀਤਾ ਗਿਆ ਹੈ, ਏਆਈ ਲਈ ਉਪਲੱਬਧ ਬਣਦਾ ਹੈ — ਇਹ ਪੈਟਰਨ ਡੇਟਾਬੇਸ, APIs, ਈਮੇਲ, ਫਾਇਲ ਓਪਰੇਸ਼ਨਾਂ ਵਗੈਰਾ ਤੱਕ ਵਿਸਥਾਰਤ ਹੈ।* -## ਟੂਲ-ਅਧਾਰਿਤ ਏਜੰਟ ਕਦੋਂ ਵਰਤਣੇ +## ਕਦੋਂ ਸੰਦ-ਆਧਾਰਿਤ ਏਜੰਟ ਵਰਤਣੇ -ਹਰ ਬੇਨਤੀ ਨੂੰ ਟੂਲਾਂ ਦੀ ਲੋੜ ਨਹੀਂ ਹੁੰਦੀ। ਫੈਸਲਾ ਇਹ ਹੋਦਾ ਹੈ ਕਿ ਕਿ AI ਨੂੰ ਬਾਹਰੀ ਪ੍ਰਣਾਲੀਆਂ ਨਾਲ ਗੱਲ ਕਰਨੀ ਹੈ ਜਾਂ ਆਪਣੀ ਜਾਣਕਾਰੀ ਤੋਂ ਜਵਾਬ ਦੇ ਸਕਦਾ ਹੈ। ਹੇਠਾਂ ਦਿੱਤਾ ਗਾਈਡ ਸਾਰ ਕਰਦਾ ਹੈ ਕਿ ਕਦੋਂ ਟੂਲ ਮਹੱਤਵਪੂਰਨ ਹੁੰਦੇ ਹਨ ਅਤੇ ਕਦੋਂ ਉਹਨਾਂ ਦੀ ਲੋੜ ਨਹੀਂ: +ਹਰ ਬੇਨਤੀ ਨੂੰ ਸੰਦਾਂ ਦੀ ਲੋੜ ਨਹੀਂ ਹੁੰਦੀ। ਫੈਸਲਾ ਇਸ ਗੱਲ 'ਤੇ ਨਿਰਭਰ ਕਰਦਾ ਹੈ ਕਿ ਕੀ ਏਆਈ ਨੂੰ ਬਾਹਰੀ ਪ੍ਰਣਾਲੀਆਂ ਨਾਲ ਇੰਟਰੈਕਟ ਕਰਨ ਦੀ ਜ਼ਰੂਰਤ ਹੈ ਜਾਂ ਇਹ ਆਪਣੀ ਜ਼ਾਨਕਾਰੀ ਤੋਂ ਜਵਾਬ ਦੇ ਸਕਦਾ ਹੈ। ਹੇਠਾਂ ਦਿੱਤਾ ਗਾਈਡ ਸੰਖੇਪ ਕਰਦਾ ਹੈ ਕਿ ਕਦੋਂ ਸੰਦਾਂ ਮੁੱਲ ਜੋੜਦੇ ਹਨ ਅਤੇ ਕਦੋਂ ਉਹ ਬੇਲੋੜੇ ਹੁੰਦੇ ਹਨ: -When to Use Tools +ਕਦੋਂ ਸੰਦ ਵਰਤੇ ਜਾਣ -*ਇੱਕ ਤੇਜ਼ ਫੈਸਲਾ ਗਾਈਡ — ਟੂਲ ਤੁਰੰਤ ਡਾਟਾ, ਗਣਨਾ, ਅਤੇ ਕਾਰਵਾਈ ਲਈ; ਆਮ ਗਿਆਨ ਅਤੇ ਰਚਨਾਤਮਕ ਕੰਮਾਂ ਲਈ ਲੋੜ ਨਹੀਂ।* +*ਇੱਕ ਤੇਜ਼ ਫੈਸਲਾ ਮਾਰਗਦਰਸ਼ਕ — ਸੰਦ ਸਮੇਂ-ਸਮੇਂ ਦੇ ਡੇਟਾ, ਗਣਨਾਵਾਂ ਅਤੇ ਕਿਰਿਆਵਾਂ ਲਈ ਹਨ; ਆਮ ਗਿਆਨ ਅਤੇ ਰਚਨਾਤਮਕ ਕੰਮਾਂ ਲਈ ਲੋੜ ਨਹੀਂ।* -## ਟੂਲਜ਼ ਵੱਲੋਂ RAG ਨਾਲ ਤੁਲਨਾ +## ਸੰਦ ਬਨਾਮ RAG -ਮੋਡੀਊਲ 03 ਅਤੇ 04 ਦੋਹਾਂ AI ਦੀ ਯੋਗਤਾ ਵਧਾਉਂਦੇ ਹਨ, ਪਰ ਬੁਨਿਆਦੀ ਤੌਰ 'ਤੇ ਵੱਖਰੇ ਤਰੀਕੇ ਨਾਲ। RAG ਮਾਡਲ ਨੂੰ **ਗਿਆਨ** ਦਸਤਾਵੇਜ਼ ਪਰਾਪਤ ਕਰਕੇ ਪ੍ਰਦਾਨ ਕਰਦਾ ਹੈ। ਟੂਲ ਮਾਡਲ ਨੂੰ ਕਾਰਵਾਈਆਂ ਕਰਨ ਦੀ ਸਮਰੱਥਾ ਦਿੰਦੇ ਹਨ ਫੰਕਸ਼ਨ ਕਾਲ ਕਰਕੇ। ਹੇਠਾਂ ਦਿੱਤੀ ਚਿੱਤਰਕਲਾ ਇਹ ਦੋਹਾਂ ਪদ্ধਤੀਆਂ ਦੇ ਸਾਈਡ-ਬਾਈ-ਸਾਈਡ ਤੁਲਨਾ ਕਰਦੀ ਹੈ — ਕਿ ਹਰ ਵਰਕਫਲੋ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ ਅਤੇ ਇਹਨਾਂ ਦੇ ਵਿਚਕਾਰ ਕਿਹੜੇ ਫਾਇਦੇ ਅਤੇ ਘਾਟ ਹਨ: +ਮੋਡੀਊਲ 03 ਅਤੇ 04 ਦੋਵਾਂ ਏਆਈ ਦੀ ਸਮਰੱਥਾ ਵਧਾਉਂਦੇ ਹਨ, ਪਰ ਬੀਨ੍ਹਦਾਰੀ ਤੌਰ 'ਤੇ ਵੱਖਰੇ ਤਰੀਕਿਆਂ ਨਾਲ। RAG ਮਾਡਲ ਨੂੰ **ਜਾਣਕਾਰੀ** ਤੱਕ ਪਹੁੰਚ ਦਿੰਦਾ ਹੈ ਦਸਤਾਵੇਜ਼ ਪ੍ਰਾਪਤ ਕਰਕੇ। ਸੰਦ ਮਾਡਲ ਨੂੰ **ਕਿਰਿਆਵਾਂ** ਕਰਨ ਦੀ ਕਾਬਲੀਅਤ ਦਿੰਦੇ ਹਨ ਫੰਕਸ਼ਨਾਂ ਨੂੰ ਕਾਲ ਕਰਕੇ। ਹੇਠਾਂ ਦਿੱਤੇ ਗਏ ਪਰਿਚਾਰ੍ਹਾ ਤੌਰ ਤੇ ਇਨ੍ਹਾਂ ਦੋਹਾਂ ਤਰੀਕਿਆਂ ਦੀ ਤੁਲਨਾ ਕੀਤੀ ਗਈ ਹੈ — ਕਿਵੇਂ ਹਰ ਵਰਕਫਲੋ ਚੱਲਦਾ ਹੈ ਤੇ ਇਨ੍ਹਾਂ ਦੇ ਵਿਚਕਾਰ ਟਰੇਡ-ਆਫ਼: -Tools vs RAG Comparison +ਸੰਦ ਬਨਾਮ RAG ਤੁਲਨਾ -*RAG ਸਥਿਰ ਦਸਤਾਵੇਜ਼ਾਂ ਤੋਂ ਜਾਣਕਾਰੀ ਲੈਂਦਾ ਹੈ — ਟੂਲ ਕਾਰਵਾਈ ਕੱਢਦੇ ਹਨ ਅਤੇ ਗਤੀਸ਼ੀਲ, ਤੁਰੰਤ ਡਾਟਾ ਪ੍ਰਾਪਤ ਕਰਦੇ ਹਨ। ਬਹੁਤ ਸਾਰੇ ਪ੍ਰੋਡਕਸ਼ਨ ਸਿਸਟਮ ਦੋਹਾਂ ਜੋੜਦੇ ਹਨ।* +*RAG ਸਥਿਰ ਦਸਤਾਵੇਜ਼ਾਂ ਤੋਂ ਜਾਣਕਾਰੀ ਲੈਂਦਾ ਹੈ — ਸੰਦ ਕਿਰਿਆਵਾਂ ਨੂੰ ਅੰਜਾਮ ਦਿੰਦੇ ਹਨ ਅਤੇ ਗਤੀਸ਼ੀਲ, ਹਕੀਕਤੀ ਸਵੇਰੇ ਲਿਆਉਂਦੇ ਹਨ। ਬਹੁਤ سارੀਆਂ ਉਤਪਾਦਕ ਪ੍ਰਣਾਲੀਆਂ ਦੋਹਾਂ ਨੂੰ ਮਿਲਾਕੇ ਵਰਤਦੀਆਂ ਹਨ।* -ਅਮਲੀ ਜੀਵਨ ਵਿੱਚ, ਬਹੁਤੇ ਪ੍ਰੋਡਕਸ਼ਨ ਸਿਸਟਮ ਦੋਹਾਂ ਤਰੀਕਿਆਂ ਨੂੰ ਜੋੜਦੇ ਹਨ: RAG ਤੁਹਾਡੇ ਦਸਤਾਵੇਜ਼ਾਂ ਵਿੱਚ ਜਵਾਬਾਂ ਦਾ ਮੂਲ ਦਿੰਦਾ ਹੈ, ਅਤੇ ਟੂਲ ਲਾਈਵ ਡਾਟਾ ਪ੍ਰਾਪਤ ਕਰਨ ਜਾਂ ਕਾਰਵਾਈ ਕਰਨ ਲਈ। +ਅਮਲ ਵਿੱਚ, ਬਹੁਤ ਸਾਰੀਆਂ ਉਤਪਾਦਕ ਪ੍ਰਣਾਲੀਆਂ ਦੋਹਾਂ ਤਰੀਕਿਆਂ ਨੂੰ ਮਿਲਾਕੇ ਵਰਤਦੀਆਂ ਹਨ: RAG ਆਪਣੇ ਦਸਤਾਵੇਜ਼ੀਕਰਨ ਵਿੱਚ ਜਵਾਬਾਂ ਨੂੰ ਧਰਤ 'ਤੇ ਮਿਲਾਉਣ ਲਈ, ਅਤੇ ਸੰਦ ਜିਵੰਤ ਡੇਟਾ ਫੈਚ ਕਰਨ ਜਾਂ ਕਾਰਵਾਈ ਕਰਨ ਲਈ। ## ਅਗਲੇ ਕਦਮ @@ -377,11 +377,11 @@ cd ..; .\stop-all.ps1 # ਸਾਰੇ ਮਾਡਿਊਲ --- -**ਨੈਵੀਗੇਸ਼ਨ:** [← ਪਹਿਲਾਂ: ਮੋਡੀਊਲ 03 - RAG](../03-rag/README.md) | [ਮੁੱਖ ਪੰਨੇ ਤੇ ਵਾਪਸ](../README.md) | [ਅਗਲਾ: ਮੋਡੀਊਲ 05 - MCP →](../05-mcp/README.md) +**ਨੈਵੀਗੇਸ਼ਨ:** [← ਪਹਿਲਾ: ਮੋਡੀਊਲ 03 - RAG](../03-rag/README.md) | [ਵਾਪਸ ਮੁੱਖ](../README.md) | [ਅਗਲਾ: ਮੋਡੀਊਲ 05 - MCP →](../05-mcp/README.md) --- -**ਰਾਖੀ** -ਇਸ ਦਸਤਾਵੇਜ਼ ਦਾ ਅਨੁਵਾਦ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਵਿੱਚ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਮਰੱਥਤਾਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਇਸ ਦੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਹੀ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਜਰੂਰੀ ਜਾਣਕਾਰੀ ਲਈ, ਵਿਸ਼ੇਸ਼ਗਿਆਨ ਵਾਲੇ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੀ ਵਰਤੋਂ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੇ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀ ਜਾਂ ਗਲਤ ਸਮਝ ਲਈ ਜ਼ਿੰਮੇਵਾਰ ਨਹੀਂ ਹਾਂ। +**ਅਸਵੀਕਾਰੋਪਣ**: +ਇਸ ਦਸਤਾਵੇਜ਼ ਦਾ ਅਨੁਵਾਦ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾਵਾਂ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਮੱਤਿਆਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਜਰੂਰੀ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੇ ਉਪਯੋਗ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਗਲਤ ਵਿਆਖਿਆਵਾਂ ਲਈ ਜਵਾਬਦੇਹ ਨਹੀਂ ਹਾਂ। \ No newline at end of file diff --git a/translations/pa/README.md b/translations/pa/README.md index 9f163657b..085379a6c 100644 --- a/translations/pa/README.md +++ b/translations/pa/README.md @@ -1,19 +1,19 @@ LangChain4j -# ਸ਼ੁਰੂਆਤੀ ਵਾਸਤੇ LangChain4j +# ਸ਼ੁਰੂਆਤੀ ਲਈ LangChain4j -LangChain4j ਅਤੇ Azure OpenAI GPT-5.2 ਨਾਲ AI ਐਪਲੀਕੇਸ਼ਨਾਂ ਬਣਾਉਣ ਲਈ ਇੱਕ ਕੋਰਸ, ਬੁਨਿਆਦੀ ਚੈਟ ਤੋਂ ਲੈਕੇ AI ਏਜੰਟਾਂ ਤੱਕ। +LangChain4j ਅਤੇ Azure OpenAI GPT-5.2 ਨਾਲ AI ਐਪਲੀਕੇਸ਼ਨ ਬਣਾਉਣ ਲਈ ਇੱਕ ਕੋਰਸ, ਬੇਸਿਕ ਚੈਟ ਤੋਂ ਲੈ ਕੇ AI ਏਜੰਟ ਤੱਕ। -### 🌐 ਬਹੁਭਾਸ਼ਾ ਸਹਾਇਤਾ +### 🌐 ਬਹੁਭਾਸ਼ੀ ਸਹਿਯੋਗ -#### GitHub Action ਰਾਹੀਂ ਸਮਰਥਿਤ (ਆਟੋਮੈਟਿਕ & ਹਮੇਸ਼ਾ ਅਪ-ਟੂ-ਡੇਟ) +#### GitHub ਐਕਸ਼ਨ ਰਾਹੀਂ ਸਮਰਥਿਤ (ਸਵੈਚਾਲਿਤ ਅਤੇ ਹਮੇਸ਼ਾ ਅਪ-ਟੂ-ਡੇਟ) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](./README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **ਸਥਾਨਕ ਕਲੋਨ ਕਰਨਾ ਪਸੰਦ ਹੈ?** +> **ਸਥਾਨਕ ਕਲੋਨ ਕਰਨਾ ਪਸੰਦ ਕਰੋ?** > -> ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਵਿੱਚ 50+ ਭਾਸ਼ਾ ਤਰਜਮਿਆਂ ਸ਼ਾਮਲ ਹਨ ਜੋ ਡਾਊਨਲੋਡ ਅਕਾਰ ਨੂੰ ਕਾਫੀ ਵਧਾ ਦਿੰਦੇ ਹਨ। ਬਿਨਾਂ ਤਰਜਮਿਆਂ ਦੇ ਕਲੋਨ ਕਰਨ ਲਈ, sparse checkout ਵਰਤੋ: +> ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਵਿੱਚ 50+ ਭਾਸ਼ਾ ਅਨੁਵਾਦ ਸ਼ਾਮਲ ਹਨ ਜੋ ਡਾਊਨਲੋਡ ਦਾ ਆਕਾਰ ਕਾਫੀ ਵਧਾ ਦਿੰਦੇ ਹਨ। ਅਨੁਵਾਦਾਂ ਤੋਂ ਬਿਨਾਂ ਕਲੋਨ ਕਰਨ ਲਈ sparse checkout ਵਰਤੋ: > > **Bash / macOS / Linux:** > ```bash @@ -29,62 +29,63 @@ LangChain4j ਅਤੇ Azure OpenAI GPT-5.2 ਨਾਲ AI ਐਪਲੀਕੇਸ਼ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> ਇਹ ਤੁਹਾਨੂੰ ਤੇਜ਼ ਡਾਊਨਲੋਡ ਨਾਲ ਕੋਰਸ ਨੂੰ ਪੂਰਾ ਕਰਨ ਲਈ ਸਭ ਕੁਝ ਦਿੰਦਾ ਹੈ। +> ਇਹ ਤੁਹਾਨੂੰ ਕੋਰਸ ਪੂਰਾ ਕਰਨ ਲਈ ਸਭ ਕੁਝ ਦੇਵੇਗਾ ਬਹੁਤ ਤੇਜ਼ ਡਾਊਨਲੋਡ ਨਾਲ। -## ਸੂਚੀ ਸਾਰਣੀ +## ਸੂਚੀ ਸਿਰਲੇਖ -1. [ਤੁਰੰਤ ਸ਼ੁਰੂਆਤ](00-quick-start/README.md) - LangChain4j ਨਾਲ ਸ਼ੁਰੂ ਕਰੋ -2. [ਪਰਚਾਇ](01-introduction/README.md) - LangChain4j ਦੇ ਮੁਢਲੀ ਗੱਲਾਂ ਸਿੱਖੋ -3. [ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](02-prompt-engineering/README.md) - ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਪ੍ਰਾਂਪਟ ਡਿਜ਼ਾਈਨ ਸਿੱਖੋ -4. [RAG (ਰਿਟਰੀਵਲ-ਆਗਮੈਂਟੇਡ ਜਨਰੇਸ਼ਨ)](03-rag/README.md) - ਸਮਝਦਾਰ ਗਿਆਨ ਅਧਾਰਿਤ ਸਿਸਟਮ ਬਣਾਓ -5. [ਟੂਲਜ਼](04-tools/README.md) - ਬਾਹਰੀ ਟੂਲ ਅਤੇ ਸਧਾਰਣ ਸਹਾਇਕ ਜੋੜੋ -6. [MCP (ਮਾਡਲ ਕੌਂਟੈਕਸਟ ਪ੍ਰੋਟੋਕੋਲ)](05-mcp/README.md) - ਮਾਡਲ ਕੌਂਟੈਕਸਟ ਪ੍ਰੋਟੋਕੋਲ (MCP) ਅਤੇ ਏਜੈਂਟਿਕ ਮੋਡੀਊਲਾਂ ਨਾਲ ਕੰਮ ਕਰੋ +1. [ਰੂਪਰੇਖਾ](01-introduction/README.md) - LangChain4j ਦੇ ਮੂਲ ਸਿਖੋ +2. [ਪ੍ਰੋਮਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](02-prompt-engineering/README.md) - ਪ੍ਰਭਾਵਸ਼ਾਲੀ ਪ੍ਰੋਮਪਟ ਡਿਜ਼ਾਈਨ ਮਾਹਰ ਬਣੋ +3. [RAG (ਰਿਕਵਲੀਉਲ-ਅਗਮੈਂਟਡ ਜਨੇਰੇਸ਼ਨ)](03-rag/README.md) - ਸਮਾਰਟ ਗਿਆਨ ਅਧਾਰਿਤ ਪ੍ਰਣਾਲੀਆਂ ਬਣਾਓ +4. [ਟੂਲ](04-tools/README.md) - ਬਾਹਰੀ ਯੰਤਰਾਂ ਅਤੇ ਸਾਦਾ ਸਹਾਇਕਾਂ ਨੂੰ ਜੋੜੋ +5. [MCP (ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰੋਟੋਕੋਲ)](05-mcp/README.md) - ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰੋਟੋਕੋਲ (MCP) ਅਤੇ ਏਜੈਂਟਿਕ ਮਾਡਿਊਲ ਨਾਲ ਕੰਮ ਕਰੋ -### ਵੀਡੀਓ ਚਾਲੂ ਕਦਮ +### ਵੀਡੀਓ ਵਾਕਥਰੂਜ਼ -ਹਰ ਮੋਡੀਊਲ ਦਾ ਇੱਕ ਸਾਥੀ ਲਾਈਵ ਸੈਸ਼ਨ ਹੁੰਦਾ ਹੈ ਜਿੱਥੇ ਅਸੀਂ ਕਾਂਸੈਪਟਾਂ ਅਤੇ ਕੋਡ ਨੂੰ ਕਦਮ ਬਦ ਕਦਮ ਸਮਝਾਉਂਦੇ ਹਾਂ। +ਹਰ ਮਾਡਿਊਲ ਦਾ ਇੱਕ ਸਾਥੀ ਲਾਈਵ ਸੈਸ਼ਨ ਹੁੰਦਾ ਹੈ ਜਿੱਥੇ ਅਸੀਂ ਤੱਤਾਂ ਅਤੇ ਕੋਡ ਨੂੰ ਕਦਮ ਦਰ ਕਦਮ ਸਮਝਾਉਂਦੇ ਹਾਂ। -| ਮੋਡੀਊਲ | ਵੀਡੀਓ | +| ਮਾਡਿਊਲ | ਵੀਡੀਓ | |--------|-------| -| 01 - ਪਰਚਾਇ | [LangChain4j ਨਾਲ ਤੁਰੰਤ ਸ਼ੁਰੂਆਤ](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ | [LangChain4j ਨਾਲ ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - ਰੂਪਰੇਖਾ | [LangChain4j ਨਾਲ ਸ਼ੁਰੂਆਤ](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - ਪ੍ਰੋਮਪਟ ਇੰਜੀਨੀਅਰਿੰਗ | [LangChain4j ਨਾਲ ਪ੍ਰੋਮਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [LangChain4j ਨਾਲ RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - ਟੂਲਜ਼ ਅਤੇ 05 - MCP | [ਟੂਲਜ਼ ਅਤੇ MCP ਨਾਲ AI ਏਜੈਂਟ](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - ਟੂਲ ਅਤੇ 05 - MCP | [ਟੂਲ ਅਤੇ MCP ਨਾਲ AI ਏਜੰਟ](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## ਸਿੱਖਣ ਦਾ ਰਸਤਾ -**LangChain4j ਵਿੱਚ ਨਵਾਂ ਹੋ?** ਮੁੱਖ ਸ਼ਬਦ ਅਤੇ ਧਾਰਣਾਵਾਂ ਦੇ ਪਰਿਭਾਸ਼ਾ ਲਈ [Glossary](docs/GLOSSARY.md) ਵੇਖੋ। +**LangChain4j ਵਿੱਚ ਨਵਾਂ ਹੋ?** ਮੁੱਖ ਸ਼ਬਦਾਂ ਅਤੇ ਵਿਚਾਰਾਂ ਲਈ [ਸ਼ਬਦਾਵਲੀ](docs/GLOSSARY.md) ਵੇਖੋ। > **ਤੁਰੰਤ ਸ਼ੁਰੂਆਤ** -1. ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਨੂੰ ਆਪਣੇ GitHub ਖਾਤੇ ਤੇ ਫੋਰਕ ਕਰੋ -2. **Code** → **Codespaces** ਟੈਬ → **...** → **New with options...** 'ਤੇ ਕਲਿੱਕ ਕਰੋ -3. ਡਿਫੌਲਟ ਵਿਕਲਪ ਵਰਤੋ – ਇਹ ਇਸ ਕੋਰਸ ਲਈ ਬਣਾਈ ਗਈ ਵਿਕਾਸ ਕਨਟੇਨਰ ਚੁਣੇਗਾ -4. **Create codespace** 'ਤੇ ਕਲਿੱਕ ਕਰੋ -5. ਵਾਤਾਵਰਣ ਤਿਆਰ ਹੋਣ ਲਈ 5-10 ਮਿੰਟ ਇੰਤਜ਼ਾਰ ਕਰੋ -6. ਤੁਰੰਤ ਸ਼ੁਰੂ ਕਰਨ ਲਈ [Quick Start](./00-quick-start/README.md) 'ਤੇ ਜਾਓ! +1. ਇਸ ਰਿਪੋਜ਼ਟਰੀ ਨੂੰ ਆਪਣੇ GitHub ਖਾਤੇ 'ਤੇ ਫੋਰਕ ਕਰੋ +2. **Code** → **Codespaces** ਟੈਬ → **...** → **ਨਵਾਂ ਵਿਕਲਪਾਂ ਨਾਲ...** ’ਤੇ ਕਲਿੱਕ ਕਰੋ +3. ਡਿਫੌਲਟ ਵਰਤੋਂ – ਇਹ ਕੋਰਸ ਲਈ ਬਣਾਏ ਗਏ ਵਿਕਾਸ ਕੰਟੇਨਰ ਦੀ ਚੋਣ ਕਰੇਗਾ +4. **ਕੋਡਸਪੇਸ ਬਣਾਓ** ’ਤੇ ਕਲਿੱਕ ਕਰੋ +5. ਵਾਤਾਵਰਣ ਤਿਆਰ ਹੋਣ ਲਈ 5-10 ਮਿੰਟ ਉਡੀਕ ਕਰੋ +6. ਸ਼ੁਰੂਆਤ ਲਈ ਸਿੱਧਾ [ਰੂਪਰੇਖਾ](./01-introduction/README.md) 'ਤੇ ਜਾਓ! -ਮੋਡੀਊਲ ਪੂਰੇ ਕਰਨ ਮਗਰੋਂ, LangChain4j ਟੈਸਟਿੰਗ ਧਾਰਣਾਵਾਂ ਦੀ ਕਾਰਗੁਜ਼ਾਰੀ ਦੇਖਣ ਲਈ [Testing Guide](docs/TESTING.md) ਨੂੰ ਖੋਜੋ। +ਮਾਡਿਊਲ ਪੂਰੇ ਕਰਨ ਤੋਂ ਬਾਅਦ, LangChain4j ਟੈਸਟਿੰਗ ਸੰਕਲਪਾਂ ਦੇਖਣ ਲਈ [ਟੈਸਟਿੰਗ ਗਾਈਡ](docs/TESTING.md) ਦੀ ਜਾਂਚ ਕਰੋ। + +> **ਨੋਟ:** ਇਹ ਪ੍ਰਸ਼ਿਖਣ Azure OpenAI ਵਰਤਦਾ ਹੈ। ਜੇ ਤੁਹਾਡੇ ਕੋਲ ਨਵਾਂ ਖਾਤਾ ਨਹੀਂ ਹੈ ਤਾਂ [ਮੁਫਤ Azure ਖਾਤਾ](https://aka.ms/azure-free-account) ਦਿਵਾਇਆ ਜਾ ਸਕਦਾ ਹੈ। -> **ਨੋਟ:** ਇਹ ਟ੍ਰੇਨਿੰਗ GitHub ਮਾਡਲ ਅਤੇ Azure OpenAI ਦੋਹਾਂ ਨੂੰ ਵਰਤਦੀ ਹੈ। [Quick Start](00-quick-start/README.md) ਮੋਡੀਊਲ GitHub ਮਾਡਲ ਵਰਤਦਾ ਹੈ (ਕੋਈ Azure ਸਬਸਕ੍ਰਿਪਸ਼ਨ ਲੋੜੀਂਦਾ ਨਹੀਂ), ਜਦਕਿ ਮੋਡੀਊਲ 1-5 Azure OpenAI ਵਰਤਦੇ ਹਨ। ਜੇ ਤੁਹਾਡੇ ਕੋਲ ਨਹੀਂ ਹੈ, ਤਾਂ [ਮੁਫ਼ਤ Azure ਖਾਤਾ](https://aka.ms/azure-free-account) ਨਾਲ ਸ਼ੁਰੂਆਤ ਕਰੋ। ## GitHub Copilot ਨਾਲ ਸਿੱਖਣਾ -ਤੇਜ਼ੀ ਨਾਲ ਕੋਡ ਲਿਖਣ ਲਈ, ਇਸ ਪ੍ਰੋਜੈਕਟ ਨੂੰ GitHub Codespace ਜਾਂ ਕੈਨਟੇਨਰ ਵਾਲੇ ਆਪਣੇ ਸਥਾਨਕ IDE ਵਿੱਚ ਖੋਲ੍ਹੋ। ਇਸ ਕੋਰਸ ਵਿੱਚ ਵਰਤੀ ਗਈ devcontainer GitHub Copilot ਨਾਲ ਪਹਿਲਾਂ ਤੋਂ ਸੰਰਚਿਤ ਹੈ AI ਜੁੜੇ ਪ੍ਰੋਗਰਾਮਿੰਗ ਲਈ। +ਤੇਜ਼ੀ ਨਾਲ ਕੋਡਿੰਗ ਸ਼ੁਰੂ ਕਰਨ ਲਈ, ਇਸ ਪ੍ਰੋਜੈਕਟ ਨੂੰ GitHub Codespace ਜਾਂ ਆਪਣੇ ਸਥਾਨਕ IDE ਵਿੱਚ ਪ੍ਰਦਾਨ ਕੀਤੇ ਗਏ devcontainer ਨਾਲ ਖੋਲ੍ਹੋ। ਇਸ ਕੋਰਸ ਵਿਚ ਵਰਤਿਆ ਗਿਆ devcontainer GitHub Copilot ਨਾਲ ਪੂਰਵ-ਕੰਫਿਗਰਡ ਹੈ ਜੋ AI ਜੋੜੀ ਪ੍ਰੋਗ੍ਰਾਮਿੰਗ ਲਈ ਹੈ। + +ਹਰ ਕੋਡ ਉਦਾਹਰਨ ਵਿੱਚ GitHub Copilot ਨੂੰ ਪੁੱਛ ਸਕਦੇ ਪ੍ਰਸਤਾਵਿਤ ਸਵਾਲ ਸ਼ਾਮਲ ਹਨ ਤਾਂ ਜੋ ਤੁਸੀਂ ਆਪਣੀ ਸਮਝ ਨੂੰ ਵਧਾ ਸਕੋ। ટીਪਾਂ ਲਈ 💡/🤖 ਨੂੰ ਵੇਖੋ: -ਹਰ ਕੋਡ ਉਦਾਹਰਨ ਨਾਲ ਕੁਝ ਸਵਾਲ ਹਨ ਜੋ ਤੁਸੀਂ GitHub Copilot ਨੂੰ ਪੁੱਛ ਕੇ ਆਪਣੀ ਸਮਝ ਨਿਖਾਰ ਸਕਦੇ ਹੋ। 💡/🤖 ਪ੍ਰਾਂਪਟਾਂ ਉੱਤੇ ਧਿਆਨ ਦਿਓ: +- **Java ਫਾਇਲ ਹੈਡਰ** - ਹਰ ਉਦਾਹਰਨ ਲਈ ਵਿਸ਼ੇਸ਼ ਸਵਾਲ +- **ਮਾਡਿਊਲ README** - ਕੋਡ ਉਦਾਹਰਨਾਂ ਬਾਅਦ ਖੋਜਣ ਵਾਲੇ ਪ੍ਰਸ਼ਨ -- **Java ਫਾਈਲ ਹੈਡਰਜ਼** - ਹਰ ਉਦਾਹਰਨ ਲਈ ਵਿਸ਼ੇਸ਼ ਸਵਾਲ -- **ਮੋਡੀਊਲ README** - ਕੋਡ ਉਦਾਹਰਨਾਂ ਦੇ ਬਾਅਦ ਖੋਜ ਪ੍ਰਾਂਪਟ +**ਕਿਵੇਂ ਵਰਤਣਾ ਹੈ:** ਕੋਈ ਵੀ ਕੋਡ ਫਾਇਲ ਖੋਲ੍ਹੋ ਅਤੇ Copilot ਨੂੰ ਪ੍ਰਸਤਾਵਿਤ ਸਵਾਲ ਪੁੱਛੋ। ਇਹ ਕੋਡਬੇਸ ਦਾ ਪੂਰਾ ਸੰਦਰਭ ਜਾਣਦਾ ਹੈ ਅਤੇ ਵਿਆਖਿਆ ਕਰ ਸਕਦਾ ਹੈ, ਵਧਾ ਸਕਦਾ ਹੈ, ਅਤੇ ਵਿਕਲਪ ਸੁਝਾ ਸਕਦਾ ਹੈ। -**ਕਿਵੇਂ ਵਰਤਣਾ ਹੈ:** ਕੋਈ ਵੀ ਕੋਡ ਫਾਈਲ ਖੋਲ੍ਹੋ ਅਤੇ Copilot ਨੂੰ ਸਵਾਲ ਪੁੱਛੋ। ਇਹ ਕੋਡਬੇਸ ਦਾ ਪੂਰਾ ਸੰਦਰਭ ਜਾਣਦਾ ਹੈ ਅਤੇ ਵਿਵਰਣਾ, ਵਧਾਰੇ ਅਤੇ ਵਿਕਲਪ ਸੁਝਾ ਸਕਦਾ ਹੈ। +ਹੋਰ ਸਿੱਖਣਾ ਚਾਹੁੰਦੇ ਹੋ? [AI ਜੋੜੀ ਪ੍ਰੋਗ੍ਰਾਮਿੰਗ ਲਈ Copilot](https://aka.ms/GitHubCopilotAI) ਵੇਖੋ। -ਹੋਰ ਜਾਣਨਾ ਚਾਹੁੰਦੇ ਹੋ? [Copilot for AI Paired Programming](https://aka.ms/GitHubCopilotAI) ਵੇਖੋ। -## ਵਧੂ ਸਰੋਤ +## ਵਾਤਾਵਰਣ ਸਮੱਗਰੀ ### LangChain @@ -109,40 +110,41 @@ LangChain4j ਅਤੇ Azure OpenAI GPT-5.2 ਨਾਲ AI ਐਪਲੀਕੇਸ਼ --- -### ਮੁੱਖ ਸਿੱਖਿਆ +### ਕੋਰ ਸਿੱਖਿਆ [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![ਨਵਾਂ ਸਿਖਣ ਵਾਲਿਆਂ ਲਈ ਸਾਈਬਰਸੁਰੱਖਿਆ](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![ਨਵਾਂ ਸਿਖਣ ਵਾਲਿਆਂ ਲਈ ਵੈੱਬ ਡਿਵੈਲਪਮੈਂਟ](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![ਨਵਾਂ ਸਿਖਣ ਵਾਲਿਆਂ ਲਈ ਆਈਓਟੀ](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![ਨਵਾਂ ਸਿਖਣ ਵਾਲਿਆਂ ਲਈ XR ਡਿਵੈਲਪਮੈਂਟ](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### ਕੋਪਾਇਲਟ ਸੀਰੀਜ਼ -[![AI ਜੋੜੀ ਪ੍ਰੋਗ੍ਰਾਮਿੰਗ ਲਈ ਕੋਪਾਇਲਟ](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET ਲਈ ਕੋਪਾਇਲਟ](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![ਕੋਪਾਇਲਟ ਐਡਵੈਂਚਰ](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## ਮਦਦ ਪ੍ਰਾਪਤ ਕਰਨਾ +## ਮਦਦ ਲੈਣਾ ਜੇ ਤੁਸੀਂ ਅਟਕ ਜਾਂਦੇ ਹੋ ਜਾਂ AI ਐਪਸ ਬਣਾਉਣ ਬਾਰੇ ਕੋਈ ਸਵਾਲ ਹੈ, ਤਾਂ ਜੁੜੋ: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -ਜੇ ਤੁਹਾਡੇ ਕੋਲ ਉਤਪਾਦ ਫੀਡਬੈਕ ਜਾਂ ਬਣਾਉਂਦੇ ਸਮੇਂ ਕੋਈ ਗਲਤੀਆਂ ਹੋਣ, ਤਾਂ ਵੀਜ਼ਟ ਕਰੋ: +ਜੇ ਤੁਹਾਡੇ ਕੋਲ ਉਤਪਾਦ ਬਾਰੇ ਫੀਡਬੈਕ ਹੈ ਜਾਂ ਬਣਾਉਣ ਸਮੇਂ ਕੋਈ ਗਲਤੀ ਆਈ ਹੈ ਤਾਂ ਦੌਰਾ ਕਰੋ: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## ਲਾਇਸੈਂਸ -MIT ਲਾਇਸੈਂਸ - ਵੀਰਵੇ ਲਈ [LICENSE](../../LICENSE) ਫਾਇਲ ਵੇਖੋ। +MIT ਲਾਇਸੈਂਸ - ਵੇਰਵੇ ਲਈ [LICENSE](../../LICENSE) ਫਾਈਲ ਦੇਖੋ। --- -**ਅਸਵੀਕਾਰੋक्ति**: -ਇਹ ਦਸਤਾਵੇਜ਼ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਅਨੁਵਾਦਿਤ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਅਤ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਵਿੱਚ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਣਸਹੀਤੀਆਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਹੀ ਪ੍ਰਮਾਣਿਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਅਹੰਕਾਰਪੂਰਕ ਜਾਣਕਾਰੀ ਲਈ, ਪ੍ਰੋਫੈਸ਼ਨਲ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫਾਰਿਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੀ ਵਰਤੋਂ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀ ਜਾਂ ਗਲਤ ਅਰਥ ਲੱਗਣ ਲਈ ਜ਼ਿੰਮੇਵਾਰ ਨਹੀਂ ਹਾਂ। +**ਅਸਵੀਕਾਰੋਪਣ**: +ਇਸ ਦਸਤਾਵੇਜ਼ ਦਾ ਅਨੁਵਾਦ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾਵਾਂ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਮੱਤਿਆਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਜਰੂਰੀ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੇ ਉਪਯੋਗ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਗਲਤ ਵਿਆਖਿਆਵਾਂ ਲਈ ਜਵਾਬਦੇਹ ਨਹੀਂ ਹਾਂ। \ No newline at end of file diff --git a/translations/pa/docs/GLOSSARY.md b/translations/pa/docs/GLOSSARY.md index 3e1bc0914..90c31a958 100644 --- a/translations/pa/docs/GLOSSARY.md +++ b/translations/pa/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## ਸੂਚੀ -- [ਮੁੱਖ ਧਾਰਾਵਾਂ](../../../docs) -- [LangChain4j ਘਟਕ](../../../docs) -- [AI/ML ਧਾਰਾਵਾਂ](../../../docs) -- [ਗਾਰਡਰੇਲਜ਼](../../../docs) -- [ਪ੍ਰੌੰਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](../../../docs) -- [RAG (ਰਿਟਰੀਵਲ-ਆਗਮੈਂਟਡ ਜਨਰੇਸ਼ਨ)](../../../docs) -- [ਏਜੰਟ ਅਤੇ ਔਜ਼ਾਰ](../../../docs) -- [ਏਜੈਂਟਿਕ ਮੋਡਿਊਲ](../../../docs) -- [ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰਭਾਅ (MCP)](../../../docs) -- [ਅਜ਼ੂਰ ਸੇਵਾਵਾਂ](../../../docs) -- [ਟੈਸਟਿੰਗ ਅਤੇ ਵਿਕਾਸ](../../../docs) +- [ਮੁੱਖ ਧਾਰਣਾ](#ਮੁੱਖ-ਧਾਰਣਾ) +- [LangChain4j ਘਟਕ](#langchain4j-ਘਟਕ) +- [AI/ML ਧਾਰਣਾ](#aiml-ਧਾਰਣਾ) +- [ਗਾਰਡਰੇਲ](#ਗਾਰਡਰੇਲ) +- [ਪ੍ਰੌਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](#prompt-engineering---module-02) +- [RAG (ਰੀਟ੍ਰੀਵਲ-ਅਗਮੈਂਟਡ ਜੈਨਰੇਸ਼ਨ)](#rag-retrieval-augmented-generation---module-03) +- [ਏਜੰਟ ਅਤੇ ਟੂਲਜ਼](#agents-and-tools---module-04) +- [ਏਜੰਟਿਕ ਮਾਡਿਊਲ](#agentic-module---module-05) +- [ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰੋਟੋਕੋਲ (MCP)](#model-context-protocol-mcp---module-05) +- [ਐਜ਼ਿਊਰ ਸੇਵਾਵਾਂ](#azure-services---module-01) +- [ਟੈਸਟਿੰਗ ਅਤੇ ਵਿਕਾਸ](#testing-and-development---testing-guide) -ਕੋਰਸ ਵਿੱਚ ਵਰਤੇ ਗਏ ਸ਼ਬਦਾਂ ਅਤੇ ਧਾਰਾਵਾਂ ਲਈ ਤੇਜ਼ ਸੰਦੇਸ਼ ਸੂਚਕ. +ਕੋਰਸ ਵਿੱਚ ਵਰਤੇ ਗਏ ਸ਼ਬਦਾਂ ਅਤੇ ਧਾਰਣਾਵਾਂ ਲਈ ਤੈਜ਼ ਹਵਾਲਾ। -## ਮੁੱਖ ਧਾਰਾਵਾਂ +## ਮੁੱਖ ਧਾਰਣਾ -**AI ਏਜੰਟ** - ਸਿਸਟਮ ਜੋ AI ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਸੋਚਦਾ ਹੈ ਅਤੇ ਸਵੈਚਾਲਿਤ ਤੌਰ 'ਤੇ ਕੰਮ ਕਰਦਾ ਹੈ। [ਮੋਡਿਊਲ 04](../04-tools/README.md) +**AI ਏਜੰਟ** - ਐਸਾ ਸਿਸਟਮ ਜੋ AI ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਸੁਤੰਤਰ ਤੌਰ 'ਤੇ ਤਰਕ ਅਤੇ ਕਾਰਵਾਈ ਕਰਦਾ ਹੈ। [ਮਾਡਿਊਲ 04](../04-tools/README.md) -**ਚੇਨ** - ਕਾਰਜਾਂ ਦੀ ਕ੍ਰਮਵਾਰ ਸ਼੍ਰੇਣੀ ਜਿੱਥੇ ਨਤੀਜਾ ਅਗਲੇ ਕਦਮ ਵਿੱਚ ਵਰਤਿਆ ਜਾਂਦਾ ਹੈ। +**ਚੇਨ** - ਕਾਰਵਾਈਆਂ ਦਾ ਇਕ ਲੜੀਜੋੜ ਜਿੱਥੇ ਆਉਟਪੁੱਟ ਅੱਗਲੇ ਕਦਮ ਨੂੰ ਫੀਡ ਕਰਦਾ ਹੈ। -**ਚੰਕਿੰਗ** - ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਛੋਟੇ ਹਿੱਸਿਆਂ ਵਿੱਚ ਵੰਡਣਾ। ਆਮ: 300-500 ਟੋਕਨਜ਼ ਜਿਹੜੇ ਓਵਰਲੈਪ ਨਾਲ। [ਮੋਡਿਊਲ 03](../03-rag/README.md) +**ਚੰਕਿੰਗ** - ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਛੋਟੇ ਹਿੱਸਿਆਂ ਵਿੱਚ ਵੰਡਣਾ। ਆਮ ਤੌਰ 'ਤੇ: 300-500 ਟੋਕਨਸ ਨਾਲ ਓਵਰਲੈਪ। [ਮਾਡਿਊਲ 03](../03-rag/README.md) -**ਕਾਂਟੈਕਸਟ ਵਿੰਡੋ** - ਜ਼ਿਆਦਾ ਤੋਂ ਜ਼ਿਆਦਾ ਟੋਕਨ ਜੋ ਮਾਡਲ ਪ੍ਰਭਾਸ਼ਿਤ ਕਰ ਸਕਦਾ ਹੈ। GPT-5.2: 400K ਟੋਕਨ (ਜੋੜ-ਦਾਖਲਾ 272K, ਨਿਕਾਸ 128K). +**ਸੰਦਰਭ ਵਿੰਡੋ** - ਮਾਡਲ ਵੱਲੋਂ ਪ੍ਰਕਿਰਿਆ ਕੀਤੇ ਜਾ ਸਕਦੇ ਸਬ ਤੋਂ ਵੱਧ ਟੋਕਨ। GPT-5.2: 400K ਟੋਕਨ (272K ਇਨਪੁੱਟ ਤੱਕ, 128K ਆਉਟਪੁੱਟ ਲਈ)। -**ਐਮਬੈਡਿੰਗਸ** - ਗਿਣਤੀਕ ਦਿੱਗਦੇ ਜਿਹੜੇ ਟੈਕਸਟ ਦੇ ਅਰਥ ਨੂੰ ਦਰਸਾਉਂਦੇ ਹਨ। [ਮੋਡਿਊਲ 03](../03-rag/README.md) +**ਐਂਬੈਡਿੰਗਸ** - ਲਿਖਤ ਦੇ ਅਰਥ ਨੂੰ ਦਰਸਾਉਂਦੇ ਗਿਣਤੀ ਅੰਕੀਆਂ ਵਾਲੇ ਵੇਕਟਰ। [ਮਾਡਿਊਲ 03](../03-rag/README.md) -**ਫੰਕਸ਼ਨ ਕਾਲਿੰਗ** - ਮਾਡਲ ਬਾਹਰੀ ਫੰਕਸ਼ਨਾਂ ਨੂੰ ਕਾਲ ਕਰਨ ਲਈ ਰਚਨਾਤਮਕ ਅਗਿਆਵਾਂ ਤਇਆਰ ਕਰਦਾ ਹੈ। [ਮੋਡਿਊਲ 04](../04-tools/README.md) +**ਫੰਕਸ਼ਨ ਕਾਲਿੰਗ** - ਮਾਡਲ ਬਾਹਰੀ ਫੰਕਸ਼ਨਾਂ ਨੂੰ ਕਾਲ ਕਰਨ ਲਈ ਸੰਰਚਿਤ ਬੇਨਤੀਆਂ ਬਣਾਉਂਦਾ ਹੈ। [ਮਾਡਿਊਲ 04](../04-tools/README.md) -**ਹੈਲੂਸੀਨੇਸ਼ਨ** - ਜਦੋਂ ਮਾਡਲ ਗਲਤ ਪਰ ਸਹੀ ਜਾਣਕਾਰੀਆਂ ਪੈਦਾ ਕਰਦੇ ਹਨ। +**ਹੈਲੁਸੀਨੇਸ਼ਨ** - ਜਦ ਮਾਡਲ ਗਲਤ ਪਰ ਸੰਭਾਵਿਤ ਜਾਣਕਾਰੀ ਬਣਾਉਂਦਾ ਹੈ। -**ਪ੍ਰੌੰਪਟ** - ਭਾਸ਼ਾ ਮਾਡਲ ਲਈ ਟੈਕਸਟ ਇੰਪੁੱਟ। [ਮੋਡਿਊਲ 02](../02-prompt-engineering/README.md) +**ਪ੍ਰੌਂਪਟ** - ਭਾਸ਼ਾ ਮਾਡਲ ਲਈ ਲਿਖਤ ਇਨਪੁੱਟ। [ਮਾਡਿਊਲ 02](../02-prompt-engineering/README.md) -**ਸੈਮੈਂਟਿਕ ਖੋਜ** - ਅਰਥ ਤੇ ਅਧਾਰਿਤ ਖੋਜ ਜਿਸ ਵਿੱਚ ਐਮਬੈਡਿੰਗਸ ਵਰਤੀ ਜਾਂਦੀਆਂ ਹਨ, ਨਾ ਕਿ ਕੀਵਰਡਜ਼। [ਮੋਡਿਊਲ 03](../03-rag/README.md) +**ਸੈਮੈਂਟਿਕ ਖੋਜ** - ਕਰਮ-ਪ੍ਰਸੰਗ ਅਨੁਸਾਰ ਖੋਜ, ਐਂਬੈਡਿੰਗਸ ਦੀ ਵਰਤੋਂ ਕਰਕੇ, ਕੀਵਰਡ ਲਈ ਨਹੀਂ। [ਮਾਡਿਊਲ 03](../03-rag/README.md) -**ਸਟੇਟਫੁਲ ਬਣਾਮ ਸਟੇਟਲੈੱਸ** - ਸਟੇਟਲੈੱਸ: ਕੋਈ ਯਾਦ ਨਹੀਂ. ਸਟੇਟਫੁਲ: ਗੱਲਬਾਤ ਦਾ ਇਤਿਹਾਸ ਰੱਖਦਾ ਹੈ। [ਮੋਡਿਊਲ 01](../01-introduction/README.md) +**ਸਟੇਟਫੁਲ ਵਿਰੁੱਧ ਸਟੇਟਲੈੱਸ** - ਸਟੇਟਲੈੱਸ: ਕੋਈ ਮੈਮੋਰੀ ਨਹੀਂ। ਸਟੇਟਫੁਲ: ਗੱਲਬਾਤ ਦੀ ਇਤਿਹਾਸ ਨੂੰ ਸੰਭਾਲਦਾ ਹੈ। [ਮਾਡਿਊਲ 01](../01-introduction/README.md) -**ਟੋਕਨਜ਼** - ਮੂਲ ਟੈਕਸਟ ਇਕਾਈਆਂ ਜੋ ਮਾਡਲ ਪ੍ਰੋਸੈਸ ਕਰਦੇ ਹਨ। ਖਰਚੇ ਅਤੇ ਸੀਮਾਵਾਂ ਉੱਤੇ ਪ੍ਰਭਾਵ। [ਮੋਡਿਊਲ 01](../01-introduction/README.md) +**ਟੋਕਨਸ** - ਮਾਡਲ ਦੁਆਰਾ ਪ੍ਰਕਿਰਿਆ ਕੀਤੇ ਜਾਣ ਵਾਲੇ ਮੂਲ ਲਿਖਤ ਇਕਾਈਆਂ। ਖ਼ਰਚ ਅਤੇ ਸੀਮਾਵਾਂ ਪ੍ਰਭਾਵਿਤ ਕਰਦੇ ਹਨ। [ਮਾਡਿਊਲ 01](../01-introduction/README.md) -**ਟੂਲ ਚੇਨਿੰਗ** - ਲੜੀਵਾਰ ਤੌਰ 'ਤੇ ਟੂਲ ਚਲਾਉਣਾ ਜਿੱਥੇ ਨਤੀਜਾ ਅਗਲੇ ਕਾਲ ਲਈ ਜਾਣਕਾਰੀ ਦਿੰਦਾ ਹੈ। [ਮੋਡਿਊਲ 04](../04-tools/README.md) +**ਟੂਲ ਚੇਨਿੰਗ** - ਲਗਾਤਾਰ ਟੂਲ ਦਾ ਕਾਰਜ, ਜਿੱਥੇ ਆਉਟਪੁੱਟ ਅਗਲੇ ਕਾਲ ਨੂੰ ਸੂਚਿਤ ਕਰਦਾ ਹੈ। [ਮਾਡਿਊਲ 04](../04-tools/README.md) ## LangChain4j ਘਟਕ -**AiServices** - ਕਿਸਮ ਸੁਰੱਖਿਅਤ AI ਸੇਵਾ ਇੰਟਰਫੇਸ ਬਣਾਉਂਦਾ ਹੈ। +**AiServices** - ਪ੍ਰਕਾਰ-ਸੁਰੱਖਿਅਤ AI ਸੇਵਾ ਇੰਟਰਫੇਸ ਬਣਾਉਂਦਾ ਹੈ। -**OpenAiOfficialChatModel** - OpenAI ਅਤੇ Azure OpenAI ਮਾਡਲਾਂ ਲਈ ਇਕੱਠਾ ਕਲਾਇੰਟ। +**OpenAiOfficialChatModel** - OpenAI ਅਤੇ Azure OpenAI ਮਾਡਲਾਂ ਲਈ ਇਕਜੁੱਟ ਕਲਾਇੰਟ। -**OpenAiOfficialEmbeddingModel** - OpenAI ਅਧਿਕਾਰਿਕ ਕਲਾਇੰਟ (OpenAI ਅਤੇ Azure OpenAI ਦੋਹਾਂ ਲਈ) ਨਾਲ ਐਮਬੈਡਿੰਗਸ ਬਣਾਉਂਦਾ ਹੈ। +**OpenAiOfficialEmbeddingModel** - OpenAI ਅਦਿਕਾਰਿਕ ਕਲਾਇੰਟ ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਐਂਬੈਡਿੰਗਸ ਬਣਾਉਂਦਾ ਹੈ (ਦੋਹਾਂ OpenAI ਅਤੇ Azure OpenAI ਦਾ ਸਮਰਥਨ ਕਰਦਾ ਹੈ)। **ChatModel** - ਭਾਸ਼ਾ ਮਾਡਲਾਂ ਲਈ ਕੋਰ ਇੰਟਰਫੇਸ। **ChatMemory** - ਗੱਲਬਾਤ ਦਾ ਇਤਿਹਾਸ ਰੱਖਦਾ ਹੈ। -**ContentRetriever** - RAG ਲਈ ਲੋੜੀਂਦੇ ਦਸਤਾਵੇਜ਼ ਚੰਕ ਲੱਭਦਾ ਹੈ। +**ContentRetriever** - RAG ਲਈ ਸੰਬੰਧਿਤ ਦਸਤਾਵੇਜ਼ ਚੰਕ ਲੱਭਦਾ ਹੈ। -**DocumentSplitter** - ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਚੰਕ ਵਿੱਚ ਵੰਡਦਾ ਹੈ। +**DocumentSplitter** - ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਚੰਕਾਂ ਵਿੱਚ ਵੰਡਦਾ ਹੈ। -**EmbeddingModel** - ਟੈਕਸਟ ਨੂੰ ਗਿਣਤੀਕ ਵੈਕਟਰਾਂ ਵਿੱਚ ਬਦਲਦਾ ਹੈ। +**EmbeddingModel** - ਲਿਖਤ ਨੂੰ ਗਿਣਤੀ ਅੰਕੀਆਂ ਵਾਲੇ ਵੇਕਟਰ ਵਿੱਚ ਬਦਲਦਾ ਹੈ। -**EmbeddingStore** - ਐਮਬੈਡਿੰਗਸ ਸੰਭਾਲਦਾ ਅਤੇ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ। +**EmbeddingStore** - ਐਂਬੈਡਿੰਗਸ ਸਟੋਰ ਅਤੇ ਪ੍ਰਾਪਤ ਕਰਦਾ ਹੈ। **MessageWindowChatMemory** - ਹਾਲੀਆ ਸੁਨੇਹਿਆਂ ਦੀ ਸਲਾਇਡਿੰਗ ਵਿੰਡੋ ਰੱਖਦਾ ਹੈ। -**PromptTemplate** - `{{variable}}` ਪਲੇਸਹੋਲਡਰਾਂ ਨਾਲ ਦੁਹਰਾਏ ਜਾ ਸਕਣ ਵਾਲੇ ਪ੍ਰੌੰਪਟ ਬਣਾਉਂਦਾ ਹੈ। +**PromptTemplate** - `{{variable}}` ਸਥਾਨਧਾਰਕਾਂ ਨਾਲ ਪੁਨਰਵਰਤਨਯੋਗ ਪ੍ਰੌਂਪਟ ਬਣਾਉਂਦਾ ਹੈ। -**TextSegment** - ਮੈਟਾਡੇਟਾ ਸਮੇਤ ਟੈਕਸਟ ਚੰਕ। RAG ਵਿੱਚ ਵਰਤਿਆ ਜਾਂਦਾ ਹੈ। +**TextSegment** - ਮੈਟਾਡੇਟਾ ਵਾਲਾ ਲਿਖਤੀ ਚੰਕ। RAG ਵਿੱਚ ਵਰਤਿਆ ਜਾਂਦਾ ਹੈ। -**ToolExecutionRequest** - ਟੂਲ ਕਾਲ ਦੀ ਅਗਿਆ ਪ੍ਰਤੀਨਿ਷ਠਾ। +**ToolExecutionRequest** - ਟੂਲ ਕਾਰਜ ਦੀ ਬੇਨਤੀ ਦਰਸਾਉਂਦਾ ਹੈ। -**UserMessage / AiMessage / SystemMessage** - ਗੱਲਬਾਤ ਦਾ ਸੁਨੇਹਾ ਕਿਸਮਾਂ। +**UserMessage / AiMessage / SystemMessage** - ਗੱਲਬਾਤ ਸੁਨੇਹੇ ਦੇ ਕਿਸਮਾਂ। -## AI/ML ਧਾਰਾਵਾਂ +## AI/ML ਧਾਰਣਾ -**ਫਿਊ-ਸ਼ੌਟ ਲਰਨਿੰਗ** - ਪ੍ਰੌੰਪਟ ਵਿਚ ਉਦਾਹਰਣਾਂ ਦੇਣਾ। [ਮੋਡਿਊਲ 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - ਪ੍ਰੌਂਪਟ ਵਿੱਚ ਉਦਾਹਰਣਾਂ ਦੇਣਾ। [ਮਾਡਿਊਲ 02](../02-prompt-engineering/README.md) -**ਲਾਰਜ ਲੈੰਗਵੇਜ ਮਾਡਲ (LLM)** - ਬਹੁਤ ਸਾਰੇ ਟੈਕਸਟ ਡੇਟਾ 'ਤੇ ਤਿਆਰ ਕੀਤੇ ਗਏ AI ਮਾਡਲ। +**ਵੱਡਾ ਭਾਸ਼ਾਈ ਮਾਡਲ (LLM)** - ਵੱਡੇ ਗਿਣਤ ਲਿਖਤ ਡਾਟਾ 'ਤੇ ਤਿਆਰ AI ਮਾਡਲ। -**ਰਿਜਨਿੰਗ ਕੋਸ਼ਿਸ਼** - GPT-5.2 ਪੈਰਾਮੀਟਰ ਜੋ ਸੋਚਣ ਦੀ ਗਹਿਰਾਈ ਨੂੰ ਨਿਯੰਤਰਿਤ ਕਰਦਾ ਹੈ। [ਮੋਡਿਊਲ 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - ਸੋਚਣ ਦੀ ਗਹਿਰਾਈ ਨੂੰ ਨਿਯੰਤਰਿਤ ਕਰਨ ਵਾਲਾ GPT-5.2 ਪੈਰਾਮੀਟਰ। [ਮਾਡਿਊਲ 02](../02-prompt-engineering/README.md) -**ਟੈਂਪਰੇਚਰ** - ਨਿਕਾਸ ਦੀ ਬੇਇਹਮਈ ਨੂੰ ਨਿਯੰਤਰਿਤ ਕਰਦਾ ਹੈ। ਘੱਟ=ਨਿਰਧਾਰਤ, ਉੱਚ=ਰਚਨਾਤਮਕ। +**ਟੈਮਪਰੈਚਰ** - ਆਉਟਪੁੱਟ ਦੀ ਬੇਰੁਕਾਬਾਰੀ ਨੂੰ ਨਿਯੰਤਰਿਤ ਕਰਦਾ ਹੈ। ਘੱਟ=ਦੇਖਾਇਆ ਹੋਇਆ, ਉੱਚ=ਸਿਰਜਣਾਤਮਕ। -**ਵੈਕਟਰ ਡੇਟਾਬੇਸ** - ਐਮਬੈਡਿੰਗਸ ਲਈ ਵਿਸ਼ੇਸ਼ ਡੇਟਾਬੇਸ। [ਮੋਡਿਊਲ 03](../03-rag/README.md) +**ਵੇਕਟਰ ਡਾਟਾਬੇਸ** - ਐਂਬੈਡਿੰਗਸ ਲਈ ਵਿਸ਼ੇਸ਼ ਡਾਟਾਬੇਸ। [ਮਾਡਿਊਲ 03](../03-rag/README.md) -**ਜ਼ੀਰੋ-ਸ਼ੌਟ ਲਰਨਿੰਗ** - ਉਦਾਹਰਣਾਂ ਦੇ ਬਿਨਾਂ ਕੰਮ ਕਰਨਾ। [ਮੋਡਿਊਲ 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - ਬਿਨਾਂ ਉਦਾਹਰਣਾਂ ਦੇ ਕੰਮ ਕਰਨਾ। [ਮਾਡਿਊਲ 02](../02-prompt-engineering/README.md) -## ਗਾਰਡਰੇਲਜ਼ - [ਮੋਡਿਊਲ 00](../00-quick-start/README.md) +## ਗਾਰਡਰੇਲ -**ਡਿਫੈਂਸ ਇਨ ਡੈਪਥ** - ਐਪਲੀਕੇਸ਼ਨ-ਸਤਹ ਗਾਰਡਰੇਲਜ਼ ਨੂੰ ਪਰਦਾਤਾ ਸੁਰੱਖਿਆ ਫਿਲਟਰਾਂ ਨਾਲ ਜੋੜ ਕੇ ਬਹੁ-ਪਹਿਰੀ ਸੁਰੱਖਿਆ ਪਹਿਰਾਵਾ। +**ਡਿਫੈਂਸ ਇਨ ਡੈਪਥ** - ਇਹ ਮਲਟੀ-ਸਤਰ ਸੁਰੱਖਿਆ ਪਹੁੰਚ ਹੈ ਜੋ ਐਪਲੀਕੇਸ਼ਨ ਪੱਧਰ ਦੇ ਗਾਰਡਰੇਲਜ਼ ਨਾਲ ਪ੍ਰਦਾਤਾ ਦੀ ਸੁਰੱਖਿਆ ਫਿਲਟਰਾਂ ਨੂੰ ਮਿਲਾਉਂਦੀ ਹੈ। -**ਹਾਰਡ ਬਲਾਕ** - ਪਰਦਾਤਾ ਗੰਭੀਰ ਸਮੱਗਰੀ ਉਲੰਘਣਾ ਲਈ HTTP 400 ਤਰੁੱਟੀ ਫੈਂਕਦਾ ਹੈ। +**ਹਾਰਡ ਬਲੌਕ** - ਪ੍ਰਦਾਤਾ ਗੰਭੀਰ ਸਮੱਗਰੀ ਉਲੰਘਣਾਂ ਲਈ HTTP 400 ਗਲਤੀ ਦੇਂਦਾ ਹੈ। -**InputGuardrail** - LangChain4j ਇੰਟਰਫੇਸ ਜੋ LLM ਤੱਕ ਪੁੱਜਣ ਤੋਂ ਪਹਿਲਾਂ ਉਪਭੋਗਤਾ ਇੰਪੁੱਟ ਨੂੰ ਮਾਨਤਾ ਦਿੰਦਾ ਹੈ। ਨੁਕਸਾਨਦੇਹ ਪ੍ਰੌੰਪਟਾਂ ਨੂੰ ਜਲਦੀ ਰੋਕ ਕੇ ਖ਼ਰਚ ਅਤੇ ਦੇਰੀ ਬਚਾਉਂਦਾ ਹੈ। +**InputGuardrail** - LangChain4j ਇੰਟਰਫੇਸ ਜੋ LLM ਤੱਕ ਪਹੁੰਚਣ ਤੋਂ ਪਹਿਲਾਂ ਉਪਭੋਗਤਾ ਇਨਪੁੱਟ ਦੀ ਜਾਂਚ ਕਰਦਾ ਹੈ। ਨੁਕਸਾਨਦੇਹ ਪ੍ਰੌਂਪਟਾਂ ਨੂੰ ਜਲਦੀ ਰੋਕ ਕੇ ਲਾਗਤ ਅਤੇ ਲੈਟੈਂਸੀ ਬਚਾਉਂਦਾ ਹੈ। -**InputGuardrailResult** - ਗਾਰਡਰੇਲ ਮਾਨਤਾ ਲਈ ਵਾਪਸੀ ਕਿਸਮ: `success()` ਜਾਂ `fatal("ਵਜ੍ਹਾ")`। +**InputGuardrailResult** - ਗਾਰਡਰੇਲ ਵੈਰਿਫਿਕੇਸ਼ਨ ਲਈ ਵਾਪਸੀ ਕਿਸਮ: `success()` ਜਾਂ `fatal("ਕਾਰਨ")`। -**OutputGuardrail** - ਉਪਭੋਗਤਿਆਂ ਕੋਲ ਵਾਪਸ ਜਾਣ ਤੋਂ ਪਹਿਲਾਂ AI ਜਵਾਬਾਂ ਨੂੰ ਜਾਂਚਣ ਵਾਲਾ ਇੰਟਰਫੇਸ। +**OutputGuardrail** - ਉਪਭੋਗਤਾਵਾਂ ਨੂੰ ਜਵਾਬ ਦਿੱਤਿਆਂ ਪਹਿਲਾਂ AI ਦੇ ਜਵਾਬਾਂ ਦੀ ਜਾਂਚ ਲਈ ਇੰਟਰਫੇਸ। -**Provider Safety Filters** - AI ਪ੍ਰਦਾਤਾ (ਜਿਵੇਂ ਕਿ GitHub ਮਾਡਲ) ਵੱਲੋਂ ਬਿਲਟ-ਇਨ ਸਮੱਗਰੀ ਫਿਲਟਰ ਜੋ API ਪੱਧਰ 'ਤੇ ਉਲੰਘਣਾਂ ਫੜਦੇ ਹਨ। +**Provider Safety Filters** - AI ਪ੍ਰਦਾਤਾਵਾਂ (ਜਿਵੇਂ ਕਿ Azure OpenAI) ਤੋਂ ਅੰਦਰੂਨੀ ਸਮੱਗਰੀ ਫਿਲਟਰ ਜੋ API ਪੱਧਰ 'ਤੇ ਉਲੰਘਣਾਂ ਨੂੰ ਰੋਕਦੇ ਹਨ। -**Soft Refusal** - ਮਾਡਲ ਉੱਤਰ ਦੇਣ ਤੋਂ ਇਨਕਾਰ ਬਿਨਾਂ ਤਰੁੱਟੀ ਦੇ ਨਿੱਜੀ ਢੰਗ ਨਾਲ ਕਰਦਾ ਹੈ। +**Soft Refusal** - ਮਾਡਲ ਸੱਤਕਾਰਪੂਰਵਕ ਜਵਾਬ ਦੇਣ ਤੋਂ ਇਨਕਾਰ ਕਰਦਾ ਹੈ ਬਿਨਾਂ ਗਲਤੀ ਫੇਂਕੇ। -## ਪ੍ਰੌੰਪਟ ਇੰਜੀਨੀਅਰਿੰਗ - [ਮੋਡਿਊਲ 02](../02-prompt-engineering/README.md) +## ਪ੍ਰੌਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ - [ਮਾਡਿਊਲ 02](../02-prompt-engineering/README.md) -**ਚੇਨ-ਆਫ-ਥਾਟ** - ਚੰਗੀ ਸਹੀਤਾ ਲਈ ਕਦਮ ਬਦ ਕਦਮ ਤਰਕ। +**Chain-of-Thought** - ਬਿਹਤਰੀਨ ਸਹੀਤਾ ਲਈ ਕਦਮ ਦਰ ਕਦਮ ਤਰਕ। -**ਸੰਕੁਚਿਤ ਨਿਕਾਸ** - ਖਾਸ ਫਾਰਮੈਟ ਜਾਂ ਢਾਂਚਾ ਲਾਗੂ ਕਰਨਾ। +**Constrained Output** - ਖਾਸ ਫਾਰਮੈਟ ਜਾਂ ਸੰਰਚਨਾ ਲਾਗੂ ਕਰਨਾ। -**ਉੱਚ ਲਾਲਚ** - GPT-5.2 ਪੈਟਰਨ ਜੋ ਵਿਆਪਕ ਤਰਕ ਲਈ ਬਣਇਆ। +**High Eagerness** - GPT-5.2 ਦੀ ਪੈਟਰਨ ਜੋ ਵਿਆਪਕ ਤਰਕ ਨੂੰ ਦਰਸਾਉਂਦੀ ਹੈ। -**ਘੱਟ ਲਾਲਚ** - GPT-5.2 ਪੈਟਰਨ ਜੋ ਤੇਜ਼ ਜਵਾਬ ਲਈ ਬਣਾਇਆ। +**Low Eagerness** - GPT-5.2 ਦੀ ਪੈਟਰਨ ਜੋ ਤੇਜ਼ ਜਵਾਬ ਲਈ ਹੈ। -**ਮਲਟੀ-ਟਰਨ ਗੱਲਬਾਤ** - ਪਰਸਪਰ ਸੰਵਾਦ ਦੇ ਵਿਚਕਾਰ ਸੰਦਰਭ ਨਿਭਾਉਣਾ। +**ਬਹੁ-ਮੁੜ ਗੱਲਬਾਤ** - ਵਟਾਂਦਰੇ ਦੇ ਦੌਰਾਨ ਸੰਦਰਭ ਨੂੰ ਬਣਾਈ ਰੱਖਣਾ। -**ਭੂਮਿਕਾ ਅਧਾਰਿਤ ਪ੍ਰੌੰਪਟਿੰਗ** - ਪ੍ਰਣਾਲੀ ਸੁਨੇਹਿਆਂ ਰਾਹੀਂ ਮਾਡਲ ਵ੍ਯਕਤੀਤਾ ਸੈੱਟ ਕਰਨਾ। +**ਭੂਮਿਕਾ-ਆਧਾਰਿਤ ਪ੍ਰੌਂਪਟਿੰਗ** - ਸਿਸਟਮ ਸੁਨੇਹਿਆਂ ਰਾਹੀਂ ਮਾਡਲ ਦੀ ਵਿਅਕਤੀਤਾ ਸੈਟ ਕਰਨਾ। -**ਸਵ-ਮੁਲਾਂਕਣ** - ਮਾਡਲ ਆਪਣੀ ਨਿਕਾਸ ਦਾ ਅੰਕਲਨ ਅਤੇ ਸੁਧਾਰ ਕਰਦਾ ਹੈ। +**ਆਤਮ-ਮੁਲਾਂਕਣ** - ਮਾਡਲ ਆਪਣੇ ਆਉਟਪੁੱਟ ਦੀ ਕਦਰ ਕਰਦਾ ਅਤੇ ਸੁਧਾਰ ਕਰਦਾ ਹੈ। -**ਸੰਰਚਿਤ ਵਿਸ਼ਲੇਸ਼ਣ** - ਸਥਿਰ ਮੁਲਾਂਕਣ ਢਾਂਚਾ। +**ਸੰਰਚਿਤ ਵਿਸ਼ਲੇਸ਼ਣ** - ਨਿਰਧਾਰਿਤ ਮੁਲਾਂਕਣ ਢਾਂਚਾ। -**ਕਾਰਜ ਨਿਭਾਉਣ ਪੈਟਰਨ** - ਯੋਜਨਾ ਬਨਾਉ → ਕਰਵਾਈ ਕਰੋ → ਸਾਰ ਸੰਖੇਪ। +**ਕਾਰਜ ਨਿਭਾਅ ਪੈਟਰਨ** - ਯੋਜਨਾ → ਨਿਭਾਅ → ਸੰਖੇਪ। -## RAG (ਰਿਟਰੀਵਲ-ਆਗਮੈਂਟਡ ਜਨਰੇਸ਼ਨ) - [ਮੋਡਿਊਲ 03](../03-rag/README.md) +## RAG (ਰੀਟ੍ਰੀਵਲ-ਅਗਮੈਂਟਡ ਜੈਨਰੇਸ਼ਨ) - [ਮਾਡਿਊਲ 03](../03-rag/README.md) -**ਦਸਤਾਵੇਜ਼ ਪਰੋਸੈਸਿੰਗ ਪਾਈਪਲਾਈਨ** - ਲੋਡ ਕਰੋ → ਚੰਕ ਕਰੋ → ਐਮਬੈਡ ਕਰੋ → ਸਟੋਰ ਕਰੋ। +**ਦਸਤਾਵੇਜ਼ ਪ੍ਰਕਿਰਿਆ ਪਾਈਪਲਾਈਨ** - ਲੋਡ → ਚੰਕ → ਐਂਬੈਡ → ਸਟੋਰ। -**ਇਨ-ਮੇਮੋਰੀ ਐਮਬੈਡਿੰਗ ਸਟੋਰ** - ਟੈਸਟਿੰਗ ਲਈ ਗੈਰ-ਟਿਕਾਊ ਸਟੋਰੇਜ। +**ਇਨ-ਮੇਮੋਰੀ ਐਂਬੈਡਿੰਗ ਸਟੋਰ** - ਟੈਸਟਿੰਗ ਲਈ ਗੈਰ-ਕਾਇਮੀ ਸਟੋਰੇਜ। -**RAG** - ਜਵਾਬਾਂ ਨੂੰ ਮੂਲਧਾਰਿਤ ਕਰਨ ਲਈ ਰਿਟਰੀਵਲ ਨੂੰ ਜਨਰੇਸ਼ਨ ਨਾਲ ਜੋੜਦਾ ਹੈ। +**RAG** - ਪ੍ਰਤੀਸਾਦਾਂ ਨੂੰ ਜਮੀਨੀ ਹਕੀਕਤ ਵਿੱਚ ਲਿਆਉਣ ਲਈ ਰੀਟ੍ਰੀਵਲ ਅਤੇ ਜੈਨਰੇਸ਼ਨ ਨੂੰ ਜੋੜਦਾ ਹੈ। -**ਸਮੇਤਤਾ ਸਕੋਰ** - ਸੈਮੈਂਟਿਕ ਸਮਾਨਤਾ ਦਾ ਮਾਪ (0-1)। +**ਸਮਾਨਤਾ ਸਕੋਰ** - ਸੈਮੈਂਟਿਕ ਸਮਾਨਤਾ ਦੀ ਮਾਪ (0-1)। -**ਸਰੋਤ ਸੰਦਰਭ** - ਪ੍ਰਾਪਤ ਸਮੱਗਰੀ ਬਾਰੇ ਮੈਟਾਡੇਟਾ। +**ਸਰੋਤ ਰੈਫਰੈਂਸ** - ਪ੍ਰਾਪਤ ਸਮੱਗਰੀ ਬਾਰੇ ਮੈਟਾਡੇਟਾ। -## ਏਜੰਟ ਅਤੇ ਔਜ਼ਾਰ - [ਮੋਡਿਊਲ 04](../04-tools/README.md) +## ਏਜੰਟ ਅਤੇ ਟੂਲਜ਼ - [ਮਾਡਿਊਲ 04](../04-tools/README.md) -**@Tool ਐਨੋਟੇਸ਼ਨ** - ਜਾਵਾ ਮੈਥਡਜ਼ ਨੂੰ AI-ਕਾਲੇਬਲ ਟੂਲ ਵਜੋਂ ਨਿਸ਼ਾਨਤ ਕਰਦਾ ਹੈ। +**@Tool ਐਨੋਟੇਸ਼ਨ** - ਜਾਵਾ ਮੈਥਡਾਂ ਨੂੰ AI ਕਾਲ ਕਰਨ ਯੋਗ ਟੂਲ ਮਾਰਕ ਕਰਦਾ ਹੈ। -**ReAct ਪੈਟਰਨ** - ਸੋਚੋ → ਕੰਮ ਕਰੋ → ਦੇਖੋ → ਦੁਹਰਾਓ। +**ReAct ਪੈਟਰਨ** - ਤਰਕ → ਕਾਰਵਾਈ → ਮਾਨਿਟਰ → ਦੁਹਰਾਉ। -**ਸੈਸ਼ਨ ਪ੍ਰਬੰਧਨ** - ਵੱਖ-ਵੱਖ ਉਪਭੋਗਤਿਆਂ ਲਈ ਵੱਖਰੇ ਸੰਦਰਭ। +**ਸੈਸ਼ਨ ਪ੍ਰਬੰਧਨ** - ਵੱਖ-ਵੱਖ ਉਪਭੋਗਤਾਵਾਂ ਲਈ ਅਲੱਗ ਸੰਦਰਭ। -**ਟੂਲ** - ਇੱਕ ਐਸਾ ਫੰਕਸ਼ਨ ਜਿਸਨੂੰ AI ਏਜੰਟ ਕਾਲ ਕਰ ਸਕਦਾ ਹੈ। +**ਟੂਲ** - ਫੰਕਸ਼ਨ ਜੋ AI ਏਜੰਟ ਕਾਲ ਕਰ ਸਕਦਾ ਹੈ। -**ਟੂਲ ਵਰਨਨ** - ਟੂਲ ਦੇ ਉਦੇਸ਼ ਅਤੇ ਪੈਰਾਮੀਟਰਾਂ ਦਾ ਦਸਤਾਵੇਜ਼। +**ਟੂਲ ਵਰਨਨ** - ਟੂਲ ਮਕਸਦ ਅਤੇ ਪੈਰਾਮੀਟਰਾਂ ਦੀ ਦਸਤਾਵੇਜ਼ੀਕਰਨ। -## ਏਜੈਂਟਿਕ ਮੋਡਿਊਲ - [ਮੋਡਿਊਲ 05](../05-mcp/README.md) +## ਏਜੰਟਿਕ ਮਾਡਿਊਲ - [ਮਾਡਿਊਲ 05](../05-mcp/README.md) -**@Agent ਐਨੋਟੇਸ਼ਨ** - ਇੰਟਰਫੇਸਾਂ ਨੂੰ AI ਏਜੰਟ ਵਜੋਂ ਨਿਸ਼ਾਨਤ ਕਰਦਾ ਹੈ ਜਿਸ ਵਿੱਚ ਪਿਛੋਕੜ ਆਚਰਨ ਦੀ ਘੋਸ਼ਣਾ ਹੁੰਦੀ ਹੈ। +**@Agent ਐਨੋਟੇਸ਼ਨ** - ਇੰਟਰਫੇਸਾਂ ਨੂੰ AI ਏਜੰਟ ਮਾਰਕ ਕਰਦਾ ਹੈ ਜਿਸ ਨਾਲ ਘੋਸ਼ਣਾਤਮਕ ਵਿਹਾਰ ਪਰਿਭਾਸ਼ਿਤ ਹੁੰਦਾ ਹੈ। -**Agent Listener** - `beforeAgentInvocation()` ਅਤੇ `afterAgentInvocation()` ਰਾਹੀਂ ਏਜੰਟ ਕਾਰਜਬੰਦੀ ਦੀ ਨਿਗਰਾਨੀ ਲਈ ਕੁੱਕੜ। +**Agent Listener** - `beforeAgentInvocation()` ਅਤੇ `afterAgentInvocation()` ਰਾਹੀਂ ਏਜੰਟ ਕਾਰਜ ਦਾ ਨਿਰੀਖਣ ਕਰਨ ਦਾ ਜੁੜਾ ਹੋਇਆ ਹੂਕ। -**Agentic Scope** - ਸਾਂਝਾ ਮੈਮੋਰੀ ਜਿੱਥੇ ਏਜੰਟ ਨਤੀਜੇ `outputKey` ਦੀ ਵਰਤੋਂ ਨਾਲ ਸਟੋਰ ਕਰਦੇ ਹਨ ਤਾਂ ਜੋ ਹੇਠਲੇ ਏਜੰਟ ਵਰਤ ਸਕਣ। +**Agentic Scope** - ਸਾਂਝਾ ਮੈਮੋਰੀ ਜਿੱਥੇ ਏਜੰਟ ਆਪਣੇ ਨਤੀਜੇ ਭੰਡਾਰਿਤ ਕਰਦੇ ਹਨ, ਅਤੇ ਹੇਠਲਾ ਏਜੰਟ ਖਪਤ ਲਈ `outputKey` ਵਰਤਦਾ ਹੈ। -**AgenticServices** - `agentBuilder()` ਅਤੇ `supervisorBuilder()` ਦੀ ਵਰਤੋਂ ਨਾਲ ਏਜੰਟ ਬਣਾਉਣ ਲਈ ਫੈਕਟਰੀ। +**AgenticServices** - `agentBuilder()` ਅਤੇ `supervisorBuilder()` ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਏਜੰਟ ਬਣਾਉਣ ਲਈ ਫੈਕਟਰੀ। -**ਸ਼ਰਤੀ ਵਹਿਬਾਅ** - ਹਾਲਾਤ ਦੇ ਆਧਾਰ 'ਤੇ ਵੱਖ-ਵੱਖ ਵਿਸ਼ੇਸ਼ਗਿਆ ਏਜੰਟਾਂ ਨੂੰ ਰਾਹ ਦਿਖਾਉਣਾ। +**ਸ਼ਰਤੀ ਤਹਿਤ ਵਰਕਫਲੋ** - ਵੱਖ-ਵੱਖ ਵਿਸ਼ੇਸ਼ਗਿਆ ਏਜੰਟਾਂ ਲਈ ਸਥਿਤੀਆਂ ਅਨੁਸਾਰ ਰਸਤਾ। -**ਹਿਊਮਨ-ਇਨ-ਦਾ-ਲੂਪ** - ਮਨੁੱਖੀ ਪੁਸ਼ਟੀ ਜਾਂ ਸਮੱਗਰੀ ਸਮੀਖਿਆ ਲਈ ਵਹਿਬਾਅ ਦਰਜਾ। +**Human-in-the-Loop** - ਮਨੁੱਖੀ ਚੈੱਕਪੋਇੰਟ ਜੋੜਨ ਵਾਲਾ ਵਰਕਫਲੋ ਪੈਟਰਨ ਜਿਵੇਂ ਮਨਜ਼ੂਰੀ ਜਾਂ ਸਮੱਗਰੀ ਸਮੀਖਿਆ ਲਈ। -**langchain4j-agentic** - ਘੋਸ਼ਨਾਤਮਕ ਏਜੰਟ ਬਨਾਉਣ ਲਈ ਮਾਵਨ ਨਿਰਭਰਤਾ (ਪਰਯੋਗਸ਼ਾਲਾ ਵਾਲਾ)। +**langchain4j-agentic** - ਘੋਸ਼ਣਾਤਮਕ ਏਜੰਟ ਬਣਾਉਣ ਲਈ Maven ਡੀਪੈਂਡੇਸੀ (ਪਰਖ ਮੁਕਾਬਲਾ)। -**ਲੂਪ ਵਹਿਬਾਅ** - ਸ਼ਰਤ ਪੂਰੀ ਹੋਣ ਤੱਕ ਏਜੰਟ ਚਲਾਉਣਾ (ਜਿਵੇਂ ਕਿ ਗੁਣਵੱਤਾ ਸਕੋਰ ≥ 0.8)। +**ਲੂਪ ਵਰਕਫਲੋ** - ਇੱਕ ਸ਼ਰਤ ਨੂੰ ਪੂਰਾ ਕਰਨ ਤੱਕ ਏਜੰਟ ਕਾਰਜ ਨੂੰ ਦੁਹਰਾਉਣਾ (ਜਿਵੇਂ ਗੁਣਵੱਤਾ ਸਕੋਰ ≥ 0.8)। -**outputKey** - ਏਜੰਟ ਐਨੋਟੇਸ਼ਨ ਪੈਰਾਮੀਟਰ ਜੋ ਦੱਸਦਾ ਹੈ ਕਿ ਨਤੀਜੇ Agentic Scope ਵਿੱਚ ਕਿੱਥੇ ਸਟੋਰ ਕਰਨੇ ਹਨ। +**outputKey** - ਏਜੰਟ ਐਨੋਟੇਸ਼ਨ ਪੈਰਾਮੀਟਰ ਜੋ ਦਰਸਾਉਂਦਾ ਹੈ ਕਿ ਨਤੀਜੇ Agentic Scope ਵਿੱਚ ਕਿੱਥੇ ਸਟੋਰ ਕਰਨੇ ਹਨ। -**ਪੈਰਾਲੈਲ ਵਹਿਬਾਅ** - ਸੁਤੰਤਰ ਕੰਮਾਂ ਲਈ ਇੱਕ ਹੀ ਸਮੇਂ ਕਈ ਏਜੰਟ ਚਲਾਉਣਾ। +**ਪੈਰੱਲਲ ਵਰਕਫਲੋ** - ਵੱਖ-ਵੱਖ ਕੰਮਾਂ ਲਈ ਕਈ ਏਜੰਟ ਇਕੱਠੇ ਚਲਾਉਣਾ। -**ਰੇਸਪਾਂਸ ਰਣਨੀਤੀ** - ਸੁਪਰਵਾਈਜ਼ਰ ਅੰਤਿਮ ਜਵਾਬ ਕਿਵੇਂ ਤਿਆਰ ਕਰਦਾ ਹੈ: LAST, SUMMARY, ਜਾਂ SCORED। +**ਜਵਾਬ ਰਣਨੀਤੀ** - ਸੁਪਰਵਾਈਜ਼ਰ ਅੰਤਿਮ ਉੱਤਰ ਕਿਸ ਤਰ੍ਹਾਂ ਬਣਾਉਂਦਾ ਹੈ: LAST, SUMMARY ਜਾਂ SCORED। -**ਸੀਕਵੇਂਸ਼ਲ ਵਹਿਬਾਅ** - ਓਰਡਰ ਵਿੱਚ ਏਜੰਟ ਚਲਾਉਣਾ ਜਿੱਥੇ ਨਤੀਜਾ ਅਗਲੇ ਕਦਮ ਲਈ ਜਾਂਦਾ ਹੈ। +**ਲੜੀਵਾਰ ਵਰਕਫਲੋ** - ਏਜੰਟਾਂ ਨੂੰ ਕ੍ਰਮਵਾਰ ਚਲਾਉਣਾ, ਜਿੱਥੇ ਆਉਟਪੁੱਟ ਅਗਲੇ ਕਦਮ ਨੂੰ ਮਿਲਦਾ ਹੈ। -**ਸੁਪਰਵਾਈਜ਼ਰ ਏਜੰਟ ਪੈਟਰਨ** - ਇੱਕ ਅਗਲੀ ਪੱਧਰੀ ਏਜੈਂਟਿਕ ਪੈਟਰਨ, ਜਿਸ ਵਿੱਚ ਸੁਪਰਵਾਈਜ਼ਰ LLM ਗਤੀਸ਼ੀਲ ਤੌਰ 'ਤੇ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕਿਹੜੇ ਉਪ-ਏਜੰਟ ਕਾਲ ਕਰਨੇ ਹਨ। +**ਸੁਪਰਵਾਈਜ਼ਰ ਏਜੰਟ ਪੈਟਰਨ** - ਉੱਨਤ ਏਜੰਟਿਕ ਪੈਟਰਨ ਜਿੱਥੇ ਇੱਕ ਸੁਪਰਵਾਈਜ਼ਰ LLM ਗਤੀਸ਼ੀਲ ਤੌਰ 'ਤੇ ਫੈਸਲਾ ਕਰਦਾ ਹੈ ਕਿ ਕਿਹੜੇ ਸਬ-ਏਜੰਟਾਂ ਨੂੰ ਕਾਲ ਕਰਨਾ ਹੈ। -## ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰਭਾਅ (MCP) - [ਮੋਡਿਊਲ 05](../05-mcp/README.md) +## ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰੋਟੋਕੋਲ (MCP) - [ਮਾਡਿਊਲ 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j ਵਿੱਚ MCP ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਲਈ ਮਾਵਨ ਨਿਰਭਰਤਾ। +**langchain4j-mcp** - LangChain4j ਵਿੱਚ MCP ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਲਈ Maven ਡੀਪੈਂਡੇਸੀ। -**MCP** - ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰੋਟੋਕੋਲ: ਬਾਹਰੀ ਟੂਲਾਂ ਨਾਲ AI ਐਪਸ ਜੋੜਨ ਦਾ ਮਿਆਰੀ ਤਰੀਕਾ। ਇਕ ਵਾਰੀ ਬਣਾਓ, ਹਰ ਜਗ੍ਹਾਂ ਵਰਤੋਂ। +**MCP** - ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰੋਟੋਕੋਲ: ਬਾਹਰੀ ਟੂਲਜ਼ ਨਾਲ AI ਐਪਸ ਨੂੰ ਜੁੜਨ ਲਈ ਮਿਆਰੀਕृत ਤਰੀਕਾ। ਇਕ ਵਾਰੀ ਬਣਾਓ, ਹਰ ਥਾਂ ਵਰਤੋ। -**MCP ਕਲਾਇੰਟ** - ਐਪਲੀਕੇਸ਼ਨ ਜੋ MCP ਸਰਵਰਾਂ ਨਾਲ ਜੁੜ ਕੇ ਟੂਲ ਵਰਤਦਾ ਹੈ। +**MCP ਕਲਾਇੰਟ** - ਐਪਲੀਕੇਸ਼ਨ ਜੋ MCP ਸਰਵਰ ਨਾਲ ਜੁੜਦਾ ਹੈ ਅਤੇ ਟੂਲਜ਼ ਦੀ ਖੋਜ ਅਤੇ ਵਰਤੋਂ ਕਰਦਾ ਹੈ। -**MCP ਸਰਵਰ** - MCP ਕੇ ذریعے ਟੂਲਾਂ ਨੂੰ ਸੇਵਾ ਦੇਂਦਾ ਹੈ, ਸਾਫ਼ ਵਰਣਨ ਤੇ ਪੈਰਾਮੀਟਰ ਸਕੀਮਾਂ ਸਮੇਤ। +**MCP ਸਰਵਰ** - ਇਹ ਸੇਵਾ MCP ਰਾਹੀਂ ਟੂਲਜ਼ ਪ੍ਰਦਾਨ ਕਰਦੀ ਹੈ ਜਿਸ ਵਿੱਚ ਸਾਫ਼ ਵਰਣਨ ਅਤੇ ਪੈਰਾਮੀਟਰ ਸਕੀਮਾ ਹੁੰਦੇ ਹਨ। -**McpToolProvider** - LangChain4j ਘਟਕ ਜੋ MCP ਟੂਲਾਂ ਨੂੰ AI ਸੇਵਾਵਾਂ ਅਤੇ ਏਜੰਟਾਂ ਵਿੱਚ ਵਰਤਣ ਲਈ ਰੈਪ ਕਰਦਾ ਹੈ। +**McpToolProvider** - LangChain4j ਕੰਪੋਨੇਨਟ ਜੋ MCP ਟੂਲਜ਼ ਨੂੰ AI ਸੇਵਾਵਾਂ ਅਤੇ ਏਜੰਟਾਂ ਵਿੱਚ ਵਰਤੋਂ ਲਈ ਲਪੇਟਦਾ ਹੈ। -**McpTransport** - MCP ਸੰਚਾਰ ਲਈ ਇੰਟਰਫੇਸ। ਇਸ ਦੇ ਅਮਲ ਵਿੱਚ Stdio ਅਤੇ HTTP ਸ਼ਾਮਲ ਹਨ। +**McpTransport** - MCP ਸੰਚਾਰ ਲਈ ਇੰਟਰਫੇਸ। ਇਸ ਦੇ ਲਾਗੂ ਕਰਨ ਵਿੱਚ Stdio ਅਤੇ HTTP ਸ਼ਾਮਿਲ ਹਨ। -**Stdio ਟਰਾਂਸਪੋਰਟ** - stdin/stdout ਰਾਹੀਂ ਸਥਾਨਕ ਪ੍ਰਕਿਰਿਆ ਟਰਾਂਸਪੋਰਟ। ਫਾਇਲ ਸਿਸਟਮ ਪਹੁੰਚ ਜਾਂ ਕਮਾਂਡ-ਲਾਈਨ ਟੂਲ ਲਈ ਲਾਭਦਾਇਕ। +**Stdio ਟ੍ਰਾਂਸਪੋਰਟ** - stdin/stdout ਰਾਹੀਂ ਦੇਸੀ ਪ੍ਰੋਸੈਸ ਟ੍ਰਾਂਸਪੋਰਟ। ਫਾਇਲ ਸਿਸਟਮ ਪਹੁੰਚ ਜਾਂ ਕਮਾਂਡ-ਲਾਈਨ ਟੂਲਜ਼ ਲਈ ਲਾਭਦਾਇਕ। -**StdioMcpTransport** - LangChain4j ਦਾ ਐਪਲੀਕੇਸ਼ਨ ਜੋ MCP ਸਰਵਰ ਨੂੰ ਸਬ-ਪ੍ਰਕਿਰਿਆ ਵਜੋਂ ਸਪੌਨ ਕਰਦਾ ਹੈ। +**StdioMcpTransport** - LangChain4j ਲਾਗੂ ਕਰਨ ਵਾਂਗ MCP ਸਰਵਰ ਨੂੰ ਸਬਪ੍ਰੋਸੈਸ ਵਜੋਂ ਚਲਾਉਂਦਾ ਹੈ। -**ਟੂਲ ਖੋਜ** - ਕਲਾਇੰਟ ਸਰਵਰ ਤੋਂ ਉਪਲੱਬਧ ਟੂਲਾਂ ਬਾਰੇ ਵਰਣਨ ਅਤੇ ਸਕੀਮਾਂ ਪੁੱਛਦਾ ਹੈ। +**ਟੂਲ ਖੋਜ** - ਕਲਾਇੰਟ ਸਰਵਰ ਤੋਂ ਉਪਲਬਧ ਟੂਲਜ਼ ਦੀ ਵਰਣਨਾ ਅਤੇ ਸਕੀਮਾਂ ਸਮੇਤ ਪੁੱਛਗਿੱਛ ਕਰਦਾ ਹੈ। -## ਅਜ਼ੂਰ ਸੇਵਾਵਾਂ - [ਮੋਡਿਊਲ 01](../01-introduction/README.md) +## ਐਜ਼ਿਊਰ ਸੇਵਾਵਾਂ - [ਮਾਡਿਊਲ 01](../01-introduction/README.md) -**ਅਜ਼ੂਰ AI ਸੇਰਚ** - ਵੈਕਟਰ ਸਮਰੱਥਾ ਵਾਲੀ ਕਲਾਉਡ ਖੋਜ। [ਮੋਡਿਊਲ 03](../03-rag/README.md) +**Azure AI Search** - ਵੇਕਟਰ ਸਮਰੱਥਾ ਸਮੇਤ ਕਲਾਉਡ ਖੋਜ। [ਮਾਡਿਊਲ 03](../03-rag/README.md) -**ਅਜ਼ੂਰ ਡਿਵੈਲਪਰ CLI (azd)** - ਅਜ਼ੂਰ ਸਰੋਤ ਤਿਆਰ ਕਰਦਾ ਹੈ। +**Azure Developer CLI (azd)** - Azure ਸਰੋਤਾਂ ਨੂੰ ਤੈਅ ਕਰਨ ਲਈ। -**ਅਜ਼ੂਰ OpenAI** - ਮਾਈਕ੍ਰੋਸੌਫਟ ਦਾ ਏੰਟਰਪਰਾਈਜ਼ AI ਸੇਵਾ। +**Azure OpenAI** - ਮਾਈਕਰੋਸਾਫਟ ਦੀ ਐਂਟਰਪ੍ਰਾਈਜ਼ AI ਸੇਵਾ। -**ਬਾਇਸਪ** - ਅਜ਼ੂਰ ਇੰਫ਼ਰਾਸਟ੍ਰੱਕਚਰ-ਐਜ਼-ਕੋਡ ਭਾਸ਼ਾ। [ਇੰਫ਼ਰਾਸਟ੍ਰੱਕਚਰ ਗਾਈਡ](../01-introduction/infra/README.md) +**Bicep** - ਐਜ਼ਿਊਰ ਇੰਫ਼ਰਾਸਟਰੱਕਚਰ-ਐਜ਼-ਕੋਡ ਭਾਸ਼ਾ। [ਇੰਫ੍ਰਾਸਟਰੱਕਚਰ ਗਾਈਡ](../01-introduction/infra/README.md) -**ਡਿਪਲੋਇਮੈਂਟ ਨਾਮ** - ਅਜ਼ੂਰ ਵਿੱਚ ਮਾਡਲ ਡਿਪਲੋਇਮੈਂਟ ਲਈ ਨਾਮ। +**Deployment Name** - Azure ਵਿੱਚ ਮਾਡਲ ਤੈਅ ਕਰਨ ਦਾ ਨਾਮ। -**GPT-5.2** - ਨਵਾਂ OpenAI ਮਾਡਲ ਜਿਹੜਾ ਤਰਕ ਨਿਯੰਤਰਿਤ ਕਰਦਾ ਹੈ। [ਮੋਡਿਊਲ 02](../02-prompt-engineering/README.md) +**GPT-5.2** - ਤਾਜ਼ਾ OpenAI ਮਾਡਲ ਜੋ ਤਰਕ ਨਿਯੰਤਰਣ ਨਾਲ ਹੈ। [ਮਾਡਿਊਲ 02](../02-prompt-engineering/README.md) ## ਟੈਸਟਿੰਗ ਅਤੇ ਵਿਕਾਸ - [ਟੈਸਟਿੰਗ ਗਾਈਡ](TESTING.md) -**ਡੈਵ ਕਨਟੇਨਰ** - ਕੰਟੇਨਰਕ੍ਰਿਤ ਵਿਕਾਸ ਵਾਤਾਵਰਣ। [ਸੰਰਚਨਾ](../../../.devcontainer/devcontainer.json) - -**GitHub ਮਾਡਲ** - ਮੁਫ਼ਤ AI ਮਾਡਲ ਪਲੇਅਗ੍ਰਾਊਂਡ। [ਮੋਡਿਊਲ 00](../00-quick-start/README.md) +**Dev Container** - ਕੰਟੇਨਰਾਈਜ਼ਡ ਵਿਕਾਸ ਵਾਤਾਵਰਣ। [ਸੰਰਚਨਾ](../../../.devcontainer/devcontainer.json) **ਇਨ-ਮੇਮੋਰੀ ਟੈਸਟਿੰਗ** - ਇਨ-ਮੇਮੋਰੀ ਸਟੋਰੇਜ ਨਾਲ ਟੈਸਟਿੰਗ। -**ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਟੈਸਟਿੰਗ** - ਅਸਲੀ ਇੰਫ਼ਰਾਸਟ੍ਰੱਕਚਰ ਨਾਲ ਟੈਸਟਿੰਗ। +**ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਟੈਸਟਿੰਗ** - ਅਸਲੀ ਢਾਂਚੇ ਨਾਲ ਟੈਸਟਿੰਗ। -**ਮਾਵਨ** - ਜਾਵਾ ਬਿਲਡ ਆਟੋਮੇਸ਼ਨ ਟੂਲ। +**Maven** - ਜਾਵਾ ਬਿਲਡ ਆਟੋਮੇਸ਼ਨ ਟੂਲ। **Mockito** - ਜਾਵਾ ਮੌਕਿੰਗ ਫ੍ਰੇਮਵਰਕ। -**Spring Boot** - ਜਾਵਾ ਐਪਲੀਕੇਸ਼ਨ ਫ੍ਰੇਮਵਰਕ। [ਮੋਡਿਊਲ 01](../01-introduction/README.md) +**Spring Boot** - ਜਾਵਾ ਐਪਲੀਕੇਸ਼ਨ ਫ੍ਰੇਮਵਰਕ। [ਮਾਡਿਊਲ 01](../01-introduction/README.md) --- -**ਅਸਵੀਕਾਰਤਾ**: -ਇਹ ਦਸਤਾਵੇਜ਼ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਨਾਲ ਅਨੁਵਾਦਿਤ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾ ਲਈ ਕੋਸ਼ਿਸ਼ ਕਰਦੇ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਵਿੱਚ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਣਸਹੀਤੀਆਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਜਿਹੜਾ ਇਸ ਦੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਹੈ, ਉਹ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਮਹੱਤਵਪੂਰਨ ਜਾਣਕਾਰੀ ਲਈ, ਪ੍ਰੋਫੈਸ਼ਨਲ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੀ ਵਰਤੋਂ ਨਾਲ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਮੀਆਂ ਜਾਂ ਅਸਪਸ਼ਟਤਾਵਾਂ ਲਈ ਜ਼ਿੰਮੇਵਾਰ ਨਹੀਂ ਹਾਂ। +**ਅਸਵੀਕਾਰੋਪਣ**: +ਇਸ ਦਸਤਾਵੇਜ਼ ਦਾ ਅਨੁਵਾਦ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾਵਾਂ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਮੱਤਿਆਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਜਰੂਰੀ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੇ ਉਪਯੋਗ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਗਲਤ ਵਿਆਖਿਆਵਾਂ ਲਈ ਜਵਾਬਦੇਹ ਨਹੀਂ ਹਾਂ। \ No newline at end of file diff --git a/translations/pa/docs/TESTING.md b/translations/pa/docs/TESTING.md index 08b9acd41..54f8da59f 100644 --- a/translations/pa/docs/TESTING.md +++ b/translations/pa/docs/TESTING.md @@ -1,20 +1,20 @@ -# Testing LangChain4j Applications +# LangChain4j ਐਪਲੀਕੇਸ਼ਨਾਂ ਦੀ ਟੈਸਟਿੰਗ -## Table of Contents +## ਸੂਚੀ ਸਾਰਣੀ -- [Quick Start](../../../docs) -- [What the Tests Cover](../../../docs) -- [Running the Tests](../../../docs) -- [Running Tests in VS Code](../../../docs) -- [Testing Patterns](../../../docs) -- [Testing Philosophy](../../../docs) -- [Next Steps](../../../docs) +- [ਕੁਇੱਕ ਸਟਾਰਟ](#ਕੁਇੱਕ-ਸਟਾਰਟ) +- [ਟੈਸਟ ਕਿਵੇਂ ਕਵਰ ਕਰਦੇ ਹਨ](#ਟੈਸਟ-ਕਿਵੇਂ-ਕਵਰ-ਕਰਦੇ-ਹਨ) +- [ਟੈਸਟ ਚਲਾਉਣਾ](#ਟੈਸਟ-ਚਲਾਉਣਾ) +- [VS ਕੋਡ ਵਿੱਚ ਟੈਸਟ ਚਲਾਉਣਾ](#vs-ਕੋਡ-ਵਿੱਚ-ਟੈਸਟ-ਚਲਾਉਣਾ) +- [ਟੈਸਟਿੰਗ ਪੈਟਰਨ](#ਟੈਸਟਿੰਗ-ਪੈਟਰਨ) +- [ਟੈਸਟਿੰਗ ਫ਼ਿਲਾਸਫ਼ੀ](#ਟੈਸਟਿੰਗ-ਫ਼ਿਲਾਸਫ਼ੀ) +- [ਅਗਲੇ ਕਦਮ](#ਅਗਲੇ-ਕਦਮ) -This guide walks you through the tests that demonstrate how to test AI applications without requiring API keys or external services. +ਇਹ ਗਾਈਡ ਤੁਹਾਨੂੰ ਉਹਨਾਂ ਟੈਸਟਾਂ ਨਾਲ ਵਾਕਿਫ ਕਰਵਾਉਂਦੀ ਹੈ ਜੋ ਬਿਨਾਂ API ਕੁੰਜੀਆਂ ਜਾਂ ਬਾਹਰੀ ਸੇਵਾਵਾਂ ਦੀ ਲੋੜ ਦੇ AI ਐਪਲੀਕੇਸ਼ਨਾਂ ਨੂੰ ਟੈਸਟ ਕਰਨਾ ਵੇਖਾਉਂਦੀਆਂ ਹਨ। -## Quick Start +## ਕੁਇੱਕ ਸਟਾਰਟ -Run all tests with a single command: +ਸਾਰੇ ਟੈਸਟ ਇੱਕ ਕਮਾਂਡ ਨਾਲ ਚਲਾਓ: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -When all tests pass, you should see output like the screenshot below — tests run with zero failures. +ਜਦੋਂ ਸਾਰੇ ਟੈਸਟ ਪਾਸ ਹੋ ਜਾਣ, ਤਾਹੀਂ ਤੁਹਾਨੂੰ ਹੇਠਾਂ ਦਿੱਤੀ ਸਕ੍ਰੀਨਸ਼ਾਟ ਵਰਗਾ ਆਉਟਪੁੱਟ ਵੇਖਣ ਨੂੰ ਮਿਲੇਗਾ — ਸਾਰੇ ਟੈਸਟ ਬਿਨਾਂ ਕਿਸੇ ਅਸਫਲਤਾ ਦੇ ਚਲ ਰਹੇ ਹਨ। Successful Test Results -*Successful test execution showing all tests passing with zero failures* +*ਸਫਲ ਟੈਸਟ ਐਗਜ਼ੀਕਿਊਸ਼ਨ ਜਿਸ ਵਿੱਚ ਸਾਰੇ ਟੈਸਟ ਬਿਨਾਂ ਅਸਫਲਤਾ ਦੇ ਪਾਸ ਹੋ ਰਹੇ ਹਨ* -## What the Tests Cover +## ਟੈਸਟ ਕਿਵੇਂ ਕਵਰ ਕਰਦੇ ਹਨ -This course focuses on **unit tests** that run locally. Each test demonstrates a specific LangChain4j concept in isolation. The testing pyramid below shows where unit tests fit — they form the fast, reliable foundation that the rest of your test strategy builds on. +ਇਹ ਕੋਰਸ **ਯੂਨਿਟ ਟੈਸਟਾਂ** ’ਤੇ ਧਿਆਨ ਕੇਂਦਰਿਤ ਕਰਦਾ ਹੈ ਜੋ ਸਥਾਨਕ ਤੌਰ ’ਤੇ ਚਲਦੇ ਹਨ। ਹਰ ਟੈਸਟ LangChain4j ਦੇ ਇੱਕ ਖਾਸ ਸੰਕਲਪ ਨੂੰ ਅਲੱਗ ਕਰਕੇ ਦਰਸਾਉਂਦਾ ਹੈ। ਹੇਠਾਂ ਦਿੱਤਾ ਟੈਸਟਿੰਗ ਪਿਰਾਮਿਡ ਯੂਨਿਟ ਟੈਸਟਾਂ ਦੀ ਸਥਿਤੀ ਦਿਖਾਉਂਦਾ ਹੈ — ਇਹ ਤੇਜ਼, ਭਰੋਸੇਯੋਗ ਬੁਨਿਆਦ ਬਣਾਂਦੇ ਹਨ ਜਿਸ ’ਤੇ ਤੁਹਾਡੀ ਹੋਰ ਟੈਸਟ रणनीਤੀ ਨਿਰਭਰ ਕਰਦੀ ਹੈ। Testing Pyramid -*Testing pyramid showing the balance between unit tests (fast, isolated), integration tests (real components), and end-to-end tests. This training covers unit testing.* +*ਟੈਸਟਿੰਗ ਪਿਰਾਮਿਡ ਜੋ ਯੂਨਿਟ ਟੈਸਟਾਂ (ਤੇਜ਼, ਅਲੱਗ) ਅਤੇ ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਟੈਸਟਾਂ (ਅਸਲੀ ਕੰਪੋਨੈਂਟ) ਅਤੇ ਏਂਡ-ਟੂ-ਏਂਡ ਟੈਸਟਾਂ ਦੇ ਬਰਾਬਰੀ ਵੇਖਾਉਂਦਾ ਹੈ। ਇਹ ਤਾਲੀਮ ਯੂਨਿਟ ਟੈਸਟਿੰਗ ’ਤੇ ਕਵਰ ਕਰਦੀ ਹੈ।* -| Module | Tests | Focus | Key Files | +| ਮੋਡੀਊਲ | ਟੈਸਟ | ਧਿਆਨ | ਮੁੱਖ ਫਾਈਲਾਂ | |--------|-------|-------|-----------| -| **00 - Quick Start** | 6 | Prompt templates and variable substitution | `SimpleQuickStartTest.java` | -| **01 - Introduction** | 8 | Conversation memory and stateful chat | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | GPT-5.2 patterns, eagerness levels, structured output | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Document ingestion, embeddings, similarity search | `DocumentServiceTest.java` | -| **04 - Tools** | 12 | Function calling and tool chaining | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol with Stdio transport | `SimpleMcpTest.java` | +| **01 - ਪਰਿਚਯ** | 8 | ਗੱਲਬਾਤ ਨੂੰ ਯਾਦ ਰੱਖਣਾ ਅਤੇ ਸਟੇਟਫੁਲ ਚੈਟ | `SimpleConversationTest.java` | +| **02 - ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ** | 12 | GPT-5.2 ਪੈਟਰਨ, ਉਤਸ਼ਾਹ ਦੇ ਪੱਧਰ, ਸੰਰਚਿਤ ਆਉਟਪੁੱਟ | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | ਦਸਤਾਵੇਜ਼ ਸ਼ਮੂਲੀਅਤ, ਐਂਬੈਡਿੰਗ, ਸਮਾਨਤਾ ਖੋਜ | `DocumentServiceTest.java` | +| **04 - ਟੂਲਜ਼** | 12 | ਫੰਕਸ਼ਨ ਕਾਲਿੰਗ ਅਤੇ ਟੂਲ ਚੇਨਿੰਗ | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰੋਟੋਕੋਲ ਸਟਡਿਓ ਟ੍ਰਾਂਸਪੋਰਟ ਨਾਲ | `SimpleMcpTest.java` | -## Running the Tests +## ਟੈਸਟ ਚਲਾਉਣਾ -**Run all tests from root:** +**ਰੂਟ ਤੋਂ ਸਾਰੇ ਟੈਸਟ ਚਲਾਓ:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Run tests for a specific module:** +**ਕਿਸੇ ਖਾਸ ਮੋਡੀਊਲ ਲਈ ਟੈਸਟ ਚਲਾਓ:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Run a single test class:** +**ਇੱਕ ਅਕੇਲਾ ਟੈਸਟ ਕਲਾਸ ਚਲਾਓ:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Run a specific test method:** +**ਕਿਸੇ ਖਾਸ ਟੈਸਟ ਮੇਥਡ ਨੂੰ ਚਲਾਓ:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#ਗੱਲਬਾਤ ਦਾ ਇਤਿਹਾਸ ਬਰਕਰਾਰ ਰੱਖਣਾ ਚਾਹੀਦਾ ਹੈ +mvn test -Dtest=SimpleConversationTest#ਗੱਲਬਾਤ ਦੀ ਇਤਿਹਾਸਕ ਰੱਖਿਆ ਜਾਰੀ ਰੱਖਣੀ ਚਾਹੀਦੀ ਹੈ ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#ਗੱਲਬਾਤ ਦਾ ਇਤਿਹਾਸ ਬਣਾਈ ਰੱਖਣਾ ਚਾਹੀਦਾ ਹੈ +mvn --% test -Dtest=SimpleConversationTest#ਗੱਲਬਾਤ ਦੇ ਇਤਿਹਾਸ ਨੂੰ ਬਣਾਈ ਰੱਖਣਾ ਚਾਹੀਦਾ ਹੈ ``` -## Running Tests in VS Code +## VS ਕੋਡ ਵਿੱਚ ਟੈਸਟ ਚਲਾਉਣਾ -If you're using Visual Studio Code, the Test Explorer provides a graphical interface for running and debugging tests. +ਜੇ ਤੁਸੀਂ Visual Studio Code ਵਰਤ ਰਹੇ ਹੋ, ਤਾਂ ਟੈਸਟ ਐਕਸਪਲੋਰਰ ਟੈਸਟ ਚਲਾਉਣ ਅਤੇ ਡਿਬੱਗ ਕਰਨ ਲਈ ਗ੍ਰਾਫਿਕਲ ਇੰਟਰਫੇਸ ਮੁਹੱਈਆ ਕਰਵਾਉਂਦਾ ਹੈ। VS Code Test Explorer -*VS Code Test Explorer showing the test tree with all Java test classes and individual test methods* +*VS ਕੋਡ ਟੈਸਟ ਐਕਸਪਲੋਰਰ ਸਾਰਾ ਜਾਵਾ ਟੈਸਟ ਕਲਾਸਾਂ ਅਤੇ ਇਕੱਲੇ ਟੈਸਟ ਮੇਥਡਾਂ ਨਾਲ ਟੈਸਟ ਟ్రీ ਦਿਖਾ ਰਿਹਾ ਹੈ* -**To run tests in VS Code:** +**VS ਕੋਡ ਵਿੱਚ ਟੈਸਟ ਚਲਾਉਣ ਲਈ:** -1. Open the Test Explorer by clicking the beaker icon in the Activity Bar -2. Expand the test tree to see all modules and test classes -3. Click the play button next to any test to run it individually -4. Click "Run All Tests" to execute the entire suite -5. Right-click any test and select "Debug Test" to set breakpoints and step through code +1. ਐਕਟਿਵਿਟੀ ਬਾਰ ਵਿੱਚ ਬੀਕਰ ਆਈਕਨ ’ਤੇ ਕਲਿੱਕ ਕਰਕੇ ਟੈਸਟ ਐਕਸਪਲੋਰਰ ਖੋਲ੍ਹੋ +2. ਸਾਰੇ ਮੋਡੀਊਲ ਅਤੇ ਟੈਸਟ ਕਲਾਸਾਂ ਵੇਖਣ ਲਈ ਟੈਸਟ ਟ੍ਰੀ ਖੋਲ੍ਹੋ +3. ਕਿਸੇ ਵੀ ਟੈਸਟ ਦੇ ਨਜ਼ਦੀਕ ਪਲੇ ਬਟਨ ’ਤੇ ਕਲਿੱਕ ਕਰਕੇ ਇੱਕੱਲਾ ਟੈਸਟ ਚਲਾਓ +4. "Run All Tests" ’ਤੇ ਕਲਿੱਕ ਕਰਕੇ ਸਾਰੀ ਸੂਟ ਚਲਾਓ +5. ਕਿਸੇ ਵੀ ਟੈਸਟ ’ਤੇ ਰਾਈਟ-ਕਲਿੱਕ ਕਰਕੇ "Debug Test" ਚੁਣੋ, ਬ੍ਰੇਕਪੋਇੰਟ ਸੈੱਟ ਕਰੋ ਅਤੇ ਕੋਡ ਨੂੰ ਕਦਮ-ਕਦਮ ਕਰਕੇ ਚਲਾਓ -The Test Explorer shows green checkmarks for passing tests and provides detailed failure messages when tests fail. +ਟੈਸਟ ਐਕਸਪਲੋਰਰ ਪਾਸ ਹੋਏ ਟੈਸਟਾਂ ਲਈ ਹਰੇ ਚੈਕਮਾਰਕ ਦਿਖਾਉਂਦਾ ਹੈ ਅਤੇ ਜਦੋਂ ਟੈਸਟ ਫੇਲ ਹੁੰਦੇ ਹਨ ਤਾਂ ਵਿਸਥਾਰਪੂਰਕ ਅਸਫਲਤਾ ਸੁਨੇਹੇ ਦਿੰਦੈ ਹੈ। -## Testing Patterns +## ਟੈਸਟਿੰਗ ਪੈਟਰਨ -### Pattern 1: Testing Prompt Templates +### ਪੈਟਰਨ 1: ਪ੍ਰਾਂਪਟ ਟੈਂਪਲੇਟ ਦੀ ਟੈਸਟਿੰਗ -The simplest pattern tests prompt templates without calling any AI model. You verify that variable substitution works correctly and prompts are formatted as expected. +ਸਭ ਤੋਂ ਸਧਾਰਣ ਪੈਟਰਨ ਪ੍ਰਾਂਪਟ ਟੈਂਪਲੇਟਾਂ ਨੂੰ ਟੈਸਟ ਕਰਦਾ ਹੈ ਬਿਨਾਂ ਕਿਸੇ AI ਮਾਡਲ ਨੂੰ ਕਾਲ ਕੀਤੇ। ਤੁਸੀਂ ਇਹ ਪੜਤਾਲ ਕਰਦੇ ਹੋ ਕਿ ਵੈਰੀਏਬਲ ਸਬਸਟੀਚਿਊਸ਼ਨ ਸਹੀ ਤਰ੍ਹਾਂ ਕੰਮ ਕਰਦਾ ਹੈ ਅਤੇ ਪ੍ਰਾਂਪਟ ਉਮੀਦ ਮੁਤਾਬਕ ਫਾਰਮੈਟ ਕੀਤੇ ਗਏ ਹਨ। Prompt Template Testing -*Testing prompt templates showing variable substitution flow: template with placeholders → values applied → formatted output verified* +*ਪ੍ਰਾਂਪਟ ਟੈਂਪਲੇਟ ਟੈਸਟਿੰਗ ਦਿਖਾਉਂਦਾ ਹੈ ਵੈਰੀਏਬਲ ਸਬਸਟੀਚਿਊਸ਼ਨ ਦਾ ਪ੍ਰਵਾਹ: ਟੈਂਪਲੇਟ ਵਿੱਚ ਪਲੇਸਹੋਲਡਰ → ਵੈਲਿਊਜ਼ ਲਾਗੂ → ਫਾਰਮੈਟ ਕੀਤਾ ਗਿਆ ਆਉਟਪੁੱਟ ਅਨੁਸ਼ੀਲਨ* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -This test lives in `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +ਇਹ ਪੈਟਰਨ ਸਬੂਤ ਕਰਦਾ ਹੈ ਕਿ ਵੈਰੀਏਬਲ ਸਬਸਟੀਚਿਊਸ਼ਨ ਸਹੀ ਤਰ੍ਹਾਂ ਕਾਰਜ ਕਰਦਾ ਹੈ ਅਤੇ ਪ੍ਰਾਂਪਟ ਉਮੀਦ ਮੁਤਾਬਕ ਫਾਰਮੈਟ ਕੀਤੇ ਗਏ ਹਨ — ਕੋਈ API ਕੁੰਜੀ ਜਾਂ ਮਾਡਲ ਕਾਲ ਦੀ ਲੋੜ ਨਹੀਂ। -**Run it:** +### ਪੈਟਰਨ 2: ਭਾਸ਼ਾ ਮਾਡਲਾਂ ਦਾ ਮੌਕਿੰਗ -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#ਟੈਸਟ ਪ੍ਰਾਂਪਟ ਟੈਮਪਲੇਟ ਫਾਰਮੈਟਿੰਗ -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#ਟੈਸਟ ਪ੍ਰਾਂਪਟ ਟੈਮਪਲੇਟ ਫਾਰਮੈਟਿੰਗ -``` - -### Pattern 2: Mocking Language Models - -When testing conversation logic, use Mockito to create fake models that return predetermined responses. This makes tests fast, free, and deterministic. +ਜਦੋਂ ਗੱਲਬਾਤ ਲਾਜਿਕ ਦੀ ਟੈਸਟਿੰਗ ਕਰਨੀ ਹੁੰਦੀ ਹੈ, ਤਾਂ Mockito ਵਰਤ ਕੇ ਨਕਲੀ ਮਾਡਲ ਬਣਾਓ ਜੋ ਨਿਰਧਾਰਿਤ ਜਵਾਬ ਵਾਪਸ ਦਿੰਦੇ ਹਨ। ਇਸ ਨਾਲ ਟੈਸਟ ਤੇਜ਼, ਮੁਫ਼ਤ ਅਤੇ ਨਿਰਣਾਇਤਮਕ ਬਣ ਜਾਂਦੇ ਹਨ। Mock vs Real API Comparison -*Comparison showing why mocks are preferred for testing: they're fast, free, deterministic, and require no API keys* +*ਤੁਲਨਾ ਦਿਖਾਈ ਗਈ ਹੈ ਕਿ ਟੈਸਟਿੰਗ ਲਈ ਮੌਕ ਕਿਉਂ ਵਧੀਆ ਹਨ: ਇਹ ਤੇਜ਼, ਮੁਫ਼ਤ, ਨਿਰਣਾਇਤਮਕ ਹਨ ਅਤੇ API ਕੁੰਜੀਆਂ ਦੀ ਲੋੜ ਨਹੀਂ* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 ਯੂਜ਼ਰ + 3 ਏਆਈ ਸੁਨੇਹੇ + assertThat(history).hasSize(6); // 3 ਉਪਭੋਗਤਾ + 3 ਏਆਈ ਸੁਨੇਹੇ } } ``` -This pattern appears in `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. The mock ensures consistent behavior so you can verify memory management works correctly. +ਇਹ ਪੈਟਰਨ `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` ਵਿੱਚ ਮਿਲਦਾ ਹੈ। ਮੌਕ ਯਕੀਨੀ ਬਣਾਉਂਦਾ ਹੈ ਕਿ ਅਪਮੈਮੋਰੀ ਪ੍ਰਬੰਧਨ ਸਹੀ ਤਰ੍ਹਾਂ ਕੰਮ ਕਰਦਾ ਹੈ। -### Pattern 3: Testing Conversation Isolation +### ਪੈਟਰਨ 3: ਗੱਲਬਾਤ ਦੀ ਅਲੱਗਾਵਟ ਦੀ ਟੈਸਟਿੰਗ -Conversation memory must keep multiple users separate. This test verifies that conversations don't mix contexts. +ਗੱਲਬਾਤ ਦੀ ਯਾਦ ਵਿੱਚ ਕਈ ਉਪਭੋਗਤਿਆਂ ਨੂੰ ਅਲੱਗ ਰੱਖਣਾ ਲਾਜ਼ਮੀ ਹੈ। ਇਹ ਟੈਸਟ ਯਕੀਨੀ ਬਣਾਉਂਦਾ ਹੈ ਕਿ ਗੱਲਬਾਤਾਂ ਵਿੱਚ ਹਾਲਤਾਂ ਮਿਲਦੀਆਂ-ਜੁਲਦੀਆਂ ਨਹੀਂ। Conversation Isolation -*Testing conversation isolation showing separate memory stores for different users to prevent context mixing* +*ਗੱਲਬਾਤ ਦੀ ਅਲੱਗਾਵਟ ਦੀ ਟੈਸਟਿੰਗ ਦਿਖਾਉਂਦੀ ਹੈ ਕਿ ਵੱਖ-ਵੱਖ ਉਪਭੋਗਤਿਆਂ ਲਈ ਅਲੱਗ ਯਾਦ ਸੰਗ੍ਰਹਿਤ ਕੀਤੀ ਜਾਂਦੀ ਹੈ ਤਾਂ ਜੋ ਸੰਦਰਭ ਮਿਸਮੈਚ ਨਾ ਹੋਵੇ* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Each conversation maintains its own independent history. In production systems, this isolation is critical for multi-user applications. +ਹਰ ਗੱਲਬਾਤ ਆਪਣੀ ਸੁਤੰਤਰ ਇਤਿਹਾਸ ਰੱਖਦੀ ਹੈ। ਉਤਪਾਦਨ ਪ੍ਰਣਾਲੀਆਂ ਵਿੱਚ, ਇਹ ਅਲੱਗਾਵਟ ਬਹੁ-ਉਪਭੋਗਤਾ ਐਪਲੀਕੇਸ਼ਨਾਂ ਲਈ ਜ਼ਰੂਰੀ ਹੁੰਦੀ ਹੈ। -### Pattern 4: Testing Tools Independently +### ਪੈਟਰਨ 4: ਸਵਤੰਤਰ ਟੂਲਜ਼ ਦੀ ਟੈਸਟਿੰਗ -Tools are functions the AI can call. Test them directly to ensure they work correctly regardless of AI decisions. +ਟੂਲਜ਼ ਉਹ ਫੰਕਸ਼ਨ ਹਨ ਜੋ AI ਕਾਲ ਕਰ ਸਕਦਾ ਹੈ। ਉਹਨਾਂ ਨੂੰ ਸਿੱਧਾ ਟੈਸਟ ਕਰੋ ਤਾਂ ਜੋ ਇਹ ਯਕੀਨੀ ਬਣੇ ਕਿ AI ਦੇ ਫੈਸਲਿਆਂ ਤੋਂ ਬਿਨਾਂ ਉਹ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਕੰਮ ਕਰਦੇ ਹਨ। Tools Testing -*Testing tools independently showing mock tool execution without AI calls to verify business logic* +*ਸਵਤੰਤਰ ਟੂਲ ਟੈਸਟਿੰਗ ਦਿਖਾਉਂਦੀ ਹੈ ਮੌਕ ਟੂਲ निष्पਾਦਨ ਬਿਨਾਂ AI ਕਾਲ ਦੇ, ਕਾਰੋਬਾਰੀ ਲਾਜ਼ਿਕ ਪਰਖਣ ਲਈ* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -These tests from `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validate tool logic without AI involvement. The chaining example shows how one tool's output feeds into another's input. +ਇਹ ਟੈਸਟ `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ਤੋਂ ਹਨ ਜੋ ਟੂਲ ਲਾਜਿਕ ਨੂੰ ਬਿਨਾਂ AI ਦੇ ਹਿੱਸੇ ਦੇ ਪਰਖਦੇ ਹਨ। ਚੇਨਿੰਗ ਉਦਾਹਰਨ ਦਿਖਾਉਂਦੀ ਹੈ ਕਿ ਇੱਕ ਟੂਲ ਦਾ ਆਉਟਪੁੱਟ ਕਿਵੇਂ ਦੂਜੇ ਦਾ ਇਨਪੁੱਟ ਬਣਦਾ ਹੈ। -### Pattern 5: In-Memory RAG Testing +### ਪੈਟਰਨ 5: ਇਨ-ਮੇਮੋਰੀ RAG ਟੈਸਟਿੰਗ -RAG systems traditionally require vector databases and embedding services. The in-memory pattern lets you test the entire pipeline without external dependencies. +RAG ਪ੍ਰਣਾਲੀਆਂ ਆਮ ਤੌਰ ’ਤੇ ਵੈਕਟਰ ਡੇਟਾਬੇਸ ਅਤੇ ਐਂਬੈਡਿੰਗ ਸੇਵਾਵਾਂ ਮੰਗਦੀਆਂ ਹਨ। ਇਨ-ਮੇਮੋਰੀ ਪੈਟਰਨ ਤੁਹਾਡੇ ਸਾਰੇ ਪਾਈਪਲਾਈਨ ਨੂੰ ਬਿਨਾਂ ਬਾਹਰੀ ਨਿਰਭਰਤਾਵਾਂ ਦੇ ਟੈਸਟ ਕਰਨ ਦਿੰਦਾ ਹੈ। In-Memory RAG Testing -*In-memory RAG testing workflow showing document parsing, embedding storage, and similarity search without requiring a database* +*ਇਨ-ਮੇਮੋਰੀ RAG ਟੈਸਟਿੰਗ ਵਰਕਫਲੋ ਦਿਖਾਉਂਦੀ ਹੈ ਦਸਤਾਵੇਜ਼ ਪਾਰਸਿੰਗ, ਐਂਬੈਡਿੰਗ ਸਟੋਰੇਜ ਅਤੇ ਸਮਾਨਤਾ ਖੋਜ ਬਿਨਾਂ ਕਿਸੇ ਡੇਟਾਬੇਸ ਦੀ ਲੋੜ ਦੇ* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -This test from `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` creates a document in memory and verifies chunking and metadata handling. +ਇਹ ਟੈਸਟ `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` ਤੋਂ ਹੈ ਜੋ ਮੈਮੋਰੀ ਵਿੱਚ ਦਸਤਾਵੇਜ਼ ਬਣਾਦਾ ਹੈ ਅਤੇ ਚੰਕਿੰਗ ਅਤੇ ਮੈਟਾਡੇਟਾ ਹੇਠਾਂ ਹੱਲ ਕਰਦਾ ਹੈ। -### Pattern 6: MCP Integration Testing +### ਪੈਟਰਨ 6: MCP ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਟੈਸਟਿੰਗ -The MCP module tests the Model Context Protocol integration using stdio transport. These tests verify that your application can spawn and communicate with MCP servers as subprocesses. +MCP ਮੋਡੀਊਲ ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰੋਟੋਕੋਲ ਦੀ ਇੰਟੀਗ੍ਰੇਸ਼ਨ stdio ਟ੍ਰਾਂਸਪੋਰਟ ਨਾਲ ਟੈਸਟ ਕਰਦਾ ਹੈ। ਇਹ ਟੈਸਟ ਯਕੀਨੀ ਬਣਾਉਂਦੇ ਹਨ ਕਿ ਤੁਹਾਡੀ ਐਪਲੀਕੇਸ਼ਨ MCP ਸਰਵਰਾਂ ਨੂੰ ਸਬਪ੍ਰੋਸੈਸ ਵਜੋਂ ਚਲਾ ਸਕਦੀ ਹੈ ਅਤੇ ਚਾਰਚਾ ਕਰ ਸਕਦੀ ਹੈ। -The tests in `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validate MCP client behavior. +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` ਦੇ ਟੈਸਟ MCP ਕਲਾਇੰਟ ਵਿਹਾਰ ਦੀ ਪੁਸ਼ਟੀ ਕਰਦੇ ਹਨ। -**Run them:** +**ਉਹਨਾਂ ਨੂੰ ਚਲਾਓ:** **Bash:** ```bash @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## Testing Philosophy +## ਟੈਸਟਿੰਗ ਫ਼ਿਲਾਸਫ਼ੀ -Test your code, not the AI. Your tests should validate the code you write by checking how prompts are constructed, how memory is managed, and how tools execute. AI responses vary and shouldn't be part of test assertions. Ask yourself whether your prompt template correctly substitutes variables, not whether the AI gives the right answer. +ਆਪਣੇ ਕੋਡ ਦੀ ਟੈਸਟਿੰਗ ਕਰੋ, AI ਦੀ ਨਹੀਂ। ਤੁਹਾਡੇ ਟੈਸਟ ਉਹ ਕੋਡ ਵੈਰੀਫਾਈ ਕਰਣੇ ਚਾਹੀਦੇ ਹਨ ਜੋ ਤੁਸੀਂ ਲਿਖਦੇ ਹੋ, ਇਹ ਜਾਂਚ ਕੇ ਕਿ ਪ੍ਰਾਂਪਟ ਕਿਵੇਂ ਬਣਾਏ ਗਏ ਹਨ, ਯਾਦ ਰੱਖਣ ਕਿਵੇਂ ਸੰਭਾਲੀ ਜਾਂਦੀ ਹੈ, ਅਤੇ ਟੂਲ ਕਿਵੇਂ ਚਲਦੇ ਹਨ। AI ਦੇ ਜਵਾਬ ਬਦਲ ਸਕਦੇ ਹਨ ਅਤੇ ਉਹ ਟੈਸਟ ਦਾਅਵਿਆਂ ਦਾ ਹਿੱਸਾ ਨਹੀਂ ਹੋਣੇ ਚਾਹੀਦੇ। ਆਪਣੇ ਆਪ ਨੂੰ ਪੁੱਛੋ ਕਿ ਕੀ ਤੁਹਾਡਾ ਪ੍ਰਾਂਪਟ ਟੈਂਪਲੇਟ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਵੈਰੀਏਬਲ ਸਬਸਟੀਚਿਊਟ ਕਰਦਾ ਹੈ, ਨਾ ਕਿ AI ਸਹੀ ਜਵਾਬ ਦਿੰਦਾ ਹੈ। -Use mocks for language models. They're external dependencies that are slow, expensive, and non-deterministic. Mocking makes tests fast with milliseconds instead of seconds, free with no API costs, and deterministic with the same result every time. +ਭਾਸ਼ਾ ਮਾਡਲਾਂ ਲਈ ਮੌਕਜ਼ ਦੀ ਵਰਤੋਂ ਕਰੋ। ਉਹ ਬਾਹਰੀ ਨਿਰਭਰਤਾਵਾਂ ਹਨ ਜੋ ਧੀਮੇ, ਮਹਿੰਗੇ ਅਤੇ ਗੈਰ-ਨਿਰਣਾਇਤਮਕ ਹੁੰਦੇ ਹਨ। ਮੌਕਿੰਗ ਨਾਲ ਟੈਸਟ ਤੇਜ਼ ਹੁੰਦੇ ਹਨ, ਮਿਲੀਸੈਕੰਡਾਂ ਵਿੱਚ, ਮੁਫ਼ਤ ਹੁੰਦੇ ਹਨ ਬਿਨਾਂ ਕਿਸੇ API ਖ਼ਰਚ ਦੇ, ਅਤੇ ਨਿਰਣਾਇਤਮਕ ਹੁੰਦੇ ਹਨ ਜੇਹੜੇ ਹਰ ਵਾਰੀ ਉਦੋਂਹੀ ਨਤੀਜੇ ਦਿੰਦੈ ਹਨ। -Keep tests independent. Each test should set up its own data, not rely on other tests, and clean up after itself. Tests should pass regardless of execution order. +ਟੈਸਟਾਂ ਨੂੰ ਸਵਤੰਤਰ ਰੱਖੋ। ਹਰ ਟੈਸਟ ਆਪਣਾ ਡਾਟਾ ਸੈਟਅੱਪ ਕਰੇ, ਦੂਜੇ ਟੈਸਟਾਂ ’ਤੇ ਨਿਰਭਰ ਨਾ ਕਰੇ, ਅਤੇ ਆਪਣੇ ਆਪ ਨੂੰ ਸਾਫ਼ ਕਰੇ। ਟੈਸਟ ਕਿਸੇ ਵੀ ਕ੍ਰਮ ਵਿੱਚ ਚੱਲਣ 'ਤੇ ਪਾਸ ਹੋਣੇ ਚਾਹੀਦੇ ਹਨ। -Test edge cases beyond the happy path. Try empty inputs, very large inputs, special characters, invalid parameters, and boundary conditions. These often reveal bugs that normal usage doesn't expose. +ਖੁਸ਼ਹਾਲ ਰਸਤੇ ਤੋਂ ਬਾਹਰ ਵੀ ਟੈਸਟ ਕਰੋ। ਖਾਲੀ ਇਨਪੁੱਟ, ਬਹੁਤ ਵੱਡੇ ਇਨਪੁੱਟ, ਵਿਸ਼ੇਸ਼ ਅੱਖਰ, ਗਲਤ ਪੈਰਾਮੀਟਰ, ਅਤੇ ਸੀਮਾ ਵਾਲੀਆਂ ਸਥਿਤੀਆਂ ਟੈਸਟ ਕਰੋ। ਇਹ ਅਕਸਰ ਉਹ ਬੱਗਜ਼ ਦਿਖਾਉਂਦੇ ਹਨ ਜੋ ਆਮ ਵਰਤੋਂ ਕਰਮ ਵਿੱਚ ਨਹੀਂ ਮਿਲਦੇ। -Use descriptive names. Compare `shouldMaintainConversationHistoryAcrossMultipleMessages()` with `test1()`. The first tells you exactly what's being tested, making debugging failures much easier. +ਵੇਰਵਾ ਵਾਲੇ ਨਾਮ ਵਰਤੋਂ। `shouldMaintainConversationHistoryAcrossMultipleMessages()` ਨਾਲ `test1()` ਦੀ ਤੁਲਨਾ ਕਰੋ। ਪਹਿਲਾ ਨਾਮ ਦੱਸਦਾ ਹੈ ਕਿ ਕੀ ਟੈਸਟ ਕੀਤਾ ਜਾ ਰਿਹਾ ਹੈ, ਜਿਸ ਨਾਲ ਫੇਲ ਹੋਣ 'ਤੇ ਡਿਬੱਗ ਕਰਨਾ ਬਹੁਤ ਆਸਾਨ ਹੁੰਦਾ ਹੈ। -## Next Steps +## ਅਗਲੇ ਕਦਮ -Now that you understand the testing patterns, dive deeper into each module: +ਹੁਣ ਜਦੋਂ ਤੁਸੀਂ ਟੈਸਟਿੰਗ ਪੈਟਰਨ ਸਮਝ ਗਏ ਹੋ, ਤਾਂ ਹਰ ਮੋਡੀਊਲ ਵਿਚ ਹੋਰ ਗਹਿਰਾਈ ’ਚ ਜਾਵੋ: -- **[00 - Quick Start](../00-quick-start/README.md)** - Start with prompt template basics -- **[01 - Introduction](../01-introduction/README.md)** - Learn conversation memory management -- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Master GPT-5.2 prompting patterns -- **[03 - RAG](../03-rag/README.md)** - Build retrieval-augmented generation systems -- **[04 - Tools](../04-tools/README.md)** - Implement function calling and tool chains -- **[05 - MCP](../05-mcp/README.md)** - Integrate Model Context Protocol +- **[01 - ਪਰਿਚਯ](../01-introduction/README.md)** - ਗੱਲਬਾਤ ਯਾਦ ਮੈਨੇਜਮੈਂਟ ਸਿੱਖੋ +- **[02 - ਪ੍ਰਾਂਪਟ ਇੰਜੀਨੀਅਰਿੰਗ](../02-prompt-engineering/README.md)** - GPT-5.2 ਪ੍ਰਾਂਪਟਿੰਗ ਪੈਟਰਨ ਮਾਹਿਰ ਬਣੋ +- **[03 - RAG](../03-rag/README.md)** - ਰੀਟ੍ਰੀਵਲ-ਆਗਮੈਂਟਿਡ ਜਨਰੇਸ਼ਨ ਸਿਸਟਮ ਬਣਾਓ +- **[04 - ਟੂਲਜ਼](../04-tools/README.md)** - ਫੰਕਸ਼ਨ ਕਾਲਿੰਗ ਅਤੇ ਟੂਲ ਚੇਨ ਬਣਾਓ +- **[05 - MCP](../05-mcp/README.md)** - ਮਾਡਲ ਸੰਦਰਭ ਪ੍ਰੋਟੋਕੋਲ ਨੂੰ ਇਕੱਠਾ ਕਰੋ -Each module's README provides detailed explanations of the concepts tested here. +ਹਰ ਮੋਡੀਊਲ ਦੀ README ਇਸ ਸਥਾਨ ‘ਤੇ ਟੈਸਟ ਕੀਤੇ ਸੰਕਲਪਾਂ ਦੀ ਵਿਸਥਾਰਪੂਰਕ ਵਿਆਖਿਆ ਮੁਹੱਈਆ ਕਰਦੀ ਹੈ। --- -**Navigation:** [← Back to Main](../README.md) +**ਨੈਵੀਗੇਸ਼ਨ:** [← ਮੁੱਖ ਤੇ ਵਾਪਸ](../README.md) --- -**ਅਸਵੀਕਾਰੋक्ति**: -ਇਸ ਦਸਤਾਵੇਜ਼ ਦਾ ਅਨੁਵਾਦ AI ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਨਾਲ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਦਿਓ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਮਰੱਥਤਾਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਨੂੰ ਇਸਦੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਪ੍ਰਮਾਣਿਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਮਹੱਤਵਪੂਰਨ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੀ ਵਰਤੋਂ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗ਼ਲਤਫਹਿਮੀਆਂ ਜਾਂ ਗਲਤ ਵਿਆਖਿਆਵਾਂ ਲਈ ਜ਼ਿੰਮੇਵਾਰ ਨਹੀਂ ਹਾਂ। +**ਅਸਵੀਕਾਰੋਪਣ**: +ਇਸ ਦਸਤਾਵੇਜ਼ ਦਾ ਅਨੁਵਾਦ ਏਆਈ ਅਨੁਵਾਦ ਸੇਵਾ [Co-op Translator](https://github.com/Azure/co-op-translator) ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਕੀਤਾ ਗਿਆ ਹੈ। ਜਦੋਂ ਕਿ ਅਸੀਂ ਸਹੀਤਾਵਾਂ ਲਈ ਯਤਨਸ਼ੀਲ ਹਾਂ, ਕਿਰਪਾ ਕਰਕੇ ਧਿਆਨ ਰੱਖੋ ਕਿ ਸਵੈਚਾਲਿਤ ਅਨੁਵਾਦਾਂ ਵਿੱਚ ਗਲਤੀਆਂ ਜਾਂ ਅਸਮੱਤਿਆਵਾਂ ਹੋ ਸਕਦੀਆਂ ਹਨ। ਮੂਲ ਦਸਤਾਵੇਜ਼ ਆਪਣੀ ਮੂਲ ਭਾਸ਼ਾ ਵਿੱਚ ਅਧਿਕਾਰਕ ਸਰੋਤ ਮੰਨਿਆ ਜਾਣਾ ਚਾਹੀਦਾ ਹੈ। ਜਰੂਰੀ ਜਾਣਕਾਰੀ ਲਈ, ਪੇਸ਼ੇਵਰ ਮਨੁੱਖੀ ਅਨੁਵਾਦ ਦੀ ਸਿਫ਼ਾਰਸ਼ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਅਸੀਂ ਇਸ ਅਨੁਵਾਦ ਦੇ ਉਪਯੋਗ ਤੋਂ ਪੈਦਾ ਹੋਣ ਵਾਲੀਆਂ ਕਿਸੇ ਵੀ ਗਲਤਫਹਿਮੀਆਂ ਜਾਂ ਗਲਤ ਵਿਆਖਿਆਵਾਂ ਲਈ ਜਵਾਬਦੇਹ ਨਹੀਂ ਹਾਂ। \ No newline at end of file diff --git a/translations/pcm/.co-op-translator.json b/translations/pcm/.co-op-translator.json index ac08abe1f..1dd37a85a 100644 --- a/translations/pcm/.co-op-translator.json +++ b/translations/pcm/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "pcm" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T22:15:13+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T09:21:08+00:00", "source_file": "01-introduction/README.md", "language_code": "pcm" }, @@ -18,20 +18,20 @@ "language_code": "pcm" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T22:17:37+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T09:17:22+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "pcm" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T22:19:01+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T09:20:24+00:00", "source_file": "03-rag/README.md", "language_code": "pcm" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:32:53+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T09:19:19+00:00", "source_file": "04-tools/README.md", "language_code": "pcm" }, @@ -54,8 +54,8 @@ "language_code": "pcm" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:00:28+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T09:16:17+00:00", "source_file": "README.md", "language_code": "pcm" }, @@ -72,14 +72,14 @@ "language_code": "pcm" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T22:22:24+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T09:17:46+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "pcm" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T22:23:07+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T09:18:18+00:00", "source_file": "docs/TESTING.md", "language_code": "pcm" } diff --git a/translations/pcm/00-quick-start/README.md b/translations/pcm/00-quick-start/README.md deleted file mode 100644 index 47f03ae24..000000000 --- a/translations/pcm/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Quick Start - -## Table of Contents - -- [Introduction](../../../00-quick-start) -- [Wetɪn be LangChain4j?](../../../00-quick-start) -- [LangChain4j Dependencies](../../../00-quick-start) -- [Prerequisites](../../../00-quick-start) -- [Setup](../../../00-quick-start) - - [1. Get Your GitHub Token](../../../00-quick-start) - - [2. Set Your Token](../../../00-quick-start) -- [Run the Examples](../../../00-quick-start) - - [1. Basic Chat](../../../00-quick-start) - - [2. Prompt Patterns](../../../00-quick-start) - - [3. Function Calling](../../../00-quick-start) - - [4. Document Q&A (Easy RAG)](../../../00-quick-start) - - [5. Responsible AI](../../../00-quick-start) -- [Wetɪn Each Example Dey Show](../../../00-quick-start) -- [Next Steps](../../../00-quick-start) -- [Troubleshooting](../../../00-quick-start) - -## Introduction - -Dis quickstart na to make you start quickly wit LangChain4j. E cover di simple simple basics of how to build AI applications wit LangChain4j and GitHub Models. For di next modules, you go change go Azure OpenAI and GPT-5.2 and learn deep pass about di concepts. - -## Wetɪn be LangChain4j? - -LangChain4j na Java library wey dey make e easy to build AI-powered applications. Instead make you dey use HTTP clients and dey parse JSON, you go dey work wit clean Java APIs. - -Di "chain" for LangChain mean say you go join different components together - fit be say you link prompt go model go parser, or join many AI calls where output from one go enter as input go next. Dis quick start dey focus on di basics before dem waka for complex chains. - -LangChain4j Chaining Concept - -*Joining components for LangChain4j - di building blocks dey connect to make strong AI workflows* - -We go use three core components: - -**ChatModel** - Na interface wey you use for AI model interaction. You fit call `model.chat("prompt")` come get response string. We dey use `OpenAiOfficialChatModel` wey dey work wit OpenAI-style endpoints like GitHub Models. - -**AiServices** - E dey create type-safe AI service interfaces. You define methods, put `@Tool` annotation, LangChain4j go handle di orchestration. AI go automatically call your Java methods when e need am. - -**MessageWindowChatMemory** - E dey keep all di conversation history. Without am, each request be like fresh one. With am, AI dey remember previous messages and keep di context over different turns. - -LangChain4j Architecture - -*LangChain4j architecture - core components dey work together to power your AI applications* - -## LangChain4j Dependencies - -Dis quick start dey use three Maven dependencies for di [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Di `langchain4j-open-ai-official` module dey provide `OpenAiOfficialChatModel` class wey dey connect to OpenAI-style APIs. GitHub Models dey use di same API format, so no special adapter need - just point di base URL to `https://models.github.ai/inference`. - -Di `langchain4j-easy-rag` module dey provide automatic document splitting, embedding, and retrieval so you fit build RAG apps without to set every step manually. - -## Prerequisites - -**You dey use Dev Container?** Java and Maven don already install. You only need GitHub Personal Access Token. - -**Local Development:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (instructions dey below) - -> **Note:** Dis module dey use `gpt-4.1-nano` from GitHub Models. No change di model name inside di code - e be configured for GitHub models dem wey dey. - -## Setup - -### 1. Get Your GitHub Token - -1. Go [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Click "Generate new token" -3. Set name wey make sense (like "LangChain4j Demo") -4. Set expiration (7 days dey recommended) -5. For "Account permissions", find "Models" set am to "Read-only" -6. Click "Generate token" -7. Copy and save your token - you no go see am again - -### 2. Set Your Token - -**Option 1: Using VS Code (Better Option)** - -If you dey use VS Code, put your token for `.env` file inside project root: - -If `.env` no dey, copy `.env.example` go `.env` or create new `.env` file for project root. - -**Example `.env` file:** -```bash -# Inside /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -You fit just right-click any demo file (for example `BasicChatDemo.java`) for Explorer and select **"Run Java"** or use launch configurations for Run and Debug panel. - -**Option 2: Using Terminal** - -Set token as environment variable: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Run the Examples - -**With VS Code:** Just right-click any demo file inside Explorer and select **"Run Java"**, or use launch configurations from Run and Debug panel (make sure say you don add token to `.env` file first). - -**With Maven:** Or you fit run from command line: - -### 1. Basic Chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Prompt Patterns - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -E dey show zero-shot, few-shot, chain-of-thought, and role-based prompting. - -### 3. Function Calling - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI go automatically call your Java methods when e need. - -### 4. Document Q&A (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -You fit ask questions about your documents using Easy RAG wey get automatic embedding and retrieval. - -### 5. Responsible AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -See as AI safety filters dey block harmful content. - -## Wetɪn Each Example Dey Show - -**Basic Chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Start here to see LangChain4j for e simplest form. You go create `OpenAiOfficialChatModel`, send prompt wit `.chat()`, then get response. This one na di foundation: how to start models wit custom endpoints and API keys. Once you understand dis pattern, every other thing go build on top. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) and ask: -> - "How I go waka from GitHub Models go Azure OpenAI for this code?" -> - "Wetin other parameters I fit configure inside OpenAiOfficialChatModel.builder()?" -> - "How I fit add streaming responses instead to dey wait for full response?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Now wey you sabi how to talk to model, mek we check wetin you go talk to am. Dis demo dey use di same model setup but e get five different prompt patterns. Try zero-shot prompts for direct instructions, few-shot prompts wey learn from examples, chain-of-thought prompts wey show reasoning steps, and role-based prompts wey set context. You go see how di same model fit give different results depending on how you take arrange your request. - -Di demo dey also show prompt templates, wey na strong way to create reusable prompts wit variables. -Below example show prompt wit LangChain4j `PromptTemplate` to fill variables. AI go answer base on destination and activity wey you give. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) and ask: -> - "Wetin be di difference between zero-shot and few-shot prompting, and when I suppose use each?" -> - "How di temperature parameter dey affect model responses?" -> - "Wetin be some ways to stop prompt injection attacks for production?" -> - "How I fit create reusable PromptTemplate objects for common patterns?" - -**Tool Integration** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Na here LangChain4j dey powerful. You go use `AiServices` take build AI assistant wey fit call your Java methods. Just annotate methods with `@Tool("description")`, LangChain4j go handle the rest - AI go decide automatically when to use tool depending on wetin user talk. Dis na function calling, one important technique to build AI wey fit do actions, no only answer questions. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) and ask: -> - "How di @Tool annotation dey work and wetin LangChain4j dey do wit am for background?" -> - "Fit AI call many tools one after di other to solve complex problems?" -> - "Wetin happen if tool throw exception - how I fit handle errors?" -> - "How I go integrate real API instead of dis calculator example?" - -**Document Q&A (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Here you go see RAG (retrieval-augmented generation) using LangChain4j "Easy RAG". Documents go load, e go split and embed automatically inside memory store, then content retriever go supply relevant parts to AI when you ask. AI go answer based on your documents no be general knowledge. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) and ask: -> - "How RAG dey prevent AI hallucinations compared to using model training data?" -> - "Wetin be di difference between this easy way and custom RAG pipeline?" -> - "How I go scale am to handle many documents or bigger knowledge bases?" - -**Responsible AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Build AI safety wit defense inside depth. Dis demo dey show two layers of protection wey dey work together: - -**Part 1: LangChain4j Input Guardrails** - Block dangerous prompts before dem reach LLM. Create custom guardrails to check for forbidden keywords or patterns. Dem dey run inside your code, so dem quick and free. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Part 2: Provider Safety Filters** - GitHub Models get filters wey fit catch wetin your guardrails fit miss. You go see hard blocks (HTTP 400 errors) for serious violations and soft refusals where AI go politely refuse. - -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) and ask: -> - "Wetin be InputGuardrail and how I fit create my own?" -> - "Wetin be difference between hard block and soft refusal?" -> - "Why I suppose use both guardrails and provider filters together?" - -## Next Steps - -**Next Module:** [01-introduction - Getting Started with LangChain4j](../01-introduction/README.md) - ---- - -**Navigation:** [← Back to Main](../README.md) | [Next: Module 01 - Introduction →](../01-introduction/README.md) - ---- - -## Troubleshooting - -### First-Time Maven Build - -**Issue**: First time `mvn clean compile` or `mvn package` go take long (10-15 minutes) - -**Cause**: Maven need to download all project dependencies (Spring Boot, LangChain4j libraries, Azure SDKs, etc.) for first build. - -**Solution**: Dis normal. After first time, builds go fast because dependencies go dey cached locally. Download time depend on your network speed. - -### PowerShell Maven Command Syntax - -**Issue**: Maven commands dey fail wit error `Unknown lifecycle phase ".mainClass=..."` -**Cause**: PowerShell de interpret `=` as variable assignment operator, wey go break Maven property syntax - -**Solution**: Make you use stop-parsing operator `--%` before Maven command: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -The `--%` operator dey tell PowerShell make e pass all remaining arguments for Maven without any interpretation. - -### Windows PowerShell Emoji Display - -**Issue**: AI response go show rubbish characters (like `????` or `â??`) instead of emojis for PowerShell - -**Cause**: PowerShell default encoding no dey support UTF-8 emojis - -**Solution**: Run dis command before you run Java applications: -```cmd -chcp 65001 -``` - -Dis one go force UTF-8 encoding to dey for terminal. Another option na to use Windows Terminal wey get better Unicode support. - -### Debugging API Calls - -**Issue**: Authentication errors, rate limits, or unexpected responses from the AI model - -**Solution**: Di examples get `.logRequests(true)` and `.logResponses(true)` wey dey show API calls for console. Dis one go help troubleshoot authentication errors, rate limits, or unexpected responses. Remove dis flags when you move to production to reduce log noise. - ---- - - -**Disclaimer**: -Dis dokument don translate wit AI translation service wey dey call [Co-op Translator](https://github.com/Azure/co-op-translator). Even though we dey try make am correct, abeg sabi say automated translation fit get mistakes or errors. Di original dokument wey dem write for im own language na im get final trust. If na important info, make you try use professional human translation. We no go carry any blame if person no understand or if dem use dis translation wrongly. - \ No newline at end of file diff --git a/translations/pcm/01-introduction/README.md b/translations/pcm/01-introduction/README.md index c248b1b45..e4d01993f 100644 --- a/translations/pcm/01-introduction/README.md +++ b/translations/pcm/01-introduction/README.md @@ -1,85 +1,85 @@ -# Module 01: Getting Started with LangChain4j +# Module 01: Getting Started wit LangChain4j ## Table of Contents -- [Video Walkthrough](../../../01-introduction) -- [What You'll Learn](../../../01-introduction) -- [Prerequisites](../../../01-introduction) -- [Understanding the Core Problem](../../../01-introduction) -- [Understanding Tokens](../../../01-introduction) -- [How Memory Works](../../../01-introduction) -- [How This Uses LangChain4j](../../../01-introduction) -- [Deploy Azure OpenAI Infrastructure](../../../01-introduction) -- [Run the Application Locally](../../../01-introduction) -- [Using the Application](../../../01-introduction) - - [Stateless Chat (Left Panel)](../../../01-introduction) - - [Stateful Chat (Right Panel)](../../../01-introduction) -- [Next Steps](../../../01-introduction) +- [Video Walkthrough](#video-walkthrough) +- [Wetìn You Go Learn](#wetìn-you-go-learn) +- [Wetìn You Go Need](#wetìn-you-go-need) +- [Undastand Di Main Wahala](#undastand-di-main-wahala) +- [Undastand Tokens](#undastand-tokens) +- [How Memory Dey Work](#how-memory-dey-work) +- [How Dis One Take Use LangChain4j](#how-dis-one-take-use-langchain4j) +- [Deploy Azure OpenAI Infrastructure](#deploy-azure-openai-infrastructure) +- [Run Di Application for Your Local](#run-di-application-for-your-local) +- [How to Use Di Application](#how-to-use-di-application) + - [Stateless Chat (Left Panel)](#stateless-chat-left-panel) + - [Stateful Chat (Right Panel)](#stateful-chat-right-panel) +- [Wetìn to Do Next](#wetìn-to-do-next) ## Video Walkthrough -Watch dis live session wey dey explain how to start to use dis module: +Watch dis live session wey explain how you go start wit dis module: Getting Started with LangChain4j - Live Session -## What You'll Learn +## Wetìn You Go Learn -Inside di quick start, you use GitHub Models to send prompts, call tools, build one RAG pipeline, and test guardrails. Dem demos show wetin fit be done — now we go switch to Azure OpenAI and GPT-5.2 and start to build production-style applications. Dis module focus on conversational AI wey dey remember context and keep state — di concepts wey dem quick start demos use for back ground but no explain. +Dis na your start point wit LangChain4j and Azure OpenAI. We go start wit di basics and begin build production-style applications. Dis module na for conversational AI wey dey remember context and dey maintain state — di basic tins wey every later module go build on top. -We go use Azure OpenAI GPT-5.2 for dis guide because e strong for reasoning and make di behavior of different patterns clear. When you add memory, you go clearly sabi di difference. Dis one go make am easy to understand wetin each component dey bring come your application. +We go use Azure OpenAI GPT-5.2 throughout dis guide because im strong reasoning fit make di different patterns clear well well. When you add memory, you go clearly sabi di difference. Dis one go make am easy to understand wetin each part dey bring to your application. You go build one application wey go show both patterns: -**Stateless Chat** - Each request na separate one. Di model no get memory of previous messages. Na di pattern wey you use for quick start. +**Stateless Chat** - Each request na separate tin. Di model no get memory of wetin you talk before. Na di simplest starting point be dis. -**Stateful Conversation** - Each request get conversation history. Di model dey keep context through many turns. Na wetin production applications need. +**Stateful Conversation** - Each request get conversation history join. Di model dey maintain context across plenty turns. Na wetin production applications need. -## Prerequisites +## Wetìn You Go Need - Azure subscription wey get Azure OpenAI access -- Java 21, Maven 3.9+ +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Note:** Java, Maven, Azure CLI and Azure Developer CLI (azd) don already install for di devcontainer wey dem provide. +> **Note:** Java, Maven, Azure CLI and Azure Developer CLI (azd) don already dey inside di devcontainer wey dem provide. -> **Note:** Dis module dey use GPT-5.2 for Azure OpenAI. The deployment dey configured automatically by `azd up` - no change di model name inside di code. +> **Note:** Dis module dey use GPT-5.2 for Azure OpenAI. Di deployment dey automatic with `azd up` - no change di model name for di code. -## Understanding the Core Problem +## Undastand Di Main Wahala -Language models no get state. Each API call na separate one. If you talk “My name is John” then ask “What's my name?”, di model no go know say you don already introduce yourself. E dey treat all requests like say na di first conversation wey you dey do. +Language models no get memory. Each API call na separate tin. If you send "My name is John" and then ask "What's my name?", di model no go sabi say you don yarn yourself before. E go treat every request like na di first conversation wey you don ever get. -E good for simple Q&A but e no work for real applications. Customer service bots need to remember wetin you talk. Personal assistants need context. Any multi-turn conversation need memory. +Dis one good for simple Q&A but e no work for real applications. Customer service bots need to remember wetin you talk before. Personal assistants need context. Any multi-turn conversation need memory. -Di picture below show di two ways — for left side, na stateless call wey forget your name; for right side, na stateful call wey use ChatMemory wey remember am. +Di diagram wey follow below compare di two different ways — for left na stateless call wey dey forget your name; for right na stateful call wey get ChatMemory wey dey remember am. Stateless vs Stateful Conversations -*Di difference between stateless (independent calls) and stateful (context-aware) conversations* +*Di difference between stateless (calls wey independent) and stateful (calls wey sabi context) conversations* -## Understanding Tokens +## Undastand Tokens -Before you enter conversation matter, e good to sabi tokens - na di basic text units wey language models dey process: +Before you begin talk for conversation, e important to sabi tokens - di basic units of text wey language models dey use: Token Explanation -*Example how text dey break into tokens - "I love AI!" become 4 separate processing units* +*Example how text dey break for tokens - "I love AI!" go be 4 separate processing units* -Tokens na how AI models dey measure and process text. Words, punctuation, and space fit be tokens. Your model get limit on how many tokens e fit process at once (400,000 for GPT-5.2, with up to 272,000 input tokens and 128,000 output tokens). If you sabi tokens, e go help you manage conversation length and cost. +Tokens na how AI models take measure and process text. Words, punctuation, and even spaces fit be tokens. Your model get limit on how many tokens e fit process for one time (400,000 for GPT-5.2, wit up to 272,000 input tokens and 128,000 output tokens). To sabi tokens go help you manage conversation length and cost. -## How Memory Works +## How Memory Dey Work -Chat memory solve di stateless wahala by keeping conversation history. Before dem send your request to di model, di framework go first put di relevant previous messages front front. When you ask "What's my name?", di system go actually send all di conversation history. This one make di model see say you already talk "My name is John." +Chat memory na di solution for di stateless wahala by maintaining conversation history. Before you send your request go di model, di framework go add previous messages wey dey relevant before di new one. When you ask "What's my name?", di system go send di whole conversation history, so di model go fit see say you don talk "My name is John" before. -LangChain4j get memory implementations wey dey handle dis one automatically. You go choose how many messages to keep and di framework go arrange di context window. Di picture below show how MessageWindowChatMemory dey keep sliding window of recent messages. +LangChain4j dey provide memory implementations wey dey do dis one automatically. You go choose how many messages to keep and di framework go manage context window. Di diagram wey below show how MessageWindowChatMemory dey maintain sliding window of recent messages. Memory Window Concept -*MessageWindowChatMemory dey keep sliding window of recent messages, e dey automatically drop old ones* +*MessageWindowChatMemory dey keep sliding window of recent messages, dey drop old ones automatically* -## How This Uses LangChain4j +## How Dis One Take Use LangChain4j -Dis module dey build on top quick start by adding Spring Boot and conversation memory. Na so di pieces dey connect: +Dis module join Spring Boot and add conversation memory. See how di parts dem link together: **Dependencies** - Add two LangChain4j libraries: @@ -94,7 +94,7 @@ Dis module dey build on top quick start by adding Spring Boot and conversation m ``` -**Chat Model** - Configure Azure OpenAI as one Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chat Model** - Configure Azure OpenAI as Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -The builder dey read credentials from environment variables wey `azd up` set. If you set `baseUrl` to your Azure endpoint, e make OpenAI client fit work with Azure OpenAI. +Di builder go read credentials from environment variables wey `azd up` set. If you set `baseUrl` to your Azure endpoint, OpenAI client go work with Azure OpenAI. -**Conversation Memory** - Track chat history with MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Conversation Memory** - Track chat history wit MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,51 +124,51 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Create memory with `withMaxMessages(10)` to keep last 10 messages. Add user and AI messages with typed wrappers: `UserMessage.from(text)` and `AiMessage.from(text)`. Get history `memory.messages()` then send am go di model. Di service store separate memory per conversation ID so multiple users fit chat at the same time. +Create memory wit `withMaxMessages(10)` to keep last 10 messages. Add user and AI messages wit typed wrappers: `UserMessage.from(text)` and `AiMessage.from(text)`. To get history, use `memory.messages()` and send am to di model. Di service dey store separate memory for each conversation ID, so multiple users fit dey chat at di same time. -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) and ask: -> - "How MessageWindowChatMemory dey decide which messages to drop when window full?" -> - "Fit I do custom memory storage with database instead of in-memory?" -> - "How I fit add summarization to compress old conversation history?" +> **🤖 Try wit [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) and ask: +> - "How MessageWindowChatMemory dey decide which messages to drop when window ful?" +> - "Fit I implement custom memory storage using database instead of memory?" +> - "How I go add summarization to compress old conversation history?" -Di stateless chat endpoint no use memory - just `chatModel.chat(prompt)` like for quick start. Di stateful endpoint dey add messages go memory, gather history and join di context for each request. Same model config, different patterns. +Di stateless chat endpoint no use memory at all - na just `chatModel.chat(prompt)` like quick start. Di stateful endpoint add messages to memory, retrieve history, and join am with each request. Same model configuration, different patterns. ## Deploy Azure OpenAI Infrastructure **Bash:** ```bash cd 01-introduction -azd up # Choose subscription and place (eastus2 na di best) +azd up # Select subscription and location (eastus2 dem recommend) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Choose subscription and where you dey (eastus2 na beta) +azd up # Chọs subscription and location (eastus2 dey recommended) ``` -> **Note:** If you see timeout error (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), no wahala, just run `azd up` again. Azure resources fit still dey provision in background, so retrying go help deployment finish when resources finish. +> **Note:** If you see timeout error (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), jus run `azd up` again. Azure resources fit still dey provision inside background, to try again go allow di deployment finish when resource dem reach terminal state. This one go: -1. Deploy Azure OpenAI resource with GPT-5.2 and text-embedding-3-small models -2. Automatically create `.env` file for project root with credentials -3. Set all necessary environment variables +1. Deploy Azure OpenAI resource wit GPT-5.2 and text-embedding-3-small models +2. Automatically generate `.env` file for project root wit credentials +3. Setup all required environment variables -**If deployment get wahala?** Check [Infrastructure README](infra/README.md) for troubleshooting tips including subdomain name conflicts, manual Azure Portal deployment steps, and model config guide. +**If deployment get problem?** Check [Infrastructure README](infra/README.md) for troubleshooting like subdomain name wahala, manual Azure Portal deployment steps, and model configuration guide. -**Confirm deployment complete:** +**Make sure deployment succeed:** **Bash:** ```bash -cat ../.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, etc. +cat ../.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, anoda tin dem. ``` **PowerShell:** ```powershell -Get-Content ..\.env # Suppose show AZURE_OPENAI_ENDPOINT, API_KEY, etc. +Get-Content ..\.env # E for show AZURE_OPENAI_ENDPOINT, API_KEY, etc. ``` -> **Note:** `azd up` command dey automatically generate `.env` file. If you want update am later, fit manually edit `.env` or regenerate by running: +> **Note:** `azd up` command dey automatically generate `.env` file. If you want update am later, you fit either edit `.env` file manual or regenerate am by running: > > **Bash:** > ```bash @@ -182,47 +182,47 @@ Get-Content ..\.env # Suppose show AZURE_OPENAI_ENDPOINT, API_KEY, etc. > .\.azd-env.ps1 > ``` -## Run the Application Locally +## Run Di Application for Your Local -**Confirm deployment:** +**Make sure deployment ready:** -Make sure `.env` file dey root folder wit Azure credentials. Run this command inside module folder (`01-introduction/`): +Ensure `.env` file dey root directory wit Azure credentials. Run dis from module directory (`01-introduction/`): **Bash:** ```bash -cat ../.env # Suppoz go show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Shiud show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Start di apps:** +**Start di applications:** -**Option 1: Use Spring Boot Dashboard (Best for VS Code users)** +**Option 1: Using Spring Boot Dashboard (Better for VS Code users)** -Di devcontainer get Spring Boot Dashboard extension, wey get GUI interface to control all Spring Boot apps. You fit find am for di Activity Bar for left side of VS Code (look for Spring Boot icon). +Di dev container get Spring Boot Dashboard extension, wey go give you visual interface to manage all Spring Boot applications. You fit find am for Activity Bar wey dey left side of VS Code (look for Spring Boot icon). -From di Spring Boot Dashboard you fit: -- See all Spring Boot apps for di workspace -- Start/stop apps with one click -- View app logs as e dey happen -- Check app status +From Spring Boot Dashboard, you fit: +- See all Spring Boot apps for workspace +- Start/stop applications wit one click +- View application logs live +- Monitor application status -Just click di play button beside "introduction" to start dis module, or start all modules at once. +Just click play button next to "introduction" to start dis module, or start all modules together. Spring Boot Dashboard -*Spring Boot Dashboard inside VS Code — start, stop, and monitor all modules for one place* +*Spring Boot Dashboard for VS Code — start, stop, and monitor all modules for one place* -**Option 2: Use shell scripts** +**Option 2: Using shell scripts** -Start all web apps (modules 01-04): +Start all web applications (modules 01-04): **Bash:** ```bash -cd .. # From root directory +cd .. # From di root directory ./start-all.sh ``` @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Both scripts go load environment variables from root `.env` file and go build the JARs if dem no dey. +Both scripts go automatically load environment variables from root `.env` file, and go build JARs if dem never dey. -> **Note:** If you want build all modules manually before starting: +> **Note:** If you prefer build all modules yourself before you start: > > **Bash:** > ```bash @@ -270,53 +270,53 @@ Open http://localhost:8080 for your browser. ```bash ./stop.sh # Dis module only # Or -cd .. && ./stop-all.sh # All di modules +cd .. && ./stop-all.sh # All modules ``` **PowerShell:** ```powershell -.\stop.ps1 # Dis module only +.\stop.ps1 # Dis moduul only # Or -cd ..; .\stop-all.ps1 # All di modules +cd ..; .\stop-all.ps1 # All moduuls ``` -## Using the Application +## How to Use Di Application -Di application get web interface with two chat types side-by-side. +Di application get web interface wit two chat implementations side by side. Application Home Screen -*Dashboard wey show Simple Chat (stateless) and Conversational Chat (stateful) options* +*Dashboard wey show both Simple Chat (stateless) and Conversational Chat (stateful) options* ### Stateless Chat (Left Panel) -Try am first. Tell "My name is John" then quickly ask "What's my name?" Di model no go remember because each message na separate one. Dis one show di core problem with basic language model integration - no conversation context. +Try dis one first. Ask "My name is John" then immediately ask "What's my name?" Di model no go remember because each message na different tin. Dis one show di core wahala with basic language model join - no conversation context. Stateless Chat Demo -*AI no remember your name from your last message* +*AI no remember your name from previous message* ### Stateful Chat (Right Panel) -Now try di same thing here. Tell "My name is John" then ask "What's my name?" This time e remember. Di difference na MessageWindowChatMemory - e dey keep conversation history and add am with every request. Na so production conversational AI dey work. +Now try same thing here. Ask "My name is John" then "What's my name?" This time e remember. Di difference na MessageWindowChatMemory - e maintain conversation history and add am with each request. Na so production conversational AI dey work. Stateful Chat Demo -*AI remember your name from earlier conversation* +*AI dey remember your name from earlier conversation* -Both sides use di same GPT-5.2 model. Di only difference na memory. Dis one make clear how memory fit improve your app and why e important for real use. +Both panels dey use same GPT-5.2 model. Di only difference na memory. Dis one clear how memory dey help your application and why e important for real use case dem. -## Next Steps +## Wetìn to Do Next -**Next Module:** [02-prompt-engineering - Prompt Engineering with GPT-5.2](../02-prompt-engineering/README.md) +**Next Module:** [02-prompt-engineering - Prompt Engineering wit GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigation:** [← Previous: Module 00 - Quick Start](../00-quick-start/README.md) | [Back to Main](../README.md) | [Next: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigation:** [← Back to Main](../README.md) | [Next: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **Disclaimer**: -Dis document na di one wey AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator) translate. Even though we dey try make e correct, abeg make you sabi say automated translations fit get some errors or mistake. Di original document for dia own language na di main correct source. If na important info, e better make pro human translator do am. We no gree take any blame if person misunderstand or misinterpret tins because of dis translation. +Dis document don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even tho we dey try make am correct, abeg make you know say automated translation fit get errors or mistakes. Di original document for dia own language na im be di correct source. For important info, make person wey sabi human translation do am. We no go responsible for any misunderstanding or wrong understanding wey fit happen because of dis translation. \ No newline at end of file diff --git a/translations/pcm/02-prompt-engineering/README.md b/translations/pcm/02-prompt-engineering/README.md index de81f56b8..0edf3a36f 100644 --- a/translations/pcm/02-prompt-engineering/README.md +++ b/translations/pcm/02-prompt-engineering/README.md @@ -2,84 +2,84 @@ ## Table of Contents -- [Video Walkthrough](../../../02-prompt-engineering) -- [Wetin You Go Learn](../../../02-prompt-engineering) -- [Prerequisites](../../../02-prompt-engineering) -- [Understanding Prompt Engineering](../../../02-prompt-engineering) -- [Prompt Engineering Fundamentals](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Templates](../../../02-prompt-engineering) -- [Advanced Patterns](../../../02-prompt-engineering) -- [Run the Application](../../../02-prompt-engineering) -- [Application Screenshots](../../../02-prompt-engineering) -- [Exploring the Patterns](../../../02-prompt-engineering) - - [Low vs High Eagerness](../../../02-prompt-engineering) - - [Task Execution (Tool Preambles)](../../../02-prompt-engineering) - - [Self-Reflecting Code](../../../02-prompt-engineering) - - [Structured Analysis](../../../02-prompt-engineering) - - [Multi-Turn Chat](../../../02-prompt-engineering) - - [Step-by-Step Reasoning](../../../02-prompt-engineering) - - [Constrained Output](../../../02-prompt-engineering) -- [Wetin You Really Dey Learn](../../../02-prompt-engineering) -- [Next Steps](../../../02-prompt-engineering) +- [Video Walkthrough](#video-walkthrough) +- [Wet tin You Go Learn](#wet-tin-you-go-learn) +- [Prerequisites](#prerequisites) +- [Understanding Prompt Engineering](#understanding-prompt-engineering) +- [Prompt Engineering Fundamentals](#prompt-engineering-fundamentals) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Advanced Patterns](#advanced-patterns) +- [Run the Application](#run-the-application) +- [Application Screenshots](#application-screenshots) +- [Exploring the Patterns](#exploring-the-patterns) + - [Low vs High Eagerness](#low-vs-high-eagerness) + - [Task Execution (Tool Preambles)](#task-execution-tool-preambles) + - [Self-Reflecting Code](#self-reflecting-code) + - [Structured Analysis](#structured-analysis) + - [Multi-Turn Chat](#multi-turn-chat) + - [Step-by-Step Reasoning](#step-by-step-reasoning) + - [Constrained Output](#constrained-output) +- [Wet You Really Dey Learn](#what-youre-really-learning) +- [Next Steps](#next-steps) ## Video Walkthrough -Watch dis live session wey go explain how to start wit dis module: +Watch dis live session wey dey explain how to start dis module: Prompt Engineering with LangChain4j - Live Session -## Wetin You Go Learn +## Wet tin You Go Learn -Dis diagram show overview of the main topics and skills wey you go develop for dis module — from prompt refinement techniques to the step-by-step workflow you go follow. +The diagram wey follow show the main topics and skills wey you go develop for dis module — from how to make prompts better reach the step-by-step workflow wey you go follow. What You'll Learn -For di previous modules, you don explore basic LangChain4j interactions wit GitHub Models and see how memory dey enable conversational AI wit Azure OpenAI. Now we go focus on how you dey ask questions — di prompts themselves — using Azure OpenAI's GPT-5.2. Di way wey you structure your prompts go really affect di quality of di responses you go get. We go start wit review of di fundamental prompting techniques, then move go eight advanced patterns wey go take full advantage of GPT-5.2's capabilities. +For the last module, you see how memory dey enable conversational AI wit Azure OpenAI. Now we go focus on how you dey ask questions — di prompts themselves — using Azure OpenAI GPT-5.2. How you take arrange your prompts get serious effect on the kind answer you go get. We go start wit di basic prompt techniques, then go enter eight advanced patterns wey make full use of GPT-5.2 features. -We go use GPT-5.2 because e bring reasoning control - you fit tell di model how much thinking to do before e answer. Dis one make different prompting strategies clear and go help you sabi when to use each approach. We go also benefit from Azure's fewer rate limits for GPT-5.2 compared to GitHub Models. +We go use GPT-5.2 because e get reasoning control - you fit tell di model how much thinking e suppose do before e answer. Dis one dey make different prompt strategies clear and e go help you understand when to use which approach. ## Prerequisites -- Complete Module 01 (Azure OpenAI resources don deploy) -- `.env` file for root directory wit Azure credentials (wey `azd up` make for Module 01) +- You go don finish Module 01 (Azure OpenAI resources don deploy) +- `.env` file dey your root folder wit Azure credentials (e dey created by `azd up` for Module 01) -> **Note:** If you never finish Module 01, make you follow deployment instructions there first. +> **Note:** If you never finish Module 01, make you follow deployment instructions inside there first. ## Understanding Prompt Engineering -At dia core, prompt engineering na di difference between vague instructions and precise ones, as di comparison below show. +For inside, prompt engineering na di difference between instructions wey no clear and instructions wey clear well well, as di comparison below dey show. What is Prompt Engineering? -Prompt engineering na to design input text wey go always give you di results wey you want. E no just dey about to ask questions - na to structure requests so di model go understand exactly wetin you want and how e go deliver am. +Prompt engineering na about how you dey design input text wey go always give you di correct answer wey you need. E no be only to ask questions - na how you dey arrange your request make di model understand exactly wetin you want and how e go deliver am. -Think am like how you go dey give instruction to colleague. "Fix the bug" na vague. "Fix the null pointer exception for UserService.java line 45 by adding a null check" na specific instruction. Language models dey work the same way - specificity and structure matter. +Make you think am like you dey give instruction to your padi for work. "Fix the bug" no clear. "Fix the null pointer exception for UserService.java line 45 by adding a null check" clear well. Language models dey work like that too - clear instruction and arrangement dey matter. -Di diagram below show how LangChain4j dey fit inside dis picture — connecting your prompt patterns to di model through SystemMessage and UserMessage building blocks. +Di diagram below show how LangChain4j take fit inside di picture — e dey connect your prompt patterns go di model through SystemMessage and UserMessage building blocks. How LangChain4j Fits -LangChain4j dey provide di infrastructure — model connections, memory, and message types — while prompt patterns na just carefully structured text wey you dey send through dat infrastructure. Di main building blocks na `SystemMessage` (wey dey set di AI's behavior and role) and `UserMessage` (wey carry your actual request). +LangChain4j na di infrastructure — model connections, memory, and message types — but prompt patterns na carefully arranged text wey you dey send through dat infrastructure. Di main building blocks na `SystemMessage` (wey dey set di AI style and role) and `UserMessage` (wey carry your actual request). ## Prompt Engineering Fundamentals -Di five core techniques wey dem show below na di foundation of effective prompt engineering. Each one dey handle different aspect of how you dey talk to language models. +The five core techniques wey dey below na di foundation for any good prompt engineering work. Each one dey handle different part of how you take dey communicate wit language model. Five Prompt Engineering Patterns Overview -Before we enter di advanced patterns for dis module, make we review five foundational prompting techniques. Dem na di building blocks wey every prompt engineer suppose sabi. If you don already work through di [Quick Start module](../00-quick-start/README.md#2-prompt-patterns), you don see dem for action — here na di conceptual framework behind dem. +Before we start di advanced patterns for dis module, make we review five basic prompting techniques. Dem na di building blocks all prompt engineers suppose sabi. ### Zero-Shot Prompting -Di simplest way: give di model direct instruction wit no example. Di model dey rely completely on im training to understand and execute di task. Dis one dey work well for straightforward requests wey di expected behavior clear. +Di simplest way: you just give di model direct instruction without any example. Di model go depend fully on wetin e learn before to understand and do di task. Dis one dey work well for easy requests wey di expected way clear. Zero-Shot Prompting -*Direct instruction wit no examples — di model dey infer di task from di instruction alone* +*Direct instruction wey no get example — di model go understand task from only di instruction* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Response: "Positiv" ``` -**When to use:** Simple classifications, direct questions, translations, or any task wey di model fit handle without extra guidance. +**When to use:** Simple classifications, direct questions, translations, or any task di model fit do without extra guide. ### Few-Shot Prompting -Give examples wey show di pattern wey you want di model to follow. Di model go learn di expected input-output format from your examples and apply am to new inputs. Dis one improve consistency wella for tasks wey di desired format or behavior no obvious. +You give example wey show di pattern wey you want di model follow. Di model go learn di input-output style from your examples and then apply am for new inputs. Dis one dey improve how consistent di model dey when di format or behavior no clear obviously. Few-Shot Prompting -*Learn from examples — di model dey identify di pattern and apply am to new inputs* +*Learning from example — di model go find di pattern and apply am for new inputs* ```java String prompt = """ @@ -116,11 +116,11 @@ String response = model.chat(prompt); ### Chain of Thought -Ask di model to show hin reasoning step-by-step. Instead of jumping direct to answer, di model go break down di problem and work through each part explicitly. Dis one go improve accuracy for math, logic, and multi-step reasoning tasks. +Ask di model make e show how e reason step by step. Instead of just giving one answer quick quick, di model go break di problem down and solve each part clearly. Dis dey increase accuracy for math, logic, and tasks wey get many steps. Chain of Thought Prompting -*Step-by-step reasoning — dey break complex problems into explicit logical steps* +*Step by step reasoning — breaking complex problems into clear logical steps* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Di model dey show: 15 - 8 = 7, afta dat 7 + 12 = 19 apple dem +// Di model dey show: 15 - 8 = 7, den 7 + 12 = 19 apples ``` -**When to use:** Math problems, logic puzzles, debugging, or any task wey showing di reasoning process go improve accuracy and trust. +**When to use:** Math wahala, logic puzzle, debugging, or any task wey showing how you reason go improve accuracy and trust. ### Role-Based Prompting -Set persona or role for di AI before you ask your question. Dis one dey provide context wey go shape di tone, depth, and focus of di response. "Software architect" go give different advice than "junior developer" or "security auditor". +Set persona or role for di AI before you ask your question. Dis dey give context wey go affect how di AI go yan, di level and kind of answer e go give. "Software architect" go give different advice pass "junior developer" or "security auditor". Role-Based Prompting -*Setting context and persona — di same question fit get different response based on di role wey assign* +*Setting context and persona — di same question fit get different answer depending on role wey you set* ```java String prompt = """ @@ -157,11 +157,11 @@ String prompt = """ String response = model.chat(prompt); ``` -**When to use:** Code reviews, tutoring, domain-specific analysis, or when you need responses wey dem tailor to particular expertise level or perspective. +**When to use:** Code reviews, tutoring, domain-specific analysis, or when you want answers wey fit specific expertise level or perspective. ### Prompt Templates -Create reusable prompts wit variable placeholders. Instead of writing new prompt anytime, define template once and fill different values. LangChain4j's `PromptTemplate` class make am easy wit `{{variable}}` syntax. +Make reusable prompts wey get variable placeholders. Instead of you dey write new prompt every time, you go define one template and fill different values. LangChain4j `PromptTemplate` class dey make dis easy wit `{{variable}}` syntax. Prompt Templates @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**When to use:** Repeated queries wit different inputs, batch processing, building reusable AI workflows, or any scenario wey di prompt structure remain the same but di data changes. +**When to use:** Repeated queries wit different inputs, batch processing, building reusable AI workflows, or any time wey di prompt structure remain but di data change. --- -Dis five fundamentals go give you solid toolkit for most prompting tasks. Di rest of dis module go build on dem wit **eight advanced patterns** wey dey leverage GPT-5.2's reasoning control, self-evaluation, and structured output capabilities. +Dis five fundamentals go give you strong toolkit for most prompt tasks. Di rest of dis module go build on dem wit **eight advanced patterns** wey use GPT-5.2 reasoning control, self-evaluation, and structured output features. ## Advanced Patterns -Now we don cover fundamentals, make we move go di eight advanced patterns wey make dis module special. No all problems need di same approach. Some questions need quick answers, others need deep thinking. Some need visible reasoning, others just need results. Each pattern below optimize for different scenario — and GPT-5.2's reasoning control go make di difference dem even clear. +Since fundamentals don done, make we enter di eight advanced patterns wey make dis module special. Not all problems need same approach. Some questions need quick answer, others need deep thinking. Some need reasoning wey you fit see, others just want result. Each pattern below dey optimized for different thing — and GPT-5.2 reasoning control dey make di difference clear well well. Eight Prompting Patterns *Overview of di eight prompt engineering patterns and their use cases* -GPT-5.2 add one extra dimension to dis patterns: *reasoning control*. Di slider below show how you fit adjust di model's thinking effort — from quick, direct answers to deep, thorough analysis. +GPT-5.2 add one more dimension to dis patterns: *reasoning control*. Di slider below dey show how you fit adjust di model thinking effort — from quick direct answers to deep thorough analysis. Reasoning Control with GPT-5.2 -*GPT-5.2's reasoning control let you specify how much thinking di model suppose do — from fast direct answers to deep exploration* +*GPT-5.2 reasoning control let you choose how much thinking di model go do — from fast direct answers to deep exploration* -**Low Eagerness (Quick & Focused)** - For simple questions where you want fast, direct answers. Di model go do minimal reasoning - max 2 steps. Use dis for calculations, lookups, or straightforward questions. +**Low Eagerness (Quick & Focused)** - For simple questions wey you want quick, direct answers. Di model no go reason too much - maximum 2 steps. Use am for calculation, lookups, or simple questions. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Explore wit GitHub Copilot:** Open [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) and ask: -> - "Wetin be di difference between low eagerness and high eagerness prompting patterns?" -> - "How di XML tags for prompts dey help structure di AI's response?" +> - "Wet different dey between low eagerness and high eagerness prompting patterns?" +> - "How di XML tags for prompts dey help arrange AI response?" > - "When I go use self-reflection patterns vs direct instruction?" -**High Eagerness (Deep & Thorough)** - For complex problems where you want full analysis. Di model go explore well and show detailed reasoning. Use dis one for system design, architecture decisions, or complex research. +**High Eagerness (Deep & Thorough)** - For complex problems wey you want full analysis. Di model go reason well and show detailed steps. Use am for system design, architecture decisions, or heavy research. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Task Execution (Step-by-Step Progress)** - For multi-step workflows. Di model go provide upfront plan, narrate each step as e dey work, then give summary. Use dis for migrations, implementations, or any multi-step process. +**Task Execution (Step-by-Step Progress)** - For workflows wey get many steps. Di model go give plan upfront, tell you each step as e dey do, then give summary. Use am for migrations, implementations, or any multi-step process. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Chain-of-Thought prompting dey directly ask di model to show hin reasoning process, to improve accuracy for complex tasks. Di step-by-step breakdown dey help both humans and AI understand di logic. +Chain-of-Thought prompting dey explicitly ask di model to show how e reason, e dey improve accuracy for complex tasks. Di step by step breakdown dey help both human and AI understand di logic. > **🤖 Try wit [GitHub Copilot](https://github.com/features/copilot) Chat:** Ask about dis pattern: -> - "How I go adapt di task execution pattern for long-running operations?" -> - "Wetin be best practices for structuring tool preambles for production applications?" -> - "How I fit capture and display intermediate progress updates for UI?" +> - "How I go change di task execution pattern for long-running operations?" +> - "Wetin be best practices for arranging tool preambles for production apps?" +> - "How I fit capture and show in-between progress updates for UI?" -Di diagram below show dis Plan → Execute → Summarize workflow. +Di diagram below dey show dis Plan → Execute → Summarize workflow. Task Execution Pattern *Plan → Execute → Summarize workflow for multi-step tasks* -**Self-Reflecting Code** - For generating production-quality code. Di model dey generate code following pro production standards wit proper error handling. Use dis when you dey build new features or services. +**Self-Reflecting Code** - For generating code wey production quality. Di model go generate code following production standards wit proper error handling. Use am when you wan build new features or services. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Di diagram below show dis iterative improvement loop — generate, evaluate, identify weaknesses, and refine till di code reach production standards. +Di diagram below show dis iterative improvement loop — generate, evaluate, find wahala, and improve until code reach production standard. Self-Reflection Cycle -*Iterative improvement loop - generate, evaluate, identify issues, improve, repeat* +*Iterative improvement loop - generate, evaluate, find problems, improve, repeat* -**Structured Analysis** - For consistent evaluation. Di model dey review code using fixed framework (correctness, practices, performance, security, maintainability). Use dis one for code reviews or quality assessments. +**Structured Analysis** - For consistent evaluation. Di model go review code using fixed framework (correctness, practices, performance, security, maintainability). Use am for code review or quality check. ```java String prompt = """ @@ -355,17 +355,17 @@ String response = chatModel.chat(prompt); ``` > **🤖 Try wit [GitHub Copilot](https://github.com/features/copilot) Chat:** Ask about structured analysis: -> - "How I fit customize di analysis framework for different types of code reviews?" -> - "Wetin be di best way to parse and act on structured output programmatically?" -> - "How I fit ensure consistent severity levels across different review sessions?" +> - "How I fit customize di analysis framework for different code reviews?" +> - "Wetin be best way to parse and handle structured output inside program?" +> - "How I fit maintain consistency for severity levels across different review sessions?" -Di diagram below show how dis structured framework dey organize code review into consistent categories wit severity levels. +Di diagram below show how dis structured framework fit organize code review into steady categories wit severity levels. Structured Analysis Pattern -*Framework for consistent code reviews wit severity levels* +*Framework for steady code reviews wit severity levels* -**Multi-Turn Chat** - For conversations wey need context. Di model dey remember previous messages and dey build on dem. Use dis for interactive help sessions or complex Q&A. +**Multi-Turn Chat** - For conversation wey need context. Di model dey remember previous messages and build on top. Use am for interactive help sessions or complex Q&A. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Di diagram below dey show how conversation context dey accumulate as turns dey increase and how e relate to di model's token limit. +Di diagram below dey show how conversation context dey build up every turn and how e take relate to di model token limit. Context Memory -*How conversation context dey accumulate over multiple turns till e reach di token limit* -**Step-by-Step Reasoning** - For problems wey need visible logic. Di model dey show clear reasoning for every step. Use dis one for math problems, logic puzzles, or anytime you want understand how di thinking process dey go. +*How conversation context dey increase every turn till e reach token limit* + +**Step-by-Step Reasoning** - For problems wey need visible logic. Di model go show clear thinking for each step. Use am for math problems, logic puzzles, or when you want understand di thinking method. ```java String prompt = """ @@ -401,10 +402,9 @@ String response = chatModel.chat(prompt); Di diagram below dey show how di model dey break problems into clear, numbered logical steps. Step-by-Step Pattern - *Breaking down problems into explicit logical steps* -**Constrained Output** - For responses wey get specific format requirements. Di model go follow format and length rules strictly. Use dis one for summaries or anytime you need precise output structure. +**Constrained Output** - For responses wey get specific format requirements. Di model go strictly follow format and length rules. Use dis one for summaries or wen you need correct output structure. ```java String prompt = """ @@ -419,8 +419,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -Di diagram wey follow dey show how constraints dey guide di model to produce output wey strictly follow your format and length requirements. + +Di diagram wey dey below dey show how constraints dey guide di model to produce output wey strictly follow your format and length requirements. Constrained Output Pattern @@ -430,155 +430,155 @@ Di diagram wey follow dey show how constraints dey guide di model to produce out **Verify deployment:** -Make sure di `.env` file dey inside root directory with Azure credentials (wey dem create for Module 01). Run dis one from di module directory (`02-prompt-engineering/`): +Make sure say `.env` file dey for the root directory with Azure credentials (wey dem create for Module 01). Run am from the module directory (`02-prompt-engineering/`): -**Bash:** +**Bash:** ```bash -cat ../.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # E for show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Start the application:** -> **Note:** If you don start all applications already using `./start-all.sh` from root directory (like dem talk for Module 01), dis module don dey run for port 8083. You fit skip di start commands below and go straight to http://localhost:8083. +> **Note:** If you don start all applications using `./start-all.sh` from the root directory (as dem talk for Module 01), this module don dey run already for port 8083. You fit skip the start commands wey dey below and waka straight go http://localhost:8083. **Option 1: Using Spring Boot Dashboard (Recommended for VS Code users)** -Di dev container get Spring Boot Dashboard extension wey dey provide visual interface to manage all Spring Boot applications. You fit find am for Activity Bar for left side of VS Code (look for di Spring Boot icon). +Di dev container get the Spring Boot Dashboard extension wey dey provide visual interface to manage all Spring Boot applications. You fit find am for the Activity Bar for the left side of VS Code (look for di Spring Boot icon). -From di Spring Boot Dashboard, you fit: -- See all di Spring Boot applications wey dey for workspace -- Start/stop applications with just one click -- View application logs in real-time -- Monitor application status +From the Spring Boot Dashboard, you fit: +- See all di Spring Boot applications wey dey the workspace +- Start/stop applications with one click +- View application logs for real-time +- Monitor application status -Just click di play button wey dey near "prompt-engineering" to start dis module, or start all modules at once. +Just click di play button wey dey next to "prompt-engineering" to start this module, or start all modules at once. Spring Boot Dashboard -*The Spring Boot Dashboard in VS Code — start, stop, and monitor all modules from one place* +*The Spring Boot Dashboard wey dey VS Code — start, stop, and monitor all modules for one place* **Option 2: Using shell scripts** Start all web applications (modules 01-04): -**Bash:** +**Bash:** ```bash cd .. # From root directory ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell -cd .. # From di root directory +cd .. # From root directory .\start-all.ps1 ``` + +Or start just this module: -Or start just dis module: - -**Bash:** +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` + +Both scripts go automatically load environment variables from the root `.env` file and go build the JARs if dem no dey. -Both scripts go automatically load environment variables from root `.env` file and them go build di JARs if dem no dey. - -> **Note:** If you prefer to build all modules manually before you start: -> -> **Bash:** +> **Note:** If you prefer to build all modules manually before you start: +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> -> **PowerShell:** + +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + Open http://localhost:8083 for your browser. **To stop:** -**Bash:** +**Bash:** ```bash ./stop.sh # Dis module only # Or cd .. && ./stop-all.sh # All modules ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # Dis module only # Or -cd ..; .\stop-all.ps1 # All di modules +cd ..; .\stop-all.ps1 # All modules ``` - + ## Application Screenshots -Here be di main interface of di prompt engineering module, where you fit experiment with all eight patterns side by side. +Here na di main interface of di prompt engineering module, wey you fit experiment with all di eight patterns side by side. Dashboard Home -*Di main dashboard wey dey show all 8 prompt engineering patterns with their characteristics and use cases* +*The main dashboard wey dey show all 8 prompt engineering patterns wit their characteristics and use cases* ## Exploring the Patterns -Di web interface dey let you experiment with different prompting strategies. Every pattern dey solve different problems - try dem to see when each approach go shine. +Di web interface make you try different prompting strategies. Each pattern solve different problems - try dem to see when each one sharp. -> **Note: Streaming vs Non-Streaming** — Every pattern page get two buttons: **🔴 Stream Response (Live)** and one **Non-streaming** option. Streaming dey use Server-Sent Events (SSE) to display tokens for real-time as di model dey generate dem, so you fit see progress immediately. Di non-streaming option go wait for di full response before e show am. For prompts wey go make model do deep reasoning (like High Eagerness, Self-Reflecting Code), di non-streaming call fit take plenty time — sometimes minutes — with no feedback wey dey visible. **Use streaming anytime you dey experiment with complex prompts** so you fit see di model dey work and avoid di impression say di request don time out. -> -> **Note: Browser Requirement** — Di streaming feature dey use Fetch Streams API (`response.body.getReader()`) wey require full browser (Chrome, Edge, Firefox, Safari). E no dey work for VS Code's built-in Simple Browser, because di webview no support di ReadableStream API. If you dey use di Simple Browser, di non-streaming buttons go still work normally — na only di streaming buttons go get wahala. Open `http://localhost:8083` for external browser to get full experience. +> **Note: Streaming vs Non-Streaming** — Every pattern page get two buttons: **🔴 Stream Response (Live)** and one **Non-streaming** option. Streaming na Server-Sent Events (SSE) wey dey show tokens as di model dey generate am, so you go see progress sharp sharp. Non-streaming option go wait till the whole response ready before e show. For prompts wey need deep thinking (like High Eagerness, Self-Reflecting Code), non-streaming call fit take long time — sometimes na minutes — and no feedback go show. **Use streaming when you dey try complex prompts** so you fit see the model work and no go think say the request don time out. +> +> **Note: Browser Requirement** — Di streaming feature dey use Fetch Streams API (`response.body.getReader()`) wey need full browser (Chrome, Edge, Firefox, Safari). E no dey work for VS Code's Simple Browser because e no get support for ReadableStream API. If you dey use Simple Browser, non-streaming buttons still go work normal — na only streaming buttons wey go no work. Open `http://localhost:8083` for external browser to get full experience. ### Low vs High Eagerness -Ask simple question like "Wetn be 15% of 200?" using Low Eagerness. You go get answer sharp and direct. Now ask something complex like "Design caching strategy for high-traffic API" using High Eagerness. Click **🔴 Stream Response (Live)** and watch model dey show detailed reasoning token-by-token. Same model, same question structure - but di prompt dey guide am how much thinking to do. +Ask simple question like "Wetín be 15% of 200?" using Low Eagerness. You go get answer sharp sharp, direct. Now ask something wey complex like "Design caching strategy for high-traffic API" with High Eagerness. Click **🔴 Stream Response (Live)** and watch how model go reason well token by token. Same model, same question format - but di prompt dey tell am how much to think. ### Task Execution (Tool Preambles) -Multi-step workflows need upfront planning and progress narration. Di model dey outline wetn e go do, narrate every step, then summarize results. +Multi-step workflows better if you plan before and yarn progress step by step. Di model go talk wetin e go do, yarn each step, then summarize results. ### Self-Reflecting Code -Try "Create an email validation service". Instead of just generating code and stop, di model go generate, check am against quality criteria, find weaknesses, and improve. You go see am dey try till di code meet production standards. +Try "Create email validation service". Instead of just write code then stop, di model go generate code, check am based on quality criteria, find weak points, then improve. You go see am dey do iteration till code meet production standard. ### Structured Analysis -Code reviews need constant evaluation frameworks. Di model go analyze code using fixed categories (correctness, practices, performance, security) with severity levels. +Code review need consistent framework for evaluation. Di model dey use fixed categories (correctness, practices, performance, security) with severity levels to analyze code. ### Multi-Turn Chat -Ask "Wetn be Spring Boot?" then follow immediately with "Show me an example". Di model go remember your first question and give you Spring Boot example specially. Without memory, dat second question go too vague. +Ask "Wetín be Spring Boot?" then quickly follow up wit "Show me example". Di model go remember your first question and give you Spring Boot example specially. Without memory, the second question go too vague. ### Step-by-Step Reasoning -Pick math problem try am with Step-by-Step Reasoning and Low Eagerness together. Low eagerness go just give answer quick but no details. Step-by-step go show every calculation and decision. +Pick math problem and try am with Step-by-Step Reasoning and Low Eagerness. Low eagerness just give you answer fast but e no clear. Step-by-step go show you every calculation and decision. ### Constrained Output -If you need specific formats or word count, dis pattern dey enforce strict rules. Try generate summary with exactly 100 words for bullet points format. +When you need specific formats or word counts, this pattern go enforce strict adherence. Try generate summary with exactly 100 words for bullet point format. -## Wetn You Really Dey Learn +## What You're Really Learning **Reasoning Effort Changes Everything** -GPT-5.2 allow you control computational effort through your prompts. Low effort mean fast response with small exploration. High effort mean model go spend time think well. You dey learn how to match effort to task complexity - no waste time on simple questions, but no rush complex decisions too. +GPT-5.2 make you control how much effort model go put through your prompts. Low effort mean fast responses with little exploration. High effort mean model go take time to think deep. You dey learn how to match effort to how hard the task be - no waste time on simple questions, and no rush complex decisions too. **Structure Guides Behavior** -You see di XML tags for di prompts? Dem no be decoration. Models dey follow structured instructions more steady pass freeform text. When you need multi-step processes or complex logic, structure dey help model track where e dey and wetn come next. Di diagram below break down well-structured prompt, showing how tags like ``, ``, ``, ``, and `` dey organize your instructions into clear sections. +You see di XML tags for the prompts? No be decoration. Models dey follow structured instructions better than freeform text. When you need multi-step processes or complex logic, structure dey help the model know where e dey and wetin next. Di diagram below breakdown well-structured prompt, showing how tags like ``, ``, ``, ``, and `` dey organize your instructions into clear sections. Prompt Structure @@ -586,11 +586,11 @@ You see di XML tags for di prompts? Dem no be decoration. Models dey follow stru **Quality Through Self-Evaluation** -Di self-reflecting patterns dey work by making quality criteria explicit. Instead of hoping say di model "go do am right", you go tell am exactly wetn "right" mean: correct logic, error handling, performance, security. Di model fit evaluate im own output and improve. Dis one dey turn code generation from lottery into process. +Self-reflecting patterns dey work by making quality criteria explicit. Instead of hope say model go "do am right", you talk exactly what "right" mean: correct logic, error handling, performance, security. Model fit evaluate own output then improve. E turn code generation to process no be lottery. **Context Is Finite** -Multi-turn conversation dey work by including message history with every request. But e get limit - every model get max token count. As conversation dey grow, you need strategy to keep relevant context without reach dat limit. Dis module go show you how memory work; later you go learn when to summarize, when to forget, and when to retrieve. +Multi-turn conversations work by including message history for each request. But limit dey - every model get max token count. As conversation grow, you need strategies to keep relevant context without pass that limit. This module show you how memory works; later you go learn when to summarize, when to forget, and when to retrieve. ## Next Steps @@ -604,5 +604,5 @@ Multi-turn conversation dey work by including message history with every request **Disclaimer**: -Dis document don translate by AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even though we try make am correct, abeg sabi say automated translations fit get some mistakes or wrong parts. Di original document for dia correct language na di main thing wey you suppose trust. For important tori, e better make professional human translation do am. We no go take responsibility if person misunderstand or misinterpret anything wey come from dis translation. +Dis document don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even tho we dey try make am correct, abeg make you know say automated translation fit get errors or mistakes. Di original document for dia own language na im be di correct source. For important info, make person wey sabi human translation do am. We no go responsible for any misunderstanding or wrong understanding wey fit happen because of dis translation. \ No newline at end of file diff --git a/translations/pcm/03-rag/README.md b/translations/pcm/03-rag/README.md index 3de423ec7..8b547bd80 100644 --- a/translations/pcm/03-rag/README.md +++ b/translations/pcm/03-rag/README.md @@ -2,143 +2,142 @@ ## Table of Contents -- [Video Walkthrough](../../../03-rag) -- [Wetin You Go Learn](../../../03-rag) -- [Wetin You Must Know Before](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Dis Tutorial Dey Use?](../../../03-rag) -- [How E Dey Work](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matter](../../../03-rag) -- [Next Steps](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [Wet In You Go Learn](#wet-in-you-go-learn) +- [Wet You Must Sabi Before](#prerequisites) +- [How You Go Take Understand RAG](#how-you-go-take-understand-rag) + - [Which Kain RAG Dis Tutorial Dey Use?](#which-kain-rag-dis-tutorial-dey-use) +- [How E Dey Work](#how-e-dey-work) + - [How You Go Take Process Document](#how-you-go-take-process-document) + - [How You Go Take Do Embeddings](#how-you-go-take-do-embeddings) + - [Semantic Search](#semantic-search) + - [How You Go Take Generate Answer](#answer-generation) +- [How To Run The Application](#run-the-application) +- [How You Go Take Use The Application](#how-to-use-di-application) + - [How You Go Take Upload Document](#upload-document) + - [How You Go Take Ask Questions](#ask-questions) + - [How You Go Take Check Source References](#check-source-references) + - [How You Go Take Experiment With Questions](#experiment-wit-questions) +- [Important Concepts](#key-concepts) + - [Chunking Strategy](#chunking-strategy) + - [Similarity Scores](#similarity-scores) + - [In-Memory Storage](#in-memory-storage) + - [How You Go Take Manage Context Window](#context-window-management) +- [When RAG Get Importance](#when-rag-matters) +- [Next Steps](#next-steps) ## Video Walkthrough -Watch dis live session wey dey explain how to start with dis module: +Watch dis live session wey explain how to start dis module: RAG with LangChain4j - Live Session -## Wetin You Go Learn +## Wet In You Go Learn -For the previous modules, you don learn how to dey talk with AI and how to arrange your prompts well well. But one basic wahala dey: language models only sabi wetin dem learn during training. Dem no fit answer questions about your company policy, your project documentation, or any info wey dem never train on. +For the modules we done before, you don learn how to hold talk with AI and arrange your prompts well well. But one thing dey limit am: language models only sabi wetin dem learn during training. Dem no fit answer questions about your company policies, your project document, or any info wey dem no train with. -RAG (Retrieval-Augmented Generation) na solution to dis problem. Instead of trying to teach the model your info (wey dey expensive and no too practical), you dey give am the power to search your documents. When person ask question, system go find relevant info, then put am for prompt. The model go then answer based on that retrieved context. +RAG (Retrieval-Augmented Generation) solve dis palava. Instead make you dey try teach the model your info (wey dey expensive and e no easy), you go give am power to search for your documents. When person ask question, the system go find relevant info come put am for the prompt. Then the model go answer base on that context wey e find. -Think am like dis: RAG na like you dey give the model one reference library. When you ask question, the system: +Think am like say RAG dey give the model one reference library. When you ask question, the system: -1. **User Query** - You ask question -2. **Embedding** - E change your question to vector -3. **Vector Search** - E find similar document chunks -4. **Context Assembly** - E add correct chunks to the prompt -5. **Response** - LLM go generate answer based on the context +1. **User Query** - You ask question +2. **Embedding** - E con convert your question to vector +3. **Vector Search** - E find document chunks wey similar +4. **Context Assembly** - E add relevant chunks join the prompt +5. **Response** - LLM go generate answer base on the context -Dis one dey ground the model response for your real data instead of make e rely on training knowledge or make up answer. +This one make the model answer from your real data, no be only their training knowledge or just make answer. ## Prerequisites -- Complete [Module 00 - Quick Start](../00-quick-start/README.md) (for the Easy RAG example wey we talk about later for dis module) -- Complete [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI resources deployed, including the `text-embedding-3-small` embedding model) -- `.env` file for root directory with Azure credentials (wey `azd up` create for Module 01) +- You don finish [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI resources deploy finish, including `text-embedding-3-small` embedding model) +- `.env` file dey for root folder with Azure credentials (you fit create am with `azd up` for Module 01) -> **Note:** If you never finish Module 01, abeg follow de deployment instructions wey dey there first. The `azd up` command go deploy both GPT chat model and the embedding model wey dis module dey use. +> **Note:** If you never finish Module 01, abeg follow the deployment instructions for that one first. The `azd up` command go deploy both GPT chat model and embedding model wey dis module dey use. -## Understanding RAG +## How You Go Take Understand RAG -The diagram below dey show the main idea: instead of only rely on the model training data, RAG dey give am one reference library of your documents to check before e generate answer. +The diagram we dey show below na the main idea: instead of trust only the model training data, RAG go give am one reference library of your documents to check before e generate answer. What is RAG -*Dis diagram dey show the difference between normal LLM (wey dey guess from training data) and RAG-enhanced LLM (wey dey check your documents first).* +*This diagram dey show difference between normal LLM (wey dey guess from training data) and RAG-enhanced LLM (wey go check your documents first).* -See how the parts connect from beginning to end. Question from user pass through four stages — embedding, vector search, context assembly, and answer generation — each one dey build on the other: +See how everything connect from beginning to end. User question flow pass for four stages — embedding, vector search, context assembly, and answer generation — each one dey build on the previous: RAG Architecture -*Dis diagram dey show the RAG pipeline complete — user question pass through embedding, vector search, context assembly, and answer generation.* +*This diagram show the whole RAG pipeline from start to finish — user question go through embedding, vector search, context assembly, and answer generation.* -The rest of this module go explain each stage well well, with code wey you fit run and modify. +The rest of this module go walk you through each stage well well, with code wey you fit run and change. -### Which RAG Approach Dis Tutorial Dey Use? +### Which Kain RAG Dis Tutorial Dey Use? -LangChain4j get three ways to implement RAG, each get different abstraction level. The diagram below dey compare am side by side: +LangChain4j get three ways to implement RAG, each get different level of abstraction. See the diagram wey compare them side side: Three RAG Approaches in LangChain4j -*Dis diagram dey compare the three LangChain4j RAG approaches — Easy, Native, and Advanced — showing the main parts and when to use each one.* +*This diagram compare the three LangChain4j RAG ways — Easy, Native, and Advanced — showing their main parts and when you go use each one.* | Approach | Wetin E Dey Do | Trade-off | |---|---|---| -| **Easy RAG** | E dey wire everything automatically through `AiServices` and `ContentRetriever`. You just annotate interface, attach retriever, and LangChain4j go handle embedding, search, and prompt assembly for you. | Small code, but you no go see wetin dey happen for each step. | -| **Native RAG** | You go call embedding model, search the store, build prompt, and generate answer yourself — one explicit step per time. | More code, but every stage dey clear and you fit change am. | -| **Advanced RAG** | E dey use `RetrievalAugmentor` framework with pluggable query transformers, routers, re-rankers, and content injectors for production level pipelines. | Maximum flexibility, but e dey complex well well. | +| **Easy RAG** | E wire everything automatically through `AiServices` and `ContentRetriever`. You just annotate interface, attach retriever, LangChain4j go handle embedding, searching, and prompt assembly for you. | Small code, but you no go see wetin dey happen for each step. | +| **Native RAG** | You dey call embedding model, search store, build prompt, and generate answer by yourself — one by one step. | More code, but every stage dey clear and you fit change am. | +| **Advanced RAG** | E use `RetrievalAugmentor` framework with plug-in query transformers, routers, re-rankers, and content injectors for production-level pipelines. | Maximum flexibility, but e get plenty complexity. | -**Dis tutorial na Native approach e dey use.** Every step for RAG pipeline — embed the query, search vector store, assemble context, and generate answer — dey clearly written inside [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). E mean say as learning resource, e dey more important make you see and understand every stage pass to minimize code. When you don sabi how the pieces join, you fit move go Easy RAG for fast prototype or Advanced RAG for production. +**This tutorial na the Native way e dey use.** Every step for RAG pipeline — embedding the query, searching the vector store, assemble context, and generate answer — dey written clearly for [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Na on purpose e be like that: as learning resource, e better make you see and understand every step than to just minimize code. When you don sabi well how everything join, you fit move go Easy RAG for quick prototype or Advanced RAG for production. -> **💡 You don see Easy RAG before?** The [Quick Start module](../00-quick-start/README.md) get Document Q&A example ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) wey dey use Easy RAG — LangChain4j dey handle embedding, searching, and prompt assembly automatically. Dis module na next level wey open the pipeline make you fit see and control every stage by yourself. +> **💡 You curious about Easy RAG?** LangChain4j also get *Easy RAG* approach wey `AiServices` and `ContentRetriever` dey handle embedding, search, and prompt assemble automatically. But dis module wan show you the full detail path — break the pipeline open so you go fit see and control all the steps yourself. -Diagram below show Easy RAG pipeline from that Quick Start example. Notice how `AiServices` and `EmbeddingStoreContentRetriever` hide all the complexity — you just load document, attach retriever, and get answer. The Native approach for this module go open those hidden steps: +Diagram below show Easy RAG pipeline. Notice how `AiServices` and `EmbeddingStoreContentRetriever` hide all the complexity — you just load document, attach retriever, and collect answers. The Native way for this module go break all that hidden steps open: Easy RAG Pipeline - LangChain4j -*Dis diagram dey show Easy RAG pipeline from `SimpleReaderDemo.java`. Compare am with Native approach wey dis module dey use: Easy RAG hide embedding, retrieval, and prompt assembly behind `AiServices` and `ContentRetriever` — you load document, attach retriever, and receive answers. Native approach for dis module open the pipeline so you fit call each stage (embed, search, assemble context, generate) yourself, give you full control and clear view.* +*This diagram dey show Easy RAG pipeline. Compare am with Native approach wey dey dis module: Easy RAG hide embedding, retrieval, and prompt assemble behind `AiServices` and `ContentRetriever` — you just load document, attach retriever, and get answers. Native method for dis module dey open the pipeline so you fit call each stage (embed, search, assemble context, generate) yourself, give you full view and control.* ## How E Dey Work -RAG pipeline for dis module break down into four stages wey run one after another anytime user ask question. First, uploaded document go **parse and chunk** into small small parts. Those chunks go convert to **vector embeddings** and store so e fit compare mathematically. When query come, system go run **semantic search** to find the best chunks, then pass dem as context to LLM for **answer generation**. The sections below go explain each stage with real code and diagrams. Make we start with the first step. +The RAG pipeline for this module break down into four stages wey dey run one after another every time user ask question. First, document wey you upload. E go **parse and chunk** am into small small pieces wey model fit handle. Then the chunks go convert to **vector embeddings** come store so dem fit compare mathematically. When query land, the system go do **semantic search** to find the chunks wey match pass, then pass am as context to LLM for **answer generation**. The sections below go explain each stage with code and diagrams. Make we start with first step. -### Document Processing +### How You Go Take Process Document [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -When you upload document, system go parse am (PDF or plain text), attach metadata like filename, then break am into chunks — smaller parts wey fit inside model context window well well. These chunks dey overlap small so you no lose context for boundaries. +When you upload document, the system go parse am (PDF or plain text), attach some metadata like filename, then break am into chunks — small pieces wey go fit inside model's context window well. The chunks get small small overlap so you no lose context when e cut for the boundary. ```java // Parse di uploaded file an wrap am inside LangChain4j Document Document document = Document.from(content, metadata); -// Cut am into 300-token chunks wit 30-token overlap +// Split am into 300-token chunks wit 30-token overlap DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -Diagram below dey show how e dey work visually. Notice say each chunk dey share some tokens with im neighbours — the 30-token overlap make sure say no important context go lost between the cracks: + +Diagram below go show how e dey work for eye. See how each chunk share some tokens with the one beside am — the 30-token overlap make sure no important context waka disappear for between: Document Chunking -*Dis diagram dey show document wey dey split into 300-token chunks wit 30-token overlap, to preserve context for chunk boundaries.* +*This diagram dey show one document wey them split into 300-token chunks with 30-token overlap, so context for chunk boundary still dey.* -> **🤖 Try wit [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) and ask: -> - "How LangChain4j split documents into chunks and why overlap dey important?" -> - "Wetin be optimal chunk size for different document types and why?" -> - "How I fit handle documents wey get many languages or special formatting?" +> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) and ask: +> - "How LangChain4j dey split document into chunks and why overlap matter?" +> - "Wetin be best chunk size for different document types and why?" +> - "How I fit handle document wey get many languages or special formatting?" -### Creating Embeddings +### How You Go Take Do Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Each chunk go convert to numerical format wey dem dey call embedding — na how text meaning dey convert to numbers. Embedding model no be "intelligent" like chat model; e no fit follow instruction, reason or answer questions. Di one e fit do na to put text for mathematical space where meanings wey dey similar go dey close — like "car" near "automobile," "refund policy" near "return my money." Think chat model like person wey you fit yarn with; embedding model na one keen filing system. +Every chunk go convert into numerical form wey dem dey call embedding — na like meaning-to-numbers converter. The embedding model no be "intelligent" like chat model; e no fit obey instruction, reason, or answer questions. Wetin e fit do na map text into one mathematical space where similar meanings dey near each other — "car" near "automobile," "refund policy" near "return my money." Think am like say chat model na person wey you fit talk to; embedding model na correct filing system. -Diagram below show dis concept — text enter, numbers vectored come out, and similar meanings dey near each other: +Diagram below go show this idea — text dey go in, numbers dey come out, and similar meanings dey produce vectors wey near each other: Embedding Model Concept -*Di diagram show how embedding model dey convert text to numerical vectors, placing similar meanings — like "car" and "automobile" — close to each other for vector space.* +*This diagram dey show how embedding model con convert text to numerical vectors, put similar meanings — like "car" and "automobile" — close for vector space.* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -Class diagram below show di two separate flows inside RAG pipeline and LangChain4j classes wey handle dem. **Ingestion flow** (wey run once when upload) dey split documents, embed chunks, and store dem with `.addAll()`. **Query flow** (wey run anytime user ask) go embed question, search store with `.search()`, then pass context wey match to chat model. Both flows dey connected via shared `EmbeddingStore` interface: + +Class diagram below show two different flows inside RAG pipeline and LangChain4j classes wey implement dem. The **ingestion flow** (wey run once during upload) go split document, embed chunks, and store am with `.addAll()`. The **query flow** (wey run every time person ask question) go embed question, search store with `.search()`, then pass context matched to chat model. Both flows meet for shared `EmbeddingStore` interface: LangChain4j RAG Classes -*Dis diagram show di two flows inside RAG pipeline — ingestion and query — and how dem take connect via shared EmbeddingStore.* +*This diagram show the two flows for RAG pipeline — ingestion and query — and how dem join through shared EmbeddingStore.* -After embedding store finish, similar content go group together for vector space naturally. Visualization below dey show how documents about related topics dey come close one another as points, and dat na wetin make semantic search possible: +After embeddings don store, similar content go naturally group together for vector space. Visualization below show how documents wey related topics get nearby points, na wetin make semantic search work: Vector Embeddings Space -*Dis visualization dey show how related documents dey cluster for 3D vector space, with topics like Technical Docs, Business Rules, and FAQs making separate groups.* +*This picture dey show how related documents cluster together for 3D vector space, with topics like Technical Docs, Business Rules, and FAQs form their own groups.* -When user search, system dey follow four steps: embed documents once, embed query everytime search happen, compare query vector with all stored vectors using cosine similarity, then return top-K chunks wey score pass. Diagram below go show each step and LangChain4j classes wey dey involved: +When person search, the system dey follow four steps: embed documents once, embed query every search, compare query vector to all stored vectors using cosine similarity, and return top-K chunks with highest scores. Diagram below go show each step and LangChain4j classes wey dey involved: Embedding Search Steps -*Dis diagram dey show four-step embedding search process: embed documents, embed query, compare vectors with cosine similarity, and return top-K results.* +*This diagram go show embedding search four-step process: embed documents, embed query, compare vectors by cosine similarity, and return top-K results.* ### Semantic Search [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -When you ask question, your question carry embedding too. System go compare your question embedding with all document chunks embedding. E go find chunks wey get closest meaning — no be only keywords, na real semantic similarity. +When you ask question, your question also go become embedding. System go compare your question embedding with all document chunks embeddings. E go find chunks wey get most similar meanings — no be only keyword wey match, but real semantic similarity. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -Diagram below go contrast semantic search with traditional keyword search. Keyword search for "vehicle" no fit find chunk wey talk about "cars and trucks," but semantic search sabi say dem mean same thing and e go return am as high scoring match: + +Diagram below go show difference between semantic search and normal keyword search. Keyword search for "vehicle" no go find chunk about "cars and trucks," but semantic search sabi say dem mean one thing, so e go return am as high match: Semantic Search -*Dis diagram go compare keyword-based search with semantic search, showing how semantic search fit find content related by concept even if exact keywords differ.* -Unda di hood, similarity na wetin dem dey measure wit cosine similarity — e dey basically ask "di two arrow dem dey point for di same direction?" Two chunks fit use totally different words, but if dem mean di same tin their vectors go dey point di same way and dem go score near to 1.0: +*This diagram dey compare keyword search to semantic search, showing how semantic search fit find related content even if keywords no the same.* -Cosine Similarity +Under the hood, similarity na to measure with cosine similarity — na to ask "make we see if these two arrows dey point the same way?" Two chunks fit use different words, but if their meaning same, their vectors go point same way and score close to 1.0: -*Dis diagram dey show cosine similarity as di angle between embedding vectors — vectors wen align well go score close to 1.0, wey mean say dem mean almost di same tin.* +Cosine Similarity +*Dis diagram dey show cosine similarity as di angle between embedding vectors — di vectors wey align well go score closer to 1.0, wey mean say dem get high semantic similarity.* -> **🤖 Try wit [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) and ask: +> **🤖 Try wit [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) come ask: > - "How similarity search dey work wit embeddings and wetin dey determine di score?" -> - "Wetin similarity threshold I suppose use and how e dey affect results?" -> - "How I go handle cases wen no relevant documents dey found?" +> - "Wetin be di similarity threshold way I go use and how e dey affect di results?" +> - "How I go take handle cases wey no relevant documents dey found?" ### Answer Generation [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Di most relevant chunks dem dey put together inside one structured prompt wey get explicit instructions, di context wey dem find, and di question wey user ask. Di model go read only di chunks dem and answer based on dat tin — e go fit use only wetin dey front am, dis one dey prevent hallucination. +Di most relevant chunks na dem dem put together inside structured prompt wey get explicit instructions, di retrieved context, and di user question. Di model go read those particular chunks come answer based on wetin dey that information — e fit only use wetin dey front of am, wey go prevent am from hallucination. ```java String context = matches.stream() @@ -237,21 +236,21 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Di diagram wey dey below dey show how dem dey put dis tin together — di top-scoring chunks from di search step dem dey put inside di prompt template, and di `OpenAiOfficialChatModel` go generate grounded answer: +Di diagram wey dey down show how dis assembly dey work — di top-scoring chunks wey come from di search step dem dey put inside di prompt template, and di `OpenAiOfficialChatModel` dey generate grounded answer: Context Assembly -*Dis diagram dey show how di top-scoring chunks dem dey join to form structured prompt, wey allow di model to generate grounded answer from your data.* +*Dis diagram dey show how dem take gather di top-scoring chunks inside structured prompt, wey allow di model to generate grounded answer from your data.* ## Run the Application -**Verify deployment:** +**Make sure say deployment dey valid:** -Make sure say di `.env` file dey for root directory wit Azure credentials (wey dem create for Module 01). Run dis from di module directory (`03-rag/`): +Confirm say `.env` file dey for root directory wit Azure credentials (wey dem create during Module 01). Run dis for di module directory (`03-rag/`): **Bash:** ```bash -cat ../.env # Suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -261,37 +260,37 @@ Get-Content ..\.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Start di application:** -> **Note:** If you don start all applications wit `./start-all.sh` from root directory before (as we explain for Module 01), dis module dey already run on port 8081. You fit skip di start commands below go directly to http://localhost:8081. +> **Note:** If you don already start all applications using `./start-all.sh` from root directory (as per Module 01), dis module don dey run for port 8081. You fit skip di start commands below come go http://localhost:8081 direct. -**Option 1: Using Spring Boot Dashboard (Recommended for VS Code users)** +**Option 1: Use Spring Boot Dashboard (Na di one wey VS Code users suppose use)** -Di dev container get Spring Boot Dashboard extension, wey dey give you visual interface to manage all Spring Boot applications. You fit find am for di Activity Bar for left side of VS Code (look for di Spring Boot icon). +Di dev container get Spring Boot Dashboard extension, wey provide visual interface to manage all Spring Boot applications. You fit find am for Activity Bar for di left side inside VS Code (look out for di Spring Boot icon). -From Spring Boot Dashboard, you fit: -- See all di Spring Boot applications wey dey di workspace -- Start/stop applications wit just one click -- View application logs in real-time +From di Spring Boot Dashboard, you fit: +- See all Spring Boot applications wey dey for di workspace +- Start/stop applications with just one click +- View application logs anytime - Monitor application status -Just click di play button wey dey beside "rag" to start dis module, or start all modules at once. +Just click di play button beside "rag" to start dis module, or start all modules at once. Spring Boot Dashboard -*Dis screenshot dey show how Spring Boot Dashboard dey VS Code, where you fit start, stop, and monitor applications visually.* +*Dis screenshot dey show Spring Boot Dashboard inside VS Code, wey you fit start, stop, and dey monitor applications visually.* -**Option 2: Using shell scripts** +**Option 2: Use shell scripts** Start all web applications (modules 01-04): **Bash:** ```bash -cd .. # From root folder +cd .. # From root directory ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # From root directory +cd .. # From di top folder .\start-all.ps1 ``` @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Both scripts go automatically load environment variables from root `.env` file and dem go build di JARs if dem never dey. +Both scripts go automatically load environment variables from root `.env` file and go build di JARs if dem no dey. -> **Note:** If you wan build all modules by yourself before you start: +> **Note:** If you wan build all modules manually before you start: > > **Bash:** > ```bash @@ -327,13 +326,13 @@ Both scripts go automatically load environment variables from root `.env` file a Open http://localhost:8081 for your browser. -**To stop:** +**To stop am:** **Bash:** ```bash ./stop.sh # Dis module only # Or -cd .. && ./stop-all.sh # All modules +cd .. && ./stop-all.sh # All di modules ``` **PowerShell:** @@ -343,83 +342,83 @@ cd .. && ./stop-all.sh # All modules cd ..; .\stop-all.ps1 # All modules ``` -## Using di Application +## How to Use di Application -Di application dey provide web interface for document upload and question ask. +Di application get web interface wey you fit upload document come ask question. RAG Application Interface -*Dis screenshot dey show di RAG application interface wey you fit upload documents and ask questions.* +*Dis screenshot dey show RAG application interface wey you fit upload documents and ask questions.* -### Upload a Document +### Upload Document -Start by uploading document — TXT files dey best for testing. One `sample-document.txt` dey for dis directory, e get information about LangChain4j features, RAG implementation, and best practices - perfect for testing di system. +Begin by uploading document - TXT files go best for testing. We don provide `sample-document.txt` inside dis directory wey get info about LangChain4j features, RAG implementation, and best practices - perfect for testing di system. -Di system go process your document, break am into chunks, then e go create embeddings for each chunk. Dis one dey happen automatically when you upload. +Di system go process your document, break am into chunks, then create embeddings for each chunk. Dis one dey automatic when you upload. ### Ask Questions -Now ask di specific questions about di document content. Try ask factual tins wey clearly dey inside di document. Di system go search for relevant chunks, include dem inside di prompt, then generate answer. +Now, ask specific questions about di document content. Try ask something wey factual and wey clear for di document. Di system go search relevant chunks, include dem inside di prompt, then generate answer. ### Check Source References -You go notice say each answer get source references wit similarity scores. Dis scores (from 0 to 1) dey show how relevant each chunk be to your question. Higher scores mean better match. Dis one go help you verify di answer against di source. +You go notice say each answer get source references with similarity scores. Di scores (0 to 1) dey show how relevant each chunk be to your question. Higher scores mean say e better match. Dis one go help you verify answer with source material. RAG Query Results -*Dis screenshot dey show query results wit generated answer, source references, and relevance scores for each chunk dem find.* +*Dis screenshot dey show query results wit di generated answer, source references, and relevance scores for every chunk wey dem retrieve.* ### Experiment wit Questions -Try different kinds of questions: +Try different kind questions: - Specific facts: "Wetin be di main topic?" - Comparisons: "Wetin be di difference between X and Y?" - Summaries: "Summarize di key points about Z" -Watch how di relevance scores dey change based on how well your question match di document content. +Watch how di relevance scores dey change based on how your question dey match document content. ## Key Concepts ### Chunking Strategy -Documents dem dey split into 300-token chunks with 30 tokens overlap. Dis one dey balance so dat each chunk get enough context to mean wetin e suppose mean but e still small enough to fit many chunks inside prompt. +Documents dem dey split into 300-token chunks wit 30 tokens overlap. Dis balance dey make sure say each chunk get enough context to make sense but still small to fit plenty chunks inside one prompt. ### Similarity Scores -Every chunk wey dem find get similarity score between 0 and 1 wey dey show how close e match di user's question. Di diagram below dey show di score ranges and how system dey use dem to filter results: +Every retrieved chunk dey come wit similarity score between 0 and 1 wey mean how close e match user question. Di diagram below dey show di score ranges and how di system dey use dem to filter results: Similarity Scores -*Dis diagram dey show score ranges from 0 to 1, wit minimum threshold of 0.5 wey dey filter out chunks wey no too relate.* +*Dis diagram dey show score ranges from 0 to 1, wit minimum threshold of 0.5 wey dey filter out irrelevant chunks.* -Scores range from 0 to 1: +Scores dey range from 0 to 1: - 0.7-1.0: Highly relevant, exact match - 0.5-0.7: Relevant, good context -- Below 0.5: Dem filter am out, e too different +- Below 0.5: Filtered out, too different -Di system na only chunks wey pass di minimum threshold e go retrieve so dat quality go dey. +Di system go only retrieve chunks wey above di minimum threshold to guarantee quality. -Embeddings dey work well when meaning clusters cleanly, but dem get blind spots. Di diagram below dey show di common failure modes — chunks wey big too much go create muddy vectors, chunks wey small die no get enough context, ambiguous terms dey point to many clusters, and exact-match lookups (IDs, part numbers) no dey work wit embeddings at all: +Embeddings dey work well when meaning cluster clean, but dem get blind spots. Di diagram below show common failure modes — chunks wey too big dey produce muddy vectors, chunks wey too small no get context, ambiguous terms fit point to many clusters, and exact-match lookups (IDs, part numbers) no work with embeddings at all: Embedding Failure Modes -*Dis diagram dey show common embedding failure modes: chunks wey big die, chunks wey small die, ambiguous terms wey dey point to different clusters, and exact-match lookups like IDs.* +*Dis diagram dey show common embedding failure modes: chunks wey too big, chunks wey too small, ambiguous terms wey fit mean many clusters, and exact-match lookups like IDs.* ### In-Memory Storage -Dis module dey use in-memory storage for simplicity. When you restart di application, di uploaded documents go lost. Production systems dey use persistent vector databases like Qdrant or Azure AI Search. +Dis module dey use in-memory storage for simplicity. Once you restart di application, uploaded documents go lost. Production systems dey use persistent vector databases like Qdrant or Azure AI Search. ### Context Window Management -Each model get maximum context window. You no fit put every chunk from big document. Di system go retrieve top N most relevant chunks (default na 5) to stay within di limit but still provide enough context make answers accurate. +Each model get maximum context window. You no fit include every chunk from big document. Di system go retrieve top N most relevant chunks (default na 5) to stay within limit but still provide enough context for correct answers. ## When RAG Matters -RAG no always be di right approach. Di decision guide below dey help you sabi when RAG get value versus when simpler approaches — like putting content straight inside prompt or relying on di model built-in knowledge — dey good enough: +RAG no always be di correct way. Di decision guide below go help you sabi when RAG go add value versus when simpler ways — like include content direct inside prompt or depend on di model own built-in knowledge — go sufice: When to Use RAG -*Dis diagram dey show decision guide for when RAG get value versus when simpler methods jus enough.* +*Dis diagram dey show decision guide for when RAG add value versus when simpler ways go sufice.* ## Next Steps @@ -433,5 +432,5 @@ RAG no always be di right approach. Di decision guide below dey help you sabi wh **Disclaimer**: -Dis dokumant don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even as we dey try make am correct, abeg sabi say automated translation fit get errors or mistakes. Di original dokumant wey dem write for im own language na di correct one. If na important tin, better make human professional person do di translation. We no go hold ourselves responsible if people no understand well or misinterpret because of dis translation. +Dis document don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even tho we dey try make am correct, abeg make you know say automated translation fit get errors or mistakes. Di original document for dia own language na im be di correct source. For important info, make person wey sabi human translation do am. We no go responsible for any misunderstanding or wrong understanding wey fit happen because of dis translation. \ No newline at end of file diff --git a/translations/pcm/04-tools/README.md b/translations/pcm/04-tools/README.md index f3c58f9cc..34a49fc65 100644 --- a/translations/pcm/04-tools/README.md +++ b/translations/pcm/04-tools/README.md @@ -2,75 +2,75 @@ ## Table of Contents -- [Video Walkthrough](../../../04-tools) -- [Wetín You Go Learn](../../../04-tools) -- [Prerequisites](../../../04-tools) -- [Understanding AI Agents wit Tools](../../../04-tools) -- [How Tool Calling Dey Work](../../../04-tools) - - [Tool Definitions](../../../04-tools) - - [Decision Making](../../../04-tools) - - [Execution](../../../04-tools) - - [Response Generation](../../../04-tools) - - [Architecture: Spring Boot Auto-Wiring](../../../04-tools) -- [Tool Chaining](../../../04-tools) -- [Run the Application](../../../04-tools) -- [Using the Application](../../../04-tools) - - [Try Simple Tool Usage](../../../04-tools) - - [Test Tool Chaining](../../../04-tools) - - [See Conversation Flow](../../../04-tools) - - [Experiment wit Different Requests](../../../04-tools) -- [Key Concepts](../../../04-tools) - - [ReAct Pattern (Reasoning and Acting)](../../../04-tools) - - [Tool Descriptions Matter](../../../04-tools) - - [Session Management](../../../04-tools) - - [Error Handling](../../../04-tools) -- [Available Tools](../../../04-tools) -- [When to Use Tool-Based Agents](../../../04-tools) -- [Tools vs RAG](../../../04-tools) -- [Next Steps](../../../04-tools) +- [Video Walkthrough](#video-walkthrough) +- [Wetin You Go Learn](#wetin-you-go-learn) +- [Prerequisites](#prerequisites) +- [Understanding AI Agents wit Tools](#understanding-ai-agents-wit-tools) +- [How Tool Calling Dey Work](#how-tool-calling-dey-work) + - [Tool Definitions](#tool-definitions) + - [Decision Making](#decision-making) + - [Execution](#execution) + - [Response Generation](#response-generation) + - [Architecture: Spring Boot Auto-Wiring](#architecture-spring-boot-auto-wiring) +- [Tool Chaining](#tool-chaining) +- [Run the Application](#run-the-application) +- [Using the Application](#using-di-application) + - [Try Simple Tool Usage](#try-simple-tool-usage) + - [Test Tool Chaining](#test-tool-chaining) + - [See Conversation Flow](#see-conversation-flow) + - [Experiment wit Different Requests](#experiment-wit-different-requests) +- [Key Concepts](#key-concepts) + - [ReAct Pattern (Reasoning and Acting)](#react-pattern-reasoning-and-acting) + - [Tool Descriptions Matter](#tool-descriptions-matter) + - [Session Management](#session-management) + - [Error Handling](#error-handling) +- [Available Tools](#available-tools) +- [When to Use Tool-Based Agents](#when-to-use-tool-based-agents) +- [Tools vs RAG](#tools-vs-rag) +- [Next Steps](#next-steps) ## Video Walkthrough Watch dis live session wey explain how to start wit dis module: -AI Agents with Tools and MCP - Live Session +AI Agents wit Tools and MCP - Live Session -## Wetín You Go Learn +## Wetin You Go Learn -So far, you don learn how to yarn wit AI, how to arrange prompts well well, and how to base responses for your documents. But one gbege still dey: language models fit only make text. Dem no fit check weather, do maths, ask databases, or dey interact wit outside systems. +So far, you don learn how to dey hold conversation wit AI, how to structure prompts well, and how to ground responses for your documents. But still e get one big problem: language models fit only generate text. Dem no fit check weather, do calculations, query databases, or interact wit external systems. -Tools change dis. By giving the model access to functions wey e fit call, you go turn am from just text generator to agent wey fit take action. The model dey decide when e need tool, which tool to use, and which parameters to pass. Your code go run the function and return the result. The model go add that result to e response. +Tools change dis. By giving di model access to functions wey e fit call, you fit turn am from just text generator to agent wey fit take actions. Di model dey decide wen e need tool, which tool to use, and wetin parameters to pass. Your code go execute di function and return di result. Di model go incorporate dat result inside im response. ## Prerequisites -- Don finish [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI resources done deploy) -- Don finish previous modules wey dem recommend (dis module dey talk about [RAG concepts from Module 03](../03-rag/README.md) for the Tools vs RAG comparison) -- `.env` file for root directory wit Azure credentials (na `azd up` for Module 01 create am) +- Done [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI resources deployed) +- Done previous modules wey dem recommend (dis module dey reference [RAG concepts from Module 03](../03-rag/README.md) for Tools vs RAG comparison) +- `.env` file dey for root directory wit Azure credentials (wey na `azd up` for Module 01 create am) -> **Note:** If you never finish Module 01, start from there first with the deployment instructions. +> **Note:** If you never finish Module 01, make you follow di deployment instructions there first. ## Understanding AI Agents wit Tools -> **📝 Note:** The word "agents" for dis module mean AI assistants wey dem add tool-calling abilities to. Dis different from **Agentic AI** patterns (autonomous agents wit planning, memory, and multi-step reasoning) wey we go cover for [Module 05: MCP](../05-mcp/README.md). +> **📝 Note:** Di term "agents" for dis module mean AI assistants wey get tool-calling capabilities. Dis no be di same as **Agentic AI** patterns (wey be autonomous agents wit planning, memory, and multi-step reasoning) wey we go cover for [Module 05: MCP](../05-mcp/README.md). -Without tools, language model fit only generate text from wetin e learn. If you ask am about weather now, e go just guess. But if you give am tools, e fit call weather API, do maths, or ask database — then join real result inside e response. +Without tools, one language model fit only generate text from im training data. If you ask am for di weather now, e go just guess. But if you give am tools, e fit call weather API, do calculations, or query database — then fit weave those real results into im response. Without Tools vs With Tools -*Without tools the model go just guess — wit tools e fit call APIs, do maths, and bring real-time data.* +*Without tools model fit only guess — wit tools e fit call API dem, run calculations, and return real-time data.* -AI agent wit tools dey follow **Reasoning and Acting (ReAct)** pattern. The model no just answer — e dey think wetin e need, call tool, check the result, then decide if e go act again or give answer: +One AI agent wit tools dey follow **Reasoning and Acting (ReAct)** pattern. Di model no dey just respond — e go think wetin e need, act by calling tool, check di result, then decide whether to act again or deliver di final answer: -1. **Reason** — Agent dey check user question and find wetin e need -2. **Act** — Agent pick correct tool, set parameters, and call am -3. **Observe** — Agent see the tool output and judge am -4. **Repeat or Respond** — If e still need data, e go start again; if no, e go give normal language answer +1. **Reason** — Agent go analyze wetin user ask and determine wetin info e need +2. **Act** — Agent go pick correct tool, generate correct parameters, then call am +3. **Observe** — Agent go receive tool output and evaluate di result +4. **Repeat or Respond** — If e still need more data, agent go loop back; if no, e go compose normal language answer ReAct Pattern -*ReAct cycle — agent dey reason, act by calling tool, observe result, and continue till e fit give final answer.* +*Di ReAct cycle — agent dey reason wetin e suppose do, act by calling tool, observe di result, then repeat till e fit give final answer.* -Dis dey happen automatically. You go define tools and their description. The model go dey handle when and how to use dem. +Dis one dey happen automatically. You go define di tools and dem descriptions. Di model go handle di decision wen and how to use dem. ## How Tool Calling Dey Work @@ -78,7 +78,7 @@ Dis dey happen automatically. You go define tools and their description. The mod [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -You go define functions wit clear description and parameters. The model go see these description inside system prompt and understand wetin each tool dey do. +You dey define functions wit clear descriptions and parameter specs. Di model dey see those descriptions for im system prompt and e go sabi wetin each tool de do. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // How you dey find weather + // Your weather lookup logic return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,137 +96,137 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Assistant na Spring Boot dey automatically connect am with: +// Assistant dey automatically connect by Spring Boot wit: // - ChatModel bean // - All @Tool methods from @Component classes // - ChatMemoryProvider for session management ``` -The diagram below show every annotation and how each part dey help AI know when to call tool and which arguments to pass: +Di diagram below break down every annotation and show how each part help AI sabi wen to call tool and wetin arguments to pass: Anatomy of Tool Definitions -*Anatomy of tool definition — @Tool tell AI when to use am, @P describe each parameter, and @AiService join everything together for startup.* +*How tool definition be — @Tool dey tell AI wen to use am, @P dey describe each parameter, and @AiService dey wire everything together when startup.* > **🤖 Try wit [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) and ask: -> - "How I go join real weather API like OpenWeatherMap instead of mock data?" -> - "Wetin make beta tool description wey go help AI use am well?" -> - "How I go handle API wahala and rate limits for tool implementations?" +> - "How I go fit integrate real weather API like OpenWeatherMap instead of mock data?" +> - "Wetin make good tool description wey go help AI use am well?" +> - "How I go fit handle API errors and rate limits for tool implementations?" ### Decision Making -If user ask "Wetyn the weather dey like for Seattle?", the model no just pick tool anyhow. E go compare user intent to all tool description wey e get, score all for relevance, then pick correct one. E go generate function call with right parameters — here e set `location` to `"Seattle"`. +When user ask "Wetn be di weather for Seattle?", di model no go just pick any tool anyhow. E go compare wetin user want wit every tool description wey e get, score each one based on how e relate, then pick di best one. E go generate structured function call with correct parameters — for here, e go set `location` to `"Seattle"`. -If no tool fit user request, model go reply with wetin e know. If tool plenty wey fit, e go choose the most correct one. +If no tool match wetin user want, di model go fallback to answer wit im own knowledge. If plenty tools match, e go pick di one wey be most specific. How the AI Decides Which Tool to Use -*Model dey check all available tools against user intent and pick correct one — na why clear, specific tool description dey important.* +*Model dey evaluate every tool against wetin user want and pick di best one — na why e good to write clear, specific tool descriptions.* ### Execution [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot auto-wires the `@AiService` interfaces for all tools registered, LangChain4j go run tool calls automatically. Under the hood, tool call go run six stages — from user natural language question reach natural language answer: +Spring Boot dey auto-wire di declarative `@AiService` interface wit all registered tools, and LangChain4j dey execute tool calls automatically. Behind di scenes, full tool call dey flow through six stages — from user natural language question all di way back to natural language answer: Tool Calling Flow -*End-to-end flow — user ask, model select tool, LangChain4j run am, model use result join response.* +*End-to-end flow — user ask question, model pick tool, LangChain4j execute am, and model weave di result into natural response.* -If you run [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) for Module 00 before, you don see dis pattern — Calculator tool calls dey the same. Sequence diagram below show wetin happen under the hood that time: +For backend, `AiServices` dey run the same tool-calling loop for any tool — here e show wit simple `Calculator`. Di sequence diagram below show exactly wetin dey happen inside: Tool Calling Sequence Diagram -*Tool-calling loop from Quick Start demo — `AiServices` send your message and tool schema to LLM, LLM come reply wit function call like `add(42, 58)`, LangChain4j run Calculator method for local, then return result for final answer.* +*Tool-calling loop — `AiServices` go send your message and tool schemas to di LLM, LLM go reply wit function call like `add(42, 58)`, LangChain4j go execute di `Calculator` method locally, and send di result back for di final answer.* > **🤖 Try wit [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) and ask: > - "How ReAct pattern dey work and why e dey effective for AI agents?" > - "How agent dey decide which tool to use and wetin order?" -> - "If tool run fail, how I fit handle errors strong strong?" +> - "Wetin dey happen if tool execution fail - how person go fit handle errors well?" ### Response Generation -Model go receive weather data then format am as natural language response for user. +Di model go receive di weather data and format am into natural language response for user. ### Architecture: Spring Boot Auto-Wiring -Dis module dey use LangChain4j Spring Boot integration wit declarative `@AiService` interfaces. For startup, Spring Boot go find every `@Component` wey get `@Tool` methods, plus your `ChatModel` bean and `ChatMemoryProvider` — then wire dem all into one `Assistant` interface wit no extra code. +Dis module dey use LangChain4j Spring Boot integration wit declarative `@AiService` interfaces. For startup, Spring Boot go find every `@Component` wey get `@Tool` methods, your `ChatModel` bean, and di `ChatMemoryProvider` — then e go wire dem join into one `Assistant` interface wit zero boilerplate. Spring Boot Auto-Wiring Architecture -*@AiService interface dey join ChatModel, tool components, and memory provider — Spring Boot dey handle all wiring automatically.* +*Di @AiService interface dey connect ChatModel, tool components, and memory provider — Spring Boot go handle all di wiring automatically.* -This na full request lifecycle as sequence diagram — from HTTP request through controller, service, and auto-wired proxy, go all the way to tool execution and back: +Here na the full request lifecycle as sequence diagram — from HTTP request through controller, service, and auto-wired proxy all di way to tool execution and back: Spring Boot Tool Calling Sequence -*Complete Spring Boot request lifecycle — HTTP request flow reach controller, service, auto-wired Assistant proxy, and e manage LLM and tool calls automatically.* +*Complete Spring Boot request lifecycle — HTTP request dey flow through controller and service to auto-wired Assistant proxy, wey dey run di LLM and tool calls automatically.* -Big benefits of dis approach: +Key benefits of dis method: -- **Spring Boot auto-wiring** — ChatModel and tools dey inject automatically +- **Spring Boot auto-wiring** — ChatModel and tools automatically dey injected - **@MemoryId pattern** — Automatic session-based memory management -- **Single instance** — Assistant create once, dem dey reuse am for better speed -- **Type-safe execution** — Java methods dey call direct wit type conversion -- **Multi-turn orchestration** — E dey handle tool chaining automatically -- **Zero boilerplate** — No manual `AiServices.builder()` or memory HashMap +- **Single instance** — Assistant create once, reuse am for better performance +- **Type-safe execution** — Java methods dey called directly wit type conversion +- **Multi-turn orchestration** — Handles tool chaining automatically +- **Zero boilerplate** — No manual `AiServices.builder()` calls or memory HashMap -Other ways (manual `AiServices.builder()`) need more code and no get Spring Boot integration benefits. +Other methods (manual `AiServices.builder()`) go need more code and no get di Spring Boot integration benefits. ## Tool Chaining -**Tool Chaining** — Real power of tool-based agents show when one question need many tools. If you ask "Wetyn weather dey like for Seattle in Fahrenheit?" agent go chain two tools automatic: first call `getCurrentWeather` get temp for Celsius, then pass am to `celsiusToFahrenheit` to convert — all na one conversation turn. +**Tool Chaining** — Real power of tool-based agents dey show wen one single question need multiple tools. If you ask "Wetn be di weather for Seattle in Fahrenheit?" agent go automatically chain two tools: first e go call `getCurrentWeather` to get temperature for Celsius, then e pass dat value to `celsiusToFahrenheit` to convert — all na one conversation turn. Tool Chaining Example -*Tool chaining in action — agent call getCurrentWeather first, then use Celsius result for celsiusToFahrenheit, then give combined answer.* +*Tool chaining for action — agent first call getCurrentWeather, then pipe di Celsius result enter celsiusToFahrenheit, den deliver combined answer.* -**Graceful Failures** — If you ask weather for city wey no dey mock data, tool go return error message, AI go explain say e no fit help instead make e crash. Tools dey fail safely. Diagram below compare the two style — wit correct error handling, agent go catch the error and answer well; if no, whole app go crash: +**Graceful Failures** — If you ask for weather for city wey no dey inside mock data, tool go return error message, and AI go explain say e no fit help instead of crash. Tools dey fail safe. Di diagram below show di two way — wit good error handling, agent go catch exception and respond nicely, but without am whole app go crash: Error Handling Flow -*If tool fail, agent go catch error and give helpful explanation instead of crash.* +*When tool fail, agent go catch di error and respond wit helpful explanation, no be to crash.* -Na one conversation turn dis one. Agent dey manage many tool calls by itself. +Dis one dey happen in one conversation turn. Agent dey manage multiple tool calls by itself. ## Run the Application **Check deployment:** -Make sure `.env` file dey root directory with Azure credentials (na Module 01 create am). Run dis from module folder (`04-tools/`): +Make sure `.env` file dey for root directory wit Azure credentials (wey create during Module 01). Run dis from di module directory (`04-tools/`): **Bash:** ```bash -cat ../.env # En go show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # En suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # E suppose show AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Start the application:** -> **Note:** If you don start all apps wit `./start-all.sh` from root directory (like Module 01 talk), dis module dey run for port 8084 already. You fit skip the start commands here and go straight to http://localhost:8084. +> **Note:** If you don already start all applications wit `./start-all.sh` from root directory (like e talk for Module 01), dis module dey already run for port 8084. You fit skip di start commands below and go straight to http://localhost:8084. **Option 1: Using Spring Boot Dashboard (Recommended for VS Code users)** -Dev container get Spring Boot Dashboard extension wey give GUI to manage all Spring Boot apps. You fit find am for Activity Bar left side of VS Code (look for the Spring Boot icon). +Di dev container get di Spring Boot Dashboard extension, wey dey provide visual interface to manage all Spring Boot applications. You fit find am for di Activity Bar for left side of VS Code (look for di Spring Boot icon). -From Spring Boot Dashboard, you fit: -- See all Spring Boot apps wey dey workspace -- Start/stop apps with one click -- See app logs inside real-time -- Monitor app status -Just click di play button wey dey next to "tools" to start dis module, or start all modules at once. +From di Spring Boot Dashboard, you fit: +- See all available Spring Boot applications for workspace +- Start/stop applications wit one click +- View application logs live +- Monitor application status -Na so di Spring Boot Dashboard be for VS Code: +Just click di play button wey dey beside "tools" to start dis module, or start all modules at once. +See wetin di Spring Boot Dashboard look like for VS Code: Spring Boot Dashboard *Di Spring Boot Dashboard for VS Code — start, stop, and monitor all modules from one place* -**Option 2: Using shell scripts** +**Option 2: Wɛ̄ yus shell scripts** Start all web applications (modules 01-04): @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Both scripts dey automatically load environment variables from di root `.env` file and go build di JARs if dem no dey. +Both scripts automatically load environment variables from di root `.env` file and go build di JARs if dem no dey. -> **Note:** If you prefer make you build all modules manually before you start: +> **Note:** If you prefer to build all modules manually before you start: > > **Bash:** > ```bash @@ -287,89 +287,89 @@ cd .. && ./stop-all.sh # All di modules ```powershell .\stop.ps1 # Dis module only # Or -cd ..; .\stop-all.ps1 # All modules +cd ..; .\stop-all.ps1 # All di modules ``` -## How to Use Di Application +## Using di Application -Di application dey provide web interface wey you fit use to interact with AI agent wey get access to weather and temperature conversion tools. Na so di interface be — e get quick-start examples and chat panel for sending requests: +Di application get web interface wey you fit interact wit AI agent wey get access to weather and temperature conversion tools. Dis na wetin di interface dey look like — e get quick-start examples and chat panel for send requests: AI Agent Tools Interface -*Di AI Agent Tools interface - quick examples and chat interface for interacting with tools* +*Di AI Agent Tools interface - quick examples and chat interface for interact wit tools* ### Try Simple Tool Usage -Start with simple request: "Convert 100 degrees Fahrenheit to Celsius". Di agent go sabi say e need di temperature conversion tool, go call am with correct parameters, then return di result. You go notice say dis kain thing feel natural - you no talk which tool make e use or how to call am. +Start wit straightforward request: "Convert 100 degrees Fahrenheit to Celsius". Di agent sabi say e need temperature conversion tool, e call am wit correct parameters, and e return di result. Notice how natural e dey feel - you no specify which tool to use or how to call am. ### Test Tool Chaining -Now try sometin wey get small complication: "What's the weather in Seattle and convert am to Fahrenheit?" Watch as di agent go work am step by step. E first get di weather (wey dey return Celsius), then e go sabi say e need make e convert to Fahrenheit, go call di conversion tool, then join both results into one response. +Now try sometin wey complex pass: "Wetin be di weather for Seattle and convert am to Fahrenheit?" Watch di agent work dis step by step. E first get di weather (wey return Celsius), know say e need do conversion to Fahrenheit, call di conversion tool, then combine both results into one response. ### See Conversation Flow -Di chat interface dey keep conversation history, e make you fit do multi-turn interactions. You fit see all previous questions and answers, e easy to track di conversation and understand how di agent dey build context as you dey yarn many times. +Di chat interface dey keep conversation history, e allow you get multi-turn interactions. You fit see all previous queries and responses, e make am easy to track di conversation and understand how di agent dey build context over multiple exchanges. Conversation with Multiple Tool Calls *Multi-turn conversation wey dey show simple conversions, weather lookups, and tool chaining* -### Experiment with Different Requests +### Experiment wit Different Requests Try different combinations: -- Weather lookups: "What's the weather in Tokyo?" -- Temperature conversions: "What is 25°C in Kelvin?" -- Combined queries: "Check di weather for Paris and tell me if e dey above 20°C" +- Weather lookups: "Wetin be di weather for Tokyo?" +- Temperature conversions: "Wetin be 25°C for Kelvin?" +- Combined queries: "Check di weather for Paris and tell me if e pass 20°C" -You go see how di agent dey interpret natural language and map am to correct tool calls. +Notice how di agent interpret natural language and map am to correct tool calls. ## Key Concepts ### ReAct Pattern (Reasoning and Acting) -Di agent dey change between reasoning (to decide wetin im go do) and acting (to use tools). Dis pattern dey allow autonomous problem-solving instead of just obey instructions. +Di agent dey switch between reasoning (deciding wetin e go do) and acting (using tools). Dis pattern make am fit solve problem by itself instead of just respond to instructions. ### Tool Descriptions Matter -How you describe your tools dey affect how well di agent fit use dem. Clear and specific descriptions dey help di model understand when and how to call each tool. +How you describe your tools fit affect how well di agent go use dem. Clear, specific descriptions help di model understand when and how to call each tool. ### Session Management -Di `@MemoryId` annotation dey enable automatic session-based memory management. Each session ID get im own `ChatMemory` instance wey di `ChatMemoryProvider` bean dey manage, so many users fit interact with di agent at di same time without their conversations mixing. Di diagram below show how many users dey routed to separate memory stores based on their session IDs: +Di `@MemoryId` annotation dey enable automatic session-based memory management. Each session ID get im own `ChatMemory` instance wey di `ChatMemoryProvider` bean dey manage, so multiple users fit interact wit di agent at same time without their conversations mix together. Di diagram below show how multiple users go direct go isolated memory stores based on their session IDs: Session Management with @MemoryId -*Each session ID maps to isolated conversation history — users no fit see each other's messages.* +*Each session ID dey map to isolated conversation history — users no fit see each other's messages.* ### Error Handling -Tools fit fail — APIs fit timeout, parameters fit be invalid, external services fit crash. Production agents need error handling so di model fit explain problems or try other ways instead of crash di whole app. When tool throw exception, LangChain4j go catch am and pass di error message back to di model, so e fit explain di problem in natural language. +Tools fit fail — APIs fit timeout, parameters fit wrong, external services fit down. Production agents need error handling so di model fit explain problem or try other options instead of make di whole application crash. When tool throw exception, LangChain4j go catch am and feed di error message back to di model, wey fit explain di problem for natural language. ## Available Tools -Di diagram below show di broad ecosystem of tools you fit build. Dis module show weather and temperature tools, but di same `@Tool` pattern fit work for any Java method — from database queries to payment processing. +Di diagram below show di wide range of tools wey you fit build. Dis module dey show weather and temperature tools, but di same `@Tool` pattern fit work for any Java method — from database queries to payment processing. Tool Ecosystem -*Any Java method wey annotated with @Tool fit become available to di AI — di pattern fit extend to databases, APIs, email, file operations, and more.* +*Any Java method annotated wit @Tool go dey available to di AI — di pattern fit spread to databases, APIs, email, file operations, and more.* ## When to Use Tool-Based Agents -No all requests need tools. Di decision na if di AI need interact with external systems or e fit answer from im own knowledge. Di guide below summarize when tools dey add value and when dem no necessary: +No be every request need tools. Di decision na whether di AI need interact wit external systems or if e fit answer from im own knowledge. Di guide below summarize when tools dey useful and when dem no really need am: When to Use Tools -*A quick decision guide — tools dey for real-time data, calculations, and actions; general knowledge and creative tasks no need dem.* +*Quick decision guide — tools dey for real-time data, calculations, and actions; general knowledge and creative tasks no need dem.* ## Tools vs RAG -Modules 03 and 04 both extend wetin di AI fit do, but for different ways. RAG dey give di model access to **knowledge** by retrieving documents. Tools dey give di model ability to perform **actions** by calling functions. Di diagram below compare both approaches side by side — from how dem workflow dey operate to di trade-offs wey dey: +Modules 03 and 04 both extend wetin di AI fit do, but for fundamentally different ways. RAG dey give di model access to **knowledge** by retrieving documents. Tools dey give di model ability to take **actions** by calling functions. Di diagram below compare these two approaches side by side — from how each workflow dey operate to di trade-offs between dem: Tools vs RAG Comparison -*RAG dey retrieve info from static documents — Tools dey execute actions and fetch dynamic, real-time data. Many production systems dey combine both.* +*RAG dey retrieve information from static documents — Tools dey execute actions and fetch dynamic, real-time data. Many production systems dey combine both.* -For practice, many production systems dey use both ways together: RAG to ground answers for your documentation, and Tools to fetch live data or perform actions. +For practice, many production systems dey combine both approaches: RAG for grounding answers inside your documentation, and Tools for fetching live data or doing operations. ## Next Steps @@ -383,5 +383,5 @@ For practice, many production systems dey use both ways together: RAG to ground **Disclaimer**: -Dis document don been translate usin AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even though we dey try make am correct, abeg remember say automated translations fit get errors or mistakes. Di original document wey dem write for im own language na di correct one. For important matter, better make person wey sabi human translation do am. We no dey responsible for any wahala or wrong understanding wey fit come from dis translation. +Dis document don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even tho we dey try make am correct, abeg make you know say automated translation fit get errors or mistakes. Di original document for dia own language na im be di correct source. For important info, make person wey sabi human translation do am. We no go responsible for any misunderstanding or wrong understanding wey fit happen because of dis translation. \ No newline at end of file diff --git a/translations/pcm/README.md b/translations/pcm/README.md index 1155b13da..a233f3218 100644 --- a/translations/pcm/README.md +++ b/translations/pcm/README.md @@ -2,18 +2,18 @@ # LangChain4j for Beginners -Na kurs wey dey teach how to build AI apps wit LangChain4j and Azure OpenAI GPT-5.2, from basic chat reach AI agents. +One course wey dey teach how to build AI applications wit LangChain4j and Azure OpenAI GPT-5.2, from basic chat go reach AI agents. ### 🌐 Multi-Language Support -#### Supported via GitHub Action (Automated & Always Up-to-Date) +#### Dem dey support am for GitHub Action (Automated & Always Up-to-Date) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](./README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **You prefer to Clone Locally?** +> **You Nor Dey Want Small Wahala? Clon am for your system?** > -> Dis repository get more than 50 language translations wey make di download size big well well. If you want clone without di translations, use sparse checkout: +> Dis repository get 50+ language translations wey fit make di download big. If you wan clone without translations, use sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,21 +29,20 @@ Na kurs wey dey teach how to build AI apps wit LangChain4j and Azure OpenAI GPT- > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Dis one go give you everything wey you need to finish di course but your download go quick well. +> Dis one go give you everytin wey you need to complete di course quick quick. ## Table of Contents -1. [Quick Start](00-quick-start/README.md) - How to start with LangChain4j -2. [Introduction](01-introduction/README.md) - Learn di basic tins about LangChain4j -3. [Prompt Engineering](02-prompt-engineering/README.md) - How to sabi design better prompt dem -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Build smart knowledge-based systems -5. [Tools](04-tools/README.md) - How to join outside tools and simple assistants -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Work wit di Model Context Protocol (MCP) and Agentic modules +1. [Introduction](01-introduction/README.md) - Learn di basics of LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Master how to design prompt well well +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Build smart knowledge based systems +4. [Tools](04-tools/README.md) - Connect external tools and simple assistants +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Work wit Model Context Protocol (MCP) and Agentic modules ### Video Walkthroughs -Each module get live session wey go show di concepts and code small small. +Each module get live session wey we dey go through di ideas and code step by step. | Module | Video | |--------|-------| @@ -56,33 +55,35 @@ Each module get live session wey go show di concepts and code small small. ## Learning Path -**New for LangChain4j?** Check di [Glossary](docs/GLOSSARY.md) for wetin key terms and concepts mean. +**You be new for LangChain4j?** Check out di [Glossary](docs/GLOSSARY.md) for wetin key terms and concepts mean. -> **Quick Start** +> **How to Start Quick** -1. Fork dis repo go your GitHub account +1. Fork dis repository go your GitHub account 2. Click **Code** → **Codespaces** tab → **...** → **New with options...** -3. Use di default – dis one go select di Development container wey dem create for dis course +3. Use di defaults – dis one go select di Development container wey dem make for dis course 4. Click **Create codespace** -5. Wait like 5-10 minutes for di environment to ready -6. Jump quick go [Quick Start](./00-quick-start/README.md) make you fit start! +5. Wait 5-10 minutes till environment ready +6. Jump straight go [Introduction](./01-introduction/README.md) to start! -After you don finish di modules, try check di [Testing Guide](docs/TESTING.md) make you see how di LangChain4j testing concepts dey work. +After you finish all di modules, check di [Testing Guide](docs/TESTING.md) to sabi how dem dey test LangChain4j concepts. + +> **Note:** Dis training dey use Azure OpenAI. If you never get, start with [FREE Azure account](https://aka.ms/azure-free-account). -> **Note:** Dis training dey use both GitHub Models and Azure OpenAI. Di [Quick Start](00-quick-start/README.md) module dey use GitHub Models (no need Azure subscription), but modules 1-5 dey use Azure OpenAI. If you never get, start wit [FREE Azure account](https://aka.ms/azure-free-account). ## Learning with GitHub Copilot -To quick start writing your code, open dis project for one GitHub Codespace or for your local IDE wit di devcontainer wey dem give. Di devcontainer wey dem use for dis course don ready wit GitHub Copilot for AI paired programming. +To start coding quick quick, open dis project inside GitHub Codespace or your local IDE with di devcontainer wey dem provide. Di devcontainer wey dis course use don already set GitHub Copilot for AI paired programming. + +Each code example get suggested questions wey you fit ask GitHub Copilot to understand better. Look out for di 💡/🤖 prompts for: -Every code example get questions wey you fit ask GitHub Copilot to make you understand better. Look for di 💡/🤖 signs for: +- **Java file headers** - Questions wey dey for each example +- **Module READMEs** - Exploration prompts after di code examples -- **Java file headers** - Questions wey dey particular to each example -- **Module READMEs** - Exploration prompts after code examples +**How to use am:** Open any code file and ask Copilot di suggested questions. E sabi all about di codebase and fit explain, add more, and suggest other options. -**How to use:** Open any code file and ask Copilot di questions wey dem suggest. E get full idea of di codebase and fit explain, add more, or suggest other options. +You wan learn more? Check [Copilot for AI Paired Programming](https://aka.ms/GitHubCopilotAI). -You want sabi more? Check [Copilot for AI Paired Programming](https://aka.ms/GitHubCopilotAI). ## Additional Resources @@ -128,11 +129,11 @@ You want sabi more? Check [Copilot for AI Paired Programming](https://aka.ms/Git ## Getting Help -If you get stuck or get question about how to build AI apps, abeg join: +If you get stuck or get any questions about how to build AI apps, join: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -If you get product feedback or wahala when you dey build, commot go: +If you get product feedback or errors as you dey build, waka go: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) @@ -143,6 +144,6 @@ MIT License - See [LICENSE](../../LICENSE) file for details. --- -**Disclaimer**: -Dis document don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even tho we dey try make am correct, abeg sabi say automated translation fit get wahala or mistake. Di original document for im own language na di main correct source. For important tin dem, e better make person wey sabi translate human translate am. We no go responsible for any wrong understanding or wrong meaning wey fit show from dis translation. +**Disclaimer**: +Dis document don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even tho we dey try make am correct, abeg make you know say automated translation fit get errors or mistakes. Di original document for dia own language na im be di correct source. For important info, make person wey sabi human translation do am. We no go responsible for any misunderstanding or wrong understanding wey fit happen because of dis translation. \ No newline at end of file diff --git a/translations/pcm/docs/GLOSSARY.md b/translations/pcm/docs/GLOSSARY.md index 0c1108123..9ae993f8a 100644 --- a/translations/pcm/docs/GLOSSARY.md +++ b/translations/pcm/docs/GLOSSARY.md @@ -2,45 +2,45 @@ ## Table of Contents -- [Core Concepts](../../../docs) -- [LangChain4j Components](../../../docs) -- [AI/ML Concepts](../../../docs) -- [Guardrails](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agents and Tools](../../../docs) -- [Agentic Module](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure Services](../../../docs) -- [Testing and Development](../../../docs) - -Quick reference for terms and concepts wey dem dey use for di whole course. +- [Core Concepts](#core-concepts) +- [LangChain4j Components](#langchain4j-components) +- [AI/ML Concepts](#aiml-concepts) +- [Guardrails](#guardrails) +- [Prompt Engineering](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agents and Tools](#agents-and-tools---module-04) +- [Agentic Module](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure Services](#azure-services---module-01) +- [Testing and Development](#testing-and-development---testing-guide) + +Quick reference for terms and concepts wey dem use throughout di course. ## Core Concepts -**AI Agent** - System wey dey use AI to reason and to act on e own. [Module 04](../04-tools/README.md) +**AI Agent** - System wey dey use AI take reason and act on im own. [Module 04](../04-tools/README.md) -**Chain** - Sequence of operations wey di output go enter di next step. +**Chain** - Sequence of operations wey output dey feed into di next step. -**Chunking** - Breaking documents into small small pieces. Typical: 300-500 tokens wit overlap. [Module 03](../03-rag/README.md) +**Chunking** - Breaking documents into smaller pieces dem. Typical: 300-500 tokens wit overlap. [Module 03](../03-rag/README.md) **Context Window** - Maximum tokens wey model fit process. GPT-5.2: 400K tokens (up to 272K input, 128K output). -**Embeddings** - Number vectors wey represent wetin text mean. [Module 03](../03-rag/README.md) +**Embeddings** - Numerical vectors wey dey represent text meaning. [Module 03](../03-rag/README.md) **Function Calling** - Model dey generate structured requests to call external functions. [Module 04](../04-tools/README.md) -**Hallucination** - When models dem generate wrong but e fit look like correct information. +**Hallucination** - When models dey generate wrong but e fit make sense information. -**Prompt** - Text wey you enter for language model. [Module 02](../02-prompt-engineering/README.md) +**Prompt** - Text input wey you dey give language model. [Module 02](../02-prompt-engineering/README.md) -**Semantic Search** - Search by meaning using embeddings, no be keywords. [Module 03](../03-rag/README.md) +**Semantic Search** - Search by meaning wey dey use embeddings, no be keywords. [Module 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: no memory. Stateful: e dey remember conversation history. [Module 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: no memory. Stateful: e dey maintain conversation history. [Module 01](../01-introduction/README.md) -**Tokens** - Basic text units wey models dey process. E affect cost and limits. [Module 01](../01-introduction/README.md) +**Tokens** - Basic text units wey models dey process. E dey affect costs and limits. [Module 01](../01-introduction/README.md) -**Tool Chaining** - Sequential tool action wey output dey inform next call. [Module 04](../04-tools/README.md) +**Tool Chaining** - Sequential tool execution wey output dey guide next call. [Module 04](../04-tools/README.md) ## LangChain4j Components @@ -48,7 +48,7 @@ Quick reference for terms and concepts wey dem dey use for di whole course. **OpenAiOfficialChatModel** - Unified client for OpenAI and Azure OpenAI models. -**OpenAiOfficialEmbeddingModel** - E dey create embeddings using OpenAI Official client (e support both OpenAI and Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - E dey create embeddings dey use OpenAI Official client (e support both OpenAI and Azure OpenAI). **ChatModel** - Core interface for language models. @@ -58,67 +58,67 @@ Quick reference for terms and concepts wey dem dey use for di whole course. **DocumentSplitter** - E dey break documents into chunks. -**EmbeddingModel** - E dey convert text to number vectors. +**EmbeddingModel** - E dey convert text into numerical vectors. **EmbeddingStore** - E dey store and retrieve embeddings. **MessageWindowChatMemory** - E dey maintain sliding window of recent messages. -**PromptTemplate** - E dey create reusable prompts wit `{{variable}}` placeholders. +**PromptTemplate** - E dey create reusable prompts with `{{variable}}` placeholders. -**TextSegment** - Text chunk wit metadata. Dem dey use for RAG. +**TextSegment** - Text chunk with metadata. E dey use for RAG. -**ToolExecutionRequest** - E represent tool execution request. +**ToolExecutionRequest** - Na tool execution request e represent. -**UserMessage / AiMessage / SystemMessage** - Conversation message types. +**UserMessage / AiMessage / SystemMessage** - Different types of conversation message. ## AI/ML Concepts -**Few-Shot Learning** - E mean say you go provide examples inside prompts. [Module 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - To provide examples inside prompt. [Module 02](../02-prompt-engineering/README.md) **Large Language Model (LLM)** - AI models wey dem train on plenty text data. -**Reasoning Effort** - GPT-5.2 parameter wey e control how deep di thinkin be. [Module 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - GPT-5.2 parameter wey dey control how deep e go reason. [Module 02](../02-prompt-engineering/README.md) -**Temperature** - E dey control wetin output randomness go be. Low=deterministic, high=creative. +**Temperature** - E dey control how random output go be. Low na deterministic, high na creative. -**Vector Database** - Special database for embeddings. [Module 03](../03-rag/README.md) +**Vector Database** - Specialized database for embeddings. [Module 03](../03-rag/README.md) -**Zero-Shot Learning** - E mean say you no need give example before dem perform task. [Module 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - To perform task without examples. [Module 02](../02-prompt-engineering/README.md) -## Guardrails - [Module 00](../00-quick-start/README.md) +## Guardrails -**Defense in Depth** - Multi-layer security approach wey combine application-level guardrails wit provider safety filters. +**Defense in Depth** - Multi-layer security approach wey combine application-level guardrails with provider safety filters. -**Hard Block** - Provider dey throw HTTP 400 error if content violation strong like dat. +**Hard Block** - Provider go throw HTTP 400 error if content break serious rule. -**InputGuardrail** - LangChain4j interface wey dey check user input before e reach LLM. Na so e save cost and time by blocking bad prompts early. +**InputGuardrail** - LangChain4j interface wey dey validate user input before e reach LLM. E dey save cost and latency by blocking harmful prompts early. -**InputGuardrailResult** - E mean type wey guardrail validation go return: `success()` or `fatal("reason")`. +**InputGuardrailResult** - Na return type for guardrail validation: `success()` or `fatal("reason")`. -**OutputGuardrail** - Interface wey dem dey check AI response before dem return to users. +**OutputGuardrail** - Interface wey validate AI responses before e go return to users. -**Provider Safety Filters** - Built-in content filters from AI providers (like GitHub Models) wey fit catch violations for API level. +**Provider Safety Filters** - Built-in content filters from AI providers (for example Azure OpenAI) wey dey catch violations for API level. -**Soft Refusal** - Model dey politely talk say e no go fit answer without throwing error. +**Soft Refusal** - Model dey politely refuse answer without throwing error. ## Prompt Engineering - [Module 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Step by step reasoning for better accuracy. +**Chain-of-Thought** - Step-by-step reasoning for better accuracy. -**Constrained Output** - To force output follow particular format or structure. +**Constrained Output** - To enforce specific format or structure. -**High Eagerness** - GPT-5.2 pattern wey e dey reason well well. +**High Eagerness** - GPT-5.2 pattern for serious thorough reasoning. -**Low Eagerness** - GPT-5.2 pattern wey e quick answer. +**Low Eagerness** - GPT-5.2 pattern for quick answers. -**Multi-Turn Conversation** - E mean maintaining context for every exchange. +**Multi-Turn Conversation** - To maintain context across multiple exchanges. -**Role-Based Prompting** - To set model personality through system messages. +**Role-Based Prompting** - To set model persona through system messages. -**Self-Reflection** - Model go check and improve e own output. +**Self-Reflection** - Model go check and improve im output. -**Structured Analysis** - Fixed framework for evaluation. +**Structured Analysis** - Fixed evaluation framework. **Task Execution Pattern** - Plan → Execute → Summarize. @@ -126,13 +126,13 @@ Quick reference for terms and concepts wey dem dey use for di whole course. **Document Processing Pipeline** - Load → chunk → embed → store. -**In-Memory Embedding Store** - Storage wey no permanent for testing. +**In-Memory Embedding Store** - Non-persistent storage wey dem dey use for testing. -**RAG** - E combine retrieval with generation to give grounded response. +**RAG** - E combine retrieval with generation to ground responses. -**Similarity Score** - Measure (0-1) of how semantic similarity e be. +**Similarity Score** - Measure (0-1) wey show semantic similarity. -**Source Reference** - Metadata about content wey dem retrieve. +**Source Reference** - Metadata about di content wey dem retrieve. ## Agents and Tools - [Module 04](../04-tools/README.md) @@ -140,83 +140,81 @@ Quick reference for terms and concepts wey dem dey use for di whole course. **ReAct Pattern** - Reason → Act → Observe → Repeat. -**Session Management** - Separate context for different users. +**Session Management** - E dey separate contexts for different users. -**Tool** - Function wey AI agent fit call. +**Tool** - Na function wey AI agent fit call. -**Tool Description** - Documentation of tool purpose and parameters. +**Tool Description** - Documentation about tool purpose and parameters. ## Agentic Module - [Module 05](../05-mcp/README.md) -**@Agent Annotation** - E dey mark interfaces as AI agents wit declarative behavior definition. +**@Agent Annotation** - E dey mark interfaces as AI agents with declarative behavior definition. -**Agent Listener** - Hook wey e dey monitor agent execution through `beforeAgentInvocation()` and `afterAgentInvocation()`. +**Agent Listener** - Hook wey dey monitor agent execution via `beforeAgentInvocation()` and `afterAgentInvocation()`. -**Agentic Scope** - Shared memory wey agents dey store output wit `outputKey` for other agents to use. +**Agentic Scope** - Shared memory wey agents dey store outputs using `outputKey` for downstream agents to use. -**AgenticServices** - Factory wey e dey create agents using `agentBuilder()` and `supervisorBuilder()`. +**AgenticServices** - Factory to create agents dey use `agentBuilder()` and `supervisorBuilder()`. -**Conditional Workflow** - Route wey e depend on conditions to different specialist agents. +**Conditional Workflow** - Route based on conditions go different specialist agents. -**Human-in-the-Loop** - Workflow pattern wey add human checkpoints for approval or content review. +**Human-in-the-Loop** - Workflow pattern wey add human checkpoint for approval or content review. **langchain4j-agentic** - Maven dependency for declarative agent building (experimental). -**Loop Workflow** - E mean to keep iterate agent execution until condition done (e.g., quality score ≥ 0.8). +**Loop Workflow** - To repeat agent execution till condition meet (for example quality score ≥ 0.8). -**outputKey** - Agent annotation parameter wey e tell where results go dey store inside Agentic Scope. +**outputKey** - Agent annotation parameter wey tell where dem go store results inside Agentic Scope. -**Parallel Workflow** - Run many agents at once for independent tasks. +**Parallel Workflow** - To run multiple agents together for independent tasks. -**Response Strategy** - How supervisor go put final answer together: LAST, SUMMARY, or SCORED. +**Response Strategy** - How supervisor go arrange final answer: LAST, SUMMARY, or SCORED. -**Sequential Workflow** - E mean to execute agents in order where output dey flow to next step. +**Sequential Workflow** - To run agents in order wey output flow go next step. -**Supervisor Agent Pattern** - Advanced agentic pattern wey supervisor LLM dey decide dynamically which sub-agents to call. +**Supervisor Agent Pattern** - Advanced agentic pattern wey supervisor LLM go dynamically decide which sub-agents to invoke. ## Model Context Protocol (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - Maven dependency for MCP integration inside LangChain4j. +**langchain4j-mcp** - Maven dependency for MCP integration for LangChain4j. -**MCP** - Model Context Protocol: na standard wey dey connect AI apps to external tools. Build once, fit use everywhere. +**MCP** - Model Context Protocol: na standard to connect AI apps to external tools. Build once, use everywhere. -**MCP Client** - Application wey dey connect to MCP servers to find and use tools. +**MCP Client** - Application wey connect to MCP servers to find and use tools. -**MCP Server** - Service wey dey expose tools via MCP wit clear descriptions and parameter schemas. +**MCP Server** - Service wey expose tools via MCP with clear descriptions and parameter schemas. -**McpToolProvider** - LangChain4j component wey dey wrap MCP tools so AI services and agents fit use am. +**McpToolProvider** - LangChain4j component wey dey wrap MCP tools to use for AI services and agents. -**McpTransport** - Interface for MCP communication. E get implementation like Stdio and HTTP. +**McpTransport** - Interface for MCP communication. Implementation include Stdio and HTTP. -**Stdio Transport** - Local process transport via stdin/stdout. E dey useful for filesystem access or command-line tools. +**Stdio Transport** - Local process transport wey use stdin/stdout. E good for filesystem access or command-line tools. -**StdioMcpTransport** - LangChain4j implementation wey dey spawn MCP server as subprocess. +**StdioMcpTransport** - LangChain4j implementation wey dey launch MCP server as subprocess. -**Tool Discovery** - Client dey ask server for tools wey dey available wit descriptions and schemas. +**Tool Discovery** - Client dey ask server for available tools with descriptions and schemas. ## Azure Services - [Module 01](../01-introduction/README.md) **Azure AI Search** - Cloud search wey get vector capabilities. [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - E deploy Azure resources. +**Azure Developer CLI (azd)** - E dey deploy Azure resources. -**Azure OpenAI** - Microsoft enterprise AI service. +**Azure OpenAI** - Microsoft's enterprise AI service. **Bicep** - Azure infrastructure-as-code language. [Infrastructure Guide](../01-introduction/infra/README.md) -**Deployment Name** - Name wey you go give model deployment for Azure. +**Deployment Name** - Name wey you go take deploy model for Azure. -**GPT-5.2** - Latest OpenAI model wey reason plenti. [Module 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Latest OpenAI model wey get reasoning control. [Module 02](../02-prompt-engineering/README.md) ## Testing and Development - [Testing Guide](TESTING.md) **Dev Container** - Containerized development environment. [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Free AI model playground. [Module 00](../00-quick-start/README.md) +**In-Memory Testing** - Testing wey dey use in-memory storage. -**In-Memory Testing** - Testing wit in-memory storage. - -**Integration Testing** - Testing wit real infrastructure. +**Integration Testing** - Testing with real infrastructure. **Maven** - Java build automation tool. @@ -227,6 +225,6 @@ Quick reference for terms and concepts wey dem dey use for di whole course. --- -**Disclaimer**: -Dis document don translate wit AI translation service wey dem dey call [Co-op Translator](https://github.com/Azure/co-op-translator). Even though we dey try make am correct, abeg sabi say automated translation fit get some errors or wahala. Di original document wey e dey in im own language na im be di correct source. If na serious mata, e beta make person wey sabi translate am well well do am for you. We no go take any blame if pesin misunderstand or use dis translation wrongly. +**Disclaimer**: +Dis document don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even tho we dey try make am correct, abeg make you know say automated translation fit get errors or mistakes. Di original document for dia own language na im be di correct source. For important info, make person wey sabi human translation do am. We no go responsible for any misunderstanding or wrong understanding wey fit happen because of dis translation. \ No newline at end of file diff --git a/translations/pcm/docs/TESTING.md b/translations/pcm/docs/TESTING.md index f078da842..e19fac57a 100644 --- a/translations/pcm/docs/TESTING.md +++ b/translations/pcm/docs/TESTING.md @@ -2,19 +2,19 @@ ## Table of Contents -- [Quick Start](../../../docs) -- [Wet Tin De Tests Cover](../../../docs) -- [How To Run Di Tests](../../../docs) -- [How To Run Tests For VS Code](../../../docs) -- [Testing Patterns](../../../docs) -- [Testing Philosophy](../../../docs) -- [Next Steps](../../../docs) +- [Quick Start](#quick-start) +- [What the Tests Cover](#what-the-tests-cover) +- [Running the Tests](#running-the-tests) +- [Running Tests in VS Code](#running-tests-in-vs-code) +- [Testing Patterns](#testing-patterns) +- [Testing Philosophy](#testing-philosophy) +- [Next Steps](#next-steps) -Dis guide go waka you through di tests wey dem dey use show how to test AI applications without you need API keys or outside services. +Dis guide go carry you waka through di tests wey dey show how to test AI applications without need API keys or outside services. ## Quick Start -Run all di tests wit just one command: +Run all di tests with one command: **Bash:** ```bash @@ -26,30 +26,29 @@ mvn test mvn --% test ``` -When all di tests pass, you go see output like di screenshot below — di tests run wit zero failures. +When all di tests pass, you go see output wey dey like di screenshot below — tests run without any failure. Successful Test Results *Successful test execution showing all tests passing with zero failures* -## Wet Tin De Tests Cover +## What the Tests Cover -Dis course focus on **unit tests** wey dey run for local machine. Each test dey show one LangChain4j idea for isolation. Di testing pyramid below dey show where unit tests fit — dem dey form di fast, reliable foundation wey all your other test strategy base on top. +Dis course focus on **unit tests** wey run locally. Every test go show one LangChain4j concept for isolation. Di testing pyramid wey dey below show where unit tests fit — na dem be di fast, reliable base wey all your test strategy build on. Testing Pyramid -*Testing pyramid wey dey show balance between unit tests (fast, isolated), integration tests (real components), and end-to-end tests. Dis training na for unit testing.* +*Testing pyramid showing di balance between unit tests (fast, isolated), integration tests (real components), and end-to-end tests. Dis training cover unit testing.* | Module | Tests | Focus | Key Files | |--------|-------|-------|-----------| -| **00 - Quick Start** | 6 | Prompt templates and variable substitution | `SimpleQuickStartTest.java` | | **01 - Introduction** | 8 | Conversation memory and stateful chat | `SimpleConversationTest.java` | | **02 - Prompt Engineering** | 12 | GPT-5.2 patterns, eagerness levels, structured output | `SimpleGpt5PromptTest.java` | | **03 - RAG** | 10 | Document ingestion, embeddings, similarity search | `DocumentServiceTest.java` | | **04 - Tools** | 12 | Function calling and tool chaining | `SimpleToolsTest.java` | | **05 - MCP** | 8 | Model Context Protocol with Stdio transport | `SimpleMcpTest.java` | -## How To Run Di Tests +## Running the Tests **Run all di tests from root:** @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Run one test class:** +**Run one single test class:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Run specific test method:** +**Run one specific test method:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#suppose mek e keep di tori wey dem don talk before +mvn test -Dtest=SimpleConversationTest#suppose make dey remember wetin we don yarn before ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#suppose make e dey keep di gist wey dey before +mvn --% test -Dtest=SimpleConversationTest#suppose make e keep di tori wey dem don yarn before ``` -## How To Run Tests For VS Code +## Running Tests in VS Code -If you dey use Visual Studio Code, di Test Explorer get graphic interface wey fit help you run and debug di tests. +If you dey use Visual Studio Code, di Test Explorer go give graphical interface to run and debug tests. VS Code Test Explorer -*VS Code Test Explorer wey dey show di test tree wit all di Java test classes and individual test methods* +*VS Code Test Explorer showing di test tree with all Java test classes and individual test methods* -**To run the tests for VS Code:** +**How to run tests for VS Code:** 1. Open di Test Explorer by clicking di beaker icon for di Activity Bar -2. Expand di test tree to see all modules and test classes -3. Click di play button wey dey next to any test to run am one by one -4. Click "Run All Tests" to run all di suite -5. Right-click any test and choose "Debug Test" to set breakpoints and step through di code +2. Expand di test tree to see all di modules and test classes +3. Click di play button beside any test to run am one-one +4. Click "Run All Tests" to run di whole suite +5. Right-click any test and choose "Debug Test" to set breakpoints and step through code -Di Test Explorer go show green checkmarks if tests pass and go give you detailed failure messages if e fail. +Di Test Explorer go show green checkmarks for di tests wey pass and give detailed failure messages when any test fail. ## Testing Patterns ### Pattern 1: Testing Prompt Templates -Di simplest pattern na to test prompt templates without to call any AI model. You go check if di variable substitution dey work well and confirm say di prompts dey formatted like how you expect am. +Di simplest pattern test prompt templates without calling any AI model. You dey check whether variable substitution dey work well and prompt dem correct. Prompt Template Testing -*Testing prompt templates wey dey show variable substitution flow: template wey get placeholders → values dem apply → formatted output we verify* +*Testing prompt templates showing variable substitution flow: template with placeholders → values applied → formatted output verified* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Dis test dey `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Run am:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatting -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatting -``` +Dis pattern dey verify say variable substitution dey work well and prompt dem format correct — no API key or model call needed. ### Pattern 2: Mocking Language Models -When you dey test conversation logic, use Mockito to create fake models wey go return set responses wey you don arrange before. Dis one dey make tests fast, free, and predictable. +When you dey test conversation logic, use Mockito to make fake models wey return predetermined replies. Dis one make di tests fast, free, and deterministic. Mock vs Real API Comparison -*Comparison wey dey show why mocks dey beta for testing: dem fast, dem no cost anything, dem dey repeat same result, and dem no need API keys* +*Comparison showing why mocks dey preferred for testing: dem dey fast, free, deterministic, and dem no need API keys* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Dis pattern dey for `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Di mock dey make sure say behavior dey consistent so you fit check if memory management work well. +Dis pattern dey `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Di mock dey make sure behaviour consistent so you fit verify memory management dey work well. ### Pattern 3: Testing Conversation Isolation -Conversation memory must keep many users separate. Dis test dey check if conversations no dey mix their contexts. +Conversation memory suppose keep different users separate. Dis test dey check say conversations no dey mix contexts. Conversation Isolation -*Testing conversation isolation wey dey show separate memory stores for different users so no mixing of context* +*Testing conversation isolation showing separate memory stores for different users to prevent context mixing* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Each conversation get e own independent history. For production systems, dis kind isolation na very important for multi-user applications. +Every conversation get im own independent history. For production systems, dis kind isolation na important for multi-user applications. ### Pattern 4: Testing Tools Independently -Tools na functions wey di AI fit call. You test dem direct to make sure dem dey work well no matter how AI go take decide. +Tools na functions wey AI fit call. Test dem directly to make sure dem dey work correct no matter wetin AI decide. Tools Testing -*Testing tools independently wey dey show mock tool execution without AI calls to verify business logic* +*Testing tools independently showing mock tool execution without AI calls to verify business logic* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Dem get dis tests from `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` wey validate tool logic without AI interference. Di chaining example dey show how one tool output dey feed into another input. +Dis tests from `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` dey validate tool logic without AI input. Di chaining example show how one tool output dey enter another tool input. ### Pattern 5: In-Memory RAG Testing -RAG systems dey normally require vector databases plus embedding services. Di in-memory pattern dey allow you test all di pipeline without outside dependencies. +RAG systems normally need vector databases and embedding services. Di in-memory pattern make you fit test di whole pipeline without outside dependencies. In-Memory RAG Testing -*In-memory RAG testing workflow wey dey show document parsing, embedding storage, and similarity search without needing database* +*In-memory RAG testing workflow showing document parsing, embedding storage, and similarity search without requiring a database* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -Dis test from `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` dey create document for memory and verify chunking and metadata management. +Dis test from `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` dey create one document inside memory and verify how e dey chunk and handle metadata. ### Pattern 6: MCP Integration Testing -Di MCP module dey test Model Context Protocol integration using stdio transport. Dem tests dey verify say your app fit spawn and communicate with MCP servers as subprocesses. +Di MCP module dey test Model Context Protocol integration wey use stdio transport. Dem tests go verify say your app fit spawn and communicate with MCP servers as subprocesses. -Di tests wey dey `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` dey validate MCP client behavior. +Tests for `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` dey validate MCP client behaviour. -**Run dem:** +**Run them:** **Bash:** ```bash @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## Testing Philosophy -Test your code, no be AI. Your tests suppose validate di code wey you write by checking how prompts dey build, how memory dey managed, and how tools dey execute. AI response dey change, e no suppose dey part of test assertions. Ask yourself if your prompt template dey correctly substitute variables, no be if AI dey give the correct answer. +Test your code, no be AI. Your tests suppose validate di code wey you write by checking how prompts dem build, how memory dey handle, and how tools dey execute. AI responses dey different every time and no suppose be part of test assertions. Ask yourself if your prompt template correctly substitute variables, no be if AI dey give correct answer. -Use mocks for language models. Dem na external things wey dey slow, expensive and no dey predictable. Mocking dey make tests fast with milliseconds instead of seconds, free without API cost, and predictable with the same result every time. +Use mocks for language models. Dem be outside dependencies wey slow, expensive, and no dey predictable. Mocking dey make tests fast with milliseconds instead of seconds, free with no API money, and deterministic with di same result every time. -Make tests independent. Every test suppose setup im own data, no rely on other tests and clean up after itself. Tests should pass no matter how you run am. +Keep tests independent. Every test suppose set up im own data, no rely on other tests, and clean up after imself. Tests suppose pass no matter di order wey dem run. -Test edge cases way beyond the common way. Try empty inputs, big big inputs, special characters, invalid parameters, and boundary conditions. These ones fit show bugs wey normal usage no go fit show. +Test edge cases wey go beyond di happy path. Try empty inputs, very big inputs, special characters, invalid parameters, and boundary conditions. Dem dey always show bugs wey normal usage no dey expose. -Use descriptive names. Compare `shouldMaintainConversationHistoryAcrossMultipleMessages()` with `test1()`. Di first one go tell you exactly wetin di test mean to test, to make debugging easier. +Use descriptive names. Compare `shouldMaintainConversationHistoryAcrossMultipleMessages()` with `test1()`. Di first one tell you exactly wetin dem dey test, e dey make debugging failure easy. ## Next Steps -Now wey you don understand di testing patterns, you fit dive deep into each module: +Now wey you don understand di testing patterns, dive deeper inside each module: -- **[00 - Quick Start](../00-quick-start/README.md)** - Start wit prompt template basics -- **[01 - Introduction](../01-introduction/README.md)** - Learn conversation memory management -- **[02 - Prompt Engineering](../02/prompt-engineering/README.md)** - Master GPT-5.2 prompting patterns +- **[01 - Introduction](../01-introduction/README.md)** - Learn how to manage conversation memory +- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Master GPT-5.2 prompting patterns - **[03 - RAG](../03-rag/README.md)** - Build retrieval-augmented generation systems - **[04 - Tools](../04-tools/README.md)** - Implement function calling and tool chains - **[05 - MCP](../05-mcp/README.md)** - Integrate Model Context Protocol -Each module README go provide detailed explanations of di concepts tested here. +Every module's README go give detailed tori about the concepts wey dey tested here. --- @@ -358,5 +344,6 @@ Each module README go provide detailed explanations of di concepts tested here. --- -**Disclaimer**: Dis document don translate by AI translation service wey dem dey call [Co-op Translator](https://github.com/Azure/co-op-translator). Even though we dey try make am correct, abeg sabi say automated translation fit get mistakes or no correct well. Di original document for im own language na di correct one wey you suppose trust. If na beta important information, e better make person wey sabi do human translation help you do am. We no go responsible if any misunderstanding or wrong meaning come from dis translation. +**Disclaimer**: +Dis document don translate wit AI translation service [Co-op Translator](https://github.com/Azure/co-op-translator). Even tho we dey try make am correct, abeg make you know say automated translation fit get errors or mistakes. Di original document for dia own language na im be di correct source. For important info, make person wey sabi human translation do am. We no go responsible for any misunderstanding or wrong understanding wey fit happen because of dis translation. \ No newline at end of file diff --git a/translations/pl/.co-op-translator.json b/translations/pl/.co-op-translator.json index 4a02b9489..52d5a6518 100644 --- a/translations/pl/.co-op-translator.json +++ b/translations/pl/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "pl" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T21:38:13+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T10:40:12+00:00", "source_file": "01-introduction/README.md", "language_code": "pl" }, @@ -18,20 +18,20 @@ "language_code": "pl" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T21:40:44+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T10:35:17+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "pl" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T21:42:20+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T10:39:17+00:00", "source_file": "03-rag/README.md", "language_code": "pl" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:53:33+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T10:37:51+00:00", "source_file": "04-tools/README.md", "language_code": "pl" }, @@ -54,8 +54,8 @@ "language_code": "pl" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:04:29+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T10:33:45+00:00", "source_file": "README.md", "language_code": "pl" }, @@ -72,14 +72,14 @@ "language_code": "pl" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T21:46:05+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T10:35:51+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "pl" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T21:46:53+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T10:36:32+00:00", "source_file": "docs/TESTING.md", "language_code": "pl" } diff --git a/translations/pl/00-quick-start/README.md b/translations/pl/00-quick-start/README.md deleted file mode 100644 index 1037e3ceb..000000000 --- a/translations/pl/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Szybki start - -## Spis treści - -- [Wprowadzenie](../../../00-quick-start) -- [Co to jest LangChain4j?](../../../00-quick-start) -- [Zależności LangChain4j](../../../00-quick-start) -- [Wymagania wstępne](../../../00-quick-start) -- [Konfiguracja](../../../00-quick-start) - - [1. Pobierz token GitHub](../../../00-quick-start) - - [2. Ustaw swój token](../../../00-quick-start) -- [Uruchom przykłady](../../../00-quick-start) - - [1. Podstawowy czat](../../../00-quick-start) - - [2. Wzorce promptów](../../../00-quick-start) - - [3. Wywoływanie funkcji](../../../00-quick-start) - - [4. Pytania i odpowiedzi na dokumenty (Easy RAG)](../../../00-quick-start) - - [5. Odpowiedzialna AI](../../../00-quick-start) -- [Co pokazuje każdy przykład](../../../00-quick-start) -- [Kolejne kroki](../../../00-quick-start) -- [Rozwiązywanie problemów](../../../00-quick-start) - -## Wprowadzenie - -Ten szybki start ma na celu jak najszybsze uruchomienie LangChain4j. Obejmuje on absolutne podstawy budowania aplikacji AI z użyciem LangChain4j i modeli GitHub. W kolejnych modułach przejdziesz do Azure OpenAI i GPT-5.2 oraz zagłębisz się w każdy koncept. - -## Co to jest LangChain4j? - -LangChain4j to biblioteka Java, która upraszcza tworzenie aplikacji zasilanych AI. Zamiast zajmować się klientami HTTP i parsowaniem JSON, pracujesz z czystymi API w Javie. - -"Chain" w LangChain oznacza łączenie razem wielu komponentów – możesz łączyć prompt z modelem i z parserem lub łączyć wiele wywołań AI, gdzie wyjście jednego jest wejściem kolejnego. Ten szybki start skupia się na podstawach przed eksploracją bardziej złożonych łańcuchów. - -Koncepcja łańcuchowania LangChain4j - -*Łączenie komponentów w LangChain4j – połączenie bloków budujących potężne przepływy pracy AI* - -Będziemy używać trzech podstawowych komponentów: - -**ChatModel** – interfejs do interakcji z modelem AI. Wywołaj `model.chat("prompt")` i otrzymaj odpowiedź w postaci tekstu. Używamy `OpenAiOfficialChatModel`, który działa z punktami końcowymi kompatybilnymi z OpenAI, takimi jak modele GitHub. - -**AiServices** – tworzy typowane interfejsy usług AI. Definiujesz metody, oznaczasz je za pomocą `@Tool`, a LangChain4j zajmuje się ich orkiestracją. AI automatycznie wywołuje Twoje metody Java kiedy jest to potrzebne. - -**MessageWindowChatMemory** – utrzymuje historię rozmowy. Bez niego każde żądanie jest niezależne. Z nim AI pamięta poprzednie wiadomości i utrzymuje kontekst przez wiele tur. - -Architektura LangChain4j - -*Architektura LangChain4j – rdzeniowe komponenty współpracujące, aby zasilać Twoje aplikacje AI* - -## Zależności LangChain4j - -Ten szybki start używa trzech zależności Maven w pliku [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Moduł `langchain4j-open-ai-official` dostarcza klasę `OpenAiOfficialChatModel`, która łączy się z API kompatybilnymi z OpenAI. Modele GitHub używają tego samego formatu API, więc nie jest potrzebny specjalny adapter – wystarczy wskazać URL bazowy na `https://models.github.ai/inference`. - -Moduł `langchain4j-easy-rag` zapewnia automatyczne dzielenie dokumentów, osadzanie i wyszukiwanie, dzięki czemu możesz budować aplikacje RAG bez manualnej konfiguracji każdego kroku. - -## Wymagania wstępne - -**Używasz kontenera deweloperskiego?** Java i Maven są już zainstalowane. Potrzebujesz tylko tokena dostępu osobistego GitHub. - -**Lokalny rozwój:** -- Java 21+, Maven 3.9+ -- Token dostępu osobistego GitHub (instrukcje poniżej) - -> **Uwaga:** Ten moduł używa `gpt-4.1-nano` z modeli GitHub. Nie zmieniaj nazwy modelu w kodzie – jest skonfigurowany do współpracy z dostępnymi modelami GitHub. - -## Konfiguracja - -### 1. Pobierz token GitHub - -1. Przejdź do [Ustawienia GitHub → Tokeny dostępu osobistego](https://github.com/settings/personal-access-tokens) -2. Kliknij „Wygeneruj nowy token” -3. Ustaw opisową nazwę (np. „LangChain4j Demo”) -4. Ustaw wygaśnięcie (zalecane 7 dni) -5. W sekcji „Uprawnienia konta” znajdź „Models” i ustaw na „Tylko do odczytu” -6. Kliknij „Wygeneruj token” -7. Skopiuj i zapisz swój token – nie będzie go widać ponownie - -### 2. Ustaw swój token - -**Opcja 1: Użycie VS Code (zalecane)** - -Jeśli korzystasz z VS Code, dodaj token do pliku `.env` w katalogu głównym projektu: - -Jeśli plik `.env` nie istnieje, skopiuj `.env.example` do `.env` lub utwórz nowy plik `.env` w katalogu głównym. - -**Przykładowy plik `.env`:** -```bash -# W /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Następnie wystarczy kliknąć prawym przyciskiem myszy dowolny plik demo (np. `BasicChatDemo.java`) w Eksploratorze i wybrać **„Uruchom Java”** lub użyć konfiguracji uruchamiania z panelu Run and Debug. - -**Opcja 2: Użycie terminala** - -Ustaw token jako zmienną środowiskową: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Uruchom przykłady - -**Używając VS Code:** Po prostu kliknij prawym przyciskiem myszy dowolny plik demo w Eksploratorze i wybierz **„Uruchom Java”**, albo skorzystaj z konfiguracji uruchamiania z panelu Run and Debug (upewnij się, że wcześniej dodałeś token do pliku `.env`). - -**Używając Maven:** Alternatywnie możesz uruchomić z linii poleceń: - -### 1. Podstawowy czat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Wzorce promptów - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Pokazuje zero-shot, few-shot, chain-of-thought oraz role-based prompting. - -### 3. Wywoływanie funkcji - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI automatycznie wywołuje Twoje metody Java kiedy jest to potrzebne. - -### 4. Pytania i odpowiedzi na dokumenty (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Zadawaj pytania dotyczące dokumentów używając Easy RAG z automatycznym embeddingiem i wyszukiwaniem. - -### 5. Odpowiedzialna AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Zobacz, jak filtry bezpieczeństwa AI blokują szkodliwe treści. - -## Co pokazuje każdy przykład - -**Podstawowy czat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Zacznij tutaj, aby zobaczyć LangChain4j w najprostszej formie. Stworzysz `OpenAiOfficialChatModel`, wyślesz prompt z `.chat()` i otrzymasz odpowiedź. Pokazuje to podstawy: jak inicjalizować modele z niestandardowymi punktami końcowymi i kluczami API. Kiedy zrozumiesz ten wzorzec, wszystko inne na nim się opiera. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Spróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) i zapytaj: -> - "Jak przełączyć się z modeli GitHub na Azure OpenAI w tym kodzie?" -> - "Jakie inne parametry mogę konfigurować w OpenAiOfficialChatModel.builder()?" -> - "Jak dodać strumieniowanie odpowiedzi zamiast czekać na pełną odpowiedź?" - -**Inżynieria promptów** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Teraz, gdy wiesz jak rozmawiać z modelem, zobacz co do niego mówisz. Ten demo używa tego samego ustawienia modelu, ale pokazuje pięć różnych wzorców promptów. Wypróbuj zero-shot dla bezpośrednich instrukcji, few-shot uczące się na przykładach, chain-of-thought pokazujące kroki rozumowania oraz role-based, które ustalają kontekst. Zobaczysz, jak ten sam model daje diametralnie różne rezultaty w zależności od sposobu sformułowania zapytania. - -Demo także demonstruje szablony promptów, które są potężnym sposobem tworzenia wielokrotnego użytku promptów ze zmiennymi. -Poniższy przykład pokazuje prompt używający LangChain4j `PromptTemplate` do wypełniania zmiennych. AI odpowie bazując na podanym celu i aktywności. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Spróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) i zapytaj: -> - "Jaka jest różnica między zero-shot a few-shot prompting i kiedy używać którego?" -> - "Jak parametr temperature wpływa na odpowiedzi modelu?" -> - "Jakie są techniki zapobiegania atakom typu prompt injection w produkcji?" -> - "Jak tworzyć wielokrotnego użytku obiekty PromptTemplate dla popularnych wzorców?" - -**Integracja narzędzi** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Tu LangChain4j pokazuje swoją moc. Użyjesz `AiServices`, aby stworzyć asystenta AI, który może wywoływać Twoje metody Java. Wystarczy oznaczyć metody `@Tool("opis")`, a LangChain4j zajmie się resztą – AI automatycznie decyduje, kiedy użyć danego narzędzia na podstawie zapytań użytkownika. To demonstruje wywoływanie funkcji, kluczową technikę budowania AI, które może podejmować działania, nie tylko odpowiadać na pytania. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Spróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) i zapytaj: -> - "Jak działa adnotacja @Tool i co LangChain4j robi z nią w tle?" -> - "Czy AI może wywoływać wiele narzędzi po kolei, aby rozwiązywać złożone problemy?" -> - "Co się stanie, jeśli narzędzie wyrzuci wyjątek – jak obsługiwać błędy?" -> - "Jak zintegrować prawdziwe API zamiast tego przykładu kalkulatora?" - -**Pytania i odpowiedzi na dokumenty (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Tu zobaczysz RAG (retrieval-augmented generation) wykorzystujące podejście LangChain4j „Easy RAG”. Dokumenty są ładowane, automatycznie dzielone i osadzane w pamięci, następnie wyszukiwarka dostarcza AI odpowiednie fragmenty podczas zapytania. AI odpowiada na podstawie Twoich dokumentów, nie swojej ogólnej wiedzy. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Spróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) i zapytaj: -> - "Jak RAG zapobiega halucynacjom AI w porównaniu do korzystania z danych treningowych modelu?" -> - "Jaka jest różnica między tym łatwym podejściem a niestandardową pipeline RAG?" -> - "Jak skalować to, aby obsługiwać wiele dokumentów lub większe bazy wiedzy?" - -**Odpowiedzialna AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Buduj bezpieczeństwo AI dzięki obronie wielowarstwowej. W tym demo zobaczysz dwie warstwy ochrony działające razem: - -**Część 1: LangChain4j Input Guardrails** – blokują niebezpieczne prompt’y zanim dotrą do LLM. Twórz własne strażniki sprawdzające zakazane słowa kluczowe lub wzorce. Działają one w Twoim kodzie, więc są szybkie i darmowe. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Część 2: Filtry bezpieczeństwa dostawcy** – Modele GitHub mają wbudowane filtry, które łapią to, co może przeoczyć strażnik. Zobaczysz twarde blokady (błędy HTTP 400) dla poważnych naruszeń oraz miękkie odmowy, gdy AI grzecznie odmawia odpowiedzi. - -> **🤖 Spróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) i zapytaj: -> - "Czym jest InputGuardrail i jak stworzyć własny?" -> - "Jaka jest różnica między twardą blokadą a miękką odmową?" -> - "Dlaczego używać zarówno strażników, jak i filtrów dostawcy razem?" - -## Kolejne kroki - -**Następny moduł:** [01-introduction - Rozpoczęcie pracy z LangChain4j](../01-introduction/README.md) - ---- - -**Nawigacja:** [← Wróć do głównego](../README.md) | [Dalej: Moduł 01 - Wprowadzenie →](../01-introduction/README.md) - ---- - -## Rozwiązywanie problemów - -### Pierwsze kompilacje Maven - -**Problem:** Pierwsze `mvn clean compile` lub `mvn package` trwa długo (10-15 minut) - -**Przyczyna:** Maven musi pobrać wszystkie zależności projektu (Spring Boot, biblioteki LangChain4j, SDK Azure itp.) przy pierwszej kompilacji. - -**Rozwiązanie:** To normalne zachowanie. Kolejne kompilacje będą znacznie szybsze, ponieważ zależności są buforowane lokalnie. Czas pobierania zależy od szybkości Twojego łącza. - -### Składnia poleceń Maven w PowerShell - -**Problem:** Polecenia Maven kończą się błędem `Unknown lifecycle phase ".mainClass=..."` -**Przyczyna**: PowerShell interpretuje `=` jako operator przypisania zmiennej, co psuje składnię właściwości Mavena - -**Rozwiązanie**: Użyj operatora zatrzymania parsowania `--%` przed poleceniem Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operator `--%` nakazuje PowerShell przekazać wszystkie pozostałe argumenty dosłownie do Mavena bez interpretacji. - -### Wyświetlanie emoji w Windows PowerShell - -**Problem**: Odpowiedzi AI pokazują znaki zastępcze (np. `????` lub `â??`) zamiast emoji w PowerShell - -**Przyczyna**: Domyślne kodowanie PowerShell nie obsługuje emoji w UTF-8 - -**Rozwiązanie**: Uruchom to polecenie przed uruchomieniem aplikacji Java: -```cmd -chcp 65001 -``` - -To wymusza kodowanie UTF-8 w terminalu. Alternatywnie, użyj Windows Terminal, który lepiej obsługuje Unicode. - -### Debugowanie wywołań API - -**Problem**: Błędy uwierzytelniania, limity szybkości lub nieoczekiwane odpowiedzi od modelu AI - -**Rozwiązanie**: Przykłady zawierają `.logRequests(true)` i `.logResponses(true)` aby wyświetlać wywołania API w konsoli. Pomaga to w rozwiązywaniu błędów uwierzytelniania, limitów szybkości lub nieoczekiwanych odpowiedzi. Usuń te flagi na produkcji, aby zmniejszyć hałas w logach. - ---- - - -**Zastrzeżenie**: -Niniejszy dokument został przetłumaczony przy użyciu usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mimo że dokładamy wszelkich starań, aby zapewnić poprawność tłumaczenia, prosimy mieć na uwadze, że automatyczne przekłady mogą zawierać błędy lub niedokładności. Oryginalny dokument w języku źródłowym należy uznawać za wiarygodne źródło. W przypadku informacji istotnych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonywanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia. - \ No newline at end of file diff --git a/translations/pl/01-introduction/README.md b/translations/pl/01-introduction/README.md index b279896fc..572f841f5 100644 --- a/translations/pl/01-introduction/README.md +++ b/translations/pl/01-introduction/README.md @@ -1,38 +1,38 @@ -# Moduł 01: Pierwsze kroki z LangChain4j +# Moduł 01: Rozpoczęcie pracy z LangChain4j ## Spis treści -- [Przewodnik wideo](../../../01-introduction) -- [Czego się nauczysz](../../../01-introduction) -- [Wymagania wstępne](../../../01-introduction) -- [Zrozumienie podstawowego problemu](../../../01-introduction) -- [Zrozumienie tokenów](../../../01-introduction) -- [Jak działa pamięć](../../../01-introduction) -- [Jak to wykorzystuje LangChain4j](../../../01-introduction) -- [Wdrożenie infrastruktury Azure OpenAI](../../../01-introduction) -- [Uruchomienie aplikacji lokalnie](../../../01-introduction) -- [Korzystanie z aplikacji](../../../01-introduction) - - [Czat bezstanowy (panel lewy)](../../../01-introduction) - - [Czat stanowy (panel prawy)](../../../01-introduction) -- [Kolejne kroki](../../../01-introduction) - -## Przewodnik wideo +- [Wideo przewodnik](#wideo-przewodnik) +- [Czego się nauczysz](#czego-się-nauczysz) +- [Wymagania wstępne](#wymagania-wstępne) +- [Zrozumienie podstawowego problemu](#zrozumienie-podstawowego-problemu) +- [Zrozumienie tokenów](#zrozumienie-tokenów) +- [Jak działa pamięć](#jak-działa-pamięć) +- [Jak to wykorzystuje LangChain4j](#jak-to-wykorzystuje-langchain4j) +- [Wdrożenie infrastruktury Azure OpenAI](#wdrożenie-infrastruktury-azure-openai) +- [Uruchomienie aplikacji lokalnie](#uruchomienie-aplikacji-lokalnie) +- [Korzystanie z aplikacji](#korzystanie-z-aplikacji) + - [Chat bezstanowy (lewy panel)](#chat-bezstanowy-lewy-panel) + - [Chat ze stanem (prawy panel)](#chat-ze-stanem-prawy-panel) +- [Kolejne kroki](#kolejne-kroki) + +## Wideo przewodnik Obejrzyj tę sesję na żywo, która wyjaśnia, jak zacząć z tym modułem: -Pierwsze kroki z LangChain4j - sesja na żywo +Getting Started with LangChain4j - Live Session ## Czego się nauczysz -W szybkim starcie korzystałeś z modeli GitHub, aby wysyłać prompt, wywoływać narzędzia, budować pipeline RAG oraz testować zabezpieczenia. Te dema pokazały, co jest możliwe — teraz przechodzimy do Azure OpenAI i GPT-5.2 i zaczynamy budować aplikacje produkcyjne. Ten moduł skupia się na konwersacyjnym AI, które pamięta kontekst i utrzymuje stan — to pojęcia, które były używane w demonstracjach szybkiego startu, ale nie zostały wyjaśnione. +To jest Twój punkt startowy z LangChain4j i Azure OpenAI. Zaczynamy od podstaw i zaczynamy budować aplikacje w stylu produkcyjnym. Ten moduł skupia się na konwersacyjnym AI, które zapamiętuje kontekst i utrzymuje stan — to podstawowe pojęcia, na których opierają się wszystkie kolejne moduły. -W całym przewodniku użyjemy GPT-5.2 od Azure OpenAI, ponieważ jego zaawansowane możliwości rozumowania sprawiają, że zachowanie różnych wzorców jest bardziej widoczne. Kiedy dodasz pamięć, wyraźnie zobaczysz różnicę. To ułatwia zrozumienie, co każdy element wnosi do twojej aplikacji. +Przez cały przewodnik będziemy korzystać z GPT-5.2 Azure OpenAI, ponieważ zaawansowane możliwości rozumowania tego modelu sprawiają, że zachowanie różnych wzorców jest bardziej widoczne. Kiedy dodasz pamięć, wyraźnie zobaczysz różnicę. To ułatwia zrozumienie, co każdy komponent wnosi do Twojej aplikacji. -Zbudujesz jedną aplikację, która demonstruje oba wzorce: +Zbudujesz jedną aplikację pokazującą oba wzorce: -**Czat bezstanowy** – Każde zapytanie jest niezależne. Model nie pamięta poprzednich wiadomości. To wzorzec używany w szybkim starcie. +**Chat bezstanowy** - Każde żądanie jest niezależne. Model nie ma pamięci poprzednich wiadomości. To najprostszy punkt startowy. -**Konwersacja stanowa** – Każde zapytanie zawiera historię rozmowy. Model utrzymuje kontekst przez wiele tur. To jest wymagane w aplikacjach produkcyjnych. +**Konwersacja ze stanem** - Każde żądanie zawiera historię konwersacji. Model utrzymuje kontekst przez wiele wymian. To, czego wymagają aplikacje produkcyjne. ## Wymagania wstępne @@ -41,47 +41,47 @@ Zbudujesz jedną aplikację, która demonstruje oba wzorce: - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Uwaga:** Java, Maven, Azure CLI i Azure Developer CLI (azd) są preinstalowane w dostarczonym devcontainerze. +> **Uwaga:** Java, Maven, Azure CLI oraz Azure Developer CLI (azd) są preinstalowane w dostarczonym devcontainerze. -> **Uwaga:** Ten moduł korzysta z GPT-5.2 na Azure OpenAI. Wdrożenie jest konfigurowane automatycznie przez `azd up` – nie modyfikuj nazwy modelu w kodzie. +> **Uwaga:** Ten moduł używa GPT-5.2 na Azure OpenAI. Wdrożenie jest konfigurowane automatycznie przez `azd up` — nie zmieniaj nazwy modelu w kodzie. ## Zrozumienie podstawowego problemu -Modele językowe są bezstanowe. Każde wywołanie API jest niezależne. Jeśli wyślesz „Nazywam się John”, a potem zapytasz „Jak mam na imię?”, model nie ma pojęcia, że właśnie się przedstawiłeś. Traktuje każde zapytanie tak, jakby to była twoja pierwsza rozmowa. +Modele językowe są bezstanowe. Każde wywołanie API jest niezależne. Jeśli wyślesz „Mam na imię John”, a potem zapytasz „Jak mam na imię?”, model nie ma pojęcia, że się przedstawiłeś. Traktuje każde żądanie, jakby to była pierwsza rozmowa, jaką kiedykolwiek prowadziłeś. -To wystarcza do prostych pytań i odpowiedzi, ale jest bezużyteczne dla prawdziwych aplikacji. Boty obsługi klienta muszą pamiętać, co im powiedziałeś. Asystenci osobisci potrzebują kontekstu. Każda rozmowa wieloturnowa wymaga pamięci. +To jest w porządku dla prostych Q&A, ale bezużyteczne dla rzeczywistych aplikacji. Boty obsługi klienta muszą pamiętać, co im powiedziałeś. Osobiste asystenty potrzebują kontekstu. Każda konwersacja wieloetapowa wymaga pamięci. -Poniższy diagram kontrastuje oba podejścia – po lewej wywołanie bezstanowe, które zapomina twoje imię; po prawej wywołanie stanowe wspierane przez ChatMemory, które je pamięta. +Poniższy diagram przedstawia kontrast dwóch podejść — po lewej wywołanie bezstanowe, które zapomina Twoje imię; po prawej wywołanie ze stanem wspierane przez ChatMemory, które je pamięta. -Rozmowy bezstanowe vs stanowe +Stateless vs Stateful Conversations -*Różnica między rozmowami bezstanowymi (niezależnymi wywołaniami) a stanowymi (świadomymi kontekstu)* +*Różnica między konwersacjami bezstanowymi (niezależne wywołania) a ze stanem (świadome kontekstu)* ## Zrozumienie tokenów -Zanim zanurkujesz w rozmowy, ważne jest, aby zrozumieć tokeny – podstawowe jednostki tekstu, które przetwarzają modele językowe: +Zanim zagłębimy się w rozmowy, ważne jest zrozumienie tokenów — podstawowych jednostek tekstu przetwarzanych przez modele językowe: -Wyjaśnienie tokena +Token Explanation -*Przykład rozbicia tekstu na tokeny – "I love AI!" staje się 4 oddzielnymi jednostkami do przetwarzania* +*Przykład, jak tekst jest dzielony na tokeny — "I love AI!" staje się 4 oddzielnymi jednostkami przetwarzania* -Tokeny to sposób, w jaki modele AI mierzą i przetwarzają tekst. Słowa, znaki interpunkcyjne, a nawet spacje mogą być tokenami. Twój model ma limit, ile tokenów może przetworzyć naraz (400 000 dla GPT-5.2, z maksymalnie 272 000 tokenów wejściowych i 128 000 wyjściowych). Zrozumienie tokenów pomaga zarządzać długością rozmowy i kosztami. +Tokeny to sposób, w jaki modele AI mierzą i przetwarzają tekst. Słowa, interpunkcja, a nawet spacje mogą być tokenami. Twój model ma limit, ile tokenów może przetwarzać jednocześnie (400 000 dla GPT-5.2, z maksymalnie 272 000 tokenów wejściowych i 128 000 wyjściowych). Zrozumienie tokenów pomaga zarządzać długością rozmowy i kosztami. ## Jak działa pamięć -Pamięć czatu rozwiązuje problem bezstanowości przez utrzymywanie historii rozmowy. Przed wysłaniem twojego zapytania do modelu, framework dodaje na początek odpowiednie poprzednie wiadomości. Gdy zapytasz „Jak mam na imię?”, system rzeczywiście wysyła całą historię rozmowy, pozwalając modelowi zobaczyć, że wcześniej powiedziałeś „Nazywam się John”. +Pamięć czatu rozwiązuje problem bezstanu poprzez utrzymywanie historii konwersacji. Zanim wyślesz żądanie do modelu, framework dołącza odpowiednie wcześniejsze wiadomości. Kiedy pytasz „Jak mam na imię?”, system faktycznie wysyła całą historię konwersacji, pozwalając modelowi zobaczyć, że wcześniej powiedziałeś „Mam na imię John.” -LangChain4j dostarcza implementacje pamięci, które obsługują to automatycznie. Wybierasz, ile wiadomości chcesz przechowywać, a framework zarządza oknem kontekstowym. Poniższy diagram pokazuje, jak MessageWindowChatMemory utrzymuje przesuwne okno ostatnich wiadomości. +LangChain4j dostarcza implementacje pamięci, które obsługują to automatycznie. Wybierasz, ile wiadomości zachować, a framework zarządza oknem kontekstowym. Diagram poniżej pokazuje, jak MessageWindowChatMemory utrzymuje przesuwne okno ostatnich wiadomości. -Koncepcja okna pamięci +Memory Window Concept *MessageWindowChatMemory utrzymuje przesuwne okno ostatnich wiadomości, automatycznie usuwając stare* ## Jak to wykorzystuje LangChain4j -Ten moduł rozszerza szybki start przez integrację Spring Boot i dodanie pamięci konwersacji. Oto jak elementy współpracują: +Ten moduł integruje Spring Boot i dodaje pamięć konwersacji. Oto jak te elementy współgrają: -**Zależności** – Dodaj dwie biblioteki LangChain4j: +**Zależności** - Dodaj dwie biblioteki LangChain4j: ```xml @@ -93,8 +93,8 @@ Ten moduł rozszerza szybki start przez integrację Spring Boot i dodanie pamię langchain4j-open-ai-official ``` - -**Model czatu** – Skonfiguruj Azure OpenAI jako bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): + +**Model czatu** – Skonfiguruj Azure OpenAI jako komponent Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -108,8 +108,8 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { .build(); } ``` - -Builder odczytuje poświadczenia z zmiennych środowiskowych ustawionych przez `azd up`. Ustawienie `baseUrl` na twój punkt końcowy Azure zapewnia działanie klienta OpenAI z Azure OpenAI. + +Builder odczytuje poświadczenia ze zmiennych środowiskowych ustawionych przez `azd up`. Ustawienie `baseUrl` na Twój punkt końcowy Azure sprawia, że klient OpenAI działa z Azure OpenAI. **Pamięć konwersacji** – Śledź historię czatu z MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -123,188 +123,188 @@ memory.add(UserMessage.from("What's my name?")); AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` + +Tworzy pamięć z `withMaxMessages(10)`, aby zachować ostatnie 10 wiadomości. Dodaje wiadomości użytkownika i AI za pomocą specjalnych wrapperów: `UserMessage.from(text)` i `AiMessage.from(text)`. Historia jest pobierana przez `memory.messages()` i wysyłana do modelu. Serwis przechowuje osobne instancje pamięci dla każdego ID konwersacji, umożliwiając wielu użytkownikom jednoczesne prowadzenie rozmów. -Tworzy pamięć z `withMaxMessages(10)`, aby zachować ostatnie 10 wiadomości. Dodaje wiadomości użytkownika i AI za pomocą typowanych wrapperów: `UserMessage.from(text)` i `AiMessage.from(text)`. Pobiera historię z `memory.messages()` i wysyła ją do modelu. Serwis przechowuje oddzielne instancje pamięci dla każdego ID rozmowy, co pozwala na jednoczesne rozmowy wielu użytkowników. - -> **🤖 Wypróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) i zapytaj: -> - "Jak MessageWindowChatMemory decyduje, które wiadomości usunąć, gdy okno jest pełne?" -> - "Czy mogę zaimplementować niestandardowe przechowywanie pamięci używając bazy danych zamiast pamięci operacyjnej?" -> - "Jak dodać podsumowanie do kompresji starej historii rozmowy?" +> **🤖 Spróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) i zapytaj: +> - „Jak MessageWindowChatMemory decyduje, które wiadomości usunąć, gdy okno jest pełne?” +> - „Czy mogę zaimplementować własne przechowywanie pamięci przy użyciu bazy danych zamiast pamięci operacyjnej?” +> - „Jak dodać podsumowywanie, aby skompresować starą historię konwersacji?” -Endpoint czatu bezstanowego pomija całkowicie pamięć – po prostu `chatModel.chat(prompt)`, jak w szybkim starcie. Endpoint stanowy dodaje wiadomości do pamięci, pobiera historię i dołącza ją do każdego zapytania. Ta sama konfiguracja modelu, różne wzorce. +Endpoint chatu bezstanowego omija pamięć — po prostu `chatModel.chat(prompt)`, tak jak w szybkim starcie. Stateful endpoint dodaje wiadomości do pamięci, pobiera historię i dołącza ten kontekst do każdego żądania. Ta sama konfiguracja modelu, różne wzorce. ## Wdrożenie infrastruktury Azure OpenAI -**Bash:** +**Bash:** ```bash cd 01-introduction azd up # Wybierz subskrypcję i lokalizację (zalecane eastus2) ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 01-introduction azd up # Wybierz subskrypcję i lokalizację (zalecane eastus2) ``` + +> **Uwaga:** Jeśli napotkasz błąd timeoutu (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), po prostu uruchom ponownie `azd up`. Zasoby Azure mogą wciąż się wdrażać w tle, a ponowne próby pozwalają zakończyć wdrożenie, gdy zasoby osiągną stan końcowy. -> **Uwaga:** Jeśli wystąpi błąd timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), po prostu uruchom ponownie `azd up`. Zasoby Azure mogą być nadal wdrażane w tle, a ponowna próba pozwoli zakończyć wdrożenie, gdy zasoby osiągną stan terminalny. - -To wykona: -1. Wdrożenie zasobu Azure OpenAI z modelami GPT-5.2 i text-embedding-3-small -2. Automatyczne wygenerowanie pliku `.env` w katalogu głównym projektu z poświadczeniami -3. Ustawienie wszystkich wymaganych zmiennych środowiskowych +To spowoduje: +1. Wdrożenie zasobu Azure OpenAI z modelami GPT-5.2 i text-embedding-3-small +2. Automatyczne wygenerowanie pliku `.env` w katalogu głównym projektu z poświadczeniami +3. Ustawienie wszystkich wymaganych zmiennych środowiskowych -**Masz problemy z wdrożeniem?** Zobacz [README infrastruktury](infra/README.md) dla szczegółowego rozwiązywania problemów, w tym konfliktów nazw subdomen, ręcznych kroków wdrażania w Azure Portal oraz wskazówek dotyczących konfiguracji modelu. +**Masz problemy z wdrożeniem?** Zobacz [Infrastructure README](infra/README.md) z dokładniejszymi instrukcjami rozwiązywania problemów, m.in. konfliktami nazw subdomen, ręcznymi krokami wdrożenia przez Azure Portal i wskazówkami konfiguracyjnymi modelu. -**Sprawdź, czy wdrożenie się powiodło:** +**Sprawdź, czy wdrożenie się powiodło:** -**Bash:** +**Bash:** ```bash cat ../.env # Powinno pokazywać AZURE_OPENAI_ENDPOINT, API_KEY itd. ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Powinno pokazywać AZURE_OPENAI_ENDPOINT, API_KEY, itd. ``` - -> **Uwaga:** Komenda `azd up` automatycznie generuje plik `.env`. Jeśli potrzebujesz go później zaktualizować, możesz albo edytować `.env` ręcznie albo wygenerować go ponownie uruchamiając: -> -> **Bash:** + +> **Uwaga:** Komenda `azd up` automatycznie generuje plik `.env`. Jeśli chcesz go później zaktualizować, możesz edytować `.env` ręcznie lub wygenerować ponownie, uruchamiając: +> +> **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` -> -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` - + ## Uruchomienie aplikacji lokalnie -**Zweryfikuj wdrożenie:** +**Sprawdź wdrożenie:** -Upewnij się, że plik `.env` znajduje się w katalogu głównym z poświadczeniami Azure. Uruchom to z katalogu modułu (`01-introduction/`): +Upewnij się, że plik `.env` istnieje w katalogu głównym z poświadczeniami Azure. Uruchom to z katalogu modułu (`01-introduction/`): -**Bash:** +**Bash:** ```bash -cat ../.env # Powinno wyświetlać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Powinno pokazywać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # Powinno wyświetlać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Powinno pokazać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**Uruchom aplikacje:** + +**Uruchom aplikacje:** **Opcja 1: Korzystanie z Spring Boot Dashboard (zalecane dla użytkowników VS Code)** -Devcontainer zawiera rozszerzenie Spring Boot Dashboard, które zapewnia wizualny interfejs do zarządzania wszystkimi aplikacjami Spring Boot. Znajdziesz go na pasku aktywności po lewej stronie VS Code (ikona Spring Boot). +Kontener deweloperski zawiera rozszerzenie Spring Boot Dashboard, które zapewnia graficzny interfejs do zarządzania wszystkimi aplikacjami Spring Boot. Znajdziesz je na pasku aktywności po lewej stronie VS Code (poszukaj ikony Spring Boot). -W Spring Boot Dashboard możesz: -- Zobaczyć wszystkie dostępne aplikacje Spring Boot w workspace -- Uruchomić/zatrzymać aplikacje jednym kliknięciem -- Przeglądać logi aplikacji w czasie rzeczywistym -- Monitorować status aplikacji +Z poziomu Spring Boot Dashboard możesz: +- Zobaczyć wszystkie dostępne aplikacje Spring Boot w przestrzeni roboczej +- Uruchomić/zatrzymać aplikacje jednym kliknięciem +- Przeglądać logi aplikacji w czasie rzeczywistym +- Monitorować status aplikacji -Kliknij przycisk odtwarzania obok "introduction", aby uruchomić ten moduł, lub uruchom wszystkie moduły naraz. +Po prostu kliknij przycisk odtwarzania obok „introduction”, aby uruchomić ten moduł, lub uruchom wszystkie moduły naraz. Spring Boot Dashboard -*Spring Boot Dashboard w VS Code — uruchamiaj, zatrzymuj i monitoruj wszystkie moduły z jednego miejsca* +*Spring Boot Dashboard w VS Code — uruchamiaj, zatrzymuj i monitoruj wszystkie moduły w jednym miejscu* -**Opcja 2: Korzystanie ze skryptów shell** +**Opcja 2: Korzystanie ze skryptów powłoki** Uruchom wszystkie aplikacje webowe (moduły 01-04): -**Bash:** +**Bash:** ```bash cd .. # Z katalogu głównego ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd .. # Z katalogu głównego .\start-all.ps1 ``` - + Lub uruchom tylko ten moduł: -**Bash:** +**Bash:** ```bash cd 01-introduction ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 01-introduction .\start.ps1 ``` - + Oba skrypty automatycznie ładują zmienne środowiskowe z pliku `.env` w katalogu głównym i zbudują pliki JAR, jeśli jeszcze nie istnieją. -> **Uwaga:** Jeśli wolisz samodzielnie budować wszystkie moduły przed uruchomieniem: -> -> **Bash:** +> **Uwaga:** Jeśli wolisz zbudować wszystkie moduły ręcznie przed uruchomieniem: +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + Otwórz w przeglądarce http://localhost:8080. -**Aby zatrzymać:** +**Aby zatrzymać:** -**Bash:** +**Bash:** ```bash ./stop.sh # Tylko ten moduł # Lub cd .. && ./stop-all.sh # Wszystkie moduły ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # Tylko ten moduł # Lub cd ..; .\stop-all.ps1 # Wszystkie moduły ``` - + ## Korzystanie z aplikacji Aplikacja zapewnia interfejs webowy z dwoma implementacjami czatu obok siebie. -Ekran główny aplikacji +Application Home Screen -*Panel pokazujący oba czaty — prosty czat (bezstanowy) i czat konwersacyjny (stanowy)* +*Panel pokazujący opcje Simple Chat (bezstanowy) i Conversational Chat (ze stanem)* -### Czat bezstanowy (panel lewy) +### Chat bezstanowy (lewy panel) -Wypróbuj najpierw to. Powiedz „Nazywam się John”, a potem natychmiast zapytaj „Jak mam na imię?”. Model tego nie zapamięta, ponieważ każda wiadomość jest niezależna. To demonstruje podstawowy problem integracji modeli językowych – brak kontekstu rozmowy. +Wypróbuj najpierw ten. Zapytaj „Mam na imię John”, a następnie natychmiast „Jak mam na imię?” Model nie zapamięta, ponieważ każda wiadomość jest niezależna. Demonstruje to podstawowy problem integracji prostego modelu językowego — brak kontekstu rozmowy. -Demo czatu bezstanowego +Stateless Chat Demo -*AI nie pamięta twojego imienia z poprzedniej wiadomości* +*AI nie pamięta Twojego imienia z poprzedniej wiadomości* -### Czat stanowy (panel prawy) +### Chat ze stanem (prawy panel) -Teraz spróbuj tę samą sekwencję tutaj. Powiedz „Nazywam się John”, a potem „Jak mam na imię?”. Tym razem pamięta. Różnica to MessageWindowChatMemory – utrzymuje historię rozmowy i dołącza ją do każdego zapytania. Tak działa konwersacyjne AI produkcyjne. +Teraz spróbuj tego samego tutaj. Zapytaj „Mam na imię John”, a potem „Jak mam na imię?” Tym razem pamięta. Różnicą jest MessageWindowChatMemory - utrzymuje historię rozmowy i dołącza ją do każdego żądania. Tak działa produkcyjne AI konwersacyjne. -Demo czatu stanowego +Stateful Chat Demo -*AI pamięta twoje imię z wcześniejszej rozmowy* +*AI pamięta Twoje imię z wcześniejszej części rozmowy* -Oba panele korzystają z tego samego modelu GPT-5.2. Jedyną różnicą jest pamięć. To jasno pokazuje, co pamięć wnosi do twojej aplikacji i dlaczego jest niezbędna w realnych przypadkach użycia. +Oba panele korzystają z tego samego modelu GPT-5.2. Jedyna różnica to pamięć. To jasno pokazuje, co pamięć wnosi do Twojej aplikacji i dlaczego jest niezbędna w rzeczywistych zastosowaniach. ## Kolejne kroki @@ -312,11 +312,11 @@ Oba panele korzystają z tego samego modelu GPT-5.2. Jedyną różnicą jest pam --- -**Nawigacja:** [← Poprzedni: Moduł 00 - szybki start](../00-quick-start/README.md) | [Powrót do głównego](../README.md) | [Następny: Moduł 02 - Inżynieria promptów →](../02-prompt-engineering/README.md) +**Nawigacja:** [← Wróć do głównej](../README.md) | [Następny: Moduł 02 - Inżynieria promptów →](../02-prompt-engineering/README.md) --- -**Zrzeczenie się odpowiedzialności**: -Dokument ten został przetłumaczony za pomocą usługi tłumaczeń AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mimo że dążymy do dokładności, prosimy mieć na uwadze, że automatyczne tłumaczenia mogą zawierać błędy lub nieścisłości. Oryginalny dokument w języku źródłowym powinien być uznawany za autorytatywne źródło. W przypadku informacji krytycznych zaleca się skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia. +**Zastrzeżenie**: +Niniejszy dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Choć dążymy do dokładności, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub niedokładności. Oryginalny dokument w jego języku źródłowym należy uznawać za autorytatywne źródło. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia. \ No newline at end of file diff --git a/translations/pl/02-prompt-engineering/README.md b/translations/pl/02-prompt-engineering/README.md index c5f2e9f91..dc652d4d0 100644 --- a/translations/pl/02-prompt-engineering/README.md +++ b/translations/pl/02-prompt-engineering/README.md @@ -2,100 +2,100 @@ ## Spis treści -- [Film instruktażowy](../../../02-prompt-engineering) -- [Czego się nauczysz](../../../02-prompt-engineering) -- [Wymagania wstępne](../../../02-prompt-engineering) -- [Zrozumienie inżynierii promptów](../../../02-prompt-engineering) -- [Podstawy inżynierii promptów](../../../02-prompt-engineering) - - [Zeroshot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Szablony promptów](../../../02-prompt-engineering) -- [Zaawansowane wzorce](../../../02-prompt-engineering) -- [Uruchom aplikację](../../../02-prompt-engineering) -- [Zrzuty ekranu aplikacji](../../../02-prompt-engineering) -- [Eksploracja wzorców](../../../02-prompt-engineering) - - [Niskie vs wysokie zaangażowanie](../../../02-prompt-engineering) - - [Wykonywanie zadania (nagłówki narzędzi)](../../../02-prompt-engineering) - - [Kod autorefleksyjny](../../../02-prompt-engineering) - - [Analiza strukturalna](../../../02-prompt-engineering) - - [Wielokrotna rozmowa](../../../02-prompt-engineering) - - [Rozumowanie krok po kroku](../../../02-prompt-engineering) - - [Ograniczony wynik](../../../02-prompt-engineering) -- [Czego naprawdę się uczysz](../../../02-prompt-engineering) -- [Kolejne kroki](../../../02-prompt-engineering) - -## Film instruktażowy +- [Przegląd video](#przegląd-video) +- [Czego się nauczysz](#czego-się-nauczysz) +- [Wymagania wstępne](#wymagania-wstępne) +- [Zrozumienie inżynierii promptów](#zrozumienie-inżynierii-promptów) +- [Podstawy inżynierii promptów](#podstawy-inżynierii-promptów) + - [Prompting zero-shot](#prompting-zero-shot) + - [Prompting few-shot](#prompting-few-shot) + - [Chain of Thought](#chain-of-thought) + - [Prompting oparty na roli](#prompting-oparty-na-roli) + - [Szablony promptów](#szablony-promptów) +- [Zaawansowane wzorce](#zaawansowane-wzorce) +- [Uruchom aplikację](#uruchom-aplikację) +- [Zrzuty ekranu aplikacji](#zrzuty-ekranu-aplikacji) +- [Badanie wzorców](#eksploracja-wzorców) + - [Niska vs wysoka chęć](#niskie-vs-wysokie-zaangażowanie-eagerness) + - [Wykonanie zadania (wstępy do narzędzi)](#wykonywanie-zadań-wstępy-narzędziowe) + - [Kod autorefleksyjny](#samorefleksyjny-kod) + - [Analiza strukturalna](#analiza-strukturalna) + - [Czat wieloetapowy](#wielokrotna-rozmowa) + - [Rozumowanie krok po kroku](#rozumowanie-krok-po-kroku) + - [Ograniczona odpowiedź](#wymuszony-wynik) +- [Co naprawdę się uczysz](#czego-naprawdę-się-uczysz) +- [Kolejne kroki](#następne-kroki) + +## Przegląd video Obejrzyj tę sesję na żywo, która wyjaśnia, jak rozpocząć pracę z tym modułem: -Inżynieria promptów z LangChain4j – sesja na żywo +Inżynieria promptów z LangChain4j - sesja na żywo ## Czego się nauczysz -Poniższy diagram przedstawia przegląd kluczowych tematów i umiejętności, które rozwiniesz w tym module — od technik udoskonalania promptów po krok po kroku przebieg pracy, którego będziesz się trzymać. +Poniższy diagram przedstawia przegląd kluczowych tematów i umiejętności, które rozwiniesz w tym module — od technik udoskonalania promptów po krok po kroku przepływ pracy, który będziesz stosować. Czego się nauczysz -W poprzednich modułach zapoznałeś się z podstawowymi interakcjami LangChain4j z modelami GitHub oraz zobaczyłeś, jak pamięć umożliwia konwersacyjne AI z Azure OpenAI. Teraz skupimy się na tym, jak zadajesz pytania — czyli na samych promptach — wykorzystując GPT-5.2 z Azure OpenAI. Sposób, w jaki strukturyzujesz prompt, diametralnie wpływa na jakość uzyskiwanych odpowiedzi. Zaczynamy od przeglądu podstawowych technik promptowania, a potem przechodzimy do ośmiu zaawansowanych wzorców, które w pełni wykorzystują możliwości GPT-5.2. +W poprzednim module zobaczyłeś, jak pamięć umożliwia konwersacyjną sztuczną inteligencję z Azure OpenAI. Teraz skupimy się na tym, jak zadajesz pytania — czyli na samych promptach — korzystając z GPT-5.2 w Azure OpenAI. Sposób, w jaki strukturyzujesz swoje promptsy, znacząco wpływa na jakość otrzymywanych odpowiedzi. Zaczniemy od przeglądu podstawowych technik promptingu, a następnie przejdziemy do ośmiu zaawansowanych wzorców, które w pełni wykorzystują możliwości GPT-5.2. -Użyjemy GPT-5.2, ponieważ wprowadza on kontrolę rozumowania - możesz powiedzieć modelowi, ile ma się zastanawiać przed udzieleniem odpowiedzi. To sprawia, że różne strategie promptowania stają się bardziej widoczne i pomaga zrozumieć, kiedy stosować każde podejście. Skorzystamy też z mniejszych limitów narzuconych przez Azure dla GPT-5.2 w porównaniu do modeli GitHub. +Użyjemy GPT-5.2, ponieważ wprowadza on kontrolę rozumowania - możesz określić, ile myślenia model ma wykonać przed odpowiedzią. To uwidacznia różne strategie promptingu i pomaga zrozumieć, kiedy stosować każdą z nich. ## Wymagania wstępne -- Ukończony moduł 01 (wdrożone zasoby Azure OpenAI) -- Plik `.env` w katalogu głównym z danymi uwierzytelniającymi Azure (stworzony przez `azd up` w moduł 01) +- Ukończony Moduł 01 (wdrożone zasoby Azure OpenAI) +- Plik `.env` w katalogu głównym z poświadczeniami Azure (utworzony przez `azd up` w Module 01) -> **Uwaga:** Jeśli nie ukończyłeś modułu 01, najpierw wykonaj tam instrukcje wdrożenia. +> **Uwaga:** Jeśli nie ukończyłeś Modułu 01, najpierw wykonaj tamte instrukcje wdrożenia. ## Zrozumienie inżynierii promptów -W istocie inżynieria promptów to różnica między niejasnymi a precyzyjnymi instrukcjami, jak pokazuje poniższe porównanie. +W swojej istocie inżynieria promptów to różnica między niejasnymi a precyzyjnymi instrukcjami, jak ilustruje poniższe porównanie. -Co to jest inżynieria promptów? +Czym jest inżynieria promptów? -Inżynieria promptów polega na projektowaniu wprowadzanego tekstu tak, by konsekwentnie uzyskiwać potrzebne wyniki. To nie tylko zadawanie pytań - to strukturyzowanie próśb tak, by model dokładnie rozumiał, czego oczekujesz i jak to dostarczyć. +Inżynieria promptów polega na projektowaniu tekstu wejściowego, który konsekwentnie dostarcza potrzebne wyniki. To nie tylko zadawanie pytań — to strukturyzowanie próśb tak, aby model dokładnie rozumiał, czego chcesz i jak to dostarczyć. -Pomyśl o tym jak o dawaniu instrukcji współpracownikowi. "Napraw błąd" jest niejasne. "Napraw wyjątek null pointer w UserService.java w linii 45, dodając sprawdzenie na null" to już konkret. Modele językowe działają podobnie - specyfika i struktura mają znaczenie. +Pomyśl o tym, jakbyś dawał instrukcje koledze. "Napraw błąd" jest niejasne. "Napraw wyjątek null pointer w UserService.java linia 45, dodając sprawdzenie na null" jest precyzyjne. Modele językowe działają podobnie — chodzi o konkrety i strukturę. -Poniższy diagram pokazuje, jak LangChain4j wpisuje się w ten obraz — łącząc twoje wzorce promptów z modelem poprzez bloki budujące SystemMessage i UserMessage. +Diagram poniżej pokazuje, jak LangChain4j wpisuje się w ten obraz — łącząc wzorce promptów z modelem poprzez elementy konstrukcyjne SystemMessage i UserMessage. Jak LangChain4j pasuje -LangChain4j dostarcza infrastrukturę — połączenia z modelem, pamięć i typy komunikatów — podczas gdy wzorce promptów to po prostu starannie zbudowany tekst przekazywany przez tę infrastrukturę. Kluczowymi elementami są `SystemMessage` (ustawia zachowanie i rolę AI) oraz `UserMessage` (przekazuje twoją rzeczywistą prośbę). +LangChain4j dostarcza infrastrukturę — połączenia z modelem, pamięć i typy wiadomości — podczas gdy wzorce promptów to po prostu starannie ustrukturyzowany tekst, który wysyłasz przez tę infrastrukturę. Kluczowymi elementami są `SystemMessage` (który ustawia zachowanie i rolę AI) oraz `UserMessage` (który niesie Twoją rzeczywistą prośbę). ## Podstawy inżynierii promptów -Pięć podstawowych technik pokazanych poniżej stanowi fundament skutecznej inżynierii promptów. Każda z nich odnosi się do innego aspektu komunikacji z modelami językowymi. +Pięć podstawowych technik pokazanych poniżej stanowi fundament skutecznej inżynierii promptów. Każda dotyczy innego aspektu komunikacji z modelami językowymi. Przegląd pięciu wzorców inżynierii promptów -Zanim zanurzymy się w zaawansowane wzorce tego modułu, zróbmy przegląd pięciu podstawowych technik promptowania. To podstawowe elementy, które każdy inżynier promptów powinien znać. Jeśli już przeszedłeś przez [moduł szybkiego startu](../00-quick-start/README.md#2-prompt-patterns), widziałeś je w praktyce — oto koncepcyjna rama, która za nimi stoi. +Zanim zagłębimy się w zaawansowane wzorce w tym module, przypomnijmy pięć podstawowych technik promptingu. To podstawowe narzędzia, które powinien znać każdy inżynier promptów. -### Zeroshot Prompting +### Prompting zero-shot -Najprostsze podejście: daj modelowi bezpośrednią instrukcję bez przykładów. Model polega całkowicie na swoim treningu, by zrozumieć i wykonać zadanie. Sprawdza się dobrze przy prostych prośbach, gdzie oczekiwane zachowanie jest oczywiste. +Najprostsze podejście: daj modelowi bezpośrednią instrukcję bez przykładów. Model polega całkowicie na swoim treningu, aby zrozumieć i wykonać zadanie. Działa to dobrze przy prostych żądaniach, gdzie oczekiwane zachowanie jest oczywiste. -Zeroshot Prompting +Prompting zero-shot -*Bezpośrednia instrukcja bez przykładów — model wywnioskuje zadanie tylko z instrukcji* +*Bezpośrednia instrukcja bez przykładów — model wywnioskuje zadanie na podstawie samej instrukcji* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); // Odpowiedź: "Pozytywna" ``` - -**Kiedy używać:** Proste klasyfikacje, bezpośrednie pytania, tłumaczenia lub każde zadanie, które model może wykonać bez dodatkowego wsparcia. -### Few-Shot Prompting +**Kiedy używać:** Proste klasyfikacje, bezpośrednie pytania, tłumaczenia lub każde zadanie, które model może wykonać bez dodatkowego prowadzenia. + +### Prompting few-shot -Podaj przykłady, które pokazują wzorzec, jaki chcesz, by model naśladował. Model uczy się oczekiwanego formatu wejścia-wyjścia z twoich przykładów i stosuje go do nowych danych. To znacznie poprawia spójność przy zadaniach, gdzie pożądany format lub zachowanie nie jest oczywiste. +Podaj przykłady, które pokazują wzorzec, jaki chcesz, aby model naśladował. Model uczy się oczekiwanego formatu wejścia i wyjścia z Twoich przykładów i stosuje go do nowych danych. To znacznie poprawia spójność w zadaniach, gdzie pożądany format lub zachowanie nie jest oczywiste. -Few-Shot Prompting +Prompting few-shot -*Nauka na przykładach — model identyfikuje wzorzec i stosuje go do nowych danych* +*Nauka na przykładach — model identyfikuje wzorzec i stosuje go do nowych wejść* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**Kiedy używać:** Niestandardowe klasyfikacje, spójne formatowanie, zadania specyficzne dla dziedziny lub gdy zeroshot daje niespójne wyniki. + +**Kiedy używać:** Niestandardowe klasyfikacje, spójne formatowanie, zadania specyficzne dla domeny lub gdy wyniki zero-shot są niespójne. ### Chain of Thought -Poproś model o pokazanie swojego rozumowania krok po kroku. Zamiast od razu podawać odpowiedź, model rozbija problem i przechodzi przez każdy etap jawnie. Poprawia to dokładność w zadaniach matematycznych, logicznych i wieloetapowych. +Poproś model o pokazanie rozumowania krok po kroku. Zamiast od razu przejść do odpowiedzi, model rozbija problem i explicite przeprowadza przez każdy etap. To poprawia dokładność w zadaniach matematycznych, logicznych i wieloetapowych rozumowaniach. -Chain of Thought Prompting +Prompting Chain of Thought -*Rozumowanie krok po kroku — rozbijanie złożonych problemów na jawne kroki logiczne* +*Rozumowanie krok po kroku — rozbijanie złożonych problemów na jawne logiczne etapy* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Model pokazuje: 15 - 8 = 7, następnie 7 + 12 = 19 jabłek +// Model pokazuje: 15 - 8 = 7, a następnie 7 + 12 = 19 jabłek ``` - -**Kiedy używać:** Problemy matematyczne, zagadki logiczne, debugowanie lub każde zadanie, gdzie pokazanie procesu rozumowania zwiększa dokładność i zaufanie. -### Role-Based Prompting +**Kiedy używać:** Zadania matematyczne, łamigłówki logiczne, debugowanie lub każde zadanie, gdzie pokazanie procesu rozumowania poprawia dokładność i zaufanie. + +### Prompting oparty na roli -Ustaw personę lub rolę dla AI przed zadaniem pytania. To daje kontekst, który kształtuje ton, głębokość i skupienie odpowiedzi. "Architekt oprogramowania" doradzi inaczej niż "młodszy programista" czy "audytor bezpieczeństwa". +Ustaw personę lub rolę AI przed zadaniem pytania. To zapewnia kontekst, który kształtuje ton, głębokość i fokus odpowiedzi. "Architekt oprogramowania" doradzi inaczej niż "młodszy programista" czy "audytor bezpieczeństwa". -Role-Based Prompting +Prompting oparty na roli -*Ustawianie kontekstu i persony — to samo pytanie otrzymuje różne odpowiedzi w zależności od przypisanej roli* +*Ustawianie kontekstu i osoby — to samo pytanie dostaje inną odpowiedź w zależności od przypisanej roli* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**Kiedy używać:** Przeglądy kodu, korepetycje, analizy specyficzne dla dziedziny lub gdy potrzebujesz odpowiedzi dostosowanych do poziomu wiedzy lub perspektywy. + +**Kiedy używać:** Przeglądy kodu, nauczanie, analiza specyficzna dla domeny lub gdy potrzebujesz odpowiedzi dopasowanych do określonego poziomu ekspertyzy lub perspektywy. ### Szablony promptów -Twórz wielokrotnie używalne prompty z zmiennymi zastępczymi. Zamiast pisać nowy prompt za każdym razem, zdefiniuj szablon raz i wypełniaj różne wartości. Klasa `PromptTemplate` LangChain4j ułatwia to ze składnią `{{zmienna}}`. +Twórz wielokrotnego użytku promptsy z zmiennymi placeholderami. Zamiast pisać nowy prompt za każdym razem, zdefiniuj szablon raz i wstawiaj różne wartości. Klasa `PromptTemplate` w LangChain4j ułatwia to z użyciem składni `{{variable}}`. Szablony promptów -*Wielokrotnie używalne prompty z miejscami na zmienne — jeden szablon, wiele zastosowań* +*Wielokrotnego użytku promptsy ze zmiennymi placeholderami — jeden szablon, wiele zastosowań* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**Kiedy używać:** Powtarzalne zapytania z różnymi danymi, wsadowe przetwarzanie, budowanie powtarzalnych przepływów AI lub każda sytuacja, gdzie struktura promptu pozostaje ta sama, ale zmieniają się dane. + +**Kiedy używać:** Powtarzające się zapytania z różnymi danymi wejściowymi, przetwarzanie wsadowe, budowanie wielokrotnego użytku przepływów AI lub każdy scenariusz, w którym struktura promptu jest stała, ale dane się zmieniają. --- -Te pięć podstawowych technik daje solidny zestaw narzędzi do większości zadań promptowania. Reszta tego modułu opiera się na nich, prezentując **osiem zaawansowanych wzorców** wykorzystujących kontrolę rozumowania GPT-5.2, samoocenę i możliwości strukturalnego wyjścia. +Te pięć fundamentów daje solidny zestaw narzędzi do większości zadań promptingu. Reszta tego modułu opiera się na nich, dodając **osiem zaawansowanych wzorców**, które wykorzystują kontrolę rozumowania, samoocenę i możliwość strukturalnej odpowiedzi GPT-5.2. ## Zaawansowane wzorce -Po omówieniu podstaw przejdźmy do ośmiu zaawansowanych wzorców, które czynią ten moduł wyjątkowym. Nie każdy problem wymaga tego samego podejścia. Niektóre pytania potrzebują szybkich odpowiedzi, inne głębokiego namysłu. Niektóre wymagają widocznego rozumowania, inne tylko wyników. Każdy z poniższych wzorców jest zoptymalizowany pod kątem innego scenariusza — a kontrola rozumowania GPT-5.2 jeszcze bardziej uwydatnia różnice. +Po omówieniu podstaw, przejdźmy do ośmiu zaawansowanych wzorców, które czynią ten moduł wyjątkowym. Nie każde problem wymaga tego samego podejścia. Niektóre pytania potrzebują szybkich odpowiedzi, inne głębokiego rozważania. Niektóre potrzebują widocznego rozumowania, inne tylko wyników. Każdy poniższy wzorzec jest zoptymalizowany pod inny scenariusz — a kontrola rozumowania w GPT-5.2 uwydatnia te różnice jeszcze bardziej. -Osiem wzorców promptowania +Osiem wzorców promptingu *Przegląd ośmiu wzorców inżynierii promptów i ich zastosowań* -GPT-5.2 dodaje kolejną warstwę do tych wzorców: *kontrolę rozumowania*. Suwak poniżej pokazuje, jak możesz regulować wysiłek myślowy modelu — od szybkich, bezpośrednich odpowiedzi do głębokiej, dokładnej analizy. +GPT-5.2 dodaje do tych wzorców jeszcze jeden wymiar: *kontrolę rozumowania*. Suwak poniżej pokazuje, jak możesz dostosować wysiłek myślowy modelu — od szybkich, bezpośrednich odpowiedzi po głęboką i dokładną analizę. Kontrola rozumowania w GPT-5.2 -*Kontrola rozumowania GPT-5.2 pozwala określić, ile myślenia powinien wykonać model — od szybkich odpowiedzi do głębokich analiz* +*Kontrola rozumowania w GPT-5.2 pozwala określić, ile myślenia model ma wykonać — od szybkich odpowiedzi po głębokie eksploracje* -**Niskie zaangażowanie (szybkie i skupione)** – Dla prostych pytań, gdzie chcesz szybkich, bezpośrednich odpowiedzi. Model wykonuje minimalne rozumowanie – maksimum 2 kroki. Używaj tego do obliczeń, wyszukiwań lub prostych pytań. +**Niska chęć (Szybko i skupienie)** - Dla prostych pytań, gdy chcesz szybkich, bezpośrednich odpowiedzi. Model wykonuje minimalne rozumowanie - maksymalnie 2 kroki. Używaj tego do obliczeń, wyszukiwań lub prostych pytań. ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> 💡 **Eksploruj z GitHub Copilot:** Otwórz [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) i zapytaj: -> - „Jaka jest różnica między wzorcami niskiego a wysokiego zaangażowania?” -> - „Jak znaczniki XML w promptach pomagają strukturyzować odpowiedź AI?” -> - „Kiedy używać wzorców autorefleksji vs bezpośredniej instrukcji?” -**Wysokie zaangażowanie (głębokie i dokładne)** – Dla złożonych problemów, gdzie chcesz kompleksowej analizy. Model dokładnie bada temat i prezentuje szczegółowe rozumowanie. Używaj tego do projektowania systemów, decyzji architektonicznych lub złożonych badań. +> 💡 **Odkrywaj z GitHub Copilot:** Otwórz [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) i zapytaj: +> - "Jaka jest różnica między wzorcami niskiej chęci a wysokiej chęci promptingu?" +> - "Jak znacznik XML w promptach pomaga ustrukturyzować odpowiedź AI?" +> - "Kiedy stosować wzorce autorefleksji a kiedy bezpośrednie instrukcje?" + +**Wysoka chęć (Głęboko i dokładnie)** - Dla złożonych problemów, gdzie chcesz kompleksowej analizy. Model eksploruje gruntownie i pokazuje szczegółowe rozumowanie. Używaj tego do projektowania systemów, decyzji architektonicznych lub skomplikowanych badań. ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**Wykonywanie zadania (postęp krok po kroku)** – Dla wieloetapowych przepływów pracy. Model przedstawia z góry plan, opisuje każdy krok w trakcie działania, a potem podsumowuje. Używaj do migracji, wdrożeń lub dowolnych procesów wieloetapowych. + +**Wykonanie zadania (Postęp krok po kroku)** - Dla wieloetapowych przepływów pracy. Model dostarcza plan z góry, narrację każdego kroku podczas działania, a następnie podsumowanie. Używaj tego do migracji, implementacji lub każdego procesu wieloetapowego. ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -Chain-of-Thought explicite prosi model o pokazanie procesu rozumowania, co poprawia dokładność w złożonych zadaniach. Rozbicie krok po kroku pomaga zarówno ludziom, jak i AI zrozumieć logikę. -> **🤖 Wypróbuj z czatem [GitHub Copilot](https://github.com/features/copilot):** Zapytaj o ten wzorzec: -> - „Jak dostosować wzorzec wykonywania zadania do długotrwałych operacji?” -> - „Jakie są najlepsze praktyki dotyczące struktury nagłówków narzędzi w produkcyjnych aplikacjach?” -> - „Jak mogę przechwytywać i wyświetlać informacje o postępie w UI?” +Prompting Chain-of-Thought wyraźnie prosi model o pokazanie procesu rozumowania, co poprawia dokładność przy skomplikowanych zadaniach. Podział krok po kroku pomaga zrozumieć logikę zarówno ludziom, jak i AI. -Poniższy diagram ilustruje przepływ pracy Plan → Wykonaj → Podsumuj. +> **🤖 Spróbuj z czatem [GitHub Copilot](https://github.com/features/copilot):** Zapytaj o ten wzorzec: +> - "Jak dostosować wzorzec wykonania zadania do długotrwałych operacji?" +> - "Jakie są najlepsze praktyki strukturyzowania wstępów do narzędzi w aplikacjach produkcyjnych?" +> - "Jak uchwycić i wyświetlać pośrednie aktualizacje postępu w interfejsie użytkownika?" -Wzorzec wykonywania zadania +Diagram poniżej ilustruje ten model Plan → Wykonanie → Podsumowanie. -*Przepływ pracy Plan → Wykonaj → Podsumuj dla wieloetapowych zadań* +Wzorzec wykonania zadania -**Kod autorefleksyjny** – Do generowania kodu gotowego do produkcji. Model tworzy kod zgodny ze standardami produkcyjnymi z właściwą obsługą błędów. Używaj tego podczas budowania nowych funkcji lub usług. +*Plan → Wykonanie → Podsumowanie w przepływach wieloetapowych* + +**Kod autorefleksyjny** - Do generowania kodu o jakości produkcyjnej. Model generuje kod zgodny ze standardami produkcyjnymi z właściwą obsługą błędów. Używaj tego przy budowie nowych funkcji lub usług. ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -Poniższy diagram pokazuje pętlę iteracyjnej poprawy — generuj, oceniaj, identyfikuj słabości i udoskonalaj, aż kod spełni standardy produkcyjne. + +Diagram poniżej przedstawia tę iteracyjną pętlę usprawnień — generuj, oceniaj, identyfikuj słabości i dopracowuj, aż kod spełni standardy produkcyjne. Cykl autorefleksji -*Pętla iteracyjnej poprawy – generowanie, ocena, identyfikacja problemów, ulepszanie, powtarzanie* +*Iteracyjna pętla usprawnień - generuj, oceniaj, identyfikuj problemy, poprawiaj, powtarzaj* -**Analiza strukturalna** – Do spójnej oceny. Model przegląda kod używając stałego schematu (poprawność, praktyki, wydajność, bezpieczeństwo, łatwość utrzymania). Używaj tego do przeglądów kodu lub oceny jakości. +**Analiza strukturalna** - Do spójnej oceny. Model przegląda kod według ustalonego schematu (poprawność, praktyki, wydajność, bezpieczeństwo, łatwość utrzymania). Używaj tego przy przeglądach kodu lub ocenach jakości. ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> **🤖 Wypróbuj z czatem [GitHub Copilot](https://github.com/features/copilot):** Zapytaj o analizę strukturalną: -> - „Jak dostosować ramy analizy do różnych typów przeglądów kodu?” -> - „Jaki jest najlepszy sposób na programowe parsowanie i wykorzystanie strukturalnego wyniku?” -> - „Jak zapewnić spójność poziomów ważności w różnych sesjach przeglądu?” -Poniższy diagram pokazuje, jak ten uporządkowany schemat organizuje przegląd kodu w spójne kategorie z poziomami ważności. +> **🤖 Spróbuj z czatem [GitHub Copilot](https://github.com/features/copilot):** Zapytaj o analizę strukturalną: +> - "Jak dostosować ramy analizy dla różnych typów przeglądów kodu?" +> - "Jak najlepiej parsować i reagować na strukturalną odpowiedź programowo?" +> - "Jak zapewnić spójne poziomy ważności w różnych sesjach przeglądu?" + +Poniższy diagram pokazuje, jak ten strukturalny framework organizuje przegląd kodu w spójne kategorie z poziomami ważności. Wzorzec analizy strukturalnej -*Schemat dla spójnych przeglądów kodu z poziomami ważności* +*Framework do spójnych przeglądów kodu z poziomami ważności* -**Wielokrotna rozmowa** – Do konwersacji wymagających kontekstu. Model pamięta poprzednie wiadomości i na nich bazuje. Używaj do interaktywnych sesji pomocy lub złożonych Q&A. +**Czat wieloetapowy** - Do rozmów wymagających kontekstu. Model pamięta poprzednie wiadomości i buduje na ich podstawie. Używaj do interaktywnych sesji pomocy lub złożonych Q&A. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -Poniższy diagram wizualizuje, jak kontekst rozmowy kumuluje się z każdą turą i jak odnosi się do limitu tokenów modelu. -Pamięć kontekstowa +Diagram poniżej wizualizuje, jak kontekst rozmowy kumuluje się z każdą turą i jak odnosi się do limitu tokenów modelu. + +Pamięć kontekstu + +*Jak kontekst rozmowy rośnie przez wiele tur aż do osiągnięcia limitu tokenów* -*Jak kontekst rozmowy narasta podczas wielu tur aż do osiągnięcia limitu tokenów* -**Rozumowanie krok po kroku** - Dla problemów wymagających widocznej logiki. Model pokazuje explicite rozumowanie dla każdego kroku. Używaj tego do zadań matematycznych, łamigłówek logicznych lub gdy potrzebujesz zrozumieć proces myślenia. +**Rozumowanie krok po kroku** - Dla problemów wymagających jawnej logiki. Model pokazuje explicite rozumowanie dla każdego kroku. Używaj tego do zadań matematycznych, łamigłówek logicznych lub gdy chcesz zrozumieć proces myślenia. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Poniższy diagram ilustruje, jak model dzieli problemy na wyraźne, ponumerowane kroki logiczne. +Diagram poniżej ilustruje, jak model dzieli problemy na jawne, ponumerowane logiczne kroki. -Step-by-Step Pattern +Wzorzec krok po kroku +*Rozbijanie problemów na jawne, logiczne kroki* -*Rozkładanie problemów na wyraźne kroki logiczne* - -**Wymuszony format odpowiedzi** - Dla odpowiedzi z konkretnymi wymaganiami co do formatu. Model ściśle przestrzega zasad formatu i długości. Używaj tego do streszczeń lub gdy potrzebujesz precyzyjnej struktury wyjścia. +**Wymuszony wynik** – dla odpowiedzi o konkretnych wymaganiach dotyczących formatu. Model ściśle przestrzega zasad formatu i długości. Używaj tego do streszczeń lub gdy potrzebujesz precyzyjnej struktury wyjścia. ```java String prompt = """ @@ -419,190 +419,190 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +Poniższy diagram pokazuje, jak ograniczenia kierują modelem, aby wygenerował wynik ściśle zgodny z Twoimi wymaganiami dotyczącymi formatu i długości. -Poniższy diagram pokazuje, jak ograniczenia wymuszają na modelu produkcję odpowiedzi ściśle zgodnej z wymaganiami co do formatu i długości. - -Constrained Output Pattern +Wzór wymuszonego wyniku -*Wymuszanie specyficznego formatu, długości i wymagań strukturalnych* +*Narzucanie konkretnych wymagań dotyczących formatu, długości i struktury* -## Uruchomienie aplikacji +## Uruchom aplikację -**Weryfikacja wdrożenia:** +**Sprawdź wdrożenie:** -Upewnij się, że plik `.env` istnieje w katalogu głównym i zawiera poświadczenia Azure (utworzone podczas Modułu 01). Uruchom to z katalogu modułu (`02-prompt-engineering/`): +Upewnij się, że plik `.env` znajduje się w katalogu głównym z danymi uwierzytelniającymi Azure (utworzony podczas Modułu 01). Uruchom to z katalogu modułu (`02-prompt-engineering/`): -**Bash:** +**Bash:** ```bash -cat ../.env # Powinno wyświetlać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Powinno pokazywać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # Powinno wyświetlać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Powinno pokazywać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Uruchom aplikację:** -> **Uwaga:** Jeśli już uruchomiłeś wszystkie aplikacje używając `./start-all.sh` z katalogu głównego (zgodnie z opisem w Module 01), ten moduł jest już uruchomiony na porcie 8083. Możesz pominąć poniższe polecenia startowe i od razu przejść do http://localhost:8083. +> **Uwaga:** Jeśli już uruchomiłeś wszystkie aplikacje za pomocą `./start-all.sh` z katalogu głównego (jak opisano w Module 01), ten moduł już działa na porcie 8083. Możesz pominąć poniższe polecenia uruchomienia i przejść od razu do http://localhost:8083. **Opcja 1: Korzystanie z Spring Boot Dashboard (zalecane dla użytkowników VS Code)** -Kontener deweloperski zawiera rozszerzenie Spring Boot Dashboard, które zapewnia wizualny interfejs do zarządzania wszystkimi aplikacjami Spring Boot. Znajdziesz je na pasku aktywności po lewej stronie VS Code (ikona Spring Boot). +Kontener deweloperski zawiera rozszerzenie Spring Boot Dashboard, które zapewnia wizualny interfejs do zarządzania wszystkimi aplikacjami Spring Boot. Znajdziesz je na pasku aktywności po lewej stronie VS Code (szukaj ikony Spring Boot). -Z poziomu Spring Boot Dashboard możesz: -- Zobaczyć wszystkie dostępne aplikacje Spring Boot w przestrzeni roboczej -- Uruchamiać/zatrzymywać aplikacje jednym kliknięciem -- Przeglądać logi aplikacji w czasie rzeczywistym +Z poziomu Spring Boot Dashboard możesz: +- Zobaczyć wszystkie dostępne aplikacje Spring Boot w środowisku pracy +- Uruchamiać/zatrzymywać aplikacje jednym kliknięciem +- Podglądać logi aplikacji w czasie rzeczywistym - Monitorować status aplikacji -Wystarczy kliknąć przycisk „play” obok „prompt-engineering”, aby uruchomić ten moduł lub uruchomić wszystkie moduły jednocześnie. +Po prostu kliknij przycisk odtwarzania obok „prompt-engineering”, aby uruchomić ten moduł, lub uruchom wszystkie moduły naraz. Spring Boot Dashboard *Spring Boot Dashboard w VS Code — uruchamiaj, zatrzymuj i monitoruj wszystkie moduły z jednego miejsca* -**Opcja 2: Korzystanie z skryptów shell** +**Opcja 2: Korzystanie ze skryptów powłoki** Uruchom wszystkie aplikacje webowe (moduły 01-04): -**Bash:** +**Bash:** ```bash cd .. # Z katalogu głównego ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd .. # Z katalogu głównego .\start-all.ps1 ``` - + Lub uruchom tylko ten moduł: -**Bash:** +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` - + Oba skrypty automatycznie ładują zmienne środowiskowe z pliku `.env` w katalogu głównym i zbudują pliki JAR, jeśli nie istnieją. -> **Uwaga:** Jeśli wolisz najpierw ręcznie zbudować wszystkie moduły przed uruchomieniem: -> -> **Bash:** +> **Uwaga:** Jeśli wolisz najpierw ręcznie zbudować wszystkie moduły przed uruchomieniem: +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + Otwórz http://localhost:8083 w przeglądarce. **Aby zatrzymać:** -**Bash:** +**Bash:** ```bash -./stop.sh # Ten moduł tylko +./stop.sh # Tylko ten moduł # Lub cd .. && ./stop-all.sh # Wszystkie moduły ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # Tylko ten moduł # Lub cd ..; .\stop-all.ps1 # Wszystkie moduły ``` - + ## Zrzuty ekranu aplikacji -Oto główny interfejs modułu do inżynierii promptów, gdzie możesz eksperymentować ze wszystkimi ośmioma wzorcami obok siebie. +Oto główny interfejs modułu do inżynierii promptów, gdzie możesz eksperymentować z wszystkimi ośmioma wzorcami obok siebie. -Dashboard Home +Ekran główny dashboardu -*Główny panel pokazujący 8 wzorców inżynierii promptów wraz z ich cechami i przypadkami użycia* +*Główny pulpit pokazujący wszystkie 8 wzorców inżynierii promptów wraz z ich cechami i zastosowaniami* ## Eksploracja wzorców -Interfejs webowy pozwala eksperymentować z różnymi strategiami promptowania. Każdy wzorzec rozwiązuje inne problemy – wypróbuj je, aby zobaczyć, kiedy każde podejście się sprawdza. +Interfejs webowy pozwala na eksperymentowanie z różnymi strategiami tworzenia promptów. Każdy wzorzec rozwiązuje inne problemy – wypróbuj je, aby zobaczyć, kiedy każdy sposób się sprawdza. -> **Uwaga: Streaming vs Brak streamingu** — Każda strona wzorca oferuje dwa przyciski: **🔴 Stream Response (Live)** oraz opcję **Bez streamingu**. Streaming wykorzystuje Server-Sent Events (SSE) do wyświetlania tokenów na żywo w trakcie generowania przez model, więc widzisz postęp natychmiast. Opcja bez streamingu czeka na całą odpowiedź przed jej wyświetleniem. Przy promptach wywołujących głębokie rozumowanie (np. High Eagerness, Self-Reflecting Code), wywołanie bez streamingu może trwać bardzo długo – czasem minuty – bez widocznego feedbacku. **Używaj streamingu podczas eksperymentów z zaawansowanymi promptami**, aby widzieć pracę modelu i uniknąć wrażenia, że żądanie się zawiesiło. -> -> **Uwaga: Wymagania przeglądarki** — funkcja streamingu używa Fetch Streams API (`response.body.getReader()`), które wymaga pełnej przeglądarki (Chrome, Edge, Firefox, Safari). Nie działa ona w wbudowanej przeglądarce Simple Browser VS Code, ponieważ jej webview nie obsługuje ReadableStream API. Jeśli korzystasz z Simple Browser, przyciski bez streamingu nadal działają normalnie – tylko przyciski streamingu są dotknięte tym ograniczeniem. Otwórz `http://localhost:8083` w zewnętrznej przeglądarce, aby w pełni korzystać z funkcji. +> **Uwaga: Streaming vs Brak streamingu** — Każda strona wzorca oferuje dwa przyciski: **🔴 Stream Response (Na żywo)** i opcję **Bez streamingu**. Streaming używa Server-Sent Events (SSE), aby wyświetlać tokeny na bieżąco podczas generowania przez model, więc widzisz postęp natychmiast. Opcja bez streamingu czeka na pełną odpowiedź przed wyświetleniem. Dla promptów wywołujących głębokie rozumowanie (np. High Eagerness, Self-Reflecting Code) wywołanie bez streamingu może trwać bardzo długo – czasem minuty – bez żadnej widocznej informacji zwrotnej. **Używaj streamingu podczas eksperymentów z złożonymi promptami**, aby widzieć działanie modelu i uniknąć wrażenia, że żądanie wygasło. +> +> **Uwaga: Wymagania przeglądarki** — Funkcja streamingu korzysta z Fetch Streams API (`response.body.getReader()`), które wymaga pełnej przeglądarki (Chrome, Edge, Firefox, Safari). Nie działa to w wbudowanej w VS Code prostej przeglądarce Simple Browser, ponieważ jej widok internetowy nie wspiera API ReadableStream. Jeśli korzystasz z Simple Browser, przyciski bez streamingu będą działały normalnie – tylko streaming jest ograniczony. Otwórz `http://localhost:8083` w zewnętrznej przeglądarce dla pełnego doświadczenia. -### Niska vs Wysoka gorliwość (Eagerness) +### Niskie vs wysokie zaangażowanie (Eagerness) -Zadaj proste pytanie, np. „Ile to jest 15% z 200?” używając Low Eagerness. Otrzymasz natychmiastową, bezpośrednią odpowiedź. Teraz zapytaj o coś złożonego, np. „Zaprojektuj strategię cache’owania dla API o dużym ruchu” używając High Eagerness. Kliknij **🔴 Stream Response (Live)** i zobacz szczegółowe rozumowanie modelu token po tokenie. Ten sam model, ta sama struktura pytania – ale prompt mówi mu, ile myślenia ma wykonać. +Zadaj proste pytanie, np. „Jaka jest 15% z 200?” używając Niskiego Zaangażowania. Otrzymasz natychmiastową, bezpośrednią odpowiedź. Teraz zadaj coś złożonego, np. „Zaprojektuj strategię cache’owania dla API o dużym ruchu” używając Wysokiego Zaangażowania. Kliknij **🔴 Stream Response (Na żywo)** i obserwuj, jak szczegółowe rozumowanie modelu pojawia się token po tokenie. Ten sam model, ta sama struktura pytania – ale prompt mówi mu, ile ma się zastanawiać. -### Wykonywanie zadań (wstępne instrukcje dla narzędzi) +### Wykonywanie zadań (wstępy narzędziowe) -Wielokrokowe przepływy pracy korzystają na wcześniejszym planowaniu i narracji postępu. Model opisuje, co zrobi, opowiada o każdym kroku, a następnie podsumowuje wyniki. +Wielostopniowe workflowy korzystają z wcześniejszego planowania i narracji postępu. Model przedstawia, co zrobi, opisuje każdy krok, a na końcu podsumowuje wyniki. -### Samooceniający kod +### Samorefleksyjny kod -Spróbuj „Stwórz usługę walidacji email”. Zamiast tylko generować kod i przerywać, model generuje, ocenia zgodnie z kryteriami jakości, identyfikuje słabości i poprawia. Zobaczysz, jak iteruje aż kod spełni standardy produkcyjne. +Wypróbuj „Stwórz serwis walidacji maili”. Zamiast po prostu wygenerować kod i przestać, model generuje, ocenia względem kryteriów jakości, identyfikuje słabości i poprawia. Zobaczysz iteracje aż do spełnienia standardów produkcyjnych. ### Analiza strukturalna -Przeglądy kodu potrzebują spójnych ram oceny. Model analizuje kod używając stałych kategorii (poprawność, praktyki, wydajność, bezpieczeństwo) z poziomami wagi. +Przeglądy kodu potrzebują spójnych ram oceny. Model analizuje kod używając ustalonych kategorii (poprawność, praktyki, wydajność, bezpieczeństwo) z poziomami ważności. -### Czaty wieloetapowe +### Wielokrotna rozmowa -Zapytaj „Co to jest Spring Boot?”, a zaraz potem „Pokaż przykład”. Model pamięta Twoje pierwsze pytanie i daje konkretny przykład Spring Boot. Bez pamięci drugie pytanie byłoby zbyt ogólne. +Zapytaj „Co to jest Spring Boot?”, a następnie od razu „Pokaż mi przykład”. Model pamięta pierwsze pytanie i poda Ci konkretny przykład Spring Boot. Bez pamięci drugie pytanie byłoby zbyt niejasne. ### Rozumowanie krok po kroku -Wybierz problem matematyczny i spróbuj go z Step-by-Step Reasoning i Low Eagerness. Low eagerness szybko daje odpowiedź – szybka, ale nieprzejrzysta. Step-by-step pokazuje każdy krok obliczeń i decyzji. +Wybierz zadanie matematyczne i spróbuj je rozwiązać zarówno z Rozumowaniem krok po kroku, jak i Niskim Zaangażowaniem. Niskie zaangażowanie daje tylko odpowiedź – szybko, ale niejasno. Krok po kroku pokazuje każdy obliczony krok i podjętą decyzję. -### Wymuszony format odpowiedzi +### Wymuszony wynik -Gdy potrzebujesz konkretnych formatów lub limitów słów, ten wzorzec wymusza ścisłą zgodność. Spróbuj wygenerować streszczenie z dokładnie 100 słowami w formacie punktowanym. +Gdy potrzebujesz specyficznych formatów lub liczby słów, ten wzorzec narzuca ścisłą zgodność. Spróbuj wygenerować streszczenie dokładnie 100 słów w formacie punktowanym. ## Czego naprawdę się uczysz **Wysiłek rozumowania zmienia wszystko** -GPT-5.2 pozwala kontrolować wysiłek obliczeniowy przez Twoje promptowanie. Niski wysiłek oznacza szybkie odpowiedzi z minimalną eksploracją. Wysoki wysiłek oznacza, że model poświęca czas na głębokie myślenie. Uczysz się dopasowywać wysiłek do złożoności zadania – nie trać czasu na proste pytania, ale też nie spiesz się przy skomplikowanych decyzjach. +GPT-5.2 pozwala kontrolować wysiłek obliczeniowy poprzez twoje prompty. Niski wysiłek oznacza szybkie odpowiedzi z minimalną eksploracją. Wysoki wysiłek oznacza, że model poświęca czas na głębokie rozmyślanie. Uczysz się dostosowywać wysiłek do złożoności zadania – nie marnuj czasu na proste pytania, ale nie śpiesz się też złożonym decyzjom. **Struktura kieruje zachowaniem** -Zauważyłeś tagi XML w promptach? Nie są one dekoracją. Modele chętniej stosują się do uporządkowanych instrukcji niż do tekstu swobodnego. Gdy potrzebujesz procesów wieloetapowych lub złożonej logiki, struktura pomaga modelowi śledzić, gdzie jest i co następuje dalej. Poniższy diagram rozbija dobrze zbudowany prompt, pokazując jak tagi takie jak ``, ``, ``, ``, i `` organizują instrukcje w klarowne sekcje. +Zauważyłeś tagi XML w promptach? Nie są dekoracją. Modele bardziej niezawodnie wykonują instrukcje, gdy są one ustrukturyzowane niż gdy są w formie swobodnego tekstu. Gdy potrzebujesz procesów wieloetapowych lub złożonej logiki, struktura pomaga modelowi śledzić, gdzie jest i co jest dalej. Poniższy diagram rozkłada dobrze ustrukturyzowany prompt, pokazując, jak tagi takie jak ``, ``, ``, ``, oraz `` organizują twoje instrukcje w czytelne sekcje. -Prompt Structure +Struktura promptu -*Anatomia dobrze zbudowanego promptu z wyraźnymi sekcjami i organizacją w stylu XML* +*Anatomia dobrze ustrukturyzowanego promptu z jasnymi sekcjami i organizacją w stylu XML* **Jakość przez samoocenę** -Wzorce samoocenia działają przez explicite wprowadzenie kryteriów jakości. Zamiast mieć nadzieję, że model „zrobi to poprawnie”, mówisz mu dokładnie, co oznacza „poprawnie”: poprawna logika, obsługa błędów, wydajność, bezpieczeństwo. Model może wtedy ocenić własny output i go ulepszyć. To zmienia generowanie kodu z loterii w proces. +Wzorce samorefleksyjne działają dzięki ujawnieniu kryteriów jakości. Zamiast mieć nadzieję, że model „zrobi to dobrze”, mówisz mu dokładnie, co znaczy „dobrze”: poprawna logika, obsługa błędów, wydajność, bezpieczeństwo. Model może na tej podstawie ocenić swój własny output i go poprawić. To zamienia generowanie kodu z loterii w proces. **Kontekst jest ograniczony** -Rozmowy wieloetapowe działają przez dołączanie historii wiadomości do każdego żądania. Ale jest limit – każdy model ma maksymalną liczbę tokenów. Wraz z rosnącą rozmową musisz stosować strategie, by utrzymać istotny kontekst bez przekraczania limitu. Ten moduł pokazuje, jak działa pamięć; później nauczysz się, kiedy streszczać, kiedy zapominać, a kiedy pobierać. +Wielokrotne rozmowy działają dzięki dołączaniu historii wiadomości do każdego żądania. Ale istnieje limit – każdy model ma maksymalną liczbę tokenów. W miarę rozrostu rozmów, potrzebujesz strategii, aby utrzymać istotny kontekst, nie przekraczając limitu. Ten moduł pokazuje, jak działa pamięć; później nauczysz się, kiedy podsumowywać, kiedy zapominać, a kiedy przywoływać. -## Kolejne kroki +## Następne kroki **Następny moduł:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Nawigacja:** [← Poprzedni: Moduł 01 - Wprowadzenie](../01-introduction/README.md) | [Powrót do głównego](../README.md) | [Następny: Moduł 03 - RAG →](../03-rag/README.md) +**Nawigacja:** [← Poprzedni: Moduł 01 - Wprowadzenie](../01-introduction/README.md) | [Powrót do głównej](../README.md) | [Następny: Moduł 03 - RAG →](../03-rag/README.md) --- -**Zrzeczenie się odpowiedzialności**: -Niniejszy dokument został przetłumaczony przy użyciu usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mimo że dążymy do dokładności, prosimy pamiętać, że tłumaczenia automatyczne mogą zawierać błędy lub niedokładności. Oryginalny dokument w języku źródłowym powinien być uznawany za autorytatywne źródło. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia. +**Zastrzeżenie**: +Niniejszy dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Choć dążymy do dokładności, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub niedokładności. Oryginalny dokument w jego języku źródłowym należy uznawać za autorytatywne źródło. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia. \ No newline at end of file diff --git a/translations/pl/03-rag/README.md b/translations/pl/03-rag/README.md index 9dec264d2..1621aa712 100644 --- a/translations/pl/03-rag/README.md +++ b/translations/pl/03-rag/README.md @@ -2,143 +2,142 @@ ## Spis treści -- [Przewodnik wideo](../../../03-rag) -- [Czego się nauczysz](../../../03-rag) -- [Wymagania wstępne](../../../03-rag) -- [Zrozumienie RAG](../../../03-rag) - - [Którego podejścia RAG używa ten samouczek?](../../../03-rag) -- [Jak to działa](../../../03-rag) - - [Przetwarzanie dokumentów](../../../03-rag) - - [Tworzenie embeddingów](../../../03-rag) - - [Wyszukiwanie semantyczne](../../../03-rag) - - [Generowanie odpowiedzi](../../../03-rag) -- [Uruchom aplikację](../../../03-rag) -- [Korzystanie z aplikacji](../../../03-rag) - - [Prześlij dokument](../../../03-rag) - - [Zadawaj pytania](../../../03-rag) - - [Sprawdź odniesienia źródłowe](../../../03-rag) - - [Eksperymentuj z pytaniami](../../../03-rag) -- [Kluczowe koncepcje](../../../03-rag) - - [Strategia dzielenia na fragmenty](../../../03-rag) - - [Wyniki podobieństwa](../../../03-rag) - - [Przechowywanie w pamięci](../../../03-rag) - - [Zarządzanie oknem kontekstu](../../../03-rag) -- [Kiedy RAG ma znaczenie](../../../03-rag) -- [Kolejne kroki](../../../03-rag) - -## Przewodnik wideo +- [Przegląd wideo](#przegląd-wideo) +- [Czego się nauczysz](#czego-się-nauczysz) +- [Wymagania wstępne](#wymagania-wstępne) +- [Zrozumienie RAG](#zrozumienie-rag) + - [Które podejście RAG jest używane w tym samouczku?](#które-podejście-rag-jest-używane-w-tym-samouczku) +- [Jak to działa](#jak-to-działa) + - [Przetwarzanie dokumentów](#przetwarzanie-dokumentów) + - [Tworzenie osadzeń](#tworzenie-osadzeń) + - [Wyszukiwanie semantyczne](#wyszukiwanie-semantyczne) + - [Generowanie odpowiedzi](#generowanie-odpowiedzi) +- [Uruchom aplikację](#uruchom-aplikację) +- [Korzystanie z aplikacji](#korzystanie-z-aplikacji) + - [Prześlij dokument](#prześlij-dokument) + - [Zadaj pytania](#zadawaj-pytania) + - [Sprawdź odniesienia źródeł](#sprawdź-źródła) + - [Eksperymentuj z pytaniami](#eksperymentuj-z-pytaniami) +- [Kluczowe pojęcia](#kluczowe-pojęcia) + - [Strategia dzielenia na fragmenty](#strategia-dzielenia-na-fragmenty) + - [Wskaźniki podobieństwa](#wyniki-podobieństwa) + - [Przechowywanie w pamięci](#przechowywanie-w-pamięci) + - [Zarządzanie oknem kontekstu](#zarządzanie-oknem-kontekstu) +- [Kiedy RAG ma znaczenie](#kiedy-rag-ma-znaczenie) +- [Następne kroki](#następne-kroki) + +## Przegląd wideo Obejrzyj tę sesję na żywo, która wyjaśnia, jak rozpocząć pracę z tym modułem: -RAG with LangChain4j - Live Session +RAG z LangChain4j - sesja na żywo ## Czego się nauczysz -W poprzednich modułach nauczyłeś się, jak prowadzić rozmowy z AI i jak skutecznie strukturyzować swoje zapytania. Ale istnieje podstawowe ograniczenie: modele językowe wiedzą tylko to, czego nauczyły się podczas treningu. Nie potrafią odpowiedzieć na pytania dotyczące polityk Twojej firmy, dokumentacji projektu ani żadnych informacji, których nie uwzględniono podczas treningu. +W poprzednich modułach nauczyłeś się, jak prowadzić rozmowy ze sztuczną inteligencją i jak skutecznie strukturyzować swoje zapytania. Jednak istnieje fundamentalne ograniczenie: modele językowe znają tylko to, czego nauczyły się podczas treningu. Nie potrafią odpowiadać na pytania dotyczące polityk Twojej firmy, dokumentacji projektowej ani żadnych informacji, których nie uczono ich podczas treningu. -RAG (Retrieval-Augmented Generation) rozwiązuje ten problem. Zamiast próbować nauczyć model Twoich informacji (co jest kosztowne i niepraktyczne), dajesz mu możliwość przeszukiwania dokumentów. Kiedy ktoś zada pytanie, system znajdzie odpowiednie informacje i dołączy je do zapytania. Model odpowie w oparciu o ten pobrany kontekst. +RAG (Retrieval-Augmented Generation) rozwiązuje ten problem. Zamiast próbować nauczyć model informacji o Tobie (co jest kosztowne i niepraktyczne), dajesz mu możliwość przeszukiwania swoich dokumentów. Kiedy ktoś zadaje pytanie, system odnajduje odpowiednie informacje i włącza je do zapytania. Model wtedy odpowiada na podstawie tego uzyskanego kontekstu. -Pomyśl o RAG jak o podarowaniu modelowi biblioteki referencyjnej. Kiedy zadasz pytanie, system: +Pomyśl o RAG jak o udostępnieniu modelowi biblioteki referencyjnej. Gdy zadasz pytanie, system: -1. **Zapytanie użytkownika** - Ty zadajesz pytanie -2. **Embedding** - Zamienia twoje pytanie na wektor -3. **Wyszukiwanie wektorowe** - Znajduje podobne fragmenty dokumentów -4. **Tworzenie kontekstu** - Dodaje odpowiednie fragmenty do zapytania -5. **Odpowiedź** - LLM generuje odpowiedź na podstawie kontekstu +1. **Zapytanie użytkownika** – zadajesz pytanie +2. **Osadzenie (Embedding)** – zamienia twoje pytanie na wektor +3. **Wyszukiwanie wektorowe** – odnajduje podobne fragmenty dokumentów +4. **Składanie kontekstu** – dodaje odpowiednie fragmenty do zapytania +5. **Odpowiedź** – LLM generuje odpowiedź na podstawie kontekstu -Dzięki temu odpowiedzi modelu opierają się na faktycznych danych, a nie na wiedzy zdobytej podczas treningu lub na domysłach. +Dzięki temu odpowiedzi modelu opierają się na twoich faktycznych danych, a nie tylko na wiedzy z treningu czy wymyślonych odpowiedziach. ## Wymagania wstępne -- Ukończony [Moduł 00 - Szybki Start](../00-quick-start/README.md) (dla przykładu Easy RAG, na który jest odniesienie w tym module) -- Ukończony [Moduł 01 - Wprowadzenie](../01-introduction/README.md) (wdrożone zasoby Azure OpenAI, w tym model embeddingowy `text-embedding-3-small`) +- Ukończony [Moduł 01 - Wprowadzenie](../01-introduction/README.md) (zasoby Azure OpenAI wdrożone, w tym model embeddingu `text-embedding-3-small`) - Plik `.env` w katalogu głównym z poświadczeniami Azure (utworzony przez `azd up` w Module 01) -> **Uwaga:** Jeśli nie ukończyłeś Modułu 01, najpierw wykonaj instrukcje wdrożenia tam zawarte. Polecenie `azd up` wdraża zarówno model czatu GPT, jak i model embeddingowy używany w tym module. +> **Uwaga:** Jeśli nie ukończyłeś Modułu 01, najpierw postępuj zgodnie z instrukcjami wdrożenia tam zawartymi. Komenda `azd up` wdraża zarówno model czatu GPT, jak i model embeddingu używany w tym module. ## Zrozumienie RAG -Poniższy diagram ilustruje podstawową koncepcję: zamiast polegać wyłącznie na danych treningowych modelu, RAG dostarcza mu bibliotekę referencyjną Twoich dokumentów, do której może się odwołać przed wygenerowaniem każdej odpowiedzi. +Poniższy diagram ilustruje podstawową koncepcję: zamiast opierać się tylko na danych treningowych modelu, RAG daje mu do konsultacji bibliotekę twoich dokumentów przed generowaniem każdej odpowiedzi. -What is RAG +Co to jest RAG -*Ten diagram pokazuje różnicę między standardowym LLM (który zgaduje na podstawie danych treningowych) a LLM z rozszerzeniem RAG (który najpierw odwołuje się do Twoich dokumentów).* +*Ten diagram pokazuje różnicę między standardowym LLM (który zgaduje na podstawie danych treningowych) a LLM ulepszonym o RAG (który najpierw sięga do twoich dokumentów).* -Oto jak elementy łączą się w całość. Pytanie użytkownika przechodzi przez cztery etapy — embedding, wyszukiwanie wektorowe, składanie kontekstu oraz generowanie odpowiedzi — z których każdy opiera się na poprzednim: +Tak łączą się poszczególne elementy end-to-end. Pytanie użytkownika przechodzi przez cztery etapy — osadzanie, wyszukiwanie wektorowe, składanie kontekstu i generowanie odpowiedzi — każdy opierając się na poprzednim: -RAG Architecture +Architektura RAG -*Ten diagram pokazuje end-to-end pipeline RAG — zapytanie użytkownika przechodzi przez embedding, wyszukiwanie wektorowe, składanie kontekstu i generowanie odpowiedzi.* +*Ten diagram pokazuje pełną pipeline RAG — zapytanie użytkownika przechodzi kolejno przez osadzanie, wyszukiwanie wektorowe, składanie kontekstu i generowanie odpowiedzi.* -W dalszej części tego modułu omówimy każdy etap szczegółowo, z kodem, który możesz uruchomić i modyfikować. +Reszta tego modułu przeprowadza przez każdy etap szczegółowo, z kodem, który możesz uruchomić i zmodyfikować. -### Którego podejścia RAG używa ten samouczek? +### Które podejście RAG jest używane w tym samouczku? -LangChain4j oferuje trzy sposoby implementacji RAG, każdy na innym poziomie abstrakcji. Poniższy diagram porównuje je obok siebie: +LangChain4j oferuje trzy metody implementacji RAG, każda na różnym poziomie abstrakcji. Poniższy diagram porównuje je obok siebie: -Three RAG Approaches in LangChain4j +Trzy podejścia RAG w LangChain4j *Ten diagram porównuje trzy podejścia RAG w LangChain4j — Easy, Native i Advanced — pokazując ich kluczowe komponenty i kiedy stosować każde z nich.* -| Podejście | Co robi | Wady i zalety | +| Podejście | Co robi | Kompromis | |---|---|---| -| **Easy RAG** | Łączy wszystko automatycznie przez `AiServices` i `ContentRetriever`. Adnotujesz interfejs, dołączasz retriever, a LangChain4j obsługuje embedding, wyszukiwanie i składanie promptu w tle. | Minimalna ilość kodu, ale nie widzisz, co dzieje się na każdym etapie. | -| **Native RAG** | Sam wywołujesz model embeddingowy, przeszukujesz magazyn, budujesz prompt i generujesz odpowiedź — krok po kroku, jawnie. | Więcej kodu, ale każdy etap jest widoczny i modyfikowalny. | -| **Advanced RAG** | Używa frameworka `RetrievalAugmentor` z wtyczkami przekształceń zapytań, trasowania, ponownego oceniania i wstrzykiwania zawartości dla produkcyjnych pipeline’ów. | Maksymalna elastyczność, ale znacznie większa złożoność. | +| **Easy RAG** | Automatycznie łączy wszystko przez `AiServices` i `ContentRetriever`. Oznaczasz interfejs, przypisujesz retriever, a LangChain4j zajmuje się embeddingiem, wyszukiwaniem i składaniem promptu za kulisami. | Minimalna ilość kodu, ale nie widzisz, co dzieje się na każdym etapie. | +| **Native RAG** | Sam wywołujesz model embeddingu, przeszukujesz magazyn, tworzysz prompt i generujesz odpowiedź — krok po kroku. | Więcej kodu, ale każdy etap jest widoczny i można go modyfikować. | +| **Advanced RAG** | Używa frameworka `RetrievalAugmentor` z wtyczkami do transformacji zapytań, routerów, ponownego sortowania i wstrzykiwania treści dla systemów produkcyjnych. | Maksymalna elastyczność, ale znacznie bardziej złożone. | -**Ten samouczek używa podejścia Native.** Każdy etap pipeline’u RAG — tworzenie embeddinga zapytania, wyszukiwanie w sklepie wektorowym, składanie kontekstu i generowanie odpowiedzi — jest jawnie zapisany w [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). To celowe: jako materiał do nauki ważniejsze jest, byś widział i rozumiał każdy etap, niż by kod był maksymalnie zminimalizowany. Gdy poczujesz się swobodnie z tym, jak elementy się łączą, możesz przejść do Easy RAG dla szybkich prototypów lub Advanced RAG dla systemów produkcyjnych. +**Ten samouczek używa podejścia Native.** Każdy etap pipeline RAG — osadzanie zapytania, wyszukiwanie w sklepie wektorowym, składanie kontekstu i generowanie odpowiedzi — jest jawnie zapisany w [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). To celowe: jako zasób do nauki ważniejsze jest, abyś widział i rozumiał każdy etap niż minimalizował kod. Gdy już zrozumiesz, jak działają poszczególne elementy, możesz przejść do Easy RAG dla szybkich prototypów lub Advanced RAG dla systemów produkcyjnych. -> **💡 Znasz już Easy RAG z praktyki?** Moduł [Quick Start](../00-quick-start/README.md) zawiera przykład Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), który używa podejścia Easy RAG — LangChain4j automatycznie obsługuje embedding, wyszukiwanie i składanie promptu. Ten moduł idzie krok dalej, rozbijając ten pipeline, abyś mógł zobaczyć i kontrolować każdy etap samodzielnie. +> **💡 Zainteresowany Easy RAG?** LangChain4j oferuje także podejście *Easy RAG*, gdzie `AiServices` i `ContentRetriever` automatycznie zajmują się embeddingiem, wyszukiwaniem i składaniem prompta. Ten moduł wybiera bardziej jawny sposób — otwiera ten pipeline, byś mógł zobaczyć i kontrolować każdy etap samodzielnie. -Poniższy diagram pokazuje pipeline Easy RAG z tego przykładu Quick Start. Zwróć uwagę, jak `AiServices` i `EmbeddingStoreContentRetriever` ukrywają całą złożoność — ładujesz dokument, dołączasz retriever i dostajesz odpowiedzi. Podejście Native w tym module rozbija te ukryte kroki: +Poniższy diagram pokazuje pipeline Easy RAG. Zauważ, jak `AiServices` i `EmbeddingStoreContentRetriever` ukrywają całą złożoność — ładujesz dokument, przypisujesz retriever i dostajesz odpowiedzi. Podejście Native w tym module otwiera każdy z tych ukrytych etapów: -Easy RAG Pipeline - LangChain4j +Pipeline Easy RAG - LangChain4j -*Ten diagram pokazuje pipeline Easy RAG z `SimpleReaderDemo.java`. Porównaj go z podejściem Native używanym w tym module: Easy RAG ukrywa embedding, wyszukiwanie i składanie promptu za `AiServices` i `ContentRetriever` — ładujesz dokument, dołączasz retriever i dostajesz odpowiedzi. Podejście Native w tym module rozbija ten pipeline, więc wywołujesz każdy etap (embedding, wyszukiwanie, składanie kontekstu, generowanie) samodzielnie, z pełną kontrolą i widocznością.* +*Ten diagram pokazuje pipeline Easy RAG. Porównaj go z podejściem Native używanym w tym module: Easy RAG ukrywa embedding, wyszukiwanie i składanie promptu w `AiServices` i `ContentRetriever` — ładujesz dokument, przypisujesz retriever i otrzymujesz odpowiedzi. Podejście Native otwiera ten pipeline, abyś mógł samemu wywoływać każdy etap (embed, search, assemble context, generate), zapewniając pełną widoczność i kontrolę.* ## Jak to działa -Pipeline RAG w tym module dzieli się na cztery etapy, które wykonują się kolejno za każdym razem, gdy użytkownik zada pytanie. Najpierw przesłany dokument jest **parsowany i dzielony na fragmenty** o rozmiarze do zarządzania. Te fragmenty są następnie konwertowane na **wektorowe embeddingi** i przechowywane, by można było je matematycznie porównywać. Gdy przychodzi zapytanie, system wykonuje **wyszukiwanie semantyczne**, by znaleźć najbardziej trafne fragmenty, a na końcu przekazuje je jako kontekst do LLM w celu **generowania odpowiedzi**. Poniższe sekcje przechodzą przez każdy etap z rzeczywistym kodem i diagramami. Zaczynamy od pierwszego kroku. +Pipeline RAG w tym module składa się z czterech etapów wykonywanych kolejno za każdym razem, gdy użytkownik zadaje pytanie. Najpierw przesłany dokument jest **parsowany i dzielony na fragmenty**. Te fragmenty są następnie konwertowane na **wektorowe osadzenia** i przechowywane, aby można było je matematycznie porównać. Gdy przychodzi zapytanie, system przeprowadza **wyszukiwanie semantyczne**, aby znaleźć najbardziej odpowiednie fragmenty, a na koniec przekazuje je do LLM jako kontekst do **generowania odpowiedzi**. Poniższe sekcje przeprowadzają przez każdy etap z rzeczywistym kodem i diagramami. Zacznijmy od pierwszego kroku. ### Przetwarzanie dokumentów [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Kiedy przesyłasz dokument, system go parsuje (PDF lub tekst zwykły), dołącza metadane takie jak nazwa pliku, a następnie dzieli go na fragmenty — mniejsze części mieszczące się komfortowo w oknie kontekstowym modelu. Te fragmenty nakładają się częściowo, aby nie utracić kontekstu na granicach. +Kiedy przesyłasz dokument, system go analizuje (PDF lub zwykły tekst), dodaje metadane takie jak nazwa pliku, a następnie dzieli na fragmenty — mniejsze kawałki, które wygodnie mieszczą się w oknie kontekstu modelu. Te fragmenty lekko się nakładają, aby nie zgubić kontekstu na granicach. ```java -// Przetwórz przesłany plik i zapakuj go w dokument LangChain4j +// Przetwórz przesłany plik i opakuj go w dokument LangChain4j Document document = Document.from(content, metadata); -// Podziel na fragmenty po 300 tokenów z nakładaniem 30 tokenów +// Podziel na fragmenty o długości 300 tokenów z 30-tokenowym nakładaniem się DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Poniższy diagram pokazuje, jak to działa wizualnie. Zauważ, że każdy fragment dzieli część tokenów ze swoimi sąsiadami — nakładka 30 tokenów zapewnia, że żaden ważny kontekst nie zostanie utracony: +Poniższy diagram pokazuje to wizualnie. Zauważ, jak każdy fragment dzieli część tokenów z sąsiednimi — nakładka 30-tokenowa zapewnia, że żaden ważny kontekst nie wypadnie między szczelinami: -Document Chunking +Dzielnie dokumentu na fragmenty -*Ten diagram pokazuje dokument dzielony na fragmenty po 300 tokenów z nakładką 30-tokenową, zachowując kontekst na granicach fragmentów.* +*Ten diagram pokazuje dzielenie dokumentu na fragmenty po 300 tokenów z 30-tokenową nakładką, zachowując kontekst na granicach fragmentów.* -> **🤖 Wypróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) i zapytaj: -> - „Jak LangChain4j dzieli dokumenty na fragmenty i dlaczego nakładka jest ważna?” -> - „Jaki jest optymalny rozmiar fragmentu dla różnych typów dokumentów i dlaczego?” -> - „Jak radzić sobie z dokumentami w wielu językach lub ze specjalnym formatowaniem?” +> **🤖 Wypróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) i zapytaj: +> - "Jak LangChain4j dzieli dokumenty na fragmenty i dlaczego nakładka jest ważna?" +> - "Jaki jest optymalny rozmiar fragmentu dla różnych typów dokumentów i dlaczego?" +> - "Jak obsługiwać dokumenty w kilku językach lub ze specjalnym formatowaniem?" -### Tworzenie embeddingów +### Tworzenie osadzeń [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Każdy fragment jest zamieniany na reprezentację numeryczną zwaną embeddingiem — praktycznie konwerter znaczenia na liczby. Model embeddingowy nie jest „inteligentny” jak model czatu; nie potrafi wykonywać instrukcji, rozumować ani odpowiadać na pytania. Potrafi jednak odzwierciedlić tekst w przestrzeni matematycznej, gdzie zbliżone znaczenia znajdują się blisko siebie — „samochód” blisko „automobil”, „polityka zwrotów” blisko „zwróć mi pieniądze”. Pomyśl o modelu czatu jak o osobie, z którą rozmawiasz; model embeddingowy to system archiwizacji na wysokim poziomie. +Każdy fragment jest zamieniany na reprezentację numeryczną zwaną osadzeniem (embeddingiem) — w praktyce to konwerter znaczenia na liczby. Model embeddingowy nie jest „inteligentny” jak model czatu; nie potrafi wykonywać poleceń, wnioskować ani odpowiadać na pytania. Potrafi natomiast przekształcić tekst w przestrzeń matematyczną, w której podobne znaczenia znajdują się blisko siebie — „samochód” blisko „auto”, „polityka zwrotów” blisko „zwróć mi pieniądze”. Pomyśl o modelu czatu jak o osobie, z którą rozmawiasz; model embeddingowy to ultradobry system katalogowy. -Poniższy diagram wizualizuje tę koncepcję — tekst wchodzi, wychodzą wektory liczbowe, a podobne znaczenia dają bliskie wektory: +Poniższy diagram wizualizuje tę koncepcję — tekst wchodzi, wychodzą wektorowe liczby, a podobne znaczenia dają bliskie sobie wektory: -Embedding Model Concept +Koncepcja modelu embeddingowego -*Ten diagram pokazuje, jak model embeddingowy zamienia tekst na numeryczne wektory, umieszczając podobne znaczenia — jak „samochód” i „automobil” — blisko siebie w przestrzeni wektorowej.* +*Ten diagram pokazuje, jak model embeddingowy zamienia tekst na wektory numeryczne, umieszczając podobne znaczenia — jak "samochód" i "auto" — blisko siebie w przestrzeni wektorowej.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Poniższy diagram klas pokazuje dwa oddzielne przebiegi w pipeline RAG oraz klasy LangChain4j, które je implementują. **Przebieg ingestii** (wykonuje się raz przy przesłaniu) dzieli dokument, tworzy embeddingi fragmentów i przechowuje je za pomocą `.addAll()`. **Przebieg zapytania** (wykonuje się za każdym razem, gdy użytkownik pyta) tworzy embedding zapytania, przeszukuje sklep za pomocą `.search()`, i przekazuje dopasowany kontekst do modelu czatu. Oba przebiegi łączy wspólny interfejs `EmbeddingStore`: +Poniższy diagram klas pokazuje dwa oddzielne przepływy w pipeline RAG i klasy LangChain4j, które je realizują. **Przepływ ingestii** (wykonywany raz przy przesłaniu) dzieli dokument, osadza fragmenty i zapisuje je przez `.addAll()`. **Przepływ zapytania** (wykonywany za każdym razem, gdy użytkownik pyta) osadza pytanie, przeszukuje sklep przez `.search()` i przekazuje dopasowany kontekst do modelu czatu. Oba przepływy łączą się w wspólnym interfejsie `EmbeddingStore`: -LangChain4j RAG Classes +Klasy LangChain4j do RAG -*Ten diagram pokazuje dwa przebiegi pipeline RAG — ingestii i zapytania — oraz ich połączenie przez wspólny EmbeddingStore.* +*Ten diagram pokazuje dwa przepływy w pipeline RAG — ingestii i zapytania — i ich połączenie przez wspólny EmbeddingStore.* -Gdy embeddingi są przechowywane, podobne treści naturalnie tworzą klastry w przestrzeni wektorowej. Poniższa wizualizacja pokazuje, jak dokumenty o pokrewnych tematach tworzą pobliskie punkty, co umożliwia wyszukiwanie semantyczne: +Po zapisaniu osadzeń podobne treści naturalnie grupują się w przestrzeni wektorowej. Poniższa wizualizacja pokazuje, jak dokumenty o powiązanych tematach kończą blisko siebie, co umożliwia wyszukiwanie semantyczne: -Vector Embeddings Space +Przestrzeń osadzeń wektorowych -*Ta wizualizacja pokazuje, jak powiązane dokumenty grupują się w przestrzeni wektorowej 3D, z tematami takimi jak Dokumenty Techniczne, Reguły Biznesowe i FAQ tworzącymi odrębne grupy.* +*Ta wizualizacja pokazuje, jak powiązane dokumenty grupują się w trójwymiarowej przestrzeni wektorowej, z tematami takimi jak dokumentacja techniczna, zasady biznesowe i FAQ tworzącymi odrębne grupy.* -Gdy użytkownik wyszukuje, system przechodzi przez cztery kroki: tworzy embedding dokumentów raz, tworzy embedding zapytania przy każdym wyszukiwaniu, porównuje wektor zapytania z wszystkimi przechowywanymi wektorami za pomocą podobieństwa cosinusowego i zwraca najwyżej oceniane top-K fragmenty. Poniższy diagram pokazuje krok po kroku ten proces i klasy LangChain4j zaangażowane w każdy z nich: +Gdy użytkownik przeszukuje, system wykonuje cztery kroki: osadza dokumenty raz, osadza zapytanie przy każdym wyszukiwaniu, porównuje wektor zapytania ze wszystkimi zapisanymi wektorami za pomocą kosinusowej miary podobieństwa oraz zwraca top-K najwyżej ocenionych fragmentów. Poniższy diagram pokazuje każdy krok i klasy LangChain4j, które są zaangażowane: -Embedding Search Steps +Kroki wyszukiwania na bazie osadzeń -*Ten diagram pokazuje czterostopniowy proces wyszukiwania embeddingów: stworzenie embeddingów dokumentów, embedding zapytania, porównanie wektorów za pomocą podobieństwa cosinusowego i zwrócenie top-K wyników.* +*Ten diagram pokazuje czterostopniowy proces wyszukiwania na podstawie osadzeń: osadzanie dokumentów, osadzanie zapytania, porównywanie wektorów za pomocą podobieństwa kosinusowego oraz zwracanie top-K wyników.* ### Wyszukiwanie semantyczne [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Kiedy zadajesz pytanie, twoje pytanie również jest zamieniane na embedding. System porównuje embedding pytania z embeddingami wszystkich fragmentów dokumentów. Znajduje fragmenty o najbardziej zbliżonym znaczeniu - nie tylko dopasowanie słów kluczowych, lecz rzeczywiste podobieństwo semantyczne. +Kiedy zadasz pytanie, twoje pytanie także jest osadzane. System porównuje osadzenie twojego pytania z osadzeniami wszystkich fragmentów dokumentów. Znajduje fragmenty o najbardziej podobnych znaczeniach — nie tylko dopasowując słowa kluczowe, ale faktyczne podobieństwo semantyczne. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Poniższy diagram kontrastuje wyszukiwanie semantyczne z tradycyjnym wyszukiwaniem słów kluczowych. Wyszukiwanie słowa „pojazd” nie znajdzie fragmentu o „samochodach i ciężarówkach”, ale wyszukiwanie semantyczne rozumie, że oznaczają to samo i zwraca go jako wysoko ocenione dopasowanie: +Poniższy diagram kontrastuje wyszukiwanie semantyczne z tradycyjnym wyszukiwaniem słów kluczowych. Wyszukiwanie słowa „pojazd” pomija fragment o „samochodach i ciężarówkach”, ale wyszukiwanie semantyczne rozumie, że to to samo i zwraca go jako dopasowanie o wysokiej ocenie: -Semantic Search +Wyszukiwanie semantyczne -*Ten diagram porównuje wyszukiwanie oparte na słowach kluczowych z wyszukiwaniem semantycznym, pokazując jak to drugie odzyskuje związane konceptualnie treści, nawet gdy dokładne słowa kluczowe się różnią.* -Pod maską, podobieństwo mierzone jest za pomocą podobieństwa kosinusowego — zasadniczo pytając „czy te dwie strzałki wskazują w tym samym kierunku?” Dwa fragmenty mogą używać zupełnie innych słów, ale jeśli znaczą to samo, ich wektory wskazują w tym samym kierunku i wynik jest bliski 1.0: +*Ten diagram porównuje wyszukiwanie na bazie słów kluczowych z wyszukiwaniem semantycznym, pokazując jak semantyczne wyszukiwanie odnajduje treści powiązane koncepcyjnie nawet gdy słowa kluczowe się różnią.* -Cosine Similarity +W praktyce podobieństwo mierzone jest za pomocą podobieństwa kosinusowego — zasadniczo pytając „czy te dwie strzałki wskazują w tym samym kierunku?” Dwa fragmenty mogą używać zupełnie innych słów, ale jeśli znaczą to samo, ich wektory będą skierowane podobnie i uzyskają wynik bliski 1.0: -*Ten diagram ilustruje podobieństwo kosinusowe jako kąt między wektorami osadzeń — bardziej wyrównane wektory zdobywają wynik bliższy 1.0, co wskazuje na wyższe podobieństwo semantyczne.* +Podobieństwo kosinusowe +*Ten diagram ilustruje podobieństwo cosinusowe jako kąt między wektorami osadzeń — wektory bardziej zgrane uzyskują wynik bliższy 1.0, co wskazuje na wyższe podobieństwo semantyczne.* -> **🤖 Spróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) i zapytaj: -> - „Jak działa wyszukiwanie podobieństwa przy użyciu osadzeń i co decyduje o wyniku?” -> - „Jaki próg podobieństwa powinienem użyć i jak wpływa to na wyniki?” -> - „Jak radzić sobie w sytuacjach, gdy nie znaleziono odpowiednich dokumentów?” +> **🤖 Wypróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) i zapytaj: +> - "Jak działa wyszukiwanie podobieństwa z osadzeniami i co determinuje wynik?" +> - "Jaki próg podobieństwa powinienem stosować i jak wpływa na wyniki?" +> - "Jak radzić sobie z przypadkami, gdy nie znaleziono istotnych dokumentów?" ### Generowanie odpowiedzi [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Najbardziej relewantne fragmenty są składane w strukturalny prompt, który zawiera wyraźne instrukcje, pobrany kontekst oraz pytanie użytkownika. Model czyta te konkretne fragmenty i odpowiada na ich podstawie — może używać tylko tego, co ma przed sobą, co zapobiega „halucynacjom”. +Najistotniejsze fragmenty są składane w ustrukturyzowany prompt, który zawiera wyraźne instrukcje, pobrany kontekst oraz pytanie użytkownika. Model czyta te konkretne fragmenty i odpowiada na ich podstawie — może użyć tylko tego, co ma przed sobą, co zapobiega wymyślaniu odpowiedzi. ```java String context = matches.stream() @@ -237,11 +236,11 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Poniższy diagram pokazuje tę składankę w akcji — najwyżej ocenione fragmenty z kroku wyszukiwania są wstrzykiwane do szablonu promptu, a `OpenAiOfficialChatModel` generuje ugruntowaną odpowiedź: +Poniższy diagram pokazuje to składanie w akcji — fragmenty z najwyższymi wynikami z kroku wyszukiwania są wstrzykiwane do szablonu promptu, a `OpenAiOfficialChatModel` generuje ugruntowaną odpowiedź: Context Assembly -*Ten diagram pokazuje, jak najwyżej ocenione fragmenty są składane w strukturalny prompt, pozwalając modelowi na wygenerowanie ugruntowanej odpowiedzi na podstawie twoich danych.* +*Ten diagram pokazuje, jak fragmenty z najwyższymi wynikami są składane w ustrukturyzowany prompt, umożliwiający modelowi wygenerowanie osadzonej odpowiedzi z twoich danych.* ## Uruchom aplikację @@ -251,29 +250,29 @@ Upewnij się, że plik `.env` znajduje się w katalogu głównym i zawiera pośw **Bash:** ```bash -cat ../.env # Powinno wyświetlać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Powinno pokazać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Powinno pokazywać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Powinno wyświetlić AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Uruchom aplikację:** -> **Uwaga:** Jeśli już uruchomiłeś wszystkie aplikacje używając `./start-all.sh` z katalogu głównego (zgodnie z opisem w Module 01), ten moduł działa już na porcie 8081. Możesz pominąć poniższe polecenia startowe i przejść bezpośrednio do http://localhost:8081. +> **Uwaga:** Jeśli już uruchomiłeś wszystkie aplikacje za pomocą `./start-all.sh` z katalogu głównego (zgodnie z opisem w Module 01), ten moduł jest już uruchomiony na porcie 8081. Możesz pominąć poniższe polecenia uruchomienia i przejść bezpośrednio do http://localhost:8081. **Opcja 1: Użycie Spring Boot Dashboard (zalecane dla użytkowników VS Code)** -Kontener deweloperski zawiera rozszerzenie Spring Boot Dashboard, które zapewnia wizualny interfejs do zarządzania wszystkimi aplikacjami Spring Boot. Znajdziesz je w pasku aktywności po lewej stronie VS Code (ikona Spring Boot). +Kontener deweloperski zawiera rozszerzenie Spring Boot Dashboard, które oferuje wizualny interfejs do zarządzania wszystkimi aplikacjami Spring Boot. Znajdziesz go na pasku aktywności po lewej stronie VS Code (ikona Spring Boot). Z poziomu Spring Boot Dashboard możesz: - Zobaczyć wszystkie dostępne aplikacje Spring Boot w przestrzeni roboczej - Uruchamiać/zatrzymywać aplikacje jednym kliknięciem -- Przeglądać logi aplikacji w czasie rzeczywistym +- Przeglądać logi aplikacji na żywo - Monitorować status aplikacji -Po prostu kliknij przycisk play obok „rag”, aby uruchomić ten moduł, lub uruchom wszystkie moduły naraz. +Po prostu kliknij przycisk odtwarzania obok "rag", aby uruchomić ten moduł lub uruchom wszystkie moduły jednocześnie. Spring Boot Dashboard @@ -309,16 +308,16 @@ cd 03-rag .\start.ps1 ``` -Oba skrypty automatycznie ładują zmienne środowiskowe z pliku `.env` w katalogu głównym i zbudują JAR-y, jeśli nie istnieją. +Oba skrypty automatycznie ładują zmienne środowiskowe z pliku `.env` w katalogu głównym i zbudują pliki JAR, jeśli jeszcze ich nie ma. -> **Uwaga:** Jeśli wolisz najpierw ręcznie zbudować wszystkie moduły przed startem: +> **Uwaga:** Jeśli wolisz ręcznie zbudować wszystkie moduły przed uruchomieniem: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -345,7 +344,7 @@ cd ..; .\stop-all.ps1 # Wszystkie moduły ## Korzystanie z aplikacji -Aplikacja udostępnia interfejs webowy do przesyłania dokumentów i zadawania pytań. +Aplikacja oferuje interfejs webowy do przesyłania dokumentów i zadawania pytań. RAG Application Interface @@ -353,85 +352,85 @@ Aplikacja udostępnia interfejs webowy do przesyłania dokumentów i zadawania p ### Prześlij dokument -Zacznij od przesłania dokumentu — najlepiej sprawdzają się pliki TXT do testów. W tym katalogu znajduje się plik `sample-document.txt` zawierający informacje o funkcjach LangChain4j, implementacji RAG i najlepszych praktykach — idealny do testowania systemu. +Zacznij od przesłania dokumentu — najlepiej sprawdzają się pliki TXT do testów. W tym katalogu znajduje się przykładowy plik `sample-document.txt` zawierający informacje o funkcjach LangChain4j, implementacji RAG i najlepszych praktykach — idealny do testów systemu. -System przetwarza twój dokument, dzieli go na fragmenty i tworzy osadzenia dla każdego fragmentu. Dzieje się to automatycznie po przesłaniu. +System przetwarza twój dokument, dzieli go na fragmenty i tworzy osadzenia dla każdego fragmentu. Odbywa się to automatycznie podczas przesyłania. ### Zadawaj pytania -Teraz zadawaj konkretne pytania dotyczące zawartości dokumentu. Spróbuj czegoś faktycznego, co jest jasno napisane w dokumencie. System wyszukuje odpowiednie fragmenty, dołącza je do promptu i generuje odpowiedź. +Teraz zadaj konkretne pytania dotyczące treści dokumentu. Spróbuj czegoś faktograficznego, co jest jasno przedstawione w dokumencie. System wyszukuje odpowiednie fragmenty, uwzględnia je w promptcie i generuje odpowiedź. ### Sprawdź źródła -Zauważ, że każda odpowiedź zawiera odniesienia do źródeł z wynikami podobieństwa. Te wyniki (od 0 do 1) pokazują, jak bardzo dany fragment odpowiada twojemu pytaniu. Wyższe wyniki oznaczają lepsze dopasowanie. Pozwala to zweryfikować odpowiedź względem materiału źródłowego. +Zauważ, że każda odpowiedź zawiera odniesienia do źródeł z wynikami podobieństwa. Wyniki te (od 0 do 1) pokazują, jak bardzo dany fragment jest istotny względem Twojego pytania. Wyższe wyniki oznaczają lepsze dopasowanie. To pozwala Ci zweryfikować odpowiedź względem materiałów źródłowych. RAG Query Results -*Ten zrzut ekranu pokazuje wyniki zapytania z wygenerowaną odpowiedzią, odniesieniami do źródeł i wynikami relewancji dla każdego pobranego fragmentu.* +*Ten zrzut ekranu pokazuje wyniki zapytania z wygenerowaną odpowiedzią, odnośnikami do źródeł oraz wynikami istotności dla każdego pobranego fragmentu.* ### Eksperymentuj z pytaniami Wypróbuj różne typy pytań: -- Konkretne fakty: „Jaki jest główny temat?” -- Porównania: „Jaka jest różnica między X a Y?” -- Podsumowania: „Podsumuj kluczowe punkty dotyczące Z” +- Fakty szczegółowe: "Jaki jest główny temat?" +- Porównania: "Jaka jest różnica między X a Y?" +- Podsumowania: "Podsumuj kluczowe punkty dotyczące Z" -Obserwuj, jak zmieniają się wyniki relewancji w zależności od tego, jak dobrze twoje pytanie pasuje do zawartości dokumentu. +Obserwuj, jak zmieniają się wyniki istotności w zależności od tego, jak dobrze pytanie pasuje do treści dokumentu. -## Kluczowe koncepcje +## Kluczowe pojęcia ### Strategia dzielenia na fragmenty -Dokumenty są dzielone na fragmenty o 300 tokenach z 30 tokenami nakładki. To równowaga, która zapewnia, że każdy fragment ma wystarczająco kontekstu, aby być znaczący, a jednocześnie jest wystarczająco mały, aby można było zamieścić wiele fragmentów w promptcie. +Dokumenty są dzielone na fragmenty po 300 tokenów z 30-tokenowym nakładaniem. Ten balans zapewnia, że każdy fragment ma wystarczająco dużo kontekstu, aby być znaczący, a jednocześnie pozostaje na tyle mały, aby można było uwzględnić wiele fragmentów w promptcie. ### Wyniki podobieństwa -Każdy pobrany fragment ma wynik podobieństwa między 0 a 1, który wskazuje, jak bardzo pasuje do pytania użytkownika. Poniższy diagram wizualizuje zakresy wyników i jak system ich używa do filtrowania wyników: +Każdy pobrany fragment ma przypisany wynik podobieństwa od 0 do 1, który wskazuje, jak bardzo jest dopasowany do pytania użytkownika. Poniższy diagram wizualizuje zakresy wyników i sposób, w jaki system wykorzystuje je do filtrowania wyników: Similarity Scores -*Ten diagram pokazuje zakresy wyników od 0 do 1, z minimalnym progiem 0.5, który filtruje nieistotne fragmenty.* +*Ten diagram pokazuje zakres wyników od 0 do 1, z minimalnym progiem 0.5, który odfiltrowuje fragmenty nieistotne.* -Wyniki mieszczą się w zakresie od 0 do 1: -- 0.7-1.0: Wysoce relewantne, dokładne dopasowanie -- 0.5-0.7: Relewantne, dobry kontekst -- Poniżej 0.5: Odfiltrowane, zbyt różne +Wyniki mieszczą się w przedziale 0 do 1: +- 0.7-1.0: Wysoce istotne, dokładne dopasowanie +- 0.5-0.7: Istotne, dobry kontekst +- Poniżej 0.5: Odfiltrowane, zbyt niepodobne System pobiera tylko fragmenty powyżej minimalnego progu, aby zapewnić jakość. -Osadzenia działają dobrze, gdy znaczenie grupuje się czysto, ale mają też słabe punkty. Poniższy diagram pokazuje typowe tryby niepowodzeń — fragmenty zbyt duże dają rozmyte wektory, fragmenty zbyt małe tracą kontekst, niejednoznaczne terminy wskazują na wiele grup, a wyszukiwania dokładne (ID, numery części) w ogóle nie działają z osadzeniami: +Osadzenia dobrze działają, gdy sens grupuje się wyraźnie, ale mają swoje ograniczenia. Poniższy diagram pokazuje typowe tryby błędów — zbyt duże fragmenty dają zamazane wektory, zbyt małe tracą kontekst, niejednoznaczne terminy wskazują na wiele klastrów, a wyszukiwanie dokładnych dopasowań (ID, numery części) w ogóle nie działa z osadzeniami: Embedding Failure Modes -*Ten diagram pokazuje typowe tryby niepowodzenia osadzeń: zbyt duże fragmenty, zbyt małe fragmenty, niejednoznaczne terminy wskazujące na wiele grup oraz wyszukiwania dokładne, jak numery ID.* +*Ten diagram pokazuje typowe tryby błędów w osadzeniach: fragmenty za duże, fragmenty za małe, niejednoznaczne terminy wskazujące na wiele klastrów oraz wyszukiwania dokładne jak ID.* -### Pamięć w RAM +### Przechowywanie w pamięci -Ten moduł korzysta z pamięci ulotnej (in-memory) dla uproszczenia. Po restarcie aplikacji przesłane dokumenty są tracone. Systemy produkcyjne używają trwałych baz danych wektorowych, takich jak Qdrant lub Azure AI Search. +Ten moduł używa przechowywania w pamięci dla uproszczenia. Po ponownym uruchomieniu aplikacji przesłane dokumenty są tracone. Systemy produkcyjne używają trwałych baz wektorowych, takich jak Qdrant lub Azure AI Search. -### Zarządzanie oknem kontekstowym +### Zarządzanie oknem kontekstu -Każdy model ma maksymalne okno kontekstowe. Nie da się zamieścić każdego fragmentu z dużego dokumentu. System pobiera N najbardziej relewantnych fragmentów (domyślnie 5), aby pozostać w limitach i dostarczyć wystarczająco kontekstu do dokładnych odpowiedzi. +Każdy model ma maksymalne okno kontekstu. Nie możesz uwzględnić wszystkich fragmentów z dużego dokumentu. System pobiera top N najbardziej istotnych fragmentów (domyślnie 5), aby zmieścić się w limitach i jednocześnie zapewnić wystarczający kontekst do dokładnych odpowiedzi. ## Kiedy RAG ma znaczenie -RAG nie zawsze jest najlepszym rozwiązaniem. Poniższy przewodnik decyzyjny pomaga określić, kiedy RAG wnosi wartość, a kiedy prostsze podejścia — jak bezpośrednie dołączenie treści do promptu lub poleganie na wbudowanej wiedzy modelu — są wystarczające: +RAG nie zawsze jest właściwym podejściem. Poniższy przewodnik decyzyjny pomaga określić, kiedy RAG dodaje wartość, a kiedy proste podejścia — jak zawieranie treści bezpośrednio w promptcie lub poleganie na wbudowanej wiedzy modelu — są wystarczające: When to Use RAG -*Ten diagram pokazuje przewodnik decyzyjny, kiedy RAG dodaje wartość, a kiedy wystarczają prostsze podejścia.* +*Ten diagram pokazuje przewodnik decyzyjny, kiedy RAG dodaje wartość w porównaniu do sytuacji, gdy wystarczą prostsze podejścia.* -## Kolejne kroki +## Następne kroki -**Następny modół:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Następny moduł:** [04-tools - AI Agenci z narzędziami](../04-tools/README.md) --- -**Nawigacja:** [← Poprzedni: Moduł 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Powrót do głównej](../README.md) | [Następny: Moduł 04 - Tools →](../04-tools/README.md) +**Nawigacja:** [← Poprzedni: Moduł 02 - Inżynieria promptów](../02-prompt-engineering/README.md) | [Powrót do głównej](../README.md) | [Następny: Moduł 04 - Narzędzia →](../04-tools/README.md) --- -**Zastrzeżenie**: -Niniejszy dokument został przetłumaczony za pomocą usługi tłumaczeniowej AI [Co-op Translator](https://github.com/Azure/co-op-translator). Choć dokładamy starań, aby tłumaczenie było precyzyjne, prosimy mieć na uwadze, że automatyczne tłumaczenia mogą zawierać błędy lub nieścisłości. Oryginalny dokument w języku źródłowym należy traktować jako wersję autorytatywną. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia. +**Zastrzeżenie**: +Niniejszy dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Choć dążymy do dokładności, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub niedokładności. Oryginalny dokument w jego języku źródłowym należy uznawać za autorytatywne źródło. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia. \ No newline at end of file diff --git a/translations/pl/04-tools/README.md b/translations/pl/04-tools/README.md index ca0aa2004..06675b20a 100644 --- a/translations/pl/04-tools/README.md +++ b/translations/pl/04-tools/README.md @@ -1,76 +1,76 @@ -# Moduł 04: Agenci AI z narzędziami +# Moduł 04: Agenci AI z Narzędziami ## Spis treści -- [Film instruktażowy](../../../04-tools) -- [Czego się nauczysz](../../../04-tools) -- [Wymagania wstępne](../../../04-tools) -- [Zrozumienie agentów AI z narzędziami](../../../04-tools) -- [Jak działa wywoływanie narzędzi](../../../04-tools) - - [Definicje narzędzi](../../../04-tools) - - [Podejmowanie decyzji](../../../04-tools) - - [Wykonanie](../../../04-tools) - - [Generowanie odpowiedzi](../../../04-tools) - - [Architektura: automatyczne wiązanie Spring Boot](../../../04-tools) -- [Łańcuchowanie narzędzi](../../../04-tools) -- [Uruchomienie aplikacji](../../../04-tools) -- [Korzystanie z aplikacji](../../../04-tools) - - [Wypróbuj proste użycie narzędzi](../../../04-tools) - - [Przetestuj łańcuchowanie narzędzi](../../../04-tools) - - [Zobacz przebieg rozmowy](../../../04-tools) - - [Eksperymentuj z różnymi zapytaniami](../../../04-tools) -- [Kluczowe pojęcia](../../../04-tools) - - [Wzorzec ReAct (Rozumowanie i Działanie)](../../../04-tools) - - [Opisy narzędzi mają znaczenie](../../../04-tools) - - [Zarządzanie sesją](../../../04-tools) - - [Obsługa błędów](../../../04-tools) -- [Dostępne narzędzia](../../../04-tools) -- [Kiedy używać agentów opartych na narzędziach](../../../04-tools) -- [Narzędzia a RAG](../../../04-tools) -- [Kolejne kroki](../../../04-tools) - -## Film instruktażowy - -Obejrzyj tę sesję na żywo, która wyjaśnia, jak zacząć pracę z tym modułem: - -Agenci AI z narzędziami i MCP - sesja na żywo +- [Przewodnik wideo](#przewodnik-wideo) +- [Czego się nauczysz](#czego-się-nauczysz) +- [Wymagania wstępne](#wymagania-wstępne) +- [Zrozumienie agentów AI z narzędziami](#zrozumienie-agentów-ai-z-narzędziami) +- [Jak działa wywoływanie narzędzi](#jak-działa-wywoływanie-narzędzi) + - [Definicje narzędzi](#definicje-narzędzi) + - [Proces decyzyjny](#proces-decyzyjny) + - [Wykonanie](#wykonanie) + - [Generowanie odpowiedzi](#generowanie-odpowiedzi) + - [Architektura: automatyczne wiązanie Spring Boot](#architektura-automatyczne-wiązanie-spring-boot) +- [Łączenie narzędzi](#łączenie-narzędzi) +- [Uruchomienie aplikacji](#uruchomienie-aplikacji) +- [Korzystanie z aplikacji](#korzystanie-z-aplikacji) + - [Wypróbuj proste użycie narzędzia](#wypróbuj-proste-użycie-narzędzi) + - [Przetestuj łączenie narzędzi](#przetestuj-łączenie-narzędzi) + - [Zobacz przebieg rozmowy](#zobacz-przebieg-rozmowy) + - [Eksperymentuj z różnymi zapytaniami](#eksperymentuj-z-różnymi-zapytaniami) +- [Kluczowe koncepcje](#kluczowe-pojęcia) + - [Wzorzec ReAct (Rozumowanie i działanie)](#wzorzec-react-rozumowanie-i-działanie) + - [Znaczenie opisów narzędzi](#opisy-narzędzi-mają-znaczenie) + - [Zarządzanie sesją](#zarządzanie-sesją) + - [Obsługa błędów](#obsługa-błędów) +- [Dostępne narzędzia](#dostępne-narzędzia) +- [Kiedy używać agentów bazujących na narzędziach](#kiedy-używać-agentów-opartych-na-narzędziach) +- [Narzędzia a RAG](#narzędzia-a-rag) +- [Kolejne kroki](#kolejne-kroki) + +## Przewodnik wideo + +Obejrzyj tę sesję na żywo, która wyjaśnia, jak rozpocząć pracę z tym modułem: + +AI Agents with Tools and MCP - Live Session ## Czego się nauczysz -Do tej pory nauczyłeś się, jak prowadzić rozmowy z AI, skutecznie budować prompt’y i opierać odpowiedzi na twoich dokumentach. Jednak nadal istnieje podstawowe ograniczenie: modele językowe mogą generować tylko tekst. Nie mogą sprawdzać pogody, wykonywać obliczeń, zapytać bazy danych ani współdziałać z zewnętrznymi systemami. +Do tej pory nauczyłeś się prowadzić rozmowy z AI, skutecznie strukturyzować prompt-y i opierać odpowiedzi na Twoich dokumentach. Ale nadal istnieje podstawowe ograniczenie: modele językowe mogą generować tylko tekst. Nie mogą sprawdzić pogody, wykonać obliczeń, zapytać baz danych ani komunikować się z zewnętrznymi systemami. -Narzędzia to zmieniają. Dając modelowi dostęp do funkcji, które może wywoływać, przekształcasz go z generatora tekstu w agenta, który może podejmować działania. Model decyduje, kiedy potrzebuje narzędzia, którego narzędzia użyć i jakie argumenty przekazać. Twój kod wykonuje funkcję i zwraca wynik. Model włącza ten wynik do odpowiedzi. +Narzędzia to zmieniają. Dając modelowi dostęp do funkcji, które może wywołać, przekształcasz go z generatora tekstu w agenta zdolnego do podejmowania działań. Model decyduje, kiedy potrzebuje narzędzia, którego narzędzia użyć i jakie parametry przekazać. Twój kod wykonuje funkcję i zwraca wynik. Model włącza ten wynik do swojej odpowiedzi. ## Wymagania wstępne -- Ukończony [Moduł 01 - Wprowadzenie](../01-introduction/README.md) (zasoby Azure OpenAI wdrożone) -- Zalecane ukończenie poprzednich modułów (ten moduł odnosi się do [koncepcji RAG z Modułu 03](../03-rag/README.md) w porównaniu Narzędzia vs RAG) -- Plik `.env` w katalogu głównym z poświadczeniami Azure (utworzony przez `azd up` w Module 01) +- Ukończenie [Modułu 01 - Wprowadzenie](../01-introduction/README.md) (dostępne zasoby Azure OpenAI) +- Zalecane ukończenie poprzednich modułów (moduł ten odwołuje się do [koncepcji RAG z Modułu 03](../03-rag/README.md) w porównaniu Narzędzia vs RAG) +- Plik `.env` w katalogu głównym z danymi uwierzytelniającymi Azure (utworzony przez `azd up` w Moduł 01) -> **Uwaga:** Jeśli nie ukończyłeś Modułu 01, najpierw wykonaj instrukcje wdrożeniowe tam zawarte. +> **Uwaga:** Jeśli nie ukończyłeś Modułu 01, najpierw wykonaj tam instrukcje dotyczące wdrożenia. ## Zrozumienie agentów AI z narzędziami -> **📝 Uwaga:** Termin „agenci” w tym module odnosi się do asystentów AI rozszerzonych o możliwość wywoływania narzędzi. To różni się od wzorców **Agentic AI** (agentów autonomicznych z planowaniem, pamięcią i rozumowaniem wieloetapowym), które omówimy w [Moduł 05: MCP](../05-mcp/README.md). +> **📝 Uwaga:** Termin „agenci” w tym module odnosi się do asystentów AI rozszerzonych o możliwość wywoływania narzędzi. Różni się to od wzorców **Agentic AI** (autonomicznych agentów z planowaniem, pamięcią i wieloetapowym rozumowaniem), które omówimy w [Moduł 05: MCP](../05-mcp/README.md). -Bez narzędzi model językowy może generować tylko tekst na podstawie swoich danych treningowych. Zapytaj o aktualną pogodę, a będzie musiał zgadywać. Dodaj narzędzia, a model może wywołać API pogodowe, wykonać obliczenia lub zapytać bazę danych — a następnie wpleść faktyczne rezultaty w swoją odpowiedź. +Bez narzędzi model językowy może tylko generować tekst na podstawie danych treningowych. Zapytaj go o aktualną pogodę, a będzie musiał zgadywać. Daj mu narzędzia, a może wywołać API pogodowe, wykonać obliczenia lub zapytać bazę danych — a następnie wpleść te rzeczywiste wyniki w odpowiedź. -Bez narzędzi kontra z narzędziami +Without Tools vs With Tools -*Bez narzędzi model może tylko zgadywać — z narzędziami może wywoływać API, wykonywać obliczenia i zwracać dane w czasie rzeczywistym.* +*Bez narzędzi model tylko zgaduje — z narzędziami może wywoływać API, wykonywać obliczenia i zwracać dane w czasie rzeczywistym.* -Agent AI z narzędziami działa według wzorca **Reasoning and Acting (ReAct)**. Model nie tylko odpowiada — zastanawia się, czego potrzebuje, działa wywołując narzędzie, obserwuje wynik, a następnie decyduje, czy działać dalej, czy dostarczyć ostateczną odpowiedź: +Agent AI z narzędziami stosuje wzorzec **Rozumowanie i działanie (ReAct)**. Model nie tylko odpowiada — myśli o tym, czego potrzebuje, działa, wywołując narzędzie, obserwuje wynik, a następnie decyduje, czy działać dalej, czy dostarczyć ostateczną odpowiedź: -1. **Rozumowanie** — agent analizuje pytanie użytkownika i określa, jakie informacje są potrzebne -2. **Działanie** — agent wybiera właściwe narzędzie, generuje odpowiednie parametry i wywołuje funkcję -3. **Obserwacja** — agent otrzymuje wynik narzędzia i ocenia rezultat -4. **Powtarzanie lub odpowiedź** — jeśli potrzeba więcej danych, agent wraca do kroku 1; w przeciwnym razie tworzy odpowiedź w języku naturalnym +1. **Rozumowanie** — Agent analizuje pytanie użytkownika i ustala, jakich informacji potrzebuje +2. **Działanie** — Agent wybiera odpowiednie narzędzie, generuje właściwe parametry i je wywołuje +3. **Obserwacja** — Agent otrzymuje wynik narzędzia i ocenia rezultat +4. **Powtarzaj lub odpowiadaj** — Jeśli potrzebne są dalsze dane, agent powtarza pętlę; w przeciwnym razie komponuje odpowiedź w naturalnym języku -Wzorzec ReAct +ReAct Pattern -*Cykl ReAct — agent rozważa, co zrobić, działa wywołując narzędzie, obserwuje wynik i powtarza pętlę aż do dostarczenia ostatecznej odpowiedzi.* +*Cykl ReAct — agent myśli, co zrobić, działa, wywołując narzędzie, obserwuje wynik i powtarza, aż może dostarczyć ostateczną odpowiedź.* -Dzieje się to automatycznie. Definiujesz narzędzia i ich opisy. Model sam podejmuje decyzje, kiedy i jak ich używać. +Działa to automatycznie. Definiujesz narzędzia i ich opisy. Model sam podejmuje decyzje, kiedy i jak ich użyć. ## Jak działa wywoływanie narzędzi @@ -78,7 +78,7 @@ Dzieje się to automatycznie. Definiujesz narzędzia i ich opisy. Model sam pode [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Definiujesz funkcje z jasnymi opisami i specyfikacją parametrów. Model widzi te opisy w systemowym prompt i rozumie, co każde narzędzie robi. +Definiujesz funkcje z jasnymi opisami i specyfikacją parametrów. Model widzi te opisy w promptach systemowych i rozumie, do czego służy każde narzędzie. ```java @Component @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Asystent jest automatycznie konfigurowany przez Spring Boot z: -// - Bean ChatModel -// - Wszystkie metody @Tool z klas @Component +// Asystent jest automatycznie powiązany przez Spring Boot z: +// - beana ChatModel +// - wszystkimi metodami @Tool z klas oznaczonych @Component // - ChatMemoryProvider do zarządzania sesją ``` -Poniższy diagram rozkłada na części każdą adnotację i pokazuje, jak każdy element pomaga SI zrozumieć, kiedy wywołać narzędzie i jakie argumenty przekazać: +Diagram poniżej rozkłada każdą adnotację i pokazuje, jak każda część pomaga AI zrozumieć, kiedy wywołać narzędzie i jakie argumenty przekazać: -Anatomia definicji narzędzi +Anatomy of Tool Definitions -*Anatomia definicji narzędzia — @Tool mówi SI, kiedy go użyć, @P opisuje każdy parametr, a @AiService wiąże wszystko razem przy starcie.* +*Anatomia definicji narzędzia — @Tool mówi AI, kiedy go użyć, @P opisuje każdy parametr, a @AiService wiąże wszystko razem podczas uruchamiania.* > **🤖 Wypróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) i zapytaj: -> - „Jak zintegrowałbym prawdziwe API pogodowe, np. OpenWeatherMap, zamiast danych mock?” -> - „Co sprawia, że opis narzędzia dobrze pomaga SI używać go prawidłowo?” -> - „Jak obsługiwać błędy API i limity liczby wywołań w implementacji narzędzi?” +> - „Jak zintegrować prawdziwe API pogodowe, np. OpenWeatherMap, zamiast danych testowych?” +> - „Co sprawia, że opis narzędzia pomaga AI używać go poprawnie?” +> - „Jak obsługiwać błędy API i limity zapytań w implementacjach narzędzi?” -### Podejmowanie decyzji +### Proces decyzyjny -Kiedy użytkownik pyta „Jaka jest pogoda w Seattle?”, model nie wybiera narzędzia losowo. Porównuje intencję użytkownika z opisami wszystkich dostępnych narzędzi, ocenia je pod kątem trafności i wybiera najlepsze. Następnie generuje znormalizowane wywołanie funkcji z odpowiednimi parametrami — w tym przypadku ustawia `location` na `"Seattle"`. +Gdy użytkownik zapyta „Jaka jest pogoda w Seattle?”, model nie wybiera narzędzia losowo. Porównuje intencję użytkownika z opisami wszystkich dostępnych narzędzi, ocenia ich trafność i wybiera najlepsze dopasowanie. Następnie generuje ustrukturyzowane wywołanie funkcji z odpowiednimi parametrami — w tym przypadku ustawia `location` na `"Seattle"`. -Jeśli żadne narzędzie nie pasuje do zapytania, model odpowiada na podstawie własnej wiedzy. Jeśli pasuje wiele narzędzi, wybiera to najbardziej specyficzne. +Jeśli żadne narzędzie nie pasuje do zapytania użytkownika, model odpowiada z własnej wiedzy. Jeśli pasuje więcej narzędzi, wybiera najdokładniejsze. -Jak SI wybiera narzędzie +How the AI Decides Which Tool to Use -*Model ocenia każde dostępne narzędzie względem intencji użytkownika i wybiera najlepsze dopasowanie — dlatego właśnie ważne jest pisanie jasnych, konkretnych opisów narzędzi.* +*Model ocenia każde dostępne narzędzie względem intencji użytkownika i wybiera najlepsze dopasowanie — dlatego ważne jest pisanie jasnych, konkretnych opisów narzędzi.* ### Wykonanie [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot automatycznie wstrzykuje deklaratywny interfejs `@AiService` ze wszystkimi zarejestrowanymi narzędziami, a LangChain4j automatycznie wykonuje wywołania narzędzi. Za kulisami pełne wywołanie narzędzia przebiega przez sześć etapów — od pytania użytkownika w języku naturalnym po odpowiedź w tym samym języku: +Spring Boot automatycznie wstrzykuje interfejs deklaratywny `@AiService` ze wszystkimi zarejestrowanymi narzędziami, a LangChain4j wykonuje wywołania narzędzi automatycznie. W tle wywołanie narzędzia przebiega przez sześć etapów — od pytania naturalnego języka użytkownika do odpowiedzi w naturalnym języku: -Przebieg wywoływania narzędzi +Tool Calling Flow -*Przebieg end-to-end — użytkownik zadaje pytanie, model wybiera narzędzie, LangChain4j je wykonuje, a model wplata wynik w naturalną odpowiedź.* +*Przepływ end-to-end — użytkownik zadaje pytanie, model wybiera narzędzie, LangChain4j je wykonuje, a model wplata wynik w naturalną odpowiedź.* -Jeśli uruchomiłeś [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) w Moduł 00, już widziałeś ten wzorzec w praktyce — narzędzia `Calculator` były wywoływane w ten sam sposób. Diagram sekwencji poniżej pokazuje dokładnie, co działo się „pod maską” podczas tamtego demo: +W tle `AiServices` uruchamia tę samą pętlę wywołań narzędzi dla dowolnego narzędzia — tutaj pokazane na przykładzie prostego `Calculator`. Diagram sekwencji poniżej pokazuje dokładnie, co dzieje się pod maską: -Diagram sekwencji wywoływania narzędzi +Tool Calling Sequence Diagram -*Pętla wywoływania narzędzi z demo Quick Start — `AiServices` wysyła twoją wiadomość i schematy narzędzi do LLM, LLM odpowiada wywołaniem funkcji `add(42, 58)`, LangChain4j lokalnie wykonuje metodę `Calculator` i odsyła wynik do ostatecznej odpowiedzi.* +*Pętla wywoływania narzędzi — `AiServices` wysyła Twoją wiadomość i schematy narzędzi do LLM, LLM odpowiada wywołaniem funkcji jak `add(42, 58)`, LangChain4j wykonuje lokalnie metodę `Calculator`, a wynik przekazuje z powrotem dla finalnej odpowiedzi.* > **🤖 Wypróbuj z [GitHub Copilot](https://github.com/features/copilot) Chat:** Otwórz [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) i zapytaj: > - „Jak działa wzorzec ReAct i dlaczego jest skuteczny dla agentów AI?” > - „Jak agent decyduje, którego narzędzia użyć i w jakiej kolejności?” -> - „Co się dzieje, jeśli wywołanie narzędzia się nie powiedzie — jak poprawnie obsługiwać błędy?” +> - „Co się stanie, jeśli wykonanie narzędzia się nie powiedzie — jak solidnie obsługiwać błędy?” ### Generowanie odpowiedzi -Model otrzymuje dane pogodowe i formatuje je na naturalną odpowiedź dla użytkownika. +Model otrzymuje dane pogodowe i formatuje je na odpowiedź w naturalnym języku dla użytkownika. ### Architektura: automatyczne wiązanie Spring Boot -Ten moduł korzysta z integracji LangChain4j ze Spring Boot i deklaratywnych interfejsów `@AiService`. Przy starcie Spring Boot wykrywa każdy `@Component` zawierający metody `@Tool`, twój bean `ChatModel` oraz `ChatMemoryProvider` — a następnie podłącza je razem do pojedynczego interfejsu `Assistant` bez żadnego boilerplate. +Ten moduł wykorzystuje integrację LangChain4j ze Spring Boot z deklaratywnymi interfejsami `@AiService`. Przy uruchamianiu Spring Boot wykrywa każdy `@Component` zawierający metody `@Tool`, Twój bean `ChatModel` oraz `ChatMemoryProvider` — po czym łączy je wszystkie w pojedynczy interfejs `Assistant` bez zbędnego kodu. -Architektura automatycznego wiązania Spring Boot +Spring Boot Auto-Wiring Architecture -*Interfejs @AiService łączy ChatModel, komponenty narzędzi i dostawcę pamięci — Spring Boot automatycznie zarządza całym wiązaniem.* +*Interfejs @AiService spina razem ChatModel, komponenty narzędzi i dostawcę pamięci — Spring Boot sam obsługuje wiązanie.* -Poniżej pełny cykl życia żądania jako diagram sekwencji — od żądania HTTP przez kontroler, usługę i auto-wiązany proxy, aż po wykonanie narzędzia i powrót: +Oto pełny cykl życia zapytania jako diagram sekwencji — od zapytania HTTP, przez kontroler, serwis i auto-wiązany proxy, aż do wykonania narzędzia i powrotu: -Diagram sekwencji wywołania narzędzi w Spring Boot +Spring Boot Tool Calling Sequence -*Pełny cykl życia żądania w Spring Boot — żądanie HTTP przechodzi przez kontroler i serwis do auto-wiązanego proxy Assistant, które automatycznie orkiestruje wywołania LLM i narzędzi.* +*Pełny cykl życia zapytania Spring Boot — żądanie HTTP przechodzi przez kontroler i serwis do auto-wiązanego proxy Assistant, które automatycznie orkiestruje LLM i wywołania narzędzi.* -Główne zalety tego podejścia: +Kluczowe zalety tego podejścia: - **Automatyczne wiązanie Spring Boot** — ChatModel i narzędzia wstrzykiwane automatycznie -- **Wzorzec @MemoryId** — Automatyczne zarządzanie pamięcią opartą na sesji -- **Pojedyncza instancja** — Asystent tworzony raz i używany ponownie dla lepszej wydajności -- **Wykonanie bezpieczne typowo** — metody Java wywoływane bezpośrednio z konwersją typów -- **Orkiestracja wielu tur** — obsługuje automatycznie łańcuchowanie narzędzi -- **Zero boilerplate** — brak ręcznych wywołań `AiServices.builder()` lub pamięci w HashMap +- **Wzorzec @MemoryId** — Automatyczne zarządzanie pamięcią oparte na sesji +- **Jedna instancja** — Assistant tworzony raz i używany ponownie dla lepszej wydajności +- **Bezpieczne typowanie** — Metody Javy wywoływane bezpośrednio z konwersją typów +- **Wieloetapowa orkiestracja** — Automatyczna obsługa łączenia narzędzi +- **Zero boilerplate** — Brak ręcznych wywołań `AiServices.builder()` lub pamięci HashMap -Alternatywne podejścia (ręczne `AiServices.builder()`) wymagają więcej kodu i nie korzystają z zalet integracji Spring Boot. +Alternatywne podejścia (ręczne `AiServices.builder()`) wymagają więcej kodu i nie oferują korzyści integracji ze Spring Boot. -## Łańcuchowanie narzędzi +## Łączenie narzędzi -**Łańcuchowanie narzędzi** — prawdziwa moc agentów opartych na narzędziach ujawnia się, gdy pojedyncze pytanie wymaga wielu narzędzi. Zapytaj „Jaka jest pogoda w Seattle w stopniach Fahrenheita?”, a agent automatycznie połączy dwa narzędzia: najpierw wywoła `getCurrentWeather`, aby uzyskać temperaturę w stopniach Celsjusza, a następnie przekaże tę wartość do `celsiusToFahrenheit` w celu konwersji — wszystko w jednej turze rozmowy. +**Łączenie narzędzi** — Prawdziwa moc agentów bazujących na narzędziach ujawnia się, gdy jedno pytanie wymaga użycia wielu narzędzi. Zapytaj „Jaka jest pogoda w Seattle w Fahrenheit?” a agent automatycznie łączy dwa narzędzia: najpierw wywołuje `getCurrentWeather` by pozyskać temperaturę w Celsiuszach, potem przekazuje tę wartość do `celsiusToFahrenheit` w celu przeliczenia — wszystko w jednym obrocie konwersacji. -Przykład łańcuchowania narzędzi +Tool Chaining Example -*Łańcuchowanie narzędzi w akcji — agent najpierw wywołuje getCurrentWeather, potem przekazuje wynik w Celsjuszach do celsiusToFahrenheit i dostarcza złożoną odpowiedź.* +*Łączenie narzędzi w działaniu — agent najpierw wywołuje getCurrentWeather, następnie przesyła wynik w Celsiuszach do celsiusToFahrenheit i dostarcza skonsolidowaną odpowiedź.* -**Łagodne błędy** — Poproś o pogodę w mieście, którego nie ma w danych mockowych. Narzędzie zwraca komunikat o błędzie, a AI wyjaśnia, że nie może pomóc, zamiast się zawiesić. Narzędzia zawiodą bezpiecznie. Diagram poniżej porównuje oba podejścia — przy właściwej obsłudze błędów agent łapie wyjątek i odpowiednio reaguje, a bez niej cała aplikacja się zawiesza: +**Łagodne awarie** — Zapytaj o pogodę w mieście, którego nie ma w danych testowych. Narzędzie zwraca komunikat o błędzie, a AI tłumaczy, że nie może pomóc, zamiast się zawiesić. Narzędzia zawodzą bezpiecznie. Diagram poniżej kontrastuje oba podejścia — przy poprawnej obsłudze błędów agent łapie wyjątek i odpowiada pomocnie, a bez niej cała aplikacja ulega awarii: -Przebieg obsługi błędów +Error Handling Flow -*Gdy narzędzie zawodzi, agent łapie błąd i odpowiada pomocnym wyjaśnieniem zamiast awarii.* +*Gdy narzędzie zawodzi, agent łapie błąd i odpowiada wyjaśnieniem zamiast awarii.* -Dzieje się to w jednej turze rozmowy. Agent autonomicznie orkiestruje wiele wywołań narzędzi. +Dzieje się to w jednym obrocie rozmowy. Agent samodzielnie orkiestruje wiele wywołań narzędzi. ## Uruchomienie aplikacji -**Potwierdzenie wdrożenia:** +**Sprawdź wdrożenie:** -Upewnij się, że plik `.env` istnieje w katalogu głównym z poświadczeniami Azure (stworzony podczas Modułu 01). Uruchom to z katalogu modułu (`04-tools/`): +Upewnij się, że plik `.env` istnieje w katalogu głównym z danymi uwierzytelniającymi Azure (utworzony podczas Modułu 01). Uruchom to z katalogu modułu (`04-tools/`): **Bash:** ```bash @@ -202,33 +202,33 @@ cat ../.env # Powinno pokazywać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **PowerShell:** ```powershell -Get-Content ..\.env # Powinien pokazać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Powinno pokazywać AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Uruchom aplikację:** -> **Uwaga:** Jeśli uruchomiłeś już wszystkie aplikacje za pomocą `./start-all.sh` z katalogu głównego (zgodnie z opisem w Module 01), ten moduł działa już na porcie 8084. Możesz pominąć komendy startowe poniżej i przejść bezpośrednio do http://localhost:8084. +> **Uwaga:** Jeśli już uruchomiłeś wszystkie aplikacje przy pomocy `./start-all.sh` z katalogu głównego (zgodnie z Modułem 01), ten moduł działa już na porcie 8084. Możesz pominąć poniższe komendy i przejść bezpośrednio do http://localhost:8084. -**Opcja 1: Korzystanie z Spring Boot Dashboard (zalecane dla użytkowników VS Code)** +**Opcja 1: Użycie Spring Boot Dashboard (zalecane dla użytkowników VS Code)** -Kontener deweloperski zawiera rozszerzenie Spring Boot Dashboard, które udostępnia graficzny interfejs do zarządzania wszystkimi aplikacjami Spring Boot. Znajdziesz je na pasku aktywności po lewej stronie VS Code (ikona Spring Boot). +Kontener developerski zawiera rozszerzenie Spring Boot Dashboard, które daje interfejs wizualny do zarządzania wszystkimi aplikacjami Spring Boot. Znajdziesz je na pasku aktywności po lewej stronie VS Code (ikonka Spring Boot). Z poziomu Spring Boot Dashboard możesz: -- Zobaczyć wszystkie dostępne aplikacje Spring Boot w przestrzeni roboczej -- Uruchamiać/wyłączać aplikacje jednym kliknięciem +- Zobaczyć wszystkie dostępne aplikacje Spring Boot w workspace +- Uruchamiać/zatrzymywać aplikacje jednym kliknięciem - Przeglądać logi aplikacji w czasie rzeczywistym - Monitorować status aplikacji -Po prostu kliknij przycisk odtwarzania obok "tools", aby rozpocząć ten moduł, lub uruchom wszystkie moduły jednocześnie. -Tak wygląda Spring Boot Dashboard w VS Code: +Kliknij przycisk uruchomienia obok „tools”, aby wystartować ten moduł, lub rozpocznij wszystkie moduły na raz. -Panel kontrolny Spring Boot +Tak wygląda Spring Boot Dashboard w VS Code: +Spring Boot Dashboard -*Panel kontrolny Spring Boot w VS Code — uruchamiaj, zatrzymuj i monitoruj wszystkie moduły z jednego miejsca* +*Panel Spring Boot w VS Code — uruchamiaj, zatrzymuj i monitoruj wszystkie moduły w jednym miejscu* -**Opcja 2: Korzystanie ze skryptów shell** +**Opcja 2: Użycie skryptów powłoki** -Uruchom wszystkie aplikacje webowe (moduły 01-04): +Uruchom wszystkie aplikacje internetowe (moduły 01-04): **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Oba skrypty automatycznie ładują zmienne środowiskowe z pliku `.env` w katalogu głównym i zbudują pliki JAR, jeśli te nie istnieją. +Oba skrypty automatycznie ładują zmienne środowiskowe z głównego pliku `.env` i zbudują pliki JAR, jeśli jeszcze nie istnieją. -> **Uwaga:** Jeśli wolisz zbudować wszystkie moduły ręcznie przed uruchomieniem: +> **Uwaga:** Jeśli wolisz ręcznie zbudować wszystkie moduły przed uruchomieniem: > > **Bash:** > ```bash @@ -272,7 +272,7 @@ Oba skrypty automatycznie ładują zmienne środowiskowe z pliku `.env` w katalo > mvn clean package -DskipTests > ``` -Otwórz w przeglądarce http://localhost:8084. +Otwórz http://localhost:8084 w swojej przeglądarce. **Aby zatrzymać:** @@ -292,84 +292,84 @@ cd ..; .\stop-all.ps1 # Wszystkie moduły ## Korzystanie z aplikacji -Aplikacja zapewnia interfejs webowy, w którym możesz wchodzić w interakcje z agentem AI, który ma dostęp do narzędzi pogodowych i do konwersji temperatur. Tak wygląda ten interfejs — zawiera szybką sekcję z przykładami i panel czatu do wysyłania zapytań: +Aplikacja udostępnia interfejs webowy, w którym możesz wchodzić w interakcje z agentem AI mającym dostęp do narzędzi pogodowych i do konwersji temperatur. Tak wygląda interfejs — zawiera przykłady szybkiego startu i panel czatu do wysyłania zapytań: Interfejs narzędzi agenta AI -*Interfejs narzędzi agenta AI - szybkie przykłady i panel czatu do interakcji z narzędziami* +*Interfejs narzędzi Agenta AI - szybkie przykłady i interfejs czatu do interakcji z narzędziami* ### Wypróbuj proste użycie narzędzi -Zacznij od prostego zapytania: „Przelicz 100 stopni Fahrenheita na Celsjusza”. Agent rozpoznaje, że potrzebuje narzędzia do konwersji temperatury, wywołuje je z właściwymi parametrami i zwraca wynik. Zauważ, jak naturalne to jest — nie określiłeś, którego narzędzia użyć ani jak je wywołać. +Zacznij od prostego zapytania: „Przelicz 100 stopni Fahrenheita na Celsjusza”. Agent rozpoznaje, że potrzebne jest narzędzie do konwersji temperatur, wywołuje je z odpowiednimi parametrami i zwraca wynik. Zauważ, jak naturalnie to działa — nie określałeś, którego narzędzia użyć ani jak je wywołać. ### Przetestuj łączenie narzędzi -Teraz spróbuj czegoś bardziej złożonego: „Jaka jest pogoda w Seattle i przelicz ją na Fahrenheita?” Obserwuj, jak agent działa krok po kroku. Najpierw pobiera pogodę (która zwraca wartość w stopniach Celsjusza), rozpoznaje, że musi przeliczyć na Fahrenheita, wywołuje narzędzie konwersji i łączy oba wyniki w jedną odpowiedź. +Teraz spróbuj czegoś bardziej złożonego: „Jaka jest pogoda w Seattle i przelicz ją na Fahrenheita?” Obserwuj, jak agent wykonuje to krok po kroku. Najpierw pobiera pogodę (wynik w stopniach Celsjusza), rozpoznaje potrzebę konwersji na Fahrenheita, wywołuje narzędzie do konwersji i łączy oba wyniki w jedną odpowiedź. ### Zobacz przebieg rozmowy -Interfejs czatu utrzymuje historię rozmów, co pozwala na wielokrotne interakcje. Możesz zobaczyć wszystkie poprzednie zapytania i odpowiedzi, co ułatwia śledzenie rozmowy i zrozumienie, jak agent buduje kontekst na przestrzeni wielu wymian. +Interfejs czatu zachowuje historię rozmowy, co pozwala na wielokrotne interakcje. Możesz zobaczyć wszystkie poprzednie zapytania i odpowiedzi, co ułatwia śledzenie konwersacji i zrozumienie, jak agent buduje kontekst przez kolejne wymiany. Rozmowa z wieloma wywołaniami narzędzi -*Wielokrotna rozmowa pokazująca proste konwersje, wyszukiwanie pogody i łączenie narzędzi* +*Wielokrotna rozmowa pokazująca proste konwersje, wyszukiwania pogodowe i łączenie narzędzi* ### Eksperymentuj z różnymi zapytaniami -Wypróbuj różne kombinacje: +Spróbuj różnych kombinacji: - Wyszukiwanie pogody: „Jaka jest pogoda w Tokio?” -- Konwersje temperatur: „Ile to 25°C w kelwinach?” +- Konwersje temperatur: „Ile to jest 25°C w kelwinach?” - Zapytania łączone: „Sprawdź pogodę w Paryżu i powiedz, czy jest powyżej 20°C” -Zauważ, jak agent interpretuje język naturalny i dopasowuje go do odpowiednich wywołań narzędzi. +Zwróć uwagę, jak agent interpretuje język naturalny i mapuje go na odpowiednie wywołania narzędzi. -## Kluczowe koncepcje +## Kluczowe pojęcia ### Wzorzec ReAct (Rozumowanie i Działanie) -Agent naprzemiennie rozważa (decyduje co zrobić) i działa (używa narzędzi). Ten wzorzec umożliwia autonomiczne rozwiązywanie problemów, a nie tylko odpowiadanie na polecenia. +Agent przełącza się pomiędzy rozumowaniem (decyzja, co zrobić) a działaniem (używanie narzędzi). Ten wzorzec pozwala na autonomiczne rozwiązywanie problemów, a nie tylko reagowanie na polecenia. -### Opisy narzędzi są ważne +### Opisy narzędzi mają znaczenie -Jakość opisów narzędzi bezpośrednio wpływa na to, jak dobrze agent je wykorzystuje. Jasne, precyzyjne opisy pomagają modelowi zrozumieć, kiedy i jak wywołać każde narzędzie. +Jakość opisów narzędzi bezpośrednio wpływa na to, jak dobrze agent je wykorzystuje. Jasne i konkretne opisy pomagają modelowi zrozumieć, kiedy i jak wywołać każde narzędzie. -### Zarządzanie sesjami +### Zarządzanie sesją -Adnotacja `@MemoryId` umożliwia automatyczne zarządzanie pamięcią na bazie sesji. Każde ID sesji ma własną instancję `ChatMemory` zarządzaną przez bean `ChatMemoryProvider`, dzięki czemu wielu użytkowników może korzystać z agenta równocześnie bez mieszania się rozmów. Poniższy diagram pokazuje, jak wielu użytkowników jest kierowanych do izolowanych pamięci na podstawie ich identyfikatorów sesji: +Adnotacja `@MemoryId` umożliwia automatyczne zarządzanie pamięcią na podstawie sesji. Każdemu ID sesji przypisywana jest własna instancja `ChatMemory`, zarządzana przez bean `ChatMemoryProvider`, dzięki czemu wielu użytkowników może równocześnie korzystać z agenta bez mieszania rozmów. Poniższy diagram pokazuje, jak wielu użytkowników jest kierowanych do odizolowanych magazynów pamięci na bazie ich ID sesji: Zarządzanie sesją z @MemoryId -*Każde ID sesji odpowiada izolowanej historii rozmowy — użytkownicy nigdy nie widzą wiadomości innych.* +*Każde ID sesji mapuje się na oddzielną historię rozmowy — użytkownicy nigdy nie widzą wiadomości innych.* ### Obsługa błędów -Narzędzia mogą zawieść — API mogą przekroczyć limit czasu, parametry mogą być nieprawidłowe, usługi zewnętrzne mogą przestać działać. Agenci produkcyjni potrzebują obsługi błędów, aby model mógł wyjaśnić problemy lub spróbować alternatyw, zamiast zawieszać całą aplikację. Gdy narzędzie wyrzuca wyjątek, LangChain4j go łapie i przekazuje komunikat o błędzie z powrotem do modelu, który może wtedy wytłumaczyć problem w języku naturalnym. +Narzędzia mogą zawodzić — API mogą mieć timeouty, parametry mogą być nieprawidłowe, zewnętrzne usługi mogą przestać działać. Agent produkcyjny potrzebuje obsługi błędów, żeby model mógł wyjaśnić problemy lub spróbować alternatyw, zamiast wywoływać awarię całej aplikacji. Kiedy narzędzie zgłasza wyjątek, LangChain4j go przechwytuje i przekazuje wiadomość o błędzie do modelu, który może następnie wyjaśnić problem w naturalnym języku. ## Dostępne narzędzia -Poniższy diagram pokazuje szeroki ekosystem narzędzi, które można tworzyć. Ten moduł demonstruje narzędzia pogodowe i do konwersji temperatur, lecz ten sam wzorzec `@Tool` działa dla dowolnej metody w Javie — od zapytań do bazy danych po przetwarzanie płatności. +Poniższy diagram przedstawia szeroki ekosystem narzędzi, które możesz tworzyć. Ten moduł demonstruje narzędzia pogodowe i do konwersji temperatur, ale ten sam wzorzec `@Tool` działa dla każdej metody Java — od zapytań do baz danych po przetwarzanie płatności. Ekosystem narzędzi -*Każda metoda Javy z adnotacją @Tool staje się dostępna dla AI — wzorzec obejmuje bazy danych, API, e-maile, operacje na plikach i więcej.* +*Każda metoda Java opatrzona adnotacją @Tool staje się dostępna dla AI — wzorzec rozciąga się na bazy danych, API, e-maile, operacje na plikach i więcej.* ## Kiedy używać agentów opartych na narzędziach -Nie każde zapytanie wymaga narzędzi. Decyzja zależy od tego, czy AI musi wchodzić w interakcję z systemami zewnętrznymi czy potrafi odpowiedzieć na podstawie własnej wiedzy. Poniższy przewodnik podsumowuje, kiedy narzędzia są przydatne, a kiedy zbędne: +Nie każde zapytanie wymaga narzędzi. Decyzja zależy od tego, czy AI musi wchodzić w interakcję z zewnętrznymi systemami, czy może odpowiedzieć na podstawie własnej wiedzy. Poniższy przewodnik podsumowuje, kiedy narzędzia są wartościowe, a kiedy zbędne: Kiedy używać narzędzi -*Szybki przewodnik — narzędzia do danych na żywo, obliczeń i działań; wiedza ogólna i zadania kreatywne nie wymagają ich.* +*Szybki przewodnik decyzyjny — narzędzia są do danych w czasie rzeczywistym, obliczeń i akcji; ogólna wiedza i zadania kreatywne ich nie potrzebują.* -## Narzędzia vs RAG +## Narzędzia a RAG -Moduły 03 i 04 rozszerzają możliwości AI, ale w zasadniczo różnych aspektach. RAG daje modelowi dostęp do **wiedzy** przez wyszukiwanie dokumentów. Narzędzia dają modelowi możliwość podejmowania **działań** przez wywoływanie funkcji. Poniższy diagram porównuje oba podejścia obok siebie — od sposobu działania każdego z nich po kompromisy między nimi: +Moduły 03 i 04 rozszerzają możliwości AI, ale w fundamentalnie różny sposób. RAG daje modelowi dostęp do **wiedzy** przez pobieranie dokumentów. Narzędzia dają modelowi możliwość wykonywania **akcji** przez wywoływanie funkcji. Poniższy diagram porównuje oba podejścia obok siebie — od sposobu działania każdego do kompromisów między nimi: Porównanie Narzędzi i RAG -*RAG pobiera informacje ze statycznych dokumentów — narzędzia wykonują działania i pobierają dane dynamiczne, w czasie rzeczywistym. Wiele systemów produkcyjnych łączy oba podejścia.* +*RAG pobiera informacje z dokumentów statycznych — Narzędzia wykonują akcje i pobierają dane dynamiczne, w czasie rzeczywistym. Wiele systemów produkcyjnych łączy oba podejścia.* -W praktyce wiele systemów produkcyjnych łączy oba podejścia: RAG do osadzania odpowiedzi w dokumentacji oraz Narzędzia do pobierania danych na żywo lub wykonywania operacji. +W praktyce wiele systemów produkcyjnych łączy oba podejścia: RAG do zakorzeniania odpowiedzi w dokumentacji oraz Narzędzia do pobierania danych na żywo lub wykonywania operacji. ## Kolejne kroki @@ -382,6 +382,6 @@ W praktyce wiele systemów produkcyjnych łączy oba podejścia: RAG do osadzani --- -**Zastrzeżenie**: -Ten dokument został przetłumaczony przy użyciu usługi tłumaczeń AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mimo że dążymy do jak największej dokładności, prosimy mieć na uwadze, że tłumaczenia automatyczne mogą zawierać błędy lub niedokładności. Oryginalny dokument w języku źródłowym należy traktować jako źródło autorytatywne. W przypadku istotnych informacji zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonane przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia. +**Zastrzeżenie**: +Niniejszy dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Choć dążymy do dokładności, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub niedokładności. Oryginalny dokument w jego języku źródłowym należy uznawać za autorytatywne źródło. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia. \ No newline at end of file diff --git a/translations/pl/README.md b/translations/pl/README.md index 8f5d4bee9..0c9949faf 100644 --- a/translations/pl/README.md +++ b/translations/pl/README.md @@ -4,16 +4,16 @@ Kurs tworzenia aplikacji AI z LangChain4j i Azure OpenAI GPT-5.2, od podstawowego czatu po agentów AI. -### 🌐 Wielojęzyczne wsparcie +### 🌐 Wsparcie wielojęzyczne #### Obsługiwane przez GitHub Action (Automatyczne i zawsze aktualne) -[Arabski](../ar/README.md) | [Bengalski](../bn/README.md) | [Bułgarski](../bg/README.md) | [Birmański (Myanmar)](../my/README.md) | [Chiński (uproszczony)](../zh-CN/README.md) | [Chiński (tradycyjny, Hongkong)](../zh-HK/README.md) | [Chiński (tradycyjny, Makau)](../zh-MO/README.md) | [Chiński (tradycyjny, Tajwan)](../zh-TW/README.md) | [Chorwacki](../hr/README.md) | [Czeski](../cs/README.md) | [Duński](../da/README.md) | [Holenderski](../nl/README.md) | [Estoński](../et/README.md) | [Fiński](../fi/README.md) | [Francuski](../fr/README.md) | [Niemiecki](../de/README.md) | [Grecki](../el/README.md) | [Hebrajski](../he/README.md) | [Hinduski](../hi/README.md) | [Węgierski](../hu/README.md) | [Indonezyjski](../id/README.md) | [Włoski](../it/README.md) | [Japoński](../ja/README.md) | [Kannada](../kn/README.md) | [Khmerski](../km/README.md) | [Koreański](../ko/README.md) | [Litewski](../lt/README.md) | [Malajski](../ms/README.md) | [Malajalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalski](../ne/README.md) | [Nigeryjski pidgin](../pcm/README.md) | [Norweski](../no/README.md) | [Perski (Farsi)](../fa/README.md) | [Polski](./README.md) | [Portugalski (Brazylia)](../pt-BR/README.md) | [Portugalski (Portugalia)](../pt-PT/README.md) | [Pandźabski (Gurmukhi)](../pa/README.md) | [Rumuński](../ro/README.md) | [Rosyjski](../ru/README.md) | [Serbski (cyrylica)](../sr/README.md) | [Słowacki](../sk/README.md) | [Słoweński](../sl/README.md) | [Hiszpański](../es/README.md) | [Suahili](../sw/README.md) | [Szwedzki](../sv/README.md) | [Tagalog (Filipiński)](../tl/README.md) | [Tamilski](../ta/README.md) | [Telugu](../te/README.md) | [Tajski](../th/README.md) | [Turecki](../tr/README.md) | [Ukraiński](../uk/README.md) | [Urdu](../ur/README.md) | [Wietnamski](../vi/README.md) +[Arabski](../ar/README.md) | [Bengalski](../bn/README.md) | [Bułgarski](../bg/README.md) | [Birmański (Myanmar)](../my/README.md) | [Chiński (uproszczony)](../zh-CN/README.md) | [Chiński (tradycyjny, Hongkong)](../zh-HK/README.md) | [Chiński (tradycyjny, Makau)](../zh-MO/README.md) | [Chiński (tradycyjny, Tajwan)](../zh-TW/README.md) | [Chorwacki](../hr/README.md) | [Czeski](../cs/README.md) | [Duński](../da/README.md) | [Niderlandzki](../nl/README.md) | [Estoński](../et/README.md) | [Fiński](../fi/README.md) | [Francuski](../fr/README.md) | [Niemiecki](../de/README.md) | [Grecki](../el/README.md) | [Hebrajski](../he/README.md) | [Hindi](../hi/README.md) | [Węgierski](../hu/README.md) | [Indonezyjski](../id/README.md) | [Włoski](../it/README.md) | [Japoński](../ja/README.md) | [Kannada](../kn/README.md) | [Khmerski](../km/README.md) | [Koreański](../ko/README.md) | [Litewski](../lt/README.md) | [Malajski](../ms/README.md) | [Malajalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalski](../ne/README.md) | [Pidgin nigeryjski](../pcm/README.md) | [Norweski](../no/README.md) | [Perski (farsi)](../fa/README.md) | [Polski](./README.md) | [Portugalski (Brazylia)](../pt-BR/README.md) | [Portugalski (Portugalia)](../pt-PT/README.md) | [Pendżabski (Gurmukhi)](../pa/README.md) | [Rumuński](../ro/README.md) | [Rosyjski](../ru/README.md) | [Serbski (cyrylica)](../sr/README.md) | [Słowacki](../sk/README.md) | [Słoweński](../sl/README.md) | [Hiszpański](../es/README.md) | [Suahili](../sw/README.md) | [Szwedzki](../sv/README.md) | [Tagalog (filipiński)](../tl/README.md) | [Tamilski](../ta/README.md) | [Telugu](../te/README.md) | [Tajski](../th/README.md) | [Turecki](../tr/README.md) | [Ukraiński](../uk/README.md) | [Urdu](../ur/README.md) | [Wietnamski](../vi/README.md) > **Wolisz sklonować lokalnie?** > -> To repozytorium zawiera ponad 50 tłumaczeń językowych, co znacznie zwiększa rozmiar pobierania. Aby sklonować bez tłumaczeń, użyj sparse checkout: +> To repozytorium zawiera 50+ tłumaczeń językowych, co znacznie zwiększa rozmiar pobierania. Aby sklonować bez tłumaczeń, użyj sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,25 +29,24 @@ Kurs tworzenia aplikacji AI z LangChain4j i Azure OpenAI GPT-5.2, od podstawoweg > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> To zapewnia wszystko, co potrzebne do ukończenia kursu, z dużo szybszym pobieraniem. +> Dzięki temu otrzymujesz wszystko, co potrzebne do ukończenia kursu, przy znacznie szybszym pobieraniu. ## Spis treści -1. [Szybki start](00-quick-start/README.md) - Rozpocznij pracę z LangChain4j -2. [Wprowadzenie](01-introduction/README.md) - Poznaj podstawy LangChain4j -3. [Inżynieria promptów](02-prompt-engineering/README.md) - Opanuj efektywne projektowanie promptów -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Twórz inteligentne systemy bazujące na wiedzy -5. [Narzędzia](04-tools/README.md) - Integruj narzędzia zewnętrzne i proste asystenty -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Pracuj z protokołem Model Context Protocol (MCP) i modułami agentowymi +1. [Wprowadzenie](01-introduction/README.md) - Poznaj podstawy LangChain4j +2. [Inżynieria promptów](02-prompt-engineering/README.md) - Opanuj skuteczne projektowanie promptów +3. [RAG (Generowanie z wsparciem wyszukiwania)](03-rag/README.md) - Buduj inteligentne systemy oparte na wiedzy +4. [Narzędzia](04-tools/README.md) - Integruj zewnętrzne narzędzia i proste asystenty +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Pracuj z Modelem Protokołu Kontekstu (MCP) i modułami agentskimi -### Przejścia wideo +### Przewodniki wideo -Każdy moduł ma sesję na żywo, podczas której omawiamy koncepcje i kod krok po kroku. +Każdy moduł ma towarzyszącą sesję na żywo, w której krok po kroku omawiamy koncepcje i kod. | Moduł | Wideo | |--------|-------| -| 01 - Wprowadzenie | [Rozpoczęcie pracy z LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 01 - Wprowadzenie | [Rozpoczęcie z LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - Inżynieria promptów | [Inżynieria promptów z LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG z LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Narzędzia & 05 - MCP | [Agenci AI z narzędziami i MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | @@ -56,34 +55,34 @@ Każdy moduł ma sesję na żywo, podczas której omawiamy koncepcje i kod krok ## Ścieżka nauki -**Nowy w LangChain4j?** Sprawdź [Słownik](docs/GLOSSARY.md) dla definicji kluczowych terminów i pojęć. +**Nowy w LangChain4j?** Zapoznaj się z [Słownikiem](docs/GLOSSARY.md) definicji kluczowych terminów i pojęć. > **Szybki start** -1. Utwórz fork tego repozytorium na swoje konto GitHub -2. Kliknij **Code** → zakładka **Codespaces** → **...** → **New with options...** -3. Użyj domyślnych ustawień – wybierze to kontener programistyczny stworzony na potrzeby tego kursu +1. Sklonuj to repozytorium do swojego konta GitHub +2. Kliknij **Code** → zakładkę **Codespaces** → **...** → **Nowy z opcjami...** +3. Użyj domyślnych ustawień – to wybierze kontener developerski stworzony na potrzeby tego kursu 4. Kliknij **Create codespace** 5. Poczekaj 5-10 minut, aż środowisko będzie gotowe -6. Przejdź bezpośrednio do [Szybkiego startu](./00-quick-start/README.md), aby rozpocząć! +6. Przejdź od razu do [Wprowadzenia](./01-introduction/README.md), aby zacząć! -Po ukończeniu modułów zapoznaj się z [Przewodnikiem testowania](docs/TESTING.md), aby zobaczyć koncepcje testowania LangChain4j w praktyce. +Po ukończeniu modułów, przejrzyj [Przewodnik testowania](docs/TESTING.md), aby zobaczyć koncepcje testowania LangChain4j w praktyce. -> **Uwaga:** Szkolenie korzysta z modeli GitHub i Azure OpenAI. Moduł [Szybki start](00-quick-start/README.md) używa modeli GitHub (nie wymaga subskrypcji Azure), natomiast moduły 1-5 używają Azure OpenAI. Zacznij od [DARMOWEGO konta Azure](https://aka.ms/azure-free-account), jeśli jeszcze go nie masz. +> **Uwaga:** Szkolenie korzysta z Azure OpenAI. Zacznij od [BEZPŁATNEGO konta Azure](https://aka.ms/azure-free-account), jeśli jeszcze go nie masz. ## Nauka z GitHub Copilot -Aby szybko zacząć kodować, otwórz ten projekt w GitHub Codespace lub w lokalnym IDE z użyciem dostarczonego devcontainera. Devcontainer używany w tym kursie jest wstępnie skonfigurowany z GitHub Copilot do AI w programowaniu zespołowym. +Aby szybko zacząć kodować, otwórz ten projekt w GitHub Codespace lub swoim lokalnym IDE z dostarczonym devcontainer. Devcontainer użyty w tym kursie jest wstępnie skonfigurowany z GitHub Copilot do programowania w parach z AI. -Każdy przykład kodu zawiera sugerowane pytania, które możesz zadać GitHub Copilot, aby pogłębić zrozumienie. Szukaj wskazówek 💡/🤖 w: +Każdy przykład kodu zawiera sugerowane pytania, które możesz zadać GitHub Copilot, aby pogłębić swoją wiedzę. Szukaj podpowiedzi 💡/🤖 w: -- **nagłówkach plików Java** - pytania specyficzne dla każdego przykładu -- **plikach README modułów** - sugestie do eksploracji po przykładach kodu +- **Nagłówkach plików Java** – pytania specyficzne dla każdego przykładu +- **Plikach README modułów** – pytania do eksploracji po przykładach kodu -**Jak używać:** Otwórz dowolny plik z kodem i zadaj Copilotowi zasugerowane pytania. Ma pełen kontekst bazy kodu i może wyjaśniać, rozszerzać oraz sugerować alternatywy. +**Jak używać:** Otwórz dowolny plik z kodem i zadaj Copilotowi proponowane pytania. Ma pełny kontekst kodu i potrafi wyjaśniać, rozszerzać i sugerować alternatywy. -Chcesz wiedzieć więcej? Sprawdź [Copilot do programowania zespołowego AI](https://aka.ms/GitHubCopilotAI). +Chcesz się dowiedzieć więcej? Sprawdź [Copilot do programowania w parach z AI](https://aka.ms/GitHubCopilotAI). ## Dodatkowe zasoby @@ -103,48 +102,49 @@ Chcesz wiedzieć więcej? Sprawdź [Copilot do programowania zespołowego AI](ht --- -### Seria Generatywnego AI -[![Generatywne AI dla początkujących](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generatywne AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generatywne AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generatywne AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Seria Generatywnej AI +[![Generatywna AI dla początkujących](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generatywna AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generatywna AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generatywna AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Podstawy nauki +### Podstawowa nauka [![ML dla początkujących](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science dla początkujących](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI dla początkujących](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Cyberbezpieczeństwo dla początkujących](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Web Dev dla początkujących](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT dla początkujących](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR Development dla początkujących](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Seria Copilot -[![Copilot do programowania w parach z AI](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot dla C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Przygoda z Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## Uzyskanie pomocy +## Uzyskiwanie pomocy Jeśli utkniesz lub masz pytania dotyczące tworzenia aplikacji AI, dołącz do: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Jeśli masz uwagi dotyczące produktu lub napotkasz błędy podczas tworzenia, odwiedź: +Jeśli masz opinie o produkcie lub napotykasz błędy podczas tworzenia, odwiedź: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licencja -Licencja MIT - szczegóły w pliku [LICENSE](../../LICENSE). +Licencja MIT - zobacz plik [LICENSE](../../LICENSE) po szczegóły. --- -**Zastrzeżenie**: -Ten dokument został przetłumaczony przy użyciu usługi tłumaczeń AI [Co-op Translator](https://github.com/Azure/co-op-translator). Chociaż dążymy do dokładności, pamiętaj, że tłumaczenia automatyczne mogą zawierać błędy lub nieścisłości. Oryginalny dokument w jego ojczystym języku powinien być uważany za źródło autorytatywne. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia. +**Zastrzeżenie**: +Niniejszy dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Choć dążymy do dokładności, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub niedokładności. Oryginalny dokument w jego języku źródłowym należy uznawać za autorytatywne źródło. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia. \ No newline at end of file diff --git a/translations/pl/docs/GLOSSARY.md b/translations/pl/docs/GLOSSARY.md index 12fb558ad..9c13a91ac 100644 --- a/translations/pl/docs/GLOSSARY.md +++ b/translations/pl/docs/GLOSSARY.md @@ -2,59 +2,59 @@ ## Spis treści -- [Podstawowe pojęcia](../../../docs) -- [Komponenty LangChain4j](../../../docs) -- [Pojęcia AI/ML](../../../docs) -- [Zabezpieczenia](../../../docs) -- [Inżynieria promptów](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agenci i narzędzia](../../../docs) -- [Moduł Agentic](../../../docs) -- [Protokół kontekstu modelu (MCP)](../../../docs) -- [Usługi Azure](../../../docs) -- [Testowanie i rozwój](../../../docs) - -Szybkie odniesienie do terminów i pojęć używanych w całym kursie. +- [Podstawowe pojęcia](#podstawowe-pojęcia) +- [Komponenty LangChain4j](#komponenty-langchain4j) +- [Pojęcia AI/ML](#pojęcia-aiml) +- [Zabezpieczenia](#zabezpieczenia) +- [Inżynieria promptów](#prompt-engineering---module-02) +- [RAG (Generowanie wspomagane wyszukiwaniem)](#rag-retrieval-augmented-generation---module-03) +- [Agenci i narzędzia](#agents-and-tools---module-04) +- [Moduł Agentic](#agentic-module---module-05) +- [Protokół kontekstu modelu (MCP)](#model-context-protocol-mcp---module-05) +- [Usługi Azure](#azure-services---module-01) +- [Testowanie i rozwój](#testing-and-development---testing-guide) + +Szybkie odniesienie do terminów i pojęć używanych w trakcie kursu. ## Podstawowe pojęcia -**Agent AI** - System wykorzystujący AI do autonomicznego rozumowania i działania. [Moduł 04](../04-tools/README.md) +**Agent AI** - System wykorzystujący AI do samodzielnego rozumowania i działania. [Moduł 04](../04-tools/README.md) -**Chain** - Sekwencja operacji, gdzie wyjście jest podawane do następnego kroku. +**Łańcuch** - Sekwencja operacji, w której wyjście zasila następny krok. -**Chunking** - Dzielenie dokumentów na mniejsze fragmenty. Typowe: 300-500 tokenów z nakładką. [Moduł 03](../03-rag/README.md) +**Dzielenie na kawałki** - Dzielnie dokumentów na mniejsze części. Typowo: 300-500 tokenów z nakładką. [Moduł 03](../03-rag/README.md) -**Okno kontekstu** - Maksymalna liczba tokenów, które model może przetworzyć. GPT-5.2: 400 tys. tokenów (do 272 tys. na wejściu, 128 tys. na wyjściu). +**Okno kontekstu** - Maksymalna liczba tokenów, które model może przetworzyć. GPT-5.2: 400K tokenów (do 272K wejścia, 128K wyjścia). -**Wektory osadzeń (embeddings)** - Numeryczne wektory reprezentujące znaczenie tekstu. [Moduł 03](../03-rag/README.md) +**Wektory osadzeń (Embeddings)** - Numeryczne wektory reprezentujące znaczenie tekstu. [Moduł 03](../03-rag/README.md) -**Wywołanie funkcji** - Model generuje ustrukturyzowane żądania do wywołania funkcji zewnętrznych. [Moduł 04](../04-tools/README.md) +**Wywołanie funkcji** - Model generuje strukturalne żądania wywołania funkcji zewnętrznych. [Moduł 04](../04-tools/README.md) -**Halucynacje** - Gdy modele generują niepoprawne, ale wiarygodne informacje. +**Halucynacje** - Gdy modele generują nieprawdziwe, lecz wiarygodne informacje. -**Prompt** - Tekst wejściowy do modelu językowego. [Moduł 02](../02-prompt-engineering/README.md) +**Prompt** - Tekstowy input do modelu językowego. [Moduł 02](../02-prompt-engineering/README.md) -**Wyszukiwanie semantyczne** - Wyszukiwanie według znaczenia z użyciem embeddings, a nie słów kluczowych. [Moduł 03](../03-rag/README.md) +**Wyszukiwanie semantyczne** - Szukanie po znaczeniu używając embeddings, a nie słów kluczowych. [Moduł 03](../03-rag/README.md) -**Stanowy vs bezstanowy** - Bezstanowy: brak pamięci. Stanowy: utrzymuje historię rozmowy. [Moduł 01](../01-introduction/README.md) +**Stanowe vs bezstanowe** - Bezstanowe: brak pamięci. Stanowe: utrzymuje historię rozmowy. [Moduł 01](../01-introduction/README.md) -**Tokeny** - Podstawowe jednostki tekstu przetwarzane przez modele. Wpływa na koszty i limity. [Moduł 01](../01-introduction/README.md) +**Tokeny** - Podstawowe jednostki tekstu przetwarzane przez modele. Wpływają na koszty i limity. [Moduł 01](../01-introduction/README.md) -**Łańcuchowanie narzędzi** - Wykonywanie narzędzi po kolei, gdzie wyjście informuje kolejne wywołanie. [Moduł 04](../04-tools/README.md) +**Łączenie narzędzi** - Sekwencyjne wykonywanie narzędzi, gdzie wyjście służy do kolejnego wywołania. [Moduł 04](../04-tools/README.md) ## Komponenty LangChain4j -**AiServices** - Tworzy bezpieczne typowo interfejsy usług AI. +**AiServices** - Tworzy typowo-bezpieczne interfejsy usług AI. -**OpenAiOfficialChatModel** - Zunifikowany klient dla modeli OpenAI i Azure OpenAI. +**OpenAiOfficialChatModel** - Ujednolicony klient dla modeli OpenAI i Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Tworzy embeddings z użyciem oficjalnego klienta OpenAI (obsługuje OpenAI i Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Tworzy embeddings używając oficjalnego klienta OpenAI (obsługuje OpenAI oraz Azure OpenAI). -**ChatModel** - Główny interfejs modeli językowych. +**ChatModel** - Główny interfejs dla modeli językowych. **ChatMemory** - Utrzymuje historię rozmowy. -**ContentRetriever** - Znajduje istotne fragmenty dokumentów do RAG. +**ContentRetriever** - Znajduje odpowiednie kawałki dokumentów dla RAG. **DocumentSplitter** - Dzieli dokumenty na fragmenty. @@ -62,133 +62,133 @@ Szybkie odniesienie do terminów i pojęć używanych w całym kursie. **EmbeddingStore** - Przechowuje i pobiera embeddings. -**MessageWindowChatMemory** - Utrzymuje przesuwane okno ostatnich wiadomości. +**MessageWindowChatMemory** - Utrzymuje przesuwne okno ostatnich wiadomości. -**PromptTemplate** - Tworzy wielokrotnego użytku prompt z miejscami na zmienne `{{variable}}`. +**PromptTemplate** - Tworzy wielokrotnego użytku prompt-y z `{{zmienna}}` jako miejscem na dane. **TextSegment** - Fragment tekstu z metadanymi. Używany w RAG. **ToolExecutionRequest** - Reprezentuje żądanie wykonania narzędzia. -**UserMessage / AiMessage / SystemMessage** - Typy wiadomości konwersacji. +**UserMessage / AiMessage / SystemMessage** - Typy wiadomości w rozmowie. ## Pojęcia AI/ML -**Uczenie Few-Shot** - Dostarczanie przykładów w promptach. [Moduł 02](../02-prompt-engineering/README.md) +**Uczenie na kilku przykładach (Few-Shot Learning)** - Podawanie przykładów w promptach. [Moduł 02](../02-prompt-engineering/README.md) -**Duży Model Językowy (LLM)** - Modele AI trenowane na ogromnych zbiorach tekstów. +**Duży model językowy (LLM)** - Modele AI wytrenowane na ogromnej ilości danych tekstowych. -**Wysiłek rozumowania** - Parametr GPT-5.2 kontrolujący głębokość myślenia. [Moduł 02](../02-prompt-engineering/README.md) +**Wysiłek rozumowania** - Parametr GPT-5.2 kontrolujący głębokość rozumowania. [Moduł 02](../02-prompt-engineering/README.md) **Temperatura** - Kontroluje losowość wyjścia. Niska=deterministyczne, wysoka=kreatywne. -**Baza danych wektorowych** - Specjalistyczna baza dla embeddings. [Moduł 03](../03-rag/README.md) +**Baza danych wektorów** - Specjalistyczna baza dla embeddings. [Moduł 03](../03-rag/README.md) -**Uczenie Zero-Shot** - Wykonywanie zadań bez przykładów. [Moduł 02](../02-prompt-engineering/README.md) +**Uczenie zerowego przykładu (Zero-Shot Learning)** - Wykonywanie zadań bez przykładów. [Moduł 02](../02-prompt-engineering/README.md) -## Zabezpieczenia - [Moduł 00](../00-quick-start/README.md) +## Zabezpieczenia -**Obrona w głębokości** - Wielowarstwowe podejście do bezpieczeństwa łączące zabezpieczenia na poziomie aplikacji z filtrami bezpieczeństwa dostawcy. +**Obrona warstwowa** - Wielowarstwowe podejście zabezpieczeń łączące zabezpieczenia na poziomie aplikacji z filtrami bezpieczeństwa dostawcy. -**Twardy blok** - Dostawca zwraca błąd HTTP 400 przy poważnych naruszeniach treści. +**Blokada krytyczna** - Dostawca zwraca błąd HTTP 400 dla poważnych naruszeń treści. -**InputGuardrail** - Interfejs LangChain4j do walidacji danych wejściowych użytkownika zanim dotrą do LLM. Oszczędza koszty i latencję blokując szkodliwe prompt-y na wczesnym etapie. +**InputGuardrail** - Interfejs LangChain4j walidujący dane wejściowe użytkownika zanim dotrą do LLM. Oszczędza koszty i opóźnienia blokując szkodliwe prompt-y na wczesnym etapie. -**InputGuardrailResult** - Typ zwracany walidacji guardrail: `success()` lub `fatal("powód")`. +**InputGuardrailResult** - Typ zwracany przez walidację guardrail: `success()` lub `fatal("powód")`. -**OutputGuardrail** - Interfejs do walidacji odpowiedzi AI przed zwróceniem użytkownikom. +**OutputGuardrail** - Interfejs walidujący odpowiedzi AI przed przekazaniem użytkownikom. -**Filtry bezpieczeństwa dostawcy** - Wbudowane filtry treści od dostawców AI (np. GitHub Models) wykrywające naruszenia na poziomie API. +**Filtry bezpieczeństwa dostawcy** - Wbudowane filtry treści od dostawców AI (np. Azure OpenAI) wykrywające naruszenia na poziomie API. -**Miękka odmowa** - Model grzecznie odmawia odpowiedzi bez wyrzucania błędu. +**Łagodne odmowa** - Model uprzejmie odmawia odpowiedzi bez zgłaszania błędu. ## Inżynieria promptów - [Moduł 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Rozumowanie krok po kroku dla lepszej dokładności. +**Chain-of-Thought (łańcuch myślowy)** - Krok po kroku rozumowanie dla lepszej dokładności. -**Wymuszone wyjście** - Wymuszanie konkretnego formatu lub struktury. +**Ograniczone wyjście** - Wymuszanie określonego formatu lub struktury. -**Wysoka wnikliwość** - Wzorzec GPT-5.2 dla dokładnego rozumowania. +**Wysoka dokładność** - Wzorzec GPT-5.2 dla dogłębnego rozumowania. -**Niska wnikliwość** - Wzorzec GPT-5.2 dla szybkich odpowiedzi. +**Niska dokładność** - Wzorzec GPT-5.2 dla szybkich odpowiedzi. -**Konwersacja wieloetapowa** - Utrzymywanie kontekstu przez wymiany. +**Wieloturnowa rozmowa** - Utrzymywanie kontekstu przez wymianę wiadomości. -**Promptowanie oparte na roli** - Ustawianie persony modelu za pomocą komunikatów systemowych. +**Promptowanie oparte na roli** - Ustawianie persony modelu poprzez wiadomości systemowe. -**Autoanaliza** - Model ocenia i poprawia swoje wyjście. +**Auto-refleksja** - Model ocenia i poprawia swoje wyjście. -**Strukturalna analiza** - Stały szablon ewaluacji. +**Analiza strukturalna** - Stałe ramy ewaluacyjne. **Wzorzec wykonania zadania** - Planowanie → Wykonanie → Podsumowanie. -## RAG (Retrieval-Augmented Generation) - [Moduł 03](../03-rag/README.md) +## RAG (Generowanie wspomagane wyszukiwaniem) - [Moduł 03](../03-rag/README.md) -**Proces przetwarzania dokumentów** - Ładuj → dziel na fragmenty → osadź → przechowuj. +**Pipeline przetwarzania dokumentów** - Załaduj → podziel → zakotwicz → przechowuj. -**In-memory Embedding Store** - Pamięć tymczasowa do testów. +**Pamięć podręczna embeddingów w pamięci (In-Memory Embedding Store)** - Nieperzystentne przechowywanie do testów. -**RAG** - Łączy wyszukiwanie z generowaniem by ugruntować odpowiedzi. +**RAG** - Łączy wyszukiwanie z generowaniem, by ugruntować odpowiedzi. -**Współczynnik podobieństwa** - Miarę (0-1) podobieństwa semantycznego. +**Wskaźnik podobieństwa** - Miara (0-1) semantycznego podobieństwa. -**Odniesienie źródłowe** - Metadane o pobranej zawartości. +**Źródłowa referencja** - Metadane o znalezionym materiale. ## Agenci i narzędzia - [Moduł 04](../04-tools/README.md) **Adnotacja @Tool** - Oznacza metody Java jako narzędzia wywoływane przez AI. -**Wzorzec ReAct** - Rozumuj → Działaj → Obserwuj → Powtórz. +**Wzorzec ReAct** - Rozumuj → Działaj → Obserwuj → Powtarzaj. -**Zarządzanie sesją** - Oddzielne konteksty dla różnych użytkowników. +**Zarządzanie sesjami** - Oddzielne konteksty dla różnych użytkowników. -**Narzędzie (Tool)** - Funkcja, którą agent AI może wywołać. +**Narzędzie** - Funkcja, którą agent AI może wywołać. -**Opis narzędzia** - Dokumentacja celu i parametrów narzędzia. +**Opis narzędzia** - Dokumentacja celu narzędzia i jego parametrów. ## Moduł Agentic - [Moduł 05](../05-mcp/README.md) **Adnotacja @Agent** - Oznacza interfejsy jako agentów AI z deklaratywną definicją zachowania. -**Agent Listener** - Hook do monitorowania wykonania agenta przez `beforeAgentInvocation()` i `afterAgentInvocation()`. +**Listener agenta** - Hak do monitorowania wykonania agenta poprzez `beforeAgentInvocation()` i `afterAgentInvocation()`. -**Zakres Agentic** - Wspólna pamięć, w której agenci przechowują wyniki używając `outputKey` do konsumpcji przez innych agentów. +**Zakres agentic** - Wspólna pamięć, gdzie agenci zapisują wyniki używając `outputKey` do dalszego wykorzystania przez innych agentów. -**AgenticServices** - Fabryka do tworzenia agentów za pomocą `agentBuilder()` i `supervisorBuilder()`. +**AgenticServices** - Fabryka tworząca agentów przez `agentBuilder()` i `supervisorBuilder()`. -**Przepływ warunkowy** - Kierowanie według warunków do różnych agentów specjalistycznych. +**Warunkowy workflow** - Ruch na podstawie warunków do różnych specjalistycznych agentów. -**Człowiek w pętli (Human-in-the-Loop)** - Wzorzec workflow dodający punkt kontrolny człowieka do zatwierdzenia lub przeglądu treści. +**Człowiek w pętli (Human-in-the-Loop)** - Wzorzec workflow dodający ludzkie punkty kontrolne do zatwierdzania lub przeglądu treści. -**langchain4j-agentic** - Zależność Maven do deklaratywnego budowania agentów (eksperymentalne). +**langchain4j-agentic** - Zależność Maven do deklaratywnej budowy agentów (eksperymentalne). -**Przepływ pętli (Loop Workflow)** - Iteracja wykonywania agenta aż do spełnienia warunku (np. ocena jakości ≥ 0.8). +**Pętla workflow (Loop Workflow)** - Iteracja wykonania agenta aż do spełnienia warunku (np. wynik jakości ≥ 0.8). -**outputKey** - Parametr adnotacji agenta określający miejsce przechowywania wyników w Zakresie Agentic. +**outputKey** - Parametr adnotacji agenta wskazujący miejsce zapisu wyników w Zakresie Agentic. -**Przepływ równoległy** - Uruchamianie wielu agentów jednocześnie do niezależnych zadań. +**Równoległy workflow** - Uruchamianie wielu agentów równocześnie dla niezależnych zadań. -**Strategia odpowiedzi** - Sposób formułowania ostatecznej odpowiedzi przez nadzorcę: LAST, SUMMARY lub SCORED. +**Strategia odpowiedzi** - Sposób formułowania ostatecznej odpowiedzi przez supervisor: OSTANIA, PODSUMOWANIE lub OCENIANA. -**Przepływ sekwencyjny** - Wykonywanie agentów kolejno, gdzie wyjście przechodzi do następnego kroku. +**Sekwencyjny workflow** - Wykonanie agentów po kolei, gdzie wyjście przepływa do następnego kroku. -**Wzorzec agenta nadzorującego (Supervisor Agent Pattern)** - Zaawansowany wzorzec agentic, gdzie nadzorca LLM dynamicznie decyduje, których podagentów wywołać. +**Wzorzec agenta supervisor** - Zaawansowany wzorzec, w którym agent supervisor LLM dynamicznie decyduje, których podagentów wywołać. ## Protokół kontekstu modelu (MCP) - [Moduł 05](../05-mcp/README.md) **langchain4j-mcp** - Zależność Maven do integracji MCP w LangChain4j. -**MCP** - Model Context Protocol: standard łączenia aplikacji AI z narzędziami zewnętrznymi. Zbuduj raz, używaj wszędzie. +**MCP** - Protokół kontekstu modelu: standard łączenia aplikacji AI z zewnętrznymi narzędziami. Zbuduj raz, używaj wszędzie. -**MCP Client** - Aplikacja łącząca się z serwerem MCP do odkrywania i używania narzędzi. +**Klient MCP** - Aplikacja łącząca się z serwerami MCP do odkrywania i używania narzędzi. -**MCP Server** - Usługa udostępniająca narzędzia przez MCP z jasnymi opisami i schematami parametrów. +**Serwer MCP** - Usługa udostępniająca narzędzia przez MCP z jasnymi opisami i schematami parametrów. -**McpToolProvider** - Komponent LangChain4j owija narzędzia MCP do użycia w usługach i agentach AI. +**McpToolProvider** - Komponent LangChain4j opakowujący narzędzia MCP dla usług AI i agentów. -**McpTransport** - Interfejs komunikacji MCP. Implementacje to Stdio i HTTP. +**McpTransport** - Interfejs komunikacji MCP. Implementacje to m.in. Stdio i HTTP. -**Stdio Transport** - Lokalny transport procesu przez stdin/stdout. Przydatny do dostępu do systemu plików lub narzędzi CLI. +**Transport Stdio** - Lokalny transport procesu przez stdin/stdout. Przydatny do dostępu do systemu plików lub narzędzi CLI. **StdioMcpTransport** - Implementacja LangChain4j uruchamiająca serwer MCP jako podproces. @@ -196,13 +196,13 @@ Szybkie odniesienie do terminów i pojęć używanych w całym kursie. ## Usługi Azure - [Moduł 01](../01-introduction/README.md) -**Azure AI Search** - Chmurowe wyszukiwanie z możliwością wektorową. [Moduł 03](../03-rag/README.md) +**Azure AI Search** - Chmurowa wyszukiwarka z funkcjami wektorowymi. [Moduł 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Rozmieszcza zasoby Azure. +**Azure Developer CLI (azd)** - Wdraża zasoby Azure. -**Azure OpenAI** - Usługa AI klasy enterprise Microsoft. +**Azure OpenAI** - Usługa AI przedsiębiorstwa Microsoft. -**Bicep** - Język infrastruktury jako kod Azure. [Przewodnik infrastruktury](../01-introduction/infra/README.md) +**Bicep** - Język infrastruktury jako kod dla Azure. [Przewodnik infrastruktury](../01-introduction/infra/README.md) **Nazwa wdrożenia** - Nazwa wdrożenia modelu w Azure. @@ -210,17 +210,15 @@ Szybkie odniesienie do terminów i pojęć używanych w całym kursie. ## Testowanie i rozwój - [Przewodnik testowania](TESTING.md) -**Dev Container** - Konteneryzowane środowisko deweloperskie. [Konfiguracja](../../../.devcontainer/devcontainer.json) +**Dev Container** - Konteneryzowane środowisko programistyczne. [Konfiguracja](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Darmowy plac zabaw AI. [Moduł 00](../00-quick-start/README.md) +**Testowanie w pamięci** - Testowanie z pamięcią tymczasową. -**Testowanie in-memory** - Testowanie z pamięcią tymczasową. +**Testowanie integracyjne** - Testowanie z prawdziwą infrastrukturą. -**Testy integracyjne** - Testowanie z prawdziwą infrastrukturą. +**Maven** - Narzędzie automatyzacji kompilacji Java. -**Maven** - Narzędzie automatyzacji budowania Java. - -**Mockito** - Framework do mockowania w Java. +**Mockito** - Framework do mockowania w Javie. **Spring Boot** - Framework aplikacji Java. [Moduł 01](../01-introduction/README.md) @@ -228,5 +226,5 @@ Szybkie odniesienie do terminów i pojęć używanych w całym kursie. **Zastrzeżenie**: -Dokument ten został przetłumaczony przy użyciu automatycznej usługi tłumaczeniowej AI [Co-op Translator](https://github.com/Azure/co-op-translator). Chociaż dokładamy starań, aby tłumaczenie było precyzyjne, prosimy pamiętać, że tłumaczenia automatyczne mogą zawierać błędy lub nieścisłości. Oryginalny dokument w jego języku źródłowym należy uznać za źródło ostateczne. W przypadku istotnych informacji zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia. +Niniejszy dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Choć dążymy do dokładności, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub niedokładności. Oryginalny dokument w jego języku źródłowym należy uznawać za autorytatywne źródło. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia. \ No newline at end of file diff --git a/translations/pl/docs/TESTING.md b/translations/pl/docs/TESTING.md index 21ab2aeb2..4686be72c 100644 --- a/translations/pl/docs/TESTING.md +++ b/translations/pl/docs/TESTING.md @@ -2,19 +2,19 @@ ## Spis treści -- [Szybki start](../../../docs) -- [Co obejmują testy](../../../docs) -- [Uruchamianie testów](../../../docs) -- [Uruchamianie testów w VS Code](../../../docs) -- [Wzorce testowania](../../../docs) -- [Filozofia testowania](../../../docs) -- [Kolejne kroki](../../../docs) +- [Szybki start](#szybki-start) +- [Co obejmują testy](#co-obejmują-testy) +- [Uruchamianie testów](#uruchamianie-testów) +- [Uruchamianie testów w VS Code](#uruchamianie-testów-w-vs-code) +- [Wzorce testowe](#wzorce-testowe) +- [Filozofia testowania](#filozofia-testowania) +- [Kolejne kroki](#kolejne-kroki) -Ten przewodnik przeprowadzi Cię przez testy, które pokazują, jak testować aplikacje AI bez konieczności posiadania kluczy API lub korzystania z zewnętrznych usług. +Ten przewodnik przeprowadzi Cię przez testy, które pokazują, jak testować aplikacje AI bez potrzeby kluczy API lub usług zewnętrznych. ## Szybki start -Uruchom wszystkie testy jednym poleceniem: +Uruchom wszystkie testy za pomocą jednego polecenia: **Bash:** ```bash @@ -26,28 +26,27 @@ mvn test mvn --% test ``` -Kiedy wszystkie testy przejdą pomyślnie, powinieneś zobaczyć wynik podobny do zrzutu ekranu poniżej — testy uruchomione bez żadnych błędów. +Gdy wszystkie testy zakończą się sukcesem, zobaczysz wyjście podobne do zrzutu ekranu poniżej — testy uruchomione bez żadnych błędów. Successful Test Results -*Pomyslne wykonanie testów pokazujące wszystkie testy z zerową liczbą błędów* +*Udane wykonanie testów pokazujące, że wszystkie testy przeszły bez błędów* ## Co obejmują testy -Ten kurs koncentruje się na **testach jednostkowych** uruchamianych lokalnie. Każdy test demonstruje konkretną koncepcję LangChain4j w izolacji. Piramida testów poniżej pokazuje, gdzie mieszczą się testy jednostkowe — stanowią one szybkie, niezawodne fundamenty, na których opiera się reszta Twojej strategii testowania. +Ten kurs skupia się na **testach jednostkowych** uruchamianych lokalnie. Każdy test demonstruje konkretną koncepcję LangChain4j w izolacji. Poniższa piramida testowa pokazuje, gdzie mieszczą się testy jednostkowe — stanowią one szybkie, niezawodne podstawy, na których opiera się reszta strategii testowej. Testing Pyramid -*Piramida testowania pokazująca równowagę między testami jednostkowymi (szybkie, izolowane), testami integracyjnymi (prawdziwe komponenty) i testami end-to-end. To szkolenie dotyczy testów jednostkowych.* +*Piramida testowa pokazująca równowagę między testami jednostkowymi (szybkie, izolowane), testami integracyjnymi (rzeczywiste komponenty) oraz testami end-to-end. To szkolenie obejmuje testy jednostkowe.* | Moduł | Testy | Skupienie | Kluczowe pliki | |--------|-------|-------|-----------| -| **00 - Szybki start** | 6 | Szablony promptów i podstawienie zmiennych | `SimpleQuickStartTest.java` | -| **01 - Wprowadzenie** | 8 | Pamięć konwersacji i stanowy chat | `SimpleConversationTest.java` | -| **02 - Inżynieria promptów** | 12 | Wzorce GPT-5.2, poziomy chęci, strukturalny output | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Wprowadzanie dokumentów, osadzenia, wyszukiwanie podobieństw | `DocumentServiceTest.java` | +| **01 - Wprowadzenie** | 8 | Pamięć rozmowy i stan czatu | `SimpleConversationTest.java` | +| **02 - Inżynieria podpowiedzi** | 12 | Wzorce GPT-5.2, poziomy gotowości, ustrukturyzowany output | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Wczytywanie dokumentów, osadzanie, wyszukiwanie podobieństw | `DocumentServiceTest.java` | | **04 - Narzędzia** | 12 | Wywoływanie funkcji i łączenie narzędzi | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Protokół kontekstowy modelu z transportem stdio | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | Protokoły kontekstu modelu z transportem stdio | `SimpleMcpTest.java` | ## Uruchamianie testów @@ -63,19 +62,19 @@ mvn test mvn --% test ``` -**Uruchom testy dla wybranego modułu:** +**Uruchom testy dla określonego modułu:** **Bash:** ```bash cd 01-introduction && mvn test -# Lub z katalogu głównego +# Lub od katalogu głównego mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Lub z katalogu głównego +# Lub z root mvn --% test -pl 01-introduction ``` @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Uruchom pojedynczą metodę testową:** +**Uruchom konkretną metodę testową:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#powinienZachowaćHistorięRozmowy +mvn test -Dtest=SimpleConversationTest#powinnoUtrzymywaćHistorięKonwersacji ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#powinnoZachowaćHistorięRozmowy +mvn --% test -Dtest=SimpleConversationTest#powinnoZachowaćHistorięKonwersacji ``` ## Uruchamianie testów w VS Code -Jeśli korzystasz z Visual Studio Code, Test Explorer oferuje graficzny interfejs do uruchamiania i debugowania testów. +Jeśli używasz Visual Studio Code, Eksplorator testów zapewnia graficzny interfejs do uruchamiania i debugowania testów. VS Code Test Explorer -*Test Explorer w VS Code pokazujący drzewo testów ze wszystkimi klasami testowymi Java i poszczególnymi metodami testowymi* +*Eksplorator testów VS Code pokazujący drzewo testów ze wszystkimi klasami testów Java i poszczególnymi metodami testowymi* **Aby uruchomić testy w VS Code:** -1. Otwórz Test Explorer klikając ikonę probówki na pasku aktywności +1. Otwórz Eksplorator testów, klikając ikonę zlewki na pasku aktywności 2. Rozwiń drzewo testów, aby zobaczyć wszystkie moduły i klasy testowe -3. Kliknij przycisk odtwarzania obok dowolnego testu, aby uruchomić go indywidualnie -4. Kliknij "Run All Tests", aby uruchomić cały zestaw -5. Kliknij prawym przyciskiem myszy dowolny test i wybierz "Debug Test", aby ustawić punkty przerwań i krokować po kodzie +3. Kliknij przycisk odtwarzania obok dowolnego testu, aby uruchomić go pojedynczo +4. Kliknij „Run All Tests”, aby wykonać cały zestaw testów +5. Kliknij prawym przyciskiem dowolny test i wybierz „Debug Test”, aby ustawić punkty przerwania i krokować po kodzie -Test Explorer pokazuje zielone znaczniki dla przechodzących testów i dostarcza szczegółowe komunikaty o błędach, gdy testy nie przejdą. +Eksplorator testów pokazuje zielone znaczniki dla zaliczonych testów i dostarcza szczegółowych komunikatów o niepowodzeniach, gdy testy zawiodą. -## Wzorce testowania +## Wzorce testowe -### Wzorzec 1: Testowanie szablonów promptów +### Wzorzec 1: Testowanie szablonów podpowiedzi -Najprostszy wzorzec testuje szablony promptów bez wywoływania jakiegokolwiek modelu AI. Sprawdzasz, czy podstawienie zmiennych działa poprawnie oraz czy prompty są formatowane zgodnie z oczekiwaniami. +Najprostszy wzorzec testuje szablony podpowiedzi bez wywoływania modelu AI. Weryfikujesz, czy substytucja zmiennych działa poprawnie oraz czy podpowiedzi są sformatowane zgodnie z oczekiwaniami. Prompt Template Testing -*Testowanie szablonów promptów pokazujące przepływ podstawiania zmiennych: szablon z miejscami na wartości → zastosowanie wartości → weryfikacja sformatowanego outputu* +*Testowanie szablonów podpowiedzi pokazujące przepływ substytucji zmiennych: szablon z placeholderami → wprowadzone wartości → zweryfikowany sformatowany wynik* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Ten test znajduje się w `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Uruchom go:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testowanieFormatowaniaSzablonuPodpowiedzi -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testowanieFormatowaniaSzablonuPromptu -``` +Ten wzorzec weryfikuje, że substytucja zmiennych działa poprawnie, a podpowiedzi są sformatowane zgodnie z oczekiwaniami — nie wymaga klucza API ani wywołania modelu. ### Wzorzec 2: Mockowanie modeli językowych -Testując logikę konwersacji, użyj Mockito, aby stworzyć fałszywe modele, które zwracają z góry ustalone odpowiedzi. Dzięki temu testy są szybkie, darmowe i deterministyczne. +Podczas testowania logiki rozmowy użyj Mockito do tworzenia fałszywych modeli, które zwracają z góry ustalone odpowiedzi. Sprawia to, że testy są szybkie, darmowe i deterministyczne. Mock vs Real API Comparison -*Porównanie pokazujące, dlaczego do testowania preferuje się mocki: są szybkie, darmowe, deterministyczne i nie wymagają kluczy API* +*Porównanie pokazujące, dlaczego mocki są preferowane do testów: są szybkie, darmowe, deterministyczne i nie wymagają kluczy API* ```java @ExtendWith(MockitoExtension.class) @@ -218,11 +205,11 @@ class SimpleConversationTest { } ``` -Ten wzorzec pojawia się w `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock zapewnia stałe zachowanie, dzięki czemu możesz zweryfikować poprawność zarządzania pamięcią. +Ten wzorzec pojawia się w `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock zapewnia spójne zachowanie, dzięki czemu można zweryfikować poprawność zarządzania pamięcią. ### Wzorzec 3: Testowanie izolacji konwersacji -Pamięć konwersacji musi utrzymywać oddzielnie wielu użytkowników. Ten test weryfikuje, że konwersacje nie mieszają kontekstów. +Pamięć konwersacji musi oddzielać wielu użytkowników. Ten test weryfikuje, że rozmowy nie mieszają ze sobą kontekstów. Conversation Isolation @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Każda konwersacja zachowuje swoją niezależną historię. W systemach produkcyjnych ta izolacja jest kluczowa dla aplikacji wieloużytkownikowych. +Każda rozmowa utrzymuje własną, niezależną historię. W systemach produkcyjnych izolacja ta jest krytyczna dla aplikacji wieloużytkownikowych. ### Wzorzec 4: Testowanie narzędzi niezależnie -Narzędzia to funkcje, które AI może wywoływać. Testuj je bezpośrednio, aby upewnić się, że działają poprawnie, niezależnie od decyzji AI. +Narzędzia to funkcje, które AI może wywoływać. Testuj je bezpośrednio, aby upewnić się, że działają prawidłowo niezależnie od decyzji AI. Tools Testing -*Testowanie narzędzi niezależnie pokazujące wykonanie mockowanego narzędzia bez wywołań AI, w celu weryfikacji logiki biznesowej* +*Testowanie narzędzi niezależnie pokazujące wykonywanie mockowego narzędzia bez wywołań AI, w celu weryfikacji logiki biznesowej* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Te testy z `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` walidują logikę narzędzi bez udziału AI. Przykład łączenia pokazuje, jak output jednego narzędzia zasila input drugiego. +Te testy z `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` walidują logikę narzędzi bez udziału AI. Przykład łańcuchowania pokazuje, jak output jednego narzędzia jest przekazywany jako input do drugiego. ### Wzorzec 5: Testowanie RAG w pamięci -Systemy RAG tradycyjnie wymagają baz wektorowych i usług osadzeń. Wzorzec w pamięci pozwala na testowanie całej pipeline bez zewnętrznych zależności. +Systemy RAG tradycyjnie wymagają baz danych wektorowych i usług osadzania. Wzorzec w pamięci pozwala testować cały pipeline bez zależności zewnętrznych. In-Memory RAG Testing -*Przepływ testowania RAG w pamięci pokazujący analiza dokumentu, przechowywanie osadzeń i wyszukiwanie podobieństw bez potrzeby bazy danych* +*Przepływ testowania RAG w pamięci pokazujący analizę dokumentów, przechowywanie osadzeń i wyszukiwanie podobieństw bez konieczności używania bazy danych* ```java @Test @@ -310,9 +297,9 @@ Ten test z `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentSer ### Wzorzec 6: Testowanie integracji MCP -Moduł MCP testuje integrację Protokołu Kontekstu Modelu używając transportu stdio. Testy weryfikują, że Twoja aplikacja może uruchamiać i komunikować się z serwerami MCP jako podprocesami. +Moduł MCP testuje integrację Model Context Protocol za pomocą transportu stdio. Testy te weryfikują, że Twoja aplikacja może uruchamiać i komunikować się z serwerami MCP jako procesami podrzędnymi. -Testy w `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` potwierdzają zachowanie klienta MCP. +Testy w `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` walidują zachowanie klienta MCP. **Uruchom je:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Filozofia testowania -Testuj swój kod, nie AI. Twoje testy powinny weryfikować kod, który piszesz, sprawdzając jak konstruowane są prompt’y, jak zarządzana jest pamięć i jak wykonywane są narzędzia. Odpowiedzi AI są zmienne i nie powinny być częścią asercji testowych. Pytaj siebie, czy Twój szablon prompta poprawnie podstawia zmienne, a nie czy AI daje właściwą odpowiedź. +Testuj swój kod, a nie AI. Twoje testy powinny weryfikować kod, który piszesz, poprzez sprawdzenie, jak budowane są podpowiedzi, jak zarządzana jest pamięć i jak działają narzędzia. Odpowiedzi AI są zmienne i nie powinny stanowić części asercji testów. Pytaj siebie, czy szablon podpowiedzi poprawnie zastępuje zmienne, a nie czy AI podaje właściwą odpowiedź. -Używaj mocków dla modeli językowych. To zewnętrzne zależności, które są wolne, kosztowne i niedeterministyczne. Mockowanie sprawia, że testy są szybkie (milisekundy zamiast sekund), darmowe (bez kosztów API) i deterministyczne (ten sam wynik za każdym razem). +Używaj mocków dla modeli językowych. Są to zależności zewnętrzne, które są wolne, kosztowne i nie deterministyczne. Mockowanie sprawia, że testy są szybkie (milisekundy zamiast sekund), darmowe (bez kosztów API) oraz deterministyczne (ten sam wynik za każdym razem). -Utrzymuj testy niezależne. Każdy test powinien samodzielnie przygotować dane, nie polegać na innych testach i sprzątać po sobie. Testy powinny przechodzić niezależnie od kolejności uruchomienia. +Utrzymuj testy niezależne. Każdy test powinien sam przygotować swoje dane, nie polegać na innych testach i sprzątać po sobie. Testy powinny przechodzić bez względu na kolejność wykonywania. -Testuj przypadki brzegowe poza szczęśliwą ścieżką. Próbuj pustych danych, bardzo dużych wejść, znaków specjalnych, niepoprawnych parametrów i warunków granicznych. To często odkrywa błędy, których normalne użycie nie ujawnia. +Testuj również przypadki brzegowe, nie tylko ścieżkę szczęścia. Sprawdzaj puste dane, bardzo duże dane, znaki specjalne, nieprawidłowe parametry i warunki graniczne. Często to właśnie one ujawniają błędy, których normalne użycie nie wykrywa. -Używaj opisowych nazw. Porównaj `shouldMaintainConversationHistoryAcrossMultipleMessages()` z `test1()`. Pierwsza nazwa mówi dokładnie, co jest testowane, co znacznie ułatwia debugowanie błędów. +Używaj opisowych nazw. Porównaj `shouldMaintainConversationHistoryAcrossMultipleMessages()` z `test1()`. Pierwsza dokładnie mówi, co jest testowane, co znacznie ułatwia debugowanie błędów. ## Kolejne kroki -Teraz, gdy rozumiesz wzorce testowania, zagłęb się w każdy moduł: +Teraz, gdy znasz wzorce testowe, zagłęb się w każdy moduł: -- **[00 - Szybki start](../00-quick-start/README.md)** - Zacznij od podstaw szablonów promptów -- **[01 - Wprowadzenie](../01-introduction/README.md)** - Naucz się zarządzania pamięcią konwersacji -- **[02 - Inżynieria promptów](../02/prompt-engineering/README.md)** - Opanuj wzorce promptów GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Buduj systemy generacji rozszerzonej o wyszukiwanie +- **[01 - Wprowadzenie](../01-introduction/README.md)** - Naucz się zarządzania pamięcią rozmowy +- **[02 - Inżynieria podpowiedzi](../02/prompt-engineering/README.md)** - Opanuj wzorce podpowiedzi GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Buduj systemy wzbogacania generowania o odzyskiwanie danych - **[04 - Narzędzia](../04-tools/README.md)** - Implementuj wywoływanie funkcji i łańcuchy narzędzi -- **[05 - MCP](../05-mcp/README.md)** - Integruj Protokół Kontekstu Modelu +- **[05 - MCP](../05-mcp/README.md)** - Integruj Model Context Protocol -README każdego modułu zawiera szczegółowe wyjaśnienia koncepcji testowanych tutaj. +Pliki README każdego modułu zawierają szczegółowe wyjaśnienia koncepcji testowanych tutaj. --- -**Nawigacja:** [← Wróć do głównej](../README.md) +**Nawigacja:** [← Powrót do głównej](../README.md) --- **Zastrzeżenie**: -Niniejszy dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Pomimo naszych starań o dokładność, prosimy mieć na uwadze, że automatyczne tłumaczenia mogą zawierać błędy lub nieścisłości. Oryginalny dokument w języku źródłowym powinien być uważany za źródło autorytatywne. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia ludzkiego. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z korzystania z tego tłumaczenia. +Niniejszy dokument został przetłumaczony za pomocą usługi tłumaczenia AI [Co-op Translator](https://github.com/Azure/co-op-translator). Choć dążymy do dokładności, prosimy pamiętać, że automatyczne tłumaczenia mogą zawierać błędy lub niedokładności. Oryginalny dokument w jego języku źródłowym należy uznawać za autorytatywne źródło. W przypadku informacji krytycznych zalecane jest skorzystanie z profesjonalnego tłumaczenia wykonanego przez człowieka. Nie ponosimy odpowiedzialności za jakiekolwiek nieporozumienia lub błędne interpretacje wynikające z użycia tego tłumaczenia. \ No newline at end of file diff --git a/translations/pt-BR/.co-op-translator.json b/translations/pt-BR/.co-op-translator.json index 5bbed8bab..f45d63c05 100644 --- a/translations/pt-BR/.co-op-translator.json +++ b/translations/pt-BR/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "pt-BR" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T19:11:00+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T12:01:51+00:00", "source_file": "01-introduction/README.md", "language_code": "pt-BR" }, @@ -18,20 +18,20 @@ "language_code": "pt-BR" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T19:13:13+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T11:57:51+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "pt-BR" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T19:14:37+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T12:00:59+00:00", "source_file": "03-rag/README.md", "language_code": "pt-BR" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:49:34+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T11:59:49+00:00", "source_file": "04-tools/README.md", "language_code": "pt-BR" }, @@ -54,8 +54,8 @@ "language_code": "pt-BR" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:52:57+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T11:56:42+00:00", "source_file": "README.md", "language_code": "pt-BR" }, @@ -72,14 +72,14 @@ "language_code": "pt-BR" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T19:17:37+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T11:58:14+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "pt-BR" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T19:18:17+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T11:58:46+00:00", "source_file": "docs/TESTING.md", "language_code": "pt-BR" } diff --git a/translations/pt-BR/00-quick-start/README.md b/translations/pt-BR/00-quick-start/README.md deleted file mode 100644 index d55ecf60a..000000000 --- a/translations/pt-BR/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Início Rápido - -## Sumário - -- [Introdução](../../../00-quick-start) -- [O que é LangChain4j?](../../../00-quick-start) -- [Dependências do LangChain4j](../../../00-quick-start) -- [Pré-requisitos](../../../00-quick-start) -- [Configuração](../../../00-quick-start) - - [1. Obtenha seu Token do GitHub](../../../00-quick-start) - - [2. Defina seu Token](../../../00-quick-start) -- [Execute os Exemplos](../../../00-quick-start) - - [1. Chat Básico](../../../00-quick-start) - - [2. Padrões de Prompt](../../../00-quick-start) - - [3. Chamada de Função](../../../00-quick-start) - - [4. Perguntas e Respostas de Documentos (Easy RAG)](../../../00-quick-start) - - [5. IA Responsável](../../../00-quick-start) -- [O que Cada Exemplo Mostra](../../../00-quick-start) -- [Próximos Passos](../../../00-quick-start) -- [Solução de Problemas](../../../00-quick-start) - -## Introdução - -Este início rápido tem como objetivo colocá-lo para rodar com LangChain4j o mais rapidamente possível. Ele cobre o básico absoluto de construção de aplicações de IA com LangChain4j e os Modelos do GitHub. Nos próximos módulos, você mudará para Azure OpenAI e GPT-5.2 e aprofundará em cada conceito. - -## O que é LangChain4j? - -LangChain4j é uma biblioteca Java que simplifica a criação de aplicações com inteligência artificial. Em vez de lidar com clientes HTTP e parsing JSON, você trabalha com APIs Java limpas. - -A “cadeia” em LangChain refere-se a encadear vários componentes — você pode encadear um prompt a um modelo, a um parser, ou encadear múltiplas chamadas de IA onde uma saída alimenta a próxima entrada. Este início rápido foca nos fundamentos antes de explorar cadeias mais complexas. - -LangChain4j Chaining Concept - -*Encadeando componentes no LangChain4j — blocos de construção que se conectam para criar fluxos de trabalho poderosos em IA* - -Usaremos três componentes principais: - -**ChatModel** - A interface para interações com modelos de IA. Chame `model.chat("prompt")` e obtenha uma string de resposta. Usamos `OpenAiOfficialChatModel`, que funciona com endpoints compatíveis com OpenAI, como os Modelos do GitHub. - -**AiServices** - Cria interfaces de serviço de IA tipadas. Defina métodos, anote-os com `@Tool`, e LangChain4j gerencia a orquestração. A IA chama automaticamente seus métodos Java quando necessário. - -**MessageWindowChatMemory** - Mantém o histórico de conversa. Sem isso, cada requisição é independente. Com ele, a IA lembra mensagens anteriores e mantém o contexto em múltiplas interações. - -LangChain4j Architecture - -*Arquitetura LangChain4j — componentes principais trabalhando juntos para impulsionar suas aplicações de IA* - -## Dependências do LangChain4j - -Este início rápido usa três dependências Maven no [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -O módulo `langchain4j-open-ai-official` fornece a classe `OpenAiOfficialChatModel`, que conecta-se a APIs compatíveis com OpenAI. Os Modelos do GitHub usam o mesmo formato de API, então não é necessário adaptador especial — basta apontar a URL base para `https://models.github.ai/inference`. - -O módulo `langchain4j-easy-rag` oferece divisão automática de documentos, embedding e recuperação para que você possa construir aplicações RAG sem configurar manualmente cada etapa. - -## Pré-requisitos - -**Usando o Dev Container?** Java e Maven já estão instalados. Você só precisa de um Token de Acesso Pessoal do GitHub. - -**Desenvolvimento Local:** -- Java 21+, Maven 3.9+ -- Token de Acesso Pessoal do GitHub (instruções abaixo) - -> **Nota:** Este módulo usa `gpt-4.1-nano` dos Modelos do GitHub. Não modifique o nome do modelo no código — ele está configurado para funcionar com os modelos disponíveis do GitHub. - -## Configuração - -### 1. Obtenha seu Token do GitHub - -1. Vá para [Configurações do GitHub → Tokens de Acesso Pessoal](https://github.com/settings/personal-access-tokens) -2. Clique em "Gerar novo token" -3. Defina um nome descritivo (ex.: "LangChain4j Demo") -4. Defina a expiração (7 dias recomendado) -5. Em "Permissões da conta", encontre "Models" e defina como "Somente leitura" -6. Clique em "Gerar token" -7. Copie e salve seu token — você não verá ele novamente - -### 2. Defina seu Token - -**Opção 1: Usando VS Code (Recomendado)** - -Se você estiver usando VS Code, adicione seu token no arquivo `.env` na raiz do projeto: - -Se o arquivo `.env` não existir, copie `.env.example` para `.env` ou crie um arquivo `.env` novo na raiz do projeto. - -**Exemplo de arquivo `.env`:** -```bash -# Em /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Então você pode simplesmente clicar com o botão direito em qualquer arquivo de demonstração (ex.: `BasicChatDemo.java`) no Explorer e selecionar **"Run Java"** ou usar as configurações de lançamento do painel Executar e Depurar. - -**Opção 2: Usando Terminal** - -Defina o token como variável de ambiente: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Execute os Exemplos - -**Usando VS Code:** Basta clicar com o botão direito em qualquer arquivo de demonstração no Explorer e escolher **"Run Java"**, ou usar as configurações de lançamento do painel Executar e Depurar (certifique-se de ter adicionado seu token no arquivo `.env` primeiro). - -**Usando Maven:** Alternativamente, você pode executar pela linha de comando: - -### 1. Chat Básico - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Padrões de Prompt - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Mostra zero-shot, few-shot, chain-of-thought e prompting baseado em papéis. - -### 3. Chamada de Função - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -A IA chama automaticamente seus métodos Java quando necessário. - -### 4. Perguntas e Respostas de Documentos (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Faça perguntas sobre seus documentos usando Easy RAG com embedding e recuperação automáticos. - -### 5. IA Responsável - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Veja como os filtros de segurança da IA bloqueiam conteúdo nocivo. - -## O que Cada Exemplo Mostra - -**Chat Básico** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Comece aqui para ver LangChain4j em seu estado mais simples. Você criará um `OpenAiOfficialChatModel`, enviará um prompt com `.chat()` e receberá uma resposta. Isso demonstra o fundamento: como inicializar modelos com endpoints personalizados e chaves de API. Uma vez entendido esse padrão, todo o resto se baseia nele. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) e pergunte: -> - "Como eu mudaria dos Modelos do GitHub para Azure OpenAI neste código?" -> - "Quais outros parâmetros posso configurar em OpenAiOfficialChatModel.builder()?" -> - "Como eu adiciono respostas em streaming em vez de esperar pela resposta completa?" - -**Engenharia de Prompt** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Agora que você sabe como conversar com um modelo, vamos explorar o que você diz a ele. Esta demonstração usa a mesma configuração do modelo, mas mostra cinco padrões diferentes de prompting. Experimente prompts zero-shot para instruções diretas, few-shot que aprendem com exemplos, chain-of-thought que revelam os passos de raciocínio, e prompts baseados em papéis que definem contexto. Você verá como o mesmo modelo gera resultados dramaticamente diferentes dependendo de como você enquadra seu pedido. - -A demo também demonstra templates de prompt, que são uma forma poderosa de criar prompts reutilizáveis com variáveis. -O exemplo abaixo mostra um prompt usando o `PromptTemplate` do LangChain4j para preencher variáveis. A IA responderá com base no destino e atividade fornecidos. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) e pergunte: -> - "Qual a diferença entre zero-shot e few-shot prompting, e quando devo usar cada um?" -> - "Como o parâmetro temperature afeta as respostas do modelo?" -> - "Quais são algumas técnicas para prevenir ataques de injeção de prompt em produção?" -> - "Como posso criar objetos PromptTemplate reutilizáveis para padrões comuns?" - -**Integração de Ferramentas** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Aqui é onde LangChain4j fica poderoso. Você usará `AiServices` para criar um assistente de IA que pode chamar seus métodos Java. Apenas anote métodos com `@Tool("descrição")` e LangChain4j cuida do resto — a IA escolhe automaticamente quando usar cada ferramenta com base no que o usuário pede. Isso demonstra chamada de função, uma técnica chave para construir IA que pode executar ações, não só responder perguntas. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) e pergunte: -> - "Como funciona a anotação @Tool e o que LangChain4j faz com ela nos bastidores?" -> - "A IA pode chamar múltiplas ferramentas em sequência para resolver problemas complexos?" -> - "O que acontece se uma ferramenta lançar uma exceção — como devo tratar erros?" -> - "Como eu integraria uma API real em vez deste exemplo de calculadora?" - -**Perguntas e Respostas de Documentos (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Aqui você verá RAG (geração aumentada por recuperação) usando a abordagem "Easy RAG" do LangChain4j. Documentos são carregados, automaticamente divididos e embutidos numa store em memória, depois um recuperador de conteúdo fornece pedaços relevantes para a IA no momento da consulta. A IA responde com base nos seus documentos, não no seu conhecimento geral. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) e pergunte: -> - "Como o RAG previne alucinações da IA comparado a usar dados de treinamento do modelo?" -> - "Qual a diferença entre essa abordagem fácil e um pipeline RAG customizado?" -> - "Como eu escalaria isso para lidar com múltiplos documentos ou bases de conhecimento maiores?" - -**IA Responsável** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Construa segurança em IA com defesa em profundidade. Esta demo mostra duas camadas de proteção trabalhando juntas: - -**Parte 1: LangChain4j Input Guardrails** - Bloqueia prompts perigosos antes que alcancem o LLM. Crie guardrails personalizados que verificam palavras-chave ou padrões proibidos. Rodam no seu código, então são rápidos e gratuitos. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Parte 2: Filtros de Segurança do Provedor** - Os Modelos do GitHub têm filtros embutidos que capturam o que seus guardrails podem não pegar. Você verá bloqueios duros (erros HTTP 400) para violações graves e recusas leves onde a IA recusa educadamente. - -> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) e pergunte: -> - "O que é InputGuardrail e como crio o meu próprio?" -> - "Qual a diferença entre bloqueio duro e recusa leve?" -> - "Por que usar guardrails e filtros do provedor juntos?" - -## Próximos Passos - -**Próximo Módulo:** [01-introdução - Começando com LangChain4j](../01-introduction/README.md) - ---- - -**Navegação:** [← Voltar ao Principal](../README.md) | [Próximo: Module 01 - Introdução →](../01-introduction/README.md) - ---- - -## Solução de Problemas - -### Primeira Compilação Maven - -**Problema:** O comando inicial `mvn clean compile` ou `mvn package` demora muito (10-15 minutos) - -**Causa:** O Maven precisa baixar todas as dependências do projeto (Spring Boot, bibliotecas LangChain4j, SDKs Azure, etc.) na primeira compilação. - -**Solução:** Este é um comportamento normal. As compilações subsequentes serão muito mais rápidas pois as dependências ficam em cache localmente. O tempo de download depende da velocidade da sua rede. - -### Sintaxe do comando Maven no PowerShell - -**Problema:** Comandos Maven falham com erro `Unknown lifecycle phase ".mainClass=..."` -**Causa**: PowerShell interpreta `=` como um operador de atribuição de variável, quebrando a sintaxe da propriedade Maven - -**Solução**: Use o operador de parada de análise `--%` antes do comando Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -O operador `--%` diz ao PowerShell para passar todos os argumentos restantes literalmente para o Maven sem interpretação. - -### Exibição de Emoji no Windows PowerShell - -**Problema**: Respostas da IA mostram caracteres ilegíveis (ex.: `????` ou `â??`) em vez de emojis no PowerShell - -**Causa**: A codificação padrão do PowerShell não suporta emojis UTF-8 - -**Solução**: Execute este comando antes de rodar aplicações Java: -```cmd -chcp 65001 -``` - -Isso força a codificação UTF-8 no terminal. Alternativamente, use o Windows Terminal que possui melhor suporte a Unicode. - -### Depuração de Chamadas API - -**Problema**: Erros de autenticação, limites de taxa ou respostas inesperadas do modelo de IA - -**Solução**: Os exemplos incluem `.logRequests(true)` e `.logResponses(true)` para mostrar as chamadas da API no console. Isso ajuda a diagnosticar erros de autenticação, limites de taxa ou respostas inesperadas. Remova essas flags em produção para reduzir o ruído dos logs. - ---- - - -**Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, por favor esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original no seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução. - \ No newline at end of file diff --git a/translations/pt-BR/01-introduction/README.md b/translations/pt-BR/01-introduction/README.md index 04a7b1050..27c4234f7 100644 --- a/translations/pt-BR/01-introduction/README.md +++ b/translations/pt-BR/01-introduction/README.md @@ -1,87 +1,87 @@ -# Módulo 01: Começando com LangChain4j - -## Sumário - -- [Videoaula](../../../01-introduction) -- [O Que Você Vai Aprender](../../../01-introduction) -- [Pré-requisitos](../../../01-introduction) -- [Compreendendo o Problema Principal](../../../01-introduction) -- [Compreendendo Tokens](../../../01-introduction) -- [Como a Memória Funciona](../../../01-introduction) -- [Como Isto Usa LangChain4j](../../../01-introduction) -- [Implantar Infraestrutura Azure OpenAI](../../../01-introduction) -- [Executar a Aplicação Localmente](../../../01-introduction) -- [Usando a Aplicação](../../../01-introduction) - - [Chat Sem Estado (Painel Esquerdo)](../../../01-introduction) - - [Chat com Estado (Painel Direito)](../../../01-introduction) -- [Próximos Passos](../../../01-introduction) - -## Videoaula +# Module 01: Começando com LangChain4j + +## Table of Contents + +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding the Core Problem](#understanding-the-core-problem) +- [Understanding Tokens](#understanding-tokens) +- [How Memory Works](#how-memory-works) +- [How This Uses LangChain4j](#how-this-uses-langchain4j) +- [Deploy Azure OpenAI Infrastructure](#deploy-azure-openai-infrastructure) +- [Run the Application Locally](#run-the-application-locally) +- [Using the Application](#using-the-application) + - [Stateless Chat (Left Panel)](#stateless-chat-left-panel) + - [Stateful Chat (Right Panel)](#stateful-chat-right-panel) +- [Next Steps](#next-steps) + +## Video Walkthrough Assista a esta sessão ao vivo que explica como começar com este módulo: -Começando com LangChain4j - Sessão ao Vivo +Getting Started with LangChain4j - Live Session -## O Que Você Vai Aprender +## What You'll Learn -No início rápido, você usou Modelos do GitHub para enviar prompts, chamar ferramentas, construir um pipeline RAG e testar guardrails. Essas demonstrações mostraram o que é possível — agora mudamos para Azure OpenAI e GPT-5.2 e começamos a construir aplicações estilo produção. Este módulo foca em IA conversacional que lembra o contexto e mantém estado — os conceitos que aquelas demos iniciais usaram nos bastidores mas não explicaram. +Este é seu ponto de partida com LangChain4j e Azure OpenAI. Começamos com os fundamentos e começamos a construir aplicações no estilo de produção. Este módulo foca em IA conversacional que lembra o contexto e mantém estado — os conceitos fundamentais que todos os módulos posteriores constroem. -Usaremos o GPT-5.2 do Azure OpenAI ao longo deste guia porque suas capacidades avançadas de raciocínio tornam o comportamento de diferentes padrões mais perceptível. Quando você adiciona memória, verá claramente a diferença. Isso facilita entender o que cada componente traz para sua aplicação. +Usaremos o GPT-5.2 do Azure OpenAI em todo este guia porque suas capacidades avançadas de raciocínio tornam o comportamento dos diferentes padrões mais evidentes. Quando você adiciona memória, verá claramente a diferença. Isso facilita entender o que cada componente traz para sua aplicação. Você construirá uma aplicação que demonstra ambos os padrões: -**Chat Sem Estado** - Cada requisição é independente. O modelo não tem memória das mensagens anteriores. Este é o padrão que você usou no início rápido. +**Stateless Chat** - Cada requisição é independente. O modelo não tem memória das mensagens anteriores. Este é o ponto de partida mais simples. -**Conversa com Estado** - Cada requisição inclui o histórico da conversa. O modelo mantém contexto ao longo de várias interações. Isso é o que aplicações de produção exigem. +**Stateful Conversation** - Cada requisição inclui o histórico da conversa. O modelo mantém o contexto em múltiplas interações. Isso é o que aplicações em produção exigem. -## Pré-requisitos +## Prerequisites - Assinatura Azure com acesso ao Azure OpenAI - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Nota:** Java, Maven, Azure CLI e Azure Developer CLI (azd) já estão pré-instalados no devcontainer fornecido. +> **Note:** Java, Maven, Azure CLI e Azure Developer CLI (azd) já estão pré-instalados no devcontainer fornecido. -> **Nota:** Este módulo usa GPT-5.2 no Azure OpenAI. A implantação é configurada automaticamente via `azd up` - não modifique o nome do modelo no código. +> **Note:** Este módulo usa GPT-5.2 no Azure OpenAI. O deployment é configurado automaticamente via `azd up` - não modifique o nome do modelo no código. -## Compreendendo o Problema Principal +## Understanding the Core Problem -Modelos de linguagem são sem estado. Cada chamada API é independente. Se você enviar "Meu nome é João" e depois perguntar "Qual é o meu nome?", o modelo não sabe que você acabou de se apresentar. Ele trata cada requisição como se fosse a primeira conversa que você teve. +Modelos de linguagem são stateless. Cada chamada de API é independente. Se você enviar "Meu nome é John" e depois perguntar "Qual é o meu nome?", o modelo não sabe que você acabou de se apresentar. Ele trata todas as requisições como se fosse a primeira conversa que você já teve. -Isso é aceitável para perguntas e respostas simples, mas inútil para aplicações reais. Bots de atendimento ao cliente precisam lembrar o que você falou. Assistentes pessoais precisam de contexto. Qualquer conversa com múltiplos turnos requer memória. +Isso é aceitável para perguntas e respostas simples, mas inútil para aplicações reais. Bots de atendimento ao cliente precisam lembrar o que você disse. Assistentes pessoais precisam de contexto. Qualquer conversa com múltiplas interações necessita de memória. -O diagrama a seguir contrapõe as duas abordagens — à esquerda, uma chamada sem estado que esquece seu nome; à direita, uma chamada com estado suportada por ChatMemory que lembra dele. +O diagrama a seguir contrasta as duas abordagens — à esquerda, uma chamada stateless que esquece seu nome; à direita, uma chamada stateful apoiada por ChatMemory que lembra o nome. -Conversas Stateless vs Stateful +Stateless vs Stateful Conversations -*A diferença entre conversas sem estado (chamadas independentes) e com estado (cientes do contexto)* +*A diferença entre conversas stateless (chamadas independentes) e stateful (com consciência de contexto)* -## Compreendendo Tokens +## Understanding Tokens -Antes de mergulhar nas conversas, é importante entender tokens - as unidades básicas de texto que os modelos de linguagem processam: +Antes de mergulhar nas conversas, é importante entender tokens — as unidades básicas de texto que modelos de linguagem processam: -Explicação de Tokens +Token Explanation -*Exemplo de como o texto é dividido em tokens - "Eu amo IA!" se torna 4 unidades separadas para processamento* +*Exemplo de como o texto é fragmentado em tokens - "I love AI!" vira 4 unidades de processamento separadas* -Tokens são como modelos de IA medem e processam texto. Palavras, pontuação e até espaços podem ser tokens. Seu modelo tem um limite de quantos tokens pode processar de uma vez (400.000 para GPT-5.2, com até 272.000 tokens de entrada e 128.000 tokens de saída). Compreender tokens ajuda a gerenciar o tamanho da conversa e custos. +Tokens são como os modelos de IA medem e processam texto. Palavras, pontuação e até espaços podem ser tokens. Seu modelo tem um limite de quantos tokens pode processar de uma vez (400.000 para GPT-5.2, com até 272.000 tokens de entrada e 128.000 de saída). Entender tokens ajuda a gerenciar o comprimento da conversa e os custos. -## Como a Memória Funciona +## How Memory Works -A memória de chat resolve o problema do estado mantendo o histórico da conversa. Antes de enviar sua requisição para o modelo, o framework antepõe mensagens anteriores relevantes. Quando você pergunta "Qual é o meu nome?", o sistema na verdade envia todo o histórico da conversa, permitindo que o modelo veja que você disse antes "Meu nome é João". +A memória do chat resolve o problema do stateless mantendo o histórico da conversa. Antes de enviar sua requisição ao modelo, a estrutura acrescenta mensagens anteriores relevantes. Quando você pergunta "Qual é o meu nome?", o sistema realmente envia todo o histórico da conversa, permitindo que o modelo veja que você disse antes "Meu nome é John." -LangChain4j fornece implementações de memória que cuidam disso automaticamente. Você escolhe quantas mensagens reter e o framework gerencia a janela de contexto. O diagrama abaixo mostra como MessageWindowChatMemory mantém uma janela deslizante das mensagens recentes. +LangChain4j fornece implementações de memória que cuidam disso automaticamente. Você escolhe quantas mensagens manter e o framework gerencia a janela de contexto. O diagrama abaixo mostra como MessageWindowChatMemory mantém uma janela deslizante das mensagens recentes. -Conceito de Janela de Memória +Memory Window Concept -*MessageWindowChatMemory mantém uma janela deslizante das mensagens recentes, descartando automaticamente as antigas* +*MessageWindowChatMemory mantém uma janela deslizante das últimas mensagens, automaticamente descartando as mais antigas* -## Como Isto Usa LangChain4j +## How This Uses LangChain4j -Este módulo expande o início rápido integrando Spring Boot e adicionando memória de conversa. Veja como as partes se encaixam: +Este módulo integra Spring Boot e adiciona memória de conversa. Veja como as peças se encaixam: -**Dependências** - Adicione duas bibliotecas LangChain4j: +**Dependencies** - Adicione duas bibliotecas LangChain4j: ```xml @@ -94,7 +94,7 @@ Este módulo expande o início rápido integrando Spring Boot e adicionando mem ``` -**Modelo de Chat** - Configure Azure OpenAI como um bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chat Model** - Configure Azure OpenAI como um bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -O builder lê credenciais a partir de variáveis de ambiente definidas pelo `azd up`. Definir `baseUrl` para seu endpoint Azure faz o cliente OpenAI funcionar com Azure OpenAI. +O builder lê credenciais de variáveis de ambiente definidas pelo `azd up`. Configurar `baseUrl` para seu endpoint Azure faz o cliente OpenAI funcionar com Azure OpenAI. -**Memória de Conversa** - Acompanhe o histórico de chat com MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Conversation Memory** - Rastreie o histórico do chat com MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,39 +124,39 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Crie memória com `withMaxMessages(10)` para manter as últimas 10 mensagens. Adicione mensagens de usuário e IA com wrappers tipados: `UserMessage.from(text)` e `AiMessage.from(text)`. Recupere o histórico com `memory.messages()` e envie ao modelo. O serviço armazena instâncias de memória separadas por ID de conversa, permitindo múltiplos usuários conversarem simultaneamente. +Crie memória com `withMaxMessages(10)` para manter as últimas 10 mensagens. Adicione mensagens do usuário e da IA com wrappers tipados: `UserMessage.from(text)` e `AiMessage.from(text)`. Recupere o histórico com `memory.messages()` e envie ao modelo. O serviço armazena instâncias separadas de memória por ID de conversa, permitindo múltiplos usuários conversarem simultaneamente. > **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) e pergunte: -> - "Como o MessageWindowChatMemory decide quais mensagens descartar quando a janela está cheia?" -> - "Posso implementar armazenamento de memória personalizado usando um banco de dados em vez de memória em RAM?" +> - "Como MessageWindowChatMemory decide quais mensagens descartar quando a janela está cheia?" +> - "Posso implementar armazenamento de memória customizado usando um banco de dados em vez de memória interna?" > - "Como eu adicionaria sumarização para comprimir o histórico antigo da conversa?" -O endpoint de chat sem estado ignora memória completamente - apenas `chatModel.chat(prompt)` como no início rápido. O endpoint com estado adiciona mensagens à memória, recupera histórico e inclui esse contexto a cada requisição. Mesma configuração de modelo, padrões diferentes. +O endpoint de chat stateless ignora memória completamente - apenas `chatModel.chat(prompt)` como no início rápido. O endpoint stateful adiciona mensagens à memória, recupera o histórico e inclui esse contexto em cada requisição. Mesma configuração de modelo, padrões diferentes. -## Implantar Infraestrutura Azure OpenAI +## Deploy Azure OpenAI Infrastructure **Bash:** ```bash cd 01-introduction -azd up # Selecione a assinatura e localização (eastus2 recomendado) +azd up # Selecione a assinatura e a localização (eastus2 recomendado) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Selecione a assinatura e o local (eastus2 recomendado) +azd up # Selecione a assinatura e a localização (eastus2 recomendado) ``` -> **Nota:** Se você encontrar erro de timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), simplesmente execute `azd up` novamente. Os recursos do Azure podem ainda estar sendo provisionados em segundo plano, e tentar novamente permite que a implantação complete quando os recursos atingirem estado terminal. +> **Note:** Se encontrar erro de timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), execute `azd up` novamente. Recursos Azure podem ainda estar sendo provisionados em segundo plano, e tentar novamente permite a conclusão do deployment assim que os recursos atingirem estado terminal. -Isto irá: -1. Implantar recurso Azure OpenAI com modelos GPT-5.2 e text-embedding-3-small -2. Gerar automaticamente arquivo `.env` na raiz do projeto com credenciais -3. Configurar todas as variáveis de ambiente requeridas +Isso fará: +1. Deploy do recurso Azure OpenAI com modelos GPT-5.2 e text-embedding-3-small +2. Geração automática do arquivo `.env` na raiz do projeto com credenciais +3. Configuração de todas as variáveis de ambiente necessárias -**Problemas com implantação?** Veja o [README da Infraestrutura](infra/README.md) para solução detalhada de problemas incluindo conflitos de nomes de subdomínio, passos manuais para implantar pelo Portal Azure e orientações de configuração dos modelos. +**Problemas no deployment?** Veja o [Infrastructure README](infra/README.md) para solução detalhada, incluindo conflitos de nome de subdomínio, passos manuais no Portal Azure, e orientação para configuração de modelos. -**Verifique se a implantação foi bem sucedida:** +**Verifique se o deployment foi bem-sucedido:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, etc. Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, etc. ``` -> **Nota:** O comando `azd up` gera automaticamente o arquivo `.env`. Se precisar atualizá-lo depois, você pode editar manualmente ou regenerar rodando: +> **Note:** O comando `azd up` gera automaticamente o arquivo `.env`. Se precisar atualizá-lo depois, você pode editar o `.env` manualmente ou regenerá-lo executando: > > **Bash:** > ```bash @@ -182,15 +182,15 @@ Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, etc. > .\.azd-env.ps1 > ``` -## Executar a Aplicação Localmente +## Run the Application Locally -**Verifique a implantação:** +**Verifique o deployment:** -Certifique-se de que o arquivo `.env` existe no diretório raiz com credenciais Azure. Execute isso no diretório do módulo (`01-introduction/`): +Verifique se o arquivo `.env` existe no diretório raiz com as credenciais do Azure. Execute isso no diretório do módulo (`01-introduction/`): **Bash:** ```bash -cat ../.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Deve exibir AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -202,19 +202,19 @@ Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Opção 1: Usando o Spring Boot Dashboard (Recomendado para usuários VS Code)** -O dev container inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerir todas as aplicações Spring Boot. Você pode encontrá-la na Activity Bar à esquerda do VS Code (procure o ícone do Spring Boot). +O devcontainer inclui a extensão Spring Boot Dashboard, que oferece uma interface visual para gerenciar todas as aplicações Spring Boot. Você pode encontrá-la na Barra de Atividades à esquerda do VS Code (procure o ícone Spring Boot). -A partir do Spring Boot Dashboard, você pode: +No Spring Boot Dashboard, você pode: - Ver todas as aplicações Spring Boot disponíveis no workspace - Iniciar/parar aplicações com um clique -- Ver logs da aplicação em tempo real -- Monitorar status da aplicação +- Visualizar logs em tempo real +- Monitorar o status das aplicações Basta clicar no botão play ao lado de "introduction" para iniciar este módulo, ou iniciar todos os módulos de uma vez. -Painel Spring Boot +Spring Boot Dashboard -*O Spring Boot Dashboard no VS Code — inicie, pare e monitore todos os módulos de um lugar* +*O Spring Boot Dashboard no VS Code — iniciar, parar e monitorar todos os módulos em um só lugar* **Opção 2: Usando scripts shell** @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Ambos os scripts carregam automaticamente variáveis de ambiente do arquivo `.env` da raiz e irão construir os JARs se eles não existirem. +Ambos os scripts carregam automaticamente variáveis de ambiente do arquivo `.env` raiz e irão construir os JARs caso não existam. -> **Nota:** Se preferir compilar todos os módulos manualmente antes de iniciar: +> **Note:** Se preferir construir todos os módulos manualmente antes de iniciar: > > **Bash:** > ```bash @@ -268,7 +268,7 @@ Abra http://localhost:8080 no seu navegador. **Bash:** ```bash -./stop.sh # Apenas este módulo +./stop.sh # Somente este módulo # Ou cd .. && ./stop-all.sh # Todos os módulos ``` @@ -280,43 +280,43 @@ cd .. && ./stop-all.sh # Todos os módulos cd ..; .\stop-all.ps1 # Todos os módulos ``` -## Usando a Aplicação +## Using the Application A aplicação fornece uma interface web com duas implementações de chat lado a lado. -Tela Inicial da Aplicação +Application Home Screen -*Dashboard mostrando opções de Chat Simples (sem estado) e Chat Conversacional (com estado)* +*Dashboard mostrando opções de Simple Chat (stateless) e Conversational Chat (stateful)* -### Chat Sem Estado (Painel Esquerdo) +### Stateless Chat (Left Panel) -Experimente primeiro. Pergunte "Meu nome é João" e então imediatamente pergunte "Qual é o meu nome?" O modelo não irá lembrar porque cada mensagem é independente. Isso demonstra o problema principal da integração básica do modelo de linguagem - sem contexto de conversa. +Experimente primeiro. Diga "Meu nome é John" e imediatamente depois pergunte "Qual é o meu nome?" O modelo não lembrará porque cada mensagem é independente. Isso demonstra o problema central da integração básica com modelos de linguagem — sem contexto de conversa. -Demonstração Chat Sem Estado +Stateless Chat Demo *IA não lembra seu nome da mensagem anterior* -### Chat com Estado (Painel Direito) +### Stateful Chat (Right Panel) -Agora tente a mesma sequência aqui. Pergunte "Meu nome é João" e depois "Qual é o meu nome?" Dessa vez ele lembra. A diferença é o MessageWindowChatMemory - ele mantém o histórico da conversa e o inclui em cada requisição. É assim que funciona IA conversacional de produção. +Agora, tente a mesma sequência aqui. Diga "Meu nome é John" e depois "Qual é o meu nome?" Desta vez, ele lembra. A diferença é MessageWindowChatMemory — ele mantém o histórico da conversa e o inclui em cada requisição. É assim que funciona a IA conversacional em produção. -Demonstração Chat com Estado +Stateful Chat Demo -*IA lembra seu nome de antes na conversa* +*IA lembra seu nome dado anteriormente na conversa* -Ambos os painéis usam o mesmo modelo GPT-5.2. A única diferença é a memória. Isso deixa claro o que a memória traz para sua aplicação e porque é essencial para casos de uso reais. +Ambos os painéis usam o mesmo modelo GPT-5.2. A única diferença é a memória. Isso deixa claro o que a memória traz para sua aplicação e por que é essencial para casos de uso reais. -## Próximos Passos +## Next Steps -**Próximo Módulo:** [02-prompt-engineering - Engenharia de Prompt com GPT-5.2](../02-prompt-engineering/README.md) +**Next Module:** [02-prompt-engineering - Engenharia de Prompt com GPT-5.2](../02-prompt-engineering/README.md) --- -**Navegação:** [← Anterior: Módulo 00 - Início Rápido](../00-quick-start/README.md) | [Voltar ao Início](../README.md) | [Próximo: Módulo 02 - Engenharia de Prompt →](../02-prompt-engineering/README.md) +**Navigation:** [← Voltar para Principal](../README.md) | [Próximo: Módulo 02 - Engenharia de Prompt →](../02-prompt-engineering/README.md) --- -**Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, é importante estar ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original em sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se a tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução. +**Aviso Legal**: +Este documento foi traduzido usando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. \ No newline at end of file diff --git a/translations/pt-BR/02-prompt-engineering/README.md b/translations/pt-BR/02-prompt-engineering/README.md index 41cf85277..da5297951 100644 --- a/translations/pt-BR/02-prompt-engineering/README.md +++ b/translations/pt-BR/02-prompt-engineering/README.md @@ -2,29 +2,29 @@ ## Índice -- [Video Walkthrough](../../../02-prompt-engineering) -- [O que você vai aprender](../../../02-prompt-engineering) -- [Pré-requisitos](../../../02-prompt-engineering) -- [Entendendo Engenharia de Prompt](../../../02-prompt-engineering) -- [Fundamentos da Engenharia de Prompt](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Modelos de Prompt](../../../02-prompt-engineering) -- [Padrões Avançados](../../../02-prompt-engineering) -- [Execute a Aplicação](../../../02-prompt-engineering) -- [Capturas de Tela da Aplicação](../../../02-prompt-engineering) -- [Explorando os Padrões](../../../02-prompt-engineering) - - [Baixa vs Alta Diligência](../../../02-prompt-engineering) - - [Execução de Tarefas (Preâmbulos de Ferramentas)](../../../02-prompt-engineering) - - [Código Auto-Reflexivo](../../../02-prompt-engineering) - - [Análise Estruturada](../../../02-prompt-engineering) - - [Chat Multi-Turno](../../../02-prompt-engineering) - - [Raciocínio Passo a Passo](../../../02-prompt-engineering) - - [Saída Confinada](../../../02-prompt-engineering) -- [O que você está realmente aprendendo](../../../02-prompt-engineering) -- [Próximos Passos](../../../02-prompt-engineering) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding Prompt Engineering](#understanding-prompt-engineering) +- [Prompt Engineering Fundamentals](#prompt-engineering-fundamentals) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Advanced Patterns](#advanced-patterns) +- [Run the Application](#executar-a-aplicação) +- [Application Screenshots](#capturas-de-tela-da-aplicação) +- [Exploring the Patterns](#explorando-os-padrões) + - [Low vs High Eagerness](#baixa-vs-alta-vontade) + - [Task Execution (Tool Preambles)](#execução-de-tarefa-preambos-de-ferramentas) + - [Self-Reflecting Code](#código-auto-reflexivo) + - [Structured Analysis](#análise-estruturada) + - [Multi-Turn Chat](#chat-multi-turno) + - [Step-by-Step Reasoning](#raciocínio-passo-a-passo) + - [Constrained Output](#saída-constrained) +- [What You're Really Learning](#o-que-você-está-realmente-aprendendo) +- [Next Steps](#próximos-passos) ## Video Walkthrough @@ -32,54 +32,54 @@ Assista a esta sessão ao vivo que explica como começar com este módulo: Prompt Engineering with LangChain4j - Live Session -## O que você vai aprender +## What You'll Learn -O diagrama a seguir oferece uma visão geral dos principais tópicos e habilidades que você desenvolverá neste módulo — desde técnicas de refinamento de prompts até o fluxo de trabalho passo a passo que você seguirá. +O diagrama a seguir fornece uma visão geral dos principais tópicos e habilidades que você desenvolverá neste módulo — desde técnicas de refinamento de prompt até o fluxo de trabalho passo a passo que você seguirá. What You'll Learn -Nos módulos anteriores, você explorou interações básicas do LangChain4j com modelos do GitHub e viu como a memória permite IA conversacional com Azure OpenAI. Agora, focaremos em como você faz perguntas — os próprios prompts — usando o GPT-5.2 do Azure OpenAI. A forma como você estrutura seus prompts afeta dramaticamente a qualidade das respostas que obtém. Começamos com uma revisão das técnicas fundamentais de prompting e depois avançamos para oito padrões avançados que aproveitam ao máximo as capacidades do GPT-5.2. +No módulo anterior, você viu como a memória possibilita a IA conversacional com Azure OpenAI. Agora vamos focar em como você faz perguntas — os próprios prompts — usando o GPT-5.2 do Azure OpenAI. A forma como você estrutura seus prompts afeta drasticamente a qualidade das respostas que obtém. Começamos com uma revisão das técnicas fundamentais de prompting, depois avançamos para oito padrões avançados que aproveitam ao máximo as capacidades do GPT-5.2. -Usaremos o GPT-5.2 porque ele introduz controle de raciocínio - você pode dizer ao modelo quanto ele deve pensar antes de responder. Isso torna as diferentes estratégias de prompting mais evidentes e ajuda você a entender quando usar cada abordagem. Também aproveitaremos os limites de taxa menores do Azure para o GPT-5.2 em comparação com os modelos do GitHub. +Usaremos o GPT-5.2 porque ele introduz controle de raciocínio — você pode dizer ao modelo quanto pensar antes de responder. Isso torna as diferentes estratégias de prompting mais evidentes e ajuda a entender quando usar cada abordagem. -## Pré-requisitos +## Prerequisites -- Módulo 01 concluído (recursos Azure OpenAI implantados) +- Módulo 01 concluído (recursos do Azure OpenAI implantados) - Arquivo `.env` no diretório raiz com credenciais Azure (criado pelo `azd up` no Módulo 01) -> **Nota:** Se você não completou o Módulo 01, siga as instruções de implantação lá primeiro. +> **Nota:** Se você ainda não concluiu o Módulo 01, siga as instruções de implantação lá primeiro. -## Entendendo Engenharia de Prompt +## Understanding Prompt Engineering -Na essência, engenharia de prompt é a diferença entre instruções vagas e precisas, como a comparação abaixo ilustra. +Essencialmente, engenharia de prompt é a diferença entre instruções vagas e instruções precisas, como ilustra a comparação abaixo. What is Prompt Engineering? -Engenharia de prompt é sobre projetar texto de entrada que consistentemente gera os resultados que você precisa. Não é apenas fazer perguntas - é estruturar solicitações para que o modelo entenda exatamente o que quer e como entregar. +Engenharia de prompt consiste em projetar um texto de entrada que consistentemente lhe dá os resultados que você precisa. Não é apenas sobre fazer perguntas — é sobre estruturar solicitações para que o modelo entenda exatamente o que você quer e como entregar isso. -Pense nisso como dar instruções a um colega. "Conserte o bug" é vago. "Conserte a exceção de ponteiro nulo em UserService.java linha 45 adicionando uma verificação nula" é específico. Modelos de linguagem funcionam da mesma forma - especificidade e estrutura importam. +Pense nisso como dar instruções a um colega. "Conserte o bug" é vago. "Conserte a exceção de ponteiro nulo em UserService.java linha 45 adicionando uma verificação nula" é específico. Modelos de linguagem funcionam da mesma forma — especificidade e estrutura importam. -O diagrama abaixo mostra como o LangChain4j se encaixa nessa imagem — conectando seus padrões de prompt ao modelo através dos blocos de construção SystemMessage e UserMessage. +O diagrama abaixo mostra como o LangChain4j se encaixa nessa imagem — conectando seus padrões de prompt ao modelo por meio dos blocos de construção SystemMessage e UserMessage. How LangChain4j Fits -LangChain4j fornece a infraestrutura — conexões com o modelo, memória e tipos de mensagem — enquanto os padrões de prompt são apenas texto cuidadosamente estruturado que você envia por essa infraestrutura. Os blocos essenciais são `SystemMessage` (que define o comportamento e o papel da IA) e `UserMessage` (que carrega sua solicitação real). +O LangChain4j fornece a infraestrutura — conexões com modelo, memória e tipos de mensagem — enquanto os padrões de prompt são apenas textos cuidadosamente estruturados que você envia por essa infraestrutura. Os blocos de construção principais são `SystemMessage` (que define o comportamento e o papel da IA) e `UserMessage` (que carrega seu pedido real). -## Fundamentos da Engenharia de Prompt +## Prompt Engineering Fundamentals -As cinco técnicas centrais mostradas abaixo formam a base da engenharia de prompt eficaz. Cada uma aborda um aspecto diferente da comunicação com modelos de linguagem. +As cinco técnicas principais mostradas abaixo formam a base da engenharia de prompt eficaz. Cada uma aborda um aspecto diferente de como você se comunica com modelos de linguagem. Five Prompt Engineering Patterns Overview -Antes de mergulharmos nos padrões avançados deste módulo, vamos revisar cinco técnicas fundamentais de prompting. Estes são os blocos de construção que todo engenheiro de prompt deve conhecer. Se você já trabalhou no [módulo de Início Rápido](../00-quick-start/README.md#2-prompt-patterns), já viu esses em ação — aqui está a estrutura conceitual por trás deles. +Antes de mergulhar nos padrões avançados deste módulo, vamos revisar cinco técnicas fundamentais de prompting. Essas são as bases que todo engenheiro de prompt deve conhecer. ### Zero-Shot Prompting -A abordagem mais simples: dê ao modelo uma instrução direta sem exemplos. O modelo confia inteiramente em seu treinamento para entender e executar a tarefa. Funciona bem para solicitações diretas onde o comportamento esperado é óbvio. +A abordagem mais simples: dê ao modelo uma instrução direta sem exemplos. O modelo depende inteiramente de seu treinamento para entender e executar a tarefa. Isso funciona bem para solicitações diretas onde o comportamento esperado é óbvio. Zero-Shot Prompting -*Instrução direta sem exemplos — o modelo infere a tarefa apenas pela instrução* +*Instrução direta sem exemplos — o modelo infere a tarefa apenas a partir da instrução* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Resposta: "Positivo" ``` -**Quando usar:** Classificações simples, perguntas diretas, traduções ou qualquer tarefa que o modelo possa lidar sem orientação adicional. +**Quando usar:** Classificações simples, perguntas diretas, traduções ou qualquer tarefa que o modelo possa executar sem orientação adicional. ### Few-Shot Prompting -Forneça exemplos que demonstrem o padrão que deseja que o modelo siga. O modelo aprende o formato esperado de entrada-saída pelos seus exemplos e aplica a novos inputs. Isso melhora dramaticamente a consistência para tarefas onde o formato ou comportamento desejado não é óbvio. +Forneça exemplos que demonstrem o padrão que você quer que o modelo siga. O modelo aprende o formato esperado de entrada-saída a partir dos seus exemplos e aplica a novas entradas. Isso melhora drasticamente a consistência para tarefas onde o formato ou comportamento desejado não é óbvio. Few-Shot Prompting -*Aprendendo com exemplos — o modelo identifica o padrão e o aplica a novos inputs* +*Aprender com exemplos — o modelo identifica o padrão e o aplica a novas entradas* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Quando usar:** Classificações customizadas, formatação consistente, tarefas específicas de domínio, ou quando os resultados zero-shot são inconsistentes. +**Quando usar:** Classificações personalizadas, formatação consistente, tarefas específicas de domínio ou quando resultados zero-shot são inconsistentes. ### Chain of Thought -Peça ao modelo para mostrar seu raciocínio passo a passo. Em vez de ir direto à resposta, o modelo divide o problema e trabalha cada parte explicitamente. Isso melhora a precisão em tarefas de matemática, lógica e raciocínio multi-etapas. +Peça ao modelo para mostrar seu raciocínio passo a passo. Em vez de pular direto para uma resposta, o modelo divide o problema e trabalha em cada parte explicitamente. Isso melhora a precisão em tarefas de matemática, lógica e raciocínio em múltiplas etapas. Chain of Thought Prompting -*Raciocínio passo a passo — quebrando problemas complexos em etapas lógicas explícitas* +*Raciocínio passo a passo — dividindo problemas complexos em etapas lógicas explícitas* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // O modelo mostra: 15 - 8 = 7, então 7 + 12 = 19 maçãs ``` -**Quando usar:** Problemas matemáticos, quebra-cabeças lógicos, depuração ou qualquer tarefa onde mostrar o processo de raciocínio melhora precisão e confiança. +**Quando usar:** Problemas matemáticos, quebra-cabeças lógicos, depuração ou qualquer tarefa onde mostrar o processo de raciocínio melhora a precisão e a confiança. ### Role-Based Prompting -Defina uma persona ou papel para a IA antes de fazer a pergunta. Isso fornece contexto que molda o tom, profundidade e foco da resposta. Um "arquiteto de software" dá conselhos diferentes de um "desenvolvedor júnior" ou um "auditor de segurança". +Defina uma persona ou papel para a IA antes de fazer sua pergunta. Isso fornece contexto que molda o tom, profundidade e foco da resposta. Um "arquitet@ de software" fornece conselhos diferentes de um "desenvolvedor júnior" ou um "auditor de segurança". Role-Based Prompting -*Configurando contexto e persona — a mesma pergunta recebe resposta diferente conforme o papel atribuído* +*Estabelecendo contexto e persona — a mesma pergunta recebe respostas diferentes dependendo do papel atribuído* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Quando usar:** Revisões de código, tutoria, análise específica de domínio ou quando você precisa de respostas ajustadas a um nível de expertise ou perspectiva particular. +**Quando usar:** Revisões de código, tutoria, análise específica de domínio ou quando você precisa de respostas adaptadas a um nível específico de expertise ou perspectiva. -### Modelos de Prompt +### Prompt Templates -Crie prompts reutilizáveis com espaços reservados para variáveis. Em vez de escrever um novo prompt toda vez, defina um modelo uma vez e preencha com valores diferentes. A classe `PromptTemplate` do LangChain4j facilita isso com a sintaxe `{{variable}}`. +Crie prompts reutilizáveis com espaços reservados para variáveis. Em vez de escrever um novo prompt toda vez, defina um template uma vez e preencha com diferentes valores. A classe `PromptTemplate` do LangChain4j facilita isso com a sintaxe `{{variable}}`. Prompt Templates -*Prompts reutilizáveis com espaços para variáveis — um modelo, muitos usos* +*Prompts reutilizáveis com espaços para variáveis — um template, muitos usos* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Quando usar:** Consultas repetidas com diferentes inputs, processamento em lote, construção de fluxos de trabalho reutilizáveis de IA ou qualquer cenário onde a estrutura do prompt permanece a mesma mas os dados mudam. +**Quando usar:** Consultas repetidas com entradas diferentes, processamento em lote, construção de fluxos reutilizáveis de IA ou qualquer cenário onde a estrutura do prompt permanece a mesma mas os dados mudam. --- -Esses cinco fundamentos oferecem uma caixa de ferramentas sólida para a maioria das tarefas de prompting. O restante deste módulo constrói sobre eles com **oito padrões avançados** que aproveitam o controle de raciocínio, autoavaliação e capacidade de saída estruturada do GPT-5.2. +Esses cinco fundamentos lhe dão uma caixa de ferramentas sólida para a maioria das tarefas de prompting. O restante deste módulo constrói sobre eles com **oito padrões avançados** que aproveitam o controle de raciocínio, autoavaliação e capacidades de saída estruturada do GPT-5.2. -## Padrões Avançados +## Advanced Patterns -Com os fundamentos cobertos, vamos avançar para os oito padrões avançados que tornam este módulo único. Nem todos os problemas precisam da mesma abordagem. Algumas perguntas precisam de respostas rápidas, outras de pensamento profundo. Algumas precisam de raciocínio visível, outras só dos resultados. Cada padrão abaixo é otimizado para um cenário diferente — e o controle de raciocínio do GPT-5.2 torna as diferenças ainda mais evidentes. +Com os fundamentos cobertos, vamos aos oito padrões avançados que tornam este módulo único. Nem todos os problemas precisam do mesmo método. Algumas perguntas precisam de respostas rápidas, outras de pensamento profundo. Algumas precisam de raciocínio visível, outras só precisam dos resultados. Cada padrão abaixo é otimizado para um cenário diferente — e o controle de raciocínio do GPT-5.2 torna as diferenças ainda mais evidentes. Eight Prompting Patterns *Visão geral dos oito padrões de engenharia de prompt e seus casos de uso* -O GPT-5.2 adiciona outra dimensão a esses padrões: *controle de raciocínio*. O controle abaixo mostra como você pode ajustar o esforço de pensamento do modelo — de respostas rápidas e diretas a análises profundas e detalhadas. +O GPT-5.2 adiciona outra dimensão a esses padrões: *controle de raciocínio*. O controle deslizante abaixo mostra como você pode ajustar o esforço de pensamento do modelo — de respostas rápidas e diretas até análises profundas e detalhadas. Reasoning Control with GPT-5.2 -*O controle de raciocínio do GPT-5.2 permite especificar quanto o modelo deve pensar — de respostas rápidas e diretas a explorações profundas* +*O controle de raciocínio do GPT-5.2 permite que você especifique quanto o modelo deve pensar — de respostas rápidas diretas a exploração profunda* -**Baixa Diligência (Rápido e Focado)** - Para perguntas simples onde você quer respostas rápidas e diretas. O modelo faz raciocínio mínimo - máximo 2 passos. Use para cálculos, consultas ou perguntas diretas. +**Baixa Disposição (Rápido & Focado)** - Para perguntas simples onde você quer respostas rápidas e diretas. O modelo faz raciocínio mínimo — no máximo 2 passos. Use isso para cálculos, consultas ou perguntas diretas. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Explore com GitHub Copilot:** Abra [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) e pergunte: -> - "Qual a diferença entre os padrões de prompting de baixa e alta diligência?" +> 💡 **Explore com o GitHub Copilot:** Abra [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) e pergunte: +> - "Qual a diferença entre os padrões de prompting de baixa e alta disposição?" > - "Como as tags XML nos prompts ajudam a estruturar a resposta da IA?" > - "Quando devo usar padrões de autorreflexão versus instrução direta?" -**Alta Diligência (Profundo e Detalhado)** - Para problemas complexos onde você quer análise abrangente. O modelo explora a fundo e mostra raciocínio detalhado. Use para design de sistemas, decisões de arquitetura ou pesquisas complexas. +**Alta Disposição (Profundo & Completo)** - Para problemas complexos onde você quer análise abrangente. O modelo explora em profundidade e mostra raciocínio detalhado. Use isso para design de sistemas, decisões de arquitetura ou pesquisas complexas. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Execução de Tarefas (Progresso Passo a Passo)** - Para fluxos de trabalho multi-etapas. O modelo fornece um plano inicial, narra cada passo enquanto executa e depois faz um resumo. Use para migrações, implementações ou qualquer processo com múltiplas etapas. +**Execução de Tarefa (Progresso Passo a Passo)** - Para fluxos de trabalho em múltiplas etapas. O modelo fornece um plano inicial, narra cada passo enquanto trabalha, depois dá um resumo. Use isso para migrações, implementações ou qualquer processo com múltiplas etapas. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Chain-of-Thought prompting pede explicitamente ao modelo para mostrar seu processo de raciocínio, melhorando a precisão para tarefas complexas. A divisão passo a passo ajuda tanto humanos quanto IA a entenderem a lógica. +O prompting Chain-of-Thought (cadeia de pensamento) pede explicitamente que o modelo mostre seu processo de raciocínio, melhorando a precisão em tarefas complexas. A decomposição passo a passo ajuda tanto humanos quanto IA a entenderem a lógica. > **🤖 Experimente com o Chat do [GitHub Copilot](https://github.com/features/copilot):** Pergunte sobre esse padrão: -> - "Como eu adaptaria o padrão de execução de tarefas para operações de longa duração?" +> - "Como eu adaptaria o padrão de execução de tarefa para operações de longa duração?" > - "Quais são as melhores práticas para estruturar preâmbulos de ferramentas em aplicações de produção?" -> - "Como posso capturar e exibir atualizações intermediárias de progresso em uma interface?" +> - "Como posso capturar e exibir atualizações intermediárias de progresso em uma interface de usuário?" -O diagrama abaixo ilustra esse fluxo Plano → Executar → Resumir. +O diagrama abaixo ilustra esse fluxo Plan → Execute → Summarize. Task Execution Pattern -*Fluxo Plano → Executar → Resumir para tarefas multi-etapas* +*Fluxo Plan → Execute → Summarize para tarefas em múltiplas etapas* -**Código Auto-Reflexivo** - Para gerar código com qualidade de produção. O modelo gera código seguindo padrões de produção com tratamento adequado de erros. Use para construir novas funcionalidades ou serviços. +**Código Auto-Reflexivo** - Para gerar código de qualidade para produção. O modelo gera código seguindo padrões de produção com tratamento adequado de erros. Use isso para construir novas funcionalidades ou serviços. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -O diagrama abaixo mostra esse ciclo iterativo de melhoria — gerar, avaliar, identificar fraquezas e refinar até que o código atenda aos padrões de produção. +O diagrama abaixo mostra este ciclo iterativo de melhoria — gerar, avaliar, identificar pontos fracos e refinar até que o código atenda aos padrões de produção. Self-Reflection Cycle -*Ciclo iterativo de melhoria - gerar, avaliar, identificar problemas, melhorar, repetir* +*Ciclo iterativo de melhoria — gerar, avaliar, identificar problemas, melhorar, repetir* -**Análise Estruturada** - Para avaliação consistente. O modelo revisa código usando uma estrutura fixa (correção, práticas, desempenho, segurança, manutenção). Use para revisões de código ou avaliações de qualidade. +**Análise Estruturada** - Para avaliação consistente. O modelo revisa código usando um framework fixo (correção, práticas, desempenho, segurança, manutenibilidade). Use isso para revisões de código ou avaliações de qualidade. ```java String prompt = """ @@ -355,17 +355,17 @@ String response = chatModel.chat(prompt); ``` > **🤖 Experimente com o Chat do [GitHub Copilot](https://github.com/features/copilot):** Pergunte sobre análise estruturada: -> - "Como posso personalizar a estrutura de análise para diferentes tipos de revisões de código?" -> - "Qual a melhor maneira de interpretar e agir com saída estruturada programaticamente?" -> - "Como garantir níveis consistentes de severidade em diferentes sessões de revisão?" +> - "Como posso personalizar o framework de análise para diferentes tipos de revisões de código?" +> - "Qual a melhor forma de interpretar e agir conforme a saída estruturada programaticamente?" +> - "Como garantir níveis de severidade consistentes em diferentes sessões de revisão?" -O diagrama a seguir mostra como essa estrutura organizada divide uma revisão de código em categorias consistentes com níveis de severidade. +O diagrama a seguir mostra como esse framework estruturado organiza uma revisão de código em categorias consistentes com níveis de severidade. Structured Analysis Pattern -*Estrutura para revisões consistentes de código com níveis de severidade* +*Framework para revisões de código consistentes com níveis de severidade* -**Chat Multi-Turno** - Para conversas que precisam de contexto. O modelo lembra mensagens anteriores e vai construindo sobre elas. Use para sessões de ajuda interativas ou perguntas e respostas complexas. +**Chat Multi-Turno** - Para conversas que precisam de contexto. O modelo lembra das mensagens anteriores e constrói sobre elas. Use isso para sessões interativas de ajuda ou perguntas e respostas complexas. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -383,8 +383,9 @@ O diagrama abaixo visualiza como o contexto da conversa se acumula a cada turno Context Memory -*Como o contexto da conversa se acumula em múltiplos turnos até atingir o limite de tokens* -**Raciocínio Passo a Passo** - Para problemas que exigem lógica visível. O modelo mostra raciocínio explícito para cada etapa. Use isso para problemas matemáticos, quebra-cabeças lógicos ou quando precisar entender o processo de pensamento. +*Como o contexto da conversa se acumula ao longo de múltiplos turnos até atingir o limite de tokens* + +**Raciocínio Passo a Passo** - Para problemas que exigem lógica visível. O modelo apresenta raciocínio explícito para cada etapa. Use isso para problemas matemáticos, quebra-cabeças lógicos ou quando precisar entender o processo de pensamento. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -O diagrama abaixo ilustra como o modelo divide problemas em etapas lógicas explícitas numeradas. - -Padrão Passo a Passo +O diagrama abaixo ilustra como o modelo divide problemas em passos lógicos explícitos e numerados. -*Dividindo problemas em etapas lógicas explícitas* +Step-by-Step Pattern +*Quebrando problemas em passos lógicos explícitos* -**Saída Constrita** - Para respostas com requisitos específicos de formato. O modelo segue rigorosamente as regras de formato e comprimento. Use isso para resumos ou quando precisar de uma estrutura precisa de saída. +**Saída Constrained** - Para respostas com requisitos de formato específicos. O modelo segue rigorosamente as regras de formato e comprimento. Use isso para resumos ou quando precisar de estrutura de saída precisa. ```java String prompt = """ @@ -420,13 +420,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -O diagrama a seguir mostra como restrições orientam o modelo a produzir uma saída que segue estritamente seu formato e requisitos de comprimento. +O diagrama a seguir mostra como as restrições guiam o modelo para produzir uma saída que adere estritamente aos seus requisitos de formato e comprimento. -Padrão de Saída Constrita +Padrão de Saída Constrained *Impondo requisitos específicos de formato, comprimento e estrutura* -## Execute a Aplicação +## Executar a Aplicação **Verifique a implantação:** @@ -444,13 +444,13 @@ Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Inicie a aplicação:** -> **Nota:** Se você já iniciou todas as aplicações usando `./start-all.sh` a partir do diretório raiz (conforme descrito no Módulo 01), este módulo já está rodando na porta 8083. Você pode pular os comandos de início abaixo e ir direto para http://localhost:8083. +> **Nota:** Se você já iniciou todas as aplicações usando `./start-all.sh` a partir do diretório raiz (como descrito no Módulo 01), este módulo já está rodando na porta 8083. Você pode pular os comandos de inicialização abaixo e ir direto para http://localhost:8083. -**Opção 1: Usando o Spring Boot Dashboard (Recomendado para usuários VS Code)** +**Opção 1: Usando o Spring Boot Dashboard (Recomendado para usuários do VS Code)** -O contêiner de desenvolvimento inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerenciar todas as aplicações Spring Boot. Você pode encontrá-la na Barra de Atividades à esquerda do VS Code (procure pelo ícone do Spring Boot). +O contêiner dev inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerenciar todas as aplicações Spring Boot. Você pode encontrá-lo na Barra de Atividades do lado esquerdo do VS Code (procure pelo ícone do Spring Boot). -No Spring Boot Dashboard, você pode: +A partir do Spring Boot Dashboard, você pode: - Ver todas as aplicações Spring Boot disponíveis no workspace - Iniciar/parar aplicações com um clique - Visualizar logs das aplicações em tempo real @@ -460,7 +460,7 @@ Basta clicar no botão de play ao lado de "prompt-engineering" para iniciar este Spring Boot Dashboard -*O Spring Boot Dashboard no VS Code — inicie, pare e monitore todos os módulos a partir de um único lugar* +*O Spring Boot Dashboard no VS Code — inicie, pare e monitore todos os módulos a partir de um só lugar* **Opção 2: Usando scripts shell** @@ -474,7 +474,7 @@ cd .. # A partir do diretório raiz **PowerShell:** ```powershell -cd .. # Desde o diretório raiz +cd .. # A partir do diretório raiz .\start-all.ps1 ``` @@ -492,7 +492,7 @@ cd 02-prompt-engineering .\start.ps1 ``` -Ambos os scripts carregam automaticamente as variáveis de ambiente do arquivo `.env` raiz e construirão os JARs se eles não existirem. +Ambos os scripts carregam automaticamente as variáveis de ambiente do arquivo `.env` raiz e irão construir os JARs se eles não existirem. > **Nota:** Se preferir construir todos os módulos manualmente antes de iniciar: > @@ -528,73 +528,73 @@ cd ..; .\stop-all.ps1 # Todos os módulos ## Capturas de Tela da Aplicação -Aqui está a interface principal do módulo de engenharia de prompt, onde você pode experimentar todos os oito padrões lado a lado. +Aqui está a interface principal do módulo de engenharia de prompts, onde você pode experimentar todos os oito padrões lado a lado. -Tela Inicial do Dashboard +Página Inicial do Dashboard -*O dashboard principal mostrando os 8 padrões de engenharia de prompt com suas características e casos de uso* +*O dashboard principal mostrando todos os 8 padrões de engenharia de prompt com suas características e casos de uso* ## Explorando os Padrões -A interface web permite que você experimente diferentes estratégias de prompting. Cada padrão resolve problemas distintos — experimente para ver quando cada abordagem se destaca. +A interface web permite que você experimente diferentes estratégias de prompting. Cada padrão resolve problemas diferentes – experimente para ver quando cada abordagem se destaca. -> **Nota: Streaming vs Não Streaming** — Cada página de padrão oferece dois botões: **🔴 Stream Response (Live)** e uma opção **Não streaming**. Streaming usa Server-Sent Events (SSE) para mostrar os tokens em tempo real enquanto o modelo os gera, para que você veja o progresso imediatamente. A opção não streaming espera pela resposta completa antes de exibi-la. Para prompts que exigem raciocínio aprofundado (ex: High Eagerness, Self-Reflecting Code), a chamada não streaming pode demorar muito — às vezes minutos — sem feedback visível. **Use streaming ao experimentar prompts complexos** para ver o modelo trabalhando e evitar a impressão de timeout. +> **Nota: Streaming vs Não-Streaming** — Cada página de padrão oferece dois botões: **🔴 Stream Response (Ao Vivo)** e uma opção **Não-streaming**. O streaming usa Server-Sent Events (SSE) para exibir tokens em tempo real conforme o modelo os gera, para que você veja o progresso imediatamente. A opção não-streaming espera a resposta completa antes de exibi-la. Para prompts que acionam raciocínio profundo (ex: Alta Vontade, Código Auto-Reflexivo), a chamada não-streaming pode levar muito tempo – às vezes minutos – sem feedback visível. **Use o streaming ao experimentar prompts complexos** para ver o modelo trabalhando e evitar a impressão de timeout na requisição. > -> **Nota: Requisito do Navegador** — O recurso de streaming usa a Fetch Streams API (`response.body.getReader()`) que requer um navegador completo (Chrome, Edge, Firefox, Safari). Não funciona no Simple Browser embutido do VS Code, pois seu webview não suporta a API ReadableStream. Se usar o Simple Browser, os botões não streaming funcionarão normalmente — apenas os botões de streaming são afetados. Abra `http://localhost:8083` em um navegador externo para a experiência completa. +> **Nota: Requisito do Navegador** — O recurso de streaming usa a Fetch Streams API (`response.body.getReader()`), que requer um navegador completo (Chrome, Edge, Firefox, Safari). Não funciona no Simple Browser embutido do VS Code, pois seu webview não suporta a ReadableStream API. Se usar o Simple Browser, os botões não streaming funcionarão normalmente — somente os botões de streaming são afetados. Abra `http://localhost:8083` em um navegador externo para a experiência completa. -### Baixa vs Alta Empolgação (Eagerness) +### Baixa vs Alta Vontade -Faça uma pergunta simples como "Qual é 15% de 200?" usando Baixa Empolgação. Você receberá uma resposta direta e instantânea. Agora pergunte algo complexo como "Desenvolva uma estratégia de cache para uma API de alto tráfego" usando Alta Empolgação. Clique em **🔴 Stream Response (Live)** e veja o raciocínio detalhado do modelo aparecer token por token. Mesmo modelo, mesma estrutura de pergunta — mas o prompt indica quanto pensamento fazer. +Faça uma pergunta simples como "Qual é 15% de 200?" usando Baixa Vontade. Você receberá uma resposta instantânea e direta. Agora pergunte algo complexo como "Projete uma estratégia de cache para uma API com alto tráfego" usando Alta Vontade. Clique em **🔴 Stream Response (Ao Vivo)** e observe o raciocínio detalhado do modelo aparecer token por token. Mesmo modelo, mesma estrutura de pergunta – mas o prompt diz quanto pensar. -### Execução de Tarefas (Preâmbulos de Ferramentas) +### Execução de Tarefa (Preambos de Ferramentas) -Fluxos de trabalho multi-etapas se beneficiam de planejamento prévio e narração do progresso. O modelo descreve o que fará, narra cada etapa e depois resume os resultados. +Fluxos de trabalho multi-etapas se beneficiam de planejamento antecipado e narração do progresso. O modelo esboça o que fará, narra cada passo e depois resume os resultados. ### Código Auto-Reflexivo -Experimente "Crie um serviço de validação de e-mail". Em vez de apenas gerar o código e parar, o modelo gera, avalia com critérios de qualidade, identifica pontos fracos e melhora. Você verá iterar até que o código alcance padrões de produção. +Experimente "Crie um serviço de validação de e-mails". Em vez de apenas gerar o código e parar, o modelo gera, avalia contra critérios de qualidade, identifica fraquezas e melhora. Você verá iterações até o código atingir padrões de produção. ### Análise Estruturada -Revisões de código precisam de frameworks consistentes de avaliação. O modelo analisa código usando categorias fixas (correção, práticas, desempenho, segurança) com níveis de severidade. +Revisões de código precisam de frameworks de avaliação consistentes. O modelo analisa o código usando categorias fixas (correção, práticas, desempenho, segurança) com níveis de severidade. ### Chat Multi-Turno -Pergunte "O que é Spring Boot?" e em seguida "Mostre um exemplo". O modelo lembra a primeira pergunta e fornece um exemplo específico de Spring Boot. Sem memória, a segunda pergunta seria vaga demais. +Pergunte "O que é Spring Boot?" e logo depois "Mostre-me um exemplo". O modelo lembra da primeira pergunta e fornece um exemplo de Spring Boot específico. Sem memória, essa segunda pergunta seria vaga demais. ### Raciocínio Passo a Passo -Escolha um problema matemático e tente tanto com Raciocínio Passo a Passo quanto com Baixa Empolgação. A baixa empolgação só dá a resposta — rápido, mas opaco. Passo a passo mostra cada cálculo e decisão. +Escolha um problema matemático e tente com Raciocínio Passo a Passo e Baixa Vontade. A baixa vontade dá só a resposta – rápido, mas opaco. O passo a passo mostra cada cálculo e decisão. -### Saída Constrita +### Saída Constrained -Quando você precisa de formatos ou contagens precisas de palavras, este padrão impõe aderência estrita. Experimente gerar um resumo com exatamente 100 palavras em formato de lista. +Quando você precisa de formatos ou contagens de palavras específicas, este padrão impõe aderência estrita. Experimente gerar um resumo com exatamente 100 palavras em formato de lista. ## O Que Você Está Realmente Aprendendo -**O Esforço de Raciocínio Muda Tudo** +**Esforço de Raciocínio Muda Tudo** -GPT-5.2 permite controlar o esforço computacional através dos seus prompts. Baixo esforço significa respostas rápidas com exploração mínima. Alto esforço faz o modelo pensar profundamente e com calma. Você está aprendendo a ajustar o esforço à complexidade da tarefa — não perca tempo com perguntas simples, mas também não apresse decisões complexas. +O GPT-5.2 permite controlar o esforço computacional através dos seus prompts. Baixo esforço significa respostas rápidas com exploração mínima. Alto esforço faz o modelo dedicar tempo para pensar profundamente. Você aprende a ajustar esforço à complexidade da tarefa – não perca tempo com perguntas simples, mas também não acelere decisões complexas. -**Estrutura Guia o Comportamento** +**Estrutura Guia Comportamento** -Percebe as tags XML nos prompts? Elas não são decorativas. Modelos seguem instruções estruturadas de forma mais confiável que texto livre. Quando você precisa de processos multi-etapas ou lógica complexa, a estrutura ajuda o modelo a rastrear onde está e o que vem a seguir. O diagrama abaixo detalha um prompt bem estruturado, mostrando como tags como ``, ``, ``, `` e `` organizam suas instruções em seções claras. +Reparou nas tags XML nos prompts? Elas não são decorativas. Modelos seguem instruções estruturadas com mais confiabilidade do que texto livre. Quando precisa de processos multi-etapas ou lógica complexa, estrutura ajuda o modelo a rastrear onde está e o que vem a seguir. O diagrama abaixo detalha um prompt bem estruturado, mostrando como tags como ``, ``, ``, ``, e `` organizam suas instruções em seções claras. Estrutura do Prompt -*Anatomia de um prompt bem estruturado com seções claras e organização estilo XML* +*Anatomia de um prompt bem estruturado com seções claras e organização ao estilo XML* -**Qualidade Por Autoavaliação** +**Qualidade Através da Autoavaliação** -Os padrões auto-reflexivos funcionam tornando explícitos os critérios de qualidade. Em vez de esperar que o modelo "faça certo", você define exatamente o que "certo" significa: lógica correta, tratamento de erros, desempenho, segurança. O modelo pode então avaliar sua própria saída e melhorar. Isso transforma geração de código de loteria em processo. +Os padrões auto-reflexivos funcionam tornando explícitos os critérios de qualidade. Em vez de esperar que o modelo “faça certo”, você diz exatamente o que “certo” significa: lógica correta, tratamento de erros, desempenho, segurança. O modelo pode então avaliar sua própria saída e melhorar. Isso transforma geração de código de um jogo de loteria em um processo. -**O Contexto é Finito** +**Contexto é Finito** -Conversas multi-turno funcionam incluindo o histórico das mensagens em cada requisição. Mas há limite — todo modelo tem contagem máxima de tokens. Conforme as conversas crescem, você precisará de estratégias para manter contexto relevante sem atingir esse teto. Este módulo mostra como a memória funciona; depois você aprenderá quando resumir, esquecer ou recuperar. +Conversas multi-turno funcionam incluindo histórico de mensagens a cada requisição. Mas há um limite – todo modelo tem um máximo de tokens. Conforme as conversas crescem, você precisará de estratégias para manter o contexto relevante sem ultrapassar esse limite. Este módulo mostra como a memória funciona; depois você aprenderá quando resumir, quando esquecer e quando recuperar. ## Próximos Passos -**Próximo Módulo:** [03-rag - RAG (Geração com Recuperação)](../03-rag/README.md) +**Próximo Módulo:** [03-rag - RAG (Geração Aumentada por Recuperação)](../03-rag/README.md) --- @@ -604,5 +604,5 @@ Conversas multi-turno funcionam incluindo o histórico das mensagens em cada req **Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. +Este documento foi traduzido usando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. \ No newline at end of file diff --git a/translations/pt-BR/03-rag/README.md b/translations/pt-BR/03-rag/README.md index 90ca54998..bb1036804 100644 --- a/translations/pt-BR/03-rag/README.md +++ b/translations/pt-BR/03-rag/README.md @@ -2,143 +2,142 @@ ## Índice -- [Vídeo Demonstrativo](../../../03-rag) -- [O Que Você Vai Aprender](../../../03-rag) -- [Pré-requisitos](../../../03-rag) -- [Entendendo o RAG](../../../03-rag) - - [Qual Abordagem RAG Este Tutorial Usa?](../../../03-rag) -- [Como Funciona](../../../03-rag) - - [Processamento de Documentos](../../../03-rag) - - [Criando Embeddings](../../../03-rag) - - [Busca Semântica](../../../03-rag) - - [Geração de Respostas](../../../03-rag) -- [Executando a Aplicação](../../../03-rag) -- [Usando a Aplicação](../../../03-rag) - - [Enviar um Documento](../../../03-rag) - - [Fazer Perguntas](../../../03-rag) - - [Verificar Referências das Fontes](../../../03-rag) - - [Experimentar com Perguntas](../../../03-rag) -- [Conceitos-Chave](../../../03-rag) - - [Estratégia de Chunking](../../../03-rag) - - [Pontuação de Similaridade](../../../03-rag) - - [Armazenamento em Memória](../../../03-rag) - - [Gerenciamento da Janela de Contexto](../../../03-rag) -- [Quando o RAG é Importante](../../../03-rag) -- [Próximos Passos](../../../03-rag) - -## Vídeo Demonstrativo +- [Vídeo Tutorial](#vídeo-tutorial) +- [O Que Você Vai Aprender](#o-que-você-vai-aprender) +- [Pré-requisitos](#pré-requisitos) +- [Entendendo o RAG](#entendendo-o-rag) + - [Qual abordagem RAG este tutorial utiliza?](#qual-abordagem-rag-este-tutorial-utiliza) +- [Como Funciona](#como-funciona) + - [Processamento de Documentos](#processamento-de-documentos) + - [Criando Embeddings](#criando-embeddings) + - [Busca Semântica](#busca-semântica) + - [Geração de Respostas](#geração-de-resposta) +- [Executar a Aplicação](#executar-a-aplicação) +- [Usando a Aplicação](#usando-a-aplicação) + - [Enviar um Documento](#fazer-upload-de-um-documento) + - [Fazer Perguntas](#fazer-perguntas) + - [Verificar Referências das Fontes](#verificar-referências-das-fontes) + - [Experimentar com Perguntas](#experimente-com-perguntas) +- [Conceitos-Chave](#conceitos-chave) + - [Estratégia de Fragmentação](#estratégia-de-divisão-em-pedaços) + - [Pontuações de Similaridade](#pontuações-de-similaridade) + - [Armazenamento em Memória](#armazenamento-em-memória) + - [Gerenciamento da Janela de Contexto](#gerenciamento-da-janela-de-contexto) +- [Quando o RAG Importa](#quando-o-rag-importa) +- [Próximos Passos](#próximos-passos) + +## Vídeo Tutorial Assista a esta sessão ao vivo que explica como começar com este módulo: -RAG com LangChain4j - Sessão ao Vivo +RAG with LangChain4j - Live Session ## O Que Você Vai Aprender -Nos módulos anteriores, você aprendeu como ter conversas com IA e estruturar seus prompts de forma eficaz. Mas existe uma limitação fundamental: modelos de linguagem só sabem o que aprenderam durante o treinamento. Eles não conseguem responder perguntas sobre as políticas da sua empresa, a documentação do seu projeto ou qualquer informação que não tenha sido usada durante o treinamento. +Nos módulos anteriores, você aprendeu a ter conversas com IA e estruturar seus prompts de forma eficaz. Mas há uma limitação fundamental: os modelos de linguagem só sabem o que aprenderam durante o treinamento. Eles não podem responder perguntas sobre as políticas da sua empresa, sua documentação de projeto ou qualquer informação na qual eles não foram treinados. -O RAG (Geração Aumentada por Recuperação) resolve esse problema. Em vez de tentar ensinar suas informações ao modelo (que é caro e impraticável), você dá a ele a capacidade de buscar nos seus documentos. Quando alguém faz uma pergunta, o sistema encontra informações relevantes e as inclui no prompt. O modelo então responde com base nesse contexto recuperado. +RAG (Geração Aumentada por Recuperação) resolve esse problema. Em vez de tentar ensinar o modelo suas informações (o que é caro e impraticável), você dá a ele a capacidade de buscar em seus documentos. Quando alguém faz uma pergunta, o sistema encontra informações relevantes e as inclui no prompt. O modelo então responde com base nesse contexto recuperado. Pense no RAG como dar ao modelo uma biblioteca de referência. Quando você faz uma pergunta, o sistema: 1. **Consulta do Usuário** - Você faz uma pergunta 2. **Embedding** - Converte sua pergunta em um vetor -3. **Busca Vetorial** - Encontra blocos de documento similares -4. **Montagem do Contexto** - Adiciona os blocos relevantes ao prompt -5. **Resposta** - O LLM gera uma resposta baseada no contexto +3. **Busca Vetorial** - Encontra fragmentos de documentos semelhantes +4. **Montagem do Contexto** - Adiciona os fragmentos relevantes ao prompt +5. **Resposta** - O LLM gera uma resposta baseado no contexto -Isso fundamenta as respostas do modelo nos seus dados reais ao invés de depender só do conhecimento do treinamento ou inventar respostas. +Isso fundamenta as respostas do modelo nos seus dados reais, em vez de depender somente do conhecimento do treinamento ou inventar respostas. ## Pré-requisitos -- Ter completado o [Módulo 00 - Início Rápido](../00-quick-start/README.md) (para o exemplo Easy RAG citado mais adiante neste módulo) -- Ter completado o [Módulo 01 - Introdução](../01-introduction/README.md) (recursos Azure OpenAI implantados, incluindo o modelo de embedding `text-embedding-3-small`) -- Arquivo `.env` no diretório raiz com credenciais Azure (criado pelo `azd up` no Módulo 01) +- Módulo [01 - Introdução](../01-introduction/README.md) concluído (recursos Azure OpenAI implantados, incluindo o modelo de embedding `text-embedding-3-small`) +- Arquivo `.env` no diretório raiz com credenciais Azure (criado pelo `azd up` no Módulo 01) -> **Nota:** Se você não completou o Módulo 01, siga as instruções de implantação lá primeiro. O comando `azd up` implanta tanto o modelo de chat GPT quanto o modelo de embedding usados por este módulo. +> **Nota:** Se você não completou o Módulo 01, siga as instruções de implantação lá primeiro. O comando `azd up` implanta tanto o modelo de chat GPT quanto o modelo de embedding usado por este módulo. ## Entendendo o RAG -O diagrama abaixo ilustra o conceito central: em vez de depender apenas dos dados de treinamento do modelo, o RAG oferece uma biblioteca de referência dos seus documentos para consultar antes de gerar cada resposta. +O diagrama abaixo ilustra o conceito principal: em vez de depender apenas dos dados de treino do modelo, o RAG fornece uma biblioteca de referência dos seus documentos para consultar antes de gerar cada resposta. -O que é RAG +What is RAG -*Este diagrama mostra a diferença entre um LLM padrão (que adivinha a partir dos dados de treinamento) e um LLM aprimorado com RAG (que consulta seus documentos primeiro).* +*Este diagrama mostra a diferença entre um LLM padrão (que adivinha com base nos dados de treino) e um LLM com RAG (que consulta seus documentos primeiro).* -Aqui está como as peças se conectam de ponta a ponta. A pergunta do usuário passa por quatro estágios — embedding, busca vetorial, montagem do contexto e geração da resposta — cada um construindo sobre o anterior: +Veja como as partes se conectam de ponta a ponta. A pergunta do usuário passa por quatro etapas — embedding, busca vetorial, montagem do contexto e geração de resposta — cada uma baseado na anterior: -Arquitetura RAG +RAG Architecture -*Este diagrama mostra a pipeline RAG de ponta a ponta — a consulta do usuário passa por embedding, busca vetorial, montagem do contexto e geração da resposta.* +*Este diagrama mostra o pipeline RAG de ponta a ponta — a consulta do usuário passa por embedding, busca vetorial, montagem do contexto e geração de resposta.* -O restante deste módulo explora cada etapa em detalhes, com código que você pode executar e modificar. +O restante deste módulo irá detalhar cada etapa, com código que você pode executar e modificar. -### Qual Abordagem RAG Este Tutorial Usa? +### Qual abordagem RAG este tutorial utiliza? -LangChain4j oferece três formas de implementar RAG, cada uma com um nível diferente de abstração. O diagrama abaixo as compara lado a lado: +LangChain4j oferece três maneiras de implementar RAG, cada uma com um nível diferente de abstração. O diagrama abaixo compara-as lado a lado: -Três Abordagens RAG em LangChain4j +Three RAG Approaches in LangChain4j -*Este diagrama compara as três abordagens RAG do LangChain4j — Easy, Nativo e Avançado — mostrando seus componentes chave e quando usar cada uma.* +*Este diagrama compara as três abordagens RAG do LangChain4j — Easy, Native e Advanced — mostrando seus componentes principais e quando usar cada uma.* -| Abordagem | O Que Ela Faz | Compromisso | +| Abordagem | O Que Faz | Compromisso | |---|---|---| -| **Easy RAG** | Integra tudo automaticamente via `AiServices` e `ContentRetriever`. Você anota uma interface, conecta um retriever, e o LangChain4j cuida do embedding, busca e montagem do prompt nos bastidores. | Código mínimo, mas você não vê o que acontece em cada passo. | -| **Native RAG** | Você chama o modelo de embedding, busca na loja, monta o prompt e gera a resposta você mesmo — um passo explícito de cada vez. | Mais código, mas cada etapa é visível e modificável. | -| **Advanced RAG** | Usa o framework `RetrievalAugmentor` com transformadores de consulta plugáveis, roteadores, reordenadores e injetores de conteúdo para pipelines de nível produção. | Flexibilidade máxima, mas com complexidade muito maior. | +| **Easy RAG** | Conecta tudo automaticamente via `AiServices` e `ContentRetriever`. Você anota uma interface, conecta um retriever, e o LangChain4j faz embedding, busca e montagem do prompt por trás dos panos. | Código mínimo, mas você não vê o que acontece em cada etapa. | +| **Native RAG** | Você chama o modelo de embedding, busca na loja, constrói o prompt e gera a resposta — um passo explícito de cada vez. | Mais código, mas cada etapa é visível e modificável. | +| **Advanced RAG** | Usa o framework `RetrievalAugmentor` com transformadores de consulta pluggable, roteadores, re-ranqueadores e injetores de conteúdo para pipelines de produção. | Máxima flexibilidade, porém muito mais complexidade. | -**Este tutorial usa a abordagem Nativa.** Cada passo da pipeline RAG — embedding da consulta, busca na loja vetorial, montagem do contexto e geração da resposta — está explicitamente escrito em [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Isso é intencional: como recurso de aprendizado, é mais importante que você veja e entenda cada etapa do que que o código seja minimizado. Quando se sentir confortável com as peças, pode migrar para Easy RAG para protótipos rápidos ou Advanced RAG para sistemas de produção. +**Este tutorial usa a abordagem Native.** Cada etapa do pipeline RAG — embedar a consulta, buscar na loja vetorial, montar o contexto e gerar a resposta — está explicitamente escrita em [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Isso é intencional: como recurso de aprendizado, é mais importante que você veja e entenda cada etapa do que ter o código minimizado. Quando estiver confortável com o funcionamento das partes, você pode evoluir para Easy RAG para protótipos rápidos ou Advanced RAG para sistemas de produção. -> **💡 Já viu o Easy RAG em ação?** O [módulo Início Rápido](../00-quick-start/README.md) inclui um exemplo de Perguntas & Respostas com Documentos ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) que usa a abordagem Easy RAG — o LangChain4j gerencia embedding, busca e montagem do prompt automaticamente. Este módulo dá o próximo passo, detalhando essa pipeline para que você veja e controle cada etapa. +> **💡 Curioso sobre Easy RAG?** O LangChain4j também oferece uma abordagem *Easy RAG* onde `AiServices` e um `ContentRetriever` cuidam automaticamente do embedding, busca e montagem do prompt. Este módulo segue um caminho mais explícito — desmistificando esse pipeline para você ver e controlar cada etapa. -O diagrama abaixo mostra a pipeline Easy RAG do exemplo do Início Rápido. Repare como `AiServices` e `EmbeddingStoreContentRetriever` escondem toda a complexidade — você carrega um documento, conecta um retriever e obtém respostas. A abordagem Nativa deste módulo abre cada uma dessas etapas ocultas: +O diagrama abaixo mostra o pipeline Easy RAG. Note como `AiServices` e `EmbeddingStoreContentRetriever` ocultam toda a complexidade — você carrega um documento, liga um retriever e obtém respostas. A abordagem Native deste módulo abre cada um desses passos ocultos: -Pipeline Easy RAG - LangChain4j +Easy RAG Pipeline - LangChain4j -*Este diagrama mostra a pipeline Easy RAG de `SimpleReaderDemo.java`. Compare com a abordagem Nativa usada neste módulo: Easy RAG oculta embedding, recuperação e montagem do prompt atrás de `AiServices` e `ContentRetriever` — você carrega um documento, conecta um retriever e obtém respostas. A abordagem Nativa deste módulo abre essa pipeline para que você chame cada etapa (embedar, buscar, montar contexto, gerar) você mesmo, oferecendo visibilidade e controle completos.* +*Este diagrama mostra o pipeline Easy RAG. Compare com a abordagem Native usada neste módulo: Easy RAG oculta embedding, recuperação e montagem do prompt atrás de `AiServices` e `ContentRetriever` — você carrega um documento, conecta um retriever e obtém respostas. A abordagem Native neste módulo abre esse pipeline para que você chame cada etapa (embedar, buscar, montar contexto, gerar) você mesmo, fornecendo total visibilidade e controle.* ## Como Funciona -A pipeline RAG deste módulo se divide em quatro etapas que são executadas em sequência toda vez que um usuário faz uma pergunta. Primeiro, um documento enviado é **analisado e fragmentado** em pedaços gerenciáveis. Esses pedaços são então convertidos em **embeddings vetoriais** e armazenados para comparações matemáticas. Quando chega uma consulta, o sistema realiza uma **busca semântica** para encontrar os pedaços mais relevantes e, por fim, os passa como contexto para o LLM para **geração da resposta**. As seções abaixo descrevem cada etapa com o código real e diagramas. Vamos olhar o primeiro passo. +O pipeline RAG deste módulo é dividido em quatro etapas que executam em sequência toda vez que um usuário faz uma pergunta. Primeiro, um documento enviado é **analisado e fragmentado** em pedaços gerenciáveis. Esses pedaços são então convertidos em **embeddings vetoriais** e armazenados para que possam ser comparados matematicamente. Quando uma consulta chega, o sistema realiza uma **busca semântica** para encontrar os fragmentos mais relevantes e, por fim, os passa como contexto para o LLM gerar a **resposta**. As seções abaixo detalham cada estágio com código real e diagramas. Vamos olhar a primeira etapa. ### Processamento de Documentos [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Quando você envia um documento, o sistema o analisa (PDF ou texto simples), anexa metadados como o nome do arquivo e então divide em pedaços — partes menores que cabem confortavelmente na janela de contexto do modelo. Esses pedaços se sobrepõem ligeiramente para que você não perca o contexto nas fronteiras. +Quando você envia um documento, o sistema o analisa (PDF ou texto simples), anexa metadados como o nome do arquivo, e então o quebra em fragmentos — pedaços menores que cabem confortavelmente na janela de contexto do modelo. Esses fragmentos se sobrepõem levemente para que você não perca o contexto nas bordas. ```java // Analise o arquivo enviado e envolva-o em um Documento LangChain4j Document document = Document.from(content, metadata); -// Divida em pedaços de 300 tokens com sobreposição de 30 tokens +// Divida em blocos de 300 tokens com sobreposição de 30 tokens DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -O diagrama abaixo mostra como isso funciona visualmente. Note como cada pedaço compartilha alguns tokens com seus vizinhos — a sobreposição de 30 tokens garante que nenhum contexto importante fique perdido: +O diagrama abaixo mostra como isso funciona visualmente. Repare como cada fragmento compartilha alguns tokens com seus vizinhos — a sobreposição de 30 tokens garante que nenhum contexto importante fique fora: -Fragmentação de Documento +Document Chunking -*Este diagrama mostra um documento sendo dividido em pedaços de 300 tokens com sobreposição de 30 tokens, preservando o contexto nas bordas dos pedaços.* +*Este diagrama mostra um documento sendo dividido em fragmentos de 300 tokens com 30 tokens de sobreposição, preservando o contexto nas bordas dos fragmentos.* > **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) e pergunte: -> - "Como o LangChain4j divide documentos em pedaços e por que a sobreposição é importante?" -> - "Qual é o tamanho ideal dos pedaços para diferentes tipos de documento e por quê?" +> - "Como o LangChain4j divide documentos em fragmentos e por que a sobreposição é importante?" +> - "Qual é o tamanho ideal dos fragmentos para diferentes tipos de documento e por quê?" > - "Como lidar com documentos em múltiplos idiomas ou com formatação especial?" ### Criando Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Cada pedaço é convertido em uma representação numérica chamada embedding — essencialmente um conversor do significado para números. O modelo de embedding não é "inteligente" como um modelo de chat; ele não segue instruções, não raciocina nem responde perguntas. O que ele faz é mapear texto em um espaço matemático onde significados similares ficam próximos — "carro" perto de "automóvel", "política de reembolso" perto de "devolver meu dinheiro". Pense em um modelo de chat como uma pessoa com quem você conversa; um modelo de embedding é um sistema de arquivamento ultra eficaz. +Cada fragmento é convertido em uma representação numérica chamada embedding — essencialmente um conversor de significado para números. O modelo de embedding não é "inteligente" como um modelo de chat; ele não pode seguir instruções, raciocinar ou responder perguntas. O que ele faz é mapear texto em um espaço matemático onde significados semelhantes ficam próximos — "carro" próximo de "automóvel", "política de reembolso" próximo de "devolver meu dinheiro". Pense em um modelo de chat como uma pessoa com quem você conversa; um modelo de embedding é um sistema de arquivamento ultra eficaz. -O diagrama abaixo visualiza este conceito — o texto entra, vetores numéricos saem, e significados similares produzem vetores próximos: +O diagrama abaixo visualiza esse conceito — texto entra, vetores numéricos saem, e significados parecidos produzem vetores próximos: -Conceito de Modelo de Embedding +Embedding Model Concept -*Este diagrama mostra como um modelo de embedding converte texto em vetores numéricos, posicionando significados similares — como "carro" e "automóvel" — próximos uns dos outros no espaço vetorial.* +*Este diagrama mostra como um modelo de embedding converte texto em vetores numéricos, colocando significados semelhantes — como "carro" e "automóvel" — próximos uns dos outros no espaço vetorial.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -O diagrama de classes abaixo mostra os dois fluxos separados numa pipeline RAG e as classes do LangChain4j que os implementam. O **fluxo de ingestão** (executado uma vez na hora do upload) divide o documento, gera embeddings dos pedaços e os armazena via `.addAll()`. O **fluxo de consulta** (executado toda vez que um usuário pergunta) gera embedding da pergunta, busca na loja via `.search()` e passa o contexto correspondente para o modelo de chat. Ambos os fluxos convergem na interface compartilhada `EmbeddingStore`: +O diagrama de classes abaixo mostra os dois fluxos separados em um pipeline RAG e as classes LangChain4j que os implementam. O **fluxo de ingestão** (executado uma vez ao enviar) divide o documento, gera embeddings dos fragmentos e os armazena via `.addAll()`. O **fluxo de consulta** (executado cada vez que um usuário pergunta) gera embedding da questão, busca na loja via `.search()`, e passa o contexto encontrado para o modelo de chat. Ambos os fluxos se conectam pela interface compartilhada `EmbeddingStore`: -Classes RAG do LangChain4j +LangChain4j RAG Classes -*Este diagrama mostra os dois fluxos numa pipeline RAG — ingestão e consulta — e como eles se conectam através de um EmbeddingStore compartilhado.* +*Este diagrama mostra os dois fluxos do pipeline RAG — ingestão e consulta — e como se conectam através de um EmbeddingStore compartilhado.* -Uma vez que embeddings estão armazenados, conteúdos similares naturalmente formam aglomerados no espaço vetorial. A visualização abaixo mostra como documentos sobre tópicos relacionados ficam próximos, o que torna possível a busca semântica: +Uma vez armazenados os embeddings, conteúdos semelhantes naturalmente se agrupam no espaço vetorial. A visualização abaixo mostra como documentos sobre tópicos relacionados acabam próximos, o que torna a busca semântica possível: -Espaço de Embeddings Vetoriais +Vector Embeddings Space -*Esta visualização demonstra como documentos relacionados se agrupam no espaço vetorial 3D, com tópicos como Documentação Técnica, Regras de Negócio e FAQs formando grupos distintos.* +*Esta visualização mostra como documentos relacionados se agrupam no espaço vetorial 3D, com tópicos como Documentação Técnica, Regras de Negócio e FAQs formando grupos distintos.* -Quando um usuário faz uma busca, o sistema segue quatro passos: embedar os documentos uma vez, embedar a consulta a cada busca, comparar o vetor da consulta com todos os vetores armazenados usando similaridade do cosseno e retornar os top-K pedaços com pontuação mais alta. O diagrama abaixo mostra cada passo e as classes LangChain4j envolvidas: +Quando um usuário realiza uma busca, o sistema segue quatro passos: embedar os documentos uma vez, embedar a consulta em cada busca, comparar o vetor da consulta contra todos os vetores armazenados usando similaridade cosseno, e retornar os K fragmentos com as maiores pontuações. O diagrama abaixo ilustra cada etapa e as classes LangChain4j envolvidas: -Passos da Busca por Embeddings +Embedding Search Steps -*Este diagrama mostra o processo de busca em quatro etapas: embedar documentos, embedar a consulta, comparar vetores com similaridade do cosseno e retornar os top-K resultados.* +*Este diagrama mostra o processo de busca via embeddings em quatro etapas: embedar documentos, embedar consulta, comparar vetores com similaridade cosseno e retornar os melhores resultados.* ### Busca Semântica [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Quando você pergunta algo, sua pergunta também vira um embedding. O sistema compara o embedding da sua pergunta com os embeddings de todos os pedaços do documento. Ele encontra os pedaços com significados mais similares — não só combinando palavras-chave, mas com real similaridade semântica. +Quando você faz uma pergunta, sua questão também é convertida em embedding. O sistema compara o embedding da pergunta com todos os embeddings dos fragmentos do documento. Ele encontra os fragmentos com significados mais similares — não somente palavras-chave correspondentes, mas similaridade semântica real. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -O diagrama abaixo contrasta busca semântica com busca tradicional por palavra-chave. Uma busca por palavra-chave por "veículo" perde um pedaço sobre "carros e caminhões", mas a busca semântica entende que significam a mesma coisa e o retorna como uma correspondência com alta pontuação: +O diagrama abaixo contrasta busca semântica com busca tradicional por palavra-chave. Uma busca por palavra-chave por "veículo" perde um fragmento sobre "carros e caminhões," mas a busca semântica entende que têm o mesmo significado e o retorna como resultado relevante: -Busca Semântica +Semantic Search -*Este diagrama compara busca baseada em palavra-chave com busca semântica, mostrando como a busca semântica recupera conteúdo relacionado conceitualmente mesmo quando as palavras exatas diferem.* -Por trás das cenas, a similaridade é medida usando similaridade do cosseno — basicamente perguntando "esses dois vetores estão apontando na mesma direção?" Dois pedaços podem usar palavras completamente diferentes, mas se tiverem o mesmo significado, seus vetores apontam na mesma direção e obtêm uma pontuação próxima de 1,0: +*Este diagrama compara busca baseada em palavras-chave com busca semântica, mostrando como a busca semântica recupera conteúdos conceitualmente relacionados mesmo quando as palavras exatas são diferentes.* -Cosine Similarity +Nos bastidores, a similaridade é medida usando similaridade cosseno — basicamente perguntando "esses dois vetores apontam na mesma direção?" Dois fragmentos podem usar palavras completamente diferentes, mas se significam o mesmo, seus vetores apontam na mesma direção e têm pontuação próxima de 1.0: -*Este diagrama ilustra a similaridade do cosseno como o ângulo entre os vetores de embedding — vetores mais alinhados obtêm uma pontuação mais próxima de 1,0, indicando maior similaridade semântica.* +Cosine Similarity +*Este diagrama ilustra a similaridade do cosseno como o ângulo entre vetores de embedding — vetores mais alinhados têm pontuação mais próxima de 1,0, indicando maior similaridade semântica.* -> **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) e pergunte: +> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) e pergunte: > - "Como funciona a busca por similaridade com embeddings e o que determina a pontuação?" > - "Qual limiar de similaridade devo usar e como isso afeta os resultados?" -> - "Como lidar com casos em que nenhum documento relevante é encontrado?" +> - "Como lidar com casos onde nenhum documento relevante é encontrado?" ### Geração de Resposta [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Os pedaços mais relevantes são montados em um prompt estruturado que inclui instruções explícitas, o contexto recuperado e a pergunta do usuário. O modelo lê esses pedaços específicos e responde com base nessa informação — ele só pode usar o que está à sua frente, o que evita alucinações. +Os pedaços mais relevantes são reunidos em um prompt estruturado que inclui instruções explícitas, o contexto recuperado e a pergunta do usuário. O modelo lê aqueles pedaços específicos e responde com base nessa informação — ele só pode usar o que está à sua frente, o que previne alucinações. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -O diagrama abaixo mostra essa montagem em ação — os pedaços com melhor pontuação da etapa de busca são injetados no template de prompt, e o `OpenAiOfficialChatModel` gera uma resposta fundamentada: +O diagrama abaixo mostra esse processo em ação — os pedaços com maior pontuação da etapa de busca são inseridos no template do prompt, e o `OpenAiOfficialChatModel` gera uma resposta fundamentada: Context Assembly -*Este diagrama mostra como os pedaços com melhor pontuação são montados em um prompt estruturado, permitindo que o modelo gere uma resposta fundamentada a partir dos seus dados.* +*Este diagrama mostra como os pedaços com maior pontuação são reunidos em um prompt estruturado, permitindo que o modelo gere uma resposta fundamentada a partir dos seus dados.* -## Execute a Aplicação +## Executar a Aplicação **Verifique a implantação:** -Certifique-se de que o arquivo `.env` exista no diretório raiz com as credenciais do Azure (criadas durante o Módulo 01). Execute isto a partir do diretório do módulo (`03-rag/`): +Certifique-se de que o arquivo `.env` existe no diretório raiz com credenciais Azure (criado durante o Módulo 01). Execute isso a partir do diretório do módulo (`03-rag/`): **Bash:** ```bash @@ -261,17 +260,17 @@ Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Inicie a aplicação:** -> **Nota:** Se você já iniciou todas as aplicações usando `./start-all.sh` a partir do diretório raiz (como descrito no Módulo 01), este módulo já está rodando na porta 8081. Você pode pular os comandos de inicialização abaixo e ir diretamente para http://localhost:8081. +> **Nota:** Se você já iniciou todas as aplicações usando `./start-all.sh` a partir do diretório raiz (como descrito no Módulo 01), este módulo já está rodando na porta 8081. Você pode pular os comandos de inicialização abaixo e ir direto para http://localhost:8081. **Opção 1: Usando o Spring Boot Dashboard (Recomendado para usuários do VS Code)** -O contêiner de desenvolvimento inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerenciar todas as aplicações Spring Boot. Você pode encontrá-lo na Barra de Atividades do lado esquerdo do VS Code (procure o ícone do Spring Boot). +O dev container inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerenciar todas as aplicações Spring Boot. Você pode encontrá-la na Barra de Atividades à esquerda do VS Code (procure pelo ícone do Spring Boot). -A partir do Spring Boot Dashboard, você pode: +No Spring Boot Dashboard, você pode: - Ver todas as aplicações Spring Boot disponíveis no workspace -- Iniciar/parar aplicações com um único clique -- Visualizar logs das aplicações em tempo real -- Monitorar o status das aplicações +- Iniciar/parar aplicações com um clique +- Visualizar logs da aplicação em tempo real +- Monitorar o status da aplicação Basta clicar no botão de play ao lado de "rag" para iniciar este módulo, ou iniciar todos os módulos de uma vez. @@ -291,7 +290,7 @@ cd .. # A partir do diretório raiz **PowerShell:** ```powershell -cd .. # Do diretório raiz +cd .. # A partir do diretório raiz .\start-all.ps1 ``` @@ -309,7 +308,7 @@ cd 03-rag .\start.ps1 ``` -Ambos os scripts carregam automaticamente as variáveis de ambiente do arquivo `.env` raiz e vão construir os JARs caso não existam. +Ambos os scripts carregam automaticamente as variáveis de ambiente do arquivo `.env` raiz e irão construir os JARs se eles não existirem. > **Nota:** Se preferir construir todos os módulos manualmente antes de iniciar: > @@ -331,7 +330,7 @@ Abra http://localhost:8081 no seu navegador. **Bash:** ```bash -./stop.sh # Este módulo apenas +./stop.sh # Apenas este módulo # Ou cd .. && ./stop-all.sh # Todos os módulos ``` @@ -345,81 +344,81 @@ cd ..; .\stop-all.ps1 # Todos os módulos ## Usando a Aplicação -A aplicação fornece uma interface web para upload de documentos e realização de perguntas. +A aplicação oferece uma interface web para upload de documentos e perguntas. RAG Application Interface -*Esta captura de tela mostra a interface da aplicação RAG onde você pode enviar documentos e fazer perguntas.* +*Esta captura de tela mostra a interface da aplicação RAG onde você carrega documentos e faz perguntas.* -### Enviar um Documento +### Fazer Upload de um Documento -Comece enviando um documento — arquivos TXT funcionam melhor para testes. Um `sample-document.txt` é fornecido neste diretório e contém informações sobre recursos do LangChain4j, implementação do RAG e melhores práticas — perfeito para testar o sistema. +Comece fazendo upload de um documento — arquivos TXT funcionam melhor para teste. Um `sample-document.txt` é fornecido neste diretório que contém informações sobre recursos do LangChain4j, implementação RAG e melhores práticas — perfeito para testar o sistema. -O sistema processa seu documento, divide em pedaços, e cria embeddings para cada pedaço. Isso acontece automaticamente quando você faz o upload. +O sistema processa seu documento, divide em pedaços e cria embeddings para cada pedaço. Isso acontece automaticamente ao enviar o arquivo. -### Faça Perguntas +### Fazer Perguntas -Agora faça perguntas específicas sobre o conteúdo do documento. Tente algo factual que esteja claramente declarado no documento. O sistema busca pedaços relevantes, inclui-os no prompt, e gera uma resposta. +Agora faça perguntas específicas sobre o conteúdo do documento. Tente algo factual que esteja claramente declarado no documento. O sistema busca pedaços relevantes, inclui-os no prompt e gera uma resposta. -### Verifique as Referências de Fonte +### Verificar Referências das Fontes -Observe que cada resposta inclui referências de fonte com pontuações de similaridade. Essas pontuações (de 0 a 1) mostram o quão relevante cada pedaço foi para sua pergunta. Pontuações mais altas significam correspondências melhores. Isso permite que você verifique a resposta com o material fonte. +Repare que cada resposta inclui referências das fontes com pontuações de similaridade. Essas pontuações (de 0 a 1) mostram quão relevante cada pedaço foi para sua pergunta. Pontuações mais altas significam melhores correspondências. Isso permite que você verifique a resposta em relação ao material fonte. RAG Query Results -*Esta captura de tela mostra os resultados da consulta com a resposta gerada, referências de fonte e pontuações de relevância para cada pedaço recuperado.* +*Esta captura de tela mostra os resultados da consulta com a resposta gerada, referências das fontes e pontuações de relevância para cada pedaço recuperado.* ### Experimente com Perguntas -Tente diferentes tipos de perguntas: +Teste diferentes tipos de perguntas: - Fatos específicos: "Qual é o tema principal?" -- Comparações: "Qual a diferença entre X e Y?" -- Resumos: "Resuma os pontos chave sobre Z" +- Comparações: "Qual é a diferença entre X e Y?" +- Resumos: "Resuma os pontos-chave sobre Z" -Observe como as pontuações de relevância mudam com base no quão bem sua pergunta corresponde ao conteúdo do documento. +Observe como as pontuações de relevância mudam com base em quão bem sua pergunta corresponde ao conteúdo do documento. ## Conceitos-Chave -### Estratégia de Quebra em Pedaços +### Estratégia de Divisão em Pedaços -Documentos são divididos em pedaços de 300 tokens com 30 tokens de sobreposição. Esse equilíbrio garante que cada pedaço tenha contexto suficiente para ser significativo, enquanto permanece pequeno o suficiente para incluir múltiplos pedaços em um prompt. +Documentos são divididos em pedaços de 300 tokens com 30 tokens de sobreposição. Este equilíbrio garante que cada pedaço tenha contexto suficiente para ser significativo, enquanto permanece pequeno o bastante para incluir múltiplos pedaços no prompt. ### Pontuações de Similaridade -Cada pedaço recuperado vem com uma pontuação de similaridade entre 0 e 1 que indica o quão próximo ele está da pergunta do usuário. O diagrama abaixo visualiza as faixas de pontuação e como o sistema as usa para filtrar resultados: +Cada pedaço recuperado vem com uma pontuação de similaridade entre 0 e 1 que indica o quão próximo ele corresponde à pergunta do usuário. O diagrama abaixo visualiza os intervalos de pontuação e como o sistema os usa para filtrar resultados: Similarity Scores -*Este diagrama mostra faixas de pontuação de 0 a 1, com um limiar mínimo de 0,5 que filtra pedaços irrelevantes.* +*Este diagrama mostra intervalos de pontuação de 0 a 1, com um limiar mínimo de 0,5 que filtra pedaços irrelevantes.* As pontuações variam de 0 a 1: - 0,7-1,0: Altamente relevante, correspondência exata - 0,5-0,7: Relevante, bom contexto -- Abaixo de 0,5: Filtrado, muito diferente +- Abaixo de 0,5: Filtrado, muito dissimilar O sistema recupera apenas pedaços acima do limiar mínimo para garantir qualidade. -Embeddings funcionam bem quando o significado se agrupa claramente, mas têm pontos cegos. O diagrama abaixo mostra modos comuns de falha — pedaços muito grandes produzem vetores confusos, pedaços muito pequenos carecem de contexto, termos ambíguos apontam para múltiplos agrupamentos e buscas por correspondência exata (IDs, números de peça) não funcionam com embeddings: +Embeddings funcionam bem quando o significado forma clusters claros, mas possuem pontos cegos. O diagrama abaixo mostra modos comuns de falha — pedaços muito grandes produzem vetores confusos, pedaços pequenos demais carecem de contexto, termos ambíguos apontam para múltiplos clusters, e buscas de correspondência exata (IDs, números de peça) não funcionam com embeddings: Embedding Failure Modes -*Este diagrama mostra modos comuns de falha em embeddings: pedaços grandes demais, pedaços pequenos demais, termos ambíguos que apontam para múltiplos agrupamentos e buscas por correspondência exata como IDs.* +*Este diagrama mostra modos comuns de falha em embeddings: pedaços muito grandes, pedaços muito pequenos, termos ambíguos que apontam para múltiplos clusters, e buscas de correspondência exata como IDs.* ### Armazenamento em Memória -Este módulo usa armazenamento em memória para simplicidade. Quando você reinicia a aplicação, documentos enviados são perdidos. Sistemas de produção usam bancos de dados vetoriais persistentes como Qdrant ou Azure AI Search. +Este módulo usa armazenamento em memória para simplicidade. Quando você reinicia a aplicação, os documentos enviados são perdidos. Sistemas de produção usam bancos de dados vetoriais persistentes como Qdrant ou Azure AI Search. ### Gerenciamento da Janela de Contexto -Cada modelo tem uma janela máxima de contexto. Você não pode incluir todos os pedaços de um documento grande. O sistema recupera os N pedaços mais relevantes (padrão 5) para permanecer dentro dos limites, oferecendo contexto suficiente para respostas precisas. +Cada modelo tem uma janela máxima de contexto. Você não pode incluir todos os pedaços de um documento grande. O sistema recupera os N pedaços mais relevantes (padrão 5) para ficar dentro dos limites enquanto fornece contexto suficiente para respostas precisas. -## Quando RAG é Importante +## Quando o RAG Importa -RAG nem sempre é a abordagem certa. O guia de decisão abaixo ajuda a determinar quando RAG agrega valor versus quando abordagens mais simples — como incluir conteúdo direto no prompt ou confiar no conhecimento embutido do modelo — são suficientes: +RAG nem sempre é a abordagem correta. O guia de decisão abaixo ajuda a determinar quando o RAG agrega valor versus quando abordagens mais simples — como incluir conteúdo diretamente no prompt ou confiar no conhecimento embutido do modelo — são suficientes: When to Use RAG -*Este diagrama mostra um guia de decisão para quando RAG agrega valor versus quando abordagens mais simples são suficientes.* +*Este diagrama mostra um guia de decisão para quando o RAG agrega valor versus quando abordagens mais simples são suficientes.* ## Próximos Passos @@ -427,11 +426,11 @@ RAG nem sempre é a abordagem certa. O guia de decisão abaixo ajuda a determina --- -**Navegação:** [← Anterior: Módulo 02 - Engenharia de Prompt](../02-prompt-engineering/README.md) | [Voltar ao Principal](../README.md) | [Próximo: Módulo 04 - Ferramentas →](../04-tools/README.md) +**Navegação:** [← Anterior: Módulo 02 - Engenharia de Prompt](../02-prompt-engineering/README.md) | [Voltar ao Início](../README.md) | [Próximo: Módulo 04 - Ferramentas →](../04-tools/README.md) --- **Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte oficial. Para informações críticas, recomenda-se a tradução profissional feita por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução. +Este documento foi traduzido usando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. \ No newline at end of file diff --git a/translations/pt-BR/04-tools/README.md b/translations/pt-BR/04-tools/README.md index 950b5a5d8..e14bc7c82 100644 --- a/translations/pt-BR/04-tools/README.md +++ b/translations/pt-BR/04-tools/README.md @@ -2,75 +2,75 @@ ## Índice -- [Vídeo Tutorial](../../../04-tools) -- [O que você vai aprender](../../../04-tools) -- [Pré-requisitos](../../../04-tools) -- [Entendendo Agentes de IA com Ferramentas](../../../04-tools) -- [Como Funciona a Chamada de Ferramentas](../../../04-tools) - - [Definições de Ferramentas](../../../04-tools) - - [Tomada de Decisão](../../../04-tools) - - [Execução](../../../04-tools) - - [Geração de Respostas](../../../04-tools) - - [Arquitetura: Injeção Automática do Spring Boot](../../../04-tools) -- [Encadeamento de Ferramentas](../../../04-tools) -- [Executar a Aplicação](../../../04-tools) -- [Usando a Aplicação](../../../04-tools) - - [Tente Uso Simples de Ferramentas](../../../04-tools) - - [Teste o Encadeamento de Ferramentas](../../../04-tools) - - [Veja o Fluxo de Conversa](../../../04-tools) - - [Experimente com Pedidos Diferentes](../../../04-tools) -- [Conceitos-Chave](../../../04-tools) - - [Padrão ReAct (Raciocínio e Ação)](../../../04-tools) - - [Descrições de Ferramentas Importam](../../../04-tools) - - [Gerenciamento de Sessão](../../../04-tools) - - [Tratamento de Erros](../../../04-tools) -- [Ferramentas Disponíveis](../../../04-tools) -- [Quando Usar Agentes Baseados em Ferramentas](../../../04-tools) -- [Ferramentas vs RAG](../../../04-tools) -- [Próximos Passos](../../../04-tools) - -## Vídeo Tutorial +- [Vídeo Passo a Passo](#vídeo-passo-a-passo) +- [O Que Você Vai Aprender](#o-que-você-vai-aprender) +- [Pré-requisitos](#pré-requisitos) +- [Compreendendo Agentes de IA com Ferramentas](#compreendendo-agentes-de-ia-com-ferramentas) +- [Como Funciona a Chamada de Ferramentas](#como-funciona-a-chamada-de-ferramentas) + - [Definições de Ferramentas](#definições-de-ferramentas) + - [Tomada de Decisão](#tomada-de-decisão) + - [Execução](#execução) + - [Geração de Resposta](#geração-de-resposta) + - [Arquitetura: Auto-Injeção do Spring Boot](#arquitetura-auto-injeção-do-spring-boot) +- [Encadeamento de Ferramentas](#encadeamento-de-ferramentas) +- [Executar a Aplicação](#executar-a-aplicação) +- [Usando a Aplicação](#usando-a-aplicação) + - [Teste o Uso Simples de Ferramentas](#experimente-o-uso-simples-de-ferramentas) + - [Teste o Encadeamento de Ferramentas](#teste-a-encadeação-de-ferramentas) + - [Veja o Fluxo da Conversa](#veja-o-fluxo-da-conversa) + - [Experimente Diferentes Solicitações](#experimente-diferentes-solicitações) +- [Conceitos Chave](#conceitos-chave) + - [Padrão ReAct (Raciocínio e Ação)](#padrão-react-raciocínio-e-ação) + - [Descrições das Ferramentas Importam](#descrições-de-ferramentas-importam) + - [Gerenciamento de Sessão](#gerenciamento-de-sessão) + - [Tratamento de Erros](#tratamento-de-erros) +- [Ferramentas Disponíveis](#ferramentas-disponíveis) +- [Quando Usar Agentes Baseados em Ferramentas](#quando-usar-agentes-baseados-em-ferramentas) +- [Ferramentas vs RAG](#ferramentas-vs-rag) +- [Próximos Passos](#próximos-passos) + +## Vídeo Passo a Passo Assista a esta sessão ao vivo que explica como começar com este módulo: Agentes de IA com Ferramentas e MCP - Sessão ao Vivo -## O que você vai aprender +## O Que Você Vai Aprender -Até agora, você aprendeu a ter conversas com IA, estruturar prompts efetivamente e fundamentar respostas em seus documentos. Mas ainda existe uma limitação fundamental: modelos de linguagem só podem gerar texto. Eles não conseguem verificar o clima, realizar cálculos, consultar bancos de dados ou interagir com sistemas externos. +Até agora, você aprendeu como ter conversas com IA, estruturar prompts de forma eficaz e basear respostas em seus documentos. Mas ainda há uma limitação fundamental: modelos de linguagem só conseguem gerar texto. Eles não conseguem verificar a previsão do tempo, realizar cálculos, consultar bancos de dados ou interagir com sistemas externos. -Ferramentas mudam isso. Ao dar ao modelo acesso a funções que ele pode chamar, você o transforma de um gerador de texto em um agente que pode tomar ações. O modelo decide quando precisa de uma ferramenta, qual usar e quais parâmetros passar. Seu código executa a função e retorna o resultado. O modelo incorpora esse resultado em sua resposta. +Ferramentas mudam isso. Ao dar ao modelo acesso a funções que ele pode chamar, você o transforma de um gerador de texto em um agente que pode agir. O modelo decide quando precisa de uma ferramenta, qual usar e quais parâmetros passar. Seu código executa a função e retorna o resultado. O modelo incorpora esse resultado em sua resposta. ## Pré-requisitos -- Concluído o [Módulo 01 - Introdução](../01-introduction/README.md) (recursos Azure OpenAI implantados) -- Recomendado ter completado os módulos anteriores (este módulo faz referência aos [conceitos RAG do Módulo 03](../03-rag/README.md) na comparação Ferramentas vs RAG) -- Arquivo `.env` no diretório raiz com credenciais Azure (criado pelo `azd up` no Módulo 01) +- Ter concluído o [Módulo 01 - Introdução](../01-introduction/README.md) (recursos Azure OpenAI implantados) +- Ter concluído os módulos anteriores recomendados (este módulo faz referências aos [conceitos de RAG do Módulo 03](../03-rag/README.md) na comparação Ferramentas vs RAG) +- Arquivo `.env` na raiz com credenciais Azure (criado por `azd up` no Módulo 01) -> **Nota:** Se você não concluiu o Módulo 01, siga primeiro as instruções de implantação lá. +> **Nota:** Se você não completou o Módulo 01, siga primeiro as instruções de implantação daquele módulo. -## Entendendo Agentes de IA com Ferramentas +## Compreendendo Agentes de IA com Ferramentas -> **📝 Nota:** O termo "agentes" neste módulo se refere a assistentes de IA aprimorados com capacidades de chamada de ferramentas. Isso é diferente dos padrões de **Agentic AI** (agentes autônomos com planejamento, memória e raciocínio em múltiplas etapas) que cobriremos no [Módulo 05: MCP](../05-mcp/README.md). +> **📝 Nota:** O termo "agentes" neste módulo refere-se a assistentes de IA aprimorados com a capacidade de chamar ferramentas. Isso é diferente dos padrões de **Agentic AI** (agentes autônomos com planejamento, memória e raciocínio multi-etapas) que abordaremos no [Módulo 05: MCP](../05-mcp/README.md). -Sem ferramentas, um modelo de linguagem só pode gerar texto baseado em seu treinamento. Pergunte o clima atual e ele tem que adivinhar. Dê ferramentas a ele, e pode chamar uma API de clima, realizar cálculos ou consultar um banco de dados — depois tecer esses resultados reais em sua resposta. +Sem ferramentas, um modelo de linguagem só pode gerar texto a partir de seus dados de treinamento. Pergunte sobre o tempo atual e ele terá que adivinhar. Dê ferramentas a ele, e ele pode chamar uma API de clima, fazer cálculos, ou consultar um banco de dados — e então entrelaçar esses resultados reais em sua resposta. Sem Ferramentas vs Com Ferramentas -*Sem ferramentas, o modelo só pode adivinhar — com ferramentas ele pode chamar APIs, rodar cálculos e retornar dados em tempo real.* +*Sem ferramentas, o modelo só pode adivinhar — com ferramentas, ele pode chamar APIs, fazer cálculos e retornar dados em tempo real.* -Um agente de IA com ferramentas segue um padrão **Raciocínio e Ação (ReAct)**. O modelo não apenas responde — ele pensa no que precisa, age chamando uma ferramenta, observa o resultado e depois decide se age novamente ou entrega a resposta final: +Um agente de IA com ferramentas segue o padrão **Raciocínio e Ação (ReAct)**. O modelo não apenas responde — ele pensa no que precisa, age chamando uma ferramenta, observa o resultado e então decide se age novamente ou entrega a resposta final: -1. **Raciocinar** — O agente analisa a pergunta do usuário e determina qual informação precisa -2. **Agir** — O agente seleciona a ferramenta correta, gera os parâmetros certos e a chama -3. **Observar** — O agente recebe a saída da ferramenta e avalia o resultado -4. **Repetir ou Responder** — Se precisar de mais dados, o agente retorna ao passo anterior; caso contrário, compõe uma resposta em linguagem natural +1. **Raciocina** — O agente analisa a pergunta do usuário e determina quais informações precisa +2. **Age** — O agente seleciona a ferramenta correta, gera os parâmetros e a chama +3. **Observa** — O agente recebe a saída da ferramenta e avalia o resultado +4. **Repete ou Responde** — Se precisar de mais dados, o agente volta ao início; senão, compõe a resposta em linguagem natural Padrão ReAct *O ciclo ReAct — o agente raciocina sobre o que fazer, age chamando uma ferramenta, observa o resultado e repete até entregar a resposta final.* -Isso acontece automaticamente. Você define as ferramentas e suas descrições. O modelo cuida da tomada de decisão sobre quando e como usá-las. +Isso acontece automaticamente. Você define as ferramentas e suas descrições. O modelo cuida da decisão de quando e como usá-las. ## Como Funciona a Chamada de Ferramentas @@ -78,7 +78,7 @@ Isso acontece automaticamente. Você define as ferramentas e suas descrições. [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Você define funções com descrições claras e especificações de parâmetros. O modelo vê essas descrições em seu prompt do sistema e entende o que cada ferramenta faz. +Você define funções com descrições claras e especificações de parâmetros. O modelo vê essas descrições no prompt do sistema e entende o que cada ferramenta faz. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Sua lógica de consulta do tempo + // Sua lógica de consulta de clima return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// O assistente é automaticamente configurado pelo Spring Boot com: +// O assistente é automaticamente conectado pelo Spring Boot com: // - Bean ChatModel -// - Todos os métodos @Tool de classes @Component +// - Todos os métodos @Tool das classes @Component // - ChatMemoryProvider para gerenciamento de sessão ``` -O diagrama abaixo detalha cada anotação e mostra como cada parte ajuda a IA a entender quando chamar a ferramenta e quais argumentos passar: +O diagrama abaixo explica cada anotação e mostra como cada parte ajuda a IA a entender quando chamar a ferramenta e quais argumentos passar: Anatomia das Definições de Ferramentas -*Anatomia de uma definição de ferramenta — @Tool indica à IA quando usá-la, @P descreve cada parâmetro e @AiService conecta tudo na inicialização.* +*Anatomia de uma definição de ferramenta — @Tool indica à IA quando usar, @P descreve cada parâmetro, e @AiService conecta tudo na inicialização.* > **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) e pergunte: -> - "Como eu integraria uma API real de clima como OpenWeatherMap ao invés de dados simulados?" +> - "Como eu integraria uma API real de clima como OpenWeatherMap em vez de dados mock?" > - "O que faz uma boa descrição de ferramenta que ajuda a IA a usá-la corretamente?" -> - "Como lidar com erros de API e limites de requisição nas implementações de ferramentas?" +> - "Como eu trato erros de API e limites de taxa nas implementações das ferramentas?" ### Tomada de Decisão -Quando um usuário pergunta "Qual o clima em Seattle?", o modelo não escolhe uma ferramenta aleatoriamente. Ele compara a intenção do usuário contra cada descrição de ferramenta que possui, pontua cada uma por relevância e seleciona a melhor correspondência. Então gera uma chamada de função estruturada com os parâmetros certos — neste caso, definindo `location` como `"Seattle"`. +Quando um usuário pergunta "Como está o tempo em Seattle?", o modelo não escolhe uma ferramenta aleatoriamente. Ele compara a intenção do usuário com cada descrição de ferramenta que tem acesso, avalia a relevância de cada uma e seleciona a melhor. Depois gera uma chamada de função estruturada com os parâmetros corretos — neste caso, definindo `location` como `"Seattle"`. -Se nenhuma ferramenta corresponder ao pedido do usuário, o modelo recai para responder com seu próprio conhecimento. Se múltiplas ferramentas corresponderem, ele escolhe a mais específica. +Se nenhuma ferramenta corresponder ao pedido do usuário, o modelo tenta responder usando seu próprio conhecimento. Se várias ferramentas corresponderem, ele escolhe a mais específica. Como a IA Decide Qual Ferramenta Usar -*O modelo avalia todas as ferramentas disponíveis contra a intenção do usuário e seleciona a melhor correspondência — por isso escrever descrições claras e específicas para ferramentas importa.* +*O modelo avalia cada ferramenta disponível em relação à intenção do usuário e seleciona a melhor — por isso é importante escrever descrições de ferramentas claras e específicas.* ### Execução [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot injeta automaticamente a interface declarativa `@AiService` com todas as ferramentas registradas, e LangChain4j executa as chamadas de ferramentas automaticamente. Nos bastidores, uma chamada de ferramenta completa passa por seis etapas — desde a pergunta em linguagem natural do usuário até a resposta também em linguagem natural: +O Spring Boot injeta automaticamente a interface declarativa `@AiService` com todas as ferramentas registradas, e LangChain4j executa as chamadas às ferramentas automaticamente. Por trás disso, uma chamada completa passa por seis etapas — desde a pergunta em linguagem natural do usuário até a resposta na mesma linguagem: Fluxo de Chamada de Ferramentas -*O fluxo de ponta a ponta — o usuário faz uma pergunta, o modelo seleciona uma ferramenta, LangChain4j a executa e o modelo incorpora o resultado em uma resposta natural.* +*O fluxo completo — o usuário faz uma pergunta, o modelo seleciona uma ferramenta, LangChain4j a executa, e o modelo incorpora o resultado na resposta.* -Se você executou o [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) no Módulo 00, já viu esse padrão em ação — as ferramentas `Calculator` foram chamadas da mesma forma. O diagrama de sequência abaixo mostra exatamente o que aconteceu nos bastidores durante aquela demonstração: +Nos bastidores, `AiServices` executa o mesmo laço de chamada para qualquer ferramenta — aqui ilustrado com um simples `Calculator`. O diagrama de sequência abaixo mostra exatamente o que acontece nos bastidores: Diagrama de Sequência de Chamada de Ferramentas -*O ciclo de chamada de ferramentas do demo Quick Start — `AiServices` envia sua mensagem e esquemas de ferramentas ao LLM, o LLM responde com uma chamada de função como `add(42, 58)`, LangChain4j executa o método `Calculator` localmente e envia o resultado de volta para a resposta final.* +*O ciclo de chamada — `AiServices` envia sua mensagem e esquemas de ferramentas para o LLM, o LLM responde com uma chamada de função como `add(42, 58)`, LangChain4j executa o método `Calculator` localmente e fornece o resultado para a resposta final.* > **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) e pergunte: -> - "Como funciona o padrão ReAct e por que ele é eficaz para agentes de IA?" +> - "Como funciona o padrão ReAct e por que é eficaz para agentes de IA?" > - "Como o agente decide qual ferramenta usar e em que ordem?" -> - "O que acontece se uma execução de ferramenta falhar — como devo tratar erros de forma robusta?" +> - "O que acontece se a execução da ferramenta falhar — como tratar erros de forma robusta?" -### Geração de Respostas +### Geração de Resposta -O modelo recebe os dados do clima e os formata em uma resposta em linguagem natural para o usuário. +O modelo recebe os dados do clima e formata em uma resposta em linguagem natural para o usuário. -### Arquitetura: Injeção Automática do Spring Boot +### Arquitetura: Auto-Injeção do Spring Boot -Este módulo usa a integração do LangChain4j com Spring Boot por meio de interfaces declarativas `@AiService`. Na inicialização, o Spring Boot descobre cada `@Component` que contenha métodos anotados com `@Tool`, seu bean `ChatModel` e o `ChatMemoryProvider` — então os conecta todos numa única interface `Assistant` sem necessidade de código repetitivo. +Este módulo usa a integração do LangChain4j com Spring Boot via interfaces declarativas `@AiService`. Na inicialização, o Spring Boot descobre cada `@Component` que contém métodos `@Tool`, seu bean `ChatModel` e o `ChatMemoryProvider` — e conecta tudo em uma única interface `Assistant` sem código repetitivo. -Arquitetura de Injeção Automática do Spring Boot +Arquitetura de Auto-Injeção do Spring Boot -*A interface @AiService conecta o ChatModel, componentes de ferramenta e provedor de memória — o Spring Boot cuida de toda a injeção automaticamente.* +*A interface @AiService conecta o ChatModel, componentes de ferramentas e o provedor de memória — o Spring Boot cuida de toda injeção automaticamente.* -Aqui está o ciclo completo da requisição em um diagrama de sequência — desde o pedido HTTP através do controlador, serviço e proxy injetado, até a execução da ferramenta e retorno: +Aqui está o ciclo completo de uma requisição como diagrama de sequência — desde a requisição HTTP pelo controller, passando pelo serviço e proxy injetado automaticamente, até a execução da ferramenta e retorno: -Sequência de Chamada de Ferramenta no Spring Boot +Sequência de Chamada de Ferramentas com Spring Boot -*O ciclo completo da requisição no Spring Boot — o pedido HTTP flui pelo controlador e serviço para o proxy Assistant injetado automaticamente, que orquestra o LLM e chamadas de ferramentas sem intervenção.* +*Ciclo completo da requisição Spring Boot — a requisição HTTP passa pelo controller e serviço até o proxy do Assistant auto-injetado, que orquestra o LLM e chamadas de ferramentas automaticamente.* Principais benefícios dessa abordagem: -- **Injeção automática do Spring Boot** — ChatModel e ferramentas são injetados automaticamente -- **Padrão @MemoryId** — Gerenciamento automático de memória baseada em sessão -- **Instância única** — Assistant criado uma vez e reutilizado para melhor desempenho -- **Execução tipada** — Métodos Java chamados diretamente com conversão de tipos -- **Orquestração multi-turno** — Controla encadeamento de ferramentas automaticamente -- **Zero código repetitivo** — Sem chamadas manuais `AiServices.builder()` ou HashMap de memória +- **Auto-injeção do Spring Boot** — ChatModel e ferramentas são injetados automaticamente +- **Padrão @MemoryId** — Gerenciamento automático de memória por sessão +- **Instância única** — Assistant criado uma vez e reutilizado para melhor performance +- **Execução com segurança de tipos** — Métodos Java chamados diretamente com conversão de tipos +- **Orquestração multi-turno** — Lida com encadeamento de ferramentas automaticamente +- **Zero código repetitivo** — Sem chamadas manuais `AiServices.builder()` ou mapas de memória -Abordagens alternativas (manual `AiServices.builder()`) exigem mais código e não aproveitam os benefícios da integração com Spring Boot. +Abordagens alternativas (construção manual com `AiServices.builder()`) requerem mais código e perdem os benefícios da integração com Spring Boot. ## Encadeamento de Ferramentas -**Encadeamento de Ferramentas** — O verdadeiro poder dos agentes baseados em ferramentas aparece quando uma única pergunta requer múltiplas ferramentas. Pergunte "Qual o clima em Seattle em Fahrenheit?" e o agente encadeia automaticamente duas ferramentas: primeiro chama `getCurrentWeather` para obter a temperatura em Celsius, depois passa esse valor para `celsiusToFahrenheit` para conversão — tudo em um único turno de conversa. +**Encadeamento de Ferramentas** — O verdadeiro poder dos agentes baseados em ferramentas aparece quando uma única pergunta exige múltiplas ferramentas. Pergunte "Como está o tempo em Seattle em Fahrenheit?" e o agente encadeia automaticamente duas ferramentas: primeiro chama `getCurrentWeather` para obter a temperatura em Celsius, depois passa esse valor para `celsiusToFahrenheit` para conversão — tudo em um único turno de conversa. Exemplo de Encadeamento de Ferramentas -*Encadeamento de ferramentas em ação — o agente chama getCurrentWeather primeiro, depois direciona o resultado em Celsius para celsiusToFahrenheit e entrega uma resposta combinada.* +*Encadeamento de ferramentas em ação — o agente chama getCurrentWeather primeiro, depois passa o resultado em Celsius para celsiusToFahrenheit, entregando uma resposta combinada.* -**Falhas Elegantes** — Peça o clima numa cidade que não está nos dados simulados. A ferramenta retorna uma mensagem de erro, e a IA explica que não pode ajudar em vez de travar. Ferramentas falham de forma segura. O diagrama abaixo contrasta as duas abordagens — com tratamento adequado de erros, o agente captura a exceção e responde com ajuda, enquanto sem isso a aplicação inteira cai: +**Falhas Graciosas** — Peça o clima de uma cidade que não está nos dados mock. A ferramenta retorna uma mensagem de erro, e a IA explica que não pode ajudar ao invés de travar. As ferramentas falham de forma segura. O diagrama abaixo contrasta as duas abordagens — com tratamento adequado de erros, o agente captura a exceção e responde com ajuda, enquanto sem isso a aplicação inteira trava: Fluxo de Tratamento de Erros -*Quando uma ferramenta falha, o agente captura o erro e responde com uma explicação útil em vez de travar.* +*Quando uma ferramenta falha, o agente captura o erro e responde com uma explicação útil ao invés de travar.* -Isso acontece em um único turno de conversa. O agente orquestra múltiplas chamadas de ferramentas autonomamente. +Isso acontece em um único turno da conversa. O agente orquestra múltiplas chamadas de ferramentas autonomamente. ## Executar a Aplicação **Verifique a implantação:** -Certifique-se de que o arquivo `.env` existe no diretório raiz com credenciais Azure (criado durante o Módulo 01). Execute isto a partir do diretório do módulo (`04-tools/`): +Garanta que o arquivo `.env` exista na raiz com as credenciais Azure (criado durante o Módulo 01). Execute a partir do diretório do módulo (`04-tools/`): **Bash:** ```bash @@ -207,24 +207,24 @@ Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Inicie a aplicação:** -> **Nota:** Se você já iniciou todas as aplicações usando `./start-all.sh` do diretório raiz (conforme descrito no Módulo 01), este módulo já está rodando na porta 8084. Você pode pular os comandos de início abaixo e ir direto para http://localhost:8084. +> **Nota:** Se você já iniciou todas as aplicações usando `./start-all.sh` na raiz (como descrito no Módulo 01), este módulo já está rodando na porta 8084. Você pode pular os comandos de inicialização abaixo e acessar diretamente http://localhost:8084. **Opção 1: Usando o Spring Boot Dashboard (Recomendado para usuários VS Code)** -O contêiner de desenvolvimento inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerenciar todas as aplicações Spring Boot. Você pode encontrá-la na Barra de Atividades do lado esquerdo do VS Code (identifique pelo ícone do Spring Boot). +O container de desenvolvimento inclui a extensão Spring Boot Dashboard, que oferece uma interface visual para gerenciar todas as aplicações Spring Boot. Você pode encontrá-la na Barra de Atividades à esquerda do VS Code (procure o ícone do Spring Boot). -No Spring Boot Dashboard, você pode: +Pelo Spring Boot Dashboard, você pode: - Ver todas as aplicações Spring Boot disponíveis no workspace - Iniciar/parar aplicações com um clique -- Visualizar logs da aplicação em tempo real -- Monitorar status da aplicação -Simplesmente clique no botão de play ao lado de "tools" para iniciar este módulo, ou inicie todos os módulos de uma vez. +- Visualizar os logs da aplicação em tempo real +- Monitorar o status das aplicações -Aqui está como o Spring Boot Dashboard aparece no VS Code: +Basta clicar no botão de play ao lado de "tools" para iniciar este módulo, ou iniciar todos os módulos de uma vez. -Spring Boot Dashboard +Veja como o Spring Boot Dashboard aparece no VS Code: +Painel Spring Boot -*O Spring Boot Dashboard no VS Code — iniciar, parar e monitorar todos os módulos em um só lugar* +*O Painel Spring Boot no VS Code — iniciar, parar e monitorar todos os módulos em um só lugar* **Opção 2: Usando scripts shell** @@ -238,7 +238,7 @@ cd .. # Do diretório raiz **PowerShell:** ```powershell -cd .. # A partir do diretório root +cd .. # Do diretório raiz .\start-all.ps1 ``` @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Ambos os scripts carregam automaticamente variáveis de ambiente do arquivo `.env` na raiz e irão construir os JARs caso eles não existam. +Ambos os scripts carregam automaticamente as variáveis de ambiente do arquivo `.env` raiz e irão compilar os JARs caso eles não existam. -> **Nota:** Se preferir construir todos os módulos manualmente antes de iniciar: +> **Nota:** Se preferir compilar todos os módulos manualmente antes de iniciar: > > **Bash:** > ```bash @@ -292,84 +292,84 @@ cd ..; .\stop-all.ps1 # Todos os módulos ## Usando a Aplicação -A aplicação fornece uma interface web onde você pode interagir com um agente de IA que tem acesso a ferramentas de previsão do tempo e conversão de temperatura. Veja como a interface é — inclui exemplos rápidos e um painel de chat para enviar solicitações: +A aplicação oferece uma interface web onde você pode interagir com um agente de IA que tem acesso a ferramentas de clima e conversão de temperatura. Veja como é a interface — inclui exemplos para início rápido e um painel de chat para enviar solicitações: -AI Agent Tools Interface +Interface de Ferramentas do Agente de IA -*Interface da Ferramenta do Agente de IA — exemplos rápidos e interface de chat para interagir com as ferramentas* +*Interface das Ferramentas do Agente de IA - exemplos rápidos e interface de chat para interagir com as ferramentas* ### Experimente o Uso Simples de Ferramentas -Comece com uma solicitação simples: "Converta 100 graus Fahrenheit para Celsius". O agente reconhece que precisa da ferramenta de conversão de temperatura, a chama com os parâmetros certos e retorna o resultado. Note como isso parece natural – você não especificou qual ferramenta usar nem como chamá-la. +Comece com um pedido simples: "Converter 100 graus Fahrenheit para Celsius". O agente reconhece que precisa da ferramenta de conversão de temperatura, a chama com os parâmetros corretos e retorna o resultado. Note como isso soa natural — você não especificou qual ferramenta usar nem como chamá-la. -### Teste o Encadeamento de Ferramentas +### Teste a Encadeação de Ferramentas -Agora tente algo mais complexo: "Qual é o tempo em Seattle e converta para Fahrenheit?" Observe o agente resolver isso em etapas. Primeiro ele obtém o tempo (que retorna em Celsius), reconhece que precisa converter para Fahrenheit, chama a ferramenta de conversão, e combina ambos os resultados em uma resposta. +Agora tente algo mais complexo: "Qual é o tempo em Seattle e converta para Fahrenheit?" Veja o agente trabalhar isso em etapas. Primeiro ele obtém o clima (que retorna em Celsius), reconhece que precisa converter para Fahrenheit, chama a ferramenta de conversão, e combina os dois resultados em uma resposta única. ### Veja o Fluxo da Conversa -A interface de chat mantém o histórico da conversa, permitindo interações em múltiplas etapas. Você pode ver todas as perguntas e respostas anteriores, facilitando acompanhar a conversa e entender como o agente constrói contexto através de várias trocas. +A interface de chat mantém o histórico da conversa, permitindo interações com múltiplas trocas. Você pode ver todas as consultas e respostas anteriores, facilitando acompanhar a conversa e entender como o agente constrói o contexto ao longo de várias interações. -Conversation with Multiple Tool Calls +Conversa com múltiplas chamadas de ferramenta -*Conversa de múltiplas etapas mostrando conversões simples, buscas de tempo e encadeamento de ferramentas* +*Conversa multi-turno mostrando conversões simples, consultas de clima e encadeamento de ferramentas* -### Experimente Diferentes Solicitações +### Experimente diferentes solicitações -Experimente várias combinações: -- Consultas do tempo: "Qual é o tempo em Tóquio?" +Teste várias combinações: +- Consultas de clima: "Qual o clima em Tóquio?" - Conversões de temperatura: "Quanto é 25°C em Kelvin?" -- Consultas combinadas: "Verifique o tempo em Paris e me diga se está acima de 20°C" +- Consultas combinadas: "Verifique o clima em Paris e me diga se está acima de 20°C" -Note como o agente interpreta linguagem natural e a mapeia para chamadas apropriadas às ferramentas. +Note como o agente interpreta a linguagem natural e mapeia para chamadas adequadas às ferramentas. ## Conceitos-Chave -### Padrão ReAct (Raciocinar e Agir) +### Padrão ReAct (Raciocínio e Ação) -O agente alterna entre raciocinar (decidir o que fazer) e agir (usar ferramentas). Este padrão permite a resolução autônoma de problemas ao invés de apenas responder instruções. +O agente alterna entre raciocinar (decidir o que fazer) e agir (usar ferramentas). Esse padrão possibilita solução autônoma de problemas, em vez de apenas responder às instruções. ### Descrições de Ferramentas Importam -A qualidade das descrições das suas ferramentas afeta diretamente quão bem o agente as utiliza. Descrições claras e específicas ajudam o modelo a entender quando e como chamar cada ferramenta. +A qualidade das descrições das suas ferramentas afeta diretamente a forma como o agente as utiliza. Descrições claras e específicas ajudam o modelo a entender quando e como chamar cada ferramenta. ### Gerenciamento de Sessão -A anotação `@MemoryId` permite o gerenciamento automático de memória baseada em sessão. Cada ID de sessão recebe sua própria instância de `ChatMemory` gerenciada pelo bean `ChatMemoryProvider`, para que vários usuários possam interagir com o agente simultaneamente sem misturar as conversas. O diagrama a seguir mostra como múltiplos usuários são roteados para memórias isoladas baseadas em seus IDs de sessão: +A anotação `@MemoryId` permite gerenciamento automático de memória baseado em sessão. Cada ID de sessão recebe sua própria instância `ChatMemory` gerenciada pelo bean `ChatMemoryProvider`, assim múltiplos usuários podem interagir com o agente simultaneamente sem misturar as conversas. O diagrama abaixo mostra como múltiplos usuários são roteados para memórias isoladas baseadas em seus IDs de sessão: -Session Management with @MemoryId +Gerenciamento de sessão com @MemoryId -*Cada ID de sessão é mapeado para um histórico de conversa isolado — usuários nunca veem as mensagens uns dos outros.* +*Cada ID de sessão mapeia para um histórico de conversa isolado — usuários nunca veem as mensagens uns dos outros.* ### Tratamento de Erros -Ferramentas podem falhar — APIs podem expirar, parâmetros podem ser inválidos, serviços externos podem cair. Agentes de produção precisam de tratamento de erros para que o modelo possa explicar problemas ou tentar alternativas ao invés de travar a aplicação toda. Quando uma ferramenta lança uma exceção, LangChain4j a captura e retorna a mensagem de erro para o modelo, que então pode explicar o problema em linguagem natural. +Ferramentas podem falhar — APIs com timeout, parâmetros inválidos, serviços externos indisponíveis. Agentes para produção precisam de tratamento de erros para que o modelo possa explicar problemas ou tentar alternativas em vez de travar a aplicação inteira. Quando uma ferramenta lança uma exceção, LangChain4j a captura e envia a mensagem de erro de volta ao modelo, que pode então explicar o problema em linguagem natural. ## Ferramentas Disponíveis -O diagrama abaixo mostra o amplo ecossistema de ferramentas que você pode construir. Este módulo demonstra ferramentas de previsão do tempo e temperatura, mas o mesmo padrão `@Tool` funciona para qualquer método Java — desde consultas a banco de dados até processamento de pagamento. +O diagrama abaixo mostra o amplo ecossistema de ferramentas que você pode construir. Este módulo demonstra ferramentas de clima e temperatura, mas o mesmo padrão `@Tool` funciona para qualquer método Java — desde consultas a banco de dados até processamento de pagamentos. -Tool Ecosystem +Ecossistema de Ferramentas -*Qualquer método Java anotado com @Tool torna-se disponível para a IA — o padrão se estende a bancos de dados, APIs, e-mail, operações de arquivo, e mais.* +*Qualquer método Java anotado com @Tool fica disponível para a IA — o padrão se estende a bancos de dados, APIs, email, operações de arquivos e muito mais.* ## Quando Usar Agentes Baseados em Ferramentas -Nem toda solicitação precisa de ferramentas. A decisão depende de a IA precisar interagir com sistemas externos ou poder responder com seu próprio conhecimento. O guia a seguir resume quando as ferramentas agregam valor e quando não são necessárias: +Nem toda solicitação precisa de ferramentas. A decisão depende se a IA precisa interagir com sistemas externos ou pode responder com seu próprio conhecimento. O guia a seguir resume quando as ferramentas agregam valor e quando não são necessárias: -When to Use Tools +Quando Usar Ferramentas -*Um guia rápido — ferramentas são para dados em tempo real, cálculos e ações; conhecimento geral e tarefas criativas não precisam delas.* +*Um guia rápido para decisão — ferramentas são para dados em tempo real, cálculos e ações; conhecimentos gerais e tarefas criativas não precisam delas.* ## Ferramentas vs RAG -Os módulos 03 e 04 ampliam o que a IA pode fazer, mas de formas fundamentalmente diferentes. RAG oferece ao modelo acesso ao **conhecimento** por meio da recuperação de documentos. Ferramentas dão ao modelo a capacidade de realizar **ações** por meio de chamadas de funções. O diagrama abaixo compara essas duas abordagens lado a lado — do funcionamento de cada fluxo até as compensações entre eles: +Os módulos 03 e 04 estendem o que a IA pode fazer, mas de formas fundamentalmente diferentes. RAG dá ao modelo acesso a **conhecimento** recuperando documentos. Ferramentas dão ao modelo a capacidade de tomar **ações** chamando funções. O diagrama abaixo compara as duas abordagens lado a lado — desde como cada fluxo opera até as compensações entre eles: -Tools vs RAG Comparison +Comparação Ferramentas vs RAG -*RAG recupera informação de documentos estáticos — Ferramentas executam ações e buscam dados dinâmicos e em tempo real. Muitos sistemas de produção combinam ambos.* +*RAG recupera informações de documentos estáticos — Ferramentas executam ações e buscam dados dinâmicos em tempo real. Muitos sistemas de produção combinam ambos.* -Na prática, muitos sistemas de produção combinam ambas as abordagens: RAG para fundamentar respostas na sua documentação, e Ferramentas para buscar dados ao vivo ou executar operações. +Na prática, muitos sistemas de produção combinam ambas as abordagens: RAG para fundamentar respostas na sua documentação e Ferramentas para buscar dados ao vivo ou executar operações. ## Próximos Passos @@ -382,6 +382,6 @@ Na prática, muitos sistemas de produção combinam ambas as abordagens: RAG par --- -**Aviso Legal**: -Este documento foi traduzido usando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir precisão, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte oficial. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. +**Aviso Legal**: +Este documento foi traduzido usando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. \ No newline at end of file diff --git a/translations/pt-BR/README.md b/translations/pt-BR/README.md index cf1dbfc7a..059c696c4 100644 --- a/translations/pt-BR/README.md +++ b/translations/pt-BR/README.md @@ -2,18 +2,18 @@ # LangChain4j para Iniciantes -Um curso para construir aplicações de IA com LangChain4j e Azure OpenAI GPT-5.2, desde chat básico até agentes de IA. +Um curso para construir aplicações de IA com LangChain4j e Azure OpenAI GPT-5.2, do chat básico a agentes de IA. ### 🌐 Suporte Multilíngue #### Suportado via GitHub Action (Automatizado e Sempre Atualizado) -[Árabe](../ar/README.md) | [Bengali](../bn/README.md) | [Búlgaro](../bg/README.md) | [Birmanês (Myanmar)](../my/README.md) | [Chinês (Simplificado)](../zh-CN/README.md) | [Chinês (Tradicional, Hong Kong)](../zh-HK/README.md) | [Chinês (Tradicional, Macau)](../zh-MO/README.md) | [Chinês (Tradicional, Taiwan)](../zh-TW/README.md) | [Croata](../hr/README.md) | [Tcheco](../cs/README.md) | [Dinamarquês](../da/README.md) | [Holandês](../nl/README.md) | [Estoniano](../et/README.md) | [Finlandês](../fi/README.md) | [Francês](../fr/README.md) | [Alemão](../de/README.md) | [Grego](../el/README.md) | [Hebraico](../he/README.md) | [Hindi](../hi/README.md) | [Húngaro](../hu/README.md) | [Indonésio](../id/README.md) | [Italiano](../it/README.md) | [Japonês](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Coreano](../ko/README.md) | [Lituano](../lt/README.md) | [Malaio](../ms/README.md) | [Malaiala](../ml/README.md) | [Marata](../mr/README.md) | [Nepali](../ne/README.md) | [Pidgin Nigeriano](../pcm/README.md) | [Norueguês](../no/README.md) | [Persa (Farsi)](../fa/README.md) | [Polonês](../pl/README.md) | [Português (Brasil)](./README.md) | [Português (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romeno](../ro/README.md) | [Russo](../ru/README.md) | [Sérvio (Cirílico)](../sr/README.md) | [Eslovaco](../sk/README.md) | [Esloveno](../sl/README.md) | [Espanhol](../es/README.md) | [Swahili](../sw/README.md) | [Sueco](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tâmil](../ta/README.md) | [Telugu](../te/README.md) | [Tailandês](../th/README.md) | [Turco](../tr/README.md) | [Ucraniano](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamita](../vi/README.md) +[Árabe](../ar/README.md) | [Bengali](../bn/README.md) | [Búlgaro](../bg/README.md) | [Birmanês (Myanmar)](../my/README.md) | [Chinês (Simplificado)](../zh-CN/README.md) | [Chinês (Tradicional, Hong Kong)](../zh-HK/README.md) | [Chinês (Tradicional, Macau)](../zh-MO/README.md) | [Chinês (Tradicional, Taiwan)](../zh-TW/README.md) | [Croata](../hr/README.md) | [Checo](../cs/README.md) | [Dinamarquês](../da/README.md) | [Holandês](../nl/README.md) | [Estoniano](../et/README.md) | [Finlandês](../fi/README.md) | [Francês](../fr/README.md) | [Alemão](../de/README.md) | [Grego](../el/README.md) | [Hebraico](../he/README.md) | [Hindi](../hi/README.md) | [Húngaro](../hu/README.md) | [Indonésio](../id/README.md) | [Italiano](../it/README.md) | [Japonês](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Coreano](../ko/README.md) | [Lituano](../lt/README.md) | [Malaio](../ms/README.md) | [Malaiala](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Pidgin Nigeriano](../pcm/README.md) | [Norueguês](../no/README.md) | [Persa (Farsi)](../fa/README.md) | [Polonês](../pl/README.md) | [Português (Brasil)](./README.md) | [Português (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romeno](../ro/README.md) | [Russo](../ru/README.md) | [Sérvio (Cirílico)](../sr/README.md) | [Eslovaco](../sk/README.md) | [Esloveno](../sl/README.md) | [Espanhol](../es/README.md) | [Suaíli](../sw/README.md) | [Sueco](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tâmil](../ta/README.md) | [Telugu](../te/README.md) | [Tailandês](../th/README.md) | [Turco](../tr/README.md) | [Ucraniano](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamita](../vi/README.md) > **Prefere Clonar Localmente?** > -> Este repositório inclui mais de 50 traduções de idiomas, o que aumenta significativamente o tamanho do download. Para clonar sem traduções, use checkout esparso: +> Este repositório inclui traduções para mais de 50 idiomas, o que aumenta significativamente o tamanho do download. Para clonar sem traduções, use checkout esparso: > > **Bash / macOS / Linux:** > ```bash @@ -29,21 +29,20 @@ Um curso para construir aplicações de IA com LangChain4j e Azure OpenAI GPT-5. > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Isso fornece tudo o que você precisa para completar o curso com um download muito mais rápido. +> Isso fornece tudo que você precisa para completar o curso com um download muito mais rápido. ## Sumário -1. [Início Rápido](00-quick-start/README.md) - Comece com LangChain4j -2. [Introdução](01-introduction/README.md) - Aprenda os fundamentos do LangChain4j -3. [Engenharia de Prompt](02-prompt-engineering/README.md) - Domine o design eficaz de prompts -4. [RAG (Geração Aumentada por Recuperação)](03-rag/README.md) - Construa sistemas inteligentes baseados em conhecimento -5. [Ferramentas](04-tools/README.md) - Integre ferramentas externas e assistentes simples -6. [MCP (Protocolo de Contexto do Modelo)](05-mcp/README.md) - Trabalhe com o Protocolo de Contexto do Modelo (MCP) e módulos Agentic +1. [Introdução](01-introduction/README.md) - Aprenda os fundamentos do LangChain4j +2. [Engenharia de Prompt](02-prompt-engineering/README.md) - Domine o design eficaz de prompts +3. [RAG (Geração Aumentada por Recuperação)](03-rag/README.md) - Construa sistemas inteligentes baseados em conhecimento +4. [Ferramentas](04-tools/README.md) - Integre ferramentas externas e assistentes simples +5. [MCP (Protocolo do Contexto do Modelo)](05-mcp/README.md) - Trabalhe com o Protocolo do Contexto do Modelo (MCP) e módulos Agentic -### Vídeos Explicativos +### Vídeos Orientativos -Cada módulo tem uma sessão ao vivo acompanhante onde explicamos os conceitos e o código passo a passo. +Cada módulo tem uma sessão ao vivo acompanhante onde caminhamos pelos conceitos e código passo a passo. | Módulo | Vídeo | |--------|-------| @@ -54,34 +53,34 @@ Cada módulo tem uma sessão ao vivo acompanhante onde explicamos os conceitos e --- -## Caminho de Aprendizagem +## Caminho de Aprendizado -**Novo no LangChain4j?** Confira o [Glossário](docs/GLOSSARY.md) para definições de termos e conceitos chave. +**Novo no LangChain4j?** Confira o [Glossário](docs/GLOSSARY.md) para definições de termos e conceitos importantes. > **Início Rápido** 1. Faça fork deste repositório para sua conta GitHub 2. Clique em **Code** → aba **Codespaces** → **...** → **Novo com opções...** -3. Use as opções padrão – isso selecionará o container de Desenvolvimento criado para este curso +3. Use as configurações padrão – isso selecionará o container de Desenvolvimento criado para este curso 4. Clique em **Criar codespace** -5. Aguarde 5-10 minutos para o ambiente estar pronto -6. Vá direto para [Início Rápido](./00-quick-start/README.md) para começar! +5. Aguarde de 5 a 10 minutos para o ambiente ficar pronto +6. Vá diretamente para [Introdução](./01-introduction/README.md) para começar! -Após completar os módulos, explore o [Guia de Testes](docs/TESTING.md) para ver os conceitos de teste do LangChain4j na prática. +Após completar os módulos, explore o [Guia de Testes](docs/TESTING.md) para ver conceitos de teste do LangChain4j em ação. -> **Nota:** Este treinamento usa tanto Modelos GitHub quanto Azure OpenAI. O módulo [Início Rápido](00-quick-start/README.md) usa Modelos GitHub (não requer assinatura Azure), enquanto os módulos 1-5 usam Azure OpenAI. Comece com uma [conta Azure GRATUITA](https://aka.ms/azure-free-account) se ainda não tiver uma. +> **Observação:** Este treinamento usa Azure OpenAI. Comece com uma [conta Azure GRATIS](https://aka.ms/azure-free-account) se você ainda não tiver uma. -## Aprendendo com o GitHub Copilot +## Aprendendo com GitHub Copilot -Para começar a programar rapidamente, abra este projeto em um GitHub Codespace ou seu IDE local com o devcontainer fornecido. O devcontainer usado neste curso vem pré-configurado com o GitHub Copilot para programação em par com IA. +Para começar a programar rapidamente, abra este projeto em um GitHub Codespace ou em seu IDE local com o devcontainer fornecido. O devcontainer usado neste curso já vem pré-configurado com GitHub Copilot para programação em par com IA. Cada exemplo de código inclui perguntas sugeridas que você pode fazer ao GitHub Copilot para aprofundar seu entendimento. Procure os prompts 💡/🤖 em: - **Cabeçalhos de arquivos Java** - Perguntas específicas para cada exemplo -- **READMEs dos módulos** - Prompts de exploração após exemplos de código +- **READMEs dos módulos** - Sugestões de exploração após exemplos de código -**Como usar:** Abra qualquer arquivo de código e faça as perguntas sugeridas ao Copilot. Ele tem contexto completo do código e pode explicar, estender e sugerir alternativas. +**Como usar:** Abra qualquer arquivo de código e faça as perguntas sugeridas ao Copilot. Ele tem o contexto completo do código e pode explicar, estender e sugerir alternativas. Quer aprender mais? Confira [Copilot para Programação em Par com IA](https://aka.ms/GitHubCopilotAI). @@ -111,11 +110,12 @@ Quer aprender mais? Confira [Copilot para Programação em Par com IA](https://a --- -### Aprendizagem Básica +### Aprendizado Central [![ML para Iniciantes](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Ciência de Dados para Iniciantes](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![IA para Iniciantes](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Cibersegurança para Iniciantes](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -130,11 +130,11 @@ Quer aprender mais? Confira [Copilot para Programação em Par com IA](https://a ## Obtendo Ajuda -Se você ficar preso ou tiver alguma dúvida sobre como criar aplicativos de IA, participe: +Se você ficar preso ou tiver alguma dúvida sobre como construir aplicativos de IA, entre em: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Se você tiver feedback sobre o produto ou erros durante a criação, visite: +Se você tiver feedback sobre o produto ou erros durante a construção, visite: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) @@ -145,6 +145,6 @@ Licença MIT - Veja o arquivo [LICENSE](../../LICENSE) para detalhes. --- -**Aviso Legal**: -Este documento foi traduzido usando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, por favor, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomendamos a tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. +**Aviso Legal**: +Este documento foi traduzido usando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. \ No newline at end of file diff --git a/translations/pt-BR/docs/GLOSSARY.md b/translations/pt-BR/docs/GLOSSARY.md index 52aa17b34..9b1f2a5b4 100644 --- a/translations/pt-BR/docs/GLOSSARY.md +++ b/translations/pt-BR/docs/GLOSSARY.md @@ -2,17 +2,17 @@ ## Índice -- [Conceitos Básicos](../../../docs) -- [Componentes LangChain4j](../../../docs) -- [Conceitos de AI/ML](../../../docs) -- [Guardrails](../../../docs) -- [Engenharia de Prompt](../../../docs) -- [RAG (Geração com Recuperação)](../../../docs) -- [Agentes e Ferramentas](../../../docs) -- [Módulo Agentic](../../../docs) -- [Protocolo de Contexto de Modelo (MCP)](../../../docs) -- [Serviços Azure](../../../docs) -- [Teste e Desenvolvimento](../../../docs) +- [Conceitos Básicos](#conceitos-básicos) +- [Componentes do LangChain4j](#componentes-do-langchain4j) +- [Conceitos de IA/ML](#conceitos-de-iaml) +- [Guardrails](#guardrails) +- [Engenharia de Prompt](#prompt-engineering---module-02) +- [RAG (Geração com Recuperação)](#rag-retrieval-augmented-generation---module-03) +- [Agentes e Ferramentas](#agents-and-tools---module-04) +- [Módulo Agentic](#agentic-module---module-05) +- [Protocolo de Contexto de Modelo (MCP)](#model-context-protocol-mcp---module-05) +- [Serviços Azure](#azure-services---module-01) +- [Teste e Desenvolvimento](#testing-and-development---testing-guide) Referência rápida para termos e conceitos usados ao longo do curso. @@ -20,61 +20,61 @@ Referência rápida para termos e conceitos usados ao longo do curso. **Agente de IA** - Sistema que usa IA para raciocinar e agir de forma autônoma. [Módulo 04](../04-tools/README.md) -**Cadeia** - Sequência de operações onde a saída alimenta a próxima etapa. +**Chain** - Sequência de operações onde a saída alimenta a próxima etapa. -**Fragmentação** - Dividir documentos em partes menores. Típico: 300-500 tokens com sobreposição. [Módulo 03](../03-rag/README.md) +**Chunking** - Dividir documentos em pedaços menores. Típico: 300-500 tokens com sobreposição. [Módulo 03](../03-rag/README.md) **Janela de Contexto** - Máximo de tokens que um modelo pode processar. GPT-5.2: 400K tokens (até 272K entrada, 128K saída). -**Embeddings** - Vetores numéricos que representam o significado do texto. [Módulo 03](../03-rag/README.md) +**Embeddings** - Vetores numéricos representando o significado do texto. [Módulo 03](../03-rag/README.md) -**Chamada de Função** - Modelo gera requisições estruturadas para chamar funções externas. [Módulo 04](../04-tools/README.md) +**Chamada de Função** - O modelo gera solicitações estruturadas para chamar funções externas. [Módulo 04](../04-tools/README.md) **Alucinação** - Quando modelos geram informações incorretas mas plausíveis. -**Prompt** - Entrada de texto para um modelo de linguagem. [Módulo 02](../02-prompt-engineering/README.md) +**Prompt** - Texto de entrada para um modelo de linguagem. [Módulo 02](../02-prompt-engineering/README.md) -**Busca Semântica** - Busca por significado usando embeddings, não por palavras-chave. [Módulo 03](../03-rag/README.md) +**Busca Semântica** - Busca por significado usando embeddings, não palavras-chave. [Módulo 03](../03-rag/README.md) -**Sem Estado vs Com Estado** - Sem estado: sem memória. Com estado: mantém histórico da conversa. [Módulo 01](../01-introduction/README.md) +**Com Estado vs Sem Estado** - Sem estado: sem memória. Com estado: mantém histórico de conversação. [Módulo 01](../01-introduction/README.md) **Tokens** - Unidades básicas de texto que modelos processam. Afeta custos e limites. [Módulo 01](../01-introduction/README.md) -**Encadeamento de Ferramentas** - Execução sequencial de ferramentas onde a saída informa a próxima chamada. [Módulo 04](../04-tools/README.md) +**Encadeamento de Ferramentas** - Execução sequencial de ferramentas onde saída informa a próxima chamada. [Módulo 04](../04-tools/README.md) -## Componentes LangChain4j +## Componentes do LangChain4j -**AiServices** - Cria interfaces de serviço de IA com tipagem segura. +**AiServices** - Cria interfaces de serviços de IA com tipagem segura. **OpenAiOfficialChatModel** - Cliente unificado para modelos OpenAI e Azure OpenAI. **OpenAiOfficialEmbeddingModel** - Cria embeddings usando cliente oficial OpenAI (suporta OpenAI e Azure OpenAI). -**ChatModel** - Interface central para modelos de linguagem. +**ChatModel** - Interface principal para modelos de linguagem. -**ChatMemory** - Mantém histórico da conversa. +**ChatMemory** - Mantém o histórico de conversação. -**ContentRetriever** - Encontra fragmentos de documentos relevantes para RAG. +**ContentRetriever** - Encontra pedaços relevantes de documentos para RAG. -**DocumentSplitter** - Divide documentos em fragmentos. +**DocumentSplitter** - Divide documentos em pedaços. **EmbeddingModel** - Converte texto em vetores numéricos. **EmbeddingStore** - Armazena e recupera embeddings. -**MessageWindowChatMemory** - Mantém janela deslizante das mensagens recentes. +**MessageWindowChatMemory** - Mantém uma janela deslizante das mensagens recentes. -**PromptTemplate** - Cria prompts reutilizáveis com espaços reservados `{{variable}}`. +**PromptTemplate** - Cria prompts reutilizáveis com placeholders `{{variable}}`. -**TextSegment** - Fragmento de texto com metadados. Usado em RAG. +**TextSegment** - Pedaço de texto com metadados. Usado no RAG. -**ToolExecutionRequest** - Representa requisição de execução de ferramenta. +**ToolExecutionRequest** - Representa uma solicitação de execução de ferramenta. -**UserMessage / AiMessage / SystemMessage** - Tipos de mensagens na conversa. +**UserMessage / AiMessage / SystemMessage** - Tipos de mensagens na conversação. -## Conceitos de AI/ML +## Conceitos de IA/ML -**Few-Shot Learning** - Fornecer exemplos nos prompts. [Módulo 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Fornecer exemplos em prompts. [Módulo 02](../02-prompt-engineering/README.md) **Modelo de Linguagem Grande (LLM)** - Modelos de IA treinados com grandes volumes de texto. @@ -82,67 +82,67 @@ Referência rápida para termos e conceitos usados ao longo do curso. **Temperatura** - Controla a aleatoriedade da saída. Baixa=determinístico, alta=criativo. -**Banco de Dados Vetorial** - Banco especializado em embeddings. [Módulo 03](../03-rag/README.md) +**Banco de Dados Vetorial** - Banco especializado para embeddings. [Módulo 03](../03-rag/README.md) **Zero-Shot Learning** - Realizar tarefas sem exemplos. [Módulo 02](../02-prompt-engineering/README.md) -## Guardrails - [Módulo 00](../00-quick-start/README.md) +## Guardrails -**Defesa em Profundidade** - Abordagem de segurança multicamadas que combina guardrails no nível da aplicação com filtros de segurança do provedor. +**Defesa em Profundidade** - Abordagem de segurança em múltiplas camadas combinando guardrails no nível da aplicação com filtros de segurança do provedor. **Bloqueio Rígido** - Provedor retorna erro HTTP 400 para violações graves de conteúdo. -**InputGuardrail** - Interface LangChain4j para validar entrada do usuário antes de chegar ao LLM. Economiza custo e latência bloqueando prompts nocivos cedo. +**InputGuardrail** - Interface LangChain4j para validar entrada do usuário antes de chegar ao LLM. Economiza custo e latência bloqueando prompts prejudiciais antecipadamente. -**InputGuardrailResult** - Tipo de retorno para validação guardrail: `success()` ou `fatal("razão")`. +**InputGuardrailResult** - Tipo de retorno para validação de guardrails: `success()` ou `fatal("reason")`. -**OutputGuardrail** - Interface para validar respostas de IA antes de retornar ao usuário. +**OutputGuardrail** - Interface para validar respostas da IA antes de retorná-las aos usuários. -**Filtros de Segurança do Provedor** - Filtros de conteúdo incorporados dos provedores de IA (ex.: GitHub Models) que detectam violações na API. +**Filtros de Segurança do Provedor** - Filtros embutidos de conteúdo dos provedores de IA (ex: Azure OpenAI) que detectam violações na camada da API. -**Recusa Suave** - Modelo educadamente se recusa a responder sem gerar erro. +**Recusa Suave** - Modelo recusa educadamente responder sem retornar erro. ## Engenharia de Prompt - [Módulo 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Raciocínio passo a passo para melhor precisão. +**Chain-of-Thought** - Raciocínio passo a passo para maior precisão. -**Saída Confinada** - Aplicar formato ou estrutura específicos. +**Saída Constrainada** - Imposição de formato ou estrutura específicos. -**Alta Vontade** - Padrão GPT-5.2 para raciocínio aprofundado. +**Alta Disposição** - Padrão GPT-5.2 para raciocínio aprofundado. -**Baixa Vontade** - Padrão GPT-5.2 para respostas rápidas. +**Baixa Disposição** - Padrão GPT-5.2 para respostas rápidas. -**Conversação Multi-Turno** - Manter contexto entre trocas. +**Conversa Multi-Turn** - Manter contexto entre trocas. -**Prompt por Papel** - Definir persona do modelo por mensagens do sistema. +**Prompting Baseado em Papel** - Configurar persona do modelo via mensagens do sistema. -**Autorreflexão** - Modelo avalia e melhora sua saída. +**Autorreflexão** - Modelo avalia e melhora sua própria saída. -**Análise Estruturada** - Estrutura fixa de avaliação. +**Análise Estruturada** - Framework fixo de avaliação. **Padrão de Execução de Tarefa** - Planejar → Executar → Resumir. ## RAG (Geração com Recuperação) - [Módulo 03](../03-rag/README.md) -**Pipeline de Processamento de Documento** - Carregar → fragmentar → embedar → armazenar. +**Pipeline de Processamento de Documento** - Carregar → chunk → embed → armazenar. **Armazenamento de Embeddings em Memória** - Armazenamento não persistente para testes. **RAG** - Combina recuperação com geração para fundamentar respostas. -**Pontuação de Similaridade** - Medida (0-1) de similaridade semântica. +**Score de Similaridade** - Medida (0-1) de similaridade semântica. -**Referência de Fonte** - Metadados sobre o conteúdo recuperado. +**Referência de Fonte** - Metadados sobre conteúdo recuperado. ## Agentes e Ferramentas - [Módulo 04](../04-tools/README.md) -**Anotação @Tool** - Marca métodos Java como ferramentas chamáveis pela IA. +**Anotação @Tool** - Marca métodos Java como ferramentas acessíveis pela IA. **Padrão ReAct** - Raciocinar → Agir → Observar → Repetir. **Gerenciamento de Sessão** - Contextos separados para usuários diferentes. -**Ferramenta** - Função que um agente de IA pode chamar. +**Tool** - Função que um agente de IA pode chamar. **Descrição da Ferramenta** - Documentação do propósito e parâmetros da ferramenta. @@ -150,83 +150,81 @@ Referência rápida para termos e conceitos usados ao longo do curso. **Anotação @Agent** - Marca interfaces como agentes de IA com definição declarativa de comportamento. -**Agent Listener** - Hook para monitorar execução do agente via `beforeAgentInvocation()` e `afterAgentInvocation()`. +**Agent Listener** - Gancho para monitorar execução do agente via `beforeAgentInvocation()` e `afterAgentInvocation()`. -**Agentic Scope** - Memória compartilhada onde agentes armazenam saídas usando `outputKey` para consumo por agentes downstream. +**Agentic Scope** - Memória compartilhada onde agentes armazenam saídas usando `outputKey` para consumo por agentes seguintes. -**AgenticServices** - Fábrica para criar agentes usando `agentBuilder()` e `supervisorBuilder()`. +**AgenticServices** - Fábrica para criação de agentes usando `agentBuilder()` e `supervisorBuilder()`. -**Fluxo Condicional** - Direcionar com base em condições para agentes especialistas diferentes. +**Fluxo Condicional** - Roteamento baseado em condições para agentes especialistas diferentes. -**Humano no Loop** - Padrão de fluxo com checkpoints humanos para aprovação ou revisão de conteúdo. +**Human-in-the-Loop** - Padrão de workflow adicionando pontos de aprovação humana ou revisão de conteúdo. -**langchain4j-agentic** - Dependência Maven para criação declarativa de agentes (experimental). +**langchain4j-agentic** - Dependência Maven para construção declarativa de agentes (experimental). -**Fluxo de Repetição** - Iterar execução de agente até condição ser atendida (ex.: pontuação de qualidade ≥ 0.8). +**Loop Workflow** - Iterar execução do agente até condição ser atendida (ex: score de qualidade ≥ 0.8). -**outputKey** - Parâmetro da anotação do agente que especifica onde resultados são armazenados em Agentic Scope. +**outputKey** - Parâmetro da anotação do agente que especifica onde resultados são armazenados no Agentic Scope. -**Fluxo Paralelo** - Executar múltiplos agentes simultaneamente para tarefas independentes. +**Parallel Workflow** - Executar vários agentes simultaneamente para tarefas independentes. **Estratégia de Resposta** - Como o supervisor formula a resposta final: LAST, SUMMARY ou SCORED. -**Fluxo Sequencial** - Executar agentes em ordem onde saída flui para a próxima etapa. +**Sequential Workflow** - Executar agentes em ordem onde saída flui para próximo passo. -**Padrão Supervisor Agent** - Padrão agentic avançado onde um LLM supervisor decide dinamicamente quais subagentes chamar. +**Padrão de Supervisor Agent** - Padrão agentic avançado onde um supervisor LLM decide dinamicamente quais subagentes invocar. ## Protocolo de Contexto de Modelo (MCP) - [Módulo 05](../05-mcp/README.md) **langchain4j-mcp** - Dependência Maven para integração MCP no LangChain4j. -**MCP** - Protocolo de Contexto de Modelo: padrão para conectar apps de IA a ferramentas externas. Construa uma vez, use em todo lugar. +**MCP** - Protocolo de Contexto de Modelo: padrão para conectar apps de IA a ferramentas externas. Construir uma vez, usar em todo lugar. **Cliente MCP** - Aplicação que conecta a servidores MCP para descobrir e usar ferramentas. **Servidor MCP** - Serviço que expõe ferramentas via MCP com descrições claras e esquemas de parâmetros. -**McpToolProvider** - Componente LangChain4j que embrulha ferramentas MCP para uso em serviços e agentes de IA. +**McpToolProvider** - Componente LangChain4j que encapsula ferramentas MCP para uso em serviços e agentes de IA. **McpTransport** - Interface para comunicação MCP. Implementações incluem Stdio e HTTP. -**Transporte Stdio** - Transporte local por meio de stdin/stdout. Útil para acesso ao sistema de arquivos ou ferramentas de linha de comando. +**Transporte Stdio** - Transporte local via stdin/stdout. Útil para acesso a sistema de arquivos ou ferramentas de linha de comando. **StdioMcpTransport** - Implementação LangChain4j que inicia servidor MCP como subprocesso. -**Descoberta de Ferramentas** - Cliente consulta servidor por ferramentas disponíveis com descrições e esquemas. +**Descoberta de Ferramentas** - Cliente consulta servidor para ferramentas disponíveis com descrições e esquemas. ## Serviços Azure - [Módulo 01](../01-introduction/README.md) -**Azure AI Search** - Busca na nuvem com capacidade vetorial. [Módulo 03](../03-rag/README.md) +**Azure AI Search** - Busca em nuvem com capacidades vetoriais. [Módulo 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Implanta recursos Azure. +**Azure Developer CLI (azd)** - Ferramenta para deploy de recursos Azure. **Azure OpenAI** - Serviço de IA empresarial da Microsoft. -**Bicep** - Linguagem de infraestrutura como código da Azure. [Guia de Infraestrutura](../01-introduction/infra/README.md) +**Bicep** - Linguagem de infraestrutura como código para Azure. [Guia de Infraestrutura](../01-introduction/infra/README.md) -**Nome da Implantação** - Nome para implantação do modelo no Azure. +**Nome do Deployment** - Nome para implantação de modelo no Azure. -**GPT-5.2** - Modelo OpenAI mais recente com controle de raciocínio. [Módulo 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Último modelo da OpenAI com controle de raciocínio. [Módulo 02](../02-prompt-engineering/README.md) ## Teste e Desenvolvimento - [Guia de Testes](TESTING.md) **Dev Container** - Ambiente de desenvolvimento conteinerizado. [Configuração](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Playground gratuito de modelos de IA. [Módulo 00](../00-quick-start/README.md) +**Teste em Memória** - Testes com armazenamento em memória. -**Teste em Memória** - Teste com armazenamento em memória. - -**Teste de Integração** - Teste com infraestrutura real. +**Teste de Integração** - Testes com infraestrutura real. **Maven** - Ferramenta de automação de build Java. -**Mockito** - Framework Java para mock. +**Mockito** - Framework de mocks Java. -**Spring Boot** - Framework de aplicação Java. [Módulo 01](../01-introduction/README.md) +**Spring Boot** - Framework para aplicações Java. [Módulo 01](../01-introduction/README.md) --- -**Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original em sua língua nativa deve ser considerado a fonte autoritária. Para informações críticas, recomenda-se tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. +**Aviso Legal**: +Este documento foi traduzido usando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. \ No newline at end of file diff --git a/translations/pt-BR/docs/TESTING.md b/translations/pt-BR/docs/TESTING.md index 15e5e2a71..1664c7df0 100644 --- a/translations/pt-BR/docs/TESTING.md +++ b/translations/pt-BR/docs/TESTING.md @@ -1,16 +1,16 @@ # Testando Aplicações LangChain4j -## Sumário +## Índice -- [Início Rápido](../../../docs) -- [O Que os Testes Cobrem](../../../docs) -- [Executando os Testes](../../../docs) -- [Executando Testes no VS Code](../../../docs) -- [Padrões de Teste](../../../docs) -- [Filosofia de Teste](../../../docs) -- [Próximos Passos](../../../docs) +- [Início Rápido](#início-rápido) +- [O Que os Testes Abrangem](#o-que-os-testes-abrangem) +- [Executando os Testes](#executando-os-testes) +- [Executando Testes no VS Code](#executando-testes-no-vs-code) +- [Padrões de Testes](#padrões-de-testes) +- [Filosofia de Testes](#filosofia-de-testes) +- [Próximos Passos](#próximos-passos) -Este guia explica os testes que demonstram como testar aplicações de IA sem precisar de chaves de API ou serviços externos. +Este guia orienta você pelos testes que demonstram como testar aplicações de IA sem precisar de chaves de API ou serviços externos. ## Início Rápido @@ -26,28 +26,27 @@ mvn test mvn --% test ``` -Quando todos os testes passarem, você deverá ver uma saída como a imagem abaixo — testes executados com zero falhas. +Quando todos os testes passarem, você verá uma saída semelhante à imagem abaixo — testes executados sem falhas. Successful Test Results -*Execução bem-sucedida dos testes mostrando todos os testes aprovados com zero falhas* +*Execução bem-sucedida dos testes mostrando todos os testes aprovados sem falhas* -## O Que os Testes Cobrem +## O Que os Testes Abrangem -Este curso foca em **testes unitários** que rodam localmente. Cada teste demonstra um conceito específico do LangChain4j isoladamente. A pirâmide de testes abaixo mostra onde os testes unitários se encaixam — formando a base rápida e confiável sobre a qual o resto da sua estratégia de testes é construída. +Este curso foca em **testes unitários** que rodam localmente. Cada teste demonstra um conceito específico do LangChain4j isoladamente. A pirâmide de testes abaixo mostra onde os testes unitários se encaixam — eles formam a base rápida e confiável sobre a qual o restante da sua estratégia de testes é construída. Testing Pyramid *Pirâmide de testes mostrando o equilíbrio entre testes unitários (rápidos, isolados), testes de integração (componentes reais) e testes ponta a ponta. Este treinamento cobre testes unitários.* -| Módulo | Testes | Foco | Arquivos-Chave | -|--------|-------|-------|-----------| -| **00 - Início Rápido** | 6 | Templates de prompt e substituição de variáveis | `SimpleQuickStartTest.java` | +| Módulo | Testes | Foco | Arquivos Principais | +|--------|--------|-------|--------------------| | **01 - Introdução** | 8 | Memória de conversa e chat com estado | `SimpleConversationTest.java` | | **02 - Engenharia de Prompt** | 12 | Padrões GPT-5.2, níveis de prontidão, saída estruturada | `SimpleGpt5PromptTest.java` | | **03 - RAG** | 10 | Ingestão de documentos, embeddings, busca por similaridade | `DocumentServiceTest.java` | | **04 - Ferramentas** | 12 | Chamada de funções e encadeamento de ferramentas | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Protocolo de Contexto de Modelo com transporte stdio | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | Protocolo de Contexto de Modelo com transporte Stdio | `SimpleMcpTest.java` | ## Executando os Testes @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Execute testes para um módulo específico:** +**Execute testes de um módulo específico:** **Bash:** ```bash @@ -95,7 +94,7 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#deveManterHistoricoDeConversa +mvn test -Dtest=SimpleConversationTest#deveManterHistoricoDeConversas ``` **PowerShell:** @@ -105,27 +104,27 @@ mvn --% test -Dtest=SimpleConversationTest#deveManterHistoricoDaConversa ## Executando Testes no VS Code -Se você usa o Visual Studio Code, o Test Explorer oferece uma interface gráfica para executar e depurar testes. +Se você usa o Visual Studio Code, o Test Explorer fornece uma interface gráfica para executar e depurar testes. VS Code Test Explorer -*Test Explorer do VS Code mostrando a árvore de testes com todas as classes de teste Java e métodos de teste individuais* +*Test Explorer do VS Code mostrando a árvore de testes com todas as classes Java e métodos individuais de teste* -**Para rodar testes no VS Code:** +**Para executar testes no VS Code:** -1. Abra o Test Explorer clicando no ícone de tubo de ensaio na Barra de Atividades +1. Abra o Test Explorer clicando no ícone de béquer na Barra de Atividades 2. Expanda a árvore de testes para ver todos os módulos e classes de teste 3. Clique no botão de play ao lado de qualquer teste para executá-lo individualmente 4. Clique em "Run All Tests" para executar toda a suíte -5. Clique com o botão direito em qualquer teste e selecione "Debug Test" para definir pontos de interrupção e executar passo a passo +5. Clique com o botão direito em qualquer teste e selecione "Debug Test" para definir pontos de interrupção e depurar passo a passo -O Test Explorer exibe marcas verdes para testes aprovados e fornece mensagens detalhadas em caso de falhas. +O Test Explorer mostra marcas de seleção verdes para testes aprovados e fornece mensagens detalhadas de falha quando os testes falham. -## Padrões de Teste +## Padrões de Testes ### Padrão 1: Testando Templates de Prompt -O padrão mais simples testa templates de prompt sem chamar nenhum modelo de IA. Você verifica se a substituição de variáveis funciona corretamente e se os prompts estão formatados conforme esperado. +O padrão mais simples testa templates de prompt sem chamar nenhum modelo de IA. Você verifica se a substituição de variáveis funciona corretamente e se os prompts são formatados conforme esperado. Prompt Template Testing @@ -148,23 +147,11 @@ void testPromptTemplateFormatting() { } ``` -Este teste está em `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Este padrão verifica que a substituição de variáveis funciona corretamente e os prompts são formatados conforme esperado — não é necessária chave de API nem chamada ao modelo. -**Execute-o:** +### Padrão 2: Mocking de Modelos de Linguagem -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testarFormataçãoDoModeloDePrompt -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testarFormataçãoDoModeloDePrompt -``` - -### Padrão 2: Mockando Modelos de Linguagem - -Ao testar lógica de conversa, use Mockito para criar modelos falsos que retornam respostas predefinidas. Isso torna os testes rápidos, gratuitos e determinísticos. +Ao testar a lógica de conversação, use Mockito para criar modelos falsos que retornam respostas predefinidas. Isso torna os testes rápidos, gratuitos e determinísticos. Mock vs Real API Comparison @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Este padrão aparece em `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. O mock assegura comportamento consistente para você verificar que o gerenciamento de memória funciona corretamente. +Este padrão aparece em `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. O mock garante comportamento consistente para que você possa verificar se o gerenciamento de memória funciona corretamente. -### Padrão 3: Testando Isolamento de Conversa +### Padrão 3: Testando a Isolação de Conversas -A memória de conversa deve manter múltiplos usuários separados. Este teste verifica que conversas não misturam contextos. +A memória da conversa deve manter usuários múltiplos separados. Este teste verifica que as conversas não misturam contextos. Conversation Isolation -*Testando isolamento de conversa mostrando armazenamentos de memória separados para diferentes usuários para evitar mistura de contexto* +*Teste de isolamento de conversas mostrando armazenamentos de memória separados para diferentes usuários para evitar mistura de contexto* ```java @Test @@ -250,7 +237,7 @@ void shouldIsolateConversationsByid() { } ``` -Cada conversa mantém seu próprio histórico independente. Em sistemas de produção, esse isolamento é fundamental para aplicações multiusuário. +Cada conversa mantém seu próprio histórico independente. Em sistemas de produção, esse isolamento é crítico para aplicações multiusuário. ### Padrão 4: Testando Ferramentas Independentemente @@ -258,7 +245,7 @@ Ferramentas são funções que a IA pode chamar. Teste-as diretamente para garan Tools Testing -*Testando ferramentas independentemente mostrando execução mock sem chamadas de IA para validar lógica de negócio* +*Testando ferramentas independentemente mostrando execução de ferramenta mock sem chamadas de IA para verificar a lógica de negócio* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Estes testes em `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validam a lógica das ferramentas sem envolvimento da IA. O exemplo de encadeamento mostra como a saída de uma ferramenta alimenta a entrada de outra. +Estes testes de `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validam a lógica das ferramentas sem envolvimento da IA. O exemplo de encadeamento mostra como a saída de uma ferramenta alimenta a entrada de outra. ### Padrão 5: Teste RAG em Memória -Sistemas RAG tradicionalmente exigem bancos de dados vetoriais e serviços de embedding. O padrão em memória permite testar todo o pipeline sem dependências externas. +Sistemas RAG tradicionalmente exigem bancos de dados vetoriais e serviços de embeddings. O padrão em memória permite testar todo o pipeline sem dependências externas. In-Memory RAG Testing -*Fluxo de teste RAG em memória mostrando análise de documentos, armazenamento de embeddings e busca por similaridade sem exigir banco de dados* +*Fluxo de trabalho do teste RAG em memória mostrando parsing de documentos, armazenamento de embeddings e busca por similaridade sem precisar de banco de dados* ```java @Test @@ -306,11 +293,11 @@ void testProcessTextDocument() { } ``` -Este teste de `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` cria um documento em memória e verifica segmentação e tratamento de metadados. +Este teste de `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` cria um documento em memória e verifica a divisão em chunks e o manuseio de metadados. ### Padrão 6: Teste de Integração MCP -O módulo MCP testa a integração do Model Context Protocol usando transporte stdio. Estes testes verificam se sua aplicação pode iniciar e se comunicar com servidores MCP como subprocessos. +O módulo MCP testa a integração do Protocolo de Contexto de Modelo usando transporte stdio. Estes testes verificam que sua aplicação pode iniciar e comunicar-se com servidores MCP como subprocessos. Os testes em `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validam o comportamento do cliente MCP. @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## Filosofia de Teste +## Filosofia de Testes -Teste seu código, não a IA. Seus testes devem validar o código que você escreve verificando como prompts são construídos, como a memória é gerenciada e como ferramentas são executadas. Respostas da IA variam e não devem fazer parte das assertivas dos testes. Pergunte-se se seu template de prompt substitui variáveis corretamente, não se a IA dá a resposta certa. +Teste seu código, não a IA. Seus testes devem validar o código que você escreve verificando como os prompts são construídos, como a memória é gerenciada e como as ferramentas executam. Respostas de IA variam e não devem fazer parte das asserções dos testes. Pergunte-se se seu template de prompt substitui corretamente as variáveis, não se a IA dá a resposta certa. -Use mocks para modelos de linguagem. São dependências externas que são lentas, caras e não determinísticas. Mockar torna os testes rápidos com milissegundos em vez de segundos, gratuitos sem custos de API e determinísticos com o mesmo resultado sempre. +Use mocks para modelos de linguagem. Eles são dependências externas que são lentas, caras e não determinísticas. Mocking torna os testes rápidos, com milissegundos ao invés de segundos, grátis sem custos de API e determinísticos com o mesmo resultado sempre. -Mantenha os testes independentes. Cada teste deve preparar seus próprios dados, não depender de outros e limpar seu estado. Testes devem passar independentemente da ordem de execução. +Mantenha os testes independentes. Cada teste deve configurar seus próprios dados, não depender de outros testes e limpar após si. Testes devem passar independentemente da ordem de execução. -Teste casos limites além do caminho feliz. Experimente entradas vazias, entradas muito grandes, caracteres especiais, parâmetros inválidos e condições de fronteira. Muitas vezes isso revela bugs não expostos pelo uso normal. +Teste casos limites além do caminho feliz. Tente entradas vazias, entradas muito grandes, caracteres especiais, parâmetros inválidos e condições de fronteira. Isso frequentemente revela bugs que o uso normal não expõe. -Use nomes descritivos. Compare `shouldMaintainConversationHistoryAcrossMultipleMessages()` com `test1()`. O primeiro diz exatamente o que está sendo testado, facilitando muito o debug ao falhar. +Use nomes descritivos. Compare `shouldMaintainConversationHistoryAcrossMultipleMessages()` com `test1()`. O primeiro diz exatamente o que está sendo testado, facilitando muito a depuração de falhas. ## Próximos Passos -Agora que você entende os padrões de teste, aprofunde-se em cada módulo: +Agora que você entende os padrões de teste, mergulhe mais fundo em cada módulo: -- **[00 - Início Rápido](../00-quick-start/README.md)** - Comece com o básico de templates de prompt - **[01 - Introdução](../01-introduction/README.md)** - Aprenda gerenciamento de memória de conversa -- **[02 - Engenharia de Prompt](../02-prompt-engineering/README.md)** - Domine os padrões de prompt GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Construa sistemas de geração augmentada por recuperação -- **[04 - Ferramentas](../04-tools/README.md)** - Implemente chamadas de funções e cadeias de ferramentas +- **[02 - Engenharia de Prompt](../02/prompt-engineering/README.md)** - Domine padrões de prompt GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Construa sistemas de geração aumentada por recuperação +- **[04 - Ferramentas](../04-tools/README.md)** - Implemente chamadas de funções e encadeamento de ferramentas - **[05 - MCP](../05-mcp/README.md)** - Integre o Protocolo de Contexto de Modelo O README de cada módulo fornece explicações detalhadas dos conceitos testados aqui. --- -**Navegação:** [← Voltar ao Principal](../README.md) +**Navegação:** [← Voltar para o Início](../README.md) --- -**Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução. +**Aviso Legal**: +Este documento foi traduzido usando o serviço de tradução por IA [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. \ No newline at end of file diff --git a/translations/pt-PT/.co-op-translator.json b/translations/pt-PT/.co-op-translator.json index bd933a2bc..f6e3b04ab 100644 --- a/translations/pt-PT/.co-op-translator.json +++ b/translations/pt-PT/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "pt-PT" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T19:02:10+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T11:56:06+00:00", "source_file": "01-introduction/README.md", "language_code": "pt-PT" }, @@ -18,20 +18,20 @@ "language_code": "pt-PT" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T19:04:25+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T11:52:03+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "pt-PT" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T19:05:56+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T11:55:16+00:00", "source_file": "03-rag/README.md", "language_code": "pt-PT" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:45:52+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T11:54:09+00:00", "source_file": "04-tools/README.md", "language_code": "pt-PT" }, @@ -54,8 +54,8 @@ "language_code": "pt-PT" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:51:55+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T11:50:47+00:00", "source_file": "README.md", "language_code": "pt-PT" }, @@ -72,14 +72,14 @@ "language_code": "pt-PT" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T19:09:09+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T11:52:28+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "pt-PT" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T19:09:55+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T11:53:01+00:00", "source_file": "docs/TESTING.md", "language_code": "pt-PT" } diff --git a/translations/pt-PT/00-quick-start/README.md b/translations/pt-PT/00-quick-start/README.md deleted file mode 100644 index 897c722ae..000000000 --- a/translations/pt-PT/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Quick Start - -## Table of Contents - -- [Introdução](../../../00-quick-start) -- [O que é LangChain4j?](../../../00-quick-start) -- [Dependências do LangChain4j](../../../00-quick-start) -- [Pré-requisitos](../../../00-quick-start) -- [Configuração](../../../00-quick-start) - - [1. Obter o seu Token do GitHub](../../../00-quick-start) - - [2. Definir o seu Token](../../../00-quick-start) -- [Executar os Exemplos](../../../00-quick-start) - - [1. Chat Básico](../../../00-quick-start) - - [2. Padrões de Prompt](../../../00-quick-start) - - [3. Chamada de Funções](../../../00-quick-start) - - [4. Perguntas e Respostas a Documentos (Easy RAG)](../../../00-quick-start) - - [5. IA Responsável](../../../00-quick-start) -- [O que cada exemplo demonstra](../../../00-quick-start) -- [Próximos Passos](../../../00-quick-start) -- [Resolução de Problemas](../../../00-quick-start) - -## Introdução - -Este quickstart destina-se a colocá-lo a trabalhar com LangChain4j da forma mais rápida possível. Cobre o básico absoluto da construção de aplicações de IA com LangChain4j e Modelos GitHub. Nos próximos módulos, irá mudar para Azure OpenAI e GPT-5.2 e aprofundar cada conceito. - -## O que é LangChain4j? - -LangChain4j é uma biblioteca Java que simplifica a construção de aplicações potenciadas por IA. Em vez de lidar com cliente HTTP e parsing JSON, trabalha com APIs Java limpas. - -O "chain" (cadeia) em LangChain refere-se a encadear vários componentes – pode encadear um prompt a um modelo, a um parser, ou encadear múltiplas chamadas de IA onde uma saída alimenta a próxima entrada. Este início rápido foca-se nos fundamentos antes de explorar cadeias mais complexas. - -LangChain4j Chaining Concept - -*Encadeamento de componentes no LangChain4j - blocos de construção que ligam para criar fluxos de trabalho poderosos de IA* - -Usaremos três componentes principais: - -**ChatModel** - A interface para interações com modelos de IA. Chame `model.chat("prompt")` e obtenha uma string de resposta. Usamos `OpenAiOfficialChatModel` que funciona com endpoints compatíveis com OpenAI, como os Modelos do GitHub. - -**AiServices** - Cria interfaces de serviço de IA com tipagem segura. Defina métodos, anote-os com `@Tool`, e LangChain4j gere a orquestração. A IA chama automaticamente os seus métodos Java quando necessário. - -**MessageWindowChatMemory** - Mantém o histórico da conversação. Sem isto, cada pedido é independente. Com ele, a IA lembra mensagens anteriores e mantém o contexto através de múltiplos turnos. - -LangChain4j Architecture - -*Arquitetura do LangChain4j - componentes principais a trabalhar juntos para potenciar as suas aplicações de IA* - -## Dependências do LangChain4j - -Este quick start usa três dependências Maven no [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -O módulo `langchain4j-open-ai-official` fornece a classe `OpenAiOfficialChatModel` que liga a APIs compatíveis com OpenAI. Os Modelos do GitHub usam o mesmo formato de API, por isso não é necessário nenhum adaptador especial - basta apontar a URL base para `https://models.github.ai/inference`. - -O módulo `langchain4j-easy-rag` fornece divisão automática de documentos, embedding e recuperação para que possa construir aplicações RAG sem configurar cada passo manualmente. - -## Pré-requisitos - -**A usar o Dev Container?** Java e Maven já estão instalados. Só precisa de um Token de Acesso Pessoal GitHub. - -**Desenvolvimento Local:** -- Java 21+, Maven 3.9+ -- Token de Acesso Pessoal GitHub (instruções abaixo) - -> **Nota:** Este módulo usa `gpt-4.1-nano` dos Modelos GitHub. Não modifique o nome do modelo no código - está configurado para funcionar com os modelos disponíveis no GitHub. - -## Configuração - -### 1. Obter o seu Token do GitHub - -1. Vá a [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Clique em "Generate new token" -3. Defina um nome descritivo (ex.: "LangChain4j Demo") -4. Defina a expiração (recomendado 7 dias) -5. Em "Account permissions", encontre "Models" e defina para "Read-only" -6. Clique em "Generate token" -7. Copie e guarde o seu token - não voltará a vê-lo - -### 2. Definir o seu Token - -**Opção 1: Usando VS Code (Recomendado)** - -Se usa VS Code, adicione o seu token no ficheiro `.env` na raiz do projeto: - -Se o ficheiro `.env` não existir, copie `.env.example` para `.env` ou crie um novo ficheiro `.env` na raiz do projeto. - -**Exemplo de ficheiro `.env`:** -```bash -# Em /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Depois pode simplesmente clicar com o botão direito em qualquer ficheiro demo (ex.: `BasicChatDemo.java`) no Explorador e selecionar **"Run Java"**, ou usar as configurações de lançamento do painel Run and Debug. - -**Opção 2: Usando Terminal** - -Defina o token como variável de ambiente: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Executar os Exemplos - -**Usando VS Code:** Basta clicar com o botão direito em qualquer ficheiro demo no Explorador e selecionar **"Run Java"**, ou usar as configurações de lançamento do painel Run and Debug (certifique-se que adicionou o token ao ficheiro `.env` primeiro). - -**Usando Maven:** Alternativamente, pode executar pela linha de comandos: - -### 1. Chat Básico - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Padrões de Prompt - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Mostra prompting zero-shot, few-shot, chain-of-thought e baseado em papéis. - -### 3. Chamada de Funções - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -A IA chama automaticamente os seus métodos Java quando necessário. - -### 4. Perguntas e Respostas a Documentos (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Faça perguntas sobre os seus documentos usando Easy RAG com embedding e recuperação automáticos. - -### 5. IA Responsável - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Veja como os filtros de segurança da IA bloqueiam conteúdos prejudiciais. - -## O que cada exemplo demonstra - -**Chat Básico** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Comece aqui para ver LangChain4j no seu estado mais simples. Vai criar um `OpenAiOfficialChatModel`, enviar um prompt com `.chat()` e obter uma resposta. Isto demonstra a base: como inicializar modelos com endpoints personalizados e chaves API. Quando compreender este padrão, tudo o resto assenta nele. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) e pergunte: -> - "Como mudo dos Modelos GitHub para Azure OpenAI neste código?" -> - "Que outros parâmetros posso configurar em OpenAiOfficialChatModel.builder()?" -> - "Como adiciono respostas em streaming em vez de esperar pela resposta completa?" - -**Engenharia de Prompt** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Agora que sabe como falar com um modelo, vamos explorar o que lhe diz. Este demo usa a mesma configuração de modelo mas mostra cinco padrões diferentes de prompting. Experimente prompts zero-shot para instruções diretas, few-shot que aprendem com exemplos, chain-of-thought que revelam os passos do raciocínio, e prompts baseados em papéis que definem contexto. Verá como o mesmo modelo dá resultados dramaticamente diferentes consoante como formula o pedido. - -O demo também demonstra templates de prompt, que são uma forma poderosa de criar prompts reutilizáveis com variáveis. -O exemplo abaixo mostra um prompt usando o `PromptTemplate` do LangChain4j para preencher variáveis. A IA responderá com base no destino e atividade fornecidos. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) e pergunte: -> - "Qual é a diferença entre prompting zero-shot e few-shot, e quando devo usar cada um?" -> - "Como o parâmetro temperatura afeta as respostas do modelo?" -> - "Quais são algumas técnicas para prevenir ataques de injeção de prompt em produção?" -> - "Como posso criar objetos PromptTemplate reutilizáveis para padrões comuns?" - -**Integração com Ferramentas** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Aqui é onde LangChain4j se torna poderoso. Vai usar `AiServices` para criar um assistente de IA que pode chamar os seus métodos Java. Basta anotar os métodos com `@Tool("descrição")` e LangChain4j trata do resto – a IA decide automaticamente quando usar cada ferramenta com base no que o utilizador pede. Isto demonstra a chamada de funções, uma técnica chave para construir IA que pode tomar ações, não apenas responder a perguntas. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) e pergunte: -> - "Como funciona a anotação @Tool e o que o LangChain4j faz com ela por trás das cenas?" -> - "Pode a IA chamar múltiplas ferramentas em sequência para resolver problemas complexos?" -> - "O que acontece se uma ferramenta lançar uma exceção - como devo tratar erros?" -> - "Como integraria uma API real em vez deste exemplo da calculadora?" - -**Perguntas e Respostas a Documentos (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Aqui verá RAG (geração aumentada por recuperação) usando a abordagem "Easy RAG" do LangChain4j. Documentos são carregados, automaticamente divididos e embedados numa store em memória, depois um recuperador de conteúdo fornece pedaços relevantes à IA no momento da consulta. A IA responde com base nos seus documentos, não no seu conhecimento geral. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) e pergunte: -> - "Como é que o RAG previne alucinações da IA comparado ao uso dos dados de treino do modelo?" -> - "Qual é a diferença entre esta abordagem fácil e uma pipeline RAG personalizada?" -> - "Como escalaria isto para lidar com múltiplos documentos ou bases de conhecimento maiores?" - -**IA Responsável** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Construa segurança na IA com defesa em profundidade. Este demo mostra duas camadas de proteção a funcionar juntas: - -**Parte 1: LangChain4j Input Guardrails** - Bloqueia prompts perigosos antes de chegarem ao LLM. Crie guardrails personalizados que verificam palavras-chave ou padrões proibidos. Estes correm no seu código, portanto são rápidos e gratuitos. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Parte 2: Filtros de Segurança do Provedor** - Os Modelos GitHub têm filtros embutidos que apanham o que os seus guardrails possam falhar. Verá bloqueios fortes (erros HTTP 400) para violações graves e recusas suaves onde a IA recusa educadamente. - -> **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) e pergunte: -> - "O que é InputGuardrail e como crio o meu próprio?" -> - "Qual é a diferença entre um bloqueio forte e uma recusa suave?" -> - "Porque usar guardrails e filtros do provedor em conjunto?" - -## Próximos Passos - -**Módulo Seguinte:** [01-introduction - Começar com LangChain4j](../01-introduction/README.md) - ---- - -**Navegação:** [← Voltar ao Principal](../README.md) | [Seguinte: Módulo 01 - Introdução →](../01-introduction/README.md) - ---- - -## Resolução de Problemas - -### Primeira Compilação Maven - -**Problema**: `mvn clean compile` ou `mvn package` inicial demora muito (10-15 minutos) - -**Causa**: O Maven precisa de descarregar todas as dependências do projeto (Spring Boot, bibliotecas LangChain4j, SDKs Azure, etc.) na primeira compilação. - -**Solução**: Este comportamento é normal. As compilações subsequentes serão muito mais rápidas pois as dependências ficam cacheadas localmente. O tempo de descarga depende da velocidade da sua rede. - -### Sintaxe dos Comandos Maven no PowerShell - -**Problema**: Comandos Maven falham com erro `Unknown lifecycle phase ".mainClass=..."` -**Causa**: PowerShell interpreta `=` como operador de atribuição de variável, quebrando a sintaxe da propriedade Maven - -**Solução**: Use o operador de paragem de análise `--%` antes do comando Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -O operador `--%` indica ao PowerShell que passe todos os argumentos restantes literalmente para o Maven sem interpretação. - -### Exibição de Emojis no Windows PowerShell - -**Problema**: Respostas da IA mostram caracteres indesejados (ex.: `????` ou `â??`) em vez de emojis no PowerShell - -**Causa**: A codificação padrão do PowerShell não suporta emojis UTF-8 - -**Solução**: Execute este comando antes de executar aplicações Java: -```cmd -chcp 65001 -``` - -Isto força a codificação UTF-8 no terminal. Alternativamente, use o Windows Terminal que tem melhor suporte a Unicode. - -### Depuração de Chamadas API - -**Problema**: Erros de autenticação, limites de taxa ou respostas inesperadas do modelo IA - -**Solução**: Os exemplos incluem `.logRequests(true)` e `.logResponses(true)` para mostrar as chamadas API na consola. Isto ajuda a diagnosticar erros de autenticação, limites de taxa ou respostas inesperadas. Remova estes flags em produção para reduzir o ruído nos logs. - ---- - - -**Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, tenha em atenção que as traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autoritativa. Para informações críticas, recomendam-se traduções profissionais feitas por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes da utilização desta tradução. - \ No newline at end of file diff --git a/translations/pt-PT/01-introduction/README.md b/translations/pt-PT/01-introduction/README.md index 4cf011d77..e5ff42f6f 100644 --- a/translations/pt-PT/01-introduction/README.md +++ b/translations/pt-PT/01-introduction/README.md @@ -2,84 +2,84 @@ ## Índice -- [Vídeo Explicativo](../../../01-introduction) -- [O Que Vai Aprender](../../../01-introduction) -- [Pré-requisitos](../../../01-introduction) -- [Compreender o Problema Central](../../../01-introduction) -- [Compreender Tokens](../../../01-introduction) -- [Como a Memória Funciona](../../../01-introduction) -- [Como Isto Utiliza LangChain4j](../../../01-introduction) -- [Desplegar Infraestrutura Azure OpenAI](../../../01-introduction) -- [Executar a Aplicação Localmente](../../../01-introduction) -- [Utilizar a Aplicação](../../../01-introduction) - - [Chat Sem Estado (Painel Esquerdo)](../../../01-introduction) - - [Chat Com Estado (Painel Direito)](../../../01-introduction) -- [Próximos Passos](../../../01-introduction) +- [Vídeo Explicativo](#vídeo-explicativo) +- [O que Vai Aprender](#o-que-vai-aprender) +- [Pré-requisitos](#pré-requisitos) +- [Compreender o Problema Principal](#compreender-o-problema-principal) +- [Compreender Tokens](#compreender-tokens) +- [Como Funciona a Memória](#como-funciona-a-memória) +- [Como Isto Usa LangChain4j](#como-isto-usa-langchain4j) +- [Desplegar Infraestrutura Azure OpenAI](#desplegar-infraestrutura-azure-openai) +- [Executar a Aplicação Localmente](#executar-a-aplicação-localmente) +- [Usar a Aplicação](#usar-a-aplicação) + - [Chat Sem Estado (Painel Esquerdo)](#chat-sem-estado-painel-esquerdo) + - [Chat Com Estado (Painel Direito)](#chat-com-estado-painel-direito) +- [Próximos Passos](#próximos-passos) ## Vídeo Explicativo -Veja esta sessão ao vivo que explica como começar com este módulo: +Assista a esta sessão ao vivo que explica como começar com este módulo: -Getting Started with LangChain4j - Live Session +Começar com LangChain4j - Sessão ao Vivo -## O Que Vai Aprender +## O que Vai Aprender -No início rápido, usou os Modelos do GitHub para enviar prompts, chamar ferramentas, construir um pipeline RAG e testar guardrails. Essas demonstrações mostraram o que é possível — agora mudamos para Azure OpenAI e GPT-5.2 e começamos a construir aplicações estilo produção. Este módulo foca em IA conversacional que lembra contexto e mantém estado — os conceitos que os demos do início rápido usavam nos bastidores, mas que não foram explicados. +Este é o seu ponto de partida com LangChain4j e Azure OpenAI. Começamos pelos fundamentos e iniciamos a construção de aplicações em modo produção. Este módulo foca na IA conversacional que lembra o contexto e mantém o estado — os conceitos base sobre os quais todos os módulos posteriores se constroem. -Vamos usar o GPT-5.2 do Azure OpenAI ao longo deste guia porque as suas capacidades avançadas de raciocínio tornam o comportamento dos diferentes padrões mais evidente. Quando adicionar memória, verá claramente a diferença. Isso facilita compreender o que cada componente traz para a sua aplicação. +Usaremos o GPT-5.2 da Azure OpenAI ao longo deste guia porque as suas capacidades avançadas de raciocínio tornam mais evidente o comportamento dos diferentes padrões. Quando adicionar memória, verá claramente a diferença. Isto facilita o entendimento do que cada componente traz para a sua aplicação. -Vai construir uma aplicação que demonstra ambos os padrões: +Construirá uma aplicação que demonstra ambos os padrões: -**Chat Sem Estado** - Cada pedido é independente. O modelo não tem memória das mensagens anteriores. Este é o padrão que usou no início rápido. +**Chat Sem Estado** - Cada pedido é independente. O modelo não tem memória das mensagens anteriores. Este é o ponto de partida mais simples. -**Conversa Com Estado** - Cada pedido inclui o histórico da conversa. O modelo mantém o contexto ao longo de múltiplos turnos. Isto é o que as aplicações em produção requerem. +**Conversa com Estado** - Cada pedido inclui o histórico da conversa. O modelo mantém o contexto através de múltiplas interações. Isto é o que as aplicações em produção exigem. ## Pré-requisitos -- Subscrição Azure com acesso a Azure OpenAI +- Subscrição Azure com acesso ao Azure OpenAI - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) > **Nota:** Java, Maven, Azure CLI e Azure Developer CLI (azd) estão pré-instalados no devcontainer fornecido. -> **Nota:** Este módulo usa GPT-5.2 no Azure OpenAI. O despliege está configurado automaticamente através de `azd up` - não modifique o nome do modelo no código. +> **Nota:** Este módulo usa GPT-5.2 no Azure OpenAI. O deploy é configurado automaticamente via `azd up` - não modifique o nome do modelo no código. -## Compreender o Problema Central +## Compreender o Problema Principal -Os modelos de linguagem são sem estado. Cada chamada API é independente. Se enviar "O meu nome é John" e depois perguntar "Qual é o meu nome?", o modelo não tem ideia que acabou de se apresentar. Trata cada pedido como se fosse a primeira conversa que alguma vez teve. +Os modelos de linguagem são sem estado. Cada chamada API é independente. Se enviar "O meu nome é João" e depois perguntar "Qual é o meu nome?", o modelo não tem noção de que se apresentou anteriormente. Trata cada pedido como se fosse a primeira conversa que teve. -Isto é aceitável para Q&A simples, mas inútil para aplicações reais. Bots de serviço ao cliente precisam lembrar o que lhes disse. Assistentes pessoais precisam de contexto. Qualquer conversa com múltiplos turnos requer memória. +Isto é aceitável para perguntas e respostas simples, mas inútil para aplicações reais. Bots de atendimento ao cliente precisam de lembrar o que lhes disse. Assistentes pessoais precisam de contexto. Qualquer conversa com múltiplas interações exige memória. -O diagrama seguinte contrasta as duas abordagens — à esquerda, uma chamada sem estado que esquece o seu nome; à direita, uma chamada com estado suportada por ChatMemory que o lembra. +O diagrama abaixo contrasta as duas abordagens — à esquerda, uma chamada sem estado que esquece o seu nome; à direita, uma chamada com estado suportada pelo ChatMemory que o recorda. -Stateless vs Stateful Conversations +Conversas Sem Estado vs Com Estado -*A diferença entre conversas sem estado (chamadas independentes) e com estado (com conhecimento do contexto)* +*A diferença entre conversas sem estado (chamadas independentes) e com estado (com consciência de contexto)* ## Compreender Tokens -Antes de mergulhar nas conversas, é importante compreender tokens - as unidades básicas de texto que os modelos de linguagem processam: +Antes de começar a explorar conversas, é importante perceber os tokens - as unidades básicas de texto que os modelos de linguagem processam: -Token Explanation +Explicação de Tokens -*Exemplo de como o texto é dividido em tokens - "I love AI!" torna-se 4 unidades separadas de processamento* +*Exemplo de como o texto é dividido em tokens - "Adoro IA!" torna-se em 4 unidades separadas para processamento* -Tokens são como os modelos de IA medem e processam texto. Palavras, pontuação e até espaços podem ser tokens. O seu modelo tem um limite sobre quantos tokens pode processar de cada vez (400.000 para o GPT-5.2, com até 272.000 tokens de entrada e 128.000 tokens de saída). Compreender tokens ajuda a gerir o comprimento da conversa e os custos. +Os tokens são como os modelos de IA medem e processam texto. Palavras, pontuação e até espaços podem ser tokens. O seu modelo tem um limite de tokens que pode processar de uma vez (400.000 para GPT-5.2, com até 272.000 tokens de entrada e 128.000 tokens de saída). Compreender tokens ajuda a gerir o comprimento da conversa e os custos. -## Como a Memória Funciona +## Como Funciona a Memória -A memória de chat resolve o problema de ser sem estado mantendo o histórico da conversa. Antes de enviar o seu pedido para o modelo, o framework adiciona mensagens anteriores relevantes. Quando pergunta "Qual é o meu nome?", o sistema envia na verdade todo o histórico da conversa, permitindo que o modelo veja que disse anteriormente "O meu nome é John." +A memória de chat resolve o problema de falta de estado ao manter o histórico da conversa. Antes de enviar o seu pedido ao modelo, o framework junta as mensagens anteriores relevantes. Quando pergunta "Qual é o meu nome?", o sistema de facto envia todo o histórico da conversa, permitindo ao modelo ver que disse "O meu nome é João". -LangChain4j fornece implementações de memória que tratam disso automaticamente. Escolhe quantas mensagens reter e o framework gere a janela de contexto. O diagrama abaixo mostra como MessageWindowChatMemory mantém uma janela deslizante das mensagens recentes. +LangChain4j providencia implementações de memória que tratam disto automaticamente. Você escolhe quantas mensagens quer reter e o framework gere a janela de contexto. O diagrama abaixo mostra como MessageWindowChatMemory mantém uma janela deslizante das mensagens recentes. -Memory Window Concept +Conceito de Janela de Memória *MessageWindowChatMemory mantém uma janela deslizante das mensagens recentes, eliminando automaticamente as mais antigas* -## Como Isto Utiliza LangChain4j +## Como Isto Usa LangChain4j -Este módulo estende o início rápido integrando Spring Boot e adicionando memória de conversa. Eis como as peças se encaixam: +Este módulo integra Spring Boot e adiciona memória de conversa. Eis como as peças se encaixam: **Dependências** - Adicione duas bibliotecas LangChain4j: @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -O builder lê as credenciais das variáveis de ambiente definidas por `azd up`. Definir `baseUrl` para o seu endpoint Azure faz o cliente OpenAI funcionar com Azure OpenAI. +O builder lê credenciais das variáveis de ambiente definidas pelo `azd up`. Definir `baseUrl` para o seu endpoint Azure faz o cliente OpenAI funcionar com o Azure OpenAI. -**Memória de Conversa** - Faça o tracking do histórico de chat com MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Memória de Conversa** - Rastreie o histórico de chat com MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,39 +124,39 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Crie a memória com `withMaxMessages(10)` para manter as últimas 10 mensagens. Adicione mensagens do utilizador e da IA com wrappers tipados: `UserMessage.from(text)` e `AiMessage.from(text)`. Recupere o histórico com `memory.messages()` e envie-o para o modelo. O serviço armazena instâncias de memória separadas por ID da conversa, permitindo que múltiplos utilizadores conversem simultaneamente. +Crie a memória com `withMaxMessages(10)` para manter as últimas 10 mensagens. Adicione mensagens do utilizador e da IA com wrappers tipados: `UserMessage.from(text)` e `AiMessage.from(text)`. Recupere o histórico com `memory.messages()` e envie-o ao modelo. O serviço guarda instâncias de memória separadas por ID de conversa, permitindo múltiplos utilizadores a conversar simultaneamente. > **🤖 Experimente com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) e pergunte: -> - "Como é que o MessageWindowChatMemory decide quais mensagens eliminar quando a janela está cheia?" -> - "Posso implementar armazenamento de memória personalizado usando uma base de dados em vez de memória volátil?" -> - "Como adicionaria sumarização para comprimir o histórico antigo da conversa?" +> - "Como decide o MessageWindowChatMemory quais mensagens eliminar quando a janela está cheia?" +> - "Posso implementar armazenamento de memória personalizado usando uma base de dados em vez da memória volátil?" +> - "Como poderia acrescentar sumarização para comprimir o histórico antigo da conversa?" -O endpoint de chat sem estado ignora totalmente a memória - apenas `chatModel.chat(prompt)` tal como no início rápido. O endpoint com estado adiciona mensagens à memória, recupera o histórico e inclui esse contexto em cada pedido. Mesma configuração do modelo, padrões diferentes. +O endpoint de chat sem estado ignora completamente a memória - apenas `chatModel.chat(prompt)` como no início rápido. O endpoint com estado adiciona mensagens à memória, recupera o histórico e inclui esse contexto em cada pedido. Mesma configuração de modelo, padrões diferentes. ## Desplegar Infraestrutura Azure OpenAI **Bash:** ```bash cd 01-introduction -azd up # Selecionar subscrição e localização (eastus2 recomendado) +azd up # Selecione subscrição e localização (eastus2 recomendado) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Selecionar subscrição e localização (eastus2 recomendado) +azd up # Selecione a subscrição e a localização (recomendado eastus2) ``` -> **Nota:** Se encontrar um erro de timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), basta executar `azd up` novamente. Os recursos Azure podem ainda estar a ser provisionados em segundo plano, e tentar outra vez permite que o despliege seja concluído assim que os recursos chegarem a um estado terminal. +> **Nota:** Se encontrar um erro de timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), execute `azd up` novamente. Os recursos Azure podem ainda estar a ser provisionados em segundo plano, e tentar de novo permite que o deploy conclua assim que os recursos atingem um estado terminal. Isto irá: -1. Desplegar o recurso Azure OpenAI com modelos GPT-5.2 e text-embedding-3-small -2. Gerar automaticamente o ficheiro `.env` na raiz do projeto com as credenciais +1. Desplegar recurso Azure OpenAI com modelos GPT-5.2 e text-embedding-3-small +2. Gerar automaticamente o ficheiro `.env` na raiz do projeto com credenciais 3. Configurar todas as variáveis de ambiente necessárias -**Tem problemas no despliege?** Veja o [README da Infraestrutura](infra/README.md) para resolução detalhada incluindo conflitos de nome de subdomínio, passos manuais no Portal Azure, e orientações para configuração do modelo. +**Tem problemas com o deploy?** Consulte o [README da Infraestrutura](infra/README.md) para resolução detalhada de problemas, incluindo conflitos de nomes de subdomínio, passos manuais no Portal Azure e orientações sobre configuração do modelo. -**Verifique se o despliege teve sucesso:** +**Verifique se o deploy foi bem-sucedido:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, etc. Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, etc. ``` -> **Nota:** O comando `azd up` gera automaticamente o ficheiro `.env`. Se precisar de o atualizar mais tarde, pode editar manualmente o ficheiro `.env` ou regenerá-lo executando: +> **Nota:** O comando `azd up` gera automaticamente o ficheiro `.env`. Se precisar de atualizá-lo mais tarde, pode editar manualmente o ficheiro `.env` ou regenerá-lo executando: > > **Bash:** > ```bash @@ -184,9 +184,9 @@ Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, etc. ## Executar a Aplicação Localmente -**Verifique o despliege:** +**Verificar deploy:** -Assegure-se que o ficheiro `.env` existe na diretoria raiz com as credenciais Azure. Execute isto a partir da diretoria do módulo (`01-introduction/`): +Assegure que o ficheiro `.env` existe na raiz com as credenciais Azure. Execute isto a partir da diretoria do módulo (`01-introduction/`): **Bash:** ```bash @@ -198,19 +198,19 @@ cat ../.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Inicie as aplicações:** +**Iniciar as aplicações:** **Opção 1: Usar o Spring Boot Dashboard (Recomendado para utilizadores VS Code)** -O dev container inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerir todas as aplicações Spring Boot. Pode encontrá-la na Barra de Atividades à esquerda do VS Code (procure o ícone Spring Boot). +O dev container inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerir todas as aplicações Spring Boot. Pode encontrá-la na Barra de Atividades à esquerda no VS Code (procure o ícone do Spring Boot). -No Spring Boot Dashboard pode: +No Spring Boot Dashboard, pode: - Ver todas as aplicações Spring Boot disponíveis no workspace - Iniciar/parar aplicações com um clique -- Visualizar logs da aplicação em tempo real +- Ver logs da aplicação em tempo real - Monitorizar o estado da aplicação -Basta clicar no botão de play junto a "introduction" para iniciar este módulo, ou iniciar todos os módulos de uma vez. +Basta clicar no botão de play ao lado de "introduction" para iniciar este módulo, ou iniciar todos os módulos de uma vez. Spring Boot Dashboard @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Ambos os scripts carregam automaticamente as variáveis de ambiente do ficheiro `.env` da raiz e irão construir os JARs se estes não existirem. +Ambos os scripts carregam automaticamente as variáveis de ambiente a partir do ficheiro `.env` na raiz e vão construir os JARs se não existirem. -> **Nota:** Se preferir compilar todos os módulos manualmente antes de iniciar: +> **Nota:** Se preferir construir manualmente todos os módulos antes de iniciar: > > **Bash:** > ```bash @@ -275,48 +275,48 @@ cd .. && ./stop-all.sh # Todos os módulos **PowerShell:** ```powershell -.\stop.ps1 # Apenas este módulo +.\stop.ps1 # Este módulo apenas # Ou cd ..; .\stop-all.ps1 # Todos os módulos ``` -## Utilizar a Aplicação +## Usar a Aplicação -A aplicação oferece uma interface web com duas implementações de chat lado a lado. +A aplicação fornece uma interface web com duas implementações de chat lado-a-lado. -Application Home Screen +Ecrã Inicial da Aplicação -*Painel mostrando as opções Simples Chat (sem estado) e Conversational Chat (com estado)* +*Painel que mostra as opções Chat Simples (sem estado) e Chat Conversacional (com estado)* ### Chat Sem Estado (Painel Esquerdo) -Experimente primeiro. Pergunte "O meu nome é John" e depois imediatamente pergunte "Qual é o meu nome?". O modelo não irá lembrar porque cada mensagem é independente. Isto demonstra o problema central da integração básica com modelos de linguagem - nenhum contexto de conversa. +Comece por este. Peça "O meu nome é João" e depois pergunte imediatamente "Qual é o meu nome?" O modelo não vai lembrar porque cada mensagem é independente. Isto demonstra o problema principal da integração básica de modelos de linguagem - sem contexto de conversa. -Stateless Chat Demo +Demo Chat Sem Estado -*IA não se lembra do seu nome da mensagem anterior* +*IA não lembra o seu nome da mensagem anterior* ### Chat Com Estado (Painel Direito) -Agora experimente a mesma sequência aqui. Pergunte "O meu nome é John" e depois "Qual é o meu nome?". Desta vez lembra-se. A diferença é MessageWindowChatMemory - esta mantém o histórico da conversa e inclui-o em cada pedido. É assim que a IA conversacional em produção funciona. +Agora experimente a mesma sequência aqui. Peça "O meu nome é João" e depois "Qual é o meu nome?" Desta vez ele lembra-se. A diferença é o MessageWindowChatMemory - que mantém o histórico da conversa e inclui esse contexto em cada pedido. É assim que a IA conversacional em produção funciona. -Stateful Chat Demo +Demo Chat Com Estado -*IA lembra-se do seu nome do início da conversa* +*IA lembra-se do seu nome mencionado anteriormente na conversa* Ambos os painéis usam o mesmo modelo GPT-5.2. A única diferença é a memória. Isto torna claro o que a memória traz para a sua aplicação e porque é essencial para casos reais. ## Próximos Passos -**Próximo Módulo:** [02-prompt-engineering - Engenharia de Prompt com GPT-5.2](../02-prompt-engineering/README.md) +**Próximo Módulo:** [02-prompt-engineering - Engenharia de Prompts com GPT-5.2](../02-prompt-engineering/README.md) --- -**Navegação:** [← Anterior: Módulo 00 - Início Rápido](../00-quick-start/README.md) | [Voltar ao Início](../README.md) | [Seguinte: Módulo 02 - Engenharia de Prompt →](../02-prompt-engineering/README.md) +**Navegação:** [← Voltar ao Principal](../README.md) | [Seguinte: Módulo 02 - Engenharia de Prompts →](../02-prompt-engineering/README.md) --- -**Aviso legal**: -Este documento foi traduzido usando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, por favor, tenha em mente que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autoritativa. Para informações críticas, recomenda-se a tradução profissional feita por um ser humano. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. +**Aviso Legal**: +Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes da utilização desta tradução. \ No newline at end of file diff --git a/translations/pt-PT/02-prompt-engineering/README.md b/translations/pt-PT/02-prompt-engineering/README.md index 403b8a4f9..2c0948f7d 100644 --- a/translations/pt-PT/02-prompt-engineering/README.md +++ b/translations/pt-PT/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ -# Módulo 02: Engenharia de Prompts com GPT-5.2 +# Módulo 02: Engenharia de Prompt com GPT-5.2 ## Índice -- [Video Walkthrough](../../../02-prompt-engineering) -- [O que vai aprender](../../../02-prompt-engineering) -- [Pré-requisitos](../../../02-prompt-engineering) -- [Compreensão da Engenharia de Prompts](../../../02-prompt-engineering) -- [Fundamentos da Engenharia de Prompts](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Templates](../../../02-prompt-engineering) -- [Padrões Avançados](../../../02-prompt-engineering) -- [Executar a Aplicação](../../../02-prompt-engineering) -- [Capturas de Ecrã da Aplicação](../../../02-prompt-engineering) -- [Explorando os Padrões](../../../02-prompt-engineering) - - [Baixa vs Alta Diligência](../../../02-prompt-engineering) - - [Execução de Tarefas (Preâmbulos de Ferramentas)](../../../02-prompt-engineering) - - [Código com Auto-reflexão](../../../02-prompt-engineering) - - [Análise Estruturada](../../../02-prompt-engineering) - - [Chat Multi-turno](../../../02-prompt-engineering) - - [Raciocínio Passo-a-Passo](../../../02-prompt-engineering) - - [Saída Constrangida](../../../02-prompt-engineering) -- [O que está realmente a aprender](../../../02-prompt-engineering) -- [Próximos Passos](../../../02-prompt-engineering) - -## Video Walkthrough +- [Demonstração em Vídeo](#demonstração-em-vídeo) +- [O que Vai Aprender](#o-que-vai-aprender) +- [Pré-requisitos](#pré-requisitos) +- [Compreender Engenharia de Prompt](#compreender-engenharia-de-prompt) +- [Fundamentos da Engenharia de Prompt](#fundamentos-da-engenharia-de-prompt) + - [Prompt Zero-Shot](#prompt-zero-shot) + - [Prompt Few-Shot](#prompt-few-shot) + - [Cadeia de Pensamento](#cadeia-de-pensamento) + - [Prompt com Base no Papel](#prompt-com-base-no-papel) + - [Modelos de Prompt](#modelos-de-prompt) +- [Padrões Avançados](#padrões-avançados) +- [Executar a Aplicação](#executar-a-aplicação) +- [Capturas de Ecrã da Aplicação](#capturas-de-ecrã-da-aplicação) +- [Explorar os Padrões](#explorar-os-padrões) + - [Baixo vs Alto Entusiasmo](#baixo-vs-alto-entusiasmo) + - [Execução de Tarefas (Preâmbulos de Ferramentas)](#execução-de-tarefas-preâmbulos-de-ferramentas) + - [Código Auto-Refletente](#código-auto-refletivo) + - [Análise Estruturada](#análise-estruturada) + - [Chat Multi-Turno](#chat-multi-turno) + - [Raciocínio Passo a Passo](#raciocínio-passo-a-passo) + - [Saída Constrangida](#saída-confinada) +- [O que Está a Aprender Realmente](#o-que-está-realmente-a-aprender) +- [Próximos Passos](#passos-seguintes) + +## Demonstração em Vídeo Assista a esta sessão ao vivo que explica como começar com este módulo: -Prompt Engineering with LangChain4j - Live Session +Engenharia de Prompt com LangChain4j - Sessão ao Vivo -## O que vai aprender +## O que Vai Aprender -O diagrama seguinte fornece uma visão geral dos tópicos e competências principais que irá desenvolver neste módulo — desde técnicas de refinamento de prompts até ao fluxo de trabalho passo-a-passo que seguirá. +O diagrama seguinte fornece uma visão geral dos tópicos principais e das competências que vai desenvolver neste módulo — desde técnicas de refinamento de prompt até ao fluxo de trabalho passo a passo que irá seguir. -O que vai aprender +O que Vai Aprender -Nos módulos anteriores, explorou as interações básicas do LangChain4j com os Modelos do GitHub e viu como a memória permite IA conversacional com Azure OpenAI. Agora vamos concentrar-nos em como colocar perguntas — os próprios prompts — usando o GPT-5.2 da Azure OpenAI. A forma como estrutura os seus prompts afeta drasticamente a qualidade das respostas que obtém. Começamos com uma revisão das técnicas fundamentais de prompting, depois avançamos para oito padrões avançados que aproveitam totalmente as capacidades do GPT-5.2. +No módulo anterior, viu como a memória permite a IA conversacional com Azure OpenAI. Agora focamo-nos em como faz perguntas — os próprios prompts — usando o GPT-5.2 do Azure OpenAI. A forma como estrutura os seus prompts afeta drasticamente a qualidade das respostas que obtém. Começamos com uma revisão das técnicas fundamentais de prompting, depois avançamos para oito padrões avançados que tiram pleno proveito das capacidades do GPT-5.2. -Usaremos o GPT-5.2 porque este introduz controlo do raciocínio - pode dizer ao modelo quanto pensamento deve fazer antes de responder. Isso torna diferentes estratégias de prompting mais evidentes e ajuda a entender quando usar cada abordagem. Também beneficiaremos dos limites de taxa mais baixos do Azure para o GPT-5.2 em comparação com os Modelos do GitHub. +Vamos usar o GPT-5.2 porque ele introduz controlo de raciocínio — pode dizer ao modelo quanto deve pensar antes de responder. Isto torna as diferentes estratégias de prompting mais evidentes e ajuda a compreender quando usar cada abordagem. ## Pré-requisitos - Módulo 01 concluído (recursos Azure OpenAI implementados) -- Ficheiro `.env` na diretoria raiz com as credenciais Azure (criado pelo `azd up` no Módulo 01) +- Ficheiro `.env` no diretório raiz com as credenciais Azure (criado pelo `azd up` no Módulo 01) -> **Nota:** Se ainda não concluiu o Módulo 01, siga primeiro as instruções de implementação aí indicadas. +> **Nota:** Se ainda não completou o Módulo 01, siga primeiro as instruções de implementação lá. -## Compreensão da Engenharia de Prompts +## Compreender Engenharia de Prompt -Na sua essência, engenharia de prompts é a diferença entre instruções vagas e instruções precisas, como a comparação abaixo ilustra. +Na sua essência, engenharia de prompt é a diferença entre instruções vagas e instruções precisas, como ilustra a comparação abaixo. -O que é Engenharia de Prompts? +O que é Engenharia de Prompt? -Engenharia de prompts consiste em desenhar texto de entrada que obtém consistentemente os resultados de que precisa. Não é apenas fazer perguntas - é estruturar pedidos para que o modelo entenda exatamente o que quer e como fornecer. +Engenharia de prompt é sobre projetar texto de entrada que consegue consistentemente os resultados que precisa. Não se trata apenas de fazer perguntas — é sobre estruturar pedidos para que o modelo entenda exatamente o que quer e como o deve entregar. -Pense nisso como dar instruções a um colega. "Corrige o erro" é vago. "Corrige a exceção null pointer em UserService.java linha 45 adicionando uma verificação de nulo" é específico. Modelos de linguagem funcionam da mesma forma - especificidade e estrutura são importantes. +Pense nisso como dar instruções a um colega. "Corrige o bug" é vago. "Corrige a exceção null pointer em UserService.java linha 45 adicionando uma verificação de nulo" é específico. Os modelos de linguagem funcionam da mesma forma — especificidade e estrutura são importantes. -O diagrama abaixo mostra como o LangChain4j se encaixa nesta imagem — ligando os seus padrões de prompt ao modelo através dos blocos de construção SystemMessage e UserMessage. +O diagrama abaixo mostra como o LangChain4j se encaixa nesta imagem — ligando os seus padrões de prompt ao modelo através dos blocos construtores SystemMessage e UserMessage. -Como LangChain4j se encaixa +Como o LangChain4j se Encaixa -LangChain4j fornece a infraestrutura — conexões de modelos, memória, e tipos de mensagem — enquanto os padrões de prompt são apenas texto cuidadosamente estruturado que envia através dessa infraestrutura. Os blocos de construção chave são `SystemMessage` (que define o comportamento e papel da IA) e `UserMessage` (que transporta o seu pedido real). +O LangChain4j fornece a infraestrutura — ligações ao modelo, memória e tipos de mensagem — enquanto os padrões de prompt são apenas texto cuidadosamente estruturado que envia através dessa infraestrutura. Os blocos chave são `SystemMessage` (que define o comportamento e papel da IA) e `UserMessage` (que contém o seu pedido real). -## Fundamentos da Engenharia de Prompts +## Fundamentos da Engenharia de Prompt -As cinco técnicas principais mostradas abaixo formam a base da engenharia de prompts eficaz. Cada uma aborda um aspeto diferente de como se comunica com modelos de linguagem. +As cinco técnicas principais mostradas abaixo formam a base da engenharia de prompt eficaz. Cada uma aborda um aspeto diferente de como comunica com modelos de linguagem. -Visão geral dos cinco padrões de Engenharia de Prompts +Visão Geral dos Cinco Padrões de Engenharia de Prompt -Antes de mergulharmos nos padrões avançados deste módulo, vamos rever cinco técnicas fundamentais de prompting. São os blocos de construção que todo engenheiro de prompts deve conhecer. Se já trabalhou no [módulo Introdução rápida](../00-quick-start/README.md#2-prompt-patterns), já os viu em ação — aqui está o quadro conceptual por trás deles. +Antes de mergulhar nos padrões avançados deste módulo, vamos rever cinco técnicas de prompting fundamentais. São os blocos de construção que todos os engenheiros de prompt devem conhecer. -### Zero-Shot Prompting +### Prompt Zero-Shot -A abordagem mais simples: dar ao modelo uma instrução direta sem exemplos. O modelo depende inteiramente do seu treino para entender e executar a tarefa. Isto funciona bem para pedidos diretos onde o comportamento esperado é óbvio. +A abordagem mais simples: dar ao modelo uma instrução direta sem exemplos. O modelo depende inteiramente do seu treino para entender e executar a tarefa. Funciona bem para pedidos simples onde o comportamento esperado é óbvio. -Zero-Shot Prompting +Prompt Zero-Shot -*Instrução direta sem exemplos — o modelo deduz a tarefa apenas a partir da instrução* +*Instrução direta sem exemplos — o modelo infere a tarefa apenas pela instrução* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Resposta: "Positivo" ``` -**Quando usar:** Classificações simples, perguntas diretas, traduções ou qualquer tarefa que o modelo consiga tratar sem orientação adicional. +**Quando usar:** Classificações simples, perguntas diretas, traduções ou qualquer tarefa que o modelo consiga executar sem orientação adicional. -### Few-Shot Prompting +### Prompt Few-Shot -Fornecer exemplos que demonstram o padrão que quer que o modelo siga. O modelo aprende o formato esperado de entrada e saída a partir dos seus exemplos e aplica-o a novas entradas. Isso melhora dramaticamente a consistência em tarefas onde o formato ou comportamento desejado não é óbvio. +Forneça exemplos que demonstrem o padrão que deseja que o modelo siga. O modelo aprende o formato esperado de entrada-saída a partir dos seus exemplos e aplica-o a novas entradas. Isto melhora drasticamente a consistência para tarefas onde o formato ou comportamento desejado não é óbvio. -Few-Shot Prompting +Prompt Few-Shot -*Aprender com exemplos — o modelo identifica o padrão e aplica-o a novas entradas* +*Aprender pelos exemplos — o modelo identifica o padrão e aplica-o a novas entradas* ```java String prompt = """ @@ -114,11 +114,11 @@ String response = model.chat(prompt); **Quando usar:** Classificações personalizadas, formatação consistente, tarefas específicas de domínio ou quando os resultados zero-shot são inconsistentes. -### Chain of Thought +### Cadeia de Pensamento -Pedir ao modelo para mostrar o seu raciocínio passo a passo. Em vez de saltar diretamente para uma resposta, o modelo divide o problema e trabalha cada parte explicitamente. Isso melhora a precisão em matemática, lógica e tarefas de raciocínio em vários passos. +Peça ao modelo para mostrar o seu raciocínio passo a passo. Em vez de saltar diretamente para uma resposta, o modelo divide o problema e trabalha cada parte explicitamente. Isto melhora a precisão em matemática, lógica e tarefas que exigem raciocínio em múltiplos passos. -Prompting Chain of Thought +Prompt Cadeia de Pensamento *Raciocínio passo a passo — dividir problemas complexos em passos lógicos explícitos* @@ -133,15 +133,15 @@ String response = model.chat(prompt); // O modelo mostra: 15 - 8 = 7, depois 7 + 12 = 19 maçãs ``` -**Quando usar:** Problemas matemáticos, quebra-cabeças lógicos, depuração ou qualquer tarefa onde mostrar o processo de raciocínio melhora a precisão e confiança. +**Quando usar:** Problemas matemáticos, enigmas lógicos, debugging ou qualquer tarefa onde mostrar o processo de raciocínio melhora a precisão e confiança. -### Role-Based Prompting +### Prompt com Base no Papel -Definir uma persona ou papel para a IA antes de fazer a sua pergunta. Isso fornece contexto que molda o tom, a profundidade e o foco da resposta. Um "arquiteto de software" dá conselhos diferentes de um "desenvolvedor júnior" ou "auditor de segurança". +Defina uma persona ou papel para a IA antes de fazer a sua pergunta. Isto fornece contexto que molda o tom, profundidade e foco da resposta. Um "arquiteto de software" dá conselhos diferentes de um "programador júnior" ou de um "auditor de segurança". -Role-Based Prompting +Prompt com Base no Papel -*Definir contexto e persona — a mesma pergunta recebe respostas diferentes conforme o papel atribuído* +*Definir contexto e persona — a mesma pergunta recebe uma resposta diferente dependendo do papel atribuído* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Quando usar:** Revisões de código, tutoria, análise específica de domínio ou quando precisa de respostas adaptadas a um nível de especialização ou perspetiva particular. +**Quando usar:** Revisões de código, tutoria, análises específicas de domínio ou quando precisar de respostas adaptadas a um nível de especialização ou perspetiva particular. -### Prompt Templates +### Modelos de Prompt -Criar prompts reutilizáveis com espaços variáveis. Em vez de escrever um prompt novo cada vez, defina um template uma vez e preencha valores diferentes. A classe `PromptTemplate` do LangChain4j facilita isto com a sintaxe `{{variable}}`. +Crie prompts reutilizáveis com espaços variáveis. Em vez de escrever um prompt novo sempre, defina um modelo uma vez e preencha valores diferentes. A classe `PromptTemplate` do LangChain4j facilita isto com a sintaxe `{{variable}}`. -Prompt Templates +Modelos de Prompt -*Prompts reutilizáveis com espaços variáveis — um template, muitos usos* +*Prompts reutilizáveis com espaços variáveis — um modelo, muitos usos* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Quando usar:** Consultas repetidas com entradas diferentes, processamento em lote, construção de fluxos de trabalho AI reutilizáveis ou qualquer cenário onde a estrutura do prompt se mantém mas os dados mudam. +**Quando usar:** Consultas repetidas com entradas diferentes, processamento por lotes, construção de fluxos de trabalho AI reutilizáveis ou qualquer cenário onde a estrutura do prompt se mantém igual mas os dados mudam. --- -Estes cinco fundamentos fornecem uma caixa de ferramentas sólida para a maioria das tarefas de prompting. O resto deste módulo baseia-se neles com **oito padrões avançados** que tiram partido do controlo de raciocínio, autoavaliação e capacidades de saída estruturada do GPT-5.2. +Estes cinco fundamentos dão-lhe uma caixa de ferramentas sólida para a maioria das tarefas de prompting. O resto deste módulo baseia-se neles com **oito padrões avançados** que aproveitam o controlo de raciocínio, autoavaliação e capacidades de saída estruturada do GPT-5.2. ## Padrões Avançados -Com os fundamentos abordados, vamos aos oito padrões avançados que tornam este módulo único. Nem todos os problemas precisam do mesmo método. Algumas perguntas precisam de respostas rápidas, outras de pensamento profundo. Algumas precisam de raciocínio visível, outras só resultados. Cada padrão abaixo está otimizado para um cenário diferente — e o controlo de raciocínio do GPT-5.2 torna as diferenças ainda mais evidentes. +Com os fundamentos cobertos, passemos aos oito padrões avançados que tornam este módulo único. Nem todos os problemas precisam da mesma abordagem. Algumas perguntas precisam de respostas rápidas, outras de pensamento profundo. Algumas precisam de raciocínio visível, outras apenas dos resultados. Cada padrão abaixo é otimizado para um cenário diferente — e o controlo de raciocínio do GPT-5.2 torna as diferenças ainda mais pronunciadas. Oito Padrões de Prompting -*Visão geral dos oito padrões de engenharia de prompts e os seus casos de uso* +*Visão geral dos oito padrões de engenharia de prompt e seus casos de uso* -O GPT-5.2 adiciona outra dimensão a estes padrões: *controlo do raciocínio*. O slider abaixo mostra como pode ajustar o esforço de pensamento do modelo — desde respostas rápidas e diretas a análises profundas e escrutinadas. +O GPT-5.2 adiciona outra dimensão a estes padrões: *controlo de raciocínio*. O deslizador abaixo mostra como pode ajustar o esforço de pensamento do modelo — desde respostas rápidas e diretas a análises profundas e detalhadas. Controlo de Raciocínio com GPT-5.2 -*O controlo de raciocínio do GPT-5.2 permite especificar quanto pensamento o modelo deve fazer — de respostas diretas rápidas a exploração profunda* +*O controlo de raciocínio do GPT-5.2 permite especificar quanto o modelo deve pensar — desde respostas rápidas até exploração profunda* -**Baixa Diligência (Rápido & Focado)** - Para perguntas simples onde quer respostas rápidas e diretas. O modelo faz raciocínio mínimo - no máximo 2 passos. Use para cálculos, pesquisas ou perguntas diretas. +**Baixo Entusiasmo (Rápido & Focado)** - Para perguntas simples onde quer respostas rápidas e diretas. O modelo faz raciocínio mínimo - no máximo 2 passos. Use isto para cálculos, pesquisas ou perguntas diretas. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Explore com GitHub Copilot:** Abra [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) e pergunte: -> - "Qual é a diferença entre padrões de prompting de baixa e alta diligência?" -> - "Como é que as tags XML nos prompts ajudam a estruturar a resposta da IA?" +> - "Qual é a diferença entre os padrões de prompting de baixo entusiasmo e alto entusiasmo?" +> - "Como as etiquetas XML nos prompts ajudam a estruturar a resposta da IA?" > - "Quando devo usar padrões de auto-reflexão vs instrução direta?" -**Alta Diligência (Profundo & Esmiuçado)** - Para problemas complexos onde quer uma análise completa. O modelo explora em detalhe e mostra raciocínio pormenorizado. Use para design de sistemas, decisões arquitetónicas ou pesquisa complexa. +**Alto Entusiasmo (Profundo & Minucioso)** - Para problemas complexos onde quer uma análise abrangente. O modelo explora minuciosamente e mostra raciocínio detalhado. Use isto para design de sistemas, decisões arquitetónicas ou pesquisas complexas. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Execução de Tarefas (Progresso Passo a Passo)** - Para fluxos de trabalho multi-etapas. O modelo fornece um plano inicial, narra cada passo enquanto trabalha, depois dá um resumo. Use para migrações, implementações, ou qualquer processo multi-etapas. +**Execução de Tarefas (Progresso Passo a Passo)** - Para fluxos de trabalho em múltiplos passos. O modelo fornece um plano inicial, narra cada passo conforme trabalha e depois apresenta um resumo. Use isto para migrações, implementações ou qualquer processo com vários passos. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -O prompting Chain-of-Thought pede explicitamente ao modelo que mostre o seu processo de raciocínio, melhorando a precisão para tarefas complexas. A decomposição passo-a-passo ajuda humanos e IA a entenderem a lógica. +O prompting cadeia de pensamento pede explicitamente ao modelo para mostrar o seu processo de raciocínio, melhorando a precisão em tarefas complexas. A decomposição passo a passo ajuda tanto humanos como IA a entenderem a lógica. -> **🤖 Experimente com o Chat do [GitHub Copilot](https://github.com/features/copilot):** Pergunte sobre este padrão: -> - "Como adaptaria o padrão de execução de tarefa para operações de longa duração?" +> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Pergunte sobre este padrão: +> - "Como adaptaria o padrão de execução de tarefas para operações de longa duração?" > - "Quais são as melhores práticas para estruturar preâmbulos de ferramentas em aplicações de produção?" -> - "Como posso capturar e mostrar atualizações intermediárias de progresso numa interface?" +> - "Como captar e mostrar atualizações de progresso intermédias numa interface?" O diagrama abaixo ilustra este fluxo Planear → Executar → Resumir. -Padrão de Execução de Tarefa +Padrão Execução de Tarefas -*Fluxo Planear → Executar → Resumir para tarefas multi-etapas* +*Fluxo Planear → Executar → Resumir para tarefas em múltiplos passos* -**Código com Auto-reflexão** - Para gerar código com qualidade de produção. O modelo gera código seguindo padrões de produção com tratamento adequado de erros. Use ao construir novas funcionalidades ou serviços. +**Código Auto-Refletente** - Para gerar código de qualidade para produção. O modelo gera código seguindo padrões de produção com tratamento de erros adequado. Use isto para criar novas funcionalidades ou serviços. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -O diagrama abaixo mostra este ciclo iterativo de melhoria — gerar, avaliar, identificar pontos fracos, e refinar até o código cumprir padrões de produção. +O diagrama abaixo mostra este ciclo iterativo de melhoria — gerar, avaliar, identificar fraquezas e refinar até o código cumprir os padrões de produção. -Ciclo de Auto-reflexão +Ciclo de Auto-Reflexão *Ciclo iterativo de melhoria - gerar, avaliar, identificar problemas, melhorar, repetir* -**Análise Estruturada** - Para avaliações consistentes. O modelo revê código usando uma estrutura fixa (correção, práticas, desempenho, segurança, manutenção). Use para revisões de código ou avaliações de qualidade. +**Análise Estruturada** - Para avaliações consistentes. O modelo revê código usando uma framework fixa (correção, práticas, desempenho, segurança, manutenção). Use isto para revisões de código ou avaliações de qualidade. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Experimente com o Chat do [GitHub Copilot](https://github.com/features/copilot):** Pergunte sobre análise estruturada: -> - "Como posso personalizar a estrutura de análise para diferentes tipos de revisões de código?" -> - "Qual a melhor forma de analisar e agir programaticamente sobre saídas estruturadas?" -> - "Como garantir níveis de severidade consistentes entre diferentes sessões de revisão?" +> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Pergunte sobre análise estruturada: +> - "Como personalizar a framework de análise para diferentes tipos de revisão de código?" +> - "Qual a melhor forma de analisar e atuar sobre a saída estruturada programaticamente?" +> - "Como garantir níveis de severidade consistentes em diferentes sessões de revisão?" -O diagrama seguinte mostra como esta estrutura organizada categoriza uma revisão de código em categorias consistentes com níveis de severidade. +O diagrama seguinte mostra como esta framework estruturada organiza uma revisão de código em categorias consistentes com níveis de severidade. Padrão de Análise Estruturada -*Estrutura para revisões consistentes de código com níveis de severidade* +*Framework para revisões consistentes de código com níveis de severidade* -**Chat Multi-turno** - Para conversas que precisam de contexto. O modelo lembra as mensagens anteriores e constrói a partir delas. Use para sessões interativas de ajuda ou Q&A complexos. +**Chat Multi-Turno** - Para conversas que precisam de contexto. O modelo lembra mensagens anteriores e constrói sobre elas. Use isto para sessões interativas de ajuda ou Q&A complexas. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -O diagrama abaixo visualiza como o contexto da conversa se acumula a cada troca e como isso se relaciona com o limite de tokens do modelo. +O diagrama abaixo visualiza como o contexto da conversa se acumula a cada turno e como isto se relaciona com o limite de tokens do modelo. Memória de Contexto -*Como o contexto da conversa se acumula ao longo de vários turnos até atingir o limite de tokens* -**Raciocínio Passo a Passo** - Para problemas que requerem lógica visível. O modelo mostra um raciocínio explícito para cada passo. Use isto para problemas matemáticos, enigmas lógicos ou quando precisar compreender o processo de pensamento. +*Como o contexto da conversa se acumula ao longo de múltiplos turnos até atingir o limite de tokens* + +**Raciocínio Passo a Passo** - Para problemas que exigem lógica visível. O modelo mostra raciocínio explícito para cada passo. Use isto para problemas matemáticos, enigmas lógicos ou quando precisar entender o processo de pensamento. ```java String prompt = """ @@ -400,11 +401,10 @@ String response = chatModel.chat(prompt); O diagrama abaixo ilustra como o modelo divide problemas em passos lógicos explícitos e numerados. -Step-by-Step Pattern - -*Dividindo problemas em passos lógicos explícitos* +Padrão Passo a Passo +*Desconstruir problemas em passos lógicos explícitos* -**Saída Constrangida** - Para respostas com requisitos específicos de formato. O modelo segue estritamente as regras de formato e comprimento. Use isto para resumos ou quando precisar de uma estrutura precisa de saída. +**Saída Confinada** - Para respostas com requisitos específicos de formato. O modelo segue rigorosamente as regras de formato e comprimento. Use isto para resumos ou quando precisa de uma estrutura de saída precisa. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -O diagrama seguinte mostra como restrições orientam o modelo a produzir uma saída que adere estritamente ao seu formato e requisitos de comprimento. +O diagrama seguinte mostra como as restrições orientam o modelo a produzir uma saída que cumpre estritamente os seus requisitos de formato e comprimento. -Constrained Output Pattern +Padrão de Saída Confinada -*Impondo requisitos específicos de formato, comprimento e estrutura* +*Impor requisitos específicos de formato, comprimento e estrutura* ## Executar a Aplicação -**Verificar a implementação:** +**Verificar a implantação:** -Assegure-se de que o ficheiro `.env` existe na diretoria raiz com as credenciais Azure (criadas durante o Módulo 01). Execute isto a partir da diretoria do módulo (`02-prompt-engineering/`): +Assegure-se de que o ficheiro `.env` existe no diretório raiz com as credenciais Azure (criado durante o Módulo 01). Execute isto a partir do diretório do módulo (`02-prompt-engineering/`): **Bash:** ```bash @@ -444,23 +444,23 @@ Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Iniciar a aplicação:** -> **Nota:** Se já iniciou todas as aplicações usando `./start-all.sh` a partir da diretoria raiz (conforme descrito no Módulo 01), este módulo já está a correr na porta 8083. Pode pular os comandos de arranque abaixo e ir diretamente para http://localhost:8083. +> **Nota:** Se já tiver iniciado todas as aplicações usando `./start-all.sh` a partir do diretório raiz (conforme descrito no Módulo 01), este módulo já está a correr na porta 8083. Pode ignorar os comandos de arranque abaixo e ir diretamente para http://localhost:8083. **Opção 1: Usar o Spring Boot Dashboard (Recomendado para utilizadores VS Code)** -O contentor dev inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerir todas as aplicações Spring Boot. Pode encontrá-la na Barra de Atividades no lado esquerdo do VS Code (procure o ícone do Spring Boot). +O contentor de desenvolvimento inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerir todas as aplicações Spring Boot. Pode encontrá-la na Barra de Atividade no lado esquerdo do VS Code (procure o ícone Spring Boot). -No Spring Boot Dashboard, pode: +A partir do Spring Boot Dashboard, pode: - Ver todas as aplicações Spring Boot disponíveis no espaço de trabalho - Iniciar/parar aplicações com um clique -- Ver os logs da aplicação em tempo real +- Ver os registos da aplicação em tempo real - Monitorizar o estado da aplicação -Basta clicar no botão de play ao lado de "prompt-engineering" para iniciar este módulo, ou iniciar todos os módulos de uma só vez. +Basta clicar no botão de play junto a "prompt-engineering" para iniciar este módulo, ou iniciar todos os módulos de uma vez. Spring Boot Dashboard -*O Spring Boot Dashboard no VS Code — iniciar, parar e monitorizar todos os módulos a partir de um só local* +*O Spring Boot Dashboard no VS Code — iniciar, parar e monitorizar todos os módulos num só local* **Opção 2: Usar scripts shell** @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Ambos os scripts carregam automaticamente as variáveis de ambiente a partir do ficheiro `.env` na raiz e construirão os JARs se estes não existirem. +Ambos os scripts carregam automaticamente as variáveis de ambiente do ficheiro `.env` da raiz e irão construir os JARs caso não existam. -> **Nota:** Se preferir compilar todos os módulos manualmente antes de iniciar: +> **Nota:** Se preferir construir todos os módulos manualmente antes de iniciar: > > **Bash:** > ```bash @@ -528,81 +528,81 @@ cd ..; .\stop-all.ps1 # Todos os módulos ## Capturas de Ecrã da Aplicação -Aqui está a interface principal do módulo de prompt engineering, onde pode experimentar todos os oito padrões lado a lado. +Aqui está a interface principal do módulo de engenharia de prompts, onde pode experimentar todos os oito padrões lado a lado. Dashboard Home -*O painel principal mostrando todos os 8 padrões de engenharia de prompts com as suas características e casos de uso* +*O painel principal mostrando os 8 padrões de engenharia de prompts com as suas características e casos de uso* ## Explorar os Padrões -A interface web permite experimentar diferentes estratégias de prompting. Cada padrão resolve diferentes problemas - experimente para ver quando cada abordagem se destaca. +A interface web permite-lhe experimentar diferentes estratégias de prompting. Cada padrão resolve problemas diferentes - experimente-os para ver quando cada abordagem sobressai. -> **Nota: Streaming vs Não Streaming** — Cada página de padrão oferece dois botões: **🔴 Resposta por Streaming (Ao Vivo)** e uma opção **Não-streaming**. O streaming usa Server-Sent Events (SSE) para mostrar tokens em tempo real enquanto o modelo os gera, por isso vê o progresso imediatamente. A opção não-streaming espera pela resposta completa antes de a exibir. Para prompts que desencadeiam raciocínio profundo (ex.: Alta Vontade, Código Auto-Refletido), a chamada não-streaming pode demorar muito — por vezes minutos — sem qualquer feedback visível. **Use streaming quando experimentar prompts complexos** para poder ver o modelo a trabalhar e evitar a impressão de que o pedido expirou. +> **Nota: Streaming vs Não Streaming** — Cada página de padrão oferece dois botões: **🔴 Stream Response (Live)** e uma opção **Não streaming**. O streaming usa Server-Sent Events (SSE) para mostrar os tokens em tempo real conforme o modelo os gera, para ver o progresso imediatamente. A opção não streaming espera pela resposta completa antes de a mostrar. Para prompts que desencadeiam raciocínio profundo (ex: Alto Entusiasmo, Código Auto-Refletivo), a chamada não streaming pode demorar muito tempo — por vezes minutos — sem feedback visível. **Use streaming quando experimentar prompts complexos** para ver o modelo a trabalhar e evitar a impressão que o pedido expirou. > -> **Nota: Requisito de Navegador** — A funcionalidade de streaming usa a Fetch Streams API (`response.body.getReader()`) que requer um navegador completo (Chrome, Edge, Firefox, Safari). Não funciona no Simple Browser incorporado no VS Code, pois a sua webview não suporta a API ReadableStream. Se usar o Simple Browser, os botões não-streaming continuam a funcionar normalmente — apenas os botões de streaming são afetados. Abra `http://localhost:8083` num navegador externo para uma experiência completa. +> **Nota: Requisito do Navegador** — A funcionalidade de streaming usa a API Fetch Streams (`response.body.getReader()`) que requer um navegador completo (Chrome, Edge, Firefox, Safari). Não funciona no Simple Browser integrado do VS Code, pois a sua webview não suporta a ReadableStream API. Se usar o Simple Browser, os botões não streaming funcionam normalmente — apenas os botões de streaming são afetados. Abra `http://localhost:8083` num navegador externo para uma experiência completa. -### Baixa vs Alta Vontade +### Baixo vs Alto Entusiasmo -Faça uma pergunta simples como "Qual é 15% de 200?" usando Baixa Vontade. Receberá uma resposta direta e instantânea. Agora peça algo complexo como "Desenha uma estratégia de cache para uma API de elevado tráfego" usando Alta Vontade. Clique em **🔴 Resposta por Streaming (Ao Vivo)** e veja o raciocínio detalhado do modelo aparecer token a token. Mesmo modelo, mesma estrutura de pergunta - mas o prompt indica quanto raciocínio fazer. +Faça uma pergunta simples como "Qual é 15% de 200?" usando Baixo Entusiasmo. Receberá uma resposta direta e instantânea. Agora faça algo complexo como "Desenhe uma estratégia de caching para uma API de alto tráfego" usando Alto Entusiasmo. Clique em **🔴 Stream Response (Live)** e veja o raciocínio detalhado do modelo aparecer token a token. Mesmo modelo, mesma estrutura de pergunta - mas o prompt indica quanto pensar. -### Execução de Tarefas (Preambulares de Ferramentas) +### Execução de Tarefas (Preâmbulos de Ferramentas) -Fluxos de trabalho em vários passos beneficiam de planeamento inicial e narração do progresso. O modelo descreve o que vai fazer, narra cada passo e depois resume os resultados. +Workflows multi-passos beneficiam de planeamento prévio e narração do progresso. O modelo descreve o que vai fazer, narra cada passo e depois sumariza os resultados. -### Código Auto-Refletido +### Código Auto-Refletivo -Experimente "Criar um serviço de validação de email". Em vez de apenas gerar código e parar, o modelo gera, avalia com critérios de qualidade, identifica fraquezas e melhora. Verá o modelo a iterar até o código cumprir os padrões de produção. +Experimente "Criar um serviço de validação de email". Em vez de apenas gerar código e parar, o modelo gera, avalia contra critérios de qualidade, identifica fraquezas e melhora. Vai ver iterar até o código estar apto para produção. ### Análise Estruturada -Revisões de código precisam de frameworks de avaliação consistentes. O modelo analisa o código usando categorias fixas (correção, práticas, desempenho, segurança) com níveis de severidade. +Revisões de código precisam de esquemas de avaliação consistentes. O modelo analisa código usando categorias fixas (correção, práticas, desempenho, segurança) com níveis de severidade. -### Chat Multi-turno +### Chat Multi-Turno -Pergunte "O que é Spring Boot?" e depois imediatamente siga com "Mostra-me um exemplo". O modelo lembra-se da primeira pergunta e dá-lhe um exemplo de Spring Boot específico. Sem memória, essa segunda pergunta seria demasiado vaga. +Pergunte "O que é o Spring Boot?" e logo depois "Mostra-me um exemplo". O modelo lembra a primeira pergunta e dá um exemplo específico de Spring Boot. Sem memória, a segunda pergunta seria demasiado vaga. ### Raciocínio Passo a Passo -Escolha um problema matemático e experimente com Raciocínio Passo a Passo e Baixa Vontade. Baixa vontade dá-lhe só a resposta – rápido mas opaco. O passo a passo mostra-lhe cada cálculo e decisão. +Escolha um problema de matemática e experimente com Raciocínio Passo a Passo e Baixo Entusiasmo. Baixo entusiasmo só dá a resposta - rápido mas opaco. Passo a passo mostra todos os cálculos e decisões. -### Saída Constrangida +### Saída Confinada -Quando precisa de formatos específicos ou contagens de palavras, este padrão impõe aderência estrita. Experimente gerar um resumo com exatamente 100 palavras em formato de pontos. +Quando precisar de formatos específicos ou contagem exata de palavras, este padrão garante estrita conformidade. Experimente gerar um resumo com exatamente 100 palavras em formato de tópico. ## O Que Está Realmente a Aprender **O Esforço de Raciocínio Muda Tudo** -O GPT-5.2 permite controlar o esforço computacional pelos seus prompts. Baixo esforço significa respostas rápidas com exploração mínima. Alto esforço indica que o modelo dedica tempo a pensar profundamente. Está a aprender a ajustar o esforço à complexidade da tarefa - não perca tempo em perguntas simples, mas não se apresse em decisões complexas. +O GPT-5.2 permite controlar o esforço computacional através dos seus prompts. Baixo esforço significa respostas rápidas com exploração mínima. Alto esforço significa que o modelo pensa profundamente. Está a aprender a ajustar o esforço à complexidade da tarefa - não perca tempo em perguntas simples, mas não apresse decisões complexas. **Estrutura Guia o Comportamento** -Reparou nas etiquetas XML nos prompts? Não são decorativas. Os modelos seguem instruções estruturadas de forma mais fiável do que texto livre. Quando precisa de processos multi-etapas ou lógica complexa, a estrutura ajuda o modelo a rastrear onde está e o que vem a seguir. O diagrama abaixo divide um prompt bem estruturado, mostrando como etiquetas como ``, ``, ``, ``, e `` organizam as suas instruções em secções claras. +Reparou nas tags XML nos prompts? Não são decorativas. Os modelos seguem instruções estruturadas com mais fiabilidade que texto livre. Quando precisa de processos multi-passos ou lógica complexa, a estrutura ajuda o modelo a saber onde está e o que vem a seguir. O diagrama abaixo desconstrói um prompt bem-estruturado, mostrando como tags como ``, ``, ``, ``, e `` organizam as suas instruções em secções claras. -Prompt Structure +Estrutura do Prompt -*Anatomia de um prompt bem estruturado com secções claras e organização ao estilo XML* +*Anatomia de um prompt bem-estruturado com secções claras e organização estilo XML* **Qualidade Através da Autoavaliação** -Os padrões auto-refletidos funcionam tornando os critérios de qualidade explícitos. Em vez de esperar que o modelo "faça certo", diz-lhe exatamente o que significa "certo": lógica correta, tratamento de erros, desempenho, segurança. O modelo pode então avaliar a própria saída e melhorar. Isto torna a geração de código num processo - não numa lotaria. +Os padrões auto-refletivos funcionam ao tornar explícitos os critérios de qualidade. Em vez de esperar que o modelo "faça bem", diz-lhe exatamente o que "bem" significa: lógica correta, tratamento de erros, desempenho, segurança. O modelo pode então avaliar a sua própria saída e melhorar. Isto transforma a geração de código numa tarefa controlada. **O Contexto É Finito** -Conversas multi-turno funcionam incluindo histórico de mensagens em cada pedido. Mas há um limite - cada modelo tem uma contagem máxima de tokens. À medida que as conversas crescem, precisará de estratégias para manter o contexto relevante sem atingir esse limite. Este módulo mostra-lhe como funciona a memória; mais tarde aprenderá quando resumir, quando esquecer e quando recuperar. +Conversas multi-turno funcionam incluindo o histórico de mensagens em cada pedido. Mas há um limite - cada modelo tem um máximo de tokens. À medida que as conversas crescem, precisa de estratégias para manter o contexto relevante sem ultrapassar esse limite. Este módulo mostra como funciona a memória; mais tarde aprenderá quando resumir, quando esquecer e quando recuperar. -## Próximos Passos +## Passos Seguintes -**Próximo Módulo:** [03-rag - RAG (Geração Assistida por Recuperação)](../03-rag/README.md) +**Próximo Módulo:** [03-rag - RAG (Geracão Aumentada por Recuperação)](../03-rag/README.md) --- -**Navegação:** [← Anterior: Módulo 01 - Introdução](../01-introduction/README.md) | [Voltar ao Índice](../README.md) | [Seguinte: Módulo 03 - RAG →](../03-rag/README.md) +**Navegação:** [← Anterior: Módulo 01 - Introdução](../01-introduction/README.md) | [Voltar ao Início](../README.md) | [Seguinte: Módulo 03 - RAG →](../03-rag/README.md) --- -**Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos para garantir a precisão, por favor tenha em atenção que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se uma tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes da utilização desta tradução. +**Aviso Legal**: +Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes da utilização desta tradução. \ No newline at end of file diff --git a/translations/pt-PT/03-rag/README.md b/translations/pt-PT/03-rag/README.md index 58b3fa551..44a33ceb7 100644 --- a/translations/pt-PT/03-rag/README.md +++ b/translations/pt-PT/03-rag/README.md @@ -1,144 +1,143 @@ -# Módulo 03: RAG (Geração Aumentada por Recuperação) +# Módulo 03: RAG (Geração com Recuperação Aprimorada) ## Índice -- [Guia em Vídeo](../../../03-rag) -- [O Que Vai Aprender](../../../03-rag) -- [Pré-requisitos](../../../03-rag) -- [Compreender o RAG](../../../03-rag) - - [Que Abordagem RAG Este Tutorial Usa?](../../../03-rag) -- [Como Funciona](../../../03-rag) - - [Processamento de Documentos](../../../03-rag) - - [Criação de Embeddings](../../../03-rag) - - [Pesquisa Semântica](../../../03-rag) - - [Geração de Respostas](../../../03-rag) -- [Executar a Aplicação](../../../03-rag) -- [Usar a Aplicação](../../../03-rag) - - [Enviar um Documento](../../../03-rag) - - [Fazer Perguntas](../../../03-rag) - - [Verificar Referências de Origem](../../../03-rag) - - [Experimentar com Perguntas](../../../03-rag) -- [Conceitos-Chave](../../../03-rag) - - [Estratégia de Divisão em Pedaços](../../../03-rag) - - [Pontuações de Similaridade](../../../03-rag) - - [Armazenamento em Memória](../../../03-rag) - - [Gestão da Janela de Contexto](../../../03-rag) -- [Quando o RAG Importa](../../../03-rag) -- [Próximos Passos](../../../03-rag) - -## Guia em Vídeo +- [Video Explicativo](#video-explicativo) +- [O Que Vai Aprender](#o-que-vai-aprender) +- [Pré-requisitos](#pré-requisitos) +- [Compreendendo o RAG](#compreendendo-o-rag) + - [Qual Abordagem RAG Este Tutorial Usa?](#qual-abordagem-rag-este-tutorial-usa) +- [Como Funciona](#como-funciona) + - [Processamento de Documentos](#processamento-de-documentos) + - [Criação de Embeddings](#criação-de-embeddings) + - [Pesquisa Semântica](#pesquisa-semântica) + - [Geração de Resposta](#geração-de-respostas) +- [Executar a Aplicação](#executar-a-aplicação) +- [Usar a Aplicação](#usar-a-aplicação) + - [Enviar um Documento](#carregar-um-documento) + - [Fazer Perguntas](#colocar-perguntas) + - [Verificar Referências de Fonte](#verificar-referências-das-fontes) + - [Experimentar com Perguntas](#experimente-com-perguntas) +- [Conceitos-Chave](#conceitos-chave) + - [Estratégia de Chunking](#estratégia-de-fragmentação) + - [Pontuações de Similaridade](#pontuações-de-similaridade) + - [Armazenamento na Memória](#armazenamento-em-memória) + - [Gestão da Janela de Contexto](#gestão-da-janela-de-contexto) +- [Quando o RAG Importa](#quando-o-rag-é-importante) +- [Próximos Passos](#próximos-passos) + +## Video Explicativo Assista a esta sessão ao vivo que explica como começar com este módulo: -RAG com LangChain4j - Sessão ao Vivo +RAG with LangChain4j - Live Session ## O Que Vai Aprender -Nos módulos anteriores, aprendeu como ter conversas com IA e estruturar os seus prompts de forma eficaz. Mas há uma limitação fundamental: os modelos de linguagem só sabem o que aprenderam durante o treino. Não conseguem responder a perguntas sobre as políticas da sua empresa, documentação do seu projeto, ou qualquer informação em que não foram treinados. +Nos módulos anteriores, aprendeu a ter conversas com IA e a estruturar os seus prompts de forma eficaz. Mas há uma limitação fundamental: os modelos de linguagem apenas sabem o que aprenderam durante o treino. Eles não conseguem responder a perguntas sobre as políticas da sua empresa, a documentação do seu projeto ou qualquer informação que não tenham sido treinados para conhecer. -O RAG (Geração Aumentada por Recuperação) resolve este problema. Em vez de tentar ensinar ao modelo as suas informações (que é caro e impraticável), dá-lhe a capacidade de pesquisar nos seus documentos. Quando alguém faz uma pergunta, o sistema encontra a informação relevante e inclui-a no prompt. O modelo responde então com base nesse contexto recuperado. +O RAG (Geração com Recuperação Aprimorada) resolve este problema. Em vez de tentar ensinar o modelo com a sua informação (o que é caro e pouco prático), dá-lhe a capacidade de pesquisar nos seus documentos. Quando alguém faz uma pergunta, o sistema encontra informação relevante e inclui-a no prompt. O modelo responde com base nesse contexto recuperado. Pense no RAG como dar ao modelo uma biblioteca de referência. Quando faz uma pergunta, o sistema: 1. **Consulta do Utilizador** - Você faz uma pergunta 2. **Embedding** - Converte a sua pergunta num vetor 3. **Pesquisa Vetorial** - Encontra pedaços de documentos semelhantes -4. **Montagem do Contexto** - Adiciona os pedaços relevantes ao prompt +4. **Montagem do Contexto** - Adiciona pedaços relevantes ao prompt 5. **Resposta** - O LLM gera uma resposta com base no contexto -Isto fundamenta as respostas do modelo nos seus dados reais em vez de depender no conhecimento aprendido ou inventar respostas. +Isto fundamenta as respostas do modelo nos seus dados reais, em vez de depender do conhecimento de treino ou inventar respostas. ## Pré-requisitos -- Completar o [Módulo 00 - Começo Rápido](../00-quick-start/README.md) (para o exemplo Easy RAG referido mais à frente neste módulo) -- Completar o [Módulo 01 - Introdução](../01-introduction/README.md) (recursos Azure OpenAI implementados, incluindo o modelo de embedding `text-embedding-3-small`) -- Ficheiro `.env` na raiz com as credenciais Azure (criado pelo comando `azd up` no Módulo 01) +- Conclusão do [Módulo 01 - Introdução](../01-introduction/README.md) (recursos Azure OpenAI implantados, incluindo o modelo de embedding `text-embedding-3-small`) +- Ficheiro `.env` no diretório raiz com credenciais Azure (criado pelo comando `azd up` no Módulo 01) -> **Nota:** Se ainda não completou o Módulo 01, siga primeiro as instruções de implementação lá descritas. O comando `azd up` implementa tanto o modelo de chat GPT como o modelo de embedding usados neste módulo. +> **Nota:** Se não completou o Módulo 01, siga as instruções de implantação aí primeiro. O comando `azd up` implanta tanto o modelo de chat GPT como o modelo de embedding usado por este módulo. -## Compreender o RAG +## Compreendendo o RAG -O diagrama abaixo ilustra o conceito principal: em vez de depender só dos dados de treino do modelo, o RAG fornece ao modelo uma biblioteca de referência dos seus documentos para consultar antes de gerar cada resposta. +O diagrama abaixo ilustra o conceito principal: em vez de confiar apenas nos dados de treino do modelo, o RAG dá-lhe uma biblioteca de referência dos seus documentos para consultar antes de gerar cada resposta. -O Que é o RAG +What is RAG -*Este diagrama mostra a diferença entre um LLM padrão (que adivinha a partir dos dados de treino) e um LLM potenciado por RAG (que consulta primeiro os seus documentos).* +*Este diagrama mostra a diferença entre um LLM padrão (que tenta adivinhar com base no treino) e um LLM com RAG (que consulta primeiro os seus documentos).* -Aqui está como as peças se ligam de ponta a ponta. A pergunta de um utilizador passa por quatro fases — embedding, pesquisa vetorial, montagem do contexto e geração da resposta — cada uma construindo a anterior: +Aqui está como as peças se ligam end-to-end. A pergunta do utilizador flui por quatro etapas — embedding, pesquisa vetorial, montagem do contexto e geração da resposta — cada uma construindo sobre a anterior: -Arquitetura do RAG +RAG Architecture -*Este diagrama mostra a pipeline RAG de ponta a ponta — uma consulta do utilizador passa por embedding, pesquisa vetorial, montagem do contexto e geração da resposta.* +*Este diagrama mostra o pipeline RAG de ponta a ponta — a pergunta do utilizador flui por embedding, pesquisa vetorial, montagem do contexto e geração da resposta.* -O resto deste módulo explica cada etapa em detalhe, com código que pode executar e modificar. +O resto deste módulo percorre cada etapa em detalhe, com código que pode executar e modificar. -### Que Abordagem RAG Este Tutorial Usa? +### Qual Abordagem RAG Este Tutorial Usa? -LangChain4j oferece três maneiras de implementar RAG, cada uma com um nível diferente de abstração. O diagrama abaixo compara-as lado a lado: +O LangChain4j oferece três formas de implementar RAG, cada uma com um nível diferente de abstração. O diagrama abaixo compara-as lado a lado: -Três Abordagens RAG no LangChain4j +Three RAG Approaches in LangChain4j -*Este diagrama compara as três abordagens RAG do LangChain4j — Easy, Native e Advanced — mostrando os seus componentes principais e quando usar cada uma.* +*Este diagrama compara as três abordagens RAG do LangChain4j — Easy, Native e Advanced — mostrando os seus componentes chave e quando usar cada uma.* | Abordagem | O Que Faz | Compromisso | |---|---|---| -| **Easy RAG** | Liga tudo automaticamente através de `AiServices` e `ContentRetriever`. Anota-se uma interface, liga-se um recuperador, e o LangChain4j trata dos embeddings, da pesquisa e da montagem do prompt nos bastidores. | Código mínimo, mas não vê o que acontece em cada passo. | -| **Native RAG** | Chama diretamente o modelo de embedding, pesquisa na store, constrói o prompt e gera a resposta — um passo explícito de cada vez. | Mais código, mas cada etapa é visível e pode ser modificada. | -| **Advanced RAG** | Usa o framework `RetrievalAugmentor` com transformadores de consultas, routers, reclassificadores e injetores de conteúdo plugáveis para pipelines de produção. | Flexibilidade máxima, mas muito mais complexo. | +| **Easy RAG** | Liga tudo automaticamente através do `AiServices` e `ContentRetriever`. Anota uma interface, liga um recuperador, e o LangChain4j trata do embedding, pesquisa e montagem do prompt nos bastidores. | Código mínimo, mas não vê o que acontece em cada etapa. | +| **Native RAG** | Chama o modelo de embedding, pesquisa na loja, constrói o prompt e gera a resposta — um passo explícito de cada vez. | Mais código, mas cada etapa é visível e modificável. | +| **Advanced RAG** | Usa o framework `RetrievalAugmentor` com transformadores de consulta plugáveis, routers, re-rankers e injetores de conteúdo para pipelines de nível produção. | Máxima flexibilidade, mas com complexidade muito maior. | -**Este tutorial usa a abordagem Native.** Cada etapa da pipeline RAG — embedding da consulta, pesquisa na store vetorial, montagem do contexto e geração da resposta — está escrita explicitamente em [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Isto é intencional: como recurso de aprendizagem, é mais importante que veja e compreenda cada fase do que que o código esteja minimizado. Quando estiver confortável com o funcionamento das peças, pode passar para Easy RAG para protótipos rápidos ou Advanced RAG para sistemas de produção. +**Este tutorial usa a abordagem Native.** Cada passo do pipeline RAG — embedding da consulta, pesquisa na loja vetorial, montagem do contexto e geração da resposta — está explicitamente escrito em [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Isto é intencional: como recurso de aprendizagem, é mais importante que veja e compreenda cada etapa do que que o código esteja minimizado. Quando se sentir confortável com a montagem das peças, pode passar para Easy RAG para protótipos rápidos ou Advanced RAG para sistemas de produção. -> **💡 Já viu o Easy RAG em ação?** O [módulo Começo Rápido](../00-quick-start/README.md) inclui um exemplo de Perguntas e Respostas com Documentos ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) que usa a abordagem Easy RAG — o LangChain4j trata automaticamente dos embeddings, da pesquisa e da montagem dos prompts. Este módulo dá o passo seguinte ao abrir essa pipeline para que possa ver e controlar cada fase por si próprio. +> **💡 Curioso sobre Easy RAG?** O LangChain4j também oferece uma abordagem *Easy RAG* onde `AiServices` e um `ContentRetriever` tratam automaticamente do embedding, pesquisa e montagem do prompt. Este módulo escolhe o caminho mais explícito — abrir o pipeline para que possa ver e controlar cada etapa. -O diagrama abaixo mostra a pipeline Easy RAG desse exemplo do Começo Rápido. Note como `AiServices` e `EmbeddingStoreContentRetriever` escondem toda a complexidade — carregue um documento, ligue um recuperador e obtenha respostas. A abordagem Native deste módulo abre cada um destes passos ocultos: +O diagrama abaixo mostra o pipeline Easy RAG. Repare como `AiServices` e `EmbeddingStoreContentRetriever` ocultam toda a complexidade — você carrega um documento, liga um recuperador e obtém respostas. A abordagem Native neste módulo abre cada um desses passos ocultos: -Pipeline Easy RAG - LangChain4j +Easy RAG Pipeline - LangChain4j -*Este diagrama mostra a pipeline Easy RAG de `SimpleReaderDemo.java`. Compare com a abordagem Native usada neste módulo: o Easy RAG esconde o embedding, recuperação e montagem do prompt atrás de `AiServices` e `ContentRetriever` — carrega um documento, liga um recuperador e obtém respostas. A abordagem Native neste módulo abre essa pipeline para que chame cada etapa (embed, pesquisar, montar contexto, gerar) por si, dando-lhe total visibilidade e controlo.* +*Este diagrama mostra o pipeline Easy RAG. Compare com a abordagem Native usada neste módulo: o Easy RAG oculta o embedding, a recuperação e a montagem do prompt atrás de `AiServices` e `ContentRetriever` — carrega um documento, liga um recuperador e obtém respostas. A abordagem Native deste módulo abre esse pipeline para que chame cada etapa (embed, pesquisa, monta contexto, gera) sozinho, dando-lhe total visibilidade e controlo.* ## Como Funciona -A pipeline RAG deste módulo divide-se em quatro fases que correm em sequência cada vez que um utilizador faz uma pergunta. Primeiro, um documento enviado é **analisado e dividido em pedaços** geríveis. Esses pedaços são depois convertidos em **embeddings vetoriais** e armazenados para que possam ser comparados matematicamente. Quando chega uma consulta, o sistema realiza uma **pesquisa semântica** para encontrar os pedaços mais relevantes e finalmente passa-os como contexto ao LLM para a **geração da resposta**. As secções abaixo explicam cada etapa com o código e diagramas reais. Vamos ver o primeiro passo. +O pipeline RAG neste módulo divide-se em quatro etapas que correm em sequência sempre que um utilizador faz uma pergunta. Primeiro, um documento enviado é **analisado e dividido em pedaços** geríveis. Esses pedaços são depois convertidos em **embeddings vetoriais** e armazenados para poderem ser comparados matematicamente. Quando chega uma consulta, o sistema executa uma **pesquisa semântica** para encontrar os pedaços mais relevantes e, finalmente, passa esses pedaços como contexto ao LLM para a **geração da resposta**. As secções abaixo percorrem cada etapa com o código e diagramas reais. Vamos ver o primeiro passo. ### Processamento de Documentos [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Quando envia um documento, o sistema analisa-o (PDF ou texto simples), anexa metadados, como o nome do ficheiro, e depois divide-o em pedaços — partes mais pequenas que cabem confortavelmente na janela de contexto do modelo. Esses pedaços sobrepõem-se ligeiramente para não perder contexto nas fronteiras. +Quando envia um documento, o sistema faz o parsing (PDF ou texto simples), anexa metadados como o nome do ficheiro e depois divide-o em pedaços — peças menores que cabem confortavelmente na janela de contexto do modelo. Esses pedaços se sobrepõem ligeiramente para não perder contexto nas fronteiras. ```java -// Analise o ficheiro carregado e envolva-o num Documento LangChain4j +// Analisar o ficheiro carregado e encapsulá-lo num Documento LangChain4j Document document = Document.from(content, metadata); -// Dividir em fragmentos de 300 tokens com uma sobreposição de 30 tokens +// Dividir em pedaços de 300 tokens com uma sobreposição de 30 tokens DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -O diagrama abaixo mostra como isto funciona visualmente. Note como cada pedaço partilha alguns tokens com os vizinhos — a sobreposição de 30 tokens assegura que nenhum contexto importante se perde nas junções: +O diagrama abaixo mostra como isto funciona visualmente. Repare como cada pedaço partilha alguns tokens com os vizinhos — a sobreposição de 30 tokens assegura que nenhum contexto importante fique entre as fendas: -Divisão em Pedaços de Documento +Document Chunking -*Este diagrama mostra um documento a ser dividido em pedaços de 300 tokens com 30 tokens de sobreposição, preservando o contexto nas fronteiras dos pedaços.* +*Este diagrama mostra um documento a ser separado em pedaços de 300 tokens com sobreposição de 30 tokens, preservando o contexto nas fronteiras dos pedaços.* -> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) e pergunte: -> - "Como é que o LangChain4j divide documentos em pedaços e por que é que a sobreposição é importante?" -> - "Qual é o tamanho ótimo dos pedaços para diferentes tipos de documentos e por quê?" -> - "Como tratar documentos em várias línguas ou com formatações especiais?" +> **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) e pergunte: +> - "Como o LangChain4j divide documentos em pedaços e por que a sobreposição é importante?" +> - "Qual é o tamanho ótimo dos pedaços para diferentes tipos de documentos e porquê?" +> - "Como lidar com documentos em múltiplas línguas ou com formatação especial?" ### Criação de Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Cada pedaço é convertido numa representação numérica chamada embedding — essencialmente um sistema que converte significado em números. O modelo de embedding não é "inteligente" como um modelo de chat; não consegue seguir instruções, raciocinar ou responder perguntas. O que pode fazer é mapear texto num espaço matemático onde significados semelhantes ficam próximos — “carro” perto de “automóvel”, “política de reembolso” perto de “devolver o meu dinheiro”. Pense num modelo de chat como uma pessoa com quem pode conversar; um modelo de embedding é um sistema de arquivo ultra eficaz. +Cada pedaço é convertido numa representação numérica chamada embedding — essencialmente um conversor de significado para números. O modelo de embedding não é "inteligente" como um modelo de chat; não consegue seguir instruções, raciocinar ou responder perguntas. O que ele pode fazer é mapear texto num espaço matemático onde significados semelhantes ficam próximos — "carro" perto de "automóvel", "política de reembolso" perto de "devolver o meu dinheiro". Pense num modelo de chat como uma pessoa com quem pode falar; um modelo de embedding é um sistema de arquivamento ultra eficiente. -O diagrama abaixo visualiza este conceito — o texto entra, saem vetores numéricos, e significados semelhantes produzem vetores próximos: +O diagrama abaixo visualiza este conceito — entra texto, saem vetores numéricos, e significados semelhantes produzem vetores próximos: -Conceito do Modelo de Embedding +Embedding Model Concept -*Este diagrama mostra como um modelo de embedding converte texto em vetores numéricos, colocando significados semelhantes — como “carro” e “automóvel” — próximos no espaço vetorial.* +*Este diagrama mostra como um modelo de embedding converte texto em vetores numéricos, colocando significados semelhantes — como "carro" e "automóvel" — próximos um do outro no espaço vetorial.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -O diagrama de classes abaixo mostra os dois fluxos separados numa pipeline RAG e as classes LangChain4j que os implementam. O **fluxo de ingestão** (corre uma vez na altura do upload) divide o documento, cria embeddings dos pedaços, e armazena-os via `.addAll()`. O **fluxo de consulta** (corre cada vez que o utilizador pergunta) cria o embedding da pergunta, pesquisa na store via `.search()`, e passa o contexto combinado ao modelo de chat. Ambos os fluxos encontram-se na interface partilhada `EmbeddingStore`: +O diagrama de classes abaixo mostra os dois fluxos separados num pipeline RAG e as classes LangChain4j que os implementam. O **fluxo de ingestão** (executado uma vez no momento do upload) divide o documento, faz embedding dos pedaços e armazena-os via `.addAll()`. O **fluxo de consulta** (executado cada vez que um utilizador pergunta) faz embedding da pergunta, pesquisa na loja via `.search()`, e passa o contexto encontrado ao modelo de chat. Ambos os fluxos partilham a interface `EmbeddingStore`: -Classes RAG do LangChain4j +LangChain4j RAG Classes -*Este diagrama mostra os dois fluxos numa pipeline RAG — ingestão e consulta — e como se ligam através de uma EmbeddingStore partilhada.* +*Este diagrama mostra os dois fluxos num pipeline RAG — ingestão e consulta — e como se ligam através de um EmbeddingStore partilhado.* -Quando os embeddings são armazenados, conteúdos semelhantes agrupam-se naturalmente no espaço vetorial. A visualização abaixo mostra como documentos sobre tópicos relacionados acabam como pontos próximos, o que torna possível a pesquisa semântica: +Uma vez armazenados os embeddings, conteúdos semelhantes naturalmente agrupam-se no espaço vetorial. A visualização abaixo mostra como documentos sobre tópicos relacionados acabam como pontos próximos, que é o que torna possível a pesquisa semântica: -Espaço de Embeddings Vetoriais +Vector Embeddings Space -*Esta visualização mostra como documentos relacionados agrupam-se no espaço vetorial 3D, com tópicos como Documentação Técnica, Regras de Negócio e FAQs formando grupos distintos.* +*Esta visualização mostra como documentos relacionados agrupam-se em espaço vetorial 3D, com tópicos como Documentação Técnica, Regras de Negócio e FAQ formando grupos distintos.* -Quando um utilizador pesquisa, o sistema segue quatro passos: embedar os documentos uma vez, embedar a consulta a cada pesquisa, comparar o vetor da consulta contra todos os vetores armazenados usando similaridade cosseno, e devolver os top-K pedaços com melhor pontuação. O diagrama abaixo mostra cada passo e as classes LangChain4j envolvidas: +Quando um utilizador pesquisa, o sistema segue quatro passos: embedding dos documentos uma vez, embedding da consulta a cada pesquisa, comparação do vetor da consulta contra todos os vetores armazenados usando similaridade do cosseno, e devolve os top-K pedaços com maior pontuação. O diagrama abaixo percorre cada etapa e as classes LangChain4j envolvidas: -Passos da Pesquisa por Embedding +Embedding Search Steps -*Este diagrama mostra o processo de pesquisa por embedding em quatro passos: embedar documentos, embedar a consulta, comparar vetores com similaridade cosseno e devolver os resultados top-K.* +*Este diagrama mostra o processo de pesquisa por embedding em quatro passos: embed dos documentos, embed da consulta, comparação dos vetores pela similaridade do cosseno, e retorno dos top-K resultados.* ### Pesquisa Semântica [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Quando faz uma pergunta, a sua questão também se converte numa embedding. O sistema compara o embedding da sua pergunta contra todos os embeddings dos pedaços do documento. Encontra os pedaços com os significados mais semelhantes — não só correspondência de palavras-chave, mas verdadeira semelhança semântica. +Quando faz uma pergunta, a sua questão também é transformada num embedding. O sistema compara o embedding da sua pergunta contra os embeddings de todos os pedaços dos documentos. Ele encontra os pedaços com os significados mais semelhantes — não apenas correspondência de palavras-chave, mas similaridade semântica real. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -O diagrama abaixo contrasta a pesquisa semântica com a pesquisa tradicional por palavras-chave. Uma pesquisa por palavra-chave de “veículo” não encontra um pedaço sobre “carros e camiões”, mas a pesquisa semântica percebe que significam o mesmo e devolve-o como uma correspondência com alta pontuação: +O diagrama abaixo contrasta a pesquisa semântica com a pesquisa tradicional por palavra-chave. Uma pesquisa por palavra-chave para "veículo" não encontra um pedaço sobre "carros e camiões", mas a pesquisa semântica entende que significam a mesma coisa e retorna isso como resultado de alta pontuação: -Pesquisa Semântica +Semantic Search -*Este diagrama compara a pesquisa baseada em palavras-chave com a pesquisa semântica, mostrando como esta última recupera conteúdo conceitualmente relacionado mesmo quando as palavras-chave exatas diferem.* -Por baixo, a similaridade é medida usando similaridade cosseno — basicamente a perguntar "estes dois vetores apontam na mesma direção?" Dois fragmentos podem usar palavras completamente diferentes, mas se significarem a mesma coisa, os seus vetores apontam na mesma direção e a pontuação fica próxima de 1.0: +*Este diagrama compara pesquisa baseada em palavras-chave com pesquisa semântica, mostrando como a pesquisa semântica recupera conteúdo conceitualmente relacionado mesmo quando as palavras-chave exatas diferem.* -Similaridade Cosseno +Nos bastidores, a similaridade é medida usando similaridade do cosseno — basicamente perguntando "estes dois vetores apontam para a mesma direção?" Dois pedaços podem usar palavras completamente diferentes, mas se significam a mesma coisa os seus vetores apontam na mesma direção e a pontuação é próxima de 1.0: -*Este diagrama ilustra a similaridade cosseno como o ângulo entre vetores de incorporação — vetores mais alinhados obtêm uma pontuação próxima de 1.0, indicando maior similaridade semântica.* +Cosine Similarity +*Este diagrama ilustra a similaridade do cosseno como o ângulo entre vetores de incorporação — vetores mais alinhados pontuam mais perto de 1.0, indicando maior similaridade semântica.* > **🤖 Experimente com o [GitHub Copilot](https://github.com/features/copilot) Chat:** Abra [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) e pergunte: -> - "Como funciona a pesquisa de similaridade com incorporações e o que determina a pontuação?" -> - "Que limiar de similaridade devo usar e como isso afeta os resultados?" -> - "Como lidar com casos onde nenhum documento relevante é encontrado?" +> - "Como funciona a pesquisa de similaridade com embeddings e o que determina a pontuação?" +> - "Que limiar de similaridade devo usar e como ele afeta os resultados?" +> - "Como lidar com casos em que nenhum documento relevante é encontrado?" -### Geração de Resposta +### Geração de Respostas [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Os fragmentos mais relevantes são montados numa prompt estruturada que inclui instruções explícitas, o contexto recuperado e a pergunta do utilizador. O modelo lê esses fragmentos específicos e responde com base nessa informação — só pode usar o que está à sua frente, o que previne fabulações. +Os fragmentos mais relevantes são reunidos num prompt estruturado que inclui instruções explícitas, o contexto recuperado e a pergunta do utilizador. O modelo lê esses fragmentos específicos e responde com base nessa informação — pode usar apenas o que está à sua frente, o que evita alucinações. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -O diagrama abaixo mostra esta montagem em ação — os fragmentos com pontuação mais alta do passo de pesquisa são inseridos no template da prompt, e o `OpenAiOfficialChatModel` gera uma resposta fundamentada: +O diagrama abaixo mostra esta montagem em ação — os fragmentos com as melhores pontuações da etapa de pesquisa são inseridos no modelo de prompt, e o `OpenAiOfficialChatModel` gera uma resposta fundamentada: -Montagem de Contexto +Context Assembly -*Este diagrama mostra como os fragmentos com melhor pontuação são montados numa prompt estruturada, permitindo que o modelo gere uma resposta fundamentada nos seus dados.* +*Este diagrama mostra como os fragmentos com melhor pontuação são montados num prompt estruturado, permitindo ao modelo gerar uma resposta fundamentada a partir dos seus dados.* ## Executar a Aplicação -**Verificar a implantação:** +**Verifique a implantação:** -Certifique-se de que o ficheiro `.env` existe na pasta raiz com as credenciais Azure (criadas durante o Módulo 01). Execute isto da pasta do módulo (`03-rag/`): +Certifique-se de que o ficheiro `.env` existe no diretório raiz com as credenciais Azure (criadas durante o Módulo 01). Execute isto a partir do diretório do módulo (`03-rag/`): **Bash:** ```bash @@ -259,29 +258,29 @@ cat ../.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Iniciar a aplicação:** +**Inicie a aplicação:** -> **Nota:** Se já iniciou todas as aplicações usando `./start-all.sh` da pasta raiz (como descrito no Módulo 01), este módulo já está a correr na porta 8081. Pode saltar os comandos de arranque abaixo e ir diretamente para http://localhost:8081. +> **Nota:** Se já iniciou todas as aplicações usando `./start-all.sh` a partir do diretório raiz (conforme descrito no Módulo 01), este módulo já está a correr na porta 8081. Pode saltar os comandos de início abaixo e aceder diretamente a http://localhost:8081. -**Opção 1: Usar o Spring Boot Dashboard (Recomendado para utilizadores VS Code)** +**Opção 1: Usar o Spring Boot Dashboard (Recomendado para utilizadores do VS Code)** -O contentor de desenvolvimento inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerir todas as aplicações Spring Boot. Pode encontrá-la na Barra de Atividades do lado esquerdo do VS Code (procure o ícone Spring Boot). +O container de desenvolvimento inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerir todas as aplicações Spring Boot. Pode encontrá-la na Barra de Actividades à esquerda do VS Code (procure o ícone do Spring Boot). -No Spring Boot Dashboard pode: +A partir do Spring Boot Dashboard pode: - Ver todas as aplicações Spring Boot disponíveis no workspace -- Iniciar/parar aplicações com um único clique -- Ver logs das aplicações em tempo real -- Monitorizar o estado das aplicações +- Iniciar/parar aplicações com um clique +- Visualizar logs da aplicação em tempo real +- Monitorizar o estado da aplicação Basta clicar no botão de play ao lado de "rag" para iniciar este módulo, ou iniciar todos os módulos de uma vez. Spring Boot Dashboard -*Esta captura mostra o Spring Boot Dashboard no VS Code, onde pode iniciar, parar e monitorizar aplicações visualmente.* +*Esta captura de ecrã mostra o Spring Boot Dashboard no VS Code, onde pode iniciar, parar e monitorizar aplicações visualmente.* **Opção 2: Usar scripts shell** -Iniciar todas as aplicações web (módulos 01-04): +Inicie todas as aplicações web (módulos 01-04): **Bash:** ```bash @@ -295,7 +294,7 @@ cd .. # A partir do diretório raiz .\start-all.ps1 ``` -Ou iniciar apenas este módulo: +Ou inicie só este módulo: **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Ambos os scripts carregam automaticamente as variáveis de ambiente do ficheiro `.env` da raiz e irão construir os JARs se não existirem. +Ambos os scripts carregam automaticamente as variáveis de ambiente do ficheiro `.env` raiz e irão compilar os JARs se não existirem. -> **Nota:** Se preferir construir todos os módulos manualmente antes de iniciar: +> **Nota:** Se preferir compilar todos os módulos manualmente antes de iniciar: > > **Bash:** > ```bash @@ -345,85 +344,85 @@ cd ..; .\stop-all.ps1 # Todos os módulos ## Usar a Aplicação -A aplicação fornece uma interface web para carregamento de documentos e realização de perguntas. +A aplicação fornece uma interface web para upload de documentos e colocação de perguntas. -Interface da Aplicação RAG +RAG Application Interface -*Esta captura mostra a interface da aplicação RAG onde pode carregar documentos e colocar perguntas.* +*Esta captura de ecrã mostra a interface da aplicação RAG onde carrega documentos e coloca perguntas.* ### Carregar um Documento -Comece por carregar um documento - ficheiros TXT funcionam melhor para testes. Está disponível um `sample-document.txt` neste diretório que contém informações sobre funcionalidades do LangChain4j, implementação RAG e boas práticas - perfeito para testar o sistema. +Comece por carregar um documento — ficheiros TXT funcionam melhor para testes. Um `sample-document.txt` é fornecido neste diretório e contém informação sobre as funcionalidades LangChain4j, implementação RAG e melhores práticas — perfeito para testar o sistema. -O sistema processa o seu documento, divide-o em fragmentos e cria incorporações para cada fragmento. Isto acontece automaticamente ao carregar. +O sistema processa o seu documento, divide-o em fragmentos e cria embeddings para cada fragmento. Isto acontece automaticamente quando faz o upload. ### Colocar Perguntas -Agora faça perguntas específicas sobre o conteúdo do documento. Tente algo factual que esteja claramente indicado no documento. O sistema pesquisa os fragmentos relevantes, inclui-os na prompt e gera a resposta. +Agora coloque perguntas específicas sobre o conteúdo do documento. Experimente algo factual que esteja claramente declarado no documento. O sistema procura fragmentos relevantes, inclui-os no prompt e gera uma resposta. -### Verificar Referências de Fonte +### Verificar Referências das Fontes -Note que cada resposta inclui referências com pontuações de similaridade. Estas pontuações (de 0 a 1) mostram quão relevante foi cada fragmento para a sua pergunta. Pontuações mais altas significam melhores correspondências. Isto permite-lhe verificar a resposta relativamente ao material fonte. +Note que cada resposta inclui referências das fontes com pontuações de similaridade. Estas pontuações (de 0 a 1) mostram quão relevante foi cada fragmento para a sua pergunta. Pontuações mais altas significam melhores correspondências. Isto permite-lhe verificar a resposta em relação ao material de origem. -Resultados da Consulta RAG +RAG Query Results -*Esta captura mostra os resultados da consulta com a resposta gerada, referências de fonte e pontuações de relevância para cada fragmento recuperado.* +*Esta captura de ecrã mostra resultados de consultas com a resposta gerada, referências das fontes e pontuações de relevância para cada fragmento recuperado.* -### Experimente Perguntas +### Experimente com Perguntas Experimente diferentes tipos de perguntas: - Factos específicos: "Qual é o tema principal?" -- Comparações: "Qual é a diferença entre X e Y?" +- Comparações: "Qual a diferença entre X e Y?" - Resumos: "Resuma os pontos chave sobre Z" -Observe como as pontuações de relevância mudam consoante o quão bem a sua pergunta corresponde ao conteúdo do documento. +Observe como as pontuações de relevância mudam com base na correspondência da sua pergunta com o conteúdo do documento. ## Conceitos-Chave -### Estratégia de Particionamento +### Estratégia de Fragmentação -Os documentos são divididos em fragmentos de 300 tokens com 30 tokens de sobreposição. Este equilíbrio garante que cada fragmento tem contexto suficiente para ser significativo, mantendo-os pequenos o suficiente para incluir vários fragmentos numa prompt. +Os documentos são divididos em fragmentos de 300 tokens com 30 tokens de sobreposição. Este equilíbrio assegura que cada fragmento tem contexto suficiente para ser significativo e permanece pequeno o suficiente para incluir múltiplos fragmentos num prompt. ### Pontuações de Similaridade -Cada fragmento recuperado vem com uma pontuação de similaridade entre 0 e 1 que indica quão próximo corresponde à pergunta do utilizador. O diagrama abaixo visualiza as faixas de pontuação e como o sistema as usa para filtrar resultados: +Cada fragmento recuperado vem com uma pontuação de similaridade entre 0 e 1 que indica o quão próximo está da pergunta do utilizador. O diagrama abaixo visualiza os intervalos de pontuação e como o sistema os usa para filtrar resultados: -Pontuações de Similaridade +Similarity Scores -*Este diagrama mostra faixas de pontuação de 0 a 1, com um limiar mínimo de 0.5 que filtra fragmentos irrelevantes.* +*Este diagrama mostra intervalos de pontuações entre 0 e 1, com um limiar mínimo de 0.5 que filtra fragmentos irrelevantes.* As pontuações variam de 0 a 1: - 0.7-1.0: Altamente relevante, correspondência exata - 0.5-0.7: Relevante, bom contexto -- Abaixo de 0.5: Filtrado, demasiado dissemelhante +- Abaixo de 0.5: Filtrado, demasiado dissimilar O sistema só recupera fragmentos acima do limiar mínimo para garantir qualidade. -As incorporações funcionam bem quando os significados agrupam-se claramente, mas têm pontos cegos. O diagrama abaixo mostra os modos comuns de falha — fragmentos grandes demais produzem vetores confusos, fragmentos pequenos demais carecem de contexto, termos ambíguos apontam para múltiplos grupos, e pesquisas por correspondência exata (IDs, números de peça) não funcionam com incorporações: +Embeddings funcionam bem quando o significado agrupa-se claramente, mas têm pontos cegos. O diagrama abaixo mostra os modos comuns de falha — fragmentos demasiado grandes produzem vetores imprecisos, fragmentos demasiado pequenos carecem de contexto, termos ambíguos apontam para múltiplos agrupamentos, e pesquisas de correspondência exata (IDs, números de peça) não funcionam de todo com embeddings: -Modos de Falha de Incorporações +Embedding Failure Modes -*Este diagrama mostra modos comuns de falha nas incorporações: fragmentos muito grandes, fragmentos muito pequenos, termos ambíguos que apontam para clusters múltiplos e pesquisas por correspondência exata como IDs.* +*Este diagrama mostra modos comuns de falha em embeddings: fragmentos demasiado grandes, fragmentos demasiado pequenos, termos ambíguos que apontam para múltiplos agrupamentos, e pesquisas de correspondência exata como IDs.* ### Armazenamento em Memória -Este módulo usa armazenamento em memória para simplicidade. Ao reiniciar a aplicação, os documentos carregados são perdidos. Sistemas de produção usam bases de dados vetoriais persistentes como Qdrant ou Azure AI Search. +Este módulo usa armazenamento em memória pela simplicidade. Quando reinicia a aplicação, os documentos carregados são perdidos. Sistemas em produção usam bases de dados vetoriais persistentes como Qdrant ou Azure AI Search. ### Gestão da Janela de Contexto -Cada modelo tem uma janela de contexto máxima. Não pode incluir todos os fragmentos de um documento grande. O sistema recupera os N fragmentos mais relevantes (padrão 5) para manter-se dentro dos limites e fornecer contexto suficiente para respostas precisas. +Cada modelo tem uma janela de contexto máxima. Não pode incluir todos os fragmentos de um documento grande. O sistema recupera os N fragmentos mais relevantes (padrão 5) para manter-se dentro dos limites enquanto fornece contexto suficiente para respostas precisas. -## Quando o RAG Importa +## Quando o RAG é Importante -RAG não é sempre a abordagem certa. O guia de decisão abaixo ajuda a determinar quando o RAG adiciona valor versus quando abordagens mais simples — como incluir conteúdo diretamente na prompt ou confiar no conhecimento embutido do modelo — são suficientes: +RAG não é sempre o método adequado. O guia decisório abaixo ajuda a determinar quando o RAG acrescenta valor versus quando abordagens mais simples — como incluir o conteúdo diretamente no prompt ou confiar no conhecimento incorporado do modelo — são suficientes: -Quando Usar RAG +When to Use RAG -*Este diagrama mostra um guia de decisão para quando o RAG acrescenta valor versus quando abordagens mais simples são suficientes.* +*Este diagrama mostra um guia decisório para quando o RAG acrescenta valor versus quando abordagens mais simples são suficientes.* ## Próximos Passos -**Próximo Módulo:** [04-tools - Agentes de IA com Ferramentas](../04-tools/README.md) +**Próximo Módulo:** [04-tools - Agentes AI com Ferramentas](../04-tools/README.md) --- @@ -433,5 +432,5 @@ RAG não é sempre a abordagem certa. O guia de decisão abaixo ajuda a determin **Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos por garantir a precisão, por favor tenha em conta que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte oficial. Para informações críticas, recomenda-se a tradução profissional por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações erradas decorrentes do uso desta tradução. +Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes da utilização desta tradução. \ No newline at end of file diff --git a/translations/pt-PT/04-tools/README.md b/translations/pt-PT/04-tools/README.md index ac40df2c8..b39a14f6c 100644 --- a/translations/pt-PT/04-tools/README.md +++ b/translations/pt-PT/04-tools/README.md @@ -2,83 +2,83 @@ ## Índice -- [Passeio em Vídeo](../../../04-tools) -- [O Que Vai Aprender](../../../04-tools) -- [Pré-requisitos](../../../04-tools) -- [Compreender Agentes de IA com Ferramentas](../../../04-tools) -- [Como Funciona a Chamada de Ferramentas](../../../04-tools) - - [Definições de Ferramentas](../../../04-tools) - - [Tomada de Decisão](../../../04-tools) - - [Execução](../../../04-tools) - - [Geração de Resposta](../../../04-tools) - - [Arquitetura: Auto-Wiring Spring Boot](../../../04-tools) -- [Encadeamento de Ferramentas](../../../04-tools) -- [Executar a Aplicação](../../../04-tools) -- [Utilizar a Aplicação](../../../04-tools) - - [Experimente o Uso Simples de Ferramentas](../../../04-tools) - - [Teste o Encadeamento de Ferramentas](../../../04-tools) - - [Veja o Fluxo da Conversa](../../../04-tools) - - [Experimente Diferentes Pedidos](../../../04-tools) -- [Conceitos-Chave](../../../04-tools) - - [Padrão ReAct (Raciocinar e Agir)](../../../04-tools) - - [As Descrições das Ferramentas São Importantes](../../../04-tools) - - [Gestão de Sessões](../../../04-tools) - - [Tratamento de Erros](../../../04-tools) -- [Ferramentas Disponíveis](../../../04-tools) -- [Quando Usar Agentes Baseados em Ferramentas](../../../04-tools) -- [Ferramentas vs RAG](../../../04-tools) -- [Próximos Passos](../../../04-tools) - -## Passeio em Vídeo - -Assista a esta sessão ao vivo que explica como começar com este módulo: - -Agentes de IA com Ferramentas e MCP - Sessão Ao Vivo - -## O Que Vai Aprender - -Até agora, aprendeu como ter conversas com IA, estruturar prompts de forma eficaz e fundamentar respostas nos seus documentos. Mas há ainda uma limitação fundamental: os modelos de linguagem só conseguem gerar texto. Não podem verificar o tempo, fazer cálculos, consultar bases de dados nem interagir com sistemas externos. - -As ferramentas mudam isso. Ao dar ao modelo acesso a funções que pode chamar, transforma-o de gerador de texto num agente que pode tomar ações. O modelo decide quando precisa de uma ferramenta, qual deve usar e que parâmetros deve passar. O seu código executa a função e devolve o resultado. O modelo incorpora esse resultado na sua resposta. +- [Video Walkthrough](#video-walkthrough) +- [O que vais aprender](#o-que-vais-aprender) +- [Pré-requisitos](#pré-requisitos) +- [Compreender Agentes de IA com Ferramentas](#compreender-agentes-de-ia-com-ferramentas) +- [Como funciona a chamada de ferramentas](#como-funciona-a-chamada-de-ferramentas) + - [Definições de Ferramentas](#definições-de-ferramentas) + - [Tomada de Decisão](#tomada-de-decisão) + - [Execução](#execução) + - [Geração de Resposta](#geração-de-resposta) + - [Arquitetura: Spring Boot Auto-Wiring](#arquitetura-spring-boot-auto-wiring) +- [Encadeamento de Ferramentas](#encadeamento-de-ferramentas) +- [Executar a Aplicação](#executar-a-aplicação) +- [Utilizar a Aplicação](#usar-a-aplicação) + - [Experimentar Uso Simples de Ferramentas](#experimente-um-uso-simples-da-ferramenta) + - [Testar Encadeamento de Ferramentas](#testar-cadeia-de-ferramentas) + - [Ver Fluxo de Conversa](#ver-o-fluxo-da-conversa) + - [Experimentar com Diferentes Pedidos](#experimente-pedidos-diferentes) +- [Conceitos-Chave](#conceitos-chave) + - [Padrão ReAct (Raciocínio e Ação)](#padrão-react-raciocínio-e-ação) + - [Descrições de Ferramentas Importam](#as-descrições-das-ferramentas-são-importantes) + - [Gestão de Sessão](#gestão-de-sessão) + - [Gestão de Erros](#tratamento-de-erros) +- [Ferramentas Disponíveis](#ferramentas-disponíveis) +- [Quando Usar Agentes Baseados em Ferramentas](#quando-usar-agentes-baseados-em-ferramentas) +- [Ferramentas vs RAG](#ferramentas-vs-rag) +- [Próximos Passos](#próximos-passos) + +## Video Walkthrough + +Assiste a esta sessão ao vivo que explica como começar com este módulo: + +Agentes de IA com Ferramentas e MCP - Sessão ao Vivo + +## O que vais aprender + +Até agora, aprendeste como ter conversas com IA, estruturar prompts de forma eficaz e fundamentar respostas com os teus documentos. Mas ainda existe uma limitação fundamental: os modelos de linguagem só conseguem gerar texto. Não podem verificar o tempo, fazer cálculos, consultar bases de dados ou interagir com sistemas externos. + +As ferramentas mudam isso. Ao dar acesso ao modelo a funções que pode invocar, transformas-no de um gerador de texto num agente que pode tomar ações. O modelo decide quando precisa de uma ferramenta, qual utilizar e que parâmetros passar. O teu código executa a função e devolve o resultado. O modelo incorpora esse resultado na sua resposta. ## Pré-requisitos -- Completar o [Módulo 01 - Introdução](../01-introduction/README.md) (recursos Azure OpenAI implementados) -- Recomenda-se ter completado os módulos anteriores (este módulo referencia [conceitos RAG do Módulo 03](../03-rag/README.md) na comparação Ferramentas vs RAG) -- Ficheiro `.env` no diretório raiz com credenciais do Azure (criado pelo `azd up` no Módulo 01) +- Completar [Módulo 01 - Introdução](../01-introduction/README.md) (recursos Azure OpenAI implantados) +- Recomenda-se completar os módulos anteriores (este módulo referencia [conceitos de RAG do Módulo 03](../03-rag/README.md) na comparação Ferramentas vs RAG) +- Ficheiro `.env` na diretoria raiz com credenciais Azure (criado pelo `azd up` no Módulo 01) -> **Nota:** Se não completou o Módulo 01, siga primeiro as instruções de implementação aí indicadas. +> **Nota:** Se não concluíste o Módulo 01, segue primeiro as instruções de implantação aí descritas. ## Compreender Agentes de IA com Ferramentas -> **📝 Nota:** O termo "agentes" neste módulo refere-se a assistentes de IA melhorados com capacidades de chamada de ferramentas. Isto é diferente dos padrões **Agentic AI** (agentes autónomos com planeamento, memória e raciocínio multi-etapas) que abordaremos no [Módulo 05: MCP](../05-mcp/README.md). +> **📝 Nota:** O termo "agentes" neste módulo refere-se a assistentes de IA com capacidade para invocar ferramentas. Isto é diferente dos padrões **Agentic AI** (agentes autónomos com planeamento, memória e raciocínio multi-etapa) que abordaremos no [Módulo 05: MCP](../05-mcp/README.md). -Sem ferramentas, um modelo de linguagem só pode gerar texto a partir dos seus dados de treino. Pergunte-lhe qual o tempo atual e ele tem de adivinhar. Dê-lhe ferramentas, e pode chamar uma API meteorológica, fazer cálculos, ou consultar uma base de dados — depois entrelaça esses resultados reais na sua resposta. +Sem ferramentas, um modelo de linguagem só consegue gerar texto com base nos seus dados de treino. Pergunta-lhe o tempo atual e terá de adivinhar. Dá-lhe ferramentas e pode invocar uma API meteorológica, fazer cálculos ou consultar uma base de dados — e depois integrar esses resultados reais na resposta. Sem Ferramentas vs Com Ferramentas -*Sem ferramentas, o modelo só pode adivinhar — com ferramentas, pode chamar APIs, fazer cálculos e devolver dados em tempo real.* +*Sem ferramentas, o modelo só pode adivinhar — com ferramentas pode chamar APIs, fazer cálculos e retornar dados em tempo real.* -Um agente de IA com ferramentas segue um padrão de **Raciocinar e Agir (ReAct)**. O modelo não só responde — pensa no que precisa, age chamando uma ferramenta, observa o resultado e depois decide se volta a agir ou entrega a resposta final: +Um agente de IA com ferramentas segue um padrão **Raciocínio e Ação (ReAct)**. O modelo não responde apenas — pensa no que precisa, age chamando uma ferramenta, observa o resultado e depois decide se volta a agir ou entrega a resposta final: -1. **Raciocinar** — O agente analisa a questão do utilizador e determina que informação precisa -2. **Agir** — O agente seleciona a ferramenta certa, gera os parâmetros corretos e chama a função -3. **Observar** — O agente recebe o resultado da ferramenta e avalia -4. **Repetir ou Responder** — Se precisar de mais dados, repete o ciclo; caso contrário, compõe a resposta em linguagem natural +1. **Raciocina** — O agente analisa a questão do utilizador e determina que informação precisa +2. **Age** — O agente seleciona a ferramenta correta, gera os parâmetros adequados e chama-a +3. **Observa** — O agente recebe a saída da ferramenta e avalia o resultado +4. **Repetir ou Responder** — Se for necessário mais dados, o agente repete o processo; caso contrário, compõe uma resposta em linguagem natural Padrão ReAct -*O ciclo ReAct — o agente raciocina sobre o que fazer, age chamando uma ferramenta, observa o resultado e repete até poder fornecer a resposta final.* +*O ciclo ReAct — o agente raciocina sobre o que fazer, age chamando uma ferramenta, observa o resultado e repete até poder entregar a resposta final.* -Isto acontece automaticamente. Você define as ferramentas e as suas descrições. O modelo gere a tomada de decisão sobre quando e como usá-las. +Isto acontece automaticamente. Definis as ferramentas e as suas descrições. O modelo trata da decisão sobre quando e como as usar. -## Como Funciona a Chamada de Ferramentas +## Como funciona a chamada de ferramentas ### Definições de Ferramentas [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Define funções com descrições claras e especificações de parâmetros. O modelo vê essas descrições no seu prompt de sistema e compreende o que cada ferramenta faz. +Definis funções com descrições claras e especificações de parâmetros. O modelo vê estas descrições no prompt do sistema e percebe o que cada ferramenta faz. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // A sua lógica de consulta meteorológica + // A sua lógica de pesquisa do tempo return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// O Assistente é automaticamente configurado pelo Spring Boot com: +// O assistente é automaticamente configurado pelo Spring Boot com: // - Bean ChatModel // - Todos os métodos @Tool das classes @Component // - ChatMemoryProvider para gestão de sessões ``` -O diagrama abaixo detalha cada anotação e mostra como cada parte ajuda a IA a perceber quando chamar a ferramenta e que argumentos passar: +O diagrama abaixo detalha cada anotação e mostra como cada parte ajuda a IA a perceber quando invocar a ferramenta e que argumentos passar: Anatomia das Definições de Ferramentas -*Anatomia de uma definição de ferramenta — @Tool indica à IA quando usar, @P descreve cada parâmetro, e @AiService liga tudo no arranque.* +*Anatomia de uma definição de ferramenta — @Tool indica à IA quando a usar, @P descreve cada parâmetro, e @AiService liga tudo juntamente no arranque.* -> **🤖 Experimente com o Chat [GitHub Copilot](https://github.com/features/copilot):** Abra [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) e pergunte: -> - "Como integraria uma API real de meteorologia, como o OpenWeatherMap, em vez de dados simulados?" -> - "O que torna uma boa descrição de ferramenta que ajuda a IA a usá-la corretamente?" -> - "Como devo gerir erros de API e limites de taxa em implementações de ferramentas?" +> **🤖 Experimenta com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) e pergunta: +> - "Como integraria uma API meteorológica real como OpenWeatherMap em vez de dados mock?" +> - "O que faz uma boa descrição de ferramenta que ajuda a IA a usá-la corretamente?" +> - "Como faço para lidar com erros de API e limites de chamadas nas implementações das ferramentas?" ### Tomada de Decisão -Quando um utilizador pergunta "Qual é o tempo em Seattle?", o modelo não escolhe uma ferramenta aleatoriamente. Compara a intenção do utilizador com cada descrição de ferramenta a que tem acesso, pontua cada uma pela relevância e seleciona a melhor correspondência. Depois gera uma chamada de função estruturada com os parâmetros corretos — neste caso, definiu `location` para `"Seattle"`. +Quando o utilizador pergunta "Qual é o tempo em Seattle?", o modelo não escolhe uma ferramenta aleatoriamente. Compara a intenção do utilizador com cada descrição de ferramenta disponível, pontua a relevância e seleciona a melhor. Depois gera uma chamada estruturada à função com os parâmetros corretos — neste caso, definir `location` para `"Seattle"`. -Se nenhuma ferramenta corresponder ao pedido do utilizador, o modelo responde a partir do seu próprio conhecimento. Se várias ferramentas corresponderem, escolhe a mais específica. +Se nenhuma ferramenta corresponder ao pedido, o modelo recorre a responder com o seu próprio conhecimento. Se várias ferramentas corresponderem, escolhe a mais específica. -Como a IA Decide Que Ferramenta Usar +Como a IA Decide Qual Ferramenta Usar -*O modelo avalia cada ferramenta disponível contra a intenção do utilizador e seleciona a melhor correspondência — por isso escrever descrições de ferramentas claras e específicas é fundamental.* +*O modelo avalia cada ferramenta disponível face à intenção do utilizador e seleciona a melhor — por isso é importante escrever descrições claras e específicas de ferramentas.* ### Execução [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -O Spring Boot injeta automaticamente a interface declarativa `@AiService` com todas as ferramentas registadas, e o LangChain4j executa as chamadas às ferramentas automaticamente. Nos bastidores, uma chamada completa a uma ferramenta passa por seis etapas — desde a pergunta em linguagem natural do utilizador até à resposta em linguagem natural: +O Spring Boot liga automaticamente a interface declarativa `@AiService` com todas as ferramentas registadas, e o LangChain4j executa as chamadas às ferramentas automaticamente. Por trás das cenas, uma chamada completa passa por seis fases — desde a pergunta em linguagem natural do utilizador até uma resposta final em linguagem natural: -Fluxo de Chamada de Ferramentas +Fluxo de Chamada de Ferramenta -*O fluxo completo — o utilizador faz uma pergunta, o modelo seleciona uma ferramenta, o LangChain4j executa, e o modelo integra o resultado numa resposta natural.* +*O fluxo completo — o utilizador faz uma pergunta, o modelo seleciona uma ferramenta, o LangChain4j executa-a, e o modelo tece o resultado numa resposta natural.* -Se executou a [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) no Módulo 00, já viu este padrão em ação — as ferramentas `Calculator` foram chamadas da mesma forma. O diagrama de sequência abaixo mostra exatamente o que aconteceu por trás das cenas durante essa demo: +Nos bastidores, `AiServices` executa o mesmo ciclo de chamada para qualquer ferramenta — aqui ilustrado com um simples `Calculator`. O diagrama de sequência abaixo mostra exatamente o que acontece por trás: Diagrama de Sequência da Chamada de Ferramentas -*O ciclo de chamada de ferramenta da demo Quick Start — `AiServices` envia a sua mensagem e esquemas de ferramentas ao LLM, o LLM responde com uma chamada de função como `add(42, 58)`, o LangChain4j executa o método `Calculator` localmente, e devolve o resultado para a resposta final.* +*O ciclo de chamada de ferramentas — `AiServices` envia a tua mensagem e esquemas das ferramentas para o LLM, o LLM responde com uma chamada de função como `add(42, 58)`, o LangChain4j executa o método `Calculator` localmente, e envia o resultado de volta para a resposta final.* -> **🤖 Experimente com o Chat [GitHub Copilot](https://github.com/features/copilot):** Abra [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) e pergunte: +> **🤖 Experimenta com [GitHub Copilot](https://github.com/features/copilot) Chat:** Abre [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) e pergunta: > - "Como funciona o padrão ReAct e por que é eficaz para agentes de IA?" > - "Como o agente decide que ferramenta usar e em que ordem?" -> - "O que acontece se a execução de uma ferramenta falhar — como posso gerir erros de forma robusta?" +> - "O que acontece se a execução de uma ferramenta falhar - como devo tratar erros de forma robusta?" ### Geração de Resposta -O modelo recebe os dados meteorológicos e formata-os numa resposta em linguagem natural para o utilizador. +O modelo recebe os dados do tempo e formata-os numa resposta em linguagem natural para o utilizador. -### Arquitetura: Auto-Wiring Spring Boot +### Arquitetura: Spring Boot Auto-Wiring -Este módulo utiliza a integração LangChain4j com Spring Boot e interfaces declarativas `@AiService`. No arranque, o Spring Boot descobre todos os `@Component` que contêm métodos com `@Tool`, o seu bean `ChatModel`, e o `ChatMemoryProvider` — depois liga tudo numa única interface `Assistant` sem código repetitivo. +Este módulo usa a integração do LangChain4j com Spring Boot e interfaces declarativas `@AiService`. No arranque, o Spring Boot descobre todos os `@Component` que contêm métodos `@Tool`, o bean `ChatModel` e o `ChatMemoryProvider` — e liga-os todos numa única interface `Assistant` sem código repetitivo. -Arquitetura Auto-Wiring Spring Boot +Arquitetura Spring Boot Auto-Wiring -*A interface @AiService liga o ChatModel, componentes das ferramentas e o memory provider — o Spring Boot gere automaticamente todas as ligações.* +*A interface @AiService liga o ChatModel, os componentes de ferramenta e o fornecedor de memória — o Spring Boot faz toda a ligação automaticamente.* -Aqui está o ciclo de vida completo do pedido como diagrama de sequência — desde a requisição HTTP, passando pelo controlador, serviço e proxy auto-injetado, até à execução da ferramenta e retorno: +Aqui está o ciclo completo do pedido como diagrama de sequência — desde o pedido HTTP, pelo controlador, serviço, proxy auto-ligado, até à execução da ferramenta e retorno: -Sequência de Chamada de Ferramentas Spring Boot +Sequência de Chamadas de Ferramentas no Spring Boot -*O ciclo de vida completo da requisição Spring Boot — a requisição HTTP passa pelo controlador e serviço até ao proxy Assistant auto-injetado, que orquestra o LLM e as chamadas às ferramentas automaticamente.* +*O ciclo completo de pedido Spring Boot — o pedido HTTP passa pelo controlador e serviço até ao proxy Assistant auto-ligado, que orquestra o LLM e as chamadas às ferramentas automaticamente.* -Principais vantagens desta abordagem: +Vantagens-chave desta abordagem: -- **Auto-wiring Spring Boot** — ChatModel e ferramentas injetadas automaticamente -- **Padrão @MemoryId** — Gestão automática de memória por sessão -- **Instância única** — Assistant criado apenas uma vez e reutilizado para melhor desempenho -- **Execução com segurança de tipos** — Métodos Java chamados diretamente com conversão de tipos -- **Orquestração multi-turno** — Gere encadeamento de ferramentas automaticamente -- **Zero código repetitivo** — Sem chamadas manuais a `AiServices.builder()` ou uso de HashMap de memória +- **Auto-wiring do Spring Boot** — ChatModel e ferramentas injetados automaticamente +- **Padrão @MemoryId** — Gestão automática de memória baseada em sessão +- **Instância única** — Assistant criado uma vez e reutilizado para melhor performance +- **Execução com tipo seguro** — Métodos Java chamados diretamente com conversão de tipos +- **Orquestração multi-turno** — Lida automaticamente com encadeamento de ferramentas +- **Zero código repetitivo** — Sem chamadas manuais a `AiServices.builder()` ou HashMaps de memória -Abordagens alternativas (com chamadas manuais a `AiServices.builder()`) requerem mais código e perdem os benefícios da integração Spring Boot. +Abordagens alternativas (manual `AiServices.builder()`) exigem mais código e perdem os benefícios da integração Spring Boot. ## Encadeamento de Ferramentas -**Encadeamento de Ferramentas** — O verdadeiro poder dos agentes baseados em ferramentas mostra-se quando uma única pergunta requer várias ferramentas. Pergunte "Qual é o tempo em Seattle em Fahrenheit?" e o agente encadeia automaticamente duas ferramentas: primeiro chama `getCurrentWeather` para obter a temperatura em Celsius, depois passa esse valor para `celsiusToFahrenheit` para conversão — tudo numa só interação. +**Encadeamento de Ferramentas** — O verdadeiro poder dos agentes baseados em ferramentas revela-se quando uma única pergunta exige múltiplas ferramentas. Pergunta "Qual é o tempo em Seattle em Fahrenheit?" e o agente automaticamente encadeia duas ferramentas: primeiro chama `getCurrentWeather` para obter a temperatura em Celsius, depois passa esse valor para `celsiusToFahrenheit` para conversão — tudo numa única interação de conversa. Exemplo de Encadeamento de Ferramentas -*Encadeamento de ferramentas em ação — o agente chama primeiro getCurrentWeather, depois passa o resultado em Celsius para celsiusToFahrenheit, e entrega uma resposta combinada.* +*Encadeamento de ferramentas em ação — o agente chama primeiro getCurrentWeather, depois envia o resultado em Celsius para celsiusToFahrenheit, e entrega uma resposta combinada.* -**Falhas Elegantes** — Peça o tempo numa cidade que não está nos dados simulados. A ferramenta devolve uma mensagem de erro, e a IA explica que não pode ajudar em vez de falhar. As ferramentas falham de forma segura. O diagrama abaixo contrasta as duas abordagens — com tratamento de erros adequado, o agente apanha a exceção e responde de forma útil, sem ele toda a aplicação falha: +**Falhas Elegantes** — Pede o tempo numa cidade que não está nos dados mock. A ferramenta devolve uma mensagem de erro, e a IA explica que não pode ajudar em vez de falhar. As ferramentas falham com segurança. O diagrama abaixo contrasta as duas abordagens — com tratamento de erro apropriado, o agente apanha a exceção e responde de forma útil, enquanto que sem ele toda a aplicação crasha: -Fluxo de Tratamento de Erros +Fluxo de Gestão de Erros -*Quando uma ferramenta falha, o agente apanha o erro e responde com uma explicação útil em vez de falhar.* +*Quando uma ferramenta falha, o agente apanha o erro e responde com uma explicação útil em vez de crashar.* -Isto acontece numa única interação. O agente orquestra múltiplas chamadas de ferramentas autonomamente. +Isto acontece numa única interação de conversa. O agente orquestra múltiplas chamadas de ferramentas autonomamente. ## Executar a Aplicação -**Verificar a implementação:** +**Verificar implantação:** -Assegure-se que o ficheiro `.env` existe no diretório raiz com as credenciais Azure (criado durante o Módulo 01). Execute este comando a partir do diretório do módulo (`04-tools/`): +Confirma que o ficheiro `.env` existe na diretoria raiz com as credenciais Azure (criado durante o Módulo 01). Executa isto na diretoria do módulo (`04-tools/`): **Bash:** ```bash @@ -207,24 +207,24 @@ Get-Content ..\.env # Deve mostrar AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Iniciar a aplicação:** -> **Nota:** Se já iniciou todas as aplicações usando `./start-all.sh` a partir do diretório raiz (como descrito no Módulo 01), este módulo já está a correr na porta 8084. Pode ignorar os comandos de início abaixo e ir diretamente para http://localhost:8084. +> **Nota:** Se já iniciaste todas as aplicações usando `./start-all.sh` na diretoria raiz (como descrito no Módulo 01), este módulo já estará a correr na porta 8084. Podes saltar os comandos de arranque abaixo e ir diretamente para http://localhost:8084. **Opção 1: Usar o Spring Boot Dashboard (Recomendado para utilizadores VS Code)** -O contentor de desenvolvimento inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerir todas as aplicações Spring Boot. Pode encontrá-la na Barra de Atividades no lado esquerdo do VS Code (procure o ícone do Spring Boot). +O contêiner de desenvolvimento inclui a extensão Spring Boot Dashboard, que fornece uma interface visual para gerir todas as aplicações Spring Boot. Podes encontrá-la na Barra de Atividades no lado esquerdo do VS Code (procura pelo ícone do Spring Boot). -A partir do Spring Boot Dashboard, pode: -- Ver todas as aplicações Spring Boot disponíveis no workspace +No Spring Boot Dashboard, podes: +- Ver todas as aplicações Spring Boot disponíveis no espaço de trabalho - Iniciar/parar aplicações com um clique -- Ver logs das aplicações em tempo real -- Monitorizar o estado das aplicações -Basta clicar no botão de reprodução junto a "tools" para iniciar este módulo, ou iniciar todos os módulos de uma só vez. +- Ver logs da aplicação em tempo real +- Monitorizar o estado da aplicação -Aqui está a aparência do Spring Boot Dashboard no VS Code: +Clica simplesmente no botão de play junto a "tools" para iniciar este módulo, ou inicia todos os módulos de uma vez. -Painel do Spring Boot +Aqui está como o Spring Boot Dashboard aparece no VS Code: +Painel Spring Boot -*O Painel Spring Boot no VS Code — iniciar, parar e monitorizar todos os módulos num só local* +*O Painel Spring Boot no VS Code — iniciar, parar e monitorizar todos os módulos a partir de um único local* **Opção 2: Usar scripts shell** @@ -238,7 +238,7 @@ cd .. # A partir do diretório raiz **PowerShell:** ```powershell -cd .. # Da diretoria raiz +cd .. # A partir do diretório raiz .\start-all.ps1 ``` @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Ambos os scripts carregam automaticamente as variáveis de ambiente do ficheiro `.env` na raiz e irão construir os JARs se não existirem. +Ambos os scripts carregam automaticamente as variáveis de ambiente a partir do ficheiro `.env` da raiz e irão construir os JARs caso não existam. -> **Nota:** Se preferir construir todos os módulos manualmente antes de iniciar: +> **Nota:** Se preferir construir manualmente todos os módulos antes de iniciar: > > **Bash:** > ```bash @@ -285,103 +285,103 @@ cd .. && ./stop-all.sh # Todos os módulos **PowerShell:** ```powershell -.\stop.ps1 # Este módulo apenas +.\stop.ps1 # Apenas este módulo # Ou cd ..; .\stop-all.ps1 # Todos os módulos ``` -## Utilizar a Aplicação +## Usar a Aplicação -A aplicação fornece uma interface web onde pode interagir com um agente de IA que tem acesso a ferramentas de tempo e conversão de temperatura. Aqui está a aparência da interface — inclui exemplos rápidos e um painel de chat para enviar pedidos: +A aplicação fornece uma interface web onde pode interagir com um agente AI que tem acesso a ferramentas de previsão do tempo e conversão de temperatura. Aqui está o aspeto da interface — inclui exemplos de início rápido e um painel de chat para enviar pedidos: -Interface das Ferramentas do Agente de IA +Interface de Ferramentas do Agente AI -*Interface das Ferramentas do Agente de IA - exemplos rápidos e interface de chat para interagir com as ferramentas* +*Interface das Ferramentas do Agente AI - exemplos rápidos e interface de chat para interação com as ferramentas* -### Experimente Usar uma Ferramenta Simples +### Experimente um Uso Simples da Ferramenta -Comece com um pedido simples: "Converte 100 graus Fahrenheit para Celsius". O agente reconhece que precisa da ferramenta de conversão de temperatura, chama-a com os parâmetros corretos e devolve o resultado. Repare como é natural — não especificou qual ferramenta usar nem como a chamar. +Comece com um pedido simples: "Converter 100 graus Fahrenheit para Celsius". O agente reconhece que precisa da ferramenta de conversão de temperatura, chama-a com os parâmetros corretos e devolve o resultado. Repare em como isto parece natural — não teve de especificar qual a ferramenta a usar nem como a chamar. -### Testar Encadeamento de Ferramentas +### Testar Cadeia de Ferramentas -Agora experimente algo mais complexo: "Qual é o tempo em Seattle e converte para Fahrenheit?" Observe o agente a trabalhar por passos. Primeiro obtém o tempo (que devolve em Celsius), reconhece que precisa converter para Fahrenheit, chama a ferramenta de conversão e combina ambos os resultados numa só resposta. +Agora experimente algo mais complexo: "Qual é o tempo em Seattle e converte para Fahrenheit?" Veja o agente a trabalhar isto em passos. Primeiro obtém a previsão do tempo (que retorna Celsius), reconhece que precisa converter para Fahrenheit, chama a ferramenta de conversão e combina ambos os resultados numa única resposta. -### Veja o Fluxo da Conversa +### Ver o Fluxo da Conversa -A interface de chat mantém o histórico da conversa, permitindo interações em múltiplas voltas. Pode ver todas as perguntas e respostas anteriores, tornando fácil seguir a conversa e compreender como o agente constrói o contexto ao longo de várias trocas. +A interface de chat mantém o histórico da conversa, permitindo interações multi-turno. Pode ver todas as perguntas e respostas anteriores, facilitando o acompanhamento da conversa e a compreensão de como o agente constrói o contexto ao longo de múltiplas trocas. -Conversa com Múltiplas Chamadas de Ferramentas +Conversa com Múltiplas Chamadas a Ferramentas -*Conversa em múltiplas voltas mostrando conversões simples, consultas de tempo e encadeamento de ferramentas* +*Conversa multi-turno mostrando conversões simples, consultas de previsão do tempo e cadeia de ferramentas* -### Experimente Diferentes Pedidos +### Experimente Pedidos Diferentes -Teste várias combinações: -- Consultas meteorológicas: "Qual é o tempo em Tóquio?" +Tente várias combinações: +- Consultas de previsão do tempo: "Qual é o tempo em Tóquio?" - Conversões de temperatura: "Quanto é 25°C em Kelvin?" -- Consultas combinadas: "Consulta o tempo em Paris e diz-me se está acima dos 20°C" +- Consultas combinadas: "Verifica o tempo em Paris e diz-me se está acima de 20°C" -Repare como o agente interpreta linguagem natural e mapeia para chamadas adequadas às ferramentas. +Repare em como o agente interpreta a linguagem natural e a traduz em chamadas apropriadas às ferramentas. ## Conceitos-Chave -### Padrão ReAct (Raciocinar e Agir) +### Padrão ReAct (Raciocínio e Ação) -O agente alterna entre raciocinar (decidir o que fazer) e agir (usar ferramentas). Este padrão permite resolução autónoma de problemas em vez de apenas responder a instruções. +O agente alterna entre raciocínio (decidir o que fazer) e ação (usar ferramentas). Este padrão permite a resolução autónoma de problemas em vez de simplesmente responder a instruções. -### A Descrição das Ferramentas é Importante +### As Descrições das Ferramentas São Importantes -A qualidade das descrições das suas ferramentas afeta diretamente a eficácia do agente na sua utilização. Descrições claras e específicas ajudam o modelo a perceber quando e como chamar cada ferramenta. +A qualidade das descrições das suas ferramentas afeta diretamente o quão bem o agente as usa. Descrições claras e específicas ajudam o modelo a perceber quando e como chamar cada ferramenta. -### Gestão de Sessões +### Gestão de Sessão -A anotação `@MemoryId` permite gestão automática de memória baseada em sessões. Cada ID de sessão obtém a sua própria instância `ChatMemory` gerida pelo bean `ChatMemoryProvider`, para que múltiplos utilizadores possam interagir com o agente simultaneamente sem misturar as conversas. O diagrama seguinte mostra como múltiplos utilizadores são direcionados para memórias isoladas com base nos IDs de sessão: +A anotação `@MemoryId` permite a gestão automática de memória baseada em sessões. Cada ID de sessão tem a sua própria instância `ChatMemory` gerida pelo bean `ChatMemoryProvider`, permitindo que múltiplos utilizadores interajam com o agente simultaneamente sem misturar as conversas. O diagrama abaixo mostra como múltiplos utilizadores são encaminhados para memórias isoladas baseadas nos seus IDs de sessão: -Gestão de Sessões com @MemoryId +Gestão de Sessão com @MemoryId -*Cada ID de sessão corresponde a um histórico de conversa isolado — os utilizadores nunca veem as mensagens uns dos outros.* +*Cada ID de sessão mapeia para um histórico de conversação isolado — os utilizadores nunca veem as mensagens uns dos outros.* -### Gestão de Erros +### Tratamento de Erros -As ferramentas podem falhar — as APIs podem expirar, os parâmetros podem ser inválidos, serviços externos podem cair. Os agentes em produção precisam de tratamento de erros para que o modelo possa explicar problemas ou tentar alternativas em vez de falhar completamente. Quando uma ferramenta lança uma exceção, o LangChain4j captura-a e envia a mensagem de erro ao modelo, que pode então explicar o problema em linguagem natural. +As ferramentas podem falhar — APIs podem expirar, parâmetros podem ser inválidos, serviços externos podem falhar. Agentes de produção precisam de tratamento de erros para que o modelo possa explicar problemas ou tentar alternativas em vez de fazer a aplicação inteira falhar. Quando uma ferramenta lança uma exceção, o LangChain4j apanha-a e envia a mensagem de erro para o modelo, que pode então explicar o problema em linguagem natural. ## Ferramentas Disponíveis -O diagrama abaixo mostra o vasto ecossistema de ferramentas que pode construir. Este módulo demonstra ferramentas de tempo e temperatura, mas o mesmo padrão `@Tool` funciona para qualquer método Java — desde consultas a bases de dados a processamento de pagamentos. +O diagrama abaixo mostra o amplo ecossistema de ferramentas que pode construir. Este módulo demonstra ferramentas de previsão do tempo e temperatura, mas o mesmo padrão `@Tool` funciona para qualquer método Java — desde consultas a bases de dados a processamento de pagamentos. Ecossistema de Ferramentas -*Qualquer método Java anotado com @Tool fica disponível para a IA — o padrão estende-se a bases de dados, APIs, email, operações de ficheiros e mais.* +*Qualquer método Java anotado com @Tool torna-se disponível para a AI — o padrão estende-se a bases de dados, APIs, email, operações de ficheiros e muito mais.* ## Quando Usar Agentes Baseados em Ferramentas -Nem todos os pedidos precisam de ferramentas. A decisão depende de se a IA precisa interagir com sistemas externos ou pode responder com o seu próprio conhecimento. O guia seguinte resume quando as ferramentas acrescentam valor e quando são desnecessárias: +Nem todos os pedidos precisam de ferramentas. A decisão depende se a AI precisa interagir com sistemas externos ou pode responder com base no seu próprio conhecimento. O guia abaixo resume quando as ferramentas acrescentam valor e quando não são necessárias: Quando Usar Ferramentas -*Um guia rápido de decisão — as ferramentas são para dados em tempo real, cálculos e ações; conhecimento geral e tarefas criativas não precisam delas.* +*Um guia rápido de decisão — ferramentas são para dados em tempo real, cálculos e ações; conhecimento geral e tarefas criativas não precisam delas.* ## Ferramentas vs RAG -Os módulos 03 e 04 estendem o que a IA pode fazer, mas de formas fundamentalmente diferentes. RAG dá acesso ao modelo ao **conhecimento** recuperando documentos. Ferramentas dão ao modelo a capacidade de realizar **ações** chamando funções. O diagrama abaixo compara estas duas abordagens lado a lado — desde o funcionamento de cada fluxo de trabalho até às compensações entre eles: +Os módulos 03 e 04 ampliam o que a AI pode fazer, mas de formas fundamentalmente diferentes. RAG dá ao modelo acesso ao **conhecimento** ao recuperar documentos. Ferramentas dão ao modelo a habilidade de tomar **ações** ao chamar funções. O diagrama abaixo compara estas duas abordagens lado a lado — desde como cada fluxo de trabalho opera até aos compromissos entre eles: Comparação Ferramentas vs RAG -*RAG recupera informação de documentos estáticos — Ferramentas executam ações e obtêm dados dinâmicos em tempo real. Muitos sistemas de produção combinam ambos.* +*RAG recupera informação de documentos estáticos — Ferramentas executam ações e buscam dados dinâmicos em tempo real. Muitos sistemas de produção combinam ambos.* Na prática, muitos sistemas de produção combinam ambas as abordagens: RAG para fundamentar respostas na sua documentação, e Ferramentas para obter dados ao vivo ou realizar operações. ## Próximos Passos -**Próximo Módulo:** [05-mcp - Protocolo de Contexto do Modelo (MCP)](../05-mcp/README.md) +**Próximo Módulo:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**Navegação:** [← Anterior: Módulo 03 - RAG](../03-rag/README.md) | [Voltar ao Início](../README.md) | [Próximo: Módulo 05 - MCP →](../05-mcp/README.md) +**Navegação:** [← Anterior: Módulo 03 - RAG](../03-rag/README.md) | [Voltar ao Início](../README.md) | [Seguinte: Módulo 05 - MCP →](../05-mcp/README.md) --- **Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos por garantir a precisão, por favor tenha em conta que traduções automáticas podem conter erros ou imprecisões. O documento original no seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se a tradução profissional por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações erradas resultantes do uso desta tradução. +Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes da utilização desta tradução. \ No newline at end of file diff --git a/translations/pt-PT/README.md b/translations/pt-PT/README.md index 666fad715..97fd1ffec 100644 --- a/translations/pt-PT/README.md +++ b/translations/pt-PT/README.md @@ -2,18 +2,18 @@ # LangChain4j para Iniciantes -Um curso para construir aplicações de IA com LangChain4j e Azure OpenAI GPT-5.2, desde chat básico a agentes de IA. +Um curso para construir aplicações de IA com LangChain4j e Azure OpenAI GPT-5.2, desde o chat básico até agentes de IA. ### 🌐 Suporte Multilíngue #### Suportado via GitHub Action (Automatizado e Sempre Atualizado) -[Árabe](../ar/README.md) | [Bengali](../bn/README.md) | [Búlgaro](../bg/README.md) | [Birmanês (Myanmar)](../my/README.md) | [Chinês (Simplificado)](../zh-CN/README.md) | [Chinês (Tradicional, Hong Kong)](../zh-HK/README.md) | [Chinês (Tradicional, Macau)](../zh-MO/README.md) | [Chinês (Tradicional, Taiwan)](../zh-TW/README.md) | [Croata](../hr/README.md) | [Checo](../cs/README.md) | [Dinamarquês](../da/README.md) | [Holandês](../nl/README.md) | [Estónio](../et/README.md) | [Finlandês](../fi/README.md) | [Francês](../fr/README.md) | [Alemão](../de/README.md) | [Grego](../el/README.md) | [Hebraico](../he/README.md) | [Hindi](../hi/README.md) | [Húngaro](../hu/README.md) | [Indonésio](../id/README.md) | [Italiano](../it/README.md) | [Japonês](../ja/README.md) | [Canarês](../kn/README.md) | [Khmer](../km/README.md) | [Coreano](../ko/README.md) | [Lituano](../lt/README.md) | [Malaio](../ms/README.md) | [Malaiala](../ml/README.md) | [Marata](../mr/README.md) | [Nepali](../ne/README.md) | [Pidgin Nigeriano](../pcm/README.md) | [Norueguês](../no/README.md) | [Persa (Farsi)](../fa/README.md) | [Polaco](../pl/README.md) | [Português (Brasil)](../pt-BR/README.md) | [Português (Portugal)](./README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romeno](../ro/README.md) | [Russo](../ru/README.md) | [Sérvio (Cirílico)](../sr/README.md) | [Eslovaco](../sk/README.md) | [Esloveno](../sl/README.md) | [Espanhol](../es/README.md) | [Suaíli](../sw/README.md) | [Sueco](../sv/README.md) | [Tagalo (Filipino)](../tl/README.md) | [Tâmil](../ta/README.md) | [Telugu](../te/README.md) | [Tailandês](../th/README.md) | [Turco](../tr/README.md) | [Ucraniano](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamita](../vi/README.md) +[Árabe](../ar/README.md) | [Bengali](../bn/README.md) | [Búlgaro](../bg/README.md) | [Birmanês (Myanmar)](../my/README.md) | [Chinês (Simplificado)](../zh-CN/README.md) | [Chinês (Tradicional, Hong Kong)](../zh-HK/README.md) | [Chinês (Tradicional, Macau)](../zh-MO/README.md) | [Chinês (Tradicional, Taiwan)](../zh-TW/README.md) | [Croata](../hr/README.md) | [Checo](../cs/README.md) | [Dinamarquês](../da/README.md) | [Holandês](../nl/README.md) | [Estónio](../et/README.md) | [Finlandês](../fi/README.md) | [Francês](../fr/README.md) | [Alemão](../de/README.md) | [Grego](../el/README.md) | [Hebraico](../he/README.md) | [Hindi](../hi/README.md) | [Húngaro](../hu/README.md) | [Indonésio](../id/README.md) | [Italiano](../it/README.md) | [Japonês](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Coreano](../ko/README.md) | [Lituano](../lt/README.md) | [Malaio](../ms/README.md) | [Malaiala](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Pidgin Nigeriano](../pcm/README.md) | [Norueguês](../no/README.md) | [Persa (Farsi)](../fa/README.md) | [Polaco](../pl/README.md) | [Português (Brasil)](../pt-BR/README.md) | [Português (Portugal)](./README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romeno](../ro/README.md) | [Russo](../ru/README.md) | [Sérvio (Cirílico)](../sr/README.md) | [Eslovaco](../sk/README.md) | [Esloveno](../sl/README.md) | [Espanhol](../es/README.md) | [Suaíli](../sw/README.md) | [Sueco](../sv/README.md) | [Tagalo (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Tailandês](../th/README.md) | [Turco](../tr/README.md) | [Ucraniano](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamita](../vi/README.md) > **Prefere Clonar Localmente?** > -> Este repositório inclui 50+ traduções de idiomas que aumentam significativamente o tamanho do download. Para clonar sem traduções, use checkout esparso: +> Este repositório inclui traduções em mais de 50 idiomas, o que aumenta significativamente o tamanho do download. Para clonar sem as traduções, utilize o checkout esparso: > > **Bash / macOS / Linux:** > ```bash @@ -29,21 +29,20 @@ Um curso para construir aplicações de IA com LangChain4j e Azure OpenAI GPT-5. > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Isto dá-lhe tudo o que precisa para completar o curso com um download muito mais rápido. +> Isto fornece tudo o que precisa para completar o curso com um download muito mais rápido. ## Índice -1. [Início Rápido](00-quick-start/README.md) - Comece com LangChain4j -2. [Introdução](01-introduction/README.md) - Aprenda os fundamentos do LangChain4j -3. [Engenharia de Prompt](02-prompt-engineering/README.md) - Domine o design eficaz de prompts -4. [RAG (Geração Aumentada por Recuperação)](03-rag/README.md) - Construa sistemas inteligentes baseados em conhecimento -5. [Ferramentas](04-tools/README.md) - Integre ferramentas externas e assistentes simples -6. [MCP (Protocolo de Contexto de Modelo)](05-mcp/README.md) - Trabalhe com o Protocolo de Contexto de Modelo (MCP) e módulos Agentic +1. [Introdução](01-introduction/README.md) - Aprenda os fundamentos do LangChain4j +2. [Engenharia de Prompt](02-prompt-engineering/README.md) - Domine o design eficaz de prompts +3. [RAG (Geração Aumentada por Recuperação)](03-rag/README.md) - Construa sistemas inteligentes baseados em conhecimento +4. [Ferramentas](04-tools/README.md) - Integre ferramentas externas e assistentes simples +5. [MCP (Protocolo de Contexto de Modelo)](05-mcp/README.md) - Trabalhe com o Protocolo de Contexto do Modelo (MCP) e módulos Agentic -### Vídeos Explicativos +### Vídeos Demonstrativos -Cada módulo tem uma sessão ao vivo acompanhante onde analisamos os conceitos e código passo a passo. +Cada módulo tem uma sessão ao vivo acompanhante onde percorremos os conceitos e código passo a passo. | Módulo | Vídeo | |--------|-------| @@ -54,35 +53,37 @@ Cada módulo tem uma sessão ao vivo acompanhante onde analisamos os conceitos e --- -## Roteiro de Aprendizagem +## Caminho de Aprendizagem -**Novo no LangChain4j?** Consulte o [Glossário](docs/GLOSSARY.md) para definições de termos e conceitos principais. +**Novo no LangChain4j?** Consulte o [Glossário](docs/GLOSSARY.md) para definições dos termos e conceitos principais. > **Início Rápido** -1. Faça um fork deste repositório para a sua conta GitHub -2. Clique em **Code** → aba **Codespaces** → **...** → **New with options...** -3. Use as predefinições – isto selecionará o container de Desenvolvimento criado para este curso +1. Faça fork deste repositório para sua conta GitHub +2. Clique em **Code** → aba **Codespaces** → **...** → **Novo com opções...** +3. Use as opções padrão – isto selecionará o contentor de desenvolvimento criado para este curso 4. Clique em **Create codespace** -5. Aguarde 5-10 minutos até o ambiente estar pronto -6. Vá diretamente para [Início Rápido](./00-quick-start/README.md) para começar! +5. Aguarde 5-10 minutos para o ambiente ficar pronto +6. Vá diretamente para [Introdução](./01-introduction/README.md) para começar! Após concluir os módulos, explore o [Guia de Testes](docs/TESTING.md) para ver conceitos de teste do LangChain4j em ação. -> **Nota:** Este treino usa tanto GitHub Models como Azure OpenAI. O módulo [Início Rápido](00-quick-start/README.md) usa GitHub Models (não requer subscrição Azure), enquanto os módulos 1-5 utilizam Azure OpenAI. Comece com uma [conta Azure GRATUITA](https://aka.ms/azure-free-account) se ainda não tiver. +> **Nota:** Este treino usa Azure OpenAI. Comece com uma [conta GRATUITA Azure](https://aka.ms/azure-free-account) se ainda não tiver uma. + ## Aprender com GitHub Copilot -Para começar a codificar rapidamente, abra este projeto num GitHub Codespace ou no seu IDE local com o devcontainer fornecido. O devcontainer usado neste curso vem pré-configurado com GitHub Copilot para programação em par assistida por IA. +Para começar a programar rapidamente, abra este projeto num GitHub Codespace ou na sua IDE local com o devcontainer fornecido. O devcontainer usado neste curso vem pré-configurado com GitHub Copilot para programação assistida por IA. -Cada exemplo de código inclui perguntas sugeridas que pode fazer ao GitHub Copilot para aprofundar o seu entendimento. Procure os prompts 💡/🤖 em: +Cada exemplo de código inclui perguntas sugeridas que pode fazer ao GitHub Copilot para aprofundar a sua compreensão. Procure os prompts 💡/🤖 em: - **Cabeçalhos de ficheiros Java** - Perguntas específicas para cada exemplo -- **READMEs dos módulos** - Prompts de exploração após exemplos de código +- **README dos módulos** - Prompts para exploração após exemplos de código + +**Como usar:** Abra qualquer ficheiro de código e faça ao Copilot as perguntas sugeridas. Ele tem o contexto completo do código e pode explicar, expandir e sugerir alternativas. -**Como usar:** Abra qualquer ficheiro de código e faça ao Copilot as perguntas sugeridas. Ele tem contexto completo da base de código e pode explicar, expandir e sugerir alternativas. +Quer saber mais? Veja [Copilot para Programação Assistida por IA](https://aka.ms/GitHubCopilotAI). -Quer saber mais? Veja [Copilot para Programação em Par com IA](https://aka.ms/GitHubCopilotAI). ## Recursos Adicionais @@ -93,11 +94,11 @@ Quer saber mais? Veja [Copilot para Programação em Par com IA](https://aka.ms/ [![LangChain para Iniciantes](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents +### Azure / Edge / MCP / Agentes [![AZD para Iniciantes](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) [![Edge AI para Iniciantes](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) [![MCP para Iniciantes](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Agentes de IA para Iniciantes](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Agentes IA para Iniciantes](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- @@ -114,35 +115,36 @@ Quer saber mais? Veja [Copilot para Programação em Par com IA](https://aka.ms/ [![Ciência de Dados para Iniciantes](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![IA para Iniciantes](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Cibersegurança para Iniciantes](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Desenvolvimento Web para Iniciantes](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT para Iniciantes](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![Desenvolvimento XR para Iniciantes](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Série Copilot -[![Copilot para Programação em Par com IA](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot para C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Aventura Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Obter Ajuda -Se ficar preso ou tiver alguma dúvida sobre a criação de aplicações de IA, junte-se a: +Se ficar bloqueado ou tiver alguma pergunta sobre como criar aplicações de IA, junte-se a: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Se tiver feedback sobre o produto ou erros durante o desenvolvimento, visite: +Se tiver feedback sobre o produto ou erros enquanto constrói, visite: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licença -Licença MIT - Veja o ficheiro [LICENSE](../../LICENSE) para detalhes. +Licença MIT - Veja o ficheiro [LICENSE](../../LICENSE) para mais detalhes. --- -**Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos por garantir a precisão, esteja ciente de que as traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se a tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações erradas decorrentes da utilização desta tradução. +**Aviso Legal**: +Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes da utilização desta tradução. \ No newline at end of file diff --git a/translations/pt-PT/docs/GLOSSARY.md b/translations/pt-PT/docs/GLOSSARY.md index ec4e3d048..3b8cb976d 100644 --- a/translations/pt-PT/docs/GLOSSARY.md +++ b/translations/pt-PT/docs/GLOSSARY.md @@ -2,31 +2,31 @@ ## Índice -- [Conceitos Principais](../../../docs) -- [Componentes LangChain4j](../../../docs) -- [Conceitos de IA/ML](../../../docs) -- [Guardrails](../../../docs) -- [Engenharia de Prompt](../../../docs) -- [RAG (Geração Aumentada por Recuperação)](../../../docs) -- [Agentes e Ferramentas](../../../docs) -- [Módulo Agente](../../../docs) -- [Protocolo de Contexto do Modelo (MCP)](../../../docs) -- [Serviços Azure](../../../docs) -- [Testes e Desenvolvimento](../../../docs) +- [Conceitos Principais](#conceitos-principais) +- [Componentes LangChain4j](#componentes-langchain4j) +- [Conceitos AI/ML](#conceitos-aiml) +- [Guardrails](#guardrails) +- [Engenharia de Prompt](#prompt-engineering---module-02) +- [RAG (Geração Aumentada por Recuperação)](#rag-retrieval-augmented-generation---module-03) +- [Agentes e Ferramentas](#agents-and-tools---module-04) +- [Módulo Agente](#agentic-module---module-05) +- [Protocolo de Contexto do Modelo (MCP)](#model-context-protocol-mcp---module-05) +- [Serviços Azure](#azure-services---module-01) +- [Testes e Desenvolvimento](#testing-and-development---testing-guide) Referência rápida para termos e conceitos usados ao longo do curso. ## Conceitos Principais -**Agente de IA** - Sistema que usa IA para raciocinar e agir autonomamente. [Módulo 04](../04-tools/README.md) +**Agente AI** - Sistema que usa AI para raciocinar e agir autonomamente. [Módulo 04](../04-tools/README.md) **Cadeia** - Sequência de operações onde a saída alimenta o passo seguinte. -**Divisão em Pedaços (Chunking)** - Dividir documentos em partes menores. Típico: 300-500 tokens com sobreposição. [Módulo 03](../03-rag/README.md) +**Fragmentação** - Dividir documentos em pedaços menores. Típico: 300-500 tokens com sobreposição. [Módulo 03](../03-rag/README.md) -**Janela de Contexto** - Número máximo de tokens que um modelo pode processar. GPT-5.2: 400K tokens (até 272K de entrada, 128K de saída). +**Janela de Contexto** - Máximo de tokens que um modelo pode processar. GPT-5.2: 400K tokens (até 272K entrada, 128K saída). -**Embeddings** - Vetores numéricos que representam o significado do texto. [Módulo 03](../03-rag/README.md) +**Embedding** - Vetores numéricos que representam o significado do texto. [Módulo 03](../03-rag/README.md) **Chamada de Função** - Modelo gera pedidos estruturados para chamar funções externas. [Módulo 04](../04-tools/README.md) @@ -34,9 +34,9 @@ Referência rápida para termos e conceitos usados ao longo do curso. **Prompt** - Texto de entrada para um modelo de linguagem. [Módulo 02](../02-prompt-engineering/README.md) -**Pesquisa Semântica** - Pesquisa pelo significado usando embeddings, não palavras-chave. [Módulo 03](../03-rag/README.md) +**Pesquisa Semântica** - Pesquisa por significado usando embeddings, não por palavras-chave. [Módulo 03](../03-rag/README.md) -**Com Estado vs Sem Estado** - Sem estado: sem memória. Com estado: mantém histórico da conversa. [Módulo 01](../01-introduction/README.md) +**Com Estado vs Sem Estado** - Sem Estado: sem memória. Com Estado: mantém histórico da conversa. [Módulo 01](../01-introduction/README.md) **Tokens** - Unidades básicas de texto que os modelos processam. Afetam custos e limites. [Módulo 01](../01-introduction/README.md) @@ -44,19 +44,19 @@ Referência rápida para termos e conceitos usados ao longo do curso. ## Componentes LangChain4j -**AiServices** - Cria interfaces de serviço de IA com segurança de tipos. +**AiServices** - Cria interfaces de serviço AI com tipagem segura. -**OpenAiOfficialChatModel** - Cliente unificado para os modelos OpenAI e Azure OpenAI. +**OpenAiOfficialChatModel** - Cliente unificado para modelos OpenAI e Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Cria embeddings usando o cliente oficial OpenAI (suporta OpenAI e Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Cria embeddings usando cliente oficial OpenAI (suporta OpenAI e Azure OpenAI). -**ChatModel** - Interface central para modelos de linguagem. +**ChatModel** - Interface principal para modelos de linguagem. -**ChatMemory** - Mantém histórico da conversa. +**ChatMemory** - Mantém histórico de conversas. -**ContentRetriever** - Encontra pedaços relevantes de documentos para RAG. +**ContentRetriever** - Encontra fragmentos de documentos relevantes para RAG. -**DocumentSplitter** - Divide documentos em pedaços. +**DocumentSplitter** - Divide documentos em fragmentos. **EmbeddingModel** - Converte texto em vetores numéricos. @@ -66,65 +66,65 @@ Referência rápida para termos e conceitos usados ao longo do curso. **PromptTemplate** - Cria prompts reutilizáveis com espaços reservados `{{variable}}`. -**TextSegment** - Pedaço de texto com metadados. Usado no RAG. +**TextSegment** - Fragmento de texto com metadados. Usado em RAG. **ToolExecutionRequest** - Representa pedido de execução de ferramenta. -**UserMessage / AiMessage / SystemMessage** - Tipos de mensagens na conversa. +**UserMessage / AiMessage / SystemMessage** - Tipos de mensagens de conversa. -## Conceitos de IA/ML +## Conceitos AI/ML **Few-Shot Learning** - Fornecer exemplos nos prompts. [Módulo 02](../02-prompt-engineering/README.md) -**Modelo de Linguagem Grande (LLM)** - Modelos de IA treinados com grandes volumes de texto. +**Modelo de Linguagem Grande (LLM)** - Modelos AI treinados com muitos dados textuais. -**Esforço de Raciocínio** - Parâmetro do GPT-5.2 que controla profundidade de pensamento. [Módulo 02](../02-prompt-engineering/README.md) +**Esforço de Raciocínio** - Parâmetro do GPT-5.2 que controla a profundidade do pensamento. [Módulo 02](../02-prompt-engineering/README.md) -**Temperatura** - Controla aleatoriedade da saída. Baixa=determinístico, alta=criativo. +**Temperatura** - Controla a aleatoriedade da saída. Baixa=determinística, alta=criativa. **Base de Dados Vetorial** - Base de dados especializada para embeddings. [Módulo 03](../03-rag/README.md) **Zero-Shot Learning** - Realizar tarefas sem exemplos. [Módulo 02](../02-prompt-engineering/README.md) -## Guardrails - [Módulo 00](../00-quick-start/README.md) +## Guardrails -**Defesa em Profundidade** - Abordagem multi-camadas de segurança combinando guardrails a nível de aplicação com filtros de segurança do fornecedor. +**Defense in Depth** - Abordagem de segurança em múltiplas camadas combinando guardrails a nível de aplicação com filtros de segurança do fornecedor. -**Bloqueio Rígido** - Fornecedor retorna erro HTTP 400 para violações graves de conteúdo. +**Bloqueio Rígido** - Fornecedor emite erro HTTP 400 para violações graves de conteúdo. -**InputGuardrail** - Interface LangChain4j para validar input do utilizador antes de atingir o LLM. Economiza custo e latência bloqueando prompts prejudiciais cedo. +**InputGuardrail** - Interface LangChain4j para validar entrada do utilizador antes de chegar ao LLM. Poupa custo e latência bloqueando prompts potencialmente prejudiciais antecipadamente. -**InputGuardrailResult** - Tipo de retorno para validação de guardrail: `success()` ou `fatal("reason")`. +**InputGuardrailResult** - Tipo de retorno para validação guardrail: `success()` ou `fatal("razão")`. -**OutputGuardrail** - Interface para validar respostas de IA antes de devolver aos utilizadores. +**OutputGuardrail** - Interface para validar respostas AI antes de serem enviadas aos utilizadores. -**Filtros de Segurança do Fornecedor** - Filtros integrados de conteúdo dos fornecedores de IA (ex.: GitHub Models) que detectam violações a nível de API. +**Filtros de Segurança do Fornecedor** - Filtros integrados de conteúdo dos fornecedores AI (ex. Azure OpenAI) que capturam violações a nível da API. -**Recusa Suave** - Modelo educadamente recusa responder sem gerar erro. +**Recusa Suave** - Modelo recusa educadamente responder sem gerar erro. ## Engenharia de Prompt - [Módulo 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Raciocínio passo a passo para maior precisão. +**Cadeia de Pensamento** - Raciocínio passo-a-passo para maior precisão. -**Saída Constrangida** - Imposição de formato ou estrutura específicos. +**Saída Constrainida** - Aplicar formato ou estrutura específica. -**Alta Diligência** - Padrão GPT-5.2 para raciocínio detalhado. +**Alto Entusiasmo** - Padrão GPT-5.2 para raciocínio rigoroso. -**Baixa Diligência** - Padrão GPT-5.2 para respostas rápidas. +**Baixo Entusiasmo** - Padrão GPT-5.2 para respostas rápidas. -**Conversação Multi-Turno** - Manutenção de contexto ao longo das trocas. +**Conversação Multi-Turno** - Manter contexto ao longo das trocas. -**Prompting Baseado em Papéis** - Definição da persona do modelo via mensagens do sistema. +**Prompting Baseado em Papel** - Definir persona do modelo via mensagens do sistema. -**Auto-Reflexão** - Modelo avalia e melhora a sua própria saída. +**Autorreflexão** - Modelo avalia e melhora a sua saída. -**Análise Estruturada** - Quadro fixo de avaliação. +**Análise Estruturada** - Estrutura fixa de avaliação. -**Padrão de Execução de Tarefa** - Planear → Executar → Resumir. +**Padrão de Execução de Tarefas** - Planear → Executar → Resumir. ## RAG (Geração Aumentada por Recuperação) - [Módulo 03](../03-rag/README.md) -**Pipeline de Processamento de Documentos** - Carregar → dividir → embedar → armazenar. +**Pipeline de Processamento de Documentos** - Carregar → fragmentar → inserir embeddings → armazenar. **Armazenamento de Embeddings em Memória** - Armazenamento não persistente para testes. @@ -136,97 +136,95 @@ Referência rápida para termos e conceitos usados ao longo do curso. ## Agentes e Ferramentas - [Módulo 04](../04-tools/README.md) -**Anotação @Tool** - Marca métodos Java como ferramentas acessíveis por IA. +**@Tool Annotation** - Marca métodos Java como ferramentas chamáveis por AI. **Padrão ReAct** - Raciocinar → Agir → Observar → Repetir. -**Gestão de Sessão** - Contextos separados para utilizadores diferentes. +**Gestão de Sessão** - Contextos separados para diferentes utilizadores. -**Ferramenta** - Função que um agente IA pode chamar. +**Ferramenta** - Função que um agente AI pode chamar. **Descrição da Ferramenta** - Documentação do propósito e parâmetros da ferramenta. ## Módulo Agente - [Módulo 05](../05-mcp/README.md) -**Anotação @Agent** - Marca interfaces como agentes de IA com definição declarativa de comportamento. +**@Agent Annotation** - Marca interfaces como agentes AI com definição declarativa de comportamento. -**Agent Listener** - Gancho para monitorizar execução do agente via `beforeAgentInvocation()` e `afterAgentInvocation()`. +**Agent Listener** - Hook para monitorar execução do agente via `beforeAgentInvocation()` e `afterAgentInvocation()`. -**Agentic Scope** - Memória partilhada onde agentes guardam resultados usando `outputKey` para agentes seguintes consumirem. +**Agentic Scope** - Memória partilhada onde agentes armazenam saídas usando `outputKey` para consumo por agentes a jusante. **AgenticServices** - Fábrica para criar agentes usando `agentBuilder()` e `supervisorBuilder()`. -**Workflow Condicional** - Roteamento baseado em condições para diferentes agentes especializados. +**Fluxo Condicional** - Roteamento baseado em condições para diferentes agentes especialistas. -**Human-in-the-Loop** - Padrão de workflow que adiciona pontos de controlo humanos para aprovação ou revisão de conteúdo. +**Humano no Loop** - Padrão de fluxo adicionando pontos de aprovação ou revisão humana. **langchain4j-agentic** - Dependência Maven para construção declarativa de agentes (experimental). -**Loop Workflow** - Iterar a execução do agente até uma condição ser cumprida (ex.: pontuação de qualidade ≥ 0.8). +**Fluxo em Ciclo** - Iterar execução do agente até uma condição ser satisfeita (ex: pontuação de qualidade ≥ 0.8). -**outputKey** - Parâmetro de anotação do agente que especifica onde armazenar resultados no Agentic Scope. +**outputKey** - Parâmetro da anotação de agente que especifica onde guardar resultados no Agentic Scope. -**Parallel Workflow** - Executar vários agentes simultaneamente para tarefas independentes. +**Fluxo Paralelo** - Executar múltiplos agentes simultaneamente para tarefas independentes. -**Estratégia de Resposta** - Como o supervisor formula a resposta final: LAST, SUMMARY, ou SCORED. +**Estratégia de Resposta** - Como o supervisor formula resposta final: LAST, SUMMARY, ou SCORED. -**Sequential Workflow** - Executar agentes em ordem, onde a saída flui para o passo seguinte. +**Fluxo Sequencial** - Executar agentes em ordem onde saída flui para o passo seguinte. -**Padrão de Agente Supervisor** - Padrão agente avançado onde um supervisor LLM decide dinamicamente quais sub-agentes invocar. +**Padrão Agente Supervisor** - Padrão agente avançado onde um LLM supervisor decide dinamicamente quais sub-agentes invocar. ## Protocolo de Contexto do Modelo (MCP) - [Módulo 05](../05-mcp/README.md) **langchain4j-mcp** - Dependência Maven para integração MCP em LangChain4j. -**MCP** - Protocolo de Contexto do Modelo: padrão para ligação de apps de IA a ferramentas externas. Construir uma vez, usar em todo o lado. +**MCP** - Modelo Context Protocol: padrão para conectar apps AI a ferramentas externas. Construa uma vez, use em todo lado. **Cliente MCP** - Aplicação que conecta a servidores MCP para descobrir e usar ferramentas. **Servidor MCP** - Serviço que expõe ferramentas via MCP com descrições claras e esquemas de parâmetros. -**McpToolProvider** - Componente LangChain4j que embrulha ferramentas MCP para uso em serviços IA e agentes. +**McpToolProvider** - Componente LangChain4j que envolve ferramentas MCP para uso em serviços AI e agentes. **McpTransport** - Interface para comunicação MCP. Implementações incluem Stdio e HTTP. -**Transporte Stdio** - Transporte local via stdin/stdout. Útil para acesso ao sistema de ficheiros ou ferramentas linha de comando. +**Transporte Stdio** - Transporte de processo local via stdin/stdout. Útil para acesso a sistema de ficheiros ou ferramentas command-line. -**StdioMcpTransport** - Implementação LangChain4j que inicia servidor MCP como subprocesso. +**StdioMcpTransport** - Implementação LangChain4j que lança servidor MCP como subprocesso. -**Descoberta de Ferramentas** - Cliente consulta servidor para ferramentas disponíveis com descrições e esquemas. +**Descoberta de Ferramentas** - Cliente pergunta servidor por ferramentas disponíveis com descrições e esquemas. ## Serviços Azure - [Módulo 01](../01-introduction/README.md) -**Azure AI Search** - Pesquisa na cloud com capacidades vetoriais. [Módulo 03](../03-rag/README.md) +**Azure AI Search** - Pesquisa cloud com capacidades vetoriais. [Módulo 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Implementa recursos Azure. +**Azure Developer CLI (azd)** - Implanta recursos Azure. -**Azure OpenAI** - Serviço empresarial de IA da Microsoft. +**Azure OpenAI** - Serviço AI empresarial da Microsoft. -**Bicep** - Linguagem Azure de infra-estrutura como código. [Guia de Infraestrutura](../01-introduction/infra/README.md) +**Bicep** - Linguagem de infraestrutura como código Azure. [Guia Infraestrutura](../01-introduction/infra/README.md) -**Nome da Implementação** - Nome para a implementação do modelo no Azure. +**Nome da Implantação** - Nome para implantação de modelo no Azure. **GPT-5.2** - Último modelo OpenAI com controlo de raciocínio. [Módulo 02](../02-prompt-engineering/README.md) ## Testes e Desenvolvimento - [Guia de Testes](TESTING.md) -**Dev Container** - Ambiente de desenvolvimento containerizado. [Configuração](../../../.devcontainer/devcontainer.json) - -**GitHub Models** - Playground gratuito de modelos IA. [Módulo 00](../00-quick-start/README.md) +**Dev Container** - Ambiente de desenvolvimento conteinerizado. [Configuração](../../../.devcontainer/devcontainer.json) **Testes em Memória** - Testes com armazenamento em memória. **Testes de Integração** - Testes com infraestrutura real. -**Maven** - Ferramenta de automação de build Java. +**Maven** - Ferramenta de automação de build para Java. -**Mockito** - Framework de mocking Java. +**Mockito** - Framework de mocking para Java. -**Spring Boot** - Framework de aplicações Java. [Módulo 01](../01-introduction/README.md) +**Spring Boot** - Framework para aplicações Java. [Módulo 01](../01-introduction/README.md) --- **Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, por favor tenha em conta que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informação crítica, recomenda-se a tradução profissional efetuada por um humano. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes da utilização desta tradução. +Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes da utilização desta tradução. \ No newline at end of file diff --git a/translations/pt-PT/docs/TESTING.md b/translations/pt-PT/docs/TESTING.md index 9e96d2d83..7e09472f2 100644 --- a/translations/pt-PT/docs/TESTING.md +++ b/translations/pt-PT/docs/TESTING.md @@ -1,18 +1,18 @@ -# Testar Aplicações LangChain4j +# Testar aplicações LangChain4j ## Índice -- [Começo Rápido](../../../docs) -- [O Que os Testes Cobrem](../../../docs) -- [Executar os Testes](../../../docs) -- [Executar Testes no VS Code](../../../docs) -- [Padrões de Teste](../../../docs) -- [Filosofia de Teste](../../../docs) -- [Próximos Passos](../../../docs) +- [Início Rápido](#inicio-rápido) +- [O Que os Testes Abrangem](#o-que-os-testes-abrangem) +- [Executar os Testes](#executar-os-testes) +- [Executar Testes no VS Code](#executar-testes-no-vs-code) +- [Padrões de Teste](#padrões-de-teste) +- [Filosofia de Teste](#filosofia-de-teste) +- [Próximos Passos](#próximos-passos) -Este guia orienta-o pelos testes que demonstram como testar aplicações de IA sem necessitar de chaves de API ou serviços externos. +Este guia orienta-o através dos testes que demonstram como testar aplicações de IA sem necessitar de chaves de API ou serviços externos. -## Começo Rápido +## Início Rápido Execute todos os testes com um único comando: @@ -26,28 +26,27 @@ mvn test mvn --% test ``` -Quando todos os testes passarem, deverá ver uma saída semelhante à imagem abaixo — testes executados com zero falhas. +Quando todos os testes passarem, deverá ver saída semelhante à captura de ecrã abaixo — testes executados sem falhas. Successful Test Results -*Execução bem-sucedida dos testes mostrando todos a passar sem falhas* +*Execução bem-sucedida do teste mostrando todos os testes a passar sem falhas* -## O Que os Testes Cobrem +## O Que os Testes Abrangem -Este curso foca-se em **testes unitários** que correm localmente. Cada teste demonstra um conceito específico do LangChain4j isoladamente. A pirâmide de testes abaixo mostra onde os testes unitários se encaixam — formam a base rápida e fiável sobre a qual todo o resto da sua estratégia de testes se apoia. +Este curso foca-se em **testes unitários** que são executados localmente. Cada teste demonstra um conceito específico do LangChain4j isoladamente. A pirâmide de testes abaixo mostra onde os testes unitários se encaixam — formam a base rápida e fiável sobre a qual o restante da sua estratégia de testes se constrói. Testing Pyramid -*Pirâmide de testes mostrando o equilíbrio entre testes unitários (rápidos, isolados), testes de integração (componentes reais) e testes fim-a-fim. Esta formação cobre testes unitários.* +*Pirâmide de testes mostrando o equilíbrio entre testes unitários (rápidos, isolados), testes de integração (componentes reais) e testes end-to-end. Este curso aborda testes unitários.* -| Módulo | Testes | Foco | Ficheiros Chave | -|--------|--------|------|-----------------| -| **00 - Começo Rápido** | 6 | Templates de prompts e substituição de variáveis | `SimpleQuickStartTest.java` | -| **01 - Introdução** | 8 | Memória de conversação e chat com estado | `SimpleConversationTest.java` | -| **02 - Engenharia de Prompts** | 12 | Padrões GPT-5.2, níveis de prontidão, saída estruturada | `SimpleGpt5PromptTest.java` | +| Módulo | Testes | Foco | Ficheiros Principais | +|--------|-------|-------|-----------| +| **01 - Introdução** | 8 | Memória de conversa e chat com estado | `SimpleConversationTest.java` | +| **02 - Engenharia de Prompt** | 12 | Padrões GPT-5.2, níveis de prontidão, saída estruturada | `SimpleGpt5PromptTest.java` | | **03 - RAG** | 10 | Ingestão de documentos, embeddings, pesquisa por similaridade | `DocumentServiceTest.java` | | **04 - Ferramentas** | 12 | Chamada de funções e encadeamento de ferramentas | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Protocolo de Contexto de Modelo com transporte stdio | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | Protocolo de Contexto de Modelo com transporte Stdio | `SimpleMcpTest.java` | ## Executar os Testes @@ -95,7 +94,7 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#deveManterHistóricoDeConversação +mvn test -Dtest=SimpleConversationTest#deveManterHistoricoDeConversacao ``` **PowerShell:** @@ -105,7 +104,7 @@ mvn --% test -Dtest=SimpleConversationTest#deveManterHistoricoDaConversa ## Executar Testes no VS Code -Se estiver a usar o Visual Studio Code, o Test Explorer fornece uma interface gráfica para executar e depurar testes. +Se estiver a usar o Visual Studio Code, o Test Explorer oferece uma interface gráfica para executar e depurar testes. VS Code Test Explorer @@ -113,23 +112,23 @@ Se estiver a usar o Visual Studio Code, o Test Explorer fornece uma interface gr **Para executar testes no VS Code:** -1. Abra o Test Explorer clicando no ícone do béquer na Barra de Atividades -2. Expanda a árvore de teste para ver todos os módulos e classes de teste -3. Clique no botão de executar ao lado de qualquer teste para o executar individualmente -4. Clique em "Run All Tests" para executar toda a suíte -5. Clique com o botão direito num teste e selecione "Debug Test" para definir pontos de interrupção e avançar passo a passo no código +1. Abra o Test Explorer clicando no ícone de béquer na Barra de Atividades +2. Expanda a árvore de testes para ver todos os módulos e classes de testes +3. Clique no botão de reprodução ao lado de qualquer teste para o executar individualmente +4. Clique em "Run All Tests" para executar todo o conjunto +5. Clique com o botão direito em qualquer teste e selecione "Debug Test" para definir pontos de interrupção e avançar no código -O Test Explorer mostra marcas verdes de verificação para testes aprovados e fornece mensagens detalhadas de falha quando um teste falha. +O Test Explorer mostra sinais verdes de verificação para testes que passam e fornece mensagens detalhadas de falha quando os testes falham. ## Padrões de Teste ### Padrão 1: Testar Templates de Prompt -O padrão mais simples testa templates de prompt sem chamar qualquer modelo de IA. Verifica-se que a substituição de variáveis funciona corretamente e que os prompts estão formatados como esperado. +O padrão mais simples testa templates de prompt sem chamar qualquer modelo de IA. Verifica-se que a substituição de variáveis funciona corretamente e que os prompts são formatados como esperado. Prompt Template Testing -*Teste de templates de prompt mostrando o fluxo de substituição de variáveis: template com espaços reservados → valores aplicados → saída formatada verificada* +*Testar templates de prompt mostrando o fluxo da substituição de variáveis: template com marcadores → valores aplicados → saída formatada verificada* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Este teste encontra-se em `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Este padrão verifica que a substituição de variáveis funciona corretamente e que os prompts são formatados como esperado — não é necessária chave de API nem chamada a modelo. -**Execute-o:** +### Padrão 2: Simular Modelos de Linguagem -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testarFormataçãoDoModeloDePrompt -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testarFormataçãoDoModeloDePrompt -``` - -### Padrão 2: Mocking de Modelos de Linguagem - -Ao testar a lógica da conversação, use Mockito para criar modelos falsos que retornam respostas predeterminadas. Isto torna os testes rápidos, gratuitos e determinísticos. +Ao testar a lógica de conversação, use Mockito para criar modelos falsos que retornam respostas pré-determinadas. Isto torna os testes rápidos, gratuitos e determinísticos. Mock vs Real API Comparison -*Comparação mostrando por que os mocks são preferidos para testes: são rápidos, grátis, determinísticos e não requerem chaves de API* +*Comparação mostrando por que os mocks são preferidos para testes: são rápidos, gratuitos, determinísticos e não requerem chaves de API* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 mensagens de utilizador + 3 mensagens de IA + assertThat(history).hasSize(6); // 3 mensagens do utilizador + 3 mensagens de IA } } ``` -Este padrão aparece em `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. O mock assegura comportamento consistente para que possa verificar que a gestão de memória funciona corretamente. +Este padrão aparece em `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. O mock garante comportamento consistente para que possa verificar que a gestão da memória funciona corretamente. -### Padrão 3: Testar Isolamento da Conversação +### Padrão 3: Testar Isolamento de Conversação -A memória da conversação deve manter múltiplos utilizadores separados. Este teste verifica que as conversações não misturam contextos. +A memória da conversação deve manter usuários múltiplos separados. Este teste verifica que as conversas não misturam contextos. Conversation Isolation -*Teste de isolamento de conversação mostrando repositórios de memória separados para diferentes utilizadores para evitar mistura de contextos* +*Testar isolamento da conversação mostrando memórias separadas para diferentes utilizadores para evitar mistura de contextos* ```java @Test @@ -250,7 +237,7 @@ void shouldIsolateConversationsByid() { } ``` -Cada conversação mantém a sua própria história independente. Em sistemas de produção, este isolamento é crítico para aplicações multiutilizador. +Cada conversação mantém o seu próprio histórico independente. Em sistemas de produção, este isolamento é crítico para aplicações multi-utilizador. ### Padrão 4: Testar Ferramentas Independentemente @@ -258,7 +245,7 @@ As ferramentas são funções que a IA pode chamar. Teste-as diretamente para ga Tools Testing -*Teste de ferramentas independentemente mostrando execução de ferramentas mock sem chamadas à IA para verificar a lógica de negócio* +*Testar ferramentas independentemente mostrando execução simulada sem chamadas à IA para verificar a lógica do negócio* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Estes testes de `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validam a lógica das ferramentas sem envolvimento da IA. O exemplo de encadeamento mostra como a saída de uma ferramenta alimenta a entrada de outra. +Estes testes de `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validam a lógica das ferramentas sem envolvimento da IA. O exemplo de encadeamento mostra como a saída de uma ferramenta serve de entrada para outra. ### Padrão 5: Testar RAG em Memória -Sistemas RAG tradicionalmente requerem bases de dados vetoriais e serviços de embeddings. O padrão em memória permite testar todo o pipeline sem dependências externas. +Sistemas RAG normalmente requerem bases de dados vetoriais e serviços de embedding. O padrão em memória permite testar toda a pipeline sem dependências externas. In-Memory RAG Testing -*Fluxo de trabalho RAG em memória mostrando parsing de documentos, armazenamento de embeddings e pesquisa por similaridade sem necessidade de base de dados* +*Fluxo de trabalho de teste RAG em memória mostrando análise de documentos, armazenamento de embeddings e pesquisa por similaridade sem necessidade de base de dados* ```java @Test @@ -306,11 +293,11 @@ void testProcessTextDocument() { } ``` -Este teste de `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` cria um documento em memória e verifica a segmentação e o tratamento de metadados. +Este teste de `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` cria um documento em memória e verifica segmentação e manipulação de metadados. ### Padrão 6: Testar Integração MCP -O módulo MCP testa a integração do Protocolo de Contexto de Modelo usando transporte stdio. Estes testes verificam que a sua aplicação pode lançar e comunicar com servidores MCP como subprocessos. +O módulo MCP testa a integração do Protocolo de Contexto de Modelo usando transporte stdio. Estes testes verificam que a sua aplicação pode gerar e comunicar com servidores MCP como subprocessos. Os testes em `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validam o comportamento do cliente MCP. @@ -328,25 +315,24 @@ cd 05-mcp; mvn --% test ## Filosofia de Teste -Teste o seu código, não a IA. Os seus testes devem validar o código que escreve verificando como os prompts são construídos, como a memória é gerida e como as ferramentas executam. As respostas da IA variam e não devem fazer parte das asserções dos testes. Pergunte-se se o seu template de prompt substitui corretamente as variáveis, não se a IA dá a resposta correta. +Teste o seu código, não a IA. Os seus testes devem validar o código que escreve verificando como os prompts são construídos, como a memória é gerida e como as ferramentas executam. As respostas da IA variam e não devem fazer parte das assertivas dos testes. Pergunte-se se o seu template de prompt substitui corretamente as variáveis, não se a IA dá a resposta certa. -Use mocks para modelos de linguagem. São dependências externas lentas, caras e não determinísticas. Mocking torna os testes rápidos com milissegundos em vez de segundos, gratuitos sem custos de API e determinísticos com o mesmo resultado sempre. +Use mocks para modelos de linguagem. São dependências externas lentas, dispendiosas e não determinísticas. Simular torna os testes rápidos em milissegundos em vez de segundos, gratuitos sem custos de API, e determinísticos com o mesmo resultado sempre. -Mantenha os testes independentes. Cada teste deve configurar os seus próprios dados, não depender de outros testes, e limpar-se a si próprio. Os testes devem passar independentemente da ordem de execução. +Mantenha os testes independentes. Cada teste deve configurar os seus próprios dados, não depender de outros testes e limpar após si próprio. Os testes devem passar independentemente da ordem de execução. -Teste casos limite além do caminho feliz. Tente inputs vazios, inputs muito grandes, caracteres especiais, parâmetros inválidos e condições de fronteira. Estes frequentemente revelam bugs que o uso normal não expõe. +Teste casos extremos além do caminho feliz. Experimente entradas vazias, entradas muito grandes, caracteres especiais, parâmetros inválidos e condições limite. Estes frequentemente revelam bugs que o uso normal não expõe. -Use nomes descritivos. Compare `shouldMaintainConversationHistoryAcrossMultipleMessages()` com `test1()`. O primeiro diz-lhe exatamente o que está a ser testado, tornando a depuração de falhas muito mais fácil. +Use nomes descritivos. Compare `shouldMaintainConversationHistoryAcrossMultipleMessages()` com `test1()`. O primeiro diz exatamente o que está a ser testado, tornando mais fácil depurar falhas. ## Próximos Passos Agora que entende os padrões de teste, aprofunde-se em cada módulo: -- **[00 - Começo Rápido](../00-quick-start/README.md)** - Comece com o básico de templates de prompt -- **[01 - Introdução](../01-introduction/README.md)** - Aprenda a gestão de memória de conversação -- **[02 - Engenharia de Prompts](../02-prompt-engineering/README.md)** - Domine padrões de prompting GPT-5.2 +- **[01 - Introdução](../01-introduction/README.md)** - Aprenda gestão de memória de conversação +- **[02 - Engenharia de Prompt](../02/prompt-engineering/README.md)** - Domine padrões de prompting GPT-5.2 - **[03 - RAG](../03-rag/README.md)** - Construa sistemas de geração aumentada por recuperação -- **[04 - Ferramentas](../04-tools/README.md)** - Implemente chamadas de função e cadeias de ferramentas +- **[04 - Ferramentas](../04-tools/README.md)** - Implemente chamadas de funções e cadeias de ferramentas - **[05 - MCP](../05-mcp/README.md)** - Integre o Protocolo de Contexto de Modelo O README de cada módulo fornece explicações detalhadas dos conceitos aqui testados. @@ -359,5 +345,5 @@ O README de cada módulo fornece explicações detalhadas dos conceitos aqui tes **Aviso Legal**: -Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, tenha em atenção que traduções automáticas podem conter erros ou imprecisões. O documento original, na sua língua nativa, deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional feita por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes da utilização desta tradução. +Este documento foi traduzido utilizando o serviço de tradução automática [Co-op Translator](https://github.com/Azure/co-op-translator). Embora nos esforcemos pela precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes da utilização desta tradução. \ No newline at end of file diff --git a/translations/ro/.co-op-translator.json b/translations/ro/.co-op-translator.json index 5a26daef9..eeaa3af78 100644 --- a/translations/ro/.co-op-translator.json +++ b/translations/ro/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ro" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T23:52:54+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T11:00:13+00:00", "source_file": "01-introduction/README.md", "language_code": "ro" }, @@ -18,20 +18,20 @@ "language_code": "ro" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T23:55:01+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T10:55:55+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ro" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T23:56:18+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T10:59:29+00:00", "source_file": "03-rag/README.md", "language_code": "ro" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:29:54+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T10:58:31+00:00", "source_file": "04-tools/README.md", "language_code": "ro" }, @@ -54,8 +54,8 @@ "language_code": "ro" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:00:02+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T10:54:22+00:00", "source_file": "README.md", "language_code": "ro" }, @@ -72,14 +72,14 @@ "language_code": "ro" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T23:59:07+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T10:56:27+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ro" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T23:59:45+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T10:57:06+00:00", "source_file": "docs/TESTING.md", "language_code": "ro" } diff --git a/translations/ro/00-quick-start/README.md b/translations/ro/00-quick-start/README.md deleted file mode 100644 index 606063aed..000000000 --- a/translations/ro/00-quick-start/README.md +++ /dev/null @@ -1,389 +0,0 @@ -# Modulul 00: Pornire Rapidă - -## Cuprins - -- [Introducere](../../../00-quick-start) -- [Ce este LangChain4j?](../../../00-quick-start) -- [Dependențe LangChain4j](../../../00-quick-start) -- [Precondiții](../../../00-quick-start) -- [Configurare](../../../00-quick-start) - - [1. Obțineți tokenul GitHub](../../../00-quick-start) - - [2. Setează tokenul](../../../00-quick-start) -- [Rulare Exemple](../../../00-quick-start) - - [1. Chat de bază](../../../00-quick-start) - - [2. Modele de prompturi](../../../00-quick-start) - - [3. Apelarea funcțiilor](../../../00-quick-start) - - [4. Întrebări și răspunsuri document (Easy RAG)](../../../00-quick-start) - - [5. AI responsabilă](../../../00-quick-start) -- [Ce arată fiecare exemplu](../../../00-quick-start) -- [Pașii următori](../../../00-quick-start) -- [Rezolvarea problemelor](../../../00-quick-start) - -## Introducere - -Acest ghid rapid are scopul de a vă ajuta să începeți să utilizați LangChain4j cât mai repede posibil. Acoperă elementele absolut de bază pentru construirea aplicațiilor AI cu LangChain4j și Modele GitHub. În următoarele module veți trece la Azure OpenAI și GPT-5.2 și veți aprofunda fiecare concept. - -## Ce este LangChain4j? - -LangChain4j este o bibliotecă Java care simplifică construirea aplicațiilor alimentate de AI. În loc să lucrați cu clienți HTTP și parsarea JSON, folosiți API-uri clare Java. - -„Chain” în LangChain se referă la conectarea în lanț a mai multor componente – puteți conecta un prompt la un model, apoi la un parser, sau puteți conecta mai multe apeluri AI unde ieșirea unuia devine intrarea următorului. Această pornire rapidă se concentrează pe fundamente înainte de a explora lanțuri mai complexe. - -Conceptul de conectare în lanț LangChain4j - -*Conectarea componentelor în LangChain4j - blocuri de bază conectate pentru a crea fluxuri AI puternice* - -Vom folosi trei componente de bază: - -**ChatModel** – Interfața pentru interacțiuni cu modelul AI. Apelați `model.chat("prompt")` și primiți un răspuns sub formă de text. Folosim `OpenAiOfficialChatModel` care funcționează cu endpoint-uri compatibile OpenAI, cum sunt Modelele GitHub. - -**AiServices** – Creează interfețe sigure pe tipuri pentru servicii AI. Definiți metode, le notați cu `@Tool` și LangChain4j se ocupă de orchestrare. AI-ul vă apelează automat metodele Java când este nevoie. - -**MessageWindowChatMemory** – Menține istoricul conversației. Fără acesta, fiecare cerere este independentă. Cu acesta, AI-ul își amintește mesajele anterioare și păstrează contextul pe parcursul mai multor interacțiuni. - -Arhitectura LangChain4j - -*Arhitectura LangChain4j - componentele principale care lucrează împreună pentru a alimenta aplicațiile tale AI* - -## Dependențe LangChain4j - -Această pornire rapidă folosește trei dependențe Maven în [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modulul `langchain4j-open-ai-official` oferă clasa `OpenAiOfficialChatModel` care se conectează la API-uri compatibile OpenAI. Modelele GitHub folosesc același format de API, deci nu este necesar un adaptor special - trebuie doar să indicați URL-ul de bază spre `https://models.github.ai/inference`. - -Modulul `langchain4j-easy-rag` oferă divizarea automată a documentelor, embedding și recuperare, astfel încât să puteți construi aplicații RAG fără a configura manual fiecare pas. - -## Precondiții - -**Folosiți containerul de dezvoltare?** Java și Maven sunt deja instalate. Aveți nevoie doar de un Token de acces personal GitHub. - -**Dezvoltare locală:** -- Java 21+, Maven 3.9+ -- Token de Acces Personal GitHub (instrucțiuni mai jos) - -> **Notă:** Acest modul folosește `gpt-4.1-nano` de la Modelele GitHub. Nu modificați numele modelului în cod - este configurat să funcționeze cu modelele disponibile pe GitHub. - -## Configurare - -### 1. Obțineți tokenul GitHub - -1. Accesați [Setări GitHub → Tokenuri de Acces Personal](https://github.com/settings/personal-access-tokens) -2. Click pe „Generați token nou” -3. Dați-i un nume descriptiv (ex., „LangChain4j Demo”) -4. Stabiliți expirarea (7 zile recomandat) -5. La „Permisiuni cont”, găsiți „Models” și setați pe „Read-only” -6. Click pe „Generate token” -7. Copiați și salvați tokenul – nu îl veți mai vedea din nou - -### 2. Setează tokenul - -**Opțiunea 1: Folosind VS Code (recomandat)** - -Dacă folosiți VS Code, adăugați tokenul în fișierul `.env` din rădăcina proiectului: - -Dacă fișierul `.env` nu există, copiați `.env.example` în `.env` sau creați un fișier `.env` nou în rădăcina proiectului. - -**Exemplu fișier `.env`:** -```bash -# În /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Apoi puteți face click dreapta pe orice fișier demo (ex., `BasicChatDemo.java`) în Explorer și selecta **„Run Java”** sau să folosiți configurațiile de lansare din panoul Run and Debug. - -**Opțiunea 2: Folosind Terminalul** - -Setați tokenul ca variabilă de mediu: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - - -## Rulare Exemple - -**Folosind VS Code:** Pur și simplu faceți click dreapta pe orice fișier demo în Explorer și selectați **„Run Java”**, sau folosiți configurațiile din Run and Debug (asigurați-vă că ați adăugat tokenul în fișierul `.env` înainte). - -**Folosind Maven:** Alternativ, puteți rula din linia de comandă: - -### 1. Chat de bază - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - - -### 2. Modele de prompturi - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Arată zero-shot, few-shot, chain-of-thought și prompting bazat pe rol. - -### 3. Apelarea funcțiilor - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI apelează automat metodele Java când este nevoie. - -### 4. Întrebări și răspunsuri document (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Puneți întrebări despre documentele voastre folosind Easy RAG cu embedding și recuperare automată. - -### 5. AI responsabilă - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Vezi cum filtrele de siguranță AI blochează conținutul dăunător. - -## Ce arată fiecare exemplu - -**Chat de bază** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Începeți aici pentru a vedea LangChain4j în cea mai simplă formă. Veți crea un `OpenAiOfficialChatModel`, veți trimite un prompt cu `.chat()` și veți primi un răspuns. Acesta demonstrează fundația: cum să inițializați modelele cu endpoint-uri personalizate și chei API. Odată ce înțelegeți acest model, totul se construiește pe el. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Încercați cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschideți [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) și întrebați: -> - „Cum aș comuta de la Modele GitHub la Azure OpenAI în acest cod?” -> - „Ce alți parametri pot configura în OpenAiOfficialChatModel.builder()?” -> - „Cum adaug răspunsuri în streaming în loc să aștept răspunsul complet?” - -**Inginerie Prompturi** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Acum că știți cum să vorbiți cu un model, să explorăm ce îi spuneți. Acest demo folosește aceeași configurare dar arată cinci modele diferite de prompting. Încercați zero-shot pentru instrucțiuni directe, few-shot care învață din exemple, chain-of-thought care dezvăluie pașii de raționament și prompting bazat pe rol pentru a seta contextul. Veți vedea cum același model dă rezultate foarte diferite în funcție de modul în care formulați cererea. - -Demo arată și template-uri de prompturi, o metodă puternică pentru a crea prompturi reutilizabile cu variabile. -Exemplul de mai jos arată un prompt folosind `PromptTemplate` din LangChain4j pentru a completa variabilele. AI va răspunde bazat pe destinația și activitatea oferite. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Încercați cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschideți [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) și întrebați: -> - „Care este diferența între zero-shot și few-shot prompting și când ar trebui să le folosesc?” -> - „Cum afectează parametrul temperature răspunsurile modelului?” -> - „Care sunt tehnicile pentru a preveni atacurile de tip prompt injection în producție?” -> - „Cum pot crea obiecte PromptTemplate reutilizabile pentru tipare comune?” - -**Integrare Unelte** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Aici LangChain4j devine puternic. Folosiți `AiServices` pentru a crea un asistent AI care poate apela metodele Java. Notați metodele cu `@Tool("descriere")` și LangChain4j se ocupă de restul – AI-ul decide automat când să folosească fiecare unealtă în funcție de cererile utilizatorului. Aceasta demonstrează apelarea funcțiilor, o tehnică cheie pentru a construi AI care poate lua acțiuni, nu doar răspunde la întrebări. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Încercați cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschideți [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) și întrebați: -> - „Cum funcționează notația @Tool și ce face LangChain4j cu ea în fundal?” -> - „Poate AI să apeleze mai multe unelte în secvență pentru a rezolva probleme complexe?” -> - „Ce se întâmplă dacă o unealtă aruncă o excepție – cum ar trebui să gestionez erorile?” -> - „Cum aș integra o API reală în locul acestui exemplu de calculator?” - -**Întrebări și răspunsuri document (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Aici veți vedea RAG (retrieval-augmented generation) folosind abordarea „Easy RAG” a LangChain4j. Documentele sunt încărcate, împărțite automat și integrate într-un depozit în memorie, apoi un recuperator de conținut furnizează bucățile relevante AI-ului la interogare. AI-ul răspunde bazat pe documentele voastre, nu pe cunoștințele generale. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Încercați cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschideți [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) și întrebați: -> - „Cum previne RAG halucinațiile AI în comparație cu folosirea datelor de antrenament ale modelului?” -> - „Care este diferența între această metodă ușoară și o pipeline RAG personalizată?” -> - „Cum aș scala asta pentru a gestiona mai multe documente sau baze de cunoștințe mai mari?” - -**AI responsabilă** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Construiți siguranță AI cu apărare în profunzime. Acest demo arată două nivele de protecție care lucrează împreună: - -**Partea 1: LangChain4j Input Guardrails** – Blochează prompturile periculoase înainte să ajungă la LLM. Creați bariere personalizate care verifică cuvinte cheie sau tipare interzise. Acestea rulează în codul vostru, deci sunt rapide și fără cost. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Partea 2: Filtre de siguranță ale providerului** – Modelele GitHub au filtre integrate care prind ceea ce barierele voastre pot rata. Veți vedea blocări dure (erori HTTP 400) pentru încălcări grave și refuzuri blânde unde AI-ul refuză politicos. - -> **🤖 Încercați cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschideți [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) și întrebați: -> - „Ce este InputGuardrail și cum creez unul propriu?” -> - „Care este diferența între o blocare dură și un refuz blând?” -> - „De ce să folosesc împreună bariere și filtre ale providerului?” - -## Pașii următori - -**Următorul modul:** [01-introduction - Început cu LangChain4j](../01-introduction/README.md) - ---- - -**Navigare:** [← Înapoi la Principal](../README.md) | [Următorul: Modul 01 - Introducere →](../01-introduction/README.md) - ---- - -## Rezolvarea problemelor - -### Prima compilare Maven - -**Problemă:** Primul `mvn clean compile` sau `mvn package` durează mult (10-15 minute) - -**Cauză:** Maven trebuie să descarce toate dependențele proiectului (Spring Boot, biblioteci LangChain4j, SDK-uri Azure etc.) la prima compilare. - -**Soluție:** Comportament normal. Compilările următoare vor fi mult mai rapide deoarece dependențele sunt memorate local. Timpul de descărcare depinde de viteza rețelei. - -### Sintaxa comenzii Maven în PowerShell - -**Problemă:** Comenzile Maven eșuează cu eroarea `Unknown lifecycle phase ".mainClass=..."` -**Cauză**: PowerShell interpretează `=` ca operator de atribuire a variabilei, întrerupând sintaxa proprietăților Maven - -**Soluție**: Folosiți operatorul de oprire a analizării `--%` înaintea comenzii Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operatorul `--%` spune PowerShell să transmită toate argumentele rămase literal către Maven fără interpretare. - -### Afișarea emoji-urilor în Windows PowerShell - -**Problemă**: Răspunsurile AI afișează caractere ciudate (de exemplu, `????` sau `â??`) în loc de emoji-uri în PowerShell - -**Cauză**: Codificarea implicită a PowerShell nu suportă emoji-urile UTF-8 - -**Soluție**: Rulați această comandă înainte de a executa aplicațiile Java: -```cmd -chcp 65001 -``` - -Aceasta forțează codificarea UTF-8 în terminal. Alternativ, folosiți Windows Terminal care are suport mai bun pentru Unicode. - -### Depanarea apelurilor API - -**Problemă**: Erori de autentificare, limite de rată sau răspunsuri neașteptate de la modelul AI - -**Soluție**: Exemplele includ `.logRequests(true)` și `.logResponses(true)` pentru a afișa apelurile API în consolă. Aceasta ajută la depanarea erorilor de autentificare, limitelor de rată sau răspunsurilor neașteptate. Eliminați aceste opțiuni în producție pentru a reduce zgomotul din loguri. - ---- - - -**Disclaimer**: -Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autoritară. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist uman. Nu ne asumăm responsabilitatea pentru eventuale neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri. - \ No newline at end of file diff --git a/translations/ro/01-introduction/README.md b/translations/ro/01-introduction/README.md index 33b49b983..a566183c8 100644 --- a/translations/ro/01-introduction/README.md +++ b/translations/ro/01-introduction/README.md @@ -1,85 +1,85 @@ -# Modulul 01: Începutul cu LangChain4j +# Modulul 01: Început cu LangChain4j ## Cuprins -- [Parcurgere Video](../../../01-introduction) -- [Ce Vei Învăța](../../../01-introduction) -- [Cerinte Prealabile](../../../01-introduction) -- [Înțelegerea Problemei de Bază](../../../01-introduction) -- [Înțelegerea Token-urilor](../../../01-introduction) -- [Cum Funcționează Memoria](../../../01-introduction) -- [Cum Folosește Acesta LangChain4j](../../../01-introduction) -- [Deplasează Infrastructura Azure OpenAI](../../../01-introduction) -- [Rulează Aplicația Local](../../../01-introduction) -- [Folosirea Aplicației](../../../01-introduction) - - [Chat Stateless (Panoul Stâng)](../../../01-introduction) - - [Chat Stateful (Panoul Drept)](../../../01-introduction) -- [Pașii Următori](../../../01-introduction) - -## Parcurgere Video +- [Prezentare Video](#prezentare-video) +- [Ce vei învăța](#ce-vei-învăța) +- [Precondiții](#precondiții) +- [Înțelegerea problemei de bază](#înțelegerea-problemei-de-bază) +- [Înțelegerea token-urilor](#înțelegerea-token-urilor) +- [Cum funcționează memoria](#cum-funcționează-memoria) +- [Cum folosește acest lucru LangChain4j](#cum-folosește-acest-lucru-langchain4j) +- [Implementarea infrastructurii Azure OpenAI](#implementarea-infrastructurii-azure-openai) +- [Rularea aplicației local](#rularea-aplicației-local) +- [Folosirea aplicației](#folosirea-aplicației) + - [Chat fără stare (panoul din stânga)](#chat-fără-stare-panoul-din-stânga) + - [Chat cu stare (panoul din dreapta)](#chat-cu-stare-panoul-din-dreapta) +- [Pașii următori](#pașii-următori) + +## Prezentare Video Urmărește această sesiune live care explică cum să începi cu acest modul: -Începerea cu LangChain4j - Sesiune Live +Început cu LangChain4j - Sesiune Live -## Ce Vei Învăța +## Ce vei învăța -În startul rapid, ai folosit Modelele GitHub pentru a trimite prompturi, a apela instrumente, a construi un pipeline RAG și a testa guardrails. Acele demo-uri au arătat ce este posibil — acum trecem la Azure OpenAI și GPT-5.2 și începem să construim aplicații de tip producție. Acest modul se concentrează pe AI conversațional care ține minte contextul și menține starea — conceptele pe care acele demo-uri quick start le-au folosit în spate, dar fără să le explice. +Acesta este punctul tău de start cu LangChain4j și Azure OpenAI. Începem cu elementele fundamentale și începem să construim aplicații de tip producție. Acest modul se concentrează pe AI conversațional care reține contextul și menține starea — conceptele fundamentale pe care se bazează toate modulele ulterioare. -Vom folosi GPT-5.2 de la Azure OpenAI pe tot parcursul acestui ghid deoarece capacitățile sale avansate de raționament fac comportamentul diferitelor tipare mai evident. Când adaugi memorie, vei vedea clar diferența. Acest lucru face mai ușoară înțelegerea a ceea ce fiecare componentă aduce aplicației tale. +Vom folosi GPT-5.2 de la Azure OpenAI pe tot parcursul acestui ghid pentru că capacitățile sale avansate de raționament fac comportamentul diferitelor modele mai evident. Când adaugi memorie, vei vedea clar diferența. Acest lucru face mai ușor să înțelegi ce aduce fiecare componentă aplicației tale. -Vei construi o aplicație care demonstrează ambele tipare: +Veți crea o singură aplicație care demonstrează ambele modele: -**Chat Stateless** - Fiecare cerere este independentă. Modelul nu are memorie a mesajelor anterioare. Acesta este tiparul folosit în quick start. +**Chat fără stare** - Fiecare cerere este independentă. Modelul nu păstrează memoria mesajelor anterioare. Aceasta este cea mai simplă pornire. -**Conversație Stateful** - Fiecare cerere include istoricul conversației. Modelul menține contextul pe mai multe runde. Acesta este ceea ce cer aplicațiile de producție. +**Conversație cu stare** - Fiecare cerere include istoricul conversației. Modelul păstrează contextul pe parcursul mai multor schimburi. Asta este ceea ce cer aplicațiile de producție. -## Cerinte Prealabile +## Precondiții - Abonament Azure cu acces la Azure OpenAI -- Java 21, Maven 3.9+ +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) > **Notă:** Java, Maven, Azure CLI și Azure Developer CLI (azd) sunt preinstalate în devcontainer-ul furnizat. -> **Notă:** Acest modul folosește GPT-5.2 pe Azure OpenAI. Deploy-ul este configurat automat prin `azd up` - nu modifica numele modelului în cod. +> **Notă:** Acest modul folosește GPT-5.2 pe Azure OpenAI. Implementarea este configurată automat prin `azd up` - nu modificați numele modelului în cod. -## Înțelegerea Problemei de Bază +## Înțelegerea problemei de bază -Modelele de limbaj sunt stateless. Fiecare apel API este independent. Dacă trimiți „Numele meu este John” și apoi întrebi „Care este numele meu?”, modelul nu are idee că tocmai te-ai prezentat. Tratatează fiecare cerere ca și cum ar fi prima conversație pe care o ai vreodată. +Modelele de limbaj sunt fără stare. Fiecare apel API este independent. Dacă trimiți "Numele meu este John" și apoi întrebi "Care este numele meu?", modelul nu are nicio idee că tocmai te-ai prezentat. Tratează fiecare cerere ca și cum ar fi prima conversație pe care ai avut-o vreodată. -Aceasta este în regulă pentru Q&A simple, dar inutil pentru aplicații reale. Boții de servicii clienți trebuie să-și amintească ce le-ai spus. Asistenții personali au nevoie de context. Orice conversație cu mai multe runde necesită memorie. +Acest lucru este perfect pentru întrebări și răspunsuri simple, dar inutil pentru aplicații reale. Roboții de servicii clienți trebuie să-și amintească ce le-ai spus. Asistenții personali au nevoie de context. Orice conversație cu mai multe schimburi necesită memorie. -Diagrama următoare contrastează cele două abordări — în stânga, un apel stateless care uită numele tău; în dreapta, un apel stateful susținut de ChatMemory care reține acest lucru. +Diagrama următoare contrastează cele două abordări — în stânga, un apel fără stare care îți uită numele; în dreapta, un apel cu stare susținut de ChatMemory care îl reține. -Conversații Stateless vs Stateful +Conversații fără stare vs cu stare -*Diferența între conversațiile stateless (apeluri independente) și cele stateful (sensibile la context)* +*Diferența dintre conversațiile fără stare (apeluri independente) și cele cu stare (conștiente de context)* -## Înțelegerea Token-urilor +## Înțelegerea token-urilor -Înainte de a intra în conversații, este important să înțelegi token-urile — unitățile de bază de text pe care modelele de limbaj le procesează: +Înainte de a intra în conversații, este important să înțelegi token-urile - unitățile de bază de text pe care modelele de limbaj le procesează: Explicație Token -*Exemplu de cum textul este împărțit în token-uri - „I love AI!” devine 4 unități separate de procesare* +*Exemplu de cum textul este descompus în token-uri - "I love AI!" devine 4 unități separate de procesare* -Token-urile sunt modul în care modelele AI măsoară și procesează textul. Cuvintele, punctuația și chiar spațiile pot fi token-uri. Modelul tău are o limită a numărului de token-uri pe care le poate procesa simultan (400,000 pentru GPT-5.2, cu până la 272,000 token-uri de intrare și 128,000 token-uri de ieșire). Înțelegerea token-urilor te ajută să gestionezi lungimea conversației și costurile. +Token-urile sunt modul în care modelele AI măsoară și procesează textul. Cuvintele, semnele de punctuație și chiar spațiile pot fi token-uri. Modelul tău are o limită privind câte token-uri poate procesa odată (400.000 pentru GPT-5.2, cu până la 272.000 token-uri de intrare și 128.000 token-uri de ieșire). Înțelegerea token-urilor te ajută să gestionezi lungimea și costurile conversațiilor. -## Cum Funcționează Memoria +## Cum funcționează memoria -Memoria pentru chat rezolvă problema stateless prin menținerea istoricului conversației. Înainte de a trimite cererea către model, cadrul de lucru adaugă în față mesajele anterioare relevante. Când întrebi „Care este numele meu?”, sistemul trimite de fapt întreg istoricul conversației, permițând modelului să vadă că anterior ai spus „Numele meu este John.” +Memoria pentru chat rezolvă problema lipsei de stare prin păstrarea istoricului conversației. Înainte de a trimite cererea ta modelului, cadrul adaugă mesajele relevante anterioare în față. Când întrebi "Care este numele meu?", sistemul trimite de fapt întregul istoric al conversației, permițând modelului să vadă că ai spus anterior "Numele meu este John." -LangChain4j oferă implementări de memorie care gestionează acest lucru automat. Alegi câte mesaje să reții și cadrul de lucru gestionează fereastra de context. Diagrama de mai jos arată cum MessageWindowChatMemory menține o fereastră glisantă a mesajelor recente. +LangChain4j oferă implementări de memorie care gestionează acest proces automat. Alegi câte mesaje să păstrezi, iar cadrul administrează fereastra de context. Diagrama de mai jos arată cum MessageWindowChatMemory menține o fereastră mobilă cu cele mai recente mesaje. -Conceptul Ferestrei de Memorie +Conceptul ferestrei de memorie -*MessageWindowChatMemory menține o fereastră glisantă a mesajelor recente, eliminând automat cele vechi* +*MessageWindowChatMemory menține o fereastră mobilă cu cele mai recente mesaje, eliminând automat mesajele vechi* -## Cum Folosește Acesta LangChain4j +## Cum folosește acest lucru LangChain4j -Acest modul extinde quick start-ul prin integrarea Spring Boot și adăugarea memoriei conversației. Iată cum se leagă piesele: +Acest modul integrează Spring Boot și adaugă memorie pentru conversații. Iată cum se combină piesele: **Dependențe** - Adaugă două biblioteci LangChain4j: @@ -94,7 +94,7 @@ Acest modul extinde quick start-ul prin integrarea Spring Boot și adăugarea me ``` -**Modelul Chat** - Configurează Azure OpenAI ca bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Model Chat** - Configurează Azure OpenAI ca bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder-ul citește acreditările din variabilele de mediu setate de `azd up`. Setarea `baseUrl` la endpoint-ul Azure face ca clientul OpenAI să funcționeze cu Azure OpenAI. +Builder-ul citește credențialele din variabilele de mediu setate de `azd up`. Setarea `baseUrl` spre endpoint-ul tău Azure face ca clientul OpenAI să funcționeze cu Azure OpenAI. -**Memoria Conversației** - Urmărește istoricul chat-ului cu MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Memorie conversație** - Urmărește istoricul chat-ului cu MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,16 +124,16 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Crează memoria cu `withMaxMessages(10)` pentru a păstra ultimele 10 mesaje. Adaugă mesaje de utilizator și AI cu wrapper-e tipizate: `UserMessage.from(text)` și `AiMessage.from(text)`. Recuperează istoricul cu `memory.messages()` și trimite-l modelului. Serviciul păstrează instanțe de memorie separate per ID conversație, permițând mai multor utilizatori să chateze simultan. +Creează memoria cu `withMaxMessages(10)` pentru a păstra ultimele 10 mesaje. Adaugă mesajele utilizatorului și AI-ului cu învelișuri tipizate: `UserMessage.from(text)` și `AiMessage.from(text)`. Recuperează istoricul cu `memory.messages()` și trimite-l modelului. Serviciul stochează instanțe distincte de memorie pentru fiecare ID de conversație, permițând mai multor utilizatori să converseze simultan. > **🤖 Încearcă cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschide [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) și întreabă: -> - „Cum decide MessageWindowChatMemory ce mesaje elimină când fereastra este plină?” -> - „Pot implementa o stocare personalizată a memoriei folosind o bază de date în loc de memorie internă?” -> - „Cum aș adăuga sumarizare pentru a comprima istoricul vechi al conversației?” +> - "Cum decide MessageWindowChatMemory ce mesaje să elimine când fereastra este plină?" +> - "Pot implementa o stocare personalizată a memoriei folosind o bază de date în loc de memorie în RAM?" +> - "Cum aș putea adăuga sumarizare pentru a comprima istoricul conversațiilor vechi?" -Endpoint-ul stateless omite complet memoria - doar `chatModel.chat(prompt)`, ca în quick start. Endpoint-ul stateful adaugă mesaje în memorie, recuperează istoricul și include contextul cu fiecare cerere. Aceeași configurare model, tipare diferite. +Endpoint-ul pentru chat fără stare ignoră complet memoria - doar `chatModel.chat(prompt)` ca în startul rapid. Endpoint-ul pentru chat cu stare adaugă mesaje în memorie, recuperează istoricul și include acel context cu fiecare cerere. Aceeași configurație model, modele diferite. -## Deplasează Infrastructura Azure OpenAI +## Implementarea infrastructurii Azure OpenAI **Bash:** ```bash @@ -144,19 +144,19 @@ azd up # Selectați abonamentul și locația (recomandat eastus2) **PowerShell:** ```powershell cd 01-introduction -azd up # Selectați abonamentul și locația (eastus2 recomandat) +azd up # Selectați abonamentul și locația (se recomandă eastus2) ``` -> **Notă:** Dacă întâmpini o eroare de timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), rulează pur și simplu `azd up` din nou. Resursele Azure pot fi încă în curs de aprovizionare în fundal și reluarea comenzii permite finalizarea deploy-ului odată ce resursele ajung într-o stare terminală. +> **Notă:** Dacă întâmpini o eroare de timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), pur și simplu rulează din nou `azd up`. Resursele Azure pot fi încă în proces de configurare în fundal, iar o nouă încercare va permite finalizarea implementării odată ce resursele ajung într-o stare terminală. Aceasta va: -1. Deplasa resursa Azure OpenAI cu modelele GPT-5.2 și text-embedding-3-small -2. Genera automat fișierul `.env` în rădăcina proiectului cu acreditările -3. Configura toate variabilele de mediu necesare +1. Implementa resursa Azure OpenAI cu modelele GPT-5.2 și text-embedding-3-small +2. Va genera automat fișierul `.env` în rădăcina proiectului cu credențiale +3. Va configura toate variabilele de mediu necesare -**Ai probleme cu deploy-ul?** Consultă [README-ul pentru Infrastructură](infra/README.md) pentru depanare detaliată incluzând conflicte de nume subdomeniu, pași manuali de deploy în Azure Portal și ghidaj pentru configurarea modelului. +**Ai probleme cu implementarea?** Vezi [Infrastructure README](infra/README.md) pentru detalii despre depanare, inclusiv conflicte legate de numele subdomeniilor, pași manuali pentru implementarea în Azure Portal și ghid pentru configurarea modelului. -**Verifică dacă deploy-ul a reușit:** +**Verifică dacă implementarea a reușit:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Ar trebui să afișeze AZURE_OPENAI_ENDPOINT, API_KEY, etc. Get-Content ..\.env # Ar trebui să afișeze AZURE_OPENAI_ENDPOINT, API_KEY, etc. ``` -> **Notă:** Comanda `azd up` generează automat fișierul `.env`. Dacă trebuie să îl actualizezi ulterior, poți fie să îl editezi manual, fie să-l regenerezi rulând: +> **Notă:** Comanda `azd up` generează automat fișierul `.env`. Dacă trebuie să îl actualizezi ulterior, poți edita manual fișierul `.env` sau îl poți regenera rulând: > > **Bash:** > ```bash @@ -182,11 +182,11 @@ Get-Content ..\.env # Ar trebui să afișeze AZURE_OPENAI_ENDPOINT, API_KEY, et > .\.azd-env.ps1 > ``` -## Rulează Aplicația Local +## Rularea aplicației local -**Verifică deploy-ul:** +**Verifică implementarea:** -Asigură-te că fișierul `.env` există în directorul rădăcină cu acreditările Azure. Rulează din directorul modulului (`01-introduction/`): +Asigură-te că fișierul `.env` există în directorul rădăcină cu credențiale Azure. Rulează din directorul modulului (`01-introduction/`): **Bash:** ```bash @@ -200,21 +200,21 @@ Get-Content ..\.env # Ar trebui să afișeze AZURE_OPENAI_ENDPOINT, API_KEY, DE **Pornește aplicațiile:** -**Opțiunea 1: Folosind Spring Boot Dashboard (Recomandat pentru utilizatorii VS Code)** +**Opțiunea 1: Folosind Spring Boot Dashboard (recomandat pentru utilizatorii VS Code)** -Dev container-ul include extensia Spring Boot Dashboard, care oferă o interfață vizuală pentru gestionarea tuturor aplicațiilor Spring Boot. O vei găsi în bara de activități din stânga VS Code (caută iconița Spring Boot). +Dev container-ul include extensia Spring Boot Dashboard, care oferă o interfață vizuală pentru gestionarea tuturor aplicațiilor Spring Boot. O poți găsi în bara de activități din partea stângă a VS Code (caută iconița Spring Boot). -Din Spring Boot Dashboard poți: -- Vizualiza toate aplicațiile Spring Boot disponibile în workspace -- Porni/opri aplicații cu un singur click -- Vizualiza log-urile aplicației în timp real +Din Spring Boot Dashboard, poți: +- Vizualiza toate aplicațiile Spring Boot disponibile în spațiul de lucru +- Porni/opri aplicațiile cu un singur clic +- Vizualiza jurnalele aplicațiilor în timp real - Monitoriza starea aplicațiilor -Pur și simplu apasă butonul de play de lângă „introduction” pentru a porni acest modul sau pornește toate modulele simultan. +Pur și simplu fă clic pe butonul de redare de lângă "introduction" pentru a porni acest modul, sau pornește toate modulele simultan. -Spring Boot Dashboard +Panoul de control Spring Boot -*Spring Boot Dashboard în VS Code — pornește, oprește și monitorizează toate modulele dintr-un singur loc* +*Panoul Spring Boot Dashboard în VS Code — pornește, oprește și monitorizează toate modulele dintr-un singur loc* **Opțiunea 2: Folosind scripturi shell** @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Ambele scripturi încarcă automat variabilele de mediu din fișierul `.env` rădăcină și vor compila JAR-urile dacă nu există. +Ambele scripturi încarcă automat variabilele de mediu din fișierul `.env` de la rădăcină și vor construi JAR-urile dacă nu există. -> **Notă:** Dacă preferi să construiești manual toate modulele înainte să pornești: +> **Notă:** Dacă preferi să compilezi manual toate modulele înainte de rulare: > > **Bash:** > ```bash @@ -262,61 +262,61 @@ Ambele scripturi încarcă automat variabilele de mediu din fișierul `.env` ră > mvn clean package -DskipTests > ``` -Deschide în browser http://localhost:8080. +Deschide http://localhost:8080 în browser. **Pentru oprire:** **Bash:** ```bash -./stop.sh # Acest modul numai +./stop.sh # Doar acest modul # Sau cd .. && ./stop-all.sh # Toate modulele ``` **PowerShell:** ```powershell -.\stop.ps1 # Numai acest modul +.\stop.ps1 # Doar acest modul # Sau cd ..; .\stop-all.ps1 # Toate modulele ``` -## Folosirea Aplicației +## Folosirea aplicației -Aplicația oferă o interfață web cu două implementări de chat afișate alăturat. +Aplicația oferă o interfață web cu două implementări de chat afișate una lângă cealaltă. -Ecranul Principal al Aplicației +Ecranul principal al aplicației -*Dashboard care arată opțiunile Simple Chat (stateless) și Conversational Chat (stateful)* +*Panou de control care afișează atât opțiunea de Chat Simplu (fără stare), cât și Chat Conversațional (cu stare)* -### Chat Stateless (Panoul Stâng) +### Chat fără stare (panoul din stânga) -Încearcă asta prima dată. Spune „Numele meu este John” și apoi imediat „Care este numele meu?” Modelul nu își va aminti deoarece fiecare mesaj este independent. Aceasta demonstrează problema de bază a integrării simple a modelului de limbaj - fără context conversațional. +Încearcă asta primul. Spune "Numele meu este John" și apoi imediat întreabă "Care este numele meu?" Modelul nu va reține deoarece fiecare mesaj este independent. Aceasta demonstrează problema principală a integrării simple cu modele de limbaj - lipsa contextului conversației. -Demo Chat Stateless +Demo chat fără stare -*AI nu își amintește numele tău din mesajul anterior* +*AI nu își amintește numele spus anterior* -### Chat Stateful (Panoul Drept) +### Chat cu stare (panoul din dreapta) -Acum încearcă aceeași secvență aici. Spune „Numele meu este John” și apoi „Care este numele meu?” De data aceasta modelul își amintește. Diferența este MessageWindowChatMemory - aceasta menține istoricul conversației și îl include în fiecare cerere. Așa funcționează AI-ul conversațional în producție. +Acum încearcă aceeași secvență aici. Spune "Numele meu este John" și apoi "Care este numele meu?" De data aceasta îl reține. Diferența o face MessageWindowChatMemory - păstrează istoricul conversației și îl include cu fiecare cerere. Așa funcționează AI conversațional în producție. -Demo Chat Stateful +Demo chat cu stare -*AI își amintește numele tău din conversația anterioară* +*AI își amintește numele spus anterior în conversație* -Ambele panouri folosesc același model GPT-5.2. Singura diferență este memoria. Acest lucru clarifică ce aduce memorie aplicației tale și de ce este esențială în cazurile reale de utilizare. +Ambele panouri folosesc același model GPT-5.2. Singura diferență este memoria. Acest lucru face clar ce aduce memoria aplicației tale și de ce este esențială pentru cazurile reale de utilizare. -## Pașii Următori +## Pașii următori -**Următorul Modul:** [02-prompt-engineering - Ingineria Prompt-urilor cu GPT-5.2](../02-prompt-engineering/README.md) +**Următorul modul:** [02-prompt-engineering - Ingineria prompt-ului cu GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigare:** [← Anterior: Modul 00 - Quick Start](../00-quick-start/README.md) | [Înapoi la Principal](../README.md) | [Următorul: Modul 02 - Ingineria Prompt-urilor →](../02-prompt-engineering/README.md) +**Navigare:** [← Înapoi la Principal](../README.md) | [Următor: Modulul 02 - Ingineria Prompt-ului →](../02-prompt-engineering/README.md) --- -**Declinare de responsabilitate**: -Acest document a fost tradus folosind serviciul de traducere automată AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autoritară. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist uman. Nu ne asumăm răspunderea pentru eventuale neînțelegeri sau interpretări greșite apărute în urma utilizării acestei traduceri. +**Declinare a responsabilității**: +Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri. \ No newline at end of file diff --git a/translations/ro/02-prompt-engineering/README.md b/translations/ro/02-prompt-engineering/README.md index 86cfb0aa5..7f09a6b12 100644 --- a/translations/ro/02-prompt-engineering/README.md +++ b/translations/ro/02-prompt-engineering/README.md @@ -1,81 +1,81 @@ -# Modulul 02: Ingineria prompturilor cu GPT-5.2 +# Modulul 02: Ingineria Prompturilor cu GPT-5.2 ## Cuprins -- [Prezentare video](../../../02-prompt-engineering) -- [Ce vei învăța](../../../02-prompt-engineering) -- [Prerechizite](../../../02-prompt-engineering) -- [Înțelegerea Ingineriei Prompturilor](../../../02-prompt-engineering) -- [Fundamentele Ingineriei Prompturilor](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Șabloane de Prompturi](../../../02-prompt-engineering) -- [Modele avansate](../../../02-prompt-engineering) -- [Rulează aplicația](../../../02-prompt-engineering) -- [Capturi de ecran ale aplicației](../../../02-prompt-engineering) -- [Explorarea modelelor](../../../02-prompt-engineering) - - [Eageritate scăzută vs ridicată](../../../02-prompt-engineering) - - [Executarea sarcinilor (preambuluri pentru instrumente)](../../../02-prompt-engineering) - - [Cod cu auto-reflecție](../../../02-prompt-engineering) - - [Analiză structurată](../../../02-prompt-engineering) - - [Chat în mai multe runde](../../../02-prompt-engineering) - - [Raționament pas cu pas](../../../02-prompt-engineering) - - [Ieșire constrânsă](../../../02-prompt-engineering) -- [Ce înveți cu adevărat](../../../02-prompt-engineering) -- [Pașii următori](../../../02-prompt-engineering) - -## Prezentare video +- [Parcurgere Video](#parcurgere-video) +- [Ce Vei Învăța](#ce-vei-învăța) +- [Precondiții](#precondiții) +- [Înțelegerea Ingineriei Prompturilor](#înțelegerea-ingineriei-prompturilor) +- [Fundamentele Ingineriei Prompturilor](#fundamentele-ingineriei-prompturilor) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Șabloane de Prompturi](#șabloane-de-prompturi) +- [Modele Avansate](#modele-avansate) +- [Rularea Aplicației](#rulează-aplicația) +- [Capturi de Ecran ale Aplicației](#capturi-de-ecran-ale-aplicației) +- [Explorarea Modelelor](#explorarea-modelelor) + - [Energie Joasă vs Energie Ridicată](#low-vs-high-eagerness) + - [Execuția Sarcinilor (Premisele Instrumentelor)](#executarea-sarcinilor-introductive-de-instrument) + - [Cod ce Reflectă asupra Sa](#cod-auto-reflectiv) + - [Analiză Structurată](#analiză-structurată) + - [Chat cu Tururi Multiple](#chat-multi-rundă) + - [Raționament Pas cu Pas](#raționament-pas-cu-pas) + - [Output Constrâns](#output-constrâns) +- [Ce Înveți Cu Adevărat](#ce-înveți-cu-adevărat) +- [Pașii Următori](#pașii-următori) + +## Parcurgere Video Urmărește această sesiune live care explică cum să începi cu acest modul: Prompt Engineering with LangChain4j - Live Session -## Ce vei învăța +## Ce Vei Învăța -Diagrama următoare oferă o privire de ansamblu asupra subiectelor cheie și abilităților pe care le vei dezvolta în acest modul — de la tehnicile de rafinare a prompturilor până la fluxul de lucru pas cu pas pe care îl vei urma. +Diagrama următoare oferă o privire de ansamblu asupra subiectelor și abilităților cheie pe care le vei dezvolta în acest modul — de la tehnici de rafinare a prompturilor până la fluxul de lucru pas cu pas pe care îl vei urma. -What You'll Learn +Ce Vei Învăța -În modulele anterioare, ai explorat interacțiuni de bază LangChain4j cu GitHub Models și ai văzut cum memoria permite AI conversațional cu Azure OpenAI. Acum ne vom concentra pe cum formulezi întrebările — prompturile propriu-zise — folosind GPT-5.2 de la Azure OpenAI. Modul în care structurezi prompturile afectează dramatic calitatea răspunsurilor primite. Începem cu o revizuire a tehnicilor fundamentale de prompting, apoi trecem la opt modele avansate care valorifică pe deplin capacitățile GPT-5.2. +În modulul precedent, ai văzut cum memoria permite AI conversațional cu Azure OpenAI. Acum ne vom concentra pe cum pui întrebări — pe prompturile în sine — folosind GPT-5.2 de la Azure OpenAI. Modul în care îți structurezi prompturile afectează dramatic calitatea răspunsurilor pe care le primești. Începem cu o recenzie a tehnicilor fundamentale de prompting, apoi trecem la opt modele avansate care valorifică pe deplin capabilitățile GPT-5.2. -Vom folosi GPT-5.2 deoarece introduce controlul raționamentului - poți spune modelului cât să gândească înainte să răspundă. Aceasta face diversele strategii de prompting mai evidente și te ajută să înțelegi când să folosești fiecare abordare. Vom beneficia și de mai puține limite de rată la Azure pentru GPT-5.2 comparativ cu modelele GitHub. +Vom folosi GPT-5.2 pentru că introduce controlul raționamentului – poți spune modelului cât de mult să gândească înainte de a răspunde. Aceasta face strategiile diferite de prompting mai evidente și te ajută să înțelegi când să folosești fiecare abordare. -## Prerechizite +## Precondiții -- Modulul 01 finalizat (resurse Azure OpenAI implementate) +- Modului 01 finalizat (resurse Azure OpenAI implementate) - Fișier `.env` în directorul rădăcină cu acreditările Azure (creat de `azd up` în Modulul 01) -> **Notă:** Dacă nu ai finalizat Modulul 01, urmează mai întâi instrucțiunile de implementare din acolo. +> **Notă:** Dacă nu ai terminat Modulul 01, urmează mai întâi instrucțiunile de implementare de acolo. ## Înțelegerea Ingineriei Prompturilor -În esență, ingineria prompturilor este diferența dintre instrucțiuni vagi și precise, după cum ilustrează comparația de mai jos. +La bază, ingineria prompturilor este diferența între instrucțiuni vagi și precise, după cum ilustrează comparația de mai jos. -What is Prompt Engineering? +Ce este Ingineria Prompturilor? -Ingineria prompturilor ține de proiectarea textului de intrare care îți oferă în mod constant rezultatele dorite. Nu este doar despre a pune întrebări - este despre structurarea cererilor astfel încât modelul să înțeleagă exact ce dorești și cum să livreze. +Ingineria prompturilor înseamnă proiectarea textului de intrare care să-ți ofere consecvent rezultatele de care ai nevoie. Nu este vorba doar despre a pune întrebări - ci despre structurarea cererilor astfel încât modelul să înțeleagă exact ce vrei și cum să-l livreze. -Gândește-te la asta ca la a da instrucțiuni unui coleg. "Remediază bug-ul" este vag. "Rezolvă excepția null pointer în UserService.java linia 45 prin adăugarea unui control pentru null" este specific. Modelele lingvistice funcționează la fel - specificitatea și structura contează. +Gândește-te la asta ca la oferirea de instrucțiuni unui coleg. „Rezolvă bug-ul” e vag. „Rezolvă excepția null pointer în UserService.java, linia 45, adăugând o verificare null” este specific. Modelele de limbaj funcționează la fel – specificitatea și structura contează. -Diagrama de mai jos arată cum se încadrează LangChain4j în acest tablou — conectând modelele tale de prompturi la model prin blocuri de construcție SystemMessage și UserMessage. +Diagrama de mai jos arată cum se integrează LangChain4j în această imagine — conectând modelele de prompt la model prin blocuri de construcție SystemMessage și UserMessage. -How LangChain4j Fits +Cum se Integrează LangChain4j -LangChain4j oferă infrastructura — conexiuni la modele, memorie și tipuri de mesaje — în timp ce modelele de prompturi sunt doar texte atent structurate pe care le trimiți prin acea infrastructură. Blocurile cheie sunt `SystemMessage` (care setează comportamentul și rolul AI-ului) și `UserMessage` (care conține cererea ta efectivă). +LangChain4j oferă infrastructura — conexiuni cu modelul, memorie și tipuri de mesaje — în timp ce modelele de prompt sunt doar text structurat cu grijă pe care îl trimiți prin acea infrastructură. Blocurile de construcție cheie sunt `SystemMessage` (care setează comportamentul și rolul AI-ului) și `UserMessage` (care poartă cererea ta efectivă). ## Fundamentele Ingineriei Prompturilor -Cele cinci tehnici de bază prezentate mai jos formează fundamentul ingineriei eficiente a prompturilor. Fiecare abordează un aspect diferit al modului în care comunici cu modelele lingvistice. +Cele cinci tehnici de bază prezentate mai jos formează temelia unei inginerii eficiente a prompturilor. Fiecare abordează un aspect diferit al modului în care comunici cu modelele de limbaj. -Five Prompt Engineering Patterns Overview +Privire de ansamblu asupra celor Cinci Modele de Inginerie de Prompt -Înainte să explorăm modelele avansate din acest modul, să revizuim cele cinci tehnici fundamentale de prompting. Acestea sunt blocurile de construcție pe care orice inginer de prompturi ar trebui să le cunoască. Dacă ai parcurs deja modulul [Quick Start](../00-quick-start/README.md#2-prompt-patterns), le-ai văzut în acțiune — iată cadrul conceptual din spatele lor. +Înainte de a trece la modelele avansate din acest modul, să revizuim cinci tehnici fundamentale de prompting. Acestea sunt pietrele de temelie pe care orice inginer de prompturi ar trebui să le cunoască. ### Zero-Shot Prompting -Abordarea cea mai simplă: oferă modelului o instrucțiune directă fără exemple. Modelul se bazează exclusiv pe antrenamentul său pentru a înțelege și executa sarcina. Funcționează bine pentru cereri simple unde comportamentul așteptat este evident. +Cea mai simplă abordare: dă modelului o instrucțiune directă fără exemple. Modelul se bazează complet pe antrenamentul său pentru a înțelege și executa sarcina. Aceasta funcționează bine pentru cereri simple, unde comportamentul așteptat este evident. Zero-Shot Prompting @@ -91,11 +91,11 @@ String response = model.chat(prompt); ### Few-Shot Prompting -Oferă exemple care demonstrează tiparul pe care vrei modelul să-l urmeze. Modelul învață formatul de intrare-ieșire așteptat din exemplele tale și îl aplică la intrări noi. Aceasta îmbunătățește dramatic consistența pentru sarcini unde formatul sau comportamentul dorit nu sunt evidente. +Oferă exemple care demonstrează modelul pe care vrei să-l urmeze modelul. Modelul învață formatul așteptat intrare-ieșire din exemplele tale și îl aplică pentru noile intrări. Aceasta îmbunătățește dramatic consistența pentru sarcini în care formatul sau comportamentul dorit nu sunt evidente. Few-Shot Prompting -*Învățarea din exemple — modelul identifică tiparul și îl aplică la intrări noi* +*Învață din exemple — modelul identifică modelul și îl aplică la noile intrări* ```java String prompt = """ @@ -112,11 +112,11 @@ String prompt = """ String response = model.chat(prompt); ``` -**Când să folosești:** Clasificări personalizate, formatări consistente, sarcini specifice domeniului sau când rezultatele zero-shot sunt inconsistente. +**Când să folosești:** Clasificări personalizate, formatare consistentă, sarcini specifice domeniului sau când rezultatele zero-shot sunt inconsistente. ### Chain of Thought -Cere modelului să arate raționamentul său pas cu pas. În loc sări direct la un răspuns, modelul descompune problema și lucrează prin fiecare parte explicit. Aceasta îmbunătățește acuratețea la probleme matematice, logice și de raționament în mai mulți pași. +Cere modelului să-și arate raționamentul pas cu pas. În loc să sară direct la un răspuns, modelul descompune problema și parcurge fiecare parte explicit. Aceasta îmbunătățește acuratețea la probleme matematice, de logică și raționamente în mai mulți pași. Chain of Thought Prompting @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Modelul arată: 15 - 8 = 7, apoi 7 + 12 = 19 mere ``` -**Când să folosești:** Probleme de matematică, puzzle-uri logice, depanare sau orice sarcină unde afișarea procesului de raționament îmbunătățește acuratețea și încrederea. +**Când să folosești:** Probleme de matematică, puzzle-uri logice, depanare sau orice sarcină unde arătarea procesului de raționament crește acuratețea și încrederea. ### Role-Based Prompting -Setează o persona sau un rol pentru AI înainte de a pune întrebarea ta. Aceasta oferă context care modelează tonul, profunzimea și accentul răspunsului. Un „arhitect software” oferă sfaturi diferite de un „dezvoltator junior” sau un „auditor de securitate”. +Setează o persoană sau un rol pentru AI înainte de a pune întrebarea. Aceasta oferă context care modelează tonul, profunzimea și focalizarea răspunsului. Un „arhitect software” oferă sfaturi diferite față de un „dezvoltator junior” sau un „auditor de securitate”. Role-Based Prompting -*Setarea contextului și a personajului — aceeași întrebare primește răspunsuri diferite în funcție de rolul atribuit* +*Setarea contextului și a persoanei — aceeași întrebare primește răspuns diferit în funcție de rol* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Când să folosești:** Revizuiri de cod, meditații, analize specifice domeniului sau când ai nevoie de răspunsuri adaptate unui anumit nivel de expertiză sau perspectivă. +**Când să folosești:** Revizuiri de cod, tutoring, analize specifice domeniului sau când ai nevoie de răspunsuri adaptate unui anumit nivel de expertiză sau perspectivă. ### Șabloane de Prompturi -Creează prompturi reutilizabile cu variabile. În loc să scrii un prompt nou de fiecare dată, definește o șablon o singură dată și completează valori diferite. Clasa `PromptTemplate` din LangChain4j face acest lucru ușor cu sintaxa `{{variable}}`. +Creează prompturi reutilizabile cu variabile. În loc să scrii un prompt nou de fiecare dată, definește un șablon odată și completează cu valori diferite. Clasa `PromptTemplate` din LangChain4j face acest lucru ușor cu sintaxa `{{variable}}`. -Prompt Templates +Șabloane de Prompturi -*Prompturi reutilizabile cu variabile — un șablon, multe utilizări* +*Prompturi reutilizabile cu locuri pentru variabile — un șablon, multe utilizări* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Când să folosești:** Interogări repetitive cu intrări diferite, procesare în lot, construirea de fluxuri AI reutilizabile sau orice scenariu unde structura promptului rămâne aceeași, dar datele se schimbă. +**Când să folosești:** Interogări repetate cu intrări diferite, procesare pe loturi, construirea de fluxuri de lucru AI reutilizabile sau orice scenariu unde structura promptului rămâne aceeași, dar datele se schimbă. --- -Aceste cinci fundamentale îți oferă un set solid de unelte pentru majoritatea sarcinilor de prompting. Restul modulului se bazează pe ele cu **opt modele avansate** care valorifică controlul raționamentului, auto-evaluarea și capacitățile de ieșire structurate ale GPT-5.2. +Aceste cinci fundamentale îți oferă un set solid de instrumente pentru majoritatea sarcinilor de prompting. Restul modulului se construiește pe ele cu **opt modele avansate** care valorifică controlul raționamentului, autoevaluarea și capabilitățile de output structurat ale GPT-5.2. -## Modele avansate +## Modele Avansate -Odată acoperite fundamentele, să trecem la cele opt modele avansate care fac acest modul unic. Nu toate problemele necesită aceeași abordare. Unele întrebări au nevoie de răspunsuri rapide, altele de gândire profundă. Unele cer raționament vizibil, altele doar rezultate. Fiecare model de mai jos este optimizat pentru un scenariu diferit — iar controlul raționamentului din GPT-5.2 face diferențele și mai evidente. +După ce fundamentele au fost acoperite, să trecem la cele opt modele avansate care fac acest modul unic. Nu toate problemele necesită aceeași abordare. Unele întrebări cer răspunsuri rapide, altele gândire profundă. Unele cer raționament vizibil, altele doar rezultate. Fiecare model de mai jos este optimizat pentru un scenariu diferit — iar controlul raționamentului al GPT-5.2 face diferențele și mai evidente. -Eight Prompting Patterns +Opt Modele de Prompting -*Privire de ansamblu asupra celor opt modele de inginerie a prompturilor și cazurile lor de utilizare* +*Privire de ansamblu asupra celor opt modele de inginerie prompt și cazurile lor de utilizare* -GPT-5.2 adaugă o dimensiune suplimentară acestor modele: *controlul raționamentului*. Glisorul de mai jos arată cum poți ajusta efortul de gândire al modelului — de la răspunsuri rapide și directe la analize profunde și detaliate. +GPT-5.2 adaugă o dimensiune suplimentară acestor modele: *controlul raționamentului*. Glisorul de mai jos arată cum poți ajusta efortul de gândire al modelului — de la răspunsuri rapide și directe până la analiză profundă și temeinică. -Reasoning Control with GPT-5.2 +Controlul raționamentului cu GPT-5.2 -*Controlul raționamentului GPT-5.2 îți permite să specifici cât trebuie să gândească modelul — de la răspunsuri rapide și directe la explorare profundă* +*Controlul raționamentului GPT-5.2 îți permite să specifici cât de multă gândire să facă modelul — de la răspunsuri rapide și directe la explorare profundă* -**Eageritate scăzută (rapid și concentrat)** - Pentru întrebări simple unde vrei răspunsuri rapide și directe. Modelul face raționament minim - maxim 2 pași. Folosește asta pentru calcule, căutări sau întrebări directe. +**Energie Joasă (Rapid & Focalizat)** - Pentru întrebări simple unde vrei răspunsuri rapide și directe. Modelul face un raționament minimal - maxim 2 pași. Folosește asta pentru calcule, căutări sau întrebări simple. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Explorează cu GitHub Copilot:** Deschide [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) și întreabă: -> - "Care este diferența dintre modelele de prompt cu eageritate scăzută și cele cu eageritate ridicată?" +> - "Care este diferența dintre modelele de prompting cu energie joasă și cea ridicată?" > - "Cum ajută etichetele XML din prompturi la structurarea răspunsului AI?" -> - "Când ar trebui să folosesc modelele de auto-reflecție versus instrucțiunea directă?" +> - "Când ar trebui să folosesc modelele de auto-reflecție vs instrucțiuni directe?" -**Eageritate ridicată (profund și temeinic)** - Pentru probleme complexe unde dorești o analiză cuprinzătoare. Modelul explorează temeinic și arată raționamente detaliate. Folosește asta pentru proiectarea sistemelor, decizii de arhitectură sau cercetări complexe. +**Energie Ridicată (Profund & Temeinic)** - Pentru probleme complexe unde vrei o analiză cuprinzătoare. Modelul explorează temeinic și arată raționamentul detaliat. Folosește asta pentru proiectarea sistemelor, decizii de arhitectură sau cercetare complexă. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Executarea sarcinilor (progres pas cu pas)** - Pentru fluxuri de lucru în mai mulți pași. Modelul oferă un plan inițial, povestește fiecare pas pe măsură ce îl execută, apoi oferă un rezumat. Folosește asta pentru migrații, implementări sau orice proces în mai mulți pași. +**Execuția Sarcinii (Progres Pas cu Pas)** - Pentru fluxuri de lucru în mai mulți pași. Modelul oferă un plan inițial, povestește fiecare pas pe măsură ce lucrează, apoi oferă un rezumat. Folosește asta pentru migrații, implementări sau orice proces în mai mulți pași. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Prompting-ul Chain-of-Thought cere explicit modelului să-și arate procesul de raționament, îmbunătățind acuratețea pentru sarcini complexe. Descompunerea pas cu pas ajută atât oamenii, cât și AI-ul să înțeleagă logica. +Promptul Chain-of-Thought cere explicit modelului să arate procesul său de raționament, îmbunătățind precizia pentru sarcini complexe. Descompunerea pas cu pas ajută atât oamenii, cât și AI să înțeleagă logica. -> **🤖 Încearcă cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Întreabă despre acest model: -> - "Cum aș adapta modelul de executare a sarcinii pentru operațiuni de durată lungă?" -> - "Care sunt cele mai bune practici pentru structurarea preambulurilor instrumentelor în aplicații de producție?" +> **🤖 Încearcă cu Chat-ul [GitHub Copilot](https://github.com/features/copilot):** Întreabă despre acest model: +> - "Cum aș adapta modelul de execuție a sarcinii pentru operațiuni de durată lungă?" +> - "Care sunt bunele practici pentru structurarea premiselor instrumentelor în aplicații de producție?" > - "Cum pot captura și afișa actualizări de progres intermediare într-o interfață?" -Diagrama de mai jos ilustrează acest flux Plan → Execută → Rezumă. +Diagrama de mai jos ilustrează acest flux Planificare → Execuție → Rezumare. -Task Execution Pattern +Modelul de Execuție a Sarcinii -*Flux Plan → Execută → Rezumă pentru sarcini în pași multipli* +*Flux Planificare → Execuție → Rezumare pentru sarcini în mai mulți pași* -**Cod cu auto-reflecție** - Pentru generarea de cod de calitate de producție. Modelul generează cod conform standardelor de producție cu gestionare corespunzătoare a erorilor. Folosește asta când construiești funcționalități sau servicii noi. +**Cod ce Reflectă asupra Sa** - Pentru generarea de cod de calitate pentru producție. Modelul generează cod urmând standarde de producție cu gestionarea corectă a erorilor. Folosește asta când creezi funcționalități noi sau servicii. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagrama următoare arată acest ciclu iterativ de îmbunătățire — generează, evaluează, identifică punctele slabe și rafinează până când codul atinge standardele de producție. +Diagrama de mai jos arată acest ciclu iterativ de îmbunătățire — generează, evaluează, identifică punctele slabe și rafinează până când codul îndeplinește standardele de producție. -Self-Reflection Cycle +Ciclul de Auto-Reflecție *Ciclu iterativ de îmbunătățire - generează, evaluează, identifică probleme, îmbunătățește, repetă* -**Analiză structurată** - Pentru evaluare consistentă. Modelul revizuiește codul folosind un cadru fix (corectitudine, practici, performanță, securitate, mentenabilitate). Folosește asta pentru code review-uri sau evaluări de calitate. +**Analiză Structurată** - Pentru evaluare consistentă. Modelul revizuiește codul folosind un cadru fix (corectitudine, practici, performanță, securitate, întreținere). Folosește asta pentru revizuiri de cod sau evaluări de calitate. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Încearcă cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Întreabă despre analiza structurată: +> **🤖 Încearcă cu Chat-ul [GitHub Copilot](https://github.com/features/copilot):** Întreabă despre analiza structurată: > - "Cum pot personaliza cadrul de analiză pentru diferite tipuri de revizuiri de cod?" -> - "Care este cea mai bună metodă de a parsa și acționa pe baza ieșirii structurate programatic?" -> - "Cum asigur un nivel consistent de severitate în sesiuni diferite de revizuire?" +> - "Care este cea mai bună metodă de a parsa și acționa pe output structurat programatic?" +> - "Cum asigur niveluri consistente de severitate în diferite sesiuni de revizuire?" Diagrama următoare arată cum acest cadru structurat organizează o revizuire de cod în categorii consistente cu nivele de severitate. -Structured Analysis Pattern +Modelul de Analiză Structurată -*Cadru pentru revizuiri consistente ale codului cu nivele de severitate* +*Cadru pentru revizuiri de cod consistente cu nivele de severitate* -**Chat în mai multe runde** - Pentru conversații care necesită context. Modelul își amintește mesajele anterioare și le construiește pe ele. Folosește asta pentru sesiuni interactive de asistență sau Q&A complexe. +**Chat cu Tururi Multiple** - Pentru conversații care necesită context. Modelul își amintește mesajele anterioare și construiește pe baza lor. Folosește asta pentru sesiuni de ajutor interactive sau întrebări complexe. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Diagrama de mai jos vizualizează cum se acumulează contextul conversației cu fiecare tură și cum se raportează la limita de tokeni a modelului. +Diagrama de mai jos vizualizează cum contextul conversației se acumulează cu fiecare tur și cum se raportează la limita de tokeni a modelului. -Context Memory +Memoria Contextului -*Cum se acumulează contextul conversației peste mai multe runde până la atingerea limitei de tokeni* -**Raționament Pas cu Pas** - Pentru probleme care necesită logică vizibilă. Modelul arată raționamentul explicit pentru fiecare pas. Folosește asta pentru probleme de matematică, puzzle-uri logice sau când ai nevoie să înțelegi procesul de gândire. +*Cum se acumulează contextul conversației pe mai multe tururi până la atingerea limitei de tokeni* + +**Raționament Pas cu Pas** - Pentru probleme care cer logică vizibilă. Modelul arată raționamentul explicit pentru fiecare pas. Folosește asta pentru probleme matematice, puzzle-uri logice sau când ai nevoie să înțelegi procesul de gândire. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagrama de mai jos ilustrează cum modelul descompune problemele în pași logici expliciți, numerotați. - -Tipar Pas cu Pas +Diagrama de mai jos ilustrează cum modelul descompune problemele în pași logici numerotați explicit. +Modelul Pas cu Pas *Descompunerea problemelor în pași logici expliciți* -**Rezultat Constrâns** - Pentru răspunsuri cu cerințe specifice de format. Modelul urmează cu strictețe regulile de format și lungime. Folosește asta pentru rezumate sau când ai nevoie de o structură precisă a rezultatului. +**Output Constrâns** - Pentru răspunsuri cu cerințe specifice de format. Modelul respectă strict regulile de format și lungime. Folosește asta pentru rezumate sau când ai nevoie de o structură precisă a outputului. ```java String prompt = """ @@ -420,43 +420,43 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagrama următoare arată cum constrângerile ghidează modelul să producă un rezultat care respectă cu strictețe cerințele tale de format și lungime. +Diagrama următoare arată cum constrângerile ghidează modelul să producă un output care respectă strict cerințele tale de format și lungime. -Tipar Rezultat Constrâns +Model de Output Constrâns -*Impunerea cerințelor specifice de format, lungime și structură* +*Aplicarea cerințelor specifice de format, lungime și structură* ## Rulează Aplicația **Verifică implementarea:** -Asigură-te că fișierul `.env` există în directorul rădăcină cu acreditările Azure (create în Modulul 01). Rulează de aici din directorul modulului (`02-prompt-engineering/`): +Asigură-te că fișierul `.env` există în directorul rădăcină cu datele de autentificare Azure (create în timpul Modulului 01). Rulează din directorul modulului (`02-prompt-engineering/`): -**Bash:** +**Bash:** ```bash cat ../.env # Ar trebui să afișeze AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Ar trebui să afișeze AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Pornește aplicația:** -> **Notă:** Dacă ai pornit deja toate aplicațiile folosind `./start-all.sh` din directorul rădăcină (așa cum este descris în Modulul 01), acest modul este deja pornit pe portul 8083. Poți sări peste comenzile de start de mai jos și să accesezi direct http://localhost:8083. +> **Notă:** Dacă ai pornit deja toate aplicațiile folosind `./start-all.sh` din directorul rădăcină (așa cum s-a descris în Modulul 01), acest modul rulează deja pe portul 8083. Poți sări peste comenzile de start de mai jos și să accesezi direct http://localhost:8083. **Opțiunea 1: Folosind Spring Boot Dashboard (Recomandat pentru utilizatorii VS Code)** -Containerul de dezvoltare include extensia Spring Boot Dashboard, care oferă o interfață vizuală pentru gestionarea tuturor aplicațiilor Spring Boot. O poți găsi în Bara de Activități din partea stângă a VS Code (caută pictograma Spring Boot). +Containerul de dezvoltare include extensia Spring Boot Dashboard, care oferă o interfață vizuală pentru a gestiona toate aplicațiile Spring Boot. O găsești în bara de activități din partea stângă a VS Code (caută pictograma Spring Boot). -Din Spring Boot Dashboard poți: -- Să vezi toate aplicațiile Spring Boot disponibile în spațiul de lucru -- Să pornești/oprești aplicațiile cu un singur click -- Să vizualizezi log-urile aplicațiilor în timp real -- Să monitorizezi starea aplicațiilor +Din Spring Boot Dashboard poți: +- Vizualiza toate aplicațiile Spring Boot disponibile în workspace +- Porni/opri aplicațiile cu un singur clic +- Vizualiza în timp real log-urile aplicațiilor +- Monitoriza starea aplicațiilor -Pur și simplu click pe butonul de redare de lângă "prompt-engineering" pentru a porni acest modul, sau pornește toate modulele simultan. +Pur și simplu dă clic pe butonul play de lângă "prompt-engineering" pentru a porni acest modul, sau pornește toate modulele simultan. Spring Boot Dashboard @@ -466,135 +466,136 @@ Pur și simplu click pe butonul de redare de lângă "prompt-engineering" pentru Pornește toate aplicațiile web (modulele 01-04): -**Bash:** +**Bash:** ```bash cd .. # Din directorul rădăcină ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd .. # Din directorul rădăcină .\start-all.ps1 ``` - + Sau pornește doar acest modul: -**Bash:** +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` - -Ambele scripturi încarcă automat variabilele de mediu din fișierul `.env` din rădăcină și vor construi JAR-urile dacă nu există. + +Ambele scripturi încarcă automat variabilele de mediu din fișierul `.env` de la rădăcină și vor construi fișierele JAR dacă acestea nu există. > **Notă:** Dacă preferi să construiești manual toate modulele înainte de pornire: > -> **Bash:** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> -> **PowerShell:** + +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Deschide http://localhost:8083 în browserul tău. + +Deschide http://localhost:8083 în browser. **Pentru oprire:** -**Bash:** +**Bash:** ```bash -./stop.sh # Doar acest modul +./stop.sh # Numai acest modul # Sau cd .. && ./stop-all.sh # Toate modulele ``` - -**PowerShell:** + +**PowerShell:** ```powershell -.\stop.ps1 # Doar acest modul +.\stop.ps1 # Numai acest modul # Sau cd ..; .\stop-all.ps1 # Toate modulele ``` + +## Capturi de ecran ale aplicației -## Capturi de Ecran ale Aplicației - -Iată interfața principală a modulului de inginerie a prompturilor, unde poți experimenta toate cele opt tipare una lângă alta. +Iată interfața principală a modulului de inginerie a prompturilor, unde poți experimenta cu toate cele opt modele unul lângă altul. -Panoul Principal +Pagina principală Dashboard -*Panoul principal afișând toate cele 8 tipare de inginerie a prompturilor cu caracteristicile și cazurile lor de utilizare* +*Dashboard-ul principal afișând toate cele 8 modele de inginerie a prompturilor cu caracteristicile și cazurile de utilizare* -## Explorarea Tiparelor +## Explorarea modelelor -Interfața web îți permite să experimentezi cu diferite strategii de promptare. Fiecare tipar rezolvă probleme diferite - încearcă-le pentru a vedea când strălucește fiecare abordare. +Interfața web îți permite să experimentezi diferite strategii de prompting. Fiecare model rezolvă probleme diferite - încearcă-le să vezi când se evidențiază fiecare abordare. -> **Notă: Streaming vs Non-Streaming** — Fiecare pagină de tipar oferă două butoane: **🔴 Stream Response (Live)** și o opțiune **Non-streaming**. Streaming folosește Server-Sent Events (SSE) pentru a afișa tokenii în timp real pe măsură ce modelul îi generează, astfel vezi progresul imediat. Opțiunea non-streaming așteaptă răspunsul complet înainte de afișare. Pentru prompturi care declanșează raționamente profunde (de ex. High Eagerness, Self-Reflecting Code), apelul non-streaming poate dura foarte mult – uneori minute – fără feedback vizibil. **Folosește streaming atunci când experimentezi cu prompturi complexe** pentru a vedea modelul în acțiune și a evita impresia că cererea a expirat. +> **Notă: Streaming vs Non-Streaming** — Fiecare pagină a unui model oferă două butoane: **🔴 Stream Response (Live)** și o opțiune **Non-streaming**. Streaming folosește Server-Sent Events (SSE) pentru a afișa în timp real tokenii generați de model, astfel vezi progresul imediat. Opțiunea non-streaming așteaptă răspunsul complet înainte de afișare. Pentru prompturi care declanșează raționamente profunde (de ex. High Eagerness, Self-Reflecting Code), apelul non-streaming poate dura foarte mult timp — uneori minute — fără feedback vizibil. **Folosește streaming când experimentezi cu prompturi complexe** ca să vezi modelul lucrând și să eviți impresia că cererea a expirat. > -> **Notă: Cerință Browser** — Funcția de streaming folosește Fetch Streams API (`response.body.getReader()`) care necesită un browser complet (Chrome, Edge, Firefox, Safari). NU funcționează în Simple Browser-ul integrat în VS Code, deoarece webview-ul său nu suportă API-ul ReadableStream. Dacă folosești Simple Browser, butoanele non-streaming vor funcționa normal — doar butoanele de streaming sunt afectate. Deschide `http://localhost:8083` într-un browser extern pentru experiența completă. +> **Notă: Cerință Browser** — Funcția de streaming folosește Fetch Streams API (`response.body.getReader()`) care necesită un browser complet (Chrome, Edge, Firefox, Safari). Nu funcționează în Simple Browser-ul integrat în VS Code, deoarece webview-ul său nu suportă ReadableStream API. Dacă folosești Simple Browser, butoanele non-streaming funcționează normal — doar cele de streaming sunt afectate. Deschide `http://localhost:8083` într-un browser extern pentru experiența completă. ### Low vs High Eagerness -Pune o întrebare simplă precum „Care este 15% din 200?” folosind Low Eagerness. Vei primi un răspuns rapid, direct. Acum pune ceva complex ca „Proiectează o strategie de caching pentru un API cu trafic mare” folosind High Eagerness. Apasă **🔴 Stream Response (Live)** și urmărește cum apare raționamentul detaliat token-cu-token. Același model, aceeași structură a întrebării – dar promptul îi spune cât de mult să gândească. +Pune o întrebare simplă precum „Care este 15% din 200?” folosind Low Eagerness. Primești un răspuns direct și instant. Acum pune ceva complex, ca „Proiectează o strategie de caching pentru o API cu trafic ridicat” folosind High Eagerness. Apasă **🔴 Stream Response (Live)** și urmărește raționamentul detaliat token cu token al modelului. Același model, aceeași structură a întrebării - dar promptul îi spune cât să gândească. -### Executarea Sarcinilor (Tool Preambles) +### Executarea sarcinilor (Introductive de instrument) -Fluxurile multi-pasu beneficiază de planificare în avans și narare a progresului. Modelul schițează ce va face, povestește fiecare pas, apoi rezumă rezultatele. +Fluxurile de lucru cu mai mulți pași beneficiază de planificare înainte și nararea progresului. Modelul descrie ce va face, narrează fiecare pas, apoi rezumă rezultatele. -### Cod Auto-Reflectiv +### Cod auto-reflectiv -Încearcă „Crează un serviciu de validare email”. În loc să genereze doar cod și să se oprească, modelul generează, evaluează după criterii de calitate, identifică punctele slabe și îmbunătățește. Vei vedea cum iterează până când codul îndeplinește standardele de producție. +Încearcă „Creează un serviciu de validare email”. În loc să genereze doar cod și să se oprească, modelul generează, evaluează după criterii de calitate, identifică slăbiciuni și îmbunătățește. Vei vedea iterații până când codul atinge standarde de producție. -### Analiză Structurată +### Analiză structurată -Reviziile de cod au nevoie de cadre de evaluare consistente. Modelul analizează codul folosind categorii fixe (corectitudine, practici, performanță, securitate) cu niveluri de severitate. +Review-urile de cod au nevoie de cadre de evaluare constante. Modelul analizează codul folosind categorii fixe (corectitudine, practici, performanță, securitate) cu niveluri de severitate. -### Chat Multi-Turn +### Chat multi-rundă -Întreabă „Ce este Spring Boot?” apoi urmează imediat cu „Arată-mi un exemplu”. Modelul își amintește prima întrebare și îți oferă un exemplu specific Spring Boot. Fără memorie, a doua întrebare ar fi prea vagă. +Întreabă „Ce este Spring Boot?” apoi imediat continuă cu „Arată-mi un exemplu”. Modelul își amintește prima întrebare și îți oferă un exemplu Spring Boot specializat. Fără memorie, a doua întrebare ar fi vague. -### Raționament Pas cu Pas +### Raționament pas cu pas -Alege o problemă de matematică și încearc-o atât cu Raționament Pas cu Pas cât și cu Low Eagerness. Low eagerness îți dă doar răspunsul – rapid, dar opac. Raționamentul pas cu pas îți arată toate calculele și deciziile. +Alege o problemă de matematică și încearc-o cu Step-by-Step Reasoning și Low Eagerness. Low eagerness îți dă doar răspunsul – rapid, dar opac. Raționamentul pas cu pas îți arată fiecare calcul și decizie. -### Rezultat Constrâns +### Output Constrâns -Când ai nevoie de formate specifice sau un număr fix de cuvinte, acest tipar impune respectarea strictă. Încearcă să generezi un rezumat cu exact 100 de cuvinte în format punctat. +Când ai nevoie de formate specifice sau număr fix de cuvinte, acest model impune respectarea strictă. Încearcă să generezi un rezumat cu exact 100 de cuvinte în format listat. -## Ce Înveți Cu Adevărat +## Ce înveți cu adevărat -**Efortul de Raționament Schimbă Totul** +**Efortul de raționament schimbă totul** -GPT-5.2 îți permite să controlezi efortul computațional prin prompturi. Efortul mic înseamnă răspunsuri rapide cu explorare minimă. Efortul mare înseamnă că modelul ia timp să gândească profund. Înveți să potrivești efortul cu complexitatea sarcinii – nu pierde timp cu întrebări simple, dar nu grăbi deciziile complexe. +GPT-5.2 îți permite să controlezi efortul computațional prin prompturi. Efort mic înseamnă răspunsuri rapide cu explorare minimă. Efort mare înseamnă că modelul alocă timp pentru un gând profund. Înveți să potrivești efortul cu complexitatea sarcinii – nu pierde timpul pe întrebări simple, dar nici nu te grăbi cu deciziile complexe. -**Structura Ghidează Comportamentul** +**Structura ghidează comportamentul** -Observi etichetele XML în prompturi? Nu sunt decorative. Modelele urmează instrucțiuni structurate mai fiabil decât textul liber. Când ai nevoie de procese multi-pasu sau logică complexă, structura ajută modelul să știe unde este și ce urmează. Diagrama de mai jos descompune un prompt bine structurat, arătând cum tag-urile ca ``, ``, ``, `` și `` organizează instrucțiunile în secțiuni clare. +Ai observat tag-urile XML din prompturi? Nu sunt decorative. Modelele urmează instrucțiuni structurate mai fiabil decât textul liber. Când ai nevoie de procese multi-pas sau logică complexă, structura ajută modelul să știe unde se află și ce urmează. Diagrama de mai jos descompune un prompt bine structurat, arătând cum tag-uri ca ``, ``, ``, ``, și `` organizează instrucțiunile în secțiuni clare. Structura Promptului *Anatomia unui prompt bine structurat cu secțiuni clare și organizare de tip XML* -**Calitatea Prin Auto-Evaluare** +**Calitate prin auto-evaluare** -Tiparele auto-reflective funcționează prin explicitarea criteriilor de calitate. În loc să speri că modelul „face bine”, îi spui exact ce înseamnă „bine”: logică corectă, tratament al erorilor, performanță, securitate. Modelul își poate evalua apoi propriul output și-l poate îmbunătăți. Astfel, generarea de cod devine un proces, nu o loterie. +Modelele auto-reflective funcționează prin explicitarea criteriilor de calitate. În loc să speri că modelul „face bine”, îi spui exact ce înseamnă „bine”: logică corectă, gestionarea erorilor, performanță, securitate. Modelul poate evalua apoi singur output-ul și îmbunătăți. Transformă generarea de cod din loterie într-un proces. -**Contextul Este Limitat** +**Contextul este limitat** -Conversațiile multi-turn funcționează prin includerea istoricului mesajelor la fiecare cerere. Dar există o limită – fiecare model are un număr maxim de tokeni. Pe măsură ce conversațiile cresc, vei avea nevoie de strategii ca să păstrezi context relevant fără să atingi plafonul. Acest modul îți arată cum funcționează memoria; mai târziu vei învăța când să rezumi, când să uiți și când să recuperezi. +Conversațiile multi-turn funcționează prin includerea istoricului mesajelor la fiecare cerere. Dar există o limită - fiecare model are un număr maxim de tokeni. Pe măsură ce conversațiile cresc, ai nevoie de strategii pentru a păstra context relevant fără a atinge limita. Acest modul îți arată cum funcționează memoria; mai târziu vei învăța când să rezumi, când să uiți și când să reiei. -## Pașii Următori +## Pașii următori -**Următorul ModuI:** [03-rag - RAG (Generare Augmentată prin Recuperare)](../03-rag/README.md) +**Următorul modul:** [03-rag - RAG (Generare augmentată prin recuperare)](../03-rag/README.md) --- @@ -603,6 +604,6 @@ Conversațiile multi-turn funcționează prin includerea istoricului mesajelor l --- -**Declinare de responsabilitate**: -Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original, în limba sa nativă, trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist uman. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite rezultate din utilizarea acestei traduceri. +**Declinare a responsabilității**: +Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri. \ No newline at end of file diff --git a/translations/ro/03-rag/README.md b/translations/ro/03-rag/README.md index 563fbc18b..2f90ec577 100644 --- a/translations/ro/03-rag/README.md +++ b/translations/ro/03-rag/README.md @@ -2,112 +2,111 @@ ## Cuprins -- [Prezentare video](../../../03-rag) -- [Ce vei învăța](../../../03-rag) -- [Prerechizite](../../../03-rag) -- [Înțelegerea RAG](../../../03-rag) - - [Ce abordare RAG folosește acest tutorial?](../../../03-rag) -- [Cum funcționează](../../../03-rag) - - [Procesarea documentelor](../../../03-rag) - - [Crearea embedding-urilor](../../../03-rag) - - [Căutare semantică](../../../03-rag) - - [Generarea răspunsului](../../../03-rag) -- [Rulează aplicația](../../../03-rag) -- [Utilizarea aplicației](../../../03-rag) - - [Încarcă un document](../../../03-rag) - - [Pune întrebări](../../../03-rag) - - [Verifică referințele sursă](../../../03-rag) - - [Experimentează cu întrebări](../../../03-rag) -- [Concepte cheie](../../../03-rag) - - [Strategia de fragmentare](../../../03-rag) - - [Scoruri de similitudine](../../../03-rag) - - [Stocare în memorie](../../../03-rag) - - [Gestionarea ferestrei de context](../../../03-rag) -- [Când contează RAG](../../../03-rag) -- [Pașii următori](../../../03-rag) - -## Prezentare video +- [Parcurgere Video](#parcurgere-video) +- [Ce Vei Învăța](#ce-vei-învăța) +- [Prerechizite](#prerechizite) +- [Înțelegerea RAG](#înțelegerea-rag) + - [Ce abordare RAG folosește acest tutorial?](#ce-abordare-rag-folosește-acest-tutorial) +- [Cum Funcționează](#cum-funcționează) + - [Procesarea Documentelor](#procesarea-documentelor) + - [Crearea Embedding-urilor](#crearea-embedding-urilor) + - [Căutare Semantică](#căutare-semantică) + - [Generarea Răspunsului](#generarea-răspunsului) +- [Rulează Aplicația](#rulează-aplicația) +- [Folosirea Aplicației](#utilizarea-aplicației) + - [Încarcă un Document](#încarcă-un-document) + - [Pune Întrebări](#pune-întrebări) + - [Verifică Referințele Sursă](#verifică-referințele-sursei) + - [Experimentează cu Întrebările](#experimentează-cu-întrebări) +- [Concepte Cheie](#concepte-cheie) + - [Strategia de Chunking](#strategia-de-segmențare) + - [Scoruri de Similaritate](#scoruri-de-similaritate) + - [Stocare în Memorie](#stocarea-în-memorie) + - [Gestionarea Ferestrei de Context](#gestionarea-ferestrei-de-context) +- [Când Contează RAG](#când-contează-rag) +- [Pașii Următori](#pașii-următori) + +## Parcurgere Video Urmărește această sesiune live care explică cum să începi cu acest modul: -RAG cu LangChain4j - Sesiune Live +RAG with LangChain4j - Live Session -## Ce vei învăța +## Ce Vei Învăța -În modulele anterioare, ai învățat cum să ai conversații cu AI și să îți structurezi prompturile eficient. Dar există o limitare fundamentală: modelele de limbaj cunosc doar ceea ce au învățat în timpul antrenamentului. Nu pot răspunde la întrebări despre politicile companiei tale, documentația proiectului tău sau orice informație pentru care nu au fost instruiți. +În modulele precedente, ai învățat cum să ai conversații cu AI și să structurezi prompturile eficient. Dar există o limitare fundamentală: modelele de limbaj cunosc doar ceea ce au învățat în timpul antrenamentului. Ele nu pot răspunde la întrebări despre politicile companiei tale, documentația proiectului sau orice informație ce nu a fost inclusă în antrenament. -RAG (Generare Augmentată cu Recuperare) rezolvă această problemă. În loc să încerci să înveți modelul informațiile tale (ceea ce este costisitor și nepractic), îi oferi abilitatea de a căuta prin documentele tale. Când cineva pune o întrebare, sistemul găsește informația relevantă și o include în prompt. Modelul răspunde apoi pe baza contextului astfel recuperat. +RAG (Generare Augmentată cu Recuperare) rezolvă această problemă. În loc să încerci să „înveți” modelul cu informațiile tale (ceea ce este costisitor și nepractic), îi dai abilitatea de a căuta prin documentele tale. Atunci când cineva pune o întrebare, sistemul găsește informații relevante și le include în prompt. Modelul răspunde în funcție de contextul recuperat. -Gândește-te la RAG ca și cum i-ai oferi modelului o bibliotecă de referință. Când pui o întrebare, sistemul: +Gândește-te la RAG ca la o bibliotecă de referință pentru model. Când pui o întrebare, sistemul: -1. **Interogarea utilizatorului** - Pui o întrebare -2. **Embedding** - Convertește întrebarea într-un vector -3. **Căutare vectorială** - Găsește fragmente de document similare -4. **Asamblarea contextului** - Adaugă fragmente relevante la prompt -5. **Răspuns** - LLM generează un răspuns bazat pe context +1. **Interogare Utilizator** - Pui o întrebare +2. **Embedding** - Transformă întrebarea ta într-un vector +3. **Căutare Vector** - Găsește fragmente similare din documente +4. **Asamblare Context** - Adaugă fragmente relevante la prompt +5. **Răspuns** - LLM generează un răspuns pe baza contextului -Aceasta ancorează răspunsurile modelului în datele tale reale, în loc să se bazeze pe cunoștințele de antrenament sau să inventeze răspunsuri. +Aceasta ancorează răspunsurile modelului în datele tale reale în loc să se bazeze doar pe cunoștințele din antrenament sau să inventeze răspunsuri. ## Prerechizite -- Finalizat [Modulul 00 - Start rapid](../00-quick-start/README.md) (pentru exemplul Easy RAG referit mai târziu în acest modul) -- Finalizat [Modulul 01 - Introducere](../01-introduction/README.md) (resurse Azure OpenAI implementate, inclusiv modelul `text-embedding-3-small`) -- Fișier `.env` în directorul principal cu credențialele Azure (creat de `azd up` în Modulul 01) +- Finalizat [Modulul 01 - Introducere](../01-introduction/README.md) (resurse Azure OpenAI proiectate, inclusiv modelul de embedding `text-embedding-3-small`) +- Fișier `.env` în directorul rădăcină cu credențialele Azure (creat de `azd up` în Modulul 01) -> **Notă:** Dacă nu ai terminat Modulul 01, urmează mai întâi instrucțiunile de implementare de acolo. Comanda `azd up` implementează atât modelul de chat GPT, cât și modelul de embedding folosit de acest modul. +> **Notă:** Dacă nu ai terminat Modulul 01, urmează mai întâi instrucțiunile de acolo. Comanda `azd up` implementează atât modelul GPT pentru chat, cât și modelul de embedding folosit în acest modul. ## Înțelegerea RAG -Diagrama de mai jos ilustrează conceptul de bază: în loc să se bazeze doar pe datele de antrenament ale modelului, RAG îi oferă o bibliotecă de referință a documentelor tale pentru a consulta înainte de a genera fiecare răspuns. +Diagrama de mai jos ilustrează conceptul principal: în loc să se bazeze doar pe datele de antrenament ale modelului, RAG îi oferă o bibliotecă de referință compusă din documentele tale, pe care o consultă înainte de a genera fiecare răspuns. -Ce este RAG +What is RAG -*Această diagramă prezintă diferența dintre un LLM standard (care ghicește din datele de antrenament) și un LLM îmbunătățit cu RAG (care consultă mai întâi documentele tale).* +*Această diagramă arată diferența dintre un LLM standard (care ghicește din datele de antrenament) și un LLM îmbunătățit prin RAG (care consultă mai întâi documentele tale).* -Iată cum se leagă piesele cap-la-cap. Întrebarea utilizatorului trece prin patru etape — embedding, căutare vectorială, asamblare a contextului și generare a răspunsului — fiecare construind pe cea anterioară: +Iată cum sunt legate piesele cap la cap. Întrebarea unui utilizator trece prin patru etape — embedding, căutare vectorială, asamblare context și generare răspuns — fiecare construind pe cea anterioară: -Arhitectura RAG +RAG Architecture -*Această diagramă arată fluxul complet al pipeline-ului RAG — o interogare a utilizatorului trece prin embedding, căutare vectorială, asamblarea contextului și generarea răspunsului.* +*Această diagramă arată pipeline-ul complet RAG — o interogare utilizator trece prin embedding, căutare vectorială, asamblare context și generare răspuns.* Restul modulului parcurge fiecare etapă în detaliu, cu cod pe care îl poți rula și modifica. ### Ce abordare RAG folosește acest tutorial? -LangChain4j oferă trei metode de implementare a RAG, fiecare cu un nivel diferit de abstractizare. Diagrama de mai jos le compară unul lângă altul: +LangChain4j oferă trei moduri de a implementa RAG, fiecare cu un nivel diferit de abstractizare. Diagrama de mai jos le compară alăturat: -Trei abordări RAG în LangChain4j +Three RAG Approaches in LangChain4j -*Această diagramă compară cele trei abordări LangChain4j pentru RAG — Easy, Native și Advanced — arătând componentele cheie și când să le folosești.* +*Această diagramă compară cele trei abordări RAG din LangChain4j — Easy, Native și Advanced — arătând componentele lor cheie și când să folosești fiecare.* -| Abordare | Ce face | Compromis | +| Abordare | Ce Face | Compromis | |---|---|---| -| **Easy RAG** | Leagă totul automat prin `AiServices` și `ContentRetriever`. Anotezi o interfață, atașezi un retriever, iar LangChain4j se ocupă de embedding, căutare și asamblarea promptului în fundal. | Minimal de cod, dar nu vezi ce se întâmplă la fiecare pas. | -| **Native RAG** | Apelezi modelul de embedding, cauți în magazin, construiești promptul și generezi răspunsul singur — pas cu pas explicit. | Mai mult cod, dar fiecare etapă este vizibilă și modificabilă. | -| **Advanced RAG** | Folosește cadrul `RetrievalAugmentor` cu transformatoare, rutări, re-clasificatoare și injectoare de conținut pentru pipeline-uri la nivel de producție. | Flexibilitate maximă, dar complexitate mult mai mare. | +| **Easy RAG** | Leagă totul automat prin `AiServices` și `ContentRetriever`. Anotezi o interfață, atașezi un retriever, iar LangChain4j se ocupă de embedding, căutare și asamblare prompt în fundal. | Cod minim, dar nu vezi ce se întâmplă la fiecare pas. | +| **Native RAG** | Apelezi modelul de embedding, cauți în magazin, construiești promptul și generezi răspunsul tu însuți — câte un pas explicit. | Mai mult cod, dar fiecare etapă este vizibilă și modificabilă. | +| **Advanced RAG** | Folosește cadrul `RetrievalAugmentor` cu transformatoare de interogare, rutere, re-rankeri și injectoare de conținut plug-in pentru pipeline-uri de calitate producție. | Flexibilitate maximă, dar complexitate mult mai mare. | -**Tutorialul folosește abordarea Native.** Fiecare pas al pipeline-ului RAG — embedarea interogării, căutarea în vector store, asamblarea contextului și generarea răspunsului — este scris explicit în [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Acest lucru este intenționat: ca resursă de învățare, este mai important să vezi și să înțelegi fiecare etapă decât să minimizezi codul. Odată ce ești confortabil cu cum se leagă piesele, poți trece la Easy RAG pentru prototipuri rapide sau Advanced RAG pentru sisteme de producție. +**Acest tutorial folosește abordarea Native.** Fiecare pas din pipeline-ul RAG — embedding-ul interogării, căutarea în magazinul vectorial, asamblarea contextului și generarea răspunsului — este scris explicit în [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Acest lucru este intenționat: ca resursă de învățare, este mai important să vezi și să înțelegi fiecare etapă decât să minimizezi codul. Odată ce te simți confortabil cu modul în care toate piesele se potrivesc, poți trece la Easy RAG pentru prototipuri rapide sau Advanced RAG pentru sisteme de producție. -> **💡 Ai văzut deja Easy RAG în acțiune?** Modulul [Quick Start](../00-quick-start/README.md) include un exemplu de Q&A pe documente ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) care folosește abordarea Easy RAG — LangChain4j se ocupă automat de embedding, căutare și asamblarea promptului. Acest modul face pasul următor, deschizând acel pipeline pentru ca tu să vezi și să controlezi fiecare etapă. +> **💡 Curios despre Easy RAG?** LangChain4j oferă de asemenea o abordare *Easy RAG* în care `AiServices` și un `ContentRetriever` se ocupă automat de embedding, căutare și asamblare prompt. Acest modul ia calea mai explicită — deschizând pipeline-ul astfel încât să poți vedea și controla fiecare etapă. -Diagrama de mai jos arată pipeline-ul Easy RAG din acel exemplu Quick Start. Observă cum `AiServices` și `EmbeddingStoreContentRetriever` ascund întreaga complexitate — încarci un document, atașezi un retriever și primești răspunsuri. Abordarea Native din acest modul deschide fiecare dintre acei pași ascunși: +Diagrama de mai jos arată pipeline-ul Easy RAG. Observă cum `AiServices` și `EmbeddingStoreContentRetriever` ascund toată complexitatea — încarci un document, atașezi un retriever și primești răspunsuri. Abordarea Native din acest modul desface pe rând fiecare din aceste etape ascunse: -Pipeline Easy RAG - LangChain4j +Easy RAG Pipeline - LangChain4j -*Această diagramă arată pipeline-ul Easy RAG din `SimpleReaderDemo.java`. Compară-l cu abordarea Native folosită în acest modul: Easy RAG ascunde embedding-ul, recuperarea și asamblarea promptului în spatele `AiServices` și `ContentRetriever` — încarci un document, atașezi un retriever și primești răspunsuri. Abordarea Native din acest modul deschide pipeline-ul astfel încât să apelezi fiecare etapă (embed, search, asamblează context, generează) manual, oferindu-ți vizibilitate și control complet.* +*Această diagramă arată pipeline-ul Easy RAG. Compară cu abordarea Native folosită în acest modul: Easy RAG ascunde embedding-ul, recuperarea și asamblarea promptului în spatele `AiServices` și `ContentRetriever` — încarci un document, atașezi un retriever și primești răspunsuri. Abordarea Native din acest modul desface acest pipeline astfel încât să apelezi fiecare etapă (embedding, căutare, asamblare context, generare) singur, oferindu-ți vizibilitate și control complet.* -## Cum funcționează +## Cum Funcționează -Pipeline-ul RAG din acest modul se împarte în patru etape care rulează secvențial de fiecare dată când un utilizator pune o întrebare. Mai întâi, un document încărcat este **parsat și fragmentat** în bucăți gestionabile. Aceste fragmente sunt apoi convertite în **embedding-uri vectoriale** și stocate pentru a putea fi comparate matematic. Când sosește o interogare, sistemul efectuează o **căutare semantică** pentru a găsi cele mai relevante fragmente și în final le transmite ca context LLM-ului pentru **generarea răspunsului**. Secțiunile următoare parcurg fiecare etapă cu codul efectiv și diagrame. Să începem cu primul pas. +Pipeline-ul RAG din acest modul se împarte în patru etape care se rulează în secvență de fiecare dată când un utilizator pune o întrebare. Mai întâi, un document încărcat este **parsificat și fragmentat** în bucăți ușor de gestionat. Aceste fragmente sunt apoi convertite în **embedding-uri vectoriale** și stocate pentru a putea fi comparate matematic. Când apare o interogare, sistemul efectuează o **căutare semantică** pentru a găsi cele mai relevante fragmente, iar în final le pasează ca context către LLM pentru **generarea răspunsului**. Secțiunile următoare parcurg fiecare etapă cu codul efectiv și diagrame. Să privim primul pas. -### Procesarea documentelor +### Procesarea Documentelor [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Când încarci un document, sistemul îl parsează (PDF sau text simplu), atașează metadata precum numele fișierului, apoi îl împarte în fragmente — bucăți mai mici care încă încap confortabil în fereastra de context a modelului. Aceste fragmente se suprapun ușor pentru a nu pierde context la granițe. +Când încarci un document, sistemul îl parsează (PDF sau text simplu), atașează metadate precum numele fișierului și apoi îl sparge în fragmente — bucăți mai mici care se potrivesc confortabil în fereastra de context a modelului. Aceste fragmente se suprapun ușor pentru a nu pierde contextul la limite. ```java -// Parcurge fișierul încărcat și îl înfășoară într-un Document LangChain4j +// Analizează fișierul încărcat și înfășoară-l într-un Document LangChain4j Document document = Document.from(content, metadata); // Împarte în bucăți de 300 de tokeni cu o suprapunere de 30 de tokeni @@ -117,28 +116,28 @@ DocumentSplitter splitter = DocumentSplitters List segments = splitter.split(document); ``` -Diagrama de mai jos arată cum funcționează vizual acest proces. Observă cum fiecare fragment share-uiește unele tokenuri cu vecinii săi — suprapunerea de 30 de tokenuri asigură că nu se pierde context important între fragmente: +Diagrama de mai jos arată cum funcționează vizual. Observă cum fiecare fragment împarte unele tokenuri cu vecinii săi — suprapunerea de 30 de tokenuri asigură că nu se pierde context important la margini: -Fragmentarea documentelor +Document Chunking -*Această diagramă arată un document fragmentat în bucăți de 300 de tokenuri cu suprapunere de 30 de tokenuri, păstrând contextul la granițele fragmentelor.* +*Această diagramă arată un document împărțit în fragmente de 300 de tokenuri cu suprapunere de 30 de tokenuri, păstrând contextul la marginile fragmentelor.* -> **🤖 Încearcă cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschide [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) și întreabă: -> - "Cum împarte LangChain4j documentele în fragmente și de ce este importantă suprapunerea?" -> - "Care este dimensiunea optimă a fragmentului pentru diferite tipuri de documente și de ce?" -> - "Cum gestionez documentele în mai multe limbi sau cu formatare specială?" +> **🤖 Încearcă cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschide [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) și întreabă: +> - "Cum împarte LangChain4j documentele în fragmente și de ce este importantă suprapunerea?" +> - "Care este dimensiunea optimă a fragmentelor pentru diferite tipuri de documente și de ce?" +> - "Cum gestionez documente în mai multe limbi sau cu formatare specială?" -### Crearea embedding-urilor +### Crearea Embedding-urilor [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Fiecare fragment este convertit într-o reprezentare numerică numită embedding — practic un convertor de semnificații în numere. Modelul de embedding nu este „inteligent” ca un model de chat; nu poate urma instrucțiuni, raționa sau răspunde la întrebări. Ce poate face este să mapeze textul într-un spațiu matematic unde semnificații similare stau aproape unele de altele — „mașină” este aproape de „automobil”, „politică de rambursare” este aproape de „returnează banii”. Gândește-te la modelul de chat ca la o persoană cu care poți vorbi; modelul de embedding este un sistem ultra-bun de arhivare. +Fiecare fragment este convertit într-o reprezentare numerică numită embedding — practic un convertor de sens în numere. Modelul de embedding nu este „inteligent” precum un model de chat; nu poate urma instrucțiuni, nu poate raționa sau răspunde la întrebări. Ce poate face este să mapeze textul într-un spațiu matematic în care sensuri similare ajung aproape unul de altul — „mașină” lângă „automobil”, „politica de returnare” lângă „îmi returnează banii”. Gândește-te la un model de chat ca la o persoană cu care poți conversa; un model de embedding este un sistem de arhivare ultra-eficient. -Diagrama de mai jos vizualizează acest concept — textul intră, vectori numerici ies, iar semnificațiile similare produc vectori apropiați: +Diagrama de mai jos vizualizează acest concept — textul intră, vectorii numerici ies, iar sensurile similare produc vectori apropiați: -Concept Model Embedding +Embedding Model Concept -*Această diagramă arată cum un model de embedding convertește textul în vectori numerici, plasând semnificații similare — precum „mașină” și „automobil” — apropiate în spațiul vectorial.* +*Această diagramă arată cum un model de embedding convertește textul în vectori numerici, plasând sensuri similare — precum „mașină” și „automobil” — aproape unul de altul în spațiul vectorial.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Diagrama claselor de mai jos arată cele două fluxuri separate într-un pipeline RAG și clasele LangChain4j care le implementează. Fluxul de **ingestie** (rulează o singură dată la încărcare) împarte documentul, creează embedding-urile fragmentelor și le stochează prin `.addAll()`. Fluxul de **interogare** (rulează la fiecare întrebare) embed-ează întrebarea, caută în magazin prin `.search()` și transmite contextul găsit modelului de chat. Ambele fluxuri se întâlnesc în interfața comună `EmbeddingStore`: +Diagrama claselor de mai jos arată cele două fluxuri separate într-un pipeline RAG și clasele LangChain4j care le implementează. Fluxul de **încărcare** (rulează o singură dată la încărcarea documentului) sparge documentul, creează embedding-urile fragmentelor și le stochează prin `.addAll()`. Fluxul de **interogare** (rulează de fiecare dată când un utilizator întreabă) creează embedding-ul întrebării, caută în magazin prin `.search()`, și pasează contextul găsit la modelul de chat. Ambele fluxuri se întâlnesc la interfața comună `EmbeddingStore`: -Clase LangChain4j RAG +LangChain4j RAG Classes -*Această diagramă arată cele două fluxuri într-un pipeline RAG — ingestie și interogare — și cum se leagă printr-un EmbeddingStore comun.* +*Această diagramă arată cele două fluxuri într-un pipeline RAG — încărcare și interogare — și cum se conectează printr-un EmbeddingStore comun.* -Odată ce embedding-urile sunt stocate, conținutul similar se grupează natural în spațiul vectorial. Vizualizarea de mai jos arată cum documentele despre subiecte înrudite devin puncte apropiate, ceea ce face posibilă căutarea semantică: +Odată ce embedding-urile sunt stocate, conținutul similar se grupează natural în spațiul vectorial. Vizualizarea de mai jos arată cum documentele despre subiecte conexe devin puncte vecine, ceea ce face posibilă căutarea semantică: -Spațiul embedding-urilor vectoriale +Vector Embeddings Space -*Această vizualizare arată cum documentele înrudite se grupează împreună în spațiul vectorial 3D, cu grupuri distincte precum Documentație Tehnică, Reguli de Afaceri și Întrebări Frecvente.* +*Această vizualizare arată cum documentele corelate se grupează în spațiul tridimensional vectorial, cu subiecte precum Documente Tehnice, Reguli de Afaceri și Întrebări Frecvente formând grupuri distincte.* -Când un utilizator caută, sistemul urmează patru pași: embed-ează o singură dată documentele, embed-ează interogarea la fiecare căutare, compară vectorul interogării cu toți vectorii stocați folosind similitudinea cosinus și returnează primele K fragmente cu cel mai înalt scor. Diagrama de mai jos parcurge fiecare pas și clasele LangChain4j implicate: +Când un utilizator caută, sistemul urmează patru pași: creează embedding-urile documentelor o singură dată, creează embedding-ul interogării la fiecare căutare, compară vectorul întrebării cu toate vectorii stocați folosind similaritatea cosinus, și returnează cele mai bine punctate fragmente top-K. Diagrama de mai jos parcurge fiecare pas și clasele LangChain4j implicate: -Pașii căutării embedding +Embedding Search Steps -*Această diagramă arată procesul căutării embedding în patru pași: embed-ează documentele, embed-ează interogarea, compară vectorii cu similitudinea cosinus și returnează primele K rezultate.* +*Această diagramă arată procesul de căutare embedding în patru pași: creează embedding documente, creează embedding interogare, compară vectorii cu similaritate cosinus și returnează rezultatele top-K.* -### Căutare semantică +### Căutare Semantică [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Când pui o întrebare, întrebarea ta devine la rândul ei un embedding. Sistemul compară embedding-ul întrebării tale cu embedding-urile tuturor fragmentelor de document. Găsește cele mai asemănătoare fragmente — nu doar potriviri de cuvinte-cheie, ci similitudine semantică reală. +Când pui o întrebare, și întrebarea ta devine un embedding. Sistemul compară embedding-ul întrebării tale cu embedding-urile tuturor fragmentelor de document. Găsește fragmentele cu cele mai similare sensuri - nu doar cuvinte cheie potrivite, ci similaritate semantică reală. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Diagrama de mai jos contrastează căutarea semantică cu căutarea tradițională pe cuvinte-cheie. O căutare pe cuvântul „vehicul” ratează un fragment despre „mașini și camioane”, dar căutarea semantică înțelege că înseamnă același lucru și îl returnează ca o potrivire cu scor ridicat: +Diagrama de mai jos contrastează căutarea semantică cu cea tradițională bazată pe cuvinte cheie. O căutare după cuvântul „vehicul” ratează un fragment despre „mașini și camioane”, dar căutarea semantică înțelege că acestea înseamnă același lucru și îl returnează ca potrivire bine punctată: -Căutare semantică +Semantic Search -*Această diagramă compară căutarea bazată pe cuvinte-cheie cu cea semantică, arătând cum căutarea semantică returnează conținut conceptual înrudit chiar și când cuvintele exacte diferă.* -La bază, similaritatea este măsurată folosind similaritatea cosinus — practic întrebând „indică aceste două săgeți în aceeași direcție?” Două bucăți pot folosi cuvinte complet diferite, dar dacă înseamnă același lucru vectorii lor indică aceeași direcție și obțin un scor aproape de 1.0: +*Această diagramă compară căutarea bazată pe cuvinte cheie cu cea semantică, arătând cum căutarea semantică recuperează conținut conceptually legat chiar dacă cuvintele exacte diferă.* -Similaritate cosinus +În partea internă, similaritatea este măsurată folosind similaritatea cosinus — practic întrebând „arată acești doi săgeți în aceeași direcție?” Două fragmente pot folosi cuvinte complet diferite, dar dacă au același sens vectorii lor indică aceeași direcție și au scor aproape de 1.0: -*Acest diagramă ilustrează similaritatea cosinus ca unghiul dintre vectorii de embedding — vectorii mai aliniați obțin scoruri mai apropiate de 1.0, indicând o similaritate semantică mai mare.* +Cosine Similarity +*Acest diagramă ilustrează similitudinea cosinus ca unghiul dintre vectorii de embedding — vectorii mai aliniați obțin scoruri apropiate de 1.0, indicând o similitudine semantică mai mare.* > **🤖 Încearcă cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschide [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) și întreabă: -> - "Cum funcționează căutarea similarității cu embeddings și ce determină scorul?" +> - "Cum funcționează căutarea prin similaritate cu embeddings și ce determină scorul?" > - "Ce prag de similaritate ar trebui să folosesc și cum afectează rezultatele?" -> - "Cum gestionez cazurile când nu se găsesc documente relevante?" +> - "Cum gestionez cazurile în care nu se găsesc documente relevante?" -### Generarea răspunsului +### Generarea Răspunsului [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Cele mai relevante bucăți sunt asamblate într-un prompt structurat care include instructiuni explicite, contextul recuperat și întrebarea utilizatorului. Modelul citește acele bucăți specifice și răspunde pe baza acelor informații — poate folosi doar ce are în față, ceea ce previne halucinațiile. +Cele mai relevante segmente sunt asamblate într-un prompt structurat care include instrucțiuni explicite, contextul recuperat și întrebarea utilizatorului. Modelul citește acele segmente specifice și răspunde pe baza acelor informații — poate folosi doar ce are în față, ceea ce previne halucinațiile. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Diagrama de mai jos arată această asamblare în acțiune — cele mai bine cotate bucăți din pasul de căutare sunt injectate în șablonul de prompt, iar `OpenAiOfficialChatModel` generează un răspuns fundamentat: +Diagrama de mai jos arată această asamblare în acțiune — segmentele cu cel mai mare scor din pasul de căutare sunt injectate în șablonul de prompt, iar `OpenAiOfficialChatModel` generează un răspuns fundamentat: -Asamblare context +Context Assembly -*Această diagramă arată cum cele mai bine cotate bucăți sunt asamblate într-un prompt structurat, permițând modelului să genereze un răspuns fundamentat pe datele tale.* +*Această diagramă arată cum segmentele cu cel mai mare scor sunt asamblate într-un prompt structurat, permițând modelului să genereze un răspuns fundamentat din datele tale.* -## Rulează aplicația +## Rulează Aplicația **Verifică implementarea:** -Asigură-te că fișierul `.env` există în directorul rădăcină cu credențiale Azure (create în timpul Modulului 01). Rulează acest lucru din directorul modulului (`03-rag/`): +Asigură-te că fișierul `.env` există în directorul rădăcină cu acreditările Azure (create în Modulul 01). Rulează acest lucru din directorul modulului (`03-rag/`): **Bash:** ```bash @@ -261,19 +260,19 @@ Get-Content ..\.env # Ar trebui să afișeze AZURE_OPENAI_ENDPOINT, API_KEY, DE **Pornește aplicația:** -> **Notă:** Dacă ai pornit deja toate aplicațiile folosind `./start-all.sh` din directorul rădăcină (așa cum este descris în Modulul 01), acest modul rulează deja pe portul 8081. Poți sări peste comenzile de pornire de mai jos și merge direct la http://localhost:8081. +> **Notă:** Dacă ai pornit deja toate aplicațiile folosind `./start-all.sh` din directorul rădăcină (așa cum este descris în Modulul 01), acest modul rulează deja pe portul 8081. Poți sări peste comenzile de start de mai jos și să accesezi direct http://localhost:8081. **Opțiunea 1: Folosind Spring Boot Dashboard (Recomandat pentru utilizatorii VS Code)** -Containerul de dezvoltare include extensia Spring Boot Dashboard, care oferă o interfață vizuală pentru gestionarea tuturor aplicațiilor Spring Boot. O poți găsi în bara de activități din partea stângă a VS Code (caută pictograma Spring Boot). +Containerul de dezvoltare include extensia Spring Boot Dashboard, care oferă o interfață vizuală pentru gestionarea tuturor aplicațiilor Spring Boot. O poți găsi în Bara de activitate din partea stângă a VS Code (caută iconița Spring Boot). Din Spring Boot Dashboard, poți: -- Vizualiza toate aplicațiile Spring Boot disponibile în spațiul de lucru -- Porni/opri aplicațiile cu un singur clic +- Vedea toate aplicațiile Spring Boot disponibile în spațiul de lucru +- Porni/opri aplicații cu un singur clic - Vizualiza jurnalele aplicației în timp real -- Monitoriza starea aplicațiilor +- Monitoriza starea aplicației -Pur și simplu apasă butonul de redare de lângă „rag” pentru a porni acest modul, sau pornește toate modulele simultan. +Simplu, apasă butonul de play lângă „rag” pentru a porni acest modul sau pornește toate modulele odată. Spring Boot Dashboard @@ -311,7 +310,7 @@ cd 03-rag Ambele scripturi încarcă automat variabilele de mediu din fișierul `.env` din rădăcină și vor construi JAR-urile dacă acestea nu există. -> **Notă:** Dacă preferi să compilezi manual toate modulele înainte de pornire: +> **Notă:** Dacă preferi să construiești manual toate modulele înainte de pornire: > > **Bash:** > ```bash @@ -343,95 +342,95 @@ cd .. && ./stop-all.sh # Toate modulele cd ..; .\stop-all.ps1 # Toate modulele ``` -## Utilizarea aplicației +## Utilizarea Aplicației -Aplicația oferă o interfață web pentru încărcarea documentelor și punerea de întrebări. +Aplicația oferă o interfață web pentru încărcarea documentelor și adresarea întrebărilor. -Interfață aplicație RAG +RAG Application Interface *Această captură de ecran arată interfața aplicației RAG unde încarci documente și pui întrebări.* -### Încarcă un document +### Încarcă un Document -Începe prin a încărca un document - fișiere TXT funcționează cel mai bine pentru testare. În acest director este oferit un fișier `sample-document.txt` care conține informații despre caracteristicile LangChain4j, implementarea RAG și bune practici - perfect pentru testarea sistemului. +Începe prin a încărca un document - cele TXT funcționează cel mai bine pentru testare. În acest director există un `sample-document.txt` care conține informații despre funcționalitățile LangChain4j, implementarea RAG și bune practici - perfect pentru testarea sistemului. -Sistemul procesează documentul tău, îl împarte în bucăți și creează embeddings pentru fiecare bucată. Acest lucru se întâmplă automat la încărcare. +Sistemul procesează documentul tău, îl împarte în segmente și creează embeddings pentru fiecare segment. Acest lucru se face automat la încărcare. -### Pune întrebări +### Pune Întrebări -Acum pune întrebări specifice despre conținutul documentului. Încearcă ceva factual care este clar menționat în document. Sistemul caută bucățile relevante, le include în prompt și generează un răspuns. +Acum pune întrebări specifice despre conținutul documentului. Încearcă ceva factual care este clar menționat în document. Sistemul caută segmente relevante, le include în prompt și generează un răspuns. -### Verifică referințele sursă +### Verifică Referințele Sursei -Observă că fiecare răspuns include referințe la surse cu scoruri de similaritate. Aceste scoruri (0 până la 1) arată cât de relevantă a fost fiecare bucată pentru întrebarea ta. Scorurile mai mari înseamnă potriviri mai bune. Acest lucru îți permite să verifici răspunsul față de materialul sursă. +Observă că fiecare răspuns include referințe la surse cu scoruri de similaritate. Aceste scoruri (0 până la 1) arată cât de relevant a fost fiecare segment pentru întrebarea ta. Scorurile mai mari înseamnă potriviri mai bune. Astfel poți verifica răspunsul față de materialul sursă. -Rezultate interogare RAG +RAG Query Results -*Această captură de ecran arată rezultatele interogărilor cu răspunsul generat, referințele sursă și scorurile de relevanță pentru fiecare bucată recuperată.* +*Această captură de ecran arată rezultatele interogării cu răspunsul generat, referințele sursei și scorurile de relevanță pentru fiecare segment recuperat.* -### Experimentează cu întrebări +### Experimentează cu Întrebări Încearcă diferite tipuri de întrebări: - Fapte specifice: "Care este subiectul principal?" -- Comparații: "Care este diferența între X și Y?" -- Rezumate: "Rezumați punctele cheie despre Z" +- Comparații: "Care este diferența dintre X și Y?" +- Rezumate: "Rezuma punctele cheie despre Z" -Urmărește cum se schimbă scorurile de relevanță în funcție de cât de bine se potrivește întrebarea ta cu conținutul documentului. +Urmărește cum scorurile de relevanță se schimbă în funcție de cât de bine se potrivește întrebarea ta cu conținutul documentului. -## Concepute cheie +## Concepte Cheie -### Strategia de împărțire în bucăți +### Strategia de Segmențare -Documentele sunt împărțite în bucăți de 300 de tokeni cu o suprapunere de 30 de tokeni. Această balanță asigură că fiecare bucată are suficient context pentru a fi semnificativă, dar rămâne suficient de mică pentru a include mai multe bucăți într-un prompt. +Documentele sunt împărțite în segmente de 300 de tokeni cu o suprapunere de 30 de tokeni. Această balansare asigură că fiecare segment are suficient context pentru a fi relevant, menținând în același timp dimensiuni mici pentru a include mai multe segmente în prompt. -### Scorurile de similaritate +### Scoruri de Similaritate -Fiecare bucată recuperată vine cu un scor de similaritate între 0 și 1 care indică cât de bine se potrivește întrebării utilizatorului. Diagrama de mai jos vizualizează intervalele scorurilor și cum le folosește sistemul pentru a filtra rezultatele: +Fiecare segment recuperat vine cu un scor de similaritate între 0 și 1 care indică cât de bine se potrivește cu întrebarea utilizatorului. Diagrama de mai jos vizualizează intervalele scorurilor și cum sistemul le folosește pentru a filtra rezultatele: -Scoruri de similaritate +Similarity Scores -*Această diagramă arată intervalul scorurilor de la 0 la 1, cu un prag minim de 0.5 care elimină bucățile irelevante.* +*Această diagramă arată intervale de scor de la 0 la 1, cu un prag minim de 0.5 care filtrează segmentele irelevante.* -Scorurile variază între 0 și 1: -- 0.7-1.0: Foarte relevante, potrivire exactă -- 0.5-0.7: Relevante, context bun -- Sub 0.5: Eliminat, prea puțin similar +Scorurile variază de la 0 la 1: +- 0.7-1.0: Extrem de relevant, potrivire exactă +- 0.5-0.7: Relevant, context bun +- Sub 0.5: Filtrate, prea diferite -Sistemul recuperează doar bucățile deasupra pragului minim pentru a asigura calitatea. +Sistemul recuperează doar segmentele peste pragul minim pentru a asigura calitatea. -Embeddings funcționează bine când sensurile se grupează clar, dar au puncte oarbe. Diagrama de mai jos arată modurile comune de eșec — bucățile prea mari produc vectori neclari, bucățile prea mici lipsesc contextul, termenii ambigui indică multiple grupuri, iar căutările după potrivire exactă (ID-uri, numere de piese) nu funcționează deloc cu embeddings: +Embeddings funcționează bine când sensul se grupează clar, dar au puncte oarbe. Diagrama de mai jos arată modurile comune de eșec — segmentele prea mari produc vectori neclari, segmentele prea mici lipsesc de context, termenii ambigui indică mai multe grupuri, iar căutările exacte (ID-uri, numere de parte) nu funcționează deloc cu embeddings: -Moduri de eșec ale embedding-urilor +Embedding Failure Modes -*Această diagramă arată modurile comune de eșec ale embedding-urilor: bucăți prea mari, bucăți prea mici, termeni ambigui care indică multiple grupuri și căutări exacte ca ID-urile.* +*Această diagramă arată modurile comune de eșec ale embedding-urilor: segmente prea mari, segmente prea mici, termeni ambigui care indică multiple grupuri și căutări exacte ca ID-urile.* -### Stocare în memorie +### Stocarea în Memorie -Acest modul folosește stocare în memorie pentru simplitate. Când repornești aplicația, documentele încărcate se pierd. Sistemele de producție folosesc baze de date vectoriale persistente precum Qdrant sau Azure AI Search. +Acest modul folosește stocarea în memorie pentru simplitate. Când repornești aplicația, documentele încărcate se pierd. Sistemele de producție folosesc baze de date vectoriale persistente precum Qdrant sau Azure AI Search. -### Gestionarea ferestrei de context +### Gestionarea Ferestrei de Context -Fiecare model are o limită maximă a ferestrei de context. Nu poți include fiecare bucată dintr-un document mare. Sistemul recuperează primele N bucăți cele mai relevante (implicit 5) pentru a rămâne în limite și a oferi suficient context pentru răspunsuri corecte. +Fiecare model are o fereastră maximă de context. Nu poți include fiecare segment dintr-un document mare. Sistemul recuperează cele mai relevante N segmente (implicit 5) pentru a rămâne în limite și totuși a oferi suficient context pentru răspunsuri precise. -## Când contează RAG +## Când Contează RAG -RAG nu este întotdeauna abordarea corectă. Ghidul decizional de mai jos te ajută să determini când RAG adaugă valoare versus când abordările mai simple — cum ar fi includerea conținutului direct în prompt sau bazarea pe cunoștințele încorporate ale modelului — sunt suficiente: +RAG nu este întotdeauna abordarea potrivită. Ghidul decizional de mai jos te ajută să determini când RAG adaugă valoare versus când abordările mai simple — precum includerea conținutului direct în prompt sau bazarea pe cunoștințele construite ale modelului — sunt suficiente: -Când să folosești RAG +When to Use RAG *Această diagramă arată un ghid decizional pentru când RAG adaugă valoare versus când abordările mai simple sunt suficiente.* -## Pașii următori +## Pașii Următori -**Următorul modul:** [04-tools - Agenți AI cu unelte](../04-tools/README.md) +**Următorul Modul:** [04-tools - Agenți AI cu Unelte](../04-tools/README.md) --- -**Navigare:** [← Anterior: Modul 02 - Inginerie Prompt](../02-prompt-engineering/README.md) | [Înapoi la Principal](../README.md) | [Următor: Modul 04 - Unelte →](../04-tools/README.md) +**Navigare:** [← Anterior: Modul 02 - Inginerie de Prompt](../02-prompt-engineering/README.md) | [Înapoi la Principal](../README.md) | [Următor: Modul 04 - Unelte →](../04-tools/README.md) --- -**Declinare de responsabilitate**: -Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim pentru precizie, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original, în limba sa nativă, trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist uman. Nu ne asumăm nicio răspundere pentru eventualele neînțelegeri sau interpretări greșite rezultate din utilizarea acestei traduceri. +**Declinare a responsabilității**: +Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri. \ No newline at end of file diff --git a/translations/ro/04-tools/README.md b/translations/ro/04-tools/README.md index 16acf2849..746112c07 100644 --- a/translations/ro/04-tools/README.md +++ b/translations/ro/04-tools/README.md @@ -2,32 +2,32 @@ ## Cuprins -- [Parcurgere Video](../../../04-tools) -- [Ce Vei Învăța](../../../04-tools) -- [Precondiții](../../../04-tools) -- [Înțelegerea Agenților AI cu Unelte](../../../04-tools) -- [Cum Funcționează Apelarea Uneltelor](../../../04-tools) - - [Definiții ale Uneltelor](../../../04-tools) - - [Luarea Deciziilor](../../../04-tools) - - [Execuție](../../../04-tools) - - [Generarea Răspunsului](../../../04-tools) - - [Arhitectură: Auto-Conectare Spring Boot](../../../04-tools) -- [Lanțuirea Uneltelor](../../../04-tools) -- [Rulați Aplicația](../../../04-tools) -- [Folosirea Aplicației](../../../04-tools) - - [Încercați Utilizarea Simplă a Unei Unelte](../../../04-tools) - - [Testați Lanțuirea Unei Unelte](../../../04-tools) - - [Vezi Fluxul Conversației](../../../04-tools) - - [Experimentați cu Cereri Diferite](../../../04-tools) -- [Concepte Cheie](../../../04-tools) - - [Modelul ReAct (Raționament și Acțiune)](../../../04-tools) - - [Importanța Descrierii Uneltelor](../../../04-tools) - - [Gestionarea Sesiunii](../../../04-tools) - - [Gestionarea Erorilor](../../../04-tools) -- [Unelte Disponibile](../../../04-tools) -- [Când Să Folosești Agenți Bazati pe Unelte](../../../04-tools) -- [Unelte vs RAG](../../../04-tools) -- [Pași Următori](../../../04-tools) +- [Parcurgere Video](#parcurgere-video) +- [Ce Vei Învăța](#ce-vei-învăța) +- [Precondiții](#precondiții) +- [Înțelegerea Agenților AI cu Unelte](#înțelegerea-agenților-ai-cu-unelte) +- [Cum Funcționează Apelarea Uneltelor](#cum-funcționează-apelarea-uneltelor) + - [Definițiile Uneltelor](#definițiile-uneltelor) + - [Luarea Deciziilor](#luarea-deciziilor) + - [Executarea](#executarea) + - [Generarea Răspunsului](#generarea-răspunsului) + - [Arhitectură: Auto-Conectare Spring Boot](#arhitectură-auto-conectare-spring-boot) +- [Lanțuirea Uneltelor](#lanțuirea-uneltelor) +- [Pornirea Aplicației](#pornirea-aplicației) +- [Folosirea Aplicației](#utilizarea-aplicației) + - [Încearcă Utilizarea Simplă a Unei Unelte](#încearcă-utilizarea-simplă-a-instrumentului) + - [Testează Lanțuirea Uneltelor](#testează-lanțuirea-instrumentelor) + - [Vezi Fluxul Conversației](#vezi-fluxul-conversației) + - [Experimentează cu Cereri Diferite](#experimentează-cu-cereri-diferite) +- [Concepte Cheie](#concepte-cheie) + - [Modelul ReAct (Raționament și Acțiune)](#tiparul-react-raționare-și-acțiune) + - [Descrierile Unealtelor Contează](#descrierile-instrumentelor-contează) + - [Gestionarea Sesiunii](#gestionarea-sesiunilor) + - [Gestionarea Erorilor](#gestionarea-erorilor) +- [Unelte Disponibile](#instrumente-disponibile) +- [Când să Folosești Agenți Bazati pe Unelte](#când-să-folosești-agenți-bazate-pe-instrumente) +- [Unelte vs RAG](#instrumente-vs-rag) +- [Pașii Următori](#pașii-următori) ## Parcurgere Video @@ -37,44 +37,44 @@ Urmărește această sesiune live care explică cum să începi cu acest modul: ## Ce Vei Învăța -Până acum, ai învățat cum să porți conversații cu AI, cum să structurezi prompturi eficient și cum să bazezi răspunsurile pe documentele tale. Dar există încă o limitare fundamentală: modelele de limbaj pot genera doar text. Nu pot verifica vremea, face calcule, interoga baze de date sau interacționa cu sisteme externe. +Până acum, ai învățat cum să ai conversații cu AI, să structurezi prompturi eficient și să ancorezi răspunsuri în documentele tale. Dar există încă o limitare fundamentală: modelele de limbaj pot genera doar text. Ele nu pot verifica vremea, executa calcule, întreba baze de date sau interacționa cu sisteme externe. -Uneltele schimbă acest lucru. Oferind modelului acces la funcții pe care le poate apela, îl transformi dintr-un generator de text într-un agent care poate lua acțiuni. Modelul decide când are nevoie de o unealtă, ce unealtă să folosească și ce parametri să transmită. Codul tău execută funcția și returnează rezultatul. Modelul încorporează acel rezultat în răspunsul său. +Uneltele schimbă asta. Dând modelului acces la funcții pe care le poate apela, îl transformi dintr-un generator de text într-un agent care poate lua acțiuni. Modelul decide când are nevoie de o unealtă, ce unealtă să folosească și ce parametri să trimită. Codul tău execută funcția și returnează rezultatul. Modelul încorporează acel rezultat în răspunsul său. ## Precondiții - Modulul [01 - Introducere](../01-introduction/README.md) finalizat (resurse Azure OpenAI implementate) -- Modulele anterioare recomandate (acest modul face referire la [conceptele RAG din Modulul 03](../03-rag/README.md) în comparația Unelte vs RAG) -- Fișier `.env` în directorul principal cu acreditările Azure (creat de `azd up` în Modulul 01) +- Modulele anterioare recomandate (acest modul face referire la [conceptul RAG din Modulul 03](../03-rag/README.md) în comparația Unelte vs RAG) +- Fișier `.env` în directorul rădăcină cu acreditări Azure (creat de `azd up` în Modulul 01) -> **Notă:** Dacă nu ai finalizat Modulul 01, urmează mai întâi instrucțiunile de implementare de acolo. +> **Notă:** Dacă nu ai terminat Modulul 01, urmează întâi instrucțiunile de implementare de acolo. ## Înțelegerea Agenților AI cu Unelte -> **📝 Notă:** Termenul „agenți” în acest modul se referă la asistenți AI îmbunătățiți cu capabilități de apelare a uneltelor. Acest lucru este diferit față de modelele **Agentic AI** (agenți autonomi cu planificare, memorie și raționament în mai mulți pași) pe care le vom acoperi în [Modulul 05: MCP](../05-mcp/README.md). +> **📝 Notă:** Termenul „agenți” în acest modul se referă la asistenți AI îmbunătățiți cu capabilități de apelare a uneltelor. Acest lucru este diferit de modelele **Agentic AI** (agenți autonomi cu planificare, memorie și raționament pe mai mulți pași) pe care le vom aborda în [Modulul 05: MCP](../05-mcp/README.md). -Fără unelte, un model de limbaj poate doar să genereze text pe baza datelor sale de antrenament. Întreabă-l despre vremea actuală și va trebui să ghicească. Dă-i unelte și poate apela un API meteo, poate face calcule sau poate interoga o bază de date — apoi încorporează aceste rezultate reale în răspuns. +Fără unelte, un model de limbaj poate doar genera text pe baza datelor de antrenament. Întreabă-l care este vremea în prezent, și el trebuie să ghicească. Dă-i unelte și poate apela o API meteo, efectua calcule sau interoga o bază de date — apoi împletește acele rezultate reale în răspunsul său. Fără Unelte vs Cu Unelte -*Fără unelte modelul poate doar să ghicească — cu unelte poate apela API-uri, face calcule și returna date în timp real.* +*Fără unelte modelul poate doar ghici — cu unelte poate apela API-uri, executa calcule și returna date în timp real.* -Un agent AI cu unelte urmează un model de **Raționament și Acțiune (ReAct)**. Modelul nu răspunde doar — gândește ce are nevoie, acționează apelând o unealtă, observă rezultatul și apoi decide dacă acționează din nou sau oferă răspunsul final: +Un agent AI cu unelte urmează un model **Raționare și Acțiune (ReAct)**. Modelul nu doar răspunde — gândește ce are nevoie, acționează apelând o unealtă, observă rezultatul și apoi decide dacă să acționeze din nou sau să ofere răspunsul final: -1. **Raționează** — Agentul analizează întrebarea utilizatorului și stabilește ce informații are nevoie +1. **Raționează** — Agentul analizează întrebarea utilizatorului și determină ce informație îi trebuie 2. **Acționează** — Agentul selectează unealta potrivită, generează parametrii corecți și o apelează -3. **Observă** — Agentul primește ieșirea uneltei și evaluează rezultatul -4. **Repetă sau Răspunde** — Dacă sunt necesare mai multe date, agentul revine la pasul anterior; altfel formulează un răspuns în limbaj natural +3. **Observează** — Agentul primește rezultatul uneltei și evaluează rezultatul +4. **Repetă sau Răspunde** — Dacă este nevoie de mai multe date, agentul revine la pasul anterior; altfel compune un răspuns în limbaj natural Modelul ReAct *Ciclul ReAct — agentul raționează ce să facă, acționează apelând o unealtă, observă rezultatul și repetă până poate oferi răspunsul final.* -Acest proces se întâmplă automat. Definiți uneltele și descrierile lor. Modelul gestionează luarea deciziilor despre când și cum să le folosească. +Acest proces se întâmplă automat. Definiți uneltele și descrierile lor. Modelul gestionează luarea deciziilor despre când și cum să le utilizeze. ## Cum Funcționează Apelarea Uneltelor -### Definiții ale Uneltelor +### Definițiile Uneltelor [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Logica ta pentru căutarea vremii + // Logica ta de căutare a vremii return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,53 +96,53 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Asistentul este conectat automat de Spring Boot cu: +// Asistentul este configurat automat de Spring Boot cu: // - Bean-ul ChatModel // - Toate metodele @Tool din clasele @Component // - ChatMemoryProvider pentru gestionarea sesiunilor ``` -Diagrama de mai jos descompune fiecare adnotare și arată cum fiecare element ajută AI să înțeleagă când să apeleze unealta și ce argumente să transmită: +Diagrama de mai jos detaliază fiecare adnotare și arată cum fiecare parte ajută AI să înțeleagă când să apeleze unealta și ce argumente să transmită: -Anatomia Definițiilor Uneltelor +Anatomia Definițiilor Uneletelor -*Anatomia definiției unei unelte — @Tool spune AI când să o folosească, @P descrie fiecare parametru, iar @AiService le leagă pe toate automat la pornire.* +*Anatomia definiției unei unelte — @Tool spune AI-ului când să o folosească, @P descrie fiecare parametru, iar @AiService le conectează pe toate la pornire.* > **🤖 Încearcă cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschide [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) și întreabă: -> - „Cum aș integra un API meteo real precum OpenWeatherMap în loc de date mock?” -> - „Ce face o descriere bună de unealtă care ajută AI să o folosească corect?” +> - „Cum aș integra o API meteo reală, cum ar fi OpenWeatherMap, în loc de date mock?” +> - „Ce face o descriere bună a unei unelte care ajută AI să o folosească corect?” > - „Cum gestionez erorile API și limitele de rată în implementările uneltelor?” ### Luarea Deciziilor -Când un utilizator întreabă „Cum este vremea în Seattle?”, modelul nu alege o unealtă aleator. Compară intenția utilizatorului cu fiecare descriere de unealtă la care are acces, le evaluează relevanța și selectează cea mai potrivită. Apoi generează un apel de funcție structurat cu parametrii potriviți — în acest caz, setează `location` la `"Seattle"`. +Când un utilizator întreabă „Cum e vremea în Seattle?”, modelul nu alege aleator o unealtă. Compară intenția utilizatorului cu fiecare descriere de unealtă de care dispune, evaluează relevanța și selectează cea mai bună potrivire. Apoi generează un apel de funcție structurat cu parametrii corecți — în acest caz, setând `location` la `"Seattle"`. -Dacă nicio unealtă nu corespunde cererii utilizatorului, modelul revine la a răspunde din propria sa cunoaștere. Dacă mai multe unelte se potrivesc, alege pe cea mai specifică. +Dacă nicio unealtă nu corespunde cererii utilizatorului, modelul răspunde din propria sa cunoaștere. Dacă mai multe unelte corespund, alege pe cea mai specifică. -Cum Decide AI Ce Unealtă Să Folosească +Cum Decide AI care Unealtă să Folosească -*Modelul evaluează fiecare unealtă disponibilă în raport cu intenția utilizatorului și selectează cea mai potrivită — de aceea contează să scrii descrieri clare și specifice pentru unelte.* +*Modelul evaluează fiecare unealtă disponibilă față de intenția utilizatorului și selectează cea mai bună potrivire — de aceea contează să scrii descrieri clare și specifice pentru unelte.* -### Execuție +### Executarea [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot leagă automat interfața declarativă `@AiService` cu toate uneltele înregistrate, iar LangChain4j execută apelurile uneltelor automat. În spate, un apel complet al unei unelte trece prin șase etape — de la întrebarea în limbaj natural a utilizatorului până la răspunsul tot în limbaj natural: +Spring Boot auto-conectează interfața declarativă `@AiService` cu toate uneltele înregistrate, iar LangChain4j execută apelurile uneltelor automat. În spate, un apel complet de unealtă parcurge șase etape — de la întrebarea utilizatorului în limbaj natural până la răspunsul final în limbaj natural: -Fluxul Apelului Uneletei +Fluxul Apelului Unealtelor -*Fluxul cap-la-cap — utilizatorul pune o întrebare, modelul selectează o unealtă, LangChain4j o execută, iar modelul încorporează rezultatul într-un răspuns natural.* +*Fluxul complet — utilizatorul pune o întrebare, modelul selectează o unealtă, LangChain4j o execută, iar modelul împletește rezultatul într-un răspuns natural.* -Dacă ai rulat [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) în Modulul 00, ai văzut deja acest model în acțiune — uneltele `Calculator` erau apelate în același mod. Diagrama de secvență de mai jos arată exact ce s-a întâmplat în spate în timpul acelui demo: +În culise, `AiServices` rulează același ciclu de apel de unelte pentru orice unealtă — aici ilustrat cu un simplu `Calculator`. Diagrama de secvență de mai jos arată exact ce se întâmplă în spate: -Diagrama Secvenței Apelului Uneletei +Diagrama de Secvență a Apelării Uneletelor -*Bucle de apelare a uneltei din demo-ul Quick Start — `AiServices` trimite mesajul și schemele uneltelor către LLM, LLM răspunde cu un apel de funcție precum `add(42, 58)`, LangChain4j execută metoda `Calculator` local și trimite rezultatul înapoi pentru răspunsul final.* +*Ciclul de apelare a uneltei — `AiServices` trimite mesajul tău și schemele uneltelor către LLM, LLM răspunde cu un apel de funcție ca `add(42, 58)`, LangChain4j execută metoda `Calculator` local și trimite rezultatul înapoi pentru răspunsul final.* > **🤖 Încearcă cu [GitHub Copilot](https://github.com/features/copilot) Chat:** Deschide [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) și întreabă: > - „Cum funcționează modelul ReAct și de ce este eficient pentru agenții AI?” > - „Cum decide agentul ce unealtă să folosească și în ce ordine?” -> - „Ce se întâmplă dacă execuția unei unelte eșuează — cum ar trebui să gestionez erorile robust?” +> - „Ce se întâmplă dacă execuția unei unelte eșuează - cum ar trebui să gestionez erorile solid?” ### Generarea Răspunsului @@ -150,50 +150,50 @@ Modelul primește datele meteo și le formatează într-un răspuns în limbaj n ### Arhitectură: Auto-Conectare Spring Boot -Acest modul folosește integrarea LangChain4j cu Spring Boot prin interfețe declarative `@AiService`. La pornire, Spring Boot detectează fiecare `@Component` care conține metode cu `@Tool`, bean-ul tău `ChatModel`, și `ChatMemoryProvider` — apoi le conectează pe toate într-o singură interfață `Assistant` fără niciun cod suplimentar. +Acest modul folosește integrarea LangChain4j cu Spring Boot și interfețele declarative `@AiService`. La pornire, Spring Boot descoperă fiecare `@Component` care conține metode `@Tool`, bean-ul tău `ChatModel` și `ChatMemoryProvider` — apoi le conectează pe toate într-o singură interfață `Assistant` fără cod repetitiv. Arhitectura Auto-Conectării Spring Boot -*Interfața @AiService leagă ChatModel, componentele uneltelor și furnizorul de memorie — Spring Boot realizează conexiunile automat.* +*Interfața @AiService le leagă pe toate - ChatModel, componentele uneltelor și furnizorul de memorie — Spring Boot gestionează automat toate conexiunile.* -Iată întregul ciclu al solicitării ca diagramă de secvență — de la cererea HTTP prin controller, service și proxy auto-conectat, până la execuția uneltei și înapoi: +Iată ciclul complet de viață al cererii ca diagramă de secvență — de la cererea HTTP prin controller, serviciu și proxy auto-conectat, până la execuția uneltei și înapoi: -Secvență de Apel a Uneletei cu Spring Boot +Diagrama Secvențială a Apelului Uneletelor Spring Boot -*Ciclul complet al solicitării Spring Boot — cererea HTTP trece prin controller și service către proxy Assistant auto-conectat, care orchestrează LLM și apelurile uneltelor automat.* +*Ciclul complet de viață al cererii Spring Boot — cererea HTTP parcurge controllerul și serviciul către proxy-ul Assistant auto-conectat, care orchestrează automat LLM și apelurile uneltelor.* Beneficii cheie ale acestei abordări: -- **Auto-conectare Spring Boot** — ChatModel și uneltele sunt injectate automat -- **Modelul @MemoryId** — Management automat al memoriei pe sesiune +- **Auto-conectare Spring Boot** — ChatModel și uneltele injectate automat +- **Model @MemoryId** — Gestionarea automată a memoriei bazate pe sesiune - **Instanță unică** — Assistant creat o singură dată și reutilizat pentru performanță mai bună -- **Execuție tip-safe** — metode Java apelate direct cu conversie de tip -- **Orchestrare multi-turn** — gestionează lanțuirea uneltelor automat -- **Fără boilerplate** — fără apeluri manuale `AiServices.builder()` sau HashMap pentru memorie +- **Execuție tip-sigură** — metode Java apelate direct cu conversie de tip +- **Orchestrare multi-turn** — gestionează automat lanțuirea uneltelor +- **Zero cod repetitiv** — fără apeluri manuale `AiServices.builder()` sau hărți HashMap pentru memorie Abordările alternative (manual `AiServices.builder()`) necesită mai mult cod și pierd beneficiile integrării Spring Boot. ## Lanțuirea Uneltelor -**Lanțuirea Uneltelor** — Puterea reală a agenților bazati pe unelte apare când o singură întrebare necesită mai multe unelte. Întreabă „Cum este vremea în Seattle în Fahrenheit?” și agentul leagă automat două unelte: mai întâi apelează `getCurrentWeather` pentru temperatura în Celsius, apoi transmite valoarea către `celsiusToFahrenheit` pentru conversie — toate într-un singur tur de conversație. +**Lanțuirea Uneltelor** — Puterea reală a agenților bazati pe unelte apare când o singură întrebare necesită mai multe unelte. Întreabă „Cum e vremea în Seattle în Fahrenheit?” și agentul leagă automat două unelte: mai întâi apelează `getCurrentWeather` pentru temperatura în Celsius, apoi transmite acea valoare lui `celsiusToFahrenheit` pentru conversie — toate într-un singur tur de conversație. -Exemplu de Lanțuire a Uneletei +Exemplu de Lanțuire a Uneletelor -*Lanțuirea uneltelor în acțiune — agentul apelează mai întâi getCurrentWeather, apoi transmite rezultatul în Celsius către celsiusToFahrenheit și oferă un răspuns combinat.* +*Lanțuirea uneltelor în acțiune — agentul apelează mai întâi getCurrentWeather, apoi transferă rezultatul în Celsius către celsiusToFahrenheit și oferă un răspuns combinat.* -**Eșuări Grațioase** — Cere vremea într-un oraș care nu este în datele mock. Unealta returnează un mesaj de eroare, iar AI explică că nu poate ajuta în loc să se blocheze. Uneltele eșuează în siguranță. Diagrama de mai jos compară cele două abordări — cu gestionarea corectă a erorilor, agentul prinde excepția și răspunde util, pe când fără aceasta aplicația întreagă se blochează: +**Eșecuri Gratioase** — Cere vremea într-un oraș care nu este în datele mock. Unealta returnează un mesaj de eroare, iar AI explică că nu poate ajuta în loc să se blocheze. Uneltele eșuează în siguranță. Diagrama de mai jos compară cele două abordări — cu gestionare corectă a erorilor agentul prinde excepția și răspunde ajutător, în timp ce fără ea întreaga aplicație cade: Fluxul Gestionării Erorilor *Când o unealtă eșuează, agentul prinde eroarea și răspunde cu o explicație utilă în loc să se blocheze.* -Acest lucru se întâmplă într-un singur tur de conversație. Agentul orchestrează automat mai multe apeluri de unelte. +Acest proces se întâmplă într-un singur tur de conversație. Agentul orchestrează apeluri multiple de unelte autonom. -## Rulați Aplicația +## Pornirea Aplicației -**Verificați implementarea:** +**Verifică implementarea:** -Asigurați-vă că fișierul `.env` există în directorul principal cu acreditările Azure (creat în timpul Modulului 01). Rulați acest lucru din directorul modulului (`04-tools/`): +Asigură-te că fișierul `.env` există în directorul rădăcină cu acreditări Azure (creat în Modulul 01). Rulează acest lucru din directorul modulului (`04-tools/`): **Bash:** ```bash @@ -205,30 +205,30 @@ cat ../.env # Ar trebui să afișeze AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Ar trebui să afișeze AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Porniți aplicația:** +**Pornește aplicația:** -> **Notă:** Dacă ați pornit deja toate aplicațiile folosind `./start-all.sh` din directorul principal (așa cum a fost descris în Modulul 01), acest modul este deja rulând pe portul 8084. Puteți sări peste comenzile de pornire de mai jos și să mergeți direct la http://localhost:8084. +> **Notă:** Dacă ai pornit deja toate aplicațiile folosind `./start-all.sh` din directorul rădăcină (așa cum este descris în Modulul 01), acest modul rulează deja pe portul 8084. Poți să sari peste comenzile de pornire de mai jos și să accesezi direct http://localhost:8084. **Opțiunea 1: Folosirea Spring Boot Dashboard (Recomandat pentru utilizatorii VS Code)** -Containerul de dezvoltare include extensia Spring Boot Dashboard, care oferă o interfață vizuală pentru gestionarea tuturor aplicațiilor Spring Boot. O puteți găsi în bara de activități din partea stângă a VS Code (căutați iconița Spring Boot). +Containerul de dezvoltare include extensia Spring Boot Dashboard, care oferă o interfață vizuală pentru gestionarea tuturor aplicațiilor Spring Boot. O poți găsi în bara de activități din partea stângă a VS Code (caută iconița Spring Boot). -Din Spring Boot Dashboard puteți: -- Vedea toate aplicațiile Spring Boot disponibile în spațiul de lucru -- Porni/opri aplicații cu un singur click -- Vizualiza jurnalele aplicației în timp real -- Monitoriza starea aplicației -Pur și simplu faceți clic pe butonul de redare de lângă „tools” pentru a porni acest modul sau porniți toate modulele odată. +Din Spring Boot Dashboard poți: +- Vizualiza toate aplicațiile Spring Boot disponibile în spațiul de lucru +- Porni/opri aplicațiile cu un singur click +- Vizualiza jurnalele aplicațiilor în timp real +- Monitoriza starea aplicațiilor -Iată cum arată Spring Boot Dashboard în VS Code: +Pur și simplu apasă butonul de start lângă „tools” pentru a porni acest modul sau pornește toate modulele simultan. +Așa arată Spring Boot Dashboard în VS Code: Spring Boot Dashboard -*Spring Boot Dashboard în VS Code — porniți, opriți și monitorizați toate modulele dintr-un singur loc* +*Dashboard-ul Spring Boot în VS Code — pornește, oprește și monitorizează toate modulele dintr-un singur loc* -**Opțiunea 2: Folosind scripturi shell** +**Opțiunea 2: Utilizarea scripturilor shell** -Porniți toate aplicațiile web (modulele 01-04): +Pornește toate aplicațiile web (modulele 01-04): **Bash:** ```bash @@ -242,7 +242,7 @@ cd .. # Din directorul rădăcină .\start-all.ps1 ``` -Sau porniți doar acest modul: +Sau pornește doar acest modul: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Ambele scripturi încarcă automat variabilele de mediu din fișierul `.env` de la rădăcină și vor construi JAR-urile dacă nu există. +Ambele scripturi încarcă automat variabilele de mediu din fișierul rădăcină `.env` și vor construi JAR-urile dacă acestea nu există. -> **Notă:** Dacă preferați să construiți manual toate modulele înainte de a porni: +> **Notă:** Dacă preferi să construiești manual toate modulele înainte de a le porni: > > **Bash:** > ```bash @@ -272,13 +272,13 @@ Ambele scripturi încarcă automat variabilele de mediu din fișierul `.env` de > mvn clean package -DskipTests > ``` -Deschideți http://localhost:8084 în browserul dvs. +Deschide http://localhost:8084 în browserul tău. -**Pentru oprire:** +**Pentru a opri:** **Bash:** ```bash -./stop.sh # Numai acest modul +./stop.sh # Doar acest modul # Sau cd .. && ./stop-all.sh # Toate modulele ``` @@ -290,98 +290,98 @@ cd .. && ./stop-all.sh # Toate modulele cd ..; .\stop-all.ps1 # Toate modulele ``` -## Utilizarea aplicației +## Utilizarea Aplicației -Aplicația oferă o interfață web unde puteți interacționa cu un agent AI care are acces la unelte pentru vreme și conversia temperaturii. Iată cum arată interfața — include exemple rapide și un panou de chat pentru trimiterea cererilor: +Aplicația oferă o interfață web unde poți interacționa cu un agent AI care are acces la instrumente de vreme și conversie a temperaturii. Iată cum arată interfața — include exemple rapide și un panou de chat pentru a trimite cereri: AI Agent Tools Interface -*Interfața AI Agent Tools - exemple rapide și interfață de chat pentru interacțiunea cu uneltele* +*Interfața AI Agent Tools - exemple rapide și interfață de chat pentru interacțiunea cu instrumentele* -### Încercați utilizarea simplă a unealtelor +### Încearcă Utilizarea Simplă a Instrumentului -Începeți cu o cerere simplă: „Convertește 100 de grade Fahrenheit în Celsius”. Agentul recunoaște că are nevoie de unealta de conversie a temperaturii, o apelează cu parametrii corecți și returnează rezultatul. Observați cât de natural se simte - nu ați specificat ce unealtă să folosească sau cum să o apeleze. +Începe cu o cerere simplă: "Convertește 100 grade Fahrenheit în Celsius". Agentul recunoaște că are nevoie de instrumentul de conversie a temperaturii, îl apelează cu parametrii corecți și returnează rezultatul. Observă cât de natural se simte — nu ai specificat ce instrument să folosească sau cum să-l apeleze. -### Testați combinarea uneltelor +### Testează Lanțuirea Instrumentelor -Acum încercați ceva mai complex: „Care este vremea în Seattle și convertește-o în Fahrenheit?” Urmăriți cum agentul parcurge aceasta în pași. Mai întâi obține vremea (care returnează Celsius), recunoaște că trebuie să convertească în Fahrenheit, apelează unealta de conversie și combină ambele rezultate într-un singur răspuns. +Acum încearcă ceva mai complex: "Care este vremea în Seattle și convertește-o în Fahrenheit?" Urmărește cum agentul parcurge pașii. Mai întâi obține vremea (care returnează în Celsius), apoi recunoaște că trebuie să convertească în Fahrenheit, apelează instrumentul de conversie și combină ambele rezultate într-un singur răspuns. -### Vedeți fluxul conversației +### Vezi Fluxul Conversației -Interfața de chat păstrează istoricul conversației, permițând interacțiuni pe mai multe tururi. Puteți vedea toate întrebările și răspunsurile anterioare, facilitând urmărirea conversației și înțelegerea modului în care agentul construiește context pe mai multe schimburi. +Interfața de chat păstrează istoricul conversației, permițându-ți să ai interacțiuni cu schimburi multiple. Poți vedea toate întrebările și răspunsurile anterioare, ceea ce face ușoară urmărirea conversației și înțelegerea modului în care agentul construiește context pe durata mai multor schimburi. Conversation with Multiple Tool Calls -*Conversație multi-tur care arată conversii simple, consultări meteo și combinarea uneltelor* +*Conversație cu mai multe schimburi arătând conversii simple, căutări meteo și lanțuirea instrumentelor* -### Experimentează cu cereri diferite +### Experimentează cu Cereri Diferite -Încearcă diverse combinații: -- Consultări meteo: „Care este vremea în Tokyo?” -- Conversii temperatură: „Cât înseamnă 25°C în Kelvin?” -- Cereri combinate: „Verifică vremea în Paris și spune-mi dacă este peste 20°C” +Încearcă combinații variate: +- Căutări meteo: "Care este vremea în Tokyo?" +- Conversii de temperatură: "Cât fac 25°C în Kelvin?" +- Cereri combinate: "Verifică vremea în Paris și spune-mi dacă este peste 20°C" -Observați cum agentul interpretează limbajul natural și îl mapează la apelurile corespunzătoare ale uneltelor. +Observă cum agentul interpretează limbajul natural și îl mapează la apeluri adecvate ale instrumentelor. -## Concepte-cheie +## Concepte Cheie -### Pattern ReAct (Raționare și Acțiune) +### Tiparul ReAct (Raționare și Acțiune) -Agentul alternează între raționare (decide ce să facă) și acțiune (folosește unelte). Acest pattern permite rezolvarea autonomă a problemelor, nu doar răspunsuri la instrucțiuni. +Agentul alternează între raționare (decide ce să facă) și acțiune (folosește instrumentele). Acest tipar permite rezolvarea autonomă a problemelor, nu doar răspunsuri la instrucțiuni. -### Descrierile uneltelor contează +### Descrierile Instrumentelor Contează -Calitatea descrierilor uneltelor influențează direct cum sunt ele folosite de agent. Descrierile clare și specifice ajută modelul să înțeleagă când și cum să apeleze fiecare unealtă. +Calitatea descrierilor instrumentelor tale influențează direct cât de bine le folosește agentul. Descrieri clare și specifice ajută modelul să înțeleagă când și cum să apeleze fiecare instrument. -### Gestionarea sesiunii +### Gestionarea Sesiunilor -Anotația `@MemoryId` permite gestionarea automată a memoriei pe bază de sesiune. Fiecare ID de sesiune primește o instanță `ChatMemory` gestionată de bean-ul `ChatMemoryProvider`, astfel încât mai mulți utilizatori pot interacționa simultan cu agentul fără ca conversațiile să se amestece. Diagrama de mai jos ilustrează cum mai mulți utilizatori sunt direcționați către stocări de memorie izolate pe baza ID-urilor lor de sesiune: +Anotarea `@MemoryId` activează gestionarea memoriei bazate pe sesiuni automat. Fiecare ID de sesiune primește propria instanță `ChatMemory` gestionată de bean-ul `ChatMemoryProvider`, astfel încât mai mulți utilizatori pot interacționa cu agentul simultan fără ca conversațiile lor să se amestece. Diagrama următoare arată cum mai mulți utilizatori sunt direcționați către stocări de memorie izolate pe baza ID-urilor de sesiune: Session Management with @MemoryId -*Fiecare ID de sesiune corespunde unui istoric de conversație izolat — utilizatorii nu văd niciodată mesajele celorlalți.* +*Fiecare ID de sesiune se mapează la un istoric de conversație izolat — utilizatorii nu văd mesajele celorlalți.* -### Gestionarea erorilor +### Gestionarea Erorilor -Uneltele pot da greș — API-urile pot expira, parametrii pot fi invalizi, serviciile externe pot cădea. Agenții de producție au nevoie de gestionare a erorilor pentru ca modelul să poată explica problemele sau să încerce alternative, în loc să oprească întreaga aplicație. Când o unealtă aruncă o excepție, LangChain4j o prinde și trimite mesajul de eroare înapoi către model, care poate apoi explica problema în limbaj natural. +Instrumentele pot da erori — API-urile pot expira, parametrii pot fi invalizi, serviciile externe pot cădea. Agenții de producție au nevoie de gestionarea erorilor pentru ca modelul să poată explica problemele sau să încerce alternative, în loc să se blocheze toată aplicația. Când un instrument aruncă o excepție, LangChain4j o prinde și transmite mesajul de eroare înapoi modelului, care poate apoi să explice problema în limbaj natural. -## Unelte disponibile +## Instrumente Disponibile -Diagrama de mai jos arată ecosistemul larg de unelte pe care le poți construi. Acest modul demonstrează unelte pentru vreme și temperatură, dar același pattern `@Tool` funcționează pentru orice metodă Java — de la interogări de baze de date la procesare de plăți. +Diagrama de mai jos arată ecosistemul larg de instrumente pe care le poți construi. Acest modul demonstrează instrumente meteo și de temperatură, dar același tipar `@Tool` funcționează pentru orice metodă Java — de la interogări baze de date la procesare plăți. Tool Ecosystem -*Orice metodă Java anotată cu @Tool devine disponibilă pentru AI — patternul se extinde la baze de date, API-uri, email, operații pe fișiere și multe altele.* +*Orice metodă Java anotată cu @Tool devine disponibilă pentru AI — tiparul se extinde la baze de date, API-uri, email, operații pe fișiere și multe altele.* -## Când să folosești agenți pe bază de unelte +## Când să Folosești Agenți bazate pe Instrumente -Nu toate cererile necesită unelte. Decizia depinde de dacă AI trebuie să interacționeze cu sisteme externe sau poate răspunde din propria sa cunoaștere. Ghidul de mai jos rezumă când uneltele adaugă valoare și când nu sunt necesare: +Nu toate cererile necesită instrumente. Decizia depinde dacă AI are nevoie să interacționeze cu sisteme externe sau poate răspunde din propria cunoaștere. Ghidul următor rezumă când instrumentele adaugă valoare și când sunt inutile: When to Use Tools -*Un ghid rapid de decizie — uneltele sunt pentru date în timp real, calcule și acțiuni; cunoștințe generale și sarcini creative nu au nevoie de ele.* +*Un ghid rapid de decizie — instrumentele sunt pentru date în timp real, calcule și acțiuni; cunoștințele generale și sarcinile creative nu le necesită.* -## Unelte vs RAG +## Instrumente vs RAG -Modulele 03 și 04 extind ambele capabilitățile AI, dar în moduri fundamental diferite. RAG dă modelului acces la **cunoștințe** prin regăsirea documentelor. Uneltele îi oferă modelului abilitatea de a lua **acțiuni** prin apelarea funcțiilor. Diagrama de mai jos compară aceste două abordări — de la modul în care funcționează fluxul fiecăruia până la compromisurile dintre ele: +Modulele 03 și 04 extind ambele ce poate face AI-ul, dar în moduri fundamental diferite. RAG dă modelului acces la **cunoștințe** prin recuperarea de documente. Instrumentele oferă modelului capacitatea de a lua **acțiuni** prin apelarea de funcții. Diagrama de mai jos compară aceste două abordări alăturat — de la cum funcționează fiecare flux de lucru până la compromisurile dintre ele: Tools vs RAG Comparison -*RAG regăsește informații din documente statice — Uneltele execută acțiuni și obțin date dinamice, în timp real. Multe sisteme de producție combină ambele.* +*RAG preia informații din documente statice — Instrumentele execută acțiuni și obțin date dinamice, în timp real. Multe sisteme de producție combină ambele.* -În practică, multe sisteme de producție combină ambele abordări: RAG pentru fundamentarea răspunsurilor în documentație, și Unelte pentru a obține date live sau a executa operațiuni. +În practică, multe sisteme de producție combină ambele abordări: RAG pentru a fundamenta răspunsurile în documentația ta și Instrumente pentru a prelua date live sau a efectua operațiuni. -## Pașii următori +## Pașii Următori **Următorul modul:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**Navigare:** [← Anterior: Modul 03 - RAG](../03-rag/README.md) | [Înapoi la Principal](../README.md) | [Următor: Modul 05 - MCP →](../05-mcp/README.md) +**Navigare:** [← Anterior: Modulul 03 - RAG](../03-rag/README.md) | [Înapoi la Principal](../README.md) | [Următorul: Modulul 05 - MCP →](../05-mcp/README.md) --- -**Declinare de responsabilitate**: -Acest document a fost tradus folosind serviciul de traducere automată AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim pentru acuratețe, vă rugăm să țineți cont că traducerile automate pot conține erori sau inexactități. Documentul original, în limba sa nativă, trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist uman. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite cauzate de utilizarea acestei traduceri. +**Declinare a responsabilității**: +Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri. \ No newline at end of file diff --git a/translations/ro/README.md b/translations/ro/README.md index b9b589bfa..1f70d2982 100644 --- a/translations/ro/README.md +++ b/translations/ro/README.md @@ -4,16 +4,16 @@ Un curs pentru construirea aplicațiilor AI cu LangChain4j și Azure OpenAI GPT-5.2, de la chat de bază la agenți AI. -### 🌐 Suport Multilingv +### 🌐 Suport multilingv -#### Suportat prin GitHub Action (Automatizat & Întotdeauna Actualizat) +#### Suportat prin GitHub Action (automatizat și întotdeauna actualizat) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](./README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Preferi să Clonezi Local?** +> **Preferi să clonezi local?** > -> Acest depozit include peste 50 de traduceri în limbi diferite, ceea ce crește semnificativ dimensiunea descărcării. Pentru a clona fără traduceri, folosește sparse checkout: +> Acest depozit include peste 50 de traduceri în limbi străine, ceea ce mărește semnificativ dimensiunea descărcării. Pentru a clona fără traduceri, folosește sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,64 +29,63 @@ Un curs pentru construirea aplicațiilor AI cu LangChain4j și Azure OpenAI GPT- > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Aceasta îți oferă tot ce ai nevoie pentru a finaliza cursul, cu o descărcare mult mai rapidă. +> Acest lucru îți oferă tot ce ai nevoie pentru a finaliza cursul cu o descărcare mult mai rapidă. ## Cuprins -1. [Începere Rapidă](00-quick-start/README.md) - Începe cu LangChain4j -2. [Introducere](01-introduction/README.md) - Învață fundamentele LangChain4j -3. [Ingineria Prompturilor](02-prompt-engineering/README.md) - Stăpânește designul eficient al prompturilor -4. [RAG (Generare Îmbunătățită prin Recuperare)](03-rag/README.md) - Construiește sisteme inteligente bazate pe cunoștințe -5. [Unelte](04-tools/README.md) - Integrează unelte externe și asistenți simpli -6. [MCP (Protocolul Contextului Modelului)](05-mcp/README.md) - Lucrează cu Protocolul Contextului Modelului (MCP) și module Agentic +1. [Introducere](01-introduction/README.md) - Învață fundamentele LangChain4j +2. [Ingineria comenzilor (Prompt Engineering)](02-prompt-engineering/README.md) - Stăpânește proiectarea eficientă a comenzilor +3. [RAG (Generare augmentată prin recuperare)](03-rag/README.md) - Construiește sisteme inteligente bazate pe cunoștințe +4. [Instrumente](04-tools/README.md) - Integrează instrumente externe și asistenți simpli +5. [MCP (Protocolul Contextului Modelului)](05-mcp/README.md) - Lucrează cu Protocolul Contextului Modelului (MCP) și module agentice -### Parcurgeri Video +### Prezentări video -Fiecare modul are o sesiune live companion unde parcurgem conceptele și codul pas cu pas. +Fiecare modul are o sesiune live complementară în care parcurgem conceptele și codul pas cu pas. | Modul | Video | |--------|-------| -| 01 - Introducere | [Începe cu LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Ingineria Prompturilor | [Ingineria Prompturilor cu LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - Introducere | [Începem cu LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Ingineria comenzilor | [Ingineria comenzilor cu LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG cu LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Unelte & 05 - MCP | [Agenți AI cu Unelte și MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Instrumente & 05 - MCP | [Agenți AI cu Instrumente și MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Parcursul de Învățare +## Parcurs de învățare -**Nou în LangChain4j?** Consultă [Glosarul](docs/GLOSSARY.md) pentru definiții ale termenilor și conceptelor cheie. +**Ești nou la LangChain4j?** Consultă [Glosarul](docs/GLOSSARY.md) pentru definiții ale termenilor și conceptelor cheie. -> **Începere Rapidă** +> **Pornire rapidă** -1. Forkază acest depozit în contul tău de GitHub -2. Apasă **Code** → fila **Codespaces** → **...** → **New with options...** -3. Folosește setările implicite – va selecta containerul de dezvoltare creat pentru acest curs -4. Apasă **Create codespace** -5. Așteaptă 5-10 minute ca mediul să fie pregătit -6. Mergi direct la [Începere Rapidă](./00-quick-start/README.md) pentru a începe! +1. Creează un fork al acestui depozit în contul tău GitHub +2. Apasă pe **Code** → fila **Codespaces** → **...** → **New with options...** +3. Folosește setările implicite – acestea vor selecta containerul de Dezvoltare creat pentru acest curs +4. Apasă pe **Create codespace** +5. Așteaptă 5-10 minute pentru ca mediul să fie gata +6. Accesează direct [Introducerea](./01-introduction/README.md) pentru a începe! -După finalizarea modulelor, explorează [Ghidul de Testare](docs/TESTING.md) pentru a vedea conceptele de testare LangChain4j în acțiune. +După ce ai finalizat modulele, explorează [Ghidul de testare](docs/TESTING.md) pentru a vedea conceptele de testare LangChain4j în acțiune. -> **Notă:** Acest training folosește atât Modele GitHub cât și Azure OpenAI. Modulul [Începere Rapidă](00-quick-start/README.md) folosește Modelele GitHub (nu necesită abonament Azure), în timp ce modulele 1-5 folosesc Azure OpenAI. Începe cu un [cont AZURE GRATUIT](https://aka.ms/azure-free-account) dacă nu ai unul. +> **Notă:** Acest training utilizează Azure OpenAI. Pornește cu un [cont GRATUIT Azure](https://aka.ms/azure-free-account) dacă nu ai deja unul. ## Învățare cu GitHub Copilot -Pentru a începe rapid să programezi, deschide acest proiect într-un GitHub Codespace sau în IDE-ul local cu devcontainer-ul oferit. Devcontainer-ul folosit în acest curs vine pre-configurat cu GitHub Copilot pentru programare asistată AI în echipă. +Pentru a începe rapid să codezi, deschide acest proiect într-un GitHub Codespace sau în IDE-ul tău local cu devcontainer-ul oferit. Devcontainer-ul folosit în acest curs este preconfigurat cu GitHub Copilot pentru programare AI în pereche. -Fiecare exemplu de cod include întrebări sugerate pe care le poți adresa lui GitHub Copilot pentru a-ți adânci înțelegerea. Caută prompturile 💡/🤖 în: +Fiecare exemplu de cod include întrebări sugerate pe care le poți adresa GitHub Copilot pentru a-ți aprofunda înțelegerea. Caută indicațiile 💡/🤖 în: -- **Antetele fișierelor Java** - întrebări specifice fiecărui exemplu -- **README-urile modulelor** - sugestii de explorare după exemplele de cod +- **Anteturile fișierelor Java** - Întrebări specifice pentru fiecare exemplu +- **README-urile modulelor** - Indicații de explorare după exemplele de cod -**Cum se folosește:** Deschide orice fișier de cod și pune-i întrebările sugerate lui Copilot. Acesta are context complet asupra codului și poate explica, extinde și sugera alternative. +**Cum se folosește:** Deschide orice fișier de cod și întreabă Copilot întrebările sugerate. Are context complet al codului și poate explica, extinde și sugera alternative. -Vrei să afli mai multe? Consultă [Copilot pentru programare asistată AI](https://aka.ms/GitHubCopilotAI). +Vrei să afli mai multe? Vezi [Copilot pentru programare AI în pereche](https://aka.ms/GitHubCopilotAI). -## Resurse Suplimentare +## Resurse suplimentare ### LangChain @@ -103,48 +102,48 @@ Vrei să afli mai multe? Consultă [Copilot pentru programare asistată AI](http --- -### Seria AI Generativ -[![AI Generativ pentru Începători](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Generativ (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![AI Generativ (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![AI Generativ (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Seria Generative AI +[![Generative AI pentru Începători](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Învățare de Bază +### Învățare de bază [![ML pentru Începători](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science pentru Începători](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![Știința datelor pentru Începători](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI pentru Începători](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Securitate cibernetică pentru începători](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Dezvoltare web pentru începători](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT pentru începători](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![Dezvoltare XR pentru începători](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Securitatea cibernetică pentru Începători](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Seria Copilot -[![Copilot pentru programare pereche AI](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot pentru C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Aventura Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## Obținerea ajutorului +## Obținerea Ajutorului -Dacă întâmpinați dificultăți sau aveți întrebări despre construirea aplicațiilor AI, alăturați-vă: +Dacă întâmpini dificultăți sau ai întrebări despre construirea aplicațiilor AI, alătură-te: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Dacă aveți feedback despre produs sau erori în timpul dezvoltării, vizitați: +Dacă ai feedback despre produs sau erori în timpul construirii, vizitează: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licență -Licența MIT - Consultați fișierul [LICENSE](../../LICENSE) pentru detalii. +Licență MIT - Consultă fișierul [LICENSE](../../LICENSE) pentru detalii. --- -**Declinare de responsabilitate**: -Acest document a fost tradus folosind serviciul de traducere automată AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autoritară. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist uman. Nu suntem responsabili pentru orice neînțelegeri sau interpretări greșite care rezultă din utilizarea acestei traduceri. +**Declinare a responsabilității**: +Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri. \ No newline at end of file diff --git a/translations/ro/docs/GLOSSARY.md b/translations/ro/docs/GLOSSARY.md index 353097126..093ea2ca6 100644 --- a/translations/ro/docs/GLOSSARY.md +++ b/translations/ro/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## Cuprins -- [Concepte de bază](../../../docs) -- [Componente LangChain4j](../../../docs) -- [Concepte AI/ML](../../../docs) -- [Guardrails](../../../docs) -- [Ingineria Promptului](../../../docs) -- [RAG (Generare augmentată prin recuperare)](../../../docs) -- [Agenți și Unelte](../../../docs) -- [Modul Agentic](../../../docs) -- [Protocolul Contextului Modelului (MCP)](../../../docs) -- [Servicii Azure](../../../docs) -- [Testare și Dezvoltare](../../../docs) +- [Concepte de bază](#concepte-de-bază) +- [Componente LangChain4j](#componente-langchain4j) +- [Concepte AI/ML](#concepte-aiml) +- [Măsuri de protecție](#măsuri-de-protecție) +- [Ingineria Promptului](#prompt-engineering---module-02) +- [RAG (Generare augmentată prin recuperare)](#rag-retrieval-augmented-generation---module-03) +- [Agenți și Unelte](#agents-and-tools---module-04) +- [Modul Agentic](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Servicii Azure](#azure-services---module-01) +- [Testare și Dezvoltare](#testing-and-development---testing-guide) Referință rapidă pentru termeni și concepte utilizate pe parcursul cursului. ## Concepte de bază -**Agent AI** - Sistem care folosește AI pentru raționament și acțiune autonomă. [Modul 04](../04-tools/README.md) +**Agent AI** - Sistem care folosește AI pentru a raționa și acționa autonom. [Modul 04](../04-tools/README.md) -**Lanț** - Secvență de operațiuni unde ieșirea alimentează pasul următor. +**Lanț** - Secvență de operații unde ieșirea alimentează pasul următor. -**Fragmentare (Chunking)** - Împărțirea documentelor în bucăți mai mici. Tipic: 300-500 tokeni cu suprapunere. [Modul 03](../03-rag/README.md) +**Fragmentare** - Împărțirea documentelor în bucăți mai mici. Tipic: 300-500 tokeni cu suprapunere. [Modul 03](../03-rag/README.md) -**Fereastra de Context** - Numărul maxim de tokeni pe care un model îl poate procesa. GPT-5.2: 400K tokeni (până la 272K input, 128K output). +**Fereastră de Context** - Numărul maxim de tokeni pe care un model îi poate procesa. GPT-5.2: 400K tokeni (până la 272K input, 128K output). -**Embeddings** - Vectori numerici care reprezintă semnificația textului. [Modul 03](../03-rag/README.md) +**Embeddings** - Vectori numerici care reprezintă sensul textului. [Modul 03](../03-rag/README.md) -**Apelare Funcții** - Modelul generează cereri structurate pentru a apela funcții externe. [Modul 04](../04-tools/README.md) +**Apel de Funcție** - Modelul generează cereri structurate pentru a apela funcții externe. [Modul 04](../04-tools/README.md) **Halucinație** - Când modelele generează informații incorecte dar plauzibile. -**Prompt** - Text de intrare pentru un model de limbaj. [Modul 02](../02-prompt-engineering/README.md) +**Prompt** - Textul de intrare pentru un model lingvistic. [Modul 02](../02-prompt-engineering/README.md) **Căutare Semantică** - Căutare după sens folosind embeddings, nu cuvinte cheie. [Modul 03](../03-rag/README.md) -**Cu Stare vs Fără Stare** - Stateless: fără memorie. Stateful: păstrează istoricul conversației. [Modul 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: fără memorie. Stateful: păstrează istoricul conversației. [Modul 01](../01-introduction/README.md) -**Tokeni** - Unități de bază de text pe care modelele le procesează. Afectează costurile și limitele. [Modul 01](../01-introduction/README.md) +**Tokeni** - Unități fundamentale de text procesate de modele. Afectează costuri și limite. [Modul 01](../01-introduction/README.md) -**Lanț de Unelte** - Execuția secvențială de unelte unde ieșirea informează următorul apel. [Modul 04](../04-tools/README.md) +**Lanț de Unelte** - Execuția secvențială a uneltelor unde ieșirea informează următorul apel. [Modul 04](../04-tools/README.md) ## Componente LangChain4j -**AiServices** - Creează interfețe de servicii AI tip-safe. +**AiServices** - Creează interfețe de servicii AI cu tipuri sigure. **OpenAiOfficialChatModel** - Client unificat pentru modelele OpenAI și Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Creează embeddings folosind clientul oficial OpenAI (suportă OpenAI și Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Creează embeddings folosind clientul oficial OpenAI (suportă atât OpenAI cât și Azure OpenAI). -**ChatModel** - Interfața principală pentru modelele de limbaj. +**ChatModel** - Interfața de bază pentru modelele de limbaj. -**ChatMemory** - Menține istoricul conversației. +**ChatMemory** - Menține istoricul conversațiilor. -**ContentRetriever** - Găsește bucăți relevante de documente pentru RAG. +**ContentRetriever** - Găsește fragmente relevante de documente pentru RAG. **DocumentSplitter** - Împarte documentele în fragmente. -**EmbeddingModel** - Converteste textul în vectori numerici. +**EmbeddingModel** - Convertește textul în vectori numerici. **EmbeddingStore** - Stochează și recuperează embeddings. -**MessageWindowChatMemory** - Menține o fereastră glisantă cu mesajele recente. +**MessageWindowChatMemory** - Menține o fereastră mobilă a mesajelor recente. -**PromptTemplate** - Creează prompturi reutilizabile cu spații `{{variable}}`. +**PromptTemplate** - Creează prompturi reutilizabile cu substituenți `{{variable}}`. -**TextSegment** - Fragment de text cu metadate. Utilizat în RAG. +**TextSegment** - Fragment de text cu metadate. Folosit în RAG. -**ToolExecutionRequest** - Reprezintă o cerere de execuție a unei unelte. +**ToolExecutionRequest** - Reprezintă o cerere de execuție a uneltei. -**UserMessage / AiMessage / SystemMessage** - Tipuri de mesaje în conversație. +**UserMessage / AiMessage / SystemMessage** - Tipuri de mesaje din conversație. ## Concepte AI/ML -**Învățare Few-Shot** - Oferirea de exemple în prompturi. [Modul 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Furnizarea de exemple în prompturi. [Modul 02](../02-prompt-engineering/README.md) -**Model Mare de Limbaj (LLM)** - Modele AI antrenate pe volume mari de text. +**Model de Limbaj Mare (LLM)** - Modele AI antrenate pe volume mari de text. -**Efort de Raționament** - Parametru GPT-5.2 care controlează adâncimea gândirii. [Modul 02](../02-prompt-engineering/README.md) +**Efort de Raționare** - Parametru GPT-5.2 care controlează profunzimea gândirii. [Modul 02](../02-prompt-engineering/README.md) -**Temperatură** - Controlează gradul de aleatoriu al ieșirii. Mică = determinist, mare = creativ. +**Temperatură** - Controlează gradul de aleatoriu al ieșirii. Low=deterministic, high=creativ. **Bază de Date Vectorială** - Bază de date specializată pentru embeddings. [Modul 03](../03-rag/README.md) -**Învățare Zero-Shot** - Realizarea sarcinilor fără exemple. [Modul 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Efectuarea sarcinilor fără exemple. [Modul 02](../02-prompt-engineering/README.md) -## Guardrails - [Modul 00](../00-quick-start/README.md) +## Măsuri de protecție -**Apărare în profunzime** - Abordare de securitate multi-strat combinând guardrails la nivel de aplicație cu filtrele de siguranță ale furnizorului. +**Apărare în Straturi** - Abordare de securitate multi-strat combinând măsuri la nivel de aplicație cu filtre de siguranță ale furnizorului. -**Blocare dură** - Furnizorul returnează eroare HTTP 400 pentru încălcări severe ale conținutului. +**Blocare Dură** - Furnizorul emite eroare HTTP 400 pentru încălcări grave ale conținutului. -**InputGuardrail** - Interfață LangChain4j pentru validarea input-ului utilizatorului înainte de a ajunge la LLM. Economisește cost și latență blocând prompturi dăunătoare devreme. +**InputGuardrail** - Interfață LangChain4j pentru validarea inputului utilizator înainte să ajungă la LLM. Economisește cost și latență blocând prompturile dăunătoare devreme. -**InputGuardrailResult** - Tip de retur pentru validarea guardrail: `success()` sau `fatal("motiv")`. +**InputGuardrailResult** - Tip returnat pentru validarea măsurii de protecție: `success()` sau `fatal("motiv")`. **OutputGuardrail** - Interfață pentru validarea răspunsurilor AI înainte de a le returna utilizatorilor. -**Filtre de Siguranță ale Furnizorului** - Filtre încorporate în furnizorii AI (ex. GitHub Models) care detectează încălcări la nivel de API. +**Filtre de Siguranță ale Furnizorului** - Filtre de conținut integrate de la furnizorii AI (ex. Azure OpenAI) care detectează încălcări la nivel de API. -**Refuz Moale** - Modelul refuză politicos să răspundă fără a genera o eroare. +**Refuz Moale** - Modelul refuză politicos să răspundă fără să arunce o eroare. ## Ingineria Promptului - [Modul 02](../02-prompt-engineering/README.md) -**Lanț de Gândire** - Raționament pas cu pas pentru acuratețe sporită. +**Lanț de Gândire** - Raționare pas-cu-pas pentru o acuratețe mai bună. -**Output Restricționat** - Impunerea unui format sau structură specifică. +**Ieșire Constrânsă** - Impunerea unui format sau structură specifică. -**Entuziasm Ridicat** - Tipar GPT-5.2 pentru raționament detaliat. +**Entuziasm Ridicat** - Tipar GPT-5.2 pentru raționare amănunțită. **Entuziasm Scăzut** - Tipar GPT-5.2 pentru răspunsuri rapide. -**Conversație Multi-Turn** - Menținerea contextului peste schimburi multiple. +**Conversație Multi-Rotundă** - Menținerea contextului pe parcursul schimburilor. -**Promptare Bazată pe Rol** - Stabilirea personajului modelului prin mesaje de sistem. +**Promptare pe Bază de Rol** - Setarea personalității modelului prin mesaje de sistem. -**Auto-Reflecție** - Modelul evaluează și îmbunătățește propria ieșire. +**Auto-Reflecție** - Modelul evaluează și își îmbunătățește ieșirea. -**Analiză Structurată** - Cadru fix de evaluare. +**Analiză Structurată** - Cadru fix pentru evaluare. -**Tipar de Execuție a Sarcinii** - Planificare → Executare → Rezumat. +**Tipar Execuție Sarcină** - Planifică → Execută → Rezumă. ## RAG (Generare augmentată prin recuperare) - [Modul 03](../03-rag/README.md) -**Pipeline de procesare documente** - Încărcare → fragmentare → embedding → stocare. +**Pipelină Procesare Documente** - Încarcă → fragmentează → încorporează → stochează. -**Depozit Embedding în Memorie** - Stocare nepermanentă pentru testare. +**Stocare Embeddings în Memorie** - Stocare nepermanentă pentru testare. -**RAG** - Combină recuperarea cu generarea pentru a fundamenta răspunsuri. +**RAG** - Combină recuperarea cu generarea pentru a fundamenta răspunsurile. -**Scor de Similaritate** - Măsură (0-1) a similarității semantice. +**Scor de Similaritate** - Măsură (0-1) a similitudinii semantice. -**Referință Surse** - Metadate despre conținutul recuperat. +**Referință de Sursă** - Metadate despre conținutul recuperat. ## Agenți și Unelte - [Modul 04](../04-tools/README.md) -**Anotare @Tool** - Marchează metode Java ca unelte apelabile prin AI. +**Anotare @Tool** - Marchează metode Java ca unelte apelabile de AI. -**Tipar ReAct** - Raționează → Acționează → Observează → Repetă. +**Tipar ReAct** - Raționează → Acționează → Observă → Repetă. -**Managementul Sesiunii** - Contexte separate pentru utilizatori diferiți. +**Managementul Sesiunii** - Contexturi separate pentru utilizatori diferiți. **Unealtă** - Funcție pe care un agent AI o poate apela. -**Descriere Unealtă** - Documentație despre scopul și parametrii uneltei. +**Descrierea Uneltei** - Documentația scopului și parametrilor uneltei. ## Modul Agentic - [Modul 05](../05-mcp/README.md) -**Anotare @Agent** - Marchează interfețele ca agenți AI cu definiție declarativă de comportament. +**Anotare @Agent** - Marchează interfețele ca agenți AI cu definiții de comportament declarative. -**Agent Listener** - Hook pentru monitorizarea execuției agentului prin `beforeAgentInvocation()` și `afterAgentInvocation()`. +**Ascultător Agent** - Hook pentru monitorizarea execuției agentului prin `beforeAgentInvocation()` și `afterAgentInvocation()`. -**Agentic Scope** - Memorie partajată unde agenții stochează ieșirile folosind `outputKey` pentru a fi consumate de agenți ulteriori. +**Domeniu Agentic** - Memorie partajată unde agenții stochează ieșiri folosind `outputKey` pentru consumul agentilor downstream. **AgenticServices** - Fabrica pentru crearea de agenți folosind `agentBuilder()` și `supervisorBuilder()`. -**Flux Condițional** - Rutează pe baza condițiilor către agenți specialiști diferiți. +**Flux Condițional** - Rutare pe bază de condiții către agenți specialiști diferiți. -**Human-in-the-Loop** - Tipar de flux de lucru care adaugă verificări umane pentru aprobare sau revizuirea conținutului. +**Omul în Buclă** - Tipar de flux ce adaugă puncte de control umane pentru aprobare sau revizuire a conținutului. -**langchain4j-agentic** - Dependență Maven pentru construire declarativă de agenți (experimental). +**langchain4j-agentic** - Dependență Maven pentru construcție declarativă de agenți (experimental). -**Flux Loop** - Iterează execuția agentului până când o condiție este îndeplinită (de ex. scor calitate ≥ 0.8). +**Flux în Buclă** - Iterează execuția agentului până când o condiție este îndeplinită (ex. scor de calitate ≥ 0.8). -**outputKey** - Parametru de anotare agent care specifică unde sunt stocate rezultatele în Agentic Scope. +**outputKey** - Parametru al anotării agentului care specifică unde se stochează rezultatele în Domeniul Agentic. **Flux Paralel** - Rulează mai mulți agenți simultan pentru sarcini independente. -**Strategia de Răspuns** - Cum formulează supraveghetorul răspunsul final: LAST, SUMMARY sau SCORED. +**Strategie de Răspuns** - Cum formulează supraveghetorul răspunsul final: LAST, SUMMARY sau SCORED. -**Flux Secvențial** - Execută agenți în ordine unde ieșirea curge către pasul următor. +**Flux Secvențial** - Execută agenții în ordine unde ieșirea curge către pasul următor. -**Tipar Agent Supraveghetor** - Tipar avansat agentic în care un LLM supraveghetor decide dinamic ce subagenți să invoce. +**Tipar Agent Supraveghetor** - Tipar agentic avansat în care un LLM supraveghetor decide dinamic ce subagenți să invoce. -## Protocolul Contextului Modelului (MCP) - [Modul 05](../05-mcp/README.md) +## Model Context Protocol (MCP) - [Modul 05](../05-mcp/README.md) **langchain4j-mcp** - Dependență Maven pentru integrarea MCP în LangChain4j. -**MCP** - Protocolul Contextului Modelului: standard pentru conectarea aplicațiilor AI la unelte externe. Construiește o dată, folosește oriunde. +**MCP** - Model Context Protocol: standard pentru conectarea aplicațiilor AI la unelte externe. Construiește o dată, folosește oriunde. -**Client MCP** - Aplicație care se conectează la serverele MCP pentru a descoperi și folosi unelte. +**Client MCP** - Aplicație care se conectează la servere MCP pentru a descoperi și folosi unelte. -**Server MCP** - Serviciu care expune unelte prin MCP cu descrieri clare și scheme de parametri. +**Server MCP** - Serviciu ce expune unelte prin MCP cu descrieri clare și scheme de parametri. -**McpToolProvider** - Componentă LangChain4j ce învelește uneltele MCP pentru folosire în servicii AI și agenți. +**McpToolProvider** - Componentă LangChain4j care înfășoară uneltele MCP pentru utilizare în servicii și agenți AI. -**McpTransport** - Interfață pentru comunicare MCP. Implementări includ Stdio și HTTP. +**McpTransport** - Interfață pentru comunicarea MCP. Implementările includ Stdio și HTTP. -**Transport Stdio** - Transport local prin stdin/stdout. Util pentru acces la sistem de fișiere sau unelte în linia de comandă. +**Transport Stdio** - Transport local prin stdin/stdout. Util pentru acces la sistemul de fișiere sau unelte din linia de comandă. -**StdioMcpTransport** - Implementare LangChain4j care lansează server MCP ca subproces. +**StdioMcpTransport** - Implementarea LangChain4j care pornește server MCP ca proces subprocess. **Descoperire Unelte** - Clientul interoghează serverul pentru unelte disponibile cu descrieri și scheme. ## Servicii Azure - [Modul 01](../01-introduction/README.md) -**Azure AI Search** - Căutare cloud cu capabilități vectoriale. [Modul 03](../03-rag/README.md) +**Azure AI Search** - Căutare în cloud cu capabilități vectoriale. [Modul 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Deplasează resurse Azure. +**Azure Developer CLI (azd)** - Depune resurse Azure. -**Azure OpenAI** - Serviciul AI enterprise al Microsoft. +**Azure OpenAI** - Serviciul AI enterprise Microsoft. **Bicep** - Limbaj Azure pentru infrastructură ca cod. [Ghid Infrastructură](../01-introduction/infra/README.md) -**Nume Deplasărilor** - Numele pentru deployment model în Azure. +**Numele Deployerii** - Numele implementării modelului în Azure. -**GPT-5.2** - Cel mai recent model OpenAI cu control al raționamentului. [Modul 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Modelul OpenAI cel mai nou cu control de raționare. [Modul 02](../02-prompt-engineering/README.md) -## Testare și Dezvoltare - [Ghid Testare](TESTING.md) +## Testare și Dezvoltare - [Ghid de Testare](TESTING.md) -**Dev Container** - Mediu de dezvoltare containerizat. [Configurație](../../../.devcontainer/devcontainer.json) - -**GitHub Models** - Playground gratuit pentru modele AI. [Modul 00](../00-quick-start/README.md) +**Container Dev** - Mediu containerizat de dezvoltare. [Configurație](../../../.devcontainer/devcontainer.json) **Testare în Memorie** - Testare cu stocare în memorie. **Testare de Integrare** - Testare cu infrastructură reală. -**Maven** - Instrument Java de automatizare a construirii. +**Maven** - Unealtă de automatizare build Java. -**Mockito** - Framework Java pentru mocking. +**Mockito** - Framework Java pentru simulări. -**Spring Boot** - Framework pentru aplicații Java. [Modul 01](../01-introduction/README.md) +**Spring Boot** - Framework aplicații Java. [Modul 01](../01-introduction/README.md) --- -**Declinare de responsabilitate**: -Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original, în limba sa nativă, trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist uman. Nu ne asumăm răspunderea pentru eventualele neînțelegeri sau interpretări greșite cauzate de utilizarea acestei traduceri. +**Declinare a responsabilității**: +Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri. \ No newline at end of file diff --git a/translations/ro/docs/TESTING.md b/translations/ro/docs/TESTING.md index 29d8b092d..ab16e1dbd 100644 --- a/translations/ro/docs/TESTING.md +++ b/translations/ro/docs/TESTING.md @@ -2,19 +2,19 @@ ## Cuprins -- [Început rapid](../../../docs) -- [Ce acoperă testele](../../../docs) -- [Rularea testelor](../../../docs) -- [Rularea testelor în VS Code](../../../docs) -- [Modele de testare](../../../docs) -- [Filosofia testării](../../../docs) -- [Pașii următori](../../../docs) +- [Pornire rapidă](#pornire-rapidă) +- [Ce acoperă testele](#ce-acoperă-testele) +- [Executarea testelor](#executarea-testelor) +- [Executarea testelor în VS Code](#executarea-testelor-în-vs-code) +- [Modele de testare](#modele-de-testare) +- [Filosofia testării](#filosofia-testării) +- [Pașii următori](#pașii-următori) -Acest ghid te parcurge prin testele care demonstrează cum să testezi aplicații AI fără a necesita chei API sau servicii externe. +Acest ghid te conduce prin testele care demonstrează cum să testezi aplicații AI fără a avea nevoie de chei API sau servicii externe. -## Început rapid +## Pornire rapidă -Rulează toate testele cu o singură comandă: +Execută toate testele cu o singură comandă: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Când toate testele trec, ar trebui să vezi un output ca în captura de ecran de mai jos — testele rulează fără niciun eșec. +Când toate testele trec, ar trebui să vezi un rezultat asemănător cu captura de ecran de mai jos — testele rulează fără niciun eșec. Successful Test Results -*Executarea testelor cu succes arătând toate testele trecute fără niciun eșec* +*Executarea cu succes a testelor arătând toate testele trecute fără eșecuri* ## Ce acoperă testele -Acest curs se concentrează pe **teste unitare** care rulează local. Fiecare test demonstrează un concept specific LangChain4j izolat. Piramida de testare de mai jos arată unde se înscriu testele unitare — ele formează fundația rapidă și de încredere pe care se construiește restul strategiei tale de testare. +Acest curs se concentrează pe **teste unitare** care rulează local. Fiecare test demonstrează un concept specific LangChain4j în izolare. Piramida de testare de mai jos arată unde se încadrează testele unitare — ele formează fundația rapidă și fiabilă pe care se construiește restul strategiei tale de testare. Testing Pyramid -*Piramida de testare arătând echilibrul între testele unitare (rapide, izolate), testele de integrare (componente reale) și testele end-to-end. Această instruire acoperă testarea unitară.* +*Piramida de testare care arată echilibrul dintre testele unitare (rapide, izolate), testele de integrare (componente reale) și testele end-to-end. Acest antrenament acoperă testarea unitară.* -| Modul | Teste | Focalizare | Fișiere principale | +| Modul | Teste | Focalizare | Fișiere cheie | |--------|-------|-------|-----------| -| **00 - Început rapid** | 6 | Șabloane prompt și substituția variabilelor | `SimpleQuickStartTest.java` | -| **01 - Introducere** | 8 | Memorie conversație și chat cu stare | `SimpleConversationTest.java` | -| **02 - Ingineria prompturilor** | 12 | Modele GPT-5.2, niveluri de entuziasm, output structurat | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Ingestie documente, embedding-uri, căutare după similaritate | `DocumentServiceTest.java` | -| **04 - Unelte** | 12 | Apelarea funcțiilor și concatenarea uneltelor | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Protocol de context model cu transport Stdio | `SimpleMcpTest.java` | +| **01 - Introducere** | 8 | Memorie conversațională și chat cu stări | `SimpleConversationTest.java` | +| **02 - Inginerie Prompt** | 12 | Tipare GPT-5.2, nivele de entuziasm, output structurat | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Ingestie documente, embeddings, căutare după similaritate | `DocumentServiceTest.java` | +| **04 - Unelte** | 12 | Apelare funcții și înlănțuire unelte | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Protocolul Contextului Modelului cu transport stdio | `SimpleMcpTest.java` | -## Rularea testelor +## Executarea testelor -**Rulează toate testele de la rădăcină:** +**Execută toate testele din rădăcină:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Rulează testele pentru un modul specific:** +**Execută testele pentru un modul specific:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Rulează o singură clasă de test:** +**Execută o singură clasă de test:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Rulează o metodă de test specifică:** +**Execută o metodă de test specifică:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#ar trebui să mențină istoricul conversației +mvn test -Dtest=SimpleConversationTest#ar trebui să păstreze istoricul conversației ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#ar trebui să mențină istoricul conversației +mvn --% test -Dtest=SimpleConversationTest#ar trebui să păstreze istoricul conversației ``` -## Rularea testelor în VS Code +## Executarea testelor în VS Code Dacă folosești Visual Studio Code, Test Explorer oferă o interfață grafică pentru rularea și depanarea testelor. VS Code Test Explorer -*Test Explorer din VS Code arătând arborele testelor cu toate clasele de test Java și metodele individuale* +*Test Explorer din VS Code care arată arborele de test cu toate clasele de test Java și metodele de test individuale* **Pentru a rula testele în VS Code:** -1. Deschide Test Explorer făcând clic pe iconița cu eprubetă din bara de activități -2. Extinde arborele testelor pentru a vedea toate modulele și clasele de test -3. Fă clic pe butonul de redare de lângă orice test pentru a-l rula individual -4. Fă clic pe „Run All Tests” pentru a executa întreaga suită -5. Click dreapta pe orice test și selectează „Debug Test” pentru a seta breakpoint-uri și a parcurge codul +1. Deschide Test Explorer făcând clic pe pictograma eprubetei din Bara de activități +2. Extinde arborele de test pentru a vedea toate modulele și clasele de test +3. Fă clic pe butonul play de lângă orice test pentru a-l rula individual +4. Fă clic pe „Run All Tests” pentru a executa întregul set +5. Click dreapta pe orice test și selectează „Debug Test” pentru a seta puncte de întrerupere și a parcurge codul -Test Explorer arată bife verzi pentru testele trecute și oferă mesaje detaliate de eșec când testele nu trec. +Test Explorer afișează bifele verzi pentru testele care trec și oferă mesaje detaliate de eșec când testele pică. ## Modele de testare -### Model 1: Testarea șabloanelor prompt +### Model 1: Testarea șabloanelor de prompt -Cel mai simplu model testează șabloanele prompt fără a apela niciun model AI. Verifici că substituția variabilelor funcționează corect și prompturile sunt formatate conform așteptărilor. +Cel mai simplu model testează șabloanele de prompt fără a apela vreun model AI. Verifici că substituirea variabilelor funcționează corect și prompturile sunt formatate corect. Prompt Template Testing -*Testarea șabloanelor prompt arătând fluxul de substituție a variabilelor: șablon cu locuri de completat → valori aplicate → output formatat verificat* +*Testarea șabloanelor de prompt arătând fluxul de substituție a variabilelor: șablon cu locuri rezervate → valori aplicate → output formatat verificat* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Acest test se află în `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Acest model verifică că substituirea variabilelor funcționează corect și prompturile sunt formatate așa cum se așteaptă — nu este nevoie de cheie API sau apel la model. -**Rulează-l:** +### Model 2: Mocking modelelor de limbaj -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testareaFormatariiSablonuluiPrompt -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testareaFormatuluiTemplateuluiPrompt -``` - -### Model 2: Falsificarea modelelor de limbaj - -Când testezi logica conversației, folosește Mockito pentru a crea modele false care returnează răspunsuri prestabilite. Acest lucru face ca testele să fie rapide, gratuite și deterministe. +Când testezi logica conversației, folosește Mockito pentru a crea modele false care înapoiază răspunsuri prestabilite. Acest lucru face testele rapide, gratuite și deterministe. Mock vs Real API Comparison -*Comparație arătând de ce se preferă mocks pentru testare: sunt rapide, gratuite, deterministe și nu necesită chei API* +*Comparație care arată de ce mock-urile sunt preferate pentru testare: sunt rapide, gratuite, deterministe și nu necesită chei API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Acest model apare în `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock-ul asigură un comportament constant astfel încât să verifici că gestionarea memoriei funcționează corect. +Acest model apare în `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock-ul asigură un comportament consistent pentru a putea verifica corectitudinea gestionării memoriei. ### Model 3: Testarea izolării conversației -Memoria conversației trebuie să păstreze utilizatorii separați. Acest test verifică că conversațiile nu amestecă contexte. +Memoria conversațională trebuie să păstreze separația între mai mulți utilizatori. Acest test verifică că conversațiile nu amestecă contextul. Conversation Isolation -*Testarea izolării conversației arătând magazine de memorie separate pentru utilizatori diferiți, prevenind amestecul de contexte* +*Testarea izolării conversației care arată stocuri de memorie separate pentru diferiți utilizatori pentru a preveni amestecarea contextului* ```java @Test @@ -250,7 +237,7 @@ void shouldIsolateConversationsByid() { } ``` -Fiecare conversație își păstrează propriul istoric independent. În sistemele de producție, această izolare este critică pentru aplicațiile multi-utilizator. +Fiecare conversație își păstrează istoricul independent. În sistemele de producție, această izolare este critică pentru aplicațiile multi-utilizator. ### Model 4: Testarea uneltelor independent @@ -258,7 +245,7 @@ Uneltele sunt funcții pe care AI le poate apela. Testează-le direct pentru a t Tools Testing -*Testarea uneltelor independent arătând execuția uneltelor mock fără apeluri AI pentru a verifica logica de business* +*Testarea uneltelor independent arătând execuția unei unelte mock fără apeluri AI pentru a verifica logica de business* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Aceste teste din `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validează logica uneltelor fără implicarea AI. Exemplul cu concatenarea arată cum output-ul unei unelte alimentază input-ul alteia. +Aceste teste din `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validează logica uneltelor fără implicarea AI. Exemplul de înlănțuire arată cum output-ul unei unelte alimentează input-ul altei unelte. ### Model 5: Testarea RAG în memorie -Sistemele RAG necesită în mod tradițional baze de date vectoriale și servicii de embedding-uri. Modelul în memorie îți permite să testezi întregul pipeline fără dependențe externe. +Sistemele RAG necesită în mod tradițional baze de date vectoriale și servicii de embedding. Modelul în memorie îți permite să testezi întregul flux fără dependențe externe. In-Memory RAG Testing -*Fluxul de testare RAG în memorie arătând parsarea documentelor, stocarea embedding-urilor și căutarea după similaritate fără a necesita bază de date* +*Flux de testare RAG în memorie arătând procesarea documentelor, stocarea embedding-urilor și căutarea după similaritate fără a necesita o bază de date* ```java @Test @@ -306,11 +293,11 @@ void testProcessTextDocument() { } ``` -Acest test din `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` creează un document în memorie și verifică segmentarea și gestionarea metadata. +Acest test din `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` creează un document în memorie și verifică segmentarea și gestionarea metadatelor. ### Model 6: Testarea integrării MCP -Modulul MCP testează integrarea Protocolului Contextului Model folosind transportul stdio. Aceste teste verifică dacă aplicația ta poate genera și comunica cu servere MCP ca subprocese. +Modulul MCP testează integrarea Protocolului Contextului Modelului folosind transportul stdio. Aceste teste verifică că aplicația ta poate lansa și comunica cu servere MCP ca subprocese. Testele din `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validează comportamentul clientului MCP. @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## Filosofia testării -Testează codul tău, nu AI-ul. Testele tale ar trebui să valideze codul pe care îl scrii verificând cum sunt construite prompturile, cum este gestionată memoria și cum execută uneltele. Răspunsurile AI variază și nu ar trebui să facă parte din aserțiunile testelor. Întreabă-te dacă șablonul tău de prompt substituie corect variabilele, nu dacă AI oferă răspunsul corect. +Testează codul tău, nu AI-ul. Testele tale ar trebui să valideze codul scris, verificând cum sunt construite prompturile, cum este gestionată memoria și cum se execută uneltele. Răspunsurile AI variază și nu ar trebui să facă parte din aserțiunile testelor. Întreabă-te dacă șablonul promptului substituie corect variabilele, nu dacă AI oferă răspunsul corect. -Folosește mocks pentru modelele de limbaj. Sunt dependențe externe care sunt lente, costisitoare și nedeterministe. Falsificarea face testele rapide în milisecunde în loc de secunde, gratuite fără costuri API și deterministe cu același rezultat de fiecare dată. +Folosește mock-uri pentru modelele de limbaj. Sunt dependențe externe care sunt lente, costisitoare și nedeterministe. Mock-urile fac testele rapide, cu milisecunde în loc de secunde, gratuite fără costuri API și deterministe cu același rezultat de fiecare dată. -Păstrează testele independente. Fiecare test ar trebui să seteze propriile date, să nu se bazeze pe alte teste și să se curețe după sine. Testele ar trebui să treacă indiferent de ordinea execuției. +Păstrează testele independente. Fiecare test trebuie să-și configureze propriile date, să nu depindă de alte teste și să curețe după sine. Testele trebuie să treacă indiferent de ordinea de execuție. -Testează cazuri limită dincolo de calea fericită. Încearcă inputuri goale, inputuri foarte mari, caractere speciale, parametri invalizi și condiții limită. Acestea dezvăluie de multe ori bug-uri pe care utilizarea normală nu le expune. +Testează cazurile-limită dincolo de drumul fericit. Încearcă inputuri goale, inputuri foarte mari, caractere speciale, parametri invalizi și condiții de margine. Acestea dezvăluie adesea bug-uri pe care utilizarea normală nu le expune. -Folosește nume descriptive. Compară `shouldMaintainConversationHistoryAcrossMultipleMessages()` cu `test1()`. Primul îți spune exact ce se testează, făcând depanarea eșecurilor mult mai ușoară. +Folosește nume descriptive. Compară `shouldMaintainConversationHistoryAcrossMultipleMessages()` cu `test1()`. Primul îți spune exact ce se testează, făcând debugging-ul defecțiunilor mult mai ușor. ## Pașii următori Acum că înțelegi modelele de testare, aprofundează fiecare modul: -- **[00 - Început rapid](../00-quick-start/README.md)** - Începe cu bazele șabloanelor prompt -- **[01 - Introducere](../01-introduction/README.md)** - Învață gestionarea memoriei conversației -- **[02 - Ingineria prompturilor](../02/prompt-engineering/README.md)** - Stăpânește modelele de prompting GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Construiește sisteme de generare augmentată prin recuperare -- **[04 - Unelte](../04-tools/README.md)** - Implementează apelarea funcțiilor și lanțuri de unelte -- **[05 - MCP](../05-mcp/README.md)** - Integrează Protocolul Contextului Model +- **[01 - Introducere](../01-introduction/README.md)** - Învață gestionarea memoriei conversaționale +- **[02 - Inginerie Prompt](../02/prompt-engineering/README.md)** - Stăpânește tiparele de prompting GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Construiește sisteme de generare augmentată cu recuperare +- **[04 - Unelte](../04-tools/README.md)** - Implementează apelarea funcțiilor și lanțurile de unelte +- **[05 - MCP](../05-mcp/README.md)** - Integrează Protocolul Contextului Modelului -README-urile fiecărui modul oferă explicații detaliate ale conceptelor testate aici. +README-ul fiecărui modul oferă explicații detaliate ale conceptelor testate aici. --- @@ -358,6 +344,6 @@ README-urile fiecărui modul oferă explicații detaliate ale conceptelor testat --- -**Declinare de responsabilitate**: -Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original, în limba sa nativă, trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un specialist uman. Nu ne asumăm răspunderea pentru eventualele neînțelegeri sau interpretări greșite rezultate din utilizarea acestei traduceri. +**Declinare a responsabilității**: +Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri. \ No newline at end of file diff --git a/translations/ru/.co-op-translator.json b/translations/ru/.co-op-translator.json index 6f0dada97..dc16cffeb 100644 --- a/translations/ru/.co-op-translator.json +++ b/translations/ru/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ru" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T00:18:07+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T08:08:56+00:00", "source_file": "01-introduction/README.md", "language_code": "ru" }, @@ -18,20 +18,20 @@ "language_code": "ru" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T00:20:21+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T08:04:15+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ru" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T00:21:55+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T08:08:04+00:00", "source_file": "03-rag/README.md", "language_code": "ru" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T12:07:30+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T08:06:45+00:00", "source_file": "04-tools/README.md", "language_code": "ru" }, @@ -54,8 +54,8 @@ "language_code": "ru" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:55:51+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T08:02:49+00:00", "source_file": "README.md", "language_code": "ru" }, @@ -72,14 +72,14 @@ "language_code": "ru" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T00:25:01+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T08:04:51+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ru" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T00:25:49+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T08:05:32+00:00", "source_file": "docs/TESTING.md", "language_code": "ru" } diff --git a/translations/ru/00-quick-start/README.md b/translations/ru/00-quick-start/README.md deleted file mode 100644 index 47b72eb5b..000000000 --- a/translations/ru/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Модуль 00: Быстрый старт - -## Содержание - -- [Введение](../../../00-quick-start) -- [Что такое LangChain4j?](../../../00-quick-start) -- [Зависимости LangChain4j](../../../00-quick-start) -- [Требования](../../../00-quick-start) -- [Настройка](../../../00-quick-start) - - [1. Получите ваш токен GitHub](../../../00-quick-start) - - [2. Установите токен](../../../00-quick-start) -- [Запустите примеры](../../../00-quick-start) - - [1. Основной чат](../../../00-quick-start) - - [2. Шаблоны запросов](../../../00-quick-start) - - [3. Вызов функций](../../../00-quick-start) - - [4. Вопросы и ответы по документам (Easy RAG)](../../../00-quick-start) - - [5. Ответственный ИИ](../../../00-quick-start) -- [Что демонстрирует каждый пример](../../../00-quick-start) -- [Дальнейшие шаги](../../../00-quick-start) -- [Устранение неполадок](../../../00-quick-start) - -## Введение - -Этот быстрый старт предназначен для того, чтобы вы могли как можно быстрее начать работать с LangChain4j. Он охватывает самые основы создания AI-приложений с помощью LangChain4j и моделей GitHub. В следующих модулях вы переключитесь на Azure OpenAI и GPT-5.2 и углубитесь в каждый концепт. - -## Что такое LangChain4j? - -LangChain4j — это Java-библиотека, упрощающая создание приложений с искусственным интеллектом. Вместо работы с HTTP-клиентами и разбором JSON вы используете чистые Java API. - -«Chain» в LangChain означает цепочку компонентов — вы можете связать вместе запрос, модель и парсер, или связать несколько вызовов ИИ, где вывод одного становится входом для следующего. Этот быстрый старт сосредоточен на основах перед изучением более сложных цепочек. - -LangChain4j Chaining Concept - -*Компоненты в LangChain4j соединяются в цепочку — строительные блоки создают мощные AI-процессы* - -Мы используем три основных компонента: - -**ChatModel** — интерфейс для взаимодействия с AI-моделью. Вызываете `model.chat("prompt")` и получаете ответ в виде строки. Мы используем `OpenAiOfficialChatModel`, который работает с API, совместимыми с OpenAI, такими как модели GitHub. - -**AiServices** — создает типобезопасные интерфейсы AI-сервисов. Определяете методы, аннотируете их `@Tool`, и LangChain4j управляет оркестрацией. ИИ автоматически вызывает ваши Java-методы при необходимости. - -**MessageWindowChatMemory** — хранит историю разговора. Без него каждый запрос независим. С ним ИИ запоминает предыдущие сообщения и сохраняет контекст через несколько ходов. - -LangChain4j Architecture - -*Архитектура LangChain4j — основные компоненты работают вместе, чтобы запустить ваши AI-приложения* - -## Зависимости LangChain4j - -Этот быстрый старт использует три зависимости Maven в [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Модуль `langchain4j-open-ai-official` предоставляет класс `OpenAiOfficialChatModel`, который подключается к API, совместимым с OpenAI. Модели GitHub используют тот же формат API, поэтому специальный адаптер не нужен — просто укажите базовый URL `https://models.github.ai/inference`. - -Модуль `langchain4j-easy-rag` обеспечивает автоматическое разделение документов, создание векторных представлений и поиск, чтобы вы могли создавать RAG-приложения без ручной настройки каждого шага. - -## Требования - -**Используете Dev Container?** Java и Maven уже установлены. Вам нужен только персональный токен доступа GitHub. - -**Локальная разработка:** -- Java 21+, Maven 3.9+ -- Персональный токен доступа GitHub (инструкции ниже) - -> **Примечание:** Этот модуль использует модель `gpt-4.1-nano` из моделей GitHub. Не изменяйте имя модели в коде — оно настроено для работы с доступными моделями GitHub. - -## Настройка - -### 1. Получите ваш токен GitHub - -1. Перейдите в [Настройки GitHub → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Нажмите «Generate new token» -3. Задайте описательное имя (например, «LangChain4j Demo») -4. Установите срок действия (рекомендуется 7 дней) -5. В разделе «Account permissions» найдите «Models» и установите «Read-only» -6. Нажмите «Generate token» -7. Скопируйте и сохраните токен — его больше не покажут - -### 2. Установите токен - -**Вариант 1: Использование VS Code (рекомендуется)** - -Если вы используете VS Code, добавьте токен в файл `.env` в корне проекта: - -Если файл `.env` отсутствует, скопируйте `.env.example` в `.env` или создайте новый файл `.env` в корне проекта. - -**Пример файла `.env`:** -```bash -# В /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Затем просто кликните правой кнопкой по любому демо-файлу (например, `BasicChatDemo.java`) в Проводнике и выберите **«Run Java»** или используйте конфигурации запуска из панели Run and Debug. - -**Вариант 2: Использование терминала** - -Установите переменную окружения с токеном: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Запуск примеров - -**Использование VS Code:** Просто кликните правой кнопкой по любому демо-файлу в Проводнике и выберите **«Run Java»**, либо используйте конфигурации запуска из панели Run and Debug (предварительно добавьте токен в `.env`). - -**Использование Maven:** Или запустите из командной строки: - -### 1. Основной чат - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Шаблоны запросов - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Демонстрирует нулевой-shot, few-shot, chain-of-thought и ролевой подходы к запросам. - -### 3. Вызов функций - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -ИИ автоматически вызывает ваши Java-методы при необходимости. - -### 4. Вопросы и ответы по документам (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Задавайте вопросы по вашим документам с помощью Easy RAG с автоматическим созданием векторных представлений и поиском. - -### 5. Ответственный ИИ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Увидьте, как фильтры безопасности ИИ блокируют вредоносный контент. - -## Что демонстрирует каждый пример - -**Основной чат** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Начните здесь, чтобы увидеть LangChain4j в самом простом виде. Вы создадите `OpenAiOfficialChatModel`, отправите запрос через `.chat()` и получите ответ. Это демонстрирует основу: как инициализировать модели с помощью пользовательских конечных точек и API-ключей. Поняв этот шаблон, вы сможете строить всё остальное на его базе. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) и спросите: -> - «Как переключиться с моделей GitHub на Azure OpenAI в этом коде?» -> - «Какие другие параметры я могу настроить в OpenAiOfficialChatModel.builder()?» -> - «Как добавить потоковые ответы вместо ожидания полного ответа?» - -**Инжиниринг запросов** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Теперь, когда вы знаете, как общаться с моделью, давайте изучим, что вы ей говорите. В этом демо используется та же настройка модели, но показаны пять различных паттернов запросов. Попробуйте нулевой-shot для прямых инструкций, few-shot — когда модель обучается на примерах, chain-of-thought — для вывода промежуточных рассуждений, и ролевой подход — для заданного контекста. Вы увидите, как один и тот же модель даёт кардинально разные результаты в зависимости от формулировки запроса. - -Демо также демонстрирует шаблоны запросов, мощный способ создавать переиспользуемые запросы с переменными. -Ниже пример использования `PromptTemplate` LangChain4j для подстановки переменных. ИИ отвечает, основываясь на указанном пункте назначения и активности. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) и спросите: -> - «В чем разница между нулевым-shot и few-shot запросами и когда использовать каждый?» -> - «Как параметр температуры влияет на ответы модели?» -> - «Какие техники помогают предотвратить атаки с внедрением запросов в продакшене?» -> - «Как создавать переиспользуемые объекты PromptTemplate для распространённых паттернов?» - -**Интеграция инструментов** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Вот где LangChain4j становится мощным. Вы используете `AiServices` для создания помощника на базе ИИ, который может вызывать ваши Java-методы. Просто аннотируйте методы `@Tool("описание")`, и LangChain4j выполнит остальное — ИИ сам решает, когда использовать каждый инструмент, исходя из запроса пользователя. Это демонстрирует вызов функций, ключевой приём создания ИИ, который может совершать действия, а не только отвечать на вопросы. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) и спросите: -> - «Как работает аннотация @Tool и что LangChain4j с ней делает?» -> - «Может ли ИИ вызывать несколько инструментов подряд для решения сложных задач?» -> - «Что происходит, если инструмент выбрасывает исключение — как обрабатывать ошибки?» -> - «Как интегрировать реальное API вместо этого калькулятора?» - -**Вопросы и ответы по документам (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Здесь вы увидите RAG (retrieval-augmented generation) с использованием подхода LangChain4j «Easy RAG». Документы загружаются, автоматически разбиваются на части и преобразуются в векторные представления, которые хранятся в оперативной памяти, затем компонент поиска подаёт AI релевантные фрагменты при запросе. ИИ отвечает на основе ваших документов, а не общей обучающей информации. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) и спросите: -> - «Как RAG предотвращает галлюцинации ИИ по сравнению с использованием обучающих данных модели?» -> - «В чем разница между этим простым подходом и кастомной RAG-конвейером?» -> - «Как масштабировать это для обработки нескольких документов или больших баз знаний?» - -**Ответственный ИИ** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Создавайте безопасность ИИ с многоуровневой защитой. В этом демо показано, как работают вместе два уровня защиты: - -**Часть 1: LangChain4j Input Guardrails** — блокируют опасные запросы до того, как они попадут в LLM. Создавайте свои собственные guardrails, проверяющие запрещённые ключевые слова или паттерны. Они работают в вашем коде, так что быстро и бесплатно. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Часть 2: Фильтры безопасности поставщика** — у моделей GitHub встроены фильтры, которые ловят то, что могут пропустить ваши guardrails. Вы увидите жёсткие блокировки (ошибки HTTP 400) при серьезных нарушениях и мягкие отказы, когда ИИ вежливо отказывается. - -> **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) и спросите: -> - «Что такое InputGuardrail и как создать свой?» -> - «В чем разница между жёсткой блокировкой и мягким отказом?» -> - «Зачем использовать вместе guardrails и фильтры поставщика?» - -## Дальнейшие шаги - -**Следующий модуль:** [01-introduction - Начало работы с LangChain4j](../01-introduction/README.md) - ---- - -**Навигация:** [← Назад к основному](../README.md) | [Далее: Модуль 01 - Введение →](../01-introduction/README.md) - ---- - -## Устранение неполадок - -### Первый запуск сборки Maven - -**Проблема:** Первый запуск `mvn clean compile` или `mvn package` занимает много времени (10–15 минут) - -**Причина:** Maven должен скачать все зависимости проекта (Spring Boot, библиотеки LangChain4j, Azure SDK и т.д.) при первой сборке. - -**Решение:** Это нормальное поведение. Последующие сборки будут намного быстрее, так как зависимости уже будут кэшированы локально. Время загрузки зависит от скорости вашего интернета. - -### Синтаксис команд Maven в PowerShell - -**Проблема:** Команды Maven завершаются ошибкой `Unknown lifecycle phase ".mainClass=..."` -**Причина**: PowerShell интерпретирует `=` как оператор присваивания переменной, что нарушает синтаксис свойства Maven - -**Решение**: Используйте оператор остановки разбора `--%` перед командой Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Оператор `--%` сообщает PowerShell передавать все последующие аргументы буквально Maven без интерпретации. - -### Отображение эмодзи в Windows PowerShell - -**Проблема**: В ответах ИИ вместо эмодзи отображаются мусорные символы (например, `????` или `â??`) в PowerShell - -**Причина**: Кодировка по умолчанию PowerShell не поддерживает UTF-8 эмодзи - -**Решение**: Выполните эту команду перед запуском Java-приложений: -```cmd -chcp 65001 -``` - -Это принудительно включает кодировку UTF-8 в терминале. Альтернативно используйте Windows Terminal, который лучше поддерживает Unicode. - -### Отладка вызовов API - -**Проблема**: Ошибки аутентификации, ограничения по частоте запросов или неожиданные ответы от модели ИИ - -**Решение**: В примерах используются `.logRequests(true)` и `.logResponses(true)` для отображения вызовов API в консоли. Это помогает выявлять ошибки аутентификации, ограничения по частоте запросов или неожиданные ответы. Уберите эти флаги в продуктивной среде, чтобы уменьшить количество записей в логе. - ---- - - -**Отказ от ответственности**: -Этот документ был переведен с помощью ИИ-сервиса перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на то, что мы стремимся к точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его родном языке следует считать авторитетным источником. Для критически важной информации рекомендуется профессиональный перевод человеком. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования данного перевода. - \ No newline at end of file diff --git a/translations/ru/01-introduction/README.md b/translations/ru/01-introduction/README.md index a2b06021b..7cbf5506b 100644 --- a/translations/ru/01-introduction/README.md +++ b/translations/ru/01-introduction/README.md @@ -2,37 +2,37 @@ ## Содержание -- [Видеообзор](../../../01-introduction) -- [Чему вы научитесь](../../../01-introduction) -- [Требования](../../../01-introduction) -- [Понимание основной задачи](../../../01-introduction) -- [Понимание токенов](../../../01-introduction) -- [Как работает память](../../../01-introduction) -- [Как это использует LangChain4j](../../../01-introduction) -- [Развертывание инфраструктуры Azure OpenAI](../../../01-introduction) -- [Запуск приложения локально](../../../01-introduction) -- [Использование приложения](../../../01-introduction) - - [Бесконтекстный чат (левая панель)](../../../01-introduction) - - [Контекстный чат (правая панель)](../../../01-introduction) -- [Следующие шаги](../../../01-introduction) +- [Видеообзор](#видеообзор) +- [Чему вы научитесь](#чему-вы-научитесь) +- [Требования](#требования) +- [Понимание основной проблемы](#понимание-основной-проблемы) +- [Понимание токенов](#понимание-токенов) +- [Как работает память](#как-работает-память) +- [Как это использует LangChain4j](#как-это-использует-langchain4j) +- [Развертывание инфраструктуры Azure OpenAI](#развертывание-инфраструктуры-azure-openai) +- [Запуск приложения локально](#запуск-приложения-локально) +- [Использование приложения](#использование-приложения) + - [Бессостояный чат (левая панель)](#бессостояный-чат-левая-панель) + - [Состояный чат (правая панель)](#состояный-чат-правая-панель) +- [Следующие шаги](#следующие-шаги) ## Видеообзор -Смотрите эту прямую трансляцию, в которой объясняется, как начать работу с этим модулем: +Смотрите эту живую сессию, которая объясняет, как начать работу с этим модулем: -Начало работы с LangChain4j — прямая сессия +Начало работы с LangChain4j - Живая сессия ## Чему вы научитесь -В быстром старте вы использовали GitHub Models для отправки запросов, вызова инструментов, построения RAG пайплайна и тестирования ограничений. Те демонстрации показали, что возможно — теперь мы переключаемся на Azure OpenAI и GPT-5.2 и начинаем строить приложения промышленного уровня. Этот модуль фокусируется на разговорном ИИ, который запоминает контекст и поддерживает состояние — концепции, которые использовались в демонстрациях быстрого старта, но не были объяснены. +Это ваша отправная точка с LangChain4j и Azure OpenAI. Мы начинаем с основ и приступаем к созданию приложений производственного уровня. Этот модуль сосредоточен на разговорном ИИ, который запоминает контекст и сохраняет состояние — базовых концепциях, на которых строятся все последующие модули. -Мы будем использовать GPT-5.2 на Azure OpenAI на протяжении всего руководства, поскольку его продвинутые возможности рассуждений делают поведение разных паттернов более очевидным. Когда вы добавите память, разница будет особенно заметна. Это облегчает понимание того, что вносит каждый компонент в ваше приложение. +Мы будем использовать GPT-5.2 от Azure OpenAI на протяжении всего руководства, поскольку его расширенные возможности рассуждения делают поведение различных паттернов более очевидным. Когда вы добавляете память, вы чётко увидите разницу. Это облегчает понимание того, что каждый компонент приносит вашему приложению. -Вы создадите одно приложение, которое демонстрирует оба паттерна: +Вы создадите одно приложение, демонстрирующее оба паттерна: -**Бесконтекстный чат** — каждый запрос независим. Модель не помнит предыдущие сообщения. Это паттерн, который вы использовали в быстром старте. +**Бессостояный чат** — каждый запрос независим. У модели нет памяти о предыдущих сообщениях. Это самый простой старт. -**Контекстный разговор** — каждый запрос включает историю разговора. Модель поддерживает контекст на протяжении нескольких ходов. Это то, что требуется в производственных приложениях. +**Состояный разговор** — каждый запрос включает историю разговора. Модель поддерживает контекст в нескольких ходах. Это то, что требуется в производственных приложениях. ## Требования @@ -41,37 +41,37 @@ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Примечание:** Java, Maven, Azure CLI и Azure Developer CLI (azd) уже предустановлены в предоставленном devcontainer. +> **Примечание:** Java, Maven, Azure CLI и Azure Developer CLI (azd) предустановлены в предоставленном devcontainer. > **Примечание:** Этот модуль использует GPT-5.2 на Azure OpenAI. Развертывание настраивается автоматически через `azd up` — не изменяйте имя модели в коде. -## Понимание основной задачи +## Понимание основной проблемы -Языковые модели — бесконтекстны. Каждый вызов API независим. Если вы отправите "Меня зовут Джон", а затем спросите "Как меня зовут?", модель не знает, что вы только что представились. Она обрабатывает каждый запрос так, как будто это первый в вашей жизни разговор. +Языковые модели — бессостояны. Каждый вызов API независим. Если вы отправите "Меня зовут Джон", а потом спросите "Как меня зовут?", модель не понимает, что вы только что представились. Она воспринимает каждый запрос, как первый разговор. -Это подходит для простых вопросов-ответов, но бесполезно для реальных приложений. Боты службы поддержки должны помнить, что вы им сказали. Личные ассистенты нуждаются в контексте. Любой разговор с несколькими ходами требует памяти. +Это приемлемо для простых вопросов и ответов, но бесполезно для реальных приложений. Чат-боты поддержки клиентов должны запоминать, что вы им сказали. Личные помощники нуждаются в контексте. Любой многоходовой разговор требует памяти. -Следующая диаграмма сравнивает два подхода — слева бесконтекстный вызов, который забывает ваше имя; справа — контекстный вызов с ChatMemory, который его запоминает. +Следующая диаграмма показывает контраст двух подходов — слева бессостояный вызов, который забывает ваше имя; справа — состояный вызов с ChatMemory, который его запоминает. -Бесконтекстные и контекстные разговоры +Бессостояные vs Состояные разговоры -*Разница между бесконтекстными (независимыми вызовами) и контекстными (с учётом контекста) разговорами* +*Разница между бессостояными (независимыми) и состояными (учитывающими контекст) разговорами* ## Понимание токенов -Перед тем как погрузиться в разговоры, важно понять токены — базовые единицы текста, которые обрабатывают языковые модели: +Прежде чем углубляться в разговоры, важно понять токены — базовые единицы текста, которые обрабатывают языковые модели: -Объяснение токена +Объяснение токенов -*Пример того, как текст разбивается на токены — "I love AI!" становится 4 отдельными единицами обработки* +*Пример того, как текст разбивается на токены — "Я люблю ИИ!" превращается в 4 отдельных единицы обработки* -Токены — это способ, которым модели ИИ измеряют и обрабатывают текст. Слова, знаки препинания и даже пробелы могут быть токенами. Ваша модель имеет ограничение на количество токенов, которые она может обработать за один раз (400,000 для GPT-5.2, с максимум 272,000 входных токенов и 128,000 выходных). Понимание токенов помогает управлять длиной разговора и затратами. +Токены — это то, как модели ИИ измеряют и обрабатывают текст. Слово, пунктуация и даже пробелы могут быть токенами. У вашей модели есть ограничение на количество токенов, которые она может обрабатывать одновременно (400,000 для GPT-5.2, с максимум 272,000 входных токенов и 128,000 выходных). Понимание токенов помогает управлять длиной разговора и расходами. ## Как работает память -Память чата решает проблему бесконтекстности, сохраняя историю разговора. Перед отправкой запроса модели, фреймворк добавляет релевантные предыдущие сообщения. Когда вы спрашиваете "Как меня зовут?", система на самом деле отправляет всю историю разговора, позволяя модели видеть, что вы ранее сказали "Меня зовут Джон." +Память чата решает проблему бессостояния, сохраняя историю разговора. Перед отправкой вашего запроса модели, фреймворк подставляет релевантные предыдущие сообщения. Когда вы спрашиваете "Как меня зовут?", система фактически отправляет всю историю разговора, позволяя модели увидеть, что вы ранее сказали "Меня зовут Джон." -LangChain4j предоставляет реализации памяти, которые делают это автоматически. Вы выбираете, сколько сообщений хранить, а фреймворк управляет окном контекста. Ниже показано, как MessageWindowChatMemory поддерживает скользящее окно последних сообщений. +LangChain4j предоставляет реализации памяти, которые делают это автоматически. Вы выбираете, сколько сообщений хранить, а фреймворк управляет контекстным окном. На диаграмме ниже показано, как MessageWindowChatMemory поддерживает скользящее окно из последних сообщений. Концепция окна памяти @@ -79,7 +79,7 @@ LangChain4j предоставляет реализации памяти, кот ## Как это использует LangChain4j -Этот модуль расширяет быстрый старт, интегрируя Spring Boot и добавляя память разговора. Вот как компоненты взаимодействуют: +Этот модуль интегрирует Spring Boot и добавляет память разговора. Вот как компоненты связаны между собой: **Зависимости** — добавьте две библиотеки LangChain4j: @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Билдер читает учетные данные из переменных окружения, установленных командой `azd up`. Установка `baseUrl` на ваш Azure endpoint заставляет клиент OpenAI работать с Azure OpenAI. +Билдер читает учётные данные из переменных окружения, установленных `azd up`. Установка `baseUrl` на ваш Azure endpoint позволяет клиенту OpenAI работать с Azure OpenAI. -**Память разговора** — отслеживайте историю чата с помощью MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Память разговора** — отслеживайте историю чата с MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,51 +124,51 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Создайте память с `withMaxMessages(10)`, чтобы хранить последние 10 сообщений. Добавляйте сообщения пользователя и ИИ с помощью типизированных обёрток: `UserMessage.from(text)` и `AiMessage.from(text)`. Получайте историю через `memory.messages()` и отправляйте ее модели. Сервис хранит отдельные экземпляры памяти для каждого ID разговора, позволяя нескольким пользователям общаться одновременно. +Создайте память с помощью `withMaxMessages(10)`, чтобы хранить последние 10 сообщений. Добавляйте сообщения пользователя и ИИ с помощью типизированных оболочек: `UserMessage.from(text)` и `AiMessage.from(text)`. Получайте историю с помощью `memory.messages()` и отправляйте её модели. Сервис хранит отдельные экземпляры памяти для каждого ID разговора, позволяя нескольким пользователям общаться одновременно. > **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) и спросите: -> - "Как MessageWindowChatMemory решает, какие сообщения удалять, когда окно полно?" -> - "Могу ли я реализовать собственное хранилище памяти, используя базу данных вместо памяти в ОЗУ?" -> - "Как добавить суммирование, чтобы сжимать старую историю разговора?" +> - "Как MessageWindowChatMemory решает, какие сообщения удалять, когда окно заполнено?" +> - "Могу ли я реализовать собственное хранилище памяти, используя базу данных вместо памяти в оперативной памяти?" +> - "Как бы я добавил суммирование для сжатия старой истории разговора?" -Бесконтекстный эндпоинт пропускает память полностью — просто `chatModel.chat(prompt)`, как в быстром старте. Контекстный эндпоинт добавляет сообщения в память, получает историю и включает этот контекст в каждый запрос. Одна и та же конфигурация модели, разные паттерны. +Точка доступа бессостояного чата полностью пропускает память — просто `chatModel.chat(prompt)`, как в быстром старте. Состояный endpoint добавляет сообщения в память, получает историю и включает этот контекст в каждый запрос. Конфигурация модели одинаковая, но разные паттерны. ## Развертывание инфраструктуры Azure OpenAI **Bash:** ```bash cd 01-introduction -azd up # Выберите подписку и расположение (рекомендуется eastus2) +azd up # Выберите подписку и регион (рекомендуется eastus2) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Выберите подписку и расположение (рекомендуется eastus2) +azd up # Выберите подписку и местоположение (рекомендуется eastus2) ``` -> **Примечание:** Если вы получите ошибку таймаута (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), просто выполните `azd up` снова. Ресурсы Azure могут все еще развертываться в фоновом режиме, и повторная попытка позволяет завершить развертывание, когда они достигнут конечного состояния. +> **Примечание:** Если вы столкнулись с ошибкой таймаута (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), просто выполните `azd up` ещё раз. Ресурсы Azure могут ещё развертываться в фоне, и повторная попытка позволит завершить развертывание, когда ресурсы достигнут конечного состояния. -Это сделает следующее: -1. Развернет ресурс Azure OpenAI с моделями GPT-5.2 и text-embedding-3-small -2. Автоматически создаст файл `.env` в корне проекта с учетными данными -3. Настроит все необходимые переменные окружения +Это выполнит: +1. Развертывание ресурса Azure OpenAI с моделями GPT-5.2 и text-embedding-3-small +2. Автоматическую генерацию файла `.env` в корне проекта с учётными данными +3. Настройку всех необходимых переменных окружения -**Проблемы с развертыванием?** Смотрите [README по инфраструктуре](infra/README.md) для подробного устранения неполадок, включая конфликты поддоменных имен, шаги ручного развертывания в Azure Portal и руководство по настройке моделей. +**Проблемы с развертыванием?** См. [README по инфраструктуре](infra/README.md) для подробного устранения неполадок, включая конфликты имени поддомена, ручные шаги развертывания в Azure Portal и рекомендации по настройке моделей. -**Проверьте успешность развертывания:** +**Проверка успешности развертывания:** **Bash:** ```bash -cat ../.env # Должен показывать AZURE_OPENAI_ENDPOINT, API_KEY и т. д. +cat ../.env # Должен показывать AZURE_OPENAI_ENDPOINT, API_KEY и т.д. ``` **PowerShell:** ```powershell -Get-Content ..\.env # Должно показывать AZURE_OPENAI_ENDPOINT, API_KEY и т.д. +Get-Content ..\.env # Должен показать AZURE_OPENAI_ENDPOINT, API_KEY и т.д. ``` -> **Примечание:** Команда `azd up` автоматически генерирует файл `.env`. Если нужно обновить его позднее, вы можете либо отредактировать `.env` вручную, либо сгенерировать заново, выполнив: +> **Примечание:** Команда `azd up` автоматически генерирует файл `.env`. Если потребуется обновить его позже, вы можете либо вручную отредактировать `.env`, либо пересоздать его, выполнив: > > **Bash:** > ```bash @@ -182,12 +182,11 @@ Get-Content ..\.env # Должно показывать AZURE_OPENAI_ENDPOINT, > .\.azd-env.ps1 > ``` - ## Запуск приложения локально **Проверьте развертывание:** -Убедитесь, что файл `.env` существует в корне с учетными данными Azure. Запускайте из каталога модуля (`01-introduction/`): +Убедитесь, что файл `.env` существует в корне с вашими учётными данными Azure. Выполните это из директории модуля (`01-introduction/`): **Bash:** ```bash @@ -196,28 +195,28 @@ cat ../.env # Должен показывать AZURE_OPENAI_ENDPOINT, API_KEY, **PowerShell:** ```powershell -Get-Content ..\.env # Должно показать AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Должно показывать AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Запуск приложений:** +**Запустите приложения:** -**Вариант 1: Использование Spring Boot Dashboard (Рекомендуется для пользователей VS Code)** +**Вариант 1: Использование Spring Boot Dashboard (рекомендуется для пользователей VS Code)** -Dev container включает расширение Spring Boot Dashboard, которое предоставляет визуальный интерфейс для управления всеми приложениями Spring Boot. Найдите его на панели активностей слева в VS Code (значок Spring Boot). +Dev контейнер включает расширение Spring Boot Dashboard, которое предоставляет визуальный интерфейс для управления всеми приложениями Spring Boot. Вы найдете его в панели активности слева в VS Code (иконка Spring Boot). -С помощью Spring Boot Dashboard вы можете: -- Видеть все доступные приложения Spring Boot в рабочей области -- Запускать и останавливать приложения одним кликом -- Смотреть логи приложений в реальном времени -- Отслеживать состояние приложений +Через Spring Boot Dashboard вы можете: +- Видеть все доступные приложения Spring Boot в рабочем пространстве +- Запускать/останавливать приложения одним кликом +- Просматривать логи приложений в реальном времени +- Мониторить статус приложений -Просто нажмите кнопку запуска рядом с "introduction", чтобы стартовать этот модуль, или запустите все модули одновременно. +Просто нажмите кнопку воспроизведения рядом с "introduction", чтобы запустить этот модуль, или запустите все модули сразу. Панель управления Spring Boot -*Панель управления Spring Boot в VS Code — запуск, остановка и мониторинг всех модулей в одном месте* +*Панель управления Spring Boot в VS Code — запуск, остановка и мониторинг всех модулей из одного места* -**Вариант 2: С помощью shell скриптов** +**Вариант 2: Использование shell скриптов** Запустите все веб-приложения (модули 01-04): @@ -233,7 +232,7 @@ cd .. # Из корневого каталога .\start-all.ps1 ``` -Или запустите только этот модуль: +Или только этот модуль: **Bash:** ```bash @@ -247,7 +246,7 @@ cd 01-introduction .\start.ps1 ``` -Оба скрипта автоматически загружают переменные окружения из корневого файла `.env` и соберут JAR-файлы, если их нет. +Оба скрипта автоматически загружают переменные окружения из корневого файла `.env` и соберут JAR, если он отсутствует. > **Примечание:** Если хотите собрать все модули вручную перед запуском: > @@ -263,10 +262,9 @@ cd 01-introduction > mvn clean package -DskipTests > ``` +Откройте в браузере http://localhost:8080. -Откройте http://localhost:8080 в вашем браузере. - -**Для остановки:** +**Чтобы остановить:** **Bash:** ```bash @@ -282,44 +280,43 @@ cd .. && ./stop-all.sh # Все модули cd ..; .\stop-all.ps1 # Все модули ``` - ## Использование приложения -Приложение предоставляет веб-интерфейс с двумя реализациями чата, расположенными рядом. +Приложение предоставляет веб-интерфейс с двумя реализациями чатов бок о бок. Главный экран приложения -*Панель с вариантами Простого чата (бесконтекстный) и Разговорного чата (контекстный)* +*Панель выбора между Простым чатом (бессостояный) и Разговорным чатом (состояный)* -### Бесконтекстный чат (левая панель) +### Бессостояный чат (левая панель) -Попробуйте начать здесь. Скажите "Меня зовут Джон", а затем сразу спросите "Как меня зовут?" Модель не запомнит, потому что каждое сообщение обрабатывается независимо. Это демонстрирует основную проблему простого интегрирования языковой модели — отсутствует контекст разговора. +Попробуйте сначала здесь. Скажите "Меня зовут Джон", а затем сразу спросите "Как меня зовут?" Модель не запомнит, так как каждое сообщение независимо. Это демонстрирует основную проблему базовой интеграции языковой модели — отсутствие контекста разговора. -Демонстрация бесконтекстного чата +Демонстрация бессостояного чата *ИИ не помнит ваше имя из предыдущего сообщения* -### Контекстный чат (правая панель) +### Состояный чат (правая панель) -Теперь попробуйте ту же последовательность здесь. Скажите "Меня зовут Джон", затем "Как меня зовут?" В этот раз модель запомнила. Разница в MessageWindowChatMemory — он сохраняет историю разговора и включает её в каждый запрос. Именно так работают производственные разговорные ИИ. +Теперь попробуйте ту же последовательность здесь. Скажите "Меня зовут Джон", затем "Как меня зовут?" На этот раз ИИ запомнит. Разница в MessageWindowChatMemory — он поддерживает историю разговора и включает её в каждый запрос. Вот как работает производственный разговорный ИИ. -Демонстрация контекстного чата +Демонстрация состояного чата -*ИИ помнит ваше имя из более раннего разговора* +*ИИ помнит ваше имя из начала разговора* -Обе панели используют одну и ту же модель GPT-5.2. Единственное отличие — память. Это ясно показывает, что память даёт вашему приложению и почему она необходима для реальных сценариев. +Обе панели используют одну и ту же модель GPT-5.2. Единственная разница — память. Это понятно показывает, что даёт память вашему приложению и почему она необходима для реальных случаев. ## Следующие шаги -**Следующий модуль:** [02-prompt-engineering - Инжиниринг подсказок с GPT-5.2](../02-prompt-engineering/README.md) +**Следующий модуль:** [02-prompt-engineering - Создание подсказок с GPT-5.2](../02-prompt-engineering/README.md) --- -**Навигация:** [← Предыдущий: Модуль 00 - Быстрый старт](../00-quick-start/README.md) | [Назад к главной](../README.md) | [Следующий: Модуль 02 - Инжиниринг подсказок →](../02-prompt-engineering/README.md) +**Навигация:** [← Назад к Главной](../README.md) | [Вперёд: Модуль 02 - Создание подсказок →](../02-prompt-engineering/README.md) --- -**Отказ от ответственности**: -Данный документ был переведен с помощью сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия обеспечить точность, просим учитывать, что автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется воспользоваться услугами профессионального перевода человеком. Мы не несем ответственности за любые недоразумения или искажения смысла, возникшие в результате использования данного перевода. +**Отказ от ответственности**: +Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода. \ No newline at end of file diff --git a/translations/ru/02-prompt-engineering/README.md b/translations/ru/02-prompt-engineering/README.md index cad7605e2..4da36c7df 100644 --- a/translations/ru/02-prompt-engineering/README.md +++ b/translations/ru/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Модуль 02: Проектирование запросов с GPT-5.2 - -## Содержание - -- [Видеообзор](../../../02-prompt-engineering) -- [Чему вы научитесь](../../../02-prompt-engineering) -- [Требования](../../../02-prompt-engineering) -- [Понимание проектирования запросов](../../../02-prompt-engineering) -- [Основы проектирования запросов](../../../02-prompt-engineering) - - [Zero-Shot Запросы](../../../02-prompt-engineering) - - [Few-Shot Запросы](../../../02-prompt-engineering) - - [Цепочка рассуждений](../../../02-prompt-engineering) - - [Запросы на основе ролей](../../../02-prompt-engineering) - - [Шаблоны запросов](../../../02-prompt-engineering) -- [Продвинутые шаблоны](../../../02-prompt-engineering) -- [Запуск приложения](../../../02-prompt-engineering) -- [Скриншоты приложения](../../../02-prompt-engineering) -- [Изучение шаблонов](../../../02-prompt-engineering) - - [Низкий и высокий уровень усердия](../../../02-prompt-engineering) - - [Выполнение задач (вступления к инструментам)](../../../02-prompt-engineering) - - [Саморефлексирующий код](../../../02-prompt-engineering) - - [Структурированный анализ](../../../02-prompt-engineering) - - [Многошаговый чат](../../../02-prompt-engineering) - - [Пошаговое рассуждение](../../../02-prompt-engineering) - - [Ограниченный вывод](../../../02-prompt-engineering) -- [Что вы действительно изучаете](../../../02-prompt-engineering) -- [Следующие шаги](../../../02-prompt-engineering) - -## Видеообзор - -Посмотрите эту живую сессию, которая объясняет, как начать работу с этим модулем: +# Модуль 02: Проектирование подсказок с GPT-5.2 + +## Оглавление + +- [Пошаговое видео](#пошаговое-видео) +- [Чему вы научитесь](#чему-вы-научитесь) +- [Требования](#требования) +- [Понимание проектирования подсказок](#понимание-проектирования-подсказок) +- [Основы проектирования подсказок](#основы-проектирования-подсказок) + - [Подсказки без примеров (Zero-Shot)](#подсказки-без-примеров-zero-shot) + - [Подсказки с примерами (Few-Shot)](#подсказки-с-примерами-few-shot) + - [Цепочка рассуждений](#цепочка-рассуждений) + - [Ролевая формулировка](#ролевая-формулировка) + - [Шаблоны подсказок](#шаблоны-подсказок) +- [Продвинутые паттерны](#продвинутые-паттерны) +- [Запуск приложения](#запуск-приложения) +- [Скриншоты приложения](#скриншоты-приложения) +- [Изучение паттернов](#изучение-шаблонов) + - [Низкая и высокая активность](#низкая-vs-высокая-активность-мышления) + - [Выполнение задач (Вводные тексты для инструментов)](#выполнение-задач-инструкции-по-инструментам) + - [Саморефлектирующий код](#саморефлексирующий-код) + - [Структурированный анализ](#структурированный-анализ) + - [Многоходовой чат](#многошаговый-чат) + - [Пошаговые рассуждения](#поэтапное-рассуждение) + - [Ограниченный вывод](#ограниченный-вывод) +- [Чему вы действительно учитесь](#чему-вы-на-самом-деле-учитесь) +- [Следующие шаги](#следующие-шаги) + +## Пошаговое видео + +Посмотрите эту сессию вживую, где объясняется, как начать работу с этим модулем: Prompt Engineering with LangChain4j - Live Session ## Чему вы научитесь -Следующая диаграмма даёт обзор ключевых тем и навыков, которые вы освоите в этом модуле — от методик уточнения запросов до пошагового рабочего процесса, который вы будете использовать. +Следующая диаграмма предоставляет обзор ключевых тем и навыков, которые вы освоите в этом модуле — от методов уточнения подсказок до пошагового рабочего процесса, который вы будете использовать. -What You'll Learn +Что вы изучите -В предыдущих модулях вы изучали базовые взаимодействия LangChain4j с GitHub Models и увидели, как память обеспечивает диалоговый ИИ с помощью Azure OpenAI. Теперь мы сосредоточимся на том, как вы задаёте вопросы — на самих запросах — используя GPT-5.2 от Azure OpenAI. Способ структурирования запросов значительно влияет на качество получаемых ответов. Мы начнем с обзора основных техник проектирования запросов, затем перейдём к восьми продвинутым шаблонам, которые полностью используют возможности GPT-5.2. +В предыдущем модуле вы узнали, как память обеспечивает диалоговый ИИ на базе Azure OpenAI. Теперь мы сосредоточимся на том, как задавать вопросы — то есть на самих подсказках — используя GPT-5.2 от Azure OpenAI. То, как вы структурируете подсказки, существенно влияет на качество получаемых ответов. Начнем с обзора основных техник создания подсказок, а затем перейдем к восьми продвинутым паттернам, которые полностью используют возможности GPT-5.2. -Мы используем GPT-5.2, потому что он вводит контроль рассуждений — вы можете указать модели, сколько размышлений сделать перед ответом. Это делает различные стратегии запросов более очевидными и помогает понять, когда использовать каждый подход. Также мы получаем выгоду от меньших ограничений по скорости для GPT-5.2 в Azure по сравнению с GitHub Models. +Мы используем GPT-5.2, потому что он вводит управление рассуждениями — вы можете указать модели, сколько размышлять перед ответом. Это делает стратегии подсказок более очевидными и помогает понять, когда применять каждый из подходов. ## Требования -- Завершён модуль 01 (развёрнуты ресурсы Azure OpenAI) -- Файл `.env` в корневом каталоге с учётными данными Azure (созданный командой `azd up` в модуле 01) +- Завершенный Модуль 01 (развернуты ресурсы Azure OpenAI) +- Файл `.env` в корневой директории с учетными данными Azure (созданный с помощью `azd up` в Модуле 01) -> **Примечание:** Если вы не завершили модуль 01, сначала следуйте инструкциям по развертыванию там. +> **Примечание:** Если вы не завершили Модуль 01, сначала следуйте инструкциям по развертыванию в нем. -## Понимание проектирования запросов +## Понимание проектирования подсказок -В своей основе проектирование запросов — это разница между расплывчатыми и точными инструкциями, как показывает следующее сравнение. +В основе проектирования подсказок лежит разница между расплывчатыми и точными инструкциями, что иллюстрирует приведенное ниже сравнение. -What is Prompt Engineering? +Что такое проектирование подсказок? -Проектирование запросов — это создание входного текста, который последовательно даёт требуемый результат. Дело не только в задавании вопросов — это структура запросов так, чтобы модель точно понимала, чего вы хотите и как это предоставить. +Проектирование подсказок — это разработка входного текста, который последовательно дает нужные вам результаты. Это не просто вопросы — это структурирование запросов так, чтобы модель точно понимала, чего вы хотите и как это предоставить. -Представьте, что вы даёте инструкции коллеге. «Исправь баг» — неясная инструкция. «Исправь исключение null pointer в UserService.java на строке 45, добавив проверку на null» — конкретная. Языковые модели работают аналогично — важны конкретность и структура. +Представьте, что вы даете инструкции коллеге. «Исправь ошибку» — это расплывчато. «Исправь ошибку null pointer exception в UserService.java на строке 45, добавив проверку на null» — конкретно. Языковые модели работают так же — важна точность и структура. -Диаграмма ниже показывает, как LangChain4j вписывается в эту цепочку — связывая ваши шаблоны запросов с моделью через строительные блоки SystemMessage и UserMessage. +Следующая диаграмма показывает, как LangChain4j вписывается в эту картину — связывая ваши шаблоны подсказок с моделью через строительные блоки SystemMessage и UserMessage. -How LangChain4j Fits +Как работает LangChain4j -LangChain4j предоставляет инфраструктуру — подключения к моделям, память и типы сообщений — а шаблоны запросов — это просто тщательно структурированный текст, который вы отправляете через эту инфраструктуру. Ключевые строительные блоки — это `SystemMessage` (задаёт поведение и роль ИИ) и `UserMessage` (несёт ваш фактический запрос). +LangChain4j предоставляет инфраструктуру — подключения к моделям, память и типы сообщений — а паттерны подсказок — это просто тщательно структурированный текст, который вы отправляете через эту инфраструктуру. Ключевые строительные блоки — это `SystemMessage` (которое задает поведение ИИ и роль) и `UserMessage` (которое несет ваш реальный запрос). -## Основы проектирования запросов +## Основы проектирования подсказок -Пять основных техник, показанных ниже, составляют основу эффективного проектирования запросов. Каждая из них охватывает разный аспект того, как вы коммуницируете с языковыми моделями. +Пять основных техник, показанных ниже, формируют основу эффективного проектирования подсказок. Каждая из них решает разные аспекты вашего взаимодействия с языковыми моделями. -Five Prompt Engineering Patterns Overview +Обзор пяти паттернов проектирования подсказок -Прежде чем углубляться в продвинутые шаблоны этого модуля, давайте рассмотрим пять фундаментальных техник запросов. Это строительные блоки, которые должен знать каждый инженер по запросам. Если вы уже прошли [модуль быстрого старта](../00-quick-start/README.md#2-prompt-patterns), вы видели их в действии — вот концептуальная основа. +Прежде чем перейти к продвинутым паттернам этого модуля, давайте вспомним пять основных техник создания подсказок. Это базовые строительные блоки, которые должен знать каждый разработчик подсказок. -### Zero-Shot Запросы +### Подсказки без примеров (Zero-Shot) -Самый простой подход: дать модели прямую инструкцию без примеров. Модель полностью опирается на своё обучение, чтобы понять и выполнить задачу. Хорошо работает для простых запросов, где ожидаемое поведение очевидно. +Самый простой подход: дать модели прямую инструкцию без примеров. Модель полностью опирается на свое обучение, чтобы понять и выполнить задачу. Хорошо работает для простых запросов, где ожидаемое поведение очевидно. -Zero-Shot Prompting +Подсказки без примеров -*Прямая инструкция без примеров — модель выводит задачу только из инструкции* +*Прямая инструкция без примеров — модель выводит задачу только по инструкции* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// Ответ: "Положительный" +// Ответ: "Положительно" ``` **Когда использовать:** Простая классификация, прямые вопросы, переводы или любые задачи, которые модель может выполнить без дополнительного руководства. -### Few-Shot Запросы +### Подсказки с примерами (Few-Shot) -Предоставьте примеры, демонстрирующие паттерн, который вы хотите, чтобы модель применила. Модель учится ожидаемому формату ввода-вывода из ваших примеров и применяет его к новым входам. Это значительно улучшает согласованность для задач, где нужный формат или поведение не очевидны. +Предоставьте примеры, которые демонстрируют паттерн, который модель должна повторять. Модель учится формату ввода-вывода по вашим примерам и применяет его к новым входным данным. Это значительно повышает согласованность для задач, где желаемый формат или поведение не очевидны. -Few-Shot Prompting +Подсказки с примерами -*Обучение на примерах — модель идентифицирует паттерн и применяет его к новым входам* +*Обучение на примерах — модель распознает паттерн и применяет его к новым данным* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Когда использовать:** Кастомные классификации, согласованное форматирование, задачи в определённой области, или когда результаты zero-shot нестабильны. +**Когда использовать:** Пользовательская классификация, согласованное форматирование, задачи в конкретной области или когда результаты zero-shot нестабильны. ### Цепочка рассуждений -Попросите модель показать рассуждения пошагово. Вместо того чтобы сразу дать ответ, модель разлагает проблему и прорабатывает каждый шаг явно. Это повышает точность в математике, логике и многозадачных рассуждениях. +Попросите модель показать свои рассуждения шаг за шагом. Вместо прямого ответа модель разлагает проблему и последовательно рассматривает каждый шаг. Это повышает точность при решении задач по математике, логике и многозадачному рассуждению. -Chain of Thought Prompting +Подсказки с цепочкой рассуждений -*Пошаговое рассуждение — разбор сложных задач на явные логические шаги* +*Пошаговое рассуждение — разбиение сложных задач на явные логические шаги* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Модель показывает: 15 - 8 = 7, затем 7 + 12 = 19 яблок ``` -**Когда использовать:** Математические задачи, логические головоломки, отладка или любые задачи, где показ рассуждений повышает точность и доверие. +**Когда использовать:** Математические задачи, логические головоломки, отладка или любые задачи, где показ процесса рассуждений повышает точность и доверие. -### Запросы на основе ролей +### Ролевая формулировка -Задайте персонажа или роль ИИ перед вашим вопросом. Это создаёт контекст, который формирует тон, глубину и фокус ответа. «Архитектор ПО» даст другой совет, чем «младший разработчик» или «аудитор безопасности». +Задайте персонаж или роль ИИ перед тем, как спросить. Это создает контекст, влияющий на тон, глубину и акцент ответа. «Архитектор ПО» даст другие советы, чем «младший разработчик» или «аудитор безопасности». -Role-Based Prompting +Ролевая формулировка -*Задание контекста и роли — один и тот же вопрос получает разный ответ в зависимости от роли* +*Задание контекста и роли — один и тот же вопрос получает разные ответы в зависимости от роли* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Когда использовать:** Код-ревью, обучение, специализированный анализ или когда нужны ответы, адаптированные под уровень экспертизы или перспективу. +**Когда использовать:** Ревью кода, обучение, анализ по конкретной области или когда нужны ответы, адаптированные под уровень экспертизы или точку зрения. -### Шаблоны запросов +### Шаблоны подсказок -Создайте переиспользуемые запросы с переменными-заполнителями. Вместо того, чтобы каждый раз писать новый запрос, определите шаблон один раз и подставляйте разные значения. Класс `PromptTemplate` в LangChain4j облегчает это с синтаксисом `{{variable}}`. +Создавайте повторно используемые подсказки с переменными-заполнителями. Вместо написания новой подсказки каждый раз, определите шаблон один раз и подставляйте разные значения. Класс `PromptTemplate` LangChain4j облегчает это с помощью синтаксиса `{{variable}}`. -Prompt Templates +Шаблоны подсказок -*Переиспользуемые запросы с переменными — один шаблон, много применений* +*Повторно используемые подсказки с переменными — один шаблон, много применений* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Когда использовать:** Повторяющиеся запросы с разными входами, пакетная обработка, построение переиспользуемых рабочих процессов ИИ или любые сценарии, где структура запроса постоянна, а данные меняются. +**Когда использовать:** Повторяющиеся запросы с разными входными данными, пакетная обработка, создание повторно используемых AI-рабочих процессов или в любом сценарии, где структура подсказки остается неизменной, а данные меняются. --- -Эти пять основ дают вам надёжный набор инструментов для большинства задач проектирования запросов. Остальная часть модуля строится на них с использованием **восьми продвинутых шаблонов**, которые используют контроль рассуждений GPT-5.2, самооценку и возможности структурированного вывода. +Эти пять основ обеспечивают вас надежным набором инструментов для большинства задач проектирования подсказок. Остальная часть этого модуля строится на них с помощью **восьми продвинутых паттернов**, которые используют управление рассуждениями, самооценку и возможности структурированного вывода GPT-5.2. -## Продвинутые шаблоны +## Продвинутые паттерны -После освоения основ перейдём к восьми продвинутым шаблонам, которые делают этот модуль уникальным. Не все задачи требуют одного и того же подхода. Некоторые вопросы требуют быстрых ответов, другие — глубокого анализа. Некоторые требуют видимых рассуждений, другие — только результатов. Каждый из шаблонов ниже оптимизирован для конкретного сценария — и контроль рассуждений GPT-5.2 делает эти различия ещё заметнее. +После базовых техник перейдем к восьми продвинутым паттернам, которые делают этот модуль уникальным. Не все задачи требуют одного и того же подхода. Некоторые вопросы требуют быстрых ответов, другие — глубокого осмысления. Некоторые требуют видимых рассуждений, другие — лишь результатов. Каждый паттерн оптимизирован под разные сценарии — а управление рассуждениями GPT-5.2 делает эти различия еще более очевидными. -Eight Prompting Patterns +Восемь паттернов подсказок -*Обзор восьми шаблонов проектирования запросов и их сценариев использования* +*Обзор восьми паттернов проектирования подсказок и их случаев использования* -GPT-5.2 добавляет ещё одно измерение в эти шаблоны: *контроль рассуждений*. Ползунок ниже показывает, как можно регулировать объём размышлений модели — от быстрых прямых ответов до глубокого тщательного анализа. +GPT-5.2 добавляет другое измерение этим паттернам: *управление рассуждениями*. Ползунок ниже показывает, как вы можете регулировать усилия мышления модели — от быстрых, прямых ответов до глубокого, тщательного анализа. -Reasoning Control with GPT-5.2 +Управление рассуждениями с GPT-5.2 -*Контроль рассуждений GPT-5.2 позволяет задавать, сколько размышлений должна сделать модель — от быстрых ответов до глубокого изучения* +*Управление рассуждениями GPT-5.2 позволяет указать, сколько размышлений должна делать модель — от быстрых прямых ответов до глубокого анализа* -**Низкий усердие (быстро и по делу)** — Для простых вопросов, когда нужны быстрые и точные ответы. Модель выполняет минимальные рассуждения — максимум 2 шага. Используйте для вычислений, поиска или прямых вопросов. +**Низкая активность (Быстро и по существу)** — для простых вопросов, где нужны быстрые прямые ответы. Модель делает минимум рассуждений — максимум 2 шага. Используйте для расчетов, запросов к справочнику или простых вопросов. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Исследуйте с GitHub Copilot:** Откройте [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) и спросите: -> - «В чём разница между шаблонами низкой и высокой усердия?» -> - «Как XML-теги в запросах помогают структурировать ответ ИИ?» -> - «Когда следует использовать шаблоны саморефлексии, а когда прямые инструкции?» +> 💡 **Используйте вместе с GitHub Copilot:** Откройте [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) и спросите: +> - «В чем разница между паттернами подсказок с низкой и высокой активностью?» +> - «Как XML-теги в подсказках помогают структурировать ответ ИИ?» +> - «Когда лучше использовать паттерны саморефлексии, а когда прямые инструкции?» -**Высокий усердие (глубоко и тщательно)** — Для сложных задач, когда нужен всесторонний анализ. Модель тщательно исследует и показывает подробные рассуждения. Используйте для проектирования систем, архитектурных решений или сложных исследований. +**Высокая активность (Глубоко и тщательно)** — для сложных проблем, требующих детального анализа. Модель исследует вопрос глубоко и показывает подробные рассуждения. Используйте для системного проектирования, архитектурных решений или комплексных исследований. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Выполнение задач (пошаговый прогресс)** — Для многошаговых рабочих процессов. Модель выстраивает план, описывает каждый шаг по мере выполнения, затем даёт итог. Используйте для миграций, внедрений или любых многошаговых процессов. +**Выполнение задачи (Пошаговый прогресс)** — для многоэтапных рабочих процессов. Модель сразу дает план, комментирует каждый шаг выполнения, затем подытоживает. Используйте для миграций, реализации или любого многошагового процесса. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Запросы с цепочкой рассуждений (Chain-of-Thought) явно просят модель показать процесс мышления, что повышает точность для сложных задач. Пошаговый разбор помогает как людям, так и ИИ понять логику. +Подсказки с цепочкой рассуждений явно просят модель показать процесс мышления, повышая точность для сложных задач. Пошаговое разбиение помогает и людям, и ИИ понять логику. -> **🤖 Попробуйте с чат-ботом [GitHub Copilot](https://github.com/features/copilot):** Спросите про этот шаблон: -> - «Как адаптировать шаблон выполнения задач для длительных операций?» -> - «Какие лучшие практики для структурирования вступительных сообщений инструментов в продуктивных приложениях?» -> - «Как захватывать и отображать промежуточные обновления прогресса в пользовательском интерфейсе?» +> **🤖 Попробуйте в чате [GitHub Copilot](https://github.com/features/copilot):** Спросите про этот паттерн: +> - «Как адаптировать паттерн выполнения задач для длительных операций?» +> - «Какие лучшие практики структурирования вводных текстов инструментов для продакшена?» +> - «Как записывать и отображать промежуточные обновления прогресса в UI?» -Диаграмма ниже иллюстрирует этот рабочий процесс План → Выполнение → Итог. +Следующая диаграмма иллюстрирует рабочий процесс План → Выполнение → Резюме. -Task Execution Pattern +Паттерн выполнения задачи -*Рабочий процесс План → Выполнение → Итог для многошаговых задач* +*Рабочий процесс План → Выполнение → Резюме для многошаговых задач* -**Саморефлексирующий код** — Для генерации кода производственного качества. Модель создаёт код с соблюдением стандартов продакшена с надлежащей обработкой ошибок. Используйте для построения новых функций или сервисов. +**Саморефлектирующий код** — для генерации кода производственного качества. Модель создает код согласно стандартам производства с правильной обработкой ошибок. Используйте при разработке новых функций или сервисов. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Диаграмма ниже показывает этот цикл итеративного улучшения — генерация, оценка, выявление недостатков и доработка до соответствия стандартам производства. +Диаграмма ниже показывает этот итеративный цикл улучшений — генерация, оценка, выявление слабых мест и доработка до соответствия стандартам. -Self-Reflection Cycle +Цикл саморефлексии -*Цикл итеративного улучшения — генерировать, оценивать, выявлять проблемы, улучшать, повторять* +*Итеративный цикл улучшений — генерация, оценка, выявление проблем, доработка, повтор* -**Структурированный анализ** — Для последовательной оценки. Модель оценивает код по фиксированной системе (правильность, практика, производительность, безопасность, сопровождаемость). Используйте для код-ревью или оценок качества. +**Структурированный анализ** — для последовательной оценки. Модель проверяет код по фиксированной схеме (корректность, практики, производительность, безопасность, поддерживаемость). Используйте для ревью кода или оценки качества. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Попробуйте с чат-ботом [GitHub Copilot](https://github.com/features/copilot):** Спросите про структурированный анализ: -> - «Как настроить систему анализа для разных типов код-ревью?» -> - «Как программно парсить и использовать структурированный вывод?» -> - «Как обеспечить единообразие уровней серьёзности в разных сессиях обзора?» +> **🤖 Попробуйте в чате [GitHub Copilot](https://github.com/features/copilot):** Спросите про структурированный анализ: +> - «Как настроить схему анализа для разных типов ревью кода?» +> - «Как лучше всего программно разбирать и использовать структурированный вывод?» +> - «Как обеспечить последовательность уровней серьезности в разных сессиях ревью?» -Следующая диаграмма показывает, как эта структурированная рамка организует код-ревью по категориям с уровнями серьёзности. +Следующая диаграмма показывает, как эта структурированная схема организует ревью кода по категориям с уровнями серьезности. -Structured Analysis Pattern +Паттерн структурированного анализа -*Рамка для последовательных код-ревью с уровнями серьёзности* +*Схема для последовательных ревью кода с уровнями серьезности* -**Многошаговый чат** — Для разговоров, требующих контекста. Модель запоминает предыдущие сообщения и строит на их основе. Используйте для интерактивных консультаций или сложных вопросов и ответов. +**Многоходовой чат** — для диалогов с контекстом. Модель запоминает предыдущие сообщения и строит ответы на их основе. Используйте для интерактивной помощи или сложных вопросов и ответов. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Диаграмма ниже визуализирует, как контекст разговора накапливается с каждым ходом и как это связано с ограничением по токенам модели. +Диаграмма ниже визуализирует, как накапливается контекст разговора с каждым ходом и как это связано с лимитом токенов модели. -Context Memory +Память контекста -*Как контекст разговора накапливается через множество ходов до достижения лимита токенов* -**Пошаговое рассуждение** — Для задач, требующих явной логики. Модель показывает явное рассуждение на каждом шаге. Используйте это для математических задач, логических головоломок или когда нужно понять ход мыслей. +*Как контекст разговора накапливается за несколько ходов до достижения лимита токенов* + +**Пошаговые рассуждения** — для задач, требующих явной логики. Модель показывает явные рассуждения для каждого шага. Используйте для математических задач, логических головоломок или когда нужно понять процесс мышления. ```java String prompt = """ @@ -397,14 +398,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +Диаграмма ниже иллюстрирует, как модель разбивает задачи на явные, пронумерованные логические шаги. -На диаграмме ниже показано, как модель разбивает задачи на явные, пронумерованные логические шаги. - -Step-by-Step Pattern - +Паттерн пошагового рассуждения *Разбиение задач на явные логические шаги* -**Ограниченный вывод** — Для ответов с определёнными требованиями к формату. Модель строго соблюдает правила формата и длины. Используйте это для кратких изложений или когда нужен точный структурированный вывод. +**Ограниченный вывод** – для ответов с особыми требованиями к формату. Модель строго соблюдает правила формата и длины. Используйте это для резюме или когда требуется точная структура вывода. ```java String prompt = """ @@ -420,21 +420,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Следующая диаграмма показывает, как ограничения помогают модели выдавать результат, строго соответствующий вашим требованиям по формату и длине. +Следующая диаграмма показывает, как ограничения направляют модель на создание вывода, строго соответствующего вашим требованиям по формату и длине. -Constrained Output Pattern +Шаблон ограниченного вывода -*Обеспечение соблюдения требований по формату, длине и структуре* +*Принудительное соблюдение требований к формату, длине и структуре* ## Запуск приложения **Проверка развертывания:** -Убедитесь, что в корневой директории существует файл `.env` с учетными данными Azure (созданный в модуле 01). Запустите из директории модуля (`02-prompt-engineering/`): +Убедитесь, что в корневой директории существует файл `.env` с учетными данными Azure (создан в модуле 01). Запустите из каталога модуля (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Должен показать AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Должен показывать AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -444,19 +444,19 @@ Get-Content ..\.env # Должен отображать AZURE_OPENAI_ENDPOINT, **Запуск приложения:** -> **Примечание:** Если вы уже запустили все приложения с помощью `./start-all.sh` из корня (как описано в модуле 01), этот модуль уже запущен на порту 8083. Можно пропустить команды запуска ниже и сразу перейти по адресу http://localhost:8083. +> **Примечание:** Если вы уже запустили все приложения с помощью `./start-all.sh` из корневой директории (как описано в Модуле 01), этот модуль уже работает на порту 8083. Можно пропустить команды запуска ниже и перейти напрямую по адресу http://localhost:8083. **Вариант 1: Использование Spring Boot Dashboard (рекомендуется для пользователей VS Code)** -Dev контейнер включает расширение Spring Boot Dashboard, которое предоставляет визуальный интерфейс для управления всеми приложениями Spring Boot. Найти его можно в панели действий слева в VS Code (значок Spring Boot). +В dev-контейнер включено расширение Spring Boot Dashboard, которое предоставляет визуальный интерфейс для управления всеми приложениями Spring Boot. Найдите его в панели действий слева в VS Code (ищите иконку Spring Boot). -В Spring Boot Dashboard вы можете: -- Просматривать все доступные Spring Boot приложения в рабочей области +Через Spring Boot Dashboard вы можете: +- Видеть все доступные приложения Spring Boot в рабочем пространстве - Запускать/останавливать приложения одним кликом -- Просматривать логи приложений в реальном времени -- Отслеживать статус приложений +- Просматривать логи приложения в реальном времени +- Мониторить статус приложений -Просто нажмите кнопку запуска рядом с "prompt-engineering", чтобы запустить этот модуль, либо запустите сразу все модули. +Просто нажмите кнопку воспроизведения рядом с «prompt-engineering», чтобы запустить этот модуль, или запустите все модули сразу. Spring Boot Dashboard @@ -464,11 +464,11 @@ Dev контейнер включает расширение Spring Boot Dashboa **Вариант 2: Использование shell-скриптов** -Запуск всех веб-приложений (модули 01-04): +Запустите все веб-приложения (модули 01-04): **Bash:** ```bash -cd .. # Из корневой директории +cd .. # Из корневого каталога ./start-all.sh ``` @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Оба скрипта автоматически загружают переменные окружения из корневого файла `.env` и соберут JAR-файлы, если они отсутствуют. +Оба скрипта автоматически загружают переменные окружения из корневого файла `.env` и соберут JAR-файлы, если их нет. -> **Примечание:** Если вы хотите собрать все модули вручную перед запуском: +> **Примечание:** Если вы предпочитаете собирать все модули вручную перед запуском: > > **Bash:** > ```bash @@ -508,9 +508,9 @@ cd 02-prompt-engineering > mvn clean package -DskipTests > ``` -Откройте в браузере http://localhost:8083. +Откройте http://localhost:8083 в браузере. -**Остановка:** +**Для остановки:** **Bash:** ```bash @@ -528,81 +528,81 @@ cd ..; .\stop-all.ps1 # Все модули ## Скриншоты приложения -Вот основной интерфейс модуля prompt engineering, где вы можете экспериментировать со всеми восемью паттернами рядом. +Основной интерфейс модуля prompt engineering, где можно экспериментировать сразу с восемью шаблонами. -Dashboard Home +Главная панель -*Главная панель с отображением всех 8 паттернов prompt engineering, их характеристиками и сценариями использования* +*Главная панель с отображением всех 8 шаблонов prompt engineering с их характеристиками и вариантами использования* -## Изучение паттернов +## Изучение шаблонов -Веб-интерфейс позволяет экспериментировать с разными стратегиями формирования запроса. Каждый паттерн решает разные задачи — попробуйте, чтобы понять, в каких случаях лучше какой подход. +Веб-интерфейс позволяет экспериментировать с разными стратегиями оформления запросов. Каждый шаблон решает разные задачи — попробуйте их, чтобы понять, в каких случаях каждый из них проявляется лучше всего. -> **Примечание: Потоковая передача vs Без потоковой передачи** — На каждой странице паттерна есть две кнопки: **🔴 Потоковый ответ (в реальном времени)** и опция **Без потоковой передачи**. Потоковая передача использует Server-Sent Events (SSE), чтобы показывать токены сразу по мере генерации, так вы видите процесс работы модели. Без потоковой передачи ответ показывается только целиком после завершения генерации. Для запросов, вызывающих глубокое рассуждение (например, High Eagerness, Self-Reflecting Code), вариант без потоковой передачи может занимать очень много времени — иногда минуты — без видимой обратной связи. **Используйте потоковую передачу при экспериментах с комплексными запросами**, чтобы видеть процесс работы и не думать, что запрос завис. +> **Примечание: Потоковый vs непотоковый режим** — На каждой странице шаблона есть две кнопки: **🔴 Потоковый ответ (В реальном времени)** и вариант **Непотоковый**. Потоковый режим использует Server-Sent Events (SSE) для отображения токенов по мере их генерации моделью, так вы видите прогресс сразу. Непотоковый режим ждет полного ответа перед отображением. Для запросов с глубокой проработкой (например, High Eagerness, Self-Reflecting Code) непотоковый вызов может занимать очень много времени — иногда минуты — без видимой обратной связи. **Используйте потоковый режим для экспериментов с комплексными запросами**, чтобы видеть работу модели и не думать, что запрос «завис». > -> **Примечание: Требования к браузеру** — Потоковая передача использует Fetch Streams API (`response.body.getReader()`), который поддерживается в полноценных браузерах (Chrome, Edge, Firefox, Safari). Она **не работает** во встроенном Simple Browser VS Code, так как его webview не поддерживает ReadableStream API. В Simple Browser кнопки без потоковой передачи работают нормально — затрагиваются только потоковые кнопки. Для полного опыта открывайте `http://localhost:8083` во внешнем браузере. +> **Примечание: Требование к браузеру** — Потоковый режим использует Fetch Streams API (`response.body.getReader()`), который требует полноценный браузер (Chrome, Edge, Firefox, Safari). Он **не работает** во встроенном Simple Browser VS Code, так как его вебвью не поддерживает ReadableStream API. Если вы используете Simple Browser, непотоковые кнопки работают нормально — потоковые затронуты. Для полного опыта открывайте `http://localhost:8083` во внешнем браузере. -### Низкая vs высокая старательность (Eagerness) +### Низкая vs высокая активность мышления -Задайте простой вопрос, например "Сколько будет 15% от 200?" с Low Eagerness. Вы получите мгновенный прямой ответ. Теперь задайте сложный вопрос типа "Разработай стратегию кэширования для высоконагруженного API" с High Eagerness. Нажмите **🔴 Потоковый ответ (в реальном времени)** и наблюдайте, как появляется подробное пошаговое рассуждение токен за токеном. Та же модель, та же структура вопроса — но подсказка задаёт интенсивность размышлений. +Задайте простой вопрос типа «Сколько будет 15% от 200?» с низкой активностью. Вы получите мгновенный, прямой ответ. Теперь задайте сложный вопрос типа «Спроектируй стратегию кэширования для высоконагруженного API» с высокой активностью. Нажмите **🔴 Потоковый ответ (В реальном времени)** и наблюдайте, как модель последовательно выводит подробные рассуждения. Та же модель, та же структура вопроса — но в запросе указано, сколько размышлений делать. -### Выполнение задач (преамбулы инструментов) +### Выполнение задач (инструкции по инструментам) -Многошаговые рабочие процессы выигрывают от предварительного планирования и прогресс-отчётов. Модель сначала описывает, что сделает, затем повествует о каждом шаге, а в конце подводит итоги. +Многошаговые рабочие процессы выигрывают от предварительного планирования и озвучивания прогресса. Модель описывает, что сделает, озвучивает каждый шаг, затем подводит итоги. ### Саморефлексирующий код -Попробуйте "Создай сервис валидации email". Вместо того чтобы просто сгенерировать код и остановиться, модель генерирует, оценивает по критериям качества, выявляет слабые места и улучшает. Вы увидите, как она итерирует код до соответствия стандартам продакшена. +Попробуйте «Создать сервис проверки email». Вместо простой генерации кода и остановки, модель генерирует, оценивает по критериям качества, выявляет слабые места и улучшает. Вы увидите, как она итеративно дорабатывает код, пока он не станет готов к продакшену. ### Структурированный анализ -Код-ревью требуют единых критериев оценки. Модель анализирует код по фиксированным категориям (корректность, практики, производительность, безопасность) с уровнями серьёзности. +Код-ревью требует единой рамки оценки. Модель анализирует код по фиксированным категориям (корректность, практики, производительность, безопасность) с уровнем серьезности. -### Многоходовой чат +### Многошаговый чат -Спросите "Что такое Spring Boot?", а затем сразу "Покажи пример". Модель помнит ваш первый вопрос и даёт конкретный пример Spring Boot. Без памяти второй вопрос был бы слишком расплывчатым. +Спросите «Что такое Spring Boot?», затем сразу «Покажи пример». Модель помнит первый вопрос и дает именно пример Spring Boot. Без памяти второй вопрос был бы слишком неопределенным. -### Пошаговое рассуждение +### Поэтапное рассуждение -Возьмите математическую задачу и попробуйте решить её с помощью Step-by-Step Reasoning и Low Eagerness. Low Eagerness просто выдает ответ — быстро, но без объяснений. Пошаговое рассуждение показывает все вычисления и решения. +Выберите математическую задачу и попробуйте решить её и с пошаговым рассуждением, и с низкой активностью. Низкая активность просто дает ответ — быстро, но без объяснений. Пошаговое рассуждение показывает все вычисления и логику. ### Ограниченный вывод -Когда нужен конкретный формат или размер текста, этот паттерн строго это обеспечивает. Попробуйте сгенерировать резюме ровно из 100 слов в виде списка. +Когда нужен конкретный формат или точное количество слов, этот шаблон строго контролирует выполнение. Попробуйте сгенерировать резюме ровно из 100 слов в виде списка. -## Что вы действительно изучаете +## Чему вы на самом деле учитесь -**Усилия в рассуждении меняют всё** +**Усилия в рассуждениях меняют всё** -GPT-5.2 позволяет вам контролировать вычислительные усилия через ваши подсказки. Малая нагрузка — это быстрые ответы с минимальными поисками. Большая нагрузка — модель тратит время на глубокое размышление. Вы учитесь соответствовать усилия сложности задачи — не тратите время зря на простые вопросы, но и не торопитесь с важными решениями. +GPT-5.2 позволяет управлять вычислительной нагрузкой с помощью запросов. Низкие усилия — быстрые ответы с минимальным исследованием. Высокие усилия — глубокое, вдумчивое рассуждение модели. Вы учитесь соотносить усилия с сложностью задачи — не тратьте время на простые вопросы, но и не спешите при сложных решениях. -**Структура управляет поведением** +**Структура задает поведение** -Заметили XML-теги в подсказках? Это не украшение. Модели надежнее следуют структурированным инструкциям, чем произвольному тексту. Когда нужны многошаговые процессы или сложная логика, структура помогает модели понимать, где она и что дальше. На диаграмме ниже показан пример хорошо структурированной подсказки с тегами ``, ``, ``, `` и ``, которые организуют указания в чёткие разделы. +Обратили внимание на XML-теги в запросах? Это не украшение. Модели надежнее следуют структурированным инструкциям, чем свободному тексту. Когда нужны многошаговые процессы или сложная логика, структура помогает модели понимать, где она и что делать дальше. На диаграмме ниже разбирается хорошо структурированный запрос с такими тегами как ``, ``, ``, `` и ``, которые организуют инструкции по разделам. -Prompt Structure +Структура запроса -*Анатомия хорошо структурированной подсказки с чёткими разделами и организацией в стиле XML* +*Анатомия хорошо структурированного запроса с четкими разделами и организацией в стиле XML* **Качество через самооценку** -Паттерны самоанализа работают, задавая чёткие критерии качества. Вместо надежды, что модель "сделает правильно", вы точно указываете, что значит "правильно": логика, обработка ошибок, производительность, безопасность. Тогда модель может сама оценить результат и улучшить его. Это превращает генерацию кода из лотереи в контролируемый процесс. +Шаблоны с саморефлексией работают, делая критерии качества явными. Вместо надежды, что модель «сделает правильно», вы точно говорите, что значит «правильно»: корректная логика, обработка ошибок, производительность, безопасность. Модель может оценивать собственный вывод и улучшаться. Это превращает генерацию кода из лотереи в процесс. **Контекст ограничен** -Многоходовые диалоги работают, включая историю сообщений в каждый запрос. Но есть лимит — у каждой модели максимальное количество токенов. По мере роста диалогов нужно стратегии для сохранения релевантного контекста без превышения лимита. Этот модуль показывает, как работает память; позже вы научитесь, когда обобщать, когда забывать, а когда извлекать. +Многошаговые диалоги работают за счет включения истории сообщений в каждый запрос. Но есть предел — у каждой модели максимум токенов. По мере роста беседы нужны стратегии сохранения релевантного контекста, не превышая лимит. Этот модуль показывает работу памяти; позже вы узнаете, когда сворачивать, забывать и вызывать контекст. ## Следующие шаги -**Следующий модуль:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**Следующий модуль:** [03-rag - RAG (гибридный генеративный поиск)](../03-rag/README.md) --- -**Навигация:** [← Предыдущий: Модуль 01 - Введение](../01-introduction/README.md) | [Назад к Главной](../README.md) | [Следующий: Модуль 03 - RAG →](../03-rag/README.md) +**Навигация:** [← Предыдущий: Модуль 01 - Введение](../01-introduction/README.md) | [Назад к главной](../README.md) | [Далее: Модуль 03 - RAG →](../03-rag/README.md) --- **Отказ от ответственности**: -Данный документ был переведен с использованием сервиса автоматического перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия обеспечить точность, просим учитывать, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его родном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется использовать профессиональный перевод человеком. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования данного перевода. +Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода. \ No newline at end of file diff --git a/translations/ru/03-rag/README.md b/translations/ru/03-rag/README.md index 7feedfdb7..9452b403b 100644 --- a/translations/ru/03-rag/README.md +++ b/translations/ru/03-rag/README.md @@ -1,30 +1,30 @@ -# Модуль 03: RAG (Генерация с поддержкой поиска) +# Модуль 03: RAG (генерация с использованием поиска) ## Содержание -- [Видеообзор](../../../03-rag) -- [Что вы узнаете](../../../03-rag) -- [Требования](../../../03-rag) -- [Понимание RAG](../../../03-rag) - - [Какой подход RAG используется в этом руководстве?](../../../03-rag) -- [Как это работает](../../../03-rag) - - [Обработка документов](../../../03-rag) - - [Создание эмбеддингов](../../../03-rag) - - [Семантический поиск](../../../03-rag) - - [Генерация ответа](../../../03-rag) -- [Запуск приложения](../../../03-rag) -- [Использование приложения](../../../03-rag) - - [Загрузка документа](../../../03-rag) - - [Задавайте вопросы](../../../03-rag) - - [Проверка источников](../../../03-rag) - - [Эксперименты с вопросами](../../../03-rag) -- [Основные концепции](../../../03-rag) - - [Стратегия разделения на чанки](../../../03-rag) - - [Оценки сходства](../../../03-rag) - - [Хранение в памяти](../../../03-rag) - - [Управление контекстным окном](../../../03-rag) -- [Когда RAG важен](../../../03-rag) -- [Следующие шаги](../../../03-rag) +- [Видеообзор](#видеообзор) +- [Чему вы научитесь](#чему-вы-научитесь) +- [Требования](#требования) +- [Понимание RAG](#понимание-rag) + - [Какой подход RAG используется в этом руководстве?](#какой-подход-rag-используется-в-этом-руководстве) +- [Как это работает](#как-это-работает) + - [Обработка документов](#обработка-документов) + - [Создание эмбеддингов](#создание-эмбеддингов) + - [Семантический поиск](#семантический-поиск) + - [Генерация ответов](#генерация-ответа) +- [Запуск приложения](#запуск-приложения) +- [Использование приложения](#использование-приложения) + - [Загрузка документа](#загрузка-документа) + - [Задавайте вопросы](#задавайте-вопросы) + - [Проверка ссылок на источники](#проверяйте-ссылки-на-источники) + - [Эксперименты с вопросами](#экспериментируйте-с-вопросами) +- [Ключевые понятия](#ключевые-концепции) + - [Стратегия разбиения на части](#стратегия-разбиения-на-куски) + - [Оценки схожести](#оценки-похожести) + - [Хранение в памяти](#хранение-в-памяти) + - [Управление контекстным окном](#управление-контекстным-окном) +- [Когда RAG имеет значение](#когда-rag-имеет-значение) +- [Следующие шаги](#следующие-шаги) ## Видеообзор @@ -32,114 +32,112 @@ RAG with LangChain4j - Live Session -## Что вы узнаете +## Чему вы научитесь -В предыдущих модулях вы узнали, как вести разговор с ИИ и эффективно структурировать свои запросы. Но есть фундаментальное ограничение: языковые модели знают только то, чему их научили во время обучения. Они не могут ответить на вопросы о политике вашей компании, документации вашего проекта или любую информацию, которой не обучались. +В предыдущих модулях вы научились вести диалоги с ИИ и эффективно структурировать подсказки. Но есть фундаментальное ограничение: языковые модели знают только то, чему они были обучены. Они не могут отвечать на вопросы о политике вашей компании, документации проекта или любой информации, которой не обучались. -RAG (Генерация с поддержкой поиска) решает эту проблему. Вместо того, чтобы пытаться обучить модель вашей информации (что дорого и непрактично), вы даёте ей возможность искать по вашим документам. Когда кто-то задаёт вопрос, система находит релевантную информацию и включает её в запрос. Модель затем отвечает, основываясь на полученном контексте. +RAG (генерация с использованием поиска) решает эту проблему. Вместо того, чтобы пытаться обучить модель вашей информации (что дорого и непрактично), вы даёте ей возможность искать по вашим документам. Когда кто-то задаёт вопрос, система находит соответствующую информацию и включает её в подсказку. Модель затем отвечает, основываясь на найденном контексте. -Подумайте о RAG как о библиотеке справочных материалов для модели. Когда вы задаёте вопрос, система: +Думайте о RAG как о предоставлении модели справочной библиотеки. Когда вы задаёте вопрос, система: -1. **Запрос пользователя** — вы задаёте вопрос -2. **Эмбеддинг** — преобразование вашего вопроса в вектор -3. **Векторный поиск** — поиск похожих кусочков документа -4. **Формирование контекста** — добавление релевантных частей в запрос -5. **Ответ** — языковая модель генерирует ответ на основе контекста +1. **Запрос пользователя** — Вы задаёте вопрос +2. **Эмбеддинг** — Преобразует ваш вопрос в вектор +3. **Поиск в векторном пространстве** — Находит схожие части документов +4. **Формирование контекста** — Добавляет релевантные части в подсказку +5. **Ответ** — LLM генерирует ответ на основании контекста -Это связывает ответы модели с вашими реальными данными, а не просто с её обучением или вымышленными ответами. +Это закрепляет ответы модели в ваших реальных данных вместо того, чтобы полагаться только на знания из обучения или придумывать ответы. ## Требования -- Завершён [Модуль 00 - Быстрый старт](../00-quick-start/README.md) (для примера Easy RAG, упомянутого позже в этом модуле) -- Завершён [Модуль 01 - Введение](../01-introduction/README.md) (развёрнуты ресурсы Azure OpenAI, включая модель эмбеддинга `text-embedding-3-small`) -- Файл `.env` в корневой директории с учётными данными Azure (создаётся командой `azd up` в Модуле 01) +- Закончен [Модуль 01 - Введение](../01-introduction/README.md) (развёрнуты ресурсы Azure OpenAI, включая модель эмбеддинга `text-embedding-3-small`) +- Файл `.env` в корневой директории с учётными данными Azure (создаётся командой `azd up` в Модуле 01) -> **Примечание:** Если вы не завершили Модуль 01, сначала следуйте тамошним инструкциям по развёртыванию. Команда `azd up` развёртывает как GPT чат-модель, так и модель эмбеддинга, используемую в этом модуле. +> **Примечание:** Если вы не завершили Модуль 01, сначала следуйте там инструкциям по развёртыванию. Команда `azd up` развёртывает как GPT чат-модель, так и используемую в этом модуле модель эмбеддинга. ## Понимание RAG -Ниже диаграмма иллюстрирует основную концепцию: вместо того, чтобы полагаться только на данные обучения модели, RAG даёт ей библиотеку ваших документов, к которым она обращается перед генерацией каждого ответа. +Схема ниже иллюстрирует основную концепцию: вместо того чтобы полагаться только на обучающие данные модели, RAG даёт ей справочную библиотеку ваших документов для обращения к ним перед генерацией каждого ответа. -Что такое RAG +What is RAG -*На этой диаграмме показано отличие стандартной модели LLM (которая делает предположения на основе обучающих данных) от модели с поддержкой RAG (которая сначала обращается к вашим документам).* +*Эта схема показывает разницу между стандартной LLM (которая угадывает из обучающих данных) и LLM с RAG (которая сначала обращается к вашим документам).* -Вот как части связаны от начала до конца. Вопрос пользователя проходит через четыре этапа — эмбеддинг, векторный поиск, формирование контекста и генерацию ответа — каждый из которых строится на предыдущем: +Вот как элементы связаны от начала до конца. Вопрос пользователя проходит через четыре этапа — эмбеддинг, поиск по векторам, сбор контекста и генерация ответа — каждый из которых строится на предыдущем: -Архитектура RAG +RAG Architecture -*На диаграмме показан полный конвейер RAG — запрос пользователя проходит через эмбеддинг, векторный поиск, формирование контекста и генерацию ответа.* +*Эта схема показывает сквозной конвейер RAG — запрос пользователя проходит через эмбеддинг, поиск по векторам, сбор контекста и генерацию ответа.* -Остальная часть этого модуля подробно разбирает каждый этап с приведённым кодом, который вы можете запускать и изменять. +Далее в этом модуле подробно разбирается каждый этап с кодом, который вы можете запускать и модифицировать. ### Какой подход RAG используется в этом руководстве? -LangChain4j предлагает три способа реализации RAG, каждый с разным уровнем абстракции. Ниже диаграмма, которая сравнивает их рядом: +LangChain4j предлагает три способа реализовать RAG с разными уровнями абстракции. Схема ниже сравнивает их рядом: -Три подхода RAG в LangChain4j +Three RAG Approaches in LangChain4j -*Диаграмма сравнивает три подхода RAG в LangChain4j — Easy, Native и Advanced, показывая их ключевые компоненты и когда использовать каждый.* +*Эта схема сравнивает три подхода RAG в LangChain4j — Easy, Native и Advanced — показывая их ключевые компоненты и когда использовать каждый.* | Подход | Что делает | Компромисс | |---|---|---| -| **Easy RAG** | Автоматически связывает всё через `AiServices` и `ContentRetriever`. Вы аннотируете интерфейс, прикрепляете поиск, а LangChain4j занимается эмбеддингом, поиском и сборкой запросов за кулисами. | Минимум кода, но вы не видите, что происходит на каждом шаге. | -| **Native RAG** | Вы сами вызываете модель эмбеддинга, ищете в хранилище, собираете запрос и генерируете ответ — каждый шаг явно прописан. | Больше кода, но каждый этап виден и изменяем. | -| **Advanced RAG** | Использует фреймворк `RetrievalAugmentor` с подключаемыми преобразователями запросов, маршрутизаторами, ремаркетингом и инжекторами контента для промышленных решений. | Максимальная гибкость, но значительно большая сложность. | +| **Easy RAG** | Автоматически связывает всё через `AiServices` и `ContentRetriever`. Вы аннотируете интерфейс, подключаете ретривер, а LangChain4j за кулисами обрабатывает эмбеддинг, поиск и сбор контекста. | Минимум кода, но вы не видите внутренние этапы. | +| **Native RAG** | Вы сами вызываете модель эмбеддинга, ищете в хранилище, строите подсказку и генерируете ответ — явно каждый шаг. | Больше кода, но каждый этап виден и изменяем. | +| **Advanced RAG** | Использует фреймворк `RetrievalAugmentor` с подключаемыми трансформерами запросов, маршрутизаторами, повторной сортировкой и инжекторами контента для промышленных решений. | Максимальная гибкость, но значительно больше сложности. | -**В этом уроке используется Native подход.** Каждый этап конвейера RAG — эмбеддинг запроса, поиск в векторном хранилище, сбор контекста и генерация ответа — явно написан в [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Это сделано умышленно: в целях обучения важнее, чтобы вы видели и понимали каждый этап, а не минимизировали код. Когда вы почувствуете себя комфортно с тем, как всё работает, можно перейти к Easy RAG для быстрых прототипов или Advanced RAG для промышленных систем. +**В этом руководстве используется подход Native.** Каждый шаг конвейера RAG — эмбеддинг запроса, поиск в векторном хранилище, сбор контекста и генерация ответа — написан явно в [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Это сделано намеренно: в учебных целях важнее видеть и понимать каждый этап, чем минимизировать код. Когда вы освоитесь с тем, как всё связано, можете перейти к Easy RAG для быстрых прототипов или Advanced RAG для продакшн-систем. -> **💡 Уже видели Easy RAG в действии?** Модуль [Быстрый старт](../00-quick-start/README.md) содержит пример вопрос-ответ с документом ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), который использует подход Easy RAG — LangChain4j автоматически занимается эмбеддингом, поиском и сборкой запросов. Этот модуль делает следующий шаг, разбирая этот конвейер, чтобы вы могли видеть и контролировать каждый этап сами. +> **💡 Интересует Easy RAG?** LangChain4j также предлагает *Easy RAG*, где `AiServices` и `ContentRetriever` автоматически обрабатывают эмбеддинг, поиск и сбор подсказок. Этот модуль идёт более явным путём — раскрывая каждый этап конвейера, чтобы вы могли видеть и контролировать его сами. -Ниже показан конвейер Easy RAG из примера Быстрого старта. Обратите внимание, как `AiServices` и `EmbeddingStoreContentRetriever` скрывают всю сложность — вы загружаете документ, подключаете поисковый модуль и получаете ответы. Native подход в этом модуле разбирает каждый скрытый шаг: +Схема ниже показывает конвейер Easy RAG. Обратите внимание, как `AiServices` и `EmbeddingStoreContentRetriever` скрывают всю сложность — вы загружаете документ, подключаете ретривер и получаете ответы. Подход Native в этом модуле разбирает каждый из этих скрытых шагов: -Конвейер Easy RAG - LangChain4j +Easy RAG Pipeline - LangChain4j -*Диаграмма показывает конвейер Easy RAG из `SimpleReaderDemo.java`. Сравните его с Native подходом в этом модуле: Easy RAG скрывает эмбеддинг, поиск и сборку запроса за `AiServices` и `ContentRetriever` — вы загружаете документ, подключаете поисковый модуль и получаете ответы. Native подход в этом модуле раскрывает этот конвейер, чтобы вы могли вызывать каждый этап (эмбеддить, искать, собирать контекст, генерировать) самостоятельно, обеспечивая полный контроль и прозрачность.* +*Эта схема показывает конвейер Easy RAG. Сравните с Native подходом из этого модуля: Easy RAG скрывает эмбеддинг, поиск и сбор подсказки за `AiServices` и `ContentRetriever` — вы загружаете документ, подключаете ретривер и получаете ответы. Native подход в этом модуле раскрывает конвейер, чтобы вы вызывали каждый этап (эмбеддинг, поиск, сбор контекста, генерация) самостоятельно, давая полный контроль.* ## Как это работает -Конвейер RAG в этом модуле разделён на четыре этапа, которые выполняются последовательно каждый раз, когда пользователь задаёт вопрос. Сначала загруженный документ **разбирается и разбивается на чанки** — управляемые по размеру части. Затем эти чанки преобразуются в **векторные эмбеддинги** и сохраняются для последующего математического сравнения. Когда поступает запрос, система выполняет **семантический поиск**, чтобы найти наиболее релевантные чанки, и в конце передаёт их в LLM для **генерации ответа**. Ниже по разделам подробно рассмотрим каждый этап с реальным кодом и диаграммами. Начнём с первого шага. +Конвейер RAG в этом модуле разбит на четыре этапа, выполняющихся последовательно при каждом вопросе пользователя. Сначала загруженный документ **парсится и разбивается на части**. Эти части затем преобразуются в **векторные эмбеддинги** и сохраняются для математического сравнения. При поступлении запроса система выполняет **семантический поиск** релевантных частей и передаёт их в LLM для **генерации ответа**. Ниже вы найдёте описание каждого этапа с реальным кодом и схемами. Рассмотрим первый шаг. ### Обработка документов [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Когда вы загружаете документ, система его парсит (PDF или простой текст), добавляет метаданные, такие как имя файла, а затем разбивает на чанки — меньшие части, которые удобно помещаются в контекстное окно модели. Эти чанки частично перекрываются, чтобы не терялся контекст на границах. +Когда вы загружаете документ, система парсит его (PDF или обычный текст), добавляет метаданные, например имя файла, а затем разбивает на части — более мелкие фрагменты, которые удобно помещаются в контекст модели. Части немного перекрываются, чтобы не терять контекст на границах. ```java -// Разобрать загруженный файл и обернуть его в Документ LangChain4j +// Разобрать загруженный файл и обернуть его в документ LangChain4j Document document = Document.from(content, metadata); -// Разделить на фрагменты по 300 токенов с перекрытием в 30 токенов +// Разделить на части по 300 токенов с перекрытием в 30 токенов DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` +Схема ниже демонстрирует это визуально. Обратите внимание, что каждая часть частично перекрывается с соседними — перекрытие в 30 токенов гарантирует, что важный контекст не теряется между частями: -Ниже диаграмма визуально показывает, как это работает. Обратите внимание, что каждый чанк частично совпадает с соседними — перекрытие на 30 токенов гарантирует, что важный контекст не потеряется между частями: +Document Chunking -Разбиение документа на чанки +*Эта схема показывает документ, разбитый на части по 300 токенов с перекрытием в 30 токенов, сохраняя контекст на границах.* -*На диаграмме показано, как документ разбивается на чанки по 300 токенов с перекрытием 30 токенов, что сохраняет контекст на границах.* - -> **🤖 Попробуйте с помощью [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) и спросите: -> - «Как LangChain4j делит документы на чанки и почему перекрытие важно?» -> - «Какой оптимальный размер чанка для разных типов документов и почему?» -> - «Как обрабатывать документы на нескольких языках или с особым форматированием?» +> **🤖 Попробуйте с помощью [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) и задайте вопросы: +> - "Как LangChain4j разбивает документы на части и почему важно перекрытие?" +> - "Какой оптимальный размер части для разных типов документов и почему?" +> - "Как обрабатывать документы на нескольких языках или с особым форматированием?" ### Создание эмбеддингов [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Каждый чанк преобразуется в числовое представление, называемое эмбеддингом — по сути, конвертер значения в числа. Модель эмбеддинга не «умна» в том смысле, в каком умна чат-модель; она не следует инструкциям, не рассуждает и не отвечает на вопросы. Она лишь отображает текст в математическое пространство, где похожие по смыслу вектора располагаются рядом — «car» рядом с «automobile», «refund policy» рядом с «return my money». Подумайте о чат-модели как о собеседнике, с которым можно поговорить, а модель эмбеддинга — как о превосходной системе классификации. +Каждая часть преобразуется в числовое представление, называемое эмбеддингом — по сути конвертер значений в числа. Модель эмбеддинга не «интеллектуальна», как чат-модель; она не может следовать инструкциям, рассуждать или отвечать на вопросы. Зато она отображает текст в математическое пространство, где схожие значения оказываются рядом — «машина» рядом с «автомобилем», «политика возврата» рядом с «верните мои деньги». Можно представить чат-модель как человека для разговора, а модель эмбеддинга — как отличный файл. -Ниже диаграмма визуализирует эту концепцию — текст на входе, числовые векторы на выходе, близкие по смыслу значения располагаются рядом: +Схема ниже визуализирует эту концепцию — поступает текст, выходят числовые векторы, и схожие значения образуют близкие векторы: -Концепция модели эмбеддинга +Embedding Model Concept -*Диаграмма показывает, как модель эмбеддинга преобразует текст в числовые векторы, размещая похожие по смыслу слова — например, «car» и «automobile» — рядом в векторном пространстве.* +*Эта схема показывает, как модель эмбеддинга преобразует текст в числовые векторы, располагая похожие значения — например "машина" и "автомобиль" — рядом в векторном пространстве.* ```java @Bean @@ -155,30 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` +Диаграмма классов показывает два отдельных потока в конвейере RAG и соответствующие классы LangChain4j. **Поток загрузки** (запускается один раз при загрузке) разбивает документ, создаёт эмбеддинги частей и сохраняет их через `.addAll()`. **Поток запроса** (запускается при каждом запросе пользователя) создаёт эмбеддинг вопроса, ищет в хранилище через `.search()` и передаёт найденный контекст в чат-модель. Оба потока соединяются через общий интерфейс `EmbeddingStore`: -Ниже класс диаграммы показывает два отдельных потока в конвейере RAG и классы LangChain4j, которые их реализуют. **Поток загрузки** (запускается один раз при загрузке) разбивает документ, создаёт эмбеддинги чанков и сохраняет их через `.addAll()`. **Поток запроса** (запускается при каждом вопросе) эмбеддит вопрос, ищет по хранилищу через `.search()` и передаёт найденный контекст в чат-модель. Оба потока соединяются через общий интерфейс `EmbeddingStore`: - -Классы RAG в LangChain4j +LangChain4j RAG Classes -*Диаграмма показывает два потока в конвейере RAG — загрузку и запрос, и как они связаны через общий EmbeddingStore.* +*Эта схема показывает два потока в конвейере RAG — загрузку и запрос — и как они связаны через общий EmbeddingStore.* -После сохранения эмбеддингов похожий контент естественно группируется в векторном пространстве. Ниже визуализация показывает, как документы на схожие темы оказываются близко друг к другу, что и делает возможным семантический поиск: +После сохранения эмбеддингов схожий контент естественно группируется в векторном пространстве. Визуализация ниже показывает, как документы по связанным темам образуют соседние точки — именно это делает возможным семантический поиск: -Пространство векторных эмбеддингов +Vector Embeddings Space -*Визуализация показывает, как связанные документы сгруппированы в 3D векторном пространстве, с темами, такими как техническая документация, бизнес-правила и FAQ, образующими отдельные группы.* +*Эта визуализация показывает, как связанные документы группируются вместе в 3D векторном пространстве, с такими темами, как техническая документация, бизнес-правила и часто задаваемые вопросы, образующими отдельные кластеры.* -Когда пользователь ищет, система выполняет четыре шага: один раз эмбеддит документы, затем эмбеддит запрос при каждом поиске, сравнивает вектор запроса со всеми сохранёнными векторами с помощью косинусного сходства и возвращает топ-К чанков с наивысшими оценками. Ниже диаграмма описывает каждый шаг и классы LangChain4j, участвующие в процессе: +При поиске система выполняет четыре шага: эмбеддит документы один раз, эмбеддит запрос при каждом поиске, сравнивает вектор запроса со всеми сохранёнными векторами с помощью косинусного сходства и возвращает топ-K самых релевантных частей. Схема ниже показывает шаги и вовлечённые классы LangChain4j: -Шаги поиска через эмбеддинги +Embedding Search Steps -*Диаграмма показывает четырёхэтапный процесс поиска: эмбеддинг документов, эмбеддинг запроса, сравнение векторов с помощью косинусного сходства и возврат топ-К результатов.* +*Эта схема показывает четырёхшаговый процесс поиска по эмбеддингам: эмбеддит документы, эмбеддит запрос, сравнивает векторы с помощью косинусного сходства и возвращает топ-K результатов.* ### Семантический поиск [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Когда вы задаёте вопрос, он тоже преобразуется в эмбеддинг. Система сравнивает эмбеддинг вашего вопроса со всеми эмбеддингами чанков документа. Находит чанки с максимально похожими значениями — не только по ключевым словам, но по смысловой близости. +Когда вы задаёте вопрос, он тоже преобразуется в эмбеддинг. Система сравнивает эмбеддинг вашего вопроса со всеми эмбеддингами частей документов. Она находит части с наиболее схожими значениями — не только совпадающие ключевые слова, но и фактическую семантическую близость. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -198,28 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` +Схема ниже сравнивает семантический поиск с традиционным поиском по ключевым словам. Поиск по слову "транспортное средство" пропускает часть с «машины и грузовики», но семантический поиск понимает, что они означают одно и то же, и возвращает её как релевантный результат: -Ниже диаграмма сравнивает семантический поиск с традиционным поиском по ключевым словам. Запрос по слову «vehicle» не находит чанк про «cars and trucks», но семантический поиск понимает, что это одно и то же и возвращает этот чанк как релевантный: - -Семантический поиск +Semantic Search -*Диаграмма сравнивает поиск по ключевым словам и семантический поиск, показывая, как семантический поиск извлекает концептуально связанные данные, даже если точных ключевых слов нет.* -Под капотом измерение схожести осуществляется с помощью косинусной близости — по сути, это вопрос «направлены ли эти два вектора в ту же сторону?» Два фрагмента могут использовать совершенно разные слова, но если они означают одно и то же, их векторы направлены одинаково и оцениваются близко к 1.0: +*Эта схема сравнивает поиск по ключевым словам с семантическим поиском, показывая, как семантический поиск находит концептуально связанные материалы, даже если точные ключевые слова отличаются.* -Косинусная близость +В основе лежит косинусное сходство — по сути вопрос "указывают ли эти две стрелки в одном направлении?" Две части могут использовать совершенно разные слова, но если они означают одно и то же, их векторы указывают в одном направлении и набирают оценку, близкую к 1.0: -*Эта диаграмма иллюстрирует косинусную близость как угол между векторными эмбеддингами — более выровненные векторы имеют оценку ближе к 1.0, что указывает на более высокую семантическую схожесть.* +Cosine Similarity +*Эта диаграмма иллюстрирует косинусное сходство как угол между векторами эмбеддингов — более согласованные векторы имеют оценку ближе к 1.0, что указывает на более высокое семантическое сходство.* > **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) и спросите: -> - «Как работает поиск по схожести с помощью эмбеддингов и что определяет оценку?» -> - «Какой порог схожести следует использовать и как он влияет на результаты?» -> - «Как обработать случаи, когда релевантные документы не найдены?» +> - "Как работает поиск по похожести с эмбеддингами и что определяет оценку?" +> - "Какой порог похожести следует использовать и как это влияет на результаты?" +> - "Как обрабатывать случаи, когда не найдено релевантных документов?" -### Генерация ответов +### Генерация ответа [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Наиболее релевантные фрагменты собираются в структурированный промпт, который включает явные инструкции, извлечённый контекст и вопрос пользователя. Модель читает именно эти фрагменты и отвечает на основе этой информации — она может использовать только то, что перед ней, что предотвращает галлюцинации. +Самые релевантные куски собираются в структурированный запрос, который включает явные инструкции, извлечённый контекст и вопрос пользователя. Модель читает именно эти куски и отвечает на основе этой информации — она может использовать только то, что у неё перед глазами, что предотвращает галлюцинации. ```java String context = matches.stream() @@ -240,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Ниже показано, как происходит эта сборка — фрагменты с наивысшими оценками из шага поиска вставляются в шаблон промпта, и `OpenAiOfficialChatModel` генерирует обоснованный ответ: +Диаграмма ниже показывает эту сборку в действии — куски с наивысшим баллом из этапа поиска вставляются в шаблон запроса, и `OpenAiOfficialChatModel` генерирует обоснованный ответ: -Сборка контекста +Context Assembly -*Эта диаграмма показывает, как фрагменты с наивысшими оценками собираются в структурированный промпт, позволяя модели генерировать обоснованный ответ на основе ваших данных.* +*Эта диаграмма показывает, как куски с наивысшим баллом собираются в структурированный запрос, позволяя модели генерировать обоснованный ответ на основе ваших данных.* ## Запуск приложения -**Проверьте развертывание:** +**Проверка развертывания:** -Убедитесь, что файл `.env` существует в корневой директории с учетными данными Azure (создан в модуле 01). Запустите это из директории модуля (`03-rag/`): +Убедитесь, что в корневой директории существует файл `.env` с учётными данными Azure (созданный в Модуле 01). Запустите это из директории модуля (`03-rag/`): **Bash:** ```bash @@ -259,36 +255,36 @@ cat ../.env # Должен отображать AZURE_OPENAI_ENDPOINT, API_KEY, **PowerShell:** ```powershell -Get-Content ..\.env # Должен показать AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Должен отображать AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Запустите приложение:** +**Запуск приложения:** -> **Примечание:** Если вы уже запускали все приложения с помощью `./start-all.sh` из корневой директории (как описано в модуле 01), этот модуль уже работает на порту 8081. Вы можете пропустить команды запуска ниже и перейти прямо по адресу http://localhost:8081. +> **Примечание:** Если вы уже запускали все приложения с помощью `./start-all.sh` из корневой директории (как описано в Модуле 01), этот модуль уже работает на порту 8081. Вы можете пропустить команды запуска и перейти напрямую по адресу http://localhost:8081. **Вариант 1: Использование Spring Boot Dashboard (рекомендуется для пользователей VS Code)** -Dev-контейнер включает расширение Spring Boot Dashboard, которое предоставляет визуальный интерфейс для управления всеми приложениями Spring Boot. Вы можете найти его на панели активности слева в VS Code (иконка Spring Boot). +В контейнере разработчика установлено расширение Spring Boot Dashboard, которое предоставляет визуальный интерфейс для управления всеми приложениями Spring Boot. Вы найдёте его на панели активности слева в VS Code (иконка Spring Boot). С помощью Spring Boot Dashboard вы можете: - Просматривать все доступные приложения Spring Boot в рабочем пространстве -- Запускать и останавливать приложения одним кликом +- Запускать/останавливать приложения одним кликом - Просматривать логи приложений в реальном времени -- Отслеживать состояние приложений +- Отслеживать статус приложений -Просто нажмите кнопку запуска рядом с "rag", чтобы стартовать этот модуль, или запустите все модули сразу. +Просто нажмите кнопку запуска рядом с "rag", чтобы запустить этот модуль, или запустите сразу все модули. -Панель управления Spring Boot +Spring Boot Dashboard -*Этот скриншот показывает панель управления Spring Boot в VS Code, где вы можете визуально запускать, останавливать и мониторить приложения.* +*Этот скриншот показывает Spring Boot Dashboard в VS Code, где можно визуально запускать, останавливать и мониторить приложения.* -**Вариант 2: Использование скриптов shell** +**Вариант 2: Использование shell-скриптов** Запустите все веб-приложения (модули 01-04): **Bash:** ```bash -cd .. # Из корневого каталога +cd .. # Из корневой директории ./start-all.sh ``` @@ -312,16 +308,16 @@ cd 03-rag .\start.ps1 ``` -Оба скрипта автоматически загружают переменные окружения из корневого файла `.env` и при необходимости соберут JAR-файлы. +Оба скрипта автоматически загружают переменные окружения из корневого файла `.env` и собирают JAR-файлы, если они отсутствуют. -> **Примечание:** Если вы хотите сначала вручную собрать все модули перед запуском: +> **Примечание:** Если хотите собрать все модули вручную перед запуском: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -350,91 +346,91 @@ cd ..; .\stop-all.ps1 # Все модули Приложение предоставляет веб-интерфейс для загрузки документов и задавания вопросов. -Интерфейс приложения RAG +RAG Application Interface -*Этот скриншот показывает интерфейс приложения RAG, где вы загружаете документы и задаете вопросы.* +*Этот скриншот показывает интерфейс приложения RAG, где вы загружаете документы и задаёте вопросы.* ### Загрузка документа -Начните с загрузки документа — для тестирования лучше всего подходят файлы TXT. В этой директории находится `sample-document.txt`, который содержит информацию о возможностях LangChain4j, реализации RAG и лучших практиках — идеально подходит для тестирования системы. +Начните с загрузки документа — для тестирования лучше всего подходят TXT-файлы. В этой директории есть `sample-document.txt`, содержащий информацию о функциях LangChain4j, реализации RAG и лучших практиках — идеально для тестирования системы. -Система обрабатывает ваш документ, разбивает его на фрагменты и создаёт эмбеддинги для каждого фрагмента. Это происходит автоматически при загрузке. +Система обрабатывает ваш документ, разбивает его на куски и создаёт эмбеддинги для каждого куска. Это происходит автоматически при загрузке. -### Задайте вопросы +### Задавайте вопросы -Теперь задайте конкретные вопросы по содержимому документа. Попробуйте что-то фактическое, что явно указано в документе. Система ищет релевантные фрагменты, включает их в промпт и генерирует ответ. +Теперь задавайте конкретные вопросы о содержании документа. Попробуйте что-то фактическое, что чётко указано в документе. Система ищет релевантные куски, включает их в запрос и генерирует ответ. -### Проверьте источники +### Проверяйте ссылки на источники -Обратите внимание, что каждый ответ содержит ссылки на источники с оценками схожести. Эти оценки (от 0 до 1) показывают, насколько каждый фрагмент релевантен вашему вопросу. Чем выше оценка, тем лучше совпадение. Это позволяет вам проверить ответ по исходным материалам. +Обратите внимание, что каждый ответ включает ссылки на источники с оценками похожести. Эти оценки (от 0 до 1) показывают, насколько каждый кусок был релевантен вашему вопросу. Более высокие оценки означают лучшее совпадение. Это позволяет проверить ответ относительно исходного материала. -Результаты запроса RAG +RAG Query Results -*Этот скриншот показывает результаты запроса с сгенерированным ответом, ссылками на источники и оценками релевантности для каждого найденного фрагмента.* +*Этот скриншот показывает результаты запроса с сгенерированным ответом, ссылками на источники и оценками релевантности для каждого извлечённого куска.* ### Экспериментируйте с вопросами Пробуйте разные типы вопросов: -- Конкретные факты: «Какова основная тема?» -- Сравнения: «В чем разница между X и Y?» -- Краткие содержания: «Подытожьте ключевые моменты по Z» +- Конкретные факты: "Какова основная тема?" +- Сравнения: "В чём разница между X и Y?" +- Итоги: "Суммируй ключевые моменты о Z" -Смотрите, как меняются оценки релевантности в зависимости от того, насколько хорошо ваш вопрос соответствует содержимому документа. +Наблюдайте, как меняются оценки релевантности в зависимости от того, насколько ваш вопрос соответствует содержанию документа. -## Основные концепции +## Ключевые концепции -### Стратегия разбиения на фрагменты +### Стратегия разбиения на куски -Документы разбиваются на фрагменты длиной 300 токенов с перекрытием в 30 токенов. Такой баланс обеспечивает достаточный контекст в каждом фрагменте, сохраняя их достаточно маленькими, чтобы уместить несколько фрагментов в один промпт. +Документы разбиваются на куски по 300 токенов с перекрытием в 30 токенов. Этот баланс обеспечивает достаточно контекста для каждого куска, при этом размер остаётся достаточно малым, чтобы вместить несколько кусков в запрос. -### Оценки схожести +### Оценки похожести -Каждый извлечённый фрагмент имеет оценку схожести от 0 до 1, которая указывает, насколько близко он соответствует вопросу пользователя. Диаграмма ниже визуализирует диапазоны оценок и как система использует их для фильтрации результатов: +Каждый извлечённый кусок имеет оценку похожести от 0 до 1, которая указывает, насколько он близок к вопросу пользователя. Диаграмма ниже визуализирует диапазоны оценок и как система использует их для фильтрации результатов: -Оценки схожести +Similarity Scores -*Эта диаграмма показывает диапазон оценок от 0 до 1 с минимальным порогом 0.5, который фильтрует нерелевантные фрагменты.* +*Эта диаграмма показывает диапазоны оценок от 0 до 1 с минимальным порогом 0.5, который фильтрует нерелевантные куски.* Оценки варьируются от 0 до 1: -- 0.7-1.0: Высокая релевантность, точное совпадение +- 0.7-1.0: Очень релевантно, точное совпадение - 0.5-0.7: Релевантно, хороший контекст -- Ниже 0.5: Отфильтровано, слишком разные +- Ниже 0.5: Отфильтровано, слишком несхоже -Система извлекает только фрагменты выше минимального порога для обеспечения качества. +Система извлекает только куски выше минимального порога для обеспечения качества. -Эмбеддинги хорошо работают, когда смысловые кластеры чётко разграничены, но у них есть слабые места. На диаграмме ниже показаны распространённые ошибки — слишком большие фрагменты дают мутные векторы, слишком маленькие не содержат контекста, неоднозначные термины указывают на несколько кластеров, а точный поиск по совпадению (ID, номера деталей) не работает с эмбеддингами вообще: +Эмбеддинги хорошо работают, когда смысл чётко группируется, но у них есть «слепые зоны». Диаграмма ниже показывает типичные ошибки — слишком большие куски создают слишком размытые векторы, слишком маленькие — лишены контекста, неоднозначные термины указывают на несколько кластеров, а точные совпадения (ID, номера деталей) вообще не работают с эмбеддингами: -Типичные ошибки эмбеддингов +Embedding Failure Modes -*Эта диаграмма показывает типичные ошибки эмбеддингов: слишком большие фрагменты, слишком маленькие, неоднозначные термины с несколькими кластерами и точный поиск по совпадению вроде ID.* +*Эта диаграмма показывает типичные ошибки эмбеддингов: куски слишком большие, куски слишком маленькие, неоднозначные термины указывают на несколько кластеров и точные совпадения вроде ID.* ### Хранение в памяти -В этом модуле используется хранение в памяти для простоты. При перезапуске приложения загруженные документы теряются. В продуктивных системах используют постоянные векторные базы данных, такие как Qdrant или Azure AI Search. +Для простоты этот модуль использует хранение в памяти. При перезапуске приложения загруженные документы теряются. В продуктивных системах применяются персистентные векторные базы данных, такие как Qdrant или Azure AI Search. ### Управление контекстным окном -Каждая модель имеет максимальный размер контекстного окна. Нельзя включить все фрагменты из большого документа. Система извлекает топ N наиболее релевантных фрагментов (по умолчанию 5), чтобы оставаться в пределах лимита, при этом обеспечивая достаточный контекст для точных ответов. +Каждая модель имеет максимальный размер контекстного окна. Нельзя включить все куски большого документа. Система выбирает топ N самых релевантных кусков (по умолчанию 5), чтобы уложиться в лимиты и при этом обеспечить достаточный контекст для точных ответов. -## Когда RAG важен +## Когда RAG имеет значение -RAG не всегда лучший подход. Ниже представлен гид для принятия решения, когда RAG добавляет ценность, а когда проще использовать включение контента напрямую в промпт или полагаться на встроенные знания модели: +RAG не всегда является правильным подходом. Руководство по принятию решения ниже помогает определить, когда RAG добавляет ценность, а когда достаточно более простых подходов — например, включение контента напрямую в запрос или использование встроенных знаний модели: -Когда использовать RAG +When to Use RAG -*Эта диаграмма показывает руководство по решению, когда RAG добавляет ценность, а когда более простые подходы достаточны.* +*Эта диаграмма показывает руководство по решению, когда RAG добавляет ценность, а когда достаточно более простых методов.* ## Следующие шаги -**Следующий модуль:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Следующий модуль:** [04-tools - AI агенты с инструментами](../04-tools/README.md) --- -**Навигация:** [← Предыдущий: Модуль 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Назад к главному](../README.md) | [Следующий: Модуль 04 - Tools →](../04-tools/README.md) +**Навигация:** [← Предыдущий: Модуль 02 - Построение запросов](../02-prompt-engineering/README.md) | [Вернуться к оглавлению](../README.md) | [Следующий: Модуль 04 - Инструменты →](../04-tools/README.md) --- -**Отказ от ответственности**: -Этот документ был переведен с помощью сервиса автоматического перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия обеспечить точность перевода, пожалуйста, имейте в виду, что автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обращаться к профессиональному переводу, выполненному человеком. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода. +**Отказ от ответственности**: +Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода. \ No newline at end of file diff --git a/translations/ru/04-tools/README.md b/translations/ru/04-tools/README.md index b5b5d460c..8dcc34bed 100644 --- a/translations/ru/04-tools/README.md +++ b/translations/ru/04-tools/README.md @@ -2,83 +2,83 @@ ## Содержание -- [Видеообзор](../../../04-tools) -- [Что вы узнаете](../../../04-tools) -- [Требования](../../../04-tools) -- [Понимание AI-агентов с инструментами](../../../04-tools) -- [Как работает вызов инструментов](../../../04-tools) - - [Определения инструментов](../../../04-tools) - - [Принятие решений](../../../04-tools) - - [Выполнение](../../../04-tools) - - [Генерация ответа](../../../04-tools) - - [Архитектура: автоматическая проводка Spring Boot](../../../04-tools) -- [Цепочка инструментов](../../../04-tools) -- [Запуск приложения](../../../04-tools) -- [Использование приложения](../../../04-tools) - - [Попробуйте простое использование инструмента](../../../04-tools) - - [Проверьте цепочку инструментов](../../../04-tools) - - [Просмотрите ход разговора](../../../04-tools) - - [Экспериментируйте с разными запросами](../../../04-tools) -- [Ключевые концепции](../../../04-tools) - - [Паттерн ReAct (Размышление и Действие)](../../../04-tools) - - [Важность описаний инструментов](../../../04-tools) - - [Управление сессией](../../../04-tools) - - [Обработка ошибок](../../../04-tools) -- [Доступные инструменты](../../../04-tools) -- [Когда использовать агентов с инструментами](../../../04-tools) -- [Инструменты против RAG](../../../04-tools) -- [Следующие шаги](../../../04-tools) +- [Видеообзор](#видеообзор) +- [Чему вы научитесь](#чему-вы-научитесь) +- [Требования](#требования) +- [Понимание AI-агентов с инструментами](#понимание-ai-агентов-с-инструментами) +- [Как работает вызов инструмента](#как-работает-вызов-инструмента) + - [Определения инструментов](#определения-инструментов) + - [Принятие решений](#принятие-решений) + - [Выполнение](#выполнение) + - [Генерация ответа](#генерация-ответа) + - [Архитектура: Автоматическое связывание Spring Boot](#архитектура-автоматическое-связывание-spring-boot) +- [Цепочки инструментов](#цепочки-инструментов) +- [Запуск приложения](#запуск-приложения) +- [Использование приложения](#использование-приложения) + - [Попробуйте простой вызов инструмента](#попробуйте-простое-использование-инструментов) + - [Проверьте цепочку инструментов](#проверьте-цепочку-инструментов) + - [Посмотрите ход беседы](#просмотрите-ход-разговора) + - [Экспериментируйте с разными запросами](#экспериментируйте-с-разными-запросами) +- [Ключевые концепции](#основные-понятия) + - [Шаблон ReAct (Размышления и действия)](#паттерн-react-рассуждение-и-действие) + - [Важность описаний инструментов](#значение-описаний-инструментов) + - [Управление сессиями](#управление-сессиями) + - [Обработка ошибок](#обработка-ошибок) +- [Доступные инструменты](#доступные-инструменты) +- [Когда использовать агентов на основе инструментов](#когда-использовать-агентов-с-инструментами) +- [Инструменты vs RAG](#инструменты-vs-rag) +- [Следующие шаги](#следующие-шаги) ## Видеообзор -Смотрите этот живой сеанс, в котором объясняется, как начать работу с этим модулем: +Смотрите это живое занятие, в котором объясняется, как начать работу с этим модулем: AI Agents with Tools and MCP - Live Session -## Что вы узнаете +## Чему вы научитесь -До сих пор вы научились вести диалоги с AI, эффективно структурировать подсказки и основывать ответы на ваших документах. Но есть фундаментальное ограничение: языковые модели могут только генерировать текст. Они не могут проверить погоду, выполнять вычисления, запрашивать базы данных или взаимодействовать с внешними системами. +До сих пор вы узнали, как вести беседы с ИИ, эффективно структурировать подсказки и основываться на ваших документах в ответах. Но есть фундаментальное ограничение: языковые модели могут только генерировать текст. Они не могут проверить погоду, выполнять вычисления, запрашивать базы данных или взаимодействовать с внешними системами. -Инструменты меняют это. Давая модели доступ к функциям, которые она может вызывать, вы превращаете её из генератора текста в агента, который может выполнять действия. Модель решает, когда ей нужен инструмент, какой инструмент использовать и какие параметры передать. Ваш код выполняет функцию и возвращает результат. Модель включает этот результат в свой ответ. +Инструменты это меняют. Давая модели доступ к функциям, которые она может вызывать, вы преобразуете её из генератора текста в агента, способного предпринимать действия. Модель решает, когда ей нужен инструмент, какой инструмент использовать и какие параметры передать. Ваш код выполняет функцию и возвращает результат. Модель включает этот результат в свой ответ. ## Требования -- Завершённый [Модуль 01 - Введение](../01-introduction/README.md) (развёрнутые ресурсы Azure OpenAI) -- Рекомендуется завершить предыдущие модули (в этом модуле есть ссылки на [концепции RAG из Модуля 03](../03-rag/README.md) в сравнении Инструменты vs RAG) -- Файл `.env` в корневом каталоге с учётными данными Azure (создаётся командой `azd up` в Модуле 01) +- Завершён [Модуль 01 - Введение](../01-introduction/README.md) (развернуты ресурсы Azure OpenAI) +- Рекомендуется пройти предыдущие модули (в этом модуле есть ссылки на [концепции RAG из Модуля 03](../03-rag/README.md) в сравнении Инструменты vs RAG) +- Файл `.env` в корневой директории с учётными данными Azure (создаётся командой `azd up` в Модуле 01) -> **Примечание:** Если Модуль 01 не завершён, сначала следуйте инструкциям по развёртыванию там. +> **Примечание:** Если вы не завершили Модуль 01, сначала выполните инструкции по развертыванию там. ## Понимание AI-агентов с инструментами -> **📝 Примечание:** Термин "агенты" в этом модуле относится к AI-ассистентам с расширенными возможностями вызова инструментов. Это отличается от паттернов **Agentic AI** (автономных агентов с планированием, памятью и многошаговым рассуждением), которые мы рассмотрим в [Модуле 05: MCP](../05-mcp/README.md). +> **📝 Примечание:** Термин «агенты» в этом модуле относится к AI-ассистентам, расширенным возможностями вызова инструментов. Это отличается от шаблонов **Agentic AI** (автономные агенты с планированием, памятью и многоэтапным рассуждением), которые мы рассмотрим в [Модуле 05: MCP](../05-mcp/README.md). -Без инструментов языковая модель может только генерировать текст на основе своих обучающих данных. Спросите у неё, какая сейчас погода, — она будет только угадывать. Дайте ей инструменты, и она сможет вызвать API погоды, выполнить вычисления или запросить базу данных — а затем использовать эти реальные данные в своём ответе. +Без инструментов языковая модель может только генерировать текст по своим обучающим данным. Спросите у неё текущую погоду — и она будет угадывать. Дайте ей инструменты, и она сможет вызвать API погоды, выполнить вычисления или запросить базу данных — затем вплетёт эти реальные результаты в ответ. -Без инструментов vs С инструментами +Без инструментов против с инструментами -*Без инструментов модель только угадывает — с инструментами она может вызывать API, выполнять вычисления и возвращать актуальные данные.* +*Без инструментов модель может только угадывать — с инструментами она может вызывать API, выполнять вычисления и возвращать данные в реальном времени.* -AI-агент с инструментами следует паттерну **Reasoning and Acting (ReAct)**. Модель не просто отвечает — она размышляет о том, что ей нужно, действует, вызывая инструмент, наблюдает за результатом, а затем решает, действовать дальше или дать итоговый ответ: +AI-агент с инструментами следует шаблону **Размышления и действий (ReAct)**. Модель не просто отвечает — она размышляет о том, что нужно, действует, вызывая инструмент, наблюдает результат, а затем решает, нужно ли действовать снова или выдать окончательный ответ: -1. **Размышление** — агент анализирует вопрос пользователя и определяет, какая информация ему нужна -2. **Действие** — агент выбирает нужный инструмент, генерирует корректные параметры и вызывает его -3. **Наблюдение** — агент получает результаты работы инструмента и оценивает их -4. **Повтор или ответ** — если нужно больше данных, агент повторяет цикл; иначе составляет ответ на естественном языке +1. **Размышляет** — агент анализирует вопрос пользователя и определяет, какую информацию ему нужно получить +2. **Действует** — агент выбирает подходящий инструмент, формирует правильные параметры и вызывает его +3. **Наблюдает** — агент получает результат работы инструмента и оценивает его +4. **Повторяет или отвечает** — если нужно больше данных, агент возвращается к началу; иначе формирует ответ на естественном языке -Паттерн ReAct +Шаблон ReAct -*Цикл ReAct — агент размышляет, что сделать, действует через вызов инструмента, наблюдает результат и повторяет, пока не сможет дать итоговый ответ.* +*Цикл ReAct — агент размышляет о том, что делать, действует, вызывая инструмент, наблюдает результат и повторяет цикл, пока не сможет выдать окончательный ответ.* -Это происходит автоматически. Вы определяете инструменты и их описания. Модель принимает решение, когда и как ими пользоваться. +Это происходит автоматически. Вы определяете инструменты и их описания. Модель сама принимает решения, когда и как их использовать. -## Как работает вызов инструментов +## Как работает вызов инструмента ### Определения инструментов [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Вы определяете функции с чёткими описаниями и спецификациями параметров. Модель видит эти описания в системном подсказе и понимает, что делает каждый инструмент. +Вы определяете функции с понятными описаниями и спецификациями параметров. Модель видит эти описания в системном подсказе и понимает, для чего нужен каждый инструмент. ```java @Component @@ -96,139 +96,139 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Ассистент автоматически подключается Spring Boot с: -// - Bean ChatModel -// - Все методы @Tool из классов @Component +// Ассистент автоматически подключается с помощью Spring Boot к: +// - bean ChatModel +// - Все методы @Tool из классов с @Component // - ChatMemoryProvider для управления сессиями ``` + +Ниже диаграмма разбирает каждую аннотацию и показывает, как каждый элемент помогает ИИ понять, когда вызывать инструмент и какие аргументы передавать: -Диаграмма ниже разбирает каждую аннотацию и показывает, как каждая часть помогает AI понимать, когда вызывать инструмент и какие аргументы передавать: +Анатомия определения инструмента -Анатомия определений инструментов +*Анатомия определения инструмента — @Tool сообщает ИИ, когда его использовать, @P описывает каждый параметр, а @AiService объединяет всё вместе при запуске.* -*Анатомия определения инструмента — @Tool сообщает AI, когда использовать инструмент, @P описывает каждый параметр, а @AiService связывает всё вместе во время запуска.* - -> **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) и спросите: -> - "Как интегрировать реальный API погоды, например OpenWeatherMap, вместо тестовых данных?" -> - "Что делает хорошее описание инструмента, которое помогает AI использовать его правильно?" -> - "Как обрабатывать ошибки API и ограничения по количеству вызовов в реализации инструментов?" +> **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) и задайте вопросы: +> - «Как интегрировать реальный API погоды, например OpenWeatherMap, вместо мок-данных?» +> - «Что делает хорошее описание инструмента, помогающее ИИ правильно его использовать?» +> - «Как обрабатывать ошибки API и ограничения скорости в реализации инструментов?» ### Принятие решений -Когда пользователь спрашивает: "Какая погода в Сиэтле?", модель не выбирает инструмент случайно. Она сравнивает намерение пользователя с каждым описанием инструмента, оценивает их релевантность и выбирает лучший вариант. Затем генерирует структурированный вызов функции с нужными параметрами — в данном случае, устанавливая `location` в значение `"Seattle"`. +Когда пользователь спрашивает «Какая погода в Сиэтле?», модель не выбирает инструмент случайно. Она сравнивает намерение пользователя с описаниями всех доступных инструментов, оценивает релевантность каждого и выбирает лучший вариант. Затем генерирует структурированный вызов функции с правильными параметрами — в данном случае устанавливая `location` в `"Seattle"`. -Если ни один инструмент не соответствует запросу, модель отвечает из собственных знаний. Если подходит несколько инструментов, выбирает самый специфичный. +Если ни один инструмент не подходит для запроса пользователя, модель отвечает на основе собственных знаний. Если подходит несколько, выбирается самый конкретный. -Как AI выбирает инструмент +Как ИИ решает, какой инструмент использовать -*Модель оценивает каждый доступный инструмент относительно намерения пользователя и выбирает лучший — поэтому важно писать чёткие и конкретные описания.* +*Модель оценивает каждый доступный инструмент относительно запроса пользователя и выбирает лучший — поэтому важно писать чёткие и конкретные описания инструментов.* ### Выполнение [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot автоматически проводит внедрение зависимостей для декларативного интерфейса `@AiService` с зарегистрированными инструментами, а LangChain4j выполняет вызовы инструментов автоматически. За кулисами вызов инструмента проходит через шесть этапов — от вопроса пользователя на естественном языке до ответа на естественном языке: +Spring Boot автоматически связывает декларативный интерфейс `@AiService` со всеми зарегистрированными инструментами, и LangChain4j автоматически выполняет вызовы инструментов. За кулисами полный вызов инструмента проходит через шесть этапов — от вопроса пользователя на естественном языке до ответа на естественном языке: Поток вызова инструмента -*Полный ход процесса — пользователь задаёт вопрос, модель выбирает инструмент, LangChain4j его выполняет, и модель включает результат в естественный ответ.* +*Полный процесс — пользователь задаёт вопрос, модель выбирает инструмент, LangChain4j его выполняет, а модель включает результат в естественный ответ.* -Если вы запускали [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) в Модуле 00, то уже видели этот паттерн — инструменты `Calculator` вызывались так же. Диаграмма последовательности ниже показывает, что именно происходило во время того демо: +За сценой `AiServices` выполняет тот же цикл вызова инструмента для любого инструмента — здесь на примере простого калькулятора. Диаграмма последовательности ниже показывает, что происходит под капотом: -Диаграмма последовательности вызова инструмента +Диаграмма последовательности вызова инструментов -*Цикл вызова инструмента из демонстрации быстрого старта — `AiServices` отправляет ваше сообщение и схемы инструментов LLM, LLM отвечает вызовом функции типа `add(42, 58)`, LangChain4j локально выполняет метод `Calculator`, и возвращает результат для итогового ответа.* +*Цикл вызова инструментов — `AiServices` отправляет ваше сообщение и схемы инструментов LLM, LLM отвечает вызовом функции, например `add(42, 58)`, LangChain4j выполняет метод `Calculator` локально и передаёт результат обратно для окончательного ответа.* -> **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) и спросите: -> - "Как работает паттерн ReAct и почему он эффективен для AI-агентов?" -> - "Как агент решает, какой инструмент использовать и в каком порядке?" -> - "Что происходит при сбое выполнения инструмента — как обработать ошибки надёжно?" +> **🤖 Попробуйте с [GitHub Copilot](https://github.com/features/copilot) Chat:** Откройте [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) и задайте вопросы: +> - «Как работает шаблон ReAct и почему он эффективен для AI-агентов?» +> - «Как агент выбирает, какой инструмент использовать и в каком порядке?» +> - «Что происходит, если выполнение инструмента не удаётся — как устойчиво обрабатывать ошибки?» ### Генерация ответа -Модель получает данные о погоде и форматирует их в ответ на естественном языке для пользователя. +Модель получает данные о погоде и оформляет их в ответ на естественном языке для пользователя. -### Архитектура: автоматическая проводка Spring Boot +### Архитектура: Автоматическое связывание Spring Boot -Этот модуль использует интеграцию LangChain4j со Spring Boot и декларативные интерфейсы `@AiService`. При запуске Spring Boot обнаруживает каждый `@Component` с методами `@Tool`, ваш бин `ChatModel` и `ChatMemoryProvider` — затем подключает их вместе в единый интерфейс `Assistant` без ручного кода. +В этом модуле используется интеграция LangChain4j со Spring Boot и декларативными интерфейсами `@AiService`. При запуске Spring Boot автоматически обнаруживает каждый `@Component`, содержащий методы с `@Tool`, ваш бин `ChatModel` и `ChatMemoryProvider` — затем объединяет их все в один интерфейс `Assistant` без шаблонного кода. -Архитектура автоматической проводки Spring Boot +Архитектура автоматического связывания Spring Boot -*Интерфейс @AiService связывает ChatModel, компоненты инструментов и провайдера памяти — Spring Boot управляет всей проводкой автоматически.* +*Интерфейс @AiService связывает ChatModel, компоненты инструментов и провайдера памяти — Spring Boot автоматизирует всю проводку.* -Ниже полный жизненный цикл запроса в виде диаграммы последовательности — от HTTP-запроса через контроллер, сервис и автоинжектируемый прокси до выполнения инструмента и обратно: +Ниже показан полный жизненный цикл запроса в виде диаграммы последовательности — от HTTP-запроса через контроллер, сервис и авто-связанное прокси до выполнения инструмента и обратно: -Диаграмма последовательности вызова инструмента в Spring Boot +Диаграмма последовательности вызова инструментов в Spring Boot -*Полный жизненный цикл запроса Spring Boot — HTTP-запрос проходит через контроллер и сервис к автоинжектируемому прокси Assistant, который автоматически оркестрирует LLM и вызовы инструментов.* +*Полный жизненный цикл запроса Spring Boot — HTTP-запрос проходит через контроллер и сервис к авто-связанному прокси Assistant, который автоматически управляет LLM и вызовами инструментов.* -Ключевые преимущества такого подхода: +Ключевые преимущества подхода: -- **Автоматическая проводка Spring Boot** — ChatModel и инструменты внедряются автоматически -- **Паттерн @MemoryId** — Автоматическое управление памятью на основе сессий -- **Один экземпляр** — Assistant создаётся один раз и повторно используется для лучшей производительности -- **Типобезопасное выполнение** — Java-методы вызываются напрямую с преобразованием типов -- **Многоступенчатая оркестрация** — автоматическая обработка цепочек инструментов -- **Отсутствие шаблонного кода** — нет ручных вызовов `AiServices.builder()` или хранилища памяти в HashMap +- **Автоматическое связывание Spring Boot** — автоматическая инъекция ChatModel и инструментов +- **Шаблон @MemoryId** — автоматическое управление памятью на основе сессии +- **Один экземпляр** — Assistant создаётся один раз и переиспользуется для лучшей производительности +- **Типобезопасное выполнение** — вызов Java-методов напрямую с конвертацией типов +- **Многоступенчатое оркестрирование** — автоматическая обработка цепочек инструментов +- **Отсутствие шаблонного кода** — без ручных вызовов `AiServices.builder()` или использования HashMap для памяти -Альтернативные подходы (ручной `AiServices.builder()`) требуют больше кода и не дают преимуществ интеграции Spring Boot. +Альтернативные подходы (ручное `AiServices.builder()`) требуют больше кода и не обеспечивают преимуществ интеграции со Spring Boot. -## Цепочка инструментов +## Цепочки инструментов -**Цепочка инструментов** — настоящая сила агентов с инструментами проявляется, когда на один вопрос нужно использовать несколько инструментов. Спросите "Какая погода в Сиэтле в Фаренгейтах?" — агент автоматически связывает два инструмента: сначала вызывает `getCurrentWeather`, чтобы получить температуру в Цельсиях, затем передаёт это значение в `celsiusToFahrenheit` для конвертации — всё в одном разговорном шаге. +**Цепочки инструментов** — реальная сила агентов на основе инструментов проявляется, когда для одного вопроса требуются несколько инструментов. Спросите «Какая погода в Сиэтле по Фаренгейту?» — агент автоматически свяжет два инструмента: сначала вызовет `getCurrentWeather` для получения температуры в Цельсиях, потом передаст это значение в `celsiusToFahrenheit` для конвертации — всё в одном ходе беседы. Пример цепочки инструментов -*Цепочка инструментов в действии — агент сначала вызывает getCurrentWeather, затем передаёт результат в celsiusToFahrenheit и выдаёт комбинированный ответ.* +*Цепочка инструментов в действии — агент сначала вызывает getCurrentWeather, затем передаёт результат в Цельсиях в celsiusToFahrenheit и выдаёт объединённый ответ.* -**Грациозные отказы** — запросите погоду в городе, которого нет в тестовых данных. Инструмент вернёт сообщение об ошибке, а AI пояснит, что помочь не может, вместо краха приложения. Инструменты терпят ошибки безопасно. Диаграмма ниже сравнивает два подхода — с правильной обработкой ошибок агент ловит исключение и отвечает полезно, а без неё приложение полностью падает: +**Грациозная обработка неудач** — запросите погоду для города, которого нет в мок-данных. Инструмент вернёт сообщение об ошибке, и ИИ объяснит, что помочь не может, а не аварийно завершит работу. Инструменты отказывают безопасно. Диаграмма ниже сопоставляет оба подхода: с правильной обработкой ошибок агент ловит исключение и отвечает полезно, без неё всё приложение падает: Поток обработки ошибок -*Когда инструмент не удаётся, агент ловит ошибку и отвечает с полезным пояснением вместо краха.* +*Когда инструмент не удаётся, агент ловит ошибку и отвечает с полезным объяснением вместо сбоя.* -Это происходит в одном разговорном шаге. Агент автономно оркеструет множественные вызовы инструментов. +Это происходит за один ход беседы. Агент самостоятельно оркестрирует несколько вызовов инструментов. ## Запуск приложения -**Проверьте развёртывание:** +**Проверьте развертывание:** -Убедитесь, что файл `.env` существует в корневом каталоге с учётными данными Azure (созданный во время Модуля 01). Запустите из каталога модуля (`04-tools/`): +Убедитесь, что файл `.env` существует в корневой директории с данными Azure (создаётся в Модуле 01). Выполните это из каталога модуля (`04-tools/`): -**Bash:** +**Bash:** ```bash cat ../.env # Должен показывать AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell -Get-Content ..\.env # Должен показать AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Должен показывать AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` + +**Запустите приложение:** -**Запуск приложения:** - -> **Примечание:** Если вы уже запускали все приложения с помощью `./start-all.sh` из корня (как описано в Модуле 01), этот модуль уже работает на порту 8084. Вы можете пропустить команды запуска ниже и перейти сразу к http://localhost:8084. +> **Примечание:** Если вы уже запускали все приложения с помощью `./start-all.sh` из корневой директории (как описано в Модуле 01), этот модуль уже запущен на порту 8084. Вы можете пропустить команды запуска ниже и сразу перейти по адресу http://localhost:8084. -**Вариант 1: Использование Spring Boot Dashboard (Рекомендуется для пользователей VS Code)** +**Вариант 1: Использование Spring Boot Dashboard (рекомендуется для пользователей VS Code)** -Dev-контейнер включает расширение Spring Boot Dashboard, которое предоставляет визуальный интерфейс для управления всеми приложениями Spring Boot. Его можно найти на панели активности слева в VS Code (иконка Spring Boot). +Контейнер разработки включает расширение Spring Boot Dashboard, которое предоставляет визуальный интерфейс для управления всеми Spring Boot приложениями. Вы найдёте его на панели активности слева в VS Code (иконка Spring Boot). -В Spring Boot Dashboard вы можете: -- Просматривать все доступные приложения Spring Boot в рабочем пространстве -- Запускать / останавливать приложения одним кликом -- Смотреть логи приложений в реальном времени -- Мониторить состояние приложений -Просто нажмите кнопку воспроизведения рядом с «tools», чтобы запустить этот модуль, или запустите все модули одновременно. +Из Spring Boot Dashboard вы можете: +- Просматривать все доступные Spring Boot приложения в рабочем пространстве +- Запускать/останавливать приложения одним кликом +- Смотреть логи приложений в реальном времени +- Следить за состоянием приложений -Вот как выглядит панель Spring Boot Dashboard в VS Code: +Просто нажмите кнопку воспроизведения рядом с "tools" для запуска этого модуля или запустите сразу все модули. -Панель Spring Boot Dashboard +Вот как выглядит Spring Boot Dashboard в VS Code: +Панель управления Spring Boot -*Панель Spring Boot Dashboard в VS Code — запуск, остановка и мониторинг всех модулей из одного места* +*Панель управления Spring Boot в VS Code — запуск, остановка и мониторинг всех модулей из одного места* **Вариант 2: Использование shell-скриптов** -Запуск всех веб-приложений (модули 01-04): +Запустите все веб-приложения (модули 01-04): **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Оба скрипта автоматически загружают переменные окружения из корневого файла `.env` и соберут JAR-файлы, если они отсутствуют. +Оба скрипта автоматически загружают переменные окружения из корневого файла `.env` и соберут JAR-файлы, если они еще не существуют. -> **Примечание:** Если вы предпочитаете вручную собрать все модули перед запуском: +> **Примечание:** Если вы предпочитаете собрать все модули вручную перед запуском: > > **Bash:** > ```bash @@ -274,7 +274,7 @@ cd 04-tools Откройте http://localhost:8084 в вашем браузере. -**Чтобы остановить:** +**Для остановки:** **Bash:** ```bash @@ -292,84 +292,84 @@ cd ..; .\stop-all.ps1 # Все модули ## Использование приложения -Приложение предоставляет веб-интерфейс, где вы можете взаимодействовать с AI-агентом, который имеет доступ к инструментам погоды и преобразования температур. Вот как выглядит интерфейс — он включает примеры для быстрого старта и чат-панель для отправки запросов: +Приложение предоставляет веб-интерфейс, где вы можете взаимодействовать с AI-агентом, имеющим доступ к инструментам погоды и преобразования температуры. Вот как выглядит интерфейс — он включает быстрые примеры и панель чата для отправки запросов: Интерфейс инструментов AI-агента -*Интерфейс инструментов AI-агента — быстрые примеры и чат для взаимодействия с инструментами* +*Интерфейс инструментов AI-агента – быстрые примеры и чат для взаимодействия с инструментами* ### Попробуйте простое использование инструментов -Начните с простого запроса: «Преобразуй 100 градусов по Фаренгейту в Цельсий». Агент понимает, что нужно использовать инструмент преобразования температуры, вызывает его с правильными параметрами и возвращает результат. Обратите внимание, насколько это естественно — вы не указывали, какой инструмент использовать и как его вызывать. +Начните с простого запроса: «Преобразуй 100 градусов по Фаренгейту в Цельсий». Агент понимает, что нужно использовать инструмент преобразования температуры, вызывает его с нужными параметрами и возвращает результат. Обратите внимание, насколько естественно это выглядит — вы не указывали, какой именно инструмент использовать или как его вызвать. -### Проверьте цепочку использования инструментов +### Проверьте цепочку инструментов -Теперь попробуйте что-то более сложное: «Какая погода в Сиэтле и преобразуй ее в Фаренгейты?» Посмотрите, как агент выполняет это по шагам. Сначала он получает погоду (в Цельсиях), понимает, что нужно преобразовать в Фаренгейты, вызывает инструмент преобразования и объединяет оба результата в один ответ. +Теперь попробуйте что-то сложнее: «Какая погода в Сиэтле и переведите её в Фаренгейт?» Смотрите, как агент выполняет это по шагам. Он сначала получает погоду (которая возвращается в Цельсиях), понимает, что нужно конвертировать в Фаренгейт, вызывает инструмент конвертации и объединяет оба результата в одном ответе. -### Посмотрите поток разговора +### Просмотрите ход разговора -Интерфейс чата сохраняет историю беседы, позволяя вам вести многотуровые взаимодействия. Вы видите все предыдущие запросы и ответы, что облегчает отслеживание разговора и понимание, как агент строит контекст на протяжении нескольких обменов. +Интерфейс чата сохраняет историю разговоров, позволяя вести многошаговое взаимодействие. Вы можете видеть все предыдущие запросы и ответы, что облегчает отслеживание беседы и понимание того, как агент строит контекст на протяжении нескольких обменов. -Разговор с множественными вызовами инструментов +Разговор с несколькими вызовами инструментов -*Многотуровый разговор, показывающий простые преобразования, запросы погоды и цепочку инструментов* +*Многошаговый разговор, демонстрирующий простые преобразования, запросы погоды и цепочку инструментов* -### Экспериментируйте с различными запросами +### Экспериментируйте с разными запросами -Попробуйте разные варианты: +Пробуйте различные комбинации: - Запросы погоды: «Какая погода в Токио?» -- Преобразования температуры: «Что такое 25°C в Кельвинах?» -- Сложные запросы: «Проверь погоду в Париже и скажи, выше ли там 20°C» +- Преобразования температуры: «Сколько будет 25°C в Кельвинах?» +- Сложные запросы: «Проверь погоду в Париже и скажи, выше ли 20°C» Обратите внимание, как агент интерпретирует естественный язык и сопоставляет его с соответствующими вызовами инструментов. -## Ключевые концепции +## Основные понятия -### Паттерн ReAct (рассуждение и действие) +### Паттерн ReAct (Рассуждение и действие) -Агент чередует рассуждения (решение, что делать) и действия (использование инструментов). Этот паттерн позволяет автономно решать задачи, а не просто отвечать на инструкции. +Агент чередует рассуждение (решение, что делать) и действие (использование инструментов). Этот паттерн позволяет автономно решать задачи, а не просто отвечать на инструкции. -### Описания инструментов имеют значение +### Значение описаний инструментов -Качество описаний ваших инструментов напрямую влияет на то, насколько хорошо агент их использует. Ясные, конкретные описания помогают модели понять, когда и как вызывать каждый инструмент. +Качество описаний ваших инструментов напрямую влияет на то, насколько хорошо агент их использует. Ясные и конкретные описания помогают модели понимать, когда и как вызывать каждый инструмент. ### Управление сессиями -Аннотация `@MemoryId` позволяет автоматически управлять памятью на основе сессий. Каждому идентификатору сессии соответствует отдельный экземпляр `ChatMemory`, которым управляет bean `ChatMemoryProvider`, что позволяет нескольким пользователям одновременно взаимодействовать с агентом без смешивания их разговоров. Следующая диаграмма показывает, как нескольким пользователям назначаются изолированные хранилища памяти в зависимости от их идентификаторов сессий: +Аннотация `@MemoryId` включает автоматическое управление памятью на основе сессий. Каждому идентификатору сессии соответствует собственный экземпляр `ChatMemory`, управляемый бином `ChatMemoryProvider`, так что несколько пользователей могут одновременно взаимодействовать с агентом, не смешивая свои разговоры. Следующая диаграмма показывает, как пользователей направляют в изолированные хранилища памяти на основе их идентификаторов сессий: Управление сессиями с @MemoryId -*Каждому идентификатору сессии соответствует изолированная история разговора — пользователи не видят сообщения друг друга.* +*Каждому идентификатору сессии соответствует изолированная история беседы — пользователи никогда не видят сообщения друг друга.* ### Обработка ошибок -Инструменты могут давать сбои — API могут тайм-аутиться, параметры могут быть некорректными, внешние сервисы могут перестать работать. Производственные агенты нуждаются в обработке ошибок, чтобы модель могла объяснять проблемы или пробовать альтернативы, а не аварийно завершать работу всего приложения. Когда инструмент бросает исключение, LangChain4j перехватывает его и возвращает сообщение об ошибке обратно модели, которая затем может объяснить проблему на естественном языке. +Инструменты могут давать сбои — API могут тайм-аутиться, параметры могут быть некорректны, внешние сервисы могут отключаться. Промышленные агенты нуждаются в обработке ошибок, чтобы модель могла объяснить проблему или попытаться альтернативные варианты, а не вызывать сбой всего приложения. Если инструмент вызывает исключение, LangChain4j перехватывает его и передает сообщение об ошибке обратно модели, которая затем может объяснить проблему на естественном языке. ## Доступные инструменты -Следующая диаграмма показывает широкий спектр инструментов, которые вы можете создать. В этом модуле продемонстрированы инструменты погоды и преобразования температур, но тот же паттерн `@Tool` работает для любых Java-методов — от запросов к базе данных до обработки платежей. +Следующая диаграмма показывает широкую экосистему инструментов, которые вы можете создавать. Этот модуль демонстрирует инструменты погоды и температуры, но тот же паттерн `@Tool` работает для любых методов Java — от запросов к базе данных до обработки платежей. Экосистема инструментов -*Любой Java-метод с аннотацией @Tool становится доступен AI — паттерн расширяется на базы данных, API, email, файловые операции и многое другое.* +*Любой метод Java, аннотированный `@Tool`, становится доступен AI — паттерн распространяется на базы данных, API, электронную почту, операции с файлами и многое другое.* -## Когда использовать агенты на основе инструментов +## Когда использовать агентов с инструментами -Не каждому запросу нужны инструменты. Решение зависит от того, нужно ли AI взаимодействовать с внешними системами или он может ответить на основе собственных знаний. Следующее руководство суммирует, когда инструменты приносят пользу, а когда они излишни: +Не все запросы требуют использования инструментов. Решение зависит от того, нужно ли ИИ взаимодействовать с внешними системами или он может ответить из собственных знаний. Следующее руководство резюмирует, когда инструменты приносят пользу, а когда они излишни: Когда использовать инструменты -*Краткое руководство по принятию решений — инструменты нужны для данных в реальном времени, вычислений и действий; общие знания и творческие задачи не требуют их.* +*Краткое руководство по выбору — инструменты нужны для данных в реальном времени, вычислений и действий; общие знания и творческие задачи обходятся без них.* ## Инструменты vs RAG -Модули 03 и 04 расширяют возможности AI, но принципиально разными способами. RAG предоставляет модели доступ к **знаниям** через поиск документов. Инструменты дают модели возможность выполнять **действия**, вызывая функции. Следующая диаграмма сравнивает эти два подхода бок о бок — от того, как работают рабочие процессы, до компромиссов между ними: +Модули 03 и 04 расширяют возможности ИИ, но принципиально по-разному. RAG даёт модели доступ к **знаниям** через поиск документов. Инструменты дают модели возможность выполнять **действия**, вызывая функции. Следующая диаграмма сравнивает эти два подхода — от того, как работает каждый процесс, до плюсов и минусов: -Сравнение инструментов и RAG +Сравнение Инструменты и RAG -*RAG извлекает информацию из статических документов — инструменты выполняют действия и получают динамические, актуальные данные. Многие производственные системы комбинируют оба подхода.* +*RAG извлекает информацию из статических документов — Инструменты выполняют действия и получают динамические, актуальные данные. Многие промышленные системы используют оба подхода вместе.* -На практике многие производственные системы используют оба подхода: RAG для обоснования ответов вашей документацией и инструменты для получения живых данных или выполнения операций. +На практике многие производственные системы сочетают оба подхода: RAG для обоснования ответов в вашей документации и Инструменты для получения живых данных или выполнения операций. ## Следующие шаги @@ -377,11 +377,11 @@ cd ..; .\stop-all.ps1 # Все модули --- -**Навигация:** [← Предыдущий: Модуль 03 - RAG](../03-rag/README.md) | [Назад к главной](../README.md) | [Далее: Модуль 05 - MCP →](../05-mcp/README.md) +**Навигация:** [← Предыдущий: Модуль 03 - RAG](../03-rag/README.md) | [На главную](../README.md) | [Следующий: Модуль 05 - MCP →](../05-mcp/README.md) --- -**Отказ от ответственности**: -Этот документ был переведен с помощью сервиса автоматического перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия обеспечить точность, пожалуйста, учитывайте, что автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать официальным источником. Для критически важной информации рекомендуется использовать профессиональный человеческий перевод. Мы не несем ответственности за любые недоразумения или ошибки в интерпретации, возникшие в результате использования данного перевода. +**Отказ от ответственности**: +Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода. \ No newline at end of file diff --git a/translations/ru/README.md b/translations/ru/README.md index 089483cf2..27d5cd572 100644 --- a/translations/ru/README.md +++ b/translations/ru/README.md @@ -9,11 +9,11 @@ #### Поддерживается через GitHub Action (автоматически и всегда актуально) -[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](./README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) +[Арабский](../ar/README.md) | [Бенгали](../bn/README.md) | [Болгарский](../bg/README.md) | [Бирманский (Мьянма)](../my/README.md) | [Китайский (упрощённый)](../zh-CN/README.md) | [Китайский (традиционный, Гонконг)](../zh-HK/README.md) | [Китайский (традиционный, Макао)](../zh-MO/README.md) | [Китайский (традиционный, Тайвань)](../zh-TW/README.md) | [Хорватский](../hr/README.md) | [Чешский](../cs/README.md) | [Датский](../da/README.md) | [Нидерландский](../nl/README.md) | [Эстонский](../et/README.md) | [Финский](../fi/README.md) | [Французский](../fr/README.md) | [Немецкий](../de/README.md) | [Греческий](../el/README.md) | [Иврит](../he/README.md) | [Хинди](../hi/README.md) | [Венгерский](../hu/README.md) | [Индонезийский](../id/README.md) | [Итальянский](../it/README.md) | [Японский](../ja/README.md) | [Каннада](../kn/README.md) | [Кхмерский](../km/README.md) | [Корейский](../ko/README.md) | [Литовский](../lt/README.md) | [Малайский](../ms/README.md) | [Малаялам](../ml/README.md) | [Маратхи](../mr/README.md) | [Непальский](../ne/README.md) | [Нигерийский пиджин](../pcm/README.md) | [Норвежский](../no/README.md) | [Персидский (фарси)](../fa/README.md) | [Польский](../pl/README.md) | [Португальский (Бразилия)](../pt-BR/README.md) | [Португальский (Португалия)](../pt-PT/README.md) | [Пенджаби (гурмукхи)](../pa/README.md) | [Румынский](../ro/README.md) | [Русский](./README.md) | [Сербский (кириллица)](../sr/README.md) | [Словацкий](../sk/README.md) | [Словенский](../sl/README.md) | [Испанский](../es/README.md) | [Свахили](../sw/README.md) | [Шведский](../sv/README.md) | [Тагалог (филиппинский)](../tl/README.md) | [Тамильский](../ta/README.md) | [Телугу](../te/README.md) | [Тайский](../th/README.md) | [Турецкий](../tr/README.md) | [Украинский](../uk/README.md) | [Урду](../ur/README.md) | [Вьетнамский](../vi/README.md) > **Предпочитаете клонировать локально?** > -> Этот репозиторий включает более 50 языковых переводов, что значительно увеличивает размер скачивания. Чтобы клонировать без переводов, используйте sparse checkout: +> В этом репозитории есть переводы на 50+ языков, что значительно увеличивает размер загрузки. Чтобы клонировать без переводов, используйте sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,122 +29,122 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Это даст вам всё, что нужно для прохождения курса, при значительно более быстрой загрузке. +> Это даст вам все необходимое для прохождения курса с гораздо более быстрой загрузкой. ## Содержание -1. [Быстрый старт](00-quick-start/README.md) - Начало работы с LangChain4j -2. [Введение](01-introduction/README.md) - Изучение основ LangChain4j -3. [Проектирование подсказок](02-prompt-engineering/README.md) - Освоение эффективного создания подсказок -4. [RAG (генерация с расширенным поиском)](03-rag/README.md) - Создание интеллектуальных систем на основе знаний -5. [Инструменты](04-tools/README.md) - Интеграция внешних инструментов и простых ассистентов -6. [MCP (Протокол контекста модели)](05-mcp/README.md) - Работа с Протоколом контекста модели (MCP) и агентными модулями +1. [Введение](01-introduction/README.md) - Изучите основы LangChain4j +2. [Создание запросов (Prompt Engineering)](02-prompt-engineering/README.md) - Освойте эффективный дизайн запросов +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Создавайте интеллектуальные системы на основе знаний +4. [Инструменты](04-tools/README.md) - Интегрируйте внешние инструменты и простых помощников +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Работайте с протоколом контекста модели (MCP) и агентскими модулями ### Видеоруководства -Для каждого модуля проводится сопровождающая сессия в прямом эфире, где мы последовательно разбираем концепции и код. +Каждый модуль сопровождается живой сессией, на которой мы шаг за шагом разберём концепции и код. | Модуль | Видео | |--------|-------| | 01 - Введение | [Начало работы с LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Проектирование подсказок | [Проектирование подсказок с LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 02 - Создание запросов | [Создание запросов с LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG с LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Инструменты & 05 - MCP | [AI-агенты с инструментами и MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Учебный план +## Учебный путь -**Новичок в LangChain4j?** Ознакомьтесь с [Глоссарием](docs/GLOSSARY.md) для определения ключевых терминов и понятий. +**Новичок в LangChain4j?** Ознакомьтесь со [Словарём](docs/GLOSSARY.md) для определения ключевых терминов и понятий. > **Быстрый старт** 1. Форкните этот репозиторий в свой аккаунт GitHub 2. Нажмите **Code** → вкладка **Codespaces** → **...** → **New with options...** -3. Используйте настройки по умолчанию – будет выбран контейнер разработки, созданный для этого курса +3. Используйте настройки по умолчанию – это выберет контейнер для разработки, подготовленный для этого курса 4. Нажмите **Create codespace** 5. Подождите 5-10 минут, пока среда будет готова -6. Переходите сразу к [Быстрому старту](./00-quick-start/README.md), чтобы начать! +6. Перейдите прямо к [Введению](./01-introduction/README.md), чтобы начать! -После прохождения модулей изучите [Руководство по тестированию](docs/TESTING.md), чтобы увидеть работу концепций тестирования LangChain4j на практике. +После прохождения модулей изучите [Руководство по тестированию](docs/TESTING.md), чтобы увидеть концепции тестирования LangChain4j в действии. -> **Примечание:** В этом курсе используются как GitHub Models, так и Azure OpenAI. Модуль [Быстрый старт](00-quick-start/README.md) использует GitHub Models (подписка Azure не требуется), тогда как модули 1-5 используют Azure OpenAI. Если у вас нет аккаунта, начните с [бесплатного аккаунта Azure](https://aka.ms/azure-free-account). +> **Примечание:** Это обучение использует Azure OpenAI. Если у вас его нет, начните с [БЕСПЛАТНОГО аккаунта Azure](https://aka.ms/azure-free-account). ## Обучение с GitHub Copilot -Чтобы быстро начать программировать, откройте этот проект в GitHub Codespace или в вашей локальной IDE с предоставленным devcontainer. Devcontainer, используемый в этом курсе, предварительно настроен с GitHub Copilot для совместного программирования с AI. +Чтобы быстро начать писать код, откройте этот проект в GitHub Codespace или в вашем локальном IDE с предоставленным devcontainer. Devcontainer, используемый в этом курсе, предварительно настроен с GitHub Copilot для совместного программирования с AI. -Каждый пример кода включает рекомендованные вопросы, которые вы можете задать GitHub Copilot для углубления понимания. Ищите подсказки 💡/🤖 в: +Каждый пример кода содержит предлагаемые вопросы, которые вы можете задать GitHub Copilot для углубления понимания. Ищите подсказки 💡/🤖 в: -- **Заголовках Java-файлов** – вопросы, связанные с конкретным примером -- **README модулей** – вопросы для исследования после примеров кода +- **Заголовках Java-файлов** – Вопросы, специфичные для каждого примера +- **README модулей** – Подсказки для исследования после примеров кода -**Как использовать:** Откройте любой файл с кодом и задайте Copilot предложенные вопросы. Он имеет полный контекст кода и может объяснить, расширить и предложить альтернативы. +**Как использовать:** Откройте любой файл с кодом и задайте Copilot предложенные вопросы. Он имеет полный контекст кода и может объяснять, расширять и предлагать альтернативы. -Хотите узнать больше? Ознакомьтесь с [Copilot для совместного программирования с AI](https://aka.ms/GitHubCopilotAI). +Хотите узнать больше? Посмотрите [Copilot для совместного программирования с AI](https://aka.ms/GitHubCopilotAI). ## Дополнительные ресурсы ### LangChain -[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j для начинающих](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js для начинающих](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain для начинающих](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents -[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Агенты +[![AZD для начинающих](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI для начинающих](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP для начинающих](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI-агенты для начинающих](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Серия по генеративному ИИ -[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +[![Генеративный ИИ для начинающих](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Генеративный ИИ (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Генеративный ИИ (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Генеративный ИИ (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Основное обучение -[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +### Основы обучения +[![ML для начинающих](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science для начинающих](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![ИИ для начинающих](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Кибербезопасность для начинающих](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + [![Веб-разработка для начинающих](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT для начинающих](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![Интернет вещей для начинающих](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![Разработка XR для начинающих](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Серия Copilot -[![Copilot для совместного программирования с ИИ](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot для AI совместного программирования](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![Copilot для C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![Приключения Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## Получение помощи +## Получение Помощи Если вы застряли или у вас есть вопросы по созданию AI-приложений, присоединяйтесь: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Если у вас есть отзывы о продукте или ошибки при разработке, посетите: +Если у вас есть отзывы о продукте или ошибки при создании, посетите: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Лицензия -Лицензия MIT - смотрите файл [LICENSE](../../LICENSE) для подробностей. +Лицензия MIT — см. файл [LICENSE](../../LICENSE) для подробностей. --- -**Отказ от ответственности**: -Этот документ был переведён с помощью сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия обеспечить точность, пожалуйста, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на родном языке следует считать авторитетным источником. Для важной информации рекомендуется профессиональный человеческий перевод. Мы не несем ответственности за возможные недоразумения или неправильное толкование, возникшие в результате использования данного перевода. +**Отказ от ответственности**: +Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода. \ No newline at end of file diff --git a/translations/ru/docs/GLOSSARY.md b/translations/ru/docs/GLOSSARY.md index 16eb3a35e..9ba4421c6 100644 --- a/translations/ru/docs/GLOSSARY.md +++ b/translations/ru/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## Содержание -- [Основные понятия](../../../docs) -- [Компоненты LangChain4j](../../../docs) -- [Концепции ИИ/МО](../../../docs) -- [Ограничения (Guardrails)](../../../docs) -- [Промпт-инжиниринг](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Агенты и Инструменты](../../../docs) -- [Agentic Модуль](../../../docs) -- [Протокол Контекста Модели (MCP)](../../../docs) -- [Сервисы Azure](../../../docs) -- [Тестирование и Разработка](../../../docs) - -Быстрая справка по терминам и понятиям, используемым в курсе. +- [Основные понятия](#основные-понятия) +- [Компоненты LangChain4j](#компоненты-langchain4j) +- [Концепции ИИ/МО](#концепции-иимо) +- [Ограничения безопасности](#ограничения-безопасности) +- [Промпт Инжиниринг](#prompt-engineering---module-02) +- [RAG (Генерация с подкреплением)](#rag-retrieval-augmented-generation---module-03) +- [Агенты и инструменты](#agents-and-tools---module-04) +- [Agentic Модуль](#agentic-module---module-05) +- [Протокол контекста модели (MCP)](#model-context-protocol-mcp---module-05) +- [Сервисы Azure](#azure-services---module-01) +- [Тестирование и разработка](#testing-and-development---testing-guide) + +Быстрая справка по терминам и понятиям, используемым в ходе курса. ## Основные понятия -**AI Agent** — Система, использующая ИИ для автономного рассуждения и действий. [Модуль 04](../04-tools/README.md) +**AI Agent** – Система, использующая ИИ для автономного рассуждения и действий. [Модуль 04](../04-tools/README.md) -**Chain** — Последовательность операций, где результат одной служит входом для следующей. +**Chain** – Последовательность операций, где выход одного шага становится входом для следующего. -**Распределение на части (Chunking)** — Разбиение документов на меньшие фрагменты. Обычно: 300-500 токенов с наложением. [Модуль 03](../03-rag/README.md) +**Chunking** – Разбиение документов на меньшие части. Обычно: 300-500 токенов с перекрытием. [Модуль 03](../03-rag/README.md) -**Окно Контекста** — Максимальное количество токенов, обрабатываемых моделью. GPT-5.2: 400К токенов (до 272К вход, 128К выход). +**Context Window** – Максимальное количество токенов, которое модель может обработать. GPT-5.2: 400K токенов (до 272K на вход, 128K на выход). -**Встраивания (Embeddings)** — Числовые векторы, представляющие смысл текста. [Модуль 03](../03-rag/README.md) +**Embeddings** – Числовые векторы, представляющие смысл текста. [Модуль 03](../03-rag/README.md) -**Вызов Функций (Function Calling)** — Модель генерирует структурированные запросы на вызов внешних функций. [Модуль 04](../04-tools/README.md) +**Function Calling** – Модель генерирует структурированные запросы для вызова внешних функций. [Модуль 04](../04-tools/README.md) -**Галлюцинация (Hallucination)** — Когда модели генерируют неверную, но правдоподобную информацию. +**Hallucination** – Ситуация, когда модели генерируют некорректную, но правдоподобную информацию. -**Промпт (Prompt)** — Текстовый ввод для языковой модели. [Модуль 02](../02-prompt-engineering/README.md) +**Prompt** – Текстовый ввод в языковую модель. [Модуль 02](../02-prompt-engineering/README.md) -**Семантический Поиск (Semantic Search)** — Поиск по смыслу с помощью встраиваний, а не ключевых слов. [Модуль 03](../03-rag/README.md) +**Semantic Search** – Поиск по смыслу с использованием эмбеддингов, а не ключевых слов. [Модуль 03](../03-rag/README.md) -**Состояние с/без памяти (Stateful vs Stateless)** — Stateless: без памяти. Stateful: сохраняет историю диалога. [Модуль 01](../01-introduction/README.md) +**Stateful vs Stateless** – Stateless: без памяти. Stateful: хранит историю диалога. [Модуль 01](../01-introduction/README.md) -**Токены (Tokens)** — Базовые единицы текста, которые обрабатывают модели. Влияют на стоимость и лимиты. [Модуль 01](../01-introduction/README.md) +**Tokens** – Базовые единицы текста, которые обрабатывают модели. Влияют на стоимость и ограничения. [Модуль 01](../01-introduction/README.md) -**Цепочка Инструментов (Tool Chaining)** — Последовательное выполнение инструментов, когда результат одного влияет на вызов следующего. [Модуль 04](../04-tools/README.md) +**Tool Chaining** – Последовательное выполнение инструментов, где результат влияет на следующий вызов. [Модуль 04](../04-tools/README.md) ## Компоненты LangChain4j -**AiServices** — Создаёт типобезопасные интерфейсы AI-сервисов. +**AiServices** – Создает типобезопасные интерфейсы AI-сервисов. -**OpenAiOfficialChatModel** — Универсальный клиент для моделей OpenAI и Azure OpenAI. +**OpenAiOfficialChatModel** – Унифицированный клиент для моделей OpenAI и Azure OpenAI. -**OpenAiOfficialEmbeddingModel** — Создаёт встраивания с помощью официального клиента OpenAI (поддерживает OpenAI и Azure OpenAI). +**OpenAiOfficialEmbeddingModel** – Создает эмбеддинги с помощью официального клиента OpenAI (поддерживает OpenAI и Azure OpenAI). -**ChatModel** — Основной интерфейс языковых моделей. +**ChatModel** – Основной интерфейс для языковых моделей. -**ChatMemory** — Хранит историю диалога. +**ChatMemory** – Поддерживает историю диалога. -**ContentRetriever** — Находит соответствующие фрагменты документов для RAG. +**ContentRetriever** – Находит релевантные куски документов для RAG. -**DocumentSplitter** — Разбивает документы на части. +**DocumentSplitter** – Разбивает документы на части. -**EmbeddingModel** — Преобразует текст в числовые векторы. +**EmbeddingModel** – Преобразует текст в числовые векторы. -**EmbeddingStore** — Хранит и извлекает встраивания. +**EmbeddingStore** – Хранит и извлекает эмбеддинги. -**MessageWindowChatMemory** — Хранит скользящее окно последних сообщений. +**MessageWindowChatMemory** – Поддерживает скользящее окно недавних сообщений. -**PromptTemplate** — Создаёт переиспользуемые промпты с заполнителями `{{variable}}`. +**PromptTemplate** – Создает повторно используемые промпты с плейсхолдерами `{{variable}}`. -**TextSegment** — Текстовый фрагмент с метаданными. Используется в RAG. +**TextSegment** – Текстовый фрагмент с метаданными. Используется в RAG. -**ToolExecutionRequest** — Представляет запрос на выполнение инструмента. +**ToolExecutionRequest** – Представляет запрос на выполнение инструмента. -**UserMessage / AiMessage / SystemMessage** — Типы сообщений в диалоге. +**UserMessage / AiMessage / SystemMessage** – Типы сообщений диалога. ## Концепции ИИ/МО -**Обучение на малом числе примеров (Few-Shot Learning)** — Предоставление примеров в промптах. [Модуль 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** – Предоставление примеров в промптах. [Модуль 02](../02-prompt-engineering/README.md) -**Большая Языковая Модель (LLM)** — ИИ-модели, обученные на обширных текстовых данных. +**Large Language Model (LLM)** – ИИ-модели, обученные на огромных текстовых данных. -**Уровень Рассуждений (Reasoning Effort)** — Параметр GPT-5.2, контролирующий глубину мышления. [Модуль 02](../02-prompt-engineering/README.md) +**Reasoning Effort** – Параметр GPT-5.2, контролирующий глубину рассуждения. [Модуль 02](../02-prompt-engineering/README.md) -**Температура (Temperature)** — Контролирует случайность вывода. Низкая = детерминированно, высокая = креативно. +**Temperature** – Контролирует случайность вывода. Низкое = детерминированное, высокое = креативное. -**Векторная база данных (Vector Database)** — Специализированная БД для встраиваний. [Модуль 03](../03-rag/README.md) +**Vector Database** – Специализированная база данных для эмбеддингов. [Модуль 03](../03-rag/README.md) -**Обучение без примеров (Zero-Shot Learning)** — Выполнение задач без примеров. [Модуль 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** – Выполнение задач без примеров. [Модуль 02](../02-prompt-engineering/README.md) -## Ограничения (Guardrails) - [Модуль 00](../00-quick-start/README.md) +## Ограничения безопасности -**Многоуровневая защита (Defense in Depth)** — Многоступенчатый подход безопасности, объединяющий прикладные ограничения и фильтры безопасности провайдера. +**Defense in Depth** – Многоуровневый подход к безопасности, сочетающий ограничения на уровне приложения с фильтрами безопасности провайдеров. -**Жёсткая блокировка (Hard Block)** — Провайдер возвращает ошибку HTTP 400 при серьёзном нарушении контента. +**Hard Block** – Провайдер возвращает HTTP 400 ошибку при серьезных нарушениях контента. -**InputGuardrail** — Интерфейс LangChain4j для проверки пользовательского ввода перед поступлением в LLM. Сохраняет ресурсы и время, блокируя вредоносные промпты заранее. +**InputGuardrail** – Интерфейс LangChain4j для проверки пользовательского ввода до передачи в LLM. Экономит затраты и задержки, блокируя вредоносные промпты на раннем этапе. -**InputGuardrailResult** — Тип результата проверки guardrail: `success()` или `fatal("причина")`. +**InputGuardrailResult** – Тип возврата проверки ограничений: `success()` или `fatal("причина")`. -**OutputGuardrail** — Интерфейс проверки ответов ИИ до возврата пользователям. +**OutputGuardrail** – Интерфейс проверки ответов ИИ перед возвратом пользователям. -**Фильтры безопасности провайдера (Provider Safety Filters)** — Встроенные фильтры провайдера ИИ (например, GitHub Models), которые выявляют нарушения на уровне API. +**Provider Safety Filters** – Встроенные фильтры контента от AI-провайдеров (например, Azure OpenAI), блокирующие нарушения на уровне API. -**Мягкий отказ (Soft Refusal)** — Модель вежливо отказывается отвечать без генерации ошибки. +**Soft Refusal** – Модель вежливо отказывается отвечать без генерации ошибки. -## Промпт-инжиниринг - [Модуль 02](../02-prompt-engineering/README.md) +## Промпт Инжиниринг - [Модуль 02](../02-prompt-engineering/README.md) -**Цепочка рассуждений (Chain-of-Thought)** — Пошаговое рассуждение для повышения точности. +**Chain-of-Thought** – Пошаговое рассуждение для повышения точности. -**Ограниченный вывод (Constrained Output)** — Принудительное соблюдение конкретного формата или структуры. +**Constrained Output** – Принудительное соблюдение конкретного формата или структуры. -**Высокая готовность (High Eagerness)** — Паттерн GPT-5.2 для глубоких рассуждений. +**High Eagerness** – Паттерн GPT-5.2 для тщательных рассуждений. -**Низкая готовность (Low Eagerness)** — Паттерн GPT-5.2 для быстрых ответов. +**Low Eagerness** – Паттерн GPT-5.2 для быстрых ответов. -**Многоходовой диалог (Multi-Turn Conversation)** — Поддержание контекста в ходе обмена сообщениями. +**Multi-Turn Conversation** – Поддержание контекста в ходе диалога. -**Ролевое создание промптов (Role-Based Prompting)** — Задаёт личность модели через системные сообщения. +**Role-Based Prompting** – Установка роли модели через системные сообщения. -**Саморефлексия (Self-Reflection)** — Модель оценивает и улучшает свой вывод. +**Self-Reflection** – Модель оценивает и улучшает свой вывод. -**Структурированный анализ (Structured Analysis)** — Фиксированная схема оценки. +**Structured Analysis** – Фиксированная структура оценки. -**Шаблон выполнения задачи (Task Execution Pattern)** — План → Выполнение → Итог. +**Task Execution Pattern** – План → Выполнение → Резюме. -## RAG (Retrieval-Augmented Generation) - [Модуль 03](../03-rag/README.md) +## RAG (Генерация с подкреплением) - [Модуль 03](../03-rag/README.md) -**Конвейер обработки документов** — Загрузка → разбиение → встраивание → хранение. +**Document Processing Pipeline** – Загрузка → разбиение → эмбеддинг → хранение. -**Встраивания в памяти (In-Memory Embedding Store)** — Непостоянное хранилище для тестирования. +**In-Memory Embedding Store** – Непостоянное хранилище для тестирования. -**RAG** — Комбинация поиска и генерации для обоснованных ответов. +**RAG** – Комбинация поиска и генерации для обоснования ответов. -**Оценка похожести (Similarity Score)** — Мера (0-1) семантической близости. +**Similarity Score** – Мера (0-1) семантического сходства. -**Ссылка на источник (Source Reference)** — Метаданные о найденном контенте. +**Source Reference** – Метаданные о найденном контенте. -## Агенты и Инструменты - [Модуль 04](../04-tools/README.md) +## Агенты и инструменты - [Модуль 04](../04-tools/README.md) -**Аннотация @Tool** — Помечает методы Java как вызываемые ИИ инструменты. +**@Tool Annotation** – Маркирует Java-методы как инструменты, вызываемые ИИ. -**Паттерн ReAct** — Рассуждать → Действовать → Наблюдать → Повторять. +**ReAct Pattern** – Рассуждение → Действие → Наблюдение → Повтор. -**Управление сессиями** — Отдельные контексты для разных пользователей. +**Session Management** – Раздельные контексты для разных пользователей. -**Инструмент (Tool)** — Функция, которую агент ИИ может вызвать. +**Tool** – Функция, которую может вызывать AI-агент. -**Описание инструмента (Tool Description)** — Документация назначения и параметров инструмента. +**Tool Description** – Документация по назначению и параметрам инструмента. ## Agentic Модуль - [Модуль 05](../05-mcp/README.md) -**Аннотация @Agent** — Помечает интерфейсы как агенты ИИ с декларативным описанием поведения. +**@Agent Annotation** – Маркирует интерфейсы как AI-агентов с декларативным описанием поведения. -**Agent Listener** — Хук для мониторинга выполнения агента через `beforeAgentInvocation()` и `afterAgentInvocation()`. +**Agent Listener** – Хук для мониторинга выполнения агента через `beforeAgentInvocation()` и `afterAgentInvocation()`. -**Agentic Scope** — Общая память, где агенты сохраняют результаты с помощью `outputKey` для использования другими агентами. +**Agentic Scope** – Общая память, где агенты сохраняют результаты с помощью `outputKey` для использования другими агентами. -**AgenticServices** — Фабрика создания агентов через `agentBuilder()` и `supervisorBuilder()`. +**AgenticServices** – Фабрика для создания агентов с помощью `agentBuilder()` и `supervisorBuilder()`. -**Условный рабочий процесс (Conditional Workflow)** — Маршрутизация к разным специализированным агентам в зависимости от условий. +**Conditional Workflow** – Маршрутизация к разным специализированным агентам на основе условий. -**Human-in-the-Loop** — Паттерн с добавлением человекочитаемых контрольных точек для одобрения или проверки контента. +**Human-in-the-Loop** – Паттерн с добавлением человеческих контрольных точек для одобрения или проверки содержания. -**langchain4j-agentic** — Maven-зависимость для декларативного построения агентов (экспериментальная). +**langchain4j-agentic** – Maven-зависимость для декларативного построения агентов (экспериментальная). -**Циклический рабочий процесс (Loop Workflow)** — Повторяет выполнение агента до достижения условия (например, качество ≥ 0.8). +**Loop Workflow** – Итерация выполнения агента до достижения условия (например, качество ≥ 0.8). -**outputKey** — Параметр аннотации агента, указывающий, где сохраняются результаты в Agentic Scope. +**outputKey** – Параметр аннотации агента, указывающий, где сохраняются результаты в Agentic Scope. -**Параллельный рабочий процесс (Parallel Workflow)** — Запуск нескольких агентов одновременно для независимых задач. +**Parallel Workflow** – Параллельный запуск нескольких агентов для независимых задач. -**Стратегия ответа (Response Strategy)** — Как супервизор формулирует итоговый ответ: LAST, SUMMARY или SCORED. +**Response Strategy** – Способ формулирования итогового ответа супервизором: LAST, SUMMARY, или SCORED. -**Последовательный рабочий процесс (Sequential Workflow)** — Последовательное выполнение агентов, передача вывода между этапами. +**Sequential Workflow** – Последовательное выполнение агентов, где выход влияет на следующий шаг. -**Паттерн супервизор агента (Supervisor Agent Pattern)** — Продвинутый паттерн, где супервизор LLM динамически выбирает подагентов для вызова. +**Supervisor Agent Pattern** – Продвинутый агентный паттерн, в котором супервизор LLM динамически выбирает, каких подагентов вызывать. -## Протокол Контекста Модели (MCP) - [Модуль 05](../05-mcp/README.md) +## Протокол контекста модели (MCP) - [Модуль 05](../05-mcp/README.md) -**langchain4j-mcp** — Maven-зависимость для интеграции MCP в LangChain4j. +**langchain4j-mcp** – Maven-зависимость для интеграции MCP в LangChain4j. -**MCP** — Протокол Контекста Модели: стандарт для подключения AI-приложений к внешним инструментам. Создайте один раз — используйте везде. +**MCP** – Протокол контекста модели: стандарт для подключения AI-приложений к внешним инструментам. Напиши один раз — используй везде. -**MCP Клиент** — Приложение, которое подключается к MCP серверам для обнаружения и использования инструментов. +**MCP Client** – Приложение, подключающееся к MCP-серверам для обнаружения и использования инструментов. -**MCP Сервер** — Сервис, предоставляющий инструменты через MCP с понятными описаниями и схемами параметров. +**MCP Server** – Сервис, предоставляющий инструменты через MCP с описаниями и схемами параметров. -**McpToolProvider** — Компонент LangChain4j, обёртывающий MCP инструменты для использования в AI сервисах и агентах. +**McpToolProvider** – Компонент LangChain4j, оборачивающий MCP-инструменты для использования в AI-сервисах и агентах. -**McpTransport** — Интерфейс для коммуникации MCP. Реализации: Stdio и HTTP. +**McpTransport** – Интерфейс для коммуникации MCP. Реализации: Stdio и HTTP. -**Stdio Транспорт** — Локальный процессный транспорт через stdin/stdout. Полезно для доступа к файловой системе или CLI-инструментам. +**Stdio Transport** – Транспорт локального процесса через stdin/stdout. Полезен для доступа к файловой системе или CLI-инструментам. -**StdioMcpTransport** — Реализация LangChain4j, запускающая MCP сервер как подпроцесс. +**StdioMcpTransport** – Реализация LangChain4j, которая запускает MCP-сервер как подпроцесс. -**Обнаружение Инструментов (Tool Discovery)** — Клиент запрашивает сервер о доступных инструментах с описаниями и схемами. +**Tool Discovery** – Клиент запрашивает у сервера список доступных инструментов с описаниями и схемами. ## Сервисы Azure - [Модуль 01](../01-introduction/README.md) -**Azure AI Search** — Облачный поиск с возможностями встраивания. [Модуль 03](../03-rag/README.md) +**Azure AI Search** – Облачный поиск с векторными возможностями. [Модуль 03](../03-rag/README.md) -**Azure Developer CLI (azd)** — Развёртывание ресурсов Azure. +**Azure Developer CLI (azd)** – Инструмент для развертывания ресурсов Azure. -**Azure OpenAI** — Корпоративный AI-сервис Microsoft. +**Azure OpenAI** – Корпоративный сервис ИИ от Microsoft. -**Bicep** — Язык инфраструктуры как кода Azure. [Гид по инфраструктуре](../01-introduction/infra/README.md) +**Bicep** – Язык инфраструктуры как кода для Azure. [Гайд по инфраструктуре](../01-introduction/infra/README.md) -**Имя развёртывания (Deployment Name)** — Имя для развёртывания модели в Azure. +**Deployment Name** – Имя развертывания модели в Azure. -**GPT-5.2** — Последняя модель OpenAI с контролем рассуждений. [Модуль 02](../02-prompt-engineering/README.md) +**GPT-5.2** – Последняя модель OpenAI с контролем рассуждений. [Модуль 02](../02-prompt-engineering/README.md) -## Тестирование и Разработка - [Руководство по тестированию](TESTING.md) +## Тестирование и разработка - [Гайд по тестированию](TESTING.md) -**Dev Container** — Контейнеризированная среда разработки. [Конфигурация](../../../.devcontainer/devcontainer.json) +**Dev Container** – Контейнеризированная среда разработки. [Конфигурация](../../../.devcontainer/devcontainer.json) -**GitHub Models** — Бесплатная площадка для ИИ-моделей. [Модуль 00](../00-quick-start/README.md) +**In-Memory Testing** – Тестирование с использованием памяти. -**Тестирование в памяти** — Тесты, использующие хранилище в памяти. +**Integration Testing** – Тестирование с использованием реальной инфраструктуры. -**Интеграционное тестирование** — Тестирование с использованием реальной инфраструктуры. +**Maven** – Инструмент автоматизации сборки Java. -**Maven** — Инструмент автоматизации сборки для Java. +**Mockito** – Фреймворк для мокирования в Java. -**Mockito** — Фреймворк для мокирования в Java. - -**Spring Boot** — Фреймворк для Java приложений. [Модуль 01](../01-introduction/README.md) +**Spring Boot** – Java-фреймворк для приложений. [Модуль 01](../01-introduction/README.md) --- -**Отказ от ответственности**: -Этот документ был переведен с помощью сервиса автоматического перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия обеспечить точность, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения важной информации рекомендуется обратиться к профессиональному переводу, выполненному человеком. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования данного перевода. +**Отказ от ответственности**: +Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода. \ No newline at end of file diff --git a/translations/ru/docs/TESTING.md b/translations/ru/docs/TESTING.md index e69ed3f16..24f4ea28f 100644 --- a/translations/ru/docs/TESTING.md +++ b/translations/ru/docs/TESTING.md @@ -2,15 +2,15 @@ ## Содержание -- [Быстрый старт](../../../docs) -- [Что покрывают тесты](../../../docs) -- [Запуск тестов](../../../docs) -- [Запуск тестов в VS Code](../../../docs) -- [Паттерны тестирования](../../../docs) -- [Философия тестирования](../../../docs) -- [Следующие шаги](../../../docs) +- [Быстрый старт](#быстрый-старт) +- [Что охватывают тесты](#что-охватывают-тесты) +- [Запуск тестов](#запуск-тестов) +- [Запуск тестов в VS Code](#запуск-тестов-в-vs-code) +- [Паттерны тестирования](#паттерны-тестирования) +- [Философия тестирования](#философия-тестирования) +- [Дальнейшие шаги](#дальнейшие-шаги) -Это руководство проведет вас через тесты, демонстрирующие, как тестировать AI-приложения без необходимости использования API ключей или внешних сервисов. +Это руководство проведет вас через тесты, которые демонстрируют, как тестировать AI-приложения без необходимости использования API-ключей или внешних сервисов. ## Быстрый старт @@ -26,28 +26,27 @@ mvn test mvn --% test ``` -Когда все тесты пройдут успешно, вы увидите вывод, похожий на скриншот ниже — тесты выполнены без ошибок. +Когда все тесты пройдут, вы увидите вывод, похожий на скриншот ниже — все тесты выполнены без ошибок. Successful Test Results -*Успешное выполнение тестов со всеми пройденными тестами без сбоев* +*Успешное выполнение тестов с нулевым числом ошибок* -## Что покрывают тесты +## Что охватывают тесты -Этот курс фокусируется на **модульных тестах**, которые выполняются локально. Каждый тест демонстрирует конкретную концепцию LangChain4j в изоляции. Ниже приведена пирамида тестирования, показывающая, где размещаются модульные тесты — они образуют быстрый, надежный фундамент, на котором строится остальная стратегия тестирования. +Этот курс сосредоточен на **модульных тестах**, которые выполняются локально. Каждый тест демонстрирует конкретную концепцию LangChain4j в изоляции. Пирамида тестирования ниже показывает, где размещаются модульные тесты — они образуют быстрый и надежный фундамент для всей вашей стратегии тестирования. Testing Pyramid -*Пирамида тестирования, показывающая баланс между модульными тестами (быстрые, изолированные), интеграционными тестами (реальные компоненты) и сквозными тестами. Это обучение охватывает модульное тестирование.* +*Пирамида тестирования, показывающая баланс между модульными тестами (быстрыми, изолированными), интеграционными тестами (с реальными компонентами) и end-to-end тестами. В этом обучении рассматривается модульное тестирование.* | Модуль | Тесты | Фокус | Ключевые файлы | -|--------|-------|-------|----------------| -| **00 - Быстрый старт** | 6 | Шаблоны подсказок и подстановка переменных | `SimpleQuickStartTest.java` | -| **01 - Введение** | 8 | Память диалогов и состояние чата | `SimpleConversationTest.java` | -| **02 - Инженерия подсказок** | 12 | Паттерны GPT-5.2, уровни готовности, структурированный вывод | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Ингестия документов, эмбеддинги, поиск по похожести | `DocumentServiceTest.java` | -| **04 - Инструменты** | 12 | Вызовы функций и цепочки инструментов | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Протокол Model Context с передачей через stdio | `SimpleMcpTest.java` | +|--------|-------|-------|-----------| +| **01 - Введение** | 8 | Память диалога и состоянийный чат | `SimpleConversationTest.java` | +| **02 - Создание шаблонов запросов** | 12 | Паттерны GPT-5.2, уровни готовности, структурированный вывод | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Ввод документов, векторные представления, поиск по сходству | `DocumentServiceTest.java` | +| **04 - Инструменты** | 12 | Вызов функций и цепочки инструментов | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Протокол контекста модели с транспортом stdio | `SimpleMcpTest.java` | ## Запуск тестов @@ -68,14 +67,14 @@ mvn --% test **Bash:** ```bash cd 01-introduction && mvn test -# Или от корня +# Или из root mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Или от корня +# Или из корня mvn --% test -pl 01-introduction ``` @@ -95,12 +94,12 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#необходимо сохранять историю разговора +mvn test -Dtest=SimpleConversationTest#следуетСохранятьИсториюРазговоров ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#следуетСохранятьИсториюРазговора +mvn --% test -Dtest=SimpleConversationTest#следуетПоддерживатьИсториюБеседы ``` ## Запуск тестов в VS Code @@ -109,27 +108,27 @@ mvn --% test -Dtest=SimpleConversationTest#следуетСохранятьИс VS Code Test Explorer -*Test Explorer в VS Code с деревом тестов, показывающим все Java-классы тестов и отдельные тестовые методы* +*Test Explorer в VS Code показывает дерево тестов со всеми классами и отдельными методами тестов на Java* **Чтобы запустить тесты в VS Code:** -1. Откройте Test Explorer, нажав на иконку с колбой в панели активности +1. Откройте Test Explorer, нажав на иконку стакана в панели активности 2. Разверните дерево тестов, чтобы увидеть все модули и классы тестов -3. Нажмите кнопку воспроизведения рядом с любым тестом, чтобы запустить его отдельно -4. Нажмите "Run All Tests" для запуска всего набора -5. Кликните правой кнопкой по любому тесту и выберите "Debug Test" для установки точек останова и пошагового выполнения кода +3. Нажмите кнопку запуска рядом с любым тестом для отдельного запуска +4. Нажмите "Запустить все тесты" для выполнения всего набора +5. Щелкните правой кнопкой мыши по тесту и выберите "Отладить тест", чтобы установить точки останова и пошагово выполнить код -Test Explorer показывает зеленые галочки для прошедших тестов и предоставляет подробные сообщения об ошибках при неудачном прохождении. +Test Explorer показывает зеленые галочки для прошедших тестов и предоставляет подробные сообщения при ошибках. ## Паттерны тестирования -### Паттерн 1: Тестирование шаблонов подсказок +### Паттерн 1: Тестирование шаблонов запросов -Самый простой паттерн тестирует шаблоны подсказок без вызова какой-либо AI-модели. Вы проверяете, что подстановка переменных работает правильно, и подсказки отформатированы как ожидалось. +Самый простой паттерн тестирует шаблоны запросов без вызова AI-модели. Вы проверяете, что подстановка переменных работает правильно и шаблоны форматируются как ожидается. Prompt Template Testing -*Тестирование шаблонов подсказок, показывающее поток подстановки переменных: шаблон с заполнителями → примененные значения → проверенный форматированный вывод* +*Тестирование шаблонов запросов с показом замещения переменных: шаблон с заполнителями → примененные значения → проверенный отформатированный вывод* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Этот тест находится в `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Этот паттерн проверяет корректность подстановки переменных и правильность форматирования шаблонов — не требуется API-ключ или вызов модели. -**Запустите его:** +### Паттерн 2: Мокирование языковых моделей -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#форматированиеШаблонаТеста -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#тестированиеФорматированияШаблонаПодсказки -``` - -### Паттерн 2: Мокинг языковых моделей - -При тестировании логики разговоров используйте Mockito для создания поддельных моделей, которые возвращают заранее определённые ответы. Это делает тесты быстрыми, бесплатными и детерминированными. +При тестировании логики диалогов используйте Mockito для создания фиктивных моделей, которые возвращают предопределённые ответы. Это делает тесты быстрыми, бесплатными и детерминированными. Mock vs Real API Comparison -*Сравнение, показывающее, почему моки предпочтительнее для тестирования: они быстрые, бесплатные, детерминированные и не требуют API ключей* +*Сравнение, почему для тестирования предпочитают моки: они быстрые, бесплатные, детерминированные и не требуют API-ключей* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 сообщения пользователя + 3 сообщения ИИ + assertThat(history).hasSize(6); // 3 сообщения от пользователя + 3 сообщения от ИИ } } ``` -Этот паттерн используется в `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Мок обеспечивает согласованное поведение, чтобы вы могли проверить правильность управления памятью. +Этот паттерн встречается в `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Мок обеспечивает стабильное поведение, чтобы проверить правильность управления памятью. -### Паттерн 3: Тестирование изоляции разговоров +### Паттерн 3: Тестирование изоляции диалогов -Память разговоров должна хранить данные для нескольких пользователей раздельно. Этот тест проверяет, что разговоры не смешивают контексты. +Память диалога должна сохранять разделение между несколькими пользователями. Этот тест проверяет, что диалоги не смешивают контексты. Conversation Isolation -*Тестирование изоляции разговоров с раздельными хранилищами памяти для разных пользователей, чтобы избежать смешения контекста* +*Тестирование изоляции диалогов с раздельными хранилищами памяти для разных пользователей для предотвращения смешивания контекстов* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Каждый разговор ведет свою независимую историю. В производственных системах такая изоляция критична для приложений с несколькими пользователями. +Каждый диалог ведет собственную независимую историю. В продуктивных системах такая изоляция важна для многопользовательских приложений. -### Паттерн 4: Тестирование инструментов независимо +### Паттерн 4: Тестирование инструментов отдельно -Инструменты — это функции, которые AI может вызывать. Тестируйте их напрямую, чтобы убедиться, что они работают корректно независимо от решений AI. +Инструменты — это функции, которые AI может вызывать. Тестируйте их напрямую, чтобы убедиться, что они работают правильно независимо от решений AI. Tools Testing -*Тестирование инструментов самостоятельно, показывающее выполнение поддельных инструментов без вызовов AI для проверки бизнес-логики* +*Тестирование инструментов отдельно с показом выполнения мок-инструментов без вызова AI для проверки бизнес-логики* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Эти тесты из `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` проверяют логику инструментов без участия AI. Пример цепочки показывает, как вывод одного инструмента подаётся на вход другому. +Эти тесты из `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` проверяют логику инструментов без участия AI. Пример цепочки показывает, как выход одного инструмента становится входом другого. ### Паттерн 5: Тестирование RAG в памяти -Системы RAG традиционно требуют векторных баз данных и сервисов эмбеддингов. Паттерн в памяти позволяет тестировать весь конвейер без внешних зависимостей. +Системы RAG обычно требуют векторных баз данных и сервисов эмбеддингов. Паттерн in-memory позволяет протестировать весь процесс без внешних зависимостей. In-Memory RAG Testing -*Рабочий процесс тестирования RAG в памяти, включающий разбор документа, хранение эмбеддингов и поиск по похожести без необходимости базы данных* +*Рабочий процесс тестирования RAG в памяти: парсинг документа, хранение эмбеддингов и поиск по сходству без необходимости базы данных* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Этот тест из `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` создает документ в памяти и проверяет разбиение на части и обработку метаданных. +Этот тест из `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` создает документ в памяти и проверяет нарезку на чанки и работу с метаданными. -### Паттерн 6: Интеграционные тесты MCP +### Паттерн 6: Интеграционное тестирование MCP -Модуль MCP тестирует интеграцию протокола Model Context с использованием передачи через stdio. Эти тесты проверяют, что ваше приложение может запускать и взаимодействовать с MCP-серверами как подпроцессами. +Модуль MCP тестирует интеграцию Протокола Контекста Модели с использованием транспорта stdio. Эти тесты проверяют, что ваше приложение может запускать и общаться с MCP-серверами как подпроцессами. -Тесты в `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` проверяют поведение клиента MCP. +Тесты в `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` проверяют поведение MCP клиента. **Запустите их:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Философия тестирования -Тестируйте свой код, а не AI. Ваши тесты должны проверять код, который вы пишете, проверяя, как строятся подсказки, как управляется память и как выполняются инструменты. Ответы AI вариативны и не должны быть частью утверждений теста. Спрашивайте себя, правильно ли ваш шаблон подсказки подставляет переменные, а не дает ли AI правильный ответ. +Тестируйте ваш код, а не AI. Ваши тесты должны проверять написанный вами код, контролируя построение шаблонов запросов, управление памятью и выполнение инструментов. Ответы AI меняются и не должны входить в утверждения тестов. Спрашивайте себя, правильно ли подставляются переменные в шаблоне запросов, а не дает ли AI правильный ответ. -Используйте моки для языковых моделей. Это внешние зависимости, которые медленные, дорогие и недетерминированные. Мокинг делает тесты быстрыми — миллисекунды вместо секунд, бесплатными — без затрат на API, и детерминированными — один и тот же результат каждый раз. +Используйте моки для языковых моделей. Это внешние зависимости, которые медленные, дорогие и недетерминированные. Мокирование делает тесты быстрыми (миллисекунды вместо секунд), бесплатными (отсутствие расходов на API) и детерминированными (одинаковый результат каждое выполнение). -Держите тесты независимыми. Каждый тест должен инициализировать свои данные, не зависеть от других тестов и убирать за собой. Тесты должны проходить независимо от порядка выполнения. +Держите тесты независимыми. Каждый тест должен создавать собственные данные, не зависеть от других тестов и очищаться после себя. Тесты должны проходить вне зависимости от порядка выполнения. -Тестируйте краевые случаи, выходящие за рамки основного сценария. Пробуйте пустые вводы, очень большие вводы, специальные символы, неверные параметры и граничные условия. Они часто выявляют ошибки, которые в нормальном использовании не проявляются. +Тестируйте пограничные случаи, выходящие за рамки нормального сценария. Пробуйте пустые входные данные, очень большие объемы, специальные символы, некорректные параметры и граничные условия. Именно они часто выявляют баги, неочевидные при обычном использовании. -Используйте описательные имена. Сравните `shouldMaintainConversationHistoryAcrossMultipleMessages()` с `test1()`. Первое точно говорит, что тестируется, что облегчает отладку при сбоях. +Используйте описательные имена. Сравните `shouldMaintainConversationHistoryAcrossMultipleMessages()` и `test1()`. Первое говорит вам точно, что тестируется, упрощая отладку при ошибках. -## Следующие шаги +## Дальнейшие шаги -Теперь, когда вы понимаете паттерны тестирования, изучите каждый модуль подробнее: +Теперь, когда вы понимаете паттерны тестирования, углубитесь в каждый модуль: -- **[00 - Быстрый старт](../00-quick-start/README.md)** - Начните с основ шаблонов подсказок -- **[01 - Введение](../01-introduction/README.md)** - Изучите управление памятью разговоров -- **[02 - Инженерия подсказок](../02/prompt-engineering/README.md)** - Освойте паттерны подсказок GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Создайте системы дополненной генерации с поиском -- **[04 - Инструменты](../04-tools/README.md)** - Реализуйте вызовы функций и цепочки инструментов -- **[05 - MCP](../05-mcp/README.md)** - Интегрируйте Model Context Protocol +- **[01 - Введение](../01-introduction/README.md)** — Узнайте про управление памятью диалога +- **[02 - Создание шаблонов запросов](../02/prompt-engineering/README.md)** — Освойте паттерны создания запросов GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** — Создавайте системы расширенного генеративного поиска +- **[04 - Инструменты](../04-tools/README.md)** — Реализуйте вызов функций и цепочки инструментов +- **[05 - MCP](../05-mcp/README.md)** — Интегрируйте Протокол Контекста Модели -README каждого модуля содержит подробные объяснения рассмотренных здесь концепций. +README каждого модуля содержит подробные объяснения концепций, проверяемых здесь. --- -**Навигация:** [← Назад к началу](../README.md) +**Навигация:** [← Назад к главной](../README.md) --- -**Отказ от ответственности**: -Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия обеспечить точность, просим учитывать, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для критически важной информации рекомендуется воспользоваться услугами профессионального перевода. Мы не несем ответственности за любые недоразумения или неверные толкования, вызванные использованием данного перевода. +**Отказ от ответственности**: +Этот документ был переведен с использованием сервиса машинного перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода. \ No newline at end of file diff --git a/translations/sk/.co-op-translator.json b/translations/sk/.co-op-translator.json index ad3a87dbd..16dfec97b 100644 --- a/translations/sk/.co-op-translator.json +++ b/translations/sk/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "sk" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T23:45:29+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T10:53:31+00:00", "source_file": "01-introduction/README.md", "language_code": "sk" }, @@ -18,20 +18,20 @@ "language_code": "sk" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T23:47:30+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T10:49:01+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "sk" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T23:48:47+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T10:52:37+00:00", "source_file": "03-rag/README.md", "language_code": "sk" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:25:28+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T10:51:19+00:00", "source_file": "04-tools/README.md", "language_code": "sk" }, @@ -54,8 +54,8 @@ "language_code": "sk" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:59:02+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T10:47:44+00:00", "source_file": "README.md", "language_code": "sk" }, @@ -72,14 +72,14 @@ "language_code": "sk" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T23:51:23+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T10:49:30+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "sk" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T23:52:00+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T10:50:06+00:00", "source_file": "docs/TESTING.md", "language_code": "sk" } diff --git a/translations/sk/00-quick-start/README.md b/translations/sk/00-quick-start/README.md deleted file mode 100644 index a0c195c62..000000000 --- a/translations/sk/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modul 00: Rýchly štart - -## Obsah - -- [Úvod](../../../00-quick-start) -- [Čo je LangChain4j?](../../../00-quick-start) -- [Závislosti LangChain4j](../../../00-quick-start) -- [Predpoklady](../../../00-quick-start) -- [Nastavenie](../../../00-quick-start) - - [1. Získajte svoj GitHub token](../../../00-quick-start) - - [2. Nastavte svoj token](../../../00-quick-start) -- [Spustenie príkladov](../../../00-quick-start) - - [1. Základný chat](../../../00-quick-start) - - [2. Vzory výziev](../../../00-quick-start) - - [3. Volanie funkcií](../../../00-quick-start) - - [4. Otázky a odpovede k dokumentom (Easy RAG)](../../../00-quick-start) - - [5. Zodpovedná AI](../../../00-quick-start) -- [Čo každý príklad ukazuje](../../../00-quick-start) -- [Ďalšie kroky](../../../00-quick-start) -- [Riešenie problémov](../../../00-quick-start) - -## Úvod - -Tento rýchly štart je určený na to, aby vás čo najrýchlejšie uviedol do práce s LangChain4j. Pokrýva úplné základy vytvárania AI aplikácií s LangChain4j a GitHub Modelmi. V nasledujúcich moduloch prejdete na Azure OpenAI a GPT-5.2 a hlbšie sa ponoríte do každého konceptu. - -## Čo je LangChain4j? - -LangChain4j je Java knižnica, ktorá zjednodušuje tvorbu aplikácií poháňaných AI. Namiesto práce s HTTP klientmi a parsovaním JSON pracujete s čistými Java API. - -„Reťaz“ v LangChain odkazuje na spájanie viacerých komponentov – napríklad spájať výzvu k modelu, potom k parseru, alebo spojiť viac AI volaní, kde výstup jedného slúži ako vstup pre ďalšie. Tento rýchly štart sa sústreďuje na základy predtým, než preskúmate zložitejšie reťazce. - -LangChain4j Chaining Concept - -*Spájanie komponentov v LangChain4j – stavebné bloky sa spájajú na vytvorenie výkonných AI pracovných tokov* - -Použijeme tri základné komponenty: - -**ChatModel** – Rozhranie pre interakciu s AI modelom. Zavolajte `model.chat("prompt")` a získajte odpoveď ako reťazec. Používame `OpenAiOfficialChatModel`, ktorý pracuje s OpenAI-kompatibilnými koncovými bodmi ako GitHub Models. - -**AiServices** – Vytvára typovo bezpečné rozhrania AI služieb. Definujte metódy, označte ich anotáciou `@Tool`, a LangChain4j sa postará o orchestráciu. AI automaticky volá vaše Java metódy, keď je to potrebné. - -**MessageWindowChatMemory** – Uchováva históriu konverzácie. Bez toho je každá požiadavka nezávislá. S týmto si AI pamätá predchádzajúce správy a udržiava kontext cez viacero kol. - -LangChain4j Architecture - -*Architektúra LangChain4j – základné komponenty spolupracujú na poháňanie vašich AI aplikácií* - -## Závislosti LangChain4j - -Tento rýchly štart používa tri Maven závislosti v [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modul `langchain4j-open-ai-official` poskytuje triedu `OpenAiOfficialChatModel`, ktorá sa pripája k OpenAI-kompatibilným API. GitHub Models používa rovnaký formát API, takže nie je potrebný žiaden špeciálny adaptér – stačí nastaviť základnú URL na `https://models.github.ai/inference`. - -Modul `langchain4j-easy-rag` poskytuje automatické delenie dokumentov, vkladanie do vektorov (embedding) a vyhľadávanie, takže môžete vytvárať RAG aplikácie bez manuálneho nastavovania každého kroku. - -## Predpoklady - -**Používate Dev Container?** Java a Maven sú už nainštalované. Potrebujete len GitHub Osobný Prístupový Token. - -**Lokálny vývoj:** -- Java 21+, Maven 3.9+ -- GitHub Osobný Prístupový Token (inštrukcie nižšie) - -> **Poznámka:** Tento modul používa `gpt-4.1-nano` z GitHub Models. Nemodifikujte názov modelu v kóde – je nakonfigurovaný tak, aby fungoval s dostupnými modelmi GitHubu. - -## Nastavenie - -### 1. Získajte svoj GitHub token - -1. Prejdite na [GitHub Nastavenia → Osobné prístupové tokeny](https://github.com/settings/personal-access-tokens) -2. Kliknite na „Generate new token“ -3. Nastavte popisný názov (napr. „LangChain4j Demo“) -4. Nastavte platnosť (odporúčaných 7 dní) -5. V časti „Account permissions“ nájdite „Models“ a nastavte na „Read-only“ -6. Kliknite na „Generate token“ -7. Skopírujte a uložte si token – už ho znova neuvidíte - -### 2. Nastavte svoj token - -**Možnosť 1: Použitie VS Code (odporúčané)** - -Ak používate VS Code, pridajte svoj token do súboru `.env` v koreňovom adresári projektu: - -Ak `.env` súbor neexistuje, skopírujte `.env.example` do `.env` alebo vytvorte nový `.env` súbor v koreňovom adresári. - -**Príklad `.env` súboru:** -```bash -# V /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Potom môžete jednoducho kliknúť pravým tlačidlom na ktorýkoľvek demo súbor (napr. `BasicChatDemo.java`) v Prieskumníku a vybrať **„Run Java“** alebo použiť spúšťacie konfigurácie z panela Run and Debug. - -**Možnosť 2: Použitie terminálu** - -Nastavte token ako premennú prostredia: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Spustenie príkladov - -**Použitie VS Code:** Jednoducho kliknite pravým tlačidlom na ktorýkoľvek demo súbor v Prieskumníku a vyberte **„Run Java“**, alebo použite spúšťacie konfigurácie z panela Run and Debug (predtým si nezabudnite pridať token do `.env` súboru). - -**Použitie Maven:** Alternatívne môžete spustiť príklady príkazovým riadkom: - -### 1. Základný chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Vzory výziev - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Ukazuje zero-shot, few-shot, chain-of-thought a role-based prompting. - -### 3. Volanie funkcií - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI automaticky volá vaše Java metódy podľa potreby. - -### 4. Otázky a odpovede k dokumentom (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Pýtajte sa otázky o svojich dokumentoch pomocou Easy RAG s automatickým vkladaním a vyhľadávaním. - -### 5. Zodpovedná AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Pozrite sa, ako bezpečnostné filtre AI blokujú škodlivý obsah. - -## Čo každý príklad ukazuje - -**Základný chat** – [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Začnite tu, aby ste videli LangChain4j v jeho najjednoduchšej podobe. Vytvoríte `OpenAiOfficialChatModel`, odošlete výzvu pomocou `.chat()` a získate späť odpoveď. Toto demonštruje základy: ako inicializovať modely s vlastnými koncovými bodmi a API kľúčmi. Keď pochopíte tento vzor, všetko ostatné na ňom staviate. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) a spýtajte sa: -> - „Ako by som v tomto kóde prepol z GitHub Models na Azure OpenAI?“ -> - „Aké ďalšie parametre môžem nakonfigurovať v OpenAiOfficialChatModel.builder()?“ -> - „Ako pridať streamovanie odpovedí namiesto čakania na kompletnú odpoveď?“ - -**Prompt Engineering** – [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Teraz, keď viete, ako komunikovať s modelom, preskúmajme, čo mu hovoríte. Toto demo používa rovnaké nastavenie modelu, ale ukazuje päť rôznych vzorov zadávania výziev. Vyskúšajte zero-shot výzvy pre priame inštrukcie, few-shot výzvy, ktoré sa učia z príkladov, chain-of-thought výzvy, ktoré odkrývajú kroky uvažovania, a role-based výzvy, ktoré nastavujú kontext. Uvidíte, ako rovnaký model dáva výrazne odlišné výsledky v závislosti od toho, ako rámujete svoju požiadavku. - -Demo tiež demonštruje šablóny výziev, ktoré sú mocným spôsobom, ako vytvárať znovupoužiteľné výzvy s premennými. -Nižšie je príklad výzvy pomocou `PromptTemplate` z LangChain4j na vyplnenie premenných. AI odpovie na základe poskytnutého cieľa a aktivity. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) a spýtajte sa: -> - „Aký je rozdiel medzi zero-shot a few-shot výzvami a kedy použiť ktorý? “ -> - „Ako parameter teploty ovplyvňuje odpovede modelu?“ -> - „Aké sú techniky na zabránenie útokom prompt injection v produkcii?“ -> - „Ako môžem vytvoriť znovupoužiteľné objekty PromptTemplate pre bežné vzory?“ - -**Integrácia nástrojov** – [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Tu LangChain4j získava na sile. Použijete `AiServices` na vytvorenie AI asistenta, ktorý môže volať vaše Java metódy. Stačí označiť metódy anotáciou `@Tool("popis")` a LangChain4j sa postará o zvyšok – AI automaticky rozhodne, kedy použiť ktorý nástroj podľa požiadaviek používateľa. Toto demonštruje volanie funkcií, kľúčovú techniku na vytváranie AI, ktorá môže konať, nie len odpovedať na otázky. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) a spýtajte sa: -> - „Ako funguje anotácia @Tool a čo s ňou robí LangChain4j na pozadí?“ -> - „Môže AI volať niekoľko nástrojov za sebou na riešenie zložitých problémov?“ -> - „Čo sa stane, ak nástroj vyhodí výnimku – ako mám riešiť chyby?“ -> - „Ako by som integroval skutočné API namiesto tohto príkladu kalkulačky?“ - -**Otázky a odpovede k dokumentom (Easy RAG)** – [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Tu uvidíte RAG (retrieval-augmented generation) pomocou prístupu LangChain4j „Easy RAG“. Dokumenty sa načítajú, automaticky rozdelia a vložia do pamäťového úložiska, potom vyhľadávač obsahu dodáva relevantné kúsky AI v čase dotazu. AI odpovedá na základe vašich dokumentov, nie všeobecných vedomostí modelu. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) a spýtajte sa: -> - „Ako RAG zabraňuje AI halucináciám v porovnaní s použitím trénovacích dát modelu?“ -> - „Aký je rozdiel medzi týmto jednoduchým prístupom a vlastným RAG pipeline?“ -> - „Ako by som to škáloval pre viac dokumentov alebo väčšie znalostné bázy?“ - -**Zodpovedná AI** – [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Postavte bezpečnosť AI s obranou do hĺbky. Toto demo ukazuje dve vrstvy ochrany pracujúce spoločne: - -**Časť 1: LangChain4j vstupné bezpečnostné zábrany (Input Guardrails)** – Blokujú nebezpečné výzvy ešte predtým, než sa dostanú k LLM. Vytvorte vlastné zábrany, ktoré kontrolujú nepovolené kľúčové slová alebo vzory. Bežia vo vašom kóde, takže sú rýchle a zadarmo. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Časť 2: Bezpečnostné filtre poskytovateľa** – GitHub Models majú zabudované filtre, ktoré zachytia to, čo vaše zábrany môžu prehliadnuť. Uvidíte hardbloky (HTTP 400 chyby) pri vážnych porušeniach a mäkké odmietnutia, kde AI zdvorilo odmietne. - -> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) a spýtajte sa: -> - „Čo je InputGuardrail a ako vytvorím vlastný?“ -> - „Aký je rozdiel medzi hard blokom a soft odmietnutím?“ -> - „Prečo používať súčasne zábrany a filtre poskytovateľa?“ - -## Ďalšie kroky - -**Ďalší modul:** [01-introduction - Začíname s LangChain4j](../01-introduction/README.md) - ---- - -**Navigácia:** [← Späť na hlavný](../README.md) | [Ďalej: Modul 01 - Úvod →](../01-introduction/README.md) - ---- - -## Riešenie problémov - -### Prvé zostavenie Maven - -**Problém**: Počiatočný príkaz `mvn clean compile` alebo `mvn package` trvá dlho (10-15 minút) - -**Príčina**: Maven potrebuje stiahnuť všetky závislosti projektu (Spring Boot, LangChain4j knižnice, Azure SDK, atď.) pri prvom zostavení. - -**Riešenie**: Toto je normálne správanie. Následné zostavenia budú omnoho rýchlejšie, keďže závislosti sú uložené v lokálnej cache. Dĺžka sťahovania závisí od rýchlosti vašej siete. - -### Syntax Maven príkazov v PowerShell - -**Problém**: Maven príkazy zlyhávajú s chybou `Unknown lifecycle phase ".mainClass=..."` -**Príčina**: PowerShell interpretuje `=` ako operátor priradenia premennej, čo narušuje syntax vlastností Maven - -**Riešenie**: Použite operátor zastavenia parsovania `--%` pred príkazom Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operátor `--%` informuje PowerShell, aby všetky nasledujúce argumenty odovzdal Maven doslovne bez interpretácie. - -### Zobrazenie emoji vo Windows PowerShell - -**Problém**: Odpovede AI zobrazujú nečitateľné znaky (napr. `????` alebo `â??`) namiesto emoji v PowerShell - -**Príčina**: Predvolené kódovanie PowerShell nepodporuje UTF-8 emoji - -**Riešenie**: Spustite tento príkaz pred vykonaním Java aplikácií: -```cmd -chcp 65001 -``` - -Tým sa v termináli vynúti kódovanie UTF-8. Alternatívou je použiť Windows Terminal, ktorý má lepšiu podporu Unicode. - -### Ladenie API volaní - -**Problém**: Chyby overenia, limity rýchlosti alebo neočakávané odpovede od AI modelu - -**Riešenie**: Príklady obsahujú `.logRequests(true)` a `.logResponses(true)`, aby sa API volania zobrazovali v konzole. To pomáha riešiť chyby overenia, limity rýchlosti alebo neočakávané odpovede. V produkcii tieto príznaky odstráňte, aby ste znížili hluk v logoch. - ---- - - -**Zrieknutie sa zodpovednosti**: -Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Aj keď sa snažíme o presnosť, berte prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Originálny dokument v pôvodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pri kritických informáciách sa odporúča využiť profesionálny ľudský preklad. Nie sme zodpovední za akékoľvek nepochopenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu. - \ No newline at end of file diff --git a/translations/sk/01-introduction/README.md b/translations/sk/01-introduction/README.md index 4e3176d7c..7053e705e 100644 --- a/translations/sk/01-introduction/README.md +++ b/translations/sk/01-introduction/README.md @@ -2,37 +2,37 @@ ## Obsah -- [Video prehľad](../../../01-introduction) -- [Čo sa naučíte](../../../01-introduction) -- [Predpoklady](../../../01-introduction) -- [Pochopenie základného problému](../../../01-introduction) -- [Pochopenie tokenov](../../../01-introduction) -- [Ako funguje pamäť](../../../01-introduction) -- [Ako to používa LangChain4j](../../../01-introduction) -- [Nasadenie infraštruktúry Azure OpenAI](../../../01-introduction) -- [Spustenie aplikácie lokálne](../../../01-introduction) -- [Používanie aplikácie](../../../01-introduction) - - [Stateless Chat (ľavý panel)](../../../01-introduction) - - [Stateful Chat (pravý panel)](../../../01-introduction) -- [Ďalšie kroky](../../../01-introduction) - -## Video prehľad - -Pozrite si túto živú reláciu, ktorá vysvetľuje, ako začať s týmto modulom: - -Getting Started with LangChain4j - Live Session +- [Video prehliadka](#video-prehliadka) +- [Čo sa naučíte](#čo-sa-naučíte) +- [Predpoklady](#predpoklady) +- [Pochopenie základného problému](#pochopenie-základného-problému) +- [Pochopenie tokenov](#pochopenie-tokenov) +- [Ako funguje pamäť](#ako-funguje-pamäť) +- [Ako to využíva LangChain4j](#ako-to-využíva-langchain4j) +- [Nasadenie infraštruktúry Azure OpenAI](#nasadenie-infraštruktúry-azure-openai) +- [Spustenie aplikácie lokálne](#spustenie-aplikácie-lokálne) +- [Použitie aplikácie](#použitie-aplikácie) + - [Stateless Chat (ľavý panel)](#stateless-chat-ľavý-panel) + - [Stateful Chat (pravý panel)](#stateful-chat-pravý-panel) +- [Ďalšie kroky](#ďalšie-kroky) + +## Video prehliadka + +Pozrite si toto živé vysielanie, ktoré vysvetľuje, ako začať s týmto modulom: + +Začíname s LangChain4j - Živé vysielanie ## Čo sa naučíte -V rýchlom štarte ste použili GitHub Models na posielanie promptov, volanie nástrojov, vytváranie RAG pipeline a testovanie ochranných opatrení. Tieto demo ukázali, čo je možné — teraz prejdeme na Azure OpenAI a GPT-5.2 a začneme stavať aplikácie na produkčnej úrovni. Tento modul sa sústreďuje na konverzačné AI, ktoré si pamätá kontext a udržiava stav — koncepty, ktoré použili rýchle demo, ale neboli vysvetlené. +Toto je váš východiskový bod s LangChain4j a Azure OpenAI. Začíname základmi a začíname stavať produkčné aplikácie. Tento modul sa zameriava na konverzačné AI, ktorá si pamätá kontext a udržiava stav — základné koncepty, na ktorých sú postavené všetky neskoršie moduly. -Po celý tento návod budeme používať GPT-5.2 z Azure OpenAI, pretože jeho pokročilé schopnosti uvažovania robia správanie rôznych vzorov jasnejším. Keď pridáte pamäť, jasne uvidíte rozdiel. To uľahčuje pochopenie, čo každý komponent prináša vašej aplikácii. +Budeme používať Azure OpenAI GPT-5.2 cez celý tento návod, pretože jeho pokročilé schopnosti logického uvažovania robia správanie rôznych vzorov jasnejším. Keď pridáte pamäť, jasne uvidíte rozdiel. To uľahčuje pochopenie toho, čo každý komponent vášmu riešeniu prináša. -Postavíte jednu aplikáciu, ktorá demonštruje oba vzory: +Vybudujete jednu aplikáciu, ktorá demonštruje oba vzory: -**Stateless Chat** — Každý dotaz je nezávislý. Model si nepamätá predchádzajúce správy. Toto je vzor, ktorý ste použili v rýchlom štarte. +**Stateless Chat** – Každý request je nezávislý. Model si nepamätá predchádzajúce správy. Toto je najjednoduchšia východisková možnosť. -**Stateful Conversation** — Každý dotaz obsahuje históriu konverzácie. Model udržiava kontext počas viacerých výmen. Toto je to, čo produkčné aplikácie vyžadujú. +**Stateful Conversation** – Každý request obsahuje históriu konverzácie. Model udržiava kontext naprieč viacerými kolami. Toto je to, čo produkčné aplikácie vyžadujú. ## Predpoklady @@ -41,47 +41,47 @@ Postavíte jednu aplikáciu, ktorá demonštruje oba vzory: - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Poznámka:** Java, Maven, Azure CLI a Azure Developer CLI (azd) sú predinštalované v poskytnutom devcontaineri. +> **Poznámka:** Java, Maven, Azure CLI a Azure Developer CLI (azd) sú predinštalované v poskytnutom devcontainery. -> **Poznámka:** Tento modul používa GPT-5.2 na Azure OpenAI. Nasadenie je nakonfigurované automaticky cez `azd up` - nemodifikujte názov modelu v kóde. +> **Poznámka:** Tento modul používa GPT-5.2 na Azure OpenAI. Nasadenie je automaticky nakonfigurované cez `azd up` – nemeniť názov modelu v kóde. ## Pochopenie základného problému -Jazykové modely sú stateless. Každé API volanie je nezávislé. Ak pošlete "Volám sa John" a potom sa opýtate "Ako sa volám?", model nemá tušenie, že ste sa práve predstavili. Každý požiadavok spracováva, akoby to bola vaša prvá konverzácia. +Jazykové modely sú bezstavové. Každé API volanie je nezávislé. Ak pošlete "Volám sa John" a potom sa opýtate "Ako sa volám?", model nemá poňatia, že ste sa práve predstavili. Každý request spracováva, akoby to bola vaša prvá konverzácia. -To je v poriadku pre jednoduché otázky a odpovede, ale na reálne aplikácie nepoužiteľné. Chatboty zákazníckej podpory si musia pamätať, čo ste im povedali. Osobní asistenti potrebujú kontext. Každá viackolová konverzácia vyžaduje pamäť. +To je v poriadku pre jednoduché otázky a odpovede, ale nepoužiteľné pre skutočné aplikácie. Boti zákazníckej podpory potrebujú pamätať, čo ste im povedali. Osobní asistenti potrebujú kontext. Akákoľvek viackolová konverzácia vyžaduje pamäť. -Nasledujúci diagram porovnáva oba prístupy — vľavo stateless volanie, ktoré zabúda vaše meno; vpravo stateful volanie podporované ChatMemory, ktoré si ho pamätá. +Nasledujúci diagram ukazuje kontrast dvoch prístupov – vľavo bezstavové volanie, ktoré zabúda vaše meno; vpravo stavové volanie s ChatMemory, ktoré si meno pamätá. -Stateless vs Stateful Conversations +Bezstavové vs Stavové konverzácie -*Rozdiel medzi stateless (nezávislé volania) a stateful (kontextovo uvedomelé) konverzácie* +*Rozdiel medzi bezstavovými (nezávislé volania) a stavovými (s vedomím kontextu) konverzáciami* ## Pochopenie tokenov -Predtým, než sa pustíme do konverzácií, je dôležité pochopiť tokeny — základné jednotky textu, ktoré jazykové modely spracovávajú: +Pred zanorením sa do konverzácií je dôležité pochopiť tokeny – základné jednotky textu, ktoré jazykové modely spracúvajú: -Token Explanation +Vysvetlenie tokenu -*Príklad, ako sa text rozkladá na tokeny - "I love AI!" sa stáva 4 samostatné spracovateľské jednotky* +*Príklad, ako je text rozdelený na tokeny – "I love AI!" sa stáva 4 samostatnými spracovacími jednotkami* -Tokeny sú spôsob, akým AI modely merajú a spracovávajú text. Slová, interpunkcia a dokonca aj medzery môžu byť tokeny. Váš model má limit, koľko tokenov môže spracovať naraz (400 000 pre GPT-5.2, s až 272 000 vstupnými tokenmi a 128 000 výstupnými tokenmi). Pochopenie tokenov vám pomôže spravovať dĺžku konverzácie a náklady. +Tokeny sú, ako AI modely merajú a spracúvajú text. Slová, interpunkcia a dokonca aj medzery môžu byť tokeny. Váš model má limit, koľko tokenov môže naraz spracovať (400 000 pri GPT-5.2, s maximálne 272 000 vstupných tokenov a 128 000 výstupných tokenov). Pochopenie tokenov vám pomáha riadiť dĺžku konverzácie a náklady. ## Ako funguje pamäť -Chat pamäť rieši problém stateless tým, že udržiava históriu konverzácie. Pred odoslaním požiadavku modelu framework doplní relevantné predchádzajúce správy. Keď sa opýtate "Ako sa volám?", systém skutočne pošle celú históriu konverzácie, čo umožní modelu vidieť, že ste predtým povedali "Volám sa John." +Pamäť chatov rieši problém bezstavovosti tým, že udržiava históriu konverzácie. Pred odoslaním požiadavky do modelu framework pridá relevantné predchádzajúce správy. Keď sa opýtate "Ako sa volám?", systém vlastne pošle celú históriu konverzácie, čo umožní modelu vidieť, že ste predtým povedali "Volám sa John." -LangChain4j poskytuje implementácie pamäte, ktoré to automaticky zvládajú. Vy si vyberiete, koľko správ si chcete ponechať a framework spravuje kontextové okno. Nasledujúci diagram ukazuje, ako MessageWindowChatMemory udržiava posuvné okno nedávnych správ. +LangChain4j poskytuje implementácie pamäte, ktoré to automaticky zvládajú. Vyberiete, koľko správ chcete uchovať, a framework spravuje kontextové okno. Nižšie uvedený diagram ukazuje, ako MessageWindowChatMemory udržiava kĺzavé okno nedávnych správ. -Memory Window Concept +Koncept pamäťového okna -*MessageWindowChatMemory udržiava posuvné okno nedávnych správ, automaticky vyhadzujúc staršie* +*MessageWindowChatMemory udržiava kĺzavé okno nedávnych správ, automaticky vyhadzuje tie staršie* -## Ako to používa LangChain4j +## Ako to využíva LangChain4j -Tento modul rozširuje rýchly štart integráciou Spring Boot a pridávaním pamäte pre konverzácie. Takto do seba zapadajú komponenty: +Tento modul integruje Spring Boot a pridáva pamäť konverzácie. Takto spolu diely zapadajú: -**Závislosti** — Pridajte dve knižnice LangChain4j: +**Závislosti** – Pridajte dve knižnice LangChain4j: ```xml @@ -94,7 +94,7 @@ Tento modul rozširuje rýchly štart integráciou Spring Boot a pridávaním pa ``` -**Chat model** — Nakonfigurujte Azure OpenAI ako Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Chatovací model** – Nakonfigurujte Azure OpenAI ako Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder číta prihlasovacie údaje z environmentálnych premenných nastavených `azd up`. Nastavenie `baseUrl` na váš Azure endpoint spôsobí, že OpenAI klient bude pracovať s Azure OpenAI. +Builder číta prihlasovacie údaje z environmentálnych premenných nastavených cez `azd up`. Nastavenie `baseUrl` na váš Azure endpoint umožní OpenAI klientovi pracovať s Azure OpenAI. -**Pamäť konverzácie** — Sledujte históriu chatu pomocou MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Pamäť konverzácie** – Sledujte históriu chatu pomocou MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Vytvorte pamäť s `withMaxMessages(10)` pre uloženie posledných 10 správ. Pridávajte správy používateľa a AI s typovanými wrappermi: `UserMessage.from(text)` a `AiMessage.from(text)`. Históriu získate cez `memory.messages()` a odošlete ju modelu. Služba uchováva samostatné inštancie pamäte pre každý ID konverzácie, čo umožňuje viacerým používateľom chatovať súčasne. +Vytvorte pamäť s `withMaxMessages(10)` pre uchovanie posledných 10 správ. Pridávajte správy používateľa a AI s typovanými wrappermi: `UserMessage.from(text)` a `AiMessage.from(text)`. Históriu získate cez `memory.messages()` a pošlete modelu. Služba udržiava samostatné inštancie pamäte pre každý ID konverzácie, čo umožňuje viacerým používateľom chatovať súčasne. > **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) a spýtajte sa: > - "Ako MessageWindowChatMemory rozhoduje, ktoré správy zahodiť, keď je okno plné?" -> - "Môžem implementovať vlastné ukladanie pamäte pomocou databázy namiesto pamäte v RAM?" -> - "Ako by som pridal zhrnutie na kompresiu starej histórie konverzácie?" +> - "Môžem implementovať vlastné uloženie pamäte pomocou databázy namiesto pamäte v RAM?" +> - "Ako by som pridal sumarizáciu na kompresiu starej histórie konverzácie?" -Stateless chat endpoint úplne preskočí pamäť — len `chatModel.chat(prompt)` ako v rýchlom štarte. Stateful endpoint pridáva správy do pamäte, získava históriu a zahŕňa tento kontext pri každom požiadavku. Rovnaká konfigurácia modelu, rôzne vzory. +Bezstavový chat endpoint úplne ignoruje pamäť – stačí `chatModel.chat(prompt)` ako v rýchlom štarte. Stavový endpoint pridáva správy do pamäte, získava históriu a zahŕňa ju v každom requeste. Rovnaká konfigurácia modelu, rôzne vzory. ## Nasadenie infraštruktúry Azure OpenAI @@ -144,31 +144,33 @@ azd up # Vyberte predplatné a umiestnenie (odporúča sa eastus2) **PowerShell:** ```powershell cd 01-introduction -azd up # Vyberte predplatné a umiestnenie (odporúčané eastus2) +azd up # Vyberte predplatné a lokalitu (odporúča sa eastus2) ``` -> **Poznámka:** Ak narazíte na chybu timeoutu (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), jednoducho spustite `azd up` znova. Azure zdroje môžu byť stále v procese provisioning, a opakovanie umožní nasadeniu dokončiť sa, keď zdroje dosiahnu konečný stav. -Toto vykoná: -1. Nasadí Azure OpenAI zdroj s GPT-5.2 a modelmi text-embedding-3-small -2. Automaticky vygeneruje `.env` súbor v koreňovom priečinku projektu s prihlasovacími údajmi -3. Nastaví všetky požadované environmentálne premenné +> **Poznámka:** Ak narazíte na chybu časového limitu (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), jednoducho spustite `azd up` znovu. Azure zdroje môžu byť stále procesne vytvárané na pozadí a opakovaný pokus umožní nasadenie dokončiť, keď zdroje dosiahnu konečný stav. -**Máte problémy s nasadením?** Pozrite si [Infrastructure README](infra/README.md) pre podrobné riešenie problémov vrátane konfliktov názvov subdomén, manuálneho nasadenia cez Azure Portal a usmernenia k konfigurácii modelov. +Toto zabezpečí: +1. Nasadenie Azure OpenAI zdroja s GPT-5.2 a modelmi text-embedding-3-small +2. Automatické vygenerovanie `.env` súboru v koreňovom adresári projektu s údajmi pre prístup +3. Nastavenie všetkých potrebných environmentálnych premenných -**Overte úspešnosť nasadenia:** +**Máte problémy s nasadením?** Pozrite si [Infrastructure README](infra/README.md) pre podrobnú pomoc vrátane konfliktov s názvami subdomén, manuálne kroky nasadenia cez Azure Portal a návod na nastavenie modelov. + +**Overte, že nasadenie prebehlo úspešne:** **Bash:** ```bash -cat ../.env # Malo by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, atď. +cat ../.env # Mal by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY a pod. ``` **PowerShell:** ```powershell -Get-Content ..\.env # Malo by sa zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, atď. +Get-Content ..\.env # Malo by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, atď. ``` -> **Poznámka:** Príkaz `azd up` automaticky generuje `.env` súbor. Ak ho budete chcieť neskôr aktualizovať, môžete buď manuálne upraviť `.env` súbor, alebo ho znovu vygenerovať spustením: + +> **Poznámka:** Príkaz `azd up` automaticky vygeneruje `.env` súbor. Ak ho potrebujete neskôr aktualizovať, môžete buď editovať `.env` manuálne, alebo ho znovu vygenerovať spustením: > > **Bash:** > ```bash @@ -182,15 +184,16 @@ Get-Content ..\.env # Malo by sa zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, atď > .\.azd-env.ps1 > ``` + ## Spustenie aplikácie lokálne -**Overte nasadenie:** +**Overenie nasadenia:** -Uistite sa, že `.env` súbor existuje v koreňovom adresári s Azure prihlasovacími údajmi. Spustite toto z adresára modulu (`01-introduction/`): +Uistite sa, že `.env` súbor je v koreňovom adresári s Azure údajmi. Spustite z adresára modulu (`01-introduction/`): **Bash:** ```bash -cat ../.env # Malo by zobrazovať AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Malo by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -198,23 +201,24 @@ cat ../.env # Malo by zobrazovať AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Malo by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Spustite aplikácie:** -**Možnosť 1: Použitie Spring Boot Dashboard (odporúčané pre používateľov VS Code)** +**Spustenie aplikácií:** + +**Možnosť 1: Použitie Spring Boot Dashboard (odporúčané pre VS Code používateľov)** -Dev container obsahuje rozšírenie Spring Boot Dashboard, ktoré poskytuje vizuálne rozhranie na správu všetkých Spring Boot aplikácií. Nájdete ho v Activity Bar na ľavej strane VS Code (ikonka Spring Boot). +Devcontainer obsahuje rozšírenie Spring Boot Dashboard, ktoré poskytuje vizuálne rozhranie na správu všetkých Spring Boot aplikácií. Nájdete ho v Activity Bar na ľavej strane VS Code (hľadajte ikonu Spring Boot). -Zo Spring Boot Dashboard môžete: -- Vidieť všetky dostupné Spring Boot aplikácie v pracovnom priestore -- Jedným kliknutím spustiť/zastaviť aplikácie -- V reálnom čase sledovať logy aplikácie -- Monitorovať stav aplikácií +Z Spring Boot Dashboard môžete: +- vidieť všetky dostupné Spring Boot aplikácie v pracovnom priestore +- jedným kliknutím spustiť/zastaviť aplikácie +- sledovať logy aplikácie v reálnom čase +- monitorovať stav aplikácií -Jednoducho kliknite na tlačidlo play vedľa „introduction“ na spustenie tohto modulu, alebo spustite všetky moduly naraz. +Jednoducho kliknite na tlačidlo spustiť vedľa "introduction" na spustenie tohto modulu, alebo spustite všetky moduly naraz. Spring Boot Dashboard -*Spring Boot Dashboard vo VS Code — spustite, zastavte a monitorujte všetky moduly z jedného miesta* +*Spring Boot Dashboard vo VS Code — spúšťajte, zastavujte a sledujte všetky moduly na jednom mieste* **Možnosť 2: Použitie shell skriptov** @@ -228,10 +232,11 @@ cd .. # Z koreňového adresára **PowerShell:** ```powershell -cd .. # Zo koreňového adresára +cd .. # Zo základného adresára .\start-all.ps1 ``` + Alebo spustite len tento modul: **Bash:** @@ -246,9 +251,10 @@ cd 01-introduction .\start.ps1 ``` -Oba skripty automaticky načítajú environmentálne premenné z koreňového `.env` súboru a vytvoria JAR súbory, ak neexistujú. -> **Poznámka:** Ak chcete pred spustením manuálne zostaviť všetky moduly: +Obe skripty automaticky načítajú environmentálne premenné zo súboru `.env` v koreňovom adresári a zostavia JAR súbory, ak ešte neexistujú. + +> **Poznámka:** Ak preferujete manuálne zostavenie všetkých modulov pred spustením: > > **Bash:** > ```bash @@ -262,9 +268,10 @@ Oba skripty automaticky načítajú environmentálne premenné z koreňového `. > mvn clean package -DskipTests > ``` + Otvorte http://localhost:8080 vo vašom prehliadači. -**Na zastavenie:** +**Ako zastaviť:** **Bash:** ```bash @@ -275,48 +282,49 @@ cd .. && ./stop-all.sh # Všetky moduly **PowerShell:** ```powershell -.\stop.ps1 # Tento modul iba +.\stop.ps1 # Len tento modul # Alebo cd ..; .\stop-all.ps1 # Všetky moduly ``` -## Používanie aplikácie + +## Použitie aplikácie Aplikácia poskytuje webové rozhranie s dvoma chat implementáciami vedľa seba. -Application Home Screen +Domovská obrazovka aplikácie -*Dashboard ukazujúci možnosti Simple Chat (stateless) a Conversational Chat (stateful)* +*Dashboard zobrazuje obidve možnosti – Jednoduchý chat (bezstavový) a Konverzačný chat (stavový)* ### Stateless Chat (ľavý panel) -Vyskúšajte toto ako prvé. Povedzte "Volám sa John" a ihneď sa opýtajte "Ako sa volám?" Model si nepamätá, pretože každá správa je nezávislá. Toto demonštruje základný problém s integráciou jazykových modelov — žiadny kontext konverzácie. +Vyskúšajte najskôr toto. Spýtajte sa "Volám sa John" a potom hneď "Ako sa volám?" Model si nepamätá, pretože každá správa je nezávislá. To demonštruje základný problém integrácie jazykového modelu – bez kontextu konverzácie. -Stateless Chat Demo +Demo bezstavového chatu -*AI si nepamätá vaše meno zo predchádzajúcej správy* +*AI si nepamätá vaše meno z predchádzajúcej správy* ### Stateful Chat (pravý panel) -Teraz vyskúšajte tú istú sekvenciu tu. Povedzte "Volám sa John" a potom "Ako sa volám?" Tentokrát si to pamätá. Rozdiel je MessageWindowChatMemory — udržiava históriu konverzácie a zahrňuje ju do každého požiadavku. Takto funguje produkčné konverzačné AI. +Teraz skúste rovnakú sériu tu. Spýtajte sa "Volám sa John" a potom "Ako sa volám?" Tentokrát si pamätá. Rozdiel je MessageWindowChatMemory – udržiava históriu konverzácie a zahrňuje ju do každého requestu. Takto funguje produkčné konverzačné AI. -Stateful Chat Demo +Demo stavového chatu *AI si pamätá vaše meno z predchádzajúcej konverzácie* -Oba panely používajú rovnaký model GPT-5.2. Jediný rozdiel je pamäť. To jasne ukazuje, čo pamäť prináša vašej aplikácii a prečo je nevyhnutná pre reálne použitie. +Oba panely používajú rovnaký model GPT-5.2. Jediný rozdiel je pamäť. Toto jasne ukazuje, čo pamäť prináša vášmu riešeniu a prečo je nevyhnutná pre reálne použitie. ## Ďalšie kroky -**Ďalší modul:** [02-prompt-engineering - Inžinierstvo promptov s GPT-5.2](../02-prompt-engineering/README.md) +**Ďalší modul:** [02-prompt-engineering - Tvorba promptov s GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigácia:** [← Predchádzajúci: Modul 00 - Rýchly štart](../00-quick-start/README.md) | [Späť na hlavnú stránku](../README.md) | [Ďalší: Modul 02 - Inžinierstvo promptov →](../02-prompt-engineering/README.md) +**Navigácia:** [← Späť na hlavnú stránku](../README.md) | [Ďalej: Modul 02 - Tvorba promptov →](../02-prompt-engineering/README.md) --- **Vyhlásenie o zodpovednosti**: -Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Aj keď sa snažíme o presnosť, prosím berte na vedomie, že automatizované preklady môžu obsahovať chyby alebo nepresnosti. Originálny dokument v jeho rodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre dôležité informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za akékoľvek nedorozumenia alebo chybnú interpretáciu vyplývajúcu z použitia tohto prekladu. +Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za žiadne nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu. \ No newline at end of file diff --git a/translations/sk/02-prompt-engineering/README.md b/translations/sk/02-prompt-engineering/README.md index 172056f00..d13cb1bf1 100644 --- a/translations/sk/02-prompt-engineering/README.md +++ b/translations/sk/02-prompt-engineering/README.md @@ -1,32 +1,32 @@ -# Modul 02: Prompt Engineering s GPT-5.2 +# Modul 02: Inžinierstvo promptov s GPT-5.2 ## Obsah -- [Video Prehľad](../../../02-prompt-engineering) -- [Čo sa naučíte](../../../02-prompt-engineering) -- [Predpoklady](../../../02-prompt-engineering) -- [Pochopenie Prompt Engineering](../../../02-prompt-engineering) -- [Základy Prompt Engineering](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Templates](../../../02-prompt-engineering) -- [Pokročilé vzory](../../../02-prompt-engineering) -- [Spustenie aplikácie](../../../02-prompt-engineering) -- [Screenshoty aplikácie](../../../02-prompt-engineering) -- [Preskúmanie vzorov](../../../02-prompt-engineering) - - [Nízka vs vysoka ochota](../../../02-prompt-engineering) - - [Vykonávanie úloh (predslovy nástrojov)](../../../02-prompt-engineering) - - [Seba-reflektujúci kód](../../../02-prompt-engineering) - - [Štruktúrovaná analýza](../../../02-prompt-engineering) - - [Viackolové konverzácie](../../../02-prompt-engineering) - - [Dôvodovanie krok za krokom](../../../02-prompt-engineering) - - [Obmedzený výstup](../../../02-prompt-engineering) -- [Čo sa naozaj učíte](../../../02-prompt-engineering) -- [Ďalšie kroky](../../../02-prompt-engineering) - -## Video Prehľad +- [Video prehliadka](#video-prehliadka) +- [Čo sa naučíte](#čo-sa-naučíte) +- [Predpoklady](#predpoklady) +- [Pochopenie inžinierstva promptov](#pochopenie-inžinierstva-promptov) +- [Základy inžinierstva promptov](#základy-inžinierstva-promptov) + - [Zero-Shot prompting](#zero-shot-prompting) + - [Few-Shot prompting](#few-shot-prompting) + - [Ťaž ťaže myslenia (Chain of Thought)](#ťaž-ťaže-myslenia-chain-of-thought) + - [Role-Based prompting](#role-based-prompting) + - [Šablóny promptov](#šablóny-promptov) +- [Pokročilé vzory](#pokročilé-vzory) +- [Spustenie aplikácie](#spustenie-aplikácie) +- [Snímky obrazovky aplikácie](#snímky-obrazovky-aplikácie) +- [Preskúmanie vzorov](#preskúmanie-vzorov) + - [Nízka vs vysoká ochota (Eagerness)](#nízká-verzus-vysoká-snaživosť) + - [Vykonávanie úloh (Predslovy nástrojov)](#vykonanie-úlohy-tool-preambles) + - [Sebareflexia kódu](#sebareflektujúci-kód) + - [Štruktúrovaná analýza](#štruktúrovaná-analýza) + - [Viackolový chat](#viackolový-chat) + - [Krok za krokom uvažovanie](#krok-za-krokom-uvažovanie) + - [Obmedzený výstup](#obmedzený-výstup) +- [Čo sa naozaj učíte](#čo-sa-naozaj-učíte) +- [Ďalšie kroky](#ďalšie-kroky) + +## Video prehliadka Pozrite si túto živú reláciu, ktorá vysvetľuje, ako začať s týmto modulom: @@ -34,52 +34,52 @@ Pozrite si túto živú reláciu, ktorá vysvetľuje, ako začať s týmto modul ## Čo sa naučíte -Nasledujúca schéma poskytuje prehľad kľúčových tém a zručností, ktoré v tomto module získate — od techník zdokonaľovania promptov až po postupný pracovný tok, ktorý budete nasledovať. +Nasledujúci diagram poskytuje prehľad kľúčových tém a zručností, ktoré v tomto module rozviniete — od techník dolaďovania promptov až po krok za krokom pracovný postup, ktorý budete nasledovať. -What You'll Learn +Čo sa naučíte -V predchádzajúcich moduloch ste preskúmali základné interakcie LangChain4j s GitHub modelmi a videli ste, ako pamäť umožňuje konverzačné AI s Azure OpenAI. Teraz sa zameriame na to, ako kladiete otázky — samotné promptovanie — pomocou GPT-5.2 od Azure OpenAI. Spôsob, akým štruktúrujete svoje prompty, dramaticky ovplyvňuje kvalitu odpovedí, ktoré dostávate. Začíname prehľadom základných techník promptovania, potom prejdeme na osem pokročilých vzorov, ktoré plne využívajú schopnosti GPT-5.2. +V predchádzajúcom module ste videli, ako pamäť umožňuje konverzačné AI s Azure OpenAI. Teraz sa zameriame na to, ako klásť otázky — samotné prompty — pomocou GPT-5.2 od Azure OpenAI. Spôsob, akým štruktúrujete svoje prompty, výrazne ovplyvňuje kvalitu odpovedí, ktoré dostanete. Začneme prehľadom základných techník promptovania a potom prejdeme k ôsmim pokročilým vzorom, ktoré využívajú plný potenciál GPT-5.2. -Použijeme GPT-5.2, pretože zavádza kontrolu razonovania - môžete modelu povedať, koľko má premýšľať pred odpoveďou. To robí rôzne stratégie promptovania zreteľnejšie a pomáha pochopiť, kedy použiť ktorý prístup. Tiež využijeme výhodu Azure, ktorý má menej obmedzení rýchlosti pre GPT-5.2 v porovnaní s GitHub modelmi. +Použijeme GPT-5.2, pretože predstavuje ovládanie uvažovania - môžete modelu povedať, koľko času má myslieť pred odpoveďou. To robí rôzne stratégie promptovania jasnejšími a pomáha pochopiť, kedy použiť ktorý prístup. ## Predpoklady - Dokončený Modul 01 (nasadené zdroje Azure OpenAI) -- Súbor `.env` v koreňovom adresári s Azure povereniami (vytvorený príkazom `azd up` v Module 01) +- Súbor `.env` v koreňovom adresári s povereniami Azure (vytvorený pomocou `azd up` v Module 01) -> **Poznámka:** Ak ste ešte neukončili Modul 01, najskôr postupujte podľa tamojších inštrukcií nasadenia. +> **Poznámka:** Ak ste Modúl 01 neabsolvovali, najskôr postupujte podľa pokynov na nasadenie tam uvedených. -## Pochopenie Prompt Engineering +## Pochopenie inžinierstva promptov -V jadre je prompt engineering rozdiel medzi nejasnými a presnými inštrukciami, ako ukazuje nasledujúce porovnanie. +V jadre je inžinierstvo promptov rozdiel medzi nejasnými a presnými inštrukciami, ako ukazuje nasledujúce porovnanie. -What is Prompt Engineering? +Čo je inžinierstvo promptov? -Prompt engineering je o navrhovaní vstupného textu, ktorý vám konzistentne prináša požadované výsledky. Nie je to len o kladení otázok - ide o štruktúrovanie požiadaviek tak, aby model presne pochopil, čo chcete a ako to má doručiť. +Inžinierstvo promptov je o navrhovaní vstupného textu, ktorý dôsledne prináša požadované výsledky. Nejde len o kladenie otázok – ide o štruktúrovanie požiadaviek tak, aby model presne pochopil, čo chcete a ako to má dodať. -Predstavte si to ako dávanie inštrukcií kolegovi. "Oprav chybu" je nejasné. "Oprav výnimku null pointer v súbore UserService.java na riadku 45 pridaním kontroly na null" je špecifické. Jazykové modely fungujú rovnako - špecifikácia a štruktúra sú dôležité. +Predstavte si to ako poskytovanie inštrukcií kolegovi. „Oprav chybu“ je nejasné. „Oprav NullPointerException v UserService.java na riadku 45 pridaním kontroly null“ je špecifické. Jazykové modely fungujú rovnako – dôležitá je špecifickosť a štruktúra. -Nasledujúca schéma ukazuje, ako sa LangChain4j tohto procesu zúčastňuje — prepája vaše vzory promptov s modelom cez stavebné bloky SystemMessage a UserMessage. +Nasledujúci diagram ukazuje, ako do toho zapadá LangChain4j — prepájajúc vaše vzory promptov s modelom cez stavebný blok SystemMessage a UserMessage. -How LangChain4j Fits +Ako zapadá LangChain4j -LangChain4j poskytuje infraštruktúru — pripojenia k modelu, pamäť a typy správ — zatiaľ čo vzory promptov sú len starostlivo štruktúrovaný text, ktorý cez túto infraštruktúru posielate. Kľúčové stavebné bloky sú `SystemMessage` (ktorý nastavuje správanie a rolu AI) a `UserMessage` (ktorý nesie vašu skutočnú požiadavku). +LangChain4j poskytuje infraštruktúru — pripojenia k modelom, pamäť a typy správ — zatiaľ čo vzory promptov sú len starostlivo štruktúrovaným textom, ktorý posielate touto infraštruktúrou. Kľúčovými stavebnými blokmi sú `SystemMessage` (ktorý nastavuje správanie AI a jej rolu) a `UserMessage` (ktorý nesie vašu reálnu požiadavku). -## Základy Prompt Engineering +## Základy inžinierstva promptov -Päť základných techník zobrazených nižšie tvorí základ efektívneho prompt engineeringu. Každá rieši iný aspekt toho, ako komunikujete s jazykovými modelmi. +Päť základných techník uvedených nižšie tvorí základ efektívneho inžinierstva promptov. Každá sa zameriava na iný aspekt komunikácie s jazykovými modelmi. -Five Prompt Engineering Patterns Overview +Prehľad piatich vzorov inžinierstva promptov -Predtým, než sa ponoríme do pokročilých vzorov v tomto module, prejdime si päť základných techník promptovania. Sú to stavebné kamene, ktoré by mal poznať každý prompt inžinier. Ak ste už prešli cez [Quick Start modul](../00-quick-start/README.md#2-prompt-patterns), videli ste ich v akcii — tu je konceptuálny rámec za nimi. +Predtým, než sa pustíme do pokročilých vzorov v tomto module, pozrime sa na päť základných techník promptovania. Sú to stavebné kamene, ktoré by mal každý prompt inžinier poznať. -### Zero-Shot Prompting +### Zero-Shot prompting -Najjednoduchší prístup: dajte modelu priamu inštrukciu bez príkladov. Model sa spolieha výhradne na svoje tréningové dáta, aby pochopil a vykonal úlohu. Funguje to dobre pri jednoznačných požiadavkách, kde je očakávané správanie zrejmé. +Najjednoduchší prístup: dajte modelu priamu inštrukciu bez príkladov. Model sa spolieha výhradne na svoje tréningové dáta, aby pochopil a vykonal úlohu. Funguje to dobre pre priamočiare požiadavky, kde je očakávané správanie zrejmé. -Zero-Shot Prompting +Zero-Shot prompting -*Priama inštrukcia bez príkladov — model vyvodzuje úlohu z inštrukcie samotnej* +*Priama inštrukcia bez príkladov — model odvodí úlohu iba z inštrukcie* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Odpoveď: "Pozitívne" ``` -**Kedy použiť:** Jednoduché klasifikácie, priame otázky, preklady alebo akúkoľvek úlohu, ktorú model zvládne bez ďalších pokynov. +**Kedy použiť:** Jednoduché klasifikácie, priame otázky, preklady alebo akákoľvek úloha, ktorú model zvládne bez ďalších pokynov. -### Few-Shot Prompting +### Few-Shot prompting -Poskytnite príklady, ktoré demonštrujú vzor, ktorý chcete, aby model nasledoval. Model sa naučí očakávaný formát vstupu a výstupu z vašich príkladov a aplikuje ho na nové vstupy. Toto výrazne zlepšuje konzistenciu pri úlohách, kde požadovaný formát alebo správanie nie je zrejmé. +Poskytnite príklady, ktoré demonštrujú vzor, podľa ktorého má model postupovať. Model sa z vašich príkladov naučí očakávaný formát vstupu a výstupu a aplikuje ho na nové vstupy. Výrazne to zlepšuje konzistentnosť pri úlohách, kde nie je formát alebo správanie zrejmé. -Few-Shot Prompting +Few-Shot prompting -*Učenie sa z príkladov — model identifikuje vzor a aplikuje ho na nové vstupy* +*Naučenie sa z príkladov — model identifikuje vzor a aplikuje ho na nové vstupy* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kedy použiť:** Vlastné klasifikácie, konzistentné formátovanie, špecifické doménové úlohy alebo ak sú výsledky zero-shot nejednoznačné. +**Kedy použiť:** Vlastné klasifikácie, konzistentné formátovanie, úlohy špecifické pre danú doménu alebo keď sú výsledky pri zero-shot nekonzistentné. -### Chain of Thought +### Ťaž ťaže myslenia (Chain of Thought) -Požiadajte model, aby ukázal svoje zdôvodnenie krok za krokom. Namiesto okamžitej odpovede model rozkladá problém a explicitne rieši každú časť. To zlepšuje presnosť pri matematike, logike a viacstupňových razonovacích úlohách. +Požiadajte model, aby ukázal svoje uvažovanie krok za krokom. Namiesto toho, aby preskočil priamo na odpoveď, model rozdelí problém a prejde každou časťou explicitne. To zlepšuje presnosť pri matematike, logike a viacstupňovom uvažovaní. -Chain of Thought Prompting +Chain of Thought prompting -*Dôvodovanie krok za krokom — rozkladanie komplexných problémov na explicitné logické kroky* +*Krok za krokom uvažovanie — rozkladanie zložitých problémov na explicitné logické kroky* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Model ukazuje: 15 - 8 = 7, potom 7 + 12 = 19 jabĺk ``` -**Kedy použiť:** Matematické problémy, logické hádanky, ladenie chýb alebo akákoľvek úloha, kde zobrazenie procesu razonovania zvyšuje presnosť a dôveru. +**Kedy použiť:** Matematické problémy, logické hádanky, ladenie chýb alebo akákoľvek úloha, kde zobrazenie uvažovacieho procesu zvyšuje presnosť a dôveru. -### Role-Based Prompting +### Role-Based prompting -Nastavte AI personu alebo rolu pred položením otázky. To poskytuje kontext, ktorý formuje tón, hĺbku a fokus odpovede. "Softvérový architekt" dáva iné rady než "junior vývojár" alebo "auditor bezpečnosti". +Nastavte personu alebo rolu AI pred položením otázky. Poskytuje to kontext, ktorý formuje tón, hĺbku a zameranie odpovede. „Softvérový architekt“ dáva iné rady ako „junior vývojár“ alebo „audítor bezpečnosti“. -Role-Based Prompting +Role-Based prompting -*Nastavenie kontextu a persony — rovnaká otázka dostane odlišnú odpoveď podľa pridanej role* +*Nastavenie kontextu a persony — tá istá otázka dostane inú odpoveď podľa priradenej roly* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kedy použiť:** Kontroly kódu, doučovanie, špecifická doménová analýza alebo keď potrebujete odpovede prispôsobené určitej úrovni odbornosti či perspektíve. +**Kedy použiť:** Kontroly kódu, doučovanie, analýzy špecifické pre doménu alebo keď potrebujete odpovede prispôsobené určitej odbornej úrovni alebo perspektíve. -### Prompt Templates +### Šablóny promptov -Vytvorte znovupoužiteľné prompty s premennými zástupcami. Namiesto písania nového promptu zakaždým, definujte šablónu raz a vyplňujte rôzne hodnoty. Trieda `PromptTemplate` v LangChain4j to uľahčuje pomocou syntaxe `{{variable}}`. +Vytvárajte znovupoužiteľné prompty s premennými zástupcami. Namiesto písania nového promptu zakaždým definujte šablónu raz a dopĺňajte rôzne hodnoty. Trieda `PromptTemplate` v LangChain4j to uľahčuje pomocou syntaxe `{{variable}}`. -Prompt Templates +Šablóny promptov -*Znovupoužiteľné prompty s premennými zástupcami — jedna šablóna, mnoho využití* +*Znovupoužiteľné prompty s premennými zástupcami — jedna šablóna, mnoho použitia* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Kedy použiť:** Opakované dopyty s rôznymi vstupmi, dávkové spracovanie, budovanie znovupoužiteľných AI pracovných tokov alebo akýkoľvek scenár, kde sa štruktúra promptu nemení, ale údaje áno. +**Kedy použiť:** Opakované otázky s rôznymi vstupmi, hromadné spracovanie, tvorba znovupoužiteľných AI pracovných tokov alebo akýkoľvek scenár, kde štruktúra promptu zostáva rovnaká, ale menia sa dáta. --- -Tieto päť základov vám poskytuje pevný nástrojový súbor pre väčšinu promptovacích úloh. Zvyšok tohto modulu na nich stavia s **osem pokročilými vzormi**, ktoré využívajú razonovaciu kontrolu, sebahodnotenie a schopnosti štruktúrovaného výstupu GPT-5.2. +Tieto päť základov vám poskytuje pevný nástrojový set pre väčšinu úloh promptovania. Zvyšok tohto modulu na nich stavia pomocou **osem pokročilých vzorov**, ktoré využívajú ovládanie uvažovania, sebahodnotenie a štruktúrované výstupy GPT-5.2. ## Pokročilé vzory -Keďže základné techniky sú pokryté, poďme k ôsmim pokročilým vzorom, ktoré robia tento modul jedinečným. Nie všetky problémy vyžadujú rovnaký prístup. Niektoré otázky potrebujú rýchle odpovede, iné hlboké premýšľanie. Niektoré potrebujú viditeľné razonovanie, iné len výsledky. Každý z nižšie uvedených vzorov je optimalizovaný pre inú situáciu — a razonovacia kontrola GPT-5.2 robí rozdiely ešte výraznejšími. +Po pokrytí základov prejdime na osem pokročilých vzorov, ktoré robia tento modul jedinečným. Nie všetky problémy vyžadujú rovnaký prístup. Niektoré otázky potrebujú rýchle odpovede, iné hlboké uvažovanie. Niektoré potrebujú viditeľné uvažovanie, iné len výsledky. Každý vzor nižšie je optimalizovaný pre iný scenár — a ovládanie uvažovania GPT-5.2 robí rozdiely ešte výraznejšími. -Eight Prompting Patterns +Osem vzorov promptingu -*Prehľad ôsmich vzorov prompt engineeringu a ich použitia* +*Prehľad ôsmich vzorov inžinierstva promptov a ich prípadov použitia* -GPT-5.2 pridáva ďalšiu dimenziu k týmto vzorom: *kontrolu razonovania*. Posuvník nižšie ukazuje, ako môžete upraviť rozsah premýšľania modelu — od rýchlych, priamych odpovedí po hlbokú, dôkladnú analýzu. +GPT-5.2 pridáva ďalší rozmer k týmto vzorom: *ovládanie uvažovania*. Posuvník nižšie ukazuje, ako môžete nastaviť úsilie modelu o premýšľanie — od rýchlych, priamych odpovedí po hlbokú, dôkladnú analýzu. -Reasoning Control with GPT-5.2 +Ovládanie uvažovania s GPT-5.2 -*Razonovacia kontrola GPT-5.2 vám umožňuje špecifikovať, koľko má model rozmýšľať — od rýchlych priamych odpovedí po hlboké skúmanie* +*Ovládanie uvažovania GPT-5.2 vám umožňuje špecifikovať, koľko má model myslieť — od rýchlych priamych odpovedí po hlboký prieskum* -**Nízka ochota (rýchle a zamerané)** - Pre jednoduché otázky, kde chcete rýchle, priame odpovede. Model vykoná minimálne razonovanie - maximálne 2 kroky. Použite to na výpočty, vyhľadávania alebo jednoznačné otázky. +**Nízka ochota (Rýchle a zamerané)** - Pre jednoduché otázky, kde chcete rýchle, priame odpovede. Model robí minimálne uvažovanie - maximálne 2 kroky. Použite to na výpočty, vyhľadávania alebo priamočiare otázky. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Preskúmajte s GitHub Copilot:** Otvorte [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) a spýtajte sa: -> - "Aký je rozdiel medzi nízkou a vysokou ochotou pri promptovacích vzoroch?" -> - "Ako XML značky v promptoch pomáhajú štruktúrovať odpoveď AI?" -> - "Kedy mám použiť vzory so sebareflexiou oproti priamej inštrukcii?" +> - „Aký je rozdiel medzi nízkou a vysokou ochotou v promptovacích vzoroch?“ +> - „Ako pomáhajú XML značky v promptoch štruktúrovať odpoveď AI?“ +> - „Kedy by som mal použiť vzory sebareflexie namiesto priamej inštrukcie?“ -**Vysoká ochota (hlboké a dôkladné)** - Pre komplexné problémy, kde chcete komplexnú analýzu. Model dôkladne skúma a ukazuje podrobné zdôvodnenia. Použite to na návrhy systémov, rozhodnutia o architektúre alebo komplexný výskum. +**Vysoká ochota (Hlboké a dôkladné)** - Pre zložité problémy, kde chcete komplexnú analýzu. Model skúma dôkladne a ukazuje detailné uvažovanie. Použite to na návrhy systémov, rozhodnutia o architektúre alebo zložité výskumy. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Vykonávanie úloh (postupný pokrok)** - Pre viacstupňové pracovné toky. Model poskytne plán vopred, komentuje každý krok pri práci a potom dá zhrnutie. Použite to pri migráciách, implementáciách alebo akomkoľvek viacstupňovom procese. +**Vykonávanie úloh (Pokrok krok za krokom)** - Pre viacstupňové pracovné toky. Model poskytne dopredu plán, rozpráva každý krok počas práce a potom dá zhrnutie. Použite to na migrácie, implementácie alebo akýkoľvek proces s viacerými krokmi. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Promptovanie Chain-of-Thought explicitne žiada model, aby ukázal proces razonovania, čím zlepšuje presnosť pri zložitých úlohách. Postupné rozdelenie pomáha ľuďom aj AI pochopiť logiku. +Chain-of-Thought prompting explicitne žiada model, aby ukázal svoj uvažovací proces, čím sa zlepšuje presnosť pri zložitých úlohách. Postupné rozkladanie pomáha pochopiť logiku ľuďom aj AI. -> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Spýtajte sa na tento vzor: -> - "Ako by som upravil vzor vykonávania úloh pre dlhodobé operácie?" -> - "Aké sú najlepšie praktiky pre štrukturovanie predslovov nástrojov v produkčných aplikáciách?" -> - "Ako zachytiť a zobrazovať priebežné aktualizácie pokroku v UI?" +> **🤖 Vyskúšajte s chatom [GitHub Copilot](https://github.com/features/copilot):** Spýtajte sa na tento vzor: +> - „Ako by som prispôsobil vzor vykonávania úloh pre dlhodobé operácie?“ +> - „Aké sú najlepšie praktiky pre štruktúrovanie predslovov nástrojov v produkčných aplikáciách?“ +> - „Ako môžem zachytiť a zobraziť priebežné aktualizácie pokroku v UI?“ -Schéma nižšie ilustruje pracovný tok Plán → Vykonaj → Zhrň. +Nasledujúci diagram znázorňuje pracovný tok Plánuj → Vykonaj → Zhrň. -Task Execution Pattern +Vzor vykonávania úloh -*Pracovný tok Plán → Vykonaj → Zhrň pre viacstupňové úlohy* +*Pracovný tok Plánuj → Vykonaj → Zhrň pre viacstupňové úlohy* -**Seba-reflektujúci kód** - Pre generovanie produkčne kvalitného kódu. Model generuje kód v súlade s produkčnými štandardmi s riadnym spracovaním chýb. Použite to pri budovaní nových funkcií alebo služieb. +**Sebareflexia kódu** - Na generovanie kódu vhodného pre produkciu. Model generuje kód podľa produkčných štandardov s riadnym zvládaním chýb. Použite to pri tvorbe nových funkcií alebo služieb. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Schéma nižšie ukazuje tento iteratívny cyklus zlepšovania — generuj, vyhodnoť, identifikuj nedostatky a dolad až kým kód spĺňa produkčné štandardy. +Nasledujúci diagram ukazuje túto iteratívnu slučku zlepšovania — generuj, vyhodnoť, identifikuj slabiny a dolaďuj, kým kód nespĺňa produkčné štandardy. -Self-Reflection Cycle +Cyklus sebareflexie -*Iteratívny cyklus zlepšovania - generovať, hodnotiť, identifikovať problémy, zlepšovať, opakovať* +*Iteratívna slučka zlepšovania - generovať, hodnotiť, identifikovať problémy, zdokonaľovať, opakovať* -**Štruktúrovaná analýza** - Pre konzistentné hodnotenie. Model hodnotí kód pomocou pevne stanovenej štruktúry (správnosť, postupy, výkon, bezpečnosť, udržiavateľnosť). Použite to na kontrolu kódu alebo hodnotenie kvality. +**Štruktúrovaná analýza** - Pre konzistentné hodnotenie. Model kontroluje kód pomocou pevného rámca (správnosť, praktiky, výkon, bezpečnosť, udržiavateľnosť). Použite to na kódové revízie alebo hodnotenia kvality. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Spýtajte sa na štruktúrovanú analýzu: -> - "Ako prispôsobiť analytický rámec pre rôzne typy kontrol kódu?" -> - "Aký je najlepší spôsob, ako programovo spracovať a reagovať na štruktúrovaný výstup?" -> - "Ako zabezpečiť konzistentné úrovne závažnosti naprieč rôznymi kontrolnými sedeními?" +> **🤖 Vyskúšajte s chatom [GitHub Copilot](https://github.com/features/copilot):** Spýtajte sa na štruktúrovanú analýzu: +> - „Ako si môžem prispôsobiť rámec analýzy pre rôzne typy kódových revízií?“ +> - „Aký je najlepší spôsob, ako programovo spracovať a reagovať na štruktúrovaný výstup?“ +> - „Ako zabezpečiť konzistentné úrovne závažnosti naprieč rôznymi kontrolnými reláciami?“ -Nasledujúca schéma ukazuje, ako táto štruktúrovaná rámcová analýza organizuje kontrolu kódu do konzistentných kategórií s úrovňami závažnosti. +Nasledujúci diagram ukazuje, ako tento štruktúrovaný rámec organizuje kontrolu kódu do konzistentných kategórií s úrovňami závažnosti. -Structured Analysis Pattern +Vzor štruktúrovanej analýzy -*Rámec pre konzistentné kontroly kódu s úrovňami závažnosti* +*Rámec pre konzistentné revízie kódu s úrovňami závažnosti* -**Viackolové konverzácie** - Pre rozhovory, ktoré potrebujú kontext. Model si pamätá predchádzajúce správy a buduje na nich. Použite to na interaktívnu pomoc alebo zložité otázky a odpovede. +**Viackolový chat** - Pre konverzácie, ktoré potrebujú kontext. Model si pamätá predchádzajúce správy a nadväzuje na ne. Použite to na interaktívne pomoci alebo zložité otázky a odpovede. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Schéma nižšie vizualizuje, ako sa konverzačný kontext s každým kolom kumuluje a ako súvisí s limitom tokenov modelu. +Nasledujúci diagram vizualizuje, ako sa kontext konverzácie hromadí s každým kolom a ako súvisí so limitom tokenov modelu. -Context Memory +Pamäť kontextu -*Ako sa konverzačný kontext kumuluje cez viaceré kolá až do dosiahnutia limitu tokenov* -**Krok za krokom vysvetlenie** - Pre problémy vyžadujúce viditeľnú logiku. Model ukazuje explicitné zdôvodnenie pre každý krok. Použite to pri matematických úlohách, logických hádankách alebo keď potrebujete pochopiť myšlienkový proces. +*Ako sa kontext konverzácie hromadí počas viacerých kôl až do dosiahnutia limitu tokenov* + +**Krok za krokom uvažovanie** - Pre problémy vyžadujúce viditeľnú logiku. Model ukazuje explicitné uvažovanie pre každý krok. Použite to na matematické problémy, logické hádanky alebo ak potrebujete pochopiť uvažovací proces. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Nižšie uvedený diagram zobrazuje, ako model rozdeľuje problémy na explicitné, číslované logické kroky. - -Step-by-Step Pattern +Nasledujúci diagram ilustruje, ako model rozkladá problémy na explicitné, očíslované logické kroky. +Vzor krok za krokom *Rozkladanie problémov na explicitné logické kroky* -**Obmedzený výstup** - Pre odpovede s konkrétnymi požiadavkami na formát. Model striktne dodržiava pravidlá formátu a dĺžky. Použite to na súhrny alebo keď potrebujete presnú štruktúru výstupu. +**Obmedzený výstup** – Pre odpovede so špecifickými požiadavkami na formát. Model prísne dodržiava pravidlá formátu a dĺžky. Použite to na zhrnutia alebo keď potrebujete presnú štruktúru výstupu. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Nasledujúci diagram ukazuje, ako obmedzenia usmerňujú model vytvoriť výstup, ktorý striktne dodržiava vaše požiadavky na formát a dĺžku. +Nasledujúci diagram ukazuje, ako obmedzenia vedú model k vytváraniu výstupu, ktorý prísne dodržiava vaše požiadavky na formát a dĺžku. Constrained Output Pattern -*Nútenie dodržiavania špecifických požiadaviek na formát, dĺžku a štruktúru* +*Vynucovanie konkrétnych požiadaviek na formát, dĺžku a štruktúru* ## Spustenie aplikácie **Overenie nasadenia:** -Uistite sa, že súbor `.env` existuje v koreňovom adresári s údajmi Azure (vytvorený počas Modulu 01). Spustite to z adresára modulu (`02-prompt-engineering/`): +Uistite sa, že súbor `.env` existuje v koreňovom adresári s prihlasovacími údajmi Azure (vytvorený počas Modulu 01). Spustite toto z adresára modulu (`02-prompt-engineering/`): **Bash:** ```bash @@ -444,23 +444,23 @@ Get-Content ..\.env # Malo by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Spustenie aplikácie:** -> **Poznámka:** Ak ste už spustili všetky aplikácie pomocou `./start-all.sh` z koreňového adresára (ako je popísané v Module 01), tento modul už beží na porte 8083. Môžete vynechať príkazy na spustenie nižšie a ísť priamo na http://localhost:8083. +> **Poznámka:** Ak ste už spustili všetky aplikácie pomocou `./start-all.sh` z koreňového adresára (ako je popísané v Module 01), tento modul už beží na porte 8083. Môžete preto preskočiť nižšie uvedené príkazy na spustenie a ísť priamo na http://localhost:8083. **Možnosť 1: Použitie Spring Boot Dashboard (Odporúčané pre používateľov VS Code)** -Vývojové prostredie obsahuje rozšírenie Spring Boot Dashboard, ktoré poskytuje vizuálne rozhranie na správu všetkých Spring Boot aplikácií. Nájdete ho na Paneli aktivít na ľavej strane VS Code (hľadajte ikonu Spring Boot). +Vývojový kontajner obsahuje rozšírenie Spring Boot Dashboard, ktoré poskytuje vizuálne rozhranie na správu všetkých Spring Boot aplikácií. Nájdete ho na bočnom paneli vľavo vo VS Code (ikona Spring Boot). Zo Spring Boot Dashboard môžete: - Vidieť všetky dostupné Spring Boot aplikácie v pracovnom priestore -- Jedným kliknutím spustiť/zastaviť aplikácie +- Spustiť/zastaviť aplikácie jediným kliknutím - Sledovať logy aplikácie v reálnom čase - Monitorovať stav aplikácie -Jednoducho kliknite na tlačidlo prehrávania vedľa "prompt-engineering" pre spustenie tohto modulu, alebo spustite všetky moduly naraz. +Jednoducho kliknite na tlačidlo pre spustenie vedľa "prompt-engineering" pre spustenie tohto modulu, alebo spustite všetky moduly naraz. Spring Boot Dashboard -*Spring Boot Dashboard vo VS Code — spustite, zastavte a sledujte všetky moduly z jedného miesta* +*Spring Boot Dashboard vo VS Code — spustite, zastavte a monitorujte všetky moduly z jedného miesta* **Možnosť 2: Použitie shell skriptov** @@ -492,7 +492,7 @@ cd 02-prompt-engineering .\start.ps1 ``` -Oba skripty automaticky načítajú premenné prostredia z koreňového `.env` súboru a zostavia JAR súbory, ak neexistujú. +Oba skripty automaticky načítajú premenné prostredia z koreňového súboru `.env` a zostavia JARy, ak ešte neexistujú. > **Poznámka:** Ak chcete radšej zostaviť všetky moduly manuálne pred spustením: > @@ -508,25 +508,25 @@ Oba skripty automaticky načítajú premenné prostredia z koreňového `.env` s > mvn clean package -DskipTests > ``` -Otvorte http://localhost:8083 vo svojom prehliadači. +Otvorte http://localhost:8083 vo vašom prehliadači. **Na zastavenie:** **Bash:** ```bash -./stop.sh # Iba tento modul +./stop.sh # Tento modul iba # Alebo cd .. && ./stop-all.sh # Všetky moduly ``` **PowerShell:** ```powershell -.\stop.ps1 # Tento modul iba +.\stop.ps1 # Len tento modul # Alebo cd ..; .\stop-all.ps1 # Všetky moduly ``` -## Screenshoty aplikácie +## Snímky obrazovky aplikácie Tu je hlavné rozhranie modulu prompt engineering, kde môžete experimentovať so všetkými ôsmimi vzormi vedľa seba. @@ -536,73 +536,73 @@ Tu je hlavné rozhranie modulu prompt engineering, kde môžete experimentovať ## Preskúmanie vzorov -Webové rozhranie vám umožňuje experimentovať s rôznymi stratégiami promptovania. Každý vzor rieši odlišné problémy – vyskúšajte ich a zistite, kedy ktorý prístup vynikne. +Webové rozhranie vám umožňuje experimentovať s rôznymi stratégiami promptovania. Každý vzor rieši iné problémy – vyskúšajte ich, aby ste videli, kedy každý prístup exceluje. -> **Poznámka: Streamovanie vs Nestreamovanie** — Každá stránka s vzorom ponúka dva tlačidlá: **🔴 Stream Response (Live)** a možnosť **Nestreamovanie**. Streamovanie používa Server-Sent Events (SSE) na zobrazenie tokenov v reálnom čase, keď ich model generuje, takže vidíte postup okamžite. Nestreamovanie čaká na celú odpoveď, až potom ju zobrazí. Pre prompt-y vyžadujúce hlboké uvažovanie (napr. High Eagerness, Self-Reflecting Code) môže nestreamovanie trvať veľmi dlho — niekedy minúty — bez viditeľnej spätnej väzby. **Používajte streamovanie pri experimentoch s komplexnými promptami**, aby ste videli model pracovať a predišli dojmu, že požiadavka vypršala. +> **Poznámka: Streaming vs Non-Streaming** — Každá stránka vzoru ponúka dve tlačidlá: **🔴 Stream Response (Live)** a **Non-streaming** možnosť. Streaming používa Server-Sent Events (SSE) na zobrazovanie tokenov v reálnom čase, ako ich model generuje, takže vidíte priebeh okamžite. Non-streaming možnosť počká na celú odpoveď pred zobrazením. Pre prompt-y, ktoré vyžadujú hlboké uvažovanie (napr. High Eagerness, Self-Reflecting Code) môže non-streaming volanie trvať veľmi dlho – niekedy minúty – bez viditeľnej spätnej väzby. **Používajte streaming pri experimentovaní s komplexnými promptmi**, aby ste videli model pracovať a predišli dojmu, že požiadavka stroskotala. > -> **Poznámka: Požiadavka na prehliadač** — Funkcia streamovania používa Fetch Streams API (`response.body.getReader()`), ktoré vyžaduje plnohodnotný prehliadač (Chrome, Edge, Firefox, Safari). Nepracuje vo VS Code zabudovanom Simple Browser, pretože jeho webview nepodporuje ReadableStream API. Ak používate Simple Browser, tlačidlá pre nestreamovanie budú fungovať normálne — postihnuté sú len tlačidlá pre streamovanie. Pre úplný zážitok otvorte `http://localhost:8083` v externom prehliadači. +> **Poznámka: Požiadavka na prehliadač** — Funkcia streamingu používa Fetch Streams API (`response.body.getReader()`), ktoré vyžaduje plnohodnotný prehliadač (Chrome, Edge, Firefox, Safari). Nepracuje vo VS Code zabudovanom Simple Browser, pretože jeho webview nepodporuje ReadableStream API. Ak používate Simple Browser, non-streaming tlačidlá budú fungovať normálne – postihnuté sú len tlačidlá streamingu. Pre plný zážitok otvorte `http://localhost:8083` v externom prehliadači. -### Nízka vs vysoká snaha (Eagerness) +### Nízká verzus vysoká snaživosť -Opýtajte sa jednoduchú otázku, napríklad „Čo je 15 % zo 200?“ pomocou Nízkej snahe. Dostanete okamžitú, priamu odpoveď. Teraz sa opýtajte niečo zložité, napríklad „Navrhnite caching stratégiu pre vysokotrafikovú API“ pomocou Vysokej snahy. Kliknite na **🔴 Stream Response (Live)** a sledujte, ako sa token po tokene objavuje podrobné zdôvodnenie modelu. Rovnaký model, rovnaká štruktúra otázky – ale prompt mu hovorí, koľko premýšľania má urobiť. +Opýtajte sa jednoduchú otázku ako "Koľko je 15% z 200?" s nízkou snaživosťou. Dostanete okamžitú, priamu odpoveď. Teraz sa spýtajte niečo zložité ako "Navrhnite stratégiu cachovania pre API s vysokou záťažou" s vysokou snaživosťou. Kliknite na **🔴 Stream Response (Live)** a sledujte, ako sa podrobné uvažovanie modelu zobrazuje token po tokene. Rovnaký model, rovnaká štruktúra otázky – ale prompt hovorí, koľko má model premýšľať. -### Vykonávanie úloh (předslovné nástroje) +### Vykonanie úlohy (Tool Preambles) -Workflows s viacerými krokmi profitujú z vopred plánovania a priebežného rozprávania. Model načrtne, čo urobí, popíše každý krok, potom zhrnie výsledky. +Viacstupňové pracovné postupy profitujú z vopred naplánovania a rozprávania priebehu. Model načrtne, čo urobí, popisuje každý krok a potom zhrnie výsledky. -### Samo-reflektujúci kód +### Sebareflektujúci kód -Vyskúšajte „Vytvorte službu na validáciu emailov“. Namiesto toho, aby model len vygeneroval kód a zastavil sa, generuje, hodnotí podľa kvalitatívnych kritérií, identifikuje slabé miesta a zlepšuje ho. Uvidíte, ako iteruje, kým kód nespĺňa produkčné štandardy. +Vyskúšajte "Vytvor službu na validáciu e-mailov". Namiesto toho, aby len generoval kód a skončil, model vytvára, vyhodnocuje podľa kritérií kvality, identifikuje slabé miesta a zlepšuje. Uvidíte, ako iteruje, kým kód nespĺňa produkčné štandardy. ### Štruktúrovaná analýza -Kontroly kódu vyžadujú konzistentné hodnotiace rámce. Model analyzuje kód s použitím pevných kategórií (správnosť, praktiky, výkon, bezpečnosť) a úrovní závažnosti. +Code review vyžaduje konzistentné hodnotiace rámce. Model analyzuje kód pomocou pevných kategórií (správnosť, praktiky, výkon, bezpečnosť) so stupňami závažnosti. -### Viackrokový chat +### Viackolový chat -Opýtajte sa „Čo je Spring Boot?“ a potom hneď pokračujte otázkou „Ukáž mi príklad“. Model si pamätá vašu prvú otázku a poskytne vám konkrétny príklad Spring Boot. Bez pamäti by druhá otázka bola príliš všeobecná. +Opýtajte sa "Čo je Spring Boot?" a hneď potom "Ukáž mi príklad". Model si pamätá vašu prvú otázku a poskytne konkrétny príklad Spring Boot. Bez pamäte by druhá otázka bola príliš nejasná. -### Krok za krokom zdôvodnenie +### Krok za krokom uvažovanie -Vyberte matematický problém a vyskúšajte ho s Krok za krokom zdôvodnením aj Nízku snahu. Nízka snaha vám len rýchlo dá odpoveď, no bez vysvetlenia. Krok za krokom vám ukáže každý výpočet a rozhodnutie. +Vyberte matematický problém a vyskúšajte ho s Krok za krokom uvažovaním aj s nízkou snaživosťou. Nízka snaživosť len dáva odpoveď – rýchlo, ale neprehľadne. Krok za krokom vám ukáže každý výpočet a rozhodnutie. ### Obmedzený výstup -Keď potrebujete konkrétne formáty alebo počet slov, tento vzor vynucuje prísne dodržiavanie pravidiel. Vyskúšajte generovanie súhrnu presne so 100 slovami v odrážkach. +Keď potrebujete konkrétny formát alebo počet slov, tento vzor vynucuje prísne dodržiavanie. Vyskúšajte generovať zhrnutie presne so 100 slovami v bodoch. ## Čo sa naozaj učíte -**Snahou o zdôvodnenie sa mení všetko** +**Úsilie o uvažovanie mení všetko** -GPT-5.2 vám umožňuje kontrolovať výpočtové úsilie cez vaše prompt-y. Nízke úsilie znamená rýchle odpovede s minimálnym skúmaním. Vysoké úsilie znamená, že model si dá čas na dôkladné premýšľanie. Učíte sa prispôsobiť úsilie zložitosti úlohy – nestrácajte čas na jednoduché otázky, ale ani neponáhľajte zložité rozhodnutia. +GPT-5.2 vám umožňuje ovládať výpočtové úsilie cez vaše prompty. Nízke úsilie znamená rýchle odpovede s minimálnym preskúmaním. Vysoké úsilie znamená, že model si dá čas na hlboké premýšľanie. Učíte sa prispôsobiť úsilie zložitosti úlohy – nestrácajte čas na jednoduché otázky, ale ani neponáhľajte zložité rozhodnutia. -**Štruktúra usmerňuje správanie** +**Štruktúra riadi správanie** -Všimli ste si XML tagy v promptoch? Nie sú len dekoratívne. Modely dôveryhodnejšie nasledujú štruktúrované inštrukcie než voľný text. Keď potrebujete viacstupňové procesy alebo komplexnú logiku, štruktúra pomáha modelu sledovať, kde je a čo nasleduje. Nižšie uvedený diagram rozkladá dobre štruktúrovaný prompt, ukazujúc ako tagy ``, ``, ``, `` a `` organizujú vaše inštrukcie do prehľadných sekcií. +Všímajte si XML značky v promptoch? Nie sú dekoratívne. Modely spoľahlivejšie dodržiavajú štruktúrované inštrukcie než voľný text. Ak potrebujete viacstupňové procesy alebo komplexnú logiku, štruktúra pomáha modelu sledovať, kde sa nachádza a čo príde ďalej. Nižšie uvedený diagram rozkladá dobre štruktúrovaný prompt, ukazujúc, ako značky ako ``, ``, ``, ``, a `` organizujú vaše inštrukcie do jasných sekcií. Prompt Structure -*Anatómia dobre štruktúrovaného promptu s jasnými sekciami a XML štýlom organizácie* +*Anatómia dobre štruktúrovaného promptu s jasnými sekciami a XML-štýlovou organizáciou* -**Kvalita cez samo-hodnotenie** +**Kvalita cez seba-hodnotenie** -Samo-reflektujúce vzory fungujú tak, že explicitne uvedú kvalitatívne kritériá. Namiesto dúfania, že model „to urobí správne“, mu presne poviete, čo znamená „správne“: správna logika, spracovanie chýb, výkon, bezpečnosť. Model potom dokáže ohodnotiť vlastný výstup a zlepšiť ho. To premieňa generovanie kódu z lotérie na proces. +Sebareflektujúce vzory fungujú tak, že robia kritériá kvality explicitnými. Namiesto toho, aby ste dúfali, že model „to spraví správne“, presne mu hovoríte, čo „správne“ znamená: korektná logika, spracovanie chýb, výkon, bezpečnosť. Model potom môže vyhodnotiť svoj vlastný výstup a zlepšiť ho. Tým sa generovanie kódu mení z lotérie na proces. **Kontext je konečný** -Viacstupňové rozhovory fungujú tak, že so žiadosťou sa zahrnie história správ. Ale je tu limit – každý model má maximálny počet tokenov. Ako konverzácie rastú, budete potrebovať stratégie na udržanie relevantného kontextu bez prekročenia limitu. Tento modul vám ukazuje, ako funguje pamäť; neskôr sa naučíte, kedy zhrnúť, kedy zabudnúť a kedy získať späť. +Viackolové konverzácie fungujú tak, že každý požiadavok obsahuje históriu správ. Ale je tu limit – každý model má maximálny počet tokenov. Ako konverzácie rastú, budete potrebovať stratégie na udržanie relevantného kontextu bez prekročenia limitu. Tento modul vás naučí, ako pamäť funguje; neskôr sa naučíte, kedy zhrnúť, kedy zabudnúť a kedy vyhľadať. ## Ďalšie kroky -**Ďalší modul:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**Nasledujúci modul:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigácia:** [← Predchádzajúci: Modul 01 - Úvod](../01-introduction/README.md) | [Späť na hlavný](../README.md) | [Ďalší: Modul 03 - RAG →](../03-rag/README.md) +**Navigácia:** [← Predchádzajúci: Modul 01 - Úvod](../01-introduction/README.md) | [Späť na hlavnú stránku](../README.md) | [Ďalší: Modul 03 - RAG →](../03-rag/README.md) --- -**Upozornenie**: -Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Aj keď sa snažíme o presnosť, uvedomte si, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nezodpovedáme za akékoľvek nedorozumenia alebo zle interpretácie vyplývajúce z použitia tohto prekladu. +**Vyhlásenie o zodpovednosti**: +Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za žiadne nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu. \ No newline at end of file diff --git a/translations/sk/03-rag/README.md b/translations/sk/03-rag/README.md index aff51a188..7f277baae 100644 --- a/translations/sk/03-rag/README.md +++ b/translations/sk/03-rag/README.md @@ -1,144 +1,143 @@ -# Modul 03: RAG (Retrieval-Augmented Generation) +# Modul 03: RAG (Generovanie s podporou vyhľadávania) ## Obsah -- [Video Prehľad](../../../03-rag) -- [Čo sa Naučíte](../../../03-rag) -- [Predpoklady](../../../03-rag) -- [Pochopenie RAG](../../../03-rag) - - [Ktorý RAG Prístup Tento Tutoriál Používa?](../../../03-rag) -- [Ako To Funguje](../../../03-rag) - - [Spracovanie Dokumentov](../../../03-rag) - - [Vytváranie Embeddingov](../../../03-rag) - - [Sémantické Vyhľadávanie](../../../03-rag) - - [Generovanie Odpovedí](../../../03-rag) -- [Spustenie Aplikácie](../../../03-rag) -- [Používanie Aplikácie](../../../03-rag) - - [Nahranie Dokumentu](../../../03-rag) - - [Kladenie Otázok](../../../03-rag) - - [Kontrola Zdrojových Referencií](../../../03-rag) - - [Experimentovanie s Otázkami](../../../03-rag) -- [Kľúčové Koncepty](../../../03-rag) - - [Stratégia Členenia](../../../03-rag) - - [Skóre Podobnosti](../../../03-rag) - - [Ukladanie v Pamäti](../../../03-rag) - - [Správa Kontextového Okna](../../../03-rag) -- [Kedy RAG Záleží](../../../03-rag) -- [Ďalšie Kroky](../../../03-rag) +- [Video Prezentácia](#video-prezentácia) +- [Čo sa naučíte](#čo-sa-naučíte) +- [Predpoklady](#predpoklady) +- [Pochopenie RAG](#pochopenie-rag) + - [Ktorý RAG prístup tento tutoriál používa?](#ktorý-rag-prístup-tento-tutoriál-používa) +- [Ako to funguje](#ako-to-funguje) + - [Spracovanie dokumentov](#spracovanie-dokumentov) + - [Vytváranie embedov](#vytváranie-embedov) + - [Sémantické vyhľadávanie](#sémantické-vyhľadávanie) + - [Generovanie odpovedí](#generovanie-odpovedí) +- [Spustenie aplikácie](#spustenie-aplikácie) +- [Používanie aplikácie](#používanie-aplikácie) + - [Nahratie dokumentu](#nahranie-dokumentu) + - [Kladenie otázok](#kladenie-otázok) + - [Skontrolovať zdrojové odkazy](#skontrolujte-referencie-zdrojov) + - [Experimentovanie s otázkami](#experimentujte-s-otázkami) +- [Kľúčové koncepty](#kľúčové-koncepty) + - [Stratégia rozdelenia na časti](#stratégia-delenia-na-segmenty) + - [Skóre podobnosti](#hodnotenia-podobnosti) + - [Ukladanie v pamäti](#ukladanie-v-pamäti) + - [Správa kontextového okna](#správa-kontextového-okna) +- [Kedy je RAG dôležitý](#kedy-je-rag-dôležité) +- [Ďalšie kroky](#ďalšie-kroky) -## Video Prehľad +## Video Prezentácia -Pozrite si túto živú reláciu, ktorá vysvetľuje, ako začať s týmto modulom: +Pozrite si toto živé vysielanie, ktoré vysvetľuje, ako začať s týmto modulom: -RAG s LangChain4j - Živá relácia +RAG with LangChain4j - Live Session -## Čo sa Naučíte +## Čo sa naučíte -V predchádzajúcich moduloch ste sa naučili viesť konverzácie s AI a efektívne štruktúrovať svoje prompt-y. Ale existuje základné obmedzenie: jazykové modely vedia len to, čo sa naučili počas tréningu. Nevedia odpovedať na otázky o politikách vašej firmy, dokumentácii projektov alebo informáciách, ktoré neboli súčasťou ich tréningu. +V predchádzajúcich moduloch ste sa naučili viesť rozhovory s AI a efektívne štruktúrovať svoje prompt-y. Ale je tu zásadné obmedzenie: jazykové modely vedia len to, čo sa naučili počas trénovania. Nevedia odpovedať na otázky o firemných politikách, dokumentácii vašich projektov alebo o informáciách, na ktorých neboli trénované. -RAG (Retrieval-Augmented Generation) tento problém rieši. Namiesto toho, aby ste model učili vaše informácie (čo je nákladné a nepraktické), dáte mu možnosť prehľadávať vaše dokumenty. Keď niekto položí otázku, systém nájde relevantné informácie a zahrnie ich do promptu. Model potom odpovie na základe tohto získaného kontextu. +RAG (Generovanie s podporou vyhľadávania) tento problém rieši. Namiesto toho, aby ste model učili vaše informácie (čo je nákladné a nepraktické), dáte mu možnosť vyhľadávať vo vašich dokumentoch. Keď niekto položí otázku, systém nájde relevantné informácie a zahrnie ich do promptu. Model potom odpovie na základe tohto získaného kontextu. -Predstavte si RAG ako poskytnutie referenčnej knižnice modelu. Keď sa opýtate otázku, systém: +Predstavte si RAG ako referenčnú knižnicu pre model. Keď položíte otázku, systém: -1. **Používateľský Dotaz** – Položíte otázku -2. **Embedding** – Prevedie vašu otázku na vektor -3. **Vektorové Vyhľadávanie** – Nájde podobné časti dokumentu -4. **Zostavenie Kontextu** – Pridá relevantné časti do promptu -5. **Odpoveď** – LLM generuje odpoveď na základe kontextu +1. **Používateľská otázka** - Položíte otázku +2. **Embedovanie** - Premení vašu otázku na vektor +3. **Vyhľadávanie vo vektoroch** - Nájde podobné časti dokumentu +4. **Sestavenie kontextu** - Pridá relevantné časti k promptu +5. **Odpoveď** - LLM vytvorí odpoveď založenú na kontexte -Týmto spôsobom sú odpovede modelu zakotvené vo vašich skutočných dátach namiesto spoliehania sa na znalosti z tréningu alebo vymýšľania odpovedí. +Týmto sa odpovede modelu zakladajú na vašich reálnych dátach namiesto toho, aby sa spoliehali len na vedomosti zo školenia či vymýšľali odpovede. ## Predpoklady -- Dokončený [Modul 00 - Rýchly Začiatok](../00-quick-start/README.md) (pre príklad Easy RAG, na ktorý sa neskôr v tomto module odkazuje) -- Dokončený [Modul 01 - Úvod](../01-introduction/README.md) (nasadené Azure OpenAI zdroje vrátane embedding modelu `text-embedding-3-small`) -- Súbor `.env` v koreňovom adresári s Azure povereniami (vytvorený príkazom `azd up` v Module 01) +- Dokončené [Modul 01 - Úvod](../01-introduction/README.md) (nasadené Azure OpenAI zdroje vrátane embedding modelu `text-embedding-3-small`) +- `.env` súbor v koreňovom adresári so Azure povereniami (vytvorený príkazom `azd up` v Module 01) -> **Poznámka:** Ak ste nedokončili Modul 01, najprv postupujte podľa tam uvedených inštrukcií na nasadenie. Príkaz `azd up` nasadí chatovací GPT model aj embedding model používaný v tomto module. +> **Poznámka:** Ak ste Modulu 01 nedokončili, najskôr postupujte podľa jeho inštrukcií. Príkaz `azd up` nasadzuje ako GPT chat model, tak embedding model používaný v tomto module. ## Pochopenie RAG -Nižšie uvedený diagram ilustruje základný koncept: namiesto spoléhaniu sa len na tréningové dáta modelu, RAG mu poskytuje referenčnú knižnicu vašich dokumentov, do ktorej môže nazrieť pred generovaním každej odpovede. +Nasledujúci diagram ilustruje základný koncept: namiesto spoliehania sa len na tréningové dáta modelu, RAG mu poskytuje referenčnú knižnicu vašich dokumentov, ktoré môže konzultovať pred generovaním každej odpovede. Čo je RAG -*Tento diagram ukazuje rozdiel medzi štandardným LLM (ktorý tipuje na základe tréningových dát) a LLM obohateným o RAG (ktorý sa najprv obracia na vaše dokumenty).* +*Tento diagram ukazuje rozdiel medzi štandardným LLM (ktorý háda z tréningových dát) a RAG vylepšeným LLM (ktorý najskôr konzultuje vaše dokumenty).* -Tu je, ako sú kusy prepojené od začiatku do konca. Otázka používateľa prechádza štyrmi fázami — embedding, vektorové vyhľadávanie, zostavenie kontextu a generovanie odpovede — pričom každá nadväzuje na predchádzajúcu: +Tu je, ako sú jednotlivé časti prepojené koniec-koncov. Otázka používateľa prechádza štyrmi fázami — embedovaním, vyhľadávaním vo vektore, zostavením kontextu a generovaním odpovede — pričom každá fáza nadväzuje na predchádzajúcu: -Architektúra RAG +RAG Architektúra -*Tento diagram ukazuje kompletný RAG proces — používateľský dotaz prechádza embeddingom, vektorovým vyhľadávaním, zostavením kontextu a generovaním odpovede.* +*Diagram ukazuje end-to-end RAG pipeline — používateľská otázka prechádza embedovaním, vyhľadávaním, zostavením kontextu a generovaním odpovedí.* -Zvyšok tohto modulu podrobne prechádza každú etapu s kódom, ktorý môžete spustiť a upraviť. +Zvyšok tohto modulu podrobne prechádza každou fázou s ukážkovým kódom, ktorý si môžete spustiť a upravovať. -### Ktorý RAG Prístup Tento Tutoriál Používa? +### Ktorý RAG prístup tento tutoriál používa? -LangChain4j ponúka tri spôsoby implementácie RAG, každý s inou úrovňou abstrakcie. Nižšie uvedený diagram ich porovnáva vedľa seba: +LangChain4j ponúka tri spôsoby implementácie RAG, každý s inou úrovňou abstrakcie. Nasledujúci diagram ich porovnáva vedľa seba: -Tri RAG Prístupy v LangChain4j +Tri RAG prístupy v LangChain4j -*Tento diagram porovnáva tri LangChain4j RAG prístupy — Easy, Native a Advanced — ukazujúc ich kľúčové komponenty a kedy ich použiť.* +*Diagram porovnáva tri LangChain4j RAG prístupy — Easy, Native a Advanced — zobrazujúc ich kľúčové komponenty a situácie, kedy ich použiť.* | Prístup | Čo robí | Kompromis | |---|---|---| -| **Easy RAG** | Automaticky prepája všetko cez `AiServices` a `ContentRetriever`. Vy označíte rozhranie, pripojíte retriever a LangChain4j sa za vás stará o embedding, vyhľadávanie a zostavenie promptu. | Minimálny kód, ale nevidíte každý krok. | -| **Native RAG** | Voláte embedding model, vyhľadávate v úložisku, staviate prompt a generujete odpoveď sami, krok po kroku. | Viac kódu, ale každá fáza je viditeľná a upraviteľná. | -| **Advanced RAG** | Používa framework `RetrievalAugmentor` s rozšíriteľnými transformátormi dotazov, routermi, re-rankermi a injektormi obsahu pre produkčné pipeline. | Maximálna flexibilita, ale výrazne zložitejšie. | +| **Easy RAG** | Všetko automaticky prepája cez `AiServices` a `ContentRetriever`. Anotovanie rozhrania, pripojenie retrievera a LangChain4j za vás spracuje embedovanie, vyhľadávanie a zostavenie promptu. | Minimálny kód, ale nevidíte, čo sa deje v každom kroku. | +| **Native RAG** | Vyvolávate embedding model, vyhľadávate v store, budujete prompt a generujete odpoveď sami — po jednom explicitnom kroku. | Viac kódu, ale každá fáza je viditeľná a modifikovateľná. | +| **Advanced RAG** | Používa framework `RetrievalAugmentor` s pluggable transformátormi, routermi, re-rankerami a content injectormi pre produkčné pipeline. | Maximálna flexibilita, ale výrazne zložitejšie. | -**Tento tutoriál používa prístup Native.** Každý krok RAG pipeline — embedding dotazu, vyhľadávanie vo vektorovom úložisku, zostavenie kontextu a generovanie odpovede — je explicitne napísaný v [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Je to zámerné: ako zdroj učenia je dôležitejšie, aby ste videli a pochopili každý krok, než aby bol kód minimalizovaný. Keď sa s tým cítite komfortne, môžete prejsť na Easy RAG pre rýchle prototypy alebo Advanced RAG pre produkčné systémy. +**Tento tutoriál používa Native prístup.** Každý krok RAG pipeline — embedovanie otázky, vyhľadávanie vo vektorovom úložisku, zostavenie kontextu a generovanie odpovede — je explicitne napísaný v [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Toto je zámerné: ako vzdelávací materiál je dôležitejšie, aby ste videli a pochopili každý krok, než aby bol kód minimalizovaný. Keď si osvojíte, ako to všetko zapadá, môžete prejsť na Easy RAG pre rýchle prototypy alebo Advanced RAG pre produkčné systémy. -> **💡 Už ste videli Easy RAG v praxi?** Modul [Rýchly Začiatok](../00-quick-start/README.md) obsahuje príklad Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) používajúci Easy RAG — LangChain4j automaticky zabezpečuje embedding, vyhľadávanie a zostavenie promptu. Tento modul ide ďalej a rozoberá túto pipeline tak, aby ste každý krok videli a mohli ovládať sami. +> **💡 Zaujíma vás Easy RAG?** LangChain4j tiež ponúka *Easy RAG* prístup, kde `AiServices` a `ContentRetriever` automaticky riešia embedovanie, vyhľadávanie a zostavenie promptu. Tento modul ide explicitnejšou cestou — rozbíja pipeline, aby ste mohli každý krok vidieť a riadiť sami. -Nižšie uvedený diagram zobrazuje pipeline Easy RAG z príkladu Rýchleho Začiatku. Všimnite si, ako `AiServices` a `EmbeddingStoreContentRetriever` skrývajú všetku zložitosť — načítate dokument, pripojíte retriever a dostanete odpovede. Native prístup v tomto module rozoberá každý z týchto skrytých krokov: +Nasledujúci diagram ukazuje Easy RAG pipeline. Všimnite si, ako `AiServices` a `EmbeddingStoreContentRetriever` skrývajú celú komplexnosť — načítate dokument, pripojíte retriever, a dostanete odpovede. Native prístup v tomto module jednotlivé kroky odhaľuje: -Pipeline Easy RAG - LangChain4j +Easy RAG Pipeline - LangChain4j -*Tento diagram ukazuje pipeline Easy RAG z `SimpleReaderDemo.java`. Porovnajte to s Native prístupom použitým v tomto module: Easy RAG skrýva embedding, vyhľadávanie a zostavenie promptu za `AiServices` a `ContentRetriever` — načítate dokument, pripojíte retriever a dostanete odpovede. Native prístup rozoberá túto pipeline, takže voláte každý krok (embed, vyhľadanie, zostavenie kontextu, generovanie) sami, čo vám dáva plnú viditeľnosť a kontrolu.* +*Diagram ukazuje Easy RAG pipeline. Porovnajte to s Native prístupom použitým v tomto module: Easy RAG skrýva embedovanie, vyhľadávanie a zostavenie promptu za `AiServices` a `ContentRetriever` — načítate dokument, pripojíte retriever a dostanete odpovede. Native prístup jednotlivé kroky otvára, takže ich voláte sami (embedovať, vyhľadávať, zostaviť kontext, generovať), čím máte plnú viditeľnosť a kontrolu.* -## Ako To Funguje +## Ako to funguje -RAG pipeline v tomto module sa skladá zo štyroch fáz, ktoré sa spúšťajú po sebe vždy, keď používateľ položí otázku. Najskôr je nahratý dokument **parsovaný a rozdelený na časti** vhodnej veľkosti. Tieto časti sa následne prevedú na **vektorové embeddingy** a uložia sa for matematickú porovnateľnosť. Keď príde dopyt, systém vykoná **sémantické vyhľadávanie**, aby našiel najrelevantnejšie časti, a nakoniec ich odovzdá ako kontext do LLM pre **generovanie odpovede**. Nižšie si prejdeme každú fázu s reálnym kódom a diagramami. Pozrime sa najskôr na prvý krok. +RAG pipeline v tomto module sa skladá zo štyroch fáz, ktoré sa vykonávajú za sebou vždy, keď používateľ položí otázku. Najprv sa nahraný dokument **analyzuje a rozdelí** na zvládnuteľné časti. Tieto časti sa potom prevedú na **vektorové embedy** a uloží sa ich reprezentácia, aby sa dali matematicky porovnávať. Keď príde dopyt, systém vykoná **sémantické vyhľadávanie** na nájdenie najrelevantnejších častí a nakoniec ich odovzdá ako kontext LLM pre **generovanie odpovede**. Nižšie prejdeme každú fázu s reálnym kódom a diagramami. Pozrime sa na prvý krok. -### Spracovanie Dokumentov +### Spracovanie dokumentov [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Keď nahráte dokument, systém ho spracuje (PDF alebo čistý text), pripojí metadata ako názov súboru a potom ho rozdelí na časti — menšie kúsky, ktoré sa pohodlne zmestia do kontextového okna modelu. Tieto časti sa čiastočne prekrývajú, aby sa nezmizol kontext na hraniciach. +Keď nahráte dokument, systém ho analyzuje (PDF alebo čistý text), pripojí metaúdaje ako názov súboru a rozdelí ho na časti — menšie kúsky, ktoré pohodlne vojdú do kontextového okna modelu. Tieto časti sa mierne prekrývajú, aby sa nezstratil kontext na hraniciach. ```java // Analyzujte nahraný súbor a zabaľte ho do dokumentu LangChain4j Document document = Document.from(content, metadata); -// Rozdeľte na 300-tokenové časti s 30-tokenovým prekrytím +// Rozdeľte na kúsky po 300 tokenoch s 30-tokenovým prekrytím DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` + +Nasledujúci diagram vizualizuje tento proces. Všimnite si, že každá časť si s susedmi zdieľa niekoľko tokenov — 30-tokenové prekrytie zabezpečuje, že žiadny dôležitý kontext nepadne medzi praskliny: -Nižšie uvedený diagram vizuálne ukazuje, ako to funguje. Všimnite si, že každá časť zdieľa niektoré tokeny so susedmi — prekrytie 30 tokenov zabezpečuje, že sa nestratí žiadny dôležitý kontext medzi časťami: - -Členenie Dokumentu +Rozdelenie dokumentu na časti -*Tento diagram ukazuje rozdelenie dokumentu na 300-tokenové časti s prekrytím 30 tokenov, čím sa zachováva kontext na hraniciach častí.* +*Diagram ukazuje, ako je dokument rozdelený do 300-tokenových častí s 30-tokenovým prekrytím, čím sa zachováva kontext na hraniciach častí.* -> **🤖 Vyskúšajte chat s [GitHub Copilot](https://github.com/features/copilot):** Otvorte [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) a opýtajte sa: -> - "Ako LangChain4j rozdeľuje dokumenty na časti a prečo je prekrytie dôležité?" -> - "Aká je optimálna veľkosť častí pre rôzne typy dokumentov a prečo?" -> - "Ako spracovať dokumenty v rôznych jazykoch alebo so špeciálnym formátovaním?" +> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) a spýtajte sa: +> - "Ako LangChain4j rozdeľuje dokumenty na časti a prečo je prekrytie dôležité?" +> - "Aká je optimálna veľkosť častí pre rôzne typy dokumentov a prečo?" +> - "Ako spracovať dokumenty v viacerých jazykoch alebo so špeciálnym formátovaním?" -### Vytváranie Embeddingov +### Vytváranie embedov [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Každá časť sa prevedie na číselné vyjadrenie nazývané embedding — v podstate prevodník významu na čísla. Embedding model nie je „inteligentný“ ako chat model; nedokáže nasledovať inštrukcie, argumentovať ani odpovedať na otázky. Vie však premietnuť text do matematického priestoru, kde podobné významy ležia blízko seba — „auto“ blízko „automobil“, „refundácia“ blízko „vrátenie peňazí“. Predstavte si chat model ako osobu, s ktorou môžete hovoriť; embedding model je ultra dobrý systém na usporiadanie súborov. +Každá časť sa prevedie na číselnú reprezentáciu nazývanú embedding — v podstate prevodník významu na čísla. Embedding model nie je "inteligentný" ako chat model; nedokáže dodržiavať inštrukcie, dedukovať ani odpovedať na otázky. Čo dokáže, je premapovať text do matematického priestoru, kde sa podobné významy nachádzajú blízko seba — napríklad "auto" blízko "automobil," "politika vrátenia" blízko "vráť mi peniaze." Predstavte si chat model ako osobu, s ktorou môžete hovoriť; embedding model ako špičkový systém na triedenie. -Nižšie uvedený diagram vizualizuje tento koncept — text vstupuje, vychádzajú číselné vektory a podobné významy produkujú vektory blízko seba: +Nasledujúci diagram znázorňuje tento koncept — text ide dovnútra, vychádzajú numerické vektory, a podobné významy produkujú vektory vedľa seba: Koncept embedding modelu -*Tento diagram ukazuje, ako embedding model prevádza text na číselné vektory, pričom podobné významy — ako "auto" a "automobil" — sú blízko seba vo vektorovom priestore.* +*Diagram ukazuje, ako embedding model prevádza text na číselné vektory, pričom podobné významy — ako "auto" a "automobil" — sú umiestnené blízko seba vo vektorovom priestore.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Nižšie uvedený diagram tried ukazuje dva samostatné toky v RAG pipeleine a LangChain4j triedy, ktoré ich implementujú. **Tok ingestie** (beží raz pri nahrávaní) rozdeľuje dokument, vytvára embeddingy častí a ukladá ich cez `.addAll()`. **Tok dotazu** (beží vždy, keď používateľ položí otázku) vytvára embedding otázky, vyhľadáva v úložisku cez `.search()` a odovzdáva nájdený kontext do chat modelu. Obidva toky sa spájajú v zdieľanom rozhraní `EmbeddingStore`: +Nižšie uvedený diagram tried ukazuje dva samostatné toky v RAG pipeline a LangChain4j triedy ich realizujúce. **Ingestný tok** (spustí sa raz pri nahrávaní) rozdeľuje dokument, embeduje časti a ukladá cez `.addAll()`. **Dopytový tok** (beží pri každom dopyte používateľa) embeduje otázku, vyhľadáva v store cez `.search()` a odovzdáva nájdený kontext chat modelu. Oba toky sa prepájajú cez zdieľané rozhranie `EmbeddingStore`: -LangChain4j RAG Triedy +Triedy LangChain4j pre RAG -*Tento diagram ukazuje dva toky v RAG pipeline — ingestiu a dotaz — a ich prepojenie cez zdieľané EmbeddingStore.* +*Diagram zobrazuje dva toky v RAG pipeline — ingestný a dopytový — a ich prepojenie cez zdieľané EmbeddingStore.* -Keď sú embeddingy uložené, podobný obsah sa prirodzene zhlukuje vo vektorovom priestore. Nižšie uvedená vizualizácia ukazuje, ako dokumenty o súvisiacich témach končia blízko seba, čo umožňuje sémantické vyhľadávanie: +Keď sú embedy uložené, podobný obsah sa prirodzene zoskupuje vektorovo priestorovo. Vizualizácia nižšie ukazuje, ako dokumenty o súvisiacich témach vytvárajú blízke body, čo umožňuje sémantické vyhľadávanie: Priestor vektorových embeddingov -*Táto vizualizácia ukazuje, ako sa súvisiace dokumenty zhlukujú v 3D vektorovom priestore, pričom témy ako Technická dokumentácia, Firemné pravidlá a Často kladené otázky tvorí samostatné skupiny.* +*Vizualizácia ukazuje, ako sa dokumenty s podobnou tématikou zoskupujú v 3D vektorovom priestore do samostatných zhlukov, ako sú Technická dokumentácia, Obchodné pravidlá a FAQ.* -Keď používateľ vyhľadáva, systém vykonáva štyri kroky: embeduje dokumenty raz, embeduje dotaz pri každom vyhľadávaní, porovnáva dotazový vektor so všetkými uloženými vektormi pomocou kosínusovej podobnosti a vracia top-K najlepšie hodnotené časti. Nižšie uvedený diagram prechádza každým krokom a zúčastnenými LangChain4j triedami: +Keď používateľ vyhľadáva, systém nasleduje štyri kroky: embedovanie dokumentov raz, embedovanie otázky pri každom vyhľadávaní, porovnanie otázkového vektora so všetkými uloženými vektormi pomocou kosínovej podobnosti a vrátenie top-K najlepších častí. Diagram nižšie prechádza každý krok a zúčastnené LangChain4j triedy: -Kroky vyhľadávania embeddingov +Kroky embedding vyhľadávania -*Tento diagram ukazuje štvorkrokový proces vyhľadávania embeddingov: embedovanie dokumentov, embedovanie dotazu, porovnávanie vektorov s kosínusovou podobnosťou a vrátenie top-K výsledkov.* +*Diagram ukazuje štvorkrokový proces embedding vyhľadávania: embedovať dokumenty, embedovať otázku, porovnať vektory pomocou kosínovej podobnosti a vrátiť top-K výsledkov.* -### Sémantické Vyhľadávanie +### Sémantické vyhľadávanie [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Keď položíte otázku, vaša otázka sa tiež prevedie na embedding. Systém porovná embedding vašej otázky so všetkými embeddingmi častí dokumentu. Nájde časti s najpodobnejšími významami — nie len kľúčové slová, ale reálnu sémantickú podobnosť. +Keď položíte otázku, táto otázka sa tiež prevedie na embedding. Systém porovná embedding vašej otázky so všetkými embeddingami častí dokumentu. Nájde časti s najpodobnejším významom — nielen zhodu kľúčových slov, ale skutočnú sémantickú podobnosť. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Nižšie uvedený diagram kontrastuje sémantické vyhľadávanie s tradičným vyhľadávaním podľa kľúčových slov. Vyhľadávanie podľa kľúčového slova „vozidlo“ prehliadne časť o „autách a nákladiakoch“, ale sémantické vyhľadávanie chápe, že znamenajú to isté a vráti ju ako najlepšie hodnotenú zhodu: +Nasledujúci diagram porovnáva sémantické vyhľadávanie s tradičným vyhľadávaním podľa kľúčových slov. Vyhľadávanie podľa kľúčového slova „vozidlo“ prehliadne časť o „autách a nákladiakoch,“ ale sémantické vyhľadávanie chápe, že ide o to isté a vráti ju ako vysoko hodnotený výsledok: Sémantické vyhľadávanie -*Tento diagram porovnáva vyhľadávanie založené na kľúčových slovách so sémantickým vyhľadávaním, ukazujúc, ako sémantické vyhľadávanie získava obsah konceptuálne príbuzný, aj keď sa kľúčové slová líšia.* -Pod kapotou sa podobnosť meria pomocou kosínovej podobnosti — v podstate sa pýta "ukazujú tieto dve šípky rovnakým smerom?" Dve časti môžu používať úplne odlišné slová, ale ak znamenajú to isté, ich vektory smerujú rovnako a skóre je blízke 1.0: +*Diagram porovnáva vyhľadávanie podľa kľúčových slov so sémantickým vyhľadávaním, ktoré vracia obsah konceptuálne príbuzný, aj keď sa kľúčové slová líšia.* -Kosínová podobnosť +V základe sa podobnosť meria pomocou kosínovej podobnosti — v podstate otázkou „ukazujú tieto dva šípy rovnakým smerom?“ Dve časti môžu použiť úplne odlišné slová, ale ak majú rovnaký význam, vektory smerujú podobne a skóre je blízke 1.0: -*Táto schéma znázorňuje kosínovú podobnosť ako uhol medzi vektormi embeddingov — čím sú vektory zosúladené, tým bližšie je skóre k 1.0, čo naznačuje vyššiu sémantickú podobnosť.* +Kosínová podobnosť +*Táto schéma znázorňuje kosínusovú podobnosť ako uhol medzi vektormi embedingov — viac zladené vektory majú skóre bližšie k 1,0, čo naznačuje vyššiu sémantickú podobnosť.* > **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) a opýtajte sa: -> - "Ako funguje vyhľadávanie podobnosti pomocou embeddingov a čo určuje skóre?" -> - "Aký prah podobnosti mám použiť a ako to ovplyvňuje výsledky?" -> - "Ako riešiť prípady, keď sa nenájdu žiadne relevantné dokumenty?" +> - "Ako funguje vyhľadávanie podobnosti s embeddingami a čo určuje skóre?" +> - "Akú prahovú hodnotu podobnosti by som mal použiť a ako ovplyvňuje výsledky?" +> - "Ako riešim prípady, keď nie sú nájdené relevantné dokumenty?" ### Generovanie odpovedí [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Najrelevantnejšie časti sa zostavujú do štruktúrovaného promptu, ktorý obsahuje explicitné inštrukcie, získaný kontext a otázku používateľa. Model číta tieto konkrétne časti a odpovedá na základe týchto informácií — môže použiť iba to, čo má pred sebou, čím sa zabraňuje halucináciám. +Najrelevantnejšie segmenty sú zostavené do štruktúrovaného promptu, ktorý obsahuje explicitné inštrukcie, získaný kontext a otázku používateľa. Model číta tieto konkrétne segmenty a odpovedá na základe týchto informácií — môže použiť iba to, čo má pred sebou, čo zabraňuje halucináciám. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Nižšie uvedená schéma ukazuje tento proces zostavovania v akcii — časti s najvyšším skóre z vyhľadávacieho kroku sa vložia do promptu a `OpenAiOfficialChatModel` vytvorí podloženú odpoveď: +Nižšie znázorňuje táto schéma tento proces zostavenia — najvyššie skórujúce segmenty zo skúšobného kroku sú vložené do šablóny promptu a `OpenAiOfficialChatModel` generuje podloženú odpoveď: -Zostavenie kontextu +Context Assembly -*Táto schéma ukazuje, ako sa najlepšie časti zostavujú do štruktúrovaného promptu, čo umožňuje modelu generovať podloženú odpoveď z vašich dát.* +*Táto schéma ukazuje, ako sú najlepšie skórujúce segmenty zostavené do štruktúrovaného promptu, čo modelu umožňuje generovať podloženú odpoveď z vašich dát.* ## Spustenie aplikácie **Overenie nasadenia:** -Uistite sa, že súbor `.env` existuje v koreňovom adresári s Azure povereniami (vytvorené počas modulu 01). Spustite to z adresára modulu (`03-rag/`): +Uistite sa, že v koreňovom adresári existuje súbor `.env` s Azure povereniami (vytvorený počas Modulu 01). Spustite toto z adresára modulu (`03-rag/`): **Bash:** ```bash @@ -261,27 +260,27 @@ Get-Content ..\.env # Malo by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Spustenie aplikácie:** -> **Poznámka:** Ak ste už spustili všetky aplikácie pomocou `./start-all.sh` z koreňového adresára (ako je popísané v Module 01), tento modul už beží na porte 8081. Môžete preskočiť spúšťacie príkazy nižšie a ísť priamo na http://localhost:8081. +> **Poznámka:** Ak ste už všetky aplikácie spustili pomocou `./start-all.sh` z koreňového adresára (ako je popísané v Module 01), tento modul už beží na porte 8081. Môžete preskočiť príkazy na spustenie nižšie a prejsť priamo na http://localhost:8081. **Možnosť 1: Použitie Spring Boot Dashboard (Odporúčané pre používateľov VS Code)** -Vývojársky kontajner obsahuje rozšírenie Spring Boot Dashboard, ktoré poskytuje vizuálne rozhranie na správu všetkých Spring Boot aplikácií. Nájdete ho v paneli aktivít na ľavej strane VS Code (hľadajte ikonu Spring Boot). +Vývojové kontajner obsahuje rozšírenie Spring Boot Dashboard, ktoré poskytuje vizuálne rozhranie na správu všetkých Spring Boot aplikácií. Nájdete ho v Activity Bar na ľavej strane VS Code (ikona Spring Boot). -Zo Spring Boot Dashboard môžete: +Z Spring Boot Dashboard môžete: - Vidieť všetky dostupné Spring Boot aplikácie v pracovnom priestore -- Spustiť/zastaviť aplikácie jedným kliknutím -- Zobraziť denníky aplikácie v reálnom čase -- Monitorovať stav aplikácie +- Jedným kliknutím spúšťať alebo zastavovať aplikácie +- Pozerať logy aplikácií v reálnom čase +- Monitorovať stav aplikácií -Jednoducho kliknite na tlačidlo play vedľa "rag" pre spustenie tohto modulu, alebo spustite všetky moduly naraz. +Jednoducho kliknite na tlačidlo prehrávania vedľa „rag“ na spustenie tohto modulu, alebo spustite všetky moduly naraz. Spring Boot Dashboard -*Tento snímok obrazovky zobrazuje Spring Boot Dashboard vo VS Code, kde môžete vizuálne spúšťať, zastavovať a monitorovať aplikácie.* +*Táto snímka obrazovky zobrazuje Spring Boot Dashboard v VS Code, kde môžete vizuálne spúšťať, zastavovať a monitorovať aplikácie.* **Možnosť 2: Použitie shell skriptov** -Spustite všetky webové aplikácie (moduly 01-04): +Spustiť všetky webové aplikácie (moduly 01-04): **Bash:** ```bash @@ -295,7 +294,7 @@ cd .. # Z koreňového adresára .\start-all.ps1 ``` -Alebo spustite iba tento modul: +Alebo spustiť len tento modul: **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Obidva skripty automaticky načítajú premenné prostredia zo súboru `.env` v koreňovom adresári a zostavia JAR, ak ešte neexistuje. +Obidva skripty automaticky načítajú premenné prostredia zo súboru `.env` v koreňovom adresári a postavia JAR súbory, ak ešte neexistujú. -> **Poznámka:** Ak chcete pred spustením manuálne zostaviť všetky moduly: +> **Poznámka:** Ak preferujete najprv manuálne zostaviť všetky moduly pred spustením: > > **Bash:** > ```bash @@ -325,13 +324,13 @@ Obidva skripty automaticky načítajú premenné prostredia zo súboru `.env` v > mvn clean package -DskipTests > ``` -Otvorte http://localhost:8081 vo vašom prehliadači. +Otvorte v prehliadači http://localhost:8081. -**Pre zastavenie:** +**Na zastavenie:** **Bash:** ```bash -./stop.sh # Len tento modul +./stop.sh # Iba tento modul # Alebo cd .. && ./stop-all.sh # Všetky moduly ``` @@ -347,91 +346,91 @@ cd ..; .\stop-all.ps1 # Všetky moduly Aplikácia poskytuje webové rozhranie na nahrávanie dokumentov a kladenie otázok. -Rozhranie aplikácie RAG +RAG Application Interface -*Tento snímok obrazovky zobrazuje rozhranie aplikácie RAG, kde môžete nahrávať dokumenty a klásť otázky.* +*Táto snímka obrazovky zobrazuje rozhranie RAG aplikácie, kde nahrávate dokumenty a kladiete otázky.* ### Nahranie dokumentu -Začnite nahraním dokumentu — na testovanie najlepšie fungujú TXT súbory. V tomto adresári je poskytovaný súbor `sample-document.txt`, ktorý obsahuje informácie o funkciách LangChain4j, implementácii RAG a najlepších postupoch — ideálne pre testovanie systému. +Začnite nahraním dokumentu — na testovanie najlepšie fungujú TXT súbory. V tomto adresári je k dispozícii `sample-document.txt`, ktorý obsahuje informácie o funkciách LangChain4j, implementácii RAG a osvedčených postupoch — ideálny na testovanie systému. -Systém spracuje váš dokument, rozdelí ho na časti a vytvorí embeddingy pre každú časť. To sa deje automaticky po nahraní. +Systém spracuje váš dokument, rozdelí ho na časti a vytvorí embeddingy pre každú časť. Toto prebieha automaticky pri nahraní. ### Kladenie otázok -Teraz položte konkrétne otázky o obsahu dokumentu. Skúste niečo faktické, čo je jasne uvedené v dokumente. Systém vyhľadá relevantné časti, zahrnie ich do promptu a vygeneruje odpoveď. +Teraz sa môžete pýtať konkrétne otázky o obsahu dokumentu. Skúste niečo faktické, čo je jasne uvedené v dokumente. Systém vyhľadá relevantné segmenty, zahrnie ich do promptu a vygeneruje odpoveď. -### Kontrola zdrojových odkazov +### Skontrolujte referencie zdrojov -Všimnite si, že každá odpoveď obsahuje zdrojové odkazy s hodnotami podobnosti. Tieto skóre (od 0 do 1) ukazujú, ako relevantná bola každá časť voči vašej otázke. Vyššie skóre znamená lepšie zhody. To vám umožní overiť odpoveď voči zdrojovému materiálu. +Všimnite si, že každá odpoveď obsahuje referencie na zdroje spolu s hodnoteniami podobnosti. Tieto skóre (0 až 1) ukazujú, ako relevantný každý segment bol pre vašu otázku. Vyššie skóre znamená lepšiu zhody. Toto vám umožňuje overiť odpoveď s pôvodným materiálom. -Výsledky dotazu RAG +RAG Query Results -*Tento snímok obrazovky zobrazuje výsledky dotazu s vygenerovanou odpoveďou, zdrojovými odkazmi a skóre relevantnosti pre každú získanú časť.* +*Táto snímka obrazovky zobrazuje výsledky dotazu s vygenerovanou odpoveďou, referenciami na zdroje a skóre relevantnosti pre každý získaný segment.* ### Experimentujte s otázkami -Vyskúšajte rôzne typy otázok: +Vyskúšajte rôzne druhy otázok: - Konkrétne fakty: "Aká je hlavná téma?" -- Porovnania: "Aký je rozdiel medzi X a Y?" +- Porovnania: "V čom sa líši X od Y?" - Zhrnutia: "Zhrňte kľúčové body o Z" -Sledujte, ako sa skóre relevantnosti mení na základe toho, ako dobre vaša otázka zodpovedá obsahu dokumentu. +Sledujte, ako sa skóre relevantnosti mení podľa toho, ako dobre vaša otázka zodpovedá obsahu dokumentu. ## Kľúčové koncepty -### Stratégia delenia na časti (Chunking) +### Stratégia delenia na segmenty -Dokumenty sa rozdeľujú na časti po 300 tokenoch s prekrytím 30 tokenov. Tento kompromis zabezpečuje, že každá časť má dostatok kontextu na zmysluplnosť, pritom je dostatočne malá, aby sa mohlo zahrnúť viac častí do promptu. +Dokumenty sa rozdeľujú na segmenty po 300 tokenoch s prekrytím 30 tokenov. Tento kompromis zabezpečuje, že každý segment má dostatok kontextu na zmysluplné chápanie, zároveň je dosť malý na to, aby sa v promptu zmestilo viac segmentov. -### Skóre podobnosti +### Hodnotenia podobnosti -Každá získaná časť prichádza so skóre podobnosti od 0 do 1, ktoré ukazuje, ako veľmi zodpovedá otázke používateľa. Nižšie uvedená schéma vizualizuje rozsahy skóre a ako ich systém používa na filtrovanie výsledkov: +Každý získaný segment má skóre podobnosti medzi 0 a 1, ktoré indikuje, ako veľmi sa zhoduje s otázkou používateľa. Nižšie uvedená schéma vizualizuje rozsahy skóre a spôsob, akým systém filtruje výsledky: -Skóre podobnosti +Similarity Scores -*Táto schéma zobrazuje rozsahy skóre od 0 do 1, s minimálnym prahom 0,5, ktorý filtruje irelevantné časti.* +*Táto schéma zobrazuje rozsahy skóre od 0 do 1, s minimálnym prahom 0,5, ktorý filtruje irelevantné segmenty.* -Skóre sa pohybujú od 0 do 1: +Skóre sa pohybuje od 0 do 1: - 0,7-1,0: Vysoko relevantné, presná zhoda - 0,5-0,7: Relevantné, dobrý kontext -- Pod 0,5: Filtrované, príliš odlišné +- Pod 0,5: Vylúčené, príliš nezhodné -Systém získava iba časti nad minimálnym prahom, aby zaistil kvalitu. +Systém vyhľadáva iba segmenty nad minimálnym prahom, aby zabezpečil kvalitu. -Embeddingy dobre fungujú, keď sa význam zreteľne zoskupuje, ale majú slabiny. Nižšie uvedená schéma ukazuje bežné chyby — príliš veľké časti produkujú nejasné vektory, príliš malé časti postrádajú kontext, dvojsmyselné termíny vedú do viacerých klastrov a presné vyhľadávanie (ID, čísla dielov) s embeddingmi vôbec nefunguje: +Embeddingy dobre fungujú, keď sa významy jasne zhlukujú, ale majú aj slabé miesta. Nižšie uvedená schéma zobrazuje bežné chyby — príliš veľké segmenty produkujú nejasné vektory, príliš malé segmenty nemajú kontext, nejednoznačné pojmy ukazujú na viacero zhlukov a presné vyhľadávanie zhodných hodnôt (ID, dielenské čísla) embeddingy vôbec nepodporujú: -Režimy zlyhania embeddingov +Embedding Failure Modes -*Táto schéma znázorňuje bežné režimy zlyhania embeddingov: príliš veľké časti, príliš malé časti, dvojsmyselné výrazy vedúce k viacerým klastrom a presné vyhľadávanie ako ID.* +*Táto schéma ukazuje bežné chyby embeddingov: príliš veľké segmenty, príliš malé segmenty, nejednoznačné pojmy, ktoré ukazujú na viacero zhlukov, a presné vyhľadávanie ako ID.* -### Ukladanie v pamäti (In-Memory Storage) +### Ukladanie v pamäti -Tento modul používa pre jednoduchosť ukladanie v pamäti. Po reštarte aplikácie sa nahrané dokumenty stratia. Produkčné systémy používajú perzistentné úložiská vektorov ako Qdrant alebo Azure AI Search. +Tento modul používa pre jednoduchosť ukladanie v pamäti. Po reštarte aplikácie sa nahraté dokumenty stratia. Produkčné systémy používajú perzistentné vektorové databázy ako Qdrant alebo Azure AI Search. ### Správa kontextového okna -Každý model má maximálnu veľkosť kontextového okna. Nie je možné zahrnúť všetky časti veľkého dokumentu. Systém načíta najrelevantnejších N častí (predvolene 5), aby sa zmestil do limitov a poskytol dostatok kontextu na presné odpovede. +Každý model má maximálnu veľkosť kontextového okna. Nemôžete zahrnúť každý segment z veľkého dokumentu. Systém získava top N najrelevantnejších segmentov (štandardne 5), aby zostal v limitách a zároveň poskytol dostatok kontextu na presné odpovede. -## Kedy je RAG dôležitý +## Kedy je RAG dôležité -RAG nie je vždy správny prístup. Nižšie uvedený rozhodovací diagram vám pomôže určiť, kedy RAG prináša hodnotu a kedy sú jednoduchšie prístupy — ako zahrnutie obsahu priamo do promptu alebo spoliehanie sa na zabudované vedomosti modelu — postačujúce: +RAG nie je vždy správny prístup. Nižšie uvedený rozhodovací návod vám pomôže určiť, kedy RAG prináša hodnotu a kedy sú jednoduchšie prístupy — ako zahrnutie obsahu priamo do promptu alebo spoliehanie sa na vstavané znalosti modelu — postačujúce: -Kedy použiť RAG +When to Use RAG -*Táto schéma ukazuje rozhodovací diagram, kedy RAG pridáva hodnotu a kedy sú postačujúce jednoduchšie prístupy.* +*Táto schéma zobrazuje rozhodovací návod, kedy RAG prináša hodnotu oproti jednoduchším prístupom.* ## Ďalšie kroky -**Ďalší modul:** [04-tools - AI agenti s nástrojmi](../04-tools/README.md) +**Ďalší modul:** [04-tools - AI Agenti s nástrojmi](../04-tools/README.md) --- -**Navigácia:** [← Predchádzajúci: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Späť na hlavné](../README.md) | [Ďalší: Modul 04 - Nástroje →](../04-tools/README.md) +**Navigácia:** [← Predchádzajúci: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Späť na hlavnú stránku](../README.md) | [Ďalší: Modul 04 - Tools →](../04-tools/README.md) --- -**Vyhlásenie**: -Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Aj keď sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho rodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za akékoľvek nedorozumenia alebo nesprávne výklady vyplývajúce z použitia tohto prekladu. +**Vyhlásenie o zodpovednosti**: +Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za žiadne nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu. \ No newline at end of file diff --git a/translations/sk/04-tools/README.md b/translations/sk/04-tools/README.md index 02ff4a73e..2dab8f0b4 100644 --- a/translations/sk/04-tools/README.md +++ b/translations/sk/04-tools/README.md @@ -1,84 +1,84 @@ -# Modul 04: AI agenti s nástrojmi +# Modul 04: AI Agenti s Nástrojmi ## Obsah -- [Prehľad videa](../../../04-tools) -- [Čo sa naučíte](../../../04-tools) -- [Predpoklady](../../../04-tools) -- [Pochopenie AI agentov s nástrojmi](../../../04-tools) -- [Ako funguje volanie nástrojov](../../../04-tools) - - [Definície nástrojov](../../../04-tools) - - [Rozhodovanie](../../../04-tools) - - [Vykonanie](../../../04-tools) - - [Generovanie odpovede](../../../04-tools) - - [Architektúra: Spring Boot automatické prepojenie](../../../04-tools) -- [Reťazenie nástrojov](../../../04-tools) -- [Spustenie aplikácie](../../../04-tools) -- [Používanie aplikácie](../../../04-tools) - - [Vyskúšajte jednoduché použitie nástroja](../../../04-tools) - - [Testovanie reťazenia nástrojov](../../../04-tools) - - [Zobraziť tok konverzácie](../../../04-tools) - - [Experimentovanie s rôznymi požiadavkami](../../../04-tools) -- [Kľúčové koncepty](../../../04-tools) - - [ReAct vzor (reasoning and acting)](../../../04-tools) - - [Opis nástrojov je dôležitý](../../../04-tools) - - [Správa relácií](../../../04-tools) - - [Spracovanie chýb](../../../04-tools) -- [Dostupné nástroje](../../../04-tools) -- [Kedy používať agentov založených na nástrojoch](../../../04-tools) -- [Nástroje verzus RAG](../../../04-tools) -- [Ďalšie kroky](../../../04-tools) - -## Prehľad videa - -Pozrite si živú reláciu, ktorá vysvetľuje, ako začať s týmto modulom: - -AI agenti s nástrojmi a MCP - živá relácia - -## Čo sa naučíte - -Doteraz ste sa naučili viesť rozhovory s AI, efektívne štruktúrovať promptovanie a zakladať odpovede na vašich dokumentoch. Ale stále existuje základné obmedzenie: jazykové modely dokážu generovať len text. Nevedia skontrolovať počasie, robiť výpočty, dotazovať databázy ani interagovať s externými systémami. - -Nástroje to menia. Tým, že modelu dáte prístup k funkciám, ktoré môže volať, premeníte ho z generátora textu na agenta, ktorý môže konať. Model rozhoduje, kedy potrebuje nástroj, ktorý nástroj použiť a aké parametre odovzdať. Váš kód vykoná funkciu a vráti výsledok. Model potom tento výsledok zakomponuje do svojej odpovede. +- [Video Prehľad](#video-prehľad) +- [Čo sa Naučíte](#čo-sa-naučíte) +- [Predpoklady](#predpoklady) +- [Pochopenie AI Agentov s Nástrojmi](#pochopenie-ai-agentov-s-nástrojmi) +- [Ako Funguje Volanie Nástrojov](#ako-funguje-volanie-nástrojov) + - [Definície Nástrojov](#definície-nástrojov) + - [Rozhodovanie](#rozhodovanie) + - [Vykonanie](#vykonanie) + - [Generovanie Odpovede](#generovanie-odpovede) + - [Architektúra: Spring Boot Auto-Wiring](#architektúra-spring-boot-auto-wiring) +- [Reťazenie Nástrojov](#reťazenie-nástrojov) +- [Spustenie Aplikácie](#spustenie-aplikácie) +- [Používanie Aplikácie](#použitie-aplikácie) + - [Vyskúšať Jednoduché Použitie Nástroja](#vyskúšajte-jednoduché-použitie-nástroja) + - [Otestovať Reťazenie Nástrojov](#vyskúšajte-reťazenie-nástrojov) + - [Zobraziť Tok Konverzácie](#sledujte-priebeh-rozhovoru) + - [Experimentovať s Rôznymi Požiadavkami](#experimentujte-s-rôznymi-požiadavkami) +- [Kľúčové Koncepty](#kľúčové-koncepty) + - [ReAct Vzor (Uvažovanie a Konanie)](#react-vzor-rozumovanie-a-konanie) + - [Význam Popisov Nástrojov](#popisy-nástrojov-majú-význam) + - [Správa Session](#správa-relácií) + - [Riešenie Chýb](#spracovanie-chýb) +- [Dostupné Nástroje](#dostupné-nástroje) +- [Kedy Používať Agentov založených na Nástrojoch](#kedy-používať-agentov-s-nástrojmi) +- [Nástroje vs RAG](#nástroje-vs-rag) +- [Ďalšie Kroky](#ďalšie-kroky) + +## Video Prehľad + +Pozrite si túto živú reláciu, ktorá vysvetľuje, ako začať s týmto modulom: + +AI Agents with Tools and MCP - Live Session + +## Čo sa Naučíte + +Doteraz ste sa naučili viesť rozhovory s AI, efektívne štruktúrovať výzvy a zakladať odpovede na vašich dokumentoch. Ale stále je tu základné obmedzenie: jazykové modely môžu generovať len text. Nemôžu skontrolovať počasie, vykonávať výpočty, dotazovať sa databáz ani komunikovať s externými systémami. + +Nástroje to menia. Tým, že modelu dávate prístup k funkciám, ktoré môže vyvolať, premieňate ho zo generátora textu na agenta, ktorý môže konať. Model rozhoduje, kedy potrebuje nástroj, ktorý nástroj použiť a aké parametre poslať. Váš kód vykoná funkciu a vráti výsledok. Model tento výsledok vloží do svojej odpovede. ## Predpoklady - Dokončený [Modul 01 - Úvod](../01-introduction/README.md) (nasadené Azure OpenAI zdroje) -- Odporúča sa dokončiť predchádzajúce moduly (tento modul odkazuje na [koncepty RAG z Modulu 03](../03-rag/README.md) v porovnaní Nástroje verzus RAG) +- Odporúča sa dokončiť predchádzajúce moduly (tento modul odkazuje na [RAG koncepty z Modulu 03](../03-rag/README.md) v porovnaní Nástrojov vs RAG) - Súbor `.env` v koreňovom adresári s Azure povereniami (vytvorený pomocou `azd up` v Module 01) -> **Poznámka:** Ak Modul 01 nie je dokončený, najskôr postupujte podľa jeho inštrukcií na nasadenie. +> **Poznámka:** Ak ste ešte nedokončili Modul 01, najskôr postupujte podľa jeho inštrukcií na nasadenie. -## Pochopenie AI agentov s nástrojmi +## Pochopenie AI Agentov s Nástrojmi -> **📝 Poznámka:** Termín "agenti" v tomto module označuje AI asistentov rozšírených o schopnosť volať nástroje. Toto sa líši od **Agentic AI** vzorov (autonómni agenti s plánovaním, pamäťou a viacstupňovým uvažovaním), ktoré pokryjeme v [Module 05: MCP](../05-mcp/README.md). +> **📝 Poznámka:** Termín „agenti“ v tomto module sa vzťahuje na AI asistentov rozšírených o schopnosť volania nástrojov. Toto je odlišné od **Agentic AI** vzorov (autonómni agenti s plánovaním, pamäťou a viacstupňovým uvažovaním), ktoré budeme preberať v [Module 05: MCP](../05-mcp/README.md). -Bez nástrojov môže jazykový model len generovať text zo svojich trénovacích dát. Ak sa ho opýtate na aktuálne počasie, musí hádať. Ak mu dáte nástroje, môže volať weather API, robiť výpočty, dotazovať databázu — a potom skutočné výsledky „vložiť“ do svojej odpovede. +Bez nástrojov môže jazykový model generovať len text z daných tréningových dát. Opýtajte sa ho na aktuálne počasie a musí hádať. Dajte mu nástroje a môže zavolať API počasia, vykonať výpočty alebo dotaz do databázy — a potom tieto skutočné výsledky zahrnúť do svojej odpovede. -Bez nástrojov verzus s nástrojmi +Without Tools vs With Tools -*Bez nástrojov model háda — s nástrojmi môže volať API, robiť výpočty a vracať dáta v reálnom čase.* +*Bez nástrojov model iba háda — s nástrojmi môže volať API, vykonávať výpočty a vracať dáta v reálnom čase.* -AI agent s nástrojmi nasleduje vzor **Reasoning and Acting (ReAct)**. Model nielen odpovedá — rozmýšľa, čo potrebuje, koná volaním nástroja, pozoruje výsledok a potom sa rozhoduje, či má konať znova alebo doručiť konečnú odpoveď: +AI agent s nástrojmi nasleduje **Reasoning and Acting (ReAct)** vzor. Model nielen odpovedá — rozmýšľa o tom, čo potrebuje, koná vyvolaním nástroja, sleduje výsledok a potom rozhodne, či konať znovu, alebo doručiť konečnú odpoveď: -1. **Reason (rozumovať)** — Agent analyzuje otázku používateľa a určí, aké informácie potrebuje -2. **Act (konať)** — Agent vyberie správny nástroj, generuje správne parametre a zavolá ho -3. **Observe (pozorovať)** — Agent dostane výstup nástroja a vyhodnotí výsledok -4. **Repeat or Respond (opakovať alebo odpovedať)** — Ak je potrebných viac dát, agent sa vracia späť; inak zloží odpoveď v prirodzenom jazyku +1. **Uvažovanie** — agent analyzuje otázku používateľa a určí, aké informácie potrebuje +2. **Konanie** — agent vyberie správny nástroj, vygeneruje správne parametre a zavolá ho +3. **Pozorovanie** — agent prijíma výstup z nástroja a hodnotí výsledok +4. **Opakovanie alebo Odpoveď** — ak je potrebných viac dát, agent sa vracia; inak zloží odpoveď v prirodzenom jazyku -ReAct vzor +ReAct Pattern -*Cyklus ReAct — agent rozumuje, čo má urobiť, koná volaním nástroja, pozoruje výsledok a opakuje, kým môže doručiť konečnú odpoveď.* +*Cyklus ReAct — agent rozmýšľa, čo má robiť, koná vyvolaním nástroja, pozoruje výsledok a opakuje, kým nedoručí odpoveď.* -Toto sa deje automaticky. Definujete nástroje a ich opisy. Model sa stará o rozhodovanie kedy a ako ich používať. +Toto prebieha automaticky. Definujete nástroje a ich popisy. Model sa stará o rozhodovanie, kedy a ako ich použiť. -## Ako funguje volanie nástrojov +## Ako Funguje Volanie Nástrojov -### Definície nástrojov +### Definície Nástrojov [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Definujete funkcie s jasnými popismi a špecifikáciami parametrov. Model vidí tieto popisy v systémovom prompte a rozumie, čo každý nástroj robí. +Definujete funkcie s jasnými popismi a špecifikáciami parametrov. Model vidí tieto popisy vo svojom systémovom prompt-e a rozumie, čo každý nástroj robí. ```java @Component @@ -98,100 +98,100 @@ public interface Assistant { // Asistent je automaticky prepojený pomocou Spring Boot s: // - Bean ChatModel -// - Všetky metódy @Tool z tried @Component +// - Všetky metódy @Tool z tried s @Component // - ChatMemoryProvider pre správu relácií ``` -Nižšie uvedený diagram rozoberá každú anotáciu a vysvetľuje, ako každý prvok pomáha AI pochopiť, kedy má nástroj volať a aké argumenty odovzdať: +Nižšie uvedený diagram rozoberá každú anotáciu a ukazuje, ako každý prvok pomáha AI pochopiť, kedy nástroj volať a aké argumenty odovzdať: -Anatómia definícií nástrojov +Anatomy of Tool Definitions -*Anatómia definície nástroja — @Tool hovorí AI, kedy ho použiť, @P popisuje každý parameter a @AiService všetko pri spustení prepojí.* +*Anatómia definície nástroja — @Tool hovorí AI, kedy ho používať, @P popisuje každý parameter a @AiService spája všetko dohromady pri štarte.* -> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) a opýtajte sa: -> - „Ako začleniť skutočné weather API ako OpenWeatherMap namiesto mock dát?“ -> - „Čo robí dobrý opis nástroja, ktorý pomáha AI správne ho používať?“ -> - „Ako spracovať chyby API a limitácie rýchlosti v implementáciách nástrojov?“ +> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) a spýtajte sa: +> - "Ako by som integroval reálne API počasia ako OpenWeatherMap namiesto simulovaných dát?" +> - "Čo robí dobrý popis nástroja, ktorý pomáha AI správne ho používať?" +> - "Ako riešiť chyby API a limity volaní v implementáciách nástrojov?" ### Rozhodovanie -Keď používateľ položí otázku „Aké je počasie v Seattli?“, model nevyberá nástroj náhodne. Porovnáva zámery používateľa so všetkými dostupnými opismi nástrojov, hodnotí ich relevantnosť a vyberie najlepšie zodpovedajúci nástroj. Potom vygeneruje štruktúrované volanie funkcie so správnymi parametrami — v tomto prípade nastaví `location` na `"Seattle"`. +Keď sa používateľ opýta "Aké je počasie v Seattli?", model nevyberá náhodne nástroj. Porovnáva zámer používateľa s každým popisom dostupných nástrojov, hodnotí ich relevantnosť a vyberie najvhodnejší. Potom vygeneruje štruktúrovaný funkčný hovor s správnymi parametrami — v tomto prípade nastaví `location` na `"Seattle"`. -Ak žiadny nástroj nevyhovuje požiadavke používateľa, model odpovie z vlastného poznania. Ak vyhovuje viac nástrojov, vyberie ten najšpecifickejší. +Ak žiadny nástroj nezodpovedá požiadavke používateľa, model odpovedá zo svojich vlastných znalostí. Ak zodpovedá viacero nástrojov, vyberie ten najšpecifickejší. -Ako AI rozhoduje, ktorý nástroj použiť +How the AI Decides Which Tool to Use -*Model vyhodnocuje každý dostupný nástroj voči zámeru používateľa a vyberá najlepší zápas — preto je dôležité písať jasné a konkrétne opisy nástrojov.* +*Model hodnotí každý dostupný nástroj voči zámeru používateľa a vyberá najlepší zhodu — preto je dôležité písať jasné a konkrétne popisy nástrojov.* ### Vykonanie [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot automaticky prepája deklaratívne `@AiService` rozhranie so všetkými zaregistrovanými nástrojmi a LangChain4j volania nástrojov vykonáva automaticky. V pozadí prechádza kompletné volanie nástroja cez šesť fáz — od otázky používateľa v prirodzenom jazyku až po odpoveď v prirodzenom jazyku: +Spring Boot automaticky prepája deklaratívne `@AiService` rozhranie so všetkými registrovanými nástrojmi a LangChain4j volania nástrojov vykonáva automaticky. V pozadí prebieha kompletný tok volania nástroja cez šesť fáz — od používateľovej otázky v prirodzenom jazyku až po odpoveď taktiež v prirodzenom jazyku: -Priebeh volania nástroja +Tool Calling Flow -*End-to-end tok — používateľ položí otázku, model vyberie nástroj, LangChain4j ho vykoná a model výsledok zahŕňa do prirodzenej odpovede.* +*Kompletný tok — používateľ položí otázku, model vyberie nástroj, LangChain4j ho vykoná a model vloží výsledok do odpovede.* -Ak ste spustili [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) v Module 00, už ste videli tento vzor v akcii — `Calculator` nástroje sa volali rovnako. Nasledujúci sekvenčný diagram ukazuje presne, čo sa stalo v pozadí počas tejto ukážky: +V pozadí `AiServices` spúšťa rovnaký cyklus volania nástroja pre ktorýkoľvek nástroj — tu demonštrované jednoduchým `Calculator`. Nasledujúci sekvenčný diagram presne ukazuje, čo sa deje pod kapotou: -Sekvenčný diagram volania nástroja +Tool Calling Sequence Diagram -*Cyklus volania nástroja z Quick Start demo — `AiServices` odosiela vašu správu a schémy nástrojov do LLM, LLM odpovie volaním funkcie ako `add(42, 58)`, LangChain4j vykoná metódu `Calculator` lokálne a vráti výsledok pre konečnú odpoveď.* +*Cyklus volania nástroja — `AiServices` posiela vašu správu a schémy nástrojov LLM, LLM odpovedá funkčným volaním ako `add(42, 58)`, LangChain4j lokálne vykoná metódu `Calculator` a výsledok vráti pre konečnú odpoveď.* -> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) a opýtajte sa: -> - „Ako funguje ReAct vzor a prečo je efektívny pre AI agentov?“ -> - „Ako agent rozhoduje, ktorý nástroj použiť a v akom poradí?“ -> - „Čo sa stane, ak zlyhá vykonanie nástroja — ako robustne spracovať chyby?“ +> **🤖 Vyskúšajte s [GitHub Copilot](https://github.com/features/copilot) Chat:** Otvorte [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) a spýtajte sa: +> - "Ako funguje ReAct vzor a prečo je efektívny pre AI agentov?" +> - "Ako agent rozhoduje, ktorý nástroj použiť a v akom poradí?" +> - "Čo sa stane, keď volanie nástroja zlyhá - ako mám robustne riešiť chyby?" -### Generovanie odpovede +### Generovanie Odpovede -Model dostane údaje o počasí a naformátuje ich do odpovede v prirodzenom jazyku pre používateľa. +Model prijme dáta o počasí a formátuje ich do prirodzenej jazykovej odpovede používateľovi. -### Architektúra: Spring Boot automatické prepojenie +### Architektúra: Spring Boot Auto-Wiring -Tento modul používa LangChain4j integráciu so Spring Boot cez deklaratívne `@AiService` rozhrania. Pri spustení Spring Boot automaticky nájde každý `@Component` obsahujúci `@Tool` metódy, vašu `ChatModel` bean a `ChatMemoryProvider` — a všetko to prepojí do jedného `Assistant` rozhrania bez boilerplatu. +Tento modul používa Spring Boot integráciu LangChain4j s deklaratívnymi `@AiService` rozhraniami. Pri štarte Spring Boot objaví každý `@Component` obsahujúci metódy označené `@Tool`, váš `ChatModel` bean a `ChatMemoryProvider` — a všetko to zviaže do jedného rozhrania `Assistant` bez potreby boilerplatu. -Architektúra Spring Boot automatického prepojenia +Spring Boot Auto-Wiring Architecture -*Rozhranie @AiService prepája ChatModel, komponenty nástrojov a poskytovateľa pamäte — Spring Boot všetko automaticky spraví.* +*Rozhranie @AiService spája ChatModel, komponenty nástrojov a poskytovateľa pamäte — Spring Boot zaistí automatické zapojenie všetkého.* -Tu je celý životný cyklus požiadavky vo forme sekvenčného diagramu — od HTTP požiadavky cez kontrolér, službu a automaticky prepojený proxy až po vykonanie nástroja a späť: +Tu je celý životný cyklus požiadavky zobrazený sekvenčným diagramom — od HTTP požiadavky cez kontrolér, službu a automaticky zapojený proxy, až po vykonanie nástroja a návrat: -Sekvenčný diagram volania nástrojov Spring Boot +Spring Boot Tool Calling Sequence -*Kompletný životný cyklus požiadavky Spring Boot — HTTP požiadavka prechádza kontrolérom a službou k proxy asistenta, ktorý automaticky orchestruje LLM a volania nástrojov.* +*Kompletný životný cyklus požiadavky Spring Boot — HTTP požiadavka prechádza kontrolérom a službou k proxy Assistanta, ktorý automaticky orchestruje LLM a volania nástrojov.* Hlavné výhody tohto prístupu: -- **Spring Boot automatické prepojenie** — ChatModel a nástroje automaticky injektované -- **@MemoryId vzor** — automatická správa pamäte na základe relácie -- **Jedna inštancia** — asistent vytvorený raz a znovu použitý pre lepší výkon -- **Typovo bezpečné vykonanie** — Java metódy volané priamo s konverziou typov -- **Vícekroková orchestrácia** — automaticky spracováva reťazenie nástrojov -- **Žiadny boilerplate** — žiadne manuálne volania `AiServices.builder()` alebo HashMap pamäte +- **Spring Boot auto-wiring** — ChatModel a nástroje sa automaticky vkladajú +- **@MemoryId vzor** — Automatická správa pamäte na základe session +- **Jedna inštancia** — Assistant vytvorený raz a opakovane používaný pre lepší výkon +- **Bezpečné vykonávanie podľa typu** — Java metódy sú volané priamo s konverziou typov +- **Orchestrácia viacerých krokov** — Automaticky rieši reťazenie nástrojov +- **Žiadny boilerplate** — Nie je potrebné manuálne volanie `AiServices.builder()` alebo použitie pamäťového HashMap -Alternatívne prístupy (manuálne `AiServices.builder()`) vyžadujú viac kódu a nevyužívajú výhody Spring Boot integrácie. +Alternatívne prístupy (ručné `AiServices.builder()`) vyžadujú viac kódu a nevyužívajú výhody integrácie Spring Boot. -## Reťazenie nástrojov +## Reťazenie Nástrojov -**Reťazenie nástrojov** — Skutočná sila agentov založených na nástrojoch sa ukáže, keď jedna otázka vyžaduje viac nástrojov. Spýtajte sa „Aké je počasie v Seattli vo Fahrenheitoch?“ a agent automaticky spojí dva nástroje: najprv zavolá `getCurrentWeather` a získa teplotu v Celziách, potom tento výsledok predá `celsiusToFahrenheit` na prepočet — to všetko v jednom kole rozhovoru. +**Reťazenie Nástrojov** — Skutočná sila agentov založených na nástrojoch sa prejaví, keď jedna otázka vyžaduje použitie viacerých nástrojov. Spýtajte sa "Aké je počasie v Seattli vo Fahrenheitoch?" a agent automaticky spojí dva nástroje: najskôr zavolá `getCurrentWeather` pre teplotu v Celziách, potom túto hodnotu prenechá nástroju `celsiusToFahrenheit` na konverziu — všetko v jednom kole konverzácie. -Príklad reťazenia nástrojov +Tool Chaining Example -*Reťazenie nástrojov v akcii — agent najprv zavolá getCurrentWeather, potom výsledok v Celziach pošle do celsiusToFahrenheit a doručí zloženú odpoveď.* +*Reťazenie nástrojov v praxi — agent najskôr zavolá getCurrentWeather, potom výsledok v Celziách pošle do celsiusToFahrenheit a doručí kombinovanú odpoveď.* -**Elegantné chybové spracovanie** — Spýtajte sa na počasie v meste, ktoré nie je v mock dátach. Nástroj vráti chybovú správu a AI vysvetlí, že nemôže pomôcť, namiesto toho, aby aplikácia spadla. Nástroje zlyhávajú bezpečne. Nižšie uvedený diagram porovnáva oba prístupy — s riadnym spracovaním chýb agent zachytí výnimku a odpovie užitočne, bez neho aplikácia úplne spadne: +**Elegantné zlyhania** — Opýtajte sa na počasie v meste, ktoré nie je v simulovaných dátach. Nástroj vráti chybovú správu a AI vysvetlí, že nemôže pomôcť, namiesto toho, aby došlo k pádu aplikácie. Nástroje zlyhávajú bezpečne. Nasledujúci diagram kontrastuje oba prístupy — s riadnym spracovaním chyby agent zachytí výnimku a odpovie nápomocne, bez neho by celá aplikácia spadla: -Priebeh spracovania chýb +Error Handling Flow -*Keď nástroj zlyhá, agent zachytí chybu a odpovie užitočným vysvetlením namiesto pádu.* +*Keď nástroj zlyhá, agent zachytí chybu a odpovie s užitočným vysvetlením namiesto pádu.* -Toto sa deje v jednom kole rozhovoru. Agent autonómne orchestruje viacero volaní nástrojov. +To všetko sa deje v jednom kole konverzácie. Agent sám orchestruje viaceré volania nástrojov. -## Spustenie aplikácie +## Spustenie Aplikácie -**Overenie nasadenia:** +**Overte nasadenie:** Uistite sa, že súbor `.env` existuje v koreňovom adresári s Azure povereniami (vytvorený počas Modulu 01). Spustite to z adresára modulu (`04-tools/`): @@ -202,29 +202,29 @@ cat ../.env # Malo by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **PowerShell:** ```powershell -Get-Content ..\.env # Mala by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Malo by zobraziť AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Spustenie aplikácie:** +**Spustite aplikáciu:** -> **Poznámka:** Ak ste už spustili všetky aplikácie pomocou `./start-all.sh` z koreňového adresára (ako je popísané v Module 01), tento modul už beží na porte 8084. Môžete vynechať spúšťacie príkazy nižšie a ísť priamo na http://localhost:8084. +> **Poznámka:** Ak ste už spustili všetky aplikácie pomocou `./start-all.sh` z koreňového adresára (ako popísané v Module 01), tento modul už beží na porte 8084. Môžete preskočiť príkazy na spustenie a ísť priamo na http://localhost:8084. **Možnosť 1: Použitie Spring Boot Dashboard (odporúčané pre používateľov VS Code)** -Vývojový kontajner obsahuje rozšírenie Spring Boot Dashboard, ktoré poskytuje vizuálne rozhranie na správu všetkých Spring Boot aplikácií. Nájdete ho v bočnom paneli (Activity Bar) na ľavej strane vo VS Code (ikona Spring Boot). +Vývojársky kontajner obsahuje rozšírenie Spring Boot Dashboard, ktoré poskytuje vizuálne rozhranie na správu všetkých Spring Boot aplikácií. Nájdete ho v Activity Bar na ľavej strane VS Code (ikona Spring Boot). -V Spring Boot Dashboard môžete: +Zo Spring Boot Dashboard môžete: - Vidieť všetky dostupné Spring Boot aplikácie v pracovnom priestore -- Spustiť/zastaviť aplikácie jedným kliknutím -- Zobraziť logy aplikácie v reálnom čase -- Monitorovať stav aplikácie -Jednoducho kliknite na tlačidlo pre spustenie vedľa „tools“, aby ste spustili tento modul, alebo spustite všetky moduly naraz. +- Jedným kliknutím spustiť/zastaviť aplikácie +- Prezerať logy aplikácie v reálnom čase +- Monitorovať stav aplikácií -Takto vyzerá Spring Boot Dashboard vo VS Code: +Stačí kliknúť na tlačidlo play vedľa "tools" pre spustenie tohto modulu alebo spustiť všetky moduly naraz. +Takto vyzerá Spring Boot Dashboard vo VS Code: Spring Boot Dashboard -*Spring Boot Dashboard vo VS Code — spúšťanie, zastavenie a monitorovanie všetkých modulov z jedného miesta* +*Spring Boot Dashboard vo VS Code — spustite, zastavte a sledujte všetky moduly z jedného miesta* **Možnosť 2: Použitie shell skriptov** @@ -242,7 +242,7 @@ cd .. # Z koreňového adresára .\start-all.ps1 ``` -Alebo spustite iba tento modul: +Alebo spustite len tento modul: **Bash:** ```bash @@ -256,29 +256,29 @@ cd 04-tools .\start.ps1 ``` -Oba skripty automaticky načítajú premenné prostredia zo súboru `.env` v koreňovom adresári a zostavia JAR súbory, ak ešte neexistujú. +Oba skripty automaticky načítajú premenné prostredia zo súboru `.env` v koreňovom priečinku a zkompilujú JAR súbory, ak ešte neexistujú. -> **Poznámka:** Ak si prajete zostaviť všetky moduly ručne pred spustením: +> **Poznámka:** Ak uprednostňujete manuálnu kompiláciu všetkých modulov pred spustením: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Otvorte http://localhost:8084 vo vašom prehliadači. +Otvorte v prehliadači http://localhost:8084. **Na zastavenie:** **Bash:** ```bash -./stop.sh # Iba tento modul +./stop.sh # Len tento modul # Alebo cd .. && ./stop-all.sh # Všetky moduly ``` @@ -290,86 +290,86 @@ cd .. && ./stop-all.sh # Všetky moduly cd ..; .\stop-all.ps1 # Všetky moduly ``` -## Používanie aplikácie +## Použitie aplikácie -Aplikácia poskytuje webové rozhranie, kde môžete komunikovať s AI agentom, ktorý má prístup k nástrojom na počasie a konverziu teploty. Takto vyzerá rozhranie - obsahuje rýchle ukážky a chatovací panel na zasielanie požiadaviek: +Aplikácia poskytuje webové rozhranie, kde môžete komunikovať s AI agentom, ktorý má prístup k nástrojom na počasie a prevod teplôt. Takto vyzerá rozhranie — obsahuje rýchle príklady a chatovací panel na odosielanie požiadaviek: AI Agent Tools Interface -*Rozhranie AI Agent Tools - rýchle príklady a chatovacie rozhranie pre interakciu s nástrojmi* +*Rozhranie nástrojov AI agenta - rýchle príklady a chatovací panel na interakciu s nástrojmi* ### Vyskúšajte jednoduché použitie nástroja -Začnite jednoduchou požiadavkou: „Preveď 100 stupňov Fahrenheita na Celziovu teplotu“. Agent rozpozná, že potrebuje nástroj na konverziu teploty, zavolá ho s správnymi parametrami a vráti výsledok. Všimnite si, aké prirodzené to pôsobí – nešpecifikovali ste, ktorý nástroj použiť alebo ako ho zavolať. +Začnite jednoduchou požiadavkou: „Preveď 100 stupňov Fahrenheita na Celziove.“ Agent rozpozná, že potrebuje nástroj na prevod teplôt, vyvolá ho s príslušnými parametrami a vráti výsledok. Všimnite si, aké to pôsobí prirodzene – nezadávali ste, ktorý nástroj použiť ani ako ho volať. -### Otestujte reťazenie nástrojov +### Vyskúšajte reťazenie nástrojov -Teraz skúste niečo zložitejšie: „Aké je počasie v Seattli a preveď ho na Fahrenheit?“ Sledujte, ako agent postupuje v krokoch. Najprv získa počasie (ktoré vracia hodnotu v Celziovej teplote), rozpozná, že potrebuje prepočítať na Fahrenheit, zavolá nástroj na konverziu a nakoniec skombinuje oba výsledky do jednej odpovede. +Teraz skúste niečo zložitejšie: „Aké je počasie v Seattli a preveď to na Fahrenheit?“ Sledujte, ako agent pracuje v krokoch. Najprv získa počasie (ktoré vracia v Celziovi), rozpozná, že musí previesť na Fahrenheit, zavolá nástroj na prevod a oba výsledky skombinuje do jednej odpovede. -### Pozrite sa na tok konverzácie +### Sledujte priebeh rozhovoru -Chatové rozhranie uchováva históriu konverzácie, čo umožňuje viackolové interakcie. Vidíte všetky predchádzajúce otázky a odpovede, čo uľahčuje sledovanie konverzácie a pochopenie, ako agent počas viacerých výmen buduje kontext. +Chatovací panel uchováva históriu rozhovoru, čo umožňuje viackolové interakcie. Vidíte všetky predchádzajúce dopyty a odpovede, čo uľahčuje sledovať konverzáciu a chápať, ako agent buduje kontext počas viacerých výmen. Conversation with Multiple Tool Calls -*Viackolová konverzácia ukazujúca jednoduché konverzie, vyhľadávanie počasia a reťazenie nástrojov* +*Viackolový rozhovor ukazujúci jednoduché prevody, vyhľadávanie počasia a reťazenie nástrojov* ### Experimentujte s rôznymi požiadavkami Vyskúšajte rôzne kombinácie: - Vyhľadávanie počasia: „Aké je počasie v Tokiu?“ -- Konverzia teplôt: „Koľko je 25°C v Kelvinoch?“ -- Kombinované otázky: „Skontroluj počasie v Paríži a povedz mi, či je nad 20°C“ +- Prevod teplôt: „Koľko je 25 °C v Kelvinoch?“ +- Zložité dotazy: „Skontroluj počasie v Paríži a povedz, či je nad 20 °C“ -Všimnite si, ako agent interpretuje prirodzený jazyk a mapuje ho na správne volania nástrojov. +Všímajte si, ako agent interpretuje prirodzený jazyk a mapuje ho na správne volania nástrojov. ## Kľúčové koncepty ### ReAct vzor (Rozumovanie a konanie) -Agent strieda rozumovanie (rozhodovanie, čo robiť) a konanie (používanie nástrojov). Tento vzor umožňuje autonómne riešenie problémov namiesto iba reagovania na pokyny. +Agent strieda rozumovanie (rozhodovanie, čo robiť) a konanie (použitie nástrojov). Tento vzor umožňuje autonómne riešenie problémov namiesto jednoduchého reagovania na inštrukcie. -### Popisy nástrojov sú dôležité +### Popisy nástrojov majú význam -Kvalita vašich popisov nástrojov priamo ovplyvňuje, ako ich agent používa. Jasné a špecifické popisy pomáhajú modelu pochopiť, kedy a ako každý nástroj volať. +Kvalita popisov vašich nástrojov priamo ovplyvňuje, ako dobre ich agent využíva. Jasné, špecifické popisy pomáhajú modelu pochopiť, kedy a ako nástroj volať. ### Správa relácií -Anotácia `@MemoryId` umožňuje automatickú správu pamäte viazanú na relácie. Každé ID relácie získa vlastnú inštanciu `ChatMemory`, ktorú spravuje bean `ChatMemoryProvider`, takže viacerí používatelia môžu s agentom komunikovať súbežne bez prelínania konverzácií. Nasledujúci diagram ukazuje, ako sú viacerí používatelia smerovaní do izolovaných pamätí na základe ich ID relácie: +Anotácia `@MemoryId` umožňuje automatickú správu pamäte založenú na relácii. Každé ID relácie má svoju vlastnú inštanciu `ChatMemory` spravovanú beanom `ChatMemoryProvider`, takže viacerí používatelia môžu komunikovať s agentom súčasne bez zamieňania konverzácií. Nasledujúci diagram ukazuje, ako sú viacerí používatelia smerovaní do izolovaných úložísk pamäte na základe ID relácií: Session Management with @MemoryId -*Každé ID relácie sa mapuje do izolovanej histórie konverzácií — používatelia nikdy nevidia správy ostatných.* +*Každé ID relácie má samostatnú históriu rozhovoru — používatelia nikdy nevidia správy iných.* ### Spracovanie chýb -Nástroje môžu zlyhať — API môžu mať časový limit, parametre môžu byť neplatné, externé služby môžu padnúť. Produkční agenti potrebujú spracovanie chýb, aby model mohol vysvetliť problémy alebo skúsiť alternatívy namiesto zlyhania celej aplikácie. Keď nástroj vyhodí výnimku, LangChain4j ju zachytí a pošle chybovú správu spätne do modelu, ktorý potom môže vysvetliť problém prirodzeným jazykom. +Nástroje môžu zlyhať — API môžu vypršať, parametre môžu byť neplatné, externé služby môžu byť nedostupné. Produkčné agenti potrebujú spracovanie chýb, aby model mohol vysvetliť problémy alebo skúsiť alternatívy namiesto toho, aby celá aplikácia zlyhala. Keď nástroj vyhodí výnimku, LangChain4j ju zachytí a pošle späť modelu ako chybu, ktorú model môže vysvetliť prirodzeným jazykom. ## Dostupné nástroje -Nasledujúci diagram ukazuje širokú ekosystém nástrojov, ktoré môžete vytvoriť. Tento modul demonštruje nástroje na počasie a teplotu, ale rovnaký vzor `@Tool` funguje pre akúkoľvek Java metódu — od dotazov na databázy po spracovanie platieb. +Diagram nižšie ukazuje širokú ekosystém nástrojov, ktoré môžete vytvárať. Tento modul demonštruje nástroje pre počasie a teplotu, ale rovnaký vzor `@Tool` funguje pre akúkoľvek Java metódu — od dotazov do databázy po spracovanie platieb. Tool Ecosystem -*Každá Java metóda anotovaná `@Tool` je dostupná pre AI — tento vzor sa rozširuje na databázy, API, e-maily, operácie so súbormi a viac.* +*Každá Java metóda anotovaná `@Tool` sa sprístupní AI — vzor sa rozširuje na databázy, API, emaily, súborové operácie a ďalšie.* -## Kedy používať agentov založených na nástrojoch +## Kedy používať agentov s nástrojmi -Nie každá požiadavka vyžaduje nástroje. Rozhodnutie spočíva v tom, či AI musí komunikovať s externými systémami, alebo či môže odpovedať zo svojich znalostí. Nasledujúci sprievodca zhrňuje, kedy nástroje prinášajú hodnotu a kedy nie sú potrebné: +Nie každý dopyt potrebuje nástroje. Rozhodnutie závisí od toho, či AI potrebuje komunikovať s externými systémami alebo môže odpovedať z vlastných znalostí. Nasledujúci návod zhrňuje, kedy nástroje pridávajú hodnotu a kedy nie sú potrebné: When to Use Tools -*Rýchly rozhodovací sprievodca — nástroje sú vhodné pre aktuálne údaje, výpočty a akcie; všeobecné znalosti a tvorivé úlohy ich nepotrebujú.* +*Rýchly rozhodovací sprievodca — nástroje slúžia na aktuálne dáta, výpočty a akcie; všeobecné znalosti a tvorivé úlohy ich nevyžadujú.* ## Nástroje vs RAG -Moduly 03 a 04 oba rozširujú možnosti AI, ale zásadne odlišným spôsobom. RAG poskytuje modelu prístup ku **znalostiam** vyhľadávaním dokumentov. Nástroje dávajú modelu schopnosť vykonávať **akcie** volaním funkcií. Nasledujúci diagram porovnáva tieto dva prístupy vedľa seba — od spôsobu ich fungovania až po kompromisy medzi nimi: +Moduly 03 a 04 rozširujú schopnosti AI, ale zásadne rôznymi spôsobmi. RAG poskytuje modelu prístup k **poznatkom** vyhľadávaním dokumentov. Nástroje dávajú modelu schopnosť vykonávať **akcie** volaním funkcií. Nasledujúci diagram porovnáva tieto dva prístupy bok po boku — od spôsobu fungovania po kompromisy medzi nimi: Tools vs RAG Comparison -*RAG získava informácie zo statických dokumentov — nástroje vykonávajú akcie a získavajú dynamické, aktuálne údaje. Mnoho produkčných systémov kombinuje oba prístupy.* +*RAG získava informácie zo statických dokumentov — Nástroje vykonávajú akcie a sťahujú dynamické, aktuálne údaje. Mnoho produkčných systémov kombinuje oba prístupy.* -V praxi mnohé produkčné systémy kombinujú oba prístupy: RAG na zakotvenie odpovedí vo vašej dokumentácii a nástroje na získavanie živých údajov alebo vykonávanie operácií. +V praxi mnohé produkčné systémy kombinujú obidva prístupy: RAG pre zakotvenie odpovedí vo vašej dokumentácii a Nástroje pre získavanie živých údajov alebo vykonávanie operácií. ## Ďalšie kroky @@ -382,6 +382,6 @@ V praxi mnohé produkčné systémy kombinujú oba prístupy: RAG na zakotvenie --- -**Vyhlásenie o vylúčení zodpovednosti**: -Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, berte prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Originálny dokument v jeho pôvodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre dôležité informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za akékoľvek nepochopenia alebo nesprávne výklady vyplývajúce z použitia tohto prekladu. +**Vyhlásenie o zodpovednosti**: +Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za žiadne nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu. \ No newline at end of file diff --git a/translations/sk/README.md b/translations/sk/README.md index 3485e4352..b218d7ccc 100644 --- a/translations/sk/README.md +++ b/translations/sk/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j pre Začiatočníkov +# LangChain4j pre začiatočníkov Kurz na tvorbu AI aplikácií s LangChain4j a Azure OpenAI GPT-5.2, od základného chatu po AI agentov. ### 🌐 Podpora viacerých jazykov -#### Podporované cez GitHub Action (Automatizované a vždy aktuálne) +#### Podporované cez GitHub Action (automatizované a vždy aktuálne) -[Arabčina](../ar/README.md) | [Bengálčina](../bn/README.md) | [Bulharčina](../bg/README.md) | [Barmčina (Myanmar)](../my/README.md) | [Čínština (zjednodušená)](../zh-CN/README.md) | [Čínština (tradičná, Hongkong)](../zh-HK/README.md) | [Čínština (tradičná, Macau)](../zh-MO/README.md) | [Čínština (tradičná, Taiwan)](../zh-TW/README.md) | [Chorvátčina](../hr/README.md) | [Čeština](../cs/README.md) | [Dánčina](../da/README.md) | [Holandčina](../nl/README.md) | [Estónčina](../et/README.md) | [Fínčina](../fi/README.md) | [Francúzština](../fr/README.md) | [Nemčina](../de/README.md) | [Gréčtina](../el/README.md) | [Hebrejčina](../he/README.md) | [Hindčina](../hi/README.md) | [Maďarčina](../hu/README.md) | [Indonézština](../id/README.md) | [Taliančina](../it/README.md) | [Japončina](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Kórejčina](../ko/README.md) | [Litovčina](../lt/README.md) | [Malajčina](../ms/README.md) | [Malajálamčina](../ml/README.md) | [Maráthčina](../mr/README.md) | [Nepálčina](../ne/README.md) | [Nigerijský pidžin](../pcm/README.md) | [Nórčina](../no/README.md) | [Perzčina (Farsi)](../fa/README.md) | [Poľština](../pl/README.md) | [Portugalčina (Brazília)](../pt-BR/README.md) | [Portugalčina (Portugalsko)](../pt-PT/README.md) | [Pandžábčina (Gurmukhi)](../pa/README.md) | [Rumunčina](../ro/README.md) | [Ruština](../ru/README.md) | [Srbčina (cyrilika)](../sr/README.md) | [Slovenčina](./README.md) | [Slovinčina](../sl/README.md) | [Španielčina](../es/README.md) | [Svahilčina](../sw/README.md) | [Švédčina](../sv/README.md) | [Tagalog (Filipíny)](../tl/README.md) | [Tamilčina](../ta/README.md) | [Telugčina](../te/README.md) | [Tajčina](../th/README.md) | [Turečtina](../tr/README.md) | [Ukrajinčina](../uk/README.md) | [Urdčina](../ur/README.md) | [Vietnamčina](../vi/README.md) +[Arabčina](../ar/README.md) | [Bengálčina](../bn/README.md) | [Bulharčina](../bg/README.md) | [Barmčina (Myanmar)](../my/README.md) | [Čínština (zjednodušená)](../zh-CN/README.md) | [Čínština (tradičná, Hong Kong)](../zh-HK/README.md) | [Čínština (tradičná, Macau)](../zh-MO/README.md) | [Čínština (tradičná, Taiwan)](../zh-TW/README.md) | [Chorvátčina](../hr/README.md) | [Čeština](../cs/README.md) | [Dánčina](../da/README.md) | [Holandčina](../nl/README.md) | [Estónčina](../et/README.md) | [Fínčina](../fi/README.md) | [Francúzština](../fr/README.md) | [Nemčina](../de/README.md) | [Gréčtina](../el/README.md) | [Hebrejčina](../he/README.md) | [Hindčina](../hi/README.md) | [Maďarčina](../hu/README.md) | [Indonézština](../id/README.md) | [Taliančina](../it/README.md) | [Japončina](../ja/README.md) | [Kannadčina](../kn/README.md) | [Khmerčina](../km/README.md) | [Kórejčina](../ko/README.md) | [Litovčina](../lt/README.md) | [Malajčina](../ms/README.md) | [Malayálam](../ml/README.md) | [Maráthčina](../mr/README.md) | [Nepálčina](../ne/README.md) | [Nigérijská pidžinčina](../pcm/README.md) | [Nórčina](../no/README.md) | [Perzština (Farsi)](../fa/README.md) | [Poľština](../pl/README.md) | [Portugalčina (Brazília)](../pt-BR/README.md) | [Portugalčina (Portugalsko)](../pt-PT/README.md) | [Pandžábčina (Gurmukhí)](../pa/README.md) | [Rumunčina](../ro/README.md) | [Ruština](../ru/README.md) | [Srbčina (cyrilika)](../sr/README.md) | [Slovenčina](./README.md) | [Slovinčina](../sl/README.md) | [Španielčina](../es/README.md) | [Svahilčina](../sw/README.md) | [Švédčina](../sv/README.md) | [Tagalog (Filipínčina)](../tl/README.md) | [Tamilčina](../ta/README.md) | [Telugu](../te/README.md) | [Thajčina](../th/README.md) | [Turečtina](../tr/README.md) | [Ukrajinčina](../uk/README.md) | [Urdčina](../ur/README.md) | [Vietnamčina](../vi/README.md) -> **Uprednostňujete klonovanie lokálne?** +> **Preferujete klonovanie lokálne?** > -> Tento repozitár obsahuje viac ako 50 jazykových prekladov, ktoré výrazne zvyšujú veľkosť stiahnutia. Ak chcete klonovať bez prekladov, použite sparse checkout: +> Toto úložisko obsahuje viac než 50 jazykových prekladov, čo výrazne zväčšuje veľkosť sťahovania. Na klonovanie bez prekladov použite sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,122 +29,119 @@ Kurz na tvorbu AI aplikácií s LangChain4j a Azure OpenAI GPT-5.2, od základn > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Tým získate všetko potrebné na dokončenie kurzu s omnoho rýchlejším stiahnutím. +> Toto vám poskytne všetko potrebné na dokončenie kurzu s oveľa rýchlejším sťahovaním. ## Obsah -1. [Rýchly štart](00-quick-start/README.md) - Začnite s LangChain4j -2. [Úvod](01-introduction/README.md) - Naučte sa základy LangChain4j -3. [Návrh promptov](02-prompt-engineering/README.md) - Ovládnite efektívny dizajn promptov -4. [RAG (Generovanie s podporou vyhľadávania)](03-rag/README.md) - Vytvorte inteligentné systémy založené na znalostiach -5. [Nástroje](04-tools/README.md) - Integrujte externé nástroje a jednoduchých asistentov -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Pracujte s protokolom Model Context Protocol (MCP) a agentnými modulmi +1. [Úvod](01-introduction/README.md) - Naučte sa základy LangChain4j +2. [Tvorba promptov](02-prompt-engineering/README.md) - Ovládnite efektívny návrh promptov +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Vytvorte inteligentné systémy založené na znalostiach +4. [Nástroje](04-tools/README.md) - Integrujte externé nástroje a jednoduchých asistentov +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Pracujte s Model Context Protocol (MCP) a agentnými modulmi -### Video prechádzky +### Video návody -Každý modul má sprevádzajúcu živú reláciu, kde krok za krokom prejdeme koncepty a kód. +Každý modul má sprievodnú živú reláciu, kde prejdeme koncepty a kód krok za krokom. | Modul | Video | |--------|-------| -| 01 - Úvod | [Začíname s LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Návrh promptov | [Návrh promptov s LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - Úvod | [Začnite s LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Tvorba promptov | [Tvorba promptov s LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG s LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Nástroje & 05 - MCP | [AI agenti s nástrojmi a MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Vzdelávacia cesta +## Učebná cesta -**Nový v LangChain4j?** Pozrite si [Glosár](docs/GLOSSARY.md) pre definície kľúčových pojmov a konceptov. +**Nový v LangChain4j?** Pozrite si [Slovník](docs/GLOSSARY.md) pre definície kľúčových pojmov a konceptov. > **Rýchly štart** -1. Vytvorte fork tohto repozitára na svojom GitHub účte -2. Kliknite na **Code** → **Karta Codespaces** → **...** → **Nový s možnosťami...** -3. Použite predvolené nastavenia – toto vyberie vývojové kontajner vytvorený pre tento kurz +1. Zálohujte si toto úložisko do svojho GitHub účtu +2. Kliknite na **Code** → záložka **Codespaces** → **...** → **Nový s možnosťami...** +3. Použite predvolené nastavenia – vyberie to vývojársky kontajner vytvorený pre tento kurz 4. Kliknite na **Create codespace** 5. Počkajte 5-10 minút, kým bude prostredie pripravené -6. Prejdite rovno do [Rýchleho štartu](./00-quick-start/README.md) a začnite! +6. Ihneď prejdite na [Úvod](./01-introduction/README.md) a začnite! -Po dokončení modulov preskúmajte [Testovací sprievodca](docs/TESTING.md), aby ste videli koncepty testovania LangChain4j v praxi. +Po dokončení modulov preskúmajte [Sprievodcu testovaním](docs/TESTING.md), kde uvidíte testovacie koncepty LangChain4j v praxi. -> **Poznámka:** Tento kurz používa modely GitHub a Azure OpenAI. Modul [Rýchly štart](00-quick-start/README.md) používa modely GitHub (nevyžaduje sa Azure predplatné), zatiaľ čo moduly 1-5 používajú Azure OpenAI. Ak ešte nemáte, začnite s [BEZPLATNÝM Azure účtom](https://aka.ms/azure-free-account). +> **Poznámka:** Tento tréning používa Azure OpenAI. Začnite s [PLATNÝM Azure účtom zadarmo](https://aka.ms/azure-free-account), ak ešte nemáte. +## Učenie s GitHub Copilot -## Vzdelávanie s GitHub Copilot +Na rýchle začatie kódovania otvorte tento projekt v GitHub Codespace alebo vo vašom lokálnom IDE s poskytnutým devcontainerom. Devcontainer použitý v tomto kurze je predkonfigurovaný s GitHub Copilot pre AI párové programovanie. -Ak chcete rýchlo začať kódovať, otvorte tento projekt v GitHub Codespace alebo vo svojom lokálnom IDE s poskytnutým devcontainerom. Devcontainer použitý v tomto kurze je predkonfigurovaný s GitHub Copilot pre AI párové programovanie. +Každý príklad kódu obsahuje navrhované otázky, ktoré môžete položiť GitHub Copilot, aby ste prehĺbili svoje znalosti. Hľadajte výzvy 💡/🤖 v: -Každý príklad kódu obsahuje navrhnuté otázky, ktoré môžete položiť GitHub Copilotu, aby ste prehĺbili svoje porozumenie. Hľadajte výzvy 💡/🤖 v: +- **Hlavičkách Java súborov** - otázky špecifické pre každý príklad +- **READMEs modulov** - výzvy na skúmanie po príkladoch kódu -- **Hlavičkách Java súborov** - Otázky špecifické pre každý príklad -- **README modulov** - Výskumné výzvy po príkladoch kódu - -**Ako používať:** Otvorte ľubovoľný kódový súbor a položte Copilotovi navrhnuté otázky. Má úplný kontext kódu a môže vysvetľovať, rozširovať a navrhovať alternatívy. +**Ako používať:** Otvorte akýkoľvek súbor s kódom a položte Copilotovi navrhované otázky. Má plný kontext zdrojového kódu a môže vysvetliť, rozšíriť a navrhnúť alternatívy. Chcete sa dozvedieť viac? Pozrite si [Copilot pre AI párové programovanie](https://aka.ms/GitHubCopilotAI). - -## Dodatočné zdroje +## Ďalšie zdroje ### LangChain -[![LangChain4j pre Začiatočníkov](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js pre Začiatočníkov](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain pre Začiatočníkov](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j pre začiatočníkov](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js pre začiatočníkov](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain pre začiatočníkov](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agenti -[![AZD pre Začiatočníkov](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI pre Začiatočníkov](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP pre Začiatočníkov](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agenti pre Začiatočníkov](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Agent +[![AZD pre začiatočníkov](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI pre začiatočníkov](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP pre začiatočníkov](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI agenti pre začiatočníkov](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Séria Generatívnej AI -[![Generatívna AI pre Začiatočníkov](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generatívna AI pre začiatočníkov](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generatívna AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generatívna AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) [![Generatívna AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Základné vzdelávanie -[![ML pre Začiatočníkov](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science pre Začiatočníkov](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI pre Začiatočníkov](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +### Základy učenia +[![ML pre začiatočníkov](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Dátová veda pre začiatočníkov](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI pre začiatočníkov](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Kybernetická bezpečnosť pre začiatočníkov](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Web vývoj pre začiatočníkov](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT pre začiatočníkov](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR vývoj pre začiatočníkov](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Séria Copilot -[![Copilot pre AI párové programovanie](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot pre C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot dobrodružstvo](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Získanie pomoci -Ak ste uviazli alebo máte nejaké otázky o budovaní AI aplikácií, pridajte sa: +Ak sa zaseknete alebo máte otázky ohľadom tvorby AI aplikácií, pripojte sa: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Ak máte pripomienky k produktu alebo chyby počas vývoja, navštívte: +Ak máte spätnú väzbu na produkt alebo pri tvorbe narazíte na chyby, navštívte: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licencia -MIT licencia - Pozrite si súbor [LICENSE](../../LICENSE) pre podrobnosti. +MIT licencia - Podrobnosti nájdete v súbore [LICENSE](../../LICENSE). --- -**Vyhlásenie o zodpovednosti**: -Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Aj keď sa snažíme o presnosť, uvedomte si, že automatizované preklady môžu obsahovať chyby alebo nepresnosti. Originálny dokument v jeho rodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nezodpovedáme za akékoľvek nedorozumenia alebo nesprávne výklady vyplývajúce z použitia tohto prekladu. +**Vyhlásenie o zodpovednosti**: +Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za žiadne nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu. \ No newline at end of file diff --git a/translations/sk/docs/GLOSSARY.md b/translations/sk/docs/GLOSSARY.md index 69fcad040..5b0d95cc6 100644 --- a/translations/sk/docs/GLOSSARY.md +++ b/translations/sk/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j Slovník +# LangChain4j Slovník pojmov ## Obsah -- [Základné pojmy](../../../docs) -- [Komponenty LangChain4j](../../../docs) -- [Pojmy AI/ML](../../../docs) -- [Bezpečnostné opatrenia](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agenti a nástroje](../../../docs) -- [Agentic Modul](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure služby](../../../docs) -- [Testovanie a vývoj](../../../docs) +- [Základné koncepty](#základné-koncepty) +- [Komponenty LangChain4j](#komponenty-langchain4j) +- [Koncepty AI/ML](#koncepty-aiml) +- [Bezpečnostné opatrenia](#bezpečnostné-opatrenia) +- [Návrh promptov](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agenti a nástroje](#agents-and-tools---module-04) +- [Agentic modul](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure služby](#azure-services---module-01) +- [Testovanie a vývoj](#testing-and-development---testing-guide) -Rýchla referencia pre pojmy a koncepty používané v priebehu kurzu. +Rýchly prehľad termínov a konceptov používaných v celom kurze. -## Základné pojmy +## Základné koncepty -**AI Agent** - Systém, ktorý používa AI na autonómne uvažovanie a konanie. [Modul 04](../04-tools/README.md) +**AI Agent** - Systém využívajúci AI na uvažovanie a autonómne konanie. [Modul 04](../04-tools/README.md) -**Chain** - Sekvencia operácií, kde výstup slúži ako vstup do ďalšieho kroku. +**Reťazec (Chain)** - Sekvencia operácií, kde výstup slúži ako vstup ďalšieho kroku. -**Chunking** - Rozdeľovanie dokumentov na menšie časti. Typicky 300-500 tokenov s prekrytím. [Modul 03](../03-rag/README.md) +**Rozdeľovanie na časti (Chunking)** - Rozdeľovanie dokumentov na menšie kúsky. Typické: 300-500 tokenov s prekrytím. [Modul 03](../03-rag/README.md) -**Context Window** - Maximálny počet tokenov, ktoré model dokáže spracovať. GPT-5.2: 400K tokenov (do 272K vstup, 128K výstup). +**Kontextové okno (Context Window)** - Maximálny počet tokenov, ktoré model dokáže spracovať. GPT-5.2: 400K tokenov (až 272K vstup, 128K výstup). **Embeddings** - Číselné vektory reprezentujúce význam textu. [Modul 03](../03-rag/README.md) -**Function Calling** - Model generuje štruktúrované požiadavky na volanie externých funkcií. [Modul 04](../04-tools/README.md) +**Volanie funkcií (Function Calling)** - Model generuje štruktúrované požiadavky na volanie externých funkcií. [Modul 04](../04-tools/README.md) -**Halucinácia** - Keď modely generujú nesprávne ale vierohodné informácie. +**Halucinácie (Hallucination)** - Keď modely generujú nesprávne, no na prvý pohľad pravdepodobné informácie. **Prompt** - Textový vstup do jazykového modelu. [Modul 02](../02-prompt-engineering/README.md) -**Sémantické vyhľadávanie** - Vyhľadávanie podľa významu pomocou embeddings, nie podľa kľúčových slov. [Modul 03](../03-rag/README.md) +**Sémantické vyhľadávanie (Semantic Search)** - Vyhľadávanie podľa významu pomocou embeddings, nie podľa kľúčových slov. [Modul 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: bez pamäti. Stateful: uchováva históriu konverzácie. [Modul 01](../01-introduction/README.md) +**Stavové vs. bezstavové (Stateful vs Stateless)** - Bezstavové: bez pamäte. Stavové: uchováva históriu konverzácie. [Modul 01](../01-introduction/README.md) -**Tokens** - Základné textové jednotky, ktoré model spracováva. Ovplyvňuje náklady a limity. [Modul 01](../01-introduction/README.md) +**Tokény (Tokens)** - Základné textové jednotky, ktoré modely spracúvajú. Ovplyvňujú náklady a limity. [Modul 01](../01-introduction/README.md) -**Tool Chaining** - Sekvenčné spúšťanie nástrojov, kde výstup ovplyvňuje ďalší hovor. [Modul 04](../04-tools/README.md) +**Zreťazenie nástrojov (Tool Chaining)** - Sekvenčné spúšťanie nástrojov, kde výstup informuje ďalšie volanie. [Modul 04](../04-tools/README.md) ## Komponenty LangChain4j -**AiServices** - Vytvára typovo bezpečné AI servisné rozhrania. +**AiServices** - Vytvára typovo bezpečné rozhrania AI služieb. -**OpenAiOfficialChatModel** - Zjednotený klient pre OpenAI a Azure OpenAI modely. +**OpenAiOfficialChatModel** - Uniformný klient pre OpenAI a Azure OpenAI modely. **OpenAiOfficialEmbeddingModel** - Vytvára embeddings pomocou oficiálneho klienta OpenAI (podporuje OpenAI aj Azure OpenAI). -**ChatModel** - Hlavné rozhranie pre jazykové modely. +**ChatModel** - Základné rozhranie pre jazykové modely. **ChatMemory** - Uchováva históriu konverzácie. -**ContentRetriever** - Nájde relevantné časti dokumentov pre RAG. +**ContentRetriever** - Nájdu relevantné kúsky dokumentov pre RAG. **DocumentSplitter** - Rozdeľuje dokumenty na časti. -**EmbeddingModel** - Premení text na číselné vektory. +**EmbeddingModel** - Konvertuje text na číselné vektory. **EmbeddingStore** - Ukladá a získava embeddings. -**MessageWindowChatMemory** - Udržiava kĺzavé okno nedávnych správ. +**MessageWindowChatMemory** - Uchováva posuvné okno nedávnych správ. -**PromptTemplate** - Vytvára opakovane použiteľné promptové šablóny s `{{variable}}` zástupcami. +**PromptTemplate** - Vytvára znovupoužiteľné prompty s {{variable}} zástupcami. **TextSegment** - Textový úsek s metadátami. Používa sa v RAG. -**ToolExecutionRequest** - Reprezentuje požiadavku na vykonanie nástroja. +**ToolExecutionRequest** - Reprezentuje požiadavku na spustenie nástroja. **UserMessage / AiMessage / SystemMessage** - Typy správ v konverzácii. -## Pojmy AI/ML +## Koncepty AI/ML -**Few-Shot Learning** - Poskytovanie príkladov v promptoch. [Modul 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Poskytnutie príkladov v promptoch. [Modul 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - AI modely trénované na rozsiahlych textových dátach. +**Veľký jazykový model (LLM)** - AI modely trénované na obrovskom množstve textových dát. -**Reasoning Effort** - Parameter GPT-5.2 riadiaci hĺbku uvažovania. [Modul 02](../02-prompt-engineering/README.md) +**Úsilie o uvažovanie (Reasoning Effort)** - Parameter GPT-5.2 regulujúci hĺbku uvažovania. [Modul 02](../02-prompt-engineering/README.md) -**Temperature** - Riadi náhodnosť výstupu. Nízka=deterministické, vysoká=kreatívne. +**Teplota (Temperature)** - Riadi náhodnosť výstupu. Nízka = deterministický, vysoká = kreatívny. **Vektorová databáza** - Špecializovaná databáza pre embeddings. [Modul 03](../03-rag/README.md) **Zero-Shot Learning** - Vykonávanie úloh bez príkladov. [Modul 02](../02-prompt-engineering/README.md) -## Bezpečnostné opatrenia - [Modul 00](../00-quick-start/README.md) +## Bezpečnostné opatrenia -**Defense in Depth** - Viacvrstvový bezpečnostný prístup kombinujúci aplikačné guardrails so bezpečnostnými filtrami poskytovateľa. +**Obrana v hĺbke (Defense in Depth)** - Viacvrstvový bezpečnostný prístup kombinujúci aplikačné ochrany s bezpečnostnými filtrami poskytovateľa. -**Hard Block** - Poskytovateľ vyhodí HTTP 400 chybu pri vážnom porušení obsahu. +**Tvrdý blok (Hard Block)** - Poskytovateľ vracia HTTP 400 chybu pri vážnych porušeniach obsahu. -**InputGuardrail** - Rozhranie LangChain4j na validáciu používateľského vstupu pred dosiahnutím LLM. Šetrí náklady a latenciu tým, že blokuje škodlivé prompty skôr. +**InputGuardrail** - Rozhranie LangChain4j na validáciu používateľského vstupu pred odoslaním do LLM. Šetrí náklady a latenciu blokovaním škodlivých promptov včas. -**InputGuardrailResult** - Návratový typ validácie guardrailu: `success()` alebo `fatal("dôvod")`. +**InputGuardrailResult** - Typ návratovej hodnoty validácie: `success()` alebo `fatal("dôvod")`. -**OutputGuardrail** - Rozhranie na validáciu odpovedí AI pred ich vrátením používateľom. +**OutputGuardrail** - Rozhranie na validáciu odpovedí AI pred ich odoslaním používateľom. -**Filtery bezpečnosti poskytovateľa** - Vstavané filtre obsahu od AI poskytovateľov (napr. GitHub Models), ktoré zachytávajú porušenia na úrovni API. +**Bezpečnostné filtre poskytovateľa** - Vstavané filtre obsahu od AI poskytovateľov (napr. Azure OpenAI), ktoré zachytávajú porušenia na úrovni API. -**Soft Refusal** - Model zdvorilo odmietne odpovedať bez vyvolania chyby. +**Mäkké odmietnutie (Soft Refusal)** - Model slušne odmietne odpovedať bez chyby. -## Prompt Engineering - [Modul 02](../02-prompt-engineering/README.md) +## Návrh promptov - [Modul 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Postupné uvažovanie pre lepšiu presnosť. +**Reťazec myšlienok (Chain-of-Thought)** - Krokovanie uvažovania pre lepšiu presnosť. -**Constrained Output** - Vynútenie konkrétneho formátu alebo štruktúry. +**Obmedzený výstup (Constrained Output)** - Vynucovanie konkrétneho formátu alebo štruktúry. -**High Eagerness** - Vzor GPT-5.2 pre dôkladné uvažovanie. +**Vysoká snaha (High Eagerness)** - Vzorec GPT-5.2 pre dôkladné uvažovanie. -**Low Eagerness** - Vzor GPT-5.2 pre rýchle odpovede. +**Nízka snaha (Low Eagerness)** - Vzorec GPT-5.2 pre rýchle odpovede. -**Multi-Turn Conversation** - Udržiavanie kontextu v priebehu výmen. +**Viackolová konverzácia (Multi-Turn Conversation)** - Udržiavanie kontextu naprieč výmenami. -**Role-Based Prompting** - Nastavenie osobnosti modelu cez systémové správy. +**Promptovanie podľa rolí (Role-Based Prompting)** - Nastavenie modelovej persony pomocou systémových správ. -**Self-Reflection** - Model hodnotí a zlepšuje svoj výstup. +**Sebareflexia (Self-Reflection)** - Model hodnotí a zlepšuje svoj výstup. -**Structured Analysis** - Pevný hodnotiaci rámec. +**Štruktúrovaná analýza (Structured Analysis)** - Fixný rámec hodnotenia. -**Task Execution Pattern** - Plánuj → Vykonaj → Zhrň. +**Vzor vykonávania úlohy (Task Execution Pattern)** - Plánuj → Vykonaj → Zhrni. ## RAG (Retrieval-Augmented Generation) - [Modul 03](../03-rag/README.md) -**Document Processing Pipeline** - Načítať → rozdeliť → embedded → uložiť. +**Pracovný tok spracovania dokumentov (Document Processing Pipeline)** - Načítaj → rozdeľ → vlož do embeddingov → ulož. -**In-Memory Embedding Store** - Nepersistentné uloženie na testovanie. +**Pamäťové úložisko embeddingov (In-Memory Embedding Store)** - Nepersistentné úložisko na testovanie. -**RAG** - Kombinuje vyhľadávanie a generovanie na zakotvenie odpovedí. +**RAG** - Kombinuje vyhľadávanie a generovanie pre overené odpovede. -**Similarity Score** - Miera (0-1) sémantickej podobnosti. +**Miera podobnosti (Similarity Score)** - Miera (0-1) sémantickej podobnosti. -**Source Reference** - Metadáta o získanom obsahu. +**Zdrojová referencia (Source Reference)** - Metadáta o načítanom obsahu. ## Agenti a nástroje - [Modul 04](../04-tools/README.md) -**@Tool Anotácia** - Označuje Java metódy ako AI volateľné nástroje. +**@Tool anotácia** - Označuje Java metódy ako AI-volateľné nástroje. -**ReAct Pattern** - Uvažuj → Konaj → Pozoruj → Opakuj. +**ReAct vzorec** - Uvažuj → Konaj → Pozoruj → Opakuj. -**Správa relácie** - Oddelené kontexty pre rôznych používateľov. +**Správa relácií (Session Management)** - Oddelené kontexty pre rôznych používateľov. -**Nástroj** - Funkcia, ktorú AI agent môže vyvolať. +**Nástroj (Tool)** - Funkcia, ktorú môže AI agent volať. -**Popis nástroja** - Dokumentácia účelu nástroja a parametrov. +**Popis nástroja (Tool Description)** - Dokumentácia účelu a parametrov nástroja. -## Agentic Modul - [Modul 05](../05-mcp/README.md) +## Agentic modul - [Modul 05](../05-mcp/README.md) -**@Agent Anotácia** - Označuje rozhrania ako AI agentov s deklaratívnym definovaním správania. +**@Agent anotácia** - Označuje rozhrania ako AI agentov s deklaratívnym definovaním správania. **Agent Listener** - Háčik na monitorovanie vykonávania agenta cez `beforeAgentInvocation()` a `afterAgentInvocation()`. -**Agentic Scope** - Zdieľaná pamäť, kde agenti ukladajú výstupy pomocou `outputKey` pre použitie downstream agentmi. +**Agentic Scope** - Zdieľaná pamäť, kde agenti ukladajú výstupy pomocou `outputKey` pre ďalších agentov. -**AgenticServices** - Fabrika na vytváranie agentov pomocou `agentBuilder()` a `supervisorBuilder()`. +**AgenticServices** - Fabrika na tvorbu agentov cez `agentBuilder()` a `supervisorBuilder()`. -**Podmienkový workflow** - Trasa podľa podmienok ku rôznym špecializovaným agentom. +**Podmienený pracovný tok (Conditional Workflow)** - Trasa podľa podmienok k rôznym špecializovaným agentom. -**Human-in-the-Loop** - Vzorec workflow pridávajúci ľudské kontrolné body na schválenie alebo revíziu obsahu. +**Človek v slučke (Human-in-the-Loop)** - Vzorec pracovného toku pridávajúci ľudské kontroly na schválenie alebo revíziu obsahu. -**langchain4j-agentic** - Maven závislosť pre deklaratívnu tvorbu agentov (experimentálne). +**langchain4j-agentic** - Maven závislosť na deklaratívnu tvorbu agentov (experimentálne). -**Loop Workflow** - Iteruje vykonávanie agenta až do splnenia podmienky (napr. skóre kvality ≥ 0.8). +**Cyklický pracovný tok (Loop Workflow)** - Iteruje vykonávanie agenta, kým nie je splnená podmienka (napr. skóre kvality ≥ 0.8). -**outputKey** - Parameter anotácie agenta určujúci, kde sa uložia výsledky v Agentic Scope. +**outputKey** - Parameter anotácie agenta určujúci, kde sa výsledky ukladajú v Agentic Scope. -**Paralelný workflow** - Súčasné spúšťanie viacerých agentov pre nezávislé úlohy. +**Paralelný pracovný tok (Parallel Workflow)** - Súbežné spúšťanie viacerých agentov pre nezávislé úlohy. -**Response Strategy** - Ako dozorný agent formuluje konečnú odpoveď: LAST, SUMMARY alebo SCORED. +**Stratégia odpovede (Response Strategy)** - Ako supervízor formuluje finálnu odpoveď: LAST, SUMMARY alebo SCORED. -**Sekvenčný workflow** - Vykonávanie agentov podľa poradia, kde výstup prúdi do ďalšieho kroku. +**Sekvenčný pracovný tok (Sequential Workflow)** - Vykonanie agentov za sebou, kde výstup tečie do ďalšieho kroku. -**Supervisor Agent Pattern** - Pokročilý agentický vzorec, kde dozorný LLM dynamicky rozhoduje, ktorých podagentov spustiť. +**Supervisor Agent Pattern** - Pokročilý agentický vzorec, kde supervízor LLM dynamicky rozhoduje, ktorých podagentov zavolať. ## Model Context Protocol (MCP) - [Modul 05](../05-mcp/README.md) **langchain4j-mcp** - Maven závislosť pre integráciu MCP v LangChain4j. -**MCP** - Model Context Protocol: štandard pre prepájanie AI aplikácií s externými nástrojmi. Vytvor raz, používaj všade. +**MCP** - Model Context Protocol: štandard na prepojenie AI aplikácií s externými nástrojmi. Spoj raz, používaj všade. -**MCP Client** - Aplikácia pripájajúca sa k MCP serverom na objavovanie a používanie nástrojov. +**MCP klient** - Aplikácia, ktorá sa pripája na MCP servery, aby objavila a používala nástroje. -**MCP Server** - Služba vystavujúca nástroje cez MCP s jasnými popismi a schémami parametrov. +**MCP server** - Služba vystavujúca nástroje cez MCP s jasnými popismi a schémami parametrov. -**McpToolProvider** - Komponent LangChain4j, ktorý obaluje MCP nástroje na použitie v AI službách a agentoch. +**McpToolProvider** - Komponent LangChain4j, ktorý obalí MCP nástroje pre použitie v AI službách a agentoch. -**McpTransport** - Rozhranie na MCP komunikáciu. Implementácie zahŕňajú Stdio a HTTP. +**McpTransport** - Rozhranie pre komunikáciu MCP. Implementácie zahŕňajú Stdio a HTTP. -**Stdio Transport** - Lokálny procesný transport cez stdin/stdout. Užitečné pre prístup k súborovému systému alebo príkazové nástroje. +**Stdio transport** - Lokálny transport procesov cez stdin/stdout. Vhodný na prístup k súborovému systému alebo príkazovým nástrojom. -**StdioMcpTransport** - Implementácia LangChain4j, ktorá spúšťa MCP server ako podproces. +**StdioMcpTransport** - Implementácia LangChain4j, ktorá spúšťa MCP server ako podsproces. -**Objavovanie nástrojov** - Klient dopytuje server po dostupných nástrojoch s popismi a schémami. +**Objavovanie nástrojov (Tool Discovery)** - Klient zisťuje dostupné nástroje so špecifikáciami a popismi. ## Azure služby - [Modul 01](../01-introduction/README.md) -**Azure AI Search** - Cloudové vyhľadávanie s vektorovými schopnosťami. [Modul 03](../03-rag/README.md) +**Azure AI Search** - Cloudové vyhľadávanie so schopnosťou práce s vektormi. [Modul 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Nástroj na nasadenie Azure prostriedkov. +**Azure Developer CLI (azd)** - Nasadzuje Azure zdroje. -**Azure OpenAI** - Podniková AI služba Microsoftu. +**Azure OpenAI** - Podniková AI služba od Microsoftu. -**Bicep** - Azure jazyk infraštruktúry ako kódu. [Sprievodca infraštruktúrou](../01-introduction/infra/README.md) +**Bicep** - Jazyk infraštruktúry ako kódu pre Azure. [Infrastructure Guide](../01-introduction/infra/README.md) -**Názov nasadenia** - Názov pre nasadenie modelu v Azure. +**Názov nasadenia (Deployment Name)** - Názov pre nasadenie modelu v Azure. -**GPT-5.2** - Najnovší model OpenAI s riadením uvažovania. [Modul 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Najnovší OpenAI model s riadením uvažovania. [Modul 02](../02-prompt-engineering/README.md) -## Testovanie a vývoj - [Testovací sprievodca](TESTING.md) +## Testovanie a vývoj - [Testing Guide](TESTING.md) **Dev Container** - Kontajnerizované vývojové prostredie. [Konfigurácia](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Bezplatné AI modelové prostredie. [Modul 00](../00-quick-start/README.md) +**Testovanie v pamäti (In-Memory Testing)** - Testovanie s úložiskom v pamäti. -**In-Memory Testing** - Testovanie s využitím pamäťového uloženia. +**Integračné testovanie (Integration Testing)** - Testovanie s reálnou infraštruktúrou. -**Integration Testing** - Testovanie s reálnou infraštruktúrou. +**Maven** - Nástroj na automatizáciu buildov v Jave. -**Maven** - Java nástroj na automatizáciu buildov. +**Mockito** - Framework na mocking v Jave. -**Mockito** - Java knižnica na mockovanie. - -**Spring Boot** - Java aplikačný framework. [Modul 01](../01-introduction/README.md) +**Spring Boot** - Framework pre Java aplikácie. [Modul 01](../01-introduction/README.md) --- -**Upozornenie**: -Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, majte na pamäti, že automatizované preklady môžu obsahovať chyby alebo nepresnosti. Originálny dokument v jeho pôvodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nezodpovedáme za akékoľvek nedorozumenia alebo nesprávne výklady vyplývajúce z používania tohto prekladu. +**Vyhlásenie o zodpovednosti**: +Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za žiadne nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu. \ No newline at end of file diff --git a/translations/sk/docs/TESTING.md b/translations/sk/docs/TESTING.md index 0d209b362..7ecf42ad1 100644 --- a/translations/sk/docs/TESTING.md +++ b/translations/sk/docs/TESTING.md @@ -2,19 +2,19 @@ ## Obsah -- [Rýchly štart](../../../docs) -- [Čo testy pokrývajú](../../../docs) -- [Spustenie testov](../../../docs) -- [Spustenie testov vo VS Code](../../../docs) -- [Vzory testovania](../../../docs) -- [Filozofia testovania](../../../docs) -- [Ďalšie kroky](../../../docs) +- [Rýchly štart](#rýchly-štart) +- [Čo testy pokrývajú](#čo-testy-pokrývajú) +- [Spustenie testov](#spustenie-testov) +- [Spustenie testov vo VS Code](#spustenie-testov-vo-vs-code) +- [Testovacie vzory](#testovacie-vzory) +- [Testovacia filozofia](#testovacia-filozofia) +- [Ďalšie kroky](#ďalšie-kroky) -Táto príručka vás prevedie testami, ktoré ukazujú, ako testovať AI aplikácie bez nutnosti API kľúčov alebo externých služieb. +Tento návod vás prevedie testmi, ktoré ukazujú, ako testovať AI aplikácie bez potreby API kľúčov alebo externých služieb. ## Rýchly štart -Spustite všetky testy jediným príkazom: +Spustite všetky testy jedným príkazom: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Keď všetky testy prebehnú úspešne, mali by ste vidieť výstup ako na obrázku nižšie — testy prebiehajú bez zlyhaní. +Keď všetky testy prejdú, mali by ste vidieť výstup ako na obrázku nižšie — testy prebehli bez jediného zlyhania. -Úspešné výsledky testov +Successful Test Results -*Úspešné spustenie testov ukazujúce, že všetky testy prešli bez zlyhaní* +*Úspešné vykonanie testov ukazujúce, že všetky testy prešli bez zlyhaní* ## Čo testy pokrývajú -Tento kurz sa zameriava na **jednotkové testy**, ktoré sa spúšťajú lokálne. Každý test predvádza určitý koncept LangChain4j izolovane. Nižšie je testovacia pyramída, ktorá ukazuje, kde jednotkové testy zapadajú — tvoria rýchly a spoľahlivý základ, na ktorom sa buduje zvyšok vašej testovacej stratégie. +Tento kurz sa zameriava na **jednotkové testy**, ktoré bežia lokálne. Každý test demonštruje konkrétny koncept LangChain4j samostatne. Nižšie uvedená testovacia pyramída ukazuje, kde jednotkové testy zapadajú — tvoria rýchly, spoľahlivý základ, na ktorom je postavená zvyšná testovacia stratégia. -Testovacia pyramída +Testing Pyramid -*Testovacia pyramída ukazujúca rovnováhu medzi jednotkovými testami (rýchle, izolované), integračnými testami (skutočné komponenty) a end-to-end testami. Tento kurz sa zaoberá jednotkovým testovaním.* +*Testovacia pyramída ukazujúca rovnováhu medzi jednotkovými testami (rýchle, izolované), integračnými testami (skutočné komponenty) a end-to-end testami. Tento kurz pokrýva jednotkové testovanie.* | Modul | Testy | Zameranie | Kľúčové súbory | -|--------|-------|-----------|----------------| -| **00 - Rýchly štart** | 6 | Šablóny promptov a nahradzovanie premenných | `SimpleQuickStartTest.java` | +|--------|-------|-------|-----------| | **01 - Úvod** | 8 | Pamäť konverzácie a stavový chat | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | GPT-5.2 vzory, úrovne ochoty, štruktúrovaný výstup | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Načítanie dokumentov, embeddingy, vyhľadávanie podobností | `DocumentServiceTest.java` | +| **02 - Prompt Engineering** | 12 | Vzory GPT-5.2, úrovne nadšenia, štruktúrovaný výstup | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Spracovanie dokumentov, vkladania, vyhľadávanie podobnosti | `DocumentServiceTest.java` | | **04 - Nástroje** | 12 | Volanie funkcií a reťazenie nástrojov | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol s transportom stdio | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | Protokol Model Context pomocou stdio transportu | `SimpleMcpTest.java` | ## Spustenie testov -**Spustenie všetkých testov z koreňového adresára:** +**Spustite všetky testy z koreňového adresára:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Spustenie testov pre konkrétny modul:** +**Spustite testy pre konkrétny modul:** **Bash:** ```bash @@ -75,11 +74,11 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Alebo z koreňa +# Alebo od koreňa mvn --% test -pl 01-introduction ``` -**Spustenie jedného testovacieho triedy:** +**Spustite jednu testovaciu triedu:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Spustenie konkrétnej testovacej metódy:** +**Spustite konkrétnu testovaciu metódu:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#mal by udržiavať históriu rozhovoru +mvn test -Dtest=SimpleConversationTest#mal by zachovať históriu konverzácie ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#mal by udržiavať históriu konverzácie +mvn --% test -Dtest=SimpleConversationTest#mala by zachovať históriu konverzácie ``` ## Spustenie testov vo VS Code -Ak používate Visual Studio Code, Test Explorer poskytuje grafické rozhranie pre spúšťanie a ladenie testov. +Ak používate Visual Studio Code, Test Explorer poskytuje grafické rozhranie na spúšťanie a ladenie testov. VS Code Test Explorer -*VS Code Test Explorer ukazujúci strom testov so všetkými Java testovacími triedami a jednotlivými testovacími metódami* +*Test Explorer vo VS Code ukazujúci strom testov so všetkými Java testovacími triedami a jednotlivými testovacími metódami* **Ako spustiť testy vo VS Code:** 1. Otvorte Test Explorer kliknutím na ikonu skúmavky v paneli aktivít -2. Rozbaľte strom testov, aby ste videli všetky moduly a testovacie triedy -3. Kliknite na tlačidlo prehrávania vedľa ľubovoľného testu pre jeho samostatné spustenie -4. Kliknite na "Run All Tests" pre spustenie celého balíka testov -5. Kliknite pravým tlačidlom na ktorýkoľvek test a vyberte "Debug Test" pre nastavenie breakpointov a krokovanie kódu +2. Rozbaľte strom testov a zobrazte všetky moduly a testovacie triedy +3. Kliknite na tlačidlo pre spustenie vedľa akéhokoľvek testu pre jeho spustenie samostatne +4. Kliknite na "Run All Tests" pre spustenie celej sady +5. Kliknite pravým tlačidlom na hociktorý test a vyberte "Debug Test" pre nastavenie breakpointov a krokovanie kódom -Test Explorer zobrazuje zelené zaškrtnutia pri úspešných testoch a poskytuje podrobné oznámenia o zlyhaniach, keď testy zlyhajú. +Test Explorer zobrazuje zelené zaškrtnutia pre prešlé testy a poskytuje podrobné správy o neúspechoch, keď testy zlyhajú. -## Vzory testovania +## Testovacie vzory -### Vzor 1: Testovanie šablón promptov +### Vzor 1: Testovanie prompt šablón -Najjednoduchší vzor testuje šablóny promptov bez volania AI modelu. Overujete, že nahradzovanie premenných funguje správne a prompty sú formátované podľa očakávania. +Najjednoduchší vzor testuje prompt šablóny bez volania AI modelu. Overujete, že substitúcia premenných funguje správne a prompt je naformátovaný podľa očakávaní. -Testovanie šablón promptov +Prompt Template Testing -*Testovanie šablón promptov ukazujúce proces nahradzovania premenných: šablóna s zástupcami → aplikované hodnoty → overený formátovaný výstup* +*Testovanie prompt šablón ukazujúce tok substitúcie premenných: šablóna s miestami pre hodnoty → aplikované hodnoty → overený naformátovaný výstup* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Tento test sa nachádza v súbore `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Spustite ho:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testFormátovaniaŠablónyVýzvy -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#test formátovania šablóny výzvy -``` +Tento vzor overuje správnu substitúciu premenných a formátovanie promptov — nie je potrebný API kľúč ani volanie modelu. ### Vzor 2: Mockovanie jazykových modelov -Pri testovaní logiky konverzácie používajte Mockito na vytvorenie falošných modelov, ktoré vracajú preddefinované odpovede. Toto robí testy rýchlymi, bezplatnými a deterministickými. +Pri testovaní logiky konverzácie použite Mockito na vytvorenie falošných modelov, ktoré vracajú vopred určené odpovede. Toto robí testy rýchlymi, bezplatnými a deterministickými. -Porovnanie mock vs skutočné API +Mock vs Real API Comparison -*Porovnanie ukazujúce, prečo sú mockingy preferované pri testovaní: sú rýchle, zadarmo, deterministické a nevyžadujú API kľúče* +*Porovnanie ukazujúce, prečo sú mocky preferované pri testovaní: sú rýchle, zadarmo, deterministické a nevyžadujú API kľúče* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Tento vzor sa nachádza v `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock zaručuje konzistentné správanie, takže môžete overiť správne spravovanie pamäte. +Tento vzor sa nachádza v `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mock zaručuje konzistentné správanie, aby ste mohli overiť správu pamäte. ### Vzor 3: Testovanie izolácie konverzácie -Pamäť konverzácie musí udržiavať viacerých používateľov oddelene. Tento test overuje, že sa konverzácie nekrižujú. +Pamäť konverzácie musí udržiavať viacerých používateľov oddelene. Tento test overuje, že sa konverzácie neprelínajú. -Izolácia konverzácie +Conversation Isolation -*Testovanie izolácie konverzácie ukazujúce samostatné úložiská pamäte pre rôznych používateľov, aby sa predišlo miešaniu kontextov* +*Testovanie izolácie konverzácie ukazujúce oddelené úložiská pamäte pre rôznych používateľov, aby sa predišlo prelínaniu kontextov* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Každá konverzácia udržiava svoju vlastnú nezávislú históriu. V produkčných systémoch je táto izolácia kľúčová pre aplikácie s viacerými používateľmi. +Každá konverzácia si udržiava vlastnú nezávislú históriu. V produkčných systémoch je táto izolácia kritická pre aplikácie s viacerými používateľmi. ### Vzor 4: Testovanie nástrojov samostatne -Nástroje sú funkcie, ktoré môže AI volať. Testujte ich priamo, aby ste zabezpečili ich správnu funkčnosť nezávisle od rozhodnutí AI. +Nástroje sú funkcie, ktoré môže AI volať. Testujte ich priamo, aby ste sa uistili, že fungujú správne nezávisle od rozhodnutí AI. -Testovanie nástrojov +Tools Testing -*Testovanie nástrojov samostatne ukazujúce spustenie mock nástrojov bez volania AI na overenie obchodnej logiky* +*Samostatné testovanie nástrojov ukazujúce vykonávanie mock nástrojov bez volaní AI na overenie obchodnej logiky* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Tieto testy z `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` overujú logiku nástrojov bez účasti AI. Príklad reťazenia ukazuje, ako výstup jedného nástroja ovplyvňuje vstup ďalšieho. +Tieto testy z `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` overujú logiku nástrojov bez zapojenia AI. Príklad reťazenia ukazuje, ako výstup jedného nástroja vstupuje do druhého. ### Vzor 5: Testovanie RAG v pamäti -RAG systémy tradične vyžadujú vektorové databázy a embedding služby. Vzor v pamäti umožňuje testovať celý pipeline bez externých závislostí. +RAG systémy tradične vyžadujú vektorové databázy a embedding služby. Vzor v pamäti vám umožňuje testovať celý proces bez externých závislostí. -Testovanie RAG v pamäti +In-Memory RAG Testing -*Testovanie RAG v pamäti ukazujúce spracovanie dokumentu, ukladanie embeddingov a vyhľadávanie podobností bez potreby databázy* +*Pracovný tok testovania RAG v pamäti ukazujúci spracovanie dokumentov, ukladanie embeddingov a vyhľadávanie podobnosti bez potreby databázy* ```java @Test @@ -306,11 +293,11 @@ void testProcessTextDocument() { } ``` -Tento test z `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` vytvára dokument v pamäti a overuje jeho rozklad na kúsky a spracovanie metadát. +Tento test z `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` vytvára dokument v pamäti a overuje delenie na kúsky a spracovanie metadát. ### Vzor 6: Integračné testovanie MCP -Modul MCP testuje integráciu protokolu Model Context Protocol pomocou stdio transportu. Tieto testy overujú, že vaša aplikácia dokáže spúšťať a komunikovať s MCP servermi ako podprocesmi. +Modul MCP testuje integráciu Model Context Protokolu pomocou stdio transportu. Tieto testy overujú, že vaša aplikácia môže spúšťať a komunikovať s MCP servermi ako podprocesmi. Testy v `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` overujú správanie MCP klienta. @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## Filozofia testovania +## Testovacia filozofia -Testujte svoj kód, nie AI. Vaše testy by mali validovať kód, ktorý píšete, tým, že kontrolujú, ako sa prompty konštruujú, ako sa spravuje pamäť a ako sa vykonávajú nástroje. AI odpovede sa môžu líšiť a nemali by byť súčasťou testovacích tvrdení. Pýtajte sa, či vaša šablóna promptu správne nahrádza premenné, nie či AI dáva správnu odpoveď. +Testujte svoj kód, nie AI. Vaše testy by mali overovať kód, ktorý píšete, kontrolou, ako sú konštruované prompty, ako sa spravuje pamäť a ako funguje vykonávanie nástrojov. Odpovede AI sa líšia a nemali by byť predmetom testovacích tvrdení. Pýtajte sa, či vaša prompt šablóna správne nahrádza premenné, nie či AI dáva správnu odpoveď. -Používajte mocky pre jazykové modely. Sú to externé závislosti, ktoré sú pomalé, drahé a nedeterministické. Mockovanie robí testy rýchlymi (v milisekundách namiesto sekúnd), bezplatnými (žiadne API náklady) a deterministickými (rovnaký výsledok zakaždým). +Používajte mocky pre jazykové modely. Sú to externé závislosti, ktoré sú pomalé, drahé a nedeterministické. Mockovanie robí testy rýchlymi s milisekundami namiesto sekúnd, bezplatnými bez nákladov na API a deterministickými so stále rovnakým výsledkom. -Udržujte testy nezávislé. Každý test by mal nastaviť vlastné dáta, nespoliehať sa na iné testy a po sebe upratať. Testy by mali prejsť bez ohľadu na poradie spúšťania. +Udržujte testy nezávislé. Každý test by mal nastaviť vlastné dáta, nespoliehať sa na iné testy a po sebe upratať. Testy by mali prejsť bez ohľadu na poradie spustenia. -Testujte hraničné prípady mimo bežných scénarov. Skúste prázdne vstupy, veľmi veľké vstupy, špeciálne znaky, neplatné parametre a hranicné podmienky. Tieto často odhalia chyby, ktoré bežné používanie neodhalí. +Testujte okrajové prípady nad rámec štandardného priebehu. Skúšajte prázdne vstupy, veľmi veľké vstupy, špeciálne znaky, neplatné parametre a hraničné podmienky. Tieto často odhaľujú chyby, ktoré bežné používanie nezjistí. -Používajte popisné názvy. Porovnajte `shouldMaintainConversationHistoryAcrossMultipleMessages()` a `test1()`. Prvý názov presne vysvetľuje, čo sa testuje, čo výrazne uľahčuje ladenie zlyhaní. +Používajte popisné názvy. Porovnajte `shouldMaintainConversationHistoryAcrossMultipleMessages()` s `test1()`. Prvý vám presne povie, čo sa testuje, čo veľmi uľahčuje ladenie v prípade zlyhaní. ## Ďalšie kroky -Keď už rozumiete testovacím vzorom, ponorte sa hlbšie do jednotlivých modulov: +Teraz, keď rozumiete testovacím vzorom, študujte každý modul podrobnejšie: -- **[00 - Rýchly štart](../00-quick-start/README.md)** - Začnite so základmi šablón promptov - **[01 - Úvod](../01-introduction/README.md)** - Naučte sa spravovať pamäť konverzácie -- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Osvojte si vzory pre GPT-5.2 promptovanie -- **[03 - RAG](../03-rag/README.md)** - Budujte systémy pre retrieval-augmented generation -- **[04 - Nástroje](../04-tools/README.md)** - Implementujte volanie funkcií a reťazce nástrojov +- **[02 - Prompt Engineering](../02/prompt-engineering/README.md)** - Ovládnite vzory promptovania GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Budujte systémy retrieval-augmented generation +- **[04 - Nástroje](../04-tools/README.md)** - Implementujte volanie funkcií a reťazenie nástrojov - **[05 - MCP](../05-mcp/README.md)** - Integrujte Model Context Protocol README každého modulu poskytuje podrobné vysvetlenia konceptov testovaných tu. --- -**Navigácia:** [← Späť na hlavné](../README.md) +**Navigácia:** [← Späť na Hlavnú stránku](../README.md) --- -**Zrieknutie sa zodpovednosti**: -Tento dokument bol preložený pomocou AI prekladačskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Aj keď sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Originálny dokument v jeho rodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre dôležité informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za akékoľvek nejasnosti alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu. +**Vyhlásenie o zodpovednosti**: +Tento dokument bol preložený pomocou AI prekladateľskej služby [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, vezmite prosím na vedomie, že automatické preklady môžu obsahovať chyby alebo nepresnosti. Pôvodný dokument v jeho natívnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za žiadne nedorozumenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu. \ No newline at end of file diff --git a/translations/sl/.co-op-translator.json b/translations/sl/.co-op-translator.json index 3482bf271..b3d9a1c69 100644 --- a/translations/sl/.co-op-translator.json +++ b/translations/sl/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "sl" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T03:49:09+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T11:39:27+00:00", "source_file": "01-introduction/README.md", "language_code": "sl" }, @@ -18,20 +18,20 @@ "language_code": "sl" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T03:51:34+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T11:26:12+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "sl" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T03:53:09+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T11:36:51+00:00", "source_file": "03-rag/README.md", "language_code": "sl" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:48:40+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T11:32:45+00:00", "source_file": "04-tools/README.md", "language_code": "sl" }, @@ -54,8 +54,8 @@ "language_code": "sl" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:04:29+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T11:22:26+00:00", "source_file": "README.md", "language_code": "sl" }, @@ -72,14 +72,14 @@ "language_code": "sl" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T03:56:30+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T11:27:42+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "sl" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T03:57:19+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T11:29:21+00:00", "source_file": "docs/TESTING.md", "language_code": "sl" } diff --git a/translations/sl/00-quick-start/README.md b/translations/sl/00-quick-start/README.md deleted file mode 100644 index ba7aee303..000000000 --- a/translations/sl/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modul 00: Hiter začetek - -## Kazalo - -- [Uvod](../../../00-quick-start) -- [Kaj je LangChain4j?](../../../00-quick-start) -- [Odvisnosti LangChain4j](../../../00-quick-start) -- [Predpogoji](../../../00-quick-start) -- [Nastavitev](../../../00-quick-start) - - [1. Pridobite svoj GitHub žeton](../../../00-quick-start) - - [2. Nastavite svoj žeton](../../../00-quick-start) -- [Zagon primerov](../../../00-quick-start) - - [1. Osnovni klepet](../../../00-quick-start) - - [2. Vzorci pozivov](../../../00-quick-start) - - [3. Klic funkcij](../../../00-quick-start) - - [4. Vprašanja in odgovori o dokumentih (Easy RAG)](../../../00-quick-start) - - [5. Odgovorna AI](../../../00-quick-start) -- [Kaj posamezen primer prikazuje](../../../00-quick-start) -- [Naslednji koraki](../../../00-quick-start) -- [Reševanje težav](../../../00-quick-start) - -## Uvod - -Ta hiter začetek je namenjen, da vas čim prej spravi v pogon z LangChain4j. Pokriva absolutne osnove ustvarjanja AI aplikacij z LangChain4j in GitHub modeli. V naslednjih modulih boste prešli na Azure OpenAI in GPT-5.2 ter se poglobili v vsak koncept. - -## Kaj je LangChain4j? - -LangChain4j je Java knjižnica, ki poenostavlja ustvarjanje aplikacij, ki temeljijo na AI. Namesto da bi se ukvarjali z HTTP odjemalci in JSON razčlenjevanjem, delate s čistimi Java API-ji. - -"Veriga" v LangChain pomeni povezovanje več komponent - lahko povežete poziv z modelom in z razčlenjevalnikom ali povežete več AI klicev zaporedoma, kjer en izhod služi kot naslednji vhod. Ta hiter začetek se osredotoča na osnovna načela, preden raziskujete bolj zapletene verige. - -LangChain4j Chaining Concept - -*Povezovanje komponent v LangChain4j - gradniki se povezujejo, da ustvarijo močne AI delovne tokove* - -Uporabili bomo tri osnovne komponente: - -**ChatModel** - Vmesnik za interakcijo z AI modeli. Pokličete `model.chat("prompt")` in dobite niz odgovora. Uporabljamo `OpenAiOfficialChatModel`, ki deluje z OpenAI-kompatibilnimi končnimi točkami, kot so GitHub modeli. - -**AiServices** - Ustvari tipno varne vmesnike AI storitev. Definirajte metode, jih označite z `@Tool`, LangChain4j pa poskrbi za orkestracijo. AI samodejno kliče vaše Java metode, ko je to potrebno. - -**MessageWindowChatMemory** - Ohranja zgodovino pogovora. Brez tega je vsak zahtevek neodvisen. Z njim se AI spomni prejšnjih sporočil in vzdržuje kontekst skozi več krogov. - -LangChain4j Architecture - -*Arhitektura LangChain4j - osnovne komponente sodelujejo za pogon vaših AI aplikacij* - -## Odvisnosti LangChain4j - -Ta hiter začetek uporablja tri Maven odvisnosti v [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modul `langchain4j-open-ai-official` zagotavlja razred `OpenAiOfficialChatModel`, ki se povezuje z OpenAI-kompatibilnimi API-ji. GitHub modeli uporabljajo enak API format, zato ni potrebnega posebnega vmesnika - samo usmerite osnovni URL na `https://models.github.ai/inference`. - -Modul `langchain4j-easy-rag` zagotavlja avtomatsko razdeljevanje dokumentov, vdelavo in iskanje, tako da lahko ustvarite RAG aplikacije brez ročne konfiguracije posameznih korakov. - -## Predpogoji - -**Uporabljate razvojno posodo?** Java in Maven sta že nameščena. Potrebujete samo osebni dostopni žeton za GitHub. - -**Lokalni razvoj:** -- Java 21+, Maven 3.9+ -- Osebni žeton za dostop do GitHub (navodila spodaj) - -> **Opomba:** Ta modul uporablja `gpt-4.1-nano` iz GitHub Modelov. Ne spreminjajte imena modela v kodi - konfiguriran je za delo z razpoložljivimi GitHub modeli. - -## Nastavitev - -### 1. Pridobite svoj GitHub žeton - -1. Pojdite na [GitHub Nastavitve → Osebni dostopni žetoni](https://github.com/settings/personal-access-tokens) -2. Kliknite "Generate new token" -3. Nastavite opisno ime (npr. "LangChain4j Demo") -4. Nastavite veljavnost (priporočeno 7 dni) -5. Pod "Dovoljenja računa" poiščite "Models" in nastavite na "Samo za branje" -6. Kliknite "Generate token" -7. Kopirajte in shranite svoj žeton - ponovno ga ne boste videli - -### 2. Nastavite svoj žeton - -**Možnost 1: Uporaba VS Code (priporočeno)** - -Če uporabljate VS Code, dodajte svoj žeton v `.env` datoteko v korenu projekta: - -Če `.env` datoteka ne obstaja, kopirajte `.env.example` v `.env` ali ustvarite novo `.env` datoteko v korenu projekta. - -**Primer `.env` datoteke:** -```bash -# V /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Nato lahko preprosto kliknete z desno tipko miške na katerokoli datoteko z demonstracijo (npr. `BasicChatDemo.java`) v Explorerju in izberete **"Run Java"** ali uporabite zagonske konfiguracije iz plošče Run and Debug. - -**Možnost 2: Uporaba terminala** - -Nastavite žeton kot okoljsko spremenljivko: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Zagon primerov - -**Uporaba VS Code:** Preprosto kliknite z desno tipko na katerokoli datoteko z demonstracijo v Explorerju in izberite **"Run Java"** ali uporabite zagonske konfiguracije iz Run and Debug plošče (prepričajte se, da ste prej dodali svoj žeton v `.env` datoteko). - -**Uporaba Maven:** Alternativno lahko zaženete iz ukazne vrstice: - -### 1. Osnovni klepet - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Vzorci pozivov - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Prikazuje zero-shot, few-shot, chain-of-thought in role-based pozive. - -### 3. Klic funkcij - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI samodejno kliče vaše Java metode, ko je to potrebno. - -### 4. Vprašanja in odgovori o dokumentih (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Postavljajte vprašanja o vaših dokumentih z uporabo Easy RAG s samodejno vdelavo in iskanjem. - -### 5. Odgovorna AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Oglejte si, kako varnostni filtri AI blokirajo škodljivo vsebino. - -## Kaj posamezen primer prikazuje - -**Osnovni klepet** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Začnite tukaj, da vidite LangChain4j v najbolj osnovni obliki. Ustvarili boste `OpenAiOfficialChatModel`, poslali poziv z `.chat()` in prejeli odgovor kot niz. To prikazuje temelje: kako inicializirati modele s prilagojenimi končnimi točkami in API ključem. Ko razumete ta vzorec, se vse ostalo gradi na njem. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Poskusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odprite [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) in vprašajte: -> - "Kako bi v tej kodi preklopil z GitHub Modelov na Azure OpenAI?" -> - "Katere druge parametre lahko konfiguriram v OpenAiOfficialChatModel.builder()?" -> - "Kako dodam pretočne odgovore namesto, da čakam na celoten odgovor?" - -**Inženiring pozivov** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Zdaj, ko veste, kako govoriti z modelom, poglejmo, kaj mu rečete. Ta demo uporablja enako nastavitev modela, a prikazuje pet različnih vzorcev pozivov. Preizkusite zero-shot pozive za neposredna navodila, few-shot pozive, ki se učijo iz primerov, chain-of-thought pozive, ki razkrivajo korake razmišljanja, in role-based pozive, ki postavijo kontekst. Videli boste, kako enak model da drastično različne rezultate glede na to, kako oblikujete zahtevo. - -Demo tudi prikazuje predloge pozivov, ki so močan način za ustvarjanje ponovno uporabnih pozivov z uporabo spremenljivk. -Spodnji primer prikazuje poziv z uporabo LangChain4j `PromptTemplate` za izpolnitev spremenljivk. AI bo odgovoril na podlagi danega cilja in dejavnosti. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Poskusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odprite [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) in vprašajte: -> - "Kaj je razlika med zero-shot in few-shot pozivanjem in kdaj naj uporabim katero?" -> - "Kako parameter temperature vpliva na odgovore modela?" -> - "Katere tehnike obstajajo za preprečevanje napadov z vbrizgavanjem pozivov v produkciji?" -> - "Kako lahko ustvarim ponovno uporabne objekte PromptTemplate za pogoste vzorce?" - -**Integracija orodij** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Tu LangChain4j postane močan. Uporabili boste `AiServices` za ustvarjanje AI asistenta, ki lahko kliče vaše Java metode. Preprosto označite metode z `@Tool("opis")` in LangChain4j poskrbi za ostalo - AI sam odloča, kdaj uporabiti katero orodje glede na vprašanja uporabnika. To prikazuje klic funkcij, ključno tehniko za gradnjo AI, ki lahko izvaja dejanja, ne samo odgovarja na vprašanja. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Poskusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odprite [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) in vprašajte: -> - "Kako deluje oznaka @Tool in kaj LangChain4j počne z njo v ozadju?" -> - "Ali AI lahko kliče več orodij zaporedoma za reševanje zapletenih problemov?" -> - "Kaj se zgodi, če orodje vrže izjemo - kako naj upravljam napake?" -> - "Kako bi integriral pravi API namesto tega primera kalkulatorja?" - -**Vprašanja in odgovori o dokumentih (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Tukaj boste videli RAG (generiranje s podprtim iskanjem) z uporabo LangChain4jjevega pristopa "Easy RAG". Dokumenti se naložijo, samodejno razdelijo in vdelajo v pomnilniški shranjevalnik, nato pa vsebinsko iskanje zagotavlja relevantne dele AI ob času poizvedbe. AI odgovarja na podlagi vaših dokumentov, ne na splošnem znanju. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Poskusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odprite [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) in vprašajte: -> - "Kako RAG preprečuje AI halucinacije glede na uporabo učnih podatkov modela?" -> - "Kaj je razlika med tem enostavnim pristopom in lastno RAG verigo?" -> - "Kako bi to razširil za upravljanje več dokumentov ali večjih podatkovnih baz?" - -**Odgovorna AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Ustvarjajte varnost AI z večplastno obrambo. Ta demo prikazuje dve plasti zaščite, ki delujeta skupaj: - -**1. del: LangChain4j vnosne varovalke** - Blokirajo nevarne pozive, preden pridejo do LLM. Ustvarite lastne varovalke, ki preverjajo prepovedane ključne besede ali vzorce. Te se izvajajo v vaši kodi, zato so hitre in brezplačne. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**2. del: Varnostni filtri ponudnika** - GitHub modeli imajo vgrajene filtre, ki ujamejo tisto, kar bi vaše varovalke lahko spregledale. Videli boste surove blokade (napake HTTP 400) za hude kršitve in mehke zavrnitve, kjer AI vljudno zavrne. - -> **🤖 Poskusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odprite [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) in vprašajte: -> - "Kaj je InputGuardrail in kako ustvarim svojega?" -> - "Kaj je razlika med surovo blokado in mehko zavrnitvijo?" -> - "Zakaj uporabljati tako varovalke kot filtre ponudnika skupaj?" - -## Naslednji koraki - -**Naslednji modul:** [01-uvod - Začetek z LangChain4j](../01-introduction/README.md) - ---- - -**Navigacija:** [← Nazaj na glavno](../README.md) | [Naprej: Modul 01 - Uvod →](../01-introduction/README.md) - ---- - -## Reševanje težav - -### Prvič gradnja z Maven - -**Težava:** Začetni `mvn clean compile` ali `mvn package` traja dolgo (10-15 minut) - -**Vzrok:** Maven mora prvič prenesti vse odvisnosti projekta (Spring Boot, LangChain4j knjižnice, Azure SDK-je itd.). - -**Rešitev:** To je normalno vedenje. Naslednje gradnje bodo veliko hitrejše, saj se odvisnosti shranijo lokalno. Čas prenosa je odvisen od vaše hitrosti internetne povezave. - -### Sintaksa Maven ukaza v PowerShell - -**Težava:** Maven ukazi spodletijo z napako `Unknown lifecycle phase ".mainClass=..."` -**Vzrok**: PowerShell interpretira `=` kot operator dodeljevanja spremenljivke, kar prekine Maven sintakso lastnosti - -**Rešitev**: Pred Maven ukazom uporabite operator za ustavitev razčlenjevanja `--%`: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operator `--%` pove PowerShellu, da vse preostale argumente dobesedno posreduje Maven-u brez razlage. - -### Prikaz emojijev v Windows PowerShell - -**Težava**: Odgovori AI prikazujejo neberljive znake (npr. `????` ali `â??`) namesto emojijev v PowerShell-u - -**Vzrok**: Privzeta kodna tabela PowerShell-a ne podpira UTF-8 emojijev - -**Rešitev**: Pred zaganjanjem Java aplikacij zaženite ta ukaz: -```cmd -chcp 65001 -``` - -To prisili uporabo UTF-8 kodiranja v terminalu. Alternativno lahko uporabite Windows Terminal, ki ima boljšo podporo za Unicode. - -### Razhroščevanje klicev API-ja - -**Težava**: Napake pri preverjanju pristnosti, omejitve stopenj ali nepričakovani odzivi iz AI modela - -**Rešitev**: Primeri vključujejo `.logRequests(true)` in `.logResponses(true)`, da se prikažejo klici API v konzoli. To pomaga pri odpravljanju napak preverjanja pristnosti, omejitev stopenj ali nepričakovanih odzivov. V proizvodnji odstranite te zastavice, da zmanjšate število zapisov. - ---- - - -**Omejitev odgovornosti**: -Ta dokument je bil preveden z uporabo storitve za prevajanje z umetno inteligenco [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas opozarjamo, da lahko avtomatizirani prevodi vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku velja za avtoritativni vir. Za pomembne informacije priporočamo strokovni človeški prevod. Nismo odgovorni za morebitna nesporazumevanja ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. - \ No newline at end of file diff --git a/translations/sl/01-introduction/README.md b/translations/sl/01-introduction/README.md index 11ef54640..429d0a389 100644 --- a/translations/sl/01-introduction/README.md +++ b/translations/sl/01-introduction/README.md @@ -1,38 +1,38 @@ # Modul 01: Začetek z LangChain4j -## Kazalo vsebine +## Kazalo -- [Video predstavitev](../../../01-introduction) -- [Kaj se boste naučili](../../../01-introduction) -- [Predpogoji](../../../01-introduction) -- [Razumevanje osnovnega problema](../../../01-introduction) -- [Razumevanje tokenov](../../../01-introduction) -- [Kako deluje pomnilnik](../../../01-introduction) -- [Kako to uporablja LangChain4j](../../../01-introduction) -- [Implementacija infrastrukture Azure OpenAI](../../../01-introduction) -- [Zagon aplikacije lokalno](../../../01-introduction) -- [Uporaba aplikacije](../../../01-introduction) - - [Brezstaten klepet (levo okno)](../../../01-introduction) - - [Staten klepet (desno okno)](../../../01-introduction) -- [Naslednji koraki](../../../01-introduction) +- [Video vodnik](#video-vodnik) +- [Kaj se boste naučili](#kaj-se-boste-naucili) +- [Predpogoji](#predpogoji) +- [Razumevanje jedrnega problema](#razumevanje-jedrnega-problema) +- [Razumevanje žetonov](#razumevanje-zetonov) +- [Kako deluje pomnilnik](#kako-deluje-pomnilnik) +- [Kako to uporablja LangChain4j](#kako-to-uporablja-langchain4j) +- [Implementacija infrastrukture Azure OpenAI](#implementacija-infrastrukture-azure-openai) +- [Zagon aplikacije lokalno](#zagon-aplikacije-lokalno) +- [Uporaba aplikacije](#uporaba-aplikacije) + - [Nihran klepet (levi panel)](#nihran-klepet-leve-panel) + - [Stalni klepet (desni panel)](#stalni-klepet-desni-panel) +- [Naslednji koraki](#naslednji-koraki) -## Video predstavitev +## Video vodnik -Oglejte si to v živo posneto sejo, ki pojasnjuje, kako začeti z modulom: +Oglejte si to v živo predstavitev, ki razlaga, kako začeti s tem modulom: -Začetek z LangChain4j - V živo seja +Začetek z LangChain4j - Seansa v živo ## Kaj se boste naučili -V hitrem začetku ste uporabili GitHub modele za pošiljanje pozivov, klic orodij, zgradnjo RAG cevovoda in testiranje varovanih mehanizmov. Te predstavitve so pokazale, kaj je mogoče — zdaj preklopimo na Azure OpenAI in GPT-5.2 ter začnemo graditi aplikacije v produkcijskem slogu. Ta modul se osredotoča na pogovorno AI, ki si zapomni kontekst in ohranja stanje — koncepti, ki so jih uporabili hitri začetni primeri, a niso razloženi. +To je vaše izhodišče z LangChain4j in Azure OpenAI. Začnemo z osnovami in pričenjamo graditi aplikacije v produkcijskem slogu. Ta modul se osredotoča na pogovorno AI, ki si zapomni kontekst in ohranja stanje — temeljne koncepte, na katerih gradijo vsi kasnejši moduli. -V celotnem vodniku bomo uporabljali Azure OpenAI GPT-5.2, saj njegove napredne zmožnosti sklepanja naredijo vedenje različnih vzorcev jasneje vidno. Ko dodate pomnilnik, boste jasno videli razliko. To olajša razumevanje, kaj posamezna komponenta prinaša vaši aplikaciji. +V tem vodiču bomo uporabljali GPT-5.2 Azure OpenAI, saj njegove napredne sposobnosti razmišljanja omogočajo lažje razumevanje vedenja različnih vzorcev. Ko dodate pomnilnik, boste jasno videli razliko. To olajša razumevanje, kaj vsak komponenta prinaša vaši aplikaciji. -Zgradili boste eno aplikacijo, ki prikazuje oba vzorca: +Zgradili boste eno aplikacijo, ki ponazarja oba vzorca: -**Brezstaten klepet** – Vsak zahtevek je neodvisen. Model nima pomnilnika prejšnjih sporočil. To je vzorec, ki ste ga uporabili v hitrem začetku. +**Nihran klepet** – Vsak zahtevek je neodvisen. Model nima pomnilnika prejšnjih sporočil. To je najpreprostejše izhodišče. -**Staten pogovor** – Vsak zahtevek vključuje zgodovino pogovora. Model ohranja kontekst skozi več krogov. To je tisto, kar zahtevajo produkcijske aplikacije. +**Stalni pogovor** – Vsak zahtevek vključuje zgodovino pogovora. Model ohranja kontekst skozi več potez. To je tisto, kar zahtevajo produkcijske aplikacije. ## Predpogoji @@ -41,47 +41,47 @@ Zgradili boste eno aplikacijo, ki prikazuje oba vzorca: - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Opomba:** Java, Maven, Azure CLI in Azure Developer CLI (azd) so v predhodno nameščenem devcontainerju. +> **Opomba:** Java, Maven, Azure CLI in Azure Developer CLI (azd) so predhodno nameščeni v ponujenem devcontainer. -> **Opomba:** Ta modul uporablja GPT-5.2 na Azure OpenAI. Implementacija je samodejno konfigurirana preko `azd up` - ne spreminjajte imena modela v kodi. +> **Opomba:** Ta modul uporablja GPT-5.2 na Azure OpenAI. Implementacija je samodejno konfigurirana prek `azd up` - ne spreminjajte imena modela v kodi. -## Razumevanje osnovnega problema +## Razumevanje jedrnega problema -Jezikovni modeli so brezstatični. Vsak API klic je neodvisen. Če pošljete "Moje ime je John" in nato vprašate "Kako je moje ime?", model nima pojma, da ste se pravkar predstavili. Vsak zahtevek obravnava, kot da je prvi pogovor, ki ste ga kdaj imeli. +Jezikovni modeli so brezstanje. Vsak API klic je neodvisen. Če pošljete "Moje ime je John" in nato vprašate "Kako je moje ime?", model nima pojma, da ste se pravkar predstavili. Vsak zahtevek obravnava, kot da je prvi pogovor, ki ste ga kdaj imeli. -To je v redu za preprosta vprašanja in odgovore, a nepomembno za resne aplikacije. Pomočniki v storitvah za stranke morajo si zapomniti, kaj ste jim povedali. Osebni asistenti potrebujejo kontekst. Vsak večkrogovni pogovor zahteva pomnilnik. +To je primerno za preprosta vprašanja in odgovore, vendar neuporabno za resnične aplikacije. Bot-i za službo za stranke morajo vedeti, kaj ste jim povedali. Osebni asistenti potrebujejo kontekst. Vsak pogovor z več potezami zahteva pomnilnik. -Naslednja shema primerja oba pristopa — na levi brezstaten klic, ki pozabi vaše ime; na desni staten klic s ChatMemory, ki si ga zapomni. +Spodnja shema prikazuje razliko med obema pristopoma – na levi je brezstanje klic, ki pozabi vaše ime; na desni pa statičen klic, ki ga podpira ChatMemory in si ga zapomni. -Brezstatični proti statičnim pogovorom +Nihran proti stalnim pogovorom -*Razlika med brezstatičnimi (neodvisnimi klici) in statičnimi (zavedajočimi se konteksta) pogovori* +*Razlika med nihranim (neodvisnimi klici) in stalnim (kontekstno ozaveščenim) pogovorom* -## Razumevanje tokenov +## Razumevanje žetonov -Preden se poglobite v pogovore, je pomembno razumeti tokene – osnovne enote besedila, ki jih procesirajo jezikovni modeli: +Preden se poglobite v pogovore, je pomembno razumeti žetone – osnovne enote besedila, ki jih jezikovni modeli obdelujejo: -Razlaga tokenov +Razlaga žetonov -*Primer, kako se besedilo razdeli na tokene – "I love AI!" postane 4 ločene obdelovalne enote* +*Primer kako je besedilo razčlenjeno v žetone - "I love AI!" postane 4 ločene obdelovalne enote* -Tokeni so način, na katerega AI modeli merijo in obdelujejo besedilo. Besede, ločila in celo presledki so lahko tokeni. Vaš model ima omejitev koliko tokenov lahko obdela hkrati (400.000 za GPT-5.2, z do 272.000 vhodnimi in 128.000 izhodnimi tokeni). Razumevanje tokenov pomaga upravljati dolžino pogovora in stroške. +Žetoni so način, kako AI modeli merijo in obdelujejo besedilo. Besede, ločila in celo presledki so lahko žetoni. Vaš model ima omejitev, koliko žetonov lahko obdeluje naenkrat (400.000 za GPT-5.2, z do 272.000 vhodnimi žetoni in 128.000 izhodnimi žetoni). Razumevanje žetonov vam pomaga upravljati dolžino pogovora in stroške. ## Kako deluje pomnilnik -Pogovorni pomnilnik rešuje problem brezstatnosti tako, da ohranja zgodovino pogovorov. Preden pošljete zahtevek modelu, okvir doda ustrezna prejšnja sporočila. Ko vprašate "Kako je moje ime?", sistem dejansko pošlje celotno zgodovino pogovora, kar modelu omogoča, da vidi, da ste predhodno rekli "Moje ime je John." +Klepetalni pomnilnik rešuje brezstanje problem z ohranjanjem zgodovine pogovora. Preden pošljete zahtevo modelu, ogrodje doda relevantna prejšnja sporočila na začetek. Ko vprašate "Kako je moje ime?", sistem dejansko pošlje celotno zgodovino pogovora, kar modelu omogoča, da vidi, da ste prej rekli "Moje ime je John." -LangChain4j ponuja implementacije pomnilnika, ki to upravljajo samodejno. Izberete koliko sporočil shraniti, okvir pa upravlja okno konteksta. Spodnja shema prikazuje, kako MessageWindowChatMemory ohranja drseče okno nedavnih sporočil. +LangChain4j omogoča implementacije pomnilnika, ki to samodejno obravnavajo. Izberete, koliko sporočil želite obdržati, ogrodje pa upravlja s kontekstnim oknom. Spodnja shema prikazuje, kako MessageWindowChatMemory ohranja pomično okno nedavnih sporočil. Koncept pomnilniškega okna -*MessageWindowChatMemory ohranja drseče okno nedavnih sporočil in samodejno odstranjuje stare* +*MessageWindowChatMemory ohranja pomično okno nedavnih sporočil in samodejno odvrže starejša* ## Kako to uporablja LangChain4j -Ta modul nadgradi hiter začetek z integracijo Spring Boot in dodajanjem pomnilnika pogovora. Tako se deli povežejo: +Ta modul integrira Spring Boot in dodaja pomnilnik pogovorov. Tako se deli povezujejo: -**Odvisnosti** – Dodajte dve LangChain4j knjižnici: +**Odvisnosti** – Dodajte dve knjižnici LangChain4j: ```xml @@ -93,8 +93,8 @@ Ta modul nadgradi hiter začetek z integracijo Spring Boot in dodajanjem pomniln langchain4j-open-ai-official ``` - -**Klepetni model** – Konfigurirajte Azure OpenAI kot Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): + +**Klepetalni model** – Konfigurirajte Azure OpenAI kot Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -108,10 +108,10 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { .build(); } ``` + +Graditelj prebere poverilnice iz okolijskih spremenljivk, nastavljenih z `azd up`. Nastavitev `baseUrl` na vaš Azure končni točki omogoči, da OpenAI odjemalec deluje z Azure OpenAI. -Builder prebere poverilnice iz okoljskih spremenljivk, nastavljenih z `azd up`. Nastavitev `baseUrl` na vašo Azure točko konca omogoča delovanje OpenAI odjemalca z Azure OpenAI. - -**Pomnilnik pogovora** – Sledite zgodovini klepeta z MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Pomnilnik pogovorov** – Sledenje zgodovine klepeta z MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -123,15 +123,15 @@ memory.add(UserMessage.from("What's my name?")); AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` + +Pomnilnik ustvarite z `withMaxMessages(10)`, da obdržite zadnjih 10 sporočil. Dodajate sporočila uporabnika in AI s tipiziranimi ovoji: `UserMessage.from(text)` in `AiMessage.from(text)`. Zgodovino pridobite z `memory.messages()` in jo pošljete modelu. Storitev hrani ločene instance pomnilnika za vsak ID pogovora, kar omogoča, da lahko več uporabnikov hkrati klepeta. -Ustvarite pomnilnik z `withMaxMessages(10)` za hranjenje zadnjih 10 sporočil. Dodajte uporabniška in AI sporočila z ohišji tipa: `UserMessage.from(text)` in `AiMessage.from(text)`. Z zgodovino dostopajte z `memory.messages()` in jo pošljite modelu. Storitev hrani ločene instance pomnilnika za vsak ID pogovora, kar omogoča hkratno klepetanje več uporabnikov. - -> **🤖 Poskusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odprite [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) in vprašajte: -> - "Kako MessageWindowChatMemory odloči, katera sporočila bo odstranil, ko je okno polno?" -> - "Ali lahko implementiram lastno shrambo pomnilnika z uporabo baze podatkov namesto v pomnilniku?" -> - "Kako bi dodal povzetek za stiskanje stare zgodovine pogovora?" +> **🤖 Preizkusite s [GitHub Copilot](https://github.com/features/copilot) klepetom:** Odprite [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) in vprašajte: +> - "Kako MessageWindowChatMemory odloči, katera sporočila vrže, ko je okno polno?" +> - "Ali lahko implementiram prilagojeno shranjevanje pomnilnika z uporabo baze podatkov namesto pomnilnika v spominu?" +> - "Kako bi dodal povzemanje za stiskanje stare zgodovine pogovora?" -Brezstatični klepetni endpoint popolnoma preide preko pomnilnika - samo `chatModel.chat(prompt)` kot v hitrem začetku. Staten endpoint doda sporočila v pomnilnik, pridobi zgodovino in vključuje ta kontekst z vsako zahtevo. Enaka konfiguracija modela, različni vzorci. +Klepetalna točka brez pomnilnika popolnoma preskoči pomnilnik - samo `chatModel.chat(prompt)` kot pri hitrem zagonu. Statična točka dodaja sporočila v pomnilnik, pridobi zgodovino in skupaj z vsakim zahtevkom vključuje ta kontekst. Enaka konfiguracija modela, različni vzorci. ## Implementacija infrastrukture Azure OpenAI @@ -140,83 +140,83 @@ Brezstatični klepetni endpoint popolnoma preide preko pomnilnika - samo `chatMo cd 01-introduction azd up # Izberite naročnino in lokacijo (priporočeno eastus2) ``` - + **PowerShell:** ```powershell cd 01-introduction azd up # Izberite naročnino in lokacijo (priporočeno eastus2) ``` + +> **Opomba:** Če naletite na napako poteka časa (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), preprosto znova zaženite `azd up`. Azure viri se morda še vedno konfigurirajo v ozadju, ponovno poskus omogoči izvedbo implementacije, ko viri dosežejo končno stanje. -> **Opomba:** Če naletite na napako poteka časa (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), preprosto zaženite `azd up` znova. Azure viri so morda še vedno v postopku provisioniranja v ozadju, zato ponovni poskus omogoči dokončanje implementacije, ko viri dosežejo končno stanje. - -To bo: -1. Namestilo Azure OpenAI sredstvo z GPT-5.2 in modeli text-embedding-3-small -2. Samodejno ustvarilo `.env` datoteko v korenu projekta s poverilnicami -3. Nastavilo vse potrebne okoljske spremenljivke +To bo: +1. Implementiralo Azure OpenAI vir s GPT-5.2 in modeli text-embedding-3-small +2. Samodejno ustvarilo `.env` datoteko v korenu projekta s poverilnicami +3. Nastavilo vse zahtevane okoljske spremenljivke -**Imate težave z implementacijo?** Oglejte si [Infrastructure README](infra/README.md) za podrobno odpravljanje težav, vključno s konflikti imen poddomen, ročno implementacijo v Azure Portal in navodili za konfiguracijo modela. +**Imate težave z implementacijo?** Oglejte si [README infrastrukture](infra/README.md) za podrobna navodila za odpravljanje težav, vključno s konflikti imen poddomen, koraki ročne implementacije v Azure Portal in nasveti za konfiguracijo modela. -**Preverite uspešnost implementacije:** +**Preverite, ali je implementacija uspela:** **Bash:** ```bash -cat ../.env # Prikazati bi moral AZURE_OPENAI_ENDPOINT, API_KEY itd. +cat ../.env # Naj bi prikazoval AZURE_OPENAI_ENDPOINT, API_KEY itd. ``` - + **PowerShell:** ```powershell -Get-Content ..\.env # Naj prikaže AZURE_OPENAI_ENDPOINT, API_KEY, itd. +Get-Content ..\.env # Mora prikazati AZURE_OPENAI_ENDPOINT, API_KEY itd. ``` - -> **Opomba:** Ukaz `azd up` samodejno ustvari `.env` datoteko. Če jo želite kasneje posodobiti, jo lahko ročno uredite ali ponovno ustvarite z izvajanjem: + +> **Opomba:** Ukaz `azd up` samodejno ustvari `.env` datoteko. Če jo morate pozneje posodobiti, lahko datoteko ročno uredite ali jo znova ustvarite z zagonom: > > **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` -> +> > **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` - + ## Zagon aplikacije lokalno **Preverite implementacijo:** -Prepričajte se, da `.env` datoteka obstaja v korenski mapi z Azure poverilnicami. Zaženite to v mapi modula (`01-introduction/`): +Prepričajte se, da `.env` datoteka obstaja v korenski mapi z Azure poverilnicami. Zaženite iz mape modula (`01-introduction/`): **Bash:** ```bash -cat ../.env # Prikazati bi moral AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Naj prikazuje AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **PowerShell:** ```powershell -Get-Content ..\.env # Prikazati bi moralo AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Naj prikaže AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Zaženite aplikacije:** -**Možnost 1: Uporaba Spring Boot nadzorne plošče (priporočeno za uporabnike VS Code)** +**Opcija 1: Uporaba Spring Boot Dashborda (priporočeno za uporabnike VS Code)** -Dev container vključuje razširitev Spring Boot Dashboard, ki omogoča vizualni vmesnik za upravljanje vseh Spring Boot aplikacij. Najdete jo v Aktivnostni vrstici na levi strani VS Code (ikona Spring Boot). +Dev container vključuje razširitev Spring Boot Dashboard, ki nudi vizualno vmesnik za upravljanje vseh Spring Boot aplikacij. Nahaja se v vrstici dejavnosti na levi strani VS Code (poglejte za ikono Spring Boot). -Iz Spring Boot Dashboard lahko: -- Vidite vse razpoložljive Spring Boot aplikacije v delovnem prostoru -- Zaženete/ustavite aplikacije z enim klikom -- Ogledate dnevniške datoteke aplikacij v realnem času -- Spremljate stanje aplikacije +Iz Spring Boot Dashborda lahko: +- Vidite vse razpoložljive Spring Boot aplikacije v delovnem prostoru +- Zaženete/ustavite aplikacije z enim klikom +- Pregledate aplikacijske dnevnike v realnem času +- Spremljate stanje aplikacij -Preprosto kliknite gumb za predvajanje ob "introduction" za zagon tega modula ali zaženite vse module skupaj. +Preprosto kliknite gumb za predvajanje poleg "introduction" za začetek tega modula ali zaženite vse module hkrati. -Spring Boot nadzorna plošča +Spring Boot Dashboard -*Spring Boot nadzorna plošča v VS Code — začnite, ustavite in spremljajte vse module iz enega mesta* +*Spring Boot Dashboard v VS Code — začnite, ustavite in spremljajte vse module na enem mestu* -**Možnost 2: Uporaba shell skript** +**Opcija 2: Uporaba shell skript** Zaženite vse spletne aplikacije (moduli 01-04): @@ -225,86 +225,86 @@ Zaženite vse spletne aplikacije (moduli 01-04): cd .. # Iz korenskega imenika ./start-all.sh ``` - + **PowerShell:** ```powershell -cd .. # Iz korenskega imenika +cd .. # Iz korenske mape .\start-all.ps1 ``` - -Ali zaženite zgolj ta modul: + +Ali zaženite samo ta modul: **Bash:** ```bash cd 01-introduction ./start.sh ``` - + **PowerShell:** ```powershell cd 01-introduction .\start.ps1 ``` + +Obe skripti samodejno naložita okoljske spremenljivke iz korenske `.env` datoteke in bodo po potrebi sestavile JAR datoteke. -Obe skripti samodejno naložita okoljske spremenljivke iz korenske `.env` datoteke in zgradita JAR datoteke, če ne obstajajo. - -> **Opomba:** Če želite vse module ročno zgraditi pred zagonom: +> **Opomba:** Če želite pred zagonom ročno sestaviti vse module: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -Odprite http://localhost:8080 v vašem brskalniku. + +Odprite http://localhost:8080 v brskalniku. **Za ustavitev:** **Bash:** ```bash -./stop.sh # Ta modul samo +./stop.sh # Samo ta modul # Ali cd .. && ./stop-all.sh # Vsi moduli ``` - + **PowerShell:** ```powershell .\stop.ps1 # Samo ta modul # Ali cd ..; .\stop-all.ps1 # Vsi moduli ``` - + ## Uporaba aplikacije -Aplikacija zagotavlja spletni vmesnik z dvema klepetalnima implementacijama ena ob drugi. +Aplikacija nudi spletni vmesnik z dvema implementacijama klepeta ena ob drugi. -Glavni zaslon aplikacije +Domača stran aplikacije -*Nadzorna plošča prikazuje obe možnosti: Preprost klepet (brezstaten) in Pogovorni klepet (staten)* +*Nadzorna plošča prikazuje možnosti Enostaven klepet (brezstanje) in Pogovorni klepet (stalni)* -### Brezstaten klepet (levo okno) +### Nihran klepet (levi panel) -Preizkusite najprej to. Vprašajte "Moje ime je John" in nato takoj "Kako je moje ime?" Model se ne bo spomnil, ker sta sporočili neodvisni. To prikazuje osnovni problem integracije jezikovnega modela - ni konteksta pogovora. +Najprej preizkusite to. Vprašajte "Moje ime je John" in nato takoj vprašajte "Kako je moje ime?" Model si ne bo zapomnil, ker je vsako sporočilo neodvisno. To prikazuje osnovni problem integracije jezikovnih modelov - ni konteksta pogovora. -Demo brezstatnega klepeta +Demo nihran klepet -*AI se ne spomni vašega imena iz prejšnjega sporočila* +*AI si ne zapomni vašega imena iz prejšnjega sporočila* -### Staten klepet (desno okno) +### Stalni klepet (desni panel) -Zdaj poskusite isti postopek tukaj. Vprašajte "Moje ime je John" in nato "Kako je moje ime?" Tokrat se spomni. Razlika je MessageWindowChatMemory - ohranja zgodovino pogovora in jo vključuje v vsak zahtevek. Tako deluje produkcijska pogovorna AI. +Sedaj preizkusite isto zaporedje tukaj. Vprašajte "Moje ime je John" in nato "Kako je moje ime?" Tokrat si zapomni. Razlika je MessageWindowChatMemory – ohranja zgodovino pogovora in jo vključuje v vsak zahtevek. Tak deluje produkcijski pogovorni AI. -Demo statnega klepeta +Demo stalni klepet -*AI se spomni vašega imena iz večjega dela pogovora* +*AI si zapomni vaše ime iz prej v pogovoru* -Oba okna uporabljata isti GPT-5.2 model. Edina razlika je pomnilnik. To jasno pokaže, kaj pomnilnik prinaša vaši aplikaciji in zakaj je ključnega pomena za resnične primere uporabe. +Oba panela uporabljata isti GPT-5.2 model. Edina razlika je pomnilnik. To jasno pokaže, kaj pomnilnik prinaša vaši aplikaciji in zakaj je bistven za resnične primere. ## Naslednji koraki @@ -312,11 +312,11 @@ Oba okna uporabljata isti GPT-5.2 model. Edina razlika je pomnilnik. To jasno po --- -**Navigacija:** [← Prejšnji: Modul 00 - Hiter začetek](../00-quick-start/README.md) | [Nazaj na glavno](../README.md) | [Naprej: Modul 02 - Oblikovanje pozivov →](../02-prompt-engineering/README.md) +**Navigacija:** [← Nazaj na glavno](../README.md) | [Naprej: Modul 02 - Oblikovanje pozivov →](../02-prompt-engineering/README.md) --- **Omejitev odgovornosti**: -Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, upoštevajte, da lahko avtomatizirani prevodi vsebujejo napake ali netočnosti. Izvirni dokument v izvorni jeziku velja za avtoritativni vir. Za ključne informacije priporočamo strokovni človeški prevod. Nismo odgovorni za morebitne nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. +Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za kritične informacije je priporočljiv strokovni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. \ No newline at end of file diff --git a/translations/sl/02-prompt-engineering/README.md b/translations/sl/02-prompt-engineering/README.md index b521b4e31..46ff003af 100644 --- a/translations/sl/02-prompt-engineering/README.md +++ b/translations/sl/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ # Modul 02: Inženiring pozivov z GPT-5.2 -## Kazalo - -- [Video vodič](../../../02-prompt-engineering) -- [Kaj se boste naučili](../../../02-prompt-engineering) -- [Predpogoji](../../../02-prompt-engineering) -- [Razumevanje inženiringa pozivov](../../../02-prompt-engineering) -- [Osnove inženiringa pozivov](../../../02-prompt-engineering) - - [Zero-Shot pozivanje](../../../02-prompt-engineering) - - [Few-Shot pozivanje](../../../02-prompt-engineering) - - [Veriga misli](../../../02-prompt-engineering) - - [Pozivanje na podlagi vlog](../../../02-prompt-engineering) - - [Predloge pozivov](../../../02-prompt-engineering) -- [Napredni vzorci](../../../02-prompt-engineering) -- [Zaženite aplikacijo](../../../02-prompt-engineering) -- [Posnetki zaslona aplikacije](../../../02-prompt-engineering) -- [Raziskovanje vzorcev](../../../02-prompt-engineering) - - [Nizka proti visoki zavzetosti](../../../02-prompt-engineering) - - [Izvajanje nalog (uvodniki orodij)](../../../02-prompt-engineering) - - [Koda za samorefleksijo](../../../02-prompt-engineering) - - [Strukturirana analiza](../../../02-prompt-engineering) - - [Večokratni klepet](../../../02-prompt-engineering) - - [Razmišljanje korak za korakom](../../../02-prompt-engineering) - - [Omejen izhod](../../../02-prompt-engineering) -- [Kaj se resnično učite](../../../02-prompt-engineering) -- [Nadaljnji koraki](../../../02-prompt-engineering) - -## Video vodič - -Oglejte si to v živo predavanje, ki razlaga, kako začeti z modulom: - -Inženiring pozivov z LangChain4j - v živo +## Kazalo vsebine + +- [Video predstavitev](#video-predstavitev) +- [Kaj se boste naučili](#kaj-se-boste-naučili) +- [Predpogoji](#predpogoji) +- [Razumevanje inženiringa pozivov](#razumevanje-inženiringa-pozivov) +- [Temelji inženiringa pozivov](#temelji-inženiringa-pozivov) + - [Zero-Shot Pozivanje](#zero-shot-pozivanje) + - [Few-Shot Pozivanje](#few-shot-pozivanje) + - [Veriga misli](#veriga-misli) + - [Pozivanje z vlogo](#pozivanje-z-vlogo) + - [Predloge pozivov](#predloge-pozivov) +- [Napredni vzorci](#napredni-vzorci) +- [Zaženi aplikacijo](#zaženite-aplikacijo) +- [Posnetki zaslona aplikacije](#posnetki-zaslona-aplikacije) +- [Raziskovanje vzorcev](#raziščite-vzorce) + - [Nizka vs Visoka vnema](#nizka-vs-visoka-zagnanost) + - [Izvajanje nalog (Uvodni deli orodij)](#izvajanje-nalog-predpone-orodij) + - [Samoreflektirajoča koda](#samoreflektirajoča-koda) + - [Strukturirana analiza](#strukturirana-analiza) + - [Večkratni pogovori](#pogovor-s-več-koraki) + - [Korak za korakom razmišljanje](#razmišljanje-korak-za-korakom) + - [Omejen izhod](#omejen-izhod) +- [Kaj se resnično učite](#kaj-se-dejansko-učite) +- [Naslednji koraki](#naslednji-koraki) + +## Video predstavitev + +Oglejte si to v živo predavanje, ki pojasnjuje, kako začeti z modulom: + +Inženiring pozivov z LangChain4j - V živo ## Kaj se boste naučili -Naslednji diagram prikazuje pregled ključnih tem in veščin, ki jih boste razvili v tem modulu — od tehnik izboljševanja pozivov do korak za korakom poteka, ki ga boste sledili. +Naslednji diagram ponuja pregled ključnih tem in veščin, ki jih boste razvili v tem modulu — od tehnik izboljšanja pozivov do korak-po-korak delovnega procesa, ki ga boste sledili. Kaj se boste naučili -V prejšnjih modulih ste spoznali osnovne interakcije LangChain4j z modeli GitHub in videli, kako spomin omogoča konverzacijsko AI z Azure OpenAI. Zdaj se bomo osredotočili na to, kako postavljate vprašanja — torej same pozive — z uporabo GPT-5.2 Azure OpenAI. Način, kako strukturirate svoje pozive, drastično vpliva na kakovost prejetih odgovorov. Začnemo z pregledom osnovnih tehnik pozivanja, nato pa preidemo na osem naprednih vzorcev, ki v celoti izkoriščajo zmogljivosti GPT-5.2. +V prejšnjem modulu ste spoznali, kako pomnilnik omogoča pogovorni AI z Azure OpenAI. Zdaj se osredotočimo na to, kako zastavljate vprašanja — na same pozive — z uporabo GPT-5.2 v Azure OpenAI. Način, kako strukturirate pozive, bistveno vpliva na kakovost odgovorov, ki jih dobite. Začnemo s pregledom osnovnih tehnik pozivanja, nato pa preidemo k osmim naprednim vzorcem, ki v celoti izkoristijo zmogljivosti GPT-5.2. -Uporabljali bomo GPT-5.2, ker uvaja nadzor nad razmišljanjem — lahko modelu poveste, koliko razmišljanja naj opravi pred odgovorom. To naredi različne strategije pozivanja bolj opazne in pomaga razumeti, kdaj uporabiti kateri pristop. Prav tako bomo imeli koristi od manjših omejitev hitrosti v Azure za GPT-5.2 v primerjavi z modeli GitHub. +Uporabljali bomo GPT-5.2, ker uvaja nadzor razmišljanja - lahko modelu poveste, koliko naj razmišlja pred odgovorom. To različne strategije pozivanja naredi bolj izrazite in pomaga razumeti, kdaj katero uporabljati. ## Predpogoji -- Zaključen Modul 01 (nameščeni Azure OpenAI viri) -- `.env` datoteka v glavni mapi z Azure poverilnicami (ustvarjena z `azd up` v Modulu 01) +- Dokončan modul 01 (Azure OpenAI viri nameščeni) +- Datoteka `.env` v korenski mapi z Azure poverilnicami (ustvarjena z `azd up` v modulu 01) -> **Opomba:** Če niste zaključili Modula 01, najprej sledite tam navodilom za namestitev. +> **Opomba:** Če niste zaključili modula 01, najprej sledite navodilom za namestitev tam. ## Razumevanje inženiringa pozivov -V jedru je inženiring pozivov razlika med nejasnimi in natančnimi navodili, kot kaže spodnja primerjava. +V jedru je inženiring pozivov razlika med nejasnimi in natančnimi navodili, kot ponazarja spodnja primerjava. Kaj je inženiring pozivov? -Inženiring pozivov pomeni oblikovanje vhodnega besedila, ki vam dosledno prinese želene rezultate. Ne gre samo za postavljanje vprašanj — gre za strukturiranje zahtev, da model natančno razume, kaj želite in kako to zagotoviti. +Inženiring pozivov je oblikovanje vhodnega besedila, ki vam dosledno prinaša želene rezultate. Ne gre samo za postavljanje vprašanj - gre za strukturiranje zahtev, da model točno razume, kaj želite in kako to dostaviti. -Pomislite na to kot da dajete navodila sodelavcu. "Odpravi napako" je nejasno. "Odpravi izjemo na null pointer v UserService.java vrstica 45 z dodajanjem preverjanja na null" je specifično. Jezikovni modeli delujejo enako — pomembna sta natančnost in struktura. +Predstavljajte si, da dajete navodila sodelavcu. "Popravi napako" je nejasno. "Popravi izjemo z ničelnim kazalcem v UserService.java na vrstici 45 z dodajanjem preverjanja ničelnosti" je specifično. Jezikovni modeli delujejo enako - specifičnost in struktura štejeta. -Spodnji diagram prikazuje, kako LangChain4j ustreza tej sliki — povezuje vaše vzorce pozivov z modelom preko gradnikov SystemMessage in UserMessage. +Spodnji diagram prikazuje, kako se LangChain4j prilega tej sliki — povezuje vzorce pozivov z modelom preko gradnikov SystemMessage in UserMessage. -Kako LangChain4j ustreza +Kako LangChain4j se prilega -LangChain4j zagotavlja infrastrukturo — povezave do modelov, spomin in tipe sporočil — medtem ko so vzorci pozivov le skrbno strukturirano besedilo, ki ga pošljete skozi to infrastrukturo. Ključna gradnika sta `SystemMessage` (ki nastavi vedenje in vlogo AI) in `UserMessage` (ki nosi vašo dejansko zahtevo). +LangChain4j zagotavlja infrastrukturo — povezave z modeli, pomnilnik in vrste sporočil — medtem ko so vzorci pozivov le skrbno strukturirano besedilo, ki ga pošiljate prek te infrastrukture. Ključni gradniki so `SystemMessage` (ki določa vedenje in vlogo AI) in `UserMessage` (ki nosi vašo dejansko zahtevo). -## Osnove inženiringa pozivov +## Temelji inženiringa pozivov Pet osnovnih tehnik, prikazanih spodaj, tvori temelj učinkovitega inženiringa pozivov. Vsaka naslavlja drugačen vidik, kako komunicirate z jezikovnimi modeli. Pregled petih vzorcev inženiringa pozivov -Preden se poglobimo v napredne vzorce tega modula, si poglejmo pet temeljev tehnik pozivanja. To so gradniki, ki jih mora poznati vsak inženir pozivov. Če ste že delali skozi [Hitri začetek modul](../00-quick-start/README.md#2-prompt-patterns), ste jih že videli v akciji — tukaj je konceptualni okvir zanje. +Preden se poglobimo v napredne vzorce v tem modulu, ponovimo pet osnovnih tehnik pozivanja. To so gradniki, ki jih mora poznati vsak inženir pozivov. -### Zero-Shot pozivanje +### Zero-Shot Pozivanje -Najpreprostejši pristop: modelu daste neposredno navodilo brez primerov. Model se v celoti zanaša na svoje usposabljanje, da razume in izvede nalogo. To deluje dobro za preproste zahteve, kjer je pričakovano vedenje očitno. +Najpreprostejši pristop: modelu daste neposredno navodilo brez primerov. Model popolnoma uporablja svoje učenje, da razume in izvede nalogo. To deluje dobro za jasne zahteve, kjer je pričakovano vedenje očitno. -Zero-Shot pozivanje +Zero-Shot Pozivanje -*Neposredno navodilo brez primerov — model razbere nalogo samo iz navodila* +*Neposredno navodilo brez primerov — model izvede nalogo samo na podlagi navodila* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Odgovor: "Pozitivno" ``` -**Kdaj uporabiti:** Enostavne klasifikacije, neposredna vprašanja, prevodi ali katerakoli naloga, ki jo model lahko izvede brez dodatnih navodil. +**Kdaj uporabiti:** Preproste klasifikacije, neposredna vprašanja, prevodi ali katerakoli naloga, ki jo model lahko izvede brez dodatnih smernic. -### Few-Shot pozivanje +### Few-Shot Pozivanje -Podajte primere, ki pokažejo vzorec, ki ga želite, da model sledi. Model se iz vaših primerov nauči pričakovanega vhodno-izhodnega formata in ga uporabi na novih vhodih. To močno izboljša doslednost za naloge, kjer želeni format ali vedenje ni očitno. +Navedete primere, ki pokažejo vzorec, ki ga želite, da se model drži. Model se nauči pričakovani vhodno-izhodni format iz vaših primerov in ga uporablja na novih vhodih. To močno izboljša doslednost za naloge, kjer format ali vedenje ni očiten. -Few-Shot pozivanje +Few-Shot Pozivanje -*Učenje iz primerov — model prepozna vzorec in ga uporabi na novih vhodih* +*Učenje iz primerov — model prepozna vzorec in ga uporablja na novih vhodih* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kdaj uporabiti:** Prilagojene klasifikacije, dosledno oblikovanje, naloge specifične za domeno ali kadar so rezultati zero-shot neenotni. +**Kdaj uporabiti:** Prilagojene klasifikacije, dosledno oblikovanje, naloge specifične za domeno ali kadar so rezultati zero-shot nedosledni. ### Veriga misli -Model prosite, naj pokaže svoje razmišljanje korak za korakom. Namesto da skoči neposredno do odgovora, model razgradi problem in razločno obdela vsak del. To izboljša natančnost pri matematičnih, logičnih in večstopenjskih nalogah. +Modelu naročite, naj pokaže svoje razmišljanje korak za korakom. Namesto da bi skočil neposredno na odgovor, model razdeli problem in dela skozi vsak del posebej. To izboljša natančnost pri matematičnih, logičnih in večkorakih razmišljanjih. Veriga misli pozivanja -*Razmišljanje korak za korakom — razbijanje kompleksnih problemov v eksplicitne logične korake* +*Korak za korakom razmišljanje — razbijanje kompleksnih problemov v eksplicitne logične korake* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Model prikazuje: 15 - 8 = 7, nato 7 + 12 = 19 jabolk ``` -**Kdaj uporabiti:** Matematične težave, logične uganke, odpravljanje napak ali katera koli naloga, kjer prikaz procesa razmišljanja izboljša natančnost in zaupanje. +**Kdaj uporabiti:** Matematični problemi, logične uganke, odpravljanje napak ali katera koli naloga, kjer prikaz razmišljanja izboljša natančnost in zaupanje. -### Pozivanje na podlagi vlog +### Pozivanje z vlogo -Nastavite persono ali vlogo za AI pred postavitvijo vprašanja. To daje kontekst, ki oblikuje ton, globino in fokus odgovora. "Programski arhitekt" daje drugačne nasvete kot "mlajši razvijalec" ali "varnostni revizor". +Določite osebo ali vlogo za AI pred zastavitvijo vprašanja. To zagotovi kontekst, ki oblikuje ton, globino in fokus odgovora. "Programsko arhitekt" daje drugačen nasvet kot "mlajši razvijalec" ali "varnostni revizor". -Pozivanje na podlagi vlog +Pozivanje z vlogo -*Nastavljanje konteksta in persone — isto vprašanje dobi različne odgovore glede na dodeljeno vlogo* +*Določanje konteksta in osebnosti — isto vprašanje dobi drugačen odgovor glede na dodeljeno vlogo* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kdaj uporabiti:** Pregledi kode, poučevanje, domeno specifične analize ali kadar potrebujete odgovore prilagojene določeni ravni strokovnosti ali perspektivi. +**Kdaj uporabiti:** Pregledi kode, mentorstvo, analize specifične za domeno ali kadar potrebujete odgovore, prilagojene določenemu strokovnemu nivoju ali perspektivi. ### Predloge pozivov -Ustvarite ponovno uporabne pozive s spremenljivkami kot držali. Namesto da vsakokrat pišete nov poziv, definirajte predlogo enkrat in napolnite različne vrednosti. Razred `PromptTemplate` v LangChain4j to olajša s sintakso `{{variable}}`. +Ustvarite ponovno uporabne pozive z vloženimi spremenljivkami. Namesto da bi vsakič pisali nov poziv, definirajte predlogo enkrat in vstavite različne vrednosti. Razred `PromptTemplate` v LangChain4j to olajša z `{{variable}}` sintakso. Predloge pozivov -*Ponovno uporabni pozivi s spremenljivkami kot držali — ena predloga, več uporab* +*Ponovno uporabni pozivi z vloženimi spremenljivkami — ena predloga, veliko uporab* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Kdaj uporabiti:** Ponavljane poizvedbe z različnimi vhodi, paketno obdelavo, gradnjo ponovno uporabnih AI potekov dela ali kakršen koli scenarij, kjer struktura poziva ostaja enaka, podatki pa se spreminjajo. +**Kdaj uporabiti:** Ponovljene poizvedbe z različnimi vhodi, serijska obdelava, gradnja ponovno uporabnih AI delovnih tokov ali v vsakem primeru, ko struktura poziva ostane enaka, a se podatki spreminjajo. --- -Te pet osnovnih tehnik vam daje trden komplet orodij za večino nalog pozivanja. Preostanek tega modula gradi na njih s **osmimi naprednimi vzorci**, ki uporabljajo nadzor nad razmišljanjem GPT-5.2, samoocenjevanje in zmogljivosti strukturiranega izhoda. +Ti pet osnovnih tehnik vam daje solidno orodje za večino pozivnih nalog. Preostali del tega modula gradi na njih z **osmimi naprednimi vzorci**, ki izkoriščajo nadzor razmišljanja GPT-5.2, samoocenjevanje in zmožnosti strukturiranega izhoda. ## Napredni vzorci -Ko smo pokrili osnove, preidimo k osmim naprednim vzorcem, ki naredijo ta modul unikaten. Ne vsi problemi zahtevajo enak pristop. Nekatera vprašanja potrebujejo hitre odgovore, druga globoko razmišljanje. Nekatera potrebujejo vidno razmišljanje, druga samo rezultate. Vsak vzorec spodaj je optimiziran za drugačen scenarij — in nadzor razmišljanja GPT-5.2 naredi razlike še bolj izrazite. +Ko so osnovne tehnike pokrite, preidimo na osem naprednih vzorcev, ki ta modul naredijo edinstven. Vsi problemi ne potrebujejo istega pristopa. Nekatera vprašanja zahtevajo hitre odgovore, druga globoko razmišljanje. Nekatera vidno razmišljanje, druga samo rezultate. Vsak spodnji vzorec je optimiziran za drugačen scenarij — nadzor razmišljanja GPT-5.2 pa te razlike še poudari. Osem vzorcev pozivanja -*Pregled osmih vzorcev inženiringa pozivov in njihovi primeri uporabe* +*Pregled osmih vzorcev inženiringa pozivov in njihovih primerov uporabe* -GPT-5.2 dodaja še eno dimenzijo tem vzorcem: *nadzor razmišljanja*. Drsnik spodaj prikazuje, kako lahko prilagodite trud razmišljanja modela — od hitrih neposrednih odgovorov do globoke, temeljite analize. +GPT-5.2 dodaja še eno dimenzijo tem vzorcem: *nadzor razmišljanja*. Spodnji drsnik prikazuje, kako lahko prilagajate modelovo razmišljanje — od hitrih, neposrednih odgovorov do globoke, temeljite analize. Nadzor razmišljanja z GPT-5.2 -*Nadzor razmišljanja GPT-5.2 omogoča, da določite, koliko razmišljanja mora model opraviti — od hitrih neposrednih odgovorov do globokega raziskovanja* +*Nadzor razmišljanja GPT-5.2 vam omogoča določiti, koliko naj model razmišlja — od hitrih, neposrednih odgovorov do poglobljenega raziskovanja* -**Nizka zavzetost (hitro in osredotočeno)** - Za enostavna vprašanja, kjer želite hitre, neposredne odgovore. Model opravi minimalno razmišljanje - največ 2 koraka. Uporabite to za izračune, poizvedbe ali neposredna vprašanja. +**Nizka vnema (Hitro in osredotočeno)** - Za preprosta vprašanja, kjer želite hitre, neposredne odgovore. Model razmišlja minimalno - največ 2 koraka. Uporabite to za izračune, poizvedbe ali preprosta vprašanja. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Raziskujte z GitHub Copilot:** Odprite [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) in vprašajte: -> - "Kakšna je razlika med nizko in visoko zavzetostjo vzorcev pozivanja?" -> - "Kako XML oznake v pozivih pomagajo strukturirati AI odgovor?" -> - "Kdaj naj uporabim vzorce za samorefleksijo in kdaj neposredna navodila?" +> - "Kakšna je razlika med nizko in visoko vneto strategijo pozivanja?" +> - "Kako XML oznake v pozivih pomagajo strukturirati odgovor AI?" +> - "Kdaj uporabiti vzorce samorefleksije v primerjavi z neposrednimi navodili?" -**Visoka zavzetost (globoko in temeljito)** - Za kompleksne probleme, kjer želite podrobno analizo. Model tukaj temeljito raziskuje in pokaže podrobno razmišljanje. Uporabite to za sistemske načrte, odločitve o arhitekturi ali kompleksne raziskave. +**Visoka vnema (Globoko in temeljito)** - Za kompleksne probleme, kjer želite celovito analizo. Model temeljito raziskuje in pokaže podrobno razmišljanje. Uporabite to za sistemsko oblikovanje, arhitekturne odločitve ali kompleksne raziskave. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Izvajanje nalog (napredek korak za korakom)** - Za večstopenjske poteke dela. Model posreduje načrt vnaprej, opisuje vsak korak med delom in nato poda povzetek. Uporabite to za migracije, implementacije ali katerikoli večstopenjski proces. +**Izvajanje nalog (Napredek korak za korakom)** - Za večkorakne delovne tokove. Model najprej poda načrt, nato pripoveduje vsak korak med delom in na koncu poda povzetek. Uporabite to za migracije, implementacije ali katerikoli večkorakni proces. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Veriga misli pozivanje izrecno zahteva od modela, da pokaže svoj proces razmišljanja, kar izboljšuje natančnost pri zahtevnih nalogah. Razčlenitev korak za korakom pomaga tako ljudem kot AI razumeti logiko. +Pozivanje z Verigo misli modelu eksplicitno naroči, naj prikaže svojo procesno logiko, kar izboljša natančnost pri kompleksnih nalogah. Razčlenitev korak za korakom pomaga tako ljudem kot AI razumeti logiko. -> **🤖 Preizkusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Vprašajte o tem vzorcu: -> - "Kako bi prilagodil vzorec izvajanja nalog za dolgo trajajoče operacije?" -> - "Kakšne so najboljše prakse za strukturiranje uvodnikov orodij v produkcijskih aplikacijah?" -> - "Kako lahko zajamem in prikažem posredne posodobitve napredka v uporabniškem vmesniku?" +> **🤖 Poskusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Vprašajte o tem vzorcu: +> - "Kako bi prilagodil vzorec izvajanja nalog za dolgotrajne operacije?" +> - "Kakšne so najboljše prakse za strukturiranje uvodnih delov orodij v produkcijskih aplikacijah?" +> - "Kako lahko ujamem in prikažem vmesne posodobitve napredka v uporabniškem vmesniku?" -Spodnji diagram ponazarja ta potek dela Načrtuj → Izvedi → Povzemi. +Spodnji diagram prikazuje ta načrt → izvedbo → povzetek delovnega procesa. -Vzorčni potek izvajanja nalog +Vzorec izvajanja nalog -*Načrtuj → Izvedi → Povzemi potek dela za večstopenjske naloge* +*Načrt → Izvedba → Povzetek delovnega procesa za večkorakne naloge* -**Koda za samorefleksijo** - Za generiranje kode produkcijske kakovosti. Model generira kodo po produkcijskih standardih z ustreznim upravljanjem napak. Uporabite to pri gradnji novih funkcionalnosti ali storitev. +**Samoreflektirajoča koda** - Za generiranje kode kakovosti za produkcijo. Model generira kodo, ki sledi produkcijskim standardom z ustreznim ravnanjem z napakami. Uporabite, ko gradite nove funkcionalnosti ali storitve. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Spodnji diagram prikazuje ta iterativni zanko izboljševanja — generiraj, oceni, prepoznaj slabosti in izboljšaj, dokler koda ne doseže produkcijskih standardov. +Spodnji diagram prikazuje ta iterativni zanki izboljšav — generiraj, ocenjuj, ugotovi pomanjkljivosti in izpopolnjuj, dokler koda ne doseže produkcijskih standardov. Cikel samorefleksije -*Iterativna zanka izboljševanja - generiraj, oceni, prepoznaj težave, izboljšaj, ponovi* +*Iterativni cikel izboljšav - generiranje, ocenjevanje, odkrivanje težav, izboljšave, ponavljanje* -**Strukturirana analiza** - Za dosledno ocenjevanje. Model pregleda kodo z uporabo fiksnega okvira (pravilnost, prakse, zmogljivost, varnost, vzdržljivost). Uporabite to za preglede kode ali ocene kakovosti. +**Strukturirana analiza** - Za dosledno ocenjevanje. Model pregleda kodo z uporabo fiksiranega okvira (pravilnost, praksa, zmogljivost, varnost, vzdržnost). Uporabite za preglede kode ali ocene kakovosti. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Preizkusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Vprašajte o strukturirani analizi: +> **🤖 Poskusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Vprašajte o strukturirani analizi: > - "Kako lahko prilagodim analitični okvir za različne vrste pregledov kode?" -> - "Kateri je najboljši način za programatično razčlenjevanje in ukrepanje na strukturiran izhod?" -> - "Kako zagotovim dosledne nivoje resnosti skozi različne seje pregledov?" +> - "Kakšen je najboljši način za programatično razčlenjevanje in ukrepanje na strukturiran izhod?" +> - "Kako zagotoviti doslednost ravni resnosti med različnimi pregledi?" -Spodnji diagram prikazuje, kako ta strukturirani okvir organizira pregled kode v dosledne kategorije z nivoji resnosti. +Naslednji diagram prikazuje, kako ta strukturirani okvir organizira pregled kode v dosledne kategorije z ravnmi resnosti. -Vzorčni okvir strukturirane analize +Vzorec strukturirane analize -*Okvir za dosledne preglede kode z nivoji resnosti* +*Okvir za dosledne preglede kode z ravnmi resnosti* -**Večkratni klepet** - Za pogovore, ki potrebujejo kontekst. Model si zapomni prejšnja sporočila in gradi nanje. Uporabite to za interaktivne podporne seje ali kompleksna vprašanja in odgovore. +**Večkratni pogovori** - Za pogovore, ki potrebujejo kontekst. Model si zapomni pretekla sporočila in gradi nanje. Uporabite za interaktivne pomoči ali kompleksna vprašanja in odgovore. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Spodnji diagram ponazarja, kako se kontekst pogovora kopiči z vsakim krogom in kako se to nanaša na omejitev modelovih tokenov. +Spodnji diagram prikazuje, kako se kontekst pogovora kopiči z vsakim krogom in kako je povezan z omejitvijo tokenov modela. -Spomin konteksta +Pomnilnik konteksta *Kako se kontekst pogovora kopiči skozi več krogov do dosega omejitve tokenov* -**Korak za korakom razmišljanje** - Za probleme, ki zahtevajo vidno logiko. Model pokaže eksplicitno razmišljanje za vsak korak. Uporabite to za matematične probleme, logične uganke ali ko morate razumeti proces razmišljanja. + +**Korak za korakom razmišljanje** - Za probleme, ki zahtevajo vidno logiko. Model pokaže eksplicitno razmišljanje za vsak korak. Uporabite za matematične probleme, logične uganke ali kadar želite razumeti proces razmišljanja. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagram spodaj prikazuje, kako model razdeli probleme na eksplicitne, številčene logične korake. - -Korak za korakom vzorec +Spodnji diagram prikazuje, kako model razdeli probleme v eksplicitne, oštevilčene logične korake. -*Razčlenjevanje problemov na eksplicitne logične korake* +Vzorec korak za korakom +*Razčlenjevanje problemov v izrecne logične korake* -**Omejen izhod** - Za odzive s posebnimi zahtevami za format. Model strogo upošteva pravila za format in dolžino. Uporabite to za povzetke ali ko potrebujete natančno strukturo izhoda. +**Omejen izhod** – Za odgovore z zahtevami glede posebne oblike. Model strogo upošteva pravila oblikovanja in dolžine. Uporabite to za povzetke ali ko potrebujete natančno strukturo izhoda. ```java String prompt = """ @@ -420,55 +420,55 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Naslednji diagram kaže, kako omejitve usmerjajo model, da ustvari izhod, ki strogo sledi vašim zahtevam glede formata in dolžine. +Naslednji diagram prikazuje, kako omejitve usmerjajo model k ustvarjanju izhoda, ki strogo upošteva vaše zahteve glede oblike in dolžine. Vzorec omejenega izhoda -*Uveljavljanje specifičnih zahtev za format, dolžino in strukturo* +*Uveljavljanje zahtev glede oblike, dolžine in strukture* -## Zagon aplikacije +## Zaženite aplikacijo -**Preverite namestitev:** +**Potrdite namestitev:** -Poskrbite, da datoteka `.env` obstaja v korenski mapi z Azure poverilnicami (ustvarjena v Modul 01). Zaženite to iz mape modula (`02-prompt-engineering/`): +Preverite, da je datoteka `.env` prisotna v korenski mapi z Azure poverilnicami (ustvarjeno med Modulom 01). Zaženite to iz mape modula (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Naj pokaže AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Mora prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Prikazati bi moralo AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Prikaže mora AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Začnite aplikacijo:** +**Zaženite aplikacijo:** -> **Opomba:** Če ste že zagnali vse aplikacije z `./start-all.sh` iz korenske mape (kot je opisano v Modul 01), ta modul že teče na portu 8083. Lahko preskočite ukaze za začetek spodaj in pojdite neposredno na http://localhost:8083. +> **Opomba:** Če ste že zaženili vse aplikacije z ukazom `./start-all.sh` iz korenske mape (kot opisano v Modulu 01), ta modul že teče na vratih 8083. Zaženete lahko neposredno, brez ukazov spodaj, na naslovu http://localhost:8083. -**Možnost 1: Uporaba Spring Boot Dashboard (Priporočeno za uporabnike VS Code)** +**Možnost 1: Uporaba nadzorne plošče Spring Boot (priporočeno za uporabnike VS Code)** -Razvojno okolje vsebuje razširitev Spring Boot Dashboard, ki omogoča vizualni vmesnik za upravljanje vseh Spring Boot aplikacij. Najdete jo v vrstici z aktivnostmi na levi strani VS Code (poiščite ikono Spring Boot). +Razvojno okolje vsebuje razširitev Spring Boot Dashboard, ki omogoča vizualno upravljanje vseh Spring Boot aplikacij. Najdete jo v vrstici aktivnosti na levi strani VS Code (ikona Spring Boot). -Iz Spring Boot Dashboarda lahko: +Iz Spring Boot Dashboard lahko: - Vidite vse razpoložljive Spring Boot aplikacije v delovnem prostoru - Zaženete/ustavite aplikacije z enim klikom - V živo spremljate dnevnike aplikacij - Nadzorujete stanje aplikacij -Preprosto kliknite gumb za predvajanje zraven "prompt-engineering", da zaženete ta modul, ali zaženite vse module naenkrat. +Preprosto kliknite gumb za predvajanje ob "prompt-engineering" za zagon tega modula ali začnite vse module hkrati. -Spring Boot nadzorna plošča +Nadzorna plošča Spring Boot -*Spring Boot Dashboard v VS Code — začni, ustavi in nadziraj vse module na enem mestu* +*Nadzorna plošča Spring Boot v VS Code — zaženite, ustavite in spremljajte vse module iz enega mesta* -**Možnost 2: Uporaba shell skript** +**Možnost 2: Uporaba skript v lupini** -Zaženite vse spletne aplikacije (moduli 01-04): +Zaženi vse spletne aplikacije (moduli 01-04): **Bash:** ```bash -cd .. # Iz korenskega imenika +cd .. # Iz korenske mape ./start-all.sh ``` @@ -478,7 +478,7 @@ cd .. # Iz korenske mape .\start-all.ps1 ``` -Ali zaženite samo ta modul: +Ali zaženi samo ta modul: **Bash:** ```bash @@ -492,16 +492,16 @@ cd 02-prompt-engineering .\start.ps1 ``` -Obe skripti samodejno naložita okoljske spremenljivke iz korenske datoteke `.env` in ustvarita JAR datoteke, če še ne obstajajo. +Obe skripti samodejno naložita okoljske spremenljivke iz korenske datoteke `.env` in ob potrebi sestavita JAR datoteke. -> **Opomba:** Če želite zgraditi vse module ročno pred zagonom: +> **Opomba:** Če želite pred zagonom ročno sestaviti vse module: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -510,7 +510,7 @@ Obe skripti samodejno naložita okoljske spremenljivke iz korenske datoteke `.en Odprite http://localhost:8083 v vašem brskalniku. -**Za ustavitev:** +**Zaustavitev:** **Bash:** ```bash @@ -528,81 +528,81 @@ cd ..; .\stop-all.ps1 # Vsi moduli ## Posnetki zaslona aplikacije -Tukaj je glavni vmesnik modula za prompt engineering, kjer lahko poskusite vseh osem vzorcev drug ob drugem. +Tu je glavni vmesnik modula za prompt engineering, kjer lahko poskusite vseh osem vzorcev drug ob drugem. -Glavna stran nadzorne plošče +Glavna nadzorna plošča -*Glavna nadzorna plošča z vsemi 8 vzorci za prompt engineering z njihovimi značilnostmi in primeri uporabe* +*Glavna nadzorna plošča prikazuje vseh 8 vzorcev prompt engineeringa z njihovimi značilnostmi in primeri uporabe* -## Raziskovanje vzorcev +## Raziščite vzorce -Spletni vmesnik vam omogoča, da eksperimentirate z različnimi strategijami pozivanja. Vsak vzorec rešuje različne težave – preizkusite jih, da vidite, kdaj kateri pristop najbolje deluje. +Spletni vmesnik omogoča eksperimentiranje z različnimi strategijami spodbujanja. Vsak vzorec rešuje različne probleme – preizkusite jih in ugotovite, kdaj kateri pristop najbolje deluje. -> **Opomba: Tokovno proti netokovnemu** — Vsaka stran vzorca ponuja dva gumba: **🔴 Tokovni odgovor (v živo)** in možnost **Netokovno**. Tokovno uporablja Server-Sent Events (SSE), da v realnem času prikazuje tokene, ko jih model ustvarja, tako da napredek takoj vidite. Netokovna možnost počaka, da se celoten odgovor ustvari, preden ga prikaže. Za pozive, ki sprožijo globoko razmišljanje (npr. High Eagerness, Self-Reflecting Code), netokovni klic lahko traja zelo dolgo – tudi minute – brez vidne povratne informacije. **Pri eksperimentiranju s kompleksnimi pozivi uporabljajte tokovno,** da boste lahko videli model v akciji in se izognili vtisu, da je zahteva potekla. +> **Opomba: Pretakanje vs Ne-pretakanje** — Vsaka stran vzorca ponuja dva gumba: **🔴 Pretakanje odgovora (v živo)** in nepretakalno možnost. Pretakanje uporablja Server-Sent Events (SSE) za prikazovanje tokenov v realnem času med generiranjem, da takoj vidite napredek. Nepretakalna možnost čaka na celoten odgovor pred prikazom. Pri pozivih, ki sprožijo globoko razmišljanje (npr. Visoka zagnanost, Samoreflektirajoča koda), lahko nepretakanje traja zelo dolgo – tudi minute – brez vidnih povratnih informacij. **Uporabljajte pretakanje pri eksperimentih z zahtevnimi pozivi**, da vidite model v delovanju in preprečite vtis, da je zahteva potekla. > -> **Opomba: Zahteve brskalnika** — Tokovna funkcija uporablja Fetch Streams API (`response.body.getReader()`), ki zahteva poln brskalnik (Chrome, Edge, Firefox, Safari). Ne deluje v vgrajenem preprostem brskalniku VS Code, saj njegova spletna ogledala ne podpirajo ReadableStream API. Če uporabljate Simple Browser, bodo netokovni gumbi še vedno delovali normalno – samo tokovni so vplivani. Odprite `http://localhost:8083` v zunanjem brskalniku za polno izkušnjo. +> **Opomba: Zahteva brskalnika** — Funkcija pretakanja uporablja Fetch Streams API (`response.body.getReader()`), ki zahteva poln brskalnik (Chrome, Edge, Firefox, Safari). Vgrajeni preprost brskalnik v VS Code ne podpira ReadableStream API, zato tam ne deluje. V preprostem brskalniku bodo nepretakalni gumbi delovali normalno, samodejno pa bodo pretakalni neuporabni. Za polno izkušnjo odprite `http://localhost:8083` v zunanjem brskalniku. -### Nizka proti visoki zavzetosti +### Nizka vs Visoka zagnanost -Postavite preprosto vprašanje, kot je "Koliko je 15 % od 200?" z nizko zavzetostjo. Dobite takojšen, neposreden odgovor. Zdaj postavite nekaj zahtevnejšega, na primer "Oblikuj strategijo predpomnjenja za API z veliko obremenitvijo" z visoko zavzetostjo. Kliknite **🔴 Tokovni odgovor (v živo)** in opazujte podrobno razmišljanje modela, ki se prikaže token za tokenom. Enak model, enaka struktura vprašanja – a poziv mu pove, koliko razmišljanja mora vložiti. +Postavite preprosto vprašanje, na primer "Koliko je 15 % od 200?" z nizko zagnanostjo. Pridobili boste takojšen, neposreden odgovor. Zdaj vprašajte nekaj zahtevnega, na primer "Oblikuj strategijo predpomnjenja za visoko-obremenjen API", z visoko zagnanostjo. Kliknite **🔴 Pretakanje odgovora (v živo)** in opazujte podroben razmislek modela, prikazan token za tokenom. Enak model, ista struktura vprašanja – vendar prompt določa količino razmišljanja. -### Izvajanje naloge (orodna uvodna sporočila) +### Izvajanje nalog (predpone orodij) -Večstopenjski delovni procesi imajo koristi od načrtovanja vnaprej in pripovedovanja o napredku. Model predstavi, kaj bo naredil, predstavi vsak korak in nato povzame rezultate. +Večstopenjski delovni tokovi imajo koristi od načrtovanja in pripovedovanja napredka. Model orisuje, kaj bo naredil, po korakih pripoveduje, nato povzame rezultate. ### Samoreflektirajoča koda -Poskusite "Ustvari storitev za preverjanje e-pošte". Namesto, da bi samo generiral kodo in se ustavil, model ustvari, ovrednoti glede na merila kakovosti, opredeli slabosti in izboljšuje. Videli boste, kako iterira, dokler koda ne doseže proizvodnih standardov. +Poskusite "Ustvari storitev za preverjanje e-poštnih naslovov". Namesto da bi samo generiral kodo in nehal, model generira, ocenjuje glede kriterijev kakovosti, prepozna slabosti in izboljšuje. Videli boste iteracije, dokler koda ne doseže proizvodnih standardov. ### Strukturirana analiza -Pregledi kode potrebujejo konzistentne ocenjevalne okvire. Model analizira kodo z uporabo fiksnih kategorij (pravilnost, prakse, zmogljivost, varnost) z različnimi stopnjami resnosti. +Pregledi kode potrebujejo dosledne kriterije ocenjevanja. Model analizira kodo skozi fiksne kategorije (pravilenost, prakse, zmogljivost, varnost) z različnimi stopnjami resnosti. -### Večkratni klepet +### Pogovor s več koraki -Vprašajte "Kaj je Spring Boot?" nato takoj nadaljujte z "Pokaži mi primer". Model se spomni vašega prvega vprašanja in vam posebej poda primer Spring Boot. Brez spomina bi bilo drugo vprašanje preveč nejasno. +Vprašajte "Kaj je Spring Boot?" in takoj dodajte "Pokaži mi primer". Model si zapomni prvo vprašanje in vam poda primer posebej za Spring Boot. Brez spomina bi bilo drugo vprašanje preveč splošno. -### Korak za korakom razmišljanje +### Razmišljanje korak za korakom -Izberite matematični problem in ga poskusite tako z razmišljanjem korak za korakom kot z nizko zavzetostjo. Nizka zavzetost vam samo da odgovor - hitro, a nejasno. Korak za korakom prikaže vsak izračun in odločitev. +Izberite matematični problem in ga preizkusite z razmišljanjem korak za korakom ter z nizko zagnanostjo. Nizka zagnanost priskrbi samo odgovor – hitro, a nejasno. Razmišljanje korak za korakom prikaže vsak izračun in odločitev. ### Omejen izhod -Ko potrebujete specifične formate ali število besed, ta vzorec zagotavlja strogo upoštevanje. Poskusite ustvariti povzetek z natanko 100 besedami v obliki alinej. +Če potrebujete specifične oblike ali število besed, ta vzorec zagotavlja strogo upoštevanje. Poskusite ustvariti povzetek z natanko 100 besedami v obliki alinej. -## Kaj se pravzaprav učite +## Kaj se dejansko učite -**Napori pri razmišljanju spreminjajo vse** +**Napor razmišljanja spremeni vse** -GPT-5.2 vam omogoča nadzor nad računalniškim naporom preko vaših pozivov. Nizki napori pomenijo hitre odgovore z minimalno raziskavo. Visoki napori pomenijo, da model potrebuje čas za globoko razmišljanje. Učite se prilagajati napor kompleksnosti naloge - ne izgubljajte časa s preprostimi vprašanji, a tudi ne hitite pri zahtevnih odločitvah. +GPT-5.2 vam omogoča nadzorovanje računalniškega napora prek vaših pozivov. Nizek napor pomeni hitre odgovore z minimalnim raziskovanjem. Visok napor pomeni, da model vzame čas za globoko razmišljanje. Učite se prilagajati napor kompleksnosti naloge – ne izgubljajte časa na enostavnih vprašanjih, a tudi pri zahtevnih odločitvah ne hitite. **Struktura usmerja vedenje** -Opazili ste XML oznake v pozivih? Niso dekorativne. Modeli bolje sledijo strukturiranim navodilom kot prostemu besedilu. Ko potrebujete večstopenjske procese ali zapleteno logiko, struktura pomaga modelu slediti, kje je in kaj sledi. Diagram spodaj razčleni dobro strukturiran poziv, ki prikazuje, kako oznake, kot so ``, ``, ``, `` in `` organizirajo vaša navodila v jasne sekcije. +Opazili ste XML oznake v pozivih? Niso okrasne. Modeli bolje sledijo strukturiranim navodilom kot prostemu tekstu. Ko potrebujete večstopenjske postopke ali zapleteno logiko, struktura pomaga modelu slediti, kje se nahaja in kaj sledi. Spodnji diagram razčlenjuje dobro strukturiran poziv, ki prikazuje, kako oznake kot ``, ``, ``, `` in `` organizirajo navodila v jasne sekcije. Struktura poziva -*Anatomija dobro strukturiranega poziva z jasnimi sekcijami in XML-stilno organizacijo* +*Zgradba dobro strukturiranega poziva z jasnimi sekcijami in organizacijo v slogu XML* -**Kakovost prek samoevalvacije** +**Kakovost skozi samoevalvacijo** -Vzorec samoreflektiranja deluje tako, da kakovostna merila naredi eksplicitna. Namesto da bi upali, da model "naredi prav", mu točno poveste, kaj "prav" pomeni: pravilna logika, obdelava napak, zmogljivost, varnost. Model lahko nato oceni svoj izhod in ga izboljša. Tako generiranje kode ne postane loterija, ampak proces. +Samoreflektirajoči vzorci delujejo tako, da eksplicitno določijo kriterije kakovosti. Namesto da upate, da bo model „pravilno naredil“, mu točno poveste, kaj pomeni „pravilno“: pravilna logika, ravnanje z napakami, zmogljivost, varnost. Model lahko nato oceni svoj izhod in ga izboljša. Tako ustvarjanje kode ni več loterija, ampak proces. **Kontekst je omejen** -Večkratni pogovori delujejo tako, da imajo vključeno zgodovino sporočil z vsakim zahtevkom. A obstaja meja - vsak model ima maksimalno število tokenov. Ko pogovori rastejo, boste potrebovali strategije za ohranjanje relevantnega konteksta brez preseganja te meje. Ta modul vam pokaže, kako deluje spomin; pozneje se boste naučili, kdaj povzeti, kdaj pozabiti in kdaj poiskati. +Večkorak pogovor deluje tako, da vsakemu pozivu dodate zgodovino sporočil. Toda obstaja omejitev – vsak model ima največje število tokenov. Ko pogovori rastejo, boste potrebovali strategije za ohranjanje relevantnega konteksta, ne da bi presegli omejitev. Ta modul vam pokaže, kako deluje spomin; kasneje boste spoznali, kdaj povzemati, kdaj pozabljati in kdaj pridobivati informacije. ## Naslednji koraki -**Naslednji modul:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**Naslednji modul:** [03-rag - RAG (Generiranje z nadgradnjo iskanja)](../03-rag/README.md) --- -**Navigacija:** [← Prejšnje: Modul 01 - Uvod](../01-introduction/README.md) | [Nazaj na glavno](../README.md) | [Naslednje: Modul 03 - RAG →](../03-rag/README.md) +**Navigacija:** [← Prejšnji: Modul 01 - Uvod](../01-introduction/README.md) | [Nazaj na začetek](../README.md) | [Naprej: Modul 03 - RAG →](../03-rag/README.md) --- **Omejitev odgovornosti**: -Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, upoštevajte, da lahko samodejni prevodi vsebujejo napake ali netočnosti. Izvirni dokument v njegovem maternem jeziku naj velja za zavezujoči vir. Za kritične informacije priporočamo strokovni človeški prevod. Nismo odgovorni za morebitne nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. +Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za kritične informacije je priporočljiv strokovni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. \ No newline at end of file diff --git a/translations/sl/03-rag/README.md b/translations/sl/03-rag/README.md index c1d64f43c..b5c0c4616 100644 --- a/translations/sl/03-rag/README.md +++ b/translations/sl/03-rag/README.md @@ -1,144 +1,143 @@ -# Modul 03: RAG (generiranje z iskanjem po virov) +# Modul 03: RAG (Generacija z iskanjem) ## Kazalo -- [Video predstavitev](../../../03-rag) -- [Kaj se boste naučili](../../../03-rag) -- [Predpogoji](../../../03-rag) -- [Razumevanje RAG](../../../03-rag) - - [Kateri pristop RAG ta vodič uporablja?](../../../03-rag) -- [Kako deluje](../../../03-rag) - - [Obdelava dokumentov](../../../03-rag) - - [Ustvarjanje vdelav](../../../03-rag) - - [Semantično iskanje](../../../03-rag) - - [Generiranje odgovorov](../../../03-rag) -- [Zaženi aplikacijo](../../../03-rag) -- [Uporaba aplikacije](../../../03-rag) - - [Naloži dokument](../../../03-rag) - - [Postavljaj vprašanja](../../../03-rag) - - [Preveri reference virov](../../../03-rag) - - [Eksperimentiraj z vprašanji](../../../03-rag) -- [Ključni pojmi](../../../03-rag) - - [Strategija razdeljevanja na dele](../../../03-rag) - - [Ocene podobnosti](../../../03-rag) - - [Shranjevanje v pomnilniku](../../../03-rag) - - [Upravljanje kontekstnega okna](../../../03-rag) -- [Kdaj je RAG pomemben](../../../03-rag) -- [Naslednji koraki](../../../03-rag) - -## Video predstavitev - -Oglejte si to neposredno predstavitev, ki razlaga, kako začeti s tem modulom: +- [Video vodič](#video-vodič) +- [Kaj se boste naučili](#kaj-se-boste-naučili) +- [Pogojna znanja](#pogojna-znanja) +- [Razumevanje RAG](#razumevanje-rag) + - [Kateri RAG pristop uporablja ta vodič?](#kateri-rag-pristop-uporablja-ta-vodič) +- [Kako deluje](#kako-deluje) + - [Obdelava dokumentov](#obdelava-dokumentov) + - [Ustvarjanje vektorskih predstavitev](#ustvarjanje-vektorskih-predstavitev) + - [Semantično iskanje](#semantično-iskanje) + - [Generiranje odgovorov](#generiranje-odgovora) +- [Zaženite aplikacijo](#zaženi-aplikacijo) +- [Uporaba aplikacije](#uporaba-aplikacije) + - [Naložite dokument](#naloži-dokument) + - [Postavljajte vprašanja](#postavi-vprašanja) + - [Preverite reference virov](#preveri-vire) + - [Eksperimentirajte z vprašanji](#eksperimentiraj-z-vprašanji) +- [Ključni koncepti](#ključni-koncepti) + - [Strategija razbitja na dele](#strategija-razdelitve-na-dele) + - [Ocene podobnosti](#ocene-podobnosti) + - [Shranjevanje v pomnilnik](#shranjevanje-v-pomnilnik) + - [Upravljanje okna konteksta](#upravljanje-okna-konteksta) +- [Kdaj RAG pride prav](#kdaj-je-rag-pomemben) +- [Naslednji koraki](#naslednji-koraki) + +## Video vodič + +Oglejte si to neposredno predstavitev, ki razlaga, kako začeti z modulom: RAG z LangChain4j - neposredna seja ## Kaj se boste naučili -V prejšnjih modulih ste se naučili, kako imeti pogovore z AI in učinkovito strukturirati svoja poziva. Toda obstaja temeljna omejitev: jezikovni modeli poznajo le tisto, kar so se naučili med usposabljanjem. Ne morejo odgovarjati na vprašanja o politikah vašega podjetja, dokumentaciji vašega projekta ali katerikoli informaciji, na kateri niso bili usposobljeni. +V prejšnjih modulih ste se naučili, kako voditi pogovore z AI in učinkovito strukturirati vaše pozive. Toda obstaja osnovna omejitev: jezikovni modeli poznajo le tisto, kar so se naučili med usposabljanjem. Ne morejo odgovarjati na vprašanja o politikah vašega podjetja, vaši projektni dokumentaciji ali kakršnihkoli informacijah, na katerih niso bili usposobljeni. -RAG (generiranje z iskanjem po virov) rešuje ta problem. Namesto da bi modelu poskušali "naučiti" vaše informacije (kar je drago in nepraktično), mu daste sposobnost, da išče po vaših dokumentih. Ko nekdo postavi vprašanje, sistem najde ustrezne informacije in jih vključi v poziv. Model nato odgovori na podlagi tega pridobljenega konteksta. +RAG (Generacija z iskanjem) rešuje ta problem. Namesto da bi modelu poskušali »naučiti« vaše podatke (kar je drago in nepraktično), mu omogočite iskanje znotraj vaših dokumentov. Ko nekdo postavi vprašanje, sistem poišče relevantne informacije in jih vključuje v poziv. Model nato odgovori na podlagi tega pridobljenega konteksta. -RAG si predstavljajte kot modelu podarjeno referenčno knjižnico. Ko postavite vprašanje, sistem: +Razmislite o RAG kot o tem, da modelu daste referenčno knjižnico. Ko postavite vprašanje, sistem: -1. **Uporabniški poizvedba** – vi postavite vprašanje -2. **Vdelava** – vaše vprašanje prevede v vektor -3. **Iskanje po vektorjih** – najde podobne dele dokumentov -4. **Sestavljanje konteksta** – doda ustrezne dele v poziv -5. **Odgovor** – LLM (velik jezikovni model) generira odgovor na podlagi konteksta +1. **Uporabniški poizvedba** - Vi postavite vprašanje +2. **Vektorska predstavitev** - Vaše vprašanje pretvori v vektor +3. **Večdimenzionalno iskanje** - Poišče podobne dele dokumenta +4. **Sestava konteksta** - Doda relevantne dele v poziv +5. **Odgovor** - Velik jezikovni model (LLM) ustvari odgovor na podlagi konteksta -Tako so odgovori modela zasidrani v vaših dejanskih podatkih namesto da bi temeljili le na usposabljanju ali si jih izmislili. +To pritrdi odgovore modela na vaše dejanske podatke namesto, da bi se zanašal na usposabljanje ali zgolj izmišljeval odgovore. -## Predpogoji +## Pogojna znanja -- Zaključen [Modul 00 - Hitri začetek](../00-quick-start/README.md) (za primer Easy RAG, na katerega se sklicuje ta modul) -- Zaključen [Modul 01 - Uvod](../01-introduction/README.md) (Azure OpenAI viri so nameščeni, vključno z modelom `text-embedding-3-small`) -- Datoteka `.env` v korenski mapi z Azure poverilnicami (ustvarjena z `azd up` v Modulu 01) +- Dokončan [Modul 01 - Uvod](../01-introduction/README.md) (Azure OpenAI viri vzpostavljeni, vključno z vektorskim modelom `text-embedding-3-small`) +- `.env` datoteka v korenskem imeniku z Azure poverilnicami (ustvarjena s `azd up` v Modul 01) -> **Opomba:** Če Modul 01 še niste zaključili, najprej sledite navodilom za namestitev tam. Ukaz `azd up` namesti tako GPT klepetalni model kot tudi model za vdelave, ki ga ta modul uporablja. +> **Opomba:** Če niste zaključili Modula 01, sledite tam navodilom za namestitev. Ukaz `azd up` vzpostavi tako GPT klepetalni model kot tudi vektorski model, ki ga uporablja ta modul. ## Razumevanje RAG -Spodnja shema ponazarja osnovni koncept: namesto da bi se zanašali izključno na podatke usposabljanja modela, RAG modelu omogoča referenčno knjižnico vaših dokumentov, ki jih pregleduje pred generiranjem vsakega odgovora. +Spodnja shema ponazarja osnovni koncept: namesto da bi se model zanašal zgolj na podatke iz usposabljanja, mu RAG omogoča, da pred generiranjem vsakega odgovora najprej pregleda vaše dokumente. Kaj je RAG -*Ta shema kaže razliko med običajnim LLM (ki ugiba iz podatkov usposabljanja) in LLM, izboljšanim z RAG (ki najprej pregleduje vaše dokumente).* +*Ta shema prikazuje razliko med standardnim LLM (ki ugiba iz učnih podatkov) in RAG-razširjenim LLM (ki najprej preveri vaše dokumente).* -Poglejmo, kako so deli povezani od začetka do konca. Uporabnikovo vprašanje poteka skozi štiri faze — vdelava, iskanje po vektorjih, sestavljanje konteksta in generiranje odgovora — vsaka temelji na prejšnji: +Tukaj je povezava vseh delov od začetka do konca. Uporabnikovo vprašanje poteka skozi štiri faze — vektorska reprezentacija, iskanje po vektorjih, sestava konteksta in generiranje odgovora — vsaka gradi na prejšnji: -Arhitektura RAG +RAG arhitektura -*Ta shema kaže celoten RAG potek — uporabniška poizvedba poteka skozi vdelavo, iskanje, sestavljanje konteksta in generiranje odgovora.* +*Ta shema prikazuje celoten RAG potek — vprašanje uporabnika gre skozi vektorsko reprezentacijo, iskanje po vektorjih, sestavo konteksta in generiranje odgovora.* -Preostali del tega modula podrobno razlaga vsako fazo s kodo, ki jo lahko zaženete in prilagodite. +Preostali del tega modula obravnava vsako fazo podrobno, s kodo, ki jo lahko zaženete in spreminjate. -### Kateri pristop RAG ta vodič uporablja? +### Kateri RAG pristop uporablja ta vodič? -LangChain4j ponuja tri načine za implementacijo RAG, vsak z različnim nivojem abstrakcije. Spodnja shema jih primerja vzporedno: +LangChain4j ponuja tri načine implementacije RAG, vsak s svojo stopnjo abstrakcije. Spodnja shema jih primerja vzporedno: -Trije pristopi RAG v LangChain4j +Trije RAG pristopi v LangChain4j -*Ta shema primerja tri RAG pristope v LangChain4j — Easy, Native in Advanced — ter prikazuje njihove ključne komponente in kdaj jih uporabiti.* +*Ta shema primerja tri LangChain4j RAG pristope — Easy, Native in Advanced — prikazuje njihove ključne sestavine in kdaj jih uporabiti.* -| Pristop | Kaj počne | Kompromis | +| Pristop | Kaj počne | Kompromisi | |---|---|---| -| **Easy RAG** | Vse samodejno poveže preko `AiServices` in `ContentRetriever`. Obeležite vmesnik, dodate pridobivalca, LangChain4j pa za vas upravlja vdelave, iskanje in sestavljanje poziva. | Minimalna koda, a ne vidite, kaj se dogaja v vsakem koraku. | -| **Native RAG** | Sami pokličete model za vdelave, iščete v shrambi, sestavite poziv in generirate odgovor — vse korake izrecno. | Več kode, a vsak korak je viden in spreminjiv. | -| **Advanced RAG** | Uporablja ogrodje `RetrievalAugmentor` z vtičnimi transformatorji poizvedb, usmerjevalniki, ponovnim razvrščanjem in vstavljalniki vsebine za produkcijske cevovode. | Največja fleksibilnost, a precej več kompleksnosti. | +| **Easy RAG** | Samodejno poveže vse prek `AiServices` in `ContentRetriever`. Označite vmesnik, priključite iskalnik in LangChain4j skrbi za vektorsko predstavitev, iskanje in sestavljanje poziva v ozadju. | Minimalno kodiranja, vendar ne vidite vsakega koraka posebej. | +| **Native RAG** | Sami kličete vektorski model, iščete v shrambi, gradite poziv in ustvarjate odgovor — korak po koraku, eksplicitno. | Več kode, a vsaka faza je vidna in prilagodljiva. | +| **Advanced RAG** | Uporablja `RetrievalAugmentor` okvir z vtičniki za transformatorje poizvedb, usmerjevalce, ponovno rangiranje in vstavljanje vsebin za proizvodne pipeleine. | Največja prilagodljivost, a bistveno več kompleksnosti. | -**Ta vodič uporablja Native pristop.** Vsak korak RAG poteka — vdelava poizvedbe, iskanje v vektorski shrambi, združevanje konteksta in generiranje odgovora — je jasno zapisan v [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). To je namerno: kot učni vir je pomembnejše, da vidite in razumete vsak korak, kot da je koda čim bolj zgoščena. Ko boste obvladali, kako se deli povezujejo, se lahko premaknete na Easy RAG za hitre prototipe ali Advanced RAG za produkcijske sisteme. +**Ta vodič uporablja Native pristop.** Vsak korak RAG pipeline — vektorska predstavitev poizvedbe, iskanje v vektorski shrambi, sestavljanje konteksta in generiranje odgovora — je jasno zapisan v [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). To je namenoma: kot učni vir je pomembneje, da vidite in razumete vsak korak, kot da je koda čim krajša. Ko boste razumeli, kako kosi skupaj delujejo, lahko preidete na Easy RAG za hitre prototipe ali Advanced RAG za proizvodne sisteme. -> **💡 Ste že videli Easy RAG v praksi?** Modul [Hitri začetek](../00-quick-start/README.md) vključuje primer vprašanj in odgovorov na dokument ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) z uporabo Easy RAG pristopa — LangChain4j samodejno upravlja vdelave, iskanje in sestavljanje poziva. Ta modul naredi naslednji korak tako, da odpre ta cevovod, da vidite in kontrolirate vsak korak. +> **💡 Vas zanima Easy RAG?** LangChain4j ponuja tudi *Easy RAG* pristop, kjer `AiServices` in `ContentRetriever` avtomatsko upravljata z vektorsko predstavitvijo, iskanjem in sestavljanjem poziva. Ta modul sledi bolj eksplicitni poti – odpira ta pipeline, da lahko sami vidite in upravljate vsako fazo. -Spodnja shema prikazuje Easy RAG cevovod iz primera Hitrega začetka. Opazite, kako `AiServices` in `EmbeddingStoreContentRetriever` skrijeta vso kompleksnost — naložite dokument, dodate pridobivalca in prejmete odgovore. Native pristop tega modula razkrije vse te skrite korake: +Spodnja shema prikazuje Easy RAG pipeline. Opazite, kako `AiServices` in `EmbeddingStoreContentRetriever` skrivata vso kompleksnost — naložite dokument, priključite iskalnik in dobite odgovore. Native pristop v tem modulu pa razkrije te skrite korake: -Easy RAG cevovod - LangChain4j +Easy RAG pipeline - LangChain4j -*Ta shema prikazuje Easy RAG cevovod iz `SimpleReaderDemo.java`. Primerjajte z Native pristopom, uporabljenim v tem modulu: Easy RAG skriva vdelave, iskanje in sestavljanje poziva za `AiServices` in `ContentRetriever` — naložite dokument, dodate pridobivalca, in dobite odgovore. Native pristop tega modula odpre ta cevovod, da sami pokličete posamezne faze (vdelava, iskanje, sestavljanje konteksta, generiranje), kar vam omogoča popoln vpogled in nadzor.* +*Ta shema prikazuje Easy RAG pipeline. Primerjajte jo z Native pristopom iz tega modula: Easy RAG skriva embedding, iskanje in sestavo poziva za `AiServices` in `ContentRetriever` — naložite dokument, priključite iskalnik in dobite odgovore. Native pristop tega modula odpira pipeline tako, da sami kličete vsako fazo (vektorska predstavitev, iskanje, sestava konteksta, generiranje), kar vam daje popoln vpogled in nadzor.* ## Kako deluje -RAG cevovod v tem modulu je razdeljen na štiri faze, ki se izvajajo zaporedno vsakič, ko uporabnik postavi vprašanje. Najprej se naloženi dokument **razčleni in razdeli na dele** v obvladljive koščke. Ti deli se nato pretvorijo v **vektorske vdelave** in shranijo za matematično primerjavo. Ko pride poizvedba, sistem opravi **semantično iskanje**, da najde najbolj relevantne dele, in jih nato kot kontekst posreduje LLM-ju za **generiranje odgovora**. Spodnji razdelki podrobno razložijo vsak korak z dejansko kodo in diagrami. Poglejmo najprej prvi korak. +RAG pipeline tega modula je sestavljen iz štirih zaporednih faz, ki se spustijo vsakič, ko uporabnik postavi vprašanje. Najprej se naloženi dokument **parsira in razdeli na dele**. Ti deli se nato pretvorijo v **vektorske predstavitve** in shranijo, da se lahko matematično primerjajo. Ko prispe poizvedba, sistem opravi **semantično iskanje** za najbližje dele, nato pa jih predloži kot kontekst LLM za **generiranje odgovora**. Spodnji razdelki opisujejo vsako fazo z dejansko kodo in shemami. Poglejmo prvi korak. ### Obdelava dokumentov [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Ko naložite dokument, ga sistem prebere (PDF ali navaden tekst), mu doda metapodatke, kot je ime datoteke, in ga razdeli na dele — manjše koščke, ki udobno ustrezajo modelovemu kontekstnemu oknu. Ti deli se nekoliko prekrivajo, da ne izgubite konteksta na mejah. +Ko naložite dokument, ga sistem parsira (PDF ali navaden tekst), pripne metapodatke, kot je ime datoteke, nato pa ga razbije na dele — manjše koščke, ki zlahka sprejemajo model v kontekstno okno. Ti deli se rahlo prekrivajo, da ne izgubite konteksta na robovih. ```java -// Analizirajte naloženo datoteko in jo ovijte v LangChain4j dokument +// Razčleni naloženo datoteko in jo zavij v LangChain4j dokument Document document = Document.from(content, metadata); -// Razdelite na dele po 300 žetonov z 30-žetonskim prekrivanjem +// Razdeli na dele po 300 znakov s 30-znakovnim prekrivanjem DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Spodnja shema prikazuje to na vizualni način. Opazite, kako vsak del deli nekaj tokenov s sosednjimi — 30-tokensko prekrivanje zagotavlja, da noben pomemben kontekst ne pade med reže: +Spodnja shema prikazuje, kako to deluje vizualno. Opazite, kako vsak del deli nekaj tokenov s sosedi — 30 tokenov prekrivanja zagotavlja, da ne izgubite pomembnega konteksta med deli: -Deljenje dokumenta na dele +Razbitje dokumenta -*Ta shema prikazuje, kako je dokument razdeljen na 300-token dele s 30-token prekrivanjem, kar ohranja kontekst na mejah delov.* +*Ta shema prikazuje dokument razdeljen v 300-token bloki s 30-token prekrivanjem, kar ohranja kontekst na robovih blokov.* > **🤖 Poskusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odprite [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) in vprašajte: -> - "Kako LangChain4j razdeli dokumente na dele in zakaj je pomembno prekrivanje?" +> - "Kako LangChain4j razbija dokumente na dele in zakaj je prekrivanje pomembno?" > - "Kakšna je optimalna velikost delov za različne vrste dokumentov in zakaj?" -> - "Kako obravnavati dokumente v več jezikih ali s posebno obliko?" +> - "Kako upravljam z dokumenti v več jezikih ali s posebnim oblikovanjem?" -### Ustvarjanje vdelav +### Ustvarjanje vektorskih predstavitev [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Vsak del je pretvorjen v številčno predstavo, imenovano vdelava — v bistvu pretvornik pomena v številke. Model za vdelave ni "pameten" kot klepetalni model; ne more slediti navodilom, sklepati ali odgovarjati na vprašanja. Lahko pa tekst preslika v matematični prostor, kjer so podobni pomeni blizu drug drugemu — "avto" blizu "vozilo", "politika vračil" blizu "vrnite denar". Klepetalni model si predstavljajte kot osebo, s katero govorite; model za vdelave je izjemno dober sistem arhiviranja. +Vsak del se pretvori v številčno predstavitev, imenovano embedding — v bistvu pretvornik pomena v številke. Model za vektorsko predstavitev ni "inteligenten" kot klepetalni model; ne zmore slediti navodilom, razmišljati ali odgovarjati na vprašanja. Zmore pa preslikati besedilo v matematični prostor, kjer so podobni pomeni blizu drug drugega — "avto" blizu "vozilo", "politika vračila" blizu "vrnite denar". Klepetalni model je kot oseba, ki ji lahko govorite; embedding model je odličen sistem za urejanje datotek. -Spodnja shema vizualizira ta koncept — vstopi tekst, izstopijo številčni vektorji, podobni pomeni imajo bližnje vektorje: +Spodnja shema vizualizira ta koncept — prispe besedilo, izhajajo številčni vektorji, podobni pomeni pa so blizu drug drugemu: -Koncept modela za vdelave +Koncept embedding modela -*Ta shema prikazuje, kako model za vdelave pretvori tekst v številčne vektorje, pri čemer so podobni pomeni — kot "avto" in "vozilo" — umeščeni blizu v vektorskem prostoru.* +*Ta shema prikazuje, kako embedding model pretvori besedilo v številčne vektorje, pri čemer podobni pomeni — kot "avto" in "vozilo" — stojijo blizu drug drugemu v vektorskem prostoru.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Spodnja razredna shema prikazuje dva ločena poteka v RAG cevovodu in LangChain4j razrede, ki jih implementirajo. **Tok vnosa** (izvaja se ob nalaganju) razdeli dokument, vdeluje dele in jih shrani preko `.addAll()`. **Tok poizvedbe** (izvaja se vsakič, ko uporabnik vpraša) vdeluje vprašanje, išče v shrambi preko `.search()`, in posreduje najden kontekst klepetalnemu modelu. Oba toka se združita na skupnem vmesniku `EmbeddingStore`: +Razredna shema spodaj prikazuje dva ločena toka v RAG pipeline ter LangChain4j razrede, ki jih implementirajo. Tok **uvoza** (zažene se enkrat ob nalaganju) razdeli dokument, ustvari embedding za dele in jih shrani preko `.addAll()`. Tok **poizvedbe** (zažene se ob vsakem vprašanju) naredi embedding vprašanja, išče po shrambi s `.search()` in predloži ustrezni kontekst klepetalnemu modelu. Oba toka sta povezana prek skupnega vmesnika `EmbeddingStore`: LangChain4j RAG razredi -*Ta shema prikazuje dva poteka v RAG cevovodu — vnos in poizvedbo — ter kako sta povezana skozi skupni EmbeddingStore.* +*Ta shema prikazuje dva toka v RAG pipeline — uvoz in poizvedbo — in kako se povežeta preko skupnega vmesnika EmbeddingStore.* -Ko so vdelave shranjene, se podobne vsebine naravno združujejo v vektorskem prostoru. Spodnja vizualizacija kaže, kako se dokumenti o sorodnih temah združujejo v bližnje točke, kar omogoča semantično iskanje: +Ko so embeddingi shranjeni, se podobne vsebine naravno zberejo skupaj v vektorskem prostoru. Spodnja vizualizacija prikazuje, kako se dokumenti o sorodnih temah združijo v bližnje točke, kar omogoča semantično iskanje: -Prostor vektorskih vdelav +Vektorski embeddingi -*Ta vizualizacija prikazuje, kako sorodni dokumenti tvorijo skupine v tridimenzionalnem vektorskem prostoru, s področji kot tehnični dokumenti, poslovna pravila in pogosta vprašanja.* +*Ta vizualizacija prikazuje, kako se sorodni dokumenti zberejo skupaj v 3D vektorskem prostoru, s temami kot Tehnična dokumentacija, Poslovna pravila in Pogosto zastavljena vprašanja, ki tvorijo ločene skupine.* -Ko uporabnik išče, sistem sledi štirim korakom: enkrat vdelava dokumentov, vdelava poizvedbe vsakič ob iskanju, primerjava vektorja poizvedbe z vsemi shranjenimi vektorji s pomočjo kosinusne podobnosti in vrnitev najboljših top-K rezultatov. Spodnja shema vodi skozi vsak korak in LangChain4j razrede, ki se pri tem uporabljajo: +Ko uporabnik išče, sistem sledi štirim korakom: enkrat naredi embedding dokumentov, za vsako poizvedbo naredi embedding vprašanja, primerja vektor poizvedbe proti vsem shranjenim vektorjem z uporabo kosinusne podobnosti in vrne top-K najvišje ocenjene dele. Spodnja shema prikazuje korake in LangChain4j razrede: -Koraki iskanja po vdelavah +Koraki iskanja po embeddingu -*Ta shema prikazuje štiristopenjski postopek iskanja po vdelavah: vdelava dokumentov, vdelava poizvedbe, primerjava vektorjev s kosinusno podobnostjo in vrnitev najboljših rezultatov.* +*Ta shema prikazuje štiri korake iskanja po embeddingu: embedding dokumentov, embedding poizvedbe, primerjava vektorjev s kosinusno podobnostjo in vrnitev top-K rezultatov.* ### Semantično iskanje [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Ko postavite vprašanje, vaše vprašanje postane tudi vdelava. Sistem primerja vdelavo vašega vprašanja z vdelavami vseh dokumentnih delov. Najde dele z najbolj podobnimi pomeni — ne le ujemanje ključnih besed, temveč dejansko semantično podobnost. +Ko postavite vprašanje, se tudi vaše vprašanje spremeni v embedding. Sistem primerja embedding vašega vprašanja z embeddingi vseh delov dokumenta. Najde dele z najbolj podobnim pomenom — ne le besedne ujemanja, ampak dejansko semantično podobnost. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Spodnja shema primerja semantično iskanje s tradicionalnim iskanjem po ključnih besedah. Iskanje po ključni besedi "vozilo" zamudi del o "avtih in tovornjakih", medtem ko semantično iskanje razume, da to pomeni enako in ga vrne kot visoko ocenjen rezultat: +Spodnja shema primerja semantično iskanje s tradicionalnim iskanjem po ključnih besedah. Iskanje po ključni besedi "vozilo" ne zadene na del o "avtih in tovornjakih", a semantično iskanje razume, da pomenita isto in ga vrne kot visoko ujemajoč rezultat: Semantično iskanje -*Ta shema primerja iskanje na podlagi ključnih besed z semantičnim iskanjem, ki najde konceptualno sorodno vsebino tudi, če se natančne ključne besede razlikujejo.* -Pod pokrovom se podobnost meri z uporabo kosinusne podobnosti — kar v bistvu pomeni vprašanje "ali ti dve puščici kažeta v isto smer?" Dva kosa lahko uporabita popolnoma različne besede, vendar če pomenita isto stvar, njihovi vektorji kažejo v isto smer in dosežejo rezultat blizu 1.0: +*Ta shema primerja iskanje po ključnih besedah in semantično iskanje, kjer semantično iskanje pridobi konceptualno sorodne vsebine, tudi če se natančne ključne besede razlikujejo.* -Cosine Similarity +Pod pokrovom se podobnost meri z uporabo kosinusne podobnosti — v bistvu sprašuje »ali ti dve pušči kažeta v isto smer?« Dva dela lahko uporabita popolnoma različne besede, a če pomenita isto, večdimenzionalni vektorji kažeta v isto smer in nakazujejo oceno blizu 1,0: -*Ta diagram prikazuje kosinusno podobnost kot kot med vektorji vdelave — bolj poravnani vektorji dosegajo rezultat bližje 1.0, kar kaže na višjo semantično podobnost.* +Kosinusna podobnost +*Ta diagram ponazarja podobnost kosinus kot kot med vektorskimi predstavitvami — bolj usklajeni vektorji dosegajo vrednost bližje 1,0, kar kaže na večjo semantično podobnost.* -> **🤖 Preizkusi z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odpri [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) in vprašaj: -> - "Kako deluje iskanje podobnosti z vdelavami in kaj določa rezultat?" -> - "Katero mejo podobnosti naj uporabim in kako to vpliva na rezultate?" -> - "Kako ravnam v primerih, ko niso najdeni relevantni dokumenti?" +> **🤖 Poskusi s klepetom [GitHub Copilot](https://github.com/features/copilot):** Odpri [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) in vprašaj: +> - "Kako deluje iskanje podobnosti z embeddingi in kaj določa oceno?" +> - "Kateri prag podobnosti naj uporabim in kako vpliva na rezultate?" +> - "Kako ravnam v primerih, ko ni najdenih relevantnih dokumentov?" -### Generiranje Odgovora +### Generiranje odgovora [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Najbolj relevantni kosi so sestavljeni v strukturirano poziv, ki vključuje eksplicitna navodila, pridobljen kontekst in vprašanje uporabnika. Model prebere te specifične koščke in odgovori na podlagi teh informacij — lahko uporabi le to, kar je pred njim, kar preprečuje halucinacije. +Najbolj relevantni deli so sestavljeni v strukturiran poziv, ki vključuje eksplicitna navodila, pridobljen kontekst in uporabnikovo vprašanje. Model prebere te specifične dele in odgovori na podlagi teh informacij — lahko uporablja le tisto, kar ima pred seboj, kar preprečuje halucinacije. ```java String context = matches.stream() @@ -237,49 +236,49 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Diagram spodaj prikazuje ta postopek sestavljanja v akciji — najboljše ocenjeni kosi iz koraka iskanja so vstavljeni v predlogo poziva, `OpenAiOfficialChatModel` pa ustvari utemeljen odgovor: +Spodnji diagram prikazuje to sestavljanje v akciji — najbolj ocenjeni deli iz koraka iskanja se vnesejo v predlogo poziva, `OpenAiOfficialChatModel` pa generira utemeljen odgovor: -Context Assembly +Sestavljanje konteksta -*Ta diagram prikazuje, kako so najboljši ocenjeni kosi sestavljeni v strukturirano poziv, kar omogoča modelu, da iz vaših podatkov ustvari utemeljen odgovor.* +*Ta diagram prikazuje, kako se najbolj ocenjeni deli sestavijo v strukturiran poziv, kar omogoča modelu generiranje utemeljenega odgovora iz vaših podatkov.* -## Zaženi Aplikacijo +## Zaženi aplikacijo **Preveri namestitev:** -Prepričaj se, da datoteka `.env` obstaja v korenskem imeniku z Azure poverilnicami (ustvarjeno med Modulom 01). Zaženi to iz imenika modula (`03-rag/`): +Prepričaj se, da datoteka `.env` obstaja v korenski mapi z Azure poverilnicami (ustvarjena med modulom 01). Zaženi to iz mape modula (`03-rag/`): **Bash:** ```bash -cat ../.env # Prikazati mora AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Naj prikazuje AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Mora prikazati AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Naj prikazuje AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Zaženi aplikacijo:** -> **Opomba:** Če ste že zagnali vse aplikacije z `./start-all.sh` iz korenskega imenika (kot je opisano v Modulu 01), je ta modul že zagnan na vratih 8081. Spodnje ukaze za zagon lahko preskočite in pojdite neposredno na http://localhost:8081. +> **Opomba:** Če si že zagnal vse aplikacije z uporabo `./start-all.sh` iz korenske mape (kot je opisano v modulu 01), ta modul že teče na vratih 8081. Ukaze za zagon spodaj lahko preskočiš in greš neposredno na http://localhost:8081. -**Možnost 1: Uporaba Spring Boot nadzorne plošče (Priporočeno za uporabnike VS Code)** +**Možnost 1: Uporaba Spring Boot nadzorne plošče (priporočeno za uporabnike VS Code)** -Dev container vključuje razširitev Spring Boot Dashboard, ki ponuja vizualni vmesnik za upravljanje vseh Spring Boot aplikacij. Najdete ga na vrstici aktivnosti na levi strani VS Code (poiščite ikono Spring Boot). +Razvojno okolje vsebuje razširitev Spring Boot Dashboard, ki nudi vizualni vmesnik za upravljanje vseh aplikacij Spring Boot. Najdeš jo v vrstici aktivnosti na levi strani VS Code (poišči ikono Spring Boot). -Iz Spring Boot nadzorne plošče lahko: -- Vidite vse razpoložljive Spring Boot aplikacije v delovnem prostoru -- Enostavno zaženete/ustavite aplikacije z enim klikom -- V realnem času spremljate dnevnike aplikacij -- Nadzorujete stanje aplikacije +Iz Spring Boot Dashboarda lahko: +- vidiš vse razpoložljive Spring Boot aplikacije v delovnem prostoru +- zaženeš/ustaviš aplikacije z enim klikom +- v realnem času spremljaš dnevnike aplikacij +- spremljaš status aplikacij -Preprosto kliknite gumb za predvajanje poleg "rag" za zagon tega modula ali zaženite vse module naenkrat. +Preprosto klikni na gumb predvajanja poleg "rag", da zaženeš ta modul, ali pa zaženi vse module naenkrat. -Spring Boot Dashboard +Spring Boot nadzorna plošča -*Ta posnetek zaslona prikazuje Spring Boot Dashboard v VS Code, kjer lahko vizualno zaženete, ustavite in spremljate aplikacije.* +*Ta posnetek zaslona prikazuje Spring Boot nadzorno ploščo v VS Code, kjer lahko vizualno zaženeš, ustaviš in spremljaš aplikacije.* -**Možnost 2: Uporaba shell skript** +**Možnost 2: Uporaba ukaznih skript** Zaženi vse spletne aplikacije (moduli 01-04): @@ -309,25 +308,25 @@ cd 03-rag .\start.ps1 ``` -Oba skripta samodejno naložita spremenljivke okolja iz korenske `.env` datoteke in bodo sestavila JAR-je, če ti še ne obstajajo. +Oba skripta samodejno naložita spremenljivke okolja iz korenske `.env` datoteke in po potrebi zgradita JAR datoteke. -> **Opomba:** Če želite najprej ročno sestaviti vse module pred zagonom: +> **Opomba:** Če raje ročno zgradiš vse module pred zagonom: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Odprite http://localhost:8081 v vašem brskalniku. +Odpri http://localhost:8081 v svojem brskalniku. -**Za zaustavitev:** +**Za ustavitev:** **Bash:** ```bash @@ -343,95 +342,95 @@ cd .. && ./stop-all.sh # Vsi moduli cd ..; .\stop-all.ps1 # Vsi moduli ``` -## Uporaba Aplikacije +## Uporaba aplikacije Aplikacija nudi spletni vmesnik za nalaganje dokumentov in postavljanje vprašanj. -RAG Application Interface +Vmesnik RAG aplikacije -*Ta posnetek zaslona prikazuje vmesnik RAG aplikacije, kjer nalagate dokumente in postavljate vprašanja.* +*Ta posnetek prikazuje vmesnik RAG aplikacije, kjer nalagaš dokumente in postavljaš vprašanja.* -### Naloži Dokument +### Naloži dokument -Začni z nalaganjem dokumenta – za testiranje so najbolj primerni TXT datoteki. V tem imeniku je na voljo `sample-document.txt`, ki vsebuje informacije o funkcijah LangChain4j, implementaciji RAG in najboljših praksah – idealno za preizkus sistema. +Začni z nalaganjem dokumenta — za testiranje najbolje delujejo TXT datoteke. V tej mapi je na voljo `sample-document.txt`, ki vsebuje informacije o funkcijah LangChain4j, implementaciji RAG in najboljših praksah — idealno za testiranje sistema. -Sistem obdela vaš dokument, ga razdeli na koščke in ustvarja vdelave za vsak košček. To se zgodi samodejno ob nalaganju. +Sistem obdela tvoj dokument, ga razdeli na dele in ustvari vektorske predstavitve (embeddinge) za vsak del. To se zgodi samodejno ob nalaganju. -### Postavljaj Vprašanja +### Postavi vprašanja -Zdaj postavite specifična vprašanja o vsebini dokumenta. Poskusite s kakšno dejansko trditvijo, ki je jasno navedena v dokumentu. Sistem poišče relevantne koščke, jih vključi v poziv in ustvari odgovor. +Zdaj postavi specifična vprašanja o vsebini dokumenta. Poskusi nekaj dejanskega, kar je jasno navedeno v dokumentu. Sistem poišče relevantne dele, jih vključi v poziv in generira odgovor. -### Preveri Vire +### Preveri vire -Opazili boste, da vsak odgovor vključuje reference virov z ocenami podobnosti. Te ocene (od 0 do 1) kažejo, kako relevanten je bil vsak košček za vaše vprašanje. Višje ocene pomenijo boljše ujemanje. To vam omogoča preverjanje odgovora glede na izvirni material. +Opazi, da vsak odgovor vključuje sklice na vire s podobnostnimi ocenami. Te ocene (od 0 do 1) prikazujejo, kako relevanten je bil vsak del za tvoje vprašanje. Višje ocene pomenijo boljše ujemanje. To ti omogoča preverjanje odgovora glede na izvorno gradivo. -RAG Query Results +Rezultati poizvedbe RAG -*Ta posnetek zaslona prikazuje rezultate poizvedbe z ustvarjenim odgovorom, referencami virov in ocenami relevantnosti za vsak pridobljeni košček.* +*Ta posnetek prikazuje rezultate poizvedbe z generiranim odgovorom, viri in ocenami relevantnosti za vsak najdeni del.* ### Eksperimentiraj z vprašanji -Poskusi različne vrste vprašanj: +Preizkusi različne vrste vprašanj: - Specifična dejstva: "Kakšna je glavna tema?" -- Primerjave: "Kakšna je razlika med X in Y?" +- Primerjave: "V čem je razlika med X in Y?" - Povzetki: "Povzemi ključne točke o Z" -Opazuj, kako se ocene relevantnosti spreminjajo glede na to, kako dobro se tvoje vprašanje ujema z vsebino dokumenta. +Opazuj, kako se ocene relevantnosti spreminjajo glede na to, kako dobro vprašanje ustreza vsebini dokumenta. -## Ključni Koncepti +## Ključni koncepti -### Strategija razdelitve (Chunking) +### Strategija razdelitve na dele -Dokumenti so razdeljeni na koščke po 300 tokenov z 30 tokeni prekrivanja. Ta uravnoteženost zagotavlja, da ima vsak kos dovolj konteksta, da je smiseln, hkrati pa je dovolj majhen, da je lahko vključen več koščkov v poziv. +Dokumenti so razdeljeni na 300-token dele z 30-token prekrivanjem. Ta uravnoteženost zagotavlja, da ima vsak del dovolj konteksta, da je smiseln, hkrati pa ostane dovolj majhen, da jih je mogoče vključiti več v poziv. ### Ocene podobnosti -Vsak pridobljeni kos ima oceno podobnosti med 0 in 1, ki kaže, kako tesno se ujema z vprašanjem uporabnika. Diagram spodaj vizualizira razpone ocen in način, kako jih sistem uporablja za filtriranje rezultatov: +Vsak pridobljeni del ima oceno podobnosti med 0 in 1, ki nakazuje, kako dobro se ujema z uporabnikovim vprašanjem. Spodnji diagram prikazuje razpone ocen in kako sistem uporablja te razpone za filtriranje rezultatov: -Similarity Scores +Ocene podobnosti -*Ta diagram prikazuje razpone ocen od 0 do 1, z minimalno mejo 0.5, ki filtrira irelevantne koščke.* +*Ta diagram prikazuje razpone ocen od 0 do 1, s minimalnim pragom 0,5, ki filtrira nepomembne dele.* -Ocene se gibljejo od 0 do 1: -- 0.7-1.0: Zelo relevantno, točno ujemanje -- 0.5-0.7: Relevantno, dober kontekst -- Pod 0.5: Filtrirano, preveč različno +Ocene segajo od 0 do 1: +- 0,7–1,0: Zelo relevantno, natanko ujemanje +- 0,5–0,7: Relevantno, dober kontekst +- Pod 0,5: Filtrirano, preveč neujemajoče -Sistem pridobi le koščke nad minimalno mejo za zagotavljanje kakovosti. +Sistem pridobiva le dele nad minimalnim pragom, da zagotovi kakovost. -Vdelave delujejo dobro, kadar se pomen jasno združuje, a imajo tudi slepe točke. Diagram spodaj prikazuje pogoste načine neuspeha — preveliki kosi ustvarjajo nejasne vektorje, premajhni kosi nimajo konteksta, dvoumni izrazi kažejo na več grozdov, in natančna iskanja (ID-ji, številke delov) sploh ne delujejo z vdelavami: +Embeddingi delujejo dobro, ko so pomeni jasno združeni, vendar imajo slepe pege. Spodnji diagram prikazuje pogoste neuspehe — preveliki deli proizvedejo zamegljene vektorje, premajhni nimajo konteksta, dvoumni izrazi kažejo na več grozdov, in neposredni pregledi (ID-ji, številke delov) z embeddingi sploh ne delujejo: -Embedding Failure Modes +Načini neuspeha embeddingov -*Ta diagram prikazuje pogoste načine neuspeha vdelav: preveliki kosi, premajhni kosi, dvoumni izrazi, in natančna iskanja kot ID-ji.* +*Ta diagram prikazuje pogoste načine neuspeha embeddingov: preveliki deli, premajhni deli, dvoumni izrazi, ki kažejo na več grozdov, in neposredni pregledi, kot so ID-ji.* -### Shranjevanje v pomnilniku +### Shranjevanje v pomnilnik -Ta modul uporablja shranjevanje v pomnilniku za preprostost. Ko ponovno zaženete aplikacijo, so naloženi dokumenti izgubljeni. Produkcijski sistemi uporabljajo trajne vektorske baze podatkov, kot so Qdrant ali Azure AI Search. +Ta modul uporablja shranjevanje v pomnilnik za enostavnost. Ob ponovnem zagonu aplikacije so naloženi dokumenti izgubljeni. Produkcijski sistemi uporabljajo trajne vektorske baze, kot sta Qdrant ali Azure AI Search. -### Upravljanje kontekstnega okna +### Upravljanje okna konteksta -Vsak model ima največjo velikost kontekstnega okna. Ne morete vključiti vseh kosov iz velikega dokumenta. Sistem pridobi prvih N najbolj relevantnih kosov (privzeto 5), da ostane znotraj omejitev in hkrati zagotovi dovolj konteksta za točne odgovore. +Vsak model ima največjo velikost kontekstnega okna. Ne moreš vključiti vseh delov velikega dokumenta. Sistem pridobi najboljših N najbolj relevantnih delov (privzeto 5), da ostane znotraj omejitev, hkrati pa nudi dovolj konteksta za točne odgovore. ## Kdaj je RAG pomemben -RAG ni vedno prava izbira. Spodnji vodnik za odločanje vam pomaga ugotoviti, kdaj RAG prinese dodano vrednost in kdaj so preprostejši pristopi — kot vključevanje vsebine neposredno v poziv ali zanašanje na vgrajeno znanje modela — zadostni: +RAG ni vedno prava izbira. Spodnji vodnik odločitve ti pomaga določiti, kdaj RAG prinaša dodano vrednost in kdaj so preprostejši pristopi — kot vključevanje vsebine neposredno v poziv ali zanašanje na vgrajeno znanje modela — dovolj: -When to Use RAG +Kdaj uporabiti RAG -*Ta diagram prikazuje vodnik za odločanje o tem, kdaj RAG prinaša dodano vrednost in kdaj so zadostni preprostejši pristopi.* +*Ta diagram prikazuje vodnik odločitve, kdaj RAG prinaša vrednost in kdaj so dovolj preprosti pristopi.* -## Naslednji Koraki +## Naslednji koraki -**Naslednji modul:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Naslednji modul:** [04-tools - AI agenti z orodji](../04-tools/README.md) --- -**Navigacija:** [← Prejšnji: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Nazaj na glavno](../README.md) | [Naslednji: Modul 04 - Tools →](../04-tools/README.md) +**Navigacija:** [← Prejšnji: Modul 02 - Inženiring pozivov](../02-prompt-engineering/README.md) | [Nazaj na začetek](../README.md) | [Naprej: Modul 04 - Orodja →](../04-tools/README.md) --- -**Opozorilo**: -Ta dokument je bil preveden z uporabo storitve za prevajanje z umetno inteligenco [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvor nem jeziku velja za avtoritativni vir. Za pomembne informacije priporočamo strokovni človeški prevod. Ne odgovarjamo za morebitne nesporazume ali napačne razlage, ki izhajajo iz uporabe tega prevoda. +**Omejitev odgovornosti**: +Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za kritične informacije je priporočljiv strokovni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. \ No newline at end of file diff --git a/translations/sl/04-tools/README.md b/translations/sl/04-tools/README.md index 9c20f0498..aeccbdfd2 100644 --- a/translations/sl/04-tools/README.md +++ b/translations/sl/04-tools/README.md @@ -1,84 +1,84 @@ # Modul 04: AI agenti z orodji -## Kazalo - -- [Video vodič](../../../04-tools) -- [Kaj se boste naučili](../../../04-tools) -- [Predpogoji](../../../04-tools) -- [Razumevanje AI agentov z orodji](../../../04-tools) -- [Kako deluje klic orodja](../../../04-tools) - - [Definicije orodij](../../../04-tools) - - [Sprejemanje odločitev](../../../04-tools) - - [Izvedba](../../../04-tools) - - [Generiranje odgovora](../../../04-tools) - - [Arhitektura: Spring Boot samodejno povezovanje](../../../04-tools) -- [Verižna uporaba orodij](../../../04-tools) -- [Zaženite aplikacijo](../../../04-tools) -- [Uporaba aplikacije](../../../04-tools) - - [Preizkusite preprosto uporabo orodij](../../../04-tools) - - [Testirajte verižni klic orodij](../../../04-tools) - - [Oglejte si potek pogovora](../../../04-tools) - - [Eksperimentirajte z različnimi zahtevki](../../../04-tools) -- [Ključni pojmi](../../../04-tools) - - [Vzorec ReAct (razmišljanje in delovanje)](../../../04-tools) - - [Pomen opisov orodij](../../../04-tools) - - [Upravljanje seje](../../../04-tools) - - [Ravnanje z napakami](../../../04-tools) -- [Na voljo orodja](../../../04-tools) -- [Kdaj uporabljati agente na osnovi orodij](../../../04-tools) -- [Orodja proti RAG](../../../04-tools) -- [Naslednji koraki](../../../04-tools) - -## Video vodič - -Oglejte si to v živo sejo, ki pojasnjuje, kako začeti z modulom: - -AI agenti z orodji in MCP - v živo +## Kazalo vsebine + +- [Video predstavitev](#video-predstavitev) +- [Kaj se boste naučili](#kaj-se-boste-naučili) +- [Predpogoji](#predpogoji) +- [Razumevanje AI agentov z orodji](#razumevanje-ai-agentov-z-orodji) +- [Kako deluje klic orodij](#kako-deluje-klic-orodij) + - [Definicije orodij](#definicije-orodij) + - [Sprejemanje odločitev](#sprejemanje-odločitev) + - [Izvedba](#izvedba) + - [Generiranje odziva](#generiranje-odziva) + - [Arhitektura: Spring Boot samodejno povezovanje](#arhitektura-spring-boot-samodejno-povezovanje) +- [Verižna uporaba orodij](#verižna-uporaba-orodij) +- [Zagon aplikacije](#zagon-aplikacije) +- [Uporaba aplikacije](#uporaba-aplikacije) + - [Poskus enostavne uporabe orodja](#poskusite-preprosto-uporabo-orodij) + - [Testiranje verižne uporabe orodij](#preskusite-povezovanje-orodij) + - [Pregled poteka pogovora](#oglejte-si-tok-pogovora) + - [Eksperimentiranje z različnimi zahtevami](#eksperimentirajte-z-različnimi-zahtevami) +- [Ključni pojmi](#ključni-koncepti) + - [ReAct vzorec (razmišljanje in delovanje)](#react-vzorec-razmišljanje-in-ukrepanje) + - [Pomen opisov orodij](#opisi-orodij-so-pomembni) + - [Upravljanje sej](#upravljanje-seje) + - [Ravnanje z napakami](#ravnanje-z-napakami) +- [Razpoložljiva orodja](#razpoložljiva-orodja) +- [Kdaj uporabljati agente na osnovi orodij](#kdaj-uporabljati-agente-z-orodji) +- [Orodja proti RAG](#orodja-proti-rag) +- [Naslednji koraki](#naslednji-koraki) + +## Video predstavitev + +Oglejte si to prenos v živo, ki razloži, kako začeti z modulom: + +AI Agents with Tools and MCP - Live Session ## Kaj se boste naučili -Doslej ste se naučili, kako voditi pogovore z AI, učinkovito strukturirati pozive in zakoreniniti odgovore v svojih dokumentih. Toda obstaja temeljna omejitev: jezikovni modeli lahko ustvarjajo le besedilo. Ne morejo preveriti vremena, izvesti izračunov, poizvedovati po bazah podatkov ali komunicirati z zunanjimi sistemi. +Do sedaj ste se naučili, kako voditi pogovore z AI, kako učinkovito strukturirati pozive in kako utemeljiti odgovore na vaših dokumentih. Vendar pa obstaja temeljna omejitev: jezikovni modeli lahko generirajo samo besedilo. Ne morejo preveriti vremena, izvajati izračunov, poizvedovati v podatkovnih bazah ali komunicirati z zunanjimi sistemi. -Orodja to spremenijo. Z omogočanjem modelu dostopa do funkcij, ki jih lahko kliče, ga spremenite iz generatorja besedila v agenta, ki lahko izvaja dejanja. Model odloča, kdaj potrebuje orodje, katero orodje uporabiti in katere parametre posredovati. Vaša koda izvede funkcijo in vrne rezultat. Model vključi ta rezultat v svoj odgovor. +Orodja to spremenijo. Z zagotavljanjem modelu dostopa do funkcij, ki jih lahko kliče, ga spremenite iz generatorja besedila v agenta, ki lahko izvaja dejanja. Model odloča, kdaj potrebuje orodje, katero orodje uporabiti in katere parametre posredovati. Vaša koda izvede funkcijo in vrne rezultat. Model ta rezultat vključi v svoj odgovor. ## Predpogoji -- Dokončan [Modul 01 - Uvod](../01-introduction/README.md) (uvoženi Azure OpenAI viri) -- Priporočeno dokončanje prejšnjih modulov (ta modul naslavlja [RAG koncepte iz Modula 03](../03-rag/README.md) v primerjavi Orodij z RAG) -- Datoteka `.env` v korenskem imeniku z Azure poverilnicami (ustvarjena z `azd up` v Modulu 01) +- Dokončan [Modul 01 - Uvod](../01-introduction/README.md) (Azure OpenAI viri nameščeni) +- Priporočeni zaključeni prejšnji moduli (ta modul se sklicuje na [RAG koncepte iz Modula 03](../03-rag/README.md) v primerjavi Orodja proti RAG) +- Datoteka `.env` v korenski mapi z Azure poverilnicami (ustvarjena z `azd up` v Modulu 01) -> **Opomba:** Če Modul 01 še niste dokončali, sledite navodilom za uvod tam. +> **Opomba:** Če modul 01 še niste dokončali, upoštevajte najprej navodila za namestitev tam. ## Razumevanje AI agentov z orodji -> **📝 Opomba:** Izraz "agenti" v tem modulu pomeni AI asistente, izboljšane z zmožnostmi klica orodij. To se razlikuje od vzorcev **Agentic AI** (avtonomni agenti z načrtovanjem, spominom in večstopenjskim sklepanjem), ki jih bomo obravnavali v [Modulu 05: MCP](../05-mcp/README.md). +> **📝 Opomba:** Termin "agenti" v tem modulu se nanaša na AI asistente, izboljšane s funkcionalnostjo klica orodij. To se razlikuje od **Agentic AI** vzorcev (avtonomni agenti z načrtovanjem, spominom in večstopenjskim razmišljanjem), ki jih bomo obravnavali v [Modulu 05: MCP](../05-mcp/README.md). -Brez orodij lahko jezikovni model ustvarja le besedilo iz svojih podatkov. Če ga vprašaš po trenutnem vremenu, mora ugibati. Če mu daš orodja, lahko kliče vremenski API, izvaja izračune ali poizveduje v bazi podatkov — nato pa te prave rezultate vključi v svoj odgovor. +Brez orodij lahko jezikovni model generira samo besedilo na podlagi svojih učnih podatkov. Če ga vprašate za trenutno vreme, mora ugibati. Če mu daste orodja, lahko pokliče vremenski API, izvede izračune ali poizveduje v podatkovni bazi — nato te resnične rezultate vplete v svoj odgovor. -Brez orodij proti z orodji +Without Tools vs With Tools -*Brez orodij model le ugiba — z orodji kliče API-je, izvaja izračune in vrača podatke v realnem času.* +*Brez orodij model lahko samo ugiba — z orodji lahko kliče API-je, izvaja izračune in vrača podatke v realnem času.* -AI agent z orodji sledi vzorcu **Razmišljanja in Delovanja (ReAct)**. Model ne le odgovarja — razmišlja, kaj potrebuje, deluje tako, da kliče orodje, opazuje rezultat in nato odloči, ali bo ponovno ukrepal ali posredoval končni odgovor: +AI agent z orodji sledi vzorcu **Razmišljanje in Delovanje (ReAct)**. Model ne odgovarja zgolj — razmišlja o tem, kaj potrebuje, ukrepa, tako da kliče orodje, opazuje rezultat in se nato odloči, ali naj še enkrat ukrepa ali poda končni odgovor: -1. **Razmišljanje** — agent analizira uporabnikovo vprašanje in ugotovi, katere informacije so potrebne -2. **Delovanje** — agent izbere pravo orodje, pripravi pravilne parametre in ga pokliče -3. **Opazovanje** — agent prejme izhod orodja in oceni rezultat -4. **Ponovitev ali odgovor** — če je potrebnih več podatkov, agent ponovi zanko; sicer sestavi odgovor v naravnem jeziku +1. **Razmišljaj** — agent analizira uporabnikovo vprašanje in določi, katere informacije potrebuje +2. **Ukrepi** — agent izbere ustrezno orodje, generira pravilne parametre in ga pokliče +3. **Opazuj** — agent prejme izhod orodja in oceni rezultat +4. **Ponovi ali odgovori** — če je potrebnih več podatkov, agent ponovi cikel; sicer sestavi naravni jezikovni odgovor -Vzorec ReAct +ReAct Pattern -*Cikel ReAct — agent razmišlja, kaj narediti, deluje s klicem orodja, opazuje rezultat in ponavlja, dokler ne poda končnega odgovora.* +*Cikel ReAct — agent razmišlja, kaj storiti, ukrepa s klicem orodja, opazuje rezultat in ponavlja, dokler lahko ne poda končnega odgovora.* -To se zgodi samodejno. Vi definirate orodja in njihove opise. Model sam sprejema odločitve o tem, kdaj in kako jih uporabiti. +To poteka samodejno. Definirate orodja in njihove opise. Model pa sam sprejema odločitve o tem, kdaj in kako jih uporabiti. -## Kako deluje klic orodja +## Kako deluje klic orodij ### Definicije orodij [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Definirate funkcije z jasnimi opisi in specifikacijami parametrov. Model vidi te opise v sistemskem pozivu in razume, kaj vsako orodje počne. +Definirate funkcije z jasnimi opisi in specifikacijami parametrov. Model vidi te opise v svojem sistemskem pozivu in razume, kaj vsakemu orodju pripada. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Vaša logika iskanja vremena + // Vaša logika iskanja vremenskih informacij return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,137 +96,137 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Pomočnik je samodejno povezan s Spring Boot z: +// Asistent je samodejno povezan s Spring Boot z: // - ChatModel bean -// - Vse metode @Tool iz razredov @Component +// - Vse @Tool metode iz @Component razredov // - ChatMemoryProvider za upravljanje sej ``` -Diagram spodaj razčleni vsak anotacijo in pokaže, kako vsak element pomaga AI razumeti, kdaj klicati orodje in katere argumente posredovati: +Diagram spodaj razčleni vsako oznako in pokaže, kako vsak del pomaga AI razumeti, kdaj orodje poklicati in katere argumente posredovati: -Anatomija definicij orodij +Anatomy of Tool Definitions -*Anatomija definicije orodja — @Tool pove AI, kdaj ga uporabiti, @P opisuje vsak parameter, @AiService pa na začetku vse poveže.* +*Anatomija definicije orodja — @Tool pove AI, kdaj naj ga uporablja, @P opiše vsak parameter, @AiService pa vse skupaj poveže ob zagonu.* > **🤖 Preizkusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odprite [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) in vprašajte: -> - "Kako vključim pravi vremenski API kot OpenWeatherMap namesto vzorčnih podatkov?" -> - "Kaj naredi dober opis orodja, ki AI pomaga pravilno uporabiti orodje?" -> - "Kako obravnavam napake API-ja in omejitve hitrosti v izvedbah orodij?" +> - "Kako vključim pravi vremenski API, kot je OpenWeatherMap, namesto poskusnih podatkov?" +> - "Kaj naredi dober opis orodja, ki pomaga AI, da ga pravilno uporabi?" +> - "Kako v implementacijah orodij obravnavam API napake in omejitve hitrosti?" ### Sprejemanje odločitev -Ko uporabnik vpraša "Kakšno je vreme v Seattle?", model ne izbira naključno orodja. Primerja uporabnikov namen z vsakim opisom orodja, ki mu je na voljo, oceni relevantnost in izbere najboljšo ujemanje. Nato ustvari strukturiran klic funkcije s pravimi parametri — v tem primeru nastavi `location` na `"Seattle"`. +Ko uporabnik vpraša "Kako je vreme v Seattlu?", model ne izbira orodja naključno. Primerja uporabnikov namen z vsemi opisi orodij, do katerih ima dostop, oceni pomembnost vsakega in izbere najbolj ustrezno. Nato ustvari strukturiran klic funkcije z ustreznimi parametri — v tem primeru nastavi `location` na `"Seattle"`. -Če nobeno orodje ne ustreza uporabnikovi zahtevi, model odgovori na podlagi svojega znanja. Če ustreza več orodij, izbere najbolj specifično. +Če nobeno orodje ne ustreza uporabnikovemu zahtevku, model odgovarja iz lastnega znanja. Če več orodij ustreza, izbere najbolj specifično. -Kako AI odloča, katero orodje uporabiti +How the AI Decides Which Tool to Use -*Model ovrednoti vsako razpoložljivo orodje glede na uporabnikov namen in izbere najboljše ujemanje — zato so jasni, specifični opisi orodij pomembni.* +*Model oceni vsako razpoložljivo orodje glede na uporabnikov namen in izbere najbolj ustrezno — zato so jasni in specifični opisi orodij tako pomembni.* ### Izvedba [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot samodejno poveže deklarativni vmesnik `@AiService` z vsemi registriranimi orodji, LangChain4j pa samodejno izvaja klice orodij. V ozadju poteka celoten klic orodja skozi šest stopenj — od uporabnikovega vprašanja v naravnem jeziku vse do odgovora v naravnem jeziku: +Spring Boot samodejno poveže deklarativni `@AiService` vmesnik z vsemi registiranimi orodji, LangChain4j pa samodejno izvrši klice orodij. Za kulisami poteka celoten klic orodja skozi šest stopenj — od naravnega jezikovnega vprašanja uporabnika do naravnega odgovora: -Potek klica orodja +Tool Calling Flow -*Celoten potek — uporabnik postavi vprašanje, model izbere orodje, LangChain4j ga izvede, model pa vključi rezultat v naravni odgovor.* +*Celoten potek — uporabnik postavi vprašanje, model izbere orodje, LangChain4j ga izvede, model pa vstavi rezultat v naraven odgovor.* -Če ste v Modulu 00 zagnali [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java), ste to že videli v praksi — orodje `Calculator` so poklicali na enak način. Uporabniški diagram zaporedja spodaj prikazuje, kaj se je pravzaprav zgodilo med tem poskusom: +Za kulisami `AiServices` izvaja enak klicni cikel za katerokoli orodje — tukaj prikazan s preprostim `Calculator` orodjem. Sekvenčni diagram spodaj natančno prikazuje, kaj se dogaja: -Diagram zaporedja klica orodja +Tool Calling Sequence Diagram -*Zanka klica orodja iz demoja Quick Start — `AiServices` pošlje vaše sporočilo in sheme orodij LLM‑ju, LLM odgovori s klicem funkcije, kot je `add(42, 58)`, LangChain4j lokalno izvede metodo `Calculator`, rezultat pa poda nazaj za končni odgovor.* +*Cikel klica orodja — `AiServices` pošlje vaše sporočilo in sheme orodij LLM-ju, LLM odgovori s klicem funkcije, na primer `add(42, 58)`, LangChain4j lokalno izvede `Calculator` metodo in rezultat vrne za končni odgovor.* > **🤖 Preizkusite z [GitHub Copilot](https://github.com/features/copilot) Chat:** Odprite [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) in vprašajte: -> - "Kako deluje vzorec ReAct in zakaj je učinkovit za AI agente?" -> - "Kako agent odloča, katero orodje uporabiti in v kakšnem vrstnem redu?" -> - "Kaj se zgodi, če izvedba orodja ne uspe - kako naj robustno obravnavam napake?" +> - "Kako deluje ReAct vzorec in zakaj je učinkovit za AI agente?" +> - "Kako agent odloči, katero orodje uporabiti in v kakšnem vrstnem redu?" +> - "Kaj se zgodi, če izvršitev orodja spodleti — kako naj robustno upravljam napake?" -### Generiranje odgovora +### Generiranje odziva -Model prejme vremenske podatke in jih oblikuje v odgovor v naravnem jeziku za uporabnika. +Model prejme vremenske podatke in jih oblikuje v naraven odgovor za uporabnika. ### Arhitektura: Spring Boot samodejno povezovanje -Ta modul uporablja integracijo LangChain4j za Spring Boot s deklarativnimi vmesniki `@AiService`. Ob zagonu Spring Boot odkrije vsak `@Component`, ki vsebuje metode `@Tool`, vaš `ChatModel` bean in `ChatMemoryProvider` — nato vse skupaj poveže v en sam vmesnik `Assistant` brez odvečnega kode. +Ta modul uporablja LangChain4j integracijo s Spring Boot z deklarativnimi `@AiService` vmesniki. Ob zagonu Spring Boot odkrije vsak `@Component`, ki vsebuje `@Tool` metode, vaš `ChatModel` bean in `ChatMemoryProvider` — nato vse skupaj poveže v en `Assistant` vmesnik brez nepotrebne kode. -Arhitektura samodejnega povezovanja Spring Boot +Spring Boot Auto-Wiring Architecture -*Vmesnik @AiService združuje ChatModel, komponente orodij in dobavitelja pomnilnika — Spring Boot samodejno poskrbi za povezovanje.* +*Vmesnik @AiService povezuje ChatModel, komponente orodij in ponudnika pomnilnika — Spring Boot samodejno skrbi za vse povezave.* -Tu je celoten življenjski cikel zahtevka kot diagram zaporedja — od HTTP zahtevka prek kontrolerja, storitve in samodejno povezanega proxyja vse do izvedbe orodja in nazaj: +Tu je polni življenjski cikel zahtevka kot sekvenčni diagram — od HTTP zahtevka skozi kontroler, servis in samodejno povezan proxy, vse do izvedbe orodja in nazaj: -Zaporedje klica orodja v Spring Boot +Spring Boot Tool Calling Sequence -*Celoten življenjski cikel zahtevka Spring Boot — HTTP zahtevek teče skozi kontroler in storitev do samodejno povezanega proxyja Assistant, ki samodejno organizira klice LLM in orodij.* +*Celoten življenjski cikel zahtevka Spring Boot — HTTP zahtevek potuje skozi kontroler in servis do samodejno povezanega Assistant proxyja, ki samodejno orkestrira LLM in klice orodij.* -Glavne prednosti tega pristopa: +Ključne prednosti tega pristopa: -- **Spring Boot samodejno povezovanje** — ChatModel in orodja se samodejno vstavijo -- **Vzorec @MemoryId** — Samodejno upravljanje seje na osnovi pomnilnika -- **En sam primerek** — Asistent se ustvari enkrat in ponovno uporabi za boljšo zmogljivost -- **Varnost tipa pri izvedbi** — Java metode se kličejo neposredno s pretvorbo tipov -- **Večkrožna orkestracija** — Samodejno obravnava verižni klic orodij -- **Brez odvečnih kod** — Ni ročnih klicev `AiServices.builder()` ali pomnilniških HashMap +- **Spring Boot samodejno povezovanje** — ChatModel in orodja so samodejno vbrizgani +- **@MemoryId vzorec** — samodejno upravljanje spomina na osnovi sej +- **En sam primerek** — Assistant ustvarjen enkrat in ponovno uporabljen za boljšo zmogljivost +- **Izvedba z varnostjo tipov** — Java metode so kliče neposredno s pretvorbo tipov +- **Večkrožna orkestracija** — samodejno upravlja verižne klice orodij +- **Brez nepotrebne kode** — brez ročnih klicev `AiServices.builder()` ali uporabe HashMap za spomin -Alternativni pristopi (ročni `AiServices.builder()`) zahtevajo več kode in ne nudijo prednosti integracije Spring Boot. +Alternativni pristopi (ročni `AiServices.builder()`) zahtevajo več kode in zamujajo prednosti Spring Boot integracije. ## Verižna uporaba orodij -**Verižna uporaba orodij** — Prava moč agentov na osnovi orodij se pokaže, ko eno vprašanje zahteva več orodij. Vprašajte "Kakšno je vreme v Seattle v Fahrenheitu?" in agent samodejno veriženo uporabi dve orodji: najprej kliče `getCurrentWeather` za temperaturo v Celziju, nato to vrednost posreduje `celsiusToFahrenheit` za pretvorbo — vse v enem pogovornem krogu. +**Verižna uporaba orodij** — pravi potencial orodnjenih agentov se pokaže, ko eno vprašanje zahteva več orodij. Vprašajte "Kakšno je vreme v Seattlu v Fahrenheitu?" in agent samodejno veriženo uporabi dve orodji: najprej pokliče `getCurrentWeather` za temperaturo v Celziju, nato to vrednost posreduje `celsiusToFahrenheit` za pretvorbo — vse v enem pogovornem koraku. -Primer verižne uporabe orodij +Tool Chaining Example -*Verižna uporaba orodij v akciji — agent najprej kliče getCurrentWeather, nato Celsius rezultat preusmeri v celsiusToFahrenheit in poda združen odgovor.* +*Verižna uporaba orodij v akciji — agent najprej kliče getCurrentWeather, nato rezultat v Celzijih poda v celsiusToFahrenheit in poda združen odgovor.* -**Vljudno obravnavanje napak** — Vprašajte za vreme v mestu, ki ni v vzorčnih podatkih. Orodje vrne sporočilo o napaki, AI pa pojasni, da ne more pomagati, namesto da bi aplikacija zatajila. Orodja varno obravnavajo napake. Diagram spodaj primerja oba pristopa — ob pravilnem ravnanju z napakami agent prestreže izjemo in razloži, medtem ko brez tega celotna aplikacija zruši: +**Lepe napake** — povprašajte za vreme v mestu, ki ni v poskusnih podatkih. Orodje vrne sporočilo o napaki, AI pa razloži, da ne more pomagati, namesto da bi se aplikacija zrušila. Orodja prijazno poročajo o napakah. Diagram spodaj primerja oba pristopa — ob pravilnem ravnanju z napakami agent ujame izjemo in odgovori v pomoč, brez tega pa se celotna aplikacija zruši: -Potek ravnanja z napakami +Error Handling Flow -*Ko orodje zataj, agent prestreže napako in odgovori s koristnim pojasnilom namesto z zrušitvijo.* +*Ko orodje spodleti, agent ujame napako in odgovori s koristno razlago namesto z zrušitvijo.* -To se zgodi v enem krogu pogovora. Agent samostojno organizira več klicev orodij. +To se zgodi v enem samem pogovoru. Agent samostojno orkestrira več klicev orodij. -## Zaženite aplikacijo +## Zagon aplikacije -**Preverite nameščanje:** +**Preverite namestitev:** -Prepričajte se, da datoteka `.env` obstaja v korenskem imeniku z Azure poverilnicami (ustvarjena v Modulu 01). Zaženite to iz imenika modula (`04-tools/`): +Prepričajte se, da datoteka `.env` obstaja v korenski mapi z Azure poverilnicami (ustvarjena med Modulom 01). Zaženite to v mapi modula (`04-tools/`): **Bash:** ```bash -cat ../.env # Naj pokaže AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Prikazati mora AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Naj prikazuje AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Naj pokaže AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Zaženite aplikacijo:** +**Zagon aplikacije:** -> **Opomba:** Če ste že zagnali vse aplikacije z `./start-all.sh` iz korenskega imenika (kot opisano v Modulu 01), ta modul že teče na vratih 8084. Lahko preskočite ukaze za zagon spodaj in se neposredno povežete na http://localhost:8084. +> **Opomba:** Če ste že zagnali vse aplikacije s pomočjo `./start-all.sh` iz korenske mape (kot opisano v Modulu 01), ta modul že teče na vratih 8084. Ukaze za zagon spodaj lahko preskočite in neposredno obiščete http://localhost:8084. -**Možnost 1: Uporaba Spring Boot nadzorne plošče (priporočeno uporabnikom VS Code)** +**Možnost 1: Uporaba Spring Boot nadzorne plošče (priporočeno za uporabnike VS Code)** -Razvojni kontejner vsebuje razširitev Spring Boot nadzorne plošče, ki omogoča vizualno upravljanje vseh Spring Boot aplikacij. Najdete jo v vrstici z dejavnostmi na levi strani VS Code (poiščite ikono Spring Boot). +Razvojno okolje vključuje razširitev Spring Boot Dashboard, ki zagotavlja vizualni vmesnik za upravljanje vseh Spring Boot aplikacij. Najdete jo v lokacijski vrstici na levi strani VS Code (poglejte ikono Spring Boot). Iz Spring Boot nadzorne plošče lahko: - Vidite vse razpoložljive Spring Boot aplikacije v delovnem prostoru - Zaženete/ustavite aplikacije z enim klikom - V realnem času spremljate dnevnike aplikacij -- Spremljate stanje aplikacij -Preprosto kliknite gumb za predvajanje ob "tools", da zaženete ta modul, ali pa zaženite vse module hkrati. +- Spremljate status aplikacij -Tako izgleda Spring Boot nadzorna plošča v VS Code: +Preprosto kliknite gumb za predvajanje ob "tools" za zagon tega modula ali zaženite vse module hkrati. -Spring Boot Dashboard +Tako izgleda Spring Boot nadzorna plošča v VS Code: +Spring Boot Nadzorna plošča -*Spring Boot nadzorna plošča v VS Code — začnite, ustavite in spremljajte vse module na enem mestu* +*Spring Boot Nadzorna plošča v VS Code — zaženite, ustavite in spremljajte vse module na enem mestu* -**Možnost 2: Uporaba shell skript** +**Možnost 2: Uporaba ukaznih skript** Zaženite vse spletne aplikacije (moduli 01-04): @@ -242,7 +242,7 @@ cd .. # Iz korenskega imenika .\start-all.ps1 ``` -Ali pa zaženite samo ta modul: +Ali zaženite samo ta modul: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Obe skripti samodejno naložita spremenljivke okolja iz korenske datoteke `.env` in ustvarita JAR-je, če ti še ne obstajajo. +Oba skripta samodejno naložita okoljske spremenljivke iz korenske datoteke `.env` in bosta sestavila JAR-e, če ti še ne obstajajo. -> **Opomba:** Če želite pred zagonom ročno zgraditi vse module: +> **Opomba:** Če želite pred zagonom ročno sestaviti vse module: > > **Bash:** > ```bash @@ -274,7 +274,7 @@ Obe skripti samodejno naložita spremenljivke okolja iz korenske datoteke `.env` Odprite http://localhost:8084 v svojem brskalniku. -**Za ustavitev:** +**Zaustavitev:** **Bash:** ```bash @@ -292,96 +292,96 @@ cd ..; .\stop-all.ps1 # Vsi moduli ## Uporaba aplikacije -Aplikacija omogoča spletni vmesnik, kjer lahko komunicirate z AI agentom, ki ima dostop do orodij za vreme in pretvorbo temperature. Tako izgleda vmesnik — vključuje hitre začetne primere in klepetalno ploščo za pošiljanje zahtev: +Aplikacija nudi spletni vmesnik, kjer lahko komunicirate z AI agentom, ki ima dostop do orodij za vreme in pretvorbo temperatur. Tako izgleda vmesnik — vključuje hitre primere in klepetalni panel za pošiljanje zahtev: -AI Agent Tools Interface +Vmesnik orodij AI agenta -*Vmesnik AI agent orodij - hitri primeri in klepetalni vmesnik za interakcijo z orodji* +*Vmesnik orodij AI agenta - hitri primeri in klepetalni vmesnik za interakcijo z orodji* -### Poskusite enostavno uporabo orodij +### Poskusite preprosto uporabo orodij -Začnite z enostavno zahtevo: "Pretvori 100 stopinj Fahrenheita v Celzija". Agent prepozna, da potrebuje orodje za pretvorbo temperature, ga pokliče z ustreznimi parametri in vrne rezultat. Opazite, kako naravno deluje — niste določili, katero orodje uporabiti ali kako ga klicati. +Začnite z enostavno zahtevo: "Pretvori 100 stopinj Fahrenheita v Celzija." Agent prepozna, da potrebuje orodje za pretvorbo temperature, ga pokliče z ustreznimi parametri in vrne rezultat. Opazite, kako naravno deluje – niste specificirali, katero orodje uporabiti ali kako ga poklicati. -### Preizkusite povezanost orodij +### Preskusite povezovanje orodij -Zdaj poskusite nekaj bolj kompleksnega: "Kakšno je vreme v Seattleu in pretvori v Fahrenheite?" Spremljajte, kako agent deluje v korakih. Najprej pridobi vreme (ki vrne Celzije), nato prepozna potrebo po pretvorbi v Fahrenheite, pokliče orodje za pretvorbo in združi oba rezultata v en odgovor. +Poskusite kaj zahtevnejšega: "Kakšno je vreme v Seattlu in pretvori to v Fahrenheite?" Opazujte, kako agent to izvede postopoma. Najprej pridobi vreme (ki vrne Celzije), potem prepozna potrebo po pretvorbi v Fahrenheite, pokliče pretvornik in združi obe informaciji v en odgovor. -### Oglejte si potek pogovora +### Oglejte si tok pogovora -Klepetalni vmesnik ohranja zgodovino pogovora, kar omogoča večkrožne interakcije. Vidite lahko vse prejšnje zahtevke in odgovore, kar olajša sledenje pogovoru in razumevanje, kako agent gradi kontekst skozi več izmenjav. +Klepetalni vmesnik hrani zgodovino pogovorov, kar omogoča večkratne izmenjave. Vidite lahko vse prejšnje poizvedbe in odgovore, kar olajša sledenje pogovoru in razumevanje, kako agent gradi kontekst skozi številna izmenjanja. -Conversation with Multiple Tool Calls +Pogovor z več pozivi orodjem -*Večkrožni pogovor, ki prikazuje preproste pretvorbe, vremenske poizvedbe in povezovanje orodij* +*Večkratni pogovor z enostavnimi pretvorbami, vremenskimi poizvedbami in povezovanjem orodij* -### Eksperimentirajte z različnimi zahtevki +### Eksperimentirajte z različnimi zahtevami -Poskusite različne kombinacije: -- Poizvedbe o vremenu: "Kakšno je vreme v Tokiu?" -- Pretvorbe temperature: "Koliko je 25°C v kelvinih?" -- Kombinirane poizvedbe: "Preveri vreme v Parizu in povej, če je nad 20°C" +Preizkusite različne kombinacije: +- Poizvedbe za vreme: "Kakšno je vreme v Tokiu?" +- Pretvorba temperature: "Koliko je 25°C v Kelvinih?" +- Kombinirane poizvedbe: "Preveri vreme v Parizu in povej, ali je nad 20°C" -Opazite, kako agent razlaga naravni jezik in ga preslika v ustrezne klice orodij. +Opazite, kako agent interpretira naravni jezik in to preslika v ustrezne klice orodij. -## Ključni pojmi +## Ključni koncepti -### ReAct vzorec (razmišljanje in delovanje) +### ReAct vzorec (razmišljanje in ukrepanje) -Agent izmenično razmišlja (odloča, kaj storiti) in deluje (uporablja orodja). Ta vzorec omogoča avtonomno reševanje problemov namesto zgolj odgovarjanja na ukaze. +Agent izmenično razmišlja (odloča, kaj narediti) in ukrepa (uporablja orodja). Ta vzorec omogoča avtonomno reševanje problemov namesto zgolj odzivanja na ukaze. ### Opisi orodij so pomembni -Kakovost opisov vaših orodij neposredno vpliva na to, kako dobro jih agent uporablja. Jasni in specifični opisi pomagajo modelu razumeti, kdaj in kako klicati posamezno orodje. +Kakovost opisov orodij neposredno vpliva na učinkovitost njihove uporabe s strani agenta. Jasni in specifični opisi pomagajo modelu razumeti, kdaj in kako uporabiti posamezno orodje. ### Upravljanje seje -Označba `@MemoryId` omogoča avtomatsko upravljanje s pomnilnikom na osnovi seje. Vsak ID seje dobi svojo instanco `ChatMemory`, ki jo upravlja `ChatMemoryProvider` bean, tako da lahko več uporabnikov hkrati sodeluje z agentom brez mešanja njihovih pogovorov. Spodnji diagram prikazuje, kako so več uporabnikov usmerjeni v izolirane shrambe pomnilnika glede na njihove ID-je sej: +Oznaka `@MemoryId` omogoča samodejno upravljanje pomnilnika znotraj seje. Vsaka identifikacija seje dobi lastno instanco `ChatMemory`, ki jo upravlja `ChatMemoryProvider` bean, tako da lahko več uporabnikov istočasno komunicira z agentom brez mešanja pogovorov. Naslednji diagram prikazuje, kako so uporabniki usmerjeni v ločene shrambe spomina glede na njihove ID-je sej: -Session Management with @MemoryId +Upravljanje sej z @MemoryId -*Vsak ID seje ustreza izolirani zgodovini pogovora — uporabniki ne vidijo sporočil drug drugega.* +*Vsak ID seje ima ločeno zgodovino pogovorov — uporabniki nikoli ne vidijo sporočil drugih.* -### Obdelava napak +### Ravnanje z napakami -Orodja lahko odpovejo — API-ji potečejo, parametri so lahko neveljavni, zunanji servisi so nedostopni. Produkcijski agenti potrebujejo obdelavo napak, da model lahko pojasni težave ali poskusi alternative namesto, da bi aplikacija absolutno padla. Ko orodje vrže izjemo, jo LangChain4j ujame in sporočilo o napaki prenese nazaj modelu, ki lahko nato v naravnem jeziku pojasni problem. +Orodja lahko odpovejo — API-ji potečejo, parametri so lahko neveljavni, zunanje storitve odpovedo. Produkcijski agenti potrebujejo ravnanje z napakami, da lahko model pojasni težave ali poskusi alternative namesto, da se celotna aplikacija zruši. Ko orodje vrže izjemo, jo LangChain4j ujame in sporočilo o napaki posreduje nazaj modelu, ki lahko težavo nato pojasni v naravnem jeziku. ## Razpoložljiva orodja -Spodnji diagram prikazuje širok ekosistem orodij, ki jih lahko ustvarite. Ta modul prikazuje vremenska in temperaturna orodja, a isti vzorec `@Tool` deluje za katerokoli Java metodo — od poizvedb po podatkovnih bazah do obdelave plačil. +Spodnji diagram prikazuje širok ekosistem orodij, ki jih lahko zgradite. Ta modul prikazuje orodja za vreme in temperaturo, a enak vzorec `@Tool` deluje za katerokoli Java metodo — od poizvedb v bazi do obdelave plačil. -Tool Ecosystem +Ekosistem orodij -*Katera koli Java metoda z oznako @Tool postane na voljo za AI — vzorec se razteza na baze podatkov, API-je, e-pošto, datotečne operacije in še več.* +*Katera koli Java metoda, označena z @Tool, postane dostopna AI-ju — vzorec se razširi na baze podatkov, API-je, elektronsko pošto, datotečne operacije in še več.* -## Kdaj uporabiti agente, ki temeljijo na orodjih +## Kdaj uporabljati agente z orodji -Ne vsaka zahteva potrebuje orodja. Odločitev je odvisna od tega, ali AI rabi interakcijo z zunanjimi sistemi ali lahko odgovori iz lastnega znanja. Spodnji vodič povzema, kdaj orodja dodajo vrednost in kdaj niso potrebna: +Ne vsaka zahteva potrebuje orodja. Odločitev je, ali AI mora komunicirati z zunanjimi sistemi ali lahko odgovori na podlagi lastnega znanja. Naslednji vodič povzema, kdaj orodja prinašajo vrednost in kdaj niso potrebna: -When to Use Tools +Kdaj uporabljati orodja -*Hiter vodič za odločanje — orodja so za podatke v realnem času, izračune in dejanja; splošno znanje in ustvarjalne naloge jih ne potrebujejo.* +*Hitri vodič za odločanje — orodja so za podatke v realnem času, izračune in ukrepe; splošno znanje in ustvarjalne naloge jih ne potrebujejo.* ## Orodja proti RAG -Moduli 03 in 04 oba razširjata zmožnosti AI, a na povsem drugačne načine. RAG modelu omogoča dostop do **znanja** z iskanjem dokumentov. Orodja modelu omogočajo izvajanje **dejanj** z klici funkcij. Spodnji diagram primerja ti dve pristopi vzporedno — od načina delovanja do kompromisov med njima: +Moduli 03 in 04 oba razširjata zmožnosti AI, vendar na temeljno različne načine. RAG modelu omogoča dostop do **znanja** z iskanjem v dokumentih. Orodja omogočajo modelu, da sprejema **ukrepe** z izvajanjem funkcij. Spodnji diagram primerja oba pristopa — od tega, kako vsak potek dela, do kompromisov med njima: -Tools vs RAG Comparison +Primerjava Orodij in RAG -*RAG pridobiva informacije iz statičnih dokumentov — orodja izvajajo dejanja in pridobivajo dinamične, aktualne podatke. Veliko produkcijskih sistemov združuje obe.* +*RAG pridobiva informacije iz statičnih dokumentov — Orodja izvajajo ukrepe in pridobivajo dinamične, trenutne podatke. Veliko produkcijskih sistemov združuje oba.* -V praksi mnogi produkcijski sistemi združujejo oba pristopa: RAG za podlago odgovorov v vaši dokumentaciji in Orodja za pridobivanje živih podatkov ali izvajanje operacij. +V praksi številni produkcijski sistemi združujejo oba pristopa: RAG za utemeljitev odgovorov v vaši dokumentaciji in Orodja za pridobivanje živih podatkov ali izvajanje operacij. ## Naslednji koraki -**Naslednji modul:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Naslednji modul:** [05-mcp - Protokol konteksta modela (MCP)](../05-mcp/README.md) --- -**Navigacija:** [← Prejšnji: Modul 03 - RAG](../03-rag/README.md) | [Nazaj na začetek](../README.md) | [Naslednji: Modul 05 - MCP →](../05-mcp/README.md) +**Navigacija:** [← Prejšnji: Modul 03 - RAG](../03-rag/README.md) | [Nazaj na glavno](../README.md) | [Naslednji: Modul 05 - MCP →](../05-mcp/README.md) --- **Omejitev odgovornosti**: -Ta dokument je bil preveden z uporabo storitve za prevajanje z umetno inteligenco [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, upoštevajte, da lahko avtomatizirani prevodi vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvornem jeziku velja za avtoritativni vir. Za ključne informacije priporočamo profesionalni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. +Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za kritične informacije je priporočljiv strokovni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. \ No newline at end of file diff --git a/translations/sl/README.md b/translations/sl/README.md index cafc66b8b..548495d26 100644 --- a/translations/sl/README.md +++ b/translations/sl/README.md @@ -2,18 +2,18 @@ # LangChain4j za začetnike -Tečaj za gradnjo AI aplikacij z LangChain4j in Azure OpenAI GPT-5.2, od osnovnega klepeta do AI agentov. +Tečaj za izgradnjo AI aplikacij z LangChain4j in Azure OpenAI GPT-5.2, od osnovnega klepeta do AI agentov. ### 🌐 Podpora za več jezikov -#### Podprto preko GitHub Action (avtomatizirano in vedno posodobljeno) +#### Podprto preko GitHub Actions (avtomatizirano in vedno posodobljeno) -[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](./README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) +[Arabščina](../ar/README.md) | [Bengalščina](../bn/README.md) | [Bolgarščina](../bg/README.md) | [Burmščina (Mjanmar)](../my/README.md) | [Kitajščina (poenostavljena)](../zh-CN/README.md) | [Kitajščina (klasična, Hong Kong)](../zh-HK/README.md) | [Kitajščina (klasična, Macao)](../zh-MO/README.md) | [Kitajščina (klasična, Tajvan)](../zh-TW/README.md) | [Hrvaščina](../hr/README.md) | [Češčina](../cs/README.md) | [Danščina](../da/README.md) | [Nizozemščina](../nl/README.md) | [Estonščina](../et/README.md) | [Finščina](../fi/README.md) | [Francoščina](../fr/README.md) | [Nemščina](../de/README.md) | [Grščina](../el/README.md) | [Hebrejščina](../he/README.md) | [Hindijščina](../hi/README.md) | [Madžarščina](../hu/README.md) | [Indonezijščina](../id/README.md) | [Italijanščina](../it/README.md) | [Japonščina](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korejščina](../ko/README.md) | [Litvanščina](../lt/README.md) | [Malajščina](../ms/README.md) | [Malajalščina](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalščina](../ne/README.md) | [Nigerijski pidžin](../pcm/README.md) | [Norveščina](../no/README.md) | [Perzijščina (Farsi)](../fa/README.md) | [Poljščina](../pl/README.md) | [Portugalščina (Brazilija)](../pt-BR/README.md) | [Portugalščina (Portugalska)](../pt-PT/README.md) | [Pandžabski (Gurmukhi)](../pa/README.md) | [Romunščina](../ro/README.md) | [Ruščina](../ru/README.md) | [Srbščina (cirilica)](../sr/README.md) | [Slovaščina](../sk/README.md) | [Slovenščina](./README.md) | [Španščina](../es/README.md) | [Svahili](../sw/README.md) | [Švedščina](../sv/README.md) | [Tagalog (Filipinski)](../tl/README.md) | [Tamilščina](../ta/README.md) | [Telugujščina](../te/README.md) | [Tajščina](../th/README.md) | [Turščina](../tr/README.md) | [Ukrajinščina](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamščina](../vi/README.md) -> **Raje klonirate lokalno?** +> **Raje želite prenesti lokalno?** > -> To repozitorij vsebuje več kot 50 jezikovnih prevodov, kar znatno poveča velikost prenosa. Če želite klonirati brez prevodov, uporabite sparse checkout: +> Ta repozitorij vsebuje prevode v več kot 50 jezikih, kar znatno povečuje velikost prenosa. Če želite klonirati brez prevodov, uporabite sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,26 +29,25 @@ Tečaj za gradnjo AI aplikacij z LangChain4j in Azure OpenAI GPT-5.2, od osnovne > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> To vam omogoča, da dobite vse, kar potrebujete za dokončanje tečaja z veliko hitrejšim prenosom. +> Tako boste dobili vse potrebno za dokončanje tečaja z veliko hitrejšim prenosom. -## Kazalo vsebine +## Kazalo -1. [Hitri začetek](00-quick-start/README.md) - Začnite z LangChain4j -2. [Uvod](01-introduction/README.md) - Spoznajte osnove LangChain4j -3. [Oblikovanje povpraševanja](02-prompt-engineering/README.md) - Obvladajte učinkovito oblikovanje povpraševanja -4. [RAG (Generiranje z iskanjem)](03-rag/README.md) - Gradite inteligentne sisteme na osnovi znanja -5. [Orodja](04-tools/README.md) - Integrirajte zunanja orodja in preproste asistente -6. [MCP (Protokol konteksta modela)](05-mcp/README.md) - Delajte s Protokolom konteksta modela (MCP) in Agentskimi moduli +1. [Uvod](01-introduction/README.md) - Spoznajte osnove LangChain4j +2. [Ustvarjanje pozivov](02-prompt-engineering/README.md) - Obvladajte učinkovito načrtovanje pozivov +3. [RAG (Generiranje s pridobivanjem)](03-rag/README.md) - Ustvarite inteligentne sisteme znanja +4. [Orodja](04-tools/README.md) - Integrirajte zunanja orodja in preproste asistente +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Delajte z Model Context Protocol (MCP) in agentnimi moduli -### Video vodenja +### Video predstavitve -Vsak modul ima spremljevalno živo sejo, kjer korak za korakom obravnavamo koncepte in kodo. +Vsak modul ima spremljajočo sejo v živo, kjer postopoma razložimo koncepte in kodo. | Modul | Video | |--------|-------| | 01 - Uvod | [Začetek z LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Oblikovanje povpraševanja | [Oblikovanje povpraševanja z LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 02 - Ustvarjanje pozivov | [Ustvarjanje pozivov z LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG z LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Orodja & 05 - MCP | [AI agenti z orodji in MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | @@ -56,66 +55,67 @@ Vsak modul ima spremljevalno živo sejo, kjer korak za korakom obravnavamo konce ## Učna pot -**Nova v LangChain4j?** Oglejte si [Slovarček](docs/GLOSSARY.md) za definicije ključnih izrazov in konceptov. +**Ste novinec v LangChain4j?** Oglejte si [Slovarček](docs/GLOSSARY.md) za definicije ključnih izrazov in konceptov. -> **Hitri začetek** +> **Hiter začetek** -1. Razvežite ta repozitorij v svoj GitHub račun -2. Kliknite **Code** → zavihek **Codespaces** → **...** → **New with options...** -3. Uporabite privzete nastavitve – izbralo bo razvojno posodo, ustvarjeno za ta tečaj +1. Razvijte ta repozitorij na svoj GitHub račun +2. Kliknite **Code** → zavihek **Codespaces** → **...** → **Nov z možnostmi...** +3. Uporabite privzete nastavitve – izbral bo Development container, ustvarjen za ta tečaj 4. Kliknite **Create codespace** -5. Počakajte 5-10 minut, da je okolje pripravljeno -6. Pojdite neposredno na [Hitri začetek](./00-quick-start/README.md) in začnite! +5. Počakajte 5-10 minut, da se okolje pripravi +6. Neposredno skočite na [Uvod](./01-introduction/README.md) in začnite! -Po končanih modulih raziskujte [Vodnik za testiranje](docs/TESTING.md), da si ogledate koncepte testiranja LangChain4j v praksi. +Po zaključku modulov raziščite [Vodnik za testiranje](docs/TESTING.md), da si ogledate koncepte testiranja LangChain4j v praksi. -> **Opomba:** Ta usposabljanje uporablja tako GitHub modele kot Azure OpenAI. Modul [Hitri začetek](00-quick-start/README.md) uporablja GitHub modele (brez potrebe po naročnini na Azure), medtem ko moduli 1-5 uporabljajo Azure OpenAI. Začnite z [BREZPLAČNIM Azure računom](https://aka.ms/azure-free-account), če ga še nimate. +> **Opomba:** Ta trening uporablja Azure OpenAI. Začnite z [BREZPLAČNIM Azure računom](https://aka.ms/azure-free-account), če ga še nimate. -## Učenje s pomočjo GitHub Copilot +## Učenje z GitHub Copilot -Za hiter začetek programiranja odprite ta projekt v GitHub Codespace ali v lokalnem IDE z uporabo priloženega devcontainerja. Devcontainer, uporabljen v tem tečaju, je predkonfiguriran z GitHub Copilot za AI so-pisanje kode. +Za hiter začetek programiranja odprite ta projekt v GitHub Codespace ali v svojem lokalnem IDE z zagotovljenim devcontainerjem. Devcontainer, uporabljen v tem tečaju, je prednastavljen z GitHub Copilot za AI programiranje v paru. -Vsak primer kode vsebuje predlagana vprašanja, ki jih lahko zastavite GitHub Copilotu za poglobljeno razumevanje. Poiščite oznake 💡/🤖 v: +Vsak primer kode vključuje predlagana vprašanja, ki jih lahko zastavite GitHub Copilotu za poglobitev razumevanja. Poiščite oznake 💡/🤖 v: -- **Glavah Java datotek** - vprašanja specifična za vsak primer -- **README-jih modulov** - raziskovalna vprašanja po primerih kode +- **Glavah Java datotek** - Vprašanja specifična za vsak primer +- **README modulov** - Spodbudni pozivi za raziskovanje po primerih kode -**Kako uporabljati:** Odprite katerokoli datoteko s kodo in vprašajte Copilota predlagana vprašanja. Ima celoten kontekst kode in lahko pojasni, razširi in predlaga alternative. +**Kako uporabljati:** Odprite poljubno datoteko kode in zastavite Copilotu predlagana vprašanja. Ima popoln kontekst kode in lahko razloži, razširi ter predlaga alternative. -Želite izvedeti več? Oglejte si [Copilot za AI so-pisanje kode](https://aka.ms/GitHubCopilotAI). +Želite izvedeti več? Oglejte si [Copilot za AI programiranje v paru](https://aka.ms/GitHubCopilotAI). ## Dodatni viri ### LangChain -[![LangChain4j za začetnike](https://img.shields.io/badge/LangChain4j%20za%20začetnike-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js za začetnike](https://img.shields.io/badge/LangChain.js%20za%20začetnike-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain za začetnike](https://img.shields.io/badge/LangChain%20za%20začetnike-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j za začetnike](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js za začetnike](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain za začetnike](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agent -[![AZD za začetnike](https://img.shields.io/badge/AZD%20za%20začetnike-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI za začetnike](https://img.shields.io/badge/Edge%20AI%20za%20začetnike-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP za začetnike](https://img.shields.io/badge/MCP%20za%20začetnike-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI agenti za začetnike](https://img.shields.io/badge/AI%20agenti%20za%20začetnike-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Agenti +[![AZD za začetnike](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI za začetnike](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP za začetnike](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI Agent za začetnike](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Serija Generativne AI -[![Generativna AI za začetnike](https://img.shields.io/badge/Generativna%20AI%20za%20začetnike-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generativna AI (.NET)](https://img.shields.io/badge/Generativna%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generativna AI (Java)](https://img.shields.io/badge/Generativna%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generativna AI (JavaScript)](https://img.shields.io/badge/Generativna%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +[![Generativna AI za začetnike](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generativna AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generativna AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generativna AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- ### Osnovno učenje -[![ML za začetnike](https://img.shields.io/badge/ML%20za%20začetnike-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Podatkovna znanost za začetnike](https://img.shields.io/badge/Podatkovna%20znanost%20za%20začetnike-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI za začetnike](https://img.shields.io/badge/AI%20za%20začetnike-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![ML za začetnike](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Podatkovna znanost za začetnike](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI za začetnike](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Kibernetska varnost za začetnike](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + [![Spletni razvoj za začetnike](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT za začetnike](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR razvoj za začetnike](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -123,28 +123,28 @@ Vsak primer kode vsebuje predlagana vprašanja, ki jih lahko zastavite GitHub Co --- ### Serija Copilot -[![Copilot za AI programiranje v paru](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot za AI sočasno programiranje](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![Copilot za C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot avantura](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Pustolovščina Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## Iskanje pomoči +## Pridobivanje pomoči -Če zataknete ali imate kakršnakoli vprašanja o izdelavi AI aplikacij, se pridružite: +Če se zataknete ali imate kakršnakoli vprašanja o ustvarjanju AI aplikacij, se pridružite: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Če imate povratne informacije o izdelku ali napake med razvojem, obiščite: +Če imate povratne informacije o izdelku ali napake med izdelavo, obiščite: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Licenca -Licenca MIT - podrobnosti si oglejte v datoteki [LICENSE](../../LICENSE). +Licenca MIT - Podrobnosti si oglejte v datoteki [LICENSE](../../LICENSE). --- -**Omejitev odgovornosti**: -Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas opozarjamo, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba razumeti kot avtoritativni vir. Za kritične informacije priporočamo strokovni človeški prevod. Za morebitne nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda, ne prevzemamo nobene odgovornosti. +**Omejitev odgovornosti**: +Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za kritične informacije je priporočljiv strokovni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. \ No newline at end of file diff --git a/translations/sl/docs/GLOSSARY.md b/translations/sl/docs/GLOSSARY.md index 7ead095f0..818b32b49 100644 --- a/translations/sl/docs/GLOSSARY.md +++ b/translations/sl/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## Kazalo -- [Temeljni pojmi](../../../docs) -- [Komponente LangChain4j](../../../docs) -- [AI/ML pojmi](../../../docs) -- [Varovala](../../../docs) -- [Inženiring pozivov](../../../docs) -- [RAG (generiranje z iskanjem)](../../../docs) -- [Agentje in orodja](../../../docs) -- [Agentski modul](../../../docs) -- [Protokol konteksta modela (MCP)](../../../docs) -- [Azure storitve](../../../docs) -- [Testiranje in razvoj](../../../docs) +- [Osnovni pojmi](#osnovni-pojmi) +- [Komponente LangChain4j](#komponente-langchain4j) +- [Pojmi AI/ML](#pojmi-aiml) +- [Zaščitni mehanizmi](#zaščitni-mehanizmi) +- [Inženiring pozivov](#prompt-engineering---module-02) +- [RAG (Generiranje z nadgradnjo pridobivanja)](#rag-retrieval-augmented-generation---module-03) +- [Agentje in orodja](#agents-and-tools---module-04) +- [Agentni modul](#agentic-module---module-05) +- [Protokol modelnega konteksta (MCP)](#model-context-protocol-mcp---module-05) +- [Azure storitve](#azure-services---module-01) +- [Testiranje in razvoj](#testing-and-development---testing-guide) -Hiter pregled izrazov in pojmov, uporabljenih v celotnem tečaju. +Hiter pregled pojmov in konceptov, ki se uporabljajo skozi celoten tečaj. -## Temeljni pojmi +## Osnovni pojmi -**AI agent** - sistem, ki uporablja AI za razmišljanje in samostojno delovanje. [Modul 04](../04-tools/README.md) +**AI agent** - Sistem, ki uporablja AI za samostojno razmišljanje in delovanje. [Modul 04](../04-tools/README.md) -**Veriga** - zaporedje operacij, kjer izhod služi kot vhod za naslednji korak. +**Veriga** - Zaporedje operacij, kjer izhod vstopa v naslednji korak. -**Razbijanje na kose** - razdeljevanje dokumentov na manjše dele. Običajno: 300-500 tokenov z prekrivanjem. [Modul 03](../03-rag/README.md) +**Razbitje na dele** - Razbijanje dokumentov na manjše koščke. Tipično: 300-500 tokenov s prekrivanjem. [Modul 03](../03-rag/README.md) -**Kontekstno okno** - največje število tokenov, ki jih model lahko obdela. GPT-5.2: 400K tokenov (do 272K vhod, 128K izhod). +**Kontekstno okno** - Največje število tokenov, ki jih model lahko obdela. GPT-5.2: 400K tokenov (do 272K vhod, 128K izhod). -**Vdelave** - numerične vektorje, ki predstavljajo pomen besedila. [Modul 03](../03-rag/README.md) +**Vdelave** - Numerični vektorji, ki predstavljajo pomen besedila. [Modul 03](../03-rag/README.md) -**Klic funkcije** - model generira strukturirane zahteve za klicanje zunanjih funkcij. [Modul 04](../04-tools/README.md) +**Klic funkcije** - Model ustvari strukturirane zahteve za klic zunanjih funkcij. [Modul 04](../04-tools/README.md) -**Halucinacija** - ko modeli generirajo napačne, a verjetne informacije. +**Halucinacija** - Ko modeli generirajo napačne, a verjetne informacije. -**Poziv** - besedilni vhod v jezikovni model. [Modul 02](../02-prompt-engineering/README.md) +**Poziv** - Besedilni vhod za jezikovni model. [Modul 02](../02-prompt-engineering/README.md) -**Semantično iskanje** - iskanje po pomenu z uporabo vdelav, ne ključnih besed. [Modul 03](../03-rag/README.md) +**Semantično iskanje** - Iskanje po pomenu z uporabo vdelav, ne ključnih besed. [Modul 03](../03-rag/README.md) -**Stanje s spominom vs brez spomina** - brez spomina: brez zgodovine pogovora. S spominom: ohranja zgodovino pogovora. [Modul 01](../01-introduction/README.md) +**Stanje z in brez pomnilnika** - Brezpomnilnično: ni spomina. S pomnilnikom: ohranja zgodovino pogovora. [Modul 01](../01-introduction/README.md) -**Tokeni** - osnovne besedilne enote, ki jih modeli obdelujejo. Vplivajo na stroške in omejitve. [Modul 01](../01-introduction/README.md) +**Tokeni** - Osnovne enote besedila, ki jih modeli obdelujejo. Vplivajo na stroške in omejitve. [Modul 01](../01-introduction/README.md) -**Verižna uporaba orodij** - zaporedno izvajanje orodij, kjer izhod informira naslednji klic. [Modul 04](../04-tools/README.md) +**Verižna uporaba orodij** - Zaporedno izvajanje orodij, kjer izhod vpliva na naslednji klic. [Modul 04](../04-tools/README.md) ## Komponente LangChain4j -**AiServices** - ustvarja varne vtipizirane vmesnike za AI storitve. +**AiServices** - Ustvarja tipno varne vmesnike AI storitev. -**OpenAiOfficialChatModel** - združeni odjemalec za OpenAI in Azure OpenAI modele. +**OpenAiOfficialChatModel** - Enoten odjemalec za modele OpenAI in Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - ustvarja vdelave z uporabo uradnega OpenAI odjemalca (podpira tako OpenAI kot Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Ustvarja vdelave z uradnim odjemalcem OpenAI (podpira OpenAI in Azure OpenAI). -**ChatModel** - osrednji vmesnik za jezikovne modele. +**ChatModel** - Osnovni vmesnik za jezikovne modele. -**ChatMemory** - ohranja zgodovino pogovora. +**ChatMemory** - Ohranja zgodovino pogovora. -**ContentRetriever** - išče relevantne kose dokumentov za RAG. +**ContentRetriever** - Najde relevantne dele dokumenta za RAG. -**DocumentSplitter** - razdeli dokumente na dele. +**DocumentSplitter** - Razbija dokumente na dele. -**EmbeddingModel** - pretvori besedilo v numerične vektorje. +**EmbeddingModel** - Pretvori besedilo v numerične vektorje. -**EmbeddingStore** - shrani in pridobi vdelave. +**EmbeddingStore** - Shrani in odpira vdelave. -**MessageWindowChatMemory** - ohranja drsno okno zadnjih sporočil. +**MessageWindowChatMemory** - Ohranja drseče okno nedavnih sporočil. -**PromptTemplate** - ustvarja znova uporabne pozive z označevalci `{{variable}}`. +**PromptTemplate** - Ustvarja ponovno uporabne pozive z `{{variable}}` mestnimi označevalci. -**TextSegment** - kos besedila z metapodatki. Uporablja se v RAG. +**TextSegment** - Besedilni kos z metapodatki. Uporablja se v RAG. -**ToolExecutionRequest** - predstavlja zahtevo za izvajanje orodja. +**ToolExecutionRequest** - Predstavlja zahtevo za izvedbo orodja. -**UserMessage / AiMessage / SystemMessage** - tipi sporočil v pogovoru. +**UserMessage / AiMessage / SystemMessage** - Vrste sporočil v pogovoru. -## AI/ML pojmi +## Pojmi AI/ML -**Učenje z nekaj primeri** - zagotovitev primerov v pozivih. [Modul 02](../02-prompt-engineering/README.md) +**Učenje z malo primeri** - Zagotavljanje primerov v pozivih. [Modul 02](../02-prompt-engineering/README.md) -**Veliki jezikovni model (LLM)** - AI modeli, usposobljeni na ogromnih količinah besedilnih podatkov. +**Veliki jezikovni model (LLM)** - AI modeli, trenirani na ogromnih količinah besedil. -**Prizadevanje za razumen odgovor** - parameter GPT-5.2 za nadzor globine razmišljanja. [Modul 02](../02-prompt-engineering/README.md) +**Napor razmišljanja** - Parameter GPT-5.2, ki nadzoruje globino razmišljanja. [Modul 02](../02-prompt-engineering/README.md) -**Temperatura** - uravnava naključnost izhoda. Nizka = deterministična, visoka = ustvarjalna. +**Temperatura** - Nadzoruje naključnost izhoda. Nizka=deterministična, visoka=kreativna. -**Vektorska baza podatkov** - specializirana baza za vdelave. [Modul 03](../03-rag/README.md) +**Vektorska baza podatkov** - Specializirana baza za vdelave. [Modul 03](../03-rag/README.md) -**Učenje brez primerov** - izvajanje nalog brez primerov. [Modul 02](../02-prompt-engineering/README.md) +**Učenje brez primerov** - Izvajanje nalog brez primerov. [Modul 02](../02-prompt-engineering/README.md) -## Varovala - [Modul 00](../00-quick-start/README.md) +## Zaščitni mehanizmi -**Obramba v globino** - večplastni varnostni pristop, ki združuje varovala na ravni aplikacij s filtri ponudnika. +**Zmogljiva zaščita** - Večplastni varnostni pristop, ki združuje zaščite na ravni aplikacije z varnostnimi filtri ponudnikov. -**Trda blokada** - ponudnik vrže HTTP 400 napako za resne kršitve vsebine. +**Trda blokada** - Ponudnik vrže napako HTTP 400 za hujše kršitve vsebine. -**InputGuardrail** - vmesnik LangChain4j za preverjanje vhodnih uporabniških podatkov preden dosežejo LLM. Prihrani stroške in zakasnitve z zgodnjo blokado škodljivih pozivov. +**InputGuardrail** - LangChain4j vmesnik za preverjanje uporabniškega vnosa pred posredovanjem LLM-ju. Prihrani stroške in latenco z zgodnjim blokiranjem škodljivih pozivov. -**InputGuardrailResult** - tip vrnjene vrednosti za preverjanje varovala: `success()` ali `fatal("razlog")`. +**InputGuardrailResult** - Vrsta vrnitve preverjanja varovalke: `success()` ali `fatal("reason")`. -**OutputGuardrail** - vmesnik za preverjanje AI odgovorov preden se vrnejo uporabnikom. +**OutputGuardrail** - Vmesnik za preverjanje AI odgovorov pred vračanjem uporabnikom. -**Varnostni filtri ponudnika** - vgrajeni filtri vsebine pri AI ponudnikih (npr. GitHub modeli), ki zaznajo kršitve na ravni API. +**Provider Safety Filters** - Vgrajeni filtri vsebine AI ponudnikov (npr. Azure OpenAI), ki zaznavajo kršitve na ravni API-ja. -**Nežen zavrnitev** - model vljudno odkloni odgovor brez izmeta napake. +**Mehki odklon** - Model vljudno zavrne odgovor brez vrženja napake. ## Inženiring pozivov - [Modul 02](../02-prompt-engineering/README.md) -**Razmišljanje po korakih** - postopno razmišljanje za boljšo natančnost. +**Veriga razmišljanja** - Korak-po-korak razmišljanje za boljšo natančnost. -**Omejen izhod** - izvajanje specifične oblike ali strukture. +**Omejen izhod** - Uveljavljanje specifične oblike ali strukture. -**Visoka zagnanost** - vzorec GPT-5.2 za temeljito razmišljanje. +**Visoka vnema** - Vzorec GPT-5.2 za temeljito razmišljanje. -**Nizka zagnanost** - vzorec GPT-5.2 za hitre odgovore. +**Nizka vnema** - Vzorec GPT-5.2 za hitre odgovore. -**Večkratni pogovor** - ohranjanje konteksta skozi izmenjave. +**Večvrstni pogovor** - Ohranjanje konteksta čez menjave. -**Pozivanje glede na vlogo** - nastavitev osebnosti modela preko sistemskih sporočil. +**Pozivanje na podlagi vloge** - Nastavitev osebnosti modela preko sistemskih sporočil. -**Samo-refleksija** - model oceni in izboljša lasten izhod. +**Samoocena** - Model oceni in izboljšuje svoj izhod. -**Strukturirana analiza** - fiksiran okvir za ocenjevanje. +**Strukturirana analiza** - Fiksni okvir za ocenjevanje. **Vzorec izvajanja naloge** - Načrtuj → Izvedi → Povzemi. -## RAG (generiranje z iskanjem) - [Modul 03](../03-rag/README.md) +## RAG (Generiranje z nadgradnjo pridobivanja) - [Modul 03](../03-rag/README.md) -**Procesna veriga za dokumente** - Nalaganje → razbijanje → vdelava → shranjevanje. +**Procesna veriga za dokumente** - Naloži → razdeli → vdelaj → shrani. -**Shranjevanje vdelav v pomnilniku** - neperzistentno shranjevanje za testiranje. +**Shranjevanje vdelav v spominu** - Ne-persistenčno shranjevanje za testiranje. -**RAG** - združuje iskanje z generiranjem za podlago odgovorov. +**RAG** - Združuje pridobivanje z generiranjem za utemeljitev odgovorov. -**Ocena podobnosti** - mera (0-1) semantične podobnosti. +**Ocena podobnosti** - Merilo (0-1) semantične podobnosti. -**Vzorčni vir** - metapodatki o pridobljeni vsebini. +**Referenca vira** - Metapodatki o pridobljeni vsebini. ## Agentje in orodja - [Modul 04](../04-tools/README.md) -**@Tool anotacija** - označi Java metode kot orodja, ki jih lahko kliče AI. +**@Tool oznaka** - Označuje Java metode kot orodja, dostopna AI-ju. **ReAct vzorec** - Razmišljaj → Ukrepaj → Opazuj → Ponovi. -**Upravljanje sej** - ločeni konteksti za različne uporabnike. +**Upravljanje sej** - Ločeni konteksti za različne uporabnike. -**Orodje** - funkcija, ki jo lahko kliče AI agent. +**Orodje** - Funkcija, ki jo AI agent lahko pokliče. -**Opis orodja** - dokumentacija namena in parametrov orodja. +**Opis orodja** - Dokumentacija namena orodja in parametrov. -## Agentski modul - [Modul 05](../05-mcp/README.md) +## Agentni modul - [Modul 05](../05-mcp/README.md) -**@Agent anotacija** - označi vmesnike kot AI agente z deklarativno definicijo vedenja. +**@Agent oznaka** - Označuje vmesnike kot AI agente z deklarativno definicijo vedenja. -**Agent poslušalec** - vtičnica za spremljanje izvajanja agenta preko `beforeAgentInvocation()` in `afterAgentInvocation()`. +**Agentni poslušalec** - Hook za spremljanje izvajanja agentov preko `beforeAgentInvocation()` in `afterAgentInvocation()`. -**Agentski obseg** - deljeni spomin, kjer agenti shranjujejo izhode z uporabo `outputKey` za nadaljnjo porabo. +**Agentni obseg** - Deljeni pomnilnik, kjer agenti shranjujejo rezultate z uporabo `outputKey` za nadaljnjo uporabo. -**AgenticServices** - tovarna za ustvarjanje agentov z `agentBuilder()` in `supervisorBuilder()`. +**AgenticServices** - Tovarna za ustvarjanje agentov z `agentBuilder()` in `supervisorBuilder()`. -**Pogojni potek dela** - usmerjanje na podlagi pogojev do različnih specializiranih agentov. +**Pogojni potek dela** - Usmeritev na različne specializirane agente glede na pogoje. -**Človek v zanki** - vzorec poteka dela, ki dodaja človeške kontrole za odobritev ali pregled vsebine. +**Človek v zanki** - Vzorec poteka dela z dodanimi človekovimi kontrolnimi točkami za odobritev ali pregled vsebine. -**langchain4j-agentic** - Maven odvisnost za deklarativno gradnjo agentov (eksperimentalno). +**langchain4j-agentic** - Maven odvisnost za deklarativno izdelavo agentov (eksperimentalno). -**Zanka potek dela** - ponavljanje izvajanja agenta, dokler ni izpolnjen pogoj (npr. ocena kakovosti ≥ 0,8). +**Zanke potek dela** - Iterativno izvajanje agenta dokler ni dosežen pogoj (npr. ocena kakovosti ≥ 0,8). -**outputKey** - parameter anotacije agenta, ki določa, kam se rezultati shranijo v Agentskem obsegu. +**outputKey** - Parameter oznake agenta, ki določa, kje se rezultati shranjujejo v agentnem obsegu. -**Vzporedni potek dela** - hkratno izvajanje več agentov za neodvisne naloge. +**Vzporedni potek dela** - Sočasno izvajanje več agentov za neodvisne naloge. -**Strategija odziva** - kako nadzornik oblikuje končni odgovor: ZADNJI, POVZETEK ali OCENJEN. +**Strategija odgovora** - Kako nadzornik oblikuje končni odgovor: ZADNJI, POVZETEK ali OCENJENO. -**Zaporedni potek dela** - izvajanje agentov po vrsti, kjer izhod teče v naslednji korak. +**Zaporedni potek dela** - Izvedba agentov po vrsti, kjer izhod teče v naslednji korak. -**Vzorec nadzornega agenta** - napreden agentski vzorec, kjer nadzorni LLM dinamično odloča, katere pod-agente poklicati. +**Vzorec nadzornega agenta** - Napreden agentni vzorec, kjer nadzorni LLM dinamično odloča, katere pod-agente poklicati. -## Protokol konteksta modela (MCP) - [Modul 05](../05-mcp/README.md) +## Protokol modelnega konteksta (MCP) - [Modul 05](../05-mcp/README.md) **langchain4j-mcp** - Maven odvisnost za integracijo MCP v LangChain4j. -**MCP** - Protokol konteksta modela: standard za povezovanje AI aplikacij z zunanjimi orodji. Zgradi enkrat, uporabljaj povsod. +**MCP** - Protokol modelnega konteksta: standard za povezovanje AI aplikacij z zunanjimi orodji. Naredi enkrat, uporabi povsod. -**MCP odjemalec** - aplikacija, ki se poveže z MCP strežniki za odkrivanje in uporabo orodij. +**MCP odjemalec** - Aplikacija, ki se poveže na MCP strežnike za odkrivanje in uporabo orodij. -**MCP strežnik** - storitev, ki izpostavlja orodja preko MCP z jasnimi opisi in shemami parametrov. +**MCP strežnik** - Storitev, ki preko MCP izpostavlja orodja z jasnimi opisi in shemami parametrov. -**McpToolProvider** - komponenta LangChain4j, ki ovije MCP orodja za uporabo v AI storitvah in agentih. +**McpToolProvider** - Komponenta LangChain4j, ki ovije MCP orodja za uporabo v AI storitvah in agentih. -**McpTransport** - vmesnik za komunikacijo MCP. Implementacije vključujejo Stdio in HTTP. +**McpTransport** - Vmesnik za MCP komunikacijo. Implementacije vključujejo Stdio in HTTP. -**Stdio Transport** - lokalni procesni transport preko stdin/stdout. Uporaben za dostop do datotečnega sistema ali orodij ukazne vrstice. +**Stdio transport** - Lokalni transport procesa preko stdin/stdout. Koristen za dostop do datotečnega sistema ali ukaznih orodij. -**StdioMcpTransport** - implementacija LangChain4j, ki sproži MCP strežnik kot podproces. +**StdioMcpTransport** - Implementacija LangChain4j, ki zažene MCP strežnik kot podproces. -**Odkritje orodij** - odjemalec poizveduje strežnik za razpoložljiva orodja z opisi in shemami. +**Odkritje orodij** - Odjemalec povpraša strežnik o razpoložljivih orodjih z opisi in shemami. ## Azure storitve - [Modul 01](../01-introduction/README.md) -**Azure AI Search** - oblačno iskanje z vektorskimi zmožnostmi. [Modul 03](../03-rag/README.md) +**Azure AI Search** - Oblačno iskanje z vektorskimi zmožnostmi. [Modul 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - uvaja Azure vire. +**Azure Developer CLI (azd)** - Razmestitev Azure virov. **Azure OpenAI** - Microsoftova podjetniška AI storitev. -**Bicep** - jezik za infrastrukturo kot kodo za Azure. [Vodnik o infrastrukturi](../01-introduction/infra/README.md) +**Bicep** - Jezik za infrastrukturo kot koda za Azure. [Vodnik za infrastrukturo](../01-introduction/infra/README.md) -**Ime izvedbe** - ime za namestitev modela v Azure. +**Ime razmestitve** - Ime za razmestitev modela v Azure. -**GPT-5.2** - najnovejši OpenAI model z nadzorom razmišljanja. [Modul 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Najnovejši OpenAI model z nadzorom razmišljanja. [Modul 02](../02-prompt-engineering/README.md) ## Testiranje in razvoj - [Vodnik za testiranje](TESTING.md) -**Razvojni kontejner** - kontejnerizirano razvojno okolje. [Konfiguracija](../../../.devcontainer/devcontainer.json) +**Razvojni kontejner** - Kontejnerizirano razvojno okolje. [Konfiguracija](../../../.devcontainer/devcontainer.json) -**GitHub modeli** - brezplačno igrišče za AI modele. [Modul 00](../00-quick-start/README.md) +**Testiranje v spominu** - Testiranje s shrambo v spominu. -**Testiranje v pomnilniku** - testiranje z uporabo shranjevanja v pomnilniku. +**Integracijsko testiranje** - Testiranje z realno infrastrukturo. -**Integracijsko testiranje** - testiranje z resnično infrastrukturo. +**Maven** - Orodje za avtomatizacijo gradnje Java. -**Maven** - orodje za samodejno gradnjo Java. +**Mockito** - Okvir za lažno ustvarjanje v Java. -**Mockito** - okvir za ustvarjanje nadomestkov v Javi. - -**Spring Boot** - Java okvir za aplikacije. [Modul 01](../01-introduction/README.md) +**Spring Boot** - Okvir za razvoj aplikacij Java. [Modul 01](../01-introduction/README.md) --- **Omejitev odgovornosti**: -Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da lahko avtomatski prevodi vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvorni jezik velja za avtoritativni vir. Za ključne informacije priporočamo strokovni človeški prevod. Za morebitna nesporazume ali napačne razlage, ki izhajajo iz uporabe tega prevoda, ne prevzemamo odgovornosti. +Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za kritične informacije je priporočljiv strokovni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. \ No newline at end of file diff --git a/translations/sl/docs/TESTING.md b/translations/sl/docs/TESTING.md index 472830121..379603fe0 100644 --- a/translations/sl/docs/TESTING.md +++ b/translations/sl/docs/TESTING.md @@ -2,19 +2,19 @@ ## Kazalo vsebine -- [Hitri začetek](../../../docs) -- [Kaj pokrivajo testi](../../../docs) -- [Zagon testov](../../../docs) -- [Zagon testov v VS Code](../../../docs) -- [Vzorec testiranja](../../../docs) -- [Filozofija testiranja](../../../docs) -- [Naslednji koraki](../../../docs) +- [Hiter začetek](#hiter-začetek) +- [Kaj testi zajemajo](#kaj-testi-zajemajo) +- [Zagon testov](#zagon-testov) +- [Zagon testov v VS Code](#zagon-testov-v-vs-code) +- [Vzorci testiranja](#vzorci-testiranja) +- [Filozofija testiranja](#filozofija-testiranja) +- [Naslednji koraki](#naslednji-koraki) -Ta vodič vas vodi skozi teste, ki prikazujejo, kako testirati AI aplikacije brez potrebe po API ključih ali zunanjih storitvah. +Ta vodič vas vodi skozi teste, ki kažejo, kako testirati AI aplikacije brez potrebe po API ključih ali zunanjih storitvah. -## Hitri začetek +## Hiter začetek -Zaženite vse teste z eno samo ukazno vrstico: +Zaženite vse teste z enim ukazom: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Ko vsi testi uspešno opravijo, bi morali videti izhod, podoben spodnjemu posnetku zaslona — testi se izvajajo brez napak. +Ko vsi testi uspešno pretečejo, bi morali videti izhod, kot je prikazan na spodnji sliki — testi se izvajajo brez napak. Uspešni rezultati testov -*Uspešno izvršeni testi, ki kažejo vse teste z nič napakami* +*Uspešno izvajanje testov, ki prikazuje vse teste brez napak* -## Kaj pokrivajo testi +## Kaj testi zajemajo -Ta tečaj se osredotoča na **enotske teste**, ki se izvajajo lokalno. Vsak test prikaže določen koncept LangChain4j izolirano. Spodnja piramida testiranja prikazuje, kje enotni testi sodijo — tvorijo hitro, zanesljivo osnovo, na kateri temelji preostala testna strategija. +Ta tečaj se osredotoča na **enotske teste**, ki tečejo lokalno. Vsak test prikaže poseben koncept LangChain4j ločeno. Spodnja piramida testiranja kaže, kam sodijo enotski testi — ti predstavljajo hitro in zanesljivo osnovo, na kateri temelji celotna testna strategija. Piramida testiranja -*Piramida testiranja, ki prikazuje ravnotežje med enotskimi testi (hitro, izolirano), integracijskimi testi (pravi komponenti) in end-to-end testi. Ta usposabljanje pokriva enotsko testiranje.* +*Piramida testiranja, ki prikazuje ravnovesje med enotskimi testi (hitri, izolirani), integracijskimi testi (pravi komponenti) in e2e testi. Ta usposabljanje zajema enotsko testiranje.* | Modul | Testi | Osredotočenost | Ključne datoteke | -|--------|-------|---------------|------------------| -| **00 - Hitri začetek** | 6 | Predloge pozivov in zamenjava spremenljivk | `SimpleQuickStartTest.java` | -| **01 - Uvod** | 8 | Spomin pogovora in stanje klepeta | `SimpleConversationTest.java` | -| **02 - Inženiring pozivov** | 12 | Vzorce GPT-5.2, stopnje vneme, strukturiran izhod | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Vnos dokumentov, vgrajene predstavitve, iskanje podobnosti | `DocumentServiceTest.java` | -| **04 - Orodja** | 12 | Kličem funkcije in verižim orodja | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Protokol modelnega konteksta s stdio prenosom | `SimpleMcpTest.java` | +|--------|-------|-------|-----------| +| **01 - Uvod** | 8 | Pomnilnik pogovora in stanje klepeta | `SimpleConversationTest.java` | +| **02 - Inženiring pozivov** | 12 | Vzorci GPT-5.2, stopnje navdušenja, strukturiran izhod | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Vnos dokumentov, vgradnje, iskanje podobnosti | `DocumentServiceTest.java` | +| **04 - Orodja** | 12 | Klic funkcij in povezovanje orodij | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Protokol konteksta modela s transportom stdio | `SimpleMcpTest.java` | ## Zagon testov -**Zaženi vse teste iz korena:** +**Zaženite vse teste iz korenskega imenika:** **Bash:** ```bash @@ -63,12 +62,12 @@ mvn test mvn --% test ``` -**Zaženi teste za določen modul:** +**Zaženite teste za določen modul:** **Bash:** ```bash cd 01-introduction && mvn test -# Ali iz root +# Ali iz korena mvn test -pl 01-introduction ``` @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Zaženi posamezen testni razred:** +**Zaženite posamezno testno razredno datoteko:** **Bash:** ```bash @@ -91,11 +90,11 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Zaženi specifično testno metodo:** +**Zaženite določen testni metod:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#naj ohrani zgodovino pogovora +mvn test -Dtest=SimpleConversationTest#bi morali ohraniti zgodovino pogovora ``` **PowerShell:** @@ -105,31 +104,31 @@ mvn --% test -Dtest=SimpleConversationTest#naj vzdržuje zgodovino pogovora ## Zagon testov v VS Code -Če uporabljate Visual Studio Code, Test Explorer nudi grafični vmesnik za zagon in odpravljanje napak testov. +Če uporabljate Visual Studio Code, vam Test Explorer ponuja grafični vmesnik za izvajanje in razhroščevanje testov. Test Explorer v VS Code -*Test Explorer v VS Code prikazuje drevo testov z vsemi Java testnimi razredi in posameznimi testnimi metodami* +*Test Explorer v VS Code prikazuje drevo testov z vsemi razredi testov za Java in posameznimi testi* **Za zagon testov v VS Code:** -1. Odprite Test Explorer s klikom na ikono stekleničke na vrstici aktivnosti +1. Odprite Test Explorer s klikom na ikono epruvete na Activity Barju 2. Razširite drevo testov, da vidite vse module in testne razrede -3. Kliknite gumb za predvajanje poleg katerega koli testa, da ga zaženete posamično -4. Kliknite "Run All Tests" za izvajanje celotne zbirke -5. Z desnim klikom na kateri koli test izberite "Debug Test" za nastavitev preloma in korak skozi kodo +3. Kliknite gumb za predvajanje poleg kateregakoli testa, da ga zaženete posamezno +4. Kliknite "Run All Tests", da zaženete celoten niz +5. Z desnim klikom na katerikoli test izberite "Debug Test" za nastavitev prelomnih točk in korakanje po kodi -Test Explorer prikazuje zelene kljukice za uspešno opravljene teste in daje podrobna sporočila o napakah, ko testi spodletijo. +Test Explorer prikazuje zelene kljukice za uspešno opravljene teste in podrobna sporočila o napakah, če testi ne uspejo. -## Vzorec testiranja +## Vzorci testiranja ### Vzorec 1: Testiranje predlog pozivov -Najpreprostejši vzorec preizkuša predloge pozivov brez klica na AI model. Preverite, ali zamenjava spremenljivk deluje pravilno in ali so pozivi oblikovani kot pričakovano. +Najpreprostejši vzorec testira predloge pozivov, ne da bi klical AI model. Preverite, ali nadomeščanje spremenljivk deluje pravilno in ali so pozivi ustrezno oblikovani. -Testiranje predloge poziva +Testiranje predlog pozivov -*Testiranje predlog pozivov, ki prikazuje potek zamenjave spremenljivk: predloga z označevalci → uporabljene vrednosti → preverjen oblikovan izhod* +*Testiranje predlog pozivov prikazuje potek nadomeščanja spremenljivk: predloga z zamenjavami → uporabljene vrednosti → preverjen oblikovan izhod* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Ta test se nahaja v `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Zaženi ga:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#preveriObrazecPredlogePoziva -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testiranjeOblikePredlogePoziva -``` +Ta vzorec preverja pravilno delovanje nadomeščanja spremenljivk in ustrezno oblikovanje pozivov — ni potreben API ključ ali klic modela. -### Vzorec 2: Uporaba lažnih jezikovnih modelov +### Vzorec 2: Simulacija jezikovnih modelov -Pri testiranju logike pogovora uporabite Mockito za ustvarjanje lažnih modelov, ki vračajo vnaprej določene odzive. To naredi teste hitre, brezplačne in deterministične. +Pri testiranju logike pogovorov uporabite Mockito za ustvarjanje lažnih modelov, ki vračajo vnaprej določene odgovore. To naredi teste hitre, brezplačne in deterministične. -Primerjava lažnih in pravih API-jev +Primerjava simulacije in pravega API -*Primerjava, zakaj so lažni modeli za testiranje boljši: so hitri, brezplačni, deterministični in ne potrebujejo API ključev* +*Primerjava, zakaj so simulatorji boljši za testiranje: so hitri, brezplačni, deterministični in ne zahtevajo API ključev* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Ta vzorec najdete v `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Lažni model zagotavlja dosledno vedenje, tako da lahko preverite pravilno upravljanje s spominom. +Ta vzorec se pojavi v `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Simulacija zagotavlja dosledno vedenje, da lahko preverite pravilno upravljanje s pomnilnikom. ### Vzorec 3: Testiranje izolacije pogovora -Spomin pogovora mora ločevati več uporabnikov. Ta test preverja, da se konteksti pogovorov ne mešajo. +Pomnilnik pogovora mora ohranjati uporabnike ločene. Ta test preverja, da se konteksti pogovorov ne mešajo. Izolacija pogovora -*Testiranje izolacije pogovorov, ki prikazuje ločene spominske shrambe za različne uporabnike, da prepreči mešanje konteksta* +*Testiranje izolacije pogovora prikazuje ločene shrambe pomnilnika za različne uporabnike, da se prepreči mešanje konteksta* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Vsak pogovor ohranja svojo neodvisno zgodovino. V proizvodnih sistemih je ta izolacija ključna za aplikacije z več uporabniki. +Vsak pogovor ohranja svojo neodvisno zgodovino. V proizvodnih sistemih je ta izolacija ključna za večuporabniške aplikacije. ### Vzorec 4: Neodvisno testiranje orodij -Orodja so funkcije, ki jih lahko AI pokliče. Testirajte jih neposredno, da zagotovite, da delujejo pravilno ne glede na odločitve AI. +Orodja so funkcije, ki jih AI lahko pokliče. Testirajte jih neposredno, da zagotovite pravilno delovanje ne glede na odločitve AI. Testiranje orodij -*Neodvisno testiranje orodij, ki prikazuje izvajanje lažnih orodij brez AI klicev za preverjanje poslovne logike* +*Neodvisno testiranje orodij prikazuje izvajanje simuliranega orodja brez klica AI za preverjanje poslovne logike* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Ti testi iz `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` preverjajo logiko orodij brez vključitve AI. Primer verižnega povezovanja prikazuje, kako izhod enega orodja napaja vhod drugega. +Ti testi iz `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` preverjajo logiko orodij brez sodelovanja AI. Primer povezovanja prikazuje, kako izhod enega orodja služi kot vhod drugemu. -### Vzorec 5: RAG testiranje v pomnilniku +### Vzorec 5: Testiranje RAG v pomnilniku -Sistemi RAG običajno potrebujejo vektorske baze podatkov in storitve za vgrajevanje. Vzorec v pomnilniku vam omogoča, da testirate celoten pipeline brez zunanjih odvisnosti. +Sistemi RAG običajno zahtevajo vektorske baze podatkov in storitve vgradnje. Vzorec v pomnilniku omogoča testiranje celotnega poteka brez zunanjih odvisnosti. -RAG testiranje v pomnilniku +Testiranje RAG v pomnilniku -*Delovni potek RAG testiranja v pomnilniku, ki prikazuje razčlenjevanje dokumentov, shranjevanje vgradnje in iskanje podobnosti brez potrebe po bazi podatkov* +*Potek testiranja RAG v pomnilniku prikazuje analizo dokumenta, shranjevanje vgradenj in iskanje podobnosti brez potrebe po podatkovni bazi* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -Ta test iz `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` ustvari dokument v pomnilniku in preveri razdeljevanje delcev ter ravnanje z metapodatki. +Ta test iz `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` ustvari dokument v pomnilniku in preveri razbitje na kose ter upravljanje meta-podatkov. ### Vzorec 6: Integracijsko testiranje MCP -Modul MCP testira integracijo Protokola modelnega konteksta z uporabo stdio prenosa. Ti testi preverjajo, da vaša aplikacija lahko zažene in komunicira z MCP strežniki kot podprocesi. +Modul MCP testira integracijo Protokola konteksta modela z uporabo stdio prenosa. Ti testi preverjajo, da vaša aplikacija lahko zažene in komunicira z MCP strežniki kot podprocesi. -Testi v `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` potrjujejo vedenje MCP odjemalca. +Testi v `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` preverjajo delovanje MCP odjemalca. -**Zaženi jih:** +**Zaženite jih:** **Bash:** ```bash @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## Filozofija testiranja -Testirajte svojo kodo, ne AI. Vaši testi bi morali potrditi kodo, ki jo napišete, tako da preverite, kako so zgrajeni pozivi, kako se upravlja s spominom in kako se izvajajo orodja. Odzivi AI se razlikujejo in ne bi smeli biti del testnih trditev. Vprašajte se, ali vaša predloga poziva pravilno nadomešča spremenljivke, ne ali AI poda pravi odgovor. +Testirajte vašo kodo, ne AI. Vaši testi naj preverjajo kodo, ki jo napišete, tako da preverijo, kako so pozivi sestavljeni, kako je upravljan pomnilnik in kako se izvajajo orodja. Odgovori AI so lahko različni in ne bi smeli biti del testnih trditev. Pozanimajte se, ali vaša predloga poziva pravilno nadomešča spremenljivke, ne ali AI poda pravilen odgovor. -Uporabite lažne modele jezikov. So zunanje odvisnosti, ki so počasne, drage in nedeterministične. Lažno modeliranje naredi teste hitre z milisekundami namesto sekund, brezplačne brez stroškov API, in deterministične z istim rezultatom vsakič. +Uporabljajte simulacije za jezikovne modele. To so zunanje odvisnosti, ki so počasne, drage in nedeterministične. Simulacija naredi teste hitre z izvajanjem v milisekundah namesto sekund, brezplačne brez stroškov API in deterministične z istim rezultatom vsakič. -Ohranjajte teste neodvisne. Vsak test naj nastavi svoje podatke, se ne zanaša na druge teste in počisti za sabo. Testi naj uspevajo ne glede na vrstni red izvajanja. +Ohranite teste neodvisne. Vsak test naj si sam nastavi podatke, ne naj se zanese na druge teste in naj se sam počisti. Testi naj vedno uspešno opravijo test, ne glede na vrstni red izvajanja. -Testirajte robne primere, ki presegajo srečne poti. Poskusite prazne vnose, zelo velike vnose, posebne znake, neveljavne parametre in mejne pogoje. Ti pogosto razkrijejo napake, ki jih običajna uporaba ne pokaže. +Testirajte robne primere poleg osnovne poti. Poskusite prazne vnose, zelo velike vnose, posebne znake, neveljavne parametre in mejne pogoje. Ti pogosto razkrijejo napake, ki jih običajna uporaba ne pokaže. -Uporabite opisna imena. Primerjajte `shouldMaintainConversationHistoryAcrossMultipleMessages()` z `test1()`. Prvo vam natančno pove, kaj se testira, kar bistveno olajša odpravljanje napak. +Uporabljajte opisna imena. Primerjajte `shouldMaintainConversationHistoryAcrossMultipleMessages()` s `test1()`. Prvo vam izrecno pove, kaj se testira, kar olajša iskanje napak. ## Naslednji koraki -Zdaj, ko razumete vzorce testiranja, se poglobite v vsak modul: +Zdaj, ko razumete vzorce testiranja, se poglobite v posamezne module: -- **[00 - Hitri začetek](../00-quick-start/README.md)** - Začnite z osnovami predlog pozivov -- **[01 - Uvod](../01-introduction/README.md)** - Naučite se upravljanja s spominom pogovorov -- **[02 - Inženiring pozivov](../02-prompt-engineering/README.md)** - Obvladujte vzorce pozivov GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Gradite sisteme za generiranje z izboljšanim iskanjem -- **[04 - Orodja](../04-tools/README.md)** - Uvedite klic funkcij in verige orodij -- **[05 - MCP](../05-mcp/README.md)** - Integrirajte Protokol modelnega konteksta +- **[01 - Uvod](../01-introduction/README.md)** - Naučite se upravljanja spomina pogovora +- **[02 - Inženiring pozivov](../02/prompt-engineering/README.md)** - Obvladajte vzorce pozivov GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Zgradite sisteme za generiranje s podporo pridobivanja +- **[04 - Orodja](../04-tools/README.md)** - Implementirajte klice funkcij in povezave orodij +- **[05 - MCP](../05-mcp/README.md)** - Integrirajte Protokol konteksta modela -README vseh modulov vsebuje podrobna pojasnila konceptov, testiranih tukaj. +Vsak modulov README vsebuje podrobna pojasnila konceptov, ki so tu testirani. --- @@ -359,5 +345,5 @@ README vseh modulov vsebuje podrobna pojasnila konceptov, testiranih tukaj. **Omejitev odgovornosti**: -Ta dokument je bil preveden z uporabo storitve za prevajanje z umetno inteligenco [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas opozarjamo, da lahko avtomatizirani prevodi vsebujejo napake ali netočnosti. Izvirnik dokumenta v njegovem izvirnem jeziku naj velja za avtoritativni vir. Za ključne informacije priporočamo strokovni človeški prevod. Za kakršnekoli napačne razlage ali nerazumevanja, ki izhajajo iz uporabe tega prevoda, ne odgovarjamo. +Ta dokument je bil preveden z uporabo AI prevajalske storitve [Co-op Translator](https://github.com/Azure/co-op-translator). Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za kritične informacije je priporočljiv strokovni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda. \ No newline at end of file diff --git a/translations/sr/.co-op-translator.json b/translations/sr/.co-op-translator.json index ba4897d69..476ae526f 100644 --- a/translations/sr/.co-op-translator.json +++ b/translations/sr/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "sr" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T03:32:23+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T11:14:04+00:00", "source_file": "01-introduction/README.md", "language_code": "sr" }, @@ -18,20 +18,20 @@ "language_code": "sr" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T03:34:54+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T11:09:50+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "sr" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T03:36:28+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T11:13:13+00:00", "source_file": "03-rag/README.md", "language_code": "sr" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T08:39:24+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T11:11:56+00:00", "source_file": "04-tools/README.md", "language_code": "sr" }, @@ -54,8 +54,8 @@ "language_code": "sr" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:02:28+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T11:08:36+00:00", "source_file": "README.md", "language_code": "sr" }, @@ -72,14 +72,14 @@ "language_code": "sr" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T03:39:38+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T11:10:15+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "sr" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T03:40:27+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T11:10:49+00:00", "source_file": "docs/TESTING.md", "language_code": "sr" } diff --git a/translations/sr/00-quick-start/README.md b/translations/sr/00-quick-start/README.md deleted file mode 100644 index b39d1bf17..000000000 --- a/translations/sr/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Модул 00: Брзи почетак - -## Садржај - -- [Увод](../../../00-quick-start) -- [Шта је LangChain4j?](../../../00-quick-start) -- [Зависности LangChain4j](../../../00-quick-start) -- [Предуслови](../../../00-quick-start) -- [Подешавање](../../../00-quick-start) - - [1. Узмите свој GitHub токен](../../../00-quick-start) - - [2. Поставите свој токен](../../../00-quick-start) -- [Покрените примере](../../../00-quick-start) - - [1. Основни ћаскање](../../../00-quick-start) - - [2. Обрасци за упите](../../../00-quick-start) - - [3. Позивање функција](../../../00-quick-start) - - [4. Питања и одговори на документима (Easy RAG)](../../../00-quick-start) - - [5. Одговорни AI](../../../00-quick-start) -- [Шта сваки пример показује](../../../00-quick-start) -- [Следећи кораци](../../../00-quick-start) -- [Решавање проблема](../../../00-quick-start) - -## Увод - -Овај брзи почетак је намењен да вас што брже покрене са LangChain4j. Обухвата основе прављења AI апликација са LangChain4j и GitHub моделима. У наредним модулима прелазите на Azure OpenAI и GPT-5.2 и дубље се бавите сваким концептом. - -## Шта је LangChain4j? - -LangChain4j је Java библиотека која поједностављује прављење апликација са вештачком интелигенцијом. Уместо да се бавите HTTP клијентима и парсирањем JSON-а, радите са чистим Java API-јима. - -„Ланац“ у LangChain означава повезивање више компоненти заједно – можете повезати упит са моделом, затим са парсером, или повезати више AI позива где резултат једног иде као улаз за други. Овај брзи почетак је усредсређен на основе пре него што истражите сложеније ланце. - -LangChain4j концепт ланца - -*Повезивање компоненти у LangChain4j – градивни блокови се спајају да створе моћне AI токове рада* - -Користићемо три основне компоненте: - -**ChatModel** – Интерфејс за интеракцију са AI моделом. Позовете `model.chat("промпт")` и добијете одговор у виду низа. Користимо `OpenAiOfficialChatModel` који ради са OpenAI-компатибилним крајњим тачкама као што су GitHub модели. - -**AiServices** – Креира типско безбедне AI сервисне интерфејсе. Дефинишете методе, означите их са `@Tool`, и LangChain4j се бави оркестрацијом. AI аутоматски позива ваше Java методе кад је потребно. - -**MessageWindowChatMemory** – Одржава историју разговора. Без ове компоненте сваки захтев је независан. Са њом, AI памти претходне поруке и одржава контекст кроз више корака. - -Архитектура LangChain4j - -*Архитектура LangChain4j – основне компоненте које раде заједно да покрећу ваше AI апликације* - -## Зависности LangChain4j - -Овај брзи почетак користи три Maven зависности у [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Модул `langchain4j-open-ai-official` обезбеђује класу `OpenAiOfficialChatModel` која се повезује на OpenAI-компатибилне API-је. GitHub модели користе исти формат API-ја, тако да није потребан посебан адаптер – само усмерите базну URL адресу на `https://models.github.ai/inference`. - -Модул `langchain4j-easy-rag` обезбеђује аутоматско раздвајање, уграђивање и претрагу докумената, тако да можете изградити RAG апликације без ручног конфигурисања сваког корака. - -## Предуслови - -**Користите ли Dev Container?** Јава и Maven су већ инсталирани. Потребан вам је само GitHub Personal Access Token. - -**Локални развој:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (упутство доле) - -> **Напомена:** Овај модул користи `gpt-4.1-nano` из GitHub модела. Немојте мењати име модела у коду – конфигурисан је да ради са расположивим моделима GitHub-а. - -## Подешавање - -### 1. Узмите свој GitHub токен - -1. Идите на [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Кликните на "Generate new token" -3. Поставите описно име (нпр. "LangChain4j Demo") -4. Поставите рок важности (препоручује се 7 дана) -5. Под „Account permissions“ пронађите „Models“ и подесите на „Read-only“ -6. Кликните на "Generate token" -7. Копирајте и сачувајте токен – више га нећете видети - -### 2. Поставите свој токен - -**Опција 1: Користећи VS Code (препоручено)** - -Ако користите VS Code, додајте свој токен у `.env` фајл у корену пројекта: - -Ако `.env` фајл не постоји, копирајте `.env.example` у `.env` или направите нови `.env` фајл у корену пројекта. - -**Пример `.env` фајла:** -```bash -# У /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Онда можете једноставно десним кликом на било који демо фајл (нпр. `BasicChatDemo.java`) у Explorer-у и одабрати **"Run Java"** или користити конфигурације за покретање из Run and Debug панела. - -**Опција 2: Користећи терминал** - -Поставите токен као променљиву окружења: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Покрените примере - -**Користећи VS Code:** Једноставно десним кликом на било који демо фајл у Explorer-у одаберите **"Run Java"** или користите конфигурације из Run and Debug панела (обавезно сте претходно додали токен у `.env`). - -**Користећи Maven:** Алтернативно, можете покренути из командне линије: - -### 1. Основни ћаскање - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Обрасци за упите - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Приказује zero-shot, few-shot, chain-of-thought и упите засноване на улогама. - -### 3. Позивање функција - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI аутоматски позива ваше Java методе кад је потребно. - -### 4. Питања и одговори на документима (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Постављајте питања о вашим документима користећи Easy RAG са аутоматским уграђивањем и претрагом. - -### 5. Одговорни AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Погледајте како AI филтери за безбедност блокирају штетни садржај. - -## Шта сваки пример показује - -**Основни ћаскање** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Започните овде да видите LangChain4j у најједноставнијој форми. Креираћете `OpenAiOfficialChatModel`, послаћете упит `.chat()` и добити одговор. Ово показује темеље: како инициализовати моделе са прилагођеним крајњим тачкама и API кључевима. Када разумете овај образац, све остало се гради на томе. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Ćаскањем:** Отворите [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) и питајте: -> - "Како бих пребацио са GitHub модела на Azure OpenAI у овом коду?" -> - "Које друге параметре могу да конфигуришем у OpenAiOfficialChatModel.builder()?" -> - "Како да додам стриминг одговоре уместо да чекам комплетан одговор?" - -**Инжењеринг упита** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Сад када знате како да разговарате са моделом, истражимо шта му говорите. Овај демо користи исту конфигурацију модела али показује пет различитих образаца упита. Испробајте zero-shot упите за директне инструкције, few-shot упите који уче из примера, chain-of-thought упите који откривају кораке резоновања, и упите засноване на улогама који постављају контекст. Видео ћете како исти модел даје драстично различите резултате у зависности од начина формулације захтева. - -Демо такође приказује предлошке за упите, који су моћан начин да направите поновљиве упите са променљивима. -Испод је пример упита користећи LangChain4j `PromptTemplate` за попуњавање променљивих. AI ће одговорити на основу дате дестинације и активности. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Ćаскањем:** Отворите [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) и питајте: -> - "Која је разлика између zero-shot и few-shot упита и када треба користити који?" -> - "Како параметар temperature утиче на одговоре модела?" -> - "Које су неке технике за спречавање напада уписивањем упита (prompt injection) у продукцији?" -> - "Како да направим поновљиве PromptTemplate објекте за честе обрасце?" - -**Интеграција алата** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Овде LangChain4j постаје моћан. Користићете `AiServices` да направите AI асистента који може позивати ваше Java методе. Само означите методе са `@Tool("опис")` и LangChain4j се бави осталим – AI аутоматски одлучује када ће користити који алат на основу онога што корисник тражи. Ово приказује позивање функција, кључну технику за прављење AI који може извршавати акције, а не само одговарати на питања. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Ćаскањем:** Отворите [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) и питајте: -> - "Како ради @Tool анотација и шта LangChain4j ради са њом иза сцене?" -> - "Може ли AI позивати више алата узастопно да реши сложене проблеме?" -> - "Шта се дешава ако алат баци изузетак – како треба да руковам грешкама?" -> - "Како бих интегрисао прави API уместо овог примера калкулатора?" - -**Питања и одговори на документима (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Овде ћете видети RAG (retrieval-augmented generation) користећи LangChain4j приступ "Easy RAG". Документи се учитавају, аутоматски раздвајају и уграђују у меморијску базу, затим претраживач садржаја доставља релевантне делове AI-ју у тренутку упита. AI одговара на основу ваших докумената, не своје опште базе знања. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Ćаскањем:** Отворите [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) и питајте: -> - "Како RAG спречава AI халуцинације у поређењу са коришћењем података о обучавању модела?" -> - "Која је разлика између овог једноставног приступа и прилагођеног RAG процеса?" -> - "Како бих ово скалирао за рад са више докумената или већим базама знања?" - -**Одговорни AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Градите AI безбедност са одбраном у дубини. Овај демо приказује два слоја заштите који раде заједно: - -**Део 1: LangChain4j Guardrails за унос** – Блокира опасне упите пре него што дођу до LLM-а. Креирајте прилагођене грејдрајлове који проверавају забрањене кључне речи или обрасце. Они раде у вашем коду, тако да су брзи и бесплатни. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Део 2: Филтери безбедности провајдера** – GitHub модели имају уграђене филтере који хватају оно што ваши грејдрајлови пропусте. Видећете оштре блокаде (HTTP 400 грешке) за озбиљне прекршаје и благе одбијања где AI љубазно одбија. - -> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Ćаскањем:** Отворите [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) и питајте: -> - "Шта је InputGuardrail и како направити свој?" -> - "Која је разлика између оштре блокаде и блажег одбијања?" -> - "Зашто користити и грејдрајлове и филтере провајдера заједно?" - -## Следећи кораци - -**Следећи модул:** [01-introduction - Почетак рада са LangChain4j](../01-introduction/README.md) - ---- - -**Навигација:** [← Назад на Главну](../README.md) | [Следеће: Модул 01 - Увод →](../01-introduction/README.md) - ---- - -## Решавање проблема - -### Прва Maven компилација - -**Проблем:** Почетни `mvn clean compile` или `mvn package` траје дуго (10-15 минута) - -**Узрок:** Maven мора да преузме све зависности пројекта (Spring Boot, LangChain4j библиотеке, Azure SDK итд.) при првој компилацији. - -**Решење:** Ово је нормално понашање. Наредне компилације ће бити много брже јер се зависности кеширају локално. Време преузимања зависи од брзине ваше мреже. - -### Синтакса Maven команди у PowerShell-у - -**Проблем:** Maven команде не успевају са грешком `Unknown lifecycle phase ".mainClass=..."` -**Узрок**: PowerShell тумачи `=` као оператор додељивања вредности променљивој, што нарушава Maven синтаксу својстава - -**Решење**: Користите оператор за заустављање парсирања `--%` пре Maven команде: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Оператор `--%` каже PowerShell-у да све остале аргументе проследи Maven-у буквално, без тумачења. - -### Приказ емоџија у Windows PowerShell - -**Проблем**: AI одговори приказују бесмислене знакове (нпр. `????` или `â??`) уместо емоџија у PowerShell-у - -**Узрок**: Подразумевани енкодирање PowerShell-а не подржава UTF-8 емоџије - -**Решење**: Покрените ову команду пре извршавања Java апликација: -```cmd -chcp 65001 -``` - -Ово приморава UTF-8 енкодирање у терминалу. Алтернативно, користите Windows Terminal који има бољу подршку за Unicode. - -### Дебаговање API позива - -**Проблем**: Грешке при аутентификацији, ограничења брзине или неочекивани одговори од AI модела - -**Решење**: Примери укључују `.logRequests(true)` и `.logResponses(true)` да би приказали API позиве у конзоли. Ово помаже при решавању проблема са аутентификацијом, ограничењима брзине или неочекиваним одговорима. Уклоните ове заставице у продукцији да бисте смањили буку у логовима. - ---- - - -**Одрицање од одговорности**: -Овај документ је преведен помоћу AI услуге за превођење [Co-op Translator](https://github.com/Azure/co-op-translator). Иако настојимо да превод буде тачан, молимо вас да имате у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитетним извором. За критичне информације препоручује се професионални превод од стране људског стручњака. Не преузимамо одговорност за било каква неспоразума или погрешна тумачења која проистекну из коришћења овог превода. - \ No newline at end of file diff --git a/translations/sr/01-introduction/README.md b/translations/sr/01-introduction/README.md index aa9892014..9a6f9cf40 100644 --- a/translations/sr/01-introduction/README.md +++ b/translations/sr/01-introduction/README.md @@ -1,85 +1,85 @@ -# Модул 01: Почетак рада са LangChain4j +# Модул 01: Започињање са LangChain4j ## Садржај -- [Видео водич](../../../01-introduction) -- [Шта ћете научити](../../../01-introduction) -- [Предуслови](../../../01-introduction) -- [Разумевање основног проблема](../../../01-introduction) -- [Разумевање токена](../../../01-introduction) -- [Како памћење функционише](../../../01-introduction) -- [Како ово користи LangChain4j](../../../01-introduction) -- [Деплојмент Azure OpenAI инфраструктуре](../../../01-introduction) -- [Покретање апликације локално](../../../01-introduction) -- [Коришћење апликације](../../../01-introduction) - - [Чет без стања (леви панел)](../../../01-introduction) - - [Чет са стањем (десни панел)](../../../01-introduction) -- [Следећи кораци](../../../01-introduction) +- [Видео водич](#видео-водич) +- [Шта ћете научити](#шта-ћете-научити) +- [Претпоставке](#претпоставке) +- [Разумевање основног проблема](#разумевање-основног-проблема) +- [Разумевање токена](#разумевање-токена) +- [Како меморија функционише](#како-меморија-функционише) +- [Како ово користи LangChain4j](#како-ово-користи-langchain4j) +- [Деплој инфраструктуре Azure OpenAI](#деплој-инфраструктуре-azure-openai) +- [Покретање апликације локално](#покретање-апликације-локално) +- [Коришћење апликације](#коришћење-апликације) + - [Беспрекорни ћаскање (леви панел)](#беспрекорно-ћаскање-леви-панел) + - [Са стањем ћаскање (десни панел)](#са-стањем-ћаскање-десни-панел) +- [Следећи кораци](#следећи-кораци) ## Видео водич -Погледајте ову уживо сесију која објашњава како започети са овим модулом: +Гледајте ову живу сесију која објашњава како започети са овим модулом: -Getting Started with LangChain4j - Live Session +Започињање са LangChain4j - Лива сесија ## Шта ћете научити -У брзом почетку користили сте GitHub моделе за слање упита, позив алата, прављење RAG пипелина и тестирање гардилајнс-а. Те демонстрације су показале шта је могуће — сада прелазимо на Azure OpenAI и GPT-5.2 и почињемо да градимо продукцијске апликације. Овај модул се фокусира на конверзациони АИ који памти контекст и одржава стање — концепти које су брзи почетни примери користили иза сцена али нису објашњавали. +Ово је ваша почетна тачка са LangChain4j и Azure OpenAI. Почињемо са основама и почињемо да градимо апликације стилом продукције. Овај модул се фокусира на конверзацијски АИ који памти контекст и одржава стање — основне концепте на којима се граде сви каснији модули. -Током овог водича користићемо Azure OpenAI GPT-5.2 јер његове напредне могућности резоновања више илуструју понашање различитих паттерна. Када додате памћење, разлика ће бити јасно видљива. Ово олакшава разумевање шта сваки део доноси вашој апликацији. +У овом водичу ћемо користити Azure OpenAI GPT-5.2 зато што његове напредне могућности разумевања чине понашање различитих образаца јаснијим. Када додате меморију, јасно ћете видети разлику. Ово олакшава разумевање шта свака компонента доноси вашој апликацији. -Изградићете једну апликацију која демонстрира оба паттерна: +Изградићете једну апликацију која демонстрира оба образца: -**Чет без стања** - Сваки захтев је независан. Модел нема памћење претходних порука. Ово је паттерн који сте користили у брзом почетку. +**Беспрекорни ћаскање** - сваки захтев је независан. Модел нема сећање на претходне поруке. Ово је најједноставнија почетна тачка. -**Чет са стањем** - Сваки захтев укључује историју разговора. Модел одржава контекст кроз више корака. Ово је оно што продукцијске апликације захтевају. +**Ћаскање са стањем** - сваки захтев укључује историју разговора. Модел одржава контекст кроз више корака. Ово је оно што производне апликације захтевају. -## Предуслови +## Претпоставке - Azure претплата са приступом Azure OpenAI - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Напомена:** Java, Maven, Azure CLI и Azure Developer CLI (azd) су претходно инсталирани у обезбеђеном девконтейнеру. +> **Белешка:** Java, Maven, Azure CLI и Azure Developer CLI (azd) су већ инсталирани у обезбеђеном девконтејнеру. -> **Напомена:** Овај модул користи GPT-5.2 на Azure OpenAI. Деплојмент је аутоматски конфигурисан преко `azd up` - немојте мењати име модела у коду. +> **Белешка:** Овај модул користи GPT-5.2 на Azure OpenAI. Деплој је аутоматски конфигурисан преко `azd up` - немојте мењати име модела у коду. ## Разумевање основног проблема -Језички модели су без стања. Сваки API позив је независан. Ако пошаљете "Зовем се Јован" и онда питате "Како ми се зовеш?", модел нема појма да сте се управо представили. Поступа као да је сваки захтев први разговор који сте икада имали. +Језички модели су беспрекорни (без стања). Сваки позив API-ју је независан. Ако пошаљете "Зовем се Јован" и затим питате "Које ми је име?", модел нема појма да сте се управо представили. Сматра сваки захтев као да је то први разговор који сте икада имали. -Ово је у реду за једноставна питања и одговоре али је бескорисно за стварне апликације. Ботови за корисничку подршку морају да памте шта сте им рекли. Лични асистенти захтевају контекст. Свaки разговор који траје више корака тражи памћење. +Ово је у реду за једноставна питања и одговоре, али бескорисно за праве апликације. Ботови за корисничку службу морају да памте шта сте им рекли. Лични асистенти требају контекст. Свака вишекрупна конверзација захтева меморију. -Следећа дијаграм илуструје две приступа — са леве стране, позив без стања који заборавља ваше име; са десне стране, позив са стањем подржан од ChatMemory који га памти. +Следећа дијаграм упоређује ова два приступа — са леве стране беспрекорни позив који заборавља ваше име; са десне стране позив са стањем са ChatMemory који га памти. -Stateless vs Stateful Conversations +Разговори без и са стањем -*Разлика између разговора без стања (независни позиви) и са стањем (са знањем контекста)* +*Разлика између беспрекорних (независних позива) и разговор са стањем (познат контекст)* ## Разумевање токена -Пре него што уроните у разговоре, важно је разумети токене - основне јединице текста које језички модели обрађују: +Пре него што заронимо у разговоре, важно је разумети токене - основне јединице текста које језички модели обрађују: -Token Explanation +Објашњење токена -*Пример како се текст разлаже на токене - "Волим АИ!" постаје 4 одвојене јединице за обраду* +*Пример како се текст разлаже на токене - „Волим АИ!“ постаје 4 одвојене јединице за обраду* -Токени су начин на који АИ модели мере и обрађују текст. Речи, интерпункција и чак размаке могу бити токени. Ваш модел има ограничење колико токена може одједном обрадити (400,000 за GPT-5.2, са до 272,000 улазних и 128,000 излазних токена). Разумевање токена помаже у управљању дужином разговора и трошковима. +Токени су како АИ модели мере и обрађују текст. Речи, интерпункција и чак размаке могу бити токени. Ваш модел има лимит колико токена може обрадити одједном (400,000 за GPT-5.2, са до 272,000 улазних токена и 128,000 излазних токена). Разумевање токена помаже у управљању дужином конверзације и трошковима. -## Како памћење функционише +## Како меморија функционише -Чат меморија решава проблем без стања одржавајући историју разговора. Пре слања вашег захтева моделу, оквир претходно додаје релевантне претходне поруке. Када питате "Како ми се зовеш?", систем заправо шаље целу историју разговора, омогућавајући моделу да види да сте раније рекли "Зовем се Јован." +Меморија ћаскања решава проблем беспрекорности одржавањем историје разговора. Пре слања вашег захтева моделу, оквир додаје релевантне претходне поруке. Када питате "Које ми је име?", систем заправо шаље целу историју разговора, што омогућава моделу да види да сте раније рекли "Зовем се Јован." -LangChain4j пружа имплементације меморије које се аутоматски брину о овоме. Изаберете колико порука желите да задржите, а оквир управља прозором контекста. Дијаграм испод показује како MessageWindowChatMemory одржава клизни прозор недавних порука. +LangChain4j обезбеђује имплементације меморије које ово аутоматски управљају. Ви бирати колико порука желите да задржите, а оквир управља прозором контекста. Дијаграм испод показује како MessageWindowChatMemory одржава клизни прозор недавних порука. -Memory Window Concept +Концепт меморијског прозора -*MessageWindowChatMemory одржава клизни прозор недавних порука, аутоматски избацујући старе* +*MessageWindowChatMemory одржава клизни прозор недавних порука, аутоматски одбацујући старе* ## Како ово користи LangChain4j -Овај модул проширује брзи почетак интеграцијом Spring Boot-а и додавањем меморије разговора. Ево како делови функционишу заједно: +Овај модул интегрише Spring Boot и додаје меморију разговора. Ево како се делови уклапају заједно: **Зависности** - Додајте две LangChain4j библиотеке: @@ -94,7 +94,7 @@ LangChain4j пружа имплементације меморије које с ``` -**Чат модел** - Конфигуришите Azure OpenAI као спрингов bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Модел ћаскања** - Конфигуришите Azure OpenAI као Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Билдер преузима акредитиве из променљивих окружења подешених од `azd up`. Постављање `baseUrl` на вашу Azure крајњу тачку омогућава OpenAI клијенту да ради са Azure OpenAI. +Билдер чита креденцијале из променљивих окружења подешених од `azd up`. Подешавање `baseUrl` на вашу Azure крајњу тачку чини OpenAI клијент радом са Azure OpenAI. -**Меморија разговора** - Пратите историју ћаскања помоћу MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Меморија разговора** - Пратите историју ћаскања са MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,21 +124,21 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Креирајте меморију са `withMaxMessages(10)` да задржите последњих 10 порука. Додајте поруке корисника и АИ са типизованим омотачима: `UserMessage.from(text)` и `AiMessage.from(text)`. Преузмите историју помоћу `memory.messages()` и пошаљите је моделу. Сервис чува посебне инстанце меморије по ID-у разговора, што омогућава више корисника да ћаскају истовремено. +Креирајте меморију помоћу `withMaxMessages(10)` да бисте задржали последњих 10 порука. Додајте поруке корисника и АИ са типизованим обмотачима: `UserMessage.from(text)` и `AiMessage.from(text)`. Вратите историју са `memory.messages()` и пошаљите је моделу. Сервис чува засебне инстанце меморије по ИД-у разговора, омогућавајући више корисника да истовремено разговарају. -> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Четом:** Отворите [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) и питајте: -> - "Како MessageWindowChatMemory одлучује које поруке ће избацити када је прозор пун?" -> - "Могу ли имплементирати прилагођено складиштење меморије користећи базу података уместо у меморији?" -> - "Како бих додао резимирање за компримиовање старе историје разговора?" +> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) ћаскањем:** Отворите [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) и питајте: +> - "Како MessageWindowChatMemory одлучује које поруке да одбаци када је прозор пун?" +> - "Могу ли да имплементирам прилагођено складиштење меморије користећи базу података уместо у меморији?" +> - "Како бих додао сумирање да компресујем стару историју разговора?" -Чет без стања прескаче меморију у потпуности - само `chatModel.chat(prompt)` као у брзом почетку. Чет са стањем додаје поруке меморији, преузима историју и укључује тај контекст у сваки захтев. Иста конфигурација модела, различити паттерни. +Ендпоинт за беспрекорно ћаскање потпуно прескаче меморију - само `chatModel.chat(prompt)` као код брзог старта. Ендпоинт са стањем додаје поруке меморији, враћа историју и укључује тај контекст у сваки захтев. Иста конфигурација модела, различити образци. -## Деплојмент Azure OpenAI инфраструктуре +## Деплој инфраструктуре Azure OpenAI **Bash:** ```bash cd 01-introduction -azd up # Изаберите претплату и локацију (препоручено eastus2) +azd up # Изаберите претплату и локацију (препоручује се eastus2) ``` **PowerShell:** @@ -147,28 +147,28 @@ cd 01-introduction azd up # Изаберите претплату и локацију (препоручује се eastus2) ``` -> **Напомена:** Ако наиђете на timeout грешку (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), једноставно покрените `azd up` поново. Azure ресурси можда још увек пролазе кроз процес креирања у позадини, а поновни покушај дозвољава да деплојмент буде завршен када ресурси достигну завршно стање. +> **Белешка:** Ако наиђете на грешку временског ограничења (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), само поново покрените `azd up`. Azure ресурси могу још увек бити у фази припреме у позадини, а поновно покушавање омогућава да деплој заврши када ресурси достигну коначну фазу. Ово ће: -1. Деплојтовати Azure OpenAI ресурс са GPT-5.2 и text-embedding-3-small моделима -2. Аутоматски генерисати `.env` фајл у корену пројекта са акредитивима +1. Разместити Azure OpenAI ресурс са GPT-5.2 и текстуалним ембединг моделом text-embedding-3-small +2. Аутоматски генерисати `.env` датотеку у корену пројекта са креденцијалима 3. Подесити све потребне променљиве окружења -**Имате проблеме са деплојментом?** Погледајте [Infrastructure README](infra/README.md) за детаљне кораке о решавању проблема укључујући конфликте имена поддомена, ручне кораке у Azure порталу и смернице за конфигурацију модела. +**Имате проблема са деплојем?** Погледајте [Infrastructure README](infra/README.md) за детаљно решавање проблема укључујући сукобе имена поддомена, ручне кораке деплоја на Azure портал и водич за конфигурацију модела. -**Проверите да ли је деплојмент успео:** +**Проверите да ли је деплој успео:** **Bash:** ```bash -cat ../.env # Требало би да приказује AZURE_OPENAI_ENDPOINT, API_KEY, итд. +cat ../.env # Треба да приказује AZURE_OPENAI_ENDPOINT, API_KEY, итд. ``` **PowerShell:** ```powershell -Get-Content ..\.env # Треба приказати AZURE_OPENAI_ENDPOINT, API_KEY и сл. +Get-Content ..\.env # Треба да приказује AZURE_OPENAI_ENDPOINT, API_KEY, итд. ``` -> **Напомена:** Команда `azd up` аутоматски генерише `.env` фајл. Ако треба касније да га ажурирате, можете га уредити ручно или га поново генерисати покретањем: +> **Белешка:** Наредба `azd up` аутоматски генерише `.env` датотеку. Ако је касније потребно да је ажурирате, можете уредити `.env` датотеку ручно или је регенерисати покретањем: > > **Bash:** > ```bash @@ -184,39 +184,39 @@ Get-Content ..\.env # Треба приказати AZURE_OPENAI_ENDPOINT, API_ ## Покретање апликације локално -**Проверите деплојмент:** +**Проверите деплој:** -Осигурајте да `.env` фајл постоји у коренском директоријуму са Azure акредитивима. Покрените ово из директоријума модула (`01-introduction/`): +Уверите се да `.env` датотека постоји у коренском директоријуму са Azure креденцијалима. Покрените ово из фасцикле модула (`01-introduction/`): **Bash:** ```bash -cat ../.env # Треба да прикаже AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Треба да приказује AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Требало би да приказује AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Требало би да прикаже AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Покрените апликације:** -**Опција 1: Користећи Spring Boot Dashboard (препоручено за кориснике VS Code-а)** +**Опција 1: Коришћење Spring Boot Dashboard (препоручено за кориснике VS Code-a)** -Дев контејнер укључује екстензију Spring Boot Dashboard која пружа визуелни интерфејс за управљање свим Spring Boot апликацијама. Можете је пронаћи на Activity Bar-у на левој страни VS Code-а (потражите икону Spring Boot). +Дев контејнер укључује проширење Spring Boot Dashboard, које обезбеђује визуелни интерфејс за управљање свим Spring Boot апликацијама. Можете га пронаћи у траци активности лево у VS Code-у (потражите икону Spring Boot-a). Из Spring Boot Dashboard-а можете: - Видети све доступне Spring Boot апликације у радном простору - Покретати/заустављати апликације једним кликом - Пратити логове апликације у реалном времену -- Надгледати статус апликације +- Праћење статуса апликације -Једноставно кликните дугме за покретање поред "introduction" да покренете овај модул, или покрените све модуле одједном. +Само кликните на дугме за покретање поред "introduction" да покренете овај модул, или покрените све модуле одједном. Spring Boot Dashboard -*Spring Boot Dashboard у VS Code-у — покрените, зауставите и пратите све модуле са једног места* +*Spring Boot Dashboard у VS Code — покрени, заустави и прати све модуле са једног места* -**Опција 2: Користећи shell скрипте** +**Опција 2: Коришћење shell скрипти** Покрените све веб апликације (модуле 01-04): @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Оба скрипта аутоматски учитавају променљиве окружења из коренског `.env` фајла и састављају JAR-ове ако не постоје. +Обе скрипте аутоматски учитавају променљиве окружења из коренске `.env` датотеке и саставиће JAR датотеке ако не постоје. -> **Напомена:** Ако више волите да ручно компајлирате све модуле пре покретања: +> **Белешка:** Ако више волите ручно да градите све модуле пре покретања: > > **Bash:** > ```bash @@ -262,9 +262,9 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -Отворите http://localhost:8080 у вашем претраживачу. +Отворите http://localhost:8080 у вашем прегледачу. -**Да зауставите:** +**Да бисте зауставили:** **Bash:** ```bash @@ -282,41 +282,41 @@ cd ..; .\stop-all.ps1 # Сви модули ## Коришћење апликације -Апликација пружа веб интерфејс са две имплементације ћаскања поредане једна поред друге. +Апликација пружа веб интерфејс са две имплементације ћаскања једна поред друге. -Application Home Screen +Почетни екран апликације -*Контролна табла показује опције за Једноставан Чет (без стања) и Конверзациони Чет (са стањем)* +*Контролна табла која показује и Општи ћаскање (без стања) и Конверзацијски ћаскање (са стањем)* -### Чет без стања (леви панел) +### Беспрекорно ћаскање (леви панел) -Прво испробајте ову опцију. Реците "Зовем се Јован" и одмах онда питајте "Како ми се зовеш?" Модел неће памтити јер је свака порука независна. Ово показује основни проблем интеграције језичког модела — нема контекста разговора. +Прво испробајте ово. Реците "Зовем се Јован" и одмах затим питајте "Које ми је име?" Модел неће памтити јер је свака порука независна. Ово демонстрира основни проблем интеграције језичког модела - нема контекст разговора. -Stateless Chat Demo +Демо беспрекорног ћаскања *АИ не памти ваше име из претходне поруке* -### Чет са стањем (десни панел) +### Са стањем ћаскање (десни панел) -Сада испробајте исти низ овде. Реците "Зовем се Јован" и онда "Како ми се зовеш?" Овог пута памти. Разлика је у MessageWindowChatMemory - она одржава историју разговора и укључује је у сваки захтев. Овако функционише продукцијски конверзациони АИ. +Сада испробајте исти низ овде. Реците "Зовем се Јован" и затим "Које ми је име?" Овог пута памти. Разлика је у MessageWindowChatMemory - он одржава историју разговора и укључује је у сваки захтев. Ово је начин на који продукцијски конверзацијски АИ ради. -Stateful Chat Demo +Демо ћаскања са стањем -*АИ памти ваше име из ранијег дела разговора* +*АИ се сећа вашег имена из ранијег дела разговора* -Обa панела користе исти GPT-5.2 модел. Једина разлика је меморија. Ово јасно показује шта меморија доноси вашој апликацији и зашто је важна за стварне случајеве коришћења. +Оба панела користе исти GPT-5.2 модел. Једина разлика је меморија. Ово јасно показује шта меморија доноси вашој апликацији и зашто је неопходна за праве случајеве коришћења. ## Следећи кораци -**Следећи модул:** [02-prompt-engineering - Инжењеринг упита са GPT-5.2](../02-prompt-engineering/README.md) +**Следећи модул:** [02-prompt-engineering - Prompt Engineering са GPT-5.2](../02-prompt-engineering/README.md) --- -**Навигација:** [← Претходни: Модул 00 - Брзи почетак](../00-quick-start/README.md) | [Назад на главну](../README.md) | [Следећи: Модул 02 - Инжењеринг упита →](../02-prompt-engineering/README.md) +**Навигација:** [← Назад на Главну](../README.md) | [Следећи: Модул 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **Изјава о одрицању одговорности**: -Овај документ је преведен уз помоћ AI преводилачке услуге [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо прецизности, имајте у виду да аутоматизовани преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати званичним извором. За критичне информације препоручује се професионални људски превод. Не прихватамо одговорност за било каква неспоразума или погрешна тумачења која произилазе из употребе овог превода. +Овај документ је преведен коришћењем услуге за аутоматски превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода. \ No newline at end of file diff --git a/translations/sr/02-prompt-engineering/README.md b/translations/sr/02-prompt-engineering/README.md index 05c7ae5a5..753d8df89 100644 --- a/translations/sr/02-prompt-engineering/README.md +++ b/translations/sr/02-prompt-engineering/README.md @@ -2,84 +2,84 @@ ## Садржај -- [Видео преглед](../../../02-prompt-engineering) -- [Шта ћете научити](../../../02-prompt-engineering) -- [Предзнања](../../../02-prompt-engineering) -- [Разумевање инжењеринга упита](../../../02-prompt-engineering) -- [Основе инжењеринга упита](../../../02-prompt-engineering) - - [Zero-Shot упити](../../../02-prompt-engineering) - - [Few-Shot упити](../../../02-prompt-engineering) - - [Ланац размишљања](../../../02-prompt-engineering) - - [Упити засновани на улогама](../../../02-prompt-engineering) - - [Шаблони упита](../../../02-prompt-engineering) -- [Напредни обрасци](../../../02-prompt-engineering) -- [Покрени апликацију](../../../02-prompt-engineering) -- [Снимци екрана апликације](../../../02-prompt-engineering) -- [Истраживање образаца](../../../02-prompt-engineering) - - [Низак против високог ентузијазма](../../../02-prompt-engineering) - - [Извођење задатка (Уводи алата)](../../../02-prompt-engineering) - - [Саморефлектирајући код](../../../02-prompt-engineering) - - [Структурисана анализа](../../../02-prompt-engineering) - - [Вишекратно ћаскање](../../../02-prompt-engineering) - - [Разумевање корак по корак](../../../02-prompt-engineering) - - [Ограничен излаз](../../../02-prompt-engineering) -- [Шта заиста учите](../../../02-prompt-engineering) -- [Следећи кораци](../../../02-prompt-engineering) - -## Видео преглед - -Погледајте ову уживо сесију која објашњава како почети са овим модулом: +- [Преглед видео снимка](#преглед-видео-снимка) +- [Шта ћете научити](#шта-ћете-научити) +- [Претпоставке](#претпоставке) +- [Разумевање инжењеринга упита](#разумевање-инжењеринга-упита) +- [Основе инжењеринга упита](#основе-инжењеринга-упита) + - [Zero-Shot упити](#zero-shot-упити) + - [Few-Shot упити](#few-shot-упити) + - [Ланац размишљања](#ланац-размишљања) + - [Упити засновани на улогама](#упити-засновани-на-улогама) + - [Шаблони упита](#шаблони-упита) +- [Напредни шаблони](#напредни-шаблони) +- [Покретање апликације](#покретање-апликације) +- [Снимци екрана апликације](#снимци-екрана-апликације) +- [Истраживање шаблона](#истраживање-шаблона) + - [Низак у односу на висок ниво воље](#ниска-у-односу-на-високу-жељу) + - [Извођење задатака (Уводи у алате)](#извођење-задатка-увод-у-алате) + - [Код који се самоанализа](#саморефлектујући-код) + - [Структурисана анализа](#структурисана-анализа) + - [Више-окретни разговор](#вишекратни-разговор) + - [Размишљање корак по корак](#размишљање-корак-по-корак) + - [Ограничен излаз](#ограничен-излаз) +- [Шта заиста учите](#шта-заправо-учите) +- [Следећи кораци](#следећи-кораци) + +## Преглед видео снимка + +Погледајте ову уживо сесију која објашњава како започети са овим модулом: Prompt Engineering with LangChain4j - Live Session ## Шта ћете научити -Следећа дијаграм пружа преглед кључних тема и вештина које ћете развити у овом модулу — од техника усавршавања упита до корак по корак радног процеса који ћете пратити. +Следећа дијаграм пружа преглед кључних тема и вештина које ћете развити у овом модулу — од техника усавршавања упита до корак-по-корак процеса који ћете пратити. -What You'll Learn +Шта ћете научити -У претходним модулима истраживали сте основне интеракције LangChain4j са GitHub моделима и видели како меморија омогућава разговорни АИ са Azure OpenAI. Сада ћемо се фокусирати на начин на који постављате питања — саме упите — користећи Azure OpenAI GPT-5.2. Начин на који структурирате своје упите драстично утиче на квалитет одговора које добијате. Започињемо прегледом основних техника упитивања, а затим прелазимо на осам напредних образаца који у потпуности искоришћавају могућности GPT-5.2. +У претходном модулу сте видели како меморија омогућава конверзацијалну вештачку интелигенцију са Azure OpenAI. Сада ћемо се фокусирати на то како постављате питања — односно саме упите — користећи Azure OpenAI GPT-5.2. Начин на који структурирате упите драматично утиче на квалитет одговора које добијате. Започињемо прегледом основних техника упита, а затим прелазимо на осам напредних шаблона који у потпуности користе могућности GPT-5.2. -Користићемо GPT-5.2 јер уводи контролу размишљања - можете рећи моделу колико размишљања да уради пре одговора. Ово издваја различите стратегије упитивања и помаже вам да разумете када која приступа применити. Такође ћемо имати користи од мањих ограничења Azure код GPT-5.2 у поређењу са GitHub моделима. +Користићемо GPT-5.2 јер уводи контролу размишљања — можете модели рећи колико треба да размишља пре одговора. То различите стратегије упита чини приметнијим и помаже вам да разумете када користити који приступ. -## Предзнања +## Претпоставке - Завршен Модул 01 (Azure OpenAI ресурси распоређени) -- `.env` датотека у коренском директоријуму са Azure акредитивима (креирана командом `azd up` у Модулу 01) +- `.env` фајл у коренском директоријуму са Azure акредитивима (направљен командом `azd up` у Модулу 01) -> **Напомена:** Ако нисте завршили Модул 01, најпре пратите упутства за распоређивање тамо. +> **Напомена:** Ако нисте завршили Модул 01, прво пратите упутства за распоређивање тамо. ## Разумевање инжењеринга упита -У сржи, инжењеринг упита је разлика између нејасних и прецизних упутстава, као што поређење испод илуструје. +У сржи, инжењеринг упита је разлика између нејасних инструкција и прецизних, као што илуструје поређење у наставку. -What is Prompt Engineering? +Шта је инжењеринг упита? -Инжењеринг упита је о дизајнирању улазног текста који вам конзистентно даје резултате које желите. Није само питање како поставити питања - већ како структуирати захтеве да модел тачно разуме шта желите и како да то испоручи. +Инжењеринг упита је о дизајнирању улазног текста који доследно добија резултате које желите. Није само постављање питања — већ структурирање захтева тако да модел тачно разуме шта желите и како то испоручити. -Замислите то као да дајете упутства колеги. „Поправи грешку“ је нејасно. „Поправи NullPointerException у UserService.java линији 45 додавањем провере за null“ је прецизно. Језички модели функционишу исто — прецизност и структура су важни. +Размишљајте о томе као да дајете упутства колеги. "Поправи грешку" је нејасно. "Поправи NullPointerException у UserService.java на линији 45 додавањем провере нуле" је прецизно. Језички модели раде исто тако — прецизност и структура су битни. -Дијаграм испод показује како LangChain4j уклапа ову слику — повезујући ваше обрасце упита са моделом кроз грађевне блокове SystemMessage и UserMessage. +Дијаграм испод показује како LangChain4j уклапа у ову слику — повезујући ваше шаблоне упита са моделом преко SystemMessage и UserMessage грађевних блокова. -How LangChain4j Fits +Како LangChain4j уклапа -LangChain4j пружа инфраструктуру — везе са моделом, меморију и типове порука — док су обрасци упита само пажљиво структурисан текст који шаљете кроз ту инфраструктуру. Кључни грађевни блокови су `SystemMessage` (који поставља понашање и улогу АИ) и `UserMessage` (који садржи ваш стварни захтев). +LangChain4j пружа инфраструктуру — везе са моделом, меморију и типове порука — док су шаблони упита само пажљиво структурисан текст који преко те инфраструктуре шаљете. Кључни градивни блокови су `SystemMessage` (који поставља понашање и улогу АИ) и `UserMessage` (који носи ваш стварни захтев). ## Основе инжењеринга упита -Пет основних техника приказаних испод чине темељ ефикасног инжењеринга упита. Свака се бави различитим аспектом начина на који комуницирате са језичким моделима. +Пет основних техника приказаних доле чине темеље ефективног инжењеринга упита. Свака се бави другим аспектом комуникације са језичким моделима. -Five Prompt Engineering Patterns Overview +Преглед пет шаблона инжењеринга упита -Пре него што заронимо у напредне образце овог модула, хајде да прегледамо пет темељних техника упитивања. Они су грађевни блокови које сваки инжењер упита треба да познаје. Ако сте већ радили кроз [Quick Start модул](../00-quick-start/README.md#2-prompt-patterns), видели сте их у акцији — ево концептуалног оквира иза њих. +Пре него што заронимо у напредне шаблоне овог модула, хајде да прегледамо пет основних техника упита. Ово су грађевински блокови које сваки инжењер упита треба да познаје. ### Zero-Shot упити -Најједноставнији приступ: дајте моделу директну инструкцију без примера. Модел се потпуно ослања на своју обуку да разуме и изврши задатак. Ово добро функционише за једноставне захтеве где је очекивано понашање јасно. +Најједноставнији приступ: дајте моделу директну инструкцију без примера. Модел у потпуности зависи од свог тренинга да разуме и изврши задатак. Ово добро функционише за једноставне захтеве где је очекивано понашање очигледно. -Zero-Shot Prompting +Zero-Shot упити -*Директна инструкција без примера — модел закључује задатак само из упутства* +*Директна инструкција без примера — модел изводи задатак само из инструкције* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Одговор: "Позитивно" ``` -**Када користити:** Једноставне класификације, директна питања, преводи или било који задатак који модел може обрадити без додатних упутстава. +**Када користити:** Једноставне класификације, директна питања, преводи или било који задатак који модел може решити без додатних упутстава. ### Few-Shot упити -Пружајте примере који показују образац који желите да модел следи. Модел учи очекивани улазно-излазни формат из ваших примера и примењује га на нове уносе. Ово драстично побољшава конзистенцију за задатке где жељени формат или понашање нису очигледни. +Дајте примере који показују образац који желите да модел прати. Модел учи очекивани формат улаз-излаз из ваших примера и примењује га на нове уносе. Ово драматично побољшава конзистентност за задатке где форматирање или понашање нису очигледни. -Few-Shot Prompting +Few-Shot упити -*Учимо из примера — модел идентификује образац и примењује га на нове уносе* +*Учитење из примера — модел идентификује образац и примењује га на нове уносе* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Када користити:** Прилагођене класификације, конзистентно форматирање, доменски специфични задаци или када zero-shot резултати нису конзистентни. +**Када користити:** Прилагођене класификације, доследно форматирање, доменски специфични задаци или када Zero-Shot резултати нису конзистентни. ### Ланац размишљања -Замолите модел да приказује своје размишљање корак по корак. Уместо да одмах да одговор, модел разлаже проблем и ради кроз сваки део експлицитно. Ово побољшава прецизност на задацима из математике, логике и разматрању у више корака. +Замолите модел да покаже своје разматрање корак по корак. Уместо да прескаче директно на одговор, модел разлаже проблем и ради кроз сваки део јасно. Ово побољшава тачност код математичких, логичких и вишестепених задатака. -Chain of Thought Prompting +Ланац размишљања -*Размишљање корак по корак — разлагање сложених проблема у експлицитне логичке кораке* +*Размишљање корак по корак — разлагање сложених проблема у јасне логичке кораке* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Модел показује: 15 - 8 = 7, затим 7 + 12 = 19 јабука ``` -**Када користити:** Математички задаци, логичке слагалице, отклањање грешака или било који задатак где приказивање процеса размишљања побољшава прецизност и поверење. +**Када користити:** Математички проблеми, логичке загонетке, дебаговање или било који задатак где показивање процеса размишљања побољшава тачност и поверење. ### Упити засновани на улогама -Поставите личност или улогу АИ-ју пре него што поставите питање. Ово пружа контекст који обликује тон, дубину и фокус одговора. „Софтверски архитекта“ даје другачије савете од „млађег програмера“ или „безбедносног ревизора“. +Поставите особу или улогу АИ пре постављања питања. Ово даје контекст који обликује тон, дубину и фокус одговора. "Софтверски архитекта" даје другачије савете од "млађег програмера" или "ревизора безбедности". -Role-Based Prompting +Упити засновани на улогама -*Постављање контекста и личности — исто питање добија различит одговор у зависности од додељене улоге* +*Постављање контекста и улоге — исто питање добија различит одговор у зависности од додељене улоге* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Када користити:** Прегледи кода, туторална помоћ, доменски специфичне анализе или када су вам потребни одговори прилагођени одређеном нивоу стручности или перспективи. +**Када користити:** Прегледи кода, туторство, анализе специфичне за домен или кад су вам потребни одговори прилагођени нивоу стручности или перспективи. ### Шаблони упита -Креирајте поновно употребљиве упите са променљивим местима за уметање. Уместо да сваки пут пишете нови упит, дефинишите шаблон једном и попуњавајте различите вредности. LangChain4j класа `PromptTemplate` то олакшава са синтаксом `{{variable}}`. +Креирајте поновно употребљиве упите са променљивим параметрима. Уместо да сваки пут пишете нови упит, дефинишите шаблон једном и попуњавајте различите вредности. LangChain4j класа `PromptTemplate` то олакшава са `{{variable}}` синтаксом. -Prompt Templates +Шаблони упита -*Поновно употребљиви упити са променљивим местима — један шаблон, више употреба* +*Поновно употребљиви упити са променљивим параметрима — један шаблон, многе употребе* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Када користити:** Понављани упити са различитим уносима, обрада у пакетима, градња поново употребљивих АИ радних токова или било који сценарио где структура упита остаје иста, али се подаци мењају. +**Када користити:** Поновљени упити са различитим уносима, пакетна обрада, грађење поновно употребљивих AI радних токова или било која ситуација где структура упита остаје иста, али се подаци мењају. --- -Ових пет основа вам дају проверен скуп алата за већину задатака упитивања. Остатак овог модула надограђује по њима са **осам напредних образаца** који искоришћавају GPT-5.2 контролу размишљања, самопроцену и могућности структурисаног излаза. +Ових пет основа пружају вам солидан алат за већину задатака упита. Остатак овог модула гради на њима са **осам напредних шаблона** који искоришћавају контролу размишљања, самоевалуцију и могућности структурисаног излаза GPT-5.2. -## Напредни обрасци +## Напредни шаблони -Са обрадом основа прецртана, пређимо на осам напредних образаца који овај модул чине јединственим. Ни сви проблеми не захтевају исти приступ. Нека питања траже брзе одговоре, друга дубоко размишљање. Неки траже видљиво размишљање, други само резултате. Сваки образац испод је оптимизован за другачији сценарио — а GPT-5.2 контрола размишљања чини разлике још израженијим. +Након разматрања основа, хајде да пређемо на осам напредних шаблона који овај модул чине јединственим. Неки проблеми не захтевају исти приступ. Нека питања тражe брзе одговоре, друга дубоко размишљање. Нека захтевају видљиво размишљање, друга само резултате. Сваки шаблон испод је оптимизован за различиту ситуацију — а контролa размишљања GPT-5.2 ове разлике чини још израженијим. -Eight Prompting Patterns +Осам шаблона инжењеринга упита -*Преглед осам образаца инжењеринга упита и њихове примене* +*Преглед осам шаблона инжењеринга упита и њихових употреба* -GPT-5.2 додаје још једну димензију овим образцима: *контролу размишљања*. Клизач испод показује како можете подесити колико напора модел треба уложити у размишљање — од брзих, директних одговора до дубоке, темељне анализе. +GPT-5.2 додаје још једну димензију овим шаблонима: *контролу размишљања*. Линијски контролер испод показује како можете подесити напор модела — од брзих, директних одговора до дубоке, темељне анализе. -Reasoning Control with GPT-5.2 +Контрола размишљања са GPT-5.2 -*GPT-5.2 контрола размишљања вам омогућава да одредите колико размишљања модел треба да уради — од брзих директних одговора до дубоке експлорације* +*Контрола размишљања GPT-5.2 вам омогућава да одредите колико модел треба да размишља — од брзих директних одговора до дубоке истраге* -**Низак ентузијазам (Брзо & Фокусирано)** - За једноставна питања где желите брзе, директне одговоре. Модел прави минимално размишљање - максимум 2 корака. Користите ово за прорачуне, претраге или једноставна питања. +**Низак ниво воље (брзо и фокусирано)** - За једноставна питања где желите брзе, директне одговоре. Модел врши минимално размишљање - максимум 2 корака. Користите ово за калкулације, претраге или једноставна питања. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Истражите са GitHub Copilot:** Отворите [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) и питајте: -> - "Која је разлика између ниског и високог ентузијазма код упитних образаца?" -> - "Како XML ознаке у упитима помажу у структурирању одговора АИ-ја?" -> - "Када треба користити образце саморефлексије у односу на директна упутства?" +> - "Која је разлика између образаца упита са ниским и високим нивоом воље?" +> - "Како XML тагови у упитима помажу у структуирању одговора АИ?" +> - "Када треба користити шаблоне самоанализа уместо директних инструкција?" -**Висок ентузијазам (Дубоко & Темељно)** - За сложене проблеме где желите свеобухватну анализу. Модел темељно истражује и показује детаљно размишљање. Користите ово за дизајн система, архитектонске одлуке или сложена истраживања. +**Висок ниво воље (дубоко и темељно)** - За комплексне проблеме где желите свеобухватну анализу. Модел темељно истражује и показује детаљно размишљање. Користите ово за дизајн система, архитектонске одлуке или сложена истраживања. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Извођење задатка (Напредовање корак по корак)** - За радне токове у више корака. Модел пружа почетни план, приповеда сваки корак док ради, па даје резиме. Користите ово за миграције, имплементације или било који процес са више корака. +**Извођење задатака (наступ у корацима)** - За вишестепене радне токове. Модел пружа план унапред, прича о сваком кораку док ради и даје резиме. Користите ово за миграције, имплементације или било који вишестепени процес. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Ланац размишљања експлицитно тражи од модела да прикаже свој процес размишљања, побољшавајући прецизност за сложене задатке. Разлагање корак по корак помаже и људима и АИју да разумеју логику. +Ланац-размишљања упити јасно траже од модела да прикаже свој процес размишљања, побољшавајући тачност за сложене задатке. Разлагање корак по корак помаже и људима и АИ да разумеју логику. -> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Chat:** Питајте о овом образцу: -> - "Како бих прилагодио образац извођења задатка за дуготрајне операције?" -> - "Које су најбоље праксе за структурирање уводних делова алата у продукционим апликацијама?" -> - "Како могу да снимим и прикажем међупроседне извештаје о напретку у корисничком интерфејсу?" +> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Четом:** Питајте о овом шаблону: +> - "Како бих прилагодио образац извођења задатака за дуготрајне операције?" +> - "Које су најбоље праксе за структуирање уводних делова алата у продукцијским апликацијама?" +> - "Како могу пратити и приказати међупрогресне извештаје у корисничком интерфејсу?" -Дијаграм испод илуструје овај План → Извршење → Резиме радни ток. +Дијаграм у наставку илуструје овај радни ток План → Извршење → Резиме. -Task Execution Pattern +Образац извођења задатака -*План → Извршење → Резиме радног тока за задатке у више корака* +*Радни ток План → Извршење → Резиме за вишестепене задатке* -**Саморефлектирајући код** - За генерисање кода квалитета погодног за продукцију. Модел генерише код који прати продукционе стандарде са одговарајућом обрадом грешака. Користите ово при изградњи нових функција или сервиса. +**Код који се самоанализа** - За генерисање кода производног квалитета. Модел генерише код који следи стандардe продукције са исправним руковањем грешкама. Користите ово када градите нове карактеристике или сервисе. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Дијаграм испод показује овај итеративни циклус унапређења — генериши, евалуирај, идентификуј слабости и усавршавај док код не испуни продукционе стандарде. +Дијаграм испод приказује ову итеративну петљу побољшања — генерисање, евалуација, идентификација слабости и усавршавање док код не достигне стандарде продукције. -Self-Reflection Cycle +Циклус самоанализа -*Итеративни циклус унапређења - генериши, оцени, идентификуј проблеме, унапреди, понављај* +*Итеративна петља побољшања - генерисање, евалуација, идентификација проблема, побољшање, понављање* -**Структурисана анализа** - За конзистентну евалуацију. Модел прегледа код користећи фиксни оквир (тачност, праксе, перформансе, безбедност, одрживост). Користите ово за прегледе кода или процену квалитета. +**Структурисана анализа** - За конзистентну евалуацију. Модел прегледа код користећи фиксни оквир (исправност, праксе, перформансе, безбедност, одрживост). Користите ово за прегледе кода или оцену квалитета. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Chat:** Питајте о структурисаној анализи: -> - "Како могу прилагодити оквир анализе за различите типове прегледа кода?" -> - "Који је најбољи начин за програмско парсирање и деловање по структурисаном излазу?" -> - "Како осигурати конзистентне нивое озбиљности у различитим сесијама прегледа?" +> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Четом:** Питајте о структурисаној анализи: +> - "Како могу прилагодити оквир за анализу за различите типове прегледа кода?" +> - "Који је најбољи начин да програмски тумачим и делујем према структуираном излазу?" +> - "Како да обезбедим конзистентне нивое озбиљности у различитим сесијама прегледа?" -Дијаграм испод показује како овај структурисани оквир организује преглед кода у конзистентне категорије са нивоима озбиљности. +Следећи дијаграм показује како овај структурисани оквир организује преглед кода у доследне категорије са нивоима озбиљности. -Structured Analysis Pattern +Образац структурисане анализе -*Оквир за конзистентне прегледе кода са нивоима озбиљности* +*Оквир за доследне прегледе кода са нивоима озбиљности* -**Вишекратно ћаскање** - За разговоре којима је потребан контекст. Модел памти претходне поруке и надовезује се на њих. Користите ово за интерактивне сесије помоћи или сложена питања и одговоре. +**Више-окретни разговор** - За разговоре који траже контекст. Модел памти претходне поруке и надограђује се на њима. Користите ово за интерактивне помоћне сесије или сложена питања и одговоре. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Дијаграм испод визуелно приказује како се контекст разговора акумулира током више корака и како то кореспондира са лимитом токена модела. +Дијаграм испод визуализује како се контекст разговора акумулира са сваким окретом и како се односи на лимит токена модела. -Context Memory +Меморија контекста -*Како се контекст разговора акумулира кроз више корака све док не достигне лимит токена* -**Корак по корак размишљање** - За проблеме који захтевају видљиву логику. Модел приказује јасно образложење за сваки корак. Користите ово за математичке проблеме, логичке загонетке или кад треба да разумете процес размишљања. +*Како се контекст разговора акумулира током више окрета док се не достигне лимит токена* + +**Размишљање корак по корак** - За проблеме који захтевају видљиву логику. Модел показује јасно размишљање за сваки корак. Користите ово за математичке проблеме, логичке загонетке или кад треба да разумете процес размишљања. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Дијаграм испод илуструје како модел разлаже проблеме у јасне, нумерисане логичке кораке. - -Step-by-Step Pattern +Дијаграм у наставку илуструје како модел разлаже проблеме у јасне, нумерисане логичке кораке. +Образац корак по корак *Разлагање проблема у јасне логичке кораке* -**Ограничен излаз** - За одговоре са специфичним захтевима формата. Модел строго прати правила формата и дужине. Користите ово за резиме или кад вам је потребна прецизна структура излаза. +**Ограничен излаз** - За одговоре са специфичним захтевима формата. Модел строго прати правила формата и дужине. Користите ово за резиме или када вам је потребна прецизна структура излаза. ```java String prompt = """ @@ -420,51 +420,51 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Следећи дијаграм показује како ограничења усмеравају модел да произведе излаз који строго поштује ваш формат и захтеве дужине. +Следећи дијаграм показује како ограничења усмеравају модел да произведе излаз који строго поштује ваше захтеве формата и дужине. -Constrained Output Pattern +Шаблон ограниченог излаза -*Примена специфичних захтева за формат, дужину и структуру* +*Спровођење специфичних захтева формата, дужине и структуре* ## Покретање апликације -**Потврдите развој:** +**Проверите имплементацију:** -Уверите се да фајл `.env` постоји у коренском директоријуму са Azure акредитивима (направљен током Модула 01). Покрените ово из директоријума модула (`02-prompt-engineering/`): +Уверите се да `.env` фајл постоји у коренском директоријуму са Azure акредитивима (креиран током Модула 01). Покрените ово из директоријума модула (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Требало би да прикаже AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Требало би да приказује AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Требало би да приказује AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Требало би да прикаже AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Покрените апликацију:** -> **Напомена:** Ако сте већ покренули све апликације користећи `./start-all.sh` из коренског директоријума (као што је описано у Модулу 01), овај модул већ ради на порту 8083. Можете прескочити наредбе за покретање испод и директно отићи на http://localhost:8083. +> **Напомена:** Ако сте већ покренули све апликације користећи `./start-all.sh` из коренског директоријума (као што је описано у Модулу 01), овај модул већ ради на порту 8083. Можете прескочити наредбе за покретање испод и одмах отићи на http://localhost:8083. -**Опција 1: Коришћење Spring Boot Dashboard (Препоручено за кориснике VS Code-а)** +**Опција 1: Коришћење Spring Boot Dashboard-а (Препоручено за кориснике VS Code-а)** -Развојни контејнер укључује екстензију Spring Boot Dashboard која пружа визуелни интерфејс за управљање свим Spring Boot апликацијама. Можете је пронаћи у Activity Бару са леве стране VS Code-а (потражите Spring Boot иконицу). +Dev контејнер укључује Spring Boot Dashboard екстензију, која обезбеђује визуелни интерфејс за управљање свим Spring Boot апликацијама. Можете је пронаћи у Activity Bar-у са леве стране VS Code-а (потражите Spring Boot икону). Из Spring Boot Dashboard-а можете: - Видети све доступне Spring Boot апликације у радном простору -- Покренути/зауставити апликације једним кликом -- Гледати дневнике апликација у реалном времену -- Пратити статус апликација +- Покренути/стопирати апликације једним кликом +- Пратити логове апликација у реалном времену +- Мониторисати статус апликације -Само кликните на дугме за покретање поред "prompt-engineering" да бисте стартовали овај модул, или покрените све модуле одједном. +Само кликните на дугме за покретање поред "prompt-engineering" да покренете овај модул, или покрените све модуле одједном. Spring Boot Dashboard -*Spring Boot Dashboard у VS Code — покрените, зауставите и пратите све модуле с једног места* +*Spring Boot Dashboard у VS Code-у — покрените, зауставите и пратите све модуле с једног места* **Опција 2: Коришћење shell скрипти** -Покрените све веб апликације (модуле 01-04): +Покрените све веб апликације (модули 01-04): **Bash:** ```bash @@ -492,7 +492,7 @@ cd 02-prompt-engineering .\start.ps1 ``` -Обе скрипте аутоматски учитавају променљиве окружења из коренског `.env` фајла и граде JAR фајлове ако не постоје. +Обе скрипте аутоматски учитавају променљиве окружења из коренског `.env` фајла и изградиће JAR-ове ако не постоје. > **Напомена:** Ако више волите да ручно изградите све модуле пре покретања: > @@ -508,9 +508,9 @@ cd 02-prompt-engineering > mvn clean package -DskipTests > ``` -Отворите http://localhost:8083 у вашем претраживачу. +Отворите http://localhost:8083 у вашем прегледачу. -**Да бисте зауставили:** +**За заустављање:** **Bash:** ```bash @@ -528,69 +528,69 @@ cd ..; .\stop-all.ps1 # Сви модули ## Снимци екрана апликације -Овде је главни интерфејс модула за prompt engineering, где можете истовремено експериментисати са сва осам образаца. +Ево главног интерфејса модула за инжењеринг упита, где можете експериментисати са свих осам шаблона поредано. -Dashboard Home +Почетна табла -*Главна табла која приказује свих 8 образаца за prompt engineering са карактеристикама и случајевима употребе* +*Главна табла која приказује свих 8 шаблона инжењеринга упита са карактеристикама и применицима* -## Истраживање Образаца +## Истраживање шаблона -Веб интерфејс вам омогућава да експериментишете са различитим стратегијама подстицања. Свако решење решава различите проблеме - испробајте их да видите када који приступ најбоље функционише. +Веб интерфејс вам омогућава да експериментишете са различитим стратегијама упита. Сваки шаблон решава различите проблеме - пробајте их да видите када сваки приступ најбоље функционише. -> **Напомена: Стримовање против не-стримовања** — Свако страницу са образцем нуди два дугмета: **🔴 Стримуј одговор (У живо)** и опцију **Не-стримовање**. Стримовање користи Server-Sent Events (SSE) за приказивање токена у реалном времену како модел генерише одговор, тако да видите напредак одмах. Опција не-стримовања чека цео одговор пре него што га покаже. За подстицаје који изазивају дубоко разумевање (нпр. High Eagerness, Self-Reflecting Code), не-стримовање може трајати веома дуго — понекад и минутима — без икакве видљиве повратне информације. **Користите стримовање када експериментишете са сложеним подстицајима** да бисте видели модел у раду и избегли утисак да је време за одговор истекло. +> **Напомена: Стриминг у односу на не-стриминг** — Свакој страници са шаблоном нуди се два дугмета: **🔴 Stream Response (Уживо)** и опција **Без стриминга**. Стриминг користи Server-Sent Events (SSE) да приказује токене у реалном времену како их модел генерише, тако да видите напредак одмах. Без-стриминг опција чека цео одговор пре приказивања. За упите који покрећу дубоко размишљање (нпр. Висока жеља, Саморефлектујући код), позив без стриминга може трајати врло дуго — понекад и минуте — без видљиве повратне информације. **Користите стриминг када експериментишете са сложеним упитима** да бисте видели модел у раду и избегли утисак да је захтев истекао. > -> **Напомена: Захтев претраживача** — Стримовање користи Fetch Streams API (`response.body.getReader()`) који захтева пун претраживач (Chrome, Edge, Firefox, Safari). Не функционише у уграђеном једноставном претраживачу VS Code-а, јер његов webview не подржава ReadableStream API. Ако користите Simple Browser, дугмад за не-стримовање ће радити нормално — само дугмад за стримовање су погођена. Отворите `http://localhost:8083` у спољном претраживачу за пуну функционалност. +> **Напомена: Захтеви прегледача** — Стриминг функција користи Fetch Streams API (`response.body.getReader()`) који захтева пун прегледач (Chrome, Edge, Firefox, Safari). Не ради у уграђеном Simple Browser-у у VS Code-у, јер његов webview не подржава ReadableStream API. Ако користите Simple Browser, дугмад за не-стриминг и даље раде нормално — само су дугмад за стриминг утицана. Отворите `http://localhost:8083` у спољном прегледачу за пуну функционалност. -### Ниска и висока жеља (Eagerness) +### Ниска у односу на високу жељу -Поставите једноставно питање као „Колико је 15% од 200?“ користећи Low Eagerness. Добићете тренутан, директан одговор. Сада поставите нешто сложеније као „Дизајнирај стратегију кеширања за API са великим саобраћајем“ користећи High Eagerness. Кликните **🔴 Стримуј одговор (У живо)** и пратите детаљно разматрање модела, корак по корак. Исти модел, иста структура питања - али подстицај му говори колико дубоко да размишља. +Поставите једноставно питање као „Шта је 15% од 200?“ користећи ниску жељу. Добићете тренутан, директан одговор. Сада питајте нешто сложено као „Дизајнирај стратегију кеширања за API са великим прометом“ користећи високу жељу. Кликните **🔴 Stream Response (Уживо)** и пратите детаљно размишљање модела које се појављује токен по токен. Исти модел, иста структура питања - али упит му говори колико дубоко треба да размишља. -### Извршење задатка (Предговори алата) +### Извођење задатка (Увод у алате) -Вишестепени радни токови имају користи од раног планирања и пратње напретка. Модел описује шта ће урадити, извештава о сваком кораку, затим сабира резултате. +Вишестепени токови рада добијају корист од унапред планирања и нарације напретка. Модел описује шта ће урадити, прича о сваком кораку и затим сумира резултате. -### Само-рефлектујући код +### Саморефлектујући код -Покушајте „Креирај услугу за валидацију е-поште“. Уместо да само генерише код и стане, модел генерише, процењује према критеријумима квалитета, открива слабости и унапређује. Видећете како понавља док код не достигне производне стандарде. +Пробајте „Креирај сервис за проверу е-поште“. Уместо да само генерише код и стане, модел генерише, оцењује по критеријумима квалитета, идентификује слабости и побољшава. Видећете како врши итерације док код не достигне производни ниво. ### Структурисана анализа -Ревизије кода захтевају доследне оквире за процену. Модел анализира код користећи фиксне категорије (тачност, праксе, перформансе, безбедност) са нивоима озбиљности. +Прегледи кода захтевају доследне оквире за оцењивање. Модел анализира код користећи фиксне категорије (исправност, пракса, перформансе, безбедност) са нивоима озбиљности. ### Вишекратни разговор -Питајте „Шта је Spring Boot?“ а затим одмах наставите са „Прикажи ми пример“. Модел памти ваше прво питање и даје пример Spring Boot-а посебно за то. Без меморије, друго питање би било превасходно неодређено. +Питајте „Шта је Spring Boot?“ па затим одмах „Покажи ми пример“. Модел памти ваше прво питање и даје пример Spring Boot-а посебно за вас. Без меморије, друго питање би било пренаглашено. -### Корак по корак размишљање +### Размишљање корак по корак -Изаберите математички проблем и покушајте га са и Step-by-Step Reasoning и Low Eagerness. Ниска жеља вам само даје одговор - брзо, али нејасно. Корак по корак приказује свака рачунања и одлуке. +Изаберите математички проблем и пробајте га са Размишљањем корак по корак и ниском жељом. Ниска жеља само даје одговор — брзо али непрозирно. Корак по корак вам показује сваки израчун и одлуку. ### Ограничен излаз -Када вам требају специфични формати или број речи, овај образац примењује строгу дисциплину. Покушајте са генерацијом резимеа од тачно 100 речи у формату листе. +Када су вам потребни специфични формати или број речи, овај шаблон спроводи строго поштовање правила. Покушајте да генеришете резиме са тачно 100 речи у формату тачкица. ## Шта заправо учите **Напор размишљања мења све** -GPT-5.2 вам омогућава да контролишете рачунарски напор кроз ваше подстицаје. Низак напор значи брзе одговоре са минималном претрагом. Висок напор значи да модел узима време за дубоко размишљање. Учите како ускладити напор са сложеношћу задатка - не губите време на једноставна питања, али ни не журите са сложеним одлукама. +GPT-5.2 вам омогућава да контролишете рачунарски напор кроз ваше упите. Ниски напор значи брзе одговоре са минималним истраживањем. Високи напор значи да модел узима време за дубоко размишљање. Учите како да ускладите напор са сложеношћу задатка — немојте трошити време на једноставна питања, али немојте ни журити са сложеним одлукама. -**Структура усмеравa понашање** +**Структура води понашање** -Примећујете ли XML ознаке у подстицајима? Оне нису декоративне. Модели поузданије прате структуиране инструкције него слободан текст. Када су вам потребни вишестепени процеси или сложена логика, структура помаже моделу да прати где је и шта следи. Дијаграм испод разлаже добро структуриран подстицај, показујући како ознаке као што су ``, ``, ``, ``, и `` организују ваше инструкције у јасне секције. +Приметите XML ознаке у упитима? Оне нису само декорација. Модели поузданије прате структуирана упутства него слободан текст. Када вам требају вишестепени процеси или сложена логика, структура помаже моделу да прати где се налази и шта следи. Дијаграм испод разлаже добро структуиран упит, показујући како ознаке као ``, ``, ``, ``, и `` организују ваша упутства у јасне секције. -Prompt Structure +Структура упита -*Анатомија добро структурираног подстицаја са јасним секцијама и организацијом у XML стилу* +*Анатомија добро структурираног упита са јасним секцијама и XML стилском организацијом* -**Квалитет кроз само-евалуацију** +**Квалитет кроз самоевалуацију** -Обрасци само-рефлексије раде тако што квалитетне критеријуме чине јасним. Уместо да се надате да модел „ради исправно“, ви му тачно кажете шта значи „исправно“: исправна логика, руковање грешкама, перформансе, безбедност. Модел онда може сам да процени свој излаз и унапреди га. Ово претвара генерисање кода из игре на срећу у контролисани процес. +Саморефлектујући шаблони раде тако што квалитативне критеријуме чине експлицитним. Уместо да се надају да модел „уради како треба“, ви му тачно кажете шта значи „како треба“: исправна логика, руковање грешкама, перформансе, безбедност. Модел онда може да оцени свој излаз и побољша га. Ово претвара генерисање кода из лутрије у процес. **Контекст је ограничен** -Вишестепени разговори функционишу тако што укључују историју порука у сваком захтеву. Али постоји ограничење - сваки модел има максималан број токена. Како разговори расту, потребне су стратегије да се задржи релевантан контекст без преласка лимита. Овај модул вам показује како меморија ради; касније ћете научити када да сумирате, када да заборавите, а када да добијете назад. +Вишекратни разговори раде укључивањем историје порука у сваки захтев. Али постоји ограничење - сваки модел има максималан број токена. Како разговори расту, потребне су стратегије да се сачува релевантни контекст без преласка границе. Овај модул вам показује како меморија функционише; касније ћете научити када да сумирате, када да заборављате, и када да враћате. ## Следећи кораци @@ -598,11 +598,11 @@ GPT-5.2 вам омогућава да контролишете рачунарс --- -**Навигација:** [← Претходни: Модул 01 - Увод](../01-introduction/README.md) | [Назад на главну страну](../README.md) | [Следећи: Модул 03 - RAG →](../03-rag/README.md) +**Навигација:** [← Претходни: Модул 01 - Увод](../01-introduction/README.md) | [Назад на главну](../README.md) | [Следећи: Модул 03 - RAG →](../03-rag/README.md) --- -**Одрицање одговорности**: -Овај документ је преведен помоћу АИ сервиса за превођење [Co-op Translator](https://github.com/Azure/co-op-translator). Иако се трудимо да превод буде тачан, имајте у виду да аутоматизовани преводи могу садржати грешке или нетачности. Изворни документ на његовом оригиналном језику треба сматрати ауторитетом. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која могу настати употребом овог превода. +**Изјава о одрицању одговорности**: +Овај документ је преведен коришћењем услуге за аутоматски превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода. \ No newline at end of file diff --git a/translations/sr/03-rag/README.md b/translations/sr/03-rag/README.md index 3c611ce3a..ee644d1cc 100644 --- a/translations/sr/03-rag/README.md +++ b/translations/sr/03-rag/README.md @@ -2,143 +2,142 @@ ## Садржај -- [Видео водич](../../../03-rag) -- [Шта ћете научити](../../../03-rag) -- [Предуслови](../../../03-rag) -- [Разумевање RAG-а](../../../03-rag) - - [Који RAG приступ овај туторијал користи?](../../../03-rag) -- [Како функционише](../../../03-rag) - - [Обрада докумената](../../../03-rag) - - [Креирање угнежђења](../../../03-rag) - - [Семантичко претраживање](../../../03-rag) - - [Генерисање одговора](../../../03-rag) -- [Покрени апликацију](../../../03-rag) -- [Коришћење апликације](../../../03-rag) - - [Отпреми документ](../../../03-rag) - - [Постави питања](../../../03-rag) - - [Провери референце извора](../../../03-rag) - - [Експериментиши са питањима](../../../03-rag) -- [Кључни појмови](../../../03-rag) - - [Стратегија раздвајања на делове](../../../03-rag) - - [Скорови сличности](../../../03-rag) - - [Чување у меморији](../../../03-rag) - - [Управљање контекстним прозором](../../../03-rag) -- [Када је RAG важан](../../../03-rag) -- [Следећи кораци](../../../03-rag) +- [Видео водич](#видео-водич) +- [Шта ћете научити](#шта-ћете-научити) +- [Претпоставке](#претпоставке) +- [Разумевање RAG](#разумевање-rag) + - [Који RAG приступ овај туторијал користи?](#који-rag-приступ-овај-туторијал-користи) +- [Како ради](#како-ради) + - [Обрада докумената](#обрада-докумената) + - [Креирање угнежђења](#креирање-угнежђења) + - [Семантичка претрага](#семантичка-претрага) + - [Генерисање одговора](#генерисање-одговора) +- [Покрени апликацију](#покретање-апликације) +- [Коришћење апликације](#коришћење-апликације) + - [Отпреми документ](#отпремање-документа) + - [Постави питања](#постављање-питања) + - [Провери изворне референце](#провера-извора) + - [Играј се са питањима](#експериментишите-са-питањима) +- [Кључни концепти](#кључни-појмови) + - [Стратегија комадања](#стратегија-деловања-chunking) + - [Скорови сличности](#оцене-сличности) + - [Чување у меморији](#складиштење-у-меморији) + - [Управљање прозором контекста](#управљање-прозором-контекста) +- [Када RAG значи](#када-је-rag-важан) +- [Следећи кораци](#следећи-кораци) ## Видео водич -Погледајте ову уживо сесију која објашњава како почети са овим модулом: +Погледајте ову уживо сесију која објашњава како да започнете са овим модулом: -RAG са LangChain4j - Уживо сесија +RAG with LangChain4j - Live Session ## Шта ћете научити -У претходним модулима сте научили како водити разговоре са вештачком интелигенцијом и како ефикасно структуирати своје упите. Али постоји основно ограничење: језички модели знају само оно што су научили током тренинга. Нису у стању да одговоре на питања о политикама ваше компаније, пројектној документацији или било којој информацији за коју нису тренирани. +У претходним модулима сте учили како да водите разговоре са AI и како ефикасно структуирате своје упите. Али постоји основно ограничење: језички модели знају само оно што су научили током тренинга. Они не могу одговорити на питања о политикама ваше компаније, документацији пројекта или било којој информацији на којој нису тренирани. -RAG (Retrieval-Augmented Generation) решава овај проблем. Уместо да покушавате да модел учите вашим информацијама (што је скупо и непрактично), дајете му могућност да претражује ваше документе. Када неко постави питање, систем пронађе релевантне информације и укључи их у упит. Модел онда одговара на основу тог пронађеног контекста. +RAG (Retrieval-Augmented Generation) решава овај проблем. Уместо да покушавате да модел научите вашим информацијама (што је скупо и непрактично), дајете му могућност да претражује ваше документе. Када неко постави питање, систем пронађе релевантне информације и укључује их у упит. Модел затим одговара на основу тог пронађеног контекста. -Замислите RAG као библиотеку референци коју дајете моделу. Када поставите питање, систем: +Замислите RAG као дајете моделу референтну библиотеку. Када питате питање, систем: -1. **Кориснички упит** - Постављате питање -2. **Угнежђење** - Преводи ваше питање у вектор -3. **Претрага вектора** - Проналази сличне делове документа -4. **Састављање контекста** - Додаје релевантне делове у упит -5. **Одговор** - LLM генерише одговор на основу контекста +1. **Кориснички упит** - Ви постављате питање +2. **Угнежђење** - Претвара ваше питање у вектор +3. **Векторска претрага** - Проналази сличне делове докумената +4. **Склапање контекста** - Додаје релевантне делове у упит +5. **Одговор** - LLM генерише одговор на основу контекста -Ово оснива одговоре модела на вашим стварним подацима, уместо да се ослања само на знање из тренинга или да смишља одговоре. +Ово у основи оснажује одговоре модела да буду засновани на вашим стварним подацима уместо да се ослањају на знање из тренинга или да измисле одговоре. -## Предуслови +## Претпоставке -- Завршен [Модул 00 - Брзи почетак](../00-quick-start/README.md) (за пример Easy RAG који се наводи касније у овом модулу) -- Завршен [Модул 01 - Увод](../01-introduction/README.md) (деплојовани Azure OpenAI ресурси, укључујући embedding модел `text-embedding-3-small`) -- Фајл `.env` у коренском директоријуму са Azure акредитивима (направљен комandom `azd up` у Модулу 01) +- Завршен [Модул 01 - Увод](../01-introduction/README.md) (Azure OpenAI ресурси распоређени, укључујући модел угнежђења `text-embedding-3-small`) +- `.env` фајл у коренском директоријуму са Azure акредитивима (креиран командом `azd up` у Модулу 01) -> **Белешка:** Ако нисте завршили Модул 01, прво пратите упутства за деплој. Команда `azd up` деплојује и GPT chat модел и embedding модел који користи овај модул. +> **Напомена:** Ако нисте завршили Модул 01, прво пратите инструкције за распоређивање ту. Команда `azd up` распоређује како GPT чат модел тако и модел угнежђења који користи овај модул. -## Разумевање RAG-а +## Разумевање RAG -Дијаграм испод илуструје основни концепт: уместо ослањања само на податке коришћене за тренинг модела, RAG му даје референтну библиотеку ваших докумената да их консултује пре него што генерише сваки одговор. +Дијаграм испод илуструје основни концепт: уместо да се ослања само на податке из тренинга модела, RAG му даје референтну библиотеку ваших докумената коју може консултовати пре генерисања сваког одговора. -Шта је RAG +What is RAG -*Овај дијаграм показује разлику између стандардног LLM-а (који нагађа на основу података за тренинг) и RAG-побољшаног LLM-а (који прво консултује ваше документе).* +*Овај дијаграм показује разлику између стандардног LLM-а (који погађа на основу тренинг података) и RAG-подржаног LLM-а (који прво консултује ваше документе).* -Ево како се делови повезују од краја до краја. Корисничко питање пролази кроз четири фазе — угнежђење, претрагу вектора, састављање контекста, и генерисање одговора — свака гради на претходној: +Ево како делови повезују крај до краја. Корисничко питање пролази кроз четири фазе — угнежђење, векторску претрагу, састављање контекста и генерисање одговора — свака градећи на претходној: -Архитектура RAG-а +RAG Architecture -*Овај дијаграм показује RAG pipeline од краја до краја — кориснички упит пролази кроз угнежђење, претрагу вектора, састављање контекста и генерисање одговора.* +*Овај дијаграм приказује крај-до-краја RAG проток — кориснички упит пролази кроз угнежђење, векторску претрагу, састављање контекста и генерисање одговора.* -Остатак овог модула детаљно обрађује сваку фазу, са кодом који можете покренути и модификовати. +Остатак овог модула детаљно описује сваки корак, са кодом који можете покренути и модификовати. ### Који RAG приступ овај туторијал користи? -LangChain4j нуди три начина за имплементацију RAG-а, сваки са различитим нивоом апстракције. Дијаграм испод их пореди један уз други: +LangChain4j нуди три начина за имплементацију RAG, сваки са различитим нивоом апстракције. Дијаграм испод их упоређује један поред другог: -Три RAG приступа у LangChain4j +Three RAG Approaches in LangChain4j -*Овај дијаграм упоређује три LangChain4j RAG приступа — Easy, Native и Advanced — показујући њихове кључне компоненте и када се сваки користи.* +*Овај дијаграм упоређује три LangChain4j RAG приступа — Easy, Native и Advanced — приказујући кључне компоненте и када их користити.* | Приступ | Шта ради | Компромис | |---|---|---| -| **Easy RAG** | Аутоматски повезује све кроз `AiServices` и `ContentRetriever`. Ви анотирате интерфејс, прикључујете retriever, а LangChain4j иза сцене рукује угнежђењем, претрагом и састављањем упита. | Мали број линија кода, али не видите шта се дешава у сваком кораку. | -| **Native RAG** | Ви сами позивате embedding модел, претражујете складиште, градите упит и генеришете одговор — један изричит корак по корак. | Више кода, али сваки корак је видљив и могуће га је модификовати. | -| **Advanced RAG** | Користи `RetrievalAugmentor` фрејмворк са плуг-ин трансформерима упита, рутирачима, ре-ранкерима, и content injector-има за продукцијске pipeline-ове. | Максимална флексибилност, али и значајно више сложености. | +| **Easy RAG** | Аутоматски повезује све преко `AiServices` и `ContentRetriever`. Анотирате интерфејс, повезујете ретеривер и LangChain4j у позадини управља угнежђивањем, претрагом и саставом упита. | Минималан код, али не видите шта се дешава у сваком кораку. | +| **Native RAG** | Ви зовете модел угнежђења, претражујете складиште, градите упит и генеришете одговор сами — корак по корак. | Више кода, али сваки корак је видљив и модификован. | +| **Advanced RAG** | Користи `RetrievalAugmentor` оквир са подесивим трансформерима упита, рутирањем, ре-рејкирањем и убризгавањем садржаја за производне пипелине. | Максимална флексибилност, али значајно сложеније. | -**Овај туторијал користи Native приступ.** Сваки корак RAG pipeline-а — угнежђење упита, претрага векторског складишта, састављање контекста, и генерисање одговора — је исцрпно написан у [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Ово је намерно: као ресурс за учење, важније је да видите и разумете сваки корак него да је код минимализован. Кад будете комфорни са тим како се делови уклапају, можете прећи на Easy RAG за брзе прототипове или Advanced RAG за продукцијске системе. +**Овај туторијал користи Native приступ.** Сваки корак RAG пипелина — угнежђење упита, претрага векторског складишта, састављање контекста и генерисање одговора — је јасно написан у [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Ово је намерно: као ресурс за учење, важније је да видите и разумете сваки корак него да код буде минималан. Када будете комфорни са тим како се делови уклапају, можете прећи на Easy RAG за брзе прототипове или Advanced RAG за производне системе. -> **💡 Већ сте видели Easy RAG у акцији?** Модул [Quick Start](../00-quick-start/README.md) укључује пример Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) који користи Easy RAG приступ — LangChain4j аутоматски управља угнежђењем, претрагом и састављањем упита. Овај модул иде корак даље тако што отвара тај pipeline да бисте могли да видите и контролишете сваки корак. +> **💡 Занима вас Easy RAG?** LangChain4j такође нуди *Easy RAG* приступ где `AiServices` и `ContentRetriever` аутоматски управљају угнежђивањем, претрагом и саставом упита. Овај модул узима јаснији пут — отвара ту пипелину да бисте видели и контролисали сваки корак сами. -Дијаграм испод приказује Easy RAG pipeline из тог Quick Start примера. Примећујете како `AiServices` и `EmbeddingStoreContentRetriever` крију сву сложеност — учитавате документ, прикључујете retriever и добијате одговоре. Native приступ у овом модулу открива сваки од тих скривених корака: +Дијаграм испод показује Easy RAG пипелин. Примајте како `AiServices` и `EmbeddingStoreContentRetriever` крију целу сложеност — учитавате документ, прикључујете ретеривер и добијате одговоре. Native приступ у овом модулу отвара те сакривене кораке: Easy RAG Pipeline - LangChain4j -*Овај дијаграм показује Easy RAG pipeline из `SimpleReaderDemo.java`. Упоредите са Native приступом коришћеним у овом модулу: Easy RAG крије угнежђење, претрагу и састављање упита иза `AiServices` и `ContentRetriever` — учитавате документ, прикључујете retriever и добијате одговоре. Native приступ у овом модулу отвара тај pipeline тако да позивате сваки корак (угнежђење, претрага, састављање контекста, генерисање) сами, дајући потпуну видљивост и контролу.* +*Овај дијаграм приказује Easy RAG пипелин. Упоредите ово са Native приступом који се користи у овом модулу: Easy RAG крије угнежђење, претрагу и састав упита иза `AiServices` и `ContentRetriever` — учитате документ, прикључујете ретеривер и добијате одговоре. Native приступ у овом модулу отвара ту пипелину тако да сами зовете сваки корак (угнежђуј, претражуј, састави контекст, генериши), пружајући пуну видљивост и контролу.* -## Како функционише +## Како ради -RAG pipeline у овом модулу се састоји од четири фазе које се извршавају у низу сваки пут када корисник постави питање. Прво, отпремљени документ се **парсира и раздваја на делове** који су управљиви. Ти делови се затим претварају у **векторска угнежђења** и чувају како би се могли математички упоређивати. Када упит стигне, систем врши **семантичку претрагу** да пронађе најрелевантније делове, и на крају им прослеђује као контекст LLM-у за **генерисање одговора**. Следећи одељци детаљно обрађују сваку фазу са стварним примером кода и дијаграмима. Хајде да погледамо први корак. +RAG пипелин у овом модулу разлаже се на четири фазе које се извршавају секвенцијално сваки пут када корисник постави питање. Прво, отпремљени документ се **парсира и дели на делове** погодне величине. Ти делови се затим претварају у **векторска угнежђења** и чувају како би се могли математички упоређивати. Када стигне упит, систем врши **семантичку претрагу** да пронађе најрелевантније делове, и коначно их шаље као контекст LLM-у за **генерисање одговора**. Следећи одељци описују сваки корак са стварним кодом и дијаграмима. Погледајмо први корак. ### Обрада докумената [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Када отпремите документ, систем га парсира (PDF или обичан текст), прикључује метаподатке као што је име фајла, и затим га раздваја на делове — мање комаде који се лако уклапају у контекстни прозор модела. Ти делови се благо преклапају како се контекст не би изгубио на границама. +Када отпремите документ, систем га парсира (PDF или текстом), придружује метаподатке попут имена фајла, и затим га дели на комаде — мање делове који лако стају у контекст прозора модела. Ти делови се благо преклапају како се не би изгубио контекст на границама. ```java // Парсирај отпремљену датотеку и умотај је у LangChain4j Документ Document document = Document.from(content, metadata); -// Подели на делове од 300 токена са преклапањем од 30 токена +// Подели на сегменте од 300 токена са преклапањем од 30 токена DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Дијаграм испод визуелно показује како ово функционише. Примећујете како сваки део дели неке токене са својим суседима — преклапање од 30 токена гарантује да важан контекст не падне између пукотина: +Дијаграм испод визуелно приказује како то функционише. Примећује се како сваки део дели неке токене са суседним — преклапање од 30 токена обезбеђује да ниједан важан контекст не падне између фрагмената: -Раздвајање документа на делове +Document Chunking -*Овај дијаграм показује да се документ дели на делове од 300 токена са преклапањем од 30 токена, чувајући контекст на ивицама делова.* +*Овај дијаграм показује документ подељен на делове од 300 токена са преклапањем од 30 токена, очувајући контекст на границама делова.* -> **🤖 Испробај са [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворите [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) и питајте: -> - „Како LangChain4j раздваја документе на делове и зашто је преклапање важно?“ -> - „Која је оптимална величина делова за различите типове докумената и зашто?“ -> - „Како рукујем документима на више језика или са посебним форматирањем?“ +> **🤖 Пробајте са [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворите [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) и питајте: +> - "Како LangChain4j дели документе на делове и зашто је преклапање важно?" +> - "Која је оптимална величина делова за различите типове докумената и зашто?" +> - "Како се носити с документима на више језика или са посебним форматирањем?" ### Креирање угнежђења [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Сваки део се претвара у нумерички приказ који се зове угнежђење — у суштини конвертер значења у бројеве. Embedding модел није „интелигентан“ као чат модел; не може да извршава инструкције, разуме или одговара на питања. Оно што може је да пројектује текст у математички простор где слична значења буду близу једна другог — „аутомобил“ близу „кола“, „политика повраћаја“ близу „поврати ми новац“. Можете замислити чат модел као особу са којом комуницирате; embedding модел је изузетно добар систем за класификацију фајлова. +Сваки део се претвара у нумерички приказ назван угнежђење — у суштини претварач смисла у бројеве. Модел угнежђења није „интелигентан“ као чат модел; не може да прати инструкције, закључује или одговара на питања. Оно што може да уради јесте да текст преслика у математички простор у којем слични смислови буду близу један другог — „ауто“ близу „путничко возило“, „политика повраћаја“ близу „враћање новца“. Замислите да је чат модел особа с којом можете причати; модел угнежђења је врло добар систем архивирања. -Дијаграм испод визуализује овај концепт — текст улази, нумерички вектори излазе, и слична значења дају близу лоциране векторе: +Дијаграм испод визуелизује овај концепт — убацује се текст, излазе нумерички вектори, а слични смислови производе векторе близу један другом: -Концепт embedding модела +Embedding Model Concept -*Овај дијаграм показује како embedding модел претвара текст у нумеричке векторе, постављајући слична значења — као што су "аутомобил" и "кола" — близу једна другог у векторском простору.* +*Овај дијаграм показује како модел угнежђења претвара текст у нумеричке векторе, постављајући сличне смислове — као „ауто“ и „путничко возило“ — блиско један другом у векторском простору.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Дијаграм класа испод приказује два одвојена тока у RAG pipeline-у и LangChain4j класе које их имплементирају. **Ток уноса** (који се извршава једном у тренутку отпремања) раздваја документ, угнежђује делове и чува их преко `.addAll()`. **Ток упита** (који се извршава сваки пут када корисник пита) угнежђује питање, претражује складиште преко `.search()`, и прослеђује подударајући контекст чату. Оба тока се спајају на заједничком интерфејсу `EmbeddingStore`: +Дијаграм класа испод приказује два одвојена протока у RAG пипелину и LangChain4j класе које их имплементирају. **Проток учитавања** (врши се једном приликом при отпремању) дели документ, угнежђује делове и чува их преко `.addAll()`. **Проток упита** (врши се сваки пут када се постави питање) угнежђује питање, претражује складиште преко `.search()`, и прослеђује пронађени контекст модели за ћаскање. Оба протока се спајају преко заједничког интерфејса `EmbeddingStore`: -LangChain4j RAG класе +LangChain4j RAG Classes -*Овај дијаграм показује два тока у RAG pipeline-у — унос и упит — и како су повезани кроз заједнички EmbeddingStore.* +*Овај дијаграм приказује два протока у RAG пипелину — учитавање и упит — и како се повезују преко заједничког EmbeddingStore.* -Кад се угнежђења сачувају, сличан садржај се природно кластерује у векторском простору. Визуализација испод показује како документи о сродним темама постају блиски тачкама, што омогућава семантичку претрагу: +Када се угнежђења сачувају, сличан садржај природно групише близу у векторском простору. Визуелизација испод показује како документи о сродним темама завршавају као блиски тачки, што омогућава семантичку претрагу: -Простор векторских угнежђења +Vector Embeddings Space -*Ова визуализација приказује како повезани документи клестерују у 3D векторском простору, са темама као што су Техничка документација, Пословна правила, и Често постављана питања које формирају јасне групе.* +*Ова визуализација приказује како се сродни документи групишу у 3D векторском простору, са темама као што су Техничка документација, Пословна правила и Честа питања формирајући посебне групе.* -Када корисник врши претрагу, систем пролази четири корака: угнежђује документе једном, угнежђује упит сваки пут када се врши претрага, упоређује вектор упита са свим сачуваним векторима коришћењем косинусне сличности, и враћа топ-K највише оцењених делова. Дијаграм испод води кроз сваки корак и LangChain4j класе укључене у процес: +Када корисник претражује, систем следи четири корака: угнежђује документе једном, угнежђује упит при свакој претрази, упоређује упитни вектор са свим сачуваним векторима коришћењем косинусне сличности, и враћа топ-K најбоље оцењене делове. Дијаграм испод приказује сваки корак и LangChain4j класе укључене: -Кораци претраге угнежђења +Embedding Search Steps -*Овај дијаграм приказује четворокоракни процес претраге угнежђења: угнежђење докумената, угнежђење упита, поређење вектора уз косинусну сличност, и повраћање топ-K резултата.* +*Овај дијаграм приказује четворокорачан процес претраге угнежђења: угнежђује документе, угнежђује упит, упоређује векторе помоћу косинусне сличности и враћа топ-K резултате.* ### Семантичка претрага [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Када поставите питање, и ваше питање такође постаје угнежђење. Систем упоређује угнежђење вашег питања са свим угнежђењима делова документа. Проналази делове са најсличнијим значењима — не само појединачне кључне речи већ стварну семантичку сличност. +Када поставите питање, и ваше питање постаје угнежђење. Систем упоређује угнежђење вашег питања са угнежђењима свих делова документа. Пронађе делове са најсличнијим значењима — не само поклапајућим кључним речима, већ стварном семантичком сличношћу. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Дијаграм испод контрастира семантичку претрагу са традиционалном претрагом по кључним речима. Претрага кључне речи „возило“ пропушта део о „колима и камионима“, али семантичка претрага разуме да је то исто и враћа га као високо оцењену подударност: +Дијаграм испод упоређује семантичку претрагу са традиционалном претрагом по кључним речима. Претрага кључном речју „возило“ пропушта део о „аутомобилима и камионима“, али семантичка претрага разуме да значе исто и враћа га као висококвалитетну сличност: -Семантичка претрага +Semantic Search -*Овај дијаграм упоређује претрагу по кључним речима са семантичком претрагом, показујући како семантичка претрага враћа концептуално повезан садржај чак и када се кључне речи разликују.* -Иза кулиса, сличност се мери коришћењем косинусне сличности — у суштини пита „да ли ове две стрелице показују у истом правцу?“ Два парчета могу да користе сасвим различите речи, али ако значе исту ствар, њихови вектори показују у истом смеру и резултат је близу 1.0: +*Овај дијаграм пореди претрагу по кључним речима са семантичком претрагом, показујући како семантичка претрага враћа концептуално повезани садржај чак и када тачне кључне речи нису исте.* -Cosine Similarity +Испод хаубе, сличност се мери коришћењем косинусне сличности — у суштини питајући се „да ли ова два стрелца показују у истом правцу?“ Два дела могу користити потпуно различите речи, али ако значе исту ствар, њихови вектори показују у истом правцу и имају ранг близу 1.0: -*Овај дијаграм илуструје косинусну сличност као угао између угњеждених вектора — више усаглашени вектори имају резултат ближи 1.0, што указује на већу семантичку сличност.* +Cosine Similarity +*Овај дијаграм илуструје косинусну сличност као угао између уграђених вектора — више поравнати вектори имају резултат ближи 1.0, што указује на већу семантичку сличност.* -> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Четом:** Отворите [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) и питајте: -> - "Како функционише претрага сличности са угњежђењима и шта одређује резултат?" -> - "Који праг сличности треба да користим и како то утиче на резултате?" -> - "Како да поступим када не нађем релевантне документе?" +> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Чатом:** Отворите [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) и питајте: +> - "Како ради претрага по сличности са уграђивањима и шта одређује резултат?" +> - "Који праг сличности треба да користим и како он утиче на резултате?" +> - "Како да поступим у случајевима када не нађем релевантне документе?" ### Генерисање одговора [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Најрелевантнији делови су састављени у структурирану наводну поруку која укључује експлицитна упутства, пронађени контекст и питање корисника. Модел чита те конкретне делове и одговара на основу тих информација — може да користи само оно што је пред собом, што спречава халуцинације. +Најрелевантнији делови се састављају у структуриран упит који укључује експлицитна упутства, преузети контекст и корисничко питање. Модел чита те одређене делове и одговара на основу тих информација — може користити само оно што је испред њега, што спречава халуцинације. ```java String context = matches.stream() @@ -237,55 +236,55 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Дијаграм испод приказује ову састављање у акцији — најбоље оцењени делови из корака претраге убацују се у шаблон поруке, а `OpenAiOfficialChatModel` генерише базирани одговор: +Дијаграм испод показује ову скупштину на делу — делови са највишим оценама из фазе претраге убацују се у шаблон упита, а `OpenAiOfficialChatModel` генерише поткрепљен одговор: Context Assembly -*Овај дијаграм показује како се најбоље оцењени делови састављају у структурирану поруку, омогућавајући моделу да генерише базирани одговор из ваших података.* +*Овај дијаграм показује како се делови са највишим оценама скупљају у структуриран упит, омогућавајући моделу да генерише поткрепљен одговор из ваших података.* -## Покрени апликацију +## Покретање апликације -**Потврдите распоређивање:** +**Проверите распоређивање:** -Осигурајте да `.env` фајл постоји у главном директоријуму са Азуре акредитивима (креирано током Модула 01). Покрените ово из директоријума модула (`03-rag/`): +Проверите да ли је датотека `.env` присутна у коренском директоријуму са Azure акредитивима (направљена током Модула 01). Покрените ово из директоријума модула (`03-rag/`): -**Баш:** +**Bash:** ```bash -cat ../.env # Требало би да приказује AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Треба да покаже AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Требало би да прикаже AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Треба да прикаже AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Покрени апликацију:** +**Покрените апликацију:** -> **Напомена:** Ако сте већ покренули све апликације користећи `./start-all.sh` из главног директоријума (као што је описано у Модулу 01), овај модул већ ради на порту 8081. Можете прескочити команде за покретање испод и директно отићи на http://localhost:8081. +> **Напомена:** Ако сте већ покренули све апликације користећи `./start-all.sh` из коренског директоријума (као што је описано у Модулу 01), овај модул већ ради на порту 8081. Можете прескочити наредбе за покретање испод и директно отићи на http://localhost:8081. -**Опција 1: Коришћење Spring Boot Dashboard (препоручено за кориснике VS Code)** +**Опција 1: Коришћење Spring Boot командне табле (Препоручено за кориснике VS Code-а)** -Дев контејнер укључује Spring Boot Dashboard екстензију, која пружа визуелни интерфејс за управљање свим Spring Boot апликацијама. Можете је пронаћи у Activity Bar са леве стране VS Code-а (потражите иконицу Spring Boot). +Дев контейнер укључује проширење Spring Boot командне табле, које пружа визуелни интерфејс за управљање свим Spring Boot апликацијама. Можете га пронаћи у траци активности са леве стране VS Code-а (потражите иконицу Spring Boot-а). -Из Spring Boot Dashboard-а можете: -- Видети све расположиве Spring Boot апликације у радном простору -- Покренути/зауставити апликације једним кликом -- Пратити дневнике апликација у реалном времену -- Надгледати статус апликације +Из Spring Boot командне табле можете: +- Видети све доступне Spring Boot апликације у радном простору +- Покретати/заустављати апликације једним кликом +- Прегледати записе апликација у реалном времену +- Пратити статус апликација -Једноставно кликните на дугме за репродукцију поред „rag“ да бисте покренули овај модул, или покрените све модуле одједном. +Једноставно кликните на дугме за покретање поред "rag" да бисте покренули овај модул, или покрените све модуле одједном. Spring Boot Dashboard -*Овај снимак екрана приказује Spring Boot Dashboard у VS Code-у, где можете визуелно покретати, заустављати и пратити апликације.* +*Слика екрана приказује Spring Boot командну таблу у VS Code-у, где можете визуелно покретати, заустављати и пратити апликације.* -**Опција 2: Коришћење shell скрипти** +**Опција 2: Коришћење скрипти за шкољку** -Покрени све веб апликације (модули 01-04): +Покрените све веб апликације (модули 01-04): -**Баш:** +**Bash:** ```bash -cd .. # Из директоријума корена +cd .. # Из коренског директоријума ./start-all.sh ``` @@ -295,9 +294,9 @@ cd .. # Из коренског директоријума .\start-all.ps1 ``` -Или покрени само овај модул: +Или покрените само овај модул: -**Баш:** +**Bash:** ```bash cd 03-rag ./start.sh @@ -309,16 +308,16 @@ cd 03-rag .\start.ps1 ``` -Обе скрипте аутоматски учитавају променљиве окружења из главног `.env` фајла и изградиће JAR-ове ако не постоје. +Обa скрипте аутоматски учитавају променљиве окружења из коренске `.env` датотеке и граде JAR фајлове ако не постоје. > **Напомена:** Ако више волите да ручно изградите све модуле пре покретања: > -> **Баш:** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -327,9 +326,9 @@ cd 03-rag Отворите http://localhost:8081 у вашем прегледачу. -**Да зауставите:** +**За заустављање:** -**Баш:** +**Bash:** ```bash ./stop.sh # Само овај модул # Или @@ -349,89 +348,89 @@ cd ..; .\stop-all.ps1 # Сви модули RAG Application Interface -*Овај снимак екрана приказује интерфејс RAG апликације где отпремате документе и постављате питања.* +*Овај снимак екрана приказује интерфејс RAG апликације у којој отпремате документе и постављате питања.* ### Отпремање документа -Започните отпремањем документа – за тестирање најбоље раде TXT фајлови. У овом директоријуму је обезбеђен `sample-document.txt` који садржи информације о карактеристикама LangChain4j, имплементацији RAG и најбољим праксама – савршено за тестирање система. +Почните са отпремањем документа — TXT фајлови најбоље функционишу за тестирање. У овом директоријуму је обезбеђен фајл `sample-document.txt` који садржи информације о функцијама LangChain4j, RAG имплементацији и најбољим праксама — идеално за тестирање система. -Систем обрађује ваш документ, раздваја га на делове и креира угњежђења за сваки део. Ово се дешава аутоматски кад отпремите. +Систем обрађује ваш документ, дели га на делове и креира уграђивања за сваки део. Ово се дешава аутоматски при отпремању. ### Постављање питања -Сада постављајте конкретна питања о садржају документа. Покушајте нешто фактографско што је јасно наведено у документу. Систем тражи релевантне делове, укључује их у поруку и генерише одговор. +Сада поставите специфична питања о садржају документа. Покушајте са чињеничним питањима која су јасно наведена у документу. Систем претражује релевантне делове, укључује их у упит и генерише одговор. -### Проверите изворне референце +### Провера извора -Приметите да сваки одговор укључује изворне референце са оценама сличности. Ове оцене (од 0 до 1) показују колико је сваки део био релевантан за ваше питање. Више оцене значе боље поклапање. Ово вам омогућава да проверите одговор у односу на изворни материјал. +Приметите да сваки одговор укључује референце извора са оценама сличности. Ове оцене (од 0 до 1) показују колико је сваки део био релевантан вашем питању. Више оцене значе боље поклапање. Ово вам омогућава да проверите одговор у односу на изворни материјал. RAG Query Results -*Овај снимак екрана приказује резултате упита са генерисаним одговором, изворним референцама и оценама релевантности за сваки пронађени део.* +*Овај снимак екрана показује резултате претраге са генерисаним одговором, изворним референцама и оценама релевантности за сваки повучени део.* -### Истражујте питања +### Експериментишите са питањима -Покушајте различите врсте питања: -- Конкретне чињенице: „Која је главна тема?“ -- Поређења: „Која је разлика између X и Y?“ -- Резиме: „Сажми кључне тачке о З“ +Пробајте различите типове питања: +- Специфичне чињенице: "Која је главна тема?" +- Поређења: "Која је разлика између X и Y?" +- Сажецима: "Сажми кључне тачке о Z" -Пратите како се оцене релевантности мењају у зависности од тога колико ваше питање одговара садржају документа. +Пратите како оцене релевантности мењају у зависности од тога колико ваше питање одговара садржају документа. -## Кључни концепти +## Кључни појмови -### Стратегија раздвајања делова +### Стратегија деловања (Chunking) -Документи се деле на делове од 300 токена са прелазом од 30 токена. Ова равнотежа осигурава да сваки део има довољно контекста да буде смислен, а да остане довољно мали да се више делова може укључити у један захтев. +Документи се деле на делове од 300 токена са преклапањем од 30 токена. Ова равнотежа обезбеђује да сваки део има довољан контекст да буде смислен, а да истовремено буде довољно мали да се у упит може укључити више делова. ### Оцене сличности -Сваки пронађени део долази са оценом сличности између 0 и 1 која показује колико је тај део близак корисничком питању. Дијаграм испод визуелно приказује распон оцена и како систем њима филтрира резултате: +Сваки повучени део долази са оценом сличности између 0 и 1 која указује колико добро одговара корисниковом питању. Дијаграм испод визуализује распоне оцена и како их систем користи за филтрирање резултата: Similarity Scores -*Овај дијаграм показује распоне оцена од 0 до 1, са минималним прагом од 0.5 који филтрира нерелевантне делове.* +*Овај дијаграм показује распоне оцена од 0 до 1, са минималним праком од 0.5 који филтрира нерелевантне делове.* Оцене се крећу од 0 до 1: -- 0.7-1.0: Веома релевантно, тачно поклапање +- 0.7-1.0: Врло релевантно, тачна поклапања - 0.5-0.7: Релевантно, добар контекст - Испод 0.5: Филтрирано, превише различито -Систем враћа само делове изнад минималног прага ради обезбеђења квалитета. +Систем преузима само делове изнад минималног прага како би обезбедио квалитет. -Угњежђења добро функционишу када се значења јасно групишу, али имају слаба места. Дијаграм испод показује уобичајене начине неуспеха — делови који су превелики производе нејасне векторе, делови који су превише мали немају контекст, двосмислени термини показују на више група, а претрага по тачном поклапању (ИД-ови, бројеви делова) уопште не функционише са угњежђењима: +Уграђивања добро раде када се значења јасно класификују, али имају своје слепе тачке. Дијаграм испод показује уобичајене начине пропуста — превелики делови производе мутне векторе, премали делови немају довољно контекста, двосмислени термини упућују на више кластера, а тачна поклапања (ИД-и, бројеви делова) уопште не функционишу са уграђивањима: Embedding Failure Modes -*Овај дијаграм показује уобичајене неуспехе у угњежђењима: превелики делови, превише мали делови, двосмислени термини који показују на више група, и претрага по тачном поклапању као што су ИД-ови.* +*Овај дијаграм показује уобичајене начине пропуста уграђивања: превелики делови, премали делови, двосмислени термини који упућују на више кластера и тачна поклапања као што су ИД-ови.* -### Чување у меморији +### Складиштење у меморији -Овај модул користи чување у меморији ради једноставности. Када поново покренете апликацију, отпремљени документи се губе. Продукцијски системи користе упорне векторске базе као што су Qdrant или Azure AI Search. +Овај модул користи складиштење у меморији због једноставности. Када поново покренете апликацију, отпремљени документи се губе. Продукцијски системи користе перзистентне векторске базе података као што су Qdrant или Azure AI Search. -### Управљање контекстним прозором +### Управљање прозором контекста -Сваки модел има максималан контекстни прозор. Не можете укључити сваки део из великог документа. Систем дохвата најрелевантнијих Н делова (подразумевано 5) да остане унутар граница, пружајући довољно контекста за прецизне одговоре. +Сваки модел има максимални прозор контекста. Не можете укључити сваки део из великог документа. Систем преузима најрелевантнијих N делова (подразумевано 5) да остане у границама, а истовремено пружи довољно контекста за тачне одговоре. ## Када је RAG важан -RAG није увек прави приступ. Водич за одлуке испод помаже да одредите када RAG додаје вредност у поређењу са једноставнијим приступима — као што је укључивање садржаја директно у захтев или ослањање на уграђено знање модела — који су довољни: +RAG није увек прави приступ. Водич за одлучивање испод вам помаже да утврдите када RAG доноси вредност, а када су једноставнији приступи — као што је укључивање садржаја директно у упит или ослањање на уграђено знање модела — довољни: When to Use RAG -*Овај дијаграм приказује водич за одлуке када RAG додаје вредност у поређењу са када су једноставнији приступи довољни.* +*Овај дијаграм показује водич за одлучивање када RAG доноси вредност у односу на када су једноставнији приступи довољни.* ## Следећи кораци -**Следећи модул:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Следећи модул:** [04-tools - AI агенти са алатима](../04-tools/README.md) --- -**Навигација:** [← Претходни: Модул 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Назад на Главну](../README.md) | [Следећи: Модул 04 - Алати →](../04-tools/README.md) +**Навигација:** [← Претходно: Модул 02 - Продужење упита](../02-prompt-engineering/README.md) | [Назад на Главно](../README.md) | [Следеће: Модул 04 - Алатке →](../04-tools/README.md) --- -**Одрицање одговорности**: -Овај документ је преведен коришћењем АИ услуге превођења [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо прецизности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитетним извором. За критичне информације препорука је професионални људски превод. Нисмо одговорни за било какве неспоразуме или погрешне тумачења настале коришћењем овог превода. +**Изјава о одрицању одговорности**: +Овај документ је преведен коришћењем услуге за аутоматски превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода. \ No newline at end of file diff --git a/translations/sr/04-tools/README.md b/translations/sr/04-tools/README.md index 99f82496e..e3e5121da 100644 --- a/translations/sr/04-tools/README.md +++ b/translations/sr/04-tools/README.md @@ -1,84 +1,84 @@ -# Модул 04: AI агенти са алаткама +# Модул 04: AI агенти са алатима ## Садржај -- [Водич кроз видео](../../../04-tools) -- [Шта ћете научити](../../../04-tools) -- [Предзнања](../../../04-tools) -- [Разумевање AI агената са алаткама](../../../04-tools) -- [Како функционише позивање алатки](../../../04-tools) - - [Дефиниције алатки](../../../04-tools) - - [Доношење одлука](../../../04-tools) - - [Извршење](../../../04-tools) - - [Генерисање одговора](../../../04-tools) - - [Архитектура: Spring Boot аутоматско повезивање](../../../04-tools) -- [Повезивање алатки](../../../04-tools) -- [Покретање апликације](../../../04-tools) -- [Коришћење апликације](../../../04-tools) - - [Пробајте једноставно коришћење алатке](../../../04-tools) - - [Тестирајте повезивање алатки](../../../04-tools) - - [Погледајте ток разговора](../../../04-tools) - - [Експериментишите са различитим захтевима](../../../04-tools) -- [Кључни појмови](../../../04-tools) - - [ReAct обрасци (рачунање и деловање)](../../../04-tools) - - [Опис алатки је важан](../../../04-tools) - - [Управљање сесијом](../../../04-tools) - - [Руковање грешкама](../../../04-tools) -- [Располиживе алатке](../../../04-tools) -- [Када користити агенте базиране на алаткама](../../../04-tools) -- [Алатке у поређењу са RAG](../../../04-tools) -- [Следећи кораци](../../../04-tools) - -## Водич кроз видео - -Погледајте ову уживо сесију која објашњава како почети са овим модулом: +- [Видео водич](#видео-водич) +- [Шта ћете научити](#шта-ћете-научити) +- [Пре захтеви](#пре-захтеви) +- [Разумевање AI агената са алатима](#разумевање-ai-агената-са-алатима) +- [Како позив алата функционише](#како-позив-алата-функционише) + - [Дефиниције алата](#дефиниције-алата) + - [Доносити одлуке](#доносити-одлуке) + - [Извршење](#извршење) + - [Генерисање одговора](#генерисање-одговора) + - [Архитектура: Spring Boot аутоматско повезивање](#архитектура-spring-boot-аутоматско-повезивање) +- [Повезивање алата](#повезивање-алата) +- [Покрени апликацију](#покрени-апликацију) +- [Коришћење апликације](#коришћење-апликације) + - [Испробајте једноставну употребу алата](#испробајте-једноставно-коришћење-алата) + - [Тестирајте повезивање алата](#тестирајте-повезивање-алата) + - [Погледајте ток разговора](#погледајте-ток-разговора) + - [Експериментишите са различитим захтевима](#испробајте-различите-захтеве) +- [Кључни концепти](#кључни-појмови) + - [ReAct образац (Размишљање и Деловање)](#react-шаблон-размишљање-и-деловање) + - [Опис алата је важан](#описи-алата-су-важни) + - [Управљање сесијом](#управљање-сесијом) + - [Руковање грешкама](#руковање-грешкама) +- [Доступни алати](#доступни-алати) +- [Када користити агенте базиране на алатима](#када-користити-агенте-засноване-на-алатима) +- [Алатке насупрот RAG](#алати-и-rag) +- [Следећи кораци](#следећи-кораци) + +## Видео водич + +Погледајте ову уживо сесију која објашњава како започети са овим модулом: AI Agents with Tools and MCP - Live Session ## Шта ћете научити -До сада сте научили како водити разговоре са AI, како ефикасно структуирати упите и како засновати одговоре на вашим документима. Али постоји основно ограничење: модели језика могу само да генеришу текст. Они не могу да провере време, израчунају нешто, упитују базе података или комуницирају са спољним системима. +До сада сте научили како водити разговоре са AI, како ефективно структуирати упите и како засновати одговоре на вашим документима. Али постоји основно ограничење: језички модели могу само да генеришу текст. Они не могу да провере време, израчунају, упитују базе података или комуницирају са спољним системима. -Алатке мењају то. Омогућавајући моделу приступ функцијама које може позивати, трансформишете га из генератора текста у агента који може предузимати акције. Модел одлучује када му треба алатка, коју алатку да користи и које параметре да проследи. Ваш код извршава функцију и враћа резултат. Модел уноси тај резултат у свој одговор. +Алатке мењају то. Давањем модулу приступа функцијама које може позивати, претварате га из генератора текста у агента који може предузимати радње. Модел одлучује када му је потребан алат, који алат да користи и које параметре да проследи. Ваш код извршава ту функцију и враћа резултат. Модел укључује тај резултат у свој одговор. -## Предзнања +## Пре захтеви -- Завршен [Модул 01 - Увод](../01-introduction/README.md) (размештени Azure OpenAI ресурси) -- Препоручује се завршетак претходних модула (овaj модул референцира [RAG концепте из Модула 03](../03-rag/README.md) у поређењу алатки и RAG) -- `.env` фајл у коренском директоријуму са Azure акредитивима (направљен командом `azd up` у Модулу 01) +- Завршен [Модул 01 - Увод](../01-introduction/README.md) (Azure OpenAI ресурси постављени) +- Препоручени претходни модули завршени (овај модул се ослања на [RAG концепте из Модула 03](../03-rag/README.md) у поређењу алатки и RAG) +- `.env` фајл у корену директоријума са Azure акредитивима (направљен командом `azd up` у Модулу 01) -> **Напомена:** Ако нисте завршили Модул 01, пратите упутства за постављање тамо прво. +> **Напомена:** Ако нисте завршили Модул 01, прво пратите упутства за деплои. -## Разумевање AI агената са алаткама +## Разумевање AI агената са алатима -> **📝 Напомена:** Термин „агенти“ у овом модулу односи се на AI асистенте који су побољшани могућношћу позивања алатки. Ово се разликује од **Agentic AI** образаца (аутономни агенти са планирањем, меморијом и вишестепеним размишљањем) које ћемо обрадити у [Модул 05: MCP](../05-mcp/README.md). +> **📝 Напомена:** Пojам "агенти" у овом модулу се односи на AI асистенте побољшане способностима позивања алата. Ово се разликује од **Agentic AI** образаца (аутономни агенти са планирањем, меморијом и више корачним закључивањем) које ћемо обрадити у [Модулу 05: MCP](../05-mcp/README.md). -Без алатки, модел језика може само да генерише текст из свог тренинг скупа података. Питајте га какво је време у уређају и мораће да погађа. Додајте му алатке и он може позвати API за време, извршити прорачуне или упитати базу података — и онда уградити те стварне резултате у свој одговор. +Без алата, језички модел може само да генерише текст из својих тренинг података. Питајте га за тренутно време и мораће да нагађа. Дате му алате, и може позвати временски API, израчунати нешто или упитати базу података — а затим те реалне резултате уградити у одговор. -Without Tools vs With Tools +Без алата против са алатима -*Без алатки модел само погађа — са алаткама може позивати API-је, извршавати прорачуне и враћати податке у реалном времену.* +*Без алата модел само нагађа — са алатима може да позива API-је, израчунава и враћа податке у реалном времену.* -AI агент са алаткама прати **Reasoning and Acting (ReAct)** образац. Модел не само да одговара — он размишља шта му треба, делује позивајући алатку, прати резултат и онда одлучује да ли да поново делује или да достави коначни одговор: +AI агент са алатима прати образац **Размишљање и Деловање (ReAct)**. Модел не само да одговара — он размишља о томе шта му је потребно, делује позивајући алат, посматра резултат, и онда одлучује да ли да поново делује или да да крајњи одговор: -1. **Размишљање** — Агент анализира корисничко питање и утврђује које информације су му потребне -2. **Деловање** — Агент бира праву алатку, генерише одговарајуће параметре и позива је -3. **Прати** — Агент добија излаз алатке и процењује резултат -4. **Понавља или одговара** — Ако је потребно више података, агент се враћа на почетак; у супротном, саставља природно језички одговор +1. **Размисли** — Агент анализира корисничко питање и одређује које информације су му потребне +2. **Делуј** — Агент одабира прави алат, генерише исправне параметре и позива га +3. **Посматрај** — Агент добија излаз алата и процењује резултат +4. **Понови или одговори** — Ако је потребно више података, агент се враћа на почетак; иначе, саставља одговор на природном језику -ReAct Pattern +ReAct образац -*ReAct циклус — агент размишља шта да уради, делује позивајући алатку, прати резултат и врти се док не може дати коначни одговор.* +*ReAct циклус — агент размишља шта да уради, делује позивајући алат, посматра резултат и наставља док не може да да крајњи одговор.* -Ово се дешава аутоматски. Ви дефинишете алатке и њихове описе. Модел сам одлучује када и како да их користи. +Ово се одвија аутоматски. Ви дефинишете алате и њихове описе. Модел доноси одлуку када и како да их користи. -## Како функционише позивање алатки +## Како позив алата функционише -### Дефиниције алатки +### Дефиниције алата [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Дефинишете функције са јасним описима и спецификацијом параметара. Модел види те описе у свом системском упиту и разуме шта свака алатка ради. +Дефинишете функције са јасним описима и спецификацијама параметара. Модел види те описе у свом системском упиту и разуме шта сваки алат ради. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Логика вашег претраживања временске прогнозе + // Ваша логика претраживања времена return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,143 +96,143 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Помоћник је аутоматски повезан помоћу Spring Boot-а са: -// - ChatModel бином -// - Све @Tool методе из @Component класа -// - ChatMemoryProvider за управљање сесијом +// Асистент је аутоматски повезан од стране Spring Boot-а са: +// - ChatModel bean-ом +// - Свим @Tool методама из @Component класа +// - ChatMemoryProvider-ом за управљање сесијама ``` -Дијаграм испод разлаже сваку анотацију и показује како сваки део помаже AI да разуме када да позове алатку и које аргументе да проследи: +Дијаграм испод раздваја сваку анотацију и показује како сваки део помаже AI да разуме када да позове алат и које аргументе да проследи: -Anatomy of Tool Definitions +Структура дефиниција алата -*Анатомија дефиниције алатке — @Tool говори AI кад да је користи, @P описује сваки параметар, а @AiService у стартовању повезује све заједно.* +*Структура дефиниције алата — @Tool говори AI-ју када да га користи, @P описује сваки параметар, а @AiService повезује све при покретању.* -> **🤖 Пробајте са [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворите [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) и питајте: -> - "Како бих интегрисао прави API за време као OpenWeatherMap уместо лажних података?" -> - "Шта чини добар опис алатке који помаже AI да је правилно користи?" -> - "Како да обрађујем грешке API-ја и ограничења учесталости у имплементацији алатки?" +> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворите [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) и питајте: +> - "Како бих интегрисао прави временски API као OpenWeatherMap уместо лажних података?" +> - "Шта чини добар опис алата који помаже AI-ју да га правилно користи?" +> - "Како да ручам грешке API-ja и ограничења у позивима у имплементацијама алата?" -### Доношење одлука +### Доносити одлуке -Када корисник пита „Какво је време у Сијетлу?“, модел не бира алатку насумично. Он упоређује намеру корисника са описима свих алатки којима има приступ, даје оцена важности и бира најбољи одговарајући алат. Онда генерише структуирани позив функције са одговарајућим параметрима — у овом случају, поставља `location` на `"Seattle"`. +Када корисник пита "Какво је време у Сијетлу?", модел не бира алат насумично. Он упоређује корисничку намеру са сваким описом алата којем има приступ, оцењује релевантност и бира најбољи одговор. Затим генерише структуриран позив функције са исправним параметрима — у овом случају, постављајући `location` на `"Seattle"`. -Ако ниједна алатка не одговара корисничком захтеву, модел се враћа одговарању на основу свог знања. Ако више алатки одговара, он бира најспецифичнију. +Ако ниједан алат не одговара корисниковом захтеву, модел се враћа да одговори из свог знања. Ако више алата одговара, бира најспецифичнији. -How the AI Decides Which Tool to Use +Како AI одлучује који алат да користи -*Модел процењује сваку доступну алатку у односу на намеру корисника и бира најбољу — зато је важно писати јасне и специфичне описе алатки.* +*Модел процењује сваки доступни алат у односу на намеру корисника и бира најбољи — зато је писање јасних и прецизних описа алата важно.* ### Извршење [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot аутоматски повезује декларативни `@AiService` интерфејс са свим регистрованим алаткама, а LangChain4j аутоматски извршава позиве алатки. Испод хаубе, цео позив алатки тече кроз шест фаза — од корисничког питања у природном језику па све до одговора у природном језику: +Spring Boot аутоматски повезује декларативни интерфејс `@AiService` са свим регистрованим алатима, а LangChain4j аутоматски извршава позиве алата. Кроз позадину, комплетан позив алата протиче кроз шест фаза — од корисничког питања на природном језику све до одговора на природном језику: -Tool Calling Flow +Ток позивања алата -*Потпуни ток — корисник поставља питање, модел бира алатку, LangChain4j је извршава, а модел уграђује резултат у природан одговор.* +*Цео процес — корисник пита, модел бира алат, LangChain4j га извршава, а модел ускомешује резултат у природан одговор.* -Ако сте покренули [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) у Модулу 00, већ сте видели овај образац у акцији — алатке `Calculator` су позиване на исти начин. Дијаграм секвенце испод приказује шта се тачно десило испод хаубе током тог демо-а: +У позадини, `AiServices` извршава исти циклус позивања алата за сваки алат — овде илустрован једноставним `Calculator`-ом. Дијаграм секвенце испод показује прецизно шта се дешава испод хаубе: -Tool Calling Sequence Diagram +Дијаграм секвенце позивања алата -*Луп позива алатки из Quick Start демо-а — `AiServices` шаље вашу поруку и шеме алатки у LLM, LLM одговара позивом функције као што је `add(42, 58)`, LangChain4j локално извршава `Calculator` методу, и враћа резултат назад за коначни одговор.* +*Циклус позивања алата — `AiServices` шаље вашу поруку и шеме алата LLM-у, LLM одговара позивом функције као што је `add(42, 58)`, LangChain4j локално извршава методу `Calculator`, и враћа резултат за крајњи одговор.* -> **🤖 Пробајте са [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворите [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) и питајте: -> - "Како ради ReAct образац и зашто је ефикасан за AI агенте?" -> - "Како агент одлучује коју алатку да користи и у ком редоследу?" -> - "Шта се дешава ако извршење алатке не успе - како да безбедно обрадим грешке?" +> **🤖 Испробајте са [GitHub Copilot](https://github.com/features/copilot) Chat:** Отворите [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) и питајте: +> - "Како ReAct образац функционише и зашто је ефикасан за AI агенте?" +> - "Како агент одлучује који алат да користи и којим редоследом?" +> - "Шта се дешава ако позив алата не успе - како да поуздано руковати грешкама?" ### Генерисање одговора -Модел прими податке о времену и форматира их у природан језички одговор за корисника. +Модел добија податке о времену и форматира их у одговор на природном језику кориснику. ### Архитектура: Spring Boot аутоматско повезивање -Овај модул користи LangChain4j Spring Boot интеграцију са декларативним `@AiService` интерфејсима. При покретању, Spring Boot открива сваки `@Component` који садржи `@Tool` методе, ваш `ChatModel` bean и `ChatMemoryProvider` — па их све повезује у један `Assistant` интерфејс без икаквог додатног кода. +Овај модул користи LangChain4j интеграцију са Spring Boot-ом и декларативним интерфејсима `@AiService`. При покретању Spring Boot открива све `@Component` који садрже `@Tool` методе, ваш `ChatModel` bean и `ChatMemoryProvider` — па их све повезује у један интерфејс `Assistant` без икаквог додатног кода. -Spring Boot Auto-Wiring Architecture +Spring Boot аутаповезивање архитектура -*@AiService интерфејс повезује ChatModel, компоненте алатки и провајдер меморије — Spring Boot све аутоматски повезује.* +*Интерфејс @AiService повезује ChatModel, компоненте алата и провајдер меморије — Spring Boot аутоматски обавља све везе.* -Ево комплетног животног циклуса захтева као дијаграма секвенце — од HTTP захтева, преко контролера, сервиса и аутоматски повезаног proxy-ја, све до извршења алатке и повратка: +Овде је комплетан ток живота захтева као дијаграм секвенце — од HTTP захтева, преко контролера, сервиса и аутоматски повезаног проксија, све до извршења алата и назад: -Spring Boot Tool Calling Sequence +Spring Boot секвенца позива алата -*Комплетан животни циклус HTTP захтева - захтев тече кроз контролер и сервис до аутоматски повезаног Assistant proxy-ја, који аутоматски координише LLM и позиве алатки.* +*Цео ток живота захтева у Spring Boot-у — HTTP захтев пролази кроз контролер и сервис до аутоматски повезаног Assistant проксија који оркестрира LLM и позиве алата аутоматски.* Кључне предности овог приступа: -- **Spring Boot аутоматско повезивање** — ChatModel и алатке се аутоматски инјектују -- **@MemoryId образац** — Аутоматско управљање меморијом заснованом на сесији -- **Једна инстанца** — Assistant се креира једном и реупотребљава ради боље перформансе -- **Типски безбедно извршење** — Java методе се позивају директно са конверзијом типова -- **Оркестрација више корака** — Аутоматски управља повезивањем алатки -- **Нула шаблонског кода** — Нема ручних позива `AiServices.builder()` или меморијског HashMap-а +- **Spring Boot аутаповезивање** — ChatModel и алати аутоматски инјектовани +- **@MemoryId образац** — Аутоматско управљање меморијом засновано на сесији +- **Једна инстанца** — Assistant направљен једном и користи се више пута ради бољег перформанса +- **Извршење безбедно по типу** — Java методе позивају се директно са конверзијом типова +- **Оркестрација више корака** — Аутоматски се рукује повезивањем алата +- **Нула додатног кода** — Без ручних позива `AiServices.builder()` или меморијских ХашМап структура -Алтернативни приступи (ручно коришћење `AiServices.builder()`) захтевају више кода и немају предности Spring Boot интеграције. +Алтернативни приступи (ручни `AiServices.builder()`) захтевају више кода и губе предности интеграције са Spring Boot-ом. -## Повезивање алатки +## Повезивање алата -**Повезивање алатки** — стварна снага агената базираних на алаткама показује се када једно питање захтева више алатки. Питајте „Какво је време у Сијетлу у Фаренхајтима?“ и агент аутоматски повезује две алатке: прво позива `getCurrentWeather` да добије температуру у Целзијусима, а затим ту вредност прослеђује у `celsiusToFahrenheit` за конверзију — све у једном кораку разговора. +**Повезивање алата** — Праву снагу агената базираних на алатима добијамо када једно питање захтева више алата. Питајте "Какво је време у Сијетлу у Фаренхајтима?" и агент аутоматски повезује два алата: прво позива `getCurrentWeather` да добије температуру у Целзијусима, а затим прослеђује ту вредност алату `celsiusToFahrenheit` ради конверзије — све у једном кораку разговора. -Tool Chaining Example +Пример повезивања алата -*Повезивање алатки у пракси — агент прво позива getCurrentWeather, затим резултат у Целзијусима пропушта кроз celsiusToFahrenheit и даје комбинивани одговор.* +*Повезивање алата у акцији — агент прво позива getCurrentWeather, затим прослеђује Целзијус резултат алату celsiusToFahrenheit и даје комбиновани одговор.* -**Љубазно руковање грешкама** — Питајте за време у граду који није у лажној бази података. Алатка враћа поруку о грешци, а AI објашњава да не може да помогне уместо да апликација падне. Алатке безбедно падају. Дијаграм испод упоређује ова два приступа — уз исправно руковање грешкама агент хвата изузетак и одговара корисно, док без тога цела апликација пада: +**Љубазно руковање грешкама** — Питајте за време у граду који није у лажним подацима. Алат враћа поруку о грешци, а AI објашњава да не може да помогне уместо да се апликација сруши. Алатке сигурно подносе неуспехе. Дијаграм испод сукобљава два приступа — уз исправно руковање грешкама, агент хвата изузетак и одговара корисно, док без тога цела апликација пада: -Error Handling Flow +Ток руковања грешкама -*Када алатка падне, агент хвата грешку и одговара корисним објашњењем уместо да се сруши.* +*Када алат не успе, агент хвата грешку и одговара корисним објашњењем уместо пада апликације.* -Ово се дешава у једном кораку разговора. Агент аутономно оркестрира више позива алатки. +Ово се дешава у једном кораку разговора. Агент аутономно оркестрира више позива алата. -## Покретање апликације +## Покрени апликацију -**Потврдите постављање:** +**Проверите деплои:** -Уверите се да `.env` фајл постоји у коренском директоријуму са Azure акредитивима (направљен током Модула 01). Покрените ово из директоријума овог модула (`04-tools/`): +Уверите се да `.env` фајл постоји у корену директоријума са Azure акредитивима (направљен током Модула 01). Покрените ову команду из директоријума модула (`04-tools/`): **Bash:** ```bash -cat ../.env # Требало би да приказује AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Треба да прикаже AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Треба да приказује AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Требало би да прикаже AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Покрените апликацију:** +**Покретање апликације:** -> **Напомена:** Ако сте већ покренули све апликације користећи `./start-all.sh` из коренског директоријума (као што је описано у Модулу 01), овај модул већ ради на порту 8084. Можете прескочити следеће команде и отићи директно на http://localhost:8084. +> **Напомена:** Ако сте већ покренули све апликације помоћу `./start-all.sh` из кореног директоријума (као што је описано у Модулу 01), овај модул већ ради на порту 8084. Можете прескочити команде за покретање и одмах отићи на http://localhost:8084. -**Опција 1: Коришћење Spring Boot Dashboard-а (препоручено за кориснике VS Code-а)** +**Опција 1: Коришћење Spring Boot Dashboard (Препоручено за кориснике VS Code-а)** -Дев контејнер укључује екстензију Spring Boot Dashboard, која пружа визуелни интерфејс за управљање свим Spring Boot апликацијама. Можете је пронаћи у Activity Bar-у са леве стране VS Code-а (потражите Spring Boot иконицу). +Дев контејнер садржи проширење Spring Boot Dashboard које пружа визуелни интерфејс за управљање свим Spring Boot апликацијама. Можете га пронаћи у траци активности лево у VS Code-у (тражите Spring Boot иконицу). Из Spring Boot Dashboard-а можете: -- Виде све доступне Spring Boot апликације у радном простору -- Покренути/пауирати апликације једним кликом -- Пратити логове апликације у реалном времену +- Видети све доступне Spring Boot апликације у радном простору +- Покренути/зауставити апликације једним кликом +- Гледати логове апликације у реалном времену - Пратити статус апликације -Једноставно кликните на дугме за репродукцију поред „tools“ да бисте покренули овај модул, или покрените све модуле одједном. -Ево како изгледа Spring Boot Dashboard у VS Code: +Једноставно кликните на дугме за покретање поред "tools" да бисте покренули овај модул, или покрените све модуле одједном. -Spring Boot Dashboard +Ево како изгледа Spring Boot Dashboard у VS Code: +Spring Boot Контролна табла -*Spring Boot Dashboard у VS Code — покрените, зауставите и пратите све модуле са једног места* +*Spring Boot Контролна табла у VS Code — покрените, зауставите и надгледајте све модуле са једног места* **Опција 2: Коришћење shell скрипти** -Покрените све веб апликације (модули 01-04): +Покрените све веб апликације (модуле 01-04): **Bash:** ```bash -cd .. # Из корен директоријума +cd .. # Из коренског директоријума ./start-all.sh ``` @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Обе скрипте аутоматски учитавају променљиве окружења из `.env` фајла у коренском фолдеру и правиће JAR фајлове ако не постоје. +Обе скрипте аутоматски учитавају променљиве окружења из коренске `.env` датотеке и изградиће JAR фајлове ако не постоје. -> **Белешка:** Ако желите да ручно направите све модуле пре покретања: +> **Напомена:** Ако више волите да ручно изградите све модуле пре покретања: > > **Bash:** > ```bash @@ -274,7 +274,7 @@ cd 04-tools Отворите http://localhost:8084 у вашем прегледачу. -**Да зауставите:** +**За заустављање:** **Bash:** ```bash @@ -292,96 +292,96 @@ cd ..; .\stop-all.ps1 # Сви модули ## Коришћење апликације -Апликација пружа веб интерфејс где можете комуницирати са AI агентом који има приступ алатима за време и конверзију температуре. Ево како интерфејс изгледа — укључује примере за брзи почетак и ћаскање за слање захтева: +Апликација пружа веб интерфејс где можете комуницирати са AI агентом који има приступ алаткама за временску прогнозу и конверзију температуре. Ево како интерфејс изгледа — укључује примере за брз почетак и чет панел за слање упита: -AI Agent Tools Interface +AI Agent Алати Интерфејс -*AI Agent Tools интерфејс - брзи примери и интерфејс за ћаскање за интеракцију са алатима* +*AI Agent Алати интерфејс - брзи примери и чет интерфејс за интеракцију са алаткама* -### Испробајте једноставну употребу алата +### Испробајте једноставно коришћење алата -Почните са једноставним захтевом: „Конвертуј 100 степени Фаренхајта у Целзијус“. Агент препознаје да треба да користи алат за конверзију температуре, позива га са тачним параметрима и враћа резултат. Обратите пажњу колико је ово природно — нисте специфицирали који алат да се користи нити како да га позове. +Почните са једноставним захтевом: "Конвертуј 100 степени Фаренхајта у Целзијус". Агент препознаје да му треба алат за конверзију температура, позива га са правим параметрима и враћа резултат. Приметите колико ово делује природно - нисте навели који алат да се користи нити како да га позове. -### Тестирајте ланац алата +### Тестирајте повезивање алата -Сада покушајте нешто комплексније: „Какво је време у Сијетлу и конвертуј га у Фаренхајт?“ Пратите како агент решава ово у корацима. Прво добија информације о времену (које враћа у Целзијусима), препознаје да мора да конвертује у Фаренхајт, позива алат за конверзију и комбинује оба резултата у један одговор. +Сада испробајте нешто сложеније: "Какво је време у Сијетлу и конвертуј у Фаренхајт?" Пратите агента како ради корак по корак. Прво добија време (које враћа у Целзијусима), препознаје да треба конвертовати у Фаренхајт, позива алат за конверзију и комбинује оба резултата у један одговор. ### Погледајте ток разговора -Интерфејс за ћаскање чува историју разговора, омогућавајући да имате више размена. Можете видети све претходне упите и одговоре, што олакшава праћење разговора и разумевање како агент гради контекст кроз више интеракција. +Чет интерфејс чува историју разговора, омогућавајући вишекратну интеракцију. Можете видети све претходне упите и одговоре, што олакшава праћење разговора и разумевање како агент гради контекст кроз више размена. -Conversation with Multiple Tool Calls +Разговор са вишестуким позивима алата -*Више корака разговора који приказује једноставне конверзије, прегледе времена и ланце алата* +*Вишеструки разговор показује једноставне конверзије, претраге времена и повезивање алата* ### Испробајте различите захтеве -Покушајте различите комбиновације: -- Преглед времена: „Какво је време у Токију?“ -- Конверзије температуре: „Колико је 25°C у Келвинима?“ -- Комбиновани упити: „Провери време у Паризу и реци ми да ли је изнад 20°C“ +Пробајте различите комбинације: +- Претраге времена: "Какво је време у Токију?" +- Конверзије температура: "Колико је 25°C у Келвину?" +- Комбиновани упити: "Провери време у Паризу и реци ми да ли је изнад 20°C" -Обратите пажњу како агент тумачи природни језик и мапира га на одговарајуће позиве алата. +Приметите како агент тумачи природни језик и мапира га на одговарајуће позиве алата. ## Кључни појмови -### ReAct образац (Размишљање и деловање) +### ReAct Шаблон (Размишљање и Деловање) -Агент наизменично размисли (одлучује шта да ради) и делује (користи алате). Овај образац омогућава аутономно решавање проблема уместо само одговарања на инструкције. +Агент наизменично размишља (одлучује шта да уради) и делује (користи алате). Овај шаблон омогућава аутономно решавање проблема уместо само одговарања на упутства. ### Описи алата су важни -Квалитет описа ваших алата директно утиче на то како агент користи те алате. Јасни, специфични описи помажу моделу да разуме када и како позвати сваки алат. +Квалитет описа ваших алата директно утиче на то колико их агент добро користи. Јасни, прецизни описи помажу моделу да схвати када и како да позове сваки алат. ### Управљање сесијом -`@MemoryId` анотација омогућава аутоматско управљање меморијом базираном на сесијама. Сваки session ID добија свој `ChatMemory` инстанцу којом управља `ChatMemoryProvider` bean, тако да више корисника може истовремено да комуницира са агентом без мешања разговора. Следећа шема приказује како је више корисника усмерено на изоловане меморијске просторе на основу њихових session ID-ева: +Анотација `@MemoryId` омогућава аутоматски менаџмент меморије засноване на сесији. Сваки ID сесије добија своју `ChatMemory` инстанцу коју управља `ChatMemoryProvider` bean, тако да више корисника може истовремено да комуницира са агентом без мешања разговора. Следећа дијаграм показује како се више корисника усмерава на изоловане меморијске складиште на основу њихових ID сесије: -Session Management with @MemoryId +Управљање сесијом са @MemoryId -*Сваки session ID мапира историју разговора у изоловану меморију — корисници никада не виде поруке једни других.* +*Сваком ID сесије одговара изолована историја разговора — корисници никада не виде поруке једни других.* -### Обрада грешака +### Руковање грешкама -Алат може да пропадне — API-ји могу да истекну, параметри могу бити неважећи, спољни сервиси могу пасти. Производни агенти треба да имају обраду грешака како би модел могао да објасни проблем или покуша алтернативе, уместо да се читава апликација сруши. Када алат баци изузетак, LangChain4j га хвата и шаље поруку о грешци назад моделу, који може да објасни проблем природним језиком. +Алатке могу да не успеју — APIји могу истећи, параметри могу бити неважећи, спољни сервиси могу бити ван функције. Производни агенти морају да имају руковање грешкама како би модел могао да објасни проблеме или проба алтернативе уместо да сруши целу апликацију. Када алат баци изузетак, LangChain4j га хвата и шаље поруку о грешци назад моделу, који онда може на природном језику објаснити проблем. ## Доступни алати -Испод шема приказује широку екосистем алата које можете креирати. Овај модул демонстрира алате за време и температуру, али исти `@Tool` образац ради за било коју Java методу — од упита базе података до обраде плаћања. +Дијаграм испод показује широку екосистему алата које можете направити. Овај модул демонстрира алате за време и температуру, али исти `@Tool` шаблон ради за било који Java метод — од упита базе података до обраде плаћања. -Tool Ecosystem +Екосистем алата -*Било која Java метода анотирана са @Tool постаје доступна AI-ју — образац се проширује на базе података, API-је, имејл, операције са фајловима и још много тога.* +*Сваки Java метод анотиран са @Tool постаје доступан AI-ју — шаблон се проширује на базе података, APIје, имејл, рад са фајловима и више.* -## Када користити агенте базиране на алатима +## Када користити агенте засноване на алатима -Ниједан захтев не мора нужно да користи алате. Одлука зависи од тога да ли AI треба да комуницира са спољним системима или може да одговори из властитог знања. Следећи водич сумира када алати доносе вредност, а када нису потребни: +Не сваки захтев треба алате. Одлука зависи од тога да ли AI треба да комуницира са спољним системима или може одговорити из властитог знања. Следећи водич резимира када алати доносе вредност, а када нису неопходни: -When to Use Tools +Када користити алате -*Брз водич — алати су за реалне податке, калкулације и акције; опште знање и креативни задаци их не захтевају.* +*Кратак водич за одлуку — алати су за податке у реалном времену, калкулације и акције; опште знање и креативни задаци не захтевају алате.* -## Алати у односу на RAG +## Алати и RAG -Модули 03 и 04 оба проширују шта AI може да уради, али на супстанцијално различите начине. RAG даје моделу приступ **знању** тако што извлачи документе. Алатке дају моделу способност да изврши **акције** позивајући функције. Следећа шема упоређује ова два приступа поред један другог — од начина рада до компромиса између њих: +Модули 03 и 04 оба проширују шта AI може, али на фундаментално различите начине. RAG даје моделу приступ **знању** преузимањем докумената. Алати дају моделу могућност да предузима **акције** позивајући функције. Дијаграм испод упоређује ова два приступа један поред другог — од начина рада сваког до компромиса између њих: -Tools vs RAG Comparison +Поређење Алатки и RAG -*RAG преузима информације из статичних докумената — Алатке извршавају акције и добијају динамичке, реалне податке. Многи производни системи комбинују оба.* +*RAG преузима информације из статичних докумената — Алати извршавају акције и преузимају динамичке, реално-временске податке. Многи производни системи комбинују оба.* -У пракси, многи производни системи комбинују оба приступа: RAG за утемељење одговора у документацији и Алатке за добијање живих података или извршење операција. +У пракси, многи производни системи комбинују оба приступа: RAG за ослањање одговора на вашу документацију, и Алати за преузимање живих података или извођење операција. ## Следећи кораци -**Следећи модул:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Следећи модул:** [05-mcp - Моделски Контекст Протокол (MCP)](../05-mcp/README.md) --- -**Навигација:** [← Претходни: Модул 03 - RAG](../03-rag/README.md) | [Назад на главну](../README.md) | [Следећи: Модул 05 - MCP →](../05-mcp/README.md) +**Навигација:** [← Претходно: Модул 03 - RAG](../03-rag/README.md) | [Назад на главну](../README.md) | [Следеће: Модул 05 - MCP →](../05-mcp/README.md) --- -**Одрицање одговорности**: -Овај документ је преведен помоћу АИ услуге за превођење [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо прецизности, молимо имате у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитетним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешне интерпретације настале коришћењем овог превода. +**Изјава о одрицању одговорности**: +Овај документ је преведен коришћењем услуге за аутоматски превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода. \ No newline at end of file diff --git a/translations/sr/README.md b/translations/sr/README.md index cf53fd2a9..c092602dc 100644 --- a/translations/sr/README.md +++ b/translations/sr/README.md @@ -6,14 +6,14 @@ ### 🌐 Подршка за више језика -#### Подржано преко GitHub Action (Аутоматски и увек ажурирано) +#### Подржано преко GitHub акције (Аутоматизовано и увек ажурирано) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](./README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) > **Више волите да клонирате локално?** > -> Овај репозиторијум садржи преводе на 50+ језика што значајно повећава величину преузимања. Да бисте клонирали без превода, користите sparse checkout: +> Ово складиште садржи преводе на преко 50 језика, што знатно повећава величину преузимања. Да бисте клонирали без превода, користите sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,122 +29,121 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Ово вам даје све што вам је потребно за завршетак курса са много бржим преузимањем. +> Ово вам даје све што је потребно за завршетак курса са много бржим преузимањем. ## Садржај -1. [Брзи почетак](00-quick-start/README.md) - Започните са LangChain4j -2. [Увод](01-introduction/README.md) - Упознајте основе LangChain4j -3. [Дизајн упита](02-prompt-engineering/README.md) - Савладајте ефикасан дизајн упита -4. [RAG (Ретриевал-Аугментед Генератион)](03-rag/README.md) - Изградите интелигентне системе засноване на знању -5. [Алатке](04-tools/README.md) - Интегришите екстерне алатке и једноставне асистенте -6. [MCP (Протокол контекста модела)](05-mcp/README.md) - Рад са MCP и агентским модулима +1. [Увод](01-introduction/README.md) - Научите основе LangChain4j +2. [Prompt инжењеринг](02-prompt-engineering/README.md) - Савладајте ефикасан дизајн упита +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Направите интелигентне системе засноване на знању +4. [Алатке](04-tools/README.md) - Интегришите спољашње алате и једноставне асистенте +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Рад са протоколом моделског контекста (MCP) и агенцијским модулима -### Видео прегледи +### Видеоуроци -Сваки модул има придружену уживо сесију где корак по корак пролазимо кроз концепте и код. +Сваки модул има пратњу уживо у којој корак по корак презентујемо концепте и код. | Модул | Видео | |--------|-------| -| 01 - Увод | [Започните са LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Дизајн упита | [Дизајн упита са LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - Увод | [Започињање са LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Prompt инжењеринг | [Prompt инжењеринг са LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG са LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Алатке & 05 - MCP | [AI агенти са алаткама и MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Учeње корак по корак +## Пут учења -**Нов си у LangChain4j?** Погледајте [Речник](docs/GLOSSARY.md) за дефиниције кључних појмова и концепата. +**Нови сте у LangChain4j?** Погледајте [Речник](docs/GLOSSARY.md) за дефиниције кључних термина и појмова. > **Брзи почетак** -1. Форкујте овај репозиторијум на свој GitHub налог -2. Кликните **Code** → **Codespaces** таб → **...** → **New with options...** -3. Користите подразумеване поставке – одабраће се Development контејнер направљен за овај курс +1. Форкујте ово складиште на свој GitHub налог +2. Кликните **Code** → картица **Codespaces** → **...** → **New with options...** +3. Користите подразумеване поставке – одабраће се Development контејнер креиран за овај курс 4. Кликните **Create codespace** -5. Саčekајте 5-10 минута да се окружење припреми -6. Пратите одмах [Брзи почетак](./00-quick-start/README.md) да почнете! +5. Сачекајте 5-10 минута док се окружење припреми +6. Одмах идите на [Увод](./01-introduction/README.md) и почните! -Након завршетка модула, истражите [Водич за тестирање](docs/TESTING.md) да видите концепте LangChain4j тестирања у пракси. +Након завршетка модула, истражите [Водич за тестирање](docs/TESTING.md) да бисте видели концепте тестирања LangChain4j у пракси. -> **Напомена:** Ова обука користи како GitHub Models тако и Azure OpenAI. Модул [Брзи почетак](00-quick-start/README.md) користи GitHub Models (није потребна Azure претплата), док модули 1-5 користе Azure OpenAI. Почните са [БЕСПЛАТНИМ Azure налогом](https://aka.ms/azure-free-account) ако га немате. +> **Напомена:** Овај тренинг користи Azure OpenAI. Почните са [БЕСПЛАТНИМ Azure налогом](https://aka.ms/azure-free-account) ако га немате. -## Учите уз GitHub Copilot +## Учење са GitHub Copilot-ом -Да брзо кренете са кодирањем, отворите овај пројекат у GitHub Codespace-у или локалном IDE-у са приложеним devcontainer-ом. Devcontainer који се користи у овом курсу је претходно конфигурисан са GitHub Copilot-ом за AI парско програмирање. +Да бисте брзо почели да кодирајте, отворите овај пројекат у GitHub Codespace или у свом локалном IDE-ју са обезбеђеним devcontainer-ом. Devcontainer коришћен у овом курсу долази предконфигурисан са GitHub Copilot за AI парно програмирање. -Свако пример кода садржи предлоге питања која можете поставити GitHub Copilot-у да продубите разумевање. Потражите 💡/🤖 упутства у: +Свaki пример кода укључује предложена питања која можете поставити GitHub Copilot-у да бисте продубили разумевање. Потражите 💡/🤖 упутства у: - **Java заглављима датотека** - Питања специфична за сваки пример -- **Модулским README датотекама** - Упутства за даље истраживање након примера кода +- **READMEs модула** - Предлози за истраживање након примера кода -**Како користити:** Отворите било коју датотеку са кодом и поставите Copilot-у препоручена питања. Има пун контекст кодне базе и може објаснити, проширити и предложити алтернативе. +**Како користити:** Отворите било коју датотеку са кодом и поставите Copilot-у предложена питања. Има пун контекст код базе и може објашњавати, проширивати и предлагати алтернативе. -Желите да сазнате више? Погледајте [Copilot за AI парско програмирање](https://aka.ms/GitHubCopilotAI). +Желите да сазнате више? Погледајте [Copilot за AI парно програмирање](https://aka.ms/GitHubCopilotAI). ## Додатни ресурси ### LangChain -[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j за почетнике](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js за почетнике](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain за почетнике](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents -[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Агенти +[![AZD за почетнике](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI за почетнике](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP за почетнике](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI агенти за почетнике](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Generative AI Series -[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Серия генеративног AI +[![Генеративни AI за почетнике](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Генеративни AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Генеративни AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Генеративни AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- ### Основно учење -[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![ML за почетнике](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science за почетнике](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI за почетнике](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity за почетнике](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Веб развој за почетнике](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![ИоТ за почетнике](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![ИКС развој за почетнике](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Серја око Пилота -[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +### Серия Копилот +[![Копилот за АИ заједничко програмирање](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Копилот за Ц#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Копилот авантура](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## Добивање помоћи +## Помоћ -Ако запнете или имате било каквих питања о прављењу AI апликација, придружите се: +Ако запнете или имате било каквих питања у вези са креирањем АИ апликација, придружите се: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Ако имате повратне информације о производу или грешке током прављења, посетите: +Ако имате повратне информације о производу или грешке током развоја посетите: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Лиценца -MIT лиценца - Погледајте датотеку [LICENSE](../../LICENSE) за детаље. +MIT лиценца - Погледајте фајл [LICENSE](../../LICENSE) за детаље. --- -**Одрицање одговорности**: -Овај документ је преведен коришћењем AI сервиса за превођење [Co-op Translator](https://github.com/Azure/co-op-translator). Иако се трудимо да превод буде тачан, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Изворни документ на његовом оригиналном језику треба сматрати ауторитетом. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било какве неспоразуме или погрешне тумачења настала употребом овог превода. +**Изјава о одрицању одговорности**: +Овај документ је преведен коришћењем услуге за аутоматски превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода. \ No newline at end of file diff --git a/translations/sr/docs/GLOSSARY.md b/translations/sr/docs/GLOSSARY.md index 6c2fb6788..81ce7a6b8 100644 --- a/translations/sr/docs/GLOSSARY.md +++ b/translations/sr/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## Садржај -- [Основни појмови](../../../docs) -- [LangChain4j Компоненте](../../../docs) -- [AI/ML Концепти](../../../docs) -- [Guardrails](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agents and Tools](../../../docs) -- [Agentic Module](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure Services](../../../docs) -- [Testing and Development](../../../docs) - -Брза референца за термине и појмове коришћене кроз цео курс. +- [Основни појмови](#основни-појмови) +- [Компоненте LangChain4j](#компоненте-langchain4j) +- [Појмови везани за AI/ML](#појмови-везани-за-aiml) +- [Заштитне мере](#заштитне-мере) +- [Инжењеринг упита](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Агенти и алати](#agents-and-tools---module-04) +- [Агентни модул](#agentic-module---module-05) +- [Протокол контекста модела (MCP)](#model-context-protocol-mcp---module-05) +- [Azure услуге](#azure-services---module-01) +- [Тестирање и развој](#testing-and-development---testing-guide) + +Брзи преглед терминологије и концепата коришћених кроз цео курс. ## Основни појмови -**AI Agent** - Систем који користи вештачку интелигенцију за аутономно резоновање и деловање. [Модул 04](../04-tools/README.md) +**AI агент** - Систем који користи AI за аутономно размишљање и деловање. [Модул 04](../04-tools/README.md) -**Chain** - Низ операција где излаз служи као улаз за следећи корак. +**Ланац** - Низ операција где излаз иде у наредни корак. -**Chunking** - Разбијање докумената у мање делове. Типично: 300–500 токена са преклапањем. [Модул 03](../03-rag/README.md) +**Распарчивање** - Деловање докумената на мање делове. Типично: 300-500 токена са преклапањем. [Модул 03](../03-rag/README.md) -**Context Window** - Максималан број токена које модел може обрадити. GPT-5.2: 400К токена (до 272К улаз, 128К излаз). +**Прозор контекста** - Максималан број токена које модел може да обради. GPT-5.2: 400К токена (до 272К улаз, 128К излаз). -**Embeddings** - Нумерички вектори који представљају значење текста. [Модул 03](../03-rag/README.md) +**Ембеддинзи** - Нумерички вектори који представљају значење текста. [Модул 03](../03-rag/README.md) -**Function Calling** - Модел генерише структуиране захтеве за позивање спољних функција. [Модул 04](../04-tools/README.md) +**Позивање функција** - Модел генерише структуриране захтеве за позивање спољних функција. [Модул 04](../04-tools/README.md) -**Hallucination** - Када модели генеришу нетачне али вероватне информације. +**Халуцинација** - Када модели генеришу нетачне али веродостојне информације. -**Prompt** - Текстуални улаз за језички модел. [Модул 02](../02-prompt-engineering/README.md) +**Подстицај (пит)** - Текстуални улаз у језички модел. [Модул 02](../02-prompt-engineering/README.md) -**Semantic Search** - Претрага по значењу уз помоћ embeddings, а не по кључним речима. [Модул 03](../03-rag/README.md) +**Семантичка претрага** - Претрага по значењу коришћењем ембеддинза, а не кључних речи. [Модул 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: без меморије. Stateful: чува историју разговора. [Модул 01](../01-introduction/README.md) +**Државно стање против бездржавног** - Бездржавно: нема меморију. Стајтфул: одржава историју разговора. [Модул 01](../01-introduction/README.md) -**Tokens** - Основне текстуалне јединице које модели обрађују. Утичу на трошкове и лимите. [Модул 01](../01-introduction/README.md) +**Токени** - Основне текстуалне јединице које модели обрађују. Утичу на трошкове и ограничења. [Модул 01](../01-introduction/README.md) -**Tool Chaining** - Низкупно извршавање алата где излаз обавештава следећи позив. [Модул 04](../04-tools/README.md) +**Повезивање алата** - Секвенцијално извршење алата где излаз обавештава наредни позив. [Модул 04](../04-tools/README.md) -## LangChain4j Компоненте +## Компоненте LangChain4j -**AiServices** - Креира тип-безбедне интерфејсе за AI сервисе. +**AiServices** - Креира типско безбедне интерфејсе за AI услуге. -**OpenAiOfficialChatModel** - Уједињени клијент за OpenAI и Azure OpenAI моделе. +**OpenAiOfficialChatModel** - Јединствени клијент за OpenAI и Azure OpenAI моделе. -**OpenAiOfficialEmbeddingModel** - Креира embeddings користећи OpenAI Official клијента (подржава и OpenAI и Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Креира ембеддинге користећи OpenAI Official клијент (подржава OpenAI и Azure OpenAI). **ChatModel** - Основни интерфејс за језичке моделе. -**ChatMemory** - Чува историју разговора. +**ChatMemory** - Одржава историју разговора. **ContentRetriever** - Проналази релевантне делове докумената за RAG. -**DocumentSplitter** - Разбија документе у делове. +**DocumentSplitter** - Делује документе на делове. -**EmbeddingModel** - Претвара текст у нумеричке векторе. +**EmbeddingModel** - Прелази текст у нумеричке векторе. -**EmbeddingStore** - Чува и преузима embeddings. +**EmbeddingStore** - Чува и враћа ембеддинге. -**MessageWindowChatMemory** - Чува покретни прозор недавно размењених порука. +**MessageWindowChatMemory** - Одржава проклизавајући прозор недавних порука. -**PromptTemplate** - Креира поновно употребљиве инструкције са `{{variable}}` променљивим местима. +**PromptTemplate** - Креира поновно употребљиве захтеве са `{{variable}}` променљивкама. -**TextSegment** - Текстуални део са метаподацима. Користи се у RAG. +**TextSegment** - Текстуални сегмент са метаподацима. Користи се у RAG. **ToolExecutionRequest** - Представља захтев за извршење алата. **UserMessage / AiMessage / SystemMessage** - Типови порука у разговору. -## AI/ML Концепти +## Појмови везани за AI/ML -**Few-Shot Learning** - Даје примере у упутствима. [Модул 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Пружање примера у подстицајима. [Модул 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - AI модели обучени на огромним количинама текстуалних података. +**Велики језички модел (LLM)** - AI модели обучени на огромним текстуалним подацима. -**Reasoning Effort** - Параметар GPT-5.2 за контролу дубине размишљања. [Модул 02](../02-prompt-engineering/README.md) +**Напор закључивања** - GPT-5.2 параметар који контролише дубину размишљања. [Модул 02](../02-prompt-engineering/README.md) -**Temperature** - Контролише насумичност излаза. Низак = детерминистички, висок = креативан. +**Температура** - Контролише случајност излаза. Ниска=детерминистичко, висока=креативно. -**Vector Database** - Специјализована база података за embeddings. [Модул 03](../03-rag/README.md) +**Векторска база података** - Специјализована база за ембеддинге. [Модул 03](../03-rag/README.md) **Zero-Shot Learning** - Извођење задатака без примера. [Модул 02](../02-prompt-engineering/README.md) -## Guardrails - [Модул 00](../00-quick-start/README.md) +## Заштитне мере -**Defense in Depth** - Мулти-слојни приступ безбедности који комбинује заштитне мере на нивоу апликације са безбедносним филтерима провајдера. +**Одбрана у дубини** - Мултислојни безбедносни приступ који комбинује апликацијске заштитне мере са безбедносним филтерима провајдера. -**Hard Block** - Провајдер баца HTTP 400 грешку за озбиљне прекршаје садржаја. +**Хард блокада** - Провајдер баца HTTP 400 грешку за тешке кршења садржаја. -**InputGuardrail** - LangChain4j интерфејс за валидацију корисничких уноса пре него што дођу до LLM-а. Штеди трошкове и кашњење блокирајући штетне упите рано. +**InputGuardrail** - LangChain4j интерфејс за валидацију корисничког уноса пре него што досегне LLM. Штеди трошкове и латенцију блокирајући штетне упите рано. -**InputGuardrailResult** - Тип повратне вредности за валидацију guardrail-а: `success()` или `fatal("reason")`. +**InputGuardrailResult** - Тип повратне вредности за валидацију заштитне мере: `success()` или `fatal("разлог")`. **OutputGuardrail** - Интерфејс за валидацију AI одговора пре враћања корисницима. -**Provider Safety Filters** - Уграђени филтери садржаја AI провајдера (нпр. GitHub Models) који спречавају прекршаје на нивоу API-а. +**Provider Safety Filters** - Уграђени филтери садржаја AI провајдера (нпр. Azure OpenAI) који хватају кршења на нивоу API-ја. **Soft Refusal** - Модел пристојно одбија да одговори без бацања грешке. -## Prompt Engineering - [Модул 02](../02-prompt-engineering/README.md) +## Инжењеринг упита - [Модул 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Корак-по-корак резоновање за бољу прецизност. +**Chain-of-Thought** - Размишљање корак по корак за бољу прецизност. -**Constrained Output** - Приморавање специфичног формата или структуре. +**Ограничени излаз** - Примена специфијичног формата или структуре. -**High Eagerness** - GPT-5.2 шаблон за темељно размишљање. +**Висока воља** - GPT-5.2 образац за темељно разматрање. -**Low Eagerness** - GPT-5.2 шаблон за брзе одговоре. +**Ниска воља** - GPT-5.2 образац за брзе одговоре. -**Multi-Turn Conversation** - Одржавање контекста кроз размене. +**Вишекратни разговор** - Одржавање контекста кроз размене. -**Role-Based Prompting** - Постављање персоне модела путем системских порука. +**Ролно базирани подстицаји** - Постављање личности модела путем системских порука. -**Self-Reflection** - Модел процењује и унапређује свој излаз. +**Саморефлексија** - Модел процењује и побољшава свој излаз. -**Structured Analysis** - Фиксирани оквир за процену. +**Структурирана анализа** - Фиксни оквир за евалуацију. -**Task Execution Pattern** - Планирај → Изврши → Сажми. +**Образац извршења задатка** - Планирај → Изврши → Сумирај. ## RAG (Retrieval-Augmented Generation) - [Модул 03](../03-rag/README.md) -**Document Processing Pipeline** - Учитавање → раздвајање на делове → уграђивање → складиштење. +**Поток обраде докумената** - Учитај → распарчи → ембедуј → сачувај. -**In-Memory Embedding Store** - Неперзистентно складиштење за тестирање. +**Складиште ембеддинга у меморији** - Неперзистентно складиште за тестирање. -**RAG** - Комбинује претрагу са генерацијом за утемељене одговоре. +**RAG** - Комбинује проналажење података са генерисањем ради ослањања на чињенице у одговорима. -**Similarity Score** - Мера (0-1) семантичке сличности. +**Показатељ сличности** - Мера (0-1) семантичке сличности. -**Source Reference** - Мета-подаци о пронађеном садржају. +**Референца извора** - Метаподаци о пронађеном садржају. -## Agents and Tools - [Модул 04](../04-tools/README.md) +## Агенти и алати - [Модул 04](../04-tools/README.md) -**@Tool Annotation** - Означава Java методе као алате позивне од стране AI-а. +**@Tool белешка** - Означава Java методе као алате позивом од AI. -**ReAct Pattern** - Резонуј → Дели → Опажај → Понови. +**ReAct образац** - Размишљај → Делуј → Посматрај → Понављај. -**Session Management** - Одвојени контексти за различите кориснике. +**Управљање сесијом** - Посебни контексти за различите кориснике. -**Tool** - Функција коју AI агент може позвати. +**Алaт** - Функција коју AI агент може позвати. -**Tool Description** - Документација о сврси алатке и параметрима. +**Опис алата** - Документација сврхе алата и параметара. -## Agentic Module - [Модул 05](../05-mcp/README.md) +## Агентни модул - [Модул 05](../05-mcp/README.md) -**@Agent Annotation** - Означава интерфејсе као AI агенте са декларативним дефинисањем понашања. +**@Agent белешка** - Означава интерфејсе као AI агенте са декларативним дефинисањем понашања. -**Agent Listener** - Hook за праћење извршења агента преко `beforeAgentInvocation()` и `afterAgentInvocation()`. +**Agent Listener** - Хук за праћење извршења агента преко `beforeAgentInvocation()` и `afterAgentInvocation()`. -**Agentic Scope** - Заједничка меморија где агенти чувају излазе користећи `outputKey` да би их други агенти користили. +**Agentic Scope** - Заједничка меморија у којој агенти чувају резултате користећи `outputKey` које други агенти могу користити. -**AgenticServices** - Фабрика за креирање агената користећи `agentBuilder()` и `supervisorBuilder()`. +**AgenticServices** - Фабрика за прављење агената коришћењем `agentBuilder()` и `supervisorBuilder()`. -**Conditional Workflow** - Рутација заснована на условима ка различитим специјалистичким агентима. +**Условни ток посла** - Усмеравање на основу услова ка различитим специјалистичким агентима. -**Human-in-the-Loop** - Образац радног тока који додаје људске контролне тачке за одобрење или ревизију садржаја. +**Human-in-the-Loop** - Образац тока посла који додаје људске контролне тачке за одобрење или преглед садржаја. **langchain4j-agentic** - Maven зависност за декларативно грађење агената (експериментално). **Loop Workflow** - Понављање извршења агента док се не испуни услов (нпр. квалитет ≥ 0.8). -**outputKey** - Параметар анотације агента који одређује где се резултати чувају у Agentic Scope. +**outputKey** - Параметар у агенсткој белешци који указује где се резултати чувају у Agentic Scope. -**Parallel Workflow** - Паралелно извођење више агената за независне задатке. +**Паралелни ток посла** - Покретање више агената истовремено за независне задатке. -**Response Strategy** - Како супервизор формулише коначни одговор: LAST, SUMMARY или SCORED. +**Стратегија одговора** - Како супервайзор формулише коначни одговор: LAST, SUMMARY или SCORED. -**Sequential Workflow** - Извршавање агената по реду где излаз тече у следећи корак. +**Секвенцијални ток посла** - Извршавање агената по редоследу где излаз иде у следећи корак. -**Supervisor Agent Pattern** - Напредни агентски образац где супервизорски LLM динамички одлучује које под-агенте позвати. +**Supervisor Agent Pattern** - Напредни агентни образац где супервайзор LLM динамички одлучује које под-агенте позвати. -## Model Context Protocol (MCP) - [Модул 05](../05-mcp/README.md) +## Протокол контекста модела (MCP) - [Модул 05](../05-mcp/README.md) -**langchain4j-mcp** - Maven зависност за MCP интеграцију у LangChain4j. +**langchain4j-mcp** - Maven зависност за интеграцију MCP-а у LangChain4j. -**MCP** - Model Context Protocol: стандард за повезивање AI апликација са спољним алатима. Направи једном, користи свуда. +**MCP** - Протокол контекста модела: стандард за повезивање AI апликација са спољним алатима. Једном направи, свуда користи. -**MCP Client** - Апликација која се повезује на MCP сервере да открије и користи алате. +**MCP клијент** - Апликација која се повезује на MCP сервере ради откривања и коришћења алата. -**MCP Server** - Сервис који преко MCP изложи алате са јасним описима и шемама параметара. +**MCP сервер** - Услуга која изложи алате путем MCP-а са јасним описима и шемама параметара. -**McpToolProvider** - LangChain4j компонента која омотава MCP алате за коришћење у AI сервисима и агентима. +**McpToolProvider** - LangChain4j компонента која омотава MCP алате за употребу у AI услугама и агентима. **McpTransport** - Интерфејс за MCP комуникацију. Имплементације укључују Stdio и HTTP. -**Stdio Transport** - Локални транспорт процесом преко stdin/stdout. Корисно за приступ фајл системима или командно-линијским алатима. +**Stdio транспорту** - Локални пренос процеса преко stdin/stdout. Корисно за приступ фајл систему или алатима командне линије. **StdioMcpTransport** - LangChain4j имплементација која покреће MCP сервер као подпроцес. -**Tool Discovery** - Клијент пита сервер за доступне алате са описима и шемама. +**Откривање алата** - Клијент упитује сервер за доступне алате са описима и шемама. -## Azure Services - [Модул 01](../01-introduction/README.md) +## Azure услуге - [Модул 01](../01-introduction/README.md) -**Azure AI Search** - Облачна претрага са векторским могућностима. [Модул 03](../03-rag/README.md) +**Azure AI Search** - Облачна претрага са могућностима векторске претраге. [Модул 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Делокидање Azure ресурса. +**Azure Developer CLI (azd)** - Деплоира Azure ресурсе. -**Azure OpenAI** - Microsoft-ов ентерприс AI сервис. +**Azure OpenAI** - Microsoft-ова ентерпрајз AI услуга. -**Bicep** - Језик за инфраструктуру као код за Azure. [Водич за инфраструктуру](../01-introduction/infra/README.md) +**Bicep** - Језик за инфраструктуру као код у Azure-у. [Водич за инфраструктуру](../01-introduction/infra/README.md) -**Deployment Name** - Назив за деплој модела у Azure. +**Име деплоја** - Име за распоређивање модела у Azure-у. -**GPT-5.2** - Најновији OpenAI модел са контролом резоновања. [Модул 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Најновији OpenAI модел са контролом размишљања. [Модул 02](../02-prompt-engineering/README.md) -## Testing and Development - [Водич за тестирање](TESTING.md) +## Тестирање и развој - [Водич за тестирање](TESTING.md) -**Dev Container** - Контејнеризовано развојно окружење. [Конфигурација](../../../.devcontainer/devcontainer.json) +**Dev Container** - Кутија за развојне околности. [Конфигурација](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Бесплатна AI платформа за моделе. [Модул 00](../00-quick-start/README.md) +**Тестирање у меморији** - Тестирање са складиштењем у меморији. -**In-Memory Testing** - Тестирање са унутрашњом меморијом. +**Интеграционо тестирање** - Тестирање са правом инфраструктуром. -**Integration Testing** - Тестирање са правом инфраструктуром. +**Maven** - Јава алат за аутоматизацију изградње. -**Maven** - Алат за аутоматизацију Java изградње. +**Mockito** - Јава фрејмворк за моковање. -**Mockito** - Java фрејмворк за имитацију. - -**Spring Boot** - Java фрејмворк за апликације. [Модул 01](../01-introduction/README.md) +**Spring Boot** - Јава апликациони фрејмворк. [Модул 01](../01-introduction/README.md) --- -**Одрицање од одговорности**: -Овај документ је преведен помоћу АИ сервиса за превођење [Co-op Translator](https://github.com/Azure/co-op-translator). Иако се трудимо да превод буде прецизан, имајте у виду да аутоматизовани преводи могу садржати грешке или нетачности. Изворни документ на његовом оригиналном језику треба сматрати ауторитетним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешне тумачења која могу произаћи из коришћења овог превода. +**Изјава о одрицању одговорности**: +Овај документ је преведен коришћењем услуге за аутоматски превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода. \ No newline at end of file diff --git a/translations/sr/docs/TESTING.md b/translations/sr/docs/TESTING.md index 0e40cd0fb..3042416d4 100644 --- a/translations/sr/docs/TESTING.md +++ b/translations/sr/docs/TESTING.md @@ -2,13 +2,13 @@ ## Садржај -- [Брзи почетак](../../../docs) -- [Шта тестови обухватају](../../../docs) -- [Покретање тестова](../../../docs) -- [Покретање тестова у VS Code-у](../../../docs) -- [Обрасци тестирања](../../../docs) -- [Филозофија тестирања](../../../docs) -- [Следећи кораци](../../../docs) +- [Брзи почетак](#брзи-почетак) +- [Шта тестови покривају](#шта-тестови-покривају) +- [Покретање тестова](#покретање-тестова) +- [Покретање тестова у VS Code-у](#покретање-тестова-у-vs-code-у) +- [Обрасци тестирања](#обрасци-тестирања) +- [Филозофија тестирања](#филозофија-тестирања) +- [Следећи кораци](#следећи-кораци) Овај водич вас води кроз тестове који показују како тестирати AI апликације без потребе за API кључевима или спољним сервисима. @@ -26,27 +26,26 @@ mvn test mvn --% test ``` -Када сви тестови прођу, требало би да видите излаз као на снимку екрана испод — тестови се извршавају без грешака. +Када сви тестови прођу, требало би да видите излаз као на снимку екрана испод — тестови се извршавају без иједне грешке. -Успешни резултати тестирања +Успешни резултати тестова -*Успешно извршење тестова показујући да сви тестови пролазе без грешака* +*Успешно извршење тестова које показује да сви тестови пролазе без грешака* -## Шта тестови обухватају +## Шта тестови покривају -Овај курс се фокусира на **јединичне тестове** који се извршавају локално. Сваки тест демонстрира одређени LangChain4j концепт изоловано. Пирамида тестирања испод показује где јединични тестови припадају — они чине брзу, поуздану основу на којој се гради остатак ваше тест стратегије. +Овај курс се фокусира на **јединичне тестове** који се извршавају локално. Сваки тест демонстрира одређени LangChain4j концепт у изолацији. Пирамида тестирања у наставку показује где јединични тестови припадају — они чине брзу и поуздану основу на којој се гради остатак ваше стратегије тестирања. -Пирамида тестирања +Тестирачка пирамида -*Пирамида тестирања показује баланс између јединичних тестова (брзи, изоловани), интеграционих тестова (стварне компоненте) и end-to-end тестова. Ова обука покрива јединично тестирање.* +*Пирамида тестирања која показује баланс између јединичних тестова (брзи, изоловани), интеграционих тестова (праве компоненте) и end-to-end тестова. Ова обука покрива јединично тестирање.* -| Модул | Тестови | Фокус | Главне датотеке | -|--------|-------|-------|-----------| -| **00 - Брзи почетак** | 6 | Шаблони упита и замена променљивих | `SimpleQuickStartTest.java` | -| **01 - Увод** | 8 | Меморија конверзације и стање ћаскања | `SimpleConversationTest.java` | -| **02 - Инжењеринг упита** | 12 | GPT-5.2 обрасци, нивои жеље, структурисани излаз | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Унос докумената, уградње, претрага сличности | `DocumentServiceTest.java` | -| **04 - Алати** | 12 | Позив функција и ланци алата | `SimpleToolsTest.java` | +| Модул | Тестови | Фокус | Кључне датотеке | +|--------|---------|-------|-----------------| +| **01 - Увод** | 8 | Меморија конверзације и државност ћаскања | `SimpleConversationTest.java` | +| **02 - Инжењеринг подстицаја (Prompt)** | 12 | Обрасци GPT-5.2, нивои воље, структурисани излаз | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Унос докумената, уграђени вектори, претрага сличности | `DocumentServiceTest.java` | +| **04 - Алатке** | 12 | Позив функција и повезивање алатки | `SimpleToolsTest.java` | | **05 - MCP** | 8 | Протокол контекста модела са Stdio транспортом | `SimpleMcpTest.java` | ## Покретање тестова @@ -75,7 +74,7 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Или из root-а +# Или из корена mvn --% test -pl 01-introduction ``` @@ -91,11 +90,11 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Покрените одређену тест методу:** +**Покрените одређени тест метод:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#треба_одржавати_историју_разговора +mvn test -Dtest=SimpleConversationTest#требаОдржатиИсторијуРазговора ``` **PowerShell:** @@ -105,31 +104,31 @@ mvn --% test -Dtest=SimpleConversationTest#требаОдржаватиИсто ## Покретање тестова у VS Code-у -Ако користите Visual Studio Code, Test Explorer пружа графички интерфејс за покретање и отклањање грешака у тестовима. +Ако користите Visual Studio Code, Test Explorer пружа графички интерфејс за покретање и дебаговање тестова. VS Code Test Explorer -*VS Code Test Explorer приказује стабло тестова са свим Java тест класама и појединачним тест методама* +*VS Code Test Explorer који приказује стабло тестова са свим Java тест класама и појединачним тест методама* -**За покретање тестова у VS Code-у:** +**Да бисте покренули тестове у VS Code-у:** -1. Отворите Test Explorer кликом на икону колбице у Activity Bar-у -2. Проширите стабло тестова да бисте видели све модуле и тест класе -3. Кликните на дугме за репродукцију поред било ког теста да га покренете појединачно -4. Кликните "Run All Tests" да извршите цео скуп -5. Десни клик на било који тест и одаберите "Debug Test" да поставите тачке прекида и корачате кроз код +1. Отворите Test Explorer кликом на иконицу еprода у Activity Bar-у +2. Проширите стабло тестова да бисте видели све модуле и тест класе +3. Кликните на дугме за покретање поред било ког теста да га покренете појединачно +4. Кликните „Run All Tests“ да извршите цео скуп +5. Десни клик на било који тест и одаберите „Debug Test“ да поставите breakpoint и корак по корак пролазите кроз код -Test Explorer приказује зелене ознаке за тестове који су прошли и пружа детаљне поруке о грешкама када тестови не успеју. +Test Explorer приказује зелене ознаке за тестове који су успешно прошли и пружа детаљне поруке о грешкама када неки тест не прође. ## Обрасци тестирања -### Образац 1: Тестирање шаблона упита +### Образац 1: Тестирање шаблона подстицаја (Prompt Templates) -Најједноставнији образац тестира шаблоне упита без позива било ког AI модела. Ви проверавате да ли замена променљивих ради исправно и да ли су упити форматирани као што се очекује. +Најједноставнији образац тестира шаблоне без позива AI модела. Проверавате да ли се променљиве исправно замењују и да ли су подстицаји форматирани како се очекује. -Тестирање шаблона упита +Тестирање шаблона подстицаја -*Тестирање шаблона упита које показује ток замене променљивих: шаблон са ознакама места → примењене вредности → потврђен форматирани излаз* +*Тестирање шаблона подстицаја које показује ток замене променљивих: шаблон са ознакама → примењене вредности → верификовани форматирани излаз* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Овај тест је у `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Покрените га:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#тестирањеФорматирањаУзоракПоруке -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#тестирањеФорматисањаШаблонаПодударања -``` +Овај образац проверава да ли замена променљивих ради исправно и да ли су подстицаји форматирани како треба — није потребан API кључ нити позив модела. ### Образац 2: Моковање језичких модела -Када тестирате логику конверзације, користите Mockito за креирање лажних модела који враћају унапред одређене одговоре. Ово чини тестове брзим, бесплатним и детерминистичким. +При тестирању логике разговора, користите Mockito да креирате лажне моделе који враћају унапред дефинисане одговоре. Ово тестове чини брзим, бесплатним и детерминистичким. -Поређење мокова и стварног API-ја +Поређење лажног и правог API-ja -*Поређење које показује зашто су мокови погодни за тестирање: брзи су, бесплатни, детерминистички и не захтевају API кључеве* +*Поређење које показује зашто се мокови преферирају за тестирање: брзи су, бесплатни, детерминистички и не захтевају API кључеве* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 корисничке + 3 AI поруке + assertThat(history).hasSize(6); // 3 поруке корисника + 3 поруке вештачке интелигенције } } ``` -Овај образац се налази у `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Мок обезбеђује конзистентно понашање тако да можете проверити исправно управљање меморијом. +Овај образац се налази у `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Лажни модел осигурава доследно понашање како бисте могли да проверите исправно управљање меморијом. -### Образац 3: Тестирање изолације конверзације +### Образац 3: Тестирање изолације разговора -Меморија конверзације мора одржавати више корисника одвојено. Овај тест проверава да се контексти конверзација не мешају. +Меморија разговора мора држати више корисника одвојено. Овај тест проверава да се контексти разговора не мешају. -Изолација конверзације +Изолација разговора -*Тестирање изолације конверзације које показује посебне меморијске трезоре за различите кориснике да би спречило мешање контекста* +*Тестирање изолације разговора које показује одвојене меморије за различите кориснике како би се избегло мешање контекста* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Свака конверзација одржава своју независну историју. У производним системима, ова изолација је критична за мултикорисничке апликације. +Сваки разговор одржава своју независну историју. У продукцијским системима ова изолација је критична за мултикорисничке апликације. -### Образац 4: Тестирање алата самостално +### Образац 4: Тестирање алатки независно -Алати су функције које AI може позвати. Тестирајте их директно да бисте осигурали да раде исправно без обзира на одлуке AI-а. +Алатке су функције које AI може позвати. Тестирајте их директно да бисте били сигурни да раде исправно без обзира на одлуке AIја. -Тестирање алата +Тестирање алатки -*Тестирање алата независно показује извођење мок алата без позива AI-а ради провере пословне логике* +*Тестирање алатки независно које показује извршење лажних алатки без позива AI-ју ради верификације пословне логике* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Ови тестови из `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` верификују логику алата без укључења AI-а. Пример ланца показује како излаз једног алата улази у улаз другог. +Ови тестови из `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` верификују логику алатки без укључивања AIја. Пример повезивања показује како излаз једне алатке улази као улаз другој. -### Образац 5: Тестирање RAG у меморији +### Образац 5: Тестирање RAG-а у меморији -RAG системи традиционално захтевају векторске базе података и услуге за уградњу. Образац из меморије вам дозвољава да тестирате целу пајплајн без спољних зависности. +RAG системи обично захтевају векторске базе података и услуге уграђивања. Образац у меморији омогућава тестирање целе конзоле без спољних зависности. -Тестирање RAG у меморији +Тестирање RAG-а у меморији -*Ток рада тестирања RAG у меморији који показује парсирање докумената, чување уградњи и претрагу сличности без потребе за базом података* +*Радни ток тестирања RAG-а у меморији који показује парсирање докумената, чување уграђених вектора и претрагу сличности без потребе за базом података* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Овај тест из `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` креира документ у меморији и проверава цепање у делове и руковање метаподацима. +Овај тест из `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` креира документ у меморији и проверава раздвајање докумената на делове и руковање метаподацима. ### Образац 6: MCP интеграционо тестирање -MCP модул тестира интеграцију Протокола контекста модела користећи stdio транспорт. Ови тестови проверавају да ли ваша апликација може покренути MCP сервере као подпроцесе и комуницирати с њима. +MCP модул тестира интеграцију Протокола контекста модела користећи stdio транспорт. Ови тестови проверавају да ваша апликација може покренути и комуницирати са MCP серверима као подпроцесима. -Тестови у `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` верификују понашање MCP клијента. +Тестови из `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` верификују понашање MCP клијента. **Покрените их:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Филозофија тестирања -Тестирајте свој код, а не AI. Ваши тестови треба да верификују код који пишете проверавајући како су упити конструисани, како се управља меморијом и како се извршавају алати. AI одговори варирају и не би требало да буду део тврдњи у тестовима. Питајте се да ли ваш шаблон упита правилно замењује променљиве, а не да ли AI даје прави одговор. +Тестирајте ваш код, а не AI. Ваши тестови треба да верификују код који пишете проверавајући како се подстицаји конструишу, како се меморија управља и како се алатке извршавају. AI одговори варирају и не би требало да буду део тестних тврдњи. Питајте се да ли ваш шаблон подстицаја исправно замењује променљиве, а не да ли AI даје прави одговор. -Користите мокове за језичке моделе. Они су спољне зависности које су споре, скупе и недетерминистичке. Моковање чини тестове брзим са милисекундама уместо секунди, бесплатним без трошкова API-ја и детерминистичким са истим резултатом сваког пута. +Користите мокове за језичке моделе. Они су спољне зависности које су споре, скупе и недетерминистичке. Моковање чини тестове брзим са милисекундама уместо секунди, бесплатним без трошкова за API и детерминистичким са истим резултатом сваки пут. -Држите тестове независним. Сваки тест треба да подеси своје податке, не треба да се ослања на друге тестове и треба да очисти после себе. Тестови треба да пролазе без обзира на редослед извршавања. +Држите тестове независним. Сваки тест треба сам да постави своје податке, да не зависи од других тестова и да очисти за собом. Тестови треба да пролазе без обзира на редослед извршења. -Тестирајте крајње случајеве ван срећног пута. Покушајте празне уносе, веома велике уносе, специјалне знакове, неважеће параметре и граничне услове. Често ово открива грешке које нормална употреба не изазива. +Тестирајте и крајње случајеве ван срећног пута. Испробајте празне уносе, јако велике уносе, посебне знакове, неважеће параметре и граничне услове. Ово често открива багове које нормална употреба не показује. -Користите описне називе. Упоредите `shouldMaintainConversationHistoryAcrossMultipleMessages()` са `test1()`. Први вам тачно говори шта се тестира, што много олакшава отклањање грешака. +Користите описна имена. Упоредите `shouldMaintainConversationHistoryAcrossMultipleMessages()` са `test1()`. Прво вам тачно говори шта се тестира, што олакшава отклањање грешака. ## Следећи кораци -Сада када разумете obrasce тестирања, детаљније проучите сваки модул: +Сада када разумете обрасце тестирања, дубље се упустите у сваки модул: -- **[00 - Брзи почетак](../00-quick-start/README.md)** - Почните са основама шаблона упита -- **[01 - Увод](../01-introduction/README.md)** - Научите управљање меморијом конверзације -- **[02 - Инжењеринг упита](../02-prompt-engineering/README.md)** - Савладајте GPT-5.2 обрасце упита -- **[03 - RAG](../03-rag/README.md)** - Конструишите системе за генерацију са претрагом -- **[04 - Алати](../04-tools/README.md)** - Имплементирајте позив функција и ланце алата -- **[05 - MCP](../05-mcp/README.md)** - Интегришите Протокол контекста модела +- **[01 - Увод](../01-introduction/README.md)** - Научите управљање меморијом разговора +- **[02 - Инжењеринг подстицаја](../02/prompt-engineering/README.md)** - Савладајте GPT-5.2 обрасце подстицаја +- **[03 - RAG](../03-rag/README.md)** - Правите системе засноване на генерацији уз претрагу +- **[04 - Алатке](../04-tools/README.md)** - Имплементирајте позив функција и ланце алатки +- **[05 - MCP](../05-mcp/README.md)** - Интегришите Протокол контекста модела -Сваки модул у свом README-у пружа детаљна објашњења концепата тестираних овде. +README сваког модула пружа детаљна објашњења концепата тестираних овде. --- -**Навигација:** [← Назад на Главну](../README.md) +**Навигација:** [← Назад на главну](../README.md) --- -**Ограничење одговорности**: -Овај документ је преведен користећи АИ сервис за превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако се трудимо да превод буде тачан, молимо вас да имате у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитетним извором. За критичне информације препорука је коришћење професионалног људског превода. Не одговарамо за било каква неспоразума или погрешне тумачења настала употребом овог превода. +**Изјава о одрицању одговорности**: +Овај документ је преведен коришћењем услуге за аутоматски превод [Co-op Translator](https://github.com/Azure/co-op-translator). Иако тежимо тачности, имајте у виду да аутоматски преводи могу садржати грешке или нетачности. Оригинални документ на његовом изворном језику треба сматрати ауторитативним извором. За критичне информације препоручује се професионални људски превод. Нисмо одговорни за било каква неспоразума или погрешна тумачења која произилазе из коришћења овог превода. \ No newline at end of file diff --git a/translations/sv/.co-op-translator.json b/translations/sv/.co-op-translator.json index 869c2b4b8..b80efd035 100644 --- a/translations/sv/.co-op-translator.json +++ b/translations/sv/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "sv" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T00:56:53+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T10:02:11+00:00", "source_file": "01-introduction/README.md", "language_code": "sv" }, @@ -18,20 +18,20 @@ "language_code": "sv" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T00:58:34+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T09:57:52+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "sv" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T00:59:39+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T10:01:16+00:00", "source_file": "03-rag/README.md", "language_code": "sv" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:35:17+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T10:00:00+00:00", "source_file": "04-tools/README.md", "language_code": "sv" }, @@ -54,8 +54,8 @@ "language_code": "sv" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:09:40+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T09:56:34+00:00", "source_file": "README.md", "language_code": "sv" }, @@ -72,14 +72,14 @@ "language_code": "sv" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T01:02:09+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T09:58:20+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "sv" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T01:02:48+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T09:58:54+00:00", "source_file": "docs/TESTING.md", "language_code": "sv" } diff --git a/translations/sv/00-quick-start/README.md b/translations/sv/00-quick-start/README.md deleted file mode 100644 index be12b1316..000000000 --- a/translations/sv/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Kom igång - -## Innehållsförteckning - -- [Introduktion](../../../00-quick-start) -- [Vad är LangChain4j?](../../../00-quick-start) -- [LangChain4j beroenden](../../../00-quick-start) -- [Förutsättningar](../../../00-quick-start) -- [Installation](../../../00-quick-start) - - [1. Skaffa din GitHub-token](../../../00-quick-start) - - [2. Sätt din token](../../../00-quick-start) -- [Kör exemplen](../../../00-quick-start) - - [1. Grundläggande chatt](../../../00-quick-start) - - [2. Promptmönster](../../../00-quick-start) - - [3. Funktionsanrop](../../../00-quick-start) - - [4. Dokument Q&A (Easy RAG)](../../../00-quick-start) - - [5. Ansvarsfull AI](../../../00-quick-start) -- [Vad varje exempel visar](../../../00-quick-start) -- [Nästa steg](../../../00-quick-start) -- [Felsökning](../../../00-quick-start) - -## Introduktion - -Denna snabbstart är avsedd att få dig att komma igång med LangChain4j så snabbt som möjligt. Den täcker det absoluta grunderna för att bygga AI-applikationer med LangChain4j och GitHub Models. I nästa moduler går du över till Azure OpenAI och GPT-5.2 och fördjupar dig i varje koncept. - -## Vad är LangChain4j? - -LangChain4j är ett Java-bibliotek som förenklar att bygga AI-drivna applikationer. Istället för att hantera HTTP-klienter och JSON-parsing arbetar du med rena Java-API:er. - -"Kedjan" i LangChain avser att kedja ihop flera komponenter – du kan kedja en prompt till en modell till en parser, eller kedja flera AI-anrop där en output matas in som nästa input. Denna snabbstart fokuserar på grunderna innan mer komplexa kedjor utforskas. - -LangChain4j Chaining Concept - -*Kedja ihop komponenter i LangChain4j – byggblock kopplas ihop för att skapa kraftfulla AI-arbetsflöden* - -Vi använder tre kärnkomponenter: - -**ChatModel** – Gränssnittet för AI-modellinteraktioner. Anropa `model.chat("prompt")` och få ett svar som sträng. Vi använder `OpenAiOfficialChatModel` som fungerar med OpenAI-kompatibla endpoints som GitHub Models. - -**AiServices** – Skapar typ-säkra AI-tjänstegränssnitt. Definiera metoder, annotera med `@Tool`, och LangChain4j sköter orkestreringen. AI kallar automatiskt dina Java-metoder vid behov. - -**MessageWindowChatMemory** – Underhåller konversationshistorik. Utan denna är varje anrop oberoende. Med den kommer AI ihåg tidigare meddelanden och bibehåller kontext över flera turer. - -LangChain4j Architecture - -*LangChain4j-arkitektur – kärnkomponenter som arbetar ihop för att driva dina AI-applikationer* - -## LangChain4j beroenden - -Denna snabbstart använder tre Maven-beroenden i [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Modulen `langchain4j-open-ai-official` tillhandahåller klassen `OpenAiOfficialChatModel` som kopplar till OpenAI-kompatibla API:er. GitHub Models använder samma API-format, så ingen särskild adapter behövs – peka bara bas-URL:en till `https://models.github.ai/inference`. - -Modulen `langchain4j-easy-rag` tillhandahåller automatisk dokumentuppdelning, inbäddning och hämtning så att du kan bygga RAG-applikationer utan manuell konfiguration av varje steg. - -## Förutsättningar - -**Använder du Dev Container?** Java och Maven är redan installerade. Du behöver bara en GitHub Personal Access Token. - -**Lokal utveckling:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (instruktioner nedan) - -> **Notera:** Denna modul använder `gpt-4.1-nano` från GitHub Models. Ändra inte modellnamnet i koden – det är konfigurerat att fungera med GitHubs tillgängliga modeller. - -## Installation - -### 1. Skaffa din GitHub-token - -1. Gå till [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Klicka på "Generate new token" -3. Ange ett beskrivande namn (t.ex. "LangChain4j Demo") -4. Sätt utgångsdatum (7 dagar rekommenderas) -5. Under "Account permissions", hitta "Models" och sätt till "Read-only" -6. Klicka på "Generate token" -7. Kopiera och spara din token – du kommer inte se den igen - -### 2. Sätt din token - -**Alternativ 1: Använda VS Code (Rekommenderat)** - -Om du använder VS Code, lägg till din token i `.env`-filen i projektets rot: - -Om `.env`-filen inte finns, kopiera `.env.example` till `.env` eller skapa en ny `.env`-fil i projektroten. - -**Exempel på `.env`-fil:** -```bash -# I /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Därefter kan du högerklicka på valfri demo-fil (t.ex. `BasicChatDemo.java`) i Explorer och välja **"Run Java"** eller använda startkonfigurationerna från Run and Debug-panelen. - -**Alternativ 2: Använd Terminal** - -Sätt token som en miljövariabel: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Kör exemplen - -**Med VS Code:** Högerklicka helt enkelt på någon demofil i Explorer och välj **"Run Java"**, eller använd startkonfigurationer i Run and Debug-panelen (se till att du först lagt till din token i `.env`-filen). - -**Med Maven:** Alternativt kan du köra via kommandoraden: - -### 1. Grundläggande chatt - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Promptmönster - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Visar zero-shot, few-shot, chain-of-thought och rollbaserad prompting. - -### 3. Funktionsanrop - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI anropar automatiskt dina Java-metoder vid behov. - -### 4. Dokument Q&A (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Ställ frågor om dina dokument med Easy RAG, med automatisk inbäddning och hämtning. - -### 5. Ansvarsfull AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Se hur AI-säkerhetsfilter blockerar skadligt innehåll. - -## Vad varje exempel visar - -**Grundläggande chatt** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Börja här för att se LangChain4j i sin enklaste form. Du skapar en `OpenAiOfficialChatModel`, skickar en prompt med `.chat()` och får tillbaka ett svar. Detta visar grunden: hur man initierar modeller med egna endpoints och API-nycklar. När du förstår detta mönster bygger allt annat på det. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Testa med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) och fråga: -> - "Hur byter jag från GitHub Models till Azure OpenAI i den här koden?" -> - "Vilka andra parametrar kan jag konfigurera i OpenAiOfficialChatModel.builder()?" -> - "Hur lägger jag till streaming-svar istället för att vänta på komplett svar?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Nu när du vet hur man pratar med en modell, låt oss utforska vad du säger till den. Den här demon använder samma modellinställning men visar fem olika promptmönster. Prova zero-shot-prompter för direkta instruktioner, few-shot-prompter som lär från exempel, chain-of-thought-prompter som visar resonemangssteg och rollbaserade promter som sätter kontext. Du ser hur samma modell ger dramatiskt olika resultat beroende på hur du formulerar din fråga. - -Demon visar också promptmallar, ett kraftfullt sätt att skapa återanvändbara prompts med variabler. -Nedanstående exempel visar en prompt som använder LangChain4j:s `PromptTemplate` för att fylla i variabler. AI kommer svara baserat på angiven destination och aktivitet. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Testa med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) och fråga: -> - "Vad är skillnaden mellan zero-shot och few-shot prompting, och när bör jag använda vardera?" -> - "Hur påverkar temperatur-parametern modellens svar?" -> - "Vilka tekniker finns för att förhindra promptinjektionsattacker i produktion?" -> - "Hur kan jag skapa återanvändbara PromptTemplate-objekt för vanliga mönster?" - -**Verktygsintegration** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Här blir LangChain4j kraftfullt. Du använder `AiServices` för att skapa en AI-assistent som kan anropa dina Java-metoder. Annotera bara metoder med `@Tool("beskrivning")` och LangChain4j sköter resten – AI avgör automatiskt när varje verktyg ska användas baserat på användarens fråga. Detta demonstrerar funktionsanrop, en nyckelteknik för att bygga AI som kan utföra handlingar, inte bara svara på frågor. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Testa med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) och fråga: -> - "Hur fungerar @Tool-annoteringen och vad gör LangChain4j med den bakom kulisserna?" -> - "Kan AI använda flera verktyg i följd för att lösa komplexa problem?" -> - "Vad händer om ett verktyg kastar ett undantag – hur bör jag hantera fel?" -> - "Hur integrerar jag ett verkligt API istället för detta exempel med kalkylator?" - -**Dokument Q&A (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Här ser du RAG (retrieval-augmented generation) med LangChain4j:s "Easy RAG"-metod. Dokument laddas, delas automatiskt upp och bäddas in i ett minneslager, sedan levererar en innehållsinnhämtare relevanta delar till AI vid frågetillfället. AI svarar baserat på dina dokument, inte dess generella kunskap. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Testa med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) och fråga: -> - "Hur förhindrar RAG AI-hallucinationer jämfört med att använda modellens träningsdata?" -> - "Vad är skillnaden mellan detta enkla tillvägagångssätt och en egen RAG-pipeline?" -> - "Hur kan jag skala detta för att hantera flera dokument eller större kunskapsbaser?" - -**Ansvarsfull AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Bygg AI-säkerhet med försvar i djupet. Denna demo visar två skyddslager som arbetar tillsammans: - -**Del 1: LangChain4j Input Guardrails** – Blockera farliga prompts innan de når LLM. Skapa egna guardrails som kollar efter förbjudna nyckelord eller mönster. Dessa körs i din kod, så de är snabba och kostnadsfria. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Del 2: Leverantörens säkerhetsfilter** – GitHub Models har inbyggda filter som fångar vad dina guardrails kan missa. Du ser hårda blockeringar (HTTP 400-fel) vid allvarliga överträdelser och mjuka avslag där AI artigt tackar nej. - -> **🤖 Testa med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) och fråga: -> - "Vad är InputGuardrail och hur skapar jag egna?" -> - "Vad är skillnaden mellan hårt block och mjukt avslag?" -> - "Varför använda både guardrails och leverantörsfilter samtidigt?" - -## Nästa steg - -**Nästa modul:** [01-introduction - Kom igång med LangChain4j](../01-introduction/README.md) - ---- - -**Navigering:** [← Tillbaka till huvudsidan](../README.md) | [Nästa: Modul 01 - Introduktion →](../01-introduction/README.md) - ---- - -## Felsökning - -### Första bygg med Maven - -**Problem:** Initierande `mvn clean compile` eller `mvn package` tar lång tid (10-15 minuter) - -**Orsak:** Maven behöver ladda ner alla projektberoenden (Spring Boot, LangChain4j-bibliotek, Azure SDKs, etc.) vid första byggningen. - -**Lösning:** Detta är normalt. Efterföljande byggningar går mycket snabbare eftersom beroenden cachas lokalt. Nedladdningstiden beror på din nätverkshastighet. - -### Syntax för Maven-kommando i PowerShell - -**Problem:** Maven-kommandon misslyckas med felmeddelandet `Unknown lifecycle phase ".mainClass=..."` -**Orsak**: PowerShell tolkar `=` som en variabeltilldelningsoperator, vilket bryter Maven-egenskapssyntaxen - -**Lösning**: Använd stopparsingoperatorn `--%` före Maven-kommandot: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Operatorn `--%` talar om för PowerShell att vidarebefordra alla resterande argument bokstavligt till Maven utan tolkning. - -### Windows PowerShell Emoji-visning - -**Problem**: AI-svar visar skräptecken (t.ex. `????` eller `â??`) istället för emojis i PowerShell - -**Orsak**: PowerShells standardkodning stödjer inte UTF-8-emojis - -**Lösning**: Kör detta kommando innan du kör Java-applikationer: -```cmd -chcp 65001 -``` - -Detta tvingar UTF-8-kodning i terminalen. Alternativt, använd Windows Terminal som har bättre Unicode-stöd. - -### Felsökning av API-anrop - -**Problem**: Autentiseringsfel, hastighetsbegränsningar eller oväntade svar från AI-modellen - -**Lösning**: Exemplen inkluderar `.logRequests(true)` och `.logResponses(true)` för att visa API-anrop i konsolen. Det hjälper till att felsöka autentiseringsfel, hastighetsbegränsningar eller oväntade svar. Ta bort dessa flaggor i produktion för att minska loggbrus. - ---- - - -**Ansvarsfriskrivning**: -Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål ska betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår vid användning av denna översättning. - \ No newline at end of file diff --git a/translations/sv/01-introduction/README.md b/translations/sv/01-introduction/README.md index 5a38ef909..614465c37 100644 --- a/translations/sv/01-introduction/README.md +++ b/translations/sv/01-introduction/README.md @@ -2,84 +2,84 @@ ## Innehållsförteckning -- [Videogenomgång](../../../01-introduction) -- [Vad Du Kommer Lära Dig](../../../01-introduction) -- [Förutsättningar](../../../01-introduction) -- [Förstå kärnproblemet](../../../01-introduction) -- [Förstå tokens](../../../01-introduction) -- [Hur minne fungerar](../../../01-introduction) -- [Hur detta använder LangChain4j](../../../01-introduction) -- [Distribuera Azure OpenAI-infrastruktur](../../../01-introduction) -- [Kör applikationen lokalt](../../../01-introduction) -- [Använda applikationen](../../../01-introduction) - - [Stateless Chat (vänsterpanel)](../../../01-introduction) - - [Stateful Chat (högerpanel)](../../../01-introduction) -- [Nästa steg](../../../01-introduction) +- [Videogenomgång](#videogenomgång) +- [Vad du kommer att lära dig](#vad-du-kommer-att-lära-dig) +- [Förutsättningar](#förutsättningar) +- [Förstå det grundläggande problemet](#förstå-det-grundläggande-problemet) +- [Förstå tokens](#förstå-tokens) +- [Hur minnet fungerar](#hur-minnet-fungerar) +- [Hur detta använder LangChain4j](#hur-detta-använder-langchain4j) +- [Distribuera Azure OpenAI-infrastruktur](#distribuera-azure-openai-infrastruktur) +- [Kör applikationen lokalt](#kör-applikationen-lokalt) +- [Använda applikationen](#använda-applikationen) + - [Stateless chatt (vänster panel)](#stateless-chatt-vänster-panel) + - [Stateful chatt (höger panel)](#stateful-chatt-höger-panel) +- [Nästa steg](#nästa-steg) ## Videogenomgång -Titta på denna livesession som förklarar hur du kommer igång med denna modul: +Se denna livesession som förklarar hur du kommer igång med denna modul: Getting Started with LangChain4j - Live Session -## Vad Du Kommer Lära Dig +## Vad du kommer att lära dig -I snabbstarten använde du GitHub Models för att skicka prompts, anropa verktyg, bygga en RAG-pipeline och testa skyddsbarriärer. Dessa demo visade vad som är möjligt – nu byter vi till Azure OpenAI och GPT-5.2 och börjar bygga produktionslika applikationer. Denna modul fokuserar på konversationell AI som kommer ihåg kontext och bevarar tillstånd – de koncept som snabbstartsdemona använde i bakgrunden men inte förklarade. +Detta är din startpunkt med LangChain4j och Azure OpenAI. Vi börjar med grunderna och börjar bygga produktionsliknande applikationer. Den här modulen fokuserar på konversations-AI som kommer ihåg kontext och bibehåller tillstånd — de grundläggande koncepten som varje senare modul bygger på. -Vi använder Azure OpenAI:s GPT-5.2 genom hela denna guide eftersom dess avancerade resonemangsförmåga gör beteendet hos olika mönster tydligare. När du lägger till minne kommer du tydligt att se skillnaden. Detta gör det enklare att förstå vad varje komponent bidrar med till din applikation. +Vi kommer använda Azure OpenAI:s GPT-5.2 genom hela denna guide eftersom dess avancerade resonemangsförmåga gör beteendet hos olika mönster tydligare. När du lägger till minne ser du tydligt skillnaden. Detta gör det lättare att förstå vad varje komponent tillför din applikation. -Du kommer att bygga en applikation som demonstrerar båda mönstren: +Du kommer bygga en applikation som demonstrerar båda mönstren: -**Stateless Chat** – Varje förfrågan är oberoende. Modellen har inget minne av tidigare meddelanden. Detta är mönstret du använde i snabbstarten. +**Stateless Chat** – Varje förfrågan är oberoende. Modellen har inget minne av tidigare meddelanden. Detta är den enklaste startpunkten. -**Stateful Conversation** – Varje förfrågan inkluderar konversationshistorik. Modellen bevarar kontext över flera vändningar. Detta är vad produktionsapplikationer kräver. +**Stateful Conversation** – Varje förfrågan inkluderar konversationshistorik. Modellen bibehåller kontext över flera turer. Detta är vad produktionsapplikationer kräver. ## Förutsättningar -- Azure-prenumeration med tillgång till Azure OpenAI -- Java 21, Maven 3.9+ +- Azure-prenumeration med Azure OpenAI-åtkomst +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Obs:** Java, Maven, Azure CLI och Azure Developer CLI (azd) är förinstallerade i den tillhandahållna devcontainern. +> **Observera:** Java, Maven, Azure CLI och Azure Developer CLI (azd) är förinstallerade i den medföljande utvecklingscontainern. -> **Obs:** Denna modul använder GPT-5.2 på Azure OpenAI. Utplaceringen konfigureras automatiskt via `azd up` – ändra inte modellnamnet i koden. +> **Observera:** Den här modulen använder GPT-5.2 på Azure OpenAI. Distributionen konfigureras automatiskt via `azd up` – ändra inte modellnamnet i koden. -## Förstå kärnproblemet +## Förstå det grundläggande problemet -Språkmodeller är stateless. Varje API-anrop är oberoende. Om du skickar "Mitt namn är John" och sedan frågar "Vad heter jag?", har modellen ingen aning om att du just presenterade dig. Den behandlar varje förfrågan som om det vore din första konversation någonsin. +Språkmodeller är stateless. Varje API-anrop är oberoende. Om du skriver "Mitt namn är John" och sedan frågar "Vad heter jag?" har modellen ingen aning om att du just presenterade dig. Den behandlar varje förfrågan som om det vore din första konversation någonsin. -Det fungerar för enkla frågor och svar men är värdelöst för riktiga applikationer. Kundtjänstrobotar måste komma ihåg vad du har sagt. Personliga assistenter behöver kontext. Alla flervändskonversationer kräver minne. +Detta fungerar bra för enkla frågor och svar men är värdelöst för riktiga applikationer. Kundtjänstrobotar måste komma ihåg vad du sa till dem. Personliga assistenter behöver kontext. Varje konversation med flera turer kräver minne. -Följande diagram kontrasterar de två tillvägagångssätten – till vänster, ett stateless-anrop som glömmer ditt namn; till höger, ett stateful-anrop som stöds av ChatMemory som kommer ihåg det. +Följande diagram visar skillnaden mellan de två tillvägagångssätten — till vänster ett stateless-anrop som glömmer ditt namn; till höger ett stateful-anrop baserat på ChatMemory som kommer ihåg det. Stateless vs Stateful Conversations -*Skillnaden mellan stateless (oberoende anrop) och stateful (konstextmedvetna) konversationer* +*Skillnaden mellan stateless (oberoende anrop) och stateful (kontextmedvetna) konversationer* ## Förstå tokens -Innan vi dyker in i konversationer är det viktigt att förstå tokens – de grundläggande textenheterna som språkmodeller bearbetar: +Innan vi dyker in i konversationer är det viktigt att förstå tokens – grundläggande enheter av text som språkmodeller bearbetar: Token Explanation *Exempel på hur text delas upp i tokens – "I love AI!" blir 4 separata bearbetningsenheter* -Tokens är hur AI-modeller mäter och bearbetar text. Ord, skiljetecken och till och med mellanslag kan vara tokens. Din modell har en gräns för hur många tokens den kan bearbeta åt gången (400 000 för GPT-5.2, med upp till 272 000 inmatningstokens och 128 000 utmatningstokens). Att förstå tokens hjälper dig att hantera konversationens längd och kostnader. +Tokens är hur AI-modeller mäter och bearbetar text. Ord, skiljetecken och till och med mellanslag kan vara tokens. Din modell har en gräns för hur många tokens den kan bearbeta samtidigt (400 000 för GPT-5.2, med upp till 272 000 input-tokens och 128 000 output-tokens). Att förstå tokens hjälper dig att hantera konversationslängd och kostnader. -## Hur minne fungerar +## Hur minnet fungerar -Chattminne löser det stateless-problemet genom att bevara konversationshistorik. Innan din förfrågan skickas till modellen lägger ramverket till relevanta tidigare meddelanden. När du frågar "Vad heter jag?" skickar systemet faktiskt hela konversationshistoriken, vilket gör det möjligt för modellen att se att du tidigare sa "Mitt namn är John." +Chattminnet löser problemet med stateless genom att bibehålla konversationshistorik. Innan du skickar din förfrågan till modellen lägger ramverket till relevanta tidigare meddelanden. När du frågar "Vad heter jag?" skickar systemet faktiskt hela konversationshistoriken, vilket gör att modellen kan se att du tidigare sa "Mitt namn är John." -LangChain4j tillhandahåller minnesimplementationer som hanterar detta automatiskt. Du väljer hur många meddelanden som ska behållas och ramverket hanterar kontextfönstret. Diagrammet nedan visar hur MessageWindowChatMemory upprätthåller ett rullande fönster av nyliga meddelanden. +LangChain4j erbjuder minnesimplementationer som hanterar detta automatiskt. Du väljer hur många meddelanden som ska sparas och ramverket sköter kontextfönstret. Diagrammet nedan visar hur MessageWindowChatMemory bibehåller ett rullande fönster med nyligen skickade meddelanden. Memory Window Concept -*MessageWindowChatMemory upprätthåller ett rullande fönster av nyliga meddelanden, som automatiskt kastar äldre* +*MessageWindowChatMemory bibehåller ett rullande fönster med nyligen skickade meddelanden och tar automatiskt bort äldre* ## Hur detta använder LangChain4j -Denna modul utökar snabbstarten genom att integrera Spring Boot och lägga till konversationsminne. Så här passar bitarna ihop: +Denna modul integrerar Spring Boot och lägger till konversationsminne. Så här hänger delarna ihop: **Beroenden** – Lägg till två LangChain4j-bibliotek: @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Buildern läser inloggningsuppgifter från miljövariabler som sätts av `azd up`. Att sätta `baseUrl` till din Azure-endpoint gör att OpenAI-klienten fungerar med Azure OpenAI. +Buildern läser inloggningsuppgifter från miljövariabler satta av `azd up`. Genom att sätta `baseUrl` till din Azure-endpoint fungerar OpenAI-klienten med Azure OpenAI. -**Konversationsminne** – Spåra chattens historik med MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Konversationsminne** – Spåra chattloggen med MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Skapa minnet med `withMaxMessages(10)` för att behålla de sista 10 meddelandena. Lägg till användar- och AI-meddelanden med typade wrappers: `UserMessage.from(text)` och `AiMessage.from(text)`. Hämta historik med `memory.messages()` och skicka den till modellen. Tjänsten lagrar separata minnesinstanser per konversations-ID, vilket tillåter flera användare att chatta samtidigt. +Skapa minne med `withMaxMessages(10)` för att behålla de senaste 10 meddelandena. Lägg till användar- och AI-meddelanden med typade wrappers: `UserMessage.from(text)` och `AiMessage.from(text)`. Hämta historiken med `memory.messages()` och skicka den till modellen. Tjänsten lagrar separata minnesinstanser per konversations-ID, vilket gör det möjligt för flera användare att chatta samtidigt. > **🤖 Prova med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) och fråga: > - "Hur bestämmer MessageWindowChatMemory vilka meddelanden som ska tas bort när fönstret är fullt?" > - "Kan jag implementera eget minneslagring med en databas istället för i minnet?" -> - "Hur skulle jag lägga till sammanfattning för att komprimera gammal konversationshistorik?" +> - "Hur skulle jag lägga till summering för att komprimera gammal konversationshistorik?" -Stateless chatt-endpointen hoppar över minne helt – bara `chatModel.chat(prompt)` som i snabbstarten. Stateful-endpointen lägger till meddelanden i minnet, hämtar historik och inkluderar den kontexten med varje förfrågan. Samma modellkonfiguration, olika mönster. +Stateless-chattens endpoint hoppar över minnet helt – bara `chatModel.chat(prompt)` som i snabbstarten. Stateful-endpointen lägger till meddelanden i minnet, hämtar historik och inkluderar den kontexten i varje förfrågan. Samma modellkonfiguration, olika mönster. ## Distribuera Azure OpenAI-infrastruktur @@ -147,14 +147,14 @@ cd 01-introduction azd up # Välj prenumeration och plats (eastus2 rekommenderas) ``` -> **Obs:** Om du får ett timeout-fel (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), kör helt enkelt `azd up` igen. Azure-resurser kan fortfarande sättas upp i bakgrunden, och att försöka igen låter distributionen slutföras när resurserna går in i ett slutligt tillstånd. +> **Observera:** Om du får ett timeout-fel (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), kör helt enkelt `azd up` igen. Azure-resurser kan fortfarande provisioneras i bakgrunden och en ny försök gör att distributionen slutförs när resurserna når ett terminalt tillstånd. Detta kommer att: 1. Distribuera Azure OpenAI-resurs med GPT-5.2 och text-embedding-3-small modeller -2. Automatiskt generera `.env`-fil i projektets rot med inloggningsuppgifter +2. Automatiskt generera `.env`-fil i projektroten med inloggningsuppgifter 3. Sätta upp alla nödvändiga miljövariabler -**Har du distributionsproblem?** Se [Infrastructure README](infra/README.md) för detaljerad felsökning inklusive problem med subdomännamn, manuella steg för Azure Portal-distribution och modellkonfigurationsråd. +**Har du problem med distributionen?** Se [Infrastructure README](infra/README.md) för detaljerad felsökning inklusive konflikter om subdomännamn, manuella steg för distribution via Azure Portal, och modellkonfigurationsråd. **Verifiera att distributionen lyckades:** @@ -165,10 +165,10 @@ cat ../.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, etc. **PowerShell:** ```powershell -Get-Content ..\.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, osv. +Get-Content ..\.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, etc. ``` -> **Obs:** Kommandot `azd up` genererar automatiskt `.env`-filen. Om du behöver uppdatera den senare kan du redigera `.env`-filen manuellt eller generera om den genom att köra: +> **Observera:** Kommandot `azd up` genererar automatiskt `.env`-filen. Om du behöver uppdatera den senare kan du antingen redigera `.env`-filen manuellt eller återgenerera den genom att köra: > > **Bash:** > ```bash @@ -186,7 +186,7 @@ Get-Content ..\.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, osv. **Verifiera distribution:** -Säkerställ att `.env`-filen finns i rotkatalogen med Azure-uppgifter. Kör detta från modulkatalogen (`01-introduction/`): +Se till att `.env`-filen finns i rotkatalogen med Azure-uppgifter. Kör detta från modulkatalogen (`01-introduction/`): **Bash:** ```bash @@ -202,11 +202,11 @@ Get-Content ..\.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Alternativ 1: Använd Spring Boot Dashboard (Rekommenderas för VS Code-användare)** -Devcontainern inkluderar Spring Boot Dashboard-tillägget som ger ett visuellt gränssnitt för att hantera alla Spring Boot-applikationer. Du hittar det i aktivitetsfältet på vänster sida av VS Code (titta efter Spring Boot-ikonen). +Utvecklingscontainern inkluderar Spring Boot Dashboard-tillägget, som ger ett grafiskt gränssnitt för att hantera alla Spring Boot-applikationer. Du hittar det i aktivitetsfältet på vänster sida i VS Code (leta efter Spring Boot-ikonen). -I Spring Boot Dashboard kan du: -- Se alla tillgängliga Spring Boot-applikationer i workspace -- Starta/stoppa applikationer med ett klick +Från Spring Boot Dashboard kan du: +- Se alla tillgängliga Spring Boot-applikationer i arbetsytan +- Starta/stoppa applikationer med ett enda klick - Visa applikationsloggar i realtid - Övervaka applikationsstatus @@ -216,7 +216,7 @@ Klicka helt enkelt på play-knappen bredvid "introduction" för att starta denna *Spring Boot Dashboard i VS Code — starta, stoppa och övervaka alla moduler från en plats* -**Alternativ 2: Använd shell-script** +**Alternativ 2: Använd shell-skript** Starta alla webbapplikationer (moduler 01-04): @@ -232,7 +232,7 @@ cd .. # Från rotkatalogen .\start-all.ps1 ``` -Eller starta endast denna modul: +Eller starta bara denna modul: **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Båda skripten laddar automatiskt miljövariabler från root `.env`-fil och bygger JAR-filerna om de inte finns. +Båda skripten laddar automatiskt miljövariabler från rotens `.env`-fil och kommer bygga JAR-filerna om de inte finns. -> **Obs:** Om du föredrar att bygga alla moduler manuellt innan start: +> **Observera:** Om du föredrar att manuellt bygga alla moduler innan start: > > **Bash:** > ```bash @@ -286,25 +286,25 @@ Applikationen erbjuder ett webbgränssnitt med två chattimplementationer sida v Application Home Screen -*Dashboard som visar både Enkel Chatt (stateless) och Konversationell Chatt (stateful) alternativ* +*Dashboard som visar både Enkel Chatt (stateless) och Konversationschatt (stateful)* -### Stateless Chat (vänsterpanel) +### Stateless chatt (vänster panel) -Prova detta först. Säg "Mitt namn är John" och fråga direkt efter "Vad heter jag?" Modellen kommer inte ihåg eftersom varje meddelande är oberoende. Detta demonstrerar kärnproblemet med grundläggande språkmodellintegration – ingen konversationskontext. +Testa detta först. Skriv "Mitt namn är John" och fråga direkt efteråt "Vad heter jag?" Modellen kommer inte ihåg eftersom varje meddelande är oberoende. Detta visar det grundläggande problemet med enkel språkmodellintegration – ingen kontext i konversationen. Stateless Chat Demo *AI kommer inte ihåg ditt namn från föregående meddelande* -### Stateful Chat (högerpanel) +### Stateful chatt (höger panel) -Prova nu samma sekvens här. Säg "Mitt namn är John" och sedan "Vad heter jag?" Den här gången minns den. Skillnaden är MessageWindowChatMemory – den bevarar konversationshistorik och inkluderar den med varje förfrågan. Så fungerar produktionsklar konversationell AI. +Testa nu samma sekvens här. Skriv "Mitt namn är John" och sedan "Vad heter jag?" Denna gång kommer modellen ihåg. Skillnaden är MessageWindowChatMemory – den bibehåller konversationshistorik och inkluderar den vid varje förfrågan. Så fungerar produktionsklar konversations-AI. Stateful Chat Demo -*AI minns ditt namn från tidigare i konversationen* +*AI kommer ihåg ditt namn från tidigare i konversationen* -Båda panelerna använder samma GPT-5.2-modell. Den enda skillnaden är minnet. Detta visar tydligt vad minnet tillför till din applikation och varför det är nödvändigt för verkliga användningsfall. +Båda panelerna använder samma GPT-5.2-modell. Den enda skillnaden är minnet. Det gör det tydligt vad minnet tillför din applikation och varför det är avgörande för verkliga användningsfall. ## Nästa steg @@ -312,11 +312,11 @@ Båda panelerna använder samma GPT-5.2-modell. Den enda skillnaden är minnet. --- -**Navigering:** [← Föregående: Modul 00 - Snabbstart](../00-quick-start/README.md) | [Tillbaka till huvudsidan](../README.md) | [Nästa: Modul 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigation:** [← Tillbaka till huvudsidan](../README.md) | [Nästa: Modul 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **Ansvarsfriskrivning**: -Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, bör man vara medveten om att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess ursprungsspråk ska betraktas som den auktoritativa källan. För viktig information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning. +Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning. \ No newline at end of file diff --git a/translations/sv/02-prompt-engineering/README.md b/translations/sv/02-prompt-engineering/README.md index 468709d20..5e008f1e0 100644 --- a/translations/sv/02-prompt-engineering/README.md +++ b/translations/sv/02-prompt-engineering/README.md @@ -2,84 +2,84 @@ ## Innehållsförteckning -- [Video Walkthrough](../../../02-prompt-engineering) -- [Vad du kommer att lära dig](../../../02-prompt-engineering) -- [Förutsättningar](../../../02-prompt-engineering) -- [Förstå Prompt Engineering](../../../02-prompt-engineering) -- [Grunderna i Prompt Engineering](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Rollbaserad Prompting](../../../02-prompt-engineering) - - [Promptmallar](../../../02-prompt-engineering) -- [Avancerade mönster](../../../02-prompt-engineering) -- [Kör applikationen](../../../02-prompt-engineering) -- [Skärmdumpar från applikationen](../../../02-prompt-engineering) -- [Utforska mönstren](../../../02-prompt-engineering) - - [Låg vs Hög Iver](../../../02-prompt-engineering) - - [Uppgiftshantering (Verktygspreambler)](../../../02-prompt-engineering) - - [Självreflekterande kod](../../../02-prompt-engineering) - - [Strukturerad analys](../../../02-prompt-engineering) - - [Flerstegs-chatt](../../../02-prompt-engineering) - - [Steg-för-steg-resonemang](../../../02-prompt-engineering) - - [Begränsad output](../../../02-prompt-engineering) -- [Vad du egentligen lär dig](../../../02-prompt-engineering) -- [Nästa steg](../../../02-prompt-engineering) - -## Video Walkthrough - -Titta på denna livesession som förklarar hur du kommer igång med denna modul: +- [Videogenomgång](#videogenomgång) +- [Det du kommer lära dig](#det-du-kommer-lära-dig) +- [Förkunskaper](#förkunskaper) +- [Förstå prompt engineering](#förstå-prompt-engineering) +- [Grundläggande om prompt engineering](#grundläggande-om-prompt-engineering) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Promptmallar](#promptmallar) +- [Avancerade mönster](#avancerade-mönster) +- [Kör applikationen](#kör-applikationen) +- [Skärmdumpar från applikationen](#applikationsskärmbilder) +- [Utforska mönstren](#utforska-mönstren) + - [Låg vs hög iver](#low-vs-high-eagerness) + - [Uppgiftsutförande (verktygspreambler)](#utförande-av-uppgifter-verktygspreamblar) + - [Självreflekterande kod](#självreflekterande-kod) + - [Strukturerad analys](#strukturerad-analys) + - [Flergångs-chatt](#flerstegs-chatt) + - [Steg-för-steg-resonemang](#steg-för-steg-resonemang) + - [Begränsat utdata](#begränsad-utdatan) +- [Vad du verkligen lär dig](#vad-du-verkligen-lär-dig) +- [Nästa steg](#nästa-steg) + +## Videogenomgång + +Titta på denna direktsända session som förklarar hur du kommer igång med denna modul: Prompt Engineering with LangChain4j - Live Session -## Vad du kommer att lära dig +## Det du kommer lära dig -Följande diagram ger en översikt över de viktigaste ämnena och färdigheterna du kommer att utveckla i denna modul — från tekniker för förfining av prompts till det steg-för-steg-arbetsflöde du kommer följa. +Följande diagram ger en översikt över de viktigaste ämnena och färdigheterna du kommer utveckla i denna modul — från tekniker för förbättring av prompts till det steg-för-steg-arbetsflöde du kommer följa. What You'll Learn -I tidigare moduler har du utforskat grundläggande LangChain4j-interaktioner med GitHub Models och sett hur minne möjliggör konversations-AI med Azure OpenAI. Nu ska vi fokusera på hur du ställer frågor — själva prompterna — med Azure OpenAI:s GPT-5.2. Sättet du strukturerar dina prompts påverkar dramatiskt kvaliteten på svaren du får. Vi börjar med en översikt över grundläggande prompttekniker, sedan går vi vidare till åtta avancerade mönster som utnyttjar GPT-5.2:s kapabiliteter fullt ut. +I den föregående modulen såg du hur minne möjliggör konversations-AI med Azure OpenAI. Nu fokuserar vi på hur du ställer frågor — själva promptsen — med hjälp av Azure OpenAI:s GPT-5.2. Sättet du strukturerar dina prompts påverkar dramatiskt kvaliteten på svaren du får. Vi börjar med en översyn av de grundläggande prompting-teknikerna, och går sedan vidare till åtta avancerade mönster som utnyttjar GPT-5.2:s kapaciteter fullt ut. -Vi använder GPT-5.2 eftersom det introducerar resonemangskontroll – du kan berätta för modellen hur mycket tänkande den ska göra innan den svarar. Detta gör olika prompting-strategier tydligare och hjälper dig förstå när du ska använda varje metod. Vi drar också nytta av Azures färre begränsningar för GPT-5.2 jämfört med GitHub Models. +Vi använder GPT-5.2 eftersom den introducerar styrning av resonemang - du kan ange för modellen hur mycket tänkande den ska göra innan den svarar. Detta gör olika prompting-strategier tydligare och hjälper dig förstå när du ska använda varje tillvägagångssätt. -## Förutsättningar +## Förkunskaper -- Genomförd Modul 01 (Azure OpenAI-resurser utplacerade) -- `.env`-fil i rotkatalogen med Azure-uppgifter (skapad av `azd up` i Modul 01) +- Avslutad modul 01 (Azure OpenAI-resurser distribuerade) +- `.env`-fil i rotkatalogen med Azure-referenser (skapad av `azd up` i modul 01) -> **Obs:** Om du inte har genomfört Modul 01, följ först installationsinstruktionerna där. +> **Notera:** Om du inte har slutfört modul 01, följ installationsanvisningarna där först. -## Förstå Prompt Engineering +## Förstå prompt engineering I grunden handlar prompt engineering om skillnaden mellan vaga instruktioner och precisa sådana, som jämförelsen nedan illustrerar. What is Prompt Engineering? -Prompt engineering handlar om att designa inmatad text som konsekvent ger dig de resultat du behöver. Det är inte bara att ställa frågor – det handlar om att strukturera begäran så att modellen exakt förstår vad du vill ha och hur det ska levereras. +Prompt engineering handlar om att designa inmatningstext som konsekvent ger dig de resultat du behöver. Det handlar inte bara om att ställa frågor - det handlar om att strukturera förfrågningar så att modellen exakt förstår vad du vill ha och hur det ska levereras. -Tänk på det som att ge instruktioner till en kollega. "Fix the bug" är vagt. "Fix the null pointer exception in UserService.java line 45 by adding a null check" är specifikt. Språkmodeller fungerar på samma sätt – precision och struktur spelar roll. +Tänk på det som att ge instruktioner till en kollega. "Fix the bug" är vagt. "Fix the null pointer exception in UserService.java line 45 by adding a null check" är specifikt. Språkmodeller fungerar på samma sätt - specificitet och struktur är viktiga. -Diagrammet nedan visar hur LangChain4j passar in i bilden — kopplar dina promptmönster till modellen via byggstenarna SystemMessage och UserMessage. +Diagrammet nedan visar hur LangChain4j passar in i denna bild — genom att koppla dina promptmönster till modellen via byggstenarna SystemMessage och UserMessage. How LangChain4j Fits -LangChain4j tillhandahåller infrastrukturen — modellanslutningar, minne och meddelandetyper — medan promptmönster är bara noggrant strukturerad text som du skickar genom den infrastrukturen. De viktiga byggstenarna är `SystemMessage` (som ställer in AI:ns beteende och roll) och `UserMessage` (som bär din faktiska begäran). +LangChain4j tillhandahåller infrastrukturen — modellkopplingar, minne och meddelandetyper — medan promptmönster bara är noggrant strukturerad text som du skickar genom denna infrastruktur. Nyckelbyggstenarna är `SystemMessage` (som sätter AI:ns beteende och roll) och `UserMessage` (som förmedlar din faktiska förfrågan). -## Grunderna i Prompt Engineering +## Grundläggande om prompt engineering -De fem kärnteknikerna nedan utgör grunden för effektiv prompt engineering. Var och en tar upp en annan aspekt av hur du kommunicerar med språkmodeller. +De fem kärntekniker som visas nedan utgör grunden för effektiv prompt engineering. Var och en adresserar en annan aspekt av hur du kommunicerar med språkmodeller. Five Prompt Engineering Patterns Overview -Innan vi dyker in i de avancerade mönstren i denna modul, låt oss gå igenom fem grundläggande prompting-tekniker. Dessa är byggstenarna som varje promptingenjör bör känna till. Om du redan har arbetat igenom [Quick Start-modulen](../00-quick-start/README.md#2-prompt-patterns) har du sett dessa i praktiken – här är det konceptuella ramverket bakom dem. +Innan vi dyker in i de avancerade mönstren i denna modul, låt oss gå igenom fem grundläggande prompting-tekniker. Dessa är byggstenarna som varje promptingenjör bör känna till. ### Zero-Shot Prompting -Det enklaste tillvägagångssättet: ge modellen en direkt instruktion utan exempel. Modellen förlitar sig helt på sin träning för att förstå och utföra uppgiften. Detta fungerar bra för enkla begäranden där förväntat beteende är uppenbart. +Det enklaste tillvägagångssättet: ge modellen en direkt instruktion utan exempel. Modellen förlitar sig helt på sin träning för att förstå och utföra uppgiften. Detta fungerar bra för okomplicerade förfrågningar där förväntat beteende är uppenbart. Zero-Shot Prompting -*Direkt instruktion utan exempel – modellen härleder uppgiften endast från instruktionen* +*Direkt instruktion utan exempel — modellen härleder uppgiften utifrån instruktionen* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Svar: "Positiv" ``` -**När man ska använda:** Enkla klassificeringar, direkta frågor, översättningar eller uppgifter som modellen kan hantera utan ytterligare vägledning. +**När du ska använda det:** Enkla klassificeringar, direkta frågor, översättningar eller alla uppgifter som modellen kan hantera utan extra vägledning. ### Few-Shot Prompting -Ge exempel som visar mönstret du vill att modellen ska följa. Modellen lär sig det förväntade indata-utdata-formatet från dina exempel och tillämpar det på nya indata. Detta förbättrar dramatiskt konsekvensen för uppgifter där önskat format eller beteende inte är uppenbart. +Ge exempel som demonstrerar mönstret du vill att modellen ska följa. Modellen lär sig det förväntade inmatnings- och utdataformatet från dina exempel och tillämpar det på nya indata. Detta förbättrar drastiskt konsekvensen för uppgifter där det önskade formatet eller beteendet inte är självklart. Few-Shot Prompting -*Lär sig från exempel – modellen identifierar mönstret och tillämpar det på nya indata* +*Lära av exempel — modellen identifierar mönstret och tillämpar det på nya indata* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**När man ska använda:** Anpassade klassificeringar, konsekvent formattering, domänspecifika uppgifter eller när zero-shot-resultat är inkonsekventa. +**När du ska använda det:** Anpassade klassificeringar, konsekvent formatering, domänspecifika uppgifter eller när zero-shot-resultat är inkonsekventa. ### Chain of Thought -Be modellen visa sitt resonemang steg för steg. Istället för att hoppa direkt till ett svar bryter modellen ner problemet och arbetar igenom varje del explicit. Detta förbättrar noggrannheten i matematik, logik och flerstegsresonemangsuppgifter. +Be modellen visa sitt resonemang steg-för-steg. Istället för att hoppa direkt till ett svar delar modellen upp problemet och arbetar igenom varje del explicit. Detta förbättrar noggrannheten vid matematiska, logiska och flerstegsresonerande uppgifter. Chain of Thought Prompting -*Steg-för-steg-resonemang – bryter ner komplexa problem i explicita logiska steg* +*Steg-för-steg-resonemang — dela upp komplexa problem i tydliga logiska steg* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Modellen visar: 15 - 8 = 7, sedan 7 + 12 = 19 äpplen ``` -**När man ska använda:** Matematikproblem, logikpussel, felsökning eller andra uppgifter där att visa resonemangsprocessen förbättrar noggrannhet och förtroende. +**När du ska använda det:** Matteproblem, logiska pussel, felsökning eller alla uppgifter där att visa resonemangsprocessen förbättrar noggrannheten och förtroendet. -### Rollbaserad Prompting +### Role-Based Prompting -Sätt en persona eller roll för AI:n innan du ställer din fråga. Detta ger kontext som formar tonen, djupet och fokus i svaret. En "software architect" ger annan rådgivning än en "junior developer" eller en "security auditor". +Sätt en persona eller roll för AI:n innan du ställer din fråga. Detta ger kontext som formar tonen, djupet och fokus i svaret. En "software architect" ger andra råd än en "junior developer" eller en "security auditor". Role-Based Prompting -*Sätta kontext och persona – samma fråga får olika svar beroende på tilldelad roll* +*Ställa in kontext och persona — samma fråga får olika svar beroende på tilldelad roll* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**När man ska använda:** Kodgranskningar, handledning, domänspecifik analys eller när du behöver svar anpassade till en särskild expertisnivå eller perspektiv. +**När du ska använda det:** Kodgranskningar, handledning, domänspecifik analys eller när du behöver svar anpassade efter en viss expertisnivå eller perspektiv. ### Promptmallar -Skapa återanvändbara prompts med variabla platshållare. Istället för att skriva en ny prompt varje gång, definiera en mall en gång och fyll i olika värden. LangChain4js `PromptTemplate`-klass gör detta enkelt med `{{variable}}`-syntakt. +Skapa återanvändbara prompts med variabla platshållare. Istället för att skriva en ny prompt varje gång, definiera en mall en gång och fyll i olika värden. LangChain4j:s `PromptTemplate`-klass gör detta enkelt med `{{variable}}`-syntaxen. Prompt Templates -*Återanvändbara prompts med variabla platshållare – en mall, många användningar* +*Återanvändbara prompts med variabla platshållare — en mall, många användningar* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**När man ska använda:** Upprepade frågor med olika indata, batchbearbetning, bygga återanvändbara AI-arbetsflöden eller i situationer där promptens struktur förblir densamma men data ändras. +**När du ska använda det:** Upprepade frågor med olika indata, batchbearbetning, bygga återanvändbara AI-arbetsflöden eller alla scenarier där promptstrukturen är konstant men datat förändras. --- -Dessa fem grunder ger dig en robust verktygslåda för de flesta prompting-uppgifter. Resten av denna modul bygger vidare på dem med **åtta avancerade mönster** som utnyttjar GPT-5.2:s resonemangskontroll, självvärdering och strukturerade output-funktioner. +Dessa fem grundläggande tekniker ger dig en stabil verktygslåda för de flesta prompting-uppgifter. Resten av denna modul bygger vidare på dem med **åtta avancerade mönster** som utnyttjar GPT-5.2:s styrning av resonemang, självvärdering och strukturerad utdata. ## Avancerade mönster -Med grunderna på plats går vi vidare till de åtta avancerade mönster som gör denna modul unik. Inte alla problem behöver samma tillvägagångssätt. Vissa frågor kräver snabba svar, andra kräver djup eftertanke. Vissa behöver synligt resonemang, andra bara resultat. Varje mönster nedan är optimerat för ett specifikt scenario — och GPT-5.2:s resonemangskontroll förstärker skillnaderna ytterligare. +Med grunderna täckta, låt oss gå vidare till de åtta avancerade mönstren som gör denna modul unik. Inte alla problem kräver samma tillvägagångssätt. Vissa frågor behöver snabba svar, andra kräver djupt tänkande. Vissa behöver synligt resonemang, andra bara resultat. Varje mönster nedan är optimerat för ett annat scenario — och GPT-5.2:s resonemangsstyrning gör skillnaderna ännu tydligare. Eight Prompting Patterns *Översikt över de åtta prompt engineering-mönstren och deras användningsområden* -GPT-5.2 tillför en dimension till dessa mönster: *resonemangskontroll*. Reglaget nedan visar hur du kan justera modellens tänkande – från snabba, direkta svar till djup, grundlig analys. +GPT-5.2 lägger till en ny dimension till dessa mönster: *resonemangsstyrning*. Reglaget nedan visar hur du kan justera modellens tänkande — från snabba, direkta svar till djuplodande, grundlig analys. Reasoning Control with GPT-5.2 -*GPT-5.2:s resonemangskontroll låter dig specificera hur mycket modellen ska tänka – från snabba, direkta svar till djupgående utforskning* +*GPT-5.2:s resonemangsstyrning låter dig specificera hur mycket tänkande modellen ska göra — från snabba direkta svar till djup utforskning* -**Låg iver (Snabb & Fokuserad)** - För enkla frågor där du vill ha snabba, direkta svar. Modellen gör minimalt resonemang - max 2 steg. Använd detta för beräkningar, uppslag eller enkla frågor. +**Låg iver (Snabbt & Fokuserat)** - För enkla frågor där du vill ha snabba, direkta svar. Modellen gör minimalt resonemang - max 2 steg. Använd detta för beräkningar, uppslagningar eller enkla frågor. ```java String prompt = """ @@ -221,10 +221,10 @@ String response = chatModel.chat(prompt); > 💡 **Utforska med GitHub Copilot:** Öppna [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) och fråga: > - "Vad är skillnaden mellan låga och höga iver-promptmönster?" -> - "Hur hjälper XML-taggarna i prompts att strukturera AI:ns svar?" +> - "Hur hjälper XML-taggar i prompts att strukturera AI:ns svar?" > - "När ska jag använda självreflektionsmönster kontra direkt instruktion?" -**Hög iver (Djup & Grundlig)** - För komplexa problem där du vill ha en omfattande analys. Modellen undersöker noggrant och visar detaljerat resonemang. Använd detta för systemdesign, arkitekturval eller komplex forskning. +**Hög iver (Djupt & Grundligt)** - För komplexa problem där du vill ha en omfattande analys. Modellen undersöker grundligt och visar detaljerat resonemang. Använd detta för systemdesign, arkitekturval eller komplex forskning. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Uppgiftshantering (Steg-för-steg-framsteg)** - För arbetsflöden med flera steg. Modellen presenterar en plan i förväg, berättar om varje steg medan den arbetar, och avslutar med en sammanfattning. Använd detta för migrationer, implementeringar eller andra flerstegsprocesser. +**Uppgiftsutförande (Steg-för-steg-framsteg)** - För flerstegsarbetsflöden. Modellen ger en plan i förväg, berättar om varje steg under arbetets gång och avslutar med en sammanfattning. Använd detta för migrationer, implementationer eller alla flerstegsprocesser. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Chain-of-Thought prompting ber uttryckligen modellen att visa sitt resonemang, vilket förbättrar noggrannheten vid komplexa uppgifter. Steg-för-steg-nedbrytningen hjälper både människor och AI att förstå logiken. +Chain-of-Thought-prompting ber modellen visa sitt resonemang, vilket förbättrar noggrannheten för komplexa uppgifter. Genom att bryta ned processen steg-för-steg hjälper det både människor och AI att förstå logiken. > **🤖 Prova med [GitHub Copilot](https://github.com/features/copilot) Chat:** Fråga om detta mönster: -> - "Hur skulle jag anpassa uppgiftshanteringsmönstret för långvariga operationer?" +> - "Hur kan jag anpassa mönstret för uppgiftsutförande för långvariga operationer?" > - "Vilka är bästa praxis för att strukturera verktygspreambler i produktionsapplikationer?" -> - "Hur kan jag fånga och visa uppdateringar om mellanliggande framsteg i ett UI?" +> - "Hur kan jag fånga och visa mellanliggande uppdateringar i en användargränssnitt?" -Diagrammet nedan illustrerar detta Planera → Utföra → Sammanfatta arbetsflöde. +Diagrammet nedan illustrerar detta Planera → Utföra → Sammanfatta-arbetsflöde. Task Execution Pattern -*Arbetsflöde Planera → Utföra → Sammanfatta för flerstegsuppgifter* +*Planera → Utföra → Sammanfatta-arbetsflöde för flerstegsuppgifter* -**Självreflekterande kod** - För att generera produktionskvalitativ kod. Modellen genererar kod enligt produktionsstandarder med korrekt felhantering. Använd detta när du bygger nya funktioner eller tjänster. +**Självreflekterande kod** - För att generera produktionsklar kod. Modellen genererar kod som följer produktionsstandarder med korrekt felhantering. Använd detta när du bygger nya funktioner eller tjänster. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagrammet nedan visar denna iterativa förbättringscykel – generera, utvärdera, identifiera svagheter och förbättra tills koden uppfyller produktionsstandarder. +Diagrammet nedan visar denna iterativa förbättringscykel — generera, utvärdera, identifiera svagheter och förfina tills koden uppfyller produktionsstandarder. Self-Reflection Cycle -*Iterativ förbättringscykel – generera, utvärdera, upptäcka problem, förbättra, upprepa* +*Iterativ förbättringscykel - generera, utvärdera, identifiera problem, förbättra, upprepa* -**Strukturerad analys** - För konsekvent utvärdering. Modellen granskar kod med ett fast ramverk (korrekthet, praxis, prestanda, säkerhet, underhållbarhet). Använd detta för kodgranskningar eller kvalitetsbedömningar. +**Strukturerad analys** - För konsekvent utvärdering. Modellen granskar kod med en fast ram (korrekthet, praxis, prestanda, säkerhet, underhållbarhet). Använd detta för kodgranskningar eller kvalitetsbedömningar. ```java String prompt = """ @@ -356,16 +356,16 @@ String response = chatModel.chat(prompt); > **🤖 Prova med [GitHub Copilot](https://github.com/features/copilot) Chat:** Fråga om strukturerad analys: > - "Hur kan jag anpassa analysramverket för olika typer av kodgranskningar?" -> - "Vad är bästa sättet att programmässigt tolka och agera på strukturerad output?" -> - "Hur säkerställer jag konsekventa allvarlighetsnivåer mellan olika granskningssessioner?" +> - "Vad är bästa sättet att parsa och agera på strukturerad utdata programmässigt?" +> - "Hur säkerställer jag konsekventa allvarlighetsnivåer över olika granskningssessioner?" -Diagrammet nedan visar hur detta strukturerade ramverk organiserar en kodgranskning i konsekventa kategorier med allvarlighetsnivåer. +Följande diagram visar hur detta strukturerade ramverk organiserar en kodgranskning i konsekventa kategorier med allvarlighetsnivåer. Structured Analysis Pattern *Ramverk för konsekventa kodgranskningar med allvarlighetsnivåer* -**Flerstegs-chatt** - För konversationer som behöver kontext. Modellen kommer ihåg tidigare meddelanden och bygger vidare på dem. Använd detta för interaktiva hjälpsessioner eller komplexa frågor och svar. +**Flergångs-chatt** - För konversationer som behöver kontext. Modellen minns tidigare meddelanden och bygger vidare på dem. Använd detta för interaktiva hjälpsessioner eller komplexa frågor och svar. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Diagrammet nedan visualiserar hur kontexten i samtalet ackumuleras med varje tur och hur det förhåller sig till modellens tokenbegränsning. +Diagrammet nedan visualiserar hur konversationskontext ackumuleras med varje vändning och hur det relaterar till modellens token-gräns. Context Memory -*Hur samtalskontext ackumuleras över flera turer tills tokenbegränsningen nås* -**Steg-för-steg-resonemang** – För problem som kräver synlig logik. Modellen visar tydlig resonemang för varje steg. Använd detta för matematiska problem, logikpussel eller när du behöver förstå tankegången. +*Hur konversationskontext ackumuleras över flera vändningar tills token-gränsen nås* + +**Steg-för-steg-resonemang** - För problem som kräver synlig logik. Modellen visar explicit resonemang för varje steg. Använd detta för matteproblem, logiska pussel eller när du behöver förstå tänkandeprocessen. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Diagrammet nedan illustrerar hur modellen delar upp problem i explicita, numrerade logiska steg. +Diagrammet nedan illustrerar hur modellen delar upp problem i tydliga, numrerade logiska steg. Step-by-Step Pattern +*Nedbrytning av problem i tydliga logiska steg* -*Att bryta ned problem i explicita logiska steg* - -**Begränsad Output** – För svar med specifika formatkrav. Modellen följer strikt format- och längdregler. Använd detta för sammanfattningar eller när du behöver exakt outputstruktur. +**Begränsad utdata** – För svar med specifika formatkrav. Modellen följer strikt format- och längdregler. Använd detta för sammanfattningar eller när du behöver exakt utdata. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Följande diagram visar hur begränsningar styr modellen att producera output som strikt följer dina format- och längdkrav. +Följande diagram visar hur begränsningar styr modellen att producera utdata som strikt följer dina format- och längdkrav. -Constrained Output Pattern +Begränsad utdata-mönster -*Att tillämpa specifika format-, längd- och strukturkrav* +*Upprätthålla specifika format-, längd- och strukturkrav* ## Kör applikationen -**Verifiera distribution:** +**Verifiera distributionen:** -Säkerställ att filen `.env` finns i rotkatalogen med Azure-behörigheter (skapades under Modul 01). Kör detta från modulkatalogen (`02-prompt-engineering/`): +Säkerställ att filen `.env` finns i rotkatalogen med Azure-uppgifter (skapad under Modul 01). Kör detta från modulkatalogen (`02-prompt-engineering/`): **Bash:** ```bash @@ -439,16 +439,16 @@ cat ../.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **PowerShell:** ```powershell -Get-Content ..\.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Ska visa AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **Starta applikationen:** -> **Notera:** Om du redan startade alla applikationer med `./start-all.sh` från rotkatalogen (som beskrivs i Modul 01) kör denna modul redan på port 8083. Du kan hoppa över startkommandona nedan och gå direkt till http://localhost:8083. +> **Notera:** Om du redan startat alla applikationer med `./start-all.sh` från rotkatalogen (som beskrivs i Modul 01) kör denna modul redan på port 8083. Du kan då hoppa över startkommandona nedan och gå direkt till http://localhost:8083. **Alternativ 1: Använd Spring Boot Dashboard (Rekommenderas för VS Code-användare)** -Dev-containern inkluderar Spring Boot Dashboard-tillägget, som ger ett visuellt gränssnitt för att hantera alla Spring Boot-applikationer. Du hittar det i aktivitetsfältet till vänster i VS Code (leta efter Spring Boot-ikonen). +Dev-containern inkluderar Spring Boot Dashboard-tillägget, som ger ett visuellt gränssnitt för att hantera alla Spring Boot-applikationer. Du hittar det i aktivitetsfältet till vänster i VS Code (letar efter Spring Boot-ikonen). Från Spring Boot Dashboard kan du: - Se alla tillgängliga Spring Boot-applikationer i arbetsytan @@ -456,7 +456,7 @@ Från Spring Boot Dashboard kan du: - Visa applikationsloggar i realtid - Övervaka applikationens status -Klicka bara på play-knappen bredvid "prompt-engineering" för att starta denna modul, eller starta alla moduler samtidigt. +Klicka helt enkelt på play-knappen bredvid "prompt-engineering" för att starta denna modul, eller starta alla moduler samtidigt. Spring Boot Dashboard @@ -478,7 +478,7 @@ cd .. # Från rotkatalogen .\start-all.ps1 ``` -Eller starta enbart denna modul: +Eller starta bara denna modul: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Båda skripten laddar automatiskt miljövariabler från roten `.env`-filen och bygger JAR-filerna om de inte finns. +Båda skripten laddar automatiskt miljövariabler från rotens `.env`-fil och bygger JAR-filerna om de inte finns. -> **Notera:** Om du föredrar att manuellt bygga alla moduler innan start: +> **Notera:** Om du föredrar att bygga alla moduler manuellt innan start: > > **Bash:** > ```bash @@ -526,71 +526,71 @@ cd .. && ./stop-all.sh # Alla moduler cd ..; .\stop-all.ps1 # Alla moduler ``` -## Applikationsskärmdumpar +## Applikationsskärmbilder Här är huvudgränssnittet för prompt engineering-modulen, där du kan experimentera med alla åtta mönster sida vid sida. -Dashboard Home +Dashboard Hem -*Huvuddashboard som visar alla 8 prompt engineering-mönster med deras egenskaper och användningsområden* +*Huvuddashboard som visar alla 8 prompt engineering-mönster med deras egenskaper och användningsfall* ## Utforska mönstren -Webbgränssnittet låter dig experimentera med olika promptingstrategier. Varje mönster löser olika problem – prova dem för att se när varje metod passar bäst. +Webbgränssnittet låter dig experimentera med olika promptstrategier. Varje mönster löser olika problem – testa dem för att se när varje metod lyser. -> **Notera: Streaming vs Icke-streaming** — Varje mönstersida erbjuder två knappar: **🔴 Stream Response (Live)** och ett **Icke-streaming** alternativ. Streaming använder Server-Sent Events (SSE) för att visa tokens i realtid medan modellen genererar dem, så du ser framsteg direkt. Icke-streaming väntar på hela svaret innan det visas. För prompts som triggar djup resonemang (t.ex. High Eagerness, Self-Reflecting Code) kan icke-streaming-anrop ta väldigt lång tid — ibland flera minuter — utan synlig återkoppling. **Använd streaming när du experimenterar med komplexa prompts** så kan du se modellen arbeta och undvika intrycket att förfrågan har hängt sig. +> **Notera: Strömmande vs Icke-strömmande** — Varje mönstersida erbjuder två knappar: **🔴 Stream Response (Live)** och ett **icke-strömmande** alternativ. Strömning använder Server-Sent Events (SSE) för att visa token i realtid när modellen genererar dem, så du ser framstegen direkt. Det icke-strömmande alternativet väntar tills hela svaret är färdigt innan det visas. För prompts som kräver djup resonemang (t.ex. High Eagerness, Self-Reflecting Code) kan icke-strömmande anrop ta mycket lång tid – ibland minuter – utan synlig återkoppling. **Använd strömning när du experimenterar med komplexa prompts** så du kan se modellen arbeta och undvika intrycket att förfrågan har tidsutgått. > -> **Notera: Webbläsarkrav** — Streamingfunktionen använder Fetch Streams API (`response.body.getReader()`) som kräver en fullständig webbläsare (Chrome, Edge, Firefox, Safari). Det fungerar **inte** i VS Codes inbyggda Simple Browser, eftersom dess webvy inte stödjer ReadableStream API. Om du använder Simple Browser fungerar icke-streaming-knapparna normalt — det är bara streaming-knapparna som påverkas. Öppna `http://localhost:8083` i en extern webbläsare för full upplevelse. +> **Notera: Webbläsarkrav** — Strömfunktionaliteten använder Fetch Streams API (`response.body.getReader()`) som kräver en full webbläsare (Chrome, Edge, Firefox, Safari). Det fungerar **inte** i VS Codes inbyggda Simple Browser, eftersom dess webview inte stödjer ReadableStream API. Om du använder Simple Browser fungerar de icke-strömmande knapparna fortfarande normalt – endast strömknapparna är påverkade. Öppna `http://localhost:8083` i en extern webbläsare för full upplevelse. -### Låg vs Hög Eagerness +### Low vs High Eagerness -Ställ en enkel fråga som "Vad är 15% av 200?" med låg eagerness. Du får ett omedelbart, direkt svar. Ställ sedan en komplex fråga som "Designa en caching-strategi för ett högtrafikerat API" med hög eagerness. Klicka på **🔴 Stream Response (Live)** och se modellens detaljerade resonemang dyka upp token för token. Samma modell, samma frågestruktur – men prompten berättar hur mycket tänkande som ska göras. +Ställ en enkel fråga som "Vad är 15% av 200?" med Low Eagerness. Du får ett omedelbart, direkt svar. Ställ sedan något komplext som "Designa en caching-strategi för en högtrafikerad API" med High Eagerness. Klicka på **🔴 Stream Response (Live)** och se modellens detaljerade resonemang visas token-för-token. Samma modell, samma frågestruktur – men prompten talar om hur mycket tänkande som ska göras. -### Uppgiftsutförande (Verktygs-Preamblar) +### Utförande av uppgifter (Verktygspreamblar) -Flerstegsrutiner vinner på att planera och berätta om framsteg i förväg. Modellen beskriver vad den kommer att göra, kommenterar varje steg och sammanfattar sedan resultaten. +Flerstegsarbetsflöden gynnas av förhandsplanering och progressiv berättande. Modellen beskriver vad den ska göra, berättar om varje steg och sammanfattar sedan resultaten. ### Självreflekterande kod -Prova "Skapa en e-postvalideringstjänst". Istället för att bara generera kod och sluta, genererar modellen, utvärderar mot kvalitetskriterier, identifierar svagheter och förbättrar. Du ser den iterera tills koden uppfyller produktionsstandard. +Prova "Skapa en tjänst för e-postvalidering". Istället för att bara generera kod och sluta så genererar modellen, utvärderar mot kvalitetskriterier, identifierar svagheter och förbättrar. Du ser den iterera tills koden håller produktionsstandard. ### Strukturerad analys -Kodgranskningar behöver konsekventa utvärderingsramverk. Modellen analyserar kod med fasta kategorier (riktighet, praxis, prestanda, säkerhet) med allvarlighetsnivåer. +Kodgranskningar behöver konsekventa utvärderingsramverk. Modellen analyserar kod utifrån fasta kategorier (korrekthet, metoder, prestanda, säkerhet) med allvarlighetsnivåer. ### Flerstegs-chatt -Fråga "Vad är Spring Boot?" och följ sedan omedelbart upp med "Visa mig ett exempel". Modellen minns din första fråga och ger dig ett specifikt Spring Boot-exempel. Utan minne hade den andra frågan varit för vag. +Fråga "Vad är Spring Boot?" och följ direkt upp med "Visa ett exempel". Modellen minns din första fråga och ger dig ett specifikt Spring Boot-exempel. Utan minne hade den andra frågan varit för vag. ### Steg-för-steg-resonemang -Välj ett matteproblem och prova det både med Steg-för-steg-resonemang och Låg Eagerness. Låg eagerness ger bara svaret – snabbt men ointuitivt. Steg-för-steg visar varje beräkning och beslut. +Välj ett mattetal och prova med både Steg-för-steg-resonemang och Low Eagerness. Low eagerness ger bara svaret – snabbt men otydligt. Steg-för-steg visar varje beräkning och beslut. -### Begränsad output +### Begränsad utdatan -När du behöver specifika format eller antal ord, ser detta mönster till att formatet följs strikt. Prova att generera en sammanfattning med exakt 100 ord i punktform. +När du behöver specifika format eller ordantal, upprätthåller detta mönster strikt efterlevnad. Försök generera en sammanfattning med exakt 100 ord i punktlista. ## Vad du verkligen lär dig -**Resonerande ansträngning förändrar allt** +**Resoneringsinsats förändrar allt** -GPT-5.2 låter dig styra beräkningsinsatsen genom dina prompts. Låg ansträngning betyder snabba svar med minimal utforskning. Hög ansträngning betyder att modellen tar tid att tänka djupt. Du lär dig att matcha ansträngning efter uppgiftens komplexitet – slösa inte tid på enkla frågor, men skynda inte komplexa beslut. +GPT-5.2 låter dig kontrollera beräkningsinsats genom dina prompts. Låg insats ger snabba svar med minimal utforskning. Hög insats innebär att modellen tar tid på sig att tänka djupt. Du lär dig anpassa insats efter uppgiftskomplexitet – slösa inte tid på enkla frågor, men stressa inte komplexa beslut heller. **Struktur styr beteende** -Lägg märke till XML-taggarna i promptarna? De är inte dekorativa. Modeller följer strukturerade instruktioner mer pålitligt än fri form text. När du behöver flerstegsprocesser eller komplex logik hjälper strukturen modellen att hålla reda på var den är och vad som kommer härnäst. Diagrammet nedan bryter ner en välstrukturerad prompt och visar hur taggar som ``, ``, ``, ``, och `` organiserar dina instruktioner i tydliga sektioner. +Ser du XML-taggarna i prompts? De är inte bara dekorativa. Modeller följer strukturerade instruktioner mer pålitligt än fri text. När du behöver flerstegsprocesser eller komplex logik, hjälper struktur modellen att hålla koll på var den är och vad som kommer härnäst. Diagrammet nedan bryter ner en välstrukturerad prompt och visar hur taggar som ``, ``, ``, `` och `` organiserar dina instruktioner i tydliga sektioner. -Prompt Structure +Promptstruktur *Anatomi av en välstrukturerad prompt med tydliga sektioner och XML-liknande organisation* **Kvalitet genom självvärdering** -De självreflekterande mönstren fungerar genom att göra kvalitetskriterier explicita. Istället för att hoppas att modellen "gör rätt", berättar du exakt vad "rätt" betyder: korrekt logik, felhantering, prestanda, säkerhet. Modellen kan sedan värdera sin egen output och förbättra sig. Detta förvandlar kodgenerering från ett lotteri till en process. +De självreflekterande mönstren fungerar genom att göra kvalitetskriterier explicit. Istället för att hoppas att modellen "gör rätt", berättar du exakt vad "rätt" betyder: korrekt logik, felhantering, prestanda, säkerhet. Modellen kan sedan utvärdera sin egen output och förbättra sig. Detta förvandlar kodgenerering från ett lotteri till en process. **Kontext är ändlig** -Flerstegs-konversationer fungerar genom att inkludera meddelandehistorik med varje förfrågan. Men det finns en gräns — varje modell har ett maximalt tokenantal. När konversationer växer behöver du strategier för att behålla relevant kontext utan att nå taket. Denna modul visar hur minnet fungerar; senare lär du dig när du ska sammanfatta, när du ska glömma och när du ska hämta. +Flerstegs-samtal fungerar genom att inkludera meddelandehistorik i varje förfrågan. Men det finns en gräns – varje modell har ett max antal tokens. När samtal växer behöver du strategier för att behålla relevant kontext utan att nå taket. Denna modul visar hur minnet fungerar; senare lär du dig när du ska sammanfatta, när du ska glömma och när du ska hämta. ## Nästa steg @@ -598,11 +598,11 @@ Flerstegs-konversationer fungerar genom att inkludera meddelandehistorik med var --- -**Navigering:** [← Föregående: Modul 01 - Introduktion](../01-introduction/README.md) | [Tillbaka till huvud](../README.md) | [Nästa: Modul 03 - RAG →](../03-rag/README.md) +**Navigering:** [← Föregående: Modul 01 - Introduktion](../01-introduction/README.md) | [Tillbaka till huvudmeny](../README.md) | [Nästa: Modul 03 - RAG →](../03-rag/README.md) --- **Ansvarsfriskrivning**: -Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, vänligen observera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål ska anses vara den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för missförstånd eller feltolkningar som uppstår från användningen av denna översättning. +Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning. \ No newline at end of file diff --git a/translations/sv/03-rag/README.md b/translations/sv/03-rag/README.md index a49d989e6..582522e5c 100644 --- a/translations/sv/03-rag/README.md +++ b/translations/sv/03-rag/README.md @@ -2,143 +2,142 @@ ## Innehållsförteckning -- [Video Walkthrough](../../../03-rag) -- [Vad du kommer att lära dig](../../../03-rag) -- [Förutsättningar](../../../03-rag) -- [Förstå RAG](../../../03-rag) - - [Vilket RAG-tillvägagångssätt använder denna handledning?](../../../03-rag) -- [Hur det fungerar](../../../03-rag) - - [Dokumentbearbetning](../../../03-rag) - - [Skapa embeddings](../../../03-rag) - - [Semantisk sökning](../../../03-rag) - - [Svarsgenerering](../../../03-rag) -- [Kör applikationen](../../../03-rag) -- [Använda applikationen](../../../03-rag) - - [Ladda upp ett dokument](../../../03-rag) - - [Ställ frågor](../../../03-rag) - - [Kontrollera källreferenser](../../../03-rag) - - [Experimentera med frågor](../../../03-rag) -- [Nyckelkoncept](../../../03-rag) - - [Chunking-strategi](../../../03-rag) - - [Likhetspoäng](../../../03-rag) - - [I-minneslagring](../../../03-rag) - - [Hantera kontextfönster](../../../03-rag) -- [När RAG är viktigt](../../../03-rag) -- [Nästa steg](../../../03-rag) - -## Video Walkthrough - -Se denna livesession som förklarar hur du kommer igång med denna modul: - -RAG with LangChain4j - Live Session - -## Vad du kommer att lära dig - -I de tidigare modulerna lärde du dig hur du kan föra konversationer med AI och strukturera dina prompts effektivt. Men det finns en grundläggande begränsning: språkmodeller vet bara det de lärde sig under träningen. De kan inte svara på frågor om ditt företags policyer, din projekt-dokumentation eller någon information de inte tränades på. - -RAG (Retrieval-Augmented Generation) löser detta problem. Istället för att försöka lära modellen din information (vilket är dyrt och opraktiskt), ger du den möjligheten att söka igenom dina dokument. När någon ställer en fråga hittar systemet relevant information och inkluderar den i prompten. Modellen svarar sedan baserat på den hämtade kontexten. +- [Videogenomgång](#videogenomgång) +- [Det du kommer lära dig](#det-du-kommer-lära-dig) +- [Förkunskaper](#förkunskaper) +- [Förstå RAG](#förstå-rag) + - [Vilken RAG-metod använder denna handledning?](#vilken-rag-metod-använder-denna-handledning) +- [Hur det fungerar](#hur-det-fungerar) + - [Dokumentbearbetning](#dokumentbearbetning) + - [Skapa inbäddningar](#skapa-inbäddningar) + - [Semantisk sökning](#semantisk-sökning) + - [Svarsgenerering](#svarsgenerering) +- [Kör applikationen](#kör-applikationen) +- [Använda applikationen](#använda-applikationen) + - [Ladda upp ett dokument](#ladda-upp-ett-dokument) + - [Ställ frågor](#ställ-frågor) + - [Kontrollera källa-referenser](#kontrollera-källreferenser) + - [Experimentera med frågor](#experimentera-med-frågor) +- [Nyckelbegrepp](#nyckelbegrepp) + - [Chunking-strategi](#uppdelningsstrategi) + - [Likhetspoäng](#likhetspoäng) + - [Minneslagring](#minneslagring) + - [Hantera kontextfönster](#hantering-av-kontextfönster) +- [När RAG spelar roll](#när-rag-är-viktigt) +- [Nästa steg](#nästa-steg) + +## Videogenomgång + +Titta på denna livesession som förklarar hur du kommer igång med denna modul: + +RAG med LangChain4j - Livesession + +## Det du kommer lära dig + +I tidigare moduler lärde du dig hur man samtalar med AI och strukturerar dina prompts effektivt. Men det finns en grundläggande begränsning: språkmodeller vet bara det de lärde sig under träningen. De kan inte svara på frågor om ditt företags policyer, din projektdokumentation eller någon information de inte tränades på. + +RAG (Retrieval-Augmented Generation) löser detta problem. Istället för att försöka lära modellen din information (vilket är dyrt och opraktiskt) ger du den möjlighet att söka igenom dina dokument. När någon ställer en fråga hittar systemet relevant information och inkluderar den i prompten. Modellen svarar sedan baserat på den hämtade kontexten. Tänk på RAG som att ge modellen ett referensbibliotek. När du ställer en fråga gör systemet: 1. **Användarfråga** - Du ställer en fråga -2. **Embedding** - Omvandlar din fråga till en vektor +2. **Inbäddning** - Konverterar din fråga till en vektor 3. **Vektorsökning** - Hittar liknande dokumentbitar -4. **Kontextsammansättning** - Lägger till relevanta bitar i prompten +4. **Konstuktionssammanställning** - Lägger till relevanta bitar i prompten 5. **Svar** - LLM genererar ett svar baserat på kontexten -Detta grundar modellens svar i dina faktiska data istället för att förlita sig på dess träningskunskap eller hitta på svar. +Detta förankrar modellens svar i dina faktiska data istället för att förlita sig på dess träningskunskap eller hitta på svar. -## Förutsättningar +## Förkunskaper -- Avklarat [Modul 00 - Snabbstart](../00-quick-start/README.md) (för det lätta RAG-exemplet som refereras senare i denna modul) -- Avklarat [Modul 01 - Introduktion](../01-introduction/README.md) (Azure OpenAI-resurser distribuerade, inklusive embeddingmodellen `text-embedding-3-small`) -- `.env`-fil i rotkatalogen med Azure-uppgifter (skapad av `azd up` i Modul 01) +- Slutförd [Modul 01 - Introduktion](../01-introduction/README.md) (Azure OpenAI-resurser distribuerade, inklusive inbäddningsmodellen `text-embedding-3-small`) +- `.env`-fil i rotkatalogen med Azure-referenser (skapad med `azd up` i Modul 01) -> **Notera:** Om du inte har avklarat Modul 01, följ distributionsinstruktionerna där först. Kommandot `azd up` distribuerar både GPT chat-modellen och embeddingmodellen som används i denna modul. +> **Notera:** Om du inte har slutfört Modul 01, följ installationsinstruktionerna där först. Kommandot `azd up` distribuerar både GPT-chatmodellen och inbäddningsmodellen som används i denna modul. ## Förstå RAG -Diagrammet nedan illustrerar kärnbegreppet: istället för att bara förlita sig på modellens träningsdata ger RAG den ett referensbibliotek med dina dokument att konsultera innan varje svar genereras. +Diagrammet nedan illustrerar kärnkonceptet: istället för att enbart förlita sig på modellens träningsdata ger RAG modellen ett referensbibliotek av dina dokument att konsultera innan varje svar genereras. -What is RAG +Vad är RAG -*Detta diagram visar skillnaden mellan en standard-LLM (som gissar utifrån träningsdata) och en RAG-förbättrad LLM (som konsulterar dina dokument först).* +*Detta diagram visar skillnaden mellan en standard-LLM (som gissar från träningsdata) och en RAG-förstärkt LLM (som först konsulterar dina dokument).* -Så här kopplas delarna ihop från början till slut. En användares fråga passerar genom fyra steg — embedding, vektorsökning, kontextsammansättning och svarsgenerering — där varje steg bygger på det föregående: +Så här kopplas delarna samman från början till slut. En användares fråga går igenom fyra steg — inbäddning, vektorsökning, kontextsammanställning och svarsgenerering — där varje steg bygger på det föregående: -RAG Architecture +RAG-arkitektur -*Detta diagram visar den kompletta RAG-pipelinen — en användarfråga går igenom embedding, vektorsökning, kontextsammansättning och svarsgenerering.* +*Detta diagram visar den end-to-end RAG-pipelinen — en användarfråga går igenom inbäddning, vektorsökning, kontextsammanställning och svarsgenerering.* -Resten av denna modul går igenom varje steg i detalj, med kod du kan köra och modifiera. +Resten av denna modul går igenom varje steg i detalj med kod du kan köra och modifiera. -### Vilket RAG-tillvägagångssätt använder denna handledning? +### Vilken RAG-metod använder denna handledning? LangChain4j erbjuder tre sätt att implementera RAG, var och en med olika nivåer av abstraktion. Diagrammet nedan jämför dem sida vid sida: -Three RAG Approaches in LangChain4j +Tre RAG-metoder i LangChain4j -*Detta diagram jämför de tre LangChain4j RAG-tillvägagångssätten — Easy, Native och Advanced — visar deras nyckelkomponenter och när man ska använda varje.* +*Detta diagram jämför de tre LangChain4j RAG-metoderna — Easy, Native och Advanced — visar deras nyckelkomponenter och när man bör använda varje.* -| Tillvägagångssätt | Vad det gör | Avvägning | +| Metod | Vad den gör | Avvägning | |---|---|---| -| **Easy RAG** | Kopplar allt automatiskt via `AiServices` och `ContentRetriever`. Du annoterar ett interface, fäster en retriever, och LangChain4j hanterar embedding, sökning och promptsammanställning bakom kulisserna. | Minimal kod, men du ser inte vad som händer i varje steg. | -| **Native RAG** | Du kallar embeddingmodellen, söker i lagret, bygger prompten och genererar svaret själv — ett tydligt steg i taget. | Mer kod, men varje steg är synligt och modifierbart. | -| **Advanced RAG** | Använder `RetrievalAugmentor`-ramverket med pluggbara söktransformatorer, routrar, omrangörer och innehållsinjektorer för produktionspipeline. | Maximal flexibilitet, men avsevärt mer komplexitet. | +| **Easy RAG** | Kopplar allt automatiskt genom `AiServices` och `ContentRetriever`. Du annoterar ett gränssnitt, kopplar en retriever, och LangChain4j hanterar inbäddning, sökning och promptsammanställning i bakgrunden. | Minimal kod, men du ser inte vad som händer i varje steg. | +| **Native RAG** | Du anropar inbäddningsmodellen, söker i lagret, bygger prompten och genererar svaret själv — ett tydligt steg i taget. | Mer kod, men varje steg är synligt och kan modifieras. | +| **Advanced RAG** | Använder `RetrievalAugmentor`-ramverket med pluggbara frågetransformatorer, ruttrar, omrankare och innehållsinjektorer för produktionsklara pipelines. | Maximal flexibilitet, men avsevärt mer komplexitet. | -**Denna handledning använder Native-tillvägagångssättet.** Varje steg i RAG-pipelinen — embedda frågan, söka i vektorlager, sammanställa kontext och generera svar — skrivs explicit i [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Detta är avsiktligt: som inlärningsresurs är det viktigare att du ser och förstår varje steg än att koden är nedbantad. När du känner dig bekväm med hur delarna passar ihop kan du gå vidare till Easy RAG för snabba prototyper eller Advanced RAG för produktionssystem. +**Denna handledning använder Native-metoden.** Varje steg i RAG-pipelinen — att bädda in frågan, söka i vektorlager, sammanställa kontext och generera svar — är explicit utskrivet i [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Detta är avsiktligt: som en lärresurs är det viktigare att du ser och förstår varje steg än att koden är minimal. När du känner dig bekväm med hur delarna hänger ihop kan du gå vidare till Easy RAG för snabba prototyper eller Advanced RAG för produktionssystem. -> **💡Redan sett Easy RAG i aktion?** [Snabbstart-modulen](../00-quick-start/README.md) inkluderar ett exempel på dokument Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) som använder Easy RAG-tillvägagångssättet — LangChain4j hanterar embedding, sökning och promptsammanställning automatiskt. Denna modul tar nästa steg genom att bryta ned den pipelinen så att du kan se och styra varje steg själv. +> **💡 Nyfiken på Easy RAG?** LangChain4j erbjuder även en *Easy RAG*-metod där `AiServices` och en `ContentRetriever` hanterar inbäddning, sökning och promptsammanställning automatiskt. Denna modul tar den mer explicita vägen — bryter upp pipelinen så du kan se och kontrollera varje steg själv. -Diagrammet nedan visar Easy RAG-pipelinen från det exemplet i Snabbstarten. Lägg märke till hur `AiServices` och `EmbeddingStoreContentRetriever` döljer all komplexitet — du laddar ett dokument, fäster en retriever och får svar. Native-tillvägagångssättet i denna modul öppnar upp varje dolt steg: +Diagrammet nedan visar Easy RAG-pipelinen. Notera hur `AiServices` och `EmbeddingStoreContentRetriever` döljer all komplexitet — du laddar upp ett dokument, kopplar en retriever och får svar. Native-metoden i denna modul bryter upp dessa dolda steg: -Easy RAG Pipeline - LangChain4j +Easy RAG-pipeline - LangChain4j -*Detta diagram visar Easy RAG-pipelinen från `SimpleReaderDemo.java`. Jämför med Native-tillvägagångssättet som används i denna modul: Easy RAG döljer embedding, hämtning och promptsammanställning bakom `AiServices` och `ContentRetriever` — du laddar ett dokument, fäster en retriever och får svar. Native-tillvägagångssättet i denna modul öppnar upp den pipelinen så att du kallar varje steg (embedda, söka, sammanställa kontext, generera) själv, vilket ger full insyn och kontroll.* +*Detta diagram visar Easy RAG-pipelinen. Jämför med Native-metoden i denna modul: Easy RAG döljer inbäddning, hämtning och promptsammanställning bakom `AiServices` och `ContentRetriever` — du laddar upp ett dokument, fäster en retriever och får svar. Native-metoden bryter upp den pipelinen så du själv anropar varje steg (bädda in, sök, sammanställ kontext, generera), vilket ger full insyn och kontroll.* ## Hur det fungerar -RAG-pipelinen i denna modul delas upp i fyra steg som körs i sekvens varje gång en användare ställer en fråga. Först **parsas och chunkas** ett uppladdat dokument i hanterbara delar. Dessa bitar konverteras sedan till **vektorembeddings** och lagras för att kunna jämföras matematisk. När en fråga kommer in gör systemet en **semantisk sökning** för att hitta de mest relevanta bitarna och slutligen skickas dessa som kontext till LLM för **svarsgenerering**. Sektionerna nedan går igenom varje steg med faktisk kod och diagram. Börja med första steget. +RAG-pipelinen i denna modul delas upp i fyra steg som körs i följd varje gång en användare ställer en fråga. Först parsas och delas ett uppladdat dokument upp i hanterbara delar. Dessa delar konverteras sedan till vektorinbäddningar och lagras så att de kan jämföras matematiskt. När en fråga kommer gör systemet en semantisk sökning för att hitta de mest relevanta delarna, och slutligen skickas de som kontext till LLM:n för att generera ett svar. Sektionerna nedan går igenom varje steg med faktisk kod och diagram. Låt oss titta på första steget. ### Dokumentbearbetning [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -När du laddar upp ett dokument parsar systemet det (PDF eller ren text), fäster metadata som filnamn och delar sedan upp det i chunkar — mindre delar som får plats i modellens kontextfönster. Dessa chunkar överlappar något så att du inte tappar kontext vid gränserna. +När du laddar upp ett dokument parsar systemet det (PDF eller ren text), fäster metadata som filnamn och delar sedan upp det i chunkar — mindre bitar som passar bekvämt i modellens kontextfönster. Dessa bitar överlappar något så att du inte förlorar kontext vid gränserna. ```java -// Analysera den uppladdade filen och slå in den i ett LangChain4j-dokument +// Analysera den uppladdade filen och kapsla in den i ett LangChain4j-dokument Document document = Document.from(content, metadata); -// Dela upp i 300-tokenbitar med 30-token överlappning +// Dela upp i 300-token bitar med 30-token överlappning DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -Diagrammet nedan visar hur detta fungerar visuellt. Lägg märke till hur varje chunk delar vissa tokens med sina grannar — 30 tokens överlapp säkerställer att ingen viktig kontext faller mellan stolarna: -Document Chunking +Diagrammet nedan visar detta visuellt. Notera hur varje chunk delar vissa tokens med sina grannar — en 30-token överlappning säkerställer att ingen viktig kontext försvinner mellan sprickorna: -*Detta diagram visar ett dokument som delas upp i 300-token chunkar med 30-token överlapp för att bevara kontext vid chunkgränser.* +Dokumentdelning i chunkar + +*Detta diagram visar ett dokument som delas upp i chunkar om 300 tokens med 30 tokens överlappning, vilket bevarar kontexten vid chunk-gränserna.* > **🤖 Prova med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) och fråga: -> - "Hur delar LangChain4j dokument i chunkar och varför är överlapp viktigt?" -> - "Vad är optimal chunkstorlek för olika dokumenttyper och varför?" +> - "Hur delar LangChain4j upp dokument i chunkar och varför är överlappning viktig?" +> - "Vad är optimal chunk-storlek för olika dokumenttyper och varför?" > - "Hur hanterar jag dokument på flera språk eller med specialformatering?" -### Skapa embeddings +### Skapa inbäddningar [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Varje chunk konverteras till en numerisk representation kallad embedding — i huvudsak en omvandlare från mening till tal. Embeddingmodellen är inte "intelligent" på samma sätt som en chattmodell; den kan inte följa instruktioner, resonera eller svara på frågor. Vad den kan göra är att mappa text till ett matematiskt utrymme där liknande betydelser hamnar nära varandra — "bil" nära "automobil", "återbetalningspolicy" nära "återfå mina pengar". Tänk på en chattmodell som en person du kan prata med; en embeddingmodell är ett ultrabra arkivsystem. +Varje chunk omvandlas till en numerisk representation som kallas inbäddning — i princip en betydelse-till-siffror-omvandlare. Inbäddningsmodellen är inte "intelligent" på samma sätt som en chatmodell; den kan inte följa instruktioner, resonera eller svara på frågor. Det den kan göra är att mappa text till ett matematiskt rum där liknande betydelser hamnar nära varandra — ”bil” nära ”automobil”, ”återbetalningspolicy” nära ”få mina pengar tillbaka.” Tänk på en chatmodell som en person du kan prata med; en inbäddningsmodell är ett superskickligt arkiveringssystem. -Diagrammet nedan visualiserar konceptet — text går in, numeriska vektorer kommer ut, och liknande betydelser ger närliggande vektorer: +Diagrammet nedan visualiserar detta koncept — text går in, numeriska vektorer kommer ut, och liknande betydelser ger vektorer som hamnar nära varandra: -Embedding Model Concept +Inbäddningsmodellens koncept -*Detta diagram visar hur en embeddingmodell konverterar text till numeriska vektorer, där liknande betydelser — som "bil" och "automobil" — placeras nära varandra i vektorutrymmet.* +*Detta diagram visar hur en inbäddningsmodell konverterar text till numeriska vektorer, där liknande betydelser — som "bil" och "automobil" — placeras nära varandra i vektorrummet.* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -Klassdiagrammet nedan visar de två separata flödena i en RAG-pipeline och LangChain4j-klasserna som implementerar dem. **Inlagringsflödet** (körs en gång vid uppladdning) delar dokumentet, embedder chunkarna och lagrar dem via `.addAll()`. **Frågeflödet** (körs varje gång användaren frågar) embedder frågan, söker i lagret via `.search()` och skickar matchande kontext till chattmodellen. Båda flödena möts i det delade `EmbeddingStore`-gränssnittet: -LangChain4j RAG Classes +Klassdiagrammet nedan visar de två separata flödena i en RAG-pipeline och LangChain4j-klasserna som implementerar dem. **Inmatningsflödet** (körs en gång vid uppladdning) delar dokumentet, bäddar in chunkarna och lagrar dem via `.addAll()`. **Frågeflödet** (körs varje gång en användare frågar) bäddar in frågan, söker i lagret via `.search()`, och skickar den matchande kontexten till chatmodellen. Båda flödena möts vid delade `EmbeddingStore`-gränssnittet: + +LangChain4j RAG-klasser -*Detta diagram visar de två flödena i en RAG-pipeline — inläsning och fråga — och hur de kopplas ihop via ett delat EmbeddingStore.* +*Detta diagram visar de två flödena i en RAG-pipeline — inmatning och fråga — och hur de kopplas samman via ett gemensamt EmbeddingStore.* -När embeddings är lagrade klustras liknande innehåll naturligt tillsammans i vektorutrymmet. Visualiseringen nedan visar hur dokument om relaterade ämnen hamnar som närliggande punkter, vilket möjliggör semantisk sökning: +När inbäddningarna är lagrade klustrar liknande innehåll naturligt ihop sig i vektorrummet. Visualiseringen nedan visar hur dokument om relaterade ämnen hamnar som närliggande punkter, vilket möjliggör semantisk sökning: -Vector Embeddings Space +Vektor-inbäddningsrum -*Denna visualisering visar hur relaterade dokument klustras i 3D-vektorutrymmet, med ämnen som Teknikdokument, Affärsregler och FAQ som bildar separata grupper.* +*Denna visualisering visar hur relaterade dokument klustrar ihop sig i 3D-vektorrum med ämnen som Tekniska dokument, Affärsregler och FAQ:er som bildar distinkta grupper.* -När en användare söker följer systemet fyra steg: embedda dokumenten en gång, embedda frågan vid varje sökning, jämföra frågevektorn mot alla lagrade vektorer med kosinuslikhet, och returnera de bäst rankade top-K chunkarna. Diagrammet nedan visar varje steg och involverade LangChain4j-klasser: +När en användare söker följer systemet fyra steg: bädda in dokumenten en gång, bädda in frågan vid varje sökning, jämföra frågeverktorn mot alla lagrade vektorer med kosinuslikhet och returnera topp-K högst värderade chunkar. Diagrammet nedan går igenom varje steg och de LangChain4j-klasser som används: -Embedding Search Steps +Steg i inbäddningssökning -*Detta diagram visar fyra-stegs processen för embedding-sökning: embedda dokument, embedda frågan, jämföra vektorer med kosinuslikhet och returnera top-K resultat.* +*Detta diagram visar det fyrastegsprocessen för inbäddningssökning: bädda in dokument, bädda in fråga, jämför vektorer med kosinuslikhet och returnera toppresultaten.* ### Semantisk sökning [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -När du ställer en fråga blir även din fråga en embedding. Systemet jämför din frågas embedding mot alla dokumentchunks embeddings. Det hittar chunkarna med mest liknande betydelse — inte bara matchande nyckelord, utan riktig semantisk likhet. +När du ställer en fråga blir din fråga också en inbäddning. Systemet jämför frågans inbäddning med inbäddningarna för alla dokumentchunkar. Det hittar de chunkar som har mest liknande betydelse – inte bara nyckelords-matchning, utan faktisk semantisk likhet. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -Diagrammet nedan ställer semantisk sökning mot traditionell nyckelordssökning. En nyckelordssökning på "fordon" missar en chunk om "bilar och lastbilar", men semantisk sökning förstår att de betyder samma sak och returnerar det som ett högt rankat träff: -Semantic Search +Diagrammet nedan jämför semantisk sökning med traditionell nyckelordssökning. En nyckelordssökning på ”fordon” missar en chunk om ”bilar och lastbilar,” men semantisk sökning förstår att de betyder samma sak och returnerar den som en högt värderad träff: + +Semantisk sökning -*Detta diagram jämför nyckelordsbaserad sökning med semantisk sökning, och visar hur semantisk sökning hämtar konceptuellt relaterat innehåll även när exakta nyckelord skiljer sig åt.* -Under huven mäts likhet med hjälp av kosinuslikhet — i princip genom att fråga "pekar dessa två pilar i samma riktning?" Två textstycken kan använda helt olika ord, men om de betyder samma sak pekar deras vektorer åt samma håll och ger ett poängvärde nära 1,0: +*Detta diagram jämför nyckelordsbaserad sökning med semantisk sökning, och visar hur semantisk sökning hämtar konceptuellt relaterat innehåll även när exakta nyckelord skiljer sig.* -Cosine Similarity +Under huven mäts likheten med kosinuslikhet — i princip frågan ”pekar dessa två pilar i samma riktning?” Två chunkar kan använda helt olika ord, men om de betyder samma sak pekar deras vektorer åt samma håll och får ett värde nära 1.0: -*Denna diagram illustrerar kosinuslikhet som vinkeln mellan inbäddningsvektorer — mer anpassade vektorer får poäng närmare 1,0, vilket indikerar högre semantisk likhet.* +Kosinuslikhet +*Det här diagrammet illustrerar cosinuslikhet som vinkeln mellan inbäddningsvektorer — mer samordnade vektorer får poäng närmare 1,0, vilket indikerar högre semantisk likhet.* > **🤖 Prova med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) och fråga: -> - "Hur fungerar sökning baserat på likhet med inbäddningar och vad avgör poängen?" -> - "Vilken likhetströskel bör jag använda och hur påverkar det resultaten?" -> - "Hur hanterar jag fall där inga relevanta dokument hittas?" +> - "Hur fungerar likhetssökning med inbäddningar och vad avgör poängen?" +> - "Vilken likhetsgräns bör jag använda och hur påverkar det resultaten?" +> - "Hur hanterar jag situationer där inga relevanta dokument hittas?" ### Svarsgenerering [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -De mest relevanta textstyckena samlas ihop till en strukturerad prompt som inkluderar tydliga instruktioner, den hämtade kontexten och användarens fråga. Modellen läser dessa specifika delar och svarar baserat på den informationen — den kan bara använda det som finns framför sig, vilket förhindrar hallucination. +De mest relevanta delarna sätts ihop till en strukturerad prompt som inkluderar explicita instruktioner, den hämtade kontexten och användarens fråga. Modellen läser just dessa specifika delar och svarar baserat på den informationen — den kan bara använda det som finns framför sig, vilket förhindrar hallucination. ```java String context = matches.stream() @@ -237,21 +236,21 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Diagrammet nedan visar denna sammansättning i praktiken — de textstycken med högst poäng från söksteget injiceras i promptmallen, och `OpenAiOfficialChatModel` genererar ett grundat svar: +Diagrammet nedan visar denna sammanställning i praktiken — de högst rankade delarna från söksteget injiceras i promptmallen, och `OpenAiOfficialChatModel` genererar ett grundat svar: Context Assembly -*Detta diagram visar hur textstycken med högst poäng sätts ihop till en strukturerad prompt, vilket tillåter modellen att generera ett grundat svar från dina data.* +*Det här diagrammet visar hur topprankade delar sätts ihop till en strukturerad prompt, vilket gör det möjligt för modellen att generera ett grundat svar från din data.* ## Kör applikationen -**Verifiera driftsättning:** +**Verifiera distribution:** -Se till att filen `.env` finns i rotkatalogen med Azure-uppgifter (skapad under Modul 01). Kör detta från modulkatalogen (`03-rag/`): +Se till att `.env`-filen finns i rotmappen med Azure-referenser (skapade under Modul 01). Kör detta från modulkatalogen (`03-rag/`): **Bash:** ```bash -cat ../.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Ska visa AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -261,25 +260,25 @@ Get-Content ..\.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT **Starta applikationen:** -> **Notera:** Om du redan har startat alla applikationer med `./start-all.sh` från rotkatalogen (enligt Modul 01) kör denna modul redan på port 8081. Du kan hoppa över startkommandona nedan och gå direkt till http://localhost:8081. +> **Notera:** Om du redan har startat alla applikationer med `./start-all.sh` från rotmappen (som beskrivet i Modul 01) körs den här modulen redan på port 8081. Du kan hoppa över startkommandona nedan och gå direkt till http://localhost:8081. -**Alternativ 1: Använda Spring Boot Dashboard (Rekommenderas för VS Code-användare)** +**Alternativ 1: Använd Spring Boot Dashboard (Rekommenderas för VS Code-användare)** -Dev-containern innehåller Spring Boot Dashboard-tillägget, som ger ett visuellt gränssnitt för att hantera alla Spring Boot-applikationer. Du hittar det i aktivitetsfältet på vänster sida i VS Code (leta efter Spring Boot-ikonen). +Devcontainern inkluderar Spring Boot Dashboard-tillägget, som erbjuder ett visuellt gränssnitt för att hantera alla Spring Boot-applikationer. Du hittar det i Aktivitetsfältet på vänstra sidan i VS Code (letar efter Spring Boot-ikonen). Från Spring Boot Dashboard kan du: - Se alla tillgängliga Spring Boot-applikationer i arbetsytan -- Starta/stoppa applikationer med ett klick +- Starta/stoppa applikationer med ett enda klick - Visa applikationsloggar i realtid - Övervaka applikationsstatus -Klicka bara på play-knappen bredvid "rag" för att starta denna modul, eller starta alla moduler på en gång. +Klicka bara på play-knappen bredvid "rag" för att starta den här modulen, eller starta alla moduler samtidigt. Spring Boot Dashboard -*Denna skärmdump visar Spring Boot Dashboard i VS Code där du visuellt kan starta, stoppa och övervaka applikationer.* +*Den här skärmbilden visar Spring Boot Dashboard i VS Code, där du visuellt kan starta, stoppa och övervaka applikationer.* -**Alternativ 2: Använda shell-skript** +**Alternativ 2: Använda shellskript** Starta alla webbapplikationer (moduler 01-04): @@ -295,7 +294,7 @@ cd .. # Från rotkatalogen .\start-all.ps1 ``` -Eller starta bara denna modul: +Eller starta bara den här modulen: **Bash:** ```bash @@ -309,16 +308,16 @@ cd 03-rag .\start.ps1 ``` -Båda skripten laddar automatiskt miljövariabler från rotens `.env`-fil och bygger JAR-filerna om de inte finns. +Båda skripten laddar automatiskt miljövariabler från den överordnade `.env`-filen och kommer att bygga JAR-filerna om de inte redan finns. -> **Notera:** Om du föredrar att bygga alla moduler manuellt innan start: +> **Notera:** Om du föredrar att manuellt bygga alla moduler innan du startar: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -343,95 +342,95 @@ cd .. && ./stop-all.sh # Alla moduler cd ..; .\stop-all.ps1 # Alla moduler ``` -## Använda Applikationen +## Använda applikationen -Applikationen erbjuder ett webbgränssnitt för dokumentuppladdning och frågeställning. +Applikationen tillhandahåller ett webbgränssnitt för dokumentuppladdning och frågeställning. RAG Application Interface -*Denna skärmdump visar RAG-applikationens gränssnitt där du laddar upp dokument och ställer frågor.* +*Den här skärmbilden visar RAG-applikationens gränssnitt där du laddar upp dokument och ställer frågor.* ### Ladda upp ett dokument -Börja med att ladda upp ett dokument - TXT-filer fungerar bäst för testning. En `sample-document.txt` medföljer i denna katalog och innehåller information om LangChain4j-funktioner, RAG-implementering och bästa praxis - perfekt för att testa systemet. +Börja med att ladda upp ett dokument - TXT-filer fungerar bäst för testning. En `sample-document.txt` finns i denna katalog som innehåller information om LangChain4j-funktioner, RAG-implementation och bästa praxis - perfekt för att testa systemet. -Systemet bearbetar ditt dokument, delar upp det i mindre delar och skapar inbäddningar för varje del. Detta sker automatiskt när du laddar upp. +Systemet bearbetar ditt dokument, delar upp det i delar och skapar inbäddningar för varje del. Detta sker automatiskt när du laddar upp. ### Ställ frågor -Ställ nu specifika frågor om dokumentets innehåll. Prova något faktabaserat som tydligt anges i dokumentet. Systemet söker efter relevanta delar, inkluderar dem i prompten och genererar ett svar. +Ställ nu specifika frågor om dokumentinnehållet. Prova något faktabaserat som tydligt anges i dokumentet. Systemet söker efter relevanta delar, inkluderar dem i prompten och genererar ett svar. ### Kontrollera källreferenser -Observera att varje svar inkluderar källreferenser med likhetspoäng. Dessa poäng (0 till 1) visar hur relevanta varje del var i förhållande till din fråga. Högre poäng innebär bättre träffar. Detta låter dig verifiera svaret mot källmaterialet. +Observera att varje svar inkluderar källreferenser med likhetspoäng. Dessa poäng (0 till 1) visar hur relevanta varje del var för din fråga. Högre poäng betyder bättre matchningar. Detta låter dig verifiera svaret mot källmaterialet. RAG Query Results -*Denna skärmdump visar frågeresultat med det genererade svaret, källreferenser och relevanspoäng för varje hämtat textstycke.* +*Den här skärmbilden visar frågeresultat med det genererade svaret, källreferenser och relevanspoäng för varje hämtad del.* ### Experimentera med frågor Prova olika typer av frågor: -- Specifika fakta: "Vad är huvudsakliga ämnet?" +- Specifika fakta: "Vad är huvudämnet?" - Jämförelser: "Vad är skillnaden mellan X och Y?" - Sammanfattningar: "Sammanfatta huvudpunkterna om Z" -Se hur relevanspoängen ändras beroende på hur väl din fråga matchar dokumentinnehållet. +Se hur relevanspoängen förändras beroende på hur väl din fråga matchar dokumentinnehållet. -## Nyckelkoncept +## Nyckelbegrepp -### Delningsstrategi +### Uppdelningsstrategi -Dokument delas upp i 300-token-stycken med 30 tokens överlappning. Denna balans säkerställer att varje stycke har tillräcklig kontext för att vara meningsfullt samtidigt som det är tillräckligt litet för att kunna inkluderas flera stycken i en prompt. +Dokument delas upp i 300-token delar med 30 tokens överlappning. Denna balans säkerställer att varje del har tillräcklig kontext för att vara meningsfull samtidigt som den är tillräckligt liten för att inkludera flera delar i en prompt. ### Likhetspoäng -Varje hittat stycke kommer med en likhetspoäng mellan 0 och 1 som indikerar hur nära det matchar användarens fråga. Diagrammet nedan visualiserar poängintervallen och hur systemet använder dem för att filtrera resultat: +Varje hämtad del kommer med en likhetspoäng mellan 0 och 1 som indikerar hur nära den matchar användarens fråga. Diagrammet nedan visualiserar poängintervallen och hur systemet använder dem för att filtrera resultat: Similarity Scores -*Detta diagram visar poängintervall från 0 till 1, med en minimigräns på 0,5 som filtrerar bort irrelevanta stycken.* +*Det här diagrammet visar poängintervall från 0 till 1, med en miniminivå på 0,5 som filtrerar bort irrelevanta delar.* -Poängen spänner från 0 till 1: +Poängen varierar mellan 0 och 1: - 0,7-1,0: Mycket relevant, exakt träff - 0,5-0,7: Relevant, bra kontext -- Under 0,5: Filtrerat bort, för olik +- Under 0,5: Filtreras bort, för olik -Systemet hämtar endast stycken över minimigränsen för att säkerställa kvalitet. +Systemet hämtar endast delar över minimitröskeln för att säkerställa kvalitet. -Inbäddningar fungerar bra när betydelser grupperas tydligt, men de har blinda fläckar. Diagrammet nedan visar vanliga fel — för stora stycken skapar otydliga vektorer, för små stycken saknar kontext, tvetydiga termer pekar på flera kluster, och sökningar på exakt träff (ID:n, artikelnummer) fungerar inte alls med inbäddningar: +Inbäddningar fungerar bra när betydelser klustras tydligt, men de har svagheter. Diagrammet nedan visar vanliga felorsaker — delar som är för stora ger otydliga vektorer, delar som är för små saknar kontext, tvetydiga termer pekar på flera kluster, och exaktmatchningar (ID, artikelnummer) fungerar inte alls med inbäddningar: Embedding Failure Modes -*Detta diagram visar vanliga felriktningar vid inbäddning: för stora stycken, för små stycken, tvetydiga termer som pekar på flera kluster, och sökningar på exakt träff som ID:n.* +*Det här diagrammet visar vanliga felorsaker vid inbäddningar: delar som är för stora, delar som är för små, tvetydiga termer som pekar på flera kluster samt exaktmatchningar som ID.* -### In-Memory Lagring +### Minneslagring -Denna modul använder in-memory lagring för enkelhetens skull. När du startar om applikationen går uppladdade dokument förlorade. Produktionssystem använder persistenta vektordatabaser som Qdrant eller Azure AI Search. +Den här modulen använder minneslagring för enkelhetens skull. När du startar om applikationen förloras uppladdade dokument. Produktionssystem använder persistenta vektordatabaser som Qdrant eller Azure AI Search. ### Hantering av kontextfönster -Varje modell har ett maximal kontextfönster. Du kan inte inkludera alla stycken från ett stort dokument. Systemet hämtar de topp N mest relevanta stycken (standard 5) för att hålla sig inom gränser samtidigt som tillräcklig kontext ges för exakta svar. +Varje modell har ett maximalt kontextfönster. Du kan inte inkludera alla delar från ett stort dokument. Systemet hämtar de topp N mest relevanta delarna (standard 5) för att hålla sig inom gränser samtidigt som tillräcklig kontext för exakta svar ges. ## När RAG är viktigt -RAG är inte alltid rätt angreppssätt. Beslutsguiden nedan hjälper dig avgöra när RAG tillför värde jämfört med när enklare metoder — som att inkludera innehåll direkt i prompten eller lita på modellens inbyggda kunskap — är tillräckliga: +RAG är inte alltid rätt tillvägagångssätt. Beslutsguiden nedan hjälper dig avgöra när RAG tillför värde jämfört med när enklare tillvägagångssätt — som att inkludera innehåll direkt i prompten eller förlita sig på modellens inbyggda kunskap — räcker: When to Use RAG -*Detta diagram visar en beslutsguide för när RAG tillför värde jämfört med när enklare metoder är tillräckliga.* +*Det här diagrammet visar en beslutsguide för när RAG tillför värde jämfört med när enklare metoder är tillräckliga.* ## Nästa steg -**Nästa modul:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Nästa modul:** [04-tools - AI-agenter med verktyg](../04-tools/README.md) --- -**Navigering:** [← Föregående: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Tillbaka till huvud](../README.md) | [Nästa: Modul 04 - Tools →](../04-tools/README.md) +**Navigering:** [← Föregående: Modul 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Tillbaka till start](../README.md) | [Nästa: Modul 04 - Verktyg →](../04-tools/README.md) --- **Ansvarsfriskrivning**: -Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, vänligen nota att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess ursprungliga språk bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning. +Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning. \ No newline at end of file diff --git a/translations/sv/04-tools/README.md b/translations/sv/04-tools/README.md index a7950ab79..5d0a5e3dd 100644 --- a/translations/sv/04-tools/README.md +++ b/translations/sv/04-tools/README.md @@ -1,33 +1,33 @@ -# Modul 04: AI-Agenter med Verktyg +# Modul 04: AI-agenter med verktyg ## Innehållsförteckning -- [Videogenomgång](../../../04-tools) -- [Det du kommer att lära dig](../../../04-tools) -- [Förkunskaper](../../../04-tools) -- [Att förstå AI-agenter med verktyg](../../../04-tools) -- [Hur verktygsanrop fungerar](../../../04-tools) - - [Verktygsdefinitioner](../../../04-tools) - - [Beslutsfattande](../../../04-tools) - - [Utförande](../../../04-tools) - - [Generering av svar](../../../04-tools) - - [Arkitektur: Spring Boot Auto-Wiring](../../../04-tools) -- [Verktygskedjning](../../../04-tools) -- [Kör applikationen](../../../04-tools) -- [Använda applikationen](../../../04-tools) - - [Prova enkel verktygsanvändning](../../../04-tools) - - [Testa verktygskedjning](../../../04-tools) - - [Se konversationsflöde](../../../04-tools) - - [Experimentera med olika förfrågningar](../../../04-tools) -- [Nyckelbegrepp](../../../04-tools) - - [ReAct-mönstret (Reasoning and Acting)](../../../04-tools) - - [Verktygsbeskrivningar är viktiga](../../../04-tools) - - [Sessionshantering](../../../04-tools) - - [Felhanteirng](../../../04-tools) -- [Tillgängliga verktyg](../../../04-tools) -- [När man ska använda verktygsbaserade agenter](../../../04-tools) -- [Verktyg vs RAG](../../../04-tools) -- [Nästa steg](../../../04-tools) +- [Videogenomgång](#videogenomgång) +- [Vad du kommer lära dig](#vad-du-kommer-lära-dig) +- [Förkunskaper](#förkunskaper) +- [Att förstå AI-agenter med verktyg](#att-förstå-ai-agenter-med-verktyg) +- [Hur verktygsanrop fungerar](#hur-verktygsanrop-fungerar) + - [Verktygsdefinitioner](#verktygsdefinitioner) + - [Beslutsfattande](#beslutsfattande) + - [Utförande](#utförande) + - [Generering av svar](#generering-av-svar) + - [Arkitektur: Spring Boot Auto-Wiring](#arkitektur-spring-boot-auto-wiring) +- [Verktygskedjning](#verktygskedjning) +- [Kör applikationen](#kör-applikationen) +- [Använda applikationen](#använda-applikationen) + - [Testa enkel verktygsanvändning](#prova-enkel-verktygsanvändning) + - [Testa verktygskedjning](#testa-verktygskedjning) + - [Se samtalets flöde](#se-konversationsflödet) + - [Experimentera med olika förfrågningar](#experimentera-med-olika-förfrågningar) +- [Nyckelkoncept](#viktiga-begrepp) + - [ReAct-mönstret (Resonerande och Agirande)](#react-mönstret-resonemang-och-handling) + - [Verktygsbeskrivningar är viktiga](#verktygsbeskrivningar-är-viktiga) + - [Sessionshantering](#sessionshantering) + - [Felfångst](#felhantering) +- [Tillgängliga verktyg](#tillgängliga-verktyg) +- [När man ska använda verktygsbaserade agenter](#när-man-ska-använda-verktygsbaserade-agenter) +- [Verktyg vs RAG](#verktyg-vs-rag) +- [Nästa steg](#nästa-steg) ## Videogenomgång @@ -35,42 +35,42 @@ Titta på denna livesession som förklarar hur du kommer igång med denna modul: AI Agents with Tools and MCP - Live Session -## Det du kommer att lära dig +## Vad du kommer lära dig -Hittills har du lärt dig hur man har samtal med AI, strukturerar prompts effektivt och förankrar svar i dina dokument. Men det finns fortfarande en grundläggande begränsning: språkmodeller kan bara generera text. De kan inte kolla vädret, utföra beräkningar, fråga databaser eller interagera med externa system. +Hittills har du lärt dig hur man för samtal med AI, strukturerar promptar effektivt och förankrar svar i dina dokument. Men det finns fortfarande en grundläggande begränsning: språkmodeller kan bara generera text. De kan inte kolla vädret, göra beräkningar, fråga databaser eller interagera med externa system. -Verktyg förändrar detta. Genom att ge modellen tillgång till funktioner som den kan anropa förvandlas den från en textgenerator till en agent som kan vidta åtgärder. Modellen bestämmer när den behöver ett verktyg, vilket verktyg som ska användas och vilka parametrar som ska skickas. Din kod kör funktionen och returnerar resultatet. Modellen inkorporerar sedan detta resultat i sitt svar. +Verktyg förändrar detta. Genom att ge modellen åtkomst till funktioner den kan anropa förvandlar du den från en textgenerator till en agent som kan utföra handlingar. Modellen bestämmer när den behöver ett verktyg, vilket verktyg den ska använda och vilka parametrar som ska skickas med. Din kod utför funktionen och returnerar resultatet. Modellen inkorporerar sedan detta resultat i sitt svar. ## Förkunskaper -- Genomförd [Modul 01 - Introduktion](../01-introduction/README.md) (Azure OpenAI-resurser distribuerade) -- Tidigare moduler rekommenderas (denna modul refererar till [RAG-koncept från Modul 03](../03-rag/README.md) i jämförelsen Verktyg vs RAG) -- `.env`-fil i rotkatalogen med Azure-uppgifter (skapad av `azd up` i Modul 01) +- Genomförd [Modul 01 - Introduktion](../01-introduction/README.md) (Azure OpenAI-resurser deployerade) +- Tidigare moduler rekommenderas (denna modul refererar till [RAG-koncept från Modul 03](../03-rag/README.md) i jämförelsen mellan Verktyg och RAG) +- `.env`-fil i rotmappen med Azure-referenser (skapad av `azd up` i Modul 01) -> **Notera:** Om du inte har genomfört Modul 01, följ deploymentsinstruktionerna där först. +> **Notera:** Om du inte har genomfört Modul 01, följ först deploymentsinstruktionerna där. ## Att förstå AI-agenter med verktyg -> **📝 Notera:** Termen "agenter" i denna modul syftar på AI-assistenter förbättrade med verktygsanropsfunktioner. Detta skiljer sig från **Agentic AI**-mönster (autonoma agenter med planering, minne och flerstegsresonerande) som vi kommer att täcka i [Modul 05: MCP](../05-mcp/README.md). +> **📝 Notera:** Termen "agenter" i denna modul syftar på AI-assistenter med förmåga att anropa verktyg. Detta skiljer sig från **Agentic AI**-mönstren (autonoma agenter med planering, minne och flerstegsresonemang) som vi behandlar i [Modul 05: MCP](../05-mcp/README.md). -Utan verktyg kan en språkmodell bara generera text från sin träningsdata. Fråga den om det aktuella vädret, och den måste gissa. Ge den verktyg, så kan den anropa ett väder-API, utföra beräkningar eller fråga en databas — och sedan väva in dessa verkliga resultat i sitt svar. +Utan verktyg kan en språkmodell bara generera text baserat på sin träningsdata. Fråga den om vädret idag och den måste gissa. Ge den verktyg, och den kan anropa ett väder-API, göra beräkningar eller fråga en databas — och sedan väva in dessa verkliga resultat i sitt svar. Without Tools vs With Tools *Utan verktyg kan modellen bara gissa — med verktyg kan den anropa API:er, göra beräkningar och returnera realtidsdata.* -En AI-agent med verktyg följer ett **Reasoning and Acting (ReAct)**-mönster. Modellen svarar inte bara — den tänker på vad den behöver, agerar genom att anropa ett verktyg, observerar resultatet och avgör sedan om den ska agera igen eller leverera det slutgiltiga svaret: +En AI-agent med verktyg följer ett **Reasoning and Acting (ReAct)**-mönster. Modellen svarar inte bara — den tänker på vad den behöver, agerar genom att anropa ett verktyg, observerar resultatet och beslutar sedan om den ska agera igen eller ge slutgiltigt svar: -1. **Reason** — Agenten analyserar användarens fråga och bestämmer vilken information den behöver -2. **Act** — Agenten väljer rätt verktyg, genererar korrekta parametrar och anropar det -3. **Observe** — Agenten tar emot verktygets output och utvärderar resultatet -4. **Repeat or Respond** — Om mer data behövs, loopar agenten tillbaka; annars formulerar den ett svar i naturligt språk +1. **Resonera** — Agenten analyserar användarens fråga och avgör vilken information den behöver +2. **Agera** — Agenten väljer rätt verktyg, genererar korrekta parametrar och anropar det +3. **Observera** — Agenten tar emot verktygets output och utvärderar resultatet +4. **Upprepa eller svara** — Om mer data behövs loopar agenten tillbaka; annars formulerar den ett naturligt svar ReAct Pattern -*ReAct-cykeln — agenten resonerar om vad den ska göra, agerar genom att anropa ett verktyg, observerar resultatet, och loopar tills den kan leverera ett slutgiltigt svar.* +*ReAct-cykeln — agenten resonerar om vad som ska göras, agerar genom att anropa ett verktyg, observerar resultatet och loopar tills slutgiltigt svar kan levereras.* -Detta sker automatiskt. Du definierar verktygen och deras beskrivningar. Modellen tar hand om beslutsfattandet om när och hur de ska användas. +Detta sker automatiskt. Du definierar verktygen och deras beskrivningar. Modellen hanterar beslutsfattandet om när och hur de ska användas. ## Hur verktygsanrop fungerar @@ -78,7 +78,7 @@ Detta sker automatiskt. Du definierar verktygen och deras beskrivningar. Modelle [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Du definierar funktioner med klara beskrivningar och paramspecifikationer. Modellen ser dessa beskrivningar i sitt systemprompt och förstår vad varje verktyg gör. +Du definierar funktioner med tydliga beskrivningar och parameter-specifikationer. Modellen ser dessa beskrivningar i sitt systemprompt och förstår vad varje verktyg gör. ```java @Component @@ -101,130 +101,130 @@ public interface Assistant { // - Alla @Tool-metoder från @Component-klasser // - ChatMemoryProvider för sessionshantering ``` - -Diagrammet nedan bryter ner varje annotation och visar hur varje del hjälper AI att förstå när verktyget ska anropas och vilka argument som ska skickas: + +Diagrammet nedan bryter ner varje annotation och visar hur varje del hjälper AI:n att förstå när verktyget ska anropas och vilka argument som ska skickas: Anatomy of Tool Definitions -*Anatomin av en verktygsdefinition — @Tool berättar för AI när det ska användas, @P beskriver varje parameter, och @AiService kopplar ihop allt vid uppstart.* +*Anatomi för en verktygsdefinition — @Tool talar om för AI:n när det ska användas, @P beskriver varje parameter och @AiService kopplar ihop allt vid start.* -> **🤖 Prova med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) och fråga: -> - "Hur skulle jag integrera ett riktigt väder-API som OpenWeatherMap istället för mock-data?" -> - "Vad gör en bra verktygsbeskrivning som hjälper AI att använda det korrekt?" -> - "Hur hanterar jag API-fel och rate limits i verktygsimplementationer?" +> **🤖 Testa med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) och fråga: +> - "Hur skulle jag integrera ett riktigt väder-API som OpenWeatherMap istället för mockdata?" +> - "Vad gör en bra verktygsbeskrivning som hjälper AI:n att använda det korrekt?" +> - "Hur hanterar jag API-fel och rate limits i verktygsimplementeringar?" ### Beslutsfattande -När en användare frågar "Hur är vädret i Seattle?" väljer modellen inte verktyg slumpmässigt. Den jämför användarens intention med varje verktygsbeskrivning den har tillgång till, poängsätter varje för relevans och väljer bästa match. Den genererar sedan ett strukturerat funktionsanrop med rätt parametrar – i detta fall sätter den `location` till `"Seattle"`. +När en användare frågar "Hur är vädret i Seattle?" väljer inte modellen verktyg slumpmässigt. Den jämför användarens avsikt mot varje verktygsbeskrivning den har tillgång till, ger varje en poäng för relevans och väljer sedan den bästa matchen. Därefter genererar den ett strukturerat funktionsanrop med rätt parametrar — i detta fall sätter den `location` till `"Seattle"`. Om inget verktyg matchar användarens förfrågan faller modellen tillbaka på att svara från sin egen kunskap. Om flera verktyg matchar väljer den det mest specifika. How the AI Decides Which Tool to Use -*Modellen utvärderar varje tillgängligt verktyg mot användarens intention och väljer bästa match – därför är det viktigt att skriva tydliga, specifika verktygsbeskrivningar.* +*Modellen utvärderar varje tillgängligt verktyg mot användarens avsikt och väljer bästa match — därför är det viktigt att skriva tydliga, specifika verktygsbeskrivningar.* ### Utförande [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot auto-wires den deklarativa `@AiService`-interfacet med alla registrerade verktyg, och LangChain4j exekverar verktygsanrop automatiskt. Bakom kulisserna flyter ett komplett verktygsanrop genom sex steg – från användarens fråga i naturligt språk hela vägen tillbaka till ett svar i naturligt språk: +Spring Boot auto-wirar det deklarativa `@AiService`-gränssnittet med alla registrerade verktyg, och LangChain4j kör verktygsanrop automatiskt. Bakom kulisserna flödar ett fullständigt verktygsanrop genom sex steg — från användarens naturliga språkfråga ända tillbaka till ett naturligt språk-svar: Tool Calling Flow -*Slutet-till-slut-flöde – användaren ställer en fråga, modellen väljer ett verktyg, LangChain4j exekverar det, och modellen väver in resultatet i ett naturligt svar.* +*Slut-till-slut-flöde — användaren ställer en fråga, modellen väljer ett verktyg, LangChain4j utför det, och modellen väver in resultatet i ett naturligt svar.* -Om du körde [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) i Modul 00 har du redan sett detta mönster i action – `Calculator`-verktygen anropades på samma sätt. Sekvensdiagrammet nedan visar exakt vad som hände under huven under den demonstrationen: +Bakom kulisserna kör `AiServices` samma verktygsanrops-loop för vilket verktyg som helst — här illustrerat med en enkel `Calculator`. Sekvensdiagrammet nedan visar exakt vad som händer under huven: Tool Calling Sequence Diagram -*Verktygsanropsloopen från Quick Start-demonstrationen – `AiServices` skickar ditt meddelande och verktygsscheman till LLM, LLM svarar med ett funktionsanrop som `add(42, 58)`, LangChain4j exekverar `Calculator`-metoden lokalt och matar sedan tillbaka resultatet för slutgiltigt svar.* +*Verktygsanrops-loopen — `AiServices` skickar ditt meddelande och verktygsscheman till LLM:n, LLM:n svarar med ett funktionsanrop som `add(42, 58)`, LangChain4j kör `Calculator`-metoden lokalt och skickar tillbaka resultatet för slutgiltigt svar.* -> **🤖 Prova med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) och fråga: +> **🤖 Testa med [GitHub Copilot](https://github.com/features/copilot) Chat:** Öppna [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) och fråga: > - "Hur fungerar ReAct-mönstret och varför är det effektivt för AI-agenter?" -> - "Hur bestämmer agenten vilket verktyg som ska användas och i vilken ordning?" -> - "Vad händer om ett verktygsanrop misslyckas – hur ska jag hantera fel robust?" +> - "Hur avgör agenten vilket verktyg som ska användas och i vilken ordning?" +> - "Vad händer om ett verktygsutförande misslyckas — hur hanterar jag fel robust?" ### Generering av svar -Modellen tar emot väderdata och formaterar det till ett svar i naturligt språk till användaren. +Modellen tar emot väderdata och formaterar det till ett naturligt språk-svar till användaren. ### Arkitektur: Spring Boot Auto-Wiring -Denna modul använder LangChain4js Spring Boot-integration med deklarativa `@AiService`-interface. Vid uppstart upptäcker Spring Boot varje `@Component` som innehåller `@Tool`-metoder, din `ChatModel` bean och `ChatMemoryProvider` — och kopplar ihop allt till ett enda `Assistant`-interface utan behov av boilerplate. +Denna modul använder LangChain4j:s Spring Boot-integration med deklarativa `@AiService`-gränssnitt. Vid start upptäcker Spring Boot varje `@Component` som innehåller `@Tool`-metoder, din `ChatModel`-bean och `ChatMemoryProvider` — och kopplar sedan ihop dem till ett enda `Assistant`-gränssnitt utan boilerplate. Spring Boot Auto-Wiring Architecture -*@AiService-interfacet knyter ihop ChatModel, verktygskomponenter och minnesleverantör – Spring Boot sköter all koppling automatiskt.* +*@AiService-gränssnittet knyter ihop ChatModel, verktygskomponenter och minnesprovider — Spring Boot hanterar all koppling automatiskt.* -Här är hela förfrågningslivscykeln som ett sekvensdiagram – från HTTP-förfrågan genom controller, service och auto-wired proxy, hela vägen till verktygsutförandet och tillbaka: +Här är hela förfrågningslivscykeln som sekvensdiagram — från HTTP-förfrågan via controller, service och auto-wired proxy, hela vägen till verktygsutförandet och tillbaka: Spring Boot Tool Calling Sequence -*Den kompletta Spring Boot-förfrågningslivscykeln – HTTP-förfrågan går genom controller och service till den auto-wirade Assistant-proxyn, som orchestrerar LLM och verktygsanrop automatiskt.* +*Den kompletta Spring Boot-förfrågningslivscykeln — HTTP-förfrågan flödar genom controller och service till den auto-wirade Assistant-proxyn, som orkestrerar LLM och verktygsanrop automatiskt.* -Viktiga fördelar med detta tillvägagångssätt: +Viktiga fördelar med denna metod: - **Spring Boot auto-wiring** — ChatModel och verktyg injiceras automatiskt - **@MemoryId-mönstret** — Automatisk sessionsbaserad minneshantering -- **Enda instans** — Assistant skapas en gång och återanvänds för bättre prestanda -- **Typsäker exekvering** — Java-metoder anropas direkt med typkonvertering -- **Multi-turn orchestration** — Hanterar verktygskedjning automatiskt -- **Ingen boilerplate** — Inga manuella `AiServices.builder()`-anrop eller minnes-HashMap +- **Enkel instans** — Assistant skapas en gång och återanvänds för bättre prestanda +- **Typ-säker exekvering** — Java-metoder anropas direkt med typkonvertering +- **Multi-turn orkestrering** — Hanterar verktygskedjning automatiskt +- **Inga boilerplate** — Inga manuella `AiServices.builder()`-anrop eller minnes-HashMap -Alternativa tillvägagångssätt (manuella `AiServices.builder()`) kräver mer kod och saknar Spring Boot-integrationsfördelarna. +Alternativa angreppssätt (manuell `AiServices.builder()`) kräver mer kod och saknar Spring Boot-integrationsfördelarna. ## Verktygskedjning -**Verktygskedjning** – Den verkliga kraften med verktygsbaserade agenter syns när en enda fråga kräver flera verktyg. Fråga "Hur är vädret i Seattle i Fahrenheit?" och agenten kedjar automatiskt två verktyg: först anropar den `getCurrentWeather` för att hämta temperaturen i Celsius, sedan skickar den det värdet till `celsiusToFahrenheit` för konvertering – allt i en enda samtalsrunda. +**Verktygskedjning** — Den verkliga kraften i verktygsbaserade agenter visar sig när en enda fråga kräver flera verktyg. Fråga "Hur är vädret i Seattle i Fahrenheit?" och agenten kedjar automatiskt ihop två verktyg: först anropas `getCurrentWeather` för att få temperaturen i Celsius, sedan skickas det värdet till `celsiusToFahrenheit` för omvandling — allt i ett enda samtalsvarv. Tool Chaining Example -*Verktygskedjning i praktiken – agenten anropar först getCurrentWeather, sedan skickar Celsius-resultatet till celsiusToFahrenheit och levererar ett sammansatt svar.* +*Verktygskedjning i praktiken — agenten anropar först getCurrentWeather, skickar sedan Celsius-resultatet vidare till celsiusToFahrenheit och levererar ett sammansatt svar.* -**Felfria hanteringar** – Fråga efter vädret i en stad som inte finns i mock-datan. Verktyget returnerar ett felmeddelande, och AI förklarar att den inte kan hjälpa istället för att krascha. Verktyg misslyckas säkert. Diagrammet nedan jämför de två tillvägagångssätten – med korrekt felhantering fångar agenten undantaget och svarar hjälpsamt, utan det kraschar hela applikationen: +**Felfall hanteras smidigt** — Fråga om vädret i en stad som inte finns i mockdata. Verktyget returnerar ett felmeddelande och AI förklarar att det inte kan hjälpa till i stället för att krascha. Verktyg misslyckas säkert. Diagrammet nedan visar kontrasten mellan metoderna — med korrekt felhantering fångar agenten undantaget och svarar hjälpsamt, medan utan hantering kraschar hela applikationen: Error Handling Flow *När ett verktyg misslyckas fångar agenten felet och svarar med en hjälpsam förklaring istället för att krascha.* -Detta sker i en enda samtalsrunda. Agenten orchestrerar flera verktygsanrop autonomt. +Detta sker i ett enda samtalsvarv. Agenten orkestrerar flera verktygsanrop autonomt. ## Kör applikationen -**Verifiera distribution:** +**Verifiera deployment:** -Säkerställ att `.env`-filen finns i rotkatalogen med Azure-uppgifter (skapad under Modul 01). Kör detta från modulkatalogen (`04-tools/`): +Säkerställ att `.env`-filen finns i rotmappen med Azure-referenser (skapad under Modul 01). Kör detta från modulkatalogen (`04-tools/`): -**Bash:** +**Bash:** ```bash cat ../.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Bör visa AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **Starta applikationen:** -> **Notera:** Om du redan startade alla applikationer med `./start-all.sh` från rotkatalogen (som beskrivs i Modul 01) körs denna modul redan på port 8084. Du kan hoppa över startkommandona nedan och gå direkt till http://localhost:8084. +> **Notera:** Om du redan startat alla applikationer med `./start-all.sh` från rotmappen (som beskrivs i Modul 01) kör denna modul redan på port 8084. Du kan hoppa över startkommandona nedan och gå direkt till http://localhost:8084. + +**Alternativ 1: Använd Spring Boot Dashboard (Rekommenderas för VS Code-användare)** -**Alternativ 1: Använd Spring Boot Dashboard (Rekommenderat för VS Code-användare)** +Dev-containern inkluderar Spring Boot Dashboard-tillägget, som ger ett visuellt gränssnitt för att hantera alla Spring Boot-applikationer. Du hittar det i aktivitetsfältet till vänster i VS Code (leta efter Spring Boot-ikonen). -Dev-container inkluderar Spring Boot Dashboard-tillägget, som ger ett visuellt gränssnitt för att hantera alla Spring Boot-applikationer. Du hittar det i Aktivitetsfältet till vänster i VS Code (leta efter Spring Boot-ikonen). +Från Spring Boot Dashboard kan du: +- Se alla tillgängliga Spring Boot-applikationer i arbetsytan +- Starta/stoppa applikationer med ett klick +- Visa applikationsloggar i realtid +- Övervaka applikationsstatus -Från Spring Boot Dashboard kan du: -- Se alla tillgängliga Spring Boot-applikationer i arbetsytan -- Starta/stopp applikationer med ett klick -- Visa applikationsloggar i realtid -- Övervaka applikationsstatus Klicka helt enkelt på play-knappen bredvid "tools" för att starta denna modul, eller starta alla moduler samtidigt. Så här ser Spring Boot Dashboard ut i VS Code: - Spring Boot Dashboard -*Spring Boot Dashboard i VS Code — starta, stoppa och övervaka alla moduler från en plats* +*Spring Boot-instrumentpanelen i VS Code — starta, stoppa och övervaka alla moduler från en och samma plats* **Alternativ 2: Använda shell-skript** @@ -258,7 +258,7 @@ cd 04-tools Båda skripten laddar automatiskt miljövariabler från rotens `.env`-fil och bygger JAR-filerna om de inte finns. -> **Notera:** Om du föredrar att bygga alla moduler manuellt innan start: +> **Obs:** Om du föredrar att bygga alla moduler manuellt innan start: > > **Bash:** > ```bash @@ -292,70 +292,70 @@ cd ..; .\stop-all.ps1 # Alla moduler ## Använda Applikationen -Applikationen tillhandahåller ett webbgränssnitt där du kan interagera med en AI-agent som har tillgång till väder- och temperaturkonverteringsverktyg. Så här ser gränssnittet ut — det inkluderar snabbstartsexempel och en chattpanel för att skicka förfrågningar: +Applikationen erbjuder ett webbgränssnitt där du kan interagera med en AI-agent som har tillgång till väder- och temperaturkonverteringsverktyg. Så här ser gränssnittet ut — det inkluderar snabbstarts-exempel och en chattpanel för att skicka förfrågningar: AI Agent Tools Interface -*AI Agent Tools-gränssnittet - snabba exempel och chattgränssnitt för att interagera med verktyg* +*AI Agent Tools-gränssnittet – snabbe exempel och chattgränssnitt för interaktion med verktyg* ### Prova Enkel Verktygsanvändning -Börja med en enkel förfrågan: "Konvertera 100 grader Fahrenheit till Celsius". Agenten förstår att den behöver temperaturskonverteringsverktyget, anropar det med rätt parametrar och returnerar resultatet. Notera hur naturligt detta känns – du specificerade inte vilket verktyg som skulle användas eller hur du skulle anropa det. +Börja med en enkel fråga: "Konvertera 100 grader Fahrenheit till Celsius". Agenten förstår att den behöver temperaturkonverteringsverktyget, anropar det med rätt parametrar och returnerar resultatet. Lägg märke till hur naturligt detta känns – du specificerade inte vilket verktyg som skulle användas eller hur det skulle anropas. ### Testa Verktygskedjning -Prova nu något mer komplext: "Hur är vädret i Seattle och konvertera det till Fahrenheit?" Se hur agenten arbetar steg för steg. Den hämtar först vädret (som returnerar i Celsius), inser att det behöver konvertera till Fahrenheit, anropar konverteringsverktyget och kombinerar båda resultaten i ett svar. +Prova nu något mer komplext: "Hur är vädret i Seattle och konvertera det till Fahrenheit?" Se hur agenten arbetar steg för steg. Den hämtar först vädret (som returnerar i Celsius), förstår att det behöver konverteras till Fahrenheit, anropar konverteringsverktyget och kombinerar båda resultaten till ett svar. -### Se Samtalsflödet +### Se Konversationsflödet -Chattgränssnittet sparar samtalshistorik, vilket gör att du kan ha flerstegssamtal. Du kan se alla tidigare frågor och svar, vilket gör det enkelt att följa konversationen och förstå hur agenten bygger kontext över flera utbyten. +Chattgränssnittet sparar konversationshistorik, vilket låter dig ha interaktioner över flera turer. Du kan se alla tidigare frågor och svar, vilket gör det lätt att följa konversationen och förstå hur agenten bygger kontext över flera utbyten. Conversation with Multiple Tool Calls -*Flerstegssamtal som visar enkla konverteringar, väderuppslagningar och verktygskedjning* +*Flerstegs-konversation som visar enkla konverteringar, väderuppslag och verktygskedjning* ### Experimentera med Olika Förfrågningar Testa olika kombinationer: -- Väderuppslagningar: "Hur är vädret i Tokyo?" +- Väderuppslag: "Hur är vädret i Tokyo?" - Temperaturkonverteringar: "Vad är 25°C i Kelvin?" - Kombinerade frågor: "Kolla vädret i Paris och säg om det är över 20°C" -Lägg märke till hur agenten tolkar naturligt språk och mappas till lämpliga verktygsanrop. +Lägg märke till hur agenten tolkar naturligt språk och kopplar det till lämpliga verktygsanrop. -## Nyckelkoncept +## Viktiga Begrepp ### ReAct-mönstret (Resonemang och Handling) -Agenten alternerar mellan att resonera (besluta vad som ska göras) och att agera (använda verktyg). Detta mönster möjliggör autonom problemlösning snarare än att bara svara på instruktioner. +Agenten växlar mellan att resonera (besluta vad som ska göras) och att agera (använda verktyg). Detta mönster möjliggör autonom problemlösning snarare än att bara svara på instruktioner. -### Verktygsbeskrivningar är Viktiga +### Verktygsbeskrivningar Är Viktiga -Kvaliteten på dina verktygsbeskrivningar påverkar direkt hur väl agenten använder dem. Klara, specifika beskrivningar hjälper modellen att förstå när och hur varje verktyg ska anropas. +Kvaliteten på dina verktygsbeskrivningar påverkar hur väl agenten använder dem. Klara, specifika beskrivningar hjälper modellen att förstå när och hur varje verktyg ska anropas. ### Sessionshantering -`@MemoryId`-annoteringen möjliggör automatisk sessionbaserad minneshantering. Varje sessions-ID får en egen `ChatMemory`-instans som hanteras av `ChatMemoryProvider`-bean, så att flera användare kan interagera med agenten samtidigt utan att deras samtal blandas ihop. Följande diagram visar hur flera användare dirigeras till isolerade minneslager baserat på deras session-ID: +`@MemoryId`-annoteringen möjliggör automatisk sessionsbaserad minneshantering. Varje session-ID får en egen `ChatMemory`-instans hanterad av `ChatMemoryProvider`-bean, så att flera användare kan interagera med agenten samtidigt utan att konversationerna blandas ihop. Följande diagram visar hur flera användare dirigeras till isolerade minneslagringar baserat på deras session-ID:n: Session Management with @MemoryId -*Varje session-ID mappar till en isolerad konversationshistorik — användare ser aldrig varandras meddelanden.* +*Varje session-ID kopplas till en isolerad konversationshistorik — användare ser aldrig varandras meddelanden.* -### Felsökning +### Felhantering -Verktyg kan misslyckas — API:er kan tidsbegränsas, parametrar kan vara ogiltiga, externa tjänster kan gå ner. Produktionsagenter behöver felhantering så att modellen kan förklara problem eller försöka alternativ istället för att krascha hela applikationen. När ett verktyg kastar ett undantag fångar LangChain4j det och matar tillbaka felmeddelandet till modellen, som sedan kan förklara problemet på naturligt språk. +Verktyg kan misslyckas — API:er kan timea ut, parametrar kan vara ogiltiga, externa tjänster kan sluta fungera. Produktionsagenter behöver felhantering så att modellen kan förklara problem eller försöka alternativ istället för att krascha hela applikationen. När ett verktyg kastar ett undantag fångar LangChain4j det och skickar felmeddelandet tillbaka till modellen, som sedan kan förklara problemet på naturligt språk. ## Tillgängliga Verktyg -Diagrammet nedan visar den breda verktygsekosystemet du kan bygga. Denna modul demonstrerar väder- och temperaturverktyg, men samma `@Tool`-mönster fungerar för vilken Java-metod som helst — från databasanrop till betalningshantering. +Diagrammet nedan visar den breda ekosystemet av verktyg du kan bygga. Denna modul demonstrerar väder- och temperaturverktyg, men samma `@Tool`-mönster fungerar för vilken Java-metod som helst — från databasfrågor till betalningshantering. Tool Ecosystem -*Varje Java-metod annoterad med @Tool blir tillgänglig för AI:n — mönstret sträcker sig till databaser, API:er, e-post, filoperationer och mer.* +*Vilken Java-metod som helst som annoterats med @Tool blir tillgänglig för AI:n – mönstret sträcker sig till databaser, API:er, e-post, filoperationer och mer.* -## När man Ska Använda Verktygsbaserade Agenter +## När Man Ska Använda Verktygsbaserade Agenter -Inte varje förfrågan behöver verktyg. Beslutet handlar om huruvida AI:n behöver interagera med externa system eller kan svara från sin egen kunskap. Följande guide sammanfattar när verktyg tillför värde och när de är onödiga: +Inte varje förfrågan kräver verktyg. Beslutet handlar om AI:n behöver interagera med externa system eller kan svara från sin egen kunskap. Följande guide summerar när verktyg är värdefulla och när de är onödiga: When to Use Tools @@ -363,25 +363,25 @@ Inte varje förfrågan behöver verktyg. Beslutet handlar om huruvida AI:n behö ## Verktyg vs RAG -Modulerna 03 och 04 utökar båda vad AI kan göra, men på fundamentalt olika sätt. RAG ger modellen tillgång till **kunskap** genom att hämta dokument. Verktyg ger modellen möjlighet att utföra **åtgärder** genom att anropa funktioner. Diagrammet nedan jämför dessa två tillvägagångssätt sida vid sida — från hur varje arbetsflöde fungerar till avvägningarna mellan dem: +Modulerna 03 och 04 utökar båda vad AI:n kan göra, men på fundamentalt olika sätt. RAG ger modellen tillgång till **kunskap** genom att hämta dokument. Verktyg ger modellen förmågan att utföra **åtgärder** genom att anropa funktioner. Diagrammet nedan jämför dessa två tillvägagångssätt sida vid sida — från hur varje arbetsflöde fungerar till avvägningarna mellan dem: Tools vs RAG Comparison -*RAG hämtar information från statiska dokument — Verktyg utför åtgärder och hämtar dynamisk, realtidsdata. Många produktionssystem kombinerar båda.* +*RAG hämtar information från statiska dokument — Verktyg utför åtgärder och hämtar dynamisk, realtidsdata. Många produktsystem kombinerar båda.* -I praktiken kombinerar många produktionssystem båda tillvägagångssätten: RAG för att förankra svar i din dokumentation, och Verktyg för att hämta live-data eller utföra operationer. +I praktiken kombinerar många produktsystem båda tillvägagångssätten: RAG för att förankra svar i din dokumentation, och Verktyg för att hämta levande data eller utföra operationer. ## Nästa Steg -**Nästa modul:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Nästa Modul:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**Navigering:** [← Föregående: Modul 03 - RAG](../03-rag/README.md) | [Tillbaka till huvudmenyn](../README.md) | [Nästa: Modul 05 - MCP →](../05-mcp/README.md) +**Navigering:** [← Föregående: Modul 03 - RAG](../03-rag/README.md) | [Tillbaka till Start](../README.md) | [Nästa: Modul 05 - MCP →](../05-mcp/README.md) --- **Ansvarsfriskrivning**: -Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, bör du vara medveten om att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål ska betraktas som den auktoritativa källan. För viktig information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för eventuella missförstånd eller feltolkningar som uppstår på grund av användningen av denna översättning. +Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning. \ No newline at end of file diff --git a/translations/sv/README.md b/translations/sv/README.md index cfb526b33..c19e1aa07 100644 --- a/translations/sv/README.md +++ b/translations/sv/README.md @@ -2,18 +2,18 @@ # LangChain4j för nybörjare -En kurs för att bygga AI-applikationer med LangChain4j och Azure OpenAI GPT-5.2, från enkel chatt till AI-agenter. +En kurs för att bygga AI-applikationer med LangChain4j och Azure OpenAI GPT-5.2, från grundläggande chatt till AI-agenter. -### 🌐 Fler språkstödd +### 🌐 Flera språks stöd -#### Stöds via GitHub Action (Automatiserad & Alltid Uppdaterad) +#### Stöds via GitHub Action (Automatiserat & Alltid uppdaterat) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](./README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) > **Föredrar du att klona lokalt?** > -> Det här arkivet inkluderar över 50 språköversättningar vilket ökar nedladdningsstorleken betydligt. För att klona utan översättningar, använd sparse checkout: +> Detta arkiv inkluderar över 50 språköversättningar vilket avsevärt ökar nedladdningsstorleken. För att klona utan översättningar, använd sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,61 +29,60 @@ En kurs för att bygga AI-applikationer med LangChain4j och Azure OpenAI GPT-5.2 > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Detta ger dig allt du behöver för att genomföra kursen med en mycket snabbare nedladdning. +> Detta ger dig allt du behöver för att slutföra kursen med en mycket snabbare nedladdning. ## Innehållsförteckning -1. [Snabbstart](00-quick-start/README.md) - Kom igång med LangChain4j -2. [Introduktion](01-introduction/README.md) - Lär dig grunderna i LangChain4j -3. [Prompt Engineering](02-prompt-engineering/README.md) - Bemästra effektiv promptdesign -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Bygg intelligenta kunskapsbaserade system -5. [Verktyg](04-tools/README.md) - Integrera externa verktyg och enkla assistenter -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Arbeta med Model Context Protocol (MCP) och Agentmoduler +1. [Introduktion](01-introduction/README.md) - Lär dig grunderna i LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Bemästra effektiv promptdesign +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Bygg intelligenta kunskapsbaserade system +4. [Verktyg](04-tools/README.md) - Integrera externa verktyg och enkla assistenter +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Arbeta med Model Context Protocol (MCP) och Agentic-moduler ### Videogenomgångar -Varje modul har en medföljande livesession där vi går igenom koncept och kod steg för steg. +Varje modul har en följesession där vi steg för steg går igenom koncept och kod. | Modul | Video | |--------|-------| -| 01 - Introduktion | [Kom igång med LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 01 - Introduktion | [Komma igång med LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - Prompt Engineering | [Prompt Engineering med LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG med LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Verktyg & 05 - MCP | [AI-agenter med verktyg och MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Verktyg & 05 - MCP | [AI-agenter med Verktyg och MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Lärväg +## Läroplan -**Ny på LangChain4j?** Kolla in [Glossary](docs/GLOSSARY.md) för definitioner av nyckeltermer och koncept. +**Ny på LangChain4j?** Kolla in [Ordlista](docs/GLOSSARY.md) för definitioner av viktiga termer och begrepp. > **Snabbstart** -1. Fork:a detta arkiv till ditt GitHub-konto +1. Forka detta arkiv till ditt GitHub-konto 2. Klicka på **Code** → fliken **Codespaces** → **...** → **New with options...** -3. Använd standardinställningarna – detta väljer utvecklingsbehållaren skapad för denna kurs +3. Använd standardinställningarna – detta väljer Utvecklingscontainern som skapats för denna kurs 4. Klicka på **Create codespace** -5. Vänta 5–10 minuter tills miljön är klar -6. Gå direkt till [Snabbstart](./00-quick-start/README.md) för att komma igång! +5. Vänta 5-10 minuter tills miljön är klar +6. Hoppa direkt till [Introduktion](./01-introduction/README.md) för att komma igång! -När du har genomfört modulerna, utforska [Testing Guide](docs/TESTING.md) för att se LangChain4j testkoncept i praktiken. +Efter att ha slutfört modulerna, utforska [Testningsguiden](docs/TESTING.md) för att se LangChain4js testkoncept i praktiken. -> **Obs:** Denna utbildning använder både GitHub Models och Azure OpenAI. [Snabbstart](00-quick-start/README.md) använder GitHub Models (ingen Azure-prenumeration krävs), medan modulerna 1-5 använder Azure OpenAI. Kom igång med ett [GRATIS Azure-konto](https://aka.ms/azure-free-account) om du inte har ett. +> **Obs:** Denna träning använder Azure OpenAI. Kom igång med ett [GRATIS Azure-konto](https://aka.ms/azure-free-account) om du inte har ett. -## Lär med GitHub Copilot +## Lära med GitHub Copilot -För att snabbt börja koda, öppna detta projekt i en GitHub Codespace eller din lokala IDE med den medföljande devcontainer. Devcontainern som används i denna kurs är förkonfigurerad med GitHub Copilot för AI-parprogrammering. +För att snabbt börja koda, öppna detta projekt i en GitHub Codespace eller din lokala IDE med den medföljande devcontainern. Devcontainern som används i denna kurs är förkonfigurerad med GitHub Copilot för AI-parprogrammering. -Varje kodexempel innehåller föreslagna frågor som du kan ställa till GitHub Copilot för att fördjupa din förståelse. Leta efter 💡/🤖-promptar i: +Varje kodexempel innehåller föreslagna frågor som du kan ställa till GitHub Copilot för att fördjupa din förståelse. Leta efter 💡/🤖-prompterna i: -- **Java-filhänvisningar** - Specifika frågor för varje exempel -- **Modulernas README-filer** - Utforskningspromptar efter kodexempel +- **Java-filhuvuden** - Frågor specifika för varje exempel +- **Modulernas README-filer** - Utforskningsfrågor efter kodexempel -**Hur man använder:** Öppna någon kodfil och fråga Copilot de föreslagna frågorna. Den har full kontext om kodbasen och kan förklara, utöka och föreslå alternativ. +**Hur man använder:** Öppna vilken kodfil som helst och ställ Copilot de föreslagna frågorna. Den har full kontext av kodbasen och kan förklara, utöka och föreslå alternativ. -Vill du veta mer? Kolla in [Copilot för AI-parprogrammering](https://aka.ms/GitHubCopilotAI). +Vill du lära dig mer? Kolla in [Copilot för AI-parprogrammering](https://aka.ms/GitHubCopilotAI). ## Ytterligare resurser @@ -104,37 +103,38 @@ Vill du veta mer? Kolla in [Copilot för AI-parprogrammering](https://aka.ms/Git --- ### Generativ AI-serie -[![Generativ AI för nybörjare](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generative AI för nybörjare](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generativ AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generativ AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) [![Generativ AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Kärninlärning +### Kärnlära [![ML för nybörjare](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science för nybörjare](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI för nybörjare](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Cybersecurity för nybörjare](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Webbutveckling för nybörjare](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT för nybörjare](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR-utveckling för nybörjare](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersäkerhet för nybörjare](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Copilot-serien -[![Copilot för AI-parprogrammering](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot för C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot-äventyr](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Få hjälp -Om du kör fast eller har frågor om att bygga AI-appar, gå med i: +Om du fastnar eller har några frågor om att bygga AI-appar, gå med i: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Om du har produktfeedback eller hittar fel under byggprocessen, besök: +Om du har produktfeedback eller stöter på fel när du bygger, besök: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) @@ -146,5 +146,5 @@ MIT-licens - Se [LICENSE](../../LICENSE) filen för detaljer. **Ansvarsfriskrivning**: -Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, vänligen var medveten om att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör anses vara den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår vid användning av denna översättning. +Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning. \ No newline at end of file diff --git a/translations/sv/docs/GLOSSARY.md b/translations/sv/docs/GLOSSARY.md index fef1a1bc9..05fc6805f 100644 --- a/translations/sv/docs/GLOSSARY.md +++ b/translations/sv/docs/GLOSSARY.md @@ -2,57 +2,57 @@ ## Innehållsförteckning -- [Kärnkoncept](../../../docs) -- [LangChain4j-komponenter](../../../docs) -- [AI/ML-koncept](../../../docs) -- [Säkerhetsmekanismer](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Agenter och Verktyg](../../../docs) -- [Agentmodul](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Azure-tjänster](../../../docs) -- [Testning och Utveckling](../../../docs) - -Snabb referens för termer och koncept som används i hela kursen. +- [Kärnkoncept](#kärnkoncept) +- [LangChain4j Komponenter](#langchain4j-komponenter) +- [AI/ML Koncept](#aiml-koncept) +- [Guardrails](#guardrails) +- [Prompt Engineering](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agenter och Verktyg](#agents-and-tools---module-04) +- [Agentic Modul](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure Tjänster](#azure-services---module-01) +- [Testning och Utveckling](#testing-and-development---testing-guide) + +Snabbreferens för termer och koncept som används i hela kursen. ## Kärnkoncept **AI Agent** - System som använder AI för att resonera och agera autonomt. [Modul 04](../04-tools/README.md) -**Chain** - Sekvens av operationer där utdata mata in i nästa steg. +**Chain** - Sekvens av operationer där output matas in i nästa steg. -**Chunking** - Bryter dokument i mindre delar. Typiskt: 300-500 token med överlappning. [Modul 03](../03-rag/README.md) +**Chunking** - Bryta dokument i mindre bitar. Typiskt: 300-500 tokens med överlappning. [Modul 03](../03-rag/README.md) -**Context Window** - Max antal token en modell kan bearbeta. GPT-5.2: 400K token (upp till 272K input, 128K output). +**Context Window** - Max antal tokens en modell kan bearbeta. GPT-5.2: 400K tokens (upp till 272K input, 128K output). -**Embeddings** - Numeriska vektorer som representerar textens betydelse. [Modul 03](../03-rag/README.md) +**Embeddings** - Numeriska vektorer som representerar textens mening. [Modul 03](../03-rag/README.md) **Function Calling** - Modell genererar strukturerade förfrågningar för att anropa externa funktioner. [Modul 04](../04-tools/README.md) **Hallucination** - När modeller genererar felaktig men trovärdig information. -**Prompt** - Textinmatning till en språkmodell. [Modul 02](../02-prompt-engineering/README.md) +**Prompt** - Texteingång till en språkmodell. [Modul 02](../02-prompt-engineering/README.md) -**Semantic Search** - Sökning baserad på betydelse med embeddings, inte nyckelord. [Modul 03](../03-rag/README.md) +**Semantic Search** - Sökning baserad på mening med embeddings, inte nyckelord. [Modul 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: inget minne. Stateful: behåller konversationshistorik. [Modul 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: inget minne. Stateful: bibehåller konversationshistorik. [Modul 01](../01-introduction/README.md) **Tokens** - Grundläggande textenheter som modeller bearbetar. Påverkar kostnader och begränsningar. [Modul 01](../01-introduction/README.md) -**Tool Chaining** - Sekventiell verktygsexekvering där utdata informerar nästa anrop. [Modul 04](../04-tools/README.md) +**Tool Chaining** - Sekventiell verktygsexekvering där output informerar nästa anrop. [Modul 04](../04-tools/README.md) -## LangChain4j-komponenter +## LangChain4j Komponenter -**AiServices** - Skapar typer-baserade AI-servicelgränssnitt. +**AiServices** - Skapar typsäkra AI-tjänstegränssnitt. -**OpenAiOfficialChatModel** - Enhetlig klient för OpenAI och Azure OpenAI-modeller. +**OpenAiOfficialChatModel** - Enhetlig klient för OpenAI och Azure OpenAI modeller. -**OpenAiOfficialEmbeddingModel** - Skapar embeddings med OpenAI Official-klienten (stödjer både OpenAI och Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Skapar embeddings med OpenAI Official klient (stöder både OpenAI och Azure OpenAI). **ChatModel** - Kärngränssnitt för språkmodeller. -**ChatMemory** - Behåller konversationshistorik. +**ChatMemory** - Bibehåller konversationshistorik. **ContentRetriever** - Hittar relevanta dokumentbitar för RAG. @@ -62,57 +62,57 @@ Snabb referens för termer och koncept som används i hela kursen. **EmbeddingStore** - Lagrar och hämtar embeddings. -**MessageWindowChatMemory** - Behåller ett glidande fönster av senaste meddelanden. +**MessageWindowChatMemory** - Bibehåller ett glidande fönster av senaste meddelanden. -**PromptTemplate** - Skapar återanvändbara prompts med `{{variable}}`-platshållare. +**PromptTemplate** - Skapar återanvändbara prompts med `{{variable}}` platshållare. **TextSegment** - Textbit med metadata. Används i RAG. -**ToolExecutionRequest** - Representerar verktygsexekveringsförfrågan. +**ToolExecutionRequest** - Representerar begäran om verktygsexekvering. -**UserMessage / AiMessage / SystemMessage** - Typer av konversationsmeddelanden. +**UserMessage / AiMessage / SystemMessage** - Typer av meddelanden i konversation. -## AI/ML-koncept +## AI/ML Koncept -**Few-Shot Learning** - Tillhandahåller exempel i prompts. [Modul 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Tillhandahålla exempel i prompts. [Modul 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - AI-modeller tränade på stora textmängder. +**Large Language Model (LLM)** - AI-modeller tränade på stora mängder textdata. -**Reasoning Effort** - GPT-5.2-parameter som styr hurtighet i tänkande. [Modul 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - GPT-5.2 parameter som styr tänkardjup. [Modul 02](../02-prompt-engineering/README.md) -**Temperature** - Styr outputens slumpmässighet. Lågt=deterministiskt, högt=kreativt. +**Temperature** - Styr slumpmässighet i output. Låg=deterministisk, hög=kreativ. **Vector Database** - Specialiserad databas för embeddings. [Modul 03](../03-rag/README.md) -**Zero-Shot Learning** - Utför uppgifter utan exempel. [Modul 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Utföra uppgifter utan exempel. [Modul 02](../02-prompt-engineering/README.md) -## Säkerhetsmekanismer - [Modul 00](../00-quick-start/README.md) +## Guardrails -**Defense in Depth** - Flerlagers säkerhetsstrategi som kombinerar applikationsnivå-säkerhetsmekanismer med leverantörers säkerhetsfilter. +**Defense in Depth** - Flerlagerssäkerhetsstrategi som kombinerar applikationsnivå guardrails med leverantörers säkerhetsfilter. -**Hard Block** - Leverantör kastar HTTP 400-fel vid allvarliga innehållsöverträdelse. +**Hard Block** - Leverantör kastar HTTP 400-fel vid allvarliga innehållsbrott. -**InputGuardrail** - LangChain4j-gränssnitt för validering av användarinmatning innan det når LLM. Sparar kostnad och latens genom att blockera skadliga prompts tidigt. +**InputGuardrail** - LangChain4j-gränssnitt för validering av användarinmatning innan den når LLM. Sparar kostnad och latens genom att blockera skadliga prompts tidigt. -**InputGuardrailResult** - Returtyp för validering av säkerhetsmekanismer: `success()` eller `fatal("reason")`. +**InputGuardrailResult** - Returtyp för guardrail-validering: `success()` eller `fatal("anledning")`. **OutputGuardrail** - Gränssnitt för validering av AI-svar innan de returneras till användare. -**Provider Safety Filters** - Inbyggda innehållsfilter från AI-leverantörer (t.ex. GitHub Models) som fångar överträdelser på API-nivå. +**Provider Safety Filters** - Inbyggda innehållsfilter från AI-leverantörer (t.ex. Azure OpenAI) som fångar överträdelser på API-nivå. **Soft Refusal** - Modell artigt avböjer att svara utan att kasta fel. ## Prompt Engineering - [Modul 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Stegvis resonemang för bättre noggrannhet. +**Chain-of-Thought** - Steg-för-steg-resonemang för bättre noggrannhet. -**Constrained Output** - Tvingar specifikt format eller struktur. +**Constrained Output** - Påtvinga specifikt format eller struktur. -**High Eagerness** - GPT-5.2-mönster för grundligt resonemang. +**High Eagerness** - GPT-5.2 mönster för grundligt resonemang. -**Low Eagerness** - GPT-5.2-mönster för snabba svar. +**Low Eagerness** - GPT-5.2 mönster för snabba svar. -**Multi-Turn Conversation** - Behålla kontext över utbyten. +**Multi-Turn Conversation** - Bibehålla kontext genom utbyten. **Role-Based Prompting** - Sätta modellpersona via systemmeddelanden. @@ -120,15 +120,15 @@ Snabb referens för termer och koncept som används i hela kursen. **Structured Analysis** - Fast utvärderingsramverk. -**Task Execution Pattern** - Planera → Exekvera → Sammanfatta. +**Task Execution Pattern** - Planera → Utför → Sammanfatta. ## RAG (Retrieval-Augmented Generation) - [Modul 03](../03-rag/README.md) **Document Processing Pipeline** - Ladda → dela upp → embedda → lagra. -**In-Memory Embedding Store** - Icke-persistent lagring för testning. +**In-Memory Embedding Store** - Icke-persistenta lagring för testning. -**RAG** - Kombinerar hämtning med generering för att grundlägga svar. +**RAG** - Kombinerar återvinning med generering för att markförankra svar. **Similarity Score** - Mått (0-1) på semantisk likhet. @@ -146,17 +146,17 @@ Snabb referens för termer och koncept som används i hela kursen. **Tool Description** - Dokumentation av verktygets syfte och parametrar. -## Agentmodul - [Modul 05](../05-mcp/README.md) +## Agentic Modul - [Modul 05](../05-mcp/README.md) **@Agent Annotation** - Markerar gränssnitt som AI-agenter med deklarativ beteendedefinition. **Agent Listener** - Hook för att övervaka agentexekvering via `beforeAgentInvocation()` och `afterAgentInvocation()`. -**Agentic Scope** - Delat minne där agenter lagrar utdata med `outputKey` för att andra agenter ska kunna använda. +**Agentic Scope** - Delat minne där agenter lagrar output med `outputKey` för nedströmsagenter att konsumera. **AgenticServices** - Fabrik för att skapa agenter med `agentBuilder()` och `supervisorBuilder()`. -**Conditional Workflow** - Rutt baserat på villkor till olika specialagenters. +**Conditional Workflow** - Rutterar baserat på villkor till olika specialagentern. **Human-in-the-Loop** - Arbetsflödesmönster som lägger till mänskliga kontrollpunkter för godkännande eller innehållsgranskning. @@ -164,15 +164,15 @@ Snabb referens för termer och koncept som används i hela kursen. **Loop Workflow** - Iterera agentexekvering tills ett villkor uppfylls (t.ex. kvalitetspoäng ≥ 0.8). -**outputKey** - Agentannoteringsparameter som anger var resultat lagras i Agentic Scope. +**outputKey** - Agentannotationsparameter som specificerar var resultat ska lagras i Agentic Scope. **Parallel Workflow** - Kör flera agenter samtidigt för oberoende uppgifter. -**Response Strategy** - Hur supervisor formulerar slutgiltigt svar: LAST, SUMMARY eller SCORED. +**Response Strategy** - Hur supervisor formulerar slutligt svar: LAST, SUMMARY eller SCORED. -**Sequential Workflow** - Exekvera agenter i ordning där utdata flödar till nästa steg. +**Sequential Workflow** - Kör agenter i ordning där output flyter till nästa steg. -**Supervisor Agent Pattern** - Avancerat agentmönster där en supervisor LLM dynamiskt väljer vilka underagenter som ska anropas. +**Supervisor Agent Pattern** - Avancerat agentmönster där en supervisor-LLM dynamiskt bestämmer vilka underagenter som ska anropas. ## Model Context Protocol (MCP) - [Modul 05](../05-mcp/README.md) @@ -180,47 +180,45 @@ Snabb referens för termer och koncept som används i hela kursen. **MCP** - Model Context Protocol: standard för att koppla AI-appar till externa verktyg. Bygg en gång, använd överallt. -**MCP Client** - Applikation som ansluter till MCP-servrar för att upptäcka och använda verktyg. +**MCP Client** - Applikation som kopplar till MCP-servrar för att upptäcka och använda verktyg. **MCP Server** - Tjänst som exponerar verktyg via MCP med tydliga beskrivningar och parameterscheman. -**McpToolProvider** - LangChain4j-komponent som omsluter MCP-verktyg för användning i AI-tjänster och agenter. +**McpToolProvider** - LangChain4j-komponent som kapslar MCP-verktyg för användning i AI-tjänster och agenter. **McpTransport** - Gränssnitt för MCP-kommunikation. Implementationer inkluderar Stdio och HTTP. -**Stdio Transport** - Lokal processtransport via stdin/stdout. Användbar för åtkomst till filsystem eller kommandoradsverktyg. +**Stdio Transport** - Lokal processtransport via stdin/stdout. Användbart för filsystemåtkomst eller kommandoradsverktyg. **StdioMcpTransport** - LangChain4j-implementation som startar MCP-server som subprocess. -**Tool Discovery** - Klient frågar servern om tillgängliga verktyg med beskrivningar och scheman. +**Tool Discovery** - Klient frågar server om tillgängliga verktyg med beskrivningar och scheman. -## Azure-tjänster - [Modul 01](../01-introduction/README.md) +## Azure Tjänster - [Modul 01](../01-introduction/README.md) -**Azure AI Search** - Molnsökning med vektorbaserade funktioner. [Modul 03](../03-rag/README.md) +**Azure AI Search** - Molnsökning med vektor kapabiliteter. [Modul 03](../03-rag/README.md) **Azure Developer CLI (azd)** - Distribuerar Azure-resurser. **Azure OpenAI** - Microsofts företags-AI-tjänst. -**Bicep** - Azure infrastruktur-som-kod språk. [Infrastrukturguide](../01-introduction/infra/README.md) +**Bicep** - Azure infrastruktur-som-kod språk. [Infrastruktur Guide](../01-introduction/infra/README.md) **Deployment Name** - Namn för modellutplacering i Azure. -**GPT-5.2** - Senaste OpenAI-modellen med kontroll över resonemang. [Modul 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Senaste OpenAI-modellen med styrning av resonemang. [Modul 02](../02-prompt-engineering/README.md) -## Testning och Utveckling - [Testguide](TESTING.md) +## Testning och Utveckling - [Testningsguide](TESTING.md) **Dev Container** - Containeriserad utvecklingsmiljö. [Konfiguration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Gratis AI-modelllekplats. [Modul 00](../00-quick-start/README.md) - -**In-Memory Testing** - Testning med lagring i minnet. +**In-Memory Testing** - Testning med minneslagring. **Integration Testing** - Testning med riktig infrastruktur. -**Maven** - Java-byggautomatiseringsverktyg. +**Maven** - Java-byggautomationsverktyg. -**Mockito** - Java-ramverk för mockning. +**Mockito** - Java mockningsramverk. **Spring Boot** - Java applikationsramverk. [Modul 01](../01-introduction/README.md) @@ -228,5 +226,5 @@ Snabb referens för termer och koncept som används i hela kursen. **Ansvarsfriskrivning**: -Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, bör du vara medveten om att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess ursprungliga språk bör betraktas som den auktoritativa källan. För viktig information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för eventuella missförstånd eller feltolkningar som uppstår vid användning av denna översättning. +Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning. \ No newline at end of file diff --git a/translations/sv/docs/TESTING.md b/translations/sv/docs/TESTING.md index 3f3aa5b6d..2dde68d14 100644 --- a/translations/sv/docs/TESTING.md +++ b/translations/sv/docs/TESTING.md @@ -2,15 +2,15 @@ ## Innehållsförteckning -- [Snabbstart](../../../docs) -- [Vad testerna täcker](../../../docs) -- [Köra testerna](../../../docs) -- [Köra tester i VS Code](../../../docs) -- [Testmönster](../../../docs) -- [Testfilosofi](../../../docs) -- [Nästa steg](../../../docs) +- [Snabbstart](#snabbstart) +- [Vad testen täcker](#vad-testen-täcker) +- [Köra testen](#köra-testen) +- [Köra tester i VS Code](#köra-tester-i-vs-code) +- [Testmönster](#testmönster) +- [Testfilosofi](#testfilosofi) +- [Nästa steg](#nästa-steg) -Den här guiden går igenom tester som visar hur man testar AI-applikationer utan att behöva API-nycklar eller externa tjänster. +Denna guide går igenom testen som visar hur man testar AI-applikationer utan att kräva API-nycklar eller externa tjänster. ## Snabbstart @@ -26,30 +26,29 @@ mvn test mvn --% test ``` -När alla tester lyckas bör du se en utdata som på skärmbilden nedan — tester körs utan några fel. +När alla tester passerar bör du se output som i skärmdumpen nedan — tester körs utan några fel. Successful Test Results -*Framgångsrik testkörning som visar att alla tester gick igenom utan fel* +*Framgångsrikt testkörning som visar att alla tester passerar utan fel* -## Vad testerna täcker +## Vad testen täcker -Denna kurs fokuserar på **enhetstester** som körs lokalt. Varje test demonstrerar ett specifikt LangChain4j-koncept isolerat. Testpyramiden nedan visar var enhetstester hör hemma — de utgör den snabba, pålitliga grunden som resten av din teststrategi bygger på. +Denna kurs fokuserar på **enhetstester** som körs lokalt. Varje test demonstrerar ett specifikt LangChain4j-koncept isolerat. Testpyramiden nedan visar var enhetstester passar in — de utgör den snabba, tillförlitliga grund som resten av din teststrategi bygger på. Testing Pyramid -*Testpyramid som visar balansen mellan enhetstester (snabba, isolerade), integrationstester (riktiga komponenter) och end-to-end-tester. Denna utbildning täcker enhetstestning.* +*Testpyramid som visar balansen mellan enhetstester (snabba, isolerade), integrationstester (riktiga komponenter) och end-to-end-tester. Denna utbildning täcker enhetstester.* -| Modul | Tester | Fokus | Viktiga filer | +| Modul | Tester | Fokus | Nyckelfiler | |--------|-------|-------|-----------| -| **00 - Snabbstart** | 6 | Promptmallar och variabelersättning | `SimpleQuickStartTest.java` | -| **01 - Introduktion** | 8 | Konversationsminne och stateful chat | `SimpleConversationTest.java` | +| **01 - Introduktion** | 8 | Konversationsminne och tillståndsbaserad chatt | `SimpleConversationTest.java` | | **02 - Prompt Engineering** | 12 | GPT-5.2-mönster, ivernivåer, strukturerad output | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Dokumentintagning, embeddings, likhetssökning | `DocumentServiceTest.java` | +| **03 - RAG** | 10 | Dokumentingestion, embeddingar, likhetssökning | `DocumentServiceTest.java` | | **04 - Verktyg** | 12 | Funktionsanrop och verktygskedjor | `SimpleToolsTest.java` | | **05 - MCP** | 8 | Model Context Protocol med Stdio-transport | `SimpleMcpTest.java` | -## Köra testerna +## Köra testen **Kör alla tester från root:** @@ -95,12 +94,12 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#börBehållaSamtalshistorik +mvn test -Dtest=SimpleConversationTest#börBehållaKonversationshistorik ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#börBibehållaSamtalshistorik +mvn --% test -Dtest=SimpleConversationTest#börBehållaSamtalshistorik ``` ## Köra tester i VS Code @@ -109,27 +108,27 @@ Om du använder Visual Studio Code ger Test Explorer ett grafiskt gränssnitt f VS Code Test Explorer -*VS Code Test Explorer som visar testträdet med alla Java-testklasser och individuella testmetoder* +*VS Code Test Explorer som visar testträdet med alla Java testklasser och individuella testmetoder* **För att köra tester i VS Code:** -1. Öppna Test Explorer genom att klicka på bägareikonen i aktivitetsfältet +1. Öppna Test Explorer genom att klicka på provröret i aktivitetsfältet 2. Expandera testträdet för att se alla moduler och testklasser -3. Klicka på play-knappen bredvid valfritt test för att köra det individuellt -4. Klicka på "Run All Tests" för att köra hela testsviten -5. Högerklicka på ett test och välj "Debug Test" för att sätta brytpunkter och stega i koden +3. Klicka på spelknappen bredvid ett test för att köra det individuellt +4. Klicka på "Run All Tests" för att köra hela testuppsättningen +5. Högerklicka på ett test och välj "Debug Test" för att sätta brytpunkter och stega igenom koden -Test Explorern visar gröna bockar för godkända tester och ger detaljerade felmeddelanden när tester misslyckas. +Test Explorer visar gröna bockar för passerade tester och ger detaljerade felmeddelanden när tester misslyckas. ## Testmönster -### Mönster 1: Testa promptmallar +### Mönster 1: Testa Prompt-mallar -Det enklaste mönstret testar promptmallar utan att anropa någon AI-modell. Du verifierar att variabelersättningen fungerar korrekt och att promptar formateras som förväntat. +Det enklaste mönstret testar promptmallar utan att anropa något AI-modell. Du verifierar att variabelersättning fungerar korrekt och att promptarna är korrekt formaterade. Prompt Template Testing -*Test av promptmallar som visar flödet för variabelersättning: mall med platshållare → värden appliceras → formaterad output verifieras* +*Test av promptmallar som visar flödet för variabelersättning: mall med platshållare → värden applicerade → formaterad output verifierad* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Detta test finns i `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Kör det:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatering -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testPromptTemplateFormatering -``` +Detta mönster verifierar att variabelersättning fungerar korrekt och att promptar formateras som förväntat — ingen API-nyckel eller modell-anrop krävs. ### Mönster 2: Mocka språkmodeller -När du testar konversationslogik, använd Mockito för att skapa falska modeller som returnerar förutbestämda svar. Detta gör testerna snabba, gratis och deterministiska. +När du testar konversationslogik, använd Mockito för att skapa falska modeller som returnerar förutbestämda svar. Detta gör testerna snabba, kostnadsfria och deterministiska. Mock vs Real API Comparison -*Jämförelse som visar varför mocks är att föredra vid testning: de är snabba, gratis, deterministiska och kräver inga API-nycklar* +*Jämförelse som visar varför mocks föredras för testning: de är snabba, gratis, deterministiska och kräver inga API-nycklar* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Detta mönster finns i `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mocken säkerställer konsekvent beteende så att du kan verifiera att minneshanteringen fungerar korrekt. +Detta mönster finns i `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mocken säkerställer konsekvent beteende så att du kan verifiera att minneshantering fungerar korrekt. ### Mönster 3: Testa konversationsisolering -Konversationsminnet måste hålla flera användare åtskilda. Detta test verifierar att samtal inte blandar samman kontexter. +Konversationsminnet måste hålla flera användare separerade. Detta test verifierar att konversationer inte blandar samman kontexter. Conversation Isolation -*Test av konversationsisolering som visar separata minneslagringar för olika användare för att förhindra kontextblandning* +*Test av konversationsisolering som visar separata minneslager för olika användare för att förhindra kontextblandning* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Varje konversation håller sin egen oberoende historik. I produktionssystem är denna isolering avgörande för fleranvändarapplikationer. +Varje konversation behåller sin egen oberoende historik. I produktionssystem är denna isolering kritisk för applikationer med flera användare. ### Mönster 4: Testa verktyg oberoende -Verktyg är funktioner som AI kan anropa. Testa dem direkt för att säkerställa att de fungerar korrekt oavsett AI-beslut. +Verktyg är funktioner som AI kan anropa. Testa dem direkt för att säkerställa att de fungerar korrekt oberoende av AI-beslut. Tools Testing -*Test av verktyg oberoende som visar mock-körning av verktyg utan AI-anrop för att verifiera affärslogik* +*Test av verktyg oberoende som visar mock-körning av verktyg utan AI-anrop för att verifiera affärslogiken* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Dessa tester från `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validerar verktygets logik utan AI-inblandning. Kedjeexemplet visar hur ett verktygs output matas in till ett annat. +Dessa tester från `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` validerar verktygslogik utan AI-inblandning. Exemplet med kedjning visar hur output från ett verktyg matas som input till ett annat. ### Mönster 5: In-memory RAG-testning -RAG-system kräver traditionellt vektordatabaser och embeddingstjänster. In-memory-mönstret låter dig testa hela pipelinen utan externa beroenden. +RAG-system kräver traditionellt vektordatabaser och embeddingtjänster. In-memory-mönstret låter dig testa hela pipelinen utan externa beroenden. In-Memory RAG Testing -*In-memory RAG-testflöde som visar dokumentparsing, embeddinglagring och likhetssökning utan att kräva databas* +*In-memory RAG-testflöde som visar dokumentparsing, embedding lagring och likhetssökning utan krav på databas* ```java @Test @@ -310,9 +297,9 @@ Detta test från `03-rag/src/test/java/com/example/langchain4j/rag/service/Docum ### Mönster 6: MCP-integrationstestning -MCP-modulen testar integrationen av Model Context Protocol med stdio-transport. Dessa tester verifierar att din applikation kan skapa och kommunicera med MCP-servrar som underprocesser. +MCP-modulen testar integrationen av Model Context Protocol med stdio-transport. Dessa tester verifierar att din applikation kan starta och kommunicera med MCP-servrar som underprocesser. -Testerna i `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validerar MCP-klientens beteende. +Tester i `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` validerar MCP-klientbeteende. **Kör dem:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Testfilosofi -Testa din kod, inte AI:n. Dina tester ska validera koden du skriver genom att kontrollera hur promptar konstrueras, hur minnet hanteras och hur verktyg körs. AI-svar varierar och ska inte vara en del av testpåståenden. Fråga dig själv om din promptmall korrekt ersätter variabler, inte om AI ger rätt svar. +Testa din kod, inte AI:n. Dina tester bör validera koden du skriver genom att kontrollera hur prompts konstrueras, hur minne hanteras, och hur verktyg körs. AI-svar varierar och bör inte vara en del av testpåståenden. Fråga dig om din promptmall korrekt ersätter variabler, inte om AI:n ger rätt svar. -Använd mocks för språkmodeller. De är externa beroenden som är långsamma, dyra och icke-deterministiska. Mockning gör tester snabba med millisekunder istället för sekunder, gratis utan API-kostnader och deterministiska med samma resultat varje gång. +Använd mocks för språkmodeller. De är externa beroenden som är långsamma, dyra och icke-deterministiska. Mocking gör tester snabba med millisekunder istället för sekunder, gratis utan API-kostnader och deterministiska med samma resultat varje gång. -Håll tester oberoende. Varje test ska skapa sin egen data, inte förlita sig på andra tester, och städa upp efter sig. Tester ska gå igenom oavsett körordning. +Håll tester oberoende. Varje test bör sätta upp sina egna data, inte förlita sig på andra tester och städa upp efter sig. Tester ska passera oavsett körordning. -Testa kantfall utöver den lyckade vägen. Prova tomma inputs, mycket stora inputs, specialtecken, ogiltiga parametrar och gränsvärden. Dessa avslöjar ofta buggar som vanlig användning inte visar. +Testa kantfall utöver den lyckade vägen. Prova tomma indata, väldigt stora indata, specialtecken, ogiltiga parametrar och gränsvärden. Dessa avslöjar ofta buggar som vanlig användning inte gör. -Använd beskrivande namn. Jämför `shouldMaintainConversationHistoryAcrossMultipleMessages()` med `test1()`. Det första berättar exakt vad som testas och gör felsökning av fel mycket enklare. +Använd beskrivande namn. Jämför `shouldMaintainConversationHistoryAcrossMultipleMessages()` med `test1()`. Det första talar om exakt vad som testas, vilket gör felsökning av fel mycket enklare. ## Nästa steg Nu när du förstår testmönstren, fördjupa dig i varje modul: -- **[00 - Snabbstart](../00-quick-start/README.md)** - Börja med grunderna för promptmallar - **[01 - Introduktion](../01-introduction/README.md)** - Lär dig hantera konversationsminne -- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Bemästra GPT-5.2 promptingmönster -- **[03 - RAG](../03-rag/README.md)** - Bygg system för retrieval-augmented generation +- **[02 - Prompt Engineering](../02/prompt-engineering/README.md)** - Bemästra GPT-5.2 promptmönster +- **[03 - RAG](../03-rag/README.md)** - Bygg retrieval-augmented generation-system - **[04 - Verktyg](../04-tools/README.md)** - Implementera funktionsanrop och verktygskedjor - **[05 - MCP](../05-mcp/README.md)** - Integrera Model Context Protocol -Varje moduls README ger detaljerade förklaringar av koncepten som testas här. +Varje moduls README ger detaljerade förklaringar av de koncept som testas här. --- -**Navigation:** [← Tillbaka till Start](../README.md) +**Navigering:** [← Tillbaka till huvudmenyn](../README.md) --- **Ansvarsfriskrivning**: -Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Trots att vi strävar efter noggrannhet, vänligen observera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål ska betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för eventuella missförstånd eller feltolkningar som uppstår till följd av användning av denna översättning. +Detta dokument har översatts med hjälp av AI-översättningstjänsten [Co-op Translator](https://github.com/Azure/co-op-translator). Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning. \ No newline at end of file diff --git a/translations/sw/.co-op-translator.json b/translations/sw/.co-op-translator.json index 27641794b..6a9816a0b 100644 --- a/translations/sw/.co-op-translator.json +++ b/translations/sw/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "sw" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T02:31:43+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T08:47:17+00:00", "source_file": "01-introduction/README.md", "language_code": "sw" }, @@ -18,20 +18,20 @@ "language_code": "sw" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T02:35:09+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T08:42:04+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "sw" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T02:36:47+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T08:46:21+00:00", "source_file": "03-rag/README.md", "language_code": "sw" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:08:15+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T08:44:54+00:00", "source_file": "04-tools/README.md", "language_code": "sw" }, @@ -54,8 +54,8 @@ "language_code": "sw" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:50:41+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T08:40:31+00:00", "source_file": "README.md", "language_code": "sw" }, @@ -72,14 +72,14 @@ "language_code": "sw" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T02:40:25+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T08:42:41+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "sw" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T02:41:17+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T08:43:27+00:00", "source_file": "docs/TESTING.md", "language_code": "sw" } diff --git a/translations/sw/00-quick-start/README.md b/translations/sw/00-quick-start/README.md deleted file mode 100644 index a71bf4db7..000000000 --- a/translations/sw/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Moduli 00: Mwanzoni Haraka - -## Orodha ya Maudhui - -- [Utangulizi](../../../00-quick-start) -- [LangChain4j ni Nini?](../../../00-quick-start) -- [Mitegemezo ya LangChain4j](../../../00-quick-start) -- [Masharti ya Awali](../../../00-quick-start) -- [Usanidi](../../../00-quick-start) - - [1. Pata Tokeni Yako ya GitHub](../../../00-quick-start) - - [2. Weka Tokeni Yako](../../../00-quick-start) -- [Endesha Mifano](../../../00-quick-start) - - [1. Mazungumzo ya Msingi](../../../00-quick-start) - - [2. Mifumo ya Kuamsha](../../../00-quick-start) - - [3. Kuitikia Kazi](../../../00-quick-start) - - [4. Maswali na Majibu ya Nyaraka (RAG Rahisi)](../../../00-quick-start) - - [5. AI Yenye Uwajibikaji](../../../00-quick-start) -- [Kila Mfano Unaonyesha Nini](../../../00-quick-start) -- [Hatua Zifuatazo](../../../00-quick-start) -- [Matatizo na Suluhisho](../../../00-quick-start) - -## Utangulizi - -Mwanzoni mwende haraka huu umetengenezwa kukuwezesha kuanza na LangChain4j haraka iwezekanavyo. Unafundisha misingi ya ujenzi wa programu za AI kwa kutumia LangChain4j na Modeli za GitHub. Katika moduli zinazofuata utabadilisha kwenda Azure OpenAI na GPT-5.2 na kuingia kwa kina zaidi katika kila dhana. - -## LangChain4j ni Nini? - -LangChain4j ni maktaba ya Java ambayo inarahisisha ujenzi wa programu zinazotumia AI. Badala ya kujihangaisha na wateja wa HTTP na uchambuzi wa JSON, unafanya kazi na API za Java zisizo na matatizo. - -Neno "chain" katika LangChain linarejelea kuunganisha vipengele vingi kwa pamoja - unaweza kuunganisha onyo (prompt) kwa mfano (model) hadi parser, au kuunganisha simu nyingi za AI ambapo matokeo ya moja hutumika kama ingizo la moja inayofuata. Muanzoni hapa unazingatia mambo ya msingi kabla ya kuchunguza minyororo tata zaidi. - -Nguvu ya Kuunganisha LangChain4j - -*Kuunganisha vipengele ndani ya LangChain4j - vipande vya kujenga vinaunganishwa ili kuunda mchakato wa AI wenye nguvu* - -Tutatumia vipengele vitatu vikuu: - -**ChatModel** - Kiolesura cha mawasiliano na modeli za AI. Piga `model.chat("prompt")` na upate jibu kama mfululizo wa maneno. Tunatumia `OpenAiOfficialChatModel` ambayo hufanya kazi na vituo vya OpenAI vinavyolingana kama Modeli za GitHub. - -**AiServices** - Huunda miunganisho salama ya huduma za AI. Tafsiri njia, ziweke alama za `@Tool`, na LangChain4j inasimamia mchakato. AI huwaita njia zako za Java kiotomatiki inapohitajika. - -**MessageWindowChatMemory** - Huhifadhi kumbukumbu za mazungumzo. Bila hili, kila ombi ni huru. Ukiwa nayo, AI hukumbuka ujumbe wa awali na hubsidi muktadha kwa mizunguko mingi. - -Miundo ya LangChain4j - -*Miundo ya LangChain4j - vipengele vikuu vinavyofanya kazi pamoja kuendesha programu zako za AI* - -## Mitegemezo ya LangChain4j - -Mwanzoni hapa unatumia mitegemezo mitatu ya Maven katika [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Moduli `langchain4j-open-ai-official` hutoa darasa la `OpenAiOfficialChatModel` linalounganisha na API zinazolingana na OpenAI. Modeli za GitHub zinatumia muundo wa API uleule, hivyo hakuna hitaji la kiambatisho maalum — tuelekeze URL msingi kwa `https://models.github.ai/inference`. - -Moduli `langchain4j-easy-rag` hutoa mgawanyo wa nyaraka, uingizaji, na uhamasishaji wa kawaida ili uweze kujenga programu za RAG bila kusanidi kila hatua kwa mikono. - -## Masharti ya Awali - -**Unatumia Dev Container?** Java na Maven tayari zimewekwa. Unahitaji tu Tokeni ya Upatikanaji ya Binafsi ya GitHub. - -**Maendeleo ya Kiwanda:** -- Java 21+, Maven 3.9+ -- Tokeni ya Upatikanaji ya Binafsi ya GitHub (maelekezo yapo chini) - -> **Kumbuka:** Moduli hii inatumia `gpt-4.1-nano` kutoka Modeli za GitHub. Usibadilishe jina la modeli kwenye msimbo - limewekwa kufanya kazi na modeli zinazopatikana GitHub. - -## Usanidi - -### 1. Pata Tokeni Yako ya GitHub - -1. Nenda kwenye [Mipangilio ya GitHub → Tokeni za Upatikanaji wa Binafsi](https://github.com/settings/personal-access-tokens) -2. Bonyeza "Generate new token" -3. Weka jina linaloeleweka (mfano, "Hello LangChain4j") -4. Weka muda wa kudumu (inapendekezwa siku 7) -5. Chini ya "Account permissions", pata "Models" na weka kuwa "Read-only" -6. Bonyeza "Generate token" -7. Nakili na hifadhi tokeni yako - hutaiwona tena - -### 2. Weka Tokeni Yako - -**Chaguo 1: Kutumia VS Code (Inapendekezwa)** - -Ikiwa unatumia VS Code, ongeza tokeni yako kwenye faili `.env` kwenye mzizi wa mradi: - -Iki faili `.env` haipo, nakili `.env.example` hadi `.env` au tengeneza faili mpya `.env` kwenye mzizi wa mradi. - -**Mfano wa faili `.env`:** -```bash -# Katika /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Kisha unaweza bonyeza kulia kwenye faili lolote la onyesho (mfano, `BasicChatDemo.java`) kwenye Explorer na chagua **"Run Java"** au tumia mipangilio ya kuanzisha (launch configurations) kutoka kwenye Run and Debug panel. - -**Chaguo 2: Kutumia Terminal** - -Weka tokeni kama mabadiliko ya mazingira: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Endesha Mifano - -**Kutumia VS Code:** Bonyeza kulia kwenye faili lolote la onyesho kwenye Explorer na chagua **"Run Java"**, au tumia mipangilio ya kuanzisha kutoka Run and Debug panel (hakikisha umeweka tokeni kwenye `.env` kwanza). - -**Kutumia Maven:** Vinginevyo, unaweza endesha kutoka mstari wa amri: - -### 1. Mazungumzo ya Msingi - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Mifumo ya Kuamsha - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Inaonyesha zero-shot, few-shot, chain-of-thought, na prompt kulingana na majukumu. - -### 3. Kuitikia Kazi - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI hutumia njia zako za Java kiotomatiki inapohitajika. - -### 4. Maswali na Majibu ya Nyaraka (RAG Rahisi) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Uliza maswali kuhusu nyaraka zako ukitumia RAG Rahisi yenye ufungaji na uhamasishaji wa kiotomatiki. - -### 5. AI Yenye Uwajibikaji - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Tazama jinsi vichujio vya usalama wa AI vinavyozuia maudhui hatarishi. - -## Kila Mfano Unaonyesha Nini - -**Mazungumzo ya Msingi** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Anza hapa kuona LangChain4j kwa urahisi wake zaidi. Utaunda `OpenAiOfficialChatModel`, tuma onyo with `.chat()`, na upate jibu. Hii inaonyesha msingi: jinsi ya kuanzisha modeli kwa vituo maalum na funguo za API. Ukifahamu mfano huu, kila kitu kingine kinajengwa juu yake. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) na uliza: -> - "Ningebadilishaje kutoka Modeli za GitHub kwenda Azure OpenAI kwenye msimbo huu?" -> - "Nini vigezo vingine ninaweza kusanidi kwenye OpenAiOfficialChatModel.builder()?" -> - "Ningewajeongeza majibu yanayotiririka badala ya kusubiri jibu kamili?" - -**Uhandisi wa Prompt** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Sasa unajua jinsi ya kuzungumza na modeli, hebu tuchunguze unavyosema kwake. Demo hii inatumia usanidi ule ule wa modeli lakini inaonyesha mifumo mitano tofauti ya kuamsha (prompt). Jaribu zero-shot kwa maagizo ya moja kwa moja, few-shot ambapo hujifunza kutoka kwa mifano, chain-of-thought inayoonyesha hatua za kufikiri, na prompt kulingana na majukumu yanayoanzisha muktadha. Utaona jinsi modeli ile ile inavyotoa matokeo tofauti sana kulingana na namna unavyounda ombi lako. - -Demo pia inaonyesha template za prompt, njia yenye nguvu ya kuunda prompts zinazoweza kutumika tena kwa vigezo. -Mfano hapa chini unaonyesha prompt ukitumia `PromptTemplate` ya LangChain4j kujaza vigezo. AI itajibu kulingana na mahali pa kwenda na shughuli ulizotoa. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) na uliza: -> - "Tofauti kati ya zero-shot na few-shot ni nini, na ni lini niinate?" -> - "Jinsi joto la kiashiria (temperature) linavyoathiri majibu ya modeli?" -> - "Ni mbinu gani zinazotumika kuzuia mashambulizi ya prompt injection katika uzalishaji?" -> - "Ningejengaje vitu vya PromptTemplate vinavyoweza kutumika tena kwa mifano ya kawaida?" - -**Uunganishaji wa Zana** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Hapa ndipo LangChain4j linakuwa na nguvu zaidi. Utatumia `AiServices` kuunda msaidizi wa AI anaeyewaweza kuita njia zako za Java. Taja tu njia na `@Tool("maelezo")` na LangChain4j inasimamia yote - AI huamua kiotomatiki lini kutumia kila zana kulingana na kinachoulizwa. Hii inaonyesha kuiita kazi, tekniki muhimu ya kujenga AI inayoweza kuchukua hatua, siyo kujibu tu maswali. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) na uliza: -> - "Kiashirio cha @Tool kinafanya kazi vipi na LangChain4j hufanya nini nyuma ya pazia?" -> - "Je, AI inaweza kuita zana nyingi kwa mfululizo kutatua matatizo tata?" -> - "Nini kinatokea kama zana itatoa kosa - namna ya kushughulikia makosa ni gani?" -> - "Ningejumuishaje API halisi badala ya mfano huu wa calculator?" - -**Maswali na Majibu ya Nyaraka (RAG Rahisi)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Hapa utaona RAG (retrieval-augmented generation) ukitumia mbinu ya LangChain4j "Easy RAG". Nyaraka zinapakiwa, kugawanywa kiotomatiki na kuingizwa kwenye hifadhi ya kumbukumbu, kisha kivutio cha maudhui kinatoa vipande vinavyofaa kwa AI wakati wa kuuliza. AI hujibu kulingana na nyaraka zako, si maarifa yake ya jumla. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) na uliza: -> - "RAG inazuia vizungumzaji wa uongo vya AI vipi ikilinganishwa na kutumia data ya mafunzo ya modeli?" -> - "Tofauti kati ya njia rahisi hii na bomba la RAG maalum ni nini?" -> - "Ningeboreshaje kuhimili nyaraka nyingi au hifadhidata kubwa za maarifa?" - -**AI Yenye Uwajibikaji** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Jenga usalama wa AI kwa kinga kwa kina. Demo hii inaonyesha tabaka mbili za ulinzi zinazofanya kazi pamoja: - -**Sehemu 1: LangChain4j Input Guardrails** - Zuia maonyo hatarishi kabla hayafikie LLM. Tengeneza kinga maalum zinazotafuta maneno au mifumo isiyoruhusiwa. Hizi zinafanya kazi ndani ya msimbo wako, hivyo ni haraka na haina gharama. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Sehemu 2: Vichujio vya Usalama vya Mtoa Huduma** - Modeli za GitHub zina vichujio vilivyopo vinavyoshika yale kinga zako zinaweza kupitwa navyo. Utaona vizuizi vikali (makosa ya HTTP 400) kwa ukiukaji mkali na kukataa laini ambapo AI hukataa kwa heshima. - -> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) na uliza: -> - "InputGuardrail ni nini na ninawezaje kutengeneza yangu?" -> - "Tofauti kati ya kizuizi kigumu na kukataa laini ni nini?" -> - "Kwa nini tumia kinga na vichujio vya mtoa huduma pamoja?" - -## Hatua Zifuatazo - -**Moduli Ifuatayo:** [01-introduction - Kuanzisha na LangChain4j](../01-introduction/README.md) - ---- - -**Uelekezaji:** [← Rudi Kwenye Kuu](../README.md) | [Ifuatayo: Moduli 01 - Utangulizi →](../01-introduction/README.md) - ---- - -## Matatizo na Suluhisho - -### Kujenga Mara ya Kwanza kwa Maven - -**Tatizo:** Amri ya awali `mvn clean compile` au `mvn package` huchukua muda mrefu (dakika 10-15) - -**Sababu:** Maven inahitaji kupakua mitegemezo yote ya mradi (Spring Boot, maktaba za LangChain4j, SDK za Azure, n.k.) mara ya kwanza. - -**Suluhisho:** Hali hii ni ya kawaida. Majaribio yanayofuata yatakuwa haraka zaidi kwani mitegemezo itakuwa imehifadhiwa ndani. Muda wa kupakua unategemea kasi ya mtandao wako. - -### Syntax ya Amri za Maven katika PowerShell - -**Tatizo:** Amri za Maven zinashindwa na kosa `Unknown lifecycle phase ".mainClass=..."` -**Sababu**: PowerShell hufasiri `=` kama mtaalamu wa kugawa variable, kuharibu sintaksia ya mali za Maven - -**Suluhisho**: Tumia opereta ya kuacha kuchambua `--%` kabla ya amri ya Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Opereta `--%` huambia PowerShell kupitisha hoja zote zilizobaki moja kwa moja kwa Maven pasipo tafsiri. - -### Onyesho la Emoji la Windows PowerShell - -**Tatizo**: Majibu ya AI yanaonyesha herufi zisizotambulika (mfano, `????` au `â??`) badala ya emojis ndani ya PowerShell - -**Sababu**: Usimbaji wa PowerShell wa chaguo-msingi hauungi mkono emojis za UTF-8 - -**Suluhisho**: Endesha amri hii kabla ya kutekeleza programu za Java: -```cmd -chcp 65001 -``` - -Hii inalazimisha usimbaji wa UTF-8 kwenye terminal. Vinginevyo, tumia Windows Terminal ambayo ina msaada bora zaidi wa Unicode. - -### Kurekebisha Mapigo ya API - -**Tatizo**: Makosa ya uthibitishaji, mipaka ya kiwango, au majibu yasiyotarajiwa kutoka kwa mfano wa AI - -**Suluhisho**: Mifano inajumuisha `.logRequests(true)` na `.logResponses(true)` kuonyesha mapigo ya API kwenye konsoli. Hii husaidia kutatua makosa ya uthibitishaji, mipaka ya kiwango, au majibu yasiyotarajiwa. Ondoa bendera hizi katika uzalishaji kupunguza kelele za rekodi. - ---- - - -**Tangazo la Majeruhi**: -Hati hii imetafsiriwa kwa kutumia huduma ya utafsiri kwa AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kuwa sahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au ukosefu wa usahihi. Hati ya asili katika lugha yake ya asili inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya mtaalamu wa binadamu inashauriwa. Hatuna dhamana kwa kutoelewana au tafsiri potofu zinazotokana na matumizi ya tafsiri hii. - \ No newline at end of file diff --git a/translations/sw/01-introduction/README.md b/translations/sw/01-introduction/README.md index e420ce617..b959de940 100644 --- a/translations/sw/01-introduction/README.md +++ b/translations/sw/01-introduction/README.md @@ -1,85 +1,85 @@ # Moduli 01: Kuanzia na LangChain4j -## Jedwali la Yaliyomo - -- [Video ya Maelezo](../../../01-introduction) -- [Utajifunza Nini](../../../01-introduction) -- [Mambo ya Kuandaa](../../../01-introduction) -- [Kuelewa Tatizo Kuu](../../../01-introduction) -- [Kuelewa Vitoa-Kumbukumbu](../../../01-introduction) -- [Jinsi Kumbukumbu Inavyofanya Kazi](../../../01-introduction) -- [Jinsi Hii Inavyotumia LangChain4j](../../../01-introduction) -- [Tangaza Miundombinu ya Azure OpenAI](../../../01-introduction) -- [Endesha Programu Hapa Mkononi](../../../01-introduction) -- [Kutumia Programu](../../../01-introduction) - - [Mazungumzo Yasiyo na Hali (Paneli ya Kushoto)](../../../01-introduction) - - [Mazungumzo Yenye Hali (Paneli ya Kulia)](../../../01-introduction) -- [Hatua Zifuatazo](../../../01-introduction) - -## Video ya Maelezo - -Angalia kikao hiki cha moja kwa moja kinachoelezea jinsi ya kuanza na moduli hii: +## Jedwali la Maudhui + +- [Video ya Mwongozo](#video-ya-mwongozo) +- [Utajifunza Nini](#utajifunza-nini) +- [Mahitaji ya Awali](#mahitaji-ya-awali) +- [Kuelewa Shida Kuu](#kuelewa-shida-kuu) +- [Kuelewa Vitambulisho (Tokens)](#kuelewa-vitambulisho-tokens) +- [Jinsi Kumbukumbu Inavyofanya Kazi](#jinsi-kumbukumbu-inavyofanya-kazi) +- [Jinsi Hii Inavyotumia LangChain4j](#jinsi-hii-inavyotumia-langchain4j) +- [Weka Miundombinu ya Azure OpenAI](#weka-miundombinu-ya-azure-openai) +- [Endesha Programu Kwanza Mitaa](#endesha-programu-kwanza-mitaa) +- [Kutumia Programu](#kutumia-programu) + - [Mazungumzo Yasiyohifadhi Hali (Paneli ya Kushoto)](#mazungumzo-yasiyohifadhi-hali-paneli-ya-kushoto) + - [Mazungumzo Yanayohifadhi Hali (Paneli ya Kulia)](#mazungumzo-yanayohifadhi-hali-paneli-ya-kulia) +- [Hatua Zifuatazo](#hatua-zifuatazo) + +## Video ya Mwongozo + +Tazama kikao hiki cha moja kwa moja kinachoelezea jinsi ya kuanza na moduli hii: Kuanzia na LangChain4j - Kikao cha Moja kwa Moja ## Utajifunza Nini -Katika kuanza haraka, ulitumia Modeli za GitHub kutuma maelekezo, kutumia zana, kujenga bomba la RAG, na kupima mipaka ya usalama. Mionyesho hiyo ilionyesha nini kinawezekana — sasa tunabadilisha kuwa Azure OpenAI na GPT-5.2 na kuanza kujenga programu za mtindo wa uzalishaji. Moduli hii inazingatia AI ya mazungumzo inayokumbuka muktadha na kudumisha hali — dhana ambazo maonyesho ya kuanza haraka yalitumia nyuma ya pazia lakini hazikueleza. +Hii ni mwanzo wako na LangChain4j na Azure OpenAI. Tunaanza na misingi na kuanza kujenga programu za aina ya uzalishaji. Moduli hii inalenga AI ya mazungumzo inayokumbuka muktadha na kudumisha hali — dhana za msingi ambazo kila moduli inayofuata hujengwa juu yake. -Tutatumia GPT-5.2 ya Azure OpenAI katika mwongozo huu wote kwa sababu uwezo wake wa uelewa wa hali ya juu huifanya tabia za mifumo tofauti ionekane wazi zaidi. Utakapoongeza kumbukumbu, utaona tofauti kwa uwazi. Hii inafanya iwe rahisi kuelewa kile kila kipengele kinachochangia kwa programu yako. +Tutatumia GPT-5.2 ya Azure OpenAI katika mwongozo huu wote kwa sababu uwezo wake wa hali ya juu wa fikra huonyesha kwa uwazi tabia za mifumo tofauti. Unapoongeza kumbukumbu, utaona tofauti kwa wazi. Hii hufanya kuwa rahisi kuelewa kile kila kipengele kinachoongeza kwenye programu yako. -Utajenga programu moja inayothibitisha mifumo yote miwili: +Utajenga programu moja inayoonyesha mifumo yote miwili: -**Mazungumzo Yasiyo na Hali** - Kila ombi ni huru. Mfano huna kumbukumbu ya ujumbe wa awali. Huu ndio mfumo uliotumia katika kuanza haraka. +**Mazungumzo Yasiyohifadhi Hali** - Kila ombi ni huru. Mfano huna kumbukumbu ya ujumbe wa awali. Huu ni msingi rahisi wa kuanzia. -**Mazungumzo Yenye Hali** - Kila ombi linajumuisha historia ya mazungumzo. Mfano hudumisha muktadha katika mizunguko mingi. Hii ndio inahitajika kwa programu za uzalishaji. +**Mazungumzo Yanayohifadhi Hali** - Kila ombi linajumuisha historia ya mazungumzo. Mfano hudumisha muktadha kati ya mizunguko mingi. Hii ndiyo inahitajika katika programu za uzalishaji. -## Mambo ya Kuandaa +## Mahitaji ya Awali - Usajili wa Azure wenye ufikiaji wa Azure OpenAI -- Java 21, Maven 3.9+ +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Kumbuka:** Java, Maven, Azure CLI na Azure Developer CLI (azd) vimeshatanguliwa katika devcontainer iliyotolewa. +> **Kumbuka:** Java, Maven, Azure CLI na Azure Developer CLI (azd) vimeshatanguliwa kusanidiwa kwenye devcontainer uliotolewa. -> **Kumbuka:** Moduli hii inatumia GPT-5.2 kwenye Azure OpenAI. Uenezi umewekwa moja kwa moja kwa kutumia `azd up` - usibadilishe jina la mfano katika msimbo. +> **Kumbuka:** Moduli hii inatumia GPT-5.2 kwenye Azure OpenAI. Usanidi umewekwa moja kwa moja kupitia `azd up` - usibadilishe jina la mfano katika msimbo. -## Kuelewa Tatizo Kuu +## Kuelewa Shida Kuu -Modeli za lugha hazina hali. Kila simu ya API ni huru. Ukiwatumia "Jina langu ni John" kisha ukauliza "Jina langu ni nani?", mfano hauna wazo kwamba umejitambulisha. Hutendea kila ombi kana kwamba ndio mazungumzo yako ya kwanza kabisa. +Mifano ya lugha haina hali. Kila simu ya API ni huru. Ikiwa umetuma "Jina langu ni John" kisha ukauliza "Jina langu ni nani?", mfano haujui kuwa umejijulisha tu. Hutumia kila ombi kama vile ni mazungumzo yako ya kwanza kabisa. -Hii ni sawa kwa maswali rahisi na majibu lakini haifai kwa programu halisi. Bot za huduma kwa wateja zinahitaji kukumbuka ulichosema. Msaidizi wa kibinafsi anahitaji muktadha. Mazungumzo yoyote yenye mizunguko mingi yanahitaji kumbukumbu. +Hii ni sawa kwa maswali na majibu rahisi lakini haifai kwa programu halisi. Viboreshaji huduma kwa wateja vinahitaji kukumbuka ulicho walisema. Msaidizi wa binafsi unahitaji muktadha. Mazungumzo yenye mizunguko mingi yanahitaji kumbukumbu. -Dijagramu ifuatayo inaonyesha tofauti za mbinu hizo mbili — upande wa kushoto, simu huru inayosahau jina lako; upande wa kulia, simu yenye hali iliyo supported na ChatMemory inayokumbuka. +Mchoro ufuatao unaonyesha tofauti za mbinu mbili — kushoto, simu isiyo na hali inayosahau jina lako; kulia, simu yenye hali iliyojengwa na ChatMemory inayolikumbuka. -Mazungumzo Yasiyo na Hali dhidi ya Yenye Hali +Mazungumzo Yasiyo na Hali dhidi ya Mazungumzo Yanayohifadhi Hali -*Tofauti kati ya mazungumzo yasiyo na hali (simu huru) na yenye hali (yanayojua muktadha)* +*Tofauti kati ya mazungumzo yasiyo na hali (simu huru) na mazungumzo yanayohifadhi hali (yanaifahamu muktadha)* -## Kuelewa Vitoa-Kumbukumbu +## Kuelewa Vitambulisho (Tokens) -Kabla ya kuingia kwenye mazungumzo, ni muhimu kuelewa vitoa-kumbukumbu - vitengo vya msingi vya maandishi vinavyosindikwa na modeli za lugha: +Kabla ya kuingia katika mazungumzo, ni muhimu kuelewa vitambulisho - vitengo msingi vya maandishi ambavyo mifano ya lugha hufanya kazi navyo: -Maelezo ya Kitoa-Kumbukumbu +Maelezo ya Kitambulisho -*Mfano wa jinsi maandishi yanavyogawanywa kuwa vitoa-kumbukumbu - "Napenda AI!" kuwa vitengo 4 tofauti vya usindikaji* +*Mfano wa jinsi maandishi yanavyogawanywa katika vitambulisho - "Napenda AI!" zinazidi kuwa vitengo 4 tofauti vinavyotumika* -Vitoa-kumbukumbu ndio njia modeli za AI hupima na kusindika maandishi. Maneno, alama za uandishi, hata nafasi zinaweza kuwa vitoa-kumbukumbu. Mfano wako una kikomo cha vitoa-kumbukumbu ambacho kinaweza kusindika kwa wakati mmoja (400,000 kwa GPT-5.2, kwa vitoa-kumbukumbu hadi 272,000 kwa ingizo na 128,000 kwa matokeo). Kuelewa vitoa-kumbukumbu kunakusaidia kusimamia urefu wa mazungumzo na gharama. +Vitambulisho ni jinsi mifano ya AI inavyopima na kushughulikia maandishi. Maneno, alama za uandishi, na hata nafasi zinaweza kuwa vitambulisho. Mfano wako una kikomo cha idadi ya vitambulisho kinachoweza kushughulikiwa mara moja (400,000 kwa GPT-5.2, ambapo hadi vitambulisho 272,000 ni vya ingizo na 128,000 ni vya matokeo). Kuelewa vitambulisho kunasaidia kudhibiti urefu wa mazungumzo na gharama. ## Jinsi Kumbukumbu Inavyofanya Kazi -Kumbukumbu ya mazungumzo inatatua tatizo la kutokuwepo hali kwa kudumisha historia ya mazungumzo. Kabla ya kutuma ombi lako kwa mfano, mfumo huongeza ujumbe wa awali muhimu. Unapouliza "Jina langu ni nani?", mfumo hukutumia historia yote ya mazungumzo, ikiruhusu mfano kuona kwamba ulisema "Jina langu ni John" hapo awali. +Kumbukumbu ya mazungumzo hutatua shida ya kutokuwa na hali kwa kudumisha historia ya mazungumzo. Kabla ya kutuma ombi lako kwa mfano, mfumo huongeza ujumbe wa awali unaofaa. Ukimuuliza "Jina langu ni nani?", mfumo kwa kweli hutuma historia yote ya mazungumzo, kuruhusu mfano kuona ulisema awali "Jina langu ni John." -LangChain4j hutoa utekelezaji wa kumbukumbu unaofanya hili moja kwa moja. Unaamua ni jumbe ngapi kuzihifadhi na mfumo hushughulikia dirisha la muktadha. Dijagramu hapa chini inaonyesha jinsi MessageWindowChatMemory inavyodumisha dirisha linalopita la jumbe za hivi karibuni. +LangChain4j hutoa utekelezaji wa kumbukumbu unaoshughulikia hili moja kwa moja. Unachagua ni ujumbe wangapi kuhifadhi na mfumo hushughulikia dirisha la muktadha. Mchoro hapo chini unaonesha jinsi MessageWindowChatMemory hudumisha dirisha la ujazo wa ujumbe wa hivi karibuni. Dhana ya Dirisha la Kumbukumbu -*MessageWindowChatMemory inadumisha dirisha linalopita la jumbe za hivi karibuni, ikiachia zile za zamani kwa otomati* +*MessageWindowChatMemory hudumisha dirisha la kumpiga la ujumbe wa hivi karibuni, kwa moja kwa moja hutupa ujumbe wa zamani* ## Jinsi Hii Inavyotumia LangChain4j -Moduli hii inaendeleza kuanza haraka kwa kuunganisha Spring Boot na kuongeza kumbukumbu ya mazungumzo. Hapa ni jinsi vipengele vinaungana: +Moduli hii inaunganisha Spring Boot na kuongeza kumbukumbu ya mazungumzo. Hapa ni jinsi vipande vinavyounganika pamoja: **Mategemeo** - Ongeza maktaba mbili za LangChain4j: @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Mjenzi husoma sifa za kuingia kutoka kwa mazingira yaliyowekwa na `azd up`. Kuweka `baseUrl` kwa mwisho wa Azure kunafanya mteja wa OpenAI afanye kazi na Azure OpenAI. +Muundaji husoma vyeti kutoka kwa mabadiliko ya mazingira yaliyowekwa na `azd up`. Kuweka `baseUrl` kwenye endpoint yako ya Azure hufanya mteja wa OpenAI afanye kazi na Azure OpenAI. -**Kumbukumbu ya Mazungumzo** - Fuatilia historia ya mazungumzo kwa MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Kumbukumbu ya Mazungumzo** - Fuata historia ya mazungumzo na MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,21 +124,21 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Unda kumbukumbu na `withMaxMessages(10)` kuhifadhi jumbe 10 za mwisho. Ongeza jumbe za mtumiaji na AI kwa vifuniko vilivyoandikwa: `UserMessage.from(text)` na `AiMessage.from(text)`. Pata historia na `memory.messages()` na uitume kwa mfano. Huduma huhifadhi kumbukumbu tofauti kwa kila mazungumzo kwa ID yake, kuruhusu watumiaji wengi kuongea kwa wakati mmoja. +Tengeneza kumbukumbu na `withMaxMessages(10)` kuhifadhi ujumbe 10 za mwisho. Ongeza jumbe za mtumiaji na AI kwa vifunguo vilivyotambulika: `UserMessage.from(text)` na `AiMessage.from(text)`. Pata historia kwa `memory.messages()` na uitumie kwa mfano. Huduma huhifadhi kumbukumbu tofauti kwa kila kitambulisho cha mazungumzo, kuruhusu watumiaji wengi kuongea kwa wakati mmoja. > **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) na uliza: -> - "Jinsi gani MessageWindowChatMemory huchagua jumbe gani kuondoa wakati dirisha limejaa?" -> - "Je, naweza kutekeleza uhifadhi wa kumbukumbu wa kawaida kwa kutumia hifadhi ya data badala ya kumbukumbu ndani ya programu?" -> - "Ningepaswa kuongeza muhtasari ili kupunguza historia ya zamani ya mazungumzo?" +> - "MessageWindowChatMemory inaamua vipi ni ujumbe gani wachukue wakati dirisha limejaa?" +> - "Je, naweza kutekeleza kuhifadhi kumbukumbu maalum kutumia hifadhidata badala ya kumbukumbu ya ndani?" +> - "Nitafanya vipi kuongeza muhtasari kwa kushinikiza historia ya mazungumzo ya zamani?" -Kipengele cha mazungumzo yasiyo na hali hakiungi kumbukumbu kabisa - ni `chatModel.chat(prompt)` kama kuanza haraka. Kipengele cha mazungumzo yenye hali kinaongeza jumbe kwenye kumbukumbu, kinapata historia, na kinajumuisha muktadha na kila ombi. Sanidi mfano ule ule, mifumo tofauti. +Kipindi cha mazungumzo yasiyo na hali hakitumi kumbukumbu kabisa - ni `chatModel.chat(prompt)` kama ilivyo kwenye kuanza haraka. Kipindi cha hali pia kinaongeza jumbe kwenye kumbukumbu, kinapata historia, na kinajumuisha muktadha huu kwenye kila ombi. Sanidi mfano ule ule, mifumo tofauti. -## Tangaza Miundombinu ya Azure OpenAI +## Weka Miundombinu ya Azure OpenAI **Bash:** ```bash cd 01-introduction -azd up # Chagua usajili na eneo (eastus2 inashauriwa) +azd up # Chagua usajili na eneo (eastus2 inapendekezwa) ``` **PowerShell:** @@ -147,16 +147,16 @@ cd 01-introduction azd up # Chagua usajili na eneo (eastus2 inapendekezwa) ``` -> **Kumbuka:** Ikiwa unakutana na kosa la muda kukamilika (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), tumia tena `azd up`. Rasilimali za Azure zinaweza bado kuandaliwa nyuma, na jaribio la pili huruhusu uenezi kukamilika mara rasilimali zifikie hali ya mwisho. +> **Kumbuka:** Ikiwa unakutana na kosa la muda (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), endesha tena tu `azd up`. Rasilimali za Azure bado zinaweza kuwa zinaandaliwa nyuma, na jaribu tena huruhusu utekesaji kukamilika mara rasilimali zifikie hali ya mwisho. Hii itafanya: -1. Kutangaza rasilimali ya Azure OpenAI pamoja na modeli za GPT-5.2 na text-embedding-3-small -2. Kutengeneza faili `.env` moja kwa moja kwenye mizizi ya mradi na sifa -3. Kuweka mazingira yote yanayohitajika +1. Kuweka rasilimali ya Azure OpenAI na mifano ya GPT-5.2 na text-embedding-3-small +2. Kuunda faili la `.env` moja kwa moja kwenye mizizi ya mradi lenye vyeti +3. Kuweka mabadiliko yote ya mazingira yanayohitajika -**Kuna shida za uenezi?** Angalia [README ya Miundombinu](infra/README.md) kwa maelezo ya kutatua matatizo ikiwa ni pamoja na migongano ya majina ya viwanja, hatua za uenezi wa mikono kwenye Azure Portal, na mwongozo wa usanidi wa modeli. +**Kuna matatizo ya utekesaji?** Angalia [Infrastructure README](infra/README.md) kwa maelezo ya kutatua matatizo ikiwa ni pamoja na migongano ya majina ya subdomain, hatua za kuweka kwa mkono Azure Portal, na mwongozo wa usanidi wa mfano. -**Thibitisha uenezi ulifanikiwa:** +**Thibitisha utekesaji umefanikiwa:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Inapaswa kuonyesha AZURE_OPENAI_ENDPOINT, API_KEY, n.k. Get-Content ..\.env # Inapaswa kuonyesha AZURE_OPENAI_ENDPOINT, API_KEY, n.k. ``` -> **Kumbuka:** Amri `azd up` hutengeneza faili `.env` moja kwa moja. Ikiwa unahitaji kuiboresha baadaye, unaweza kuhariri faili `.env` kwa mikono au kuitengeneza upya kwa kuendesha: +> **Kumbuka:** Amri ya `azd up` hutoa faili la `.env` moja kwa moja. Ikiwa unahitaji kuiboresha baadaye, unaweza kuhariri faili la `.env` mwenyewe au kuunda tena kwa kuendesha: > > **Bash:** > ```bash @@ -182,11 +182,11 @@ Get-Content ..\.env # Inapaswa kuonyesha AZURE_OPENAI_ENDPOINT, API_KEY, n.k. > .\.azd-env.ps1 > ``` -## Endesha Programu Hapa Mkononi +## Endesha Programu Kwanza Mitaa -**Thibitisha uenezi:** +**Thibitisha utekesaji:** -Hakikisha faili `.env` ipo kwenye saraka ya mizizi na sifa za Azure. Endesha hii kutoka kwenye saraka ya moduli (`01-introduction/`): +Hakiki kuwa faili la `.env` lipo kwenye saraka ya mizizi na vyeti vya Azure. Endesha hili kutoka saraka ya moduli (`01-introduction/`): **Bash:** ```bash @@ -202,37 +202,37 @@ Get-Content ..\.env # Inapaswa kuonyesha AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOY **Chaguo 1: Kutumia Spring Boot Dashboard (Inapendekezwa kwa watumiaji wa VS Code)** -Dev container ina jopo la Spring Boot Dashboard, linalotoa kiolesura cha kuona kusimamia programu zote za Spring Boot. Unaweza kuipata kwenye Bar ya Shughuli upande wa kushoto wa VS Code (tafuta ikoni ya Spring Boot). +Dev container inaongezewa ugani wa Spring Boot Dashboard, unaotoa interface ya kuona kusimamia programu zote za Spring Boot. Unaweza kuipata kwenye Bar ya Shughuli upande wa kushoto wa VS Code (tazama sakata la Spring Boot). Kutoka Spring Boot Dashboard, unaweza: -- Kuona programu zote za Spring Boot zilizopo kwa nafasi ya kazi -- Kuanza/kukomesha programu kwa bonyeza moja -- Kutazama kumbukumbu za programu moja kwa moja -- Kufuatilia hali ya programu +- Kuona programu zote za Spring Boot zilizopo kwenye mazingira ya kazi +- Anzisha/zuia programu kwa bonyeza moja +- Tazama kumbukumbu za programu kwa wakati halisi +- Angalia hali ya programu -Bonyeza tu kitufe cha kuanzisha karibu na "introduction" kuanza moduli hii, au anzisha moduli zote kwa wakati mmoja. +Bonyeza kitufe cha kuanza upande wa "introduction" kuanzisha moduli hii, au anzisha moduli zote kwa pamoja. -Spring Boot Dashboard +Dashibodi ya Spring Boot -*Jopo la Spring Boot katika VS Code — anzisha, simamia, na fuatilia moduli zote kutoka mahali pamoja* +*Dashibodi ya Spring Boot katika VS Code — anzisha, zuia, na fuatilia moduli zote kutoka sehemu moja* **Chaguo 2: Kutumia skiripti za shell** -Anzisha programu zote za wavuti (moduli 01-04): +Anzisha programu za wavuti zote (moduli 01-04): **Bash:** ```bash -cd .. # Kutoka kwenye saraka ya mizizi +cd .. # Kutoka kwenye saraka kuu ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Kutoka kwa saraka kuu +cd .. # Kutoka kwa saraka ya mzizi .\start-all.ps1 ``` -Au anzisha moduli hii pekee: +Au anzisha moduli hii tu: **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Skiripti zote huchukua moja kwa moja mazingira kutoka kwenye faili `.env` ya mizizi na hutatua JARs kama hazipo. +Zote skiripti huchukua mabadiliko ya mazingira kutoka kwenye faili la `.env` la mizizi na husanidi JARs kama hazipo. -> **Kumbuka:** Ikiwa unapendelea kujenga moduli zote kwa mkono kabla ya kuanzisha: +> **Kumbuka:** Ikiwa ungependa kujenga moduli zote mwenyewe kabla ya kuanza: > > **Bash:** > ```bash @@ -264,11 +264,11 @@ Skiripti zote huchukua moja kwa moja mazingira kutoka kwenye faili `.env` ya miz Fungua http://localhost:8080 kwenye kivinjari chako. -**Kusimamisha:** +**Kusitisha:** **Bash:** ```bash -./stop.sh # Hii moduli tu +./stop.sh # Moduli hii tu # Au cd .. && ./stop-all.sh # Moduli zote ``` @@ -282,41 +282,41 @@ cd ..; .\stop-all.ps1 # Moduli zote ## Kutumia Programu -Programu inatoa kiolesura cha wavuti pamoja na utekelezaji wa mazungumzo mawili pembeni kwa pembeni. +Programu hutoa interface ya wavuti wenye utekelezaji wa mazungumzo mawili upande kwa upande. -Skrini ya Nyumbani ya Programu +Skrini ya Mbele ya Programu -*Jopo linavyoonyesha Chaguo la Mazungumzo Rahisi (yasiyo na hali) na Mazungumzo ya Hali (yenye hali)* +*Dashibodi inaonyesha chaguzi za Mazungumzo Rahisi (yasiyo na hali) na Mazungumzo ya Mazungumzo (yanayohifadhi hali)* -### Mazungumzo Yasiyo na Hali (Paneli ya Kushoto) +### Mazungumzo Yasiyohifadhi Hali (Paneli ya Kushoto) -Jaribu hii kwanza. Uliza "Jina langu ni John" kisha mara moja uliza "Jina langu ni nani?" Mfano hautakumbuka kwa sababu kila ujumbe ni huru. Hii inaonyesha tatizo kuu la kuunganishwa kwa modeli ya lugha ya msingi - hakuna muktadha wa mazungumzo. +Jaribu haya kwanza. Uliza "Jina langu ni John" kisha mara moja uliza "Jina langu ni nani?" Mfano hautakumbuka kwa sababu kila ujumbe ni huru. Hii inaonyesha shida kuu ya ushirikiano wa mifano ya lugha ya msingi - hakuna muktadha wa mazungumzo. -Mionyesho ya Mazungumzo Yasiyo na Hali +Onyesho la Mazungumzo Yasiyo na Hali *AI haikumbuki jina lako kutoka ujumbe wa awali* -### Mazungumzo Yenye Hali (Paneli ya Kulia) +### Mazungumzo Yanayohifadhi Hali (Paneli ya Kulia) -Sasa jaribu mfuatano uleule hapa. Uliza "Jina langu ni John" kisha "Jina langu ni nani?" Muda huu inakumbuka. Tofauti ni MessageWindowChatMemory - inadumisha historia ya mazungumzo na inaanzisha hilo muktadha na kila ombi. Hivi ndivyo AI za mazungumzo za uzalishaji hufanya kazi. +Sasa jaribu mfuatano huo hapa. Uliza "Jina langu ni John" kisha "Jina langu ni nani?" Wakati huu inakumbuka. Tofauti ni MessageWindowChatMemory - hudumisha historia ya mazungumzo na kuijumuisha na kila ombi. Hii ndiyo AI ya mazungumzo ya uzalishaji inavyofanya kazi. -Mionyesho ya Mazungumzo Yenye Hali +Onyesho la Mazungumzo Yanayohifadhi Hali -*AI inakumbuka jina lako kutoka awali katika mazungumzo* +*AI inakumbuka jina lako kutoka mazungumzo ya awali* -Paneli zote mbili zinatumia mfano ule ule wa GPT-5.2. Tofauti pekee ni kumbukumbu. Hii inaonyesha wazi kile kumbukumbu inachochangia kwa programu yako na kwanini ni muhimu kwa matumizi halisi. +Pande zote mbili zinatumia mfano ule ule wa GPT-5.2. Tofauti pekee ni kumbukumbu. Hii inaonyesha wazi kile kumbukumbu inachoongeza kwenye programu yako na kwa nini ni muhimu kwa matumizi halisi. ## Hatua Zifuatazo -**Moduli Ifuatayo:** [02-prompt-engineering - Uhandisi wa Maelekezo na GPT-5.2](../02-prompt-engineering/README.md) +**Moduli Ifuatayo:** [02-prompt-engineering - Uhandisi wa Prompt na GPT-5.2](../02-prompt-engineering/README.md) --- -**Uelekezaji:** [← Zamani: Moduli 00 - Kuanza Haraka](../00-quick-start/README.md) | [Rudi Mma](../README.md) | [Ifuatayo: Moduli 02 - Uhandisi wa Maelekezo →](../02-prompt-engineering/README.md) +**Uelekeo:** [← Rudi Kwenye Kuu](../README.md) | [Ifuatayo: Moduli 02 - Uhandisi wa Prompt →](../02-prompt-engineering/README.md) --- -**Tangazo la Kukataa**: -Nyaraka hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kuhakikisha usahihi, tafadhali fahamu kuwa tafsiri za moja kwa moja zinaweza kuwa na makosa au ukosefu wa usahihi. Nyaraka ya asili katika lugha yake ya asili inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa habari muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inashauriwa. Hatuna lawama kwa kutokuelewana au tafsiri kubaya kutokea kutokana na matumizi ya tafsiri hii. +**Kionyozo**: +Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake halisi inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inapendekezwa. Hatutojibu kwa kuelewa vibaya au tafsiri potofu zinazotokea kutokana na matumizi ya tafsiri hii. \ No newline at end of file diff --git a/translations/sw/02-prompt-engineering/README.md b/translations/sw/02-prompt-engineering/README.md index bffcee721..93cab4f5e 100644 --- a/translations/sw/02-prompt-engineering/README.md +++ b/translations/sw/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ -# Moduli 02: Uhandisi wa Maagizo na GPT-5.2 - -## Muhtasari wa Maudhui - -- [Video ya Maelezo](../../../02-prompt-engineering) -- [Utajifunza Nini](../../../02-prompt-engineering) -- [Mahitaji ya Msingi](../../../02-prompt-engineering) -- [Kuelewa Uhandisi wa Maagizo](../../../02-prompt-engineering) -- [Misingi ya Uhandisi wa Maagizo](../../../02-prompt-engineering) - - [Uagizo wa Zero-Shot](../../../02-prompt-engineering) - - [Uagizo wa Few-Shot](../../../02-prompt-engineering) - - [Mnyororo wa Mawazo](../../../02-prompt-engineering) - - [Uagizo wa Kutoa Nafasi](../../../02-prompt-engineering) - - [Mifano ya Maagizo](../../../02-prompt-engineering) -- [Mifumo ya Juu Zaidi](../../../02-prompt-engineering) -- [Endesha Programu](../../../02-prompt-engineering) -- [Picha za Skrini za Programu](../../../02-prompt-engineering) -- [Kuchunguza Mifumo](../../../02-prompt-engineering) - - [Kujiamini Kidogo dhidi ya Kujiamini Kuu](../../../02-prompt-engineering) - - [Utekelezaji wa Kazi (Utangulizi wa Zana)](../../../02-prompt-engineering) - - [Msimbo unaojitathmini](../../../02-prompt-engineering) - - [Uchambuzi uliopangwa](../../../02-prompt-engineering) - - [Mazungumzo ya Mzunguko Mwingi](../../../02-prompt-engineering) - - [Sababu Hatua kwa Hatua](../../../02-prompt-engineering) - - [Matokeo Yaliyodhibitiwa](../../../02-prompt-engineering) -- [Kile Unachojifunza Kweli](../../../02-prompt-engineering) -- [Hatua Zifuatazo](../../../02-prompt-engineering) - -## Video ya Maelezo +# Moduli 02: Uhandisi wa Maelekezo kwa GPT-5.2 + +## Jedwali la Maudhui + +- [Maonyesho ya Video](#maonyesho-ya-video) +- [Utajifunza Nini](#utajifunza-nini) +- [Mahitaji ya Awali](#mahitaji-ya-awali) +- [Kuelewa Uhandisi wa Maelekezo](#kuelewa-uhandisi-wa-maelekezo) +- [Misingi ya Uhandisi wa Maelekezo](#misingi-ya-uhandisi-wa-maelekezo) + - [Maelekezo Bila Mfano (Zero-Shot Prompting)](#maelekezo-bila-mfano-zero-shot-prompting) + - [Maelekezo Chache za Mfano (Few-Shot Prompting)](#maelekezo-chache-za-mfano-few-shot-prompting) + - [Mnyororo wa Fikra (Chain of Thought)](#mnyororo-wa-fikra-chain-of-thought) + - [Maelekezo kwa Kuingia Kazi (Role-Based Prompting)](#maelekezo-kwa-kuingia-kazi-role-based-prompting) + - [Templeti za Maelekezo (Prompt Templates)](#templeti-za-maelekezo-prompt-templates) +- [Mifumo ya Juu Zaidi](#mifumo-ya-juu-zaidi) +- [Endesha Programu](#endesha-programu) +- [Picha za Skrini za Programu](#picha-za-programu) +- [Kuchunguza Mifumo](#kuchunguza-mifumo) + - [Shauku Ndogo vs Shauku Kubwa](#kutaka-kidogo-dhidi-ya-kutaka-kurefu) + - [Utekelezaji wa Kazi (Maelezo ya Zana)](#utekesaji-wa-kazi-mwongozo-wa-zana) + - [Kanuni Zinazojiangalia](#msimbo-unaojitathmini) + - [Uchambuzi wa Muundo](#uchambuzi-ulio-jengwa) + - [Mazungumzo ya Mzunguko wa Nyingi](#mazungumzo-ya-mara-nyingi) + - [Ufahamu Hatua kwa Hatua](#fikra-hatua-kwa-hatua) + - [Matokeo Yaliyodhibitiwa](#matokeo-yaliyopigwa-mipaka) +- [Unajifunza Kawaida Nini](#unachojifunza-kweli) +- [Hatua Zinazofuata](#hatua-zifuatazo) + +## Maonyesho ya Video Tazama kikao hiki cha moja kwa moja kinachoelezea jinsi ya kuanza na moduli hii: -Uhandisi wa Maagizo na LangChain4j - Kikao cha Moja kwa Moja +Prompt Engineering with LangChain4j - Live Session ## Utajifunza Nini -Mchoro ufuatao unaonesha muhtasari wa mada kuu na ujuzi utakaojifunza katika moduli hii — kutoka mbinu za kusafisha maagizo hadi mtiririko wa hatua kwa hatua utakaoifuata. +Mchoro ufuatao unatoa muhtasari wa mada muhimu na ujuzi utakaoutengeneza katika moduli hii — kuanzia mbinu za kusafisha maelekezo hadi mtiririko wa hatua kwa hatua utakaoifuata. -Utajifunza Nini +What You'll Learn -Katika moduli zilizopita, ulichunguza mwingiliano wa msingi wa LangChain4j na Modeli za GitHub na ukaona jinsi kumbukumbu inavyorahisisha AI ya mazungumzo na Azure OpenAI. Sasa tutaangazia jinsi unavyouliza maswali — maagizo yenyewe — ukitumia GPT-5.2 wa Azure OpenAI. Jinsi unavyoandika maagizo yako huathiri kwa kiwango kikubwa ubora wa majibu unayopata. Tunaanza kwa mapitio ya mbinu za msingi za maagizo, kisha tunaingia kwenye mifumo nane ya juu inayotumia uwezo kamili wa GPT-5.2. +Katika moduli iliyopita, uliyona jinsi kumbukumbu inavyowawezesha AI ya mazungumzo kwa Azure OpenAI. Sasa tutazingatia jinsi unavyouliza maswali — maelekezo yenyewe — ukitumia GPT-5.2 ya Azure OpenAI. Jinsi unavyopanga maelekezo yako huathiri sana ubora wa majibu unayopata. Tunaanza na muhtasari wa mbinu za msingi za kutoa maelekezo, kisha tunaingia katika mifumo nane ya juu zaidi inayochukua faida kamili ya uwezo wa GPT-5.2. -Tutatumia GPT-5.2 kwa sababu inaleta udhibiti wa sababu - unaweza kuambia modeli ni kiasi gani cha kufikiria kufanywa kabla ya kujibu. Hii inafanya mbinu tofauti za maagizo ziwe wazi zaidi na inakusaidia kuelewa wapi unapaswa kutumia kila njia. Pia tutafaidika na vikwazo vidogo vya Azure kwa GPT-5.2 ikilinganishwa na Modeli za GitHub. +Tutatumia GPT-5.2 kwa sababu inatambulisha udhibiti wa fikra - unaweza kusema kwa mfano kiasi cha kufikiri anachotakiwa kabla ya kutoa jibu. Hii inafanya mbinu tofauti za kutoa maelekezo kuwa wazi zaidi na kukusaidia kuelewa lini utumie kila mbinu. -## Mahitaji ya Msingi +## Mahitaji ya Awali -- Imekamilika Moduli 01 (Rasilimali za Azure OpenAI zimetumika) -- Faili `.env` katika saraka kuu yenye taarifa za Azure (iliundwa na `azd up` katika Moduli 01) +- Kumaliza Moduli 01 (Rasilimali za Azure OpenAI zimetangazwa) +- Faili `.env` kwenye saraka kuu ikiwa na sifa za Azure (imeundwa na `azd up` katika Moduli 01) -> **Kumbuka:** Kama hujakamilisha Moduli 01, fuata maelekezo ya utekelezaji hapo kwanza. +> **Kumbuka:** Ikiwa hukumalizia Moduli 01, tafadhali fuata maelekezo ya utekelezaji hapo kwanza. -## Kuelewa Uhandisi wa Maagizo +## Kuelewa Uhandisi wa Maelekezo -Kwa msingi wake, uhandisi wa maagizo ni tofauti kati ya maelekezo yasiyoeleweka na yale yanayokuwa makini, kama inavyoonyeshwa kwenye mfano hapa chini. +Kwa msingi wake, uhandisi wa maelekezo ni tofauti kati ya maelekezo yasiyoeleweka na maelekezo sahihi, kama inavyoonyeshwa katika kulinganisha hapa chini. -Nini Uhandisi wa Maagizo? +What is Prompt Engineering? -Uhandisi wa maagizo ni kuhusu kubuni maandishi ya kuingiza ambayo yanakupatia matokeo unayohitaji kwa kufuata. Sio tu kuuliza maswali - ni jinsi ya kupanga maombi ili modeli iaelewe hasa unachotaka na jinsi ya kutoa majibu hayo. +Uhandisi wa maelekezo ni kuhusu kubuni maandishi ya kuingiza ambayo mara zote yanakupa matokeo unayohitaji. Sio tu kuuliza maswali - bali ni kupanga maombi ili mfano uelewe hasa unachotaka na jinsi ya kutoa. -Fikiria kama unatoa maagizo kwa mfanyakazi mwenzako. "Rekebisha hitilafu" ni maelekezo yasiyo wazi. "Rekebisha hitilafu ya null pointer katika UserService.java mstari wa 45 kwa kuongeza ukaguzi wa null" ni maelekezo maalum. Modeli za lugha zinavyofanya kazi ni hivyo hivyo - umakini na muundo ni muhimu. +Fikiria kama kutoa maelekezo kwa mwenzako kazini. "Tengeneza hitilafu" ni maelekezo ya jumla. "Tengeneza hitilafu ya kielekezi isiyohamishika katika UserService.java mstari wa 45 kwa kuongeza ukaguzi wa null" ni maelekezo maalum. Mifano ya lugha hufanya kazi kwa njia ile ile - maelezo maalum na muundo ni muhimu. -Mchoro hapa chini unaonyesha jinsi LangChain4j inavyoweka picha hii wazi — ukiunganisha mifumo yako ya maagizo na modeli kupitia vipengele vya SystemMessage na UserMessage. +Mchoro hapa chini unaonyesha jinsi LangChain4j inavyobebwa tena picha hii — kuunganisha mifumo yako ya maelekezo na mfano kupitia vipengele vya SystemMessage na UserMessage. -Jinsi LangChain4j Inavyofaa +How LangChain4j Fits -LangChain4j hutoa miundombinu — muunganisho wa modeli, kumbukumbu, na aina za ujumbe — wakati mifumo ya maagizo ni maandishi yaliyopangwa kwa makini unayotuma kupitia miundombinu hiyo. Viunganishi muhimu ni `SystemMessage` (ambayo inaweka tabia na nafasi ya AI) na `UserMessage` (ambayo huleta ombi lako halisi). +LangChain4j hutoa miundombinu — unganisho la mfano, kumbukumbu, na aina za ujumbe — wakati mifumo ya maelekezo ni tu maandishi yaliyopangwa kwa makini unayotuma kupitia miundombinu hiyo. Vipengele vikuu ni `SystemMessage` (ambayo inaweka tabia na jukumu la AI) na `UserMessage` (ambayo hubeba ombi lako halisi). -## Misingi ya Uhandisi wa Maagizo +## Misingi ya Uhandisi wa Maelekezo -Mbinu tano kuu zilizoonyeshwa hapa chini ni msingi wa uhandisi wa maagizo yenye ufanisi. Kila moja inashughulikia kipengele tofauti cha jinsi unavyozungumza na modeli za lugha. +Mbinu tano kuu zilizoonyeshwa hapa chini zinaweka msingi wa uhandisi wa maelekezo mzuri. Kila moja inashughulikia kipengele tofauti cha jinsi unavyozungumza na mifano ya lugha. -Muhtasari wa Mifumo Tano ya Uhandisi wa Maagizo +Five Prompt Engineering Patterns Overview -Kabla ya kuingia kwenye mifumo ya juu katika moduli hii, tuchunguze mbinu tano za msingi za maagizo. Hizi ni vipengele vya msingi ambavyo kila mhandisi wa maagizo anapaswa kujua. Ikiwa tayari umefanya kazi kupitia [moduli ya Kuanzisha Haraka](../00-quick-start/README.md#2-prompt-patterns), umeona hizi zikitumika — hapa kuna mfumo wa dhana nyuma yao. +Kabla ya kuingia katika mifumo ya juu zaidi katika moduli hii, tuchunguze mbinu tano za msingi za kutoa maelekezo. Hizi ni vipande vya msingi ambavyo kila mhandisi wa maelekezo anapaswa kujua. -### Uagizo wa Zero-Shot +### Maelekezo Bila Mfano (Zero-Shot Prompting) -Mbinu rahisi kabisa: toa maagizo ya moja kwa moja kwa modeli bila mifano. Modeli hutegemea kabisa mafunzo yake kuelewa na kutekeleza kazi. Hii hufanya kazi vizuri kwa maombi rahisi ambapo tabia inayotarajiwa ni dhahiri. +Njia rahisi zaidi: toa maagizo ya moja kwa moja kwa mfano bila mifano. Mfano hutegemea mafunzo yake kabisa kuelewa na kutekeleza kazi. Hii hufanya kazi vizuri kwa maombi rahisi ambapo tabia inayotarajiwa ni dhahiri. -Uagizo wa Zero-Shot +Zero-Shot Prompting -*Maagizo ya moja kwa moja bila mifano — modeli husisitiza kazi kutoka kwa maagizo pekee* +*Maagizo ya moja kwa moja bila mifano — mfano hutambua kazi kutoka kwa maagizo pekee* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Jibu: "Chanya" ``` -**Linapopaswa kutumika:** Uainishaji rahisi, maswali ya moja kwa moja, tafsiri, au kazi yoyote modeli inaweza kushughulikia bila mwongozo zaidi. +**Unapotumia:** Uainishaji rahisi, maswali ya moja kwa moja, tafsiri, au kazi yoyote ambayo mfano unaweza kushughulikia bila mwongozo zaidi. -### Uagizo wa Few-Shot +### Maelekezo Chache za Mfano (Few-Shot Prompting) -Toa mifano inayoonyesha muundo unayotaka modeli ifuate. Modeli hujifunza muundo wa pembejeo na matokeo kutokana na mifano yako na kuitumia kwa pembejeo mpya. Hii huongeza uthabiti kwa kazi ambapo muundo unaotakiwa au tabia si wazi. +Toa mifano inayoonyesha muundo unaotaka mfano ufuate. Mfano hujifunza muundo wa kuingiza-na-kutoa kutoka kwa mifano yako na kuutumia kwa maingizo mapya. Hii huongeza utulivu kwa kazi ambapo muundo unaotakiwa au tabia si ya wazi. -Uagizo wa Few-Shot +Few-Shot Prompting -*Kujifunza kutoka kwa mifano — modeli hutambua muundo na kuitumia kwa pembejeo mpya* +*Kujifunza kutoka kwa mifano — mfano hutambua mwelekeo na kuutumia kwa maingizo mapya* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Linapopaswa kutumika:** Uainishaji wa kawaida, miundo thabiti, kazi maalum za kikoa, au wakati matokeo ya zero-shot hayako thabiti. +**Unapotumia:** Uainishaji maalum, muundo thabiti, kazi za kipekee za eneo fulani, au wakati matokeo ya zero-shot hayapo thabiti. -### Mnyororo wa Mawazo +### Mnyororo wa Fikra (Chain of Thought) -Muulize modeli ionyeshe mchakato wake wa kufikiria hatua kwa hatua. Badala ya kuruka hadi jibu moja kwa moja, modeli hugawanya tatizo na kufanya kazi kupitia kila sehemu kwa uwazi. Hii huongeza usahihi kwa hesabu, mantiki, na kazi za kufikiria hatua nyingi. +Muulize mfano aonyeshe fikra zake hatua kwa hatua. Badala ya kusogea moja kwa moja kwenye jibu, mfano huweka tatizo kwa vipande na kufanyia kazi kila sehemu kwa uwazi. Hii huongeza usahihi katika hisabati, mantiki, na kazi za kutafakari hatua kwa hatua. -Uagizo wa Mnyororo wa Mawazo +Chain of Thought Prompting -*Sababu hatua kwa hatua — kugawanya matatizo magumu katika hatua wazi za mantiki* +*Ufahamu hatua kwa hatua — kugawanya matatizo magumu katika hatua za mantiki wazi* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Mfano unaonyesha: 15 - 8 = 7, kisha 7 + 12 = 19 apple +// Mfano unaonyesha: 15 - 8 = 7, kisha 7 + 12 = 19 tufaha ``` -**Linapopaswa kutumika:** Matatizo ya Hisabati, fumbo za mantiki, kuchangua kosa, au kazi yoyote ambapo kuonyesha mchakato wa sababu huongeza usahihi na kuaminiwa. +**Unapotumia:** Matatizo ya hisabati, mafumbo ya mantiki, utatuzi hitilafu, au kazi yoyote ambapo kuonyesha mchakato wa fikra huongeza usahihi na imani. -### Uagizo wa Kutoa Nafasi +### Maelekezo kwa Kuingia Kazi (Role-Based Prompting) -Weka tabia au nafasi kwa AI kabla ya kuuliza swali lako. Hii hutoa muktadha unaoathiri tone, kina, na mkazo wa jibu. "Mbunifu wa programu" hutoa ushauri tofauti kuliko "mwanafunzi mdogo" au "mkaguzi wa usalama". +Weka utu au jukumu la AI kabla ya kuuliza swali lako. Hii hutoa muktadha unaounda mtindo, kina, na msisitizo wa jibu. "Mchora programu" hutoa ushauri tofauti na "mwanafunzi mdogo" au "mchuja usalama". -Uagizo wa Kutoa Nafasi +Role-Based Prompting -*Kuweka muktadha na nafasi — swali moja hupata majibu tofauti kulingana na nafasi iliyotolewa* +*Kuweka muktadha na utu — swali lile hutoa majibu tofauti kulingana na jukumu lililowekwa* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Linapopaswa kutumika:** Ukaguzi wa msimbo, ufundishaji, uchambuzi maalum wa kikoa, au wakati unahitaji majibu yaliyojaa kwa kiwango fulani cha utaalamu au mtazamo. +**Unapotumia:** Mapitio ya msimbo, ushauri, uchambuzi maalum wa eneo fulani, au wakati unahitaji majibu yaliyobinafsishwa kwa kiwango fulani cha utaalamu au mtazamo. -### Mifano ya Maagizo +### Templeti za Maelekezo (Prompt Templates) -Tengeneza maagizo yanayotumika tena yenye nafasi za kuhifadhi tofauti. Badala ya kuandika agizo jipya kila wakati, fafanua mfano mara moja na ujaze maadili tofauti. Darasa la LangChain4j `PromptTemplate` hufanya hili kuwa rahisi kwa sintaksia ya `{{variable}}`. +Tengeneza maelekezo yanayoweza kutumika tena yenye mahali pa kuweka mabadiliko. Badala ya kuandika maelekezo mapya kila wakati, tengeneza templeti mara moja na jaza thamani tofauti. Darasa la LangChain4j la `PromptTemplate` linaifanya hii iwe rahisi kwa sintaksia ya `{{variable}}`. -Mifano ya Maagizo +Prompt Templates -*Maagizo yanayotumika tena yenye nafasi za kuhifadhi — mfano mmoja, matumizi mengi* +*Maelekezo yanayoweza kutumika tena yenye sehemu za mabadiliko — templeti moja, matumizi mengi* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Linapopaswa kutumika:** Maswali yanayoarudiwa na pembejeo tofauti, usindikaji wa kundi, ujenzi wa mitiririko ya AI inayotumika tena, au hali yoyote ambapo muundo wa agizo hubaki sawa lakini data hubadilika. +**Unapotumia:** Maswali yanayorudiwa yenye maingizo tofauti, usindikaji wa wingi, kujenga mitiririko ya AI inayoweza kutumika tena, au hali yoyote ambapo muundo wa maelekezo hubaki sawa lakini data hubadilika. --- -Misingi hii mitano inakupa zana thabiti kwa kazi nyingi za maagizo. Mengine ya moduli hii hujengwa juu yake na **mifumo nane ya juu zaidi** inayotumia udhibiti wa sababu wa GPT-5.2, kujitathmini, na uwezo wa kutoa matokeo yaliyopangwa. +Misingi hii mitano inakupa zana thabiti kwa kazi nyingi za kutoa maelekezo. Sehemu nyingine ya moduli hii inajenga juu yao kwa **mifumo nane ya juu zaidi** inayotumia udhibiti wa fikra wa GPT-5.2, kujitathmini, na uwezo wa kutoa matokeo yaliyopangwa. ## Mifumo ya Juu Zaidi -Baada ya msingi kufunikwa, tuingie katika mifumo nane ya juu zaidi inayofanya moduli hii kuwa ya kipekee. Sio matatizo yote yanahitaji njia moja. Baadhi ya maswali yanahitaji majibu ya haraka, mengine yanahitaji kufikiri kwa kina. Baadhi yanahitaji sababu inayoonekana, mengine yanahitaji tu matokeo. Kila mfumo hapa chini umeboreshwa kwa hali tofauti — na udhibiti wa sababu wa GPT-5.2 hufanya tofauti hizi zionekane zaidi. +Baada ya kufunika misingi, tunahamia kwenye mifumo nane ya juu zaidi inayofanya moduli hii kuwa ya kipekee. Siyo matatizo yote yanayohitaji mbinu sawa. Maswali mengine yanahitaji majibu ya haraka, mengine yanahitaji fikra za kina. Baadhi yanahitaji ufafanuzi wa fikra, mengine yanahitaji tu matokeo. Kila mfumo hapa chini umeboreshwa kwa hali tofauti — na udhibiti wa fikra wa GPT-5.2 unafanya tofauti hizi kuwa wazi zaidi. -Mifumo Nane ya Uhandisi wa Maagizo +Eight Prompting Patterns -*Muhtasari wa mifumo nane ya uhandisi wa maagizo na matumizi yake* +*Muhtasari wa mifumo nane ya uhandisi wa maelekezo na matumizi yake* -GPT-5.2 inaongeza kipengele kingine kwa mifumo hii: *udhibiti wa sababu*. Shuka hapa chini unaonyesha jinsi unavyoweza kurekebisha jitihada za kufikiri za modeli — kutoka majibu ya haraka, ya moja kwa moja hadi uchambuzi wa kina na wa kina. +GPT-5.2 inaongeza kipengele kingine kwa mifumo hii: *udhibiti wa fikra*. Kipimo hapo chini kinaonyesha jinsi unavyoweza kurekebisha juhudi za kufikiri za mfano — kutoka majibu ya haraka na ya moja kwa moja hadi uchambuzi wa kina na wa kina. -Udhibiti wa Sababu na GPT-5.2 +Reasoning Control with GPT-5.2 -*Udhibiti wa sababu wa GPT-5.2 unakuwezesha kubainisha kiasi cha kufikiri modeli inapaswa kufanya — kutoka majibu ya haraka ya moja kwa moja hadi uchunguzi wa kina* +*Udhibiti wa fikra wa GPT-5.2 hukuruhusu kubainisha kiasi cha fikra ambacho mfano unapaswa kufanya — kutoka majibu ya haraka ya moja kwa moja hadi uchunguzi wa kina* -**Kujiamini Kidogo (Haraka & Lengo) -** Kwa maswali rahisi ambapo unataka majibu ya haraka na ya moja kwa moja. Modeli hufanya sababu kidogo sana - hatua 2 pekee. Tumia hii kwa hesabu, utafutaji, au maswali rahisi. +**Shauku Ndogo (Haraka na Iliyolenga)** - Kwa maswali rahisi ambapo unataka majibu ya haraka na ya moja kwa moja. Mfano hufanya fikra kidogo - hatua 2 za juu kabisa. Tumia hii kwa mahesabu, tafutaji, au maswali rahisi. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Chunguza na GitHub Copilot:** Fungua [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) na uliza: -> - "Tofauti kati ya mifumo ya kujiamini kidogo na kujiamini kuu ni nini?" -> - "Michoro ya XML katika maagizo inasaidiaje kupanga majibu ya AI?" -> - "Ninapopaswa kutumia mifumo ya kujitathmini binafsi dhidi ya maagizo ya moja kwa moja?" +> - "Tofauti kati ya mifumo ya maelekezo ya shauku ndogo na shauku kubwa ni nini?" +> - "Maelezo ya XML katika maelekezo husaidiaje kupanga jibu la AI?" +> - "Lini napaswa kutumia mifumo ya kujitathmini kwa nafsi dhidi ya maagizo ya moja kwa moja?" -**Kujiamini Kuu (Kina & Kina) -** Kwa matatizo magumu ambapo unahitaji uchambuzi kamili. Modeli inachunguza kwa kina na inaonyesha sababu za kina. Tumia hii kwa muundo wa mifumo, maamuzi ya usanifu, au utafiti mgumu. +**Shauku Kubwa (Kina na Kina Kwa Kina)** - Kwa matatizo magumu unayotaka uchambuzi wa kina. Mfano huchunguza kwa kina na kuonyesha fikra kwa undani. Tumia hii kwa usanifu wa mifumo, maamuzi ya usanifu, au utafiti mgumu. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Utekelezaji wa Kazi (Mkilele wa Hatua kwa Hatua)** - Kwa mitiririko ya kazi yenye hatua nyingi. Modeli huweka mpango wa awali, huandika kila hatua anapofanya kazi, kisha hutumia muhtasari. Tumia hii kwa uhamishaji, utekelezaji, au michakato yenye hatua nyingi. +**Utekelezaji wa Kazi (Mafanikio Hatua kwa Hatua)** - Kwa mitiririko ya kazi yenye hatua nyingi. Mfano hutoa mpango wa awali, unasimulia hatua kila anapofanya kazi, kisha hutoa muhtasari. Tumia hii kwa uhamisho, utekelezaji, au mchakato wowote wenye hatua nyingi. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Uagizo wa Mnyororo wa Mawazo huuliza modeli kwa uwazi ionyeshe mchakato wake wa sababu, kuboresha usahihi kwa kazi ngumu. Mgawanyo wa hatua kwa hatua husaidia binadamu na AI kuelewa mantiki. +Maelekezo ya Mnyororo wa Fikra (Chain-of-Thought) huomba mfano aonyeshe mchakato wa kufikiri, huongeza usahihi kwenye kazi ngumu. Kugawanya kwa hatua-hatua husaidia binadamu na AI kuelewa mantiki. > **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Uliza kuhusu mfumo huu: -> - "Ningebadilishaje mfumo wa utekelezaji wa kazi kwa shughuli zinazochukua muda mrefu?" -> - "Nini mbinu bora za kupanga utangulizi wa zana katika programu za uzalishaji?" -> - "Ninawezaje kurekodi na kuonyesha taarifa za maendeleo ya kati katika UI?" +> - "Ningebadilishaje mfumo wa utekelezaji wa kazi kwa operesheni za muda mrefu?" +> - "Ni mbinu bora zipi za kupanga maelezo ya zana katika programu za uzalishaji?" +> - "Ninawezaje kunasa na kuonyesha taarifa za maendeleo ya kati katika UI?" -Mchoro hapa chini unaelezea mtiririko wa Kuweka Mpango → Kutekeleza → Kutoa Muhtasari. +Mchoro hapa chini unaonyesha mtiririko huu wa Kupanua → Kutekeleza → Kufupisha. -Mtiririko wa Mfumo wa Utekelezaji wa Kazi +Task Execution Pattern -*Mpango → Utekelezaji → Muhtasari kwa kazi zenye hatua nyingi* +*Panga → Tekeleza → Fupisha mtiririko wa kazi yenye hatua nyingi* -**Msimbo unaojitathmini** - Kwa kuzalisha msimbo wa ubora wa uzalishaji. Modeli hutoa msimbo unaofuata viwango vya uzalishaji na usimamizi sahihi wa makosa. Tumia hii unapo tengeneza vipengele vipya au huduma. +**Kanuni Zinazojiangalia** - Kwa kuunda msimbo wa ubora wa uzalishaji. Mfano hutengeneza msimbo unafuata viwango vya uzalishaji na usimamizi sahihi wa makosa. Tumia hii wakati wa kujenga vipengele vipya au huduma. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Mchoro hapa chini unaonyesha mzunguko huu wa kuboresha kidogo kidogo — tengeneza, tathmini, tambua udhaifu, na boresha hadi msimbo ukidhi viwango vya uzalishaji. +Mchoro hapa chini unaonyesha mzunguko huu wa maboresho ya kuendelea — tengeneza, tathmini, tambua mapungufu, na safisha hadi msimbo ukidhi viwango vya uzalishaji. -Mzunguko wa Kujitathmini +Self-Reflection Cycle -*Mzunguko wa kuboresha taratibu - tengeneza, tathmini, tambua matatizo, boresha, rudia* +*Mizunguko ya maboresho ya kuendelea - tengeneza, tathmini, tambua matatizo, boresha, rudia* -**Uchambuzi Uliopangwa** - Kwa tathmini thabiti. Modeli hupitia msimbo kwa kutumia mfumo uliofungwa (usahihi, mbinu, utendaji, usalama, urahisi wa kudumisha). Tumia hii kwa ukaguzi wa msimbo au tathmini za ubora. +**Uchambuzi wa Muundo** - Kwa tathmini thabiti. Mfano hupitia msimbo ukitumia mfumo thabiti (usahihi, mbinu, utendaji, usalama, uendelevu). Tumia hii kwa mapitio ya msimbo au tathmini ya ubora. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Uliza kuhusu uchambuzi uliopangwa: -> - "Ninawezaje kubadilisha mfumo wa uchambuzi kwa aina tofauti za ukaguzi wa msimbo?" -> - "Njia bora ya kuchambua na kutenda kwa matokeo yaliyopangwa kiforodha ni ipi?" -> - "Ninadhani vipi kuhakikisha viwango vya ugumu viko sawa katika vikao tofauti vya ukaguzi?" +> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Uliza kuhusu uchambuzi wa muundo: +> - "Ninawezaje kubinafsisha mfumo wa uchambuzi kwa aina mbalimbali za mapitio ya msimbo?" +> - "Njia bora za kuchanganua na kutenda juu ya matokeo yaliyopangwa ni zipi?" +> - "Ninawezaje kuhakikisha viwango sawia vya ukali kwenye vikao tofauti vya mapitio?" -Mchoro ufuatao unaonyesha jinsi mfumo huu uliopangwa unavyopanga ukaguzi wa msimbo katika makundi thabiti yenye viwango vya ugumu. +Mchoro ufuatao unaonyesha jinsi mfumo huu ulivyoandaa mapitio ya msimbo katika makundi thabiti na viwango vya ukali. -Mfumo wa Uchambuzi Uliopangwa +Structured Analysis Pattern -*Mfumo wa ukaguzi wa msimbo thabiti wenye viwango vya ugumu* +*Mfumo wa mapitio thabiti ya msimbo yenye viwango vya ukali* -**Mazungumzo ya Mzunguko Mwingi** - Kwa mazungumzo yanayohitaji muktadha. Modeli inakumbuka ujumbe wa awali na kujenga juu yake. Tumia hii kwa vikao vya msaada wa mwingiliano au maswali magumu. +**Mazungumzo ya Mzunguko wa Nyingi** - Kwa mazungumzo yanayohitaji muktadha. Mfano anakumbuka ujumbe wa awali na kujenga juu yake. Tumia hii kwa vikao vya msaada ya moja kwa moja au maswali magumu. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Mchoro hapa chini unaona jinsi muktadha wa mazungumzo unavyokusanywa kwa kila mzunguko na jinsi unavyoendana na kikomo cha tokeni cha modeli. +Mchoro hapa chini unaonesha jinsi muktadha wa mazungumzo unavyojikusanya kwa kila mzunguko na jinsi unavyohusiana na kikomo cha token cha mfano. -Kumbukumbu ya Muktadha +Context Memory -*Jinsi muktadha wa mazungumzo unavyokusanywa katika mizunguko mingi hadi kufikia kikomo cha tokeni* -**Uelewa Hatua kwa Hatua** - Kwa matatizo yanayohitaji mantiki inayoweza kuonekana. Mfano unaonyesha uelewa wazi kwa kila hatua. Tumia hili kwa matatizo ya hisabati, vitendawili vya mantiki, au unapohitaji kuelewa mchakato wa kufikiria. +*Jinsi muktadha wa mazungumzo unavyojikusanya kwa mzunguko mingi hadi kufikia kikomo cha tokeni* + +**Ufahamu Hatua kwa Hatua** - Kwa matatizo yanayohitaji mantiki inayoonekana. Mfano huonyesha fikra zilizo wazi kwa kila hatua. Tumia hii kwa matatizo ya hisabati, mafumbo ya mantiki, au wakati unahitaji kuelewa mchakato wa kufikiri. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Michoro ifuatayo inaonyesha jinsi mfano unavyovitenganisha matatizo katika hatua za mantiki zilizoandikwa na kuwekwa nambari. +Mchoro hapa chini unaonyesha jinsi mfano huvunja matatizo katika hatua za mantiki zilizoandikwa na nambari wazi. Step-by-Step Pattern +*Kuvunja matatizo katika hatua za wazi za kiakili* -*Kupunguza matatizo katika hatua za mantiki zilizo wazi* - -**Matokeo Yaliyopigwa Xaria** - Kwa majibu yenye mahitaji maalum ya muundo. Mfano hufuata kwa uangalifu kanuni za muundo na urefu. Tumia hili kwa muhtasari au unapohitaji muundo sahihi wa matokeo. +**Matokeo Yaliyopigwa Mipaka** - Kwa majibu yenye mahitaji maalum ya muundo. Mfano unafuata kwa umakini kanuni za muundo na urefu. Tumia hii kwa muhtasari au unapohitaji muundo sahihi wa matokeo. ```java String prompt = """ @@ -420,9 +420,9 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Michoro ifuatayo inaonyesha jinsi masharti yanavyoongoza mfano kutoa matokeo ambayo yanazingatia kwa ukamilifu muundo na mahitaji ya urefu. +Mchoro ufuatao unaonyesha jinsi vizuizi vinavyoelekeza mfano kutoa matokeo yanayozingatia kwa ukamilifu mahitaji yako ya muundo na urefu. -Constrained Output Pattern +Mfano wa Matokeo Yaliyopigwa Mipaka *Kutekeleza mahitaji maalum ya muundo, urefu, na muundo* @@ -430,7 +430,7 @@ Michoro ifuatayo inaonyesha jinsi masharti yanavyoongoza mfano kutoa matokeo amb **Thibitisha usambazaji:** -Hakikisha faili `.env` ipo kwenye saraka kuu ikiwa na vyeti vya Azure (vilivyotengenezwa wakati wa Moduli 01). Endesha hii kutoka kwenye saraka ya moduli (`02-prompt-engineering/`): +Hakikisha faili `.env` ipo kwenye saraka kuu na ina vibali vya Azure (vilivyoundwa wakati wa Moduli 01). Endesha hii kutoka kwenye saraka ya moduli (`02-prompt-engineering/`): **Bash:** ```bash @@ -444,37 +444,37 @@ Get-Content ..\.env # Inapaswa kuonyesha AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOY **Anzisha programu:** -> **Kumbuka:** Ikiwa tayari umeanzisha programu zote kwa kutumia `./start-all.sh` kutoka kwenye saraka kuu (kama ilivyoelezwa katika Moduli 01), moduli hii tayari inaendesha kwenye bandari 8083. Unaweza kuruka amri za kuanzisha hapa chini na kwenda moja kwa moja http://localhost:8083. +> **Kumbuka:** Ikiwa tayari umeanzisha programu zote ukitumia `./start-all.sh` kutoka saraka kuu (kama ilivyoelezwa katika Moduli 01), moduli hii tayari inaendeshwa kwenye bandari 8083. Unaweza kuruka amri za kuanzisha zilizopo hapa chini na kwenda moja kwa moja http://localhost:8083. -**Chaguo 1: Kutumia Spring Boot Dashboard (Inapendekezwa kwa watumiaji wa VS Code)** +**Chaguo 1: Kutumia Spring Boot Dashboard (Inayopendekezwa kwa watumiaji wa VS Code)** -Kontena la maendeleo linajumuisha ugani wa Spring Boot Dashboard, ambao hutoa interface ya kuona ili kusimamia programu zote za Spring Boot. Unaweza kuipata kwenye Upau wa Shughuli upande wa kushoto wa VS Code (tazama ikoni ya Spring Boot). +Sanduku la maendeleo lina nyongeza ya Spring Boot Dashboard, inayotoa interface ya kuona kuendesha programu zote za Spring Boot. Unaweza kuipata kwenye Mwambaa wa Shughuli upande wa kushoto wa VS Code (tazama ikoni ya Spring Boot). -Kutoka kwenye Spring Boot Dashboard, unaweza: -- Kuona programu zote za Spring Boot zinazopatikana kwenye eneo la kazi -- Kuanza/kusimamisha programu kwa bonyeza mara moja -- Kuona rekodi za programu kwa wakati halisi +Kutoka Spring Boot Dashboard, unaweza: +- Kuona programu zote za Spring Boot zilizopo kwenye eneo la kazi +- Kuanzisha/kuzima programu kwa bonyeza moja +- Kuangalia kumbukumbu za programu kwa wakati halisi - Kufuatilia hali ya programu -Bonyeza tu kitufe cha kuanzisha karibu na "prompt-engineering" kuanzisha moduli hii, au anza moduli zote mara moja. +Bonyeza kitufe cha play kando ya "prompt-engineering" kuanzisha moduli hii, au anzisha moduli zote kwa wakati mmoja. -Spring Boot Dashboard +Dashibodi ya Spring Boot -*Spring Boot Dashboard katika VS Code — anzisha, simamisha, na fuatilia moduli zote kutoka mahali pamoja* +*Dashibodi ya Spring Boot katika VS Code — anzisha, zimia, na fuatilia moduli zote kutoka sehemu moja* -**Chaguo 2: Kutumia scripts za shell** +**Chaguo 2: Kutumia skripti za shell** -Anzisha programu zote za wavuti (moduli 01-04): +Anzisha programu zote za mtandao (moduli 01-04): **Bash:** ```bash -cd .. # Kutoka kwa saraka ya mizizi +cd .. # Kutoka kwenye saraka ya mzizi ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Kutoka kwenye saraka ya mzizi +cd .. # Kutoka kwa saraka ya mzizi .\start-all.ps1 ``` @@ -492,117 +492,117 @@ cd 02-prompt-engineering .\start.ps1 ``` -Misingi yote huchukua moja kwa moja mabadiliko ya mazingira kutoka faili `.env` la saraka kuu na itajenga JARs ikiwa hazipo. +Skripti zote zinapakia moja kwa moja mabadiliko ya mazingira kutoka faili `.env` kuu na zitajenga JARs endapo hazipo. -> **Kumbuka:** Ikiwa unapendelea kujenga moduli zote mwenyewe kabla ya kuanza: +> **Kumbuka:** Ikiwa unapendelea kujenga moduli zote kwa mikono kabla ya kuanza: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Fungua http://localhost:8083 katika kivinjari chako. +Fungua http://localhost:8083 kwenye kivinjari chako. -**Kusimamisha:** +**Kusitisha:** **Bash:** ```bash -./stop.sh # Moduli hii tu +./stop.sh # Moduli hii pekee # Au cd .. && ./stop-all.sh # Moduli zote ``` **PowerShell:** ```powershell -.\stop.ps1 # Hii moduli tu +.\stop.ps1 # Hili ni moduli tu # Au cd ..; .\stop-all.ps1 # Moduli zote ``` ## Picha za Programu -Hapa ni interface kuu ya moduli ya uhandisi wa prompt, ambapo unaweza kujaribu mifumo nane kwa pamoja. +Huu ni muonekano mkuu wa moduli ya uhandisi wa prompt, ambapo unaweza kujaribu mifumo yote nane kwa pamoja. -Dashboard Home +Muonekano Mkuu wa Dashibodi -*Dashibodi kuu inayoonyesha mifumo yote 8 ya uhandisi wa prompt pamoja na sifa zao na matumizi yao* +*Dashibodi kuu ikionyesha mifumo yote 8 ya uhandisi wa prompt pamoja na sifa na matumizi yao* ## Kuchunguza Mifumo -Interface ya wavuti inakuwezesha kujaribu mbinu tofauti za kuweka prompt. Kila mfumo hutatua matatizo tofauti - jaribu kuona lini kila njia inafaa. +Interface ya wavuti inakuwezesha kujaribu mikakati tofauti ya kuigiza (prompting). Kila mfumo unatatua matatizo tofauti - jaribu kuona lini kila njia hutoa matokeo bora. -> **Kumbuka: Streaming dhidi ya Non-Streaming** — Kila ukurasa wa mfumo hutoa vitufe viwili: **🔴 Stream Response (Live)** na chaguo la **Non-streaming**. Streaming hutumia Matukio Yanayotumwa na Seva (SSE) kuonyesha tokeni kwa wakati halisi huku mfano ukiizalisha, hivyo unaona maendeleo mara moja. Chaguo la non-streaming linasubiri jibu lote kabla ya kuonyesha. Kwa prompt zinazochochea uelewa wa kina (mfano, High Eagerness, Self-Reflecting Code), simu isiyo ya streaming inaweza kuchukua muda mrefu sana — mara nyingine dakika — bila maoni yoyote yanayoonekana. **Tumia streaming unapo jaribu prompt tata** ili uone mfano ukiendelea na kuepuka hisia kwamba ombi limechelewa. +> **Kumbuka: Streaming dhidi ya Isiyostreaming** — Kila ukurasa wa mfumo una vifungo viwili: **🔴 Jiribu Matokeo Moja kwa Moja (Live)** na chaguo la **Isiyostreaming**. Streaming hutumia Server-Sent Events (SSE) kuonyesha tokeni kwa wakati halisi wakati mfano unayazalisha, kwa hivyo unaona maendeleo mara moja. Chaguo la isiyostreaming husubiri jibu lote kabla ya kuonyesha. Kwa prompts zinazochochea fikra za kina (mfano, High Eagerness, Self-Reflecting Code), mwito wa isiyostreaming unaweza kuchukua muda mrefu sana — mara nyingine dakika — bila maoni yanayoonekana. **Tumia streaming unapojaribu prompts tata** ili uone mfano ukitumia na kuepuka hisia kwamba ombi limefikia muda wake. > -> **Kumbuka: Mahitaji ya Kivinjari** — Kipengele cha streaming kinatumia Fetch Streams API (`response.body.getReader()`) ambayo inahitaji kivinjari kamili (Chrome, Edge, Firefox, Safari). Hakifanyi kazi katika Kivinjari Rahisi kilichojengwa ndani ya VS Code, kwani webview yake haisaidii API ya ReadableStream. Ukitumia Kivinjari Rahisi, vitufe vya non-streaming bado vitafanya kazi kawaida — tu vitufe vya streaming vinaathirika. Fungua `http://localhost:8083` katika kivinjari cha nje kwa uzoefu kamili. +> **Kumbuka: Sharti la Kivinjari** — Kipengele cha streaming kinatumia Fetch Streams API (`response.body.getReader()`) kinachohitaji kivinjari kamili (Chrome, Edge, Firefox, Safari). Hakifanyi kazi katika Simple Browser iliyojengwa ndani ya VS Code, kwani muonekano wake wa wavuti hauungi mkono ReadableStream API. Ukitumia Simple Browser, vifungo vya isiyostreaming bado vitafanya kazi kama kawaida — ni vifungo vya streaming tu vinaathirika. Fungua `http://localhost:8083` kwenye kivinjari huru kwa uzoefu kamili. -### Matamanio ya Chini dhidi ya Juu +### Kutaka Kidogo dhidi ya Kutaka Kurefu -Uliza swali rahisi kama "Ni asilimia 15 ya 200 ni kiasi gani?" ukitumia Matamanio ya Chini. Utapata jibu la haraka na moja kwa moja. Sasa uliza jambo tata kama "Buni mkakati wa caching kwa API yenye trafiki nyingi" ukitumia Matamanio ya Juu. Bonyeza **🔴 Stream Response (Live)** na kutazama maelezo ya mfano yakiibuka tokeni kwa tokeni. Mfano ule ule, muundo ule ule wa swali - lakini prompt inaeleza kiasi cha kufikiria kinachohitajika. +Uliza swali rahisi kama "Ni asilimia 15 ya 200 ni kiasi gani?" ukitumia Low Eagerness. Utapokea jibu la papo hapo, moja kwa moja. Sasa uliza kitu kigumu kama "Tengeneza mkakati wa kuhifadhi data kwa API yenye trafiki kubwa" ukitumia High Eagerness. Bonyeza **🔴 Jiribu Matokeo Moja kwa Moja (Live)** na tathmini fikra za mfano kwa undani tokeni baada ya tokeni. Mfano ule ule, muundo ule ule wa swali - lakini prompt inasema ni kiasi gani cha kufikiria kinahitajika. -### Utekelezaji wa Kazi (Utangulizi wa Vifaa) +### Utekesaji wa Kazi (Mwongozo wa Zana) -Mifumo ya hatua nyingi inafaidika na upangaji wa awali na kusimuliwa kwa maendeleo. Mfano unaeleza atakachofanya, unasimulia kila hatua, halafu hutoa muhtasari wa matokeo. +Mizigo yenye hatua nyingi inafaidika na upangaji wa awali na maelezo ya maendeleo. Mfano huonyesha ni nini kitakachofanywa, hueleza kila hatua, kisha hutoa muhtasari wa matokeo. -### Msimbo Unaotafakari Mwelekeo Wake +### Msimbo Unaojitathmini -Jaribu "Tengeneza huduma ya kuthibitisha barua pepe". Badala ya tu kutengeneza msimbo na kusitisha, mfano hutengeneza, kutathmini dhidi ya vigezo vya ubora, kugundua udhaifu, na kuboresha. Utaona ukirudia mpaka msimbo ufanikiwe kwa viwango vya uzalishaji. +Jaribu "Tengeneza huduma ya kuthibitisha barua pepe". Badala ya kuzalisha msimbo na kusitisha, mfano huzalisha, huku hukagua dhidi ya vigezo vya ubora, hutambua udhaifu, na kuboresha. Utaona ikirudia hadi msimbo ukadhihirishwe kufikia viwango vya uzalishaji. -### Uchambuzi wa Kijanib +### Uchambuzi Ulio Jengwa -Mapitio ya msimbo yanahitaji mifumo thabiti ya kutathmini. Mfano unachambua msimbo ukitumia makundi maalum (usahihi, mbinu, utendaji, usalama) na viwango vya uzito. +Mapitio ya msimbo yanahitaji mfumo thabiti wa tathmini. Mfano unachambua msimbo kwa kutumia makundi thabiti (usahihi, desturi, utendaji, usalama) na viwango vya ukali. -### Maongezi ya Mazungumzo yenye Zamu Nyingi +### Mazungumzo ya Mara Nyingi -Uliza "Spring Boot ni nini?" kisha moja kwa moja uliza "Nionyeshe mfano". Mfano unakumbuka swali lako la kwanza na akutie mfano wa Spring Boot mahsusi. Bila kumbukumbu, swali la pili lingekuwa la mkanganyiko. +Uliza "Spring Boot ni nini?" kisha mara moja fuata na "Nionyeshe mfano". Mfano hukumbuka swali lako la kwanza na kukupa mfano wa Spring Boot hasa. Bila kumbukumbu, swali la pili lingekuwa la jumla sana. -### Uelewa Hatua kwa Hatua +### Fikra Hatua kwa Hatua -Chagua tatizo la hisabati na jaribu kwa Uelewa Hatua kwa Hatua na Matamanio ya Chini. Matamanio ya chini yanakupa jibu tu - haraka lakini si wazi. Uelewa hatua kwa hatua unaonyesha kila hesabu na uamuzi. +Chagua tatizo la hesabu na jiunge nalo kwa Step-by-Step Reasoning na Low Eagerness. Low eagerness hutoa jibu tu - haraka lakini haieleweki. Step-by-step inaonyesha kila hesabu na uamuzi. -### Matokeo Yaliyopigwa Xaria +### Matokeo Yaliyopigwa Mipaka -Unapohitaji muundo maalum au idadi ya maneno, mfumo huu unatekeleza utekelezwaji mkali. Jaribu kutengeneza muhtasari wenye maneno 100 kabisa kwa muundo wa pointi. +Unapohitaji muundo au idadi maalum ya maneno, mfumo huu unahakikisha kufuata maagizo kwa ukamilifu. Jaribu kuzalisha muhtasari wenye maneno 100 halisi kwa njia ya pointi za risasi. ## Unachojifunza Kweli -**Jitihada za Uelewa Hubadilisha Kila Kitu** +**Jitihada za Fikra Hubadilisha Kila Kitu** -GPT-5.2 inakuwezesha kudhibiti jitihada za kompyuta kupitia prompt zako. Jitihada kidogo maana yake majibu ya haraka kwa uchunguzi mdogo. Jitihada kubwa maana yake mfano hutumia muda kufikiria kwa kina. Unajifunza kulinganisha jitihada na ugumu wa kazi - usipoteze muda kwa maswali rahisi, lakini usikimbize maamuzi magumu pia. +GPT-5.2 inakuwezesha kudhibiti jitihada za kompyuta kupitia prompt zako. Jitihada ndogo inamaanisha majibu ya haraka yenye uchunguzi mdogo. Jitihada kubwa ina maana mfano huchukua muda kufikiria kwa kina. Unajifunza kulinganisha jitihada na ugumu wa kazi - usipoteze muda kwa maswali rahisi, lakini usiharakishe maamuzi magumu pia. -**Muundo Unaongoza Tabia** +**Muundo Huongoza Tabia** -Tazama lebo za XML katika prompt? Sio mapambo. Mifano hufuata maagizo yaliyopangwa kwa muundo zaidi kwa kuaminika kuliko maandishi yasiyo rasmi. Unapohitaji michakato ya hatua nyingi au mantiki tata, muundo husaidia mfano kufuatilia anapoelekea wapi na kinachofuata. Michoro ifuatayo inavunjwa prompt iliyopangwa vizuri, ikionyesha jinsi lebo kama ``, ``, ``, ``, na `` zinavyoratibu maagizo yako katika sehemu wazi. +Umeziona tags za XML kwenye prompts? Sio mapambo. Mifano hufuata maagizo yaliyo na muundo kwa uhakika zaidi kuliko maandishi ya kawaida. Unapohitaji michakato yenye hatua nyingi au mantiki tata, muundo husaidia mfano kufuatilia ni wapi yuko na ni nini kitakachofuata. Mchoro hapa chini unavunja prompt yenye muundo mzuri, unaonyesha jinsi tags kama ``, ``, ``, ``, na `` zinavyopanga maelekezo yako katika sehemu zilizo wazi. -Prompt Structure +Muundo wa Prompt -*Anatomi ya prompt iliyopangwa vizuri yenye sehemu wazi na muundo wa mtindo wa XML* +*Muundo wa prompt wenye sehemu zilizo wazi na mpangilio wa mtindo wa XML* -**Ubora Kupitia Tathmini Binafsi** +**Ubora Kupitia Kujitathmini** -Mifumo inayotafakari kazi zake inafanya vigezo vya ubora kuwa wazi. Badala ya kutegemea mfano kufanyia "sahihi", unaeleza hasa maana ya "sahihi": mantiki sahihi, utawala wa makosa, utendaji, usalama. Mfano unaweza kisha kutathmini matokeo yake na kuboresha. Hii hubadilisha utengenezaji wa msimbo kutoka bahati nasibu hadi mchakato. +Mifumo ya kujitathmini huendelezwa kwa kuweka wazi vigezo vya ubora. Badala ya kutegemea somo lifanye "sahihi", unalimwambia hasa maana ya "sahihi": mantiki inayofaa, utunzaji wa makosa, utendaji, usalama. Kisha mfano unaweza kutathmini matokeo yake na kuboresha. Hii hubadilisha uzalishaji wa msimbo kutoka bahati nasibu kuwa mchakato. **Muktadha Ni Mdogo** -Mazungumzo yenye zamu nyingi hufanya kazi kwa kujumuisha historia ya ujumbe katika kila ombi. Lakini kuna kikomo - kila mfano una idadi kubwa ya tokeni zinazoweza kutumiwa. Kadiri mazungumzo yanavyozidi, utahitaji mikakati ya kuweka muktadha mzuri bila kufikia kikomo hicho. Moduli hii inaonyesha jinsi kumbukumbu inavyofanya kazi; baadaye utajifunza lini kufupisha, lini kusahau, na lini kutafuta. +Mazungumzo ya mara nyingi hufanya kazi kwa kuingiza historia ya ujumbe kwa kila ombi. Lakini kuna kikomo - kila mfano una hesabu kubwa ya tokeni walioweza kubeba. Kadiri mazungumzo yanavyokua, utahitaji mikakati ya kuweka muktadha muhimu bila kufikia ukomo huo. Moduli hii inakuonyesha jinsi kumbukumbu inavyofanya kazi; baadaye utajifunza lini kufupisha, lini kusahau, na lini kupata tena. ## Hatua Zifuatazo -**Moduli Ifuatayo:** [03-rag - RAG (Uzalishaji Ulioongeza Ushuru)](../03-rag/README.md) +**Moduli Inayofuata:** [03-rag - RAG (Uzalishaji Ulioboreshwa kwa Kupata Taarifa)](../03-rag/README.md) --- -**Muelekeo:** [← Iliyopita: Moduli 01 - Utangulizi](../01-introduction/README.md) | [Rudi Kwenye Kuu](../README.md) | [Ifuatayo: Moduli 03 - RAG →](../03-rag/README.md) +**Utengezaji:** [← Awali: Moduli 01 - Utangulizi](../01-introduction/README.md) | [Rudi Kwenye Kuu](../README.md) | [Ifuatayo: Moduli 03 - RAG →](../03-rag/README.md) --- -**Taarifa ya Kukataa**: -Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kwa usahihi, tafadhali fahamu kwamba tafsiri za moja kwa moja zinaweza kuwa na makosa au upungufu wa usahihi. Hati asili katika lugha yake ya asili inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inapendekezwa. Hatutangazwa kuwajibika kwa kutokuelewana au makosa ya tafsiri yanayotokana na matumizi ya tafsiri hii. +**Kionyozo**: +Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake halisi inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inapendekezwa. Hatutojibu kwa kuelewa vibaya au tafsiri potofu zinazotokea kutokana na matumizi ya tafsiri hii. \ No newline at end of file diff --git a/translations/sw/03-rag/README.md b/translations/sw/03-rag/README.md index cb787f6b7..28e677fbe 100644 --- a/translations/sw/03-rag/README.md +++ b/translations/sw/03-rag/README.md @@ -1,144 +1,143 @@ -# Moduli 03: RAG (Uzalishaji Unaoungwa Mkono na Upataji) +# Moduli 03: RAG (Uundaji Ulioongezwa kwa Urejeshaji) ## Jedwali la Maudhui -- [Video za Maelezo](../../../03-rag) -- [Utajifunza Nini](../../../03-rag) -- [Mahitaji ya Awali](../../../03-rag) -- [Kuelewa RAG](../../../03-rag) - - [Ni Njia Gani ya RAG Inayotumika Katika Mafunzo Haya?](../../../03-rag) -- [Jinsi Inavyofanya Kazi](../../../03-rag) - - [Usindikaji wa Hati](../../../03-rag) - - [Kuumba Embeddings](../../../03-rag) - - [Utafutaji wa Kisemi](../../../03-rag) - - [Uzalishaji wa Majibu](../../../03-rag) -- [Endesha Programu](../../../03-rag) -- [Matumizi ya Programu](../../../03-rag) - - [Pakia Hati](../../../03-rag) - - [Uliza Maswali](../../../03-rag) - - [Angalia Marejeleo ya Chanzo](../../../03-rag) - - [Jaribu na Maswali](../../../03-rag) -- [Mafanikio Muhimu](../../../03-rag) - - [Mikakati ya Kugawanya Vipande](../../../03-rag) - - [Alama za Ulinganifu](../../../03-rag) - - [Uhifadhi wa Kumbukumbu](../../../03-rag) - - [Usimamizi wa Dirisha la Muktadha](../../../03-rag) -- [Wakati RAG Inapokuwa Muhimu](../../../03-rag) -- [Hatua Zinazofuata](../../../03-rag) - -## Video za Maelezo - -Tazama kikao hiki cha moja kwa moja kinachoelezea jinsi ya kuanza na moduli hii: - -RAG with LangChain4j - Live Session +- [Maelezo ya Video](#maelezo-ya-video) +- [Utajifunza Nini](#utajifunza-nini) +- [Mambo ya Kuwa Nayo Kabla](#mambo-ya-kuwa-nayo-kabla) +- [Kuelewa RAG](#kuelewa-rag) + - [Ni Mbinu Gani ya RAG Inayotumika Katika Mafunzo Haya?](#ni-mbinu-gani-ya-rag-inayotumika-katika-mafunzo-haya) +- [Jinsi Inavyofanya Kazi](#jinsi-inavyofanya-kazi) + - [Usindikaji wa Hati](#usindikaji-wa-hati) + - [Kuunda Embeddings](#kuunda-embeddings) + - [Utafutaji wa Kimaana](#utafutaji-wa-kimaana) + - [Kutengeneza Majibu](#uundaji-wa-majibu) +- [Endesha Programu](#endesha-programu) +- [Kutumia Programu](#kutumia-programu) + - [Pakua Hati](#pakia-hati) + - [Uliza Maswali](#uliza-maswali) + - [Angalia Marejeleo ya Vyanzo](#angalia-marejeleo-ya-chanzo) + - [Jaribu Maswali](#jaribu-maswali-tofauti) +- [Mafundisho Muhimu](#dhahabu-muhimu) + - [Mbinu ya Kugawanya Vipande](#mkakati-wa-kugawanya-vigawanyo) + - [Alama za Ulinganifu](#alama-za-ulinganifu) + - [Uhifadhi wa Kumbukumbu Ndani ya Kumbukumbu](#uhifadhi-wa-kumbukumbu-ndani) + - [Usimamizi wa Dirisha la Muktadha](#usimamizi-wa-dirisha-la-muktadha) +- [Wakati RAG Ina Maanisha](#wakati-rag-inafaa) +- [Hatua Zinazo Fuata](#hatua-zifuatazo) + +## Maelezo ya Video + +Tazama kikao hiki cha moja kwa moja kinachoeleza jinsi ya kuanza na moduli hii: + +RAG na LangChain4j - Kikao cha Moja kwa Moja ## Utajifunza Nini -Katika moduli zilizopita, ulijifunza jinsi ya kuzungumza na AI na kupanga maelekezo yako kwa ufanisi. Lakini kuna kikomo cha kimsingi: mifano ya lugha inajua tu kile walichojifunza wakati wa mafunzo. Haiwezi kujibu maswali kuhusu sera za kampuni yako, hati za mradi wako, au maelezo yoyote ambayo hayakufunzwa. +Katika moduli zilizopita, ulijifunza jinsi ya kuzungumza na AI na kupanga maelekezo yako kwa ufanisi. Lakini kuna kikomo cha msingi: modeli za lugha zinajua tu kile walichojifunza wakati wa mafunzo. Haziwezi kujibu maswali kuhusu sera za kampuni yako, nyaraka za mradi wako, au taarifa yoyote ambayo hazikufundishwa. -RAG (Uzalishaji Unaoungwa Mkono na Upataji) hutatua tatizo hili. Badala ya kujaribu kufundisha mfano maelezo yako (ambayo ni ghali na haziwezi kutekelezwa kwa urahisi), unampa uwezo wa kutafuta kupitia hati zako. Wakati mtu anauliza swali, mfumo hupata taarifa zinazofaa na kuzijumuisha kwenye maelekezo. Kisha mfano hujibu kulingana na muktadha uliopatikana. +RAG (Uundaji Ulioongezwa kwa Urejeshaji) hutatua tatizo hili. Badala ya kujaribu kufundisha modeli habari zako (ambayo ni ghali na haiwezekani), unaiwezesha kutafuta kupitia hati zako. Mtu anapouliza swali, mfumo hupata taarifa zinazohusiana na kuziacha kwenye maelekezo. Kisha modeli hujibu kwa msingi wa muktadha uliopatikana. -Fikiria RAG kama kumpa mfano maktaba ya rejea. Unapouliza swali, mfumo: +Fikiria RAG kama kumpa modeli maktaba ya rejeleo. Unapouliza swali, mfumo: -1. **Swali la Mtumiaji** - Unauliza swali -2. **Embedding** - Hubadilisha swali lako kuwa vector -3. **Utafutaji wa Vector** - Hupata vipande vya hati vinavyofanana -4. **Ukusanyaji wa Muktadha** - Huongeza vipande vinavyofaa kwenye maelekezo -5. **Jibu** - LLM huzalisha jibu kulingana na muktadha +1. **Swali la Mtumiaji** - Unauliza swali +2. **Embedding** - Hubadilisha swali lako kuwa vector +3. **Utafutaji wa Vector** - Hupata vipande vya hati vinavyofanana +4. **Ukusanyaji wa Muktadha** - Huongeza vipande vinavyolingana kwenye maelekezo +5. **Jibu** - LLM hutengeneza jibu kwa msingi wa muktadha -Hii huweka majibu ya mfano juu ya data yako halisi badala ya kutegemea maarifa ya mafunzo yake au kubuni majibu. +Hii hufanya majibu ya modeli kutegemea data yako halisi badala ya kutegemea maarifa ya mafunzo au kubuni majibu. -## Mahitaji ya Awali +## Mambo ya Kuwa Nayo Kabla -- Kumaliza [Moduli 00 - Mwanzo wa Haraka](../00-quick-start/README.md) (kwa mfano wa RAG Rahisi unaotajwa baadaye katika moduli hii) -- Kumaliza [Moduli 01 - Utangulizi](../01-introduction/README.md) (Rasilimali za Azure OpenAI zimewezeshwa, ikiwa ni pamoja na mfano wa kuingiza `text-embedding-3-small`) -- Faili `.env` katika saraka kuu na vyeti vya Azure (vilivyoundwa na `azd up` katika Moduli 01) +- Umemaliza [Moduli 01 - Utangulizi](../01-introduction/README.md) (rasilimali za Azure OpenAI zimewekwa, pamoja na modeli ya `text-embedding-3-small`) +- Faili la `.env` liko kwenye saraka kuu likiwa na cheti za Azure (limeundwa na `azd up` katika Moduli 01) -> **Kumbuka:** Ikiwa hujamaliza Moduli 01, fuata maelekezo ya uwezeshaji huko kwanza. Amri `azd up` huweka mfano wa mazungumzo wa GPT na mfano wa kuingiza unaotumika katika moduli hii. +> **Kumbuka:** Ikiwa bado hujamaliza Moduli 01, fuata maelekezo ya uanzishaji hapo kwanza. Amri ya `azd up` huweka modeli za mazungumzo za GPT na modeli ya embedding inayotumika katika moduli hii. ## Kuelewa RAG -Mchoro ulio hapa chini unaonyesha wazo kuu: badala ya kutegemea data za mafunzo za mfano pekee, RAG humsaidia na maktaba ya rejea ya hati zako za kushauriana kabla ya kuzalisha jibu kila mara. +Mchoro huu chini unaelezea dhana kuu: badala ya kutegemea data ya mafunzo ya modeli peke yake, RAG inaiwezesha kupata maktaba ya rejeleo ya hati zako kabla ya kutengeneza jibu kila mara. -What is RAG +Nini ni RAG -*Mchoro huu unaonyesha tofauti kati ya LLM ya kawaida (inayokisia kwa kutumia data za mafunzo) na LLM iliyoongezwa RAG (inayoshirikiana na hati zako kwanza).* +*Mchoro huu unaonyesha tofauti kati ya LLM ya kawaida (inayokisia kutoka data ya mafunzo) na LLM iliyoimarishwa na RAG (inayekagua hati zako kwanza).* -Hapa ni jinsi vipande vinavyounganishwa mwisho hadi mwisho. Swali la mtumiaji hupitia hatua nne — kuingizwa, utafutaji wa vector, ukusanyaji wa muktadha, na uzalishaji wa jibu — kila moja likijenga juu ya ile iliyotangulia: +Hapa ni jinsi sehemu zinavyounganishwa mwisho kwa mwisho. Swali la mtumiaji linapitia hatua nne — embedding, utafutaji wa vector, ukusanyaji wa muktadha, na utengenezaji wa jibu — kila moja ikijengwa juu ya ile iliyotangulia: -RAG Architecture +Ujenzi wa RAG -*Mchoro huu unaonyesha mpangilio wa RAG kutoka mwanzo hadi mwisho — swali la mtumiaji hupitia kuingizwa, utafutaji wa vector, ukusanyaji wa muktadha, na uzalishaji wa jibu.* +*Mchoro huu unaonyesha mfumo wa RAG kuanzia mwanzo hadi mwisho — swali la mtumiaji linapitia embedding, utafutaji wa vector, ukusanyaji wa muktadha, na utengenezaji wa jibu.* -Sehemu zingine za moduli hii huenda hatua kwa hatua, kwa maelezo ya kina, na pamoja na msimbo unaoweza kuendesha na kuubadilisha. +Sehemu zilizobaki za moduli hii hutembea kwa kila hatua kwa undani, pamoja na msimbo unaoweza kuendesha na kuubadilisha. -### Ni Njia Gani ya RAG Inayotumika Katika Mafunzo Haya? +### Ni Mbinu Gani ya RAG Inayotumika Katika Mafunzo Haya? -LangChain4j hutoa njia tatu za kutekeleza RAG, kila moja ikiwa na kiwango tofauti cha ujumuishaji. Mchoro ulio hapa chini unalinganisha njia hizo pande kwa pande: +LangChain4j hutoa njia tatu za kutekeleza RAG, kila moja ikiwa na kiwango tofauti cha abstraction. Mchoro huu hapa chini unazilinganisha pembeni kwa pembeni: -Three RAG Approaches in LangChain4j +Njia Tatu za RAG katika LangChain4j -*Mchoro huu unalinganisha njia tatu za RAG za LangChain4j — Rahisi, Asili, na Zaidi — unaonyesha vipengele muhimu na wakati wa kutumia kila moja.* +*Mchoro huu unalinganisha njia tatu za RAG za LangChain4j — Rahisi, Asili, na Yaliyokithiri — ukiwaonyesha vipengele muhimu na wakati wa kutumia kila moja.* -| Njia | Kinachofanya | Ushindani | +| Njia | Kifuniko | Mabadiliko | |---|---|---| -| **RAG Rahisi** | Huunganisha kila kitu moja kwa moja kupitia `AiServices` na `ContentRetriever`. Unachora interface, unambatanisha retriever, na LangChain4j hushughulikia kuingiza, kutafuta, na ukusanyaji wa maelekezo nyuma ya pazia. | Msimbo mdogo, lakini hauoni kinachotokea hatua kwa hatua. | -| **RAG ya Asili** | Unaita mfano wa kuingiza, unatafuta duka, unajenga maelekezo, na kuzalisha jibu mwenyewe — kila hatua wazi. | Msimbo mwingi, lakini kila hatua inaonekana na inaweza kubadilishwa. | -| **RAG ya Zaidi** | Inatumia mfumo wa `RetrievalAugmentor` wenye badilishaji za kuuliza, marubaini, wawekaji upya wa alama, na waingiza maudhui kwa mifumo ya uzalishaji wa kiwango cha juu. | Uwezo mkubwa zaidi, lakini changamoto kubwa. | +| **Rahisi RAG** | Huunganisha kila kitu moja kwa moja kupitia `AiServices` na `ContentRetriever`. Unatia alama kiolesura, unafunga retriever, na LangChain4j hushughulikia embedding, utafutaji, na ukusanyaji wa maelekezo nyuma ya pazia. | Msimbo mdogo, lakini huoni kinachotokea kila hatua. | +| **Asili RAG** | Unaita modeli ya embedding, kutafuta hazina, kujenga maelekezo, na kutengeneza jibu mwenyewe — hatua moja kwa moja kila wakati. | Msimbo mwingi, lakini kila hatua inaonekana na inaweza kubadilika. | +| **Yaliyokithiri RAG** | Inatumia mfumo wa `RetrievalAugmentor` wenye weka query transformers, routers, re-rankers, na wapachaji wa maudhui kwa mifumo ya ngazi ya uzalishaji. | Ubadilikaji mkubwa, lakini ugumu mkubwa. | -**Mafunzo haya yanatumia Njia ya Asili.** Kila hatua ya mtiririko wa RAG — kuingiza swali, kutafuta duka la vector, kukusanya muktadha, na kuzalisha jibu — umeandikwa wazi katika [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Hii ni kwa makusudi: kama rasilimali ya kujifunza, ni muhimu zaidi kuona na kuelewa kila hatua kuliko kupunguza msimbo. Ukijua vizuri jinsi vipande vinaunganishwa, unaweza kuhamia RAG Rahisi kwa majaribio ya haraka au RAG ya Zaidi kwa mifumo ya uzalishaji. +**Mafunzo haya yanatumia Njia ya Asili.** Kila hatua ya mfumo wa RAG — kuweka query kwenye embedding, kutafuta hazina ya vector, kukusanya muktadha, na kutengeneza jibu — imeandikwa wazi katika [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Hii ni kwa makusudi: kama rasilimali ya kujifunza, ni muhimu zaidi kuona na kuelewa kila hatua kuliko kupunguza msimbo. Mara ukijua jinsi vipande vinavyoungana, unaweza kusonga hadi Rahisi RAG kwa prototypes haraka au Yaliyokithiri RAG kwa mifumo halisi. -> **💡 Umewahi kuona RAG Rahisi ikifanya kazi?** Moduli ya [Mwanzo wa Haraka](../00-quick-start/README.md) ina mfano wa Maswali na Majibu ya Hati ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) unaotumia njia ya RAG Rahisi — LangChain4j hushughulikia kuingiza, kutafuta, na ukusanyaji wa maelekezo moja kwa moja. Moduli hii inafuata hatua inayofuata kwa kufungua mtiririko huo ili uweze kuona na kudhibiti kila hatua mwenyewe. +> **💡 Unataka kujua zaidi kuhusu Rahisi RAG?** LangChain4j pia hutoa njia ya *Rahisi RAG* ambapo `AiServices` na `ContentRetriever` hushughulikia embedding, utafutaji, na ukusanyaji wa maelekezo moja kwa moja. Moduli hii inafuata njia wazi zaidi — kufungua mfumo huu ili uone na kudhibiti kila hatua wewe mwenyewe. -Mchoro ulio hapa chini unaonyesha mtiririko wa RAG Rahisi kutoka kwa mfano wa Mwanzo wa Haraka. Angalia jinsi `AiServices` na `EmbeddingStoreContentRetriever` vinavyoficha ugumu wote — unapakia hati, unambatanisha retriever, na kupata majibu. Njia ya Asili katika moduli hii hufungua kila hatua zilizofichwa: +Mchoro huu chini unaonyesha mfumo wa Rahisi RAG. Angalia jinsi `AiServices` na `EmbeddingStoreContentRetriever` vinavyoficha ugumu wote — unapakia hati, unafunga retriever, na kupokea majibu. Njia ya Asili katika moduli hii huvunja hatua zote zilizofichwa: -Easy RAG Pipeline - LangChain4j +Mfumo wa Rahisi RAG - LangChain4j -*Mchoro huu unaonyesha mtiririko wa RAG Rahisi kutoka `SimpleReaderDemo.java`. Linganisha na Njia ya Asili inayotumika katika moduli hii: RAG Rahisi huficha kuingiza, upataji, na ukusanyaji wa maelekezo nyuma ya `AiServices` na `ContentRetriever` — unapakia hati, unambatanisha retriever, na unapata majibu. Njia ya Asili katika moduli hii hufungua mtiririko huo ili wewe uite kila hatua (kuingiza, kutafuta, kukusanya muktadha, kuzalisha) mwenyewe, ikikupa uwazi kamili na udhibiti.* +*Mchoro huu unaonyesha mfumo wa Rahisi RAG. Linganisha na Njia ya Asili inayotumika katika moduli hii: Rahisi RAG inaficha embedding, urejeshaji, na ukusanyaji wa maelekezo nyuma ya `AiServices` na `ContentRetriever` — unapakia hati, unaweka retriever, na kupata majibu. Njia ya Asili katika moduli hii huvunja mfumo huu kwa wito moja kwa moja wa kila hatua (embedding, kutafuta, kukusanya muktadha, kutengeneza) kwa udhibiti kamili.* ## Jinsi Inavyofanya Kazi -Mtiririko wa RAG katika moduli hii unajumuisha hatua nne zinazofuatana kila wakati mtumiaji anapouliza swali. Kwanza, hati iliyopakuliwa inatafsiriwa na kugawanywa katika vipande vinavyoweza kusimamiwa. Vipande hivyo hubadilishwa kuwa embeddings za vector na kuhifadhiwa ili ziweze kulinganishwa kihisabati. Wakati swali linapokuja, mfumo unafanya utafutaji wa kisemi kupata vipande vinavyofaa, na hatimaye huvipitisha kama muktadha kwa LLM kwa ajili ya uzalishaji wa jibu. Sehemu zilizo hapa chini zinaelezea kila hatua kwa msimbo halisi na michoro. Hebu tuangalie hatua ya kwanza. +Mfumo wa RAG moduli hii unagawanywa katika hatua nne zinazofanyika mfululizo kila mtu anapouliza swali. Kwanza, hati iliyopakuliwa **huchambuliwa na kugawanywa** vipande vidogo vinavyoweza kudhibitiwa. Vipande hivyo hubadilishwa kuwa **embedding za vector** na kuhifadhiwa ili ziweze kulinganishwa kwa kihisabati. Mtu anapouliza, mfumo hufanya **utafutaji wa kimaana** kupata vipande vinavyofaa, na mwishowe huvifanyia kazi kama muktadha kwa LLM kwa ajili ya **kutengeneza jibu**. Sehemu zilizofuata zinaonyesha kila hatua kwa msimbo halisi na michoro. Tuchunguze hatua ya kwanza. ### Usindikaji wa Hati [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Unapopakua hati, mfumo huichambua (PDF au maandishi ya kawaida), huambatanisha metadata kama jina la faili, na kisha hugawanya kuwa vipande — vipande vidogo vinavyolingana vizuri na dirisha la muktadha la mfano. Vipande hivi vinafanana kidogo ili usipoteze muktadha kwenye mipaka. +Unapopakua hati, mfumo huichambua (PDF au maandishi ya kawaida), huambatanisha metadata kama jina la faili, kisha hugawanya hati vipande — vipande vidogo vinavyofaa katika dirisha la muktadha la modeli. Vipande hivi vinagusana kidogo kuhakikisha huwezi kupoteza muktadha kwenye mipaka. ```java // Tafsiri faili lililopakiwa na lifunge katika Hati ya LangChain4j Document document = Document.from(content, metadata); -// Gawanya katika vipande vya tokeni 300 na mgongano wa tokeni 30 +// Gawanya katika vipande vya tokeni 300 na mduara wa tokeni 30 DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` + +Mchoro huu unaonyesha jinsi inavyofanya kazi kimaono. Angalia jinsi kila kipande kinashiriki tokeni kadhaa na majirani zake — mgusano wa tokeni 30 huhakikisha hakuna muktadha muhimu unaopotea kati ya vipande: -Mchoro ulio hapa chini unaonyesha jinsi hili linavyofanya kazi kwa picha. Angalia jinsi kila kipande kinashirikiana tokens na viungo vyake — kufanana kwa tokens 30 huhakikisha hakuna muktadha muhimu unaporejea pembeni: +Mgawanyo wa Hati -Document Chunking +*Mchoro huu unaonyesha hati ikigawanywa vipande vya tokeni 300 na mgusano wa tokeni 30, kudumisha muktadha kwenye mipaka ya vipande.* -*Mchoro huu unaonyesha hati ikigawanywa kuwa vipande vya token 300 vyenye kufanana kwa token 30, ikihifadhi muktadha katika mipaka ya vipande.* +> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) na uulize: +> - "LangChain4j hugawanya hati vipande vipi na kwa nini mgusano ni muhimu?" +> - "Ni ukubwa gani wa kipande kilichopendekezwa kwa aina tofauti za hati na kwa nini?" +> - "Namshughulikiaje hati katika lugha nyingi au zilizo na muundo maalum?" -> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) na uliza: -> - "Je, LangChain4j huigawanya hati vipande vipi na kwa nini kufanana ni muhimu?" -> - "Ni ukubwa gani sahihi wa kipande kwa aina tofauti za hati na kwa nini?" -> - "Nashughulikiaje hati kwa lugha nyingi au zenye muundo maalum?" - -### Kuumba Embeddings +### Kuunda Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Kipande kila kimebadilishwa kuwa maelezo ya nambari yanayoitwa embedding — kwa maana ni mfafanuzi wa maana kwenda kwa nambari. Mfano wa embedding si "mwerevu" kama vile mfano wa mazungumzo; hawezi kufuata maagizo, kutafakari, au kujibu maswali. Kinachoweza kufanya ni kuweka maandishi katika nafasi ya kihesabu ambapo maana zinazofanana ziko karibu — "gari" karibu na "magari," "sera ya kurejesha fedha" karibu na "rudisha fedha zangu." Fikiria mfano wa mazungumzo kama mtu unayemzungumza; mfano wa embedding ni mfumo bora wa kuhifadhi hati. +Kipande kila kimebadilishwa kuwa uwasilishaji wa nambari unaoitwa embedding — kwa kiasi fulani mabadiliko ya maana kuwa nambari. Modeli ya embedding sio "mwerevu" kama modeli ya mazungumzo; haifuati maelekezo, haifikirii, wala haijibu maswali. Kinachoweza kufanya ni kuweka maandishi katika sehemu ya kihisabati ambapo maana zinazofanana hujipanga karibu — kama "gari" karibu na "magari," "sera ya kurejesha" karibu na "rejesha fedha." Fikiria modeli ya mazungumzo kama mtu unayezungumza naye; modeli ya embedding ni mfumo mzuri sana wa kuhifadhi taarifa. -Mchoro ulio hapa chini unaonyesha dhana hii — maandishi yanaingia, vector wa nambari yanatoka, na maana zinazofanana hutoa vector za karibu: +Mchoro huu unaonyesha dhana — maandishi huingia, vector za nambari hutoka, na maana zinazofanana huleta vector karibu: -Embedding Model Concept +Dhana ya Modeli ya Embedding -*Mchoro huu unaonyesha jinsi mfano wa embedding hubadilisha maandishi kuwa vector za nambari, ukiweka maana zinazofanana — kama "gari" na "magari" — karibu katika nafasi ya vector.* +*Mchoro huu unaonyesha jinsi modeli ya embedding hubadilisha maandishi kuwa vector za nambari, kuweka maana zinazofanana — kama "gari" na "magari" — karibu katika nafasi ya vector.* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` + +Mchoro wa darasa huu unaonyesha mwelekeo miwili tofauti katika mfumo wa RAG na madarasa ya LangChain4j yanayoyatekeleza. **Mwelekeo wa kuingiza** (hufanyika mara moja wakati wa upakiaji) hugawanya hati, huingiza vipande kwenye embedding, na kuhifadhi kupitia `.addAll()`. **Mwelekeo wa swali** (hufanyika kila mtumiaji anapouliza) huingiza swali kwenye embedding, kutafuta hazina kwa `.search()`, na kupitisha muktadha unaolingana kwa modeli ya mazungumzo. Mwelekeo yote hukutana kwenye kiolesura cha pamoja `EmbeddingStore`: -Mchoro wa darasa ulio hapa chini unaonyesha mtiririko miwili katika mtiririko wa RAG na madarasa ya LangChain4j yanayotekeleza. **Mtiririko wa ingizo** (unayotekeleza mara moja wakati wa upakiaji) hugawanya hati, huingiza vipande, na kuvitunza kupitia `.addAll()`. **Mtiririko wa swali** (unapotekelezwa kila mtu anapouliza) huingiza swali, hufanya utafutaji kwenye duka kupitia `.search()`, na hupitisha muktadha wanaoungana kwa mfano wa mazungumzo. Mitiririko yote hukutana kwenye kiolesura cha pamoja `EmbeddingStore`: - -LangChain4j RAG Classes +Madarasa ya LangChain4j RAG -*Mchoro huu unaonyesha mitiririko miwili katika mtiririko wa RAG — ingizo na swali — na jinsi vinavyounganishwa kupitia EmbeddingStore ya pamoja.* +*Mchoro huu unaonyesha mwelekeo miwili katika mfumo wa RAG — kuingiza na swali — na jinsi unavyounganishwa kupitia EmbeddingStore.* -Mara embeddings zinahifadhiwa, maudhui yanayolingana hujikusanya kiasili pamoja katika nafasi ya vector. Uonyeshaji hapa chini unaonyesha jinsi hati kuhusu mada zinazohusiana zinaishia kama pointi za karibu, ambacho ndicho kinachowezesha utafutaji wa kisemi: +Mara embeddings zinapohifadhiwa, maudhui yanayofanana huwa karibu kwenye nafasi ya vector. Visualize ifuatayo inaonyesha jinsi hati za mada zinazohusiana hujipanga kama pointi karibu, jambo linalofanya utafutaji wa kimaana uwezekane: -Vector Embeddings Space +Nafasi za Vector za Embeddings -*Uonyeshaji huu unaonyesha jinsi hati zinazohusiana hukusanyika pamoja katika nafasi ya vector ya 3D, na mada kama Hati za Kiufundi, Kanuni za Biashara, na Maswali ya Mara kwa Mara zikiwa vikundi tofauti.* +*Visualize hii inaonyesha jinsi hati zinazohusiana hujipanga pamoja katika nafasi ya vector 3D, kwa mada kama Hati za Kiufundi, Sheria za Biashara, na Maswali Yanayoulizwa Mara kwa Mara (FAQ) kuunda makundi tofauti.* -Mtumiaji anapofanya utafutaji, mfumo hufuata hatua nne: kuingiza hati mara moja, kuingiza swali kila utafutaji, kulinganisha vector ya swali na vector zote zilizo hapo duka kwa kutumia uwiano wa cosine, na kurudisha vipande vinavyoongoza kulingana na alama za juu. Mchoro hapa chini unaelezea kila hatua na madarasa ya LangChain4j yanayohusika: +Mtumiaji anapofanya utafutaji, mfumo hufuata hatua nne: kuingiza hati mara moja, kuingiza swali kila utafutaji, kulinganisha vector ya swali dhidi ya vector zote zilizohifadhiwa kwa kutumia cosine similarity, na kurudisha vipande-K vinavyopata alama za juu. Mchoro huu unaelezea kila hatua na madarasa ya LangChain4j yanayohusika: -Embedding Search Steps +Hatua za Utafutaji wa Embedding -*Mchoro huu unaonyesha mchakato wa hatua nne wa utafutaji wa embedding: kuingiza hati, kuingiza swali, kulinganisha vector kwa uwiano wa cosine, na kurudisha matokeo ya juu-K.* +*Mchoro huu unaonesha mchakato wa hatua nne wa utafutaji wa embedding: kuingiza hati, kuingiza swali, kulinganisha vector kwa cosine similarity, na kurudisha matokeo ya juu-K.* -### Utafutaji wa Kisemi +### Utafutaji wa Kimaana [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Unapouliza swali, swali lako pia hubadilishwa kuwa embedding. Mfumo hulinganisha embedding ya swali lako na embeddings zote za vipande vya hati. Hupata vipande vyenye maana zinazofanana zaidi - sio tu maneno yanayolingana, bali maana halisi za mtu. +Unapouliza swali, swali lako pia hubadilishwa kuwa embedding. Mfumo hulilinganisha embedding ya swali lako dhidi ya embeddings za vipande vyote vya hati. Hupata vipande vinavyofanana zaidi maana — si tu maneno yanayolingana, bali ulinganifu wa maana halisi. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` + +Mchoro huu unaonyesha tofauti ya utafutaji wa kimaana na utafutaji wa kawaida wa maneno muhimu (keywords). Utafutaji wa maneno "gari" hupoteza kipande kuhusu "magari na malori," lakini utafutaji wa kimaana unaelewa maana zao ni sawa na kurudisha kipande hicho kama jibu lenye alama za juu: -Mchoro hapa chini unaonyesha tofauti ya utafutaji wa kisemi na utafutaji wa neno kuu wa kawaida. Utafutaji wa neno kuu kwa "gari" haupati kipande kuhusu "magari na malori," lakini utafutaji wa kisemi unaelewa maana yao ni sawa na kurudisha kipande hicho kama chenye alama ya juu: - -Semantic Search +Utafutaji wa Kimaana -*Mchoro huu unalinganisha utafutaji wa maneno muhimu na utafutaji wa kisemi, unaoonyesha jinsi utafutaji wa kisemi unavyopata maudhui yanayohusiana kifikra hata maneno halisi yapotofautiana.* -Chini ya kifuniko, umafananisho hupimwa kwa kutumia umafananisho wa cosine — kwa msingi kuuliza "je, mishale hii miwili inaelekeana upande mmoja?" Vipande viwili vinaweza kutumia maneno tofauti kabisa, lakini kama zinamaanisha jambo kama hilo mihimili yao inaelekeana upande mmoja na hupata alama karibu na 1.0: +*Mchoro huu unaonyesha utafutaji wa maneno ukilinganisha na utafutaji wa kimaana, unaonesha jinsi utafutaji wa kimaana unavyorudisha maudhui yanayohusiana kifikra hata maneno halisi yakibadilika.* -Cosine Similarity +Sehemu za ndani, ulinganifu unakokotolewa kwa kutumia cosine similarity — kwa kiasi fulani kuuliza "je, vipeo hivi viwili vinaelekea katika mwelekeo mmoja?" Vipande viwili vinaweza kutumia maneno kabisa tofauti, lakini kama maana ni ile ile vector zao zinaelekea njia kama moja na kupata alama karibu na 1.0: -*Michoro hii inaonyesha umafananisho wa cosine kama pembe kati ya mihimili ya uingizaji — mihimili inayolingana zaidi hupata alama karibu na 1.0, ikionyesha umafananisho mkubwa wa maana.* +Ulinganifu wa Cosine +*Michoro hii inaonyesha ulinganifu wa cosine kama pembe kati ya vekta za uingizaji — vekta zinazolingana zaidi hupata alama karibu na 1.0, zikionyesha ulinganifu mkubwa wa semantiki.* > **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) na uliza: -> - "Utafutaji wa umafananisho hufanya kazi vipi na uingizaji na nini huchagua alama?" -> - "Kigezo gani cha umafananisho ninapaswa kutumia na kinaathirije matokeo?" -> - "Nashughulikiaje kesi ambapo hakuna nyaraka zinazohusiana zinazopatikana?" +> - "Utafutaji wa ulinganifu hufanya kazi vipi na uingizaji na nini huamua alama?" +> - "Kiwango gani cha ulinganifu nifanye na huathirije matokeo?" +> - "Nashughulikiaje hali ambapo hakuna hati zinazofaa zilizopatikana?" -### Uundaji wa Jibu +### Uundaji wa Majibu [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Vipande vinavyofaa zaidi huunganishwa kuwa amri iliyopangwa inayojumuisha maagizo wazi, muktadha uliochukuliwa, na swali la mtumiaji. Mfano husoma vipande hivyo maalum na kujibu kulingana na taarifa hiyo — unaweza kutumia tu kilicho mbele yake, jambo ambalo linazuia kuibua habari isiyo ya kweli. +Vigawanyo muhimu zaidi huunganishwa kuwa ingizo lililo na muundo linalojumuisha maelekezo wazi, muktadha uliopatikana, na swali la mtumiaji. Mfano husoma vigawanyo hivyo maalum na kujibu kwa msingi wa taarifa hizo — unaweza tu kutumia kile kilicho mbele yake, ambacho kinazuia ubunifu usio wa kweli. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Michoro ifuatayo inaonyesha uunganishaji huu ukiwa kazini — vipande vinavyopata alama ya juu kutoka hatua ya utafutaji huingizwa ndani ya kiolezo cha amri, na `OpenAiOfficialChatModel` huunda jibu lililo na msingi: +Michoro hapa chini inaonyesha mchakato huu ukiwa kazi — vigawanyo vina alama ya juu kutoka hatua ya utafutaji vinaingizwa kwenye kiolezo cha ingizo, na `OpenAiOfficialChatModel` hutengeneza jibu lililo na msingi: Context Assembly -*Michoro hii inaonyesha jinsi vipande vinavyopata alama ya juu vinavyojumuishwa kuwa amri iliyopangwa, ikiruhusu mfano kutoa jibu lenye msingi kutoka kwa data yako.* +*Michoro hii inaonyesha jinsi vigawanyo vya alama za juu vinavyounganishwa kuwa ingizo lenye muundo, likiruhusu mfano kutoa jibu lililo na msingi kutoka kwa data yako.* ## Endesha Programu -**Thibitisha usanidi:** +**Thibitisha usanifu:** -Hakikisha faili `.env` ipo katika saraka kuu na ina taarifa za sera za Azure (zilizoanzishwa wakati wa Moduli 01). Endesha kutoka kwenye saraka ya moduli (`03-rag/`): +Hakikisha faili `.env` ipo kwenye saraka kuu ikiwa na leseni za Azure (zilizoanzishwa wakati wa Moduli 01). Endesha hii kutoka kwenye saraka ya moduli (`03-rag/`): **Bash:** ```bash @@ -261,41 +260,41 @@ Get-Content ..\.env # Inapaswa kuonyesha AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOY **Anzisha programu:** -> **Kumbuka:** Ikiwa tayari umeanza programu zote kwa kutumia `./start-all.sh` kutoka saraka kuu (kama ilivyoelezwa Moduli 01), moduli hii tayari inaendeshwa kwa bandari 8081. Unaweza kuruka amri za kuanzisha hapo chini na kwenda moja kwa moja http://localhost:8081. +> **Kumbuka:** Ikiwa tayari umeanzisha programu zote kwa kutumia `./start-all.sh` kutoka saraka kuu (kama ilivyoelezwa katika Moduli 01), moduli hii tayari inafanya kazi kwa bandari 8081. Unaweza kuruka amri za kuanzisha hapa chini na kwenda moja kwa moja http://localhost:8081. -**Chaguo la 1: Kutumia Spring Boot Dashboard (Inapendekezwa kwa watumiaji wa VS Code)** +**Chaguo 1: Kutumia Spring Boot Dashboard (Inapendekezwa kwa watumiaji wa VS Code)** -Kontena ya maendeleo ina nyongeza ya Spring Boot Dashboard, inayotoa kiolesura cha kuona na kudhibiti programu zote za Spring Boot. Unaweza kuipata kwenye Ukurasa wa Shughuli upande wa kushoto wa VS Code (angalia ikoni ya Spring Boot). +Kontena la maendeleo linajumuisha ugani wa Spring Boot Dashboard, unaotoa interface ya kuona kwa kusimamia programu zote za Spring Boot. Unaweza kulikuta kwenye Barua ya Shughuli upande wa kushoto wa VS Code (tazama ikoni ya Spring Boot). -Kutoka Spring Boot Dashboard, unaweza: -- Kuona programu zote za Spring Boot zinazopatikana katika eneo la kazi -- Anzisha/zuia programu kwa kubofya mara moja +Kutoka kwenye Spring Boot Dashboard, unaweza: +- Kuona programu zote za Spring Boot zilizopo katika sehemu ya kazi +- Anza/acha programu kwa bonyeza moja - Tazama kumbukumbu za programu kwa wakati halisi -- Fuata hali ya programu +- Fuatilia hali ya programu -Bofya tu kitufe cha kuanzia kando ya "rag" kuanzisha moduli hii, au anzisha moduli zote kwa pamoja. +Bonyeza kitufe cha kuanza kando ya "rag" kuanzisha moduli hii, au anza moduli zote mara moja. Spring Boot Dashboard -*Picha hii inaonyesha Spring Boot Dashboard katika VS Code, ambapo unaweza kuanzisha, kuzuia, na kufuatilia programu kwa njia ya kuona.* +*Picha hii inaonyesha Spring Boot Dashboard katika VS Code, ambapo unaweza kuanzisha, kuacha, na kufuatilia programu kwa njia ya kuona.* -**Chaguo la 2: Kutumia script za shell** +**Chaguo 2: Kutumia mifumo ya shell** Anzisha programu zote za wavuti (moduli 01-04): **Bash:** ```bash -cd .. # Kutoka kwenye saraka ya mizizi +cd .. # Kutoka kwenye saraka msingi ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Kutoka kwa saraka ya mzizi +cd .. # Kutoka kwa saraka ya mizizi .\start-all.ps1 ``` -Au anzisha moduli hii tu: +Au anza moduli hii tu: **Bash:** ```bash @@ -309,25 +308,25 @@ cd 03-rag .\start.ps1 ``` -Script zote zinapakia moja kwa moja vigezo vya mazingira kutoka faili la `.env` la saraka kuu na zitajenga faili za JAR ikiwa hazipo. +Skripti zote huzidisha kwa moja mabadiliko ya mazingira kutoka kwenye faili `.env` ya saraka kuu na zitaandika JAR ikiwa hazipo. -> **Kumbuka:** Ikiwa unapotaka kujenga moduli zote kwa mikono kabla ya kuanzisha: +> **Kumbuka:** Ikiwa unapendelea kujenga moduli zote kwa mkono kabla ya kuanzisha: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Fungua http://localhost:8081 kwenye kivinjari chako. +Fungua http://localhost:8081 katika kivinjari chako. -**Kuzima:** +**Kusitisha:** **Bash:** ```bash @@ -338,100 +337,100 @@ cd .. && ./stop-all.sh # Moduli zote **PowerShell:** ```powershell -.\stop.ps1 # Moduli hii tu +.\stop.ps1 # Hii moduli tu # Au cd ..; .\stop-all.ps1 # Moduli zote ``` ## Kutumia Programu -Programu hutoa kiolesura cha wavuti kwa ajili ya kupakia nyaraka na kuuliza maswali. +Programu hutoa interface ya wavuti kwa ajili ya kupakia hati na kuuliza maswali. RAG Application Interface -*Picha hii inaonyesha kiolesura cha programu ya RAG ambacho unapakiza nyaraka na kuuliza maswali.* +*Picha hii inaonyesha interface ya programu ya RAG ambapo unapakia hati na kuuliza maswali.* -### Pakia Nyaraka +### Pakia Hati -Anza kwa kupakia nyaraka - faili za TXT zinafanya vizuri kwa ajili ya majaribio. Faili la `sample-document.txt` limewekwa katika saraka hii linayoelezea kuhusu vipengele vya LangChain4j, utekelezaji wa RAG, na mbinu bora - bora kwa kujaribu mfumo. +Anza kwa kupakia hati - faili za TXT ndizo bora za majaribio. Faili `sample-document.txt` ipo katika saraka hii ikiwa na taarifa kuhusu vipengele vya LangChain4j, utekelezaji wa RAG, na mbinu bora - bora kwa kujaribu mfumo. -Mfumo unashughulikia nyaraka yako, kuigawa vipande, na kuunda uingizaji kwa kila kipande. Hii hufanyika moja kwa moja unapo upload. +Mfumo huchakata hati yako, hugawanya kuwa vigawanyo, na hutengeneza uingizaji kwa kila kipande. Hii hufanyika moja kwa moja unapopakua. ### Uliza Maswali -Sasa uliza maswali maalum kuhusu maudhui ya nyaraka. Jaribu jambo la kweli lililoonyeshwa wazi katika nyaraka. Mfumo unatafuta vipande vinavyohusiana, huvijumuisha katika amri, na hutoa jibu. +Sasa uliza maswali maalum kuhusu maudhui ya hati. Jaribu kitu cha kweli ambacho kimeelezwa wazi katika hati. Mfumo unatafuta vigawanyo vinavyofaa, vina jumuishwa katika ingizo, na hutengeneza jibu. -### Angalia Marejeo ya Chanzo +### Angalia Marejeleo ya Chanzo -Tambua kila jibu lina marejeo ya chanzo na alama za umafananisho. Alama hizi (0 hadi 1) zinaonyesha jinsi vipande vilivyohusiana na swali lako. Alama za juu zina maana ya mechi bora. Hii hukuwezesha kuthibitisha jibu dhidi ya nyaraka za chanzo. +Angalia kila jibu linajumuisha marejeleo ya chanzo pamoja na alama za ulinganifu. Alama hizi (0 hadi 1) zinaonyesha jinsi kila kipande kilivyohusiana na swali lako. Alama za juu zinamaanisha mechi bora. Hii inakuwezesha kuthibitisha jibu dhidi ya nyaraka za chanzo. RAG Query Results -*Picha hii inaonyesha matokeo ya utaftaji pamoja na jibu lililoundwa, marejeo ya chanzo, na alama za umafananisho kwa kila kipande kilichopatikana.* +*Picha hii inaonyesha matokeo ya maswali pamoja na jibu lililotengenezwa, marejeleo ya chanzo, na alama za uhusiano kwa kila kipande kilichopatikana.* ### Jaribu Maswali Tofauti Jaribu aina tofauti za maswali: -- Ukweli maalum: "Nini mada kuu?" -- Ulinganisho: "Nini tofauti kati ya X na Y?" -- Muhtasari: "Fupisha sehemu muhimu kuhusu Z" +- Ukweli maalum: "Mada kuu ni nini?" +- Mlinganisho: "Je, tofauti kati ya X na Y ni ipi?" +- Muhtasari: "Fupisha mambo muhimu kuhusu Z" -Tazama jinsi alama za umafananisho zinavyobadilika kulingana na jinsi swali lako linavyolingana na maudhui ya nyaraka. +Tazama jinsi alama za uhusiano zinavyobadilika kulingana na jinsi swali lako linavyolingana na maudhui ya hati. -## Dhana Muhimu +## Dhahabu Muhimu -### Mkakati wa Kugawanya Vipande +### Mkakati wa Kugawanya Vigawanyo -Nyaraka hugawanywa katika vipande vya tokeni 300 na tokeni 30 zinashirikiana kati ya vipande. Mlingano huu unahakikisha kila kipande kina muktadha wa kutosha kuwa na maana wakati kinabaki kidogo kuwajumuisha vipande vingi katika amri. +Nyaraka hugawanywa kuwa vigawanyo vya tokeni 300 na tokeni 30 za mkusanyiko. Uwiano huu huhakikisha kila kipande kina muktadha wa kutosha kuwa na maana wakati pia kikibaki kidogo vya kutosha kuweza kujumuisha vigawanyo vingi katika ingizo. -### Alama za Umafananisho +### Alama za Ulinganifu -Kipande kila kinaletwa na alama ya umafananisho kati ya 0 na 1 inayoonyesha jinsi kinavyolingana na swali la mtumiaji. Michoro ifuatayo inaonyesha anuwai za alama na jinsi mfumo unavyotumia kusafisha matokeo: +Kila kipande kilichopatikana kina alama ya ulinganifu kati ya 0 na 1 inayoonyesha jinsi kinavyolingana na swali la mtumiaji. Michoro hapa chini inaonyesha viwango vya alama na jinsi mfumo unavyovitumia kuchuja matokeo: Similarity Scores -*Michoro hii inaonyesha anuwai za alama kutoka 0 hadi 1, na kigezo cha chini cha 0.5 kinachosema vipande visivyo husika visijumuishwe.* +*Michoro hii inaonyesha viwango vya alama kutoka 0 hadi 1, pamoja na kiwango cha chini cha 0.5 kinachochuja vigawanyo visivyo husika.* Alama zinatoka 0 hadi 1: -- 0.7-1.0: Zinahusiana sana, mechi halisi -- 0.5-0.7: Zinahusiana, muktadha mzuri -- Chini ya 0.5: Zinazitolewa, haziendani +- 0.7-1.0: Muhimu sana, mechi halisi +- 0.5-0.7: Muhimu, muktadha mzuri +- Chini ya 0.5: Inachujwa, haitofautiani vizuri -Mfumo unachukua vipande tu vilivyo juu ya kigezo cha chini kuhakikisha ubora. +Mfumo unachukua tu vigawanyo vilivyo juu ya kiwango cha chini kuhakikisha ubora. -Uingizaji hufanya kazi vizuri wakati maana za vikundi zinaonekana wazi, lakini huwa na sehemu zisizo wazi. Michoro ifuatayo inaonyesha vidhibiti vya kufeli vya kawaida — vipande vikubwa sana hutoa mihimili isiyo wazi, vipande vidogo sana havina muktadha, maneno yenye maana mbili yanaelekeza kwenye vikundi vingi, na maangalia mechi halisi (IDs, namba za sehemu) hayaendi na uingizaji kabisa: +Uingizaji hufanya kazi vizuri wakati maana inajitokeza waziwazi, lakini kuna maeneo yanayopotea. Michoro hapa chini inaonyesha aina za makosa ya kawaida — vigawanyo vikubwa sana hutoa vekta zisizo wazi, vigawanyo vidogo sana vinakosa muktadha, maneno yenye double maana huashiria makundi mengi, na utafutaji wa mechi halisi (IDs, nambari za sehemu) hauendani kabisa na uingizaji: Embedding Failure Modes -*Michoro hii inaonyesha aina za kawaida za kushindwa kwa uingizaji: vipande vikubwa sana, vipande vidogo sana, maneno yenye maana nyingi yanayoelekeza kwenye vikundi vingi, na utafutaji wa mechi halisi kama IDs.* +*Michoro hii inaonyesha aina za kawaida za makosa ya uingizaji: vigawanyo vikubwa sana, vidogo sana, maneno yenye mashaka yanayohusu makundi mengi, na utafutaji wa mechi halisi kama IDs.* -### Uhifadhi wa Kumbukumbu za Kiasi +### Uhifadhi wa Kumbukumbu Ndani -Moduli hii hutumia uhifadhi wa kumbukumbu za kiasi kwa ajili ya urahisi. Unaporudisha programu, nyaraka zilizopakiwa hupotea. Mifumo ya uzalishaji hutumia hifadhidata za vector zenye uhifadhi wa kudumu kama Qdrant au Azure AI Search. +Moduli hii hutumia uhifadhi wa kumbukumbu ndani kwa urahisi. Unapozima programu, nyaraka zilizopakiwa hupotea. Mifumo ya uzalishaji hutumia hifadhidata za vekta zinazodumu kama Qdrant au Azure AI Search. ### Usimamizi wa Dirisha la Muktadha -Mfano wowote una dirisha la muktadha kwa kiwango cha juu. Huwezi kujumuisha kila kipande kutoka kwenye nyaraka kubwa. Mfumo hunyakua vipande vinavyolingana zaidi N (kawaida 5) ili kubaki katika mipaka huku ukitoa muktadha wa kutosha kwa majibu sahihi. +Kila mfano una ukubwa wa juu wa dirisha la muktadha. Huwezi kujumuisha kila kipande kutoka kwa hati ndefu. Mfumo unachukua vigawanyo muhimu N (chaguo-msingi 5) ili kubaki ndani ya mipaka huku ukitoa muktadha wa kutosha kwa majibu sahihi. ## Wakati RAG Inafaa -RAG si kila wakati ni njia sahihi. Mwongozo wa uamuzi hapa chini utakusaidia kuamua wakati RAG huongeza thamani dhidi ya njia rahisi — kama kujumuisha maudhui moja kwa moja kwenye amri au kutegemea ujuzi uliopo wa mfano — ni wa kutosha: +RAG sio njia sahihi kila wakati. Mwongozo wa maamuzi hapa chini unakusaidia kujua wakati RAG huongeza thamani dhidi ya njia rahisi — kama kujumuisha maudhui moja kwa moja katika ingizo au kutegemea maarifa yaliyojengewa ndani ya mfano — ni za kutosha: When to Use RAG -*Michoro hii inaonyesha mwongozo wa uamuzi wa wakati RAG huongeza thamani dhidi ya wakati njia rahisi zinafaa.* +*Michoro hii inaonyesha mwongozo wa maamuzi wakati RAG huongeza thamani dhidi ya njia rahisi zilizotosheleza.* ## Hatua Zifuatazo -**Moduli Inayofuata:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Moduli Ifuatayo:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**Uvinjari:** [← Ilivyopita: Moduli 02 - Uhandisi wa Amri](../02-prompt-engineering/README.md) | [Rudi Kwenye Msingi](../README.md) | [Ifuatayo: Moduli 04 - Zana →](../04-tools/README.md) +**Unavyo:** [← Iliyopita: Moduli 02 - Ufundi wa Ingizo](../02-prompt-engineering/README.md) | [Rudi Kwenye Msingi](../README.md) | [Ifuatayo: Moduli 04 - Zana →](../04-tools/README.md) --- -**Kielelezo cha Kujiweka Huru**: -Nyaraka hii imetafsiriwa kwa kutumia huduma ya kutafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri zilizotengenezwa kiotomatiki zinaweza kuwa na makosa au kasoro. Nyaraka ya asili katika lugha yake ya asili inapaswa kuzingatiwa kama chanzo kikuu cha ukweli. Kwa taarifa muhimu, tunapendekeza tafsiri ya kitaalamu na mtu mzima. Hatuna dhamana kwa kutoelewana au tafsiri zisizofaa zitokanazo na kutumia tafsiri hii. +**Kionyozo**: +Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake halisi inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inapendekezwa. Hatutojibu kwa kuelewa vibaya au tafsiri potofu zinazotokea kutokana na matumizi ya tafsiri hii. \ No newline at end of file diff --git a/translations/sw/04-tools/README.md b/translations/sw/04-tools/README.md index 7e39f6fb4..6872baafc 100644 --- a/translations/sw/04-tools/README.md +++ b/translations/sw/04-tools/README.md @@ -1,84 +1,84 @@ -# Sehemu ya 04: Maajenti wa AI Wenye Vifaa +# Moduli 04: Wakala wa AI Wenye Zana -## Jedwali la Yaliyomo +## Yaliyomo -- [Ufafanuzi wa Video](../../../04-tools) -- [Utachojifunza](../../../04-tools) -- [Masharti ya Awali](../../../04-tools) -- [Kuelewa Maajenti wa AI Wenye Vifaa](../../../04-tools) -- [Jinsi Kuitwa kwa Kifaa Kunavyofanya Kazi](../../../04-tools) - - [Maelezo ya Vifaa](../../../04-tools) - - [Uamuzi](../../../04-tools) - - [Utekelezaji](../../../04-tools) - - [Uundaji wa Majibu](../../../04-tools) - - [Mimino: Kubana Moja kwa Moja Spring Boot](../../../04-tools) -- [Ufuatiliaji wa Vifaa](../../../04-tools) -- [Endesha Programu](../../../04-tools) -- [Kutumia Programu](../../../04-tools) - - [Jaribu Matumizi Rahisi ya Kifaa](../../../04-tools) - - [Jaribu Ufuatiliaji wa Vifaa](../../../04-tools) - - [Tazama Mtiririko wa Mazungumzo](../../../04-tools) - - [Fanya Jaribio na Maombi Tofauti](../../../04-tools) -- [Mafundisho Muhimu](../../../04-tools) - - [Mfumo wa ReAct (Kufikiria na Kutenda)](../../../04-tools) - - [Maelezo ya Vifaa Ni Muhimu](../../../04-tools) - - [Usimamizi wa Kikao](../../../04-tools) - - [Kushughulikia Makosa](../../../04-tools) -- [Vifaa Vilivyopo](../../../04-tools) -- [Wakati wa Kutumia Maajenti Wenye Vifaa](../../../04-tools) -- [Vifaa dhidi ya RAG](../../../04-tools) -- [Hatua Zifuatazo](../../../04-tools) +- [Video Hatua kwa Hatua](#video-hatua-kwa-hatua) +- [Utajifunza Nini](#utajifunza-nini) +- [Mahitaji ya Awali](#mahitaji-ya-awali) +- [Kuelewa Wakala wa AI Wenye Zana](#kuelewa-wakala-wa-ai-wenye-zana) +- [Jinsi Kuitwa kwa Zana Kufanya Kazi](#jinsi-kuitwa-kwa-zana-kufanya-kazi) + - [Maelezo ya Zana](#maelezo-ya-zana) + - [Uamuzi](#uamuzi) + - [Utekelezaji](#utekelezaji) + - [Uundaji wa Majibu](#uundaji-wa-majibu) + - [Mimari: Spring Boot Auto-Wiring](#mimari-spring-boot-auto-wiring) +- [Kufunga Zana Mfululizo](#kufunga-zana-mfululizo) +- [Endesha Programu](#endesha-programu) +- [Kutumia Programu](#kutumia-programu) + - [Jaribu Matumizi Rahisi ya Zana](#jaribu-matumizi-rahisi-ya-zana) + - [Jaribu Kufunga Zana Mfululizo](#jaribu-mlolongo-wa-zana) + - [Tazama Mtiririko wa Mazungumzo](#tazama-mtiririko-wa-mazungumzo) + - [Fanyia Maajaribio Maombi Tofauti](#jaribu-maombi-mbalimbali) +- [Dhana Muhimu](#dhana-muhimu) + - [Mfumo wa ReAct (Kufikiri na Kutenda)](#mraba-wa-react-fikra-na-matendo) + - [Maelezo ya Zana Ni Muhimu](#maelezo-ya-zana-ni-muhimu) + - [Usimamizi wa Kikao](#usimamizi-wa-kikao) + - [Kushughulikia Makosa](#kushughulikia-makosa) +- [Zana Zinazopatikana](#zana-zilizopo) +- [Wakati wa Kutumia Wakala Wenye Zana](#wakati-wa-kutumia-wakala-wa-zana) +- [Zana dhidi ya RAG](#zana-dhidi-ya-rag) +- [Hatua Zifuatazo](#hatua-zifuatayo) -## Ufafanuzi wa Video +## Video Hatua kwa Hatua -Tazama kikao hiki cha moja kwa moja kinachoelezea jinsi ya kuanza na sehemu hii: +Tazama kipindi hiki cha moja kwa moja kinachoelezea jinsi ya kuanza na moduli hii: -Maajenti wa AI Wenye Vifaa na MCP - Kikao cha Moja kwa Moja +Wakala wa AI Wenye Zana na MCP - Kikao cha Moja kwa Moja -## Utachojifunza +## Utajifunza Nini -Mpaka sasa, umekuwa ukijifunza jinsi ya kuzungumza na AI, kuunda maelekezo kwa ufanisi, na kuweka majibu yako kwenye nyaraka zako. Lakini bado kuna kikomo msingi: mifano ya lugha inaweza tu kutoa maandishi. Haiwezi kuangalia hali ya hewa, kufanya mahesabu, kuuliza hifadhidata, au kuingiliana na mifumo ya nje. +Hadi sasa, umejifunza jinsi ya kuwa na mazungumzo na AI, kuunda maelekezo kwa ufanisi, na kuimarisha majibu katika nyaraka zako. Lakini bado kuna kikomo muhimu: mifano ya lugha inaweza tu kuzalisha maandishi. Haiwezi kuangalia hali ya hewa, kufanya mahesabu, kuuliza katika hifadhidata, au kuingiliana na mifumo ya nje. -Vifaa hubadilisha hili. Kwa kumpa mfumo upatikanaji wa kazi anazoweza kuitwa, unamgeuza kutoka kuwa mtengenezaji tu wa maandishi kuwa maajenti anayeweza kuchukua hatua. Mfano huamua anapohitaji kifaa, kifaa gani atakachotumia, na vigezo gani atavitumia. Msimbo wako unatekeleza kazi na kurudisha matokeo. Mfano huingiza matokeo hayo kwenye jibu lake. +Zana hubadilisha hili. Kwa kumpa mfano ufikiaji wa kazi anazoweza kuita, unausogeza kutoka kwa kizalishaji cha maandishi hadi kuwa wakala anayeweza kuchukua hatua. Mfano unaamua ni lini unahitaji zana, ni zana gani itumike, na ni parameta gani zitapitishwa. Msimbo wako unatekeleza kazi na kurudisha matokeo. Mfano unaingiza matokeo hayo katika jibu lake. -## Masharti ya Awali +## Mahitaji ya Awali -- Umekamilisha [Sehemu ya 01 - Utangulizi](../01-introduction/README.md) (Rasilimali za Azure OpenAI zimetumika) -- Umekamilisha sehemu zilizopita zinapendekezwa (sehemu hii inarejelea [dhana za RAG kutoka Sehemu 03](../03-rag/README.md) katika kulinganisha Vifaa dhidi ya RAG) -- Kificho `.env` kiko kwenye saraka kuu chenye cheti cha Azure (kimeundwa na `azd up` katika Sehemu 01) +- Kumaliza [Moduli 01 - Utangulizi](../01-introduction/README.md) (Rasilimali za Azure OpenAI zimewekwa) +- Kupendekezwa kumaliza moduli zilizopita (moduli hii inataja [dhana za RAG kutoka Moduli 03](../03-rag/README.md) katika kulinganisha Zana dhidi ya RAG) +- Faili `.env` katika saraka kuu yenye cheti cha Azure (iliundwa na `azd up` katika Moduli 01) -> **Kumbuka:** Ikiwa bado hujakamilisha Sehemu 01, fuata maelekezo ya usambazaji hapo kwanza. +> **Kumbuka:** Ikiwa hujakamilisha Moduli 01, fuata maelekezo ya usakinishaji hapo kwanza. -## Kuelewa Maajenti wa AI Wenye Vifaa +## Kuelewa Wakala wa AI Wenye Zana -> **📝 Kumbuka:** Neno "maajenti" katika sehemu hii linamaanisha wasaidizi wa AI walioboresha na uwezo wa kuitwa kwa vifaa. Hii ni tofauti na mifumo ya **Agentic AI** (maajenti huru wenye mipango, kumbukumbu, na fikra zinazoendelea hatua kwa hatua) ambayo tutafundisha katika [Sehemu ya 05: MCP](../05-mcp/README.md). +> **📝 Kumbuka:** Neno "wakala" katika moduli hii linarejelea wasaidizi wa AI walioboreshwa na uwezo wa kuitwa kwa zana. Hii ni tofauti na mifumo ya **Agentic AI** (wakala huru wenye mipango, kumbukumbu, na fikra za hatua nyingi) ambayo tutazungumzia katika [Moduli 05: MCP](../05-mcp/README.md). -Bila vifaa, mfano wa lugha unaweza tu kutoa maandishi kutoka kwa data zake za mafunzo. Muulize hali ya hewa ya sasa, na lazima adhani. Mpe vifaa, na anaweza kuitisha API ya hali ya hewa, kufanya mahesabu, au kuuliza hifadhidata — kisha acha matokeo halisi yaende kwenye jibu lake. +Bila zana, mfano wa lugha unaweza tu kuzalisha maandishi kutoka kwenye data yake ya mafunzo. Mwuulize hali ya hewa sasa, basi lazima anane. Mpe zana, ataita API ya hali ya hewa, kufanya mahesabu, au kuuliza hifadhidata — kisha acha atoe matokeo halisi katika jibu lake. -Bila Vifaa dhidi ya Kwa Vifaa +Bila Zana dhidi ya Kwa Zana -*Bila vifaa mfano unaweza tu kudhani — kwa vifaa anaweza kuitisha API, kuendesha mahesabu, na kurudisha data za wakati halisi.* +*Bila zana mfano unahitaji kumanane — kwa zana anaweza kuita API, kufanya mahesabu, na kurudisha data ya wakati halisi.* -Mojawapo maajenti wa AI wenye vifaa hufuata mfumo wa **Kufikiri na Kutenda (ReAct)**. Mfano haujibu tu — huwaafanya mawazo kuhusu anachohitaji, hutenda kwa kuitisha kifaa, hushuhudia matokeo, kisha huamua kama ataendelea kutenda au kutoa jibu la mwisho: +Wakala wa AI mwenye zana hunafuata mfumo wa **Kufikiri na Kutenda (ReAct)**. Mfano haujibu tu — hufikiria anachohitaji, hufanya hatua kwa kuitia zana, hutazama matokeo, kisha huamua kama aendelee au kutoa jibu la mwisho: -1. **Fikiri** — Maajenti huchambua swali la mtumiaji na kubaini taarifa anazohitaji -2. **Tenda** — Maajenti huamua kifaa sahihi, huunda vigezo sahihi, na huuita -3. **Shuhudia** — Maajenti hupokea matokeo ya kifaa na kuangalia -4. **Rudia au Jibu** — Ikiwa inahitaji data zaidi, hurudia; vinginevyo, huunda jibu la lugha asili +1. **Fikiria** — Wakala anachambua swali la mtumiaji na kubaini taarifa anazohitaji +2. **Tenda** — Wakala huchagua zana sahihi, huunda parameta sahihi, na kuitia zana +3. **Tazama** — Wakala anapokea matokeo ya zana na kufanya tathmini +4. **Rudia au Jibu** — Ikiwa data zaidi inahitajika, wakala hurudia; vinginevyo, huunda jibu la lugha ya asili Mfumo wa ReAct -*Mzunguko wa ReAct — maajenti hufikiri kuhusu kitendo, hutenda kwa kuitisha kifaa, hushuhudia matokeo, na kuendelea hadi aweze kutoa jibu la mwisho.* +*Mzunguko wa ReAct — wakala hufikiria anachotenda, hufanya kitendo kwa kuitia zana, hutazama matokeo, na hurudia hadi aweze kutoa jibu la mwisho.* -Hii hufanyika moja kwa moja. Unaeleza vifaa na maelezo yao. Mfano unashughulikia uamuzi wa lini na jinsi ya kutumia. +Hii hufanyika moja kwa moja. Wewe unaweka zana na maelezo yake. Mfano hushughulikia uamuzi wa lini na jinsi ya kuzitumia. -## Jinsi Kuitwa kwa Kifaa Kunavyofanya Kazi +## Jinsi Kuitwa kwa Zana Kufanya Kazi -### Maelezo ya Vifaa +### Maelezo ya Zana [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Unaeza kazi zilizo na maelezo wazi na sifa za vigezo. Mfano unaona maelezo haya kwenye maelekezo ya mfumo wake na unaelewa kile kifaa kila kinachofanya. +Unaeleza kazi kwa maelezo wazi na maelezo ya parameta. Mfano unaona maelezo haya katika maelekezo ya mfumo wake na unaelewa kila zana inafanya nini. ```java @Component @@ -96,136 +96,135 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Msaidizi huunganishwa moja kwa moja na Spring Boot na: -// - Bean ya ChatModel -// - Njia zote za @Tool kutoka kwa darasa la @Component +// Msaidizi anaunganishwa kwa moja kwa moja na Spring Boot na: +// - Kijani cha ChatModel +// - Mbinu zote za @Tool kutoka kwa madarasa ya @Component // - ChatMemoryProvider kwa usimamizi wa kikao ``` - -Michoro hapa chini hufafanua kila alama na kuonyesha jinsi kila sehemu inavyosaidia AI kuelewa lini kuitisha kifaa na vigezo gani kuwasilisha: -Muundo wa Maelezo ya Vifaa +Mchoro hapa chini unaelezea kila alama na kuonyesha jinsi kila sehemu inavyoisaidia AI kuelewa lini kuita zana na ni hoja gani kupitishwa: -*Muundo wa maelezo ya kifaa — @Tool humweleza AI lini aichukue, @P huambia kila kipengele, na @AiService huunganisha kila kitu wakati wa kuanzisha.* +Anuwai ya Maelezo ya Zana -> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) na uliza: -> - "Nitashirikisha API halisi ya hali ya hewa kama OpenWeatherMap badala ya data za kuigwa jinsi gani?" -> - "Nini kinafanya maelezo ya kifaa kuwa mazuri kwa kusaidia AI kuitumia kwa usahihi?" -> - "Nashughulikiaje makosa ya API na viwango vya maombi katika utekelezaji wa vifaa?" +*Anuwai ya maelezo ya zana — @Tool hueleza AI lini itumike, @P inaelezea kila parameta, na @AiService huunganisha kila kitu wakati wa kuanzisha.* + +> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) na uliza: +> - "Nitahakikisha vipi kuunganisha API halisi ya hali ya hewa kama OpenWeatherMap badala ya data feki?" +> - "Nini kinachofanya maelezo ya zana kuwa mazuri na kusaidia AI kuitumia kwa usahihi?" +> - "Nitashughulikia vipi makosa ya API na mipaka ya kutumia katika utekelezaji wa zana?" ### Uamuzi -Mtumiaji akuulize "Hali ya hewa Seattle iko aje?", mfano hauchagui kifaa kwa bahati. Huongeza nia ya mtumiaji na maelezo yote ya kifaa anazopata, hupima kila moja kwa umuhimu, na kuchagua bora zaidi. Kisha huunda mwito uliopangwa kiufundi na vigezo sahihi — katika kesi hii, kuweka `location` kuwa `"Seattle"`. +Mwanadamu au mtumiaji auliza "Hali ya hewa iko vipi Seattle?", mfano hachagui zana nasibu. Hulinganisha nia ya mtumiaji dhidi ya maelezo ya zana zote anaweza kufikia, hupima kila moja kwa umuhimu, na hupata zana bora. Kisha hutengeneza simu ya kazi yenye muundo na parameta sahihi — katika kesi hii, kuweka `location` kuwa `"Seattle"`. -Ikiwa hakuna kifaa kinacholingana na ombi la mtumiaji, mfano hurudi kujibu kwa maarifa yake mwenyewe. Ikiwa vifaa vingi vinalingana, huchagua kile kilicho maalum zaidi. +Kama hakuna zana inayokidhi ombi la mtumiaji, mfano hurudi kujibu kwa maarifa yake mwenyewe. Ikiwa zana nyingi zinakidhi, huchagua ile iliyo maalum zaidi. -Jinsi AI Huchagua Kifaa cha Kutumia +Jinsi AI Huchagua Zana ya Kutumia -*Mfano hupima kila kifaa kinachopatikana dhidi ya nia ya mtumiaji na huchagua lililo bora — ndio maana kuandika maelezo ya kifaa kwa uwazi na ufafanuzi ni muhimu.* +*Mfano hupima kila zana inayopatikana dhidi ya nia ya mtumiaji na huchagua mechi bora — ndiyo maana kuandika maelezo ya zana wazi na maalum ni muhimu.* ### Utekelezaji [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot huunganisha moja kwa moja kiolesura cha `@AiService` chenye vifaa vyote vilivyorekodiwa, na LangChain4j hutoa mwito wa kifaa moja kwa moja. Ndani yake, mwitikio kamili huenda kupitia hatua sita — kutoka kwa swali la lugha asili la mtumiaji hadi jibu la lugha asili: +Spring Boot huunganisha moja kwa moja interface ya `@AiService` yenye zana zote zilizosajiliwa, na LangChain4j hutoa simu za zana moja kwa moja. Nyuma ya pazia, mzunguko kamili wa kuitwa kwa zana hutoka kwenye swali la lugha ya asili la mtumiaji hadi jibu la lugha ya asili: -Mtiririko wa Kuitwa kwa Kifaa +Mtiririko wa Kuitwa kwa Zana -*Mtiririko kutoka mwanzo hadi mwisho — mtumiaji houliza swali, mfano huchagua kifaa, LangChain4j kinaendesha, na mfano huingiza matokeo katika jibu la asili.* +*Mtiririko kamili — mtumiaji auliza swali, mfano huchagua zana, LangChain4j hufanya kazi yake, na mfano huingiza matokeo katika jibu.* -Ukiendesha [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) katika Sehemu 00, tayari umeona mfumo huu ukitenda — vifaa vya `Calculator` vilitumwa kwa njia ile ile. Mchoro wa mfuatano hapa chini unaonyesha hasa kilichotokea chini ya pazia wakati wa onyesho hilo: +Nyuma ya pazia, `AiServices` hufanya mzunguko huo sawa kwa zana yoyote — hapa umeonyeshwa na `Calculator` rahisi. Mchoro wa mfululizo hapa chini unaonyesha kinachotokea chanya: -Mchoro wa Mfuatano wa Kuitwa kwa Kifaa +Mchoro wa Mfululizo wa Kuitwa kwa Zana -*Kizunguko cha kuitwa kwa kifaa kutoka Demo ya Quick Start — `AiServices` hutuma ujumbe wako na muundo wa vifaa kwa LLM, LLM hurudisha mwito wa kazi kama `add(42, 58)`, LangChain4j hufanya kazi ya `Calculator` ndani, na hulaidia matokeo kwa jibu la mwisho.* +*Mzunguko wa kuitwa kwa zana — `AiServices` hutuma ujumbe wako na muundo wa zana kwa LLM, LLM hurudisha simu ya kazi kama `add(42, 58)`, LangChain4j hufanya kazi ya `Calculator` eneo la ndani, na hurudisha matokeo kwa jibu la mwisho.* -> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) na uliza: -> - "Mfumo wa ReAct hufanya kazi vipi na kwa nini ni mzuri kwa maajenti wa AI?" -> - "Maajenti huamua vipi kifaa cha kutumia na kwa utaratibu gani?" -> - "Nini hutokea ikiwa utekelezaji wa kifaa unashindwa - jinsi gani nashughulikia makosa kwa usahihi?" +> **🤖 Jaribu na [GitHub Copilot](https://github.com/features/copilot) Chat:** Fungua [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) na uliza: +> - "Mfumo wa ReAct hufanya kazi vipi na kwa nini ni mzuri kwa wakala wa AI?" +> - "Wakala huamua vipi ni zana gani itumike na kwa mpangilio gani?" +> - "Kwa nini inatokea mkutano wa zana kushindwa - nitashughulikiaje makosa kwa usahihi?" ### Uundaji wa Majibu -Mfano hupokea data ya hali ya hewa na kuipitisha kuwa jibu la lugha asili kwa mtumiaji. +Mfano unapata data ya hali ya hewa na kuiunda kuwa jibu la lugha asilia kwa mtumiaji. -### Mimino: Kubana Moja kwa Moja Spring Boot +### Mimari: Spring Boot Auto-Wiring -Sehemu hii inatumia mchanganyiko wa LangChain4j na Spring Boot kwa kiolesura cha `@AiService` kinachoeleza kazi. Wakati wa kuanzisha, Spring Boot hugundua kila `@Component` yenye njia za `@Tool`, kipande chako cha `ChatModel`, na `ChatMemoryProvider` — kisha huchanganya yote kwa kiolesura kimoja kinachoitwa `Assistant` bila kazi ya ziada nyingi. +Moduli hii inatumia muunganiko wa Spring Boot wa LangChain4j na interface za `@AiService` za aina ya tamko. Wakati wa kuanzisha Spring Boot hugundua kila `@Component` iliyo na njia za `@Tool`, bean yako ya `ChatModel`, na `ChatMemoryProvider` — kisha huziunganisha zote kwenye interface moja ya `Assistant` bila mashaka ya mkono. -Mimino ya Kubana Moja kwa Moja Spring Boot +Mimari ya Spring Boot Auto-Wiring -*Kiolesura cha @AiService kinaringanisha ChatModel, vipengele vya kifaa, na mtoaji kumbukumbu — Spring Boot hushughulikia unganisho zote moja kwa moja.* +*Interface ya @AiService inahusisha pamoja ChatModel, vipengele vya zana, na mtoaji kumbukumbu — Spring Boot hushughulikia unganisho kiotomatiki.* -Huu ni mtiririko kamili wa maisha ya ombi kama mchoro wa mfuatano — kutoka ombi la HTTP kupitia kontorola, huduma, na wakala aliyeunganishwa moja kwa moja, hadi utekelezaji wa kifaa na kurudi: +Hapa ni mzunguko wa ombi kamili kama mchoro wa mfululizo — kuanzia ombi la HTTP kupitia controller, huduma, na proksi iliyounganishwa moja kwa moja, hadi utekelezaji wa zana na kurudi tena: -Mfuatano wa Kuitwa kwa Kifaa Spring Boot +Mchoro wa Mfululizo wa Kuitwa kwa Zana wa Spring Boot -*Mtiririko kamili wa maisha ya ombi la Spring Boot — ombi la HTTP hupanuka kupitia kontorola na huduma hadi wakala wa Assistant aliyeunganisha moja kwa moja, anayoratibu LLM na mwito wa kifaa moja kwa moja.* +*Mzunguko kamili wa ombi la Spring Boot — ombi la HTTP hupita controller na huduma hadi kwa proksi ya Msaidizi iliyo na waya, ambayo huandaa LLM na simu za zana moja kwa moja.* -Manufaa makuu ya njia hii: +Faida kuu za njia hii: -- **Ubunganishaji moja kwa moja wa Spring Boot** — ChatModel na vifaa huingizwa moja kwa moja -- **Mfumo wa @MemoryId** — Usimamizi wa kumbukumbu kwa kikao moja kwa moja -- **Toleo moja tu** — Assistant huunda mara moja na kutumika tena kwa utendaji bora -- **Utekelezaji salama wa aina** — Njia za Java huitwa moja kwa moja na uongofu wa aina -- **Uendeshaji wa mizunguko mingi** — Hukabiliana na ufuatiliaji wa vifaa moja kwa moja -- **Hakuna kazi za ziada** — Hakuna mwito wa mkono wa `AiServices.builder()` au ramani ya kumbukumbu +- **Auto-wiring ya Spring Boot** — ChatModel na zana zimeingizwa moja kwa moja +- **Mfumo wa @MemoryId** — Usimamizi wa kumbukumbu kwa kikao moja kwa moja +- **Kipindi kimoja** — Msaidizi huundwa mara moja na kutumika tena kwa utendaji bora +- **Utekelezaji salama kwa aina** — Njia za Java huitwa moja kwa moja na uongofu wa aina +- **Uratibu wa mipangilio mingi** — Hushughulikia kufunga zana moja kwa moja +- **Hakuna kodhi ya ziada** — Hakuna simu za mkono za `AiServices.builder()` au ramani za kumbukumbu -Njia mbadala (ya mkono `AiServices.builder()`) zinahitaji msimbo zaidi na hupoteza manufaa ya ushirikiano wa Spring Boot. +Njia mbadala (ya mkono na `AiServices.builder()`) huhitaji msimbo zaidi na hukosa faida za muunganisho wa Spring Boot. -## Ufuatiliaji wa Vifaa +## Kufunga Zana Mfululizo -**Ufuatiliaji wa Vifaa** — Nguvu halisi ya maajenti wenye vifaa hujionyesha wakati swali moja linahitaji vifaa vingi. Uliza "Hali ya hewa Seattle ni kiasi gani kwa Fahrenheit?" na maajenti huhusisha moja kwa moja vifaa viwili: kwanza huita `getCurrentWeather` kupata joto kwa Celsius, kisha hupitisha thamani hiyo kwa `celsiusToFahrenheit` kwa mabadiliko — yote yakiwa kwenye zamu moja ya mazungumzo. +**Kufunga Zana** — Nguvu halisi ya wakala mwenye zana huonekana wakati swali moja linahitaji zana nyingi. Uliza "Hali ya hewa iko Seattle kwa Fahrenheit?" na wakala huunganisha zana mbili kiotomatiki: kwanza huita `getCurrentWeather` kupata joto katika Celsius, kisha hupitisha thamani hiyo kwa `celsiusToFahrenheit` kwa uongofu — yote katika mzunguko mmoja wa mazungumzo. -Mfano wa Ufuatiliaji wa Vifaa +Mfano wa Kufunga Zana -*Ufuatiliaji wa vifaa ukiwa kazini — maajenti huita kwanza getCurrentWeather, kisha hupitisha matokeo ya Celsius kwa celsiusToFahrenheit, na kutoa jibu limeunganishwa.* +*Kufunga zana inavyofanya kazi — wakala huita getCurrentWeather kwanza, kisha hupitisha matokeo ya Celsius kwa celsiusToFahrenheit, na hutuma jibu lililojumuishwa.* -**Makala za Makosa kwa Hekima** — Uliza hali ya hewa katika mji usiopo kwenye data ya majaribio. Kifaa hurudisha ujumbe wa kosa, na AI huonyesha hawezi kusaidia badala ya kuanguka. Vifaa hutenda kwa usalama. Chati iliyo hapo chini inaonyesha tofauti za mbinu mbili — kushughulikia makosa vizuri, maajenti hukamata kosa na kujibu kwa msaada, wakati bila hiyo programu nzima huanguka: +**Kushindwa kwa Neema** — Uliza hali ya hewa katika jiji ambalo halipo kwenye data ya mfano. Zana hurudisha ujumbe wa kosa, na AI huelezea hawezi kusaidia badala ya kuzima programu. Zana hushindwa kwa usalama. Mchoro hapa chini unaonesha tofauti ya njia mbili — kwa usimamizi sahihi wa makosa, wakala huchukua makosa na kujibu kwa msaada, huku bila hivyo programu nzima inazama: Mtiririko wa Kushughulikia Makosa -*Wakati kifaa kinashindwa, maajenti hukamata kosa na kujibu kwa maelezo ya msaada badala ya kuanguka.* +*Wakati zana inashindwa, wakala huchukua kosa na kujibu kwa maelezo yenye msaada badala ya kuzima programu.* -Hii hufanyika kwa zamu moja ya mazungumzo. Maajenti huratibu mwito wa vifaa vingi kwa uhuru. +Hii hufanyika katika mzunguko mmoja wa mazungumzo. Wakala huandaa simu nyingi za zana kwa uhuru. ## Endesha Programu -**Thibitisha usambazaji:** +**Thibitisha usanifu:** -Thibitisha faili `.env` ipo kwenye saraka kuu ikiwa na cheti cha Azure (kimeundwa wakati wa Sehemu 01). Endesha amri hii kutoka kwa saraka ya sehemu (`04-tools/`): +Hakikisha faili `.env` ipo katika saraka kuu na cheti cha Azure (iliundwa wakati wa Moduli 01). Endesha hii kutoka saraka ya moduli (`04-tools/`): -**Bash:** +**Bash:** ```bash cat ../.env # Inapaswa kuonyesha AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Inapaswa kuonyesha AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**Anza programu:** -> **Kumbuka:** Ikiwa tayari umeanza programu zote kwa kutumia `./start-all.sh` kutoka kwenye saraka kuu (kama ilivyoelezwa katika Sehemu 01), sehemu hii tayari inaendesha kwenye bandari 8084. Unaweza kupita amri za kuanzisha hapa na kwenda moja kwa moja http://localhost:8084. +**Anzisha programu:** -**Chaguo 1: Kutumia Dashibodi ya Spring Boot (Inapendekezwa kwa watumiaji wa VS Code)** +> **Kumbuka:** Kama tayari umeanzisha programu zote kwa kutumia `./start-all.sh` kutoka saraka kuu (kama ilivyoelezwa katika Moduli 01), moduli hii inafanya kazi tayari kwenye bandari 8084. Unaweza kupita amri za kuanzisha hapa chini na kwenda moja kwa moja http://localhost:8084. -Kontena la maendeleo lina programu-jalizi ya Dashibodi ya Spring Boot, inayotoa kiolesura cha kuona ili kusimamia programu zote za Spring Boot. Unaweza kuipata kwenye Bar ya Shughuli upande wa kushoto wa VS Code (tazama ikoni ya Spring Boot). +**Chaguo 1: Kutumia Spring Boot Dashboard (Inapendekezwa kwa watumiaji wa VS Code)** -Kutoka kwenye Dashibodi ya Spring Boot, unaweza: -- Kuona programu zote za Spring Boot zinazopatikana kwenye nafasi ya kazi -- Anzisha/acha programu kwa kubofya mara moja -- Angalia kumbukumbu za programu papo hapo -- Fuata hali ya programu +Begani ya maendeleo ina kipengele cha Spring Boot Dashboard, kinachotoa kiolesura cha kuona na kudhibiti programu zote za Spring Boot. Unaweza kuiona katika Bar ya Shughuli upande wa kushoto wa VS Code (tafuta ikoni ya Spring Boot). -Bonyeza tu kitufe cha kucheza kando ya "zana" kuanza moduli hii, au anzisha moduli zote kwa pamoja. +Kutoka Spring Boot Dashboard, unaweza: +- Kuona programu zote za Spring Boot zinazopatikana kwenye eneo la kazi +- Kuanzisha/kuzima programu kwa kitufe kimoja +- Kutazama kumbukumbu za programu kwa muda halisi +- Kufuatilia hali ya programu -Hivi ndivyo Dashibodi ya Spring Boot inavyoonekana katika VS Code: +Bonyeza kitufe cha kucheza kando ya "tools" kuanza moduli hii, au anzisha moduli zote kwa pamoja. -Spring Boot Dashboard +Hivi ndivyo Spring Boot Dashboard inavyoonekana katika VS Code: +Dashibodi ya Spring Boot -*Dashibodi ya Spring Boot katika VS Code — anzisha, zima, na fuatilia moduli zote kutoka sehemu moja* +*Dashibodi ya Spring Boot katika VS Code — anzisha, simamisha, na fuatilia moduli zote kutoka mahali pamoja* **Chaguo 2: Kutumia skripti za shell** @@ -233,17 +232,17 @@ Anzisha programu zote za wavuti (moduli 01-04): **Bash:** ```bash -cd .. # Kutoka kwenye saraka ya mizizi +cd .. # Kutoka katika saraka ya mzizi ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Kutoka katika saraka ya mizizi +cd .. # Kutoka kwenye saraka ya mzizi .\start-all.ps1 ``` -Au anzisha moduli hii tu: +Au anzisha moduli hii peke yake: **Bash:** ```bash @@ -257,7 +256,7 @@ cd 04-tools .\start.ps1 ``` -Skripti zote hujipakia moja kwa moja mabadiliko ya mazingira kutoka kwenye faili `.env` ya mzizi na zitajenga JARs ikiwa hazipo. +Skripti zote mbili zinaleta moja kwa moja mabadiliko ya mazingira kutoka kwenye faili la mizizi `.env` na zitajenga JARs ikiwa hazipo. > **Kumbuka:** Ikiwa unapendelea kujenga moduli zote kwa mkono kabla ya kuanza: > @@ -275,114 +274,114 @@ Skripti zote hujipakia moja kwa moja mabadiliko ya mazingira kutoka kwenye faili Fungua http://localhost:8084 kwenye kivinjari chako. -**Kuzima:** +**Kusimamisha:** **Bash:** ```bash -./stop.sh # Hii moduli tu +./stop.sh # Sehemu hii tu # Au -cd .. && ./stop-all.sh # Moduli zote +cd .. && ./stop-all.sh # Sehemu zote ``` **PowerShell:** ```powershell -.\stop.ps1 # Moduli hii pekee +.\stop.ps1 # Moduli hii tu # Au cd ..; .\stop-all.ps1 # Moduli zote ``` ## Kutumia Programu -Programu hutoa kiolesura cha wavuti ambapo unaweza kuwasiliana na wakala wa AI ambaye ana upatikanaji wa zana za hali ya hewa na uongofu wa joto. Hivi ndivyo kiolesura kinavyoonekana — kinajumuisha mifano ya kuanza haraka na jopo la mazungumzo la kutuma maombi: +Programu hutoa kiolesura cha wavuti ambapo unaweza kuingiliana na wakala wa AI ambaye ana ufikiaji wa zana za hali ya hewa na uongofu wa joto. Hivi ndivyo kiolesura kinavyoonekana — kinajumuisha mifano ya kuanza kwa haraka na jopo la mazungumzo kwa kutuma maombi: -AI Agent Tools Interface +Kiolesura cha Zana za Wakala wa AI -*Kiolesura cha Zana za Wakala wa AI - mifano ya haraka na kiolesura cha mazungumzo kwa kuwasiliana na zana* +*Kiolesura cha Zana za Wakala wa AI - mifano ya haraka na kiolesura cha mazungumzo kwa kuingiliana na zana* ### Jaribu Matumizi Rahisi ya Zana -Anza na ombi rahisi: "Badilisha nyuzi 100 Fahrenheit kuwa Celsius". Wakala anatambua anahitaji zana ya uongofu wa joto, ainakili kwa vigezo sahihi, na kurudisha matokeo. Angalia jinsi hii inavyohisi kwa asili - hukueleza ni zana gani ya kutumia au jinsi ya kuitumia. +Anza na ombi rahisi: "Badilisha digrii 100 Fahrenheit kuwa Celsius". Wakala anakiri anahitaji zana ya uongofu wa joto, anaiita kwa vigezo sahihi, na kurudisha matokeo. Angalia jinsi hii inavyoonekana ya asili - hukutaja zana gani kutumia au jinsi ya kuiita. -### Jaribu Mfuatano wa Zana +### Jaribu Mlolongo wa Zana -Sasa jaribu kitu kigumu zaidi: "Hali ya hewa iko vipi Seattle na ibadilisha hadi Fahrenheit?" Tazama jinsi wakala anavyofanya kazi hatua kwa hatua. Kwanza anapata hali ya hewa (inayorejesha Celsius), anatambua anahitaji kubadilisha hadi Fahrenheit, aita zana ya uongofu, na kuunganisha matokeo yote kuwa jibu moja. +Sasa jaribu jambo ngumu zaidi: "Hali ya hewa Seattle iko vipi na ibadilishe kuwa Fahrenheit?" Tazama wakala akifanya hatua kwa hatua. Anakamilisha kupata hali ya hewa (ambayo inarudisha Celsius), anakiri anahitaji kubadilisha kuwa Fahrenheit, anaita zana ya uongofu, na kuunganisha matokeo yote kuwa jibu moja. -### Angalia Mtiririko wa Mazungumzo +### Tazama Mtiririko wa Mazungumzo -Kiolesura cha mazungumzo kinahifadhi historia ya mazungumzo, kukuwezesha kuwa na mazungumzo ya mizunguko mingi. Unaweza kuona maswali na majibu yote ya zamani, kufanya kufuatilia mazungumzo na kuelewa jinsi wakala anavyojenga muktadha kupitia mabadilikano mbalimbali iwe rahisi. +Kiolesura cha mazungumzo huweka historia ya mazungumzo, kukuwezesha kuwa na mwingiliano wa mizunguko mingi. Unaweza kuona maswali na majibu yote ya awali, hivyo kurahisisha kufuatilia mazungumzo na kuelewa jinsi wakala anavyojenga muktadha kupitia mabadilishano mengi. -Conversation with Multiple Tool Calls +Mazungumzo Yenye Miito Mingi ya Zana -*Mazungumzo ya mizunguko mingi yanayoonyesha uongofu rahisi, utafutaji wa hali ya hewa, na mfuatano wa zana* +*Mazungumzo ya mizunguko mingi yanaonyesha uongofu rahisi, kutafuta hali ya hewa, na mlolongo wa zana* -### Jaribu Maombi Tofauti +### Jaribu Maombi Mbalimbali Jaribu mchanganyiko mbalimbali: -- Utafutaji wa hali ya hewa: "Hali ya hewa iko vipi Tokyo?" -- Uongofu wa joto: "Ni kiasi gani 25°C kwa Kelvin?" -- Maswali mchanganyiko: "Angalia hali ya hewa Paris na niambie kama iko juu ya 20°C" +- Kutafuta hali ya hewa: "Je, hali ya hewa Tokyo iko vipi?" +- Uongofu wa joto: "25°C ni kiasi gani katika Kelvin?" +- Maswali mchanganyiko: "Angalia hali ya hewa Paris na niambie ikiwa iko juu ya 20°C" -Angalia jinsi wakala anavyotafsiri lugha ya asili na kuibeba kwa miito sahihi ya zana. +Angalia jinsi wakala anavyotafsiri lugha ya asili na kuihusisha na miito inayofaa ya zana. -## Misingi Muhimu +## Dhana Muhimu -### Mfano wa ReAct (Kufikiri na Kutenda) +### Mraba wa ReAct (Fikra na Matendo) -Wakala hubadilishana kati ya kufikiri (kuamua cha kufanya) na kutenda (kutumia zana). Mfano huu unaruhusu kutatua matatizo kwa kujitegemea badala ya kujibu tu maagizo. +Wakala hubadilishana kati ya kufikiria (kuamua cha kufanya) na kutenda (kutumia zana). Mraba huu unaruhusu kutatua matatizo kwa uhuru badala ya kujibu tu maagizo. -### Maelezo ya Zana Yanahitajika +### Maelezo ya Zana ni Muhimu -Ubora wa maelezo ya zana zako unasababisha wakala kuzitumia vema. Maelezo wazi, maalum husaidia mfano kuelewa wakati na jinsi ya kuita kila zana. +Ubora wa maelezo ya zana zako huathiri moja kwa moja jinsi wakala anavyotumia hizo zana. Maelezo wazi na maalum husaidia mfano kuelewa lini na jinsi ya kuitisha kila zana. ### Usimamizi wa Kikao -Maelezo ya `@MemoryId` huruhusu usimamizi wa kumbukumbu zinazoendeshwa na kikao kiotomatiki. Kila ID ya kikao hupata mfano wake wa `ChatMemory` unaosimamiwa na bean ya `ChatMemoryProvider`, hivyo watumiaji wengi wanaweza kuwasiliana na wakala bila mazungumzo yao kuchanganyika. Mchoro ufuatao unaonyesha jinsi watumiaji wengi wanavyopangwa kwenye hifadhidata za kumbukumbu pekee kwa kutumia ID zao za kikao: +Kiambatisho `@MemoryId` huruhusu usimamizi wa kumbukumbu wa kikao kiotomatiki. Kila kitambulisho cha kikao hupata mfano wake wa `ChatMemory` unaosimamiwa na bean ya `ChatMemoryProvider`, hivyo watumiaji wengi wanaweza kuingiliana na wakala kwa wakati mmoja bila mazungumzo yao kuchanganyika. Mchoro ufuatao unaonyesha jinsi watumiaji wengi wanavyopangwa katika hifadhi za kumbukumbu tofauti kulingana na kitambulisho chao cha kikao: -Session Management with @MemoryId +Usimamizi wa Kikao na @MemoryId -*Kila ID ya kikao ina historia yake ya mazungumzo iliyotengwa — watumiaji hawwezi kuona ujumbe wa wengine.* +*Kila kitambulisho cha kikao kina historia yake ya mazungumzo — watumiaji hawawahi kuona ujumbe wa wengine.* -### Usimamizi wa Makosa +### Kushughulikia Makosa -Zana zinaweza kufeli — API zinaweza kushindwa, vigezo vinaweza kuwa batili, huduma za nje zinaweza kushindwa. Wakala wa uzalishaji wanahitaji usimamizi wa makosa ili mfano uweze kueleza matatizo au kujaribu mbadala badala ya kusababisha programu yote kushindwa. Wakati zana inapotupa hitilafu, LangChain4j huikamata na kurudisha ujumbe wa kosa kwa mfano, ambao unaweza kisha kueleza tatizo kwa lugha asili. +Zana zinaweza kushindwa — API zinaweza kupitwa muda, vigezo vinaweza kuwa batili, huduma za nje zinaweza kuzimika. Wakala wa uzalishaji wanahitaji kushughulikia makosa ili mfano uweze kueleza matatizo au kujaribu mbadala badala ya kuharibu programu nzima. Wakati zana inapotupa hitilafu, LangChain4j huishika na kuwasilisha ujumbe wa makosa kwa mfano, ambao basi unaweza kueleza tatizo kwa lugha ya kawaida. -## Zana Zinazopatikana +## Zana Zilizopo -Mchoro uliopo unaonyesha mfumo mpana wa zana unazoweza kujenga. Moduli hii inaonesha zana za hali ya hewa na joto, lakini mfano ule ule wa `@Tool` hufanya kazi kwa njia yoyote ya Java — kutoka kwa maswali ya database hadi usindikaji wa malipo. +Mchoro ufuatao unaonyesha mfumo mpana wa zana unazoweza kujenga. Moduli hii inaonyesha zana za hali ya hewa na joto, lakini muundo ule ule wa `@Tool` hufanya kazi kwa njia yoyote ya Java — kuanzia maswali ya hifadhidata hadi usindikaji wa malipo. -Tool Ecosystem +Mfumo wa Zana -*Kila njia ya Java iliyoandikwa na @Tool inapatikana kwa AI — mfano huu unaenea kwa database, API, barua pepe, operesheni za faili, na zaidi.* +*Ndiyo njia yoyote ya Java iliyo nayo alama ya @Tool inapatikana kwa AI — muundo huu unajumuisha hifadhidata, API, barua pepe, uendeshaji faili, na zaidi.* -## Wakati wa Kutumia Wakala Wa Zana +## Wakati wa Kutumia Wakala wa Zana -Sio kila ombi linahitaji zana. Uamuzi unategemea kama AI inahitaji kuingiliana na mifumo ya nje au inaweza kujibu kwa maarifa yake mwenyewe. Mwongozo ufuatao unatoa muhtasari wa wakati zana zinaongeza thamani na wakati hazihitajiki: +Siyo kila ombi linahitaji zana. Uamuzi ni kama AI inahitaji kuingiliana na mifumo ya nje au inaweza kujibu kwa maarifa yake mwenyewe. Mwongozo ufuatao unafupisha lini zana zinaongeza thamani na lini hazihitajiki: -When to Use Tools +Wakati wa Kutumia Zana -*Mwongozo wa haraka wa uamuzi — zana ni kwa data za wakati halisi, hesabu, na vitendo; maarifa ya jumla na kazi za ubunifu hazihitaji zana.* +*Mwongozo mfupi wa maamuzi — zana ni kwa data za wakati halisi, mahesabu, na vitendo; maarifa ya jumla na kazi za ubunifu hazihitaji zana.* ## Zana dhidi ya RAG -Moduli 03 na 04 zote hupanua kile AI inaweza kufanya, lakini kwa njia tofauti kabisa. RAG humpa mfano upatikanaji wa **maarifa** kwa kupata hati. Zana humpa mfano uwezo wa kuchukua **vitendo** kwa kuita kazi. Mchoro hapa chini unalinganisha mbinu hizi mbili kando kando — kutoka jinsi kila mchakato unavyofanya kazi hadi mikataba kati yao: +Moduli 03 na 04 zote zinaongeza uwezo wa AI, lakini kwa njia tofauti kabisa. RAG hutoa mfano ufikiaji wa **maarifa** kwa kupata nyaraka. Zana humruhusu mfano kuchukua **vitendo** kwa kuita kazi. Mchoro ufuatao unaonyesha kulinganisha mbinu hizi mbili kando kwa kando — kutoka jinsi kila mtiririko unavyofanya kazi hadi kushindana kati ya mbadala hizo: -Tools vs RAG Comparison +Mlinganiko wa Zana dhidi ya RAG -*RAG hupata taarifa kutoka kwa hati tulivu — Zana hutekeleza vitendo na kupata data hai, ya wakati halisi. Mifumo mingi ya uzalishaji hutumia wote wawili.* +*RAG hupata taarifa kutoka kwa nyaraka zisizobadilika — Zana hufanya vitendo na kupata data hai ya wakati halisi. Mifumo mingi ya uzalishaji huunganisha zote mbili.* -Kwa vitendo, mifumo mingi ya uzalishaji hutumia mbinu zote mbili: RAG kwa kuhamasisha majibu yako katika nyaraka, na Zana kwa kupata data hai au kutekeleza shughuli. +Katika mazoezi, mifumo mingi ya uzalishaji huunganisha mbinu zote mbili: RAG kwa kuimarisha majibu katika nyaraka zako, na Zana kwa kupata data hai au kufanya shughuli. -## Hatua Zifuatazo +## Hatua Zifuatayo -**Moduli Ifuatayo:** [05-mcp - Itifaki ya Muktadha wa Mfano (MCP)](../05-mcp/README.md) +**Moduli Inayofuata:** [05-mcp - Protocol ya Muktadha wa Mfano (MCP)](../05-mcp/README.md) --- -**Uelekezaji:** [← Kwenye Moduli ya Awali: 03 - RAG](../03-rag/README.md) | [Rudi Kwenye Mwanzo](../README.md) | [Ifuatayo: Moduli 05 - MCP →](../05-mcp/README.md) +**Uelekeo:** [← Iliyotangulia: Moduli 03 - RAG](../03-rag/README.md) | [Rudi Kwenye Kuu](../README.md) | [Ifuatayo: Moduli 05 - MCP →](../05-mcp/README.md) --- -**Kiarifu cha Kutohusika**: -Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kuwa sahihi, tafadhali fahamu kwamba tafsiri za moja kwa moja zinaweza kuwa na makosa au upotoshaji. Hati asili katika lugha yake ya asili inapaswa kuzingatiwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri za mtaalamu wa kibinadamu zinapendekezwa. Hatujawajibika kwa kutoelewana au tafsiri zisizo sahihi zinazotokana na matumizi ya tafsiri hii. +**Kionyozo**: +Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake halisi inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inapendekezwa. Hatutojibu kwa kuelewa vibaya au tafsiri potofu zinazotokea kutokana na matumizi ya tafsiri hii. \ No newline at end of file diff --git a/translations/sw/README.md b/translations/sw/README.md index 34775d5b1..a2b9730a4 100644 --- a/translations/sw/README.md +++ b/translations/sw/README.md @@ -6,14 +6,14 @@ Kozi ya kujenga programu za AI kwa kutumia LangChain4j na Azure OpenAI GPT-5.2, ### 🌐 Msaada wa Lugha Nyingi -#### Inasaidiwa kupitia Kitendo cha GitHub (Kiotomatiki & Kila Wakati Kinachosasishwa) +#### Unaungwa mkono kupitia GitHub Action (Kiotomatiki & Daima Kisasa) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](./README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Unapendelea Kukunakili Mahali Pako?** +> **Unapendelea Kunakili Ndani ya Kawaida?** > -> Hifadhi hii ina lugha zaidi ya 50 za tafsiri ambazo huongeza sana ukubwa wa kupakua. Ili kunakili bila tafsiri, tumia sparse checkout: +> Hazina hii ina tafsiri za lugha zaidi ya 50 ambazo huongeza ukubwa wa pakiti ya upakuaji kwa kiasi kikubwa. Ili kunakili bila tafsiri, tumia sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,62 +29,61 @@ Kozi ya kujenga programu za AI kwa kutumia LangChain4j na Azure OpenAI GPT-5.2, > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Hii inakupa kila kitu unachohitaji kumalizia kozi kwa upakuaji wa kasi zaidi. +> Hii itakupa kila kitu unachohitaji kukamilisha kozi kwa upakuaji wa kasi zaidi. -## Jedwali la Yaliyomo +## Jedwali la Maudhui -1. [Mwanzo wa Haraka](00-quick-start/README.md) - Anza na LangChain4j -2. [Utangulizi](01-introduction/README.md) - Jifunze misingi ya LangChain4j -3. [Uhandisi wa Prompt](02-prompt-engineering/README.md) - Dhibiti muundo mzuri wa prompt -4. [RAG (Uzalishaji ulioboreshwa kwa Kutafuta)](03-rag/README.md) - Jenga mifumo ya maarifa ya akili -5. [Vifaa](04-tools/README.md) - Jumuisha zana za nje na wasaidizi rahisi -6. [MCP (Itifaki ya Muktadha wa Mfano)](05-mcp/README.md) - Fanya kazi na Itifaki ya Muktadha wa Mfano (MCP) na moduli za Agentic +1. [Utangulizi](01-introduction/README.md) - Jifunze misingi ya LangChain4j +2. [Uhandisi wa Prompt](02-prompt-engineering/README.md) - Shanisha muundo mzuri wa prompt +3. [RAG (Uzazi ulioboreshwa kwa Utafutaji)](03-rag/README.md) - Jenga mifumo ya kielimu yenye maarifa +4. [Zana](04-tools/README.md) - Unganisha zana za nje na wasaidizi rahisi +5. [MCP (Itifaki ya Muktadha wa Mfano)](05-mcp/README.md) - Fanya kazi na Itifaki ya Muktadha wa Mfano (MCP) na moduli za Agentic -### Video za Mwongozo +### Maelezo ya Video -Kila moduli ina kikao cha moja kwa moja cha rafiki ambapo tunaelekeza dhana na msimbo hatua kwa hatua. +Kila moduli ina kikao hai cha mwenzake ambapo tunapitia dhana na msimbo hatua kwa hatua. | Moduli | Video | |--------|-------| -| 01 - Utangulizi | [Kuanzia na LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Uhandisi wa Prompt | [Uhandisi wa Prompt na LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - Utangulizi | [Kuanza na LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Uhandisi wa Prompt | [Uhandisi wa Prompt kwa LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG na LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Vifaa & 05 - MCP | [Mawakala wa AI na Vifaa na MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Zana & 05 - MCP | [Mawakala wa AI pamoja na Zana na MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## Njia ya Kujifunza -**Mpya kwa LangChain4j?** Tazama [Fasili](docs/GLOSSARY.md) kwa ufafanuzi wa maneno na dhana muhimu. +**Mpya kwa LangChain4j?** Angalia [Kamusi](docs/GLOSSARY.md) kwa ufafanuzi wa maneno muhimu na dhana. -> **Mwanzo wa Haraka** +> **Anza Haraka** -1. Toa fork hifadhi hii kwenye akaunti yako ya GitHub +1. Fanyia fork hazina hii kwenye akaunti yako ya GitHub 2. Bonyeza **Code** → kichupo cha **Codespaces** → **...** → **Mpya na chaguzi...** -3. Tumia vigezo chaguomsingi – hii itachagua kontena la Maendeleo lililotengenezwa kwa kozi hii -4. Bonyeza **Unda codespace** -5. Subiri dakika 5-10 kwa mazingira kuwa tayari -6. Nenda moja kwa moja kwa [Mwanzo wa Haraka](./00-quick-start/README.md) kuanza! +3. Tumia chaguo la kawaida – hili lita chagua kontena la Maendeleo lililotengenezwa kwa ajili ya kozi hii +4. Bonyeza **Create codespace** +5. Subiri dakika 5-10 mazingira yawe tayari +6. Nenda moja kwa moja hadi [Utangulizi](./01-introduction/README.md) kuanza! -Baada ya kumaliza moduli, chunguza [Mwongozo wa Kupima](docs/TESTING.md) ili kuona dhana za upimaji za LangChain4j zinavyotumika. +Baada ya kumaliza moduli, chunguza [Mwongozo wa Upimaji](docs/TESTING.md) kuona dhana za kupima LangChain4j katika utekelezaji. -> **Kumbuka:** Mafunzo haya yanatumia Modeli za GitHub na Azure OpenAI. Moduli ya [Mwanzo wa Haraka](00-quick-start/README.md) inatumia Modeli za GitHub (hakuna usajili wa Azure unahitajika), wakati moduli 1-5 zinatumia Azure OpenAI. Anza na [akaunti ya AZURE BURE](https://aka.ms/azure-free-account) kama huna. +> **Kumbuka:** Mafunzo haya yanatumia Azure OpenAI. Anza na akaunti ya bure ya [Azure](https://aka.ms/azure-free-account) ikiwa huna moja. ## Kujifunza na GitHub Copilot -Ili kuanza kuandika msimbo haraka, fungua mradi huu katika GitHub Codespace au IDE yako ya eneo husika kwa devcontainer iliyotolewa. Devcontainer inayotumika katika kozi hii imesanifiwa awali na GitHub Copilot kwa programu ya pamoja ya AI. +Ili kuanza kuandika msimbo haraka, fungua mradi huu katika GitHub Codespace au IDE yako ya ndani ukiwa na devcontainer iliyotolewa. Devcontainer inayotumika katika kozi hii imewekwa tayari na GitHub Copilot kwa ajili ya programu ya AI iliyoambatana. -Kila mfano wa msimbo una maswali yaliyopendekezwa ambayo unaweza kumuuliza GitHub Copilot ili kuboresha uelewa wako. Tafuta dalili za 💡/🤖 katika: +Kila mfano wa msimbo una maswali yaliyopendekezwa ambayo unaweza kumuuliza GitHub Copilot ili kuelewa zaidi. Tafuta dalili za 💡/🤖 katika: -- **Vichwa vya faili za Java** - Maswali maalum kwa kila mfano -- **README za Moduli** - Mapendekezo ya kuchunguza baada ya mifano ya msimbo +- **Mada za faili za Java** - Maswali maalum kwa kila mfano +- **README za moduli** - Dalili za uchunguzi baada ya mifano ya msimbo -**Jinsi ya kutumia:** Fungua faili yoyote ya msimbo na uliza Copilot maswali yaliyopendekezwa. Ina muktadha kamili wa msimbo na inaweza kueleza, kuongeza, na kupendekeza mbadala. +**Jinsi ya kutumia:** Fungua faili yoyote ya msimbo na muulize Copilot maswali yaliyopendekezwa. Ina muktadha mzima wa misimbo na inaweza kuelezea, kuongeza, na kupendekeza mbadala. -Unataka kujifunza zaidi? Angalia [Copilot kwa Programu ya Pamoja ya AI](https://aka.ms/GitHubCopilotAI). +Unataka kujifunza zaidi? Angalia [Copilot kwa Programu ya AI iliyoambatana](https://aka.ms/GitHubCopilotAI). -## Rasilimali Zaidi +## Vyanzo Vya Ziada ### LangChain @@ -93,7 +92,7 @@ Unataka kujifunza zaidi? Angalia [Copilot kwa Programu ya Pamoja ya AI](https:// [![LangChain kwa Waanzilishi](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents +### Azure / Edge / MCP / Mawakala [![AZD kwa Waanzilishi](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) [![Edge AI kwa Waanzilishi](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) [![MCP kwa Waanzilishi](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -101,11 +100,11 @@ Unataka kujifunza zaidi? Angalia [Copilot kwa Programu ya Pamoja ya AI](https:// --- -### Mfululizo wa AI Jenereta -[![AI Jenereta kwa Waanzilishi](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Jenereta (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![AI Jenereta (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![AI Jenereta (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Mfululizo wa AI Inayozalisha +[![AI Inayozalisha kwa Waanzilishi](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI Inayozalisha (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![AI Inayozalisha (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![AI Inayozalisha (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- @@ -113,26 +112,26 @@ Unataka kujifunza zaidi? Angalia [Copilot kwa Programu ya Pamoja ya AI](https:// [![ML kwa Waanzilishi](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Sayansi ya Data kwa Waanzilishi](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI kwa Waanzilishi](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Usalama Mtandao kwa Waanza](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Uendelezaji Wavuti kwa Waanza](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT kwa Waanza](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![Maendeleo ya XR kwa Waanza](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Usalama wa Mtandao kwa Waanzilishi](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Mfululizo wa Copilot -[![Copilot kwa Kuprogramu Sambamba na AI](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot kwa C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Shughuli ya Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Kupata Msaada -Kama utakumbwa na tatizo au una maswali kuhusu kujenga programu za AI, jiunge na: +Kama utashindwa au una maswali kuhusu ujenzi wa programu za AI, jiunge: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Kama una maoni au makosa kuhusu bidhaa wakati wa kujenga, tembelea: +Kama una maoni kuhusu bidhaa au makosa wakati wa ujenzi tembelea: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) @@ -143,6 +142,6 @@ Leseni ya MIT - Angalia faili la [LICENSE](../../LICENSE) kwa maelezo. --- -**Onyo**: -Hati hii imetafsiriwa kwa kutumia huduma ya utafsiri wa AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kufanikisha usahihi, tafadhali fahamu kuwa tafsiri za mashine zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake ya asili inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa habari muhimu, tafsiri ya kitaalamu na ya binadamu inashauriwa. Hatubaliki kwa tafsiri potofu au kuelewa vibaya kunakotokana na matumizi ya tafsiri hii. +**Kionyozo**: +Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake halisi inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inapendekezwa. Hatutojibu kwa kuelewa vibaya au tafsiri potofu zinazotokea kutokana na matumizi ya tafsiri hii. \ No newline at end of file diff --git a/translations/sw/docs/GLOSSARY.md b/translations/sw/docs/GLOSSARY.md index 2f37699d8..31d3d5a6c 100644 --- a/translations/sw/docs/GLOSSARY.md +++ b/translations/sw/docs/GLOSSARY.md @@ -1,202 +1,202 @@ -# LangChain4j Kamusi +# Kamusi ya LangChain4j -## Jedwali la Yaliyomo +## Orodha ya Maudhui -- [Misingi ya Misingi](../../../docs) -- [Sehemu za LangChain4j](../../../docs) -- [Misingi ya AI/ML](../../../docs) -- [Mlinzi](../../../docs) -- [Uhandisi wa Prompt](../../../docs) -- [RAG (Uzalishaji Ulioboreshwa na Urejeshaji)](../../../docs) -- [Wakala na Zana](../../../docs) -- [Kipengele cha Wakili](../../../docs) -- [Itifaki ya Muktadha wa Mfano (MCP)](../../../docs) -- [Huduma za Azure](../../../docs) -- [Upimaji na Maendeleo](../../../docs) +- [Madhumuni Muhimu](#madhumuni-muhimu) +- [Vijumlisho vya LangChain4j](#vijumlisho-vya-langchain4j) +- [Madhumuni ya AI/ML](#madhumuni-ya-aiml) +- [Barabara za Usalama](#barabara-za-usalama) +- [Uhandisi wa Msaada wa Maandishi](#prompt-engineering---module-02) +- [RAG (Uundaji ulioboreshwa kwa Urejelezaji)](#rag-retrieval-augmented-generation---module-03) +- [Wakala na Zana](#agents-and-tools---module-04) +- [Moduli ya Kiwakilishi](#agentic-module---module-05) +- [Itifaki ya Muktadha wa Mfano (MCP)](#model-context-protocol-mcp---module-05) +- [Huduma za Azure](#azure-services---module-01) +- [Upimaji na Maendeleo](#testing-and-development---testing-guide) -Marejeleo ya haraka kwa maneno na dhana zinazotumika katika kozi nzima. +Marejeleo ya haraka kwa maneno na dhana zinazotumika katika kozi. -## Misingi ya Msingi +## Madhumuni Muhimu -**Wakala wa AI** - Mfumo unaotumia AI kufikiri na kutenda kwa uhuru. [Somo 04](../04-tools/README.md) +**Wakala wa AI** - Mfumo unaotumia AI kufikiri na kutenda kwa uhuru. [Moduli 04](../04-tools/README.md) -**Mnyororo** - Mfululizo wa shughuli ambapo matokeo huingia kwenye hatua inayofuata. +**Mnyororo** - Mfuatano wa shughuli ambapo matokeo hutumiwa katika hatua inayofuata. -**Ugawaji Vipande** - Kugawanya nyaraka katika vipande vidogo. Kawaida: tokeni 300-500 zenye mkusanyiko. [Somo 03](../03-rag/README.md) +**Kugawanya** - Kuvunja hati katika vipande vidogo. Za kawaida: tokeni 300-500 zikiwa na mchanganyiko. [Moduli 03](../03-rag/README.md) -**Dirisha la Muktadha** - Tokeni nyingi zaidi ambazo mfano unaweza kusindika. GPT-5.2: tokeni 400K (hadi 272K ingizo, 128K matokeo). +**Dirisha la Muktadha** - Kiasi kikubwa cha tokeni mfano unaweza kushughulikia. GPT-5.2: tokeni 400K (yaa 272K ya ingizo, 128K ya matokeo). -**Embeddings** - Vektors za nambari zinazoonyesha maana ya maandishi. [Somo 03](../03-rag/README.md) +**Embedding** - Vekteta za nambari zinazowakilisha maana ya maandishi. [Moduli 03](../03-rag/README.md) -**Kuita Kazi** - Mfano hutengeneza maombi yaliyopangwa kwa kufungua vitengeza vya nje. [Somo 04](../04-tools/README.md) +**Kupiga Simu ya Kazi** - Mfano hutengeneza maombi yaliyo sanifu kwa kupiga simu kazi za nje. [Moduli 04](../04-tools/README.md) -**Halusinasheni** - Wakati mifano hutengeneza habari zisizo sahihi lakini zinaonekana kuwa halali. +**Ku Halushinatia** - Wakati mifano inazalisha taarifa zisizo sahihi lakini zinaonekana kuwa za kweli. -**Prompt** - Ingizo la maandishi kwa mfano wa lugha. [Somo 02](../02-prompt-engineering/README.md) +**Msaada wa Maandishi** - Maandishi yaliyo ingizwa kwenye mfano wa lugha. [Moduli 02](../02-prompt-engineering/README.md) -**Utafutaji wa Semantiki** - Kutafuta kwa maana kwa kutumia embeddings, sio maneno muhimu. [Somo 03](../03-rag/README.md) +**Utafutaji wa Kimaana** - Utafutaji kwa maana kwa kutumia embedding, si maneno muhimu. [Moduli 03](../03-rag/README.md) -**Kiasi cha Hali vs Isiyo na Hali** - Isiyo na hali: hakuna kumbukumbu. Na hali: huhifadhi historia ya mazungumzo. [Somo 01](../01-introduction/README.md) +**Mimi au Msingi** - Msingi: huna kumbukumbu. Mimi: huthamini historia ya mazungumzo. [Moduli 01](../01-introduction/README.md) -**Tokeni** - Vitengo vya msingi vya maandishi vinavyochakatwa na mifano. Huathiri gharama na vizingiti. [Somo 01](../01-introduction/README.md) +**Tokeni** - Vitengo vya msingi vya maandishi ambavyo mifano hushughulikia. Huidhinisha gharama na vizingiti. [Moduli 01](../01-introduction/README.md) -**Mnyororo wa Zana** - Utekelezaji wa zana mfululizo ambapo matokeo huonyesha mwito unaofuata. [Somo 04](../04-tools/README.md) +**Uunganishaji wa Zana** - Kutekeleza zana mfululizo ambapo matokeo hutumika kwa simu inayofuata. [Moduli 04](../04-tools/README.md) -## Sehemu za LangChain4j +## Vijumlisho vya LangChain4j -**AiServices** - Huunda interfaces salama za huduma za AI. +**AiServices** - Inaunda interfaces za huduma za AI zenye usalama wa aina. -**OpenAiOfficialChatModel** - Mteja wa umoja kwa miundo ya OpenAI na Azure OpenAI. +**OpenAiOfficialChatModel** - Mteja wa umoja kwa ajili ya mifano ya OpenAI na Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Huunda embeddings kwa kutumia mteja rasmi wa OpenAI (huunga mkono OpenAI na Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Inaunda embedding kwa kutumia mteja Rasmi wa OpenAI (huunga mkono OpenAI na Azure OpenAI). -**ChatModel** - Kiolesura kikuu kwa mifano ya lugha. +**ChatModel** - Kiolesura cha msingi kwa mifano ya lugha. **ChatMemory** - Huhifadhi historia ya mazungumzo. -**ContentRetriever** - Hupata vipande vya nyaraka vinavyofaa kwa RAG. +**ContentRetriever** - Huona vipande vya hati vinavyofaa kwa RAG. -**DocumentSplitter** - Hugawanya nyaraka katika vipande. +**DocumentSplitter** - Huvunja hati katika vipande. -**EmbeddingModel** - Hubadilisha maandishi kuwa vektors za nambari. +**EmbeddingModel** - Hubadilisha maandishi kuwa vekteta za nambari. -**EmbeddingStore** - Huhifadhi na kurejesha embeddings. +**EmbeddingStore** - Huhifadhi na hurudisha embedding. -**MessageWindowChatMemory** - Huhifadhi dirisha linalosogezwa la ujumbe wa karibuni. +**MessageWindowChatMemory** - Huhifadhi dirisha linaloelea la ujumbe wa karibuni. -**PromptTemplate** - Huunda prompts zinazoweza kutumika tena zenye mabano ya `{{variable}}`. +**PromptTemplate** - Huutengeneza misaada inayorudiwa na sehemu za `{{variable}}`. **TextSegment** - Kipande cha maandishi chenye metadata. Kinatumika katika RAG. **ToolExecutionRequest** - Huonyesha ombi la utekelezaji wa zana. -**UserMessage / AiMessage / SystemMessage** - Aina za ujumbe wa mazungumzo. +**UserMessage / AiMessage / SystemMessage** - Aina za ujumbe za mazungumzo. -## Misingi ya AI/ML +## Madhumuni ya AI/ML -**Few-Shot Learning** - Kutoa mifano katika prompts. [Somo 02](../02-prompt-engineering/README.md) +**Kujifunza kwa Mfano Mdogo** - Kutoa mifano ndani ya msaada. [Moduli 02](../02-prompt-engineering/README.md) -**Mfano Mkubwa wa Lugha (LLM)** - Mifano ya AI iliyofunzwa kwa data nyingi za maandishi. +**Mfano Mkubwa wa Lugha (LLM)** - Mifano ya AI iliyofunzwa kwa data kubwa ya maandishi. -**Juhudi za Kuhesabu** - Parameta ya GPT-5.2 inayodhibiti undani wa fikra. [Somo 02](../02-prompt-engineering/README.md) +**Juhudi za Kufikiri** - Kigezo cha GPT-5.2 kinachodhibiti kina cha kufikiri. [Moduli 02](../02-prompt-engineering/README.md) -**Joto** - Hudhibiti mwelekeo wa matokeo. Chini=msingi, juu=ubunifu. +**Joto** - Hudhibiti mwendelezo wa matokeo. Chini=sahihi, juu=mbunifu. -**Hifadhidata ya Vektors** - Hifadhidata maalum kwa embeddings. [Somo 03](../03-rag/README.md) +**Hifadhidata ya Vekteta** - Hifadhidata maalum kwa embedding. [Moduli 03](../03-rag/README.md) -**Zero-Shot Learning** - Kutekeleza majukumu bila mifano. [Somo 02](../02-prompt-engineering/README.md) +**Kujifunza Bila Mfano** - Kutekeleza kazi bila mifano. [Moduli 02](../02-prompt-engineering/README.md) -## Mlinzi - [Somo 00](../00-quick-start/README.md) +## Barabara za Usalama -**Ulinzi kwa Ngazi Nyingi** - Mbinu ya usalama yenye tabaka nyingi ikijumuisha mlinzi wa kiwango cha programu na vichujio vya usalama vya mtoa huduma. +**Ulinzi wa Kina** - Mbinu ya usalama wa tabaka nyingi inayounganisha barabara za usalama kwa ngazi ya programu pamoja na vichujio vya usalama vya mtoa huduma. -**Kuzuia Kuwezeshwa** - Mtoa huduma hutupa kosa la HTTP 400 kwa ukiukaji makubwa wa maudhui. +**Kizuizi Mkali** - Mtoa huduma hutoa kosa la HTTP 400 kwa ukiukaji mkubwa wa maudhui. -**InputGuardrail** - Kiolesura cha LangChain4j kwa kuthibitisha ingizo la mtumiaji kabla halijafika kwa LLM. Huhifadhi gharama na kuchelewesha kwa kuzuia prompts hatarishi mapema. +**InputGuardrail** - Kiolesura cha LangChain4j cha kuthibitisha pembejeo za mtumiaji kabla hazijafika kwa LLM. Huokoa gharama na ucheleweshaji kwa kuzuia misaada hatari mapema. -**InputGuardrailResult** - Aina ya kurudisha kwa uthibitishaji wa mlinzi: `success()` au `fatal("reason")`. +**InputGuardrailResult** - Aina ya kurudisha uthibitishaji wa barabara za pembejeo: `success()` au `fatal("reason")`. -**OutputGuardrail** - Kiolesura kwa kuthibitisha majibu ya AI kabla ya kurudisha kwa watumiaji. +**OutputGuardrail** - Kiolesura cha kuthibitisha majibu ya AI kabla ya kurudisha kwa watumiaji. -**Provider Safety Filters** - Vichujio vya maudhui vilivyojengwa kutoka kwa watoa huduma za AI (mfano, GitHub Models) vinavyoshika ukiukaji katika kiwango cha API. +**Vichujio vya Usalama vya Mtoa Huduma** - Vichujio vya maudhui vilivyojengwa ndani kutoka kwa watoa huduma wa AI (mfano, Azure OpenAI) vinavyokamata ukiukaji kwenye ngazi ya API. -**Kukataa Kwa Heshima** - Mfano hukataa kwa heshima kujibu bila kutoa kosa. +**Kukataa kwa Hadhari** - Mfano unakataa kwa heshima kujibu bila kutoa kosa. -## Uhandisi wa Prompt - [Somo 02](../02-prompt-engineering/README.md) +## Uhandisi wa Msaada wa Maandishi - [Moduli 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Fikra kwa hatua kwa usahihi bora. +**Mnyororo wa Mawazo** - Kufikiri hatua kwa hatua kwa usahihi bora. -**Matokeo Yaliyolazimishwa** - Kulazimisha muundo au mfumo maalum. +**Matokeo yaliyo Thibitiwa** - Kudumisha muundo au mfumo mahususi. -**Shauku Zaidi** - Mfano wa GPT-5.2 kwa fikra za kina. +**Hamasa ya Juu** - Muundo wa GPT-5.2 wa kufikiri kwa undani. -**Shauku Ndogo** - Mfano wa GPT-5.2 kwa majibu ya haraka. +**Hamasa ya Chini** - Muundo wa GPT-5.2 wa majibu ya haraka. -**Mazungumzo ya Mizunguko Mingi** - Kuhifadhi muktadha kati ya kubadilishana. +**Mazungumzo ya Mizunguko Mingi** - Kudumisha muktadha katika kubadilishana. -**Prompting kwa Kulingana na Nafasi** - Kuweka tabia ya mfano kupitia ujumbe wa mfumo. +**Msaada wa Kulingana na Nafasi** - Kuweka tabia ya mfano kupitia ujumbe wa mfumo. -**Utambuzi wa Nafsi** - Mfano hupima na kuboresha matokeo yake. +**Kujitathmini** - Mfano huchambua na kuboresha matokeo yake. -**Uchambuzi Uliofungwa** - Mfumo wa tathmini uliowekwa. +**Uchambuzi ulio Pangwa** - Mfumo thabiti wa tathmini. -**Mfumo wa Utekelezaji wa Kazi** - Panga → Tekeleza → Fupisha. +**Mfumo wa Kutekeleza Kazi** - Panga → Tekeleza → Fupisha. -## RAG (Uzalishaji Ulioboreshwa na Urejeshaji) - [Somo 03](../03-rag/README.md) +## RAG (Uundaji ulioboreshwa kwa Urejelezaji) - [Moduli 03](../03-rag/README.md) -**Mchakato wa Usindikaji wa Nyaraka** - Pakua → gawanya → ingiza → hifadhi. +**Mtiririko wa Usindikaji wa Hati** - Pakua → gawanya → fanya embedding → hifadhi. -**Hifadhi ya Embedding Isiyo ya Kudumu** - Hifadhi isiyoendelezwa kwa upimaji. +**Hifadhi ya Embedding Kabla ya Uhifadhi wa Kudumu** - Hifadhi isiyodumu kwa ajili ya upimaji. -**RAG** - Inachanganya urejeshaji na uzalishaji kuweka majibu kwenye muktadha. +**RAG** - Inachanganya urejelezaji na uundaji kutegemeza majibu. -**Alama ya Ufanano** - Kipimo (0-1) cha ufanano wa semantiki. +**Alama ya Ulinganifu** - Kipimo (0-1) cha ulinganifu wa maana. -**Marejeo ya Chanzo** - Metadata kuhusu maudhui yaliyopatikana. +**Marejeo ya Chanzo** - Metadata kuhusu maudhui yaliyorejelewa. -## Wakala na Zana - [Somo 04](../04-tools/README.md) +## Wakala na Zana - [Moduli 04](../04-tools/README.md) -**Maelezo ya @Tool** - Inaonyesha mbinu za Java kama zana zinazoweza kuitwa na AI. +**@Tool Annotation** - Inaashiria njia za Java kama zana zinazoweza kupigiwa na AI. -**Mfumo wa ReAct** - Fikiri → Tenda → Angalia → Rudia. +**Muundo wa ReAct** - Fikiria → Tenda → Angalia → Rudia. -**Usimamizi wa Kikao** - Muktadha tofauti kwa watumiaji mbalimbali. +**Usimamizi wa Kikao** - Muktadha tofauti kwa watumiaji tofauti. -**Zana** - Kazi ambayo wakala wa AI anaweza kuita. +**Zana** - Kazi ambayo wakala wa AI anaweza kupiga simu. -**Maelezo ya Zana** - Nyaraka ya kusudi la zana na vigezo. +**Maelezo ya Zana** - Nyaraka za kusudio la zana na vigezo. -## Kipengele cha Wakili - [Somo 05](../05-mcp/README.md) +## Moduli ya Kiwakilishi - [Moduli 05](../05-mcp/README.md) -**Maelezo ya @Agent** - Inaonyesha interfaces kama wakala wa AI yenye kigezo cha tabia kilichosemwa. +**@Agent Annotation** - Inaashiria interfaces kama wakala wa AI zenye ufafanuzi wa tabia kwa njia ya tamko. -**Msimamizi wa Wakala** - Kiungo cha kufuatilia utekelezaji wa wakala kupitia `beforeAgentInvocation()` na `afterAgentInvocation()`. +**Msikilizaji wa Wakala** - Kiungo cha kufuatilia utekelezaji wa wakala kwa `beforeAgentInvocation()` na `afterAgentInvocation()`. -**Eneo la Agentic** - Kumbukumbu inayoshirikiwa ambapo mawakala huhifadhi matokeo kwa kutumia `outputKey` kwa mawakala wa hatua inayofuata. +**Eneo la Kiwakilishi** - Kumbukumbu ya pamoja ambamo mawakala hifadhi matokeo kwa kutumia `outputKey` kwa mawakala wa downstream kuyatumia. **AgenticServices** - Kiwanda cha kuunda mawakala kwa kutumia `agentBuilder()` na `supervisorBuilder()`. -**Kazi ya Masharti** - Njia kulingana na masharti kwa mawakala maalum tofauti. +**Mtiririko wa Kazi wa Masharti** - Njia inayochagua mtoa huduma wa maalum kulingana na masharti. -**Human-in-the-Loop** - Mfano wa mchakato unaoingiza binadamu kuangalia au kutoa idhini. +**Binadamu Katika Mzunguko** - Muundo wa mtiririko wa kazi unaoongeza sehemu za binadamu kwa idhini au ukaguzi wa maudhui. -**langchain4j-agentic** - Tegemezi la Maven kwa uundaji wa wakala kwa njia ya kidokezo (jaribio). +**langchain4j-agentic** - Tegemezi la Maven la ujenzi wa mawakala kwa njia ya matamko (jaribio). -**mzunguko wa kazi** - Rudia utekelezaji wa wakala mpaka hali itimizwe (mfano, alama ya ubora ≥ 0.8). +**Mtiririko wa Kazi wa Mzunguko** - Rudia utekelezaji wa wakala hadi sharti lipatikane (mfano, alama ya ubora ≥ 0.8). -**outputKey** - Kigezo cha maelezo ya wakala kinachoeleza mahali matokeo huhifadhiwa katika Eneo la Agentic. +**outputKey** - Kigezo cha maelezo ya wakala kinachobainisha mahali ambapo matokeo yatahifadhiwa katika Eneo la Kiwakilishi. -**Mchakato wa Kazi kwa Nguvu Moja** - Endesha mawakala wengi kwa wakati mmoja kwa majukumu huru. +**Mtiririko wa Kazi Sambamba** - Endesha mawakala wengi kwa wakati mmoja kwa kazi huru. -**Mikakati ya Majibu** - Jinsi msimamizi anavyoandaa jibu la mwisho: LAST, SUMMARY, au SCORED. +**Mkakati wa Majibu** - Jinsi msimamizi anavyoandaa jibu la mwisho: MWISHO, MUHTASARI, au ALAMA. -**Mchakato wa Kazi Mfululizo** - Tekeleza mawakala kwa mpangilio ambapo matokeo huingia kwenye hatua inayofuata. +**Mtiririko wa Kazi Mfuatano** - Tekeleza mawakala kwa mpangilio ambapo matokeo huenda kwenye hatua inayofuata. -**Mfano wa Wakili wa Msimamizi** - Mfano wa kipekee wa wakala ambapo msimamizi wa LLM huamua kwa nguvu ni mawakala gani ndogo wataiwe. +**Muundo wa Wakala Msimamizi** - Muundo wa kipekee wa wakala ambapo msimamizi LLM huchagua kwa nguvu mawakala madogo wa kuitwa. -## Itifaki ya Muktadha wa Mfano (MCP) - [Somo 05](../05-mcp/README.md) +## Itifaki ya Muktadha wa Mfano (MCP) - [Moduli 05](../05-mcp/README.md) -**langchain4j-mcp** - Tegemezi la Maven kwa muunganiko wa MCP katika LangChain4j. +**langchain4j-mcp** - Tegemezi la Maven kwa ushirikiano wa MCP katika LangChain4j. **MCP** - Itifaki ya Muktadha wa Mfano: kiwango cha kuunganisha programu za AI na zana za nje. Jenga mara moja, tumia kila mahali. -**Mteja wa MCP** - Programu inayounganisha na seva za MCP kugundua na kutumia zana. +**MCP Client** - Programu inayounganisha kwa seva za MCP kugundua na kutumia zana. -**Server ya MCP** - Huduma inayotoa zana kupitia MCP zenye maelezo wazi na michoro ya vigezo. +**MCP Server** - Huduma inayoonyesha zana kupitia MCP na maelezo wazi pamoja na miundo ya vigezo. -**McpToolProvider** - Sehemu ya LangChain4j inayojifunga zana za MCP kwa ajili ya matumizi katika huduma za AI na mawakala. +**McpToolProvider** - Kijumlisho cha LangChain4j kinachozunguka zana za MCP kwa matumizi katika huduma za AI na mawakala. -**McpTransport** - Kiolesura cha mawasiliano ya MCP. Matumizi ni pamoja na Stdio na HTTP. +**McpTransport** - Kiolesura cha mawasiliano ya MCP. Utekelezaji ni pamoja na Stdio na HTTP. -**Usafirishaji wa Stdio** - Usafirishaji wa mchakato wa ndani kupitia stdin/stdout. Hufaa kwa upatikanaji wa mfumo wa faili au zana za mstari wa amri. +**Usafirishaji wa Stdio** - Usafirishaji wa mchakato wa ndani kupitia stdin/stdout. Inafaa kwa upatikanaji wa mfumo wa faili au zana za mstari wa amri. -**StdioMcpTransport** - Utekelezaji wa LangChain4j unaounda seva ya MCP kama mchakato msaidizi. +**StdioMcpTransport** - Utekelezaji wa LangChain4j unaozindua seva ya MCP kama mchakato mdogo. -**Ugunduzi wa Zana** - Mteja huuliza seva kuhusu zana zinazopatikana zenye maelezo na michoro. +**Gundua Zana** - Mteja huuliza seva kuhusu zana zinazopatikana zilizo na maelezo na muundo. -## Huduma za Azure - [Somo 01](../01-introduction/README.md) +## Huduma za Azure - [Moduli 01](../01-introduction/README.md) -**Azure AI Search** - Utafutaji wa wingu yenye uwezo wa vektors. [Somo 03](../03-rag/README.md) +**Azure AI Search** - Utafutaji wa wingu wenye uwezo wa vekteta. [Moduli 03](../03-rag/README.md) **Azure Developer CLI (azd)** - Hupeleka rasilimali za Azure. @@ -204,29 +204,27 @@ Marejeleo ya haraka kwa maneno na dhana zinazotumika katika kozi nzima. **Bicep** - Lugha ya Azure ya miundombinu kama msimbo. [Mwongozo wa Miundombinu](../01-introduction/infra/README.md) -**Jina la Utekelezaji** - Jina la utekelezaji wa mfano katika Azure. +**Jina la Uwekaji** - Jina la uwekaji wa mfano katika Azure. -**GPT-5.2** - Mfano wa hivi karibuni wa OpenAI wenye udhibiti wa fikra. [Somo 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Mfano wa OpenAI wa hivi karibuni wenye udhibiti wa fikra. [Moduli 02](../02-prompt-engineering/README.md) ## Upimaji na Maendeleo - [Mwongozo wa Upimaji](TESTING.md) -**Dev Container** - Mazingira ya maendeleo yaliyopakiwa ndani ya kontena. [Mpangilio](../../../.devcontainer/devcontainer.json) +**Kifurushi cha Maendeleo** - Mazingira yaliyofungashwa kwa maendeleo. [Marekebisho](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Uwanja wa majaribio wa mfano wa AI bure. [Somo 00](../00-quick-start/README.md) +**Upimaji wa Kumbukumbu ndani ya Kumbukumbu** - Upimaji kwa hifadhi ya muda. -**Upimaji wa Kumbukumbu Ndani** - Upimaji kwa kutumia hifadhi ya ndani. +**Upimaji wa Uunganishaji** - Upimaji kwa miundombinu halisi. -**Upimaji wa Muunganiko** - Upimaji kwa kutumia miundombinu halisi. +**Maven** - Zana ya uendeshaji majengo ya Java. -**Maven** - Kifaa cha ujenzi cha programu ya Java. +**Mockito** - Mfumo wa kuiga katika Java. -**Mockito** - Mfumo wa kuiga kwa Java. - -**Spring Boot** - Mfumo wa programu ya Java. [Somo 01](../01-introduction/README.md) +**Spring Boot** - Mfumo wa programu wa Java. [Moduli 01](../01-introduction/README.md) --- -**Tangazo la Majadiliano**: -Nyaraka hii imefasiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kwa usahihi, tafadhali fahamu kwamba tafsiri za moja kwa moja zinaweza kuwa na makosa au upungufu wa usahihi. Nyaraka ya asili katika lugha yake halisi inapaswa kuzingatiwa kama chanzo halali. Kwa habari muhimu, tafsiri ya kitaalamu ya binadamu inapendekezwa. Hatubeba dhamana zozote kwa kutoelewana au tafsiri zisizo sahihi zinazosababishwa na matumizi ya tafsiri hii. +**Kionyozo**: +Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake halisi inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inapendekezwa. Hatutojibu kwa kuelewa vibaya au tafsiri potofu zinazotokea kutokana na matumizi ya tafsiri hii. \ No newline at end of file diff --git a/translations/sw/docs/TESTING.md b/translations/sw/docs/TESTING.md index 1ec8ed8fe..2270c3017 100644 --- a/translations/sw/docs/TESTING.md +++ b/translations/sw/docs/TESTING.md @@ -1,20 +1,20 @@ # Kupima Programu za LangChain4j -## Jedwali la Yaliyomo +## Jedwali la Maudhui -- [Kuanza Haraka](../../../docs) -- [Mavazi ya Vipimo](../../../docs) -- [Kukimbia Vipimo](../../../docs) -- [Kukimbia Vipimo katika VS Code](../../../docs) -- [Mifano ya Vipimo](../../../docs) -- [Falsafa ya Kupima](../../../docs) -- [Hatua Zinazofuata](../../../docs) +- [Anza Haraka](#anza-haraka) +- [Mambo Yanayojumuishwa Katika Mitihani](#mambo-yanayojumuishwa-katika-mitihani) +- [Kukimbia Mitihani](#kukimbia-mitihani) +- [Kukimbia Mitihani Katika VS Code](#kukimbia-mitihani-katika-vs-code) +- [Mifumo ya Kupima](#mifumo-ya-kupima) +- [Falsafa ya Kupima](#falsafa-ya-kupima) +- [Hatua Zifuatazo](#hatua-zifuatazo) -Mwongozo huu unakuongoza kupitia vipimo vinavyoonyesha jinsi ya kupima programu za AI bila kuhitaji funguo za API au huduma za nje. +Mwongozo huu unakupeleka kupitia mitihani inayothibitisha jinsi ya kupima programu za AI bila hitaji la funguo za API au huduma za nje. -## Kuanza Haraka +## Anza Haraka -Kimbia vipimo vyote kwa amri moja: +Kimbia mitihani yote kwa amri moja: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Unapopitia vipimo vyote bila hitilafu, utaona matokeo kama picha iliyo hapa chini — vipimo vinafanyika bila makosa. +Unapokamilisha mitihani yote bila makosa, utapata matokeo kama picha ya skrini hapa chini — mitihani inaendeshwa bila kushindwa. Successful Test Results -*Utekelezaji wa mtihani uliofanikiwa unaonyesha vipimo vyote vikienda bila makosa* +*Utekelezaji mzuri wa mtihani unaoonyesha mitihani yote imepitwa bila kushindwa* -## Mavazi ya Vipimo +## Mambo Yanayojumuishwa Katika Mitihani -Kozi hii inazingatia **vipimo vya kitengo** vinavyotekelezwa kwa ndani. Kila kipimo kinaonyesha dhana maalum ya LangChain4j pekee. Piramidi ya upimaji hapa chini inaonyesha wapi vipimo vya kitengo vinakaa — vinaunda msingi wa haraka na wa kuaminika ambao mkakati wako wa upimaji hujengwa juu yake. +Kozi hii inalenga kwenye **mitihani ya vitengo** inayotekelezwa kwa sehemu za ndani. Kila mtihani unaonyesha dhana maalum ya LangChain4j kwa kujitegemea. Piramidi ya upimaji hapa chini inaonyesha wapi mitihani ya vitengo inapatikana — ni msingi wa haraka, wa kuaminika ambayo mkakati wako wa upimaji unajenga juu yake. Testing Pyramid -*Piramidi ya upimaji inayoonyesha usawa kati ya vipimo vya kitengo (haraka, vya peke), vipimo vya muunganiko (vitu halisi), na vipimo vya mwisho hadi mwisho. Mafunzo haya yanahusu upimaji wa kitengo.* +*Piramidi ya upimaji ikionyesha usawa kati ya mitihani ya vitengo (haraka, peke yake), mitihani ya muingiliano (vipengele halisi), na mitihani ya mwisho-mwisho. Mafunzo haya yanajumuisha upimaji wa vitengo.* -| Moduli | Vipimo | Lengo | Faili Muhimu | -|--------|--------|-------|--------------| -| **00 - Kuanza Haraka** | 6 | Mifano ya maagizo na uingizaji wa mabadiliko | `SimpleQuickStartTest.java` | -| **01 - Utangulizi** | 8 | Kumbukumbu ya mazungumzo na gumzo linaloendelea | `SimpleConversationTest.java` | -| **02 - Uhandisi wa Maagizo** | 12 | Mifumo ya GPT-5.2, viwango vya hamu, matokeo yaliyoandaliwa | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Kuingiza hati, embeddings, utafutaji wa ufanano | `DocumentServiceTest.java`` | -| **04 - Zana** | 12 | Kuitisha kazi na kuunganishwa kwa zana | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Itifaki ya Muktadha wa Mfano kwa usafirishaji wa stdio | `SimpleMcpTest.java` | +| Moduli | Mitihani | Lengo | Faili Muhimu | +|--------|----------|-------|--------------| +| **01 - Utangulizi** | 8 | Kumbukumbu ya mazungumzo na mazungumzo yaliyohifadhiwa | `SimpleConversationTest.java` | +| **02 - Uhandisi wa Amri** | 12 | Mifumo ya GPT-5.2, viwango vya hamu, matokeo yaliyopangwa | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Kuingiza hati, mbinu za kuingiza, utafutaji wa fananisho | `DocumentServiceTest.java` | +| **04 - Zana** | 12 | Kupiga simu za kazi na mlolongo wa zana | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Protokoli ya Muktadha wa Mfano kwa usafirishaji wa stdio | `SimpleMcpTest.java` | -## Kukimbia Vipimo +## Kukimbia Mitihani -**Kimbia vipimo vyote kutoka kwenye mzizi:** +**Kimbia mitihani yote kutoka mzizi:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Kimbia vipimo vya moduli maalum:** +**Kimbia mitihani ya moduli maalum:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Kimbia darasa moja la kipimo:** +**Kimbia darasa moja la mtihani:** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Kimbia njia moja ya kipimo:** +**Kimbia njia mahsusi ya mtihani:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#inapaswaKudumishaHistoriaYaMazungumzo +mvn test -Dtest=SimpleConversationTest#inapaswaKuwekaHistoriaYaMazungumzo ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#inapaswaKudumishaHistoriaYaMazungumzo +mvn --% test -Dtest=SimpleConversationTest#inapaswaHifadhiHistoriaYaMazungumzo ``` -## Kukimbia Vipimo katika VS Code +## Kukimbia Mitihani Katika VS Code -Ikiwa unatumia Visual Studio Code, Test Explorer hutoa kiolesura cha picha kwa ajili ya kukimbia na kufuatilia vipimo. +Ikiwa unatumia Visual Studio Code, Mchunguzi wa Mitihani hutoa kiolesura cha picha kwa ajili ya kukimbia na kufafanua mitihani. VS Code Test Explorer -*Test Explorer ya VS Code inaonyesha mti wa vipimo na madarasa yote ya vipimo ya Java pamoja na njia binafsi za vipimo* +*Mchunguzi wa Mitihani wa VS Code unaonyesha mti wa mitihani na madarasa yote ya majaribio ya Java na njia za mtihani binafsi* -**Ili kukimbia vipimo katika VS Code:** +**Ili kukimbia mitihani katika VS Code:** -1. Fungua Test Explorer kwa kubofya ikoni ya beaker katika Bar ya Shughuli -2. Panua mti wa vipimo kuona moduli zote na madarasa ya vipimo -3. Bofya kitufe cha kucheza pamoja na kipimo chochote kuikimbia chenyewe -4. Bofya "Run All Tests" ili kutekeleza seti yote -5. Bonyeza kitufe cha kulia kwenye kipimo na chagua "Debug Test" kuweka alama za kupumzika na kupitia nambari hatua kwa hatua +1. Fungua Mchunguzi wa Mitihani kwa kubofya ikoni ya beaker katika Njia ya Shughuli +2. Panua mti wa mitihani ili kuona moduli na madarasa ya mtihani yote +3. Bonyeza kitufe cha kucheza karibu na mtihani wowote kuukimbia peke yake +4. Bonyeza "Run All Tests" kukimbia seti nzima +5. Bonyeza kulia mtihani wowote na chagua "Debug Test" kuweka alama za kukomoa na kupitia msimbo hatua kwa hatua -Test Explorer inaonyesha tiki za kijani kwa vipimo vinavyopita na kutoa ujumbe wa makosa marefu wakati vipimo vinaposhindwa. +Mchunguzi wa Mitihani unaonyesha tiki za kijani kwa mitihani iliyopita na kutoa ujumbe wa kina wakati mitihani inashindwa. -## Mifano ya Vipimo +## Mifumo ya Kupima -### Mfano 1: Kupima Mifano ya Maagizo +### Mfano 1: Kupima Maumbo ya Amri -Mfano rahisi zaidi hupima mifano ya maagizo bila kuitisha mfano wa AI. Unathibitisha kwamba uingizaji wa mabadiliko unafanyika kwa usahihi na maagizo yameundwa kama inavyotarajiwa. +Mfano rahisi kabisa hupima maumbo ya amri bila kuita mfano wowote wa AI. Unathibitisha kuwa mbadilishaji wa vigezo unafanya kazi vizuri na maagizo yamepangwa kama inavyotarajiwa. Prompt Template Testing -*Kupima mifano ya maagizo ikionyesha mtiririko wa uingizaji wa mabadiliko: mfano wenye sehemu za ujazo → thamani zinaingizwa → matokeo yamehakikishwa* +*Kupima maumbo ya amri kuonyesha mchakato wa mbadilishaji wa vigezo: kiolezo chenye nafasi za kubadilisha → maadili yamewekwa → pato limehakikiwa* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Kipimo hiki kiko katika `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Kimbia:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#jaribioLaMfumoWaMwanzoWaMaandishi -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#jaribuMpangilioMfumoWaKiolezo -``` +Mfano huu unathibitisha kuwa mbadilishaji wa vigezo unafanya kazi vizuri na maagizo yamepangwa kama inavyotarajiwa — hakuna hitaji la funguo za API au simu ya mfano. ### Mfano 2: Kuiga Mifano ya Lugha -Unapopima mantiki ya mazungumzo, tumia Mockito kuunda mifano bandia inayorudisha majibu yaliyobainishwa. Hii hufanya vipimo kuwa vya haraka, bure, na vinavyotarajiwa. +Unapopima mantiki ya mazungumzo, tumia Mockito kuunda mifano bandia inayorejesha majibu yaliyowekwa kabla. Hii inafanya mitihani kuwa ya haraka, bure, na inayoaminika. Mock vs Real API Comparison -*Ulinganisho unaoonyesha kwa nini kuiga ni bora kwa vipimo: ni haraka, bure, vinavyotarajiwa, na havihitaji funguo za API* +*Ulinganisho unaoonyesha kwa nini kuiga ni bora kwa upimaji: ni haraka, bure, inayoaminika, na haina hitaji la funguo za API* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // Ujumbe 3 za mtumiaji + 3 za AI + assertThat(history).hasSize(6); // ujumbe 3 wa mtumiaji + ujumbe 3 wa AI } } ``` -Mfano huu unaonekana katika `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Kuiga huthibitisha tabia thabiti ili uweze kuthibitisha usimamizi wa kumbukumbu unafanya kazi vizuri. +Mfano huu unaonekana katika `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Kuiga kunahakikisha tabia sawa ili uweze kuthibitisha usimamizi wa kumbukumbu kwa usahihi. -### Mfano 3: Kupima Upweke wa Mazungumzo +### Mfano 3: Kupima Ujitegemeaji wa Mazungumzo -Kumbukumbu ya mazungumzo lazima ihifadhi watumiaji wengi kando. Kipimo hiki kinathibitisha kwamba mazungumzo hayaorodani muktadha. +Kumbukumbu ya mazungumzo lazima iziwe tofauti kwa watumiaji mbalimbali. Mtihani huu unathibitisha kuwa mazungumzo hayaingi muktadha wa mtu mwingine. Conversation Isolation -*Kupima upweke wa mazungumzo kuonyesha maduka ya kumbukumbu tofauti kwa watumiaji tofauti ili kuzuia mchanganyiko wa muktadha* +*Kupima ujitegemeaji wa mazungumzo kuonyesha kuhifadhi kumbukumbu tofauti kwa watumiaji tofauti ili kuzuia kuchanganya muktadha* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Mazungumzo kila moja yana historia yake huru. Katika mifumo ya uzalishaji, upweke huu ni muhimu kwa programu za watumiaji wengi. +Kila mazungumzo huhifadhi historia yake peke yake. Katika mifumo ya uzalishaji, ujitegemeaji huu ni muhimu kwa programu za watumiaji wengi. -### Mfano 4: Kupima Zana kwa Kujitegemea +### Mfano 4: Kupima Zana Peke Yake -Zana ni kazi ambazo AI inaweza kuziita. Zipime moja kwa moja kuhakikisha zinafanya kazi vizuri hata kama AI haijazihusisha. +Zana ni kazi ambazo AI inaweza kuitisha. Zipime moja kwa moja kuhakikisha zinafanya kazi vizuri bila kuathiriwa na maamuzi ya AI. Tools Testing -*Kupima zana kwa kujitegemea kuonyesha utekelezaji wa zana za kuiga bila kuitisha AI ili kuthibitisha mantiki ya biashara* +*Kupima zana peke yake kuonyesha matumizi ya zana bandia bila simu za AI kuthibitisha mantiki ya biashara* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Vipimo hivi kutoka `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` vinathibitisha mantiki ya zana bila ushiriki wa AI. Mfano wa mlolongo unaonyesha jinsi matokeo ya zana moja yanavyoingia kama ingizo kwa nyingine. +Mitihani hii kutoka `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` inathibitisha mantiki ya zana bila kuhusika kwa AI. Mfano wa mlolongo unaonyesha jinsi pato la zana moja linaingizwa kama ingizo la nyingine. -### Mfano 5: Kupima RAG Ndani ya Kumbukumbu +### Mfano 5: Kupima RAG Kama Kumbukumbu Ndani ya Kumbukumbu -Mifumo ya RAG kwa kawaida zinahitaji hifadhidata za vector na huduma za embedding. Mfano wa ndani ya kumbukumbu unakuwezesha kupima mchakato mzima bila tegemezi za nje. +Mifumo ya RAG kawaida inahitaji database za vekta na huduma za kuingiza. Mfano wa ndani ya kumbukumbu unakuwezesha kupima mchakato mzima bila utegemezi wa nje. In-Memory RAG Testing -*Mkondo wa upimaji wa RAG ndani ya kumbukumbu unaonyesha uchambuzi wa hati, uhifadhi wa embedding, na utafutaji wa ufanano bila hitaji la hifadhidata* +*Mtiririko wa upimaji wa RAG ndani ya kumbukumbu unaonyesha uchambuzi wa hati, uhifadhi wa kuingiza, na utafutaji wa fananisho bila hitaji la database* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -Kipimo hiki kutoka `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` huchagua hati ndani ya kumbukumbu na kuangalia ugawaji na usimamizi wa metadata. +Mtihani huu kutoka `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` huunda hati ndani ya kumbukumbu na kuthibitisha upangaji vipande na usimamizi wa metadata. -### Mfano 6: Upimaji wa Muunganiko wa MCP +### Mfano 6: Upimaji wa Muunganisho wa MCP -Moduli ya MCP hupima muunganiko wa Itifaki ya Muktadha wa Mfano kwa kutumia usafirishaji wa stdio. Vipimo hivi vinaonyesha programu yako inaweza kuzalisha na kuwasiliana na seva za MCP kama michakato ndogo. +Moduli ya MCP hupima muunganisho wa Protokoli ya Muktadha wa Mfano kwa kutumia usafirishaji wa stdio. Mitihani hii inathibitisha kuwa programu yako inaweza kuzindua na kuwasiliana na seva za MCP kama michakato ndogo. -Vipimo katika `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` vinathibitisha tabia ya mteja MCP. +Mitihani katika `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` inathibitisha tabia ya mteja wa MCP. -**Vikimbie:** +**Izikimbie:** **Bash:** ```bash @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Falsafa ya Kupima -Pima nambari yako, si AI. Vipimo vyako vinapaswa kuthibitisha nambari unayoandika kwa kusohoza jinsi maagizo yanavyotengenezwa, jinsi kumbukumbu inavyosimamiwa, na jinsi zana zinavyotekelezwa. Majibu ya AI hubadilika na hayapaswi kuwa sehemu ya uthibitisho wa kipimo. Jiulize kama mfano wako wa agizo unabadilisha mabadiliko ipasavyo, si kama AI inatoa jibu sahihi. +Pingua msimbo wako, siyo AI. Mitihani yako inapaswa kuthibitisha msimbo unaouandika kwa kuangalia jinsi maagizo yanavyojengwa, jinsi kumbukumbu inavyosimamiwa, na jinsi zana zinavyoendeshwa. Majibu ya AI hubadilika na hayapaswi kuwa sehemu ya matokeo ya mtihani. Jiulize ikiwa kiolezo chako cha amri kinabadilisha vigezo vizuri, sio kama AI inatoa jibu sahihi. -Tumia kuiga kwa mifano ya lugha. Ni tegemezi za nje ambazo ni polepole, ghali, na hazitajirudi. Kuiga hufanya vipimo kuwa vya haraka kwa milisekunde badala ya sekunde, bure bila gharama za API, na zinatarajiwa na matokeo sawa kila mara. +Tumia kuiga kwa mifano ya lugha. Ni utegemezi wa nje ambao ni polepole, ghali, na hauna uhakika. Kuiga kunafanya mitihani kuwa ya haraka kwa milisekunde badala ya sekunde, bure bila gharama za API, na thabiti na matokeo sawa kila wakati. -Hakikisha vipimo vina uhuru. Kila kipimo kinapaswa kujiandaa data zake, kisitegemee vipimo vingine, na kujisafisha baada ya kukimbia. Vipimo vinapaswa kupita bila kujali mpangilio wa utekelezaji. +Hakikisha mitihani iwe huru. Kila mtihani unapaswa kuanzisha data yake, usitegemee mitihani mingine, na kusafisha baada ya mtihani. Mitihani inapaswa kupita bila kujali mpangilio wa utekelezaji. -Pima matukio ya pekee zaidi ya njia ya furaha. Jaribu pembejeo tupu, pembejeo kubwa sana, herufi maalum, vigezo batili, na masharti ya mipaka. Haya mara nyingi huonyesha kasoro ambazo matumizi ya kawaida hayaziwezi kuzijua. +Pingua kesi za kando zaidi ya njia ya kawaida. Jaribu maingizo tupu, maingizo makubwa sana, herufi maalum, parameta batili, na hali za mipaka. Hizi mara nyingi huibua hitilafu ambazo matumizi ya kawaida hayazionyeshi. -Tumia majina ya kueleza. Linganisha `shouldMaintainConversationHistoryAcrossMultipleMessages()` na `test1()`. Kwanza linaelezea hasa kinachopimwa, na kufanya utambuzi wa kasoro kuwa rahisi sana. +Tumia majina yaliyoeleweka. Linganisha `shouldMaintainConversationHistoryAcrossMultipleMessages()` na `test1()`. Kwanza linaeleza hasa kinachopimwa, na hivyo kurahisisha utambuzi wa makosa. -## Hatua Zinazofuata +## Hatua Zifuatazo -Sasa unapoelewa mifano ya vipimo, chunguza zaidi moduli kila moja: +Sasa ukiwa umeelewa mifumo ya kupima, ingia kwa undani ndani ya kila moduli: -- **[00 - Kuanza Haraka](../00-quick-start/README.md)** - Anza na msingi wa mifano ya maagizo - **[01 - Utangulizi](../01-introduction/README.md)** - Jifunze usimamizi wa kumbukumbu ya mazungumzo -- **[02 - Uhandisi wa Maagizo](../02/prompt-engineering/README.md)** - Jifundie mifumo ya kukuza GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Tengeneza mifumo ya kizazi iliyoboreshwa kwa urejeshaji -- **[04 - Zana](../04-tools/README.md)** - Tekeleza kuitisha kazi na mlolongo wa zana -- **[05 - MCP](../05-mcp/README.md)** - Unganisha Itifaki ya Muktadha wa Mfano +- **[02 - Uhandisi wa Amri](../02/prompt-engineering/README.md)** - Jifunze mifumo ya GPT-5.2 ya kutoa amri +- **[03 - RAG](../03-rag/README.md)** - Jenga mifumo ya kizalishaji iliyoongezwa upatikanaji +- **[04 - Zana](../04-tools/README.md)** - Tekeleza kupiga simu za kazi na mlolongo wa zana +- **[05 - MCP](../05-mcp/README.md)** - Unganisha Protokoli ya Muktadha wa Mfano -Kila README ya moduli hutoa maelezo ya kina ya dhana zinazopimwa hapa. +Kila README ya moduli ina maelezo ya kina kuhusu dhana zinazopimwa hapa. --- -**Mwelekeo:** [← Rudi Kwenye Kuu](../README.md) +**Uelekezaji:** [← Rudi Kwenye Kuu](../README.md) --- -**Kiarifi**: -Nyaraka hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri za moja kwa moja zinaweza kuwa na makosa au kutokukamilika. Nyaraka ya asili katika lugha yake ya asili inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na mtu inashauriwa. Hatutojibu kwa kutoelewana au tafsiri zisizo sahihi zinazotokana na matumizi ya tafsiri hii. +**Kionyozo**: +Hati hii imetafsiriwa kwa kutumia huduma ya tafsiri ya AI [Co-op Translator](https://github.com/Azure/co-op-translator). Ingawa tunajitahidi kupata usahihi, tafadhali fahamu kwamba tafsiri za kiotomatiki zinaweza kuwa na makosa au upungufu wa usahihi. Hati ya asili katika lugha yake halisi inapaswa kuchukuliwa kama chanzo cha mamlaka. Kwa taarifa muhimu, tafsiri ya kitaalamu inayofanywa na binadamu inapendekezwa. Hatutojibu kwa kuelewa vibaya au tafsiri potofu zinazotokea kutokana na matumizi ya tafsiri hii. \ No newline at end of file diff --git a/translations/ta/.co-op-translator.json b/translations/ta/.co-op-translator.json index d576363cc..e8f00f026 100644 --- a/translations/ta/.co-op-translator.json +++ b/translations/ta/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ta" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T21:56:26+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T09:09:12+00:00", "source_file": "01-introduction/README.md", "language_code": "ta" }, @@ -18,20 +18,20 @@ "language_code": "ta" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T21:59:16+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T09:04:09+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ta" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T22:01:07+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T09:08:18+00:00", "source_file": "03-rag/README.md", "language_code": "ta" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:23:45+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T09:06:52+00:00", "source_file": "04-tools/README.md", "language_code": "ta" }, @@ -54,8 +54,8 @@ "language_code": "ta" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:58:52+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T09:02:35+00:00", "source_file": "README.md", "language_code": "ta" }, @@ -72,14 +72,14 @@ "language_code": "ta" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T22:05:23+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T09:04:39+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ta" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T22:06:13+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T09:05:25+00:00", "source_file": "docs/TESTING.md", "language_code": "ta" } diff --git a/translations/ta/00-quick-start/README.md b/translations/ta/00-quick-start/README.md deleted file mode 100644 index 61e97d2c3..000000000 --- a/translations/ta/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: விரைவு துவக்கம் - -## உள்ளடக்க பட்டியல் - -- [அறிமுகம்](../../../00-quick-start) -- [LangChain4j என்றால் என்ன?](../../../00-quick-start) -- [LangChain4j சார்புகள்](../../../00-quick-start) -- [முன் தேவைகள்](../../../00-quick-start) -- [அமைப்பு](../../../00-quick-start) - - [1. உங்கள் GitHub டோக்கனைப் பெறவும்](../../../00-quick-start) - - [2. உங்கள் டோக்கனை அமைக்கவும்](../../../00-quick-start) -- [உதாரணங்களை இயக்கவும்](../../../00-quick-start) - - [1. அடிப்படைக் காட்சி](../../../00-quick-start) - - [2. கூற்றுப் பாடமுறைமை](../../../00-quick-start) - - [3. செயல்பாடு அழைப்பு](../../../00-quick-start) - - [4. ஆவண கேள்வி & பதில் (எளிய RAG)](../../../00-quick-start) - - [5. பொறுப்பான AI](../../../00-quick-start) -- [ஒவ்வொரு உதாரணமும் என்ன காட்டுுகிறது](../../../00-quick-start) -- [அடுத்த படிகள்](../../../00-quick-start) -- [பிரச்சனை தீர்க்கும் வழிகள்](../../../00-quick-start) - -## அறிமுகம் - -இந்த விரைவு துவக்கம் LangChain4j உடன் உங்களை விரைவாகத் தொடங்க உதவுகிறது. இது LangChain4j மற்றும் GitHub மாதிரிகளோடு AI பயன்பாடுகளை கட்டுமானம் செய்வதற்கான அடிப்படைகளை உள்ளடக்கியது. அடுத்த மூடியத்தில் நீங்கள் Azure OpenAI மற்றும் GPT-5.2 க்கு மாறி ஒவ்வொரு கருத்தையும் ஆழமாக ஆராய்வீர்கள். - -## LangChain4j என்றால் என்ன? - -LangChain4j என்பது AI-ஆல் இயக்கப்படும் பயன்பாடுகளை எளிதாக கட்டமைக்க உதவும் Java நூலகம். HTTP கிளையன்ட்கள் மற்றும் JSON பார்சிங் கையாள்வதைவிட நீங்கள் சுத்தமான Java APIs உடன் பணியாற்றலாம். - -LangChainஇல் "chain" என்பது பல கூறுகளை சங்கிலிப்படி இணைப்பதை குறிக்கிறது - உங்களால் ஒரு ப்ராம்ப்டை மாதிரி ஒன்றோடு, ஒரு பார்சருடன் இணைக்கலாம் அல்லது பல AI அழைப்புகளை சங்கிலி செய்யலாம், இதில் ஒரு வெளியீடு அடுத்த உள்ளீட்டுக்கு வழங்கப்படுகிறது. இந்த விரைவு துவக்கம் அடிப்படைகளைக் கவனமாக விளக்குகிறது பின்னர் சிக்கலான சங்கிலிகளை ஆராயவும். - -LangChain4j சங்கிலி கருத்து - -*LangChain4j இல் கூறுகளை சங்கிலி செய்கிறது - கட்டுமானத் தொகுதிகள் இணைந்து சக்திவாய்ந்த AI வேலைசெய்திகளை உருவாக்குகிறது* - -நாம் மூன்று முக்கிய கூறுகளைப் பயன்படுத்துவோம்: - -**ChatModel** - AI மாதிரி தொடர்புக்கான இடைமுகம். `model.chat("prompt")` ஐ அழைத்து பதிலாக ஒரு சரத்தைப் பெறலாம். நாம் `OpenAiOfficialChatModel` ஐப் பயன்படுத்துகிறோம், இது GitHub Models போன்ற OpenAI-ஐ ஒத்துள்ளது என்ற APIயுடன் இயங்குகிறது. - -**AiServices** - வகை-பாதுகாப்பான AI சேவை இடைமுகங்களை உருவாக்குகிறது. முறைகள் அமைக்கவும், அவற்றை `@Tool` ஆக்கமிடவும், LangChain4j ஒழுங்குபடுத்தலை கையாளும். AI தேவையான போது உங்கள் Java முறைகளை தானாக அழைக்கும். - -**MessageWindowChatMemory** - உரையாடல் வரலாறை பராமரிக்கிறது. இதை இல்லாமல் ஒவ்வொரு கோரிக்கையும் தனித்துவமானது. இதோடு, AI முந்திய செய்திகள் மற்றும் பல முறை உரையாடலில் உள்ளடக்கத்தை நினைவில் வைக்கிறது. - -LangChain4j கட்டமைப்பு - -*LangChain4j கட்டமைப்பு - முக்கிய கூறுகள் சேர்ந்து உங்கள் AI பயன்பாடுகளைக் இயக்குகின்றன* - -## LangChain4j சார்புகள் - -இந்த விரைவு துவக்கம் [`pom.xml`](../../../00-quick-start/pom.xml) இல் மூன்று Maven சார்புகளைப் பயன்படுத்துகிறது: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` தொகுதி OpenAiOfficialChatModel வகுப்பை வழங்குகிறது, இது OpenAI-ஐ ஒத்த APIகளுடன் இணைக்கிறது. GitHub Models இதே API வடிவமைப்பை பயன்படுத்துகிறது, எனவே வேறு ஒரு தனித்துவமான அணுகு கருவி தேவையில்லை - அடிப்படை URL ஐ `https://models.github.ai/inference` என்று காட்டவும். - -`langchain4j-easy-rag` தொகுதி தானாக ஆவணங்களை பிரிதல், செருகல் மற்றும் மீட்பு செய்வதற்கு உதவுகிறது, எனவே நீங்கள் ஒவ்வொரு படியான செயல்முறையையும் கைமுறை அமைக்காமல் RAG பயன்பாடுகளை கட்டமைக்க முடியும். - -## முன் தேவைகள் - -**Dev Container பயன்படுத்துகிறீர்களா?** Java மற்றும் Maven ஏற்கனவே நிறுவப்பட்டு உள்ளது. உங்களுக்கு GitHub Personal Access Token மட்டுமே தேவை. - -**உள்ளூர் மேம்பாடு:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (வழிமுறைகள் கீழே) - -> **குறிப்பு:** இந்த தொகுதி GitHub Models இல் உள்ள `gpt-4.1-nano`ஐப் பயன்படுத்துகிறது. கோடில் மாதிரி பெயரை மாற்ற வேண்டாம் - இது GitHub க்குப் பயன்படும் மாதிரிகளுடன் வேலை செய்ய அமைக்கப்பட்டுள்ளது. - -## அமைப்பு - -### 1. உங்கள் GitHub டோக்கனைப் பெறவும் - -1. [GitHub அமைப்புகள் → Personal Access Tokens](https://github.com/settings/personal-access-tokens) செல்லவும் -2. "Generate new token" என்பதைக் கிளிக் செய்க -3. விளக்கமான பெயரை அமைக்கவும் (எ.கா. "LangChain4j Demo") -4. காலாவதி (7 நாட்கள் பரிந்துரைக்கப்படுகிறது) -5. "Account permissions" கீழ் "Models" என்பதை "Read-only" ஆக்கு -6. "Generate token" கிளிக் செய்க -7. உங்கள் டோக்கனை நகலெடுக்கவும் மற்றும் சேமிக்கவும் - மீண்டும் பார்க்க முடியாது - -### 2. உங்கள் டோக்கனை அமைக்கவும் - -**விருப்பம் 1: VS Code பயன்படுத்துதல் (பரிந்துரைக்கப்படுகிறது)** - -VS Code பயன்படுத்துகிறீர்கள் என்றால், உங்கள் திட்ட அடிவெளியில் `.env` கோப்பில் உங்கள் டோக்கனைச் சேர்க்கவும்: - -`.env` கோப்பு இல்லை என்றால், `.env.example` ஐ `.env` ஆக நகலெடுக்கவும் அல்லது புதிய `.env` கோப்பை உருவாக்கவும். - -**எடுத்துக்காட்டு `.env` கோப்பு:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env இல் -GITHUB_TOKEN=your_token_here -``` - -பிறகு Explorer இல் எந்தவொரு டெமோ கோப்பையும் (எ.கா. `BasicChatDemo.java`) வலது கிளிக் செய்து **"Run Java"** ஐ தேர்வு செய்யலாம் அல்லது Run and Debug குழுமத்தில் இருந்து தொடக்க வடிவமைப்புகளைப் பயன்படுத்தலாம். - -**விருப்பம் 2: டெர்மினல் பயன்படுத்துதல்** - -டோக்கனை சுற்றுச்சூழல் மாறியாக அமைக்கவும்: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## உதாரணங்களை இயக்கவும் - -**VS Code பயன்படுத்துதல்:** Explorer இல் எந்தவொரு டெமோ கோப்பையும் வலது கிளிக் செய்து **"Run Java"** ஐ தேர்வு செய்யவும் அல்லது Run and Debug குழுமத்திலிருந்து தொடக்க வடிவமைப்புகளைப் பயன்படுத்தவும் (முதல் `.env` கோப்பில் டோக்கன் சேர்க்கப்பட்டுள்ளது என்பதை உறுதி செய்யவும்). - -**Maven பயன்படுத்துதல்:** மாற்றாக, நீங்கள் கட்டளை வரியில் இருந்து இயக்கலாம்: - -### 1. அடிப்படைக் காட்சி - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. கூற்றுப் பாடமுறைமை - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -சூன்ய ஷாட், சில ஷாட், சங்கிலி சிந்தனை மற்றும் பாத்திர அடிப்படையிலான ப்ராம்ப்டிங் காட்டு. - -### 3. செயல்பாடு அழைப்பு - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI தேவையான போது உங்கள் Java முறைகளை தானாக அழைக்கும். - -### 4. ஆவண கேள்வி & பதில் (எளிய RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -தானாக செருகலும் மீட்பும் உடன் எளிய RAG பயன்படுத்தி உங்கள் ஆவணங்களைப் பற்றி கேள்விகள் கேளுங்கள். - -### 5. பொறுப்பான AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -AI பாதுகாப்பு வடிகட்டிகள் தீங்கான உள்ளடக்கத்தை எவ்வாறு தடுக்கும் என்பதைக் காண்பிக்கிறது. - -## ஒவ்வொரு உதாரணமும் என்ன காட்டுுகிறது - -**அடிப்படைக் காட்சி** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -LangChain4j இன் அடிப்படைகளை இதிலிருந்து தொடங்குங்கள். `OpenAiOfficialChatModel` உருவாக்கி, `.chat()` உடன் கோரிக்கை அனுப்பி பதிலைக் பெறுவீர்கள். இது அழகான ஆதாரம்: தனித்துவமான அலுவலகங்கள் மற்றும் API விசைகளுடன் மாதிரிகளை எவ்வாறு ஆரம்பிப்பது என்பதை காட்டுகிறது. இந்த முறை தெரிந்த பிறகு மற்ற அனைத்தும் அதன் மேல் கட்டமைக்கப்படும். - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat உடன் முயற்சியுங்கள்:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) திறந்து கேளுங்கள்: -> - "GitHub மாதிரிகளிலிருந்து Azure OpenAIக்கு இந்தக் கோடில் எப்படிப் பிரவேசிப்பேன்?" -> - "OpenAiOfficialChatModel.builder() இல் இன்னும் என்ன அளவுரைகள் உள்ளன?" -> - "முழு பதிலை காத்திருக்காமல் ஸ்ட்ரீமிங் பதில்களைச் சேர்க்க எப்படி?" - -**ப்ராம்ப்ட் பொறியியல்** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -மாதிரிக்கோப்புடன் நீங்கள் பேசுவது எப்படி என்பதை இப்போது ஆராய்வோம். இந்த டெமோ அதே மாதிரி அமைப்பை பயன்படுத்துகிறது ஆனால் ஐந்து விதமான ப்ராம்ப்ட் நிலைப்பாடுகளை காட்டுகிறது. நேரடி அறிவுரைக்கு சூன்ய ஷாட் ப்ராம்ப்ட்களை முயற்சிக்கவும், எடுத்துக்காட்டுக்களிலிருந்து கற்றுக் கொள்ள சில ஷாட் ப்ராம்ப்ட்களைப் பார்க்கவும், காரணிகளை வெளிப்படுத்த சங்கிலி சிந்தனை ப்ராம்ப்ட்களைப்பார்க்கவும், மற்றும் சூழலை அமைக்கும் பாத்திர அடிப்படையிலான ப்ராம்ப்ட்களைப் பயன்படுத்தவும். அதே மாதிரி உங்கள் கோரிக்கையை எப்படி வடிவமைக்கிறீர்கள் என்பதைக் கருத்தில் கொண்டு மிக வேறுபட்ட முடிவுகளைப் பெறுவீர்கள். - -டெமோ ப்ராம்ப்ட் வார்ப்புருக்களையும் காட்டுகிறது, இது மாறிலிகளுடன் மறுபயன்படக் கூடிய ப்ராம்ப்ட்களை உருவாக்கும் சக்திவாய்ந்த வழி ஆகும். -கீழே உள்ள எடுத்துக்காட்டு LangChain4j `PromptTemplate` பயன்படுத்தி மாறிலிகளை நிரப்ப ஒரு ப்ராம்ப்டை காட்டுகிறது. AI கொடுக்கப்பட்ட இடமும் செயல்பாட்டையும் அடிப்படையாகக் கொண்டு பதிலளிக்கும். - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat உடன் முயற்சியுங்கள்:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) திறந்து கேளுங்கள்: -> - "சூன்ய ஷாட் மற்றும் சில ஷாட் ப்ராம்ப்டிங்கில் என்ன வேறுபாடு, எப்போது எது பயன்படுத்தப்படும்?" -> - "தபால்தாபம் அளவுரை மாதிரியின் பதில்களை எவ்வாறு பாதிக்கிறது?" -> - "உற்பத்தியில் ப்ராம்ப்ட் இன்ஜெக்ஷன் தாக்குதல்களைத் தடுப்பதற்கான சில நுட்பங்கள் என்ன?" -> - "பொதுவான வடிவங்களுக்கான மறுபயன்படக்கூடிய ப்ராம்ப்ட் வார்ப்புருக்களை எப்படி உருவாக்குவது?" - -**கருவி ஒருங்கிணைப்பு** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -இங்கே LangChain4j மிகவும் சக்திவாய்ந்ததாக உள்ளது. `AiServices` ஐப் பயன்படுத்தி உங்கள் Java முறைகளை அழைக்கும் AI உதவியாளரை உருவாக்குவீர்கள். முறைகளை `@Tool("விளக்கம்")` என குறிக்கவும், LangChain4j மற்ற அனைத்தையும் கையாளும் - பயனர் கேட்டதை அடிப்படையாகக் கொண்டு AI எந்த கருவியை எப்போது பயன்படுத்துவது என்று தானாக முடிவெடுக்கிறது. இது செயல்பாடு அழைப்பை விளக்குகிறது, கேள்விகளுக்கு பதிலளிப்பதற்கு மட்டுமல்லாமல் நடவடிக்கைகளை எடுக்கக்கூடிய AI கட்டமைப்பின் முக்கிய முறையாகும். - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat உடன் முயற்சியுங்கள்:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) திறந்து கேளுங்கள்: -> - "@Tool குறிப்பு எவ்வாறு செயல்படுகிறது மற்றும் LangChain4j அதை பின்னணியில் எவ்வாறு கையாள்கிறது?" -> - "AI பல கருவிகளை தொடர் முறையாக அழைத்து கடுமையான பிரச்சனைகளை தீர்க்க முடியுமா?" -> - "ஒரு கருவி தவறாக செயல் புரிந்தால் என்ன நடக்கிறது - பிழைகளை எப்படி கையாள வேண்டும்?" -> - "இந்த கணக்கீட்டுப் பொருள் எடுத்துக்காட்டின் பதிலுக்கு உண்மையான API-ஐ எப்படி ஒருங்கிணைப்பேன்?" - -**ஆவண கேள்வி & பதில் (எளிய RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -இங்கே நீங்கள் LangChain4j இன் "எளிய RAG" முறையைப் பயன்படுத்தி RAG (மீட்டல்-தீர்க்கப்பட்ட உருவாக்கம்)ஐ காண்பீர்கள். ஆவணங்கள் ஏற்றப்பட்டு தானாகவே பிரிக்கப்பட்டு உள்ள மனசை நினைவகத்தில் செருகப்படும், பின்னர் உள்ளடக்க மீட்டல் AIக்கு தொடர்புடைய துண்டுகளை அளிக்கும். AI பொது அறிவின் பதிலாக உங்கள் ஆவணங்களின் அடிப்படையில் பதிலளிக்கிறது. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat உடன் முயற்சியுங்கள்:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) திறந்து கேளுங்கள்: -> - "RAG AI கண்னிக்கை தவறுகளை மாதிரியின் பயிற்சி தரவுகளையும் ஒப்பிடுகையில் எப்படி தடுக்கும்?" -> - "இந்த எளிய முறையும் தனிப்பயன் RAG குழாயும் என்ன வேறுபாடு?" -> - "பல ஆவணங்கள் அல்லது பெரிய அறிவு தளங்களைக் கையாள இதை எப்படி அளவிடுவேன்?" - -**பொறுப்பான AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -ஆழமான பாதுகாப்புடன் AI பாதுகாப்பை கட்டியெழுப்புங்கள். இந்த டெமோ இரண்டு பாதுகாப்பு அடுக்குகளை ஒன்றாகச் செயல்படுத்துகிறது: - -**பகுதி 1: LangChain4j உள்ளீட்டு பாதுகாப்பு** - LLM-க்கு அனுப்புவதற்கு முன் தீங்கான ப்ராம்ப்ட்களைத் தடுக்கிறது. தடைசெய்யப்பட்ட முக்கிய வார்த்தைகள் அல்லது முறைகளைப் பரிசோதிக்கும் தனிப்பயன் பாதுகாப்பு தடைகளைக் கட்டமைக்கவும். இவை உங்கள் கோடில் இயங்கும் என்பதால் வேகமாகவும் இலவசமுமാണ്. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**பகுதி 2: வழங்குநர் பாதுகாப்பு வடிகட்டிகள்** - GitHub Models உள்நுழைவிற்கான வடிகட்டிகளை கொண்டுள்ளது, உங்கள் பாதுகாப்பு தடைகள் கவரவில்லை என்ற சாத்தியமானவற்றை பிடிக்கிறது. கடுமையான மீறல்களுக்கு (HTTP 400 பிழைகள்) கடுமையான தடைகள் மற்றும் AI மரியாதையாக மறுத்து விட்ட இடங்களுக்கு மென்மையான மறுக்கல்களைக் காண்பீர்கள். - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat உடன் முயற்சியுங்கள்:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) திறந்து கேளுங்கள்: -> - "InputGuardrail என்றால் என்ன மற்றும் என் சொந்ததை எப்படி உருவாக்குவது?" -> - "கடுமையான தடையுடன் மென்மையான மறுக்கும் இடையிலான வேறுபாடு என்ன?" -> - "எதற்கு இரண்டையும் கூட பாதுகாப்பு தடைகள் மற்றும் வழங்குநர் வடிகட்டிகளை பயன்படுத்த வேண்டும்?" - -## அடுத்த படிகள் - -**அடுத்த தொகுதி:** [01-introduction - LangChain4j உடன் துவக்கம்](../01-introduction/README.md) - ---- - -**வழிசெலுத்தல்:** [← முதன்மைக்குத் திரும்புக](../README.md) | [அடுத்தது: Module 01 - அறிமுகம் →](../01-introduction/README.md) - ---- - -## பிரச்சனை தீர்க்கும் வழிகள் - -### முதன்முறை Maven கட்டிடம் - -**பிரச்சனை:** முதலில் `mvn clean compile` அல்லது `mvn package` கட்டளை 10-15 நிமிடங்கள் ஆகும் - -**காரணம்:** Maven அனைத்து திட்ட சார்புகளையும் (Spring Boot, LangChain4j நூலகங்கள், Azure SDKகள் மற்றும் பிற) முதன்முறை கட்டலில் பதிவிறக்கம் செய்ய வேண்டும். - -**தீர்வு:** இது சாதாரண நடத்தை. பின்வரும் கட்டிடங்கள் வேகமாக இருக்கும், ஏனெனில் சார்புகள் உள்ளகமாக சேமிக்கப்படுகின்றன. பதிவிறக்க நேரம் உங்கள் நெட்வொர்க் வேகத்தை சார்ந்தது. - -### PowerShell Maven கட்டளை வடிவம் - -**பிரச்சனை:** Maven கட்டளைகள் `Unknown lifecycle phase ".mainClass=..."` பிழையுடன் தோல்வி அடைகின்றன -**காரணம்**: PowerShell `=` ஐ மாறிலி ஒதுக்கல் இயக்கியாகப் பொருள் படுத்துகிறது, இது Maven சொத்துக் கோட்பாட்டை உடைக்கிறது - -**தீர்வு**: Maven கட்டளைக்கு முன் நிறுத்த-பர்சிங் இயக்கி `--%` ஐ பயன்படுத்தவும்: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` இயக்கி PowerShell மற்ற அனைத்து வாதங்களையும் வார்த்தைபடுத்தாமலேயே Maven க்கு நேரடியாக அனுப்பும்படி சொல்கிறது. - -### Windows PowerShell எமோஜி காட்சி - -**பிரச்சனை**: PowerShell இல் எமோஜிகளுக்கு பதிலாக குப்பை எழுத்துக்கள் ரெண்டர் ஆகின்றன (எ.கா., `????` அல்லது `â??`) - -**காரணம்**: PowerShell இன் இயல்புநிலை குறியீட்டாக்கம் UTF-8 எமோஜிகளை ஆதரிக்காது - -**தீர்வு**: Java செயலிகளை இயக்கும்முன் இந்த கட்டளையை செயல்படுத்தவும்: -```cmd -chcp 65001 -``` - -இது டெர்மினலில் UTF-8 குறியீட்டாக்கத்தைக் கட்டாயப்படுத்தும். மாற்றாக, சிறந்த யூனிகோட் ஆதரவுடன் Windows Terminal ஐப் பயன்படுத்தவும். - -### API அழைப்புகளை பிழைத்திருத்தல் - -**பிரச்சனை**: அடையாளத்தேர்வு பிழைகள், விகித வரம்புகள், அல்லது எதிர்பாராத பதில்கள் AI மாதிரியிலிருந்து - -**தீர்வு**: எடுத்துக்காட்டுகள் `.logRequests(true)` மற்றும் `.logResponses(true)` உள்ளன, அவை API அழைப்புக்களை கன்சோலில் காட்சி படுத்துகின்றன. இதனால் அடையாளத்தேர்வு பிழைகள், விகித வரம்புகள், அல்லது எதிர்பாராத பதில்களை தீர்க்க உதவும். உற்பத்தியில் இந்த கொடிகளை நீக்கி பதிவு சத்தங்களை குறைக்கவும். - ---- - - -**பிரதிபாதிப்பு**: -இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) ஆகியவற்றைப் பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. எங்கள் முயற்சியேயானாலும், தானியங்கி மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கலாம் என கவனித்துக் கொள்ளவும். இயல்புநிலை மொழியில் உள்ள அசல் ஆவணம் அதிகாரபூர்வ மூலமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழில்முறை மனித மொழிபெயர்ப்பு பரிந்துரைக்கப்படுகிறது. இந்த மொழிபெயர்ப்பின் பயன்பாட்டினால் ஏற்பட்ட எந்தவொரு தவறான புரிதலுக்கும் அல்லது தவறான விளக்கங்களுக்கும் எங்களை பொறுப்பேற்க தேவையில்லை. - \ No newline at end of file diff --git a/translations/ta/01-introduction/README.md b/translations/ta/01-introduction/README.md index 72c28ae83..a4791977c 100644 --- a/translations/ta/01-introduction/README.md +++ b/translations/ta/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j உடன் துவக்கப்படும் முறை +# Module 01: LangChain4j உடன் தொடக்கம் -## உள்ளடக்க பட்டியல் +## зміст -- [வீடியோ நடைமுறை](../../../01-introduction) -- [நீங்கள் கற்றுக்கொள்ளும் விஷயங்கள்](../../../01-introduction) -- [முன்நிலைகள்](../../../01-introduction) -- [முக்கியப் பிரச்சனையைப் புரிந்துகொள்ளுதல்](../../../01-introduction) -- [டோக்கன்களைப் புரிந்துகொள்ளுதல்](../../../01-introduction) -- [எப்படி நினைவு வேலை செய்கிறது](../../../01-introduction) -- [இது எப்படி LangChain4j ஐப் பயன்படுத்துகிறது](../../../01-introduction) -- [Azure OpenAI பணியமைப்பை நியமித்தல்](../../../01-introduction) -- [குறிப்பிட்ட அமைப்பில் செயலியை இயக்குதல்](../../../01-introduction) -- [செயலியைப் பயன்படுத்துதல்](../../../01-introduction) - - [நிலையற்றவை உரையாடல் (இடது பக்கம்)](../../../01-introduction) - - [நிலையுடைய உரையாடல் (உறுப்புரை பக்கம்)](../../../01-introduction) -- [இறுதி படிகள்](../../../01-introduction) +- [காணொளி நடைமுறை](#காணொளி-நடைமுறை) +- [நீங்கள் கற்கப்போகும் விஷயங்கள்](#நீங்கள்-கற்கப்போகும்-விஷயங்கள்) +- [முன்‌தோகுதிகள்](#முன்‌தோகுதிகள்) +- [மையப் பிரச்சினையை புரிந்துகொள்வது](#மையப்-பிரச்சினையைப்-புரிந்துகொள்வது) +- [டோக்கன்களை புரிந்துகொள்வது](#டோக்கன்களைப்-புரிந்துகொள்வது) +- [நினைவகம் எப்படி பணிபுரிகிறது](#நினைவகம்-எப்படி-பணிபுரிகிறது) +- [இது LangChain4j ஐ எவ்வாறு பயன்படுத்துகிறது](#இது-langchain4j-ஐ-எவ்வாறு-பயன்படுத்துகிறது) +- [Azure OpenAI கட்டமைப்பை பயன்படுத்தி வைக்கவும்](#azure-openai-கட்டமைப்பை-பயன்படுத்தி-வைக்கவும்) +- [பயன்பாட்டைப் புறவிடுவோம்](#பயன்பாட்டைப்-புறவிடு) +- [பயன்பாட்டைப் பயன்படுத்துவது](#பயன்பாட்டைப்-பயன்படுத்துதல்) + - [நிலையற்ற உரையாடல் (இடது பக்கம்)](#நிலையற்ற-உரையாடல்-இடது-பக்கம்) + - [நிலையான உரையாடல் (வலது பக்கம்)](#நிலையான-உரையாடல்-வலது-பக்கம்) +- [அடுத்த படிகள்](#அடுத்த-படிகள்) -## வீடியோ நடைமுறை +## காணொளி நடைமுறை -இந்த மாடியுடன் துவங்குவது எப்படி என்பதைக் காட்டும் நேரலை அமர்வைக் கண்டு பாருங்கள்: +இந்த முதலாண்டு கட்டத்தில் LangChain4j உடன் எப்படி தொடங்குவது என்று விளக்கும் நேரடி அமர்வை பாருங்கள்: -LangChain4j உடன் துவக்கப்படுதல் - நேரலை அமர்வு +LangChain4j உடன் தொடக்கம் - நேரடி அமர்வு -## நீங்கள் கற்றுக்கொள்ளும் விஷயங்கள் +## நீங்கள் கற்கப்போகும் விஷயங்கள் -விரைவான துவக்கத்தில், நீங்கள் GitHub மாதிரிகளைப் பயன்படுத்தி கேள்விகள் அனுப்ப, கருவிகளை அழைக்க, RAG குழாயை கட்டமைக்க, மற்றும் காட்சியங்களைச் சோதிக்க பயன்படுத்தினீர்கள். அந்த டெமோக்கள் என்ன செய்ய முடியும் என்பதை காட்டின; இப்போது நாம் Azure OpenAI மற்றும் GPT-5.2 க்கு மாறுகிறோம் மற்றும் துவக்க நிலை பயன்பாடுகளை உருவாக்கத் தொடங்குகிறோம். இந்த மாடியிலிருந்து கவனம் செருக்கும் பகுதி உரையாடல் AI ஆவதற்குள் உள்ள யோசனைகள், நிலையை நினைவில் வைப்பது மற்றும் அவற்றை பராமரிப்பது என்றும் உள்ளது - இந்த யோசனைகள் விரைவான துவக்க டெமோகளுக்கு பின்னால் இருந்தது ஆனால் விளக்கப்படவில்லை. +இது LangChain4j மற்றும் Azure OpenAI உடன் உங்கள் தொடக்கப் புள்ளி. நாம் அடிப்படைகளைத் தொடங்குகிறோம் மற்றும் உற்பத்தி பாணி பயன்பாடுகளை கட்டமைக்கத் தொடங்குகிறோம். இந்த தொகுதி உரையாடல் AI ஆகும், அது சூழ்நிலையை நினைவில் வைத்திருக்கும் மற்றும் நிலையை பராமரிக்கும் — இது எல்லா அடுத்த தொகுதிகளின் அடிப்படையான கருத்துகள். -இந்த வழிகாட்டியில் Azure OpenAI யின் GPT-5.2 ஐ நாம் பயன்படுத்தப்போகிறோம், ஏனெனில் அதற்கு மேம்பட்ட நிலைமையற்ற திறன்கள் உள்ளன, வேறு மாதிரிகள் காணும் நடத்தை இன்னும் தெளிவாகக் காட்டப்படுகின்றன. நீங்கள் நினைவைக் கூட்டும் போது, இந்த வேறுபாடு தெளிவாகக் காணப்படும். இது ஒவ்வொரு கூறும் உங்கள் பயன்பாட்டிற்கு என்ன அளிக்கிறது என்பதை எளிதாக புரிந்து கொள்வதற்கு உதவும். +இந்த வழிகாட்டியிலே முழுமையாக Azure OpenAI இன் GPT-5.2 ஐ பயன்படுத்துகிறோம், ஏனெனில் அதன் மேம்பட்ட ஆய்வுக்கூறுகள் விதிகள் நடத்தை தெளிவாக காட்டுகிறது. நீங்கள் நினைவகத்தை சேர்க்கும்போது, வேறுபாட்டை தெளிவாகப் பார்ப்பீர்கள். இது ஒவ்வொரு கூறும் உங்கள் பயன்பாட்டுக்கு என்ன சேர்க்கிறது என்பதை விளக்கமாக்கிறது. -நீங்கள் இரு விதமான உரையாடல்களை இடையில் காட்டும் ஒரு பயன்பாட்டை உருவாக்குவீர்கள்: +நீங்கள் இரண்டு விதமுள்ள பயன்பாடுகளையும் உருவாக்கப்போகிறீர்கள்: -**நிலையற்ற உரையாடல்** - ஒவ்வொரு கோரலும் தனித்தனியாக செயல்படும். முறைப்பாடு முன்பு அனுப்பிய தகவல்களை நினைவில் வைக்கும் திறன் இல்லை. இது விரைவான துவக்கத்தில் நீங்கள் பயன்படுத்திய மாதிரியாகும். +**நிலையற்ற உரையாடல்** - ஒவ்வொரு கோரலும் தனித்தனி. முன் செய்திகளுக்கு எதையும் நினைவில் வைக்காது. இது எளிய தொடக்கப் புள்ளி. -**நிலையுடைய உரையாடல்** - ஒவ்வொரு கோரலிலும் உரையாடல் வரலாறு சேர்க்கப்படும். முறைப்பாடு பல திருப்புகளுக்கு இடையே சூழலை பராமரிக்கும். இது தயாரிப்பு பயன்பாடுகளில் தேவையானது. +**நிலையான உரையாடல்** - ஒவ்வொரு கோரலிலும் உரையாடல் வரலாற்று சேர்க்கப்பட்டிருக்கும். பல தடவைகள் தொடுக்கும்போது சூழ்நிலை பராமரிக்கப்படும். இது உற்பத்தி பயன்பாடுகளுக்கு தேவை. -## முன்நிலைகள் +## முன்‌தோகுதிகள் -- Azure OpenAI அணுகலுடன் Azure சந்தா -- ஜாவா 21, மேவன் 3.9+ +- Azure சந்தா மற்றும் Azure OpenAI அணுகல் +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **குறிப்பு:** ஜாவா, மேவன், Azure CLI மற்றும் Azure Developer CLI (azd) வழங்கப்பட்ட devcontainer இல் முன்பே நிறுவப்பட்டுள்ளன. +> **குறிப்பு:** Java, Maven, Azure CLI மற்றும் Azure Developer CLI (azd) வழங்கப்பட்ட devcontainer இல் முன்னதாக நிறுவப்பட்டுள்ளன. -> **குறிப்பு:** இந்த மாடியில GPT-5.2 ஐ Azure OpenAI இல் பயன்படுத்தப்படுகிறது. `azd up` மூலம் தானாகவே பணியமைப்பு செய்யப்பட்டிருக்கிறது - கோடில் மாதிரி பெயரை மாற்ற வேண்டாம். +> **குறிப்பு:** இந்த தொகுதி Azure OpenAI இல் GPT-5.2 ஐ பயன்படுத்துகிறது. azd up மூலம் தானாக கட்டமைக்கப்படுகிறது - குறியீட்டில் மாடல் பெயரை மாற்ற வேண்டாம். -## முக்கியப் பிரச்சனையைப் புரிந்துகொள்ளுதல் +## மையப் பிரச்சினையைப் புரிந்துகொள்வது -மொழி மாதிரிகள் நிலையற்றவையாகும். ஒவ்வொரு API அழைப்பும் தனிச்செயல்பாடாக இருக்கும். நீங்கள் "என் பெயர் ஜான்" என்று அனுப்பி அதன்பின் "என்னுடைய பெயர் என்ன?" என்று கேட்டால், முறைப்பாடு நீங்கள் இப்போதைக்கு தான் தன்னை அறிமுகப்படுத்தியதை அறியாது. இது ஒவ்வொரு கோரலையும் நீங்கள் செய்த முதல் உரையாடல் போலவே எடுத்துக்கொள்ளும். +மொழி மாதிரிகள் நிலையற்றவை. ஒவ்வொரு API அழைப்பும் தனி சுயமாக இருக்கும். "எனது பெயர் ஜான்" என கூறியபின் "என் பெயர் என்ன?" என கேட்டால், மாதிரி இப்பொழுது நீங்கள் அறிமுகம் செய்ததை அறியாது. அனைத்து கோரல்களையும் முதலாவது உரையாடலாகவே கருதுகிறது. -இதுவும் எளிய கேள்வி-பதில் பயன்பாடுகளுக்கு சரியாக இருக்கலாம், ஆனாலும் உண்மையான பயன்பாடுகளுக்கு இது பயனற்றது. வாடிக்கையாளர் சேவை பொத்தான்கள் நீங்கள் சொன்னதை நினைவில் வைத்திருக்க வேண்டும். தனிப்பட்ட உதவியாளர்கள் சூழலைக் கவனிக்க வேண்டும். எந்தபலதிருப்புகளான உரையாடலில் நினைவு உடன் சேர்க்கப்பட வேண்டும். +இது எளிய கேள்வி மற்றும் பதிற்ணை நன்றாக செல்லும், ஆனால் உண்மையான பயன்பாடுகளுக்கு பயனற்றது. வாடிக்கையாளர் சேவை bot கள் நீங்கள் சொன்னதை நினைவில் வைத்திருக்க வேண்டும். தனிப்பட்ட உதவியாளர்கள் சூழ்நிலையை தேவைபடுகின்றனர். பல தடவை நடந்த உரையாடல் நினைவகம் தேவை. -கீழே உள்ள வரைபடம் இரண்டு அணுகுமுறைகளுக்கான வித்தியாசத்தை காட்டுகிறது — இடது பக்கத்தில், உங்கள் பெயரை மறந்துவிடும் நிலையற்ற அழைப்பு; வலது பக்கத்தில், ChatMemory மூலம் ஆதரிக்கப்பட்ட நிலையுடைய அழைப்பு. +டயாகிராமில் இடதுபுறம் name மறந்த நிலையற்ற அழைப்பு மற்றும் வலதுபுறம் ChatMemory நோக்கிப்பார்க்கும் நிலையான அழைப்பு காட்டப்பட்டுள்ளது. -நிலையற்ற மற்றும் நிலையுடைய உரையாடல்கள் +நிலையற்ற மற்றும் நிலையான உரையாடல்கள் -*நிலையற்ற (தனிக்கலனான அழைப்புகள்) மற்றும் நிலையுடைய (சூழலும் அறிய கூடிய) உரையாடல்களுக்கு இடையேயான வித்தியாசம்* +*நிலையற்ற (தனித்தனி அழைப்புகள்) மற்றும் நிலையான (சூழ்நிலை அறிவு) உரையாடல்கள் இடையேயான வேறுபாடு* -## டோக்கன்களைப் புரிந்துகொள்ளுதல் +## டோக்கன்களைப் புரிந்துகொள்வது -உரையாடல்களுக்கு முன்னர், மொழி மாதிரிகள் செயற்படுத்தும் அடிப்படையான உரை அலகுகள் - டோக்கன்களை புரிந்துகொள்ளுவது முக்கியம்: +உரையாடல்களில் சென்று முன், டோக்கன்கள் - மொழி மாதிரிகள் செயலாக்கும் அடிப்படையான எழுத்துச் சுழற்சிகள் பற்றி அறிந்து கொள்வது முக்கியம். டோக்கன் விளக்கம் -*உரையை எப்படி டோக்கன்களில் மாற்றுகிறார்கள் என்பதை ஒரு எடுத்துக்காட்டு - "I love AI!" 4 தனிப்பட்ட செயலாக்க அலகுகளாக பிரிக்கப்பட்டுள்ளது* +*உரையை டோக்கன்களாக உடைக்கும் உதாரணம் - "I love AI!" என்பது 4 தனித்துதானிய செயலாக்க துகள்களாக மாறும்* -டோக்கன்கள் AI மாதிரிகள் உரையை அளவிடும் மற்றும் செயலாக்கும் முறையாகும். வார்த்தைகள், வாக்கியக்குறிகள் மற்றும் இடைவெளிகள் கூட டோக்கன்களாக இருக்கலாம். உங்கள் மாதிரியின் ஒருமுறை செயலாக்கக்கூடிய DTokன்கள் அளவு உள்ளது (GPT-5.2 க்கு 400,000 டோக்கன்கள், இதில் 272,000 உள்ளீட்டு மற்றும் 128,000 வெளியீட்டு). டோக்கன்களைப் புரிதல் உரையாடல் நீளம் மற்றும் செலவுகளை நிர்வகிக்க உதவும். +டோக்கன்கள் AI மாதிரிகள் உரையை அளக்கும் மற்றும் செயலாக்கும் வழி. வார்த்தைகள், எழுத்துடைச்சல் மற்றும் இடைவெளிகளும் டோக்கன்கள் ஆகும். உங்கள் மாதிரிக்கு ஒரே நேரத்தில் செயலாக்கக்கூடிய டோக்கன்களின் வரம்பு உண்டு (GPT-5.2 க்கு 400,000, 272,000 உள்ளீடு மற்றும் 128,000 வெளியீடு). டோக்கன்களை புரிந்து கொள்ளுதல் உரையாடல் நீளம் மற்றும் செலவுகளை கவனிக்க உதவும். -## எப்படி நினைவு வேலை செய்கிறது +## நினைவகம் எப்படி பணிபுரிகிறது -Chat memory நிலையற்ற பிரச்சனையை உரையாடல் வரலாற்றை பராமரிப்பதன் மூலம் தீர்க்கிறது. உங்கள் கோரலை மாதிரிக்கு அனுப்புவதற்கு முன், கட்டமைப்பு தொடர்புடைய பிற செய்திகளை முன்னோக்கி ஒட்டுகிறது. நீங்கள் "என்னுடைய பெயர் என்ன?" என்று கேட்டால், முறைப்பாடு உண்மையில் முழு உரையாடல் வரலாற்றையும் அனுப்புகிறது, அதனால் "என் பெயர் ஜான்" என்று நீங்கள் முன்பு கூறியதை மாதிரிக்கு பார்க்கலாம். +Chat memory நிலையற்ற பிரச்சனையை உரையாடல் வரலாற்றை பராமரிப்பது மூலம் தீர்க்கிறது. மாதிரிக்கு கோரல் அனுப்புவதற்கு முன்னர், கட்டமைப்பு தொடர்புடைய முன் செய்திகளை இணைக்கும். நீங்கள் "என் பெயர் என்ன?" என்றால், அமைப்பு முழு உரையாடல் வரலாற்றையும் அனுப்புகிறது என்பதால் மாதிரி "என் பெயர் ஜான்" என்று நீங்கள் முன்பு சொன்னதை பார்க்க முடியும். -LangChain4j நினைவுப் பயன்பாடுகளை தானாக பராமரிக்கிறது. நீங்கள் எத்தனை செய்திகளை நிலைநாட்ட வேண்டும் என்பதைக் தேர்வு செய்வீர்கள், கட்டமைப்பு சூழல் சாளரத்தை நிர்வகிக்கிறது. கீழே உள்ள வரைபடம் MessageWindowChatMemory புதிய செய்திகளை ஸ்லைடிங் சாளரத்துக்கு ஒதுக்கி பேணுவது காட்டுகிறது. +LangChain4j நினைவகம் செயல்திறன்களை தானாக கையாள்கிறார். நீங்கள் எத்தனை செய்திகள் வைத்திருக்க வேண்டும் என்பதைக் தெரிவுசெய்கிறீர்கள்; கட்டமைப்பு சூழ்நிலை சாளரத்தை பராமரிக்கும். கீழ்காணும் படத்தில் MessageWindowChatMemory சமீபத்திய செய்திகளின் ஒரு ஸ்லைடிங் சாளரத்தை பராமரிப்பதை காணலாம். -நினைவு சாளரக் கருத்து +நினைவகம் சாளரக் கருத்து -*MessageWindowChatMemory சமீபத்திய செய்திகள் கொண்ட ஸ்லைடிங் சாளரத்தை பராமரிக்கிறது, பழையவை தானாக நீக்கப்படுகின்றன* +*MessageWindowChatMemory சமீபத்திய செய்திகளின் ஸ்லைடிங் சாளரத்தை பராமரித்து பழையவைகளை தானாக விலக்கிறது* -## இது எப்படி LangChain4j ஐப் பயன்படுத்துகிறது +## இது LangChain4j ஐ எவ்வாறு பயன்படுத்துகிறது -இந்த மாடி விரைவான துவக்கத்துடன் Spring Boot ஐ ஒருங்கிணைத்து உரையாடல் நினைவையும் சேர்க்கிறது. கூறுகள் எப்படி இணைகின்றன என்பதைக் கீழே காணவும்: +இந்த தொகுதி Spring Boot ஐ இணைத்து உரையாடல் நினைவகத்தை சேர்க்கிறது. அங்கிருக்கும் கூறுகள் இங்கே இணைக்கப்படுகின்றன: -**பிணையங்கள்** - இரண்டு LangChain4j நூலகங்களை சேர்க்கவும்: +**இணைப்பு நூலகங்கள்** - இரண்டு LangChain4j நூலகங்களை சேர்க்கவும்: ```xml @@ -94,7 +94,7 @@ LangChain4j நினைவுப் பயன்பாடுகளை தான ``` -**உரையாடல் மாதிரி** - Azure OpenAI ஐ Spring bean ஆக நிர்வகிக்கவும் ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**உரையாடல் மாதிரி** - Azure OpenAI ஐ Spring பீனாக அமைக்கவும் ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -கட்டுமானக் காரியர் `azd up` மூலம் அமைக்கப்படும் சுற்றுப்புற வேறுபாடுகளிலிருந்து அங்கீகார தகவல்களைப் படிக்கிறது. `baseUrl` ஐ Azure இறுதிப் புள்ளிக்கு அமைத்தால் OpenAI கிளையெண்ட் Azure OpenAI உடன் இயங்கும். +பில்டர் `azd up` மூலம் அமைக்கப்படும் சுற்று மாறிகள் மூலம் அங்கீகாரங்களை வாசிக்கிறது. `baseUrl` ஐ உங்கள் Azure முடிச்சு URL ஆக அமைத்தால் OpenAI கிளையன்ட் Azure OpenAI உடன் வேலை செய்யும். -**உரையாடல் நினைவு** - MessageWindowChatMemory மூலம் உரையாடல் வரலாற்றைப் பதிவு செய்கிறது ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**உரையாடல் நினைவகம்** - MessageWindowChatMemory உடன் உரையாடல் வரலாற்றை பின்தொடர்க ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,21 +124,21 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` கொண்டு நினைவுபெட்டி கடைசித் 10 செய்திகள் மட்டுமே வைக்கும். பயனர் மற்றும் AI செய்திகள் `UserMessage.from(text)` மற்றும் `AiMessage.from(text)` வகைகளால் சேர்க்கப்படுகின்றன. வரலாறைப் `memory.messages()` மூலம் பெறலாம், அதை மாதிரிக்கு அனுப்பவும். இந்த சேவை உரையாடல் அடையாளத்திற்கு தனிப்பட்ட நினைவு ஒவ்வொன்றைக் காப்பாற்றுகிறது, இது பல பயனர்கள் ஒரே நேரத்தில் உரையாட அனுமதிக்கிறது. +`withMaxMessages(10)` உடனான நினைவகத்தை உருவாக்கி கடைசி 10 செய்திகளை வைத்திருக்கவும். Typed wrappers கொண்டு பயனர் மற்றும் AI செய்திகளைச் சேர்க்கவும்: `UserMessage.from(text)` மற்றும் `AiMessage.from(text)`. வரலாற்றை `memory.messages()` மூலம் கொண்டு வரவும் மற்றும் மாதிரிக்கு அனுப்பவும். சேவை ஒவ்வொரு உரையாடலுக்கும் தனித்த நினைவகம் உருவாக்கி பல பயனர்கள் ஒரே நேரத்தில் பேச அனுமதிக்கிறது. -> **🤖 [GitHub Copilot](https://github.com/features/copilot) உரையாடலை முயற்சிக்கவும்:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) திறந்து கேளுங்கள்: -> - "MessageWindowChatMemory சாளரம் முழுதானபோது எந்த செய்திகளை விட்டு விட முடியும் என்று எப்படி தீர்மானிக்கிறது?" -> - "நினைவுப் பகுதியை தரவுத்தளத்தில் சேமிப்பதற்கான விருப்ப முறையை உருவாக்க முடியுமா?" -> - "பழைய உரையாடல் வரலாற்றை சுருக்குவதற்கு முக்கியச் சுருக்கம் சேர்ப்பது எப்படி?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat கொண்டு முயற்சி செய்யவும்:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) திறந்து கேளுங்கள்: +> - "MessageWindowChatMemory சாளரம் நிரம்பும்போது எந்த செய்திகள் நீக்கப்படுமோ எப்படி தீர்மானிக்கிறது?" +> - "நினைவக சேமிப்பை மெமரியில் அல்லாமல் தரவுத்தளத்தில் தனிப்பயன் முறையில் அமைக்க முடியுமா?" +> - "பழைய உரையாடல் வரலாற்றை சுருக்குகிறது என்கிற சுருக்கத்தை எப்படி சேர்ப்பது?" -நிலையற்ற உரையாடல் இடைமுகம் நினைவைக் கையாளாது - வெறும் `chatModel.chat(prompt)` போல விரைவான துவக்கத்தில் இருந்தது. நிலையுடைய இடைமுகம் நினைவில் செய்திகள் சேர்க்கிறது, வரலாற்றைப் பெறுகிறது, மற்றும் ஒவ்வொரு கோரலிலும் அதைச் சேர்க்கிறது. மாதிரி ஒன்றே, விதியற்ற முறைகள் வேறுபட்டவை. +நிலையற்ற உரையாடல் முடிவில் நினைவகம் இல்லாமல் - சுருக்கமாக `chatModel.chat(prompt)` போல் செயல்படும். நிலையான முடிவில் நினைவகத்தில் செய்திகளைச் சேர்த்து வரலாற்றைப் பெற்று, அது ஒவ்வொரு கோரலுடனும் சேர்க்கிறது. மாதிரி அமைப்பு ஒன்றே, வழிமுறைகள் வேறுபாடு. -## Azure OpenAI பணியமைப்பை நியமித்தல் +## Azure OpenAI கட்டமைப்பை பயன்படுத்தி வைக்கவும் **Bash:** ```bash cd 01-introduction -azd up # சந்தா மற்றும் இடத்தை தேர்வு செய்க (eastus2 பரிந்துரைக்கப்பட்டது) +azd up # சந்தா மற்றும் இடத்தை தேர்ந்தெடுக்கவும் (கிழக்குus2 பரிந்துரைக்கப்படுகிறது) ``` **PowerShell:** @@ -147,28 +147,28 @@ cd 01-introduction azd up # சந்தா மற்றும் இடத்தை தேர்ந்தெடுக்கவும் (eastus2 பரிந்துரைக்கப்படுகிறது) ``` -> **குறிப்பு:** நீங்கள் நேரம் முடிந்த பிழை(`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) சந்தித்தால், `azd up` ஐ மீண்டும் ஓட்டுங்கள். Azure வளங்கள் பின்தங்கியிருந்தாலும், மீண்டும் முயற்சிப்பது வளங்கள் இறுதி நிலைக்கு வந்ததும் பணியமைப்பை முடிக்க உதவும். +> **குறிப்பு:** Timeout பிழை பொருந்தினால் (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), வெறும் `azd up` கட்டளை மீண்டும் தொடங்கவும். Azure வளங்கள் பின்னணி பணிகளில் இருக்கும், மீண்டும் முயற்சிப்பதால் வளங்கள் இறுதி நிலைக்கு வந்தவுடன் நிறுவல் முடியும். -இது: -1. GPT-5.2 மற்றும் text-embedding-3-small மாதிரிகளுடன் Azure OpenAI வளத்தை உருவாக்கும் -2. அங்கீகாரங்களை கொண்ட `.env` கோப்பை திட்ட அடிப்பகுதியில் தானாக உருவாக்கும் -3. தேவையான அனைத்து சுற்றுச்சூழல் மாறுகளையும் அமைக்கும் +இது செய்யும் வேலைகள்: +1. GPT-5.2 மற்றும் text-embedding-3-small மாதிரிகள் உடன் Azure OpenAI வளத்தை நிறுவுக +2. அங்கீகாரங்களுடன் `.env` கோப்பை திட்டத்தின் ரூட் என்னும் இடத்தில் தானாக உருவாக்குக +3. தேவையான அனைத்து சுற்று மாறிகள் சேர்க்கவும் -**பணியமைப்பில் சிக்கல்கள் உள்ளதா?** [Infrastructure README](infra/README.md) இல் உப டொமைன் பெயர் மோதல்கள், கையேடு Azure போர்டல் பணியமைப்பு படிகள் மற்றும் மாதிரி அமைவு வழிகாட்டி காணலாம். +**நிறுவல் சிக்கல்கள் உள்ளதா?** [கட்டமைப்பு README](infra/README.md) படி நிலைத்தளப்பிரச்சினைகள், கைமுறை Azure போர்டல் நிறுவல் படிகள் மற்றும் மாதிரி அமைப்புக்கான வழிகாட்டுதல்கள் பார்க்கவும். -**பணியமைப்பு வெற்றியடைந்ததா என சரிபார்க்க:** +**நிறுவல் வெற்றியா என்பதை சரிபார்க்கவும்:** **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY போன்றவற்றை காட்ட வேண்டும். +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY மற்றும் பிறவற்றை காட்ட வேண்டும். ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, மற்றும் பிறவை காட்ட வேண்டும். +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY போன்றவற்றை காண்பிக்க வேண்டும். ``` -> **குறிப்பு:** `azd up` கட்டளை `.env` கோப்பை தானாக உருவாக்கும். அதை பின்னர் புதுப்பிக்க வேண்டும் என்றால், அந்த `.env` கோப்பை நேரடியாக திருத்தலாம் அல்லது கீழ்காணும் கட்டளைகளை இயக்கி மறுபடியும் உருவாக்கலாம்: +> **குறிப்பு:** `azd up` கட்டளை தானாக `.env` கோப்பை உருவாக்கும். தேவைப்பட்டால், `.env` கோப்பை கைமுறையாக சீரமைக்கவும் அல்லது கீழ்காணும் கட்டளையால் மீண்டும் உருவாக்கவும்: > > **Bash:** > ```bash @@ -182,11 +182,11 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, மற்றும் ப > .\.azd-env.ps1 > ``` -## செயலியை உள்ளகமாக இயக்குதல் +## பயன்பாட்டைப் புறவிடு -**பணியமைப்பு சரிபார்க்க:** +**நிறுவல் சரிபார்க்கவும்:** -Azure அங்கீகாரங்களுடன் `.env` கோப்பு அடிப்பகுதியில் இருப்பதை உறுதிசெய்க. இதில் இருந்து (`01-introduction/`) கீழ்க்காணும் கட்டளையை இயக்கவும்: +ஆறு கணினியில் Azure அனுமதிகளுடன் `.env` கோப்பு உள்ளது என்பதை உறுதிசெய்யவும். தொகுதி அடங்கிய கோப்புறையிலிருந்து (`01-introduction/`) கீழ்காணும் கட்டளைகளை இயக்கவும்: **Bash:** ```bash @@ -195,44 +195,44 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்ட வே **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ஐ காட்ட வேண்டும் +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்டப்பட வேண்டும் ``` -**பயன்பாடுகளைத் தொடங்கவும்:** +**பயன்பாடுகளை ஆரம்பிக்கவும்:** -**முறை 1: Spring Boot டாஷ்போர்டைப் பயன்படுத்துதல் (VS Code பயனர்களுக்கான பரிந்துரை)** +**விருப்பம் 1: Spring Boot داش்போர்ட்டைப் பயன்படுத்துதல் (ஊக்குவிக்கப்பட்டது VS Code பயனர்களுக்கு)** -devcontainer-ல் Spring Boot டாஷ்போர்டு விரிவாக்கம் உள்ளடக்கப்பட்டுள்ளது, இது அனைத்து Spring Boot செயலிகளையும் கணினியில் மேலாண்மை செய்யும் ஒளிப்பட வேறுபாட்டை வழங்குகிறது. இது VS Code இன் இடது பக்க Activity பட்டியில் Spring Boot ஐகானை தேடவும். +Dev container இல் Spring Boot DASHBOARD விரிவாக்கம் உள்ளடக்கம். இது அனைத்து Spring Boot பயன்பாடுகளை பார்க்க ஒரு காட்சி இடைமுகத்தை வழங்குகிறது. VS Code இல் இடது Activity பட்டியில் Spring Boot ஐ காணவும். -Spring Boot டாஷ்போர்டில் நீங்கள் செய்யக்கூடியவை: -- பயன்பாட்டு இடத்தில் உள்ள எல்லா Spring Boot செயலிகளையும் காணலாம் -- ஒரு கிளிக்குடன் செயலிகளை தொடங்க/நிறுத்தலாம் -- செயலி பதிவு கோப்புகளை நேரடியாக பார்வையிடலாம் -- செயலி நிலையை கண்காணிக்கலாம் +Spring Boot DASHBOARD இலிருந்து நீங்கள்: +- பணிப்பலகையில் உள்ள அனைத்து Spring Boot பயன்பாடுகளையும் பார்க்கலாம் +- ஒரு கிளிக்குபடி தொடக்கம்/நிறுத்தலாம் +- பயன்பாட்டு பத்திரிகைகள் நேரடியாக பார்க்கலாம் +- பயன்பாட்டு நிலையை கண்காணிக்கலாம் -`introduction` அருகிலுள்ள பிளே பொத்தானை அழுத்தி இந்த மாடியை தொடங்கலாம் அல்லது அனைத்து மாடியையும் ஒரே முறையில் தொடங்கலாம். +"introduction" அருகே உள்ள ஓட்டுமுறை படான் கிளிக்கவும் இந்த தொகுதியை தொடங்க. அல்லது அனைத்துத் தொகுதிகளையும் ஒரே நேரத்தில் தொடங்கலாம். -Spring Boot டாஷ்போர்ட் +Spring Boot DASHBOARD -*VS Code இல் Spring Boot டாஷ்போர்ட் — எல்லா மாடிகளையும் ஒரே இடத்தில் தொடக்கம், நிறுத்தம் மற்றும் கண்காணிப்பு* +*VS Code இல் Spring Boot DASHBOARD — அனைத்து தொகுதிகளையும் ஒரே இடத்தில் தொடங்க, நிறுத்த மற்றும் கண்காணிக்க* -**முறை 2: ஷெல் ஸ்கிரிப்ட்கள் பயன்படுத்துதல்** +**விருப்பம் 2: Shell ஸ்கிரிப்ட்களைப் பயன்படுத்துதல்** -எல்லா வலை செயலிகளையும் (01-04 மாடிகள்) தொடங்க: +01-04 தொகுதிகளுக்கான அனைத்து வலை பயன்பாடுகளையும் தொடங்க: **Bash:** ```bash -cd .. # ரூட் கோப்புறை இருந்து +cd .. # ரூட் அடைவு கோப்புறை இருந்து ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # மூலம் ரூட் கோப்புறை +cd .. # மூல அடைவு இருந்து .\start-all.ps1 ``` -அல்லது இந்த மாடி மட்டும் தொடங்க: +அல்லது இந்த தொகுதியை மட்டும் தொடங்க: **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -இரு ஸ்கிரிப்ட்களும் தானாகவே அடிப்பகுதியில் உள்ள `.env` கோப்பில் சுற்றுச் சூழல் மாறிகளை ஏற்றும் மற்றும் JAR கோப்புகள் இல்லாவிட்டால் அவற்றை உருவாக்கும். +இரண்டு ஸ்கிரிப்ட்களும் ரூட் `.env` கோப்பிலிருந்து சுற்று மாறிகளை தானாக ஏற்றும் மற்றும் ஜார்களை உருவாக்குகையில் இவை இல்லையெனில் உருவாக்கும். -> **குறிப்பு:** நீங்கள் செயலி துவங்குவதற்கு முன் அனைத்து மாடிகளையும் கையால் கட்ட விரும்பினால்: +> **குறிப்பு:** நீங்கள் இவற்றைத் தொடங்குவதற்கு முன் அனைத்து தொகுதிகளையும் கைமுறையாக கட்டமைக்க விரும்பினால்: > > **Bash:** > ```bash @@ -262,61 +262,61 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -உங்கள் உலாவியில் http://localhost:8080 ஐ திறந்திடவும். +உங்கள் உலாவியில் http://localhost:8080 ஐ திறக்கவும். **நிறுத்த:** **Bash:** ```bash -./stop.sh # இந்த மாட்யுள் மட்டும் +./stop.sh # இந்த தொகுதி மட்டும் # அல்லது -cd .. && ./stop-all.sh # அனைத்து மாட்யூல்கள் +cd .. && ./stop-all.sh # அனைத்து தொகுதிகளும் ``` **PowerShell:** ```powershell -.\stop.ps1 # இந்த முறை மட்டும் +.\stop.ps1 # இந்த முறைப்பாடே மட்டும் # அல்லது -cd ..; .\stop-all.ps1 # அனைத்து முறைகளும் +cd ..; .\stop-all.ps1 # அனைத்து முறைப்பாடுகளும் ``` -## செயலியைப் பயன்படுத்துதல் +## பயன்பாட்டைப் பயன்படுத்துதல் -இந்த செயலி இரண்டு உரையாடல் அமுலங்களையும் பக்கமளவுடன் இணையவழி இடைமுகத்தை வழங்குகிறது. +இரு உரையாடல் செயல்பாடுகளை பக்கங்களில் வைத்து இணைய இடைமுகம் உள்ளது. -செயலி முகப்பு திரை +பயன்பாட்டு முகப்பு திரை -*இரு வழிகளும் உள்ள டாஷ்போர்ட்: எளிய உரையாடல் (நிலையற்ற) மற்றும் உரையாடல் உரையாடல் (நிலையுடைய) விருப்பங்கள்* +*Dashboard-ல் சுலபமான உரையாடல் (நிலையற்ற) மற்றும் உரையாடல் நிலையான (நிலையான) விருப்பங்கள் காணப்படும்* ### நிலையற்ற உரையாடல் (இடது பக்கம்) -முதலில் இதைப் பயிற்சி செய்யுங்கள். "என் பெயர் ஜான்" என்று கூறி உடனே "என்னுடைய பெயர் என்ன?" என்று கேளுங்கள். முறைப்பாடு நினைவில் வையாது, ஏனெனில் ஒவ்வொரு செய்தியும் தனி கோரல். இது அடிப்படை மொழி மாதிரி ஒருங்கிணைப்பில் உள்ள அடிப்படையான சிக்கலை காட்டுகிறது - உரையாடல் சூழல் கிடையாது. +முதல் முறையாக முயற்சிக்கவும். "என் பெயர் ஜான்" என்று சொல்வதாக, உடனடியாக "என் பெயர் என்ன?" என்று கேளுங்கள். மாதிரி நினைவில் வைக்காது, ஏனெனில் ஒவ்வொரு செய்தியும் தனித்தனியானவை. இது அடிப்படைக் மொழி மாதிரி ஒருங்கிணைப்புக்கு உள்ள பிரச்சினையை காட்டுகிறது - உரையாடல் சூழ்நிலையில்லை. நிலையற்ற உரையாடல் டெமோ -*AI முன்பு கூறிய உங்கள் பெயரை நினைவில் வைக்காது* +*AI கடந்த செய்தியில் உங்கள் பெயரை நினைவில் வைத்துக்கொள்ளாது* -### நிலையுடைய உரையாடல் (உறுப்புரை பக்கம்) +### நிலையான உரையாடல் (வலது பக்கம்) -இதுபோலவே கேள்வி தொடர் இங்கு முயற்சிக்கவும். "என் பெயர் ஜான்" என்று கூறி "என்னுடைய பெயர் என்ன?" கேட்டால், இப்போது அது நினைவில் வைக்கும். வித்தியாசம் MessageWindowChatMemory க்கு இடம். அது உரையாடல் வரலாற்றை பராமரித்து ஒவ்வொரு கோரலிலும் சேர்க்கிறது. இது தயாரிப்பு உரையாடல் AI எப்படி இயங்குகிறது என்பதைக் காட்டுகிறது. +இப்போது அதே வரிசையை இங்கு முயற்சிக்கவும். "என் பெயர் ஜான்" மற்றும் பின்பு "என் பெயர் என்ன?" இந்த முறையில் நினைவில் வைக்கும். வேறுபாடு MessageWindowChatMemory - அது உரையாடல் வரலாற்றை பராமரித்து ஒவ்வொரு கோரலுடனும் சேர்க்கிறது. இது உற்பத்தி உரையாடல் AI வேலை செய்யும் விதம். -நிலையுடைய உரையாடல் டெமோ +நிலையான உரையாடல் டெமோ -*AI உரையாடலின் முன்னாள் பகுதியிலிருந்து உங்கள் பெயரை நினைவில் வைக்கிறது* +*AI உரையாடலில் முன்பு கூறிய உங்கள் பெயரை நினைவில் வைத்திருக்கிறது* -இரண்டு இடைமுகங்களும் ஒரே GPT-5.2 மாதிரியை பயன்படுத்துகின்றன. வேறுபாடு நினைவில் மட்டுமே உள்ளது. இது நினைவின் பயன்பாட்டுக்கு என்ன முக்கியத்துவம் உள்ளது மற்றும் பயன்படுத்துவதன் நன்மைகள் குறித்து தெளிவாக காட்டுகிறது. +இரு பக்கங்களும் ஒரே GPT-5.2 மாதிரியை பயன்படுத்துகின்றன. ஒரே வேறுபாடு நினைவகம். இது நினைவகம் உங்கள் பயன்பாட்டிற்கு என்ன கொடுக்கும் மற்றும் உண்மையான பயன்பாடுகளில் ஏன் அவசியம் என்பதை தெளிவாக்குகிறது. -## இறுதி படிகள் +## அடுத்த படிகள் -**அடுத்த மாடி:** [02-prompt-engineering - GPT-5.2 உடன் Prompt Engineering](../02-prompt-engineering/README.md) +**அடுத்த தொகுதி:** [02-prompt-engineering - GPT-5.2 உடன் ப்ராம்ட் பொறியியல்](../02-prompt-engineering/README.md) --- -**நெவி கேசன்:** [← முந்தையது: Module 00 - விரைவான துவக்கம்](../00-quick-start/README.md) | [முதன்மைக்கு திரும்புக](../README.md) | [அடுத்து: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Navigation:** [← பிரத اصلیக்கு திரும்பு](../README.md) | [அடுத்தது: தொகுதி 02 - ப்ராம்ட் பொறியியல் →](../02-prompt-engineering/README.md) --- -**அறுத்துரை**: -இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவையான [Co-op Translator](https://github.com/Azure/co-op-translator) மூலம் மொழிபெயர்க்கப்பட்டது. நாங்கள் துல்லியத்துக்காக முயற்சி செய்கிறோம், என்றாலும் தானியங்கி மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கலாம் என்பதற்கு கவனமாயிருக்கவும். மூல ஆவணம் அதன் இயல்புவரையறுக்கப்பட்ட மொழியில் நிர்வாக ஆதாரமாகக் கொள்ளப்பட வேண்டும். முக்கிய தகவலுக்கு, தொழில்முறை மனித மொழிபெயர்ப்பை பரிந்துரைக்கிறோம். இந்த மொழிபெயர்ப்பை பயன்படுத்துவதால் ஏற்படும் எந்தவித மாறுபாடுகளுக்கும் அல்லது தவறான புரிந்துகொள்ளலுக்கும் நாங்கள் பொறுப்பானவர்கள் அல்ல. +**மறுப்பு**: +இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. நாங்கள் துல்லியத்திற்காக முயற்சி செய்துள்ளோம், ஆனால் தானாக செய்யப்படும் மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கலாம் என்பதை கவனத்தில் கொள்ளவும். அசல் ஆவணம் அதன் தாய்மொழியில் அதிகாரப்பூர்வ ஆதாரமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழில்நுட்பமான மனித மொழிபெயர்ப்பு பரிந்துரைக்கப்படுகிறது. இந்த மொழிபெயர்ப்பைப் பயன்படுத்துவதால் ஏற்படும் எந்த தவறான புரிதல்கள் அல்லது தவறான விளக்கத்திற்கும் நாங்கள் பொறுப்பில்வில்லை. \ No newline at end of file diff --git a/translations/ta/02-prompt-engineering/README.md b/translations/ta/02-prompt-engineering/README.md index eb224e145..4ffd2b647 100644 --- a/translations/ta/02-prompt-engineering/README.md +++ b/translations/ta/02-prompt-engineering/README.md @@ -1,102 +1,101 @@ -# தொகுதி 02: GPT-5.2 உடன் ப்ரான்ட் பொறியியல் +# அலகு 02: GPT-5.2 உடன் பிராம்ட் பொறியியல் -## உள்ளடக்கப்பட்டியல் +## உள்ளடக்கக் குறிப்பு -- [காணொளி வழிகாட்டு](../../../02-prompt-engineering) -- [நீங்கள் கற்கப் போகும் விஷயங்கள்](../../../02-prompt-engineering) -- [முதன்மைத் தேவைகள்](../../../02-prompt-engineering) -- [ப்ரான்ட் பொறியியலைப் புரிந்துகொள்](../../../02-prompt-engineering) -- [ப்ரான்ட் பொறியியல் அடிப்படைவிதிகள்](../../../02-prompt-engineering) - - [ஜீரோ-ஷாட் ப்ரான்டிங்](../../../02-prompt-engineering) - - [ஃபூ-ஷாட் ப்ரான்டிங்](../../../02-prompt-engineering) - - [திட்டக்கணிப்பு சங்கிலி](../../../02-prompt-engineering) - - [பாத்திர அடிப்படையிலான ப்ரான்டிங்](../../../02-prompt-engineering) - - [ப்ரான்ட் மாதிரிகள்](../../../02-prompt-engineering) -- [மேம்பட்ட மாதிரிகள்](../../../02-prompt-engineering) -- [சேவையை இயக்கு](../../../02-prompt-engineering) -- [சேவை திரைக்காட்சிகள்](../../../02-prompt-engineering) -- [மாதிரிகளை ஆராய்க](../../../02-prompt-engineering) - - [குறைந்த மற்றும் அதிக ஆர்வம்](../../../02-prompt-engineering) - - [பணிசெய்தல் (கருவி முன்னுரை)](../../../02-prompt-engineering) - - [சுய பரிசீலனை குறியீடு](../../../02-prompt-engineering) - - [கட்டமைக்கப்பட்ட பகுப்பாய்வு](../../../02-prompt-engineering) - - [பல-தரிசன உரையாடல்](../../../02-prompt-engineering) - - [படிகள் தவறாக காரணமாய்ச் சொல்வது](../../../02-prompt-engineering) - - [கட்டுப்படுத்தப்பட்ட வெளியீடு](../../../02-prompt-engineering) -- [நீங்கள் உண்மையில் என்ன கற்கின்றீர்கள்](../../../02-prompt-engineering) -- [அடுத்து இதை செய்யவும்](../../../02-prompt-engineering) +- [வீடியோ நடைமுறைப் பகிர்வு](#வீடியோ-நடைமுறைப்-பகிர்வு) +- [நீங்கள் கற்றுக்கொள்ள உள்ளீர்கள்](#நீங்கள்-கற்றுக்கொள்ள-உள்ளீர்கள்) +- [முன் நிபந்தனைகள்](#முன்-நிபந்தனைகள்) +- [பிராம்ட் பொறியியலைப் புரிதல்](#பிராம்ட்-பொறியியலைப்-புரிதல்) +- [பிராம்ட் பொறியியலின் அடிப்படைகள்](#பிராம்ட்-பொறியியலின்-அடிப்படைகள்) + - [சீரோ-ஷாட்டு பிராம்டிங்](#சீரோ-ஷாட்டு-பிராம்டிங்) + - [பூ-ஷாட்டு பிராம்டிங்](#few-shot-prompting) + - [சிந்தனை தொடர்](#சிந்தனை-தொடர்) + - [பங்கு அடிப்படையிலான பிராம்டிங்](#பங்கு-அடிப்படையிலான-பிராம்டிங்) + - [பிராம்ட் மாதிரிகள்](#பிராம்ட்-மாதிரிகள்) +- [அதிகப்படியான வடிவமைப்புகள்](#அதிகப்படியான-வடிவமைப்புகள்) +- [பயன்பாட்டை இயக்குக](#பயன்பாட்டை-இயக்கவும்) +- [பயன்பாட்டு திரைபடங்கள்](#பயன்பாட்டு-திரைபடங்கள்) +- [வடிவமைப்புகளை ஆய்வு செய்தல்](#படைப்புத்தடங்களை-ஆராய்தல்) + - [குறைந்த மற்றும் அதிக ஆர்வம்](#குறைந்த-எதிர்பார்ப்பு-மற்றும்-அதிக-எதிர்பார்ப்பு) + - [தொழில் நடைமுறை (கருவி முன்னோட்டங்கள்)](#பணிகள்-செயல்படுத்தல்-கருவி-முன்புலங்கள்) + - [சுய பிரதிபலிப்பு குறியீடு](#தன்னம்பிக்கை-கொண்ட-குறியீடு) + - [கட்டமைக்கப்பட்ட பகுப்பாய்வு](#கட்டமைக்கப்பட்ட-பகுப்பாய்வு) + - [பல முதல்முறை உரையாடல்](#பல-முறையான-உரையாடல்) + - [படி படியாக நடைமுறைசெய்தல்](#படி-படி-காரணக்கலை) + - [கட்டுப்படுத்தப்பட்ட வெளியீடு](#கட்டுப்பட்ட-வெளியீடு) +- [உங்களுக்கு உண்மையில் என்ன கற்றுக்கொள்ளப்படுகிறது](#நீங்கள்-உண்மையில்-கற்கிற-বিষয়ங்கள்) +- [அடுத்து என்ன செய்ய வேண்டும்](#அடுத்த-படிகள்) -## காணொளி வழிகாட்டு +## வீடியோ நடைமுறைப் பகிர்வு -இந்த தொகுதியை எவ்வாறு ஆரம்பிப்பது என்பதை விளக்கும் நேரடி இணக்கத்தைப் பாருங்கள்: +இந்த அலகுடன் எப்படிச் தொடங்குவது என்பதை விளக்கும் நேரடி அமர்வை பாருங்கள்: -LangChain4j உடன் ப்ரான்ட் பொறியியல் - நேரடி அமர்வு +Prompt Engineering with LangChain4j - Live Session -## நீங்கள் கற்கப்போகும் விஷயங்கள் +## நீங்கள் கற்றுக்கொள்ள உள்ளீர்கள் -அடுத்த படத்தில், இந்த தொகுதியில் நீங்கள் வளர்ப்பீர்கள் முக்கிய தலைப்புகள் மற்றும் திறன்கள் பற்றிய ஒரு சுருக்கக்காட்சியை காணலாம் — ப்ரான்ட் மேம்படுத்தல் தொழில்நுட்பங்களிலிருந்து படிடி படி பணிச்செயல்முறை வரையிலுக்கே. +இந்த அலகில் நீங்கள் மேம்படுத்தப்போகும் முக்கிய தலைப்புகள் மற்றும் திறன்களின் மேலோட்டம் கீழேயுள்ள படத்தில் காணலாம் — பிராம்ட் முறைகள் மேம்படுத்துதல் முதல் நீங்கள் பின்பற்றப்போகும் படி படியான தொழில்முறை வரை. -நீங்கள் கற்கப்போகும் விஷயங்கள் +What You'll Learn -முன்னைய தொகுதிகளில், நீங்கள் GitHub மாதிரிகளுடன் LangChain4j அடிப்படைக் தொடர்புகளை ஆராய்ந்து, Azure OpenAI உடன் மெமரி பேசும் AI ஐ எவ்வாறு இயங்கச் செய்கிறது என்பதைக் கண்டீர்கள். இப்போது, Azure OpenAI இன் GPT-5.2 ஐ பயன்படுத்தி நீங்கள் கேட்கும் கேள்விகள் - அதாவது ப்ரான்ட்களை - கவனிப்போம். நீங்கள் உங்கள் ப்ரான்ட்களை எவ்வாறு கட்டமைக்கிறீர்கள் என்பது பெறும் பதிலின் தரத்தை மோசடியாக்கும். நாங்கள் அடிப்படை ப்ரான்டிங் தொழில்நுட்பங்களை மறுபரிசீலனை செய்து, பிறகு GPT-5.2 உண்மையான திறன்களை முழுமையாகப் பயன்படுத்தும் எட்டுப் மேம்பட்ட மாதிரிகள் நோக்கிச் செல்கிறோம். +முந்தைய அலகில், நினைவகம் எப்படி Azure OpenAI உடன் உரையாடல் செயற்கை நுண்ணறிவை உருவாக்குகிறது என்பதை நீங்கள் பார்த்தீர்கள். இப்போது, நீங்கள் கேட்கும் கேள்விகள் — அதாவது பிராம்ட்கள் — எப்படி அமைக்கப்பட வேண்டும் என்று கவனம் செலுத்துவோம், Azure OpenAI கீழ் GPT-5.2 மூலம். உங்கள் பிராம்ட் அமைப்பு பெறும் பதில்களின் தரத்தை மிக அதிகமாக பாதிக்கிறது. முதலில் அடிப்படையான பிராம்டிங் நடைமுறைகளை மதிப்பாய்வு செய்து, பிறகு ஏழு முன்னேற்ற வடிவமைப்புகளுக்கு செல்லப்போகிறோம், அவை GPT-5.2 திறன்களை முழுமையாக பயன்படுத்துகின்றன. -நாங்கள் GPT-5.2 ஐ பயன்படுத்துவோம் ஏனெனில் இது காரணமேற்பார்வை கட்டுப்பாட்டை அறிமுகப்படுத்துகிறது — நீங்கள் மாதிரிக்கு பதில் அளிப்பதற்கு முன்னர் எவ்வளவு சிந்தனை செய்ய வேண்டும் என்பதை கூறலாம். இது பல ப்ரான்டிங் வழிமுறைகளை தெளிவாக உருவாக்கி, ஒவ்வொன்றையும் எப்போது பயன்படுத்த வேண்டும் என்பதையும் புரிந்துகொள்ள உதவுகிறது. GitHub மாதிரிகளுடன் ஒப்பிடுகையில், Azure இன் குறைவான அளவுரு வரம்புக்களையும் நாங்கள் பயன்படுத்தலாம். +நாம் GPT-5.2 ஐ பயன்படுத்துவோம் ஏனெனில் இது சிந்தனை கட்டுப்பாட்டை அறிமுகப்படுத்துகிறது — பதில் அளிப்பதற்கு முன் எவ்வளவு சிந்திக்க வேண்டும் என்பதை நீங்கள் சொல்லலாம். இது பல விதமான பிராம்டிங் கோல்புநிலைகளை தெளிவுபடுத்துகிறது மற்றும் எப்போது எந்த அணுகுமுறை பயன்படுத்த வேண்டும் என்று புரிய உதவுகிறது. -## முதன்மைத் தேவைகள் +## முன் நிபந்தனைகள் -- தொகுதி 01 முடித்திருப்பது (Azure OpenAI வளங்கள் வேரைவிடப்பட்டது) -- `.env` கோப்பு உலோக அடைவைல் Azure அங்கீகார விவரங்கள் (Module 01 இல் `azd up` மூலம் உருவாக்கப்பட்டது) +- அலகு 01 முடிக்கப்பட்டிருக்க வேண்டும் (Azure OpenAI வளங்கள் நிலைநிறுத்தப்பட்டவை) +- ரூட் கோப்புறை `.env` கோப்பு Azure அங்கீகாரங்களுடன் (அலகு 01இல் `azd up` மூலம் உருவாக்கப்பட்டது) -> **குறிப்பு:** தொகுதி 01 முடிக்காமல் இருந்தால், முதலில் அங்கே உள்ள அமைப்பு வழிமுறைகளை பின்பற்றவும். +> **குறிப்பு:** அலகு 01 முடிக்கப்படாமல் இருந்தால், முதலில் அங்கு உள்ள நிலைநிறுத்தும் வழிமுறைகளை பின்பற்றவும். -## ப்ரான்ட் பொறியியலைப் புரிந்துகொள் +## பிராம்ட் பொறியியலைப் புரிதல் -அடிப்படையில், ப்ரான்ட் பொறியியல் என்பது தெளிவற்ற அறிவுரைகளும் சரியானவைகளும் இடையேயான வேறுபாடு, கீழ்காணும் ஒப்பீடு இதை விளக்குகிறது. +அதன் சாரத்தில், பிராம்ட் பொறியியல் என்பது தெரியாத அல்லது முரண்பாடான வழிமுறைகளுக்கு மாறாக தெளிவான மற்றும் துல்லியமான வழிமுறைகள் தருவதாகும் என்பதை கீழே காட்டுகிறது. -ப்ரான்ட் பொறியியல் என்றால் என்ன? +What is Prompt Engineering? -ப்ரான்ட் பொறியியல் என்பது தொடர்ந்து நீங்கள் தேவைப்படும் முடிவுகளை பெறும் வகையில் உள்ளீடு உரையை வடிவமைப்பது. இது வெறும் கேள்விகள் கேட்டலை மட்டும் குறிக்கும் இல்லை - மாதிரி உங்கள் வேண்டுகோளை எவ்வாறு புரிந்துகொள்ள வேண்டும் மற்றும் அதை எவ்வாறு வழங்க வேண்டும் என்பதையும் கட்டமைக்கிறது. +பிராம்ட் பொறியியல் என்பது பூங்காற்றிலும் நிரந்தரமாக நீங்கள் தேவையான முடிவுகளை பெறுவதை உறுதி செய்யும் உள்ளீடு உரையை வடிவமைப்பது. அது கேள்விகள் கேட்குவதற்கு மட்டும் அல்ல — மாறாக, முறைப்படுத்தப்பட்ட கோரிக்கைகளை வழங்குவதற்கும், மாதிரி நீங்கள் என்ன வேண்டுமோ அந்த மாதிரிதான் புரிந்துகொண்டு எப்படி அதை வழங்குவது என்று அறிவதற்கும் ஆகும். -இதைக் கண்டிப்பாக ஒரு கூட்டாளருக்கு அறிவுரைகளை வழங்குவது போல நினைத்துக்கொள்ளுங்கள். "பிழையை சரி பார்" என்பது தெளிவற்றது. "UserService.java இன் 45-ஆவது வரியில் நல் சோதனையைச் சேர்த்து, null pointer exception ஐ சரி பார்" என்பது குறிப்பிட்டது. மொழி மாதிரிகள் ஒரே விதத்தில் செயல்படுகின்றன - குறிப்புணர்வு மற்றும் கட்டமைப்பு மிக முக்கியம். +உங்களைப் போன்ற ஒருவருக்கு அறிவுரைகள் அளிப்பதுபோல் நினைத்துக்கொள்ளுங்கள். "பிழையை சரி செய்" என்பது பொதுவானது. "UserService.java கோப்பின் 45-வது வரியில் உள்ள null pointer exception ஐ null சோதனை சேர்த்து சரி செய்" என்பது துல்லியமானது. மொழி மாதிரிகள் இதே விதமாக செயல்படுகின்றன — தனிப்பட்ட தன்மையும் அமைப்பும் முக்கியம். -கீழே உள்ள படத்தில், LangChain4j எப்படி இந்த படத்தில் பொருந்துகிறது என்பது காணப்படுகிறது — உங்கள் ப்ரான்ட் மாதிரிகளை SystemMessage மற்றும் UserMessage கட்டமைப்புகள் மூலம் மாதிரிக்கு இணைக்கிறது. +கீழேயுள்ள படத்தில் LangChain4j எப்படி இந்த காட்சியில் பொருத்தப்படுகிறது என்பதை காணலாம் — உங்கள் பிராம்ட் வடிவமைப்புகளை SystemMessage மற்றும் UserMessage கட்டுமானங்களை பயன்படுத்தி மாதிரிக்கு இணைக்கிறது. -LangChain4j எப்படி பொருந்துகிறது +How LangChain4j Fits -LangChain4j என்பது அடி உள்நிலை இடைமுகத்தை வழங்குகிறது — மாதிரி இணைப்புகள், நினைவகம் மற்றும் செய்தி வகைகள் — மற்றும் ப்ரான்ட் மாதிரிகள் கவனமாக கட்டமைக்கப்பட்ட உரை மட்டுமே, அவை அந்த உள்நிலையூடே அனுப்பப்படுகின்றன. முக்கிய கட்டமைப்புச் துண்டுகள் `SystemMessage` (AI இன் நடத்தை மற்றும் பாத்திரத்தை அமைக்கிறது) மற்றும் `UserMessage` (உங்கள் உண்மை வேண்டுகோளை கொண்டு செல்கிறது). +LangChain4j என்பது கட்டமைப்பு — மாதிரி இணைப்புகள், நினைவகம் மற்றும் செய்தி வகைகள் — உங்கள் பிராம்ட் வடிவமைப்புகள் அக்கட்டமைப்பின் வழியாக அனுப்பப்படும் கவனமாக வடிவமைக்கப்பட்ட உரை மட்டுமே. முக்கிய கட்டுமானங்கள் `SystemMessage` (இது AI நடத்தை மற்றும் பங்கைக் கொள்கிறது) மற்றும் `UserMessage` (உங்கள் வலுவான கோரிக்கையை எடுத்துச் செல்லும்) ஆகும். -## ப்ரான்ட் பொறியியல் அடிப்படைவிதிகள் +## பிராம்ட் பொறியியலின் அடிப்படைகள் -கீழே காணப்படும் ஐந்து முக்கிய தொழில்நுட்பங்கள், பயனுள்ள ப்ரான்ட் பொறியியலுக்கான அடிப்படையாக இருக்கின்றன. ஒவ்வொன்றும் மொழி மாதிரிகளோடு நீங்கள் தொடர்பு கொள்ளும் விதத்தின் ஒரு தனித்துவ உறுப்பை கையாள்கிறது. +கீழேயுள்ள ஐந்து முக்கிய தொழில்நுட்பங்கள் விளக்கப்பட்டுள்ளன, அவை பயனுள்ள பிராம்ட் பொறியியலின் அடித்தளமாகும். ஒவ்வொன்றும் மொழி மாதிரிகளுடன் நீங்கள் எப்படி தொடர்பு கொள்கிறீர்கள் என்பதில் வேறுபட்ட அம்சத்தைக் கையாள்கிறது. -ஐந்து ப்ரான்ட் பொறியியல் மாதிரிகளின் மேலோட்டம் +Five Prompt Engineering Patterns Overview -இந்த தொகுதியில் உள்ள மேம்பட்ட மாதிரிகளில் இறங்குவதற்கு முன், ஐந்து அடிப்படை ப்ரான்டிங் தொழில்நுட்பங்களை மறுபரிசீலனை செய்யலாம். இவை ஒவ்வொரு ப்ரான்ட் பொறியாளரும் அறிந்திருத்தல் வேண்டும். நீங்கள் ஏற்கனவே [தொடக்க தொகுதி](../00-quick-start/README.md#2-prompt-patterns) ஐ முடித்திருந்தால், இவற்றை செயலில் பார்த்திருப்பீர்கள் — இதோ அவற்றின் கற்பனைத் தளம். +இந்த அலகின் முன்னேற்ற வடிவமைப்புகளைச் சுருக்கமாக பார்க்க முன், ஐந்து அடிப்படையான பிராம்டிங் முறைகளை மீண்டும் பார்வையிடுவோம். இவை ஒவ்வொரு பிராம்ட் பொறியியலாளரும் அறிந்திருக்க வேண்டிய கட்டுமானக் கூறுகளாகும். -### ஜீரோ-ஷாட் ப்ரான்டிங் +### சீரோ-ஷாட்டு பிராம்டிங் -எளிய முறையானது: மாதிரிக்கு எதையும் எடுத்துக்காட்டு இல்லாமல் நேரடி அறிவுரையை அளிக்கவும். மாதிரி அல்வனைப் பயன்படுத்தி காரியத்தை புரிந்து செயல் படுத்துகிறது. இது நேரடி விளக்கத்துடன் கூடிய கேள்விகளுக்கு நல்லது. +எளிய அணுகுமுறை: மாதிரிக்கு எந்த உதாரணங்களும் அளிக்காமல் நேரடி அறிவுரையை கொடுக்கவும். மாதிரி அதன் பயிற்சியை முழுமையாகப் பயன்படுத்தி பணியாற்றுகிறது. இதுவே அசல் அசாதாரண கோரிக்கைகளுக்கு சிறப்பாக வேலை செய்கிறது. -ஜீரோ-ஷாட் ப்ரான்டிங் +Zero-Shot Prompting -*எடுத்துக்காட்டுகளின்றி நேரடி அறிவுரை — மாதிரி அறிவுரைகளிலிருந்து தானாகவே காரியத்தை புரிந்துகொள்கிறது* +*உதாரணங்கள் இல்லாமல் நேரடி அறிவுரைகள் — மாதிரி அறிவுரையிலிருந்து பணி எடுக்கிறது* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// பதில்: "நல்லது" +// பதில்: "நன்மை" ``` + +**எப்போது பயன்படுத்துவது:** எளிய வகைப்பாடுகள், நேரடி கேள்விகள், மொழி மாற்றங்கள் அல்லது மாதிரிக்குத் தேவையற்ற மேலதிக வழிகாட்டிகள் இல்லாத பணிகளுக்கு. +### Few-Shot Prompting -**எப்போது பயன்படுத்துவது:** எளிய வகைப்பாடு, நேரடி கேள்விகள், மொழிபெயர்ப்புகள், அல்லது கூடுதல் வழிகாட்டி தேவையில்லாத பணிகள். +மாதிரிக்கு பின்பற்றவேண்டிய வடிவமைப்பை எடுத்துக்காட்டும் உதாரணங்களை கொடுக்கவும். மாதிரி உதாரணங்களிலிருந்து எதிர்பார்க்கப்படும் உள்ளீடு-வெளியீடு வடிவத்தை கற்றுக்கொண்டும் புதிய உள்ளீடுகளுக்கு அதனைப் பயன்படுத்துகிறது. இது கோரிக்கை வடிவம் அல்லது நடத்தைகள் தெளிவாக இல்லாத பணிகளில் ஒத்திசைவுத்தன்மையை மேம்படுத்துகிறது. -### ஃபீவ்-ஷாட் ப்ரான்டிங் +Few-Shot Prompting -மாதிரிக்கு நீங்கள் பின்பற்றவேண்டிய மாதிரியை விளக்கும் எடுத்துக்காட்டுகளை வழங்கவும். மாதிரி எடுத்துக்காட்டுகளிலிருந்து ஊடுருவல் உள்ளீடு-வெளியீடு வடிவத்தை கற்றுக்கொள்ளும், புதிய உள்ளீடுகளில் அதைப் பயன்படுத்தும். இது விரும்பிய வடிவமைப்பு அல்லது நடத்தை தெளிவாக இல்லாத பணிகளுக்கு ஒத்திசைந்த செயல்திறனை மேம்படுத்தும். - -ஃபீவ்-ஷாட் ப்ரான்டிங் - -*எடுத்துக்காட்டுகளிலிருந்து கற்றுக்கொள்ளுதல் — மாதிரி மாதிரியை அடையாளம் காண்ந்து புதிய உள்ளீடுகளில் பயன்படுத்துகிறது* +*உதாரணங்களிலிருந்து கற்றல் — மாதிரி வடிவத்தை அடையாளம் கண்டு புதிய உள்ளீடுகளுக்கு பயன்படுத்துகிறது* ```java String prompt = """ @@ -112,17 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` + +**எப்போது பயன்படுத்துவது:** தனிப்பயன் வகைப்பாடுகள், நிலையான வடிவமைப்பு, குறிப்பிட்ட துறை பணி அல்லது சீரோ-ஷாட்டில் inconsistent முடிவுகள் கொண்ட பணிகளுக்கு. +### சிந்தனை தொடர் -**எப்போது பயன்படுத்துவது:** தனிப்பயன் வகைப்பாடு, ஒழுங்கான வடிவமைப்பு, துறை சார்ந்த பணிகள், அல்லது ஜீரோ-ஷாட் விளைவுகள் முரண்பட்டால். - -### Chain of Thought +மாதிரிக்கு படி படியாக அதன் சிந்தனையை காண்பிக்கும்படி கூறவும். பதில் ஒன்றுக்கு நேரடியாக செல்லாமல், மாதிரி பிரச்சினையை முறையாக உடைத்து ஒவ்வொன்றையும் வெளிப்படையாக செயல்படுத்துகிறது. இது கணிதம், விளக்கம் மற்றும் பலப்படியான சிந்தனை பணிகளுக்கு துல்லியத்தை மேம்படுத்துகிறது. -மாதிரியை படிகள் வழியாக அதன் காரணத்தை காட்டும்படி கேள். பதில் தரவிற்கு நேரடியாக குதிப்பதற்கு பதிலாக, மாதிரி பிரச்சினையை பிரித்து, ஒவ்வொரு பகுதிக்கும் தெளிவாக வேலை செய்கிறது. இதனால் கணிதம், நியாயம் மற்றும் பல படி காரணமறிவு பணிகளில் துல்லியம் அதிகரிக்கும். +Chain of Thought Prompting -திட்டக்கணிப்பு சங்கிலி ப்ரான்டிங் - -*படி படியான காரணமறிவு — சிக்கலான பிரச்சனைகளை தெளிவான நியாய படிகளாக உடைத்தல்* +*படி படி சிந்தனை — சிக்கலான பிரச்சினைகளை தெளிவான அறிய lógica நிலைகளாக உடைக்கும்* ```java String prompt = """ @@ -132,19 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// மாடல் காட்டுகிறது: 15 - 8 = 7, அதன்பின் 7 + 12 = 19 பேரீச்சம் +// மாதிரி காட்டுகிறது: 15 - 8 = 7, பின்னர் 7 + 12 = 19 ஆப்பிள்கள் ``` + +**எப்போது பயன்படுத்துவது:** கணிதப் பிரச்சினைகள், விளக்கம் புதிர்கள், பிழைத்திருத்தம் அல்லது எங்கே சிந்தனை செயல்முறை காட்டுதல் துல்லியத்தையும் நம்பகத்தன்மையையும் மேம்படுத்துகிறது. +### பங்கு அடிப்படையிலான பிராம்டிங் -**எப்போது பயன்படுத்துவது:** கணித பிரச்சனைகள், நியாய புதிர்கள், பிழைதிருத்தம், அல்லது காரணமறிவு செயல்முறை துல்லியம் மற்றும் நம்பகத்தன்மை மேம்பட வேண்டிய பணிகளில். - -### பாத்திர அடிப்படையிலான ப்ரான்டிங் - -உங்கள் கேள்விக்கு முன் AIக்கு ஒரு பாத்திரம் அல்லது பாத்திரத்தைக் கொடுக்கவும். இது பதிலின் சுருதி, ஆழம் மற்றும் கவனத்தை உருவாக்கும். ஒரு “மென்பொருள் கட்டமைப்பாளர்” "இளம் மேம்படுத்தகர்" அல்லது "பாதுகாப்பு ஆய்வாளர்" கொடுக்கும் ஆலோசனையைவிட வேறுபடுகின்றது. +உங்கள் கேள்விக்காக AIக்கு ஒரு நபர் அல்லது பங்கினை முன்பே அமைக்கவும். இது பதிலின் சுவை, ஆழம் மற்றும் கவனத்தை வடிவமைக்கும் உள்ளடக்கத்தை வழங்குகிறது. "சொப்ப்வேர் வடிவமைப்பாளர்" மற்றும் "ஜூனியர் டெவலப்பர்" அல்லது "பாதுகாப்பு ஆய்வாளர்" ஆகியோருக்கு வேறு சிக்கல்கள் உள்ளன. -பாத்திர அடிப்படையிலான ப்ரான்டிங் +Role-Based Prompting -*சூழல் மற்றும் பாத்திரத்தை அமைத்தல் — ஒற்றை கேள்விக்கு விதித்த பாத்திரத்தின் படி வெவ்வேறு பதில்கள் கிடைக்கும்* +*உள்ளடக்கம் மற்றும் பங்குகளை அமைத்தல் — அதே கேள்விக்கு விதிவிலக்கான பதில்கள் பங்கின் அடிப்படையில்* ```java String prompt = """ @@ -159,17 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` + +**எப்போது பயன்படுத்துவது:** குறியீடு மதிப்பாய்வுகள், டியூட்டோரிங், துறைக்கு ஆன பகுப்பாய்வு அல்லது குறிப்பிட்ட திறன் நிலை/காண்புகளுக்கு ஏற்ற பதில்கள் தேவைப்படும்போது. +### பிராம்ட் மாதிரிகள் -**எப்போது பயன்படுத்துவது:** குறியீட்டு மதிப்பாய்வுகள், பயிற்சியியல், துறை சார்ந்த பகுப்பாய்வுகள், அல்லது ஒரு குறிப்பிட்ட நிபுணத்துவ நிலை அல்லது பார்வைக்கேற்ப பதில்களை விரும்பும் பொழுது. +மாறும் இடங்களை கொண்ட மீண்டும் பயன்படுத்தக்கூடிய பிராம்ட்களை உருவாக்குக. ஒவ்வொரு முறையும் புதிய பிராம்ட் எழுதாமல், ஒரு மாதிரியை ஒருமுறை வரையறுத்து வெவ்வேறு மதிப்புகளை அதில் நிரப்பவும். LangChain4j இன் `PromptTemplate` வகுப்பு இதை `{{variable}}` வடிவில் எளிதாக்குகிறது. -### ப்ரான்ட் மாதிரிகள் +Prompt Templates -மாறிலி இடைத்தரவை கொண்ட மீண்டும் பயன்படுத்தக்கூடிய ப்ரான்டுகளை உருவாக்கவும். ஒவ்வொரு முறையும் புதிய ப்ரான்ட் எழுதுவதை தவிர்த்து, ஒருமுறை மாதிரியை வரைவிட்டு வெவ்வேறு மதிப்புகளை நிரப்பலாம். LangChain4j இன் `PromptTemplate` வகுப்பு `{{variable}}` வடிவத்தை எளிதாக பயன்படுத்து. - -ப்ரான்ட் மாதிரிகள் - -*இடைத்தரவு கொண்ட மீண்டும் பயன்படுத்தக்கூடிய ப்ரான்டுகள் — ஒரு மாதிரி, பல பயன்பாடுகள்* +*மாறும் இடங்களுடன் மீண்டும் பயன்படுத்தக்கூடிய பிராம்ட்கள் — ஒரு மாதிரி, பல பயன்பாடுகள்* ```java PromptTemplate template = PromptTemplate.from( @@ -183,29 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - - -**எப்போது பயன்படுத்துவது:** வித்தியாசமான உள்ளீடுகளுடன் அடிக்கடியான கேள்விகள், தொகுதி செயலாக்கம், மீண்டும் பயன்படுத்தக்கூடிய AI பணிச்செலவுகள் கட்டமைத்தல், அல்லது ப்ரான்ட் கட்டமைப்பு மாறாமலும் தரவு மாறும் சூழ்நிலைகளில். + +**எப்போது பயன்படுத்துவது:** வெவ்வேறு உள்ளீடுகளுடன் மீண்டும் மீண்டும் கேள்விகள், தொகுதி செயலாக்கம், மீண்டும் பயன்படுத்தக்கூடிய AI பணிகள் உருவாக்குவது அல்லது பிராம்ட் அமைப்பு ஒரே மாதிரியில் இருக்கும் ஆனால் தரவு மாறும் பாங்கில். --- -இந்த ஐந்து அடிப்படைகள் பெரும்பாலான ப்ரான்டிங் பணிகளுக்கு விருத்திகரமான கருவிகளை வழங்குகின்றன. இந்த தொகுதியின் மீதமுள்ள பகுதிகள் GPT-5.2 இன் காரணமறிவு கட்டுப்பாடு, சுய மதிப்பீடு மற்றும் கட்டமைக்கப்பட்ட வெளியீடு திறன்களை உள்ளடக்கிய **எட்டு மேம்பட்ட மாதிரிகளுக்கு** ஆதாரமாக அமைகின்றன. +இந்த ஐந்து அடிப்படைகள் பெரும்பாலான பிராம்டிங் பணிகளுக்கு பொருத்தமான கருவிகள் ஆகும். இந்த அலகின் மீதியான பகுதிகள் GPT-5.2 இன் சிந்தனை கட்டுப்பாடு, சுயமதிப்பீடு மற்றும் கட்டமைக்கப்பட்ட வெளியீடு திறன்களை பயன்படுத்தும் **எட்டு முன்னேற்ற வடிவமைப்புகளை** கொண்டவை. -## மேம்பட்ட மாதிரிகள் +## அதிகப்படியான வடிவமைப்புகள் -அடிப்படைகளை முடித்து, இப்போது இந்த தொகுதியை தனித்துவமாக்கும் எட்டு மேம்பட்ட மாதிரிகளுக்கு செல்வோம். அனைத்து பிரச்சனைகளும் ஒருபோதும் ஒரே அணுகுமுறையை வேண்டாமை. சில கேள்விகளுக்குத் துரித பதில்கள் வேண்டும், மற்றவை ஆழமான எண்ணம் தேவை. சிலக்கு காரணம் வெள்ளையாய் இருக்க வேண்டும், மற்றவை மட்டும் முடிவுகள் வேண்டும். கீழே உள்ள ஒவ்வொரு மாதிரி வேறு சூழ்நிலைக்காகத் தகுதியானது — GPT-5.2 இன் காரணமறிவு கட்டுப்பாடு இதை மேலும் தெளிவாகக் காணச் செய்கிறது. +அடிப்படைகள் முடிந்த பிறகு, இந்த அலகை தனித்துவமாக்கும் எட்டு முன்னேற்ற வடிவமைப்புகளுக்கு செல்லப்போகிறோம். எல்லா பிரச்சினைகளும் ஒத்த அணுகுமுறையைப் பெறவேண்டும் என்பது அவசியமில்லை. சில கேள்விகள் விரைவான பதில்களை தேவைப்படுத்துகின்றன, சில சந்தோஷமான சிந்தனையை. சிலக்கான முகங்காணும் சிந்தனை தேவை, சிலக்கு வெறும் முடிவுகள். கீழேயுள்ள ஒவ்வொரு வடிவமைப்பும் வேறுவித பிரச்சினைக்குத் tuned ஆகும் — மேலும் GPT-5.2 இன் சிந்தனை கட்டுப்பாடு வேறுபாடுகளை இன்னும் தெளிவாக்குகிறது. -எட்டு ப்ரான்ட் பொறியியல் மாதிரிகள் +Eight Prompting Patterns -*எட்டு ப்ரான்ட் பொறியியல் மாதிரிகளின் மேலோட்டம் மற்றும் அவற்றின் பயன்பாடுகள்* +*எட்டு பிராம்ட் பொறியியல் வடிவமைப்புகளின் மற்றும் அவற்றின் பயன்பாடுகளின் மேலோட்டம்* -GPT-5.2 இன் மற்றொரு பகுதி: *காரணமறிவு கட்டுப்பாடு*. கீழே உள்ள ஸ்லைடு மூலம் நீங்கள் மாதிரியின் சிந்தனை முயற்சியை - விரைவு நேரடி பதில்களிலிருந்து ஆழமான, முழுமையான பகுப்பாய்விற்கு வரை - எப்படி அமைக்கலாம் என்பதைக் காணலாம். +GPT-5.2 இன் புது அம்சம்: *சிந்தனை கட்டுப்பாடு*. கீழே உள்ள ஸ்லைடர் மாதிரி சிந்தனை முயற்சியை நீங்கள் விருத்தி செய்ய உதவுகிறது — விரைவு, நேரடி பதில்களிலிருந்து ஆழமான, விரிவான பகுப்பாய்வுக்கு வரை. -GPT-5.2 உடன் காரணமறிவு கட்டுப்பாடு +Reasoning Control with GPT-5.2 -*GPT-5.2 இன் காரணமறிவு கட்டுப்பாடு மாதிரி எத்தனை சிந்தனையைச் செய்ய வேண்டும் என்பதை நீங்கள் குறிப்பிட அனுமதிக்கிறது — விரைவான நேரடி பதில்களிலிருந்து ஆழமான சரியான ஆய்வுக்குக் காசம் வரை* +*GPT-5.2 இன் சிந்தனை கட்டுப்பாடு மாதிரிக்கு எவ்வளவு சிந்திக்க வேண்டும் என்பதை விரிவாகக் கூற அனுமதிக்கிறது — விரைவு நேரடி பதில்களிலிருந்து ஆழமான ஆராய்ச்சிக்குப்* -**குறைந்த ஆர்வம் (விரைவும் கவனமுடைந்ததும்)** - வேகமான, நேரடி பதில்களுக்கு எளிய கேள்விகளுக்கு. மாதிரி குறைந்த காரணமறிவை செய்யும் - அதிகபட்சம் 2 படிகள். கணக்குப் பணிகள், தேடல்கள் அல்லது எளிய கேள்விகளுக்கு இதைப் பயன்படுத்தவும். +**குறைந்த ஆர்வம் (விரைவும் கவனமாகவும்)** - எளிய கேள்விகளுக்காக விரைவு நேரடி பதில்கள் வேண்டும் எனில். மாதிரி குறைந்த சிந்தனையை செய்கிறது - அதிகபட்சம் 2 படிகள். கணக்குகள், தேடல்கள் அல்லது நேரடியான கேள்விகளுக்கு இதைப் பயன்படுத்தவும். ```java String prompt = """ @@ -223,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> 💡 **GitHub Copilot உடன் ஆராய்க:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ஐத் திறந்து கேளுங்கள்: +> - "குறைந்த ஆர்வம் மற்றும் அதிக ஆர்வம் பிராம்ட் வடிவமைப்புகளுக்கு என்ன வித்தியாசம்?" +> - "பிராம்ட்களில் உள்ள XML குறிச்சொற்கள் AI பதிலை அமைக்கும் விதத்தில் எப்படி உதவுகின்றன?" +> - "சுய பிரதிபலிப்பு வடிவமைப்புகளை நேரடி அறிவுரைகளுக்கு எப்போது பயன்படுத்துவது?" -> 💡 **GitHub Copilot உடன் ஆய்வு செய்யுங்கள்:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) திறந்து கேளுங்கள்: -> - "குறைந்த ஆர்வம் மற்றும் அதிக ஆர்வம் ப்ரான்ட் மாதிரிகளின் மாறுபாடு என்ன?" -> - "ப்ரான்ட்களில் XML குறிச்சொற்கள் AI பதிலை எப்படி கட்டமைக்க உதவுகின்றன?" -> - "சுய பரிசீலனை மாதிரிகளை நேரடி அறிவுரைகளோடு எப்போது பயன்படுத்த வேண்டும்?" - -**அதிக ஆர்வம் (ஆழமான மற்றும் முழுமையானது)** - விரிவான பகுப்பாய்வுக்கு வேண்டிய சிக்கலான பிரச்சனைகள். மாதிரி முழுமையாக ஆய்வு செய்து விவரமான காரணமறிவுகளை காட்டுகிறது. அமைப்பு வடிவமைப்பு, கட்டமைப்பு முடிவுகள் அல்லது சிக்கலான ஆராய்ச்சிக்கு இதைப் பயன்படுத்தவும். +**அதிக ஆர்வம் (ஆழமும் விரிவுமாக)** - கடினமான பிரச்சினைகளுக்கு விரிவான பகுப்பாய்வை விரும்பும் போது. மாதிரி ஆழமாக ஆராய்ந்து விரிவான சிந்தனையை காட்டுகிறது. இதை அமைப்பு வடிவமைப்பு, கட்டமைப்பு முடிவுகள் அல்லது சிக்கலான ஆராய்ச்சிக்குப் பயன்படுத்தவும். ```java String prompt = """ @@ -242,9 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - - -**பணி நடைமுறை (படி படி முன்னேற்றம்)** - பல படி பணிகளுக்கு. மாதிரி முன் திட்டத்தை வழங்கி, ஒவ்வொரு படியையும் செயும்போதே கூறி, பின்னர் சுருக்கத்தை வழங்கும். மாற்றங்கள், செயல்படுதல்கள் அல்லது ஏதேனும் பல படி செயலுக்காக இதைப் பயன்படுத்தவும். + +**தொழில் நடைமுறை (படி படியான முன்னேற்றம்)** - பல படிகள் உள்ள பணிகளுக்காக. மாதிரி முன்னதாக திட்டத்தை தருகிறது, ஒவ்வொரு படியையும் விளக்கி செல்கிறது, பின்னர் ஒரு சுருக்கத்தைக் கொடுக்கிறது. இடமாற்றங்கள், அமல்படுத்தல்கள் அல்லது எந்தவொரு பல படி செயலுக்கும் இதைப் பயன்படுத்தலாம். ```java String prompt = """ @@ -281,22 +275,22 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +சிந்தனை தொடர் பிராம்டிங் மாதிரி தனது சிந்தனை செயல்முறையை வெளிப்படையாக காட்டும்படி கேட்கிறது, இது சிக்கலான பணிகளுக்கான துல்லியத்தை மேம்படுத்துகிறது. படித் படியாக உடைப்பு மனிதர்களுக்கும் AI க்கும் தர்க்கத்தை புரிந்து கொள்ள உதவுகிறது. +> **🤖 [GitHub Copilot](https://github.com/features/copilot) உரையாடலுடன் முயற்சிக்கவும்:** +> இப்பிராம்ட் பற்றி கேளுங்கள்: +> - "நீண்டநேர செயல்பாடுகளுக்கான தொழில் நடைமுறை வடிவத்தை எப்படி இலகுவாக்குவேன்?" +> - "தயாரிப்பு பயன்பாடுகளில் கருவி முன்னோட்டங்களை அமைப்பதற்கான சிறந்த நடைமுறைகள் என்ன?" +> - "UIயில் இடைநிலை முன்னேற்றங்களை எப்படி பிடித்து காட்டலாம்?" -திட்டக்கணிப்பு சங்கிலி ப்ரான்டிங் காரணமறிவு செயல்முறையைத் தெளிவாக சொல்லும்படி சொல்கிறது, இது சிக்கலான பணிகளுக்கு துல்லியத்தை மேம்படுத்துகிறது. படி படியான உடைபுரிவு மனிதர்களுக்கும் AIக்கும் நியாயத்தைக் கண்டு கொள்ள உதவும். - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat உடன் முயற்சி செய்யுங்கள்:** இந்த மாதிரியை பற்றி கேளுங்கள்: -> - "நீண்ட நேர பணி நடைமுறைக்கு பணி நடைமுறை மாதிரியை எப்படி மாற்றுவது?" -> - "உற்பத்தி பயன்பாடுகளில் கருவி முன்னுரைகளுக்கு சிறந்த நடைமுறைகள் என்ன?" -> - "UI இல் இடைக்கால முன்னேற்றத்தை எவ்வாறு பிடித்து காட்டலாம்?" +எழுத்துக்காணல் -> செயல்படுத்தல் -> சுருக்கம் எனும் பணிச் செயல் நெறியை கீழ்காணும் படத்தில் காணலாம். -கீழே காணும் வரைபடம் Plan → Execute → Summarize செயல்முறையை விளக்குகிறது. +Task Execution Pattern -பணி நடைமுறை மாதிரி +*பல படி பணிகளுக்கான திட்டமிடல் -> செயல்படுத்தல் -> சுருக்கம் பணிச் செயல் நெறி* -*பல-படி பணிகளுக்கான திட்டமிடு → செய் → சுருக்கம் செயல்முறை* - -**சுய பரிசீலனை குறியீடு** - உற்பத்தி தரமான குறியீடு உருவாக்க. மாதிரி உற்பத்தி தர நிலைகளுக்கு ஏற்ப குறியீட்டை உருவாக்க, பிழை கையாள்வுடன் செயல் படுத்துகிறது. புதிய அம்சங்கள் அல்லது சேவைகள் கட்டுவது போல் பணிகளுக்கு இனி இதைப் பயன்படுத்தவும். +**சுய பிரதிபலிக்கும் குறியீடு** - தயாரிப்பு தரமான குறியீடு உருவாக்குவதற்கானது. மாதிரி தயாரிப்பு தர ஒழுங்குகளுக்கு ஏற்ப குறியீட்டை உருவாக்குகிறது மற்றும் பிழை கையாளலைச் சேர்க்கிறது. புதிய அம்சங்கள் அல்லது சேவைகள் கட்டும்போது இதைப் பயன்படுத்தவும். ```java String prompt = """ @@ -306,15 +300,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +கீழேயுள்ள சுற்றுப்படம் இந்த மறுபரிசீலனைச் சுற்றுப்பயணம் விளக்குகிறது — உருவாக்கு, மதிப்பீடு செய், பலவீனங்களை கண்டறி, மேம்படுத்து வரை குறியீடு தயாரிப்பு தரத்திற்கு ஏற்ப உருவாகும். +Self-Reflection Cycle -கீழே உள்ள வரைபடம் இதனை சுற்றி நடைபெறும் தொடர்ச்சியான மேம்பாட்டு சுழற்சியை காண்பிக்கிறது — உருவாக்கு, மதிப்பீடு செய், பலவீனங்களை கண்டறி, மேம்படுத்த, மீண்டும் செய்ய. - -சுய-பரிசீலனை சுழற்சி +*மறுபரிசீலனைச் சுற்று - உருவாக்கு, மதிப்பீடு செய், பிரச்சினைகளை கண்டறி, மேம்படுத்து, மீண்டும் செய்* -*தொடர்ச்சியான மேம்பாட்டு சுழற்சி - உருவாக்கு, மதிப்பீடு செய், பிரச்சனைகள் கண்டுபிடி, மேம்படு, மீண்டும் செய்* - -**கட்டமைக்கப்பட்ட பகுப்பாய்வு** - ஒத்திசைந்த மதிப்பீட்டுக்கு. மாதிரி ஒரு நிச்சயமான கட்டமைப்பை பயன்படுத்தி குறியீட்டை மதிப்பாய்வு செய்கிறது (தரும், நடைமுறைகள், செயல்திறன், பாதுகாப்பு, பராமரிப்பு). குறியீடு மதிப்பாய்வுக்கு அல்லது தர மதிப்பீட்டிற்கு இதைப் பயன்படுத்தவும். +**கட்டமைக்கப்பட்ட பகுப்பாய்வு** - நிலையான மதிப்பீட்டிற்கு. மாதிரி குறியீட்டை ஒரு நிலையான கட்டமைப்பை பின்தொடர்ந்து பரிசீலிக்கிறது (தயார்முறை, நடைமுறைகள், செயல்திறன், பாதுகாப்பு, பராமரிப்புத்தன்மை). குறியீடு மதிப்பாய்வுகள் அல்லது தரமாய்வு பணிகளுக்கு இதைப் பயன்படுத்தவும். ```java String prompt = """ @@ -361,19 +354,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> **🤖 [GitHub Copilot](https://github.com/features/copilot) உரையாடலுடன் முயற்சிக்கவும்:** கட்டமைக்கப்பட்ட பகுப்பாய்வு பற்றி கேளுங்கள்: +> - "வேறு வகையான குறியீடு மதிப்பாய்வுகளுக்கான பகுப்பாய்வு கட்டமைப்பை எப்படி தனிப்பயன் செய்யலாம்?" +> - "கட்டமைக்கப்பட்ட வெளியீட்டை நிரலாக்க முறையில் எப்படிப் பார்ச் செய்து செயலாற்றுவது சிறந்த வழி?" +> - "வேறுவிதமான மதிப்பாய்வுகளுக்குமிடையே ஒரே மாதிரியாகக் கடுமை நிலைகளை எப்படி உறுதி செய்வது?" -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat உடன் முயற்சி செய்யுங்கள்:** கட்டமைக்கப்பட்ட பகுப்பாய்வு பற்றி கேளுங்கள்: -> - "பல விதமான குறியீடு மதிப்பாய்வுகளுக்கு பகுப்பாய்வு கட்டமைப்பை எப்படி வகுத்துப்பெயர் மாற்றலாம்?" -> - "கட்டமைக்கப்பட்ட வெளியீட்டை நிரலாக்க முறையில் சீர்செய்து நடவடிக்கை எடுக்கும் சிறந்த வழி என்ன?" -> - "பல்வேறு மதிப்பாய்வுச் சந்திப்புகளுக்கு இடையே ஒரே மாதிரியாக கடுமைத்தன்மை நிலைகளை உறுதிப்படுத்த எப்படி?" - -கீழே உள்ள வரைபடம், கடுமைத்தன்மை நிலைகளுடன், ஒரே மாதிரியாகக் குறியீடு மதிப்பாய்வை அமைக்கிறது. +கீழேயுள்ள படத்தில் கட்டமைக்கப்பட்ட நெறிமுறைகள் ஒரு குறியீடு மதிப்பாய்வை நிலையான வகைகளும் கடுமை நிலைகளும் கொண்டு அமைப்பது காணப்படுகிறது. -கட்டமைக்கப்பட்ட பகுப்பாய்வு மாதிரி +Structured Analysis Pattern -*கடுமைத்தன்மை நிலைகளுடன் ஒரே மாதிரியான குறியீடு மதிப்பாய்வுகளுக்கான கட்டமைப்பு* +*கடுமை நிலைகள் உடன் நிலையான குறியீடு மதிப்பாய்வுக்கான கட்டமைப்பு* -**பல-தரிசன உரையாடல்** - சூழலுடன் உரையாடல்களுக்கு. மாதிரி முந்தைய செய்திகளை நினைவில் வைத்து அவற்றின் அடிப்படையில் கட்டிடம் செய்கிறது. செயற்பாட்டு உதவிக் அமர்வுகள் அல்லது சிக்கலான கேள்வி-பதில் வகைகளுக்கு இதைப் பயன்படுத்தவும். +**பல முதல்முறை உரையாடல்** - நிகழ்கால சூழல் தேவையான உரையாடல்களுக்கு. மாதிரி முந்தைய செய்திகளை நினைவில் வைத்துக் கொண்டு அதில் கட்டியெழுப்புகிறது. உதவி அமர்வுகள் அல்லது சிக்கலான கேள்வி-பதில்களுக்கு இதைப் பயன்படுத்து. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -386,14 +379,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` + +கீழேயுள்ள படத்தில் உரையாடல் சூழல் எப்படி படி படியாக சேர்க்கப்படுகிறது மற்றும் மாதிரியின் டோக்கன் எல்லையை எவ்வாறு தொடர்பு கொள்ளுகிறது என்பது காட்டப்படுகின்றது. +Context Memory -கீழே உள்ள வரைபடம் உரையாடல் சூழல் எவ்வாறு குழுவாக சேர்க்கப்படுகிறது மற்றும் மாதிரியின் டோக்கன் வரம்பால் எப்படி தொடர்பு இருப்பதை காண்பிக்கிறது. - -சூழல் நினைவகம் +*டோக்கன் எல்லை குழந்தையாய் உரையாடல் சூழல் எவ்வாறு சுருங்குகிறது* -*பல திருப்புகளுக்கான உரையாடல் சூழல் எவ்வாறு சேர்க்கப்படும் மற்றும் டோக்கன் வரம்பிற்கு எப்போது எட்டும் வரை* -**படி படியாக காரணமளிப்பு** - காட்சிப்படுத்தக்கூடிய தர்க்கத்திற்கு தேவையான பிரச்சனைகளுக்காக. மாடல் ஒவ்வொரு படியிலும் தெளிவான காரணமளிப்பை காட்டுகிறது. இதை கணிதப் பிரச்சனைகள், தர்க்க மேதினங்கள் அல்லது சிந்தனை செயல்முறையை புரிந்து கொள்ள வேண்டிய போது பயன்படுத்தவும். +**படி படியாக நடைமுறைசெய்தல்** - தெளிவான தர்க்கம் தேவைப்படும் பிரச்சினைகளுக்கு. மாதிரி ஒவ்வொரு படிக்கும் தெளிவான சிந்தனையாளர்த்து காட்டுகிறது. கணிதப் பிரச்சினைகள், விளக்கம் புதிர்கள் அல்லது சிந்தனை செயல்முறையை புரிந்துகொள்ள வேண்டிய நேரங்களில் இதைப் பயன்படுத்தவும். ```java String prompt = """ @@ -406,14 +399,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -கீழ்க்காணும் வரைபடம், மாடல் பிரச்சனைகளை தெளிவான, எண் அடிப்படையிலான தர்க்க படிகளாகப் பிரிக்கிறது என்பதைக் காட்டுகிறது. + +கீழேயுள்ள படத்தில் மாதிரி பிரச்சினைகளை தெளிவான, எண் அடையாளம் கொண்ட தர்க்க நடவடிக்கைகளாக உடைக்கும் விதம் காணப்படுகிறது. Step-by-Step Pattern +*பிரச்சனைகளை தெளிவான தர்க்கபூர்வ படிகளாக உடைக்கும் பயிற்சி* -*பிரச்சனைகளை தெளிவான தர்க்க படிகளாக உடைக்குதல்* - -**கட்டுப்படுத்தப்பட்ட வெளியீடு** - குறிப்பிட்ட வடிவமைப்பு தேவைகள் உள்ள பதில்களுக்கு. மாடல் வடிவமும் நீள விதிகளும் கடுமையாக பின்பற்றுகிறது. எச்சரிக்கைகள் அல்லது சரியான வெளியீட்டு அமைப்பை வேண்டுமெனில் இதைப் பயன்படுத்தவும். +**கட்டுப்பட்ட வெளியீடு** - குறிப்பிட்ட வடிவமைப்பு தேவைகள் உள்ள பதில்களுக்கு. மாதிரி வடிவமைப்பும் நீளக் கட்டுப்பாடுகளையும் கடுமையாக பின்பற்றும். சுருக்கங்களுக்கும் அல்லது துல்லியமான வெளியீடு கட்டமைப்புக்கு இதைப் பயன்படுத்தவும். ```java String prompt = """ @@ -429,65 +421,65 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -பின்வரும் வரைபடம் கட்டுப்பாடுகள் உங்கள் வடிவமைப்பு மற்றும் நீள தேவைகளுக்கு மாறாமல் பதிலளிக்க மாடலை எப்படி வழிநடத்துகின்றன என்பதை காட்டுகிறது. +பின்வரும் வரைபடம் மாதிரியை உங்கள் வடிவமைப்பு மற்றும் நீளக் கட்டுப்பாடுகளை கடுமையாக பின்பற்றும் வகையில் வெளியீட்டை உருவாக்க கட்டுப்பாடுகள் எவ்வாறு வழிகாட்டுகின்றன என்பதைக் காட்டுகிறது. Constrained Output Pattern -*குறிப்பிட்ட வடிவம், நீளம் மற்றும் அமைப்புப் பின்பற்றுதல்களை அமல்படுத்துதல்* +*குறிப்பிட்ட வடிவமைப்பு, நீளம், மற்றும் கட்டமைப்பு தேவைகளை காப்பது* -## பயன்பாட்டை இயக்கு +## பயன்பாட்டை இயக்கவும் -**அமைப்பை உறுதிப்படுத்துக:** +**பராமரிப்பை சரிபார்க்கவும்:** -`.env` கோப்பு ருட் கோப்புறையில் Azure அங்கீகார தகவல்களுடன் உள்ளதா என்பதை உறுதிப்படுத்துக (Module 01 இல் உருவாக்கப்பட்டது). இது இருந்து இயக்கவும் (`02-prompt-engineering/` என்ற மாட்யூல் கோப்புறையில்): +root கோப்புறை (Module 01 இல் உருவாக்கப்பட்ட) Azure சான்றிதழ்களுடன் `.env` கோப்பு இருப்பதை உறுதி செய்யவும். இதனை module கோப்பகத்திலிருந்து (`02-prompt-engineering/`) இயக்கவும்: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்ட வேண்டும் +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்டப்பட வேண்டும் ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்ட வேண்டும் +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காண்பிக்க வேண்டும் ``` -**பயன்பாட்டை துவக்குவோம்:** +**பயன்பாட்டைத் தொடங்கவும்:** -> **குறிப்பு:** நீங்கள் ஏற்கனவே அனைத்து பயன்பாடுகளையும் `./start-all.sh` மூலம் (Module 01 இல் எடுத்துக்காட்டியபடி) ருட் கோப்புறையில் துவக்கியிருந்தால், இந்த மாட்யூல் தொடங்கி உள்ளது, அதன் போர்ட் 8083. கீழுள்ள துவக்க கட்டளைகளை தவிர்த்து நேரடியாக http://localhost:8083 ஐப் பார்வையிடலாம். +> **குறிப்பு:** நீங்கள் ஏற்கனவே root கோப்புறையிலிருந்து `./start-all.sh` பயன்படுத்தி அனைத்து பயன்பாடுகளையும் துவக்கியிருந்தால் (Module 01 இல் விளக்கப்பட்டபடி), இந்த module ஏற்கனவே போர்ட் 8083 இல் இயங்கிக் கொண்டிருக்கிறது. கீழ்காணும் தொடக்க கட்டளைகளை தவிர்க்கலாம் மற்றும் நேரடியாக http://localhost:8083 சென்று தொடரலாம். -**விருப்பம் 1: Spring Boot Dashboard பயன்படுத்துதல் (VS Code பயனர்களுக்கான பரிந்துரை)** +**விருப்பம் 1: Spring Boot டாஷ்போர்டு பயன்படுத்துதல் (VS Code பயனர்களுக்கான பரிந்துரைக் கருத்து)** -வளர்ச்சித்துறை கொண்டெய்னரில் Spring Boot Dashboard நீட்சியுடன் வழங்கப்படுகிறது, இது அனைத்து Spring Boot செயலிகளையும் ஒருங்கிணைத்து காட்சிப்படுத்தும் இடைமுகம். இது VS Code இன் இடது பக்க Activity Bar இல் Spring Boot ஐகானை காணலாம். +dev containerல் Spring Boot Dashboard விரிவாக்கம் உள்ளது, இது அனைத்து Spring Boot பயன்பாடுகளையும் கையாள்வதற்கான காட்சி இடைமுகம் வழங்குகிறது. VS Codeஇல் இடதுபுற Activity Barஇல் Spring Boot ஐகானைக் காணலாம். -Spring Boot Dashboard இல் இருந்து, நீங்கள்: -- வேலைநிறுத்துதலில் உள்ள அனைத்து Spring Boot செயலிகளைப் பார்க்கலாம் -- செயலிகளை ஒரே கிளிக்கில் துவக்க/நிறுத்தலாம் -- செயலி பதிவுகளை நேரடி காலத்தில் காணலாம் -- செயலி நிலையை கண்காணிக்கலாம் +Spring Boot Dashboardயிலிருந்து நீங்கள்: +- வேலை பகுதிகளில் உள்ள அனைத்து Spring Boot பயன்பாடுகளையும் காணலாம் +- ஒரே கிளிக்கில் பயன்பாடுகளை தொடக்க/நிறுத்தலாம் +- பயன்பாட்டு பதிவுகளை நேரடியாக பார்க்கலாம் +- பயன்பாட்டு நிலையை கண்காணிக்கலாம் -"prompt-engineering" விருப்பமான செயலியை துவக்க பிளே பொத்தானை அழுத்தவும், அல்லது ஒரே நேரத்தில் அனைத்து மாட்யூல்களையும் துவக்கவும். +`prompt-engineering` அருகே உள்ள play பொத்தானை கிளிக் செய்து இந்த moduleஐத் தொடங்கவும், அல்லது அனைத்து modulesஐ ஒரே நேரத்தில் தொடங்கவும். Spring Boot Dashboard -*VS Code இல் Spring Boot Dashboard — அனைத்து மாட்யூல்களையும் ஒரே இடத்தில் துவக்க, நிறுத்த மற்றும் கண்காணிக்க* +*VS Codeஇல் Spring Boot Dashboard — அனைத்து modulesஐ ஒரே இடத்தில் தொடக்கி, நிறுத்தி, கண்காணிக்கலாம்* -**விருப்பம் 2: ஷெல் ஸ்கிரிப்ட் பயன்படுத்துதல்** +**விருப்பம் 2: shell ஸ்கிரிப்டுகளை பயன்படுத்துதல்** -அனைத்து வலை பயன்பாடுகளையும் (மாட்யூல் 01-04) துவக்கவும்: +அனைத்து வலை பயன்பாடுகளையும் (modules 01-04) துவக்கு: **Bash:** ```bash -cd .. # ரூட் அடைவு முதலாக +cd .. # வேர் அடைவைத் தொடங்கி ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # ரூட் அடைவு கோப்புறையிலிருந்து +cd .. # ரூட் அடைவு கோப்புறைஇல் இருந்து .\start-all.ps1 ``` -அல்லது இந்த மாட்யூல் மட்டும் துவக்கவும்: +இல்லையெனில் இந்த moduleஐ தனியாக துவக்கு: **Bash:** ```bash @@ -501,9 +493,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -இரண்டும் ருட் `.env` கோப்பிலிருந்து இயங்கு சூழல் மாறிகள் ஏற்றப்படுகிறது மற்றும் JAR கோப்புகள் இல்லாவிட்டால் கட்டியெடுக்கப்படும். +இரண்டுமே root `.env` கோப்பில் உள்ள சூழல் மாறிலிகளை தானாக ஏற்றும் மற்றும் JARகள் இல்லை என்றால் அவற்றை தயாரிக்கும். -> **குறிப்பு:** துவக்க முன் அனைத்து மாட்யூல்களை கைமுறையாக கட்ட விரும்பினால்: +> **குறிப்பு:** தொடங்கும் முன் அனைத்து modulesஐ கையால் கட்ட நினைத்தால்: > > **Bash:** > ```bash @@ -517,7 +509,7 @@ cd 02-prompt-engineering > mvn clean package -DskipTests > ``` -http://localhost:8083 ஐ உலாவியில் திறக்கவும். +உங்கள் உலாவியில் http://localhost:8083 ஐத் திறக்கவும். **நிறுத்த:** @@ -525,93 +517,93 @@ http://localhost:8083 ஐ உலாவியில் திறக்கவு ```bash ./stop.sh # இந்த தொகுதி மட்டும் # அல்லது -cd .. && ./stop-all.sh # அனைத்து தொகுதிகளும் +cd .. && ./stop-all.sh # அனைத்து தொகுதிகள் ``` **PowerShell:** ```powershell -.\stop.ps1 # இந்த மொடியூல் மட்டும் +.\stop.ps1 # இந்த தொகுதி மட்டும் # அல்லது -cd ..; .\stop-all.ps1 # அனைத்து மொடியூல்கள் +cd ..; .\stop-all.ps1 # அனைத்து தொகுதிகளும் ``` ## பயன்பாட்டு திரைபடங்கள் -இது prompt engineering மாட்யூலின் முக்கிய இடைமுகம், இதில் எட்டு வகைவற்றையும் நீராஜமாகப் பக்கத்தில் எடுத்து செயல்படலாம். +இது prompt engineering moduleஇன் பிரதான இடைமுகம், இதில் நீங்கள் அனைத்து எட்டு படைப்புத்தடங்களையும் ஒன்றில் பார்த்து முயற்சி செய்யலாம். Dashboard Home -*எட்டு prompting மாதிரிகளும், அவற்றின் பண்புகள் மற்றும் பயன்பாட்டு வழிகளுடன் முதன்மை டாஷ்போர்டு* +*அனைத்து 8 prompt engineering படைகள் மற்றும் அவற்றின் பண்புகள் மற்றும் பயன்பாட்டு சூழல்களை காட்டும் பிரதான டாஷ்போர்டு* -## மாதிரிகள் ஆராய்ச்சி +## படைப்புத்தடங்களை ஆராய்தல் -இணைய இடைமுகம் பல prompting தந்திரங்களுடன் செயல்பட உதவுகிறது. ஒவ்வொரு மாதிரியும் வேறுபட்ட பிரச்சனைகள் தீர்க்கிறது - அவர்களை முயற்சி செய்து எந்தப் போக்கு எப்போது சிறப்பாக செயல்படுகிறது என்பதை பாருங்கள். +வலை இடைமுகம் வெவ்வேறு prompting மூலோபாயங்களை முயற்சிக்க அனுமதிக்கிறது. ஒவ்வொரு படையும்தான் வேறுபட்ட பிரச்சனைகளை தீர்க்கிறது - எப்போது ஒவ்வொரு அணுகுமுறை சிறப்பாக செயல்படுகிறது என்பதை பாருங்கள். -> **குறிப்பு: ஓட்டுதல் மற்றும் இல்லாத ஓட்டுதல்** — ஒவ்வொரு மாதிரி பக்கத்திலும் இரண்டு பொத்தான்கள்: **🔴 Stream Response (Live)** மற்றும் ஒரு **Non-streaming** விருப்பம். ஓட்டுதல் Server-Sent Events (SSE) மூலம் பதிலின் டோக்கன்களை நேரடி காலத்தில் காட்டுகிறது, எனவே மோடல் உருவாக்கும் பொழுது உடனடியான முன்னேற்றம் தெரியும். இல்லாத ஓட்டுதல் பதிலின் முழு வரம் முடியும் வரை காத்திருக்கும். ஆழமான காரணமளிப்பைக் கோரும் prompting க்கான முறையில் (எ.கா., High Eagerness, Self-Reflecting Code), இல்லாத ஓட்டுதல் அழைப்பு மிக நீண்ட நேரம் எடுக்கலாம் — சில நேரங்களில் நிமிடங்கள் — காட்சி பின்புலம் இல்லாமல். **சிக்கலான prompting கൾ செயற்திறனை காண ஓட்டுதலைப் பயன்படுத்தவும்** மேலும் வேண்டாமென்றால் கோரிக்கை நேரம் முடிந்துவிட்டதாகப் பிழை ஏற்படுவது தவிர்க்கலாம். +> **குறிப்பு: ஸ்ட்ரீமிங் மற்றும் ஸ்ட்ரீமிங் அல்லாதவைகள்** — ஒவ்வொரு படை பக்கத்திலும் இரண்டு பொத்தான்கள் இருக்கும்: **🔴 Stream Response (Live)** மற்றும் **Non-streaming** விருப்பம். ஸ்ட்ரீமிங் Server-Sent Events (SSE) பயன்படுத்தி மாதிரியின் உருவாக்கிய டோக்கன்களை நேரடியாக காட்டுகிறது, எனவே முன்னேற்றத்தை உடனே பார்க்கலாம். ஸ்ட்ரீமிங் அல்லாத விருப்பம் முழுவெளியீட்டிற்காக காத்திருக்கிறது. ஆழமான காரணக்கலைத் தூண்டும் promptingகளுக்கு (உதா: High Eagerness, Self-Reflecting Code), ஸ்ட்ரீமிங் அல்லாத அழைப்பு மிகவும் நீண்ட நேரம் எடுத்துக்கொள்ளலாம் — சில நேரங்களில் நிமிடங்கள் — மற்றும் காணக்கிடைக்கும் பின்தொடர்பின்றி இருக்கும். **கடினமான promptingகளுடன் அனுபவிக்கும்போது ஸ்ட்ரீமிங்கை பயன்படுத்தவும்**; மாதிரி செயல்படும் என்பதைப் பார்த்து கோரிக்கையை தவறவிடாமல் இருப்பது முக்கியம். > -> **குறிப்பு: உலாவி தேவைகள்** — ஓட்டுதலுக்கான அம்சம் Fetch Streams API (`response.body.getReader()`) க்கு ஆதரவு தரும் முழுமையான உலாவியை (Chrome, Edge, Firefox, Safari) தேவைப்படுகிறது. VS Code இன் உள்ளமைக்கப்பட்ட Simple Browser இல் இது செயல்படாது, ஏனெனில் அதன் webview ReadableStream API ஐ ஆதரிக்காது. Simple Browser பயன்படுத்தினால், இல்லாத ஓட்டுதலுக்கான பொத்தான்கள் இயல்பாகவே வேலைபோகும் — ய்வானாக ஓட்டுதல் பொத்தான்கள் மட்டுமே பாதிக்கப்படும். முழுமையான அனுபவத்திற்கு வெளியுறை உலாவியில் `http://localhost:8083` ஐ திறக்கவும். +> **குறிப்பு: உலாவி தேவைகள்** — ஸ்ட்ரீமிங் அம்சம் Fetch Streams API (`response.body.getReader()`) பயன்படுத்துகிறது, இது முழு உலாவிகளை (Chrome, Edge, Firefox, Safari) தேவைப்படும். VS Code இன் கட்டப்பட்ட Simple Browser இல் இது இயங்காது, ஏனெனில் அதன் webview ReadableStream API வை ஆதரிக்காது. Simple Browser பயன்படுத்தினால் ஸ்ட்ரீமிங் அல்லாத பொத்தான்கள் வழமையாக வேலைசெய்யும் — ஸ்ட்ரீமிங் பொத்தான்கள் மட்டுமே பாதிக்கப்படும். முழு அனுபவத்திற்கு http://localhost:8083 ஐ வெளிநாட்டு உலாவியில் திறக்கவும். -### குறைந்த Eagerness மற்றும் அதிக Eagerness +### குறைந்த எதிர்பார்ப்பு மற்றும் அதிக எதிர்பார்ப்பு -"200 இன் 15% என்ன?" என்ற எளிய கேள்வியை குறைந்த Eagerness உடன் கேளுங்கள். உடனடி, நேரடியான பதில் தரப்படும். இப்போது "பெரிய போக்குவழி API க்கான கேச்சிங் திட்டத்தை வடுவமைக்கவும்" என்ற சிக்கலான கேள்வியை அதிக Eagerness உடன் கேளுங்கள். **🔴 Stream Response (Live)** சொடுக்கி, மாடல் விரிவான காரணமளிப்பை டோக்கன்களாகப் பார்க்கலாம். ஒரே மாடல், ஒரே கேள்வி அமைப்பு - ஆனால் prompting அது எவ்வளவு சிந்திக்க வேண்டும் என்பதைக் கட்டுப்படுத்துகிறது. +"200 இன் 15% எவ்வளவு?" என்ற எளிய கேள்வியை குறைந்த எதிர்பார்ப்புடன் கேளுங்கள். உடனடி, நேரடி பதிலை பெறுவீர்கள். இப்போது "உயர்ந்த போக்குவரத்து API க்கான caching யுக்தியைக் வடிவமைக்கவும்" என்ற குழப்பமான கேள்வி கேளுங்கள் உயர்ந்த எதிர்பார்ப்புடன். **🔴 Stream Response (Live)** இனை கிளிக் செய்து மாதிரியின் விரிவான காரணவியல் ஒவ்வொரு டோக்கனாக உருவாகும் போது காணுங்கள். அதே மாதிரி, அதே கேள்வி கட்டமைப்பு - ஆனால் prompting அதன் எண்ண நோக்கத்தை தெரிவிக்கிறது. -### பணி இயக்குதல் (கருவி முன்னுரை) +### பணிகள் செயல்படுத்தல் (கருவி முன்புலங்கள்) -பல படி வேலைவிளைவுகள் முன்னுரிமை திட்டமிடுதல் மற்றும் முன்னேற்ற விளக்கக் கூறுதலில் நன்மை. மாடல் செய்யும் படிகளை விளக்கி, ஒவ்வொரு படியையும் கூறி, முடிவுகளை சுருக்கி தருகிறது. +பல படிகள் உள்ள பணிகள் முன்கூட்டியே திட்டமிடல் மற்றும் முன்னேற்றத்தை விளக்குதல் மூலம் பயனடைகின்றன. மாதிரி செய்யப்போகும் செயல்களை வரையறுத்து, ஒவ்வொரு படியையும் விளக்கி, பின்னர் முடிவுகளை சுருக்கமாக கூறுகிறது. -### தன்னம்பிக்கை குறியிட்டல் குறியீடு +### தன்னம்பிக்கை கொண்ட குறியீடு -"மின்னஞ்சல் சரிபார்ப்பு சேவையை உருவாக்கு" என்று முயற்சி செய்யவும். மாடல் குறியீடு உருவாக்கி நிறுத்தமாட்டாது, தரக் குறியீட்டின் அடிப்படையில் மதிப்பாய்வு செய்து, பலவீனங்களை கண்டறிந்து மேம்படுத்தும். உற்பத்தித் தரத்துடன் குறியீடு பொருந்தும் வரை மாடல் மீண்டும் மீண்டும் முயற்சிக்கிறது. +"மேலாளியின் மின்னஞ்சல் சேவையை உருவாக்குக" என்பதை முயற்சிக்கவும். மட்டும் குறியீடு உருவாக்கி நிறுத்துவதற்கு பதிலாக, மாதிரி குறியீட்டை உருவாக்கி, தரநிலைகளோடு மதிப்பாய்வு செய்து, பலவீனங்களை கண்டறிந்து, மேம்படுத்துகிறது. குறியீடு உற்பத்தி தர நிலையில் வரும்வரை அது திருத்தத்தை தொடரும். ### கட்டமைக்கப்பட்ட பகுப்பாய்வு -குறியீட்டு மதிப்பாய்விற்குத் தனிப்பட்ட தரமான மதிப்பாய்வு கட்டமைப்புகள் தேவை. மாடல் படி வகைப்படுத்தப்பட்ட பிரிவுகளால் (தரச்சரிவு, நடைமுறை, செயல்திறன், பாதுகாப்பு) குறியீட்டை ஆராய்கிறது, அதிலும் தீவிரத்துடன். +குறியீடு விமர்சனம் ஒரே விதமாக மதிப்பீட்டுக்கு தேவைப்படுகின்றது. மாதிரி சீராக மதிப்பீடு செய்யத் தரப்பட்ட பிரிவுக்களை (தவறற்ற தன்மை, நடைமுறைகள், செயல்திறன், பாதுகாப்பு) உபயோகித்து மதிப்பாய்வு செய்கிறது. -### பல முறை உரையாடல் +### பல-முறையான உரையாடல் -"Spring Boot என்ன?" என்று கேளுங்கள், உடனே "ஒரு எடுத்துக்காட்டை காட்டவும்" கொடுக்கவும். மாடல் உங்கள் முதல் கேள்வியை நினைவில் வைத்து, Spring Boot எடுத்துக்காட்டை வழங்கும். நினைவில்லை என்றால் இரண்டாவது கேள்வி மிகவும் பொதுவானதாகிவிடும். +"Spring Boot என்பது என்ன?" என்று கேளுங்கள். பிறகு "ஒரு உதாரணத்தை காட்டவும்" என்று உடனுக்குடன் கேளுங்கள். மாதிரி உங்கள் முதன்மையான கேள்வியை நினைவுகூறும் மற்றும் குறிப்பிட்ட Spring Boot உதாரணத்தை தரும். நினைவின்றி இரண்டாவது கேள்வி மிகவும் பொதுவாக இருக்கும். -### படி படியாக காரணமளிப்பு +### படி படி காரணக்கலை -ஒரு கணிதப் பிரச்சனையை தேர்வு செய்து, அதனை படி படியாக காரணமளித்து மற்றும் குறைந்த Eagerness உடன் முயற்சிக்கவும். குறைந்த Eagerness உடன் பதிலளிப்பு விரைவானது ஆனால் வெளிப்படையில்லை. படி படியாக பாதி கணக்கீடுகள், முடிவுகளைக் காட்டும். +ஒரு கணிதப் பிரச்சனையை எடுத்து, Step-by-Step Reasoning மற்றும் குறைந்த எதிர்பார்ப்புடன் முயற்சி செய்யுங்கள். குறைந்த எதிர்பார்ப்பு நேரடியாக பதிலை தரும் - வேகமாக ஆனால் மறைந்துள்ளது. படி படியாக ஒவ்வொரு கணக்கையும் மற்றும் முடிவையும் காட்டுகிறது. -### கட்டுப்படுத்தப்பட்ட வெளியீடு +### கட்டுப்பட்ட வெளியீடு -விரிவான வடிவியம் அல்லது வார்த்தை எண்ணிக்கை தேவைப்படும் போது, இந்த மாதிரி கட்டுப்படுத்தப்பட்ட விதிகளைக் கடைப்பிடிக்கும். நேரடியாக 100 வார்த்தைகளில் பட்டியலாக சுருக்கம் செய்ய முயற்சி செய்யவும். +குறிப்பிட்ட வடிவங்கள் அல்லது சொல்லுருக்கள் எண்ணிக்கை தேவைப்படும் போது, இந்த படை கடுமையாக பின்பற்றுகிறது. துல்லியமாக 100 சொற்கள் கொண்ட புள்ளி வடிவில் சுருக்கம் உருவாக்க முயற்சி செய்யவும். -## நீங்கள் உண்மையில் கற்றுக்கொள்ளும் விஷயம் +## நீங்கள் உண்மையில் கற்கிற বিষয়ங்கள் -**காரணமளிப்புப் பிரயாசம் எல்லாமே மாற்றுகிறது** +**காரணக்கலை முயற்சி அனைத்தையும் மாற்றுகிறது** -GPT-5.2 உங்கள் prompting வாயிலாக கணக்கீட்டு முயற்சியைக் கட்டுப்படுத்த அனுமதிக்கிறது. குறைந்த முயற்சி விரைவு பதில்களையும் குறைந்த ஆய்வையும் குறிக்கும். அதிக முயற்சி மாடல் ஆழமான சிந்தனையை எடுத்துக் கொள்கிறது. நீங்கள் பணியின் சிக்கலுக்கு ஏற்ப முயற்சியை பொருத்தலினை கற்றுக்கொள்கிறீர்கள் - எளிய கேள்விகளுக்கு நேரத்தை வீண்படுத்தாதீர்கள், ஆனால் சிக்கலான முடிவுகளை ஊர்முகமாக மிச்சப்படுத்த வேண்டாம். +GPT-5.2 prompting-ன் மூலம் உங்களின் கணினி முயற்சியை கட்டுப்படுத்த உதவுகிறது. குறைந்த முயற்சி விரைவான பதிலை குறைந்த ஆராய்ச்சியுடன் தரும். அதிக முயற்சி மாதிரி ஆழமான சிந்தனை செலுத்தும். நீங்கள் செயலை வேண்டிய சிக்கலுக்கு ஏற்ப முயற்சி பொருந்துகிறது என்பதை கற்றுக்கொள்கிறீர்கள் - எளிய கேள்விகளில் நேரம் வீணாக விடாதீர்கள், ஆனால் கடின முடிவுகளை விரைந்து எடுக்க வேண்டாம். -**வடிவமைப்பு நடத்தையில் வழிகாட்டுகிறது** +**கட்டமைப்பு செயல்பாட்டை வழிநடத்துகிறது** -prompt களில் உள்ள XML குறிச்சொற்கள் கவனியுங்கள்? அவை அலங்காரமல்ல. மாடல்கள் கட்டமைக்கப்பட்ட கட்டளைகளை விட முனைப்புடனும் நம்பகத்தன்மையுடனும் பின்பற்றுகின்றன. பல படிக்கட்ட செயல்முறைகள் அல்லது சிக்கலான தர்க்கம் வேண்டுமிடத்தில், வடிவமைப்பு மாடல் எங்கே இருக்கிறது மற்றும் அடுத்து என்ன வருகிறது என்பதை கண்காணிக்க உதவுகிறது. கீழ்க்காணும் வரைபடம் நன்றாக கட்டமைக்கப்பட்ட prompting-ஐப் பிரிக்கிறது, ``, ``, ``, ``, மற்றும் `` போன்ற குறிச்சொற்கள் உங்கள் கட்டளைகளை தெளிவான பிரிவுகளாக அமைக்கிறது. +promptகளில் XML டேக்குகள் இருக்கின்றன என்பதை கவனிக்கவும்? அவை அலங்காரம் அல்ல. மாதிரிகள் கட்டமைக்கப்பட்ட அறிவுறுத்தல்களை சுதந்திர உரையைவிஷயம் காட்டும் பொறுமையாக பின்பற்றுகின்றன. பல படி செயலிகள் அல்லது குழப்பமான தர்க்கத்துக்கு கட்டமைப்பு மாதிரிக்கு எங்கே இருக்கிறது மற்றும் அடுத்தது என்ன என்பதைக் கண்காணிக்க உதவுகிறது. கீழ்காணும் வரைபடம் நல்ல கட்டமைப்புக் கொண்ட promptஐ உடைத்து, ``, ``, ``, ``, மற்றும் `` போன்ற டேக்-கள் அறிவுறுத்தல்களை தெளிவான பிரிவுகளாக ஒழுங்குபடுத்துவது எப்படி என்பதை விளக்குகிறது. Prompt Structure -*XML-வில்லான அமைப்புடன் தெளிவான பிரிவுகளைக் கொண்ட நன்றாக கட்டமைக்கப்பட்ட ஒரு prompting அமைப்பு* +*xml-உடன் தெளிவான பிரிவுகளும் கட்டமைப்புடனும் கொண்ட நல்ல prompt உருவகப்படம்* -**தனிமனித சம்பந்தப்பட்ட தரம்** +**தன் மதிப்பீட்டின் மூலம் தரம்** -தன்னம்பிக்கை prompting கள் தரம் குறிப்புகளை தெளிவுபடுத்துவதன் மூலம் செயல்படுகின்றன. மாடல் "சரி செய்துகொள்ளும்" என்ற நம்பிக்கையைப் பதிலாக, நீங்கள் சரியானது என்பதன் பொருளை உரைக்கிறீர்கள்: சரியான தர்க்கம், பிழை கையாளல், செயல்திறன், பாதுகாப்பு. அதன்பின் மாஸ்டர் தனது வெளியீட்டை மதிப்பாய்வு செய்து மேம்படுத்தலாம். இது குறியீடு உருவாக்குதலை அபரிமித வெற்றிப் பிடிவாதமாக மாற்றுகிறது. +தன்னம்பிக்கை கொண்ட படைகள் தரநிலைகளைத் தெளிவுபடுத்துவதன் மூலம் செயல்படுகின்றன. மாதிரிக "இது சரியாக செய்கிறது" என்று மட்டுமே எதிர்பார்க்காமல், உங்கள் தரச்சர்ணைகள் என்ன என்பது (சரி எண்ணிக்கைகள், பிழை கையாளுதல், செயல்திறன், பாதுகாப்பு) தெளிவாக கூறுகின்றீர்கள். பிறகு மாதிரி தன் வெளியீட்டை மதிப்பாய்வு செய்து மேம்படுத்த முடியும். இதனால் குறியீடு உருவாக்கம் ஒரு அதிர்ஷ்டப்போட்டி அல்லாமல் ஒரு செயல்முறையாக மாறும். -**ஒட்டுமொத்தமாக உள்ளடக்கம்** +**சூழல் எல்லை நோக்கியது** -பல முறை உரையாடல்கள் ஒவ்வொரு கோரிக்கையுடனும் செய்தி வரலாற்றை உள்ளடக்கியுள்ளது. ஆனால் எல்லை உண்டு - ஒவ்வொரு மாடலைக்கும் அதிகபட்ச டோக்கன் எண்ணிக்கை உள்ளது. உரையாடல்கள் வளர்ந்துகொண்டோரை, சம்பந்தப்பட்ட உள்ளடக்கத்தை இழக்காமைத்தான் வைத்துக்கொள்ளும் திட்டங்களை நீங்கள் பயன்படுத்த வேண்டும். இந்த மாட்யூல் நீங்கள் நினைவறிய செயல்பாடு எப்படி நடக்கிறது என்பதைத் தந்துள்ளது; பின்னர் எப்போது சுருக்கவும், மறக்கவும், மீண்டும் பெறவும் என்று கற்றுக்கொள்வீர்கள். +பல முறை உரையாடல்கள் முன்னணி செய்தி வரலாறுடன் ஒவ்வொரு கோரிக்கையிலும் வேலை செய்கின்றன. ஆனால் எல்லை உண்டு - ஒவ்வொரு மாதிரிக்கும் அதிகபட்ச டோக்கன் எண்ணிக்கை உள்ளது. உரையாடல் வளரும்போது, பொருத்தமான சூழலை அதன் வரம்பு கடக்காமல் வைத்திருத்தல் முக்கியம். இந்த module நினைவுப் பண்பினை எப்படி செயல்படுத்திறது என்பதை காண்பிக்கும்; பிறகு எப்போது சுருக்கம் செய்ய வேண்டும், எப்போது மறக்க, எப்போது மீட்டெடுக்க வேண்டும் என்பதையும் கற்றுக் கொள்வீர்கள். ## அடுத்த படிகள் -**அடுத்த மாட்யூல்:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) +**அடுத்த Module:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**நெவிகேஷன்:** [← முந்தையது: மாட்யூல் 01 - அறிமுகம்](../01-introduction/README.md) | [முக்கியமானவை] (../README.md) | [அடுத்து: மாட்யூல் 03 - RAG →](../03-rag/README.md) +**நெவிகேஷன்:** [← முந்தையது: Module 01 - அறிமுகம்](../01-introduction/README.md) | [முதன்மைக்கு திரும்பவும்](../README.md) | [அடுத்தது: Module 03 - RAG →](../03-rag/README.md) --- -**வழக்குறிப்பு**: -இந்த ஆவணம் செயற்கை அறிவு மொழிபெயர்ப்பு சேவையான [Co-op Translator](https://github.com/Azure/co-op-translator) மூலம் மொழிபெயர்க்கப்பட்டிருக்கிறது. எங்கள் நோக்கம் துல்லியமாக இருக்கினும், தானியங்கி மொழிபெயர்ப்புகளில் தவறுகள் அல்லது பொருள் பிழைகள் இருக்கலாம் என்பதை தயவுசெய்து கவனத்திற்கு எடுத்துகொள்ளவும். மூல ஆவணம் அதன் தாய்மொழியில் நம்பகமுடைய ஆதாரமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களில் தொழில்முறை மனித மொழிபெயர்ப்பை பரிந்துரைக்கிறோம். இந்த மொழிபெயர்ப்பின் பயன்பாட்டால் ஏற்படும் எந்தவொரு தவறான புரிதல் அல்லது பொருள் தவறுகளுக்கும் நாம் பொறுப்பேற்கமாட்டோம். +**மறுப்பு**: +இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. நாங்கள் துல்லியத்திற்காக முயற்சி செய்துள்ளோம், ஆனால் தானாக செய்யப்படும் மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கலாம் என்பதை கவனத்தில் கொள்ளவும். அசல் ஆவணம் அதன் தாய்மொழியில் அதிகாரப்பூர்வ ஆதாரமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழில்நுட்பமான மனித மொழிபெயர்ப்பு பரிந்துரைக்கப்படுகிறது. இந்த மொழிபெயர்ப்பைப் பயன்படுத்துவதால் ஏற்படும் எந்த தவறான புரிதல்கள் அல்லது தவறான விளக்கத்திற்கும் நாங்கள் பொறுப்பில்வில்லை. \ No newline at end of file diff --git a/translations/ta/03-rag/README.md b/translations/ta/03-rag/README.md index aaa203f38..695bcd8ec 100644 --- a/translations/ta/03-rag/README.md +++ b/translations/ta/03-rag/README.md @@ -1,144 +1,143 @@ -# Module 03: RAG (Retrieval-Augmented Generation) - -## Table of Contents - -- [Video Walkthrough](../../../03-rag) -- [What You'll Learn](../../../03-rag) -- [Prerequisites](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Does This Tutorial Use?](../../../03-rag) -- [How It Works](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload a Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matters](../../../03-rag) -- [Next Steps](../../../03-rag) - -## Video Walkthrough - -இந்த மாட்யூலை ஆரம்பிப்பது எப்படி என்பதை விளக்கும் இந்த நேரடி அமர்வைப் பாருங்கள்: +# Module 03: RAG (தேடல்-அதிகரிக்கப்பட்ட உருவாக்கம்) + +## உள்ளடக்கம் + +- [காணொளி நடைப்பயணம்](#காணொளி-நடைப்பயணம்) +- [நீங்கள் கற்றுக்கொள்ளவிருப்பது](#நீங்கள்-கற்கப்போவது) +- [முன்னிருப்புகள்](#முன்னிருப்புகள்) +- [RAG புரிதல்](#rag-புரிதல்) + - [இந்த கற்கைநெறி எந்த RAG அணுகுமுறையை பயன்படுத்துகிறது?](#இந்த-கற்கைநெறி-எந்த-rag-அணுகுமுறையை-பயன்படுத்துகிறது) +- [இது எப்படி வேலை செய்கிறது](#இது-எப்படி-வேலை-செய்கிறது) + - [ஆவணம் செயலாக்கம்](#ஆவணம்-செயலாக்கம்) + - [எம்பெடிங்குகள் உருவாக்கல்](#எம்பெடிங்குகள்-உருவாக்கல்) + - [அர்த்த நிறைந்த தேடல்](#அர்த்த-நிறைந்த-தேடல்) + - [பதில் உருவாக்கல்](#பதில்-உருவாக்குதல்) +- [அனுப்புக செயலியை](#செயலியை-இயக்கவும்) +- [செயலியை பயன்படுத்துதல்](#செயலியைப்-பயன்படுத்துவது) + - [ஆவணத்தை பதிவேற்றுக](#ஆவணத்தை-பதிவேற்றவும்) + - [கேள்விகள் கேளுங்கள்](#கேள்விகள்-கேட்கவும்) + - [மூல குறிப்புகளைச் சரிபார்க்கவும்](#மூல-குறிப்புகளை-சரிபார்க்கவும்) + - [கேள்விகளுடன் சிறுகாண்க](#கேள்விகளுடன்-முன்னேறவும்) +- [முக்கிய கருத்துகள்](#முக்கியக்-கொள்கைகள்) + - [துண்டு முறை](#துண்டாக்கல்-நெறிமுறை) + - [இன்மையாக்க மதிப்பெண்கள்](#ஒத்துமை-மதிப்பெண்கள்) + - [உட்புகுத்தல் நினைவகம்](#நினைவகத்தில்-சேமிப்பு) + - [சூழல் ஜன்னல் மேலாண்மை](#சூழல்-ஜன்னல்-மேலாண்மை) +- [எப்போ பதிவு முக்கியம்](#rag-முக்கியமான-போது) +- [அடுத்த படிகள்](#அடுத்த-படிகள்) + +## காணொளி நடைப்பயணம் + +இந்த தொகுதியைத் தொடங்க எப்படி என விளக்கும் நேரலை அமர்வு பார்க்கவும்: RAG with LangChain4j - Live Session -## What You'll Learn +## நீங்கள் கற்கப்போவது -முந்தைய மாட்யூல்களில், நீங்கள் AI உடன் உரையாடல்களை நடத்தி உங்கள் ப்ராம்ப்ட்களை சீரமைப்பதற்கு கற்றிருந்தீர்கள். ஆனால் ஒரு அடிப்படை வரம்பு உள்ளது: மொழி மாதிரிகள் பயிற்சியில் கற்றுக்கொண்டதையே மட்டும் அறிவார்கள். அவை உங்கள் நிறுவன கொள்கைகள், உங்கள் திட்ட ஆவணங்கள் அல்லது பயிற்சியில் இல்லாத எந்தத் தகவலுக்கும் பதில் அளிக்க முடியாது. +முந்தைய தொகுதிகளில், AI உடன் உரையாடல்கள் நடத்துவது மற்றும் உங்கள் கேள்வித்தாள் அமைப்பது எப்படி என்பதை கற்றுக்கொண்டீர்கள். ஆனால் ஒரு அடிப்படை குறைவு உள்ளது: மொழி மாதிரிகள் பயிற்சியின் போது கற்றுக்கொண்டதை மட்டுமே தெரிந்து கொள்வதற்கு முடியும். உங்கள் நிறுவன கொள்கைகள், உங்கள் திட்ட ஆவணங்கள் அல்லது பயிற்சி பெறாத எந்த தகவல்களையும் அவை கேள்வி பதில் அளிக்க முடியாது. -RAG (Retrieval-Augmented Generation) இந்த பிரச்சினையை சமாளிக்கிறது. மாதிரிக்கு உங்கள் தகவலை கற்றுக்கொள்ள முயற்சிப்பதைவிட (இதற்கான செலவு மற்றும் செயல்திறன் குறைவு உள்ளது), நீங்கள் அதை உங்கள் ஆவணங்களைத் தேட வைக்கும் திறனை வழங்குகிறீர்கள். யாராவது கேள்வி கேட்கும் போது, சிஸ்டம் தொடர்புடைய தகவலை கண்டுபிடித்து ப்ராம்ப்டில் சேர்க்கிறது. அப்போதுதான் மாதிரி அந்த பெறப்பட்ட சூழலை அடிப்படையாகக் கொண்டு பதில் அளிக்கிறது. +RAG (தேடல்-அதிகரிக்கப்பட்ட உருவாக்கம்) இந்த பிரச்சனைக்கு தீர்வு தருகிறது. மாதிரியை உங்கள் தகவல்களால் கற்றுத்தர முயற்சி செய்வதற்கு பதிலாக (அது விலை மிக உயர்ந்ததும் சாத்தியமற்றதும்), நீங்கள் அதற்கு உங்கள் ஆவணங்களைத் தேடுவதற்கான திறனை கொடுக்கின்றீர்கள். ஒருவரும் கேள்வி கேட்கும்போது, அமைப்பு பொருத்தமான தகவலை தேடி, அதை கேள்வித்தாளில் சேர்க்கிறது. மாதிரி பின்னர் அந்த பெற்ற சூழலில் அடிப்படையாக்கி பதில் அளிக்கிறது. -RAG ஐ மாதிரிக்கு ஒரு குறிப்பு நூலகத்தை வழங்குவதாக நினைத்துக் கொள்ளுங்கள். நீங்கள் ஒரு கேள்வி கேட்கும் போது, சிஸ்டம்: +RAG ஐ மாதிரிக்கு ஒரு குறிப்ப-reference நூலகம் வழங்குவது போல் எண்ணுங்கள். நீங்கள் கேள்வி கேட்கும் போது, அமைப்பு: 1. **பயனர் கேள்வி** - நீங்கள் கேள்வி கேட்கிறீர்கள் -2. **எம்பெடியிங்** - உங்கள் கேள்வியை வெக்டர் ஆக மாற்றுகிறது -3. **வெக்டர் தேடல்** - ஒத்திருக்கும் ஆவண துண்டுகளை நாடுகிறது -4. **சூழல் சேர்தல்** - தொடர்புடைய துண்டுகளை ப்ராம்ப்டுக்கு சேர்க்கிறது -5. **பதில்** - LLM அந்த சூழலை அடிப்படையாகக் கொண்டு பதில் உருவாக்குகிறது +2. **எம்பெடிங்** - உங்கள் கேள்வியை ஒரு வெக்டர் ஆக மாற்றுகிறது +3. **வெக்டர் தேடல்** - ஒத்த ஆவண துண்டுகளை கண்டுபிடிக்கிறது +4. **சூழல் தொகுப்பு** - பொருத்தமான துண்டுகளை கேள்வித்தாளில் சேர்க்கிறது +5. **பதில்** - கட்டுரை வடிவம் (LLM) சூழலை அடிப்படையாகக் கொண்டு பதில் உருவாக்குகிறது -இதன் மூலம் மாதிரி பதில்கள் பயிற்சி அறிவுக்கு அல்லது பொய் பதில்களை உருவாக்குவதற்கு பதிலாக உங்கள் உண்மையான தரவுகளில் நிலை பெறுகின்றன. +இதனால், மாதிரியின் பதில்கள் இதன் பயிற்சி அறிவியல் சார்ந்த பதில்களை பொருத்தமான உங்கள் தரவுகளுக்கு அடிப்படையாகக் கொண்டிருக்கும், உருவாக்கிய பதில்களை அல்ல. -## Prerequisites +## முன்னிருப்புகள் -- [Module 00 - Quick Start](../00-quick-start/README.md) முடித்திருக்க வேண்டும் (இந்த மாட்யூலில் பின்னர் குறிப்பிட்டுள்ள எசி RAG உதாரணத்திற்காக) -- [Module 01 - Introduction](../01-introduction/README.md) முடித்திருக்க வேண்டும் (Azure OpenAI வளங்கள் நியமிக்கப்பட்டவை, `text-embedding-3-small` என்ற எம்பெடியிங் மாதிரியை உட்பட) -- ரூட் டைரக்டரியில் `.env` கோப்பு Azure அங்கீகாரத்துடன் இருக்க வேண்டும் (Module 01 இல் `azd up` மூலம் உருவாக்கப்பட்டது) +- முடிக்கப்பட்டது [Module 01 - அறிமுகம்](../01-introduction/README.md) (Azure OpenAI வளங்கள் துவக்கப்பட்டுள்ளன, இதில் `text-embedding-3-small` எம்பெடிங் மாதிரியும் அடக்கம்) +- ரூட் கோப்பகம் `.env` கோப்புடன் Azure அங்கீகார விவரங்கள் உள்ளன (Module 01 இல் `azd up` மூலம் உருவாக்கப்பட்டது) -> **குறிப்பு:** Module 01 முடிக்கவில்லை என்றால், அங்குள்ள டெப்ளாய்மென்ட் வழிகாட்டுதலை முதலில் பின்பற்றவும். `azd up` கட்டளை GPT அரட்டை மாதிரியையும், இந்த மாட்யூலில் பயன்படுத்தப்படும் எம்பெடியிங் மாதிரியையும் டெப்ளாய் செய்கிறது. +> **குறிப்பு:** Module 01 முடிக்கப்படாதிருந்தால், முதலில் அங்குள்ள நிறுவல் வழிமுறைகளை பின்பற்றவும். `azd up` கட்டளை இந்த தொகுதியில் பயன்படுத்தப்படும் GPT உரையாடல் மாதிரியையும் எம்பெடிங் மாதிரியையும் நிறுவுகிறது. -## Understanding RAG +## RAG புரிதல் -கீழுள்ள வரைபடம் அடிப்படையான கான்செப்டை காட்டுகிறது: மாதிரியின் பயிற்சி தரவை மட்டும் பொறுத்துக் கொள்ளாமல், RAG ஒவ்வொரு பதிலையும் உருவாக்கும் முன் உங்கள் ஆவணங்களில் உள்ள குறிப்பு நூலகத்தை அணுகுவதற்கான வழியை வழங்குகிறது. +கீழ்காணும் வரைபடம் முக்கிய கருத்தை விளக்குகிறது: மாதிரி தனது பயிற்சி தரவுக்கு மட்டுமே நம்பிக்கை வைக்காமல், RAG உங்கள் ஆவணங்களின் குறிப்பு நூலகத்தை வழங்கி, ஒவ்வொரு பதிலும் உருவாக்குவதற்கு முன் அவற்றைப் பரிசீலிக்கிறது. What is RAG -*இந்த வரைபடம் ஒரு நுண்ணறிவு LLM (பயிற்சி தரவிலிருந்து ஊகிக்கிறது) மற்றும் RAG-சேர்க்கப்பட்ட LLM (முதலில் உங்கள் ஆவணங்களை அணுகுகிறது) ஆகிய இரண்டின் வேறுபாட்டை காட்டுகிறது.* +*இந்த வரைபடம் வழக்கமான LLM (பயிற்சி தரவிலிருந்து ஊகிக்கிறது) மற்றும் RAG மேம்படுத்தப்பட்ட LLM (முதலில் உங்கள் ஆவணங்களை பரிசீலிக்கிறது) இடையேயான வேறுபாட்டை காட்டுகிறது.* -இங்கே உள்ள கூறுகள் எவ்வாறு தொடர் முறையில் இணைகின்றன: ஒரு பயனரின் கேள்வி நான்கு படிகளுக்கு செல்கிறது — எம்பெடியிங், வெக்டர் தேடல், சூழல் சேர்தல், பதில் உருவாக்கம் — ஒவ்வொன்றும் முந்தைய ஒரு அடிப்படையில்: +பயனர் கேள்வி நான்கு படிகளுள் கடந்து செல்லும் விதம் இங்கே. எம்பெடிங், வெக்டர் தேடல், சூழல் தொகுப்பு மற்றும் பதில் உருவாக்கல் போன்றவை — ஒவ்வொன்றும் முன்னடடியின் அடிப்படையில் உருவாக்கப்படுகின்றன: RAG Architecture -*இந்த வரைபடம் முழுமையான RAG குழாய்துறையை காட்டுகிறது — பயனர் கேள்வி எம்பெடியிங், வெக்டர் தேடல், சூழல் சேர்தல், பதில் உருவாக்கம் ஆகியவற்றை கடக்கிறது.* +*இந்த வரைபடம் RAG குழாயமைப்பை முழுமையாக காட்டுகிறது — பயனர் கேள்வி எம்பெடிங், வெக்டர் தேடல், சூழல் தொகுப்பு மற்றும் பதில் உருவாக்கல் வழியாக ஓடுகிறது.* -இந்த மாட்யூல் ஒவ்வொரு படியையும் விரிவாக குறியீடு மற்றும் மாற்றி இயக்குவதை அறிவுரை செய்கிறது. +இந்த தொகுதியின் மீதமுள்ள பகுதி ஒவ்வொரு நிலையையும் விரிவாக செல்கிறார், நீங்கள் இயக்கு மற்றும் மாற்றக்கூடிய குறியீடு உடன். -### Which RAG Approach Does This Tutorial Use? +### இந்த கற்கைநெறி எந்த RAG அணுகுமுறையை பயன்படுத்துகிறது? -LangChain4j RAG ஐ செயல்படுத்த மூன்று விதங்கள் வழங்குகிறது, ஒவ்வொன்றும் வேறு விவரத் தன்மையுடன். கீழுள்ள வரைபடம் அவற்றை ஒப்பிடுகிறது: +LangChain4j மூன்று விதங்களில் RAG செயல்படுத்த கூறுகிறது, ஒவ்வொன்றும் வேறுபோன்ற அடிப்படைகூறுகளுடன். கீழ்காணும் வரைபடம் அவற்றை ஒப்பிடுகிறது: Three RAG Approaches in LangChain4j -*இந்த வரைபடம் LangChain4j இன் மூன்று RAG அணுகுமுறைகளை — எசி, நேடிவ், மற்றும் உயர் நிலை — முக்கிய கூறுகளுடன் ஒப்பிடுகிறது தொடர்புடைய முறையில்.* +*இந்த வரைபடம் மூன்று LangChain4j RAG அணுகுமுறைகள் — எளிய, நாட்டிவ் மற்றும் மேம்பட்ட — அவற்றின் முக்கிய கூறுகளை மற்றும் எப்போது பயன்படுத்துவது என்பதையும் காட்டுகிறது.* -| அணுகுமுறை | அதை செய்யும் செயல் | விலைபோக்கு | +| அணுகுமுறை | அது என்ன செய்கிறது | வெகுஜன திருப்பம் | |---|---|---| -| **எசி RAG** | அனைத்தையும் தானாகவே `AiServices` மற்றும் `ContentRetriever` மூலம் கையாள்கிறது. ஒரு இடைமுகத்தை குறிக்கவும், ஒரு ரீட்ரைவரை இணைக்கவும், LangChain4j பின்னணியில் எம்பெடியிங், தேடல், ப்ராம்ப்ட் தொகுப்பை கையாள்கிறது. | குறைந்த குறியீடு, ஆனால் ஒவ்வொரு படியும் என்ன நடக்கிறது என்பது தெரியாது. | -| **நேடிவ் RAG** | நீங்கள் எம்பெடியிங் மாதிரியை அழைக்கவும், அங்கிரக தூணிலிருந்து தேடவும், ப்ராம்ப்டை உருவாக்கவும், பதிலை உருவாக்கவும் செய்யும் போது ஒவ்வொரு படியும் தெளிவாகவும் தனித்தனியாகவும் செயல்படுதல். | குறியாக்கம் அதிகம், ஆனால் ஒவ்வொரு படியும் தெளிவாகவும் மாற்றத்தக்கதும் உள்ளது. | -| **உயர் நிலை RAG** | `RetrievalAugmentor` கட்டமைப்பைப் பயன்படுத்தி கேள்வி மாற்றிகள், ரூட்டர்கள், மறுபதிப்பீட்டாளர்கள், மற்றும் உள்ளடக்க செலுத்திகளுடன் தயாரிப்பு நிலை குழாய்களுக்காக. | அதிக திடீர் மற்றும் தூய்மையான விடுப்பு, ஆனால் கூடுதலான சிக்கலும் இருக்கிறது. | +| **எளிய RAG** | அனைத்தையும் தானாகவே `AiServices` மற்றும் `ContentRetriever` வழியாக இணைக்கிறது. நீங்கள் ஒரு இடைமுகத்தை குறிப்பிட்டு, ஒரு திருப்தியை இணைக்கிறீர்கள், LangChain4j பின்னணியில் எம்பெடிங், தேடல் மற்றும் கேள்வித் தொகுப்பை கையாள்கிறது. | குறைந்த குறியீடு, ஆனால் ஒவ்வொரு படியும் என்ன நடக்கிறது என்பது தெரியாது. | +| **நாட்டிவ் RAG** | நீங்கள் எம்பெடிங் மாதிரியை அழைக்கிறீர்கள், சேமிப்பகத்தில் தேடல் செய்கிறீர்கள், கேள்வியை கட்டமைக்கிறீர்கள், பதிலை உங்களால் தெளிவாக ஒரு படியாக உருவாக்குகிறீர்கள். | அதிக குறியீடு, ஆனால் ஒவ்வொரு படியும் தெளிவாக மற்றும் மாற்றக்கூடியதாக இருக்கும். | +| **மேம்பட்ட RAG** | `RetrievalAugmentor` கட்டமைப்பைப் பயன்படுத்தி, கேள்வி மாற்றிகள், வழிசெலுத்திகள், மறுஅதிகாரிகள் மற்றும் உள்ளடக்கம் ஊட்டிகள் போன்ற காணொளிகள் பயன்படுத்தி தொழிற்பயிற்சி குழாய் அமைப்புகளுக்கு. | மிக அதிக சிக்கனம் மற்றும் அளவு வழுவிலக்கு உள்ளது. | -**இந்த பயிற்சி நேடிவ் அணுகுமுறையைப் பயன்படுத்துகிறது.** RAG குழாயின் ஒவ்வொரு படியையும் — கேள்வியை எம்பெடியிங் செய்தல், வெக்டர் அங்க்ஷையை தேடல், சூழலை ஒன்றிணைத்து பதில் உருவாக்குதல் — [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) இல் தெளிவாக எழுதப்பட்டுள்ளது. இது ஒரு கற்றல் வளமாகும்: குறியீடு குறைவு அல்லாமல் ஒவ்வொரு படியும் தெளிவாக புரிந்து கொள்ளும் பொருட்டு. கூறுகள் எப்படி இணைகின்றன என்பதை புரிந்துகொண்ட பிறகு, எசி RAG உடன் விரைவு முன்மாதிரிகள் அல்லது உயர் நிலை RAG உடன் தயாரிப்பு சிஸ்டம்கள் உருவாக்கலாம். +**இந்த கற்கைநெறி நாட்டிவ் அணுகுமுறையை பயன்படுத்துகிறது.** RAG குழாய் ஒவ்வொரு நிலையும் — கேள்வி எம்பெடிங், வெக்டர் சேமிப்பகத்தில் தேடல், சூழலை சீர்செய்தல் மற்றும் பதில் உருவாக்கல் — [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) இல் தெளிவாக எழுதப்பட்டிருக்கிறது. இது意図மாக: கற்றலில் முக்கியம் ஒவ்வொரு படியும் தெளிவாக கண்டு புரிந்து கொள்ள வேண்டும் என்பது குறைந்த குறியீடுமைக்கும் மேல். நீங்கள் இவற்றின் ஒத்துழைப்பை அறிந்த பிறகு, எளிய RAG தயாரிப்பு மாதிரிகள் அல்லது மேம்பட்ட RAG தொழிற்பயிற்சி அமைப்புகளுக்கு மாறலாம். -> **💡 எசி RAG ஐ ஏற்கனவே பார்த்தீர்களா?** [Quick Start மாட்யூல்](../00-quick-start/README.md) ஒரு ஆவண கேள்வி-பதில் உதாரணத்தை கொண்டுள்ளது ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) எசி RAG அணுகுமுறையைப் பயன்படுத்துகிறது — LangChain4j தானாகவே எம்பெடியிங், தேடல் மற்றும் ப்ராம்ப்ட் தொகுப்பை கையாள்கிறது. இந்த மாட்யூல் அந்த குழாயை திறந்து, ஒவ்வொரு படியையும் உங்களால் பார்க்க மற்றும் கட்டுப்படுத்த முடியும். +> **💡 எளிய RAG பற்றி ஆர்வமா?** LangChain4j *எளிய RAG* அணுகுமுறையும் வழங்குகிறது, இங்கு `AiServices` மற்றும் `ContentRetriever` தானாகவே எம்பெடிங், தேடல் மற்றும் கேள்வி தொகுப்பு செய்கின்றன. இந்த தொகுதி அதிக தெளிவான பாதையை எடுத்துள்ளது — குழாய் திறந்து ஒழுங்குபடுத்தலுக்கு ஒவ்வொரு படியும் உங்களால் பார்க்கவும் கட்டுப்படுத்தவும். -கீழுள்ள வரைபடம் அந்த எசி RAG குழாயை காட்டுகிறது. `AiServices` மற்றும் `EmbeddingStoreContentRetriever` எல்லா சிக்கல்களையும் மறைக்கும் — நீங்கள் ஆவணத்தை ஏற்றிக், ரீட்ரைவரை இணைத்து பதில்களை பெறுவீர்கள். இந்த மாட்யூல் இருப்பிடத்தின் ஒவ்வொரு படியையும் நேரடியாக அழைக்கும்படி வேறாக்குகிறது: +கீழ்காணும் வரைபடம் எளிய RAG குழாயை காட்டுகிறது. `AiServices` மற்றும் `EmbeddingStoreContentRetriever` எல்லா சிக்கல்களையும் மறைக்கின்றன — ஆவணத்தை ஏற்றவும், ஒரு திருப்தியைச் சேர்க்கவும், பதில்கள் பெறலாம். இந்த தொகுதியின் நாட்டிவ் அணுகுமுறை அந்த மறைந்த கட்டைகளை திறக்கிறது: Easy RAG Pipeline - LangChain4j -*இந்த வரைபடம் `SimpleReaderDemo.java` இன் எசி RAG குழாயை காட்டுகிறது. இந்த மாட்யூல் பயன்படுத்தும் நேடிவ் அணுகுமுறையுடன் ஒப்பிடுக: எசி RAG எம்பெடியிங், திரும்பப்பெறும் மற்றும் ப்ராம்ப்ட் தொகுப்பை `AiServices` மற்றும் `ContentRetriever` மூலமாக மறைக்கிறது — நீங்கள் ஆவணத்தை ஏற்று, ரீட்ரைவரை இணைத்து, பதில்களைப் பெறுவீர்கள். இந்த மாட்யூல் அந்த குழாயை திறந்து, ஒவ்வொரு படியையும் நீங்கள் அழைக்கவும் கட்டுப்படுத்தவும் அனுமதிக்கிறது.* +*இந்த வரைபடம் எளிய RAG குழாயை காட்டுகிறது. நாட்டிவ் அணுகுமுறையை ஒப்பிடுக: எளிய RAG `AiServices` மற்றும் `ContentRetriever` அடித்து எம்பெடிங், தேடல் மற்றும் கேள்வி தொகுப்பை மறைக்கிறது — நீங்கள் ஆவணத்தை ஏற்றியும், திருப்தியைச் சேர்க்கவும், பதிலை பெறலாம். நாட்டிவ் அணுகுமுறை அந்த குழாயை திறந்து ஒவ்வொரு படியையும் (எம்பெட், தேடு, சூழலை தொகுக்க, உருவாக்க) நீங்கள் அழைக்கிறீர்கள், முழு பார்வையும் கட்டுப்பாட்டையும் வழங்குகிறது.* -## How It Works +## இது எப்படி வேலை செய்கிறது -இந்த மாட்யூலில் உள்ள RAG குழாய், பயனருக்குப் பிரச்சனை கேட்கும் வேளையில் ஒவ்வொரு முறையும் தொடர்ச்சியாக இயங்கும் நான்கு படிகளாக பிரிக்கப்படுகிறது. முதலில், ஏற்றுமதி செய்யப்பட்ட ஆவணம் **பகுக்கப்பட்டு துண்டாக்கப்படுகிறது**. அவை பிறகு **வெக்டர் எம்பெடியிங்களாக** மாறி சேமிக்கப்படுகின்றன, அவை கணித ரீதியாக ஒப்பிடப்படக்கூடும். ஒரு கேள்வி வந்தபோது, சிஸ்டம் மிக தொடர்புடைய துண்டுகளை மட்டும் கண்டுபிடிக்க **உள்ளார்ந்த தேடலை** செயல்படுத்துகிறது, மற்றும் கடைசியாக அவை LLM க்கு **பதில் உருவாக்குவதற்கான** சூழல் ஆக வழங்கப்படுகின்றன. கீழே ஒவ்வொரு படியையும் சம்மந்தமான குறியீடு மற்றும் வரைபடங்கள் மூலம் எடுத்துரைக்கப்பட்டது. முதலில் முதலாவது படியைப் பார்ப்போம். +இந்த தொகுதியில் RAG குழாய் ஒவ்வொரு முறையும் பயனர் கேள்வி கேட்கும் போது வரிசையாக இயக்கப்படும் நான்கு படிகளாக பிரிக்கப்படுகிறது. முதலில், பதிவேற்றிய ஆவணம் **பகுதிகள்** ஆக **வெளியிடப்படுகிறது** மற்றும் சுலபமாக கையாளும் துண்டுகளாக பிரிக்கப்படுகிறது. அந்த துண்டுகள் பிறகு **வெக்டர் எம்பெடிங்குகளாக** மாற்றப்பட்டு, கணித ரீதியாக ஒப்பிடும் படி சேமிக்கப்படுகின்றன. ஒரு கேள்வி வந்தால், அமைப்பு பொருத்தமான துண்டுகளை கண்டுபிடிக்க ஒரு **அர்த்த நிறைந்த தேடல்** நடத்துகிறது மற்றும் இறுதியில் அந்த துண்டுகளை LLMக்கு **பதில் உருவாக்க** சூழலாக வழங்குகிறது. கீழே ஒவ்வொரு நிலையும் குறியீடு மற்றும் வரைபடங்களுடன் வழிநடத்தப்படுகின்றன. முதல் படிக்கு பார்ப்போம். -### Document Processing +### ஆவணம் செயலாக்கம் [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -நீங்கள் ஒரு ஆவணத்தை ஏற்றும் போது, சிஸ்டம் அதை (PDF அல்லது தெருவுரை) பகுக்கிறது, கோப்பு பெயர் போன்ற மெட்டா தரவுகளை மீண்டும் இணைக்கிறது, பின்னர் அதை சிறிய துண்டுகளாக பிரிக்கிறது — மாதிரியின் சூழலை நேர்த்தியான முறையில் இயங்க உகந்த அளவு குலைப்புக் கொண்ட துண்டுகள். இந்த துண்டுகள் வெவ்வேறு பகுதி இடைவெளிகளில் சிறிது பகிர்ந்துகொள்ளப்படுகின்றன, இதனால் (சூழல்) எல்லைகளை இழக்காமல் பாதுகாக்கப்படுகிறது. +நீங்கள் ஆவணத்தை பதிவேற்றும் போது, அமைப்பு அதை (PDF அல்லது உரை) பிரிக்கிறது, கோப்பு பெயர் போன்ற மெட்டாடேட்டாவை இணைக்கிறது, பிறகு அதை துண்டுகளுக்கு உடைக்கிறது — மாதிரியின் சூழல் ஜன்னலுக்கு ஏற்ற சிறிய துண்டுகள். அவை எல்லாமே குறைந்த அளவு ஒவ்வொன்றுக்கு ஓவர்லாப் இருக்கின்றன, அதனால் எல்லா சூழலும் எல்லைகளில் கெடாது. ```java -// பதிவேற்றப்பட்ட கோப்பை பகுப்பாய்வு செய்து LangChain4j ஆவணமாக மூடியிடுக +// பதிவேற்றிய கோப்பை பார்ஸ் செய்து LangChain4j ஆவணமாக об.wrap செய்யவும் Document document = Document.from(content, metadata); -// 30-டோக்கன் ஓவர்லாப்புடன் 300-டோக்கன் துண்டுகளாக பிரிக்கவும் +// 30-டோக்கன் ஒட்டுமொத்தத்தை உட்பட 300-டோக்கன் துண்டுகளாக பிரிக்கவும் DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -கீழுள்ள வரைபடம் இதை விசுவல் முறையில் காட்டுகிறது. ஒவ்வொரு துண்டும் அதன் அண்டை துண்டுகளுடன் சில குறியீடுகளை பகிர்ந்து கொள்ளும் என்பதை கவனிக்கவும் — 30 குறியீடு பகிர்வு எதிர்காலத்தில் எந்த முக்கிய சூழலும் இழக்கப்படாமல் அதை உறுதி செய்கிறது: +கீழ்காணும் வரைபடம் இதைப் பார்வையாளர்களுக்காக காட்டுகிறது. ஒவ்வொரு துண்டும் அதன் அம்பிக்கட்டத்துடன் சில டோக்கன்களை பகிர்கிறது — 30-டோக்கன் ஓவர்லாப் எந்த முக்கிய சூழலும் இடைவெளியில் இருப்பதை தவிர்க்கிறது: Document Chunking -*இந்த வரைபடம் ஒரு ஆவணத்தை 300 குறியீடு குலைகளாக 30 குறியீடு பகிர்வுடன் பிரிப்பதை மற்றும் பகுதி எல்லைகளில் சூழலை பாதுகாப்பதை காட்டுகிறது.* +*இந்த வரைபடம் ஆவணத்தை 300-டோக்கன் துண்டுக்களாக பிரித்து, 30-டோக்கன் தளர்வுடன், துண்டுகளின் எல்லைகளில் சூழலை பாதுகாக்கிறது.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) அரட்டையுடன் முயற்சிக்கவும்:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) திறந்து கேட்கவும்: -> - "LangChain4j ஆவணங்களைத் துண்டுகளாக எப்படிப்பட்ட முறையில் பிரிக்கிறது மற்றும் பகிர்வு ஏன் முக்கியம்?" -> - "விவேகமான ஆவண வகைகளுக்கான சிறந்த துண்டு அளவு எது மற்றும் ஏன்?" -> - "பல மொழிகளில் உள்ள ஆவணங்கள் அல்லது சிறப்பு வடிவமைப்புகளுடன் எப்படி கையாளவேண்டும்?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) உரையாடலுடன் முயற்சிக்கவும்:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) திறந்து கேளுங்கள்: +> - "LangChain4j ஆவணங்களை துண்டுகளாக்கும் முறையும் ஓவர்லாப் முக்கியத்துவமும் என்ன?" +> - "விதிவகை ஆவணங்களுக்கு சிறந்த துண்டு அளவு என்ன மற்றும் ஏன்?" +> - "பல மொழிகளிலும் சிறப்பு வடிவமைப்பும் உள்ள ஆவணங்களை எப்படி கையாள்வது?" -### Creating Embeddings +### எம்பெடிங்குகள் உருவாக்கல் [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -ஒவ்வொரு துண்டும் எம்பெடியிங் என்ற எண்ணுக்கூறு பிரதிநிதித்துவமாக மாற்றப்படுகிறது — இது அதற்கு பொருள் விளக்கமாகும். எம்பெடியிங் மாதிரி அரட்டை மாதிரி போல "நுண்ணறிவு" இல்லை; கட்டளைகளை பின்பற்றவும், காரணமாக்கவும், பதில்களைக் கூறவும் முடியாது. அஞ்சு செய்யும் விஷயம், அது உரையை ஒரு கணிதப் பரப்பிற்கு மாற்றுவதாகும், அதில் சமான பொருள்கள் ஒன்றுக்கு அருகில் இருக்கும் — "கார்" மிகவும் "வாகனம்" அருகில், "பணத்தை திரும்பப் பெறுதல் கொள்கை" மிகவும் "இணைய பணத்தை திரும்பப் பெறுதல்" அருகில். ஒருவருடன் பேசும் அரட்டை மாதிரியாக எண்ணினால், எம்பெடியிங் மாதிரி ஒரு மிகச்சிறந்த கோப்பு முறையாகும். +ஒவ்வொரு துண்டும் ஒரு எண் வடிவமான பிரதிநிதித்துவமாக மாற்றப்படுகிறது, இதை எம்பெடிங் कहते हैं — மூலம் உரையின் பொருள் எண்களில் மாறும் மலிவு சிக்கலி. எம்பெடிங் மாதிரி உரையாடல் மாதிரி போல் "அறிவு வாய்ந்த" இல்லை; அது கட்டளைகள், துணையற்ற கருத்துக்கள் அல்லது கேள்விக்கு பதில் தருவதில்லை. ஆனால் அது உரையை கணித அமைப்புக்கு மாற்றுகிறது, நல்ல பொருள் சார்ந்த உரைகள் ஒன்றுக்கொன்று அருகில் இருக்கும் — "கார்" என்ற சொல்லுகோ "மோட்டார்" என்பதற்கு அருகிலிருக்கிறது, "திருப்பி கொடுக்கும் கொள்கை" என்ற சொல்லும் "பணம் திருப்பி பெறுதல்" என்பதற்கு அருகில் இருக்கும். உரையாடல் மாதிரி ஒருவரைப் போல பேசக்கூடியவர், எம்பெடிங் மாதிரி ஆம் ஒரு மிகச் சிறந்த சேமிப்பு முறை. -கீழுள்ள வரைபடம் இந்த கருத்தை காட்டுகிறது — உரை உள்ளே, எண்ணியல் வெக்டர்கள் வெளியே; இணையான பொருள்கள் மிக அருகிலுள்ள வெக்டர்களை உருவாக்குகின்றன: +கீழ்காணும் வரைபடம் இந்த கருத்தை காண்பிக்கிறது — உரை உள்ளே செல்கிறது, எண்வெக்டர்கள் வெளியே வருகிறார்கள், ஒத்த பொருள்கள் அருகே இருக்கும்: Embedding Model Concept -*இந்த வரைபடம் எம்பெடியிங் மாதிரி உரையை எண்ணியல் வெக்டர்களாக மாற்றுவது மற்றும் அதில் "கார்" மற்றும் "வாகனம்" போன்ற இணையான பொருள்களை வெக்டர் இடத்தில் அருகில் வைக்கிறது.* +*இந்த வரைபடம் எம்பெடிங் மாதிரி உரையை எண வெக்டர்களாக்கும் படத்தை காட்டுகிறது, "கார்" மற்றும் "மோட்டார்" போன்ற ஒத்த பொருள்களை அருகில் வைக்கிறது.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -கிளாஸ் வரைபடம் RAG குழாயில் இரண்டு தனித்தனியான பாய்முறைகளையும் மற்றும் அவற்றை செயல்படுத்தும் LangChain4j கிளாஸ்களையும் காட்டுகிறது. **எண்கொள்ளும் பாய்முறை** (ஏற்றுமதி செய்யும் போது ஒருமுறை இயங்கும்) ஆவணத்தை துண்டுகள로 பிரித்து, அந்த துண்டுகளை எம்பெடியிங் செய்து `.addAll()` மூலம் சேமிக்கிறது. **கேள்வி பாய்முறை** (ஒவ்வொரு முறையும் பயனரே கேள்வி கேட்கும் போது இயங்கும்) கேள்வியை எம்பெடியிங் செய்து, `.search()` மூலம் தேடிக், பொருந்தக்கூடிய சூழலை அரட்டை மாதிரிக்கு தருகிறது. இரண்டும் `EmbeddingStore` இடைமுகத்தில் இணைக்கப்பட்டுள்ளது: +கடற்படம் கீழே ஒரு RAG குழாயில் இரு தனி வாய்ப்புகளையும் LangChain4j வகைகளை காட்டுகிறது. **உள்ளீடு பாசம்** (பதிவேற்றும் போது ஒருமுறை இயங்கும்) ஆவணத்தை பிரித்து துண்டுகளை எம்பெட் செய்து `.addAll()` மூலம் சேமிக்கிறது. **கேள்வி பாசம்** (ஒவ்வொரு முறையும் பயனர் கேள்வி கேட்கும் போது) கேள்வியை எம்பெட் செய்து `.search()` மூலம் தேடல் செய்து, பொருந்திய சூழலை உரையாடல் மாதிரிக்கு அனுப்புகிறது. இரண்டும் பொதுவான `EmbeddingStore` இடைமுகத்தில் கூடியுள்ளன: LangChain4j RAG Classes -*இந்த வரைபடம் RAG குழாயில் உள்ள இரண்டு பாய்முறைகள் — எண்கொள் மற்றும் கேள்வி — மற்றும் அவை ஒரே EmbeddingStore மூலம் எவ்வாறு இணைக்கப்படுகின்றன என்பதை காட்டுகிறது.* +*இந்த வரைபடம் RAG குழாயின் இரண்டு வாய்ப்புகளை காண்பிக்கிறது — உள்ளீடு மற்றும் கேள்வி — அவைகள் பொதுவான EmbeddingStore வழியாக இணைக்கப்படுகின்றன.* -எம்பெடியிங் சேமிக்கப்பட்ட பிறகு, இணையான உள்ளடக்கம் குரூப்பாக ஆடைந்துவிடும். கீழுள்ள விசுவல் ஆவணங்கள் தொடர்புடைய பிரிவுகளை அருகிலுள்ள புள்ளிகளாக 3D வெக்டர் இடத்தில் நிரம்பியுள்ளன, இது உள்ளார்ந்த தேடலை சாத்தியமாக்குகிறது: +எம்பெடிங்குகள் சேமிக்கப்பட்ட பிறகு, சம்பந்தப்பட்ட உள்ளடக்கம் வெக்டர் இடத்தில் இயல்பாக கூட்டாகத் தொகுப்பாகிறது. கீழ்காணும் காட்சி சம்பந்தப்பட்ட ஆவணங்கள் பணிவீச்சு வட்டாரத்தில் அருகிலிருந்து இருப்பதை காட்டுகிறது: Vector Embeddings Space -*இந்த விசுவலேஷன் தொடர்புடைய ஆவணங்கள் தொடர்பான குறிப்புகள் (பாவனைகளில், வணிகக் கொள்கைகளை, அடிக்கடி கேட்கப்படும் கேள்விகளைக் போன்றவை) வெக்டர் இடத்தில் தனித்தனியாக குழுக்களாக இருப்பதை காட்டுகிறது.* +*இந்த காட்சி 3D வெக்டர் இடத்தில் தொடர்புடைய ஆவணங்களின் கூட்டமைப்பை காண்பிக்கிறது, தொழில்நுட்ப ஆவணங்கள், வணிக விதிகள் மற்றும்FAQகள் தனித்துப் பகுதிகளாக இணைக்கப்பட்டுள்ளன.* -பயனர் தேடும் போது, சிஸ்டம் நான்குப் படிகளை பின்பற்றுகிறது: ஆவணங்களை ஒருமுறை எம்பெடியிங் செய்கிறது, ஒவ்வொரு தேடும் நேரமும் கேள்வியை எம்பெடியிங் செய்கிறது, கேள்வி வெக்டரை அனைத்து சேமிக்கப்பட்ட வெக்டர்களுடன் கோசைன் ஒத்திசைவை அளவில் ஒப்பிடுகிறது, மேலும் அதிக மதிப்பெண்களுக்குள் உள்ள சிறந்த-K துண்டுகளைத் திருப்பி அளிக்கிறது. கீழுள்ள வரைபடம் ஒவ்வொரு படியையும் மற்றும் LangChain4j கிளாஸ்களையும் காட்டுகிறது: +பயனர் தேடும் போது, அமைப்பு நான்கு படிகள்: ஆவணங்களை ஒருமுறை எம்பெட் செய்கிறது, ஒவ்வொரு தேடலுக்கும் கேள்வியை எம்பெட் செய்கிறது, கேள்வி வெக்டரை சேமிக்கப்பட்ட வெக்டர்களுடன் கோசைன் சமானத்துவம் மூலம் ஒப்பிடுகிறது, மற்றும் மிகச் சிறந்த K துண்டுகளை தருகிறது. கீழ்காணும் வரைபடம் ஒவ்வொரு படியும் மற்றும் LangChain4j வகைகளையும் காட்டுகிறது: Embedding Search Steps -*இந்த வரைபடம் நான்கு படி எம்பெடியிங் தேடல் செயல்முறையை காட்டுகிறது: ஆவணங்களை எம்பெடியிங் செய்தல், கேள்வியை எம்பெடியிங் செய்தல், கோசைன் ஒத்திசைவு பயன்படுத்து வெக்டர்களை ஒப்பிடுதல், மற்றும் உச்ச மதிப்புள்ள முடிவுகள்.* +*இந்த வரைபடம் நான்கு படி எம்பெடிங் தேடல் செயல்முறையை காண்பிக்கிறது: ஆவணங்களை எம்பெட் செய்தல், கேள்வியை எம்பெட்டு, கோசைன் சமானத்துவத்துடன் வெக்டர்களை ஒப்பிடுதல், சிறந்த K முடிவுகளை வழங்குதல்.* -### Semantic Search +### அர்த்த நிறைந்த தேடல் [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -நீங்கள் ஒரு கேள்வி கேட்டாலே, அந்த கேள்வியும் ஒரு எம்பெடியிங்காக மாறுகிறது. சிஸ்டம் உங்கள் கேள்வியின் எம்பெடியிங் மற்றும் ஆவண துண்டுகளின் எம்பெடியிங்குகளுடன் ஒப்பிடுகிறது. முக்கியமான பொருள் அதே நண்பர்களை மட்டும் தேடுகிறது - வெறும் இணையான முக்கியசொற்கள் மட்டுமல்ல, உண்மையான உள்ளார்ந்த ஒத்திசைவு கொண்டவை. +நீங்கள் கேள்வி கேட்டால், உங்கள் கேள்வியும் எம்பெடிங் ஆகிறது. அமைப்பு உங்கள் கேள்வியின் எம்பெடிங்கை அனைத்து ஆவண துண்டுகளுடைய எம்பெடிங்குகளுடன் ஒப்பிடுகிறது. மிக ஒத்த பொருள் கொண்ட துண்டுகளை கண்டுபிடிக்கிறது - பொருளின் பூர்வமாக சில வார்த்தைகள் இல்லை என்றாலும். ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -கீழுள்ள வரைபடம் உள்ளார்ந்த தேடலை எடுத்துக்காட்டுகிறது. "வாகனம்" என்பதற்கான ஒரு முக்கியச்சொல் தேடல் "கார்கள் மற்றும் டிரக்குகள்" பற்றி உள்ள துண்டை காணாமல் விடுகிறது, ஆனால் உள்ளார்ந்த தேடல் அதற்குரிய பொருள் ஒன்றையே பொருள் படுத்தி அதை உயர்ந்த மதிப்புடன் திருப்பிச் செலுத்துகிறது: +கீழ்காணும் வரைபடம் அர்த்த நிறைந்த தேடலை பாரம்பரிய முக்கிய சொல் தேடலுடன் ஒப்பிடுகிறது. "வாகனம்" என்ற முக்கியச் சொல் தேடல் "கார்கள் மற்றும் லாரிகள்" பற்றிய துண்டை தவறவிடும், ஆனால் அர்த்த நிறைந்த தேடல் அவை அதே பொருள் என்பதைக் கண்டு அதை அதிக மதிப்பெண் கொண்டு தருகிறது: Semantic Search -*இந்த வரைபடம் முக்கியச்சொல் அடிப்படையிலான தேடலை உள்ளார்ந்த தேடலுடன் ஒப்பிட்டு காட்டுகிறது, மேலும் உள்ளார்ந்த தேடல் சரியான முக்கியச்சொற்கள் இல்லாதபோதிலும் பொருத்தமான உள்ளடக்கத்தை மீட்டெடுக்கிறது.* -உள் நோக்கில், ஒத்திசைவு கோசைன் ஒத்திசைவைக் கொண்டு அளக்கப்படுகிறது — அடிப்படையாக "இந்த இரண்டு அம்புகள் ஒரே திசை நோக்குகின்றனவா?" என்று கேட்கிறது. இரண்டு பகுதியும் முற்றிலும் வேறுபட்ட சொற்களைப் பயன்படுத்தலாம், ஆனால் அவை ஒரே பொருளைக் குறிக்குமானால், அவற்றின் வெக்டர்கள் ஒரே வழியில் நோக்கி, மதிப்பு 1.0க்கு அருகில் இருக்கும்: +*இந்த வரைபடம் முக்கியச் சொல் தேடல் மற்றும் அர்த்த நிறைந்த தேடலை ஒப்பிட்டு காட்டுகிறது, இதனால் அர்த்த நிறைந்த தேடல் பொருளுற்ற பெயர்களுடன் கூட உள்ளடக்கத்தை மீட்டெடுக்கிறது.* -கோசைன் ஒத்திசைவு +உதயத்தில், இணைமையீடு கோசைன் சமானத்துவத்தை பயன்படுத்தி அளவிடப்படுகிறது — இது "இரு அம்புகள் ஒரே திசையில் இருக்கிறதா?" என்பதை கேட்கிறது. இரண்டு துண்டுகள் வெவ்வேறு வார்த்தைகளைப் பயன்படுத்தினாலும், அவை ஒரே பொருள் கொண்டால் அவற்றின் வெக்டர்கள் ஒரே திசையில் காட்டு கருதி மதிப்பெண் 1.0க்கு அருகில் இருக்கும்: -*இந்த படக்காட்சி எம்பெட்டிங் வெக்டர்களுக்கிடையேயான கோசைன் ஒத்திசைவின் கோணத்தை விளக்குகிறது — மேலும் ஒருங்கிணைக்கப்பட்ட வெக்டர்கள் 1.0க்கு அருகிலான மதிப்பைப் பெறும், இது பொருள் சார்ந்த உயர்ந்த ஒத்திசைவை குறிக்கிறது.* +Cosine Similarity +*இந்த வரைபடம் கோசைன் ஒத்துமையை உருவாக்கும் வெக்டார்கள் இடையேயான கோணமாக விளக்குகிறது — மேலும் ஒத்துப்போகும் வெக்டார்கள் 1.0க்கு நெருக்கமான மதிப்பை பெறுகின்றன, இது அதிகமான அர்த்தம் ஒத்துமையை குறிக்கிறது.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) உரையாடலுடன் முயற்சிக்கவும்:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) திறந்து கேளுங்கள்: -> - "எம்பெட்டிங்களுடன் ஒத்திசைவு தேடல் எப்படி வேலை செய்கிறது மற்றும் மதிப்பை எப்படி நிர்ணயிக்கிறது?" -> - "எந்த ஒத்திசைவு சேதத்தினைப் பயன்படுத்த வேண்டும் மற்றும் அது முடிவுகளை எப்படி பாதிக்கிறது?" -> - "பொருத்தமான ஆவணங்கள் எப்படிச் சேர்ந்தவை இல்லை என்பதைக் கையாள எப்படி?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat கொண்டு முயற்சிக்கவும்:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) கோப்பை திறக்கவும் மற்றும் கேளுங்கள்: +> - "எம்பெட்டிங் களை கொண்டு ஒத்துமை தேடல் எப்படி செயல்படுகிறது மற்றும் மதிப்பெண் என்னவால் நிர்ணயிக்கப்படுகிறது?" +> - "எந்த ஒத்துமை எல்லையை பயன்படுத்த வேண்டும் மற்றும் அது முடிவுகளை எவ்வாறு பாதிக்கிறது?" +> - "பொருத்தமான ஆவணங்கள் கிடைக்காத நிலைகளை எப்படி கையாள வேண்டும்?" -### பதில் உருவாக்கல் +### பதில் உருவாக்குதல் [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -அதிக பொருத்தமான பகுதியை கட்டமைக்கப்பட்ட ஊக்கவாதமாக இணைக்கப்படுகிறது, இதில் தெளிவான அறிவுரைகள், பெற்றுள்ள சூழல் மற்றும் பயனர் கேள்வி அடங்கும். மாதிரியின் முன்னிலையில் உள்ளவை மட்டுமே பயன்படுத்த முடியும், இது கலப்பைத் தடுக்கும். +மிக முக்கியமான துண்டுகள் உள்ளடக்கப்பட்ட, தெளிவான הוראות, மீட்டெடுத்துள்ள சூழல் மற்றும் பயனரின் கேள்வியுடன் கூடிய வரையறுக்கப்பட்ட முன்மொழிவாக ஒன்று சேர்க்கப்படுகிறது. மாடல் அந்த குறிப்பிட்ட துண்டுகளைப் படித்து அந்த தகவலின் அடிப்படையில் பதில் அளிக்கிறது — அது முன் வைக்கப்பட்டவற்றை மட்டுமே பயன்படுத்த முடியும், இதனால் தவறான கற்பனை தவிர்க்கப்படுகிறது. ```java String context = matches.stream() @@ -237,65 +236,65 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -கீழே உள்ள படக்காட்சி இந்த கூடுதலை செயல்பாட்டில் காட்டுகிறது — தேடல் படி இருந்து மேல் மதிப்பிடப்பட்ட பகுதி ஊக்கவாத வார்ப்புருவில் இணைக்கப்படுகின்றன, மற்றும் `OpenAiOfficialChatModel` நிலையான பதிலை உருவாக்குகிறது: +கீழே உள்ள வரைபடம் இந்த ஒன்றிணைப்பை செயல்பாட்டில் காண்பிக்கின்றது — தேடல் படியிலிருந்து அதிக மதிப்பெண் பெற்ற துண்டுகள் முன்மொழிவு மாதிரியில் சேர்க்கப்படுகின்றன, மற்றும் `OpenAiOfficialChatModel` தரமான பதிலை உருவாக்குகிறது: -சூழல் கூடுதல் +Context Assembly -*இந்த படக்காட்சி மேல் மதிப்பிடப்பட்ட பகுதிகள் கட்டமைக்கப்பட்ட ஊக்கவாதமாக இணைக்கப்படுவதைக் காட்டுகிறது, இது உங்கள் தரவிலிருந்து ஒரு நிலையான பதிலை மாதிரிக்கு உருவாக்க அனுமதிக்கிறது.* +*இந்த வரைபடம் அதிக மதிப்பெண் பெற்ற துண்டுகள் அமைப்புக்குரிய முன்மொழிவாக எப்படி சேர்க்கப்படுகின்றன என்று காட்டுகிறது, இதனால் உங்கள் தரவுகளிலிருந்து மாடல் நிலையான பதிலை உருவாக்க முடிகிறது.* -## பயன்பாட்டை இயக்கவும் +## செயலியை இயக்கவும் -**நியமனம் சரிபார்க்கவும்:** +**பரிணாமம் சரிபார்க்கவும்:** -மூலம் அடைவுகளில் Azure அங்கீகாரங்கள் கொண்ட `.env` கோப்பு உள்ளது என்பதை உறுதி செய்யவும் (Module 01 இல் உருவாக்கப்பட்டது). இதனை module அடைவிலிருந்து இயக்கவும் (`03-rag/`): +.rnv கோப்பு வேர் கோப்பகத்தில் Azure அங்கீகார தகவல்களுடன் (Module 01ல் உருவாக்கப்பட்டது) இருக்க வேண்டும். இந்த இயக்கத்தைக் கீழ்க்காணும் முறை மொழிப் பகுதியில் இருந்து (`03-rag/`) செய்க: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்டப்பட வேண்டும் +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ஆகியவை காணப்பட வேண்டும் ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்சி செய்ய வேண்டும் +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காண்பிக்க வேண்டும் ``` -**பயன்பாட்டை துவங்கவும்:** +**செயலியை துவங்கவும்:** -> **குறிப்பு:** Module 01 இல் குறிப்பிடப்பட்டபடி நீங்கள் ஏற்கனவே அனைத்து பயன்பாடுகளையும் `./start-all.sh` கொண்டு இயக்கி இருந்தால், இந்த module 8081 போர்ட்டில் இயங்கிக்கொண்டிருக்கும். கீழ்க்காணும் துவக்க கட்டளைகளை தவிர்க்கவும் மற்றும் நேரடியாக http://localhost:8081 சென்றுடங்கலாம். +> **குறிப்பு:** நீங்கள் ஏற்கனவே ரூட் கோப்பகத்தில் இருந்து `./start-all.sh` மூலம் அனைத்து செயலிகளையும் துவக்கியிருந்தால் (Module 01ல் விவரிக்கப்பட்டபடி), இந்த முறை 8081 துறைமுகத்தில் இயங்குகிறது. கீழுள்ள துவக்கக் கட்டளைகளை தவிர்த்து நேரடியாக http://localhost:8081 செல்லலாம். -**விருப்பம் 1: Spring Boot டாஷ்போர்டைப் பயன்படுத்துதல் (VS Code பயனர்களுக்கு பரிந்துரை)** +**விருப்பம் 1: Spring Boot Dashboard பயன்படுத்துதல் (VS Code பயனர்களுக்கு பரிந்துரை செய்யப்படுகிறது)** -dev கன்டெய்னரில் Spring Boot டாஷ்போர்ட் நீட்சிப்பொருள் உள்ளது, இது அனைத்து Spring Boot பயன்பாடுகளையும் நிர்வகிக்க காட்சியியல் முகப்பை வழங்குகிறது. VS Code இல் இடது பக்க Activity Bar இல் (Spring Boot ஐகானைக் காணவும்) இதைப் பார்க்கலாம். +உள்நுழைவுச் சூழல் Spring Boot Dashboard நீட்சியை கொண்டுள்ளது, இது அனைத்து Spring Boot செயலிகளை மேலாண்மை செய்ய視ual இடைமுகத்தை வழங்குகிறது. VS Code இடது பக்கத்தில் உள்ள Activity Bar இல் Spring Boot ஐகானை காணலாம். -Spring Boot டாஷ்போர்டிலிருந்து, நீங்கள்: -- வேலைநிலை மண்டலத்தில் உள்ள அனைத்து Spring Boot பயன்பாடுகளையும் பார்க்க முடியும் -- ஒரு கிளிக்குடன் பயன்பாடுகளை துவங்கி/நிறுத்த முடியும் -- பயன்பாட்டு பதிவுகளை நேரடியாக காண முடியும் -- பயன்பாட்டு நிலையை கண்காணிக்க முடியும் +Spring Boot Dashboard-இல் நீங்கள்: +- வேலைநிலையிலுள்ள அனைத்து Spring Boot செயலிகளையும் பார்க்க முடியும் +- ஒரு கிளிக்கில் செயலிகளை துவக்க/நிறுத்த முடியும் +- செயலியின் பதிவு (logs) ஐ நேரலையில் பார்க்க முடியும் +- செயலியின் நிலையை கண்காணிக்க முடியும் -"rag" அருகே உள்ள பிளே பட்டனை கிளிக் செய்து இந்த module ஐத் துவங்கவும், அல்லது அனைத்துத் moduleகளையும் ஒரே நேரத்தில் துவங்கவும். +"rag"க்குப் பக்கத்தில் உள்ள play பொத்தானை கிளிக் செய்து இந்த முறைத் தொடங்கவும், அல்லது ஐக்கியமாக அனைத்து முறைங்களையும் துவங்கவும். -Spring Boot டாஷ்போர்ட் +Spring Boot Dashboard -*இந்த ஸ்கிரீன்ஷாட் VS Code இல் Spring Boot டாஷ்போர்டை காட்டுகிறது, இங்கு நீங்கள் பயன்பாடுகளை தோக்க, நிறுத்த, கண்காணிக்க முடியும்.* +*இந்த ஸ்கிரீன்ஷாட் VS Codeஇல் Spring Boot Dashboard ஐ காண்பிக்கிறது, இங்கு நீங்கள் செயலிகளை துவங்கி, நிறுத்தி, கண்காணிக்க முடியும்.* -**விருப்பம் 2: ஷெல் ஸ்கிரிப்ட்கள் பயன்படுத்துதல்** +**விருப்பம் 2: shell ஸ்கிரிப்ட்கள் பயன்படுத்துதல்** -அனைத்து வலை பயன்பாடுகளையும் (moduleகள் 01-04) துவங்கவும்: +முழு வலை செயலிகளை துவக்கம் செய்ய (முறை 01-04): **Bash:** ```bash -cd .. # ரூட் அடைவு கோப்புறையிலிருந்து +cd .. # ரூட் கோப்புறை இலிருந்து ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # ரூட் அடைவரிசையில் இருந்து +cd .. # ரூட் அடைவு இடத்தில் இருந்து .\start-all.ps1 ``` -அல்லது இந்த module மட்டும் துவங்க: +அல்லது இந்த மட்டுமே முறைத் துவங்கவும்: **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -இரண்டாமொழி ஸ்கிரிப்ட்களும் வேரு `.env` கோப்பிலிருந்து சுற்றுச்சூழல் மாறிலிகளை தானாக ஏற்றும் மற்றும் JARகளை இல்லை என்றால் உருவாக்கும். +இரு ஸ்கிரிப்ட்களும் தானாகவே ரூட் `.env` கோப்பிலிருந்து சூழல் மாறிகள் ஏற்றுகிறது மற்றும் JARகளை ஏற்கனவே இல்லையெனில் உருவாக்கும். -> **குறிப்பு:** நீங்கள் ஆரம்பிப்பதற்கு முன் அனைத்து moduleகளையும் கைமுறையாக கட்டவதற்கு விரும்பினால்: +> **குறிப்பு:** துவக்கத்துக்கு முன் அனைத்து முறைங்களையும் கையெழுத்து செய்து உருவாக்க விரும்பினால்: > > **Bash:** > ```bash @@ -325,113 +324,113 @@ cd 03-rag > mvn clean package -DskipTests > ``` -உங்கள் உலாவியில் http://localhost:8081 திறக்கவும். +உங்கள் பிரவுஸரில் http://localhost:8081 ஐத் திறக்கவும். **நிறுத்த:** **Bash:** ```bash -./stop.sh # இந்த தொகுதி மட்டும் +./stop.sh # இந்த மொடியூல் மட்டும் # அல்லது -cd .. && ./stop-all.sh # அனைத்துத் தொகுதிகள் +cd .. && ./stop-all.sh # அனைத்து மொடியூல்கள் ``` **PowerShell:** ```powershell -.\stop.ps1 # இந்த மொட்யூல் மட்டும் +.\stop.ps1 # இந்த தொகுதி மட்டும் # அல்லது -cd ..; .\stop-all.ps1 # அனைத்து மொட்யூல்கள் +cd ..; .\stop-all.ps1 # அனைத்து தொகுதிகள் ``` -## பயன்பாட்டைப் பயன்படுத்துதல் +## செயலியைப் பயன்படுத்துவது -இந்தப் பயன்பாடு ஆவணம் பதிவேற்றம் மற்றும் கேள்வி கேட்க வலை முகப்பை வழங்குகிறது. +இந்த செயலி ஆவணங்களை பதிவேற்றுவதற்கும் கேள்விகள் கேட்கவும் வலை முகப்பை வழங்குகிறது. -RAG பயன்பாட்டு முகப்பு +RAG Application Interface -*இந்த ஸ்கிரீன்ஷாட் RAG பயன்பாட்டு முகப்பை காட்டுகிறது, இதில் நீங்கள் ஆவணங்களை பதிவேற்றவும் கேள்விகளைக் கேட்க முடியும்.* +*இந்த ஸ்கிரீன்ஷாட் RAG செயலி இடைமுகத்தை காட்டுகிறது, இதில் நீங்கள் ஆவணங்களை பதிவேற்றி கேள்விகள் கேட்க முடியும்.* -### ஆவணம் பதிவேற்றல் +### ஆவணத்தை பதிவேற்றவும் -ஆரம்பத்தில் ஒரு ஆவணத்தை பதிவேற்றவும் - சோதனைக்காக TXT கோப்புகள் சிறந்தவை. இந்த அடைவிலுள்ள `sample-document.txt` LangChain4j அம்சங்கள், RAG செயல்பாடு மற்றும் சிறந்த நடைமுறைகள் ஆகியவற்றை தருகிறது - முற்றிலும் சோதனைக்காக சிறந்தது. +ஆரம்பிக்க ஒரு ஆவணத்தை பதிவேற்றுதல் - சோதனைக்கான TXT கோப்புகள் சிறந்தவை. இங்கு `sample-document.txt` என்ற கோப்பு உள்ளது, இதில் LangChain4j அம்சங்கள், RAG செயல்பாடு மற்றும் சிறந்த நடைமுறைகள் பற்றிய தகவல்கள் உள்ளன - இது அமைப்பை சோதிக்க சிறந்தது. -சிஸ்டம் உங்கள் ஆவணத்தை செயலாக்கி, அதனை பகுதிகளாக உடைத்து, ஒவ்வொரு பகுதியுக்கும் எம்பெட்டிங்களை உருவாக்குகிறது. இது பதிவேற்றுகிறபோது தானாக நடக்கும். +அமைப்பு உங்கள் ஆவணத்தை செயலாக்கி, துண்டுகளாக பிரித்து ஒவ்வொரு துண்டுக்கும் படைப்புகளை உருவாக்கும். இதை நீங்கள் பதிவேற்றும்போது தானாக நடக்கும். -### கேள்விகளைக் கேளுங்கள் +### கேள்விகள் கேட்கவும் -இந்த பின்னர் ஆவண உள்ளடக்கத்தைப் பற்றி குறிப்பிட்ட கேள்விகளை கேளுங்கள். ஆவணத்தில் தெளிவாக கூறப்பட்ட உண்மைகளை முயற்சி செய்யவும். சிஸ்டம் பொருத்தமான பகுதிகளைத் தேடி, அவற்றை ஊக்கவாதத்தில் சேர்த்து, பதிலை உருவாக்கும். +இந்தப் பிறகு ஆவண உள்ளடக்கத்தைப் பொருத்த வகையிலான குறிப்பிட்ட கேள்விகள் கேளுங்கள். ஆவணத்தில் தெளிவாக குறிப்பிடப்பட்ட நிலைகளை மையமாகக் கொண்டு ஒரு உண்மை சார்ந்த கேள்வி முயற்சிக்கவும். அமைப்பு பொருத்தமான துண்டுகளைத் தேடி, அவற்றை முன்மொழிவில் சேர்க்கிறது மற்றும் பதிலை உருவாக்குகிறது. -### மூலக் குறிப்புகளை அமைத்தல் +### மூல குறிப்புகளை சரிபார்க்கவும் -ஒவ்வொரு பதிலும் ஒத்திசைவு மதிப்புடன் மூலக் குறிப்புகளையும் கொண்டுள்ளது. இவை (0 முதல் 1 வரை மதிப்புகள்) உங்கள் கேள்விக்கு எந்த போதிலும் அந்த பகுதி பொருத்தமானது என்பதை காட்டுகின்றன. அதிக மதிப்புகள் சிறந்த பொருத்தத்தை குறிக்கின்றன. இதனால் பதிலை மூலத் தகவலிடம் ஒப்பிட முடியும். +ஒவ்வொரு பதிலிலும் ஒத்துமை மதிப்பெண்களுடன் மூல குறிப்புகள் அடங்கும் என்பதை கவனியுங்கள். இவை 0 முதல் 1 வரை மதிப்பெண்கள் உங்கள் கேள்விக்கு எவ்வளவு பொருத்தமானவையாக இருந்தன என்பதைக் காட்டுகின்றன. அதிக மதிப்பெண் என்பது சிறந்த பொருத்தம் என்பதை குறிக்கிறது. இது உங்கள் பதிலை மூலப் பொருளை தொடர்பாக சரிபார்க்க உதவுகிறது. -RAG விசாரணை முடிவுகள் +RAG Query Results -*இந்த ஸ்கிரீன்ஷாட் விசாரணை முடிவுகளை காட்டுகிறது, உருவாக்கப்பட்ட பதில், மூலக் குறிப்புகள் மற்றும் ஒவ்வொரு பெறப்பட்ட பகுதியின் பொருத்த மதிப்புகள்.* +*இந்த ஸ்கிரீன்ஷாட் கேள்வி முடிவுகளை, உருவாக்கப்பட்ட பதிலை, மூல குறிப்புகளை மற்றும் ஒவ்வொரு மீட்டெடுக்கப்பட்ட துண்டுக்கான பொருத்த மதிப்புகளை காட்டுகிறது.* -### கேள்விகளுடன் கலைவுடன் விளையாடு +### கேள்விகளுடன் முன்னேறவும் -விதிவழி கேள்விகளை முயற்சி செய்யுங்கள்: -- குறிப்பிட்ட உண்மைகள்: "முக்கிய தலைப்பு என்ன?" -- ஒப்பீடுகள்: "X மற்றும் Y இடையேயான வேறுபாடு என்ன?" -- சுருக்கங்கள்: "Z பற்றி முக்கிய புள்ளிகளை சுருக்குக" +வேறு வகை கேள்விகளை முயற்சிக்கவும்: +- குறிப்பிட்ட தகவல்கள்: "முதன்மை பொருள் என்ன?" +- ஒப்பீடுகள்: "X மற்றும் Y இல் வேறுபாடு என்ன?" +- சுருக்கங்கள்: "Z பற்றிய முக்கிய புள்ளிகளை சுருக்கவும்" -உங்கள் கேள்வியின் பின் ஆவண உள்ளடக்கத்துடன் பொருந்துவதில் பொருத்த மதிப்புகள் எப்படி மாறுகிறதென்பதை கவனிக்கவும். +உங்கள் கேள்வி ஆவண உள்ளடக்கத்துடன் எவ்வாறு பொருந்துதலைப் பொறுத்து பொருத்த மதிப்பெண்கள் எப்படி மாறுகின்றன என்பதை கவனியுங்கள். -## முக்கிய கருத்துக்கள் +## முக்கியக் கொள்கைகள் -### பகுதி பிரித்தல் முறை +### துண்டாக்கல் நெறிமுறை -ஆவணங்கள் 300-டோக்கன் பகுதிகளாக பிரிக்கப்படுகின்றன, 30 டோக்கன்கள் ஒவர்லாப் உடன். இந்த சமநிலை ஒவ்வொரு பகுதியும் பொருத்தமான சூழலைக் கொண்டிருக்கும் வகையில் மற்றும் ஒரு ஊக்கவாதத்தில் பல பகுதிகள் சேர்க்க அனுமதிக்கும் அளவுக்கு சிறியதாக இருக்கும். +ஆவணங்கள் 300-டோக்கன் துண்டுகளாகப் பிரிக்கப்படுகின்றன, 30 டோக்கன் ஒட்டுமொத்தம் இடைப்பட்டுள்ளன. இது ஒவ்வொரு துண்டுக்கும் பொருத்தமான சூழலை அளிக்க உதவுகிறது, மேலும் பல துண்டுகளை ஒரே முன்மொழிவில் சேர்ப்பதற்கு அழுத்தமாக இருக்காது. -### ஒத்திசைவு மதிப்புகள் +### ஒத்துமை மதிப்பெண்கள் -ஒவ்வொரு பெறப்பட்ட பகுதியும் 0 முதல் 1 வரை உள்ள ஒத்திசைவு மதிப்போடு வருகிறது, இது பயனர் கேள்விக்கேளிச் சரியாக பொருந்துதலின் அளவை காட்டுகிறது. கீழ்க்காணும் வரைபடம் மதிப்புகளின் அகரவரிசையை மற்றும் சிஸ்டம் அவற்றைப் பயன்படுத்தி முடிவுகளை வடிகட்டி பார்க்கும் முறையை காண்பிக்கிறது: +ஒவ்வொரு மீட்டெடுக்கப்பட்ட துண்டும் 0 முதல் 1 வரை மதிப்பெண் கொண்டுள்ளது, இது பயனரின் கேள்விக்கு எவ்வளவு நெருக்கமாக பொருந்துகிறது என்று காட்டுகிறது. கீழே உள்ள வரைபடம் மதிப்பெண் வரம்புகளை காட்டு, அமைப்பு அவற்றை எவ்வாறு முடிவுகளை வடிகட்டி பயன்படுத்துது என்பதைக் காட்டுகிறது: -ஒத்திசைவு மதிப்புகள் +Similarity Scores -*இந்த படக்காட்சி 0 முதல் 1 வரை மதிப்பு விரிவுகளைக் காட்டுகிறது, 0.5 குறைந்தபட்ச சேதத்துடன் பொருந்தாத பகுதிகளை வடிகட்டும்.* +*இந்த வரைபடம் 0 முதல் 1 வரை மதிப்பெண் வரம்புகளை காட்டுகிறது, 0.5 குறைந்தபட்ச எல்லையை வைத்து பொருத்தமற்ற துண்டுகளை வடிகட்டுகிறது.* -மதிப்புகள் 0 முதல் 1 வரையிலானவை: -- 0.7-1.0: மிகவும் பொருத்தமான, துல்லியமான பொருத்தம் -- 0.5-0.7: பொருத்தமான, நல்ல சூழல் -- 0.5 க்கும் கீழே: வடிகட்டப்பட்டது, மிகவும் வேறுபட்டது +மதிப்பெண்கள் 0 முதல் 1 வரை: +- 0.7-1.0: மிகவும் பொருத்தமானது, சரியான பொருத்தம் +- 0.5-0.7: பொருத்தமானது, நல்ல சூழல் +- 0.5க்குட்பட்டு: வடிகட்டப்பட்டது, மிகவும் வேறுபட்டது -சிஸ்டம் குறைந்தபட்ச சேதத்தை மீறிய பகுதிகளையே பெறுகிறது, இது தரநிலையை உறுதிப்படுத்துகிறது. +அமைப்பு தரத்துக்கு உறுதி செய்ய குறைந்தபட்ச எல்லையை மீண்டும் மேல் உள்ள துண்டுகளை மட்டுமே மீட்டெடுக்கிறது. -எம்பெட்டிங்குகள் அர்த்தம் நன்கு குழுக்களால் வருகையில் சிறப்பாக செயல்படுகின்றன, ஆனால் அவற்றுக்கு பனி உள்ள இடங்கள் உள்ளன. கீழ்க்காணும் படக்காட்சி பொதுவான தோல்வி முறைகளை காட்டுகிறது — மிகப் பெரிய பகுதிகள் குழ்படுத்திய வெக்டர்களை உருவாக்குகின்றன, மிகச் சிறிய பகுதிகளை சூழல் குறைபாடு உள்ளது, குழப்பமான சொற்கள் பல குழுக்களை நோக்குகின்றன, மற்றும் துல்லிய பொருத்தத் தேடல்கள் (IDs, பாக எண்கள்) எண்பட்டிங்குகளுடன் வேலை செய்யமாட்டார்: +எம்பெட்டிங்ஸ்கள் கருத்துக்கள் தெளிவாக பொருத்தும்போது சிறப்பாக செயல்படுகின்றன, ஆனால் அவற்றுக்கு முடட்டும் இடங்கள் உள்ளன. கீழ்ப் பருகப்படும் வரைபடம் பரவலாக உள்ள பழுதுகளை காட்டுகிறது — மிகப்பெரிய துண்டுகள் கலப்பற்ற வெக்டார்கள் உருவாக்குகின்றன, மிகச்சிறிய துண்டுகள் சூழல் இல்லாமை, குழப்பமுள்ள சொற்கள் பல வட்டாரங்களுக்கு காண்பிக்கும், மற்றும் சரியான பொருத்தத் தேடல்கள் (IDs, பகுதிநிலை எண்கள்) எம்பெட்டிங்ஸுடன் வேலை செய்யாது: -எம்பெட்டிங் தோல்வி முறைகள் +Embedding Failure Modes -*இந்த படக்காட்சி பொதுவான எம்பெட்டிங் தோல்வி முறைகளை காட்டுகிறது: மிகப் பெரிய பகுதிகள், மிகச் சிறிய பகுதிகள், பல குழுக்களை நோக்குவிக்கும் குழப்பமான சொற்கள், மற்றும் IDs போன்ற துல்லிய பொருத்த தேடல்கள்.* +*இந்த வரைபடம் பொதுவான எம்பெட்டிங் தோல்வித் தீமைகளை காட்டுகிறது: மிகப்பெரிய துண்டுகள், மிகச்சிறிய துண்டுகள், பல குழுக்களை குறிக்கும் குழப்பமுள்ள சொற்கள், மற்றும் சரியான பொருத்தத் தேடல்கள் (IDs போன்றவை).* -### நினைவகச் சேமிப்பு +### நினைவகத்தில் சேமிப்பு -இந்த module எளிமைக்காக நினைவகக் களஞ்சியத்தைப் பயன்படுத்துகிறது. பயன்பாட்டை மறுசீரமைத்தால் பதிவேற்றப்பட்ட ஆவணங்கள் இழக்கும். உற்பத்தி முறைகள் Qdrant அல்லது Azure AI Search போன்ற நிலையான வெக்டர் தரவுத்தளங்களைப் பயன்படுத்துகின்றன. +இந்த முறை எளிமைக்காக நினைவக சேமிப்பைப் பயன்படுத்துகிறது. நீங்கள் செயலியை மீண்டும் துவங்கும்போது, பதிவேற்றிய ஆவணங்கள் நீக்கப்படுகின்றன. தயாரிப்புத் தயாரிப்புகள் Qdrant அல்லது Azure AI Search போன்ற நிரந்தர வெக்டார் தரவுத்தளங்களைப் பயன்படுத்துகின்றன. -### சூழல் ஜன்னல் முகாமை +### சூழல் ஜன்னல் மேலாண்மை -ஒவ்வொரு மாதிரிக்கும் அதிகபட்ச சூழல் ஜன்னல் உள்ளது. பெரிய ஆவணத்திலிருந்து எல்லா பகுதிகளையும் சேர்க்க முடியாது. சிஸ்டம் அதிகம் பொருத்தமான ஊதான N பகுதிகளை (இயல்பு 5) இயற்றுகிறது, இது வரம்புகளில் இருக்க உதவுகின்றது மேலும் துல்லியப் பதில்களுக்கு போதுமான சூழலை வழங்குகின்றது. +ஒவ்வொரு மாடலுக்கும் அதிகபட்ச சூழல் ஜன்னல் உள்ளது. பெரிய ஆவணத்தில் உள்ள ஒவ்வொரு துண்டையும் சேர்க்க முடியாது. அமைப்பு அதிக படியான பொருத்தம் கொண்ட உயர்நிலை N துண்டுகளை (இயல்பானம் 5) பெறுகிறது, இது அதிக நுண்ணறிவான பதில்களை அளிக்க போதுமான சூழலை வழங்கும். -## RAG முக்கியம் எப்போது +## RAG முக்கியமான போது -RAG எப்போதும் சரியான அணுகுமுறை அல்ல. கீழ்காணும் தீர்மான வழிகாட்டி RAG மதிப்பை எப்போது சேர்க்கின்றது மற்றும் எப்போது எளிய அணுகுமுறைகள் — நேரடியாக உள்ளடக்கத்தை ஊக்கவாதத்தில் சேர்ப்பது அல்லது மாதிரியின் உள்ளடக்க அறிவுக்கு நம்புவதே போதும் — போதுமானனவாக இருக்கும் என்பதை உதவுகின்றது: +RAG எப்போதும் சரியான அணுகுமுறை அல்ல. கீழே உள்ள தீர்மான வழிகாட்டி RAG எப்போது மதிப்பை கூட்டுகிறது என்பதையும் எப்போது எளிதான அணுகுமுறைகள் — நேரடியாக உள்ளடக்கத்தை முன்மொழிவில் சேர்ப்பது அல்லது மாடலின் உள்ளமைவாகக் கொண்டுள்ள அறிவைப் பயன்படுத்துவது — போதுமானவை என்பதையும் உதவுகிறது: -RAG பயன்படுத்துவது எப்போது +When to Use RAG -*இந்த படக்காட்சி RAG மதிப்பை எப்போது சேர்க்கின்றது மற்றும் எப்போது எளிய அணுகுமுறைகள் போதும் என்பதை தீர்மானிக்கும் வழிகாட்டியைக் காட்டுகிறது.* +*இந்த வரைபடம் RAG மதிப்பையும் எளிமையான அணுகுமுறைகள் போதுமான நிலைகளையும் தீர்மானிக்க உதவும் வழிகாட்டி காட்டுகிறது.* ## அடுத்த படிகள் -**அடுத்த Module:** [04-tools - கருவிகளுடன் AI முகவர்கள்](../04-tools/README.md) +**அடுத்த முறை:** [04-tools - கருவிகளுடன் AI முகவர்கள்](../04-tools/README.md) --- -**நோக்கம்:** [← முன்பு: Module 02 - ஊக்கவாத உருவாக்கம்](../02-prompt-engineering/README.md) | [மீண்டும் முதற்கொள்ளு](../README.md) | [அடுத்து: Module 04 - கருவிகள் →](../04-tools/README.md) +**Navigation:** [← முந்தையது: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [முதன்மைக்கு திரும்பவும்](../README.md) | [அடுத்தது: Module 04 - கருவிகள் →](../04-tools/README.md) --- -**மறுப்பு**: -இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) மூலம் மொழிபெயர்க்கப்பட்டுள்ளது. நாங்கள் துல்லியத்திற்காக முயலினாலும், தானாக செய்யப்பட்ட மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கக்கூடும் என்பதை தயவுசெய்து கவனியுங்கள். இந்த ஆவணத்தின் அசல் மொழி சார்ந்த பதிப்பே அதிகாரப்பூர்வமான ஆதாரமாகக் கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்காக, தொழில்முறை மனித மொழிபெயர்ப்பை பரிந்துரைக்கிறோம். இந்த மொழிபெயர்ப்பைப் பயன்படுத்தியதன் காரணமாக ஏற்பட்ட எந்தவொரு தவறுணர்வு அல்லது தவறான புரிதலுக்கான பொறுப்பானவர்கள் அல்லாமை நாங்கள் உறுதிசெய்கிறோம். +**மறுப்பு**: +இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. நாங்கள் துல்லியத்திற்காக முயற்சி செய்துள்ளோம், ஆனால் தானாக செய்யப்படும் மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கலாம் என்பதை கவனத்தில் கொள்ளவும். அசல் ஆவணம் அதன் தாய்மொழியில் அதிகாரப்பூர்வ ஆதாரமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழில்நுட்பமான மனித மொழிபெயர்ப்பு பரிந்துரைக்கப்படுகிறது. இந்த மொழிபெயர்ப்பைப் பயன்படுத்துவதால் ஏற்படும் எந்த தவறான புரிதல்கள் அல்லது தவறான விளக்கத்திற்கும் நாங்கள் பொறுப்பில்வில்லை. \ No newline at end of file diff --git a/translations/ta/04-tools/README.md b/translations/ta/04-tools/README.md index d4f4c7310..a5d325d6a 100644 --- a/translations/ta/04-tools/README.md +++ b/translations/ta/04-tools/README.md @@ -1,84 +1,84 @@ -# Module 04: கருவிகளுடன் கூடிய AI முகவர்கள் +# Module 04: கருவிகளுடன் AI முகவர்கள் -## உள்ளடக்க அட்டவணை +## உள்ளடக்கக் குறிப்பு -- [காணொலி வழிகாட்டி](../../../04-tools) -- [நீங்கள் கற்றுக்கொள்ளப்போகும் விஷயங்கள்](../../../04-tools) -- [முதன்மையான தேவைகள்](../../../04-tools) -- [கருவிகளுடன் கூடிய AI முகவர்களை förstå](../../../04-tools) -- [கருவி அழைப்பது எப்படி வேலை செய்கிறது](../../../04-tools) - - [கருவி வரையறைகள்](../../../04-tools) - - [முடிவெடுக்கும் செயல்முறை](../../../04-tools) - - [நிர்வாகம்](../../../04-tools) - - [பதில் உருவாக்குதல்](../../../04-tools) - - [வடிவமைப்பு: Spring Boot தானாக இணைத்தல்](../../../04-tools) -- [கருவி சங்கிலி](../../../04-tools) -- [விண்ணப்பத்தை இயக்கு](../../../04-tools) -- [விண்ணப்பத்தை பயன்படுத்துதல்](../../../04-tools) - - [எளிய கருவி பயன்பாட்டை முயற்சி செய்](../../../04-tools) - - [கருவி சங்கிலியை சோதிக்கவும்](../../../04-tools) - - [संवाद ஓட்டம் கண்டு கெள்](../../../04-tools) - - [விதிவிலக்கு கோரிக்கைகளுடன் பரிசோதனை செய்](../../../04-tools) -- [முக்கிய கருத்துகள்](../../../04-tools) - - [ReAct வடிவம் (கருத்துக்களிக்கும் மற்றும் செயல்படும்)](../../../04-tools) - - [கருவி விளக்கங்கள் முக்கியம்](../../../04-tools) - - [அதுிகட்சி நிர்வாகம்](../../../04-tools) - - [பிழை கையாளுதல்](../../../04-tools) -- [கிடைக்கும் கருவிகள்](../../../04-tools) -- [எப்போது கருவி அடிப்படையிலான முகவர்களை பயன்படுத்துவது](../../../04-tools) -- [கருவிகள் மற்றும் RAG](../../../04-tools) -- [அடுத்த படிகள்](../../../04-tools) +- [வீடியோ நடைமுறை](#வீடியோ-நடைமுறை) +- [நீங்கள் கற்றுக்கொள்ளும் விஷயங்கள்](#நீங்கள்-கற்றுக்கொள்ளும்-விஷயங்கள்) +- [முன் தேவைகள்](#முன்-தேவைகள்) +- [கருவிகளுடன் AI முகவர்களைப் புரிந்துகொள்ளுதல்](#கருவிகளுடன்-ai-முகவர்களைப்-புரிந்துகொள்ளுதல்) +- [கருவி அழைப்பு எப்படி வேலை செய்கிறது](#கருவி-அழைப்பு-எப்படி-வேலை-செய்கிறது) + - [கருவி வரையறைகள்](#கருவி-வரையறைகள்) + - [ முடிவெடுக்கும் செயல்முறை](#முடிவெடுக்கும்-செயல்முறை) + - [நிறைவு](#நிறைவு) + - [பதில் உருவாக்கம்](#பதில்-உருவாக்கம்) + - [வாசல் கட்டமைப்பு: ஸ்பிரிங் பூட் தானாக இணைத்தல்](#வாசல்-கட்டமைப்பு-ஸ்பிரிங்-பூட்-தானாக-இணைத்தல்) +- [கருவி சங்கிலி](#கருவி-சங்கிலி) +- [விணைத்தளம் இயக்கவும்](#விணைத்தளம்-இயக்கவும்) +- [விணைத்தளம் பயன்படுத்துதல்](#பயன்பாட்டைப்-பயன்படுத்துதல்) + - [எளிய கருவி பயன்பாடு முயற்சிக்கவும்](#எளிய-கருவி-பயன்பாட்டை-முயற்சி-செய்க) + - [கருவி சங்கிலியை சோதிக்கவும்](#கருவி-சங்கிலி-சோதனை-செய்யுங்கள்) + - [உரையாடல் ஓட்டத்தை காணவும்](#உரையாடல்-ஓட்டத்தை-பார்க்கவும்) + - [வித்தியாசமான கோரிக்கைகளுடன் முயற்சி செய்யவும்](#வேறுபட்ட-கோரிக்கைகளை-முயற்சி-செய்யுங்கள்) +- [முக்கிய கருத்துக்கள்](#முக்கியக்-கொள்கைகள்) + - [ReAct ரூபம் (காரணம் மற்றும் செயல்)](#react-மாதிரி-கருத்து-விளக்கம்-மற்றும்-செயல்பாடு) + - [கருவி விளக்கங்கள் முக்கியம்](#கருவி-விளக்கங்கள்-முக்கியம்) + - [அமர்வு மேலாண்மை](#அமர்வு-மேலாண்மை) + - [பிழை கையாளுதல்](#பிழை-கையாளுதல்) +- [கிடைக்கும் கருவிகள்](#கிடைக்கும்-கருவிகள்) +- [எப்பொழுது கருவி அடிப்படையிலான முகவர்களைப் பயன்படுத்த வேண்டும்](#கருவி-அடிப்படையிலான-முகவர்களை-எப்போது-பயன்படுத்துவது) +- [கருவிகள் vs RAG](#கருவிகள்-vs-rag) +- [அடுத்து என்ன செய்ய வேண்டும்](#அடுத்த-படிகள்) -## காணொலி வழிகாட்டி +## வீடியோ நடைமுறை -இந்த மாடியுடன் எப்படித் தொடங்குவது என்பதை விளக்குகிறது இந்த நேரடி சந்திப்பை பார்க்கவும்: +இந்த தொகுதியில் எப்படி தொடங்குவது என்று விளக்கும் நேரடி அமர்வை பாருங்கள்: -கருவிகளுடன் கூடிய AI முகவர்கள் மற்றும் MCP - நேரடி அமர்வு +கருவிகளுடன் AI முகவர்கள் மற்றும் MCP - நேரடி அமர்வு -## நீங்கள் கற்றுக்கொள்ளப்போகும் விஷயங்கள் +## நீங்கள் கற்றுக்கொள்ளும் விஷயங்கள் -இந்நிலையில், நீங்கள் AI உடன் உரையாடல்கள் செய்வது, கீழ்காணும் முறையில் கேள்விகளை அமைப்பதையும், உங்கள் ஆவணங்களில் பதில்களை நிலைநிறுத்துவது போல் பலவற்றை கற்று கொண்டிருக்கிறீர்கள். ஆனால் இன்னும் ஒரு அடிப்படையான வரம்பு உள்ளது: மொழி மாதிரிகள் வெறும் உரையை உருவாக்க முடியும் மட்டுமே. அவை வானிலை சரிபார்க்க முடியாது, கணக்கீடுகளை செய்ய முடியாது, தரவுத்தளங்களை விசாரிக்க முடியாது அல்லது வெளியிலுள்ள அமைப்புகளுடன் தொடர்புகொள்ள முடியாது. +இதுவரை, நீங்கள் AI உடன் உரையாடல்கள் நடத்துவது, தொடக்கங்களை சீரமைப்பது, மற்றும் உங்கள் ஆவணங்களில் பதில்களை அடிப்படையாக்கொள்ளுவது பற்றி கற்றுக்கொண்டுள்ளீர்கள். ஆனால் அங்கு ஒரு அடிப்படையான எல்லை உள்ளது: மொழி மாதிரிகள் வெறும் உரை உருவாக்கக் கூடியவை. அவை வானிலை பராமரிக்க முடியாது, கணக்கீடுகளை செய்ய முடியாது, தரவுத்தளங்களை விசாரிக்க முடியாது, அல்லது வெளிப்புற கணினி அமைப்புகளுடன் தொடர்பு கொள்வதில் இயலாது. -கருவிகள் இதை மாற்றுகிறது. மாதிரிக்கு செயல்பாடுகளை அழைக்க அனுமதிப்பதன் மூலம், நீங்கள் அதை உரை உருவாக்கும் கருவியிலிருந்து, செயல்களை செய்யக்கூடிய முகவராக மாற்றுகிறீர்கள். மாதிரி எப்போது ஒரு கருவியைத் தேவைப்படுத்துவது, எந்த கருவியைப் பயன்படுத்துவது, மற்றும் எந்த அளவுருக்களை அனுப்புவது என்பதைத் தீர்மானிக்கிறது. உங்கள் கோடு செயல்பாட்டை நடத்தியவுடன் முடிவைப் பெறுகிறது. மாதிரி அந்த முடிவை தனது பதிலில் இணைக்கும். +கருவிகள் இதைத்தவிர்க்கின்றன. மாதிரிக்கு அழைக்கக்கூடிய செயல்பாடுகளை அளிப்பதால், நீங்கள் அதை உரை உருவாக்கியவராக இருந்ததை செயல்கள் மேற்கொள்ளக்கூடிய முகவராக மாற்றுகிறீர்கள். மாதிரி எப்போது கருவி தேவை, எந்த கருவி பயன்படுத்த வேண்டும், மற்றும் எந்த அளவுருக்களை அனுப்ப வேண்டும் என்பதை பரிசீலித்து தீர்மானிக்கிறது. உங்கள் குறியீடு செயல்பாட்டை இயக்கி முடிவைத் திருப்பக்கூறும். மாதிரி அந்த முடிவை தனது பதிலில் சேர்க்கிறது. -## முதன்மையான தேவைகள் +## முன் தேவைகள் -- முடிவு செய்தது [Module 01 - அறிமுகம்](../01-introduction/README.md) (Azure OpenAI வளங்கள் பணி நிலையில்) -- முன் தொகுதிகள் பரிந்துரைக்கப்பட்டவை (இந்த தொகுதி [Module 03 இல் RAG கருத்துக்களை](../03-rag/README.md) கருவிகள் மற்றும் RAG ஒப்பீட்டில் குறிப்பிடுகிறது) -- `.env` கோப்பு ரூட் கோப்பகத்தில் உள்ளது Azure அங்கீகாரத்துடன் (Module 01 இல் `azd up` மூலம் உருவாக்கப்பட்டது) +- [Module 01 - அறிமுகம்](../01-introduction/README.md) பூர்த்தி செய்திருக்க வேண்டும் (Azure OpenAI வளங்கள் அமைக்கப்பட்டுள்ளன) +- முன் தொகுதிகள் பரிந்துரைக்கப்பட்டுள்ளன (இந்த தொகுதி [RAG கருத்துக்களை Module 03](../03-rag/README.md) இல் Tools vs RAG ஒப்பீட்டில் குறிப்பிடுகிறது) +- ரூட் கோப்புறையில் Azure அங்கீகாரங்களுடன் `.env` கோப்பு இருக்க வேண்டும் (Module 01 இல் `azd up` கோம் உருவாக்கியது) -> **குறிப்பு:** Module 01 முடிக்கப்படாவிட்டால், முதலில் அங்கே உள்ள 배치 வழிகாட்டுதலை பின்பற்றவும். +> **குறிப்பு:** நீங்கள் Module 01 ஐ இன்னும் பூர்த்தி செய்யவில்லை என்றால், முதலில் அங்கு உள்ள நிரப்பும் வழிமுறைகளைக் கடைபிடிக்கவும். -## கருவிகளுடன் கூடிய AI முகவர்களை புரிந்துகொள்ளுதல் +## கருவிகளுடன் AI முகவர்களைப் புரிந்துகொள்ளுதல் -> **📝 குறிப்பு:** இந்த தொகுதியில் "முகவர்கள்" என்பதற்கான பொருள் கருவி அழைப்புக் கொள்கைகளை கொண்ட AI உதவியாளர்களைக் குறிக்கிறது. இது [Module 05: MCP](../05-mcp/README.md) இல் நாம் கையாளும் **Agentic AI** படிமங்கள் (தன்னாட்சி முகவர்கள் திட்டமிடல், நினைவகத்துடன் மற்றும் பல படி காரணிப்பாட்டுடன்) என்பவைகளில் இருந்து வேறுபட்டது. +> **📝 குறிப்பு:** இந்த தொகுதியில் "முகவர்கள்" என்றால் கருவி அழைக்கக் கூடிய திறன்களுடன் மேம்படுத்தப்பட்ட AI உதவியாளர்களை குறிக்கிறது. இது [Module 05: MCP](../05-mcp/README.md) இல் பார்க்கப்படும் **Agentic AI** வடிவமைப்புகளுக்குப் புறம்பாகும் (தன்னாட்சி முகவர்கள் திட்டமிடல், நினைவு மற்றும் பல-படிநிலைக் காரணப்பிரகடனம் உடையவர்கள்). -கருவிகள் இல்லாமல், ஒரு மொழி மாதிரி அதன் பயிற்சி தரவிலிருந்து மட்டும் உரையைக் காண்பிக்க முடியும். தற்போதைய வானிலை பற்றி கேள்வி கேட்கும் பொழுது, அது சூட்டமாக கண்டறிய முனைகிறது. ஆனால் கருவிகள் கொடுத்தால், அது வானிலை API-ஐ அழைக்க, கணக்கீடுகளை செய்ய, அல்லது தரவுத்தளத்தை விசாரிக்க முடியும் — பின்னர் அந்த உண்மையான முடிவுகளை அதன் பதிலில் ஓத்திச் சேர். +கருவிகள் இல்லாமல், ஒரு மொழி மாதிரி அதன் பயிற்சி தரவிலிருந்து வெறும் உரை உருவாக்க முடியும். தற்போதைய வானிலை என்ன என்று கேட்கும் போது அது ஊகிக்க முயல வேண்டும். கருவிகளை வழங்கினால், அது வானிலை API ஐ அழைக்க முடியும், கணக்கீடுகளை செய்யும், அல்லது தரவுத்தளத்தை விசாரிக்கும் — அப்பொழுது அந்த உண்மை முடிவுகளை தனது பதிலில் நெய்துவைக்கிறது. -கருவிகள் இல்லாமல் VS கருவிகளுடன் +கருவிகள் இல்லாதது ஒப்பிடுகையில் கருவிகளுடன் -*கருவிகள் இல்லாமல் மாதிரி மட்டும் ஊகிக்க முடியும் — கருவிகள் மூலம் அது APIகளை அழைக்க, கணக்கீடுகளை செய்ய, நேரடி தரவைத் திரும்ப வழங்க முடியும்.* +*கருவிகள் இல்லாத போது மாதிரி ஊகிக்க வேண்டியிருக்கும் — கருவிகளுடன் அது API களை அழைக்க, கணக்கீடுகளை இயக்க, மற்றும் நேரடி தரவை திருப்ப முடியும்.* -கருவிகளுடன் கூடிய AI முகவர் ஒரு **கருத்துக்களிப்பு மற்றும் செயல்பாடு (ReAct)** வடிவத்தை பின்பற்றுகிறது. மாதிரி வெறும் பதிலளிப்பது மட்டுமல்ல — அது என்ன வேண்டும் என்பதை யோசிக்கிறது, கருவியை அழைத்து செயல்படுகிறது, முடிவைக் காண்கிறது, பிறகு மீண்டும் செயல்பட வேண்டுமா அல்லது இறுதி பதிலை வழங்குமா என்று தீர்மானிக்கிறது: +கருவிகளுடன் AI முகவர் **காரணம் மற்றும் செயல் (ReAct)** ரூபத்தை பின்பற்றுகிறது. மாதிரி வெறும் பதில் கொடுப்பதல்ல — அது என்ன தேவை என்பதை சிந்திக்கிறது, கருவியை அழைக்கும் மூலம் செயல்படுகிறது, முடிவைப் பார்வையிடுகிறது, பின்னர் மீண்டும் செயல்பட வேண்டுமா அல்லது இறுதி பதிலை வழங்க வேண்டுமா எனத் தீர்மானிக்கிறது: -1. **கருத்துக்களிக்கவும்** — பயனர் கேள்வியை பகுப்பாய்வு செய்து எந்தத் தகவல் தேவைப்படுகின்றதா என்பதை கண்டறிதல் -2. **செயல் படுத்துதல்** — சரியான கருவியை தேர்வு செய்து, சரியான அளவுருக்களை உருவாக்கி அதை அழைக்குதல் -3. **கவனிக்கவும்** — கருவியின் வெளியீட்டை பெற்றுக் கொண்டு முடிவை மதிப்பாய்வு செய்தல் -4. **மீண்டும் செயல் படுத்துதல் அல்லது பதிலளித்தல்** — மேலதிக தரவு தேவையாயினால் மீண்டும் செயலாக்கம்; இல்லையெனில் இயல்பான மொழி பதிலை உருவாக்குதல் +1. **காரணம்** — முகவர் பயனரின் கேள்வியை பகுப்பாய்வு செய்து தேவையான தகவலை தீர்மானிக்கிறது +2. **செயல்** — முகவர் சரியான கருவியை தேர்ந்தெடுத்து, சரியான அளவுருக்களை உருவாக்கி அதை அழைக்கிறது +3. **பார்வை** — முகவர் கருவி வெளியீட்டை பெற்றுப் பார்வையிடுகிறது +4. **மீண்டும் செய்யவும் அல்லது பதில் அளிக்கவும்** — மேலும் தரவு தேவைப்பட்டால், முகவர் மீண்டும் அதே செயலை மேற்கொள்கிறது; இல்லையென்றால் இயல்பான மொழி பதிலை உருவாக்குகிறது -ReAct வடிவம் +ReAct ரூபம் -*ReAct சுற்றம் — முகவர் என்ன செய்யவேண்டும் என்பதை நினைத்து, கருவியை அழைத்து, முடிவைக் காண்கிறது மற்றும் முடிவைப் பெறும் வரை இது பின்வரிசையாக நடைபெறுகிறது.* +*ReAct சுற்று — முகவர் என்ன செய்யவேண்டும் என்பதில் காரணம் காண்கிறது, கருவியை அழைத்து செயல் படுகிறது, முடிவைப் பார்வையிடுகிறது, மற்றும் இறுதி பதில் தொழில்முறை முறையில் வழங்கும் வரை சுற்றுகிறது.* -இது தானாக நிகழ்கிறது. நீங்கள் கருவிகளையும் அவற்றின் விளக்கங்களையும் வரையறுக்கின்றீர்கள். மாதிரி அவற்றைப் பயன்படுத்த எப்போது, எப்படி என்பதைக் குறித்து முடிவுகளை எடுக்கிறது. +இதன் செயல் தானாக நடக்கிறது. நீங்கள் கருவிகள் மற்றும் அவற்றின் விளக்கங்களை வரையறுத்து விடுகிறீர்கள். மாதிரி அவற்றைக் எப்போது மற்றும் எப்படி பயன்படுத்துவது என்பதை தீர்மானிக்கிறது. -## கருவி அழைப்பது எப்படி வேலை செய்கிறது +## கருவி அழைப்பு எப்படி வேலை செய்கிறது ### கருவி வரையறைகள் [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -நீங்கள் தெளிவான விளக்கங்களும் அளவுரு விவரங்களும் கொண்ட செயல்பாடுகளை வரையறுக்கிறீர்கள். மாதிரி அவற்றை தனது கணினி இயக்கவியல் சார்ந்த குறிப்புகளில் பார்த்து அந்த கருவி என்ன செய்யும் என்பதைக் கற்றுக்கொள்கிறது. +நீங்கள் தெளிவான விளக்கங்களும் அளவுரு விவரங்களும் உடன் செயல்பாடுகளை வரையறுக்கிறீர்கள். மாதிரி இந்த விளக்கங்களை தனது அமைப்பு தொடக்கத்தில் பார்த்து ஒவ்வொரு கருவியும் என்ன செய்கிறது என்பதைப் புரிந்து கொள்கிறது. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // உங்கள் வானிலை தாக்குதலைத் தேடும் தந்திரம் + // உங்கள் வானிலை தேடல் தர்க்கம் return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,153 +96,153 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// உதவியாளர் Spring Boot மூலம் தானாக இணைக்கப்பட்டுள்ளது: +// Spring Boot மூலம் உதவியாளர் தானாக இணைக்கப்பட்டுள்ளது: // - ChatModel பீன் -// - @Component வகுப்புகளிலிருந்து அனைத்து @Tool முறைகள் +// - @Component வகுப்புகளின் அனைத்து @Tool முறைமைகள் // - அமர்வு மேலாண்மைக்கான ChatMemoryProvider ``` -கீழே உள்ள வரைபடம் ஒவ்வொரு குறிப்பு நிரலை விவரித்து AI எப்போது கருவியை அழைக்க வேண்டும், என்ன அளவுருக்கள் அனுப்ப வேண்டும் என்பதைக் காட்டுகிறது: +பின்வரும் படத்தில் ஒவ்வொரு குறிப்பும் உட்படப்படுவது மற்றும் AI க்கு எப்போது கருவியை அழைக்கவும் எந்த அளவுருக்களை அனுப்பவும் உதவும் வழி காட்டப்படுகிறது: கருவி வரையறைகளின் அமைப்பு -*கருவி வரையறையின் அமைப்பு — @Tool AIக்கு எப்போது பயன்படுத்த வேண்டும் என்பதைக் கூறுகிறது, @P ஒவ்வொரு அளவுருவையும் விவரிக்கிறது, மற்றும் @AiService அனைத்தையும் துவக்கத்திலே இணைத்து இருக்கிறது.* +*கருவி வரையறையின் அமைப்பு — @Tool AI க்கு எப்போது பயன்படுத்த வேண்டும் என்பதைக் குறிப்பிடுகிறது, @P ஒவ்வொரு அளவுருவையும் விளக்குகிறது, மற்றும் @AiService மூலம் அனைத்து பகுதியும் துவக்கத்தில் இணைக்கப்படுகிறது.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) உரையாடலுடன் முயற்சி செய்க:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) திறந்து கேளுங்கள்: -> - "Mock தரவின் பதிலாக உண்மையான வானிலை API OpenWeatherMap-ஐ எப்படி இணைப்பேன்?" -> - "AI அதை சரியாக பயன்படுத்த உதவும் நல்ல கருவி விளக்கம் என்பது என்ன?" -> - "கருவி செயல்பாடுகளில் API பிழைகள் மற்றும் வேக வரம்புகளை எப்படி கையாள வேண்டும்?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) மொழிபெயர்ப்புடன் முயற்சி செய்யவும்:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) கோப்பை திறந்து கேளுங்கள்: +> - "நிஜ வானிலை API(OpenWeatherMap) யை மாதிரி தரவின் பதிலாக ஒருங்கிணைக்க எப்படி செய்மாறு செய்வேன்?" +> - "AI அதைப் பயன்படுத்த தயார் செய்து உதவும் நல்ல கருவி விளக்கம் எப்படி இருக்க வேண்டும்?" +> - "API பிழைகள் மற்றும் வீதக்கட்டுப்பாடுகளை எவ்வாறு கருவி நடைமுறையில் கையாள வேண்டும்?" ### முடிவெடுக்கும் செயல்முறை -பயனர் "சீటில் வானிலை எப்படி?" என்று கேட்டால், மாதிரி வெகுவகை கருவிகளுக்கு தற்சமயம் கருவியை சர்வே செய்யாது. அது பயனர் நோக்கத்தை ஒவ்வொரு கருவியின் விளக்கத்துடனும் ஒப்பிட்டு, பொருத்தத்திற்கான மதிப்பெண்களை ოomp மற்றும் சிறந்த ஒன்றை தேர்வு செய்கிறது. பிறகு அமைப்புப் பாடல் கொண்ட செயல்பாட்டுக் கூற்று உருவாக்குகிறது — இங்கு `location`-ஐ `"Seattle"` என அமைக்கிறது. +பயனர் "Seattle இல் வானிலை என்ன?" என்று கேட்டால், மாதிரி தற்செயலாக கருவியை தேர்ந்தெடுக்கவில்லை. அது பயனர் நோக்கத்தை ஒவ்வொரு கருவி விளக்கத்துடன் ஒப்பிட்டு, பொருத்தத்தின்படி மதிப்பெண்கள் அளித்து சிறந்த பொருத்தம் உள்ள கருவியை தேர்ந்தெடுக்கிறது. பின்னர் சரியான அளவுருக்களுடன் கட்டமைக்கப்பட்ட செயல்பாடு அழைப்பை உருவாக்குகிறது — இந்நிலையில் `location` ஐ `"Seattle"` ஆக அமைக்கிறது. -பயனர் கோரிக்கைக்கு பொருத்தமான கருவி இல்லையெனில் மாடல் தனது அறிவில் இருந்து பதில் அளிக்கிறது. பல கருவிகள் பொருந்தினால், மிகக் குறிப்பிட்ட ஒரு கருவியை தேர்வு செய்யும். +பயனரின் கோரிக்கைக்கு பொருத்தமான கருவி இல்லையெனில், மாதிரி தனது சொந்த அறிவிலிருந்து பதிலளிக்கத் திரும்பி செய்கிறது. பல கருவிகள் பொருந்தினால், மிகவும் தனிப்பட்டதை தேர்ந்தெடுக்கிறது. -AI எது கருவி பயன்படுத்துவது என தீர்மானிக்கும் முறைக் கோப்பு +AI எப்படி எந்த கருவியை பயன்படுத்தும் தீர்மானிக்கிறது -*மாதிரி பயனர் நோக்கத்துக்கு ஏற்ப கிடைக்கும் கருவிகளைக் மதிப்பாய்வு செய்து சிறந்த ஒன்றைத் தேர்ந்தெடுக்கிறது — ஆகவே தெளிவான, குறிப்பிட்ட கருவி விளக்கங்கள் அவசியம்.* +*மாதிரி ஒவ்வொரு கிடைக்கும் கருவியையும் பயனர் நோக்கத்திற்க்கு ஒப்பிட்டு மதிப்பிடுகிறது மற்றும் சிறந்த பொருத்தத்தைக் தேர்ந்தெடுக்கிறது — அதுக்காக தெளிவான, குறிப்பிட்ட கருவி விளக்கங்கள் எழுதுவது முக்கியம்.* -### நிர்வாகம் +### நிறைவு [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot தரமான `@AiService` இடைமுகத்துடன் அனைத்து பதிவு செய்யப்பட்ட கருவிகளையும் தானாக இணைக்கிறது, LangChain4j கருவி அழைப்புகளை தானாகச் செயற்கைகிறான். பின்னணி செயல்முறையில், ஒரு முழுமையான கருவி அழைப்பு ஆறு படிகள் மூலம் செல்கிறது — பயனர் இயல்பான மொழி கேள்வியிலிருந்து இயல்பான மொழி பதிலுக்கு முழுமையாக: +ஸ்பிரிங் பூட் `@AiService` இடைமுகத்துடன் அனைத்து பதிவு செய்யப்பட்ட கருவிகளையும் தானாக இணைக்கிறது, மற்றும் LangChain4j கருவி அழைப்புகளை தானாக இயக்குகிறது. பின்னணி நிகழ்வில், பூரண கருவி அழைப்புச் செயல்முறை ஆறு படிகளாக நடைபெறும் — பயனரின் இயல்பான மொழி கேள்வியிலிருந்து இயல்பான மொழி பதிலுக்கு: -கருவி அழைப்புச் சட்டம் +கருவி அழைப்பு ஓட்டம் -*முழு வழிமுறை — பயனர் கேள்வி கேட்கிறது, மாதிரி கருவியை தேர்வு செய்கிறது, LangChain4j அதை செயல்படுத்துகிறது, மற்றும் மாதிரி முடிவை இயல்பான பதிலாக இணைக்கிறது.* +*முழுமையான ஓட்டம் — பயனர் கேள்வி கேட்கிறது, மாதிரி கருவியை தேர்ந்தெடுக்கிறது, LangChain4j அதை இயக்குகிறது, மற்றும் மாதிரி முடிவை இயல்பான பதிலில் நெய்துவைக்கிறது.* -நீங்கள் Module 00ல் உள்ள [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ஒழுங்கில் இவ்வழித்தடத்தை ஏற்கனவே பார்த்திருக்கிறீர்கள் — `Calculator` கருவிகள் அதே முறையில் அழைக்கப்பட்டன. கீழே உள்ள வரிசை வரைபடம் அந்த நேரத்தில் சமீபத்திய விளக்கத்தை அளிக்கிறது: +பின்னணியில், `AiServices` எளிமையான `Calculator` கருவிக்கு கருவி அழைப்புச் சுற்றை இயக்குகிறது. கீழேயுள்ள தொடர் வரைபடம் பின்னணியில் என்ன நடக்கிறது என்பதை தெளிவாக காட்டுகிறது: -கருவி அழைப்புச் வரிசை வரைபடம் +கருவி அழைப்புச் தொடர் வரைபடம் -*குவிக் ஸ்டார்ட் டெமோவில் இருந்து கருவி அழைப்புக் கட்டை — `AiServices` உங்கள் செய்தி மற்றும் கருவி வடிவமைப்புகளை LLM-க்கு அனுப்புகிறது, LLM `add(42, 58)` போன்ற செயல்பாட்டு கூற்றுடன் பதிலளிக்கிறது, LangChain4j உள்ளூர் `Calculator` முறையை செயல்படுத்துகிறது மற்றும் இறுதி பதிலுக்கு முடிவை திருப்புகிறது.* +*கருவி அழைப்புச் சுற்று — `AiServices` உங்கள் செய்தி மற்றும் கருவி விதிகளைக் LLMக்கு அனுப்புகிறது, LLM பதிலாக `add(42, 58)` போன்ற செயல்பாடு அழைப்பை அனுப்புகிறது, LangChain4j உள்ளூராக `Calculator` முறையை இயக்குகிறது, முடிவை இறுதி பதிலுக்காக மீண்டும் LLMக்கு அனுப்புகிறது.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) உரையாடலுடன் முயற்சி செய்க:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) திறந்து கேளுங்கள்: -> - "ReAct வடிவம் எப்படி வேலை செய்கிறது மற்றும் AI முகவர்களுக்குப் பயனுள்ளதாக இருப்பது ஏன்?" -> - "முகவர் எந்த கருவியை எப்போது பயன்படுத்த வேண்டும் என்று எவ்வாறு தீர்மானிக்கின்றான்?" -> - "ஒரு கருவி செயல்பாடு தோல்வியடையும் போது என்ன நடக்கும் — பிழைகளை வலுவாக எப்படி கையாள வேண்டும்?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) மொழிபெயர்ப்புடன் முயற்சி செய்யவும்:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) கோப்பை திறந்து கேளுங்கள்: +> - "ReAct ரூபம் எப்படி வேலை செய்கிறது, அது AI முகவர்களுக்கு ஏன் விளைவாக உள்ளது?" +> - "முகவர் எந்த கருவியை எப்போது, எந்த வரிசையில் பயன்படுத்த வேண்டும் என்று எப்படி தீர்மானிக்கிறது?" +> - "ஒரு கருவி செயலாக்கம் தோல்வியடைந்தால் என்ன நடக்கும் - பிழைகளை வலுவாக எப்படி கையாள வேண்டும்?" -### பதில் உருவாக்குதல் +### பதில் உருவாக்கம் -மாதிரி வானிலை தரவுகளைப் பெற்று பயனருக்கு இயல்பான மொழி பதிலாக வடிவமைக்கிறது. +மாதிரி வானிலை தரவை பெற்றுக் கொள்கிறது மற்றும் பயனருக்கான இயல்பான மொழி பதிலாக வடிவமைக்கிறது. -### வடிவமைப்பு: Spring Boot தானாக இணைத்தல் +### வாசல் கட்டமைப்பு: ஸ்பிரிங் பூட் தானாக இணைத்தல் -இந்த தொகுதி LangChain4j இன் Spring Boot ஒருங்கிணைப்பைப் பயன்படுத்துகிறது, `@AiService` இடைமுகங்களுடன் கூடிய. துவக்கத்தில் Spring Boot அனைத்து `@Tool` முறைகள் உள்ள ஒவ்வொரு `@Component` ஐ கண்டறிந்து, உங்கள் `ChatModel` பீன் மற்றும் `ChatMemoryProvider`-ஐ ஒரே `Assistant` இடைமுகத்தில் இணைக்கிறது, நிரல் அச்சிடும் செயல்திறன் இல்லாமல். +இந்த தொகுதி LangChain4j இன் ஸ்பிரிங் பூட் ஒருங்கிணைப்பைப் பயன்படுத்து, `@AiService` அறிவிப்புடன் இடைமுகங்களை பயன்படுத்துகிறது. துவக்கத்தில் ஸ்பிரிங் பூட் ஒவ்வொரு `@Component` இல் உள்ள `@Tool` முறைகளை, உங்கள் `ChatModel` மற்றும் `ChatMemoryProvider` ஐ கண்டறிந்து, அவற்றை ஓர் ஒருங்கிணைந்த `Assistant` இடைமுகமாக இணைக்கிறது. -Spring Boot தானாக இணைத்தல் வடிவமைப்பு +ஸ்பிரிங் பூட் தானாக இணைத்து குறியீடு கட்டமைப்பு -*@AiService இடைமுகம் ChatModel, கருவி கூறுகள் மற்றும் நினைவகத்தை இணைக்கிறது — Spring Boot அனைத்து இணைப்புகளையும் தானாக கையாள்கிறது.* +*`@AiService` இடைமுகம் ChatModel, கருவி கூறுகள், நினைவக வழங்குநரை இருவதை ஒருங்கிணைக்கிறது — ஸ்பிரிங் பூட் அனைத்தையும் தானாக இணைக்கிறது.* -கடைசி புகாரின் முழு வாழ்நிகழ்வு அமைப்பு வரைபடம் — HTTP கோரிக்கையிலிருந்து கட்டுப்பன்றருக்கு, சேவைக்கு மற்றும் தானாக இணைக்கப்பட்ட பிரதிநிதிக்குச் செல்ல, வேண்டிய கருவி அழைப்புக்கு திரும்ப: +இது அபிப்ராய வட்டடியில் முழு கோரிக்கை ஓட்டத்தை காட்டுகிறது — HTTP கோரிக்கையிலிருந்து கட்டுப்பாட்டு, சேவை மற்றும் தானாக இணைக்கப்பட்ட பிரதிநிதி வழியாக கருவி செயலாக்கம் வரையிலான தொடர்ச்சிப் படமாக: -Spring Boot கருவி அழைக்கும் வரிசை +ஸ்பிரிங் பூட் கருவி அழைப்பு தொடர் வரைபடம் -*முழுமையான Spring Boot கோரிக்கை வாழ்நிகழ்வு — HTTP கோரிக்கை கட்டுப்பட்சி மற்றும் சேவையிலிருந்து தானாக இணைக்கும் Assistant பிரதிநிதிக்கு செல்லும், இது LLM மற்றும் கருவி அழைப்புகளை தானாக ஒருங்கிணைக்கிறது.* +*முழு ஸ்பிரிங் பூட் கோரிக்கை உயிர்வட்டம் — HTTP கோரிக்கை கட்டுப்பாடு மற்றும் சேவையில் இருந்து தானாக இணைக்கப்பட்ட உதவியாளர் பிரதிநிதி வரைச் செல்லும், இது LLM மற்றும் கருவி அழைப்புகளை தானாக ஒருங்கிணைக்கிறது.* இந்த அணுகுமுறையின் முக்கிய நன்மைகள்: -- **Spring Boot தானாக இணைத்தல்** — ChatModel மற்றும் கருவிகள் தானாக சேர்க்கப்படுகிறது -- **@MemoryId வடிவம்** — தானாக அமர்வு அடிப்படையிலான நினைவக மேலாண்மை -- **ஒரே செயற்கூறு** — வளர்ச்சிக்கு சிறந்த கோப்புரிமை உடைய உதவி ஒருமுறை உருவாக்கப்படுகிறது -- **வகை-பாதுகாப்பான செயல்பாடு** — Java செயல்கள் நேரடியாக வகை மாற்றத்துடன் அழைக்கப்படுகிறது -- **பல முறை ஒருங்கிணைப்பு** — கருவி சங்கிலி தானாக கையாளப்படுகிறது -- **இரை அச்சிடும் நிரல் இல்லை** — கைமுறை `AiServices.builder()` அழைப்புகள் அல்லது நினைவக HashMap இல்லை +- **ஸ்பிரிங் பூட் தானாக இணைத்தல்** — ChatModel மற்றும் கருவிகள் தானாக இறக்குமதி செய்யப்படுகின்றன +- **@MemoryId ரூபம்** — தானாக அமர்வு அடிப்படையிலான நினைவக மேலாண்மை +- **ஏகக காரிய சிருஷ்டி** — சிறந்த செயல்திறனுக்காக உதவியாளர் ஒருமுறை உருவாக்கப்பட்டு மீண்டும் பயன்படுத்தப்படுகிறது +- **வகை-பாதுகாப்பான நிறைவு** — ஜாவா முறைகள் நேரடியாக வகை மாற்றத்துடன் அழைக்கப்படுகின்றன +- **பல-தூர ஒழுங்குமுறை** — கருவி சங்கிலியை தானாக கையாள்கிறது +- **பூஜ்ய கைமுறை** — கையால் `AiServices.builder()` அழைப்பும் நினைவக ஹாஷ்மேப்பும் தேவை இல்லை -மாற்று முறைகள் (கைமுறை `AiServices.builder()`) அதிகக் கோடுகளை தேவையாக்கிறது மற்றும் Spring Boot ஒருங்கிணைப்பு நன்மைகளை தவறவிடுகிறது. +மரபுவழி அணுகுமுறைகள் (`AiServices.builder()` கையால்) அதிக குறியீடு தேவைப்படும் மற்றும் ஸ்பிரிங் பூட் ஒருங்கிணைப்பு நன்மைகள் இழக்கப்படும். ## கருவி சங்கிலி -**கருவி சங்கிலி** — கருவி அடிப்படையிலான முகவர்களின் உண்மையான சக்தி ஒரே கேள்வியில் பல கருவிகளை தேவையாக்கும் போது தெரிகிறது. "சீட்டிலில் வானிலை என்ன பதிவை அளிக்கும்?" என்ற கேள்விக்கான விடையானது இரண்டு கருவிகளையும் கிண்டல் செய்கிறது: முதலில் `getCurrentWeather`-ஐ அழைத்து செல்சியஸ் வெப்ப நிலையை பெறுகிறது, பின்னர் அதை `celsiusToFahrenheit`-க்கு அளித்து பரிமாற்றம் செய்யவைக்கிறது — இது அனைத்தும் ஒரு உரையாடல் சுற்றத்தில் நிகழ்கிறது. +**கருவி சங்கிலி** — பல கருவிகள் தேவைப்படும் ஒரே கேள்விக்குப்பயன்மிக்க சக்தி வெளிக்காட்சியாகும். "Seattle இல் வெப்ப நிலை ஃபாரன்ஹீட்டில் என்ன?" என்று கேளுங்கள், முகவர் தானாக இரண்டு கருவிகளை சங்கிலி செய்கிறது: முதலில் `getCurrentWeather` ஐ அழைத்து செல்சியஸ் வெப்ப நிலையை பெறுகிறது, பின்னர் அந்த மதிப்பை `celsiusToFahrenheit` இற்கு அனுப்பி மாற்றம் செய்துவிடுகிறது — அனைத்தும் ஒரே உரையாடல் சுற்றில். கருவி சங்கிலி உதாரணம் -*கருவி சங்கிலி செயல்பாடு — முகவர் முதலில் getCurrentWeather-ஐ அழைக்கிறது, பிறகு செல்சியஸ் முடிவை celsiusToFahrenheit-க்கு அனுப்பி, கூடிய பதிலை வழங்குகிறது.* +*கருவி சங்கிலி செயல் — முகவர் முதலில் getCurrentWeatherஐ அழைக்கிறான், பின்னர் செல்சியஸ் முடிவை celsiusToFahrenheitக்கு அனுப்பி, கலந்த பதிலை வழங்குகிறான்.* -**மெல்லிய தோல்விகள்** — மாக் தரவில் இல்லை என்ற நகரின் வானிலை கேட்கும் போது கருவி பிழை செய்தி திரும்ப அளிக்கிறது, மற்றும் AI உதவ முடியாது என்று விளக்குகிறது, முற்றிலும் செயலிழக்காமல். கருவிகள் பாதுகாப்பாக தோல்வியடைகின்றன. கீழுள்ள வரைபடத்தில் இரண்டு அணுகுமுறைகள் ஒப்பிடப்படுகின்றன: சரியான பிழை கையாளுதலுடன், முகவர் தவறை பிடித்து உதவியுடன் பதிலளிக்கிறது; இல்லாவிட்டால் முழு பயன்பாடு முடக்கம்: +**மென்மையான தோல்விகள்** — மாதிரி தரவில் இல்லாத நகரத்தின் வானிலை கேட்கவும். கருவி பிழை செய்தி திருப்பும், AI அது உதவ முடியாது என்று விளக்குகிறது; முற்றிலும் செயல்பாட்டை பாதிப்பதில்லை. கீழ்க்காணும் படத்தில், முறையான பிழை கையாளுதலுடன் முகவர் பிழையை பிடித்து விளக்கமளிப்பதை, இல்லையேல் முழு பயன்பாடு கிழிக்கிறதை ஒப்பிடுகிறது: பிழை கையாளும் ஓட்டம் -*ஒரு கருவி தோல்வியடையும் போது, முகவர் பிழையை பிடித்து பயன்பாட்டை முடக்காமல் உதவியுடன் பதில் அளிக்கிறது.* +*ஒரு கருவி தோல்வியடைந்தால், முகவர் பிழையை பிடிக்கிறது மற்றும் பயன்பாடு கிழிப்பதை தவிர்த்து உதவிகரமான விளக்கம் அளிக்கிறது.* -இது ஒரே உரையாடல் சுற்றத்தில் நடக்கிறது. முகவர் பல கருவி அழைப்புகளை தன்னிச்சையாக ஒருங்கிணைக்கிறது. +இது ஒரே உரையாடல் சுற்றில் நடக்கிறது. முகவர் பல கருவி அழைப்புகளை சுயமாக ஒருங்கிணைக்கிறது. -## விண்ணப்பத்தை இயக்கு +## விணைத்தளம் இயக்கவும் -**பணி நிலையை உறுதி செய்க:** +**அமைப்பை உறுதிசெய்யவும்:** -Module 01ல் உருவாக்கப்பட்ட Azure அங்கீகாரத்துடன் `.env` கோப்பு ரூட் கோப்பகத்தில் இருப்பதை உறுதிசெய்யவும். இந்த தொகுதியின் கோப்பகத்தில் இருந்து இயக்குக (`04-tools/`): +Module 01 இல் உருவாக்கப்பட்ட Azure அங்கீகாரங்களுடன் ரூட் கோப்புறையில் `.env` கோப்பு இருக்க வேண்டும். இந்த தொகுதி கோப்புறையிலிருந்து (`04-tools/`) இயக்கவும்: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்சியளிக்க வேண்டும் +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்டு வேண்டும் ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ஐக் காட்ட வேண்டும் +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT காட்ட வேண்டும் ``` -**விண்ணப்பத்தைத் துவக்கவும்:** +**விணைத்தளத்தை தொடங்கவும்:** -> **குறிப்பு:** நீங்கள் முந்தையதாக ரூட் கோப்பகத்தில் `./start-all.sh` மூலம் அனைத்து செயல்பாடுகளையும் துவக்கியிருந்தால் (Module 01 இல் குறிப்பிடப்பட்டபடி), இந்த தொகுதி ஏற்கனவே துவங்கியிருக்கிறது போர்ட் 8084 இல். கீழே உள்ள துவக்க கட்டளைகளைத் தவிர்த்து நேரடியாக http://localhost:8084 ஐ அணுகலாம். +> **குறிப்பு:** நீங்கள் ரூட் கோப்புறையிலிருந்து `./start-all.sh` மூலம் அனைத்து பயன்பாடுகளையும் ஏற்கனவே தொடங்கியிருந்தால் (Module 01 இல் விளக்கப்பட்டபடி), இந்த தொகுதி ஏற்கனவே 8084 போர்ட்-ல் இயங்கும். கீழ்க்காணும் தொடக்கம் கட்டளைகளை தவிர்க்கவும் மற்றும் நேர்முகமாக http://localhost:8084 செல்லவும். -**விருப்பம் 1: Spring Boot ட্যাস்போர்டைப் பயன்படுத்துதல் (VS Code பயனர்களுக்கான பரிந்துரை)** +**விருப்பம் 1: ஸ்பிரிங் பூட் டாஷ்போர்டு பயன்படுத்துதல் (VS Code பயனர்களுக்கு பரிந்துரை செய்யப்படுகிறது)** -வளவுரு கணினி Spring Boot டாஷ்போர்டு விரிவாக்கத்துடன் வருகிறது, இது அனைத்து Spring Boot செயல்பாடுகளையும் கையாளும் காட்சியமைப்பைக் கொடுக்கும். VS Code இன் இடது பக்க செயல்பாட்டு பட்டியில் (Spring Boot ஐகான் தேடவும்) இதைக் காணலாம். +Dev container இல் ஸ்பிரிங் பூட் டாஷ்போர்டு விரிவீடு உள்ளடக்கம் உள்ளது, இது அனைத்து ஸ்பிரிங் பூட் பயன்பாடுகளையும் காண நேரடி இடைமுகத்தை வழங்குகிறது. VS Code இன் இடது Activity Bar இல் ஸ்பிரிங் பூட் ஐகானை காணலாம். -Spring Boot டாஷ்போர்டில் இருந்து நீங்கள்: -- வேலைப்பளுவில் கிடைக்கும் அனைத்து Spring Boot செயல்பாடுகளையும் கண்டு கொள்ளலாம் -- ஒரு கிளிக்கில் செயல்பாடுகளைத் துவக்கி/நிறுத்தலாம் -- செயலியில் பதிவு இடம்பெற்றதை நேரடியாகப் பார்க்கலாம் -- செயலியின் நிலையை கண்காணிக்கலாம் -"tools" என்ற பெயருக்கு அடுத்துள்ள play பொத்தானை கிளிக் செய்து இந்த தொகுதியை துவங்கவும், அல்லது எல்லா தொகுதிகளையும் ஒரே நேரத்தில் துவங்கவும். +ஸ்பிரிங் பூட் டாஷ்போர்டிலிருந்து நீங்கள் செய்யக்கூடியவை: +- பணியிடத்தில் உள்ள அனைத்து ஸ்பிரிங் பூட் பயன்பாடுகளையும் பார்க்கலாம் +- ஒரே கிளிக்கில் பயன்பாடுகளை துவக்க/நிறுத்தலாம் +- பயன்பாட்டு பதிவு (லக்கள்) முற்றிலும் நேரடியாகக் காணலாம் +- பயன்பாட்டு நிலையை கண்காணிக்கலாம் -VS Code இல் Spring Boot டாஷ்போர்டு இவ்வாறு இருக்கும்: +இயக்க பத்தி அருகே உள்ள பிளே பொத்தானை கிளிக் செய்து இந்த தொகுதியைத் தொடங்கலாம், அல்லது அனைத்து தொகுதிகளையும் ஒரே நேரத்தில் துவங்கலாம். -Spring Boot Dashboard +இதோ VS Code இல் ஸ்பிரிங் பூட் டாஷ்போர்டு எப்படி தெரிகிறது: +Spring Boot டாஷ்போர்டு -*VS Code இல் Spring Boot டாஷ்போர்ட் — எல்லா தொகுதிகளையும் ஒரே இடத்திலிருந்து துவக்கவும், நிறுத்தவும் மற்றும் கண்காணிக்கவும்* +*VS Code-இல் Spring Boot டாஷ்போர்டு — எல்லா மொட்யூல்களையும் ஒரு இடத்தில் துவக்கவும், நிறுத்தவும், கண்காணிக்கவும்* -**விருப்பம் 2: ஷெல் ஸ்கிரிப்ட்கள் பயன்படுத்துதல்** +**விருப்பம் 2: ஷெல்ல் ஸ்கிரிப்ட்கள் பயன்படுத்துதல்** -எல்லா வலை செயலிகளையும் (01-04 தொகுதிகள்) துவங்கவும்: +எல்லா வலை பயன்பாடுகளையும் துவங்கவும் (மொட்யூல்கள் 01-04): **Bash:** ```bash -cd .. # ரூட் அடைவு இருந்து +cd .. # ரூட் அடைவைத் தொடங்கி ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # மூல கோப்புறை இருந்து +cd .. # ரூட் கோப்புறையிலிருந்து .\start-all.ps1 ``` -அல்லது இந்த தொகுதியையேத் துவங்கவும்: +அல்லது இந்த மொட்யூல் மட்டும் துவங்கவும்: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -இரு ஸ்கிரிப்ட்களும் தானாகவே மூல `.env` கோப்பில் இருந்து சூழல் மாறிகளைக் கொண்டு, JAR கோப்புகள் இல்லையெனில் அவற்றை கட்டும். +இரு ஸ்கிரிப்ட்களும் மூலம் `.env` கோப்பிலிருந்து சுற்றுச் சூழல் மாறிலிகளை தானாக ஏற்றும் மற்றும் JARகள் இல்லாவிட்டால் அவைகளை கட்டும். -> **குறிப்பு:** நீங்கள் அனைத்து தொகுதிகளையும் துணை முறையில் கட்டி பின்னர் துவங்க விருப்பப்பட்டால்: +> **குறிப்பு:** துவங்குவதற்கு முன் அனைத்து மொட்யூல்களையும் கையேடு முறையில் கட்ட விரும்பினால்: > > **Bash:** > ```bash @@ -278,110 +278,110 @@ cd 04-tools **Bash:** ```bash -./stop.sh # இந்த தொகுதி மட்டுமே +./stop.sh # இந்த தொகுதி மட்டும் # அல்லது cd .. && ./stop-all.sh # அனைத்து தொகுதிகளும் ``` **PowerShell:** ```powershell -.\stop.ps1 # இந்த மொட்யூல் மட்டும் +.\stop.ps1 # இந்த தொகுதி மட்டும் # அல்லது -cd ..; .\stop-all.ps1 # அனைத்து மொட்யூல்கள் +cd ..; .\stop-all.ps1 # அனைத்து தொகுதிகள் ``` ## பயன்பாட்டைப் பயன்படுத்துதல் -இந்த பயன்பாடு வலை முகாமைக் கொடுக்கிறது, அதில் நீங்கள் வானிலை மற்றும் வெப்ப நிலை மாற்றும் கருவிகளுடன் இணைந்துள்ள AI முகவருடன் தொடர்பு கொள்ளலாம். முகாம் இவ்வாறு தோற்றம் பெறுகிறது — அதில் விரைவான துவக்க உதாரணங்கள் மற்றும் பணிப்படை அனுப்பும் உரையாடல் வார்டு உள்ளது: +பயன்பாடு ஒரு வலை இடைமுகத்தை வழங்குகிறது, அங்கு நீங்களும் வானிலை மற்றும் வெப்பமதிப்பீடு கருவிகளுக்கு அணுகல் உடைய ஒரு AI முகவரியுடன் தொடர்பு கொள்ள முடியும். இடைமுகம் இதோத் தோற்றம் கொண்டுள்ளது — இதில் விரைவு துவக்க உதாரணங்களும் கோரிக்கைகளை அனுப்புவதற்கான உரையாடல் பலகையும் உள்ளது: -AI Agent Tools Interface +AI முகவர் கருவிகள் இடைமுகம் -*AI முகவர் கருவிகள் இடைமுகம் - விரைவான உதாரணங்கள் மற்றும் கருவிகளுடன் தொடர்பு கொள்ள உரையாடல் இடைமுகம்* +*AI முகவர் கருவிகள் இடைமுகம் - விரைவு உதாரணங்கள் மற்றும் கருவிகளுடன் தொடர்பு கொள்ள உரையாடல் இடைமுகம்* -### எளிய கருவி பயன்பாட்டை முயற்சி செய்யவும் +### எளிய கருவி பயன்பாட்டை முயற்சி செய்க -எளிய கோரிக்கையுடன் துவங்கவும்: "100 டிகிரி ஃபாரன்ஹீட்-ஐ செல்சியஸாக மாற்று". முகவர் வெப்ப நிலை மாற்றும் கருவி தேவையானது என்பதை அறிந்து, சரியான அளவுகளுடன் அதை அழைத்து முடிவை வழங்குகிறது. இது எவ்வளவு இயல்பாக உள்ளது என்பதை கவனிக்கவும் - நீங்கள் எந்த கருவியை பயன்படுத்த வேண்டும் அல்லது எப்படிக் கூப்பிட வேண்டும் என்று குறிப்பிடவில்லை. +எளிய கோரிக்கையுடன் துவங்குங்கள்: "100 டிகிரி பாரன்ஹீட்-ஐ செல்சியஸுக்கு மாற்று". முகவர் வெப்பமதிப்பீடு கருவி தேவை என்று அடையாளம் காண்கிறது, சரியான பரிமாற்றங்களுடன் அதை அழைக்கிறது மற்றும் முடிவை திருப்புகிறது. இது எவ்வளவு இயல்பான அனுபவம் என்பதை கவனியுங்கள் - நீங்கள் எந்த கருவியை பயன்படுத்துவது அல்லது அதை எப்படி அழைப்பது என்று குறிப்பிடவில்லை. -### கருவி சங்கிலியைச் சோதிக்கவும் +### கருவி சங்கிலி சோதனை செய்யுங்கள் -இப்போது சிறிது சிக்கலானதை முயற்சிக்கவும்: "சியாட்டிலில் வானிலை என்ன மற்றும் அதை ஃபாரன்ஹீட்டுக்கு மாற்று?" முகவர் இதை படிப்படியாக செய்கின்றது. முதலில் வானிலை பெறுகிறது (இதன் முடிவு செல்சியஸ்), அதன்பின் ஃபாரன்ஹீட்டுக்கு மாற்ற வேண்டும் என்பதை உணர்ந்து, மாற்றும் கருவியைக் கூப்பிடுகிறது மற்றும் இரண்டும் ஒரே பதிலாக சேர்க்கிறது. +இப்போது சற்று சிக்கலானதை முயற்சி செய்யுங்கள்: "சியாட்டிலை வானிலை என்ன, அதை பாரன்ஹீட்டுக்கு மாற்றவும்?". முகவர் இதை படிகளாகச் செய்கிறது. முதலில் வானிலை (செல்சியஸ் திருப்புகிறது) பெறுகிறது, பாரன்ஹீตรுக்கு மாற்ற வேண்டும் என்று கண்டுபிடிக்கிறது, மாற்று கருவியை அழைக்கிறது, மற்றும் இரு முடிவுகளையும் ஒன்றாக சேர்க்கிறது. -### உரையாடல் ஓட்டத்தை காண்க +### உரையாடல் ஓட்டத்தை பார்க்கவும் -உரையாடல் இடைமுகம் உரையாடல் வரலாற்றை பராமரிக்கிறது, இதனால் நீங்கள் பல முறை தொடர்பு கொள்ள முடியும். நீங்கள் முந்தைய அனைத்து கேள்விகளையும் பதில்களையும் பார்க்க முடியும், இது உரையாடலை பின்தொடரவும் முகவர் எவ்வாறு பல முறை பரிமாற்றங்களில் சூழலை உருவாக்குகிறான் என்பதை புரிந்துகொள்ளவும் எளிதாகும். +உரையாடல் இடைமுகம் உரையாடல் வரலாற்றை பராமரிக்கிறது, இதனால் நீங்கள் பல முறை தொடர்புகளை நிகழ்த்தலாம். முன்்பு அனைத்து கேள்விகளையும் பதில்களையும் காணலாம், உரையாடலை பின்பற்றவும் முகவர் பல முறை பரிமாற்றங்களில் சந்தர்ப்பத்தை எவ்வாறு உருவாக்குகிறதென்பதை புரிந்து கொள்ளவும் இது உதவுகிறது. -Conversation with Multiple Tool Calls +பல கருவி அழைப்புகளுடன் உரையாடல் -*எளிய மாற்றங்கள், வானிலை தேடல்கள் மற்றும் கருவி சங்கிலி காட்டும் பல-முறை உரையாடல்* +*எளிய மாற்றங்கள், வானிலை தேடல்கள் மற்றும் கருவி சங்கிலி ஆகியவற்றைக் காட்டும் பல முறை உரையாடல்* -### வெவ்வேறு கோரிக்கைகளுடன் முயற்சி செய்யவும் +### வேறுபட்ட கோரிக்கைகளை முயற்சி செய்யுங்கள் -பல்வேறு வகைகள் முயற்சிக்கவும்: -- வானிலை தேடல்கள்: "டோக்கியோவின் வானிலை என்ன?" -- வெப்ப நிலை மாற்றங்கள்: "25°C என்பது கேல்வினில் कितना?" -- கலந்துகொண்டு கேட்கல்: "பாரீஸில் வானிலைச் சரிபார்த்து, 20°C-க்கு மேல் உள்ளது எனச் சொல்லவும்" +பல்வேறு கலவைகளை முயற்சி செய்யுங்கள்: +- வானிலை தேடல்கள்: "டோக்கியோவில் வானிலை என்ன?" +- வெப்ப மாற்றங்கள்: "25°C என்பது கேல்வினில் என்ன?" +- கூட்டு கேள்விகள்: "பாரிஸில் வானிலை சரிபார்க்கவும், அது 20°Cக்கு மேல் என்றால் சொல்லவும்" -முகவர் இயல்பான மொழியை எப்படி வகைப்படுத்தி சரியான கருவிகளுக்கு அழைப்பது என்பதை கவனிக்கவும். +முகவர் இயற்கை மொழியை எவ்வாறு புரிந்து கொண்டு பொருத்தமான கருவி அழைப்புகளுக்கு மாற்றுகிறதோ கவனியுங்கள். -## முக்கிய கருத்துக்கள் +## முக்கியக் கொள்கைகள் -### ReAct மாதிரி (விவேகமும் செயலும்) +### ReAct மாதிரி (கருத்து விளக்கம் மற்றும் செயல்பாடு) -முகவர் விவேகம் (எதை செய்ய வேண்டும் என்று முடிவு) மற்றும் செயல் (கருவிகளை பயன்படுத்துதல்) முறை மாறிவருகிறது. இந்த மாதிரி வழிமுறைகளைப் பின்பற்றாமல் சுயமாக பிரச்சனைகளை தீர்க்க உதவுகிறது. +முகவர் முடிவெடுக்கும் (எதை செய்ய வேண்டும்) மற்றும் செயல்படும் (கருவிகளை பயன்படுத்தும்) இடையே மாறி செயல்படுகிறார். இந்த மாதிரி தன்னாட்சி பிரச்சனை தீர்க்குதலை இயக்குகிறது, மறு உத்தரவ்களைப் பதிலளிப்பதில்லை. -### கருவி விவரங்கள் முக்கியம் +### கருவி விளக்கங்கள் முக்கியம் -உங்கள் கருவி விவரங்களின் தரம் முகவர் அவற்றைப் பயன்படுத்தும் திறனை நேரடியாக பாதிக்கிறது. தெளிவான, குறிப்பிட்ட விவரங்கள் மொத்த மாதிரியால் எப்போது மற்றும் எப்படிக் கூப்பிட வேண்டும் என்பதை புரிந்து கொள்வதில் உதவும். +உங்கள் கருவி விளக்கங்களின் தரம் முகவர் அவற்றை எவ்வாறு பயன்படுத்துவதை நேரடியாக பாதிக்கிறது. தெளிவான, குறிப்பிட்ட விளக்கங்கள் மாதிரியை எப்போது, எப்படி ஒவ்வொரு கருவியையும் அழைக்க வேண்டும் என்பதைப் புரிந்து கொள்ள உதவுகிறது. -### அமர்வு முகாமை +### அமர்வு மேலாண்மை -`@MemoryId` குறியீடு தானாக அமர்வு அடிப்படையிலான நினைவக ஆளுமையை இயக்கும். ஒவ்வொரு அமர்வுக்கான அடையாளத்திற்கும் தனியான `ChatMemory` மாதிரி `ChatMemoryProvider` மூலம் நிர்வகிக்கப்படுகிறது, இதனால் பல பயனர்கள் ஒரே சமயம் முகவருடன் தொடர்பு கொண்டு அவர்களது உரையாடல்கள் கலக்காமல் இருக்கும். கீழ்காணும் படமоу பல பயனர்கள் எவ்வாறு வேறுபட்ட நினைவகத்தில் வழிமுறை பெறுகிறார்கள் என்பதைக் காட்டுகிறது: +`@MemoryId` குறிப்பு தானாக அமர்வு அடிப்படையிலான நினைவக மேலாண்மையை இயக்கு சத்தியமாக உள்ளது. ஒவ்வொரு அமர்விற்கும் தனித்த `ChatMemory` உதவிக்குறிப்பு உள்ளது, இது `ChatMemoryProvider` பீனால் மேலாண்மை செய்யப்படுகிறது, எனவே பல பயனர்கள் ஒரே நேரத்தில் முகவருடன் கலந்துரையாடலாம் ஆனால் அவர்களது உரையாடல்கள் கலந்துகொள்ளாது. கீழுள்ள வரைபடம் அவற்றை காட்டுகிறது: -Session Management with @MemoryId +@MemoryId உடன் அமர்வு மேலாண்மை -*ஒவ்வொரு அமர்வு அடையாளமும் தனித்த உரையாடல் வரலாற்றுக்கு இணைக்கப்பட்டுள்ளது — பயனர்கள் ஒருவருக்கொருவர் செய்திகள் பார்க்க முடியாது.* +*ஒவ்வொரு அமர்வு ஐடியும் தனித்த உரையாடல் வரலாறுக்கு சென்றளிக்கப்படுகிறது — பயனர்கள் ஒருவருக்கொருவர் செய்திகளை எப்போதும் காண முடியாது.* -### பிழைகள் கையாளுதல் +### பிழை கையாளுதல் -கருவிகள் தோல்வியுறக்கூடும் — API காலாவதியாகும், அளவுருக்கள் தவறாக இருக்கலாம், வெளி சேவைகள் செயலிழக்கும். உற்பத்தித் தொழில்நுட்ப முகவர்கள் பிழை கையாளல் கொண்டிருக்க வேண்டும், அதனால் மாதிரி பிரச்சினைகளை விளக்க அல்லது மாற்று முயற்சிகளை முயற்ற முடியும், செயலியை முழுமையாக கவிழச் செய்யாது. கருவி தோற்றுக்கையான போது, LangChain4j அது கொண்டு வரும் பிழை செய்தியைப் பெற்றுக்கொண்டு மாதிரிக்குத் திருப்பி அளித்து, இயல்பான மொழியில் பிரச்சினையை விளக்க உதவுகிறது. +கருவிகள் தோல்வி அடைவதுண்டல்லவா — APIகள் நேரம் கடந்துவிடலாம், பரிமாற்றங்கள் தவறாக இருக்கலாம், வெளிப்புற சேவைகள் செயல்படாமல் போகலாம். உற்பத்தி முகவர்களுக்கு பிழை கையாளுதலும் அவசியம், இதனால் மாதிரி பிரச்சனையை விளக்க அல்லது மாற்று முயற்சிகளை செய்ய முடியும், முழு பயன்பாடு முற்றிலும் வேலைநிறுத்தப்படாமல். கருவி தவறு ஏற்பட்டால் LangChain4j அதை பிடித்து பிழை செய்தியைக் மாதிரிக்கு திருப்பிவிடுகிறது, அது இனிய மொழியில் பிரச்சனையை விளக்க முடியும். ## கிடைக்கும் கருவிகள் -கீழ்காணும் படத்தில் நீங்கள் கட்டக்கூடிய கருவிகளின் பரந்த சூழல் காட்டப்பட்டுள்ளது. இந்த தொகுதி வானிலை மற்றும் வெப்ப நிலை கருவிகளை காட்டுகிறது, ஆனால் `@Tool` மாதிரி எந்த Java முறைமையையும் — தரவுத்தள விசாரணைகள் முதல் செலுத்தும் செயலி வரை — செயல்படுத்தும். +கீழேயுள்ள வரைபடம் நீங்கள் கட்டக்கூடிய கருவிகள் பரபரப்பான சூழலை காட்டுகிறது. இந்த மொட்யூல் வானிலை மற்றும் வெப்ப கருவிகளை காட்டுகிறது, ஆனால் அதே `@Tool` மாதிரி எந்த ஜாவா முறைக்கும் பொருந்தும் — தரவுத்தள வினவல்களுக்கு தொடங்கிச் செலுத்துதல் வரை. -Tool Ecosystem +கருவி சூழல் -*@Tool குறியீட்டுடன் எந்த Java முறைமைவும் AIக்குப் பயன்படக்கூடியது — இந்த மாதிரி தரவுத்தளங்கள், APIகள், மின்னஞ்சல், கோப்பு பணிகள் மற்றும் பிறவற்றுக்கு விரிவடைகிறது.* +*@Tool குறிக்கப்பட்ட எந்த ஜாவா முறை AIக்கு கிடைக்கும் — இந்த மாதிரி தரவுத்தளங்கள், APIகள், மின்னஞ்சல், கோப்பு செயல்பாடுகள் மற்றும் பலவற்றுக்கு நீடிக்கிறது.* -## எப்போது கருவி அடிப்படையிலான முகவர்களைப் பயன்படுத்த வேண்டும் +## கருவி அடிப்படையிலான முகவர்களை எப்போது பயன்படுத்துவது -எல்லா கோரிக்கைகளும் கருவிகள் தேவையில்லை. முடிவு AI வெளிப்புற அமைப்புகளுடன் தொடர்பு கொள்ள வேண்டுமா அல்லது தனது அறிவிலிருந்து பதில் அளிக்க முடியும் என்பதைக் கொண்டு வரும். கீழ்காணும் வழிகாட்டி எப்போது கருவிகள் மதிப்பை கூட்டுகின்றன மற்றும் எப்போது அவை தேவையில்லை என்பதை சுருக்கமாக காட்சியளிக்கிறது: +ஒவ்வொரு கோரிக்கையும் கருவிகள் தேவையில்லை. முடிவு AI வெளிப்புற முறைமைகளுடன் தொடர்பு கொள்ள வேண்டுமா அல்லது தனது அறிவிலிருந்து பதிலளிக்க முடியுமா என்பது அடிப்படையில் உறுதிப்படுத்தப்படுகிறது. கீழுள்ள வழிகாட்டி எப்போது கருவிகள் மதிப்பைக் கூட்டுகின்றன மற்றும் எப்போது அவை தேவையற்றவையாக இருக்கின்றன என்பதை சுருக்கமாகக் காட்டுகிறது: -When to Use Tools +கருவிகள் எப்போது பயன்படுத்துவது -*உருவாக்கத்திற்கான விரைவு முடிவு வழிகாட்டி — கருவிகள் நேரடி தரவு, கணக்கீடுகள் மற்றும் செயல்பாடுகளுக்கு; பொது அறிவு மற்றும் படைப்பு பணிகளுக்கு அவை தேவையில்லை.* +*விரைவு முடிவு வழிகாட்டி — கருவிகள் நேரடி தரவு, கணக்கீடுகள் மற்றும் செயல்கள், பொது அறிவும் படைப்பாற்றலும் தேவையில்லை.* -## கருவிகள் மற்றும் RAG +## கருவிகள் vs RAG -03 மற்றும் 04 தொகுதிகள் இரண்டும் AIக்கு திறனைக் கூட்டுகின்றன, ஆனால் அடிப்படையாக வெவ்வேறு முறையில். RAG மாதிரிக்கு **அறிவு** கிடைக்கும் ஆவணங்களை மீட்கும் மூலமாக. கருவிகள் மாதிரிக்கு செயல்களைச் செய்யும் திறனை வழங்கும் முறையாகும். கீழ்காணும் படத்தில் ஒப்பிடப்பட்டுள்ளது — ஒவ்வொரு வேலைப்பாட்டும் எப்படி இயங்குகின்றது மற்றும் அவற்றுக்கிடையேயான வியாபாரத் திட்டங்கள்: +மொட்யூல்கள் 03 மற்றும் 04 இரண்டும் AI திறன்களை விரிவுபடுத்துகின்றன, ஆனால் அடிப்படையில் வேறுபட்ட முறைகளில். RAG மாதிரி **அறிவைப் பெற்று** ஆவணங்களை மீட்டெடுக்கும் சக்தியை அளிக்கிறது. கருவிகள் மாதிரி **செயற்பாடுகளை எடுக்கும்** திறனை வழங்கும். கீழுள்ள வரைபடம் இரு அணுகுமுறைகளையும் ஒப்பிடுகிறது — ஒவ்வொரு பணிமுறையும் எவ்வாறு இயங்குகிறது மற்றும் அவற்றிற்குள்ள முரண்பாடுகள்: -Tools vs RAG Comparison +கருவிகள் vs RAG ஒப்புமை -*RAG நிலையான ஆவணங்களில் இருந்து தகவலை பெறுகிறது — கருவிகள் செயல்களைச் செய்து நேரடி, தானாக தரவை பெற்று வருகின்றன. பல உற்பத்தித் தொழில்நுட்பங்கள் இரண்டும் சேர்த்து பயன்படுத்தப்படுகின்றன.* +*RAG நிலையான ஆவணங்களில் இருந்து தகவலை மீட்டெடுக்கிறது — கருவிகள் நடவடிக்கைகளை செய்கிறது மற்றும் திடீர், நேரடி தரவை எடுக்கிறது. பல உற்பத்தி முறைமைகள் இரண்டையும் இணைக்கின்றன.* -நிகழ்வு நேரத்தில், பல உற்பத்தித் தொழில்நுட்பங்கள் இரு அணுகுமுறைகளையும் சேர்த்து பயன்படுத்துகின்றன: உங்கள் ஆவணங்களில் பதில்களை அடிப்படையாக்க RAG மற்றும் நேரடி தரவு பெற அல்லது செயல்பாடுகளை செய்ய கருவிகள். +வாஸ்தவத்தில், பல உற்பத்தி முறைமைகள் இரண்டையும் சேர்த்து பயன்படுத்துகின்றன: RAG உங்கள் ஆவணத்தில் பதில்களை நிலைப்படுத்த, கருவிகள் நேரடி தரவை பெற அல்லது செயல்பாடுகளைச் செய்ய. ## அடுத்த படிகள் -**அடுத்து: [05-mcp - மாதிரி சூழல் நியமனம் (MCP)](../05-mcp/README.md)** +**அடுத்த மொட்யூல்:** [05-mcp - மாடல் உருவக்கூறு நடைமுறை (MCP)](../05-mcp/README.md) --- -**வழிசெலுத்தல்:** [← முந்தைய: தொகுதி 03 - RAG](../03-rag/README.md) | [மீண்டும் முதன்மை பக்கம்](../README.md) | [அடுத்து: தொகுதி 05 - MCP →](../05-mcp/README.md) +**நெவிகேஷன்:** [← முந்தையது: மொட்யூல் 03 - RAG](../03-rag/README.md) | [முதல் பக்கத்திற்கு](../README.md) | [அடுத்து: மொட்யூல் 05 - MCP →](../05-mcp/README.md) --- -**புறக்கணிப்பு**: -இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) பயன்படுத்தி மொழி மாற்றப்பட்டதாகும். நாம் சீரான மொழிபெயர்ப்பிற்கு முயலுகிறாலும், தானாக இயங்கும் மொழிபெயர்ப்புகளில் பிழைகள் அல்லது துல்லியமின்மைகள் இருக்கக்கூடும் என்பதனை கவனிக்கவும். பதிவேற்றப்பட்ட மொழியில் உள்ள மூல ஆவணம் கொண்டது அதிகாரபூர்வமான மூல ஆதாரமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழிலைப்புரிதல் மனித மொழிபெயர்ப்பை பரிந்துரைக்கிறோம். இந்த மொழிபெயர்ப்பைப் பயன்படுத்துவதில் ஏற்படும் தவறான புரிதல்கள் அல்லது தவறான அர்த்தமளிப்புகளுக்கு எங்களை பொறுப்பேற்க இயலாது. +**மறுப்பு**: +இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. நாங்கள் துல்லியத்திற்காக முயற்சி செய்துள்ளோம், ஆனால் தானாக செய்யப்படும் மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கலாம் என்பதை கவனத்தில் கொள்ளவும். அசல் ஆவணம் அதன் தாய்மொழியில் அதிகாரப்பூர்வ ஆதாரமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழில்நுட்பமான மனித மொழிபெயர்ப்பு பரிந்துரைக்கப்படுகிறது. இந்த மொழிபெயர்ப்பைப் பயன்படுத்துவதால் ஏற்படும் எந்த தவறான புரிதல்கள் அல்லது தவறான விளக்கத்திற்கும் நாங்கள் பொறுப்பில்வில்லை. \ No newline at end of file diff --git a/translations/ta/README.md b/translations/ta/README.md index fd4e41bd2..a779dd6de 100644 --- a/translations/ta/README.md +++ b/translations/ta/README.md @@ -1,19 +1,19 @@ LangChain4j -# புதியவர்களுக்கான LangChain4j +# LangChain4j துவக்கத்திற்கு -தொடக்க அளவிலான உரையாடலிலிருந்து AI முகவர்கள் வரை LangChain4j மற்றும் Azure OpenAI GPT-5.2 உடன் AI பயன்பாடுகளை உருவாக்கும் பாடநெறி. +LangChain4j மற்றும் Azure OpenAI GPT-5.2 உடன் AI பயன்பாடுகளை கட்டியமைக்கும் ஒரு பாடநெறி, அடிப்படையான அரட்டை முதல் AI முகவர்கள் வரை. ### 🌐 பன்மொழி ஆதரவு -#### GitHub Action மூலம் ஆதரிக்கப்படுகிறது (தானியங்கிய மற்றும் எப்போதும் עדכון) +#### GitHub Action மூலம் ஆதரிக்கப்படுகிறது (தானாகவும் எப்போதும் புதுப்பிக்கப்படுவதாகவும்) -[ஆரபிக்](../ar/README.md) | [பெங்காலி](../bn/README.md) | [பல்கேரியன்](../bg/README.md) | [பெருமியின் (மியான்மார்)](../my/README.md) | [சீன மொழி (சுருங்கப்பட்ட)](../zh-CN/README.md) | [சீன மொழி (சம்பிரதாய, ஹாங்காங்)](../zh-HK/README.md) | [சீன மொழி (சம்பிரதாய, மக்காவ்)](../zh-MO/README.md) | [சீன மொழி (சம்பிரதாய, தைவான்)](../zh-TW/README.md) | [குரோஷியன்](../hr/README.md) | [செக்](../cs/README.md) | [டேனிஷ்](../da/README.md) | [டச்சு](../nl/README.md) | [எஸ்டோனியன்](../et/README.md) | [பின்னிஷ்](../fi/README.md) | [பிரெஞ்சு](../fr/README.md) | [ஜெர்மன்](../de/README.md) | [கிரேக்கம்](../el/README.md) | [ஹீப்ரு](../he/README.md) | [ஹிந்தி](../hi/README.md) | [ஹங்கேரியன்](../hu/README.md) | [இந்தோனேஷியன்](../id/README.md) | [இத்தாலியன்](../it/README.md) | [ஜப்பானீஸ்](../ja/README.md) | [கன்னடம்](../kn/README.md) | [க்வெமர்](../km/README.md) | [கொரியன்](../ko/README.md) | [லிதுவேனியன்](../lt/README.md) | [மலாய்](../ms/README.md) | [மலையாளம்](../ml/README.md) | [மராத்தி](../mr/README.md) | [நெபாளி](../ne/README.md) | [நைஜீரியன் பிட்ஜின்](../pcm/README.md) | [நோர்வேஜியன்](../no/README.md) | [பெர்ஷியன் (ஃபார்சி)](../fa/README.md) | [போலீஷ்](../pl/README.md) | [போர்ச்சுகீஸ் (பிரேசில்)](../pt-BR/README.md) | [போர்ச்சுகீஸ் (போர்ச்சுகல்)](../pt-PT/README.md) | [பஞ்சாபி (குருமுகி)](../pa/README.md) | [ரோமானியன்](../ro/README.md) | [ரஷ்யன்](../ru/README.md) | [செர்பியன் (சிரிலிக்)](../sr/README.md) | [ஸ்லோவாக்](../sk/README.md) | [ஸ்லோவேனியன்](../sl/README.md) | [ஸ்பானிஷ்](../es/README.md) | [ஸ்வாஹிலி](../sw/README.md) | [ஸ்வீடிஷ்](../sv/README.md) | [தகாலொக் (பிலிப்பினோ)](../tl/README.md) | [தமிழ்](./README.md) | [தெலுங்கு](../te/README.md) | [தை](../th/README.md) | [துருக்கி](../tr/README.md) | [உக்ரைனியன்](../uk/README.md) | [உருது](../ur/README.md) | [வியேட்னாமீஸ்](../vi/README.md) +[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](./README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **உள்ளூர் கிளோன் செய்ய விரும்புகிறீர்களா?** +> **உள்ளூர் க்ளோன் செய்வதற்கு விருப்பமா?** > -> இந்த களஞ்சியம் 50+ மொழி மொழிபெயர்ப்புகள் அடங்கியுள்ளதனால் பதிவிறக்கம் அளவு பெரிதாகும். மொழிபெயர்ப்புகள் இல்லாமல் கிளோன் செய்ய விரும்பினால் sparse checkout-ஐப் பயன்படுத்துங்கள்: +> இந்த களஞ்சியம் 50+ மொழி மொழிபெயர்ப்புகளை உள்ளடக்கியது, இது பதிவிறக்க அளவை பெரிதாக அதிகரிக்கிறது. மொழிபெயர்ப்புகள் இல்லாமல் க்ளோன் செய்ய, sparse checkout பயன்படுத்தவும்: > > **Bash / macOS / Linux:** > ```bash @@ -29,122 +29,122 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> இது படிப்பை முடிக்க தேவையான அனைத்தையும் விரைவாக தருகிறது. +> இது படிப்பை முடிக்க தேவையான அனைத்தையும் மிகவும் விரைவான பதிவிறக்கத்துடன் தருகிறது. -## உள்ளடக்க அட்டவணம் +## உள்ளடக்கப் பட்டியல் -1. [விரைவான தொடக்கம்](00-quick-start/README.md) - LangChain4j உடன் துவங்குங்கள் -2. [அறிமுகம்](01-introduction/README.md) - LangChain4j அடிப்படைகளை கற்றுக்கொள்ளுங்கள் -3. [உத்தரவு பொறியியலும்](02-prompt-engineering/README.md) - பயனுள்ள உத்தரவுகள் வடிவமைப்பை ஆதிக்கமாக கொள்ளுங்கள் -4. [RAG (திருத்துக்கூடிய-மொழிமாற்றம் உருவாக்குதல்)](03-rag/README.md) - புத்திரமான அறிவுத்தளம் அமைப்புகளை கட்டியெழுப்புங்கள் -5. [கருவிகள்](04-tools/README.md) - வெளிப்புற கருவிகள் மற்றும் எளிய உதவியாளர்களை இணைத்தல் -6. [MCP (மாதிரி சூழல் நெறிமுறை)](05-mcp/README.md) - மாதிரி சூழல் நெறிமுறை மற்றும் முகவரி அலகுகளுடன் பணியாற்றுதல் +1. [அறிமுகம்](01-introduction/README.md) - LangChain4j அடிப்படைகளை கற்றுக்கொள்ளவும் +2. [அரட்டை வடிவமைப்பு](02-prompt-engineering/README.md) - பயனுள்ள அரட்டை வடிவமைப்பை கையாளவும் +3. [RAG (தகவல் மேம்படுத்தப்பட்ட உருவாக்கம்)](03-rag/README.md) - புத்திசாலித்தனமான அறிவியல் அமைப்புகளை உருவாக்கவும் +4. [கருவிகள்](04-tools/README.md) - வெளிப்புற கருவிகள் மற்றும் எளிய உதவியாளர்களை ஒருங்கிணைக்கவும் +5. [MCP (மாதிரி சூழல் நடைமுறை)](05-mcp/README.md) - மாதிரி சூழல் நடைமுறை (MCP) மற்றும் முகவர் மாட்யூல்களுடன் பணியாற்றவும் -### வீடியோ நடைமுறை +### காணொளி பயிற்சிகள் -ஒவ்வொரு அத்தியாயத்துக்கும் தொடர்புடைய நேரலை அமர்வுகள் உள்ளன, அங்கு நாங்கள் படிகள் படி கருத்துக்களையும் குறியீட்டையும் விவரிக்கிறோம். +ஒவ்வொரு மோட்டியூலும் ஒரு இணை நேர்காணல் அமர்வைக் கொண்டுள்ளது, அங்கே நாங்கள் கோடுகள் மற்றும் யூகங்களை படி படியாக நடத்துகிறோம். -| அத்தியாயம் | வீடியோ | +| மோட்டியூல் | காணொளி | |--------|-------| -| 01 - அறிமுகம் | [LangChain4j உடன் துவங்குதல்](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - உத்தரவு பொறியியல் | [LangChain4j உடன் உத்தரவு பொறியியல்](https://www.youtube.com/live/PJ6aBaE6bog) | +| 01 - அறிமுகம் | [LangChain4j உடன் தொடங்குதல்](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - அரட்டை வடிவமைப்பு | [LangChain4j உடன் அரட்டை வடிவமைப்பு](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [LangChain4j உடன் RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - கருவிகள் & 05 - MCP | [கருவிகள் மற்றும் MCP உடன் AI முகவர்கள்](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## கற்றல் பாதை +## கற்றல் பாதை -**LangChain4j-க்கு புதியவரா?** முக்கியச் சொற்கள் மற்றும் கருத்துகளுக்கு [பதிவு பட்டியல்](docs/GLOSSARY.md) ஐப் பாருங்கள். +**LangChain4j இல் புதியவரா?** முக்கிய சொற்கள் மற்றும் யூகங்களுக்கான விவரணைகளுக்கு [அகராதி](docs/GLOSSARY.md) பாருங்கள். -> **விரைவான தொடக்கம்** +> **விரைவு தொடக்கம்** -1. இந்த களஞ்சியத்தை உங்கள் GitHub கணக்கில் Fork செய்யவும் -2. **Code** → **Codespaces** tab → **...** → **New with options...** என்பதைக் கிளிக் செய்யவும் -3. இயல்புகளை பயன்படுத்தவும் – இது இந்த பாடநெறிக்கான Development container-ஐத் தேர்ந்தெடுக்கும் -4. **Create codespace** என கிளிக் செய்யவும் -5. சூழல் தயாராகும் வரை 5-10 நிமிடங்கள் காத்திருக்கவும் -6. ஆரம்பிக்க [விரைவான தொடக்கம்](./00-quick-start/README.md) இணைப்பிற்கு நேரடியாக செல்லுங்கள்! +1. இந்த களஞ்சியத்தை உங்கள் GitHub கணக்குக்கு ஒட்டவும் +2. **Code** → **Codespaces** தாவலை கிளிக் செய்யவும் → **...** → **New with options...** தேர்வு செய்யவும் +3. இயல்புகளை பயன்படுத்தவும் – இதில் இந்த பாடநெறிக்கான Development கன்டெய்னர் தேர்வு செய்யப்படும் +4. **Create codespace** கிளிக் செய்யவும் +5. சூழல் தயாராக 5-10 நிமிடங்கள் காத்திருங்கள் +6. தொடங்க [அறிமுகம்](./01-introduction/README.md) நேரடியாக சென்று கற்கவும்! -அத்தியாயங்களை முடித்த பிறகு, LangChain4j சோதனை கருத்துக்களை செயல்படுத்த [சோதனை வழிகாட்டி](docs/TESTING.md) ஐ ஆராயவும். +மோட்டியூல்கள் முடிந்த பின், LangChain4j சோதனை யூகங்களை செயல்படுத்த [சோதனை வழிகாட்டி](docs/TESTING.md) பாருங்கள். -> **குறிப்பு:** இந்த பயிற்சி GitHub மாதிரிகள் மற்றும் Azure OpenAI இரண்டையும் பயன்படுத்துகிறது. [விரைவான தொடக்கம்](00-quick-start/README.md) அத்தியாயம் GitHub மாதிரிகளைப் பயன்படுத்துகிறது (Azure சந்தா தேவையில்லை), ஆனால் 1-5 அத்தியாயங்கள் Azure OpenAI-ஐ பயன்படுத்துகின்றன. ஆதரவற்றவர்கள் [இலவச Azure கணக்குடன்](https://aka.ms/azure-free-account) துவங்குங்கள். +> **குறிப்பு:** இந்த பயிற்சி Azure OpenAI ஐ பயன்படுத்துகிறது. ஒரு [இலவச Azure கணக்கு](https://aka.ms/azure-free-account) இல்லையென்றால், முதலில் அதில் தொடங்கவும். -## GitHub Copilot உடன் கற்று கொள்ளுதல் +## GitHub Copilot உடன் கற்றல் -குறியீடு எழுத விரைவாக ஆரம்பிக்க, இந்த திட்டத்தை GitHub Codespace-ல் அல்லது உங்கள் உள்ளூர் IDE-வில் devcontainer உடன் திறக்கவும். இந்தப் பாடநெறியில் பயன்படுத்தப்படும் devcontainer GitHub Copilot-இன் AI ஒத்துழைப்பு பணிக்கான முன் அமைப்பு கொண்டுள்ளது. +விரைவாக கோடிங் செய்ய, இந்த திட்டத்தை GitHub Codespace இல் அல்லது உங்கள் உள்ளூர் IDE இல் devcontainer உடன் திறக்கவும். இந்த பாடநெறியில் பயன்படுத்தப்படும் devcontainer GitHub Copilot உடன் முன்கூட்டியே அமைக்கப்பட்டுள்ளது, இது AI இணை புரொகிராமிங்கிற்கு உதவும். -ஒவ்வொரு குறியீடு உதாரணத்திலும் GitHub Copilot-இல் கேட்கவும் கூடிய பரிந்துரைக்கப்பட்ட கேள்விகள் உளுள்ளது, இது உங்கள் புரிதலை ஆழப்படுத்த உதவும். கீழ்க்காணும் இடங்களில் 💡/🤖 குறியடிகள் காணப்படுகின்றன: +ஒவ்வொரு கோடு எடுத்துக்காட்டும் GitHub Copilot சோதனைக் கேள்விகளுடன் வருகிறது. கீழே உள்ள 💡/🤖 குறியீடுகளை காணவும்: -- **Java கோப்பு தலைப்புகளில்** - ஒவ்வொரு உதாரணத்திற்கான குறிப்பிட்ட கேள்விகள் -- **அத்தியாய READMEகளில்** - குறியீடு உதாரணங்களுக்குப் பிறகு ஆராய்ச்சி வழிகாட்டிகள் +- **Java கோப்பு தலைப்புகள்** - ஒவ்வொரு எடுத்துக்காட்டிற்கும் தொடர்புடைய கேள்விகள் +- **மோட்டியூல் READMEகள்** - கோடு எடுத்துக்காட்டுகளுக்குப்பின் ஆராய்ச்சி கேள்விகள் -**வழிமுறை:** எந்த குறியீடு கோப்பினையும் திறந்து Copilot-இல் பரிந்துரைக்கப்பட்ட கேள்விகளை கேளுங்கள். இது குறியீட்டு தளத்தின் முழு உள்ளடக்கம் தெரியும், விளக்கலாம், விரிவாக்கலாம் மற்றும் மாற்றுகளை பரிந்துரைக்கலாம். +**எப்படி பயன்படுத்துவது:** எந்த ஒரு கோப்பையும் திறக்கவும், Copilot க்கு பரிந்துரைக்கப்பட்ட கேள்விகளை கேள். இது முழுமையான மூலக் குறியீட்டை புரிந்து, விளக்கவும் விரிவாக்கவும் மாற்று ஆலோசனைகளை வழங்கலாம். -மேலும் அறிய விரும்புகிறீர்களா? [AI ஒத்துழைப்பு பணிக்கான Copilot](https://aka.ms/GitHubCopilotAI) ஐப் பாருங்கள். +மேலும் கற்றுக்கொள்ள விரும்புகிறீர்களா? [AI இணை புரொகிராமிங்குக்கான Copilot](https://aka.ms/GitHubCopilotAI) பார்க்கவும். ## கூடுதல் வளங்கள் ### LangChain -[![புதியவர்களுக்கான LangChain4j](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![புதியவர்களுக்கான LangChain.js](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![புதியவர்களுக்கான LangChain](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / முகவர்கள் -[![புதியவர்களுக்கான AZD](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![புதியவர்களுக்கான Edge AI](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![புதியவர்களுக்கான MCP](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![புதியவர்களுக்கான AI முகவர்கள்](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Agents +[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### உருவாக்கும் AI தொடர்வு -[![புதியவர்களுக்கான உருவாக்கும் AI](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![உருவாக்கும் AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![உருவாக்கும் AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![உருவாக்கும் AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Generative AI Series +[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### முக்கியக் கற்றல் -[![புதியவர்களுக்கான எம்எல்](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![புதியவர்களுக்கான தரவு அறிவியல்](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![புதியவர்களுக்கான AI](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![ஆரம்பத்தில் இருக்கும் நபர்களுக்கான கையுறவு பாதுகாப்பு](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![ஆரம்பத்தில் இருக்கும் நபர்களுக்கான வலை வளர்ச்சி](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![ஆரம்பத்தில் இருக்கும் நபர்களுக்கான IOT](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![ஆரம்பத்தில் இருக்கும் நபர்களுக்கான XR வளர்ச்சி](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +### Core Learning +[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) ---- +[![தொடக்கக்காரர்களுக்கான வலைத் dev](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![தொடக்கக்காரர்களுக்கான IoT](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![தொடக்கக்காரர்களுக்கான XR வளர்ச்சி](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) -### கோபைலட் தொடர் -[![கோபைலட் AI கூட்டு நிரலாக்கத்திற்காக](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET க்கான கோபைலட்](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +--- + +### கோபைலட் தொடர்கள் +[![AI இணைந்தக் கோப்புறுக்கான கோபைலட்](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![C#/.NETக்கான கோபைலட்](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![கோபைலட் சாகசம்](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## உதவி பெறுதல் -நீங்கள் சிக்கலில் மிக்கிடமோ அல்லது AI பயன்பாடுகள் கட்டுமானம் பற்றி ஏதேனும் கேள்விகள் இருந்தால், சேர்ந்துகொள்ளவும்: +நீங்கள் அடைக்கலம் அடைந்தால் அல்லது AI செயலிகளைக் கட்டமைப்பதையொற்றி ஏதேனும் கேள்விகள் இருந்தால், சேர்ந்துகொள்ளவும்: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -பொருள் கருத்துக்கள் அல்லது பிழைகள் இருந்தால் கட்டுமானத்தின் போது பின்வரும் முகவரிக்கு வந்து பார்க்கவும்: +உற்பத்தியின் கருத்துகள் அல்லது பிழைகள் இருந்தால்: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## உரிமம் -MIT உரிமம் - விவரங்களுக்கு [LICENSE](../../LICENSE) கோப்பைப் பார்க்கவும். +MIT உரிமம் - விவரங்களுக்கு [LICENSE](../../LICENSE) கோப்பைச் சரிபார்க்கவும். --- -**மேற்குறிப்பு**: -இந்த ஆவணம் [Co-op Translator](https://github.com/Azure/co-op-translator) என்ற AI மொழிபெயர்ப்பு சேவையைப் பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. துல்லியத்திற்காக நாம் முயற்சிப்பதாக இருந்தாலும், தானாக மேற்கொள்ளப்படும் மொழிபெயர்ப்பு தவறுகள் அல்லது தவறான தகவல்களை கொண்டிருக்க வாய்ப்பு உள்ளதை தயவுசெய்து கவனிக்கவும். தாய்மொழியில் உள்ள அசல் ஆவணம் அதிகாரபூர்வ மூலமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழில்முறை மனித மொழிபெயர்ப்பை பரிந்துரைக்கப்படுகிறது. இந்த மொழிபெயர்ப்பின் பயன்படுத்தல் காரணமாக ஏற்பட்ட ஏதாவது தவறான புரிதல்கள் அல்லது தவறான விளக்கங்களுக்கு எங்களை பொறுப்பேற்க முடியாது. +**மறுப்பு**: +இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. நாங்கள் துல்லியத்திற்காக முயற்சி செய்துள்ளோம், ஆனால் தானாக செய்யப்படும் மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கலாம் என்பதை கவனத்தில் கொள்ளவும். அசல் ஆவணம் அதன் தாய்மொழியில் அதிகாரப்பூர்வ ஆதாரமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழில்நுட்பமான மனித மொழிபெயர்ப்பு பரிந்துரைக்கப்படுகிறது. இந்த மொழிபெயர்ப்பைப் பயன்படுத்துவதால் ஏற்படும் எந்த தவறான புரிதல்கள் அல்லது தவறான விளக்கத்திற்கும் நாங்கள் பொறுப்பில்வில்லை. \ No newline at end of file diff --git a/translations/ta/docs/GLOSSARY.md b/translations/ta/docs/GLOSSARY.md index 7e6531402..b9f4a9b84 100644 --- a/translations/ta/docs/GLOSSARY.md +++ b/translations/ta/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j முக்கிய சொற்கள் +# LangChain4j சொற்பொருள் -## உள்ளடக்கக் குறிப்பு +## உள்ளடக்கப்பட்டியல் -- [முக்கியக் கான்செப்ட்கள்](../../../docs) -- [LangChain4j கூறுகள்](../../../docs) -- [AI/ML கான்செப்ட்கள்](../../../docs) -- [காப்புரைகள்](../../../docs) -- [ப்ராம்ட் பொறியியல்](../../../docs) -- [RAG (மீட்டெடுப்பு-சேர்க்கப்பட்ட உருவாக்கம்)](../../../docs) -- [ஓஜனையாளர்கள் மற்றும் கருவிகள்](../../../docs) -- [ஓஜனையியல் தொகுதி](../../../docs) -- [மாதிரி சூழல் நெறிமுறை (MCP)](../../../docs) -- [அசுரேசேவைகள்](../../../docs) -- [சோதனை மற்றும் வளர்ச்சி](../../../docs) +- [அடிப்படை கருத்துக்கள்](#அடிப்படை-கருத்துக்கள்) +- [LangChain4j கூறுகள்](#langchain4j-கூறுகள்) +- [AI/ML கருத்துக்கள்](#aiml-கருத்துக்கள்) +- [காவல் கோடுகள்](#காவல்-கோடுகள்) +- [ப்ராம்ட் பொறியியல்](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [செயலாளர்கள் மற்றும் கருவிகள்](#agents-and-tools---module-04) +- [ஏஜென்டிக் பிரிவு](#agentic-module---module-05) +- [மாடல் வார_CONTEXT_நெறிமுறை (MCP)](#model-context-protocol-mcp---module-05) +- [அழுரு சேவைகள்](#azure-services---module-01) +- [சோதனை மற்றும் மேம்பாடு](#testing-and-development---testing-guide) -படிப்பின் பல பகுதிகளிலும் பயன்படும் சொற்கள் மற்றும் கருத்துகளுக்கான விரைவு குறிப்பு. +பாடத்தைக் காப்பீட்டுத் throughout terms மற்றும் கருத்துகளுக்கான விரைவு குறிப்பாண்மை. -## முக்கியக் கான்செப்ட்கள் +## அடிப்படை கருத்துக்கள் -**AI ஓஜனையாளர்** - தானாக சிந்தித்து செயல்படும் AI ஐ பயன்படுத்தும் அமைப்பு. [தொகுதி 04](../04-tools/README.md) +**AI Agent** - AIயைப் பயன்படுத்தி தானாகக் க்கூறிவிட்டு செயல் படுத்தும் அமைப்பு. [Module 04](../04-tools/README.md) -**சிங்காரம்** - வெளியீடு அடுத்து வரும் படிக்கு ஊட்டமாக வழங்கப்படும் செயல்பாடுகளின் தொடர்ச்சி. +**Chain** - ஒவ்வொரு படியிலும் வெளிப்படும் நுழைவு அடுத்து செயலுக்கு வழங்கப்படும் செயல்முறை தொடர்ச்சி. -**வெட்டு செய்தல்** - ஆவணங்களை சிறிய துண்டுகளாக பிரித்தல். பொதுவானது: 300-500 குறியிடிகளுடன் 겹ிமையுடன். [தொகுதி 03](../03-rag/README.md) +**Chunking** - ஆவணங்களை சிறிய துண்டுகளாகப் பிரித்தல். வழக்கம்: 300-500 குறியீடுகள் ஒட்டுமொத்தம். [Module 03](../03-rag/README.md) -**சூழல் சாளரம்** - ஒரு மாதிரிக்கு maximum tokens ப்ராசஸ் செய்யலாம். GPT-5.2: 400K tokens (272K உள்ளீடு வரை, 128K வெளியீடு வரை). +**Context Window** - ஒரு மாடல் செயலாக்கக்கூடிய அதிகபட்ச குறியீடுகள். GPT-5.2: 400K குறியீடுகள் (முழுதியும் 272K உள்ளீடு, 128K வெளியீடு). -**எம்பெட்டிங்** - உரையின் பொருளை ஒப்புள்ளி எண் வடிவத்தில் காட்டுதல். [தொகுதி 03](../03-rag/README.md) +**Embeddings** - உரையின் பொருளை பிரதிபலிக்கும் இலக்கண எண்கோவைகள். [Module 03](../03-rag/README.md) -**சேவை அழைப்பு** - மாதிரி வெளிப்புற செயல்பாடுகளை அழைக்க வடிவமைக்கப்பட்ட கோரிக்கைகளை உருவாக்குதல். [தொகுதி 04](../04-tools/README.md) +**Function Calling** - மாடல் வெளிப்படும் அமைப்புடன் வெளிப்புற செயல்பாடுகளை அழைக்கும் கோரிக்கைகளை உருவாக்கும். [Module 04](../04-tools/README.md) -**தூண்டுதல்** - மாதிரிகள் தவறான ஆனால் நம்பத்தக்க தகவலை உருவாக்கும் போது. +**Hallucination** - மாடல்கள் தவறான ஆனால் நம்பத்தகுந்த தகவல்களை உருவாக்கும் நிலை. -**ப்ராம்ட்** - மொழி மாதிரிக்கு உள்ளீட்டு உரை. [தொகுதி 02](../02-prompt-engineering/README.md) +**Prompt** - மொழி மாடலுக்கு வழங்கப்படும் உரை உள்ளீடு. [Module 02](../02-prompt-engineering/README.md) -**அர்த்தவாய்ந்த தேடல்** - முக்கிய வார்த்தைகள் இல்லை; பொருள் மற்றும் எம்பெட்டிங்குகளை பயன்படுத்தி தேடல். [தொகுதி 03](../03-rag/README.md) +**Semantic Search** - பொருள் வைத்து தேடல், முக்கியச்சொற்கள் அல்லாமல் embeddings களைப் பயன்படுத்துதல். [Module 03](../03-rag/README.md) -**நிலைத்தன்மை மற்றும் நிலைத்தன்மையற்றவை** - நிலைத்தன்மையற்றவை: நினைவில்லாமல் செயல்படுதல். நிலைத்தன்மை: உரையாடல் வரலாறை பாதுகாத்தல். [தொகுதி 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: நினைவாற்றல் இல்லாதது. Stateful: உரையாடல் வரலாற்றை வைத்திருக்கும். [Module 01](../01-introduction/README.md) -**குறியிடுகள்** - மாதிரிகள் செயல்படுத்தும் அடிப்படை உரை அலகுகள். செலவு மற்றும் வரம்புகளை பாதிக்கும். [தொகுதி 01](../01-introduction/README.md) +**Tokens** - மாடல்கள் செயலாக்கும் அடிப்படைக் கட்டிகள். செலவுகள் மற்றும் வரம்புகளை பாதிக்கும். [Module 01](../01-introduction/README.md) -**கருவி சங்கிலி** - ஒரு கருவியின் வெளியீடு அடுத்த கருவி அழைப்பிற்கு தகவலளிக்கும் தொடர் செயல்பாடு. [தொகுதி 04](../04-tools/README.md) +**Tool Chaining** - கருவிகள் தொடர் முறையில் செயல்படும் போது ஒன்றின் வெளியீடு அடுத்தஅழைப்பிற்கு தகவல் அளிக்கும். [Module 04](../04-tools/README.md) ## LangChain4j கூறுகள் -**AiServices** - வகை பாதுகாப்பான AI சேவை இடைமுகங்களை உருவாக்குகிறது. +**AiServices** - வகை-பாதுகாப்பான AI சேவை இடைமுகங்களை உருவாக்குகிறது. -**OpenAiOfficialChatModel** - OpenAI மற்றும் Azure OpenAI மாதிரிகளுக்கான ஒருமித்த கிளையண்ட். +**OpenAiOfficialChatModel** - OpenAI மற்றும் Azure OpenAI மாடல்களுக்கு ஒன்றிய காயகளர்ப்புக் கிளையன். -**OpenAiOfficialEmbeddingModel** - OpenAI அதிகாரப்பூர்வ கிளையண்ட் பயன்படுத்தி எம்பெட்டிங்குகளை உருவாக்குகிறது (OpenAI மற்றும் Azure OpenAI இரண்டும் ஆதரிக்கின்றன). +**OpenAiOfficialEmbeddingModel** - OpenAI அதிகாரப்பூர்வ கிளையனைப் பயன்படுத்தி embeddings உருவாக்குதல் (OpenAI மற்றும் Azure OpenAI இரண்டும் ஆதரிக்கப்படுகிறது). -**ChatModel** - மொழி மாதிரிகளுக்கான முக்கிய இடைமுகம். +**ChatModel** - மொழி மாடல்களுக்கான மைய இடைமுகம். -**ChatMemory** - உரையாடல் வரலாறை நிர்வகிக்கும். +**ChatMemory** - உரையாடல் வரலாற்றை வைத்திருக்கும். -**ContentRetriever** - RAG க்காக பொருத்தமான ஆவண துண்டுகளை கண்டுபிடிக்கும். +**ContentRetriever** - RAGக்கான பொருத்தமான ஆவண துண்டுகளை கண்டுபிடிக்கும். -**DocumentSplitter** - ஆவணங்களை துண்டுகளாக பிரிக்கும். +**DocumentSplitter** - ஆவணங்களை துண்டுகளாகப் பிரிக்கும். -**EmbeddingModel** - உரையை எண் வடிவ எம்பெட்டிங்குகளாக மாற்றும். +**EmbeddingModel** - உரையை இலக்கண எண்கோவைகளாக மாற்றும். -**EmbeddingStore** - எம்பெட்டிங்குகளை சேமித்து மீட்டெடுக்கும். +**EmbeddingStore** - embeddings களை சேமித்து மீட்டெடுக்கிறது. -**MessageWindowChatMemory** - சமீபத்திய செய்திகள் கொண்ட ஸ்லைடிங் சாளரத்தை பராமரிக்கும். +**MessageWindowChatMemory** - சமீபத்திய செய்திகளின் செலுத்தும் சாளரத்தை பராமரிக்கும். -**PromptTemplate** - `{{variable}}` இடம் பிடிப்பாளர்களுடன் மறுபயன்பாடான ப்ராம்ட்களை உருவாக்குகிறது. +**PromptTemplate** - `{{variable}}` இடமிருந்து மீட்கக்கூடிய ப்ராம்ட்கள் உருவாக்குகிறது. -**TextSegment** - RAG இல் பயன்படுத்தப்படும் மெட்டாடேட்டாவுடன் உரை துண்டு. +**TextSegment** - உள்குறிப்புடன் கூடிய உரை துண்டு. RAG இல் பயன்படும். -**ToolExecutionRequest** - கருவி செயல்பாடு கோரிக்கை பிரதிநிதித்துவம். +**ToolExecutionRequest** - கருவி செயல்பாடல் கோரிக்கை. **UserMessage / AiMessage / SystemMessage** - உரையாடல் செய்தி வகைகள். -## AI/ML கான்செப்ட்கள் +## AI/ML கருத்துக்கள் -**சிறிய எண் எடுத்துக்காட்டுகளுடன் கற்றல்** - ப்ராம்ட்களில் எடுத்துக்காட்டுகளை வழங்குதல். [தொகுதி 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - ப்ராம்ட்களில் எடுத்துக்காட்டுகளை வழங்குதல். [Module 02](../02-prompt-engineering/README.md) -**பெரிய மொழி மாதிரி (LLM)** - பரந்த உரை தரவிலான AI மாதிரிகள். +**Large Language Model (LLM)** - பெரும் உரைத் தரவுகளின் அடிப்படையில் பயிற்சிப் பெற்ற AI மாடல்கள். -**கருத்து முயற்சி** - GPT-5.2 இல் சிந்தனைக் கோட்பாட்டை கட்டுப்படுத்தும் அளவுகோல். [தொகுதி 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - GPT-5.2 இல் எண்ணும் ஆழத்தைக் கட்டுப்படுத்தும் அளவுரு. [Module 02](../02-prompt-engineering/README.md) -**வெப்பநிலை** - வெளியீடு சிதறலை கட்டுப்படுத்து. குறைந்தது=முடிவானது, அதிகம்=புதுமையானது. +**Temperature** - வெளிப்பாட்டின் சீராக்காமல் மாறுபாட்டைக் கட்டுப்படுத்தும். குறைந்தது=தெளிவானது, அதிகம்=புதுமையாக. -**வெக்டர் தரவுத்தளம்** - எம்பெட்டிங்குகளுக்கான சிறப்பு தரவுத்தளம். [தொகுதி 03](../03-rag/README.md) +**Vector Database** - embeddings க்கான சிறப்பு தரவுத்தளம். [Module 03](../03-rag/README.md) -**பூஜ்ய-எடுத்துக்காட்டில்லா கற்றல்** - எடுத்துக்காட்டுகள் இல்லாமல் பணிகளை செய்யல். [தொகுதி 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - எடுத்துக்காட்டுகள் இல்லாமல் பணிகள் செய்யுதல். [Module 02](../02-prompt-engineering/README.md) -## காப்புரைகள் - [தொகுதி 00](../00-quick-start/README.md) +## காவல் கோடுகள் -**ஆழமான பாதுகாப்பு** - பயன்பாட்டு நிலை காப்புறைகள் மற்றும் வழங்குனர் பாதுகாப்பு கட்டுப்பாடுகளை இணைக்கும் பல அடுக்கு பாதுகாப்பு அணுகுமுறை. +**Defense in Depth** - பயன்பாட்டு மட்டத்தில் காவல் கோடுகளை வழங்கி சேவையக பாதுகாப்பு சான்றுகள் மற்றும் பகிரங்க பாதுகாப்பு வடிகட்டிகளுடன் இணைத்தல். -**முக்கிய தடை** - கடுமையான உள்ளடக்க மீறல்களுக்கு வழங்குனர் HTTP 400 தவறு காட்டுகிறான். +**Hard Block** - கடுமையான உள்ளடக்க மீறல்களுக்கு சேவையகம் HTTP 400 பிழை எழுப்பும். -**InputGuardrail** - LLM அடைவதற்கு முன்னர் பயனர் உள்ளீட்டை சரிபார்க்க LangChain4j இடைமுகம். தீங்கான ப்ராம்ட்களை ஆரம்பத்தில் தடுக்கும் மூலம் செலவு மற்றும் தாமதத்தை காப்பாற்றும். +**InputGuardrail** - LangChain4j இடைமுகம், பயனரின் உள்ளீட்டை LLM க்கு செல்லும் முன் சரிபார்த்து சேமிக்கும். ஆபத்தான ப்ராம்ட்களை முதலில் தடுக்கச் செலவு மற்றும் தாமதத்தை குறைக்கும். -**InputGuardrailResult** - காப்புரை சரிபார்ப்புக்கான திரும்பும் வகை: `success()` அல்லது `fatal("காரணம்")`. +**InputGuardrailResult** - காவல் மதிப்பீட்டிற்கான பின்வருங்கள் வகை: `success()` அல்லது `fatal("காரணம்")`. -**OutputGuardrail** - பயனர்களுக்கு திருப்புவதற்கு முன்னர் AI பதில்களை சரிபார்க்க இடைமுகம். +**OutputGuardrail** - பயனர்களுக்கு பதிலளிக்கும் முன் AI பதில்களை சரிபார்க்கும் இடைமுகம். -**வழங்குநர் பாதுகாப்பு வடிகட்டிகள்** - AI வழங்குநர்களிடமிருந்து உள்ளடக்கத்தை API நிலை에서 பறிப்பது போன்ற கட்டுப்பாடுகளை கொண்டுள்ளு வடிகட்டிகள் (எ.கா., GitHub மாதிரிகள்). +**Provider Safety Filters** - AI வழங்குநர்களால் (உதா. Azure OpenAI) வழங்கப்படும் உள்ளடக்க வடிகட்டிகள், API நிலை மீது மீறல்களை பிடிக்கும். -**மென்மையான மறுப்பு** - மாதிரி தவறு காட்டாமல் மரியாதையாக பதில் அளிக்க மறுப்பது. +**Soft Refusal** - பிழை இல்லாமல் மாடல் நெகிழ்வாக பதில் மறுக்கும். -## ப்ராம்ட் பொறியியல் - [தொகுதி 02](../02-prompt-engineering/README.md) +## ப்ராம்ட் பொறியியல் - [Module 02](../02-prompt-engineering/README.md) -**சிந்தனை சங்கிலி** - சிறந்த துல்லியத்துக்கு படி படியாக நியாயம் செய்யல். +**Chain-of-Thought** - படிப்படியாக காரணம் காட்டுதல், நிறைவான சரியான பதிலுக்கு. -**மூடிய வெளியீடு** - குறிப்பிட்ட வடிவம் அல்லது அமைப்பை கட்டாயப்படுத்தல். +**Constrained Output** - இடையறாத குறிப்பான வடிவமைப்பு அல்லது கட்டமைப்பை வலியுறுத்துதல். -**மிகவும் ஆர்வம்** - GPT-5.2 இல் விரிவான சிந்தனைக்கான முறை. +**High Eagerness** - GPT-5.2 இல் விரிவான காரணவியல் மாதிரி. -**குறைந்த ஆர்வம்** - GPT-5.2 இல் விரைவான பதில்களுக்கான முறை. +**Low Eagerness** - GPT-5.2 இல் வேகமாக பதில் அளிக்கும் மாதிரி. -**பலபடியான உரையாடல்** - மாற்றங்களுக்கிடையில் சூழலை பராமரித்தல். +**Multi-Turn Conversation** - பரிமாற்றங்களில் சுருட்டு நிலைகளை பராமரித்தல். -**பாத்திர அடிப்படையிலான ப்ராம்டிங்** - கணினி தன்மையை system செய்திகளின் மூலம் அமைத்தல். +**Role-Based Prompting** - அமைப்பு செய்திகளால் மாடல் தனிப்பட்ட வசந்தம் அமைத்தல். -**தனிமனிதம்** - மாதிரி தனது வெளியீட்டை மதிப்பீடு செய்து மேம்படுத்துதல். +**Self-Reflection** - மாடல் தனது வெளிப்பாட்டை மதிப்பாய்ந்து மேம்படுத்துதல். -**ஒழுங்கமைக்கப்பட்ட பகுப்பாய்வு** - நிர்ணயிக்கப்பட்ட மதிப்பீட்டுக் கட்டமைப்பு. +**Structured Analysis** - நிர்ணயிக்கப்பட்ட மதிப்பீட்டு கட்டமைப்பு. -**பணி செயலாக்க முறை** - திட்டமிடு → செயல்படுத்து → சுருக்கம். +**Task Execution Pattern** - திட்டமிடு → செயல் → சுருக்கம். -## RAG (மீட்டெடுப்பு-சேர்க்கப்பட்ட உருவாக்கம்) - [தொகுதி 03](../03-rag/README.md) +## RAG (Retrieval-Augmented Generation) - [Module 03](../03-rag/README.md) -**ஆவண செயலாக்க குழாய்** - ஏற்று → துண்டாக்கு → எம்பெடு → சேமி. +**Document Processing Pipeline** - ஏற்றவும் → துண்டாக்கவும் → உள்வெள்ளை உருவாக்கவும் → சேமிக்கவும். -**உள்ளமைவாக இருக்கும் எம்பெட்டிங் ஸ்டோர்** - சோதனைகளுக்கான நிரந்தரமற்ற சேமிப்பகம். +**In-Memory Embedding Store** - சோதனைகளுக்கான தற்காலிக சேமிப்பு. -**RAG** - பதில்களை நிலைத்துள்ள தகவலுடன் இணைக்கும் மீட்டெடுப்பு மற்றும் உருவாக்கக் கலவையுடன். +**RAG** - மீட்டெடுக்கும் மற்றும் உருவாக்கும் ஒன்று சேர்க்கை, பதில்களை ஆதாரமாக்கும். -**சமத்துவ மதிப்பெண்** - அர்த்தவாய்ந்த ஒத்திசைவு அளவு (0-1). +**Similarity Score** - பொருள் ஒத்திசைவு அளவு 0-1 வரை. -**மூல மேற்கோள்** - மீட்டெடுக்கப்பட்ட உள்ளடக்கத்தைச் பற்றிய மெட்டாடேட்டா. +**Source Reference** - மீட்டெடுக்கப்பட்ட உள்ளடக்கத்தின் உள் குறிப்புகள். -## ஓஜனையாளர்கள் மற்றும் கருவிகள் - [தொகுதி 04](../04-tools/README.md) +## செயலாளர்கள் மற்றும் கருவிகள் - [Module 04](../04-tools/README.md) -**@Tool குறிச்சொல்** - ஜாவா முறைகளுக்கு AI அழைக்கக்கூடிய கருவிகள் என்று குறிகள். +**@Tool Annotation** - ஜாவா முறைகளை AI அழைக்கக்கூடிய கருவியாகக் குறிக்கிறது. -**ReAct மாதிரி** - நியாயம் → செயல் → கவனிப்பு → மீண்டும் செயல். +**ReAct Pattern** - காரணம் → செயல் → கவனிக்கவும் → மீண்டும். -**அமர்வு மேலாண்மை** - வேறுபட்ட பயனர்களுக்கான தனி சூழல்கள். +**Session Management** - வேறு பயனர்களுக்கான தனித்தனித் சூழல்கள். -**கருவி** - AI ஓஜனையாளர் அழைக்கக்கூடிய செயல்பாடு. +**Tool** - AI செயலாளி அழைக்கக்கூடிய செயல்பாடு. -**கருவி விளக்கம்** - கருவியின் நோக்கம் மற்றும் அளவுருக்களின் ஆவணம். +**Tool Description** - கருவியின் நோக்கு மற்றும் அளவுருக்களின் ஆவணம். -## ஓஜனையியல் தொகுதி - [தொகுதி 05](../05-mcp/README.md) +## ஏஜென்டிக் பிரிவு - [Module 05](../05-mcp/README.md) -**@Agent குறிச்சொல்** - இடைமுகங்களை பேசும் குணாதிசயங்களுடன் AI ஓஜனையாளர்களாக குறிக்கிறது. +**@Agent Annotation** - இடைமுகங்களை AI செயலாளிகளாகவும், அறிவுரை செயலை விளக்கவும் குறிக்கிறது. -**ஓஜனையாளர் விசைப்பெயர்** - `beforeAgentInvocation()` மற்றும் `afterAgentInvocation()` மூலம் ஓஜனையாளர் செயல்பாட்டைக் கண்காணிக்க ஹுக். +**Agent Listener** - `beforeAgentInvocation()` மற்றும் `afterAgentInvocation()` மூலம் செயலாளி செயலை கண்காணிக்க உதவி. -**ஓஜனையியல் பரியலம்** - ஓஜனையாளர்கள் வெளியீடுகளை `outputKey` பயன்படுத்தி பகிரும் பகுதி, பின்னர் பிற ஓஜனையாளர்கள் 이를 பயன்படுத்துவார்கள். +**Agentic Scope** - செயலாளர்கள் வெளியீடுகளை பகிர்ந்து downstream செயலாளிகள் பயன்படுத்தும் பொதுவான நினைவகம். -**AgenticServices** - `agentBuilder()` மற்றும் `supervisorBuilder()` மூலம் ஓஜனையாளர்களை உருவாக்கும் தொழிற்சாலை. +**AgenticServices** - `agentBuilder()` மற்றும் `supervisorBuilder()` மூலம் செயலாளிகளை உருவாக்கும் தொழிற்சாலை. -**நிபந்தனை அடிப்படையிலான பணியாளர் வழி** - விதிகளின் அடிப்படையில் வேறு நிபுண ஓஜனையாளர்களிடம் வழிமாற்றல். +**Conditional Workflow** - விதிமுறைகளின்படி வித்துவாத செயலாளரிடம் வழிமாறு. -**மனிதன்-நுழைந்த செயல்முறை** - ஒப்புதல் அல்லது உள்ளடக்க பரிசீலனைக்கு மனிதரைச் சேர்க்கும் பணிச்செழு. +**Human-in-the-Loop** - அனுமதி அல்லது உள்ளடக்க பரிசீலனைக்கான மனிதச் சோதனைப்புள்ளிகள் உள்ள பணிமுறை மாதரி. -**langchain4j-agentic** - உரையாடல் ஓஜனையாளர் கட்டுமானத்திற்கான மெய்வரி நிச்சயமற்ற தொகுப்பு (அனுபவ்ச்சி). +**langchain4j-agentic** - அறிவுரையுள்ள செயலாளி கட்டமைப்பிற்கு Maven சார்பு (அனுபவபூர்வமானது). -**மடக்கு பணிச்செழு** - ஒரு நிபந்தனையை பூர்த்தி செய்யும் வரை ஓஜனையாளர் செயல்பாட்டினை மீண்டும் மீண்டும் செய்யும் வகை (எ.கா., தர மதிப்பெண் ≥ 0.8). +**Loop Workflow** - விகிதம் முந்தைய வரை அல்லது நிபந்தனை பூர்த்தி வரை செயலாளி செயல்பாட்டை மீண்டும் இயக்கு. -**outputKey** - ஓஜனையாளர் குறிச்சொல் அளவுரு, எங்கே முடிவுகள் ஓஜனையியல் பரியலத்தில் சேமிக்கப்படுகின்றன என்பதைக் குறிக்கிறது. +**outputKey** - செயலாளிக் குறிக்கோள், Agentic Scope இல் முடிவுகள் சேமிக்கப்படும் இடத்தை குறிப்பிடும். -**இணை செயல் பணிச்செழு** - பல ஓஜனையாளர்களை சுதந்திர பணிகளுக்காக ஒரே நேரத்தில் இயக்குதல். +**Parallel Workflow** - பல செயலாளிகள் தனித்தனிக் பணிகளுக்கு ஒரே நேரத்தில் இயங்கும். -**பதில் நெறிமுறை** - மேற்பார்வையாளர் கடைசி பதில் உருவாக்கும் முறை: கடைசி, சுருக்கம், அல்லது மதிப்பிடப்பட்டது. +**Response Strategy** - மேலாளர் இறுதிப்பதில் பதிலை உருவாக்கும் பாணி: LAST, SUMMARY, அல்லது SCORED. -**எதிரொலி பணிச்செழு** - ஒன்றுக்கு பிறகு ஓஜனையாளர்களை இயக்கி, வெளியீடு அடுத்த படிக்கு செல்லும். +**Sequential Workflow** - செயலாளர்களை வரிசைப்படி இயக்கு, வெளியீடு அடுத்தபடியான கட்டத்திற்கு செல்கிறது. -**மேற்பார்வையாளர் ஓஜனையாளர் மாதிரி** - மேற்பார்வை LLM இயக்கத்தான் எந்த துணை ஓஜனையாளர்களை அழைக்க வேண்டும் என்பதை உள்ளடக்கிய மேம்பட்ட ஓஜனையியல் மாதிரி. +**Supervisor Agent Pattern** - மேலாளர் LLM பின்விளைவுகளில் எந்த துணை செயலாளர்களை அழைப்பது என்று நுண்ணறிவுடன் முடிவு செய்யும் உயர் நிலை ஏஜென்டிக் மாதிரி. -## மாதிரி சூழல் நெறிமுறை (MCP) - [தொகுதி 05](../05-mcp/README.md) +## மாடல் வார_CONTEXT_நெறிமுறை (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j இல் MCP ஒருங்கிணைப்பிற்கு மெய்வரி. +**langchain4j-mcp** - LangChain4j இல் MCP ஒருங்கிணைப்புக்கான Maven சார்பு. -**MCP** - மாதிரி சூழல் நெறிமுறை: வெளிப்புற கருவிகளுடன் AI பயன்பாடுகளை இணைக்க ஒரு தரநிலை. ஒருமுறை உருவாக்கி எங்கும் பயன்படுத்து. +**MCP** - மாடல் வார_CONTEXT_நெறிமுறை: வெளிப்புற கருவிகளுடன் AI செயலிகளைக் இணைக்கும் தரநிலை. ஒருமுறை கட்டி, எங்கும் பயன்படுத்து. -**MCP கிளையண்ட்** - MCP சேவைகளுடன் இணைத்து கருவிகளை கண்டறிந்து பயன்படுத்தும் பயன்பாடு. +**MCP Client** - MCP சேவையகங்களைத் தொடர்பு கொண்டு கருவிகள் தேடவும் பயன்படுத்தவும் பயன்படும் செயலி. -**MCP சேவையகம்** - MCP வழியாக கருவிகளை வெளிப்படுத்தும் சேவை, தெளிவான விளக்கங்கள் மற்றும் அளவுரு திட்டங்கள் உடன். +**MCP Server** - தெளிவான விவரங்கள் மற்றும் அளவுரு கட்டமைப்புகளுடன் MCP மூலம் கருவிகளை வெளிப்படுத்தும் சேவை. -**McpToolProvider** - LangChain4j கூறு, MCP கருவிகளை AI சேவைகள் மற்றும் ஓஜனையாளர்களுக்காக பயன்படுத்துவதற்கான சுருள். +**McpToolProvider** - LangChain4j கூறு, MCP கருவிகளை AI சேவைகளிலும் செயலாளர்களிலும் பயன்படுத்துவதற்காக மூடியதாக காட்டும். -**McpTransport** - MCP தொடர்புக்கும் இடைமுகம். செயல்முறைகள் Stdio மற்றும் HTTP உட்பட. +**McpTransport** - MCP தொடர்புக்கான இடைமுகம். நிறைவேற்றல்கள் Stdio மற்றும் HTTP அடங்கும். -**Stdio தொடர்பு** - உள்ளூர் செயல்முறை தொடர்பு stdin/stdout மூலம். கோப்பு அணுகல் அல்லது கட்டளை வரிசை கருவிகளுக்கு பயன்படும். +**Stdio Transport** - stdin/stdout மூலம் உள்ளூர் செயலாக்கக் கருவி. கோப்பு அமைப்பிற்கு அணுகுவதற்கோ அல்லது கட்டளைக்குறி கருவிகளுக்கு பயனுள்ளது. -**StdioMcpTransport** - LangChain4j செயலாக்கம் MCP சேவையகத்தை துணைசெயல்பாடுகளாக உருவாக்கும். +**StdioMcpTransport** - LangChain4j நிறைவேற்றல், MCP சேவையகத்தை துணைசேவையாக இயக்குகிறது. -**கருவி கண்டறிதல்** - கிளையண்ட் விளக்கங்கள் மற்றும் திட்டங்களுடன் கிடைக்கும் கருவிகளை சேவையகத்திலிருந்து கேட்கும். +**Tool Discovery** - கிளையன் சேவையகத்துக்கு கிடைக்கும் கருவிகளின் விவரங்கள் மற்றும் கட்டமைப்புகளைக் கேள்வி செய்கிறது. -## அசுரேசேவைகள் - [தொகுதி 01](../01-introduction/README.md) +## அழுரு சேவைகள் - [Module 01](../01-introduction/README.md) -**Azure AI தேடல்** - வெக்டர் திறன்களுடன் மேக தேடல். [தொகுதி 03](../03-rag/README.md) +**Azure AI Search** - வெகுவாக அளவிடக்கூடிய கிளவுட் தேடல். [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Azure வளங்களை வெளியிடும். +**Azure Developer CLI (azd)** - Azure வளங்களை சர்ப்படுத்துகிறது. -**Azure OpenAI** - மைக்ரோசாஃப்ட் நிறுவனத்தின் நிறுவன AI சேவை. +**Azure OpenAI** - மைக்ரோசாஃப்ட் நிறுவனத்தின் தொழிற்சாலை AI சேவை. -**Bicep** - Azure கட்டமைப்பு-கோடு மொழி. [கட்டமைப்பு வழிகாட்டி](../01-introduction/infra/README.md) +**Bicep** - Azure உட்கட்டமைப்பு-எல்லாம் குறியீட்டு மொழி. [Infrastructure Guide](../01-introduction/infra/README.md) -**பதிவு பெயர்** - Azure இல் மாதிரி காரணம். +**Deployment Name** - Azure இல் மாடல் தெரிவிக்கப்பட்ட பெயர். -**GPT-5.2** - காரணிக் கட்டுப்பாட்டுடன் சமீபத்திய OpenAI மாதிரி. [தொகுதி 02](../02-prompt-engineering/README.md) +**GPT-5.2** - காரணிக்கையை கட்டுப்படுத்தும் புதிய OpenAI மாடல். [Module 02](../02-prompt-engineering/README.md) -## சோதனை மற்றும் வளர்ச்சி - [சோதனை வழிகாட்டி](TESTING.md) +## சோதனை மற்றும் மேம்பாடு - [Testing Guide](TESTING.md) -**வளர்ச்சி கொண்டெயினர்** - அங்கீகாரப்பட்ட மேம்பாட்டுக் சூழல். [கட்டமைப்பு](../../../.devcontainer/devcontainer.json) +**Dev Container** - கண்டெய்னரை அடிப்படையாக்கொண்ட மேம்பாட்டு சூழல். [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub மாதிரிகள்** - இலவச AI மாதிரி மேடை. [தொகுதி 00](../00-quick-start/README.md) +**In-Memory Testing** - நினைவகச் சேமிப்போடு சோதனை. -**உள்ளமைவைப் பரிசோதனை** - உள்ளமைவு சேமிப்போடு சோதனை. +**Integration Testing** - உண்மை அடிப்படையிலான கட்டமைப்புடன் சோதனை. -**உதேசல் சோதனை** - உண்மையான கட்டமைப்புடன் சோதனை. +**Maven** - ஜாவா கட்டுமான தானியங்கு கருவி. -**Maven** - ஜாவா கட்டுமான தானியங்கி கருவி. +**Mockito** - ஜாவா வஞ்சனை பரப்புக் கருவி. -**Mockito** - ஜாவா மட்டுகோப்பு மையம். - -**Spring Boot** - ஜாவா பயன்பாட்டு வடிவமைப்பு. [தொகுதி 01](../01-introduction/README.md) +**Spring Boot** - ஜாவா செயலி கட்டமைப்பு. [Module 01](../01-introduction/README.md) --- -**மீறுதல்**: -இந்த ஆவணம் AI மொழி மாற்ற சேவையான [Co-op Translator](https://github.com/Azure/co-op-translator) மூலம் மொழிமாற்றம் செய்யப்பட்டுள்ளது. நாங்கள் துல்லியத்திற்காக முயற்சித்தாலும், தானியங்கி மொழி மாற்றங்கள் பிழைகள் அல்லது தவறுகள் கொண்டிருக்கலாம் என்பதை தயவுசெய்து கவனியுங்கள். உள்ளூர் மொழியில் உள்ள அசல் ஆவணம் அதிகாரப்பூர்வமான ஆதாரமாக கருதி கொள்ள வேண்டும். முக்கியமானத் தகவல்களுக்கு, தொழில்முறை மனித மொழி மாற்றத்தை பரிந்துரைக்கின்றோம். இந்த மொழி மாற்றத்தை பயன்படுத்துவதில் ஏற்படும் எந்தவொரு தவறான புரிதல்கள் அல்லது தவறான விளக்கங்களுக்கும் நாங்கள் பொறுப்பாளிகள் அல்ல. +**மறுப்பு**: +இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. நாங்கள் துல்லியத்திற்காக முயற்சி செய்துள்ளோம், ஆனால் தானாக செய்யப்படும் மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கலாம் என்பதை கவனத்தில் கொள்ளவும். அசல் ஆவணம் அதன் தாய்மொழியில் அதிகாரப்பூர்வ ஆதாரமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழில்நுட்பமான மனித மொழிபெயர்ப்பு பரிந்துரைக்கப்படுகிறது. இந்த மொழிபெயர்ப்பைப் பயன்படுத்துவதால் ஏற்படும் எந்த தவறான புரிதல்கள் அல்லது தவறான விளக்கத்திற்கும் நாங்கள் பொறுப்பில்வில்லை. \ No newline at end of file diff --git a/translations/ta/docs/TESTING.md b/translations/ta/docs/TESTING.md index 4a0bc90e0..5511fa3ad 100644 --- a/translations/ta/docs/TESTING.md +++ b/translations/ta/docs/TESTING.md @@ -1,18 +1,18 @@ -# LangChain4j பயன்பாடுகளை சோதனை செய்வது +# LangChain4j பயன்பாடுகளை சோதனை செய்தல் -## உள்ளடக்கம் +## зміст -- [தைவிர் துவக்கம்](../../../docs) -- [சோதனைகள் என்னவற்றை கவர்கிறன](../../../docs) -- [சோதனைகளை இயக்குதல்](../../../docs) -- [VS கோடில் சோதனைகளை இயக்குதல்](../../../docs) -- [சோதனை மாதிரிகள்](../../../docs) -- [சோதனை தத்துவம்](../../../docs) -- [அடுத்த படிகள்](../../../docs) +- [விரைவு தொடக்கம்](#விரைவு-தொடக்கம்) +- [சோதனைகள் என்ன ஒன்றை உள்ளடக்கியது](#சோதனைகள்-என்ன-ஒன்றை-உள்ளடக்கியது) +- [சோதனைகளை இயக்குதல்](#சோதனைகளை-இயக்குதல்) +- [VS Code இல் சோதனைகள் இயக்குதல்](#vs-code-இல்-சோதனைகள்-இயக்குதல்) +- [சோதனை வடிவங்கள்](#சோதனை-வடிவங்கள்) +- [சோதனை தத்துவம்](#சோதனை-தத்துவம்) +- [அடுத்த படிகள்](#அடுத்த-படிகள்) -API விசைகள் அல்லது வெளிப்புற சேவைகள் தேவையில்லாமல் AI பயன்பாடுகளை எப்படி சோதிப்பது என்பதைக் காட்டும் சோதனைகள் வழியாக இந்த கையேடு உங்களை நடத்துகிறது. +இந்த வழிகாட்டி API விசைகள் அல்லது வெளி சேவைகள் தேவையின்றி AI பயன்பாடுகளை எப்படி சோதனை செய்வது என்பதை விளக்குகிறது. -## தைவிர் துவக்கம் +## விரைவு தொடக்கம் ஒரே கட்டளையுடன் அனைத்து சோதனைகளையும் இயக்கவும்: @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -அனைத்து சோதனைகளும் கடந்தால், கீழேயுள்ள திரைக்காட்சிப்போன்ற வெளியீடு காணப்படும் — சோதனைகள் பிழையின்றி இயங்குகின்றன. +அனைத்து சோதனைகளும் வெற்றி பெற்றவுடன், கீழே உள்ள திரைப் படத்தைப் போல உங்களுக்கு வெளியீடு காணப்படும் — சோதனைகள் எந்த தவறுமற்றும் இயங்கும். Successful Test Results -*அனைத்து சோதனைகளும் பிழையின்றி வெற்றி பெறுவதை காண்பிக்கும் வெற்றிகரமான சோதனை செயல்பாடு* +*எல்லா சோதனைகளும் தவறில்லாமல் இயங்குவதை காண்பிக்கும் வெற்றிகரமான சோதனை செயல்பாடு* -## சோதனைகள் என்னவற்றை கவர்கிறன +## சோதனைகள் என்ன ஒன்றை உள்ளடக்கியது -இந்த பாடநெறி உள்ளூர் இயக்கப்படும் **அலகு சோதனைகள்** மீது கவனம் செலுத்துகிறது. ஒவ்வொரு சோதனையும் தனித்துவமான LangChain4j கருத்தை பிரித்தெடுத்து காட்டுகிறது. கீழே உள்ள சோதனை piramide அலகு சோதனைகள் எங்கு பொருந்துகின்றன என்பதை காட்டுகிறது — அவை வேகமான, நம்பகமான அடித்தளத்தை உருவாக்கி, உங்கள் சோதனைத் திட்டத்தின் மற்ற பகுதிகள் அதன்மேல் கட்டமைக்கப்படுகின்றன. +இந்த பாடம் உள்ளூரில் இயங்கும் **அலகு சோதனைகள்** மீது கவனம் செலுத்துகிறது. ஒவ்வொரு சோதனையும் தனித்துவமான LangChain4j கருத்தை ஆராய்கிறது. கீழுள்ள சோதனை piramid அங்கு அலகு சோதனைகள் எவ்வளவு முக்கியமானவை என்பதைக் காண்பிக்கிறது — அவை உங்கள் சோதனைத் திட்டத்தின் வேகமான, நம்பக்கூடிய அடித்தளமாக செயல்படுகின்றன. Testing Pyramid -*அலகு சோதனைகள் (வேகமான, தனித்துவமான), ஒருங்கிணைப்பு சோதனைகள் (உண்மையான கூறுகள்), மற்றும் இறுதித் துவக்க சோதனைகள் ஆகியவற்றுக்கு இடையேயான சமன்வயத்தைக் காட்டும் சோதனை piramide. இந்த பயிற்சி அலகு சோதனைகளைப் பற்றி.* +*அலகு சோதனைகள் (வேகமான, தனித்துவமான), ஒருங்கிணைப்பு சோதனைகள் (உண்மையான கூறுகள்), மற்றும் இறுதி-வரை சோதனைகள் ஆகியவற்றின் சமனாக சோதனை பாமிட். இந்த பயிற்சி அலகு சோதனைகளை உள்ளடக்கியது.* -| யூனிட்டு | சோதனைகள் | கவனம் | முக்கிய கோப்புகள் | +| தொகுதி | சோதனைகள் | கவனம் | முக்கிய கோப்புகள் | |--------|-------|-------|-----------| -| **00 - தைவிர் துவக்கம்** | 6 | முன்மொழிவு வடிவமைப்புகள் மற்றும் மாறி இடைநிலை மாற்றம் | `SimpleQuickStartTest.java` | -| **01 - அறிமுகம்** | 8 | உரையாடல் நினைவகம் மற்றும் நிலையை பேணும் உரையாடல் | `SimpleConversationTest.java` | -| **02 - முன்மொழிவு பொறியியல்** | 12 | GPT-5.2 மாதிரிகள், ஆர்வ நிலைகள், அமைப்புக்கேற்ற வெளியீடு | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | ஆவணம் உறிஞ்சல், ஒருங்கிணைப்புகள், ஒத்திருப்புச் தேடல் | `DocumentServiceTest.java`` | -| **04 - கருவிகள்** | 12 | செயல்பாடு அழைப்பு மற்றும் கருவி தொடர் | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | stdio எடுத்துச்சொல்லும் மாடல் சூழல் நெறிமுறை | `SimpleMcpTest.java` | +| **01 - அறிமுகம்** | 8 | உரையாடல் நினைவகம் மற்றும் நிலையான அரட்டை | `SimpleConversationTest.java` | +| **02 - கூடியார் வடிவமைப்பு** | 12 | GPT-5.2 வடிவங்கள், ஆர்வ நிலைகள், அமைந்த வினையமைப்பு | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | ஆவண ஏற்றுதல், உட்பிரவேசங்கள், ஒத்திசைவு தேடல் | `DocumentServiceTest.java` | +| **04 - கருவிகள்** | 12 | செயல்பாடு அழைப்பு மற்றும் கருவி சங்கிலி | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | மாடல் காட்சி நெறிமுறை StdIO போக்குவரத்துடன் | `SimpleMcpTest.java` | -## சோதனைகள் இயக்குதல் +## சோதனைகளை இயக்குதல் -**அனைத்து சோதனைகளையும் ரூட் இருந்து இயக்க:** +**கூற்றுமருதியில் அனைத்து சோதனைகளையும் இயக்க:** **Bash:** ```bash @@ -63,23 +62,23 @@ mvn test mvn --% test ``` -**குறிப்பிட்ட யூனிட்டின் சோதனைகள் இயக்க:** +**குறிப்பிட்ட தொகுதிக்கான சோதனைகள் இயக்க:** **Bash:** ```bash cd 01-introduction && mvn test -# அல்லது ரூட் இருந்து +# அல்லது ரூட் இலிருந்து mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# அல்லது ரூட் இலிருந்து +# அல்லது மூலத்தில் இருந்து mvn --% test -pl 01-introduction ``` -**ஒரே சோதனை வகுப்பை இயக்க:** +**ஒரு சோதனை வகுப்பை இயக்க:** **Bash:** ```bash @@ -91,11 +90,11 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**குறிப்பிட்ட சோதனை முறையை இயக்க:** +**ஒரு குறிப்பிட்ட சோதனை முறையை இயக்க:** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#உரையாடல் வரலாறை பராமரிக்க வேண்டும் +mvn test -Dtest=SimpleConversationTest#உரையாடல் வரலாற்றை பராமரி்க வேண்டும் ``` **PowerShell:** @@ -103,33 +102,33 @@ mvn test -Dtest=SimpleConversationTest#உரையாடல் வரலாற mvn --% test -Dtest=SimpleConversationTest#உரையாடல் வரலாற்றை பராமரிக்க வேண்டும் ``` -## VS கோடில் சோதனைகள் இயக்குதல் +## VS Code இல் சோதனைகள் இயக்குதல் -Visual Studio Code பயன்படுத்தினால், Test Explorer சோதனைகளை இயக்கவும் பிழைநிரப்பவும் ஒரு வரைபட இடைமுகத்தை வழங்குகிறது. +Visual Studio Code பயன்படுத்தினால், Test Explorer சோதனைகளை இயக்க மற்றும் பிழைத்திருத்த சிறப்பு இடைமுகத்தை அளிக்கிறது. VS Code Test Explorer -*VS Code Test Explorer கூட்டு Java சோதனை வகுப்புகளையும் தனிப்பட்ட சோதனை முறைகளையும் காட்டுகிறது* +*VS Code Test Explorer அனைத்து ஜாவா சோதனை வகுப்புகள் மற்றும் தனிப்பட்ட சோதனை முறைகளை காட்டுகிறது* **VS Code இல் சோதனைகள் இயக்க:** -1. பணி பட்டியலில் உள்ள பீக்கர் ஐகானை கிளிக் செய்து Test Explorer திறக்கு -2. சோதனை மரத்தை விரிவாக்கி அனைத்து யூனிட்களையும் சோதனை வகுப்புகளையும் காண்க -3. தனி சோதனைகளை இயக்க எந்த சோதனையின் புற பெருகி பொத்தானை சொடுக்கவும் -4. முழு தொகுப்பையும் இயக்க "Run All Tests" பொத்தானை சொடுக்கவும் -5. எந்த சோதனையையும் வலது கிளிக் செய்து "Debug Test" தேர்வு செய்து இடையேச்சாரல் புள்ளிகளை அமைத்து படி படியே படி பிழைதிருத்தவும் +1. செயல்பாட்டு பட்டியில் பீக்கர் ஐகானை கிளிக் செய்து Test Explorer திறக்கவும் +2. அனைத்து தொகுதிகள் மற்றும் சோதனை வகுப்புகளை காண சோதனை மரத்தை விரிவாக்கவும் +3. தனித்தனியான சோதனையை இயக்க விரும்பினால் அதன் பக்கம் உள்ள play பொத்தானை கிளிக் செய்யவும் +4. முழு தொகுதிக்கான சோதனை செயற்குழுவை இயக்க "Run All Tests" கிளிக் செய்யவும் +5. எந்த சோதனையை தனியாக பிழைத்திருத்த விரும்பினால் அதை வலது கிளிக் செய்து "Debug Test" தேர்வு செய்யவும் -Test Explorer வெற்றிகரமாக கடந்த சோதனைகளுக்கு பச்சை சரிபார்ப்பு குறியீடுகள் காட்டுகிறது மற்றும் தோல்வி ஏற்பட்டால் விரிவான தவறு செய்திகளை வழங்குகிறது. +Test Explorer பாசிக்கான சோதனைகளுக்கு பச்சை சரிபார்ப்பு சின்னங்களைக் காட்டுகிறது மற்றும் தோல்விகள் ஏற்பட்டால் விரிவான பிழை செய்திகளை வழங்குகிறது. -## சோதனை மாதிரிகள் +## சோதனை வடிவங்கள் -### மாதிரி 1: முன்மொழிவு வடிவமைப்புகளை சோதனை செய்தல் +### வடிவம் 1: கூடியார் டெம்ப்ளேட்களை சோதனை செய்தல் -எளிமையான மாதிரி ஏதாவது AI மாடலை அழைக்காமலும் முன்மொழிவு வடிவமைப்புகளை சோதனை செய்கிறது. மாறி இடைநிலை மாற்றம் சரியாக செயல்படுவதை மற்றும் முன்மொழிவுகள் எதிர்பார்க்கப்படும் வடிவத்தில் உள்ளதென நீங்கள் உறுதி செய்கிறீர்கள். +எளிய வடிவம், எந்த AI மாடலையும் அழைக்காமல் கூடியார் டெம்ப்ளேட்டுகளை சோதிக்கிறது. மாற்றங்கள் சரியாக செயல்படுகிறதா மற்றும் கூடியார்கள் எதிர்பார்த்தபடி வடிவமைக்கப்படுகிறதா என்பதை உறுதிசெய்கிறது. Prompt Template Testing -*மாறி இடைநிலையில் வடிவமைப்பை சோதனை செய்வது: இடைப்பிரதிகளுடன் முன்மொழிவு → பொருத்தப்பட்ட மதிப்புகள் → வடிவமைக்கப்பட்ட வெளியீடு சரிபார்த்தல்* +*மாறிகள் நிரப்புதல் வழியைக் காட்டும் கூடியார் டெம்ப்ளேட் சோதனை: பதிப்புருக்கள் → மதிப்புகள் பொருத்தப்பட்டன → வடிவமைந்த வெளியீடு சரிபார்க்கப்பட்டது* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -இந்த சோதனை `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` உள்ளடக்கத்தில் உள்ளது. - -**இதை இயக்க:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#சோதனைவாக்கிய வடிவமைப்பு -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#சோதனைPromptவைஅமைத்தல் -``` +இந்த வடிவம் மாறிகள் சரியாக பொருந்தும் மற்றும் கூடியார்கள் எதிர்பார்த்தவாறு வடிவமைக்கப்பட்டிருப்பதை உறுதிசெய்கிறது — API விசை அல்லது மாடல் அழைப்புப் தேவையில்லை. -### மாதிரி 2: மொழி மாதிரிகள் மொக்கு செய்தல் +### வடிவம் 2: மொழி மாடல்களை மோக்கிங் செய்தல் -உரையாடல் தர்க்கத்தை சோதிக்கும் போது, Mockito ஐ பயன்படுத்தி முன்கூட்டியே தீர்மானிக்கப்பட்ட பதில்களை வழங்கும் புனைவு மாதிரிகளை உருவாக்கவும். இவ்வாறு சோதனைகள் வேகமானவை, இலவசமானவை மற்றும் தீர்மானிக்கப்பட்டவை ஆகின்றன. +உரையாடல் தர்க்கத்தை சோதிக்கும் போது, Mockito பயன்படுத்தி முற்போக்கு பதில்களை வழங்கும் கட்டமைக்கப்பட்ட மாடல்களை உருவாக்குங்கள். இது சோதனைகளை வேகமாகவும் இலவசமாகவும் மற்றும் தீர்மானமானதாகவும் மாற்றுகிறது. Mock vs Real API Comparison -*ஏன் மொக்குகளை சோதனைகளுக்கு முன்னுரிமையிடுகிறார்கள் என்பதை காட்டும் ஒப்பிடுகை: அவை வேகமானவை, இலவசம், தீர்மானிக்கப்பட்டவை மற்றும் API விசைகள் தேவையில்லை* +*சோதனைக்காக மோக்குகள் ஏன் முக்கியம் என்பதை காட்டும் ஒப்பீடு: அவை வேகமானவை, இலவசம், தீர்மானமானவை, மற்றும் API விசைகள் தேவையில்லை* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 பயனர் + 3 AI செய்திகள் + assertThat(history).hasSize(6); // 3 பயனர் + 3 செயற்கை நுண்ணறிவு செய்திகள் } } ``` -இந்த மாதிரி `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` இல் உள்ளது. மொக்குகள் நினைவக மேலாண்மை சரியாக வேலை செய்கிறதா என்பதை உறுதி செய்ய ஒரே மாதிரிச் செயல்பாட்டை வைத்திருக்கின்றன. +இந்த வடிவம் `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` இல் உள்ளது. மோக் ஒப்பனை நிலையான நடத்தை வழங்குகிறது, எனவே நினைவக நிர்வாகம் சரியாக நடைபெறுவதை நீங்கள் உறுதிபடுத்த முடியும். -### மாதிரி 3: உரையாடல் தனிமைப்படுத்தல் சோதனை +### வடிவம் 3: உரையாடல் தனித்துவத்தை சோதனை செய்தல் -உரையாடல் நினைவகம் பல பயனர்களை தனித்தனி வைக்க வேண்டும். இந்த சோதனை உரையாடல்கள் தரவுகளை கலப்பதில்லை என்பதைக் காட்டுகிறது. +உரையாடல் நினைவகம் பல பயனர்களை தனித்தனியாக வைத்திருக்க வேண்டும். இந்த சோதனை உரையாடல்கள் சூழலை கலக்காமல் இருக்கிறதா என்பதை உறுதிப்படுத்துகிறது. Conversation Isolation -*பல்வேறு பயனர்களுக்கான தனித்தனி நினைவக சேவைகளை காட்டும் உரையாடல் தனிமைப்படுத்தல் சோதனை, சூழலை கலக்க தடுக்கும்* +*பல்வேறு பயனர்களுக்கான தனித்தனி நினைவகக் கடைகளைக் காட்டி உரையாடல் தனித்துவத்தை சோதனை செய்தல்* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -ஒவ்வொரு உரையாடலும் அதன் தனிப்பட்ட வரலாற்றைப் பேணுகிறது. உற்பத்தித் திட்டங்களில், இது பல பயனர் பயன்பாடுகளுக்கு மிகவும் அவசியமான தனிமைப்படுத்தல். +ஒவ்வொரு உரையாடலும் அதன் சொந்த சுயாதீன வரலாற்றை பாதுகாக்கிறது. செயற்பாட்டு அமைப்புகளில், இந்த தனித்துவம் பல பயனர் பயன்பாடுகளுக்குத் தேவையானது. -### மாதிரி 4: கருவிகளை தனித் தனியாக சோதனை செய்தல் +### வடிவம் 4: கருவிகளை தனித்தனியாக சோதனை செய்தல் -கருவிகள் AI அழைக்கக்கூடிய செயல்பாடுகள் ஆகும். AI முடிவுகளைத் தவிர நேரடியாக அவற்றைச் சோதியுங்கள், அவை முறையாக இயங்குகிறதா என்று உறுதி செய்ய. +கருவிகள் என்பது AI அழைக்கக்கூடிய செயல்பாடுகள். AI முடிவுகளைக் கருத்தில் கொள்ளாமல் அவற்றை நேரடியாக சோதிக்கவும் அவை சரியாக வேலை செய்கின்றனவா என்பதையும் உறுதிப்படுத்தவும். Tools Testing -*AI அழைப்புகள் இல்லாமல் மொங்கு கருவி செயல்பாடு மூலம் தொழில்துறை தர்க்க சூழலைச் சோதற்சி செய்தல்* +*AI அழைப்புகள் இல்லாமல் தொழில்துறை தர்க்கத்தை சரிபார்க்கும் மோக் கருவி நிறைவேற்றலை காட்டு தானே கருவிகளை சோதனை செய்தல்* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` இல் உள்ள இச்சோதனைகள் AI தொடர்பில்லாமல் கருவி காரணியறிதல்களை சரிபார்க்கின்றன. தொடர் உதாரணம் ஒரு கருவியின் வெளியீடு மற்றொன்றின் உள்ளீடாகக் கிடைப்பதை காட்டுகிறது. +இந்த சோதனைகள் `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` இலிருந்து, AI தொடர்பில்லாமல் கருவி தர்க்கத்தை சரிபார்க்கின்றன. சங்கிலி எடுத்துக்காட்டு ஒரு கருவியின் வெளியீடு எப்படி மற்றொன்றின் உள்ளீட்டாக அனுப்பப்படுகிறது என்பதைக் காட்டுகிறது. -### மாதிரி 5: நினைவகத்தில் RAG சோதனை +### வடிவம் 5: நினைவக RAG சோதனை -RAG முறைமைகள் வழமையாக வெக்டர் தரவுத்தளங்கள் மற்றும் ஒருங்கிணைப்பு சேவைகளை தேவைப்படுத்துகின்றன. நினைவக மாதிரியில், வெளிப்புற சார்புகள் இல்லாமல் முழு குழாயை சோதிக்கலாம். +RAG அமைப்புகள் சாதாரணமாக வெக்டர் தரவுத்தளங்கள் மற்றும் உட்பிரவேச சேவைகள் தேவைபடும். நினைவக வடிவம் வெளி சார்பானவற்றைத் தவிர்த்து முழு குழாயை சோதிக்க அனுமதிக்கிறது. In-Memory RAG Testing -*வெளிப்புற தரவுத்தளம் தேவையில்லாமல் ஆவண பகிரல், ஒருங்கிணைப்பு சேமிப்பு, ஒத்திருப்புச் தேடல் ஆகியவற்றை நினைவகத்தில் சோதனை செய்யும் செயல்முறை* +*ஆவண பரிமாற்றம், உட்பிரவேச சேமிப்பு மற்றும் ஒத்திசைவு தேடலை தரவுத்தளமின்றி காட்டு நினைவக RAG சோதனை வேலைவகுப்பு* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -`03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` இல் இந்த சோதனை நினைவகத்தில் ஆவணத்தை உருவாக்கி துண்டித்து, மெட்டா தகவல்களை சரிபார்க்கிறது. +இந்த சோதனை `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` இலிருந்து, ஆவணத்தை நினைவகத்திலேயே உருவாக்கி துண்டிக்கும் மற்றும் மீட்டமைப்பு கையாளுதலை உறுதிப்படுத்துகிறது. -### மாதிரி 6: MCP ஒருங்கிணைப்பு சோதனை +### வடிவம் 6: MCP ஒருங்கிணைவு சோதனை -MCP முறைமையை stdio எடுத்துச்சொல்லும் மூலம் ஒருங்கிணைக்கும் MCP தொகுதி சோதனைகள். இச்சோதனைகள் உங்கள் பயன்பாடு MCP சேவைகளை subprocess ஆக உருவாக்கி தொடர்பு கொள்ளும் திறனை உறுதி செய்கின்றன. +MCP தொகுதி stdio போக்குவரத்துடன் மாடல் காட்சி நெறிமுறை ஒருங்கிணைப்பை சோதனை செய்யும். இந்த சோதனைகள் உங்கள் பயன்பாடு subprocess ஆக MCP சர்வர்களை எப்படி உருவாக்கி தொடர்பு கொள்கிறது என்பதைக் சோதிக்கின்றன. -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` இல் உள்ள இந்த சோதனைகள் MCP கிளையண்ட் நடத்தை சரிபார்க்கின்றன. +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` இல் உள்ள சோதனைகள் MCP கிளையண்ட் நடத்தை சரிபார்க்கின்றன. -**இவற்றை இயக்க:** +**இவற்றை இயக்கவும்:** **Bash:** ```bash @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## சோதனை தத்துவம் -AI-வை அல்ல, உங்கள் கோடுகளை சோதியுங்கள். நீங்கள் எழுதும் கோடு கட்டமைவு எப்படி என்பதை, நினைவக மேலாண்மை மற்றும் கருவி செயல்பாடுகளை உங்கள் சோதனைகள் சரிபார்க்க வேண்டும். AI பதில்கள் மாறுபடக்கூடியவை, அதை சோதனை நிபந்தனைகளில் சேர்க்க வேண்டாம். உங்கள் முன்மொழிவு வடிவமைப்பு மாறிகளை சரியாக மாற்றுகிறதா என்பதை பரிசீலியுங்கள், AI சரியான பதிலை தருகிறதா என்று அல்ல. +AI-ஐ அல்லாமல் உங்கள் குறியீட்டை சோதியுங்கள். உங்கள் சோதனைகள் நீங்கள் எழுதிய குறியீட்டை சரிபார்க்க வேண்டும்; கூடியார்கள் எவ்வாறு கட்டமைக்கப்பட்டுள்ளன, நினைவகம் எப்படி நிர்வகிக்கப்படுகிறது, கருவிகள் எப்படி செயல்படுகின்றன என்பதைக் கண்டறிந்து. AI பதில்கள் மாறுபடும், அதனால் அவை சோதனை விசாரணைகளின் பகுதியாக இருக்கக் கூடாது. உங்கள் கூடியார் டெம்ப்ளேட் மாறிகளையே சரியாக பொருத்துகிறதா என்பதில் கவனம் செலுத்துங்கள், AI சரியான பதிலை வழங்குகிறதா என்பதில் அல்ல. -மொழி மாதிரிகளுக்கு மொக்குகளை பயன்படுத்துங்கள். அவை வெளிப்புற சார்புகளாகும்; அவை மெதுவானவை, விலைப்பட்டவை மற்றும் தீர்மானிக்க முடியாதவை. மொக்குகள் சோதனைகளை சில மில்லியசெகன்களில் விரைவாக, இலவசமாக, மற்றும் தீர்மானிக்கப்பட்டவையாக மாற்றுகின்றன. +மொழி மாடல்களுக்கு மோக்குகளை பயன்படுத்துங்கள். இவை மெதுவான, செலவான, மற்றும் தீர்மானமற்ற வெளிப்புற சார்புகள். மோக்கிங் சோதனைகளை சில விநாடிகளுக்கு பதிலாக மெலிந்த(milliseconds) வேகமாகவும், API செலவில்லாமல் இலவசமாகவும், மற்றும் ஒவ்வொரு முறையும் ஒரே முடிவுடன் தீர்மானமானதாகவும் மாற்றுகிறது. -சோதனைகள் தனித்தனியாக இருக்கட்டும். ஒவ்வொரு சோதனையும் தானாகவே தரவை அமைக்க வேண்டும், மற்ற சோதனைகளில் சார்ந்திருக்க கூடாது மற்றும் முடிந்தவுடன் சுத்தம் செய்ய வேண்டும். சோதனைகள் இயக்கிய வரிசைக்கு பாதிப்பு இல்லாமல் கடந்து விட வேண்டும். +சோதனைகளை சுயாதீனமாக வைத்திருங்கள். ஒவ்வொரு சோதனையும் தற்காலிக தரவை அமைத்து, மற்ற சோதனைகளைக் சாராது மற்றும் தானாகத் தூய்மைப்படுத்தவும் வேண்டும். சோதனைகள் இயக்க வரிசையால் பாதிக்கப்படக்கூடாது. -சந்தோசமான வழி தவிர வேறுபடுபவற்றையும் சோதியுங்கள். காலியான உள்ளீடு, மிகவும் பெரிய உள்ளீடு, சிறப்பு எழுத்துக்கள், தவறான அளவுருக்கள் மற்றும் எல்லை நிலைகள் போன்றவற்றை முயற்சிக்கவும். இவை வழக்கமான பயன்பாட்டில் தெரியாத பிழைகளை வெளிப்படுத்தும். +மகிழ்ச்சியான பாதை மிக்க வழிமுறைக்கு கூடுவதைத் தவிர வெளியே இருக்கக்கூடிய எல்லைகளையும் சோதியுங்கள். காலியாக உள்ளீடு, மிகப்பெரிய உள்ளீடு, விசேஷ எழுத்துக்கள், தவறான அளவுருக்கள் மற்றும் எல்லை நிலைகள் போன்றவற்றை முயற்சியுங்கள். இவை உள்ளாட்சி பயன்பாட்டால் தெரியாத பிழைகளை அடையாளம் காண்கிறன. -விளக்கமான பெயர்களை பயன்படுத்துங்கள். `shouldMaintainConversationHistoryAcrossMultipleMessages()` மற்றும் `test1()` ஐ ஒப்பிடுக. முதல் பெயர் என்ன சோதனை செய்யப் பட்டதென்று தெளிவாக சொல்கிறது, தவறுகளை கண்டறிய உதவும். +விளக்கமான பெயர்களைப் பயன்படுத்துங்கள். `shouldMaintainConversationHistoryAcrossMultipleMessages()` மற்றும் `test1()` ஐ ஒப்பிடுங்கள். முதல் பெயர் என்ன சோதிக்கப்படுகிறது என்பதைக் தெளிவாக காட்டுவதால் தோல்விகளை பிழையுணர்வை எளிதாக்குகிறது. ## அடுத்த படிகள் -சோதனை மாதிரிகளை நீங்கள் புரிந்துவிட்டீர்கள், இப்பொழுது ஒவ்வொரு யூனிட்டிலும் ஆழமாக நுழையுங்கள்: +சோதனை வடிவங்களைப் புரிந்து கொண்டுள்ளதால், ஒவ்வொரு தொகுதியிலும் ஆழமாக செல்லுங்கள்: -- **[00 - தைவிர் துவக்கம்](../00-quick-start/README.md)** - முன்மொழிவு வடிவமைப்பு அடிப்படைகள் -- **[01 - அறிமுகம்](../01-introduction/README.md)** - உரையாடல் நினைவகம் மேலாண்மை கற்றல் -- **[02 - முன்மொழிவு பொறியியல்](../02-prompt-engineering/README.md)** - GPT-5.2 முன்மொழிவு மாதிரிகள் கற்றல் -- **[03 - RAG](../03-rag/README.md)** - பெறுமதி கூட்டிய உருவாக்கம் அமைப்புகள் கட்டமைத்தல் -- **[04 - கருவிகள்](../04-tools/README.md)** - செயல்பாடு அழைப்பு மற்றும் கருவி தொடர்கள் நடைமுறைப்படுத்தல் -- **[05 - MCP](../05-mcp/README.md)** - மாடல் சூழல் நெறிமுறை ஒருங்கிணைத்தல் +- **[01 - அறிமுகம்](../01-introduction/README.md)** - உரையாடல் நினைவகம் நிர்வாகம் கற்க +- **[02 - கூடியார் வடிவமைப்பு](../02-prompt-engineering/README.md)** - GPT-5.2 கூடியார் வடிவங்களை நிபுணத்துவம் பெற +- **[03 - RAG](../03-rag/README.md)** - பெறுகை-பெருக்கப்பட்ட உருவாக்க அமைப்புகளை கட்டமை +- **[04 - கருவிகள்](../04-tools/README.md)** - செயல்பாடு அழைப்பும் கருவி சங்கிலி செயல்பாடும் நடைமுறைப்படுத்து +- **[05 - MCP](../05-mcp/README.md)** - மாடல் காட்சி நெறிமுறை ஒருங்கிணைப்பு செய் -ஒவ்வொரு யூனிட்டின் README இல் இங்கு சோதிக்கப்பட்ட கருத்துக்களின் விரிவான விளக்கங்கள் உள்ளன. +ஒவ்வொரு தொகுதியின் README இல் இங்கு சோதிக்கப்பட்ட கருத்துக்களின் விரிவான விளக்கங்கள் உள்ளன. --- -**வழிசெலுத்தல்:** [← பிரதானத்துக்கு திரும்ப](../README.md) +**வழிசெல்வது:** [← பிரதான பக்கம்](../README.md) --- -**விராதி**: -இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. நாங்கள் துல்லியத்தன்மைக்கு முயற்சி செய்கிறோம், எனினும் தானாக செய்யப்பட்ட மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்க வாய்ப்பு உள்ளது என்பதை கவனிக்கவும். இயற்பொருள் ஆவணம் அதன் சொந்த மொழியிலேயே அதிகாரப்பூர்வமான வன்பொருளாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்காக, தொழில்முறை மனித மொழிபெயர்ப்பை பரிந்துரைக்கிறோம். இந்த மொழிபெயர்ப்பின் பயன்படுத்தலால் ஏற்படும் எந்த தவறிய புரிதல் அல்லது விமர்சனங்களிலும் நாங்கள் பொறுப்பேற்கமாட்டோம். +**மறுப்பு**: +இந்த ஆவணம் AI மொழிபெயர்ப்பு சேவை [Co-op Translator](https://github.com/Azure/co-op-translator) பயன்படுத்தி மொழிபெயர்க்கப்பட்டுள்ளது. நாங்கள் துல்லியத்திற்காக முயற்சி செய்துள்ளோம், ஆனால் தானாக செய்யப்படும் மொழிபெயர்ப்புகளில் பிழைகள் அல்லது தவறுகள் இருக்கலாம் என்பதை கவனத்தில் கொள்ளவும். அசல் ஆவணம் அதன் தாய்மொழியில் அதிகாரப்பூர்வ ஆதாரமாக கருதப்பட வேண்டும். முக்கியமான தகவல்களுக்கு, தொழில்நுட்பமான மனித மொழிபெயர்ப்பு பரிந்துரைக்கப்படுகிறது. இந்த மொழிபெயர்ப்பைப் பயன்படுத்துவதால் ஏற்படும் எந்த தவறான புரிதல்கள் அல்லது தவறான விளக்கத்திற்கும் நாங்கள் பொறுப்பில்வில்லை. \ No newline at end of file diff --git a/translations/te/.co-op-translator.json b/translations/te/.co-op-translator.json index ce023ec95..a33f240b7 100644 --- a/translations/te/.co-op-translator.json +++ b/translations/te/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "te" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T01:52:11+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T12:33:20+00:00", "source_file": "01-introduction/README.md", "language_code": "te" }, @@ -18,20 +18,20 @@ "language_code": "te" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T01:55:21+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T12:26:56+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "te" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T01:57:21+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T12:32:09+00:00", "source_file": "03-rag/README.md", "language_code": "te" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:08:47+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T12:30:15+00:00", "source_file": "04-tools/README.md", "language_code": "te" }, @@ -54,8 +54,8 @@ "language_code": "te" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:16:01+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T12:25:16+00:00", "source_file": "README.md", "language_code": "te" }, @@ -72,14 +72,14 @@ "language_code": "te" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T02:01:57+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T12:27:43+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "te" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T02:02:51+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T12:28:30+00:00", "source_file": "docs/TESTING.md", "language_code": "te" } diff --git a/translations/te/00-quick-start/README.md b/translations/te/00-quick-start/README.md deleted file mode 100644 index 882b913bb..000000000 --- a/translations/te/00-quick-start/README.md +++ /dev/null @@ -1,388 +0,0 @@ -# మాడ్యూల్ 00: త్వరిత ప్రారంభం - -## విషయ సూచిక - -- [పరిచయం](../../../00-quick-start) -- [LangChain4j అంటే ఏమిటి?](../../../00-quick-start) -- [LangChain4j ఆధారాలు](../../../00-quick-start) -- [అవసరాలు](../../../00-quick-start) -- [సెట్టప్](../../../00-quick-start) - - [1. మీ GitHub టోకెన్ పొందండి](../../../00-quick-start) - - [2. మీ టోకెన్ సెట్ చేయండి](../../../00-quick-start) -- [ఉదాహరణలను నడపండి](../../../00-quick-start) - - [1. ప్రాథమిక చాట్](../../../00-quick-start) - - [2. ప్రాంప్ట్ నమూనాలు](../../../00-quick-start) - - [3. ఫంక్షన్ కాలింగ్](../../../00-quick-start) - - [4. డాక్యుమెంట్ ప్రశ్నోత్తరాలు (సులభమైన RAG)](../../../00-quick-start) - - [5. బాధ్యతాయుత AI](../../../00-quick-start) -- [ప్రతి ఉదాహరణ ఏమి చూపిస్తుంది](../../../00-quick-start) -- [తరువాతి దశలు](../../../00-quick-start) -- [సమస్య పరిష్కారం](../../../00-quick-start) - -## పరిచయం - -ఈ త్వరితప్రారంభం LangChain4j తో మీరు వీక్షించేందుకు మరియు నిర్దేశించేందుకు గడువు వేస్తుంది. ఇది LangChain4j మరియు GitHub Models తో AI అప్లికేషన్‌లు నిర్మిస్తున్న అత్యంత ప్రాథమిక విషయాలు కవర్ చేస్తుంది. తదుపరి మాడ్యూల్స్‌లో మీరు Azure OpenAI మరియు GPT-5.2 కు మార్చుకుంటారు మరియు ప్రతి భావనలో లోతుగా జారతారు. - -## LangChain4j అంటే ఏమిటి? - -LangChain4j అనేది AI-శక్తివంతమైన అప్లికేషన్‌ల నిర్మాణాన్ని సులభతరం చేసే జావా లైబ్రరీ. HTTP క్లయింట్లు మరియు JSON అనలిసిస్ చేయాల్సిన అవసరం లేకుండా, మీరు శుచిగా ఉన్న జావా APIలతో పనిచేస్తారు. - -LangChainలో "చైన్" అనేది అనేక భాగాలు కలిపే క్రమం - మీరు ఒక ప్రాంప్ట్ నుండి మోడల్, తరువాత పార్సర్ కు లేదా అనేక AI పిలుపులు కలిపి ఒకౌట్‌పుట్ తదుపరి ఇన్‌పుట్‌కి ఇచ్చే రూపంలో కలిపే విధంగా ఉంటుంది. ఈ త్వరితప్రారంభం కాంప్లెక్స్ చైన్లు అన్వేషించడానికి మునుపుగా ప్రాథమిక విషయాలు మీద దృష్టి సారిస్తుంది. - -LangChain4j Chaining Concept - -*LangChain4jలో భాగాలను చైన్ చేయడం - శక్తివంతమైన AI పనిముట్లు సృష్టించడానికి బ్లాకులు కలిపే విధానం* - -మేము మూడు ముఖ్యమైన భాగాలను ఉపయోగిస్తాము: - -**ChatModel** - AI మోడల్ ఇంటరాక్షన్ ఇంటర్ఫేస్. `model.chat("prompt")` ను పిలిచి ఒక ప్రతిస్పందన స్ట్రింగ్ పొందండి. మేము `OpenAiOfficialChatModel` ఉపయోగిస్తాము, ఇది GitHub Models వంటి OpenAI-అనుకూల ఎండ్పాయింట్లతో పని చేస్తుంది. - -**AiServices** - టైపు-భద్రమయి AI సర్వీస్ ఇంటర్ఫేస్‌ను సృష్టిస్తుంది. విధానాలను నిర్వచించండి, వాటిని `@Tool` తో ట్యాగ్ చేయండి, LangChain4j మొత్తం ఒర్పెస్ట్రేషన్‌ను హ్యాండిల్ చేస్తుంది. అవసరం వచ్చినప్పుడు AI మీ జావా పద్ధతులను ఆటోమేటిక్ పిలుస్తుంది. - -**MessageWindowChatMemory** - సంభాషణ చరిత్రను నిలుపుతుంది. దీని లేకుండా ప్రతి అభ్యర్థన స్వతంత్రమైనది. దీనితో AI ముందు సందేశాలను గుర్తుంచుకుంటూ సంగతులను అనుసరిస్తుంది. - -LangChain4j Architecture - -*LangChain4j నిర్మాణం - ముఖ్య భాగాలు కలిసి మీ AI అప్లికేషన్ లకు శక్తి అందజేస్తాయి* - -## LangChain4j ఆధారాలు - -ఈ త్వరితప్రారంభం మూడు Maven ఆధారాలను [`pom.xml`](../../../00-quick-start/pom.xml) లో ఉపయోగిస్తుంది: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` మాడ్యూల్ `OpenAiOfficialChatModel` క్లాస్ అందిస్తుంది, ఇది OpenAI అనుకూల APIs తో కనెక్ట్ అవుతుంది. GitHub Models కూడా అదే API ఫార్మాట్ ఉపయోగిస్తుంది, కాబట్టి ప్రత్యేక అడాప్టర్ అవసరం లేదు - బేస్ URLను `https://models.github.ai/inference` గా పాయింట్ చేయండి. - -`langchain4j-easy-rag` మాడ్యూల్ ఆటోమేటిక్ డాక్యుమెంట్ విభజన, ఎంబెడింగ్ మరియు రిట్రీవల్ అందిస్తుంది, అందువల్ల మీరు RAG అప్లికేషన్‌లను మానవీయంగా ప్రతీ దశను నిర్దేశించకుండా నిర్మించవచ్చు. - -## అవసరాలు - -**Dev Container ఉపయోగిస్తున్నారా?** జావా మరియు మావెన్ ఇప్పటికే ఇన్‌స్టాల్ చేయబడ్డాయి. మీరు GitHub వ్యక్తిగత యాక్సెస్ టోకెన్ మాత్రమే అవసరం. - -**లోకల్ అభివృద్ధి:** -- జావా 21+, మావెన్ 3.9+ -- GitHub వ్యక్తిగత యాక్సెస్ టోకెన్ (కింద ఇచ్చిన సూచనలు) - -> **గమనిక:** ఈ మాడ్యూల్ GitHub Models నుండి `gpt-4.1-nano` ను ఉపయోగిస్తుంది. కోడ్‌లో మోడల్ పేరును మార్చవద్దు - ఇది GitHub అందుబాటులో ఉన్న మోడల్స్‌తో పనిచేసే విధంగా కాన్ఫిగర్ చేయబడింది. - -## సెట్‌అప్ - -### 1. మీ GitHub టోకెన్ పొందండి - -1. [GitHub సెట్టింగ్స్ → వ్యక్తిగత యాక్సెస్ టోకెన్లు](https://github.com/settings/personal-access-tokens) కి వెళ్లండి -2. "Generate new token" పై క్లిక్ చేయండి -3. వివరణాత్మక పేరు సెట్ చేయండి (ఉదాహరణకు, "LangChain4j Demo") -4. గడువును సెట్ చేయండి (7 రోజులు సిఫార్సు) -5. "ఖాతా అనుమతులు" కింద "Models" ను "Read-only" గా సెట్ చేయండి -6. "Generate token" పై క్లిక్ చేయండి -7. మీ టోకెన్ ను కాపీ చేసి సేవ్ చేసుకోండి - మీరు మళ్లీ చుడలేనిది - -### 2. మీ టోకెన్ సెట్ చేయండి - -**ఎంపిక 1: VS Code ఉపయోగించటం (సిఫార్సు చేయబడింది)** - -మీరు VS Code ఉపయోగిస్తే, ప్రాజెక్టు రూట్ లో `.env` ఫైల్‌లో మీ టోకెన్ ను జోడించండి: - -`.env` ఫైల్ లేని పక్షంలో, `.env.example` నుండి `.env` కు కాపీ చేయండి లేదా కొత్త `.env` ఫైల్ సృష్టించండి. - -**ఉదాహరణ `.env` ఫైల్:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env లో -GITHUB_TOKEN=your_token_here -``` - -తర్వాత మీరు ఎక్స్ప్లోరర్‌లో ఏ డెమో ఫైలుపై అయినా (ఉదాహరణకు `BasicChatDemo.java`) రైట్ క్లిక్ చేసి **"Run Java"** ఎంచుకోవచ్చు లేదా Run & Debug ప్యానెల్ నుండి లాంఛ్ కాన్ఫిగరేషన్లను ఉపయోగించవచ్చు. - -**ఎంపిక 2: టెర్మినల్ ఉపయోగించడం** - -టోకెన్ ను ఎన్విరాన్‌మెంట్ వేరియబుల్‌గా సెట్ చేయండి: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## ఉదాహరణలను నడపండి - -**VS Code ఉపయోగిస్తున్నప్పుడు:** ఎక్స్ప్లోరర్‌లో ఏ డెమో ఫైల్‌ను అయినా రైట్ క్లిక్ చేసి **"Run Java"** ఎంచుకోండి, లేదా ముందుగా `.env` ఫైల్‌లో టోకెన్ జోడించి Run & Debug ప్యానెల్ లో లాంఛ్ కాన్ఫిగరేషన్లను ఉపయోగించండి. - -**Maven ఉపయోగించి:** లేదా, కింది కమాండ్ లైన్ నుంచి నడిపించండి: - -### 1. ప్రాథమిక చాట్ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. ప్రాంప్ట్ నమూనాలు - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -జీరో-షాట్, ఫ్యూషాట్, చైన్-ఆఫ్-తొట, మరియు పాత్ర-ఆధారిత ప్రాంప్టింగ్ చూపిస్తుంది. - -### 3. ఫంక్షన్ కాలింగ్ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI అవసరమనుకుంటే ఆటోమేటిక్ గా మీ జావా మెథడ్స్ పిలుస్తుంది. - -### 4. డాక్యుమెంట్ ప్రశ్నోత్తరాలు (సులభమైన RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -ఆటోమేటిక్ ఎంబెడింగ్ మరియు రిట్రీవల్ తో Easy RAG ఉపయోగించి మీ డాక్యుమెంట్లకు సంబంధించిన ప్రశ్నలను అడగండి. - -### 5. బాధ్యతాయుత AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -AI సేఫ్టీ ఫిల్టర్లు హానికర కంటెంట్ ని ఎలా నిరోధిస్తాయో చూడండి. - -## ప్రతి ఉదాహరణ ఏమి చూపిస్తుంది - -**ప్రాథమిక చాట్** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -ఇక్కడ LangChain4j యొక్క అత్యంత సరళమైన రూపాన్ని చూడండి. మీరు ఒక `OpenAiOfficialChatModel` సృష్టించి, `.chat()` తో ఒక ప్రాంప్ట్ పంపించి, స్పందన పొందగలిగే విధంగా ఉంటుంది. ఇది పునాదులను చూపిస్తుంది: కస్టమ్ ఎండ్పాయింట్లు మరియు API కీలు ఉపయోగించి మోడల్స్‌ను స్వయంచాలకంగా ప్రారంభించడం. ఈ నమూనా అర్థమైతే, మిగతా ప్రతీది దీని మీద ఆధారపడి ఉంటుంది. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్ తో ప్రయత్నించండి:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) తెరవండి మరియు అడగండి: -> - "GitHub Models నుండి Azure OpenAI కి ఈ కోడ్‌లో ఎలా మార్చాలి?" -> - "OpenAiOfficialChatModel.builder() లో మరే ఇతర ప్యారామీటర్లను నాను సెట్ చేయవచ్చు?" -> - "పూర్తి స్పందన కోసం వేచి ఉండకుండా స్ట్రీమింగ్ స్పందనలను ఎలా జోడించాలి?" - -**ప్రాంప్ట్ ఇంజనీరింగ్** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -ఇప్పుడు మీరు మోడల్‌తో ఎలా మాట్లాడాలో తెలుసుకున్న తర్వాత, మీరు దానికి ఏమి చెప్పాలో అన్వేషించుకుందాం. ఈ డెమో అదే మోడల్ సెటప్‌ను ఉపయోగించి ఐదు వేర్వేరు ప్రాంప్టింగ్ నమూనాలను చూపిస్తుంది. నేరుగా సూచనలు కోసం జీరో-షాట్ ప్రాంప్ట్లు, ఉదాహరణల నుంచి నేర్చుకునే ఫ్యూషాట్ ప్రాంప్ట్‌లు, తర్క సాధన చర్యలను వెల్లడి చేసే చైన్-ఆఫ్-తోట్ ప్రాంప్ట్లు, మరియు సందర్భాన్ని సేత్ చేసే పాత్ర-ఆధారిత ప్రాంప్ట్‌లు చూడండి. ఒకే మోడల్ అడిగే విధానాన్ని బట్టి ఎంత భిన్నమైన ఫలితాలు ఇస్తుంది గమనించండి. - -డెమో ప్రాంప్ట్ టెంప్లేట్లను కూడా చూపిస్తుంది, ఇవి వేరియబుల్స్ తో రీయూజబుల్ ప్రాంప్ట్‌లు సృష్టించడానికి శక్తివంతమైన పద్ధతి. - -కింద ఇచ్చిన ఉదాహరణలో LangChain4j `PromptTemplate` ఉపయోగించి వేరియబుల్స్ నింపడం చూపిస్తుంది. AI ఇచ్చిన గమ్యం మరియు కార్యకలాపం ఆధారంగా జవాబు ఇస్తుంది. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్ తో ప్రయత్నించండి:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) తెరవండి మరియు అడగండి: -> - "జీరో-షాట్ మరియు ఫ్యూషాట్ ప్రాంప్టింగ్ మధ్య తేడా ఏంటి, ఏది ఎప్పుడు ఉపయోగించాలి?" -> - "టెంపరేచర్ ప్యారామీటర్ ఎలా మోడల్ స్పందనలను ప్రభావితం చేస్తుంది?" -> - "ప్రొడక్షన్‌లో ప్రాంప్ట్ ఇంజక్షన్ దాడులను ఎలా నివారించాలి?" -> - "సాధారణ నమూనాల కోసం రీయూజబుల్ PromptTemplate వస్తువులను ఎలా సృష్టించాలి?" - -**టూల్ ఇంటిగ్రేషన్** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -ఇక్కడ LangChain4j శక్తివంతం అవుతుంది. మీరు `AiServices` ఉపయోగించి మీ జావా పద్ధతులను పిలవగల AI సహాయకుని సృష్టిస్తారు. వికలంగా, `@Tool("description")` తో మెథడ్స్‌ను ట్యాగ్ చేయండి మరియు LangChain4j మిగత దాన్ని నిర్వహిస్తుంది - AI యూజర్ అడిగిన దాని ఆధారంగా ఏ టూల్ ఉపయోగించాలో నిర్ణయిస్తుంది. ఇది పంక్షన్ కాలింగ్‌ను చూపిస్తుంది, ఇది ప్రశ్నలకు మాత్రమే కాక చర్యలు చేయగల AI సృష్టించడానికి ముఖ్యమైన సాంకేతికత. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్ తో ప్రయత్నించండి:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) తెరవండి మరియు అడగండి: -> - "@Tool అనోటేషన్ ఎలా పనిచేస్తుంది మరియు LangChain4j వెనుక దాన్ని ఎలా నిర్వహిస్తుంది?" -> - "AI పలు టూల్స్‌ను వరుసగా పిలిచి సంక్లిష్ట సమస్యలను ఎలా పరిష్కరిస్తుంది?" -> - "టూల్ ఎర్రర్‌లు చోటుచేసుకుంటే నేను ఎలా హ్యాండిల్ చేయాలి?" -> - "ఈ కాలిక్యులేటర్ ఉదాహరణకు బదులుగా వాస్తవ APIని ఎలా ఇంటిగ్రేట్ చేయాలి?" - -**డాక్యుమెంట్ ప్రశ్నోత్తరాలు (సులభమైన RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -ఇక్కడ మీరు LangChain4j "Easy RAG" విధానం ఉపయోగించి RAG (రిట్రీవల్-ఆగ్మెంటెడ్ జనరేషన్) చూడగలరు. డాక్యుమెంట్లు లోడ్ అవుతాయి, ఆటోమేటిక్ గా విడగొట్టబడతాయి మరియు మెమరీలోని స్టోర్‌లో ఎంబెడ్ చేయబడతాయి, ఆపై కంటెంట్ రిట్రీవర్ ప్రాస్న సమయానికి సంబంధిత భాగాలను AI కి అందిస్తుంది. AI మీ డాక్యుమెంట్ల ఆధారంగా సమాధానాలు ఇస్తుంది, దాని సాధారణ జ్ఞానంపై కాకుండా. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్ తో ప్రయత్నించండి:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) తెరవండి మరియు అడగండి: -> - "AI హల్యూసినేషన్లను RAG ఎలా నివారిస్తుంది, మోడల్ ట్రైనింగ్ డేటాతో పోల్చితే?" -> - "ఈ సులభ పద్ధతి మరియు కస్టమ్ RAG పైప్లిన్ మధ్య తేడా ఏమిటి?" -> - "ఈ విధానాన్ని బహుళ డాక్యుమెంట్లు లేదా పెద్ద జ్ఞాన ఆధారాలు కోసం ఎలా పెంచుకోవచ్చు?" - -**బాధ్యతాయుత AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -రక్షణలో మందగింపు కలిగించి AI సేఫ్టీని నిర్మించండి. ఈ డెమో రెండు పరతుల రక్షణను కలిపి చూపిస్తుంది: - -**భాగం 1: LangChain4j ఇన్‌పుట్ గార్డ్‌రెయిల్స్** - LLM కి చేరకముందే ప్రమాదకర ప్రాంప్ట్‌లను బ్లాక్ చేయండి. నిషేధిత కీవర్డ్స్ లేదా నమూనాలను తనిఖీ చేసే కస్టమ్ గార్డ్‌రెయిల్స్ సృష్టించండి. ఇవి మీ కోడ్‌లో నడుస్తాయి కాబట్టి త్వరగా మరియు ఉచితంగా పనిచేస్తాయి. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**భాగం 2: ప్రొవైడర్ సేఫ్టీ ఫిల్టర్స్** - GitHub Models లో బిల్ట్-ఇన్ ఫిల్టర్లు ఉన్నాయి, ఇవి మీ గార్డ్‌రెయిల్స్ తప్పిపోయే వాటిని పట్టుకుంటాయి. తీవ్రమైన ఉల్లంఘనలకు హార్డ్ బ్లాక్స్ (HTTP 400 ఎర్రర్లు) మరియు మంచి సౌమ్యంగా నిరాకరణల రూపంలో సాఫ్ట్ రిఫ్యూజల్స్ ఉంటాయి. - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్ తో ప్రయత్నించండి:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) తెరవండి మరియు అడగండి: -> - "InputGuardrail అంటే ఏమిటి మరియు నేను ఎలా నా సొంత వాటిని సృష్టించవచ్చు?" -> - "హార్డ్ బ్లాక్ మరియు సాఫ్ట్ రిఫ్యూజల్ మధ్య తేడా ఏమిటి?" -> - "ఎందుకు గార్డ్‌రెయిల్స్ మరియు ప్రొవైడర్ ఫిల్టర్స్ రెండింటినీ కలిపి వాడాలి?" - -## తర్వాతి దశలు - -**తరువాతి మాడ్యూల్:** [01-పరిచయం - LangChain4j తో ప్రారంభం](../01-introduction/README.md) - ---- - -**నావిగేషన్:** [← మెయిన్‌కు తిరిగి](../README.md) | [తరువాత: మాడ్యూల్ 01 - పరిచయం →](../01-introduction/README.md) - ---- - -## సమస్య పరిష్కారం - -### మొదటి సారి Maven బిల್ಡ್ - -**సమस्या**: మొదటి `mvn clean compile` లేదా `mvn package` చాలా సమయం తీసుకుంటుంది (10-15 నిమిషాలు) - -**కారణం**: Maven మొదటి సారి అన్ని ప్రాజెక్టు ఆధారాలు (Spring Boot, LangChain4j లైబ్రరీలు, Azure SDKలు మొదలైనవి) డౌన్లోడ్ చేయాల్సి ఉంటుంది. - -**పరిష్కారం**: ఇది సాధారణ ప్రవర్తన. తరువాతి బిల్డ్స్ చాలా వేగంగా ఉంటాయి ఎందుకంటే ఆధారాలను స్థానికంగా క్యాష్ చేస్తుంది. డౌన్లోడ్ సమయము మీ నెట్‌వర్క్ వేగం మీద ఆధారపడి ఉంటుంది. - -### PowerShell Maven కమాండ్ సింటాక్స్ - -**సమస్య**: Maven కమాండ్లు `Unknown lifecycle phase ".mainClass=..."` అనే తప్పిదంతో విఫలమవుతాయి -**కారణం**: PowerShell `=` ను వేరియబుల్ అసైన్‌మెంట్ ఆపరేటర్‌గా గ్రహించి, Maven ప్రాపర్టీ సింటాక్స్‌ను విరుచుకుంటుంది - -**పరిష్కారం**: Maven కమాండ్ ముందు `--%` స్టాప్-పార్సింగ్ ఆపరేటర్‌ను ఉపయోగించండి: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` ఆపరేటర్ PowerShellకి మిగిలిన ఆర్గుమెంట్స్‌ను Mavenకు అనువాదం లేకుండా సరిగ్గా გადასరించమని సూచిస్తుంది. - -### Windows PowerShell ఎమోజీ ప్రదర్శన - -**సమస్య**: PowerShellలో AI ప్రతిస్పందనలు ఎమోజీల స్థానంలో నాశనం అయిన అక్షరాలు (ఉదా: `????` లేదా `â??`) చూపించాయి - -**కారణం**: PowerShell యొక్క డిఫాల్ట్ ఎన్‌కోడింగ్ UTF-8 ఎమోజీలను మద్దతు ఇవ్వదు - -**పరిష్కారం**: Java అప్లికేషన్లు నడుపు ముందు ఈ కమాండ్‌ను నడపండి: -```cmd -chcp 65001 -``` - -ఇది టెర్మినల్‌లో UTF-8 ఎన్‌కోడింగ్‌ను బలవంతం చేస్తుంది. మరోవైపు, మెరుగైన యూనికోడ్ మద్దతు ఉన్న Windows Terminalను వాడండి. - -### API కాల్లను డీబగ్ చేయడం - -**సమస్య**: AI మోడల్ నుండి ఆథెంటికేషన్ లోపాలు, రేట్ లిమిట్స్, లేక అనుకోని ప్రతిస్పందనలు - -**పరిష్కారం**: ఉదాహరణల్లో `.logRequests(true)` మరియు `.logResponses(true)` ఉన్నాయి, ఇవి API కాల్లను కన్సోల్‌లో చూపిస్తాయి. ఇది ఆథెంటికేషన్ లోపాలు, రేట్ లిమిట్స్, లేదా అనుకోని ప్రతిస్పందనలను అన్వేషించడంలో సహాయపడుతుంది. ఉత్పత్తిలో ఈ ఫ్లాగ్లను తీసివేసి లాగ్ శబ్దాన్ని తగ్గించండి. - ---- - - -**ఉపసంహారం**: -ఈ పత్రాన్ని AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ను ఉపయోగించి అనువదించాము. సరైన అనువాదానికి ప్రయత్నించినప్పటికీ, ఆగమికార అనువాదాలలో తప్పులూ లేదా అసమర్థతలూ ఉండకూడదు. స్థానిక భాషలో ఉన్న అసలు పత్రం ప్రామాణిక మూలంగా తీసుకోవాలి. ముఖ్యమైన సమాచారానికి వృత్తిపరమైన మానవ అనువాదం చేయించడం మేలైంది. ఈ అనువాదం వాడుక వల్ల కలిగే ఏదైనా తప్పు అర్థగర్భితం లేదా పొరపాటులకు మేము బాధ్యత వహించము. - \ No newline at end of file diff --git a/translations/te/01-introduction/README.md b/translations/te/01-introduction/README.md index 09d2ec31e..eae5c7cf0 100644 --- a/translations/te/01-introduction/README.md +++ b/translations/te/01-introduction/README.md @@ -1,87 +1,87 @@ -# మոդ్యూల్ 01: LangChain4j తో ప్రారంభించడం +# మాడ్యూల్ 01: LangChain4j తో ప్రాతమిక పరిచయం -## విషయాల పట్టిక +## విషయ సూచీ -- [వీడియో వాక్త్రూథ్](../../../01-introduction) -- [మీరు ఏం నేర్చుకుంటారు](../../../01-introduction) -- [ఆవశ్యకతలు](../../../01-introduction) -- [కోర్ సమస్యను అవగాహన చేసుకోవడం](../../../01-introduction) -- [టోకెన్లను అర్థం చేసుకోవడం](../../../01-introduction) -- [మెమరీ ఎలా పనిచేస్తుంది](../../../01-introduction) -- [ఇది LangChain4j ను ఎలా ఉపయోగిస్తుంది](../../../01-introduction) -- [Azure OpenAI ఇంఫ్రాస్ట్రక్చర్ ని డిప్లాయ్ చేయడం](../../../01-introduction) -- [ఆప్లికేషన్ ని లోకల్ గా రన్ చేయడం](../../../01-introduction) -- [ఆప్లికేషన్ ఉపయోగించడం](../../../01-introduction) - - [Stateless చాట్ (ఎడమ ప్యానెల్)](../../../01-introduction) - - [Stateful చాట్ (కుడి ప్యానెల్)](../../../01-introduction) -- [తదుపరి దశలు](../../../01-introduction) +- [వీడియో వాకథ్రూ](#వీడియో-వాకథ్రూ) +- [మీరు నేర్చుకునేది ఏమిటి](#మీరు-నేర్చుకునేది-ఏమిటి) +- [అవసరమైన పరిజ్ఞానం](#అవసరమైన-పరిజ్ఞానం) +- [ప్రధాన సమస్యను అర్థం చేసుకోవడం](#ప్రధాన-సమస్యను-అర్థం-చేసుకోవడం) +- [టోకెన్లను అర్థం చేసుకోవడం](#టోకెన్లను-అర్థం-చేసుకోవడం) +- [మెమరీ ఎలా పనిచేస్తుంది](#మెమరీ-ఎలా-పని-చేస్తుంది) +- [ఇది LangChain4j ను ఎలా ఉపయోగిస్తుంది](#ఇది-langchain4j-ను-ఎలా-ఉపయోగిస్తుంది) +- [Azure OpenAI ఇన్‌ఫ్రాస్ట్రక్చర్‌ను మిళితం చేయడం](#azure-openai-ఇన్‌ఫ్రాస్ట్రక్చర్‌ను-మిళితం-చేయడం) +- [యాప్‌ను స్థానికంగా నడపడం](#యాప్‌ను-స్థానికంగా-నడపడం) +- [యాప్‌ను ఉపయోగించడం](#యాప్-ఉపయోగించడం) + - [స్టేట్‌లెస్ చాట్ (ఎడమ ప్యానెల్)](#స్టేట్‌లెస్-చాట్-ఎడమ-ప్యానెల్) + - [స్టేట్‌ఫుల్ చాట్ (కుడి ప్యానెల్)](#స్టేట్‌ఫుల్-చాట్-కుడి-ప్యానెల్) +- [తరువాతి దశలు](#తర్వాతి-దశలు) -## వీడియో వాక్త్రూథ్ +## వీడియో వాకథ్రూ -ఈ మోడ్యూల్ తో ఎలా ప్రారంభించాలో వివరిస్తున్న లైవ్ సెషన్ ను వీక్షించండి: +ఈ మాడ్యూల్‌తో ఎలా ప్రారంభించాలో వివరించే లైవ్ సెషన్‌ను వీక్షించండి: Getting Started with LangChain4j - Live Session -## మీరు ఏం నేర్చుకుంటారు +## మీరు నేర్చుకునేది ఏమిటి -క్విక్ స్టార్ట్ లో, మీరు GitHub Models ఉపయోగించి ప్రాంప్ట్స్ పంపడం, టూల్స్ ను పిలవడం, RAG పైపు లైన్ నిర్మించడం, మరియు గార్డ్‌రైల్స్ ను పరీక్షించడం జరిగింది. ఆ డెమోలు సాధ్యమయ్యే దేన్ని చూపించాయి — ఇప్పుడు మనం Azure OpenAI మరియు GPT-5.2 కి మారి ప్రొడక్షన్ తరహా ఆప్లికేషన్లు తయారు చేయడం ప్రారంభిద్దాం. ఈ మోడ్యూల్ సంభాషణాత్మక AI పై దృష్టి సారిస్తుంది, ఇది సందర్భాన్ని గుర్తుంచుకుని స్థితిని నిర్వహిస్తుంది — అవి ఆ క్విక్ స్టార్ట్ డెమోలు వెనుక ఉపయోగించిన కాన్సెప్టులు కానీ వివరించలేదు. +ఇది LangChain4j మరియు Azure OpenAI తో మీ ప్రారంభ ప్రదేశం. మనం ప్రాథమికాలు మొదలుపెట్టి ప్రొడక్షన్ మాదిరి యాప్లికేషన్లు నిర్మించడం ప్రారంభిస్తాము. ఈ మాడ్యూల్ చరిత్రను గుర్తుంచుకుంటూ సందర్భాన్ని నిలిపి ఉంచే సంభాషణాత్మక AI పై కేంద్రీకృతమౌందిఅంటే, ప్రతి తర్వాతి మాడ్యూల్ పై ఈ ముఖ్యమైన భావనలు ఆధారపడి ఉంటాయి. -ఈ గైడ్ లో మొత్తం Azure OpenAI యొక్క GPT-5.2 ని ఉపయోగిస్తాము ఎందుకంటే దీని ఆవిష్కృతమైన తర్క సామర్థ్యాలు వేర్వేరు నమూనాల ప్రవర్తన స్పష్టంగా తెలియజేస్తాయి. మీరు మెమరీ కలుపుకున్నప్పుడు, తేడా స్పష్టంగా కనిపిస్తుంది. ఇది ప్రతి భాగం మీ ఆప్లికేషన్ కు ఏం తెస్తుందో అర్థం చేసుకోవడం సులభంగా చేస్తుంది. +మేము ఈ గైడ్‌లో Azure OpenAI యొక్క GPT-5.2 ని ఉపయోగిస్తాము ఎందుకంటే దాని అభివృద్ధి చెందిన తర్కశక్తి వలన వివిధ నమూనాల ప్రవర్తన బాగా స్పష్టంగా ఉంటుంది. మీరు మెమరీ చేర్చినప్పుడు, తేడా స్పష్టంగా కనిపిస్తుంది. దీని వలన ప్రతి భాగం మీ యాప్లికేషన్‌కు ఏమి తెస్తుందో అర్థం చేసుకోవడం సులభమవుతుంది. -మీరు ఇద్దరు నమూనాలను చూపించే ఒక ఆప్లికేషన్ నిర్మించబోతున్నారు: +మీరు నిర్మించబోయేది ఒకే యాప్లికేషన్, ఇది రెండు నమూనాలను చూపిస్తుంది: -**Stateless చాట్** - ప్రతి అభ్యర్థన స్వతంత్రం. మోడల్ గత సందేశాలను గుర్తుంచుకోదు. ఇది మీరు క్విక్ స్టార్ట్ లో ఉపయోగించిన నమూనా. +**స్టేట్‌లెస్ చాట్** - ప్రతి అభ్యర్థన స్వతంత్రంగా ఉంటుంది. మోడల్ గత సందేశాలను గుర్తించదు. ఇది సులభమైన ప్రారంభ పాయింట్. -**Stateful సంభాషణ** - ప్రతి అభ్యర్థనలో సంభాషణ చరిత్ర ఉంటుంది. మోడల్ అనేక మార్లు జరిగిన సంభాషణలో సందర్భాన్ని నిర్వహిస్తుంది. ఇది ప్రొడక్షన్ ఆప్లికేషన్లు అవసరం చేసేదే. +**స్టేట్‌ఫుల్ సంభాషణ** - ప్రతి అభ్యర్థనలో సంభాషణ చరిత్రను కలుపుతుంది. మోడల్ పలు రౌండ్లలో సందర్భం నిలుపుకుంటుంది. ప్రొడక్షన్ అప్లికేషన్లకు ఇది అవసరం. -## ఆవశ్యకతలు +## అవసరమైన పరిజ్ఞానం -- Azure OpenAI యాక్సెస్ ఉన్న Azure సబ్స్క్రిప్షన్ -- Java 21, Maven 3.9+ +- Azure సబ్‌స్క్రిప్షన్, Azure OpenAI యాక్సెస్ తో +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **గమనిక:** Java, Maven, Azure CLI మరియు Azure Developer CLI (azd) ప్రస్తుత devcontainer లో ముందుగానే ఇన్‌స్టాల్ చేయబడ్డాయి. +> **గమనిక:** Java, Maven, Azure CLI మరియు Azure Developer CLI (azd) ప్రాధాన్యం గల devcontainer లో ముందే ఇన్స్టాల్ చేయబడ్డాయి. -> **గమనిక:** ఈ మోడ్యూల్ Azure OpenAI కోసం GPT-5.2 ని ఉపయోగిస్తుంది. డిప్లాయ్ మెంట్ `azd up` ద్వారా ఆటోమేటిక్ గా కాన్ఫిగర్ చేయబడుతుంది — కోడ్ లో మోడల్ పేరును మార్చవద్దు. +> **గమనిక:** ఈ మాడ్యూల్ Azure OpenAI పై GPT-5.2 ను ఉపయోగిస్తుంది. `azd up` ద్వారా డిప్లాయ్‌మెంట్ ఆటోమేటిగానే సജ్జమవుతుంది - కోడ్‌లో మోడల్ పేరును మార్చొద్దు. -## కోర్ సమస్య అవగాహన చేసుకోవడం +## ప్రధాన సమస్యను అర్థం చేసుకోవడం -భాషా మోడళ్లు Stateless అవుతాయి. ప్రతి API కాల్ స్వతంత్రంగా ఉంటుంది. మీరు "నా పేరు జాన్" అంటే, ఆపై "నా పేరు ఏమిటి?" అడిగితే, మోడల్ మీ పేరు ఇప్పుడే చెప్పినట్లు గుర్తించదు. ఇది ప్రతి అభ్యర్థనను మొట్టమొదటి సంభాషణగా చూస్తుంది. +భాషా నమూనాలు స్టేట్‌లెస్ ఉంటాయి. ప్రతి API కాల్ స్వతంత్రంగా ఉంటుంది. మీరు "నా పేరు జాన్" అని పంపించాక "నా పేరు ఏమిటి?" అని అడిగితే, మోడల్ మీరు పేరు చెప్పానని తెలియదు. ఇది ప్రతి అభ్యర్థనను మీరు చేపట్టిన మొదటి సంభాషణగా పరిగణిస్తుంది. -ఇది సాధారణ ప్రశ్నల కోసం సరైనది కానీ నిజమైన ఆప్లికేషన్లకు ఉపయోగం లేదు. కస్టమర్ సర్వీస్ బోట్లు మీరు చెప్పినది గుర్తుంచుకోవాలి. వ్యక్తిగత సహాయకారి సందర్భాన్ని అవసరం పడతారు. ఏదైనా బహుమార్మిక సంభాషణకు మెమరీ అవసరం. +సాధారణ ప్రశ్నోత్తరాలకు ఇది సరైనది అయినా వాస్తవ యాప్లికేషన్లలో ఇది ఉపయోగకరము కాదు. కస్టమర్ సర్వీస్ బాట్లు మీకన్నా మీరు చెప్పిన దానిని గుర్తుంచుకోవాలి. వ్యక్తిగత సహాయకులు సందర్భాన్ని అందుకోవాలి. ఏదైనా పలు రౌండ్ల సంభాషణ మేమరీ అవసరం. -కింది చిత్రంలో రెండు పద్ధతులను పోల్చారు — ఎడమ వైపున, మీ పేరును మర్చిపోయే Stateless కాల్; కుడి వైపున, ChatMemory తో మద్దతు పొందిన Stateful కాల్ అది గుర్తుంచుకుంటుంది. +కింద ఉన్న చిత్రంలో రెండు విధానాల తేడా చూపబడింది — ఎడమ వైపున, మీ పేరు మరచిపోయే స్టేట్‌లెస్ కాల్; కుడి వైపున, ChatMemory ఆధారిత స్టేట్‌ఫుల్ కాల్, ఇది మీ పేరును గుర్తుంచుతుంది. Stateless vs Stateful Conversations -*Stateless (స్వతంత్ర కాల్స్) మరియు Stateful (సందర్భం గుర్తుంచుకున్న) సంభాషణల మధ్య తేడా* +*స్టేట్‌లెస్ (స్వతంత్ర కాల్స్) మరియు స్టేట్‌ఫుల్ (సందర్భాన్ని అర్థం చేసుకునే) సంభాషణల మధ్య తేడా* ## టోకెన్లను అర్థం చేసుకోవడం -సంభాషణల్లో ముంచెయ్యక ముందు, టోకెన్లను అర్థం చేసుకోవటం ముఖ్యం - భాషా మోడళ్లు ప్రాసెస్ చేసే మూలభూత పాఠ యూనిట్లు: +సంభాషణల్లోకి ప్రవేశించే ముందే టోకెన్లను అర్థం చేసుకోవడం ముఖ్యం - భాషా నమూనాలు ప్రాసెస్ చేసే పాఠ్య యూనిట్లు: Token Explanation -*పాఠ్యాన్ని టోకెన్లలో ఎలా విడగొడతాడని ఉదాహరణ - "I love AI!" నాలుగు ప్రాసెసింగ్ యూనిట్లుగా మారుతుంది* +*పాఠ్యం ఎలా టోకెన్లుగా విభజించబడుతుంది ఉదాహరణ — "I love AI!" 4 వేర్వేరు ప్రాసెసింగ్ యూనిట్లు అవుతుంది* -టోకెన్లు AI మోడళ్లు పాఠ్యాన్ని కొలుస్తాయి మరియు ప్రాసెస్ చేస్తాయి. పదాలు, పంక్చువేషన్ మరియు ఖాళీలు కూడా టోకెన్లు కావచ్చు. మీ మోడల్ ఒకేసారి ఎంత టోకెన్లు ప్రాసెస్ చేయగలదో (GPT-5.2 కి 400,000 టోకెన్లు, అందులో 272,000 ఇన్పుట్ టోకెన్లు, 128,000 అవుట్‌పుట్ టోకెన్లు) పరిమితి ఉంది. టోకెన్లు అర్థం చేసుకోవడం సంభాషణ పొడవు మరియు ఖర్చులను నియంత్రించడానికి సహాయపడుతుంది. +టోకెన్లు AI నమూనాలు పాఠ్యాన్ని కొలిచే మరియు ప్రాసెస్ చేసే విధానం. పదాలు, विरామਚిహ్నాలు, ఎడమవెలుపలు కూడా టోకెన్లు కావచ్చు. మీ మోడల్ ఒకేసారి ఎంత టోకెన్లు ప్రాసెస్ చేయగలదో పరిమితి ఉంది (GPT-5.2కి 400,000 టోకెన్లు, అందులో 272,000 ఇన్‌పుట్ టోకెన్లు మరియు 128,000 అవుట్‌పుట్ టోకెన్లు). టోకెన్ల అర్థం పొందడం సంభాషణ పరిమాణం మరియు ఖర్చులను నియంత్రించడంలో సహాయకరం. -## మెమరీ ఎలా పనిచేస్తుంది +## మెమరీ ఎలా పని చేస్తుంది -చాట్ మెమరీ Stateless సమస్యను పరిష్కరిస్తుంది సంభాషణ చరిత్రను నిర్వహించడం ద్వారా. మీ అభ్యర్థనను మోడల్ కి పంపే ముందు, ఫ్రేమ్‌వర్క్ సంబంధిత పూర్వ సందేశాలను ముందువైపు జత చేస్తుంది. మీరు "నా పేరు ఏమిటి?" అడగగానే, సిస్టమ్ మొత్తం సంభాషణ చరిత్ర పంపుతుంది, అందువలన మోడల్ మీరు "నా పేరు జాన్" అని ముందుగా చెప్పినట్లు చూస్తుంది. +చాట్ మెమరీ స్టేట్‌లెస్ సమస్యను సంభాషణ చరిత్రను నిలిపి ఉంచడం ద్వారా పరిష్కరిస్తుంది. మీ అభ్యర్థనను మోడల్‌కు పంపించే ముందు, సంబంధిత గత సందేశాలను ఫ్రేమ్‌వర్క్ జత చేస్తుంది. మీరు "నా పేరు ఏమిటి?" అని అడిగితే, సిస్టమ్ మొత్తం సంభాషణ చరిత్రను పంపించి, మోడల్ మీరు "నా పేరు జాన్" అని ముందుగా చెప్పారు అని తెలుసుకుంటుంది. -LangChain4j మెమరీ అమలు లను ఆటోమేటిక్ గా నిర్వహిస్తుంది. మీరు ఎన్ని సందేశాలు నిల్వ చేయాలో ఎంచుకోండి, ఫ్రేమ్‌వర్క్ సందర్భం విండో ని నిర్వహిస్తుంది. కింది చిత్రం MessageWindowChatMemory ఇటీవల సందేశాల ఒక స్లయిడింగ్ విండో ని ఎలా నిర్వహిస్తుందో చూపిస్తుంది. +LangChain4j ఆటోమేటిగానే హ్యాండిల్ చేసే మెమరీ ఇంప్లిమెంటేషన్‌లను అందిస్తుంది. మీరు ఎన్ని సందేశాలు నిలుపుకోవాలో ఎంచుకోవచ్చు, ఫ్రేమ్‌వర్క్ సందర్భం విండోను నిర్వహిస్తుంది. క్రింద దృశ్యం MessageWindowChatMemory ఇటీవల సందేశాల స్లయిడింగ్ విండోని ఎలా నిర్వహిస్తుందో చూపిస్తుంది. Memory Window Concept -*MessageWindowChatMemory ఇటీవల సందేశాల ఒక స్లయిడింగ్ విండో ని నిర్వహిస్తుంది, పాతవి ఆటోమేటిక్ గా తొలగిస్తూ* +*MessageWindowChatMemory ఇటీవల సందేశాల స్లయిడింగ్ విండోని నిర్వహించి పాత సందేశాలను ఆటోమేటిగానే తొలగిస్తోంది* ## ఇది LangChain4j ను ఎలా ఉపయోగిస్తుంది -ఈ మోడ్యూల్ క్విక్ స్టార్ట్ ని విస్తరించి Spring Boot ఐక్యీకరణతో కలిసి సంభాషణ మెమరీ ని జోడిస్తుంది. భాగాలు ఎలా కలిసిపోతున్నాయో: +ఈ మాడ్యూల్ Spring Boot ను ఇంటిగ్రేట్ చేసి సంభాషణ మెమరీ జోడించింది. భాగాలు ఇలా సరిపోయాయి: -**డిపెండెన్సీలు** - రెండు LangChain4j లైబ్రరీలు జోడించండి: +**డిపెండెన్సీలు** - రెండు LangChain4j లైబ్రరీలను జోడించండి: ```xml @@ -94,7 +94,7 @@ LangChain4j మెమరీ అమలు లను ఆటోమేటిక్ ``` -**చాట్ మోడల్** - Azure OpenAI ని Spring బీన్ ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)) గా కాన్ఫిగర్ చేయండి: +**చాట్ మోడల్** - Azure OpenAIని Spring beanగా కాన్ఫిగర్ చేయండి ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -బిల్డర్ `azd up` ద్వారా సెట్ చేసిన ఎన్విరాన్మెంట్ వేరియబుల్స్ నుండి క్రెడెన్షియల్స్ చదవుతుంది. `baseUrl` ను మీ Azure ఎండ్పాయింట్ గా సెట్ చేస్తే OpenAI క్లయింట్ Azure OpenAI తో పనిచేస్తుంది. +బిల్డర్ `azd up` ద్వారా సెట్ చేసిన ఎన్‌విరాన్‌మెంట్ వేరియబుల్స్ నుండి క్రెడెన్షియల్స్ చదువుకుంటుంది. `baseUrl` ను మీ Azure ఎండ్పాయింట్‌గా సెట్ చేయడం OpenAI క్లయింట్ Azure OpenAIతో పని చేసేందుకు కారణం. **సంభాషణ మెమరీ** - MessageWindowChatMemory తో చాట్ చరిత్ర ట్రాక్ చేయండి ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,39 +124,39 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` తో చివరి 10 సందేశాలు నిల్వ చేయండి. typed wrappers తో యూజర్ మరియు AI సందేశాలు జోడించండి: `UserMessage.from(text)`, `AiMessage.from(text)`. చరిత్రను `memory.messages()` తో పొందండి, మోడల్ కు పంపండి. సర్వీస్ ప్రతి సంభాషణ ID కి ప్రత్యేక మెమరీ ఇన్ స్టాన్స్ ట్రాక్ చేస్తుంది, అంటే ఎన్నో యూజర్లకు ఒకేసారి చాట్ చేయడం సాధ్యం. +`withMaxMessages(10)` తో మెమరీ తయారుచేయండి, దీని వలన గడిచిన 10 సందేశాలు నిల్వ ఉంటాయి. Typed wrappers ఉపయోగించి యూజర్ మరియు AI సందేశాలను జోడించండి: `UserMessage.from(text)` మరియు `AiMessage.from(text)`. చరిత్రను `memory.messages()` తో తీసుకుని మోడల్‌కు పంపండి. సర్వీస్ ప్రతి సంభాషణ ID కు ప్రత్యేక మెమరీ ఉదాహరణలను నిలిపి, అనేక యూజర్లు ఒకేసారి చాట్ చేయగలరు. -> **🤖 GitHub Copilot చాట్ తో ప్రయత్నించండి:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) ను ఓపెన్ చేసి అడగండి: -> - "MessageWindowChatMemory విండో పూర్తయ్యినపుడు ఏ సందేశాలు తొలగించాలో ఎలా నిర్ణయిస్తుంది?" -> - "నేను మేమరీ నిల్వ కోసం ఇన్ మెమరీ కాకుండా డేటాబేస్ ఉపయోగించి కస్టమ్ మెమరీ అమలు చేయగలనా?" -> - "పాత సంభాషణ చరిత్రను సంక్షిప్తం చేయడానికి సారాంశాన్ని ఎలా జోడిస్తాను?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్ తో ప్రయత్నించండి:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) తెరిచి అడగండి: +> - "MessageWindowChatMemory విండో నిండినప్పుడు ఏ సందేశాలను తొలగించాలో ఎలా నిర్ణయిస్తుంది?" +> - "ఇన్-మెమరీ కాకుండా డేటాబేస్ ఉపయోగించి కస్టమ్ మెమరీ స్టోరేజ్ ఎలా అమలు చేయగలను?" +> - "పాత సంభాషణ చరిత్రా సంక్షిప్తీకరణకు సమ్మరీ జోడించడం ఎలా చేయాలి?" -Stateless చాట్ ఎండ్‌పాయింట్ మెమరీని పూర్తిగా వదిలేస్తుంది - కేవలం `chatModel.chat(prompt)` సినిమా క్విక్ స్టార్ట్ లాంటి. Stateful ఎండ్‌పాయింట్ మెసేజ్లు మెమరీకి జోడిస్తుంది, చరిత్ర పొందుతుంది, ప్రతి అభ్యర్థనతో ఆ సందర్భాన్ని కలుపుతుంది. అదే మోడల్ కాన్ఫిగరేషన్, వేర్వేరు నమూనాలు. +స్టేట్‌లెస్ చాట్ ఎండ్‌పాయింట్ మెమరీని పూర్తిగా వదిలిపెడుతుంది - కేవలం `chatModel.chat(prompt)` మాత్రమే, వేగవంతమైన ప్రారంభం కోసం. స్టేట్‌ఫుల్ ఎండ్‌పాయింట్ మెమరీలో సందేశాలు జతచేసి చరిత్రను తీసుకుని, ఆ సందర్భాన్ని ప్రతీ అభ్యర్థనలో చేర్చుతుంది. అదే మోడల్ కాన్ఫిగరేషన్, భిన్న నమూనాలు. -## Azure OpenAI ఇంఫ్రాస్ట్రక్చర్‌ను డిప్లాయ్ చేయండి +## Azure OpenAI ఇన్‌ఫ్రాస్ట్రక్చర్‌ను మిళితం చేయడం **Bash:** ```bash cd 01-introduction -azd up # సభ్యత్వాన్ని మరియు లొకేషన్ ను ఎంచుకోండి (eastus2 సిఫార్సు చేయబడింది) +azd up # సబ్‌స్క్రిప్షన్ మరియు స్థలాన్ని ఎంచుకోండి (ఇస్టయుఎస్2 సూచించబడింది) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # సభ్యత్వం మరియు స్థలాన్ని (eastus2 సిఫార్సు చేసినది) ఎంచుకోండి +azd up # సబ్స్క్రిప్షన్ మరియు స్థానం ఎంచుకోండి (ఈస్ట్ us2 సిఫార్సు చేస్తారు) ``` -> **గమనిక:** ఒక టైమౌట్ లోపం (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) వస్తే, `azd up` ని మళ్లీ నడపండి. Azure వనరులు ఇంకా ప్రొవిజనింగ్ లో ఉండొచ్చు, మళ్లీ ప్రయత్నించడం వనరులు తుది స్థితికి చేరుకున్నప్పుడు డిప్లాయ్ మెంట్ పూర్తి అవుతుంది. +> **గమనిక:** టైమౌట్ లోపం వస్తే (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), కేవలం మళ్ళీ `azd up` నడపండి. Azure వనరులు ఇంకా బ్యాక్‌గ్రౌండ్ లో సెట్ అవుతున్నా ఉండచ్చు, మళ్ళీ ప్రయత్నించడం వలన వనరులు పూర్తిగా సిద్ధమైన తర్వాత డిప్లాయ్‌మెంట్ పూర్తవుతుంది. -ఇది: -1. GPT-5.2 మరియు text-embedding-3-small మోడళ్లు ఉన్న Azure OpenAI వనరును డిప్లాయ్ చేస్తుంది -2. ప్రాజెక్ట్ రూట్ లో క్రెడెన్షియల్స్ తో `.env` ఫైల్ ఆటోమేటిక్ గా జనరేట్ చేస్తుంది -3. అన్ని అవసరమైన ఎన్విరాన్మెంట్ వేరియబుల్స్ సెట్ చేస్తుంది +ఇదివల్ల: +1. GPT-5.2 మరియు text-embedding-3-small మోడల్స్‌తో Azure OpenAI వనరు మిళితం అవుతుంది +2. ప్రాజెక్ట్ రూట్‌లో క్రెడెన్షియల్స్ ఉన్న `.env` ఫైల్ ఆటోమేటిగానే సృష్టించబడుతుంది +3. అవసరమైన అన్ని ఎన్విరాన్‌మెంట్ వేరియబుల్స్ సెట్ చేయబడతాయి -**డిప్లాయ్ మెంట్ సమస్యలు వస్తున్నాయా?** [Infrastructure README](infra/README.md) చూడండి, ఇందులో సబ్డొమైన్ పేర్ల గందరగోళాలు, Azure Portal లో మాన్యువల్ డిప్లాయ్ మెంట్ దశలు, మరియు మోడల్ కాన్ఫిగరేషన్ సూచనలు ఉన్నాయి. +**డిప్లాయ్‌మెంట్ సమస్యలు ఉన్నారా?** సబ్‌డొమైన్ పేరు ఘర్షణలు, Azure పోర్టల్ మాన్యువల్ డిప్లాయ్‌మెంట్ దశలు, మోడల్ కాన్ఫిగరేషన్ మార్గదర్శకత్వం కోసం [Infrastructure README](infra/README.md) చూడండి. -**డిప్లాయ్ మెంట్ విజయవంతం అయ్యిందా అని ధృవీకరించండి:** +**డిప్లాయ్‌మెంట్ విజయవంతమైందని ధృవీకరించండి:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, మొదలైనవి చూ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, మొదలైనవి చూపించాలి. ``` -> **గమనిక:** `azd up` ఆదేశం ఆటోమేటిక్ గా `.env` ఫైల్ సృష్టిస్తుంది. మీరు తర్వాత దీన్ని అప్‌డేట్ చేయాల్సి వస్తే, `.env` ఫైల్ ని మాన్యువల్ గా ఎడిట్ చేయవచ్చు లేదా క్రింది కమాండ్ లు తో రీజనరేట్ చేయవచ్చు: +> **గమనిక:** `azd up` ఆదేశం ఆటోమేటిగానే `.env` ఫైల్ సృష్టిస్తుంది. తరువాత దీనిని నవీకరించాలి అంటే మీరు `.env` ఫైల్‌ను మాన్యువల్‌గా ఎడిట్ చేయొచ్చు లేదా దీన్ని తిరిగి సృష్టించేందుకు: > > **Bash:** > ```bash @@ -183,15 +183,15 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, మొదలైనవి > ``` -## ఆప్లికేషన్ ను లోకల్ గా రన్ చేయండి +## యాప్‌ను స్థానికంగా నడపడం -**డిప్లాయ్ మెంట్ ధృవీకరించండి:** +**డిప్లాయ్‌మెంట్ ధృవీకరణ:** -Azure క్రెడెన్షియల్స్ ఉన్న `.env` ఫైల్ ప్రాజెక్ట్ రూట్ లో ఉందని నిర్ధారించండి. మోడ్యూల్ డైరెక్టరీ (`01-introduction/`) నుంచి ఇది నడపండి: +Azure క్రెడెన్షియల్స్ ఉన్న `.env` ఫైల్ రూట్ డైరెక్టరీలో ఉన్నదని ధృవీకరించండి. ఈ మాడ్యూల్ ఫోల్డర్ (`01-introduction/`) నుంచి ఇది నడపండి: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ను చూపించాలి +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT చూపించాలి ``` **PowerShell:** @@ -199,31 +199,31 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ను చూపిం Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT చూపించాలి ``` -**ఆప్లికేషన్లు ప్రారంభించండి:** +**యాప్లికేషన్లను ప్రారంభించండి:** -**ఎంపిక 1: Spring Boot డాష్‌బోర్డ్ ఉపయోగించడం (VS Code వినియోగదారులకు సిఫార్సు)** +**ఎంపిక 1: Spring Boot డాష్‌బోర్డ్ ఉపయోగించి (VS Code వినియోగదారులకు సిఫార్సు)** -Dev container లో Spring Boot డాష్‌బోర్డ్ ఎక్స్‌టెన్షన్ ఉంది, ఇది అన్నీ Spring Boot ఆప్లికేషన్లను విజువల్ ఇంటర్ఫేస్ లో నిర్వహించడానికి సహాయం చేస్తుంది. ఇది VS Code లో ఎడమ వైపు Activity Bar లో(Spring Boot చిహ్నం చూడండి) కనపడుతుంది. +Devcontainer లో Spring Boot డాష్‌బోర్డ్ ఎక్స్‌టెన్షన్ ఉంది, ఇది మీకు అన్ని Spring Boot యాప్లికేషన్లను విజువల్ ఇంటర్‌ఫేస్ ద్వారా నిర్వహించేందుకు వీలు కల్పిస్తుంది. మీరు దీన్ని VS Code ఎడమ వైపు Activity Barలో (Spring Boot చిహ్నం కోసం చూడండి) కనుగొనవచ్చు. Spring Boot డాష్‌బోర్డ్ నుండి మీరు: -- వర్క్‌స్పేస్ లో అందుబాటులో ఉన్న అన్నీ Spring Boot ఆప్లికేషన్లను చూడొచ్చు -- ఒక్క క్లిక్ తో ఆప్లికేషన్లు స్టార్ట్/స్టాప్ చేయొచ్చు -- రియల్ టైంలో లాగ్స్ చూడొచ్చు -- ఆప్లికేషన్ స్థితిని పర్యవేక్షించొచ్చు +- వర్క్‌స్పేస్‌లో ఉన్న అన్ని Spring Boot యాప్లికేషన్లు చూడవచ్చు +- ఒక క్లిక్‌తో యాప్లికేషన్లు ఆన్/ఆఫ్ చేయవచ్చు +- యాప్లికేషన్ లాగ్స్ రియల్-టైమ్‌లో చూడవచ్చు +- యాప్లికేషన్ స్థితిని పర్యవేక్షించవచ్చు -"introduction" పక్కన ఉన్న ప్లే బటన్ క్లిక్ చేసి ఈ మోడ్యూల్ మొదలుపెట్టండి, లేదా ఒక్కసారి అన్ని మోడ్యూల్స్ ప్రారంభించండి. +"introduction" పక్కన ఉన్న ప్లే బటన్ నొక్కి ఈ మాడ్యూల్ ప్రారంభించండి లేదా అన్ని మాడ్యూల్స్‌ను ఒకేసారి ప్రారంభించండి. Spring Boot Dashboard -*VS Code లో Spring Boot డాష్‌బోర్డు — ఒక చోట అన్ని మోడ్యూల్స్ ను ప్రారంభించండి, ఆపండి, మరియు పర్యవేక్షించండి* +*VS Code లో Spring Boot డాష్‌బోర్డ్ — ఒకే చోట అన్ని మాడ్యూల్స్‌ను మొదలు పెట్టండి, ఆపు చేయండి మరియు పర్యవేక్షించండి* -**ఎంపిక 2: shell స్క్రిప్టులు ఉపయోగించడం** +**ఎంపిక 2: షెల్ స్క్రిప్ట్‌లను ఉపయోగించి** -అన్నీ వెబ్ ఆప్లికేషన్లు (మోడ్యూల్స్ 01-04) మొదలుపెట్టండి: +అన్ని వెబ్ యాప్లికేషన్లు (మాడ్యూల్స్ 01-04) ప్రారంభించండి: **Bash:** ```bash -cd .. # రూట్ డైరెక్టరీ నుండి +cd .. # మూల డైరెక్టరీ నుండి ./start-all.sh ``` @@ -233,7 +233,7 @@ cd .. # రూట్ డైరెక్టరీ నుండి .\start-all.ps1 ``` -లేదా కేవలం ఈ మోడ్యూల్ మాత్రమే మొదలుపెట్టండి: +లేదా కేవలం ఈ మాడ్యూల్‌ను ప్రారంభించండి: **Bash:** ```bash @@ -247,9 +247,9 @@ cd 01-introduction .\start.ps1 ``` -ఇవి రెండూ ఆటోమేటిక్ గా ప్రాజెక్ట్ రూట్ లో ఉన్న `.env` నుండి వాతావరణ వేరియబుల్స్ లోడ్ చేస్తాయి మరియు JAR లు లేకపోతే బిల్డ్ చేస్తాయి. +రూట్ `.env` ఫైల్ నుండి ఎన్విరాన్‌మెంట్ వేరియబుల్స్‌ను స్క్రిప్ట్‌లు ఆటోమేటిగానే లోడ్ చేస్తాయి మరియు JARలు లేవంటే అవి నిర్మిస్తాయి. -> **గమనిక:** ప్రారంభించే ముందు మీరు అన్ని మోడ్యూల్స్ మాన్యువల్ గా బిల్డ్ చేయాలనుకుంటే: +> **గమనిక:** మీరు ప్రారంభించే ముందు అన్ని మాడ్యూల్స్ మాన్యువల్‌గా నిర్మించాలనుకుంటే: > > **Bash:** > ```bash @@ -263,9 +263,10 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -http://localhost:8080 ను మీ బ్రౌజర్ లో ఓపెన్ చేయండి. -**నిరుద్యోగం చేయడానికి:** +http://localhost:8080 ని మీ బ్రౌజర్‌లో తెరవండి. + +**ఆపడానికి:** **Bash:** ```bash @@ -278,47 +279,47 @@ cd .. && ./stop-all.sh # అన్ని మాడ్యూల్స్ ```powershell .\stop.ps1 # ఈ మాడ్యూల్ మాత్రమే # లేదా -cd ..; .\stop-all.ps1 # అన్ని మాడ్యూల్స్ +cd ..; .\stop-all.ps1 # అన్ని మాడ్యూల్లు ``` -## ఆప్లికేషన్ ఉపయోగించడం +## యాప్ ఉపయోగించడం -ఈ ఆప్లికేషన్ వెబ్ ఇంటర్ఫేస్ తో రెండు చాట్ అమలు లను పక్కపక్కన అందిస్తుంది. +యాప్ రెండు చాట్ అమలు విధానాలతో వెబ్ ఇంటర్‌ఫేస్ను అందిస్తుంది. Application Home Screen -*ఇద్దరూ Simple Chat (stateless) మరియు Conversational Chat (stateful) ఎంపికలను చూపిస్తున్న డాష్‌బోర్డు* +*డాష్‌బోర్డ్ రెండు ఎంపికలను చూపిస్తోంది - సింపుల్ చాట్ (స్టేట్‌లెస్) మరియు సంభాషణాత్మక చాట్ (స్టేట్‌ఫుల్)* -### Stateless చాట్ (ఎడమ ప్యానెల్) +### స్టేట్‌లెస్ చాట్ (ఎడమ ప్యానెల్) -ముందుగా దీన్ని ప్రయత్నించండి. "నా పేరు జాన్" అని అడిగి, వెంటనే "నా పేరు ఏమిటి?" అని అడగండి. మోడల్ గుర్తుంచుకోదు ఎందుకంటే ప్రతి సందేశం స్వతంత్రం. ఇది ప్రాథమిక భాషా మోడల్ ఇంటిగ్రేషన్ యొక్క కోర్ సమస్యను చూపిస్తుంది - సంభాషణ సందర్భం లేదు. +ముందుగా దీన్ని ప్రయత్నించండి. "నా పేరు జాన్" అని అడిగి వెంటనే "నా పేరు ఏమిటి?" అని అడగండి. మోడల్ గుర్తుంచుకోదు ఎందుకంటే ప్రతి సందేశం స్వతంత్రం. ఇది ప్రాథమిక భాషా నమూనా ఇంటిగ్రేషన్ లో ప్రధాన సమస్యను సూచిస్తుంది - సంభాషణ సందర్భం లేమి. Stateless Chat Demo -*AI మీ పెరిగిన సందేశం నుండి పేరు గుర్తించదు* +*AI మీ పేరును గత సందేశం నుండి గుర్తించదు* -### Stateful చాట్ (కుడి ప్యానెల్) +### స్టేట్‌ఫుల్ చాట్ (కుడి ప్యానెల్) -ఇప్పుడు అదే సీక్వెన్స్ ఇక్కడ ప్రయత్నించండి. "నా పేరు జాన్" తరువాత "నా పేరు ఏమిటి?" అడగండి. ఈసారి అది గుర్తుంచుకుంటుంది. తేడా MessageWindowChatMemory లో ఉంది - ఇది సంభాషణ చరిత్రను నిర్వహించి ప్రతీ అభ్యర్థనతో పెట్టిస్తుంది. ఇది ప్రొడక్షన్ సంభాషణాత్మక AI ఎలా పనిచేస్తుందో చూపిస్తుంది. +ఇప్పుడు ఇదే శ్రేణిని ఇక్కడ ప్రయత్నించండి. "నా పేరు జాన్" అని అడిగి తర్వాత "నా పేరు ఏమిటి?" అని అడిగితే గుర్తుంచుకుంటుంది. తేడా MessageWindowChatMemory గలిది - ఇది సంభాషణ చరిత్రను నిలుపుతుంది మరియు అది ప్రతీ అభ్యర్థనతో పాటు పంపబడుతుంది. ఇదే ప్రొడక్షన్ conversational AI పని చేసే విధానం. Stateful Chat Demo -*AI ముందుగా సంభాషణలో మీ పేరును గుర్తుంచుకుంటుంది* +*AI సంభాషణలో మునుపటి మీ పేరును గుర్తుంచుకుంటుంది* -రెండు ప్యానెల్స్ ఒకే GPT-5.2 మోడల్ ని ఉపయోగిస్తాయి. ఒక్క తేడా మెమరీ. ఇది మీ ఆప్లికేషన్ కు మెమరీ ఏం తెస్తుందో, నిజమైన ఉపయోగాలకు అది ఎందుకు అత్యవసరమో స్పష్టం చేస్తుంది. +రెండు ప్యానెల్స్ ఒకే GPT-5.2 మోడల్‌ను ఉపయోగిస్తాయి. పలు మెమరీ తేడానే ఉంది. దీని వలన మెమరీ యాప్‌కు ఏం తెస్తుంది మరియు అది నిజమైన ఉపయోగాల కోసం ఎందుకు అవసరం అనేది స్పష్టమవుతుంది. -## తదుపరి దశలు +## తర్వాతి దశలు -**తదుపరి మోడ్యూల్:** [02-prompt-engineering - Prompt Engineering with GPT-5.2](../02-prompt-engineering/README.md) +**తరువాతి మాడ్యూల్:** [02-prompt-engineering - GPT-5.2 తో ప్రాంప్ట్ ఇంజనీరింగ్](../02-prompt-engineering/README.md) --- -**నావిగేషన్:** [← గతది: మోడ్యూల్ 00 - క్విక్ స్టార్ట్](../00-quick-start/README.md) | [మరల వెళ్ళండి](../README.md) | [తదుపరి: మోడ్యూల్ 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**నావిగేషన్:** [← ప్రధానానికి తిరుగు](../README.md) | [తరువాత: మాడ్యూల్ 02 - ప్రాంప్ట్ ఇంజనీరింగ్ →](../02-prompt-engineering/README.md) --- -**అస్పష్టం**: -ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడి ఉంది. మేము ఖచ్చితత్వం కోసం ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటిక్ అనువాదాలలో పొరపాట్లు లేదా అప్రమేయతలు ఉండవచ్చు అని దయచేసి గమనించండి. స్వదేశీ భాషలో ఉన్న అసలు పత్రం అధికారిక మూలంగా పరిగణించాలి. ముఖ్యమైన సమాచారానికి, నిపుణుల మానవ అనువాదాన్ని సూచించబడుతుంది. ఈ అనువాదం వలన ఉద్భవించే ఏ హోమభ్రంశాలు లేదా తప్పు వ్యాఖ్యానాలకు మేము బాధ్యత వహించము. +**అస్వీకరణ**: +ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటెడ్ అనువాదాలు తప్పులు లేదా అసమగ్రతలను కలిగి ఉండవచ్చు. దాని స్వదేశ భాషలో ఉన్న అసలు పత్రాన్ని అధికారం కలిగిన మూలంగా పరిగణించాలి. కీలకమైన సమాచారం కోసం, ప్రొఫెషనల్ మానవ అనువాదాన్ని సిఫారసు చేస్తాము. ఈ అనువాదం ఉపయోగం వల్ల కలిగే ఏవైనా అపార్థాలు లేదా తప్పుదారులు కోసం మేము బాధ్యత వహించము. \ No newline at end of file diff --git a/translations/te/02-prompt-engineering/README.md b/translations/te/02-prompt-engineering/README.md index 1b5b4a155..cb19fa06b 100644 --- a/translations/te/02-prompt-engineering/README.md +++ b/translations/te/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# మాడ్యూల్ 02: GPT-5.2తో ప్రాంప్ట్ ఇంజనీరింగ్ - -## కంటెంట్ పట్టిక - -- [వీడియో వాక్ట్రూ](../../../02-prompt-engineering) -- [మీకు నేర్చుకునేది ఏమిటి](../../../02-prompt-engineering) -- [ముందస్తు అవసరాలు](../../../02-prompt-engineering) -- [ప్రాంప్ట్ ఇంజనీరింగ్ అర్థం చేసుకోవడం](../../../02-prompt-engineering) -- [ప్రాంప్ట్ ఇంజనీరింగ్ నూతన అంశాలు](../../../02-prompt-engineering) - - [జీరో-షాట్ ప్రాంప్టింగ్](../../../02-prompt-engineering) - - [ఫ్యూ-షాట్ ప్రాంప్టింగ్](../../../02-prompt-engineering) - - [చైన్ ఆఫ్ థought](../../../02-prompt-engineering) - - [పాత్ర ఆధారంగా ప్రాంప్టింగ్](../../../02-prompt-engineering) - - [ప్రాంప్ట్ టెంప్లేట్స్](../../../02-prompt-engineering) -- [అగ్రగామి నమూనాలు](../../../02-prompt-engineering) -- [అప్లికేషన్‌ను నడపండి](../../../02-prompt-engineering) -- [అప్లికేషన్ స్క్రీన్‌షాట్లు](../../../02-prompt-engineering) -- [నమూనాలను అన్వేషించడం](../../../02-prompt-engineering) - - [తక్కువ vs అధిక ఉత్సాహం](../../../02-prompt-engineering) - - [టాస్క్ ఎగ్జిక్యూట్ (టూల్ ప్రీస్టాంబుల్స్)](../../../02-prompt-engineering) - - [స్వీయ-పరిశీలన కోడ్](../../../02-prompt-engineering) - - [సంఖ్యాబద్ధమైన విశ్లేషణ](../../../02-prompt-engineering) - - [బహుళ-తలుపు సంభాషణ](../../../02-prompt-engineering) - - [అడుగు-అడుగుగా కారణం చూపడం](../../../02-prompt-engineering) - - [పరిమిత అవుట్పుట్](../../../02-prompt-engineering) -- [మీరు నిజంగా ఏం నేర్చుకుంటున్నారు](../../../02-prompt-engineering) -- [తరలి దశలు](../../../02-prompt-engineering) - -## వీడియో వాక్ట్రూ - -ఈ లైవ్ సెషన్‌ను చూడండి, ఇది ఈ మాడ్యూల్‌తో ఎలా ప్రారంభించాలో వివరించబడింది: +# Module 02: GPT-5.2తో ప్రాంప్ట్ ఇంజనీరింగ్ + +## Table of Contents + +- [వీడియో వాక్తర్లూ](#video-walkthrough) +- [మీరు నేర్చుకునే అంశాలు](#what-youll-learn) +- [ముందస్తు పరిజ్ఞానం](#prerequisites) +- [ప్రాంప్ట్ ఇంజనీరింగ్ అర్థం చేసుకోవడం](#understanding-prompt-engineering) +- [ప్రాంప్ట్ ఇంజనీరింగ్ మూలాలు](#prompt-engineering-fundamentals) + - [జీరో-షాట్ ప్రాంప్టింగ్](#zero-shot-prompting) + - [ఫ్యూ-షాట్ ప్రాంప్టింగ్](#few-shot-prompting) + - [చైన్ ఆఫ్ థాట్](#chain-of-thought) + - [రోల్-బేస్డ్ ప్రాంప్టింగ్](#role-based-prompting) + - [ప్రాంప్ట్ టేమ్ప్లేట్లు](#prompt-templates) +- [అభివృద్ధి చెందిన నమూనాలు](#advanced-patterns) +- [యాప్లికేషన్ నడిపించండి](#అప్లికేషన్‌ను-అమలు-చేయండి) +- [యాప్లికేషన్ స్క్రీన్‌షాట్లు](#అప్లికేషన్-స్క్రీన్‌షాట్లు) +- [నమూనాలు అన్వేషణ](#నమూనాలను-అన్వేషించడం) + - [తక్కువ vs ఎక్కువ ఉత్సాహం](#తక్కువ-మరియు-ఎక్కువ-ఈగర్నెస్) + - [టాస్క్ ఎక్జిక్యూషన్ (టూల్ ప్రీాంబుల్స్)](#టాస్క్-ఎగ్జిక్యూషన్-టూల్-ప్రీమేబుల్స్) + - [స్వయం-పరిశీలన కోడ్](#స్వయం-ప్రతిబింబించే-కోడ్) + - [సంఘటిత విశ్లేషణ](#నిర్మిత-విశ్లేషణ) + - [బహుళ-తురన్ చాట్](#బహుళ-తిరుగు-చాట్) + - [దశ-దశ వ్యాసంగం](#దశలు-వారీ-తార్కికత) + - [పరిమిత అవుట్పుట్](#పరిమిత-అవుట్‌పుట్) +- [మీరు నిజంగా ఏమి నేర్చుకుంటున్నారు](#మీరు-నిజంగా-ఏమి-నేర్చుకుంటున్నారు) +- [తర్వాతి దశలు](#తదుపరి-అడుగులు) + +## Video Walkthrough + +ఈ మాడ్యూల్‌ను ఎలా ప్రారంభించాలో వివరిస్తున్న ప్రత్యక్ష సెషన్‌ను చూసుకోండి: Prompt Engineering with LangChain4j - Live Session -## మీకు నేర్చుకునేది ఏమిటి +## What You'll Learn -క్రింది డయాగ్రామ్ ఈ మాడ్యూల్‌లో మీరు అభివృద్ధి చేయబోయే ప్రధాన అంశాలు మరియు నైపుణ్యాల సమగ్ర అవగాహన ఇస్తుంది — ప్రాంప్ట్ మెరుగుదల సాంకేతికతల నుండి మీరు అనుసరించే అడుగు-అడుగు పని ప్రవాహం వరకు. +ఈ క్రింది చిత్రంలో మీరు ఈ మాడ్యూల్లో అభివృద్ధి చేసుకునే ముఖ్యమైన అంశాలు మరియు నైపుణ్యాల సమీక్ష ఉంది — ప్రాంప్ట్ మెరుగుదల సాంకేతికతలతో పాటు మీరు అనుసరించే దశల వారీ వర్క్‌ఫ్లో. What You'll Learn -మునుపటి మాడ్యూల్స్‌లో మీరు GitHub మోడల్స్‌తో ప్రాథమిక LangChain4j ఇంటరాక్షన్లను అన్వేషించి, Azure OpenAI తో సంభాషణాత్మక AI కి మెమోరీ ఎలా సహాయపడుతుందో చూడగలిగారు. ఇప్పుడు మనం ఎలా ప్రశ్నలు అడగాలో — ప్రాంప్ట్లను ఉపయోగించుకోవడంపై దృష్టి సారించబోతున్నాము, Azure OpenAI యొక్క GPT-5.2 వాడుతాము. మీరు మీ ప్రాంప్ట్లను ఎలా నిర్మిస్తారో అనేది మీకు వచ్చే ప్రతిస్పందనల నాణ్యతను గణనీయంగా ప్రభావితం చేస్తుంది. మొదట ప్రాథమిక ప్రాంప్టింగ్ సాంకేతికతలను సమీక్షిస్తాం, ఆ తరువాత GPT-5.2 యొక్క సామర్థ్యాలను పూర్తిగా వినియోగించే ఎనిమిది అగడగామి నమూనాలు చూద్దాం. +మునుపటి మాడ్యూల్లో మీరు మెమరీ ఎలా Azure OpenAI తో సంభాషణ కృత్రిమ మేధస్సు కోసం ఉపయోగపడుతుందో చూశారు. ఇప్పుడు మనం ప్రశ్నలు ఎలా అడుగుతామో — ఆ ప్రాంప్ట్‌లు ఇక్కడి ముఖ్యాంశం — Azure OpenAI యొక్క GPT-5.2 ని ఉపయోగించి. మీరు మీ ప్రాంప్ట్‌లను ఎలా నిర్మిస్తారో, అందులో మీకు వచ్చే సమాధానాల నాణ్యతపై ద్రుష్టిగా ప్రభావం చూపుతుంది. మొదట మూల ప్రాంప్టింగ్ సూత్రాలు సమీక్షించి, తర్వాత GPT-5.2 సామర్థ్యాలను పూర్తిగా ఉపయోగించే ఎనిమిది అభివృద్ధి చెందిన నమూనాలతో ముందుకు పోతాము. -మనం GPT-5.2ని ఉపయోగిస్తాము ఎందుకంటే ఇది కారణChainి నియంత్రణను పరిచయం చేస్తుంది - మీరు మోడల్ ఎంతగా ఆలోచించాలో చెప్పవచ్చు. ఇది వివిధ ప్రాంప్టింగ్ వ్యూహాలను స్పష్టంగా చేస్తుంది మరియు ప్రతీ విధానాన్ని ఎప్పుడు ఉపయోగించాలో అర్థం చేసుకోవడంలో సహాయ పడుతుంది. అలాగే GPT-5.2 కోసం Azure యొక్క తక్కువ రేటు పరిమితుల ప్రయోజనాలు GitHub మోడల్స్ కంటే ఎక్కువ. +మనం GPT-5.2 ను ఎందుకు ఉపయోగిస్తున్నాము అంటే ఇది విమర్శాత్మక నియంత్రణని పరిచయం చేస్తుంది - మోడల్ ఎన్ని ఆలోచనలు చేయాలో మీరు చెప్పగలుగుతారు. ఇది వివిధ ప్రాంప్టింగ్ వ్యూహాలను స్పష్టంగా చేస్తుంది మరియు ఏ దృష్టికోణాన్ని ఎప్పుడు ఉపయోగించాలో అర్థం పొందటంలో సహాయపడుతుంది. -## ముందస్తు అవసరాలు +## Prerequisites -- మాడ్యూల్ 01 పూర్తి చేసుకున్నది (Azure OpenAI వనరులు అమలు చేయబడ్డాయి) -- రూట్ డైరెక్టరీలో `.env` ఫైల్‌లో Azure ప్రమాణపత్రాలు ఉన్నాయి (మాడ్యూల్ 01 లో `azd up` ద్వారా సృష్టించబడింది) +- Module 01 పూర్తి (Azure OpenAI వనరులు అమలు చేయబడినవి) +- రూట్ డైరెక్టరీలో `.env` ఫైల్ అందులో Azure సర్టిఫికెట్లు (Module 01లో `azd up` ద్వారా సృష్టించబడింది) -> **గమనిక:** మీరు మాడ్యూల్ 01 పూర్తి చేయని ఉంటే, ముందుగా అక్కడున్న అమలుచెయ్యుట సూచనలను అనుసరించండి. +> **గమనిక:** మీరు Module 01 పూర్తి చేయకపోతే, ముందుగా ఆ సెట్ అప్ సూచనలను అనుసరించండి. -## ప్రాంప్ట్ ఇంజనీరింగ్ అర్థం చేసుకోవడం +## Understanding Prompt Engineering -మూలంలో, ప్రాంప్ట్ ఇంజనీరింగ్ అనేది అస్పష్ట సూచనల మరియు ఖచ్చితమైన సూచనల మధ్య వ్యత్యాసం, క్రింది సానుకూల ఉదాహరణ చూపిస్తుంది. +మూలంగా, ప్రాంప్ట్ ఇంజనీరింగ్ అనేది సాందర్భిక మరియు ఖచ్చితమైన సూచనల మధ్య తేడా, క్రింద చూపిన పోలిక దీన్ని స్పష్టం చేస్తుంది. What is Prompt Engineering? -ప్రాంప్ట్ ఇంజనీరింగ్ అనేది మీరు కావలసిన ఫలితాలను నిరంతరంగా పొందడానికి సరైన ఇన్పుట్ టెక్స్ట్ డిజైన్ చేయడమే. ఇది కేవలం ప్రశ్నలు అడగడమే కాదు - అనగా మీరు అనువర్తించే అభ్యర్థనలను మోడల్ బాగా అర్థం చేసుకునే విధంగా ఎలా నిర్మించాలో కూడా. +ప్రాంప్ట్ ఇంజనీరింగ్ అనేది మీరు కోరుకున్న ఫలితాలు నిరంతరం అందిచే విధంగా ఇన్‌పుట్ టెక్స్ట్‌ను డిజైన్ చేయటం. ఇది కేవలం ప్రశ్నలు అడగటం మాత్రమే కాదు - మోడల్ మీరు ఏమి కోరుతున్నారో మరియు ఎలా అందించాలో ఖచ్చితంగా అర్థం చేసుకునే విధంగా అభ్యర్థనలను నిర్మించడం గురించే. -దీనిని సహచరునికి సూచనలు ఇచ్చేలా భావించండి. "బగ్‌ను పరిష్కరించు" అనేది అస్పష్టంగా ఉంటుంది. "UserService.java లైన్ 45 లో నల్ పాయింటర్ ఎక్సెప్షన్‌ను పరిష్కరించు null చెక్ జత చేసి" అనేది ఖచ్చితమైనది. భాషా మోడల్స్ కూడా అదే విధంగా పనిచేస్తాయి — ఖచ్చితత్వం మరియు నిర్మాణం ముఖ్యం. +ఇందువల్ల మీరు ఒక సహోద్యోగి కి సూచనలు ఇస్తున్నట్లు ఆలోచించండి. "బగ్ సరి చేసు" అనేది అస్పష్టమైనది. "UserService.java లో 45వ లైన్ లో ఉన్న మాాస్యం చూపు తప్పు ని null చెక్ ను జోడించి సరి చూసి" అనడం స్పష్టమైనది. భాషా మోడళ్లు కూడా ఇదే విధంగా పనిచేస్తాయి - ఖచ్చితత్వం మరియు నిర్మాణం ముఖ్యం. -క్రింది డయాగ్రామ్ LangChain4j ఈ చిత్రంలో ఎలా సరిపోతుందో చూపిస్తుంది — SystemMessage మరియు UserMessage నిర్మాణాల ద్వారా మీ ప్రాంప్ట్ నమూనాలను మోడల్‌కు కనెక్ట్ చేస్తుంది. +క్రింద ఉన్న చిత్రం LangChain4j ఈ చిత్రంలో ఎక్కడ సరిపోతుందో చూపిస్తుంది —మీ ప్రాంప్ట్ నమూనాలను SystemMessage మరియు UserMessage నిర్మాణ بلاక్ల ద్వారా మోడల్‌కు అనుసంధానించడం. How LangChain4j Fits -LangChain4j మౌలిక సదుపాయాలను అందిస్తుంది — మోడల్ కనెక్షన్లు, మెమోరీ, మరియు సందేశ రకాలు — అలాగే ప్రాంప్ట్ నమూనాలు కేవలం సక్రమంగా నిర్మించిన టెక్స్ట్, మీరు ఆ మౌలిక సదుపాయాల ద్వారా పంపే దేనే. ముఖ్యమైన నిర్మాణ బ్లాక్స్ `SystemMessage` (AI ప్రవర్తన మరియు పాత్ర సెట్ చేయడం) మరియు `UserMessage` (మీ వాస్తవ అభ్యర్థన) గా ఉంటాయి. +LangChain4j మౌలిక సదుపాయాలు అందిస్తుంది — మోడల్ కనెక్షన్లు, మెమరీ, మరియు సందేశ రకాలతో — కాగా ప్రాంప్ట్ నమూనాలు ఆ సదుపాయాల ద్వారా మీరు పంపించే జాగ్రత్తగా నిర్మించిన టెక్స్ట్ మాత్రమే. ప్రధాన నిర్మాణ బ్లాకులు `SystemMessage` (AI యొక్క ప్రవర్తన మరియు పాత్రను సెట్ చేస్తుంది) మరియు `UserMessage` (మీ అసలు అభ్యర్థనను తరలిస్తుంది). -## ప్రాంప్ట్ ఇంజనీరింగ్ నూతన అంశాలు +## Prompt Engineering Fundamentals -క్రింది ఐదు ప్రధాన సాంకేతికతలు సమర్థవంతమైన ప్రాంప్ట్ ఇంజనీరింగ్ కలిగి ఉండే పునాది. +క్రింద చూపిన ఐదు ప్రధాన సాంకేతికతలు సమర్థవంతమైన ప్రాంప్ట్ ఇంజనీరింగ్ యొక్క పునాది. ఒక్కొక్కటి భాషా మోడళ్లతో మీరు ఎలా కమ్యూనికేట్ చేస్తారో విడిగా చర్చిస్తుంది. Five Prompt Engineering Patterns Overview -ఈ మాడ్యూల్‌లో ఉన్న అగ్రగామి నమూనాలు చూసే ముందు, ఐదు ప్రాథమిక ప్రాంప్టింగ్ సాంకేతికతలను సమీక్షిద్దాం. ఇవి ప్రతి ప్రాంప్ట్ ఇంజనీరర్ తెలుసుకోవలసిన నిర్మాణ బ్లాక్స్. మీరు ఇప్పటికే [క్విక్ స్టార్ట్ మాడ్యూల్](../00-quick-start/README.md#2-prompt-patterns) ద్వారా ఈ అంశాలను చూసి ఉంటే — ఇవి వెనుక ఉన్న భావనాత్మక నిర్వహణ. +ఈ మాడ్యూల్లోని అభివృద్ధి చెందిన నమూనాలు ప్రవేశానికి ముందు, ఐదు మూల ప్రాంప్టింగ్ సాంకేతికతలను సమీక్షిద్దాం. ఇవి ప్రతి ప్రాంప్ట్ ఇంజనీర్ కు తెలుసుకోవలసిన నిర్మాణ బ్లాకులు. -### జీరో-షాట్ ప్రాంప్టింగ్ +### Zero-Shot Prompting -సాధారణమైన విధానం: మోడల్‌కు ఎలాంటి ఉదాహరణలు లేకుండా నేరుగా సూచన ఇవ్వడం. మోడల్ మొత్తం శిక్షణ మాత్రమే ఆధారంగా పని చేస్తుంది. ఇది సులభమైన అభ్యర్థనలకు అనుకూలంగా ఉంటుంది. +మొత్తానికి సులభమైన పద్ధతి: ఉదాహరణలు లేకుండా మోడల్ కు నేరుగా ఆదేశం ఇవ్వడం. మోడల్ పూర్తిగా తన శిక్షణతీ మీద ఆధారపడి పని చేస్తుంది. ఇది స్పష్టమైన ప్రవర్తనా మొత్తాలతో సరళమైన అభ్యర్థనలకు బాగా పనిచేస్తుంది. Zero-Shot Prompting -*ఉదాహరణల లేకుండా నేరుగా సూచన - మోడల్ ఆదేశం నుంచే పనిని ఊహిస్తుంది* +*ఉదాహరణలు లేకుండా నేరుగా ఆదేశం — మోడల్ ఆదేశం నుండి పనిచేసింది భావిస్తుంది* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// స్పందన: "ధనాత్మక" +// ప్రతిస్పందన: "ధనాత్మక" ``` - -**ఎప్పుడు ఉపయోగించాలి:** సింపుల్ వర్గీకరణలు, నేరుగా ప్రశ్నలు, అనువాదాలు లేదా అదనపు మార్గనిర్దేశం లేకుండా మోడల్ టాస్కు నిర్వహించగలిగిన సందర్భాల్లో. -### ఫ్యూ-షాట్ ప్రాంప్టింగ్ +**ఎప్పుడు ఉపయోగించాలి:** సులభ వర్గీకరణలు, నేరుగా అడిగే ప్రశ్నలు, అనువాదాలు లేదా అదనపు మార్గనిర్దేశం అవసరం లేని పనులు. -మోడల్ అనుసరించాల్సిన నమూనాను చూపించే ఉదాహరణలను ఇవ్వండి. మోడల్ ఉదాహరణల నుంచే ఇన్పుట్-ఆుట్పుట్ ఫార్మాట్ నేర్చుకుని కొత్త ఇన్పుట్‌లకు వర్తింప చేస్తుంది. ఇది అస్పష్టమైన నమూనాల కలిగిన పనులకు సమర్ధతను పెంచుతుంది. +### Few-Shot Prompting + +మోడల్ అనుసరించాలనుకున్న నమూనా చూపించే ఉదాహరణలు ఇవ్వండి. మోడల్ మీ ఇచ్చిన ఉదాహరణల నుండి కోరుకున్న ఇన్‌పుట్-ఆউట్పుట్ ఫార్మాట్ నేర్చుకొని, కొత్త ఇన్‌పుట్స్ లోకి దాన్ని వర్తింపజేస్తుంది. ఇది కోరుకున్న ఫార్మాట్ లేదా ప్రవర్తన స్పష్టంగా కనిపించని పనులలో సంయతత్వాన్ని గణనీయంగా మెరుగుపరుస్తుంది. Few-Shot Prompting -*ఉదాహరణల నుంచే నేర్చుకోవడం — మోడల్ నమూనాను గుర్తించి కొత్త ఇన్పుట్లలో ఉపయోగిస్తుంది* +*ఉదాహరణల నుంచి నేర్చుకోవడం — మోడల్ నమూనా గుర్తించి కొత్త ఇన్‌పుట్లకు వర్తింపచేస్తుంది* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**ఎప్పుడు ఉపయోగించాలి:** కస్టమ్ వర్గీకరణలు, సమగ్ర ఫార్మాటింగ్, డొమైన్-స్పెసిఫిక్ టాస్కులు లేదా జీరో-షాట్ ఫలితాలు అసామాన్యంగా ఉన్నప్పుడు. -### చైన్ ఆఫ్ తought +**ఎప్పుడు ఉపయోగించాలి:** కస్టమ్ వర్గీకరణలు, స్థిరమైన ఆకృతీకరణ, డొమైన్ ప్రత్యేక పనులు లేదా జీరో-షాట్ ఫలితాలు అసంశ్లేష్యమైనప్పుడు. + +### Chain of Thought -మోడల్ దాని కారణాన్ని అడుగు-అడుగు చూపించమని అడగండి. మోడల్ ప్రత్యక్ష విడుదలకు బదులుగా సమస్యను విడగొట్టి ప్రతీ భాగాన్ని సంభ్రమించకూడదు. ఇది గణితం, తర్కం, మరియు బహుళ దశల కారణం పనులను మెరుగుపరుస్తుంది. +మోడల్ స్టెప్ బై స్టెప్ తన వివరణ చూపించమని అడుగు. సమాధానానికి సూటిగా దూకినప్పుడే కాకుండా, సమస్యని విడదీసి ప్రతి భాగాన్ని స్పష్టంగా పని చేస్తుంది. ఇది గణితం, తార్కికత, మరియు బహుళ దశల నిర్ణయ పథకాలలో ఖచ్చితత్వం మెరుగుపరుస్తుంది. Chain of Thought Prompting -*అడుగు-అడుగుగా కారణం — సంక్లిష్ట సమస్యలను స్పష్టమైన తర్క దశలుగా పంచడం* +*దశల వారీ వివరణ — క్లిష్టమైన సమస్యలను స్పష్టమైన తార్కిక దశలుగా విభజించడం* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// మోడల్ చూపిస్తుంది: 15 - 8 = 7, ఆపై 7 + 12 = 19 ఆపిల్స్ +// నమూనా చూపిస్తుంది: 15 - 8 = 7, ఆపాహ్మ్మగా 7 + 12 = 19 సేపుళ్ళు ``` - -**ఎప్పుడు ఉపయోగించాలి:** గణిత సమస్యలు, తార్కిక పజిల్స్, డిబగ్గింగ్ లేదా కారణంతో పనిని మెరుగుపరచే ప్రతీ టాస్కుకు. -### పాత్ర ఆధారంగా ప్రాంప్టింగ్ +**ఎప్పుడు ఉపయోగించాలి:** గణిత సమస్యలు, తార్కిక పజిల్స్, డీబగ్గింగ్ లేదా క్లుప్తంగా వివరణ అవసరమవుతున్న ఇతర పనులు. -ప్రశ్న అడగడానికి ముందు AIకి పాత్ర లేదా వ్యక్తిత్వం ఇవ్వండి. ఇది ప్రతిస్పందన శైలీ, లోతు, దృష్టిపథం పైన ప్రభావం చూపుతుంది. "సాఫ్ట్‌వేర్ ఆర్కిటెక్టర్" ఒక విధంగా, "జూనియర్ డెవలపర్" లేదా "సెక్యూరిటీ ఆడిటర్" వేరే విధంగా సలహాలు ఇస్తుంది. +### Role-Based Prompting + +మీ ప్రశ్న అడగేముందు AI కి ఒక పాత్ర లేదా వ్యక్తిత్వం సెట్ చేయండి. ఇది సమాధానం యొక్క శైలి, లోతు, మరియు ఫోకస్ మార్చుతుంది. "సాఫ్ట్వేర్ ఆర్కిటెక్ట్" "జూనియర్ డెవలపర్" లేదా "సెక్యూరిటీ ఆడిటర్"కి ఇస్తున్న సలహాలతో వేరుగా ఉంటుంది. Role-Based Prompting -*సందర్భం మరియు పాత్రను సెట్ చేయడం — అదే ప్రశ్న వివిధ పాత్రలకు వేరే ప్రతిస్పందనలు లభింపజేయుతుంది* +*సందర్భం మరియు వ్యక్తిత్వం సెట్ చేయడం — ఒకే ప్రశ్న పాత్ర ఆధారంగా వేర్వేరు సమాధానాలు వస్తాయి* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**ఎప్పుడు ఉపయోగించాలి:** కోడ్ సమీక్షలు, శిక్షణ, డొమైన్-స్పెసిఫిక్ విశ్లేషణ లేదా ప్రత్యేక నైపుణ్యాల లేదా దృష్టికోణాలకు సర్దుబాటు అవసరమైన సందర్భాల్లో. -### ప్రాంప్ట్ టెంప్లేట్స్ +**ఎప్పుడు ఉపయోగించాలి:** కోడ్ రివ్యూలు, ట్యూటరింగ్, డొమైన్-ప్రత్యేక విశ్లేషణ, లేదా నిర్దిష్ట నైపుణ్య స్థాయికి లేదా దృష్టికోణానికి అనుగుణంగా సమాధానాలు కావలసినప్పుడు. + +### Prompt Templates -వేరియబుల్ ప్లేస్‌హోల్డర్లతో పునర్వినియోగపరచదగిన ప్రాంప్ట్‌లు సృష్టించండి. ప్రతిసారీ కొత్త ప్రాంప్ట్ రాయడం బదులు, ఒక టెంప్లేట్ నిర్వచించి వేర్వేరు విలువలు నింపండి. LangChain4j యొక్క `PromptTemplate` క్లాస్ `{{variable}}` సంకేతంతో ఈ ప్రక్రియను సులభతరం చేస్తుంది. +వేరియబుల్ ప్లేస్‌హోల్డర్లతో మళ్లీ ఉపయోగించదగిన ప్రాంప్ట్‌లను సృష్టించండి. ప్రతిసారీ కొత్త ప్రాంప్ట్ రాయడం కాకుండా, ఒక సారి టేమ్ప్లేట్ ని నిర్వచించి వివిధ విలువలు నింపండి. LangChain4j `PromptTemplate` క్లాస్ `{{variable}}` సింట్యాక్స్ తో ఇది సులభం చేస్తుంది. Prompt Templates -*వేరియబుల్ నిల్వలతో పునర్వినియోగపరచదగిన ప్రాంప్ట్‌లు — ఒక టెంప్లేట్, అనేక ఉపయోగాలు* +*వేరియబుల్ ప్లేస్‌హోల్డర్లతో మళ్లి ఉపయోగించే ప్రాంప్ట్‌లు — ఒక టేమ్ప్లేట్, అనేక ఉపయోగాలు* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**ఎప్పుడు ఉపయోగించాలి:** వివిధ ఇన్పుట్లతో పునరావృత విచారణలు, బ్యాచ్ ప్రాసెసింగ్, పునర్వినియోగపరచదగిన AI వర్క్‌ఫ్లోలను నిర్మించడం లేదా ప్రాంప్ట్ నిర్మాణం అదే ఉండి డేటా మార్చబడే సందర్భాల్లో. + +**ఎప్పుడు ఉపయోగించాలి:** విభిన్న ఇన్‌పుట్‌లతో పునరావృత ప్రశ్నలు, బ్యాచ్ ప్రాసెసింగ్, తిరిగి ఉపయోగించే AI వర్క్‌ఫ్లోలు, లేదా ప్రాంప్ట్ నిర్మాణం స్థిరంగా ఉండి డేటా మాత్రమే మారే పరిస్థితులు. --- -ఈ ఐదు ప్రాథమిక అంశాలు మీకు చాలా ప్రాంప్టింగ్ టాస్కుల కోసం బలమైన పరికరాలు అందిస్తాయి. ఈ మాడ్యూల్ మిగతా భాగం GPT-5.2 యొక్క కారణ కంట్రోల్, స్వీయ-మూల్యాంకనం మరియు నిర్మాణాత్మక అవుట్పుట్ సామర్థ్యాల పొడుగున ఎలుక పాయింట్‌లతో ఎనిమిది అగ్రగామి నమూనాలపై కేంద్రీకరించబడింది. +ఈ ఐదు మూలాలు ఎక్కువ ప్రాంప్టింగ్ పనులకు ఒక బలమైన ప్యాకేజీ ఇస్తాయి. ఈ మాడ్యూల్ వారి పైన ఆధారపడి ఉంది **ఎనిమిది అభివృద్ధి చెందిన నమూనాలు** GPT-5.2 యొక్క విమర్శాత్మక నియంత్రణ, స్వయం-మూల్యాంకన, మరియు నిర్మిత అవుట్పుట్ సామర్థ్యాలను ఉపయోగిస్తాయి. -## అగ్రగామి నమూనాలు +## Advanced Patterns -ప్రాథమిక అంశాలు ముట్టడి అయిన తర్వాత, ఈ మాడ్యూల్‌ను ప్రత్యేకతగా మార్చే ఎనిమిది అగ్రగామి నమూనాలకు వెళ్దాం. అన్ని సమస్యలకు ఒకే విధానమే అవసరం కాదు. కొన్ని ప్రశ్నలకు త్వరిత సమాధానాలు కావాలి, మరికొన్ని లోతైన ఆలోచన. కొన్నింటికి ప్రత్యక్ష కారణం చూపించాలి, కొన్నింటికి ఫలితాలు కావాలి. క్రింద వాటి వాడుకకు అనుగుణంగా ప్రతి నమూనా రూపొందించబడింది — GPT-5.2 యొక్క కారణ నియంత్రణ తేడాలను మరింత స్పష్టత చేయుతుంది. +మూలాలు పూర్తయిన తరువాత, ఈ మాడ్యూల్ ప్రత్యేకతను ఇచ్చే ఎనిమిది అభివృద్ధి చెందిన నమూనాలకు చేరుకుందాం. అన్ని సమస్యలు ఒకే విధముగా ఉండవు. కొన్ని ప్రశ్నలకు తక్షణ సమాధానం అవసరం, మరికొన్ని లోతైన ఆలోచనకు. కొన్ని స్పష్టమైన విమర్శన అవసరం, మరికొన్ని ఫలితాలకే. కింది ప్రతి నమూనా వేర్వేరు సందర్భాలకు అనువైనదిగా ఆప్టిమైజ్ చేయబడింది — మరియు GPT-5.2 యొక్క విమర్శాత్మక నియంత్రణ ఈ భేదాలను మరింత స్పష్టంగా చేస్తుంది. Eight Prompting Patterns -*ఎనిమిది ప్రాంప్ట్ ఇంజనీరింగ్ నమూనాల అవగాహన మరియు వాటి వాడుక సందర్భాలు* +* ఎనిమిది ప్రాంప్ట్ ఇంజనీరింగ్ నమూనాల సమీక్ష మరియు వాటి వినియోగ సందర్భాలు * -GPT-5.2 ఈ నమూనాలకు మరో కొలతను జోడిస్తుంది: *కారణ నియంత్రణ*. క్రింది స్లైడర్ చూపించిన విధంగా మీరు మోడల్ ఆలోచనా శక్తిని—from త్వరిత, నేరుగా సమాధానాల నుండి లోతైన, సమగ్ర విశ్లేషణ వరకు—సర్దుబాటు చేసుకోవచ్చు. +GPT-5.2 ఈ నమూనాలకు మరో మలుపు ఇస్తుంది: *విమర్శా నియంత్రణ*. క్రింద స్లైడర్ మోడల్ ఎంత ఆలోచించాలో మీరు సర్దుబాటు చేయగలుగుతారు — తక్షణ, నేరుగా సమాధానాల నుంచి లోతైన, సమగ్ర విశ్లేషణ వరకు. Reasoning Control with GPT-5.2 -*GPT-5.2 యొక్క కారణ నియంత్రణ ద్వారా మీరు ఎటువంటి స్థాయిలో ఆలోచించాలో నిర్ణయించవచ్చు — త్వరిత నేరుగా సమాధానాల నుండి లోతైన అన్వేషణ వరకు* +*GPT-5.2 విమర్శా నియంత్రణ ద్వారా మీరు మోడల్ ఎంత ఆలోచించాలో నిర్ణయించవచ్చు — వేగవంతమైన నేరుగా సమాధానాలు నుంచి లోతైన విశ్లేషణ వరకు* -**తక్కువ ఉత్సాహం (త్వరితము & అదుపుకారు)** - సులభ ప్రశ్నలకు మందగించి తేలికైన సమాధానాలు అవసరమైన సందర్భాల్లో. మోడల్ తక్కువ కారణం - గరిష్టం 2 దశలు. లెక్కింపు, లుకప్, లేదా సరళ ప్రశ్నలకు వాడండి. +**తక్కువ ఉత్సాహం (తక్షణ & దృష్టిసారించబడిన)** - సులభ ప్రశ్నలకు వేగవంతమైన, నేరుగా సమాధానాలు కావాలంటే. మోడల్ తక్కువ విమర్శ చేస్తుంది - గరిష్టం 2 దశలు. గణనాలు, లుకప్స్ లేదా సరళమైన ప్రశ్నల కోసం ఉపయోగించండి. ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> 💡 **GitHub Copilot తో అన్వేషించండి:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) ఓపెన్ చేసి అడగండి: -> - "తక్కువ ఉత్సాహం మరియు అధిక ఉత్సాహం ప్రాంప్టింగ్ నమూనాల మధ్య తేడా ఏంటి?" -> - "ప్రాంప్ట్‌లలో XML ట్యాగ్లు AI ప్రతిస్పందన నిర్మాణానికి ఎలా సహాయపడతాయి?" -> - "నేను ఎప్పుడు స్వీయ-పరిశీలన నమూనాలు వాడాలి, నేరుగా సూచన ఇవ్వాలి?" -**అధిక ఉత్సాహం (లోతైన & సమగ్ర)** - సంక్లిష్ట సమస్యలకు సప్తమ, వ్యాప్తిగా విశ్లేషణ కావాలి. మోడల్ లోతుగా అన్వేషించి పూర్తి వివరణతో కారణం చూపిస్తుంది. సిస్టమ్ డిజైన్, ఆర్కిటెక్చర్ నిర్ణయాలు, క్లిష్ట పరిశోధనలకు వాడండి. +> 💡 **GitHub Copilot తో ఎక్స్‌ప్లోర్ చేయండి:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) తెరవండి మరియు అడగండి: +> - "తక్కువ ఉత్సాహం మరియు ఎక్కువ ఉత్సాహం ప్రాంప్టింగ్ నమూనాల మధ్య తేడా ఏమిటి?" +> - "ప్రమ్ప్ట్‌లలో XML ట్యాగ్లు AI ప్రతిస్పందన నిర్మాణానికి ఎలా సహాయపడతాయి?" +> - "ఎప్పుడు స్వీయ-పరిశీలన నమూనాలు ఉపయోగించాలి, ఎప్పుడు నేరుగా ఆదేశించాలి?" + +**అధిక ఉత్సాహం (లోతైన & సమగ్ర)** - క్లిష్టమైన సమస్యలకు సమగ్ర విశ్లేషణ కావాలి. మోడల్ సమగ్రంగా పరిశీలించి వివరాలైన విమర్శను చూపిస్తుంది. సిస్టమ్ డిజైన్, ఆర్కిటెక్చర్ నిర్ణయాలు, లేదా క్లిష్ట పరిశోధనలకు ఉపయోగించండి. ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**టాస్క్ ఎగ్జిక్యూషన్ (అడుగు-అడుగుగా ప్రగతి)** - బహుళ దశల వర్క్‌ఫ్లోల కోసం. మోడల్ మొదట ప్లాన్ ఇస్తుంది, ప్రతీ దశనూ తెలుపుతుంది, చివరగా సారాంశాన్ని ఇస్తుంది. మైగ్రేషన్లు, అమలుదలలు లేదా ఎలాంటి బహుళ దశల ప్రాసెస్ కోసం వాడండి. + +**టాస్క్ ఎక్జిక్యూషన్ (దశల వారీ ప్రగతి)** - బహుళ దశల వర్క్‌ఫ్లోలకు. మోడల్ ముందుగా ఒక ప్రణాళిక ఇస్తుంది, పని చేసే ప్రతీ దశను వివరించి వ్యాఖ్యానిస్తుంది, చివరలో సారాంశం ఇస్తుంది. మైగ్రేషన్లు, అమలులు, లేదా ఏదైనా బహుళ దశల ప్రక్రియకు ఉపయోగించండి. ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -చైన్-ఆఫ్-థought ప్రాంప్టింగ్ మోడల్‌ను దాని కారణాన్ని చూపించమని స్పష్టంగా అడుగుతుంది, దీని వలన సంక్లిష్ట టాస్కుల్లో ఖచ్చితత్వం పెరుగుతుంది. అడుగు-అడుగు విభజన చేత మానవులు మరియు AI రెండింటికీ తర్కాన్ని అర్థం చేసుకోవడం సులభం. -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్ తో ప్రయత్నించండి:** ఈ నమూనా గురించి అడగండి: -> - "దీర్ఘకాలిక ఆపరేషన్లు కోసం టాస్క్ ఎగ్జిక్యూషన్ నమూనాను ఎలా సర్దుబాటు చేస్తాను?" -> - "ఉత్పత్తి అప్లికేషన్లలో టూల్ ప్రీస్టాంబుల్స్ నిర్మాణం కోసం ఉత్తమ పద్ధతులు ఏంటి?" -> - "UIలో మధ్యంతర ప్రగతి సమాచారం ఎలా స్వీకరించి ప్రదర్శించగలను?" +చైన్-ఆఫ్-థాట్ ప్రాంప్టింగ్ స్పష్టంగా మోడల్ తన విమర్శా ప్రక్రియను చూపించమని అడుగుతుంది, క్లిష్ట పనులలో ఖచ్చితత్వాన్నిస్తుంది మెరుగుపరుస్తుంది. దశల వారీ బ్రేక్‌డౌన్ మనుషులు మరియు AI కి తార్కికత అర్థం చేసుకోవడానికి సహాయపడుతుంది. + +> **🤖 GitHub Copilot చాట్‌తో ప్రయత్నించండి:** ఈ నమూనా గురించి అడగండి: +> - "నా పొడిగి గడిచే ఆపరేషన్ల కోసం టాస్క్ ఎక్జిక్యూషన్ నమూనాను ఎలా మార్చగలను?" +> - "నిర్మాణ యాప్లికేషన్లలో టూల్ ప్రాంబుల్స్ నిర్మాణానికి ఉత్తమ పద్ధతులు ఏమిటి?" +> - "UI లో మధ్యంతర ప్రగతి అప్‌డేట్లను ఎలా క్యాచ్చి ప్రదర్శించగలను?" -క్రింది డయాగ్రామ్ ఈ ప్లాన్ → ఎగ్జిక్యూట్ → సారాంశం వర్క్‌ఫ్లోని చూపిస్తుంది. +క్రింద చిత్రం ఈ ప్రణాళిక → అమలు → సారాంశం వర్క్‌ఫ్లోని చూపిస్తుంది. Task Execution Pattern -*బహుళ దశల పనుల కోసం ప్లాన్ → ఎగ్జిక్యూట్ → సారాంశం వర్క్‌ఫ్లో* +* బహుళ దశల పనుల కోసం ప్రణాళిక → అమలు → సారాంశం వర్క్‌ఫ్లో * -**స్వీయ-పరిశీలన కోడ్** - ఉత్పత్తి నాణ్యత కోడ్ తయారుచేయడానికి. మోడల్ ఉత్పత్తి ప్రమాణాలు పాటిస్తూ సరైన ఎర్రర్ హ్యాండ్లింగ్‌తో కోడ్ ఉత్పత్తి చేస్తుంది. కొత్త ఫీచర్‌లు లేదా సర్వీసులు తయారుచేసేటప్పుడు వాడండి. +**స్వయం-పరిశీలన కోడ్** - ప్రొడక్షన్-నాణ్యత కోడ్ సృష్టికి. మోడల్ ప్రొడక్షన్ ప్రమాణాలను అనుసరించి తప్పిద నిర్వహణతో కోడ్ సృష్టిస్తుంది. కొత్త ఫీచర్లు లేదా సర్వీసులు నిర్మించేటప్పుడు ఉపయోగించండి. ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -క్రింది డయాగ్రామ్ ఈ పునరావృత మెరుగుదల లూపును చూపిస్తుంది — ఉత్పత్తి చేయండి, మూల్యాంకనం చేయండి, బలహీనతను గుర్తించండి, మెరుగుపరచండి, తిరిగి పునరావృతం చేయండి. + +క్రింద చిత్రంలో ఈ పునరావృత మెరుగుదల లూప్ చూపించినది — సృష్టించు, అంచనా వేయి, లోపాలను గుర్తించు, మెరుగుపరుచు, మళ్లీ పునరావృతం చేయు. Self-Reflection Cycle -*పునరావృత మెరుగుదల లూప్ - ఉత్పత్తి చేయండి, మూల్యాంకనం చేయండి, సమస్యలను గుర్తించండి, మెరుగుపరచండి, పునరావృతం చేయండి* +*పునరావృత మెరుగుదల లూప్ - సృష్టించు, అంచనా వేసి, లోపాలు గుర్తించి, మెరుగుపరుచు, పునరావృతి* -**సంఖ్యాబద్ధమైన విశ్లేషణ** - సమగ్ర మూల్యాంకనానికి. మోడల్ కోడ్‌ను ఒక స్థిరమైన ఫ్రేమ్‌వర్క్ ఆధారంగా సమీక్షిస్తుంది (ఖచ్చితత్వం, ప్రాక్టీసులు, పనితనం, భద్రత, నిర్వహణ). కోడ్ సమీక్షల కోసం వాడండి. +**సంఘటిత విశ్లేషణ** - స్థిర విశ్లేషణ కోసం. మోడల్ కోడ్ ని స్థిరమైన ఫ్రేమ్‌వర్క్ (ఖచ్చితత్వం, ఆచారాలు, పనితీరు, భద్రత, నిర్వహణ) ఉపయోగించి సమీక్షిస్తుంది. కోడ్ రివ్యూలు లేదా నాణ్యత మూల్యాంకనాలకు ఉపయోగించండి. ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్ తో ప్రయత్నించండి:** సంక్షిప్త విశ్లేషణ గురించి అడగండి: -> - "విభిన్న కోడ్ సమీక్షల కోసం విశ్లేషణ ఫ్రేమ్‌వర్క్‌ను ఎలా అనుకూలీకరించగలను?" -> - "సంఖ్యాబద్ధ అవుట్పుట్‌ను ప్రోగ్రామేటిక్గా ఎలా పార్స్ చేసి పనిచేయాలి?" -> - "విభిన్న సమీక్ష సెషన్లలో స్థిరమైన తీవ్రమైన స్థాయిలను ఎలా నిర్ధారించాలి?" -క్రింది డయాగ్రామ్ ఈ స్థిరమైన ఫ్రేమ్‌వర్క్ కోడ్ సమీక్షను తీవ్రతా స్థాయిలతో విభజించి ఎలా నిర్వహిస్తుంది చూపిస్తుంది. +> **🤖 GitHub Copilot చాట్‌తో ప్రయత్నించండి:** సంఘటిత విశ్లేషణ గురించి అడగండి: +> - "విభిన్న రకాల కోడ్ రివ్యూలకు విశ్లేషణ ఫ్రేమ్‌వర్క్‌ను ఎలా అనుకూలీకరించగలను?" +> - "సంఘటిత అవుట్పుట్‌ను ప్రోగ్రామేటిక్‌గా పార్స్ చేసి ఎలా వ్యవహరించాలి?" +> - "వివిధ రివ్యూ సెషన్లలో సమాన తీవ్రత స్థాయిలను ఎలా నిర్ధారించాలి?" + +క్రింద ఉన్న చిత్రం ఈ నిర్మిత ఫ్రేమ్‌వర్క్ కోడ్ సమీక్షను స్థిరమైన వర్గాలు మరియు తీవ్రత స్థాయిలతో ఎలా ఆర్గనైజ్ చేస్తుందో చూపిస్తుంది. Structured Analysis Pattern -*తీవ్రమైన స్థాయిలతో స్థిరమైన కోడ్ సమీక్షలకు ఫ్రేమ్‌వర్క్* +*స్థిరమైన కోడ్ రివ్యూల కోసం తీవ్రత స్థాయిలతో ఫ్రేమ్‌వర్క్* -**బహుళ-తలుపు సంభాషణ** - సందర్భం అవసరమయ్యే సంభాషణలకు. మోడల్ ఇంతకు ముందు సందేశాలను గుర్తించి వాటిపై ఆధారపడి స్కెచ్ చేస్తుంది. ఇంటరాక్టివ్ సహాయం సెషన్లు లేదా క్లిష్ట ప్రశ్న-సమాధానాల కొరకు వాడండి. +**బహుళ-తురన్ చాట్** - పరిస్థు అవసరమైన సంభాషణలకు. మోడల్ గత సందేశాలను గుర్తుంచుకొని వాటిపై నిర్మించుకుంటుంది. ఇంటరాక్టివ్ సహాయక సెషన్లు లేదా క్లిష్ట క్వెరీలు కోసం ఉపయోగించండి. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -క్రింది డయాగ్రామ్ సంభాషణ సందర్భం ప్రతీ మడతతో ఎలా పెరుగుతుందో, మరియు మోడల్ యొక్క టోకెన్ పరిమితికి ఇది ఎలా సంబంధించింది చూపిస్తుంది. + +క్రింద చిత్రం సంభాషణ సందర్భం ఎలా బహుళ దశలలో చేరిపోతోందో మరియు అది మోడల్ టోకెన్ పరిమితికి ఎలా తగిలిందో చూపిస్తుంది. Context Memory -*ఒకటి తర్వాత ఒకటి సంభాషణ సందర్భం ఎలా కూడి టోకెన్ పరిమితి వరకు పెరుగుతుంది* -**దశల వారీ వివరణ** - గణిత సమస్యలు, ధార్మిక పజిల్స్ లేదా ఆలోచన ప్రক্রియను అర్థం చేసుకోవాలి అనుకునే సందర్భాల్లో మోడల్ ప్రతి దశ కు స్పష్టమైన తర్కాన్వేషణను చూపిస్తుంది. +*బహుళ దశల్లో సంభాషణ సందర్భం ఎలా చేరుకుంటుందో టోకెన్ పరిమితి చేరుకునే వరకూ* + +**దశ-దశ వ్యాసంగం** - దృశ్యమైన తార్కికత అవసరమైన సమస్యలకు. మోడల్ ప్రతి దశకు స్పష్టమైన తార్కికత చూపిస్తుంది. గణిత సమస్యలు, తార్కిక పజిల్స్, లేదా ఆలోచన ప్రಕ್ರియను అర్థం చేసుకోవలసిన సందర్భాల్లో ఉపయోగించండి. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -క్రింది రెజు చిత్రం మోడల్ సమస్యలను స్పష్టమైన, సంఖ్యాబద్ధమైన తర్క ఆవరణ దశలుగా ఎలా విభజిస్తుందో చూపిస్తుంది. +క్రింద చిత్రం మోడల్ సమస్యలను స్పష్టమైన సంఖ్య ఉన్న తార్కిక దశలుగా ఎలా విభజిస్తుందో చూపిస్తుంది. -దశల వారీ తీరు +Step-by-Step Pattern +*సమస్యలను స్పష్టమైన తార్కిక దశలుగా విభజించడం* -*సమస్యలను స్పష్టమైన తర్క దశలుగా విభజించడం* - -**నిర్బंधిత అవుట్‌పుట్** - నిర్దిష్ట ఫార్మాట్ అవసరాలు ఉన్న స్పందనలకు. మోడల్ కఠినంగా ఫార్మాట్ మరియు పొడవు నిబంధనలను అనుసరిస్తుంది. సమ్మరీలకు లేదా ఖచ్చితమైన అవుట్‌పుట్ నిర్మాణం అవసరం ఉన్నప్పుడు దీనిని వాడండి. +**పరిమిత అవుట్‌పుట్** - నిర్దిష్ట ఫార్మాట్ అవసరాలతో ఉన్న ప్రతిపాదనలకు. మోడల్ కఠినంగా ఫార్మాట్ మరియు పొడవు నియమాలను అనుసరిస్తుంది. ఇది సారాంశాల కోసం లేదా మీరు ఖచ్చితమైన అవుట్పుట్ నిర్మాణం కావాలనుకుంటే ఉపయోగించండి. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -క్రింది చిత్రం కఠిన నియమాలు మీ ఫార్మాట్ మరియు పొడవు అవసరాలకు కట్టడి విధానాన్ని చూపిస్తుంది. +ఈ క్రింది డయాగ్రామ్ పరిమితులు మీ ఫార్మాట్ మరియు పొడవు అవసరాలను కఠినంగా అనుసరించే అవుట్‌పుట్‌ను ఉత్పత్తి చేయడానికి మోడల్‌ను ఎలా మార్గనిర్దేశం చేస్తాయో చూపిస్తుంది. -నిర్బంధిత అవుట్‌పుట్ తీరు +పరిమిత అవుట్‌పుట్ నమూనా -*నిర్దిష్ట ఫార్మాట్, పొడవు, మరియు నిర్మాణ అవసరాలు విధించడం* +*నిర్దిష్ట ఫార్మాట్, పొడవు మరియు నిర్మాణ అవసరాలను అమలు చేయడం* -## అనువర్తనాన్ని నడపండి +## అప్లికేషన్‌ను అమలు చేయండి -**డిప్లాయ్‌మెంట్‌ను నిర్ధారించండి:** +**నియామకాన్ని ధృవీకరించండి:** -మూల డైరెక్టరీలో `.env` ఫైల్ ఉండు Azure సర్టిఫికెట్స్‌తో (Module 01 లో సృష్టించబడింది) ఉండాల్సి ఉంటుంది. ఈ డైరెక్టరీ నుంచి నడపండి (`02-prompt-engineering/`): +రూట్ డైరెక్టరీలో `.env` ఫైల్ Azure క్రెడెన్షియల్స్‌తో (మాడ్యూల్ 01 సమయంలో సృష్టించబడింది) ఉన్నదని నిర్ధారించుకోండి. ఇది మాడ్యూల్ డైరెక్టరీ నుండి నడపండి (`02-prompt-engineering/`): **Bash:** ```bash @@ -442,29 +442,29 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT చూపించా Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT చూపించాలి ``` -**అనువర్తనాన్ని ప్రారంభించండి:** +**అప్లికేషన్ ప్రారంభించండి:** -> **గమనిక:** మీరు ఇప్పటికే మొదటి మాడ్యూల్ లో వివరించిన విధంగా మూల డైరెక్టరీ నుండి `./start-all.sh` ఉపయోగించి అన్ని అనువర్తనాలను ప్రారంభించినట్లయితే, ఈ మాడ్యూల్ ఇప్పటికే 8083 పోర్టు పై నడుస్తుంది. కాబట్టి క్రింది ప్రారంభ ఆదేశాలను తప్పించుకోవచ్చు మరియు నేరుగా http://localhost:8083 కి వెళ్ళండి. +> **గమనిక:** మీరు ఇప్పటికే రూట్ డైరెక్టరీ నుండి `./start-all.sh` ఉపయోగించి అన్ని అప్లికేషన్‌లను ప్రారంభించి ఉంటే (మాడ్యూల్ 01లో వివరించబడింది), ఈ మాడ్యూల్ ఇప్పటికే 8083 పోర్ట్‌లో నడుస్తోంది. కింద ఉన్న మొదలివ్వు ఆదేశాలను వదలిపెట్టండి మరియు నేరుగా http://localhost:8083 కి వెళ్లండి. -**అభ్యాసం 1: Spring Boot డాష్‌బోర్డ్ ఉపయోగించడం (VS Code వినియోగదారులకు సిఫార్సు చేయబడింది)** +**ఒప్షన్ 1: Spring Boot డాష్‌బోర్డ్ ఉపయోగించడం (VS Code వినియోగదారులకు సిఫార్సు చేయబడింది)** -డెవ్ కంటెయినర్‌లో Spring Boot డాష్‌బోర్డ్ విస్తరణ ఉన్నాయి ఇది మీరు Spring Boot అనువర్తనాలను విజువల్ ఇంటర్ఫేస్ ద్వారా నిర్వహించేందుకు అవకాశం ఇస్తుంది. ఇది VS Code లో ఎడమ వైపు Activity Bar లో Spring Boot చిహ్నం ద్వారా కనిపిస్తుంది. +డెవ్ కంటైనర్ Spring Boot డాష్‌బోర్డ్ విస్తరణను కలిగి ఉంటుంది, ఇది అన్ని Spring Boot అప్లికేషన్‌లను నిర్వహించడానికి విజువల్ ఇంటర్‌ఫేస్‌ను అందిస్తుంది. మీరు దీన్ని VS Code యొక్క ఎడమ వైపు ఉన్న Activity Barలో సులభంగా చూడవచ్చు (Spring Boot చిహ్నం కోసం చూడండి). -Spring Boot డాష్‌బోర్డ్ నుండి మీరు: -- ఆ పని ప్రదేశంలోని అన్ని Spring Boot అనువర్తనాలను చూడవచ్చు -- ఒక క్లిక్ తో అనువర్తనాలను ప్రారంభించు/ఆపు -- రియల్-టైమ్లో అనువర్తనం లాగ్‌లను వీక్షించు -- అనువర్తనం స్థితిని పర్యవేక్షించు +Spring Boot డాష్‌బోర్డ్ను ఉపయోగించి మీరు చేయగలవు: +- వర్క్‌స్పేస్‌లో అందుబాటులో ఉన్న అన్ని Spring Boot అప్లికేషన్‌లను చూడండి +- ఒక క్లిక్‌తో అప్లికేషన్‌లను ప్రారంభించండి/ఆపండి +- రియల్ టైంలో అప్లికేషన్ లాగ్‌లను వీక్షించండి +- అప్లికేషన్ స్థితిని పర్యవేక్షించండి -"prompt-engineering" పక్కన ఉన్న ప్లే బటన్‌ను క్లిక్ చేసి ఈ మాడ్యూల్ ను ప్రారంభించండి లేదా అన్ని మాడ్యూల్ లను ఒకేసారి ప్రారంభించండి. +"prompt-engineering" పక్కన ఉన్న ప్లే బటన్‌ను క్లిక్ చేయడం ద్వారా ఈ మాడ్యూల్‌ను ప్రారంభించండి లేదా అన్ని మాడ్యూల్‌లను ఒకేసారి ప్రారంభించండి. Spring Boot డాష్‌బోర్డ్ -*VS Code లో Spring Boot డాష్‌బోర్డ్ — అన్ని మాడ్యూల్ లను ఒకే చోట నుండి ప్రారంభించండి, ఆపు మరియు పర్యవేక్షించండి* +*VS Code లో Spring Boot డాష్‌బోర్డ్ — అన్ని మాడ్యూల్‌లను ఒకే చోటుంచి ప్రారంభించండి, ఆపండి మరియు పర్యవేక్షించండి* -**అభ్యాసం 2: షెల్ స్క్రిప్ట్‌లు ఉపయోగించడం** +**ఒప్షన్ 2: షెల్ స్క్రిప్ట్‌లను ఉపయోగించడం** -అனை వెబ్ అనువర్తనాలు (మాడ్యూల్ 01-04) ప్రారంభించండి: +అన్ని వెబ్ అప్లికేషన్లు (మాడ్యూల్‌లు 01-04)ను ప్రారంభించండి: **Bash:** ```bash @@ -478,7 +478,7 @@ cd .. # రూట్ డైరెక్టరీ నుండి .\start-all.ps1 ``` -లేదా ఈ మాడ్యూల్ మాత్రమే ప్రారంభించండి: +లేదా కేవలం ఈ మాడ్యూల్‌ను ప్రారంభించండి: **Bash:** ```bash @@ -492,25 +492,25 @@ cd 02-prompt-engineering .\start.ps1 ``` -రూట్ `.env` ఫైల్ నుండి వాతావరణ సారాంశాలను ఇరు స్క్రిప్ట్‌లు ఆటోమేటిగ్గా లోడ్ చేసి, కావలసినపుడు JAR ఫైళ్లను తయారు చేస్తాయి. +రూట్ `.env` ఫైల్ నుండి రెండు స్క్రిప్ట్‌లు ఆటోమేటిక్‌గా ఎన్విరాన్‌మెంట్ వేరియబుల్‌లను లోడ్ చేస్తాయి మరియు అవసరమైతే JARలను నిర్మిస్తాయి. -> **గమనిక:** మీరు మొదట మాన్యువల్ గా అన్ని మాడ్యూల్ లను నిర్మించి ఆ తరువాత ప్రారంభించాలనుకుంటే: +> **గమనిక:** మీరు ప్రారంభించే ముందు అన్ని మాడ్యూల్‌లను చేతితో నిర్మించాలని ఇష్టపడితే: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -మీ బ్రౌజర్ లో http://localhost:8083 ఓపెన్ చేయండి. +మీ బ్రౌజర్‌లో http://localhost:8083 ఓపెన్ చేయండి. -**ఆపు:** +**ఆపడానికి:** **Bash:** ```bash @@ -523,86 +523,86 @@ cd .. && ./stop-all.sh # అన్ని మాడ్యూల్స్ ```powershell .\stop.ps1 # ఈ మాడ్యూల్ మాత్రమే # లేదా -cd ..; .\stop-all.ps1 # అన్ని మాడ్యూల్స్ +cd ..; .\stop-all.ps1 # అన్ని మాడ్యూల్‌లు ``` -## అనువర్తన స్క్రీన్‌షాట్లు +## అప్లికేషన్ స్క్రీన్‌షాట్లు -ఇదే prompt engineering మాడ్యూల్ యొక్క ప్రధాన ఇంటర్ఫేస్, ఇక్కడ మీరు అన్ని ఎనిమిది ప్యాటర్న్‌లను ఒంటరిగా పరీక్షించవచ్చు. +ఇది ప్రాంప్ట్ ఇంజినీరింగ్ మాడ్యూల్ యొక్క ప్రధాన ఇంటర్‌ఫేస్, మీరు ఇక్కడ అన్ని ఎరు నమూనాలు పక్క naast పరీక్షించవచ్చు. -డాష్‌బోర్డ్ హోమ్ +డాష్‌బోర్డ్ హోం -*అన్ని 8 prompt engineering ప్యాటర్న్‌లను, వాటి లక్షణాలు మరియు ఉపయోగకారిత లక్షణాలతో ప్రదర్శించే ప్రధాన డాష్‌బోర్డ్* +*ప్రధాన డాష్‌బోర్డ్ అన్ని 8 ప్రాంప్ట్ ఇంజినీరింగ్ నమూనాలను వాటి లక్షణాలు మరియు వినియోగ సందర్భాలుతో చూపిస్తుంది* -## ప్యాటర్న్‌లను అన్వేషించడం +## నమూనాలను అన్వేషించడం -వెబ్ ఇంటర్ఫేస్ వివిధ ప్రాంప్టింగ్ వ్యూహాలను ప్రయత్నించడానికి వీలు కల్పిస్తుంది. ప్రతి ప్యాటర్న్ వేరు వేరు సమస్యలను పరిష్కరిస్తుంది - వాటిని ప్రయత్నించి ఏ సందర్భంలో ఏ విధానము మెరుగో చూడండి. +వెబ్ ఇంటర్‌ఫేస్ వేర్వేరు ప్రాంప్టింగ్ వ్యూహాలతో ప్రయోగించడం అనుమతిస్తుంది. ప్రతి నమూనా వివిధ సమస్యలను పరిష్కరిస్తుంది - అవి ఎప్పుడైతే మెరుగ్గా పనిచేస్తాయో చూడండి. -> **గమనిక: స్ట్రీమింగ్ వర్సెస్ నాన్-స్ట్రీమింగ్** — ప్రతి ప్యాటర్న్ పేజీ రెండు బటన్లను అందిస్తుంది: **🔴 Stream Response (Live)** మరియు **Non-streaming** ఎంపిక. స్ట్రీమింగ్ Server-Sent Events (SSE) ని ఉపయోగించి మోడల్ సృష్టిస్తున్న టోకెన్లను రియల్ టైంలో చూపిస్తుంది, అందువల్ల మీరు ప్రగతిని తక్షణమే చూస్తారు. నోన్-స్ట్రీమింగ్ ఆప్షన్ మొత్తం స్పందన పూర్తయ్యేవరకు వేచి ఉంటుంది. దీని వల్ల లోతైన తర్కాన్వేషణ అవసరమైన (ఉదా: High Eagerness, Self-Reflecting Code) సందర్భాల్లో చాలా సమయం పడుతుంది — కొన్నిసార్లు నిమిషాలు — మరియు దృశ్య ఫీడ్‌బ్యాక్ ఉండదు. **సంక్లిష్ట ప్రాంప్ట్‌ల పై ప్రయోగాలు చేయేటప్పుడు స్ట్రీమింగ్ ఉపయోగించండి** మోడల్ పనిచేస్తున్నట్టు తెలుస్తుంది మరియు అభ్యర్థన టైమ్ అవుట్ అయ్యిందనే అనుమానం లేకుండా ఉంటుంది. +> **గమనిక: స్ట్రీమింగ్ మరియు నాన్-స్ట్రీమింగ్** — ప్రతి నమూనా పేజీలో రెండు బటన్లు ఉంటాయి: **🔴 స్ట్రీమ్ రెస్పాన్స్ (లైవ్)** మరియు **నాన్-స్ట్రీమింగ్** ఎంపిక. స్ట్రీమింగ్ Server-Sent Events (SSE) ఉపయోగించి మోడల్ ఉత్పత్తి చేసే టోకెన్లను నిజకాలంలో ప్రదర్శిస్తుంది, కాబట్టి మీరు ప్రగతిని తక్షణమే చూడగలరు. నాన్-స్ట్రీమింగ్ ఎంపిక పూర్తి ప్రతిస్పందన కోసం వేచి ఉంటుంది. లోతైన తర్కాన్ని ట్రిగ్గर చేసే ప్రాంప్ట్‌ల (ఉదా: హై ఈగర్నెస్, Self-Reflecting కోడ్) కోసం, నాన్-స్ట్రీమింగ్ కాల్ చాలా కాలం పట్టవచ్చు — కొన్ని సార్లు నిమిషాలు — దృశ్యమైన ఫీడ్‌బ్యాక్ లేకుండా. **సంక్లిష్టమైన ప్రాంప్ట్‌లతో ప్రయోగించేటప్పుడు స్ట్రీమింగ్ ఉపయోగించండి** తద్వారా మీరు మోడల్ పనిచేస్తున్నట్టు చూడవచ్చు మరియు అభ్యర్థన టైమ్ అవుట్ అయినట్టు అనిపించకుండా ఉంటుంది. > -> **గమనిక: బ్రౌజర్ అవసరం** — స్ట్రీమింగ్ ఫీచర్ Fetch Streams API (`response.body.getReader()`) ఉపయోగిస్తుంది, ఇది పూర్తి బ్రౌజర్‌లకు (Chrome, Edge, Firefox, Safari) అవసరం. VS Code లోని నిలిపి గల Simple Browser పని చేయదు, ఎందుకంటే దాని webview ReadableStream API కు మద్దతు ఇవ్వదు. మీరు Simple Browser వాడితే, non-streaming బటన్లు సాధారణంగా పని చేస్తాయి; స్ట్రీమింగ్ బటన్లు మాత్రమే ప్రభావితం అవుతాయి. పూర్తి అనుభవం కోసం `http://localhost:8083`ని ఒక బాహ్య బ్రౌజర్‌లో తెరవండి. +> **గమనిక: బ్రౌజర్ అవసరం** — స్ట్రీమింగ్ ఫీచర్ Fetch Streams API (`response.body.getReader()`) ఉపయోగిస్తుంది, ఇది పూర్తి బ్రౌజర్‌ల (Chrome, Edge, Firefox, Safari) కోసం అవసరం. ఇది VS Code లో బిల్ట్-ఇన్ Simple Browser లో పని చేయదు, ఎందుకంటే ఆ వెబ్‌వ్యూ ReadableStream API ని మద్దతు ఇవ్వదు. మీరు Simple Browser ఉపయోగిస్తే, నాన్-స్ట్రీమింగ్ బటన్లు సర్వసాధారణంగా పనిచేస్తాయని గమనించండి — కేవలం స్ట్రీమింగ్ బటన్లు మాత్రమే ఆటంకపృతాయంగా ఉంటాయి. పూర్తి అనుభవం కోసం `http://localhost:8083` ను బాహ్య బ్రౌజర్‌లో ఓపెన్ చేయండి. -### తక్కువ వేగస్థాయీ వర్సెస్ అధిక వేగస్థాయీ +### తక్కువ మరియు ఎక్కువ ఈగర్నెస్ -"200 యొక్క 15%" వంటి సరళ ప్రశ్నను తక్కువ వేగస్థాయితో అడగండి. మీరు తక్షణ, ప్రత్యక్ష సమాధానం పొందుతారు. ఇప్పుడు "హై-ట్రాఫిక్ API కోసం caching వ్యూహాన్ని డిజైన్ చేయండి" వంటి సంక్లిష్టమైన ప్రశ్నను అధిక వేగస్థాయితో అడగండి. **🔴 Stream Response (Live)** క్లిక్ చేసి మోడల్ యొక్క వివరమైన తర్కాన్వేషణను టోకెన్ వారీగా చూడండి. ఒకటే మోడల్, ఒకటే ప్రశ్న నిర్మాణం - కానీ ప్రాంప్ట్ మోడల్ ఎంత ఆలోచించాలో సూచిస్తుంది. +"200 లో 15% ఏమిటి?" అనే సాదాసీదా ప్రశ్నను తక్కువ ఈగర్నెస్‌తో అడగండి. మీరు త్వరగా, ప్రత్యక్షమైన సమాధానాన్ని పొందుతారు. ఇప్పుడు "హై ట్రాఫిక్ API కోసం caching వ్యూహం రూపకల్పన చేయండి" అనే సంక్లిష్ట ప్రశ్నను ఎక్కువ ఈగర్నెస్‌తో అడగండి. **🔴 స్ట్రీమ్ రెస్పాన్స్ (లైవ్)** క్లిక్ చేసి మోడల్ విస్తృత ఆలోచనల్ని టోకెన్-బట్టి వీక్షించండి. అదే మోడల్, అదే ప్రశ్న నిర్మాణం - కానీ ప్రాంప్ట్ ఎవరికి ఎంత ఆలోచన చేయాలో చెప్పుతుంది. -### పని నిర్వహణ (ఇంస్ట్రుమెంటు ప్రవేశాలు) +### టాస్క్ ఎగ్జిక్యూషన్ (టూల్ ప్రీమేబుల్స్) -బహుళ దశల కార్య వ్యవహారాలకు ముందస్తు ప్రణాళిక మరియు పురోగతి వివరణలతో సహాయ పడుతుంది. మోడల్ ఏమి చేయనున్నదో వివరించి, ప్రతి దశను వివరిస్తుంది, తర్వాత ఫలితాలను సారాంశం చేస్తుంది. +బహుళ దశల వర్క్‌ఫ్లోలు ముందస్తు ప్రణాళిక మరియు పురోగతిని వివరించే విధానంతో లాభపడతాయి. మోడల్ ఏమి చేయబోతుందో వివరించి, ప్రతి దశను వివరిస్తూ, ఫలితాన్ని సారాంశం చేస్తుంది. -### స్వయంఆలోచిత కోడ్ +### స్వయం-ప్రతిబింబించే కోడ్ -"ఇమెయిల్ వాలిడ్ సర్వీస్ సృష్టించు" అని ప్రయత్నించండి. కేవలం కోడ్ సృష్టించి ఆపు చేయకుండా, మోడల్ సృష్టించి, నాణ్యత ప్రమాణాల ప్రకారం మూల్యాంకనం చేసి, బలహీనతలను గుర్తించి మెరుగుపరుస్తుంది. ప్రొడక్షన్ ప్రమాణాలు కలిగే వరకు మోడల్ పునరావృతం చూపిస్తుంది. +"ఈమెయిల్ నిర్ధారణ సేవను సృష్టించండి" అని ప్రయత్నించండి. కేవలం కోడ్ రూపొందించి ఆపకుండా, మోడల్ రూపొందించి, నాణ్యత ప్రమాణాలపై విలువలిచ్చి, లోపాలను గుర్తించి మెరుగుపరుస్తుంది. కోడ్ ఉత్పత్తి ప్రమాణాలకు సరిపోయే వరకు ఇది పునరావృతం చేయబడుతుంది. ### నిర్మిత విశ్లేషణ -కోడ్ సమీక్షలకి స్థిరమైన మూల్యాంకన పరిమాణాలు అవసరం. మోడల్ కోడ్ ను సరైన, ప్రాక్టీసులు, పనితీరు, భద్రత ఇలా వర్గీకరణలతో విశ్లేషిస్తుంది మరియు తీవ్రత స్థాయిలను చూపిస్తుంది. +కోడ్ సమీక్షలకు సुसంపన్నమైన మూల్యాంకన ఫ్రేమ్‌వర్క్‌లు అవసరం. మోడల్ స్థిరమైన వర్గాల (కరెక్ట్‌నెస్, ప్రాక్టీసెస్, పనితీరు, భద్రత)తో severity లెవల్స్‌తో కోడ్‌ని విశ్లేషిస్తుంది. -### బహుళ-ఇరణి చాట్ +### బహుళ-తిరుగు చాట్ -"Spring Boot అంటే ఏమిటి?" అని అడిగి, వెంటనే "ఉదాహరణ చూపు" అని అడగండి. మోడల్ మీ మొదటి ప్రశ్న గుర్తుంచుకొని ప్రత్యేకంగా Spring Boot ఉదాహరణ ఇస్తుంది. స్మృతి లేకపోతే, రెండవ ప్రశ్న చాలా అస్పష్టంగా ఉండిపోతుంది. +"Spring Boot ఏమిటి?" అని అడిగి వెంటనే "ఉదాహరణ చూపించు" అడగండి. మోడల్ మీ మొదటి ప్రశ్నను గుర్తుంచుకుని ప్రత్యేకంగా Spring Boot ఉదాహరణ ఇస్తుంది. మెమోరీ లేకపోతే, రెండవ ప్రశ్న చాలా అస్పష్టంగా ఉంటుంది. -### దశల వారీ తర్కాన్వೇಷణ +### దశలు-వారీ తార్కికత -గణిత సమస్య ఎంచుకుని దాన్ని దశల వారీ తర్కాన్వేషణ మరియు తక్కువ వేగస్థాయితో ప్రయత్నించండి. తక్కువ వేగం కేవలం సమాధానం సరళంగా ఇస్తుంది — వేగంగా కానీ अस्पष्टంగా. దశల వారీ విధానం ప్రతి గణన మరియు నిర్ణయాన్ని చూపిస్తుంది. +ఒక గణిత సమస్య ఎంచుకుని దశలు-వారీ తార్కికత మరియు తక్కువ ఈగర్నెస్‌తో ప్రయత్నించండి. తక్కువ ఈగర్నెస్ కేవలం సమాధానాన్ని త్వరగా ఇస్తుంది కానీ పరదాగా ఉంటుంది. దశలు-వారీ విధానం ప్రతి లెక్కింపు మరియు నిర్ణయాన్ని చూపిస్తుంది. -### నిర్బంధిత అవుట్‌పుట్ +### పరిమిత అవుట్‌పుట్ -నిర్దిష్ట ఫార్మాట్లు లేదా పదాల సంఖ్య అవసరమైతే, ఈ ప్యాటర్న్ కఠినంగా నియమాలను అమలుపరుస్తుంది. ఖచ్చితంగా 100 పదాలతో బుల్లెట్ పాయింట్ల రూపంలో ఒక సారాంశం సృష్టించండి. +మీకు నిర్దిష్ట ఫార్మాట్ లేదా పద గణన అవసరం ఉన్నప్పుడు, ఈ నమూనా కఠినంగా పాటించటానికి ఉద్దేశించబడింది. సరిగ్గా 100 పదాల సారాంశాన్ని బుల్లెట్ పాయింట్ ఫార్మాట్‌లో ఉత్పత్తి చేయడం ప్రయత్నించండి. -## మీరు నిజంగా నేర్చుకుంటున్నది +## మీరు నిజంగా ఏమి నేర్చుకుంటున్నారు -**తర్కప్రయత్నం ప్రతిదీ మార్చుతుంది** +**తార్కిక శ్రమలో మార్పులు** -GPT-5.2 మీరు ప్రాంప్ట్‌ల ద్వారా గణనాత్మక ప్రయత్నాన్ని నియంత్రించుకునేందుకు వీలు ఇస్తుంది. తక్కువ ప్రయత్నం అంటే తేలికగా స్పందనలు తక్కువ అన్వేషణతో. ఎక్కువ ప్రయత్నం అంటే మోడల్ లోతుగా ఆలోచించడానికి ఎక్కువ సమయం తీసుకుంటుంది. మీరు శ్రమను కార్యసాఫల్యానికి సరిపెట్టడం నేర్చుకుంటున్నారు - సాధారణ ప్రశ్నలకు సమయం వృథా చేయవద్దు, కానీ సంక్లిష్ట నిర్ణయాలను త్వరగా తీసుకోవడం లేదు. +GPT-5.2లో మీరు మీ ప్రాంప్ట్‌ల ద్వారా గణన శ్రమను నియంత్రించవచ్చు. తక్కువ శ్రమ అంటే తక్షణ స్పందనలు, తక్కువ అన్వేషణతో ఉంటాయి. ఎక్కువ శ్రమ అంటే మోడల్ లోతైన ఆలోచన కోసం సమయం తీసుకుంటుంది. మీరు శ్రమను పని జట్టు యొక్క సంకీర్ణతకు తగినట్టు సరిపెట్టడాన్ని నేర్చుకుంటున్నారు - సులభమైన ప్రశ్నలకు సమయాన్ని వృథా చేయవద్దు, కానీ సంక్లిష్ట నిర్ణయాలను కూడా త్వ‌రగా చేయకండి. -**నిర్మాణం ప్రవర్తనను మార్గదర్శనం చేస్తుంది** +**నిర్మాణం ప్రవర్తనను మార్గనిర్దేశం చేస్తుంది** -ప్రాంప్ట్‌లలో XML ట్యాగ్లను గమనించారా? అవి అలంకారమే కావు. మోడల్స్ నిర్మిత ఆదేశాలను ఫ్రీఫార్మ్ టెక్స్ట్ కంటే సక్రమంగా అనుసరిస్తాయి. బహుళ దశల ప్రక్రియలు లేదా సంక్లిష్ట తర్కం అవసరమైనప్పుడు, నిర్మాణం మోడల్ ఎక్కడ ఉన్నదో, తదుపరి ఏమి చేయాలో ట్రాక్ చేయడంలో సహాయపడుతుంది. క్రింది చిత్రం బాగా నిర్మిత ప్రాంప్ట్ ను విభజించి, ``, ``, ``, ``, `` లాంటి ట్యాగ్లు మీ ఆదేశాలను స్పష్టమైన విభాగాలుగా ఎలా నిర్వహిస్తాయో చూపిస్తుంది. +ప్రాంప్ట్‌లలో XML ట్యాగ్‌లు బట్టి గమనించారా? అవి అలంకారంగా కాదు. మోడల్స్ నిర్మిత సూచనలను స్వతంత్ర వచన కంటే ఎక్కువ విశ్వసనీయంగా అనుసరిస్తాయి. మీరు బహుళ దశల ప్రక్రియలు లేదా సంక్లిష్ట తార్కికత అవసరమైతే, నిర్మాణం మోడల్ ఏ దశలో ఉందో, తర్వాత ఏమి చేయాలో పర్యవేక్షిస్తుంది. క్రింద డయాగ్రామ్ ఒక బాగా నిర్మిత ప్రాంప్ట్‌ను విభజిస్తుంది, ``, ``, ``, ``, మరియు `` వంటి ట్యాగ్‌లు మీ సూచనలను స్పష్టమైన విభాగాలుగా అమర్చడాన్ని చూపిస్తుంది. ప్రాంప్ట్ నిర్మాణం -*స్పష్ట విభాగాలతో, XML శైలి సంస్కరణతో బాగా నిర్మిత ప్రాంప్ట్ యొక్క శరీరం* +*స్పష్ట విభాగాలు మరియు XML శైలి వ్యవస్థతో బాగా నిర్మిత ప్రాంప్ట్ శరీరం* -**ఆత్మ మూల్యాంకనం ద్వారా నాణ్యత** +**నాణ్యత స్వీయ-మూల్యాంకన ద్వారా** -స్వయంఆలోచన ప్యాటర్న్‌లు నాణ్యత ప్రమాణాలను స్పష్టంగా అందించడం ద్వారా పనిచేస్తాయి. మోడల్ "సరైన పని చేస్తుందని" ఆశించడానికి బదులు మీరు "సరైన" అంటే ఏమిటో చెబుతారు: సరైన తర్కం, లోపాల నిర్వహణ, పనితీరు, భద్రత. దీని ద్వారా మోడల్ తన ఉత్పత్తిని మూల్యాంకనం చేసి మెరుగుపరచగలదు. ఇది కోడ్ జనరేషన్‌ని లాటరీ నుంచి ప్రక్రియగా మార్చుతుంది. +స్వయం-ప్రతిబింబించే నమూనాలు నాణ్యత ప్రమాణాలను స్పష్టంగా చేస్తాయి. మోడల్ "సరైనదే చేస్తుంది" అని ఆశించకుండా, మీరు "సరైనది" అంటే ఏమిటో: సరైన తార్కికత, లోపాల నిర్వహణ, పనితీరు, భద్రత అని ఖచ్చితంగా చెప్పగలరు. అప్పుడు మోడల్ తానే తన అవుట్‌పుట్‌ను మూల్యాంకనం చేసి మెరుగుపరచగలదు. ఇది కోడ్ జనరేషన్‌ను లాటరీ నుండి ఒక ప్రక్రియగా మార్చుతుంది. -**సందర్భం పరిమితం** +**సందర్భం పరిమితమైనది** -బహుళ-ఇరణి సంభాషణలు ప్రతి అభ్యర్థనకు సందేశ చరిత్రను జోడించడం ద్వారా పనిచేస్తాయి. కానీ పరిమితి ఉంటుంది - ప్రతి మోడల్ కు గరిష్ఠ టోకెన్ సంఖ్యా పరిమితి ఉంటుంది. సంభాషణలు పెరిగేకొద్దీ మీరు సంబంధిత సందర్భాన్ని పటిష్టంగా ఉంచే వ్యూహాలు నేర్చుకోవాలి, అర్థం చేసుకోవడం అవసరం ఏమిటంటే ఎప్పుడూ సారాంశం చేయాలో, ఎప్పుడూ మరవాలో, ఎప్పుడూ తిరిగి తీసుకోవాలో. ఈ మాడ్యూల్ మేమరీ ఎలా పని చేస్తుందో చూపిస్తుంది; తరువాత మీరు ఈ వ్యూహాలను నేర్చుకుంటారు. +బహుళ-తిరుగు సంభాషణలు ప్రతి అభ్యర్థనతో సందేశ చరిత్రను కలుస్తాయి. కానీ పరిమితి ఉంటుంది - ప్రతి మోడల్‌కు గరిష్ట టోకెన్ సంఖ్య. సంభాషణ పెరిగితే, సంబంధిత సందర్భాన్ని గరిష్టాన్ని దాటకుండా ఉంచడానికి వ్యూహాలు అవసరం. ఈ మాడ్యూల్ మీరు మెమొరీ ఎలా పనిచేస్తుందో చూపిస్తుంది; తర్వాత మీరు సారాంశం ఎప్పుడు చేయాలో, మర్చిపోవాలి ఎప్పుడు, మరియు పునఃప్రాప్తి ఎప్పుడు చేయాలో నేర్చుకుంటారు. -## తదుపరి దశలు +## తదుపరి అడుగులు **తదుపరి మాడ్యూల్:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**నావిగేషన్:** [← మునుపటి: Module 01 - పరిచయం](../01-introduction/README.md) | [ప్రధానానికి తిరుగు](../README.md) | [తదుపరి: Module 03 - RAG →](../03-rag/README.md) +**నావిగేషన్:** [← మునుపటి: మాడ్యూల్ 01 - పరిచయం](../01-introduction/README.md) | [ప్రధానానికి తిరుగు](../README.md) | [తదుపరి: మాడ్యూల్ 03 - RAG →](../03-rag/README.md) --- -**అస్పష్టత**: -ఈ డాక్యుమెంట్‌ను AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తుంటేనూ, స్వయంచాలక అనువాదాలలో పొరుపులు లేదా తప్పిదాలు ఉండవచ్చు అని దయచేసి గమనించండి. మూల భాషలో ఉన్న అసలు డాక్యుమెంట్‌ను అధికారిక स्त्रोतంగా పరిగణించాలి. అత్యంత ముఖ్యమైన సమాచారం కోసం, ప్రొఫెషనల్ మానవ అనువాదం సిఫార్సు చేయబడుతుంది. ఈ అనువాదం వాడకం వల్ల కలిగే ఏవైనా అవగాహన లోపాలు లేదా తప్పైన అర్థాలను గురించి మేము బాధ్యత వహించము. +**అస్వీకరణ**: +ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటెడ్ అనువాదాలు తప్పులు లేదా అసమగ్రతలను కలిగి ఉండవచ్చు. దాని స్వదేశ భాషలో ఉన్న అసలు పత్రాన్ని అధికారం కలిగిన మూలంగా పరిగణించాలి. కీలకమైన సమాచారం కోసం, ప్రొఫెషనల్ మానవ అనువాదాన్ని సిఫారసు చేస్తాము. ఈ అనువాదం ఉపయోగం వల్ల కలిగే ఏవైనా అపార్థాలు లేదా తప్పుదారులు కోసం మేము బాధ్యత వహించము. \ No newline at end of file diff --git a/translations/te/03-rag/README.md b/translations/te/03-rag/README.md index c03e645c2..b56a28b24 100644 --- a/translations/te/03-rag/README.md +++ b/translations/te/03-rag/README.md @@ -1,144 +1,145 @@ -# మాడ్యూల్ 03: RAG (రిట్రివల్-ఆగ్మెంటెడ్ జనరేషన్) - -## కంటెంట్ పట్టిక - -- [వీడియో వాక్‌త్రూ](../../../03-rag) -- [మీరు నేర్చుకునే విషయాలు](../../../03-rag) -- [పూర్వష్టాపనలు](../../../03-rag) -- [RAG ను అర్థం చేసుకోవడం](../../../03-rag) - - [ఈ ట్యుటోరియల్ ఏ RAG దృక్పథాన్ని ఉపయోగిస్తుంది?](../../../03-rag) -- [ఇది ఎలా పనిచేస్తుంది](../../../03-rag) - - [డాక్యుమెంట్ ప్రాసెసింగ్](../../../03-rag) - - [ఎంబెడ్డింగ్స్ సృష్టించడం](../../../03-rag) - - [సెమాంటిక్ సర్చ్](../../../03-rag) - - [జవాబు జనరేషన్](../../../03-rag) -- [అప్లికేషన్ నడపడం](../../../03-rag) -- [అప్లికేషన్ ఉపయోగించడం](../../../03-rag) - - [డాక్యుమెంట్ అప్‌లోడ్ చేయడం](../../../03-rag) - - [ప్రశ్నలు అడగడం](../../../03-rag) - - [సూచీ ఆధారాలు తనిఖీ చేయడం](../../../03-rag) - - [ప్రశ్నలతో ప్రయోగం చేయడం](../../../03-rag) -- [ప్రధాన భావనలు](../../../03-rag) - - [చంకింగ్ వ్యూహం](../../../03-rag) - - [సారూప్యత స్కోర్లు](../../../03-rag) - - [ఇన్-మెమరీ నిల్వ](../../../03-rag) - - [సందర్భం విండో నిర్వహణ](../../../03-rag) -- [RAG అవసరం ఉన్నప్పుడు](../../../03-rag) -- [తదుపరి దశలు](../../../03-rag) - -## వీడియో వాక్‌త్రూ - -ఈ మాడ్యూల్ ఎలా ప్రారంభించాలో వివరించే లైవ్ సెషన్‌ను వీక్షించండి: +# Module 03: RAG (Retrieval-Augmented Generation) + +## Table of Contents + +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding RAG](#understanding-rag) + - [Which RAG Approach Does This Tutorial Use?](#which-rag-approach-does-this-tutorial-use) +- [How It Works](#how-it-works) + - [Document Processing](#document-processing) + - [Creating Embeddings](#creating-embeddings) + - [Semantic Search](#semantic-search) + - [Answer Generation](#సమాధాన-ఉత్పత్తి) +- [Run the Application](#దరఖాస్తును-నడపండి) +- [Using the Application](#అప్లికేషన్‌ను-ఉపయోగించడం) + - [Upload a Document](#డాక్యుమెంటు-అప్లోడ్-చేయండి) + - [Ask Questions](#ప్రశ్నలు-అడగండి) + - [Check Source References](#మూల-సూచనలను-తనిఖీ-చేయండి) + - [Experiment with Questions](#ప్రశ్నలతో-ప్రయోగించండి) +- [Key Concepts](#ముఖ్య-భావనలు) + - [Chunking Strategy](#భాగాల-కట్టడం-వ్యూహం) + - [Similarity Scores](#సాదృశ్య-స్కోర్లు) + - [In-Memory Storage](#ఇన్-మెమరీ-స్టోరేజ్) + - [Context Window Management](#కాంటెక్స్ట్-విండి-నిర్వహణ) +- [When RAG Matters](#ఎప్పుడు-rag-ఉపయోగించాలి) +- [Next Steps](#తదుపరి-దశలు) + +## Video Walkthrough + +ఈ మాడ్యూల్‌తో ఎలా ప్రారంభం చేయాలో వివరిస్తున్న ఈ లైవ్ సెషన్‌ను చూడండి: RAG with LangChain4j - Live Session -## మీరు నేర్చుకునే విషయాలు +## What You'll Learn -మునుపటి మాడ్యూల్స్‌లో, మీరు AIతో ఎలా సంభాషించాలి మరియు మీ ప్రాంప్ట్‌లను సమర్థంగా నిర్మించాలి అనేదాన్ని నేర్చుకున్నారు. కానీ ఒక ప్రాథమిక పరిమితి ఉంది: భాషా నమూనాలు శిక్షణ సమయంలో నేర్చుకున్న దానిని మాత్రమే తెలుసుకుంటాయి. అవి మీ సంస్థ విధానాలు, మీ ప్రాజెక్ట్ డాక్యుమెంటేషన్, లేదా అవి శిక్షణ పొందని ఏమైనా సమాచారం గురించి ప్రశ్నలకు సమాధానం ఇవ్వలేవు. +మునుపటి మాడ్యూల్‌లలో, మీరు AIతో సంభాషణలు ఎలా చేసుకోవాలో, మరియు మీ ప్రాంప్‌లను సక్రమంగా ఎలా నిర్మించాలో నేర్చుకున్నారు. కానీ ఒక ప్రాథమిక పరిమితి ఉంది: భాషా మోడళ్లు కేవలం శిక్షణ సమయంలో నేర్చుకున్న విషయం మాత్రమే తెలుసుకుంటాయి. అవి మీ కంపెనీ పాలసీల గురించి, మీ ప్రాజెక్ట్ డాక్యుమెంటేషన్ గురించి, లేదా శిక్షణ చేయని ఏ సమాచారంపై ప్రశ్నలకు జవాబులు ఇవ్వలేవు. -RAG (రిట్రివల్-ఆగ్మెంటెడ్ జనరేషన్) ఈ సమస్యను పరిష్కరిస్తుంది. నమూనాకు మీ సమాచారాన్ని బోధించడానికి (ఏదైనా ఖరీదైన మరియు ప్రయోజనరహితమైన విషయం) ప్రయత్నించకుండా, మీరు దానిని మీ డాక్యుమెంట్లలో శోధన చేయగలిగే సామర్థ్యాన్ని ఇస్తారు. ఎవరైనా ప్రశ్న అడుగితే, సిస్టమ్ సంబంధిత సమాచారాన్ని కనుగొని ప్రాంప్ట్‌లో చేర్చుతుంది. ఆపై నమూనా ఆ తెచ్చిన సందర్భాన్ని ఆధారంగా సమాధానం ఇస్తుంది. +RAG (Retrieval-Augmented Generation) ఈ సమస్యను పరిష్కరిస్తుంది. మోడల్తో మీ సమాచారాన్ని నేర్పించడానికి ప్రయత్నించడం (అది ఖర్చుతో కూడుకున్నది మరియు సూచించదగినది కాదు) బదులు, మీరు దానికి మీ డాక్యుమెంటులను శోధించే సామర్థ్యాన్ని ఇస్తారు. ఎవరైనా ప్రశ్న అడిగినప్పుడు, వ్యవస్థ సంబంధిత సమాచారాన్ని కనుగొంటుంది మరియు దానిని ప్రాంప్ట్‌లో చేర్చుతుంది. ఆ తరువాత మోడల్ ఆ తీసుకున్న సందర్భాన్ని ఆధారంగా జవాబు ఇస్తుంది. -RAG ను నమూనాకు ఒక సూచిక గ్రంధాలయం ఇచ్చినట్టు భావించండి. మీరు ఒక ప్రశ్న అడిగితే, సిస్టమ్: +RAGని మోడల్‌కు ఒక సూచనలు లైబ్రరీ ఇచ్చినట్లుగా நினைத்தుకోండి. మీరు ప్రశ్న అడిగినప్పుడు, వ్యవస్థ: -1. **వాడుకరి ప్రశ్న** - మీరు ఒక ప్రశ్న అడుగుతారు -2. **ఎమ్బెడ్డింగ్** - మీ ప్రశ్నను ఒక వెక్టర్‌గా మార్చుతుంది -3. **వెక్టర్ సర్చ్** - సమానం ఉన్న డాక్యుమెంట్ చంక్‌లను వెతుకుతుంది -4. **సందర్భం సమీకరణ** - సంబంధిత చంక్‌లను ప్రాంప్ట్‌కి జత చేస్తుంది -5. **స్పందన** - LLM ఆ సందర్భాన్ని ఆధారంగా సమాధానం ఉత్పత్తి చేస్తుంది +1. **వాడుకరి ప్రశ్న** - మీరు ప్రశ్న అడుగుతారు +2. **ఎంబెడ్డింగ్** - మీ ప్రశ్నను ఒక వెక్టర్‌గా మారుస్తుంది +3. **వెక్టర్ శోధన** - సమానమైన డాక్యుమెంట్ భాగాలను కనుగొంటుంది +4. **సందర్భం సమాహరణ** - సంబంధిత భాగాలను ప్రాంప్ట్‌కు చేర్చుతుంది +5. **జవాబు** - LLM సం‍దర్భాన్ని ఆధారంగా జవాబు తయారుచేస్తుంది -ఇది నమూనా యొక్క ప్రతిస్పందనలను దాని శిక్షణ జ్ఞానంపై ఆధారపడకుండా మీ వాస్తవ డేటాలో ఉన్నదిగా నిర్ధారిస్తుంది. +ఇది మోడల్ యొక్క ప్రతిస్పందనలను మీరు కలిగించిన డేటాపై ఆధారపడి ఉండేలా చేస్తుంది, శిక్షణ జ్ఞానంపై ఆధారపడకుండా లేదా జవాబులు ఊహించకుండా. -## పూర్వష్టాపనలు +## Prerequisites -- [Module 00 - Quick Start](../00-quick-start/README.md) పూర్తి చేసుకున్న స్వీయం (ఈ మాడ్యూల్ వద్ద సూచించిన సులభ RAG ఉదాహరణకోసం) -- [Module 01 - Introduction](../01-introduction/README.md) పూర్తి చేసుకున్న స్వీయం (Azure OpenAI వనరులు మాజబడినవి, ఇందులో `text-embedding-3-small` ఎంబెడ్డింగ్ మోడల్ ఉంటుంది) -- మూల డైరెక్టరీలో `.env` ఫైల్ Azure గుర్తింపు సమాచారంతో (Module 01 లో `azd up` ద్వారా సృష్టించబడింది) +- [Module 01 - పరిచయం](../01-introduction/README.md) పూర్తి చేశారా (Azure OpenAI వనరులు అమర్చబడ్డాయి, అందులో `text-embedding-3-small` embedding మోడల్ కూడా ఉన్నది) +- రూట్ డైరెక్టరీలో `.env` ఫైల్ ఉండాలి, Azure క్రెడెన్షియల్స్‌తో (Module 01లో `azd up` ద్వారా రూపొందించబడింది) -> **గమనిక:** మీరు Module 01 పూర్తి చేయకపోతే, ముందుగా అక్కడి ప్రదర్శన సూచనలను అనుసరించండి. `azd up` కమెండ్ GPT చాట్ మోడల్ మరియు ఈ మాడ్యూల్ ఉపయోగించే ఎంబెడ్డింగ్ మోడల్ రెండింటినీ మాజుతుంది. +> **గమనిక:** మీరు Module 01 పూర్తి చేయకపోతే, ముందుగా అక్కడని అమర్తనం సూచనలను అనుసరించండి. `azd up` ఆజ్ఞ GPT చాట్ మోడల్ మరియు ఈ మాడ్యూల్ ఉపయోగించే embedding మోడల్ రెండింటినీ అమర్చుతుంది. -## RAG ఆలోచనను అర్థం చేసుకోవడం +## Understanding RAG -కింది జీవ గRAFిక్ మూల చదువులో స్పష్టం చేస్తుంది: నమూనా శిక్షణ డేటాపై మాత్రమే ఆధారపడకుండా, RAG దానికి మీ డాక్యుమెంట్ల సూచిక గ్రంధాలయాన్ని ఇస్తుంది, దాని మీద ఆధారపడి ప్రతి జవాబు రూపొందించే ముందు సంప్రదిస్తుంది. +కింది చిత్రరూపం మూల భావనను చూపిస్తుంది: మోడల్ యొక్క శిక్షణ డేటాపై మాత్రమే ఆధారపడకుండా, RAG దానికి మీ డాక్యుమెంటుల సూచనలు లైబ్రరీని ఇస్తుంది, ప్రతిస్పందన రూపొందించే ముందు ఆ డాక్యుమెంటులను సంప్రదించడానికి. What is RAG -*ఈ చిత్రం ఒక సాధారణ LLM (శిక్షణ డేటాపై ఊహించే) మరియు RAG-అన్‌హాన్స్డ్ LLM (మీ డాక్యుమెంట్లతో ముందుగా సంప్రదించే) మధ్య తేడాను చూపుతుంది.* +*ఈ చిత్రంలో సాధారణ LLM (శిక్షణ డేటా నుంచి అంచనా వేసే) మరియు RAG-సహాయపడిన LLM (ముందుగా మీ డాక్యుమెంటులను సంప్రదించే) మధ్య తేడాను చూపిస్తుంది.* -ఇక్కడ భాగాలు ఎండ్-టు-ఎండ్ ఎలా కनेक్ట్ అవుతాయన్నది: వాడుకరి ప్రశ్న నాలుగు దశల గుండా ప్రవహిస్తుంది – ఎంబెడ్డింగ్, వెక్టర్ శోధన, సందర్భం సమీకరణ, మరియు జవాబు జనరేషన్ – ప్రతి దశ మునుపటి దానిపై ఆధారపడి రూపొందుతుంది: +ఇక్కడ అన్ని భాగాలు ఎలా కలిసి పనిచేస్తాయో పూర్తి ప్రవాహం: వాడుకరి ప్రశ్న నాలుగు దశల ద్వారా ప్రవహిస్తుంది — ఎంబెడ్డింగ్, వెక్టర్ శోధన, సం‍దర్భం సమాహరణ, మరియు జవాబు సృష్టి — ప్రతి దశ ముందు దశపై ఆధారపడి ఉంటుంది: RAG Architecture -*ఈ చిత్రం ఎండ్-టు-ఎండ్ RAG పైపు‌లైన్ చూపిస్తుంది — వాడుకరి ప్రశ్న ఎంబెడ్డింగ్, వెక్టర్ శోధన, సందర్భం సమీకరణ, మరియు జవాబు జనరేషన్ ద్వారా ప్రవహిస్తుంది.* +*ఈ చిత్రంలో RAG పైప్‌లైన్ చివర వరకూ — వాడుకరి ప్రశ్న ఎంబెడ్డింగ్, వెక్టర్ శోధన, సం‍దర్భం సమాహరణ, మరియు జవాబు సృష్టి ద్వారా ప్రవహిస్తుంది.* -ఈ మాడ్యూల్ మిగతా భాగం ప్రతి దశను వివరంగా, మీరు పరిగణించగల మరియు సవరించగల కోడ్‌తో పాటు పై ఇచ్చిన గ్రాఫిక్స్‌తో వివరిస్తుంది. +మిగతా ఈ మాడ్యూల్ అన్ని దశల్ని వివరంగా, మీరు రన్ చేసి మార్చుకోవచ్చునన్ని కోడ్‌తో చూపిస్తుంది. -### ఈ ట్యుటోరియల్ ఏ RAG దృక్పథాన్ని ఉపయోగిస్తుంది? +### Which RAG Approach Does This Tutorial Use? -LangChain4j RAG ను అమలు చేయడానికి మూడు మార్గాలు అందిస్తుంది, ప్రతి దృక్పథం విభిన్న స్థాయిల వాస్తవికత కలిగి ఉంటుంది. కింది చిత్రం వాటిని పక్కపక్కన పోల్చుతుంది: +LangChain4j RAGని అమలు చేయడానికి మూడు విధానాలను అందిస్తుంది, వాటిలో ప్రతి ఒకటికి వేరే మామడ్పు స్థాయి ఉంటుంది. కింది చిత్రంలో వాటిని ఒకరి పక్కదారి చూపబడింది: Three RAG Approaches in LangChain4j -*ఈ చిత్రం మూడు LangChain4j RAG దృక్పథాలను – సులభమైన, మౌలిక(native), మరియు అభివృద్ధి చెందిన – ముఖ్య భాగాలతో మరియు ఉపయోగించే సందర్భాలతో పోల్చుతుంది.* +*ఈ చిత్రంలో మూడు LangChain4j RAG విధానాలను — సులభతరం (Easy), స్థానిక (Native), మరియు ప్రగతిషీల (Advanced) — వాటి ముఖ్యమైన భాగాలతో మరియు ఉపయోగిస్తే ఎప్పుడు అనేది చూపిస్తుంది.* -| దృక్పథం | ఇది ఏమి చేస్తుంది | వ్యతిరేకం | +| విధానం | అది ఏం చేస్తుంది | వ్యత్యాసం | |---|---|---| -| **సులభ RAG** | `AiServices` మరియు `ContentRetriever` ద్వారా అన్ని వాటిని ఆటోమేటిక్ గా వైర్ చేస్తుంది. మీరు ఇంటర్‌ఫేస్‌ను.annotate చేసి, రిట్రీవర్ జత చేయండి, తర్వాత LangChain4j ఎంబెడ్డింగ్, శోధన, ప్రాంప్ట్ అసెంబ్లీ తిరుగుతుంది. | లేని కోడ్, కానీ ప్రతీ దశలో ఏమి జరుగుతుందో చూడలేరు. | -| **మౌలిక RAG** | మీరు ఎంబెడ్డింగ్ మోడల్‌ను పిలుస్తారు, స్టోర్.Search చేస్తారు, ప్రాంప్ట్ నిర్మిస్తారు, మరియు స్వయంగా జవాబు ఉత్పత్తి చేస్తారు—ప్రతి క్రమానుగుణ దశను వ్యక్తంగా పిలుస్తారు. | ఎక్కువ కోడ్, కాని ప్రతి దశ కనిపిస్తుంది మరియు మార్చకూడదు. | -| **అభివృద్ధి చెందిన RAG** | `RetrievalAugmentor` ఫ్రేమ్‌వర్క్‌ను ఉపయోగించి ప్రశ్న ట్రాన్స్‌ఫార్మర్స్, రౌటర్లు, రీ-రేంకర్లు, కంటెంట్ ఇంజెక్టర్లతో ప్రొడక్షన్-గ్రేడ్ పైపు‌లైన్ల కోసం ఉపయోగిస్తారు. | గరిష్ట సరళత, కానీ గణనీయమైన సంకీర్ణత. | +| **సులభ RAG (Easy RAG)** | `AiServices` మరియు `ContentRetriever` ద్వారా అన్నీ ఆటోమాటిక్‌గా వైర్డ్ అవుతాయి. మీరు ఒక ఇంటర్‌ఫేస్‌ను అన్నొటేట్ చేసి, రీట్రైవర్‌ను జత చేస్తారు, మరియు LangChain4j ఎంబెడ్డింగ్, శోధన, మరియు ప్రాంప్ట్ సమాహరణను హ్యాండిల్ చేస్తుంది. | కనీసం కోడ్, కానీ ప్రతీ దశలో ఏం జరుగుతుందో మీరు చూడలేరి. | +| **స్థానిక RAG (Native RAG)** | మీరు embedding మోడల్‌ను పిలిచి, స్టోర్‌ను శోధించి, ప్రాంప్ట్‌ను నిర్మించి, జవాబు సృష్టి చేస్తారు — ఒక్క దశ ఒక్కసారి స్పష్టంగా. | ఎక్కువ కోడ్, కానీ ప్రతీ దశ కనిపిస్తుంది మరియు సవరించబడవచ్చు. | +| **ప్రగతిషీల RAG (Advanced RAG)** | `RetrievalAugmentor` ఫ్రేమ్‌వర్క్ ఉపయోగించి, క్వెరీ ట్రాన్స్‌ఫార్మర్స్, రూటర్స్, రీ-రాంకర్స్, మరియు కంటెంట్ ఇంజెక్టర్లతో ప్రొడక్షన్-గ్రేడ్ పైప్‌లైన్‌ల కోసం. | గరిష్ట నమ్యతరం, కాప్లెక్స్ ఎక్కువగా. | -**ఈ ట్యుటోరియల్ మౌలిక దృక్పథాన్ని ఉపయోగిస్తుంది.** RAG పైపు‌లైన్ యొక్క ప్రతి దశ — ప్రశ్నను ఎంబెడ్ చేయడం, వెక్టర్ స్టోర్ శోధించడం, సందర్భం అసెంబ్లీ చేయడం, మరియు జవాబు ఉత్పత్తి చేయడం — [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) లో స్పష్టంగా రాసారు. ఇది ఉద్దేశపూర్వకం: ఒక నేర్చుకునే వనరుగా, మీరు ప్రతి దశను చూడడం మరియు అర్థం చేసుకోవడం చాలా ముఖ్యం, కేవలం కోడ్ తక్కువగా ఉండటం కంటే. మీరు భాగాలు ఎలా అనుసంధానం అవుతాయో తెలుసుకున్న తర్వాత, సులభ RAG కి వెళ్లడం లేదా ఉత్పత్తి వ్యవస్థల కోసం అభివృద్ధి చెందిన RAG ఉపయోగించవచ్చు. +**ఈ ట్యుటోరియల్ స్థానిక (Native) విధానాన్ని ఉపయోగిస్తుంది.** RAG పైప్‌లైన్‌లో ప్రతీ దశ — ప్రశ్న embedding, వెక్టర్ స్టోర్ శోధన, సం‍దర్భం సమాహరణ, మరియు జవాబు సృష్టి — [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) లో స్పష్టంగా రాయబడ్డాయి. ఇది ఉద్దేశపూర్వకంగా చేయబడింది: ఒక నేర్చుకునే వనరు గా, మీకు ప్రతి దశను చూడటం మరియు అర్థం చేసుకోవడం మరింత ముఖ్యం, కోడ్‌ను తగ్గించడం కన్నా. మీరు భాగాలు ఎలా జతైనాయో సద్విగా అవగాహన పొందిన తర్వాత, సులభ RAG లేదా ప్రగతిషీల RAG వైపున మీరు మారవచ్చు. -> **💡 సులభ RAG ఇప్పటికే చూసారా?** [Quick Start module](../00-quick-start/README.md) లో ఒక Document Q&A ఉదాహరణ ఉంటుంది ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), ఇది సులభ RAG దృక్పథాన్ని ఉపయోగిస్తుంది — LangChain4j ఎంబెడ్డింగ్, శోధన, మరియు ప్రాంప్ట్ అసెంబ్లీను ఆటోమేటిక్ గా నిర్వహిస్తుంది. ఈ మాడ్యూల్ ఆ పైపు‌లైన్‌ను తెరవడం ద్వారా ప్రతి దశను మీరు చూడగలుగుతారు మరియు నియంత్రణలో ఉంచగలుగుతారు. +> **💡 సులభ RAG గురించి ఆసక్తిగా ఉన్నారా?** LangChain4j లో మరో *సులభ RAG* విధానం ఉంది, ఇక్కడ `AiServices` మరియు `ContentRetriever` embedding, శోధన, మరియు ప్రాంప్ట్ సమాహరణను ఆటోమాటిక్‌గా నిర్వహిస్తాయి. ఈ మాడ్యూల్ స్పష్టమైన దారిని తీసుకుంది — ఆ పైప్‌లైన్‌ను విరించి ప్రతీ దశ తనిఖీ మరియు నియంత్రణకి యోగ్యంగా ఉంచడం. -కింది చిత్రంలో ఆ Quick Start ఉదాహరణ నుండి సులభ RAG పైపు‌లైన్ చూపించబడింది. `AiServices` మరియు `EmbeddingStoreContentRetriever` సాంక్లిష్టతను ఎలా മറుపరుస్తాయో గమనించండి — మీరు డాక్యుమెంట్ లోడ్ చేస్తారు, రిట్రీవర్ జత చేస్తారు, ఇంకా సమాధానాలు పొందుతారు. ఈ మాడ్యూల్‌లోని మౌలిక దృక్పథం ఆ దొరుకని దశలను తెరుస్తుంది: +కింది చిత్రం సులభ RAG పైప్‌లైన్‌ను చూపిస్తుంది. గమనించండి `AiServices` మరియు `EmbeddingStoreContentRetriever` అన్ని క్లిష్టతలను ఎలా దాచేస్తున్నారో — మీరు ఒక డాక్యుమెంట్‌ ని లోడ్ చేసి, రీట్రైవర్ జత చేసి, జవాబులు పొందుతారు. ఈ మాడ్యూల్‌లో ఉపయోగిస్తున్న స్థానిక విధానము ఆ దాచిన దశలను విరుస్తుంది: Easy RAG Pipeline - LangChain4j -*ఈ చిత్రం `SimpleReaderDemo.java` నుండి సులభ RAG పైపు‌లైన్ చూపిస్తుంది. ఈ మాడ్యూల్ ఉపయోగించే మౌలిక దృక్పథంతో పోల్చండి: సులభ RAG `AiServices` మరియు `ContentRetriever` క్రింద ఎంబెడ్డింగ్, రిట్రీవల్, మరియు ప్రాంప్ట్ అసెంబ్లీని కవర్ చేస్తుంది — మీరు డాక్యుమెంట్ లోడ్ చేసి, రిట్రీవర్ జత చేసి సమాధానాలు పొందతారు. ఈ మాడ్యూల్‌లోని మౌలిక దృక్పథం ఆ పైపు‌లైన్‌ను తెరవడం ద్వారా మీరు ప్రతి దశను పిలవగలుగుతారు, పూర్తి దృశ్యమానత మరియు నియంత్రణ పొందుతారు.* +*ఈ చిత్రం సులభ RAG పైప్‌లైన్‌ని చూపిస్తోంది. ఈ మాడ్యూల్ లో ఉపయోగించే స్థానిక విధానంతో పోల్చండి: సులభ RAG embedding, retrieval, మరియు prompt assemblyని `AiServices` మరియు `ContentRetriever` వెనువైపు దాచుతుంది — మీరు డాక్యుమెంట్ లోడ్ చేసి, రీట్రైవర్ జత చేసి, జవాబులు పొందుతారు. స్థానిక విధానం ఆ పైప్‌లైన్‌ను విరించి, మీరు ప్రతీ దశ (embed, search, assemble context, generate)ను స్వయంగా పిలవడానికి, పూర్తి దృశ్యత మరియు నియంత్రణ ఇవ్వటానికి అనుకూలంగా ఉంటుంది.* -## ఇది ఎలా పనిచేస్తుంది +## How It Works -ఈ మాడ్యూల్‌లో RAG పైపు‌లైన్ నాలుగు దశలుగా విభజించబడింది, ఇది ప్రతి సారి ఒక వాడుకరి ప్రశ్న అడిగినప్పుడు క్రమంగా నడుస్తుంది. మొదట, అప్‌లోడ్ చేసిన డాక్యుమెంట్‌ను **పార్స్ చేసి చంక్‌లుగా విభజిస్తారు**. ఆ చంక్‌లు తర్వాత **వెక్టర్ ఎంబెడ్డింగ్స్** గా మార్పిడి చేయబడి నిల్వ చేయబడతాయి, వీటిని గణితపరంగా సరిపోల్చవచ్చు. ఒక ప్రశ్న వచ్చినప్పుడు, సిస్టమ్ **సెమాంటిక్ శోధన** చేస్తుంది సంబంధిత చంక్‌లను కనుగొనడానికి, చివరగా వాటిని సందర్భంగా LLMకు **జవాబు ఉత్పత్తి** కోసం పంపుతుంది. క్రింది విభాగాలు ప్రతి దశను అసలు కోడ్ మరియు గRAFిక్స్‌తో వివరంగా చూపిస్తాయి. మొదటి దశను చూద్దాం. +ఈ మాడ్యూల్‌లో RAG పైప్‌లైన్ ప్రతి సారి వాడుకరి ప్రశ్న అడిగినప్పుడు నాలుగు దశలుగా అమలు అవుతుంది. మొదట, అప్‌లోడ్ చేసిన డాక్యుమెంట్ **పార్స్ చేసి చంక్స్‌గా విభజించబడుతుంది** — మోడల్ యొక్క సదుపయోగ విండోలో సౌకర్యవంతంగా సరిపోయే ఒక చిన్న భాగాలుగా. ఆ భాగాలు కొంతమేర ఒకదానితో పాటు పొడవుగా ఉంటాయి, అందువల్ల సరిహద్దుల్లో సం‍దర్భం కోల్పోకూడదు. -### డాక్యుమెంట్ ప్రాసెసింగ్ +తర్వాత ఆ చంక్‌లు **వెక్టర్ ఎంబెడ్డింగ్స్‌గా** మార్పు చెయ్యబడతాయి మరియు గణితపరంగా పోల్చుకునేలా నిల్వ చేయబడతాయి. ప్రశ్న వచ్చినప్పుడు, వ్యవస్థ **సెమెంటిక్ శోధన** (అర్ధం ఆధారిత శోధన) చేస్తుంది సంబంధిత భాగాలను కనుగొనడానికి, చివరగా ఆ భాగాలను సం‍దర్భంగా LLMకి పాసు చేసి **జవాబు సృష్టి** జరుగుతుంది. కింది విభాగాలు ప్రతి దశను ప్రత్యక్ష కోడ్ మరియు చిత్రాలతో వివరించి చూపిస్తాయి. మొదటి దశను చూద్దాం. + +### Document Processing [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -మీరు ఒక డాక్యుమెంట్ అప్‌లోడ్ చేసినప్పుడు, సిస్టమ్ దాన్ని (PDF లేదా సాధారణ పాఠ్యం) పార్స్ చేసి, ఫైల్ పేరు వంటి మెటాడేటాను జత చేస్తుంది, తర్వాత చిన్న భాగాలుగా విభజిస్తుంది — నమూనా యొక్క సందర్భ విండోలో సులభంగా సరిపోతున్న చిన్న భాగాలు. ఆ భాగాలు కొంత Overlap కలిగి ఉంటాయి, తద్వారా సముచిత సందర్భం అంతరాల వద్ద కోల్పోకుండా ఉంటుంది. +మీరు ఒక డాక్యుమెంట్‌ను అప్‌లోడ్ చేసినప్పుడు, వ్యవస్థ దాన్ని పార్స్ చేస్తుంది (PDF లేదా సాధారణ టెక్స్ట్), ఫైల్ పేర్లాంటి మెటాడేటా జత చేస్తుంది, అప్పుడు దానిని చంక్స్ గా విభజిస్తుంది — మోడల్ సదుపయోగ విండోలో బాగా సరిపోయే చిన్న భాగాలుగా. ఈ చంక్స్ కొద్దిగా ఒకదానితో పొడవుగా ఉంటాయి, అందువల్ల సరిహద్దుల్లో సం‍దర్భం కోల్పోదు. ```java -// అప్లోడ్ చేసిన ఫైల్‌ను పార్స్ చేసి LangChain4j డాక్యుమెంట్‌లో చుట్టండి +// అప్‌లోడ్ చేసిన ఫైల్నీ వాచించి LangChain4j డాక్యుమెంట్‌లో చేర్పించండి Document document = Document.from(content, metadata); -// 30-టోకెన్ ఓవర్‌ల్యాప్‌తో 300-టోకెన్ చంక్‌లుగా విభజించండి +// 300-టోకెన్ భాగాలుగా విడగొట్టి 30-టోకెన్ ఓవర్ల్యాప్‌తో చేసి DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -కింది చిత్రం దాన్ని కళ్లకు చూపిస్తుంది. ప్రతి చంక్ తన పొరుగులుతో కొన్ని టోకెన్లను పంచుకుంటుందనే గమనించండి — 30 టోకెన్ Overlap ముఖ్యం కాన్సెప్ట్ ల మధ్య లోకిచి పోకుండేందుకు కల్పిస్తుంది: + +కింది చిత్రం దీన్ని దృష్టాంతంగా చూపిస్తుంది. ప్రతి చంక్ తన పొరుగువారితో కొన్ని టోకెన్స్ పంచుకుంటుంది — 30-టోకెన్ ఒవర్‌లాప్ సారి 중요한 సంతర్భం విరుగుడుల మధ్యపడకుండా చూచుతుంది: Document Chunking -*ఈ చిత్రం ఒక డాక్యుమెంట్ 300-టోకెన్ చంక్‌లుగా 30-టోకెన్ Overlapతో విభజింపబడుతుంది, చంక్ సరిహద్దుల మధ్య సందర్భాన్ని కాపాడుతుంది అని చూపిస్తుంది.* +*ఈ చిత్రం డాక్యుమెంట్‌ను 300-టోకెన్ చంక్స్‌గా విభజించడం, 30-టోకెన్ ఒవర్‌లాప్ తో, చంక్ సరిహద్దుల్లో సం‍దర్భాన్ని సంరక్షించడం చూపిస్తుంది.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్‌తో ప్రయత్నించండి:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) తెరిచి అడగండి: -> - "LangChain4j డాక్యుమెంట్లను చంక్‌లుగా ఎలా విభజిస్తుంది మరియు Overlap ఎందుకు ముఖ్యం?" -> - "విభిన్న డాక్యుమెంట్ రకాల కోసం అత్యుత్తమ చంక్ పరిమాణం ఏది మరియు ఎందుకు?" -> - "మీరు బహుభాషా లేదా ప్రత్యేక ఫార్మాటింగ్ ఉన్న డాక్యుమెంట్లను ఎలా నిర్వహిస్తున్నారు?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్‌తో ప్రయత్నించండి:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java)ను ఓపెన్ చేసి అడగండి: +> - "LangChain4j ఎలా డాక్యుమెంట్లను చంక్స్‌గా భాగించిందో మరియు ఒవర్‌లాప్ ఎందుకు ముఖ్యం?" +> - "వివిధ రకాల డాక్యుమెంట్ల కోసం ఉత్తమ చంక్ పరిమాణం ఏమిటి మరియు ఎందుకు?" +> - "అनेक భాషలలో ఉన్న డాక్యుమెంట్లు లేదా ప్రత్యేక ఫార్మాటింగ్ ఉన్న డాక్యుమెంట్లను ఎలా హ్యాండిల్ చేయాలి?" -### ఎంబెడ్డింగ్లు సృష్టించడం +### Creating Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -ప్రతి చంక్ ఒక సంఖ్యాత్మక రూపంగా మార్చబడుతుంది, దానిని ఎంబెడ్డింగ్ అంటారు—అంటే అర్థం-నంబర్లకు మార్చే కాన్వర్టర్. ఎంబెడ్డింగ్ మోడల్ చాట్ మోడల్‌లా "సమర్థుడు" కాదు; అది ఆదేశాలు అనుసరించడం, తార్కిక తర్కం చేయడం, లేదా ప్రశ్నలకు సమాధానం ఇవ్వడం చేయదు. ఏమి చేస్తుందంటే, సారూప్య అర్థాలు దగ్గరగా ఉన్న వ్యాస స్థలంలో వచనం మ్యాప్ చేస్తుంది — "కారు" అంటే "ఆటోమొబైల్" దగ్గరగా, "రిఫండ్ పాలసీ" అంటే "నా డబ్బు తిరిగి ఇవ్వండి" దగ్గరగా. చాట్ మోడల్‌తో సంభాషించటం ఒక వ్యక్తితో మాట్లాడటంలాంటిదని కల్పించండి; ఎంబెడ్డింగ్ మోడల్ సమర్ధతగల ఫైలింగ్ వ్యవస్థ లాంటిది. +ప్రతి చంక్ సంఖ్యల్లో అనువాదం అవుతుంది, దీనిని ఎంబెడ్డింగ్ అంటారు — అంటే భావం నుంచి సంఖ్యలకు మార్పిడి. embedding మోడల్ చాట్ మోడల్ లాగా "తెలివైనది" కాదు; ఇది ఆదేశాలు పాటించగలదు, కారణం చెప్పగలదు లేదా ప్రశ్నలకు జవాబు ఇవ్వగలదు కాదు. కానీ ఇది టెక్స్ట్‌ను గణిత స్థానంలోకి మ్యాప్ చేస్తుంది, ఇక్కడ సమానమైన అర్థాలు సమీపంలో ఉంటాయి — "కారు" సమీపంలో "ఆటోమొబైల్," "రిఫండ్ పాలసీ" సమీపంలో "నా డబ్బు తిరిగి ఇవ్వండి." చాట్ మోడల్‌ను మీరు మాట్లాడగల వ్యక్తిగా భావించండి; embedding మోడల్ ఒక అద్భుతమైన శ్రేణీకరణ వ్యవస్థ. -కింది చిత్రం ఈ ఆలోచనను చూపిస్తుంది — టెక్స్ట్ ఇన్ అవుతుందీ, సంఖ్యాత్మక వెక్టర్లు అవుతాయి, సారూప్య అర్థాలున్న పదాలు దగ్గరగా వెక్టర్లుగా ఏర్పడతాయి: +కింది చిత్రం ఈ భావనను చూపిస్తుంది — టెక్స్ట్ ఇన్ అవుతుంది, సంఖ్యల వెక్టార్లు అవతరిల్లతాయి, మరియు సమాన అర్థాలు సమీప వెక్టర్‌లను ఉత్పత్తి చేస్తాయి: Embedding Model Concept -*ఈ చిత్రం ఎంబెడ్డింగ్ మోడల్ వచనాన్ని సంఖ్యాత్మక వెక్టర్లుగా మార్చే విధానాన్ని చూపిస్తుంది, "కారు" మరియు "ఆటోమొబైల్" లాంటి సారూప్య అర్థాలను వెక్టర్ స్థలంలో ఒకదాని దగ్గర ఉంచుతుంది.* +*ఈ చిత్రంలో embedding మోడల్ టెక్స్ట్‌ను సంఖ్యల వెక్టార్లగా మారుస్తుంది, సమాన భావాలు — ఉదా: "కారు" మరియు "ఆటోమొబైల్" — సమీపంలో ఉంటాయనే చూపిస్తుంది.* ```java @Bean @@ -153,30 +154,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -క్లాస్ డయాగ్రామ్ కింది RAG పైపు‌లైన్‌లో రెండు వేర్వేరు ప్రవాహాలు మరియు వాటిని అమలు చేసే LangChain4j క్లాసులను చూపిస్తుంది. **ఇంగెస్ట్షన్ ఫ్లో** (అప్‌లోడ్ సమయంలో ఒక్కసారి నడుస్తుంది) డాక్యుమెంట్ను విభజించి, చంక్‌లను ఎంబెడ్ చేసి, `.addAll()` ద్వారా నిల్వ చేస్తుంది. **ప్రశ్నాప్రవాహం** (ప్రతి వాడుకరి ప్రశ్న వద్ద నడుస్తుంది) ప్రశ్నను ఎంబెడ్ చేస్తుంది, స్టోర్‌ని `.search()` ద్వారా శోధిస్తుంది, మరియు సమీపించిన సందర్భాన్ని చాట్ మోడల్‌కి అందిస్తుంది. రెండూ పంచుకునే `EmbeddingStore` ఇంటర్‌ఫేస్ వద్ద కలుస్తాయి: + +కింది తరగతి చిత్రంలో RAG పైప్‌లైన్‌లో రెండు వేర్వేరు ప్రవాహాలు మరియు వాటిని అమలు చేసే LangChain4j తరగతులు చూపబడ్డాయి. **ఇన్జెస్ట్షన్ ప్రవాహం** (అప్‌లోడ్ సమయంలో ఒకసారి) డాక్యుమెంట్ను విడగొట్టి, చంక్స్‌ను ఎంబెడ్ చేసి, `.addAll()` ద్వారా నిల్వ చేస్తుంది. **క్వెరీ ప్రవాహం** (ప్రతి సారి వాడుకరి అడిగినప్పుడు) ప్రశ్నను ఎంబెడ్ చేసి, `.search()` ద్వారా స్టోర్‌ను శోధించి, సరిపోయిన సం‍దర్భాన్ని చాట్ మోడల్‌కు పంపిస్తుంది. ఇద్దరు ప్రవాహాలు `EmbeddingStore` ఇంటర్‌ఫేస్‌లో కలుస్తాయి: LangChain4j RAG Classes -*ఈ చిత్రం RAG పైపు‌లైన్‌లోని ఇంగెస్ట్షన్ మరియు ప్రశ్నాప్రవాహ రెండు ప్రవాహాలను మరియు అవి పంచుకునే EmbeddingStore ద్వారా ఎలా కలుస్తాయో చూపిస్తుంది.* +*ఈ చిత్రంలో RAG పైప్‌లైన్‌లో రెండు ప్రవాహాలు — ఇన్జెస్ట్షన్ మరియు క్వెరీ — మరియు అవి భాగంగా ఉన్న EmbeddingStore ద్వారా ఎలా కలిసిపోతున్నాయో చూపిస్తుంది.* -ఎంబెడ్డింగ్లు నిల్వ చేసిన తర్వాత, సారూప్య కంటెంట్ సహజంగా వెక్టర్ స్థలంలో దగ్గరగా కులగుంటలో ఉంటాయి. కింది విజువలైజేషన్ తీరుగా సంబంధిత అంశాలున్న డాక్యুমెంట్లు సమీప బిందువులుగా ఎలా ఏర్పడతాయో చూపిస్తుంది, ఇది సెమాంటిక్ సర్చ్‌కి కారణమవుతుంది: +ఎంబెడ్డింగ్స్ నిల్వ చేసిన తరువాత, సమాన కంటెంట్ సహజంగా వెక్టర్ స్థలంలో సమీపంగా క్లస్టర్ అవుతుంది. కింది విజువలైజేషన్ వివిధ టాపిక్స్ చెందిన డాక్యుమెంట్లు సమీప బిందువులుగా ఎలా మారుతున్నాయో చూపిస్తుంది, ఇది సెమెంటిక్ శోధన సాధ్యం కావడానికి మూల కారణం: Vector Embeddings Space -*ఈ విజువలైజేషన్ సంబంధిత డాక్యుమెంట్లు 3D వెక్టర్ స్థలంలో ఎలా సమూహాలుగా ఏర్పడతాయో చూపిస్తుంది, టెక్నికల్ డాక్స్, బిజినెస్ రూల్స్, మరియు FAQs వంటివి వేరే వేరే గుంపులుగా.* +*ఈ విజువలైజేషన్‌లో సంబంధిత డాక్యుమెంట్లు 3D వెక్టర్ స్పేస్‌లో కలస్టర్ అవుతున్నాయి, టెక్నికల్ డాక్స్, బిజినెస్ రూల్స్, FAQs వంటి విభాగాలతో వేర్వేరు గ్రూపులను ఏర్పరుస్తున్నాయి.* -వాడుకరి శోధన చేస్తున్నప్పుడు, వ్యవస్థ నాలుగు దశలను అనుసరిస్తుంది: ఒకసారి డాక్యుమెంట్లను ఎంబెడ్ చేయడం, ప్రతి శోధనకు ప్రశ్నను ఎంబెడ్ చేయడం, ప్రశ్న వెక్టర్‌ను స్టోర్‌లోని అన్ని వెక్టర్లతో కోసైన్ సారూప్యతతో సరిపోల్చడం, మరియు టాప్-K అత్యుత్తమ స్కోరు పొందిన చంక్‌లను తిరిగి ఇవ్వడం. కింది చిత్రం ప్రతి దశను మరియు LangChain4j క్లాసులను చూపిస్తుంది: +వాడుకరి శోధించినప్పుడు, వ్యవస్థ నాలుగు దశలను అనుసరిస్తుంది: డాక్యుమెంట్లను ఒకసారి ఎంబెడ్ చేయండి, ప్రతి శోధనా సమయంలో ప్రశ్నను ఎంబెడ్ చేయండి, ప్రశ్న వెక్టర్‌ను నిల్వ వెక్టర్‌లతో కోసైన్ సాదృశ్యం ఉపయోగించి పోల్చండి, మరియు టాప్-K అత్యధిక స్కోర్ల చంక్స్‌ను తిరిగి ఇవ్వండి. కింది చిత్రం ప్రతి దశను మరియు అందులో పాల్గొన్న LangChain4j తరగతులను చూపిస్తుంది: Embedding Search Steps -*ఈ చిత్రం నాలుగు దశల ఎంబెడ్డింగ్ శోధన ప్రక్రియను చూపిస్తుంది: డాక్యుమెంట్లను ఎంబెడ్ చేయడం, ప్రశ్నను ఎంబెడ్ చేయడం, కోసైన్ సారూప్యతతో వెక్టర్‌లను సరిపోల్చడం, మరియు టాప్-K ఫలితాలు ఇవ్వడం.* +*ఈ చిత్రంలో నాలుగు-దశల ఎంబెడ్డింగ్ శోధన ప్రక్రియ చూపబడింది: డాక్యుమెంట్లను ఎంబెడ్ చేయడం, ప్రశ్నను ఎంబెడ్ చేయడం, కోసైన్ సాదృశ్యంతో వెక్టర్‌లను పోల్చడం, మరియు టాప్-K ఫలితాలు ఇవ్వడం.* -### సెమాంటిక్ సర్చ్ +### Semantic Search [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -మీరు ప్రశ్న అడిగినప్పుడే, ఆ ప్రశ్న కూడా ఒక ఎంబెడ్డింగ్ అవుతుంది. సిస్టమ్ ఆ ప్రశ్న ఎంబెడ్డింగ్‌ను అన్ని డాక్యుమెంట్ చంక్‌ల ఎంబెడ్డింగ్‌లతో సరిపోల్చుతుంది. ఇది అత్యంత సమానమైన అర్థాలను కలిగిన చంక్‌లను కనుగొంటుంది — కేవలం కీవర్డ్లు సరిపోదు, నిజమైన సారూప్యతను గుర్తుకుంటుంది. +మీరు ప్రశ్న అడిగినా, మీ ప్రశ్న కూడా ఎంబెడ్డింగ్‌గా మారుతుంది. వ్యవస్థ మీ ప్రశ్న యొక్క ఎంబెడ్డింగ్ ను డాక్యుమెంట్ చంక్స్ అందరి ఎంబెడ్డింగ్స్ తో పోల్చుతుంది. ఇది చాలా సమాన అర్థాల గల భాగాలను కనుగొంటుంది — కీవర్డ్స్ మాత్రమే కాకుండా, నిజమైన సెమెంటిక్ సాదృశ్యాన్ని కూడా. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +196,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -కింది చిత్రం సెమాంటిక్ శోధనను సంప్రదాయ కీవర్డు శోధనతో పోల్చుతుంది. "వాహనం" అనే కీవర్డు శోధన "కార్లు మరియు ట్రక్కులు" అనే చంక్ మిస్ అవుతుంది, కానీ సెమాంటిక్ శోధన వాటి అవగాహనతో ఉంచి, దానిని అధిక స్కోరింగ్ మ్యాచ్ గా తిరిగి ఇస్తుంది: + +కింది చిత్రం సంప్రదాయ కీవర్డ్ శోధనతో సెమెంటిక్ శోధనను పోల్చుతుంది. "వాహనం"కి కీవర్డ్ శోధన "కార్లు మరియు ట్రక్స్" గురించి ఉన్న భాగాన్ని మిస్ చేస్తుంది, కానీ సెమెంటిక్ శోధన అదే అర్థం అని అర్థం చేసుకొని దానిని అత్యధిక స్కోరు గల ఫలితంగా ఇస్తుంది: Semantic Search -*ఈ చిత్రం కీవర్డు ఆధారిత శోధనను సెమాంటిక్ శోధనతో పోల్చి చూపిస్తుంది, సెమాంటిక్ శోధన ఖచ్చిత కీవర్డ్లు లేకున్నా సంబంధిత భావాలను సేకరిస్తుంది.* -అండర్ ద హుడ్, సారూప్యత కోసైన్ సారూప్యతను ఉపయోగించి కొలవబడుతుంది — విషయానికి "ఈ రెండు బాణాలు ఒకే దిశలో చూస్తున్నాయా?" అని essentially అడుగుతుంది. రెండు భాగాలు పూర్తిగా వేరు పదాలు వాడినా, అవి ఒకే అర్థం ఉంటే అవి ఒకే దిశలో ఉండే వెక్టర్లు మరియు 1.0 కి దగ్గరగా స్కోరు ఇవ్వబడతాయి: +*ఈ చిత్రం కీవర్డ్ ఆధారిత శోధన మరియు సెమెంటిక్ శోధన మధ్య తేడాను చూపిస్తుంది, సెమెంటిక్ శోధన అర్ధం ఆధారంగా సంబంధిత కంటెంట్‌ను తెస్తుంది, నిజమైన కీవర్డ్‌లు భిన్నంగా ఉన్నా కూడా.* -Cosine Similarity +దేశ్కి లో, సమానత్వమైనదాన్ని కొలవడానికి కోసైన్ సాదృశ్యం ఉపయోగిస్తారు — అది "ఈ రెండు ఎర్రాళ్ళు అదే దిశకు చూపిస్తున్నాయా?" అని అడగడం లాంటిదే. రెండు చంక్స్ పూర్తిగా వేర్వేరు పదాలు ఉపయోగించవచ్చు, కానీ అవి ఒకే ఆలోచన ఉంటే వారి వెక్టర్‌లు ఒకే దిశలో ఉంటాయి మరియు 1.0 కి సమీపంగా స్కోరు పొందుతాయి: -*ఈ డయాగ్రాం ఎంబెడింగ్ వెక్టర్ల మధ్య కోసైన్ సారూప్యతను యాంగిల్ ద్వారా చూపిస్తుంది — ఎక్కువగా సరిపోలిన వెక్టర్లు 1.0 కు దగ్గరగా స్కోరు చేస్తాయి, ఇది ఉన్నతమైన అర్థ సారూప్యతను సూచిస్తుంది.* +Cosine Similarity +*ఈ చిత్రణ ఎంబెడ్డింగ్ వెక్టర్ల మధ్య కోసైన్ సాదృశ్యాన్ని కోణంగా చూపిస్తుంది — ఎక్కువ సారూప్యత కలిగిన వెక్టర్లు 1.0కి దగ్గరగా స్కోరు పొందుతాయి, ఇది ఉన్నతమైన సార్ధక సాదృశ్యాన్ని సూచిస్తుంది.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్ తో ప్రయత్నించండి:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ఓపెన్ చేసి అడగండి: -> - "ఎంబెడింగ్స్‌తో సారూప్యత శోధన ఎలా పనిచేస్తుంది మరియు స్కోరు ఏమి నిర్ణయించేది?" -> - "నేను ఏ సారూప్యత సరిహద్దును వాడాలి మరియు అది ఫలితాలపై ఎలా ప్రభావం చూపుతుంది?" -> - "సంబంధిత పత్రాలు కనబడని సందర్భాలను నేను ఎలా నిర్వహించాలి?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్‌తో ప్రయత్నించండి:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ని తెరిచి అడగండి: +> - "ఎంబెడ్డింగ్స్‌తో సాదృశ్య శోధన ఎలా పనిచేస్తుంది మరియు స్కోరును ఏమి నిర్ణయిస్తుంది?" +> - "ఏ సాదృశ్య సరిహద్దును నేను ఉపయోగించాలి మరియు ఇది ఫలితాలపై ఎలా ప్రభావం చూపుతుంది?" +> - "సంబంధిత డాక్యుమెంట్లు కనిపించని సందర్భాలలో నేను ఎలా నిర్వహించాలి?" -### జవాబు ఉత్పత్తి +### సమాధాన ఉత్పత్తి [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -సర్వసంబంధిత భాగాలు స్పష్టమైన సూచనలు, వెలికి తీయబడిన సందర్భం మరియు వినియోగదారుడి ప్రశ్నను కలిగి ఉన్న నిర్మిత ప్రాంప్ట్‌గా ఎడమవుతాయి. మోడల్ ఆ ప్రత్యేక భాగాలనే చదివి ఆ సమాచారంపై ఆధారపడి జవాబు ఇస్తుంది — అట్టడుగు మీద ఉన్నదేనికే ఉపయోగపడుతుంది, హల్యూసినేషన్ నివారిస్తుంది. +అత్యంత సంబంధిత భాగాలు స్పష్టమైన నియమాలు, తిరిగి పొందిన సందర్భం, మరియు వినియోగదారు ప్రశ్నను కలిగి ఉన్న నిర్మిత ప్రాంప్ట్‌గా సమీకరించబడతాయి. మోడల్ ఆ ప్రత్యేక భాగాలను చదువుతూ ఆ సమాచారంపై ఆధారపడి సమాధానం ఇస్తుంది — ఇది ముందున్న సమాచారాన్నే ఉపయోగిస్తుంది, ఇది కల్పనను నిలిపివేస్తుంది. ```java String context = matches.stream() @@ -237,17 +238,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -క్రింది డయాగ్రాం ఈ అసెంబ్లీయిన్ చర్యను చూపిస్తుంది — శోధన దశలో ఉన్న అత్యుత్తమ స్కోరు పొందిన భాగాలు ప్రాంప్ట్ టెంప్లేట్‌లో చేర్చబడతాయి, మరియు `OpenAiOfficialChatModel` సమగ్ర జవాబు ఉత్పత్తి చేస్తుంది: +క్రింది диаграм ఈ సమీకరణను చూపిస్తుంది — శోధన దశ నుండి టాప్-స్కోరైన భాగాలు ప్రాంప్ట్ టెంప్లేట్‌లో చేర్చబడతాయి, మరియు `OpenAiOfficialChatModel` ఒక నిర్ధారిత సమాధానాన్ని రూపొందిస్తుంది: Context Assembly -*ఈ డయాగ్రాం చూపిస్తుంది ఎలా అత్యుత్తమ స్కోరు పొందిన భాగాలు నిర్మిత ప్రాంప్ట్‌గా ఏకీకృతమవుతూ, మోడల్‌ను మీ డేటా నుండి సాక్షాత్తు జవాబు ఇస్తున్నదో.* +*ఈ చిత్రణ టాప్-స్కోరైన భాగాలు ఎలా నిర్మిత ప్రాంప్ట్‌గా సమీకరించబడతాయో చూపిస్తుంది, ఇది మోడల్‌కు మీ డేటా నుండి ఆధారిత సమాధానం ఇవ్వడాన్ని వీలు చేస్తుంది.* -## యాప్లికేషన్ నడపండి +## దరఖాస్తును నడపండి -**డిప్లాయ్‌మెంట్ ధృవీకరించండి:** +**డిప్లాయ్ మెంట్‌ను ధృవీకరించండి:** -రూట్ డైరెక్టరీలో `.env` ఫైల్ Azure క్రెడెన్షియల్స్‌తో ఉందని నిర్ధారించండి (మాడ్యూల్ 01 లో సృష్టించబడింది). ఈ మాడ్యూల్ డైరెక్టరీలోనుంచి (`03-rag/`) దీన్ని నడపండి: +మూల డైరెక్టరీలో Azure క్రెడెన్షియల్స్‌తో `.env` ఫైలు ఉన్నదని నిర్ధారించండి (మాడ్యూల్ 01 సమయంలో సృష్టించబడింది). ఈ మాడ్యూల్ డైరెక్టరీ నుండి ఈ క్రింద అమలు చేయండి (`03-rag/`): **Bash:** ```bash @@ -259,33 +260,33 @@ cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT చూపించా Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT చూపించాలి ``` -**యాప్లికేషన్ ప్రారంభించండి:** +**అప్లికేషన్‌ను ప్రారంభించండి:** -> **గమనిక:** మీరు ఇప్పటికే రూట్ డైరెక్టరీ నుండి `./start-all.sh` రన్ చేసి అన్ని యాప్‌లను ప్రారంభించి ఉంటే (మాడ్యూల్ 01 లో వివరణ), ఈ మాడ్యూల్ 8081 పోర్ట్‌లో పని చేయటంలో ఉంది. కాబట్టి క్రింది స్టార్ట్ కమాండ్లను దాటవేసి నేరుగా http://localhost:8081 కి వెళ్లవచ్చు. +> **గమనిక:** మీరు ఇప్పటికే మూల డైరెక్టరీలోని `./start-all.sh` ఉపయోగించి అన్ని అప్లికేషన్లను ప్రారంభించినట్లయితే (మాడ్యూల్ 01లో వివరించబడింది), ఈ మాడ్యూల్ ఇప్పటికే పోర్ట్ 8081 నడుస్తోంది. మీరు క్రింది స్టార్ట్ కమాండ్లను దాటవేసి నేరుగా http://localhost:8081 వెళ్ళవచ్చు. -**ఎంపిక 1: స్ప్రింగ్ బూట్ డ్యాష్‌బోర్డ్ ఉపయోగించడం (VS Code వినియోగదారులకు సూచించబడింది)** +**ఎంపిక 1: స్ప్రింగ్ బూట్ డ్యాష్‌బోర్డ్ ఉపయోగించడం (VS కోడ్ వినియోగదారులకు సిఫార్సు)** -డెవ్ కంటైనర్‌లో Spring Boot Dashboard ఎక్స్‌టెన్షన్ ఉంటుంది, ఇది అన్ని Spring Boot యాప్లికేషన్లను కన్ఫిగర్ చేసుకోవడానికి విజువల్ ఇంటర్‌ఫేస్ అందిస్తుంది. మీరు దీన్ని VS Code ఎడమ భాగంలో Activity Barలో(Spring Boot చిహ్నం కోసం చూడండి) కనుగొనవచ్చు. +డెవ్ కంటెయినర్ స్ప్రింగ్ బూట్ డ్యాష్‌బోర్డ్ ఎక్స్టెన్షన్‌ను కలిగి ఉంటుంది, ఇది అన్ని స్ప్రింగ్ బూట్ అప్లికేషన్లను నిర్వహించడానికి విజువల్ ఇంటర్‌ఫేస్ అందిస్తుంది. దీనిని VS కోడ్ లో డెవలప్మెంట్ బార్(Activity Bar) ఎడమవైపున స్ప్రింగ్ బూట్ చిహ్నం వద్ద చూడవచ్చు. -Spring Boot Dashboard నుండి మీరు: -- వర్క్‌స్పేస్‌లో అందుబాటులో ఉన్న అన్ని Spring Boot యాప్లికేషన్లను చూడవచ్చు -- ఒక క్లిక్‌తో యాప్లికేషన్లను స్టార్ట్/స్టాప్ చేయవచ్చు -- యాప్లికేషన్ లాగ్‌లను సమయానుకూలంగా చూడవచ్చు -- యాప్లికేషన్ స్థితిని పర్యవేక్షించవచ్చు +స్ప్రింగ్ బూట్ డ్యాష్‌బోర్డ్ నుండి మీరు: +- వర్క్‌స్పేస్‌లో అందుబాటులో ఉన్న అన్ని స్ప్రింగ్ బూట్ అప్లికేషన్లను చూడవచ్చు +- ఒక క్లిక్‌లో అనువర్తనాలను ప్రారంభించగలరు లేదా ఆపగలరు +- అప్లికేషన్ లాగ్స్‌ను రియల్ టైమ్‌లో వీక్షించవచ్చు +- అప్లికేషన్ స్థితిని పర్యవేక్షించవచ్చు -"rag" పక్కన ఉన్న ప్లే బటన్ క్లిక్ చేస్తే ఈ మాడ్యూల్ ప్రారంభమవుతుంది, లేదా ఒకేసారిగా అన్ని మాడ్యూల్‌లను ప్రారంభించవచ్చు. +"rag" పక్కన ఉన్న ప్లే బటన్ పై క్లిక్ చేయడం ద్వారా ఈ మాడ్యూల్‌ను ప్రారంభించండి లేదా అన్ని మాడ్యూల్స్‌ను ఒకదానితో పాటు ప్రారంభించండి. Spring Boot Dashboard -*ఈ స్క్రీన్‌షాట్ VS Code లో Spring Boot Dashboard ని చూపిస్తుంది, మీరు యాప్లికేషన్లను విజువల్‌గా ప్రారంభించవచ్చు, ఆపవచ్చు, మరియు పరిశీలించవచ్చు.* +*ఈ స్క్రీన్‌షాట్ VS కోడ్‌లో స్ప్రింగ్ బూట్ డ్యాష్‌బోర్డ్‌ను చూపిస్తుంది, ఇక్కడ మీరు అప్లికేషన్లను విజువల్‌గా ప్రారంభించి, ఆపేందుకు, పర్యవేక్షించేందుకు পারেন.* -**ఎంపిక 2: షెల్ స్క్రిప్ట్‌లు ఉపయోగించడం** +**ఎంపిక 2: షెల్ స్క్రిప్ట్స్ ఉపయోగించడం** -అన్ని వెబ్ యాప్లికేషన్లు (మాడ్యూల్స్ 01-04) ను ప్రారంభించండి: +అన్ని వెబ్ అప్లికేషన్లను ప్రారంభించండి (మాడ్యూల్స్ 01-04): **Bash:** ```bash -cd .. # మూల డైరెక్టరీ నుండి +cd .. # రూట్ డైరెక్టరీ నుండి ./start-all.sh ``` @@ -309,9 +310,9 @@ cd 03-rag .\start.ps1 ``` -రూట్ `.env` ఫైల్ నుండి స్వయంచాలకంగా ఎన్విరాన్మెంట్ వేరియబుల్స్ లోడ్ చేస్తారు మరియు JAR ఫైళ్ళు లేమంటే అవి నిర్మించబడతాయి. +రూట్ `.env` ఫైల్ నుండి వాతావరణ փոփոխనాలను స్వయంచాలకంగా లోడ్ చేస్తాయి మరియు అవసరమైతే JARలను నిర్మిస్తాయి. -> **గమనిక:** మీరు ప్రారంభించే ముందు అన్ని మాడ్యూల్‌లను సొంతంగా కట్టెలంటే: +> **గమనిక:** మీరు ప్రారంభించే ముందు అన్ని మాడ్యూల్స్‌ను మానవీయంగా నిర్మించాలనుకుంటే: > > **Bash:** > ```bash @@ -325,9 +326,9 @@ cd 03-rag > mvn clean package -DskipTests > ``` -మీ బ్రౌజర్‌లో http://localhost:8081 ని ఓపెన్ చేయండి. +మీ బ్రౌజర్‌లో http://localhost:8081 ఓపెన్ చేయండి. -**ఆపడానికి:** +**నిర్మూలన:** **Bash:** ```bash @@ -343,95 +344,95 @@ cd .. && ./stop-all.sh # అన్ని మాడ్యూల్స్ cd ..; .\stop-all.ps1 # అన్ని మాడ్యూల్స్ ``` -## యాప్లికేషన్ ఉపయోగించడం +## అప్లికేషన్‌ను ఉపయోగించడం -యాప్లికేషన్ డాక్యుమెంట్ అప్‌లోడ్ మరియు ప్రశ్నించడం కోసం వెబ్ ఇంటర్‌ఫేస్ అందిస్తుంది. +అప్లికేషన్ డాక్యుమెంటు అప్లోడ్ మరియు ప్రశ్నించడం కోసం వెబ్ ఇంటర్‌ఫేస్ అందిస్తుంది. RAG Application Interface -*ఈ స్క్రీన్‌షాట్ RAG యాప్లికేషన్ ఇంటర్‌ఫేస్‌ని చూపిస్తుంది, ఇందులో మీరు డాక్యుమెంట్లను అప్‌లోడ్ చేసి ప్రశ్నలు అడగవచ్చు.* +*ఈ స్క్రీన్‌షాట్ RAG అప్లికేషన్ ఇంటర్‌ఫేస్ ని చూపిస్తుంది, ఇక్కడ మీరు డాక్యుమెంట్లను అప్లోడ్ చేసి ప్రశ్నలు అడగవచ్చు.* -### డాక్యుమెంట్ అప్‌లోడ్ చేయండి +### డాక్యుమెంటు అప్లోడ్ చేయండి -TXT ఫైళ్ళతో మొదలు పెట్టండి - అవి పరీక్షకోవడానికి ఉత్తమం. ఈ డైరెక్టరీలో `sample-document.txt` ఉంది, ఇందులో LangChain4j ఫీచర్స్, RAG అమలీకరణ, ఉత్తమ ప్రామాణికాలతో సంబంధిత సమాచారం ఉంది - సిస్టమ్ పరీక్షకు పర్ఫెక్ట్. +ముందుగా ఒక డాక్యుమెంటును అప్లోడ్ చేయండి - పరీక్ష కోసం TXT ఫైల్స్ బాగుంటాయి. ఈ డైరెక్టరీలో ఒక `sample-document.txt` అందుబాటులో ఉంది, ఇది LangChain4j ఫీచర్లు, RAG అమలు మరియు ఉత్తమ పద్ధతుల గురించి సమాచారాన్ని కలిగి ఉంది - సిస్టమ్ ని పరీక్షించడానికి పర్ఫెక్ట్. -సిస్టమ్ మీ డాక్యుమెంట్‌ను ప్రాసెస్ చేసి, దానిని భాగాలుగా విభజించి, ప్రతి భాగానికి ఎంబెడింగ్స్ సృష్టిస్తుంది. ఇది మీరు అప్‌లోడ్ చేస్తే స్వయంచాలకంగా జరుగుతుంది. +సిస్టమ్ మీ డాక్యుమెంటును ప్రాసెస్ చేసి, దాన్ని భాగాలుగా విభజిస్తుంది మరియు ప్రతి భాగం కోసం ఎంబెడ్డింగ్స్ సృష్టిస్తుంది. ఇది మీరు అప్లోడ్ చేసిన వెంటనే ఆటోమాటిక్‌గా జరుగుతుంది. ### ప్రశ్నలు అడగండి -ఇప్పుడు డాక్యుమెంట్ కంటెంట్ను గురించి స్పష్టమైన ప్రశ్నలు అడగండి. డాక్యుమెంట్‌లో స్పష్టంగా పేర్కొన్న వాస్తవాలను ప్రయత్నించండి. సిస్టమ్ సంబంధిత భాగాలను శోధించి, వాటిని ప్రాంప్ట్‌లో చేర్చి, జవాబు ఉత్పత్తి చేస్తుంది. +ఇప్పుడు డాక్యుమెంటు విషయంపై నిర్దిష్ట ప్రశ్నలు అడగండి. డాక్యుమెంటులో స్పష్టంగా చెప్పిన వాస్తవ విషయాలను ప్రయోగించండి. సిస్టమ్ సంబంధిత భాగాలను శోధించి, వాటిని ప్రాంప్ట్‌లో చేర్చిపెట్టి సమాధానం రూపొందిస్తుంది. -### మూల పత్ర సూచనలను తనిఖీ చేయండి +### మూల సూచనలను తనిఖీ చేయండి -ప్రతి జవాబు మూల పత్ర సూచనలతో మరియు సారూప్యత స్కోర్లు కలిగి ఉంటుంది. ఈ స్కోర్లు (0 నుండి 1 వరకూ) మీ ప్రశ్నకు భాగం ఎంత సంబంధితంగా ఉందో చూపిస్తాయి. ఎక్కువ స్కోర్స్ అంటే బాగా సరిపోతుంది. ఇది మీరు జవాబు మూలంతో సరిపోల్చడానికి సహాయపడుతుంది. +ప్రతి సమాధానంలో సాదృశ్య స్కోర్లు ఉన్న మూల సూచనలు ఉంటాయి. ఈ స్కోర్లు (0 నుండి 1 వరకు) మీ ప్రశ్నకు ప్రతి భాగం ఎంత సంబంధితమో చూపిస్తాయి. ఎక్కువ స్కోర్లు మంచి సరిపోడం సూచిస్తాయి. ఇది మీరు సమాధానాన్ని మూల పదార్థంతో సరిపోల్చుకోవడానికి సహాయపడుతుంది. RAG Query Results -*ఈ స్క్రీన్‌షాట్ ప్రశ్న ఫలితాలను చూపిస్తుంది, జనరేట్ చేసిన జవాబు, మూల పత్ర సూచనలు, మరియు పొందిన ప్రతి భాగానికి సంబంధించిన ప్రాముఖ్యత స్కోర్లతో.* +*ఈ స్క్రీన్‌షాట్ ప్రశ్న ఫలితాలను, ఉత్పన్నమైన సమాధానం, మూల సూచనలు మరియు ప్రతి వెతికిన భాగం యొక్క సంబంధిత స్కోర్లను చూపిస్తుంది.* -### ప్రశ్నలతో ప్రయోగం చేయండి +### ప్రశ్నలతో ప్రయోగించండి -వివిధ రకాల ప్రశ్నల్ని ప్రయత్నించండి: -- స్పష్టమైన వాస్తవాలు: "ముఖ్యమైన విషయం ఏమిటి?" -- పోలికలు: "X మరియు Y మధ్య వ్యత్యాసం ఏమిటి?" -- సారాంశాలు: "Z గురించిన ప్రధాన పాయింట్‌ల సారాంశం చెప్పండి" +భిన్న రకాల ప్రశ్నలను ప్రయత్నించండి: +- నిర్దిష్ట వాస్తవాలు: "ప్రధాన విషయం ఏమిటీ?" +- పోలికలు: "X మరియు Y మధ్య తేడా ఏమిటి?" +- సారాంశాలు: "Z గురించి ముఖ్యాంశాలను సంగ్రహించండి" -మీ ప్రశ్న డాక్యుమెంట్ కంటెంట్‌తో ఎంత బాగా సరిపోలుతుందో చూసి ప్రాముఖ్యత స్కోర్లు ఎలా మారుతున్నాయో గమనించండి. +మీ ప్రశ్న డాక్యుమెంటు విషయంతో ఎంత సరిపోతుందో ఆధారంగా సంబంధిత స్కోర్లు ఎలా మారుతాయో చూడండి. -## కీలక భావనలు +## ముఖ్య భావనలు -### భాగీకరణ వ్యూహం +### భాగాల కట్టడం వ్యూహం -డాక్యుమెంట్లు 300 టోకెన్ల భాగాలుగా విభజించబడతాయి, 30 టోకెన్ల ఓవర్‌లాప్‌తో. ఈ సంతులనం ప్రతి భాగానికి సరిపడిన సందర్భం ఉండేలా చూస్తుంది, అదే సమయంలో బహుళ భాగాలు ప్రాంప్ట్‌లో చేరేలా పరిమితsiz sizeనుంచి ఉండటం. +డాక్యుమెంట్లను 300-టోకెన్ భాగాలుగా విడగొడతారు, వాటి మధ్య 30 టోకెన్ల ఓవర్‌లాప్ ఉంటుంది. ఈ సమతులనం ప్రతి భాగానికి అర్ధంవంతమైన సందర్భం ఉండేలా చూసుకుంటుంది, ఒకే ప్రాంప్ట్‌లో బహుళ భాగాలను చేర్చడానికి పరిమితి పాటిస్తూ. -### సారూప్యత స్కోర్లు +### సాదృశ్య స్కోర్లు -ప్రతీ పొందిన భాగానికి 0 నుండి 1 వరకు సారూప్యత స్కోరు ఉంటుంది, ఇది యూజర్ ప్రశ్నకు ఎంత దగ్గరగా ఉందో సూచిస్తుంది. క్రింది డయాగ్రాం స్కోరు పరిధులను మరియు అవి ఫలితాలను ఫిల్టర్ చేయడానికి ఎలా ఉపయోగిస్తాయో చూపిస్తుంది: +ప్రతి వెతికిన భాగానికి 0 నుండి 1 మధ్య ఒక సాదృశ్య స్కోరు ఉంటుంది, ఇది వినియోగదారు ప్రశ్నను ఎంత దగ్గరగా సరిపోల్చిందో సూచిస్తుంది. క్రింది చిత్రణ స్కోర్ పరిధులను మరియు సిస్టమ్ వాటిని ఫలితాల ఫిల్టరింగ్ కోసం ఎలా ఉపయోగిస్తుందో చూపిస్తుంది: Similarity Scores -*ఈ డయాగ్రామ్ 0 నుండి 1 వరకు స్కోరు పరిధులను చూపిస్తుంది, కనీస సరిహద్దు 0.5 గా ఉంది, ఇది అసంబంధ భాగాలను ఫిల్టర్ చేస్తుంది.* +*ఈ చిత్రణ 0 నుండి 1 వరకు స్కోర్ పరిధులను, మరియు 0.5 కనిష్ఠ సరిహద్దును చూపిస్తుంది, ఇది సంబంధంలేని భాగాలను వడపోత చేస్తుంది.* -స్కోర్లు 0 నుండి 1 వరకు: -- 0.7-1.0: అత్యంత సంబంధిత, సమగ్ర సరిపోలిక +స్కోర్లు 0 నుండి 1 వరకు ఉంటాయి: +- 0.7-1.0: అత్యంత సంబంధితమైన, ఖచ్చిత సరిపోలింపు - 0.5-0.7: సంబంధిత, మంచి సందర్భం -- 0.5 కంటే తక్కువ: ఫిల్టర్ అవ్వబడ్డది, చాలా వ్యత్యాసం +- 0.5కన్నా తక్కువ: వడపోత, చాలా భిన్నమైనది -శ్రేష్ఠత కోసం సిస్టమ్ కనీస సరిహద్దు మించిన భాగాలనేమాత్రం తీసుకుంటుంది. +నాణ్యతను నిర్ధారించేందుకు సిస్టమ్ కనీస సరిహద్దు పై భాగాలను మాత్రమే తెస్తుంది. -ఎంబెడింగ్స్ అర్థం క్లస్టర్లుగా స్పష్టంగా ఉండేటప్పుడు బాగా పనిచేస్తాయి, కానీ వాటికి బ్లైండ్ స్పాట్లు కూడా ఉంటాయి. క్రింది డయాగ్రాం సాధారణ విఫలతా రకాలని చూపిస్తుంది — పెద్ద భాగాలు మగ్గిగల వెక్టర్లు, చిన్న భాగాలు సందర్భం లేకుండా ఉంటాయి, అనిశ్చిత పదాలు బహుళ క్లస్టర్లను సూచిస్తాయి, అసత్య సరిపోలిక లుక్‌అప్స్ (IDs, పార్ట్ నంబర్లు) ఎంబెడింగ్స్‌తో పని చేయవు: +ఎంబెడ్డింగ్స్ అర్థం క్లస్టర్లుగా స్పష్టంగా చెల్లి పనిచేస్తాయి, కానీ వీటికి బ్లైండ్ స్పాట్స్ ఉంటాయి. క్రింది చిత్రణ సాధారణ వైఫల్యాలను చూపిస్తుంది — పెద్ద భాగాలు ముట్టడి వెక్టర్లను కలిగిస్తాయి, చిన్న భాగాలు సందర్భం లేకుండా ఉంటాయి, సందిగ్ధ పదాలు బహుళ క్లస్టర్లకు సూచిస్తాయి, ఖచ్చిత-సరిపోలింపు లుక్అప్స్ (IDs, భాగ నంబర్లు) ఎంబెడ్డింగ్స్‌తో పనిచరించవు: Embedding Failure Modes -*ఈ డయాగ్రాం సాధారణ ఎంబెడింగ్ విఫలతా రకాలని చూపిస్తుంది: పెద్ద భాగాలు, చిన్న భాగాలు, అనిశ్చిత పదాలు, అసత్య సరిపోలిక లుక్‌అప్స్.* +*ఈ చిత్రణ సాధారణ ఎంబెడ్డింగ్ వైఫల్యాలను చూపిస్తుంది: చాలా పెద్ద భాగాలు, చాలా చిన్న భాగాలు, బహుళ క్లస్టర్లను సూచించే సందిగ్ధ పదాలు, మరియు IDs వంటి ఖచ్చిత సరిపోలింపు లుక్అప్స్.* ### ఇన్-మెమరీ స్టోరేజ్ -ఈ మాడ్యూల్ సామాన్యత కోసం ఇన్-మెమరీ స్టోరేజ్‌ను ఉపయోగిస్తుంది. యాప్లికేషన్ రీస్టార్ట్ అవుతున్నప్పుడు అప్‌లోడ్ చేసిన పత్రాలు పోతాయి. ప్రొడక్షన్ సిస్టమ్‌లు Qdrant లేదా Azure AI Search వంటి దృఢమైన వెక్టర్ డేటాబేస్‌లను ఉపయోగిస్తాయి. +ఈ మాడ్యూల్ సరళత కోసం ఇన్-మెమరీ స్టోరేజ్ ను ఉపయోగిస్తుంది. మీరు అప్లికేషన్‌ను మళ్లీ ప్రారంభించినప్పుడు, అప్లోడ్ చేసిన డాక్యుమెంట్లు నశిస్తాయి. ఉత్పత్తి వ్యవస్థలు Qdrant లేదా Azure AI Search వంటి స్థిరమైన వెక్టర్ డేటాబేస్‌లను ఉపయోగిస్తాయి. -### సందర్భ విండో నిర్వహణ +### కాంటెక్స్ట్ విండి నిర్వహణ -ప్రతి మోడల్‌కు గరిష్ట సందర్భ విండో ఉంటుంది. పెద్ద డాక్యుమెంట్ నుంచి ప్రతీ భాగాన్ని చేర్చలేము. సిస్టమ్ టాప్ N అత్యంత సంబంధిత భాగాలను (డిఫాల్ట్ 5) తీసుకుని పరిమితిలో ఉంటూ సరైన జవాబుకు సరిపడిన సందర్భం అందుస్తుంది. +ప్రతి మోడల్‌కు గరిష్ట కాంటెక్స్ట్ విండో ఉంటుంది. ఒక పెద్ద డాక్యుమెంటు నుండి అన్నీ భాగాలను చేర్చలేరు. సిస్టమ్ టాప్ N అత్యంత సంబంధిత భాగాలను (డిఫాల్ట్ 5) తెస్తుంది, పరిమితులలో ఉండటం మరియు ఖచ్చితమైన సమాధానాలకు తగినంత సందర్భం అందించడం కోసం. -## RAG అవసరం ఎప్పుడు +## ఎప్పుడు RAG ఉపయోగించాలి -RAG ఎప్పుడూ సరైన మార్గం కాదు. క్రింది నిర్ణయ మార్గదర్శకం RAG విలువను ఏవంటి సందర్భాలలో జోడించిందో మరియు ఎప్పుడు సులభమైన పద్ధతులు — కంటెంట్ నేరుగా ప్రాంప్ట్‌లో చేర్చడం లేదా మోడల్ భవన జ్ఞానంపై ఆధారపడటం — సరిపోతాయో చూపిస్తుంది: +RAG ప్రతిసారీ సరైన దారినైనది కాదు. క్రింది నిర్ణయ మార్గదర్శకంతో మీరు ఎప్పుడు RAG విలువ కలిగిస్తుందో లేదా ఎప్పుడు సాదారణ విధానాలు - ప్రాంప్ట్‌లో కంటెంట్ చేర్చడం లేదా మోడల్ బిల్ట్-ఇన్ పరిజ్ఞానం ఆధారపడి ఉండటం - సరిపోతాయో తెలుసుకోవచ్చు: When to Use RAG -*ఈ డయాగ్రాం RAG విలువ యప్పుడు జోడించబడుతుందో, మరియు సులభమైన పద్ధతులు యప్పుడు సరిపోతాయో నిర్ణయ మార్గదర్శకం చూపిస్తుంది.* +*ఈ చిత్రణ RAG ఎప్పుడు విలువ జోడిస్తుందో, మరియు ఎప్పుడు సాదా విధానాలు సరిపోతాయో చూపించే నిర్ణయ మార్గదర్శకం.* -## తరువాతి దశలు +## తదుపరి దశలు -**తదుపరి మాడ్యూల్:** [04-tools - AI ఏజెంట్స్ టూల్స్‌తో](../04-tools/README.md) +**తదుపరి మాడ్యూల్:** [04-tools - టూల్స్‌తో AI ఏజెంట్స్](../04-tools/README.md) --- -**నావిగేషన్:** [← మునుపటి: మాడ్యూల్ 02 - ప్రాంప్ట్ ఇంజినీరింగ్](../02-prompt-engineering/README.md) | [ప్రధానంలోకి తిరిగి](../README.md) | [తదుపరి: మాడ్యూల్ 04 - టూల్స్ →](../04-tools/README.md) +**నావిగేషన్:** [← మునుపటి: మాడ్యూల్ 02 - ప్రాంప్ట్ ఇంజనీరింగ్](../02-prompt-engineering/README.md) | [మొదటికి తిరిగి](../README.md) | [తదుపరి: మాడ్యూల్ 04 - టూల్స్ →](../04-tools/README.md) --- -**అంగీకారం**: -ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తూనే ఉన్నప్పటికీ, ఆటోమేటెడ్ అనువాదాలలో లోపాలు లేదా అపరిశుద్ధతలు ఉండవచ్చును. స్థానిక భాషలోని ప్రాథమిక పత్రాన్ని అధికారిక మూలంగా పరిగణించాలి. కీలకమైన సమాచారం కోసం, ప్రొఫెషనల్ మానవ అనువాదాన్ని సలహా ఇస్తాము. ఈ అనువాదం ఉపయోగంచుట వలన వచ్చే ఏ విధమైన తప్పుడు అర్థం లేదా తప్పు అర్థం చేయడాలకు మేము బాధ్యులము కాలేము. +**అస్వీకరణ**: +ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటెడ్ అనువాదాలు తప్పులు లేదా అసమగ్రతలను కలిగి ఉండవచ్చు. దాని స్వదేశ భాషలో ఉన్న అసలు పత్రాన్ని అధికారం కలిగిన మూలంగా పరిగణించాలి. కీలకమైన సమాచారం కోసం, ప్రొఫెషనల్ మానవ అనువాదాన్ని సిఫారసు చేస్తాము. ఈ అనువాదం ఉపయోగం వల్ల కలిగే ఏవైనా అపార్థాలు లేదా తప్పుదారులు కోసం మేము బాధ్యత వహించము. \ No newline at end of file diff --git a/translations/te/04-tools/README.md b/translations/te/04-tools/README.md index a16c079c8..7ecd20c0a 100644 --- a/translations/te/04-tools/README.md +++ b/translations/te/04-tools/README.md @@ -1,76 +1,76 @@ -# మాడ్యూల్ 04: టూల్స్ తో AI ఏజెంట్లు +# Module 04: టూల్స్‌తో AI ఏజెంట్స్ -## కంటెంట్ పట్టిక +## Table of Contents -- [వీడియో వాక్‌థ్రూ](../../../04-tools) -- [మీరు నేర్చుకోనున్నవి](../../../04-tools) -- [ముందస్తు అవసరాలు](../../../04-tools) -- [టూల్స్ తో AI ఏజెంట్లను అర్థం చేసుకోవడం](../../../04-tools) -- [టూల్ కాలింగ్ ఎలా పనిచేస్తుంది](../../../04-tools) - - [టూల్ నిర్వచనాలు](../../../04-tools) - - [సিদ্ধాంత నిర్ణయం](../../../04-tools) - - [నిర్వాహణ](../../../04-tools) - - [స్పందన విడుదల](../../../04-tools) - - [ఆర్కిటెక్చర్: స్ప్రింగ్ బూట్ ఆటో-వైరింగ్](../../../04-tools) -- [టూల్ చైనింగ్](../../../04-tools) -- [అప్లికేషన్ నడిపించండి](../../../04-tools) -- [అప్లికేషన్ ఉపయోగించడం](../../../04-tools) - - [సరళ టూల్ వినియోగం ప్రయత్నించండి](../../../04-tools) - - [టెస్టు టూల్ చైనింగ్](../../../04-tools) - - [సమావేయం ప్రవాహం చూడండి](../../../04-tools) - - [వివిధ అభ్యర్థనలతో ప్రయోగం చేయండి](../../../04-tools) -- [ప్రధాన సూత్రాలు](../../../04-tools) - - [ReAct నమూనా (తర్కాన్విత చర్యలు)](../../../04-tools) - - [టూల్ వివరణలు ముఖ్యమైనవి](../../../04-tools) - - [సెషన్ నిర్వహణ](../../../04-tools) - - [పొరపాట్ల హ్యాండ్లింగ్](../../../04-tools) -- [లభ్యమయ్యే టూల్స్](../../../04-tools) -- [ఎప్పుడు టూల్-ఆధారిత ఏజెంట్లు ఉపయోగించాలి](../../../04-tools) -- [టూల్స్ vs RAG](../../../04-tools) -- [తరవాతి దశలు](../../../04-tools) +- [వీడియో వాక్‌త్రూ](#వీడియో-వాక్‌త్రూ) +- [మీరు నేర్చుకునేది](#మీరు-నేర్చుకునేది) +- [అవసరాలు](#అవసరాలు) +- [టూల్స్‌తో AI ఏజెంట్స్‌ను అర్థం చేసుకునుకుందాం](#టూల్స్‌తో-ai-ఏజెంట్స్‌ను-అర్థం-చేసుకోవడం) +- [టూల్ కాలింగ్ ఎలా పనిచేస్తుంది](#టూల్-కాలింగ్-ఎలా-పనిచేస్తుంది) + - [టూల్ నిర్వచనాలు](#టూల్-నిర్వచనాలు) + - [నిర్ణయం తీసుకోవడం](#నిర్ణయం-తీసుకోవడం) + - [నిర్వహణ](#నిర్వహణ) + - [ప్రతిస్పందన తయారీ](#ప్రతిస్పందన-తయారీ) + - [ఆర్కిటెక్చర్: స్ప్రింగ్ బూట్ ఆటో-వైరింగ్](#ఆర్కిటెక్చర్-స్ప్రింగ్-బూట్-ఆటో-వైరింగ్) +- [టూల్ చైన్ చేయడం](#టూల్-చైనింగ్) +- [అప్లికేషన్‌ను నడపండి](#అప్లికేషన్‌ను-నడపండి) +- [అప్లికేషన్ ఉపయోగించడం](#అప్లికేషన్-వినియోగం) + - [సాదా టూల్ ఉపయోగాన్ని ప్రయత్నించండి](#సాదారణ-టూల్-వినియోగాన్ని-ప్రయత్నించండి) + - [టూల్ చైనింగ్‌ను పరీక్షించండి](#టూల్-చైనింగ్‌ను-పరీక్షించండి) + - [సంబాషణ ప్రవాహాన్ని చూడండి](#సంభాషణ-ప్రవాహాన్ని-చూడండి) + - [వివిధ అభ్యర్థనలతో ప్రయోగించండి](#వేరే-వివిధ-అభ్యర్థనలను-ప్రయత్నించండి) +- [ప్రధాన భావనలు](#ముఖ్య-భావనలు) + - [ReAct ప్యాటర్న్ (పైచర్య మరియు అమలు)](#react-నమూనా-తర్కం-మరియు-చర్య) + - [టూల్ వివరణల ప్రభావం](#టూల్-వివరణలు-ముఖ్యం) + - [సెషన్ నిర్వహణ](#సెష‌న్-మేనేజ్మెంట్) + - [లోపాలు నిర్వహణ](#లోపాల-నిర్వహణ) +- [లభ్యమయ్యే టూల్స్](#అందుబాటులో-ఉన్న-టూల్స్) +- [ఎప్పుడు టూల్ ఆధారిత ఏజెంట్స్ ఉపయోగించాలి](#టూల్-ఆధారిత-ఏజెంట్లను-ఎప్పుడు-ఉపయోగించాలి) +- [టూల్స్ vs RAG](#టూల్స్-వర్సస్-rag) +- [మరో అడుగులు](#తదుపరి-దశలు) -## వీడియో వాక్‌థ్రూ +## వీడియో వాక్‌త్రూ -ఈ మాడ్యూల్‌ను ప్రారంభించడం ఎలా అన్నది వివరించే లైవ్ సెషన్ చూడండి: +ఈ మాడ్యూల్ ప్రారంభించడానికి ఎలా అన్నది వివరిస్తున్న ఈ ప్రత్యక్ష సెషన్ చూడండి: -AI Agents with Tools and MCP - Live Session +టూల్స్‌తో AI ఏజెంట్స్ మరియు MCP - ప్రత్యక్ష సెషన్ -## మీరు నేర్చుకోనున్నవి +## మీరు నేర్చుకునేది -ఇప్పటి వరకు మీరు AI తో సంభాషణలు ఎలా చేయాలో, ప్రాంప్ట్స్‌ను ప్రభావవంతంగా ఎలా నిర్మించాలో, మరియు మీ డాక్యుమెంట్లలో ఆధారంగా సమాధానాలు ఎలా ఇవ్వాలో నేర్చుకున్నారు. కానీ వుందని ఒక బహుళమైన పరిమితి ఉంది: భాషా మోడల్స్ కేవలం టెక్స్ట్‌ను మాత్రమే ఉత్పత్తి చేయగలవు. అవి వాతావరణం తనిఖీ చేయడం, లెక్కలు చేయడం, డేటాబేస్‌లను దరఖాస్తు చేయడం, లేదా బాహ్య వ్యవస్థలతో పరస్పర చర్య చేయలేవు. +ఇప్పటి వరకు, మీరు AIతో సంభాషణలు చేసే విధానం, ప్రాంప్ట్‌లను ప్రభావవంతంగా నిర్మించడం, మరియు మీ డాక్యుమెంట్లలోని ప్రత్యుత్తరాలను బలపరిచే విధానం నేర్చుకున్నారు. కానీ ఇంతవరకు ఒక ప్రాథమిక పరిమితి ఉంది: భాషా మోడల్స్ కేవలం టెక్స్ట్‌ని మాత్రమే ఉత్పత్తి చేయగలవు. అవి వాతావరణాన్ని తనిఖీ చేయలేవు, గణనలు చేయలేవు, డేటాబేస్‌లను ప్రశ్నించలేవు, లేదా బాహ్య వ్యవస్థలతో సహకరించలేవు. -టూల్స్ దీన్ని మార్చేస్తాయి. మోడల్‌కు కాల్ చేయడానికి ఫంక్షన్లను ఇచ్చి, మీరు దాన్ని టెక్స్ట్ ఉత్పత్తిదారుడి నుండి చర్యలు చేయగల ఏజెంట్‌గా మారుస్తారు. మోడల్ ఎప్పుడు టూల్ అవసరం ఉందో, ఏ టూల్ ఉపయోగించాలో, మరియు ఏ పరామితులు పంపాలో నిర్ణయిస్తుంది. మీ కోడ్ ఆ ఫంక్షన్‌ను అమలు చేస్తుంది మరియు ఫలితాన్ని తిరిగి ఇస్తుంది. మోడల్ ఆ ఫలితాన్ని తన స్పందనలో చేర్చుతుంది. +టూల్స్ ఈ పరిస్థితిని మార్చతాయి. మోడలుకు కాల్ చేయగల ఫంక్షన్‌లు అందించడం ద్వారా, మీరు దాన్ని ఒక టెక్స్ట్ జనరేటర్ నుండి చర్యలు తీసుకోగల ఏజెంట్గా మార్చుతారు. మోడల్ ఎప్పుడు టూల్ అవసరమో, ఏ టూల్ ఉపయోగించాలో, ఏ పరామితులు అందించాలో నిర్ణయిస్తుంది. మీరు కోడ్ ఆ ఫంక్షన్‌ను అమలు చేసి ఫలితాన్ని తిరిగి ఇస్తారు. మోడల్ ఆ ఫలితాన్ని తాను ఇచ్చే ప్రతిస్పందనలో చేర్చుకుంటుంది. -## ముందస్తు అవసరాలు +## అవసరాలు -- పూర్తి చేసిన [మాడ్యూల్ 01 - పరిచయం](../01-introduction/README.md) (Azure OpenAI వనరులు అమర్చబడ్డాయి) -- సూచించిన మునుపటి మాడ్యూల్స్ పూర్తి చేసినవి (ఈ మాడ్యూల్ టూల్స్ vs RAG నుండి [RAG కాన్సెప్ట్‌లు మాడ్యూల్ 03 నుండి](../03-rag/README.md) సూచిస్తుంది) -- రూట్ డైరెక్టరీలో `.env` ఫైల్ Azure సర్టిఫికెట్లతో (Module 01 లో `azd up` ద్వారా సృష్టించబడింది) +- [Module 01 - 소개](../01-introduction/README.md) పూర్తిచేసి ఉంటే (Azure OpenAI వనరులు పనిచేసేటట్లు) +- గత మాడ్యూల్స్‌ను పూర్తి చేసుకోవడం సిఫార్సు (ఈ మాడ్యూల్ [Module 03 లోని RAG కాన్సెప్ట్‌లు](../03-rag/README.md) ని టూల్స్ vs RAGలో సూచిస్తుంది) +- రూట్ డైరెక్టరీలో `.env` ఫైల్ ఉండాలి (Module 01 లో `azd up` ద్వారా సృష్టించబడింది) -> **గమనిక:** మాడ్యూల్ 01 పూర్తి చేయకపోయినట్లయితే, మొదట అక్కడని అమరణ సూచనలను అనుసరించండి. +> **గమనిక:** మీరు Module 01 పూర్తిచేయకపోతే, ముందుగా అక్కడ ఇచ్చిన డిప్లాయ్‌మెంట్ సూచనలు పాటించండి. -## టూల్స్ తో AI ఏజెంట్లను అర్థం చేసుకోవడం +## టూల్స్‌తో AI ఏజెంట్స్‌ను అర్థం చేసుకోవడం -> **📝 గమనిక:** ఈ మాడ్యూల్లో "ఏజెంట్లు" పదం టూల్-కాలింగ్ సామర్థ్యాలతో ఇంకా మెరుగుపర్చబడిన AI అసిస్టెంట్లను సూచిస్తుంది. ఇది [మాడ్యూల్ 05: MCP](../05-mcp/README.md) లో మేము కవర్ చేసే **Agentic AI** నమూనాల నుండి వేరుగా ఉంటుంది (స్వతంత్ర ఏజెంట్లు, ప్లానింగ్, మెమరీ మరియు బహుళ-దశ తర్కం). +> **📝 గమనిక:** ఈ మాడ్యూల్‌లో "ఏజెంట్స్" అనే పదం టూల్-కాలింగ్ సామర్థ్యాలతో మెరుగుపరిచిన AI సహాయకులను సూచిస్తుంది. ఇది [Module 05: MCP](../05-mcp/README.md) లో చర్చించే **Agentic AI** ప్యాటర్న్స్ (స్వతంత్ర ఏజెంట్స్ మెమరీ, ప్లానింగ్, బహుళ-దశ తర్కం తో) నుండి భిన్నంగా ఉంది. -టూల్స్ లేకపోతే, ఒక భాషా మోడల్ కేవలం తన సెర్చిత డేటా నుండి టెక్స్ట్ ఉత్పత్తి చేయగలదు. ప్రస్తుత వాతావరణాన్ని అడగండి, అది ఊహించాల్సి ఉంటుంది. టూల్స్ ఇచ్చినప్పుడు, అది వాతావరణ API కాల్ చేయగలదు, లెక్కలు చేయవచ్చు, లేదా డేటాబేస్‌ను ప్రశ్నించవచ్చు — ఆ నిజ ఫలితాలను తన ప్రతిస్పందనలో చేర్చుతుంది. +టూల్స్ లేకపోతే, భాషా మోడల్ తన శిక్షణ డేటా నుండి మాత్రమే టెక్స్ట్ ఉత్పత్తి చేయగలదు. ప్రస్తుత వాతావరణం ఏమిటి అని అడిగితే, అది అంచనా వేయాలి. టూల్స్ ఉన్నప్పుడు, అది వాతావరణ APIని కాల్ చేయగలదు, గణనలు చెయ్యగలదు, లేదా డేటాబేస్‌ను ప్రశ్నించగలదు — ఆ నిజమైన ఫలితాలను తన ప్రతిస్పందనలో మిళితం చేస్తుంది. -Without Tools vs With Tools +టూల్స్ లేకపోతే vs టూల్స్ ఉన్నప్పుడు -*టూల్స్ లేకపోతే మోడల్ ఊహించాలి — టూల్స్ ఉన్నప్పుడు ఇది APIs కాల్ చేయగలదు, లెక్కలు నిర్వహించగలదు, మరియు రియల్-టైమ్ డేటా అందించగలదు.* +*టూల్స్ లేకపోతే మోడల్ అంచనా వేయాలి — టూల్స్ తోadhi APIsను కాల్ చేస్తుంది, గణనలు చేస్తుంది, మరియు రియల్-టైమ్ డేటాను అందిస్తుంది.* -ఒక టూల్స్ తో AI ఏజెంట్ **తర్కం మరియు చర్య (ReAct)** నమూనాను అనుసరిస్తుంది. మోడల్ కేవలం ప్రతిస్పందించదు — అది ఏమి అవసరమో ఆలోచిస్తుంది, టూల్ కాలింగ్ ద్వారా చర్య తీసుకుంటుంది, ఫలితాన్ని పరిశీలిస్తుంది, ఆపై మరలా చర్య తీసుకోవాలా లేదా ఫైనల్ సమాధానం ఇవ్వాలా నిర్ణయించుకుంటుంది: +టూల్స్‌తో AI ఏజెంట్ ఒక **Reasoning and Acting (ReAct)** ప్యాటర్న్ అనుసరిస్తుంది. మోడల్ కేవలం ప్రతిస్పందించడు — అది ఏమి అవసరమో ఆలోచిస్తుంది, టూల్‌ను కాల్ చేసి చర్యలు చేస్తుంది, ఫలితాన్ని పర్యవేక్షించి, మళ్లీ పర్యవేక్షణ లేదా తుది సమాధానం ఇవ్వాలని నిర్ణయిస్తుంది: -1. **తర్కం** — ఏజెంట్ వినియోగదారు ప్రశ్నను విశ్లేషించి అవసరమైన సమాచారాన్ని నిర్ధారిస్తుంది -2. **చర్య** — ఏజెంట్ సరైన టూల్ ఎంచుకొని, సరైన పారామితులను రూపొందించి కాల్ చేస్తుంది -3. **పరిశీలన** — ఏజెంట్ టూల్ ఔట్పుట్‌ని పొందించి ఫలితాన్ని అంచనా వేస్తుంది -4. **పునర్వంధన లేదా స్పందన** — మరింత డేటా అవసరమైతే, ఏజెంట్ తిరిగి ఇస్తుంది; లేకపోతే సహజ భాషలో సమాధానం తయారుచేస్తుంది +1. **తర్కించు** — యూజర్ ప్రశ్నను విశ్లేషించి ఏ సమాచారం అవసరమో నిర్ణయించు +2. **చర్య చేయి** — సరైన టూల్ ఎంచుకుని సరైన పరామితులతో కాల్ చేయి +3. **పర్యవేక్షించు** — టూల్ అవుట్పుట్ పొందిన తర్వాత ఫలితాన్ని అంచనా వేడు +4. **మళ్లీ చేయి లేదా ప్రతిస్పందించు** — మరిన్ని డేటా అవసరమైతే మళ్లీ ప్రయత్నించు; లేకపోతే సహజ భాషలో సమాధానం తయారు చేయి -ReAct Pattern +ReAct ప్యాటర్న్ -*ReAct చక్రం — ఏజెంట్ ఏం చేయాలో తర్కం, టూల్‌ను కాల్ చేసి చర్య, ఫలితాన్ని పరిశీలన, మరియు ఫైనల్ సమాధానం ఇవ్వగలిగే వరకూ పునరావృతం.* +*ReAct చక్రం — ఏజెంట్ ఏ పనులు చేయాలో తర్కించును, టూల్‌ను కాల్ చేస్తుంది, ఫలితాన్ని పర్యవేక్షించి, తుది సమాధానం ఇవ్వగలిగేవరకు ఇదే ప్రక్రియను కొనసాగిస్తుంది.* -ఇది స్వయంచాలకంగా జరుగుతోంది. మీరు టూల్స్ మరియు వాటి వివరణలు నిర్వచిస్తారు. మోడల్ ఎప్పుడు, ఎలా ఉపయోగించాలో నిర్ణయాన్ని తగిలిస్తుంది. +ఇది ఆటోమేటిక్‌గా జరుగుతుంది. మీరు టూల్స్ మరియు వాటి వివరణలను నిర్వచిస్తారు. మోడల్ ఎప్పుడు మరియు ఎలా వాటిని వాడాలో తర్కించడాన్ని నిర్వహిస్తుంది. ## టూల్ కాలింగ్ ఎలా పనిచేస్తుంది @@ -78,7 +78,7 @@ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -మీరు స్పష్టమైన వివరణలు మరియు పారామీటర్ వివరాలతో ఫంక్షన్లను నిర్వచిస్తారు. మోడల్ ఈ వివరణలను తన సిస్టమ్ ప్రాంప్ట్‌లో చూస్తుంది మరియు ప్రతి టూల్ ఏమి చేస్తుందో అర్థం చేసుకుంటుంది. +మీరు క్లియర్ వివరణలు మరియు పారామితి స్పెసిఫికేషన్లతో ఫంక్షన్లను నిర్వచిస్తారు. మోడల్ ఈ వివరణలను తన సిస్టమ్ ప్రాంప్ట్‌లో చూసి, ప్రతి టూల్ ఏ పని చేస్తుందో అర్థం చేసుకుంటుంది. ```java @Component @@ -96,292 +96,292 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// అసిస్ట్ Spring Boot ద్వారా ఆటోమేటిక్‌గా వైర్డ్ చేయబడింది: +// అసిస్టెంట్ స్వయంచాలకంగా Spring Boot ద్వారా వైర్డ్ చేయబడింది: // - ChatModel బీన్ -// - @Component క్లాసుల నుండి అన్ని @Tool మেথడ్లు +// - @Component తరగతుల నుండి అన్ని @Tool పద్ధతులు // - సెషన్ నిర్వహణ కోసం ChatMemoryProvider ``` - -కింద డాగ్రామ్ ప్రతి అనోటేషన్‌ను పగలబెడుతుంది మరియు AI టూల్‌ను ఎప్పుడు కాల్ చేయాలో, ఎలాంటి ఆర్గ్యుమెంట్లను పంపాలో అర్థం చేసుకోవడంలో ఏ విధంగా సహాయం చేస్తుందో చూపిస్తుంది: -Anatomy of Tool Definitions +క్రింద డయాగ్రామ్ ప్రతి గుణాన్ని విడదీసి చూపిస్తుంది, ఏ భాగం AIకి ఎప్పుడు టూల్ కాల్ చేయాలో, ఏ ఆర్గ్యుమెంట్స్ అందించాలో అర్థం చేసుకోవడానికి ఎలా సహాయపడుతుందో వివరించబడింది: -*టూల్ నిర్వచన నిర్మాణం — @Tool AI కి ఎప్పుడు ఉపయోగించాలో సూచిస్తుంది, @P ప్రతి పారామీటర్‌ని వివరిస్తుంది, మరియు @AiService స్టార్టప్లో అంతింటినీ సకాలంలో వైర్ చేస్తుంది.* +టూల్ నిర్వచనాల నిర్మాణం -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్‌తో ప్రయత్నించండి:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) తెరవండి మరియు అడగండి: -> - " реальные వాతావరణ API గా OpenWeatherMap ని మాక్ డేటా బదులు ఎలా ఇంటిగ్రేట్ చేయండి?" -> - "ఏరి AI టూల్ ని సరిగ్గా ఉపయోగించేందుకు మంచి టూల్ వివరణ ఏమి కావాలి?" -> - "టూల్ అమల్‌లో API పొరపాట్లు మరియు రేట్ పరిమితులు ఎలా హ్యాండిల్ చేయాలి?" +*టూల్ నిర్వచన నిర్మాణం — @Tool AIకి ఎప్పుడు ఉపయోగించాలో చెబుతుంది, @P ప్రతి పారామితిని సూచిస్తుంది, మరియు @AiService ప్రారంభ సమయంలో వాటిని యథాతథంగా కनेक్ట్ చేస్తుంది.* -### సిద్ధాంత నిర్ణయం +> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్‌తో ప్రయత్నించండి:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) ఫైల్ తెరవండి మరియు అడగండి: +> - "మాక్ డేటా కాకుండా వాస్తవ వాతావరణ API OpenWeatherMapను ఎలా ఇంటిగ్రేట్ చేయాలి?" +> - "AI దాన్ని సరికదా ఉపయోగించేందుకు బాగున్న టూల్ వివరణ ఎలా ఉండాలి?" +> - "టూల్ అమలులో API లోపాలు మరియు రేట్ లిమిట్స్‌ను ఎలా నిర్వహించాలి?" -వినియోగదారు "సియాటిల్‌లో వాతావరణం ఎలా ఉంది?" అని అడగగా, మోడల్ యాదృచ్చికంగా టూల్ ఎంచుకోదు. ఇది వినియోగదారు ఉద్దేశాన్ని అందుబాటులో ఉన్న ప్రతి టూల్ వివరణతో పోల్చి, సంబంధిత స్కోర్ ఇస్తుంది మరియు ఉత్తమ మ్యాచ్ ఎంచుకుంటుంది. ఆపై సరైన పారామితులతో నిర్మితమైన ఫంక్షన్ కాల్‌ను రూపొందిస్తుంది — ఈ సందర్భంలో `location` ను `"Seattle"` గా సెట్ చేస్తుంది. +### నిర్ణయం తీసుకోవడం -వినియోగదారు అభ్యర్థనకు ఏ ٹూల్ సరిపోదంటే, మోడల్ తన స్వంత జ్ఞానంతో సమాధానం ఇస్తుంది. పలు టూల్స్ సరిపోతేనయితే, అత్యంత ప్రత్యేకమైనదాన్ని ఎంచుకుంటుంది. +యూజర్ "సియాటిల్‌లో వాతావరణం ఎలా ఉంది?" అని అడిగినపుడు, మోడల్ ఏదైనా టూల్ చుట్టూ తారుమారు ఒకటిని ఎంచుకోదు. ఇది యూజర్ ఉద్దేశ్యాన్ని అందుబాటులో ఉన్న ప్రతి టూల్ వివరణతో పోల్చుతుంది, ప్రతీదిని ప్రాధాన్యతకు స్కోరింగ్ చేసి ఉత్తమాన్ని ఎంచుకుంటుంది. ఆ పాక్షికంగా ఒక స్ట్రక్చర్డ్ ఫంక్షన్ కాల్‌ను జనరేట్ చేసి సరైన పారామితులు అందిస్తుంది — ఈ సందర్భంలో `location` ను `"Seattle"` గా సెట్ చేస్తుంది. -How the AI Decides Which Tool to Use +యూజర్ అభ్యర్థనకు సరిపోని టూల్ దొరకపోతే, మోడల్ తనకు తెలిసిన పరిజ్ఞానం నుండి సమాధానం ఇస్తుంది. క్షేత్రంలో పలు టూల్స్ అనుకూలిస్తే, ఇది అత్యంత ప్రత్యేకమైనదాన్ని ఎంచుకుంటుంది. -*మోడల్ ప్రతి అందుబాటులో ఉన్న టూల్‌ను వినియోగదారు ఉద్దేశానికి ఎదురుగా అంచనా వేస్తుంది మరియు ఉత్తమ మ్యాచ్ను ఎన్నుకుంటుంది — అందుచేత స్పష్టమైన, నిర్దిష్ట టూల్ వివరణలు చాలా ముఖ్యం.* +AI ఎటువంటి టూల్ ఉపయోగించాలో ఎలా నిర్ణయిస్తుంది + +*మోడల్ యూజర్ ఉద్దేశ్యంతో ప్రతీ టూల్‌ను పరిశీలించి ఉత్తమం ఎంచుకుంటుంది — అందుకనే స్పష్టంగా, ప్రత్యేకంగా టూల్ వివరణలు ఉండటం ముఖ్యం.* ### నిర్వహణ [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -స్ప్రింగ్ బూట్ డిక్లరేటివ్ `@AiService` ఇంటర్‌ఫేస్ను అన్ని రిజిస్టర్ అయిన టూల్స్‌తో ఆటో-వైరింగ్ చేస్తుంది, మరియు LangChain4j టూల్ కాల్స్ ని ఆటోమేటిక్ గా అమలు చేస్తుంది. వాడుకరి సహజ భాషా ప్రశ్న నుండి సహజ భాష సమాధానం వరకు సంపూర్ణ టూల్ కాల్ ఆరు దశల్లో సాగుతుంది: +స్ప్రింగ్ బూట్ `@AiService` ఇంటర్ఫేస్‌ను రిజిస్టర్డ్ టూల్స్‌తో ఆటోమేటిక్‌గా వైర్ చేస్తుంది, మరియు LangChain4j టూల్ కాల్స్ ఆటోమేటిక్ చాటుతుంది. లైన్ వెనుక, ఒక పూర్తి టూల్ కాల్ ఆరు దశల ద్వారా ప్రవహిస్తుంది — యూజర్ సహజ భాషా ప్రశ్న నుండి తుది సహజ భాషా సమాధానం వరకూ: -Tool Calling Flow +టూల్ కాలింగ్ ఫ్లో -*పూర్తి ప్రవాహం — వాడుకరి ప్రశ్న అడుగుతాడు, మోడల్ టూల్ ఎంచుకుంటుంది, LangChain4j దాన్ని అమలు చేస్తుంది, మోడల్ ఫలితాన్ని సహజ భాషా ప్రతిస్పందనలో చేర్చుతుంది.* +*మొత్తం ఫ్లో — యూజర్ ప్రశ్న అడుగుతాడు, మోడల్ టూల్ ఎంచుకుంటుంది, LangChain4j దాన్ని అమలు చేస్తుంది, మోడల్ ఫలితాన్ని సహజ భాషా ప్రతిస్పందనలో చేర్చుతుంది.* -మీరు మాడ్యూల్ 00లో [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) నడిపించి ఉంటే, మీరు ఇదే నమూనాను చూశారు — `Calculator` టూల్స్ కూడా ఇదే విధంగా కాల్ చేయబడ్డాయి. క్రింది సీక్వెన్స్ డయాగ్రామ్ లో ఆ డెమోలో ఏమి జరిగిందో కచ్చితంగా చూపిస్తుంది: +లైన్ వెనుక `AiServices` ఏ టూల్ కోసం అయినా అదే కాలింగ్ లూప్ నడుపుతుంది — ఇక్కడ సులభమైన `Calculator` తో చూపబడింది. క్రింది సీక్వెన్స్ డయాగ్రామ్ లోపల ఏమి జరుగుతుందో వివరంగా చూపిస్తుంది: -Tool Calling Sequence Diagram +టూల్ కాలింగ్ సీక్వెన్స్ డయాగ్రామ్ -*క్విక్ స్టార్ట్ డెమోలో టూల్-కాల్ లూప్ — `AiServices` మీ సందేశం మరియు టూల్ స్కీమాలను LLM కి పంపుతుంది, LLM `add(42, 58)` వంటి ఫంక్షన్ కాల్ తో సమాధానం ఇస్తుంది, LangChain4j లోకల్ గా `Calculator` విధానాన్ని అమలు చేస్తుంది, ఫలితాన్ని తిరిగి అర్థం చేసుకొని చివరి సమాధానానికి ఉపయోగిస్తుంది.* +*టూల్ కాలింగ్ లూప్ — `AiServices` మీ సందేశం మరియు టూల్ స్కీమాలను LLMకి పంపుతుంది, LLM `add(42, 58)` లాంటి ఫంక్షన్ కాల్‌తో ప్రత్యుత్తరం ఇస్తుంది, LangChain4j లోకల్ గా `Calculator` మెథడ్ అమలు చేసి ఫలితాన్ని తుది సమాధానానికి తిరిగి ఇస్తుంది.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్‌తో ప్రయత్నించండి:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) తెరవండి మరియు అడగండి: -> - "ReAct నమూనా ఎలా పనిచేస్తుంది మరియు AI ఏజెంట్లు దానికి ఎందుకు సమర్ధవంతంగా ఉన్నారు?" -> - "ఏజెంట్ ఏ టూల్ ఎంచుకోవాలో, ఎలాంటి క్రమంలో ఉపయోగించాలో ఎలా నిర్ణయిస్తాడు?" -> - "టూల్ అమలు విఫలం కాకపోతే ఏం జరుగుతుంది - పొరపాట్లను పటిష్టంగా ఎలా హ్యాండిల్ చేయాలి?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) చాట్‌తో ప్రయత్నించండి:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) ఫైల్ తెరవండి మరియు అడగండి: +> - "ReAct ప్యాటర్న్ ఎలా పని చేస్తుంది మరియు AI ఏజెంట్స్ కోసం ఇది సమర్థవంతమే ఎందుకు?" +> - "ఏజెంట్ ఏ టూల్ ఎప్పుడు ఉపయోగించాలో ఎటువంటి క్రమంలో నిర్ణయిస్తుంది?" +> - "టూల్ అమలు విఫలమైతే ఏమవుతుంది - లోపాలను మేనేజ్ చేయడం ఎలా చేయాలి?" -### స్పందన విడుదల +### ప్రతిస్పందన తయారీ -మోడల్ వాతావరణ డేటాను అందుకొని దానిని సహజ భాషా ప్రతిస్పందనగా వినియోగదారుని కోసం మాడ్జులేట్ చేస్తుంది. +మోడల్ వాతావరణ డేటాను స్వీకరించి యూజర్‌కి సహజ భాషలో ప్రతిస్పందనగా రూపొందిస్తుంది. ### ఆర్కిటెక్చర్: స్ప్రింగ్ బూట్ ఆటో-వైరింగ్ -ఈ మాడ్యూల్ LangChain4j యొక్క స్ప్రింగ్ బూట్ ఇంటిగ్రేషన్ ను `@AiService` డిక్లరేటివ్ ఇంటర్‌ఫేస్లతో ఉపయోగిస్తుంది. స్టార్టప్ లో స్ప్రింగ్ బూట్ ప్రతి `@Component` జాబితా చేసిన `@Tool` పద్ధతులతో పాటు మీ `ChatModel` బీన్, మరియు `ChatMemoryProvider` చూడగలదు — అప్పుడు అన్ని వాటిని ఒకే `Assistant` ఇంటర్‌ఫేసులో బహుళ కోడ్ లేకుండా వైర్ చేస్తుంది. +ఈ మాడ్యూల్ LangChain4j యొక్క స్ప్రింగ్ బూట్ సంయోజనంతో `@AiService` డిక్లరేటివ్ ఇంటర్ఫేస్‌లను ఉపయోగిస్తుంది. ప్రారంభంలో స్ప్రింగ్ బూట్ ఈ `@Tool` మెథడ్‌లున్న ప్రతీ `@Component`, మీ `ChatModel` బీన్, మరియు `ChatMemoryProvider` ని కనుగొని సున్నా బాయిలర్‌ప్లేట్‌తో ఒకే `Assistant` ఇంటర్ఫేస్‌కు వైర్ చేస్తుంది. -Spring Boot Auto-Wiring Architecture +Spring Boot ఆటో-వైరింగ్ ఆర్కిటెక్చర్ -*@AiService ఇంటర్‌ఫేస్ చాట్‌మోడల్, టూల్ భాగాలు మరియు మెమరీ ప్రొవైడర్‌ను కలిపి స్ప్రింగ్ బూట్ అన్ని వైరింగ్‌ను ఆటోమేటిక్ గా నిర్వహిస్తుంది.* +*@AiService ఇంటర్ఫేస్ ChatModel, టూల్ కంపోనెంట్స్, మెమరీ ప్రొవైడర్‌ని కలిపి స్ప్రింగ్ బూట్ ఆటోమేటిక్‌గా వైర్ చేస్తుంది.* -క్రింది పూర్తి అభ్యర్థన జీవిత చక్రాన్ని సీక్వెన్స్ డయాగ్రామ్‌గా చూడండి — HTTP అభ్యర్థన నుండి కంట్రోలర్, సర్వీస్, ఆటో-వైర్డ్ ప్రాక్సీ వరకు, आखिरڪار టూల్ అమలుకు తిరిగి వస్తుంది: +完整的 درخواست జీవన చక్రం సీక్వెన్స్ డయాగ్రామ్ ఇక్కడ ఉంది — HTTP రిక్వెస్ట్ నుండి కంట్రోలర్, సర్వీస్, ఆటో-వైర్డ్ ప్రాక్సీ, టూల్ అమలుకి వెనక్కి వచ్చేవరకు: -Spring Boot Tool Calling Sequence +Spring Boot టూల్ కాలింగ్ సీక్వెన్స్ -*సంపూర్ణ స్ప్రింగ్ బూట్ అభ్యర్థన జీవితం — HTTP అభ్యర్థన కంట్రోలర్, సర్వీస్ ద్వారా డైరెక్ట్ అయ్యి ఆటో-వైర్డ్ అసిస్టెంట్ ప్రాక్సీకి వెళుతుంది, ఇది LLM మరియు టూల్ కాల్స్‌ని ఆటోమేటిక్ గా సమన్వయపరుస్తుంది.* +*పూర్తి స్ప్రింగ్ బూట్ రిక్వెస్ట్ జీవన చక్రం — HTTP రిక్వెస్ట్ కంట్రోలర్ మరియు సర్వీస్ ద్వారా ఆటో-వైర్డ్ అసిస్టెంట్ ప్రాక్సీకు ప్రవహిస్తుంది, ఇది LLM మరియు టూల్ కాల్స్‌ను ఆటోమేటిక్‌గా నిర్వహిస్తుంది.* -ఈ పద్ధతి యొక్క ముఖ్య ప్రయోజనాలు: +ఈ యాప్రోచ్ యొక్క ప్రధాన లాభాలు: -- **స్ప్రింగ్ బూట్ ఆటో-వైరింగ్** — చాట్‌మోడల్ మరియు టూల్స్ ఆటోమేటిక్ ఇంజెక్షన్ -- **@MemoryId నమూనా** — ఆటోమేటిక్ సెషన్ ఆధారిత మెమరీ నిర్వహణ -- **ఒక్కటి మాత్రమే ఉత్పత్తి** — అసిస్టెంట్ ఒక్కసారి సృష్టించి మెరుగైన పనితీరు కోసం పునర్వినియోగం -- **టైప్-సేఫ్ నిర్వహణ** — జావా పద్ధతులు టైప్ మార్పిడి తో నేరుగా పిలవబడతాయి -- **బహుళ-టర్న్ ఆర్కెస్ట్రేషన్** — టూల్ చైనింగ్ ని ఆటోమేటిక్ గా నిర్వహిస్తుంది -- **జీరో బోయిలర్‌ ప్లేట్** — మాన్యువల్ `AiServices.builder()` కాల్స్ లేదా మెమరీ హాష్‌మ్యాప్ అవసరం లేదు +- **స్ప్రింగ్ బూట్ ఆటో-వైరింగ్** — ChatModel మరియు టూల్స్ ఆటోమేటిక్ ఇంజెక్షన్ +- **@MemoryId ప్యాటర్న్** — ఆటోమేటిక్ సెషన్ ఆధారిత మెమరీ నిర్వహణ +- **ఒకే ఉదాహరణ** — అసిస్టెంట్ ఒక్కసారి సృష్టించి పనితీరు మెరుగ్గా ఉపయోగించడం +- **టైప్-సేఫ్ అమలు** — టైప్ కన్వర్షన్‌తో జావా మెథడ్స్ నేరుగా పిలవబడతాయి +- **బహుళ-టర్న్ ఆర్కిస్ట్రేషన్** — టూల్ చైనింగ్ ఆటోమేటిక్ నిర్వహణ +- **జీరో బాయిలర్‌ప్లేట్** — మాన్యువల్ `AiServices.builder()` లేదా మెమరీ HashMap అవసరం లేదు -వేరే పద్ధతులు (`AiServices.builder()` మాన్యువల్) ఎక్కువ కోడ్ అవసరం మరియు స్ప్రింగ్ బూట్ ఇంటిగ్రేషన్ ప్రయోజనాలు లేవు. +మరో మార్గాలు (`AiServices.builder()` మానువల్ ఉపయోగం) మరింత కోడ్ అవసరం మరియు స్ప్రింగ్ బూట్ ఇంటిగ్రేషన్ లాభాలు అందుకోవడంలేదు. ## టూల్ చైనింగ్ -**టూల్ చైనింగ్** — ఒకే ప్రశ్నకి బహుళ టూల్స్ అవసరమయ్యే సమయంలో టూల్-ఆధారిత ఏజెంట్ల అసలు శక్తి కనబడుతుంది. "సియాటిల్‌లో వాతావరణం ఫారెన్హీట్‌లో ఎలా ఉంటుంది?" అని అడిగితే, ఏజెంట్ ఆటోమేటిక్ గా రెండు టూల్స్‌ను చైన్ చేస్తుంది: మొదట `getCurrentWeather` కాల్ చేసి సెల్సియస్ ఉష్ణోగ్రత పొందుతుంది, తరువాత ఆ విలువను `celsiusToFahrenheit` కి అందించి మలచుతుంది — ఇది పూర్తీ సంభాషణ టర్న్ లో జరుగుతుంది. +**టూల్ చైనింగ్** — ఒకే ప్రశ్నకు బహుళ టూల్స్ అవసరం అయినప్పుడు టూల్ ఆధారిత ఏజెంట్స్ నిజమైన శక్తి కనబరుస్తారు. "సియాటిల్‌లో వాతావరణం ఫారెన్హీట్‌లో ఎలా ఉంది?" అని అడిగితే ఏజెంట్ ఆటోమేటిక్‌గా రెండు టూల్స్‌ను చైన్ చేస్తుంది: మొదట `getCurrentWeather` కాల్ చేయబడుతుంది టెంపరేచర్ ని సేల్సియస్‌లో పొందడానికి, తరువాత `celsiusToFahrenheit`కి ఆ విలువ పంపి మార్పిడి చేస్తుంది — ఇది ఒకే సంభాషణ టర్న్‌లో జరుగుతుంది. -Tool Chaining Example +టూల్ చైనింగ్ ఉదాహరణ -*టూల్ చైనింగ్ సన్నివేశం — ఏజెంట్ మొట్టమొదట getCurrentWeather ను కాల్ చేసి, తర్వాత సెల్సియస్ ఫలితాన్ని celsiusToFahrenheit కి పంపించి కలిపిన సమాధానం ఇస్తుంది.* +*టూల్ చైనింగ్ వేదికపై — ఏజెంట్ మొదట getCurrentWeather ను కాల్ చేస్తుంది, ఆ తర్వాత సేల్సియస్ ఫలితాన్ని celsiusToFahrenheit లోకి పంపి కలిపిన సమాధానం ఇస్తుంది.* -**శాంతమైన వైఫల్యాలు** — మాక్ డేటాలో లేని నగరానికి వాతావరణం అడిగి చూడండి. టూల్ లోపం సందేశాన్ని ఇస్తుంది, మరియు AI క్లిష్టానికి బదులుగా సహాయంగా తెలియజేస్తుంది. టూల్స్ సురక్షితంగా వైఫల్యమవుతాయి. క్రింది డాగ్రామ్ రెండు వంతులను పోలుస్తుంది — సరైన పొరపాటు నిర్వహణతో, ఏజెంట్ తప్పు పట్టుకొని సహాయక స్పందన ఇస్తుంది; లేకపోతే అనువర్తనం మొత్తం క్రాష్ అవుతుంది: +**మృదువైన విఫలాలు** — మాక్ డేటాలో లేనివి అడిగితే టూల్ లోపం సందేశం ఇస్తుంది, AI మద్దతు ఇవ్వలేవని వివరిస్తుంది, క్రాష్ అవ్వదు. టూల్స్ సురక్షితంగా విఫలమవుతాయి. క్రింది డయాగ్రామ్ రెండు పద్ధతులను పోలుస్తుంది — సరైన లోపాలు నిర్వహణతో, ఏజెంట్ తప్పును పట్టుకొని సహాయకమైన ప్రతిస్పందన ఇస్తుంది, లేకపోతే మొత్తం అప్లికేషన్ క్రాష్ అవుతుంది: -Error Handling Flow +లోపాలు నిర్వహణ ప్రవాహం -*టూల్ విఫలం అయితే ఏజెంట్ పొరపాటును పట్టుకొని క్రాష్ కాకుండా సహాయక వివరణతో స్పందిస్తుంది.* +*ఒక టూల్ విఫలమైనప్పుడు ఏజెంట్ లోపాన్ని పట్టుకొని క్రాష్ కాకుండా సహాయమయంగా ప్రతిస్పందిస్తుంది.* -ఇది ఒకే సంభాషణ టర్న్ లో జరుగుతుంది. ఏజెంట్ బహుళ టూల్ కాల్స్ స్వతంత్రంగా ఆపరేట్ చేస్తుంది. +ఇది ఒకే సంభాషణ టర్న్‌లో జరుగుతుంది. ఏజెంట్ స్వతంత్రంగా అనేక టూల్ కాల్స్ ని నిర్వహిస్తుంది. -## అప్లికేషన్ నడిపించండి +## అప్లికేషన్‌ను నడపండి -**డిప్లాయ్‌మెంట్ పరిశీలించండి:** +**డిప్లాయ్‌మెంట్ యథావతంగా ఉందా అని ధృవీకరించండి:** -మాడ్యూల్ 01 సమయంలో సృష్టించిన `.env` ఫైల్ రూట్ డైరెక్టరీలో ఉన్నదని నిర్ధారించుకోండి. ఈ మాడ్యూల్ డైరెక్టరీ నుంచి (`04-tools/`) ఇది నడపండి: +రూట్ డైరెక్టరీలో `.env` ఫైల్ Azure క్రెడెన్షియల్స్‌తో (Module 01లో సృష్టించబడింది) ఉండాలి. ఈ మాడ్యూల్ డైరెక్టరీ (`04-tools/`) నుండి ఇది నడపండి: -**Bash:** +**Bash:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT చూపించాలి ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT చూపించాలి ``` - + **అప్లికేషన్ ప్రారంభించండి:** -> **గమనిక:** మీరు ఇప్పటికే రూట్ డైరెక్టరీ నుంచి `./start-all.sh` ఉపయోగించి అన్ని అప్లికేషన్లు ప్రారంభించలేదని అనుకుంటే (మాడ్యూల్ 01 లో వివరించబడింది), ఈ మాడ్యూల్ ఇప్పటికే 8084 పోర్ట్‌లో నడుచుకుంటుంది. మీరు క్రింది ప్రారంభ ఆజ్ఞలను దాటవేసి నేరుగా http://localhost:8084 కి వెళ్ళవచ్చు. +> **గమనిక:** మీరు ఇప్పటికే రూట్ డైరెక్టరీ నుండి `./start-all.sh` ఉపయోగించి అన్ని అప్లికేషన్లు మొదలుపెట్టినట్లయితే (Module 01లో వివరణ ఇచ్చిన విధంగా), ఈ మాడ్యూల్ ఇప్పటికే 8084 పోర్టులో నడుస్తోంది. కాబట్టి క్రింద ఇచ్చిన స్టార్ట్ ఆదేశాలు పట్టించుకోకు, నేరుగా http://localhost:8084 కి వెళ్లండి. -**వికల్పం 1: స్ప్రింగ్ బూట్ డాష్‌బోర్డు ఉపయోగించడం (VS కోడ్ వినియోగదారులకు సిఫార్సు)** +**ఎంచుకున్న ఎంపిక 1: స్ప్రింగ్ బూట్ డాష్‌బోర్డ్ ఉపయోగించడం (VS Code యూజర్లకు సిఫార్సు)** -డెవ్ కంటైనర్ స్ప్రింగ్ బూట్ డాష్‌బోర్డు ఎక్స్‌టెన్షన్ కలిగి ఉంది, ఇది అన్ని స్ప్రింగ్ బూట్ అప్లికేషన్లను నిర్వహించడానికి విజువల్ ఇంటర్‌ఫేస్ అందిస్తుంది. దీన్ని VS కోడ్ లో ఎడమ వైపు యాక్టివిటీ బార్‌లో (స్ప్రింగ్ బూట్ చిహ్నం కోసం చూడండి) చూడవచ్చు. +డెవ్ కంటైనర్‌లో స్ప్రింగ్ బూట్ డాష్‌బోర్డ్ ఎక్స్‌టెన్షన్ ఉంది, ఇది అన్ని స్ప్రింగ్ బూట్ అప్లికేషన్లను నిర్వహించడానికి విజువల్ ఇంటర్‌ఫేస్ అందిస్తుంది. మీరు దానిని VS Code ఎడమవైపు యాక్టివిటీ బార్‌లో స్ప్రింగ్ బూట్ చిహ్నం అరుస్తూ చూడవచ్చు. -స్ప్రింగ్ బూట్ డాష్‌బోర్డు నుండి మీరు: -- వర్క్‌స్పేస్‌లో అందుబాటులో ఉన్న అన్ని స్ప్రింగ్ బూట్ అప్లికేషన్లు చూడండి -- ఒరిగిపోయే క్లిక్‌తో అప్లికేషన్లు ప్రారంభించండి/ఆపు -- అప్లికేషన్ లాగ్‌లు రియల్-టైમ్లో చూడండి +స్ప్రింగ్ బూట్ డాష్‌బోర్డ్ నుండి మీరు: +- వర్క్‌స్పేస్‌లో అందుబాటులో ఉన్న అన్ని స్ప్రింగ్ బూట్ అప్లికేషన్లను చూడగలరు +- ఒక క్లిక్‌లో అప్లికేషన్లను ప్రారంభించండి/నిలిపివేయండి +- అప్లికేషన్ లాగ్‌లను రీయల్-టైమ్‌లో వీక్షించండి - అప్లికేషన్ స్థితిని పర్యవేక్షించండి -కేవలం "tools" పక్కన ఉన్న ప్లే బటన్‌ను క్లిక్ చేయడం ద్వారా ఈ మాడ్యూల్‌ను ప్రారంభించండి, లేదా అన్ని మాడ్యూల్స్‌ను ఒక్కసారి ప్రారంభించండి. -ఇక్కడ VS Codeలో Spring Boot Dashboard ఎలా కనిపిస్తుందో చూపించబడింది: +సాధారణంగా "tools" పక్కన ఉన్న ప్లే బటన్ నొక్కి ఈ మాడ్యూల్‌ను ప్రారంభించండి, లేదా అన్ని మాడ్యూల్స్‌ను ఒకేసారి మొదలుపెట్టండి. -Spring Boot Dashboard +VS Codeలో స్ప్రింగ్ బూట్ డాష్‌బోర్డ్ ఎలా కనిపిస్తుందో ఇక్కడ ఉంది: +Spring Boot డాష్‍బోర్డు -*VS Codeలో Spring Boot Dashboard — ఒకే చోట నుండి అన్ని మాడ్యూల్స్‌ను ప్రారంభించండి, ఆపండి మరియు పర్యవేక్షించండి* +*VS కోడ్‌లో Spring Boot డాష్‍బోర్డు — ఒకే చోటుండి అన్ని మాడ్యూల్‌లను ప్రారంభించండి, నిలిపివేయండి మరియు పర్యవేక్షించండి* -**ఎంపిక 2: షెల్ స్క్రిప్ట్స్ వాడటం** +**ఎంపిక 2: షెల్ స్క్రిప్ట్‌ల వినియోగం** -అన్ని వెబ్ అప్లికేషన్స్ (మాడ్యూల్స్ 01-04) ప్రారంభించండి: +అన్ని వెబ్ అప్లికేషన్‌లు (మాడ్యూల్‌లు 01-04) ప్రారంభించండి: -**Bash:** +**బ్యాష్:** ```bash cd .. # రూట్ డైరెక్టరీ నుండి ./start-all.sh ``` -**PowerShell:** +**పవర్‌షెల్:** ```powershell cd .. # రూట్ డైరెక్టరీ నుండి .\start-all.ps1 ``` -లేదా కేవలం ఈ మాడ్యూల్‌ను ప్రారంభించండి: +లేదా కేవలం ఈ మాడ్యూల్‌ను మాత్రమే ప్రారంభించండి: -**Bash:** +**బ్యాష్:** ```bash cd 04-tools ./start.sh ``` -**PowerShell:** +**పవర్‌షెల్:** ```powershell cd 04-tools .\start.ps1 ``` -రూట్ `.env` ఫైల్ నుండి మౌలిక వాతావరణ వేరియబుల్స్‌ను రెండు స్క్రిప్ట్స్ స్వయంచాలకంగా లోడ్ చేస్తాయి మరియు JAR లు లేని సందర్భంలో అవి నిర్మిస్తాయి. +రూట్ `.env` ఫైల్ నుండి వాతావరణ variables ఆప్టోమేటిక్‌గా లోడ్ అవుతాయి, మరియు JARలు లేవంటే అవి తయారవుతాయి. -> **గమనిక:** మీరు ప్రారంభించే ముందు అన్ని మాడ్యూల్స్‌ను دستیగా నిర్మించాలనుకుంటే: +> **టిప్:** మీరు ప్రారంభించండానికి ముందు అన్ని మాడ్యూల్‌లను دستی طور پر నిర్మించాలనుకుంటే: > -> **Bash:** +> **బ్యాష్:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell:** +> **పవర్‌షెల్:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -మీ బ్రౌజర్‌లో http://localhost:8084 ని తెరిచి చూడండి. +మీ బ్రౌజర్‌లో http://localhost:8084 ఓపెన్ చేయండి. -**ఆపడానికి:** +**నిలిపివేయడానికి:** -**Bash:** +**బ్యాష్:** ```bash ./stop.sh # ఈ మాడ్యూల్ మాత్రమే # లేదా cd .. && ./stop-all.sh # అన్ని మాడ్యూల్లు ``` -**PowerShell:** +**పవర్‌షెల్:** ```powershell .\stop.ps1 # ఈ మాడ్యూల్ మాత్రమే # లేదా cd ..; .\stop-all.ps1 # అన్ని మాడ్యూల్స్ ``` -## అప్లికేషన్ వాడకం +## అప్లికేషన్ వినియోగం -ఈ అప్లికేషన్ ఒక వెబ్ ఇంటర్ఫేస్‌ను అందిస్తోంది, మీరు ఇది ద్వారా వాతావరణ సమాచారాన్ని మరియు ఉష్ణోగ్రత మార్పిడి సాధనాలను యాక్సెస్ చేసే AI ఏజెంట్‌తో ముం హాని చేయవచ్చు. ఇంటర్ఫేస్ ఎలా కనిపిస్తుందో ఇక్కడ ఉంది — ఇది త్వరిత ప్రారంభ ఉదాహరణలు మరియు అభ్యర్థనలు పంపేందుకు చాట్ ప్యానెల్‌ను కలిగి ఉంది: +ఈ అప్లికేషన్ ఒక వెబ్ ఇంటర్ఫేస్‌ను అందిస్తుంది, అక్కడ మీరు వాతావరణం మరియు ఉష్ణోగ్రత మార్పిడి సాధనాలను ఉపయోగించగల AI ఏజెంట్‌తో ఇంటరాక్ట్ చేయవచ్చు. ఇంటర్ఫేస్ ఇందులో ఇలా ఉంటుంది — ఇది తేలికపాటి ప్రారంభ ఉదాహరణలు మరియు అభ్యర్థనలు పంపడానికి చాట్ ప్యానెల్‌ను కలిగి ఉంది: -AI Agent Tools Interface +AI ఏజెంట్ టూల్స్ ఇంటర్ఫేస్ -*AI ఏజెంట్ టూల్స్ ఇంటర్‌ఫేస్ - టూల్స్‌తో సంక్రియ చేసేందుకు త్వరిత ఉదాహరణలు మరియు చాట్ ఇంటర్‌ఫేస్* +*AI ఏజెంట్ టూల్స్ ఇంటర్ఫేస్ - టూల్స్‌తో ఇంటరాక్ట్ చేయడానికి వేగవంతమైన ఉదాహరణలు మరియు చాట్ ఇంటర్ఫేస్* -### సింపుల్ టూల్ వాడకం ప్రయత్నించండి +### సాదారణ టూల్ వినియోగాన్ని ప్రయత్నించండి -సరళమైన అభ్యర్థనతో మొదలు పెట్టండి: "100 డిగ్రీలు ఫారెన్‌హీట్‌ను సెల్సియస్‌కు మార్పిడిచి". ఏజెంట్ దీనికి ఉష్ణోగ్రత మార్పిడి సాధనం అవసరం olduğunu గుర్తించి, సరైన పారామితులతో పిలుస్తుంది మరియు ఫలితాన్ని తిరిగి అందిస్తుంది. ఇది సహజంగా అనిపిస్తుంది — మీరు ఎటువంటి టూల్ వాడాలని లేదా ఎలా పిలవాలని పేర్కొనలేదు. +సరళమైన అభ్యర్థనతో ప్రారంభించండి: "100 డిగ్రీలు Fahrenheit నుండి Celsius కి మార్చండి". ఏజెంట్ ఉష్ణోగ్రత మార్పిడి టూల్ అవసరమని గుర్తించి, సరైన పారామీటర్లతో దీనిని పిలుస్తుంది మరియు ఫలితం ఇస్తుంది. ఇది ఎంత సహజంగా అనిపిస్తుంది గమనించండి — మీరు ఏ టూల్‌ను ఉపయోగించాలో లేదా ఎలా పిలవాలో నిర్దేశించలేదు. -### టూల్ చైనింగ్ పరీక్షించండి +### టూల్ చైనింగ్‌ను పరీక్షించండి -ఇప్పుడిముత్తి కాస్త క్లిష్టమైనది ప్రయత్నించండి: "సియాటిల్‌లో వాతావరణం ఏంటంటే మరియు దాన్ని ఫారెన్‌హీట్‌కు మార్పిడిచి?" ఏజెంట్ దశలవారీగా పని చేసే విధానం చూడండి. మొదట వాతావరణాన్ని పొందుతుంది (అది సెల్సియస్‌ను ఇస్తుంది), తరువాత ఫారెన్‌హీట్‌కు మార్చాలని గుర్తించి, మార్పిడి టూల్‌ను పిలుస్తుంది మరియు రెండింటిని కలిపి ఫలితాన్ని ఇస్తుంది. +ఇప్పుడు కొంత క్లిష్టమైనది ప్రయత్నించండి: "సియాటిల్‌లో వాతావరణం ఏమిటి మరియు దాన్ని Fahrenheit కు మార్చండి?" ఈ దశల్లో ఏజెంట్ ఎలా పని చేస్తుందో గమనించండి. ఇది ముందు వాతావరణాన్ని పొందుతుంది (సెల్షియస్‌లో ఇస్తుంది), తరువాత దీనిని Fahrenheitకి మార్చాలని గుర్తించి, మార్పిడి టూల్‌ను పిలుస్తుంది, రెండింటిని కలిపి ఫలితాన్ని ఇస్తుంది. -### సంభాషణ ప్రవాహం చూడండి +### సంభాషణ ప్రవాహాన్ని చూడండి -చాట్ ఇంటర్ఫేస్ సంభాషణ చరిత్రను నిర్వహిస్తుంది, దీనివల్ల మీరు బహుళ-తిరుగుల పరస్పర చర్యలు చేయవచ్చు. మీరు గత అభ్యర్థనలు మరియు ప్రతిస్పందనలను చూడగలుగుతారు, తద్వారా సంభాషణను ట్రాక్ చేయడం మరియు ఏజెంట్ ఎలా వివిధ పోకడలలో సారాన్ని నిర్మిస్తున్నాడో అర్థం చేసుకోవడం సులభమవుతుంది. +చాట్ ఇంటర్ఫేస్ సంభాషణ చరిత్రను నిల్వ చేస్తుంది, మీకు బహు-మార్పుల ఇంటరాక్షన్‌లు చేయడానికి అనుమతిస్తుంది. మీరు అంతకు ముందు అన్ని ప్రశ్నలు మరియు జవాబులను చూడవచ్చు, ఇది సంభాషణను ట్రాక్ చేసుకోవటం మరియు ఏజెంట్ కంటెక్స్ట్‌ను ఎలా నిర్మిస్తుందో అర్థం చేసుకోవడం సులభం చేస్తుంది. -Conversation with Multiple Tool Calls +బహుళ టూల్ పిలుపులతో సంభాషణ -*సింపుల్ మార్పిడులు, వాతావరణ సమాచారాలు, టూల్ చైనింగ్‌లతో బహుళ-తిరుగు సంభాషణ చూపడం* +*సరళమైన మార్పిడులు, వాతావరణ లుకప్‌లు, టూల్ చైనింగ్ చూపించే బహుళ మార్పుల సంభాషణ* -### వేర్వేరు అభ్యర్థనలతో ప్రయోగం చేయండి +### వేరే వివిధ అభ్యర్థనలను ప్రయత్నించండి -వివిధ సంకలింపులను ప్రయత్నించండి: -- వాతావరణ సమాచారాలు: "టోక్యోలో వాతావరణం ఏమిటి?" -- ఉష్ణోగ్రత మార్పిడులు: "25°C ను కెல்வిన్‌లో ఎంత?" -- కలిపిన ప్రశ్నలు: "పారిస్‌లో వాతావరణం చెక్ చేసి 20°C కంటే ఎక్కువ ఉంటే చెప్పు" +విభిన్న కలయికలను పరిశీలించండి: +- వాతావరణ లుకప్‌లు: "టోక్యోలో వాతావరణం ఎలా ఉంది?" +- ఉష్ణోగ్రత మార్పిడి: "25°C ఎంత Kelvin?" +- కలిపిన అభ్యర్థనలు: "ప్యారిస్‌లో వాతావరణం చెక్ చేసి 20°C కంటే ఎక్కువ ఉందా చెప్పండి" -ఏజెంట్ సహజ భాషను ఎలా అర్థం చేసుకుని సరైన టూల్ పిలుపులకు మ్యాప్ చేస్తుందో గమనించండి. +ఏజెంట్ సహజ భాషను ఎలా అర్థం చేసుకొని తగిన టూల్ పిలుపులతో మ్యాప్ చేస్తుందో గమనించండి. -## కీలక భావనలు +## ముఖ్య భావనలు -### ReAct నమూనా (రాజనీతికత మరియు చర్య) +### ReAct నమూనా (తర్కం మరియు చర్య) -ఏజెంట్ తర్కం (మంచి ప్రవర్తన నిర్ణయించడం) మరియు చర్య (టూల్స్ ఉపయోగించడం) మధ్య మారుతుంటుంది. ఈ నమూనా స్వతంత్ర సమస్య పరిష్కారానికి సహాయపడుతుంది, కేవలం సూచనలకు ప్రతిస్పందించడంలో కాదు. +ఏజెంట్ తర్కం (ఏం చేయాలో నిర్ణయించడం) మరియు చర్య (టూల్స్‌ను ఉపయోగించడం) మధ్య మార్పిడి చేస్తుంది. ఈ నమూనా సూచనలకు ప్రతిస్పందించడం కాకుండా స్వయంచాలక సమస్య పరిష్కరణను సాధ్యం చేస్తుంది. -### టూల్ వివరాలు ముఖ్యం +### టూల్ వివరణలు ముఖ్యం -మీ టూల్ వివరణల నాణ్యత ఏజెంట్ వాటిని ఎంతగా ఉపయోగిస్తాయో నేరుగా ప్రభావితం చేస్తుంది. స్పష్టమైన, ప్రత్యేకమైన వివరణలతో మోడల్ ఎప్పుడు మరియు ఎలా టూల్ పిలవాలో అర్థం చేసుకుంటుంది. +మీ టూల్ వివరణల నాణ్యత ఏజెంట్ వాటిని ఎంత బాగా ఉపయోగిస్తుందో నేరుగా ప్రభావితం చేస్తుంది. స్పష్టమైన, నిర్దిష్ట వివరణలు మోడల్‌కి ఏ టూల్‌ను ఎప్పుడు ఎలా పిలవాలో అర్థం చేసుకోవడానికి సహాయపడతాయి. -### సెషన్ నిర్వహణ +### సెష‌న్ మేనేజ్మెంట్ -`@MemoryId` వ్యాఖ్య ద్వారా ఆటోమేటిక్ సెషన్ ఆధారిత మెమరీ నిర్వహణ సాధ్యం అవుతుంది. ప్రతి సెషన్ IDకి `ChatMemory` ఉదాహరణ `ChatMemoryProvider` బీన్ ద్వారా నిర్వహించబడుతుంది, కాబట్టి బహుళ వినియోగదారులు ఏజెంట్‌తో ఒక్కసారి సహకరించినా వారి సంభాషణలు కలగడాన్ని నివారిస్తుంది. ఈ డయాగ్రామ్ బహుళ వినియోగదారులు ఎలా వారి సెషన్ IDs ఆధారంగా వేరుగానే మెమరీ స్టోర్లు పొందుతారో చూపిస్తుంది: +`@MemoryId` అనోటేషన్ ఆటోమేటిక్ సెషన్ ఆధారిత మెమొరీ నిర్వహణను సక్రియం చేస్తుంది. ప్రతి సెషన్ IDకి స్పష్టమైన `ChatMemory` ఇన్‌స్టెన్స్ ఉంటుంది మరియు ఈ మెమొరీని `ChatMemoryProvider` బీన్ నిర్వహిస్తుంది, కాబట్టి అనేక యూజర్లు ఏజెంట్‌తో ఒకేసారి సంభాషించగలరు కానీ వారి సంభాషణలు కలవరపడవు. ఈ దిగువ చిత్రం బహుళ యూజర్లను వారి సెషన్ ID ఆధారంగా వేరుచేసిన మెమొరీ స్టోర్లకు ఎలా రూట్ చేస్తారో చూపిస్తుంది: -Session Management with @MemoryId +సెషన్ మేనేజ్మెంట్ @MemoryId తో -*ప్రతి సెషన్ ID వేర్వేరు సంభాషణ చరిత్రకు మ్యాప్ అవుతుంది — వినియోగదారులు ఒకరినొకరు సందేశాలను ఎప్పుడూ చూడరు.* +*ప్రతి సెషన్ ID వేరుచేసిన సంభాషణ చరిత్రకు మ్యాప్ అవుతుంది — యూజర్లు ఒకరితో ఒకరి సందేశాలను చూడరు.* ### లోపాల నిర్వహణ -టూల్స్ విఫలం కావచ్చు — APIs టైమౌట్ అవ్వచ్చు, పారామితులు తప్పు కావచ్చు, బాహ్య సేవలు డౌన్ కావచ్చు. ఉత్పత్తి ఏజెంట్లు లోపాల నిర్వహణ అవసరం, తద్వారా మోడల్ సమస్యలను వివరించగలుగుతుంది లేదా ప్రత్యామ్నాయాలను ప్రయత్నిస్తుంది, మొత్తం అప్లికేషన్ క్రాష్ కాకుండా. ఏదైనా టూల్ ఎక్సెప్షన్ వేస్తే, LangChain4j అదన్ని పట్టుకొని లోప సందేశాన్ని మోడల్‌కు తిరిగి అందిస్తుంది, తద్వారా సహజ భాషలో సమస్యను వివరించవచ్చు. +టూల్స్ విఫలమవచ్చు — APIs టైమ్ అవుట్ కావచ్చు, పారామీటర్లు చెల్లదు, బాహ్య సేవలు డౌన్ అవుతాయి. ప్రొడక్షన్ ఏజెంట్లు లోపాల నిర్వహణ అవసరం, తద్వారా మోడల్ సమస్యలను వివరించగలదు లేదా ప్రత్యామ్నాయాలను ప్రయత్నించగలదు, ఆప్లికేషన్ మొత్తం క్రాష్ కాకుండా. ఒక టూల్ తప్పు విసురితే, LangChain4j దాన్ని కేస్కు చేస్తుంది మరియు లోపం మెసేజ్‌ను మోడల్‌కు తిరిగి ఇస్తుంది, తద్వారా సహజ భాషలో సమస్యను వివరించగలదు. ## అందుబాటులో ఉన్న టూల్స్ -క్రింది డయాగ్రామ్ మీరు నిర్మించగలిగే విస్తృత టూల్ ఎకోసిస్టమ్‌ను చూపిస్తుంది. ఈ మాడ్యూల్ వాతావరణం మరియు ఉష్ణోగ్రత టూల్స్‌ను ప్రదర్శిస్తుంది, కానీ అదే `@Tool` నమూనా ఏ Java మethoడ్‌కి వాడవచ్చు — డేటాబేస్ ప్రశ్నలు నుంచి పేమెంట్ ప్రాసెసింగ్ వరకు. +క్రింద చూపిన డయాగ్రామ్ మీరు తయారు చేయగల టూల్స్ యొక్క విస్తృత ఈకోసిస్టమ్‌ను అందిస్తుంది. ఈ మాడ్యూల్ వాతావరణ మరియు ఉష్ణోగ్రత టూల్స్‌ను ప్రదర్శిస్తుండగా, అదే `@Tool` నమూనా ఏ Java విధానం కోసం పనిచేస్తుంది — డేటాబేస్ ప్రశ్నల నుండి చెల్లింపు ప్రాసెసింగ్ వరకు. -Tool Ecosystem +టూల్ ఈకోసిస్టమ్ -*@Tool తో గుర్తించిన ఏ Java మethoడ్ AI కి అందుబాటులో ఉంటుంది — ఈ నమూనా డేటాబేస్లు, APIs, ఇమెయిల్లు, ఫైల్ ఆపరేషన్లు మరియు మరిన్ని వరకు విస్తరిస్తుంది.* +*`@Tool` తో anotate చేసిన ఏ Java విధానం AI కి అందుబాటులో ఉంటుంది — ఈ నమూనా డేటాబేసులు, APIs, ఇమెయిల్స్, ఫైల్ ఆపరేషన్స్ మరియు మరింత వరకు విస్తరిస్తుంది.* -## టూల్-ఆధారిత ఏజెంట్లను ఎప్పుడు వాడాలి +## టూల్ ఆధారిత ఏజెంట్లను ఎప్పుడు ఉపయోగించాలి -ప్రతి అభ్యర్థనకి టూల్స్ అవసరం కాదు. నిర్ణయం ఏ ఐ తన జ్ఞానంతో సమాధానం ఇవ్వగలదా లేదా బాహ్య వ్యవస్థలతో సంక్రియ అవసరమైందా అనే దానిపై ఆధారపడుతుంది. క్రింది మార్గదర్శకం టూల్స్ విలువ కలిగించేటప్పుడు మరియు అవసరం లేనప్పుడు ప్లస్ మైనస్ చెప్పుతుంది: +ప్రతి అభ్యర్థనకు టూల్స్ అవసరం ఉండదు. నిర్ణయం AIకు బాహ్య వ్యవస్థలతో ఇంటరాక్ట్ కావలసిన అవసరం ఉందా లేదా తన స్వంత సమాచారంతో సమాధానం ఇవ్వగలదా అనేదానిపై ఆధారపడి ఉంటుంది. ఈ క్రింది మార్గదర్శకం టూల్స్ విలువ చేకూర్చే సమయాలు మరియు అవసరంలేని సందర్భాలను సారాంశంగా తెలియజేస్తుంది: -When to Use Tools +టూల్స్ ఎప్పుడు ఉపయోగించాలి -*త్వరిత నిర్ణయ మార్గదర్శకం — రియల్-టైమ్ డేటా, గణనల కోసం టూల్స్; సాధారణ జ్ఞానం మరియు సృజనాత్మక పనులకి అవి అవసరం కాదు.* +*సత్వర నిర్ణయ మార్గదర్శి - టూల్స్ నిజ-సమయ డేటా, గణనల మరియు చర్యల కోసం; సాధారణ జ్ఞానం మరియు సృజనాత్మక పనులకు అవసరం లేదు.* -## టూల్స్ వర్సెస్ RAG +## టూల్స్ వర్సస్ RAG -మాడ్యూల్స్ 03 మరియు 04 రెండూ AI సామర్థ్యాన్ని విస్తరిస్తాయి, కాని మౌలికంగా వేర్వేరు మార్గాల్లో. RAG మోడల్‌కు **జ్ఞానం** యాక్సెస్ ఇవ్వడానికి డాక్యుమెంట్లను తిరిగి తెస్తుంది. టూల్స్ మోడల్‌కు చర్యలు చేపట్టడానికి ఫంక్షన్‌లను పిలిచే సామర్థ్యం ఇస్తాయి. క్రింది డయాగ్రామ్ వీటి రెండు విధానాల వైపుల్యాలను మరియు ప్రయోజనాలను పక్కనపక్క చూడిస్తుంది — ప్రతి వర్క్‌ఫ్లో ఎలా పనిచేస్తుందో మరియు వాటి మధ్య వ్యత్యాసాలు: +మాడ్యూల్‌లు 03 మరియు 04 రెండూ AI సామర్థ్యాన్ని విస్తరించుకుంటాయి, కానీ ప్రాథమికంగా విభిన్న మార్గాల్లో. RAG మోడల్‌కు **జ్ఞానాన్ని** అందిస్తుంది, డాక్యుమెంట్లను సంప్రదించడం ద్వారా. టూల్స్ మోడల్‌కు **చర్యలు** తీసుకునే సామర్థ్యం ఇస్తాయి, ఫంక్షన్లు పిలిచేందుకు. క్రింది డయాగ్రామ్ ఈ రెండు విధానాలను పక్కన పెట్టి పోల్చుతుంది — ప్రతి పని ప్రవాహం ఎలా పనిచేస్తుందో మరియు వాటి మధ్య వ్యత్యాసాలు ఏమిటో: -Tools vs RAG Comparison +టూల్స్ వర్సస్ RAG పోలిక -*RAG స్థిర డాక్యుమెంట్ల నుంచి సమాచారం తెస్తుంది — టూల్స్ చర్యలు చేపడుతూ డైనమిక్, రియల్-టైమ్ డేటాను తెచ్చుకుంటాయి. చాల ఉత్పత్తి వ్యవస్థలు రెండింటినీ కలిపి వాడతారు.* +*RAG స్థిర డాక్యుమెంట్ల నుండి సమాచారం తీసుకుంటుంది — టూల్స్ చర్యలను అమలు చేస్తాయి మరియు డైనమిక్, రియల్-టైమ్ డేటాను తెస్తాయి. అనేక ప్రొడక్షన్ వ్యవస్థలు ఇద్దరికీ మిశ్రమంగా ఉపయోగిస్తాయి.* -ప్రాయోగికంగా, చాల ఉత్పత్తి వ్యవస్థలు రెండు విధానాలను కలపడం కొనసాగిస్తాయి: RAG మీ డాక్యుమెంటేషన్‌లో జవాబులను గ్రౌండింగ్ చేయడానికి, మరియు టూల్స్ ప్రత్యక్ష డేటా తీసుకోవడానికి లేదా ఆపరేషన్లు చేయడానికి. +ప్రాక్టికల్‌లో, అనేక ప్రొడక్షన్ వ్యవస్థలు ఇద్దరి యొక్క సంయోజనాన్ని ఉపయోగిస్తాయి: RAG మీ డాక్యుమెంటేషన్‌లో సమాధానాలను ఆధారపడేందుకు, మరియు టూల్స్ ప్రత్యక్ష డేటాను తెచ్చేందుకు లేదా ఆపరేషన్లు జరపడానికి. ## తదుపరి దశలు -**తదుపరి మాడ్యూల్:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**తదుపరి మాడ్యూల్:** [05-mcp - మోడల్ కాంటెక్స్ట్ ప్రోటోకాల్ (MCP)](../05-mcp/README.md) --- -**నావిగేషన్:** [← మునుపటి: మాడ్యూల్ 03 - RAG](../03-rag/README.md) | [ప్రధానానికి తిరిగి](../README.md) | [తరువాత: మాడ్యూల్ 05 - MCP →](../05-mcp/README.md) +**నావిగేషన్:** [← పూర్వం: మాడ్యూల్ 03 - RAG](../03-rag/README.md) | [మూలానికి తిరుగు](../README.md) | [తదుపరి: మాడ్యూల్ 05 - MCP →](../05-mcp/README.md) --- -**స్పష్టం**: -ఈ డాక్యుమెంట్‌ను AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడ్డది. మేము ఖచ్చితత్వానికి ప్రయత్నించినప్పటికీ, ఆటోమేటెడ్ అనువాదాలలో తప్పులూ లేదా అసత్యతలూ ఉండవచ్చు. మూల డాక్యుమెంట్ దీనిది స్వదేశీ భాషలో ఉన్నదీ అధికారిక మూలంగా పరిగణించాలి. అత్యవసర సమాచారం కోసం, వృత్తిపరమైన మానవ అనువాదం చేయించుకోవడం సిఫార్సు చేయబడుతుంది. ఈ అనువాదం ఉపయోగంలో ఏమైనా అపార్థాలు లేదా పొరిపోకల కారణంగా మేము బాధ్యులం కాకపోయే మేము. +**అస్వీకరణ**: +ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటెడ్ అనువాదాలు తప్పులు లేదా అసమగ్రతలను కలిగి ఉండవచ్చు. దాని స్వదేశ భాషలో ఉన్న అసలు పత్రాన్ని అధికారం కలిగిన మూలంగా పరిగణించాలి. కీలకమైన సమాచారం కోసం, ప్రొఫెషనల్ మానవ అనువాదాన్ని సిఫారసు చేస్తాము. ఈ అనువాదం ఉపయోగం వల్ల కలిగే ఏవైనా అపార్థాలు లేదా తప్పుదారులు కోసం మేము బాధ్యత వహించము. \ No newline at end of file diff --git a/translations/te/README.md b/translations/te/README.md index 00e567ab0..42caa910e 100644 --- a/translations/te/README.md +++ b/translations/te/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j ప్రారంభికులకు +# ప్రారంభకులకు LangChain4j -LangChain4j మరియు Azure OpenAI GPT-5.2 తో AI అనువర్తనాలు నిర్మించడానికి ఒక కోర్స్, ప్రాథమిక చాట్ నుండి AI ఏజెంట్లు వరకు. +మూల చాట్ నుండి AI ఏజెంట్ల వరకు LangChain4j మరియు Azure OpenAI GPT-5.2 తో AI అప్లికేషన్లను నిర్మించడానికి ఒక కోర్సు. ### 🌐 బహుభాషా మద్దతు -#### GitHub Action ద్వారా మద్దతు (స్వయంచాలక & ఎప్పటికప్పుడు అప్డేట్) +#### GitHub Action ద్వారా మద్దతు (ఆటోమేటెడ్ & ఎప్పుడూ తాజా) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](./README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) > **స్థానికంగా క్లోన్ చేయాలనుకుంటున్నారా?** > -> ఈ రిపొజిటరీ 50+ భాషల అనువాదాలను కలిగి ఉంది, ఇది డౌన్లోడ్ పరిమాణాన్ని గణనీయంగా పెంచుతుంది. అనువాదాలు లేకుండా క్లోన్ చేయడానికి sparse checkout ఉపయోగించండి: +> ఈ రిపోజిటరీ 50+ భాషా అనువాదాలను కలిగి ఉంది, ఇది డౌన్‌లోడ్ పరిమాణాన్ని గణనీయంగా పెంచుతుంది. అనువాదాలు లేకుండా క్లోన్ చేయడానికి, స్పార్స్ చెకౌట్ ఉపయోగించండి: > > **Bash / macOS / Linux:** > ```bash @@ -29,100 +29,99 @@ LangChain4j మరియు Azure OpenAI GPT-5.2 తో AI అనువర్త > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> ఇది కోర్సును పూర్తి చేయడానికి అవసరమైన అన్ని విషయాలను త్వరగా డౌన్లోడ్ చేసుకోగలుగుతుంది. +> ఇది మీకు కోర్సును పూర్తిచేయడానికి అవసరమైన అన్ని ఫైళ్ళను త్వరగా డౌన్లోడ్ చేస్తుంది. ## కంటెంట్ పట్టిక -1. [త్వరిత ఆరంభం](00-quick-start/README.md) - LangChain4j తో ప్రారంభించండి -2. [పరిచయం](01-introduction/README.md) - LangChain4j యొక్క మూలబోధనలను తెలుసుకోండి -3. [ప్రాంప్ట్ ఇంజనీరింగ్](02-prompt-engineering/README.md) - సమర్థవంతమైన ప్రాంప్ట్ రూపకల్పనలో నైపుణ్యం పొందండి -4. [RAG (రిట్రీవల్-ఆగ్మెంటెడ్ జనరేషన్)](03-rag/README.md) - అర్థవంతమైన జ్ఞానాధారిత సిస్టమ్‌లను నిర్మించండి -5. [టూల్స్](04-tools/README.md) - బయటి పనిముట్లు మరియు సులభ సహాయకులను అనుసంఖ్యాయించండి -6. [MCP (మోడల్ కాన్‌టెక్స్ట్ ప్రోటోకాల్)](05-mcp/README.md) - మోడల్ కాన్‌టెక్స్ట్ ప్రోటోకాల్ (MCP) మరియు ఏజెంటిక్ మాడ్యూల్‌లతో పనిచేయండి +1. [పరిచయం](01-introduction/README.md) - LangChain4j యొక్క ప్రాథమిక విషయాలు నేర్చుకోండి +2. [ప్రాంప్ట్ ఇంజనీరింగ్](02-prompt-engineering/README.md) - సమర్థవంతమైన ప్రాంప్ట్ రూపకల్పనలో నైపుణ్యం సాధించండి +3. [RAG (రిట్రీవల్-ఆగ్మెంటెడ్ జనరేషన్)](03-rag/README.md) - తెలివైన జ్ఞానం ఆధారిత వ్యవస్థలను నిర్మించండి +4. [ఉపకరణాలు](04-tools/README.md) - బయటి ఉపకరణాలు మరియు సులభ సహాయకులను ఇంటిగ్రేట్ చేయండి +5. [MCP (మోడల్ కాంటెక్ట్ ప్రోటోకాల్)](05-mcp/README.md) - మోడల్ కాంటెక్ట్ ప్రోటోకాల్ (MCP) మరియు ఏజెంటిక్ మాడ్యూలులతో పని చేయండి -### వీడియో వాక్‌త్రోలు +### వీడియో వాక్‌త్రూప్స్ -ప్రతి మాడ్యూల్‌కు అనుసంధాన లైవ్ సెషన్ ఉంటుంది, అక్కడ మేము ఆలోచనలను మరియు కోడ్‌ను దశలవారీగా ట్రావర్స్ చేస్తాము. +ప్రతి మాడ్యూల్‌కు మా టదుపు సంభాషణలో ఆ ఉత్సాహంతో కాంసెప్ట్స్ మరియు కోడ్‌ను దశల వారీగా వివరిస్తుంది. | మాడ్యూల్ | వీడియో | |--------|-------| | 01 - పరిచయం | [LangChain4j తో ప్రారంభించడం](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - ప్రాంప్ట్ ఇంజనీరింగ్ | [LangChain4j తో ప్రాంప్ట్ ఇంజనీరింగ్](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [LangChain4j తో RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - టూల్స్ & 05 - MCP | [టూల్స్ మరియు MCP తో AI ఏజెంట్లు](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - ఉపకరణాలు & 05 - MCP | [ఉపకరణాలు మరియు MCP తో AI ఏజెంట్ల](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## నేర్చుకునే మార్గం +## అభ్యసన మార్గం -**LangChain4j కొత్తవురా?** ముఖ్య పదాలు మరియు భావాలను నిర్వచించడానికి [Glossary](docs/GLOSSARY.md) చూడండి. +**LangChain4j కొత్తవా?** ముఖ్య పదాలు మరియు కాన్సెప్ట్ల నిర్వచనాల కోసం [Glossary](docs/GLOSSARY.md) ని చూడండి. -> **త్వరిత ఆరంభం** +> **త్వరిత ప్రారంభం** -1. ఈ రిపోజిటరీని మీ GitHub ఖాతాకు Fork చేయండి -2. **Code** → **Codespaces** టాబ్ → **...** → **New with options...** క్లిక్ చేయండి -3. డిఫాల్ట్ ఎంపికలను ఉపయోగించండి – ఇది ఈ కోర్సు కోసం సృష్టించబడిన డెవలప్‌మెంట్ కంటైనర్‌ని ఎంచుకుంటుంది -4. **Create codespace** క్లిక్ చేయండి -5. వాతావరణం సిద్ధంగా అయ్యేందుకు 5-10 నిమిషాలు వేచి ఉండండి -6. ప్రారంభించడానికి నేరుగా [త్వరిత ఆరంభం](./00-quick-start/README.md)కి వెళ్లండి! +1. ఈ రిపోజిటరీని మీ GitHub ఖాతాకు ఫోర్క్ చేయండి +2. **Code** → **Codespaces** ట్యాబ్ → **...** → **New with options...** ఎంచుకోండి +3. డిఫాల్ట్స్ ఉపయోగించండి – ఇది ఈ కోర్సు కోసం సృష్టించిన డెవలప్‌మెంట్ కంటైనర్‌ను ఎంచుకుంటుంది +4. **Create codespace** క్లిక్ చేయండి +5. వాతావరణం సిద్ధంగా ఉండేందుకు 5-10 నిమిషాలు వేచివుండండి +6. సిద్దమైన తరువాత [Introduction](./01-introduction/README.md) కి వెళ్లి ప్రారంభించండి! -మాడ్యూల్‌లు పూర్తి చేసిన తరువాత, LangChain4j టెస్టింగ్ భావాలను కార్యంలో చూడటానికి [Testing Guide](docs/TESTING.md)ని పరిశీలించండి. +మాడ్యూల్‌లు పూర్తిచేసిన తర్వాత, LangChain4j పరీక్షా కాన్సెప్ట్లను ప్రత్యక్షంగా చూడటానికి [Testing Guide](docs/TESTING.md) ని అన్వేషించండి. -> **గమనిక:** ఈ శిక్షణ GitHub Models మరియు Azure OpenAI రెండింటినీ ఉపయోగిస్తుంది. [త్వరిత ఆరంభం](00-quick-start/README.md) మాడ్యూల్ GitHub Models ను ఉపయోగిస్తుంది (Azure సబ్‌స్క్రిప్షన్ అవసరం లేదు), మిగతా 1-5 మాడ్యూల్స్ Azure OpenAI ను ఉపయోగిస్తాయి. మీ వద్ద లేని వారు [ఉచిత Azure ఖాతా](https://aka.ms/azure-free-account) తో ప్రారంభించండి. +> **గమనిక:** ఈ శిక్షణ Azure OpenAI ఉపయోగిస్తుంది. మీరు ఖాతా లేదా లేనివారు అయితే [ఉచిత Azure ఖాతా](https://aka.ms/azure-free-account) తో ప్రారంభించండి. -## GitHub Copilot తో నేర్చుకోవడం +## GitHub Copilot తో అభ్యసనం -త్వరగా కోడింగ్ ప్రారంభించడానికి, ఈ ప్రాజెక్టును GitHub Codespace లో లేదా మీ స్థానిక IDE లో ఇవ్వబడిన devcontainer తో తెరవండి. ఈ కోర్సులో ఉపయోగించబడుతున్న devcontainer GitHub Copilot తో AI పేయర్డ్ ప్రోగ్రామింగ్ కోసం ముందుగానే కాన్ఫిగర్ చేయబడింది. +త్వరగా కోడింగ్ చేయడానికి, GitHub Codespace లేదా మీ స్థానిక IDEలో ఈ ప్రాజెక్టును devcontainer తో తెరవండి. ఈ కోర్సులో ఉపయోగించబడిన devcontainer GitHub Copilot తో AI జోడి ప్రోగ్రామింగ్ కోసం ముందేనుంచి కలవెనుక ఉంటుంది. -ప్రతి కోడ్ ఉదాహరణలో GitHub Copilot ను అడగవచ్చు, అవి మీ అవగాహన ను మరింత లోతుగా చేయడానికి సూచించిన ప్రశ్నలు ఉంటాయి. 💡/🤖 సూచనలు ఈ క్రింది చోట్ల ఉంటాయి: +ప్రతి కోడ్ ఉదాహరణ కోసం GitHub Copilot కి అడగగలిగే సూచనల ప్రశ్నలు ఉంటాయి, ఇవి మీ అర్థాన్ని పెంపొందిస్తాయి. 💡/🤖 సూచనలు కోసం చూడండి: -- **జావా ఫైల్ హెడ్డర్లు** - ప్రతి ఉదాహరణకు ప్రత్యేకమైన ప్రశ్నలు -- **మాడ్యూల్ READMEలు** - కోడ్ ఉదాహరణల తర్వాత అన్వేషణా సూచనలు +- **జావా ఫైల్ హెడ్డర్స్** - ప్రతి ఉదాహరణకు ప్రత్యేక ప్రశ్నలు +- **మాడ్యూల్ READMEలు** - కోడ్ ఉదాహరణల తర్వాత అన్వేషణ సూచనలు -**ఎలా ఉపయోగించాలి:** ఏ కోడ్ ఫైల్ ను తెరువు మరియు Copilot కు సూచించిన ప్రశ్నలు అడుగు. దీనికి పూర్తి కోడ్ బేస్ సూత్రాలు తెలుసు, ఇది వివరణ ఇవ్వగలదు, పొడిగించగలదు, మరియు ప్రత్యామ్నాయాల సూచనలు చేయగలదు. +**ఎలా వాడాలి:** ఏ కోడ్ ఫైల్ ను తెరవండి, Copilot కి సూచనల ప్రశ్నలు అడగండి. దీనికి కోడ్బేస్ యొక్క పూర్తి సందర్భం ఉంటుంది, అది వివరించగలదు, విస్తరించగలదు మరియు ప్రత్యామ్నాయాలు సూచించగలదు. -ఇంకా నేర్చుకోవాలనుకుంటున్నారా? [AI పేయర్డ్ ప్రోగ్రామింగ్ కోసం Copilot](https://aka.ms/GitHubCopilotAI) చూడండి. +ఇంకా తెలుసుకోవాలనుకుంటున్నారా? [AI జోడి ప్రోగ్రామింగ్ కోసం Copilot](https://aka.ms/GitHubCopilotAI) చూడండి. ## అదనపు వనరులు ### LangChain -[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![ప్రారంభకులకు LangChain4j](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![ప్రారంభకులకు LangChain.js](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![ప్రారంభకులకు LangChain](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents -[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / ఎడ్జ్ / MCP / ఏజెంట్స్ +[![ప్రారంభకులకు AZD](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![ప్రారంభకులకు ఎడ్జ్ AI](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![ప్రారంభకులకు MCP](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![ప్రారంభకులకు AI ఏజెంట్స్](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Generative AI Series -[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### జనరేటివ్ AI సిరీస్ +[![ప్రారంభకులకు జనరేటివ్ AI](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![జనరేటివ్ AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![జనరేటివ్ AI (జావా)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![జనరేటివ్ AI (జావాస్క్రిప్ట్)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Core Learning -[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +### ప్రధాన అభ్యాసం +[![ప్రారంభకులకు ML](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![ప్రారంభకులకు డేటా సైన్స్](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![ప్రారంభకులకు AI](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![ప్రారంభకులకు సైబర్‌సెక్యూరిటీ](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### కోపైలట్ సిరీస్ +### కాపిలట్ సిరీస్ [![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) @@ -130,21 +129,21 @@ LangChain4j మరియు Azure OpenAI GPT-5.2 తో AI అనువర్త ## సహాయం పొందడం -మీరు చిక్కుకున్నట్లయితే లేదా AI యాప్‌లను నిర్మించడంలో ఏవైనా ప్రశ్నలు ఉంటే, చేరండి: +మీరు చిక్కుబడినట్లయితే లేదా AI యాప్స్‌ను తయారుచేసే విషయంలో ఏవైనా ప్రశ్నలు ఉంటే, చేరండి: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -మీకు ఉత్పత్తి అభిప్రాయం లేదా నిర్మాణంలో లోపాలు ఉంటే సందర్శించండి: +తయారుచేసేటప్పుడు ఉత్పత్తి ప్రతిస్పందన లేదా లోపాలు ఉంటే సందర్శించండి: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## లైసెన్స్ -MIT లైసెన్స్ - వివరాల కోసం [LICENSE](../../LICENSE) ఫైల్ చూడండి. +MIT లైసెన్స్ - వివరాలకు [LICENSE](../../LICENSE) ఫైల్ చూడండి. --- -**నిరసన**: -ఈ డాక్యుమెంట్‌ను AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నించినప్పటికీ, ఆటోమేటెడ్ అనువాదాలలో పూర్వగ్రహాలు లేదా తప్పిదాలు ఉండవచ్చు అని దయచేసి గమనించండి. స్థానిక భాషలో ఉన్న అసలు డాక్యుమెంట్ ను ప్రామాణిక మాధ్యమంగా పరిగణించాలి. కీలకమైన సమాచారానికి, ప్రొఫెషనల్ మానవ అనువాదం సిఫార్సుచేయబడుతుంది. ఈ అనువాదం వాడకం వల్ల ఏర్పడిన ఏ ఇతరర్థం లేకపోవటం లేదా తప్పుదోవ పట్టటం కోసం మేము బాధ్యత వహించము. +**అస్వీకరణ**: +ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటెడ్ అనువాదాలు తప్పులు లేదా అసమగ్రతలను కలిగి ఉండవచ్చు. దాని స్వదేశ భాషలో ఉన్న అసలు పత్రాన్ని అధికారం కలిగిన మూలంగా పరిగణించాలి. కీలకమైన సమాచారం కోసం, ప్రొఫెషనల్ మానవ అనువాదాన్ని సిఫారసు చేస్తాము. ఈ అనువాదం ఉపయోగం వల్ల కలిగే ఏవైనా అపార్థాలు లేదా తప్పుదారులు కోసం మేము బాధ్యత వహించము. \ No newline at end of file diff --git a/translations/te/docs/GLOSSARY.md b/translations/te/docs/GLOSSARY.md index 0a381bb25..f6761b0a1 100644 --- a/translations/te/docs/GLOSSARY.md +++ b/translations/te/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j పదజాలం +# LangChain4j శబ్దకోశం -## зміాంశం +## కంటెంట్ పట్టిక -- [ముఖ్య కాన్సెప్ట్‌లు](../../../docs) -- [LangChain4j భాగాలు](../../../docs) -- [AI/ML కాన్సెప్ట్‌లు](../../../docs) -- [గార్డ్‌రేల్స్](../../../docs) -- [ప్రాంప్ట్ ఇంజనీరింగ్](../../../docs) -- [RAG (రీట్రీవల్-ఆగ్మెంటెడ్ జనరేషన్)](../../../docs) -- [ఏజెంట్లు మరియు టూల్స్](../../../docs) -- [ఏజెంటిక్ మాడ్యూల్](../../../docs) -- [మోడల్ కాంటెక్స్ట్ ప్రోటోకాల్ (MCP)](../../../docs) -- [అజ్యూర్ సర్వీసులు](../../../docs) -- [పరీక్షలు మరియు అభివృద్ధి](../../../docs) +- [ప్రధాన సిద్ధాంతాలు](#ప్రధాన-సిద్ధాంతాలు) +- [LangChain4j భాగాలు](#langchain4j-భాగాలు) +- [AI/ML సిద్ధాంతాలు](#aiml-సిద్ధాంతాలు) +- [గార్డ్‌రైళ్లు](#గార్డ్‌రైళ్లు) +- [ప్రాంప్ట్ ఇంజనీరింగ్](#prompt-engineering---module-02) +- [RAG (రిట్రీవల్-అగ్మెంటెడ్ జనరేషన్)](#rag-retrieval-augmented-generation---module-03) +- [ఏజెంట్లు మరియు టూల్స్](#agents-and-tools---module-04) +- [ఏజెంటిక్ మాడ్యూల్](#agentic-module---module-05) +- [మోడల్ కాన్టెక్స్ట్ ప్రోటోకాల్ (MCP)](#model-context-protocol-mcp---module-05) +- [అజ్యూర్ సర్వీసులు](#azure-services---module-01) +- [టెస్టింగ్ మరియు అభివృద్ధి](#testing-and-development---testing-guide) -కోర్సు మొత్తం ఉపయోగించే పదాలు మరియు కాన్సెప్ట్‌ల త్వరిత సూచిక. +కోర్సులో ఉపయోగించే పదాలు మరియు సిద్ధాంతాల త్వరిత సూచిక. -## ముఖ్య కాన్సెప్ట్‌లు +## ప్రధాన సిద్ధాంతాలు -**AI ఏజెంట్** - AIని ఉపయోగించి స్వతంత్రంగా తార్కికత మరియు చర్యలు తీసుకునే వ్యవస్థ. [Module 04](../04-tools/README.md) +**AI ఏజెంట్** - AI ఉపయోగించి స్వతంత్రంగా తర్కం చేసుకుని చర్య తీసుకునే సిస్టమ్. [Module 04](../04-tools/README.md) -**చెయిన్** - అవుట్పుట్ తదుపరి దశకి పోషణ చేసే చర్యల సన్నివేశం. +**చైన్** - అవుట్‌పుట్ తదుపరి దశకి ఫీడ్ అయ్యే ఆపరేషన్ల క్రమం. -**చంకింగ్** - డాక్యుమెంట్లను చిన్న భాగాలుగా విభజించడం. సాధారణంగా: 300-500 టోకెన్లతో ఒవర్‌లాప్. [Module 03](../03-rag/README.md) +**chunking** - డాక్యుమెంట్లను చిన్న ముక్కలుగా విభజించడం. సాధారణంగా: 300-500 టోకెన్లు స్థలాంతరం కలిగి. [Module 03](../03-rag/README.md) -**కాంటెక్స్ట్ విండో** - మోడల్ ప్రాసెస్ చేయగల గరిష్ట టోకెన్లు. GPT-5.2: 400K టోకెన్ల (అంతర్గత 272K, అవుట్పుట్ 128K). +**కాంటెక్స్ట్ విండో** - మోడల్ ప్రాసెస్ చేయగల గరిష్ట టోకెన్ల సంఖ్య. GPT-5.2: 400K టోకెన్లు (ఉపాదానం 272K, అవుట్‌పుట్ 128K). -**ఎంబెడింగ్స్** - టెక్స్ట్ అర్ధాన్ని సూచించే సంఖ్యాపరమైన వెక్టర్లు. [Module 03](../03-rag/README.md) +**ఎంబెడ్డింగ్స్** - టెక్స్ట్ అర్థాన్ని సూచించే సంఖ్యాత్మక వెక్టర్లు. [Module 03](../03-rag/README.md) -**ఫంక్షన్ కాలింగ్** - మోడల్ బాహ్య ఫంక్షన్లను పిలవడానికి నిర్మిత అభ్యర్థనలను సృష్టిస్తుంది. [Module 04](../04-tools/README.md) +**ఫంక్షన్ కాలింగ్** - మోడల్ బాహ్య ఫంక్షన్‌లను పిలవడానికి నిర్మిత అభ్యర్థనలను రూపొందిస్తుంది. [Module 04](../04-tools/README.md) -**హాలుసినేషన్** - మోడళ్లు తప్పు అయినా సహజమైన సమాచారాన్ని సృష్టిస్తాయి. +**హాల్యూసినేషన్** - మోడల్స్ తప్పు అయిన కానీ నమ్మదగ్గ సమాచారం ఉత్పత్తి చేసే పరిస్థితి. **ప్రాంప్ట్** - భాషా మోడల్‌కు టెక్స్ట్ ఇన్‌పుట్. [Module 02](../02-prompt-engineering/README.md) -**సెమాంటిక్ సెర్చ్** - కీవర్డ్స్ కాకుండా అర్థం ఆధారంగా సెర్చ్ చేయడం ఎంబెడింగ్స్ ఉపయోగించి. [Module 03](../03-rag/README.md) +**సెమాంటిక్ సెర్చ్** - కీవర్డ్స్ కాకుండా అర్థం ఆధారంగా శోధన ఎంబెడ్డింగ్స్ ఉపయోగించి. [Module 03](../03-rag/README.md) -**స్టేట్‌ఫుల్ vs స్టేట్‌లెస్** - స్టేట్‌లెస్: జ్ఞాపకశక్తి లేదు. స్టేట్‌ఫుల్: సంభాషణ చరిత్రని నిలుపుతుంది. [Module 01](../01-introduction/README.md) +**స్టేట్‌ఫుల్ vs స్టేట్‌लेస్** - స్టేట్‌లెస్: జ్ఞాపకం లేమి. స్టేట్‌ఫుల్: సంభాషణ చరిత్ర నిలుపుతుంది. [Module 01](../01-introduction/README.md) -**టోకెన్లు** - మోడళ్లు ప్రాసెస్ చేసే ప్రాథమిక టెక్స్ట్ యూనిట్లు. ఖర్చులు, పరిమితులు ప్రభావితం చేస్తాయి. [Module 01](../01-introduction/README.md) +**టోకెన్లు** - మోడల్స్ ప్రాసెస్ చేసే ప్రాథమిక టెక్స్ట్ యూనిట్లు. ఖర్చులు మరియు పరిమితులు ప్రభావితం చేస్తాయి. [Module 01](../01-introduction/README.md) -**టూల్ చైనింగ్** - ఒక టూల్ అవుట్పుట్ తదుపరి కాల్‌ను సూచిస్తుంది. [Module 04](../04-tools/README.md) +**టూల్ చైనింగ్** - అవుట్‌పుట్ తదుపరి కాల్‌కు సమాచారమిచ్చే అనుక్ర‌మంలో వర్క్ చేస్తాయి. [Module 04](../04-tools/README.md) ## LangChain4j భాగాలు **AiServices** - టైప్-సేఫ్ AI సర్వీస్ ఇంటర్‌ఫేస్‌లను సృష్టిస్తుంది. -**OpenAiOfficialChatModel** - OpenAI మరియు Azure OpenAI మోడల్స్ కోసం ఏకీకృత క్లయింట్. +**OpenAiOfficialChatModel** - OpenAI మరియు Azure OpenAI మోడల్స్ కోసం ఐక్య క్లయింట్. -**OpenAiOfficialEmbeddingModel** - OpenAI ఆఫీషియల్ క్లయింట్ ఉపయోగించి ఎంబెడింగ్స్ సృష్టిస్తుంది (OpenAI మరియు Azure OpenAI రెండింటికీ మద్దతు). +**OpenAiOfficialEmbeddingModel** - OpenAI అధికారిక క్లయింట్ ఉపయోగించి ఎంబెడ్డింగ్స్ సృష్టిస్తుంది (OpenAI మరియు Azure OpenAI రెండింటినీ మద్దతు ఇస్తుంది). **ChatModel** - భాషా మోడల్స్ కోసం ప్రధాన ఇంటర్‌ఫేస్. -**ChatMemory** - సంభాషణ చరిత్రను నిలుపుతుంది. +**ChatMemory** - సంభాషణ చరిత్ర నిలుపుతుంది. -**ContentRetriever** - RAG కోసం సంబంధించిన డాక్యుమెంటు చంక్స్‌ను కనుగొంటుంది. +**ContentRetriever** - RAG కోసం సంబంధిత డాక్యుమెంట్ ముక్కలను కనుగొంటుంది. -**DocumentSplitter** - డాక్యుమెంట్లను చంక్స్‌గా విడగొడుతుంది. +**DocumentSplitter** - డాక్యుమెంట్లను ముక్కలుగా విభజిస్తుంది. -**EmbeddingModel** - టెక్స్ట్‌ను సంఖ్యాపరమైన వెక్టర్‌లుగా మారుస్తుంది. +**EmbeddingModel** - టెక్స్ట్‌ను సంఖ్యాత్మక వెక్టర్లుగా మార్చుతుంది. -**EmbeddingStore** - ఎంబెడింగ్స్ నిల్వ చేయడం మరియు పొందడం. +**EmbeddingStore** - ఎంబెడ్డింగ్స్ నిలుపుతుంది మరియు ఆహ్వానిస్తుంది. -**MessageWindowChatMemory** - ఇటీవల సందేశాల స్లైడింగ్ విండోను నిర్వహిస్తుంది. +**MessageWindowChatMemory** - తాజా సందేశాల స్లైడింగ్ విండోని నిర్వహిస్తుంది. -**PromptTemplate** - `{{variable}}` ప్లేస్‌హోల్డర్లతో పునర్వినియోగించదగిన prompts సృష్టిస్తుంది. +**PromptTemplate** - `{{variable}}` ప్లేస్‌హోల్డర్‌లతో పునర్వినియోగదారుడు ప్రాంప్ట్‌లు సృష్టిస్తుంది. -**TextSegment** - మెటాడేటాతో కూడిన టెక్స్ట్ చంక్. RAGలో ఉపయోగం. +**TextSegment** - మెటాడేటా ఉన్న టెక్స్ట్ ముక్క. RAGలో ఉపయోగించబడుతుంది. -**ToolExecutionRequest** - టూల్ నడపడం కోసం అభ్యర్థనను సూచిస్తుంది. +**ToolExecutionRequest** - టూల్ అమలు అభ్యర్థనను సూచిస్తుంది. -**UserMessage / AiMessage / SystemMessage** - సంభాషణ‌లో ఉపయోగించే సందేశ రకాలు. +**UserMessage / AiMessage / SystemMessage** - సంభాషణ సందేశ రకాల. -## AI/ML కాన్సెప్ట్‌లు +## AI/ML సిద్ధాంతాలు -**Few-Shot లర్నింగ్** - promptsలో ఉదాహరణలివ్వడం. [Module 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - ప్రాంప్ట్‌లలో ఉదాహరణలు అందించడం. [Module 02](../02-prompt-engineering/README.md) -**లార్జ్ లాంగ్వేజ్ మోడల్ (LLM)** - విస్తృత టెక్స్ట్ డేటా మీద శిక్షణ పొందిన AI మోడల్స్. +**పెద్ధ భాషా మోడల్ (LLM)** - విశాల టెక్స్ట్ డేటాపైన శిక్షణ పొందిన AI మోడల్స్. -**రీజనింగ్ ఎఫర్ట్** - GPT-5.2లో ఆలోచనా లోతును నియంత్రించే పారామీటర్. [Module 02](../02-prompt-engineering/README.md) +**తర్కశక్తి యత్నం** - GPT-5.2లో ఆలోచన లోతును నియంత్రించే పారామితి. [Module 02](../02-prompt-engineering/README.md) -**టెంపరేచర్** - అవుట్పుట్ రాండమ్నెస్‌ను నియంత్రిస్తుంది. తక్కువ=నియమిత, అధిక=సృజనాత్మక. +**తాపనం** - అవుట్‌పుట్ యాదృచ్ఛికత నియంత్రణ. తక్కువ=నిర్ధారిత, ఎక్కువ=సృజనాత్మక. -**వెక్టర్ డేటాబేస్** - ఎంబెడింగ్స్ కోసం ప్రత్యేక డేటాబేస్. [Module 03](../03-rag/README.md) +**వెక్టర్ డేటాబేస్** - ఎంబెడ్డింగ్స్ కోసం ప్రత్యేక డేటాబేస్. [Module 03](../03-rag/README.md) -**జీరో-షాట్ లర్నింగ్** - ఉదాహరణలు లేకుండా టాస్కులు చేయడం. [Module 02](../02-prompt-engineering/README.md) +**సీరో-షాట్ లెర్నింగ్** - ఉదాహరణల లేకుండా పనులు చేయడం. [Module 02](../02-prompt-engineering/README.md) -## గార్డ్‌రేల్స్ - [Module 00](../00-quick-start/README.md) +## గార్డ్‌రైళ్లు -**డిఫెన్స్ ఇన్ డెప్త్** - అప్లికేషన్-స్థాయి గార్డ్‌రేల్స్ మరియు ప్రొవైడర్ సేఫ్టీ ఫిల్టర్లను కలిపిన బహుళ పొర భద్రతా దృష్టికోణం. +**డిఫెన్స్ ఇన్ డెప్త్** - అప్లికేషన్ స్థాయి గార్డ్‌రైళ్లు మరియు ప్రొవైడర్ సేఫ్టీ ఫిల్టర్స్ కలిపిన బహుళ-స్థాయి భద్రతా దృష్టికోణం. -**హార్డ్ బ్లాక్** - తీవ్రమైన కంటెంట్ పాలసీ ఉల్లంఘనలపై ప్రొవైడర్ HTTP 400 లోపం విసిరిపోతుంది. +**హార్డ్ బ్లాక్** - తీవ్రమైన కంటెంట్ లంగకాలు కోసం ప్రొవైడర్ HTTP 400 లోపాన్ని త్రో చేస్తుంది. -**InputGuardrail** - LangChain4j ఇంటర్‌ఫేస్ యూజర్ ఇన్‌పుట్‌ను LLMకు చేరేందుకు ముందే జాగ్రత్తగా వాలిడేట్ చేసి ఖర్చు మరియు లేటెన్సీ తగ్గిస్తుంది. +**InputGuardrail** - LLMకు చేరేముందు వినియోగదారుని ఇన్‌పుట్‌ను ధృవీకరించడానికి LangChain4j ఇంటర్‌ఫేస్. హానికరమైన ప్రాంప్ట్‌లను ముందే బ్లాక్ చేసి ఖర్చు మరియు ఆలస్యం తగ్గిస్తుంది. -**InputGuardrailResult** - గార్డ్‌రెయిల్ వాలిడేషన్ రిటర్న్ రకం: `success()` లేదా `fatal("కారణం")`. +**InputGuardrailResult** - గార్డ్‌రైల్ ధృవీకరణకు రిటర్న్ రకం: `success()` లేదా `fatal("reason")`. -**OutputGuardrail** - AI సమాధానాలు యూజర్లకు పంపే ముందు సరి చూసే ఇంటర్‌ఫేస్. +**OutputGuardrail** - వినియోగదారులకు తిరిగి ఇవ్వకముందు AI ప్రతిస్పందనలను ధృవీకరించే ఇంటర్‌ఫేస్. -**Provider Safety Filters** - AI ప్రొవైడర్ల (ఉదా: GitHub Models) లోపాల్ని API స్థాయిలో గుర్తించే సిధ్ధమైన కంటెంట్ ఫిల్టర్లు. +**Provider Safety Filters** - API స్థాయిలో ఉల్లంఘనలను పట్టుకునే AI ప్రొవైడర్‌ల (ఉదా: Azure OpenAI) నిర్మిత కంటెంట్ ఫిల్టర్స్. -**Soft Refusal** - మోడల్ దయతో సమాధానం ఇవ్వడాన్ని తిరస్కరించి లోపం లేకుండా ఒప్పుకోకపోవడం. +**Soft Refusal** - తప్పు చూపకుండా మోడల్ వినమ్రంగా జవాబు ఇవ్వడం నిరాకరిస్తుంది. ## ప్రాంప్ట్ ఇంజనీరింగ్ - [Module 02](../02-prompt-engineering/README.md) -**చెయిన్-ఆఫ్-థాట్** - మెరుగైన ఖచ్చితత్వం కోసం దశల వారీ తార్కికత. +**చైన్-ఆఫ్-థాట్** - మెరుగైన ఖచ్చితత్వానికి దశలవారీ తర్కం. -**కన్స్ట్రెయిన్డ్ అవుట్పుట్** - నిర్దిష్ట ఫార్మాట్ లేదా నిర్మాణం గట్టి ఆచరణలోకి తీసుకెళ్తుంది. +**కొనసేం అవుట్‌పుట్** - నిర్ధిష్ట ఫార్మాట్ లేదా నిర్మాణం బంధించి అమలు. -**హై ఈగర్నెస్** - GPT-5.2 సంపూర్ణ తార్కికతకు రూపొందించిన నమూనా. +**హై ఆగర్నెస్** - పూర్తిగా తర్కం చేసేందుకు GPT-5.2 నమూనా. -**లో ఈగర్నెస్** - GPT-5.2 త్వరిత సమాధానాలకు నమూనా. +**లో ఆగర్నెస్** - త్వరిత జవాబుల కోసం GPT-5.2 నమూనా. -**మల్టీ-టర్న్ సంభాషణ** - మార్పిడులపై కాంటెక్స్ట్ కొనసాగించడం. +**బహుళ-టర్న్ సంభాషణ** - మార్పిడులలో కాంటెక్స్ట్ స్థిరపరిచే ప్రక్రియ. -**రోల్-బేస్డ్ ప్రాంప్టింగ్** - సిస్టమ్ సందేశాల ద్వారా మోడల్ వ్యక్తిత్వాన్ని సెట్ చేయడం. +**పాత్ర-ఆధారిత ప్రాంప్టింగ్** - సిస్టమ్ సందేశాల ద్వారా మోడల్ వ్యక్తిత్వాన్ని సెట్ చేయడం. -**సెల్ఫ్-రెఫ్లెక్షన్** - మోడల్ తన అవుట్పుట్‌ను అంచనా వేచి మెరుగుపరుస్తుంది. +**స్వयं-పరిశీలన** - మోడల్ తన అవుట్‌పుట్‌ను స్వీయ మౌల్యాంకనం చేసి మెరుగుపరుస్తుంది. -**స్ట్రక్చర్లు అనాలిసిస్** - స్థిరమైన మూల్యాంకన ఫ్రేమ్‌వర్క్. +**నిర్మిత విశ్లేషణ** - స్థిరమైన అంచనా ఫ్రేమ్‌వర్క్. -**టాస్క్ ఎగ్జిక్యూషన్ ప్యాటర్న్** - ప్లాన్ → ఎగ్జిక్యూట్ → సారాంశం. +**టాస్క్ ఎగ్జిక్యూషన్ ప్యాటర్న్** - ప్రణాళిక → అమలు → సారాంశం. -## RAG (రీట్రీవల్-ఆగ్మెంటెడ్ జనరేషన్) - [Module 03](../03-rag/README.md) +## RAG (రిట్రీవల్-అగ్మెంటెడ్ జనరేషన్) - [Module 03](../03-rag/README.md) -**డాక్యుమెంట్ ప్రాసెసింగ్ పైప్‌లైన్** - లోడ్ → చంక్ → ఎంబెడ్ → స్టోర్. +**డాక్యుమెంట్ ప్రాసెసింగ్ పైప్‌లైన్** - లోడ్ → ముక్కలు → ఎంబెడ్ → నిల్వ. -**ఇన్-మెమరీ ఎంబెడ్డింగ్ స్టోర్** - పరీక్షలకు తాత్కాలిక నిల్వ. +**ఇన్-మెమరీ ఎంబెడ్డింగ్ స్టోర్** - టెస్టింగ్ కోసం అస్థిర నిల్వ. -**RAG** - రిట్రీవల్ మరియు జనరేషన్ కలిపి సమాధానాలను స్థిరపరుస్తుంది. +**RAG** - రిట్రీవల్ మరియు జనరేషన్ కలిపి ప్రతిస్పందనలకు ఆధారం ఇస్తుంది. -**సిమిలారిటీ స్కోర్** - సెమాంటిక్ సాదృশ্যానికి 0-1 మధ్య కొలిచే ప్రమాణం. +**సాదృశ్య స్కోర్** - సెమాంటిక్ సమానత్వం కొలమానం (0-1). -**సోర్స్ రిఫరెన్స్** - తీసుకున్న కంటెంట్‌కు సంబంధించిన మెటాడేటా. +**సోర్స్ రిఫరెన్స్** - రిట్రీవ్ చేయబడిన కంటెంట్ మీద మెటాడేటా. ## ఏజెంట్లు మరియు టూల్స్ - [Module 04](../04-tools/README.md) -**@Tool అనొటేషన్** - జావా మెథడ్స్‌ను AI-కాల్ చేయదగిన టూల్స్‌గా గుర్తించే గుర్తింపు. +**@Tool Annotation** - Java మిథోడ్లను AI-కాల్ చేయగల టూల్స్‌గా గుర్తిస్తుంది. -**ReAct ప్యాటర్న్** - రీజనింగ్ → చర్య → పరిశీలన → మళ్లీ. +**ReAct Pattern** - తర్కం → చర్య → పరిశీలన → పునరావృతం. -**సెషన్ మేనేజ్మెంట్** - వేర్వేరు యూజర్లకు వ్యక్తిగత కాంటెక్స్ట్‌లను నిర్వహించడం. +**సెషన్ మేనేజ్‌మెంట్** - వేరు వినియోగదారులకు వేరు కాంటెక్స్ట్‌ల నిర్వహణ. **టూల్** - AI ఏజెంట్ పిలవగల ఫంక్షన్. -**టూల్ వివరణ** - టూల్ ప్రయోజనం మరియు పారామీటర్ల డాక్యుమెంటేషన్. +**టూల్ వివరణ** - టూల్ ఉద్దేశ్యం మరియు పారామితులు పై డాక్యుమెంటేషన్. ## ఏజెంటిక్ మాడ్యూల్ - [Module 05](../05-mcp/README.md) -**@Agent అనొటేషన్** - ఇంటర్‌ఫేస్‌లను AI ఏజెంట్లుగా మరియు వ్యవహరణ నిర్వచనంతో గుర్తించడం. +**@Agent Annotation** - ఇంటర్‌ఫేస్‌లను AI ఏజెంట్లు అని ప్రకటించే డిక్లరేటివ్ వెయ్. -**ఏజెంట్ లిసనర్** - `beforeAgentInvocation()` మరియు `afterAgentInvocation()` ద్వారా ఏజెంట్ నడుపుటను పర్యవేక్షించే హుక్. +**Agent Listener** - `beforeAgentInvocation()` మరియు `afterAgentInvocation()` ద్వారా ఏజెంట్ అమలు పర్యవేక్షణ కోసం హుక్. -**ఏజెంటిక్ స్కోప్** - ఏజెంట్లు ఉత్పత్తులను `outputKey` ఉపయోగించి నిల్వ చేసే భాగస్వామ్య జ్ఞాపకం తదుపరి ఏజెంట్లు వినియోగించడానికి. +**Agentic Scope** - ఏజెంట్లు ఫలితాలను `outputKey` ఉపయోగించి నిల్వ చేసే పంచబడిన మెమరీ, అంతర ఏజెంట్లు అందుకొని ఉపయోగిస్తాయి. -**AgenticServices** - `agentBuilder()` మరియు `supervisorBuilder()` ఉపయోగించి ఏజెంట్‌లు సృష్టించే ఫ్యాక్టరీ. +**AgenticServices** - `agentBuilder()` మరియు `supervisorBuilder()` ఉపయోగించి ఏజెంట్ల సృష్టికి ఫ్యాక్టరీ. -**షరతుల ఆధారిత వర్క్‌ఫ్లో** - వివిధ నైపుణ్య ఏజెంట్లకు షరతుల ప్రకారం మార్గదర్శనం. +**శరతుల ఆధారంగా వర్క్‌ఫ్లో** - పరిస్థితుల ఆధారంగా విభిన్న నిపుణ ఏజెంట్లకు మార్గం. -**హ్యూమన్-ఇన్-ది-లూప్** - మానవ అనుమతి లేదా కంటెంట్ సమీక్ష కోసం వర్క్‌ఫ్లో నమూనా. +**మానవ-సహభాగిత్వం** - మానవ తనిఖీలు లేదా కంటెంట్ సమీక్ష కోసం వర్క్‌ఫ్లో నమూనా. -**langchain4j-agentic** - ప్రకటనాత్మక ఏజెంట్ నిర్మాణం కోసం మేవెన్ డిపెండెన్సీ (ప్రయోగాత్మక). +**langchain4j-agentic** - డిక్లరేటివ్ ఏజెంట్ నిర్మాణం కొరకు మావెన్ ఆధారిత (ప్రయోగాత్మక). -**లూప్ వర్క్‌ఫ్లో** - నిబంధన (ఉదా: క్వాలిటీ స్కోర్ ≥ 0.8) కలుగునప్పటివరకు ఏజెంట్ అమలును పునరావృతం చేయడం. +**లూప్ వర్క్‌ఫ్లో** - ఒక పరిస్థితి (ఉదా: నాణ్యత స్కోర్ ≥ 0.8) తీరేవరకు ఏజెంట్ అమలు పునరావృతం. -**outputKey** - ఏజెంట్ అనొటేషన్ పారామీటర్, తద్వారా Agentic స్కోప్‌లో ఫలితాలు ఎక్కడ నిల్వ చేయబడతాయో సూచిస్తుంది. +**outputKey** - ఫలితాలు Agentic Scopeలో ఎక్కడ నిల్వ చేయాలో గుర్తించే ఏజెంట్ అనోటేషన్ పారామెటర్. -**ప్యారలల్ వర్క్‌ఫ్లో** - స్వతంత్ర టాస్కులకు బహుముఖ ఏజెంట్లను ఒకసారిగా నడిపించడం. +**పారాallel వర్క్‌ఫ్లో** - స్వతంత్ర పనుల కోసం బహుసంఖ్యలో ఏజెంట్లను సమాంతరంగా నడిపించటం. -**రెస్పాన్స్ స్ట్రాటజీ** - సూపర్వైజర్ చివరి జవాబును ఎలా రూపొందిస్తుందో: LAST, SUMMARY, లేదా SCORED. +**ప్రతిస్పందన వ్యూహం** - సూపర్వైజర్ తుది జవాబు తయారీ విధానం: LAST, SUMMARY, లేదా SCORED. -**సీక్వెన్షియల్ వర్క్‌ఫ్లో** - అవుట్పుట్ తదుపరి దశకు వెళ్లే విధంగా ఏజెంట్లను క్రమబద్ధీకరించి నడిపించడం. +**సీక్వెన్షియల్ వర్క్‌ఫ్లో** - అవుట్‌పుట్ తదుపరి దశకు ప్రయాణించే క్రమంలో ఏజెంట్ల అమలును నిర్వహించడం. -**సూపర్వైజర్ ఏజెంట్ ప్యాటర్న్** - ఏజెంటిక్ ప్రత్యేక నమూనా, ఒక సూపర్వైజర్ LLM ఏ ఉప-ఏజెంట్లను పిలవాలో సజీవంగా నిర్ణయిస్తుంది. +**Supervisor Agent Pattern** - సూపర్వైజర్ LLM డైనమిక్‌గా ఉప ఏజెంట్లను పిలవడాన్ని నిర్ణయించే అభివృద్ధి చెందిన ఏజెంటిక్ నమూనా. -## మోడల్ కాంటెక్స్ట్ ప్రోటోకాల్ (MCP) - [Module 05](../05-mcp/README.md) +## మోడల్ కాన్టెక్స్ట్ ప్రోటోకాల్ (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4jలో MCP ఇంటిగ్రేషన్ కోసం మేవెన్ డిపెండెన్సీ. +**langchain4j-mcp** - LangChain4jలో MCP ఇంటిగ్రేషన్ కోసం మావెన్ ఆధారిత. -**MCP** - మోడల్ కాంటెక్స్ట్ ప్రోటోకాల్: AI యాప్‌లను బాహ్య టూల్స్‌తో అనుసంధానించడానికి סטాండర్డ్. ఒక్కసారి నిర్మించండి, ఎక్కడికైనా ఉపయోగించండి. +**MCP** - మోడల్ కాన్టెక్స్ట్ ప్రోటోకాల్: AI యాప్స్‌ను బాహ్య టూల్స్‌కి కనెక్ట్ చేయడానికి ప్రమాణీకృత ప్రోటోకాల్. ఒకసారి నిర్మించి ప్రతి చోటు ఉపయోగించండి. -**MCP క్లయింట్** - MCP సర్వర్లకు కనెక్ట్ అయ్యే, టూల్స్‌ను కనుగొని ఉపయోగించే అప్లికేషన్. +**MCP క్లయింట్** - MCP సర్వర్స్‌తో కనెక్ట్ అయి టూల్స్‌ను తెలుసుకుంది ఉపయోగించే యాప్లికేషన్. -**MCP సర్వర్** - స్పష్టమైన వివరణలు మరియు పారామీటర్ స్కీమాలతో MCP ద్వారా టూల్స్ అందించే సేవ. +**MCP సర్వర్** - స్పష్టమైన వివరణలు మరియు పారామితి స్కీమాలతో టూల్స్‌ను MCP ద్వారా అందించే సర్వీస్. -**McpToolProvider** - AI సర్వీసులు మరియు ఏజెంట్లలో ఉపయోగించడానికి MCP టూల్స్‌ను రాప్ చేసే LangChain4j భాగము. +**McpToolProvider** - AI సర్వీసులు మరియు ఏజెంట్లలో ఉపయోగించడానికి MCP టూల్స్‌ను ప్యాకేజ్ చేసే LangChain4j భాగం. -**McpTransport** - MCP కమ్యూనికేషన్ ఇంటర్‌ఫేస్. అమ‌లులో స్ట్డియో మరియు HTTP ఉన్నాయి. +**McpTransport** - MCP కమ్యూనికేషన్ ఇంటర్‌ఫేస్. అమలు: Stdio మరియు HTTP. -**Stdio ట్రాన్స్‌పోర్ట్** - లోకల్ ప్రాసెస్ ట్రాన్స్‌పోర్ట్ stdin/stdout ద్వారా. ఫైల్‌సిస్టమ్ యాక్సెస్ లేదా కమాండ్-లైన్ టూల్స్‌కు ఉపయోగకరం. +**Stdio ట్రాన్స్‌పోర్ట్** - stdin/stdout ద్వారా లోకల్ ప్రాసెస్ ట్రాన్స్‌పోర్ట్. ఫైల్‌సిస్టమ్ యాక్సెస్ లేదా కమాండ్‌లైన్ టూల్స్‌కు ఉపయోగకరం. -**StdioMcpTransport** - LangChain4j అమలు MCP సర్వర్‌ను subprocessగా స్టార్ట్ చేస్తుంది. +**StdioMcpTransport** - MCP సర్వర్‌ను సబ్‌ప్రాసెస్‌గా స్పోన్ చేయడానికి LangChain4j అమలు. -**టూల్ డిస్కవరీ** - క్లయింట్ టూల్స్ కోసం సర్వర్‌ను ప్రశ్నిస్తాడు వివరణలతో మరియు స్కీమాలతో. +**టూల్ డిస్కవరీ** - క్లయింట్ వివరణలు మరియు స్కీమాలతో అందుబాటులో ఉన్న టూల్స్ కోసం సర్వర్‌ను విచారణ చేస్తుంది. ## అజ్యూర్ సర్వీసులు - [Module 01](../01-introduction/README.md) -**Azure AI Search** - వెక్టర్ సామర్ధ్యాలతో క్లౌడ్ సెర్చ్. [Module 03](../03-rag/README.md) +**Azure AI Search** - వెక్టర్ సామర్థ్యాలతో క్లౌడ్ శోధన. [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Azure వనరులను డిప్లాయ్ చేస్తుంది. +**Azure Developer CLI (azd)** - అజ్యూర్ వనరులను డిప్లాయ్ చేస్తుంది. -**Azure OpenAI** - మైక్రోసాఫ్ట్ ఎంటర్ప్రైజ్ AI సర్వీస్. +**Azure OpenAI** - మైక్రోసాఫ్ట్ ఎంటర్‌ప్రైజ్ AI సర్వీస్. -**Bicep** - Azure ఇన్‌ఫ్రాస్ట్రక్చర్-ఏ-కోడ్ భాష. [Infrastructure Guide](../01-introduction/infra/README.md) +**Bicep** - అజ్యూర్ ఇన్‌ఫ్రాస్ట్రక్చర్-కోడ్ భాష. [Infrastructure Guide](../01-introduction/infra/README.md) -**డిప్లాయ్‌మెంట్ పేరు** - Azureలో మోడల్ డిప్లాయ్‌మెంట్‌కు పేరును సూచిస్తుంది. +**డిప్లాయ్‌మెంట్ పేరు** - అజ్యూర్‌లో మోడల్ డిప్లాయ్‌మెంట్ కోసం పేరు. **GPT-5.2** - reasoning నియంత్రణతో తాజా OpenAI మోడల్. [Module 02](../02-prompt-engineering/README.md) -## పరీక్షలు మరియు అభివృద్ధి - [Testing Guide](TESTING.md) +## టెస్టింగ్ మరియు అభివృద్ధి - [Testing Guide](TESTING.md) -**డెవ్ కంటైనర్** - కంటైనరైజ్డ్ అభివృద్ధి వాతావరణం. [Configuration](../../../.devcontainer/devcontainer.json) +**డెవ్ కంటైనర్** - కంటైనర్ చేయబడిన అభివృద్ధి వాతావరణం. [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - ఉచిత AI మోడల్ ప్లేగ్రౌండ్. [Module 00](../00-quick-start/README.md) +**ఇన్-మెమరీ టెస్టింగ్** - మెమరీ నిల్వతో టెస్టింగ్. -**ఇన్-మెమరీ టెస్టింగ్** - మెమరీ నిల్వతో పరీక్షించడం. +**ఇంటిగ్రేషన్ టెస్టింగ్** - నిజమైన ఇన్‌ఫ్రాస్ట్రక్చర్‌తో టెస్టింగ్. -**ఇంటిగ్రేషన్ టెస్టింగ్** - నిజమైన ఇన్‌ఫ్రాస్ట్రక్చర్‌తో పరీక్ష. +**మావెన్** - జావా బిల్డ్ ఆటోమేషన్ టూల్. -**Maven** - జావా బిల్డ్ ఆటోమేషన్ టూల్. - -**Mockito** - జావా మాక్ ఫ్రేమ్‌వర్క్. +**Mockito** - జావా మాక్ ఫ్రేమ్‌워크. **Spring Boot** - జావా అప్లికేషన్ ఫ్రేమ్‌వర్క్. [Module 01](../01-introduction/README.md) --- -**వివరణ**: -ఈ దస్త్రాన్ని AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి పూర్వకంగా ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటెడ్ అనువాదాల్లో పొరపాట్లు లేదా లోపాలు ఉండే అవకాశం ఉంది. అసలు దస్త్రాన్ని దాని మూల భాషలోనే అధికారిక మూలంగా పరిగణించాలి. కీలకమైన సమాచారానికి, తగిన నిపుణుల మానవ అనువాదం సిఫార్సు చేయబడుతుంది. ఈ అనువాదం ఉపయోగంలోని ఎటువంటి అపార్థాలు లేదా తప్పుదోవలకు మేము బాధ్యులను కాదు. +**అస్వీకరణ**: +ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటెడ్ అనువాదాలు తప్పులు లేదా అసమగ్రతలను కలిగి ఉండవచ్చు. దాని స్వదేశ భాషలో ఉన్న అసలు పత్రాన్ని అధికారం కలిగిన మూలంగా పరిగణించాలి. కీలకమైన సమాచారం కోసం, ప్రొఫెషనల్ మానవ అనువాదాన్ని సిఫారసు చేస్తాము. ఈ అనువాదం ఉపయోగం వల్ల కలిగే ఏవైనా అపార్థాలు లేదా తప్పుదారులు కోసం మేము బాధ్యత వహించము. \ No newline at end of file diff --git a/translations/te/docs/TESTING.md b/translations/te/docs/TESTING.md index 914128346..cd311b17a 100644 --- a/translations/te/docs/TESTING.md +++ b/translations/te/docs/TESTING.md @@ -1,135 +1,134 @@ -# LangChain4j అనువర్తనాలను పరీక్షించడం +# LangChain4j అప్లికేషన్లను పరీక్షించడం -## సూచిక +## కంటెంట్స్ పట్టిక -- [త్వరిత ప్రారంభం](../../../docs) -- [పరీక్షలు ఏం కవర్ చేస్తాయో](../../../docs) -- [పరీక్షలు ఎలా నడపాలి](../../../docs) -- [VS కోడ్‌లో పరీక్షలు నడపడం](../../../docs) -- [పరీక్షా నమూనాలు](../../../docs) -- [పరీక్షా తత్వశాస్త్రం](../../../docs) -- [తరువాతి దశలు](../../../docs) +- [త్వరిత ప్రారంభం](#త్వరిత-ప్రారంభం) +- [పరీక్షలు ఏమి కవర్ చేస్తాయి](#పరీక్షలు-ఏమి-కవర్-చేస్తాయి) +- [పరీక్షలను నడిపించడం](#పరీక్షలను-నడిపించడం) +- [VS కోడ్‌లో పరీక్షల నడిపింపు](#vs-కోడ్‌లో-పరీక్షలు-నడిపించడం) +- [పరీక్షించే నమూనాలు](#పరీక్షించే-నమూనాలు) +- [పరీక్షల తత్త్వం](#పరీక్షల-తత్త్వం) +- [తదుపరి దశలు](#తదుపరి-దశలు) -ఈ గైడ్ API కీలు లేదా బాహ్య సర్వీసులు అవసరం లేకుండానే AI అనువర్తనాలను ఎలా పరీక్షించాలో చూపించే పరీక్షల ద్వారా మీకు మార్గనిర్దేశనం చేస్తుంది. +ఈ మార్గదర్శి API కీలు లేదా బాహ్య సేవలు అవసరం లేకుండా AI అప్లికేషన్లను ఎలా పరీక్షించాలో చూపించే పరీక్షల ద్వారా మీకు సహాయం చేస్తుంది. ## త్వరిత ప్రారంభం -ఒకే కమాండ్‌తో అన్ని పరీక్షలను నడపండి: +ఒకే కమాండ్ తో అన్ని పరీక్షలను నడపండి: -**బాష్:** +**Bash:** ```bash mvn test ``` -**పవర్‌షెల్:** +**PowerShell:** ```powershell mvn --% test ``` -అన్ని పరీక్షలు విజయవంతంగా పూర్తయ్యినప్పుడు, క్రింది స్క్రీన్‌షాట్ లాంటి అవుట్‌పుట్ కనిపిస్తుంది — పరీక్షలు ఎటువంటి వైఫల్యాలు లేకుండానే నడుస్తాయి. +అన్ని పరీక్షలు విజయవంతంగా పూర్తి అయితే, దిగువ స్ర్కీన్‌షాట్ లాంటి అవుట్‌పుట్ కనిపిస్తుంది — పరీక్షలు ఏ తప్పుల్లేకుండా నడుస్తున్నాయి. Successful Test Results -*విజయవంతమైన పరీక్ష నిర్వహణలో అన్ని పరీక్షలు వైఫల్యాలు లేకుండా విజయవంతంగా పూర్తి అవుతున్నాయి* +*ఏ తప్పుల్లేకుండా అన్ని పరీక్షలు విజయవంతంగా నడుస్తున్న దృశ్యం* -## పరీక్షలు ఏం కవర్ చేస్తాయో +## పరీక్షలు ఏమి కవర్ చేస్తాయి -ఈ కోర్సు స్థానికంగా నడిచే **యూనిట్ పరీక్షల** పై దృష్టి పెట్టింది. ప్రతి పరీక్ష ఒక నిర్దిష్ట LangChain4j భావనను వేరుగా చూపిస్తుంది. క్రింది పరీక్ష హిరార్కీ యూనిట్ పరీక్షలు ఎక్కడ फिटవుతున్నాయో తెలియజేస్తుంది — అవి త్వరితమైన, విశ్వసనీయమైన పునాది వాటి మీద మీ ఇతర పరీక్షా చర్యలు బిల్డ్ అవుతాయి. +ఈ కోర్సు ప్రాధాన్యంగా **యూనిట్ టెస్టులు** పై ఉంటుంది, అవి లోకల్ గా నడుస్తాయి. ప్రతి పరీక్ష ప్రత్యేక LangChain4j సూత్రాన్ని తానే ప్రదర్శిస్తుంది. క్రింద చూపిన పరీక్షా పిరమిడ్ లో యూనిట్ పరీక్షలు ఎక్కడ నిలబడ్డాయో సూచిస్తుంది — అవి వేగవంతమైన, నమ్మకమైన పునాదిని నిర్మిస్తాయి, మీరు తలపెట్టిన పరీక్షా వ్యూహం దీనిపై ఆధారపడుతుంది. Testing Pyramid -*యూనిట్ పరీక్షలు (త్వరితమైన, వేరుచేస్తున్న), ఇంటిగ్రేషన్ పరీక్షలు (నిజమైన కొంపోనెంట్లు), ఎండ్-టు-ఎండ్ పరీక్షల మద్య సమతుల్యాన్ని చూపే పరీక్షా పిరమిడ్. ఈ శిక్షణ యూనిట్ పరీక్షలను కవర్ చేస్తుంది.* +*యూనిట్ పరీక్షలు (త్వరగా, బహిష్కృతంగా), ఇంటిగ్రేషన్ పరీక్షలు (నిజమైన భాగాలు), అండ్-టు-ఎండ్ పరీక్షల మధ్య సమతుల్యత చూపుతూ పరీక్షా పిరమిడ్. ఈ శిక్షణ యూనిట్ పరీక్షలను కవర్ చేస్తుంది.* -| మాడ్యూల్ | పరీక్షలు | ఫోకస్ | ముఖ్య ఫైళ్ళు | +| మాడ్యూల్ | పరీక్షలు | దృష్టి | కీలక ఫైళ్ళు | |--------|-------|-------|-----------| -| **00 - త్వరిత ప్రారంభం** | 6 | ప్రాంప్ట్ టెంప్లేట్లు మరియు వేరియబుల్ ప్రత్యామ్నాయం | `SimpleQuickStartTest.java` | -| **01 - పరిచయం** | 8 | సంభాషణ జ్ఞాపకం మరియు స్థితిస్థాపక చాట్ | `SimpleConversationTest.java` | -| **02 - ప్రాంప్ట్ ఇంజనీరింగ్** | 12 | GPT-5.2 నమూనాలు, ఉత్సాహ స్థాయిలు, నిర్మాణాత్మక అవుట్‌పుట్ | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | డాక్యుమెంట్ ఇంజెస్ట్, ఎంబెడింగ్స్, సమానత్వ శోధన | `DocumentServiceTest.java` | +| **01 - పరిచయం** | 8 | సంభాషణ స్మృతిఅం మరియు రాష్ట్రం గల సంభాషణ | `SimpleConversationTest.java` | +| **02 - ప్రాంప్ట్ ఇంజినీరింగ్** | 12 | GPT-5.2 నమూనాలు, ఉత్సాహ స్థాయిలు, నిర్మిత అవుట్‌పుట్ | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | డాక్యుమెంట్ ఇంజెస్టింగ్, ఎంబెడ్డింగ్లు, సారూప్యత శోధన | `DocumentServiceTest.java` | | **04 - టూల్స్** | 12 | ఫంక్షన్ కాలింగ్ మరియు టూల్ చైనింగ్ | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | మోడల్ కాంటెక్స్ట్ ప్రోటోకాల్ స్త్డీయో ట్రాన్స్పోర్ట్‌తో | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | మోడల్ కాంటెక్ట్స్ ప్రోటోకాల్ స్ట్డియో ట్రాన్స్‌పోర్ట్ తో | `SimpleMcpTest.java` | -## పరీక్షలు ఎలా నడపాలి +## పరీక్షలను నడిపించడం **రూట్ నుండి అన్ని పరీక్షలను నడపండి:** -**బాష్:** +**Bash:** ```bash mvn test ``` -**పవర్‌షెల్:** +**PowerShell:** ```powershell mvn --% test ``` **ఒక నిర్దిష్ట మాడ్యూల్ కోసం పరీక్షలు నడపండి:** -**బాష్:** +**Bash:** ```bash cd 01-introduction && mvn test # లేదా రూట్ నుండి mvn test -pl 01-introduction ``` -**పవర్‌షెల్:** +**PowerShell:** ```powershell cd 01-introduction; mvn --% test # లేదా రూట్ నుండి mvn --% test -pl 01-introduction ``` -**ఒకటే పరీక్ష తరగతిని నడపండి:** +**ఒకే టెస్ట్ క్లాస్ నడపండి:** -**బాష్:** +**Bash:** ```bash mvn test -Dtest=SimpleConversationTest ``` -**పవర్‌షెల్:** +**PowerShell:** ```powershell mvn --% test -Dtest=SimpleConversationTest ``` -**ఒక నిర్దిష్ట పరీక్ష పద్ధతిని నడపండి:** +**ఒక నిర్దిష్ట టెస్ట్ పద్ధతిని నడపండి:** -**బాష్:** +**Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#సంభాషణ చరిత్రను నిర్వహించాలి +mvn test -Dtest=SimpleConversationTest#సంభాషణ చరిత్రని నిర్వహించాలి ``` -**పవర్‌షెల్:** +**PowerShell:** ```powershell mvn --% test -Dtest=SimpleConversationTest#సంభాషణ చరిత్రను నిర్వహించాలి ``` -## VS కోడ్‌లో పరీక్షలు నడపడం +## VS కోడ్‌లో పరీక్షలు నడిపించడం -మీరు Visual Studio Code వాడుతున్నట్లయితే, Test Explorer పరీక్షలను నడపడానికి మరియు డీబగ్ చేసేందుకు గ్రాఫికల్ ఇంటర్‌ఫేస్ అందిస్తుంది. +మీరు Visual Studio Code ఉపయోగిస్తుంటే, Test Explorer ద్వారా పరీక్షలను నడపడం మరియు డీబగ్ చేయడానికి గ్రాఫికల్ ఇంటర్‌ఫేస్ ఉంటుంది. VS Code Test Explorer -*VS కోడ్ టెస్ట్ ఎక్స్ప్లోరర్ అన్ని జావా పరీక్ష తరగతులు మరియు వ్యక్తిగత పరీక్ష పద్ధతులతో కూడిన పరీక్ష డెండర్ చూపిస్తోంది* +*VS కోడ్ టెస్ట్ ఎక్స్‌ప్లోర్ లో అన్ని జావా టెస్ట్ క్లాసులు మరియు వ్యక్తిగత పరీక్షా పద్ధతులు చూపిస్తున్న టెస్ట్ ట్రి* -**VS కోడ్‌లో పరీక్షలు నడపడానికి:** +**VS కోడ్‌లో పరీక్షలు నడిపెందుకు:** -1. Activity Barలోని బీకర్ ఐకాన్‌పై క్లిక్ చేసి Test Explorer తెరవండి -2. అన్ని మాడ్యూల్స్ మరియు పరీక్ష తరగతులు చూసేందుకు పరీక్ష చెట్లను విస్తరించండి -3. ఏదైనా పరీక్ష పక్కన ఉన్న ప్లే బటనును క్లిక్ చేసి ఆ పరీక్షను వేరుగా నడపండి -4. మొత్తం సూట్ నడప "Run All Tests" క్లిక్ చేయండి -5. ఏదైనా పరీక్ష‌పై రైట్-క్లిక్ చేసి "Debug Test" ఎంచుకొని బ్రేక్ఫ్ పాయింట్లు పెడుతూ కోడ్ లో దశలవారీగా వెళ్లండి +1. Activity బార్ లో బీకర్ చిహ్నం క్లిక్ చేసి Test Explorer తెరువండి +2. అన్ని మాడ్యూల్స్ మరియు పరీక్షా క్లాసులు చూడటానికి టెస్ట్ ట్రి విస్తరించండి +3. ఏ పరీక్ష పక్కన ఉన్న ప్లే బటన్ క్లిక్ చేసి అది వ్యక్తిగతంగా నడపండి +4. "Run All Tests" క్లిక్ చేసి మొత్తం సూట్ అమలు చేయండి +5. ఏ పరీక్ష పైన రైట్-క్లిక్ చేసి "Debug Test" ఎంచుకుని బ్రేక్‌పాయింట్లు పెట్టి కోడ్ లో అడుగు అడుగు నడపండి -పరీక్షలు విజయవంతం అయితే గ్రీన్ చెక్మార్క్ కనిపిస్తుంది మరియు విఫలాలైనా వివరమైన సందేశాలు చూపిస్తుంది. +పరీక్షలు విజయవంతంగా నడిచేటప్పుడు గ్రీన్ చెక్మార్కులు చూపిస్తుంది, మరియు మరింత వివరణాత్మక వైఫల్య సందేశాలు ఇస్తుంది. -## పరీక్షా నమూనాలు +## పరీక్షించే నమూనాలు -### నమూనా 1: ప్రాంప్ట్ టెంప్లేట్లను పరీక్షించడం +### నమూనా 1: ప్రాంప్ట్ టెంప్లేట్ పరీక్ష -అతి సరళమైన నమూనా AI మోడల్‌ను కాల్ చేయకుండా ప్రాంప్ట్ టెంప్లేట్లను పరీక్షిస్తుంది. వేరియబుల్ ప్రత్యామ్నాయం సరిగ్గా పనిచేస్తుందో మరియు ప్రాంప్ట్‌లు ఆశించినట్లుగా ఫార్మాట్ అయ్యాయో సరిచూడవచ్చు. +సులభమైన నమూనా AI మోడల్ ను కాల్ చేయకుండా ప్రాంప్ట్ టెంప్లేట్ లను పరీక్షిస్తుంది. వేరియబుల్ సబ్‌స్టిట్యూషన్ సరిగా పనిచేస్తుందో, ప్రాంప్ట్‌లు సరైన ఫార్మాట్లో ఉన్నాయో మీరు ధృవీకరించాలి. Prompt Template Testing -*వేరియబుల్ ప్రత్యామ్నాయం ప్రవాహం చూపిస్తూ ప్రాంప్ట్ టెంప్లేట్లను పరీక్షించడం: ప్లేస్‌హోల్డర్లతో టెంప్లేట్ → విలువలు వర్తింపజేయబడటం → ఫార్మాటెడ్ అవుట్‌పుట్ నిర్ధారణ* +*ప్రాంప్ట్ టెంప్లేట్ పరీక్షలో వేరియబుల్ సబ్‌స్టిట్యూషన్ ఫ్లో చూపించడం: ప్లేస్‌హోల్డర్లు ఉన్న టెంప్లేట్ → విలువలు అప్లై చేయబడ్డాయి → ఫార్మాటెడ్ అవుట్‌పుట్ ధృవీకరించబడింది* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -ఈ పరీక్ష `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` లో ఉంది. +ఈ నమూనా వేరియబుల్ సబ్‌స్టిట్యూషన్ సరిగా పనిచేస్తుందో, ప్రాంప్ట్‌లు అంచనా వేసిన విధంగా ఫార్మాట్ అయ్యాయో ధృవీకరిస్తుంది — API కీ లేదా మోడల్ కాల్ అవసరం లేదు. -**దాన్ని నడపండి:** +### నమూనా 2: భాషా మోడల్స్ మాక్ చేయడం -**బాష్:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#టెస్ట్ ప్రాంప్ట్ టెంప్లేట్ ఫార్మాటింగ్ -``` - -**పవర్‌షెల్:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#పరీక్షప్రాంప్ట్ టెంప్లేట్ ఫార్మాటింగ్ -``` - -### నమూనా 2: భాషా మోడల్స్‌ను మాక్ చేయడం - -సంభాషణ తర్కాన్ని పరీక్షించేటప్పుడు Mockito ఉపయోగించి ముందుగా నిర్ణయించిన ప్రత్యుత్తరాలను అందించే నకిలీ మోడల్స్ సృష్టించండి. ఇది పరీక్షలను తక్షణ, ఉచిత మరియు నిర్ణీతం చేస్తుంది. +సంభాషణ లాజిక్ ను పరీక్షించేటప్పుడు, Mockito ఉపయోగించి ముందుగా నిర్ధారిత ప్రతిస్పందనలు ఇచ్చే మాక్ మోడల్స్ సృష్టించండి. ఇది పరీక్షలను వేగవంతంగా, ఉచితంగా, నిర్ణయాత్మకంగా చేస్తుంది. Mock vs Real API Comparison -*మాక్‌లు ఎందుకు వాస్తవ API కంటే సూచించే టెస్టింగ్ కష్టత తక్కువవో చూపే పోలిక: అవి త్వరితమైనవి, ఉచితమైనవి, నిర్ణీతమైనవి మరియు API కీలు అవసరం కాదు* +*పరీక్షలకు మాక్స్ ఎందుకు ప్రాధాన్యం ఇవ్వబడతాయో చూపిస్తూ తులనాత్మక చిత్రం: అవి వేగవంతం, ఉచితం, నిర్ణయాత్మకం మరియు API కీలు అవసరం లేవు* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 వినియోగదారుడు + 3 AI సందేశాలు + assertThat(history).hasSize(6); // 3 వినియోగదారులు + 3 AI సందేశాలు } } ``` -ఈ నమూనా `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` లో ఉంది. మాక్ స్థిరమైన ప్రవర్తనను నిర్ధారిస్తుంది కాబట్టి జ్ఞాపకం నిర్వహణ సరిగ్గా పనిచేస్తుందో మీరు ధృవీకరించవచ్చు. +ఈ నమూనా `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` లో కనిపిస్తుంది. మాక్ అనువర్తన యథార్థ ప్రవర్తనను నిర్ధారించేందుకు, మీరు మెమరీ నిర్వహణ సరిగ్గా పనిచేస్తుందో నిర్ధారించవచ్చు. -### నమూనా 3: సంభాషణ వేరుచేయడం పరీక్షించడం +### నమూనా 3: సంభాషణ విభజనను పరీక్షించడం -సంభాషణ జ్ఞాపకం పలు వినియోగదారులను వేరుగా ఉంచాలి. ఈ పరీక్ష సంభాషణలు కాన్టెక్స్ట్ మిశ్రమం చేయకుండా వేరుగా ఉన్నాయో ధృవీకరిస్తుంది. +సంభాషణ స్మృతి బహుళ వినియోగదారులను వేరుగా ఉంచాలి. ఈ పరీక్ష సంభాషణలు ఒకరి కాంటెక్స్ట్ ను మరొకరి తో కలపకుండా ఉంటాయో నిర్ధారిస్తుంది. Conversation Isolation -*పారిశ్రామిక జ్ఞాపక నిల్వలను వేరుగా ఉంచి కాన్టెక్స్ట్ మిక్సింగ్ నివారిస్తున్నట్లు చూపిస్తూ సంభాషణ వేరుచేత పలుకుల పరీక్ష* +*వివిధ వినియోగదారుల కోసం వేరుగా మెమరీ స్టోర్స్ ఉంచడం ద్వారా సంభాషణ విభజన పరీక్ష* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -ప్రతి సంభాషణకు స్వతంత్ర చరిత్ర ఉంటుంది. ఉత్పత్తి వ్యవస్థల్లో, ఈ వేరుచేత బహువినియోగదారు అనువర్తనాలకు అత్యంత అవసరం. +ప్రతి సంభాషణ తన స్వంత స్వతంత్ర చరిత్రను నిర్వహిస్తుంది. ఉత్పత్తి వ్యవస్థలలో, ఈ విభజన బహుళ వినియోగదారుల అప్లికేషన్ల కోసం అత్యంత ముఖ్యమైనది. ### నమూనా 4: టూల్స్‌ను స్వతంత్రంగా పరీక్షించడం -టూల్స్ అనేవి AI కాల్ చేయగల ఫంక్షన్లు. అవి AI నిర్ణయాలకు సలవుచూంతున్నా సరే సరిగ్గా పనిచేస్తున్నాయో ప్రత్యక్షంగా పరీక్షించండి. +టూల్స్ అంటే AI పిలవగల ఫంక్షన్లు. AI నిర్ణయాలపై ఆధారపడకుండా వాటి పనితీరును నేరుగా పరీక్షించండి. Tools Testing -*AI కాల్స్ లేకుండా మాక్ టూల్ అమలు చూపిస్తూ వ్యాపార తర్కాన్ని ధృవీకరించే టూల్స్‌ను స్వతంత్రంగా పరీక్షించడం* +*ఏ AI కాల్‌లూ లేకుండా టూల్‌లను మాక్ రీతిలో నడపడం ద్వారా వ్యాపార లాజిక్ సరిచూసే పరీక్షలు* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -ఈ పరీక్షలు `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` నుంచి ఉన్నాయి. AI భాగస్వామ్యం లేకుండా టూల్ తర్కాన్ని ధృవీకరిస్తాయి. చైనింగ్ ఉదాహరణ ఒక టూల్ అవుట్‌పుట్ మరొకదాని ఇన్‌పుట్‌గా ఎలా పనిచేస్తుందో చూపిస్తుంది. +`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` లోని ఈ పరీక్షలు AI పాల్గొనకుండా టూల్ వ్యాపార లాజిక్ ని ధృవీకరిస్తాయి. చైనింగ్ ఉదాహరణలో ఒక టూల్ అవుట్‌పుట్ మరొక టూల్ ఇన్‌పుట్‌గా ఎలా పనిచేస్తుందో చూపిస్తుంది. ### నమూనా 5: ఇన్-మెమరీ RAG పరీక్ష -RAG వ్యవస్థలకు సాధారణంగా వెక్టార్ డేటాబేసులు మరియు ఎంబెడ్డింగ్ సర్వీసులు అవసరం. ఇన్-మెమరీ నమూనా మొత్తం పైప్లైన్ ను బాహ్య ఆధారిత సదుపాయాలు లేకుండానే పరీక్షించగలుగుతుంది. +ప్రపంచంలో RAG системы వెక్టార్ డేటాబేసులు మరియు ఎంబెడ్డింగ్ సర్వీసులతో పనిచేస్తాయి. ఇన్-మెమరీ నమూనా మీకు పూర్తిగా పైప్‌లైన్‌ను బాహ్య ఆధారాలుండకుండా పరీక్షించే అవకాశం ఇస్తుంది. In-Memory RAG Testing -*డాక్యుమెంట్ పార్సింగ్, ఎంబెడ్డింగ్ నిల్వ, సమానత్వ శోధనను డేటాబేస్ అవసరం లేకుండా చూపించే ఇన్-మెమరీ RAG పరీక్షా తరలింపు* +*డాక్యుమెంట్ పార్సింగ్, ఎంబెడ్డింగ్ నిల్వ, సారూప్యత శోధన డేటాబేస్ అవసరం లేకుండా ఇన్-మెమరీ RAG పరీక్షా వర్క్‌ఫ్లో* ```java @Test @@ -306,58 +293,57 @@ void testProcessTextDocument() { } ``` -ఈ పరీక్ష `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` నుండి ఉంది. ఇన్-మెమరీలో డాక్యుమెంట్ సృష్టించి చంకింగ్ మరియు మెటాడేటా నిర్వహణను ధృవీకరిస్తుంది. +ఈ పరీక్ష `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` నుండి, ఒక డాక్యుమెంట్ ని మెమరీలో సృష్టించి, చంకింగ్ మరియు మెటాడేటా నిర్వహణని ధృవీకరిస్తుంది. -### నమూనా 6: MCP ఇంటిగ్రేషన్ పరీక్ష +### నమూనా 6: MCP ఇంటిగ్రేషన్ పరీక్షలు -MCP మాడ్యూల్ stdio ట్రాన్స్పోర్ట్ ఉపయోగించి మోడల్ కాంటెక్స్ట్ ప్రోటోకాల్ ఇంటిగ్రేషన్‌ని పరీక్షిస్తుంది. ఈ పరీక్షలు మీ అనువర్తనం MCP సర్వర్లను ఉపప్రక్రియలుగా స్పాన్ చేసి కమ్యూనికేట్ చేయగలదని ధృవీకరిస్తాయి. +MCP మాడ్యూల్ స్ట్డియో ట్రాన్స్‌పోర్ట్ ఉపయోగించి Model Context Protocol ఇంటిగ్రేషన్‌ని పరీక్షిస్తుంది. ఈ పరీక్షలు మీ అప్లికేషన్ MCP సర్వర్లను సబ్ప్రాసెస్‌లుగా మొదలెடுத்து సంభాషించగలదని నిర్ధారిస్తాయి. -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` లోని పరీక్షలు MCP క్లీంట్ ప్రవర్తనను ధృవీకరిస్తాయి. +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` లో పరీక్షలు MCP క్లయింట్ ప్రవర్తనను ధృవీకరిస్తాయి. -**దాన్ని నడిపించండి:** +**వాటిని నడపండి:** -**బాష్:** +**Bash:** ```bash cd 05-mcp && mvn test ``` -**పవర్‌షెల్:** +**PowerShell:** ```powershell cd 05-mcp; mvn --% test ``` -## పరీక్షా తత్వశాస్త్రం +## పరీక్షల తత్త్వం -AIని కాదు, మీ కోడ్‌ను పరీక్షించండి. మీ పరీక్షలు మీరు రాసే కోడ్ ఎలా పనిచేస్తుందో ధృవీకరించాలి: ప్రాంప్ట్‌లు ఎలా నిర్మించబడ్డాయో, జ్ఞాపకం ఎలా నిర్వహించబడుతున్నదో, టూల్స్ ఎలా అమలవుతున్నాయో చూసుకోండి. AI స్పందనలు మారవచ్చు మరియు పరీక్షా ధృవీకరణలో భాగం కాకూడదు. మీ ప్రాంప్ట్ టెంప్లేట్ సరిగ్గా వేరియబుల్స్ ప్రత్యామ్నాయం చేస్తున్నదా అనే విషయాన్ని చూసుకోండి, AI సరైన జవాబు ఇస్తుందా కాదా కాదు. +మీ కోడ్ ను పరీక్షించండి, AIని కాదు. మీరు రాసిన కోడ్ ని ప్రాంప్ట్‌లు ఎలా నిర్మించబడతాయో, మెమరీ ఎలా నిర్వహించబడుతుందో, మరియు టూల్స్ ఎలా నిర్వర్తించబడతాయో పరీక్షల ద్వారా ధృవీకరించాలి. AI సమాధానాలు వేర్వేరు ఉంటాయి కనుక అవి పరీక్షల నిర్ధారణలో భాగంగా ఉండకూడదు. మీరు మీ ప్రాంప్ట్ టెంప్లేట్ లో వేరియబుల్స్ సరిగా సబ్‌స్టిట్యూట్ అవుతున్నాయో చూసుకోండి, AI సరైన సమాధానం ఇస్తుందా అని కాదు. -భాషా మోడల్స్ కోసం మాక్‌లను వాడండి. అవి బాహ్య ఆధారాలు, ఆలస్యంగా ఉంటాయి, ఖరీదైనవి, మరియు నిర్ణీతం కాలేవి. మాక్ వాడటం వలన పరీక్షలు సెకన్లతో కాక, మిల్లీసెకన్లలో వేగంగా, ఉచితంగా API ఖర్చులు లేకుండా, మరియు ప్రతిసారి ఒకటే ఫలితంతో ఉంటాయి. +భాషా మోడల్స్ కోసం మాక్స్ ఉపయోగించండి. అవి బయట ఆధారపడే వనరులు, అవి నెమ్మదిగా, ఖరీదైనవిగా మరియు నిర్ణయాత్మకం కానివి. మాకింగ్ వల్ల పరీక్షలు కొన్ని సెకన్ల కాకుండా మిల్లీసెకండ్లలో వేగంగా, ఉచితంగా, నిర్ణయాత్మకంగా నడుస్తాయి. -పరీక్షలను స్వతంత్రంగా ఉంచండి. ప్రతి పరీక్ష తన డేటాను సెట్ చేసుకోవాలి, ఇతర పరీక్షలపై ఆధారపడి ఉండకూడదు, మరియు స్వయంగా శుభ్రపరచుకోవాలి. పరీక్షలు ఎటువంటి అమలులోనైనా విజయవంతం కావాలి. +పరీక్షలను స్వతంత్రంగా ఉంచండి. ప్రతీ పరీక్ష తన దత్తాంశాన్ని సెట్ చేయాలి, ఇతర పరీక్షలపై ఆధారపడకూడదు, మరియు తన తరువాత శుభ్రపరుచుకోవాలి. పరీక్షల అమలు క్రమం ఎంత అయినా అవి విజయవంతంగా ఉండాలి. -సంతృప్తికర మార్గం కంటే ఎక్కువ ఎడ్జ్ కేసులను పరీక్షించండి. ఖాళీ ఇన్‌పుట్లు, చాలా పెద్ద ఇన్‌పుట్లు, ప్రత్యేక అక్షరాలు, చెల్లని పారామీటర్లు, మరియు సరిహద్దు పరిస్థితులు ప్రయత్నించండి. ఇవి సాధారణ ఉపయోగం బయట బగ్స్‌ను బయటపెడతాయి. +సంతోషకర మార్గం మించి అడ్డంకులను పరీక్షించండి. ఖాళీ ఇన్‌పుట్లు, చాలా పెద్ద ఇన్‌పుట్లు, ప్రత్యేక అక్షరాలు, చెలామణీలో లేని పారామీటర్లు, సరిహద్దు పరిస్థితులు ప్రయత్నించండి. సాధారణ వినియోగంలో కనిపించని బగ్స్ ఇవే విపరీతంగా బయటపెడతాయి. -వర్ణనాత్మక పేర్లను వాడండి. `shouldMaintainConversationHistoryAcrossMultipleMessages()` తో `test1()`ని పోల్చండి. మొదటి పేరుతో మీరు ఏమి పరీక్షిస్తున్నారో ఖచ్చితంగా తెలుస్తుంది, డీబగ్గింగ్ బాధలను సులభతరం చేస్తుంది. +వివరణాత్మక పేర్లు ఉపయోగించండి. `shouldMaintainConversationHistoryAcrossMultipleMessages()` ను `test1()`తో పోల్చండి. మొదటి పేరు తేలికగా ఏమి పరీక్షిస్తున్నారో చెబుతుంది, ఎటువంటి లోపాలు వస్తే డీబగ్ చేయడం చాలా సులభం అవుతుంది. -## తర్వాతి దశలు +## తదుపరి దశలు -ఇప్పుడు మీరు పరీక్షా నమూనాలు అర్థం చేసుకున్నందున, ప్రతి మాడ్యూల్ లో మరింత లోతుగా ప్రవేశించండి: +మీకు పరీక్షించే నమూనాలు అర్థమయ్యాయి కాబట్టి, ప్రతి మాడ్యూల్ లో మరింత లోతుగా కుందాం: -- **[00 - త్వరిత ప్రారంభం](../00-quick-start/README.md)** - ప్రాంప్ట్ టెంప్లేట్ మౌలికాలు నేర్చుకోండి -- **[01 - పరిచయం](../01-introduction/README.md)** - సంభాషణ జ్ఞాపక నిర్వహణ తెలుసుకోండి -- **[02 - ప్రాంప్ట్ ఇంజనీరింగ్](../02-prompt-engineering/README.md)** - GPT-5.2 ప్రాంప్ట్ నమూనాలు మాస్టరు అవ్వండి -- **[03 - RAG](../03-rag/README.md)** - రిట్రీవల్-ఆగ్మెంటెడ్ జనరేషన్ సిస్టమ్స్ నిర్మించండి -- **[04 - టూల్స్](../04-tools/README.md)** - ఫంక్షన్ కాలింగ్ మరియు టూల్ చైన్స్ అమలు చేయండి -- **[05 - MCP](../05-mcp/README.md)** - మోడల్ కాంటెక్స్ట్ ప్రోటోకాల్ ఇంటిగ్రేట్ చేయండి +- **[01 - పరిచయం](../01-introduction/README.md)** - సంభాషణ స్మృతి నిర్వహణ నేర్చుకోండి +- **[02 - ప్రాంప్ట్ ఇంజినీరింగ్](../02/prompt-engineering/README.md)** - GPT-5.2 ప్రాంప్ట్ నమూనాలు పటిష్టం చేయండి +- **[03 - RAG](../03-rag/README.md)** - రిట్రీవల్-ఆగ్మెంటెడ్ జనరేషన్ సిస్టమ్లను నిర్మించండి +- **[04 - టూల్స్](../04-tools/README.md)** - ఫంక్షన్ కాలింగ్ మరియు టూల్ చైలింగ్ అమలు చేయండి +- **[05 - MCP](../05-mcp/README.md)** - మోడల్ కాంటెక్ట్స్ ప్రోటోకాల్ ఇంటిగ్రేట్ చేయండి -ప్రతి మాడ్యూల్ README ఇక్కడ పరీక్షించిన భావনার వివరణలను అందిస్తుంది. +ప్రతి మాడ్యూల్ యొక్క README ఇక్కడ పరీక్షించబడిన సూత్రాల వివరమైన వివరణ ఇస్తుంది. --- -**నావిగేషన్:** [← ప్రధానానికి తిరిగి](../README.md) +**నావిగేషన్:** [← తిరిగి మెయిన్ కు](../README.md) --- -**నిరాకరణ**: -ఈ డాక్యుమెంట్‌ను AI అనువాద සේవ అయిన [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వాన్ని లక్ష్యంగా పెట్టుకున్నప్పటికీ, స్వయంచాలక అనువాదాల్లో లోపాలు లేదా తప్పు సమాచారాలు ఉండవచ్చు అని దయచేసి గమనించండి. ఈ డాక్యుమెంట్ యొక్క అసలు మూల భాషలోనిది అధికారిక వనరు అని పరిగణించాలి. ముఖ్యమైన సమాచారం కోసం, వృత్తిపరమైన మానవ అనువాదాన్ని ఉచితం. ఈ అనువాదం వలన కలిగే ఏవైనా అవగాహన లోపాలు లేదా తప్పు అర్థం చేసుకోవడంపై మేము బాధ్యత వహించమేము. +**అస్వీకరణ**: +ఈ పత్రం AI అనువాద సేవ [Co-op Translator](https://github.com/Azure/co-op-translator) ఉపయోగించి అనువదించబడింది. మేము ఖచ్చితత్వానికి ప్రయత్నిస్తున్నప్పటికీ, ఆటోమేటెడ్ అనువాదాలు తప్పులు లేదా అసమగ్రతలను కలిగి ఉండవచ్చు. దాని స్వదేశ భాషలో ఉన్న అసలు పత్రాన్ని అధికారం కలిగిన మూలంగా పరిగణించాలి. కీలకమైన సమాచారం కోసం, ప్రొఫెషనల్ మానవ అనువాదాన్ని సిఫారసు చేస్తాము. ఈ అనువాదం ఉపయోగం వల్ల కలిగే ఏవైనా అపార్థాలు లేదా తప్పుదారులు కోసం మేము బాధ్యత వహించము. \ No newline at end of file diff --git a/translations/th/.co-op-translator.json b/translations/th/.co-op-translator.json index a8b5bd08f..eea88a9f7 100644 --- a/translations/th/.co-op-translator.json +++ b/translations/th/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "th" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T00:47:35+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T09:55:51+00:00", "source_file": "01-introduction/README.md", "language_code": "th" }, @@ -18,20 +18,20 @@ "language_code": "th" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T00:50:22+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T09:51:17+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "th" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T00:51:51+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T09:54:58+00:00", "source_file": "03-rag/README.md", "language_code": "th" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:30:52+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T09:53:40+00:00", "source_file": "04-tools/README.md", "language_code": "th" }, @@ -54,8 +54,8 @@ "language_code": "th" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:08:38+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T09:49:58+00:00", "source_file": "README.md", "language_code": "th" }, @@ -72,14 +72,14 @@ "language_code": "th" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T00:55:21+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T09:51:45+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "th" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T00:56:06+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T09:52:23+00:00", "source_file": "docs/TESTING.md", "language_code": "th" } diff --git a/translations/th/00-quick-start/README.md b/translations/th/00-quick-start/README.md deleted file mode 100644 index c6fe44121..000000000 --- a/translations/th/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: เริ่มต้นอย่างรวดเร็ว - -## สารบัญ - -- [บทนำ](../../../00-quick-start) -- [LangChain4j คืออะไร?](../../../00-quick-start) -- [การพึ่งพาของ LangChain4j](../../../00-quick-start) -- [ข้อกำหนดเบื้องต้น](../../../00-quick-start) -- [การตั้งค่า](../../../00-quick-start) - - [1. รับโทเค็น GitHub ของคุณ](../../../00-quick-start) - - [2. ตั้งค่าโทเค็นของคุณ](../../../00-quick-start) -- [รันตัวอย่าง](../../../00-quick-start) - - [1. แชทพื้นฐาน](../../../00-quick-start) - - [2. รูปแบบพรอมต์](../../../00-quick-start) - - [3. การเรียกฟังก์ชัน](../../../00-quick-start) - - [4. ถามตอบเอกสาร (Easy RAG)](../../../00-quick-start) - - [5. AI ที่รับผิดชอบ](../../../00-quick-start) -- [แต่ละตัวอย่างแสดงอะไรบ้าง](../../../00-quick-start) -- [ขั้นตอนถัดไป](../../../00-quick-start) -- [การแก้ไขปัญหา](../../../00-quick-start) - -## บทนำ - -การเริ่มต้นอย่างรวดเร็วนี้มีไว้เพื่อให้คุณสามารถเริ่มใช้ LangChain4j ได้เร็วที่สุดเท่าที่จะเป็นไปได้ ครอบคลุมพื้นฐานทั้งหมดของการสร้างแอปพลิเคชัน AI ด้วย LangChain4j และ GitHub Models ในโมดูลถัดไปคุณจะเปลี่ยนไปใช้ Azure OpenAI และ GPT-5.2 และเจาะลึกในแต่ละแนวคิด - -## LangChain4j คืออะไร? - -LangChain4j เป็นไลบรารี Java ที่ทำให้การสร้างแอปพลิเคชันที่ใช้ AI ง่ายขึ้น แทนที่จะต้องจัดการกับ HTTP clients และการแยก JSON คุณจะทำงานกับ API ของ Java ที่สะอาด - -"chain" ใน LangChain หมายถึงการเชื่อมต่อองค์ประกอบหลายๆ ตัวเข้าด้วยกัน — คุณอาจเชื่อมต่อพรอมต์กับโมเดลกับตัวแยกวิเคราะห์ หรือเชื่อมต่อการเรียก AI หลายตัวเข้าด้วยกันที่ผลลัพธ์หนึ่งจะเป็นอินพุตสำหรับตัวถัดไป การเริ่มต้นอย่างรวดเร็วนี้เน้นพื้นฐานก่อนที่จะสำรวจเชนที่ซับซ้อนมากขึ้น - -แนวคิดการเชื่อมต่อ LangChain4j - -*การเชื่อมต่อองค์ประกอบใน LangChain4j - บล็อกที่เชื่อมต่อเพื่อสร้างเวิร์กโฟลว์ AI ที่ทรงพลัง* - -เราจะใช้สามองค์ประกอบหลัก: - -**ChatModel** - อินเทอร์เฟซสำหรับโต้ตอบกับโมเดล AI เรียก `model.chat("prompt")` และรับสตริงตอบกลับ เราใช้ `OpenAiOfficialChatModel` ซึ่งทำงานกับ endpoints ที่เข้ากันได้กับ OpenAI เช่น GitHub Models - -**AiServices** - สร้างอินเทอร์เฟซบริการ AI ที่ปลอดภัยตามชนิด กำหนดเมธอด ติดเครื่องหมายด้วย `@Tool` และ LangChain4j จะจัดการการประสานงาน AI จะเรียกใช้เมธอด Java ของคุณโดยอัตโนมัติเมื่อจำเป็น - -**MessageWindowChatMemory** - รักษาประวัติการสนทนา ถ้าไม่มีสิ่งนี้แต่ละคำขอจะเป็นอิสระ แต่ถ้ามี AI จะจำข้อความก่อนหน้าและรักษาบริบทในหลายๆ รอบ - -สถาปัตยกรรม LangChain4j - -*สถาปัตยกรรม LangChain4j - องค์ประกอบหลักที่ทำงานร่วมกันเพื่อขับเคลื่อนแอป AI ของคุณ* - -## การพึ่งพาของ LangChain4j - -การเริ่มต้นอย่างรวดเร็วนี้ใช้การพึ่งพา Maven สามตัวใน [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -โมดูล `langchain4j-open-ai-official` ให้คลาส `OpenAiOfficialChatModel` ที่เชื่อมต่อกับ API ที่เข้ากันได้กับ OpenAI GitHub Models ใช้รูปแบบ API เดียวกัน จึงไม่ต้องมีอะแดปเตอร์พิเศษ — เพียงตั้งค่า URL พื้นฐานไปที่ `https://models.github.ai/inference` - -โมดูล `langchain4j-easy-rag` ให้การแยกเอกสาร การฝังตัว และการเรียกคืนอัตโนมัติ เพื่อให้คุณสร้างแอป RAG ได้โดยไม่ต้องตั้งค่าทีละขั้นตอนเอง - -## ข้อกำหนดเบื้องต้น - -**ใช้ Dev Container?** Java และ Maven ติดตั้งพร้อมใช้งานแล้ว คุณแค่ต้องมี GitHub Personal Access Token - -**การพัฒนาท้องถิ่น:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (คำแนะนำด้านล่าง) - -> **หมายเหตุ:** โมดูลนี้ใช้ `gpt-4.1-nano` จาก GitHub Models อย่าปรับชื่อโมเดลในโค้ด — โมเดลนี้ตั้งค่าให้ทำงานกับโมเดลที่ GitHub มีอยู่ได้แล้ว - -## การตั้งค่า - -### 1. รับโทเค็น GitHub ของคุณ - -1. ไปที่ [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. คลิก "Generate new token" -3. ตั้งชื่อที่อธิบายได้ (เช่น "LangChain4j Demo") -4. ตั้งวันหมดอายุ (แนะนำ 7 วัน) -5. ใน "Account permissions" ค้นหา "Models" และตั้งเป็น "Read-only" -6. คลิก "Generate token" -7. คัดลอกและบันทึกโทเค็นของคุณ — คุณจะไม่เห็นอีก - -### 2. ตั้งค่าโทเค็นของคุณ - -**ตัวเลือก 1: ใช้ VS Code (แนะนำ)** - -หากคุณใช้ VS Code ให้เพิ่มโทเค็นของคุณในไฟล์ `.env` ที่รูทโฟลเดอร์โปรเจค - -ถ้าไฟล์ `.env` ไม่มี ให้คัดลอก `.env.example` เป็น `.env` หรือสร้างไฟล์ `.env` ใหม่ในรูทโปรเจค - -**ตัวอย่างไฟล์ `.env`:** -```bash -# ใน /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -จากนั้นคุณสามารถคลิกขวาที่ไฟล์เดโมใดๆ (เช่น `BasicChatDemo.java`) ใน Explorer แล้วเลือก **"Run Java"** หรือใช้การตั้งค่า launch ผ่านแผง Run and Debug - -**ตัวเลือก 2: ใช้ Terminal** - -ตั้งค่าตัวแปรสภาพแวดล้อมสำหรับโทเค็น: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## รันตัวอย่าง - -**ใช้ VS Code:** คลิกขวาที่ไฟล์เดโมใน Explorer แล้วเลือก **"Run Java"** หรือใช้การตั้งค่า launch ผ่าน Run and Debug (ตรวจสอบให้แน่ใจว่าได้เพิ่มโทเค็นในไฟล์ `.env` แล้ว) - -**ใช้ Maven:** หรือรันจาก command line: - -### 1. แชทพื้นฐาน - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. รูปแบบพรอมต์ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -แสดง zero-shot, few-shot, chain-of-thought และ role-based prompting - -### 3. การเรียกฟังก์ชัน - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI จะเรียกใช้เมธอด Java ของคุณโดยอัตโนมัติเมื่อจำเป็น - -### 4. ถามตอบเอกสาร (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -ถามคำถามเกี่ยวกับเอกสารของคุณโดยใช้ Easy RAG ที่มีการฝังและเรียกคืนข้อมูลอัตโนมัติ - -### 5. AI ที่รับผิดชอบ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -ดูว่าฟิลเตอร์ความปลอดภัย AI บล็อกเนื้อหาที่เป็นอันตรายอย่างไร - -## แต่ละตัวอย่างแสดงอะไรบ้าง - -**แชทพื้นฐาน** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -เริ่มต้นที่นี่เพื่อดู LangChain4j ในแบบพื้นฐานที่สุด คุณจะสร้าง `OpenAiOfficialChatModel` ส่งพรอมต์ด้วย `.chat()` และรับคำตอบกลับ สิ่งนี้แสดงรากฐาน: วิธีเริ่มโมเดลด้วย endpoints และคีย์ API ที่กำหนดเอง เมื่อเข้าใจรูปแบบนี้ ทุกอย่างอื่นจะต่อยอดได้ - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 ลองใช้กับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) แล้วถาม: -> - "จะเปลี่ยนจาก GitHub Models เป็น Azure OpenAI ในโค้ดนี้ได้อย่างไร?" -> - "พารามิเตอร์ตัวไหนอีกที่สามารถตั้งค่าใน OpenAiOfficialChatModel.builder() ได้?" -> - "จะเพิ่มการสตรีมคำตอบแทนการรอคำตอบเต็มได้อย่างไร?" - -**การออกแบบพรอมต์ (Prompt Engineering)** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -เมื่อรู้วิธีคุยกับโมเดลแล้ว มาสำรวจสิ่งที่คุณพูดกัน เดโมนี้ใช้การตั้งค่าโมเดลเดียวกันแต่แสดงรูปแบบพรอมต์ 5 แบบ ลอง zero-shot สำหรับคำสั่งตรงๆ, few-shot ที่เรียนรู้จากตัวอย่าง, chain-of-thought ที่เผยขั้นตอนตรรกะ และ role-based ที่ตั้งบริบท คุณจะเห็นว่าโมเดลเดียวกันให้ผลลัพธ์ต่างกันมากตามที่คุณจัดกรอบคำขอ - -เดโมนี้ยังสาธิต prompt templates วิธีสร้างพรอมต์ซ้ำได้ด้วยตัวแปร -ตัวอย่างด้านล่างแสดงพรอมต์โดยใช้ LangChain4j `PromptTemplate` เพื่อเติมตัวแปร AI จะตอบตามปลายทางและกิจกรรมที่ให้มา - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 ลองใช้กับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) แล้วถาม: -> - "ความแตกต่างระหว่าง zero-shot กับ few-shot prompting คืออะไร และควรใช้เมื่อไร?" -> - "พารามิเตอร์ temperature มีผลกับคำตอบของโมเดลอย่างไร?" -> - "เทคนิคใดบ้างที่ช่วยป้องกัน prompt injection ในการใช้งานจริง?" -> - "จะสร้าง PromptTemplate ที่ใช้ซ้ำได้สำหรับรูปแบบทั่วไปอย่างไร?" - -**การรวมเครื่องมือ (Tool Integration)** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -นี่คือจุดที่ LangChain4j แข็งแกร่ง คุณจะใช้ `AiServices` สร้างผู้ช่วย AI ที่เรียกใช้เมธอด Java ได้ แค่ติดเครื่องหมายเมธอดด้วย `@Tool("description")` และ LangChain4j จัดการส่วนที่เหลือ — AI ตัดสินใจเองเมื่อเลือกใช้เครื่องมือใดตามที่ผู้ใช้ถาม นี่แสดงการเรียกฟังก์ชัน เทคนิคสำคัญสำหรับสร้าง AI ที่ทำงานได้ ไม่ใช่แค่ตอบคำถาม - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 ลองใช้กับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) แล้วถาม: -> - "@Tool annotation ทำงานอย่างไร และ LangChain4j ทำอะไรกับมันเบื้องหลัง?" -> - "AI จะเรียกใช้เครื่องมือหลายตัวเรียงกันเพื่อแก้ปัญหาซับซ้อนได้ไหม?" -> - "ถ้าเครื่องมือเกิดข้อผิดพลาดควรจัดการอย่างไร?" -> - "จะผสานรวม API จริงแทนตัวอย่างเครื่องคิดเลขนี้ได้อย่างไร?" - -**ถามตอบเอกสาร (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -ที่นี่คุณจะเห็น RAG (retrieval-augmented generation) โดยใช้วิธี "Easy RAG" ของ LangChain4j เอกสารถูกโหลด แยกและฝังข้อมูลอัตโนมัติลงในที่เก็บข้อมูลในหน่วยความจำ แล้ว content retriever จะส่งชิ้นส่วนข้อมูลที่เกี่ยวข้องไปยัง AI ขณะถาม คำตอบมาจากเอกสารของคุณ ไม่ใช่ความรู้ทั่วไปของโมเดล - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 ลองใช้กับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) แล้วถาม: -> - "RAG ป้องกัน AI hallucination ต่างจากการใช้ข้อมูลเทรนโมเดลอย่างไร?" -> - "ความแตกต่างระหว่างวิธีง่ายนี้กับ pipeline RAG แบบกำหนดเองคืออะไร?" -> - "จะขยายระบบนี้ให้รองรับเอกสารหลายรายการหรือตัวฐานความรู้ที่ใหญ่ขึ้นได้อย่างไร?" - -**AI ที่รับผิดชอบ** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -สร้างความปลอดภัย AI ด้วยการป้องกันหลายชั้น เดโมนี้แสดงสองชั้นของการป้องกันที่ทำงานร่วมกัน: - -**ส่วนที่ 1: LangChain4j Input Guardrails** - บล็อกพรอมต์อันตรายก่อนถึง LLM สร้าง guardrails แบบกำหนดเองเพื่อตรวจจับคำหรือรูปแบบต้องห้าม รันในโค้ดคุณจึงรวดเร็วและฟรี - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**ส่วนที่ 2: Provider Safety Filters** - GitHub Models มีฟิลเตอร์ในตัวที่จับสิ่งที่ guardrails อาจพลาด คุณจะเห็นการบล็อกแบบรุนแรง (HTTP 400 errors) สำหรับการละเมิดที่รุนแรง และการปฏิเสธแบบอ่อนโยนที่ AI ปฏิเสธอย่างสุภาพ - -> **🤖 ลองใช้กับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) แล้วถาม: -> - "InputGuardrail คืออะไร และจะสร้างของตัวเองอย่างไร?" -> - "ความแตกต่างระหว่างการบล็อกแบบรุนแรงและการปฏิเสธแบบอ่อนโยนคืออะไร?" -> - "ทำไมจึงใช้ทั้ง guardrails และฟิลเตอร์ของ provider ร่วมกัน?" - -## ขั้นตอนถัดไป - -**โมดูลถัดไป:** [01-introduction - เริ่มต้นใช้งาน LangChain4j](../01-introduction/README.md) - ---- - -**นำทาง:** [← กลับสู่หน้าแรก](../README.md) | [ถัดไป: Module 01 - บทนำ →](../01-introduction/README.md) - ---- - -## การแก้ไขปัญหา - -### การสร้าง Maven ครั้งแรก - -**ปัญหา:** คำสั่ง `mvn clean compile` หรือ `mvn package` ครั้งแรกใช้เวลานาน (10-15 นาที) - -**สาเหตุ:** Maven ต้องดาวน์โหลดการพึ่งพาทั้งหมดของโปรเจค (Spring Boot, ไลบรารี LangChain4j, SDK ของ Azure ฯลฯ) ในการสร้างครั้งแรก - -**วิธีแก้:** นี่เป็นพฤติกรรมปกติ การสร้างในครั้งถัดไปจะเร็วขึ้นมากเนื่องจากการพึ่งพาถูกเก็บไว้ในเครื่อง เวลาดาวน์โหลดขึ้นกับความเร็วเน็ตเวิร์กของคุณ - -### ไวยากรณ์คำสั่ง Maven บน PowerShell - -**ปัญหา:** คำสั่ง Maven ล้มเหลวพร้อมข้อผิดพลาด `Unknown lifecycle phase ".mainClass=..."` -**สาเหตุ**: PowerShell แปลความหมาย `=` เป็นตัวดำเนินการกำหนดค่าตัวแปร ซึ่งทำให้ไวยากรณ์ของคุณสมบัติ Maven เสียหาย - -**วิธีแก้ไข**: ใช้ตัวดำเนินการหยุดการแยกวิเคราะห์ `--%` ก่อนคำสั่ง Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -ตัวดำเนินการ `--%` บอก PowerShell ให้ส่งอาร์กิวเมนต์ที่เหลือทั้งหมดไปยัง Maven ตามตัวอักษรโดยไม่ต้องแปลความหมาย - -### การแสดงอิโมจิใน Windows PowerShell - -**ปัญหา**: การตอบกลับของ AI แสดงเป็นตัวอักษรขยะ (เช่น `????` หรือ `â??`) แทนอิโมจิใน PowerShell - -**สาเหตุ**: การเข้ารหัสเริ่มต้นของ PowerShell ไม่รองรับอิโมจิแบบ UTF-8 - -**วิธีแก้ไข**: รันคำสั่งนี้ก่อนเรียกใช้แอปพลิเคชัน Java: -```cmd -chcp 65001 -``` - -สิ่งนี้บังคับให้ใช้การเข้ารหัสแบบ UTF-8 ในเทอร์มินัล หรืออีกทางเลือกหนึ่งคือใช้ Windows Terminal ซึ่งรองรับ Unicode ได้ดีกว่า - -### การดีบักการเรียก API - -**ปัญหา**: ข้อผิดพลาดการตรวจสอบสิทธิ์ ข้อจำกัดอัตราการใช้งาน หรือการตอบสนองที่ไม่คาดคิดจากโมเดล AI - -**วิธีแก้ไข**: ตัวอย่างรวมคำสั่ง `.logRequests(true)` และ `.logResponses(true)` เพื่อแสดงการเรียก API ในคอนโซล ช่วยให้ตรวจสอบข้อผิดพลาดการตรวจสอบสิทธิ์ ข้อจำกัดอัตราการใช้งาน หรือการตอบสนองที่ไม่คาดคิดได้ ลบแฟล็กเหล่านี้ในสภาพแวดล้อมผลิตเพื่อลดเสียงรบกวนจากบันทึกล็อก - ---- - - -**ข้อจำกัดความรับผิดชอบ**: -เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษาอัตโนมัติ [Co-op Translator](https://github.com/Azure/co-op-translator) ซึ่งแม้เราจะพยายามให้ความถูกต้องสูงสุด แต่โปรดทราบว่าการแปลอัตโนมัติอาจมีข้อผิดพลาดหรือความคลาดเคลื่อน เอกสารต้นฉบับในภาษาดั้งเดิมถือเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่มีความสำคัญ ขอแนะนำให้ใช้บริการแปลโดยผู้เชี่ยวชาญมืออาชีพ เราไม่มีความรับผิดชอบต่อความเข้าใจผิดหรือความคลาดเคลื่อนที่อาจเกิดขึ้นจากการใช้แปลนี้ - \ No newline at end of file diff --git a/translations/th/01-introduction/README.md b/translations/th/01-introduction/README.md index 219fc2735..b087d0595 100644 --- a/translations/th/01-introduction/README.md +++ b/translations/th/01-introduction/README.md @@ -1,85 +1,85 @@ # Module 01: เริ่มต้นใช้งาน LangChain4j -## สารบัญ - -- [วิดีโอสาธิต](../../../01-introduction) -- [สิ่งที่คุณจะได้เรียนรู้](../../../01-introduction) -- [ข้อกำหนดเบื้องต้น](../../../01-introduction) -- [เข้าใจปัญหาหลัก](../../../01-introduction) -- [ทำความเข้าใจเกี่ยวกับโทเค็น](../../../01-introduction) -- [วิธีการทำงานของหน่วยความจำ](../../../01-introduction) -- [วิธีที่ใช้ LangChain4j](../../../01-introduction) -- [ดีพลอยโครงสร้างพื้นฐาน Azure OpenAI](../../../01-introduction) -- [รันแอปพลิเคชันในเครื่อง](../../../01-introduction) -- [การใช้งานแอปพลิเคชัน](../../../01-introduction) - - [แชทแบบไม่มีสถานะ (แผงซ้าย)](../../../01-introduction) - - [แชทแบบมีสถานะ (แผงขวา)](../../../01-introduction) -- [ขั้นตอนถัดไป](../../../01-introduction) - -## วิดีโอสาธิต - -ชมเซสชันถ่ายทอดสดนี้ซึ่งอธิบายวิธีเริ่มต้นใช้งานโมดูลนี้: +##สารบัญ + +- [วิดีโอสอนใช้งาน](#สิ่งที่คุณจะได้เรียนรู้) +- [สิ่งที่คุณจะได้เรียนรู้](#ข้อกำหนดเบื้องต้น) +- [ข้อกำหนดเบื้องต้น](#ทำความเข้าใจปัญหาหลัก) +- [ทำความเข้าใจปัญหาหลัก](#ทำความเข้าใจโทเค็น) +- [ทำความเข้าใจโทเค็น](#หน่วยความจำทำงานอย่างไร) +- [หน่วยความจำทำงานอย่างไร](#วิธีที่ใช้-langchain4j-นี้) +- [วิธีที่ใช้ LangChain4j นี้](#ปรับใช้โครงสร้างพื้นฐาน-azure-openai) +- [ปรับใช้โครงสร้างพื้นฐาน Azure OpenAI](#รันแอปพลิเคชันท้องถิ่น) +- [รันแอปพลิเคชันท้องถิ่น](#การใช้แอปพลิเคชัน) +- [การใช้แอปพลิเคชัน](#แชทแบบไม่มีสถานะ-แผงซ้าย) + - [แชทแบบไม่มีสถานะ (แผงซ้าย)](#แชทแบบมีสถานะ-แผงขวา) + - [แชทแบบมีสถานะ (แผงขวา)](#ขั้นตอนถัดไป) +- [ขั้นตอนถัดไป](#next-steps) + +## วิดีโอสอนใช้งาน + +รับชมเซสชันสดนี้ซึ่งอธิบายวิธีเริ่มต้นใช้งานโมดูลนี้: Getting Started with LangChain4j - Live Session ## สิ่งที่คุณจะได้เรียนรู้ -ใน Quick Start คุณใช้ GitHub Models เพื่อส่ง prompt, เรียกใช้เครื่องมือ, สร้าง pipeline RAG และทดสอบ guardrails ตัวอย่างเหล่านั้นแสดงให้เห็นว่าสิ่งใดเป็นไปได้ — ตอนนี้เราจะเปลี่ยนมาใช้ Azure OpenAI และ GPT-5.2 และเริ่มสร้างแอปพลิเคชันสไตล์ production โมดูลนี้เน้นด้าน AI การสนทนาที่จำบริบทและรักษาสถานะ — แนวคิดที่ตัวอย่าง Quick Start ใช้เบื้องหลังแต่ไม่ได้อธิบาย +นี่คือจุดเริ่มต้นของคุณกับ LangChain4j และ Azure OpenAI เราจะเริ่มจากพื้นฐานและเริ่มสร้างแอปพลิเคชันสไตล์การผลิต โมดูลนี้เน้นที่ AI การสนทนาที่จดจำบริบทและรักษาสถานะ — แนวคิดพื้นฐานที่โมดูลต่อๆ ไปจะสร้างขึ้นจากสิ่งนี้ -เราจะใช้ GPT-5.2 ของ Azure OpenAI ตลอดคำแนะนำนี้เพราะความสามารถในการเข้าเหตุผลขั้นสูงทำให้พฤติกรรมของแต่ละรูปแบบชัดเจนขึ้น เมื่อคุณเพิ่มหน่วยความจำ คุณจะมองเห็นความแตกต่างได้ชัดเจน ซึ่งช่วยให้เข้าใจว่าส่วนประกอบแต่ละอย่างนำอะไรมาให้แอปพลิเคชันของคุณ +เราจะใช้ GPT-5.2 ของ Azure OpenAI ตลอดคำแนะนำนี้ เพราะความสามารถในการเหตุผลขั้นสูงของมันทำให้พฤติกรรมของรูปแบบต่างๆ ชัดเจนขึ้น เมื่อคุณเพิ่มหน่วยความจำ คุณจะเห็นความแตกต่างได้อย่างชัดเจน ซึ่งช่วยให้เข้าใจองค์ประกอบแต่ละส่วนของแอปพลิเคชันได้ง่ายขึ้น -คุณจะสร้างแอปพลิเคชันหนึ่งที่สาธิตทั้งสองรูปแบบ: +คุณจะสร้างแอปพลิเคชันหนึ่งตัวที่แสดงทั้งสองรูปแบบ: -**แชทไม่มีสถานะ** - ทุกคำขอเป็นอิสระ โมเดลไม่มีความทรงจำของข้อความก่อนหน้า นี่คือรูปแบบที่คุณใช้ใน quick start +**แชทแบบไม่มีสถานะ** - ทุกคำขอเป็นอิสระอย่างสมบูรณ์ โมเดลไม่มีหน่วยความจำของข้อความก่อนหน้า นี่คือจุดเริ่มต้นที่ง่ายที่สุด -**การสนทนามีสถานะ** - ทุกคำขอรวมประวัติการสนทนา โมเดลรักษาบริบทตลอดหลายรอบ นี่คือสิ่งที่แอปพลิเคชันใน production ต้องการ +**การสนทนาแบบมีสถานะ** - แต่ละคำขอรวมประวัติการสนทนา โมเดลรักษาบริบทตลอดหลายรอบ นี่คือสิ่งที่แอปพลิเคชันจริงในงานผลิตต้องการ ## ข้อกำหนดเบื้องต้น -- บัญชี Azure พร้อมสิทธิ์เข้าถึง Azure OpenAI +- บัญชีสมาชิก Azure ที่เข้าถึง Azure OpenAI ได้ - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **หมายเหตุ:** Java, Maven, Azure CLI และ Azure Developer CLI (azd) ติดตั้งไว้ล่วงหน้าแล้วใน devcontainer ที่เตรียมไว้ให้ +> **หมายเหตุ:** Java, Maven, Azure CLI และ Azure Developer CLI (azd) ได้ติดตั้งไว้ล่วงหน้าใน devcontainer ที่เตรียมไว้ให้แล้ว -> **หมายเหตุ:** โมดูลนี้ใช้ GPT-5.2 บน Azure OpenAI การดีพลอยตั้งค่าให้อัตโนมัติผ่านคำสั่ง `azd up` - ห้ามแก้ไขชื่อโมเดลในโค้ด +> **หมายเหตุ:** โมดูลนี้ใช้ GPT-5.2 บน Azure OpenAI การปรับใช้ถูกกำหนดค่าจาก `azd up` โดยอัตโนมัติ — อย่าเปลี่ยนชื่อโมเดลในโค้ด -## เข้าใจปัญหาหลัก +## ทำความเข้าใจปัญหาหลัก -โมเดลภาษามีสถานะเป็น Stateless แต่ละคำขอ API เป็นอิสระกัน หากคุณส่ง "My name is John" แล้วถามว่า "What's my name?" โมเดลจะไม่รู้ว่าคุณเพิ่งแนะนำตัว เพราะถือว่าแต่ละคำขอเป็นบทสนทนาแรกครั้งเสมอ +โมเดลภาษาไม่มีสถานะ ทุกการเรียก API เป็นอิสระ หากคุณพิมพ์ว่า "My name is John" และถามว่า "What's my name?" โมเดลจะไม่ทราบว่าคุณเพิ่งแนะนำตัวเอง มันปฏิบัติต่อทุกคำขอเหมือนเป็นการสนทนาแรกที่คุณเคยมี -สิ่งนี้เหมาะสำหรับ Q&A ง่าย ๆ แต่ไร้ประโยชน์สำหรับแอปพลิเคชันจริง ๆ บอทบริการลูกค้าต้องจำสิ่งที่คุณบอก ผู้ช่วยส่วนตัวต้องมีบริบท การสนทนาหลายรอบต้องการหน่วยความจำ +สิ่งนี้ใช้ได้ดีกับคำถามง่ายๆ แต่ไม่มีประโยชน์สำหรับแอปพลิเคชันจริงๆ หุ่นยนต์บริการลูกค้าต้องจำสิ่งที่คุณบอกให้พวกเขาทราบ ผู้ช่วยส่วนตัวต้องมีบริบท การสนทนาแบบหลายรอบต้องมีหน่วยความจำ -แผนภาพนี้เปรียบเทียบทั้งสองแนวทาง — ด้านซ้าย คือการเรียกแบบ stateless ที่ลืมชื่อคุณ; ด้านขวา คือการเรียกแบบ stateful โดยใช้ ChatMemory ที่จำชื่อคุณได้ +แผนภาพด้านล่างเปรียบเทียบสองวิธี — ทางซ้ายคือการเรียกแบบไม่มีสถานะที่ลืมชื่อคุณ และทางขวาคือการเรียกแบบมีสถานะที่ใช้ ChatMemory ซึ่งจดจำได้ Stateless vs Stateful Conversations -*ความแตกต่างระหว่างการสนทนาแบบ stateless (เรียกอิสระ) และ stateful (มีบริบท)* +*ความแตกต่างระหว่างการสนทนาแบบไม่มีสถานะ (เรียกอิสระ) และแบบมีสถานะ (รับรู้บริบท)* -## ทำความเข้าใจเกี่ยวกับโทเค็น +## ทำความเข้าใจโทเค็น -ก่อนเข้าสู่การสนทนา จำเป็นต้องเข้าใจโทเค็น - หน่วยพื้นฐานของข้อความที่โมเดลภาษาประมวลผล: +ก่อนลงลึกในบทสนทนา จำเป็นต้องเข้าใจโทเค็น — หน่วยพื้นฐานของข้อความที่โมเดลภาษาใช้ประมวลผล: Token Explanation -*ตัวอย่างการแบ่งข้อความออกเป็นโทเค็น - "I love AI!" แยกเป็นหน่วยประมวลผล 4 หน่วย* +*ตัวอย่างการแบ่งข้อความออกเป็นโทเค็น — "I love AI!" แบ่งเป็น 4 หน่วยประมวลผลแยกกัน* -โทเค็นคือวิธีที่โมเดล AI วัดและประมวลผลข้อความ คำ, เครื่องหมายวรรคตอน และช่องว่างสามารถเป็นโทเค็นได้ โมเดลแต่ละตัวมีขีดจำกัดจำนวนโทเค็นที่ประมวลผลได้พร้อมกัน (400,000 สำหรับ GPT-5.2 โดยรับเข้าสูงสุด 272,000 โทเค็น และส่งออกสูงสุด 128,000 โทเค็น) การเข้าใจโทเค็นช่วยคุณจัดการความยาวการสนทนาและค่าใช้จ่ายได้ +โทเค็นคือวิธีที่โมเดล AI วัดและประมวลผลข้อความ คำ เครื่องหมายวรรคตอน และแม้แต่ช่องว่างสามารถเป็นโทเค็นได้ โมเดลของคุณมีจำกัดว่าประมวลผลโทเค็นได้กี่โทเค็นในครั้งเดียว (400,000 สำหรับ GPT-5.2 โดยมีโทเค็นนำเข้าได้สูงสุด 272,000 และโทเค็นส่งออก 128,000) การเข้าใจโทเค็นช่วยให้คุณจัดการความยาวบทสนทนาและค่าใช้จ่ายได้ -## วิธีการทำงานของหน่วยความจำ +## หน่วยความจำทำงานอย่างไร -หน่วยความจำแชทแก้ปัญหา stateless โดยเก็บประวัติการสนทนา ก่อนส่งคำขอ คุณสมบัติใน framework จะเพิ่มข้อความก่อนหน้าที่เกี่ยวข้องเข้าไป เมื่อคุณถามว่า "What's my name?" ระบบจะส่งประวัติการสนทนาทั้งหมด ช่วยให้โมเดลเห็นว่าคุณเคยกล่าว "My name is John." +หน่วยความจำช่วยแก้ปัญหาแบบไม่มีสถานะโดยเก็บประวัติการสนทนา ก่อนจะส่งคำขอไปยังโมเดล เฟรมเวิร์กจะเพิ่มข้อความก่อนหน้าที่เกี่ยวข้องเข้าไป เมื่อคุณถามว่า "What's my name?" ระบบจะส่งประวัติการสนทนาทั้งหมด ทำให้โมเดลเห็นว่าคุณเพิ่งบอกว่า "My name is John" -LangChain4j มี implementation ของหน่วยความจำให้จัดการเรื่องนี้โดยอัตโนมัติ คุณเลือกจำนวนข้อความที่จะเก็บ และ framework จะจัดการหน้าต่างบริบท แผนภาพด้านล่างแสดงการทำงานของ MessageWindowChatMemory ที่รักษาหน้าต่างเลื่อนของข้อความล่าสุด +LangChain4j มีการใช้งานหน่วยความจำที่จัดการกระบวนการนี้โดยอัตโนมัติ คุณเลือกจำนวนข้อความที่เก็บไว้ เฟรมเวิร์กจะจัดการหน้าต่างบริบทให้ แผนภาพด้านล่างแสดงว่า MessageWindowChatMemory รักษาหน้าต่างเลื่อนของข้อความล่าสุดอย่างไร Memory Window Concept -*MessageWindowChatMemory รักษาหน้าต่างเลื่อนของข้อความล่าสุดโดยอัตโนมัติ ลบข้อความเก่าเมื่อมีข้อความใหม่เข้ามา* +*MessageWindowChatMemory รักษาหน้าต่างเลื่อนของข้อความล่าสุด โดยลบข้อความเก่าโดยอัตโนมัติ* -## วิธีที่ใช้ LangChain4j +## วิธีที่ใช้ LangChain4j นี้ -โมดูลนี้ขยาย quick start โดยรวม Spring Boot และเพิ่มหน่วยความจำการสนทนา นี่คือการประกอบส่วนต่าง ๆ: +โมดูลนี้ผสานรวม Spring Boot และเพิ่มหน่วยความจำการสนทนา นี่คือวิธีที่ชิ้นส่วนต่างๆ ประสานกัน: **Dependencies** - เพิ่มไลบรารี LangChain4j สองตัว: @@ -93,7 +93,7 @@ LangChain4j มี implementation ของหน่วยความจำใ langchain4j-open-ai-official ``` - + **Chat Model** - กำหนดค่า Azure OpenAI เป็น Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @@ -108,8 +108,8 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { .build(); } ``` - -บิวเดอร์อ่านข้อมูลรับรองจาก environment variables ที่ตั้งโดยคำสั่ง `azd up` การตั้งค่า `baseUrl` เป็น endpoint ของ Azure ของคุณจะทำให้ OpenAI client ทำงานกับ Azure OpenAI ได้ + +Builder อ่านข้อมูลรับรองจากตัวแปรสภาพแวดล้อมที่ตั้งไว้โดย `azd up` การตั้งค่า `baseUrl` เป็น endpoint ของ Azure ทำให้ไคลเอนต์ OpenAI ทำงานกับ Azure OpenAI ได้ **หน่วยความจำการสนทนา** - ติดตามประวัติแชทด้วย MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -123,200 +123,200 @@ memory.add(UserMessage.from("What's my name?")); AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` + +สร้างหน่วยความจำด้วย `withMaxMessages(10)` เพื่อเก็บข้อความล่าสุด 10 ข้อความ เพิ่มข้อความผู้ใช้และ AI ด้วยตัวห่อประเภท: `UserMessage.from(text)` และ `AiMessage.from(text)` ดึงประวัติด้วย `memory.messages()` และส่งไปยังโมเดล บริการเก็บตัวอย่างหน่วยความจำแยกกันสำหรับแต่ละรหัสการสนทนา ทำให้ผู้ใช้หลายคนแชทพร้อมกันได้ -สร้างหน่วยความจำด้วย `withMaxMessages(10)` เพื่อเก็บข้อความล่าสุด 10 ข้อความ เพิ่มข้อความผู้ใช้และ AI ด้วยตัวห่อ typed wrappers: `UserMessage.from(text)` และ `AiMessage.from(text)` รับประวัติด้วย `memory.messages()` แล้วส่งไปยังโมเดล บริการนี้เก็บหน่วยความจำแยกต่างหากตาม ID ของการสนทนา ทำให้ผู้ใช้หลายคนแชทได้พร้อมกัน - -> **🤖 ลองใช้กับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) แล้วถาม: -> - "MessageWindowChatMemory ตัดสินใจอย่างไรว่าจะลบข้อความไหนเมื่อหน้าต่างเต็ม?" -> - "ฉันจะเก็บหน่วยความจำแบบกำหนดเองโดยใช้ฐานข้อมูลแทนใน-memory ได้ไหม?" -> - "ฉันจะเพิ่มการสรุปข้อความเพื่อบีบอัดประวัติการสนทนาเก่าได้อย่างไร?" +> **🤖 ลองใช้ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) และถามว่า: +> - "MessageWindowChatMemory ตัดสินใจทิ้งข้อความไหนเมื่อหน้าต่างเต็มอย่างไร?" +> - "ฉันจะสร้างหน่วยความจำแบบกำหนดเองโดยใช้ฐานข้อมูลแทนเก็บในหน่วยความจำได้ไหม?" +> - "ฉันจะเพิ่มการสรุปเพื่อบีบอัดประวัติการสนทนาเก่าได้อย่างไร?" -จุดสิ้นสุดแชทแบบ stateless ข้ามการใช้หน่วยความจำเลย - เพียงแค่ `chatModel.chat(prompt)` เหมือน quick start ส่วน stateful เพิ่มข้อความในหน่วยความจำ, ดึงประวัติ และผนวกบริบทนั้นกับแต่ละคำขอ การกำหนดค่าโมเดลเหมือนกัน แต่แพทเทิร์นต่างกัน +จุดสิ้นสุดแชทแบบไม่มีสถานะจะข้ามหน่วยความจำโดยสมบูรณ์ — เพียงแค่ `chatModel.chat(prompt)` เหมือนเริ่มต้นอย่างรวดเร็ว จุดสิ้นสุดแบบมีสถานะจะเพิ่มข้อความลงในหน่วยความจำ ดึงประวัติ และใส่บริบทนั้นในแต่ละคำขอ การตั้งค่าโมเดลเหมือนกัน แต่รูปแบบต่างกัน -## ดีพลอยโครงสร้างพื้นฐาน Azure OpenAI +## ปรับใช้โครงสร้างพื้นฐาน Azure OpenAI -**Bash:** +**Bash:** ```bash cd 01-introduction azd up # เลือกการสมัครใช้งานและตำแหน่งที่ตั้ง (แนะนำ eastus2) ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 01-introduction -azd up # เลือกการสมัครใช้งานและตำแหน่งที่ตั้ง (แนะนำ eastus2) +azd up # เลือกการสมัครสมาชิกและตำแหน่งที่ตั้ง (แนะนำ eastus2) ``` + +> **หมายเหตุ:** หากคุณพบข้อผิดพลาดหมดเวลารอ (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) ให้รัน `azd up` อีกครั้ง Azure อาจยังอยู่ระหว่างการจัดสรรทรัพยากรในพื้นหลัง การลองใหม่จะช่วยให้การปรับใช้เสร็จสมบูรณ์เมื่อทรัพยากรเข้าสู่สถานะสุดท้าย -> **หมายเหตุ:** หากพบข้อผิดพลาด timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), ให้รันคำสั่ง `azd up` อีกครั้ง ได้โปรดทราบว่า Azure อาจยังอยู่ระหว่าง provisioning ในเบื้องหลัง การลองใหม่จะช่วยให้ดีพลอยเสร็จสมบูรณ์เมื่อ resources อยู่ในสถานะสุดท้าย +สิ่งนี้จะ: +1. ปรับใช้ทรัพยากร Azure OpenAI ด้วยโมเดล GPT-5.2 และ text-embedding-3-small +2. สร้างไฟล์ `.env` ในโฟลเดอร์โปรเจกต์โดยอัตโนมัติพร้อมข้อมูลรับรอง +3. ตั้งค่าตัวแปรสภาพแวดล้อมทั้งหมดที่จำเป็น -ขั้นตอนจะ: -1. ดีพลอย Azure OpenAI resource กับโมเดล GPT-5.2 และ text-embedding-3-small -2. สร้างไฟล์ `.env` อัตโนมัติในโฟลเดอร์โปรเจกต์ด้วยข้อมูลรับรอง -3. ตั้งค่าสิ่งแวดล้อมที่จำเป็นทั้งหมด - -**ประสบปัญหาการดีพลอย?** ดู [Infrastructure README](infra/README.md) สำหรับการแก้ไขปัญหาละเอียด รวมถึงปัญหาชื่อโดเมนย่อย, ขั้นตอนการดีพลอยผ่าน Azure Portal ด้วยตนเอง, และคำแนะนำการตั้งค่าโมเดล +**มีปัญหาเรื่องการปรับใช้?** ดูที่ [Infrastructure README](infra/README.md) สำหรับคำแนะนำขั้นตอนแก้ปัญหาอย่างละเอียด รวมถึงปัญหาชื่อโดเมนย่อยซ้ำ ขั้นตอนการปรับใช้ Azure Portal ด้วยตนเอง และแนวทางการตั้งค่าโมเดล **ตรวจสอบว่า deployment สำเร็จ:** -**Bash:** +**Bash:** ```bash cat ../.env # ควรแสดง AZURE_OPENAI_ENDPOINT, API_KEY, เป็นต้น ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # ควรแสดง AZURE_OPENAI_ENDPOINT, API_KEY, เป็นต้น ``` - -> **หมายเหตุ:** คำสั่ง `azd up` สร้างไฟล์ `.env` ให้อัตโนมัติ หากคุณต้องการแก้ไขภายหลัง สามารถแก้ไขไฟล์ `.env` ด้วยมือ หรือสร้างไฟล์ใหม่โดยรัน: -> -> **Bash:** + +> **หมายเหตุ:** คำสั่ง `azd up` จะสร้างไฟล์ `.env` โดยอัตโนมัติ หากต้องแก้ไขทีหลัง คุณสามารถแก้ไขไฟล์ `.env` ด้วยตนเองหรือลองสร้างใหม่โดยรัน: +> +> **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` -> -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` + +## รันแอปพลิเคชันท้องถิ่น -## รันแอปพลิเคชันในเครื่อง +**ตรวจสอบการปรับใช้:** -**ตรวจสอบ deployment:** +ตรวจสอบว่าไฟล์ `.env` อยู่ในไดเรกทอรีหลักพร้อมข้อมูลรับรอง Azure รันคำสั่งนี้จากไดเรกทอรีโมดูล (`01-introduction/`): -ตรวจสอบให้แน่ใจว่าไฟล์ `.env` อยู่ในโฟลเดอร์หลักและมีข้อมูลรับรอง Azure รันคำสั่งนี้จากโฟลเดอร์โมดูล (`01-introduction/`): - -**Bash:** +**Bash:** ```bash cat ../.env # ควรแสดง AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # ควรแสดง AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - + **เริ่มต้นแอปพลิเคชัน:** **ตัวเลือกที่ 1: ใช้ Spring Boot Dashboard (แนะนำสำหรับผู้ใช้ VS Code)** -dev container มี extension Spring Boot Dashboard ซึ่งให้หน้าต่าง UI สำหรับจัดการแอป Spring Boot ทั้งหมดใน workspace คุณจะเจอมันใน Activity Bar ด้านซ้ายของ VS Code (มองหาไอคอน Spring Boot) +dev container รวมส่วนขยาย Spring Boot Dashboard ซึ่งให้ส่วนติดต่อผู้ใช้แบบกราฟิกสำหรับจัดการแอปพลิเคชัน Spring Boot ทั้งหมด คุณจะพบได้ใน Activity Bar ด้านซ้ายใน VS Code (ดูไอคอน Spring Boot) -จาก Spring Boot Dashboard คุณสามารถ: -- ดูแอป Spring Boot ทั้งหมดที่พร้อมใช้งานใน workspace -- สั่งเริ่ม/หยุดแอปด้วยการคลิกเดียว -- ดูล็อกแอปแบบเรียลไทม์ -- ตรวจสอบสถานะของแอป +จาก Spring Boot Dashboard คุณสามารถ: +- ดูแอปพลิเคชัน Spring Boot ทั้งหมดใน workspace +- เริ่ม/หยุดแอปพลิเคชันได้ด้วยคลิกเดียว +- ดูบันทึกแอปพลิเคชันแบบเรียลไทม์ +- ตรวจสอบสถานะแอปพลิเคชัน -คลิกปุ่มเล่นข้างๆ “introduction” เพื่อเริ่มโมดูลนี้ หรือสั่งเริ่มทุกโมดูลพร้อมกัน +เพียงคลิกปุ่มเล่นข้างๆ "introduction" เพื่อเริ่มโมดูลนี้ หรือเริ่มโมดูลทั้งหมดพร้อมกัน Spring Boot Dashboard -*Spring Boot Dashboard ใน VS Code — เริ่ม หยุด และตรวจสอบโมดูลทั้งหมดจากที่เดียว* +*Spring Boot Dashboard ใน VS Code — เริ่ม หยุด และตรวจสอบทุกโมดูลจากที่เดียว* **ตัวเลือกที่ 2: ใช้สคริปต์เชลล์** -เริ่มแอปเว็บทั้งหมด (โมดูล 01-04): +เริ่มแอปพลิเคชันเว็บทั้งหมด (โมดูล 01-04): -**Bash:** +**Bash:** ```bash -cd .. # จากไดเรกทอรีราก +cd .. # จากไดเรกทอรีรูท ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell -cd .. # จากไดเรกทอรีหลัก +cd .. # จากไดเรกทอรีราก .\start-all.ps1 ``` - + หรือเริ่มแค่โมดูลนี้: -**Bash:** +**Bash:** ```bash cd 01-introduction ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 01-introduction .\start.ps1 ``` + +สคริปต์ทั้งสองโหลดตัวแปรสภาพแวดล้อมจากไฟล์ `.env` ที่โฟลเดอร์รากโดยอัตโนมัติ และจะสร้าง JAR หากยังไม่มี -สคริปต์ทั้งสองโหลด environment variables จากไฟล์ `.env` ที่โฟลเดอร์หลักโดยอัตโนมัติ และจะ build JAR หากยังไม่มีไฟล์ - -> **หมายเหตุ:** หากต้องการ build โมดูลทั้งหมดด้วยมือก่อนรัน: -> -> **Bash:** +> **หมายเหตุ:** หากคุณต้องการสร้างทุกโมดูลด้วยตนเองก่อนเริ่ม: +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` + +เปิด http://localhost:8080 ในเบราว์เซอร์ของคุณ -เปิดเบราว์เซอร์ที่ http://localhost:8080 - -**เพื่อหยุด:** +**หยุดแอปพลิเคชัน:** -**Bash:** +**Bash:** ```bash ./stop.sh # เฉพาะโมดูลนี้ # หรือ cd .. && ./stop-all.sh # ทุกโมดูล ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # โมดูลนี้เท่านั้น # หรือ cd ..; .\stop-all.ps1 # ทุกโมดูล ``` + +## การใช้แอปพลิเคชัน -## การใช้งานแอปพลิเคชัน - -แอปมีอินเทอร์เฟซเว็บที่มีแชทสองรูปแบบอยู่เคียงข้างกัน +แอปพลิเคชันมีส่วนติดต่อเว็บที่แสดงสองระบบแชทขนานกัน Application Home Screen -*แดชบอร์ดแสดงตัวเลือกทั้ง Simple Chat (แบบ stateless) และ Conversational Chat (แบบ stateful)* +*แดชบอร์ดแสดงตัวเลือกแชทง่าย (ไม่มีสถานะ) และแชทแบบสนทนา (มีสถานะ)* ### แชทแบบไม่มีสถานะ (แผงซ้าย) -ลองใช้แบบนี้ก่อน ถามว่า "My name is John" แล้วถามทันทีว่า "What's my name?" โมเดลจะไม่จำเพราะแต่ละข้อความเป็นอิสระ นี่แสดงปัญหาหลักของการใช้โมเดลภาษาง่าย ๆ — ไม่มีบริบทของการสนทนา +ลองอันนี้ก่อน พิมพ์ "My name is John" แล้วถามทันทีว่า "What's my name?" โมเดลจะไม่จำเพราะแต่ละข้อความแยกกัน แสดงปัญหาหลักของการรวมโมเดลภาษาอย่างง่าย — ไม่มีบริบทการสนทนา Stateless Chat Demo -*AI จะไม่จำชื่อคุณจากข้อความก่อนหน้า* +*AI ไม่จำชื่อของคุณจากข้อความก่อนหน้า* ### แชทแบบมีสถานะ (แผงขวา) -คราวนี้ลองชุดคำถามเดียวกันที่นี่ ถามว่า "My name is John" แล้วถาม "What's my name?" โมเดลจะจำได้ ความแตกต่างคือ MessageWindowChatMemory ที่รักษาประวัติการสนทนาและแนบร่วมกับทุกคำขอ นี่คือวิธีที่ AI สนทนาใน production ทำงาน +ลองชุดคำสั่งเดียวกันนี้ที่นี่ พิมพ์ "My name is John" แล้วถาม "What's my name?" คราวนี้มันจำได้ ความต่างคือ MessageWindowChatMemory — มันเก็บประวัติการสนทนาและรวมเข้าไปกับทุกคำขอ นี่คือวิธีที่ AI สนทนาในระบบผลิตงานจริงทำงาน Stateful Chat Demo -*AI จำชื่อคุณจากการสนทนาในช่วงก่อนหน้า* +*AI จำชื่อของคุณจากก่อนหน้านี้ในการสนทนา* -ทั้งสองแผงใช้โมเดล GPT-5.2 ตัวเดียว ความแตกต่างคือหน่วยความจำ ซึ่งทำให้เห็นชัดเจนว่าหน่วยความจำช่วยแอปพลิเคชันอย่างไรและเหตุใดจึงจำเป็นสำหรับใช้งานจริง +แผงทั้งสองใช้โมเดล GPT-5.2 ตัวเดียวกัน ต่างกันแค่หน่วยความจำ ซึ่งช่วยให้เห็นภาพชัดเจนว่าหน่วยความจำมีประโยชน์อย่างไรกับแอปพลิเคชันของคุณและเหตุใดจึงจำเป็นสำหรับการใช้งานจริง ## ขั้นตอนถัดไป -**โมดูลต่อไป:** [02-prompt-engineering - การสร้าง Prompt กับ GPT-5.2](../02-prompt-engineering/README.md) +**โมดูลถัดไป:** [02-prompt-engineering - การออกแบบ Prompt ด้วย GPT-5.2](../02-prompt-engineering/README.md) --- -**การนำทาง:** [← ก่อนหน้า: Module 00 - Quick Start](../00-quick-start/README.md) | [กลับสู่หน้าหลัก](../README.md) | [ถัดไป: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**การนำทาง:** [← กลับไปหน้าแรก](../README.md) | [ถัดไป: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- -**คำปฏิเสธความรับผิด**: -เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษาด้วย AI [Co-op Translator](https://github.com/Azure/co-op-translator) แม้เราจะพยายามให้ความถูกต้องสูงสุด แต่โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความคลาดเคลื่อนได้ เอกสารต้นฉบับในภาษาต้นทางถือเป็นแหล่งข้อมูลที่ถูกต้องและเชื่อถือได้ สำหรับข้อมูลที่สำคัญ ขอแนะนำให้ใช้การแปลโดยผู้เชี่ยวชาญมนุษย์เป็นหลัก เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดที่เกิดจากการใช้การแปลนี้ +**ปฏิเสธความรับผิดชอบ**: +เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) ขณะที่เราพยายามให้ความถูกต้อง โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดที่เกิดขึ้นจากการใช้การแปลนี้ \ No newline at end of file diff --git a/translations/th/02-prompt-engineering/README.md b/translations/th/02-prompt-engineering/README.md index 40563b039..5880cfc9b 100644 --- a/translations/th/02-prompt-engineering/README.md +++ b/translations/th/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Module 02: การออกแบบ Prompt กับ GPT-5.2 +# Module 02: การออกแบบคำสั่ง (Prompt Engineering) กับ GPT-5.2 ## สารบัญ -- [วิดีโอสอน](../../../02-prompt-engineering) -- [สิ่งที่คุณจะได้เรียนรู้](../../../02-prompt-engineering) -- [ข้อกำหนดเบื้องต้น](../../../02-prompt-engineering) -- [ความเข้าใจการออกแบบ Prompt](../../../02-prompt-engineering) -- [พื้นฐานการออกแบบ Prompt](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Templates](../../../02-prompt-engineering) -- [รูปแบบขั้นสูง](../../../02-prompt-engineering) -- [รันแอปพลิเคชัน](../../../02-prompt-engineering) -- [ภาพหน้าจอแอปพลิเคชัน](../../../02-prompt-engineering) -- [สำรวจรูปแบบต่าง ๆ](../../../02-prompt-engineering) - - [ความกระตือรือร้นต่ำ vs สูง](../../../02-prompt-engineering) - - [การดำเนินการงาน (คำแนะนำเครื่องมือ)](../../../02-prompt-engineering) - - [โค้ดที่สะท้อนตนเอง](../../../02-prompt-engineering) - - [การวิเคราะห์อย่างมีโครงสร้าง](../../../02-prompt-engineering) - - [แชทหลายรอบ](../../../02-prompt-engineering) - - [การคิดอย่างเป็นขั้นตอน](../../../02-prompt-engineering) - - [ผลลัพธ์ที่จำกัด](../../../02-prompt-engineering) -- [สิ่งที่คุณกำลังเรียนรู้อย่างแท้จริง](../../../02-prompt-engineering) -- [ขั้นตอนถัดไป](../../../02-prompt-engineering) +- [วิดีโอสอน](#วิดีโอสอน) +- [สิ่งที่คุณจะได้เรียนรู้](#สิ่งที่คุณจะได้เรียนรู้) +- [สิ่งที่ต้องเตรียมก่อนเรียน](#สิ่งที่ต้องเตรียมก่อนเรียน) +- [ความเข้าใจเกี่ยวกับการออกแบบคำสั่ง](#ความเข้าใจเกี่ยวกับการออกแบบคำสั่ง) +- [พื้นฐานการออกแบบคำสั่ง](#พื้นฐานการออกแบบคำสั่ง) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [รูปแบบขั้นสูง](#รูปแบบขั้นสูง) +- [รันแอปพลิเคชัน](#เรียกใช้แอปพลิเคชัน) +- [ภาพหน้าจอแอปพลิเคชัน](#ภาพหน้าจอแอปพลิเคชัน) +- [สำรวจรูปแบบต่างๆ](#การสำรวจรูปแบบต่าง-ๆ) + - [ความกระตือรือร้นต่ำ vs สูง](#ความกระตือรือร้นต่ำกับสูง) + - [การปฏิบัติงานตามขั้นตอน (เครื่องมือเบื้องต้น)](#การดำเนินงานตามงาน-tool-preambles) + - [โค้ดที่สะท้อนตนเอง](#โค้ดที่สะท้อนตนเอง) + - [การวิเคราะห์แบบมีโครงสร้าง](#การวิเคราะห์แบบมีโครงสร้าง) + - [แชทหลายรอบ](#แชทแบบหลายรอบ) + - [เหตุผลทีละขั้นตอน](#การคิดเชิงตรรกะแบบขั้นตอนต่อขั้นตอน) + - [ผลลัพธ์ที่ถูกจำกัด](#ผลลัพธ์แบบจำกัด) +- [สิ่งที่คุณกำลังเรียนรู้อย่างแท้จริง](#สิ่งที่คุณกำลังเรียนรู้จริง-ๆ) +- [ก้าวต่อไป](#ขั้นตอนต่อไป) ## วิดีโอสอน -ชมเซสชันสดนี้ที่อธิบายวิธีเริ่มต้นกับโมดูลนี้: +ชมการสอนแบบสดนี้ที่อธิบายวิธีเริ่มต้นกับโมดูลนี้: Prompt Engineering with LangChain4j - Live Session ## สิ่งที่คุณจะได้เรียนรู้ -แผนภาพต่อไปนี้แสดงภาพรวมของหัวข้อหลักและทักษะที่คุณจะพัฒนาในโมดูลนี้ — ตั้งแต่เทคนิครับปรุง prompt จนถึงเวิร์กโฟลว์ขั้นตอนต่อขั้นตอนที่คุณจะปฏิบัติตาม +แผนภาพต่อไปนี้แสดงภาพรวมของหัวข้อและทักษะสำคัญที่คุณจะพัฒนาในโมดูลนี้ — ตั้งแต่เทคนิคการปรับแต่งคำสั่งจนถึงขั้นตอนการทำงานทีละขั้นตอนที่คุณจะปฏิบัติตาม -What You'll Learn +สิ่งที่คุณจะได้เรียนรู้ -ในโมดูลก่อนหน้า คุณได้สำรวจการโต้ตอบพื้นฐานของ LangChain4j กับโมเดล GitHub และเห็นว่าหน่วยความจำช่วยให้ AI สนทนากับ Azure OpenAI ได้อย่างไร ตอนนี้เราจะเน้นวิธีการถามคำถาม — ตัว prompt เอง — โดยใช้ GPT-5.2 ของ Azure OpenAI วิธีที่คุณจัดโครงสร้าง prompt มีผลอย่างมากต่อคุณภาพของคำตอบที่ได้รับ เราเริ่มด้วยการทบทวนเทคนิคการออกแบบ prompt พื้นฐาน จากนั้นไปยังแปดรูปแบบขั้นสูงที่ใช้ประโยชน์เต็มที่จากความสามารถของ GPT-5.2 +ในโมดูลก่อนหน้านี้ คุณได้เห็นว่าหน่วยความจำช่วยให้ AI สนทนาใช้งานกับ Azure OpenAI ได้อย่างไร ตอนนี้เราจะเน้นที่วิธีการตั้งคำถาม — คำสั่ง prompt เอง — โดยใช้ GPT-5.2 ของ Azure OpenAI วิธีที่คุณจัดโครงสร้างคำสั่งจะส่งผลอย่างมีนัยสำคัญต่อคุณภาพของคำตอบที่ได้รับ เราจะเริ่มด้วยการทบทวนเทคนิคการตั้ง prompt พื้นฐาน แล้วค่อยเข้าสู่รูปแบบขั้นสูงแปดรูปแบบที่ใช้ประโยชน์สูงสุดจากความสามารถของ GPT-5.2 -เราจะใช้ GPT-5.2 เพราะมันเพิ่มการควบคุมเหตุผล — คุณสามารถบอกโมเดลได้ว่าต้องคิดมากแค่ไหนก่อนตอบ นี่ทำให้กลยุทธ์การออกแบบ prompt ต่าง ๆ ชัดเจนขึ้นและช่วยให้คุณเข้าใจว่าเมื่อไรควรใช้วิธีใด ทั้งยังได้รับประโยชน์จากการจำกัดอัตราที่น้อยกว่าของ Azure สำหรับ GPT-5.2 เมื่อเทียบกับโมเดล GitHub +เราใช้ GPT-5.2 เพราะมันเปิดตัวฟีเจอร์การควบคุมการให้เหตุผล — คุณสามารถบอกโมเดลได้ว่าจะให้คิดมากแค่ไหนก่อนที่จะตอบ นี่ทำให้กลยุทธ์การตั้งคำสั่งต่างๆ ชัดเจนขึ้นและช่วยให้คุณเข้าใจว่าเมื่อไรควรใช้แต่ละวิธี -## ข้อกำหนดเบื้องต้น +## สิ่งที่ต้องเตรียมก่อนเรียน -- ทำโมดูล 01 (ติดตั้งทรัพยากร Azure OpenAI) เสร็จแล้ว -- มีไฟล์ `.env` ในไดเรกทอรีหลักพร้อมข้อมูลรับรอง Azure (สร้างโดย `azd up` ในโมดูล 01) +- ทำโมดูล 01 เสร็จสมบูรณ์แล้ว (พร้อมใช้งาน Azure OpenAI resources) +- ไฟล์ `.env` ในโฟลเดอร์หลักที่มีข้อมูลรับรอง Azure (ถูกสร้างโดยคำสั่ง `azd up` ในโมดูล 01) -> **หมายเหตุ:** หากยังไม่ได้ทำโมดูล 01 ให้ทำตามคำแนะนำการติดตั้งที่นั่นก่อน +> **หมายเหตุ:** หากคุณยังไม่ได้ทำโมดูล 01 ให้ทำตามคำแนะนำการติดตั้งในนั้นก่อน -## ความเข้าใจการออกแบบ Prompt +## ความเข้าใจเกี่ยวกับการออกแบบคำสั่ง -โดยพื้นฐานแล้ว การออกแบบ prompt คือความแตกต่างระหว่างคำสั่งที่คลุมเครือกับคำสั่งที่ชัดเจน ดังที่การเปรียบเทียบด้านล่างแสดงให้เห็น +โดยพื้นฐานแล้ว การออกแบบคำสั่งคือความแตกต่างระหว่างคำสั่งที่คลุมเครือกับคำสั่งที่ชัดเจน ดังภาพประกอบด้านล่างนี้ -What is Prompt Engineering? +การออกแบบคำสั่งคืออะไร? -การออกแบบ prompt คือการออกแบบข้อความเข้า (input) ที่ให้ผลลัพธ์ตามที่คุณต้องการอย่างสม่ำเสมอ ไม่ใช่แค่การตั้งคำถามเฉย ๆ แต่เป็นการจัดโครงสร้างคำขอเพื่อให้โมเดลเข้าใจอย่างแม่นยำว่าคุณต้องการอะไรและจะส่งมอบอย่างไร +การออกแบบคำสั่งเกี่ยวกับการออกแบบข้อความนำเข้าที่ทำให้คุณได้ผลลัพธ์ที่ต้องการอย่างสม่ำเสมอ ไม่ใช่แค่การตั้งคำถาม — แต่เป็นการจัดโครงสร้างคำขอให้โมเดลเข้าใจอย่างชัดเจนว่าคุณต้องการอะไรและจะตอบอย่างไร -คิดเหมือนกับการให้คำสั่งเพื่อนร่วมงาน "แก้บั๊ก" นั้นคลุมเครือ แต่ "แก้ข้อผิดพลาด null pointer ในไฟล์ UserService.java บรรทัด 45 โดยเพิ่มการตรวจสอบ null" นั้นเจาะจง โมเดลภาษาใช้งานแบบเดียวกัน — ความชัดเจนและโครงสร้างมีความสำคัญ +ลองนึกถึงเหมือนการให้คำแนะนำเพื่อนร่วมงาน “แก้บั๊ก” เป็นคำสั่งที่คลุมเครือ “แก้ข้อผิดพลาด null pointer exception ใน UserService.java บรรทัด 45 โดยการเพิ่มการตรวจสอบ null” ชัดเจนกว่า โมเดลภาษาก็ทำงานแบบเดียวกัน — ความชัดเจนและโครงสร้างมีความสำคัญ -แผนภาพต่อไปนี้แสดงว่า LangChain4j เข้ากับภาพนี้อย่างไร — เชื่อมต่อรูปแบบ prompt ของคุณกับโมเดลผ่านบล็อกก่อสร้าง SystemMessage และ UserMessage +แผนภาพด้านล่างแสดงให้เห็นว่า LangChain4j เข้ากับภาพนี้อย่างไร — โดยการเชื่อมคำสั่ง prompt ของคุณกับโมเดลผ่านองค์ประกอบ SystemMessage และ UserMessage -How LangChain4j Fits +LangChain4j เข้ากันอย่างไร -LangChain4j จัดเตรียมโครงสร้างพื้นฐาน — การเชื่อมต่อโมเดล หน่วยความจำ และประเภทข้อความ — ในขณะที่รูปแบบ prompt คือข้อความที่ถูกจัดโครงสร้างอย่างรอบคอบซึ่งคุณส่งผ่านโครงสร้างพื้นฐานนั้น บล็อกก่อสร้างหลักคือ `SystemMessage` (ซึ่งตั้งค่าพฤติกรรมและบทบาทของ AI) และ `UserMessage` (ซึ่งถือคำขอจริงของคุณ) +LangChain4j ให้โครงสร้างพื้นฐาน — การเชื่อมต่อโมเดล หน่วยความจำ และประเภทข้อความ — ในขณะที่รูปแบบ prompt คือข้อความที่คุณจัดโครงสร้างอย่างระมัดระวังส่งผ่านโครงสร้างพื้นฐานนั้น บล็อกสำคัญคืิอ `SystemMessage` (ซึ่งกำหนดพฤติกรรมและบทบาทของ AI) และ `UserMessage` (ซึ่งบรรจุคำขอของคุณจริงๆ) -## พื้นฐานการออกแบบ Prompt +## พื้นฐานการออกแบบคำสั่ง -เทคนิคหลักห้าข้อที่แสดงด้านล่างเป็นรากฐานของการออกแบบ prompt อย่างมีประสิทธิภาพ แต่ละข้อแก้ไขด้านต่าง ๆ ของวิธีการสื่อสารกับโมเดลภาษา +เทคนิคหลักห้าข้อที่แสดงด้านล่างนี้เป็นรากฐานของการออกแบบคำสั่งที่มีประสิทธิภาพ แต่ละข้อเจาะจงด้านต่างๆ ของวิธีการสื่อสารกับโมเดลภาษา -Five Prompt Engineering Patterns Overview +ภาพรวมพื้นฐานการออกแบบคำสั่ง -ก่อนจะดำดิ่งสู่รูปแบบขั้นสูงในโมดูลนี้ มาทบทวนห้าเทคนิคการออกแบบ prompt พื้นฐานกันก่อน ซึ่งเป็นบล็อกก่อสร้างที่นักออกแบบ prompt ทุกคนควรรู้ หากคุณเคยทำ [โมดูลเริ่มต้นอย่างรวดเร็ว](../00-quick-start/README.md#2-prompt-patterns) มาก่อนแล้ว คุณจะเห็นเทคนิคเหล่านี้ถูกใช้งาน — นี่คือกรอบแนวคิดเบื้องหลัง +ก่อนจะลงลึกในรูปแบบขั้นสูงในโมดูลนี้ ให้ทบทวนเทคนิคตั้ง prompt พื้นฐานทั้งห้าข้อนี้ก่อน นี่คือบล็อกพื้นฐานที่นักออกแบบคำสั่งทุกคนควรรู้ ### Zero-Shot Prompting -วิธีที่ง่ายที่สุด: ให้โมเดลคำสั่งโดยตรงโดยไม่มีตัวอย่าง โมเดลจะพึ่งพาการฝึกฝนของมันทั้งหมดเพื่อเข้าใจและดำเนินการตามงาน วิธีนี้เหมาะสำหรับคำขอตรงไปตรงมาที่พฤติกรรมที่คาดหวังชัดเจน +วิธีที่ง่ายที่สุด: ให้คำสั่งตรงไปยังโมเดลโดยไม่มีตัวอย่าง โมเดลอาศัยการฝึกสอนของตัวเองทั้งหมดเพื่อเข้าใจและทำงานตามคำสั่งนี้ เหมาะสำหรับคำขอที่ตรงไปตรงมาที่พฤติกรรมที่คาดหวังชัดเจน Zero-Shot Prompting -*คำสั่งตรงโดยไม่มีตัวอย่าง — โมเดลคาดเดางานจากคำสั่งเท่านั้น* +*คำสั่งตรงโดยไม่มีตัวอย่าง — โมเดลจะสรุปงานจากคำสั่งนั้นเอง* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// การตอบกลับ: "บวก" +// การตอบสนอง: "เชิงบวก" ``` - -**เมื่อไรควรใช้:** การจัดประเภทง่าย ๆ คำถามโดยตรง การแปล หรือภารกิจใด ๆ ที่โมเดลสามารถจัดการได้โดยไม่มีคำชี้แนะเพิ่มเติม + +**เมื่อใช้:** การจัดประเภทง่ายๆ คำถามตรงๆ การแปลภาษา หรือทุกงานที่โมเดลจัดการได้โดยไม่ต้องมีคำแนะนำเพิ่มเติม ### Few-Shot Prompting -ให้ตัวอย่างที่แสดงรูปแบบที่คุณต้องการให้โมเดลปฏิบัติตาม โมเดลเรียนรู้รูปแบบอินพุต - เอาต์พุตที่คาดหวังจากตัวอย่างของคุณและใช้กับอินพุตใหม่ วิธีนี้ช่วยปรับปรุงความสม่ำเสมอสำหรับภารกิจที่รูปแบบหรือพฤติกรรมที่ต้องการไม่ชัดเจน +ให้ตัวอย่างเพื่อแสดงรูปแบบที่ต้องการให้โมเดลปฏิบัติตาม โมเดลเรียนรู้รูปแบบอินพุต-เอาต์พุตจากตัวอย่างและนำไปใช้กับข้อมูลใหม่ วิธีนี้ช่วยเพิ่มความสม่ำเสมออย่างมากสำหรับงานที่รูปแบบหรือพฤติกรรมที่ต้องการไม่ชัดเจน Few-Shot Prompting -*เรียนรู้จากตัวอย่าง — โมเดลจดจำรูปแบบและใช้กับอินพุตใหม่* +*เรียนรู้จากตัวอย่าง — โมเดลระบุรูปแบบและใช้กับข้อมูลใหม่* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**เมื่อไรควรใช้:** การจัดประเภทที่ปรับแต่งเอง การจัดรูปแบบอย่างสม่ำเสมอ ภารกิจเฉพาะโดเมน หรือเมื่อผลลัพธ์ zero-shot ไม่สม่ำเสมอ + +**เมื่อใช้:** การจัดประเภทแบบกำหนดเอง การจัดรูปแบบที่คงที่ งานเฉพาะทาง หรือเมื่อผลลัพธ์ zero-shot ไม่สม่ำเสมอ ### Chain of Thought -ขอให้โมเดลแสดงเหตุผลอย่างเป็นขั้นตอน แทนที่จะไปสู่คำตอบโดยตรง โมเดลจะแยกปัญหาและแก้ทีละส่วนอย่างชัดเจน วิธีนี้ช่วยปรับปรุงความถูกต้องสำหรับงานคณิตศาสตร์ ตรรกะ และเหตุผลหลายขั้นตอน +ขอให้โมเดลแสดงกระบวนการให้เหตุผลทีละขั้นตอน แทนที่จะตอบทันที โมเดลจะแยกปัญหาและทำงานผ่านแต่ละส่วนอย่างชัดเจน วิธีนี้ช่วยเพิ่มความแม่นยำในการแก้ปัญหาคณิตศาสตร์ ตรรกะ และการให้เหตุผลหลายขั้นตอน Chain of Thought Prompting -*เหตุผลทีละขั้นตอน — การแยกปัญหาซับซ้อนเป็นเหตุผลเชิงตรรกะที่ชัดเจน* +*การให้เหตุผลทีละขั้นตอน — แยกปัญหาซับซ้อนออกเป็นขั้นตอนตรรกะที่ชัดเจน* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// แบบจำลองแสดง: 15 - 8 = 7 แล้ว 7 + 12 = 19 แอปเปิ้ล +// แบบจำลองแสดง: 15 - 8 = 7 จากนั้น 7 + 12 = 19 แอปเปิ้ล ``` - -**เมื่อไรควรใช้:** ปัญหาคณิตศาสตร์ ปริศนาตรรกะ การดีบัก หรือภารกิจใด ๆ ที่การแสดงกระบวนการเหตุผลช่วยเพิ่มความแม่นยำและความเชื่อถือได้ + +**เมื่อใช้:** ปัญหาคณิตศาสตร์ ปริศนาตรรกะ การดีบั๊ก หรือทุกงานที่แสดงกระบวนการคิดช่วยเพิ่มความแม่นยำและความน่าเชื่อถือ ### Role-Based Prompting -ตั้งตัวตนหรือบทบาทแก่ AI ก่อนถามคำถาม นี่เป็นการให้บริบทที่กำหนดโทนเสียง ความลึก และจุดสนใจของคำตอบ "สถาปนิกซอฟต์แวร์" ให้คำแนะนำต่างจาก "นักพัฒนารุ่นเยาว์" หรือ "ผู้ตรวจสอบความปลอดภัย" +กำหนดบุคลิกหรือบทบาทของ AI ก่อนถามคำถาม วิธีนี้ให้บริบทที่กำหนดโทนเสียง ความลึก และจุดสนใจของคำตอบ “สถาปนิกซอฟต์แวร์” ให้คำแนะนำที่แตกต่างจาก “นักพัฒนาระดับจูเนียร์” หรือ “ผู้ตรวจสอบความปลอดภัย” Role-Based Prompting -*ตั้งบริบทและบุคลิก — คำถามเดียวกันได้รับคำตอบต่างกันตามบทบาทที่กำหนด* +*กำหนดบริบทและบุคลิก — คำถามเดียวกันได้รับคำตอบต่างกันตามบทบาทที่กำหนด* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**เมื่อไรควรใช้:** การตรวจสอบโค้ด การสอน การวิเคราะห์เฉพาะโดเมน หรือเมื่อคุณต้องการคำตอบที่ปรับแต่งตามระดับความชำนาญหรือมุมมอง + +**เมื่อใช้:** การตรวจสอบโค้ด การสอน การวิเคราะห์เฉพาะโดเมน หรือเมื่อคุณต้องการคำตอบที่ปรับให้เหมาะกับระดับความเชี่ยวชาญหรือมุมมองเฉพาะ ### Prompt Templates -สร้าง prompt ที่ใช้ซ้ำได้ด้วยตัวแปรเป็นที่ว่าง แทนที่จะเขียน prompt ใหม่ทุกครั้ง ให้กำหนดแม่แบบครั้งเดียวแล้วเติมค่าต่าง ๆ คลาส `PromptTemplate` ของ LangChain4j ช่วยให้ง่ายโดยใช้ไวยากรณ์ `{{variable}}` +สร้างคำสั่งที่นำกลับมาใช้ได้ซ้ำโดยมีตัวแปรแทนที่ แทนที่จะเขียนคำสั่งใหม่ทุกครั้ง ให้กำหนดแม่แบบครั้งเดียวแล้วแทนค่าตัวแปรต่างๆ คลาส `PromptTemplate` ของ LangChain4j ทำให้สิ่งนี้ง่ายด้วยไวยากรณ์ `{{variable}}` Prompt Templates -*Prompt ใช้ซ้ำได้ด้วยตัวแปร — แม่แบบเดียว ใช้งานได้หลายครั้ง* +*คำสั่งที่ใช้ซ้ำได้ด้วยตัวแปรแทนที่ — แม่แบบเดียว ใช้งานหลายครั้ง* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**เมื่อไรควรใช้:** การสืบค้นซ้ำด้วยอินพุตต่างกัน ประมวลผลเป็นชุด การสร้างเวิร์กโฟลว์ AI ที่ใช้ซ้ำได้ หรือทุกสถานการณ์ที่โครงสร้าง prompt ไม่เปลี่ยนแต่ข้อมูลเปลี่ยน + +**เมื่อใช้:** การสืบค้นซ้ำที่มีอินพุตแตกต่างกัน การประมวลผลเป็นชุด การสร้างเวิร์กโฟลว์ AI ที่นำกลับมาใช้ซ้ำได้ หรือทุกกรณีที่โครงสร้างคำสั่งเหมือนเดิมแต่ข้อมูลเปลี่ยน --- -พื้นฐานทั้งห้านี้ให้ชุดเครื่องมือมั่นคงสำหรับภารกิจ prompt ส่วนที่เหลือของโมดูลนี้ต่อยอดโดยใช้ **แปดรูปแบบขั้นสูง** ที่ใช้ประโยชน์จากการควบคุมเหตุผลของ GPT-5.2 การประเมินตนเอง และความสามารถผลลัพธ์มีโครงสร้าง +พื้นฐานห้าข้อนี้มอบชุดเครื่องมือที่มั่นคงสำหรับงานตั้ง prompt ส่วนที่เหลือของโมดูลนี้จะต่อยอดด้วย **รูปแบบขั้นสูงแปดแบบ** ที่ใช้ประโยชน์จากการควบคุมการให้เหตุผล การประเมินตนเอง และผลลัพธ์แบบมีโครงสร้างของ GPT-5.2 ## รูปแบบขั้นสูง -หลังจากครอบคลุมพื้นฐาน เรามาดูแปดรูปแบบขั้นสูงที่ทำให้โมดูลนี้โดดเด่น ปัญหาไม่จำเป็นต้องใช้วิธีเดียวกันทั้งหมด บางคำถามต้องการคำตอบเร็ว บางคำถามต้องการคิดลึกซึ้ง บางคำถามต้องการเหตุผลที่มองเห็นได้ บางคำถามต้องการแค่ผลลัพธ์ แต่ละรูปแบบด้านล่างปรับแต่งสำหรับสถานการณ์ต่าง ๆ — และการควบคุมเหตุผลของ GPT-5.2 ทำให้ความแตกต่างชัดเจนยิ่งขึ้น +เมื่อเข้าใจพื้นฐานแล้ว มาดูรูปแบบขั้นสูงแปดแบบที่ทำให้โมดูลนี้โดดเด่น ปัญหาไม่ใช่ทั้งหมดที่ต้องการวิธีแบบเดียวกัน บางคำถามต้องการคำตอบรวดเร็ว บางคำถามต้องการการคิดลึก บางคำถามต้องการเหตุผลที่เห็นได้ชัดเจน บางคำถามต้องการแค่ผลลัพธ์ รูปแบบแต่ละแบบด้านล่างนี้ถูกปรับแต่งสำหรับสถานการณ์ต่างๆ — และการควบคุมการให้เหตุผลของ GPT-5.2 ทำให้ความแตกต่างชัดเจนยิ่งขึ้น -Eight Prompting Patterns +รูปแบบการตั้งคำสั่งแปดแบบ -*ภาพรวมแปดรูปแบบการออกแบบ prompt และกรณีใช้งาน* +*ภาพรวมของแปดรูปแบบการออกแบบคำสั่งและกรณีใช้งาน* -GPT-5.2 เพิ่มมิติอีกอย่างให้รูปแบบเหล่านี้: *การควบคุมเหตุผล* สไลเดอร์ด้านล่างแสดงว่าคุณปรับความพยายามในการคิดของโมเดลได้อย่างไร — ตั้งแต่คำตอบรวดเร็วตรงไปตรงมาจนถึงการวิเคราะห์เชิงลึกละเอียดถี่ถ้วน +GPT-5.2 เพิ่มมิติอีกมิติหนึ่งให้กับรูปแบบเหล่านี้: *การควบคุมการให้เหตุผล* แถบเลื่อนด้านล่างแสดงว่าคุณสามารถปรับความพยายามในการคิดของโมเดลได้จากการตอบคำถามรวดเร็วตรงไปตรงมาจนถึงการวิเคราะห์อย่างลึกซึ้ง -Reasoning Control with GPT-5.2 +การควบคุมการให้เหตุผลกับ GPT-5.2 -*การควบคุมเหตุผลของ GPT-5.2 ช่วยให้คุณระบุระดับการคิดของโมเดลได้ — ตั้งแต่คำตอบที่รวดเร็วตรงไปตรงมาจนถึงการสำรวจอย่างละเอียดลึกซึ้ง* +*การควบคุมการให้เหตุผลของ GPT-5.2 ให้คุณระบุได้ว่าโมเดลควรคิดมากแค่ไหน — ตั้งแต่คำตอบตรงที่รวดเร็วจนถึงการสำรวจเชิงลึก* -**ความกระตือรือร้นต่ำ (เร็ว & มุ่งเน้น)** - สำหรับคำถามง่าย ๆ ที่ต้องการคำตอบเร็วและตรง โมเดลทำเหตุผลน้อยที่สุด — สูงสุด 2 ขั้นตอน ใช้กับการคำนวณ การค้นหา หรืองานที่ตรงไปตรงมา +**ความกระตือรือร้นต่ำ (ตอบเร็ว & ตรงประเด็น)** - สำหรับคำถามง่ายๆ ที่คุณต้องการคำตอบตรงและรวดเร็ว โมเดลใช้การคิดน้อยที่สุด — สูงสุด 2 ขั้นตอน ใช้สำหรับการคำนวณ การค้นหา หรือคำถามตรงๆ ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> 💡 **ทดลองกับ GitHub Copilot:** เปิด [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) และถาม: +> - "ความแตกต่างระหว่างรูปแบบ prompting ความกระตือรือร้นต่ำกับสูงคืออะไร?" +> - "แท็ก XML ใน prompt ช่วยจัดโครงสร้างการตอบของ AI อย่างไร?" +> - "เมื่อไรควรใช้รูปแบบสะท้อนตนเองแทนการสั่งตรงๆ?" -> 💡 **สำรวจกับ GitHub Copilot:** เปิด [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) และถามว่า: -> - "ความแตกต่างระหว่างรูปแบบ prompting ความกระตือรือร้นต่ำและสูงคืออะไร?" -> - "แท็ก XML ใน prompt ช่วยจัดโครงสร้างการตอบ AI อย่างไร?" -> - "เมื่อไรควรใช้รูปแบบสะท้อนตนเองและเมื่อไรควรใช้คำสั่งตรง?" - -**ความกระตือรือร้นสูง (ลึก & ละเอียด)** - สำหรับปัญหาซับซ้อนที่ต้องการการวิเคราะห์รอบด้าน โมเดลจะวิเคราะห์อย่างละเอียดและแสดงเหตุผลอย่างเจาะลึก ใช้กับการออกแบบระบบ การตัดสินใจสถาปัตยกรรม หรือการวิจัยซับซ้อน +**ความกระตือรือร้นสูง (คิดลึก & รอบด้าน)** - สำหรับปัญหาซับซ้อนที่ต้องการการวิเคราะห์ครอบคลุม โมเดลจะสำรวจอย่างละเอียดและแสดงกระบวนการให้เหตุผลอย่างลึกซึ้ง ใช้สำหรับการออกแบบระบบ การตัดสินใจด้านสถาปัตยกรรม หรือการวิจัยที่ซับซ้อน ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**การดำเนินการงาน (ความก้าวหน้าทีละขั้นตอน)** - สำหรับเวิร์กโฟลว์หลายขั้นตอน โมเดลจะวางแผนล่วงหน้า บรรยายแต่ละขั้นตอนระหว่างทำงาน จากนั้นสรุปผล ใช้กับการย้ายระบบ การติดตั้ง หรือกระบวนการหลายขั้นตอน + +**การปฏิบัติงานตามขั้นตอน (ความก้าวหน้าทีละขั้นตอน)** - สำหรับเวิร์กโฟลว์ที่มีหลายขั้นตอน โมเดลจะนำเสนอแผนล่วงหน้า บรรยายแต่ละขั้นตอนขณะทำงาน แล้วสรุปผล ใช้สำหรับการย้ายข้อมูล การนำไปใช้ หรือทุกกระบวนการที่มีหลายขั้นตอน ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +การตั้ง prompt แบบ Chain-of-Thought ขอให้โมเดลแสดงกระบวนการให้เหตุผล ซึ่งช่วยเพิ่มความแม่นยำสำหรับงานที่ซับซ้อน การแบ่งขั้นตอนช่วยให้ทั้งมนุษย์และ AI เข้าใจตรรกะ -การ prompting แบบ Chain-of-Thought ขอให้โมเดลแสดงกระบวนการเหตุผลอย่างชัดเจน ช่วยเพิ่มความถูกต้องสำหรับงานซับซ้อน การแยกเป็นขั้นตอนช่วยให้ทั้งมนุษย์และ AI เข้าใจตรรกะ - -> **🤖 ลองกับแชท [GitHub Copilot](https://github.com/features/copilot):** ถามเกี่ยวกับรูปแบบนี้ว่า: -> - "จะปรับรูปแบบการดำเนินการงานสำหรับงานที่ใช้เวลานานอย่างไร?" -> - "แนวปฏิบัติที่ดีที่สุดสำหรับการจัดโครงสร้างคำแนะนำเครื่องมือในแอปพลิเคชันจริงคืออะไร?" -> - "จะจับและแสดงความคืบหน้าช่วงกลางใน UI ได้อย่างไร?" +> **🤖 ลองกับ [GitHub Copilot](https://github.com/features/copilot) Chat:** ถามเกี่ยวกับรูปแบบนี้: +> - "จะปรับรูปแบบการทำงานขั้นตอนสำหรับงานที่ทำเวลานานได้อย่างไร?" +> - "แนวทางที่ดีที่สุดในการจัดโครงสร้างเครื่องมือเบื้องต้นในแอปพลิเคชันจริงคืออะไร?" +> - "จะจับและแสดงสถานะความก้าวหน้าระหว่างทางใน UI อย่างไร?" -แผนภาพด้านล่างแสดงเวิร์กโฟลว์แบบ วางแผน → ดำเนินการ → สรุป +แผนภาพด้านล่างแสดงเวิร์กโฟลว์แบบวางแผน → ดำเนินการ → สรุป -Task Execution Pattern +รูปแบบการทำงานตามขั้นตอน *เวิร์กโฟลว์ วางแผน → ดำเนินการ → สรุป สำหรับงานหลายขั้นตอน* -**โค้ดที่สะท้อนตนเอง** - สำหรับสร้างโค้ดคุณภาพสำหรับผลิตภัณฑ์ โมเดลสร้างโค้ดที่เป็นไปตามมาตรฐานการผลิตพร้อมการจัดการข้อผิดพลาดอย่างเหมาะสม ใช้เมื่อสร้างฟีเจอร์หรือบริการใหม่ +**โค้ดที่สะท้อนตนเอง** - สำหรับการสร้างโค้ดที่ใช้ในสภาพแวดล้อมจริง โมเดลจะสร้างโค้ดตามมาตรฐาน พร้อมการจัดการข้อผิดพลาดอย่างเหมาะสม ใช้เมื่อสร้างฟีเจอร์หรือบริการใหม่ ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +แผนภาพด้านล่างแสดงวงจรการปรับปรุงอย่างต่อเนื่อง — สร้าง, ประเมิน, ระบุจุดอ่อน, และปรับแต่งจนโค้ดได้มาตรฐาน -แผนภาพด้านล่างแสดงวงจรปรับปรุงอย่างต่อเนื่อง — สร้าง, ประเมิน, ระบุข้อบกพร่อง, ปรับปรุงจนโค้ดเข้าสู่มาตรฐานการผลิต +วงจรการสะท้อนตนเอง -Self-Reflection Cycle +*วงจรปรับปรุงซ้ำ — สร้าง, ประเมิน, ระบุปัญหา, ปรับปรุง, ทำซ้ำ* -*วงจรปรับปรุงอย่างต่อเนื่อง - สร้าง, ประเมิน, ระบุปัญหา, ปรับปรุง, ทำซ้ำ* - -**การวิเคราะห์อย่างมีโครงสร้าง** - สำหรับการประเมินอย่างสม่ำเสมอ โมเดลตรวจสอบโค้ดโดยใช้กรอบงานที่กำหนดไว้แล้ว (ความถูกต้อง, แนวปฏิบัติ, ประสิทธิภาพ, ความปลอดภัย, ความง่ายในการดูแลรักษา) ใช้กับการรีวิวโค้ดหรือการประเมินคุณภาพ +**การวิเคราะห์แบบมีโครงสร้าง** - สำหรับการประเมินที่สม่ำเสมอ โมเดลจะตรวจสอบโค้ดโดยใช้กรอบการทำงานที่ตายตัว (ถูกต้อง, แนวปฏิบัติ, ประสิทธิภาพ, ความปลอดภัย, การบำรุงรักษา) ใช้สำหรับการตรวจสอบโค้ดหรือตรวจสอบคุณภาพ ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +> **🤖 ลองกับ [GitHub Copilot](https://github.com/features/copilot) Chat:** ถามเกี่ยวกับการวิเคราะห์แบบมีโครงสร้าง: +> - "จะปรับแต่งกรอบการวิเคราะห์สำหรับการตรวจสอบโค้ดประเภทต่างๆ อย่างไร?" +> - "วิธีที่ดีที่สุดในการแยกวิเคราะห์และจัดการกับผลลัพธ์แบบมีโครงสร้างในโปรแกรมคืออะไร?" +> - "จะทำให้ระดับความร้ายแรงเหมือนกันในการตรวจสอบหลายรอบได้อย่างไร?" -> **🤖 ลองกับแชท [GitHub Copilot](https://github.com/features/copilot):** ถามเกี่ยวกับการวิเคราะห์อย่างมีโครงสร้างว่า: -> - "จะปรับแต่งกรอบการวิเคราะห์สำหรับการตรวจสอบโค้ดประเภทต่าง ๆ อย่างไร?" -> - "วิธีที่ดีที่สุดในการวิเคราะห์และดำเนินการกับผลลัพธ์ที่มีโครงสร้างทางโปรแกรมคืออะไร?" -> - "จะทำอย่างไรให้ระดับความรุนแรงคงที่ในแต่ละการตรวจสอบโค้ด?" - -แผนภาพต่อไปนี้แสดงกรอบงานที่จัดระเบียบการรีวิวโค้ดในหมวดหมู่ที่สม่ำเสมอพร้อมระดับความรุนแรง +แผนภาพต่อไปนี้แสดงกรอบงานที่จัดการการตรวจสอบโค้ดเป็นหมวดหมู่และระดับความร้ายแรงอย่างสม่ำเสมอ -Structured Analysis Pattern +รูปแบบการวิเคราะห์แบบมีโครงสร้าง -*กรอบงานสำหรับการรีวิวโค้ดที่สม่ำเสมอด้วยระดับความรุนแรง* +*กรอบการทำงานสำหรับการตรวจสอบโค้ดอย่างสม่ำเสมอพร้อมระดับความร้ายแรง* -**แชทหลายรอบ** - สำหรับบทสนทนาที่ต้องการบริบท โมเดลจดจำข้อความก่อนหน้าและพัฒนาต่อยอดจากนั้น ใช้สำหรับการช่วยเหลือเชิงโต้ตอบหรือ Q&A ที่ซับซ้อน +**แชทหลายรอบ** - สำหรับการสนทนาที่ต้องการบริบท โมเดลจะจดจำข้อความก่อนหน้าและสร้างต่อจากนั้น ใช้สำหรับการช่วยเหลือแบบตอบโต้หรือถามตอบซับซ้อน ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` + +แผนภาพด้านล่างแสดงภาพว่าบริบทการสนทนาเพิ่มขึ้นอย่างไรในแต่ละรอบ และสัมพันธ์กับขีดจำกัดจำนวนโทเค็นของโมเดล -แผนภาพด้านล่างแสดงวิธีสะสมบริบทการสนทนากับแต่ละรอบและความสัมพันธ์กับขีดจำกัดโทเค็นของโมเดล +หน่วยความจำบริบท -Context Memory +*วิธีที่บริบทการสนทนาสะสมผ่านหลายรอบจนถึงขีดจำกัดโทเค็น* -*วิธีที่บริบทการสนทนาสะสมในหลายรอบจนถึงขีดจำกัดโทเค็น* -**Step-by-Step Reasoning** - สำหรับปัญหาที่ต้องการตรรกะที่ชัดเจน โมเดลจะแสดงเหตุผลอย่างชัดเจนในแต่ละขั้นตอน ใช้แบบนี้สำหรับปัญหาคณิตศาสตร์ ปริศนาตรรกะ หรือเมื่อคุณต้องการเข้าใจกระบวนการคิด +**เหตุผลทีละขั้นตอน** - สำหรับปัญหาที่ต้องการตรรกะที่เห็นได้ชัด โมเดลจะแสดงกระบวนการให้เหตุผลทีละขั้นตอน ใช้กับปัญหาคณิตศาสตร์ ปริศนาตรรกะ หรือเมื่อคุณต้องการเข้าใจกระบวนการคิด ```java String prompt = """ @@ -397,14 +398,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +แผนภาพด้านล่างแสดงว่าโมเดลแบ่งปัญหาออกเป็นขั้นตอนตรรกะที่ระบุหมายเลขไว้อย่างชัดเจน -ภาพด้านล่างแสดงให้เห็นว่าโมเดลแบ่งปัญหาออกเป็นขั้นตอนตรรกะที่ชัดเจนและมีหมายเลขอย่างไร - -รูปแบบขั้นตอนทีละขั้นตอน - -*การแบ่งปัญหาออกเป็นขั้นตอนตรรกะที่ชัดเจน* +รูปแบบทีละขั้นตอน +*การแบ่งปัญหาออกเป็นขั้นตอนเชิงตรรกะอย่างชัดเจน* -**Constrained Output** - สำหรับการตอบที่มีข้อกำหนดรูปแบบเฉพาะ โมเดลจะปฏิบัติตามกฎรูปแบบและความยาวอย่างเคร่งครัด ใช้สิ่งนี้สำหรับการสรุปหรือเมื่อคุณต้องการโครงสร้างผลลัพธ์ที่แม่นยำ +**ผลลัพธ์แบบจำกัด** - สำหรับคำตอบที่มีข้อกำหนดรูปแบบเฉพาะ แบบจำลองจะปฏิบัติตามกฎรูปแบบและความยาวอย่างเคร่งครัด ใช้สิ่งนี้สำหรับบทสรุปหรือเมื่อคุณต้องการโครงสร้างผลลัพธ์ที่แม่นยำ ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -แผนภาพต่อไปนี้แสดงให้เห็นว่านโยบายข้อจำกัดจะช่วยควบคุมโมเดลให้ผลิตผลลัพธ์ที่เป็นไปตามรูปแบบและข้อกำหนดความยาวอย่างเข้มงวดอย่างไร +แผนภาพต่อไปนี้แสดงวิธีที่ข้อจำกัดช่วยแนะนำแบบจำลองให้สร้างผลลัพธ์ที่ปฏิบัติตามรูปแบบและข้อกำหนดความยาวของคุณอย่างเคร่งครัด -รูปแบบผลลัพธ์ที่จำกัด +Constrained Output Pattern -*การบังคับใช้รูปแบบ ความยาว และข้อกำหนดโครงสร้างเฉพาะ* +*การบังคับใช้ข้อกำหนดรูปแบบ ความยาว และโครงสร้างเฉพาะ* -## เรียกใช้งานแอปพลิเคชัน +## เรียกใช้แอปพลิเคชัน **ตรวจสอบการปรับใช้:** -ตรวจสอบให้แน่ใจว่าไฟล์ `.env` มีอยู่ในไดเรกทอรีรากพร้อมข้อมูลรับรอง Azure (สร้างไว้ในโมดูล 01) เรียกใช้จากไดเรกทอรีโมดูล (`02-prompt-engineering/`): +ตรวจสอบให้แน่ใจว่าไฟล์ `.env` มีอยู่ในโฟลเดอร์ root พร้อมข้อมูลรับรองของ Azure (สร้างในระหว่างโมดูล 01) เรียกใช้นี้จากโฟลเดอร์โมดูล (`02-prompt-engineering/`): **Bash:** ```bash @@ -444,27 +444,27 @@ Get-Content ..\.env # ควรแสดง AZURE_OPENAI_ENDPOINT, API_KEY, DEP **เริ่มต้นแอปพลิเคชัน:** -> **หมายเหตุ:** หากคุณเคยเริ่มแอปพลิเคชันทั้งหมดโดยใช้ `./start-all.sh` จากไดเรกทอรีราก (ตามที่อธิบายในโมดูล 01) โมดูลนี้จะทำงานอยู่แล้วที่พอร์ต 8083 คุณสามารถข้ามคำสั่งเริ่มต้นด้านล่างและไปที่ http://localhost:8083 ได้เลย +> **หมายเหตุ:** หากคุณได้เริ่มแอปพลิเคชันทั้งหมดแล้วโดยใช้ `./start-all.sh` จากโฟลเดอร์ root (ตามที่อธิบายในโมดูล 01) โมดูลนี้จะทำงานอยู่ที่พอร์ต 8083 แล้ว คุณสามารถข้ามคำสั่งเริ่มต้นด้านล่างและไปที่ http://localhost:8083 ได้เลย -**ทางเลือกที่ 1: ใช้ Spring Boot Dashboard (แนะนำสำหรับผู้ใช้ VS Code)** +**ตัวเลือกที่ 1: ใช้ Spring Boot Dashboard (แนะนำสำหรับผู้ใช้ VS Code)** -dev container มีส่วนขยาย Spring Boot Dashboard ที่ให้ส่วนติดต่อแบบภาพในการจัดการแอป Spring Boot ทั้งหมด คุณสามารถหามันได้ใน Activity Bar ด้านซ้ายของ VS Code (มองหาสัญลักษณ์ Spring Boot) +คอนเทนเนอร์ dev มีส่วนขยาย Spring Boot Dashboard ซึ่งมอบอินเทอร์เฟซแบบภาพเพื่อจัดการแอปพลิเคชัน Spring Boot ทั้งหมด คุณสามารถหาได้ในแถบกิจกรรมด้านซ้ายของ VS Code (ค้นหาไอคอน Spring Boot) จาก Spring Boot Dashboard คุณสามารถ: -- ดูแอป Spring Boot ทั้งหมดที่มีใน workspace -- เริ่ม/หยุดแอปด้วยคลิกเดียว -- ดูบันทึกแอปแบบเรียลไทม์ -- ตรวจสอบสถานะแอป +- ดูแอปพลิเคชัน Spring Boot ทั้งหมดใน workspace +- เริ่ม/หยุดแอปพลิเคชันด้วยการคลิกครั้งเดียว +- ดูบันทึกแอปพลิเคชันแบบเรียลไทม์ +- ตรวจสอบสถานะแอปพลิเคชัน -เพียงคลิกปุ่มเล่นข้าง "prompt-engineering" เพื่อเริ่มโมดูลนี้ หรือเริ่มทุกโมดูลพร้อมกันได้เลย +เพียงคลิกปุ่มเล่นข้าง "prompt-engineering" เพื่อเริ่มโมดูลนี้ หรือเริ่มโมดูลทั้งหมดพร้อมกัน Spring Boot Dashboard *Spring Boot Dashboard ใน VS Code — เริ่ม หยุด และตรวจสอบโมดูลทั้งหมดจากที่เดียว* -**ทางเลือกที่ 2: ใช้สคริปต์เชลล์** +**ตัวเลือกที่ 2: ใช้สคริปต์ shell** -เริ่มเว็บแอปทั้งหมด (โมดูล 01-04): +เริ่มแอปพลิเคชันเว็บทั้งหมด (โมดูล 01-04): **Bash:** ```bash @@ -474,11 +474,11 @@ cd .. # จากไดเรกทอรีรูท **PowerShell:** ```powershell -cd .. # จากไดเรกทอรีหลัก +cd .. # จากไดเรกทอรีรูท .\start-all.ps1 ``` -หรือเริ่มเฉพาะโมดูลนี้: +หรือเริ่มแค่โมดูลนี้: **Bash:** ```bash @@ -492,25 +492,25 @@ cd 02-prompt-engineering .\start.ps1 ``` -สคริปต์ทั้งสองจะโหลดตัวแปรแวดล้อมจากไฟล์ `.env` ในโฟลเดอร์รากโดยอัตโนมัติ และจะสร้างไฟล์ JAR ถ้าไฟล์ยังไม่มีอยู่ +ทั้งสองสคริปต์จะโหลดตัวแปรสภาพแวดล้อมจากไฟล์ `.env` ที่ root อัตโนมัติและจะสร้าง JAR หากยังไม่มีอยู่ -> **หมายเหตุ:** หากคุณต้องการสร้างทุกโมดูลด้วยตนเองก่อนเริ่ม: +> **หมายเหตุ:** หากคุณต้องการสร้างโมดูลทั้งหมดด้วยตนเองก่อนเริ่ม: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -เปิด http://localhost:8083 ในเบราเซอร์ของคุณ +เปิด http://localhost:8083 ในเบราว์เซอร์ของคุณ -**การหยุด:** +**เพื่อหยุด:** **Bash:** ```bash @@ -523,86 +523,86 @@ cd .. && ./stop-all.sh # ทุกโมดูล ```powershell .\stop.ps1 # โมดูลนี้เท่านั้น # หรือ -cd ..; .\stop-all.ps1 # ทุกโมดูล +cd ..; .\stop-all.ps1 # โมดูลทั้งหมด ``` -## ภาพหน้าจอของแอปพลิเคชัน +## ภาพหน้าจอแอปพลิเคชัน -นี่คือหน้าตาหลักของโมดูล prompt engineering ที่ให้คุณทดลองกับทั้งแปดรูปแบบเคียงข้างกัน +นี่คืออินเทอร์เฟซหลักของโมดูล prompt engineering ที่ซึ่งคุณสามารถทดลองกับรูปแบบทั้งแปดคู่ขนานกัน -หน้าแรกของแดชบอร์ด +Dashboard Home -*แดชบอร์ดหลักที่แสดงรูปแบบ prompt engineering ทั้ง 8 พร้อมคุณลักษณะและกรณีการใช้งาน* +*แดชบอร์ดหลักที่แสดงรูปแบบ prompt engineering ทั้ง 8 รูปแบบพร้อมคุณลักษณะและกรณีใช้งาน* -## สำรวจรูปแบบเหล่านี้ +## การสำรวจรูปแบบต่าง ๆ -เว็บอินเทอร์เฟซช่วยให้คุณทดลองกับกลยุทธ์การส่ง prompt ต่าง ๆ แต่ละรูปแบบแก้ปัญหาที่แตกต่างกัน — ลองดูว่าแต่ละแนวทางเหมาะเมื่อใด +อินเทอร์เฟซเว็บช่วยให้คุณทดลองใช้กลยุทธ์การ prompt ที่แตกต่างกัน แต่ละรูปแบบแก้ปัญหาที่แตกต่างกัน - ลองใช้เพื่อดูว่าเมื่อไหร่ที่แต่ละวิธีเหมาะสม -> **หมายเหตุ: สตรีมมิ่งกับไม่สตรีมมิ่ง** — ทุกหน้า pattern มีปุ่มสองปุ่ม: **🔴 Stream Response (Live)** และตัวเลือก **Non-streaming** สตรีมมิ่งใช้ Server-Sent Events (SSE) เพื่อแสดงโทเคนแบบเรียลไทม์เมื่อโมเดลกำลังสร้างคำตอบ คุณจะเห็นความคืบหน้าทันที ตัวเลือกไม่สตรีมรอฟังคำตอบทั้งหมดก่อนจึงแสดง สำหรับ prompt ที่ต้องการเหตุผลเชิงลึก (เช่น High Eagerness, Self-Reflecting Code) การเรียกแบบไม่สตรีมอาจใช้เวลานานมาก — บางครั้งเป็นนาที — โดยไม่มีการตอบรับใด ๆ **ใช้แบบสตรีมมิ่งเมื่อทดลองกับ prompt ที่ซับซ้อน** เพื่อที่คุณจะเห็นโมเดลทำงานและหลีกเลี่ยงความรู้สึกว่าคำขอหมดเวลาลง +> **หมายเหตุ: สตรีมมิ่งกับไม่สตรีมมิ่ง** — แต่ละหน้าของรูปแบบจะมีปุ่มสองปุ่ม: **🔴 สตรีมการตอบกลับ (สด)** กับตัวเลือก **ไม่สตรีมมิ่ง** สตรีมมิ่งใช้ Server-Sent Events (SSE) เพื่อแสดง token แบบเรียลไทม์ขณะที่แบบจำลองสร้างผลลัพธ์ ทำให้คุณเห็นความก้าวหน้าทันที ตัวเลือกไม่สตรีมมิ่งจะรอจนกว่าจะได้รับคำตอบทั้งหมดก่อนแสดง สำหรับ prompt ที่ทำให้เกิดการคิดเชิงลึก (เช่น High Eagerness, Self-Reflecting Code) การเรียกแบบไม่สตรีมมิ่งอาจใช้เวลานาน — บางครั้งเป็นนาที — โดยไม่มีข้อมูลย้อนกลับให้เห็น **ใช้สตรีมมิ่งเมื่อต้องทดลองกับ prompt ที่ซับซ้อน** เพื่อให้คุณเห็นแบบจำลองทำงานและหลีกเลี่ยงความรู้สึกว่าการร้องขอหมดเวลา > -> **หมายเหตุ: ความต้องการเบราเซอร์** — ฟีเจอร์สตรีมมิ่งใช้ Fetch Streams API (`response.body.getReader()`) ซึ่งต้องใช้เบราเซอร์เต็มรูปแบบ (Chrome, Edge, Firefox, Safari) ไม่สามารถทำงานใน Simple Browser ที่ฝังใน VS Code ได้ เนื่องจาก webview ของมันไม่รองรับ ReadableStream API หากใช้ Simple Browser ปุ่มไม่สตรีมยังทำงานตามปกติ — มีผลเฉพาะปุ่มสตรีมเท่านั้น เปิด `http://localhost:8083` ในเบราเซอร์ภายนอกเพื่อประสบการณ์เต็มรูปแบบ +> **หมายเหตุ: เบราว์เซอร์ที่ใช้** — ฟีเจอร์สตรีมมิ่งใช้ Fetch Streams API (`response.body.getReader()`) ซึ่งต้องใช้เบราว์เซอร์เต็มรูปแบบ (Chrome, Edge, Firefox, Safari) และไม่ทำงานบน Simple Browser ที่มาพร้อมกับ VS Code เพราะ webview ของมันไม่รองรับ ReadableStream API หากคุณใช้ Simple Browser ปุ่มไม่สตรีมมิ่งจะยังใช้งานได้ตามปกติ — มีผลกระทบกับแค่ปุ่มสตรีมมิ่ง เปิด `http://localhost:8083` ในเบราว์เซอร์ภายนอกเพื่อประสบการณ์เต็มรูปแบบ -### ความเร่งรีบต่ำและสูง (Low vs High Eagerness) +### ความกระตือรือร้นต่ำกับสูง -ถามคำถามง่าย ๆ เช่น "15% ของ 200 คืออะไร?" ด้วยโหมด Low Eagerness คุณจะได้คำตอบทันทีและตรงไปตรงมา ลองถามอะไรซับซ้อนมากขึ้น เช่น "ออกแบบกลยุทธ์แคชสำหรับ API ที่มีการเข้าชมสูง" ด้วย High Eagerness คลิก **🔴 Stream Response (Live)** และดูเหตุผลละเอียดของโมเดลทีละโทเคน โมเดลเดียวกัน โครงสร้างคำถามเหมือนกัน — แต่ prompt บอกว่าให้คิดมากแค่ไหน +ถามคำถามง่ายๆ เช่น "15% ของ 200 คือเท่าไหร่?" โดยใช้ความกระตือรือร้นต่ำ คุณจะได้รับคำตอบที่รวดเร็วและตรงจุด ตอนนี้ลองถามคำถามซับซ้อนเช่น "ออกแบบกลยุทธ์การแคชสำหรับ API ที่มีการเข้าใช้สูง" โดยใช้ความกระตือรือร้นสูง คลิก **🔴 สตรีมการตอบกลับ (สด)** และดูการคิดเชิงลึกของแบบจำลองแสดงผลทีละ token แบบเดียวกัน แบบคำถามเดียวกันแตกต่างที่ prompt บอกให้คิดมากน้อยแค่ไหน ### การดำเนินงานตามงาน (Tool Preambles) -เวิร์กโฟลว์หลายขั้นตอนได้ประโยชน์จากการวางแผนล่วงหน้าและบรรยายความคืบหน้า โมเดลสรุปสิ่งที่จะทำ บรรยายแต่ละขั้นตอน แล้วสรุปผลลัพธ์ +เวิร์กโฟลว์หลายขั้นตอนได้ประโยชน์จากการวางแผนล่วงหน้าและการบรรยายความก้าวหน้า แบบจำลองจะสรุปว่าจะทำอะไร บรรยายแต่ละขั้นตอน แล้วสรุปผลลัพธ์ -### โค้ดที่สะท้อนตนเอง (Self-Reflecting Code) +### โค้ดที่สะท้อนตนเอง -ลอง "สร้างบริการตรวจสอบอีเมล" แทนที่จะสร้างโค้ดและหยุด โมเดลจะสร้าง ประเมินตามเกณฑ์คุณภาพ ระบุจุดอ่อน และปรับปรุง คุณจะเห็นมันทำซ้ำจนโค้ดตรงตามมาตรฐานการผลิต +ลองถาม "สร้างบริการตรวจสอบอีเมล" แทนที่จะสร้างโค้ดแล้วหยุด แบบจำลองจะสร้างโค้ด ประเมินตามเกณฑ์คุณภาพ ระบุจุดอ่อน และปรับปรุง คุณจะเห็นมันวนซ้ำจนโค้ดได้มาตรฐานพร้อมใช้งานจริง -### การวิเคราะห์ที่มีโครงสร้าง (Structured Analysis) +### การวิเคราะห์แบบมีโครงสร้าง -การตรวจสอบโค้ดต้องมีกรอบการประเมินที่สม่ำเสมอ โมเดลวิเคราะห์โค้ดโดยใช้หมวดหมู่ที่กำหนดไว้ (ความถูกต้อง, แนวปฏิบัติ, ประสิทธิภาพ, ความปลอดภัย) พร้อมระดับความรุนแรง +การรีวิวโค้ดต้องใช้กรอบการประเมินที่สม่ำเสมอ แบบจำลองวิเคราะห์โค้ดโดยใช้หมวดหมู่ตายตัว (ถูกต้องแนวปฏิบัติ ประสิทธิภาพ ความปลอดภัย) พร้อมระดับความรุนแรง -### การแชทหลายตา (Multi-Turn Chat) +### แชทแบบหลายรอบ -ถาม "Spring Boot คืออะไร?" แล้วตามด้วย "ขอให้แสดงตัวอย่าง" โมเดลจะจดจำคำถามแรกและให้ตัวอย่าง Spring Boot เฉพาะเจาะจง ถ้าไม่มีหน่วยความจำ คำถามที่สองจะกว้างเกินไป +ถาม "Spring Boot คืออะไร?" จากนั้นถามต่อทันทีว่า "แสดงตัวอย่างให้ดูหน่อย" แบบจำลองจะจำคำถามแรกและให้ตัวอย่าง Spring Boot เฉพาะเจาะจง หากไม่มีความจำ คำถามที่สองจะกว้างเกินไป -### Step-by-Step Reasoning +### การคิดเชิงตรรกะแบบขั้นตอนต่อขั้นตอน -เลือกปัญหาคณิตศาสตร์และลองทั้ง Step-by-Step Reasoning และ Low Eagerness โหมด Low Eagerness ให้คำตอบอย่างรวดเร็วแต่ไม่แสดงเหตุผล ส่วนแบบ Step-by-step จะโชว์การคำนวณและการตัดสินใจทุกขั้นตอน +เลือกโจทย์คณิตศาสตร์แล้วลองใช้ทั้งสองวิธี Step-by-Step Reasoning และ Low Eagerness ความกระตือรือร้นต่ำจะให้คำตอบอย่างรวดเร็วแต่ไม่แสดงขั้นตอน ส่วนแบบขั้นตอนต่อขั้นตอนจะโชว์ทุกการคำนวณและการตัดสินใจ -### Constrained Output +### ผลลัพธ์แบบจำกัด -เมื่อคุณต้องการรูปแบบเฉพาะหรือจำนวนคำที่แน่นอน รูปแบบนี้จะบังคับให้เป็นไปตามนั้นโดยเคร่งครัด ลองสร้างสรุปที่มี 100 คำตามรูปแบบหัวข้อย่อย +เมื่อคุณต้องการรูปแบบหรือจำนวนคำที่เจาะจง รูปแบบนี้จะบังคับให้ปฏิบัติตามอย่างเคร่งครัด ลองสร้างบทสรุปที่มีคำจำนวน 100 คำในรูปแบบหัวข้อย่อย ## สิ่งที่คุณกำลังเรียนรู้จริง ๆ -**ความพยายามในการให้เหตุผลเปลี่ยนทุกอย่าง** +**ความพยายามในการคิดเปลี่ยนทุกอย่าง** -GPT-5.2 ให้คุณควบคุมความพยายามในการคำนวณผ่าน prompt ของคุณ ความพยายามต่ำหมายถึงตอบสนองเร็วด้วยการสำรวจน้อย ความพยายามสูงหมายถึงโมเดลใช้เวลาคิดเชิงลึก คุณกำลังเรียนรู้ที่จะจับคู่ความพยายามกับความซับซ้อนของงาน — อย่าเสียเวลาคำถามง่าย ๆ แต่ก็อย่ารีบตัดสินใจในเรื่องซับซ้อน +GPT-5.2 ให้คุณควบคุมความพยายามในการประมวลผลผ่าน prompt ของคุณ ความพยายามต่ำหมายถึงคำตอบที่รวดเร็วและสำรวจน้อย ความพยายามสูงหมายถึงแบบจำลองใช้เวลาในการคิดอย่างลึกซึ้ง คุณกำลังเรียนรู้ที่จะจับคู่ความพยายามกับความซับซ้อนของงาน — อย่าเสียเวลากับคำถามง่าย ๆ แต่ก็อย่าเร่งการตัดสินใจที่ซับซ้อนเกินไป -**โครงสร้างชี้นำพฤติกรรม** +**โครงสร้างนำพฤติกรรม** -สังเกตแท็ก XML ใน prompt ไหม? มันไม่ใช่แค่ของตกแต่ง โมเดลจะปฏิบัติตามคำสั่งที่มีโครงสร้างได้ไวกว่าแบบข้อความอิสระ เมื่อคุณต้องการกระบวนการหลายขั้นตอนหรือเหตุผลซับซ้อน โครงสร้างช่วยให้โมเดลติดตามตำแหน่งและสิ่งที่จะทำต่อไปได้ แผนภาพด้านล่างแสดงการแบ่ง prompt ที่มีโครงสร้างดี โดยใช้แท็กอย่าง ``, ``, ``, ``, และ `` เพื่อจัดระเบียบคำสั่งของคุณเป็นส่วน ๆ อย่างชัดเจน +สังเกตแท็ก XML ใน prompt หรือไม่? มันไม่ใช่แค่การตกแต่ง แบบจำลองจะปฏิบัติตามคำสั่งแบบมีโครงสร้างได้แม่นยำกว่าข้อความเสรี เมื่อคุณต้องการกระบวนการหลายขั้นตอนหรือโลจิกซับซ้อน โครงสร้างจะช่วยให้แบบจำลองติดตามตำแหน่งและขั้นตอนถัดไปได้ แผนภาพด้านล่างแจกแจง prompt ที่มีโครงสร้างดี แสดงว่าแท็ก เช่น ``, ``, ``, ``, และ `` ช่วยจัดคำสั่งของคุณเป็นส่วน ๆ ที่ชัดเจน -โครงสร้างของ prompt +Prompt Structure -*โครงสร้างของ prompt ที่จัดอย่างดีพร้อมส่วนต่าง ๆ ชัดเจนและการจัดระเบียบแบบ XML* +*โครงสร้างของ prompt ที่มีโครงสร้างดีพร้อมส่วนที่ชัดเจนและการจัดการแบบ XML* **คุณภาพผ่านการประเมินตนเอง** -รูปแบบที่สะท้อนตนเองทำงานโดยระบุเกณฑ์คุณภาพอย่างชัดเจน แทนที่จะหวังว่าโมเดลจะ "ทำถูก" คุณบอกมันเลยว่า "ถูก" หมายถึงอะไร: ตรรกะถูกต้อง, จัดการข้อผิดพลาด, ประสิทธิภาพ, ความปลอดภัย โมเดลจึงสามารถประเมินผลลัพธ์ตัวเองและปรับปรุงได้ นี่เปลี่ยนการสร้างโค้ดจากการเสี่ยงโชคเป็นกระบวนการจริงจัง +รูปแบบสะท้อนตนเองทำงานโดยการระบุเกณฑ์คุณภาพอย่างชัดเจน แทนที่จะหวังว่าแบบจำลองจะ "ทำได้ถูกต้อง" คุณบอกแบบจำลองว่า "ถูกต้อง" หมายถึงอย่างไร: ตรรกะที่ถูกต้อง การจัดการข้อผิดพลาด ประสิทธิภาพ ความปลอดภัย จากนั้นแบบจำลองจะประเมินผลลัพธ์ของตัวเองและปรับปรุง นี่ทำให้การสร้างโค้ดเปลี่ยนจากการเสี่ยงโชคเป็นกระบวนการ -**บริบทมีขอบเขต** +**บริบทมีขีดจำกัด** -การสนทนาหลายตาทำงานโดยเก็บประวัติข้อความทุกคำขอ แต่มีขีดจำกัด — ทุกโมเดลมีจำนวนโทเคนสูงสุด เมื่อบทสนทนาโตขึ้น คุณต้องมีกลยุทธ์เก็บบริบทที่เกี่ยวข้องโดยไม่เกินขีดจำกัด โมดูลนี้สอนวิธีการทำงานของหน่วยความจำ; ต่อไปคุณจะเรียนรู้ว่าเมื่อไรควรสรุป, ลืม หรือเรียกคืนข้อมูล +บทสนทนาแบบหลายรอบทำงานด้วยการรวมประวัติข้อความกับแต่ละคำขอ แต่มีขีดจำกัด—ทุกแบบจำลองมีจำนวนโทเคนสูงสุด เมื่อบทสนทนายาวขึ้นคุณจะต้องมีวิธีเก็บบริบทที่เกี่ยวข้องโดยไม่เกินขีดจำกัดนี้ โมดูลนี้แสดงให้เห็นว่า memory ทำงานอย่างไร และต่อไปคุณจะได้เรียนรู้ว่าเมื่อไหร่ควรสรุป เมื่อไหร่ควรลืม และเมื่อไหร่ควรดึงข้อมูลคืน -## ขั้นตอนถัดไป +## ขั้นตอนต่อไป **โมดูลถัดไป:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**การนำทาง:** [← ก่อนหน้า: โมดูล 01 - บทนำ](../01-introduction/README.md) | [กลับสู่หน้าหลัก](../README.md) | [ถัดไป: โมดูล 03 - RAG →](../03-rag/README.md) +**นำทาง:** [← ก่อนหน้า: โมดูล 01 - บทนำ](../01-introduction/README.md) | [กลับสู่หน้าหลัก](../README.md) | [ถัดไป: โมดูล 03 - RAG →](../03-rag/README.md) --- -**ข้อจำกัดความรับผิดชอบ**: -เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษาด้วย AI [Co-op Translator](https://github.com/Azure/co-op-translator) แม้เราจะพยายามให้มีความถูกต้อง แต่โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่แม่นยำ เอกสารต้นฉบับในภาษาดั้งเดิมควรถือเป็นแหล่งข้อมูลที่ถูกต้อง สำหรับข้อมูลที่สำคัญ ขอแนะนำให้ใช้บริการแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดใด ๆ ที่เกิดจากการใช้การแปลนี้ +**ปฏิเสธความรับผิดชอบ**: +เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) ขณะที่เราพยายามให้ความถูกต้อง โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดที่เกิดขึ้นจากการใช้การแปลนี้ \ No newline at end of file diff --git a/translations/th/03-rag/README.md b/translations/th/03-rag/README.md index eb6b10518..e72ebf819 100644 --- a/translations/th/03-rag/README.md +++ b/translations/th/03-rag/README.md @@ -2,143 +2,142 @@ ## Table of Contents -- [Video Walkthrough](../../../03-rag) -- [What You'll Learn](../../../03-rag) -- [Prerequisites](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Does This Tutorial Use?](../../../03-rag) -- [How It Works](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload a Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matters](../../../03-rag) -- [Next Steps](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding RAG](#understanding-rag) + - [Which RAG Approach Does This Tutorial Use?](#which-rag-approach-does-this-tutorial-use) +- [How It Works](#how-it-works) + - [Document Processing](#document-processing) + - [Creating Embeddings](#creating-embeddings) + - [Semantic Search](#semantic-search) + - [Answer Generation](#การสร้างคำตอบ) +- [Run the Application](#รันแอปพลิเคชัน) +- [Using the Application](#การใช้แอปพลิเคชัน) + - [Upload a Document](#อัปโหลดเอกสาร) + - [Ask Questions](#ถามคำถาม) + - [Check Source References](#ตรวจสอบการอ้างอิงแหล่งที่มา) + - [Experiment with Questions](#ทดลองถามคำถามต่าง-ๆ) +- [Key Concepts](#แนวคิดสำคัญ) + - [Chunking Strategy](#ยุทธศาสตร์การแบ่งชิ้น) + - [Similarity Scores](#คะแนนความคล้ายคลึง) + - [In-Memory Storage](#การเก็บข้อมูลในหน่วยความจำ) + - [Context Window Management](#การจัดการหน้าต่างบริบท) +- [When RAG Matters](#เมื่อไหร่ที่-rag-มีความสำคัญ) +- [Next Steps](#ก้าวต่อไป) ## Video Walkthrough -ชมเซสชันสดนี้ซึ่งอธิบายวิธีเริ่มต้นกับโมดูลนี้: +ชมการสาธิตสดนี้ที่อธิบายวิธีเริ่มต้นกับโมดูลนี้: RAG with LangChain4j - Live Session ## What You'll Learn -ในโมดูลก่อนหน้านี้ คุณได้เรียนรู้วิธีการสนทนากับ AI และจัดโครงสร้าง prompt อย่างมีประสิทธิภาพ แต่สิ่งหนึ่งที่จำกัดโดยพื้นฐานคือ: โมเดลภาษาเรียนรู้ได้เฉพาะสิ่งที่ได้รับการฝึกฝนไว้เท่านั้น มันไม่สามารถตอบคำถามเกี่ยวกับนโยบายบริษัทของคุณ เอกสารโครงการของคุณ หรือข้อมูลอื่นใดที่ไม่ได้ฝึกสอนมา +ในโมดูลก่อนหน้า คุณได้เรียนรู้วิธีพูดคุยกับ AI และจัดโครงสร้างคำสั่งอย่างมีประสิทธิภาพ แต่มีข้อจำกัดพื้นฐาน: โมเดลภาษาเพียงรู้ในสิ่งที่เรียนรู้ระหว่างการฝึกเท่านั้น มันไม่สามารถตอบคำถามเกี่ยวกับนโยบายบริษัทของคุณ เอกสารโครงการของคุณ หรือข้อมูลใด ๆ ที่ไม่ได้ถูกฝึกมา -RAG (Retrieval-Augmented Generation) แก้ปัญหานี้ แทนที่จะพยายามสอนโมเดลด้วยข้อมูลของคุณ (ซึ่งมีค่าใช้จ่ายสูงและไม่สะดวก) คุณให้มันสามารถค้นหาข้อมูลในเอกสารของคุณได้ เมื่อมีคนถามคำถาม ระบบจะค้นหาข้อมูลที่เกี่ยวข้องและรวมข้อมูลนั้นเข้าไปใน prompt แล้วโมเดลจะตอบโดยอิงจากบริบทที่ดึงมาได้ +RAG (Retrieval-Augmented Generation) แก้ปัญหานี้ แทนที่จะพยายามสอนโมเดลด้วยข้อมูลของคุณ (ซึ่งแพงและไม่ใช่เรื่องปฏิบัติได้) คุณให้มันสามารถค้นหาข้อมูลจากเอกสารของคุณ เมื่อใครสักคนถามคำถาม ระบบจะหาข้อมูลที่เกี่ยวข้องและรวมไว้ในคำสั่ง โมเดลจึงตอบตามบริบทที่ถูกดึงมา -คิดว่า RAG คือการสร้างห้องสมุดอ้างอิงให้โมเดล เมื่อคุณถามคำถาม ระบบจะทำตามขั้นตอนนี้: +คิดว่า RAG เป็นการให้โมเดลมีห้องสมุดอ้างอิง เมื่อคุณถามคำถาม ระบบจะ: 1. **User Query** - คุณถามคำถาม -2. **Embedding** - แปลงคำถามเป็นเวกเตอร์ -3. **Vector Search** - ค้นหาชิ้นส่วนเอกสารที่มีความคล้ายคลึง -4. **Context Assembly** - เพิ่มชิ้นส่วนที่เกี่ยวข้องไปใน prompt -5. **Response** - LLM สร้างคำตอบโดยอิงจากบริบทนั้น +2. **Embedding** - แปลงคำถามของคุณเป็นเวกเตอร์ +3. **Vector Search** - หาชิ้นส่วนเอกสารที่เหมือนกัน +4. **Context Assembly** - เติมชิ้นส่วนที่เกี่ยวข้องเข้าไปในคำสั่ง +5. **Response** - LLM สร้างคำตอบตามบริบทนั้น -วิธีนี้ช่วยให้คำตอบของโมเดลยึดติดกับข้อมูลจริงของคุณ แทนที่จะพึ่งพาความรู้จากการฝึกฝนหรือการสร้างคำตอบขึ้นมาเอง +สิ่งนี้ช่วยให้คำตอบของโมเดลมีฐานในข้อมูลจริงของคุณแทนที่จะพึ่งพาความรู้ที่ได้จากการฝึกหรือสร้างคำตอบขึ้นมาเอง ## Prerequisites -- ผ่าน [Module 00 - Quick Start](../00-quick-start/README.md) (สำหรับตัวอย่าง Easy RAG ที่อ้างอิงในโมดูลนี้) -- ผ่าน [Module 01 - Introduction](../01-introduction/README.md) (ได้ติดตั้งทรัพยากร Azure OpenAI แล้ว รวมถึงโมเดล embedding `text-embedding-3-small`) -- มีไฟล์ `.env` ในไดเรกทอรีราก พร้อมข้อมูลรับรอง Azure (สร้างโดยคำสั่ง `azd up` ใน Module 01) +- เสร็จสิ้น [Module 01 - Introduction](../01-introduction/README.md) (ทรัพยากร Azure OpenAI ถูกปรับใช้ รวมถึงโมเดลฝังตัว `text-embedding-3-small`) +- มีไฟล์ `.env` ในไดเรกทอรีหลักพร้อมข้อมูลรับรอง Azure (สร้างโดยคำสั่ง `azd up` ใน Module 01) -> **Note:** หากยังไม่ได้ทำ Module 01 ให้ทำตามคำแนะนำการติดตั้งที่นั่นก่อน คำสั่ง `azd up` จะติดตั้งทั้งโมเดลแชท GPT และโมเดล embedding ที่ใช้ในโมดูลนี้ +> **Note:** หากคุณยังไม่เสร็จ Module 01 กรุณาทำตามคำแนะนำการปรับใช้ที่นั่นก่อน คำสั่ง `azd up` จะปรับใช้โมเดลแชท GPT และโมเดลฝังตัวที่โมดูลนี้ใช้ ## Understanding RAG -แผนภาพด้านล่างแสดงแนวคิดหลัก: แทนที่จะพึ่งพาข้อมูลฝึกฝนของโมเดลเพียงอย่างเดียว RAG ให้อ้างอิงห้องสมุดจากเอกสารของคุณเพื่อให้โมเดลตรวจสอบก่อนสร้างคำตอบแต่ละครั้ง +แผนภาพด้านล่างแสดงแนวคิดหลัก: แทนที่จะพึ่งพาข้อมูลการฝึกของโมเดลเพียงอย่างเดียว RAG ให้โมเดลมีห้องสมุดอ้างอิงจากเอกสารของคุณเพื่อปรึกษาก่อนสร้างคำตอบแต่ละครั้ง What is RAG -*แผนภาพนี้แสดงความแตกต่างระหว่าง LLM ปกติ (ที่เดาจากข้อมูลฝึกฝน) กับ LLM ที่เสริมด้วย RAG (ที่ตรวจสอบเอกสารของคุณก่อน)* +*แผนภาพนี้แสดงความแตกต่างระหว่าง LLM ปกติ (เดาจากข้อมูลการฝึก) กับ LLM ที่มี RAG (ปรึกษาเอกสารของคุณก่อน)* -นี่คือการเชื่อมต่อของแต่ละส่วนแบบครบวงจร ขั้นตอนการทำงานของคำถามผู้ใช้ไล่จากการ embedding, ค้นหาเวกเตอร์, การประกอบบริบท และการสร้างคำตอบ — แต่ละขั้นสร้างต่อจากขั้นก่อนหน้า: +นี่คือการเชื่อมต่อส่วนประกอบตั้งแต่ต้นจนจบ คำถามของผู้ใช้ไหลผ่านสี่ขั้นตอน — การฝังตัว, การค้นหาเวกเตอร์, การประกอบบริบท, และการสร้างคำตอบ — ทุกขั้นตอนสร้างต่อกัน: RAG Architecture -*แผนภาพนี้แสดงไลน์การทำงาน RAG แบบครบวงจร — คำถามผู้ใช้ไหลผ่าน embedding, ค้นหาเวกเตอร์, ประกอบบริบท และสร้างคำตอบ* +*แผนภาพนี้แสดงกระบวนการ RAG ตั้งแต่ต้นจนจบ — คำถามของผู้ใช้ไหลผ่านการฝังตัว, การค้นหาเวกเตอร์, การประกอบบริบท, และการสร้างคำตอบ* -ส่วนที่เหลือของโมดูลนี้จะเดินผ่านแต่ละขั้นตอนโดยละเอียด พร้อมโค้ดที่จะรันและแก้ไขได้ +ส่วนที่เหลือของโมดูลนี้จะอธิบายแต่ละขั้นตอนโดยละเอียด พร้อมด้วยโค้ดที่คุณสามารถรันและแก้ไขได้ ### Which RAG Approach Does This Tutorial Use? -LangChain4j มีสามวิธีในการใช้ RAG โดยแต่ละวิธีมีระดับนามธรรมต่างกัน แผนภาพด้านล่างเปรียบเทียบแต่ละวิธี: +LangChain4j มีวิธีการใช้ RAG สามวิธี แต่ละวิธีมีระดับนามธรรมแตกต่างกัน แผนภาพด้านล่างเปรียบเทียบแต่ละวิธีใบข้างกัน: Three RAG Approaches in LangChain4j -*แผนภาพนี้เปรียบเทียบสามวิธี RAG ของ LangChain4j — Easy, Native และ Advanced — แสดงส่วนประกอบหลักและเวลาที่ควรใช้แต่ละวิธี* +*แผนภาพนี้เปรียบเทียบสามวิธี RAG ใน LangChain4j — Easy, Native, และ Advanced — แสดงส่วนประกอบหลักและช่วงเวลาที่ควรใช้* | Approach | What It Does | Trade-off | |---|---|---| -| **Easy RAG** | เชื่อมต่อทุกอย่างอัตโนมัติผ่าน `AiServices` และ `ContentRetriever` คุณเพียงแค่ใส่ annotation ให้กับ interface, แนบ retriever แล้ว LangChain4j จะจัดการ embedding, ค้นหา และประกอบ prompt ให้เอง | โค้ดน้อย แต่คุณจะไม่เห็นรายละเอียดของแต่ละขั้นตอน | -| **Native RAG** | คุณเรียกใช้โมเดล embedding, ค้นหาใน store, สร้าง prompt และสร้างคำตอบทีละขั้นตอนอย่างชัดเจน | โค้ดมากขึ้น แต่คุณเห็นและแก้ไขได้ในทุกขั้นตอน | -| **Advanced RAG** | ใช้ `RetrievalAugmentor` framework ที่รองรับตัวแปลงคำถาม, ตัวจัดเส้นทาง, ตัวจัดอันดับใหม่ และตัวฉีดเนื้อหา สำหรับงานสเกลโปรดักชัน | ยืดหยุ่นสูงสุด แต่มีความซับซ้อนมาก | +| **Easy RAG** | เชื่อมทุกอย่างโดยอัตโนมัติผ่าน `AiServices` และ `ContentRetriever` คุณทำการระบุ interface, แนบ retriever, แล้ว LangChain4j ดูแลการฝังตัว, การค้นหา, และการประกอบคำสั่งเบื้องหลัง | โค้ดน้อย แต่คุณจะไม่เห็นสิ่งที่เกิดขึ้นในแต่ละขั้นตอน | +| **Native RAG** | คุณเรียกโมเดลฝังตัว, ค้นหาในร้านค้า, สร้างคำสั่ง, และสร้างคำตอบเอง — ทีละขั้นตอนอย่างชัดเจน | โค้ดมากขึ้น แต่ทุกขั้นตอนเห็นได้และปรับได้ | +| **Advanced RAG** | ใช้เฟรมเวิร์ก `RetrievalAugmentor` ที่มีตัวแปลงคำถาม, ตัวนำทาง, ตัวจัดอันดับใหม่ และตัวฉีดเนื้อหาที่เสียบได้ สำหรับระบบระดับผลิต | ยืดหยุ่นสูงสุด แต่ซับซ้อนมากกว่า | -**บทแนะนำนี้ใช้วิธี Native** ทุกขั้นตอนของไลน์การทำงาน RAG — การ embedding คำถาม, ค้นหาในเวกเตอร์สโตร์, การประกอบบริบท, และการสร้างคำตอบ — เขียนโดยละเอียดใน [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ซึ่งทำให้คุณเห็นและเข้าใจแต่ละขั้นตอนอย่างชัดเจน เมื่อคุณเข้าใจแนวทางนี้แล้ว คุณอาจข้ามไป Easy RAG เพื่อสร้างต้นแบบอย่างรวดเร็ว หรือ Advanced RAG สำหรับระบบโปรดักชัน +**บทเรียนนี้ใช้วิธี Native** ขั้นตอนแต่ละส่วนของ pipeline RAG — ฝังตัวคำถาม, ค้นหาจากร้านเวกเตอร์, ประกอบบริบท, สร้างคำตอบ — ถูกเขียนออกมาอย่างชัดเจนใน [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) นี่เป็นเจตนา: ในฐานะแหล่งเรียนรู้ สิ่งสำคัญกว่าคือคุณเห็นและเข้าใจแต่ละขั้นตอนมากกว่าการย่นโค้ด เมื่อคุณคุ้นเคยกับวิธีประกอบส่วนต่าง ๆ แล้ว คุณสามารถย้ายไปใช้ Easy RAG สำหรับต้นแบบรวดเร็ว หรือ Advanced RAG สำหรับระบบผลิตได้ -> **💡 เคยเห็น Easy RAG แล้ว?** โมดูล [Quick Start](../00-quick-start/README.md) มีตัวอย่าง Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) ที่ใช้ Easy RAG โดย LangChain4j จัดการ embedding, ค้นหา และประกอบ prompt อัตโนมัติ โมดูลนี้จะเปิดเผยขั้นตอนเหล่านั้นให้เห็นและควบคุมได้ด้วยตนเอง +> **💡 สนใจ Easy RAG ไหม?** LangChain4j ยังมีวิธี Easy RAG ที่ใช้ `AiServices` กับ `ContentRetriever` ดูแลการฝังตัว, การค้นหา และการประกอบคำสั่งแบบอัตโนมัติ โมดูลนี้เลือกทางชัดเจนกว่านั้น — เปิด pipeline เพื่อคุณเห็นและควบคุมแต่ละขั้นตอนเอง -แผนภาพด้านล่างแสดงไลน์การทำงาน Easy RAG จากตัวอย่าง Quick Start สังเกตว่า `AiServices` และ `EmbeddingStoreContentRetriever` ซ่อนความซับซ้อน คุณเพียงโหลดเอกสาร แนบ retriever แล้วรับคำตอบ วิธีย่อย Native ในโมดูลนี้จะเปิดเผยแต่ละขั้นตอน: +แผนภาพด้านล่างแสดง pipeline Easy RAG สังเกตว่า `AiServices` และ `EmbeddingStoreContentRetriever` ซ่อนความซับซ้อนทั้งหมด — คุณโหลดเอกสาร, แนบ retriever, และได้คำตอบ วิธี Native ในโมดูลนี้เปิดทุกขั้นตอนที่ซ่อน: Easy RAG Pipeline - LangChain4j -*แผนภาพนี้แสดงไลน์ Easy RAG จาก `SimpleReaderDemo.java` เปรียบเทียบกับวิธี Native ในโมดูลนี้: Easy RAG ซ่อน embedding, การดึงข้อมูล และการประกอบ prompt ไว้ที่ `AiServices` และ `ContentRetriever` — คุณโหลดเอกสาร แนบ retriever แล้วได้คำตอบ Native เปิดเผยขั้นตอนนี้ให้คุณเรียกใช้ทุกขั้นตอน (embedding, ค้นหา, ประกอบบริบท, สร้างคำตอบ) ด้วยตัวเอง ทำให้เห็นและควบคุมได้เต็มที่* +*แผนภาพนี้แสดง pipeline Easy RAG เปรียบเทียบกับ Native ที่โมดูลนี้ใช้: Easy RAG ซ่อนการฝังตัว, การค้นหา, การประกอบคำสั่ง ไว้ใน `AiServices` และ `ContentRetriever` — คุณโหลดเอกสาร, แนบ retriever, และได้คำตอบ Native เปิด pipeline เพื่อให้คุณเรียกแต่ละขั้นตอน (ฝัง, ค้นหา, ประกอบบริบท, สร้างคำตอบ) เอง โดยให้มองเห็นและควบคุมครบถ้วน* ## How It Works -ไลน์การทำงาน RAG ในโมดูลนี้แบ่งเป็นสี่ขั้นตอนที่ทำเป็นลำดับ เมื่อผู้ใช้ถามคำถาม ขั้นแรกเอกสารที่อัปโหลดจะถูก **แยกและแบ่งเป็นชิ้นเล็ก** เพื่อจัดการได้ง่าย ชิ้นเหล่านี้ถูกแปลงเป็น **embedding แบบเวกเตอร์** และจัดเก็บเพื่อเปรียบเทียบทางคณิตศาสตร์ เมื่อมีคำถามระบบจะทำ **การค้นหาเชิงความหมาย** เพื่อหาชิ้นส่วนที่เกี่ยวข้องมากที่สุด แล้วส่งต่อเป็นบริบทให้ LLM ทำ **การสร้างคำตอบ** ส่วนถัดไปจะอธิบายแต่ละขั้นตอนพร้อมโค้ดและแผนภาพ มาดูขั้นตอนแรกกัน +Pipeline RAG ในโมดูลนี้แบ่งออกเป็นสี่ขั้นตอนที่ทำงานต่อเนื่องทุกครั้งที่ผู้ใช้ถามคำถาม ขั้นแรก เอกสารที่อัปโหลดจะถูก **แยกและแบ่งเป็นส่วนเล็ก ๆ** ที่จัดการได้ งวดเหล่านั้นจะถูกแปลงเป็น **เวกเตอร์ฝังตัว** และเก็บไว้เพื่อให้เปรียบเทียบทางคณิตศาสตร์ได้ เมื่อมีคำถาม ระบบจะทำ **การค้นหาเชิงความหมาย** เพื่อหางวดที่เกี่ยวข้องมากที่สุด และสุดท้ายส่งผ่านคลุมบริบทไปยัง LLM เพื่อ **สร้างคำตอบ** ส่วนถัดไปจะอธิบายแต่ละขั้นตอนพร้อมโค้ดและแผนภาพ มาดูขั้นตอนแรกกัน ### Document Processing [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -เมื่อคุณอัปโหลดเอกสาร ระบบจะทำการแยกวิเคราะห์เอกสาร (PDF หรือข้อความธรรมดา) แนบเมตาดาต้าอย่างชื่อไฟล์ แล้วแบ่งเป็นชิ้นเล็ก — ส่วนที่เล็กลงซึ่งพอดีกับหน้าต่างบริบทของโมเดล ชิ้นเหล่านี้ทับซ้อนกันเล็กน้อยเพื่อไม่ให้สูญเสียบริบทตรงขอบเขต +เมื่อคุณอัปโหลดเอกสาร ระบบจะทำการแยกวิเคราะห์ (PDF หรือข้อความธรรมดา) แนบข้อมูลเมตา เช่น ชื่อไฟล์ แล้วแบ่งออกเป็นชิ้นเล็ก ๆ — ชิ้นเล็กที่สามารถใส่ใน context window ของโมเดลได้ง่าย ชิ้นเหล่านี้จะทับซ้อนกันเล็กน้อยเพื่อไม่ให้เสียบริบทตรงขอบเขต ```java // แยกวิเคราะห์ไฟล์ที่อัปโหลดและห่อหุ้มในเอกสาร LangChain4j Document document = Document.from(content, metadata); -// แบ่งเป็นชิ้นส่วนขนาด 300 โทเค็นโดยทับซ้อนกัน 30 โทเค็น +// แบ่งเป็นชิ้นขนาด 300 โทเค็นโดยมีการทับซ้อน 30 โทเค็น DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -แผนภาพด้านล่างแสดงการทำงานเป็นภาพ สังเกตว่าชิ้นแต่ละชิ้นแบ่งทับซ้อนบางส่วนกับชิ้นข้างเคียง — การทับซ้อน 30 โทเคนช่วยให้บริบทสำคัญไม่ขาดช่วงตรงขอบเขต: + +แผนภาพด้านล่างแสดงการทำงานนี้อย่างเป็นภาพ สังเกตว่าชิ้นแต่ละชิ้นจะแบ่งปันโทเคนบางส่วนกับเพื่อนบ้าน — ทับซ้อนกัน 30 โทเคนเพื่อให้บริบทสำคัญไม่ถูกละเลยที่ขอบเขต: Document Chunking -*แผนภาพนี้แสดงเอกสารถูกแบ่งเป็นชิ้นละ 300 โทเคน ที่มีการทับซ้อน 30 โทเคน เพื่อรักษาบริบทตรงขอบเขต* +*แผนภาพนี้แสดงการแบ่งเอกสารเป็นชิ้นขนาด 300 โทเคนที่ทับซ้อน 30 โทเคน เพื่อรักษาบริบทที่ขอบเขตชิ้นงาน* -> **🤖 ลองใช้ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) แล้วถาม: -> - "LangChain4j แบ่งเอกสารเป็นชิ้นเล็กๆ อย่างไรและทำไมการทับซ้อนถึงสำคัญ?" -> - "ขนาดชิ้นที่เหมาะสมสำหรับเอกสารแต่ละประเภทคือเท่าไหร่และเพราะเหตุใด?" -> - "จัดการกับเอกสารหลายภาษา หรือมีการจัดรูปแบบพิเศษอย่างไร?" +> **🤖 ลองกับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) แล้วถามว่า: +> - "LangChain4j แบ่งเอกสารเป็นชิ้นอย่างไรและทำไมต้องทับซ้อน" +> - "ขนาดชิ้นที่เหมาะสมสำหรับประเภทเอกสารต่าง ๆ คือเท่าไรและเพราะเหตุใด" +> - "จะจัดการเอกสารหลายภาษา หรือที่มีรูปแบบพิเศษได้อย่างไร" ### Creating Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -แต่ละชิ้นจะถูกแปลงเป็นตัวแทนเชิงตัวเลขที่เรียกว่า embedding — โดยเทียบเท่ากับเครื่องมือแปลงความหมายเป็นตัวเลข โมเดล embedding ไม่ใช่โมเดลแชทที่ "ฉลาด" ที่สามารถทำตามคำสั่ง ตรรกะ หรือให้คำตอบได้ สิ่งที่มันทำได้คือแม็ปข้อความลงในพื้นที่ทางคณิตศาสตร์ที่ความหมายใกล้เคียงกันจะอยู่ติดกัน — เช่น "car" ใกล้กับ "automobile," "refund policy" ใกล้กับ "return my money" คิดว่าโมเดลแชทเปรียบเหมือนคนที่คุณคุยด้วย ส่วนโมเดล embedding คือระบบจัดเก็บข้อมูลที่ดีเยี่ยม +ชิ้นส่วนแต่ละชิ้นจะถูกแปลงเป็นการแทนค่าตัวเลขเรียกว่าการฝังตัว (embedding) — โดยพื้นฐานคือเครื่องมือแปลงความหมายเป็นตัวเลข โมเดลฝังตัวไม่ใช่ "ฉลาด" เหมือนโมเดลแชท มันไม่สามารถทำตามคำสั่ง, ให้เหตุผล หรือ ตอบคำถามได้ สิ่งที่มันทำได้คือแม็ปข้อความเข้าสู่พื้นที่คณิตศาสตร์ที่ความหมายเหมือนกันอยู่ใกล้กัน — เช่น "car" อยู่ใกล้ "automobile", "refund policy" อยู่ใกล้ "return my money" คิดว่าโมเดลแชทเป็นคนที่คุณพูดคุยด้วย โมเดลฝังตัวเป็นระบบเก็บเอกสารที่ดีมาก -แผนภาพด้านล่างแสดงภาพแนวคิดนี้ — ข้อความเข้ามา เปลี่ยนเป็นเวกเตอร์ตัวเลข และความหมายใกล้เคียงกันจะอยู่จุดใกล้กัน: +แผนภาพด้านล่างแสดงแนวคิดนี้ — ข้อความเข้าไป, เวกเตอร์ตัวเลขออกมา, และความหมายที่ใกล้เคียงกันจะสร้างเวกเตอร์ที่อยู่ใกล้กัน: Embedding Model Concept -*แผนภาพนี้แสดงวิธีที่โมเดล embedding แปลงข้อความเป็นเวกเตอร์ตัวเลข โดยวางความหมายใกล้เคียง เช่น "car" และ "automobile" ให้เข้าใกล้กันในพื้นที่เวกเตอร์* +*แผนภาพนี้แสดงการแปลงข้อความเป็นเวกเตอร์ตัวเลขโดยโมเดลฝังตัว โดยวางความหมายที่เหมือนกัน เช่น "car" และ "automobile" ให้อยู่ใกล้กันในเวกเตอร์สเปซ* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -แผนภาพคลาสนี้แสดงสองไลน์การไหลใน pipeline RAG และคลาสของ LangChain4j ที่ใช้งาน ไลน์ **การ ingest** (รันครั้งเดียวตอนอัปโหลด) ทำการแบ่งเอกสาร embed ชิ้น และจัดเก็บผ่าน `.addAll()` ขณะที่ไลน์ **การ query** (รันทุกครั้งเมื่อมีคำถาม) embed คำถาม ค้นหาใน store ผ่าน `.search()` และส่งบริบทที่ตรงกันให้โมเดลแชท ทั้งสองไลน์รวมกันที่ interface ร่วม `EmbeddingStore`: + +แผนภาพคลาสด้านล่างแสดงสองกระแสแยกใน pipeline RAG และคลาส LangChain4j ที่ใช้งาน พื้นที่ **ingestion flow** (ทำงานครั้งเดียวตอนอัปโหลด) จะแบ่งเอกสาร, ฝังตัวชิ้นงาน, และเก็บผ่าน `.addAll()` ส่วน **query flow** (ทำงานทุกครั้งเมื่อมีคำถาม) ฝังตัวคำถาม, ค้นหาในร้านผ่าน `.search()`, และส่งบริบทที่จับคู่ไปยังโมเดลแชท ทั้งสองเส้นทางมาบรรจบกันที่อินเทอร์เฟซ `EmbeddingStore` ร่วมกัน: LangChain4j RAG Classes -*แผนภาพนี้แสดงสองไลน์การไหลใน pipeline RAG — ingest และ query — และการเชื่อมโยงผ่าน EmbeddingStore ร่วม* +*แผนภาพนี้แสดงสองเส้นทางใน pipeline RAG — ingestion และ query — และการเชื่อมต่อผ่าน EmbeddingStore ที่ใช้ร่วมกัน* -หลังจากเก็บ embedding แล้ว เนื้อหาที่คล้ายกันจะรวมกลุ่มกันตามธรรมชาติในพื้นที่เวกเตอร์ ภาพด้านล่างแสดงว่าเอกสารหัวข้อใกล้เคียงกันจะรวมเป็นกลุ่มใกล้เคียงกัน ซึ่งทำให้การค้นหาเชิงความหมายเป็นไปได้: +เมื่อ embeddings ถูกเก็บไว้ เนื้อหาที่คล้ายกันจะรวมกลุ่มกันตามธรรมชาติในพื้นที่เวกเตอร์ ภาพด้านล่างแสดงวิธีที่เอกสารเกี่ยวกับหัวข้อที่สัมพันธ์กันรวมเป็นกลุ่มใกล้กัน ซึ่งช่วยให้การค้นหาเชิงความหมายเป็นไปได้: Vector Embeddings Space -*ภาพนี้แสดงเอกสารที่เกี่ยวข้องรวมกลุ่มกันในพื้นที่เวกเตอร์ 3 มิติ โดยมีหัวข้ออย่าง Technical Docs, Business Rules และ FAQs แยกเป็นกลุ่มชัดเจน* +*ภาพนี้แสดงการจัดกลุ่มเอกสารที่เกี่ยวข้องในพื้นที่เวกเตอร์ 3 มิติ โดยมีหัวข้อต่าง ๆ เช่น เอกสารทางเทคนิค, กฎธุรกิจ, และ FAQ แบ่งเป็นกลุ่มชัดเจน* -เมื่อผู้ใช้ค้นหา ระบบจะทำสี่ขั้นตอน: embed เอกสารครั้งเดียว, embed คำถามทุกครั้งที่ค้นหา, เปรียบเทียบเวกเตอร์คำถามกับเวกเตอร์ทั้งหมดโดยใช้ cosine similarity และคืนชิ้นที่คะแนนสูงสุดจำนวนบนสุด แผนภาพด้านล่างแสดงแต่ละขั้นตอนและคลาสใน LangChain4j ที่เกี่ยวข้อง: +เมื่อผู้ใช้ค้นหา ระบบทำตามสี่ขั้นตอน: ฝังเอกสารครั้งเดียว, ฝังคำถามแต่ละครั้ง, เปรียบเทียบเวกเตอร์คำถามกับเวกเตอร์เก็บในร้านโดยใช้ cosine similarity, และคืนค่าชิ้นส่วนคะแนนสูงสุด K อันดับ แผนภาพด้านล่างแสดงแต่ละขั้นตอนและคลาส LangChain4j ที่เกี่ยวข้อง: Embedding Search Steps -*แผนภาพนี้แสดงขั้นตอนสี่ขั้นตอนของการค้นหา embedding: embed เอกสาร, embed คำถาม, เปรียบเทียบเวกเตอร์โดยใช้ cosine similarity และคืนผลลัพธ์ที่ดีที่สุด* +*แผนภาพนี้แสดงกระบวนการค้นหาด้วย embedding 4 ขั้นตอน: ฝังเอกสาร, ฝังคำถาม, เปรียบเทียบเวกเตอร์ด้วย cosine similarity, และคืนผลลัพธ์ท็อปเค* ### Semantic Search [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -เมื่อคุณถามคำถาม คำถามของคุณก็จะถูกแปลงเป็น embedding ด้วยเช่นกัน ระบบเทียบ embedding ของคำถามกับ embedding ของชิ้นเอกสารทั้งหมด เพื่อค้นหาชิ้นที่มีความหมายใกล้เคียงที่สุด — ไม่ใช่แค่คำหลักตรงกัน แต่เป็นความหมายเชิงความสัมพันธ์จริงๆ +เมื่อคุณถามคำถาม คำถามของคุณก็ถูกแปลงเป็น embedding ด้วย ระบบเปรียบเทียบ embedding คำถามของคุณกับ embedding ชิ้นส่วนเอกสารทั้งหมด หาชิ้นที่มีความหมายใกล้เคียงที่สุด — ไม่ใช่แค่คำหลักตรงกัน แต่ความหมายใกล้เคียงจริง ๆ ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -แผนภาพด้านล่างเปรียบเทียบการค้นหาเชิงความหมายกับการค้นหาด้วยคำหลัก การค้นหาด้วยคำหลัก "vehicle" อาจพลาดชิ้นที่พูดถึง "cars and trucks" แต่การค้นหาเชิงความหมายจะเข้าใจว่าเหมือนกันและคืนผลลัพธ์ที่เกี่ยวข้องครบถ้วน: + +แผนภาพด้านล่างเปรียบเทียบการค้นหาเชิงความหมายกับการค้นหาด้วยคำหลัก การค้นหาด้วยคำหลัก "vehicle" จะพลาดชิ้นส่วนที่พูดถึง "cars and trucks" แต่การค้นหาเชิงความหมายเข้าใจว่าหมายถึงสิ่งเดียวกันและคืนผลลัพธ์เป็นคะแนนสูง: Semantic Search -*แผนภาพนี้เทียบการค้นหาด้วยคำหลักกับการค้นหาเชิงความหมาย แสดงให้เห็นว่าการค้นหาเชิงความหมายดึงข้อมูลที่เกี่ยวข้องถึงแนวคิดแม้ว่าคำหลักจะต่างกัน* -ภายในระบบ ความคล้ายคลึงถูกวัดโดยใช้ cosine similarity — โดยถามว่า "ลูกศรสองอันนี้ชี้ไปในทิศทางเดียวกันหรือไม่?" สองส่วนของข้อความอาจใช้คำต่างกันโดยสิ้นเชิง แต่ถ้าหมายความเหมือนกัน เวกเตอร์ของพวกมันจะชี้ไปในทิศทางเดียวกันและคะแนนจะใกล้เคียงกับ 1.0: +*แผนภาพนี้เปรียบเทียบการค้นหาด้วยคำหลักกับการค้นหาเชิงความหมาย แสดงให้เห็นว่าการค้นหาเชิงความหมายดึงเนื้อหาที่เกี่ยวข้องทางความหมายแม้ว่าคำหลักจะแตกต่างกัน* -Cosine Similarity +เบื้องหลัง ความคล้ายคลึงถูกวัดโดยใช้ cosine similarity — กล่าวง่าย ๆ คือถามว่า "ลูกศรสองอันนี้ชี้ไปในทิศทางเดียวกันไหม?" ชิ้นสองชิ้นอาจใช้คำต่างกันโดยสิ้นเชิง แต่ถ้าความหมายเหมือนกัน เวกเตอร์ของสองชิ้นนี้จะชี้ไปทางเดียวกันและให้คะแนนใกล้ 1.0: -*ไดอะแกรมนี้แสดง cosine similarity เป็นมุมระหว่างเวกเตอร์ embedding — เวกเตอร์ที่เรียงตัวกันมากกว่าจะได้คะแนนใกล้เคียง 1.0 ซึ่งบ่งชี้ความคล้ายคลึงทางความหมายสูง* +Cosine Similarity +*ไดอะแกรมนี้แสดงความคล้ายคลึงแบบโคไซน์ในฐานะมุมระหว่างเวกเตอร์ฝังตัว — เวกเตอร์ที่จัดแนวมากกว่ามีคะแนนใกล้เคียงกับ 1.0 ซึ่งบ่งชี้ความคล้ายคลึงกันทางความหมายที่สูงกว่า* -> **🤖 ลองกับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิดไฟล์ [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) แล้วถาม: -> - "การค้นหาความคล้ายคลึงทำงานอย่างไรกับ embeddings และอะไรเป็นตัวกำหนดคะแนน?" -> - "ควรใช้เกณฑ์ความคล้ายคลึงเท่าไหร่และมีผลอย่างไรต่อผลลัพธ์?" -> - "จัดการกรณีที่ไม่พบเอกสารที่เกี่ยวข้องอย่างไร?" +> **🤖 ลองใช้กับ [GitHub Copilot](https://github.com/features/copilot) แชท:** เปิด [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) และถามว่า: +> - "การค้นหาความคล้ายคลึงทำงานอย่างไรกับ embeddings และอะไรที่กำหนดคะแนน?" +> - "ฉันควรใช้เกณฑ์ความคล้ายคลึงเท่าไหร่และมันส่งผลต่อผลลัพธ์อย่างไร?" +> - "ฉันจัดการกับกรณีที่ไม่พบเอกสารที่เกี่ยวข้องได้อย่างไร?" ### การสร้างคำตอบ [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -ส่วนที่เกี่ยวข้องมากที่สุดจะถูกจัดรวมเข้าเป็น prompt ที่มีโครงสร้างโดยรวมคำสั่งที่ชัดเจน ข้อมูลบริบทที่ถูกดึงมา และคำถามของผู้ใช้ โมเดลจะอ่านแต่ส่วนเหล่านี้และตอบคำถามโดยอิงจากข้อมูลเหล่านั้น — ตัวโมเดลจะใช้ได้เฉพาะข้อมูลที่ปรากฏอยู่ตรงหน้าเท่านั้น ซึ่งช่วยป้องกันการคาดเดาผิดๆ +ชิ้นส่วนที่เกี่ยวข้องที่สุดถูกประกอบเป็นข้อความแจ้งที่มีโครงสร้างซึ่งรวมถึงคำสั่งที่ชัดเจน บริบทที่เรียกคืนมา และคำถามของผู้ใช้ โมเดลจะอ่านชิ้นส่วนเหล่านั้นและตอบโดยอิงจากข้อมูลนั้น — โมเดลสามารถใช้ได้เฉพาะสิ่งที่อยู่ตรงหน้าเท่านั้น ซึ่งช่วยป้องกันการจินตนาการเกินจริง ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -ไดอะแกรมข้างล่างแสดงการจัดรวมนี้แบบแอคทีฟ — ส่วนที่ได้คะแนนสูงสุดจากขั้นตอนค้นหาจะถูกใส่เข้าไปในแม่แบบ prompt และ `OpenAiOfficialChatModel` จะสร้างคำตอบที่มีข้อมูลรองรับ: +ไดอะแกรมด้านล่างแสดงการทำงานของการประกอบนี้ — ชิ้นที่ได้คะแนนสูงสุดจากขั้นตอนการค้นหาจะถูกแทรกลงในแม่แบบคำแจ้ง และ `OpenAiOfficialChatModel` จะสร้างคำตอบที่มีพื้นฐาน: Context Assembly -*ไดอะแกรมนี้แสดงการจัดรวมส่วนที่ได้คะแนนสูงสุดเข้าไปใน prompt ที่มีโครงสร้าง อนุญาตให้โมเดลสร้างคำตอบที่มีข้อมูลรองรับจากข้อมูลของคุณ* +*ไดอะแกรมนี้แสดงวิธีการประกอบชิ้นที่ได้คะแนนสูงสุดเป็นคำแจ้งที่มีโครงสร้าง ทำให้โมเดลสามารถสร้างคำตอบที่มีพื้นฐานจากข้อมูลของคุณ* -## การรันแอปพลิเคชัน +## รันแอปพลิเคชัน **ตรวจสอบการดีพลอย:** -ตรวจสอบให้แน่ใจว่าไฟล์ `.env` มีอยู่ที่โฟลเดอร์หลักพร้อมกับข้อมูลประจำตัว Azure (สร้างขึ้นใน Module 01) รันคำสั่งนี้จากโฟลเดอร์โมดูล (`03-rag/`): +ตรวจสอบให้แน่ใจว่าไฟล์ `.env` มีอยู่ในไดเรกทอรีหลักพร้อมข้อมูลประจำตัว Azure (สร้างขึ้นในโมดูล 01) รันคำสั่งนี้จากไดเรกทอรีโมดูล (`03-rag/`): **Bash:** ```bash @@ -261,41 +260,41 @@ Get-Content ..\.env # ควรแสดง AZURE_OPENAI_ENDPOINT, API_KEY, DEP **เริ่มแอปพลิเคชัน:** -> **หมายเหตุ:** หากคุณเริ่มแอปทั้งหมดแล้วโดยใช้ `./start-all.sh` จากโฟลเดอร์หลัก (ตามที่อธิบายไว้ใน Module 01) โมดูลนี้จะทำงานอยู่บนพอร์ต 8081 แล้ว คุณสามารถข้ามคำสั่งเริ่มด้านล่างและเข้าไปที่ http://localhost:8081 ได้เลย +> **หมายเหตุ:** หากคุณเริ่มแอปพลิเคชันทั้งหมดแล้วโดยใช้ `./start-all.sh` จากไดเรกทอรีราก (ตามที่อธิบายในโมดูล 01) โมดูลนี้จะทำงานอยู่บนพอร์ต 8081 อยู่แล้ว คุณสามารถข้ามคำสั่งเริ่มด้านล่างและไปที่ http://localhost:8081 ได้เลย **ตัวเลือกที่ 1: ใช้ Spring Boot Dashboard (แนะนำสำหรับผู้ใช้ VS Code)** -ภายใน dev container มีส่วนขยาย Spring Boot Dashboard ที่ให้หน้าต่างแบบกราฟิกสำหรับจัดการแอป Spring Boot ทั้งหมด คุณจะเห็นไอคอนนี้ในแถบกิจกรรมด้านซ้ายของ VS Code (มองหาไอคอน Spring Boot) +คอนเทนเนอร์สำหรับนักพัฒนารวมส่วนขยาย Spring Boot Dashboard ซึ่งมีอินเทอร์เฟซแบบภาพสำหรับจัดการแอป Spring Boot ทั้งหมด คุณสามารถหาได้ในแถบกิจกรรมด้านซ้ายของ VS Code (มองหาไอคอน Spring Boot) จาก Spring Boot Dashboard คุณสามารถ: -- ดูแอป Spring Boot ทั้งหมดใน workspace -- เริ่ม/หยุดแอปด้วยคลิกเดียว -- ดูบันทึกแอปแบบเรียลไทม์ -- ตรวจสอบสถานะแอป +- ดูแอปพลิเคชัน Spring Boot ที่มีในพื้นที่ทำงานทั้งหมด +- เริ่ม/หยุดแอปพลิเคชันด้วยการคลิกครั้งเดียว +- ดูล็อกของแอปพลิเคชันแบบเรียลไทม์ +- ตรวจสอบสถานะแอปพลิเคชัน -เพียงคลิกปุ่มเล่นข้าง "rag" เพื่อเริ่มโมดูลนี้ หรือเริ่มโมดูลทั้งหมดพร้อมกัน +เพียงคลิกปุ่มเล่นข้าง ๆ "rag" เพื่อเริ่มโมดูลนี้ หรือเริ่มโมดูลทั้งหมดพร้อมกัน Spring Boot Dashboard -*ภาพหน้าจอนี้แสดง Spring Boot Dashboard ใน VS Code ที่ให้คุณเริ่ม หยุด และตรวจสอบแอปแบบกราฟิก* +*ภาพหน้าจอนี้แสดง Spring Boot Dashboard ใน VS Code ซึ่งคุณสามารถเริ่ม หยุด และตรวจสอบแอปพลิเคชันได้อย่างง่ายดาย* **ตัวเลือกที่ 2: ใช้สคริปต์เชลล์** -เริ่มเว็บแอปทั้งหมด (โมดูล 01-04): +เริ่มแอปพลิเคชันเว็บทั้งหมด (โมดูล 01-04): **Bash:** ```bash -cd .. # จากไดเรกทอรีราก +cd .. # จากไดเรกทอรีรูท ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # จากไดเรกทอรีรูท +cd .. # จากไดเรกทอรีราก .\start-all.ps1 ``` -หรือเริ่มแค่โมดูลนี้: +หรือเริ่มเฉพาะโมดูลนี้: **Bash:** ```bash @@ -309,29 +308,29 @@ cd 03-rag .\start.ps1 ``` -ทั้งสองสคริปต์จะโหลด environment variables จากไฟล์ `.env` ที่โฟลเดอร์หลักโดยอัตโนมัติ และจะสร้างไฟล์ JAR ถ้ายังไม่มี +สคริปต์ทั้งสองจะโหลดตัวแปรสภาพแวดล้อมโดยอัตโนมัติจากไฟล์ `.env` ในโฟลเดอร์หลัก และจะสร้างไฟล์ JAR หากยังไม่มี -> **หมายเหตุ:** ถ้าคุณต้องการสร้างโมดูลทั้งหมดด้วยตัวเองก่อนเริ่มรัน: +> **หมายเหตุ:** หากคุณต้องการสร้างโมดูลทั้งหมดด้วยตนเองก่อนเริ่ม: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -เปิด http://localhost:8081 ในเบราว์เซอร์ของคุณ +เปิด http://localhost:8081 ในเว็บเบราว์เซอร์ของคุณ **เพื่อหยุด:** **Bash:** ```bash -./stop.sh # เฉพาะโมดูลนี้ +./stop.sh # โมดูลนี้เท่านั้น # หรือ cd .. && ./stop-all.sh # ทุกโมดูล ``` @@ -345,93 +344,93 @@ cd ..; .\stop-all.ps1 # ทุกโมดูล ## การใช้แอปพลิเคชัน -แอปนี้ให้หน้าเว็บสำหรับอัพโหลดเอกสารและถามคำถาม +แอปพลิเคชันมีอินเทอร์เฟซเว็บสำหรับอัปโหลดเอกสารและสอบถามคำถาม RAG Application Interface -*ภาพหน้าจอนี้แสดงอินเทอร์เฟซแอป RAG ที่คุณอัพโหลดเอกสารและถามคำถามได้* +*ภาพหน้าจอนี้แสดงอินเทอร์เฟซของแอป RAG ซึ่งคุณสามารถอัปโหลดเอกสารและถามคำถาม* -### การอัพโหลดเอกสาร +### อัปโหลดเอกสาร -เริ่มจากการอัพโหลดเอกสาร — ไฟล์ TXT เหมาะสำหรับการทดสอบที่สุด มีไฟล์ตัวอย่าง `sample-document.txt` ในโฟลเดอร์นี้ที่มีข้อมูลเกี่ยวกับฟีเจอร์ LangChain4j การใช้งาน RAG และแนวทางปฏิบัติที่ดีที่สุด — เหมาะสำหรับการทดสอบระบบ +เริ่มต้นด้วยการอัปโหลดเอกสาร — ไฟล์ TXT ใช้ทดสอบได้ดีที่สุด มีไฟล์ `sample-document.txt` ให้ในไดเรกทอรีนี้ซึ่งมีข้อมูลเกี่ยวกับฟีเจอร์ของ LangChain4j การใช้งาน RAG และแนวปฏิบัติที่ดีที่สุด — เหมาะสำหรับทดสอบระบบ -ระบบจะประมวลผลเอกสารของคุณ แบ่งเป็นชิ้นส่วน และสร้าง embeddings สำหรับแต่ละชิ้น ซึ่งเกิดขึ้นโดยอัตโนมัติเมื่อคุณอัพโหลด +ระบบจะประมวลผลเอกสารของคุณ แบ่งเป็นชิ้น และสร้าง embeddings สำหรับแต่ละชิ้นโดยอัตโนมัติเมื่อคุณอัปโหลด ### ถามคำถาม -ตอนนี้ถามคำถามเฉพาะเจาะจงเกี่ยวกับเนื้อหาในเอกสาร ลองถามสิ่งที่เป็นข้อเท็จจริงที่ชัดเจนในเอกสาร ระบบจะค้นหาชิ้นส่วนที่เกี่ยวข้อง นำมารวมใน prompt และสร้างคำตอบขึ้น +ตอนนี้ถามคำถามเฉพาะเจาะจงเกี่ยวกับเนื้อหาในเอกสาร ลองถามข้อเท็จจริงที่ระบุอย่างชัดเจนในเอกสาร ระบบจะค้นหาชิ้นที่เกี่ยวข้อง นำมาใส่ในคำแจ้ง และสร้างคำตอบ -### ตรวจสอบแหล่งที่มา +### ตรวจสอบการอ้างอิงแหล่งที่มา -สังเกตว่าแต่ละคำตอบจะมีการอ้างอิงแหล่งที่มาพร้อมคะแนนความคล้ายคลึง คะแนนเหล่านี้ (0 ถึง 1) แสดงว่าชิ้นส่วนแต่ละอันเกี่ยวข้องกับคำถามของคุณเพียงใด ยิ่งคะแนนสูงหมายถึงแมตช์ที่ดียิ่งขึ้น ทำให้คุณตรวจสอบคำตอบกับแหล่งข้อมูลได้ +สังเกตว่าคำตอบแต่ละข้อจะรวมการอ้างอิงแหล่งที่มาพร้อมคะแนนความคล้ายคลึง ซึ่งคะแนนเหล่านี้ (0 ถึง 1) แสดงให้เห็นว่าชิ้นหนึ่ง ๆ มีความเกี่ยวข้องกับคำถามของคุณมากแค่ไหน คะแนนสูงหมายถึงการจับคู่ที่ดีกว่า ช่วยให้คุณตรวจสอบคำตอบกับแหล่งข้อมูลต้นทางได้ RAG Query Results -*ภาพหน้าจอนี้แสดงผลลัพธ์คำถามพร้อมคำตอบที่สร้างขึ้น การอ้างอิงแหล่งที่มา และคะแนนความเกี่ยวข้องสำหรับแต่ละชิ้นส่วนที่ถูกดึงมา* +*ภาพหน้าจอนี้แสดงผลลัพธ์การค้นหาคำถาม พร้อมคำตอบที่สร้างขึ้น การอ้างอิงแหล่งที่มา และคะแนนความเกี่ยวข้องของแต่ละชิ้นที่ถูกเรียกคืน* -### ทดลองถามคำถาม +### ทดลองถามคำถามต่าง ๆ -ลองตั้งคำถามหลายๆ แบบ: +ลองถามคำถามหลายประเภทย่อย: - ข้อเท็จจริงเฉพาะ: "หัวข้อหลักคืออะไร?" - การเปรียบเทียบ: "ความแตกต่างระหว่าง X กับ Y คืออะไร?" - สรุป: "สรุปประเด็นสำคัญเกี่ยวกับ Z" -ดูว่าคะแนนความเกี่ยวข้องเปลี่ยนแปลงอย่างไรขึ้นกับว่าคำถามของคุณตรงกับเนื้อหาเอกสารเพียงใด +สังเกตว่าคะแนนความเกี่ยวข้องเปลี่ยนแปลงอย่างไรตามความสอดคล้องของคำถามกับเนื้อหาเอกสาร ## แนวคิดสำคัญ -### กลยุทธ์การแบ่งชิ้น +### ยุทธศาสตร์การแบ่งชิ้น -เอกสารถูกแบ่งเป็นชิ้นละ 300 โทเค็นโดยทับซ้อนกัน 30 โทเค็น สมดุลนี้ช่วยให้แต่ละชิ้นมีบริบทเพียงพอที่จะมีความหมายในขณะเดียวกันก็ยังเล็กพอที่จะรวมหลายชิ้นใน prompt ได้ +เอกสารถูกแบ่งเป็นชิ้นละ 300 โทเคน โดยมีการเหลื่อมกัน 30 โทเคน การเลือกนี้ช่วยให้แต่ละชิ้นมีบริบทเพียงพอที่จะมีความหมายในขณะที่ยังคงขนาดเล็กพอที่จะรวมหลายชิ้นในคำแจ้งได้ ### คะแนนความคล้ายคลึง -ชิ้นส่วนที่ถูกดึงมาทั้งหมดมาพร้อมคะแนนความคล้ายคลึงจาก 0 ถึง 1 แสดงว่าตรงกับคำถามของผู้ใช้มากน้อยแค่ไหน ไดอะแกรมด้านล่างแสดงช่วงคะแนนและวิธีการใช้คะแนนเหล่านี้เพื่อกรองผลลัพธ์: +ชิ้นที่ถูกเรียกคืนแต่ละชิ้นมาพร้อมกับคะแนนความคล้ายคลึงระหว่าง 0 ถึง 1 ซึ่งบอกว่าชิ้นนั้นสอดคล้องกับคำถามของผู้ใช้แค่ไหน ไดอะแกรมด้านล่างแสดงช่วงคะแนนและวิธีที่ระบบใช้กรองผลลัพธ์: Similarity Scores -*ไดอะแกรมนี้แสดงช่วงคะแนนจาก 0 ถึง 1 โดยมีเกณฑ์ขั้นต่ำที่ 0.5 สำหรับคัดกรองชิ้นส่วนที่ไม่เกี่ยวข้อง* +*ไดอะแกรมนี้แสดงช่วงคะแนนจาก 0 ถึง 1 พร้อมเกณฑ์ขั้นต่ำที่ 0.5 ซึ่งกรองชิ้นที่ไม่เกี่ยวข้องออก* -คะแนนแบ่งเป็น: -- 0.7-1.0: เกี่ยวข้องสูง ตรงกันเป๊ะ -- 0.5-0.7: เกี่ยวข้อง มีบริบทดี -- ต่ำกว่า 0.5: ถูกคัดกรองออก ไม่เกี่ยวข้อง +คะแนนช่วง 0 ถึง 1: +- 0.7-1.0: เกี่ยวข้องสูง ตรงกันอย่างชัดเจน +- 0.5-0.7: เกี่ยวข้อง บริบทดี +- ต่ำกว่า 0.5: ถูกกรองออก เพราะไม่เหมือนกันมากเกินไป -ระบบจะดึงแต่ชิ้นที่มีคะแนนสูงกว่าเกณฑ์ขั้นต่ำเพื่อให้มั่นใจในคุณภาพ +ระบบจะเรียกคืนชิ้นที่มีคะแนนเกินเกณฑ์ขั้นต่ำเท่านั้น เพื่อรักษาคุณภาพ -Embeddings ทำงานได้ดีเมื่อความหมายกระจุกตัวได้ชัดเจน แต่ก็มีจุดอ่อน ไดอะแกรมด้านล่างแสดงรูปแบบความล้มเหลวทั่วไป — ชิ้นใหญ่เกินไปทำให้เวกเตอร์มัว ชิ้นเล็กเกินไม่มีบริบท คำที่กำกวมชี้ไปหลายกลุ่ม และการค้นหาตรงตัว (เช่น รหัส ID, หมายเลขชิ้นส่วน) ใช้ embeddings ไม่ได้เลย: +Embeddings ทำงานได้ดีเมื่อความหมายจัดกลุ่มชัดเจน แต่ก็มีจุดบอด ไดอะแกรมด้านล่างแสดงโหมดล้มเหลวทั่วไป — ชิ้นที่ใหญ่เกินไปจะสร้างเวกเตอร์ที่ไม่ชัดเจน ชิ้นเล็กเกินไปขาดบริบท คำที่คลุมเครือชี้ไปยังหลายกลุ่ม และการค้นหาตรง ๆ (ID, หมายเลขชิ้นส่วน) ไม่ทำงานกับ embeddings เลย: Embedding Failure Modes -*ไดอะแกรมนี้แสดงรูปแบบความล้มเหลวของ embedding ทั่วไป: ชิ้นใหญ่เกินไป ชิ้นเล็กเกินไป คำกำกวมที่ชี้หลายกลุ่ม และการค้นหาตรงตัวเช่น ID* +*ไดอะแกรมนี้แสดงโหมดล้มเหลวทั่วไปของ embeddings: ชิ้นใหญ่เกินไป, ชิ้นเล็กเกินไป, คำคลุมเครือที่ชี้ไปยังหลายกลุ่ม และการค้นหาตรงอย่าง ID* -### การเก็บในหน่วยความจำ +### การเก็บข้อมูลในหน่วยความจำ -โมดูลนี้ใช้การเก็บข้อมูลในหน่วยความจำเพื่อความง่าย เมื่อคุณรีสตาร์ทแอป เอกสารที่อัพโหลดจะหายไป ระบบจริงมักใช้ฐานข้อมูลแบบเวกเตอร์ที่เก็บถาวร เช่น Qdrant หรือ Azure AI Search +โมดูลนี้ใช้การเก็บข้อมูลในหน่วยความจำเพื่อความเรียบง่าย เมื่อคุณรีสตาร์ทแอปพลิเคชัน เอกสารที่อัปโหลดจะสูญหาย ระบบโปรดักชันจะใช้ฐานข้อมูลเวกเตอร์ถาวร เช่น Qdrant หรือ Azure AI Search -### การจัดการบริบทในหน้าต่าง +### การจัดการหน้าต่างบริบท -แต่ละโมเดลมีขอบเขตบริบทสูงสุด คุณไม่สามารถใส่ชิ้นทุกชิ้นจากเอกสารใหญ่ๆ ได้ ระบบจะดึงชิ้นที่เกี่ยวข้องสูงสุด N ชิ้น (ค่าสำเร็จรูปคือ 5) เพื่อความเหมาะสมกับขอบเขตและยังมีบริบทเพียงพอสำหรับคำตอบที่แม่นยำ +แต่ละโมเดลมีขนาดหน้าต่างบริบทสูงสุด คุณไม่สามารถใส่ชิ้นจากเอกสารใหญ่ทั้งหมดได้ ระบบจึงเรียกคืนชิ้นที่เกี่ยวข้องสูงสุด N ชิ้น (ตั้งค่าเริ่มต้นที่ 5) เพื่อให้อยู่ในขีดจำกัดและยังให้บริบทเพียงพอสำหรับคำตอบที่แม่นยำ -## เมื่อไหร่ที่ RAG สำคัญ +## เมื่อไหร่ที่ RAG มีความสำคัญ -RAG ไม่ใช่วิธีที่เหมาะสมเสมอไป ไกด์การตัดสินใจด้านล่างช่วยคุณประเมินว่าเมื่อไหร่ RAG จะเพิ่มมูลค่า และเมื่อไหร่ควรใช้วิธีที่ง่ายกว่า — เช่น การใส่เนื้อหาลงใน prompt โดยตรง หรือพึ่งพาความรู้ในตัวโมเดล: +RAG ไม่ใช่วิธีที่เหมาะสมเสมอไป คำแนะนำการตัดสินใจด้านล่างช่วยคุณกำหนดว่าเมื่อใดที่ RAG เพิ่มมูลค่า และเมื่อใดที่วิธีที่ง่ายกว่ — เช่น การรวมเนื้อหาโดยตรงในคำแจ้งหรือพึ่งพาความรู้ที่ฝังในโมเดล — ก็เพียงพอแล้ว: When to Use RAG -*ไดอะแกรมนี้แสดงไกด์การตัดสินใจว่าเมื่อไหร่ RAG จะเพิ่มมูลค่าและเมื่อไหร่ควรใช้วิธีที่ง่ายกว่า* +*ไดอะแกรมนี้แสดงคำแนะนำการตัดสินใจว่าควรใช้ RAG เมื่อใด และเมื่อใดที่วิธีง่าย ๆ ก็เพียงพอ* -## ขั้นตอนต่อไป +## ก้าวต่อไป -**โมดูลถัดไป:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**โมดูลถัดไป:** [04-tools - เอเจนต์ AI พร้อมเครื่องมือ](../04-tools/README.md) --- -**การนำทาง:** [← ก่อนหน้า: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [กลับสู่หน้าแรก](../README.md) | [ถัดไป: Module 04 - Tools →](../04-tools/README.md) +**นำทาง:** [← ก่อนหน้า: โมดูล 02 - การสร้างคำแจ้ง](../02-prompt-engineering/README.md) | [กลับสู่หลัก](../README.md) | [ถัดไป: โมดูล 04 - เครื่องมือ →](../04-tools/README.md) --- -**ข้อจำกัดความรับผิดชอบ**: -เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษาด้วย AI [Co-op Translator](https://github.com/Azure/co-op-translator) แม้ว่าพวกเราจะพยายามให้มีความถูกต้อง แต่โปรดทราบว่าการแปลอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ ในกรณีข้อมูลที่สำคัญ แนะนำให้ใช้บริการแปลโดยมนุษย์ผู้เชี่ยวชาญ พวกเราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดใด ๆ ที่อาจเกิดขึ้นจากการใช้การแปลนี้ +**ปฏิเสธความรับผิดชอบ**: +เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) ขณะที่เราพยายามให้ความถูกต้อง โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดที่เกิดขึ้นจากการใช้การแปลนี้ \ No newline at end of file diff --git a/translations/th/04-tools/README.md b/translations/th/04-tools/README.md index 21c13d753..914abbcd5 100644 --- a/translations/th/04-tools/README.md +++ b/translations/th/04-tools/README.md @@ -1,35 +1,35 @@ -# Module 04: ตัวแทน AI พร้อมเครื่องมือ +# Module 04: เอเจนต์ AI พร้อมเครื่องมือ ## สารบัญ -- [วิดีโอสาธิต](../../../04-tools) -- [สิ่งที่คุณจะได้เรียนรู้](../../../04-tools) -- [สิ่งที่ต้องมีพื้นฐานก่อน](../../../04-tools) -- [ทำความเข้าใจกับตัวแทน AI พร้อมเครื่องมือ](../../../04-tools) -- [การทำงานของการเรียกเครื่องมือ](../../../04-tools) - - [คำจำกัดความของเครื่องมือ](../../../04-tools) - - [การตัดสินใจ](../../../04-tools) - - [การดำเนินการ](../../../04-tools) - - [การสร้างการตอบสนอง](../../../04-tools) - - [สถาปัตยกรรม: การต่อสายอัตโนมัติของ Spring Boot](../../../04-tools) -- [การเชื่อมโยงเครื่องมือ](../../../04-tools) -- [รันแอปพลิเคชัน](../../../04-tools) -- [การใช้งานแอปพลิเคชัน](../../../04-tools) - - [ลองใช้เครื่องมือแบบง่าย](../../../04-tools) - - [ทดสอบการเชื่อมโยงเครื่องมือ](../../../04-tools) - - [ดูการไหลของการสนทนา](../../../04-tools) - - [ทดลองกับคำขอต่างๆ](../../../04-tools) -- [แนวคิดสำคัญ](../../../04-tools) - - [รูปแบบ ReAct (Reasoning and Acting)](../../../04-tools) - - [คำอธิบายของเครื่องมือสำคัญ](../../../04-tools) - - [การจัดการเซสชัน](../../../04-tools) - - [การจัดการข้อผิดพลาด](../../../04-tools) -- [เครื่องมือที่มีอยู่](../../../04-tools) -- [เมื่อไหร่ควรใช้ตัวแทนที่ใช้เครื่องมือ](../../../04-tools) -- [เครื่องมือเทียบกับ RAG](../../../04-tools) -- [ขั้นตอนต่อไป](../../../04-tools) - -## วิดีโอสาธิต +- [วิดีโอสอน](#วิดีโอสอน) +- [สิ่งที่คุณจะได้เรียนรู้](#สิ่งที่คุณจะได้เรียนรู้) +- [ข้อกำหนดพื้นฐาน](#ข้อกำหนดพื้นฐาน) +- [ความเข้าใจเกี่ยวกับเอเจนต์ AI พร้อมเครื่องมือ](#ความเข้าใจเกี่ยวกับเอเจนต์-ai-พร้อมเครื่องมือ) +- [วิธีการทำงานของการเรียกเครื่องมือ](#วิธีการทำงานของการเรียกเครื่องมือ) + - [คำนิยามของเครื่องมือ](#คำนิยามของเครื่องมือ) + - [การตัดสินใจ](#การตัดสินใจ) + - [การดำเนินการ](#การดำเนินการ) + - [การสร้างคำตอบ](#การสร้างคำตอบ) + - [สถาปัตยกรรม: การเชื่อมต่ออัตโนมัติของ Spring Boot](#สถาปัตยกรรม-การเชื่อมต่ออัตโนมัติของ-spring-boot) +- [การเชื่อมโยงเครื่องมือ](#การเชื่อมโยงเครื่องมือ) +- [รันแอปพลิเคชัน](#รันแอปพลิเคชัน) +- [การใช้งานแอปพลิเคชัน](#การใช้แอปพลิเคชัน) + - [ลองใช้เครื่องมืออย่างง่าย](#ลองใช้เครื่องมืออย่างง่าย) + - [ทดสอบการเชื่อมโยงเครื่องมือ](#ทดสอบการเชื่อมโยงเครื่องมือ) + - [ดูการไหลของการสนทนา](#ดูการไหลของบทสนทนา) + - [ทดลองกับคำขอต่าง ๆ](#ทดลองคำขอหลากหลาย) +- [แนวคิดสำคัญ](#แนวคิดสำคัญ) + - [รูปแบบ ReAct (เหตุผลและการกระทำ)](#รูปแบบ-react-การให้เหตุผลและการกระทำ) + - [ความสำคัญของคำอธิบายเครื่องมือ](#คำอธิบายเครื่องมือสำคัญ) + - [การจัดการเซสชัน](#การจัดการเซสชัน) + - [การจัดการข้อผิดพลาด](#การจัดการข้อผิดพลาด) +- [เครื่องมือที่มีให้ใช้งาน](#เครื่องมือที่มีให้ใช้งาน) +- [เมื่อใดควรใช้เอเจนต์ที่ใช้เครื่องมือ](#เมื่อใดควรใช้เอเจนต์ที่ใช้เครื่องมือ) +- [เครื่องมือ vs RAG](#เครื่องมือกับ-rag) +- [ขั้นตอนถัดไป](#ขั้นตอนถัดไป) + +## วิดีโอสอน รับชมเซสชันสดนี้ที่อธิบายวิธีเริ่มต้นกับโมดูลนี้: @@ -37,48 +37,48 @@ ## สิ่งที่คุณจะได้เรียนรู้ -จนถึงตอนนี้ คุณได้เรียนรู้วิธีสนทนากับ AI การจัดโครงสร้างพรอมต์อย่างมีประสิทธิภาพ และการทำให้การตอบสนองอ้างอิงกับเอกสารของคุณ แต่ยังมีข้อจำกัดพื้นฐานอยู่: แบบจำลองภาษาเพียงสามารถสร้างข้อความเท่านั้น มันไม่สามารถตรวจสอบสภาพอากาศ ทำการคำนวณ สืบค้นฐานข้อมูล หรือโต้ตอบกับระบบภายนอกได้ +จนถึงตอนนี้ คุณได้เรียนรู้วิธีพูดคุยกับ AI การสร้างโครงสร้างพรอมต์อย่างมีประสิทธิภาพ และการยึดคำตอบให้เชื่อมโยงกับเอกสารของคุณแล้ว แต่ยังมีข้อจำกัดพื้นฐาน คือ โมเดลภาษาสามารถสร้างข้อความได้เท่านั้น พวกมันไม่สามารถตรวจสอบสภาพอากาศ คำนวณข้อมูล สืบค้นฐานข้อมูล หรือโต้ตอบกับระบบภายนอกได้ -เครื่องมือเปลี่ยนสิ่งนี้ โดยการให้แบบจำลองสามารถเข้าถึงฟังก์ชันที่สามารถเรียกใช้ได้ คุณเปลี่ยนจากการเป็นเครื่องสร้างข้อความเป็นตัวแทนที่สามารถดำเนินการต่าง ๆ ได้ แบบจำลองจะตัดสินใจเมื่อไหร่ที่มันต้องใช้เครื่องมือ เครื่องมือใดที่ใช้ และส่งพารามิเตอร์อะไร โค้ดของคุณจะดำเนินการฟังก์ชันและคืนผลลัพธ์ แบบจำลองจะนำผลลัพธ์นั้นมารวมในคำตอบ +เครื่องมือช่วยเปลี่ยนเรื่องนี้ โดยการให้โมเดลเข้าถึงฟังก์ชันที่มันเรียกใช้ได้ คุณจะเปลี่ยนมันจากเครื่องสร้างข้อความให้เป็นเอเจนต์ที่สามารถดำเนินการได้ โมเดลจะตัดสินใจว่าเมื่อไหร่ที่ต้องใช้เครื่องมือ เครื่องมือใดที่จะใช้ และต้องส่งพารามิเตอร์อะไร โค้ดของคุณจะทำการเรียกฟังก์ชันและส่งผลลัพธ์กลับมา โมเดลจะรวมผลลัพธ์นั้นลงในคำตอบของมัน -## สิ่งที่ต้องมีพื้นฐานก่อน +## ข้อกำหนดพื้นฐาน -- เสร็จสิ้น [Module 01 - Introduction](../01-introduction/README.md) (ทรัพยากร Azure OpenAI ถูกติดตั้งแล้ว) -- แนะนำให้เสร็จสิ้นโมดูลก่อนหน้า (โมดูลนี้อ้างอิงแนวคิด [RAG จาก Module 03](../03-rag/README.md) ในการเปรียบเทียบ Tools vs RAG) -- ไฟล์ `.env` อยู่ในไดเรกทอรีหลักพร้อมข้อมูลรับรอง Azure (สร้างด้วยคำสั่ง `azd up` ใน Module 01) +- ผ่าน [Module 01 - Introduction](../01-introduction/README.md) แล้ว (ได้ทำการปรับใช้ทรัพยากร Azure OpenAI) +- ผ่านโมดูลก่อนหน้าที่แนะนำ (โมดูลนี้อ้างอิงถึง [แนวคิด RAG จาก Module 03](../03-rag/README.md) ในการเปรียบเทียบ Tools vs RAG) +- มีไฟล์ `.env` ในไดเรกทอรีรากที่มีข้อมูลประจำตัว Azure (สร้างได้โดยคำสั่ง `azd up` ใน Module 01) -> **หมายเหตุ:** หากยังไม่เสร็จสิ้น Module 01 ให้ทำตามคำแนะนำการติดตั้งในนั้นก่อน +> **หมายเหตุ:** หากคุณยังไม่ได้ผ่าน Module 01 โปรดทำตามคำแนะนำการปรับใช้ที่นั่นก่อน -## ทำความเข้าใจกับตัวแทน AI พร้อมเครื่องมือ +## ความเข้าใจเกี่ยวกับเอเจนต์ AI พร้อมเครื่องมือ -> **📝 หมายเหตุ:** คำว่า "agents" ในโมดูลนี้หมายถึงผู้ช่วย AI ที่ได้รับการเสริมความสามารถด้วยฟีเจอร์การเรียกเครื่องมือ ซึ่งแตกต่างจากรูปแบบ **Agentic AI** (ตัวแทนอัตโนมัติที่มีการวางแผน ความจำ และการให้เหตุผลหลายขั้นตอน) ที่เราจะพูดถึงใน [Module 05: MCP](../05-mcp/README.md) +> **📝 หมายเหตุ:** คำว่า "เอเจนต์" ในโมดูลนี้หมายถึงผู้ช่วย AI ที่เพิ่มความสามารถในการเรียกใช้เครื่องมือ ซึ่งแตกต่างจากรูปแบบ **Agentic AI** (เอเจนต์อิสระที่มีการวางแผน ความจำ และการใช้เหตุผลหลายขั้นตอน) ซึ่งเราจะพูดถึงใน [Module 05: MCP](../05-mcp/README.md) -ไม่มีเครื่องมือ แบบจำลองภาษาเพียงสร้างข้อความจากข้อมูลการฝึกฝน ถามเรื่องสภาพอากาศปัจจุบัน มันต้องเดา ให้เครื่องมือแก่มัน มันสามารถเรียก API สภาพอากาศ ทำคำนวณ หรือสืบค้นฐานข้อมูล — แล้วนำผลจริงเหล่านั้นมารวมในคำตอบ +ถ้าไม่มีเครื่องมือ โมเดลภาษาจะสร้างข้อความได้จากข้อมูลที่ฝึกมาเท่านั้น ถามมันถึงสภาพอากาศตอนนี้ มันก็ต้องเดาให้ ถ้ามีเครื่องมือ มันสามารถเรียกใช้ API สภาพอากาศ คำนวณ หรือสืบค้นฐานข้อมูล — แล้วสอดแทรกผลลัพธ์จริงเหล่านั้นลงในคำตอบของมัน Without Tools vs With Tools -*ไม่มีเครื่องมือ แบบจำลองจึงคาดเดา — มีเครื่องมือแล้วมันสามารถเรียก API, ทำคำนวณ และส่งข้อมูลเรียลไทม์ได้* +*ถ้าไม่มีเครื่องมือ โมเดลจะเดาเท่านั้น — แต่ถ้ามีเครื่องมือ มันจะเรียก API รันการคำนวณ และส่งข้อมูลเรียลไทม์กลับมา* -ตัวแทน AI พร้อมเครื่องมือทำงานตามรูปแบบ **Reasoning and Acting (ReAct)** แบบจำลองไม่ได้แค่ตอบ — แต่มันคิดถึงสิ่งที่ต้องการ ทำการเรียกเครื่องมือ ดูผลลัพธ์ แล้วตัดสินใจว่าจะทำอีกหรือส่งคำตอบสุดท้าย: +เอเจนต์ AI พร้อมเครื่องมือทำตามรูปแบบ **Reasoning and Acting (ReAct)** โมเดลไม่ได้แค่ตอบกลับ — แต่คิดวิเคราะห์ว่าตัวเองต้องการอะไร ดำเนินการโดยเรียกเครื่องมือ ตรวจสอบผลลัพธ์ แล้วตัดสินใจว่าจะดำเนินการต่อหรือตอบคำถามขั้นสุดท้าย: -1. **วิเคราะห์** — ตัวแทนวิเคราะห์คำถามผู้ใช้และกำหนดว่าต้องการข้อมูลอะไร -2. **ลงมือทำ** — ตัวแทนเลือกเครื่องมือที่เหมาะสม สร้างพารามิเตอร์ที่ถูกต้อง และเรียกเครื่องมือ -3. **สังเกต** — ตัวแทนรับผลลัพธ์จากเครื่องมือและประเมินผล -4. **ทำซ้ำหรือตอบ** — หากต้องการข้อมูลเพิ่ม ตัวแทนวนกลับ; หากไม่ใช่ จะสร้างคำตอบในภาษาธรรมชาติ +1. **Reason** — เอเจนต์วิเคราะห์คำถามของผู้ใช้และกำหนดข้อมูลที่ต้องการ +2. **Act** — เอเจนต์เลือกเครื่องมือที่เหมาะสม สร้างพารามิเตอร์ที่ถูกต้อง และเรียกใช้เครื่องมือนั้น +3. **Observe** — เอเจนต์รับผลลัพธ์จากเครื่องมือและประเมินผล +4. **Repeat or Respond** — ถ้าต้องการข้อมูลเพิ่ม เอเจนต์จะวนกลับไปขั้นตอนก่อนหน้า มิฉะนั้นจะสร้างคำตอบเป็นภาษาธรรมชาติ ReAct Pattern -*วงจร ReAct — ตัวแทนคิด วิเคราะห์ว่าจะทำอะไร ลงมือเรียกเครื่องมือ สังเกตผล และวนจนพร้อมตอบคำถามสุดท้าย* +*วงจร ReAct — เอเจนต์คิดวิเคราะห์ว่าจะทำอะไร ดำเนินการโดยเรียกเครื่องมือ ตรวจสอบผลลัพธ์ และวนลูปจนกว่าจะตอบคำถามได้* -สิ่งนี้เกิดขึ้นโดยอัตโนมัติ คุณกำหนดเครื่องมือและคำอธิบายแบบจำลองจัดการการตัดสินใจเมื่อต้องใช้และใช้อย่างไร +สิ่งนี้เกิดขึ้นโดยอัตโนมัติ คุณกำหนดเครื่องมือและคำอธิบายของมัน โมเดลจะจัดการการตัดสินใจว่าจะใช้เครื่องมือเมื่อไหร่และอย่างไร -## การทำงานของการเรียกเครื่องมือ +## วิธีการทำงานของการเรียกเครื่องมือ -### คำจำกัดความของเครื่องมือ +### คำนิยามของเครื่องมือ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -คุณกำหนดฟังก์ชันพร้อมคำอธิบายและพารามิเตอร์ที่ชัดเจน แบบจำลองจะเห็นคำอธิบายนี้ในพรอมต์ระบบและเข้าใจว่าเครื่องมือแต่ละตัวทำอะไร +คุณกำหนดฟังก์ชันด้วยคำอธิบายและพารามิเตอร์ที่ชัดเจน โมเดลเห็นคำอธิบายเหล่านี้ในพรอมต์ระบบและเข้าใจว่าเครื่องมือแต่ละตัวทำอะไร ```java @Component @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// ผู้ช่วยถูกตั้งค่าโดยอัตโนมัติโดย Spring Boot ด้วย: -// - bean ChatModel -// - ทุกเมธอด @Tool จากคลาส @Component +// ผู้ช่วยถูกเชื่อมต่อโดยอัตโนมัติด้วย Spring Boot กับ: +// - บีน ChatModel +// - เมธอด @Tool ทั้งหมดจากคลาส @Component // - ChatMemoryProvider สำหรับการจัดการเซสชัน ``` -แผนภาพด้านล่างแสดงการกำกับทุกส่วนและแสดงวิธีที่แต่ละส่วนช่วยให้ AI เข้าใจเมื่อเรียกใช้เครื่องมือและส่งอากิวเมนต์อะไร: +แผนภาพด้านล่างแจกแจงทุกแอนโนเทชันและแสดงให้เห็นว่าแต่ละส่วนช่วยให้ AI เข้าใจว่าเมื่อไหร่ต้องเรียกเครื่องมือและส่งอาร์กิวเมนต์อะไร: Anatomy of Tool Definitions -*โครงสร้างคำจำกัดความเครื่องมือ — @Tool บอก AI เมื่อใช้เครื่องมือ, @P อธิบายแต่ละพารามิเตอร์, และ @AiService ต่อสายทุกอย่างตอนเริ่มทำงาน* +*โครงสร้างของการนิยามเครื่องมือ — @Tool บอก AI ว่าจะใช้เมื่อไหร่, @P อธิบายแต่ละพารามิเตอร์, และ @AiService เชื่อมทุกอย่างเข้าด้วยกันตอนเริ่มต้น* -> **🤖 ลองกับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) และถาม: -> - "ฉันจะรวม API สภาพอากาศจริงอย่าง OpenWeatherMap แทนข้อมูลจำลองได้อย่างไร?" -> - "อะไรคือคำอธิบายเครื่องมือที่ดีที่จะช่วยให้ AI ใช้มันได้ถูกต้อง?" -> - "ฉันควรจัดการกับข้อผิดพลาด API และข้อจำกัดอัตราอย่างไรเมื่อสร้างเครื่องมือ?" +> **🤖 ลองใช้กับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) และถาม: +> - "จะผนวก API สภาพอากาศจริงอย่าง OpenWeatherMap แทนข้อมูลจำลองอย่างไร?" +> - "อะไรคือคำอธิบายเครื่องมือที่ดีที่จะช่วย AI ใช้งานได้ถูกต้อง?" +> - "จะจัดการกับข้อผิดพลาด API และข้อจำกัดความถี่อย่างไรในเครื่องมือ?" ### การตัดสินใจ -เมื่อผู้ใช้ถามว่า "สภาพอากาศที่ซีแอตเทิลเป็นอย่างไร?" แบบจำลองไม่ได้สุ่มเลือกเครื่องมือ มันเปรียบเทียบเจตนาผู้ใช้กับคำอธิบายเครื่องมือทั้งหมดที่เข้าถึงได้, ให้คะแนนความเกี่ยวข้อง และเลือกอันที่เหมาะสมที่สุด แล้วสร้างคำเรียกฟังก์ชันที่มีพารามิเตอร์ถูกต้อง — ในกรณีนี้ตั้ง `location` เป็น `"Seattle"` +เมื่อผู้ใช้ถามว่า "สภาพอากาศที่ซีแอตเทิลเป็นอย่างไร?" โมเดลไม่ได้เลือกเครื่องมือแบบสุ่ม แต่มันเปรียบเทียบเจตนาของผู้ใช้กับคำอธิบายเครื่องมือทุกชิ้นที่มันมีคะแนนความเกี่ยวข้อง แล้วเลือกเครื่องมือที่เหมาะสมที่สุด จากนั้นจะสร้างการเรียกฟังก์ชันที่มีโครงสร้างพร้อมพารามิเตอร์ที่ถูกต้อง ในกรณีนี้คือการตั้ง `location` เป็น `"Seattle"` -ถ้าไม่มีเครื่องมือไหนตรงกับคำขอผู้ใช้ แบบจำลองจะตอบจากความรู้ของตัวเอง หากมีหลายเครื่องมือเหมาะสม มันจะเลือกอันที่เจาะจงที่สุด +ถ้าไม่มีเครื่องมือใดตรงกับคำขอของผู้ใช้ โมเดลจะตอบจากความรู้ของตัวเอง ถ้ามีหลายเครื่องมือที่ตรงกัน มันจะเลือกตัวที่เฉพาะเจาะจงที่สุด How the AI Decides Which Tool to Use -*แบบจำลองประเมินเครื่องมือทุกตัวเทียบกับเจตนาผู้ใช้และเลือกอันที่ตรงที่สุด — นี่คือเหตุผลที่การเขียนคำอธิบายเครื่องมือให้ชัดเจนและเฉพาะเจาะจงสำคัญ* +*โมเดลประเมินเครื่องมือทุกตัวเทียบกับเจตนาผู้ใช้และเลือกคนที่เหมาะสมที่สุด — นี่คือเหตุผลว่าทำไมการเขียนคำอธิบายเครื่องมือให้ชัดเจนและเฉพาะเจาะจงจึงสำคัญ* ### การดำเนินการ [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot ต่อสาย `@AiService` แบบประกาศกับเครื่องมือที่ลงทะเบียนทั้งหมดและ LangChain4j ดำเนินการเรียกเครื่องมือโดยอัตโนมัติ เบื้องหลัง การเรียกเครื่องมือครบวงจรผ่านหกขั้นตอน — จากคำถามภาษาธรรมชาติของผู้ใช้จนถึงคำตอบภาษาธรรมชาติ: +Spring Boot เชื่อมต่ออัตโนมัติอินเทอร์เฟซ `@AiService` กับเครื่องมือที่ลงทะเบียนทั้งหมด และ LangChain4j ดำเนินการเรียกเครื่องมือโดยอัตโนมัติ เบื้องหลัง การเรียกใช้เครื่องมือหนึ่งครั้งไหลผ่านหกขั้นตอน — จากคำถามจากผู้ใช้จนถึงคำตอบภาษาธรรมชาติ: Tool Calling Flow -*ไหลตั้งแต่ต้นจนจบ — ผู้ใช้ถามคำถาม, แบบจำลองเลือกเครื่องมือ, LangChain4j ดำเนินการ, และแบบจำลองรวมผลลัพธ์ในคำตอบ* +*การไหลตั้งแต่ต้นจนจบ — ผู้ใช้ถามคำถาม, โมเดลเลือกเครื่องมือ, LangChain4j ดำเนินการ, และโมเดลสอดแทรกผลลัพธ์ลงในคำตอบ* -ถ้าคุณรัน [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ใน Module 00 คุณจะเห็นรูปแบบนี้ทำงาน — เครื่องมือ `Calculator` ถูกเรียกแบบเดียวกัน แผนภาพลำดับด้านล่างแสดงสิ่งที่เกิดขึ้นภายในในตอนนั้น: +เบื้องหลัง `AiServices` รันลูปการเรียกเครื่องมือเดียวกันสำหรับเครื่องมือใด ๆ — ที่นี่แสดงตัวอย่างด้วย `Calculator` ลำดับไดอะแกรมด้านล่างแสดงสิ่งที่เกิดขึ้นจริงภายใต้ระบบ: Tool Calling Sequence Diagram -*ลูปเรียกเครื่องมือจากเดโม Quick Start — `AiServices` ส่งข้อความและสเกม่าเครื่องมือให้ LLM, LLM ตอบด้วยฟังก์ชันเรียกอย่าง `add(42, 58)`, LangChain4j ดำเนินการเมธอด `Calculator` ในเครื่อง และส่งผลลัพธ์กลับเพื่อคำตอบสุดท้าย* +*ลูปการเรียกเครื่องมือ — `AiServices` ส่งข้อความและสกีมาของเครื่องมือไปยัง LLM, LLM ตอบกลับด้วยการเรียกฟังก์ชัน เช่น `add(42, 58)`, LangChain4j เรียกใช้เมธอด `Calculator` ภายในเครื่อง และส่งผลลัพธ์กลับเพื่อคำตอบขั้นสุดท้าย* -> **🤖 ลองกับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) และถาม: -> - "รูปแบบ ReAct ทำงานอย่างไรและทำไมจึงมีประสิทธิภาพสำหรับตัวแทน AI?" -> - "ตัวแทนตัดสินใจเลือกเครื่องมือและลำดับการใช้เครื่องมืออย่างไร?" -> - "ถ้าการดำเนินการเครื่องมือล้มเหลว คืออะไรและฉันควรจัดการข้อผิดพลาดอย่างไรให้มั่นคง?" +> **🤖 ลองใช้กับ [GitHub Copilot](https://github.com/features/copilot) Chat:** เปิด [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) และถาม: +> - "รูปแบบ ReAct ทำงานอย่างไร และทำไมถึงมีประสิทธิผลสำหรับเอเจนต์ AI?" +> - "เอเจนต์ตัดสินใจเลือกเครื่องมือและลำดับการใช้งานอย่างไร?" +> - "ถ้าเรียกใช้เครื่องมือแล้วล้มเหลว จะจัดการข้อผิดพลาดอย่างไรให้แข็งแกร่ง?" -### การสร้างการตอบสนอง +### การสร้างคำตอบ -แบบจำลองรับข้อมูลสภาพอากาศและจัดรูปแบบเป็นคำตอบภาษาธรรมชาติสำหรับผู้ใช้ +โมเดลได้รับข้อมูลสภาพอากาศและจัดรูปแบบให้เป็นภาษาธรรมชาติเพื่อตอบผู้ใช้ -### สถาปัตยกรรม: การต่อสายอัตโนมัติของ Spring Boot +### สถาปัตยกรรม: การเชื่อมต่ออัตโนมัติของ Spring Boot -โมดูลนี้ใช้การผสมผสาน LangChain4j กับ Spring Boot ผ่านอินเทอร์เฟซ `@AiService` แบบประกาศ ตอนเริ่มทำงาน Spring Boot จะค้นหา `@Component` ทุกตัวที่มีเมธอด `@Tool`, bean `ChatModel`, และ `ChatMemoryProvider` — แล้วต่อสายทั้งหมดเข้ากับอินเทอร์เฟซ `Assistant` เดียวโดยไม่มีโค้ดซ้ำซ้อน +โมดูลนี้ใช้การผสาน LangChain4j กับ Spring Boot โดยใช้ `@AiService` อินเทอร์เฟซแบบประกาศ Spring Boot จะค้นหา `@Component` ที่มีเมธอด `@Tool` ทั้งหมด, bean ของ `ChatModel` และ `ChatMemoryProvider` — จากนั้นเชื่อมต่อทั้งหมดเข้ากับอินเทอร์เฟซ `Assistant` ตัวเดียวโดยไม่มีโค้ดซ้ำซ้อน Spring Boot Auto-Wiring Architecture -*อินเทอร์เฟซ @AiService รวม ChatModel, คอมโพเนนต์เครื่องมือ และ memory provider — Spring Boot ต่อสายทั้งหมดให้โดยอัตโนมัติ* +*อินเทอร์เฟซ @AiService เชื่อม ChatModel, คอมโพเนนต์เครื่องมือ และ memory provider — Spring Boot จัดการการเชื่อมต่อทั้งหมดโดยอัตโนมัติ* -นี่คือวงจรคำขอสมบูรณ์ในรูปแบบแผนภาพลำดับ — จาก HTTP request ผ่านคอนโทรลเลอร์, เซอร์วิส, และพร็อกซีที่ต่อสายอัตโนมัติ จนถึงการเรียกเครื่องมือและส่งผลลัพธ์กลับ: +นี่คือลำดับชีวิตคำขอเต็มรูปแบบในรูปแบบลำดับภาพ — จาก HTTP request ผ่าน controller, service, proxy ที่เชื่อมต่ออัตโนมัติ กระทั่งการเรียกเครื่องมือและกลับมา: Spring Boot Tool Calling Sequence -*วงจรคำขอ Spring Boot ครบถ้วน — HTTP request ไหลผ่านคอนโทรลเลอร์และเซอร์วิสเข้าสู่พร็อกซี Assistant ที่ต่อสายอัตโนมัติ, จัดการ LLM และการเรียกเครื่องมือโดยอัตโนมัติ* +*ลำดับชีวิตคำขอ Spring Boot แบบสมบูรณ์ — HTTP request ไหลผ่าน controller และ service ไปยัง proxy Assistant ที่เชื่อมต่ออัตโนมัติซึ่งควบคุม LLM และการเรียกเครื่องมือโดยอัตโนมัติ* -ข้อดีหลักของวิธีนี้: +ประโยชน์หลักของวิธีนี้: -- **ต่อสายอัตโนมัติของ Spring Boot** — ฉีด ChatModel และเครื่องมือโดยอัตโนมัติ -- **รูปแบบ @MemoryId** — จัดการหน่วยความจำตามเซสชันอัตโนมัติ -- **อินสแตนซ์เดียว** — สร้าง Assistant ครั้งเดียวใช้ซ้ำเพื่อประสิทธิภาพดีขึ้น -- **การดำเนินการปลอดภัยตามชนิด** — เรียกเมธอด Java โดยตรงพร้อมการแปลงชนิดข้อมูล -- **จัดการหลายรอบอัตโนมัติ** — รองรับการเชื่อมโยงเครื่องมือโดยอัตโนมัติ -- **ไม่มีโค้ดซ้ำซ้อน** — ไม่ต้องเรียก `AiServices.builder()` หรือจัดการ HashMap เอง +- **การเชื่อมต่ออัตโนมัติของ Spring Boot** — ฉีด ChatModel และเครื่องมือโดยอัตโนมัติ +- **รูปแบบ @MemoryId** — การจัดการความจำตามเซสชันโดยอัตโนมัติ +- **สร้างอินสแตนซ์เดียว** — สร้าง Assistant ครั้งเดียวใช้งานซ้ำได้เพื่อประสิทธิภาพที่ดีกว่า +- **การเรียกใช้งานแบบ type-safe** — เรียกเมธอด Java โดยตรงพร้อมแปลงประเภทข้อมูล +- **การประสานงานแบบหลายรอบ** — รองรับการเชื่อมโยงเครื่องมือโดยอัตโนมัติ +- **ศูนย์โค้ดซ้ำซ้อน** — ไม่มีการเรียก `AiServices.builder()` ด้วยตนเองหรือการจัดการแฮชแมพความจำ -วิธีการอื่น (เรียก `AiServices.builder()` เอง) ใช้โค้ดมากกว่าและไม่มีประโยชน์จากการผสานกับ Spring Boot +วิธีการแบบอื่น ๆ (เรียก `AiServices.builder()` ด้วยมือ) ต้องเขียนโค้ดมากขึ้นและพลาดประโยชน์ของการรวมกับ Spring Boot ## การเชื่อมโยงเครื่องมือ -**การเชื่อมโยงเครื่องมือ** — พลังจริงของตัวแทนที่ใช้เครื่องมือแสดงเมื่อคำถามหนึ่งต้องใช้หลายเครื่องมือ ถามว่า "สภาพอากาศที่ซีแอตเทิลในองศาฟาเรนไฮต์เป็นอย่างไร?" ตัวแทนจะเชื่อมโยงเครื่องมือสองตัวโดยอัตโนมัติ: เรียก `getCurrentWeather` เพื่อรับอุณหภูมิในเซลเซียส จากนั้นส่งค่าดังกล่าวไปยัง `celsiusToFahrenheit` เพื่อแปลง — ทั้งหมดในรอบสนทนาเดียว +**การเชื่อมโยงเครื่องมือ** — พลังที่แท้จริงของเอเจนต์ที่ใช้เครื่องมือถูกแสดงออกเมื่อคำถามเดียวต้องใช้หลายเครื่องมือ ลองถามว่า "สภาพอากาศที่ซีแอตเทิลในหน่วยฟาเรนไฮต์เป็นอย่างไร?" เอเจนต์จะเชื่อมต่อสองเครื่องมือโดยอัตโนมัติ: เรียก `getCurrentWeather` เพื่อรับอุณหภูมิในเซลเซียส จากนั้นส่งค่าดังกล่าวไปยัง `celsiusToFahrenheit` เพื่อแปลงหน่วย — ทั้งหมดนี้ในรอบการสนทนาเดียว Tool Chaining Example -*การเชื่อมโยงเครื่องมือในงานจริง — ตัวแทนเรียก getCurrentWeather ก่อน จากนั้นส่งผลลัพธ์เซลเซียสไปยัง celsiusToFahrenheit และให้คำตอบที่รวมกัน* +*การเชื่อมโยงเครื่องมือในปฏิบัติ — เอเจนต์เรียก getCurrentWeather ก่อน แล้วนำผลลัพธ์เซลเซียสไปผ่าน celsiusToFahrenheit และตอบคำถามรวมกัน* -**การล้มเหลวอย่างอ่อนโยน** — ถามถึงสภาพอากาศในเมืองที่ไม่มีในข้อมูลจำลอง เครื่องมือจะส่งข้อความผิดพลาดและ AI อธิบายว่าช่วยไม่ได้ แทนที่จะล่ม เครื่องมือล้มเหลวอย่างปลอดภัย แผนภาพด้านล่างเปรียบเทียบสองวิธี — การจัดการข้อผิดพลาดอย่างเหมาะสม ตัวแทนจับข้อผิดพลาดและตอบกลับให้ความช่วยเหลือ ในขณะที่ไม่มี จะทำให้แอปล่มทั้งหมด: +**การล้มเหลวอย่างอ่อนโยน** — ลองถามหาสภาพอากาศในเมืองที่ไม่มีในข้อมูลจำลอง เครื่องมือจะส่งข้อความแสดงข้อผิดพลาด และ AI จะอธิบายว่ามันไม่สามารถช่วยได้แทนที่จะล่ม แอปพลิเคชันปลอดภัยจากการล้มเหลว แผนภาพด้านล่างเปรียบเทียบสองวิธี — เมื่อจัดการข้อผิดพลาดได้ดี เอเจนต์จับข้อยกเว้นและตอบกลับอย่างช่วยเหลือ ในขณะที่ถ้าไม่จัดการ แอปพลิเคชันจะล่มทั้งระบบ: Error Handling Flow -*เมื่อเครื่องมือเกิดข้อผิดพลาด ตัวแทนจับข้อผิดพลาดและตอบด้วยคำอธิบายที่ช่วยเหลือแทนการล่ม* +*เมื่อเครื่องมือผิดพลาด เอเจนต์จับข้อผิดพลาดและตอบกลับพร้อมคำอธิบายอย่างช่วยเหลือแทนที่จะล่ม* -สิ่งนี้เกิดขึ้นในรอบสนทนาเดียว ตัวแทนจัดการการเรียกเครื่องมือหลายตัวโดยอัตโนมัติ +สิ่งนี้เกิดขึ้นในรอบการสนทนาเดียว เอเจนต์ประสานการเรียกเครื่องมือหลายครั้งโดยอัตโนมัติ ## รันแอปพลิเคชัน -**ตรวจสอบการติดตั้ง:** +**ตรวจสอบการปรับใช้:** -ตรวจสอบว่าไฟล์ `.env` อยู่ในไดเรกทอรีหลักพร้อมข้อมูลระบุตัวตน Azure (สร้างใน Module 01) รันคำสั่งนี้จากไดเรกทอรีโมดูล (`04-tools/`): +ตรวจสอบให้แน่ใจว่าไฟล์ `.env` อยู่ในไดเรกทอรีรากและมีข้อมูลประจำตัว Azure (ซึ่งสร้างใน Module 01) รันคำสั่งนี้จากไดเรกทอรีโมดูล (`04-tools/`): **Bash:** ```bash @@ -207,28 +207,28 @@ Get-Content ..\.env # ควรแสดง AZURE_OPENAI_ENDPOINT, API_KEY, DEP **เริ่มแอปพลิเคชัน:** -> **หมายเหตุ:** หากคุณเริ่มแอปทั้งหมดด้วยคำสั่ง `./start-all.sh` จากไดเรกทอรีหลักแล้ว (ตามคำแนะนำใน Module 01) โมดูลนี้จะรันอยู่ที่พอร์ต 8084 คุณสามารถข้ามคำสั่งเริ่มด้านล่างและไปที่ http://localhost:8084 ได้เลย +> **หมายเหตุ:** หากคุณเริ่มแอปพลิเคชันทั้งหมดด้วย `./start-all.sh` จากไดเรกทอรีราก (ตามที่อธิบายใน Module 01) โมดูลนี้จะทำงานอยู่บนพอร์ต 8084 แล้ว คุณสามารถข้ามคำสั่งเริ่มด้านล่างและไปที่ http://localhost:8084 ได้เลย **ตัวเลือก 1: ใช้ Spring Boot Dashboard (แนะนำสำหรับผู้ใช้ VS Code)** -Dev container มีส่วนเสริม Spring Boot Dashboard ซึ่งให้ส่วนติดต่อผู้ใช้แบบกราฟิกสำหรับจัดการแอป Spring Boot ทุกตัว คุณจะพบได้ในแถบกิจกรรมด้านซ้ายของ VS Code (ดูไอคอน Spring Boot) +dev container มีส่วนขยาย Spring Boot Dashboard ที่ให้หน้าจอจัดการแอป Spring Boot ทั้งหมด คุณสามารถหาได้ที่แถบกิจกรรมด้านซ้ายของ VS Code (มองหาไอคอน Spring Boot) จาก Spring Boot Dashboard คุณสามารถ: -- ดูแอป Spring Boot ทั้งหมดใน workspace -- เริ่ม/หยุดแอปได้ด้วยคลิกเดียว -- ดูล็อกแอปแบบเรียลไทม์ -- ตรวจสอบสถานะแอป -เพียงคลิกปุ่มเล่นถัดจาก "tools" เพื่อเริ่มโมดูลนี้ หรือเริ่มทุกโมดูลพร้อมกัน +- ดูแอป Spring Boot ทั้งหมดที่มีในพื้นที่ทำงาน +- สตาร์ท/หยุดแอปด้วยคลิกเดียว +- ดูบันทึกของแอปแบบเรียลไทม์ +- ติดตามสถานะของแอป -นี่คือรูปลักษณ์ของ Spring Boot Dashboard ใน VS Code: +เพียงคลิกปุ่มเล่นข้าง ๆ "tools" เพื่อเริ่มโมดูลนี้ หรือเริ่มทุกโมดูลพร้อมกัน +นี่คือลักษณะของ Spring Boot Dashboard ใน VS Code: Spring Boot Dashboard -*Spring Boot Dashboard ใน VS Code — เริ่ม หยุด และตรวจสอบโมดูลทั้งหมดจากที่เดียว* +*แดชบอร์ด Spring Boot ใน VS Code — เริ่มต้น หยุด และตรวจสอบโมดูลทั้งหมดจากที่เดียว* -**ตัวเลือกที่ 2: ใช้สคริปต์เชลล์** +**ตัวเลือกที่ 2: การใช้สคริปต์เชลล์** -เริ่มเว็บแอปพลิเคชันทั้งหมด (โมดูล 01-04): +เริ่มต้นเว็บแอปพลิเคชันทั้งหมด (โมดูล 01-04): **Bash:** ```bash @@ -238,11 +238,11 @@ cd .. # จากไดเรกทอรีรูท **PowerShell:** ```powershell -cd .. # จากไดเรกทอรีรูท +cd .. # จากไดเรกทอรีราก .\start-all.ps1 ``` -หรือเริ่มเพียงโมดูลนี้: +หรือเริ่มต้นแค่โมดูลนี้: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -สคริปต์ทั้งสองโหลดค่าตัวแปรสภาพแวดล้อมจากไฟล์ `.env` ที่รูทโดยอัตโนมัติ และจะคอมไพล์ JAR หากยังไม่มี +ทั้งสองสคริปต์จะโหลดตัวแปรสิ่งแวดล้อมจากไฟล์ `.env` ที่รูทโดยอัตโนมัติและจะสร้าง JAR ถ้ายังไม่มีอยู่ -> **หมายเหตุ:** หากคุณต้องการคอมไพล์ทุกโมดูลด้วยตัวเองก่อนเริ่ม: +> **หมายเหตุ:** ถ้าคุณต้องการสร้างโมดูลทั้งหมดด้วยตนเองก่อนเริ่ม: > > **Bash:** > ```bash @@ -278,110 +278,110 @@ cd 04-tools **Bash:** ```bash -./stop.sh # เพียงโมดูลนี้ +./stop.sh # โมดูลนี้เท่านั้น # หรือ -cd .. && ./stop-all.sh # ทุกโมดูล +cd .. && ./stop-all.sh # โมดูลทั้งหมด ``` **PowerShell:** ```powershell -.\stop.ps1 # เฉพาะโมดูลนี้ +.\stop.ps1 # โมดูลนี้เท่านั้น # หรือ cd ..; .\stop-all.ps1 # ทุกโมดูล ``` -## การใช้งานแอปพลิเคชัน +## การใช้แอปพลิเคชัน -แอปพลิเคชันมีอินเทอร์เฟซเว็บที่คุณสามารถโต้ตอบกับ AI agent ที่เข้าถึงเครื่องมือสำหรับสภาพอากาศและการแปลงอุณหภูมิได้ นี่คือรูปลักษณ์ของอินเทอร์เฟซ — มีตัวอย่างเริ่มต้นอย่างรวดเร็ว และแผงแชทสำหรับส่งคำขอ: +แอปพลิเคชันมีอินเทอร์เฟซเว็บที่คุณสามารถโต้ตอบกับเอเจนต์ AI ที่มีการเข้าถึงเครื่องมือเกี่ยวกับสภาพอากาศและการแปลงอุณหภูมิ นี่คือลักษณะของอินเทอร์เฟซ — มีตัวอย่างเริ่มต้นอย่างรวดเร็วและแผงแชทสำหรับส่งคำขอ: AI Agent Tools Interface -*อินเทอร์เฟซ AI Agent Tools - ตัวอย่างอย่างรวดเร็วและอินเทอร์เฟซแชทสำหรับโต้ตอบกับเครื่องมือ* +*อินเทอร์เฟซเครื่องมือเอเจนต์ AI - ตัวอย่างอย่างรวดเร็วและอินเทอร์เฟซแชทสำหรับโต้ตอบกับเครื่องมือ* ### ลองใช้เครื่องมืออย่างง่าย -เริ่มจากคำขอธรรมดา: "แปลง 100 องศาฟาเรนไฮต์เป็นเซลเซียส" ตัวแทนจะรับรู้ว่าต้องใช้เครื่องมือแปลงอุณหภูมิ เรียกใช้ด้วยพารามิเตอร์ที่ถูกต้อง และส่งผลลัพธ์กลับมา สังเกตว่ามันดูเป็นธรรมชาติมาก - คุณไม่ได้ระบุว่าจะใช้เครื่องมือไหนหรือวิธีเรียกอย่างไร +เริ่มต้นด้วยคำขอที่ตรงไปตรงมา: "แปลง 100 องศาฟาเรนไฮต์เป็นเซลเซียส" เอเจนต์จะรับรู้ว่าต้องใช้เครื่องมือแปลงอุณหภูมิ เรียกใช้ด้วยพารามิเตอร์ที่ถูกต้อง และส่งผลลัพธ์กลับมา สังเกตว่ามันดูเป็นธรรมชาติ — คุณไม่ต้องระบุว่าใช้เครื่องมืออะไรหรือเรียกอย่างไร ### ทดสอบการเชื่อมโยงเครื่องมือ -ลองทำอะไรที่ซับซ้อนขึ้น: "สภาพอากาศในซีแอตเทิลเป็นอย่างไรและแปลงเป็นฟาเรนไฮต์" ดูว่าเอเย่นต์ทำงานเป็นขั้นตอนอย่างไร มันดึงข้อมูลสภาพอากาศ (ซึ่งเป็นเซลเซียส) รับรู้ว่าต้องแปลงเป็นฟาเรนไฮต์ เรียกใช้เครื่องมือแปลง และรวมผลลัพธ์ทั้งสองเป็นคำตอบเดียว +ตอนนี้ลองคำขอที่ซับซ้อนมากขึ้น: "สภาพอากาศในซีแอตเทิลเป็นอย่างไรและแปลงเป็นฟาเรนไฮต์" ดูเอเจนต์ทำงานทีละขั้นตอน มันจะดึงข้อมูลสภาพอากาศ (ที่ส่งกลับเป็นเซลเซียส) รับรู้ว่าต้องแปลงเป็นฟาเรนไฮต์ เรียกเครื่องมือแปลง แล้วรวมผลลัพธ์ทั้งสองมาเป็นคำตอบเดียว -### ดูการไหลของการสนทนา +### ดูการไหลของบทสนทนา -อินเทอร์เฟซแชทเก็บประวัติการสนทนาไว้ ทำให้คุณสามารถมีการโต้ตอบหลายรอบได้ คุณจะเห็นคำถามและคำตอบทั้งหมดที่ผ่านมา ทำให้ง่ายต่อการติดตามการสนทนาและเข้าใจว่าตัวแทนสร้างบริบทอย่างไรในหลายแลกเปลี่ยนข้อมูล +อินเทอร์เฟซแชทจะเก็บประวัติการสนทนา ทำให้คุณสามารถมีการสนทนาหลายตารอบได้ คุณสามารถดูคำถามและคำตอบทั้งหมดก่อนหน้านี้ ทำให้ง่ายต่อการติดตามบทสนทนาและเข้าใจว่าเอเจนต์สร้างบริบทอย่างไรในแต่ละรอบ Conversation with Multiple Tool Calls -*การสนทนาหลายรอบแสดงการแปลงแบบง่าย การค้นหาสภาพอากาศ และการเชื่อมโยงเครื่องมือ* +*บทสนทนาแบบหลายรอบที่แสดงการแปลงง่ายๆ การตรวจสอบสภาพอากาศ และการเชื่อมโยงเครื่องมือ* -### ทดลองด้วยคำขอหลากหลาย +### ทดลองคำขอหลากหลาย -ลองชุดคำขอต่าง ๆ: -- ค้นหาสภาพอากาศ: "สภาพอากาศในโตเกียวเป็นอย่างไร?" -- การแปลงอุณหภูมิ: "25°C เท่ากับกี่เคลวิน?" -- คำถามผสม: "ตรวจสอบสภาพอากาศในปารีสและบอกว่ามันเกิน 20°C หรือไม่" +ลองคำขอที่แตกต่างกัน: +- ตรวจสอบสภาพอากาศ: "สภาพอากาศในโตเกียวเป็นอย่างไร?" +- การแปลงอุณหภูมิ: "25°C เป็นเคลวินเท่าไร?" +- คำถามผสม: "ตรวจสอบสภาพอากาศในปารีสและบอกฉันว่ามันสูงกว่า 20°C ไหม" -สังเกตว่าตัวแทนตีความภาษาธรรมชาติและแปลงเป็นการเรียกใช้เครื่องมือที่เหมาะสมอย่างไร +สังเกตว่าเอเจนต์ตีความภาษาธรรมชาติอย่างไรและแม็ปไปยังการเรียกเครื่องมือที่เหมาะสม -## แนวคิดหลัก +## แนวคิดสำคัญ -### รูปแบบ ReAct (Reasoning and Acting) +### รูปแบบ ReAct (การให้เหตุผลและการกระทำ) -ตัวแทนสลับระหว่างการคิดวิเคราะห์ (ตัดสินใจว่าจะทำอะไร) และการลงมือทำ (ใช้เครื่องมือ) รูปแบบนี้ช่วยให้แก้ปัญหาได้อย่างอิสระแทนที่จะตอบตามคำสั่งเท่านั้น +เอเจนต์สลับกันระหว่างการให้เหตุผล (ตัดสินใจว่าจะทำอะไร) และการกระทำ (ใช้เครื่องมือ) รูปแบบนี้ช่วยให้แก้ปัญหาโดยอัตโนมัติ ไม่ใช่แค่ตอบคำสั่ง -### คำอธิบายเครื่องมือมีความสำคัญ +### คำอธิบายเครื่องมือสำคัญ -คุณภาพของคำอธิบายเครื่องมือมีผลโดยตรงต่อประสิทธิภาพการใช้งานของตัวแทน คำอธิบายที่ชัดเจนและเจาะจงช่วยให้โมเดลเข้าใจว่าเมื่อไหร่และอย่างไรควรเรียกใช้แต่ละเครื่องมือ +คุณภาพของคำอธิบายเครื่องมือส่งผลโดยตรงกับวิธีที่เอเจนต์ใช้งาน เครื่องมือที่มีคำอธิบายชัดเจนและเฉพาะจะช่วยให้โมเดลเข้าใจว่าเมื่อไรและอย่างไรจึงควรเรียกใช้เครื่องมือนั้นๆ ### การจัดการเซสชัน -แอนโนเทชัน `@MemoryId` ช่วยให้จัดการความจำตามเซสชันโดยอัตโนมัติ แต่ละ ID ของเซสชันจะได้อินสแตนซ์ `ChatMemory` ที่บริหารโดยบีน `ChatMemoryProvider` ดังนั้นผู้ใช้หลายคนสามารถโต้ตอบกับตัวแทนพร้อมกันโดยไม่ทำให้ข้อความสนทนาเขวี้ยงปนกัน แผนภาพด้านล่างแสดงว่าผู้ใช้หลายคนถูกส่งไปยังที่เก็บความจำแยกตาม ID ของแต่ละเซสชันอย่างไร: +คำอธิบาย `@MemoryId` ช่วยให้จัดการหน่วยความจำแบบเซสชันโดยอัตโนมัติ เซสชันแต่ละ ID จะได้อินสแตนซ์ `ChatMemory` ที่จัดการโดยบีน `ChatMemoryProvider` ทำให้ผู้ใช้หลายคนสามารถโต้ตอบกับเอเจนต์พร้อมกันโดยไม่ปะปนกัน แผนภาพด้านล่างแสดงวิธีการที่ผู้ใช้หลายคนถูกกำหนดไปยังที่เก็บประวัติแยกตามเซสชัน ID: Session Management with @MemoryId -*แต่ละ ID ของเซสชันจะเชื่อมต่อกับประวัติการสนทนาแยกกัน — ผู้ใช้จะไม่เห็นข้อความของกันและกัน* +*เซสชัน ID แต่ละตัวแม็ปไปยังประวัติการสนทนาแยกกัน — ผู้ใช้จะไม่เห็นข้อความของกันและกัน* ### การจัดการข้อผิดพลาด -เครื่องมืออาจล้มเหลว — API หมดเวลา ค่าพารามิเตอร์ไม่ถูกต้อง เซอร์วิสภายนอกล่ม ตัวแทนในระบบจริงจึงต้องมีการจัดการข้อผิดพลาดเพื่อให้โมเดลสามารถอธิบายปัญหาหรือพยายามทางเลือกอื่นแทนที่จะทำให้แอปพลิเคชันล่ม เมื่อเครื่องมือขว้างข้อยกเว้น LangChain4j จะจับและส่งข้อความข้อผิดพลาดกลับไปที่โมเดลเพื่อให้สามารถอธิบายในภาษาธรรมชาติได้ +เครื่องมืออาจล้มเหลว — API หมดเวลา พารามิเตอร์อาจไม่ถูกต้อง บริการภายนอกล่ม เอเจนต์ผลิตภัณฑ์จึงต้องมีการจัดการข้อผิดพลาดเพื่อให้โมเดลสามารถอธิบายปัญหาหรือพยายามทางเลือกอื่นแทนที่จะล่มทั้งแอปพลิเคชัน เมื่อเครื่องมือโยนข้อผิดพลาด LangChain4j จะจับไว้แล้วส่งข้อความข้อผิดพลาดกลับไปยังโมเดลที่สามารถอธิบายปัญหาเป็นภาษาธรรมชาติได้ -## เครื่องมือที่มีให้ใช้ +## เครื่องมือที่มีให้ใช้งาน -แผนภาพด้านล่างแสดงระบบนิเวศกว้างของเครื่องมือที่คุณสามารถสร้าง โมดูลนี้สาธิตเครื่องมือสภาพอากาศและอุณหภูมิ แต่รูปแบบ `@Tool` เหมาะกับเมธอด Java ใด ๆ — ตั้งแต่การสืบค้นฐานข้อมูลไปจนถึงการประมวลผลการชำระเงิน +แผนภาพด้านล่างแสดงระบบนิเวศของเครื่องมือที่คุณสามารถสร้างได้ โมดูลนี้สาธิตเครื่องมือสภาพอากาศและอุณหภูมิ แต่รูปแบบ `@Tool` เดียวกันนี้ใช้ได้กับเมธอด Java ใดก็ได้ — ตั้งแต่การสืบค้นฐานข้อมูลจนถึงการประมวลผลการชำระเงิน Tool Ecosystem -*เมธอด Java ใด ๆ ที่มีแอนโนเทชัน @Tool จะพร้อมใช้งานกับ AI — รูปแบบนี้ขยายไปยังฐานข้อมูล, APIs, อีเมล, การจัดการไฟล์ และอื่น ๆ* +*เมธอด Java ใดที่ติดแท็ก @Tool จะพร้อมใช้สำหรับ AI — รูปแบบนี้ขยายไปยังฐานข้อมูล, API, อีเมล, การจัดการไฟล์ และอื่นๆ* -## เมื่อใดควรใช้ตัวแทนที่ใช้เครื่องมือ +## เมื่อใดควรใช้เอเจนต์ที่ใช้เครื่องมือ -ไม่ใช่ทุกคำขอที่จะต้องใช้เครื่องมือ การตัดสินใจขึ้นอยู่กับว่าตัว AI ต้องโต้ตอบกับระบบภายนอกหรือสามารถตอบจากความรู้ของตนเองได้ คู่มือด้านล่างสรุปว่าเมื่อไหร่ที่เครื่องมือมีประโยชน์และเมื่อไหร่ที่ไม่จำเป็น: +ไม่ใช่ทุกคำขอต้องใช้เครื่องมือ การตัดสินใจขึ้นอยู่กับว่า AI จำเป็นต้องโต้ตอบกับระบบภายนอกหรือสามารถตอบจากความรู้ของตัวเองได้ คู่มือด้านล่างสรุปว่าเมื่อใดเครื่องมือเพิ่มคุณค่าและเมื่อใดที่ไม่จำเป็น: When to Use Tools -*คู่มือการตัดสินใจอย่างรวดเร็ว — เครื่องมือเหมาะกับข้อมูลสด การคำนวณ และการกระทำ; ความรู้ทั่วไปและงานสร้างสรรค์ไม่จำเป็นต้องใช้* +*คู่มือการตัดสินใจอย่างรวดเร็ว — เครื่องมือสำหรับข้อมูลเรียลไทม์ การคำนวณ และการกระทำ; งานความรู้ทั่วไปและสร้างสรรค์ไม่ต้องใช้* -## เครื่องมือ vs RAG +## เครื่องมือกับ RAG -โมดูล 03 และ 04 ต่างขยายขีดความสามารถของ AI แต่ในวิธีการที่แตกต่างกันโดยพื้นฐาน RAG ให้โมเดลเข้าถึง **ความรู้** โดยการดึงเอกสาร เครื่องมือให้โมเดลสามารถทำ **การกระทำ** โดยการเรียกใช้ฟังก์ชัน แผนภาพด้านล่างเปรียบเทียบสองแนวทางนี้ข้างกัน — ตั้งแต่การทำงานของแต่ละเวิร์กโฟลว์จนถึงการแลกเปลี่ยนข้อดีข้อเสีย: +โมดูล 03 และ 04 ขยายขีดความสามารถของ AI แต่ในวิธีที่แตกต่างกันโดยพื้นฐาน RAG ให้โมเดลเข้าถึง **ความรู้** โดยการดึงเอกสาร เครื่องมือให้โมเดลความสามารถในการดำเนิน **การกระทำ** โดยการเรียกฟังก์ชัน แผนภาพด้านล่างเปรียบเทียบทั้งสองวิธีข้างเคียงกัน — ตั้งแต่โฟลว์เวิร์คแต่ละแบบไปจนถึงข้อแลกเปลี่ยนระหว่างกัน: Tools vs RAG Comparison -*RAG ดึงข้อมูลจากเอกสารคงที่ — เครื่องมือรันการกระทำและดึงข้อมูลสดแบบเรียลไทม์ ระบบหลายระบบในงานจริงจึงใช้ทั้งสองร่วมกัน* +*RAG ดึงข้อมูลจากเอกสารสแตติก — เครื่องมือดำเนินการและดึงข้อมูลเรียลไทม์ ตัวระบบผลิตหลายแห่งผสมผสานทั้งสองอย่าง* -ในทางปฏิบัติ ระบบจริงจำนวนมากใช้ทั้งสองแนวทางร่วมกัน: RAG เพื่อยืนยันคำตอบจากเอกสารของคุณ และเครื่องมือเพื่อดึงข้อมูลสดหรือดำเนินการต่าง ๆ +ในทางปฏิบัติ ระบบการผลิตหลายแห่งรวมทั้งสองแนวทาง: RAG สำหรับยึดคำตอบจากเอกสารของคุณ และเครื่องมือสำหรับดึงข้อมูลสดหรือปฏิบัติการ ## ขั้นตอนถัดไป -**โมดูลถัดไป:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**โมดูลถัดไป:** [05-mcp - โปรโตคอลบริบทโมเดล (MCP)](../05-mcp/README.md) --- -**การนำทาง:** [← ก่อนหน้า: โมดูล 03 - RAG](../03-rag/README.md) | [กลับสู่หน้าหลัก](../README.md) | [ถัดไป: โมดูล 05 - MCP →](../05-mcp/README.md) +**การนำทาง:** [← ก่อนหน้า: โมดูล 03 - RAG](../03-rag/README.md) | [กลับสู่หลัก](../README.md) | [ถัดไป: โมดูล 05 - MCP →](../05-mcp/README.md) --- -**ข้อจำกัดความรับผิดชอบ**: -เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษาด้วย AI [Co-op Translator](https://github.com/Azure/co-op-translator) แม้ว่าเราจะพยายามให้ความถูกต้องสูงสุด แต่โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เป็นทางการ สำหรับข้อมูลที่สำคัญ ขอแนะนำให้ใช้บริการแปลโดยผู้เชี่ยวชาญภาษามนุษย์ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่คลาดเคลื่อนที่อาจเกิดขึ้นจากการใช้การแปลนี้ +**ปฏิเสธความรับผิดชอบ**: +เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) ขณะที่เราพยายามให้ความถูกต้อง โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดที่เกิดขึ้นจากการใช้การแปลนี้ \ No newline at end of file diff --git a/translations/th/README.md b/translations/th/README.md index 976b5f6f7..06313b946 100644 --- a/translations/th/README.md +++ b/translations/th/README.md @@ -2,18 +2,18 @@ # LangChain4j สำหรับผู้เริ่มต้น -คอร์สสำหรับสร้างแอปพลิเคชัน AI ด้วย LangChain4j และ Azure OpenAI GPT-5.2 ตั้งแต่แชทพื้นฐานจนถึงตัวแทน AI +คอร์สสำหรับการสร้างแอปพลิเคชัน AI ด้วย LangChain4j และ Azure OpenAI GPT-5.2 ตั้งแต่แชทพื้นฐานจนถึงเอเจนต์ AI -### 🌐 การรองรับหลายภาษา +### 🌐 รองรับหลายภาษา -#### รองรับผ่าน GitHub Action (อัตโนมัติ & อัพเดตเสมอ) +#### รองรับผ่าน GitHub Action (อัตโนมัติ & อัปเดตเสมอ) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](./README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **ต้องการโคลนลงเครื่องหรือไม่?** +> **ต้องการโคลนแบบท้องถิ่น?** > -> ที่เก็บนี้รวมการแปลมากกว่า 50 ภาษา ซึ่งเพิ่มขนาดการดาวน์โหลดอย่างมาก สำหรับโคลนโดยไม่รวมการแปล ให้ใช้ sparse checkout: +> ที่เก็บนี้มีการแปลมากกว่า 50 ภาษา ซึ่งจะเพิ่มขนาดดาวน์โหลดอย่างมีนัยสำคัญ ในการโคลนโดยไม่รวมการแปล ให้ใช้ sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,100 +29,98 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> วิธีนี้จะให้ทุกสิ่งที่คุณต้องการเพื่อทำคอร์สนี้ให้เสร็จพร้อมการดาวน์โหลดที่เร็วขึ้นมาก +> วิธีนี้จะให้ทุกอย่างที่คุณต้องการเพื่อทำคอร์สนี้ให้เสร็จด้วยความเร็วดาวน์โหลดที่เร็วขึ้นมาก ## สารบัญ -1. [เริ่มต้นอย่างรวดเร็ว](00-quick-start/README.md) - เริ่มต้นกับ LangChain4j -2. [บทนำ](01-introduction/README.md) - เรียนรู้พื้นฐานของ LangChain4j -3. [การออกแบบ Prompt](02-prompt-engineering/README.md) - เชี่ยวชาญการออกแบบ prompt ที่มีประสิทธิภาพ -4. [RAG (การสร้างด้วยการค้นคืน)](03-rag/README.md) - สร้างระบบฐานความรู้ที่ชาญฉลาด -5. [เครื่องมือ](04-tools/README.md) - รวมเครื่องมือภายนอกและผู้ช่วยง่ายๆ -6. [MCP (โปรโตคอลบริบทของโมเดล)](05-mcp/README.md) - ทำงานกับโปรโตคอลบริบทของโมเดล (MCP) และโมดูล Agentic +1. [บทนำ](01-introduction/README.md) - เรียนรู้พื้นฐานของ LangChain4j +2. [การออกแบบพรอมต์](02-prompt-engineering/README.md) - เก่งในการออกแบบพรอมต์ที่มีประสิทธิภาพ +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - สร้างระบบความรู้ที่ชาญฉลาด +4. [เครื่องมือ](04-tools/README.md) - รวมเครื่องมือภายนอกและผู้ช่วยง่ายๆ +5. [MCP (Model Context Protocol)](05-mcp/README.md) - ทำงานกับ Model Context Protocol (MCP) และโมดูล Agentic -### วิดีโอแนะนำ +### วิดีโอสาธิต -แต่ละโมดูลมีเซสชันถ่ายทอดสดที่เราจะอธิบายแนวคิดและโค้ดทีละขั้นตอน +แต่ละโมดูลมีเซสชันถ่ายทอดสดประกอบที่เราจะพาท่านผ่านแนวคิดและโค้ดทีละขั้นตอน | โมดูล | วิดีโอ | |--------|-------| | 01 - บทนำ | [เริ่มต้นกับ LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - การออกแบบ Prompt | [การออกแบบ Prompt ด้วย LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [RAG ด้วย LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - เครื่องมือ & 05 - MCP | [ตัวแทน AI พร้อมเครื่องมือและ MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 02 - การออกแบบพรอมต์ | [การออกแบบพรอมต์กับ LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [RAG กับ LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 04 - เครื่องมือ & 05 - MCP | [เอเจนต์ AI กับเครื่องมือและ MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## เส้นทางการเรียนรู้ -**ใหม่กับ LangChain4j?** ดู [พจนานุกรม](docs/GLOSSARY.md) สำหรับคำจำกัดความของคำและแนวคิดหลัก +**ใหม่กับ LangChain4j?** ดู [พจนานุกรมศัพท์](docs/GLOSSARY.md) สำหรับคำจำกัดความของคำสำคัญและแนวคิด > **เริ่มต้นอย่างรวดเร็ว** -1. Fork ที่เก็บนี้ไปยังบัญชี GitHub ของคุณ -2. คลิก **Code** → แท็บ **Codespaces** → **...** → **สร้างใหม่พร้อมตัวเลือก...** -3. ใช้ค่าพื้นฐาน – จะเลือก Development container ที่สร้างไว้สำหรับคอร์สนี้ -4. คลิก **Create codespace** -5. รอ 5-10 นาทีจนสภาพแวดล้อมพร้อมใช้งาน -6. ไปที่ [เริ่มต้นอย่างรวดเร็ว](./00-quick-start/README.md) เพื่อเริ่มต้น! +1. Fork ที่เก็บนี้ไปยังบัญชี GitHub ของคุณ +2. คลิก **Code** → แท็บ **Codespaces** → **...** → **New with options...** +3. ใช้ค่าเริ่มต้น – จะเลือก Development container ที่สร้างสำหรับคอร์สนี้ +4. คลิก **Create codespace** +5. รอ 5-10 นาทีจนสภาพแวดล้อมพร้อมใช้งาน +6. เข้าสู่ [บทนำ](./01-introduction/README.md) เพื่อเริ่มต้นได้เลย! -หลังจากทำโมดูลเสร็จแล้ว สำรวจ [คู่มือการทดสอบ](docs/TESTING.md) เพื่อดูแนวคิดการทดสอบ LangChain4j ในการใช้งานจริง - -> **หมายเหตุ:** การอบรมนี้ใช้ GitHub Models และ Azure OpenAI โมดูล [เริ่มต้นอย่างรวดเร็ว](00-quick-start/README.md) ใช้ GitHub Models (ไม่ต้องใช้การสมัคร Azure) ขณะที่โมดูล 1-5 ใช้ Azure OpenAI เริ่มต้นด้วย [บัญชี Azure ฟรี](https://aka.ms/azure-free-account) หากคุณยังไม่มี +หลังจากทำโมดูลเสร็จ Explore [คู่มือการทดสอบ](docs/TESTING.md) เพื่อดูแนวคิดการทดสอบ LangChain4j ในการปฏิบัติ +> **หมายเหตุ:** การฝึกอบรมนี้ใช้ Azure OpenAI เริ่มต้นด้วย [บัญชี Azure ฟรี](https://aka.ms/azure-free-account) หากคุณยังไม่มี ## การเรียนรู้กับ GitHub Copilot -เพื่อเริ่มโค้ดอย่างรวดเร็ว เปิดโปรเจกต์นี้ใน GitHub Codespace หรือ IDE ในเครื่องของคุณด้วย devcontainer ที่เตรียมไว้ล่วงหน้า devcontainer ที่ใช้ในคอร์สนี้มาพร้อม GitHub Copilot สำหรับการเขียนโค้ดแบบจับคู่กับ AI - -แต่ละตัวอย่างโค้ดมีคำถามแนะนำที่คุณสามารถถาม GitHub Copilot เพื่อเสริมสร้างความเข้าใจ ค้นหาสัญลักษณ์ 💡/🤖 ใน: +เพื่อเริ่มต้นเขียนโค้ดอย่างรวดเร็ว เปิดโปรเจกต์นี้ใน GitHub Codespace หรือ IDE แบบท้องถิ่นของคุณโดยใช้ devcontainer ที่ให้มา Devcontainer ที่ใช้ในคอร์สนี้มีการตั้งค่าล่วงหน้ารวม GitHub Copilot สำหรับการเขียนโปรแกรมร่วมกับ AI -- **ส่วนหัวไฟล์ Java** - คำถามเฉพาะสำหรับแต่ละตัวอย่าง -- **README โมดูล** - คำถามสำรวจหลังตัวอย่างโค้ด +ตัวอย่างโค้ดแต่ละตัวมีคำถามแนะนำที่คุณสามารถถาม GitHub Copilot เพื่อเพิ่มความเข้าใจ ค้นหาคำแนะนำ 💡/🤖 ใน: -**ใช้อย่างไร:** เปิดไฟล์โค้ดใดก็ได้แล้วถาม Copilot ตามคำถามที่แนะนำ มันมีบริบทของฐานโค้ดทั้งหมดและสามารถอธิบาย ขยายความ และแนะนำทางเลือกได้ +- **ส่วนหัวไฟล์ Java** – คำถามเฉพาะสำหรับแต่ละตัวอย่าง +- **README โมดูล** – คำถามสำรวจหลังจากตัวอย่างโค้ด -ต้องการเรียนรู้เพิ่มเติม? ดูที่ [Copilot สำหรับการเขียนโค้ดกับ AI](https://aka.ms/GitHubCopilotAI) +**วิธีใช้:** เปิดไฟล์โค้ดใดก็ได้และถามคำถามที่แนะนำกับ Copilot มันมีบริบทเต็มของโค้ดและสามารถอธิบาย ขยาย และแนะนำทางเลือกได้ +ต้องการเรียนรู้เพิ่มเติม? ดูที่ [Copilot สำหรับการเขียนโปรแกรมร่วมกับ AI](https://aka.ms/GitHubCopilotAI) ## แหล่งข้อมูลเพิ่มเติม ### LangChain -[![LangChain4j สำหรับผู้เริ่มต้น](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js สำหรับผู้เริ่มต้น](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain สำหรับผู้เริ่มต้น](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- ### Azure / Edge / MCP / Agents -[![AZD สำหรับผู้เริ่มต้น](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI สำหรับผู้เริ่มต้น](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP สำหรับผู้เริ่มต้น](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![ตัวแทน AI สำหรับผู้เริ่มต้น](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### ชุด AI เชิงสร้างสรรค์ -[![Generative AI สำหรับผู้เริ่มต้น](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +### Generative AI Series +[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) [![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### การเรียนรู้แกนหลัก -[![ML สำหรับผู้เริ่มต้น](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science สำหรับผู้เริ่มต้น](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI สำหรับผู้เริ่มต้น](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +### Core Learning +[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### ชุดซีรีส์ Copilot +### ชุดเรื่อง Copilot [![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) [![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) @@ -130,21 +128,21 @@ ## การขอความช่วยเหลือ -หากคุณติดขัดหรือต้องการถามคำถามเกี่ยวกับการสร้างแอป AI เข้าร่วมที่: +หากคุณติดขัดหรือมีคำถามเกี่ยวกับการสร้างแอป AI เข้าร่วมได้ที่: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -หากคุณมีข้อเสนอแนะหรือพบข้อผิดพลาดขณะพัฒนาโปรดเยี่ยมชม: +หากคุณมีข้อเสนอแนะเกี่ยวกับผลิตภัณฑ์หรือพบข้อผิดพลาดในระหว่างการพัฒนา โปรดไปที่: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## ใบอนุญาต -ใบอนุญาต MIT - ดูไฟล์ [LICENSE](../../LICENSE) สำหรับรายละเอียดเพิ่มเติม +ใบอนุญาต MIT - ดูรายละเอียดได้ในไฟล์ [LICENSE](../../LICENSE) --- -**ข้อจำกัดความรับผิดชอบ**: -เอกสารฉบับนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) แม้ว่าเราจะพยายามให้มีความถูกต้อง โปรดทราบว่าการแปลอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาดั้งเดิมควรถือเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้บริการแปลโดยมืออาชีพที่เป็นมนุษย์ เราจะไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดใด ๆ ที่เกิดจากการใช้การแปลนี้ +**ปฏิเสธความรับผิดชอบ**: +เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) ขณะที่เราพยายามให้ความถูกต้อง โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดที่เกิดขึ้นจากการใช้การแปลนี้ \ No newline at end of file diff --git a/translations/th/docs/GLOSSARY.md b/translations/th/docs/GLOSSARY.md index fa1d1a79a..0250cd80e 100644 --- a/translations/th/docs/GLOSSARY.md +++ b/translations/th/docs/GLOSSARY.md @@ -1,52 +1,52 @@ -# พจนานุกรม LangChain4j +# LangChain4j พจนานุกรมศัพท์ ## สารบัญ -- [แนวคิดหลัก](../../../docs) -- [ส่วนประกอบของ LangChain4j](../../../docs) -- [แนวคิด AI/ML](../../../docs) -- [เกราะป้องกัน](../../../docs) -- [การออกแบบ Prompt](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [เอเยนต์และเครื่องมือ](../../../docs) -- [โมดูล Agentic](../../../docs) -- [โปรโตคอลบริบทของโมเดล (MCP)](../../../docs) -- [บริการ Azure](../../../docs) -- [การทดสอบและการพัฒนา](../../../docs) +- [แนวคิดหลัก](#แนวคิดหลัก) +- [ส่วนประกอบของ LangChain4j](#ส่วนประกอบของ-langchain4j) +- [แนวคิด AI/ML](#แนวคิด-aiml) +- [มาตรการความปลอดภัย](#มาตรการความปลอดภัย) +- [วิศวกรรมการใช้พรอมต์](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [เอเย่นต์และเครื่องมือ](#agents-and-tools---module-04) +- [โมดูล Agentic](#agentic-module---module-05) +- [โปรโตคอลบริบทของโมเดล (MCP)](#model-context-protocol-mcp---module-05) +- [บริการ Azure](#azure-services---module-01) +- [การทดสอบและการพัฒนา](#testing-and-development---testing-guide) -การอ้างอิงอย่างรวดเร็วสำหรับคำศัพท์และแนวคิดที่ใช้ทั่วทั้งคอร์ส +อ้างอิงด่วนสำหรับคำและแนวคิดที่ใช้ตลอดหลักสูตร ## แนวคิดหลัก -**เอเยนต์ AI** - ระบบที่ใช้ AI ในการให้เหตุผลและทำงานโดยอิสระ [โมดูล 04](../04-tools/README.md) +**AI Agent** - ระบบที่ใช้ AI เพื่อให้เหตุผลและดำเนินการโดยอัตโนมัติ [Module 04](../04-tools/README.md) -**โซ่** - ลำดับของขั้นตอนที่ผลลัพธ์จากขั้นตอนหนึ่งถูกป้อนเข้าสู่ขั้นตอนถัดไป +**Chain** - ลำดับของการดำเนินการซึ่งผลลัพธ์เป็นข้อมูลเข้าสู่ขั้นตอนต่อไป -**การแบ่งส่วน (Chunking)** - การแบ่งเอกสารเป็นชิ้นเล็ก ๆ ขนาดปกติ: 300-500 โทเคน พร้อมทับซ้อน [โมดูล 03](../03-rag/README.md) +**Chunking** - การแบ่งเอกสารออกเป็นชิ้นเล็ก ๆ โดยทั่วไป: 300-500 โทเคนพร้อมการทับซ้อน [Module 03](../03-rag/README.md) -**หน้าต่างบริบท** - จำนวนโทเคนสูงสุดที่โมเดลสามารถประมวลผล GPT-5.2: 400K โทเคน (สูงสุด 272K อินพุต, 128K เอาต์พุต) +**Context Window** - จำนวนโทเคนสูงสุดที่โมเดลสามารถประมวลผลได้ GPT-5.2: 400K โทเคน (สูงสุด 272K อินพุต, 128K เอาต์พุต) -**Embeddings** - เวกเตอร์เชิงตัวเลขที่แสดงความหมายของข้อความ [โมดูล 03](../03-rag/README.md) +**Embeddings** - เวกเตอร์ตัวเลขที่แทนความหมายของข้อความ [Module 03](../03-rag/README.md) -**การเรียกฟังก์ชัน (Function Calling)** - โมเดลสร้างคำร้องแบบมีโครงสร้างเพื่อเรียกฟังก์ชันภายนอก [โมดูล 04](../04-tools/README.md) +**Function Calling** - โมเดลสร้างคำขอที่มีโครงสร้างเพื่อเรียกใช้ฟังก์ชันภายนอก [Module 04](../04-tools/README.md) -**การหลอกลวง (Hallucination)** - เมื่โมเดลสร้างข้อมูลที่ไม่ถูกต้องแต่ดูสมเหตุสมผล +**Hallucination** - เมื่อโมเดลสร้างข้อมูลที่ไม่ถูกต้องแต่มีความน่าเชื่อถือ -**Prompt** - ข้อความนำเข้าให้กับโมเดลภาษา [โมดูล 02](../02-prompt-engineering/README.md) +**Prompt** - ข้อความป้อนเข้าให้โมเดลภาษา [Module 02](../02-prompt-engineering/README.md) -**การค้นหาทางความหมาย (Semantic Search)** - การค้นหาด้วยความหมายโดยใช้ embeddings แทนคีย์เวิร์ด [โมดูล 03](../03-rag/README.md) +**Semantic Search** - การค้นหาตามความหมายโดยใช้ embeddings ไม่ใช่คำค้น [Module 03](../03-rag/README.md) -**สถานะมีและไม่มีสถานะ (Stateful vs Stateless)** - ไม่มีสถานะ: ไม่มีหน่วยความจำ มีสถานะ: เก็บประวัติการสนทนา [โมดูล 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: ไม่มีหน่วยความจำ Stateful: เก็บประวัติการสนทนา [Module 01](../01-introduction/README.md) -**โทเคน** - หน่วยข้อความพื้นฐานที่โมเดลประมวลผล มีผลต่อค่าใช้จ่ายและข้อจำกัด [โมดูล 01](../01-introduction/README.md) +**Tokens** - หน่วยข้อความพื้นฐานที่โมเดลประมวลผล ส่งผลต่อค่าใช้จ่ายและข้อจำกัด [Module 01](../01-introduction/README.md) -**การเชื่อมโยงเครื่องมือ (Tool Chaining)** - การเรียกใช้งานเครื่องมือเป็นลำดับโดยผลลัพธ์ใช้ในการเรียกครั้งถัดไป [โมดูล 04](../04-tools/README.md) +**Tool Chaining** - การใช้เครื่องมือแบบต่อเนื่อง โดยข้อมูลออกแจ้งการเรียกครั้งถัดไป [Module 04](../04-tools/README.md) ## ส่วนประกอบของ LangChain4j -**AiServices** - สร้างอินเทอร์เฟซบริการ AI ที่ปลอดภัยในประเภทข้อมูล +**AiServices** - สร้างอินเทอร์เฟซบริการ AI ที่ปลอดภัยตามประเภท -**OpenAiOfficialChatModel** - ไคลเอนต์รวมสำหรับโมเดล OpenAI และ Azure OpenAI +**OpenAiOfficialChatModel** - ลูกค้ารวมสำหรับโมเดล OpenAI และ Azure OpenAI **OpenAiOfficialEmbeddingModel** - สร้าง embeddings โดยใช้ไคลเอนต์ OpenAI Official (รองรับทั้ง OpenAI และ Azure OpenAI) @@ -54,179 +54,177 @@ **ChatMemory** - เก็บประวัติการสนทนา -**ContentRetriever** - ค้นหาชิ้นส่วนเอกสารที่เกี่ยวข้องสำหรับ RAG +**ContentRetriever** - ค้นหาชิ้นเอกสารที่เกี่ยวข้องสำหรับ RAG **DocumentSplitter** - แบ่งเอกสารเป็นชิ้น **EmbeddingModel** - แปลงข้อความเป็นเวกเตอร์ตัวเลข -**EmbeddingStore** - เก็บและเรียกใช้ embeddings +**EmbeddingStore** - เก็บและดึง embeddings -**MessageWindowChatMemory** - ดูแลกลุ่มข้อความล่าสุดในหน้าต่างเลื่อน +**MessageWindowChatMemory** - เก็บหน้าต่างข้อความเลื่อนสำหรับข้อความล่าสุด -**PromptTemplate** - สร้าง prompt ที่ใช้ซ้ำได้โดยมีที่ว่างสำหรับ `{{variable}}` +**PromptTemplate** - สร้างพรอมต์ที่ใช้ซ้ำได้ด้วยตัวแปร `{{variable}}` -**TextSegment** - ชิ้นข้อความที่มีข้อมูลเมตา ใช้ใน RAG +**TextSegment** - ชิ้นข้อความพร้อมเมตาดาต้า ใช้ใน RAG -**ToolExecutionRequest** - แทนคำขอการเรียกใช้งานเครื่องมือ +**ToolExecutionRequest** - ตัวแทนคำขอการใช้เครื่องมือ -**UserMessage / AiMessage / SystemMessage** - ชนิดข้อความในการสนทนา +**UserMessage / AiMessage / SystemMessage** - ประเภทข้อความสนทนา ## แนวคิด AI/ML -**การเรียนรู้แบบ Few-Shot** - การให้ตัวอย่างใน prompt [โมดูล 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - การให้ตัวอย่างในพรอมต์ [Module 02](../02-prompt-engineering/README.md) -**โมเดลภาษาใหญ่ (LLM)** - โมเดล AI ที่ผ่านการฝึกด้วยข้อมูลข้อความจำนวนมาก +**Large Language Model (LLM)** - โมเดล AI ที่ฝึกด้วยข้อมูลข้อความจำนวนมาก -**ความพยายามให้เหตุผล (Reasoning Effort)** - พารามิเตอร์ GPT-5.2 ควบคุมความลึกของการคิด [โมดูล 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - พารามิเตอร์ GPT-5.2 ที่ควบคุมความลึกของการให้เหตุผล [Module 02](../02-prompt-engineering/README.md) -**อุณหภูมิ (Temperature)** - ควบคุมความสุ่มของผลลัพธ์ ต่ำ=กำหนด, สูง=สร้างสรรค์ +**Temperature** - ควบคุมความสุ่มของผลลัพธ์ ต่ำ=แน่นอน สูง=สร้างสรรค์ -**ฐานข้อมูลเวกเตอร์** - ฐานข้อมูลเฉพาะทางสำหรับ embeddings [โมดูล 03](../03-rag/README.md) +**Vector Database** - ฐานข้อมูลเฉพาะสำหรับ embeddings [Module 03](../03-rag/README.md) -**การเรียนรู้แบบ Zero-Shot** - ทำงานโดยไม่ต้องมีตัวอย่าง [โมดูล 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - การปฏิบัติงานโดยไม่มีตัวอย่าง [Module 02](../02-prompt-engineering/README.md) -## เกราะป้องกัน - [โมดูล 00](../00-quick-start/README.md) +## มาตรการความปลอดภัย -**Defense in Depth** - แนวทางความปลอดภัยหลายชั้นรวมเกราะโปรแกรมกับตัวกรองความปลอดภัยของผู้ให้บริการ +**Defense in Depth** - แนวทางการรักษาความปลอดภัยหลายชั้นรวมมาตรการระดับแอปกับฟิลเตอร์ความปลอดภัยของผู้ให้บริการ -**Hard Block** - ผู้ให้บริการตอบข้อผิดพลาด HTTP 400 สำหรับการละเมิดเนื้อหารุนแรง +**Hard Block** - ผู้ให้บริการส่งข้อผิดพลาด HTTP 400 เมื่อพบเนื้อหาละเมิดรุนแรง -**InputGuardrail** - อินเทอร์เฟซ LangChain4j สำหรับตรวจสอบอินพุตผู้ใช้ก่อนถึง LLM ประหยัดค่าใช้จ่ายและเวลาตอบสนองโดยบล็อก prompt อันตรายตั้งแต่ต้น +**InputGuardrail** - อินเทอร์เฟซ LangChain4j สำหรับตรวจสอบข้อมูลป้อนเข้าของผู้ใช้ก่อนเข้าถึง LLM ช่วยประหยัดค่าใช้จ่ายและลดความล่าช้าโดยบล็อกพรอมต์ที่เป็นอันตรายตั้งแต่ต้น -**InputGuardrailResult** - ประเภทคืนสำหรับการตรวจสอบ guardrail: `success()` หรือ `fatal("reason")` +**InputGuardrailResult** - ประเภทค่าที่ส่งกลับการตรวจสอบ guardrail: `success()` หรือ `fatal("reason")` -**OutputGuardrail** - อินเทอร์เฟซตรวจสอบคำตอบ AI ก่อนส่งกลับผู้ใช้ +**OutputGuardrail** - อินเทอร์เฟซสำหรับตรวจสอบคำตอบ AI ก่อนส่งกลับผู้ใช้ -**ตัวกรองความปลอดภัยของผู้ให้บริการ** - ตัวกรองเนื้อหาติดตั้งจากผู้ให้บริการ AI (เช่น GitHub Models) ที่จับการละเมิดระดับ API +**Provider Safety Filters** - ฟิลเตอร์เนื้อหาที่ฝังอยู่จากผู้ให้บริการ AI (เช่น Azure OpenAI) ที่จับการละเมิดในระดับ API -**Soft Refusal** - โมเดลปฏิเสธตอบอย่างสุภาพโดยไม่เกิดข้อผิดพลาด +**Soft Refusal** - โมเดลปฏิเสธอย่างสุภาพโดยไม่ส่งข้อผิดพลาด -## การออกแบบ Prompt - [โมดูล 02](../02-prompt-engineering/README.md) +## วิศวกรรมการใช้พรอมต์ - [Module 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - การให้เหตุผลเป็นขั้นตอนเพื่อความแม่นยำที่ดีกว่า +**Chain-of-Thought** - การให้เหตุผลทีละขั้นตอนเพื่อความแม่นยำยิ่งขึ้น -**ผลลัพธ์ที่จำกัดรูปแบบ (Constrained Output)** - บังคับให้ผลลัพธ์มีรูปแบบหรือโครงสร้างเฉพาะ +**Constrained Output** - บังคับใช้รูปแบบหรือโครงสร้างเฉพาะ -**High Eagerness** - รูปแบบ GPT-5.2 สำหรับการคิดวิเคราะห์ลึกซึ้ง +**High Eagerness** - รูปแบบ GPT-5.2 สำหรับการให้เหตุผลเชิงลึก **Low Eagerness** - รูปแบบ GPT-5.2 สำหรับคำตอบรวดเร็ว -**การสนทนาแบบหลายรอบ (Multi-Turn Conversation)** - การรักษาบริบทระหว่างการแลกเปลี่ยนหลายครั้ง +**Multi-Turn Conversation** - รักษาบริบทตลอดการสนทนา -**Prompt ตามบทบาท (Role-Based Prompting)** - ตั้งบุคลิกของโมเดลผ่านข้อความระบบ +**Role-Based Prompting** - กำหนดบุคลิกโมเดลผ่านข้อความระบบ -**การสะท้อนตนเอง (Self-Reflection)** - โมเดลประเมินและปรับปรุงผลลัพธ์ของตัวเอง +**Self-Reflection** - โมเดลประเมินและปรับปรุงผลลัพธ์ของตนเอง -**การวิเคราะห์แบบมีโครงสร้าง (Structured Analysis)** - กรอบการประเมินที่ตั้งค่าไว้ล่วงหน้า +**Structured Analysis** - กรอบการประเมินที่กำหนดไว้ล่วงหน้า -**รูปแบบการปฏิบัติงาน (Task Execution Pattern)** - วางแผน → ดำเนินการ → สรุปผล +**Task Execution Pattern** - วางแผน → ดำเนินการ → สรุป -## RAG (Retrieval-Augmented Generation) - [โมดูล 03](../03-rag/README.md) +## RAG (Retrieval-Augmented Generation) - [Module 03](../03-rag/README.md) -**สายงานประมวลผลเอกสาร** - โหลด → แบ่งชิ้น → สร้าง embeddings → เก็บ +**Document Processing Pipeline** - โหลด → แบ่งชิ้น → ฝัง → เก็บ -**ที่เก็บ embeddings ในหน่วยความจำ** - ที่เก็บไม่ถาวรสำหรับทดสอบ +**In-Memory Embedding Store** - ที่เก็บชั่วคราวสำหรับการทดสอบ -**RAG** - รวมการดึงข้อมูลกับการสร้างคำตอบเพื่อยึดโยงคำตอบ +**RAG** - รวมการค้นคืนข้อมูลกับการสร้างข้อความเพื่อให้คำตอบมีฐานข้อมูล -**คะแนนความคล้าย (Similarity Score)** - ตัวชี้วัดความคล้ายเชิงความหมาย (0-1) +**Similarity Score** - มาตรวัดความเหมือนเชิงความหมาย (0-1) -**ข้อมูลอ้างอิงแหล่งที่มา** - ข้อมูลเมตาเกี่ยวกับเนื้อหาที่ดึงมา +**Source Reference** - เมตาดาต้าเกี่ยวกับเนื้อหาที่ค้นคืน -## เอเยนต์และเครื่องมือ - [โมดูล 04](../04-tools/README.md) +## เอเย่นต์และเครื่องมือ - [Module 04](../04-tools/README.md) -**@Tool Annotation** - แท็กเมธอด Java เป็นเครื่องมือที่ AI สามารถเรียกได้ +**@Tool Annotation** - ใช้ทำเครื่องหมายเมธอด Java ให้เป็นเครื่องมือเรียกใช้โดย AI -**ReAct Pattern** - ให้เหตุผล → ปฏิบัติ → สังเกต → ทำซ้ำ +**ReAct Pattern** - ให้เหตุผล → ดำเนินการ → สังเกต → ทำซ้ำ -**การจัดการเซสชัน** - บริบทแยกสำหรับผู้ใช้แต่ละคน +**Session Management** - แยกบริบทสำหรับผู้ใช้แต่ละคน -**เครื่องมือ (Tool)** - ฟังก์ชันที่เอเยนต์ AI สามารถเรียกใช้ +**Tool** - ฟังก์ชันที่เอเย่นต์ AI สามารถเรียกใช้ได้ -**คำอธิบายเครื่องมือ** - เอกสารอธิบายวัตถุประสงค์และพารามิเตอร์ของเครื่องมือ +**Tool Description** - เอกสารอธิบายวัตถุประสงค์และพารามิเตอร์ของเครื่องมือ -## โมดูล Agentic - [โมดูล 05](../05-mcp/README.md) +## โมดูล Agentic - [Module 05](../05-mcp/README.md) -**@Agent Annotation** - แท็กอินเทอร์เฟซเป็นเอเยนต์ AI พร้อมนิยามพฤติกรรมแบบประกาศ +**@Agent Annotation** - ใช้ทำเครื่องหมายอินเทอร์เฟซเป็นเอเย่นต์ AI พร้อมนิยามพฤติกรรมแบบประกาศ -**Agent Listener** - ตะขอสำหรับติดตามการทำงานเอเยนต์ผ่าน `beforeAgentInvocation()` และ `afterAgentInvocation()` +**Agent Listener** - ตัวเชื่อมสำหรับติดตามการทำงานของเอเย่นต์ผ่าน `beforeAgentInvocation()` และ `afterAgentInvocation()` -**ขอบเขตแบบ Agentic (Agentic Scope)** - หน่วยความจำแชร์ที่เอเยนต์เก็บผลลัพธ์โดยใช้ `outputKey` เพื่อให้เอเยนต์อื่นใช้ต่อ +**Agentic Scope** - หน่วยความจำร่วมที่เอเย่นต์เก็บผลลัพธ์โดยใช้ `outputKey` เพื่อให้เอเย่นต์ถัดไปใช้งาน -**AgenticServices** - โรงงานสร้างเอเยนต์โดยใช้ `agentBuilder()` และ `supervisorBuilder()` +**AgenticServices** - แฟคทอรี่สร้างเอเย่นต์ผ่าน `agentBuilder()` และ `supervisorBuilder()` -**เวิร์กโฟลว์ตามเงื่อนไข (Conditional Workflow)** - เส้นทางตามเงื่อนไขไปยังเอเยนต์เฉพาะทางต่าง ๆ +**Conditional Workflow** - เส้นทางทำงานตามเงื่อนไขไปยังเอเย่นต์ผู้เชี่ยวชาญต่าง ๆ -**มนุษย์ในวงจร (Human-in-the-Loop)** - รูปแบบการทำงานเพิ่มจุดตรวจสอบโดยมนุษย์สำหรับอนุมัติหรือตรวจเนื้อหา +**Human-in-the-Loop** - รูปแบบเวิร์กโฟลว์ที่เพิ่มจุดตรวจสอบจากมนุษย์เพื่ออนุมัติหรือทบทวนเนื้อหา -**langchain4j-agentic** - พึ่งพา Maven สำหรับสร้างเอเยนต์แบบประกาศ (ทดสอบ) +**langchain4j-agentic** - ขึ้นตอน Maven สำหรับสร้างเอเย่นต์แบบประกาศ (ทดลอง) -**เวิร์กโฟลว์ลูป (Loop Workflow)** - ทำซ้ำการทำงานของเอเยนต์จนกว่าจะครบเงื่อนไข (เช่น คะแนนคุณภาพ ≥ 0.8) +**Loop Workflow** - ทำซ้ำการทำงานของเอเย่นต์จนกว่าจะถึงเงื่อนไข (เช่น คะแนนคุณภาพ ≥ 0.8) -**outputKey** - พารามิเตอร์แท็กเอเยนต์ระบุที่เก็บผลลัพธ์ใน Agentic Scope +**outputKey** - พารามิเตอร์ของ annotation เอเย่นต์ระบุที่เก็บผลลัพธ์ใน Agentic Scope -**เวิร์กโฟลว์ขนาน (Parallel Workflow)** - รันเอเยนต์หลายตัวพร้อมกันสำหรับงานอิสระ +**Parallel Workflow** - รันเอเย่นต์หลายตัวพร้อมกันสำหรับงานอิสระ -**กลยุทธ์การตอบกลับ (Response Strategy)** - วิธีผู้ดูแลกำหนดคำตอบสุดท้าย: LAST, SUMMARY, หรือ SCORED +**Response Strategy** - วิธีที่ซูเปอร์ไวเซอร์สรุปคำตอบสุดท้าย: LAST, SUMMARY, หรือ SCORED -**เวิร์กโฟลว์เรียงลำดับ (Sequential Workflow)** - รันเอเยนต์ตามลำดับโดยผลลัพธ์ใช้ในขั้นตอนถัดไป +**Sequential Workflow** - ดำเนินการเอเย่นต์ตามลำดับโดยผลลัพธ์เป็นข้อมูลเข้าสู่ขั้นตอนถัดไป -**รูปแบบเอเยนต์ผู้ดูแล (Supervisor Agent Pattern)** - รูปแบบขั้นสูงที่ผู้ดูแล LLM ตัดสินใจเรียกเอเยนต์ย่อยแบบไดนามิก +**Supervisor Agent Pattern** - รูปแบบเอเย่นต์ขั้นสูงที่ซูเปอร์ไวเซอร์ LLM ตัดสินใจเรียกใช้ซับเอเย่นต์แบบไดนามิก -## โปรโตคอลบริบทของโมเดล (MCP) - [โมดูล 05](../05-mcp/README.md) +## โปรโตคอลบริบทของโมเดล (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - พึ่งพา Maven สำหรับรวม MCP ใน LangChain4j +**langchain4j-mcp** - ขึ้นตอน Maven สำหรับการรวม MCP ใน LangChain4j -**MCP** - โปรโตคอลบริบทของโมเดล: มาตรฐานเชื่อมต่อแอป AI กับเครื่องมือภายนอก สร้างครั้งเดียว ใช้ได้ทุกที่ +**MCP** - Model Context Protocol: มาตรฐานเชื่อมต่อแอป AI กับเครื่องมือภายนอก สร้างครั้งเดียว ใช้ทุกที่ **MCP Client** - แอปที่เชื่อมต่อกับเซิร์ฟเวอร์ MCP เพื่อค้นหาและใช้เครื่องมือ -**MCP Server** - บริการเผยแพร่เครื่องมือผ่าน MCP พร้อมคำอธิบายและสคีมาพารามิเตอร์ชัดเจน +**MCP Server** - บริการที่เปิดเผยเครื่องมือผ่าน MCP พร้อมคำอธิบายและสคีมาพารามิเตอร์ชัดเจน -**McpToolProvider** - ส่วนประกอบ LangChain4j ห่อหุ้มเครื่องมือ MCP สำหรับใช้ในบริการ AI และเอเยนต์ +**McpToolProvider** - ส่วนประกอบ LangChain4j ที่ห่อหุ้มเครื่องมือ MCP เพื่อใช้ในบริการ AI และเอเย่นต์ -**McpTransport** - อินเทอร์เฟซสำหรับสื่อสาร MCP มีการใช้งานเช่น Stdio และ HTTP +**McpTransport** - อินเทอร์เฟซสำหรับการสื่อสาร MCP การใช้งานรวม Stdio และ HTTP -**Stdio Transport** - ขนส่งผ่านกระบวนการภายในเครื่องโดย stdin/stdout ใช้งานสำหรับเข้าถึงไฟล์หรือเครื่องมือบรรทัดคำสั่ง +**Stdio Transport** - การส่งข้อมูลภายในกระบวนการผ่าน stdin/stdout เหมาะสำหรับการเข้าถึงระบบไฟล์หรือเครื่องมือบรรทัดคำสั่ง -**StdioMcpTransport** - การใช้งาน LangChain4j ที่เริ่มเซิร์ฟเวอร์ MCP เป็นซับโปรเซส +**StdioMcpTransport** - การใช้งาน LangChain4j ที่รันเซิร์ฟเวอร์ MCP เป็น subprocess -**การค้นพบเครื่องมือ (Tool Discovery)** - ไคลเอนต์สอบถามเซิร์ฟเวอร์สำหรับเครื่องมือที่มีพร้อมคำอธิบายและสคีมา +**Tool Discovery** - ลูกค้าสอบถามเซิร์ฟเวอร์หาเครื่องมือที่มีด้วยคำอธิบายและสคีมา -## บริการ Azure - [โมดูล 01](../01-introduction/README.md) +## บริการ Azure - [Module 01](../01-introduction/README.md) -**Azure AI Search** - บริการค้นหาในคลาวด์พร้อมความสามารถเวกเตอร์ [โมดูล 03](../03-rag/README.md) +**Azure AI Search** - บริการค้นหาในระบบคลาวด์พร้อมความสามารถเวกเตอร์ [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - เครื่องมือ deploy ทรัพยากร Azure +**Azure Developer CLI (azd)** - เครื่องมือสำหรับปรับใช้ทรัพยากร Azure **Azure OpenAI** - บริการ AI สำหรับองค์กรของ Microsoft -**Bicep** - ภาษา Infrastructure-as-Code ของ Azure [คู่มือโครงสร้างพื้นฐาน](../01-introduction/infra/README.md) +**Bicep** - ภาษา infrastructure-as-code สำหรับ Azure [Infrastructure Guide](../01-introduction/infra/README.md) -**ชื่อการปรับใช้ (Deployment Name)** - ชื่อสำหรับการปรับใช้โมเดลใน Azure +**Deployment Name** - ชื่อสำหรับการปรับใช้โมเดลใน Azure -**GPT-5.2** - โมเดล OpenAI รุ่นล่าสุดที่ควบคุมการให้เหตุผลได้ [โมดูล 02](../02-prompt-engineering/README.md) +**GPT-5.2** - โมเดล OpenAI ล่าสุดที่ควบคุมการให้เหตุผลได้ [Module 02](../02-prompt-engineering/README.md) -## การทดสอบและการพัฒนา - [คู่มือการทดสอบ](TESTING.md) +## การทดสอบและการพัฒนา - [Testing Guide](TESTING.md) -**Dev Container** - สภาพแวดล้อมพัฒนาที่รันในคอนเทนเนอร์ [การตั้งค่า](../../../.devcontainer/devcontainer.json) +**Dev Container** - สภาพแวดล้อมพัฒนาซอฟต์แวร์ในคอนเทนเนอร์ [Configuration](../../../.devcontainer/devcontainer.json) -**GitHub Models** - สนามเล่นโมเดล AI ฟรี [โมดูล 00](../00-quick-start/README.md) +**In-Memory Testing** - การทดสอบด้วยที่เก็บข้อมูลในหน่วยความจำ -**การทดสอบในหน่วยความจำ** - ทดสอบโดยใช้ที่เก็บข้อมูลในหน่วยความจำ +**Integration Testing** - การทดสอบกับโครงสร้างพื้นฐานจริง -**การทดสอบแบบบูรณาการ** - ทดสอบโดยใช้โครงสร้างพื้นฐานจริง +**Maven** - เครื่องมืออัตโนมัติสำหรับการสร้างแอป Java -**Maven** - เครื่องมืออัตโนมัติสำหรับการสร้างโปรเจกต์ Java +**Mockito** - เฟรมเวิร์กสำหรับการจำลองใน Java -**Mockito** - เฟรมเวิร์กจำลองใน Java - -**Spring Boot** - เฟรมเวิร์กแอปพลิเคชัน Java [โมดูล 01](../01-introduction/README.md) +**Spring Boot** - เฟรมเวิร์กแอปพลิเคชัน Java [Module 01](../01-introduction/README.md) --- -**ข้อจำกัดความรับผิดชอบ**: -เอกสารฉบับนี้ได้รับการแปลโดยใช้บริการแปลภาษาอัตโนมัติ [Co-op Translator](https://github.com/Azure/co-op-translator) แม้เราจะพยายามรักษาความถูกต้องไว้ แต่โปรดทราบว่าการแปลอัตโนมัติอาจมีข้อผิดพลาดหรือความคลาดเคลื่อน เอกสารต้นฉบับในภาษาต้นทางถือเป็นแหล่งข้อมูลที่เชื่อถือได้ที่สุด สำหรับข้อมูลที่มีความสำคัญ ขอแนะนำให้ใช้บริการแปลโดยมนุษย์ผู้เชี่ยวชาญ เราจะไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดที่เกิดจากการใช้การแปลนี้ +**ปฏิเสธความรับผิดชอบ**: +เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) ขณะที่เราพยายามให้ความถูกต้อง โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดที่เกิดขึ้นจากการใช้การแปลนี้ \ No newline at end of file diff --git a/translations/th/docs/TESTING.md b/translations/th/docs/TESTING.md index f3b0c5b97..1279bd714 100644 --- a/translations/th/docs/TESTING.md +++ b/translations/th/docs/TESTING.md @@ -2,15 +2,15 @@ ## สารบัญ -- [เริ่มต้นอย่างรวดเร็ว](../../../docs) -- [สิ่งที่การทดสอบครอบคลุม](../../../docs) -- [การรันการทดสอบ](../../../docs) -- [การรันการทดสอบใน VS Code](../../../docs) -- [รูปแบบการทดสอบ](../../../docs) -- [ปรัชญาการทดสอบ](../../../docs) -- [ขั้นตอนถัดไป](../../../docs) +- [เริ่มต้นอย่างรวดเร็ว](#เริ่มต้นอย่างรวดเร็ว) +- [สิ่งที่การทดสอบครอบคลุม](#สิ่งที่การทดสอบครอบคลุม) +- [การรันการทดสอบ](#การรันการทดสอบ) +- [การรันทดสอบใน VS Code](#การรันทดสอบใน-vs-code) +- [รูปแบบการทดสอบ](#รูปแบบการทดสอบ) +- [ปรัชญาการทดสอบ](#ปรัชญาการทดสอบ) +- [ขั้นตอนถัดไป](#ขั้นตอนถัดไป) -คู่มือนี้จะพาคุณผ่านการทดสอบที่แสดงวิธีการทดสอบแอปพลิเคชัน AI โดยไม่ต้องใช้คีย์ API หรือบริการภายนอก +คู่มือฉบับนี้จะพาคุณผ่านการทดสอบที่แสดงให้เห็นวิธีการทดสอบแอป AI โดยไม่ต้องการคีย์ API หรือบริการภายนอก ## เริ่มต้นอย่างรวดเร็ว @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -เมื่อการทดสอบทั้งหมดผ่าน คุณจะเห็นผลลัพธ์เหมือนกับภาพหน้าจอด้านล่าง — การทดสอบทำงานโดยไม่มีความล้มเหลว +เมื่อการทดสอบทั้งหมดผ่าน คุณจะเห็นผลลัพธ์เหมือนภาพด้านล่าง — การทดสอบรันไม่มีความล้มเหลว Successful Test Results -*การทำงานของการทดสอบที่สำเร็จแสดงให้เห็นการผ่านทุกการทดสอบโดยไม่มีความล้มเหลว* +*การรันทดสอบสำเร็จแสดงให้เห็นว่าการทดสอบทั้งหมดผ่านโดยไม่มีข้อผิดพลาด* ## สิ่งที่การทดสอบครอบคลุม -คอร์สนี้เน้นที่ **การทดสอบหน่วย** ที่รันในเครื่องแต่ละการทดสอบจะแสดงแนวคิดเฉพาะของ LangChain4j อย่างโดดเดี่ยว พีระมิดการทดสอบด้านล่างแสดงตำแหน่งของการทดสอบหน่วย — เป็นฐานที่รวดเร็วและเชื่อถือได้ซึ่งกลยุทธ์การทดสอบอื่น ๆ ของคุณจะสร้างขึ้น +หลักสูตรนี้เน้นที่ **unit tests** ที่รันในเครื่องแต่ละชุดทดสอบจะสาธิตแนวคิด LangChain4j เฉพาะอย่างในแยกจากกัน พีระมิดการทดสอบด้านล่างแสดงตำแหน่งของ unit tests — ซึ่งเป็นพื้นฐานที่รวดเร็วและเชื่อถือได้ที่แผนกลยุทธ์การทดสอบอื่นๆ สร้างขึ้น Testing Pyramid -*พีระมิดการทดสอบแสดงความสมดุลระหว่างการทดสอบหน่วย (รวดเร็ว แยกส่วน), การทดสอบแบบบูรณาการ (ส่วนประกอบจริง), และการทดสอบแบบ end-to-end การฝึกอบรมนี้ครอบคลุมการทดสอบหน่วย* +*พีระมิดการทดสอบแสดงความสมดุลระหว่าง unit tests (รวดเร็ว, แยกจากกัน), integration tests (ส่วนประกอบจริง), และ end-to-end tests การฝึกอบรมนี้ครอบคลุม unit testing* -| โมดูล | การทดสอบ | โฟกัส | ไฟล์หลัก | +| โมดูล | การทดสอบ | จุดสนใจ | ไฟล์หลัก | |--------|-------|-------|-----------| -| **00 - เริ่มต้นอย่างรวดเร็ว** | 6 | เทมเพลตพรอมต์และการแทนที่ตัวแปร | `SimpleQuickStartTest.java` | -| **01 - บทนำ** | 8 | หน่วยความจำการสนทนาและแชทที่มีสถานะ | `SimpleConversationTest.java` | -| **02 - การสร้างพรอมต์** | 12 | รูปแบบ GPT-5.2, ระดับความกระตือรือร้น, เอาต์พุตที่มีโครงสร้าง | `SimpleGpt5PromptTest.java` | +| **01 - บทนำ** | 8 | ความทรงจำบทสนทนาและแชทแบบมีสถานะ | `SimpleConversationTest.java` | +| **02 - การออกแบบ Prompt** | 12 | รูปแบบ GPT-5.2, ระดับความกระตือรือร้น, เอาต์พุตแบบมีโครงสร้าง | `SimpleGpt5PromptTest.java` | | **03 - RAG** | 10 | การนำเข้าข้อมูลเอกสาร, การฝังตัว, การค้นหาความคล้ายคลึง | `DocumentServiceTest.java` | -| **04 - เครื่องมือ** | 12 | การเรียกใช้งานฟังก์ชันและการเชื่อมโยงเครื่องมือ | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | โปรโตคอล Model Context กับการขนส่ง stdio | `SimpleMcpTest.java` | +| **04 - เครื่องมือ** | 12 | การเรียกฟังก์ชันและการเชื่อมเครื่องมือ | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | โปรโตคอลบริบทโมเดลกับการส่งผ่าน stdio | `SimpleMcpTest.java` | ## การรันการทดสอบ -**รันการทดสอบทั้งหมดจากโฟลเดอร์ราก:** +**รันการทดสอบทั้งหมดจากโฟลเดอร์ root:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**รันคลาสการทดสอบเดียว:** +**รันการทดสอบคลาสเดียว:** **Bash:** ```bash @@ -103,33 +102,33 @@ mvn test -Dtest=SimpleConversationTest#ควรรักษาประวั mvn --% test -Dtest=SimpleConversationTest#ควรรักษาประวัติการสนทนาไว้ ``` -## การรันการทดสอบใน VS Code +## การรันทดสอบใน VS Code -หากคุณใช้ Visual Studio Code เครื่องมือ Test Explorer จะให้ส่วนติดต่อกราฟิกสำหรับรันและดีบักการทดสอบ +หากคุณใช้ Visual Studio Code, Test Explorer ให้ส่วนต่อประสานกราฟิกสำหรับการรันและดีบักการทดสอบ VS Code Test Explorer -*VS Code Test Explorer แสดงโครงสร้างต้นไม้การทดสอบพร้อมคลาสการทดสอบ Java ทั้งหมดและเมธอดทดสอบรายตัว* +*VS Code Test Explorer แสดงโครงสร้างต้นไม้การทดสอบพร้อมคลาสทดสอบ Java ทั้งหมดและเมธอดทดสอบแยก* -**วิธีการรันการทดสอบใน VS Code:** +**วิธีรันทดสอบใน VS Code:** -1. เปิด Test Explorer โดยคลิกไอคอนบีกเกอร์ใน Activity Bar -2. ขยายต้นไม้การทดสอบเพื่อดูโมดูลและคลาสทดสอบทั้งหมด -3. คลิกปุ่มเล่นข้างการทดสอบใดก็ได้เพื่อรันแบบเดี่ยว -4. คลิก "Run All Tests" เพื่อรันชุดทั้งหมด -5. คลิกขวาการทดสอบแล้วเลือก "Debug Test" เพื่อวางเบรกพอยต์และเดินโค้ดทีละขั้น +1. เปิด Test Explorer โดยคลิกไอคอนบีกเกอร์ในแถบ Activity +2. ขยายโครงสร้างต้นไม้การทดสอบเพื่อดูโมดูลและคลาสทดสอบทั้งหมด +3. คลิกปุ่มเล่นข้างการทดสอบใดก็ได้เพื่อรันทดสอบแยก +4. คลิก "Run All Tests" เพื่อรันชุดทดสอบทั้งหมด +5. คลิกขวาที่การทดสอบแล้วเลือก "Debug Test" ตั้งเบรกพอยต์และก้าวผ่านโค้ด -Test Explorer จะแสดงเครื่องหมายถูกสีเขียวสำหรับการทดสอบที่ผ่านและแสดงข้อความความล้มเหลวโดยละเอียดเมื่อการทดสอบล้มเหลว +Test Explorer แสดงเครื่องหมายถูกสีเขียวเมื่อการทดสอบผ่านและแจ้งข้อความความล้มเหลวอย่างละเอียดเมื่อการทดสอบล้มเหลว ## รูปแบบการทดสอบ -### รูปแบบที่ 1: การทดสอบเทมเพลตพรอมต์ +### รูปแบบ 1: การทดสอบ Prompt Templates -รูปแบบที่ง่ายที่สุดคือการทดสอบเทมเพลตพรอมต์โดยไม่เรียกใช้โมเดล AI คุณตรวจสอบว่าการแทนที่ตัวแปรทำงานถูกต้องและพรอมต์ถูกจัดรูปแบบตามที่คาดไว้ +รูปแบบที่ง่ายที่สุดทดสอบเทมเพลต prompt โดยไม่ต้องเรียกโมเดล AI คุณจะตรวจสอบว่าการแทนที่ตัวแปรทำงานถูกต้องและ prompt ถูกฟอร์แมตตามที่คาดหวัง Prompt Template Testing -*การทดสอบเทมเพลตพรอมต์แสดงกระบวนการแทนที่ตัวแปร: เทมเพลตพร้อมช่องว่าง → ค่าที่ถูกนำไปใช้ → ตรวจสอบเอาต์พุตที่จัดรูปแบบ* +*การทดสอบเทมเพลต prompt แสดงการไหลของการแทนที่ตัวแปร: เทมเพลตที่มีตัวแปร → ค่าถูกนำไปใช้ → ยืนยันเอาต์พุตที่ฟอร์แมต* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -การทดสอบนี้อยู่ใน `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` +รูปแบบนี้ยืนยันว่าการแทนที่ตัวแปรทำงานถูกต้องและ prompt ถูกฟอร์แมตตามที่ควร — ไม่ต้องใช้คีย์ API หรือเรียกโมเดล -**รันได้ด้วย:** +### รูปแบบ 2: การ Mock โมเดลภาษา -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#การทดสอบการจัดรูปแบบเทมเพลตพร้อมท์ -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#ทดสอบฟอร์แมตเท็มเพลตแบบข้อความ -``` - -### รูปแบบที่ 2: การจำลองโมเดลภาษา - -เมื่อทดสอบตรรกะการสนทนา ให้ใช้ Mockito สร้างโมเดลปลอมที่คืนค่าตอบสนองที่กำหนดไว้ล่วงหน้า วิธีนี้ทำให้การทดสอบเร็ว ฟรี และมีผลลัพธ์แน่นอน +เมื่อทดสอบตรรกะบทสนทนา ใช้ Mockito สร้างโมเดลปลอมที่ส่งคืนคำตอบที่กำหนดไว้ล่วงหน้า นี้ทำให้การทดสอบรวดเร็ว ฟรี และคาดเดาได้ Mock vs Real API Comparison -*การเปรียบเทียบแสดงเหตุผลที่การใช้ mocks เหมาะสำหรับการทดสอบ: เร็ว ฟรี แน่นอน และไม่ต้องใช้คีย์ API* +*เปรียบเทียบแสดงว่าทำไม mocks จึงถูกเลือกสำหรับการทดสอบ: เร็ว, ฟรี, คาดเดาได้ และไม่ต้องใช้คีย์ API* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 ข้อความของผู้ใช้ + 3 ข้อความของ AI + assertThat(history).hasSize(6); // ข้อความจากผู้ใช้ 3 ข้อความ + ข้อความจาก AI 3 ข้อความ } } ``` -รูปแบบนี้พบได้ใน `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` ซึ่ง mock ช่วยให้พฤติกรรมคงที่เพื่อคุณจะยืนยันได้ว่าการจัดการหน่วยความจำทำงานถูกต้อง +รูปแบบนี้ปรากฏใน `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` mock ช่วยให้พฤติกรรมคงที่เพื่อให้คุณตรวจสอบการจัดการความจำทำงานถูกต้อง -### รูปแบบที่ 3: การทดสอบแยกความเป็นอิสระของการสนทนา +### รูปแบบ 3: การทดสอบการแยกบทสนทนา -หน่วยความจำการสนทนาต้องแยกผู้ใช้หลายคนออกจากกัน การทดสอบนี้ยืนยันว่าการสนทนาแต่ละชุดไม่ผสมผสานบริบทกัน +ความทรงจำของบทสนทนาจะต้องแยกผู้ใช้หลายคนออกจากกัน การทดสอบนี้ยืนยันว่าบทสนทนาไม่มีการผสมบริบท Conversation Isolation -*การทดสอบแยกความเป็นอิสระของการสนทนาแสดงที่เก็บหน่วยความจำแยกต่างหากสำหรับผู้ใช้ต่างกันเพื่อป้องกันการผสมบริบท* +*การทดสอบการแยกบทสนทนาแสดงที่เก็บความจำแยกต่างหากสำหรับผู้ใช้ต่าง ๆ เพื่อป้องกันการผสมบริบท* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -แต่ละการสนทนาจะรักษาประวัติแบบอิสระของตัวเอง ในระบบการผลิต การแยกนี้มีความสำคัญสำหรับแอปหลายผู้ใช้ +แต่ละบทสนทนาจะเก็บประวัติของตนเองอย่างอิสระ ในระบบโปรดักชัน การแยกนี้สำคัญสำหรับแอปพลิเคชันหลายผู้ใช้ -### รูปแบบที่ 4: การทดสอบเครื่องมืออย่างอิสระ +### รูปแบบ 4: การทดสอบเครื่องมือแบบอิสระ -เครื่องมือเป็นฟังก์ชันที่ AI สามารถเรียกใช้ ทดสอบเครื่องมือโดยตรงเพื่อให้แน่ใจว่าทำงานถูกต้องไม่ว่าจะตัดสินใจของ AI เป็นอย่างไร +เครื่องมือคือฟังก์ชันที่ AI สามารถเรียกใช้ ทดสอบเครื่องมือโดยตรงเพื่อให้แน่ใจว่าทำงานถูกต้องโดยไม่ขึ้นกับการตัดสินใจของ AI Tools Testing -*การทดสอบเครื่องมืออย่างอิสระแสดงการรันเครื่องมือแบบ mock โดยไม่ต้องเรียก AI เพื่อยืนยันตรรกะธุรกิจ* +*การทดสอบเครื่องมือแบบอิสระแสดงการรันเครื่องมือแบบ mock โดยไม่ต้องเรียก AI เพื่อยืนยันตรรกะธุรกิจ* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -การทดสอบเหล่านี้จาก `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ตรวจสอบตรรกะเครื่องมือโดยไม่เกี่ยวข้องกับ AI ตัวอย่างการเชื่อมโยงแสดงว่าเอาต์พุตของเครื่องมือหนึ่งป้อนเป็นอินพุตของอีกเครื่องมือได้อย่างไร +การทดสอบนี้จาก `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ตรวจสอบตรรกะเครื่องมือโดยไม่เกี่ยวข้องกับ AI ตัวอย่างการเชื่อมโยงแสดงเอาต์พุตของเครื่องมือหนึ่งเป็นอินพุตของอีกเครื่องมือหนึ่ง -### รูปแบบที่ 5: การทดสอบ RAG ในหน่วยความจำ +### รูปแบบ 5: การทดสอบ RAG ในหน่วยความจำ -ระบบ RAG โดยทั่วไปต้องใช้ฐานข้อมูลเวกเตอร์และบริการฝังข้อมูล รูปแบบในหน่วยความจำช่วยให้คุณทดสอบท่อทั้งระบบโดยไม่พึ่งพาภายนอก +ระบบ RAG โดยทั่วไปต้องการฐานข้อมูลเวกเตอร์และบริการ embedding รูปแบบในหน่วยความจำช่วยให้คุณทดสอบทั้ง pipeline โดยไม่ต้องพึ่งพาภายนอก In-Memory RAG Testing -*เวิร์กโฟลว์การทดสอบ RAG ในหน่วยความจำแสดงการแยกเอกสาร การเก็บข้อมูลฝัง และการค้นหาความคล้ายคลึงโดยไม่ต้องใช้ฐานข้อมูล* +*เวิร์กโฟลว์การทดสอบ RAG ในหน่วยความจำแสดงการแยกเอกสาร, การเก็บ embedding, และการค้นหาความคล้ายคลึงโดยไม่ต้องใช้ฐานข้อมูล* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -การทดสอบนี้จาก `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` สร้างเอกสารในหน่วยความจำและตรวจสอบการแบ่งชิ้นส่วนและการจัดการเมตาดาต้า +การทดสอบนี้จาก `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` สร้างเอกสารในหน่วยความจำและตรวจสอบการแบ่งส่วนและการจัดการเมตาดาต้า -### รูปแบบที่ 6: การทดสอบการบูรณาการ MCP +### รูปแบบ 6: การทดสอบการผสาน MCP -โมดูล MCP ทดสอบการบูรณาการโปรโตคอล Model Context โดยใช้การขนส่ง stdio การทดสอบเหล่านี้ยืนยันว่าแอปของคุณสามารถเปิดและสื่อสารกับเซิร์ฟเวอร์ MCP ในรูปแบบ subprocess ได้ +โมดูล MCP ทดสอบการผสาน Model Context Protocol โดยใช้การส่งผ่าน stdio การทดสอบเหล่านี้ตรวจสอบว่าแอปของคุณสามารถสร้างและสื่อสารกับเซิร์ฟเวอร์ MCP เป็น subprocess ได้ การทดสอบใน `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` ตรวจสอบพฤติกรรมของลูกค้า MCP -**รันได้ด้วย:** +**รันได้ดังนี้:** **Bash:** ```bash @@ -328,28 +315,27 @@ cd 05-mcp; mvn --% test ## ปรัชญาการทดสอบ -ทดสอบโค้ดของคุณ ไม่ใช่ AI การทดสอบของคุณควรตรวจสอบโค้ดที่คุณเขียนโดยดูว่าพรอมต์ถูกสร้างอย่างไร, การจัดการหน่วยความจำเป็นอย่างไร และการเรียกใช้เครื่องมือเป็นอย่างไร ตอบสนองของ AI มีความแปรผันและไม่ควรเป็นส่วนหนึ่งของการตรวจสอบผลการทดสอบ ถามว่าพรอมต์เทมเพลตของคุณแทนที่ตัวแปรถูกต้องหรือไม่ ไม่ใช่ว่า AI ให้คำตอบถูกต้องหรือไม่ +ทดสอบโค้ดของคุณ ไม่ใช่ AI การทดสอบของคุณควรตรวจสอบโค้ดที่คุณเขียนโดยเช็คว่าพรอมต์ถูกสร้างอย่างไร ความจำถูกจัดการอย่างไร และเครื่องมือทำงานได้อย่างไร การตอบสนองของ AI มีความแปรผันและไม่ควรเป็นส่วนหนึ่งของข้อสรุปของการทดสอบ ถามตัวเองว่าพรอมต์ของคุณแทนที่ตัวแปรได้ถูกต้องหรือไม่ ไม่ใช่ว่า AI ให้คำตอบถูกหรือไม่ -ใช้ mocks สำหรับโมเดลภาษา พวกเขาเป็นการพึ่งพาภายนอกที่ช้า แพง และไม่แน่นอน การใช้ mock ทำให้การทดสอบเร็วในระดับมิลลิวินาทีแทนที่จะเป็นวินาที ฟรีโดยไม่เสียค่าใช้จ่าย API และแน่นอนเพราะผลลัพธ์เหมือนเดิมทุกครั้ง +ใช้ mock สำหรับโมเดลภาษา พวกมันเป็นการพึ่งพาภายนอกที่ช้า, แพง, และไม่คงที่ การทำ mock ทำให้การทดสอบรวดเร็ววัดเป็นมิลลิวินาทีแทนวินาที, ฟรีไม่มีค่าใช้จ่าย API, และคงที่ได้ผลลัพธ์เหมือนเดิมทุกครั้ง -รักษาการทดสอบให้แยกจากกัน การทดสอบแต่ละตัวควรกำหนดข้อมูลของตัวเอง ไม่พึ่งพาการทดสอบอื่น และทำความสะอาดหลังจบการทดสอบ การทดสอบควรผ่านไม่ว่าจะรันในลำดับใดก็ตาม +รักษาการทดสอบให้เป็นอิสระ แต่ละการทดสอบควรตั้งค่าข้อมูลของตัวเอง ไม่อาศัยการทดสอบอื่น และล้างข้อมูลหลังทำเสร็จ การทดสอบควรผ่านไม่ว่าจะรันลำดับไหน -ทดสอบกรณีขอบเขตที่เกินเส้นทางปกติ ลองป้อนข้อมูลว่าง, ข้อมูลขนาดใหญ่มาก, ตัวอักษรพิเศษ, พารามิเตอร์ที่ไม่ถูกต้อง และเงื่อนไขขอบเขต กรณีเหล่านี้มักเปิดเผยบั๊กที่การใช้งานปกติไม่พบ +ทดสอบกรณีขอบเขตนอกเหนือเส้นทางปกติ ลองอินพุตว่าง, อินพุตขนาดใหญ่มาก, อักขระพิเศษ, พารามิเตอร์ไม่ถูกต้อง, และเงื่อนไขขอบเขต เหล่านี้มักเปิดเผยข้อบกพร่องที่การใช้งานปกติไม่แสดง -ใช้ชื่อที่บ่งบอกความหมาย เปรียบเทียบ `shouldMaintainConversationHistoryAcrossMultipleMessages()` กับ `test1()` ชื่อแรกบอกชัดเจนว่าทดสอบอะไร ทำให้การดีบักความล้มเหลวง่ายขึ้นมาก +ใช้ชื่อที่สื่อความหมาย เปรียบเทียบ `shouldMaintainConversationHistoryAcrossMultipleMessages()` กับ `test1()` ชื่อแรกบอกว่าอะไรถูกทดสอบ ทำให้แก้ไขข้อผิดพลาดได้ง่ายขึ้นมาก ## ขั้นตอนถัดไป -เมื่อคุณเข้าใจรูปแบบการทดสอบแล้ว ให้เจาะลึกแต่ละโมดูล: +เมื่อคุณเข้าใจรูปแบบการทดสอบแล้ว ดำดิ่งลึกลงในแต่ละโมดูล: -- **[00 - เริ่มต้นอย่างรวดเร็ว](../00-quick-start/README.md)** - เริ่มต้นกับพื้นฐานเทมเพลตพรอมต์ -- **[01 - บทนำ](../01-introduction/README.md)** - เรียนรู้การจัดการหน่วยความจำการสนทนา -- **[02 - การสร้างพรอมต์](../02/prompt-engineering/README.md)** - ฝึกฝนรูปแบบการสร้างพรอมต์ GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - สร้างระบบการสร้างข้อมูลเรียกค้นแบบเสริม -- **[04 - เครื่องมือ](../04-tools/README.md)** - ใช้ฟังก์ชันการเรียกใช้งานและการเชื่อมโยงเครื่องมือ -- **[05 - MCP](../05-mcp/README.md)** - รวมโปรโตคอล Model Context +- **[01 - บทนำ](../01-introduction/README.md)** - เรียนรู้การจัดการความทรงจำบทสนทนา +- **[02 - การออกแบบ Prompt](../02-prompt-engineering/README.md)** - เชี่ยวชาญรูปแบบ prompting GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - สร้างระบบ retrieval-augmented generation +- **[04 - เครื่องมือ](../04-tools/README.md)** - ใช้งานการเรียกฟังก์ชันและสายงานเครื่องมือ +- **[05 - MCP](../05-mcp/README.md)** - ผสานโปรโตคอลบริบทโมเดล -README ของแต่ละโมดูลอธิบายรายละเอียดแนวคิดที่ทดสอบในที่นี้ +README ของแต่ละโมดูลให้คำอธิบายอย่างละเอียดของแนวคิดที่ทดสอบในนี้ --- @@ -358,6 +344,6 @@ README ของแต่ละโมดูลอธิบายรายละ --- -**คำปฏิเสธความรับผิดชอบ**: -เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษาด้วย AI [Co-op Translator](https://github.com/Azure/co-op-translator) แม้เราจะพยายามให้ความถูกต้อง โปรดทราบว่าการแปลอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถือเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยผู้เชี่ยวชาญทางภาษามนุษย์ เราจะไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความผิดที่เกิดขึ้นจากการใช้การแปลนี้ +**ปฏิเสธความรับผิดชอบ**: +เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI [Co-op Translator](https://github.com/Azure/co-op-translator) ขณะที่เราพยายามให้ความถูกต้อง โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดที่เกิดขึ้นจากการใช้การแปลนี้ \ No newline at end of file diff --git a/translations/tl/.co-op-translator.json b/translations/tl/.co-op-translator.json index d0d4af45c..b70d5423f 100644 --- a/translations/tl/.co-op-translator.json +++ b/translations/tl/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "tl" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T20:42:30+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T10:23:20+00:00", "source_file": "01-introduction/README.md", "language_code": "tl" }, @@ -18,20 +18,20 @@ "language_code": "tl" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T20:45:17+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T10:19:03+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "tl" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T20:47:05+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T10:22:34+00:00", "source_file": "03-rag/README.md", "language_code": "tl" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T12:42:14+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T10:21:15+00:00", "source_file": "04-tools/README.md", "language_code": "tl" }, @@ -54,8 +54,8 @@ "language_code": "tl" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:13:46+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T10:17:40+00:00", "source_file": "README.md", "language_code": "tl" }, @@ -72,14 +72,14 @@ "language_code": "tl" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T20:50:37+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T10:19:27+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "tl" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T20:51:28+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T10:20:02+00:00", "source_file": "docs/TESTING.md", "language_code": "tl" } diff --git a/translations/tl/00-quick-start/README.md b/translations/tl/00-quick-start/README.md deleted file mode 100644 index b4a07dea4..000000000 --- a/translations/tl/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Quick Start - -## Table of Contents - -- [Panimula](../../../00-quick-start) -- [Ano ang LangChain4j?](../../../00-quick-start) -- [Mga Depensiya ng LangChain4j](../../../00-quick-start) -- [Mga Kinakailangan](../../../00-quick-start) -- [Setup](../../../00-quick-start) - - [1. Kunin ang Iyong GitHub Token](../../../00-quick-start) - - [2. Itakda ang Iyong Token](../../../00-quick-start) -- [Patakbuhin ang mga Halimbawa](../../../00-quick-start) - - [1. Pangunahing Chat](../../../00-quick-start) - - [2. Mga Pattern ng Prompt](../../../00-quick-start) - - [3. Pagtawag sa Function](../../../00-quick-start) - - [4. Document Q&A (Madaling RAG)](../../../00-quick-start) - - [5. Responsable na AI](../../../00-quick-start) -- [Ano ang Ipinapakita ng Bawat Halimbawa](../../../00-quick-start) -- [Mga Susunod na Hakbang](../../../00-quick-start) -- [Pag-troubleshoot](../../../00-quick-start) - -## Panimula - -Ang quickstart na ito ay inilaan upang mapabilis kang makapagsimula gamit ang LangChain4j. Sinasaklaw nito ang pinaka-pangunahing kaalaman sa pagbuo ng mga AI na aplikasyon gamit ang LangChain4j at GitHub Models. Sa mga susunod na module, lilipat ka sa Azure OpenAI at GPT-5.2 at sisisid nang mas malalim sa bawat konsepto. - -## Ano ang LangChain4j? - -Ang LangChain4j ay isang Java library na nagpapadali sa pagbuo ng mga AI-powered na aplikasyon. Sa halip na harapin ang mga HTTP client at pag-parse ng JSON, gagana ka gamit ang malilinis na Java APIs. - -Ang "chain" sa LangChain ay tumutukoy sa pagsasama-sama ng maraming bahagi - maaaring gumawa ka ng chain mula sa prompt papunta sa model papunta sa parser, o pagsamahin ang maraming tawag sa AI kung saan ang output ng isa ay magiging input ng susunod. Nakatuon ang quick start na ito sa mga pangunahing kaalaman bago tuklasin ang mas kumplikadong mga chain. - -LangChain4j Chaining Concept - -*Pagsasama-sama ng mga bahagi sa LangChain4j - ang mga bloke ng gusali ay nag-uugnay upang lumikha ng makapangyarihang mga workflow ng AI* - -Gagamitin namin ang tatlong pangunahing bahagi: - -**ChatModel** - Ang interface para sa mga interaksyon ng AI model. Tawagin ang `model.chat("prompt")` at makakuha ng tugon na string. Ginagamit namin ang `OpenAiOfficialChatModel` na gumagana sa mga endpoint na compatible sa OpenAI tulad ng GitHub Models. - -**AiServices** - Lumilikha ng type-safe na mga interface ng AI service. Tukuyin ang mga method, lagyan sila ng anotasyon na `@Tool`, at ang LangChain4j ang bahala sa orchestration. Awtomatikong tinatawagan ng AI ang iyong mga Java method kapag kailangan. - -**MessageWindowChatMemory** - Pinapanatili ang kasaysayan ng pag-uusap. Kung wala ito, ang bawat request ay hiwalay. Kung mayroon ito, naaalala ng AI ang mga naunang mensahe at pinananatili ang konteksto sa maraming palitan. - -LangChain4j Architecture - -*Arkitektura ng LangChain4j - ang pangunahing mga bahagi na nagtutulungan upang paandarin ang iyong mga AI na aplikasyon* - -## Mga Depensiya ng LangChain4j - -Gumagamit ang quick start na ito ng tatlong Maven dependencies sa [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Ang `langchain4j-open-ai-official` module ay nagbibigay ng `OpenAiOfficialChatModel` class na kumokonekta sa mga OpenAI-compatible na API. Ginagamit ng GitHub Models ang parehong format ng API, kaya hindi kailangan ng espesyal na adapter - ituro lang ang base URL sa `https://models.github.ai/inference`. - -Ang `langchain4j-easy-rag` module ay nagbibigay ng awtomatikong pag-split, embedding, at retrieval ng dokumento upang makapagtayo ka ng mga RAG application nang hindi mano-manong kinokonpigura ang bawat hakbang. - -## Mga Kinakailangan - -**Gumagamit ng Dev Container?** Nakainstall na ang Java at Maven. Kailangan mo lang ang isang GitHub Personal Access Token. - -**Lokal na Pag-develop:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (mga tagubilin sa ibaba) - -> **Tandaan:** Ginagamit ng module na ito ang `gpt-4.1-nano` mula sa GitHub Models. Huwag baguhin ang pangalan ng model sa code - ito ay naka-configure upang gumana sa mga available na modelo ng GitHub. - -## Setup - -### 1. Kunin ang Iyong GitHub Token - -1. Pumunta sa [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. I-click ang "Generate new token" -3. Maglagay ng makabuluhang pangalan (halimbawa, "LangChain4j Demo") -4. Itakda ang expiration (7 araw ang inirerekomenda) -5. Sa ilalim ng "Account permissions", hanapin ang "Models" at itakda ito sa "Read-only" -6. I-click ang "Generate token" -7. Kopyahin at i-save ang iyong token - hindi mo na ito makikita muli - -### 2. Itakda ang Iyong Token - -**Opsyon 1: Paggamit ng VS Code (Inirerekomenda)** - -Kung gumagamit ka ng VS Code, idagdag ang iyong token sa `.env` file sa root ng proyekto: - -Kung wala ang `.env` file, kopyahin ang `.env.example` papuntang `.env` o gumawa ng bagong `.env` file sa root ng proyekto. - -**Halimbawa ng `.env` file:** -```bash -# Sa /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Pagkatapos ay maaari ka nang mag-right click sa kahit anong demo file (hal., `BasicChatDemo.java`) sa Explorer at piliin ang **"Run Java"** o gamitin ang mga launch configuration mula sa Run and Debug panel. - -**Opsyon 2: Paggamit ng Terminal** - -Itakda ang token bilang environment variable: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Patakbuhin ang mga Halimbawa - -**Gamit ang VS Code:** I-right click lang ang kahit anong demo file sa Explorer at piliin ang **"Run Java"**, o gamitin ang launch configurations mula sa Run and Debug panel (siguraduhing nailagay mo muna ang iyong token sa `.env` file). - -**Gamit ang Maven:** Bilang alternatibo, maaari mong patakbuhin mula sa command line: - -### 1. Pangunahing Chat - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Mga Pattern ng Prompt - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Ipinapakita ang zero-shot, few-shot, chain-of-thought, at role-based na prompting. - -### 3. Pagtawag sa Function - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -Awtomatikong tinatawagan ng AI ang iyong mga Java method kapag kailangan. - -### 4. Document Q&A (Madaling RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Magtanong tungkol sa iyong mga dokumento gamit ang Easy RAG na may awtomatikong embedding at retrieval. - -### 5. Responsable na AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Tingnan kung paano pinipigilan ng AI safety filters ang mapanganib na nilalaman. - -## Ano ang Ipinapakita ng Bawat Halimbawa - -**Pangunahing Chat** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Magsimula dito upang makita ang LangChain4j sa pinaka-simple nitong anyo. Gumagawa ka ng `OpenAiOfficialChatModel`, magpapadala ng prompt gamit ang `.chat()`, at makakakuha ng tugon. Ipinapakita nito ang pundasyon: kung paano i-initialize ang mga modelo na may custom endpoints at API keys. Kapag naiintindihan mo na ang pattern na ito, ang lahat ay naka-base rito. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) at itanong: -> - "Paano ako lilipat mula sa GitHub Models papuntang Azure OpenAI sa code na ito?" -> - "Anong ibang mga parameter ang maaari kong i-configure sa OpenAiOfficialChatModel.builder()?" -> - "Paano ako magdadagdag ng streaming responses imbes na maghintay ng kumpletong sagot?" - -**Prompt Engineering** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Ngayon na alam mo na kung paano makipag-usap sa model, tuklasin natin kung ano ang sinasabi mo rito. Ginagamit ng demo na ito ang parehong setup ng model ngunit ipinapakita ang limang iba't ibang pattern ng prompting. Subukan ang zero-shot prompts para sa direktang utos, few-shot prompts na natututo mula sa mga halimbawa, chain-of-thought prompts na nagpapakita ng mga hakbang sa pag-iisip, at role-based prompts na nagtatakda ng konteksto. Makikita mo kung paano nagkakaroon ng malaking pagkakaiba ang mga resulta depende sa kung paano mo pinapahayag ang iyong kahilingan. - -Ipinapakita rin ng demo ang prompt templates, na isang makapangyarihang paraan upang gumawa ng mga reusable prompt na may mga variable. -Ipinapakita sa ibaba ang halimbawa ng prompt gamit ang LangChain4j `PromptTemplate` para punan ang mga variable. Sasagutin ng AI batay sa ibinigay na destinasyon at aktibidad. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) at itanong: -> - "Ano ang pagkakaiba ng zero-shot at few-shot prompting, at kailan ko dapat gamitin ang bawat isa?" -> - "Paano nakakaapekto ang temperature parameter sa mga sagot ng model?" -> - "Ano ang mga teknik para maiwasan ang prompt injection attacks sa produksyon?" -> - "Paano ako makakalikha ng reusable PromptTemplate objects para sa mga karaniwang pattern?" - -**Tool Integration** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Dito nagiging makapangyarihan ang LangChain4j. Gagamitin mo ang `AiServices` upang lumikha ng AI assistant na kayang tumawag sa iyong mga Java method. Lagyan lang ng anotasyon ang mga method gamit ang `@Tool("description")` at ang LangChain4j ang bahala sa iba - awtomatikong tinutukoy ng AI kung kailan gagamitin ang bawat tool base sa tanong ng user. Ipinapakita nito ang function calling, isang mahalagang teknik para gumawa ng AI na kayang kumilos, hindi lang sumagot ng tanong. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) at itanong: -> - "Paano gumagana ang @Tool annotation at ano ang ginagawa ng LangChain4j dito sa likod ng mga eksena?" -> - "Maaari bang tumawag ang AI ng maraming tool ng sunod-sunod para lutasin ang mga kumplikadong problema?" -> - "Ano ang nangyayari kapag may tool na nag-throw ng exception - paano ko dapat harapin ang mga error?" -> - "Paano ko isasama ang totoong API imbes na ang halimbawa ng calculator na ito?" - -**Document Q&A (Madaling RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Dito makikita mo ang RAG (retrieval-augmented generation) gamit ang "Easy RAG" na paraan ng LangChain4j. Ang mga dokumento ay niloload, awtomatikong hinahati at ine-embed sa isang in-memory na storage, pagkatapos ay ang content retriever ang nagbibigay ng mga kaugnay na bahagi sa AI kapag nagtatanong. Sumagot ang AI batay sa iyong mga dokumento, hindi sa pangkalahatang kaalaman nito. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) at itanong: -> - "Paano pinipigilan ng RAG ang mga hallucination ng AI kumpara sa paggamit ng training data ng model?" -> - "Ano ang pagkakaiba ng madaling paraan na ito at ng isang custom na RAG pipeline?" -> - "Paano ko masusukat ito upang mag-handle ng maraming dokumento o mas malalaking knowledge bases?" - -**Responsable na AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Gumawa ng kaligtasan sa AI gamit ang multiple layers ng proteksyon. Ipinapakita ng demo na ito ang dalawang antas ng proteksyon na nagtutulungan: - -**Bahagi 1: LangChain4j Input Guardrails** - Pinipigilan ang mga mapanganib na prompt bago pa man makarating ito sa LLM. Gumawa ng custom guardrails na sumusuri sa mga ipinagbabawal na keyword o pattern. Isinasagawa ito sa iyong code, kaya mabilis at libre. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Bahagi 2: Provider Safety Filters** - May mga built-in na filter ang GitHub Models na kumukuha ng mga maaaring mapalampas ng guardrails mo. Makikita mo ang mga hard blocks (HTTP 400 errors) para sa malalalang paglabag at soft refusals kung saan magalang na tinatanggihan ng AI. - -> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) at itanong: -> - "Ano ang InputGuardrail at paano ako makagagawa ng sarili ko?" -> - "Ano ang pagkakaiba ng hard block at soft refusal?" -> - "Bakit ginagamit ang parehong guardrails at provider filters nang sabay?" - -## Mga Susunod na Hakbang - -**Susunod na Module:** [01-introduction - Getting Started with LangChain4j](../01-introduction/README.md) - ---- - -**Navigation:** [← Back to Main](../README.md) | [Susunod: Module 01 - Panimula →](../01-introduction/README.md) - ---- - -## Pag-troubleshoot - -### Unang Build ng Maven - -**Isyu**: Ang unang `mvn clean compile` o `mvn package` ay tumatagal nang matagal (10-15 minuto) - -**Sanhi**: Kailangang i-download ng Maven ang lahat ng dependencies ng proyekto (Spring Boot, LangChain4j libraries, Azure SDKs, atbp.) sa unang build. - -**Solusyon**: Normal lang ito. Mas mabilis ang mga susunod na build dahil naka-cache na ang dependencies lokal. Depende ang tagal ng pag-download sa bilis ng iyong network. - -### Syntax ng PowerShell Maven Command - -**Isyu**: Nabibigo ang mga command ng Maven na may error na `Unknown lifecycle phase ".mainClass=..."` -**Sanhi**: Tinuturing ng PowerShell ang `=` bilang operator ng pagtatalaga ng variable, na sumisira sa syntax ng property ng Maven - -**Solusyon**: Gamitin ang stop-parsing operator na `--%` bago ang command ng Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Sinasabi ng operator na `--%` sa PowerShell na ipasa nang literal sa Maven ang lahat ng natitirang argumento nang walang interpretasyon. - -### Pagpapakita ng Emoji sa Windows PowerShell - -**Isyu**: Nagpapakita ang mga AI na tugon ng mga walang saysay na karakter (hal. `????` o `â??`) sa halip na mga emoji sa PowerShell - -**Sanhi**: Hindi sinusuportahan ng default na encoding ng PowerShell ang UTF-8 na mga emoji - -**Solusyon**: Patakbuhin ang command na ito bago magpatakbo ng mga Java application: -```cmd -chcp 65001 -``` - -Pinipilit nito ang UTF-8 encoding sa terminal. Bilang alternatibo, gamitin ang Windows Terminal na may mas mahusay na suporta sa Unicode. - -### Pag-debug ng Mga Tawag sa API - -**Isyu**: Mga error sa authentication, mga limitasyon sa rate, o hindi inaasahang mga tugon mula sa modelo ng AI - -**Solusyon**: Kasama sa mga halimbawa ang `.logRequests(true)` at `.logResponses(true)` upang ipakita ang mga tawag sa API sa console. Nakakatulong ito sa pag-troubleshoot ng mga error sa authentication, mga limitasyon sa rate, o hindi inaasahang mga tugon. Alisin ang mga flag na ito sa produksyon upang mabawasan ang ingay ng log. - ---- - - -**Pagtatakwil**: -Ang dokumentong ito ay isinalin gamit ang serbisyong AI na pagsasalin [Co-op Translator](https://github.com/Azure/co-op-translator). Bagaman aming pinagsisikapang maging tumpak, pakatandaan na ang mga awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o di-tumpak na impormasyon. Ang orihinal na dokumento sa likas nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang hindi pagkakaunawaan o maling interpretasyon na magmumula sa paggamit ng pagsasaling ito. - \ No newline at end of file diff --git a/translations/tl/01-introduction/README.md b/translations/tl/01-introduction/README.md index a40942ae1..cd5cd701f 100644 --- a/translations/tl/01-introduction/README.md +++ b/translations/tl/01-introduction/README.md @@ -1,20 +1,20 @@ # Module 01: Pagsisimula sa LangChain4j -## Table of Contents - -- [Pagsusuri sa Video](../../../01-introduction) -- [Ano ang Matututunan Mo](../../../01-introduction) -- [Mga Kinakailangan](../../../01-introduction) -- [Pag-unawa sa Pangunahing Suliranin](../../../01-introduction) -- [Pag-unawa sa Tokens](../../../01-introduction) -- [Paano Gumagana ang Memorya](../../../01-introduction) -- [Paano Ito Gumagamit ng LangChain4j](../../../01-introduction) -- [I-deploy ang Azure OpenAI Infrastructure](../../../01-introduction) -- [Patakbuhin ang Aplikasyon nang Lokal](../../../01-introduction) -- [Paggamit ng Aplikasyon](../../../01-introduction) - - [Stateless Chat (Kaliwang Panel)](../../../01-introduction) - - [Stateful Chat (Kanan Panel)](../../../01-introduction) -- [Mga Susunod na Hakbang](../../../01-introduction) +## Talaan ng Nilalaman + +- [Video Walkthrough](#video-walkthrough) +- [Ano ang Matututunan Mo](#ano-ang-matututunan-mo) +- [Mga Kinakailangan](#mga-kinakailangan) +- [Pag-unawa sa Pangunahing Problema](#pag-unawa-sa-pangunahing-problema) +- [Pag-unawa sa mga Token](#pag-unawa-sa-mga-token) +- [Paano Gumagana ang Memorya](#paano-gumagana-ang-memorya) +- [Paano Ito Gumagamit ng LangChain4j](#paano-ito-gumagamit-ng-langchain4j) +- [I-deploy ang Azure OpenAI Infrastructure](#i-deploy-ang-azure-openai-infrastructure) +- [Patakbuhin ang Aplikasyon Nang Lokal](#patakbuhin-ang-aplikasyon-nang-lokal) +- [Paggamit ng Aplikasyon](#paggamit-ng-aplikasyon) + - [Stateless Chat (Kaliwang Panel)](#stateless-chat-kaliwang-panel) + - [Stateful Chat (Kanang Panel)](#stateful-chat-kanang-panel) +- [Mga Susunod na Hakbang](#mga-susunod-na-hakbang) ## Video Walkthrough @@ -22,66 +22,66 @@ Panoorin ang live session na ito na nagpapaliwanag kung paano magsimula sa modul Getting Started with LangChain4j - Live Session -## What You'll Learn +## Ano ang Matututunan Mo -Sa mabilis na pagsisimula, ginamit mo ang GitHub Models upang magpadala ng mga prompt, tumawag ng mga tool, bumuo ng RAG pipeline, at subukan ang mga guardrails. Ipinakita ng mga demo na iyon ang mga posibilidad — ngayon ay lilipat tayo sa Azure OpenAI at GPT-5.2 at magsisimulang bumuo ng mga aplikasyon na parang production. Ang module na ito ay nakatuon sa conversational AI na nakakatanda ng konteksto at nagpapanatili ng estado — mga konseptong ginamit ng mga quick start demos ngunit hindi ipinaliwanag. +Ito ang iyong panimulang punto sa LangChain4j at Azure OpenAI. Magsisimula tayo sa mga pundasyon at sisimulang bumuo ng mga aplikasyon na pang-production. Nakatuon ang module na ito sa conversational AI na nakakaalala ng konteksto at nagpapanatili ng estado — ang mga pundamental na konsepto na pinagbatayan ng bawat susunod na module. -Gagamitin natin ang Azure OpenAI's GPT-5.2 sa buong gabay na ito dahil ang mga advanced na kakayahan nito sa pangangatwiran ay nagpapakita nang malinaw ng mga pag-uugali ng iba't ibang pattern. Kapag nagdagdag ka ng memorya, makikita mo nang malinaw ang pagkakaiba. Mas madali itong maintindihan kung ano ang idinudulot ng bawat bahagi sa iyong aplikasyon. +Gagamitin natin ang Azure OpenAI's GPT-5.2 sa buong gabay na ito dahil sa mga advanced na kakayahan nito sa pangangatwiran na nagpapalinaw sa pag-uugali ng iba't ibang mga pattern. Kapag inadd mo ang memorya, makikita mo nang malinaw ang pagkakaiba. Mas pinadadali nito ang pag-unawa kung ano ang dinadala ng bawat komponent sa iyong aplikasyon. -Gagawa ka ng isang aplikasyon na nagpapakita ng parehong pattern: +Bubuuin mo ang isang aplikasyon na nagpapakita ng dalawang pattern: -**Stateless Chat** - Bawat kahilingan ay independyente. Walang alaala ang modelo ng mga naunang mensahe. Ito ang pattern na ginamit mo sa quick start. +**Stateless Chat** - Ang bawat kahilingan ay independyente. Walang memorya ang modelo ng mga nakaraang mensahe. Ito ang pinakasimpleng panimulang punto. -**Stateful Conversation** - Kasama sa bawat kahilingan ang kasaysayan ng pag-uusap. Pinananatili ng modelo ang konteksto sa maraming pag-ikot. Ito ang kailangan ng mga production application. +**Stateful Conversation** - Kasama sa bawat kahilingan ang kasaysayan ng pag-uusap. Pinapanatili ng modelo ang konteksto sa maraming pag-uusap. Ito ang kinakailangan ng mga aplikasyon sa production. -## Prerequisites +## Mga Kinakailangan -- Azure subscription na may access sa Azure OpenAI +- Subscription sa Azure na may access sa Azure OpenAI - Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Note:** Nakainstall na ang Java, Maven, Azure CLI at Azure Developer CLI (azd) sa ipinakitang devcontainer. +> **Note:** Nakainstall na ang Java, Maven, Azure CLI at Azure Developer CLI (azd) sa ibinigay na devcontainer. -> **Note:** Ginagamit ng module na ito ang GPT-5.2 sa Azure OpenAI. Ang deployment ay awtomatikong naka-configure gamit ang `azd up` - huwag baguhin ang pangalan ng modelo sa code. +> **Note:** Ginagamit ng module na ito ang GPT-5.2 sa Azure OpenAI. Ang deployment ay awtomatikong nakasetup gamit ang `azd up` - huwag baguhin ang pangalan ng modelo sa code. -## Understanding the Core Problem +## Pag-unawa sa Pangunahing Problema -Ang mga language model ay stateless. Bawat API call ay independyente. Kung magpapadala ka ng "My name is John" at pagkatapos ay magtatanong ng "What's my name?", wala itong ideya na ipinakilala mo na ang iyong pangalan. Itinuturing nitong bawat kahilingan ay parang una mong pag-uusap. +Ang mga language model ay stateless. Ang bawat tawag sa API ay independyente. Kung ipapadala mo ang "My name is John" at pagkatapos ay itanong "What’s my name?", wala itong ideya na ipinakilala mo lang ang iyong sarili. Tinatrato nito ang bawat kahilingan na parang iyon ang unang pag-uusap mo kailanman. -Ayos lang ito para sa simpleng tanong at sagot pero useless para sa tunay na aplikasyon. Kailangan ng mga customer service bots na maalala ang sinasabi mo. Kailangan ng mga personal assistant ng konteksto. Ang anumang multi-turn na pag-uusap ay nangangailangan ng memorya. +Ayos ito para sa simpleng Q&A ngunit hindi kapaki-pakinabang para sa mga totoong aplikasyon. Kailangang tandaan ng mga customer service bot ang sinabi mo sa kanila. Kailangang may konteksto ang mga personal assistant. Anumang multi-turn na pag-uusap ay nangangailangan ng memorya. -Ang sumusunod na diagram ay nagpapakita ng kaibahan ng dalawang pamamaraan — sa kaliwa, isang stateless call na nakakalimot ng iyong pangalan; sa kanan, isang stateful call gamit ang ChatMemory na nakakatanda nito. +Ipinapakita ng sumusunod na diagram ang pagkakaiba ng dalawang paraan — sa kaliwa, isang stateless call na nakakalimot ng pangalan mo; sa kanan, isang stateful call na sinuportahan ng ChatMemory na natatandaan ito. Stateless vs Stateful Conversations -*Pagkakaiba ng stateless (independiyenteng tawag) at stateful (may kontekstong pag-uusap)* +*Ang pagkakaiba sa pagitan ng stateless (mga independyenteng tawag) at stateful (may kamalayang konteksto) na mga pag-uusap* -## Understanding Tokens +## Pag-unawa sa mga Token -Bago tumalon sa mga pag-uusap, mahalagang maintindihan ang tokens - ang mga pangunahing yunit ng teksto na pinoproseso ng mga language model: +Bago pumasok sa mga pag-uusap, mahalagang maintindihan ang mga token - mga pangunahing yunit ng teksto na pinoproseso ng mga language model: Token Explanation -*Halimbawa kung paano hinahati ang teksto sa mga tokens - "I love AI!" ay nahahati sa 4 na magkakahiwalay na yunit* +*Halimbawa kung paano hahatiin ang teksto sa mga token - "I love AI!" ay nagiging 4 na hiwalay na yunit ng proseso* -Ang mga tokens ang sukatan at proseso ng AI models sa teksto. Puwedeng maging tokens ang mga salita, bantas, at kahit mga spaces. May limitasyon ang iyong modelo kung ilang mga tokens ang pwede nitong iproseso nang sabay (400,000 para sa GPT-5.2, na may hanggang 272,000 input tokens at 128,000 output tokens). Ang pag-unawa sa tokens ay tumutulong sa pamamahala ng haba ng pag-uusap at mga gastos. +Ang mga token ay sukatan ng AI models sa pagsukat at pagproseso ng teksto. Mga salita, bantas, at maging mga spaces ay maaaring mga token. May limitasyon ang iyong modelo sa bilang ng token na kayang iproseso ng sabay (400,000 para sa GPT-5.2, na may hanggang 272,000 input tokens at 128,000 output tokens). Nakakatulong ang pag-unawa sa mga token upang mas maayos mong mapamahalaan ang haba ng pag-uusap at gastos. -## How Memory Works +## Paano Gumagana ang Memorya -Nilulutas ng chat memory ang problemang stateless sa pamamagitan ng pagpapanatili ng kasaysayan ng pag-uusap. Bago ipadala ang iyong kahilingan sa modelo, ang framework ay inilalagay muna ang mga relevant na naunang mensahe. Kapag tinanong mo "What's my name?", ipinapadala ng sistema ang buong kasaysayan ng pag-uusap, kaya nakikita ng modelo na sinabi mo kanina "My name is John." +Nilulutas ng chat memory ang problema ng pagiging stateless sa pamamagitan ng pagpapanatili ng kasaysayan ng pag-uusap. Bago ipadala ang iyong kahilingan sa modelo, pinapalimbag ng framework ang mga kaugnay na mga naunang mensahe. Kapag tinanong mo "What’s my name?", ipinapadala ng sistema ang buong kasaysayan ng pag-uusap, kaya nakikita ng modelo na sinasabi mo kanina "My name is John." -Nagbibigay ang LangChain4j ng mga implementasyon ng memory na nag-aasikaso nito nang awtomatiko. Pinipili mo kung ilang mga mensahe ang itatago at inaasikaso ng framework ang context window. Ipinapakita ng diagram sa ibaba kung paano pinapanatili ng MessageWindowChatMemory ang sliding window ng mga kamakailang mensahe. +Nagbibigay ang LangChain4j ng mga memory implementation na awtomatikong humahawak nito. Pinipili mo kung ilan ang mga mensaheng itatago at ang framework ang nagmanage ng context window. Ipinapakita ng diagram sa ibaba kung paano nagpapanatili ang MessageWindowChatMemory ng sliding window ng mga pinakabagong mensahe. Memory Window Concept -*Pinapanatili ng MessageWindowChatMemory ang sliding window ng mga kamakailang mensahe, awtomatikong tine-tanggal ang mga luma* +*Pinapanatili ng MessageWindowChatMemory ang sliding window ng mga pinakabagong mensahe, awtomatikong tinatanggal ang mga lumang mensahe* -## How This Uses LangChain4j +## Paano Ito Gumagamit ng LangChain4j -Pinapalawig ng module na ito ang quick start sa pamamagitan ng pagsasama ng Spring Boot at pagdagdag ng conversation memory. Ganito ang pagsasama-sama ng mga bahagi: +Pinagsasama ng module na ito ang Spring Boot at nagdaragdag ng conversation memory. Ganito ang pagkakapuwesto ng mga bahagi: -**Dependencies** - Magdagdag ng dalawang LangChain4j libraries: +**Mga Dependensya** - Magdagdag ng dalawang LangChain4j libraries: ```xml @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Binabasa ng builder ang mga kredensyal mula sa environment variables na nakaset ng `azd up`. Ang pagtatakda ng `baseUrl` sa iyong Azure endpoint ay nagagamit ang OpenAI client sa Azure OpenAI. +Binabasa ng builder ang mga kredensyal mula sa environment variables na itinakda ng `azd up`. Ang pagseset ng `baseUrl` sa iyong Azure endpoint ay nagpapagana sa OpenAI client para gumana sa Azure OpenAI. -**Conversation Memory** - Subaybayan ang chat history gamit ang MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Conversation Memory** - Subaybayan ang kasaysayan ng chat gamit ang MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,16 +124,16 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Gumawa ng memorya gamit ang `withMaxMessages(10)` para itago ang huling 10 mensahe. Magdagdag ng user at AI messages gamit ang typed wrappers: `UserMessage.from(text)` at `AiMessage.from(text)`. Kunin ang history gamit ang `memory.messages()` at ipadala ito sa modelo. Ang serbisyo ay nagtatalaga ng hiwalay na memory instance bawat conversation ID, na nagpapahintulot sa maraming user na mag-chat nang sabay-sabay. +Gumawa ng memorya gamit ang `withMaxMessages(10)` para panatilihin ang huling 10 mensahe. Magdagdag ng mga mensahe ng user at AI gamit ang mga typed wrappers: `UserMessage.from(text)` at `AiMessage.from(text)`. Kunin ang kasaysayan gamit ang `memory.messages()` at ipadala ito sa modelo. Nag-iimbak ang serbisyo ng magkakahiwalay na mga memory instance sa bawat conversation ID, na nagpapahintulot sa maraming gumagamit na makipag-chat nang sabay-sabay. > **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) at itanong: -> - "Paano pinipili ng MessageWindowChatMemory kung aling mga mensahe ang tatanggalin kapag puno na ang window?" -> - "Puwede ba akong mag-implement ng custom memory storage gamit ang database imbes na in-memory?" -> - "Paano ako magdagdag ng summarization para i-compress ang lumang kasaysayan ng pag-uusap?" +> - "Paano pinipili ng MessageWindowChatMemory kung alin sa mga mensahe ang tatanggalin kapag puno na ang window?" +> - "Puwede ko bang ipatupad ang custom memory storage gamit ang database sa halip na in-memory?" +> - "Paano ko idadagdag ang summarization para kumonpres ang lumang kasaysayan ng pag-uusap?" -Ang stateless chat endpoint ay hindi gumagamit ng memorya - `chatModel.chat(prompt)` lang tulad ng quick start. Ang stateful endpoint ay nagdaragdag ng mga mensahe sa memorya, kumukuha ng kasaysayan, at isinasama ang kontekstong iyon sa bawat kahilingan. Parehong configuration ng modelo, magkaibang mga pattern. +Ang stateless chat endpoint ay hindi gumagamit ng memorya — simpleng `chatModel.chat(prompt)` tulad ng quick start. Ang stateful endpoint naman ay nagdadagdag ng mga mensahe sa memorya, kinukuha ang kasaysayan, at isinasama ang kontekstong iyon sa bawat kahilingan. Parehong configuration ng modelo, magkaibang mga pattern. -## Deploy Azure OpenAI Infrastructure +## I-deploy ang Azure OpenAI Infrastructure **Bash:** ```bash @@ -147,16 +147,16 @@ cd 01-introduction azd up # Piliin ang subscription at lokasyon (inirerekomenda ang eastus2) ``` -> **Note:** Kung makatagpo ka ng timeout error (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), patakbuhin lang muli ang `azd up`. Maaaring nagpo-provision pa ang mga Azure resources sa background, at ang muling pagsubok ay nagpapahintulot sa deployment na matapos kapag naabot na ng mga resources ang terminal state. +> **Note:** Kung makaranas ka ng timeout error (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), patakbuhin lang muli ang `azd up`. Maaaring nagpapatuloy pa ang provisioning ng Azure resources sa background, at ang pagsubok muli ay nagpapahintulot sa deployment na matapos kapag naabot ng mga resources ang terminal state. Ito ay: -1. Mag-deploy ng Azure OpenAI resource kasama ang GPT-5.2 at text-embedding-3-small models -2. Awtomatikong gagawa ng `.env` file sa root ng proyekto na may mga kredensyal +1. Magde-deploy ng Azure OpenAI resource na may GPT-5.2 at text-embedding-3-small models +2. Awtomatikong gagawa ng `.env` file sa root ng proyekto na may kredensyal 3. Magse-set up ng lahat ng kinakailangang environment variables -**May problema ba sa deployment?** Tingnan ang [Infrastructure README](infra/README.md) para sa detalyadong troubleshooting tulad ng mga conflict sa pangalan ng subdomain, manwal na steps ng deployment sa Azure Portal, at gabay sa configuration ng modelo. +**May problema sa deployment?** Tingnan ang [Infrastructure README](infra/README.md) para sa detalyadong troubleshooting tulad ng subdomain name conflicts, mga hakbang sa manual Azure Portal deployment, at mga gabay sa model configuration. -**Siguraduhin na matagumpay ang deployment:** +**Kumpirmahin ang tagumpay ng deployment:** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # Dapat ipakita ang AZURE_OPENAI_ENDPOINT, API_KEY, atbp. Get-Content ..\.env # Dapat ipakita ang AZURE_OPENAI_ENDPOINT, API_KEY, atbp. ``` -> **Note:** Ang `azd up` command ay awtomatikong gumagawa ng `.env` file. Kung kailangan mo itong i-update mamaya, maaari mong i-edit ang `.env` file nang manu-mano o i-regenerate ito gamit ang: +> **Note:** Ang `azd up` command ay awtomatikong lumilikha ng `.env` file. Kung kailangan mo itong baguhin mamaya, maaari mo itong i-edit nang manu-mano o muling gawin ang pag-generate sa pamamagitan ng pagpapatakbo ng: > > **Bash:** > ```bash @@ -182,11 +182,11 @@ Get-Content ..\.env # Dapat ipakita ang AZURE_OPENAI_ENDPOINT, API_KEY, atbp. > .\.azd-env.ps1 > ``` -## Run the Application Locally +## Patakbuhin ang Aplikasyon Nang Lokal -**Siguraduhing matagumpay ang deployment:** +**Kumpirmahin ang deployment:** -Tiyakin na mayroon ang `.env` file sa root directory na may Azure credentials. Patakbuhin ito mula sa module directory (`01-introduction/`): +Siguraduhing naroroon ang `.env` file sa root directory na may Azure credentials. Patakbuhin ito mula sa directory ng module (`01-introduction/`): **Bash:** ```bash @@ -200,25 +200,25 @@ Get-Content ..\.env # Dapat ipakita ang AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Simulan ang mga aplikasyon:** -**Option 1: Gamit ang Spring Boot Dashboard (Inirerekomenda sa mga gumagamit ng VS Code)** +**Opsiyon 1: Gamit ang Spring Boot Dashboard (Inirerekomenda para sa mga gumagamit ng VS Code)** -Kasama sa dev container ang Spring Boot Dashboard extension, na nagbibigay ng visual interface para pamahalaan ang lahat ng Spring Boot na aplikasyon. Makikita ito sa Activity Bar sa kaliwang bahagi ng VS Code (hanapin ang Spring Boot icon). +Kasama sa dev container ang Spring Boot Dashboard extension, na nagbibigay ng visual interface para pamahalaan ang lahat ng Spring Boot applications. Makikita mo ito sa Activity Bar sa kaliwa ng VS Code (hanapin ang icon ng Spring Boot). Mula sa Spring Boot Dashboard, maaari mong: -- Makita lahat ng available na Spring Boot applications sa workspace -- Simulan/hintuin ang mga aplikasyon sa isang click lamang -- Tingnan ang mga logs ng aplikasyon nang real-time -- Bantayan ang status ng aplikasyon +- Tingnan lahat ng Spring Boot applications sa workspace +- Simulan/hintuan ang mga aplikasyon gamit ang isang click lang +- Tingnan ang mga log ng aplikasyon nang real-time +- I-monitor ang status ng aplikasyon -I-click lang ang play button sa tabi ng "introduction" para simulan ang module na ito, o simulan lahat ng modules ng sabay. +Pindutin lang ang play button sa tabi ng "introduction" para simulan ang module na ito, o simulan ang lahat ng modules ng sabay-sabay. Spring Boot Dashboard -*Spring Boot Dashboard sa VS Code — simulan, hintuin, at bantayan ang lahat ng module mula sa isang lugar* +*Ang Spring Boot Dashboard sa VS Code — simulan, hintuan, at i-monitor lahat ng modules mula sa isang lugar* -**Option 2: Gamit ang shell scripts** +**Opsiyon 2: Gamit ang mga shell script** -Simulan lahat ng web applications (modules 01-04): +Simulan ang lahat ng web applications (mga module 01-04): **Bash:** ```bash @@ -232,7 +232,7 @@ cd .. # Mula sa root directory .\start-all.ps1 ``` -O simulan lang ang module na ito: +O simulan lamang ang module na ito: **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -Awtomatikong niloload ng parehong script ang environment variables mula sa root `.env` file at ibubuo ang mga JAR kung wala pa. +Awtomatikong niloload ng mga script ang environment variables mula sa root `.env` file at buuin ang mga JAR kung wala pa. -> **Note:** Kung nais mong manu-manong i-build lahat ng modules bago magsimula: +> **Note:** Kung nais mong manu-manong buuin lahat ng modules bago simulan: > > **Bash:** > ```bash @@ -264,59 +264,59 @@ Awtomatikong niloload ng parehong script ang environment variables mula sa root Buksan ang http://localhost:8080 sa iyong browser. -**Para huminto:** +**Para itigil:** **Bash:** ```bash -./stop.sh # Module na ito lamang +./stop.sh # Ang modulong ito lamang # O cd .. && ./stop-all.sh # Lahat ng mga module ``` **PowerShell:** ```powershell -.\stop.ps1 # Tanging module na ito lamang +.\stop.ps1 # Para sa module na ito lamang # O cd ..; .\stop-all.ps1 # Lahat ng mga module ``` -## Using the Application +## Paggamit ng Aplikasyon -Nagbibigay ang aplikasyon ng web interface na may dalawang chat implementations na magkatabi. +Nagbibigay ang aplikasyon ng web interface na may dalawang chat implementations na magkakatabi. Application Home Screen -*Dashboard na nagpapakita ng parehong Simple Chat (stateless) at Conversational Chat (stateful) na mga opsyon* +*Dashboard na nagpapakita ng Simple Chat (stateless) at Conversational Chat (stateful) na mga opsyon* ### Stateless Chat (Kaliwang Panel) -Subukan mo ito muna. Sabihin ang "My name is John" at pagkatapos ay agad itanong "What's my name?" Hindi ito makatatanda dahil bawat mensahe ay independyente. Ipinapakita nito ang pangunahing problema sa basic na integration ng language model - walang konteksto ng pag-uusap. +Subukan ito muna. Itanong ang "My name is John" at pagkatapos ay agad itanong "What’s my name?" Hindi matatandaan ng modelo dahil ang bawat mensahe ay independyente. Ipinapakita nito ang pangunahing problema sa simpleng integrasyon ng language model — walang konteksto ng pag-uusap. Stateless Chat Demo -*Hindi natatandaan ng AI ang iyong pangalan mula sa nakaraang mensahe* +*Hindi natatandaan ng AI ang iyong pangalan mula sa naunang mensahe* -### Stateful Chat (Kanan Panel) +### Stateful Chat (Kanang Panel) -Ngayon subukan mo ang parehong pagkakasunod dito. Sabihin ang "My name is John" at pagkatapos ay "What's my name?" Ngayon ay natatandaan nito. Ang pagkakaiba ay ang MessageWindowChatMemory - pinananatili nito ang kasaysayan ng pag-uusap at isinama ito sa bawat kahilingan. Ganito gumagana ang production conversational AI. +Ngayon subukan ang parehong hulihan dito. Itanong "My name is John" at pagkatapos ay "What’s my name?" Sa pagkakataong ito, natatandaan. Ang pinagkaiba ay ang MessageWindowChatMemory — pinapanatili nito ang kasaysayan ng pag-uusap at isinasama ito sa bawat kahilingan. Ganito gumagana ang production conversational AI. Stateful Chat Demo -*Natandaaan ng AI ang iyong pangalan mula sa nakaraang pag-uusap* +*Natatandaan ng AI ang iyong pangalan mula sa naunang pag-uusap* -Parehong GPT-5.2 ang ginagamit ng dalawang panel. Ang tanging pinagkaiba ay memorya. Ginagawa nitong malinaw kung ano ang idinudulot ng memorya sa iyong aplikasyon at bakit ito mahalaga para sa tunay na paggamit. +Parehong gumagamit ang dalawang panel ng GPT-5.2 model. Ang nag-iisang pagkakaiba ay ang memorya. Ito ang nagpapalinaw kung ano ang idinudulot ng memorya sa iyong aplikasyon at kung bakit ito mahalaga para sa mga totoong kaso ng paggamit. -## Next Steps +## Mga Susunod na Hakbang -**Next Module:** [02-prompt-engineering - Prompt Engineering with GPT-5.2](../02-prompt-engineering/README.md) +**Susunod na Module:** [02-prompt-engineering - Prompt Engineering with GPT-5.2](../02-prompt-engineering/README.md) --- -**Navigation:** [← Previous: Module 00 - Quick Start](../00-quick-start/README.md) | [Back to Main](../README.md) | [Next: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) +**Pag-navigate:** [← Babalik sa Pangunahing Pahina](../README.md) | [Susunod: Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- -**Paunawa**: -Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagaman sinisikap naming maging tumpak, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o di-tumpak na bahagi. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang hindi pagkakaunawaan o maling interpretasyon na maaaring magmula sa paggamit ng pagsasaling ito. +**Pagtatanggi**: +Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kami para sa katumpakan, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang maling pagkakaintindi o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito. \ No newline at end of file diff --git a/translations/tl/02-prompt-engineering/README.md b/translations/tl/02-prompt-engineering/README.md index 434efdc66..1e189f19e 100644 --- a/translations/tl/02-prompt-engineering/README.md +++ b/translations/tl/02-prompt-engineering/README.md @@ -1,85 +1,85 @@ # Module 02: Prompt Engineering gamit ang GPT-5.2 -## Table of Contents - -- [Video Walkthrough](../../../02-prompt-engineering) -- [What You'll Learn](../../../02-prompt-engineering) -- [Prerequisites](../../../02-prompt-engineering) -- [Understanding Prompt Engineering](../../../02-prompt-engineering) -- [Prompt Engineering Fundamentals](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Templates](../../../02-prompt-engineering) -- [Advanced Patterns](../../../02-prompt-engineering) -- [Run the Application](../../../02-prompt-engineering) -- [Application Screenshots](../../../02-prompt-engineering) -- [Exploring the Patterns](../../../02-prompt-engineering) - - [Low vs High Eagerness](../../../02-prompt-engineering) - - [Task Execution (Tool Preambles)](../../../02-prompt-engineering) - - [Self-Reflecting Code](../../../02-prompt-engineering) - - [Structured Analysis](../../../02-prompt-engineering) - - [Multi-Turn Chat](../../../02-prompt-engineering) - - [Step-by-Step Reasoning](../../../02-prompt-engineering) - - [Constrained Output](../../../02-prompt-engineering) -- [What You're Really Learning](../../../02-prompt-engineering) -- [Next Steps](../../../02-prompt-engineering) +## Talaan ng mga Nilalaman + +- [Video Walkthrough](#video-walkthrough) +- [Ano ang Matututunan Mo](#ano-ang-matututunan-mo) +- [Mga Kinakailangan](#mga-kinakailangan) +- [Pag-unawa sa Prompt Engineering](#pag-unawa-sa-prompt-engineering) +- [Mga Pangunahing Kaalaman sa Prompt Engineering](#mga-pangunahing-kaalaman-sa-prompt-engineering) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Mga Advanced na Pattern](#mga-advanced-na-pattern) +- [Patakbuhin ang Aplikasyon](#patakbuhin-ang-aplikasyon) +- [Mga Screenshot ng Aplikasyon](#mga-screenshot-ng-aplikasyon) +- [Paggalugad sa mga Pattern](#pagsubok-sa-mga-pattern) + - [Mababa vs Mataas na Pagsisikap](#mababang-vs-mataas-na-eagerness) + - [Pagpapatupad ng Gawain (Mga Preambles ng Tool)](#pagpapaganap-ng-gawain-tool-preambles) + - [Self-Reflecting Code](#self-reflecting-code) + - [Structured Analysis](#structured-analysis) + - [Multi-Turn Chat](#multi-turn-chat) + - [Hakbang-hakbang na Pag-iisip](#hakbang-hakbang-na-pag-iisip) + - [Limitadong Output](#limitadong-output) +- [Ang Tunay na Iyong Natutunan](#ano-ang-talagang-iyong-natututuhan) +- [Mga Susunod na Hakbang](#mga-susunod-na-hakbang) ## Video Walkthrough -Panoorin ang live session na ito na nagpapaliwanag kung paano magsimula sa module na ito: +Panoorin ang live session na ito na nagpapaliwanag kung paano magsimula gamit ang module na ito: Prompt Engineering with LangChain4j - Live Session -## What You'll Learn +## Ano ang Matututunan Mo -Ang sumusunod na diagram ay nagbibigay ng pangkalahatang ideya ng mga pangunahing paksa at kasanayan na iyong mauunawaan sa module na ito — mula sa mga teknik ng pagpipino ng prompt hanggang sa step-by-step workflow na iyong susundan. +Ang sumusunod na diagram ay nagbibigay ng pangkalahatang ideya ng mga pangunahing paksa at kasanayan na iyong i-de-develop sa module na ito — mula sa mga teknik ng pag-refine ng prompt hanggang sa hakbang-hakbang na workflow na susundan mo. What You'll Learn -Sa mga naunang module, na-explore mo ang mga basic LangChain4j na interaksyon gamit ang GitHub Models at nakita kung paano pinapagana ng memorya ang conversational AI gamit ang Azure OpenAI. Ngayon, tututok tayo sa kung paano ka nagtatanong — ang mismong mga prompt — gamit ang GPT-5.2 ng Azure OpenAI. Malaki ang epekto ng pagstruktura ng mga prompt sa kalidad ng mga sagot na matatanggap mo. Magsisimula tayo sa pag-review ng mga pangunahing teknik sa pag-prompt, tapos lilipat tayo sa walong advanced na pattern na ganap na nakikinabang sa kakayahan ng GPT-5.2. +Sa nakaraang module, nakita mo kung paano nagbibigay ang memorya ng kakayahan sa conversational AI gamit ang Azure OpenAI. Ngayon tututok tayo sa kung paano ka magtatanong — ang mga prompt mismo — gamit ang GPT-5.2 ng Azure OpenAI. Ang paraan ng pagbuo ng iyong mga prompt ay malaki ang epekto sa kalidad ng mga sagot na makukuha mo. Magsisimula tayo sa pagsusuri ng mga pangunahing teknik ng prompting, pagkatapos ay lilipat sa walong advanced na pattern na ganap na umaabante sa kakayahan ng GPT-5.2. -Gagamit tayo ng GPT-5.2 dahil ipinakikilala nito ang reasoning control - maaari mong sabihin sa modelo kung gaano karami ang pag-iisip bago sumagot. Pinapalinaw nito ang iba't ibang estratehiya ng pag-prompt at tinutulungan kang maintindihan kung kailan gagamitin ang bawat paraan. Magkakaroon din tayo ng benepisyo sa mas kaunting rate limits ng Azure para sa GPT-5.2 kumpara sa GitHub Models. +Gagamit tayo ng GPT-5.2 dahil nagdadala ito ng kontrol sa pag-iisip - maaari mong sabihin sa modelo kung gaano karaming pag-iisip ang gagawin bago sumagot. Pinapalinaw nito ang iba't ibang stratihiya ng prompting at tinutulungan kang maunawaan kung kailan gagamitin ang bawat isa. -## Prerequisites +## Mga Kinakailangan -- Nakumpleto ang Module 01 (Azure OpenAI resources ay nadeploy na) +- Nakumpleto na ang Module 01 (naka-deploy na Azure OpenAI resources) - `.env` file sa root directory na may Azure credentials (nilikha ng `azd up` sa Module 01) -> **Note:** Kung hindi mo pa natatapos ang Module 01, sundin muna ang deployment instructions doon. +> **Tandaan:** Kung hindi mo pa natatapos ang Module 01, sundan muna ang mga tagubilin sa deployment doon. -## Understanding Prompt Engineering +## Pag-unawa sa Prompt Engineering -Sa pinakapuno ng kahulugan, ang prompt engineering ay ang pagkakaiba sa pagitan ng malabong instruksyon at tiyak na mga instruksyon, tulad ng ipinapakita ng paghahambing sa ibaba. +Sa pinakapayak na kahulugan, ang prompt engineering ay ang pagkakaiba sa pagitan ng malabong mga tagubilin at tumpak na mga tagubilin, tulad ng ipinapakita ng paghahambing sa ibaba. What is Prompt Engineering? -Ang prompt engineering ay tungkol sa pagdisenyo ng input na teksto na palaging nagbibigay sa iyo ng mga resulta na kailangan mo. Hindi ito tungkol lang sa pagtatanong - ito ay tungkol sa pagstruktura ng mga kahilingan upang maunawaan ng modelo kung ano talaga ang gusto mo at kung paano ito ihahatid. +Ang prompt engineering ay tungkol sa pagdidisenyo ng input na teksto na palagian ay nakakuha sa iyo ng mga resulta na kailangan mo. Hindi lamang ito ang pagtatanong - ito ay ang pagbuo ng mga kahilingan upang maintindihan ng modelo nang eksakto kung ano ang gusto mo at paano ito ihahatid. -Isipin mo ito na parang pagbibigay ng mga instruksiyon sa isang katrabaho. "Ayusin ang bug" ay malabo. "Ayusin ang null pointer exception sa UserService.java linya 45 sa pamamagitan ng pagdagdag ng null check" ay tiyak. Ganun din ang mga language model - mahalaga ang pagiging tiyak at ang kaayusan. +Isipin ito na parang nagbibigay ng instruksyon sa isang kasamahan. "Ayusin ang bug" ay malabo. "Ayusin ang null pointer exception sa UserService.java linya 45 sa pamamagitan ng pagdagdag ng null check" ay tiyak. Gumagana ang mga language model nang ganito — mahalaga ang espesipisidad at istruktura. -Ipinapakita ng diagram sa ibaba kung paano kasya ang LangChain4j sa larangang ito — ikinakabit ang iyong mga prompt pattern sa modelo sa pamamagitan ng mga SystemMessage at UserMessage na mga bahagi. +Ipinapakita ng diagram sa ibaba kung paano pumapasok ang LangChain4j sa larawan na ito — ikinakonekta ang iyong mga pattern ng prompt sa modelo sa pamamagitan ng mga SystemMessage at UserMessage na mga pang-construct. How LangChain4j Fits -Nagbibigay ang LangChain4j ng imprastruktura — mga koneksyon sa modelo, memorya, at uri ng mga mensahe — habang ang mga prompt pattern ay mga maingat na naistrukturang teksto na ipinapadala mo sa pamamagitan ng imprastrukturang iyon. Ang mga pangunahing bahagi ay ang `SystemMessage` (na nagtatakda ng ugali at papel ng AI) at `UserMessage` (na nagdadala ng iyong aktwal na kahilingan). +Nagbibigay ang LangChain4j ng infrastraktura — koneksyon sa modelo, memorya, at mga uri ng mensahe — habang ang mga pattern ng prompt ay mga maingat na istrukturadong teksto na ipinapadala mo sa pamamagitan ng infrastraktura. Ang mga pangunahing sangkap ay `SystemMessage` (na nagtatakda ng ugali at papel ng AI) at `UserMessage` (na nagdadala ng iyong aktwal na kahilingan). -## Prompt Engineering Fundamentals +## Mga Pangunahing Kaalaman sa Prompt Engineering -Ang limang pangunahing teknik na ipinapakita sa ibaba ay bumubuo sa pundasyon ng epektibong prompt engineering. Bawat isa ay tumutugon sa ibang aspeto kung paano ka makikipagkomunikasyon sa mga language model. +Ang limang pangunahing teknik na ipinapakita sa ibaba ang pundasyon ng epektibong prompt engineering. Bawat isa ay tumutugon sa ibang aspeto kung paano ka makipag-usap sa mga language model. Five Prompt Engineering Patterns Overview -Bago pumasok sa mga advanced na pattern sa module na ito, balikan muna natin ang limang pundamental na teknik sa pag-prompt. Ito ang mga bloke ng pundasyon na dapat malaman ng bawat prompt engineer. Kung napag-aralan mo na ang [Quick Start module](../00-quick-start/README.md#2-prompt-patterns), nakita mo na ang mga ito sa aksyon — narito ang konseptwal na balangkas sa likod nila. +Bago tayong tumuon sa mga advanced na pattern sa module na ito, repasuhin muna natin ang limang pundamental na teknik ng prompting. Ito ang mga pundasyon na dapat malaman ng bawat prompt engineer. ### Zero-Shot Prompting -Ang pinakasimpleng paraan: bigyan ang modelo ng direktang utos na walang mga halimbawa. Umaasa ang modelo nang buo sa kanyang pagsasanay upang maunawaan at maisakatuparan ang gawain. Epektibo ito sa mga tuwirang kahilingan kung saan halata ang inaasahang ugali. +Pinakasimpleng paraan: bigyan ang modelo ng direktang instruksyon nang walang halimbawa. Ang modelo ay umaasa nang buo sa kanyang training para maintindihan at isagawa ang gawain. Mabisa ito para sa mga simpleng utos kung saan halatang inaasahan ang kilos. Zero-Shot Prompting -*Direktang utos nang walang mga halimbawa — ang modelo ay naghihinuha ng gawain mula sa utos lamang* +*Direktang instruksyon nang walang halimbawa — hinuhusgahan ng modelo ang gawain mula sa instruksyon lamang* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Tugon: "Positibo" ``` -**Kailan gagamitin:** Mga simpleng klasipikasyon, direktang tanong, pagsasalin, o anumang gawaing kaya ng modelo nang walang dagdag na gabay. +**Kailan gagamitin:** Simpleng klasipikasyon, direktang tanong, pagsasalin, o anumang gawain na kayang hawakan ng modelo nang walang dagdag na patnubay. ### Few-Shot Prompting -Magbigay ng mga halimbawa na nagpapakita ng pattern na nais mong sundan ng modelo. Natututuhan ng modelo ang inaasahang format ng input-output mula sa mga halimbawa mo at inilalapat ito sa mga bagong input. Lubhang pinapaganda nito ang konsistensi para sa mga gawaing kung saan hindi halata ang nais na format o ugali. +Magbigay ng mga halimbawa na nagpapakita ng pattern na gusto mong sundan ng modelo. Natutunan ng modelo ang inaasahang input-output na format mula sa mga halimbawa mo at inilalapat ito sa mga bagong inputs. Malaki ang pagbuti ng konsistensi para sa mga gawain na ang nais na format o asal ay hindi halata. Few-Shot Prompting -*Pagkatuto mula sa mga halimbawa — kinikilala ng modelo ang pattern at inilalapat ito sa mga bagong input* +*Pagkatuto mula sa mga halimbawa — natutukoy ng modelo ang pattern at inilalapat ito sa mga bagong inputs* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kailan gagamitin:** Pasadyang klasipikasyon, pare-parehong pag-format, mga gawain sa espesipikong domain, o kapag hindi consistent ang zero-shot na resulta. +**Kailan gagamitin:** Custom na klasipikasyon, tuloy-tuloy na pag-format, espesyalisadong gawain, o kapag hindi pare-pareho ang mga resulta ng zero-shot. ### Chain of Thought -Tanungin ang modelo na ipakita ang pag-iisip nito nang hakbang-hakbang. Sa halip na diretsong sumagot, hinahati-hati ng modelo ang problema at nilalakad ito ng bawat bahagi nang malinaw. Pinapabuti nito ang katumpakan sa math, lohika, at mga gawaing may maraming hakbang ng pag-iisip. +Hilingin sa modelo na ipakita ang pag-iisip nito hakbang-hakbang. Sa halip na direktang sumagot, hinahati ng modelo ang problema at pinag-aaralan bawat bahagi nang malinaw. Pinapabuti nito ang katumpakan sa math, lohika, at multi-step na mga gawaing pang-pagkakataon. Chain of Thought Prompting -*Hakbang-hakbang na pag-iisip — paghahati ng kumplikadong problema sa mga malinaw na lohikal na hakbang* +*Hakbang-hakbang na pangangatwiran — hinahati ang kumplikadong problema sa malinaw na lohikal na hakbang* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Ipinapakita ng modelo: 15 - 8 = 7, pagkatapos ay 7 + 12 = 19 na mansanas +// Ipinapakita ng modelo: 15 - 8 = 7, saka 7 + 12 = 19 na mansanas ``` -**Kailan gagamitin:** Mga problema sa math, palaisipan sa lohika, debugging, o anumang gawain kung saan pinapabuti ng pagpapakita ng proseso ng pag-iisip ang katumpakan at pagtitiwala. +**Kailan gagamitin:** Problema sa math, palaisipan sa lohika, debugging, o anumang gawain kung saan nakakatulong ang pagpapakita ng proseso ng pag-iisip para sa katumpakan at pagtitiwala. ### Role-Based Prompting -Itakda ang persona o papel para sa AI bago mo itanong ang iyong tanong. Nagbibigay ito ng konteksto na humuhubog sa tono, lalim, at pokus ng sagot. Ang "software architect" ay nagbibigay ng ibang payo kaysa sa "junior developer" o isang "security auditor". +Magtakda ng persona o papel para sa AI bago itanong ang iyong tanong. Nagbibigay ito ng konteksto na humuhubog sa tono, lalim, at pokus ng sagot. Iba ang pananaw ng "software architect" kumpara sa "junior developer" o "security auditor". Role-Based Prompting -*Pagtatakda ng konteksto at persona — ang parehong tanong ay nakakakuha ng ibang sagot depende sa itinalagang papel* +*Pagtatakda ng konteksto at persona — ang parehong tanong ay may ibang sagot depende sa itinalagang papel* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Kailan gagamitin:** Mga pagsusuri ng code, pagtuturo, espesipikong pagsusuri sa domain, o kapag kailangan mo ng mga sagot na iniangkop sa partikular na antas ng kadalubhasaan o pananaw. +**Kailan gagamitin:** Review ng code, pagtuturo, espesyalisadong pagsusuri, o kapag kailangan ng mga sagot na nakaayon sa isang partikular na antas ng kadalubhasaan o pananaw. ### Prompt Templates -Lumikha ng mga reusable na prompt na may mga variable placeholder. Sa halip na magsulat ng bagong prompt kada oras, tukuyin muna ang template at punan ito ng iba't ibang mga halaga. Ginagawa itong madali ng LangChain4j na `PromptTemplate` class gamit ang `{{variable}}` syntax. +Lumikha ng mga reusable na prompt na may mga placeholder na variable. Sa halip na sumulat ng bagong prompt sa bawat pagkakataon, tukuyin ang template isang beses lang at punan ang iba't ibang halaga. Pinapadali ito ng `PromptTemplate` na klase ng LangChain4j gamit ang `{{variable}}` na syntax. Prompt Templates -*Mga reusable na prompt na may mga variable placeholder — isang template, maraming gamit* +*Reusable na mga prompt na may variable placeholders — isang template, maraming gamit* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Kailan gagamitin:** Paulit-ulit na mga query na may iba't ibang input, batch processing, pagbuo ng reusable na AI workflows, o anumang senaryo kung saan pareho ang istruktura ng prompt ngunit nagbabago ang datos. +**Kailan gagamitin:** Paulit-ulit na mga tanong na may iba't ibang input, batch processing, pagbuo ng reusable na mga AI workflow, o anumang sitwasyon na pareho ang istruktura ng prompt pero nagbabago ang datos. --- -Ang limang pundamental na ito ay nagbibigay sa iyo ng matibay na kagamitan para sa karamihan ng mga gawaing prompt. Ang natitirang bahagi ng module na ito ay nakabase sa mga ito gamit ang **walo pang advanced na mga pattern** na gumagamit ng reasoning control, self-evaluation, at structured output capabilities ng GPT-5.2. +Ang limang punong teknik na ito ang nagbibigay sa iyo ng matibay na toolkit para sa karamihan ng mga gawain sa prompting. Ang natitirang bahagi ng module na ito ay bumubuo pa rito gamit ang **walong advanced na pattern** na gumagamit ng reasoning control, self-evaluation, at structured output na mga kakayahan ng GPT-5.2. -## Advanced Patterns +## Mga Advanced na Pattern -Matapos matalakay ang mga pundamental, lumipat tayo sa walong advanced na pattern na ginagawang natatangi ang module na ito. Hindi lahat ng problema ay nangangailangan ng parehong pamamaraan. Ang iba ay nangangailangan ng mabilisang sagot, ang ilan naman ay malalim na pag-iisip. Ang iba ay kailangan ng nakikitang pag-iisip, ang iba naman ay kailangan lang ng mga resulta. Ang bawat pattern sa ibaba ay naka-optimize para sa iba’t ibang senaryo — at pinatutunayan ng reasoning control ng GPT-5.2 ang pagkakaiba ng mga ito. +Pagkatapos masaklaw ang mga pundasyon, lumipat tayo sa walong advanced na pattern na nagpapasikat sa module na ito. Hindi lahat ng problema ay nangangailangan ng parehas na paraan. Ang ilang tanong ay nangangailangan ng mabilis na sagot, ang iba ay malalim na pag-iisip. Ang ilan ay nais ng nakikitang pag-iisip, ang iba ay ang resulta lamang ang kailangan. Bawat pattern sa ibaba ay na-optimize para sa ibang sitwasyon — at pinapalakas pa ng reasoning control ng GPT-5.2 ang mga pagkakaibang ito. Eight Prompting Patterns -*Pangkalahatang ideya ng walong prompt engineering pattern at kanilang mga gamit* +*Pangkalahatang ideya ng walong pattern ng prompt engineering at kanilang mga gamit* -Nagdadagdag ang GPT-5.2 ng isa pang dimensyon sa mga pattern na ito: *reasoning control*. Ipinapakita ng slider sa ibaba kung paano mo maaaring ayusin ang pagsisikap sa pag-iisip ng modelo — mula sa mabilis, diretso na mga sagot hanggang sa malalim, masusing pagsusuri. +Nagdadagdag ang GPT-5.2 ng isa pang dimensyon sa mga pattern na ito: *kontrol sa pag-iisip*. Ipinapakita ng slider sa ibaba kung paano mo maia-adjust ang pagsisikap ng pag-iisip ng modelo — mula sa mabilis, direktang mga sagot hanggang sa malalim at masusing pagsusuri. Reasoning Control with GPT-5.2 -*Hinahayaan ka ng reasoning control ng GPT-5.2 na tukuyin kung gaano karaming pag-iisip ang dapat gawin ng modelo — mula sa mabilis na direktang sagot hanggang sa malalim na pagsasaliksik* +*Pinahihintulutan ka ng reasoning control ng GPT-5.2 na tukuyin kung gaano karaming pag-iisip ang gagawin ng modelo — mula sa mabilis na direktang sagot hanggang sa malalim na pag-usisa* -**Low Eagerness (Mabilis at Nakatuon)** - Para sa mga simpleng tanong kung saan gusto mo ng mabilis at diretsong sagot. Minimal lang ang pag-iisip ng modelo - maximum na 2 hakbang. Gamitin ito sa mga kalkulasyon, paghahanap, o mga tuwirang tanong. +**Mababang Pagsisikap (Mabilis at Pokus)** - Para sa simpleng mga tanong kung saan gusto mo ng mabilis, direktang sagot. Minimal na pag-iisip ang ginagawa ng modelo - maximum 2 hakbang. Gamitin ito para sa mga kalkulasyon, paghahanap, o simpleng tanong. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Subukan gamit ang GitHub Copilot:** Buksan ang [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) at itanong: -> - "Ano ang pagkakaiba ng low eagerness at high eagerness na mga prompt pattern?" -> - "Paano nakakatulong ang XML tags sa prompts sa pagstruktura ng sagot ng AI?" -> - "Kailan dapat gumamit ng self-reflection patterns kumpara sa direktang utos?" +> 💡 **Galugarin gamit ang GitHub Copilot:** Buksan ang [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) at itanong: +> - "Ano ang pagkakaiba ng mababang pagsisikap sa mataas na pagsisikap na mga pattern ng prompting?" +> - "Paano nakakatulong ang mga XML tag sa mga prompt para istrukturahin ang sagot ng AI?" +> - "Kailan ko dapat gamitin ang mga self-reflection na pattern kumpara sa direktang instruksyon?" -**High Eagerness (Malalim at Masusing)** - Para sa mga komplikadong problema kung saan gusto mo ng komprehensibong pagsusuri. Malalim na sinusuri ng modelo at ipinapakita ang detalyadong pag-iisip. Gamitin ito para sa system design, architecture decisions, o komplikadong pananaliksik. +**Mataas na Pagsisikap (Malalim at Masusing Pagsusuri)** - Para sa mga komplikadong problema kung saan gusto mo ng komprehensibong pagsusuri. Masusing sinusuri ng modelo at ipinapakita ang detalyadong pag-iisip. Gamitin ito para sa disenyo ng sistema, mga pagpapasya sa arkitektura, o komplikadong pananaliksik. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Task Execution (Step-by-Step Progress)** - Para sa mga workflows na may maraming hakbang. Nagbibigay ang modelo ng plano sa umpisa, ikinukwento ang bawat hakbang habang ginagawa ito, pagkatapos ay nagbibigay ng buod. Gamitin ito para sa migrations, implementasyon, o anumang multi-step na proseso. +**Pagpapatupad ng Gawain (Hakbang-hakbang na Progreso)** - Para sa mga multi-step na workflow. Nagbibigay ang modelo ng planong panimula, nagsasalaysay ng bawat hakbang habang ginagawa, pagkatapos ay nagbibigay ng buod. Gamitin ito para sa mga migration, implementasyon, o anumang multi-step na proseso. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Ang Chain-of-Thought prompting ay tahasang hinihiling sa modelo na ipakita ang kanyang proseso ng pag-iisip, na nagpapabuti ng katumpakan para sa komplikadong mga gawain. Ang hakbang-hakbang na breakdown ay tumutulong pareho sa tao at AI na maintindihan ang lohika. +Ang Chain-of-Thought prompting ay tahasang hinihiling sa modelo na ipakita ang proseso ng pag-iisip, na nagpapabuti sa katumpakan para sa mga kumplikadong gawain. Ang hakbang-hakbang na paghahati ay nakakatulong sa parehong tao at AI na maunawaan ang lohika. -> **🤖 Subukan sa [GitHub Copilot](https://github.com/features/copilot) Chat:** Itanong tungkol sa pattern na ito: -> - "Paano ko iaangkop ang task execution pattern para sa mga matagal na operation?" -> - "Ano ang mga best practice para sa pagstruktura ng tool preambles sa production applications?" -> - "Paano ko mahuhuli at maipapakita ang mga intermediate progress update sa UI?" +> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Magtanong tungkol sa pattern na ito: +> - "Paano ko iaangkop ang task execution pattern para sa mga long-running operation?" +> - "Ano ang mga pinakamahusay na praktis sa pag-istruktura ng mga tool preamble sa production na mga aplikasyon?" +> - "Paano ko maisusulat at maipapakita ang mga intermediate na progreso sa isang UI?" -Ipinapakita ng diagram sa ibaba ang Plan → Execute → Summarize workflow na ito. +Ipinapakita ng diagram sa ibaba ang Plan → Execute → Summarize na workflow. Task Execution Pattern -*Plan → Execute → Summarize workflow para sa multi-step na mga gawain* +*Plan → Execute → Summarize na workflow para sa mga multi-step na gawain* -**Self-Reflecting Code** - Para sa pagbuo ng production-quality na code. Gumagawa ang modelo ng code ayon sa mga production standards na may tamang error handling. Gamitin ito kapag nagtatayo ng mga bagong feature o serbisyo. +**Self-Reflecting Code** - Para sa pagbuo ng production-quality na code. Gumagawa ang modelo ng code na sumusunod sa mga production standard na may tamang error handling. Gamitin ito kapag nagtatayo ng mga bagong feature o serbisyo. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Ipinapakita ng diagram sa ibaba ang paulit-ulit na proseso ng pagbuti — gumawa, suriin, tukuyin ang mga kahinaan, at pinuhin hanggang matugunan ng code ang mga pamantayan ng production. +Ipinapakita ng diagram sa ibaba ang loop ng iterative na pagpapabuti — gumawa, suriin, tuklasin ang kahinaan, at pagbutihin hanggang matugunan ng code ang mga pamantayang pang-produksyon. Self-Reflection Cycle -*Paulit-ulit na proseso ng pagbuti - gumawa, suriin, tukuyin ang mga isyu, pagbutihin, ulitin* +*Loop ng paulit-ulit na pagpapabuti - gumawa, suriin, tuklasin ang isyu, pagbutihin, ulitin* -**Structured Analysis** - Para sa consistent na pagsusuri. Sine-review ng modelo ang code gamit ang isang fixed na framework (katumpakan, pagsasanay, performance, seguridad, maintainability). Gamitin ito para sa mga code review o pagsusuri ng kalidad. +**Structured Analysis** - Para sa tuloy-tuloy na pagsusuri. Nirereview ng modelo ang code gamit ang isang nakaayos na balangkas (katumpakan, praktis, performance, seguridad, maintainability). Gamitin ito para sa mga review ng code o pagsusuri ng kalidad. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Subukan sa [GitHub Copilot](https://github.com/features/copilot) Chat:** Itanong tungkol sa structured analysis: -> - "Paano ko ma-customize ang analysis framework para sa iba't ibang uri ng code review?" -> - "Ano ang pinakamahusay na paraan para i-parse at gampanan ang structured output programmatically?" -> - "Paano ko matitiyak ang consistent na severity levels sa iba't ibang mga review session?" +> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Magtanong tungkol sa structured analysis: +> - "Paano ko maia-customize ang analysis framework para sa iba't ibang uri ng code review?" +> - "Ano ang pinakamainam na paraan para i-parse at gamitin ang structured output programmatically?" +> - "Paano ko masisiguro ang konsistenteng severity levels sa iba't ibang sesyon ng review?" -Ipinapakita ng sumusunod na diagram kung paano ini-organisa ng structured framework na ito ang code review sa mga konsistenteng kategorya na may severity levels. +Ipinapakita ng sumusunod na diagram kung paano inaayos ng structured framework ang isang review ng code sa pare-parehong mga kategorya na may mga severity level. Structured Analysis Pattern -*Framework para sa konsistenteng code review na may severity levels* +*Balangkas para sa konsistenteng review ng code na may severity levels* -**Multi-Turn Chat** - Para sa mga pag-uusap na nangangailangan ng konteksto. Natatandaan ng modelo ang mga nakaraang mensahe at nililinang ang mga ito. Gamitin ito para sa interactive help sessions o kumplikadong Q&A. +**Multi-Turn Chat** - Para sa mga pag-uusap na nangangailangan ng konteksto. Naaalala ng modelo ang mga naunang mensahe at bumubuo mula doon. Gamitin ito para sa interactive na help session o komplikadong Q&A. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Ipinapakita ng diagram sa ibaba kung paano naiipon ang konteksto ng pag-uusap sa bawat turn at kung paano ito nauugnay sa token limit ng modelo. +Ipinapakita ng diagram sa ibaba kung paano nag-iipon ang konteksto ng pag-uusap sa bawat turn at kung paano ito nauugnay sa token limit ng modelo. Context Memory -*Paano naiipon ang konteksto ng pag-uusap sa maraming turn hanggang maabot ang token limit* -**Step-by-Step Reasoning** - Para sa mga problema na nangangailangan ng malinaw na lohika. Ipinapakita ng modelo ang malinaw na pangangatwiran para sa bawat hakbang. Gamitin ito para sa mga problemang matematika, palaisipan sa lohika, o kapag kailangang maunawaan ang proseso ng pag-iisip. +*Paano nag-iipon ang konteksto ng pag-uusap sa maraming turn hanggang maabot ang token limit* + +**Hakbang-hakbang na Pag-iisip** - Para sa mga problema na nangangailangan ng nakikitang lohika. Ipinapakita ng modelo ang malinaw na pag-iisip para sa bawat hakbang. Gamitin ito para sa mga problema sa math, palaisipan sa lohika, o kapag kailangan mong maunawaan ang proseso ng pag-iisip. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Ang diagram sa ibaba ay nagpapakita kung paano hinahati ng modelo ang mga problema sa malinaw at naka-numero na mga hakbang ng lohika. +Ipinapakita ng diagram sa ibaba kung paano hinahati-hati ng modelo ang mga problema sa malinaw, naka-number na mga hakbang ng lohika. Step-by-Step Pattern +*Paghahati-hati ng mga problema sa malinaw na mga lohikal na hakbang* -*Pag-hati ng mga problema sa malinaw na mga hakbang ng lohika* - -**Constrained Output** - Para sa mga sagot na may tiyak na mga kinakailangan sa format. Mahigpit na sinusunod ng modelo ang mga tuntunin sa format at haba. Gamitin ito para sa mga buod o kapag kailangan ng eksaktong istruktura ng output. +**Limitadong Output** - Para sa mga sagot na may partikular na format na kinakailangan. Mahigpit na sinusunod ng modelo ang mga patakaran sa format at haba. Gamitin ito para sa mga buod o kung kailangan mo ng tiyak na istruktura ng output. ```java String prompt = """ @@ -420,17 +420,17 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Ipinapakita ng sumusunod na diagram kung paano ginagabayan ng mga limitasyon ang modelo upang gumawa ng output na mahigpit na sumusunod sa iyong mga kinakailangan sa format at haba. +Ang sumusunod na diyagram ay nagpapakita kung paano ginagabayan ng mga limitasyon ang modelo upang gumawa ng output na mahigpit na sumusunod sa iyong mga kinakailangan sa format at haba. Constrained Output Pattern -*Pagpapatupad ng mga tiyak na kinakailangan sa format, haba, at istruktura* +*Pagsunod sa mga partikular na format, haba, at mga kinakailangan sa istruktura* ## Patakbuhin ang Aplikasyon **Suriin ang deployment:** -Tiyakin na ang file na `.env` ay nasa root directory kasama ang mga kredensyal ng Azure (nilikha noong Module 01). Patakbuhin ito mula sa direktoryo ng module (`02-prompt-engineering/`): +Tiyaking ang `.env` file ay nasa root directory kasama ang mga kredensyal ng Azure (na ginawa sa Module 01). Patakbuhin ito mula sa directory ng module (`02-prompt-engineering/`): **Bash:** ```bash @@ -444,31 +444,31 @@ Get-Content ..\.env # Dapat ipakita ang AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Simulan ang aplikasyon:** -> **Tala:** Kung sinimulan mo na ang lahat ng aplikasyon gamit ang `./start-all.sh` mula sa root directory (tulad ng inilarawan sa Module 01), tumatakbo na ang module na ito sa port 8083. Maaari mong laktawan ang mga utos ng pagsisimula sa ibaba at direktang pumunta sa http://localhost:8083. +> **Tandaan:** Kung sinimulan mo na ang lahat ng aplikasyon gamit ang `./start-all.sh` mula sa root directory (tulad ng ipinaliwanag sa Module 01), tumatakbo na ang module na ito sa port 8083. Maari mong laktawan ang mga start command sa ibaba at diretso kang pumunta sa http://localhost:8083. **Opsyon 1: Paggamit ng Spring Boot Dashboard (Inirerekomenda para sa mga gumagamit ng VS Code)** -Kasama sa dev container ang Spring Boot Dashboard extension, na nagbibigay ng visual na interface upang pamahalaan ang lahat ng Spring Boot na aplikasyon. Makikita mo ito sa Activity Bar sa kaliwang bahagi ng VS Code (hanapin ang icon ng Spring Boot). +Kasama sa dev container ang Spring Boot Dashboard extension, na nagbibigay ng visual na interface para pamahalaan ang lahat ng Spring Boot applications. Makikita mo ito sa Activity Bar sa kaliwang bahagi ng VS Code (hanapin ang icon ng Spring Boot). Mula sa Spring Boot Dashboard, maaari mong: -- Makita ang lahat ng available na Spring Boot na aplikasyon sa workspace -- Simulan/hintuin ang aplikasyon sa isang click lang -- Tingnan ang mga log ng aplikasyon nang real-time +- Tingnan ang lahat ng available na Spring Boot applications sa workspace +- Simulan/hintuin ang mga aplikasyon sa isang click lang +- Tingnan ang application logs nang real-time - Subaybayan ang status ng aplikasyon -I-click lang ang play button sa tabi ng "prompt-engineering" para simulan ang module na ito, o simulan lahat ng module nang sabay-sabay. +I-click lang ang play button sa tabi ng "prompt-engineering" upang simulan ang module na ito, o simulan lahat ng module nang sabay-sabay. Spring Boot Dashboard -*Ang Spring Boot Dashboard sa VS Code — simulan, hintuin, at subaybayan ang lahat ng module mula sa isang lugar* +*Ang Spring Boot Dashboard sa VS Code — simulan, hintuin, at subaybayan lahat ng module mula sa isang lugar* **Opsyon 2: Paggamit ng shell scripts** -Simulan ang lahat ng web application (modules 01-04): +Simulan lahat ng web applications (modules 01-04): **Bash:** ```bash -cd .. # Mula sa root directory +cd .. # Mula sa direktoryo ng ugat ./start-all.sh ``` @@ -492,16 +492,16 @@ cd 02-prompt-engineering .\start.ps1 ``` -Ang parehong mga script ay awtomatikong naglo-load ng mga environment variable mula sa root `.env` file at magbu-build ng mga JAR kung wala pa ito. +Awtomatikong niloload ng parehong script ang environment variables mula sa root `.env` file at bubuuin ang mga JAR kung wala pa ang mga ito. -> **Tala:** Kung gusto mong manu-manong i-build ang lahat ng module bago simulan: +> **Tandaan:** Kung gusto mong i-build lahat ng module nang mano-mano bago simulan: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - +> > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -510,99 +510,99 @@ Ang parehong mga script ay awtomatikong naglo-load ng mga environment variable m Buksan ang http://localhost:8083 sa iyong browser. -**Para itigil:** +**Para hintuin:** **Bash:** ```bash -./stop.sh # Para sa modulong ito lamang +./stop.sh # Ang modulong ito lamang # O cd .. && ./stop-all.sh # Lahat ng mga module ``` **PowerShell:** ```powershell -.\stop.ps1 # Tanging module na ito lamang +.\stop.ps1 # Para lamang sa module na ito # O -cd ..; .\stop-all.ps1 # Lahat ng module +cd ..; .\stop-all.ps1 # Lahat ng mga module ``` ## Mga Screenshot ng Aplikasyon -Narito ang pangunahing interface ng prompt engineering module, kung saan maaari mong subukan lahat ng walong pattern nang magkatabi. +Narito ang pangunahing interface ng prompt engineering module, kung saan maaari mong subukan ang lahat ng walong pattern nang sabay-sabay. Dashboard Home -*Ang pangunahing dashboard na nagpapakita ng lahat ng 8 prompt engineering pattern kasama ang kanilang mga katangian at gamit* +*Ang pangunahing dashboard na nagpapakita ng lahat ng 8 prompt engineering patterns kasama ang kanilang mga katangian at gamit* -## Pagsusuri sa mga Pattern +## Pagsubok sa mga Pattern -Pinapayagan ka ng web interface na subukan ang iba't ibang estratehiya sa pag-prompt. Bawat pattern ay naglutas ng ibang problema - subukan upang makita kung kailan angkop ang bawat paraan. +Pinapayagan ka ng web interface na mag-eksperimento sa iba't ibang prompting strategies. Bawat pattern ay nagsosolusyon ng iba't ibang problema - subukan ang mga ito upang makita kung kailan pinakamabisa ang bawat pamamaraan. -> **Tala: Streaming vs Non-Streaming** — Bawat pattern page ay may dalawang button: **🔴 Stream Response (Live)** at isang **Non-streaming** na opsyon. Ang streaming ay gumagamit ng Server-Sent Events (SSE) upang ipakita ang mga token nang real-time habang ginagawa ito ng modelo, kaya makikita mo agad ang progreso. Ang non-streaming na opsyon ay naghihintay ng buong sagot bago ito ipakita. Para sa mga prompt na nangangailangan ng malalim na pag-iisip (hal. High Eagerness, Self-Reflecting Code), ang non-streaming call ay maaaring tumagal nang matagal — minsan ay mga minuto — nang walang nakikitang feedback. **Gamitin ang streaming kapag nagsusubok ng mga komplikadong prompt** upang makita kung paano gumagana ang modelo at maiwasan ang impresyon na nag-timeout ang request. +> **Tandaan: Streaming vs Non-Streaming** — Bawat pahina ng pattern ay may dalawang button: **🔴 Stream Response (Live)** at isang **Non-streaming** na opsyon. Ang streaming ay gumagamit ng Server-Sent Events (SSE) upang ipakita ang mga token nang real-time habang ginagawa ng modelo, kaya makikita mo agad ang progreso. Ang non-streaming na opsyon ay naghihintay ng buong sagot bago ipakita ito. Para sa mga prompt na nangangailangan ng malalim na pag-iisip (halimbawa, High Eagerness, Self-Reflecting Code), maaaring tumagal nang matagal ang non-streaming call — minsan ay ilang minuto — nang walang nakikitang feedback. **Gamitin ang streaming kapag nagsusubok sa komplikadong prompt** para makita mong gumagana ang modelo at maiwasan ang impresyong na-timeout ang request. > -> **Tala: Kinakailangan ng Browser** — Ginagamit ng streaming feature ang Fetch Streams API (`response.body.getReader()`) na nangangailangan ng full browser (Chrome, Edge, Firefox, Safari). Hindi ito gumagana sa built-in Simple Browser ng VS Code, dahil hindi sinusuportahan ng webview nito ang ReadableStream API. Kung gagamitin ang Simple Browser, gagana pa rin ang non-streaming buttons nang normal — streaming buttons lang ang maaapektuhan. Buksan ang `http://localhost:8083` sa panlabas na browser para sa buong karanasan. +> **Tandaan: Kinakailangan ng Browser** — Ginagamit ng streaming feature ang Fetch Streams API (`response.body.getReader()`) na nangangailangan ng full browser (Chrome, Edge, Firefox, Safari). Hindi ito gumagana sa built-in Simple Browser ng VS Code, dahil ang webview nito ay hindi sumusuporta sa ReadableStream API. Kung gagamit ka ng Simple Browser, gagana pa rin ang non-streaming buttons nang normal — streaming buttons lang ang hindi. Buksan ang `http://localhost:8083` sa panlabas na browser para sa buong karanasan. -### Low vs High Eagerness +### Mababang vs Mataas na Eagerness -Magtanong ng simpleng tanong tulad ng "What is 15% of 200?" gamit ang Low Eagerness. Makakakuha ka ng agad-agad, direktang sagot. Ngayon magtanong ng komplikado tulad ng "Design a caching strategy for a high-traffic API" gamit ang High Eagerness. I-click ang **🔴 Stream Response (Live)** at panoorin ang detalyadong pangangatwiran ng modelo lumitaw token-by-token. Parehong modelo, parehong estruktura ng tanong - pero sinasabi ng prompt kung gaano kalalim ang pag-iisip. +Magtanong ng simpleng katanungan tulad ng "Ano ang 15% ng 200?" gamit ang Low Eagerness. Agad kang makakakuha ng direktang sagot. Ngayon ay magtanong ng mas kumplikado tulad ng "Disenyo ng caching strategy para sa high-traffic API" gamit ang High Eagerness. I-click ang **🔴 Stream Response (Live)** at panoorin ang detalyadong pag-iisip ng modelo na lumalabas token-by-token. Parehong modelo, parehong estruktura ng tanong - ngunit sinasabi ng prompt kung gaano karaming pag-iisip ang gagawin. -### Pagpapatupad ng Task (Tool Preambles) +### Pagpapaganap ng Gawain (Tool Preambles) -Nakikinabang ang multi-step workflows mula sa maagang pagpaplano at pagsusulat ng progreso. Inilalahad ng modelo kung ano ang gagawin, kinukwento ang bawat hakbang, pagkatapos ay binubuod ang mga resulta. +Ang mga multi-step workflows ay nakikinabang sa maagang pagpaplano at pagsasalaysay ng progreso. Ipinapakita ng modelo kung ano ang gagawin, sinasalaysay ang bawat hakbang, pagkatapos ay pinagsasama-sama ang mga resulta. ### Self-Reflecting Code -Subukan ang "Create an email validation service". Sa halip na gumawa lang ng code at tumigil, gumagawa ang modelo, sinusuri batay sa mga pamantayan ng kalidad, tinutukoy ang kahinaan, at nagpapaayos. Makikita mo itong ulit-ulitin hanggang maabot ang pamantayan para sa produksyon. +Subukan ang "Gumawa ng email validation service". Sa halip na gumawa lang ng code at tumigil, gumagawa ang modelo, sinusuri laban sa mga pamantayan ng kalidad, tinutukoy ang mga kahinaan, at pinapabuti ito. Makikita mong inuulit-ulit ito hanggang matugunan ng code ang mga pamantayan sa produksyon. ### Structured Analysis -Kailangan ng code reviews ng consistent na evaluasyon. Ina-analisa ng modelo ang code gamit ang mga fixed na kategorya (tama, practices, performance, security) at mga antas ng kalubhaan. +Ang pag-review ng code ay nangangailangan ng pare-parehong mga balangkas ng pagsusuri. Sinusuri ng modelo ang code gamit ang mga nakatakdang kategorya (katumpakan, mga gawain, pagganap, seguridad) na may antas ng kaseryosohan. ### Multi-Turn Chat -Magtanong ng "What is Spring Boot?" pagkatapos ay sunod na tanungin kaagad ng "Show me an example". Naaalala ng modelo ang iyong unang tanong at nagbibigay ng halimbawa ng Spring Boot nang partikular. Kung walang memorya, magiging masyadong malabo ang pangalawang tanong. +Magtanong ng "Ano ang Spring Boot?" pagkatapos ay agad na sundan ng "Ipakita sa akin ang isang halimbawa". Tinatandaan ng modelo ang unang tanong mo at nagbibigay ng isang halimbawa ng Spring Boot nang partikular para sa iyo. Kung walang memorya, magiging masyadong malabo ang pangalawang tanong. -### Step-by-Step Reasoning +### Hakbang-hakbang na Pag-iisip -Pumili ng problemang matematika at subukan ito gamit ang Step-by-Step Reasoning at Low Eagerness. Ang low eagerness ay nagbibigay lang ng sagot - mabilis pero hindi maliwanag. Ang step-by-step ay ipinapakita ang bawat kalkulasyon at desisyon. +Pumili ng problema sa matematika at subukan ito gamit ang parehong Step-by-Step Reasoning at Low Eagerness. Ang low eagerness ay nagbibigay lang ng sagot - mabilis pero hindi malinaw. Ang step-by-step ay ipinapakita ang bawat kalkulasyon at desisyon. -### Constrained Output +### Limitadong Output -Kapag kailangan mo ng tiyak na mga format o bilang ng salita, pinatutupad ng pattern na ito ang mahigpit na pagsunod. Subukang gumawa ng buod na eksaktong 100 salita sa bullet point format. +Kapag kailangan mo ng mga partikular na format o bilang ng salita, pinipilit ng pattern na ito ang mahigpit na pagsunod. Subukang gumawa ng buod na eksaktong 100 salita sa format na bullet point. -## Ano ang Talagang Natututunan Mo +## Ano ang Talagang Iyong Natututuhan -**Binabago ng Pagsisikap sa Pangangatwiran ang Lahat** +**Binabago ng Pagsisikap sa Pag-iisip ang Lahat** -Pinapayagan ka ng GPT-5.2 na kontrolin ang computational effort sa pamamagitan ng iyong mga prompt. Ang mababang effort ay nangangahulugang mabilis na sagot na may kaunting pagsisiyasat. Ang mataas na effort ay nangangahulugang maglalaan ng oras ang modelo upang mag-isip nang malalim. Natututo kang iayon ang effort sa kahirapan ng gawain - huwag magaksaya ng oras sa simpleng tanong, pero huwag rin magmadali sa komplikadong desisyon. +Pinapayagan ka ng GPT-5.2 na kontrolin ang pagsisikap sa komputasyon gamit ang iyong mga prompt. Ang mababang pagsisikap ay nangangahulugan ng mabilis na sagot na may minimal na pagsaliksik. Ang mataas na pagsisikap ay nangangahulugan na ginugugol ng modelo ang oras sa malalim na pag-iisip. Natututuhan mong iangkop ang pagsisikap ayon sa kumpleksidad ng gawain - huwag sayangin ang oras sa simpleng tanong, pero huwag din madaliin ang komplikadong desisyon. -**Ang Estruktura ang Gumagabay sa Pag-uugali** +**Pinapatnubayan ng Istruktura ang Pag-uugali** -Napansin mo ba ang mga XML tag sa mga prompt? Hindi sila palamuti lang. Mas maaasahan ang mga modelo kapag sumusunod sa mga istrukturadong tagubilin kaysa sa malayang teksto. Kapag kailangan mo ng mga multi-step na proseso o kumplikadong lohika, nakakatulong ang estruktura upang matunton ng modelo kung nasaan na ito at ano ang susunod. Ang diagram sa ibaba ay nagpapakita ng isang mahusay na naka-istrukturang prompt, kung paano inaayos ng mga tag tulad ng ``, ``, ``, ``, at `` ang iyong mga tagubilin sa mga malinaw na seksyon. +Napansin mo ba ang mga XML tag sa mga prompt? Hindi ito dekorasyon lamang. Mas maaasahan ang pagsunod ng mga modelo sa mga istrukturadong tagubilin kaysa sa malayang teksto. Kapag kailangan mo ng multi-step na proseso o komplikadong lohika, tumutulong ang istruktura sa modelo na malaman kung nasaan ito at ano ang susunod. Ang diyagram sa ibaba ay naghahati ng maayos na istrukturang prompt, na nagpapakita kung paano ang mga tag na ``, ``, ``, ``, at `` ay nag-oorganisa ng iyong mga tagubilin sa malinaw na mga seksyon. Prompt Structure -*Anatomiya ng isang mahusay na naka-istrukturang prompt na may malinaw na mga seksyon at organisasyon na estilo XML* +*Anatomiya ng isang maayos na istrukturang prompt na may malinaw na mga seksyon at organisasyong estilo XML* **Kalidad sa Pamamagitan ng Sariling Pagsusuri** -Gumagana ang mga self-reflecting pattern sa pagpapahayag ng mga pamantayan ng kalidad nang malinaw. Sa halip na umaasa na ang modelo "gagawin ito nang tama", sinasabi mo mismo kung ano ang ibig sabihin ng "tama": tamang lohika, paghawak ng error, performance, security. Pagkatapos, maaaring suriin at pagandahin ng modelo ang sarili nitong output. Ginagawa nitong proseso ang paggawa ng code, hindi suwerteng laro. +Gumagana ang self-reflecting patterns sa pagpapahayag nang malinaw ng mga pamantayan ng kalidad. Sa halip na umaasa na "tama" ang modelo, sinasabi mo nang eksakto kung ano ang ibig sabihin ng "tama": wastong lohika, error handling, pagganap, seguridad. Maaari nang suriin ng modelo ang sariling output at pagbutihin ito. Ginagawa nitong proseso ang paggawa ng code, hindi isang suwerte. -**Limitado ang Context** +**Limitado ang Konteksto** -Ang mga multi-turn conversation ay gumagana sa pamamagitan ng pagsama ng kasaysayan ng mensahe sa bawat request. Pero may limitasyon - bawat modelo ay may maximum na bilang ng token. Habang lumalaki ang pag-uusap, kakailanganin mo ng mga estratehiya upang mapanatili ang mahalagang konteksto nang hindi lumalampas sa limitasyon. Itinuturo sa module na ito kung paano gumagana ang memorya; sa susunod ay matututuhan mo kung kailan magbuod, kailan kalimutan, at kailan kunin muli ang impormasyon. +Ang multi-turn na pag-uusap ay gumagana sa pamamagitan ng pagsama ng kasaysayan ng mensahe sa bawat request. Pero may hangganan - bawat modelo ay may maximum na bilang ng token. Habang lumalaki ang pag-uusap, kakailanganin mo ng mga estratehiya upang panatilihin ang mahalagang konteksto nang hindi naaabot ang limitasyon. Ipinapakita sa module na ito kung paano gumagana ang memorya; sa hinaharap, matututunan mo kung kailan magbubuod, kailan magwawalang-bahala, at kailan kukuha muli. -## Susunod na Mga Hakbang +## Mga Susunod na Hakbang **Susunod na Module:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Navigation:** [← Nakaraan: Module 01 - Introduksyon](../01-introduction/README.md) | [Bumalik sa Pangunahing](../README.md) | [Susunod: Module 03 - RAG →](../03-rag/README.md) +**Pag-navigate:** [← Nakaraan: Module 01 - Panimula](../01-introduction/README.md) | [Bumalik sa Pangunahing](../README.md) | [Susunod: Module 03 - RAG →](../03-rag/README.md) --- -**Paalala**: -Ang dokumentong ito ay isinalin gamit ang AI translation service na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagamat aming pinagsusumikapan ang pagiging tumpak, pakatandaan na ang mga awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o kamalian. Ang orihinal na dokumento sa orihinal na wika nito ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang hindi pagkakaintindihan o maling interpretasyon na maaaring magmula sa paggamit ng pagsasaling ito. +**Pagtatanggi**: +Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kami para sa katumpakan, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang maling pagkakaintindi o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito. \ No newline at end of file diff --git a/translations/tl/03-rag/README.md b/translations/tl/03-rag/README.md index 302be7da7..6b3a93afd 100644 --- a/translations/tl/03-rag/README.md +++ b/translations/tl/03-rag/README.md @@ -2,29 +2,29 @@ ## Table of Contents -- [Video Walkthrough](../../../03-rag) -- [What You'll Learn](../../../03-rag) -- [Prerequisites](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Does This Tutorial Use?](../../../03-rag) -- [How It Works](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload a Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matters](../../../03-rag) -- [Next Steps](../../../03-rag) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding RAG](#understanding-rag) + - [Which RAG Approach Does This Tutorial Use?](#which-rag-approach-does-this-tutorial-use) +- [How It Works](#how-it-works) + - [Document Processing](#document-processing) + - [Creating Embeddings](#creating-embeddings) + - [Semantic Search](#semantic-search) + - [Answer Generation](#paggawa-ng-sagot) +- [Run the Application](#patakbuhin-ang-aplikasyon) +- [Using the Application](#paggamit-ng-aplikasyon) + - [Upload a Document](#mag-upload-ng-dokumento) + - [Ask Questions](#magtanong) + - [Check Source References](#suriin-ang-mga-pinanggalingang-sanggunian) + - [Experiment with Questions](#subukan-ang-ibat-ibang-mga-tanong) +- [Key Concepts](#mga-pangunahing-konsepto) + - [Chunking Strategy](#chunking-strategy) + - [Similarity Scores](#similarity-scores) + - [In-Memory Storage](#in-memory-storage) + - [Context Window Management](#pamamahala-ng-context-window) +- [When RAG Matters](#kailan-mahalaga-ang-rag) +- [Next Steps](#mga-susunod-na-hakbang) ## Video Walkthrough @@ -34,111 +34,110 @@ Panoorin ang live session na ito na nagpapaliwanag kung paano magsimula sa modul ## What You'll Learn -Sa mga naunang mga module, natutunan mo kung paano makipag-usap sa AI at paano mahusay na ayusin ang iyong mga prompt. Ngunit may pangunahing limitasyon: Ang mga language model ay alam lamang ang mga natutunan nila sa panahon ng pagsasanay. Hindi nila kayang sagutin ang mga tanong tungkol sa mga patakaran ng iyong kumpanya, dokumentasyon ng iyong proyekto, o anumang impormasyon na hindi kasama sa kanilang pagsasanay. +Sa mga naunang module, natutunan mo kung paano makipag-usap sa AI at maayos na istraktura ang iyong mga prompt. Ngunit may isang pangunahing limitasyon: ang mga language model ay nalalaman lamang ang kanilang natutunan sa panahon ng pagsasanay. Hindi nila masagot ang mga tanong tungkol sa mga patakaran ng iyong kumpanya, dokumentasyon ng iyong proyekto, o anumang impormasyon na hindi nila na-train. -Nilulutas ng RAG (Retrieval-Augmented Generation) ang problemang ito. Sa halip na subukang turuan ang modelo ng iyong impormasyon (na mahal at hindi praktikal), binibigyan mo ito ng kakayahang maghanap sa iyong mga dokumento. Kapag may nagtatanong, hinahanap ng sistema ang mga kaugnay na impormasyon at isinasama ito sa prompt. Ang modelo ay sasagot base sa nakuha nitong konteksto. +Nilulutas ng RAG (Retrieval-Augmented Generation) ang problemang ito. Sa halip na subukang turuan ang modelo ng iyong mga impormasyon (na mahal at hindi praktikal), binibigyan mo ito ng kakayahang maghanap sa iyong mga dokumento. Kapag may nagtatanong, hinahanap ng sistema ang mga kaugnay na impormasyon at isinama ito sa prompt. Ang modelo ay sumasagot base sa nakuhang kontekstong iyon. -Isipin ang RAG na parang pagbibigay sa modelo ng isang sanggunian na aklatan. Kapag nagtanong ka: +Isipin ang RAG bilang pagbibigay ng isang sangguniang aklatan sa modelo. Kapag may tanong ka, ang sistema ay: -1. **User Query** - Nagbibigay ka ng tanong -2. **Embedding** - Kinokonvert ang tanong mo sa vector -3. **Vector Search** - Hinahanap ang mga kahalintulad na bahagi ng dokumento +1. **User Query** - Nagtanong ka +2. **Embedding** - Kino-convert ang iyong tanong sa vector +3. **Vector Search** - Hinahanap ang mga katulad na bahagi ng dokumento 4. **Context Assembly** - Idinadagdag ang mga kaugnay na bahagi sa prompt -5. **Response** - Gumagawa ang LLM ng sagot base sa konteksto +5. **Response** - Gumagawa ng sagot ang LLM base sa konteksto -Ito ay nagtatakda ng mga sagot ng modelo base sa aktwal mong data sa halip na umasa lamang sa kanyang kaalaman sa pagsasanay o paggawa ng mga sagot. +Ito ay nag-uugat sa mga sagot ng modelo sa iyong tunay na data sa halip na umasa lamang sa kanyang pinag-aralang kaalaman o gumawa ng mga sagot. ## Prerequisites -- Nakumpleto ang [Module 00 - Quick Start](../00-quick-start/README.md) (para sa Easy RAG na halimbawa na binanggit sa kalaunan sa module na ito) -- Nakumpleto ang [Module 01 - Introduction](../01-introduction/README.md) (mga Azure OpenAI resources na na-deploy, kabilang ang `text-embedding-3-small` embedding model) -- `.env` file sa root directory na may Azure credentials (nilikha ng `azd up` sa Module 01) +- Nakumpleto ang [Module 01 - Introduction](../01-introduction/README.md) (nakapag-deploy ng Azure OpenAI resources, kabilang ang `text-embedding-3-small` embedding model) +- `.env` na file sa root directory na may Azure credentials (nilikhang gamit ang `azd up` sa Module 01) -> **Note:** Kung hindi mo pa natatapos ang Module 01, sundin muna ang mga tagubilin sa pag-deploy doon. Ang command na `azd up` ay nagde-deploy ng GPT chat model at embedding model na ginagamit ng module na ito. +> **Note:** Kung hindi mo pa natatapos ang Module 01, sundin muna ang mga tagubilin doon. Ang `azd up` na command ay nagde-deploy ng GPT chat model at embedding model na ginagamit sa module na ito. ## Understanding RAG -Ipinapakita ng diagram sa ibaba ang pangunahing konsepto: sa halip na umasa lamang sa data ng pagsasanay ng modelo, binibigyan ng RAG ito ng isang sangguniang aklatan ng iyong mga dokumento na maaaring tingnan bago bumuo ng bawat sagot. +Ang diagram sa ibaba ay nagpapakita ng pangunahing konsepto: sa halip na umasa lamang sa training data ng modelo, binibigyan ng RAG ito ng isang sangguniang aklatan ng iyong mga dokumento upang tignan bago gumawa ng bawat sagot. What is RAG -*Ipinapakita ng diagram na ito ang pagkakaiba ng isang karaniwang LLM (na humuhula mula sa training data) at isang RAG-enhanced LLM (na kumukonsulta muna sa iyong mga dokumento).* +*Ipinapakita ng diagram na ito ang pinagkaiba ng karaniwang LLM (na naghuhula base sa training data) at ng RAG-enhanced LLM (na kumukunsulta muna sa iyong mga dokumento).* -Ganito ang pagkakaugnay ng mga bahagi mula simula hanggang wakas. Dumadaan ang tanong ng user sa apat na yugto — embedding, vector search, context assembly, at answer generation — bawat isa ay nakasalalay sa naunang hakbang: +Ganito nag-uugnay ang mga bahagi mula simula hanggang katapusan. Ang tanong ng user ay dumadaan sa apat na yugto — embedding, vector search, context assembly, at answer generation — na bawat isa ay umaasa sa naunang hakbang: RAG Architecture -*Ipinapakita ng diagram na ito ang end-to-end na RAG pipeline — dumadaan ang user query sa embedding, vector search, context assembly, at answer generation.* +*Ipinapakita ng diagram na ito ang end-to-end pipeline ng RAG — dumadaan ang tanong ng user sa embedding, vector search, context assembly, at answer generation.* -Ang natitirang bahagi ng module ay naglalakad sa bawat yugto nang detalyado, kasama ang code na pwede mong patakbuhin at i-modify. +Ang natitirang bahagi ng module na ito ay naglalakad sa bawat yugto nang detalyado, kasama ang code na maaari mong patakbuhin at baguhin. ### Which RAG Approach Does This Tutorial Use? -Nag-aalok ang LangChain4j ng tatlong paraan upang ipatupad ang RAG, bawat isa ay may iba't ibang antas ng abstraction. Ikinukumpara sila sa diagram sa ibaba nang magkaharap: +Nag-aalok ang LangChain4j ng tatlong paraan upang ipatupad ang RAG, bawat isa ay may iba't ibang antas ng abstraction. Ang diagram sa ibaba ay inihahambing ang mga ito nang tabi-tabi: Three RAG Approaches in LangChain4j -*Ipinapakita ng diagram na ito ang tatlong LangChain4j RAG na paraan — Easy, Native, at Advanced — na nagpapakita ng kanilang mga pangunahing bahagi at kung kailan gamitin ang bawat isa.* +*Ipinapakita ng diagram na ito ang tatlong RAG approaches ng LangChain4j — Easy, Native, at Advanced — na nagpapakita ng kanilang mga pangunahing bahagi at kung kailan gamitin ang bawat isa.* -| Approach | What It Does | Trade-off | +| Approach | Ano ang Ginagawa Nito | Kapalit | |---|---|---| -| **Easy RAG** | Awtomatikong kinakabit ang lahat sa pamamagitan ng `AiServices` at `ContentRetriever`. Nag-annotate ka lang ng interface, nagdadagdag ng retriever, at ang LangChain4j ang humahandle ng embedding, paghahanap, at pagbuo ng prompt sa likod ng mga eksena. | Minimal na code, ngunit hindi mo nakikita ang nangyayari sa bawat hakbang. | -| **Native RAG** | Tinatawagan mo ang embedding model, naghahanap sa store, binubuo ang prompt, at gumagawa ng sagot ng manu-mano — isa-isang hakbang. | Mas maraming code, ngunit makikita at maima-modify ang bawat yugto. | -| **Advanced RAG** | Ginagamit ang `RetrievalAugmentor` framework na may pluggable query transformers, routers, re-rankers, at content injectors para sa production-grade pipelines. | Pinakamataas na flexibility, ngunit napakakomplikado. | +| **Easy RAG** | Awtomatikong inuugnay ang lahat gamit ang `AiServices` at `ContentRetriever`. Nag-aanotate ka ng isang interface, nag-aattach ng retriever, at ang LangChain4j na ang humahawak sa embedding, paghahanap, at pagpupulong ng prompt sa likod ng eksena. | Minimal na code, pero hindi mo direktang nakikita ang nangyayari sa bawat hakbang. | +| **Native RAG** | Ikaw ang tumatawag ng embedding model, naghahanap sa store, bumubuo ng prompt, at gumagawa ng sagot — isang hakbang kada oras na malinaw. | Mas maraming code, pero bawat yugto ay nakikita at mababago. | +| **Advanced RAG** | Gumagamit ng `RetrievalAugmentor` framework na may pluggable query transformers, routers, re-rankers, at content injectors para sa production-grade pipelines. | Pinakamalawak na flexibility, pero mas komplikado. | -**Ang tutorial na ito ay gumagamit ng Native na paraan.** Isinusulat nang malinaw sa [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) ang bawat hakbang ng RAG pipeline — embedding ng query, paghahanap sa vector store, pagbuo ng konteksto, at pag-generate ng sagot. Ito ay sinadya: bilang isang mapagkukunan sa pag-aaral, mas mahalaga na makita at maunawaan mo ang bawat yugto kaysa paikliin ang code. Kapag komportable ka na sa pag-intindi ng mga bahagi, maaari kang lumipat sa Easy RAG para sa mabilisang prototype o Advanced RAG para sa production systems. +**Ang tutorial na ito ay gumagamit ng Native approach.** Ang bawat hakbang ng RAG pipeline — embedding ng query, paghahanap sa vector store, pagbuo ng konteksto, at pag-generate ng sagot — ay isinulat nang malinaw sa [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Ito ay sinadya: bilang isang learning resource, mas mahalaga na makita at maintindihan mo ang bawat yugto kaysa mapaliit lang ang code. Kapag komportable ka na sa pagkakaugnay ng mga bahagi, maaari kang lumipat sa Easy RAG para sa mabilisang prototypes o sa Advanced RAG para sa mga production system. -> **💡 Naranasan mo na ba ang Easy RAG?** Ang [Quick Start module](../00-quick-start/README.md) ay naglalaman ng Document Q&A na halimbawa ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) na gumagamit ng Easy RAG approach — awtomatikong inaalagaan ng LangChain4j ang embedding, paghahanap, at pagbuo ng prompt. Dinadala ka ng module na ito sa susunod na hakbang sa pamamagitan ng pagbubukas ng pipeline upang makita at kontrolin mo ang bawat yugto. +> **💡 Nais mo bang malaman ang tungkol sa Easy RAG?** Nag-aalok din ang LangChain4j ng *Easy RAG* na paraan kung saan ang `AiServices` at `ContentRetriever` ang humahawak ng embedding, paghahanap, at prompt assembly nang awtomatiko. Ang module na ito ay sumusunod sa mas malinaw na paraan — binubuksan ang pipeline para makita at kontrolin mo ang bawat yugto. -Ipinapakita ng diagram sa ibaba ang Easy RAG pipeline mula sa halimbawa ng Quick Start. Pansinin kung paano itinatago ng `AiServices` at `EmbeddingStoreContentRetriever` ang lahat ng komplikasyon — naglo-load ka ng dokumento, nagdadagdag ng retriever, at nakakakuha ng mga sagot. Binubuksan ng Native na paraan sa module na ito ang mga nakatagong hakbang: +Ang diagram sa ibaba ay nagpapakita ng Easy RAG pipeline. Pansinin kung paano itinatago ng `AiServices` at `EmbeddingStoreContentRetriever` ang lahat ng kahirapan — maglo-load ka ng dokumento, mag-aattach ng retriever, at makakakuha ng sagot. Binubuksan ng Native approach sa module na ito ang bawat hakbang na iyon: Easy RAG Pipeline - LangChain4j -*Ipinapakita ng diagram na ito ang Easy RAG pipeline mula sa `SimpleReaderDemo.java`. Ihambing ito sa Native na paraan na ginagamit sa module na ito: Itinatago ng Easy RAG ang embedding, retrieval, at pagbuo ng prompt sa likod ng `AiServices` at `ContentRetriever` — naglo-load ka ng dokumento, nagdadagdag ng retriever, at nakakakuha ng mga sagot. Binubuksan ng Native na paraan sa module na ito ang pipeline kaya ikaw ang tumatawag sa bawat yugto (embed, search, assemble context, generate), na nagbibigay sa iyo ng buong visibility at kontrol.* +*Ipinapakita ng diagram na ito ang Easy RAG pipeline. Ihambing ito sa Native approach na ginamit sa module na ito: itinatago ng Easy RAG ang embedding, retrieval, at prompt assembly sa likod ng `AiServices` at `ContentRetriever` — naglo-load ka ng dokumento, nag-aattach ng retriever, at nakakakuha ng sagot. Binubuksan ng Native approach ang pipeline para tawagin mo mismo ang bawat hakbang (embed, search, assemble context, generate) nang sarili mo, kaya may buong visibility at kontrol ka.* ## How It Works -Hinahati ng RAG pipeline sa module na ito ang proseso sa apat na yugto na sinusunod sa bawat tanong ng user. Una, ang na-upload na dokumento ay **ini-parse at hinahati** sa mga piraso na madaling hawakan. Ang mga bahagi ay kino-convert naman sa mga **vector embeddings** at iniimbak upang maikumpara ng matematika. Kapag dumating ang isang query, nagsasagawa ang sistema ng **semantic search** upang makita ang pinaka-kaugnay na mga bahagi, at sa wakas ipinapasa ang mga ito bilang konteksto sa LLM para sa **paggawa ng sagot**. Dadalhin tayo ng mga seksyon sa ibaba sa bawat yugto na may aktwal na code at mga diagram. Tingnan natin ang unang hakbang. +Hinahati ang RAG pipeline sa module na ito sa apat na yugto na tumatakbo ng sunud-sunod sa tuwing may nagtatanong. Una, ang ini-upload na dokumento ay **pinoproseso at pinaghahati-hati** sa mga piraso na madaling hawakan. Ang mga pirasong iyon ay kino-convert sa **vector embeddings** at iniimbak para maikumpara nang matematika. Kapag dumating ang tanong, ginagawa ng sistema ang **semantic search** para hanapin ang mga pinaka-kaugnay na piraso, at bilang huli ay ipinapasa ang mga ito bilang konteksto sa LLM para sa **paggawa ng sagot**. Tumingin tayo sa unang hakbang. ### Document Processing [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Kapag nag-upload ka ng dokumento, ini-parse ito ng sistema (PDF o plain text), nilalagyan ng metadata tulad ng filename, at hinahati sa mga chunk — mas maliliit na bahagi na kasya sa context window ng modelo. May bahagyang pagkakapareho ang mga chunks para hindi mawala ang konteksto sa mga hangganan. +Kapag nag-upload ka ng dokumento, pini-parse ito ng sistema (PDF o plain text), nilalagyan ng metadata tulad ng pangalan ng file, at pagkatapos hinahati ito sa mga chunks — mas maliliit na bahagi na pasok nang maayos sa context window ng modelo. Ang mga chunks na ito ay may konting overlap para hindi mawala ang konteksto sa mga hangganan. ```java -// I-parse ang na-upload na file at balutin ito sa isang LangChain4j Document +// Ipaloob ang na-upload na file at balutin ito sa isang LangChain4j Document Document document = Document.from(content, metadata); -// Hatiin sa 300-token na mga bahagi na may 30-token na overlap +// Hatiin sa 300-token na mga bahagi na may 30-token na pagsasapaw DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Ipinapakita ng diagram sa ibaba kung paano ito gumagana sa biswal. Pansinin kung paano nagbabahagi ang bawat chunk ng ilang token sa mga katabing chunk — ang 30-token overlap ay nagsisiguro na walang mahalagang konteksto ang mawawala sa pagitan: +Ipinapakita sa diagram sa ibaba kung paano ito gumagana nang biswal. Pansinin kung paano ang bawat chunk ay may kaunting pinagsasaluhang tokens sa mga kapitbahay niya — ang 30-token overlap ay nagsisigurong walang mahalagang konteksto ang malalampasan: Document Chunking -*Ipinapakita ng diagram na ito ang paghahati ng dokumento sa 300-token chunks na may 30-token overlap, na pinananatili ang konteksto sa hangganan ng mga chunk.* +*Ipinapakita ng diagram na ito kung paanong hinahati ang dokumento sa 300-token chunks na may 30-token overlap, pinapanatili ang konteksto sa mga hangganan ng chunk.* -> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) at itanong: +> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) at magtanong: > - "Paano hinahati ng LangChain4j ang mga dokumento sa chunks at bakit mahalaga ang overlap?" -> - "Ano ang optimal na sukat ng chunk para sa iba’t ibang uri ng dokumento at bakit?" -> - "Paano ko pinoproseso ang mga dokumento na nasa iba’t ibang wika o may espesyal na format?" +> - "Ano ang optimal na laki ng chunk para sa iba't ibang uri ng dokumento at bakit?" +> - "Paano ko hahawakan ang mga dokumento sa maraming wika o may espesyal na pormat?" ### Creating Embeddings [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Ang bawat chunk ay kino-convert sa numerikal na representasyon na tinatawag na embedding — isang kahulugan-sa-numero na tagapag-convert. Hindi “matalino” ang embedding model katulad ng chat model; hindi ito sumusunod ng utos, nagrereason, o sumasagot ng mga tanong. Ang kaya niyang gawin ay i-map ang teksto sa isang matematikal na espasyo kung saan ang mga magkaugnay na kahulugan ay malapit sa isa’t isa — “car” malapit sa “automobile,” “refund policy” malapit sa “return my money.” Isipin ang chat model na isang tao na pwede mong kausapin; ang embedding model ay isang napakagaling na filing system. +Ang bawat chunk ay kino-convert sa isang numerikal na representasyon na tinatawag na embedding — sa madaling salita, isang meaning-to-numbers converter. Hindi "matalino" ang embedding model tulad ng isang chat model; hindi ito sumusunod sa utos, nagre-reason, o sumasagot ng tanong. Ang kaya nito ay i-map ang teksto sa isang matematikal na espasyo kung saan ang magka-kaugnay na kahulugan ay nagtatambak nang malapit sa isa't isa — tulad ng "sasakyan" malapit sa "kotse," "refund policy" malapit sa "ibalik ang pera ko." Isipin ang chat model bilang isang taong pwedeng kausapin; ang embedding model naman ay isang napakagandang filing system. -Ipinapakita ng diagram sa ibaba ang konseptong ito — pumapasok ang teksto, lumalabas ang mga numerikal na vectors, at ang mga magkatulad na kahulugan ay naglalapit sa mga vectors: +Ipinapakita sa diagram sa ibaba ang konseptong ito — pumapasok ang teksto, lumalabas ang mga numerikal na vector, at ang mga magkatulad na kahulugan ay may vectors na malapit sa isa't isa: Embedding Model Concept -*Ipinapakita ng diagram na ito kung paano kino-convert ng embedding model ang teksto sa mga numerikal na vectors, inilalapit ang mga magkakatulad na kahulugan — tulad ng "car" at "automobile" — sa vector space.* +*Ipinapakita ng diagram na ito kung paano kino-convert ng isang embedding model ang teksto sa mga numerikal na vector, inilalapit ang mga katulad na kahulugan — tulad ng "sasakyan" at "kotse" — sa vector space.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Ipinapakita ng class diagram sa ibaba ang dalawang iba’t ibang daloy sa RAG pipeline at ang mga LangChain4j classes na nagpapatupad nito. Ang **ingestion flow** (isang beses kapag na-upload) ay naghahati ng dokumento, nag-e-embed ng chunks, at iniimbak gamit ang `.addAll()`. Ang **query flow** (bawat tanong ng user) ay nag-e-embed ng tanong, naghahanap sa store gamit ang `.search()`, at ipinapasa ang na-match na konteksto sa chat model. Parehong konektado sa shared `EmbeddingStore` interface: +Ipinapakita sa class diagram sa ibaba ang dalawang magkahiwalay na daloy sa RAG pipeline at ang mga LangChain4j classes na nagpapatupad sa mga ito. Ang **ingestion flow** (tumatakbo isang beses pag-upload) ay hinahati ang dokumento, ine-embed ang mga chunks, at iniimbak gamit ang `.addAll()`. Ang **query flow** (tumatakbo kada tanong ng user) ay ine-embed ang tanong, naghahanap sa store gamit ang `.search()`, at ipinapasa ang tugmang konteksto sa chat model. Parehong nagtatagpo ang dalawa sa shared `EmbeddingStore` interface: LangChain4j RAG Classes -*Ipinapakita ng diagram na ito ang dalawang daloy sa RAG pipeline — ingestion at query — at kung paano sila nag-uugnay sa shared na EmbeddingStore.* +*Ipinapakita ng diagram na ito ang dalawang daloy sa RAG pipeline — ingestion at query — at kung paano sila kumokonekta gamit ang shared na EmbeddingStore.* -Kapag naimbak na ang embeddings, natural na nagsasama-sama ang magkaugnay na nilalaman sa vector space. Ipinapakita sa visualization sa ibaba kung paano nagiging malapit sa isa’t isa ang mga dokumento tungkol sa may kaugnay na paksa, na siyang nagpapagana ng semantic search: +Kapag naimbak na ang embeddings, natural na nagsasama-sama ang mga magkakatulad na nilalaman sa vector space. Ipinapakita ng visualization sa ibaba kung paano nagiging malapit sa isa't isa ang mga dokumento tungkol sa magkakaugnay na paksa, na siyang nagpapagana sa semantic search: Vector Embeddings Space -*Ipinapakita ng visualization na ito kung paano nagsasama-sama ang mga magkaugnay na dokumento sa 3D na vector space, kung saan ang mga paksang tulad ng Technical Docs, Business Rules, at FAQs ay bumubuo ng magkakahiwalay na grupo.* +*Ipinapakita ng visualization na ito kung paano nagsasama-sama ang mga related na dokumento sa 3D vector space, na may mga paksa tulad ng Technical Docs, Business Rules, at FAQs na bumubuo ng magkakahiwalay na grupo.* -Kapag naghahanap ang user, sumusunod ang sistema sa apat na hakbang: isang beses na i-embed ang mga dokumento, i-embed ang query sa bawat paghahanap, ikumpara ang query vector sa lahat ng nakaimbak na vectors gamit ang cosine similarity, at ibalik ang top-K na may pinakamataas na iskor na chunks. Pinapakita ng diagram sa ibaba ang bawat hakbang at ang mga LangChain4j classes na sangkot: +Kapag naghahanap ang user, sinusunod ng sistema ang apat na hakbang: i-embed ang mga dokumento nang isang beses, i-embed ang query sa bawat paghahanap, ikumpara ang query vector laban sa lahat ng nakaimbak na vectors gamit ang cosine similarity, at ibalik ang top-K na pinakamataas ang puntos na chunks. Ipinapakita ng diagram sa ibaba ang bawat hakbang at ang mga LangChain4j classes na kasangkot: Embedding Search Steps -*Ipinapakita ng diagram na ito ang apat na hakbang sa embedding search process: embed ng dokumento, embed ng query, ikumpara ang vectors gamit ang cosine similarity, at ibalik ang top-K na resulta.* +*Ipinapakita ng diagram na ito ang apat na hakbang sa embedding search process: i-embed ang mga dokumento, i-embed ang query, ikumpara ang mga vector gamit ang cosine similarity, at ibalik ang top-K na resulta.* ### Semantic Search [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Kapag nagtanong ka, ang tanong mo ay ginagawa ring embedding. Ikinumpara ng sistema ang embedding ng tanong mo sa lahat ng embedding ng mga chunk ng dokumento. Hinahanap nito ang mga chunk na may pinakakahalintulad na kahulugan - hindi lang tugma sa keyword kundi tunay na semantic similarity. +Kapag nagtatanong ka, ang iyong tanong ay na-eembed din. Kinukumpara ng sistema ang embedding ng iyong tanong sa lahat ng embeddings ng mga bahagi ng dokumento. Hinahanap nito ang mga chunks na may pinakakahawig na kahulugan - hindi lang mga salitang tugma, kundi totoong semantic similarity. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Ikinukumpara ng diagram sa ibaba ang semantic search at tradisyonal na keyword search. Ang keyword search para sa "vehicle" ay hindi nakakakuha ng chunk tungkol sa "cars and trucks," pero naiuunawa ng semantic search na pareho ang ibig sabihin at ibinabalik ito bilang mataas ang scoring na tugma: +Ipinapakita ng diagram sa ibaba ang pagkakaiba ng semantic search sa tradisyunal na keyword search. Ang keyword search para sa "vehicle" ay hindi nakakita ng chunk tungkol sa "cars and trucks," ngunit naiintindihan ng semantic search na pareho ang ibig sabihin nito at ibinabalik ito bilang mataas ang puntos na tugma: Semantic Search -*Ipinapakita ng diagram na ito ang pagkumpara ng keyword-based search at semantic search, na nagpapakita kung paano kinukuha ng semantic search ang mga konseptwal na kaugnay na nilalaman kahit iba ang eksaktong keywords.* -Sa ilalim, sinusukat ang pagkakatulad gamit ang cosine similarity — na parang nagtatanong ng "pareho ba ang direksyon ng dalawang palaso?" Maaaring magkaiba ang mga salita sa dalawang bahagi, pero kung pareho ang ibig sabihin, pareho ring nakaturo ang kanilang vectors at malapit sa 1.0 ang iskor: +*Ipinapakita ng diagram na ito ang paghahambing ng keyword-based search at semantic search, na nagpapakita kung paano kinukuha ng semantic search ang mga konseptwal na related na nilalaman kahit na magkaiba ang eksaktong mga keyword.* -Cosine Similarity +Sa likod ng telebisyon, sinusukat ang similarity gamit ang cosine similarity — sa madaling salita, tinatanong kung "pareho ba ang direksyon ng dalawang arrow na ito?" Maaaring magkaiba ng salita ang dalawang chunks, pero kung pareho ang ibig sabihin, pareho ang direksyon ng vectors nila at malapit sa score na 1.0: -*Ipinapakita ng diagram na ito ang cosine similarity bilang anggulo sa pagitan ng embedding vectors — mas magkahanay na vectors ay mas malapit ang iskor sa 1.0, na nagsasaad ng mas mataas na semantic similarity.* +Cosine Similarity +*Ipinapakita ng diagram na ito ang cosine similarity bilang anggulo sa pagitan ng mga embedding vectors — mas magkakatugmang mga vectors ang may score na mas malapit sa 1.0, na nagpapahiwatig ng mas mataas na semantikong pagkakatulad.* > **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) at itanong: -> - "Paano gumagana ang similarity search gamit ang embeddings at ano ang nagtatakda ng iskor?" -> - "Anong similarity threshold ang dapat gamitin at paano ito nakakaapekto sa mga resulta?" -> - "Paano ko haharapin ang mga kaso na walang nahanap na kaugnay na dokumento?" +> - "Paano gumagana ang similarity search gamit ang embeddings at ano ang tumutukoy sa score?" +> - "Anong similarity threshold ang dapat kong gamitin at paano ito nakakaapekto sa mga resulta?" +> - "Paano ko haharapin ang mga kaso kung saan walang nahanap na kaugnay na dokumento?" -### Pagbuo ng Sagot +### Paggawa ng Sagot [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Ang pinakamahalagang mga bahagi ay pinagsasama sa isang istrukturadong prompt na may mga tahasang tagubilin, ang nakuha na konteksto, at ang tanong ng gumagamit. Binabasa ng modelo ang mga espesipikong bahagi na iyon at sumasagot base sa impormasyong iyon — limitado lamang ito sa nakaharap sa kanya, na pumipigil sa hallucination. +Ang pinaka-may-kinalamang mga chunk ay pinagsasama sa isang istrukturadong prompt na kasama ang mga tiyak na tagubilin, ang nakuha na konteksto, at ang tanong ng gumagamit. Binabasa ng modelo ang mga partikular na chunk na iyon at sumasagot base sa impormasyong iyon — maaari lamang nitong gamitin ang nasa harap nito, na nagpigil sa hallucination. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Ipinapakita ng diagram sa ibaba ang pagbuo na ito sa aksyon — ang mga pinakamataas na iskor na chunk mula sa hakbang ng paghahanap ay inilalagay sa template ng prompt, at ang `OpenAiOfficialChatModel` ay bumubuo ng grounded na sagot: +Ipinapakita ng diagram sa ibaba ang pagsasama na ito sa aksyon — ang mga pinakamataas na scoring chunks mula sa hakbang ng paghahanap ay inilalagay sa prompt template, at ang `OpenAiOfficialChatModel` ay bumubuo ng grounded na sagot: Context Assembly -*Ipinapakita ng diagram na ito kung paano pinagsasama ang mga pinakamataas na iskor na chunk sa isang istrukturadong prompt, na nagpapahintulot sa modelo na bumuo ng grounded na sagot mula sa iyong data.* +*Ipinapakita ng diagram na ito kung paano pinagsasama ang mga pinakamataas na scoring chunks sa isang istrukturadong prompt, na nagpapahintulot sa modelo na bumuo ng grounded na sagot mula sa iyong data.* ## Patakbuhin ang Aplikasyon **I-verify ang deployment:** -Tiyaking may `.env` file sa root directory na may Azure credentials (na nilikha sa Module 01). Patakbuhin ito mula sa module directory (`03-rag/`): +Siguraduhing mayroong `.env` file sa root directory na may Azure credentials (na ginawa noong Module 01). Patakbuhin ito mula sa module directory (`03-rag/`): **Bash:** ```bash @@ -261,7 +260,7 @@ Get-Content ..\.env # Dapat ipakita ang AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Simulan ang aplikasyon:** -> **Tandaan:** Kung sinimulan mo na lahat ng aplikasyon gamit ang `./start-all.sh` mula sa root directory (tulad ng inilarawan sa Module 01), tumatakbo na ang module na ito sa port 8081. Maaari mong laktawan ang mga utos sa pagsisimula sa ibaba at pumunta na diretso sa http://localhost:8081. +> **Tandaan:** Kung sinimulan mo na lahat ng aplikasyon gamit ang `./start-all.sh` mula sa root directory (tulad ng inilarawan sa Module 01), ang module na ito ay tumatakbo na sa port 8081. Maaari mong laktawan ang mga start command sa ibaba at pumunta diretso sa http://localhost:8081. **Opsyon 1: Paggamit ng Spring Boot Dashboard (Inirerekomenda para sa mga gumagamit ng VS Code)** @@ -269,29 +268,29 @@ Kasama sa dev container ang Spring Boot Dashboard extension, na nagbibigay ng vi Mula sa Spring Boot Dashboard, maaari mong: - Tingnan lahat ng available na Spring Boot applications sa workspace -- Simulan/ihinto ang mga aplikasyon sa isang click lang -- Tingnan ang mga log ng aplikasyon nang live -- Subaybayan ang estado ng aplikasyon +- Simulan/tigilin ang mga aplikasyon sa isang click lang +- Tingnan ang mga logs ng aplikasyon nang real-time +- I-monitor ang status ng aplikasyon -Pindutin lang ang play button sa tabi ng "rag" para simulan ang module na ito, o simulan lahat ng modules nang sabay-sabay. +I-click lang ang play button sa tabi ng "rag" para simulan ang module na ito, o simulan ang lahat ng module nang sabay-sabay. Spring Boot Dashboard -*Ipinapakita ng screenshot na ito ang Spring Boot Dashboard sa VS Code, kung saan maaari mong simulan, ihinto, at subaybayan ang mga aplikasyon nang visual.* +*Ipinapakita ng screenshot na ito ang Spring Boot Dashboard sa VS Code, kung saan maaari mong simulan, itigil, at i-monitor ang mga aplikasyon nang visual.* **Opsyon 2: Paggamit ng shell scripts** -Simulan lahat ng web applications (modules 01-04): +Simulan lahat ng web applications (module 01-04): **Bash:** ```bash -cd .. # Mula sa root na direktoryo +cd .. # Mula sa root directory ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Mula sa root directory +cd .. # Mula sa ugat na direktoryo .\start-all.ps1 ``` @@ -309,7 +308,7 @@ cd 03-rag .\start.ps1 ``` -Awtomatikong niloload ng parehong script ang mga environment variables mula sa root `.env` file at bubuuin ang mga JAR kung wala pa. +Awtomatikong niloload ng parehong scripts ang mga environment variables mula sa root `.env` file at bubuuin ang mga JAR kung wala pa ito. > **Tandaan:** Kung nais mong manu-manong buuin ang lahat ng modules bago simulan: > @@ -331,14 +330,14 @@ Buksan ang http://localhost:8081 sa iyong browser. **Bash:** ```bash -./stop.sh # Sa module na ito lang +./stop.sh # Para lamang sa module na ito # O cd .. && ./stop-all.sh # Lahat ng mga module ``` **PowerShell:** ```powershell -.\stop.ps1 # Module na ito lamang +.\stop.ps1 # Para lamang sa module na ito # O cd ..; .\stop-all.ps1 # Lahat ng mga module ``` @@ -349,89 +348,89 @@ Nagbibigay ang aplikasyon ng web interface para sa pag-upload ng dokumento at pa RAG Application Interface -*Ipinapakita ng screenshot na ito ang interface ng RAG application kung saan nag-a-upload ka ng mga dokumento at nagtatanong.* +*Ipinapakita ng screenshot na ito ang interface ng RAG application kung saan ka nag-u-upload ng mga dokumento at nagtatanong.* ### Mag-upload ng Dokumento -Magsimula sa pag-upload ng dokumento - mas mainam ang mga TXT files para sa pagsubok. Mayroong `sample-document.txt` sa direktoryong ito na naglalaman ng impormasyon tungkol sa mga tampok ng LangChain4j, implementasyon ng RAG, at mga best practices - perpekto para sa pagsubok ng sistema. +Magsimula sa pag-upload ng dokumento - mas mainam ang mga TXT file para sa testing. Mayroong `sample-document.txt` sa direktoryong ito na naglalaman ng impormasyon tungkol sa mga tampok ng LangChain4j, implementasyon ng RAG, at mga best practices - perpekto para sa pagsusuri ng sistema. -Pinoproseso ng sistema ang iyong dokumento, hinahati ito sa mga bahagi, at lumilikha ng embeddings para sa bawat bahagi. Nangyayari ito nang awtomatiko kapag nag-upload ka. +Pinoproseso ng sistema ang iyong dokumento, hinahati ito sa mga chunk, at lumilikha ng embeddings para sa bawat chunk. Nangyayari ito nang awtomatiko kapag nag-upload ka. ### Magtanong -Ngayon magtanong ng espesipikong mga tanong tungkol sa nilalaman ng dokumento. Subukan ang mga fact-based na tanong na malinaw na nakasaad sa dokumento. Hinahanap ng sistema ang mga kaugnay na bahagi, isinama ang mga ito sa prompt, at bumubuo ng sagot. +Ngayon, magtanong ng mga tiyak na tanong tungkol sa nilalaman ng dokumento. Subukan ang mga fact-based na tanong na malinaw na nakasaad sa dokumento. Hinahanap ng sistema ang may-kaugnayang mga chunk, isinama ito sa prompt, at bumubuo ng sagot. -### Suriin ang Mga Sanggunian +### Suriin ang Mga Pinanggalingang Sanggunian -Pansinin na bawat sagot ay may mga sanggunian na may kasamang similarity scores. Ipinapakita ng mga iskor na ito (mula 0 hanggang 1) kung gaano kahalaga ang bawat bahagi sa iyong tanong. Mas mataas na iskor ang ibig sabihin ay mas angkop na tugma. Pinahihintulutan kang suriin ang sagot laban sa pinagmulan. +Mapapansin bawat sagot ay may kasamang sanggunian ng pinanggalingan na may mga similarity score. Ipinapakita ng mga score na ito (mula 0 hanggang 1) kung gaano kaugnay ang bawat chunk sa iyong tanong. Mas mataas na score ang ibig sabihin ay mas maganda ang tugma. Pinapayagan ka nitong i-verify ang sagot laban sa orihinal na materyal. RAG Query Results -*Ipinapakita ng screenshot na ito ang mga resulta ng query kasama ang binuong sagot, mga sanggunian ng pinagmulan, at mga iskor ng kaugnayan para sa bawat nabuong bahagi.* +*Ipinapakita ng screenshot na ito ang mga resulta ng query kasama ng nabuo na sagot, mga source references, at relevance scores para sa bawat nakuha na chunk.* -### Mag-eksperimento sa mga Tanong +### Subukan ang Iba't Ibang Mga Tanong -Subukan ang iba't ibang uri ng mga tanong: -- Espesipikong mga katotohanan: "Ano ang pangunahing paksa?" -- Pagkukumpara: "Ano ang pagkakaiba ng X at Y?" -- Mga buod: "Buodin ang mga pangunahing punto tungkol sa Z" +Subukan ang iba't ibang uri ng tanong: +- Tiyak na fakta: "Ano ang pangunahing paksa?" +- Paghahambing: "Ano ang pagkakaiba ng X at Y?" +- Buod: "Buodin ang mga pangunahing punto tungkol sa Z" -Panoorin kung paano nagbabago ang mga iskor ng kaugnayan batay sa kung gaano kahusay ang pagtutugma ng tanong mo sa nilalaman ng dokumento. +Pansinin kung paano nagbabago ang relevance scores base sa kung gaano ka-akma ang tanong mo sa nilalaman ng dokumento. ## Mga Pangunahing Konsepto -### Estratehiya sa Pagchunk +### Chunking Strategy -Hinahati ang mga dokumento sa 300-token na mga bahagi na may 30 tokens na overlap. Tinitiyak ng balanse na ito na bawat bahagi ay may sapat na konteksto upang maging makahulugan habang nananatiling maliit upang maisama ang maraming bahagi sa isang prompt. +Hinahati ang mga dokumento sa mga 300-token na chunk na may 30 token na overlap. Ang balanse na ito ay nagsisiguro na bawat chunk ay may sapat na konteksto para maging makahulugan habang nananatiling maliit upang maisama ang maraming chunk sa isang prompt. -### Mga Iskor ng Pagkakatulad +### Similarity Scores -Bawat nakuha na bahagi ay may iskor ng similarity mula 0 hanggang 1 na nagsasaad kung gaano ito kalapit sa tanong ng gumagamit. Ipinapakita ng diagram sa ibaba ang mga saklaw ng iskor at kung paano ginagamit ng sistema ang mga ito para salain ang mga resulta: +Bawat nakuha na chunk ay may kasamang similarity score mula 0 hanggang 1 na nagpapakita kung gaano kalapit ang tugma nito sa tanong ng gumagamit. Ipinapakita ng diagram sa ibaba ang mga saklaw ng score at kung paano ito ginagamit ng sistema para i-filter ang mga resulta: Similarity Scores -*Ipinapakita ng diagram na ito ang mga saklaw ng iskor mula 0 hanggang 1, na may minimum threshold na 0.5 na nagsasala ng mga hindi kaugnay na bahagi.* +*Ipinapakita ng diagram na ito ang mga saklaw ng score mula 0 hanggang 1, na may minimum threshold na 0.5 na nagfi-filter ng mga hindi kaugnay na chunk.* -Ang mga iskor ay nasa pagitan ng 0 hanggang 1: -- 0.7-1.0: Lubos na kaugnay, eksaktong tugma +Ang mga score ay nasa saklaw ng 0 hanggang 1: +- 0.7-1.0: Lubhang kaugnay, eksaktong tugma - 0.5-0.7: Kaugnay, magandang konteksto -- Mas mababa sa 0.5: Isinala, masyadong hindi magkatulad +- Mas mababa sa 0.5: Na-filter, masyadong hindi magkakatulad -Kinukuha ng sistema ang mga bahagi na lampas sa minimum threshold para matiyak ang kalidad. +Tumutukoy lamang ang sistema ng mga chunk na lampas sa minimum threshold upang matiyak ang kalidad. -Maganda ang embeddings kapag malinaw ang pagklaster ng kahulugan, ngunit may mga blind spots ito. Ipinapakita ng diagram sa ibaba ang mga karaniwang pagkukulang — ang mga sobrang laki na bahagi ay gumagawa ng malabong vectors, ang mga sobrang maliit na bahagi ay kulang sa konteksto, ang mga malabo na termino ay tumuturo sa maraming klaster, at ang eksaktong-match na mga lookup (IDs, part numbers) ay hindi gumagana sa embeddings: +Maganda ang embeddings kapag mahusay na nako-cluster ang kahulugan, ngunit mayroon silang mga bulag na punto. Ipinapakita ng diagram sa ibaba ang mga karaniwang pagkabigo — ang mga masyadong malalaking chunk ay gumagawa ng malabong vectors, ang mga masyadong maliit na chunk ay kulang sa konteksto, ang mga malabong termino ay tumutukoy sa maraming cluster, at ang eksaktong tugma na paghahanap (IDs, mga part number) ay hindi gumagana gamit ang embeddings: Embedding Failure Modes -*Ipinapakita ng diagram na ito ang mga karaniwang problema sa embedding: sobrang laki o sobrang maliit na bahagi, malabong termino na tumuturo sa maraming klaster, at eksaktong-match na mga lookup tulad ng mga ID.* +*Ipinapakita ng diagram na ito ang mga karaniwang failure mode ng embedding: masyadong malalaking chunk, masyadong maliit na chunk, mga malabong termino na tumutukoy sa maraming cluster, at eksaktong paghahanap tulad ng mga ID.* -### Imbakan sa Memorya +### In-Memory Storage -Gumagamit ang module na ito ng pag-imbak sa memorya para sa pagiging simple. Kapag nirestart mo ang aplikasyon, mawawala ang mga na-upload na dokumento. Sa produksyon, gumagamit ang mga sistema ng persistent vector databases tulad ng Qdrant o Azure AI Search. +Gumagamit ang module na ito ng in-memory storage para sa pagiging simple. Kapag nirestart mo ang application, mawawala ang mga na-upload na dokumento. Ang mga production system ay gumagamit ng persistent vector databases tulad ng Qdrant o Azure AI Search. -### Pamamahala ng Window ng Konteksto +### Pamamahala ng Context Window -Bawat modelo ay may maximum na context window. Hindi mo maaaring isama lahat ng bahagi mula sa isang malaking dokumento. Kinukuha ng sistema ang nangungunang N pinakakaugnay na mga bahagi (default ay 5) upang manatili sa loob ng limitasyon habang nagbibigay ng sapat na konteksto para sa tamang mga sagot. +Bawat modelo ay may maximum na context window. Hindi mo maaaring isama lahat ng chunk mula sa isang malaking dokumento. Kinukuha ng sistema ang top N na pinaka-kaugnay na chunk (default 5) upang manatili sa loob ng mga limitasyon habang nagbibigay ng sapat na konteksto para sa tamang mga sagot. ## Kailan Mahalaga ang RAG -Hindi palaging angkop ang RAG. Ang gabay sa pagpapasya sa ibaba ay tumutulong sa pagtukoy kung kailan nagbibigay halaga ang RAG kumpara sa mga mas simpleng pamamaraan — tulad ng pagsama ng nilalaman nang direkta sa prompt o pag-asa sa built-in na kaalaman ng modelo: +Hindi palaging tamang paraan ang RAG. Ang gabay sa desisyon sa ibaba ay tumutulong sa iyo upang matukoy kung kailan nagbibigay ng halaga ang RAG kumpara sa mga mas simpleng paraan — tulad ng direktang pagsama ng nilalaman sa prompt o pag-asa sa built-in na kaalaman ng modelo: When to Use RAG -*Ipinapakita ng diagram na ito ang gabay sa pagpapasya kung kailan nagbibigay halaga ang RAG kumpara sa mga simpler na pamamaraan.* +*Ipinapakita ng diagram na ito ang gabay sa desisyon kung kailan nagbibigay ng halaga ang RAG kumpara sa mga mas simpleng paraan na sapat na.* -## Susunod na Hakbang +## Mga Susunod na Hakbang **Susunod na Module:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**Navigation:** [← Nakaraan: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Bumalik sa Pangunahing Pahina](../README.md) | [Susunod: Module 04 - Tools →](../04-tools/README.md) +**Navigation:** [← Nakaraan: Module 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [Bumalik sa Main](../README.md) | [Susunod: Module 04 - Tools →](../04-tools/README.md) --- -**Paunawa**: -Ang dokumentong ito ay isinalin gamit ang AI translation service na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kami para sa katumpakan, mangyaring tandaan na ang mga awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasaling-tao. Hindi kami mananagot sa anumang hindi pagkakaintindihan o maling pag-unawa na bunga ng paggamit ng pagsasaling ito. +**Pagtatanggi**: +Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kami para sa katumpakan, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang maling pagkakaintindi o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito. \ No newline at end of file diff --git a/translations/tl/04-tools/README.md b/translations/tl/04-tools/README.md index 7eae54a74..8d9bd3a70 100644 --- a/translations/tl/04-tools/README.md +++ b/translations/tl/04-tools/README.md @@ -2,75 +2,75 @@ ## Table of Contents -- [Video Walkthrough](../../../04-tools) -- [What You'll Learn](../../../04-tools) -- [Prerequisites](../../../04-tools) -- [Understanding AI Agents with Tools](../../../04-tools) -- [How Tool Calling Works](../../../04-tools) - - [Tool Definitions](../../../04-tools) - - [Decision Making](../../../04-tools) - - [Execution](../../../04-tools) - - [Response Generation](../../../04-tools) - - [Architecture: Spring Boot Auto-Wiring](../../../04-tools) -- [Tool Chaining](../../../04-tools) -- [Run the Application](../../../04-tools) -- [Using the Application](../../../04-tools) - - [Try Simple Tool Usage](../../../04-tools) - - [Test Tool Chaining](../../../04-tools) - - [See Conversation Flow](../../../04-tools) - - [Experiment with Different Requests](../../../04-tools) -- [Key Concepts](../../../04-tools) - - [ReAct Pattern (Reasoning and Acting)](../../../04-tools) - - [Tool Descriptions Matter](../../../04-tools) - - [Session Management](../../../04-tools) - - [Error Handling](../../../04-tools) -- [Available Tools](../../../04-tools) -- [When to Use Tool-Based Agents](../../../04-tools) -- [Tools vs RAG](../../../04-tools) -- [Next Steps](../../../04-tools) +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding AI Agents with Tools](#understanding-ai-agents-with-tools) +- [How Tool Calling Works](#how-tool-calling-works) + - [Tool Definitions](#tool-definitions) + - [Decision Making](#decision-making) + - [Execution](#execution) + - [Response Generation](#response-generation) + - [Architecture: Spring Boot Auto-Wiring](#architecture-spring-boot-auto-wiring) +- [Tool Chaining](#tool-chaining) +- [Run the Application](#run-the-application) +- [Using the Application](#paggamit-ng-application) + - [Try Simple Tool Usage](#subukan-ang-simpleng-paggamit-ng-tools) + - [Test Tool Chaining](#subukan-ang-pagsasunud-sunod-ng-tools) + - [See Conversation Flow](#tingnan-ang-daloy-ng-usapan) + - [Experiment with Different Requests](#eksperimento-sa-ibat-ibang-kahilingan) +- [Key Concepts](#mga-pangunahing-konsepto) + - [ReAct Pattern (Reasoning and Acting)](#react-pattern-pagrason-at-pag-aksyon) + - [Tool Descriptions Matter](#mahalaga-ang-mga-deskripsyon-ng-tool) + - [Session Management](#pamamahala-ng-session) + - [Error Handling](#pag-handle-ng-error) +- [Available Tools](#mga-available-na-tool) +- [When to Use Tool-Based Agents](#kailan-gamitin-ang-mga-tool-based-na-agents) +- [Tools vs RAG](#tools-vs-rag) +- [Next Steps](#mga-susunod-na-hakbang) ## Video Walkthrough -Panoorin ang live session na nagpapaliwanag kung paano magsimula gamit ang module na ito: +Panoorin ang live session na ito na nagpapaliwanag kung paano magsimula gamit ang module na ito: AI Agents with Tools and MCP - Live Session ## What You'll Learn -Sa ngayon, natutunan mo kung paano makipag-usap sa AI, epektibong istraktura ng mga prompt, at ipundar ang mga tugon sa iyong mga dokumento. Ngunit may isang pangunahing limitasyon pa rin: ang mga language model ay makakalikha lang ng teksto. Hindi nila kayang suriin ang panahon, magsagawa ng mga kalkulasyon, mag-query ng mga database, o makipag-ugnayan sa mga panlabas na sistema. +Hanggang ngayon, natutunan mo kung paano makipag-usap sa AI, ayusin nang maayos ang mga prompt, at gawing basehan ang iyong mga dokumento sa mga sagot. Ngunit may pangunahing limitasyon pa rin: ang mga language model ay kaya lamang gumawa ng teksto. Hindi nila kayang mag-check ng panahon, magsagawa ng mga kalkulasyon, mag-query sa mga database, o makipag-ugnayan sa mga panlabas na sistema. -Binabago ito ng mga tool. Sa pagbibigay ng access sa mga function na maaaring tawagin ng modelo, ginagawa mo itong mula sa simpleng tagalikha ng teksto na maging isang agent na makakagawa ng mga aksyon. Nagpapasiya ang modelo kung kailan kailangan nito ng isang tool, aling tool ang gagamitin, at anong mga parameter ang ipapasa. Ang iyong code ang magsasagawa ng function at ibabalik ang resulta. Kasama ng modelo ang resulta sa kanyang tugon. +Binabago ito ng mga Tools. Sa pagbibigay ng access sa modelo sa mga function na maaari nitong tawagan, napapalitan mo ito mula sa pagiging tagalikha ng teksto tungo sa pagiging isang agent na kayang gumawa ng mga aksyon. Ang modelo ang nagpapasya kung kailan kailangan nito ng tool, alin ang gagamitin, at kung anong mga parameter ang ipapasa. Isinasagawa ng iyong code ang function at ibinabalik ang resulta. Isinasama ng modelo ang resulta sa kanyang tugon. ## Prerequisites -- Nakatapos ng [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI resources na na-deploy) -- Rekomendadong nakatapos na ang mga naunang module (ang module na ito ay tumutukoy sa [RAG concepts mula sa Module 03](../03-rag/README.md) sa paghahambing ng Tools vs RAG) +- Nakumpleto ang [Module 01 - Introduction](../01-introduction/README.md) (na-deploy ang Azure OpenAI resources) +- Nakumpleto ang mga naunang module na inirerekomenda (ang module na ito ay nagre-refer sa [mga konsepto ng RAG mula sa Module 03](../03-rag/README.md) sa paghahambing ng Tools vs RAG) - `.env` file sa root directory na may Azure credentials (nilikha gamit ang `azd up` sa Module 01) -> **Note:** Kung hindi mo pa natatapos ang Module 01, sundin muna ang mga instruksyon doon sa deployment. +> **Note:** Kung hindi mo pa natatapos ang Module 01, sundin muna ang mga tagubilin doon para sa deployment. ## Understanding AI Agents with Tools -> **📝 Note:** Ang terminong "agents" sa module na ito ay tumutukoy sa mga AI assistant na pinalakas ng mga kakayahan sa pagtawag ng tool. Iba ito sa mga **Agentic AI** pattern (autonomous agents na may planning, memory, at multi-step reasoning) na tatalakayin natin sa [Module 05: MCP](../05-mcp/README.md). +> **📝 Note:** Ang salitang "agents" sa module na ito ay tumutukoy sa mga AI assistants na pinalakas ng kakayahang tumawag ng mga tool. Iba ito sa mga **Agentic AI** patterns (autonomous agents na may planning, memory, at multi-step reasoning) na tatalakayin sa [Module 05: MCP](../05-mcp/README.md). -Kung walang tools, ang isang language model ay makakalikha lang ng teksto mula sa kanyang training data. Tanungin ito tungkol sa kasalukuyang panahon, at manghuhula lang ito. Bigyan ito ng mga tool, at kaya nitong tumawag ng weather API, magsagawa ng kalkulasyon, o mag-query ng database — at pagkatapos ay isasama ang mga totoong resulta sa kanyang tugon. +Kung walang tools, ang language model ay kaya lamang gumawa ng teksto mula sa pinag-aralang datos. Kapag tinanong mo ito tungkol sa kasalukuyang panahon, huhulaan lang nito. Kung bibigyan mo ito ng mga tools, kaya nitong tumawag ng isang weather API, magsagawa ng mga kalkulasyon, o mag-query ng database — tapos ihalo ang mga totoong resulta sa kanyang sagot. Without Tools vs With Tools -*Kung walang tools, ang modelo ay nanghuhula lang — sa tulong ng mga tool, kaya nitong tumawag ng mga API, magpatakbo ng kalkulasyon, at magbigay ng data sa totoong oras.* +*Kapag walang tools, huhulaan lang ng modelo — kung may tools, kaya nitong tumawag ng APIs, magsagawa ng kalkulasyon, at magbalik ng real-time na datos.* -Ang AI agent na may tools ay sumusunod sa **Reasoning and Acting (ReAct)** na pattern. Hindi lang basta sumasagot ang modelo — pinag-iisipan nito ang kailangan nito, kumikilos sa pamamagitan ng pagtawag ng tool, pinagmamasdan ang resulta, at nagpapasya kung uulit pa o magbibigay ng huling sagot: +Ang isang AI agent na may tools ay sumusunod sa **Reasoning and Acting (ReAct)** pattern. Hindi lang basta sumasagot ang modelo — iniisip nito kung ano ang kailangan, kumikilos sa pamamagitan ng pagtawag ng tool, sinusuri ang resulta, at pagkatapos ay nagpapasya kung uulitin ang aksyon o ibibigay ang panghuling sagot: 1. **Reason** — Sinusuri ng agent ang tanong ng user at tinutukoy kung anong impormasyon ang kailangan nito -2. **Act** — Pinipili ng agent ang tamang tool, bumubuo ng tamang mga parameter, at tinatawagan ito -3. **Observe** — Natatanggap ng agent ang output ng tool at sinusuri ang resulta -4. **Repeat or Respond** — Kung kailangan pa ng dagdag na data, umaulit ang agent; kung hindi, bumubuo ng natural na wika na sagot +2. **Act** — Pinipili ng agent ang tamang tool, ginagawa ang wastong mga parameter, at tinatawagan ito +3. **Observe** — Tinatanggap ng agent ang output ng tool at sinusuri ang resulta +4. **Repeat or Respond** — Kung kailangan pa ng karagdagang data, uulit ang cycle; kung hindi, bumubuo ng sagot sa natural na wika ReAct Pattern -*Ang ReAct cycle — pinaplanuhan ng agent kung ano ang gagawin, kumikilos sa pagtawag ng tool, pinagmamasdan ang resulta, at inuulit hanggang makapagbigay ng huling sagot.* +*Ang siklo ng ReAct — iniisip ng agent kung ano ang gagawin, kumikilos sa pamamagitan ng pagtawag ng tool, sinusuri ang resulta, at inuulit hanggang maibigay ang panghuling sagot.* -Ito ay nangyayari nang awtomatiko. Idefine mo ang mga tools at ang kanilang mga paglalarawan. Ang modelo ang humahawak sa pagpapasya kung kailan at paano ito gagamitin. +Nangyayari ito nang awtomatiko. Ikaw ang nagdedeklara ng mga tool at ang kanilang mga paglalarawan. Ang modelo ang humahawak ng pagpapasya kung kailan at paano ito gagamitin. ## How Tool Calling Works @@ -78,7 +78,7 @@ Ito ay nangyayari nang awtomatiko. Idefine mo ang mga tools at ang kanilang mga [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Nagbibigay ka ng mga function na may malinaw na paglalarawan at espesipikasyon ng mga parameter. Nakikita ng modelo ang mga paglalarawang ito sa system prompt nito at nauunawaan kung ano ang ginagawa ng bawat tool. +Nagdedeklara ka ng mga function na may malinaw na paglalarawan at pagtukoy sa mga parameter. Nakikita ng modelo ang mga paglalarawang ito sa prompt ng sistema at nauunawaan kung ano ang ginagawa ng bawat tool. ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // Ang iyong lohika para sa paghahanap ng panahon + // Ang iyong lohika sa paghahanap ng panahon return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Awtomatikong naka-wire ang Assistant ng Spring Boot gamit ang: +// Awtomatikong nakakabit ang Assistant sa pamamagitan ng Spring Boot gamit ang: // - ChatModel bean -// - Lahat ng @Tool na mga metodo mula sa mga klase na may @Component -// - ChatMemoryProvider para sa pamamahala ng sesyon +// - Lahat ng @Tool na mga metodo mula sa mga @Component na klase +// - ChatMemoryProvider para sa pamamahala ng session ``` -Ang diagram sa ibaba ay nagpapakita ng bawat anotasyon at kung paano tinutulungan ng bawat bahagi ang AI na maintindihan kung kailan tatawagin ang tool at anong mga argumento ang ipapasa: +Pinaghiwa-hiwalay ng diagram sa ibaba ang bawat anotasyon at ipinapakita kung paano tinutulungan ng bawat bahagi ang AI na maunawaan kung kailan tatawagin ang tool at anong mga argumento ang ipapasa: Anatomy of Tool Definitions -*Anatomiya ng isang definition ng tool — sinasabi ng @Tool sa AI kung kailan ito gagamitin, inilarawan ng @P ang bawat parameter, at ang @AiService ang nagsasama ng lahat sa pagsisimula.* +*Anatomiya ng isang tool definition — sinasabi ng @Tool sa AI kung kailan gagamitin ito, inilalarawan ng @P ang bawat parameter, at pinag-uugnay ng @AiService ang lahat sa pagsisimula.* -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) at itanong: -> - "Paano ko i-integrate ang totoong weather API tulad ng OpenWeatherMap sa halip na mock data?" -> - "Ano ang bumubuo ng mahusay na paglalarawan ng tool na tumutulong sa AI na gamitin ito nang tama?" -> - "Paano ko haharapin ang mga error sa API at mga rate limit sa implementasyon ng mga tool?" +> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) at itanong: +> - "Paano ko isasama ang totoong weather API tulad ng OpenWeatherMap sa halip na mock data?" +> - "Ano ang mga katangian ng magandang paglalarawan ng tool na tumutulong sa AI na gamitin ito nang tama?" +> - "Paano ko haharapin ang mga error sa API at mga rate limit sa mga implementasyon ng tool?" ### Decision Making -Kapag nagtanong ang user ng "Ano ang panahon sa Seattle?", hindi basta random na pumipili ang modelo ng tool. Kinukumpara nito ang intensyon ng user sa bawat paglalarawan ng tool na mayroon ito, binibigay ng marka ang bawat isa base sa kaugnayan, at pinipili ang pinaka-akmang tugma. Pagkatapos ay bumubuo ito ng istrukturadong pagtawag ng function na may tamang mga parameter — sa kasong ito, itinatakda ang `location` sa `"Seattle"`. +Kapag tinanong ng user na "Ano ang lagay ng panahon sa Seattle?", hindi basta pumipili ng tool ang modelo nang random. Kinukumpara nito ang layunin ng user sa bawat paglalarawan ng tool na mayroon ito, binibilang ang kahalagahan ng bawat isa, at pinipili ang pinakamainam. Gumagawa ito ng istrakturadong tawag sa function na may tamang mga parameter — sa kasong ito, itinakda ang `location` sa `"Seattle"`. -Kung walang tool na tumutugma sa kahilingan ng user, bumabalik ang modelo sa pagsagot mula sa sariling kaalaman nito. Kung maraming tool ang tumutugma, pinipili nito ang pinaka-tukoy. +Kung walang tumutugmang tool sa kahilingan ng user, bumabalik ang modelo sa pagsagot mula sa sariling kaalaman. Kung maraming tool ang tumutugma, pinipili nito ang pinaka-tiyak. How the AI Decides Which Tool to Use -*Pinag-aaralan ng modelo ang bawat magagamit na tool laban sa intensyon ng user at pinipili ang pinakamahusay — kaya mahalaga ang pagsulat ng malinaw, tiyak na mga paglalarawan ng tool.* +*Sinusuri ng modelo ang bawat tool laban sa layunin ng user at pinipili ang pinakamainam — kaya mahalaga ang pagsulat ng malinaw at tiyak na mga paglalarawan ng tool.* ### Execution [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Awtomatikong ina-wire ng Spring Boot ang deklaratibong `@AiService` interface sa lahat ng naka-rehistrong tool, at awtomatikong isinasagawa ng LangChain4j ang pagtawag ng mga tool. Sa likod ng eksena, dumadaan ang isang kompletong pagtawag ng tool sa anim na yugto — mula sa likas na tanong ng user pabalik sa likas na sagot: +Ang Spring Boot ay awtomatikong nag-a-wire sa declarative `@AiService` interface na may lahat ng nairehistrong mga tool, at awtomatikong isinasagawa ng LangChain4j ang mga tawag sa tool. Sa likod ng eksena, dumadaloy ang isang buong tawag sa tool sa anim na yugto — mula sa tanong ng user sa natural na wika hanggang sa sagot sa natural na wika: Tool Calling Flow -*Ang buo at tuloy-tuloy na daloy — nagtatanong ang user, pumipili ang modelo ng tool, isinasagawa ng LangChain4j, at isinama ng modelo ang resulta sa natural na tugon.* +*Ang end-to-end na daloy — nagtatanong ang user, pumipili ang modelo ng tool, isinasagawa ito ng LangChain4j, at isinamasama ng modelo ang resulta sa natural na tugon.* -Kung pinatakbo mo ang [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) sa Module 00, nakita mo na ang pattern na ito sa aksyon — ang mga `Calculator` tool ay tinawag din sa parehong paraan. Ipinapakita ng sequence diagram sa ibaba kung ano ang nangyari sa likod ng eksena noong demo na iyon: +Sa likod ng eksena, nagpapatakbo ang `AiServices` ng parehong loop sa pagtawag ng tool para sa anumang tool — dito ipinapakita gamit ang simpleng `Calculator`. Ipinapakita ng sequence diagram sa ibaba kung ano talaga ang nangyayari: Tool Calling Sequence Diagram -*Ang loop ng pagtawag ng tool mula sa Quick Start demo — nagpapadala ang `AiServices` ng iyong mensahe at tool schemas sa LLM, sumasagot ang LLM gamit ang function call na tulad ng `add(42, 58)`, isinasagawa ng LangChain4j ang `Calculator` method locally, at ibinabalik ang resulta para sa huling sagot.* +*Ang loop sa pagtawag ng tool — ipinapadala ng `AiServices` ang iyong mensahe at schemas ng tool sa LLM, sumasagot ang LLM ng function call tulad ng `add(42, 58)`, isinasagawa ng LangChain4j ang method ng `Calculator` sa lokal, at binabalik ang resulta para sa panghuling sagot.* -> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) at itanong: +> **🤖 Subukan gamit ang [GitHub Copilot](https://github.com/features/copilot) Chat:** Buksan ang [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) at itanong: > - "Paano gumagana ang ReAct pattern at bakit ito epektibo para sa mga AI agent?" -> - "Paano nagpapasya ang agent kung aling tool ang gagamitin at sa anong ayos?" -> - "Ano ang nangyayari kung pumalya ang pagtawag ng tool - paano ko dapat mahawakang mabuti ang mga error?" +> - "Paano nagpasiya ang agent kung anong tool ang gagamitin at sa anong pagkakasunod?" +> - "Ano ang nangyayari kung mabigo ang pagtawag sa tool — paano dapat ako humawak ng mga error nang matibay?" ### Response Generation -Natanggap ng modelo ang datos ng panahon at inilalatag ito sa natural na tugon para sa user. +Tinatanggap ng modelo ang datos ng panahon at inaayos ito bilang sagot sa natural na wika para sa user. ### Architecture: Spring Boot Auto-Wiring -Gamit ang module na ito ang LangChain4j na integrasyon sa Spring Boot gamit ang deklaratibong `@AiService` interfaces. Sa pagsisimula, nadidiskubre ng Spring Boot ang bawat `@Component` na may mga `@Tool` method, ang iyong `ChatModel` bean, at ang `ChatMemoryProvider` — pagkatapos ay awtomatikong pinag-iisa ang mga ito sa isang `Assistant` interface na walang kailangang boilerplate. +Gamit ang module na ito ang integration ng LangChain4j sa Spring Boot na may declarative `@AiService` interfaces. Sa pagsisimula, natutuklasan ng Spring Boot ang bawat `@Component` na naglalaman ng `@Tool` methods, ang iyong `ChatModel` bean, at ang `ChatMemoryProvider` — tapos inilalagay lahat sa isang `Assistant` interface nang walang anumang karagdagang boilerplate. Spring Boot Auto-Wiring Architecture -*Pinagsasama-sama ng interface na @AiService ang ChatModel, mga component ng tool, at memory provider — pinangangasiwaan ng Spring Boot ang wiring nang awtomatiko.* +*Pinagsasama ng @AiService interface ang ChatModel, mga tool component, at provider ng memorya — awtomatikong inaayos ng Spring Boot ang lahat.* -Narito ang buong siklo ng request bilang sequence diagram — mula sa HTTP request papunta sa controller, service, at auto-wired proxy, hanggang sa pagtawag ng tool at pabalik: +Narito ang buong lifecycle ng request bilang sequence diagram — mula sa HTTP request, controller, service, auto-wired proxy, hanggang sa pagtawag ng tool at balik: Spring Boot Tool Calling Sequence -*Ang kumpletong siklo ng request sa Spring Boot — dumadaloy ang HTTP request sa controller at service patungo sa auto-wired Assistant proxy, na awtomatikong pinamamahalaan ang LLM at pagtawag ng mga tool.* +*Buong lifecycle ng Spring Boot request — dumadaloy ang HTTP request sa controller at service papunta sa auto-wired Assistant proxy, na inaayos ang LLM at mga tawag sa tool nang awtomatiko.* Mga pangunahing benepisyo ng ganitong approach: -- **Spring Boot auto-wiring** — Awtomatikong ini-inject ang ChatModel at mga tool -- **@MemoryId pattern** — Awtomatikong session-based memory management -- **Single instance** — Ang Assistant ay nilikha minsan lang at muling ginagamit para sa mas mahusay na performance -- **Type-safe execution** — Direktang pagtawag sa mga Java method na may type conversion +- **Spring Boot auto-wiring** — Awtomatikong na-inject ang ChatModel at mga tool +- **@MemoryId pattern** — Awtomatikong session-based na pamamahala ng memorya +- **Isang instance lang** — Ang Assistant ay isang beses lang nilikha at ginagamit muli para sa mas mahusay na performance +- **Type-safe na pagsasagawa** — Direct call sa mga Java method na may type conversion - **Multi-turn orchestration** — Awtomatikong humahawak sa tool chaining -- **Zero boilerplate** — Walang mano-manong `AiServices.builder()` na tawag o memory HashMap +- **Zero boilerplate** — Walang manual na `AiServices.builder()` calls o memory HashMap -Ang mga alternatibong paraan (manu-manong `AiServices.builder()`) ay nangangailangan ng mas maraming code at nawawala ang benepisyo ng Spring Boot integration. +Ang mga alternatibong paraan (manwal na `AiServices.builder()`) ay nangangailangan ng mas maraming code at wala ang benepisyo ng Spring Boot integration. ## Tool Chaining -**Tool Chaining** — Ang tunay na kapangyarihan ng mga agent na gumamit ng tool ay nakikita kapag ang isang tanong ay nangangailangan ng maraming tool. Tanungin "Ano ang panahon sa Seattle sa Fahrenheit?" at ang agent ay awtomatikong magkakabit ng dalawang tool: una nitong tinatawagan ang `getCurrentWeather` upang makuha ang temperatura sa Celsius, pagkatapos ay ipinapasa ang value na ito sa `celsiusToFahrenheit` para sa conversion — lahat sa isang pag-usap lang. +**Tool Chaining** — Lumilitaw ang tunay na lakas ng mga agent na batay sa tool kapag ang isang tanong ay nangangailangan ng maraming mga tool. Kapag tinanong na "Ano ang lagay ng panahon sa Seattle sa Fahrenheit?" awtomatikong nagsusunod ang agent ng dalawang tool: una, tinatawag ang `getCurrentWeather` para makuha ang temperatura sa Celsius, pagkatapos ay ipinapasa ang halagang iyon sa `celsiusToFahrenheit` para sa conversion — lahat sa isang usapan. Tool Chaining Example -*Tool chaining na gumagana — tinatawagan ng agent ang getCurrentWeather muna, pagkatapos ipinasok ang Celsius na resulta sa celsiusToFahrenheit, at nagbigay ng pinagsamang sagot.* +*Tool chaining na aktibo — tinatawag muna ng agent ang getCurrentWeather, pinapasa ang resultang Celsius sa celsiusToFahrenheit, at naghahatid ng pinagsamang sagot.* -**Graceful Failures** — Humiling ng panahon sa isang lungsod na wala sa mock data. Ibinabalik ng tool ang mensahe ng error, at ipinaliwanag ng AI na hindi ito makakatulong sa halip na mag-crash. Ligtas ang pagpalya ng mga tool. Ipinapakita ng diagram sa ibaba ang kaibahan ng dalawang approach — sa tamang paghawak ng error, nahuhuli ng agent ang exception at tumutugon nang maayos, habang kung wala ito ay magka-crash ang buong application: +**Graceful Failures** — Kapag naghiling ng panahon sa isang lungsod na wala sa mock data, nagbabalik ang tool ng mensahe ng error, at ipinaliwanag ng AI na hindi ito makakatulong sa halip na mag-crash. Ligtas na bumabangga ang mga tool. Ipinapakita ng diagram sa ibaba ang pagkakaiba ng dalawang approach — sa tamang paghawak ng error, nahuhuli ng agent ang exception at tumutugon nang maayos, habang kung wala nito, nagy-crash ang buong app: Error Handling Flow -*Kapag pumalya ang tool, nahuhuli ng agent ang error at tumutugon nang makatulong sa halip na mag-crash.* +*Kapag nabigo ang isang tool, nahuhuli ng agent ang error at tumutugon nang may paliwanag sa halip na mag-crash.* -Nangyayari ito sa isang pag-uusap lang. Awtonomo ang agent sa pag-organisa ng maraming pagtawag ng tool. +Nangyayari ito sa isang usapan lang. Awtomatikong pinangangasiwaan ng agent ang maraming tawag sa tool. ## Run the Application -**Patunayan ang deployment:** +**I-verify ang deployment:** -Siguraduhin na may `.env` file sa root directory na may Azure credentials (nilikha sa panahon ng Module 01). Patakbuhin ito mula sa module directory (`04-tools/`): +Siguraduhing may `.env` file sa root directory na may Azure credentials (nalikha sa Module 01). Patakbuhin ito mula sa module directory (`04-tools/`): **Bash:** ```bash @@ -205,44 +205,44 @@ cat ../.env # Dapat ipakita ang AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT Get-Content ..\.env # Dapat ipakita ang AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Simulan ang application:** +**Simulan ang aplikasyon:** -> **Note:** Kung sinimulan mo na ang lahat ng applications gamit ang `./start-all.sh` mula sa root directory (ayon sa Module 01), tumatakbo na ang module na ito sa port 8084. Maaari mong laktawan ang mga start command sa ibaba at pumunta agad sa http://localhost:8084. +> **Note:** Kung sinimulan mo na ang lahat ng aplikasyon gamit ang `./start-all.sh` mula sa root directory (tulad ng inilalahad sa Module 01), tumatakbo na ang module na ito sa port 8084. Maaari mo nang laktawan ang mga start command sa ibaba at puntahan nang diretso ang http://localhost:8084. -**Option 1: Paggamit ng Spring Boot Dashboard (Recommended para sa mga gumagamit ng VS Code)** +**Option 1: Gamit ang Spring Boot Dashboard (Inirerekomenda para sa mga gumagamit ng VS Code)** -Kasama sa dev container ang Spring Boot Dashboard extension, na naglalaman ng visual na interface upang pamahalaan ang lahat ng Spring Boot applications. Makikita mo ito sa Activity Bar sa kaliwang bahagi ng VS Code (hanapin ang icon ng Spring Boot). +Kasama sa dev container ang Spring Boot Dashboard extension, na nagbibigay ng biswal na interface para pamahalaan ang lahat ng Spring Boot application. Makikita ito sa Activity Bar sa kaliwang bahagi ng VS Code (hanapin ang Spring Boot icon). Mula sa Spring Boot Dashboard, maaari mong: -- Tingnan ang lahat ng magagamit na Spring Boot applications sa workspace -- Simulan/hinto ang applications gamit ang isang click lang -- Tingnan ang mga log ng application nang real-time -- Subaybayan ang status ng application -Pindutin lamang ang play button sa tabi ng "tools" para simulan ang modyul na ito, o simulan lahat ng modyul nang sabay-sabay. +- Makita ang lahat ng available na Spring Boot application sa workspace +- Simulan/hinto ang mga aplikasyon sa isang click lang +- Tingnan ang logs ng aplikasyon nang real-time +- Subaybayan ang status ng aplikasyon -Ganito ang hitsura ng Spring Boot Dashboard sa VS Code: +I-click lang ang play button sa tabi ng "tools" para simulan ang module na ito, o simulan lahat ng module nang sabay-sabay. +Ganito ang hitsura ng Spring Boot Dashboard sa VS Code: Spring Boot Dashboard -*Ang Spring Boot Dashboard sa VS Code — simulan, ihinto, at bantayan ang lahat ng mga modyul mula sa iisang lugar* +*Ang Spring Boot Dashboard sa VS Code — simulan, ihinto, at subaybayan ang lahat ng module mula sa isang lugar* -**Opsyon 2: Paggamit ng shell scripts** +**Option 2: Paggamit ng shell scripts** -Simulan lahat ng web application (mga modyul 01-04): +Simulan ang lahat ng web application (modules 01-04): **Bash:** ```bash -cd .. # Mula sa root na direktoryo +cd .. # Mula sa ugat na direktoryo ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # Mula sa ugat na direktoryo +cd .. # Mula sa root na direktoryo .\start-all.ps1 ``` -O simulan lamang ang modyul na ito: +O simulan lamang ang module na ito: **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Awtomatikong niloload ng parehong mga script ang mga environment variable mula sa root `.env` file at gagawin ang mga JAR kung hindi pa ito umiiral. +Ang dalawang script ay awtomatikong naglo-load ng environment variables mula sa root `.env` file at magbu-build ng mga JAR kung wala pa ang mga ito. -> **Tandaan:** Kung gusto mong manually na gawin ang lahat ng mga modyul bago simulan: +> **Note:** Kung nais mong manu-manong i-build ang lahat ng module bago magsimula: > > **Bash:** > ```bash @@ -278,110 +278,110 @@ Buksan ang http://localhost:8084 sa iyong browser. **Bash:** ```bash -./stop.sh # Ang modulong ito lamang +./stop.sh # Para lamang sa modulong ito # O cd .. && ./stop-all.sh # Lahat ng mga module ``` **PowerShell:** ```powershell -.\stop.ps1 # Ang modulong ito lamang +.\stop.ps1 # Module lamang ito # O -cd ..; .\stop-all.ps1 # Lahat ng mga module +cd ..; .\stop-all.ps1 # Lahat ng module ``` -## Paggamit ng Aplikasyon +## Paggamit ng Application -Nagbibigay ang aplikasyon ng web interface kung saan maaari kang makipag-ugnayan sa isang AI agent na may access sa mga tool para sa panahon at pagtanggap ng temperatura. Ganito ang hitsura ng interface — kasama dito ang mga mabilisang halimbawa at panel ng chat para magpadala ng mga kahilingan: +Nagbibigay ang application ng web interface kung saan maaari kang makipag-ugnayan sa isang AI agent na may access sa mga tool para sa panahon at pag-convert ng temperatura. Ganito ang hitsura ng interface — may kasamang mabilisang halimbawa at isang chat panel para magpadala ng mga kahilingan: AI Agent Tools Interface -*Ang interface ng AI Agent Tools - mabilisang mga halimbawa at chat interface para makipag-ugnayan sa mga tool* +*Ang AI Agent Tools interface - mabilisang mga halimbawa at chat interface para makipag-ugnayan sa mga tool* -### Subukan ang Simpleng Paggamit ng Tool +### Subukan ang Simpleng Paggamit ng Tools -Magsimula sa isang tuwirang kahilingan: "Convert 100 degrees Fahrenheit to Celsius". Nakikilala ng agent na kailangan nito ang tool para sa pagtanggap ng temperatura, tinatawag ito gamit ang tamang mga parameter, at ibinabalik ang resulta. Pansinin kung gaano ito naiintindihan nang natural — hindi mo kailangang sabihin kung aling tool ang gagamitin o paano ito tatawagin. +Magsimula sa isang tuwirang kahilingan: "Convert 100 degrees Fahrenheit to Celsius". Nakikita ng agent na kailangan nito ang temperature conversion tool, ginagamit ito sa tamang mga parameter, at ibinabalik ang resulta. Pansinin kung gaano ito ka-natural — hindi mo tinukoy kung aling tool ang gagamitin o kung paano ito tatawagin. -### Subukan ang Pagsunod-sunod ng Tool +### Subukan ang Pagsasunud-sunod ng Tools -Ngayon subukan ang mas kumplikadong bagay: "What's the weather in Seattle and convert it to Fahrenheit?" Panoorin ang agent habang ginagawa ito nang paunti-unti. Una nitong kukunin ang panahon (na nagbabalik ng Celsius), nakikilala na kailangan pang i-convert sa Fahrenheit, tinatawag ang conversion tool, at pinagsasama ang parehong resulta sa isang tugon. +Ngayon subukan ang mas kumplikado: "What's the weather in Seattle and convert it to Fahrenheit?" Obserbahan ang agent na ginagawa ito sa mga hakbang. Una niyang kinukuha ang panahon (na nagbabalik ng Celsius), nakikita na kailangan niyang i-convert sa Fahrenheit, tinatawagan ang conversion tool, at pinagsasama ang dalawang resulta sa isang tugon. ### Tingnan ang Daloy ng Usapan -Pinapanatili ng chat interface ang kasaysayan ng usapan, kaya maaari kang magkaroon ng multi-turn interactions. Makikita mo ang lahat ng mga nakaraang tanong at tugon, na nagpapadali upang subaybayan ang usapan at maintindihan kung paano bumubuo ng konteksto ang agent sa maraming palitan. +Pinananatili ng chat interface ang kasaysayan ng pag-uusap, na nagpapahintulot sa iyo na magkaroon ng multi-turn na interaksyon. Makikita mo ang lahat ng naunang mga query at sagot, na nagpapadali upang subaybayan ang usapan at maunawaan kung paano nagtatayo ng konteksto ang agent sa maraming palitan. Conversation with Multiple Tool Calls -*Multi-turn na usapan na nagpapakita ng simpleng conversions, pagtingin ng panahon, at pagsunod-sunod ng tool* +*Multi-turn na pag-uusap na nagpapakita ng simpleng mga conversion, pagtingin sa panahon, at pagsasunud-sunod ng tool* -### Magsagawa ng Mga Iba't Ibang Kahilingan +### Eksperimento sa Iba't Ibang Kahilingan -Subukan ang iba't ibang kombinasyon: -- Pagtingin ng panahon: "What's the weather in Tokyo?" -- Pagtanggap ng temperatura: "What is 25°C in Kelvin?" -- Pinagsamang mga tanong: "Check the weather in Paris and tell me if it's above 20°C" +Subukan ang iba't ibang kumbinasyon: +- Pagtingin sa panahon: "What's the weather in Tokyo?" +- Pag-convert ng temperatura: "What is 25°C in Kelvin?" +- Pinaghalong mga query: "Check the weather in Paris and tell me if it's above 20°C" -Pansinin kung paano binibigyang-kahulugan ng agent ang natural na wika at inaakma ito sa angkop na mga tawag sa tool. +Pansinin kung paano iniintindi ng agent ang natural na wika at iniaangkop ito sa tamang tawag sa mga tool. -## Pangunahing Mga Konsepto +## Mga Pangunahing Konsepto -### ReAct Pattern (Pangangatwiran at Pagkilos) +### ReAct Pattern (Pagrason at Pag-aksyon) -Ang agent ay nagpapalit-palit sa pagitan ng pangangatwiran (pagpapasya kung ano ang gagawin) at pagkilos (paggamit ng mga tool). Pinapayagan ng pattern na ito ang autonomosong paglutas ng problema kaysa sa simpleng pagsunod sa mga utos. +Ang agent ay nag-iiba-iba sa pagitan ng pagrarason (pagpapasya kung ano ang gagawin) at pag-aksyon (paggamit ng mga tool). Pinapagana ng pattern na ito ang autonomous na paglutas ng problema sa halip na simpleng pagsunod sa mga utos. -### Mahalaga ang Paglalarawan ng Tool +### Mahalaga ang Mga Deskripsyon ng Tool -Direktang naaapektuhan ng kalidad ng iyong paglalarawan ng tool kung gaano ito kahusay nagagamit ng agent. Ang malinaw at espesipikong paglalarawan ay tumutulong sa modelo na maintindihan kung kailan at paano tatawagin ang bawat tool. +Direktang naaapektuhan ng kalidad ng iyong mga deskripsyon ng tool kung gaano kagaling gamitin ng agent ang mga ito. Ang malinaw at tiyak na mga deskripsyon ay tumutulong sa modelong maunawaan kung kailan at paano tatawagin ang bawat tool. ### Pamamahala ng Session -Pinapagana ng `@MemoryId` annotation ang awtomatikong pamamahala ng memorya batay sa session. Bawat session ID ay may sarili nitong `ChatMemory` instance na pinamamahalaan ng `ChatMemoryProvider` bean, kaya maaaring makipag-ugnayan ang maraming gumagamit sa agent nang sabay nang hindi nagkakahalo ang kanilang mga usapan. Ipinapakita ng sumusunod na diagram kung paano ang maraming gumagamit ay naka-route sa hiwalay na mga memory store base sa kanilang session ID: +Pinapayagan ng annotation na `@MemoryId` ang awtomatikong pamamahala ng memorya base sa session. Bawat session ID ay may sariling `ChatMemory` na pinamamahalaan ng `ChatMemoryProvider` bean, kaya maraming users ang maaaring makipag-ugnayan sa agent nang sabay-sabay nang hindi nagkakahalo ang kanilang mga usapan. Ipinapakita ng sumusunod na diagram kung paano ipinapasa ang maraming users sa hiwalay na memory stores batay sa kanilang session IDs: Session Management with @MemoryId -*Bawat session ID ay naka-map sa isang hiwalay na kasaysayan ng usapan — hindi kailanman nakikita ng mga gumagamit ang mga mensahe ng isa't isa.* +*Bawat session ID ay tumutugma sa hiwalay na kasaysayan ng pag-uusap — hindi nakikita ng mga user ang mga mensahe ng iba.* -### Paghawak ng Mga Error +### Pag-handle ng Error -Maaaring mag-fail ang mga tool — timeout ang mga API, maaaring hindi wasto ang mga parameter, maaaring bumagsak ang mga external na serbisyo. Kailangan ng production agents ng paghawak ng error para maipaliwanag ng modelo ang mga problema o subukan ang mga alternatibo sa halip na mag-crash ang buong aplikasyon. Kapag may nag-throw ng exception ang isang tool, sinalo ito ng LangChain4j at ipinapasa ang mensahe ng error pabalik sa modelo, na maaari nang ipaliwanag ang problema sa natural na wika. +Maaaring mag-fail ang mga tool — maarong ma-timeout ang APIs, maaaring maging invalid ang mga parameter, o bumagsak ang mga external services. Kinakailangan ng mga production agent ang paghawak ng error upang maipaliwanag ng model kung ano ang problema o subukang gumawa ng alternatibo sa halip na bumagsak ang buong application. Kapag may tool na nag-throw ng exception, hinuhuli ito ng LangChain4j at ibinabalik ang mensahe ng error sa model, na pagkatapos ay kayang ipaliwanag ang problema gamit ang natural na wika. -## Mga Magagamit na Tool +## Mga Available na Tool -Ipinapakita sa diagram sa ibaba ang malawak na ekosistema ng mga tool na maaari mong gawin. Pinapakita ng modyul na ito ang mga tool para sa panahon at temperatura, ngunit ang parehong `@Tool` pattern ay gumagana para sa anumang Java method — mula sa mga database queries hanggang sa pagproseso ng bayad. +Ipinapakita ng diagram sa ibaba ang malawak na ecosystem ng mga tool na maaaring buuin. Ipinapakita ng module na ito ang mga tool para sa panahon at temperatura, pero ang parehong pattern na `@Tool` ay gumagana para sa anumang Java method — mula sa mga database query hanggang sa pagproseso ng bayad. Tool Ecosystem -*Anumang Java method na may annotation na @Tool ay magiging magagamit sa AI — ang pattern ay umaabot sa databases, APIs, email, operasyon ng file, at iba pa.* +*Ang anumang Java method na may annotation na @Tool ay nagiging available sa AI — umaabot ang pattern na ito sa databases, APIs, email, operasyon sa file, at iba pa.* -## Kailan Gumamit ng Tool-Based Agents +## Kailan Gamitin ang Mga Tool-Based na Agents -Hindi lahat ng kahilingan ay kailangan ng mga tool. Ang pagpapasya ay nakasalalay kung kailangan bang makipag-ugnayan ang AI sa mga external na sistema o kaya'y makasagot mula sa sariling kaalaman. Inilalahad ng sumusunod na gabay kung kailan may halaga ang mga tool at kailan ito hindi kailangan: +Hindi lahat ng kahilingan ay nangangailangan ng mga tool. Nakasalalay ang desisyon kung kailangan ba ng AI na makipag-ugnayan sa mga external system o kaya ay masagot ito mula sa sarili nitong kaalaman. Narito ang isang gabay na nagbubuod kung kailan may silbi ang mga tool at kung kailan hindi ito kailangan: When to Use Tools -*Isang mabilis na gabay sa pagpapasya — ang mga tool ay para sa real-time na datos, kalkulasyon, at mga aksyon; ang pangkalahatang kaalaman at malikhaing gawain ay hindi nangangailangan nito.* +*Isang mabilis na gabay sa desisyon — ang mga tool ay para sa real-time na data, kalkulasyon, at mga aksyon; ang pangkalahatang kaalaman at malikhaing gawain ay hindi nangangailangan nito.* -## Tools kumpara sa RAG +## Tools vs RAG -Ang mga Modyul 03 at 04 ay parehong nagpapalawak ng kaya ng AI, ngunit sa magkaibang pamamaraan. Binibigyan ng RAG ang modelo ng access sa **kaalaman** sa pamamagitan ng pagkuha ng mga dokumento. Binibigyan naman ng Tools ang modelo ng kakayahang gumawa ng mga **aksiyon** sa pamamagitan ng pagtawag ng mga function. Ikinukumpara ng diagram sa ibaba ang dalawang approach na ito sa tabi-tabi — mula sa kung paano gumagana ang bawat workflow hanggang sa mga trade-off sa pagitan nila: +Pinapalawak ng Modules 03 at 04 kung ano ang kaya ng AI, ngunit sa dalawang magkaibang paraan. Ang RAG ay nagbibigay ng access sa **kaalaman** sa pamamagitan ng pagkuha ng mga dokumento. Ang mga Tool naman ay nagbibigay ng kakayahan sa model na magsagawa ng **mga aksyon** sa pamamagitan ng pagtawag ng mga function. Ipinapakita ng diagram sa ibaba ang paghahambing ng dalawang approach na ito — mula sa kung paano gumagana ang bawat workflow hanggang sa mga kalamangan at kahinaan nila: Tools vs RAG Comparison -*Kinukuha ng RAG ang impormasyon mula sa mga static na dokumento — Ang Tools ay gumaganap ng mga aksyon at kumukuha ng dynamic, real-time na datos. Pinagsasama ng maraming production system ang dalawa.* +*Kinukuha ng RAG ang impormasyon mula sa mga static na dokumento — Ang Tools ay nagsasagawa ng mga aksyon at kumukuha ng dinamiko, real-time na data. Maraming production system ang pinagsasama ang pareho.* -Sa praktika, maraming production system ang pinagsasama ang dalawang approach: RAG para sa pagbatay ng mga sagot sa iyong dokumentasyon, at Tools para sa pagkuha ng live na datos o pagsasagawa ng mga operasyon. +Sa praktika, maraming production system ang pinagsasama ang dalawang approach: RAG para gawing grounded ang mga sagot sa iyong dokumentasyon, at Tools para kumuha ng live na data o magsagawa ng mga operasyon. ## Mga Susunod na Hakbang -**Susunod na Modyul:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Next Module:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) --- -**Navigation:** [← Nakaraan: Modyul 03 - RAG](../03-rag/README.md) | [Bumalik sa Main](../README.md) | [Susunod: Modyul 05 - MCP →](../05-mcp/README.md) +**Navigation:** [← Previous: Module 03 - RAG](../03-rag/README.md) | [Back to Main](../README.md) | [Next: Module 05 - MCP →](../05-mcp/README.md) --- -**Pagsasalin ng Paunawa**: -Ang dokumentong ito ay isinalin gamit ang AI na serbisyo sa pagsasalin na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagamat aming pinagsisikapan ang katumpakan, mangyaring tandaan na ang mga awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o di-tiyak na mga impormasyon. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pinaka-tiwalaang sanggunian. Para sa mahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang hindi pagkakaunawaan o maling interpretasyon na maaaring magmula sa paggamit ng pagsasaling ito. +**Pagtatanggi**: +Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kami para sa katumpakan, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang maling pagkakaintindi o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito. \ No newline at end of file diff --git a/translations/tl/README.md b/translations/tl/README.md index 22667b342..8c927fa28 100644 --- a/translations/tl/README.md +++ b/translations/tl/README.md @@ -1,19 +1,19 @@ LangChain4j -# LangChain4j para sa Mga Nagsisimula +# LangChain4j para sa mga Nagsisimula -Isang kurso para sa paggawa ng mga AI na aplikasyon gamit ang LangChain4j at Azure OpenAI GPT-5.2, mula sa pangunahing chat hanggang sa mga AI agent. +Isang kurso para sa pagbuo ng mga AI na aplikasyon gamit ang LangChain4j at Azure OpenAI GPT-5.2, mula sa simpleng chat hanggang sa mga AI agents. ### 🌐 Suporta sa Maramihang Wika -#### Sinusuportahan sa pamamagitan ng GitHub Action (Awtomatiko at Laging Napapanahon) +#### Sinusuportahan sa pamamagitan ng GitHub Action (Automated & Palaging Napapanahon) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](./README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Mas gusto mong I-clone Nang Lokal?** +> **Mas Gusto Mong Mag-clone Lokally?** > -> Kasama sa repositoryo na ito ang mahigit 50 na pagsasalin ng wika na malaki ang dagdag sa laki ng pag-download. Upang i-clone nang walang mga pagsasalin, gamitin ang sparse checkout: +> Kasama sa repositoryong ito ang mahigit 50 na mga pagsasalin sa wika na malaki ang dagdag sa laki ng pag-download. Upang mag-clone nang walang mga pagsasalin, gamitin ang sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -34,77 +34,76 @@ Isang kurso para sa paggawa ng mga AI na aplikasyon gamit ang LangChain4j at Azu ## Talaan ng Nilalaman -1. [Mabilis na Simula](00-quick-start/README.md) - Magsimula sa LangChain4j -2. [Panimula](01-introduction/README.md) - Matutunan ang mga batayan ng LangChain4j -3. [Prompt Engineering](02-prompt-engineering/README.md) - Mag-master ng epektibong disenyo ng prompt -4. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Gumawa ng matatalinong sistema batay sa kaalaman -5. [Mga Tools](04-tools/README.md) - Integrasyon ng mga panlabas na tool at simpleng assistant -6. [MCP (Model Context Protocol)](05-mcp/README.md) - Gumamit ng Model Context Protocol (MCP) at mga module ng Agentic +1. [Introduksyon](01-introduction/README.md) - Matutunan ang mga pundasyon ng LangChain4j +2. [Prompt Engineering](02-prompt-engineering/README.md) - Masterin ang mabisang disenyo ng prompt +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Bumuo ng mga intelihenteng sistema na batay sa kaalaman +4. [Mga Kasangkapan](04-tools/README.md) - Isama ang mga panlabas na kasangkapan at simpleng mga assistant +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Gumamit ng Model Context Protocol (MCP) at mga Agentic modules -### Mga Video na Walkthrough +### Mga Video Walkthrough -Bawat module ay may kasamang live session kung saan tinatalakay namin ang mga konsepto at code nang sunud-sunod. +Bawat module ay may kalakip na live session kung saan tinatalakay natin ang mga konsepto at code nang hakbang-hakbang. | Module | Video | |--------|-------| -| 01 - Panimula | [Pagsisimula sa LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | +| 01 - Introduksyon | [Panimula sa LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - Prompt Engineering | [Prompt Engineering gamit ang LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG gamit ang LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Mga Tools at 05 - MCP | [AI Agents gamit ang Mga Tools at MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Mga Kasangkapan & 05 - MCP | [AI Agents gamit ang Tools at MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## Landas ng Pagkatuto -**Bago ka sa LangChain4j?** Tingnan ang [Glossary](docs/GLOSSARY.md) para sa mga kahulugan ng mga pangunahing termino at konsepto. +**Bago ka sa LangChain4j?** Tingnan ang [Glossary](docs/GLOSSARY.md) para sa mga kahulugan ng mga mahahalagang termino at konsepto. -> **Mabilis na Simula** +> **Mabilisang Simula** 1. I-fork ang repositoryong ito sa iyong GitHub account 2. I-click ang **Code** → tab na **Codespaces** → **...** → **New with options...** -3. Gamitin ang mga default – pipiliin nito ang Development container na ginawa para sa kursong ito +3. Gamitin ang default – ito ay pipili ng Development container na ginawa para sa kursong ito 4. I-click ang **Create codespace** 5. Maghintay ng 5-10 minuto para maging handa ang kapaligiran -6. Diretso sa [Mabilis na Simula](./00-quick-start/README.md) upang magsimula! +6. Diretso sa [Introduksyon](./01-introduction/README.md) para magsimula! -Pagkatapos matapos ang mga module, tuklasin ang [Testing Guide](docs/TESTING.md) upang makita ang mga konsepto ng pagsubok sa LangChain4j na gumagana. +Pagkatapos tapusin ang mga module, tuklasin ang [Gabayan sa Pagsusuri](docs/TESTING.md) upang makita ang mga konsepto sa pagsusuri ng LangChain4j sa aksyon. -> **Paunawa:** Ginagamit ng pagsasanay na ito ang parehong GitHub Models at Azure OpenAI. Ang module na [Mabilis na Simula](00-quick-start/README.md) ay gumagamit ng GitHub Models (hindi kailangan ng Azure subscription), habang ang mga module 1-5 ay gumagamit ng Azure OpenAI. Magsimula gamit ang [LIBRENG Azure account](https://aka.ms/azure-free-account) kung wala ka pa nito. +> **Tandaan:** Ginagamit ng pagsasanay na ito ang Azure OpenAI. Magsimula gamit ang isang [LIBRENG Azure account](https://aka.ms/azure-free-account) kung wala ka pa nito. ## Pagkatuto gamit ang GitHub Copilot -Para makapagsimula agad sa pag-code, buksan ang proyektong ito sa GitHub Codespace o sa iyong lokal na IDE gamit ang ibinigay na devcontainer. Ang devcontainer na ginamit sa kursong ito ay pre-configured na gamit ang GitHub Copilot para sa AI paired programming. +Para mabilis na makapagsimula sa coding, buksan ang proyekto na ito sa GitHub Codespace o iyong lokal na IDE gamit ang ibinigay na devcontainer. Ang devcontainer na ginamit sa kurso na ito ay paunang naka-configure na may GitHub Copilot para sa AI na magkasamang programming. -Bawat halimbawa ng code ay may kasamang mga inirerekomendang tanong na maaari mong itanong sa GitHub Copilot upang mapalalim ang iyong pag-unawa. Hanapin ang mga 💡/🤖 na prompt sa: +Bawat halimbawa ng code ay may mga mungkahing tanong na maaari mong itanong sa GitHub Copilot upang palalimin ang iyong pag-unawa. Hanapin ang mga 💡/🤖 na prompt sa: -- **Java file headers** - Mga tanong na tiyak para sa bawat halimbawa -- **Module READMEs** - Mga prompt sa eksplorasyon pagkatapos ng mga halimbawa ng code +- **Mga header ng Java file** - Mga tanong na partikular sa bawat halimbawa +- **Mga README ng module** - Mga prompt para sa eksplorasyon pagkatapos ng mga halimbawa ng code -**Paano gamitin:** Buksan ang anumang code file at itanong sa Copilot ang mga inirerekomendang tanong. Buo ang konteksto nito tungkol sa codebase at kaya nitong magpaliwanag, magpalawak, at magmungkahi ng mga alternatibo. +**Paano gamitin:** Buksan ang anumang file ng code at itanong sa Copilot ang mga mungkahing tanong. Mayroon itong buong konteksto ng codebase at maaaring magpaliwanag, magpalawig, at magmungkahi ng mga alternatibo. -Gusto mo pa bang matuto? Tingnan ang [Copilot para sa AI Paired Programming](https://aka.ms/GitHubCopilotAI). +Gusto mo bang matuto pa? Tingnan ang [Copilot para sa AI Paired Programming](https://aka.ms/GitHubCopilotAI). ## Karagdagang Mga Mapagkukunan ### LangChain -[![LangChain4j para sa Mga Nagsisimula](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js para sa Mga Nagsisimula](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain para sa Mga Nagsisimula](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j para sa mga Nagsisimula](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js para sa mga Nagsisimula](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain para sa mga Nagsisimula](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- ### Azure / Edge / MCP / Agents -[![AZD para sa Mga Nagsisimula](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI para sa Mga Nagsisimula](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP para sa Mga Nagsisimula](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents para sa Mga Nagsisimula](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AZD para sa mga Nagsisimula](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI para sa mga Nagsisimula](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP para sa mga Nagsisimula](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI Agents para sa mga Nagsisimula](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Generative AI Series -[![Generative AI para sa Mga Nagsisimula](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generative AI para sa mga Nagsisimula](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) [![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) @@ -112,10 +111,10 @@ Gusto mo pa bang matuto? Tingnan ang [Copilot para sa AI Paired Programming](htt --- ### Pangunahing Pagkatuto -[![ML para sa Mga Nagsisimula](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science para sa Mga Nagsisimula](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI para sa Mga Nagsisimula](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![ML para sa mga Nagsisimula](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science para sa mga Nagsisimula](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI para sa mga Nagsisimula](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity para sa mga Nagsisimula](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -128,23 +127,23 @@ Gusto mo pa bang matuto? Tingnan ang [Copilot para sa AI Paired Programming](htt [![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## Pagkuha ng Tulong +## Getting Help -Kung ikaw ay mahirapan o may mga tanong tungkol sa paggawa ng mga AI na app, sumali: +Kung ikaw ay na-stuck o may mga tanong tungkol sa paggawa ng AI apps, sumali sa: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Kung mayroon kang puna tungkol sa produkto o mga error habang gumagawa, bisitahin: +Kung mayroon kang feedback tungkol sa produkto o mga error habang gumagawa, bisitahin: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) -## Lisensya +## License -MIT Lisensya - Tingnan ang [LICENSE](../../LICENSE) na file para sa mga detalye. +MIT License - Tingnan ang [LICENSE](../../LICENSE) file para sa mga detalye. --- -**Paunawa**: -Ang dokumentong ito ay isinalin gamit ang AI translation service na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagamat nagsusumikap kami para sa katumpakan, pakitandaan na ang mga awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o di-katumpakan. Ang orihinal na dokumento sa kanyang katutubong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang mga hindi pagkakaunawaan o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito. +**Pagtatanggi**: +Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kami para sa katumpakan, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang maling pagkakaintindi o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito. \ No newline at end of file diff --git a/translations/tl/docs/GLOSSARY.md b/translations/tl/docs/GLOSSARY.md index 8687b1d9f..70299f5a1 100644 --- a/translations/tl/docs/GLOSSARY.md +++ b/translations/tl/docs/GLOSSARY.md @@ -1,124 +1,124 @@ -# LangChain4j Talahulugan - -## Talaan ng Nilalaman - -- [Pangunahing Konsepto](../../../docs) -- [Mga Komponent ng LangChain4j](../../../docs) -- [Mga Konsepto sa AI/ML](../../../docs) -- [Mga Guardrails](../../../docs) -- [Prompt Engineering](../../../docs) -- [RAG (Retrieval-Augmented Generation)](../../../docs) -- [Mga Ahente at Mga Kasangkapan](../../../docs) -- [Agentic Module](../../../docs) -- [Model Context Protocol (MCP)](../../../docs) -- [Mga Serbisyo ng Azure](../../../docs) -- [Pagsubok at Pag-unlad](../../../docs) +# LangChain4j Glossary + +## Table of Contents + +- [Core Concepts](#core-concepts) +- [LangChain4j Components](#langchain4j-components) +- [AI/ML Concepts](#aiml-concepts) +- [Guardrails](#guardrails) +- [Prompt Engineering](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Agents and Tools](#agents-and-tools---module-04) +- [Agentic Module](#agentic-module---module-05) +- [Model Context Protocol (MCP)](#model-context-protocol-mcp---module-05) +- [Azure Services](#azure-services---module-01) +- [Testing and Development](#testing-and-development---testing-guide) Mabilisang sanggunian para sa mga termino at konsepto na ginagamit sa buong kurso. -## Pangunahing Konsepto +## Core Concepts -**AI Agent** - Sistemang gumagamit ng AI para mag-isip at kumilos nang awtonomo. [Module 04](../04-tools/README.md) +**AI Agent** - Sistema na gumagamit ng AI upang mag-isip at kumilos nang awtonomo. [Module 04](../04-tools/README.md) -**Chain** - Sunud-sunod na operasyon kung saan ang output ay nagsisilbing input sa susunod na hakbang. +**Chain** - Sunod-sunod na operasyon kung saan ang output ay nagsisilbing input sa susunod na hakbang. -**Chunking** - Paghiwa-hiwalay ng mga dokumento sa maliliit na bahagi. Karaniwang: 300-500 tokens na may overlap. [Module 03](../03-rag/README.md) +**Chunking** - Paghahati ng mga dokumento sa maliliit na bahagi. Karaniwan: 300-500 na token na may overlap. [Module 03](../03-rag/README.md) -**Context Window** - Pinakamalaking bilang ng tokens na kayang i-proseso ng modelo. GPT-5.2: 400K tokens (hanggang 272K input, 128K output). +**Context Window** - Pinakamalaking bilang ng token na kayang proseso ng modelo. GPT-5.2: 400K token (hanggang 272K input, 128K output). -**Embeddings** - Numerikal na vector na kumakatawan sa kahulugan ng teksto. [Module 03](../03-rag/README.md) +**Embeddings** - Numerikal na vectors na kumakatawan sa kahulugan ng teksto. [Module 03](../03-rag/README.md) -**Function Calling** - Lumilikha ang modelo ng nakaestrukturang kahilingan para tumawag ng panlabas na mga function. [Module 04](../04-tools/README.md) +**Function Calling** - Ang modelo ay gumagawa ng istrukturadong hinihiling upang tawagan ang mga panlabas na function. [Module 04](../04-tools/README.md) -**Hallucination** - Kapag ang mga modelo ay nagbuo ng maling ngunit mukhang kapani-paniwalang impormasyon. +**Hallucination** - Kapag ang mga modelo ay lumilikha ng maling ngunit kapanipaniwala na impormasyon. -**Prompt** - Tekstong ipinasok sa isang language model. [Module 02](../02-prompt-engineering/README.md) +**Prompt** - Input na teksto sa isang language model. [Module 02](../02-prompt-engineering/README.md) -**Semantic Search** - Paghahanap batay sa kahulugan gamit ang embeddings, hindi paksa. [Module 03](../03-rag/README.md) +**Semantic Search** - Paghahanap batay sa kahulugan gamit ang embeddings, hindi keywords. [Module 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: walang memorya. Stateful: nagpapanatili ng kasaysayan ng usapan. [Module 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: walang memorya. Stateful: nagpapanatili ng kasaysayan ng pag-uusap. [Module 01](../01-introduction/README.md) **Tokens** - Pangunahing yunit ng teksto na pinoproseso ng mga modelo. Nakakaapekto sa gastos at limitasyon. [Module 01](../01-introduction/README.md) -**Tool Chaining** - Sunud-sunod na paggamit ng mga kasangkapan kung saan ang output ay ginagamit sa susunod na tawag. [Module 04](../04-tools/README.md) +**Tool Chaining** - Sunud-sunod na pagpapatakbo ng mga tool kung saan ang output ay ginagamit sa susunod na tawag. [Module 04](../04-tools/README.md) -## Mga Komponent ng LangChain4j +## LangChain4j Components -**AiServices** - Lumilikha ng type-safe na mga interface ng serbisyo ng AI. +**AiServices** - Lumilikha ng type-safe na mga interface para sa AI services. -**OpenAiOfficialChatModel** - Pinagsamang kliyente para sa OpenAI at Azure OpenAI models. +**OpenAiOfficialChatModel** - Pinag-isang kliyente para sa OpenAI at Azure OpenAI na mga modelo. -**OpenAiOfficialEmbeddingModel** - Lumilikha ng embeddings gamit ang OpenAI Official client (sumusuporta sa OpenAI at Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Lumilikha ng embeddings gamit ang OpenAI Official client (sumusuporta sa parehong OpenAI at Azure OpenAI). **ChatModel** - Pangunahing interface para sa mga language model. -**ChatMemory** - Nangangalaga ng kasaysayan ng usapan. +**ChatMemory** - Nagpapanatili ng kasaysayan ng pag-uusap. -**ContentRetriever** - Nakakahanap ng mga kaugnay na bahagi ng dokumento para sa RAG. +**ContentRetriever** - Naghahanap ng mga kaugnay na bahagi ng dokumento para sa RAG. -**DocumentSplitter** - Naghahati ng mga dokumento sa maliliit na bahagi. +**DocumentSplitter** - Humahati sa mga dokumento sa mga chunks. -**EmbeddingModel** - Nagko-convert ng teksto sa numerikal na mga vector. +**EmbeddingModel** - Nagko-convert ng teksto sa numerikal na vectors. -**EmbeddingStore** - Nag-iimbak at kumukuha ng mga embeddings. +**EmbeddingStore** - Nag-iimbak at kumukuha ng embeddings. -**MessageWindowChatMemory** - Nangangalaga ng sliding window ng mga kamakailang mensahe. +**MessageWindowChatMemory** - Nagpapanatili ng sliding window ng mga pinakabagong mensahe. -**PromptTemplate** - Lumilikha ng reusable prompts gamit ang `{{variable}}` placeholders. +**PromptTemplate** - Lumilikha ng mga reusable na prompt na may `{{variable}}` na placeholders. -**TextSegment** - Piraso ng teksto na may metadata. Ginagamit sa RAG. +**TextSegment** - Bahagi ng teksto na may metadata. Ginagamit sa RAG. -**ToolExecutionRequest** - Kinakatawan ang kahilingan para sa pagpapatupad ng kasangkapan. +**ToolExecutionRequest** - Kumakatawan sa hiling na pagpapatakbo ng tool. -**UserMessage / AiMessage / SystemMessage** - Mga uri ng mensahe sa usapan. +**UserMessage / AiMessage / SystemMessage** - Mga uri ng mensahe sa pag-uusap. -## Mga Konsepto sa AI/ML +## AI/ML Concepts -**Few-Shot Learning** - Pagbibigay ng mga halimbawa sa mga prompt. [Module 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Nagbibigay ng mga halimbawa sa mga prompt. [Module 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - AI models na sinanay gamit ang napakalaking dami ng teksto. +**Large Language Model (LLM)** - AI models na sinanay gamit ang napakaraming tekstuwal na datos. **Reasoning Effort** - Parameter ng GPT-5.2 na kumokontrol sa lalim ng pag-iisip. [Module 02](../02-prompt-engineering/README.md) -**Temperature** - Kumokontrol sa pagiging random ng output. Mababang value=deterministic, mataas=malikhain. +**Temperature** - Kumokontrol sa randomness ng output. Mababang halaga=deterministic, mataas=malikhain. -**Vector Database** - Espesyal na database para sa mga embeddings. [Module 03](../03-rag/README.md) +**Vector Database** - Espesyal na database para sa embeddings. [Module 03](../03-rag/README.md) **Zero-Shot Learning** - Pagsasagawa ng mga gawain nang walang mga halimbawa. [Module 02](../02-prompt-engineering/README.md) -## Mga Guardrails - [Module 00](../00-quick-start/README.md) +## Guardrails -**Defense in Depth** - Multi-layer na diskarte sa seguridad na pinagsasama ang application-level guardrails at provider safety filters. +**Defense in Depth** - Maramihang antas ng seguridad na pinagsasama ang mga guardrail sa antas ng application at mga provider safety filter. -**Hard Block** - Nagbibigay ang provider ng HTTP 400 error para sa matinding paglabag sa nilalaman. +**Hard Block** - Nagbibigay ang provider ng HTTP 400 error para sa seryosong paglabag sa nilalaman. -**InputGuardrail** - LangChain4j interface para sa pag-validate ng input ng user bago makarating sa LLM. Nakakatipid sa gastos at latency sa pamamagitan ng maagang pagharang ng mapanganib na prompt. +**InputGuardrail** - Interface ng LangChain4j para i-validate ang input ng user bago ito makarating sa LLM. Nakakatipid sa gastos at latency sa pamamagitan ng maagang pagharang sa mapanganib na mga prompt. **InputGuardrailResult** - Uri ng return para sa validation ng guardrail: `success()` o `fatal("reason")`. -**OutputGuardrail** - Interface para sa pag-validate ng tugon ng AI bago ibalik sa mga user. +**OutputGuardrail** - Interface para sa pag-validate ng mga sagot ng AI bago ibalik sa mga user. -**Provider Safety Filters** - Mga built-in na filter sa nilalaman mula sa AI providers (hal. GitHub Models) na naghuhuli ng paglabag sa API level. +**Provider Safety Filters** - Mga built-in na filter ng nilalaman mula sa mga AI provider (hal. Azure OpenAI) na humahuli ng paglabag sa API level. -**Soft Refusal** - Masinop na pagtanggi ng modelo na sumagot nang hindi nagbabato ng error. +**Soft Refusal** - Magalang na pagtanggi ng modelo na sumagot nang hindi nagkakaroon ng error. ## Prompt Engineering - [Module 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Hakbang-hakbang na pangangatwiran para sa mas mahusay na katumpakan. +**Chain-of-Thought** - Hakbang-hakbang na pag-unlad ng pag-iisip para sa mas mahusay na katumpakan. -**Constrained Output** - Pagpapatupad ng tiyak na format o estruktura. +**Constrained Output** - Pagpapatupad ng espesipikong format o istruktura. -**High Eagerness** - Pattern ng GPT-5.2 para sa masusing pangangatwiran. +**High Eagerness** - Pattern ng GPT-5.2 para sa masusing pag-iisip. -**Low Eagerness** - Pattern ng GPT-5.2 para sa mabilisang sagot. +**Low Eagerness** - Pattern ng GPT-5.2 para sa mabilis na sagot. -**Multi-Turn Conversation** - Pagpapanatili ng konteksto sa mga palitan. +**Multi-Turn Conversation** - Pagpapanatili ng konteksto sa iba't ibang palitan. -**Role-Based Prompting** - Pagtatakda ng personalidad ng modelo sa pamamagitan ng mga system messages. +**Role-Based Prompting** - Pagtatakda ng persona ng modelo sa pamamagitan ng system messages. **Self-Reflection** - Pagsusuri at pagpapabuti ng output ng modelo. -**Structured Analysis** - Nakapirming balangkas ng pagsusuri. +**Structured Analysis** - Nakapirming balangkas ng ebalwasyon. **Task Execution Pattern** - Plano → Isagawa → Buodin. @@ -126,99 +126,97 @@ Mabilisang sanggunian para sa mga termino at konsepto na ginagamit sa buong kurs **Document Processing Pipeline** - Load → chunk → embed → store. -**In-Memory Embedding Store** - Hindi permanenteng imbakan para sa pagsubok. +**In-Memory Embedding Store** - Hindi permanenteng imbakan para sa testing. -**RAG** - Pinagsasama ang retrieval at generation para sa mas matibay na tugon. +**RAG** - Pinagsasama ang retrieval at generation para masigurong nakabase ang mga sagot. -**Similarity Score** - Sukatan (0-1) ng semantikong pagkakatulad. +**Similarity Score** - Sukatan (0-1) ng semantic similarity. -**Source Reference** - Metadata tungkol sa nakuhang nilalaman. +**Source Reference** - Metadata tungkol sa nakuha na nilalaman. -## Mga Ahente at Mga Kasangkapan - [Module 04](../04-tools/README.md) +## Agents and Tools - [Module 04](../04-tools/README.md) -**@Tool Annotation** - Nagmamarka ng Java methods bilang AI-callable tools. +**@Tool Annotation** - Nagmamarka ng mga Java method bilang mga AI-callable na tool. **ReAct Pattern** - Mag-isip → Kumilos → Obserbahan → Ulitin. -**Session Management** - Ihiwalay na mga konteksto para sa iba't ibang user. +**Session Management** - Hiwa-hiwalay na mga konteksto para sa iba't ibang user. -**Tool** - Function na maaaring tawagin ng isang AI agent. +**Tool** - Function na maaaring tawagin ng AI agent. -**Tool Description** - Dokumentasyon ng layunin at mga parameter ng kasangkapan. +**Tool Description** - Dokumentasyon ng layunin at mga parameter ng tool. ## Agentic Module - [Module 05](../05-mcp/README.md) -**@Agent Annotation** - Nagmamarka ng mga interface bilang AI agents na may deklaratibong pagdedepina ng asal. +**@Agent Annotation** - Nagmamarka ng mga interface bilang AI agents na may deklaratibong depinisyon ng behavior. -**Agent Listener** - Hook para sa pagmamanman ng execution ng ahente gamit ang `beforeAgentInvocation()` at `afterAgentInvocation()`. +**Agent Listener** - Hook para sa pagmamanman ng pagpapatupad ng agent sa pamamagitan ng `beforeAgentInvocation()` at `afterAgentInvocation()`. -**Agentic Scope** - Pinagsamang memorya kung saan iniimbak ng mga ahente ang mga output gamit ang `outputKey` para magamit ng mga sumusunod na ahente. +**Agentic Scope** - Shared memory kung saan nag-iimbak ang mga agent ng output gamit ang `outputKey` para magamit ng mga downstream na agent. -**AgenticServices** - Pabrika para sa paggawa ng mga ahente gamit ang `agentBuilder()` at `supervisorBuilder()`. +**AgenticServices** - Pabrika para sa paggawa ng mga agent gamit ang `agentBuilder()` at `supervisorBuilder()`. -**Conditional Workflow** - Ruta base sa mga kundisyon papunta sa iba't ibang mga espesyalistang ahente. +**Conditional Workflow** - Daan batay sa kondisyon patungo sa iba't ibang espesyalistang agent. -**Human-in-the-Loop** - Workflow pattern na naglalagay ng mga checkpoint para sa tao para sa pag-apruba o pagsusuri ng nilalaman. +**Human-in-the-Loop** - Workflow pattern na naglalagay ng human checkpoint para sa pag-apruba o pagsusuri ng nilalaman. -**langchain4j-agentic** - Maven dependency para sa deklaratibong pagbuo ng ahente (eksperimento). +**langchain4j-agentic** - Dependency sa Maven para sa deklaratibong paggawa ng agent (eksperimento). -**Loop Workflow** - Paulit-ulit na pagpapatakbo ng ahente hanggang matugunan ang isang kundisyon (hal. quality score ≥ 0.8). +**Loop Workflow** - Paulit-ulit na pagpapatakbo ng agent hanggang sa matugunan ang kondisyon (hal. quality score ≥ 0.8). -**outputKey** - Parameter ng annotation ng ahente na nagsasaad kung saan iniimbak ang mga resulta sa Agentic Scope. +**outputKey** - Parameter ng annotation ng agent na nagsasaad kung saan iniimbak ang resulta sa Agentic Scope. -**Parallel Workflow** - Pagpapatakbo ng maramihang mga ahente nang sabay-sabay para sa mga independiyenteng gawain. +**Parallel Workflow** - Sabay-sabay na pagpapatakbo ng maraming agent para sa magkahiwalay na gawain. -**Response Strategy** - Paraan ng supervisor sa pagbuo ng panghuling sagot: LAST, SUMMARY, o SCORED. +**Response Strategy** - Paraan ng supervisor sa pagbubuo ng huling sagot: LAST, SUMMARY, o SCORED. -**Sequential Workflow** - Sunud-sunod na pagpapatakbo ng ahente kung saan ang output ay dumadaloy sa susunod na hakbang. +**Sequential Workflow** - Sunod-sunod na pagpapatakbo ng mga agent kung saan dumadaloy ang output sa susunod na hakbang. -**Supervisor Agent Pattern** - Advanced na pattern ng ahente kung saan ang isang supervisor LLM ang dinamiko na nagdedesisyon kung alin sa mga sub-agents ang tatawagin. +**Supervisor Agent Pattern** - Advanced na pattern ng agentic kung saan ang isang supervisor LLM ang dinamiko na nagpapasya kung aling mga sub-agent ang tatawagin. ## Model Context Protocol (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - Maven dependency para sa integrasyon ng MCP sa LangChain4j. +**langchain4j-mcp** - Dependency sa Maven para sa integrasyon ng MCP sa LangChain4j. -**MCP** - Model Context Protocol: pamantayan para sa pagkonekta ng mga AI app sa panlabas na mga kasangkapan. Gawin isang beses, gamitin saanman. +**MCP** - Model Context Protocol: pamantayan para sa pagkonekta ng mga AI app sa mga panlabas na tool. Isa lang buuin, gamitin saanman. -**MCP Client** - Aplikasyon na kumokonekta sa MCP servers para matuklasan at magamit ang mga kasangkapan. +**MCP Client** - Aplikasyon na nakakonekta sa MCP server para magdiskubre at gumamit ng mga tool. -**MCP Server** - Serbisyong nagpapakita ng mga kasangkapan sa pamamagitan ng MCP na may malinaw na mga paglalarawan at schema ng mga parameter. +**MCP Server** - Serbisyo na nagpapakita ng mga tool sa pamamagitan ng MCP na may malinaw na paglalarawan at parameter schema. -**McpToolProvider** - Komponent ng LangChain4j na kumukulayet ng MCP tools para gamitin sa AI services at mga ahente. +**McpToolProvider** - Komponent ng LangChain4j na bumabalot sa mga MCP tool para gamitin sa AI services at mga agent. -**McpTransport** - Interface para sa komunikasyon ng MCP. Kasama ang mga implementasyon ng Stdio at HTTP. +**McpTransport** - Interface para sa komunikasyon ng MCP. Ang mga implementasyon ay kinabibilangan ng Stdio at HTTP. -**Stdio Transport** - Lokal na proseso na transport gamit ang stdin/stdout. Kapaki-pakinabang sa pag-access ng filesystem o mga command-line tools. +**Stdio Transport** - Lokal na proseso ng transportasyon gamit ang stdin/stdout. Kapaki-pakinabang para sa filesystem access o command-line tools. -**StdioMcpTransport** - Implementasyon ng LangChain4j na nagpapatakbo ng MCP server bilang subprocess. +**StdioMcpTransport** - Implementasyon ng LangChain4j na nagpapasimula ng MCP server bilang subprocess. -**Tool Discovery** - Kliyente na nagtatanong sa server para sa mga available na kasangkapan na may mga paglalarawan at schema. +**Tool Discovery** - Kliyente na nagsusuri sa server para sa mga magagamit na tool kasama ang mga paglalarawan at schema. -## Mga Serbisyo ng Azure - [Module 01](../01-introduction/README.md) +## Azure Services - [Module 01](../01-introduction/README.md) -**Azure AI Search** - Cloud search na may vector capabilities. [Module 03](../03-rag/README.md) +**Azure AI Search** - Cloud search na may vector na kakayahan. [Module 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Nagde-deploy ng mga Azure resources. +**Azure Developer CLI (azd)** - Nagde-deploy ng mga Azure resource. -**Azure OpenAI** - Serbisyo ng AI ng Microsoft para sa negosyo. +**Azure OpenAI** - Enterprise AI service ng Microsoft. **Bicep** - Wika para sa Azure infrastructure-as-code. [Infrastructure Guide](../01-introduction/infra/README.md) **Deployment Name** - Pangalan para sa deployment ng modelo sa Azure. -**GPT-5.2** - Pinakabagong modelo ng OpenAI na may kontrol sa pangangatwiran. [Module 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Pinakabagong model ng OpenAI na may kontrol sa pag-iisip. [Module 02](../02-prompt-engineering/README.md) -## Pagsubok at Pag-unlad - [Testing Guide](TESTING.md) +## Testing and Development - [Testing Guide](TESTING.md) -**Dev Container** - Containerized na kapaligiran para sa pag-develop. [Configuration](../../../.devcontainer/devcontainer.json) - -**GitHub Models** - Libreng playground para sa AI models. [Module 00](../00-quick-start/README.md) +**Dev Container** - Containerized na development environment. [Configuration](../../../.devcontainer/devcontainer.json) **In-Memory Testing** - Pagsubok gamit ang in-memory na imbakan. -**Integration Testing** - Pagsubok gamit ang totoong imprastraktura. +**Integration Testing** - Pagsubok gamit ang tunay na imprastraktura. -**Maven** - Tool para sa Java build automation. +**Maven** - Java build automation tool. **Mockito** - Java mocking framework. @@ -227,6 +225,6 @@ Mabilisang sanggunian para sa mga termino at konsepto na ginagamit sa buong kurs --- -**Pagsasabi ng Pananagutan**: -Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI na pagsasalin [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kaming maging tumpak, pakatandaan na ang mga awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o di-katumpakan. Ang orihinal na dokumento sa kanyang orihinal na wika ang dapat ituring na opisyal na sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasaling pantao. Hindi kami mananagot sa anumang hindi pagkakaunawaan o maling interpretasyon na maaaring magmula sa paggamit ng pagsasaling ito. +**Pagtatanggi**: +Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kami para sa katumpakan, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang maling pagkakaintindi o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito. \ No newline at end of file diff --git a/translations/tl/docs/TESTING.md b/translations/tl/docs/TESTING.md index 08e841f00..8c2769702 100644 --- a/translations/tl/docs/TESTING.md +++ b/translations/tl/docs/TESTING.md @@ -1,18 +1,18 @@ -# Pagsusuri ng LangChain4j Applications +# Pagsusuri ng mga Aplikasyon ng LangChain4j ## Talaan ng Nilalaman -- [Mabilis na Pagsisimula](../../../docs) -- [Mga Saklaw ng Pagsusuri](../../../docs) -- [Pagsasagawa ng Mga Pagsusuri](../../../docs) -- [Pagsasagawa ng Mga Pagsusuri sa VS Code](../../../docs) -- [Mga Pattern sa Pagsusuri](../../../docs) -- [Pilosopiya sa Pagsusuri](../../../docs) -- [Mga Susunod na Hakbang](../../../docs) +- [Mabilis na Pagsisimula](#mabilis-na-pagsisimula) +- [Saklaw ng mga Pagsusuri](#saklaw-ng-mga-pagsusuri) +- [Pagpapatakbo ng mga Pagsusuri](#pagpapatakbo-ng-mga-pagsusuri) +- [Pagpapatakbo ng Pagsusuri sa VS Code](#pagpapatakbo-ng-pagsusuri-sa-vs-code) +- [Mga Pattern ng Pagsusuri](#mga-pattern-ng-pagsusuri) +- [Pilosopiya ng Pagsusuri](#pilosopiya-ng-pagsusuri) +- [Mga Susunod na Hakbang](#mga-susunod-na-hakbang) -Ang gabay na ito ay nagpapakita kung paanong susuriin ang mga AI application nang hindi nangangailangan ng mga API key o panlabas na serbisyo. +Ang gabay na ito ay naglalakad sa iyo sa mga pagsusuring nagpapakita kung paano magsuri ng mga AI na aplikasyon nang hindi nangangailangan ng mga susi ng API o panlabas na serbisyo. -## Quick Start +## Mabilis na Pagsisimula Patakbuhin lahat ng pagsusuri gamit ang isang utos: @@ -26,30 +26,29 @@ mvn test mvn --% test ``` -Kapag pumasa ang lahat ng pagsusuri, makikita mo ang output tulad ng screenshot sa ibaba — walang nabigong pagsusuri. +Kapag lahat ng pagsusuri ay pumasa, makikita mo ang output na tulad ng screenshot sa ibaba — walang nabigong pagsusuri. Successful Test Results -*Matagumpay na pagpapatakbo ng pagsusuri na nagpapakita na lahat ay pumasa na walang pagkabigo* +*Matagumpay na pagpapatupad ng pagsusuri na nagpapakita ng lahat ng pagsusuri ay pumapasa na walang kabiguan* -## Mga Saklaw ng Pagsusuri +## Saklaw ng mga Pagsusuri -Ang kursong ito ay nakatuon sa **unit tests** na tumatakbo nang lokal. Bawat pagsusuri ay nagpapakita ng isang tiyak na konsepto ng LangChain4j nang hiwalay. Ipinapakita ng testing pyramid sa ibaba kung saan nababagay ang unit tests — sila ang mabilis at maaasahang pundasyon para sa natitirang bahagi ng iyong test strategy. +Ang kursong ito ay nakatuon sa **unit tests** na tumatakbo lokal. Bawat pagsusuri ay nagpapakita ng isang partikular na konsepto ng LangChain4j nang hiwalay. Ipinapakita ng testing pyramid sa ibaba kung saan nababagay ang mga unit test — bumubuo sila ng mabilis at maaasahang pundasyon na pinagtatayohan ng iyong istratehiya sa pagsusuri. Testing Pyramid -*Pyramid ng pagsusuri na nagpapakita ng balanse sa pagitan ng unit tests (mabilis, hiwalay), integration tests (tunay na mga bahagi), at end-to-end tests. Ang pagsasanay na ito ay tungkol sa unit testing.* +*Testing pyramid na nagpapakita ng balanse sa pagitan ng unit tests (mabilis, hiwalay), integration tests (tunay na mga bahagi), at end-to-end tests. Sakop ng pagsasanay na ito ang unit testing.* | Module | Mga Pagsusuri | Pokus | Pangunahing Mga File | |--------|--------------|-------|---------------------| -| **00 - Quick Start** | 6 | Mga prompt template at variable substitution | `SimpleQuickStartTest.java` | -| **01 - Introduction** | 8 | Memory ng pag-uusap at stateful chat | `SimpleConversationTest.java` | -| **02 - Prompt Engineering** | 12 | Mga pattern ng GPT-5.2, antas ng eagerness, naayos na output | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Pagkuha ng dokumento, embeddings, paghahanap ng pagkakatulad | `DocumentServiceTest.java` | -| **04 - Tools** | 12 | Pagtawag ng function at pagkakabit-kabit ng tool | `SimpleToolsTest.java` | +| **01 - Panimula** | 8 | Memorya ng usapan at stateful chat | `SimpleConversationTest.java` | +| **02 - Prompt Engineering** | 12 | Mga pattern ng GPT-5.2, lebel ng kasigasigan, istrakturang output | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Pag-angkat ng dokumento, embeddings, paghahanap ng pagkakatulad | `DocumentServiceTest.java` | +| **04 - Mga Kasangkapan** | 12 | Pagtawag sa function at chain ng mga kasangkapan | `SimpleToolsTest.java` | | **05 - MCP** | 8 | Model Context Protocol gamit ang Stdio transport | `SimpleMcpTest.java` | -## Pagsasagawa ng Mga Pagsusuri +## Pagpapatakbo ng mga Pagsusuri **Patakbuhin lahat ng pagsusuri mula sa root:** @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Patakbuhin mga pagsusuri para sa isang partikular na module:** +**Patakbuhin ang mga pagsusuri para sa isang partikular na module:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Patakbuhin ang isang klase ng pagsusuri:** +**Patakbuhin ang isang test class:** **Bash:** ```bash @@ -91,7 +90,7 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Patakbuhin ang isang tiyak na pamamaraan ng pagsusuri:** +**Patakbuhin ang isang partikular na test method:** **Bash:** ```bash @@ -100,36 +99,36 @@ mvn test -Dtest=SimpleConversationTest#dapatPanatilihinAngKasaysayanNgPag-uusap **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#dapatPanatilihinAngKasaysayanNgPag-uusap +mvn --% test -Dtest=SimpleConversationTest#dapatPanatilihinAngKasaysayanNgUsapan ``` -## Pagsasagawa ng Mga Pagsusuri sa VS Code +## Pagpapatakbo ng Pagsusuri sa VS Code Kung gumagamit ka ng Visual Studio Code, ang Test Explorer ay nagbibigay ng grapikal na interface para sa pagpapatakbo at pag-debug ng mga pagsusuri. VS Code Test Explorer -*Test Explorer ng VS Code na nagpapakita ng puno ng pagsusuri kasama ang lahat ng Java test classes at mga indibidwal na test methods* +*VS Code Test Explorer na nagpapakita ng puno ng mga pagsusuri kasama ang lahat ng Java test classes at indibidwal na mga test method* **Para patakbuhin ang mga pagsusuri sa VS Code:** 1. Buksan ang Test Explorer sa pamamagitan ng pag-click sa icon ng beaker sa Activity Bar -2. Palawakin ang puno ng pagsusuri para makita lahat ng module at test classes -3. I-click ang play button sa tabi ng anumang pagsusuri upang patakbuhin ito nang paisa-isa +2. Palawakin ang puno ng pagsusuri para makita lahat ng mga module at test classes +3. I-click ang play button sa tabi ng anumang pagsusuri para patakbuhin ito nang paisa-isa 4. I-click ang "Run All Tests" para patakbuhin ang buong suite -5. I-right-click ang anumang pagsusuri at piliin ang "Debug Test" upang mag-set ng breakpoints at i-step through ang code +5. I-right click ang anumang pagsusuri at piliin ang "Debug Test" upang mag-set ng mga breakpoint at sundan ang code -Ipinapakita ng Test Explorer ang mga berdeng checkmark para sa mga pumasa na pagsusuri at nagbibigay ng detalyadong mga mensahe kapag may pumalpak. +Ipinapakita ng Test Explorer ang mga berdeng checkmark para sa mga pumasa na pagsusuri at nagbibigay ng detalyadong mga mensahe kapag may kabiguan ang pagsusuri. -## Mga Pattern sa Pagsusuri +## Mga Pattern ng Pagsusuri -### Pattern 1: Pagsusuri ng Prompt Templates +### Pattern 1: Pagsusuri ng mga Prompt Templates -Ang pinakasimpleng pattern ay sinusuri ang mga prompt template nang hindi tumatawag ng AI model. Tinitiyak mo na gumagana nang maayos ang variable substitution at ang mga prompt ay naiuformat nang tama. +Ang pinakasimpleng pattern ay sinusuri ang mga prompt template nang hindi tumatawag sa anumang AI model. Nini-verify mo na tama ang variable substitution at naka-format nang ayon sa inaasahan ang mga prompt. Prompt Template Testing -*Pagsusuri ng mga prompt template na nagpapakita ng daloy ng variable substitution: template na may placeholders → inilalapat na mga halaga → na-verify na na-format na output* +*Pagsusuri ng mga prompt template na nagpapakita ng daloy ng variable substitution: template na may placeholders → inilalapat na mga halaga → naverify ang naka-format na output* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Ang pagsusuring ito ay nasa `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Sinusuri ng pattern na ito na tama ang variable substitution at naka-format nang tama ang mga prompt — hindi kailangan ng API key o tawag sa model. -**Patakbuhin ito:** +### Pattern 2: Mocking ng mga Language Model -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#pagsubokSaFormatNgPromptTemplate -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#pagsubokNgPromptTemplatePag-aayos -``` - -### Pattern 2: Pagmomock ng mga Language Model - -Kapag sinusuri ang lohika ng pag-uusap, gamitin ang Mockito upang gumawa ng mga pekeng modelo na nagbabalik ng mga naunang idinagdag na tugon. Pinapabilis nito ang mga pagsusuri, libre, at tiyak ang resulta. +Kapag sinusuri ang lohika ng usapan, gamitin ang Mockito para gumawa ng mga pekeng modelo na nagbibigay ng nakatakdang sagot. Ginagawa nitong mabilis, libre, at deterministic ang mga pagsusuri. Mock vs Real API Comparison -*Paghahambing na nagpapakita kung bakit mas gusto ang mocks sa pagsusuri: mabilis sila, libre, tiyak ang resulta, at hindi nangangailangan ng API keys* +*Paghahambing na nagpapakita kung bakit mas gusto ang mga mock para sa pagsusuri: mabilis sila, libre, deterministic, at hindi nangangailangan ng API keys* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Ang pattern na ito ay makikita sa `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Tinitiyak ng mock ang pare-parehong kilos para ma-verify mo na maayos ang pamamahala ng memorya. +Makikita ang pattern na ito sa `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Sini-siguradong consistent ang pag-uugali ng mock upang ma-verify ang tamang pamamahala ng memorya. -### Pattern 3: Pagsusuri ng Isolation ng Pag-uusap +### Pattern 3: Pagsusuri ng Paghiwalay ng Usapan -Dapat panatilihing hiwalay ang memorya ng pag-uusap para sa maraming user. Sinasabing sinusuri nito na hindi nagkakahalo ang mga konteksto ng pag-uusap. +Dapat panatilihing hiwalay ang memorya ng usapan para sa maraming gumagamit. Sinusuri ng test na ito na hindi nagkakahalo ang mga konteksto ng mga usapan. Conversation Isolation -*Pagsusuri ng isolation ng pag-uusap na nagpapakita ng magkakahiwalay na mga imbakan ng memorya para sa iba't ibang user upang maiwasan ang halo ng konteksto* +*Pagsusuri ng paghiwalay ng usapan na nagpapakita ng magkahiwalay na mga memory store para sa iba't ibang gumagamit upang maiwasan ang context mixing* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Bawat pag-uusap ay may sariling independiyenteng kasaysayan. Sa mga production system, kritikal ang ganitong isolation para sa mga multi-user application. +Bawat usapan ay nagpapanatili ng sarili nitong independenteng kasaysayan. Sa mga systema sa produksyon, kritikal ang paghiwalay na ito para sa mga aplikasyon na multi-user. -### Pattern 4: Pagsusuri ng Mga Tools Nang Nakahiwalay +### Pattern 4: Pagsusuri ng mga Kasangkapan nang Hiwa-hiwalay -Ang mga tool ay mga function na pwedeng tawagin ng AI. Subukan ang mga ito nang direkta para matiyak na gumagana sila nang maayos kahit hindi kasali ang AI sa mga desisyon. +Ang mga kasangkapan ay mga function na maaaring tawagin ng AI. Suriin sila nang direkta upang masiguro na gumagana sila nang tama anuman ang mga desisyon ng AI. Tools Testing -*Pagsusuri ng mga tool nang nakahiwalay na nagpapakita ng mock tool execution nang walang tawag sa AI upang ma-verify ang lohika ng negosyo* +*Pagsusuri ng mga kasangkapan nang hiwalay na nagpapakita ng execution ng mock tool nang walang tawag sa AI para masiguro ang lohika ng negosyo* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Ang mga pagsusuring ito mula sa `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ay nag-validate ng logika ng mga tool nang hindi kailangang tumawag sa AI. Ipinapakita ang halimbawa ng chaining kung paano ang output ng isang tool ay pinapasok sa input ng isa pa. +Ang mga pagsusuring ito mula sa `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` ay nagva-validate ng lohika ng tool nang walang pakikialam ng AI. Ipinapakita ng halimbawa ng chaining kung paano pumapasok ang output ng isang tool bilang input ng isa pa. ### Pattern 5: Pagsusuri ng In-Memory RAG -Kadalasang nangangailangan ang RAG ng mga vector database at embedding service. Pinapahintulutan ka ng in-memory pattern na subukan ang buong pipeline nang walang panlabas na dependencies. +Tradisyonal na nangangailangan ang mga RAG system ng vector databases at embedding services. Pinapayagan ka ng in-memory na pattern na suriin ang buong pipeline nang walang panlabas na dependencies. In-Memory RAG Testing -*Workflow ng in-memory RAG testing na nagpapakita ng pag-parse ng dokumento, storage ng embedding, at paghahanap ng pagkakatulad nang hindi kailangan ng database* +*Workflow ng in-memory RAG testing na nagpapakita ng pag-parse ng dokumento, pag-iimbak ng embedding, at paghahanap ng pagkakatulad nang hindi kailangan ng database* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Ang pagsusuring ito mula sa `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` ay lumilikha ng dokumento sa memorya at tine-test ang chunking at metadata handling. +Ang pagsusuri na ito mula sa `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` ay lumilikha ng dokumento sa memorya at sinisigurong tama ang chunking at metadata handling. ### Pattern 6: MCP Integration Testing -Sinusuri ng module ng MCP ang Model Context Protocol integration gamit ang stdio transport. Tine-test nito kung kaya ng iyong application na mag spawn at makipagkomunikasyon sa MCP servers bilang subprocesses. +Sini-suri ng MCP module ang integrasyon ng Model Context Protocol gamit ang stdio transport. Sinusuri nito na kaya ng iyong aplikasyon ang pagsugod at pakikipagkomunikasyon sa MCP servers bilang subprocesses. -Ang mga pagsusuri sa `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` ay nag-va-validate ng ugali ng MCP client. +Ang mga pagsusuri sa `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` ay nagva-validate ng ugali ng MCP client. **Patakbuhin sila:** @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## Pilosopiya sa Pagsusuri +## Pilosopiya ng Pagsusuri -Suriin ang iyong code, hindi ang AI. Ang iyong mga pagsusuri ay dapat magpatunay sa code na sinulat mo sa pamamagitan ng pag-check kung paano ginagawa ang mga prompt, kung paano pinamamahalaan ang memorya, at kung paano gumagana ang mga tool. Nag-iiba-iba ang tugon ng AI kaya hindi ito nararapat sa mga test assertions. Tanungin ang sarili mo kung tama ba ang pagsasa-substitute ng mga variable sa prompt template, hindi kung tama ba ang sagot ng AI. +Suriin ang iyong code, hindi ang AI. Dapat i-validate ng iyong mga pagsusuri ang code na isinulat mo sa pamamagitan ng pag-check kung paano binubuo ang mga prompt, paano pinamamahalaan ang memorya, at paano ipinapatupad ang mga kasangkapan. Nag-iiba-iba ang mga sagot ng AI at hindi dapat bahagi ng test assertions. Tanungin ang iyong sarili kung tama bang napapalitan ang mga variable sa prompt template, hindi kung tama ang sagot ng AI. -Gumamit ng mga mock para sa mga language model. Sila ay mga panlabas na dependencies na mabagal, mahal, at hindi tiyak. Pinapabilis ng mocking ang mga pagsusuri na tumatakbo sa millisecond imbes na segundo, libre nang walang gastos sa API, at deterministic na laging pareho ang resulta. +Gumamit ng mocks para sa mga language model. External dependencies ang mga ito na mabagal, mahal, at hindi deterministic. Ginagawa nitong mabilis ang mga pagsusuri na millisecond lamang ang tagal imbes na segundo, libre na walang gastos sa API, at deterministic ang resulta na pare-pareho sa bawat pagkakataon. -Panatilihing independyente ang mga pagsusuri. Dapat ang bawat pagsusuri ay maghanda ng sarili nitong data, hindi umaasa sa ibang pagsusuri, at naglilinis pagkatapos nito. Dapat pumasa ang mga pagsusuri anuman ang pagkakasunod-sunod ng pagpapatupad. +Panatilihing independent ang mga pagsusuri. Bawat pagsusuri ay dapat mag-set up ng sarili nitong data, hindi umaasa sa ibang pagsusuri, at naglilinis pagkatapos. Dapat pumasa ang mga pagsusuri anuman ang pagkakasunod ng pagpapatupad. -Suriin ang mga edge case lampas sa masayang ginagamit lang. Subukan ang empty inputs, sobrang laki ng inputs, espesyal na mga karakter, invalid na mga parameter, at mga boundary na kondisyon. Madalas itong magbunyag ng mga bug na hindi nakikita sa normal na paggamit. +Suriin ang mga edge case lampas sa masayang landas. Subukan ang mga walang laman na input, napakalaking input, mga espesyal na karakter, invalid na mga parameter, at mga boundary condition. Madalas na inilalantad ng mga ito ang mga bug na hindi nakikita sa normal na paggamit. -Gumamit ng mga deskriptibong pangalan. Ihambing ang `shouldMaintainConversationHistoryAcrossMultipleMessages()` sa `test1()`. Masasabing eksakto kung ano ang susuriin ng una, kaya mas madali ang pag-debug kung may problema. +Gumamit ng mga deskriptibong pangalan. Ihambing ang `shouldMaintainConversationHistoryAcrossMultipleMessages()` sa `test1()`. Ang una ay nagsasabi nang eksakto kung ano ang sinusuri, na nagpapadali ng pag-debug kapag may kabiguan. ## Mga Susunod na Hakbang -Ngayong naintindihan mo na ang mga pattern ng pagsusuri, sumisid nang mas malalim sa bawat module: +Ngayon na naiintindihan mo na ang mga pattern ng pagsusuri, mag-aral nang mas malalim sa bawat module: -- **[00 - Quick Start](../00-quick-start/README.md)** - Simulan sa mga batayan ng prompt template -- **[01 - Introduction](../01-introduction/README.md)** - Matutunan ang pamamahala ng memorya ng pag-uusap -- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Masterin ang mga pattern ng GPT-5.2 na prompt -- **[03 - RAG](../03-rag/README.md)** - Gumawa ng retrieval-augmented generation na mga sistema -- **[04 - Tools](../04-tools/README.md)** - Ipatupad ang pagpatawag ng function at pagkakabit-kabit ng tool -- **[05 - MCP](../05-mcp/README.md)** - Mag-integrate ng Model Context Protocol +- **[01 - Panimula](../01-introduction/README.md)** - Matutunan ang pamamahala ng memorya ng usapan +- **[02 - Prompt Engineering](../02-prompt-engineering/README.md)** - Maging dalubhasa sa mga pattern ng GPT-5.2 prompting +- **[03 - RAG](../03-rag/README.md)** - Bumuo ng retrieval-augmented generation systems +- **[04 - Mga Kasangkapan](../04-tools/README.md)** - Ipatupad ang function calling at mga chain ng kasangkapan +- **[05 - MCP](../05-mcp/README.md)** - Isama ang Model Context Protocol -Nagbibigay ang README ng bawat module ng detalyadong paliwanag tungkol sa mga konseptong sinuri dito. +Nagbibigay ang README ng bawat module ng detalyadong paliwanag ng mga konseptong sinuri dito. --- -**Navigation:** [← Bumalik sa Pangunahing Pahina](../README.md) +**Navigasyon:** [← Babalik sa Pangunahing Pahina](../README.md) --- -**Paalala**: -Ang dokumentong ito ay isinalin gamit ang AI translation service na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagamat nagsisikap kaming maging tumpak, mangyaring tandaan na maaaring may mga pagkakamali o hindi pagkakatugma ang mga awtomatikong salin. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na opisyal na sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang hindi pagkakaunawaan o maling interpretasyon na nagmumula sa paggamit ng pagsasaling ito. +**Pagtatanggi**: +Ang dokumentong ito ay isinalin gamit ang serbisyo ng AI translation na [Co-op Translator](https://github.com/Azure/co-op-translator). Bagama't nagsusumikap kami para sa katumpakan, pakatandaan na ang awtomatikong pagsasalin ay maaaring maglaman ng mga pagkakamali o hindi pagkakatugma. Ang orihinal na dokumento sa orihinal nitong wika ang dapat ituring na pangunahing sanggunian. Para sa mahahalagang impormasyon, inirerekomenda ang propesyonal na pagsasalin ng tao. Hindi kami mananagot sa anumang maling pagkakaintindi o maling interpretasyon na nagmula sa paggamit ng pagsasaling ito. \ No newline at end of file diff --git a/translations/tr/.co-op-translator.json b/translations/tr/.co-op-translator.json index 609fd7e47..6f4439caf 100644 --- a/translations/tr/.co-op-translator.json +++ b/translations/tr/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "tr" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T21:47:44+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T10:45:45+00:00", "source_file": "01-introduction/README.md", "language_code": "tr" }, @@ -18,20 +18,20 @@ "language_code": "tr" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T21:49:39+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T10:41:54+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "tr" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T21:50:48+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T10:44:58+00:00", "source_file": "03-rag/README.md", "language_code": "tr" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:57:50+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T10:43:51+00:00", "source_file": "04-tools/README.md", "language_code": "tr" }, @@ -54,8 +54,8 @@ "language_code": "tr" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T16:05:42+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T10:40:47+00:00", "source_file": "README.md", "language_code": "tr" }, @@ -72,14 +72,14 @@ "language_code": "tr" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T21:53:27+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T10:42:18+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "tr" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T21:54:11+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T10:42:51+00:00", "source_file": "docs/TESTING.md", "language_code": "tr" } diff --git a/translations/tr/00-quick-start/README.md b/translations/tr/00-quick-start/README.md deleted file mode 100644 index ad2b50b8d..000000000 --- a/translations/tr/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Modül 00: Hızlı Başlangıç - -## İçindekiler - -- [Giriş](../../../00-quick-start) -- [LangChain4j Nedir?](../../../00-quick-start) -- [LangChain4j Bağımlılıkları](../../../00-quick-start) -- [Önkoşullar](../../../00-quick-start) -- [Kurulum](../../../00-quick-start) - - [1. GitHub Token'inizi Alın](../../../00-quick-start) - - [2. Token'inizi Ayarlayın](../../../00-quick-start) -- [Örnekleri Çalıştırın](../../../00-quick-start) - - [1. Temel Sohbet](../../../00-quick-start) - - [2. İstem Kalıpları](../../../00-quick-start) - - [3. Fonksiyon Çağrısı](../../../00-quick-start) - - [4. Doküman Soru-Cevap (Kolay RAG)](../../../00-quick-start) - - [5. Sorumlu Yapay Zeka](../../../00-quick-start) -- [Her Örnek Ne Gösterir](../../../00-quick-start) -- [Sonraki Adımlar](../../../00-quick-start) -- [Sorun Giderme](../../../00-quick-start) - -## Giriş - -Bu hızlı başlangıç, LangChain4j ile mümkün olan en hızlı şekilde çalışmaya başlamanızı sağlamak için tasarlanmıştır. LangChain4j ve GitHub Modelleri ile AI uygulamaları oluşturmanın en temel noktalarını kapsar. Sonraki modüllerde Azure OpenAI ve GPT-5.2'ye geçecek ve her konsepte daha derinlemesine dalacaksınız. - -## LangChain4j Nedir? - -LangChain4j, AI destekli uygulamalar oluşturmayı basitleştiren bir Java kütüphanesidir. HTTP istemcileri ve JSON ayrıştırmayla uğraşmak yerine, temiz Java API'leri ile çalışırsınız. - -LangChain'deki "zincir", birden çok bileşeni birbirine bağlamayı ifade eder — bir istemi modele, modele ayrıştırıcıya bağlayabilir veya bir çıktı diğer girdiye beslenen ardışık AI çağrıları zinciri oluşturabilirsiniz. Bu hızlı başlangıç, daha karmaşık zincirleri keşfetmeden önce temel kavramlara odaklanır. - -LangChain4j Zincirleme Konsepti - -*LangChain4j'de bileşenlerin zincirlenmesi - güçlü AI iş akışları oluşturmak için yapı taşları bağlanıyor* - -Üç temel bileşen kullanacağız: - -**ChatModel** - AI model etkileşimleri için arayüz. `model.chat("prompt")` çağırarak yanıt dizesi alırsınız. OpenAI uyumlu uç noktalarla çalışan `OpenAiOfficialChatModel` kullanıyoruz, örneğin GitHub Modelleri gibi. - -**AiServices** - Tür güvenli AI servis arayüzleri oluşturur. Yöntemlerinizi tanımlayıp `@Tool` ile işaretlersiniz, LangChain4j orkestrasyonu halleder. AI gerektiğinde Java yöntemlerinizi otomatik çağırır. - -**MessageWindowChatMemory** - Konuşma geçmişini korur. Bunu kullanmazsanız, her istek bağımsızdır. Kullanırsanız, AI önceki mesajları hatırlar ve birden fazla turda bağlamı sürdürür. - -LangChain4j Mimarisi - -*LangChain4j mimarisi - AI uygulamalarınızı çalıştırmak için birlikte çalışan temel bileşenler* - -## LangChain4j Bağımlılıkları - -Bu hızlı başlangıç, [`pom.xml`](../../../00-quick-start/pom.xml) dosyasında üç Maven bağımlılığı kullanır: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` modülü, OpenAI uyumlu API’lara bağlanan `OpenAiOfficialChatModel` sınıfını sağlar. GitHub Modelleri aynı API formatını kullanır, bu yüzden özel bir adaptöre gerek yoktur — sadece temel URL’yi `https://models.github.ai/inference` olarak ayarlayın. - -`langchain4j-easy-rag` modülü, otomatik doküman bölme, gömme ve getirme sağlar; böylece RAG uygulamalarını her adımı manuel yapılandırmadan oluşturabilirsiniz. - -## Önkoşullar - -**Geliştirici Konteyneri Kullanıyor musunuz?** Java ve Maven önceden yüklüdür. Sadece bir GitHub Kişisel Erişim Token’ına ihtiyacınız var. - -**Yerel Geliştirme:** -- Java 21+, Maven 3.9+ -- GitHub Kişisel Erişim Token’ı (aşağıdaki talimatlara bakınız) - -> **Not:** Bu modül GitHub Modelleri’nden `gpt-4.1-nano` kullanır. Kodda model adını değiştirmeyin — GitHub’ın mevcut modellerine göre yapılandırılmıştır. - -## Kurulum - -### 1. GitHub Token'inizi Alın - -1. [GitHub Ayarları → Kişisel Erişim Token’ları](https://github.com/settings/personal-access-tokens) sayfasına gidin -2. "Yeni token oluştur" seçeneğine tıklayın -3. Anlamlı bir isim verin (ör. "LangChain4j Demo") -4. Süre bitişini ayarlayın (7 gün önerilir) -5. "Hesap izinleri" altında "Modeller"i bulun ve "Yalnızca okuma" olarak ayarlayın -6. "Token oluştur" tuşuna basın -7. Token’i kopyalayın ve kaydedin — bir daha göremezsiniz - -### 2. Token'inizi Ayarlayın - -**Seçenek 1: VS Code Kullanarak (Önerilir)** - -VS Code kullanıyorsanız, projenin kök dizinindeki `.env` dosyasına token’inizi ekleyin: - -Eğer `.env` dosyası yoksa, `.env.example` dosyasını `.env` olarak kopyalayın veya yeni bir `.env` dosyası oluşturun. - -**Örnek `.env` dosyası:** -```bash -# /workspaces/LangChain4j-for-Beginners/.env dosyasında -GITHUB_TOKEN=your_token_here -``` - -Ardından Explorer’da herhangi bir demo dosyasına (örneğin `BasicChatDemo.java`) sağ tıklayıp **"Java'yı Çalıştır"** seçeneğini seçebilir ya da Çalıştır ve Hata Ayıkla panelindeki başlatma yapılandırmalarını kullanabilirsiniz. - -**Seçenek 2: Terminal Kullanarak** - -Token’i ortam değişkeni olarak ayarlayın: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Örnekleri Çalıştırın - -**VS Code Kullanıyorsanız:** Explorer’da herhangi bir demo dosyasına sağ tıklayıp **"Java'yı Çalıştır"** deyin ya da token’inizi `.env` dosyasına ekledikten sonra Çalıştır ve Hata Ayıkla panelindeki başlatma yapılandırmalarını kullanın. - -**Maven Kullanarak:** Alternatif olarak komut satırından çalıştırabilirsiniz: - -### 1. Temel Sohbet - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. İstem Kalıpları - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Sıfır atış, birkaç atış, düşünce zinciri ve rol bazlı istemleri gösterir. - -### 3. Fonksiyon Çağrısı - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI gerekli olduğunda Java yöntemlerinizi otomatik çağırır. - -### 4. Doküman Soru-Cevap (Kolay RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Otomatik gömme ve getirme ile Easy RAG kullanarak belgeleriniz hakkında sorular sorun. - -### 5. Sorumlu Yapay Zeka - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -AI güvenlik filtrelerinin zararlı içeriği nasıl engellediğini görün. - -## Her Örnek Ne Gösterir - -**Temel Sohbet** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Buradan başlayarak LangChain4j'nin en basit haliyle nasıl çalıştığını görün. Bir `OpenAiOfficialChatModel` oluşturup `.chat()` ile istem gönderir, yanıt alırsınız. Bu, özel uç noktalar ve API anahtarları ile model başlatmanın temelini gösterir. Bu kalıbı anladıktan sonra diğer her şey bunun üzerine kurulur. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) dosyasını açın ve sorun: -> - "Bu kodda GitHub Modellerinden Azure OpenAI'ye nasıl geçiş yaparım?" -> - "OpenAiOfficialChatModel.builder() içinde hangi diğer parametreleri yapılandırabilirim?" -> - "Tam yanıtı beklemek yerine akışlı yanıt nasıl eklenir?" - -**İstem Mühendisliği** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Artık moda nasıl konuşulacağını biliyorsunuz, şimdi ona ne söylediğinizi keşfedelim. Bu demo aynı model kurulumunu kullanır ama beş farklı istem kalıbı gösterir. Doğrudan talimatlar için sıfır atış, örneklerden öğrenmek için birkaç atış, mantık adımlarını gösteren düşünce zinciri ve bağlam ayarlayan rol bazlı istemleri deneyin. Aynı modelin istek şeklini nasıl dramatik şekilde etkilediğini göreceksiniz. - -Demo ayrıca değişkenlerle tekrar kullanılabilir istemler oluşturmak için güçlü bir yöntem olan istem şablonlarını gösterir. -Aşağıdaki örnek, LangChain4j `PromptTemplate` kullanarak değişkenleri dolduran bir istemi gösterir. AI sağlanan varış noktası ve aktiviteye göre yanıtlar. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) dosyasını açın ve sorun: -> - "Sıfır atış ve birkaç atış istem arasındaki fark nedir ve her biri ne zaman kullanılmalı?" -> - "Sıcaklık parametresi modelin yanıtlarını nasıl etkiler?" -> - "Üretimde istem enjeksiyonu saldırılarını önlemek için hangi teknikler var?" -> - "Yaygın kalıplar için tekrar kullanılabilir PromptTemplate nesneleri nasıl oluşturabilirim?" - -**Araç Entegrasyonu** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -LangChain4j’nin gücü burada ortaya çıkar. `AiServices` kullanarak Java yöntemlerinizi çağırabilen bir AI asistanı oluşturacaksınız. Yöntemlere sadece `@Tool("açıklama")` eklemeniz yeterli, LangChain4j gerisini halleder — AI kullanıcının ne istediğine göre hangi aracı ne zaman kullanacağına otomatik karar verir. Bu, sadece soru cevaplamakla kalmayıp, hareket edebilen AI oluşturmak için kilit bir teknik olan fonksiyon çağrısını gösterir. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) dosyasını açın ve sorun: -> - "@Tool açıklaması nasıl çalışır ve LangChain4j arka planda bununla ne yapar?" -> - "AI, karmaşık problemleri çözmek için birden çok aracı ardışık olarak çağırabilir mi?" -> - "Bir araç istisna atarsa ne olur - hataları nasıl ele almalıyım?" -> - "Bu hesap makinesi örneği yerine gerçek bir API'yi nasıl entegre ederim?" - -**Doküman Soru-Cevap (Kolay RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Burada LangChain4j "Easy RAG" yaklaşımıyla RAG (getirme destekli üretim) görüyorsunuz. Dokümanlar yüklenir, otomatik olarak ayrılır ve bellek içi depolamaya gömülür, ardından içerik getirici sorgu anında AI’ye ilgili parçaları sağlar. AI yanıtları genel bilgisinden değil, belgelerinize dayanır. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) dosyasını açın ve sorun: -> - "RAG, modelin eğitim verilerine kıyasla AI halüsinasyonlarını nasıl önler?" -> - "Bu kolay yaklaşım ile özel RAG hattı arasındaki fark nedir?" -> - "Bunu birden fazla doküman veya daha büyük bilgi tabanlarını destekleyecek şekilde nasıl ölçeklendiririm?" - -**Sorumlu Yapay Zeka** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Derin savunma ile AI güvenliği inşa edin. Bu demo birlikte çalışan iki koruma katmanını gösterir: - -**Bölüm 1: LangChain4j Giriş Koruma Kuralları** - Tehlikeli istemler LLM’ye ulaşmadan önce engellenir. Yasaklı anahtar kelimeleri ya da kalıpları kontrol eden özel kurallar oluşturun. Bunlar kodunuzda çalışır, hızlı ve ücretsizdir. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Bölüm 2: Sağlayıcı Güvenlik Filtreleri** - GitHub Modelleri yerleşik filtrelere sahiptir; kurallarınızın kaçırdığı durumları yakalar. Ciddi ihlaller için sert engeller (HTTP 400 hataları) ve AI’nin kibarca reddettiği yumuşak retler görürsünüz. - -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) dosyasını açın ve sorun: -> - "InputGuardrail nedir ve kendi kurallarımı nasıl oluştururum?" -> - "Sert engelleme ile yumuşak red arasındaki fark nedir?" -> - "Neden hem koruma kuralları hem de sağlayıcı filtreleri birlikte kullanmalıyım?" - -## Sonraki Adımlar - -**Sonraki Modül:** [01-giriş - LangChain4j ile Başlarken](../01-introduction/README.md) - ---- - -**Geçiş:** [← Ana Sayfaya Dön](../README.md) | [İleri: Modül 01 - Giriş →](../01-introduction/README.md) - ---- - -## Sorun Giderme - -### İlk Defa Maven Derleme - -**Sorun:** İlk `mvn clean compile` veya `mvn package` uzun sürüyor (10-15 dakika) - -**Sebep:** Maven, ilk derlemede tüm proje bağımlılıklarını (Spring Boot, LangChain4j kütüphaneleri, Azure SDK’ları vb.) indiriyor. - -**Çözüm:** Bu normaldir. Sonraki derlemeler daha hızlı olur çünkü bağımlılıklar yerelde önbelleğe alınır. İndirme süresi ağ hızınıza bağlıdır. - -### PowerShell Maven Komut Sözdizimi - -**Sorun:** Maven komutları `Unknown lifecycle phase ".mainClass=..."` hatası veriyor -**Neden**: PowerShell, `=` işaretini bir değişken atama operatörü olarak yorumlar ve bu durum Maven özellik sözdizimini bozar. - -**Çözüm**: Maven komutundan önce durdurma-ayrıştırma operatörü `--%` kullanın: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` operatörü, PowerShell'e kalan tüm argümanları yorum yapmadan doğrudan Maven'a iletmesini söyler. - -### Windows PowerShell Emoji Görüntüleme - -**Sorun**: AI yanıtları PowerShell'de emojiler yerine bozuk karakterler (örneğin, `????` veya `â??`) gösteriyor - -**Neden**: PowerShell'in varsayılan kodlaması UTF-8 emojilerini desteklemiyor - -**Çözüm**: Java uygulamalarını çalıştırmadan önce bu komutu kullanın: -```cmd -chcp 65001 -``` - -Bu, terminalde UTF-8 kodlamasını zorlar. Alternatif olarak, daha iyi Unicode desteği olan Windows Terminal'i kullanabilirsiniz. - -### API Çağrılarının Hata Ayıklanması - -**Sorun**: AI modelinden kimlik doğrulama hataları, hız sınırları veya beklenmeyen yanıtlar - -**Çözüm**: Örneklerde `.logRequests(true)` ve `.logResponses(true)` kullanılmıştır; bu, API çağrılarının konsolda görünmesini sağlar. Bu, kimlik doğrulama hatalarını, hız sınırlarını veya beklenmeyen yanıtları çözmeye yardımcı olur. Üretim ortamında bu bayrakları kaldırarak günlük gürültüsünü azaltın. - ---- - - -**Feragatname**: -Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluğa özen göstersek de, otomatik çevirilerin hatalar veya yanlışlıklar içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı nedeniyle oluşabilecek yanlış anlamalar veya hatalı yorumlamalardan sorumlu değiliz. - \ No newline at end of file diff --git a/translations/tr/01-introduction/README.md b/translations/tr/01-introduction/README.md index 17e56bd3b..9d2ef6add 100644 --- a/translations/tr/01-introduction/README.md +++ b/translations/tr/01-introduction/README.md @@ -1,87 +1,87 @@ -# Modül 01: LangChain4j ile Başlarken +# Modül 01: LangChain4j ile Başlangıç ## İçindekiler -- [Video Turu](../../../01-introduction) -- [Öğrenecekleriniz](../../../01-introduction) -- [Ön Koşullar](../../../01-introduction) -- [Temel Problemi Anlamak](../../../01-introduction) -- [Token'ları Anlamak](../../../01-introduction) -- [Bellek Nasıl Çalışır](../../../01-introduction) -- [Bunun LangChain4j ile Kullanımı](../../../01-introduction) -- [Azure OpenAI Altyapısını Yayınla](../../../01-introduction) -- [Uygulamayı Yerel Olarak Çalıştır](../../../01-introduction) -- [Uygulamanın Kullanımı](../../../01-introduction) - - [Durumsuz Sohbet (Sol Panel)](../../../01-introduction) - - [Durumlu Sohbet (Sağ Panel)](../../../01-introduction) -- [Sonraki Adımlar](../../../01-introduction) +- [Video Yürütme](#video-yürütme) +- [Öğrenecekleriniz](#öğrenecekleriniz) +- [Gereksinimler](#gereksinimler) +- [Temel Problemi Anlamak](#temel-problemi-anlamak) +- [Tokenları Anlamak](#tokenları-anlamak) +- [Belleğin Nasıl Çalıştığı](#belleğin-nasıl-çalıştığı) +- [LangChain4j Nasıl Kullanılır](#langchain4j-nasıl-kullanılır) +- [Azure OpenAI Altyapısını Dağıtmak](#azure-openai-altyapısını-dağıtmak) +- [Uygulamayı Yerel Olarak Çalıştırmak](#uygulamayı-yerel-olarak-çalıştırmak) +- [Uygulamayı Kullanmak](#uygulamayı-kullanmak) + - [Durumsuz Sohbet (Sol Panel)](#durumsuz-sohbet-sol-panel) + - [Durumlu Sohbet (Sağ Panel)](#durumlu-sohbet-sağ-panel) +- [Sonraki Adımlar](#sonraki-adımlar) -## Video Turu +## Video Yürütme -Bu modüle nasıl başlanacağını anlatan canlı oturumu izleyin: +Bu modülle nasıl başlayacağınızı anlatan canlı oturumu izleyin: -LangChain4j ile Başlarken - Canlı Oturum +LangChain4j ile Başlangıç - Canlı Oturum ## Öğrenecekleriniz -Hızlı başlangıçta, GitHub Modellerini kullanarak istemler gönderdiniz, araçları çağırdınız, bir RAG hattı kurdunuz ve güvenlik sınırlarını test ettiniz. Bu demolar olanakları gösterdi — şimdi Azure OpenAI ve GPT-5.2'ye geçip üretim tarzı uygulamalar geliştirmeye başlıyoruz. Bu modül, bağlamı hatırlayan ve durumu koruyan konuşma yapay zekasına odaklanıyor — hızlı başlangıç demolarının perde arkasında kullandığı ama açıklamadığı kavramlar. +LangChain4j ve Azure OpenAI ile başlangıç noktanız burasıdır. Temellerle başlıyoruz ve üretim tarzı uygulamalar geliştirmeye başlayacağız. Bu modül, bağlamı hatırlayan ve durumu koruyan konuşma yapay zekasına odaklanır — tüm sonraki modüllerin üzerine inşa edildiği temel kavramlar. -Bu kılavuz boyunca Azure OpenAI'nin GPT-5.2'sini kullanacağız çünkü gelişmiş akıl yürütme yetenekleri farklı desenlerin davranışlarını daha belirgin kılıyor. Bellek eklediğinizde farkı açıkça göreceksiniz. Bu, uygulamanıza her bir bileşenin ne kattığını anlamayı kolaylaştırır. +Bu rehber boyunca Azure OpenAI'nin GPT-5.2 modelini kullanacağız çünkü gelişmiş çıkarım yetenekleri farklı desenlerin davranışlarını daha açık hale getiriyor. Bellek eklediğinizde farkı net bir şekilde göreceksiniz. Bu, her bileşenin uygulamanıza neler kattığını anlamayı kolaylaştırır. -Her iki deseni gösteren bir uygulama geliştireceksiniz: +Her iki deseni de gösteren tek bir uygulama geliştireceksiniz: -**Durumsuz Sohbet** - Her istek bağımsız. Model önceki mesajları hatırlamaz. Hızlı başlangıçta kullandığınız desen budur. +**Durumsuz Sohbet** - Her istek bağımsızdır. Model önceki mesajları hatırlamaz. Bu en basit başlangıç noktasıdır. -**Durumlu Konuşma** - Her istek, konuşma geçmişini içerir. Model birden fazla adımlı konuşmada bağlamı korur. Üretim uygulamalarının gerektirdiği budur. +**Durumlu Konuşma** - Her istek konuşma geçmişini içerir. Model birden fazla tur boyunca bağlamı korur. Üretim uygulamalarının ihtiyacı budur. -## Ön Koşullar +## Gereksinimler -- Azure aboneliği ve Azure OpenAI erişimi -- Java 21, Maven 3.9+ +- Azure OpenAI erişimi olan Azure aboneliği +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Not:** Java, Maven, Azure CLI ve Azure Developer CLI (azd) sağlanan geliştirme konteynerinde önceden yüklüdür. +> **Not:** Java, Maven, Azure CLI ve Azure Developer CLI (azd), sağlanan geliştirme konteynerinde önceden yüklüdür. -> **Not:** Bu modül Azure OpenAI üzerinde GPT-5.2 kullanır. Dağıtım `azd up` ile otomatik yapılandırılır — koddaki model adını değiştirmeyin. +> **Not:** Bu modül Azure OpenAI üzerinde GPT-5.2 modelini kullanır. Dağıtım `azd up` ile otomatik yapılandırılır - kodda model adını değiştirmeyin. ## Temel Problemi Anlamak -Dil modelleri durumsuzdur. Her API çağrısı bağımsızdır. "Adım John" dediğinizde ve sonra "Adım ne?" diye sorduğunuzda, model kendinizi tanıttığınızı bilmez. Her isteği yaşayabileceğiniz ilk konuşma gibi değerlendirir. +Dil modelleri durumsuzdur. Her API çağrısı bağımsızdır. "Benim adım John" yazdıktan sonra "Adım ne?" diye sorarsanız, model kendinizi yeni tanıttığınızın farkında değildir. Her isteği, yaptığınız ilk konuşma gibi ele alır. -Bu, basit soru-cevaplar için sorun olmaz ancak gerçek uygulamalar için işe yaramaz. Müşteri hizmeti botları size söylediklerinizi hatırlamalıdır. Kişisel asistanlar bağlama ihtiyaç duyar. Her çok adımlı konuşma belleğe ihtiyaç duyar. +Bu basit soru-cevap için uygundur ancak gerçek uygulamalar için işe yaramaz. Müşteri hizmetleri botlarının söylediklerinizi hatırlaması gerekir. Kişisel asistanlar bağlama ihtiyaç duyar. Her çok turlu konuşma belleğe ihtiyaç duyar. -Aşağıdaki diagram iki yaklaşımı karşılaştırır — solda, isminizi unutan durumsuz çağrı; sağda ise isminizi hatırlayan ChatMemory destekli durumlu çağrı. +Aşağıdaki diyagram bu iki yaklaşımı karşılaştırır — solda isminizi unutan durumsuz çağrı; sağda isminizi hatırlayan ChatMemory destekli durumlu çağrı. -Durumsuz ve Durumlu Konuşmalar +Durumsuz vs Durumlu Konuşmalar -*Durumsuz (bağımsız çağrılar) ve durumlu (bağlam farkında) konuşmalar arasındaki fark* +*Durumsuz (bağımsız çağrılar) ile durumlu (bağlam farkında) konuşmalar arasındaki fark* -## Token'ları Anlamak +## Tokenları Anlamak -Konuşmalara dalmadan önce, dil modellerinin işlediği temel metin birimleri olan token’ları anlamak önemlidir: +Konuşmaya girmeden önce, dil modellerinin işlediği temel birimler olan tokenları anlamak önemlidir: Token Açıklaması -*Metnin token’lara nasıl bölündüğüne örnek - "I love AI!" 4 ayrı işleme birimine dönüşür* +*Metnin tokenlere nasıl bölündüğüne örnek - "I love AI!" dört ayrı işlem birimine dönüşür* -Token’lar yapay zeka modellerinin metni ölçme ve işleme yöntemidir. Kelimeler, noktalama işaretleri ve hatta boşluklar token olabilir. Modelinizin bir kerede işleyebileceği token sayısı sınırlıdır (GPT-5.2 için 400.000, 272.000 giriş token’ı ve 128.000 çıkış token’ı ile). Token’ları anlamak konuşma uzunluğunu ve maliyetleri yönetmenize yardımcı olur. +Tokenlar, yapay zeka modellerinin metni ölçme ve işleme yoludur. Kelimeler, noktalama işaretleri ve hatta boşluklar token olabilir. Modelinizin aynı anda işleyebileceği token sayısının bir limiti vardır (GPT-5.2 için 400.000, girişte 272.000 ve çıkışta 128.000 tokena kadar). Tokenları anlamak, konuşma uzunluğunu ve maliyetleri yönetmenize yardımcı olur. -## Bellek Nasıl Çalışır +## Belleğin Nasıl Çalıştığı -Konuşma belleği, durumsuz problemi, konuşma geçmişini koruyarak çözer. Modele isteğinizi göndermeden önce, çerçeve ilgili önceki mesajları başa ekler. "Adım ne?" diye sorduğunuzda, sistem tüm konuşma geçmişini gönderir; böylece model sizin daha önce "Adım John" dediğinizi görür. +Chat belleği, durumsuz problemi çözerek konuşma geçmişini korur. İsteğinizi modele göndermeden önce çerçeve, ilgili önceki mesajları başa ekler. "Adım ne?" diye sorduğunuzda, sistem tüm konuşma geçmişini gönderir, böylece model önceden "Benim adım John" dediğinizi görebilir. -LangChain4j bunu otomatik yapan bellek uygulamaları sağlar. Kaç mesaj korunacağını siz seçersiniz, çerçeve bağlam penceresini yönetir. Aşağıdaki diagram MessageWindowChatMemory’nin yakın zamandaki mesajların kayan penceresini nasıl yönettiğini gösterir. +LangChain4j, bunu otomatik olarak yöneten bellek uygulamaları sağlar. Kaç mesajı saklayacağınızı seçersiniz ve çerçeve bağlam penceresini yönetir. Aşağıdaki diyagram, MessageWindowChatMemory’nin nasıl kaydırmalı bir pencereyle yakın tarihli mesajları tuttuğunu gösterir. -Bellek Penceresi Kavramı +Bellek Penceresi Konsepti -*MessageWindowChatMemory, eski mesajları otomatik atarak yakın zamandaki mesajlar için kayan bir pencere tutar* +*MessageWindowChatMemory, kaydırmalı pencere ile yakın tarihli mesajları tutar, eski mesajları otomatik olarak düşürür* -## Bunun LangChain4j ile Kullanımı +## LangChain4j Nasıl Kullanılır -Bu modül, hızlı başlangıcı genişleterek Spring Boot entegrasyonu ve konuşma belleği ekler. Parçalar şu şekilde birleşir: +Bu modül Spring Boot’u entegre eder ve konuşma belleği ekler. Parçalar şöyle işler: -**Bağımlılıklar** — İki LangChain4j kütüphanesi ekleyin: +**Bağımlılıklar** - İki LangChain4j kütüphanesi ekleyin: ```xml @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder, `azd up` ile ayarlanmış ortam değişkenlerinden kimlik bilgilerini okur. `baseUrl`’i Azure uç noktanıza ayarlamak, OpenAI istemcisinin Azure OpenAI ile çalışmasını sağlar. +Builder, `azd up` ile ayarlanmış ortam değişkenlerinden kimlik bilgilerini okur. `baseUrl` adresini Azure uç noktanıza ayarlamak, OpenAI istemcisinin Azure OpenAI ile çalışmasını sağlar. -**Konuşma Belleği** - Mesaj geçmişini MessageWindowChatMemory ile izleyin ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Konuşma Belleği** - MessageWindowChatMemory ile sohbet geçmişini takip edin ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,21 +124,21 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` ile belleği son 10 mesajı tutacak şekilde oluşturun. Kullanıcı ve yapay zeka mesajlarını tipli sarmalayıcılarla ekleyin: `UserMessage.from(text)` ve `AiMessage.from(text)`. Geçmişi `memory.messages()` ile alın ve modele gönderin. Servis, her konuşma kimliği için ayrı bellek örnekleri tutar; böylece birden çok kullanıcı aynı anda sohbet edebilir. +`withMaxMessages(10)` ile son 10 mesajı tutan belleği oluşturun. Kullanıcı ve yapay zeka mesajlarını `UserMessage.from(text)` ve `AiMessage.from(text)` tipleriyle ekleyin. Geçmişi `memory.messages()` ile alın ve modele gönderin. Servis, her konuşma kimliği için ayrı bellek örnekleri tutar, böylece birden çok kullanıcı aynı anda sohbet edebilir. -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) dosyasını açın ve sorun: -> - "MessageWindowChatMemory pencere dolduğunda hangi mesajların atılmasına nasıl karar veriyor?" -> - "Belleği bellek içi yerine veritabanı kullanarak özel olarak nasıl uygularım?" -> - "Eski konuşma geçmişini sıkıştırmak için özetlemeyi nasıl eklerim?" +> **🤖 GitHub Copilot Chat ile deneyin:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) dosyasını açıp sorun: +> - "Pencere dolduğunda MessageWindowChatMemory hangi mesajları bırakmaya karar veriyor?" +> - "In-memory yerine veritabanı kullanarak özel bellek depolaması yapabilir miyim?" +> - "Eski konuşma geçmişini sıkıştırmak için özetleme nasıl eklenir?" -Durumsuz sohbet uç noktası belleği tamamen atlar — hızlı başlangıçta olduğu gibi sadece `chatModel.chat(prompt)`. Durumlu uç noktada mesajlar belleğe eklenir, geçmiş alınır ve her istekle o bağlam dahil edilir. Aynı model yapılandırması, farklı desenler. +Durumsuz sohbet uç noktası belleği tamamen atlar — sadece `chatModel.chat(prompt)` çağrısı yapılır, hızlı başlangıç gibi. Durumlu uç nokta, mesajları belleğe ekler, geçmişi alır ve bu bağlamı her istekle dahil eder. Aynı model yapılandırması, farklı desenler. -## Azure OpenAI Altyapısını Yayınla +## Azure OpenAI Altyapısını Dağıtmak **Bash:** ```bash cd 01-introduction -azd up # Abonelik ve konumu seçin (eastus2 önerilir) +azd up # Aboneliği ve konumu seçin (eastus2 önerilir) ``` **PowerShell:** @@ -147,28 +147,28 @@ cd 01-introduction azd up # Aboneliği ve konumu seçin (eastus2 önerilir) ``` -> **Not:** Eğer zaman aşımı hatası (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) alırsanız, `azd up` komutunu tekrar çalıştırın. Azure kaynakları arka planda hâlâ dağıtılıyor olabilir; yeniden denemek, kaynaklar terminal duruma geldiğinde dağıtımın tamamlanmasını sağlar. +> **Not:** Eğer zaman aşımı hatası (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) ile karşılaşırsanız, `azd up` komutunu yeniden çalıştırın. Azure kaynakları arka planda hala hazırlanıyor olabilir, tekrar denemek dağıtımın kaynaklar terminal durumuna ulaştığında tamamlanmasını sağlar. -Bu işlemler: +Bu işlem: 1. GPT-5.2 ve text-embedding-3-small modelleriyle Azure OpenAI kaynağı dağıtır -2. Proje kökünde kimlik bilgileriyle `.env` dosyasını otomatik oluşturur +2. Proje kökünde kimlik bilgileri içeren `.env` dosyasını otomatik oluşturur 3. Gerekli tüm ortam değişkenlerini ayarlar -**Dağıtım sorunları mı yaşıyorsunuz?** Alt alan adı adı çatışmaları, manuel Azure Portal dağıtım adımları ve model yapılandırma rehberi dahil ayrıntılı hata giderme için [Altyapı README dosyasına](infra/README.md) bakın. +**Dağıtım sorunları mı yaşıyorsunuz?** Alt alan adı çakışmaları, manuel Azure Portal dağıtımı ve model yapılandırma rehberleri için [Altyapı README dosyasına](infra/README.md) bakın. -**Dağıtımın başarılı olup olmadığını doğrulayın:** +**Dağıtımın başarılı olduğunu doğrulayın:** **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, vb. gösterilmelidir. +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, vb. göstermelidir. ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY vb. gösterilmelidir. +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY vb. gösterilmeli ``` -> **Not:** `azd up` komutu `.env` dosyasını otomatik oluşturur. Daha sonra güncellemeniz gerekirse, `.env` dosyasını manuel olarak düzenleyebilir veya yeniden oluşturmak için şu komutları çalıştırabilirsiniz: +> **Not:** `azd up` komutu `.env` dosyasını otomatik oluşturur. Daha sonra güncellemeniz gerekirse, ya `.env` dosyasını manuel düzenleyebilir ya da aşağıdaki komutla yeniden oluşturabilirsiniz: > > **Bash:** > ```bash @@ -182,11 +182,11 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY vb. gösterilmelidir. > .\.azd-env.ps1 > ``` -## Uygulamayı Yerel Olarak Çalıştır +## Uygulamayı Yerel Olarak Çalıştırmak **Dağıtımı doğrulayın:** -Azure kimlik bilgileriyle `.env` dosyasının kök dizinde olduğundan emin olun. Modül dizininden (`01-introduction/`) şu komutları çalıştırın: +Azure kimlik bilgileriyle `.env` dosyasının kök dizinde olduğundan emin olun. Bu komutu modül dizininden (`01-introduction/`) çalıştırın: **Bash:** ```bash @@ -200,25 +200,25 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT göstermeli **Uygulamaları başlatın:** -**Seçenek 1: Spring Boot Dashboard kullanımı (VS Code kullanıcıları için önerilir)** +**Seçenek 1: Spring Boot Dashboard Kullanarak (VS Code kullanıcıları için önerilir)** -Geliştirme konteynerinde, tüm Spring Boot uygulamalarını görsel olarak yönetmek için Spring Boot Dashboard eklentisi vardır. VS Code’un solundaki Aktivite Çubuğunda (Spring Boot simgesini arayın) bulunabilir. +Geliştirme konteyneri, tüm Spring Boot uygulamalarını yönetmek için görsel arayüz sağlayan Spring Boot Dashboard uzantısını içerir. VS Code'da sol taraftaki Aktivite Çubuğunda (Spring Boot ikonu) bulunabilir. Spring Boot Dashboard’dan: - Çalışma alanındaki tüm Spring Boot uygulamalarını görebilirsiniz -- Uygulamaları tek tıklamayla başlat/durdurabilirsiniz +- Uygulamaları tek tıkla başlatabilir/durdurabilirsiniz - Uygulama günlüklerini gerçek zamanlı izleyebilirsiniz -- Uygulama durumunu izleyebilirsiniz +- Uygulama durumunu takip edebilirsiniz -`introduction` modülünün yanındaki oynat düğmesine basarak bu modülü başlatın veya tüm modülleri aynı anda çalıştırın. +Bu modülü başlatmak için "introduction" yanındaki oynat düğmesine tıklayın veya tüm modülleri aynı anda çalıştırın. Spring Boot Dashboard -*VS Code’da Spring Boot Dashboard — tüm modülleri bir yerden başlat, durdur ve izle* +*VS Code’daki Spring Boot Dashboard — tüm modülleri tek yerden başlat, durdur ve izle* -**Seçenek 2: Kabuk betikleri kullanımı** +**Seçenek 2: Shell komut dosyaları kullanarak** -Tüm web uygulamalarını (modüller 01-04) başlat: +Tüm web uygulamalarını (modüller 01-04) başlatın: **Bash:** ```bash @@ -232,7 +232,7 @@ cd .. # Kök dizinden .\start-all.ps1 ``` -Ya da sadece bu modülü başlat: +Ya da sadece bu modülü başlatın: **Bash:** ```bash @@ -264,59 +264,59 @@ Her iki betik de kök `.env` dosyasından ortam değişkenlerini otomatik yükle Tarayıcınızda http://localhost:8080 adresini açın. -**Durdurmak için:** +**Durmak için:** **Bash:** ```bash -./stop.sh # Yalnızca bu modül +./stop.sh # Sadece bu modül # Veya cd .. && ./stop-all.sh # Tüm modüller ``` **PowerShell:** ```powershell -.\stop.ps1 # Sadece bu modül +.\stop.ps1 # Bu sadece modül # Veya cd ..; .\stop-all.ps1 # Tüm modüller ``` -## Uygulamanın Kullanımı +## Uygulamayı Kullanmak -Uygulama, yan yana iki sohbet uygulamasıyla web arayüzü sağlar. +Uygulama, yan yana iki sohbet uygulamasını web arayüzünde sunar. Uygulama Ana Ekranı -*Hem Basit Sohbet (durumsuz) hem de Konuşmalı Sohbet (durumlu) seçeneklerini gösteren pano* +*Hem Basit Sohbet (durumsuz) hem de Konuşma Sohbeti (durumlu) seçeneklerini gösteren kontrol paneli* ### Durumsuz Sohbet (Sol Panel) -Önce bunu deneyin. "Adım John" deyin ve hemen ardından "Adım ne?" diye sorun. Model hatırlamaz çünkü her mesaj bağımsızdır. Bu, temel dil modeli entegrasyonundaki ana sorunu gösterir — konuşma bağlamı yok. +Bundan başlayın. "Benim adım John" deyin ve hemen ardından "Adım ne?" diye sorun. Model hatırlamayacaktır, çünkü her mesaj bağımsızdır. Bu, temel dil modeli entegrasyonundaki asıl problemi gösterir - konuşma bağlamı yoktur. Durumsuz Sohbet Demo -*Yapay zeka önceki mesajdaki isminizi hatırlamaz* +*Yapay zeka önceki mesajdaki adınızı hatırlamaz* ### Durumlu Sohbet (Sağ Panel) -Şimdi aynı diziyi burada deneyin. "Adım John" deyin ve sonra "Adım ne?" diye sorun. Bu sefer hatırlar. Fark MessageWindowChatMemory'dir — konuşma geçmişini tutar ve her istekle birlikte gönderir. Üretim konuşma yapay zekası böyle çalışır. +Şimdi aynı sırayı burada deneyin. "Benim adım John" deyin ve ardından "Adım ne?" sorun. Bu sefer hatırlar. Fark MessageWindowChatMemory'dedir - konuşma geçmişini korur ve her isteğe bu bağlamı ekler. Üretim konuşma yapay zekası böyle çalışır. Durumlu Sohbet Demo -*Yapay zeka önceki konuşmadan isminizi hatırlar* +*Yapay zeka, konuşmanın başındaki adınızı hatırlar* -Her iki panelde de aynı GPT-5.2 modeli kullanılır. Tek fark bellek. Bu, belleğin uygulamanıza ne kattığını ve gerçek kullanım durumları için neden gerekli olduğunu açıkça gösterir. +Her iki panel de aynı GPT-5.2 modelini kullanır. Tek fark bellek kullanımıdır. Bu, belleğin uygulamanıza neler kattığını ve gerçek kullanım senaryoları için neden gerekli olduğunu netleştirir. ## Sonraki Adımlar -**Sonraki Modül:** [02-prompt-engineering - GPT-5.2 ile İstem Mühendisliği](../02-prompt-engineering/README.md) +**Sonraki Modül:** [02-prompt-mühendisliği - GPT-5.2 ile Prompt Mühendisliği](../02-prompt-engineering/README.md) --- -**Geçiş:** [← Önceki: Modül 00 - Hızlı Başlangıç](../00-quick-start/README.md) | [Ana Sayfaya Dön](../README.md) | [Sonraki: Modül 02 - İstem Mühendisliği →](../02-prompt-engineering/README.md) +**Gezinme:** [← Ana Sayfaya Dön](../README.md) | [İleri: Modül 02 - Prompt Mühendisliği →](../02-prompt-engineering/README.md) --- **Feragatname**: -Bu belge, AI çeviri servisi [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba göstersek de, otomatik çevirilerde hatalar veya yanlışlıklar olabileceğini lütfen unutmayın. Orijinal belge, kendi ana dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi tavsiye edilir. Bu çevirinin kullanımıyla ortaya çıkabilecek yanlış anlamalar veya yorum hatalarından sorumlu değiliz. +Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz. \ No newline at end of file diff --git a/translations/tr/02-prompt-engineering/README.md b/translations/tr/02-prompt-engineering/README.md index 4b0f43d76..744424674 100644 --- a/translations/tr/02-prompt-engineering/README.md +++ b/translations/tr/02-prompt-engineering/README.md @@ -2,100 +2,100 @@ ## İçindekiler -- [Video Yürütme](../../../02-prompt-engineering) -- [Öğrenecekleriniz](../../../02-prompt-engineering) -- [Önkoşullar](../../../02-prompt-engineering) -- [Prompt Mühendisliğini Anlamak](../../../02-prompt-engineering) -- [Prompt Mühendisliği Temelleri](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Şablonları](../../../02-prompt-engineering) -- [İleri Düzey Kalıplar](../../../02-prompt-engineering) -- [Uygulamayı Çalıştır](../../../02-prompt-engineering) -- [Uygulama Ekran Görüntüleri](../../../02-prompt-engineering) -- [Kalıpları İncelemek](../../../02-prompt-engineering) - - [Düşük ve Yüksek İsteklilik](../../../02-prompt-engineering) - - [Görev Yürütme (Araç Ön Yazıları)](../../../02-prompt-engineering) - - [Kendini Yansıtan Kod](../../../02-prompt-engineering) - - [Yapılandırılmış Analiz](../../../02-prompt-engineering) - - [Çok Turlu Sohbet](../../../02-prompt-engineering) - - [Adım Adım Mantık Yürütme](../../../02-prompt-engineering) - - [Kısıtlı Çıktı](../../../02-prompt-engineering) -- [Gerçekten Ne Öğreniyorsunuz](../../../02-prompt-engineering) -- [Sonraki Adımlar](../../../02-prompt-engineering) +- [Video Yürütme](#video-yürütme) +- [Neler Öğreneceksiniz](#neler-öğreneceksiniz) +- [Önkoşullar](#önkoşullar) +- [Prompt Mühendisliğini Anlamak](#prompt-mühendisliğini-anlamak) +- [Prompt Mühendisliği Temelleri](#prompt-mühendisliği-temelleri) + - [Sıfır-Örnekleme (Zero-Shot) Promptlama](#sıfır-örnekleme-zero-shot-promptlama) + - [Az-Örnekleme (Few-Shot) Promptlama](#az-örnekleme-few-shot-promptlama) + - [Düşünce Zinciri](#düşünce-zinciri) + - [Rol Bazlı Promptlama](#rol-bazlı-promptlama) + - [Prompt Şablonları](#prompt-şablonları) +- [Gelişmiş Kalıplar](#gelişmiş-kalıplar) +- [Uygulamayı Çalıştırma](#uygulamayı-çalıştırın) +- [Uygulama Ekran Görüntüleri](#uygulama-ekran-görüntüleri) +- [Kalıpları Keşfetmek](#kalıpları-keşfetmek) + - [Düşük vs Yüksek Heves](#düşük-ve-yüksek-i̇steklilik-eagerness) + - [Görev Yürütme (Araç Önsözleri)](#görev-yürütme-araç-ön-hazırlıkları) + - [Kendini Yansıtan Kod](#kendini-değerlendiren-kod) + - [Yapılandırılmış Analiz](#yapılandırılmış-analiz) + - [Çok Turlu Sohbet](#çok-turlu-sohbet) + - [Adım Adım Akıl Yürütme](#adım-adım-mantık-yürütme) + - [Kısıtlı Çıktı](#kısıtlı-çıktı) +- [Gerçekten Neler Öğreniyorsunuz](#gerçekten-ne-öğreniyorsunuz) +- [Sonraki Adımlar](#sonraki-adımlar) ## Video Yürütme -Bu modüle nasıl başlayacağınızı açıklayan canlı oturumu izleyin: +Bu modüle nasıl başlanacağını açıklayan canlı oturumu izleyin: LangChain4j ile Prompt Mühendisliği - Canlı Oturum -## Öğrenecekleriniz +## Neler Öğreneceksiniz Aşağıdaki diyagram, bu modülde geliştireceğiniz temel konular ve beceriler hakkında genel bir bakış sunar — prompt iyileştirme tekniklerinden takip edeceğiniz adım adım iş akışına kadar. -Öğrenecekleriniz +Neler Öğreneceksiniz -Önceki modüllerde, GitHub Modelleri ile temel LangChain4j etkileşimlerini keşfettiniz ve bellek sayesinde Azure OpenAI ile nasıl konuşma tabanlı yapay zeka yapılacağını gördünüz. Şimdi ise, soruları nasıl sorduğunuza – yani promptlara – Azure OpenAI'nin GPT-5.2'sini kullanarak odaklanacağız. Promptlarınızı nasıl yapılandırdığınız, alacağınız yanıtların kalitesini radikal şekilde etkiler. Temel prompt tekniklerini gözden geçirerek başlıyoruz, ardından GPT-5.2’nin tüm yeteneklerinden tam anlamıyla yararlanan sekiz ileri kalıba geçiyoruz. +Önceki modülde Azure OpenAI ile hafızanın nasıl konuşma AI'sını sağladığını gördünüz. Şimdi Azure OpenAI'nin GPT-5.2'sini kullanarak soruları nasıl soracağımıza — promptlara — odaklanacağız. Promptlarınızı yapılandırma şekliniz aldığınız cevapların kalitesini dramatik şekilde etkiler. Temel prompt tekniklerinin gözden geçirilmesi ile başlıyor, sonra GPT-5.2'nin yeteneklerini tam olarak kullanan sekiz gelişmiş desene geçiyoruz. -GPT-5.2'yi kullanmamızın nedeni akıl yürütme kontrolü sunmasıdır - modele yanıt vermeden önce ne kadar düşünmesi gerektiğini söyleyebilirsiniz. Bu, farklı prompt stratejilerini daha belirgin kılar ve hangi yaklaşımı ne zaman kullanmanız gerektiğini anlamanıza yardımcı olur. Ayrıca GPT-5.2 için Azure'daki daha az hız sınırlarından da faydalanacağız. +GPT-5.2'yi kullanmamızın sebebi, akıl yürütme kontrolü getirmesidir - modelin cevaplamadan önce ne kadar düşünmesi gerektiğini söyleyebilirsiniz. Bu farklı prompt stratejilerini daha net kılar ve her yaklaşımın ne zaman kullanılacağını anlamanıza yardımcı olur. ## Önkoşullar -- Modül 01'in tamamlanması (Azure OpenAI kaynaklarının dağıtılması) -- Kök dizinde Azure kimlik bilgileri ile `.env` dosyası (Modül 01’de `azd up` komutuyla oluşturuldu) +- Modül 01 tamamlanmış (Azure OpenAI kaynakları devreye alınmış) +- Ana dizinde `.env` dosyası Azure kimlik bilgileri ile (Modül 01'de `azd up` komutu ile oluşturulmuş) -> **Not:** Eğer Modül 01’i tamamlamadıysanız, önce oradaki dağıtım talimatlarını takip edin. +> **Not:** Modül 01'i tamamlamadıysanız, önce oradaki dağıtım talimatlarını izleyin. ## Prompt Mühendisliğini Anlamak -Özünde, prompt mühendisliği belirsiz talimatlar ile kesin talimatlar arasındaki farktır, aşağıdaki karşılaştırma bunu gösterir. +Temelde prompt mühendisliği belirsiz talimatlar ile kesin talimatlar arasındaki farktır; aşağıdaki karşılaştırma bunu gösterir. Prompt Mühendisliği Nedir? -Prompt mühendisliği, tutarlı şekilde istediğiniz sonuçları almanızı sağlayan giriş metinleri tasarlamaktır. Sadece soru sormak değil — modelin tam olarak ne istediğinizi ve nasıl sunması gerektiğini anlayacağı şekilde istekleri yapılandırmaktır. +Prompt mühendisliği, ihtiyaç duyduğunuz sonuçları tutarlı olarak almanızı sağlayan giriş metnini tasarlama işidir. Sadece soru sormakla ilgili değil — isteği o şekilde yapılandırmakla ilgilidir ki model tam olarak ne istediğinizi ve nasıl sunacağını anlasın. -Bunu bir meslektaşınıza talimat vermek gibi düşünün. "Hatanın düzeltilmesi" belirsizdir. "UserService.java dosyasının 45. satırındaki null pointer istisnasını null kontrolü ekleyerek düzelt" ise özeldir. Dil modelleri de aynı şekilde çalışır — spesifiklik ve yapı önemlidir. +Bir meslektaşınıza talimat vermek gibi düşünün. "Hata düzelt" belirsizdir. "UserService.java’nın 45. satırındaki null pointer istisnasını null kontrolü ekleyerek düzelt" ise spesifiktir. Dil modelleri aynı şekilde çalışır — özgüllük ve yapı önemlidir. -Aşağıdaki diyagram LangChain4j'nin bu resme nasıl uyduğunu gösterir — prompt kalıplarınızı SystemMessage ve UserMessage yapı blokları aracılığıyla modele bağlar. +Aşağıdaki diyagram LangChain4j'nin bu resmi nasıl tamamladığını gösterir — prompt kalıplarınızı SystemMessage ve UserMessage yapı taşları aracılığıyla modele bağlar. -LangChain4j'nin Uygunluğu +LangChain4j Nasıl Uyar? -LangChain4j altyapıyı sağlar — model bağlantıları, bellek ve mesaj türleri — prompt kalıpları ise bu altyapı üzerinden gönderdiğiniz dikkatlice yapılandırılmış metinlerdir. Ana yapı taşları `SystemMessage` (AI'nın davranışını ve rolünü belirler) ve `UserMessage`dir (gerçek isteğinizi taşır). +LangChain4j, altyapıyı sağlar — model bağlantıları, hafıza ve mesaj türleri — prompt kalıpları ise bu altyapı üzerinden gönderdiğiniz dikkatle yapılandırılmış metindir. Temel yapı taşları `SystemMessage` (yapay zekanın davranışını ve rolünü belirler) ve `UserMessage` (gerçek isteğinizi taşır) öğeleridir. ## Prompt Mühendisliği Temelleri -Aşağıda gösterilen beş temel teknik, etkili prompt mühendisliğinin temelini oluşturur. Her biri dil modelleriyle iletişimin farklı bir yönüne değinir. +Aşağıda gösterilen beş temel teknik, etkili prompt mühendisliğinin temelini oluşturur. Her biri dil modelleriyle iletişimin farklı bir yönünü ele alır. -Beş Prompt Mühendisliği Kalıbı Genel Bakış +Beş Prompt Mühendisliği Kalıbına Genel Bakış -Bu modüldeki ileri kalıplara girmeden önce, temel beş prompt tekniklerini gözden geçirelim. Bunlar her prompt mühendisi için bilinmesi gereken yapı taşlarıdır. Eğer [Hızlı Başlangıç modülünü](../00-quick-start/README.md#2-prompt-patterns) tamamladıysanız, bunları uygulamada görmüşsünüzdür — işte kavramsal çerçevesi. +Bu modüldeki gelişmiş kalıplara dalmadan önce, beş temel promptlama tekniğini gözden geçirelim. Bunlar her prompt mühendisi tarafından bilinmesi gereken yapı taşlarıdır. -### Zero-Shot Prompting +### Sıfır-Örnekleme (Zero-Shot) Promptlama -En basit yaklaşım: modele hiçbir örnek vermeden doğrudan talimat verin. Model, görevi anlamak ve yürütmek için tamamen eğitim bilgilerine dayanır. Beklenen davranış açık olduğu basit istekler için işe yarar. +En basit yaklaşım: modele herhangi bir örnek vermeden doğrudan bir talimat vermek. Model, görevi anlamak ve yürütmek için tamamen eğitimine güvenir. Beklenen davranışın açık olduğu basit talepler için iyi çalışır. -Zero-Shot Prompting +Sıfır-Örnekleme Promptlama -*Örnek olmadan doğrudan talimat — model yalnızca talimattan görevi çıkarır* +*Örnek olmadan doğrudan talimat — model görevi yalnızca talimattan çıkarır* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// Yanıt: "Olumlu" +// Yanıt: "Pozitif" ``` -**Ne zaman kullanılır:** Basit sınıflandırmalar, doğrudan sorular, çeviriler veya modelin ek rehberlik olmadan yapabileceği herhangi bir görev. +**Ne zaman kullanılır:** Basit sınıflandırmalar, doğrudan sorular, çeviriler veya modelin ek rehberlik olmadan işleyebileceği her türlü görev. -### Few-Shot Prompting +### Az-Örnekleme (Few-Shot) Promptlama -Modelin takip etmesini istediğiniz kalıbı gösteren örnekler verin. Model, örneklerinizden beklenen giriş-çıkış formatını öğrenir ve yeni girdilere uygular. Bu, istenen formatın veya davranışın açık olmadığı görevlerde tutarlılığı dramatik şekilde artırır. +Modelin takip etmesini istediğiniz kalıbı gösteren örnekler sağlarsınız. Model, örneklerden beklenen giriş-çıkış formatını öğrenir ve yeni girdilere uygular. Bu, istenen formatın ya da davranışın açık olmadığı görevlerde tutarlılığı dramatik şekilde artırır. -Few-Shot Prompting +Az-Örnekleme Promptlama -*Örneklerden öğrenmek — model kalıbı tanır ve yeni girdilere uygular* +*Örneklerden öğrenme — model kalıbı tanır ve yeni girdilere uygular* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Ne zaman kullanılır:** Özel sınıflandırmalar, tutarlı biçimlendirme, alan spesifik görevler veya zero-shot sonuçlar tutarsızsa. +**Ne zaman kullanılır:** Özel sınıflandırmalar, tutarlı biçimlendirme, alan spesifik görevler veya sıfır-örnekleme sonuçları tutarsız olduğunda. -### Chain of Thought +### Düşünce Zinciri -Modelden mantığını adım adım göstermesini isteyin. Doğrudan cevaba atlamaktan ziyade, model problemi parçalar ve her adımı açıkça işler. Bu, matematik, mantık ve çok adımlı akıl yürütmede doğruluğu artırır. +Modelden akıl yürütmesini adım adım göstermesini istersiniz. Cevaba doğrudan atlamak yerine, model problemi parçalara ayırır ve her kısmı açık şekilde işler. Bu, matematik, mantık ve çok adımlı akıl yürütme görevlerinde doğruluğu artırır. Düşünce Zinciri Promptlama -*Adım adım mantık yürütme — karmaşık problemleri açık mantıksal adımlara bölmek* +*Adım adım akıl yürütme — karmaşık problemleri açık mantıksal adımlara bölme* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Model gösteriyor: 15 - 8 = 7, sonra 7 + 12 = 19 elma +// Model şu sonucu gösteriyor: 15 - 8 = 7, sonra 7 + 12 = 19 elma ``` -**Ne zaman kullanılır:** Matematik problemleri, mantık bulmacaları, hata ayıklama veya mantık sürecini göstermek doğruluk ve güveni artıran görevlerde. +**Ne zaman kullanılır:** Matematik problemleri, mantık bulmacaları, hata ayıklama veya akıl yürütme sürecinin gösterilmesinin doğruluk ve güveni artırdığı durumlar. -### Role-Based Prompting +### Rol Bazlı Promptlama -Sorunuzu sormadan önce AI için bir rol veya persona belirleyin. Bu, yanıtın tonu, derinliği ve odağını şekillendiren bağlam sağlar. "Yazılım mimarı" farklı, "çaylak geliştirici" veya "güvenlik denetçisi" farklı tavsiyeler verir. +Sorunuzu sormadan önce yapay zekaya bir kişilik ya da rol verirsiniz. Bu, yanıtın tonunu, derinliğini ve odağını belirleyen bir bağlam sağlar. "Yazılım mimarı" ile "genç geliştirici" ya da "güvenlik denetçisi" farklı öneriler sunar. Rol Bazlı Promptlama -*Bağlam ve persona belirleme — aynı soru, atanmış role göre farklı yanıt alır* +*Bağlam ve kişilik ayarlama — aynı soru verilen role göre farklı yanıt alır* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Ne zaman kullanılır:** Kod incelemeleri, eğitim, alan spesifik analizler veya yanıtların belirli uzmanlık seviyesine veya bakış açısına göre uyarlanması gereken durumlarda. +**Ne zaman kullanılır:** Kod incelemeleri, eğitim, alan spesifik analiz veya yanıtların belirli uzmanlık seviyesi ya da bakış açısına göre özelleştirildiği durumlar. ### Prompt Şablonları -Değişken yer tutucuları olan yeniden kullanılabilir promptlar oluşturun. Her seferinde yeni prompt yazmak yerine, bir defa şablon tanımlayın ve farklı değerlerle doldurun. LangChain4j `PromptTemplate` sınıfı, `{{variable}}` sözdizimi ile bunu kolaylaştırır. +Değişken yer tutucularla tekrar kullanılabilir promptlar oluşturun. Her seferinde yeni bir prompt yazmak yerine, bir şablon tanımlayın ve farklı değerlerle doldurun. LangChain4j’nin `PromptTemplate` sınıfı `{{variable}}` sözdizimi ile bunu kolaylaştırır. Prompt Şablonları -*Değişken yer tutucuları ile tekrar kullanılabilir promptlar — bir şablon, birçok kullanım* +*Değişken yer tutuculara sahip tekrar kullanılabilir promptlar — bir şablon, çok kullanım* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Ne zaman kullanılır:** Farklı girişlerle tekrar eden sorgular, toplu işlem, yeniden kullanılabilir AI iş akışları oluşturma veya prompt yapısı aynı kalıp veri değişen senaryolarda. +**Ne zaman kullanılır:** Farklı girişlerle tekrarlanan sorgular, toplu işlemler, tekrar kullanılabilir AI iş akışları veya prompt yapısının aynı kalıp, verinin değiştiği her senaryo. --- -Bu beş temel, çoğu promptlama görevinde sağlam bir araç seti sağlar. Bu modülün geri kalanı, GPT-5.2’nin akıl yürütme kontrolü, kendini değerlendirme ve yapılandırılmış çıktı özelliklerini kullanan **sekiz ileri kalıp** üzerine inşa edilir. +Bu beş temel, çoğu promptlama görevi için sağlam bir araç seti sunar. Bu modül kalan kısmında, GPT-5.2'nin akıl yürütme kontrolü, kendini değerlendirme ve yapılandırılmış çıktı yeteneklerini kullanan **sekiz gelişmiş kalıp** ile devam eder. -## İleri Düzey Kalıplar +## Gelişmiş Kalıplar -Temelleri ele aldığımıza göre, bu modülü benzersiz kılan sekiz ileri kalıba geçelim. Tüm problemler aynı yaklaşımı gerektirmez. Bazı sorular hızlı yanıt ister, bazılarının derin bir düşünceye ihtiyacı vardır. Bazıları görünür mantık ister, bazıları sadece sonucu ister. Aşağıdaki her kalıp farklı bir senaryo için optimize edilmiştir — ve GPT-5.2’nin akıl yürütme kontrolü farkları daha da belirgin yapar. +Temelleri tamamladıktan sonra, bu modülü benzersiz kılan sekiz gelişmiş kalıba geçelim. Her problem aynı yaklaşımı gerektirmez. Bazı sorular hızlı cevap ister, bazıları derin düşünme. Bazıları görünür akıl yürütme ister, bazıları yalnızca sonuç. Aşağıdaki her kalıp farklı senaryo için optimize edilmiştir — ve GPT-5.2'nin akıl yürütme kontrolü farkları daha da belirgin kılar. -Sekiz Prompt Kalıbı +Sekiz Promptlama Kalıbı *Sekiz prompt mühendisliği kalıbının genel görünümü ve kullanım alanları* -GPT-5.2 bu kalıplara bir boyut daha ekler: *akıl yürütme kontrolü*. Aşağıdaki kaydırıcı, modelin düşünce çabasını nasıl ayarlayabileceğinizi gösterir — hızlı, doğrudan yanıtlar ile derin, kapsamlı analiz arasında. +GPT-5.2 bu kalıplara başka bir boyut ekler: *akıl yürütme kontrolü*. Aşağıdaki çubuk, modelin düşünme çabasını — hızlı, doğrudan cevaplardan derin, kapsamlı analizlere kadar — nasıl ayarlayabileceğinizi gösterir. GPT-5.2 ile Akıl Yürütme Kontrolü -*GPT-5.2’nin akıl yürütme kontrolü, modelin ne kadar düşünmesi gerektiğini belirtmenizi sağlar — hızlı doğrudan yanıtlardan derin incelemeye kadar* +*GPT-5.2'nin akıl yürütme kontrolü, modelin ne kadar düşünmesi gerektiğini belirtmenizi sağlar — hızlı doğrudan cevaplardan derin keşfe kadar* -**Düşük İsteklilik (Hızlı & Odaklı)** - Hızlı, doğrudan yanıtlar istediğiniz basit sorular için. Model minimal akıl yürütme yapar - en fazla 2 adım. Hesaplamalar, sorgulamalar veya basit sorular için kullanın. +**Düşük Heves (Hızlı ve Odaklı)** - Hızlı, doğrudan cevap istediğiniz basit sorular için. Model minimum akıl yürütme yapar - maksimum 2 adım. Bunu hesaplamalar, sorgular veya basit sorular için kullanın. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **GitHub Copilot ile keşfedin:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) dosyasını açın ve sorun: -> - "Düşük istekli ve yüksek istekli prompt kalıpları arasındaki fark nedir?" -> - "Promptlardaki XML etiketleri AI yanıtını nasıl yapılandırmaya yardımcı olur?" -> - "Kendini yansıtma kalıplarını ne zaman doğrudan talimatlara tercih etmeliyim?" +> 💡 **GitHub Copilot ile Keşfedin:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) dosyasını açın ve sorun: +> - "Düşük heves ve yüksek heves promptlama kalıpları arasındaki fark nedir?" +> - "Promptlardaki XML etiketleri yapay zekanın yanıtını nasıl yapılandırmaya yardım eder?" +> - "Kendini yansıtma kalıplarını ne zaman doğrudan talimat yerine kullanmalıyım?" -**Yüksek İsteklilik (Derin & Kapsamlı)** - Kapsamlı analiz istediğiniz karmaşık problemler için. Model detaylı bir şekilde keşfeder ve ayrıntılı mantık yürütür. Sistem tasarımı, mimari kararlar veya karmaşık araştırmalar için kullanın. +**Yüksek Heves (Derin ve Kapsamlı)** - Kapsamlı analiz istediğiniz karmaşık problemler için. Model derinlemesine keşfeder ve detaylı akıl yürütmeyi gösterir. Bunu sistem tasarımı, mimari kararlar veya karmaşık araştırmalar için kullanın. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Görev Yürütme (Adım-Adım İlerleme)** - Çok adımlı iş akışları için. Model önceden bir plan sunar, çalışırken her adımı anlatır ve ardından özet verir. Göçler, uygulamalar veya çok adımlı süreçler için kullanın. +**Görev Yürütme (Adım Adım İlerleme)** - Çok adımlı iş akışları için. Model baştan bir plan sunar, çalışırken her adımı anlatır, sonra özetler. Bunu geçişler, uygulamalar veya çok adımlı süreçler için tercih edin. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Düşünce Zinciri promptlama, modelden mantık sürecini açıkça göstermesini ister, karmaşık görevlerde doğruluğu artırır. Adım adım ayrıntı, hem insan hem de AI için mantığı anlamaya yardımcı olur. +Düşünce Zinciri promptlama, modelden akıl yürütme sürecini göstermesini açık şekilde ister, karmaşık görevlerin doğruluğunu artırır. Adım adım ayrım, hem insan hem yapay zekanın mantığı anlamasını kolaylaştırır. -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** Bu kalıp hakkında sorun: -> - "Uzun süren işlemler için görev yürütme kalıbını nasıl uyarlardım?" -> - "Üretim uygulamalarında araç ön yazıları nasıl yapılandırılır?" -> - "Ara ilerleme güncellemelerini UI’da nasıl yakalar ve gösteririm?" +> **🤖 GitHub Copilot Chat ile Deneyin:** Bu kalıpla ilgili sorun: +> - "Uzun süreli işlemler için görev yürütme kalıbını nasıl adapte edebilirim?" +> - "Üretim uygulamalarında araç önsözleri nasıl en iyi şekilde yapılandırılır?" +> - "Ara ilerleme güncellemelerini bir kullanıcı arayüzünde nasıl yakalar ve gösteririm?" -Aşağıdaki diyagram bu Planla → Yürüt → Özetle iş akışını gösterir. +Aşağıdaki diyagram bu Planla → Yürüt → Özetle iş akışını görselleştirir. Görev Yürütme Kalıbı -*Çok adımlı görevler için Planla → Yürüt → Özetle iş akışı* +*Planla → Yürüt → Özetle iş akışı çok adımlı görevler için* -**Kendini Yansıtan Kod** - Üretim kalitesinde kod üretmek için. Model, uygun hata yönetimi ile üretim standartlarına uygun kodlar üretir. Yeni özellikler veya servisler geliştirirken kullanın. +**Kendini Yansıtan Kod** - Üretim kalitesinde kod üretmek için. Model, uygun hata yönetimi ile üretim standartlarına uygun kod oluşturur. Yeni özellikler ya da servisler oluştururken kullanılır. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Aşağıdaki diyagram bu yinelemeli geliştirme döngüsünü gösterir — üret, değerlendir, zayıf noktaları belirle ve kod üretim standartlarına ulaşana kadar iyileştir. +Aşağıdaki diyagram bu tekrarlı iyileştirme döngüsünü gösterir — üret, değerlendirme yap, zayıf noktaları belirle, standarda ulaşana kadar iyileştir. Kendini Yansıtma Döngüsü -*Yinelemeli iyileştirme döngüsü - üret, değerlendir, sorunları tanımla, geliştir, tekrarla* +*İteratif iyileştirme döngüsü - üret, değerlendir, sorunları tespit et, geliştir, tekrarla* -**Yapılandırılmış Analiz** - Tutarlı değerlendirme için. Model, kodu sabit bir çerçeve kullanarak inceler (doğruluk, uygulamalar, performans, güvenlik, sürdürülebilirlik). Kod incelemeleri veya kalite değerlendirmeleri için kullanın. +**Yapılandırılmış Analiz** - Tutarlı değerlendirme için. Model, kodu sabit bir çerçeve ile gözden geçirir (doğruluk, uygulamalar, performans, güvenlik, sürdürülebilirlik). Kod incelemeleri veya kalite değerlendirmelerinde kullanılır. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** Yapılandırılmış analiz hakkında sorun: -> - "Farklı kod inceleme türlerine göre analiz çerçevesi nasıl özelleştirilir?" -> - "Yapılandırılmış çıktıları programatik olarak ayrıştırıp aksiyon almak için en iyi yöntem nedir?" -> - "Farklı inceleme oturumlarında tutarlı şiddet düzeyleri nasıl sağlanır?" +> **🤖 GitHub Copilot Chat ile Deneyin:** Yapılandırılmış analiz hakkında sorun: +> - "Farklı kod inceleme türleri için analiz çerçevesi nasıl özelleştirilir?" +> - "Yapılandırılmış çıktıyı programatik olarak ayrıştırmanın ve işlemenin en iyi yolu nedir?" +> - "Farklı inceleme oturumlarında tutarlı önem düzeyleri nasıl sağlanır?" -Aşağıdaki diyagram bu yapılandırılmış çerçevenin bir kod incelemesini tutarlı kategorilere ve şiddet seviyelerine nasıl organize ettiğini gösterir. +Aşağıdaki diyagram bu yapılandırılmış çerçevenin kod incelemesini tutarlı kategorilere ve önem düzeylerine nasıl ayırdığını gösterir. Yapılandırılmış Analiz Kalıbı -*Tutarlı kod incelemeleri için şiddet seviyeleri ile çerçeve* +*Tutarlı kod incelemeleri için önem düzeyli çerçeve* -**Çok Turlu Sohbet** - Bağlam gerektiren konuşmalar için. Model önceki mesajları hatırlar ve üzerine inşa eder. Etkileşimli yardım oturumları veya karmaşık SSS için kullanın. +**Çok Turlu Sohbet** - Bağlam gerektiren konuşmalar için. Model önceki mesajları hatırlar ve üzerine inşa eder. Etkileşimli yardım oturumları veya karmaşık SSS için kullanılır. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Aşağıdaki diyagram, konuşma bağlamının her turda nasıl biriktiğini ve modelin token sınırıyla nasıl ilişkili olduğunu görselleştirir. +Aşağıdaki diyagram, konuşma bağlamının her turda nasıl biriktiğini ve modelin token sınırıyla ilişkisini görselleştirir. -Bağlam Belleği +Bağlam Hafızası -*Konuşma bağlamının çoklu turlarda token sınırına ulaşana kadar birikimi* -**Adım Adım Muhakeme** - Görünür mantık gerektiren problemler için. Model her adım için açık muhakeme gösterir. Bunu matematik problemleri, mantık bulmacaları veya düşünce sürecini anlamak istediğinizde kullanın. +*Konuşma bağlamının token sınırına ulaşana kadar çoklu turlarda birikmesi* + +**Adım Adım Akıl Yürütme** - Görünür mantık gerektiren problemler için. Model, her adım için açık akıl yürütme gösterir. Matematik problemleri, mantık bulmacaları veya düşünme sürecini anlamak istediğiniz durumlar için uygundur. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Aşağıdaki diyagram, modelin problemleri nasıl açık, numaralandırılmış mantıksal adımlara böldüğünü gösterir. - -Adım Adım Desen +Aşağıdaki diyagram modelin problemleri açık, numaralandırılmış mantıksal adımlara nasıl böldüğünü gösterir. -*Problemleri açık mantıksal adımlara bölme* +Adım Adım Kalıp +*Sorunları açık mantıksal adımlara ayırmak* -**Kısıtlı Çıktı** - Belirli biçim gereksinimleri içeren yanıtlar için. Model format ve uzunluk kurallarına sıkı sıkıya uyar. Bunu özetler için veya kesin çıktı yapısına ihtiyacınız olduğunda kullanın. +**Kısıtlı Çıktı** - Belirli format gereksinimleri olan yanıtlar için. Model, format ve uzunluk kurallarına kesinlikle uyar. Özetler için veya kesin çıktı yapısına ihtiyaç duyduğunuzda kullanın. ```java String prompt = """ @@ -420,51 +420,51 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Aşağıdaki diyagram, kısıtlamaların modelin çıktıyı tam olarak istenen format ve uzunluk kurallarına uygun üretmesini nasıl sağladığını gösterir. +Aşağıdaki diyagram, modelin format ve uzunluk gereksinimlerinize sıkı sıkıya uyan çıktı üretmesini nasıl sağladığını göstermektedir. Kısıtlı Çıktı Deseni -*Belirli format, uzunluk ve yapı gereksinimlerini uygulama* +*Belirli format, uzunluk ve yapı gereksinimlerinin uygulanması* -## Uygulamayı Çalıştırma +## Uygulamayı Çalıştırın **Dağıtımı doğrulayın:** -Azure kimlik bilgileri ile root dizinde `.env` dosyasının var olduğundan emin olun (Modül 01 sırasında oluşturuldu). Bunu modül dizininden çalıştırın (`02-prompt-engineering/`): +`.env` dosyasının kök dizinde Azure kimlik bilgileri ile (Modül 01 sırasında oluşturuldu) mevcut olduğundan emin olun. Bunu modül dizininden (`02-prompt-engineering/`) çalıştırın: **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT göstermelidir +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT göstermeli ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT göstermeli +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT göstermelidir ``` **Uygulamayı başlatın:** -> **Not:** Eğer root dizinden `./start-all.sh` kullanarak tüm uygulamaları zaten başlattıysanız (Modül 01'de anlatıldığı gibi), bu modül zaten 8083 portunda çalışıyor. Aşağıdaki başlatma komutlarını atlayabilir ve doğrudan http://localhost:8083 adresine geçebilirsiniz. +> **Not:** Eğer tüm uygulamaları kök dizinden `./start-all.sh` komutuyla (Modül 01’de açıklandığı gibi) zaten başlattıysanız, bu modül 8083 portunda zaten çalışıyor. Aşağıdaki başlatma komutlarını atlayıp doğrudan http://localhost:8083 adresine gidebilirsiniz. **Seçenek 1: Spring Boot Dashboard kullanımı (VS Code kullanıcıları için önerilir)** -Geliştirici konteyneri, tüm Spring Boot uygulamalarını yönetmek için görsel bir arayüz sağlayan Spring Boot Dashboard uzantısını içerir. Bunu VS Code'un sol tarafındaki Aktivite Çubuğunda (Spring Boot simgesine bakın) bulabilirsiniz. +Dev konteyner, tüm Spring Boot uygulamalarını yönetmek için görsel arayüz sağlayan Spring Boot Dashboard eklentisini içerir. VS Code’un sol yanındaki Aktivite Çubuğunda (Spring Boot simgesine bakın) bulabilirsiniz. Spring Boot Dashboard’dan şunları yapabilirsiniz: -- Çalışma alanındaki tüm mevcut Spring Boot uygulamalarını görmek +- Çalışma alanındaki tüm kullanılabilir Spring Boot uygulamalarını görmek - Uygulamaları tek tıklamayla başlatmak/durdurmak -- Uygulama günlüklerini gerçek zamanlı izlemek -- Uygulama durumunu takip etmek +- Uygulama günlüklerini gerçek zamanlı görüntülemek +- Uygulama durumunu izlemek -"prompt-engineering" yanındaki oynat düğmesine tıklayarak bu modülü başlatabilir veya tüm modülleri aynı anda başlatabilirsiniz. +Bu modülü başlatmak için "prompt-engineering" yanındaki oynat düğmesine tıklayın veya tüm modülleri aynı anda başlatın. Spring Boot Dashboard -*VS Code’daki Spring Boot Dashboard — tüm modülleri tek yerden başlatın, durdurun ve izleyin* +*VS Code’daki Spring Boot Dashboard — tüm modülleri tek bir yerden başlatın, durdurun ve izleyin* -**Seçenek 2: Shell script kullanımı** +**Seçenek 2: Shell betikleri kullanmak** -Tüm web uygulamalarını başlatın (modüller 01-04): +Tüm web uygulamalarını (modüller 01-04) başlatın: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Her iki script de root `.env` dosyasından ortam değişkenlerini otomatik olarak yükler ve JAR dosyaları yoksa oluşturur. +Her iki betik de kök dizindeki `.env` dosyasından ortam değişkenlerini otomatik yükler ve JAR dosyaları yoksa inşa eder. -> **Not:** Başlatmadan önce tüm modülleri elle derlemeyi tercih ederseniz: +> **Not:** Başlatmadan önce tüm modülleri manuel olarak derlemeyi tercih ederseniz: > > **Bash:** > ```bash @@ -521,76 +521,76 @@ cd .. && ./stop-all.sh # Tüm modüller **PowerShell:** ```powershell -.\stop.ps1 # Sadece bu modül +.\stop.ps1 # Yalnızca bu modül # Veya cd ..; .\stop-all.ps1 # Tüm modüller ``` ## Uygulama Ekran Görüntüleri -İşte prompt engineering modülünün ana arayüzü; burada sekiz desenin tümü yan yana deneyebilirsiniz. +Burada, sekiz kalıbın tamamıyla yan yana deneme yapabileceğiniz prompt engineering modülünün ana arayüzü bulunmaktadır. -Dashboard Ana Sayfa +Dashboard Home -*Sekiz prompt engineering deseninin özellikleri ve kullanım durumları ile gösterildiği ana panel* +*Sekiz prompt engineering kalıbını özellikleri ve kullanım durumlarıyla gösteren ana paneller* -## Desenleri Keşfetmek +## Kalıpları Keşfetmek -Web arayüzü farklı prompt stratejilerini denemenizi sağlar. Her desen farklı problemleri çözer - ne zaman hangi yaklaşımın iyi olduğunu görmek için deneyin. +Web arayüzü, farklı sorgulama stratejileriyle deneme yapmanızı sağlar. Her kalıp farklı sorunları çözer - hangisinin ne zaman işe yaradığını görmek için deneyin. -> **Not: Akışlı (Streaming) vs Akışsız (Non-Streaming)** — Her desen sayfasında iki buton bulunur: **🔴 Akışlı Yanıt (Canlı)** ve bir **Akışsız** seçenek. Akışlıda, Server-Sent Events (SSE) kullanılır; model oluştukça tokenlar gerçek zamanlı gösterilir, böylece ilerlemeyi hemen görürsünüz. Akışsız seçenek ise tüm yanıt gelene kadar bekler. Derin muhakeme gerektiren komutlar için (ör. Yüksek Hırs, Öz-Değerlendiren Kod) akışsız çağrı uzun sürebilir - bazen dakikalarca - ve görünür geri bildirim yoktur. **Karmaşık promptlarla deneme yaparken akışlıyı kullanın** ki modelin çalıştığını görün ve isteğin zaman aşımına uğradığı yanılgısına kapılmayın. +> **Not: Akışlı vs Akışsız** — Her kalıp sayfası iki buton sunar: **🔴 Akışlı Yanıt (Canlı)** ve **Akışsız** seçenek. Akışlı, model tokenleri üretirken Server-Sent Events (SSE) kullanarak gerçek zamanlı gösterir, böylece ilerlemeyi hemen görürsünüz. Akışsız seçenek tüm yanıtı bekler ve sonra gösterir. Derin mantık gerektiren isteklerde (örneğin, High Eagerness, Self-Reflecting Code) akışsız çağrı çok uzun sürebilir — bazen dakikalarca — ve görünür geri bildirim olmaz. **Karmaşık sorgularla denemeler yaparken akışlıyı kullanın** böylece modelin nasıl çalıştığını görür ve isteğin zaman aşımına uğradığı izlenimini önlersiniz. > -> **Not: Tarayıcı Gereksinimi** — Akış özelliği Fetch Streams API (`response.body.getReader()`) kullanır ve tam bir tarayıcı (Chrome, Edge, Firefox, Safari) gerekir. VS Code’un gömülü Simple Browser’ında çalışmaz; çünkü webview ReadableStream API desteklemez. Simple Browser kullanıyorsanız, akışsız butonlar normal çalışır, sadece akışlı butonlar etkilenir. Tam deneyim için `http://localhost:8083` adresini harici bir tarayıcıda açın. +> **Not: Tarayıcı Gereksinimi** — Akış özelliği Fetch Streams API (`response.body.getReader()`) kullanır ve tam özellikli bir tarayıcı (Chrome, Edge, Firefox, Safari) gerektirir. VS Code’un yerleşik Basit Tarayıcısında çalışmaz çünkü onun webview’si ReadableStream API desteği sunmaz. Basit Tarayıcı kullanırsanız, akışsız düğmeler normal çalışır — sadece akışlılar etkilenir. Tam deneyim için `http://localhost:8083` adresini harici bir tarayıcıda açın. -### Düşük vs Yüksek Hırs +### Düşük ve Yüksek İsteklilik (Eagerness) -"200'ün %15'i nedir?" gibi basit bir soruyu Düşük Hırs ile sorun. Anında, doğrudan yanıt alırsınız. Şimdi "Yüksek trafikli bir API için önbellekleme stratejisi tasarla" gibi karmaşık bir şey sorun. **🔴 Akışlı Yanıt (Canlı)** düğmesine tıklayın ve modelin ayrıntılı muhakemesinin token token belirdiğini izleyin. Aynı model, aynı soru yapısı - ama prompt ona ne kadar düşünmesi gerektiğini söylüyor. +"Düşük İsteklilik" ile "200’ün %15’i nedir?" gibi basit bir soru sorun. Hızlı, doğrudan yanıt alırsınız. Şimdi "Yüksek trafikli API için önbellekleme stratejisi tasarla" gibi karmaşık bir soru sorup **🔴 Akışlı Yanıt (Canlı)** butonuna tıklayın ve modelin detaylı mantığını token token görün. Aynı model, aynı soru yapısı - ama sorgu ona ne kadar düşünmesi gerektiğini söylüyor. -### Görev Yürütme (Araç Ön Bilgileri) +### Görev Yürütme (Araç Ön Hazırlıkları) -Çok adımlı iş akışları, önceden planlama ve ilerlemenin anlatımıyla fayda sağlar. Model ne yapacağını özetler, her adımı anlatır, sonra sonuçları özetler. +Çok adımlı iş akışları önceden planlama ve ilerleme anlatımıyla gelişir. Model ne yapacağını özetler, her adımı anlatır, sonra sonuçları özetler. -### Öz-Değerlendiren Kod +### Kendini Değerlendiren Kod -"Bir e-posta doğrulama servisi oluştur" deyin. Sadece kod üretmekle kalmaz, kalite kriterlerine göre değerlendirir, zayıf noktaları belirler ve geliştirir. Kod üretim standartlarına ulaşana kadar iterasyon yaptığını görürsünüz. +"Bir e-posta doğrulama servisi oluştur" deneyin. Kod oluşturup durmak yerine, model üretir, kalite kriterlerine göre değerlendirir, zayıf noktaları belirler ve geliştirir. Kod üretim standartlarına ulaşana kadar tekrar ettirir. ### Yapılandırılmış Analiz -Kod incelemeleri tutarlı değerlendirme çerçeveleri ister. Model kodu sabit kategoriler (doğruluk, uygulama, performans, güvenlik) ve şiddet seviyeleri ile analiz eder. +Kod incelemeleri tutarlı değerlendirme çerçeveleri ister. Model, kodu doğruluk, uygulamalar, performans, güvenlik gibi sabit kategorilerle ve önem dereceleriyle analiz eder. ### Çok Turlu Sohbet -"Spring Boot nedir?" diye sorun, hemen ardından "Bir örnek göster" deyin. Model ilk soruyu hatırlar ve size özel bir Spring Boot örneği sunar. Bellek olmasaydı, ikinci soru çok belirsiz olurdu. +"Spring Boot nedir?" diye sorun, hemen ardından "Bana bir örnek göster" deyin. Model ilk soruyu hatırlar ve size özel bir Spring Boot örneği verir. Hafıza olmasaydı, ikinci soru çok belirsiz olurdu. -### Adım Adım Muhakeme +### Adım Adım Mantık Yürütme -Bir matematik problemi seçin ve hem Adım Adım Muhakeme hem de Düşük Hırs ile deneyin. Düşük hırs sadece cevabı verir - hızlı ama opak. Adım adım her hesaplama ve kararı gösterir. +Bir matematik problemi seçip hem Adım Adım Mantık Yürütme hem de Düşük İsteklilikle deneyin. Düşük istek sadece cevabı verir — hızlı ama yüzeysel. Adım adım size her hesaplamayı ve kararı gösterir. ### Kısıtlı Çıktı -Belirli format veya kelime sayısına ihtiyaç duyduğunuzda, bu desen katı uyumluluğu zorlar. Tam 100 kelimelik madde işaretli bir özet oluşturarak deneyin. +Belirli format veya kelime sayısı gerektiğinde, bu kalıp sıkı uyumu sağlar. Tam olarak 100 kelimelik, madde işaretli bir özet üretmeyi deneyin. ## Gerçekten Ne Öğreniyorsunuz -**Muhakeme Çabası Her Şeyi Değiştirir** +**Mantık Yürütme Çabası Her Şeyi Değiştirir** -GPT-5.2, promptlarınız aracılığıyla hesaplama çabasını kontrol etmenizi sağlar. Düşük çaba, minimal keşif ile hızlı yanıt verir. Yüksek çaba, modelin derin düşünmesi anlamına gelir. Görev karmaşıklığına göre çabayı ayarlamayı öğreniyorsunuz - basit sorulara zaman harcamayın, ama karmaşık kararlarda acele etmeyin. +GPT-5.2, sorgularınız aracılığıyla hesaplama çabasını kontrol etmenizi sağlar. Düşük çaba, hızlı ve az keşif içeren yanıtlar demektir. Yüksek çaba, modelin derin düşünmesi için zaman ayırması anlamına gelir. Görevin karmaşıklığına göre çaba seviyesi ayarlamayı öğreniyorsunuz — basit sorularda zaman harcamayın, ama karmaşık kararlarda acele etmeyin. **Yapı Davranışı Yönlendirir** -Promptlardaki XML etiketlerine dikkat ettiniz mi? Sadece süs değil. Modeller, serbest metinden çok yapılandırılmış talimatları daha güvenilir takip eder. Çok adımlı süreçler veya karmaşık mantık gerektiğinde, yapı modelin nerede olduğunu ve sıradakini izlemesine yardımcı olur. Aşağıdaki diyagram, iyi yapılandırılmış bir promptu parçalarına ayırır; ``, ``, ``, ``, ve `` gibi etiketlerin talimatlarınızı nasıl net bölümlere organize ettiğini gösterir. +Sorgulardaki XML etiketlerine dikkat ettiniz mi? Süs için değil. Modeller yapılandırılmış talimatları serbest metinden daha güvenilir izler. Çok aşamalı süreçler veya karmaşık mantık gerektiğinde, yapı modelin nerede olduğunu ve sırada ne olduğunu takip etmesine yardımcı olur. Aşağıdaki diyagram, iyi yapılandırılmış bir sorguyu parçalar, ``, ``, ``, `` ve `` gibi etiketlerin talimatlarınızı nasıl net bölümlere ayırdığını gösterir. Prompt Yapısı -*Açık bölümler ve XML tarzı organizasyona sahip iyi yapılandırılmış bir promptun anatomisi* +*Net bölümlere ve XML tarzı organizasyona sahip iyi yapılandırılmış bir sorgunun anatomisi* -**Kendi Kendini Değerlendirme ile Kalite** +**Kalite Kendini Değerlendirme ile** -Öz-değerlendiren desenler, kalite kriterlerini açıkça belirterek çalışır. Modelin "doğru yapmasını ummak" yerine, tam olarak "doğru"nun ne demek olduğunu söylersiniz: doğru mantık, hata yönetimi, performans, güvenlik. Model kendi çıktısını değerlendirebilir ve iyileştirebilir. Bu, kod üretimini bir piyangodan sürece dönüştürür. +Kendini değerlendiren kalıplar, kalite kriterlerini açık hale getirerek çalışır. Modelin "doğru yapacağını" ummak yerine, "doğru"nun ne anlama geldiğini kesin olarak söylersiniz: doğru mantık, hata yönetimi, performans, güvenlik. Model kendi çıktısını değerlendirebilir ve geliştirebilir. Bu, kod üretimini bir piyangodan sürece dönüştürür. -**Bağlam Sınırlıdır** +**Kontekst Sınırlıdır** -Çok turlu sohbetler, her istekte mesaj geçmişinin dahil edilmesiyle çalışır. Ancak bir sınır vardır - her modelin maksimum token sayısı vardır. Sohbetler büyüdükçe, ilgili bağlamı korurken bu limite ulaşmamak için stratejiler gerekir. Bu modül, belleğin nasıl çalıştığını gösterir; ileride ne zaman özetleneceğinizi, ne zaman unutacağınızı ve ne zaman geri çağıracağınızı öğrenirsiniz. +Çok turlu sohbetler, her istekte mesaj geçmişini dahil ederek işler. Ama bir sınır vardır — her modelin maksimum token sayısı vardır. Sohbet uzadıkça, ilgili bağlamı korumak için stratejiler gerekir, bu modül, hafızanın nasıl çalıştığını gösterir; daha sonra ne zaman özetleneceğini, ne zaman unutulacağını ve ne zaman geri çağrılacağını öğrenirsiniz. ## Sonraki Adımlar @@ -604,5 +604,5 @@ Promptlardaki XML etiketlerine dikkat ettiniz mi? Sadece süs değil. Modeller, **Feragatname**: -Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba göstersek de, otomatik çevirilerin hatalar veya yanlışlıklar içerebileceğini lütfen unutmayın. Orijinal belge, kendi ana dilinde resmi kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu oluşabilecek yanlış anlamalar veya yorumlamalardan sorumlu değiliz. +Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz. \ No newline at end of file diff --git a/translations/tr/03-rag/README.md b/translations/tr/03-rag/README.md index 6a1db27df..e838998cf 100644 --- a/translations/tr/03-rag/README.md +++ b/translations/tr/03-rag/README.md @@ -1,144 +1,143 @@ -# Modül 03: RAG (Geri Getirmeyle Desteklenen Üretim) +# Modül 03: RAG (Arama Destekli Üretim) ## İçindekiler -- [Video Gezdirmesi](../../../03-rag) -- [Neler Öğreneceksiniz](../../../03-rag) -- [Ön Koşullar](../../../03-rag) -- [RAG'ın Anlaşılması](../../../03-rag) - - [Bu Eğitim Hangi RAG Yaklaşımını Kullanıyor?](../../../03-rag) -- [Nasıl Çalışır](../../../03-rag) - - [Belge İşleme](../../../03-rag) - - [Gömmeler Oluşturma](../../../03-rag) - - [Anlamsal Arama](../../../03-rag) - - [Cevap Üretme](../../../03-rag) -- [Uygulamayı Çalıştırın](../../../03-rag) -- [Uygulamayı Kullanma](../../../03-rag) - - [Belge Yükleme](../../../03-rag) - - [Sorular Sorun](../../../03-rag) - - [Kaynak Referanslarını Kontrol Etme](../../../03-rag) - - [Sorularla Deney Yapma](../../../03-rag) -- [Anahtar Kavramlar](../../../03-rag) - - [Parçalama Stratejisi](../../../03-rag) - - [Benzerlik Skorları](../../../03-rag) - - [Bellek içi Depolama](../../../03-rag) - - [Bağlam Penceresi Yönetimi](../../../03-rag) -- [RAG Ne Zaman Önemlidir](../../../03-rag) -- [Sonraki Adımlar](../../../03-rag) - -## Video Gezdirmesi - -Bu modülle başlamayı anlatan canlı oturumu izleyin: +- [Video Rehberi](#video-rehberi) +- [Neler Öğreneceksiniz](#neler-öğreneceksiniz) +- [Ön Koşullar](#ön-koşullar) +- [RAG'ı Anlamak](#ragı-anlamak) + - [Bu Eğitim Hangi RAG Yaklaşımını Kullanıyor?](#bu-eğitim-hangi-rag-yaklaşımını-kullanıyor) +- [Nasıl Çalışır](#nasıl-çalışır) + - [Belge İşleme](#belge-i̇şleme) + - [Gömüler Oluşturma](#gömüler-oluşturma) + - [Anlamsal Arama](#anlamsal-arama) + - [Yanıt Üretimi](#yanıt-oluşturma) +- [Uygulamayı Çalıştırma](#uygulamayı-çalıştırma) +- [Uygulamayı Kullanma](#uygulama-kullanımı) + - [Belge Yükleme](#belge-yükleme) + - [Sorular Sorma](#sorular-sorun) + - [Kaynak Referanslarını Kontrol Etme](#kaynak-referanslarını-kontrol-edin) + - [Sorularla Deney Yapma](#sorularla-deney-yapın) +- [Anahtar Kavramlar](#temel-kavramlar) + - [Parçalama Stratejisi](#parça-bölme-stratejisi) + - [Benzerlik Skorları](#benzerlik-puanları) + - [Bellek İçi Depolama](#bellek-i̇çi-depolama) + - [Bağlam Penceresi Yönetimi](#bağlam-penceresi-yönetimi) +- [RAG Ne Zaman Önemlidir](#rag-ne-zaman-önemlidir) +- [Sonraki Adımlar](#sonraki-adımlar) + +## Video Rehberi + +Bu modüle nasıl başlanacağını anlatan canlı oturumu izleyin: LangChain4j ile RAG - Canlı Oturum ## Neler Öğreneceksiniz -Önceki modüllerde, yapay zeka ile nasıl sohbet edileceğini ve istemlerinizi nasıl yapılandıracağınızı öğrendiniz. Ancak temel bir sınırlama vardır: dil modelleri yalnızca eğitim sırasında öğrendiklerini bilir. Şirketinizin politikaları, proje dokümantasyonunuz veya eğitilmediği herhangi bir bilgi hakkında soruları cevaplayamazlar. +Önceki modüllerde AI ile nasıl sohbet edeceğinizi ve istemlerinizi etkili şekilde yapılandırmayı öğrendiniz. Ancak temel bir sınırlama var: dil modelleri yalnızca eğitim sırasında öğrendiklerini bilir. Şirket politikalarınız, proje dokümantasyonunuz veya eğitilmedikleri herhangi bir bilgi hakkında soruları yanıtlayamazlar. -RAG (Geri Getirmeyle Desteklenen Üretim) bu sorunu çözer. Modelinize bilgilerinizi öğretmeye çalışmak (ki bu pahalı ve pratik değildir) yerine, belgelere göz atma yeteneği verirsiniz. Bir kişi soru sorduğunda, sistem ilgili bilgileri bulur ve isteme ekler. Model ardından bu alınan bağlama dayanarak yanıt verir. +RAG (Arama Destekli Üretim) bu sorunu çözer. Modele bilgilerinizi öğretmeye çalışmak (ki bu hem maliyetli hem de pratik değildir) yerine, ona dokümanlarınızda arama yapma yeteneği verirsiniz. Birisi soru sorduğunda, sistem ilgili bilgileri bulur ve isteme ekler. Model de cevapları bu alınan bağlama dayanarak üretir. -RAG'ı modele referans kütüphanesi vermek gibi düşünebilirsiniz. Bir soru sorulduğunda sistem: +RAG’ı modele bir başvuru kütüphanesi vermek gibi düşünün. Bir soru sorduğunuzda sistem: -1. **Kullanıcı Sorgusu** – Siz bir soru sorarsınız -2. **Gömme** – Sorunuz vektöre dönüştürülür -3. **Vektör Araması** – Benzer belge parçalarını bulur -4. **Bağlam Montajı** – İlgili parçaları isteme ekler -5. **Yanıt** – LLM, bağlama dayanarak bir cevap üretir +1. **Kullanıcı Sorgusu** - Siz soru sorarsınız +2. **Gömüleme** - Sorunuzu vektöre çevirir +3. **Vektör Arama** - Benzer belge parçalarını bulur +4. **Bağlam Derleme** - İlgili parçaları isteme ekler +5. **Cevap** - LLM, bağlama dayanarak cevap üretir -Bu, modelin yanıtlarını eğitim bilgisine dayanmak yerine gerçek verilerinize dayandırır ve uydurmasına engel olur. +Bu sayede modelin yanıtları eğitim bilgisine ya da tahmine değil, gerçek verilerinize dayanır. ## Ön Koşullar -- [Modül 00 - Hızlı Başlangıç](../00-quick-start/README.md) tamamlanmış olması (bu modülde daha sonra referans verilen Kolay RAG örneği için) -- [Modül 01 - Giriş](../01-introduction/README.md) tamamlanmış olması (Azure OpenAI kaynakları dağıtılmış, özellikle `text-embedding-3-small` gömme modeli dahil) -- Kök dizinde Azure kimlik bilgileri içeren `.env` dosyası (Modül 01'de `azd up` komutuyla oluşturulur) +- [Modül 01 - Giriş](../01-introduction/README.md) tamamlanmış (Azure OpenAI kaynakları dağıtılmış, `text-embedding-3-small` gömülü modeli dahil) +- Kök dizinde Azure kimlik bilgileri içeren `.env` dosyası (Modül 01'de `azd up` ile oluşturuldu) -> **Not:** Eğer Modül 01 tamamlanmadıysa, önce oradaki dağıtım talimatlarını izleyin. `azd up` komutu bu modülün kullandığı GPT sohbet modeli ve gömme modelini dağıtır. +> **Not:** Eğer Modül 01 tamamlanmadıysa önce oradaki dağıtım talimatlarını izleyin. `azd up` komutu hem GPT sohbet modeli hem de bu modülde kullanılan gömü modeli dağıtır. -## RAG'ın Anlaşılması +## RAG'ı Anlamak -Aşağıdaki diyagram temel kavramı gösterir: modelin sadece eğitim verisine dayanmak yerine, her cevap üretmeden önce belgelerinizi danışabileceği bir referans kitaplığı sağlanır. +Aşağıdaki diyagram temel kavramı gösterir: modele sadece eğitim verilerini kullanmak yerine, cevap üretmeden önce danışması için belgelerinizden bir başvuru kütüphanesi verilmektedir. RAG Nedir -*Bu diyagram standart bir LLM (eğitim verisinden tahmin yapan) ile RAG destekli bir LLM (önce belgelerinize danışan) arasındaki farkı gösterir.* +*Bu diyagram standart bir LLM (eğitimden tahmin yapar) ile RAG destekli bir LLM (önce belgelerinize danışar) arasındaki farkı gösterir.* -Parçalar uçtan uca nasıl bağlanır? Kullanıcı sorusu dört aşamadan geçer — gömme, vektör arama, bağlam montajı ve cevap üretimi — her biri öncekinin üzerine inşa edilir: +Aşağıda, parçaların baştan sona nasıl bağlandığı gösterilmiştir. Bir kullanıcının sorusu dört aşamadan geçer — gömüleme, vektör arama, bağlam derleme ve yanıt üretimi — her aşama bir öncekine dayanır: RAG Mimarisi -*Bu diyagram uçtan uca RAG hattını gösterir — kullanıcı sorgusu gömme, vektör arama, bağlam montajı ve cevap üretiminden geçer.* +*Bu diyagram, bir kullanıcının sorgusunun gömüleme, vektör arama, bağlam derleme ve yanıt üretimi süreçlerinden geçtiği RAG hattını gösterir.* -Modülün geri kalan kısmı, çalıştırıp değiştirebileceğiniz kodlarla her aşamayı detaylı şekilde açıklar. +Modülün geri kalanı, her aşamayı çalıştırıp değiştirebileceğiniz kod ve diyagramlarla ayrıntılı anlatır. ### Bu Eğitim Hangi RAG Yaklaşımını Kullanıyor? -LangChain4j, farklı soyutlama seviyelerinde RAG uygulamak için üç yol sağlar. Aşağıdaki diyagram bunları yan yana kıyaslar: +LangChain4j, farklı soyutlama seviyeleriyle uygulanan üç RAG yöntemi sunar. Aşağıdaki diyagram yan yana karşılaştırır: -LangChain4j'deki Üç RAG Yaklaşımı +LangChain4j'de Üç RAG Yaklaşımı -*Bu diyagram, Easy, Native ve Advanced olmak üzere üç LangChain4j RAG yaklaşımını — temel bileşenleri ve ne zaman kullanılacaklarını — karşılaştırır.* +*Bu diyagram, LangChain4j'nin Easy, Native ve Advanced RAG yaklaşımlarını temel bileşenleri ve ne zaman kullanıldıkları ile karşılaştırır.* -| Yaklaşım | Ne Yapar | Takas | +| Yaklaşım | Ne Yapar | Dezavantajı | |---|---|---| -| **Kolay RAG** | Her şeyi `AiServices` ve `ContentRetriever` üzerinden otomatik bağlar. Bir arayüzü açıklarsınız, bir retriever eklersiniz, LangChain4j gömme, arama ve istem montajını perde arkasında halleder. | Minimum kod, ancak her adımda neler olduğunu görmezsiniz. | -| **Yerel RAG** | Gömme modelini çağırır, depoyu arar, istemi oluşturur ve cevabı kendiniz üretirsiniz — her adım açıkça yazılır. | Daha fazla kod, ancak her aşama görünür ve değiştirilebilir. | -| **İleri RAG** | Üretim düzeyinde boru hatları için takılabilir sorgu dönüştürücüler, yönlendiriciler, yeniden sıralayıcılar ve içerik enjektörleri içeren `RetrievalAugmentor` framework'ünü kullanır. | En fazla esneklik, fakat önemli ölçüde daha karmaşık. | +| **Easy RAG** | Tüm süreci `AiServices` ve `ContentRetriever` üzerinden otomatik olarak bağlar. Bir arayüz tanımlayıp retriever ekliyorsunuz, LangChain4j gömüleme, arama ve istem derlemeyi arka planda hallediyor. | Kod minimal ama her adım görünmüyor. | +| **Native RAG** | Gömü modelini çağırır, deposunu arar, istemi kendiniz oluşturur ve cevabı üretirsiniz — her adım açıkça yazılır. | Daha fazla kod ama her aşama görünür ve değiştirilebilir. | +| **Advanced RAG** | `RetrievalAugmentor` çerçevesi kullanır; sorgu dönüştürücüler, yönlendiriciler, yeniden sıralayıcılar ve içerik enjeksiyonları kullanımına izin verir. | Maksimum esneklik ama çok daha karmaşık. | -**Bu eğitim Yerel (Native) yaklaşımı kullanır.** RAG hattının her adımı — sorguyu gömme, vektör dükkanında arama, bağlamı monte etme ve cevabı üretme — [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) dosyasında açıkça yazılmıştır. Bu kasıtlıdır: öğrenme kaynağı olarak, kodun minimize edilmesinden çok her aşamayı görmek ve anlamak önemlidir. Parçaların nasıl oturduğuna alıştıktan sonra hızlı prototipler için Kolay RAG'a veya üretim sistemleri için İleri RAG'a geçebilirsiniz. +**Bu eğitim Native yaklaşımı kullanır.** RAG hattının her adımı — sorguyu gömülemek, vektör deposunu aramak, bağlamı derlemek ve cevabı üretmek — [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) içinde açıkça yazılmıştır. Bu bilinçli bir tercihtir; öğrenme kaynağı olarak her adımı görmeniz ve anlamanız, kodun asgari olması kadar önemlidir. Parçaların nasıl birleştiğine hakim olduktan sonra, hızlı prototipler için Easy RAG’ye ya da prodüksiyon sistemleri için Advanced RAG’ye geçebilirsiniz. -> **💡 Kolay RAG'ı daha önce gördünüz mü?** [Hızlı Başlangıç modülü](../00-quick-start/README.md) Kolay RAG yaklaşımını kullanan Bir Belge Soru-Cevap örneği (`SimpleReaderDemo.java`) içerir — LangChain4j gömme, arama ve istem montajını otomatik olarak halleder. Bu modül, o hattı açarak her aşamanın kendiniz tarafından görülebilmesini ve kontrol edilmesini sağlar. +> **💡 Easy RAG merak ettiyseniz?** LangChain4j, `AiServices` ve `ContentRetriever` ile gömüleme, arama ve istem derlemeyi otomatik yapan *Easy RAG* yaklaşımı da sunar. Bu modül ise biraz daha açık bir yolu seçer — hattı açarak her aşamayı görmenizi ve kontrol etmenizi sağlar. -Aşağıdaki diyagram, Hızlı Başlangıç örneğinden Kolay RAG hattını gösterir. Gördüğünüz gibi `AiServices` ve `EmbeddingStoreContentRetriever` tüm karmaşıklığı gizler — belgeyi yüklersiniz, retriever eklersiniz ve cevap alırsınız. Bu modüldeki Yerel yaklaşım, o gizli adımların her birini açar: +Aşağıdaki diyagram Easy RAG hattını gösterir. `AiServices` ve `EmbeddingStoreContentRetriever` tüm karmaşıklığı gizler — belge yüklersiniz, retriever ekler ve cevaplar alırsınız. Bu modülde kullanılan Native yaklaşım, o gizli adımları açar: -Kolay RAG Hattı - LangChain4j +Easy RAG Hattı - LangChain4j -*Bu diyagram `SimpleReaderDemo.java` dosyasından Kolay RAG hattını gösterir. Bu modülde kullanılan Yerel yaklaşım ile kıyaslayın: Kolay RAG gömme, retrieval ve istem montajını `AiServices` ve `ContentRetriever` arkasına gizler — belgeyi yüklersiniz, retriever eklersiniz, cevap alırsınız. Bu modüldeki Yerel yaklaşım ise hattı açar, böylece her aşamayı (gömme, arama, bağlam oluşturma, üretim) kendiniz çağırır ve tam görünürlük ile kontrol sağlar.* +*Bu diyagram Easy RAG hattını gösterir. Modülde kullanılan Native yaklaşım ile karşılaştırın: Easy RAG, gömüleme, arama ve istem derlemeyi `AiServices` ve `ContentRetriever` arkasına gizler — belge yüklersiniz, retriever ekler ve cevap alırsınız. Native yaklaşım ise o hattı açar, her aşamayı (gömüle, ara, bağlamı derle, üret) sizin çağırmanızı sağlar, tam görünürlük ve kontrol verir.* ## Nasıl Çalışır -Bu modüldeki RAG hattı, bir kullanıcı her soru sorduğunda ardışık olarak çalışan dört aşamaya ayrılır. İlk olarak, yüklenen belge **parçalanır ve bölünür** — modelin bağlam penceresine sığacak küçük parçalara. Sonra bu parçalar **vektör gömmelerine** dönüştürülür ve matematiksel karşılaştırmaya hazır şekilde saklanır. Sorgu geldiğinde, sistem en ilgili parçaları bulmak için **anlamsal arama** yapar ve son olarak bu parçaları bağlam olarak LLM'ye **cevap oluşturma** için verir. Aşağıdaki bölümler her aşamayı gerçek kod ve diyagramlarla açıklar. İlk adıma bakalım. +Bu modüldeki RAG hattı, bir kullanıcı her soru sorduğunda sıralı olarak çalışan dört aşamaya ayrılır. İlk olarak yüklenen belge **parçalanır ve işlenir**. Bu parçalar sonra **vektör gömülerine** dönüştürülür ve matematiksel karşılaştırma için saklanır. Sorgu geldiğinde, sistem **anlamsal arama** yaparak en ilgili parçaları bulur ve son olarak LLM’ye **yanıt üretimi** için bağlam olarak gönderir. Aşağıdaki bölümler her aşamayı kod ve diyagramlarla anlatır. İlk adıma bakalım. ### Belge İşleme [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Bir belge yüklediğinizde, sistem onu (PDF veya düz metin) ayrıştırır, dosya adı gibi meta veriler ekler ve sonra modele kolayca sığacak şekilde küçük parçalara böler. Bu parçalar, sınırda bağlam kaybı olmaması için biraz üst üste binerler. +Belge yüklediğinizde, sistem onu ayrıştırır (PDF veya düz metin), dosya adı gibi meta veriler ekler, sonra da modelin bağlam penceresine rahatça sığacak küçük parçalara böler. Bu parçalar birbirleriyle hafifçe örtüşür; böylece sınır bölgelerinde bağlam kaybolmaz. ```java -// Yüklenen dosyayı ayrıştırın ve LangChain4j Belgesi içinde sarın +// Yüklenen dosyayı analiz edin ve LangChain4j Belgesi içinde sarın Document document = Document.from(content, metadata); -// 30 token örtüşme ile 300 token parçalarına bölün +// 30 token örtüşme ile 300 tokenluk parçalara bölünüz DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -Aşağıdaki diyagram bunu görsel olarak gösterir. Her parçanın komşularıyla 30 token kadar üst üste binmesi, önemli bağlamın kaybolmamasını sağlar: + +Aşağıdaki diyagram bunu görsel olarak gösterir. Her parçanın komşularıyla bazı token'ları paylaştığına dikkat edin — 30 token’lık örtüşme, önemli bağlamın kırılmasını önler: Belge Parçalama -*Bu diyagram, belgeyi 30 token üst üste binmeli 300 tokenlık parçalara bölünürken bağlamın korunduğunu gösterir.* +*Bu diyagram, bir belgenin 300 token parçalar halinde, her parçanın 30 token örtüşmesi olacak şekilde bölünmesini gösterir. Bu, parça sınırlarında bağlamın korunmasını sağlar.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) dosyasını açın ve sorun: -> - "LangChain4j belgeleri parçalara nasıl ayırıyor ve üst üste binme neden önemli?" -> - "Farklı belge türleri için en uygun parça boyutu nedir ve neden?" -> - "Çok dilli veya özel biçimlendirme içeren belgelerle nasıl başa çıkabilirim?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) dosyasını açın ve sorun: +> - "LangChain4j belgeleri nasıl parçalara ayırıyor ve neden örtüşme önemli?" +> - "Farklı belge türleri için ideal parça büyüklüğü nedir ve neden?" +> - "Çok dilli veya özel formatlama içeren belgelerle nasıl başa çıkarım?" -### Gömmeler Oluşturma +### Gömüler Oluşturma [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Her parça, gömme denilen sayısal bir temsile dönüştürülür — temelde anlamdan sayıya çeviri. Gömme modeli, sohbet modeli gibi "zeki" değildir; talimatları takip edemez, mantık yürütemez veya soru cevaplayamaz. Söyleyebileceği şey, benzer anlamların yakın vektörler aldığı bir matematiksel uzay yaratmaktır — "araba" ve "otomobil" yan yana, "para iade politikası" ve "paramı geri al" de yakın. Sohbet modeli, konuştuğunuz bir kişi gibidir; gömme modeli ise çok iyi organize edilmiş bir dosyalama sistemidir. +Her parça bir gömüye dönüştürülür — anlamdan sayılara çevirme işlemi. Gömü modeli sohbet modeli gibi "zeki" değildir; talimatları takip edemez, mantık kuramaz ya da soruları yanıtlayamaz. Yapabildiği, benzer anlamları birbirine yakın vektörlerle matematiksel bir uzaya haritalamaktır — "araba" "otomobil"in yanında, "iade politikası" "paramı geri al"ın yanında yer alır. Soğuk bir sohbet modeli bir insan gibidir, gömü modeli ise çok iyi bir dosyalama sistemidir. -Aşağıdaki diyagram bu konsepti görselleştirir — metin girer, sayısal vektörler çıkar, benzer anlamlar vektör uzayında yakın yerde toplanır: +Aşağıdaki diyagram bu kavramı görselleştirir — metin girer, sayısal vektör çıkar ve benzer anlamlar yakın vektörler üretir: -Gömme Modeli Konsepti +Gömü Modeli Kavramı -*Bu diyagram, gömme modelinin metni sayısal vektörlere çevirdiğini ve "araba" ile "otomobil" gibi benzer anlamları vektör uzayında yakınlaştırdığını gösterir.* +*Bu diyagram, bir gömü modelinin metni sayısal vektörlere nasıl dönüştürdüğünü ve "araba" ile "otomobil" gibi benzer anlamları uzayda yakına yerleştirdiğini gösterir.* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -Aşağıdaki sınıf diyagramı, RAG hattında iki ayrı akışı ve LangChain4j sınıflarını gösterir. **Alım akışı** (yükleme zamanında bir kez çalışır) belgeyi böler, parçaları gömer ve `.addAll()` ile depolar. **Sorgu akışı** (her kullanıcı sorusunda çalışır) soruyu gömer, `.search()` ile arama yapar ve bulunan bağlamı sohbet modeline verir. İki akış, ortak `EmbeddingStore` arayüzünde buluşur: + +Aşağıdaki sınıf diyagramı, RAG hattındaki iki ayrı akışı ve bunları uygulayan LangChain4j sınıflarını gösterir. **Yükleme akışı** (sadece yükleme sırasında çalışır) belgeyi parçalar, gömüleri oluşturur ve `.addAll()` ile depolar. **Sorgu akışı** (kullanıcı her sorunca çalışır) soruyu gömüler, `.search()` ile arama yapar ve eşleşen bağlamı sohbet modeline verir. İki akış ortak `EmbeddingStore` arayüzünde buluşur: LangChain4j RAG Sınıfları -*Bu diyagram, RAG hattındaki iki akışı — alım ve sorgu — ve bunların ortak bir EmbeddingStore üzerinden nasıl bağlandığını gösterir.* +*Bu diyagram RAG hattındaki iki akışı — yükleme ve sorgu — ve bunların ortak EmbeddingStore üzerinden nasıl bağlandığını gösterir.* -Gömmeler depolandıktan sonra benzer içerikler vektör uzayında doğal olarak kümelenir. Aşağıdaki görselleştirme, ilgili konuların yakın noktalarda olduğunu gösterir; bu da anlamsal aramayı mümkün kılar: +Gömüler depolandıktan sonra benzer içerikler doğal olarak vektör uzayında kümelenir. Aşağıdaki görselleştirme, ilgili konulardaki belgelerin nasıl yan yana noktalar olarak toplandığını ve bunun anlamsal aramayı mümkün kıldığını gösterir: -Vektör Gömme Uzayı +Vektör Gömü Uzayı -*Bu görselleştirme, Teknik Dokümanlar, İş Kuralları ve SSS gibi konuların 3D vektör uzayında nasıl ayrı gruplar oluşturduğunu gösterir.* +*Bu görselleştirme, teknik dokümanlar, iş kuralları ve SSS gibi konuların 3D vektör uzayında nasıl farklı kümeler oluşturduğunu gösterir.* -Bir kullanıcı arama yaptığında sistem dört adım takip eder: belgeleri bir kez gömmek, her aramada sorguyu gömmek, sorgu vektörünü tüm kayıtlı vektörlerle kosinüs benzerliğiyle karşılaştırmak ve en yüksek puanlı üst-K parçaları döndürmek. Aşağıdaki diyagram her adımı ve ilgili LangChain4j sınıflarını gösterir: +Kullanıcı arama yaptığında sistem dört adımı izler: belgeleri bir kez gömüler, her aramada sorguyu gömüler, sorgu vektörü ile tüm saklanan vektörleri kosinüs benzerliğiyle karşılaştırır ve en yüksek puanlı top-K parçaları döner. Aşağıdaki diyagram her adımı ve LangChain4j sınıflarını anlatır: -Gömme Arama Adımları +Gömü Arama Adımları -*Bu diyagram, gömme arama sürecinin dört aşamasını gösterir: belgeleri gömme, sorguyu gömme, vektörleri kosinüs benzerliği ile karşılaştırma ve en iyi sonuçları döndürme.* +*Bu diyagram dört aşamalı gömü arama sürecini gösterir: belgeleri gömüle, sorguyu gömüle, kosinüs benzerliğiyle vektörleri karşılaştır, top-K sonuçları döndür.* ### Anlamsal Arama [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Bir soru sorduğunuzda, sorunuz da gömme haline gelir. Sistem, soru gömesini tüm belge parçalarının gömeleriyle karşılaştırır. Sadece anahtar kelime eşleşmesi değil, gerçek anlamsal benzerlik arar ve en yakın anlamları bulur. +Soru sorduğunuzda, sorunuzu da gömülmüş bir vektöre dönüştürür. Sistem, sorunuzun gömüsünü tüm belge parçalarının gömüleriyle karşılaştırır. En benzer anlamdaki parçaları bulur — sadece anahtar kelimeleri eşleştirmekle kalmaz, gerçek anlamsal benzerliği değerlendirir. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -Aşağıdaki diyagram anlamsal arama ile geleneksel anahtar kelime arama arasındaki farkı gösterir. "Araç" anahtar kelimesiyle yapılan arama, "arabalar ve kamyonlar" ile ilgili bir parçayı atlar, ancak anlamsal arama bunların aynı anlama geldiğini anlar ve yüksek puanlı sonuç olarak döndürür: + +Aşağıdaki diyagram anlamsal aramayı geleneksel anahtar kelime aramasıyla karşılaştırır. "Vehicle" kelimesi için yapılan anahtar kelime araması "cars and trucks" olan bir parçayı kaçırır; ancak anlamsal arama, bunun aynı anlama geldiğini fark eder ve yüksek puanlı eşleşme olarak getirir: Anlamsal Arama -*Bu diyagram, anahtar kelime tabanlı arama ile anlamsal arama arasındaki farkı gösterir; anlamsal arama, tam anahtar kelime farklılığı olsa bile kavramsal olarak ilişkili içeriği getirir.* -Motorun altında, benzerlik kosinüs benzerliği kullanılarak ölçülür — temelde "bu iki ok aynı yöne mi işaret ediyor?" diye sorar. İki parça tamamen farklı kelimeler kullanabilir, ancak aynı şeyi ifade ediyorlarsa vektörleri aynı yöne işaret eder ve skorları 1.0'a yakın olur: +*Bu diyagram, anahtar kelimeye dayalı arama ile anlamsal aramayı karşılaştırır; anlamsal arama, tam anahtar kelimeler farklı olsa bile kavramsal olarak ilgili içerikleri getirir.* -Kosinüs Benzerliği +Altta yatan benzerlik ölçütü kosinüs benzerliğidir — yani "bu iki ok aynı yöne mi bakıyor?" sorusunu sorar. İki parça tamamen farklı kelimeler kullansa da aynı anlama geliyorlarsa vektörleri aynı yöne bakar ve skorları 1.0'a yakın olur: -*Bu diyagram, gömme vektörler arasındaki açıyı kosinüs benzerliği olarak göstermektedir — daha hizalanmış vektörler 1.0'a daha yakın skor alır, bu da daha yüksek anlamsal benzerliği gösterir.* +Kosinüs Benzerliği +*Bu diyagram, gömme vektörler arasındaki açı olarak kosinüs benzerliğini gösterir — daha hizalanmış vektörler 1.0'a daha yakın puan alır, bu da daha yüksek anlamsal benzerlik anlamına gelir.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) dosyasını açın ve sorun: -> - "Benzerlik araması gömmelerle nasıl çalışır ve skoru ne belirler?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Sohbet ile deneyin:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) dosyasını açın ve sorun: +> - "Benzerlik araması gömme vektörlerle nasıl çalışır ve puanı ne belirler?" > - "Hangi benzerlik eşiğini kullanmalıyım ve bu sonuçları nasıl etkiler?" -> - "İlgili belge bulunamadığında nasıl işlem yapmalıyım?" +> - "İlgili belge bulunamadığında nasıl bir yol izlemeliyim?" -### Yanıt Üretimi +### Yanıt Oluşturma [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -En alakalı parçalar, açık talimatlar, alınan bağlam ve kullanıcının sorusunu içeren yapılandırılmış bir prompt oluşturmak için birleştirilir. Model bu belirli parçaları okur ve bu bilgiye dayanarak cevap üretir — sadece önündeki bilgiyi kullanabilir, bu halüsinasyonu önler. +En alakalı parçalar, açık talimatlar, getirilen bağlam ve kullanıcının sorusunu içeren yapılandırılmış bir isteme birleştirilir. Model bu belirli parçaları okur ve bu bilgilere dayanarak yanıt verir — sadece önünde olanı kullanabilir, bu da yanılsamayı önler. ```java String context = matches.stream() @@ -237,189 +236,189 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Aşağıdaki diyagram bu birleştirmenin nasıl çalıştığını gösterir — arama adımından en yüksek skorlu parçalar prompt şablonuna eklenir ve `OpenAiOfficialChatModel` somut bir yanıt üretir: +Aşağıdaki diyagram bu birleştirmeyi gösterir — arama adımındaki en yüksek puanlı parçalar istem şablonuna yerleştirilir ve `OpenAiOfficialChatModel` sağlam bir yanıt oluşturur: Bağlam Birleştirme -*Bu diyagram, en yüksek skorlu parçaların nasıl yapılandırılmış bir prompt’a birleştirildiğini ve böylece modelin verilerinizden somut bir cevap üretmesini sağladığını gösterir.* +*Bu diyagram, en yüksek puanlı parçaların yapılandırılmış bir isteme nasıl birleştirildiğini gösterir, böylece model verilerinizden sağlam bir yanıt oluşturabilir.* ## Uygulamayı Çalıştırma **Dağıtımı doğrulayın:** -`.env` dosyasının kök dizinde olduğunu ve Azure kimlik bilgilerini içerdiğini kontrol edin (Modül 01 sırasında oluşturuldu). Modül dizininden (`03-rag/`) bunu çalıştırın: +Kök dizinde Azure kimlik bilgileri içeren `.env` dosyasının var olduğundan emin olun (Modül 01 sırasında oluşturuldu). Modül dizininden (`03-rag/`) şunu çalıştırın: -**Bash:** +**Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT gösterilmelidir +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT göstermeli ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT göstermeli ``` - + **Uygulamayı başlatın:** -> **Not:** Eğer kök dizinden `./start-all.sh` kullanarak tüm uygulamaları zaten başlattıysanız (Modül 01'de açıklandığı gibi), bu modül zaten 8081 portunda çalışıyor. Aşağıdaki başlatma komutlarını atlayabilir ve doğrudan http://localhost:8081 adresine gidebilirsiniz. +> **Not:** Daha önce root dizinden `./start-all.sh` komutu ile tüm uygulamaları başlattıysanız (Modül 01'de açıklandı), bu modül zaten 8081 portunda çalışıyor. Aşağıdaki başlatma komutlarını atlayabilir ve doğrudan http://localhost:8081 adresine gidebilirsiniz. -**Seçenek 1: Spring Boot Dashboard kullanımı (VS Code kullanıcıları için önerilir)** +**Seçenek 1: Spring Boot Dashboard kullanmak (VS Code kullanıcıları için önerilir)** -Geliştirme konteynerinde, tüm Spring Boot uygulamalarını görsel olarak yönetmek için Spring Boot Dashboard uzantısı vardır. VS Code'un solundaki Aktivite Çubuğunda (Spring Boot simgesini arayın) bulabilirsiniz. +Geliştirme konteyneri, tüm Spring Boot uygulamalarını yönetmek için görsel bir arayüz sağlayan Spring Boot Dashboard eklentisini içerir. VS Code'un sol tarafındaki Etkinlik Çubuğunda (Spring Boot simgesine bakın) bulabilirsiniz. -Spring Boot Dashboard’dan: -- Çalışma alanındaki tüm mevcut Spring Boot uygulamalarını görebilir +Spring Boot Dashboard'dan: +- Çalışma alanındaki tüm mevcut Spring Boot uygulamalarını görebilirsiniz - Uygulamaları tek tıkla başlatabilir/durdurabilirsiniz -- Uygulama günlüklerini gerçek zamanlı izleyebilirsiniz -- Uygulama durumunu takip edebilirsiniz +- Gerçek zamanlı uygulama loglarını görüntüleyebilirsiniz +- Uygulama durumunu izleyebilirsiniz -Sadece "rag" karşısındaki oynat butonuna tıklayarak bu modülü başlatın veya tüm modülleri aynı anda başlatın. +Sadece "rag" yanındaki oynat düğmesine tıklayarak bu modülü başlatın ya da tüm modülleri aynı anda başlatın. Spring Boot Dashboard -*Bu ekran görüntüsü VS Code'da Spring Boot Dashboard’u gösterir; burada uygulamaları başlatıp durdurabilir ve görsel olarak izleyebilirsiniz.* +*Bu ekran görüntüsü, VS Code'daki Spring Boot Dashboard'u gösterir; burada uygulamaları görsel olarak başlatabilir, durdurabilir ve izleyebilirsiniz.* -**Seçenek 2: Shell betikleri kullanımı** +**Seçenek 2: Shell scriptleri kullanmak** -Tüm web uygulamalarını başlatın (modüller 01-04): +Tüm web uygulamalarını başlatmak için (modüller 01-04): -**Bash:** +**Bash:** ```bash cd .. # Kök dizinden ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd .. # Kök dizinden .\start-all.ps1 ``` - -Veya sadece bu modülü başlatın: -**Bash:** +Ya da sadece bu modülü başlatın: + +**Bash:** ```bash cd 03-rag ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 03-rag .\start.ps1 ``` - -Her iki betik de otomatik olarak kök `.env` dosyasından ortam değişkenlerini yükler ve JAR dosyaları yoksa derler. -> **Not:** Tüm modülleri elle derlemek isterseniz, başlatmadan önce: +Her iki script de kök `.env` dosyasından çevre değişkenlerini otomatik olarak yükler ve JAR dosyaları mevcut değilse derler. + +> **Not:** Başlatmadan önce tüm modülleri manuel olarak derlemeyi tercih ederseniz: > -> **Bash:** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -> **PowerShell:** +> +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + Tarayıcınızda http://localhost:8081 adresini açın. **Durdurmak için:** -**Bash:** +**Bash:** ```bash ./stop.sh # Sadece bu modül # Veya cd .. && ./stop-all.sh # Tüm modüller ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # Sadece bu modül # Veya cd ..; .\stop-all.ps1 # Tüm modüller ``` - -## Uygulamanın Kullanımı -Uygulama, belge yükleme ve soru sorma için web arayüzü sağlar. +## Uygulama Kullanımı + +Uygulama belge yükleme ve soru sorma için bir web arayüzü sağlar. RAG Uygulama Arayüzü -*Bu ekran görüntüsü RAG uygulama arayüzünü gösterir; burada belgeler yüklenir ve sorular sorulur.* +*Bu ekran görüntüsü, belgelerin yüklendiği ve sorular sorulduğu RAG uygulama arayüzünü gösterir.* ### Belge Yükleme -Öncelikle bir belge yükleyin - TXT dosyaları test için en uygun olanlardır. Bu dizinde LangChain4j özellikleri, RAG uygulaması ve en iyi uygulamalar hakkında bilgi içeren `sample-document.txt` dosyası mevcuttur - sistemi test etmek için idealdir. +Bir belge yükleyerek başlayın — test için TXT dosyaları en uygunudur. Bu dizinde LangChain4j özellikleri, RAG uygulaması ve en iyi uygulamalar hakkında bilgiler içeren `sample-document.txt` sunulmuştur — sistem testi için mükemmeldir. -Sistem belgenizi işler, parçalara böler ve her parça için gömme (embedding) oluşturur. Bu otomatik olarak yükleme sırasında gerçekleşir. +Sistem belgenizi işler, parçalara böler ve her parça için gömme vektörleri oluşturur. Bu işlem otomatik olarak yükleme sırasında gerçekleşir. ### Sorular Sorun -Şimdi, belge içeriği hakkında spesifik sorular sorabilirsiniz. Belgedeki açıkça belirtilmiş gerçeklere yönelik sorular deneyin. Sistem ilgili parçaları arar, bunları prompt’a dahil eder ve cevap üretir. +Şimdi belge içeriği hakkında spesifik sorular sorun. Belge içinde açıkça belirtilmiş somut şeyleri deneyin. Sistem ilgili parçaları arar, bunları isteme ekler ve yanıt oluşturur. ### Kaynak Referanslarını Kontrol Edin -Her cevabın kaynak referansları ve benzerlik skorları içerdiğine dikkat edin. Bu skorlar (0 ile 1 arasında) her parçanın sorunuza ne kadar alakalı olduğunu gösterir. Yüksek skorlar daha iyi eşleşmeler anlamına gelir. Bu, cevabı kaynak materyal ile doğrulamanızı sağlar. +Her yanıtın benzerlik puanları ile birlikte kaynak referanslarını içerdiğine dikkat edin. Bu puanlar (0 ile 1 arasında), her parçanın sorunuza ne kadar alakalı olduğunu gösterir. Daha yüksek puanlar daha iyi eşleştirmeler anlamına gelir. Bu sayede yanıtı kaynak materyale karşı doğrulayabilirsiniz. RAG Sorgu Sonuçları -*Bu ekran görüntüsü, oluşturulan cevapla birlikte sorgu sonuçlarını, kaynak referansları ve her alınan parçanın alaka skorlarını gösterir.* +*Bu ekran görüntüsü, oluşturulan yanıt, kaynak referansları ve her getirilen parçanın alaka puanları ile sorgu sonuçlarını gösterir.* -### Sorularla Deneyler Yapın +### Sorularla Deney Yapın -Farklı soru türlerini deneyin: -- Spesifik gerçekler: "Ana konu nedir?" -- Karşılaştırmalar: "X ve Y arasındaki fark nedir?" +Farklı tür sorular deneyin: +- Belirli gerçekler: "Ana konu nedir?" +- Karşılaştırmalar: "X ile Y arasındaki fark nedir?" - Özetler: "Z hakkında temel noktaları özetle" -Sorunuzun belge içeriğiyle ne kadar iyi eşleştiğine bağlı olarak alaka skorlarının nasıl değiştiğini gözlemleyin. +Sorunuzun belge içeriğiyle ne kadar iyi eşleştiğine bağlı olarak alaka puanlarının nasıl değiştiğine dikkat edin. ## Temel Kavramlar -### Parçalama Stratejisi +### Parça Bölme Stratejisi -Belgeler, 30 token üst üste binmeyle 300 tokenlik parçalara bölünür. Bu denge, her parçanın anlamlı olacak kadar bağlama sahip olmasını ve prompt’a birden fazla parça dahil edilebilmesi için küçük kalmasını sağlar. +Belgeler 300 token uzunluğunda, 30 token örtüşmeli parçalara bölünür. Bu denge, her parçanın anlamlı bir bağlam içermesini sağlarken, istemde birden fazla parçanın yer almasına izin verecek kadar küçük olmasını sağlar. -### Benzerlik Skorları +### Benzerlik Puanları -Her alınan parçaya, kullanıcının sorusuyla ne kadar yakın eşleştiğini gösteren 0 ile 1 arasında bir benzerlik skoru verilir. Aşağıdaki diyagram, skor aralıklarını ve sistemin bunları nasıl kullanarak sonuçları filtrelediğini görselleştirir: +Her getirilen parçaya, kullanıcının sorusuyla ne kadar yakından eşleştiğini gösteren 0 ile 1 arasında bir benzerlik puanı atanır. Aşağıdaki diyagram, puan aralıklarını ve sistemin onları sonuçları filtrelemek için nasıl kullandığını görselleştirir: -Benzerlik Skorları +Benzerlik Puanları -*Bu diyagram, 0 ila 1 arasındaki skor aralıklarını, 0.5’lik minimum eşik değeriyle gösterir; bu eşik, alakasız parçaları filtreler.* +*Bu diyagram 0 ile 1 arasındaki puan aralıklarını ve alakasız parçaları filtreleyen 0.5 minimum eşiğini gösterir.* -Skor aralıkları: -- 0.7-1.0: Çok ilgili, tam eşleşme -- 0.5-0.7: İlgili, iyi bağlam -- 0.5’in altı: Filtrelenen, çok alakasız +Puan aralıkları: +- 0.7-1.0: Çok alakalı, tam eşleşme +- 0.5-0.7: Alakalı, iyi bağlam +- 0.5’in altında: Filtrelenen, çok farklı -Sistem kaliteyi sağlamak için sadece minimum eşiğin üzerindeki parçaları alır. +Sistem sadece minimum eşik üzerindeki parçaları getirerek kalitenin korunmasını sağlar. -Gömme yöntemleri, anlamlar kategorize edildiğinde iyi çalışır, fakat bazı kör noktaları vardır. Aşağıdaki diyagram yaygın başarısızlık durumlarını gösterir — çok büyük parçalar bulanık vektörler üretir, çok küçük parçalar bağlam kaybına yol açar, belirsiz terimler birden fazla kümeye işaret eder ve tam eşleşme aramaları (kimlikler, parça numaraları) gömmelerle hiç çalışmaz: +Gömme vektörler anlam kümeleri net olduğunda iyi çalışır, ancak kör noktalar vardır. Aşağıdaki diyagram yaygın başarısızlık durumlarını gösterir — çok büyük parçalar bulanık vektörler üretir, çok küçük parçalar bağlam eksikliği yaşar, belirsiz terimler birden çok kümeye işaret eder ve net eşleşmeli aramalar (ID'ler, parça numaraları) gömmelerle hiç çalışmaz: Gömme Başarısızlık Modları -*Bu diyagram yaygın gömme başarısızlık modlarını gösterir: Çok büyük veya çok küçük parçalar, birden çok kümeye işaret eden belirsiz terimler ve kimlik gibi tam eşleşme aramaları.* +*Bu diyagram yaygın gömme başarısızlık modlarını gösterir: çok büyük parçalar, çok küçük parçalar, birden çok kümeye işaret eden belirsiz terimler ve ID gibi tam eşleşmeli aramalar.* ### Bellek İçi Depolama -Bu modül basitlik için bellek içi depolama kullanır. Uygulamayı yeniden başlattığınızda, yüklenen belgeler kaybolur. Üretim sistemleri Qdrant veya Azure AI Search gibi kalıcı vektör veritabanları kullanır. +Bu modül basitlik için bellek içi depolama kullanır. Uygulamayı yeniden başlattığınızda yüklenen belgeler kaybolur. Üretim sistemleri kalıcı vektör veritabanları kullanır, örn. Qdrant veya Azure AI Search. ### Bağlam Penceresi Yönetimi -Her modelin maksimum bağlam penceresi vardır. Büyük bir belgeden tüm parçaları dahil edemezsiniz. Sistem, sınırları aşmadan doğru cevap verecek kadar bağlam sağlamak için en alakalı N parçayı (varsayılan 5) alır. +Her modelin maksimum bir bağlam penceresi vardır. Büyük bir belgeden her parçayı dahil edemezsiniz. Sistem, sınırlar içinde kalırken doğru yanıtlar için yeterli bağlam sağlamak üzere en alakalı N parçayı (varsayılan 5) getirir. -## RAG Neden Önemli? +## RAG Ne Zaman Önemlidir? -RAG her zaman doğru yaklaşım değildir. Aşağıdaki karar rehberi, RAG’ın ne zaman değer kattığını ve ne zaman daha basit yaklaşımların — içeriği doğrudan prompt’a dahil etmek veya modelin yerleşik bilgisini kullanmak gibi — yeterli olduğunu belirlemenize yardımcı olur: +RAG her zaman doğru yaklaşım değildir. Aşağıdaki karar rehberi, ne zaman RAG’nin değer kattığını ve ne zaman daha basit yaklaşımların — örn. içeriği direkt isteme eklemek veya modelin kendi bilgi tabanına güvenmek — yeterli olduğunu belirlemenize yardımcı olur: -RAG Ne Zaman Kullanılır? +RAG Ne Zaman Kullanılır -*Bu diyagram, RAG’ın ne zaman değer kattığını ve ne zaman daha basit yaklaşımların yeterli olduğunu gösteren karar rehberidir.* +*Bu diyagram, RAG’nin değer katığı durumlar ile daha basit yaklaşımlar yeterli olduğunda karar vermeye yardımcı olur.* ## Sonraki Adımlar @@ -427,11 +426,11 @@ RAG her zaman doğru yaklaşım değildir. Aşağıdaki karar rehberi, RAG’ın --- -**Gezinme:** [← Önceki: Modül 02 - Prompt Mühendisliği](../02-prompt-engineering/README.md) | [Ana Sayfaya Dön](../README.md) | [Sonraki: Modül 04 - Araçlar →](../04-tools/README.md) +**Gezinme:** [← Önceki: Modül 02 - İstem Mühendisliği](../02-prompt-engineering/README.md) | [Ana Sayfaya Dön](../README.md) | [Sonraki: Modül 04 - Araçlar →](../04-tools/README.md) --- **Feragatname**: -Bu belge, AI çeviri servisi [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hatalar veya yanlışlıklar içerebileceğini lütfen unutmayınız. Orijinal belge, kendi diliyle yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi tavsiye edilir. Bu çevirinin kullanımı sonucunda oluşabilecek yanlış anlaşılmalardan veya yorum hatalarından sorumlu değiliz. +Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz. \ No newline at end of file diff --git a/translations/tr/04-tools/README.md b/translations/tr/04-tools/README.md index a36a48ebb..5df5dd322 100644 --- a/translations/tr/04-tools/README.md +++ b/translations/tr/04-tools/README.md @@ -1,76 +1,76 @@ -# Modül 04: Araçlara Sahip Yapay Zeka Ajanları +# Modül 04: Araçlarla AI Ajanları ## İçindekiler -- [Video Rehberi](../../../04-tools) -- [Öğrenecekleriniz](../../../04-tools) -- [Ön Koşullar](../../../04-tools) -- [Araçlara Sahip Yapay Zeka Ajanlarını Anlamak](../../../04-tools) -- [Araç Çağrısı Nasıl Çalışır](../../../04-tools) - - [Araç Tanımları](../../../04-tools) - - [Karar Verme](../../../04-tools) - - [Yürütme](../../../04-tools) - - [Yanıt Üretimi](../../../04-tools) - - [Mimari: Spring Boot Otomatik Bağlama](../../../04-tools) -- [Araç Zinciri](../../../04-tools) -- [Uygulamayı Çalıştırma](../../../04-tools) -- [Uygulamayı Kullanma](../../../04-tools) - - [Basit Araç Kullanımını Deneyin](../../../04-tools) - - [Araç Zincirini Test Edin](../../../04-tools) - - [Konuşma Akışını Görün](../../../04-tools) - - [Farklı Taleplerle Deneyler Yapın](../../../04-tools) -- [Temel Kavramlar](../../../04-tools) - - [ReAct Deseni (Düşünme ve Hareket Etme)](../../../04-tools) - - [Araç Açıklamaları Önemlidir](../../../04-tools) - - [Oturum Yönetimi](../../../04-tools) - - [Hata Yönetimi](../../../04-tools) -- [Mevcut Araçlar](../../../04-tools) -- [Araç Tabanlı Ajanları Ne Zaman Kullanmalı](../../../04-tools) -- [Araçlar vs RAG](../../../04-tools) -- [Sonraki Adımlar](../../../04-tools) - -## Video Rehberi - -Bu modüle nasıl başlanacağını açıklayan canlı oturumu izleyin: - -AI Agents with Tools and MCP - Live Session - -## Öğrenecekleriniz - -Şimdiye kadar AI ile nasıl sohbet edileceğini, yönlendirme (prompt) yapılarını etkin şekilde oluşturmayı ve yanıtları belgelerinizle ilişkilendirmeyi öğrendiniz. Ancak hâlâ temel bir sınırlama var: dil modelleri yalnızca metin oluşturabilir. Hava durumunu kontrol edemez, hesaplama yapamaz, veri tabanlarını sorgulayamaz veya dış sistemlerle etkileşime geçemez. - -Araçlar bunu değiştirir. Modele çağırabileceği fonksiyonlara erişim vererek, onu metin üreticiden eylem alabilen bir ajana dönüştürürsünüz. Model ne zaman araca ihtiyacı olduğunu, hangi aracı kullanacağını ve hangi parametreleri geçeceğini belirler. Kodunuz fonksiyonu çalıştırır ve sonucu geri döner. Model bu sonucu yanıtına entegre eder. - -## Ön Koşullar +- [Video Yürütme](#video-yürütme) +- [Neler Öğreneceksiniz](#neler-öğreneceksiniz) +- [Önkoşullar](#önkoşullar) +- [Araçlarla AI Ajanlarını Anlamak](#araçlarla-ai-ajanlarını-anlamak) +- [Araç Çağrısı Nasıl Çalışır](#araç-çağrısı-nasıl-çalışır) + - [Araç Tanımları](#araç-tanımları) + - [Karar Verme](#karar-verme) + - [Uygulama](#uygulama) + - [Yanıt Oluşturma](#yanıt-oluşturma) + - [Mimari: Spring Boot Otomatik Bağlama](#mimari-spring-boot-otomatik-bağlama) +- [Araç Zincirleme](#araç-zincirleme) +- [Uygulamayı Çalıştırma](#uygulamayı-çalıştırma) +- [Uygulamayı Kullanma](#uygulamanın-kullanımı) + - [Basit Araç Kullanmayı Deneyin](#basit-araç-kullanımını-deneyin) + - [Araç Zincirlemeyi Test Edin](#araç-zincirleme-testi) + - [Konuşma Akışını Görün](#konuşma-akışını-görün) + - [Farklı İsteklerle Deney Yapın](#farklı-i̇steklerle-deneyler-yapın) +- [Anahtar Kavramlar](#temel-kavramlar) + - [ReAct Deseni (Mantık Yürütme ve Hareket Etme)](#react-deseni-akıl-yürütme-ve-hareket-etme) + - [Araç Tanımları Önemlidir](#araç-açıklamaları-önemlidir) + - [Oturum Yönetimi](#oturum-yönetimi) + - [Hata Yönetimi](#hata-yönetimi) +- [Mevcut Araçlar](#mevcut-araçlar) +- [Araç Tabanlı Ajanları Ne Zaman Kullanmalı](#araç-tabanlı-ajanları-ne-zaman-kullanmalı) +- [Araçlar ve RAG Karşılaştırması](#araçlar-ve-rag) +- [Sonraki Adımlar](#sonraki-adımlar) + +## Video Yürütme + +Bu modüle nasıl başlayacağınızı açıklayan canlı oturumu izleyin: + +Araçlarla AI Ajanları ve MCP - Canlı Oturum + +## Neler Öğreneceksiniz + +Şu ana kadar AI ile nasıl sohbet edileceğini, istemleri etkili bir şekilde yapılandırmayı ve yanıtları belgelerinizle nasıl temel alacağınızı öğrendiniz. Ancak temel bir sınırlama hâlâ var: dil modelleri yalnızca metin üretebilir. Hava durumunu kontrol edemez, hesaplama yapamaz, veri tabanlarını sorgulayamaz veya dış sistemlerle etkileşimde bulunamazlar. + +Araçlar bunu değiştirir. Modele çağırabileceği fonksiyonlara erişim vererek, onu bir metin üreteci olmaktan, eylem yapabilen bir ajan haline dönüştürürsünüz. Model, ne zaman araca ihtiyacı olduğunu, hangi aracı kullanacağını ve hangi parametreleri geçeceğini karar verir. Kodunuz fonksiyonu uygular ve sonucu döner. Model, sonucu yanıtına dahil eder. + +## Önkoşullar - [Modül 01 - Giriş](../01-introduction/README.md) tamamlandı (Azure OpenAI kaynakları dağıtıldı) -- Önceki modüllerin tamamlanması önerilir (bu modül, Tools vs RAG karşılaştırmasında [Modül 03 RAG kavramlarına](../03-rag/README.md) referans verir) -- `.env` dosyası kök dizinde Azure kimlik bilgileri ile mevcut (Modül 01'de `azd up` ile oluşturuldu) +- Önceki modüllerin tamamlanması önerilir (bu modül, Araçlar ve RAG karşılaştırmasında [Modül 03'ten RAG kavramlarını](../03-rag/README.md) referans alır) +- Azure kimlik bilgileri içeren kök dizinde `.env` dosyası (Modül 01'de `azd up` ile oluşturuldu) -> **Not:** Modül 01'i tamamlamadıysanız, öncelikle oradaki dağıtım talimatlarını izleyin. +> **Not:** Eğer Modül 01'i tamamlamadıysanız, önce oradaki dağıtım talimatlarını izleyin. -## Araçlara Sahip Yapay Zeka Ajanlarını Anlamak +## Araçlarla AI Ajanlarını Anlamak -> **📝 Not:** Bu modüldeki "ajanlar" terimi, araç çağırma yetenekleri ile geliştirilmiş yapay zeka asistanlarını ifade eder. Bu, [Modül 05: MCP](../05-mcp/README.md) içinde ele alacağımız **Agentic AI** (planlama, hafıza ve çok adımlı muhakeme gibi özelliklere sahip otonom ajanlar) desenlerinden farklıdır. +> **📝 Not:** Bu modüldeki "ajanlar" terimi, araç çağırma yetenekleriyle geliştirilmiş AI asistanlarını ifade eder. Bu, [Modül 05: MCP](../05-mcp/README.md)'de ele alacağımız **Otonom AI** desenlerinden (planlama, hafıza ve çok adımlı akıl yürütme içeren otonom ajanlar) farklıdır. -Araçlar olmadan, bir dil modeli sadece eğitim verilerinden metin oluşturabilir. Mevcut hava durumunu sorarsanız tahmin etmek zorundadır. Araç verin, hava durumu API'si çağırabilir, hesaplama yapabilir veya veri tabanını sorgulayabilir — sonra bu gerçek sonuçları yanıtına dahil eder. +Araçlar olmadan, dil modeli yalnızca eğitim verisinden metin üretebilir. Mevcut hava durumunu sorarsanız, tahminde bulunmak zorunda kalır. Araçlar verirseniz, hava durumu API’si çağırabilir, hesaplama yapabilir veya veri tabanı sorgulayabilir — ve bu gerçek sonuçları yanıtına dahil edebilir. -Araçlar Olmadan vs Araçlar ile +Araçlar Olmadan ve Araçlarla -*Araç olmadan model sadece tahmin eder — araçlar sayesinde API çağırabilir, hesaplama yapabilir ve gerçek zamanlı veri dönebilir.* +*Araçlar olmadan model sadece tahmin eder — araçlarla API’leri çağırabilir, hesaplama yapabilir ve gerçek zamanlı veri sunabilir.* -Araçlara sahip AI ajanları **Düşünme ve Hareket Etme (ReAct)** desenini takip eder. Model sadece yanıt vermekle kalmaz — neye ihtiyacı olduğunu düşünür, bir aracı çağırarak eyleme geçer, sonucu gözlemler ve sonra tekrar mı hareket edeceğine yoksa nihai cevabı mı vereceğine karar verir: +Araçlara sahip bir AI ajanı **Mantık Yürütme ve Hareket Etme (ReAct)** desenini takip eder. Model sadece yanıt vermez — neye ihtiyacı olduğunu düşünür, bir araç çağırarak eyleme geçer, sonucu gözlemler ve ardından tekrar hareket edip etmeyeceğine ya da nihai yanıtı vereceğine karar verir: -1. **Düşün** — Ajan kullanıcının sorusunu analiz eder ve hangi bilgiye ihtiyaç duyduğunu belirler -2. **Harekete Geç** — Doğru aracı seçer, doğru parametreleri üretir ve çağırır +1. **Düşün** — Ajan kullanıcının sorusunu analiz eder ve hangi bilgilere ihtiyacı olduğunu belirler +2. **Hareket Et** — Ajan doğru aracı seçer, uygun parametreleri oluşturur ve çağırır 3. **Gözle** — Ajan aracın çıktısını alır ve sonucu değerlendirir -4. **Tekrarla veya Yanıtla** — Daha fazla veri gerekirse döngüye girer, yoksa doğal dil yanıtı oluşturur +4. **Tekrarla veya Yanıtla** — Daha fazla veriye gerek varsa döngüye devam eder; yoksa doğal dil yanıtı oluşturur ReAct Deseni -*ReAct döngüsü — ajan ne yapacağına karar verir, aracı çağırır, sonucu gözlemler ve nihai cevabı verene kadar döngüye devam eder.* +*ReAct döngüsü — ajan ne yapması gerektiğini düşünür, bir araç çağırarak hareket eder, sonucu gözlemler ve nihai yanıtı verebilene kadar döngü yapar.* -Bu süreç otomatik gerçekleşir. Siz araçları ve açıklamalarını tanımlarsınız. Model ne zaman ve nasıl kullanılacağına dair kararları kendisi verir. +Bu otomatik gerçekleşir. Siz araçları ve açıklamalarını tanımlarsınız. Model, ne zaman ve nasıl kullanılacağına karar verir. ## Araç Çağrısı Nasıl Çalışır @@ -78,7 +78,7 @@ Bu süreç otomatik gerçekleşir. Siz araçları ve açıklamalarını tanımla [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Fonksiyonları açık açıklamalar ve parametre tanımları ile belirlersiniz. Model bu açıklamaları sistem isteminde görür ve her aracın ne yaptığını anlar. +Fonksiyonları net açıklamalar ve parametre tanımlarıyla belirtirsiniz. Model, sistem isteminde bu açıklamaları görür ve her aracın ne yaptığını anlar. ```java @Component @@ -96,139 +96,139 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Asistan otomatik olarak Spring Boot tarafından şu şekilde bağlanır: +// Asistan, Spring Boot tarafından otomatik olarak yapılandırılır: // - ChatModel bileşeni -// - @Component sınıflarından tüm @Tool metodları +// - @Component sınıflarından tüm @Tool yöntemleri // - Oturum yönetimi için ChatMemoryProvider ``` - -Aşağıdaki diyagram her anotasyonu ayırır ve her parçanın yapay zekanın aracı ne zaman çağıracağını ve hangi argümanları geçeceğini anlamasına nasıl yardımcı olduğunu gösterir: + +Aşağıdaki diyagram her açıklamayı detaylandırır ve her parçanın AI’nın ne zaman aracı çağırması gerektiğini ve hangi argümanları kullanacağını nasıl anladığını gösterir: Araç Tanımlarının Anatomisi -*Bir araç tanımının anatomisi — @Tool yapay zekaya ne zaman kullanacağını söyler, @P her parametreyi açıklar, ve @AiService her şeyi başlangıçta bağlar.* +*Araç tanımının anatomisi — @Tool AI’ya ne zaman kullanacağını söyler, @P her parametreyi açıklar, ve @AiService her şeyi başlangıçta bağlar.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) dosyasını açın ve sorun: -> - "Gerçek bir hava durumu API'si kullanmak için OpenWeatherMap yerine mock veriler yerine nasıl entegre ederim?" -> - "Yapay zekanın doğru kullanmasını sağlayan iyi bir araç açıklaması nasıl olmalı?" -> - "Araç uygulamalarında API hatalarını ve oran limitlerini nasıl yönetirim?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) dosyasını açın ve sorun: +> - "Sahte veri yerine gerçek hava durumu API'si OpenWeatherMap‘i nasıl entegre ederim?" +> - "AI’nın aracı doğru kullanmasını sağlayan iyi bir araç tanımı nasıl olur?" +> - "Araç uygulamalarında API hatalarını ve hız sınırlarını nasıl yönetirim?" ### Karar Verme -Kullanıcı "Seattle'da hava nasıl?" diye sorduğunda, model rasgele bir araç seçmez. Kullanıcının amacını sahip olduğu her araç açıklaması ile karşılaştırır, her birini alaka düzeyine göre puanlar ve en uygun olanını seçer. Ardından doğru parametrelerle yapılandırılmış bir fonksiyon çağrısı oluşturur — bu örnekte `location` parametresine `"Seattle"` değeri atanır. +Kullanıcı "Seattle’de hava nasıl?" diye sorduğunda model rastgele bir araç seçmez. Kullanıcının niyetini sahip olduğu her araç açıklaması ile karşılaştırır, her birini ilgisine göre puanlar ve en iyi eşleşeni seçer. Ardından doğru parametrelerle yapılandırılmış fonksiyon çağrısı oluşturur — burada `location` değerini `"Seattle"` olarak ayarlar. -Eğer kullanıcının talebine uygun araç yoksa model bilgisiyle yanıt verir. Birden fazla uygun araç varsa en spesifik olanı seçer. +Eğer kullanıcının isteğine uyan araç yoksa, model kendi bilgisiyle cevap verir. Birden çok araç uygunsa en spesifik olanı seçer. -Yapay Zeka Hangi Aracı Seçeceğine Nasıl Karar Verir +AI'nın Hangi Aracı Seçtiği -*Model, mevcut her aracı kullanıcının amacıyla değerlendirir ve en uygun olanı seçer — bu yüzden net ve spesifik araç açıklamaları önemlidir.* +*Model, her aracı kullanıcının niyetiyle değerlendirir ve en uygun olanı seçer — bu yüzden net ve spesifik araç açıklamaları yazmak önemlidir.* -### Yürütme +### Uygulama [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot, bildirisel `@AiService` arayüzünü tüm kayıtlı araçlarla otomatik bağlar ve LangChain4j araç çağrılarını otomatik yürütür. Sahne arkası, kullanıcının doğal dil sorusundan doğal dil yanıta kadar tam bir araç çağrısı akışı altı aşamadan geçer: +Spring Boot, deklaratif `@AiService` arayüzünü tüm kayıtlı araçlarla otomatik bağlar ve LangChain4j araç çağrılarını otomatik olarak yürütür. Sahnenin arkasında eksiksiz bir araç çağrısı altı aşamadan geçer — kullanıcının doğal dil sorusundan doğal dile yanıt oluşturulana kadar: Araç Çağrısı Akışı -*Uçtan uca akış — kullanıcı soru sorar, model bir araç seçer, LangChain4j aracı çalıştırır ve model sonucu yanıt içine işler.* +*Uçtan uca akış — kullanıcı soru sorar, model araç seçer, LangChain4j aracı uygular ve model sonucu doğal yanıtına ekler.* -Eğer Modül 00’teki [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) çalıştırdıysanız bu desenin zaten nasıl işlediğini gördünüz — `Calculator` araçları benzer şekilde çağrıldı. Aşağıdaki dizin diyagramı demo sırasında tam olarak ne olduğunu gösterir: +Sahnenin arkasında `AiServices` herhangi bir araç için aynı araç çağrısı döngüsünü yürütür — burada basit bir `Calculator` örneği ile gösterilmiştir. Aşağıdaki sıra diyagramı tam olarak neler olduğunu gösteriyor: -Araç Çağrısı Sıralama Diyagramı +Araç Çağrısı Sıra Diyagramı -*Quick Start demosundaki araç çağrısı döngüsü — `AiServices` mesajınızı ve araç şemalarını LLM'ye gönderir, LLM `add(42, 58)` gibi fonksiyon çağrısı ile yanıt verir, LangChain4j `Calculator` metodunu yerel olarak çalıştırır ve sonucu nihai yanıt için geri besler.* +*Araç çağrısı döngüsü — `AiServices` mesajınızı ve araç şemalarını LLM’ye gönderir, LLM `add(42, 58)` gibi fonksiyon çağrısı yapar, LangChain4j `Calculator` metodunu yerel olarak çalıştırır ve sonucu nihai yanıt için geri besler.* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) dosyasını açın ve sorun: -> - "ReAct deseni nasıl çalışır ve AI ajanları için neden etkilidir?" -> - "Ajan hangi aracı kullanacağına ve hangi sırayla karar veriyor?" -> - "Bir araç yürütmesi başarısız olursa ne olur — hataları sağlam şekilde nasıl yönetmeliyim?" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) Chat ile deneyin:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) dosyasını açın ve sorun: +> - "ReAct deseni nasıl çalışır ve neden AI ajanları için etkilidir?" +> - "Ajan hangi aracı kullanacağına ve hangi sırayla karar verir?" +> - "Bir araç çalıştırma başarısız olursa ne olur - hataları sağlam şekilde nasıl yönetirim?" -### Yanıt Üretimi +### Yanıt Oluşturma -Model hava durumu verisini alır ve kullanıcı için doğal dil yanıtına dönüştürür. +Model hava durumu verilerini alır ve kullanıcı için doğal dil yanıtı olarak biçimlendirir. ### Mimari: Spring Boot Otomatik Bağlama -Bu modül, LangChain4j’nin Spring Boot entegrasyonunu bildirisel `@AiService` arayüzleri ile kullanır. Başlangıçta Spring Boot, `@Tool` metotları içeren her `@Component`’i, ChatModel bean’inizi ve ChatMemoryProvider’ı keşfeder — sonra hepsini tek bir `Assistant` arayüzünde sıfır kodla birbirine bağlar. +Bu modül, LangChain4j’nin deklaratif `@AiService` arayüzleriyle Spring Boot entegrasyonunu kullanır. Başlangıçta Spring Boot, `@Tool` metodları içeren tüm `@Component`'leri, ChatModel bean’inizi ve ChatMemoryProvider’ı keşfeder — sonra bunların hepsini sıfır kuvvetli kodla tek bir `Assistant` arayüzüne bağlar. -Spring Boot Otomatik Bağlama Mimaris +Spring Boot Otomatik Bağlama Mimarisi -*@AiService arayüzü ChatModel, araç bileşenleri ve hafıza sağlayıcıyı bağlar — Spring Boot bağlantıları otomatik yönetir.* +*@AiService arayüzü ChatModel, araç bileşenleri ve hafıza sağlayıcıyı bir araya getirir — Spring Boot tüm bağlantıları otomatik yapar.* -İşte tam istek yaşam döngüsünün dizin diyagramı — HTTP isteğinden başlayarak controller, servis, otomatik bağlanan proxy, araç yürütme ve geri dönüşe kadar: +İşte HTTP isteğinden kontrolör, servis ve otomatik bağlanan vekile, oradan da araç yürütmeye ve geri dönüşe kadar tam istek yaşam döngüsünün sıra diyagramı: -Spring Boot Araç Çağrısı Sıralaması +Spring Boot Araç Çağrısı Sıra Diyagramı -*Tam Spring Boot istek yaşam döngüsü — HTTP isteği controller ve servis üzerinden otomatik bağlanan Asistan proxy’sine akar, bu da LLM ve araç çağrılarını otomatik koordine eder.* +*Tam Spring Boot istek yaşam döngüsü — HTTP isteği kontrolör ve servis üzerinden otomatik bağlanan Assistant vekiline akar, o da LLM ve araç çağrılarını otomatik organize eder.* -Bu yaklaşımın başlıca avantajları: +Bu yaklaşımın temel faydaları: - **Spring Boot otomatik bağlama** — ChatModel ve araçlar otomatik olarak enjekte edilir -- **@MemoryId deseni** — Otomatik oturum temelli hafıza yönetimi -- **Tek örnek** — Asistan bir kez oluşturulur ve performans için tekrar kullanılır -- **Tip güvenli yürütme** — Java metotları doğrudan tip dönüşümü ile çağrılır -- **Çoklu tur orkestrasyonu** — Araç zincirlemesini otomatik yönetir -- **Sıfır kod tekrarları** — Manuel `AiServices.builder()` çağrısı veya hafıza için HashMap gerekmez +- **@MemoryId deseni** — Oturum bazlı hafıza yönetimi otomatik +- **Tek örnek** — Assistant bir kez oluşturulur ve performans için tekrar kullanılır +- **Tip-güvenli yürütme** — Java metodları doğrudan tür dönüşümüyle çağrılır +- **Çok turlu orkestrasyon** — Araç zincirleme otomatik yönetilir +- **Sıfır kuvvetli kod** — Elle `AiServices.builder()` çağrısı veya hafıza HashMap yok -Alternatif yaklaşımlar (manuel `AiServices.builder()`) daha fazla kod gerektirir ve Spring Boot entegrasyonunun faydalarını kaçırır. +Alternatif yaklaşımlar (manuel `AiServices.builder()`) daha fazla kod gerektirir ve Spring Boot entegrasyon avantajlarını kaçırır. -## Araç Zinciri +## Araç Zincirleme -**Araç Zinciri** — Araç tabanlı ajanların gerçek gücü tek bir sorunun birden çok araç gerektirdiği durumlarda ortaya çıkar. "Seattle’da hava Fahrenheit cinsinden nasıl?" diye sorarsanız ajan otomatik olarak iki aracı zincirler: önce `getCurrentWeather`’i çağırır ve sıcaklığı Celcius cinsinden alır, sonra bu değeri `celsiusToFahrenheit` aracına geçirir — tümü tek bir konuşma turunda gerçekleşir. +**Araç Zincirleme** — Araç tabanlı ajanların gerçek gücü, tek bir sorunun birden fazla araç gerektirdiği durumlarda ortaya çıkar. "Seattle’de hava Fahrenheit cinsinden nasıl?" diye sorarsanız ajan otomatik olarak iki aracı birleştirir: önce `getCurrentWeather` ile Santigrat cinsinden sıcaklığı alır, sonra o değeri `celsiusToFahrenheit` aracına aktarır — hepsi tek bir konuşma turunda. -Araç Zinciri Örneği +Araç Zincirleme Örneği -*Araç zinciri örneği — ajan önce getCurrentWeather'i çağırır, sonra Celcius sonucunu celsiusToFahrenheit aracına aktarır ve birleşik bir yanıt verir.* +*Araç zincirleme uygulamada — ajan önce getCurrentWeather çağırır, sonra Santigrat sonucunu celsiusToFahrenheit’e geçirir ve birleşik yanıtı verir.* -**Kibar Hatalar** — Mock verilerde olmayan bir şehir için hava durumu isterseniz araç bir hata mesajı döner. Yapay zeka yardımcı olamayacağını açıklar, uygulama çökmez. Araçlar güvenli şekilde başarısız olur. Aşağıdaki diyagram iki yaklaşımı karşılaştırır — düzgün hata yönetimi ile ajan istisnayı yakalar ve açıklayıcı yanıt verir, olmadan tüm uygulama çöker: +**Sıkıntısız Hatalar** — Sahte veride olmayan bir şehir için hava talep edin. Araç hata mesajı döner ve AI çözemediğini zarifçe açıklar, çökmez. Araçlar güvenli şekilde hata yapar. Aşağıdaki diyagram iki yaklaşımı karşılaştırır — düzgün hata yönetiminde ajan istisnayı yakalar ve yardımcı yanıt verir; yönetmeseydi uygulama tamamen çökebilirdi: Hata Yönetimi Akışı -*Bir araç hata yaparsa ajan hatayı yakalar ve çökmek yerine yardımcı bir açıklama ile yanıt verir.* +*Bir araç başarısız olduğunda ajan hatayı yakalar ve çökme yerine yardımcı bir açıklama yapar.* -Bu tek bir konuşma turunda olur. Ajan çoklu araç çağrılarını otonom şekilde orkestre eder. +Bu tek bir konuşma turunda olur. Ajan birden fazla araç çağrısını otonom şekilde yönetir. ## Uygulamayı Çalıştırma **Dağıtımı doğrulayın:** -Azure kimlik bilgileri ile `.env` dosyasının kök dizinde var olduğundan emin olun (Modül 01’de oluşturuldu). Modül dizininden (`04-tools/`) şu komutları çalıştırın: +Modül 01 sırasında oluşturulan Azure kimlik bilgileri içeren `.env` dosyasının kök dizinde olduğundan emin olun. Bunu modül dizininden çalıştırın (`04-tools/`): -**Bash:** +**Bash:** ```bash cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT göstermeli ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT göstermeli ``` - + **Uygulamayı başlatın:** -> **Not:** Eğer root dizinden `./start-all.sh` ile tüm uygulamaları zaten başlattıysanız (Modül 01’de anlatıldığı gibi), bu modül zaten 8084 portunda çalışıyor. Aşağıdaki başlatma komutlarını atlayabilir ve doğrudan http://localhost:8084 adresine gidebilirsiniz. +> **Not:** Eğer zaten kök dizinden `./start-all.sh` ile tüm uygulamaları başlattıysanız (Modül 01’de anlatıldığı gibi), bu modül zaten 8084 portunda çalışıyor. Aşağıdaki başlatma komutlarını atlayabilir ve doğrudan http://localhost:8084 adresine gidebilirsiniz. -**Seçenek 1: Spring Boot Dashboard kullanmak (VS Code kullanıcıları için önerilir)** +**Seçenek 1: Spring Boot Dashboard ile Kullanım (VS Code kullanıcıları için önerilir)** -Dev container, tüm Spring Boot uygulamalarını yönetmek için görsel arayüz sunan Spring Boot Dashboard uzantısını içerir. VS Code’un sol tarafındaki Aktivite Çubuğunda (Spring Boot simgesine bakın) bulabilirsiniz. +Geliştirme konteyneri, tüm Spring Boot uygulamalarını görsel olarak yönetmenizi sağlayan Spring Boot Dashboard uzantısını içerir. Bunu VS Code’un solundaki Etkinlik Çubuğu’nda (Spring Boot simgesine bakın) bulabilirsiniz. -Spring Boot Dashboard’dan yapabilecekleriniz: -- Çalışma alanında tüm mevcut Spring Boot uygulamalarını görme -- Uygulamaları tek tıkla başlat/durdur -- Uygulama günlüklerini gerçek zamanlı görüntüleme -- Uygulama durumunu izleme -"tools" yanındaki oynat düğmesine tıklayarak bu modülü başlatın veya tüm modülleri aynı anda başlatın. +Spring Boot Dashboard’dan şunları yapabilirsiniz: +- Çalışma alanındaki tüm kullanılabilir Spring Boot uygulamalarını görün +- Uygulamaları tek tıkla başlat/durdur +- Uygulama günlüklerini gerçek zamanlı görüntüle +- Uygulama durumunu izleyin -VS Code'daki Spring Boot Dashboard şöyle görünür: +"tools" yanındaki oynat düğmesine tıklayarak bu modülü başlatabilir veya tüm modülleri aynı anda başlatabilirsiniz. -Spring Boot Dashboard +İşte VS Code’da Spring Boot Dashboard’ın görünümü: +Spring Boot Kontrol Paneli -*VS Code'daki Spring Boot Dashboard — tüm modülleri tek bir yerden başlatın, durdurun ve izleyin* +*VS Code'daki Spring Boot Kontrol Paneli — tüm modülleri tek yerden başlatın, durdurun ve izleyin* -**Seçenek 2: Shell script kullanımı** +**Seçenek 2: Shell scriptleri kullanmak** -Tüm web uygulamalarını (modüller 01-04) başlat: +Tüm web uygulamalarını başlatın (modüller 01-04): **Bash:** ```bash @@ -242,7 +242,7 @@ cd .. # Kök dizinden .\start-all.ps1 ``` -Ya da sadece bu modülü başlat: +Ya da sadece bu modülü başlatın: **Bash:** ```bash @@ -256,16 +256,16 @@ cd 04-tools .\start.ps1 ``` -Her iki script de root `.env` dosyasından ortam değişkenlerini otomatik olarak yükler ve JAR dosyaları yoksa derler. +Her iki script de kök `.env` dosyasından ortam değişkenlerini otomatik olarak yükler ve JAR dosyaları yoksa oluşturur. -> **Not:** Başlamadan önce tüm modülleri manuel olarak derlemeyi tercih ederseniz: +> **Not:** Başlatmadan önce tüm modülleri manuel olarak derlemeyi tercih ederseniz: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -278,21 +278,21 @@ Tarayıcınızda http://localhost:8084 adresini açın. **Bash:** ```bash -./stop.sh # Yalnızca bu modül +./stop.sh # Bu modül sadece # Veya cd .. && ./stop-all.sh # Tüm modüller ``` **PowerShell:** ```powershell -.\stop.ps1 # Sadece bu modül +.\stop.ps1 # Bu modül yalnızca # Veya cd ..; .\stop-all.ps1 # Tüm modüller ``` ## Uygulamanın Kullanımı -Uygulama, hava durumu ve sıcaklık dönüştürme araçlarına erişimi olan bir AI ajanıyla etkileşim kurabileceğiniz bir web arayüzü sağlar. Arayüz şöyle görünür — hızlı başlangıç örnekleri ve istek göndermek için bir sohbet paneli içerir: +Uygulama, hava durumu ve sıcaklık dönüşümü araçlarına erişimi olan bir yapay zeka ajanı ile etkileşim kurabileceğiniz bir web arayüzü sağlar. Arayüzün görünümü şöyle — hızlı başlangıç örnekleri ve istek göndermek için bir sohbet paneli içerir: AI Agent Tools Interface @@ -300,76 +300,76 @@ Uygulama, hava durumu ve sıcaklık dönüştürme araçlarına erişimi olan bi ### Basit Araç Kullanımını Deneyin -"100 derece Fahrenheit'ı Santigrata çevir" gibi basit bir istekle başlayın. Ajan, sıcaklık dönüştürme aracına ihtiyacı olduğunu anlar, doğru parametrelerle çağırır ve sonucu döner. Ne kadar doğal hissettirdiğine dikkat edin — hangi aracı kullanacağınızı ya da nasıl çağıracağınızı belirtmediniz. +Basit bir istekle başlayın: "100 derece Fahrenheit'i Celsius'a çevir". Ajan, sıcaklık dönüşüm aracını çağırması gerektiğini anlar, doğru parametrelerle çalıştırır ve sonucu döner. Bunun ne kadar doğal olduğunu fark edin - hangi aracı kullanacağınızı veya nasıl çağıracağınızı belirtmediniz. -### Araç Zincirlemeyi Test Edin +### Araç Zincirleme Testi -Şimdi daha karmaşık bir şey deneyin: "Seattle'daki hava durumu nedir ve bunu Fahrenheit'a çevir?" Ajanın adım adım nasıl çalıştığını gözlemleyin. Önce hava durumunu alır (Santigrat cinsinden döner), sonra Fahrenheit'a dönüştürmesi gerektiğini anlar, dönüşüm aracını çağırır ve her iki sonucu tek bir yanıtta birleştirir. +Şimdi daha karmaşık bir şey deneyin: "Seattle'daki hava durumu nedir ve Fahrenheit'a çevir?" Ajanın bunu adım adım nasıl çözdüğünü izleyin. Önce hava durumunu alır (derece Celsius cinsinden), ardından Fahrenheit'a çevirmesi gerektiğini anlar, dönüşüm aracını çağırır ve her iki sonucu birleştirerek yanıt verir. ### Konuşma Akışını Görün -Sohbet arayüzü konuşma geçmişini korur, çok turlu etkileşimler yapmanızı sağlar. Önceki tüm sorguları ve yanıtları görebilirsiniz; böylece konuşmayı takip etmek ve ajanın bağlamı nasıl oluşturduğunu anlamak kolaydır. +Sohbet arayüzü, çok turlu etkileşimler için geçmişi saklar. Tüm önceki sorguları ve yanıtları görebilir, konuşmayı takip etmek ve ajanın bağlamı nasıl oluşturduğunu anlamak kolaylaşır. -Conversation with Multiple Tool Calls +Çoklu Araç Çağrılarıyla Konuşma -*Basit dönüşümler, hava durumu sorgulamaları ve araç zincirleme gösteren çok turlu sohbet* +*Basit dönüşümler, hava durumu sorgulamaları ve araç zincirlemesi gösteren çok turlu sohbet* -### Farklı İsteklerle Deney Yapın +### Farklı İsteklerle Deneyler Yapın -Çeşitli kombinasyonları deneyin: -- Hava durumu sorgulamaları: "Tokyo'daki hava durumu nedir?" -- Sıcaklık dönüşümleri: "25°C kaç Kelvin?" -- Kombine sorgular: "Paris'teki hava durumunu kontrol et ve 20°C'nin üzerinde mi söyle" +Çeşitli kombinasyonlar deneyin: +- Hava durumu sorgulamaları: "Tokyo'da hava nasıl?" +- Sıcaklık dönüşümleri: "25°C kaç Kelvin eder?" +- Kombine sorgular: "Paris'teki hava durumunu kontrol et ve 20°C üzerinde mi söyle" -Ajanın doğal dili nasıl yorumlayıp uygun araç çağrılarına dönüştürdüğüne dikkat edin. +Ajanın doğal dili nasıl yorumladığını ve uygun araç çağrılarına dönüştürdüğünü fark edin. ## Temel Kavramlar -### ReAct Deseni (Muhakeme ve Eylem) +### ReAct Deseni (Akıl Yürütme ve Hareket Etme) -Ajan, muhakeme (ne yapılacağına karar verme) ve eylem (araçları kullanma) arasında geçiş yapar. Bu desen, sadece yanıt vermek yerine otonom problem çözmeyi mümkün kılar. +Ajan, akıl yürütme (ne yapacağına karar verme) ve hareket etme (araçları kullanma) arasında geçiş yapar. Bu desen, sadece talimatlara yanıt vermek yerine, otonom problem çözmeyi mümkün kılar. -### Araç Tanımları Önemlidir +### Araç Açıklamaları Önemlidir -Araç tanımlarınızın kalitesi, ajanın onları ne kadar iyi kullandığını doğrudan etkiler. Açık, spesifik tanımlar modelin hangi aracı ne zaman ve nasıl çağıracağını anlamasına yardımcı olur. +Araç açıklamalarınızın kalitesi, ajanın araçları ne kadar iyi kullandığını doğrudan etkiler. Açık ve spesifik açıklamalar, modelin hangi araç çağrılması gerektiğini ve nasıl yapılacağını anlamasına yardımcı olur. ### Oturum Yönetimi -`@MemoryId` notasyonu otomatik oturum bazlı bellek yönetimini sağlar. Her oturum ID'si, `ChatMemoryProvider` bean tarafından yönetilen kendi `ChatMemory` örneğini alır; böylece birden fazla kullanıcı ajana aynı anda, konuşmaları karışmadan erişebilir. Aşağıdaki diyagram, kullanıcıların oturum ID'lerine göre nasıl izole bellek depolarına yönlendirildiğini gösterir: +`@MemoryId` notasyonu, otomatik oturum tabanlı hafıza yönetimini sağlar. Her oturum kimliği, `ChatMemoryProvider` bean'i tarafından yönetilen kendi `ChatMemory` örneği alır, böylece birden çok kullanıcı aynı anda ajana etkileşim kurabilir ve konuşmalar karışmaz. Aşağıdaki diyagram, çoklu kullanıcıların oturum kimliklerine göre izole hafıza depolarına nasıl yönlendirildiğini gösterir: -Session Management with @MemoryId +@MemoryId ile Oturum Yönetimi -*Her oturum ID'si yalıtılmış bir konuşma geçmişine karşılık gelir — kullanıcılar birbirlerinin mesajlarını görmez.* +*Her oturum kimliği izole bir konuşma geçmişine sahiptir — kullanıcılar birbirlerinin mesajlarını hiç görmez.* ### Hata Yönetimi -Araçlar başarısız olabilir — API'ler zaman aşımına uğrayabilir, parametreler geçersiz olabilir, dış servisler kapanabilir. Üretim ajanlarının, modeli çökertmek yerine problemleri açıklayabilmesi veya alternatifleri deneyebilmesi için hata yönetimi gerekir. Bir araç istisna attığında, LangChain4j bunu yakalar ve hata mesajını modele geri besler; model de problemi doğal dilde açıklar. +Araçlar başarısız olabilir — API'ler zaman aşımına uğrayabilir, parametreler geçersiz olabilir veya dış servisler devre dışı kalabilir. Üretim ajanları, modelin problemleri açıklayabilmesi veya alternatifler deneyebilmesi için hata yönetimine ihtiyaç duyar; yoksa uygulama çöker. Bir araç istisna fırlattığında, LangChain4j yakalar ve hata mesajını modele geri besler, böylece model doğal dilde problemi açıklayabilir. ## Mevcut Araçlar -Aşağıdaki diyagram, oluşturabileceğiniz geniş araç ekosistemini gösterir. Bu modül hava durumu ve sıcaklık araçlarını gösterir, ancak aynı `@Tool` deseni her türlü Java yöntemi için çalışır — veritabanı sorgularından ödeme işlemlerine kadar. +Aşağıdaki diyagram, oluşturabileceğiniz geniş araç ekosistemini gösteriyor. Bu modül, hava durumu ve sıcaklık araçlarını gösteriyor, ancak aynı `@Tool` deseni herhangi bir Java metodunda çalışır — veritabanı sorgularından ödeme işlemlerine kadar. -Tool Ecosystem +Araç Ekosistemi -*@Tool ile işaretlenmiş herhangi bir Java yöntemi AI için kullanılabilir hale gelir — desen veritabanları, API'ler, e-posta, dosya işlemleri ve daha fazlasını kapsar.* +*@Tool ile notasyonlu herhangi bir Java metodu, AI için kullanılabilir hale gelir — desen veritabanları, API'ler, e-posta, dosya işlemleri ve diğerlerine kadar genişler.* -## Ne Zaman Araç Tabanlı Ajan Kullanılır +## Araç Tabanlı Ajanları Ne Zaman Kullanmalı? -Her istek araç gerektirmez. Karar, AI'nın dış sistemlerle etkileşim kurup kurmaması ya da kendi bilgisiyle yanıt verebilmesine bağlıdır. Aşağıdaki rehber, araçların ne zaman değer kattığını ve ne zaman gereksiz olduğunu özetler: +Her istek araç gerektirmez. Karar, yapay zekanın dış sistemlerle etkileşime girip girmemesi veya kendi bilgisinden yanıt verip verememesi ile ilgilidir. Aşağıdaki rehber, araçların ne zaman değer kattığını ve ne zaman gereksiz olduğunu özetler: -When to Use Tools +Araçların Ne Zaman Kullanılacağı -*Hızlı karar rehberi — araçlar gerçek zamanlı veri, hesaplama ve işlemler içindir; genel bilgi ve yaratıcı görevler için gerekmez.* +*Hızlı karar rehberi — araçlar gerçek zamanlı veri, hesaplamalar ve işlemler içindir; genel bilgi ve yaratıcı görevler için gerekli değildir.* -## Araçlar ve RAG Karşılaştırması +## Araçlar ve RAG -Modüller 03 ve 04, AI'nın yapabileceklerini genişletir fakat temel olarak farklı şekillerde. RAG modele **bilgi** erişimi sağlar — dökümanları getirir. Araçlar modele **eylem** yapma kabiliyeti verir — fonksiyonları çağırır. Aşağıdaki diyagram, her iki yaklaşımı yan yana karşılaştırır — her iş akışının nasıl çalıştığını ve aralarındaki farkları: +Modüller 03 ve 04, AI'nın yapabileceklerini genişletir, ancak temelde farklı yollarla. RAG, modele **bilgi** erişimi sağlar; belgelerden alınan verilerle. Araçlar ise modele işlev çağrıları yaparak **eylemler** alma yeteneği verir. Aşağıdaki diyagram, bu iki yaklaşımı yan yana karşılaştırır — her süreç nasıl işler ve aralarındaki dezavantajlar: -Tools vs RAG Comparison +Araçlar ve RAG Karşılaştırması -*RAG statik dökümanlardan bilgi getirir — Araçlar eylemler yapar ve dinamik, gerçek zamanlı veri alır. Pek çok üretim sistemi her iki yaklaşımı kombine eder.* +*RAG statik belgelerden bilgi alır — Araçlar eylemleri gerçekleştirir ve dinamik, gerçek zamanlı verileri getirir. Pek çok üretim sistemi ikisini birden kullanır.* -Pratikte, pek çok üretim sistemi her iki yaklaşımı birleştirir: RAG yanıtları belgelerde temellemek için, Araçlar ise canlı veri almak veya işlemler yapmak için. +Pratikte birçok üretim sistemi her iki yaklaşımı da birleştirir: RAG, yanıtları belgelerinizle temellendirir; Araçlar, canlı veri getirmek veya işlem yapmak için kullanılır. ## Sonraki Adımlar @@ -383,5 +383,5 @@ Pratikte, pek çok üretim sistemi her iki yaklaşımı birleştirir: RAG yanıt **Feragatname**: -Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba göstermemize rağmen, otomatik çevirilerin hatalar veya yanlışlıklar içerebileceğini lütfen unutmayın. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu oluşabilecek herhangi bir yanlış anlama veya yorumlama için sorumluluk kabul edilmemektedir. +Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz. \ No newline at end of file diff --git a/translations/tr/README.md b/translations/tr/README.md index 73b052b8b..ca4e9a5bb 100644 --- a/translations/tr/README.md +++ b/translations/tr/README.md @@ -1,19 +1,19 @@ LangChain4j -# Yeni Başlayanlar için LangChain4j +# LangChain4j Yeni Başlayanlar İçin -Temel sohbetten AI ajanlarına kadar LangChain4j ve Azure OpenAI GPT-5.2 ile AI uygulamaları geliştirme kursu. +LangChain4j ve Azure OpenAI GPT-5.2 ile temel sohbetten AI ajanlarına kadar AI uygulamaları geliştirme kursu. ### 🌐 Çok Dilli Destek -#### GitHub Action ile Desteklenir (Otomatik ve Her Zaman Güncel) +#### GitHub Action ile Desteklenmektedir (Otomatik ve Her Zaman Güncel) -[Arapça](../ar/README.md) | [Bengalce](../bn/README.md) | [Bulgarca](../bg/README.md) | [Birmanca (Myanmar)](../my/README.md) | [Çince (Basitleştirilmiş)](../zh-CN/README.md) | [Çince (Geleneksel, Hong Kong)](../zh-HK/README.md) | [Çince (Geleneksel, Makao)](../zh-MO/README.md) | [Çince (Geleneksel, Tayvan)](../zh-TW/README.md) | [Hırvatça](../hr/README.md) | [Çekçe](../cs/README.md) | [Danca](../da/README.md) | [Flemenkçe](../nl/README.md) | [Estonca](../et/README.md) | [Fince](../fi/README.md) | [Fransızca](../fr/README.md) | [Almanca](../de/README.md) | [Yunanca](../el/README.md) | [İbranice](../he/README.md) | [Hintçe](../hi/README.md) | [Macarca](../hu/README.md) | [Endonezyaca](../id/README.md) | [İtalyanca](../it/README.md) | [Japonca](../ja/README.md) | [Kannada](../kn/README.md) | [Kmerce](../km/README.md) | [Korece](../ko/README.md) | [Litvanca](../lt/README.md) | [Malayca](../ms/README.md) | [Malayalamca](../ml/README.md) | [Marathi](../mr/README.md) | [Nepalce](../ne/README.md) | [Nijerya Pidgin](../pcm/README.md) | [Norveççe](../no/README.md) | [Farsça (Persian)](../fa/README.md) | [Lehçe](../pl/README.md) | [Portekizce (Brezilya)](../pt-BR/README.md) | [Portekizce (Portekiz)](../pt-PT/README.md) | [Pencapça (Gurmukhi)](../pa/README.md) | [Rumence](../ro/README.md) | [Rusça](../ru/README.md) | [Sırpça (Kiril)](../sr/README.md) | [Slovakça](../sk/README.md) | [Slovence](../sl/README.md) | [İspanyolca](../es/README.md) | [Svahili](../sw/README.md) | [İsveççe](../sv/README.md) | [Tagalog (Filipince)](../tl/README.md) | [Tamilce](../ta/README.md) | [Telugu](../te/README.md) | [Tayca](../th/README.md) | [Türkçe](./README.md) | [Ukraynaca](../uk/README.md) | [Urduca](../ur/README.md) | [Vietnamca](../vi/README.md) +[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](./README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **Yerel Kopyalamayı Tercih Ediyor musunuz?** +> **Yerel Olarak Klonlamayı Tercih Ediyor musunuz?** > -> Bu depo, indirme boyutunu önemli ölçüde artıran 50'den fazla dil çevirisi içerir. Çeviriler olmadan kopyalamak için, seyrek kontrolü kullanın: +> Bu depo, indirilen boyutu önemli ölçüde artıran 50'den fazla dil çevirisini içerir. Çeviriler olmadan klonlamak için seyrek kontrol (sparse checkout) kullanın: > > **Bash / macOS / Linux:** > ```bash @@ -29,26 +29,25 @@ Temel sohbetten AI ajanlarına kadar LangChain4j ve Azure OpenAI GPT-5.2 ile AI > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Bu, kursu tamamlamak için ihtiyacınız olan her şeyi çok daha hızlı bir indirme ile sağlar. +> Bu, kursu tamamlamak için ihtiyacınız olan her şeyi çok daha hızlı indirme ile sağlar. ## İçindekiler -1. [Hızlı Başlangıç](00-quick-start/README.md) - LangChain4j ile başlayın -2. [Giriş](01-introduction/README.md) - LangChain4j temellerini öğrenin -3. [Komut Mühendisliği](02-prompt-engineering/README.md) - Etkili komut tasarımında ustalaşın -4. [RAG (Bilgi Tabanlı Üretimi)](03-rag/README.md) - Akıllı bilgi tabanlı sistemler geliştirin -5. [Araçlar](04-tools/README.md) - Dış araçları ve basit asistanları entegre edin -6. [MCP (Model Bağlam Protokolü)](05-mcp/README.md) - Model Bağlam Protokolü (MCP) ve Agentic modülleri ile çalışın +1. [Giriş](01-introduction/README.md) - LangChain4j'nin temellerini öğrenin +2. [Prompt Mühendisliği](02-prompt-engineering/README.md) - Etkili prompt tasarımında ustalaşın +3. [RAG (Retrieval-Augmented Generation)](03-rag/README.md) - Akıllı bilgi tabanlı sistemler oluşturun +4. [Araçlar](04-tools/README.md) - Harici araçlar ve basit asistanlar entegre edin +5. [MCP (Model Context Protocol)](05-mcp/README.md) - Model Context Protocol (MCP) ve Ajans modülleri ile çalışın ### Video Anlatımlar -Her modül, kavramları ve kodu adım adım incelediğimiz canlı oturumlara sahiptir. +Her modül, kavramları ve kodu adım adım anlattığımız bir canlı oturum ile birlikte gelir. | Modül | Video | -|--------|-------| -| 01 - Giriş | [LangChain4j ile Başlamak](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Komut Mühendisliği | [LangChain4j ile Komut Mühendisliği](https://www.youtube.com/live/PJ6aBaE6bog) | +|-------|-------| +| 01 - Giriş | [LangChain4j ile Başlarken](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Prompt Mühendisliği | [LangChain4j ile Prompt Mühendisliği](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [LangChain4j ile RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - Araçlar & 05 - MCP | [Araçlar ve MCP ile AI Ajanları](https://www.youtube.com/watch?v=O_J30kZc0rw) | @@ -56,34 +55,34 @@ Her modül, kavramları ve kodu adım adım incelediğimiz canlı oturumlara sah ## Öğrenme Yolu -**LangChain4j'ye yeni misiniz?** Anahtar terim ve kavramların tanımları için [Sözlüğe](docs/GLOSSARY.md) göz atın. +**LangChain4j'e yeni misiniz?** Anahtar terimler ve kavramlar için [Sözlüğe](docs/GLOSSARY.md) göz atın. > **Hızlı Başlangıç** -1. Bu depoyu GitHub hesabınıza çatallayın -2. **Code** → **Codespaces** sekmesine tıklayın → **...** → **Yeni seçeneklerle...** -3. Varsayılanları kullanın – bu, bu kurs için oluşturulan Geliştirme konteynerini seçecektir -4. **Codespace oluştur**a tıklayın +1. Bu depoyu GitHub hesabınıza çatallayın (fork) +2. **Code** → **Codespaces** sekmesine tıklayın → **...** → **Seçeneklerle Yeni...** +3. Varsayılanları kullanın – bu kurs için oluşturulan Geliştirme konteynerini seçer +4. **Kodespace oluştur** butonuna tıklayın 5. Ortamın hazır olması için 5-10 dakika bekleyin -6. Başlamak için doğrudan [Hızlı Başlangıç](./00-quick-start/README.md) sayfasına geçin! +6. Başlamak için doğrudan [Giriş](./01-introduction/README.md) bölümüne atlayın! -Modülleri tamamladıktan sonra, LangChain4j test kavramlarını uygulamalı görmek için [Test Rehberini](docs/TESTING.md) inceleyin. +Modülleri tamamladıktan sonra, LangChain4j test kavramlarını uygulamada görmek için [Test Rehberini](docs/TESTING.md) keşfedin. -> **Not:** Bu eğitim hem GitHub Modelleri hem de Azure OpenAI kullanır. [Hızlı Başlangıç](00-quick-start/README.md) modülü GitHub Modellerini kullanır (Azure aboneliği gerekmez), 1-5 modülleri ise Azure OpenAI kullanır. Henüz yoksa, [ÜCRETSİZ Azure hesabı](https://aka.ms/azure-free-account) ile başlayın. +> **Not:** Bu eğitim Azure OpenAI kullanmaktadır. Henüz hesabınız yoksa [ÜCRETSİZ Azure hesabı](https://aka.ms/azure-free-account) ile başlayın. ## GitHub Copilot ile Öğrenme -Hızlıca kodlamaya başlamak için, bu projeyi GitHub Codespace'te ya da sağlanan geliştirme konteyneriyle yerel IDE'nizde açın. Bu kursta kullanılan geliştirme konteyneri, AI eşliğinde programlama için GitHub Copilot ile önceden yapılandırılmıştır. +Hemen kod yazmaya başlamak için bu projeyi GitHub Codespace'de veya sağlanan devcontainer ile yerel IDE'nizde açın. Bu kursta kullanılan devcontainer, AI eşliğinde programlama için önden yapılandırılmış GitHub Copilot içerir. -Her kod örneği, GitHub Copilot'a anlayışınızı derinleştirmek için sorabileceğiniz önerilen sorular içerir. 💡/🤖 işaretlerini şu yerlerde arayın: +Her kod örneği, GitHub Copilot'a sorabileceğiniz önerilen soruları içerir ve böylece kavrayışınızı derinleştirebilirsiniz. 💡/🤖 ipuçlarını şu yerlerde arayın: -- **Java dosya başlıkları** - Her örneğe özgü sorular -- **Modül README dosyaları** - Kod örneklerinden sonra keşif teşvikleri +- **Java dosya başlıkları** - Her örneğe özel sorular +- **Modül README dosyaları** - Kod örneklerinden sonra keşif soruları -**Kullanımı:** Herhangi bir kod dosyasını açıp Copilot'a önerilen soruları sorun. Copilot, kod tabanının tüm bağlamına sahiptir ve açıklama yapabilir, genişletebilir ve alternatifler önerebilir. +**Nasıl kullanılır:** Herhangi bir kod dosyasını açın ve Copilot'a önerilen soruları sorun. Proje kod tabanının tüm bağlamını bilir, açıklama yapabilir, genişletebilir ve alternatifler önerebilir. -Daha fazla öğrenmek ister misiniz? [AI Eşli Programlama için Copilot](https://aka.ms/GitHubCopilotAI) sayfasına göz atın. +Daha fazlasını öğrenmek ister misiniz? [AI Eşli Programlama için Copilot](https://aka.ms/GitHubCopilotAI)'a göz atın. ## Ek Kaynaklar @@ -112,39 +111,40 @@ Daha fazla öğrenmek ister misiniz? [AI Eşli Programlama için Copilot](https: --- ### Temel Öğrenme -[![Yeni Başlayanlar için ML](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Yeni Başlayanlar için Makine Öğrenimi](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Yeni Başlayanlar için Veri Bilimi](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![Yeni Başlayanlar için AI](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Yeni Başlayanlar için Siber Güvenlik](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Yeni Başlayanlar için Web Geliştirme](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![Yeni Başlayanlar için IoT](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![Yeni Başlayanlar için XR Geliştirme](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +[![Yeni Başlayanlar İçin Web Geliştirme](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![Yeni Başlayanlar İçin IoT](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![Yeni Başlayanlar İçin XR Geliştirme](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Copilot Serisi -[![Yapay Zeka Eşli Programlama için Copilot](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![AI Eşliğinde Programlama için Copilot](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) [![C#/.NET için Copilot](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot Macerası](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) - +[![Copilot Maceraları](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) + ## Yardım Alma -Tıkanırsanız veya yapay zeka uygulamaları oluşturma hakkında sorularınız varsa, katılın: +Takılırsanız veya AI uygulamaları geliştirme hakkında sorularınız varsa katılın: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Ürün geri bildirimi veya hata bildirimi için: +Ürün geri bildirimi veya geliştirirken oluşan hatalar için ziyaret edin: [![Microsoft Foundry Geliştirici Forumu](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Lisans -MIT Lisansı - Detaylar için [LICENSE](../../LICENSE) dosyasına bakınız. +MIT Lisansı - Ayrıntılar için [LICENSE](../../LICENSE) dosyasına bakın. --- -**Feragatname**: -Bu belge, AI çeviri servisi [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etmemize rağmen, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, ana dili olarak kabul edilen kaynak olarak değerlendirilmelidir. Kritik bilgiler için profesyonel insan tercümesi önerilir. Bu çevirinin kullanımı sonucunda oluşabilecek yanlış anlamalar veya yorum hatalarından sorumlu değiliz. +**Feragatname**: +Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz. \ No newline at end of file diff --git a/translations/tr/docs/GLOSSARY.md b/translations/tr/docs/GLOSSARY.md index 104bf139b..55f6fff48 100644 --- a/translations/tr/docs/GLOSSARY.md +++ b/translations/tr/docs/GLOSSARY.md @@ -2,53 +2,53 @@ ## İçindekiler -- [Temel Kavramlar](../../../docs) -- [LangChain4j Bileşenleri](../../../docs) -- [AI/ML Kavramları](../../../docs) -- [Koruyucu Önlemler](../../../docs) -- [İstem Mühendisliği](../../../docs) -- [RAG (Getirme Destekli Üretim)](../../../docs) -- [Ajanlar ve Araçlar](../../../docs) -- [Agentic Modülü](../../../docs) -- [Model Bağlam Protokolü (MCP)](../../../docs) -- [Azure Hizmetleri](../../../docs) -- [Test ve Geliştirme](../../../docs) - -Kurs boyunca kullanılan terimler ve kavramlar için hızlı başvuru. +- [Temel Kavramlar](#temel-kavramlar) +- [LangChain4j Bileşenleri](#langchain4j-bileşenleri) +- [AI/ML Kavramları](#aiml-kavramları) +- [Koruma Yolları](#koruma-yolları) +- [Prompt Mühendisliği](#prompt-engineering---module-02) +- [RAG (Alkılımsal Üretim)](#rag-retrieval-augmented-generation---module-03) +- [Ajanlar ve Araçlar](#agents-and-tools---module-04) +- [Ajan Modülü](#agentic-module---module-05) +- [Model Bağlam Protokolü (MCP)](#model-context-protocol-mcp---module-05) +- [Azure Hizmetleri](#azure-services---module-01) +- [Test ve Geliştirme](#testing-and-development---testing-guide) + +Kurs boyunca kullanılan terimler ve kavramlar için hızlı referans. ## Temel Kavramlar -**AI Agent** - Yapay zekayı kullanarak kendi kendine düşünen ve hareket eden sistem. [Modül 04](../04-tools/README.md) +**AI Agent** - Yapay zekayı kullanarak otonom şekilde düşünen ve hareket eden sistem. [Modül 04](../04-tools/README.md) -**Chain** - Çıkışın sonraki adıma aktarıldığı işlem dizisi. +**Chain** - Bir sonraki adıma çıktı veren operasyonlar zinciri. -**Chunking** - Belgelerin daha küçük parçalara bölünmesi. Tipik: 300-500 token ve örtüşme. [Modül 03](../03-rag/README.md) +**Chunking** - Belgeleri daha küçük parçalara ayırma. Tipik: 300-500 token arası, örtüşmeli. [Modül 03](../03-rag/README.md) -**Context Window** - Bir modelin işleyebileceği maksimum token sayısı. GPT-5.2: 400K token (en fazla 272K giriş, 128K çıkış). +**Context Window** - Bir modelin işleyebileceği maksimum token sayısı. GPT-5.2: 400K token (en fazla 272K girdi, 128K çıktı). **Embeddings** - Metin anlamını temsil eden sayısal vektörler. [Modül 03](../03-rag/README.md) -**Function Calling** - Modelin dış işlevleri çağırmak için yapılandırılmış istekler üretmesi. [Modül 04](../04-tools/README.md) +**Function Calling** - Modelin harici fonksiyonları çağırmak için yapılandırılmış istekler oluşturması. [Modül 04](../04-tools/README.md) -**Hallucination** - Modellerin hatalı ama inanılır bilgiler üretmesi. +**Hallucination** - Modellerin yanlış fakat makul görünen bilgi üretmesi. **Prompt** - Dil modeline verilen metin girdisi. [Modül 02](../02-prompt-engineering/README.md) -**Semantic Search** - Anahtar kelime değil, gömülü anlam kullanarak arama. [Modül 03](../03-rag/README.md) +**Semantic Search** - Anahtar kelime yerine anlam kullanarak arama yapma. [Modül 03](../03-rag/README.md) **Stateful vs Stateless** - Stateless: hafızasız. Stateful: konuşma geçmişini tutar. [Modül 01](../01-introduction/README.md) **Tokens** - Modellerin işlediği temel metin birimleri. Maliyet ve sınırları etkiler. [Modül 01](../01-introduction/README.md) -**Tool Chaining** - Çıktının sonraki çağrıyı bilgilendirdiği ardışık araç yürütme. [Modül 04](../04-tools/README.md) +**Tool Chaining** - Çıktısı sonraki çağrıyı yönlendiren ardışık araç çalıştırma. [Modül 04](../04-tools/README.md) ## LangChain4j Bileşenleri -**AiServices** - Tip-güvenli yapay zeka servis arayüzleri oluşturur. +**AiServices** - Tür güvenli yapay zeka hizmet arayüzleri oluşturur. **OpenAiOfficialChatModel** - OpenAI ve Azure OpenAI modelleri için birleşik istemci. -**OpenAiOfficialEmbeddingModel** - OpenAI Resmi istemcisi kullanarak gömüler oluşturur (OpenAI ve Azure OpenAI destekler). +**OpenAiOfficialEmbeddingModel** - OpenAI Official istemci kullanarak embedding oluşturur (OpenAI ve Azure OpenAI destekler). **ChatModel** - Dil modelleri için temel arayüz. @@ -56,17 +56,17 @@ Kurs boyunca kullanılan terimler ve kavramlar için hızlı başvuru. **ContentRetriever** - RAG için ilgili belge parçalarını bulur. -**DocumentSplitter** - Belgeleri parçalara böler. +**DocumentSplitter** - Belgeleri parçalara ayırır. **EmbeddingModel** - Metni sayısal vektörlere dönüştürür. -**EmbeddingStore** - Gömüleri depolar ve geri getirir. +**EmbeddingStore** - Embeddingleri depolar ve alır. **MessageWindowChatMemory** - Son mesajların kayan penceresini tutar. -**PromptTemplate** - `{{değişken}}` yer tutucularla yeniden kullanılabilir istemler oluşturur. +**PromptTemplate** - `{{değişken}}` yer tutucularıyla yeniden kullanılabilir promptlar oluşturur. -**TextSegment** - Meta verili metin parçası. RAG'de kullanılır. +**TextSegment** - Metadata içeren metin parçası. RAG’de kullanılır. **ToolExecutionRequest** - Araç yürütme isteğini temsil eder. @@ -74,153 +74,151 @@ Kurs boyunca kullanılan terimler ve kavramlar için hızlı başvuru. ## AI/ML Kavramları -**Few-Shot Learning** - İstemlerde örnek sağlama. [Modül 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Promptlarda örnekler sağlama. [Modül 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - Büyük metin verisiyle eğitilmiş yapay zeka modelleri. +**Large Language Model (LLM)** - Devasa metin veri ile eğitilmiş yapay zeka modelleri. -**Reasoning Effort** - GPT-5.2 parametresi, düşünmenin derinliğini kontrol eder. [Modül 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - Düşünme derinliğini kontrol eden GPT-5.2 parametresi. [Modül 02](../02-prompt-engineering/README.md) -**Temperature** - Çıktı rastgeleliğini kontrol eder. Düşük=belirli, yüksek=yaratıcı. +**Temperature** - Çıktı rastgeleliğini kontrol eder. Düşük=kesin, yüksek=yaratıcı. -**Vector Database** - Gömüler için özel veritabanı. [Modül 03](../03-rag/README.md) +**Vector Database** - Embeddingler için özelleşmiş veritabanı. [Modül 03](../03-rag/README.md) **Zero-Shot Learning** - Örnek olmadan görev yapma. [Modül 02](../02-prompt-engineering/README.md) -## Koruyucu Önlemler - [Modül 00](../00-quick-start/README.md) +## Koruma Yolları -**Defense in Depth** - Uygulama seviyesinde koruyucu önlemlerle sağlayıcı güvenlik filtrelerini birleştiren çok katmanlı güvenlik yöntemi. +**Defense in Depth** - Uygulama seviyesinde koruma ve sağlayıcı güvenlik filtrelerini birleştiren çok katmanlı güvenlik yaklaşımı. -**Hard Block** - Sağlayıcı ciddi içerik ihlallerinde HTTP 400 hatası verir. +**Hard Block** - Sağlayıcının ciddi içerik ihlallerinde HTTP 400 hatası vermesi. -**InputGuardrail** - LLM’ye ulaşmadan önce kullanıcı girişini doğrulayan LangChain4j arayüzü. Zararlı istemleri erken engelleyerek maliyet ve gecikmeyi azaltır. +**InputGuardrail** - Kullanıcı girdisini LLM’ye ulaşmadan önce doğrulayan LangChain4j arayüzü. Zararlı promptları erken engelleyerek maliyet ve gecikmeyi azaltır. -**InputGuardrailResult** - Koruyucu doğrulama dönüş türü: `success()` veya `fatal("sebep")`. +**InputGuardrailResult** - Koruma doğrulama dönüş tipi: `success()` veya `fatal("sebep")`. -**OutputGuardrail** - AI yanıtlarını kullanıcılara dönmeden önce doğrulama arayüzü. +**OutputGuardrail** - AI yanıtlarını kullanıcıya dönmeden önce doğrulayan arayüz. -**Provider Safety Filters** - API düzeyinde ihlalleri yakalayan AI sağlayıcılarının yerleşik içerik filtreleri (örn. GitHub Modelleri). +**Provider Safety Filters** - AI sağlayıcılarından (ör. Azure OpenAI) gelen, API seviyesinde ihlalleri yakalayan yerleşik içerik filtreleri. -**Soft Refusal** - Model kibarca hatasız yanıt vermekten kaçınır. +**Soft Refusal** - Model nazikçe cevap vermeyi reddeder, hata vermez. -## İstem Mühendisliği - [Modül 02](../02-prompt-engineering/README.md) +## Prompt Mühendisliği - [Modül 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - Daha iyi doğruluk için adım adım muhakeme. +**Chain-of-Thought** - Daha doğru sonuç için adım adım akıl yürütme. -**Constrained Output** - Belirli format veya yapı zorunluluğu. +**Constrained Output** - Belirli format veya yapıyı zorlamak. -**High Eagerness** - GPT-5.2 için titiz düşünme kalıbı. +**High Eagerness** - GPT-5.2 için detaylı akıl yürütme örüntüsü. -**Low Eagerness** - GPT-5.2 için hızlı yanıt kalıbı. +**Low Eagerness** - GPT-5.2 için hızlı yanıt örüntüsü. -**Multi-Turn Conversation** - Değiş tokuşlar arasında bağlamın korunması. +**Multi-Turn Conversation** - Alışverişler arasında bağlam tutma. -**Role-Based Prompting** - Sistem mesajlarıyla model kişiliğini belirleme. +**Role-Based Prompting** - Model kişiliğini sistem mesajlarıyla belirleme. -**Self-Reflection** - Model kendi çıktısını değerlendirir ve geliştirir. +**Self-Reflection** - Model kendi çıktısını değerlendirip geliştirir. **Structured Analysis** - Sabit değerlendirme çerçevesi. **Task Execution Pattern** - Planla → Uygula → Özetle. -## RAG (Getirme Destekli Üretim) - [Modül 03](../03-rag/README.md) +## RAG (Alkılımsal Üretim) - [Modül 03](../03-rag/README.md) -**Document Processing Pipeline** - Yükle → parçala → göm → depola. +**Document Processing Pipeline** - Yükle → parçalara ayır → embedle → depola. -**In-Memory Embedding Store** - Test için geçici depolama. +**In-Memory Embedding Store** - Test için geçici bellek içi depolama. -**RAG** - Yanıtları dayandırmak için getirmeyle üretimi birleştirir. +**RAG** - Yanıtları temellendirmek için retrieval ile üretimi birleştirme. **Similarity Score** - Anlamsal benzerlik ölçüsü (0-1 arası). -**Source Reference** - Getirilen içerik hakkında meta veriler. +**Source Reference** - Alınan içeriğin meta verisi. ## Ajanlar ve Araçlar - [Modül 04](../04-tools/README.md) -**@Tool Annotation** - Java yöntemlerini AI tarafından çağrılabilir araç olarak işaretler. +**@Tool Annotation** - Java metodlarını AI çağrılabilir araç olarak işaretler. **ReAct Pattern** - Düşün → Hareket Et → Gözlemle → Tekrarla. **Session Management** - Farklı kullanıcılar için ayrı bağlamlar. -**Tool** - AI ajanının çağırabileceği işlev. +**Tool** - AI ajanının çağırabileceği fonksiyon. -**Tool Description** - Araç amacı ve parametrelerinin dökümantasyonu. +**Tool Description** - Araç amacı ve parametre dokümantasyonu. -## Agentic Modülü - [Modül 05](../05-mcp/README.md) +## Ajan Modülü - [Modül 05](../05-mcp/README.md) -**@Agent Annotation** - AI ajanlarını bildirimsel davranış tanımlamasıyla işaretler. +**@Agent Annotation** - AI ajanlarını deklaratif davranış tanımıyla işaretler. -**Agent Listener** - `beforeAgentInvocation()` ve `afterAgentInvocation()` ile ajan yürütmesini izler. +**Agent Listener** - `beforeAgentInvocation()` ve `afterAgentInvocation()` ile ajan yürütmesini izleme kancası. -**Agentic Scope** - Ajanların çıktıları paylaştığı, sonraki ajanların kullandığı ortak hafıza alanı. +**Agentic Scope** - Ajanların sonuçları `outputKey` ile paylaşıp sonraki ajanların kullanabileceği paylaşılan bellek. -**AgenticServices** - `agentBuilder()` ve `supervisorBuilder()` ile ajanlar oluşturan fabrika. +**AgenticServices** - `agentBuilder()` ve `supervisorBuilder()` ile ajan yaratma fabrikası. -**Conditional Workflow** - Koşullara göre farklı uzman ajanlara yönlendirme. +**Conditional Workflow** - Şartlara göre farklı uzman ajanlara yönlendirme. -**Human-in-the-Loop** - Onay veya içerik incelemesi için insan kontrol noktaları ekleyen iş akışı. +**Human-in-the-Loop** - Onay veya içerik inceleme için insan kontrol noktaları ekleyen iş akışı. -**langchain4j-agentic** - Bildirimsel ajan oluşturmak için Maven bağımlılığı (deneysel). +**langchain4j-agentic** - Deklaratif ajan oluşturma için Maven bağımlılığı (deneysel). -**Loop Workflow** - Belirli koşul gerçekleşene kadar ajan yürütmesini yineleme (örneğin kalite skoru ≥ 0.8). +**Loop Workflow** - Bir koşul sağlanana kadar ajan yürütmesini yineleme (örneğin kalite puanı ≥ 0.8). -**outputKey** - Ajan anotasyonu parametresi, sonuçların Agentic Scope’da nereye kaydedileceğini belirtir. +**outputKey** - Sonuçların Agentic Scope’da depolanacağı yeri belirten ajan anotasyonu parametresi. -**Parallel Workflow** - Bağımsız görevler için aynı anda birden fazla ajan çalıştırma. +**Parallel Workflow** - Bağımsız görevler için birden fazla ajanı eşzamanlı çalıştırma. -**Response Strategy** - Süpervizörün nihai cevabı oluşturma yöntemi: SON, ÖZET veya PUANLI. +**Response Strategy** - Süpervizörün son cevabı formüle etme biçimi: LAST, SUMMARY veya SCORED. -**Sequential Workflow** - Ajanları sırayla yürütme, çıktı bir sonraki adıma akar. +**Sequential Workflow** - Çıktıların sonraki adıma aktığı sıralı ajan yürütme. -**Supervisor Agent Pattern** - Bir süpervizör LLM’nin hangi alt ajanları çağıracağına dinamik karar verdiği gelişmiş ajan modeli. +**Supervisor Agent Pattern** - Süpervizör LLM’nin hangi alt ajanları çağıracağını dinamik olarak belirlediği gelişmiş ajan modeli. ## Model Bağlam Protokolü (MCP) - [Modül 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j’de MCP entegrasyonu için Maven bağımlılığı. +**langchain4j-mcp** - LangChain4j için MCP entegrasyonu Maven bağımlılığı. -**MCP** - Model Bağlam Protokolü: AI uygulamalarını dış araçlara bağlamak için standart. Bir kere oluştur, her yerde kullan. +**MCP** - Model Context Protocol: Yapay zeka uygulamalarını harici araçlara bağlamak için standart. Bir defa oluştur, her yerde kullan. -**MCP Client** - MCP sunucularına bağlanan ve araçları keşfedip kullanan uygulama. +**MCP Client** - MCP sunucularına bağlanan, araçları keşfedip kullanan uygulama. -**MCP Server** - Araçları net açıklamalar ve parametre şemalarıyla MCP üzerinden sunan servis. +**MCP Server** - MCP aracılığıyla araçları açıklamalar ve parametre şemalarıyla sunan hizmet. -**McpToolProvider** - LangChain4j bileşeni, MCP araçlarını AI servisleri ve ajanlarında kullanılmak üzere sarar. +**McpToolProvider** - MCP araçlarını AI servisleri ve ajanlarında kullanmak için saran LangChain4j bileşeni. -**McpTransport** - MCP iletişimi için arayüz. Uygulamaları Stdio ve HTTP içerir. +**McpTransport** - MCP iletişim arayüzü. Stdio ve HTTP uygulamaları mevcut. -**Stdio Transport** - Yerel işlem taşımacılığı, stdin/stdout üzerinden. Dosya sistemi erişimi veya komut satırı araçları için uygun. +**Stdio Transport** - stdin/stdout üzerinden yerel süreç iletişimi. Dosya sistemi erişimi veya komut satırı araçları için ideal. -**StdioMcpTransport** - MCP sunucusunu alt süreç olarak çalıştıran LangChain4j uygulaması. +**StdioMcpTransport** - MCP sunucusunu alt süreç olarak başlatan LangChain4j uygulaması. -**Tool Discovery** - İstemcinin sunucudan açıklamalar ve şemalarla mevcut araçları sorgulaması. +**Tool Discovery** - İstemcinin kullanılabilir araçlar için sunucuya açıklamalar ve şemalarla sorgu yapması. ## Azure Hizmetleri - [Modül 01](../01-introduction/README.md) **Azure AI Search** - Vektör özellikli bulut araması. [Modül 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - Azure kaynaklarını dağıtır. +**Azure Developer CLI (azd)** - Azure kaynaklarını dağıtma aracı. **Azure OpenAI** - Microsoft’un kurumsal AI servisi. -**Bicep** - Azure altyapı kodlama dili. [Altyapı Rehberi](../01-introduction/infra/README.md) +**Bicep** - Azure altyapı kodlama dili. [Altyapı Kılavuzu](../01-introduction/infra/README.md) -**Deployment Name** - Azure’da model dağıtma için ad. +**Deployment Name** - Azure’daki model dağıtımı adı. -**GPT-5.2** - En son OpenAI modeli, muhakeme kontrolü sağlıyor. [Modül 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Düşünme kontrolüne sahip en yeni OpenAI modeli. [Modül 02](../02-prompt-engineering/README.md) -## Test ve Geliştirme - [Test Rehberi](TESTING.md) +## Test ve Geliştirme - [Test Kılavuzu](TESTING.md) -**Dev Container** - Konteynerleştirilmiş geliştirme ortamı. [Yapılandırma](../../../.devcontainer/devcontainer.json) +**Dev Container** - Konteyner tabanlı geliştirme ortamı. [Yapılandırma](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Ücretsiz AI model oyun alanı. [Modül 00](../00-quick-start/README.md) - -**In-Memory Testing** - Bellekte geçici depolama ile test. +**In-Memory Testing** - Bellek içi depolama ile test. **Integration Testing** - Gerçek altyapı ile test. -**Maven** - Java derleme otomasyon aracı. +**Maven** - Java yapı otomasyon aracı. -**Mockito** - Java için sahte/mock kütüphanesi. +**Mockito** - Java taklit kütüphanesi. **Spring Boot** - Java uygulama çatısı. [Modül 01](../01-introduction/README.md) @@ -228,5 +226,5 @@ Kurs boyunca kullanılan terimler ve kavramlar için hızlı başvuru. **Feragatname**: -Bu belge, AI çeviri servisi [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hatalar veya yanlışlıklar içerebileceğini lütfen unutmayın. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalar veya yorum hatalarından sorumlu değiliz. +Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz. \ No newline at end of file diff --git a/translations/tr/docs/TESTING.md b/translations/tr/docs/TESTING.md index df93a961c..115554f3f 100644 --- a/translations/tr/docs/TESTING.md +++ b/translations/tr/docs/TESTING.md @@ -2,19 +2,19 @@ ## İçindekiler -- [Hızlı Başlangıç](../../../docs) -- [Testlerin Kapsadığı Konular](../../../docs) -- [Testleri Çalıştırma](../../../docs) -- [VS Code'da Testleri Çalıştırma](../../../docs) -- [Test Şablonları](../../../docs) -- [Test Felsefesi](../../../docs) -- [Sonraki Adımlar](../../../docs) +- [Hızlı Başlangıç](#hızlı-başlangıç) +- [Testlerin Kapsadığı Konular](#testlerin-kapsadığı-konular) +- [Testleri Çalıştırma](#testleri-çalıştırma) +- [VS Code'da Testleri Çalıştırma](#vs-code’da-testleri-çalıştırma) +- [Test Desenleri](#test-desenleri) +- [Test Felsefesi](#test-felsefesi) +- [Sonraki Adımlar](#sonraki-adımlar) -Bu rehber, API anahtarları veya harici servisler gerektirmeden AI uygulamalarını nasıl test edeceğinizi gösteren testleri adım adım anlatır. +Bu rehber, API anahtarı veya dış servis gerektirmeden yapay zeka uygulamalarını nasıl test edeceğinizi gösteren testleri adım adım anlatır. ## Hızlı Başlangıç -Tüm testleri tek bir komutla çalıştırın: +Tüm testleri tek komutla çalıştırın: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Tüm testler geçtiğinde, aşağıdaki ekran görüntüsündeki gibi hata almadan testlerin çalıştığını görmelisiniz. +Tüm testler geçtiğinde, aşağıdaki ekran görüntüsündeki gibi bir çıktı görmelisiniz — testler sıfır hata ile çalışır. Başarılı Test Sonuçları -*Hata almadan tüm testlerin geçtiğini gösteren başarılı test çalıştırması* +*Başarılı test çalıştırması, tüm testlerin sıfır hata ile geçtiğini gösteriyor* ## Testlerin Kapsadığı Konular -Bu eğitim, yerel olarak çalışan **birim testlere** odaklanır. Her test, LangChain4j'nin belirli bir kavramını izole şekilde gösterir. Aşağıdaki test piramidi, birim testlerin nerede yer aldığını gösterir — test stratejinizin hızlı, güvenilir temelini oluştururlar. +Bu kurs, yerel olarak çalışan **birim testlere** odaklanır. Her test, LangChain4j'nin belirli bir kavramını izole şekilde gösterir. Aşağıdaki test piramidi birim testlerin nerede durduğunu gösterir — hızlı ve güvenilir temeli oluştururlar, diğer test stratejileriniz bunların üzerine inşa edilir. Test Piramidi -*Birim testler (hızlı, izole), entegrasyon testleri (gerçek bileşenler) ve uçtan uca testler arasındaki dengeyi gösteren test piramidi. Bu eğitim birim testi kapsamaktadır.* +*Test piramidi, birim testlerin (hızlı, izole), entegrasyon testlerinin (gerçek bileşenler) ve uçtan uca testlerin dengesini gösterir. Bu eğitim birim testi kapsar.* | Modül | Testler | Odak | Ana Dosyalar | |--------|-------|-------|-----------| -| **00 - Hızlı Başlangıç** | 6 | İstek şablonları ve değişken yer değiştirme | `SimpleQuickStartTest.java` | -| **01 - Giriş** | 8 | Konuşma belleği ve durumlu sohbet | `SimpleConversationTest.java` | -| **02 - İstek Mühendisliği** | 12 | GPT-5.2 şablonları, istek istekliliği, yapılandırılmış çıktı | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Doküman işleme, gömme (embedding), benzerlik araması | `DocumentServiceTest.java` | -| **04 - Araçlar** | 12 | Fonksiyon çağırma ve araç zincirleme | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Kontekst Protokolü (MCP) stdio taşıma ile | `SimpleMcpTest.java` | +| **01 - Giriş** | 8 | Konuşma hafızası ve durumlu sohbet | `SimpleConversationTest.java` | +| **02 - Prompt Mühendisliği** | 12 | GPT-5.2 desenleri, istek seviyeleri, yapılandırılmış çıktı | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Doküman alımı, gömme işlemleri, benzerlik araması | `DocumentServiceTest.java` | +| **04 - Araçlar** | 12 | Fonksiyon çağırma ve araç zinciri | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol, stdio transport ile | `SimpleMcpTest.java` | ## Testleri Çalıştırma -**Kök dizinden tüm testleri çalıştır:** +**Tüm testleri kök dizinden çalıştırın:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Belirli bir modülün testlerini çalıştır:** +**Belirli bir modülün testlerini çalıştırın:** **Bash:** ```bash @@ -75,11 +74,11 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# Ya da kök dizinden +# Veya kök dizinden mvn --% test -pl 01-introduction ``` -**Tek bir test sınıfını çalıştır:** +**Tek bir test sınıfını çalıştırın:** **Bash:** ```bash @@ -91,7 +90,7 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Belirli bir test metodunu çalıştır:** +**Belirli bir test metodunu çalıştırın:** **Bash:** ```bash @@ -105,31 +104,31 @@ mvn --% test -Dtest=SimpleConversationTest#Konuşma geçmişi korunmalı mı ## VS Code'da Testleri Çalıştırma -Visual Studio Code kullanıyorsanız, Test Gezgini testleri çalıştırmak ve hata ayıklamak için grafiksel bir arayüz sağlar. +Visual Studio Code kullanıyorsanız, Test Explorer testleri çalıştırmak ve hata ayıklamak için grafiksel bir arayüz sağlar. -VS Code Test Gezgini +VS Code Test Explorer -*Tüm Java test sınıfları ve tekil test metotlarını gösteren VS Code Test Gezgini test ağacı* +*VS Code Test Explorer, tüm Java test sınıflarını ve bireysel test metodlarını gösteren test ağacını sunar* **VS Code'da testleri çalıştırmak için:** -1. Aktivite Çubuğundaki beher simgesine tıklayarak Test Gezgini'ni açın -2. Tüm modülleri ve test sınıflarını görmek için test ağacını genişletin -3. Herhangi bir testi tek başına çalıştırmak için yanındaki oynat düğmesine tıklayın -4. Tüm testleri çalıştırmak için "Tüm Testleri Çalıştır" seçeneğine tıklayın -5. Herhangi bir teste sağ tıklayarak "Testi Hata Ayıkla" ile kesme noktaları ayarlayıp kodda adım adım ilerleyin +1. Aktivite Çubuğundaki beherik simgesine tıklayarak Test Explorer'ı açın +2. Test ağacını genişleterek tüm modülleri ve test sınıflarını görün +3. Herhangi bir testi tek başına çalıştırmak için yanındaki oynat düğmesine tıklayın +4. Tüm testleri çalıştırmak için "Run All Tests" seçeneğine tıklayın +5. Herhangi bir teste sağ tıklayıp "Debug Test" seçerek kesme noktaları ayarlayın ve kodda adım adım ilerleyin -Test Gezgini geçen testler için yeşil onay işaretleri gösterir ve başarısızlık durumunda detaylı hata mesajları sağlar. +Test Explorer başarılı testler için yeşil onay işaretleri gösterir ve test başarısız olduğunda detaylı hata mesajları sağlar. -## Test Şablonları +## Test Desenleri -### Şablon 1: İstek Şablonlarını Test Etme +### Desen 1: Prompt Şablonlarını Test Etme -En basit şablon, herhangi bir AI modelini çağırmadan istek şablonlarını test eder. Değişken yer değiştirmesinin doğru çalıştığını ve isteklerin doğru formatlandığını doğrularsınız. +En basit desen, hiç AI modeli çağırmadan prompt şablonlarını test eder. Değişken yer değiştirmesinin doğru işlediğini ve promptların beklenen formatta olduğunu doğrularsınız. -İstek Şablonu Testi +Prompt Şablonu Testi -*Değişken yer değiştirme akışını gösteren istek şablonu testi: yer tutuculu şablon → uygulanan değerler → doğrulanmış biçimlendirilmiş çıktı* +*Değişken yer değiştirme akışını gösteren prompt şablonu testi: yer tutucuları olan şablon → değerlerin uygulanması → biçimlendirilmiş çıktının doğrulanması* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Bu test `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` dosyasında yer alır. - -**Çalıştırmak için:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#testPromptŞablonFormatlama -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#testİstemŞablonuBiçimlendirmesi -``` +Bu desen, değişkenlerin doğru şekilde yer değiştirdiğini ve promptların beklenen formatta olduğunu doğrular — API anahtarı veya model çağrısı gerektirmez. -### Şablon 2: Dil Modellerini Taklit Etme (Mocking) +### Desen 2: Dil Modellerini Taklit Etme -Sohbet mantığını test ederken, önceden belirlenmiş yanıtları dönen sahte (mock) modeller oluşturmak için Mockito kullanın. Bu testleri hızlı, ücretsiz ve deterministik (kesin) yapar. +Konuşma mantığını test ederken, önceden belirlenmiş cevapları dönen sahte modeller oluşturmak için Mockito kullanın. Bu testleri hızlı, ücretsiz ve deterministik yapar. -Mock ve Gerçek API Karşılaştırması +Sahte ve Gerçek API Karşılaştırması -*Testler için neden mock tercih edildiğini gösteren karşılaştırma: hızlı, ücretsiz, deterministik ve API anahtarı gerektirmezler* +*Testlerde neden sahte modellerin tercih edildiğini gösteren karşılaştırma: hızlı, ücretsiz, deterministik ve API anahtarı gerektirmezler* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 kullanıcı + 3 yapay zeka mesajı + assertThat(history).hasSize(6); // 3 kullanıcı + 3 AI mesajı } } ``` -Bu şablon `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` dosyasında bulunur. Mock, bellek yönetiminin doğru çalıştığını doğrulamanız için tutarlı davranış sağlar. +Bu desen `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` dosyasında bulunur. Sahte model tutarlı davranış sağlar, böylece hafıza yönetiminin doğru çalıştığını doğrulayabilirsiniz. -### Şablon 3: Konuşma İzolasyonunu Test Etme +### Desen 3: Konuşma İzolasyonunu Test Etme -Konuşma belleği, birden çok kullanıcıyı ayrı tutmalıdır. Bu test, konuşmaların bağlamlarını karıştıramayacağını doğrular. +Konuşma hafızası birden fazla kullanıcıyı ayrı tutmalıdır. Bu test, konuşmaların bağlamları karıştırmadığını doğrular. Konuşma İzolasyonu -*Bağlam karışıklığını önlemek için farklı kullanıcılar için ayrı bellek depolarını gösteren konuşma izolasyon testi* +*Farklı kullanıcılar için ayrı hafıza depolarını gösteren konuşma izolasyonu testi* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Her konuşma kendi bağımsız geçmişini tutar. Üretim sistemlerinde bu izolasyon, çok kullanıcılı uygulamalar için kritik önemdedir. +Her konuşma kendi bağımsız geçmişini korur. Üretim sistemlerinde bu izolasyon çoklu kullanıcı uygulamaları için kritik önemdedir. -### Şablon 4: Araçları Bağımsız Test Etme +### Desen 4: Araçları Bağımsız Test Etme -Araçlar, AI'nın çağırabileceği fonksiyonlardır. Bunları doğrudan test ederek AI kararlarından bağımsız çalıştıklarından emin olun. +Araçlar, AI'nın çağırabileceği fonksiyonlardır. AI kararlarından bağımsız olarak doğru çalıştıklarını doğrudan test edin. -Araçların Testi +Araçların Test Edilmesi -*İş mantığını doğrulamak için AI çağrısı olmadan mock araç yürütmesini gösteren araçların bağımsız testi* +*İş mantığını doğrulamak için AI çağrısı olmadan sahte araç yürütmesini gösteren araçların bağımsız testi* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Bu testler `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` dosyasından gelir. Zincirleme örneği, bir aracın çıktısının diğerinin girdisi olarak nasıl beslediğini gösterir. +`04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` dosyasındaki bu testler, AI etkisi olmadan araç mantığını doğrular. Zincirleme örneği, bir aracın çıktısının diğerinin girdisi olarak nasıl kullanıldığını gösterir. -### Şablon 5: Bellek İçi RAG Testi +### Desen 5: Bellek İçi RAG Testi -RAG sistemleri geleneksel olarak vektör tabanlı veri tabanları ve gömme servisleri gerektirir. Bellek içi şablon, tüm hattı harici bağımlılıklar olmadan test etmenizi sağlar. +RAG sistemleri geleneksel olarak vektör veritabanları ve gömme servisleri gerektirir. Bellek içi desen, dış bağımlılıklar olmadan tüm boru hattını test etmenizi sağlar. Bellek İçi RAG Testi -*Veritabanı gerektirmeden doküman ayrıştırma, gömme depolama ve benzerlik araması gösteren bellek içi RAG test iş akışı* +*Veritabanı gerektirmeden doküman ayrıştırma, gömme depolama ve benzerlik aramayı gösteren bellek içi RAG testi iş akışı* ```java @Test @@ -306,11 +293,11 @@ void testProcessTextDocument() { } ``` -Bu test `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` dosyasından gelir; bellek içinde bir doküman oluşturur ve parçalama ile meta veri işlemini doğrular. +`03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` dosyasından bu test, bellekte bir doküman oluşturur ve parçalama ile meta veri işleme adımlarını doğrular. -### Şablon 6: MCP Entegrasyon Testi +### Desen 6: MCP Entegrasyon Testi -MCP modülü stdio taşıma kullanarak Model Kontekst Protokolü entegrasyonunu test eder. Bu testler, uygulamanızın MCP sunucularını alt süreç olarak başlatıp iletişim kurabildiğini doğrular. +MCP modülü, stdio transport kullanarak Model Context Protocol entegrasyonunu test eder. Bu testler, uygulamanızın MCP sunucularını alt süreç olarak başlatıp iletişim kurabildiğini doğrular. `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` dosyasındaki testler MCP istemci davranışını doğrular. @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Test Felsefesi -AI'yı değil, kendi kodunuzu test edin. Testleriniz, isteklerin nasıl oluşturulduğunu, belleğin nasıl yönetildiğini ve araçların nasıl çalıştırıldığını kontrol ederek yazdığınız kodu doğrulamalı. AI yanıtları değişir ve test doğrulamalarının parçası olmamalıdır. Soru şu olmalı: "İstek şablonum değişkenleri doğru şekilde değiştiriyor mu?" değil, "AI doğru cevap mı veriyor?" +Kodunuzu test edin, AI'yı değil. Testleriniz, yazdığınız kodu doğrulamalı; promptların nasıl oluşturulduğunu, hafızanın nasıl yönetildiğini ve araçların nasıl yürütüldüğünü kontrol etmelidir. AI yanıtları değişkendir ve test iddialarının parçası olmamalıdır. Sorun kendinize, prompt şablonunuz değişkenleri doğru şekilde değiştiriyor mu olmamalı, AI doğru cevabı veriyor mu olmamalıdır. -Dil modelleri için mock kullanın. Bunlar dış bağımlılıklar olup yavaş, pahalı ve deterministik olmayan kaynaklardır. Mocking, testleri saniyeler yerine milisaniyeler içinde hızlı, ücretsiz ve her seferinde aynı sonucu veren deterministik hale getirir. +Dil modelleri için sahte modeller kullanın. Bunlar dış bağımlılıklardır, yavaş, pahalı ve deterministik olmayan davranış sergilerler. Sahte modeller testleri saniyeler yerine milisaniyeler içinde hızlı, API ücreti olmadan ücretsiz ve her seferinde aynı sonucu veren deterministik yapar. -Testleri bağımsız tutun. Her test kendi verisini kurmalı, diğer testlere bağlı olmamalı ve kendi temizliğini yapmalı. Testler çalıştırma sırasından bağımsız olarak geçmelidir. +Testleri bağımsız tutun. Her test kendi verisini kurmalı, diğer testlere bağlı olmamalı ve kendi temizlik işini yapmalıdır. Testler çalıştırma sırasına bakılmaksızın geçmelidir. -Mutlu yolun ötesinde uç durumları test edin. Boş girdiler, çok büyük girdiler, özel karakterler, geçersiz parametreler ve sınır koşulları deneyin. Bunlar genellikle normal kullanımda ortaya çıkmayan hataları ortaya çıkarır. +Mutlu yolun dışındaki durumları test edin. Boş girişler, çok büyük girdiler, özel karakterler, geçersiz parametreler ve sınır durumlarını deneyin. Bunlar genellikle normal kullanımda ortaya çıkmayan hataları verir. -Anlamlı isimler kullanın. `shouldMaintainConversationHistoryAcrossMultipleMessages()` ile `test1()` karşılaştırın. İlki tam olarak ne test edildiğini söyler, hata ayıklamayı çok kolaylaştırır. +Anlamlı isimler kullanın. `shouldMaintainConversationHistoryAcrossMultipleMessages()` ile `test1()`’i karşılaştırın. İlki tam olarak ne test edildiğini söyler, hata ayıklamayı çok kolaylaştırır. ## Sonraki Adımlar -Test şablonlarını anladıysanız, her modüle derinlemesine dalın: +Artık test desenlerini anladığınıza göre, her modüle daha derinlemesine dalabilirsiniz: -- **[00 - Hızlı Başlangıç](../00-quick-start/README.md)** - İstek şablonu temelleriyle başlayın -- **[01 - Giriş](../01-introduction/README.md)** - Konuşma belleği yönetimini öğrenin -- **[02 - İstek Mühendisliği](../02/prompt-engineering/README.md)** - GPT-5.2 istek şablonları ustası olun -- **[03 - RAG](../03-rag/README.md)** - Geri getirme artırılmış üretim sistemleri oluşturun -- **[04 - Araçlar](../04-tools/README.md)** - Fonksiyon çağırma ve araç zincirleri uygulayın -- **[05 - MCP](../05-mcp/README.md)** - Model Kontekst Protokolü entegre edin +- **[01 - Giriş](../01-introduction/README.md)** - Konuşma hafızası yönetimini öğrenin +- **[02 - Prompt Mühendisliği](../02/prompt-engineering/README.md)** - GPT-5.2 prompting desenlerinde ustalaşın +- **[03 - RAG](../03-rag/README.md)** - Retrieve-augmented generation sistemleri oluşturun +- **[04 - Araçlar](../04-tools/README.md)** - Fonksiyon çağırma ve araç zincirlerini uygulayın +- **[05 - MCP](../05-mcp/README.md)** - Model Context Protocol entegrasyonu yapın -Her modülün README dosyası burada test edilen kavramların ayrıntılı açıklamalarını içerir. +Her modülün README dosyası burada test edilen kavramların detaylı açıklamalarını içerir. --- -**Geçiş:** [← Ana Sayfaya Geri](../README.md) +**Gezi:** [← Ana Sayfaya Dön](../README.md) --- -**Feragatname**: -Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlıklar içerebileceğini lütfen unutmayınız. Orijinal belge, kendi ana dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucunda oluşabilecek herhangi bir yanlış anlama veya hatalı yorumlamadan sorumlu değiliz. +**Feragatname**: +Bu belge, AI çeviri hizmeti [Co-op Translator](https://github.com/Azure/co-op-translator) kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz. \ No newline at end of file diff --git a/translations/uk/.co-op-translator.json b/translations/uk/.co-op-translator.json index b3b06b979..61c906a27 100644 --- a/translations/uk/.co-op-translator.json +++ b/translations/uk/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "uk" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T19:59:54+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T13:48:41+00:00", "source_file": "01-introduction/README.md", "language_code": "uk" }, @@ -18,20 +18,20 @@ "language_code": "uk" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T20:03:16+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T13:44:03+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "uk" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T20:05:09+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T13:47:46+00:00", "source_file": "03-rag/README.md", "language_code": "uk" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T11:39:11+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T13:46:29+00:00", "source_file": "04-tools/README.md", "language_code": "uk" }, @@ -54,8 +54,8 @@ "language_code": "uk" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:55:58+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T13:42:46+00:00", "source_file": "README.md", "language_code": "uk" }, @@ -72,14 +72,14 @@ "language_code": "uk" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T20:09:57+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T13:44:34+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "uk" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T20:10:55+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T13:45:13+00:00", "source_file": "docs/TESTING.md", "language_code": "uk" } diff --git a/translations/uk/00-quick-start/README.md b/translations/uk/00-quick-start/README.md deleted file mode 100644 index 17cce366b..000000000 --- a/translations/uk/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Швидкий старт - -## Зміст - -- [Вступ](../../../00-quick-start) -- [Що таке LangChain4j?](../../../00-quick-start) -- [Залежності LangChain4j](../../../00-quick-start) -- [Вимоги](../../../00-quick-start) -- [Налаштування](../../../00-quick-start) - - [1. Отримайте ваш GitHub токен](../../../00-quick-start) - - [2. Встановіть ваш токен](../../../00-quick-start) -- [Запуск прикладів](../../../00-quick-start) - - [1. Базовий чат](../../../00-quick-start) - - [2. Шаблони промптів](../../../00-quick-start) - - [3. Виклик функцій](../../../00-quick-start) - - [4. Запитання та відповіді по документах (Easy RAG)](../../../00-quick-start) - - [5. Відповідальний ШІ](../../../00-quick-start) -- [Що показує кожний приклад](../../../00-quick-start) -- [Наступні кроки](../../../00-quick-start) -- [Вирішення проблем](../../../00-quick-start) - -## Вступ - -Цей швидкий старт призначений, щоб якомога швидше познайомити вас із LangChain4j. Він охоплює абсолютно базові речі для створення AI-застосунків з LangChain4j та GitHub Models. У наступних модулях ви перейдете на Azure OpenAI та GPT-5.2 і глибше вивчатимете кожну концепцію. - -## Що таке LangChain4j? - -LangChain4j — це Java бібліотека, яка спрощує створення застосунків із підтримкою AI. Замість роботи з HTTP клієнтами та парсингом JSON ви працюєте з чистими Java API. - -"Chain" у LangChain означає з'єднання кількох компонентів в одну ланцюжок — ви можете поєднати промпт з моделлю, потім із парсером, або з'єднати кілька AI викликів, де вихід одного стає вхідними даними для наступного. Цей швидкий старт зосереджений на основах, перед тим як перейти до складніших ланцюжків. - -LangChain4j Chaining Concept - -*Зʼєднання компонентів у LangChain4j – будівельні блоки обʼєднуються для створення потужних AI робочих процесів* - -Ми використовуємо три ключові компоненти: - -**ChatModel** — інтерфейс для взаємодії з AI моделями. Викликайте `model.chat("prompt")` і отримуйте рядок-відповідь. Ми використовуємо `OpenAiOfficialChatModel`, який працює з сумісними з OpenAI кінцевими точками, як GitHub Models. - -**AiServices** — створює типобезпечні інтерфейси AI-сервісів. Визначайте методи, анотуйте їх за допомогою `@Tool`, і LangChain4j керує оркестрацією. AI автоматично викликає ваші Java методи за потреби. - -**MessageWindowChatMemory** — зберігає історію розмови. Без цього кожен запит — незалежний. З ним AI пам’ятає попередні повідомлення і підтримує контекст кількох ходів. - -LangChain4j Architecture - -*Архітектура LangChain4j — основні компоненти працюють разом, щоб забезпечити ваші AI-застосунки* - -## Залежності LangChain4j - -Цей швидкий старт використовує три Maven залежності у файлі [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Модуль `langchain4j-open-ai-official` надає клас `OpenAiOfficialChatModel`, який підключається до API сумісних з OpenAI. GitHub Models використовує той самий формат API, тож спеціальний адаптер не потрібен — просто вкажіть базовий URL `https://models.github.ai/inference`. - -Модуль `langchain4j-easy-rag` забезпечує автоматичне розбиття документів, ембеддинг і пошук, щоб ви могли створювати RAG-застосунки без ручного налаштування кожного кроку. - -## Вимоги - -**Використовуєте Dev Container?** Java та Maven уже встановлені. Вам потрібен лише GitHub Personal Access Token. - -**Локальна розробка:** -- Java 21+, Maven 3.9+ -- GitHub Personal Access Token (інструкції нижче) - -> **Примітка:** Цей модуль використовує `gpt-4.1-nano` від GitHub Models. Не змінюйте ім’я моделі в коді — вона налаштована для роботи з доступними моделями GitHub. - -## Налаштування - -### 1. Отримайте ваш GitHub токен - -1. Перейдіть на [GitHub Налаштування → Personal Access Tokens](https://github.com/settings/personal-access-tokens) -2. Натисніть «Generate new token» -3. Вкажіть описове ім’я (наприклад, "LangChain4j Demo") -4. Встановіть термін дії (рекомендовано 7 днів) -5. У розділі «Account permissions» знайдіть «Models» і встановіть «Read-only» -6. Натисніть «Generate token» -7. Скопіюйте та збережіть ваш токен — більше побачити його не зможете - -### 2. Встановіть ваш токен - -**Варіант 1: Використання VS Code (рекомендується)** - -Якщо ви користуєтеся VS Code, додайте ваш токен у файл `.env` у корені проєкту: - -Якщо файлу `.env` не існує, скопіюйте `.env.example` у `.env` або створіть новий файл `.env` у корені проекту. - -**Приклад файлу `.env`:** -```bash -# У /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Після цього ви можете просто клацнути правою кнопкою на будь-якому демонстраційному файлі (наприклад, `BasicChatDemo.java`) у Проводнику і вибрати **"Run Java"** або використати конфігурації запуску у панелі Run and Debug. - -**Варіант 2: Використання терміналу** - -Встановіть токен як змінну середовища: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Запуск прикладів - -**Використання VS Code:** Просто клікніть правою кнопкою на будь-якому демонстраційному файлі у Проводнику і виберіть **"Run Java"**, або використайте конфігурації запуску з панелі Run and Debug (переконайтеся, що токен доданий у `.env`). - -**Використання Maven:** Альтернативно можна запускати з командного рядка: - -### 1. Базовий чат - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Шаблони промптів - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Показує zero-shot, few-shot, chain-of-thought та рольові шаблони промптів. - -### 3. Виклик функцій - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI автоматично викликає ваші Java методи за необхідності. - -### 4. Запитання та відповіді по документах (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Задавайте питання щодо ваших документів, користуючись Easy RAG із автоматичним ембеддінгом та пошуком. - -### 5. Відповідальний ШІ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Подивіться, як фільтри безпеки ШІ блокують шкідливий контент. - -## Що показує кожний приклад - -**Базовий чат** — [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Почніть тут, щоб побачити LangChain4j у найпростішому вигляді. Ви створите `OpenAiOfficialChatModel`, надішлете промпт методом `.chat()` і отримаєте відповідь. Це демонструє основу: як ініціалізувати моделі з кастомними кінцевими точками та API ключами. Як тільки зрозумієте цей патерн, все інше будуватиметься на ньому. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) і запитайте: -> - "Як переключитися з GitHub Models на Azure OpenAI у цьому коді?" -> - "Які ще параметри можна налаштувати в OpenAiOfficialChatModel.builder()?" -> - "Як додати потокові відповіді замість очікування повної відповіді?" - -**Інженерія промптів** — [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Тепер, коли ви знаєте, як спілкуватися з моделлю, давайте розглянемо, що саме їй говорити. Цей демо-приклад використовує ту ж модель, але показує п’ять різних патернів промптів. Спробуйте zero-shot промпти для прямих інструкцій, few-shot, що навчаються на прикладах, chain-of-thought — щоб демонструвати кроки мислення, і рольові промпти, що встановлюють контекст. Ви побачите, як одна й та сама модель дає кардинально різні результати залежно від формулювання запиту. - -Демонстрація також показує шаблони промптів — потужний спосіб створювати багаторазові промпти з змінними. -Нижче наведено приклад промпта з використанням LangChain4j `PromptTemplate` для заповнення змінних. ШІ відповідатиме, ґрунтуючись на наданому пункті призначення та дії. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) і запитайте: -> - "У чому різниця між zero-shot і few-shot промптами, і коли який використовувати?" -> - "Як параметр temperature впливає на відповіді моделі?" -> - "Які є техніки для запобігання атак промпт-інжекцій у продакшні?" -> - "Як створювати багаторазові обʼєкти PromptTemplate для загальних патернів?" - -**Інтеграція інструментів** — [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Ось де LangChain4j стає потужним. Ви використаєте `AiServices` для створення AI асистента, який може викликати ваші Java методи. Просто анотуйте методи `@Tool("опис")` і LangChain4j потурбується про решту — AI автоматично вирішує, коли використовувати кожен інструмент згідно з тим, що просить користувач. Це демонструє виклик функцій — ключову техніку для створення AI, що може не тільки відповідати на питання, а й виконувати дії. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) і запитайте: -> - "Як працює анотація @Tool і що LangChain4j робить з нею за лаштунками?" -> - "Чи може AI викликати кілька інструментів послідовно для розв’язання складних проблем?" -> - "Що станеться, якщо інструмент кине виключення — як обробляти помилки?" -> - "Як інтегрувати реальне API замість цього прикладу калькулятора?" - -**Запитання та відповіді по документах (Easy RAG)** — [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Тут ви побачите RAG (retrieval-augmented generation) за допомогою підходу LangChain4j "Easy RAG". Документи завантажуються, автоматично розбиваються і вбудовуються в пам’ять, а потім пошуковик доставляє релевантні частини до AI під час запиту. AI відповідає на основі ваших документів, а не загальних знань. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) і запитайте: -> - "Як RAG запобігає галюцинаціям AI у порівнянні з використанням тренувальних даних моделі?" -> - "У чому різниця між цим легким підходом і власним RAG пайплайном?" -> - "Як масштабувати це для роботи з кількома документами або більшими базами знань?" - -**Відповідальний ШІ** — [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Побудуйте безпеку AI за принципом defense in depth. Цей приклад показує два рівні захисту, які працюють разом: - -**Частина 1: Вхідні обмеження LangChain4j** — Блокуйте небезпечні промпти, перш ніж вони дійдуть до LLM. Створюйте власні обмеження, що перевіряють заборонені ключові слова або шаблони. Вони працюють у вашому коді, тому швидкі і безкоштовні. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Частина 2: Фільтри безпеки провайдера** — GitHub Models має вбудовані фільтри, що ловлять те, що ваші обмеження можуть пропустити. Ви побачите жорстке блокування (помилки HTTP 400) для серйозних порушень і м’які відмови, коли AI ввічливо відмовляється. - -> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) і запитайте: -> - "Що таке InputGuardrail і як створити власний?" -> - "У чому різниця між жорстким блокуванням та м’якою відмовою?" -> - "Чому використовувати обмеження і фільтри провайдера разом?" - -## Наступні кроки - -**Наступний модуль:** [01-introduction - Початок роботи з LangChain4j](../01-introduction/README.md) - ---- - -**Навігація:** [← Назад до головної](../README.md) | [Далі: Модуль 01 - Вступ →](../01-introduction/README.md) - ---- - -## Вирішення проблем - -### Перший збір Maven - -**Проблема:** Початковий `mvn clean compile` або `mvn package` триває довго (10-15 хвилин) - -**Причина:** Maven має завантажити всі залежності проєкту (Spring Boot, бібліотеки LangChain4j, Azure SDK тощо) під час першої збірки. - -**Рішення:** Це нормальна поведінка. Наступні збірки будуть значно швидшими, бо залежності кешуються локально. Час завантаження залежить від швидкості вашого інтернету. - -### Синтаксис Maven команд у PowerShell - -**Проблема:** Maven команди падають з помилкою `Unknown lifecycle phase ".mainClass=..."` -**Причина**: PowerShell інтерпретує `=` як оператор присвоєння змінної, що порушує синтаксис властивостей Maven - -**Рішення**: Використовуйте оператор припинення розбору `--%` перед командою Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Оператор `--%` вказує PowerShell передавати всі наступні аргументи буквально Maven без інтерпретації. - -### Відображення емодзі у Windows PowerShell - -**Проблема**: Відповіді AI показують нечитаємі символи (наприклад, `????` або `â??`) замість емодзі у PowerShell - -**Причина**: За замовчуванням кодування PowerShell не підтримує UTF-8 емодзі - -**Рішення**: Виконайте цю команду перед запуском Java-додатків: -```cmd -chcp 65001 -``` - -Це примусить термінал використовувати кодування UTF-8. Альтернативно, використовуйте Windows Terminal, який має кращу підтримку Unicode. - -### Налагодження викликів API - -**Проблема**: Помилки автентифікації, обмеження частоти або несподівані відповіді від AI-моделі - -**Рішення**: Приклади містять `.logRequests(true)` і `.logResponses(true)` для відображення викликів API у консолі. Це допомагає усунути помилки автентифікації, обмеження частоти або несподівані відповіді. Видаліть ці прапорці у продакшн, щоб зменшити шум у логах. - ---- - - -**Відмова від відповідальності**: -Цей документ було перекладено за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, просимо враховувати, що автоматичні переклади можуть містити помилки або неточності. Оригінал документа мовою оригіналу слід вважати авторитетним джерелом. Для критичної інформації рекомендується звертатися до професійного людського перекладу. Ми не несемо відповідальності за будь-які непорозуміння чи неправильні тлумачення, що виникли внаслідок використання цього перекладу. - \ No newline at end of file diff --git a/translations/uk/01-introduction/README.md b/translations/uk/01-introduction/README.md index 6d9d19c1d..6637ce1cb 100644 --- a/translations/uk/01-introduction/README.md +++ b/translations/uk/01-introduction/README.md @@ -1,38 +1,38 @@ -# Модуль 01: Початок роботи з LangChain4j +# Module 01: Початок роботи з LangChain4j ## Зміст -- [Відеоогляд](../../../01-introduction) -- [Чого ви навчитесь](../../../01-introduction) -- [Вимоги](../../../01-introduction) -- [Розуміння основної проблеми](../../../01-introduction) -- [Розуміння токенів](../../../01-introduction) -- [Як працює пам’ять](../../../01-introduction) -- [Як це використовує LangChain4j](../../../01-introduction) -- [Розгортання інфраструктури Azure OpenAI](../../../01-introduction) -- [Запуск додатку локально](../../../01-introduction) -- [Використання додатку](../../../01-introduction) - - [Безстанковий чат (ліва панель)](../../../01-introduction) - - [Станковий чат (права панель)](../../../01-introduction) -- [Наступні кроки](../../../01-introduction) +- [Відеоогляд](#відеоогляд) +- [Чому ви навчитеся](#чому-ви-навчитеся) +- [Вимоги](#вимоги) +- [Розуміння основної проблеми](#розуміння-основної-проблеми) +- [Розуміння токенів](#розуміння-токенів) +- [Як працює пам’ять](#як-працює-пам’ять) +- [Як це використовує LangChain4j](#як-це-використовує-langchain4j) +- [Розгортання інфраструктури Azure OpenAI](#розгортання-інфраструктури-azure-openai) +- [Запуск програми локально](#запуск-програми-локально) +- [Використання програми](#використання-програми) + - [Безстанова бесіда (ліва панель)](#безстанова-бесіда-ліва-панель) + - [Станова бесіда (права панель)](#станова-бесіда-права-панель) +- [Наступні кроки](#наступні-кроки) ## Відеоогляд -Перегляньте цей живий сеанс, який пояснює, як розпочати роботу з цим модулем: +Перегляньте це живе заняття, яке пояснює, як почати роботу з цим модулем: -Getting Started with LangChain4j - Live Session +Початок роботи з LangChain4j - Живе заняття -## Чого ви навчитесь +## Чому ви навчитеся -У швидкому старті ви використовували моделі GitHub для відправлення запитів, виклику інструментів, побудови RAG конвеєра та тестування обмежень. Ці демонстрації показали, що можливо — тепер ми перейдемо до Azure OpenAI і GPT-5.2 і почнемо створювати додатки виробничого рівня. Цей модуль зосереджений на розмовному ШІ, який пам’ятає контекст і зберігає стан — концепції, які ці демонстрації швидкого старту використовували за лаштунками, але не пояснювали. +Це ваша відправна точка з LangChain4j та Azure OpenAI. Ми починаємо з основ і починаємо створювати застосунки виробничого стилю. Цей модуль зосереджений на розмовному штучному інтелекті, який пам’ятає контекст і підтримує стан — базові концепції, на яких будуються всі наступні модулі. -Ми будемо використовувати GPT-5.2 від Azure OpenAI протягом цього посібника, оскільки його розвинені можливості логічного мислення роблять поведінку різних патернів більш очевидною. Коли ви додасте пам’ять, ви чітко побачите різницю. Це полегшує розуміння того, що кожен компонент додає до вашого додатку. +Ми використаємо GPT-5.2 від Azure OpenAI протягом усього керівництва, оскільки його розвинені можливості міркування роблять поведінку різних патернів більш очевидною. Коли ви додаєте пам’ять, різницю буде видно чітко. Це полегшує розуміння того, що кожен компонент додає до вашого застосунку. -Ви створите один додаток, який демонструє обидва патерни: +Ви створите один застосунок, який демонструє обидва патерни: -**Безстанковий чат** — кожен запит є незалежним. Модель не пам’ятає попередні повідомлення. Це той патерн, який ви використовували у швидкому старті. +**Безстанова бесіда** — кожен запит незалежний. Модель не пам’ятає попередні повідомлення. Це найпростіша відправна точка. -**Станковий чат** — кожен запит включає історію розмови. Модель зберігає контекст протягом кількох кроків. Саме це потрібно для виробничих додатків. +**Станова бесіда** — кожен запит включає історію бесіди. Модель підтримує контекст через кілька ходів. Це те, що вимагають виробничі застосунки. ## Вимоги @@ -41,45 +41,45 @@ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Примітка:** Java, Maven, Azure CLI та Azure Developer CLI (azd) вже встановлені у наданому devcontainer. +> **Примітка:** Java, Maven, Azure CLI та Azure Developer CLI (azd) попередньо встановлені у наданому devcontainer. -> **Примітка:** Цей модуль використовує GPT-5.2 на Azure OpenAI. Розгортання налаштоване автоматично через `azd up` — не змінюйте ім’я моделі у коді. +> **Примітка:** Цей модуль використовує GPT-5.2 на Azure OpenAI. Розгортання конфігурується автоматично через `azd up` — не змінюйте назву моделі в коді. ## Розуміння основної проблеми -Мовні моделі є безстанковими. Кожен виклик API незалежний. Якщо ви надішлете "Мене звати Джон", а потім запитаєте "Як мене звати?", модель не зрозуміє, що ви щойно представилися. Вона сприймає кожен запит так, ніби це ваша перша розмова. +Мовні моделі безстанові. Кожен виклик API незалежний. Якщо ви скажете "Мене звати Джон" і потім спитаєте "Як мене звати?", модель навіть не здогадується, що ви тільки-но представилися. Вона обробляє кожен запит так, ніби це ваша перша розмова. -Це підходить для простих запитань-відповідей, але марно для реальних застосунків. Чатботи служби підтримки повинні пам’ятати, що ви їм розповіли. Персональні помічники потребують контексту. Будь-яка багатокрокова розмова вимагає пам’яті. +Це підходить для простих запитань-відповідей але марне для реальних застосунків. Чат-боти служби підтримки повинні пам’ятати, що ви їм сказали. Особисті помічники потребують контексту. Будь-яка багатокрокова бесіда потребує пам’яті. -Наступна схема порівнює два підходи — зліва виклик без пам’яті, що забуває ваше ім’я; праворуч — станковий виклик з ChatMemory, який його пам’ятає. +Наступна діаграма порівнює два підходи — зліва безстановий виклик, що забуває ваше ім’я; справа становий виклик з ChatMemory, що його пам’ятає. -Stateless vs Stateful Conversations +Безстанові проти станових бесід -*Різниця між безстанковими (незалежними викликами) і станковими (з урахуванням контексту) розмовами* +*Різниця між безстановими (незалежними викликами) та становими (усвідомленими контекстом) бесідами* ## Розуміння токенів -Перш ніж заглиблюватись у розмови, важливо зрозуміти токени — базові одиниці тексту, які обробляють мовні моделі: +Перед тим як заглибитися в бесіди, важливо розуміти токени — базові одиниці тексту, які обробляють мовні моделі: -Token Explanation +Пояснення токенів -*Приклад, як текст ділиться на токени – "I love AI!" стає 4 окремими одиницями обробки* +*Приклад розбиття тексту на токени — "I love AI!" стає 4 окремими обробними одиницями* -Токени — це те, як моделі ШІ вимірюють і обробляють текст. Слово, розділові знаки і навіть пропуски можуть бути токенами. У вашої моделі є обмеження щодо кількості токенів, які вона може обробити одночасно (400 000 для GPT-5.2, з максимумом 272 000 вхідних та 128 000 вихідних токенів). Розуміння токенів допомагає вам контролювати довжину розмови та витрати. +Токени — це те, як моделі ШІ вимірюють і обробляють текст. Слова, пунктуація і навіть пробіли можуть бути токенами. Ваша модель має ліміт на кількість токенів, які вона може обробити за раз (400 000 для GPT-5.2, із максимум 272 000 для вхідних і 128 000 для вихідних токенів). Розуміння токенів допомагає керувати довжиною бесіди та витратами. ## Як працює пам’ять -Пам’ять чату вирішує проблему безстанковості, зберігаючи історію розмови. Перед відправкою запиту до моделі, фреймворк додає відповідні попередні повідомлення. Коли ви питаєте "Як мене звати?", система фактично надсилає всю історію розмови, що дозволяє моделі бачити, що раніше ви сказали "Мене звати Джон." +Пам’ять чату вирішує проблему безстановості, зберігаючи історію розмови. Перед тим як надіслати ваш запит до моделі, фреймворк додає попередні релевантні повідомлення. Коли ви питаєте "Як мене звати?", система фактично надсилає всю історію бесіди, дозволяючи моделі побачити, що ви раніше сказали "Мене звати Джон." -LangChain4j надає реалізації пам’яті, які роблять це автоматично. Ви обираєте, скільки повідомлень зберігати, а фреймворк керує контекстним вікном. Схема нижче показує, як MessageWindowChatMemory зберігає ковзне вікно останніх повідомлень. +LangChain4j надає реалізації пам’яті, які виконують це автоматично. Ви обираєте, скільки повідомлень зберігати, а фреймворк керує вікном контексту. На діаграмі нижче показано, як MessageWindowChatMemory підтримує ковзне вікно останніх повідомлень. -Memory Window Concept +Концепція вікна пам’яті -*MessageWindowChatMemory підтримує ковзне вікно останніх повідомлень, автоматично відкидаючи старі* +*MessageWindowChatMemory підтримує ковзне вікно останніх повідомлень, автоматично видаляючи старі* ## Як це використовує LangChain4j -Цей модуль розширює швидкий старт, інтегруючи Spring Boot і додаючи пам’ять розмови. Ось як частини поєднуються: +Цей модуль інтегрує Spring Boot і додає пам’ять для розмов. Ось як все поєднується: **Залежності** — додайте дві бібліотеки LangChain4j: @@ -94,7 +94,7 @@ LangChain4j надає реалізації пам’яті, які роблят ``` -**Чат-модель** — налаштуйте Azure OpenAI як Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Модель чату** — налаштуйте Azure OpenAI як Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Будівник зчитує облікові дані з змінних оточення, встановлених командою `azd up`. Встановлення `baseUrl` на ваш Azure endpoint дозволяє OpenAI клієнту працювати з Azure OpenAI. +Будівник зчитує облікові дані з змінних оточення, встановлених за допомогою `azd up`. Встановлення `baseUrl` на ваш кінцевий пункт Azure дозволяє клієнту OpenAI працювати з Azure OpenAI. -**Пам’ять розмови** — відстежуйте історію чату за допомогою MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**Пам’ять розмов** — відстежуйте історію чату за допомогою MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Створіть пам’ять з `withMaxMessages(10)` для збереження останніх 10 повідомлень. Додавайте повідомлення користувача та ШІ з обгортувачами типу: `UserMessage.from(text)` і `AiMessage.from(text)`. Отримуйте історію за допомогою `memory.messages()` і надсилайте її моделі. Сервіс зберігає окремі інстанси пам’яті для кожного ID розмови, дозволяючи одночасний чат кількох користувачів. +Створіть пам’ять з `withMaxMessages(10)`, щоб зберігати останні 10 повідомлень. Додавайте повідомлення користувача і ШІ за допомогою типізованих оболонок: `UserMessage.from(text)` та `AiMessage.from(text)`. Отримуйте історію через `memory.messages()` і надсилайте її моделі. Сервіс зберігає окремі екземпляри пам’яті для кожного ID розмови, що дозволяє кільком користувачам одночасно спілкуватися. > **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) і запитайте: -> - "Як MessageWindowChatMemory вирішує, які повідомлення видаляти, коли вікно заповнене?" -> - "Чи можна реалізувати власне збереження пам’яті в базі даних замість пам’яті в оперативній?" -> - "Як додати резюме для стиснення старої історії розмови?" +> - "Як MessageWindowChatMemory вирішує, які повідомлення скидати, коли вікно заповнене?" +> - "Чи можна реалізувати власне зберігання пам’яті з використанням бази даних замість пам’яті в процесі?" +> - "Як додати підсумовування для стиснення старої історії розмови?" -Ендпоінт безстанкового чату повністю пропускає пам’ять — просто `chatModel.chat(prompt)` як у швидкому старті. Станковий ендпоінт додає повідомлення у пам’ять, отримує історію та включає цей контекст з кожним запитом. Та сама конфігурація моделі, різні патерни. +Безстановий чат не використовує пам’ять — просто `chatModel.chat(prompt)`, як у швидкому старті. Станова точка додає повідомлення до пам’яті, отримує історію і включає цей контекст у кожен запит. Та сама конфігурація моделі, різні патерни. ## Розгортання інфраструктури Azure OpenAI @@ -147,88 +147,88 @@ cd 01-introduction azd up # Виберіть підписку та розташування (рекомендується eastus2) ``` -> **Примітка:** Якщо ви зіткнулися з помилкою таймауту (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), просто запустіть `azd up` знову. Ресурси Azure можуть ще розгортатися у фоновому режимі, і повторна спроба дозволить завершити розгортання, коли ресурси досягнуть кінцевого стану. +> **Примітка:** Якщо ви отримали помилку таймауту (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), просто запустіть `azd up` ще раз. Ресурси Azure можуть досі розгортатися у фоновому режимі, і повторна спроба дозволить завершити розгортання, коли ресурси досягнуть кінцевого стану. Це зробить: 1. Розгортання ресурсу Azure OpenAI з моделями GPT-5.2 та text-embedding-3-small -2. Автоматичне створення файлу `.env` в корені проекту з обліковими даними +2. Автоматичне створення файлу `.env` у корені проекту з обліковими даними 3. Налаштування всіх необхідних змінних оточення -**Проблеми з розгортанням?** Перегляньте [Infrastructure README](infra/README.md) для детального усунення неполадок, включаючи конфлікти імен піддоменів, кроки ручного розгортання в Azure Portal та рекомендації щодо налаштування моделей. +**Виникають проблеми з розгортанням?** Перегляньте [README інфраструктури](infra/README.md) для детального усунення несправностей, зокрема конфліктів імен субдоменів, кроків ручного розгортання в Azure Portal і порад щодо конфігурації моделей. -**Перевірка успішного розгортання:** +**Перевірте успішність розгортання:** **Bash:** ```bash -cat ../.env # Має відображати AZURE_OPENAI_ENDPOINT, API_KEY тощо. +cat ../.env # Повинно показувати AZURE_OPENAI_ENDPOINT, API_KEY тощо. ``` **PowerShell:** ```powershell -Get-Content ..\.env # Має показувати AZURE_OPENAI_ENDPOINT, API_KEY тощо. +Get-Content ..\.env # Повинні показуватися AZURE_OPENAI_ENDPOINT, API_KEY тощо. ``` -> **Примітка:** Команда `azd up` автоматично генерує файл `.env`. Якщо ви хочете оновити його пізніше, можете відредагувати `.env` вручну або згенерувати знову, запустивши: +> **Примітка:** Команда `azd up` автоматично створює файл `.env`. Якщо вам потрібно оновити його пізніше, ви можете або вручну відредагувати файл `.env`, або створити його заново, запустивши: > > **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` -> + > **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 > ``` -## Запуск додатку локально +## Запуск програми локально **Перевірте розгортання:** -Переконайтеся, що файл `.env` існує у кореневій папці з обліковими даними Azure. Запустіть це з директорії модуля (`01-introduction/`): +Переконайтеся, що файл `.env` існує у кореневій директорії з обліковими даними Azure. Запустіть це з каталогу модуля (`01-introduction/`): **Bash:** ```bash -cat ../.env # Повинно показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Повинен показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Повинно показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Має відображати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Запустіть додатки:** +**Запустіть застосунки:** -**Варіант 1: Через Spring Boot Dashboard (рекомендовано для користувачів VS Code)** +**Варіант 1: Використання Spring Boot Dashboard (рекомендовано для користувачів VS Code)** -Dev container включає розширення Spring Boot Dashboard, що дає візуальний інтерфейс для керування всіма Spring Boot додатками. Знаходиться у Activity Bar зліва у VS Code (іконка Spring Boot). +Devcontainer включає розширення Spring Boot Dashboard, яке надає візуальний інтерфейс для керування всіма застосунками Spring Boot. Ви можете знайти його на панелі активності зліва у VS Code (шукайте іконку Spring Boot). -Через Spring Boot Dashboard ви можете: -- Побачити всі доступні Spring Boot додатки у робочому просторі -- Запускати/зупиняти додатки одним кліком -- Переглядати журнали додатку в режимі реального часу -- Моніторити стан додатку +З Spring Boot Dashboard ви можете: +- Бачити всі доступні застосунки Spring Boot в робочій області +- Запускати/зупиняти застосунки одним кліком +- Переглядати логи застосунку в режимі реального часу +- Моніторити стан застосунку -Просто натисніть кнопку відтворення поруч з "introduction", щоб запустити цей модуль, або запустіть всі модулі відразу. +Просто натисніть кнопку запуску біля "introduction", щоб запустити цей модуль, або запустіть усі модулі одразу. -Spring Boot Dashboard +Панель Spring Boot -*Spring Boot Dashboard у VS Code — запуск, зупинка і моніторинг усіх модулів з одного місця* +*Панель Spring Boot у VS Code — запуск, зупинка та моніторинг усіх модулів із одного місця* -**Варіант 2: Через shell-скрипти** +**Варіант 2: Використання shell-скриптів** -Запустіть всі веб-додатки (модулі 01-04): +Запустіть усі веб-застосунки (модулі 01-04): **Bash:** ```bash -cd .. # З кореневої директорії +cd .. # З кореневого каталогу ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # З кореневого каталогу +cd .. # З кореневої директорії .\start-all.ps1 ``` @@ -246,23 +246,23 @@ cd 01-introduction .\start.ps1 ``` -Обидва скрипти автоматично завантажують змінні оточення з кореневого файлу `.env` і збирають JAR, якщо його ще немає. +Обидва скрипти автоматично завантажують змінні оточення з файлу `.env` у корені і зіб’ють JAR-файли, якщо їх немає. -> **Примітка:** Якщо ви бажаєте збирати всі модулі вручну перед запуском: +> **Примітка:** Якщо ви віддаєте перевагу збирати всі модулі вручну перед запуском: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -Відкрийте http://localhost:8080 у браузері. +Відкрийте http://localhost:8080 у вашому браузері. **Щоб зупинити:** @@ -277,46 +277,46 @@ cd .. && ./stop-all.sh # Всі модулі ```powershell .\stop.ps1 # Тільки цей модуль # Або -cd ..; .\stop-all.ps1 # Усі модулі +cd ..; .\stop-all.ps1 # Всі модулі ``` -## Використання додатку +## Використання програми -Додаток надає веб-інтерфейс з двома реалізаціями чату поруч. +Програма надає веб-інтерфейс із двома реалізаціями чату поруч. -Application Home Screen +Головний екран програми -*Панель із вибором Простого чату (безстанкового) та Розмовного чату (станкового)* +*Панель керування з варіантами Проста бесіда (безстанова) і Розмовна бесіда (станова)* -### Безстанковий чат (ліва панель) +### Безстанова бесіда (ліва панель) -Спробуйте цей спочатку. Запитайте "Мене звати Джон", а потім одразу "Як мене звати?" Модель не пам’ятатиме, бо кожне повідомлення незалежне. Це демонструє основну проблему простої інтеграції мовної моделі — відсутність контексту розмови. +Спробуйте спочатку це. Скажіть "Мене звати Джон", а потім відразу спитайте "Як мене звати?" Модель не запам’ятає, бо кожне повідомлення незалежне. Це демонструє основну проблему базової інтеграції мовної моделі — відсутність контексту розмови. -Stateless Chat Demo +Демонстрація безстанового чату *ШІ не пам’ятає ваше ім’я з попереднього повідомлення* -### Станковий чат (права панель) +### Станова бесіда (права панель) -Тепер спробуйте той самий послідовність тут. Запитайте "Мене звати Джон" і потім "Як мене звати?" Цього разу модель пам’ятає. Різниця в MessageWindowChatMemory — він зберігає історію розмов і додає її до кожного запиту. Саме так працює розмовний ШІ для виробничих застосунків. +Тепер спробуйте ту ж послідовність тут. Скажіть "Мене звати Джон", потім "Як мене звати?" Тепер модель пам’ятає. Різниця в MessageWindowChatMemory — він підтримує історію розмови і включає її в кожен запит. Так працює виробничий розмовний ШІ. -Stateful Chat Demo +Демонстрація станової бесіди -*ШІ пам’ятає ваше ім’я з початку розмови* +*ШІ пам’ятає ваше ім’я з попередньої частини розмови* -Обидві панелі використовують одну й ту саму модель GPT-5.2. Єдина різниця — пам’ять. Це чітко показує, що додає пам’ять у ваш додаток і чому це важливо для реальних випадків використання. +Обидві панелі використовують ту ж модель GPT-5.2. Єдина різниця — пам’ять. Це чітко показує, що пам’ять додає вашому застосунку і чому вона необхідна для реальних випадків використання. ## Наступні кроки -**Наступний модуль:** [02-prompt-engineering - Інженерія підказок з GPT-5.2](../02-prompt-engineering/README.md) +**Наступний модуль:** [02-prompt-engineering - Проєктування підказок з GPT-5.2](../02-prompt-engineering/README.md) --- -**Навігація:** [← Попередній: Модуль 00 - Швидкий старт](../00-quick-start/README.md) | [Назад до головної](../README.md) | [Далі: Модуль 02 - Інженерія підказок →](../02-prompt-engineering/README.md) +**Навігація:** [← Назад до головної](../README.md) | [Далі: Модуль 02 - Проєктування підказок →](../02-prompt-engineering/README.md) --- -**Відмова від відповідальності**: -Цей документ було перекладено за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоч ми і прагнемо до точності, просимо враховувати, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується звертатися до професійного перекладу, виконаного людиною. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. +**Відмова від відповідальності**: +Цей документ було перекладено за допомогою сервісу штучного інтелекту для перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. \ No newline at end of file diff --git a/translations/uk/02-prompt-engineering/README.md b/translations/uk/02-prompt-engineering/README.md index bff919e9f..da00b5a59 100644 --- a/translations/uk/02-prompt-engineering/README.md +++ b/translations/uk/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Модуль 02: Проєктування Запитів з GPT-5.2 +# Модуль 02: Інженерія запитів із GPT-5.2 ## Зміст -- [Відео-огляд](../../../02-prompt-engineering) -- [Чому Ви Навчитесь](../../../02-prompt-engineering) -- [Передумови](../../../02-prompt-engineering) -- [Розуміння Проєктування Запитів](../../../02-prompt-engineering) -- [Основи Проєктування Запитів](../../../02-prompt-engineering) - - [Zero-Shot Запити](../../../02-prompt-engineering) - - [Few-Shot Запити](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Рольове Проєктування Запитів](../../../02-prompt-engineering) - - [Шаблони Запитів](../../../02-prompt-engineering) -- [Розвинені Шаблони](../../../02-prompt-engineering) -- [Запуск Додатку](../../../02-prompt-engineering) -- [Скріншоти Додатку](../../../02-prompt-engineering) -- [Дослідження Шаблонів](../../../02-prompt-engineering) - - [Низька vs Висока Енергійність](../../../02-prompt-engineering) - - [Виконання Завдань (Вступи до Інструментів)](../../../02-prompt-engineering) - - [Самоаналіз Коду](../../../02-prompt-engineering) - - [Структурований Аналіз](../../../02-prompt-engineering) - - [Багатоходова Розмова](../../../02-prompt-engineering) - - [Крок за Кроком Міркування](../../../02-prompt-engineering) - - [Обмежений Вивід](../../../02-prompt-engineering) -- [Що Ви Насправді Вивчаєте](../../../02-prompt-engineering) -- [Наступні Кроки](../../../02-prompt-engineering) +- [Відеоогляд](#відеоогляд) +- [Чому ви навчитесь](#чому-ви-навчитесь) +- [Вимоги до знань](#вимоги-до-знань) +- [Розуміння інженерії запитів](#розуміння-інженерії-запитів) +- [Основи інженерії запитів](#основи-інженерії-запитів) + - [Zero-Shot Prompting (без прикладів)](#zero-shot-prompting) + - [Few-Shot Prompting (з прикладами)](#few-shot-prompting) + - [Chain of Thought (ланцюг мислення)](#chain-of-thought) + - [Role-Based Prompting (контекст ролі)](#role-based-prompting) + - [Шаблони запитів](#prompt-templates) +- [Розширені патерни](#розширені-патерни) +- [Запустити застосунок](#запуск-застосунку) +- [Скріншоти застосунку](#знімки-екрана-застосунку) +- [Огляд патернів](#дослідження-патернів) + - [Низька vs висока готовність](#низький-проти-високого-рівня-зацікавленості) + - [Виконання завдань (преамбули інструментів)](#виконання-завдань-преамбули-інструментів) + - [Саморефлексивний код](#код-із-саморефлексією) + - [Структурований аналіз](#структурований-аналіз) + - [Багатокроковий чат](#чат-з-багатьма-повідомленнями) + - [Покрокове міркування](#крок-за-кроком-міркування) + - [Обмежений вивід](#обмежений-вивід) +- [То що ж ви справді вивчаєте](#чому-ви-справді-навчаєтеся) +- [Наступні кроки](#наступні-кроки) -## Відео-огляд +## Відеоогляд -Дивіться цю живу сесію, у якій пояснюється, як розпочати роботу з цим модулем: +Дивіться цю пряму сесію, яка пояснює, як почати роботу з цим модулем: -Проєктування Запитів з LangChain4j - Жива Сесія +Prompt Engineering with LangChain4j - Live Session -## Чому Ви Навчитесь +## Чому ви навчитесь -Наступна схема надає огляд ключових тем і навичок, які ви розвинете в цьому модулі — від методів уточнення запитів до покрокового робочого процесу, який ви будете використовувати. +Наступна діаграма дає огляд ключових тем і навичок, які ви розвинете у цьому модулі — від методів удосконалення запитів до покрокового робочого процесу, який ви будете застосовувати. -Чому Ви Навчитесь +What You'll Learn -У попередніх модулях ви ознайомились з базовою взаємодією LangChain4j та моделями GitHub і побачили, як пам’ять забезпечує розмовний ШІ з Azure OpenAI. Тепер ми зосередимось на тому, як ви формуєте запитання — самі запити — використовуючи GPT-5.2 від Azure OpenAI. Те, як ви структуруєте свої запити, суттєво впливає на якість отриманих відповідей. Ми почнемо з огляду фундаментальних технік створення запитів, а потім перейдемо до восьми розвинених шаблонів, які повністю використовують можливості GPT-5.2. +У попередньому модулі ви побачили, як пам'ять дозволяє створювати розмовний ШІ з Azure OpenAI. Тепер ми зосередимось на тому, як ставити запитання — на самих запитах — використовуючи Azure OpenAI GPT-5.2. Те, як ви структуруєте свої запити, кардинально впливає на якість отриманих відповідей. Почнемо з огляду базових технік інженерії запитів, а потім перейдемо до восьми розширених патернів, які максимально використовують можливості GPT-5.2. -Ми використовуємо GPT-5.2, тому що він вводить контроль міркувань — ви можете вказати моделі, скільки обдумування потрібно зробити перед відповіддю. Це робить різні стратегії запитів більш помітними і допомагає зрозуміти, коли слід застосовувати кожен підхід. Також ми скористаємося меншою кількістю обмежень швидкості Azure для GPT-5.2 порівняно з моделями GitHub. +Ми використовуємо GPT-5.2, бо він вводить контроль мислення — ви можете вказати моделі, скільки обдумування слід виконати перед відповіддю. Це робить різні стратегії формулювання запитів більш очевидними і допомагає зрозуміти, коли використовувати кожен підхід. -## Передумови +## Вимоги до знань -- Пройдено Модуль 01 (розгорнуті ресурси Azure OpenAI) -- Файл `.env` у кореневому каталозі з обліковими даними Azure (створений командою `azd up` у Модулі 01) +- Завершений Модуль 01 (розгорнуті ресурси Azure OpenAI) +- Файл `.env` в кореневій директорії з обліковими даними Azure (створений командою `azd up` у Модулі 01) -> **Примітка:** Якщо ви не пройшли Модуль 01, спочатку виконайте інструкції з розгортання там. +> **Примітка:** Якщо ви не завершили Модуль 01, спершу дотримуйтесь інструкцій по розгортанню з нього. -## Розуміння Проєктування Запитів +## Розуміння інженерії запитів -В основі проєктування запитів лежить різниця між нечіткими інструкціями та точними, як ілюструється нижче. +Інженерія запитів — це, по суті, різниця між нечіткими інструкціями та точними, як і показано в порівнянні нижче. -Що таке проєктування запитів? +What is Prompt Engineering? -Проєктування запитів полягає у створенні вхідного тексту, який послідовно дає потрібні вам результати. Це не тільки про ставлення питань — це про структурування запитів так, щоб модель точно розуміла, чого ви хочете і як це надати. +Інженерія запитів полягає у проектуванні вхідного тексту, який послідовно дає вам потрібні результати. Це не просто постановка питань — це структурування запитів так, щоб модель точно зрозуміла, чого ви хочете, і як це надати. -Уявіть, що даєте інструкції колезі. «Виправити баг» — це нечітко. «Виправити помилку null pointer в UserService.java на рядку 45, додавши перевірку на null» — конкретно. Мовні моделі працюють так само — важлива точність і структура. +Уявіть, що ви даєте інструкції колезі. «Виправити баг» — це нечітко. «Виправити виняток null pointer у файлі UserService.java рядок 45, додавши перевірку на null» — це конкретно. Мовні моделі працюють так само — точність і структура мають значення. -Схема нижче показує, як LangChain4j вписується в цю картину — з’єднуючи ваші шаблони запитів з моделлю через будівельні блоки SystemMessage і UserMessage. +Наступна діаграма показує, як LangChain4j вписується в цю картину — з’єднуючи ваші патерни запитів із моделлю через будівельні блоки SystemMessage і UserMessage. -Як LangChain4j Вписується +How LangChain4j Fits -LangChain4j надає інфраструктуру — з’єднання моделей, пам’ять і типи повідомлень — а шаблони запитів — це просто ретельно структурований текст, який ви надсилаєте через цю інфраструктуру. Ключові будівельні блоки — це `SystemMessage` (який задає поведінку і роль ШІ) та `UserMessage` (який несе ваше фактичне прохання). +LangChain4j забезпечує інфраструктуру — підключення моделі, пам’ять і типи повідомлень — тоді як патерни запитів — це просто ретельно структурований текст, який ви надсилаєте через цю інфраструктуру. Ключові будівельні блоки — це `SystemMessage` (що задає поведінку та роль ШІ) і `UserMessage` (що несе ваш власний запит). -## Основи Проєктування Запитів +## Основи інженерії запитів -П’ять основних технік, зображених нижче, становлять основу ефективного проєктування запитів. Кожна з них охоплює інший аспект того, як ви спілкуєтесь з мовними моделями. +П'ять основних технік, показаних нижче, формують фундамент ефективної інженерії запитів. Кожна розглядає різний аспект того, як ви спілкуєтесь із мовними моделями. -Огляд П'яти Шаблонів Проєктування Запитів +Five Prompt Engineering Patterns Overview -Перш ніж перейти до розвинених шаблонів у цьому модулі, давайте переглянемо п’ять базових технік створення запитів. Це будівельні блоки, які повинен знати кожен інженер запитів. Якщо ви вже пройшли [модуль швидкого старту](../00-quick-start/README.md#2-prompt-patterns), ви бачили їх у дії — ось концептуальна основа за ними. +Перед тим як зануритися в розширені патерни цього модуля, давайте переглянемо п’ять базових технік формулювання запитів. Це будівельні блоки, які повинен знати кожен інженер запитів. -### Zero-Shot Запити +### Zero-Shot Prompting -Найпростіший підхід: дайте моделі пряму інструкцію без прикладів. Модель повністю покладається на своє навчання, щоб зрозуміти і виконати завдання. Це добре підходить для простих запитів, де очікувана поведінка очевидна. +Найпростіший підхід: дайте моделі пряме інструктаж без прикладів. Модель повністю покладається на своє навчання, щоб зрозуміти і виконати завдання. Це добре працює для простих запитів, де очікувана поведінка очевидна. -Zero-Shot Запити +Zero-Shot Prompting -*Пряма інструкція без прикладів — модель виводить завдання лише з інструкції* +*Пряме інструктаж без прикладів — модель виводить завдання лише за інструкцією* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// Відповідь: "Позитивно" +// Відповідь: "Позитивна" ``` -**Коли використовувати:** Просту класифікацію, прямі питання, переклади або будь-яке завдання, яке модель може виконати без додаткових вказівок. +**Коли використовувати:** Просту класифікацію, прямі запитання, переклади або будь-які завдання, які модель може виконати без додаткових настанов. -### Few-Shot Запити +### Few-Shot Prompting -Надайте приклади, які демонструють шаблон, який ви хочете, щоб модель наслідувала. Модель вивчає очікуваний формат вхідних і вихідних даних з ваших прикладів і застосовує його до нових входів. Це суттєво підвищує послідовність для завдань, де бажаний формат або поведінка неочевидні. +Надайте приклади, які демонструють патерн, якого ви хочете, щоб модель дотримувалась. Модель вивчає вхід-вихідний формат із ваших прикладів і застосовує його до нових запитів. Це значно покращує консистентність для завдань, де бажаний формат або поведінка не очевидні. -Few-Shot Запити +Few-Shot Prompting -*Навчання на прикладах — модель виявляє шаблон і застосовує його до нових даних* +*Навчання на прикладах — модель визначає патерн і застосовує його до нових вхідних даних* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Коли використовувати:** Кастомні класифікації, послідовне форматування, галузеві завдання або коли результати zero-shot непослідовні. +**Коли використовувати:** Кастомні класифікації, послідовне форматування, домен-специфічні завдання або коли zero-shot результати непослідовні. ### Chain of Thought -Попросіть модель показати своє міркування крок за кроком. Замість миттєвої відповіді модель розбиває проблему і явно опрацьовує кожну частину. Це покращує точність у математичних задачах, логіці та багатокроковому міркуванні. +Попросіть модель показати свої міркування крок за кроком. Замість того, щоб одразу давати відповідь, модель розбиває проблему і послідовно опрацьовує кожну частину. Це покращує точність у математиці, логіці і багатокрокових завданнях. -Chain of Thought (Послідовність Міркувань) +Chain of Thought Prompting -*Міркування крок за кроком — розбиття складних проблем на явні логічні етапи* +*Покрокове міркування — розбиття складних проблем на явні логічні кроки* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // Модель показує: 15 - 8 = 7, потім 7 + 12 = 19 яблук ``` -**Коли використовувати:** Математичні задачі, логічні головоломки, відлагодження або будь-яке завдання, де демонстрація процесу міркувань покращує точність і довіру. +**Коли використовувати:** Математичні задачі, логічні головоломки, налагодження або будь-яке завдання, де показ міркувань покращує точність і довіру. -### Рольове Проєктування Запитів +### Role-Based Prompting -Задайте персоналію або роль для ШІ перед тим, як поставити питання. Це створює контекст, який формує тон, глибину і фокус відповіді. "Архітектор програмного забезпечення" дасть інші поради, ніж "молодший розробник" або "аудитор безпеки". +Встановіть персону або роль для ШІ перед тим, як ставити питання. Це задає контекст, який формує тон, глибину і фокус відповіді. «Архітектор ПЗ» дасть інші поради, ніж «молодший розробник» або «аудитор безпеки». -Рольове Проєктування Запитів +Role-Based Prompting -*Задання контексту і ролі — одне і те ж питання отримує різну відповідь залежно від призначеної ролі* +*Встановлення контексту і персони — одне і те ж питання отримує різну відповідь залежно від призначеної ролі* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Коли використовувати:** Код-рев’ю, навчання, галузевий аналіз або коли потрібні відповіді, адаптовані до певного рівня експертності чи перспективи. +**Коли використовувати:** Огляди коду, навчання, домен-специфічний аналіз або коли потрібні відповіді, адаптовані до конкретного рівня експертизи чи перспективи. -### Шаблони Запитів +### Prompt Templates -Створюйте повторно використовувані запити з змінними заповнювачами. Замість того, щоб писати новий запит кожного разу, визначте шаблон один раз і заповнюйте різними значеннями. Клас `PromptTemplate` LangChain4j спрощує це за допомогою синтаксису `{{variable}}`. +Створюйте повторно використовувані запити з змінними-заповнювачами. Замість того, щоб писати новий запит щоразу, визначте один шаблон і заповнюйте його різними значеннями. Клас `PromptTemplate` LangChain4j полегшує це з синтаксисом `{{variable}}`. -Шаблони Запитів +Prompt Templates -*Повторне використання запитів зі змінними — один шаблон, багато варіантів* +*Повторно використовувані запити зі змінними-заповнювачами — один шаблон, багато застосувань* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Коли використовувати:** Повторювані запити з різними вхідними даними, пакетна обробка, створення повторно використовуваних AI-робочих процесів або будь-який сценарій, де структура запиту залишається сталою, а дані змінюються. +**Коли використовувати:** Повторні запити з різними вхідними даними, пакетна обробка, створення повторно використовуваних AI робочих процесів або будь-який випадок, коли структура запиту одна, а дані змінюються. --- -Ці п’ять основ дають вам міцний набір інструментів для більшості завдань зі створення запитів. Решту цього модуля побудовано на них із додаванням **восьми розвинених шаблонів**, що використовують контроль міркувань, самооцінку та структурований вивід GPT-5.2. +Ці п’ять основ дають міцний інструментарій для більшості завдань формулювання запитів. Решта модуля розвиває їх за допомогою **восьми розширених патернів**, які використовують контроль мислення GPT-5.2, самооцінку та можливості структурованого виводу. -## Розвинені Шаблони +## Розширені патерни -Після ознайомлення з основами переходимо до восьми розвинених шаблонів, що роблять цей модуль унікальним. Не всі проблеми потребують однакового підходу. Деякі питання потребують швидких відповідей, інші — глибокого аналізу. Деяким потрібне видиме міркування, іншим — лише результат. Кожен наведений нижче шаблон оптимізований для різних сценаріїв — і контроль міркувань GPT-5.2 робить ці відмінності ще більш помітними. +Після освоєння основ, перейдемо до восьми розширених патернів, що роблять цей модуль унікальним. Не всі проблеми потребують однакового підходу. Деякі питання потрібно швидко відповісти, інші — глибоко обміркувати. Деякі вимагають видимого міркування, інші — лише результатів. Кожен патерн нижче оптимізовано для різних сценаріїв — і контроль мислення GPT-5.2 робить ці відмінності ще яскравішими. -Вісім Шаблонів Проєктування Запитів +Eight Prompting Patterns -*Огляд восьми шаблонів проєктування запитів та їх випадків використання* +*Огляд восьми патернів інженерії запитів та їх випадків використання* -GPT-5.2 додає ще один вимір до цих шаблонів: *контроль міркувань*. Слайдер нижче показує, як можна настроїти зусилля мислення моделі — від швидких, прямих відповідей до глибокого, ретельного аналізу. +GPT-5.2 додає новий вимір цим патернам: *контроль мислення*. Повзунок нижче показує, як ви можете налаштовувати зусилля мислення моделі — від швидких прямих відповідей до глибокого ретельного аналізу. -Контроль Міркувань з GPT-5.2 +Reasoning Control with GPT-5.2 -*Контроль міркувань GPT-5.2 дозволяє вказати, скільки думок модель має виконати — від швидких прямих відповідей до глибокого дослідження* +*Контроль мислення GPT-5.2 дозволяє вказати, скільки обдумування має виконати модель — від швидких прямих відповідей до глибокого дослідження* -**Низька Енергійність (Швидко і Сфокусовано)** — для простих питань, де ви хочете швидких, прямих відповідей. Модель виконує мінімальне міркування — максимум 2 кроки. Використовуйте це для обчислень, пошуку чи простих питань. +**Низька готовність (швидко і сфокусовано)** — для простих питань, де потрібні швидкі прямі відповіді. Модель виконує мінімальне міркування — максимум 2 кроки. Використовуйте для обчислень, пошуку або простих питань. ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **Досліджуйте з GitHub Copilot:** Відкрийте [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) та запитайте: -> - "У чому різниця між шаблонами з низькою та високою енергійністю?" -> - "Як XML-теги в запитах допомагають структурувати відповідь ШІ?" -> - "Коли слід використовувати шаблони самоаналізу, а коли — прямі інструкції?" +> 💡 **Вивчіть за допомогою GitHub Copilot:** Відкрийте [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) і запитайте: +> - "Чим відрізняються патерни з низькою і високою готовністю?" +> - "Як допомагають XML теги у запитах структурувати відповідь ШІ?" +> - "Коли варто використовувати патерни саморефлексії, а коли прямі інструкції?" -**Висока Енергійність (Глибоко і Ретельно)** — для комплексних проблем, де потрібен всеохопний аналіз. Модель досліджує детально і показує детальні міркування. Використовуйте це для системного дизайну, архітектурних рішень або складних досліджень. +**Висока готовність (глибоко і ретельно)** — для складних проблем, де потрібен всебічний аналіз. Модель ретельно досліджує і показує детальні міркування. Використовуйте для проектування систем, архітектурних рішень чи складних досліджень. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Виконання Завдань (Поступовий Проспів)** — для багатокрокових робочих процесів. Модель надає початковий план, описує кожен крок під час роботи, а потім дає підсумок. Використовуйте для міграцій, реалізацій або будь-яких багатокрокових процесів. +**Виконання завдань (покроковий прогрес)** — для багатокрокових робочих процесів. Модель надає план заздалегідь, озвучує кожен крок по ходу роботи, а потім робить резюме. Використовуйте для міграцій, імплементацій або будь-яких багатокрокових процесів. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Запит Chain-of-Thought явно просить модель показати процес міркування, покращуючи точність для складних завдань. Розбиття крок за кроком допомагає і людям, і ШІ краще розуміти логіку. +Патерн Chain-of-Thought (ланцюг мислення) явно просить модель показати процес міркувань, що покращує точність для складних завдань. Покрокове розбиття допомагає і людям, і ШІ зрозуміти логіку. -> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Запитайте про цей шаблон: -> - "Як я можу адаптувати шаблон виконання завдання для довготривалих операцій?" -> - "Які кращі практики для структурування вступів до інструментів у продуктивних додатках?" -> - "Як я можу фіксувати і показувати проміжний прогрес у UI?" +> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Запитайте про цей патерн: +> - "Як адаптувати патерн виконання завдань для тривалих операцій?" +> - "Які найкращі практики структурування преамбул інструментів у продуктивних застосунках?" +> - "Як захоплювати та відображати проміжні оновлення прогресу в UI?" -Нижче схема ілюструє цей робочий процес План → Виконання → Підсумок. +Наступна діаграма ілюструє робочий процес План → Виконання → Підсумок. -Шаблон Виконання Завдання +Task Execution Pattern *Робочий процес План → Виконання → Підсумок для багатокрокових завдань* -**Самоаналіз Коду** — для генерації коду виробничої якості. Модель генерує код згідно з виробничими стандартами з належною обробкою помилок. Використовуйте це під час створення нових функцій чи сервісів. +**Саморефлексивний код** — для генерації коду виробничої якості. Модель створює код відповідно до стандартів виробництва з належною обробкою помилок. Використовуйте це при розробці нових функцій або сервісів. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Нижче наведена схема цього ітеративного циклу вдосконалення — генеруйте, оцінюйте, ідентифікуйте слабкі місця і уточнюйте, доки код не відповідатиме стандартам виробництва. +Наступна діаграма показує цей ітеративний цикл покращення — генеруйте, оцінюйте, виявляйте слабкі місця і вдосконалюйте, доки код не відповідатиме стандартам виробництва. -Цикл Самоаналізу +Self-Reflection Cycle -*Ітеративний цикл вдосконалення — генерувати, оцінювати, виявляти проблеми, покращувати, повторювати* +*Цикл ітеративного покращення - генерування, оцінка, виявлення проблем, вдосконалення, повтор* -**Структурований Аналіз** — для послідовної оцінки. Модель переглядає код за фіксованою схемою (коректність, практики, продуктивність, безпека, підтримуваність). Використовуйте це для код-рев’ю або оцінки якості. +**Структурований аналіз** — для послідовної оцінки. Модель перевіряє код за фіксованою схемою (коректність, практики, продуктивність, безпека, підтримуваність). Використовуйте для оглядів коду або оцінки якості. ```java String prompt = """ @@ -355,17 +355,17 @@ String response = chatModel.chat(prompt); ``` > **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Запитайте про структурований аналіз: -> - "Як можна налаштувати рамки аналізу для різних типів код-рев’ю?" -> - "Який найкращий спосіб аналізувати і працювати зі структурованим виводом програмно?" -> - "Як забезпечити послідовні рівні серйозності в різних сесіях рев’ю?" +> - "Як налаштувати схему аналізу для різних типів оглядів коду?" +> - "Який найкращий спосіб розбирати і працювати зі структурованим виводом програмно?" +> - "Як забезпечити послідовність рівнів серйозності в різних сесіях огляду?" -Наступна схема показує, як ця структурована рамка організовує код-рев’ю у послідовні категорії з рівнями серйозності. +Наступна діаграма показує, як ця структурована схема організовує огляд коду в послідовні категорії з рівнями серйозності. -Шаблон Структурованого Аналізу +Structured Analysis Pattern -*Рамки для послідовних код-рев’ю з рівнями серйозності* +*Схема для послідовних оглядів коду з рівнями серйозності* -**Багатоходова Розмова** — для діалогів, що потребують контексту. Модель пам’ятає попередні повідомлення і використовує їх для наступних. Використовуйте для інтерактивної допомоги або складних Q&A. +**Багатокроковий чат** — для розмов, які потребують контексту. Модель запам’ятовує попередні повідомлення і розвиває їх. Використовуйте для інтерактивної допомоги або складних Q&A. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Нижче візуалізовано, як контекст розмови накопичується з кожним ходом і як це пов’язано з лімітом токенів моделі. +Наступна діаграма візуалізує, як контекст розмови накопичується з кожним кроком і як це співвідноситься з лімітом токенів моделі. -Пам’ять Контексту +Context Memory -*Як контекст розмови накопичується протягом багатьох ходів до досягнення ліміту токенів* -**Покрокове міркування** – Для завдань, що потребують видимої логіки. Модель показує чітке обґрунтування для кожного кроку. Використовуйте це для математичних задач, логічних головоломок або коли потрібно зрозуміти хід думок. +*Як контекст розмови накопичується з кількома ходами, доки не досягне ліміту токенів* + +**Покрокове міркування** — для задач, які потребують видимої логіки. Модель показує явні міркування для кожного кроку. Використовуйте для математичних задач, логічних головоломок або коли потрібно зрозуміти процес мислення. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Схема нижче ілюструє, як модель розбиває завдання на чіткі, нумеровані логічні кроки. - -Крок за кроком Патерн +Наступна діаграма ілюструє, як модель розбиває проблеми на явні, пронумеровані логічні кроки. -*Розбиття завдань на очевидні логічні кроки* +Step-by-Step Pattern +*Розбиття проблем на явні логічні кроки* -**Обмежений вивід** – Для відповідей із вимогами конкретного формату. Модель суворо дотримується правил формату і довжини. Використовуйте це для резюме або коли потрібна точна структура виводу. +**Обмежений Вивід** – для відповідей із конкретними вимогами до формату. Модель суворо дотримується правил формату й довжини. Використовуйте це для резюме або коли потрібна точна структура вихідних даних. ```java String prompt = """ @@ -420,43 +420,43 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Наступна схема показує, як обмеження керують моделлю, щоб вона створювала вивід, що суворо відповідає вашим вимогам формату і довжини. +Наступна діаграма показує, як обмеження керують моделлю для генерації виводу, що суворо відповідає вашим вимогам до формату та довжини. -Патерн Обмеженого Виводу +Constrained Output Pattern -*Виконання вимог до формату, довжини та структури* +*Забезпечення конкретних вимог до формату, довжини та структури* -## Запуск додатку +## Запуск Застосунку **Перевірка розгортання:** -Переконайтеся, що файл `.env` існує в кореневому каталозі з обліковими даними Azure (створеними під час Модуля 01). Запустіть це з каталогу модуля (`02-prompt-engineering/`): +Переконайтеся, що файл `.env` існує в кореневій теці з обліковими даними Azure (створений під час Модуля 01). Запустіть це з теки модуля (`02-prompt-engineering/`): **Bash:** ```bash -cat ../.env # Має показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Повинно відображати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # Повинно показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Має показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Запуск додатку:** +**Запуск застосунку:** -> **Примітка:** Якщо ви вже запустили всі додатки через `./start-all.sh` з кореневого каталогу (як описано в Модулі 01), цей модуль вже працює на порту 8083. Ви можете пропустити наведені нижче команди запуску і одразу перейти за посиланням http://localhost:8083. +> **Примітка:** Якщо ви вже запускали всі застосунки за допомогою `./start-all.sh` з кореневої теки (як описано в Модулі 01), цей модуль вже працює на порту 8083. Ви можете пропустити команди запуску нижче і перейти безпосередньо до http://localhost:8083. **Варіант 1: Використання Spring Boot Dashboard (Рекомендовано для користувачів VS Code)** -Dev контейнер включає розширення Spring Boot Dashboard, яке надає візуальний інтерфейс для керування всіма Spring Boot додатками. Ви знайдете його на Панелі активності зліва у VS Code (шукайте іконку Spring Boot). +Розробницький контейнер містить розширення Spring Boot Dashboard, яке надає візуальний інтерфейс для керування усіма застосунками Spring Boot. Ви знайдете його в панелі дій ліворуч у VS Code (шукайте значок Spring Boot). З Spring Boot Dashboard ви можете: -- Переглядати всі доступні Spring Boot додатки у робочому просторі -- Запускати/зупиняти додатки одним кліком -- Переглядати логи додатків у реальному часі -- Контролювати стан додатків +- Переглядати всі доступні застосунки Spring Boot у робочій області +- Запускати/зупиняти застосунки одним кліком +- Переглядати логи застосунку в реальному часі +- Моніторити стан застосунку -Просто натисніть кнопку запуску поруч із "prompt-engineering", щоб запустити цей модуль, або запустіть усі модулі одночасно. +Просто натисніть кнопку запуску поруч із "prompt-engineering", щоб запустити цей модуль, або запустіть усі модулі одразу. Spring Boot Dashboard @@ -464,11 +464,11 @@ Dev контейнер включає розширення Spring Boot Dashboard **Варіант 2: Використання shell-скриптів** -Запустіть усі вебдодатки (модулі 01-04): +Запустіть усі веб-застосунки (модулі 01-04): **Bash:** ```bash -cd .. # З кореневої директорії +cd .. # З кореневого каталогу ./start-all.sh ``` @@ -478,7 +478,7 @@ cd .. # З кореневого каталогу .\start-all.ps1 ``` -Або запустіть лише цей модуль: +Або запустіть тільки цей модуль: **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -Обидва скрипти автоматично завантажують змінні середовища з кореневого файлу `.env` і будують JAR-файли, якщо вони не існують. +Обидва скрипти автоматично завантажують змінні середовища із кореневого файлу `.env` і скомпілюють JAR-файли, якщо вони не існують. -> **Примітка:** Якщо ви хочете зібрати всі модулі вручну перед запуском: +> **Примітка:** Якщо ви хочете заздалегідь зібрати всі модулі вручну перед запуском: > > **Bash:** > ```bash @@ -514,95 +514,95 @@ cd 02-prompt-engineering **Bash:** ```bash -./stop.sh # Тільки цей модуль +./stop.sh # Лише цей модуль # Або cd .. && ./stop-all.sh # Всі модулі ``` **PowerShell:** ```powershell -.\stop.ps1 # Лише цей модуль +.\stop.ps1 # Тільки цей модуль # Або cd ..; .\stop-all.ps1 # Всі модулі ``` -## Знімки екрану додатку +## Знімки Екрана Застосунку -Ось головний інтерфейс модуля prompt engineering, де можна експериментувати з усіма восьмома патернами поруч. +Ось основний інтерфейс модуля prompt engineering, де ви можете експериментувати з усіма вісьмома патернами поруч. -Головна панель +Dashboard Home -*Головна панель із усіма 8 патернами prompt engineering з їхніми характеристиками та випадками використання* +*Головна панель, що показує всі 8 патернів prompt engineering з їхніми характеристиками та випадками використання* -## Огляд патернів +## Дослідження Патернів -Вебінтерфейс дозволяє експериментувати з різними стратегіями надання підказок. Кожен патерн розв’язує різні проблеми — спробуйте, щоб побачити, коли кожен підхід найкраще працює. +Веб-інтерфейс дозволяє вам експериментувати з різними стратегіями створення підказок. Кожен патерн вирішує різні проблеми – спробуйте їх, щоб побачити, коли який підхід спрацьовує найкраще. -> **Примітка: Потоковий режим vs Безпотоковий** — На кожній сторінці патерну є дві кнопки: **🔴 Потокова відповідь (жива)** і опція **Без потоків**. Потоковий режим використовує Server-Sent Events (SSE) для відображення токенів у реальному часі, поки модель їх генерує, тож ви бачите прогрес миттєво. Безпотоковий режим чекає на повну відповідь, після чого показує її. Для запитів, що викликають глибоке міркування (наприклад, High Eagerness, Self-Reflecting Code), безпотоковий виклик може займати дуже багато часу — іноді хвилини — без видимого зворотного зв’язку. **Використовуйте потоковий режим під час експериментів зі складними підказками**, щоб бачити роботу моделі і уникнути враження, що запит завис. +> **Примітка: Потокова і непотокова передача** — Кожна сторінка патерну має дві кнопки: **🔴 Потокова відповідь (жива)** і варіант **Без потоків**. Потокова передача використовує Server-Sent Events (SSE) для відображення токенів у реальному часі під час генерації моделі, тож ви бачите прогрес миттєво. Опція без потоків чекає повної відповіді перед відображенням. Для підказок, що викликають глибоке міркування (наприклад, High Eagerness, Self-Reflecting Code), виклик без потоків може тривати дуже довго — іноді хвилини — без видимого зворотного зв’язку. **Використовуйте стрімінг при експериментах із складними підказками**, щоб бачити роботу моделі та уникнути враження, що запит завис. > -> **Примітка: Вимога браузера** — Потокова функція використовує Fetch Streams API (`response.body.getReader()`), який потребує повноцінного браузера (Chrome, Edge, Firefox, Safari). Вона **не працює** у вбудованому в VS Code Simple Browser, оскільки його webview не підтримує API ReadableStream. Якщо ви користуєтеся Simple Browser, кнопки без потоків працюватимуть як звичайно — лише потокові кнопки не працюватимуть. Відкрийте `http://localhost:8083` в зовнішньому браузері для повного досвіду. +> **Примітка: Вимоги до браузера** — функція потоків використовує Fetch Streams API (`response.body.getReader()`), який потребує повноцінного браузера (Chrome, Edge, Firefox, Safari). Не працює в вбудованому Simple Browser у VS Code, оскільки його веб-перегляд не підтримує ReadableStream API. Якщо ви користуєтеся Simple Browser, кнопки без потоків працюватимуть нормально — тільки кнопки для потоків будуть недоступні. Відкрийте `http://localhost:8083` у зовнішньому браузері для повного досвіду. -### Низька vs Висока старанність +### Низький проти Високого Рівня Зацікавленості -Задайте просте питання, як-от "Що таке 15% від 200?" із Низькою старанністю. Ви отримаєте миттєву, прямолінійну відповідь. Тепер задайте щось складне, наприклад "Розроби стратегію кешування для високонавантаженого API" із Високою старанністю. Натисніть **🔴 Потокова відповідь (жива)** і спостерігайте за детальним міркуванням моделі крок за кроком. Та сама модель, та сама структура питання — але підказка вказує, скільки думати. +Задайте просте питання, наприклад "Що таке 15% від 200?" із низьким рівнем зацікавленості. Ви отримаєте миттєву, пряму відповідь. Тепер запитайте щось складніше, наприклад "Спроєктуй стратегію кешування для високонавантаженого API" з високим рівнем зацікавленості. Натисніть **🔴 Потокова відповідь (жива)** і дивіться, як покрокове міркування моделі з’являється токен за токеном. Та сама модель, та сама структура питання – але підказка каже, скільки думок вкладати. -### Виконання завдань (Вступні інструкції для інструментів) +### Виконання Завдань (Преамбули Інструментів) -Багатокрокові робочі процеси виграють від планування наперед та озвучування прогресу. Модель окреслює, що буде робити, розповідає про кожен крок, потім узагальнює результати. +Багатокрокові робочі процеси виграють від попереднього планування та озвучування прогресу. Модель описує, що буде робити, розповідає про кожен крок, а потім підсумовує результати. -### Саморефлексивний код +### Код із Саморефлексією -Спробуйте "Створити сервіс валідації електронної пошти". Замість простої генерації коду і зупинки, модель генерує, оцінює за критеріями якості, визначає слабкі місця і покращує. Ви побачите, як вона ітерує, доки код не відповідатиме стандартам виробництва. +Спробуйте "Створити сервіс для валідації електронної пошти". Замість простого генерування коду та зупинки, модель генерує, оцінює за критеріями якості, виявляє недоліки і покращує. Ви побачите, як вона ітерує, доки код не відповідатиме виробничим стандартам. -### Структурований аналіз +### Структурований Аналіз -Перегляди коду вимагають узгоджених критеріїв оцінки. Модель аналізує код за фіксованими категоріями (коректність, підходи, продуктивність, безпека) з рівнями серйозності. +Код-рев’ю потребує послідовних рамок оцінювання. Модель аналізує код за фіксованими категоріями (коректність, практики, продуктивність, безпека) з рівнями серйозності. -### Багатокроковий чат +### Чат з Багатьма Повідомленнями -Запитайте "Що таке Spring Boot?" і одразу запитайте "Покажи приклад". Модель пам’ятає ваше перше питання і надає приклад Spring Boot спеціально для нього. Без пам’яті друге питання було б надто загальним. +Запитайте "Що таке Spring Boot?" і відразу потім "Покажи приклад". Модель пам’ятає ваше перше питання і дає приклад Spring Boot саме для нього. Без пам’яті друге питання було б надто загальним. -### Покрокове міркування +### Крок за Кроком Міркування -Візьміть математичну задачу і спробуйте вирішити її двома способами: Покрокове міркування та Низька старанність. Низька старанність дає відповідь швидко, але без пояснень. Покрокове показує кожен розрахунок і рішення. +Візьміть математичну задачу і спробуйте її з обома способами — крок за кроком міркування і низький рівень зацікавленості. Низький рівень просто дає відповідь — швидко, але непрозоро. Крок за кроком показує всі обчислення та рішення. -### Обмежений вивід +### Обмежений Вивід -Коли потрібні специфічні формати чи лічильники слів, цей патерн суворо дотримується вимог. Спробуйте згенерувати резюме точно на 100 слів у форматі пунктів. +Коли потрібні конкретні формати або кількість слів, цей патерн суворо дотримується правил. Спробуйте згенерувати резюме рівно з 100 словами у форматі списку. -## Чого ви справді навчаєтеся +## Чому Ви Справді Навчаєтеся -**Зусилля міркування змінює все** +**Зусилля у Міркуванні Змінюють Усе** -GPT-5.2 дає змогу керувати обчислювальними зусиллями через ваші підказки. Низькі зусилля – швидкі відповіді з мінімальним дослідженням. Високі зусилля – модель глибоко розмірковує, витрачаючи більше часу. Ви навчаєтеся співставляти зусилля із складністю завдання – не марнувати час на прості питання, але й не поспішати з важкими рішеннями. +GPT-5.2 дозволяє контролювати обчислювальні зусилля через підказки. Низькі зусилля означають швидкі відповіді з мінімальним вивченням. Високі — модель тратить час на глибоке мислення. Ви вчитеся співставляти зусилля зі складністю завдання — не марнуйте час на прості питання, але не поспішайте з комплексними рішеннями. -**Структура керує поведінкою** +**Структура Керує Поведінкою** -Помітили XML-теги у підказках? Вони не декоративні. Моделі надійніше дотримуються структурованих інструкцій, аніж вільного тексту. Коли потрібні багатокрокові процеси або складна логіка, структура допомагає моделі відстежувати, на якому вона етапі і що далі. Схема нижче розбиває добре структуровану підказку, показуючи, як теги типу ``, ``, ``, ``, та `` організовують ваші інструкції у чіткі розділи. +Помітили XML-теги в підказках? Вони не для краси. Моделі надійніше слідують структурованим інструкціям, ніж вільному тексту. Коли потрібні багатокрокові процеси або складна логіка, структура допомагає моделі знати, де вона зараз і що далі. Нижче наведена діаграма розбору добре структурованої підказки, що показує, як теги ``, ``, ``, ``, `` організовують ваші інструкції у чіткі секції. -Структура підказки +Prompt Structure -*Анатомія добре структурованої підказки з чіткими розділами і організацією у стилі XML* +*Анатомія добре структурованої підказки з чіткими секціями та організацією у стилі XML* -**Якість через самооцінку** +**Якість Через Самооцінку** -Патерни саморефлексії працюють за рахунок явного вказання критеріїв якості. Замість того, щоб сподіватися, що модель "робить правильно", ви чітко прописуєте, що означає "правильно": логіка, обробка помилок, продуктивність, безпека. Модель може оцінювати власний вивід і покращувати його. Це перетворює генерацію коду з лотереї у процес. +Патерни саморефлексії працюють за рахунок чітких критеріїв якості. Замість сподівань, що модель "зробить правильно", ви точно кажете, що означає "правильно": правильна логіка, обробка помилок, продуктивність, безпека. Модель потім може оцінювати власний вихід і покращуватися. Це перетворює генерацію коду з лотереї у процес. -**Контекст є кінцевим** +**Контекст Обмежений** -Багатокрокові розмови працюють завдяки включенню історії повідомлень у кожен запит. Але існує обмеження – у кожної моделі є максимальна кількість токенів. З ростом розмов треба стратегій, щоб зберігати релевантний контекст, не перевищуючи ліміт. Цей модуль показує, як працює пам’ять; пізніше ви навчитеся, коли сумувати, коли забувати і коли витягати. +Багатоповідомні розмови працюють за рахунок включення історії повідомлень у кожен запит. Але є обмеження - у кожної моделі максимальна кількість токенів. З ростом розмови буде потрібна стратегія збереження релевантного контексту, щоб не перевищувати ліміт. Цей модуль показує, як працює пам’ять; пізніше ви навчитеся, коли підсумовувати, коли забувати і коли витягувати. -## Наступні кроки +## Наступні Кроки **Наступний модуль:** [03-rag - RAG (Retrieval-Augmented Generation)](../03-rag/README.md) --- -**Навігація:** [← Попередній: Модуль 01 - Вступ](../01-introduction/README.md) | [Назад до головної](../README.md) | [Наступний: Модуль 03 - RAG →](../03-rag/README.md) +**Навігація:** [← Попередній: Модуль 01 - Вступ](../01-introduction/README.md) | [Назад на головну](../README.md) | [Наступний: Модуль 03 - RAG →](../03-rag/README.md) --- -**Відмова від відповідальності**: -Цей документ було перекладено за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, враховуйте, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для важливої інформації рекомендується звертатися до професійного перекладу людиною. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. +**Відмова від відповідальності**: +Цей документ було перекладено за допомогою сервісу штучного інтелекту для перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. \ No newline at end of file diff --git a/translations/uk/03-rag/README.md b/translations/uk/03-rag/README.md index 13dc63e1e..7bd332556 100644 --- a/translations/uk/03-rag/README.md +++ b/translations/uk/03-rag/README.md @@ -1,144 +1,143 @@ -# Модуль 03: RAG (Збагачена Пошукова Генерація) +# Модуль 03: RAG (генерація з інформаційним пошуком) ## Зміст -- [Відеоогляд](../../../03-rag) -- [Чому ви навчитеся](../../../03-rag) -- [Вимоги](../../../03-rag) -- [Розуміння RAG](../../../03-rag) - - [Який підхід RAG використовується в цьому підручнику?](../../../03-rag) -- [Як це працює](../../../03-rag) - - [Обробка документів](../../../03-rag) - - [Створення ембеддінгів](../../../03-rag) - - [Семантичний пошук](../../../03-rag) - - [Генерація відповіді](../../../03-rag) -- [Запуск додатку](../../../03-rag) -- [Використання додатку](../../../03-rag) - - [Завантаження документа](../../../03-rag) - - [Задавайте питання](../../../03-rag) - - [Перевірка джерел посилань](../../../03-rag) - - [Експерименти з питаннями](../../../03-rag) -- [Ключові концепції](../../../03-rag) - - [Стратегія розбиття на фрагменти](../../../03-rag) - - [Оцінки схожості](../../../03-rag) - - [Збереження в пам’яті](../../../03-rag) - - [Управління вікном контексту](../../../03-rag) -- [Коли RAG має значення](../../../03-rag) -- [Наступні кроки](../../../03-rag) +- [Проходження Відео](#проходження-відео) +- [Чому Ви Навчитеся](#чому-ви-навчитеся) +- [Передумови](#передумови) +- [Розуміння RAG](#розуміння-rag) + - [Який Підхід RAG Використовується в Цьому Посібнику?](#який-підхід-rag-використовується-в-цьому-посібнику) +- [Як Це Працює](#як-це-працює) + - [Обробка Документів](#обробка-документів) + - [Створення Векторних Представлень](#створення-векторних-представлень) + - [Семантичний Пошук](#семантичний-пошук) + - [Генерація Відповіді](#генерація-відповідей) +- [Запуск Додатку](#запуск-додатку) +- [Використання Додатку](#використання-додатку) + - [Завантаження Документа](#завантаження-документа) + - [Задавайте Питання](#задавайте-питання) + - [Перевірка Джерел](#перевірка-посилань-на-джерела) + - [Експериментуйте з Питаннями](#експериментуйте-з-питаннями) +- [Ключові Концепції](#основні-поняття) + - [Стратегія Розбиття на Частини](#стратегія-розбиття-на-шматки) + - [Оценки Схожості](#оцінки-схожості) + - [Зберігання в Пам’яті](#збереження-в-пам’яті) + - [Управління Вікном Контексту](#управління-вікном-контексту) +- [Коли RAG Має Значення](#коли-rag-є-доречним) +- [Наступні Кроки](#наступні-кроки) -## Відеоогляд +## Проходження Відео -Перегляньте цю живу сесію, де пояснюють, як почати з цього модуля: +Перегляньте це живе заняття, яке пояснює, як почати працювати з цим модулем: -RAG with LangChain4j - Live Session +RAG з LangChain4j - Жива Сесія -## Чому ви навчитеся +## Чому Ви Навчитеся -В попередніх модулях ви навчилися вести розмови з ШІ та ефективно структурувати ваші пропорти. Але існує фундаментальне обмеження: мовні моделі знають лише те, що навчилися під час тренування. Вони не можуть відповідати на питання про політики вашої компанії, документацію проекту чи будь-яку інформацію, яку не тренували. +У попередніх модулях ви вчилися вести розмови з ШІ та ефективно структурувати ваші запити. Але існує фундаментальна обмеженість: мовні моделі знають лише те, що вони вивчили під час навчання. Вони не можуть відповідати на питання щодо політик вашої компанії, документації вашого проєкту або будь-якої інформації, яку вони не бачили під час тренування. -RAG (Збагачена Пошукова Генерація) вирішує цю проблему. Замість того, щоб намагатися навчити модель вашій інформації (що дорого та непрактично), ви даєте їй змогу шукати у ваших документах. Коли хтось ставить запитання, система знаходить релевантну інформацію і включає її у пропорт. Модель відповідає, базуючись на отриманому контексті. +RAG (генерація з інформаційним пошуком) вирішує цю проблему. Замість того, щоб намагатися вчити модель вашій інформації (що дорого та практично неможливо), ви даєте їй можливість шукати у ваших документах. Коли хтось ставить питання, система знаходить релевантну інформацію та включає її в запит. Модель тоді відповідає на основі отриманого контексту. -Уявіть, що RAG дає моделі довідкову бібліотеку. Коли ви ставите запитання, система: +Думайте про RAG як про надання моделі бібліотеки посилань. Коли ви ставите питання, система: -1. **Запит користувача** — Ви ставите запитання -2. **Ембеддінг** — конвертує ваше запитання у вектор -3. **Пошук по векторах** — знаходить схожі фрагменти документів -4. **Збір контексту** — додає релевантні фрагменти до пропорта -5. **Відповідь** — LLM генерує відповідь на основі контексту +1. **Запит Користувача** — ви ставите питання +2. **Векторне Представлення** — перетворює ваше питання у вектор +3. **Пошук по Векторах** — знаходить схожі частини документів +4. **Збір Контексту** — додає релевантні частини до запиту +5. **Відповідь** — великий мовний модель створює відповідь на основі контексту -Це закріплює відповіді моделі на ваших реальних даних, замість покладання на знання під час тренування або вигадки відповідей. +Це підкріплює відповіді моделі вашими реальними даними, а не лише знаннями з тренування або вигадкою відповідей. -## Вимоги +## Передумови -- Пройдено [Модуль 00 - Швидкий старт](../00-quick-start/README.md) (для прикладу Easy RAG, який буде використаний пізніше в цьому модулі) -- Пройдено [Модуль 01 - Вступ](../01-introduction/README.md) (розгорнуті ресурси Azure OpenAI, включаючи модель ембеддінгу `text-embedding-3-small`) -- Файл `.env` у кореневій директорії з обліковими даними Azure (створений командою `azd up` у Модулі 01) +- Завершений [Модуль 01 - Вступ](../01-introduction/README.md) (розгорнуті ресурси Azure OpenAI, включно з вбудованою моделлю `text-embedding-3-small`) +- Файл `.env` в кореневій теці з даними доступу Azure (створений командою `azd up` у Модулі 01) -> **Примітка:** Якщо ви не пройшли Модуль 01, спочатку дотримуйтесь інструкцій розгортання там. Команда `azd up` розгортає як модель чат GPT, так і модель ембеддінгу, яку використовує цей модуль. +> **Примітка:** Якщо ви ще не завершили Модуль 01, спочатку дотримуйтесь інструкцій там. Команда `azd up` розгортає як GPT-модель для чату, так і вбудовану модель, що використовується у цьому модулі. ## Розуміння RAG -Нижче наведена діаграма, що ілюструє основну ідею: замість покладання лише на дані тренування моделі, RAG дає їй довідкову бібліотеку ваших документів, які вона може перевірити перед генерацією кожної відповіді. +Нижче наведена діаграма ілюструє основну ідею: замість того, щоб покладатись лише на дані тренування моделі, RAG надає їй бібліотеку ваших документів для консультації перед створенням кожної відповіді. -What is RAG +Що таке RAG -*Ця діаграма показує відмінність між стандартною LLM (яка гадує на основі даних тренування) і LLM із підтримкою RAG (яка спершу звертається до ваших документів).* +*Ця діаграма показує відмінність між стандартною великою мовною моделлю (яка робить припущення на основі даних тренування) та моделлю RAG, яка спочатку консультується з вашими документами.* -Ось як частини з’єднуються цілком. Запит користувача проходить через чотири етапи — ембеддінг, пошук за векторами, збір контексту та генерація відповіді — кожен будується на попередньому: +Ось як компоненти поєднуються в кінцевому рахунку. Запит користувача проходить чотири етапи — створення векторного представлення, пошук по вектору, збір контексту та генерація відповіді — кожен наступний базується на попередньому: -RAG Architecture +Архітектура RAG -*Ця діаграма показує повний конвеєр RAG — запит користувача проходить через ембеддінг, пошук за векторами, збір контексту та генерацію відповіді.* +*Ця діаграма показує повний конвеєр RAG — запит користувача проходить через створення векторного представлення, пошук, збір контексту та генерацію відповіді.* -Решта модуля покроково розглядає кожен етап із кодом, який ви можете запускати та змінювати. +Решта цього модуля детально розглядає кожен етап, з кодом, який ви можете запускати і змінювати. -### Який підхід RAG використовується в цьому підручнику? +### Який Підхід RAG Використовується в Цьому Посібнику? -LangChain4j пропонує три способи реалізації RAG, кожен із різним рівнем абстракції. Діаграма нижче порівнює їх поруч: +LangChain4j пропонує три способи реалізації RAG, кожен з різним рівнем абстракції. Діаграма нижче порівнює їх поруч: -Three RAG Approaches in LangChain4j +Три Підходи RAG у LangChain4j -*Ця діаграма порівнює три підходи RAG у LangChain4j — Easy, Native та Advanced — показуючи їх ключові компоненти та коли використовувати кожен.* +*Ця діаграма порівнює три підходи LangChain4j RAG — Easy, Native та Advanced — показуючи їх ключові компоненти та коли кожен варто використовувати.* -| Підхід | Що він робить | Компроміс | +| Підхід | Що Робить | Компроміс | |---|---|---| -| **Easy RAG** | Автоматично все підключається через `AiServices` та `ContentRetriever`. Ви анотуєте інтерфейс, приєднуєте отримувача, і LangChain4j обробляє ембеддінг, пошук та складання пропорта за лаштунками. | Мінімум коду, але ви не бачите, що відбувається на кожному етапі. | -| **Native RAG** | Ви виконуєте виклик моделі ембеддінгу, шукаєте в сховищі, будуєте пропорт і генеруєте відповідь самі — по одному явному кроку за раз. | Більше коду, але кожен етап видно і його можна змінювати. | -| **Advanced RAG** | Використовує фреймворк `RetrievalAugmentor` із плагінами для трансформерів запитів, маршрутизаторів, ранжувальників і інжекторів контенту для виробничих конвеєрів. | Максимальна гнучкість, але суттєво більша складність. | +| **Easy RAG** | Автоматично з’єднує все через `AiServices` і `ContentRetriever`. Ви анотуєте інтерфейс, прикріплюєте ретривер, і LangChain4j опрацьовує векторні представленння, пошук і складання запиту в фоновому режимі. | Мінімум коду, але ви не бачите, що відбувається на кожному кроці. | +| **Native RAG** | Ви самі викликаєте модель створення векторних представлень, шукаєте по сховищу, складаєте запит і генеруєте відповідь — по одному кроку за раз. | Більше коду, але кожний етап видимий та керований. | +| **Advanced RAG** | Використовує рамковий модуль `RetrievalAugmentor` з підключними трансформерами запитів, маршрутизаторами, повторними ранжувальниками та інжекторами контенту для виробничих конвеєрів. | Максимальна гнучкість, але значно більша складність. | -**Цей підручник використовує Native підхід.** Кожен крок конвеєра RAG — ембеддінг запиту, пошук у векторному сховищі, збір контексту і генерація відповіді — явно прописаний у [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Це зроблено навмисне: як навчальний ресурс, важливіше, щоб ви бачили і розуміли кожен етап, ніж мінімізували код. Коли ви освоїтесь із тим, як усе працює, можна перейти до Easy RAG для швидких прототипів або Advanced RAG для виробничих систем. +**Цей посібник використовує Native підхід.** Кожен крок RAG-процесу — створення векторного представлення запиту, пошук у сховищі векторів, збір контексту та генерація відповіді — чітко описаний у [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Це зроблено навмисно: як навчальний матеріал, важливіше, щоб ви бачили і розуміли кожен етап, ніж мінімізували код. Коли ви ознайомитеся з процесом, ви зможете перейти до Easy RAG для швидких прототипів або Advanced RAG для виробничих систем. -> **💡 Уже бачили Easy RAG в дії?** [Модуль швидкого старту](../00-quick-start/README.md) містить приклад Document Q&A ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)), який використовує Easy RAG — LangChain4j автоматично робить ембеддінг, пошук і формування пропортів. Цей модуль робить крок далі, відкриваючи той конвеєр, щоб ви могли бачити і контролювати кожен етап самі. +> **💡 Цікавитесь Easy RAG?** LangChain4j також пропонує підхід *Easy RAG*, де `AiServices` і `ContentRetriever` автоматично опрацьовують створення векторних представлень, пошук та складання запиту. Цей модуль іде більш явним шляхом — розкриває цей процес, щоб ви могли бачити та керувати кожним кроком безпосередньо. -Діаграма нижче показує конвеєр Easy RAG з прикладу швидкого старту. Зверніть увагу, як `AiServices` і `EmbeddingStoreContentRetriever` приховують всю складність — ви завантажуєте документ, приєднуєте отримувача та отримуєте відповіді. Native підхід у цьому модулі відкриває кожен прихований крок: +Діаграма нижче показує конвеєр Easy RAG. Зауважте, як `AiServices` і `EmbeddingStoreContentRetriever` приховують всю складність — ви завантажуєте документ, додаєте ретривер і отримуєте відповіді. Native підхід в цьому модулі розкриває кожен із цих прихованих кроків: -Easy RAG Pipeline - LangChain4j +Конвеєр Easy RAG - LangChain4j -*Ця діаграма показує конвеєр Easy RAG з `SimpleReaderDemo.java`. Порівняйте його з Native підходом у цьому модулі: Easy RAG приховує ембеддінг, отримання і формування пропорта за `AiServices` і `ContentRetriever` — ви завантажуєте документ, додаєте отримувача і отримуєте відповіді. Native підхід у цьому модулі відкриває цей конвеєр, щоб ви викликали кожен етап (ембеддінг, пошук, збір контексту, генерація) самі, отримуючи повний огляд і контроль.* +*Ця діаграма показує конвеєр Easy RAG. Порівняйте з Native підходом, використаним у цьому модулі: Easy RAG приховує створення векторних представлень, пошук і складання запиту за `AiServices` та `ContentRetriever` — ви завантажуєте документ, додаєте ретривер і отримуєте відповіді. Native підхід розкриває цей процес так, що ви самі викликаєте кожен крок (створення векторів, пошук, збір контексту, генерацію), отримуючи повну прозорість і контроль.* -## Як це працює +## Як Це Працює -Конвеєр RAG у цьому модулі складається з чотирьох етапів, які виконуються послідовно кожного разу, коли користувач ставить питання. Спершу завантажений документ **розбирається і розбивається на фрагменти**. Ці фрагменти конвертуються у **векторні ембеддінги** і зберігаються, щоб їх можна було математично порівнювати. Коли приходить запит, система виконує **семантичний пошук**, щоб знайти найрелевантніші фрагменти, і в кінці передає їх як контекст LLM для **генерації відповіді**. Нижче кожен етап розглядається детально з прикладами коду та діаграмами. Почнемо з першого кроку. +Конвеєр RAG у цьому модулі поділяється на чотири етапи, які виконуються послідовно щоразу, коли користувач ставить питання. Спершу завантажений документ **розбирається і розбивається на частини** — керовані фрагменти. Ці частини потім конвертуються у **векторні представлення** та зберігаються для математичного порівняння. Коли приходить запит, система виконує **семантичний пошук** для знаходження найбільш релевантних частин, і нарешті передає їх як контекст до великої мовної моделі для **генерації відповіді**. Нижче йде покрокове пояснення кожного етапу з кодом і діаграмами. Почнемо з першого кроку. -### Обробка документів +### Обробка Документів [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Коли ви завантажуєте документ, система розбирає його (PDF або простий текст), додає метадані, такі як ім’я файлу, а потім розбиває на фрагменти — менші частини, що зручно містяться у контекстному вікні моделі. Ці фрагменти трохи перекриваються, щоб контекст на межах не губився. +Коли ви завантажуєте документ, система розбирає його (PDF або простий текст), додає метадані, як-от ім'я файлу, а потім розбиває на частини — менші фрагменти, які зручно поміщаються у контекстне вікно моделі. Ці частини трохи накладаються одна на одну, щоб не втратити контекст на межах. ```java -// Проаналізуйте завантажений файл і обгорніть його у документ LangChain4j +// Розпарсити завантажений файл і обгорнути його в документ LangChain4j Document document = Document.from(content, metadata); -// Розділіть на шматки по 300 токенів з перекриттям у 30 токенів +// Розбити на фрагменти по 300 токенів з перекриттям у 30 токенів DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -Нижче наведена діаграма, що наочно показує цей процес. Зверніть увагу, що кожен фрагмент має спільні токени з сусідніми — 30-токенне перекриття гарантує, що важливий контекст не буде пропущений між межами: -Document Chunking +Нижче діаграма ілюструє це візуально. Зауважте, як кожна частина має невеликий перетин з сусідніми — 30-токенне перекриття гарантує, що важливий контекст не втрачається між частинами: -*Ця діаграма показує розбиття документа на фрагменти по 300 токенів з 30-токенним перекриттям, зберігаючи контекст на межах фрагментів.* +Розбиття Документа на Частини -> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) і запитайте: -> - "Як LangChain4j розбиває документи на фрагменти і чому перекриття важливе?" -> - "Який оптимальний розмір фрагменту для різних типів документів і чому?" -> - "Як обробляти документи кількома мовами або з особливим форматуванням?" +*Ця діаграма показує документ, поділений на частини по 300 токенів із 30 токенами перекриття, зберігаючи контекст на межах частин.* -### Створення ембеддінгів +> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) і запитайте: +> - "Як LangChain4j розбиває документи на частини і чому перекриття важливе?" +> - "Який оптимальний розмір частини для різних типів документів і чому?" +> - "Як обробляти документи кількома мовами або зі спеціальним форматуванням?" + +### Створення Векторних Представлень [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Кожен фрагмент конвертується у числове подання, зване ембеддінгом — фактично конвертер значень у числа. Модель ембеддінгу не є "розумною", як чат-модель; вона не виконує інструкції, не міркує і не відповідає на питання. Вона може лише відобразити текст у математичному просторі, де схожі значення опиняються близько одне до одного — "автомобіль" біля "машини", "політика повернення грошей" біля "поверніть мої гроші". Уявіть чат-модель як людину, з якою можна спілкуватися; а модель ембеддінгу – як дуже хорошу систему архівування. +Кожна частина перетворюється у числове представлення, зване векторним представленням (embedding) — по суті конвертер змісту у числа. Модель для векторів не є "інтелектуальною", як чат-модель; вона не виконує інструкцій, не логікує та не відповідає на питання. Вона просто відображає текст у математичний простір, де схожі значення розташовуються поряд — "автомобіль" поруч із "машина", "політика повернення" поруч із "поверніть мої гроші". Якщо чат-модель — це співрозмовник, то модель векторних представлень — це відмінна система зберігання файлів. -Діаграма нижче візуалізує цю ідею — йде текст, виходять числові вектори, і схожі значення розташовуються поряд: +Нижче діаграма візуалізує цю концепцію — текст перетворюється на числові вектори, а схожі за значенням слова/фрази утворюють кластери: -Embedding Model Concept +Концепція Векторної Моделі -*Ця діаграма показує, як модель ембеддінгу конвертує текст у числові вектори, розміщуючи схожі значення — як "машина" і "автомобіль" — біля одне одного у векторному просторі.* +*Ця діаграма показує, як модель векторних представлень конвертує текст у числові вектори, розміщаючи схожі за значенням слова — як "автомобіль" та "машина" — поруч у векторному просторі.* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -Діаграма класів нижче показує два окремі потоки в конвеєрі RAG і класи LangChain4j, які їх реалізують. **Потік загрузки** (виконується один раз під час завантаження) розбиває документ, створює ембеддінги фрагментів і зберігає їх через `.addAll()`. **Потік запиту** (виконується кожен раз, коли користувач ставить питання) створює ембеддінг запиту, шукає в сховищі через `.search()` і передає знайдений контекст чат-моделі. Обидва потоки взаємодіють через спільний інтерфейс `EmbeddingStore`: -LangChain4j RAG Classes +Класова діаграма нижче демонструє дві окремі гілки у RAG-процесі і відповідні класи LangChain4j. Потік **завантаження** (виконується раз при завантаженні) розбиває документ, створює векторні представлення частин та зберігає їх через `.addAll()`. Потік **запитів** (кожного разу при питанні) створює векторне представлення питання, шукає у сховищі через `.search()` і передає знайдений контекст чат-моделі. Обидва потоки з’єднуються через спільний інтерфейс `EmbeddingStore`: + +Класи RAG LangChain4j -*Ця діаграма показує два потоки в конвеєрі RAG — загрузку і запит — та їх взаємозв’язок через спільний EmbeddingStore.* +*Ця діаграма показує два потоки у RAG — завантаження та запит — і як вони взаємодіють через спільний EmbeddingStore.* -Після збереження ембеддінгів схожий контент природньо групується у векторному просторі. Візуалізація нижче показує, як документи за суміжними темами опиняються близько один до другого, що робить можливим семантичний пошук: +Після збереження векторних представлень, схожий контент природно групується у векторному просторі. Візуалізація нижче показує, як документи на близькі теми збираються в окремі кластери, що і робить семантичний пошук можливим: -Vector Embeddings Space +Простір Векторних Представлень -*Ця візуалізація показує, як пов’язані документи групуються в 3D векторному просторі, утворюючи окремі кластери за темами, як Технічна документація, Бізнес правила та FAQ.* +*Ця візуалізація показує, як пов’язані документи групуються у 3D векторному просторі, утворюючи окремі групи за темами, наприклад, Технічна Документація, Бізнес-правила, Часті Запитання.* -Коли користувач виконує пошук, система виконує чотири кроки: один раз створює ембеддінги документів, кожного разу ембеддить запит, порівнює вектор запиту з усіма збереженими векторами за косинусною схожістю та повертає топ-K найвищих за балом фрагментів. Діаграма нижче демонструє кожен крок і класи LangChain4j, що беруть участь: +Коли користувач шукає, система виконує чотири кроки: створює embeddings для документів один раз, створює embedding запиту для кожного пошуку, порівнює вектор запиту зі всіма збереженими векторами за косинусною схожістю та повертає топ-К найкращих частин. Нижче діаграма показує кожен крок і відповідні класи LangChain4j: -Embedding Search Steps +Кроки Пошуку за Векторними Представленнями -*Ця діаграма показує чотирикроковий процес пошуку за ембеддінгами: ембеддинг документів, ембеддинг запиту, порівняння векторів за косинусною схожістю і повернення топ-K результатів.* +*Ця діаграма показує чотириступеневий процес пошуку за векторними представленнями: створення векторів документів, створення вектору запиту, порівняння векторів косинусною схожістю та повернення топ-К результатів.* -### Семантичний пошук +### Семантичний Пошук [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Коли ви ставите запитання, воно також конвертується в ембеддінг. Система порівнює ембеддінг вашого запитання з усіма ембеддінгами фрагментів документів. Знаходить ті, що мають найбільш схожу суть — не лише сумісні ключові слова, а справжню семантичну схожість. +Коли ви ставите питання, ваше питання також перетворюється у embedding. Система порівнює embedding вашого запиту з embedding-ами всіх частин документів. Вона знаходить частини з найбільш схожими значеннями — не просто за ключовими словами, а за фактичною семантичною близькістю. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -Нижче наведена діаграма, яка порівнює семантичний пошук і традиційний пошук за ключовими словами. Пошук за ключовим словом "транспорт" пропускає фрагмент про "автомобілі та вантажівки", а семантичний пошук розуміє, що це одне й те саме, і повертає його з високим балом: -Semantic Search +Діаграма нижче порівнює семантичний пошук із традиційним пошуком за ключовими словами. Пошук за ключовим словом "транспорт" пропускає частину про "автомобілі та вантажівки", тоді як семантичний пошук розуміє, що це те саме, і повертає її як відповідний результат: -*Ця діаграма порівнює пошук за ключовими словами і семантичний пошук, показуючи, як семантичний пошук отримує концептуально пов’язаний контент навіть коли точні ключові слова відрізняються.* -Під капотом схожість вимірюється за допомогою косинусної схожості — по суті питання "чи спрямовані ці дві стрілки в одному напрямку?" Два шматки тексту можуть використовувати абсолютно різні слова, але якщо вони мають однаковий зміст, їх вектори вказують в один бік і оцінка близька до 1.0: +Семантичний Пошук -Косинусна схожість +*Ця діаграма порівнює пошук за ключовими словами з семантичним пошуком, показуючи, як семантичний пошук знаходить концептуально суміжний контент, навіть якщо точні слова відрізняються.* -*Ця діаграма ілюструє косинусну схожість як кут між векторами впровадження — вектори, що більше вирівняні, отримують оцінку ближче до 1.0, що вказує на вищу семантичну схожість.* +Під капотом схожість вимірюється за допомогою косинусної схожості — фактично питання "чи вказують ці дві стріли в один напрямок?" Два фрагменти можуть містити зовсім різні слова, але якщо вони мають той самий зміст, їхні вектори дивляться в один бік і оцінка близька до 1.0: -> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) і запитайте: -> - "Як працює пошук за схожістю з використанням впроваджень і що визначає оцінку?" +Косинусна Схожість +*Ця діаграма ілюструє косинусну схожість як кут між векторами вставок — більш узгоджені вектори мають оцінку ближчу до 1.0, що вказує на вищу семантичну схожість.* + +> **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) та запитайте: +> - "Як працює пошук за схожістю з використанням embedding і що визначає оцінку?" > - "Який поріг схожості слід використовувати і як це впливає на результати?" -> - "Як мені обробляти випадки, коли релевантні документи не знайдені?" +> - "Як опрацювати випадки, коли не знайдено релевантних документів?" -### Генерація відповіді +### Генерація відповідей [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Найрелевантніші шматки збираються у структурований prompt, що включає явні інструкції, отриманий контекст і запит користувача. Модель читає ці конкретні шматки і відповідає на основі цієї інформації — вона може використовувати лише те, що перед нею, що запобігає галюцинаціям. +Найрелевантніші шматки збираються у структурований підказку, що містить явні інструкції, отриманий контекст і запит користувача. Модель читає лише ці конкретні шматки та відповідає на основі цієї інформації — вона може використовувати лише те, що перед нею, що запобігає галюцинаціям. ```java String context = matches.stream() @@ -237,21 +236,21 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Нижче наведена діаграма, яка показує цю збірку у дії — найвищо оцінені шматки з кроку пошуку вставляються у шаблон prompt, а `OpenAiOfficialChatModel` генерує обґрунтовану відповідь: +Наведену нижче діаграму показано цей процес збірки — найбільш релевантні шматки з кроку пошуку вставляються у шаблон підказки, і `OpenAiOfficialChatModel` генерує обґрунтовану відповідь: -Збірка контексту +Збір контексту -*Ця діаграма показує, як найвищо оцінені шматки збираються в структурований prompt, що дозволяє моделі генерувати обґрунтовану відповідь на основі ваших даних.* +*Ця діаграма показує, як найбільш релевантні шматки збираються у структуровану підказку, що дозволяє моделі створювати обґрунтовані відповіді на основі ваших даних.* -## Запуск застосунку +## Запуск додатку -**Перевірка розгортання:** +**Перевірте розгортання:** -Переконайтеся, що файл `.env` існує в кореневій директорії з обліковими даними Azure (створений під час Модуля 01). Запустіть це з директорії модуля (`03-rag/`): +Переконайтесь, що файл `.env` існує в кореневій теці з обліковими даними Azure (створений під час Модуля 01). Запустіть це з каталогу модуля (`03-rag/`): **Bash:** ```bash -cat ../.env # Повинно показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +cat ../.env # Має показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **PowerShell:** @@ -259,29 +258,29 @@ cat ../.env # Повинно показувати AZURE_OPENAI_ENDPOINT, API_KE Get-Content ..\.env # Повинно показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Запуск застосунку:** +**Запустіть додаток:** -> **Примітка:** Якщо ви вже запускали всі застосунки за допомогою `./start-all.sh` з кореневої директорії (як описано в Модулі 01), цей модуль вже працює на порту 8081. Ви можете пропустити команди запуску нижче і перейти безпосередньо за адресою http://localhost:8081. +> **Примітка:** Якщо ви вже запускали всі додатки за допомогою `./start-all.sh` з кореневого каталогу (як описано в Модулі 01), цей модуль вже працює на порту 8081. Ви можете пропустити команди запуску нижче і перейти безпосередньо на http://localhost:8081. -**Опція 1: Використання Spring Boot Dashboard (Рекомендується для користувачів VS Code)** +**Варіант 1: Використання Spring Boot Dashboard (Рекомендується для користувачів VS Code)** -Dev-контейнер включає розширення Spring Boot Dashboard, яке надає візуальний інтерфейс для керування всіма застосунками Spring Boot. Ви можете знайти його у панелі активності зліва у VS Code (шукайте іконку Spring Boot). +Контейнер розробника включає розширення Spring Boot Dashboard, яке надає візуальний інтерфейс для керування всіма додатками Spring Boot. Ви можете знайти його в панелі активностей ліворуч у VS Code (шукайте іконку Spring Boot). -За допомогою Spring Boot Dashboard ви можете: -- Побачити всі доступні застосунки Spring Boot у робочій області -- Запускати/зупиняти застосунки одним кліком -- Переглядати логи застосунків у реальному часі -- Моніторити статус застосунків +З Spring Boot Dashboard ви можете: +- Побачити всі доступні додатки Spring Boot у робочому просторі +- Запускати/зупиняти додатки одним кліком +- Переглядати логи додатків у реальному часі +- Моніторити стан додатків -Просто натисніть кнопку відтворення поряд із "rag", щоб запустити цей модуль, або запустіть усі модулі одночасно. +Просто натисніть кнопку відтворення поруч з "rag", щоб запустити цей модуль, або запустіть всі модулі одночасно. -Spring Boot Dashboard +Панель керування Spring Boot -*Цей скріншот показує Spring Boot Dashboard у VS Code, де ви можете запускати, зупиняти та моніторити застосунки у візуальному режимі.* +*Цей знімок екрана показує Spring Boot Dashboard у VS Code, де ви можете запускати, зупиняти та моніторити додатки візуально.* -**Опція 2: Використання shell-скриптів** +**Варіант 2: Використання shell-скриптів** -Запустіть усі веб-застосунки (модулі 01-04): +Запустіть усі веб-додатки (модулі 01-04): **Bash:** ```bash @@ -291,11 +290,11 @@ cd .. # З кореневого каталогу **PowerShell:** ```powershell -cd .. # З кореневої директорії +cd .. # З кореневого каталогу .\start-all.ps1 ``` -Або запустіть тільки цей модуль: +Або запустіть лише цей модуль: **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Обидва скрипти автоматично завантажують змінні середовища з кореневого файлу `.env` і будуть збирати JAR-файли, якщо вони відсутні. +Обидва скрипти автоматично завантажують змінні оточення з кореневого файлу `.env` і збудують JAR-файли, якщо вони відсутні. -> **Примітка:** Якщо ви хочете збирати всі модулі вручну перед запуском: +> **Примітка:** Якщо ви хочете вручну збудувати всі модулі перед запуском: > > **Bash:** > ```bash @@ -331,7 +330,7 @@ cd 03-rag **Bash:** ```bash -./stop.sh # Цей модуль лише +./stop.sh # Тільки цей модуль # Або cd .. && ./stop-all.sh # Всі модулі ``` @@ -340,98 +339,98 @@ cd .. && ./stop-all.sh # Всі модулі ```powershell .\stop.ps1 # Тільки цей модуль # Або -cd ..; .\stop-all.ps1 # Усі модулі +cd ..; .\stop-all.ps1 # Всі модулі ``` -## Використання застосунку +## Використання додатку -Застосунок надає веб-інтерфейс для завантаження документів і постановки питань. +Додаток надає веб-інтерфейс для завантаження документів та задавання питань. -Інтерфейс RAG Застосунку +Інтерфейс додатку RAG -*Цей скріншот показує інтерфейс застосунку RAG, де ви завантажуєте документи і ставите запитання.* +*Цей знімок екрана показує інтерфейс додатку RAG, де ви завантажуєте документи і ставите запитання.* ### Завантаження документа -Почніть із завантаження документа — TXT-файли найкраще підходять для тестування. У цій директорії надається `sample-document.txt`, який містить інформацію про функції LangChain4j, реалізацію RAG та найкращі практики — ідеально для тестування системи. +Почніть із завантаження документа — TXT-файли найкраще підходять для тестування. У цій теці є `sample-document.txt`, який містить інформацію про особливості LangChain4j, реалізацію RAG та найкращі практики — ідеально для тестування системи. -Система обробляє ваш документ, розбиває його на шматки та створює впровадження для кожного шматка. Це відбувається автоматично при завантаженні. +Система обробляє ваш документ, розбиває його на шматки та створює embedding для кожного шматка. Це відбувається автоматично після завантаження. -### Постановка питань +### Задавайте питання -Тепер ставте конкретні запитання про зміст документа. Спробуйте щось фактичне, що чітко вказано в документі. Система шукає релевантні шматки, включає їх у prompt і генерує відповідь. +Тепер задайте конкретні питання про вміст документа. Спробуйте щось фактичне, що чітко вказано в документі. Система шукає релевантні шматки, включає їх у підказку і генерує відповідь. ### Перевірка посилань на джерела -Зверніть увагу, що кожна відповідь містить посилання на джерела з оцінками схожості. Ці оцінки (від 0 до 1) показують, наскільки релевантний кожен шматок вашому запитанню. Вищі оцінки означають кращі збіги. Це дає змогу перевірити відповідь за джерельним матеріалом. +Зверніть увагу, що кожна відповідь містить посилання на джерела з оцінками схожості. Ці оцінки (від 0 до 1) показують, наскільки релевантним був кожний шматок до вашого питання. Вищі оцінки означають кращі відповідності. Це дозволяє вам перевірити відповідь на основі джерельного матеріалу. -Результати запиту RAG +Результати запитів RAG -*Цей скріншот показує результати запиту з згенерованою відповіддю, посиланнями на джерела та оцінками релевантності для кожного витягнутого шматка.* +*Цей скріншот показує результати запиту з генерованою відповіддю, посиланнями на джерела та оцінками релевантності кожного отриманого шматка.* ### Експериментуйте з питаннями Спробуйте різні типи питань: - Конкретні факти: "Яка основна тема?" -- Порівняння: "Яка різниця між X та Y?" -- Підсумки: "Підсумуйте ключові моменти про Z" +- Порівняння: "У чому різниця між X та Y?" +- Резюме: "Підсумуйте ключові моменти про Z" -Спостерігайте, як оцінки релевантності змінюються залежно від того, наскільки добре ваше питання відповідає змісту документа. +Спостерігайте, як змінюються оцінки релевантності залежно від того, наскільки добре ваше питання відповідає вмісту документа. -## Ключові поняття +## Основні поняття ### Стратегія розбиття на шматки -Документи розбиваються на шматки по 300 токенів з 30 токенами перекриття. Такий баланс забезпечує достатній контекст у кожному шматку, щоб бути змістовним, при цьому зберігаючи розмір достатньо малим, щоб можна було включити кілька шматків у prompt. +Документи розбиваються на шматки по 300 токенів з 30 токенами перекриття. Такий баланс гарантує, що кожен шматок має достатній контекст, щоб бути змістовним, при цьому залишається досить маленьким, щоб включити кілька шматків у підказку. ### Оцінки схожості -Кожен витягнутий шматок має оцінку схожості між 0 та 1, що показує, наскільки він відповідає запитанню користувача. Нижче наведена діаграма, що візуалізує діапазони оцінок і як система використовує їх для фільтрації результатів: +Кожний отриманий шматок має оцінку схожості від 0 до 1, що вказує, наскільки близько він відповідає питанню користувача. Наведена нижче діаграма візуалізує діапазони оцінок і як система їх використовує для фільтрації результатів: Оцінки схожості -*Ця діаграма показує діапазони оцінок від 0 до 1, з мінімальним порогом 0.5, що фільтрує нерелевантні шматки.* +*Ця діаграма показує діапазони оцінок від 0 до 1 з мінімальним порогом 0.5, що фільтрує нерелевантні шматки.* -Оцінки варіюються від 0 до 1: -- 0.7-1.0: Дуже релевантні, точна відповідність -- 0.5-0.7: Релевантні, хороший контекст -- Нижче 0.5: Відфільтровані, занадто відмінні +Оцінки коливаються від 0 до 1: +- 0.7-1.0: Високорелевантні, точне співпадіння +- 0.5-0.7: Релевантні, добрий контекст +- Нижче 0.5: Відфільтровані, надто різні -Система витягує лише шматки вище мінімального порогу для забезпечення якості. +Система витягує лише шматки, які перевищують мінімальний поріг для забезпечення якості. -Впровадження добре працюють, коли значення чітко кластеризується, але мають сліпі зони. Діаграма нижче показує типові режими відмов — занадто великі шматки створюють нечіткі вектори, занадто малі не мають контексту, неоднозначні терміни вказують на кілька кластерів, а пошук точних збігів (ID, номери деталей) взагалі не працює з впровадженнями: +Embedding працюють добре, коли значення згруповані чітко, але мають "сліпі зони". Наведена нижче діаграма показує типові помилки — занадто великі шматки дають "розмиті" вектори, занадто малі не мають контексту, неоднозначні терміни вказують на кілька кластерів, а точні пошуки за співпадінням (ID, номери деталей) зовсім не працюють з embedding: -Режими відмов впроваджень +Типові помилки embedding -*Ця діаграма показує загальні режими відмов впроваджень: шматки занадто великі, шматки занадто малі, неоднозначні терміни, які вказують на кілька кластерів, та пошук точних збігів, як-от ID.* +*Ця діаграма показує типові випадки помилок embedding: занадто великі шматки, занадто малі, неоднозначні терміни, які вказують на кілька кластерів, та пошук точних співпадінь як ID.* -### Зберігання в оперативній пам’яті +### Збереження в пам’яті -Цей модуль використовує зберігання в оперативній пам’яті для простоти. При перезапуску застосунку завантажені документи втрачаються. У продуктивних системах використовують персистентні векторні бази даних, такі як Qdrant або Azure AI Search. +Цей модуль використовує збереження в оперативній пам’яті для простоти. Після перезапуску додатку завантажені документи втрачаються. У промислових системах використовують стійкі векторні бази даних, як Qdrant або Azure AI Search. -### Управління контекстним вікном +### Управління вікном контексту -Кожна модель має максимальний розмір контекстного вікна. Ви не можете включити всі шматки великого документа. Система витягує топ N найбільш релевантних шматків (за замовчуванням 5), щоб залишатися в межах лімітів і водночас надавати достатній контекст для точних відповідей. +Кожна модель має максимальний розмір вікна контексту. Ви не можете включити всі шматки великого документа. Система вибирає топ N найбільш релевантних шматків (за замовчуванням 5), щоб відповідати обмеженням і надати достатньо контексту для точних відповідей. -## Коли RAG має значення +## Коли RAG є доречним -RAG не завжди є правильним підходом. Наведений нижче довідник допоможе визначити, коли RAG додає цінність, а коли простіші підходи — як включення контенту безпосередньо в prompt або покладання на вбудовані знання моделі — достатні: +RAG не завжди є правильним підходом. Наступний довідник допоможе вам визначити, коли RAG додає цінність, а коли простіші підходи — як включення контенту безпосередньо у підказку чи покликання на вбудовані знання моделі — є достатніми: Коли використовувати RAG -*Ця діаграма показує довідник прийняття рішень, коли RAG додає цінність, а коли достатні простіші підходи.* +*Ця діаграма показує довідник для прийняття рішення, коли RAG додає цінність у порівнянні з простішими підходами.* ## Наступні кроки -**Наступний модуль:** [04-tools - AI агенти з інструментами](../04-tools/README.md) +**Наступний модуль:** [04-tools - AI Агенти з Інструментами](../04-tools/README.md) --- -**Навігація:** [← Попередній: Модуль 02 - Інженерія промптів](../02-prompt-engineering/README.md) | [Назад до головної](../README.md) | [Далі: Модуль 04 - Інструменти →](../04-tools/README.md) +**Навігація:** [← Попередній: Модуль 02 - Проєктування підказок](../02-prompt-engineering/README.md) | [Назад до головного](../README.md) | [Наступний: Модуль 04 - Інструменти →](../04-tools/README.md) --- **Відмова від відповідальності**: -Цей документ було перекладено за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоч ми і прагнемо до точності, просимо враховувати, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендовано звертатися до професійного людського перекладу. Ми не несемо відповідальності за будь-які непорозуміння чи неправильні тлумачення, що виникли внаслідок використання цього перекладу. +Цей документ було перекладено за допомогою сервісу штучного інтелекту для перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. \ No newline at end of file diff --git a/translations/uk/04-tools/README.md b/translations/uk/04-tools/README.md index 45b552218..632464dbc 100644 --- a/translations/uk/04-tools/README.md +++ b/translations/uk/04-tools/README.md @@ -2,75 +2,75 @@ ## Зміст -- [Відео-пояснення](../../../04-tools) -- [Чому ви навчитеся](../../../04-tools) -- [Передумови](../../../04-tools) -- [Розуміння AI агентів з інструментами](../../../04-tools) -- [Як працює виклик інструментів](../../../04-tools) - - [Визначення інструментів](../../../04-tools) - - [Прийняття рішень](../../../04-tools) - - [Виконання](../../../04-tools) - - [Генерація відповіді](../../../04-tools) - - [Архітектура: Автовключення Spring Boot](../../../04-tools) -- [Ланцюжок інструментів](../../../04-tools) -- [Запуск програми](../../../04-tools) -- [Використання програми](../../../04-tools) - - [Спробуйте просте використання інструментів](../../../04-tools) - - [Перевірте ланцюжок інструментів](../../../04-tools) - - [Подивіться на хід розмови](../../../04-tools) - - [Експериментуйте з різними запитами](../../../04-tools) -- [Ключові поняття](../../../04-tools) - - [Патерн ReAct (Міркування і Дія)](../../../04-tools) - - [Опис інструментів має значення](../../../04-tools) - - [Управління сеансами](../../../04-tools) - - [Обробка помилок](../../../04-tools) -- [Доступні інструменти](../../../04-tools) -- [Коли слід використовувати агентів на основі інструментів](../../../04-tools) -- [Інструменти vs RAG](../../../04-tools) -- [Наступні кроки](../../../04-tools) - -## Відео-пояснення - -Перегляньте цю живу сесію, яка пояснює, як розпочати роботу з цим модулем: +- [Огляд відео](#огляд-відео) +- [Чого ви навчитесь](#чого-ви-навчитесь) +- [Вимоги](#вимоги) +- [Розуміння AI-агентів з інструментами](#розуміння-ai-агентів-з-інструментами) +- [Як працює виклик інструментів](#як-працює-виклик-інструментів) + - [Визначення інструментів](#визначення-інструментів) + - [Прийняття рішень](#прийняття-рішень) + - [Виконання](#виконання) + - [Генерація відповіді](#генерація-відповіді) + - [Архітектура: Spring Boot Auto-Wiring](#архітектура-spring-boot-auto-wiring) +- [Ланцюжок інструментів](#ланцюжок-інструментів) +- [Запустіть додаток](#запустіть-додаток) +- [Використання додатку](#використання-додатку) + - [Спробуйте просте використання інструментів](#спробуйте-просте-використання-інструменту) + - [Перевірте ланцюжок інструментів](#тестуйте-ланцюжок-інструментів) + - [Перегляньте хід розмови](#перегляньте-хід-розмови) + - [Експериментуйте з різними запитами](#експериментуйте-з-різними-запитами) +- [Ключові концепції](#ключові-концепції) + - [Шаблон ReAct (міркування та дія)](#патерн-react-обґрунтування-та-дія) + - [Важливість описів інструментів](#важливість-описів-інструментів) + - [Управління сесіями](#керування-сесією) + - [Обробка помилок](#обробка-помилок) +- [Доступні інструменти](#доступні-інструменти) +- [Коли використовувати агентів на основі інструментів](#коли-використовувати-агентів-на-основі-інструментів) +- [Інструменти vs RAG](#інструменти-проти-rag) +- [Наступні кроки](#наступні-кроки) + +## Огляд відео + +Дивіться цю живу сесію, яка пояснює, як почати роботу з цим модулем: AI Agents with Tools and MCP - Live Session -## Чому ви навчитеся +## Чого ви навчитесь -До цього ви навчились вести бесіди з AI, ефективно структурувати запити і базувати відповіді на документах. Але існує фундаментальне обмеження: мовні моделі можуть тільки генерувати текст. Вони не можуть перевірити погоду, виконувати обчислення, робити запити до баз даних або взаємодіяти з зовнішніми системами. +На даний момент ви навчилися вести розмови з AI, ефективно структурувати підказки та базувати відповіді на ваших документах. Але існує фундаментальне обмеження: мовні моделі можуть лише генерувати текст. Вони не можуть перевірити погоду, виконати розрахунки, робити запити до баз даних або взаємодіяти з зовнішніми системами. -Інструменти змінюють це. Надаючи моделі доступ до функцій, які вона може викликати, ви перетворюєте її з генератора тексту на агента, який здатен виконувати дії. Модель вирішує, коли їй потрібен інструмент, який саме і з якими параметрами. Ваш код виконує функцію і повертає результат. Модель включає цей результат у свою відповідь. +Інструменти змінюють це. Надаючи моделі доступ до функцій, які вона може викликати, ви перетворюєте її з генератора тексту в агента, що може виконувати дії. Модель вирішує, коли їй потрібен інструмент, який саме інструмент використати і які параметри передати. Ваш код виконує функцію та повертає результат. Модель інтегрує цей результат у свою відповідь. -## Передумови +## Вимоги -- Пройдено [Модуль 01 - Вступ](../01-introduction/README.md) (розгорнуті ресурси Azure OpenAI) -- Рекомендовано пройти попередні модулі (цей модуль посилається на [концепції RAG з Модуля 03](../03-rag/README.md) у порівнянні Інструменти vs RAG) -- Файл `.env` у кореневій теці з обліковими даними Azure (створений за допомогою `azd up` у Модулі 01) +- Завершений [Модуль 01 - Вступ](../01-introduction/README.md) (розгорнуті ресурси Azure OpenAI) +- Рекомендуються попередні модулі (цей модуль посилається на [концепції RAG з Модуля 03](../03-rag/README.md) у порівнянні Інструменти vs RAG) +- Файл `.env` у кореневій директорії з обліковими даними Azure (створений командою `azd up` у Модулі 01) -> **Примітка:** Якщо ви не завершили Модуль 01, спершу виконайте інструкції з розгортання там. +> **Примітка:** Якщо ви не завершили Модуль 01, спочатку дотримуйтесь інструкцій з розгортання там. -## Розуміння AI агентів з інструментами +## Розуміння AI-агентів з інструментами -> **📝 Примітка:** Термін "агенти" у цьому модулі означає AI-асистентів із можливістю виклику інструментів. Це відрізняється від патернів **Agentic AI** (автономні агенти з плануванням, пам’яттю і багатоетапним міркуванням), які ми розглянемо в [Модулі 05: MCP](../05-mcp/README.md). +> **📝 Примітка:** Термін "агенти" у цьому модулі означає AI-помічників з можливістю виклику інструментів. Це відрізняється від патернів **Agentic AI** (автономні агенти з плануванням, пам’яттю та багатокроковим розмірковуванням), які ми розглянемо у [Модулі 05: MCP](../05-mcp/README.md). -Без інструментів мовна модель може тільки генерувати текст на основі свого навчання. Запитайте погоду — вона мусить здогадуватись. Дайте їй інструменти — вона може викликати API погоди, робити обчислення або запити до бази даних, а потім вставити реальні результати у відповідь. +Без інструментів мовна модель може лише генерувати текст з навчальних даних. Запитайте про поточну погоду — і вона мусить гадати. Дайте їй інструменти — і вона може викликати API погоди, виконати розрахунки або запитати базу даних — та включити ці реальні результати у відповідь. -Без інструментів проти з інструментами +Без інструментів vs з інструментами -*Без інструментів модель тільки здогадується — з інструментами вона може викликати API, виконувати обчислення та повертати актуальні дані.* +*Без інструментів модель лише здогадується — з інструментами вона може викликати API, виконувати розрахунки і повертати дані в реальному часі.* -AI-агент з інструментами слідує патерну **Reasoning and Acting (ReAct)**. Модель не просто відповідає — вона мислить, що їй потрібно, діє через виклик інструменту, спостерігає результат і вирішує, чи потрібно діяти знову, або надати остаточну відповідь: +AI-агент з інструментами дотримується патерну **Reasoning and Acting (ReAct)**. Модель не просто відповідає — вона думає, що їй потрібно, діє, викликаючи інструмент, спостерігає результат, а потім вирішує, чи треба діяти знову, чи надати остаточну відповідь: -1. **Міркування** — агент аналізує питання користувача та визначає, яка інформація потрібна -2. **Дія** — агент обирає правильний інструмент, формує параметри і викликає його -3. **Спостереження** — агент отримує результат інструменту і оцінює його -4. **Повтор або Відповідь** — якщо потрібно більше даних, агент повертається на початок; інакше формує відповідь природною мовою +1. **Розмірковування** — агент аналізує запит користувача і визначає, яку інформацію потрібно отримати +2. **Дія** — агент вибирає відповідний інструмент, генерує правильні параметри і викликає його +3. **Спостереження** — агент отримує результат роботи інструмента і оцінює його +4. **Повторення або відповідь** — якщо потрібні додаткові дані, агент повертається до кроку 1; інакше формує відповідь природною мовою Патерн ReAct -*Цикл ReAct — агент міркує, що робити, діє через виклик інструменту, спостерігає результат і повторює, доки не сформує остаточну відповідь.* +*Цикл ReAct — агент розмірковує, що зробити, виконує виклик інструмента, спостерігає за результатом і повторює, доки не сформує остаточну відповідь.* -Це відбувається автоматично. Ви визначаєте інструменти і їх описи. Модель приймає рішення про те, коли і як їх використовувати. +Це відбувається автоматично. Ви визначаєте інструменти та їх описи. Модель приймає рішення, коли і як їх використовувати. ## Як працює виклик інструментів @@ -78,7 +78,7 @@ AI-агент з інструментами слідує патерну **Reason [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Ви визначаєте функції з чіткими описами та специфікаціями параметрів. Модель бачить ці описи у системному запиті і розуміє, що робить кожен інструмент. +Ви визначаєте функції з чіткими описами та специфікаціями параметрів. Модель бачить ці описи у системній підказці і розуміє, що робить кожен інструмент. ```java @Component @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Помічник автоматично підключається Spring Boot з: +// Асистент автоматично підключається через Spring Boot з: // - Bean ChatModel -// - Всі методи @Tool з класів @Component +// - Всі методи @Tool з класів, позначених @Component // - ChatMemoryProvider для управління сесіями ``` -Нижче наведена схема розбиває кожну анотацію і показує, як кожен елемент допомагає AI розуміти, коли викликати інструмент і які аргументи передавати: +Нижче наведена діаграма розбиває кожну анотацію і показує, як кожен елемент допомагає AI зрозуміти, коли викликати інструмент і які аргументи передавати: -Анатомія визначень інструментів +Анатомія визначення інструментів -*Анатомія визначення інструменту — @Tool повідомляє AI, коли використовувати його, @P описує кожен параметр, а @AiService зв’язує все разом під час запуску.* +*Анатомія визначення інструмента — @Tool повідомляє AI, коли його використовувати, @P описує кожен параметр, а @AiService об’єднує все разом при запуску.* > **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) і запитайте: -> - "Як інтегрувати реальний API погоди як OpenWeatherMap замість макетних даних?" -> - "Що робить хороший опис інструменту, який допомагає AI правильно його використовувати?" -> - "Як обробляти помилки API і обмеження швидкості у реалізації інструментів?" +> - "Як інтегрувати реальний погодний API, наприклад OpenWeatherMap, замість мок-даних?" +> - "Що робить опис інструмента корисним для правильного використання AI?" +> - "Як обробляти помилки API та обмеження за кількістю викликів у реалізації інструментів?" ### Прийняття рішень -Коли користувач питає "Яка погода в Сіетлі?", модель не обирає інструмент випадково. Вона порівнює намір користувача з усіма описами інструментів, які їй доступні, оцінює кожен по релевантності і обирає найкращий. Потім створює структурований виклик функції з правильними параметрами — в цьому випадку встановлює `location` у `"Seattle"`. +Коли користувач питає "Яка погода в Сіетлі?", модель не вибирає інструмент випадково. Вона порівнює намір користувача з описами всіх доступних інструментів, оцінює кожен за релевантністю і вибирає найкращий. Потім генерує структурований виклик функції з правильними параметрами — у цьому випадку `location` встановлюється в `"Seattle"`. -Якщо жоден інструмент не підходить під запит користувача, модель відповідає зі своєї власної бази знань. Якщо кілька інструментів підходять, вона вибирає найконкретніший. +Якщо жоден інструмент не підходить під запит користувача, модель відповідає на основі власних знань. Якщо підходить кілька інструментів, вона обирає найбільш специфічний. Як AI вирішує, який інструмент використовувати -*Модель оцінює кожен доступний інструмент щодо наміру користувача і вибирає найкращий — тому важливо писати чіткі і конкретні описи інструментів.* +*Модель оцінює кожен доступний інструмент щодо наміру користувача та обирає найкращий варіант — тому важливо писати чіткі, конкретні описи інструментів.* ### Виконання [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot автоматично підключає декларативний інтерфейс `@AiService` з усіма зареєстрованими інструментами, а LangChain4j виконує виклики інструментів автоматично. За лаштунками повний виклик інструменту проходить через шість стадій — від запитання користувача природною мовою до відповіді також природною мовою: +Spring Boot автоматично під’єднує декларативний інтерфейс `@AiService` з усіма зареєстрованими інструментами, а LangChain4j виконує виклики інструментів автоматично. За лаштунками повний виклик інструменту проходить через шість етапів — від природномовного питання користувача і назад до природної відповіді: -Потік виклику інструменту +Потік виклику інструментів -*Повний потік — користувач ставить питання, модель обирає інструмент, LangChain4j його виконує, а модель вкладає результат у природну відповідь.* +*Повний цикл — користувач ставить питання, модель обирає інструмент, LangChain4j виконує його, а модель вплітає результат у відповідь природною мовою.* -Якщо ви запускали [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) у Модулі 00, ви вже бачили цей патерн у дії — інструменти калькулятора викликались так само. Нижче діаграма послідовності показує, що саме відбувалось “під капотом” того демо: +За лаштунками `AiServices` запускає той самий цикл виклику інструменту для будь-якого інструменту — тут показано на прикладі простого `Calculator`. Послідовна діаграма нижче показує, що саме відбувається в процесі: -Діаграма послідовності виклику інструменту +Діаграма послідовності виклику інструментів -*Цикл виклику інструменту в демо Quick Start — `AiServices` надсилає повідомлення і схеми інструментів LLM, LLM відповідає викликом функції як `add(42, 58)`, LangChain4j локально виконує метод `Calculator` і повертає результат для остаточної відповіді.* +*Цикл виклику інструменту — `AiServices` надсилає повідомлення і схеми інструментів до LLM, LLM відповідає викликом функції на кшталт `add(42, 58)`, LangChain4j локально виконує метод `Calculator` і повертає результат для фінальної відповіді.* > **🤖 Спробуйте з [GitHub Copilot](https://github.com/features/copilot) Chat:** Відкрийте [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) і запитайте: -> - "Як працює патерн ReAct і чому він ефективний для AI агентів?" +> - "Як працює патерн ReAct і чому він ефективний для AI-агентів?" > - "Як агент вирішує, який інструмент використовувати і в якому порядку?" -> - "Що відбувається, якщо виконання інструменту не вдається — як надійно обробляти помилки?" +> - "Що станеться, якщо виконання інструмента не вдалося — як надійно обробляти помилки?" ### Генерація відповіді -Модель отримує дані про погоду і форматує їх у відповідь природною мовою для користувача. +Модель отримує дані про погоду і форматує їх у природномовну відповідь для користувача. -### Архітектура: Автовключення Spring Boot +### Архітектура: Spring Boot Auto-Wiring -Цей модуль використовує інтеграцію LangChain4j зі Spring Boot через декларативні інтерфейси `@AiService`. Під час запуску Spring Boot знаходить кожен `@Component`, що містить методи з `@Tool`, ваш `ChatModel` бін і `ChatMemoryProvider` — потім зв’язує їх у єдиний інтерфейс `Assistant` без жодного шаблонного коду. +Цей модуль використовує інтеграцію LangChain4j зі Spring Boot з декларативними інтерфейсами `@AiService`. При запуску Spring Boot знаходить кожен `@Component`, який містить методи з `@Tool`, ваш `ChatModel` bean і `ChatMemoryProvider` — потім об’єднує їх у єдиний інтерфейс `Assistant` без жодного шаблонного коду. -Архітектура автовключення Spring Boot +Архітектура Spring Boot Auto-Wiring -*Інтерфейс @AiService об’єднує ChatModel, компоненти інструментів і провайдер пам’яті — Spring Boot автоматично керує всіма підключеннями.* +*Інтерфейс @AiService зв’язує ChatModel, компоненти інструментів і провайдера пам’яті — Spring Boot автоматично керує їх підключенням.* -Ось повний життєвий цикл запиту у вигляді діаграми послідовності — від HTTP-запиту через контролер, сервіс та автопідключений проксі аж до виконання інструменту і назад: +Ось повний життєвий цикл запиту у вигляді послідовності — від HTTP-запиту через контролер, сервіс і автоматично підключений проксі аж до виконання інструменту і повернення: -Діаграма послідовності виклику інструменту Spring Boot +Послідовність виклику інструментів у Spring Boot -*Повний життєвий цикл запиту Spring Boot — HTTP-запит проходить через контролер і сервіс до автопідключеного проксі Assistant, який автоматично оркеструє виклики LLM і інструментів.* +*Повний життєвий цикл запиту в Spring Boot — HTTP-запит проходить через контролер і сервіс до проксі Assistant, який керує LLM і викликами інструментів автоматично.* Основні переваги цього підходу: -- **Автовключення Spring Boot** — ChatModel і інструменти автоматично інжектяться -- **Патерн @MemoryId** — Автоматичне управління пам’яттю на основі сеансів -- **Одна інстанція** — Assistant створюється один раз і повторно використовується для кращої продуктивності -- **Типобезпечне виконання** — виклики Java методів напряму з конвертацією типів -- **Керування багатокроковими діалогами** — автоматичне оброблення ланцюгів інструментів -- **Жодного шаблонного коду** — не потрібно вручну викликати `AiServices.builder()` чи керувати хеш-мапами пам’яті +- **Spring Boot auto-wiring** — ChatModel та інструменти автоматично підключаються +- **Патерн @MemoryId** — автоматичне керування пам’яттю на основі сесій +- **Один екземпляр** — Assistant створюється один раз і використовується повторно для кращої продуктивності +- **Безпечне виконання за типами** — Java-методи викликаються напряму з конвертацією типів +- **Багатокрокова оркестрація** — автоматично керує ланцюжком інструментів +- **Жодного шаблонного коду** — не потрібно вручну викликати `AiServices.builder()` або управляти HashMap пам’яті -Альтернативні підходи (ручний `AiServices.builder()`) потребують більше коду і не дають переваг Spring Boot інтеграції. +Альтернативні підходи (ручний `AiServices.builder()`) вимагають більше коду і не дають переваг інтеграції зі Spring Boot. ## Ланцюжок інструментів -**Ланцюг інструментів** — справжня потужність агентів на основі інструментів виявляється, коли одне питання вимагає кількох інструментів. Запитайте "Яка погода в Сіетлі у Фаренгейтах?" і агент автоматично створює ланцюжок із двох інструментів: спочатку викликає `getCurrentWeather` для отримання температури в Цельсіях, потім передає значення у `celsiusToFahrenheit` для перетворення — і все це за один хід розмови. +**Ланцюжок інструментів** — справжня сила агентів на основі інструментів проявляється, коли одне питання потребує кілька інструментів. Запитайте "Яка погода в Сіетлі за Фаренгейтом?", і агент автоматично об’єднає два інструменти: спочатку викликає `getCurrentWeather` для отримання температури у Цельсіях, потім передає це значення у `celsiusToFahrenheit` для конвертації — все в одному ходу розмови. Приклад ланцюжка інструментів -*Ланцюжок інструментів у дії — агент спочатку викликає getCurrentWeather, потім передає результат у celsiusToFahrenheit і формує об’єднану відповідь.* +*Ланцюжок інструментів у дії — агент спершу викликає getCurrentWeather, потім передає результат у Цельсіях до celsiusToFahrenheit, і надає комбіновану відповідь.* -**Гарна обробка помилок** — запитайте погоду у місті, якого немає у макетних даних. Інструмент повертає повідомлення про помилку, і AI пояснює, що не може допомогти, замість того щоб аварійно завершитись. Інструменти виходять із ладу безпечно. Нижче наведена діаграма, що порівнює два підходи — з належною обробкою помилок агент ловить виняток і дає корисну відповідь, а без неї уся програма падає: +**Гармонійне оброблення помилок** — Запитайте погоду в місті, якого немає у мок-даних. Інструмент повертає повідомлення про помилку, і AI пояснює, що не може допомогти, замість того щоб аварійно завершитись. Інструменти не падають. Нижче діаграма порівнює два підходи — з коректною обробкою помилок агент ловить виняток і відповідає корисно, інакше весь додаток падає: Потік обробки помилок -*Коли інструмент виходить з ладу, агент ловить помилку і відповідає з поясненням замість аварійного завершення.* +*Якщо інструмент не вдається, агент ловить помилку і відповідає з допоміжним поясненням замість аварії.* -Це відбувається за один хід розмови. Агент автономно організовує кілька викликів інструментів. +Це відбувається за один хід розмови. Агент автономно оркеструє кілька викликів інструментів. -## Запуск програми +## Запустіть додаток **Перевірка розгортання:** -Переконайтеся, що файл `.env` існує в кореневій теці з обліковими даними Azure (створений під час Модуля 01). Запустіть цю команду у теці модуля (`04-tools/`): +Переконайтеся, що файл `.env` існує у кореневій директорії з обліковими даними Azure (створений у Модулі 01). Запустіть це з директорії модуля (`04-tools/`): **Bash:** ```bash @@ -202,37 +202,37 @@ cat ../.env # Має показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLO **PowerShell:** ```powershell -Get-Content ..\.env # Повинно показувати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # Повинно відображати AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` -**Запустіть програму:** +**Запустіть додаток:** -> **Примітка:** Якщо ви вже запускали всі програми за допомогою `./start-all.sh` у кореневій теці (як описано в Модулі 01), цей модуль вже працює на порту 8084. Ви можете не виконувати команди запуску нижче і одразу перейти за адресою http://localhost:8084. +> **Примітка:** Якщо ви вже запускали всі додатки за допомогою `./start-all.sh` з кореневої директорії (як описано у Модулі 01), цей модуль вже працює на порту 8084. Ви можете пропустити команди запуску нижче і перейти безпосередньо на http://localhost:8084. -**Варіант 1: Використання Spring Boot Dashboard (рекомендовано для користувачів VS Code)** +**Опція 1: Використання Spring Boot Dashboard (Рекомендується для користувачів VS Code)** -Dev контейнер включає розширення Spring Boot Dashboard, яке надає візуальний інтерфейс для керування всіма Spring Boot застосунками. Його можна знайти у Activity Bar зліва у VS Code (шукайте іконку Spring Boot). +Dev-контейнер включає розширення Spring Boot Dashboard, що надає візуальний інтерфейс для керування всіма Spring Boot додатками. Знайти його можна у панелі активності зліва у VS Code (значок Spring Boot). За допомогою Spring Boot Dashboard ви можете: -- Побачити всі доступні Spring Boot застосунки у робочому просторі -- Запускати/зупиняти застосунки одним кліком -- Переглядати логи застосунку у реальному часі -- Моніторити статус застосунку -Просто натисніть кнопку відтворення поруч із «tools», щоб запустити цей модуль, або запустіть всі модулі одразу. +- Переглядати всі доступні Spring Boot додатки у робочій області +- Запускати/зупиняти додатки одним кліком +- Переглядати логи додатків у реальному часі +- Моніторити статус додатків -Ось як виглядає панель Spring Boot Dashboard у VS Code: +Просто натисніть кнопку запуску поряд із "tools" для запуску цього модуля або запустіть усі модулі одночасно. -Spring Boot Dashboard +Ось як виглядає Spring Boot Dashboard у VS Code: +Панель керування Spring Boot -*Панель Spring Boot Dashboard у VS Code — запуск, зупинка та моніторинг усіх модулів з одного місця* +*Панель керування Spring Boot у VS Code — запуск, зупинка та моніторинг усіх модулів з одного місця* **Варіант 2: Використання shell-скриптів** -Запустіть усі вебзастосунки (модулі 01-04): +Запустіть усі веб-додатки (модулі 01-04): **Bash:** ```bash -cd .. # З кореневої директорії +cd .. # З кореневого каталогу ./start-all.sh ``` @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Обидва скрипти автоматично завантажують змінні середовища з кореневого файлу `.env` і побудують JAR-файли, якщо вони не існують. +Обидва скрипти автоматично завантажують змінні оточення з кореневого файлу `.env` та створять JAR-файли, якщо їх немає. -> **Примітка:** Якщо ви хочете вручну зібрати всі модулі перед запуском: +> **Примітка:** Якщо ви хочете зібрати всі модулі вручну перед запуском: > > **Bash:** > ```bash @@ -272,7 +272,7 @@ cd 04-tools > mvn clean package -DskipTests > ``` -Відкрийте http://localhost:8084 у вашому браузері. +Відкрийте у браузері http://localhost:8084. **Щоб зупинити:** @@ -285,103 +285,103 @@ cd .. && ./stop-all.sh # Всі модулі **PowerShell:** ```powershell -.\stop.ps1 # Лише цей модуль +.\stop.ps1 # Тільки цей модуль # Або -cd ..; .\stop-all.ps1 # Усі модулі +cd ..; .\stop-all.ps1 # Всі модулі ``` -## Використання застосунку +## Використання додатку -Застосунок надає веб-інтерфейс, де ви можете взаємодіяти з AI-агентом, який має доступ до інструментів погоди та конвертації температури. Ось як виглядає інтерфейс — він містить приклади швидкого старту та панель чату для надсилання запитів: +Додаток надає веб-інтерфейс, де ви можете взаємодіяти з AI-агентом, який має доступ до інструментів погоди та конвертації температури. Ось як виглядає інтерфейс — він містить швидкі приклади запуску та панель чату для надсилання запитів: -AI Agent Tools Interface +Інтерфейс інструментів AI-агента -*Інтерфейс AI Agent Tools - швидкі приклади та чат для взаємодії з інструментами* +*Інтерфейс інструментів AI-агента - швидкі приклади та чат для взаємодії з інструментами* ### Спробуйте просте використання інструменту -Почніть з простого запиту: «Перетворити 100 градусів за Фаренгейтом у Цельсій». Агент визначає, що йому потрібен інструмент конвертації температури, викликає його з потрібними параметрами та повертає результат. Зверніть увагу, наскільки це природньо — ви не вказували, який інструмент використовувати чи як його викликати. +Почніть з простого запиту: «Перетвори 100 градусів за Фаренгейтом у Цельсій». Агент розуміє, що потрібен інструмент конвертації температури, викликає його з правильними параметрами і повертає результат. Зверніть увагу, наскільки це природно — ви не вказували, який інструмент використовувати або як його викликати. -### Перевірте ланцюжок інструментів +### Тестуйте ланцюжок інструментів -Тепер спробуйте щось складніше: «Яка погода в Сіетлі та конвертуй її у Фаренгейти?» Спостерігайте, як агент крок за кроком виконує завдання. Спочатку він отримує погоду (яка повертається в Цельсіях), розуміє, що потрібно конвертувати у Фаренгейти, викликає інструмент конвертації і об’єднує обидва результати в одну відповідь. +Тепер спробуйте щось складніше: «Яка погода у Сіетлі та перетвори її у Фаренгейт?» Спостерігайте, як агент виконує це поетапно. Спочатку він отримує погоду (у Цельсіях), розуміє, що потрібно конвертувати у Фаренгейт, викликає інструмент конвертації і об’єднує обидва результати в одну відповідь. ### Перегляньте хід розмови -Інтерфейс чату зберігає історію розмови, що дозволяє вести багатокрокові взаємодії. Ви бачите всі попередні запити та відповіді, що полегшує відстеження розмови та розуміння, як агент будує контекст протягом кількох обмінів. +Інтерфейс чату зберігає історію розмови, що дозволяє вести мультитурові взаємодії. Ви можете бачити всі попередні запити та відповіді, що полегшує відстеження бесіди і розуміння того, як агент будує контекст протягом кількох обмінів. -Conversation with Multiple Tool Calls +Розмова з кількома викликами інструментів -*Багатокрокова розмова, що демонструє прості конверсії, запити погоди і ланцюг викликів інструментів* +*Мультитурова розмова, що показує прості конвертації, пошук погоди та ланцюжок інструментів* ### Експериментуйте з різними запитами -Спробуйте різні комбінації: -- Запити погоди: «Яка погода в Токіо?» -- Конвертації температур: «Що таке 25°C у Кельвінах?» -- Комбіновані запити: «Перевір погоду в Парижі і скажи, чи вище там 20°C» +Спробуйте різні варіанти: +- Пошук погоди: «Яка погода в Токіо?» +- Конвертація температур: «Що таке 25°C у Кельвінах?» +- Комбіновані запити: «Перевір погоду в Парижі та скажи, чи більше 20°C» -Зверніть увагу, як агент інтерпретує природну мову і зіставляє її з потрібними викликами інструментів. +Зверніть увагу, як агент інтерпретує природну мову і переводить її у відповідні виклики інструментів. -## Ключові поняття +## Ключові концепції -### Патерн ReAct (Роздум і дія) +### Патерн ReAct (Обґрунтування та дія) -Агент чергує роздум (вирішення, що робити) та дію (використання інструментів). Цей патерн дозволяє автономно вирішувати завдання, а не просто виконувати інструкції. +Агент чергує обґрунтування (вирішує, що робити) та дія (використання інструментів). Цей патерн дозволяє автономне розв’язання задач, а не просто відповідь на інструкції. -### Опис інструментів має значення +### Важливість описів інструментів -Якість описів інструментів безпосередньо впливає на те, як агент їх використовує. Чіткі, конкретні описи допомагають моделі зрозуміти, коли і як викликати кожен інструмент. +Якість описів інструментів безпосередньо впливає на те, наскільки добре агент їх використовує. Чіткі, конкретні описи допомагають моделі розуміти, коли і як викликати кожен інструмент. -### Керування сесіями +### Керування сесією -Анотація `@MemoryId` забезпечує автоматичне керування пам’яттю на основі сесії. Кожен ID сесії отримує власний екземпляр `ChatMemory`, який керує бін `ChatMemoryProvider`, тому кілька користувачів можуть одночасно взаємодіяти з агентом без змішування розмов. Наступна діаграма показує, як кілька користувачів направляються до ізольованих сховищ пам’яті на основі їхніх ID сесій: +Анотація `@MemoryId` дозволяє автоматичне керування пам’яттю на основі сесій. Кожне ID сесії отримує окремий екземпляр `ChatMemory`, який керується компонентом `ChatMemoryProvider`, отже кілька користувачів можуть спілкуватися з агентом одночасно, не змішуючи свої розмови. Наступна діаграма показує, як кілька користувачів спрямовуються до ізольованих сховищ пам’яті за ID сесій: -Session Management with @MemoryId +Керування сесією з @MemoryId -*Кожен ID сесії відображається на ізольовану історію розмов — користувачі ніколи не бачать повідомлення один одного.* +*Кожне ID сесії відповідає ізольованій історії розмов — користувачі ніколи не бачать повідомлення один одного.* ### Обробка помилок -Інструменти можуть виходити з ладу — API таймаутяться, параметри можуть бути некоректними, сторонні сервіси відмовляють. Промислові агенти потребують обробки помилок, щоб модель могла пояснювати проблеми або пробувати альтернативи замість аварійного завершення роботи застосунку. Якщо інструмент генерує виняток, LangChain4j перехоплює його і передає повідомлення про помилку назад моделі, яка потім може пояснити проблему натуральною мовою. +Інструменти можуть давати збій — API можуть таймаутитися, параметри можуть бути недійсними, зовнішні сервіси можуть бути недоступні. Для продакшн-агентів потрібна обробка помилок, щоб модель могла пояснювати проблеми або шукати альтернативи замість краху всього додатку. Коли інструмент викидає виняток, LangChain4j ловить його та передає текст помилки назад моделі, яка тоді може пояснити проблему природною мовою. ## Доступні інструменти -Нижче наведена діаграма показує широку екосистему інструментів, які можна створювати. Цей модуль демонструє інструменти погоди та температури, але той самий патерн `@Tool` працює для будь-якого методу Java — від запитів до баз даних до обробки платежів. +Нижче наведена діаграма, що демонструє широку екосистему інструментів, які можна створити. Цей модуль показує інструменти для погоди і температури, але той самий патерн `@Tool` працює для будь-якого Java-методу — від запитів до баз даних до обробки платежів. -Tool Ecosystem +Екосистема інструментів -*Будь-який метод Java з анотацією @Tool стає доступним для AI — патерн розширюється на бази даних, API, електронну пошту, роботу з файлами та інше.* +*Будь-який Java-метод із анотацією @Tool стає доступним AI — патерн розширюється до баз даних, API, електронної пошти, файлових операцій та іншого.* -## Коли використовувати агентів із інструментами +## Коли використовувати агентів на основі інструментів -Не кожен запит потребує інструментів. Рішення зводиться до того, чи потрібно AI взаємодіяти із зовнішніми системами, чи він може відповідати на основі власних знань. Наступне керівництво узагальнює, коли інструменти додають цінність, а коли вони непотрібні: +Не кожен запит потребує інструментів. Рішення залежить від того, чи потрібно AI взаємодіяти із зовнішніми системами або він може відповідати на основі власних знань. Наступний посібник узагальнює, коли інструменти приносять користь, а коли вони зайві: -When to Use Tools +Коли використовувати інструменти -*Швидке керівництво з прийняття рішення — інструменти потрібні для актуальних даних, обчислень та дій; загальні знання та творчі завдання не потребують їх.* +*Швидкий посібник для рішень — інструменти потрібні для даних у реальному часі, обчислень та дій; загальні знання і творчі завдання не потребують їх.* -## Інструменти vs RAG +## Інструменти проти RAG -Модулі 03 і 04 розширюють можливості AI, але принципово різними способами. RAG надає моделі доступ до **знань** через пошук документів. Інструменти надають моделі можливість виконувати **дії** через виклики функцій. Нижче наведена діаграма, що порівнює ці два підходи бок о бок — від того, як працює кожен робочий процес, до компромісів між ними: +Модулі 03 і 04 розширюють можливості AI, але принципово по-різному. RAG надає моделі доступ до **знань** через вивантаження документів. Інструменти дають моделі можливість виконувати **дії** через виклики функцій. Діаграма нижче порівнює ці два підходи бок о бок — від того, як працює кожен робочий процес, до компромісів між ними: -Tools vs RAG Comparison +Порівняння інструментів та RAG -*RAG витягує інформацію зі статичних документів — інструменти виконують дії та отримують динамічні, актуальні дані. Багато промислових систем поєднують обидва підходи.* +*RAG отримує інформацію зі статичних документів — Інструменти виконують дії і отримують динамічні, актуальні дані. Багато систем у продакшені поєднують обидва.* -На практиці багато промислових систем комбінують обидва підходи: RAG для підкріплення відповідей документацією, та інструменти для отримання живих даних або виконання операцій. +На практиці багато продакшн-систем поєднують обидва підходи: RAG для підкріплення відповідей вашою документацією, а Інструменти — для отримання живих даних або виконання операцій. ## Наступні кроки -**Наступний Модуль:** [05-mcp - Протокол контексту моделі (MCP)](../05-mcp/README.md) +**Наступний модуль:** [05-mcp - Протокол контексту моделі (MCP)](../05-mcp/README.md) --- -**Навігація:** [← Попередній: Модуль 03 - RAG](../03-rag/README.md) | [Назад до головної](../README.md) | [Наступний: Модуль 05 - MCP →](../05-mcp/README.md) +**Навігація:** [← Попередній: Модуль 03 - RAG](../03-rag/README.md) | [Назад до головної](../README.md) | [Вперед: Модуль 05 - MCP →](../05-mcp/README.md) --- **Відмова від відповідальності**: -Цей документ було перекладено за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми докладаємо зусиль для забезпечення точності, зверніть увагу, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом інформації. Для критично важливої інформації рекомендується звертатися до професійного людського перекладу. Ми не несемо відповідальності за будь-які непорозуміння або неправильне тлумачення, що виникли в результаті використання цього перекладу. +Цей документ було перекладено за допомогою сервісу штучного інтелекту для перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. \ No newline at end of file diff --git a/translations/uk/README.md b/translations/uk/README.md index 64e3eefec..b1b4a9707 100644 --- a/translations/uk/README.md +++ b/translations/uk/README.md @@ -2,18 +2,18 @@ # LangChain4j для початківців -Курс зі створення AI-застосунків з LangChain4j та Azure OpenAI GPT-5.2, від базового чату до AI агентів. +Курс зі створення AI-додатків з LangChain4j та Azure OpenAI GPT-5.2, від базового чату до AI агентів. -### 🌐 Підтримка багатьох мов +### 🌐 Підтримка кількох мов -#### Підтримується через GitHub Action (автоматично та завжди актуально) +#### Підтримується через GitHub Action (Автоматично та завжди актуально) -[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](./README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) +[Арабська](../ar/README.md) | [Бенгальська](../bn/README.md) | [Болгарська](../bg/README.md) | [Бирманська (М’янма)](../my/README.md) | [Китайська (спрощена)](../zh-CN/README.md) | [Китайська (традиційна, Гонконг)](../zh-HK/README.md) | [Китайська (традиційна, Макао)](../zh-MO/README.md) | [Китайська (традиційна, Тайвань)](../zh-TW/README.md) | [Хорватська](../hr/README.md) | [Чеська](../cs/README.md) | [Данська](../da/README.md) | [Голландська](../nl/README.md) | [Естонська](../et/README.md) | [Фінська](../fi/README.md) | [Французька](../fr/README.md) | [Німецька](../de/README.md) | [Грецька](../el/README.md) | [Іврит](../he/README.md) | [Гінді](../hi/README.md) | [Угорська](../hu/README.md) | [Індонезійська](../id/README.md) | [Італійська](../it/README.md) | [Японська](../ja/README.md) | [Каннада](../kn/README.md) | [Кхмер](../km/README.md) | [Корейська](../ko/README.md) | [Литовська](../lt/README.md) | [Малайська](../ms/README.md) | [Малаялам](../ml/README.md) | [Мараті](../mr/README.md) | [Неапалі](../ne/README.md) | [Нігерійський Піджин](../pcm/README.md) | [Норвезька](../no/README.md) | [Перська (фарсі)](../fa/README.md) | [Польська](../pl/README.md) | [Португальська (Бразилія)](../pt-BR/README.md) | [Португальська (Португалія)](../pt-PT/README.md) | [Панджабі (гурмукхі)](../pa/README.md) | [Румунська](../ro/README.md) | [Російська](../ru/README.md) | [Сербська (кирилиця)](../sr/README.md) | [Словацька](../sk/README.md) | [Словенська](../sl/README.md) | [Іспанська](../es/README.md) | [Свахілі](../sw/README.md) | [Шведська](../sv/README.md) | [Тагальська (філіппінська)](../tl/README.md) | [Тамільська](../ta/README.md) | [Телугу](../te/README.md) | [Тайська](../th/README.md) | [Турецька](../tr/README.md) | [Українська](./README.md) | [Урду](../ur/README.md) | [В’єтнамська](../vi/README.md) > **Віддаєте перевагу клонувати локально?** > -> Цей репозиторій включає понад 50 перекладів, що суттєво збільшує розмір завантаження. Щоб клонувати без перекладів, використовуйте sparse checkout: +> Цей репозиторій містить понад 50 перекладів, що значно збільшує розмір завантаження. Щоб клонувати без перекладів, використовуйте sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,122 +29,122 @@ > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Це дасть вам все необхідне для проходження курсу з набагато швидшим завантаженням. +> Це дасть вам усе необхідне для проходження курсу з набагато швидшим завантаженням. ## Зміст -1. [Швидкий старт](00-quick-start/README.md) — Почніть з LangChain4j -2. [Вступ](01-introduction/README.md) — Вивчіть основи LangChain4j -3. [Інженерія підказок](02-prompt-engineering/README.md) — Опануйте ефективний дизайн підказок -4. [RAG (Генерація з пошуком)](03-rag/README.md) — Створюйте інтелектуальні системи на основі знань -5. [Інструменти](04-tools/README.md) — Інтегруйте зовнішні інструменти та простих асистентів -6. [MCP (Протокол контексту моделі)](05-mcp/README.md) — Працюйте з MCP та агентними модулями +1. [Вступ](01-introduction/README.md) - Вивчайте основи LangChain4j +2. [Проєктування підказок](02-prompt-engineering/README.md) - Опануйте ефективний дизайн підказок +3. [RAG (Підсилене пошуком покоління)](03-rag/README.md) - Створюйте інтелектуальні системи на основі знань +4. [Інструменти](04-tools/README.md) - Інтегруйте зовнішні інструменти та прості помічники +5. [MCP (Протокол контексту моделі)](05-mcp/README.md) - Працюйте з Протоколом контексту моделі (MCP) та агентними модулями ### Відеоогляди -Кожен модуль має супровідну пряму сесію, де ми крок за кроком проходимо концепції та код. +Кожен модуль має супровідну живу сесію, де ми крок за кроком розглядаємо концепції та код. | Модуль | Відео | |--------|-------| | 01 - Вступ | [Початок роботи з LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - Інженерія підказок | [Інженерія підказок з LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | +| 02 - Проєктування підказок | [Проєктування підказок з LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG з LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Інструменти & 05 - MCP | [AI Агенти з інструментами і MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Інструменти & 05 - MCP | [AI агенти з інструментами та MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## Навчальний шлях -**Новачок в LangChain4j?** Перегляньте [Глосарій](docs/GLOSSARY.md) для визначень ключових термінів і понять. +**Новачок у LangChain4j?** Ознайомтеся з [Глосарієм](docs/GLOSSARY.md) для визначень основних термінів і понять. -> **Швидкий старт** +> **Швидкий початок** -1. Форкніть цей репозиторій у свій акаунт GitHub -2. Виберіть **Code** → вкладка **Codespaces** → **...** → **New with options...** -3. Використовуйте налаштування за замовчуванням – це вибере контейнер для розробки, створений для цього курсу +1. Форкніть цей репозиторій у свій обліковий запис GitHub +2. Натисніть **Code** → вкладка **Codespaces** → **...** → **Новий з опціями...** +3. Використовуйте значення за замовчуванням – це вибере контейнер розробника, створений для цього курсу 4. Натисніть **Create codespace** -5. Чекайте 5-10 хвилин, поки середовище буде готове -6. Перейдіть безпосередньо до [Швидкого старту](./00-quick-start/README.md), щоб почати! +5. Почекайте 5-10 хвилин, доки середовище буде готове +6. Одразу переходьте до [Вступу](./01-introduction/README.md) для старту! -Після завершення модулів ознайомтеся з [Посібником з тестування](docs/TESTING.md), щоб побачити концепції тестування LangChain4j у дії. +Після проходження модулів вивчіть [Посібник з тестування](docs/TESTING.md), щоб побачити концепції тестування LangChain4j у дії. -> **Примітка:** Це навчання використовує як GitHub Models, так і Azure OpenAI. Модуль [Швидкий старт](00-quick-start/README.md) використовує GitHub Models (підписка Azure не потрібна), а модулі 1-5 використовують Azure OpenAI. Почніть із [БЕЗКОШТОВНОГО акаунту Azure](https://aka.ms/azure-free-account), якщо у вас його немає. +> **Примітка:** це тренування використовує Azure OpenAI. Почніть з [БЕЗКОШТОВНОГО облікового запису Azure](https://aka.ms/azure-free-account), якщо у вас його немає. ## Навчання з GitHub Copilot -Щоб швидко почати писати код, відкрийте цей проєкт у GitHub Codespace або у вашому локальному IDE з наданим devcontainer. Devcontainer, який використовується в цьому курсі, вже налаштований з GitHub Copilot для AI парного програмування. +Щоб швидко почати програмувати, відкрийте цей проєкт у GitHub Codespace або вашому локальному IDE з наданим devcontainer. Devcontainer, що використовується у цьому курсі, попередньо налаштований з GitHub Copilot для AI-парного програмування. -Кожен приклад коду включає запропоновані питання, які ви можете задати GitHub Copilot, щоб поглибити розуміння. Шукайте підказки 💡/🤖 у: +Кожен приклад коду містить запропоновані питання, які ви можете задати GitHub Copilot, щоб поглибити розуміння. Шукайте підказки 💡/🤖 у: -- **Заголовках Java-файлів** — питання, специфічні для кожного прикладу -- **README модулів** — підказки для дослідження після прикладів коду +- **Заголовках Java-файлів** - Питання, специфічні для кожного прикладу +- **README модулів** - Пропозиції для дослідження після прикладів коду -**Як використовувати:** Відкрийте будь-який код та поставте Copilot запропоновані питання. Він має повний контекст коду і може пояснювати, розширювати та пропонувати альтернативи. +**Як користуватися:** Відкрийте будь-який файл коду і задайте Copilot запропоновані питання. Він має повний контекст кодової бази і може пояснювати, розширювати і пропонувати альтернативи. -Хочете дізнатись більше? Перегляньте [Copilot для AI парного програмування](https://aka.ms/GitHubCopilotAI). +Хочете дізнатися більше? Перегляньте [Copilot для AI-парного програмування](https://aka.ms/GitHubCopilotAI). ## Додаткові ресурси ### LangChain -[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j для початківців](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js для початківців](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain для початківців](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents -[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Агенти +[![AZD для початківців](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI для початківців](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP для початківців](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI агенти для початківців](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Generative AI Series -[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Серія Generative AI +[![Генеративний AI для початківців](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Генеративний AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Генеративний AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Генеративний AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Core Learning -[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +### Основи навчання +[![Машинне навчання для початківців](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science для початківців](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI для початківців](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Кібербезпека для початківців](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Веб-розробка для початківців](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT для початківців](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![XR Розробка для початківців](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Серія Copilot -[![Copilot для AI парного програмування](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot для C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Пригоди Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Отримання допомоги -Якщо ви застрягли або маєте питання щодо створення AI-додатків, приєднуйтеся до: +Якщо ви застрягли або маєте запитання щодо створення додатків зі штучним інтелектом, приєднуйтесь до: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -Якщо у вас є відгуки про продукт або ви зіткнулися з помилками під час розробки, відвідайте: +Якщо у вас є відгуки про продукт або помилки під час розробки, відвідайте: [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## Ліцензія -Ліцензія MIT - див. файл [LICENSE](../../LICENSE) для деталей. +Ліцензія MIT — дивіться файл [LICENSE](../../LICENSE) для деталей. --- **Відмова від відповідальності**: -Цей документ був перекладений за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматизовані переклади можуть містити помилки або неточності. Оригінальний документ на його рідній мові слід вважати авторитетним джерелом. Для критичної інформації рекомендується звертатися до професійного людського перекладу. Ми не несемо відповідальність за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. +Цей документ було перекладено за допомогою сервісу штучного інтелекту для перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. \ No newline at end of file diff --git a/translations/uk/docs/GLOSSARY.md b/translations/uk/docs/GLOSSARY.md index 1c3565f68..b09d25f36 100644 --- a/translations/uk/docs/GLOSSARY.md +++ b/translations/uk/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## Зміст -- [Основні поняття](../../../docs) -- [Компоненти LangChain4j](../../../docs) -- [Поняття AI/ML](../../../docs) -- [Охоронні Механізми](../../../docs) -- [Проєктування промптів](../../../docs) -- [RAG (генерація з доповненням пошуком)](../../../docs) -- [Агенти та Інструменти](../../../docs) -- [Модуль Агента](../../../docs) -- [Протокол Контексту Моделі (MCP)](../../../docs) -- [Сервіси Azure](../../../docs) -- [Тестування та Розробка](../../../docs) - -Швидкий довідник термінів і понять, що використовуються протягом курсу. +- [Основні поняття](#основні-поняття) +- [Компоненти LangChain4j](#компоненти-langchain4j) +- [Поняття ШІ/МЛ](#поняття-шімл) +- [Охоронні заходи](#охоронні-заходи) +- [Проєктування промптів](#prompt-engineering---module-02) +- [RAG (Retrieval-Augmented Generation)](#rag-retrieval-augmented-generation---module-03) +- [Агенти та інструменти](#agents-and-tools---module-04) +- [Агентний модуль](#agentic-module---module-05) +- [Протокол контексту моделі (MCP)](#model-context-protocol-mcp---module-05) +- [Сервіси Azure](#azure-services---module-01) +- [Тестування та розробка](#testing-and-development---testing-guide) + +Швидке посилання на терміни та поняття, які використовуються впродовж курсу. ## Основні поняття -**AI Agent** – Система, що використовує ШІ для автономного мислення та дій. [Модуль 04](../04-tools/README.md) +**AI Agent** - Система, що використовує ШІ для автономного логічного мислення та дій. [Модуль 04](../04-tools/README.md) -**Chain** – Послідовність операцій, де вихід є вхідним для наступного кроку. +**Chain** - Послідовність операцій, де вихід одного кроку стає вхідними даними для наступного. -**Chunking** – Розбиття документів на менші частини. Типово: 300-500 токенів з перекриттям. [Модуль 03](../03-rag/README.md) +**Chunking** - Розбивка документів на менші частини. Типово: 300-500 токенів з перекриттям. [Модуль 03](../03-rag/README.md) -**Context Window** – Максимальна кількість токенів, які модель може обробити. GPT-5.2: 400К токенів (до 272К вхідних, 128К вихідних). +**Context Window** - Максимальна кількість токенів, які модель може обробляти. GPT-5.2: 400K токенів (до 272K на вхід, 128K на вихід). -**Embeddings** – Числові вектори, що представляють зміст тексту. [Модуль 03](../03-rag/README.md) +**Embeddings** - Числові вектори, що представляють значення тексту. [Модуль 03](../03-rag/README.md) -**Function Calling** – Модель генерує структуровані запити для виклику зовнішніх функцій. [Модуль 04](../04-tools/README.md) +**Function Calling** - Модель генерує структуровані запити для виклику зовнішніх функцій. [Модуль 04](../04-tools/README.md) -**Hallucination** – Коли моделі генерують некоректну, але правдоподібну інформацію. +**Hallucination** - Вироблення моделлю неправдивої, але правдоподібної інформації. -**Prompt** – Текстовий вхід до мовної моделі. [Модуль 02](../02-prompt-engineering/README.md) +**Prompt** - Текстовий ввід для мовної моделі. [Модуль 02](../02-prompt-engineering/README.md) -**Semantic Search** – Пошук за значенням через embeddings, а не ключовими словами. [Модуль 03](../03-rag/README.md) +**Semantic Search** - Пошук за значенням з використанням embeddings, а не ключових слів. [Модуль 03](../03-rag/README.md) -**Stateful vs Stateless** – Stateless: без пам’яті. Stateful: зберігає історію розмови. [Модуль 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: без пам'яті. Stateful: зберігає історію розмови. [Модуль 01](../01-introduction/README.md) -**Tokens** – Основні текстові одиниці, які обробляють моделі. Впливають на вартість і обмеження. [Модуль 01](../01-introduction/README.md) +**Tokens** - Базові одиниці тексту, які обробляють моделі. Впливає на вартість і ліміти. [Модуль 01](../01-introduction/README.md) -**Tool Chaining** – Послідовне виконання інструментів, де вихід інформує наступний виклик. [Модуль 04](../04-tools/README.md) +**Tool Chaining** - Послідовне виконання інструментів, де вихід одного кроку інформує наступний виклик. [Модуль 04](../04-tools/README.md) ## Компоненти LangChain4j -**AiServices** – Створює типобезпечні інтерфейси AI-сервісів. +**AiServices** - Створює типобезпечні інтерфейси для AI-сервісів. -**OpenAiOfficialChatModel** – Єдиний клієнт для моделей OpenAI та Azure OpenAI. +**OpenAiOfficialChatModel** - Уніфікований клієнт для моделей OpenAI та Azure OpenAI. -**OpenAiOfficialEmbeddingModel** – Створює embeddings з використанням офіційного клієнта OpenAI (підтримує OpenAI і Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Створює embeddings за допомогою офіційного клієнта OpenAI (підтримує і OpenAI, і Azure OpenAI). -**ChatModel** – Основний інтерфейс для мовних моделей. +**ChatModel** - Основний інтерфейс для мовних моделей. -**ChatMemory** – Зберігає історію розмови. +**ChatMemory** - Зберігає історію розмов. -**ContentRetriever** – Знаходить релевантні частини документів для RAG. +**ContentRetriever** - Знаходить релевантні частини документів для RAG. -**DocumentSplitter** – Розбиває документи на шматки. +**DocumentSplitter** - Розбиває документи на частини. -**EmbeddingModel** – Конвертує текст у числові вектори. +**EmbeddingModel** - Перетворює текст у числові вектори. -**EmbeddingStore** – Зберігає та отримує embeddings. +**EmbeddingStore** - Зберігає та отримує embeddings. -**MessageWindowChatMemory** – Зберігає ковзаюче вікно останніх повідомлень. +**MessageWindowChatMemory** - Підтримує скользяче вікно з останніми повідомленнями. -**PromptTemplate** – Створює повторно використовувані промпти з заповнювачами `{{variable}}`. +**PromptTemplate** - Створює шаблони промптів з заповнювачами `{{variable}}`. -**TextSegment** – Текстовий фрагмент з метаданими. Використовується в RAG. +**TextSegment** - Фрагмент тексту з метаданими. Використовується в RAG. -**ToolExecutionRequest** – Представляє запит на виконання інструменту. +**ToolExecutionRequest** - Представляє запит на виконання інструменту. -**UserMessage / AiMessage / SystemMessage** – Типи повідомлень у розмові. +**UserMessage / AiMessage / SystemMessage** - Типи повідомлень у розмові. -## Поняття AI/ML +## Поняття ШІ/МЛ -**Few-Shot Learning** – Надання прикладів у промптах. [Модуль 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - Надання прикладів у промптах. [Модуль 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** – AI-моделі, навчені на великому обсязі тексту. +**Large Language Model (LLM)** - ШІ-моделі, навчанні на величезних обсягах тексту. -**Reasoning Effort** – Параметр GPT-5.2, що контролює глибину мислення. [Модуль 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - Параметр GPT-5.2, що керує глибиною мислення. [Модуль 02](../02-prompt-engineering/README.md) -**Temperature** – Контролює випадковість виходу. Низьке=детерміноване, високе=креативне. +**Temperature** - Контролює випадковість виходу. Низьке = детерміністичне, високе = креативне. -**Vector Database** – Спеціалізована база даних для embeddings. [Модуль 03](../03-rag/README.md) +**Vector Database** - Спеціалізована база даних для embeddings. [Модуль 03](../03-rag/README.md) -**Zero-Shot Learning** – Виконання завдань без прикладів. [Модуль 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - Виконання завдань без прикладів. [Модуль 02](../02-prompt-engineering/README.md) -## Охоронні Механізми - [Модуль 00](../00-quick-start/README.md) +## Охоронні заходи -**Defense in Depth** – Багаторівневий підхід безпеки, що поєднує охоронні механізми на рівні застосунку та фільтри безпеки провайдера. +**Defense in Depth** - Багаторівневий підхід безпеки, що поєднує програмні охоронні засоби з фільтрами безпеки провайдера. -**Hard Block** – Провайдер повертає помилку HTTP 400 за серйозні порушення контенту. +**Hard Block** - Провайдер видає HTTP 400 помилку за серйозні порушення контенту. -**InputGuardrail** – Інтерфейс LangChain4j для валідації користувацького вводу перед надсиланням до LLM. Зберігає кошти та затримку, блокуючи небезпечні промпти на ранньому етапі. +**InputGuardrail** - Інтерфейс LangChain4j для валідації користувацьких ввідних даних перед попаданням в LLM. Зберігає час і гроші, блокуючи шкідливі промпти на ранньому етапі. -**InputGuardrailResult** – Тип повернення результату валідації guardrail: `success()` або `fatal("причина")`. +**InputGuardrailResult** - Тип повернення для валідації guardrail: `success()` або `fatal("причина")`. -**OutputGuardrail** – Інтерфейс для валідації відповідей AI перед поверненням користувачам. +**OutputGuardrail** - Інтерфейс для валідації відповідей ШІ перед поверненням користувачу. -**Provider Safety Filters** – Вбудовані фільтри контенту від AI-провайдерів (наприклад, GitHub Models), які перехоплюють порушення на рівні API. +**Provider Safety Filters** - Вбудовані фільтри контенту від провайдерів ШІ (наприклад, Azure OpenAI), які виявляють порушення на рівні API. -**Soft Refusal** – Модель ввічливо відмовляється відповідати без генерації помилки. +**Soft Refusal** - Модель ввічливо відмовляється відповідати без викидання помилки. ## Проєктування промптів - [Модуль 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** – Крок за кроком міркування для підвищення точності. +**Chain-of-Thought** - Крок за кроком логічне мислення для кращої точності. -**Constrained Output** – Примусовий специфічний формат або структура. +**Constrained Output** - Вимога певного формату або структури. -**High Eagerness** – Шаблон GPT-5.2 для детального мислення. +**High Eagerness** - Шаблон GPT-5.2 для детального мислення. -**Low Eagerness** – Шаблон GPT-5.2 для швидких відповідей. +**Low Eagerness** - Шаблон GPT-5.2 для швидких відповідей. -**Multi-Turn Conversation** – Підтримка контексту між обмінами. +**Multi-Turn Conversation** - Підтримка контексту між обмінами. -**Role-Based Prompting** – Встановлення персоналії моделі через системні повідомлення. +**Role-Based Prompting** - Встановлення персонажу моделі через системні повідомлення. -**Self-Reflection** – Модель оцінює та покращує власний вихід. +**Self-Reflection** - Модель оцінює і покращує свій вивід. -**Structured Analysis** – Фіксована рамка оцінювання. +**Structured Analysis** - Фіксована рамка оцінки. -**Task Execution Pattern** – План → Виконати → Підсумувати. +**Task Execution Pattern** - Планувати → Виконувати → Підсумовувати. -## RAG (генерація з доповненням пошуком) - [Модуль 03](../03-rag/README.md) +## RAG (Retrieval-Augmented Generation) - [Модуль 03](../03-rag/README.md) -**Document Processing Pipeline** – Завантажити → розбити → вбудувати → зберегти. +**Document Processing Pipeline** - Завантажити → розбити → заэмбедити → зберегти. -**In-Memory Embedding Store** – Тимчасове сховище для тестування. +**In-Memory Embedding Store** - Непостійне сховище для тестування. -**RAG** – Поєднує пошук і генерацію для обґрунтованих відповідей. +**RAG** - Поєднує пошук та генерацію для грунтовних відповідей. -**Similarity Score** – Оцінка (0-1) семантичної схожості. +**Similarity Score** - Міра (0-1) семантичної подібності. -**Source Reference** – Метадані про отриманий контент. +**Source Reference** - Метадані про отриманий контент. -## Агенти та Інструменти - [Модуль 04](../04-tools/README.md) +## Агенти та інструменти - [Модуль 04](../04-tools/README.md) -**@Tool Annotation** – Позначає Java-методи як AI-викликувані інструменти. +**@Tool Annotation** - Позначає Java методи як викликаємі ШІ інструменти. -**ReAct Pattern** – Міркувати → Діяти → Спостерігати → Повторювати. +**ReAct Pattern** - Логувати → Діяти → Спостерігати → Повторювати. -**Session Management** – Окремі контексти для різних користувачів. +**Session Management** - Окремі контексти для різних користувачів. -**Tool** – Функція, яку може викликати AI агент. +**Tool** - Функція, яку може викликати агент ШІ. -**Tool Description** – Документація цілей і параметрів інструменту. +**Tool Description** - Документування призначення та параметрів інструменту. -## Модуль Агента - [Модуль 05](../05-mcp/README.md) +## Агентний модуль - [Модуль 05](../05-mcp/README.md) -**@Agent Annotation** – Позначає інтерфейси як AI-агенти з декларативним визначенням поведінки. +**@Agent Annotation** - Позначає інтерфейси як агенти ШІ з декларативним визначенням поведінки. -**Agent Listener** – Хук для моніторингу виконання агента через `beforeAgentInvocation()` та `afterAgentInvocation()`. +**Agent Listener** - Хук для моніторингу виконання агента через `beforeAgentInvocation()` та `afterAgentInvocation()`. -**Agentic Scope** – Спільна пам’ять, де агенти зберігають результати з параметром `outputKey` для використання іншими агентами. +**Agentic Scope** - Спільна пам'ять, де агенти зберігають результати під ключем `outputKey` для споживання іншими агентами. -**AgenticServices** – Фабрика для створення агентів через `agentBuilder()` і `supervisorBuilder()`. +**AgenticServices** - Фабрика для створення агентів за допомогою `agentBuilder()` та `supervisorBuilder()`. -**Conditional Workflow** – Маршрутизація за умови до різних спеціалізованих агентів. +**Conditional Workflow** - Маршрутизація до різних спеціалістів за умовами. -**Human-in-the-Loop** – Патерн робочого процесу з людськими перевірками для затвердження або перегляду контенту. +**Human-in-the-Loop** - Шаблон робочого процесу з додаванням людського контролю для схвалення або перевірки контенту. -**langchain4j-agentic** – Maven-залежність для декларативного створення агентів (експериментально). +**langchain4j-agentic** - Maven залежність для декларативного побудови агентів (експериментально). -**Loop Workflow** – Повторення виконання агента доти, доки не буде досягнуто умову (наприклад, оцінка якості ≥ 0.8). +**Loop Workflow** - Ітеративне виконання агента до досягнення умови (наприклад, якість ≥ 0.8). -**outputKey** – Параметр анотації агента, що визначає, де зберігаються результати у Agentic Scope. +**outputKey** - Параметр анотації агента, що вказує, де зберігаються результати у Agentic Scope. -**Parallel Workflow** – Одночасний запуск кількох агентів для незалежних завдань. +**Parallel Workflow** - Одночасне запускання декількох агентів для незалежних завдань. -**Response Strategy** – Як супервайзер формує остаточну відповідь: LAST, SUMMARY або SCORED. +**Response Strategy** - Як супервайзер формулює фінальну відповідь: LAST, SUMMARY або SCORED. -**Sequential Workflow** – Виконання агентів послідовно, де вихід переходить до наступного кроку. +**Sequential Workflow** - Послідовне виконання агентів, де вихід переходить у наступний крок. -**Supervisor Agent Pattern** – Розширений патерн, де супервайзер LLM динамічно вирішує, які підагенти викликати. +**Supervisor Agent Pattern** - Розвинений агентний патерн, де супервайзер LLM динамічно вирішує, яких субагентів викликати. -## Протокол Контексту Моделі (MCP) - [Модуль 05](../05-mcp/README.md) +## Протокол контексту моделі (MCP) - [Модуль 05](../05-mcp/README.md) -**langchain4j-mcp** – Maven-залежність для інтеграції MCP у LangChain4j. +**langchain4j-mcp** - Maven залежність для інтеграції MCP у LangChain4j. -**MCP** – Model Context Protocol: стандарт підключення AI-застосунків до зовнішніх інструментів. Побудуй один раз, використовуй скрізь. +**MCP** - Протокол контексту моделі: стандарт для підключення AI-застосунків до зовнішніх інструментів. Одного разу створити, скрізь використовувати. -**MCP Client** – Застосунок, який підключається до MCP-сервера для виявлення та використання інструментів. +**MCP Client** - Застосунок, що підключається до MCP серверів для виявлення і використання інструментів. -**MCP Server** – Сервіс, що надає інструменти через MCP із чіткими описами і схемами параметрів. +**MCP Server** - Сервіс, що надає інструменти через MCP з чіткими описами та схемами параметрів. -**McpToolProvider** – Компонент LangChain4j, що обгортає MCP-інструменти для використання у AI-сервісах та агентах. +**McpToolProvider** - Компонент LangChain4j, що обгортає MCP інструменти для використання в AI-сервісах та агентах. -**McpTransport** – Інтерфейс для зв’язку MCP. Імплементації включають Stdio та HTTP. +**McpTransport** - Інтерфейс для MCP-комунікації. Реалізації включають Stdio та HTTP. -**Stdio Transport** – Локальний процесний транспорт через stdin/stdout. Корисний для доступу до файлової системи чи командних інструментів. +**Stdio Transport** - Локальний транспорт процесу через stdin/stdout. Корисний для доступу до файлової системи чи командних рядків. -**StdioMcpTransport** – Імплементація LangChain4j, що запускає MCP-сервер як підпроцес. +**StdioMcpTransport** - Реалізація LangChain4j, що запускає MCP сервер як підпроцес. -**Tool Discovery** – Клієнт запитує сервер про доступні інструменти з описами і схемами. +**Tool Discovery** - Клієнт запитує сервер про доступні інструменти з описами та схемами. ## Сервіси Azure - [Модуль 01](../01-introduction/README.md) -**Azure AI Search** – Хмарний пошук з векторними можливостями. [Модуль 03](../03-rag/README.md) +**Azure AI Search** - Хмарний пошук з можливостями векторного пошуку. [Модуль 03](../03-rag/README.md) -**Azure Developer CLI (azd)** – Розгортання ресурсів Azure. +**Azure Developer CLI (azd)** - Розгортання ресурсів Azure. -**Azure OpenAI** – Корпоративний AI-сервіс Microsoft. +**Azure OpenAI** - Корпоративний сервіс ШІ Microsoft. -**Bicep** – Мова інфраструктури як коду для Azure. [Інструкція з інфраструктури](../01-introduction/infra/README.md) +**Bicep** - Мова інфраструктури як коду для Azure. [Інфраструктурний посібник](../01-introduction/infra/README.md) -**Deployment Name** – Ім’я розгортання моделі в Azure. +**Deployment Name** - Назва розгортання моделі в Azure. -**GPT-5.2** – Остання модель OpenAI з контролем міркувань. [Модуль 02](../02-prompt-engineering/README.md) +**GPT-5.2** - Остання модель OpenAI з контролем мислення. [Модуль 02](../02-prompt-engineering/README.md) -## Тестування та Розробка - [Керівництво з тестування](TESTING.md) +## Тестування та розробка - [Посібник з тестування](TESTING.md) -**Dev Container** – Контейнеризоване середовище розробки. [Конфігурація](../../../.devcontainer/devcontainer.json) +**Dev Container** - Контейнеризоване середовище розробки. [Конфігурація](../../../.devcontainer/devcontainer.json) -**GitHub Models** – Безкоштовний майданчик AI-моделей. [Модуль 00](../00-quick-start/README.md) +**In-Memory Testing** - Тестування з використанням in-memory сховища. -**In-Memory Testing** – Тестування з використанням пам’яті. +**Integration Testing** - Інтеграційне тестування з реальною інфраструктурою. -**Integration Testing** – Тестування з реальною інфраструктурою. +**Maven** - Інструмент автоматизації збирання Java. -**Maven** – Інструмент автомації збірки Java. +**Mockito** - Java фреймворк для мокінгу. -**Mockito** – Фреймворк для мокування в Java. - -**Spring Boot** – Фреймворк для Java-застосунків. [Модуль 01](../01-introduction/README.md) +**Spring Boot** - Java фреймворк для створення застосунків. [Модуль 01](../01-introduction/README.md) --- -**Відмова від відповідальності**: -Цей документ був перекладений за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, просимо враховувати, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний переклад людиною. Ми не несемо відповідальності за будь-які непорозуміння чи неправильні тлумачення, що виникли внаслідок використання цього перекладу. +**Відмова від відповідальності**: +Цей документ було перекладено за допомогою сервісу штучного інтелекту для перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. \ No newline at end of file diff --git a/translations/uk/docs/TESTING.md b/translations/uk/docs/TESTING.md index 41f9d6085..0d0675399 100644 --- a/translations/uk/docs/TESTING.md +++ b/translations/uk/docs/TESTING.md @@ -2,19 +2,19 @@ ## Зміст -- [Швидкий старт](../../../docs) -- [Що охоплюють тести](../../../docs) -- [Запуск тестів](../../../docs) -- [Запуск тестів у VS Code](../../../docs) -- [Шаблони тестування](../../../docs) -- [Філософія тестування](../../../docs) -- [Наступні кроки](../../../docs) +- [Швидкий старт](#швидкий-старт) +- [Що охоплюють тести](#що-охоплюють-тести) +- [Запуск тестів](#запуск-тестів) +- [Запуск тестів у VS Code](#запуск-тестів-у-vs-code) +- [Патерни тестування](#патерни-тестування) +- [Філософія тестування](#філософія-тестування) +- [Наступні кроки](#наступні-кроки) Цей посібник проведе вас через тести, які демонструють, як тестувати AI-додатки без необхідності ключів API чи зовнішніх сервісів. ## Швидкий старт -Запустіть усі тести однією командою: +Запустіть усі тести одною командою: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Коли всі тести проходять, ви побачите вивід, як на скриншоті нижче — тести виконуються без жодних помилок. +Коли всі тести пройдуть успішно, ви побачите результат, як на скріншоті нижче — тести пройшли без помилок. Successful Test Results -*Успішне виконання тестів, що показує проходження всіх тестів без помилок* +*Успішне виконання тестів, яке показує, що всі тести пройшли без помилок* ## Що охоплюють тести -Цей курс зосереджений на **блокових тестах**, які запускаються локально. Кожен тест демонструє окрему концепцію LangChain4j. Нижче показано тестову піраміду — саме блокові тести утворюють швидку, надійну основу, на якій будується ваша тестова стратегія. +Цей курс зосереджений на **модульних тестах**, які запускаються локально. Кожен тест демонструє конкретну концепцію LangChain4j окремо. Піраміда тестування нижче показує, де розташовані модульні тести — вони формують швидку та надійну основу, на якій будується решта вашої стратегії тестування. Testing Pyramid -*Тестова піраміда, що показує баланс між блоковими тестами (швидкі, ізольовані), інтеграційними тестами (реальні компоненти) і end-to-end тестами. Це навчання охоплює саме блокове тестування.* +*Піраміда тестування, що показує баланс між модульними тестами (швидкі, ізольовані), інтеграційними тестами (реальні компоненти) та end-to-end тестами. Цей тренінг охоплює модульне тестування.* | Модуль | Тести | Фокус | Ключові файли | -|--------|-------|-------|---------------| -| **00 - Швидкий старт** | 6 | Шаблони підказок та заміщення змінних | `SimpleQuickStartTest.java` | -| **01 - Вступ** | 8 | Пам'ять розмови та стан чату | `SimpleConversationTest.java` | -| **02 - Інженерія підказок** | 12 | Патерни GPT-5.2, рівні готовності, структурований вивід | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Інгестування документів, ембеддинги, пошук за схожістю | `DocumentServiceTest.java` | -| **04 - Інструменти** | 12 | Виклики функцій і ланцюжки інструментів | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Протокол Model Context з транспортом stdio | `SimpleMcpTest.java` | +|--------|-------|-------|-----------| +| **01 - Вступ** | 8 | Пам'ять розмови та станова чат-сесія | `SimpleConversationTest.java` | +| **02 - Конструювання запитів (Prompt Engineering)** | 12 | Шаблони GPT-5.2, рівні готовності, структурований вивід | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Імпорт документів, вектори, пошук за схожістю | `DocumentServiceTest.java` | +| **04 - Інструменти** | 12 | Виклик функцій та ланцюжки інструментів | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Протокол контексту моделі з транспортом stdio | `SimpleMcpTest.java` | ## Запуск тестів -**Запустіть усі тести з кореня:** +**Запустити всі тести з кореневої директорії:** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**Запуск тестів для конкретного модуля:** +**Запустити тести для конкретного модуля:** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**Запуск одного класу тестів:** +**Запустити окремий клас тестів:** **Bash:** ```bash @@ -91,7 +90,7 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**Запуск конкретного тестового методу:** +**Запустити конкретний метод тесту:** **Bash:** ```bash @@ -105,31 +104,31 @@ mvn --% test -Dtest=SimpleConversationTest#слід зберігати істо ## Запуск тестів у VS Code -Якщо ви користуєтеся Visual Studio Code, Test Explorer пропонує графічний інтерфейс для запуску та налагодження тестів. +Якщо ви використовуєте Visual Studio Code, Test Explorer надає графічний інтерфейс для запуску та відлагодження тестів. VS Code Test Explorer -*Test Explorer у VS Code, що показує дерево тестів із усіма Java класами та окремими тестовими методами* +*VS Code Test Explorer показує дерево тестів з усіма Java-класами тестів та окремими методами тестів* **Щоб запускати тести у VS Code:** -1. Відкрийте Test Explorer, натиснувши іконку колби на панелі активності +1. Відкрийте Test Explorer, клацнувши значок лабораторної колби в панелі Activity Bar 2. Розгорніть дерево тестів, щоб побачити всі модулі та класи тестів -3. Натисніть кнопку відтворення поруч із будь-яким тестом, щоб запустити його окремо -4. Натисніть «Run All Tests», щоб виконати весь набір -5. Клацніть правою кнопкою миші по тесту та виберіть «Debug Test», щоб встановити брекпойнти та проходити крок за кроком +3. Клацніть кнопку відтворення поруч із будь-яким тестом, щоб запустити його окремо +4. Клацніть "Run All Tests", щоб виконати весь набір +5. Клацніть правою кнопкою миші на будь-який тест і виберіть "Debug Test", щоб встановити точки зупину та проходити код крок за кроком -Test Explorer показує зелені позначки для пройдених тестів і надає докладні повідомлення про помилки, якщо тести не проходять. +Test Explorer показує зелені галочки для пройдених тестів і надає детальні повідомлення про помилки, коли тести не проходять. -## Шаблони тестування +## Патерни тестування -### Шаблон 1: Тестування шаблонів підказок +### Патерн 1: Тестування шаблонів запитів -Найпростіший шаблон тестує шаблони підказок без виклику будь-якої AI-моделі. Ви перевіряєте, що заміщення змінних працює правильно, а підказки форматуються очікувано. +Найпростіший патерн тестує шаблони запитів без виклику жодної AI-моделі. Ви перевіряєте, що підстановка змінних працює правильно і запити форматуються як очікується. Prompt Template Testing -*Тестування шаблонів підказок із потоком заміщення змінних: шаблон із заповнювачами → застосовані значення → перевірений форматований вивід* +*Тестування шаблонів запитів, що демонструє процес підстановки змінних: шаблон з заповнювачами → застосовані значення → перевірений форматований вивід* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Цей тест знаходиться у `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. +Цей патерн перевіряє, що підстановка змінних працює правильно і запити форматуються як очікується — ключ API або виклик моделі не потрібні. -**Запустіть його:** +### Патерн 2: Мокінг мовних моделей -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#тестуванняФорматуванняШаблонуПідказки -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#тестуванняФорматуванняШаблонуПідказки -``` - -### Шаблон 2: Мокінг мовних моделей - -При тестуванні логіки розмови використовуйте Mockito для створення підроблених моделей, які повертають заздалегідь визначені відповіді. Це робить тести швидкими, безкоштовними і детермінованими. +При тестуванні логіки розмов використовуйте Mockito для створення фейкових моделей, які повертають заздалегідь визначені відповіді. Це робить тести швидкими, безкоштовними та детерміністичними. Mock vs Real API Comparison -*Порівняння, що показує, чому для тестування переважно використовувати моки: вони швидкі, безкоштовні, детерміновані та не потребують ключів API* +*Порівняння, що демонструє, чому для тестів краще використовувати моки: вони швидкі, безкоштовні, детерміністичні і не потребують ключів API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Цей шаблон застосовується в `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Мок гарантує послідовну поведінку, щоб ви могли перевірити коректність управління пам’яттю. +Цей патерн використовується у `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Мок гарантує послідовну поведінку, щоб ви могли перевірити, чи правильно працює управління пам'яттю. -### Шаблон 3: Тестування ізоляції розмов +### Патерн 3: Тестування ізоляції розмов -Пам’ять розмови має розділяти користувачів. Цей тест перевіряє, що контексти розмов не змішуються. +Пам'ять розмов повинна зберігати кілька користувачів окремо. Цей тест перевіряє, що контексти розмов не змішуються. Conversation Isolation -*Тестування ізоляції розмов, що показує окремі сховища пам’яті для різних користувачів щоб запобігти змішуванню контекстів* +*Тестування ізоляції розмов, що показує окремі сховища пам'яті для різних користувачів, щоб запобігти змішуванню контекстів* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Кожна розмова підтримує свою власну незалежну історію. В продакшн-системах ця ізоляція критична для багатокористувацьких застосунків. +Кожна розмова підтримує власну незалежну історію. В продуктивних системах така ізоляція критична для багатокористувацьких додатків. -### Шаблон 4: Тестування інструментів окремо +### Патерн 4: Тестування інструментів окремо -Інструменти — це функції, які може викликати AI. Тестуйте їх напряму, щоб переконатися, що вони працюють правильно незалежно від рішень AI. +Інструменти — це функції, які AI може викликати. Тестуйте їх напряму, щоб переконатися, що вони працюють правильно, незалежно від рішень AI. Tools Testing -*Тестування інструментів окремо, показуючи мок-інструмент, що виконується без викликів AI для перевірки бізнес-логіки* +*Тестування інструментів окремо, що демонструє виконання мок-інструменту без виклику AI для перевірки бізнес-логіки* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Ці тести з `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` перевіряють логіку інструментів без участі AI. Приклад ланцюжка показує, як вихід одного інструменту передається як вхід іншому. +Ці тести з `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` перевіряють логіку інструментів без участі AI. Приклад ланцюжка показує, як вихід одного інструменту передається на вхід іншого. -### Шаблон 5: Тестування RAG в пам’яті +### Патерн 5: Тестування RAG у пам'яті -Системи RAG зазвичай потребують векторних баз даних та сервісів ембеддингів. Візерунок “в пам’яті” дає змогу тестувати весь конвеєр без зовнішніх залежностей. +Системи RAG традиційно потребують векторних баз даних і сервісів для ембеддінгу. Патерн in-memory дозволяє тестувати весь процес без зовнішніх залежностей. In-Memory RAG Testing -*Робочий процес тестування RAG в пам’яті, що показує парсинг документів, зберігання ембеддингів і пошук за схожістю без потреби у базі даних* +*Потік тестування in-memory RAG, що показує парсинг документів, зберігання ембеддингів і пошук за схожістю без потреби у базі даних* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Цей тест з `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` створює документ в пам’яті та перевіряє нарізку на частини і обробку метаданих. +Цей тест з `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` створює документ у пам'яті і перевіряє поділ на частини та обробку метаданих. -### Шаблон 6: Інтеграційне тестування MCP +### Патерн 6: Інтеграційне тестування MCP -Модуль MCP тестує інтеграцію Model Context Protocol з транспортом stdio. Ці тести перевіряють, чи ваш додаток може запускати і взаємодіяти з MCP-серверами як підпроцесами. +Модуль MCP тестує інтеграцію Протоколу Контексту Моделі за допомогою транспортного stdio. Ці тести перевіряють, що ваш додаток може запускати і спілкуватися з MCP-серверами як підпроцесами. -Тести в `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` перевіряють поведінку клієнта MCP. +Тести з `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` перевіряють поведінку MCP клієнта. **Запустіть їх:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Філософія тестування -Тестуйте ваш код, а не AI. Ваші тести повинні перевіряти код, що ви пишете, контролюючи, як будуються підказки, як керується пам’ять і як виконуються інструменти. Відповіді AI варіюються і не повинні бути частиною тверджень тестів. Запитуйте себе, чи правильно ваш шаблон підказки заміщує змінні, а не чи дає AI правильну відповідь. +Тестуйте ваш код, а не AI. Ваші тести мають перевіряти код, який ви пишете, контролюючи, як конструюються запити (prompts), як керується пам'ять і як виконуються інструменти. Відповіді AI можуть варіюватися і не повинні бути частиною тверджень тестів. Запитуйте себе, чи правильно ваш шаблон запиту підставляє змінні, а не те, чи правильну відповідь дає AI. -Використовуйте моки для мовних моделей. Це зовнішні залежності, які працюють повільно, дорого і недетерміновано. Мокінг робить тести швидкими (мілісекунди замість секунд), безкоштовними (без витрат на API) та детермінованими (однаковий результат кожного разу). +Використовуйте моки для мовних моделей. Це зовнішні залежності, які працюють повільно, дорого і нестабільно. Мокінг робить тести швидкими (мілісекунди замість секунд), безкоштовними (без витрат на API) і детерміністичними (той самий результат щоразу). -Підтримуйте тести незалежними. Кожен тест повинен налаштовувати власні дані, не покладатися на інші тести і прибирати за собою. Тести мають проходити незалежно від порядку виконання. +Підтримуйте тести незалежними. Кожен тест має налаштовувати власні дані, не залежати від інших тестів і прибирати після себе. Тести повинні проходити незалежно від порядку запуску. -Тестуйте крайні випадки, а не лише успішні шляхи. Спробуйте пусті вхідні дані, дуже великі вхідні дані, спеціальні символи, недійсні параметри та граничні умови. Вони часто виявляють баги, які при нормальному використанні не проявляються. +Тестуйте крайні випадки поза «щасливим шляхом». Спробуйте порожній ввід, дуже великий ввід, спеціальні символи, недійсні параметри і граничні умови. Часто саме вони виявляють баги, які звичайне використання не показує. -Використовуйте описові назви. Порівняйте `shouldMaintainConversationHistoryAcrossMultipleMessages()` і `test1()`. Перша точно повідомляє, що тестується, що значно полегшує налагодження помилок. +Використовуйте описові назви. Порівняйте `shouldMaintainConversationHistoryAcrossMultipleMessages()` з `test1()`. Перша одразу показує, що тестується, що значно полегшує налагодження помилок. ## Наступні кроки -Тепер, коли ви розумієте шаблони тестування, зануртесь глибше в кожен модуль: +Тепер, коли ви розумієте патерни тестування, заглибтесь у кожен модуль: -- **[00 - Швидкий старт](../00-quick-start/README.md)** — Почніть із основ шаблонів підказок -- **[01 - Вступ](../01-introduction/README.md)** — Вивчіть управління пам’яттю розмов -- **[02 - Інженерія підказок](../02/prompt-engineering/README.md)** — Опануйте патерни GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** — Створюйте системи звернення з доповненням -- **[04 - Інструменти](../04-tools/README.md)** — Реалізуйте виклики функцій і ланцюжки інструментів -- **[05 - MCP](../05-mcp/README.md)** — Інтегруйте Model Context Protocol +- **[01 - Вступ](../01-introduction/README.md)** - Вивчіть управління пам'яттю розмов +- **[02 - Конструювання запитів (Prompt Engineering)](../02/prompt-engineering/README.md)** - Опануйте шаблони GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Створюйте системи генерації з доповненням пошуком +- **[04 - Інструменти](../04-tools/README.md)** - Реалізуйте виклики функцій та ланцюжки інструментів +- **[05 - MCP](../05-mcp/README.md)** - Інтегруйте Протокол Контексту Моделі -README кожного модуля надає докладне пояснення концепцій, що тестуються тут. +README кожного модуля містить детальні пояснення концепцій, які тут тестуються. --- -**Навігація:** [← Назад до головної](../README.md) +**Навігація:** [← Назад на головну](../README.md) --- -**Відмова від відповідальності**: -Цей документ було перекладено за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, зверніть увагу, що автоматичний переклад може містити помилки чи неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критичної інформації рекомендується звертатися до професійного людського перекладу. Ми не несемо відповідальності за будь-які непорозуміння чи неправильні тлумачення, що виникли внаслідок використання цього перекладу. +**Відмова від відповідальності**: +Цей документ було перекладено за допомогою сервісу штучного інтелекту для перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критично важливої інформації рекомендується професійний людський переклад. Ми не несемо відповідальності за будь-які непорозуміння або неправильні тлумачення, що виникли внаслідок використання цього перекладу. \ No newline at end of file diff --git a/translations/ur/.co-op-translator.json b/translations/ur/.co-op-translator.json index f2ecf1d97..2368993d5 100644 --- a/translations/ur/.co-op-translator.json +++ b/translations/ur/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "ur" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T22:35:16+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T07:26:14+00:00", "source_file": "01-introduction/README.md", "language_code": "ur" }, @@ -18,20 +18,20 @@ "language_code": "ur" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T22:38:07+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T07:21:28+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "ur" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T22:39:51+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T07:25:17+00:00", "source_file": "03-rag/README.md", "language_code": "ur" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T12:22:33+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T07:23:56+00:00", "source_file": "04-tools/README.md", "language_code": "ur" }, @@ -54,8 +54,8 @@ "language_code": "ur" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:35:09+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T07:20:03+00:00", "source_file": "README.md", "language_code": "ur" }, @@ -72,14 +72,14 @@ "language_code": "ur" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T22:43:21+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T07:22:03+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "ur" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T22:44:08+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T07:22:42+00:00", "source_file": "docs/TESTING.md", "language_code": "ur" } diff --git a/translations/ur/00-quick-start/README.md b/translations/ur/00-quick-start/README.md deleted file mode 100644 index 2bb4a6f9d..000000000 --- a/translations/ur/00-quick-start/README.md +++ /dev/null @@ -1,389 +0,0 @@ -# ماڈیول 00: تیز آغاز - -## فہرست مضامین - -- [تعارف](../../../00-quick-start) -- [LangChain4j کیا ہے؟](../../../00-quick-start) -- [LangChain4j کی منحصرات](../../../00-quick-start) -- [ضروریات](../../../00-quick-start) -- [سیٹ اپ](../../../00-quick-start) - - [1. اپنا GitHub ٹوکن حاصل کریں](../../../00-quick-start) - - [2. اپنا ٹوکن سیٹ کریں](../../../00-quick-start) -- [مثالیں چلائیں](../../../00-quick-start) - - [1. بنیادی چیٹ](../../../00-quick-start) - - [2. پرامپٹ پیٹرنز](../../../00-quick-start) - - [3. فنکشن کالنگ](../../../00-quick-start) - - [4. دستاویز سوال و جواب (آسان RAG)](../../../00-quick-start) - - [5. ذمہ دار AI](../../../00-quick-start) -- [ہر مثال کیا دکھاتی ہے](../../../00-quick-start) -- [آگے کے مراحل](../../../00-quick-start) -- [مسائل کا حل](../../../00-quick-start) - -## تعارف - -یہ تیز آغاز آپ کو LangChain4j کے ساتھ جلد از جلد کام شروع کرنے کے لیے ہے۔ یہ LangChain4j اور GitHub Models کے ساتھ AI ایپلیکیشنز بنانے کی بنیادی باتیں کور کرتا ہے۔ اگلے ماڈیولز میں آپ Azure OpenAI اور GPT-5.2 پر منتقل ہوں گے اور ہر تصور کو مزید گہرائی سے سمجھیں گے۔ - -## LangChain4j کیا ہے؟ - -LangChain4j ایک Java لائبریری ہے جو AI سے چلنے والی ایپلیکیشنز بنانے کو آسان بناتی ہے۔ HTTP کلائنٹس اور JSON تجزیہ کے بجائے، آپ صاف ستھری Java APIs کے ساتھ کام کرتے ہیں۔ - -LangChain میں "چین" سے مراد متعدد اجزاء کو آپس میں جوڑنا ہے - آپ پرامپٹ کو ماڈل سے پارسر تک چیک کر سکتے ہیں، یا متعدد AI کالز کو ایک دوسرے کے ساتھ سلسلے وار جوڑ سکتے ہیں جہاں ایک آؤٹ پٹ اگلے ان پٹ میں جاتا ہے۔ یہ تیز آغاز بنیادی اصولوں پر توجہ دیتا ہے اس سے پہلے کہ آپ مزید پیچیدہ چینز کو دریافت کریں۔ - -LangChain4j Chaining Concept - -*LangChain4j میں اجزاء کو سلسلے وار جوڑنا - بلاکس کو جوڑ کر طاقتور AI ورک فلو بنانا* - -ہم تین بنیادی اجزاء استعمال کریں گے: - -**ChatModel** - AI ماڈل کے ساتھ بات چیت کا انٹرفیس۔ `model.chat("prompt")` کال کریں اور جواب حاصل کریں۔ ہم `OpenAiOfficialChatModel` استعمال کرتے ہیں جو OpenAI-مطابقت والے اینڈ پوائنٹس جیسے GitHub Models کے ساتھ کام کرتا ہے۔ - -**AiServices** - قسم محفوظ AI سروس انٹرفیسز بناتا ہے۔ طریقے define کریں، ان پر `@Tool` کا ٹیگ لگائیں، اور LangChain4j انتظام کرتا ہے۔ AI آپ کے Java طریقوں کو خود بخود کال کرتا ہے جب ضرورت ہو۔ - -**MessageWindowChatMemory** - گفتگو کی تاریخ کو برقرار رکھتا ہے۔ اس کے بغیر ہر درخواست آزاد ہوتی ہے۔ اس کے ساتھ، AI پچھلے پیغامات کو یاد رکھتا ہے اور متعدد ٹرنز میں سیاق و سباق بنائے رکھتا ہے۔ - -LangChain4j Architecture - -*LangChain4j کی ساخت - بنیادی اجزاء مل کر آپ کی AI ایپلیکیشنز کو چلانے کے لیے کام کرتے ہیں* - -## LangChain4j کی منحصرات - -یہ تیز آغاز [`pom.xml`](../../../00-quick-start/pom.xml) میں تین Maven منحصرات استعمال کرتا ہے: - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` ماڈیول `OpenAiOfficialChatModel` کلاس فراہم کرتا ہے جو OpenAI-مطابقت رکھنے والی APIs سے جڑتا ہے۔ GitHub Models اسی API فارمٹ استعمال کرتا ہے، اس لیے کوئی خاص اڈاپٹر نہیں چاہیے - بس بیس URL کو `https://models.github.ai/inference` پر پوائنٹ کریں۔ - -`langchain4j-easy-rag` ماڈیول خودکار دستاویزی تقسیم، ایمبیڈنگ اور بازیافت فراہم کرتا ہے تاکہ آپ بغیر دستی طور پر ہر مرحلہ مرتب کیے RAG ایپلیکیشنز بنا سکیں۔ - -## ضروریات - -**Dev Container استعمال کر رہے ہیں؟** Java اور Maven پہلے سے انسٹال ہیں۔ آپ کو صرف GitHub Personal Access Token چاہیے۔ - -**مقامی ترقی:** -- Java 21+، Maven 3.9+ -- GitHub Personal Access Token (نیچے ہدایات) - -> **نوٹ:** یہ ماڈیول GitHub Models سے `gpt-4.1-nano` استعمال کرتا ہے۔ کوڈ میں ماڈل نام تبدیل نہ کریں - یہ GitHub کے دستیاب ماڈلز کے ساتھ کام کرنے کے لیے ترتیب دیا گیا ہے۔ - -## سیٹ اپ - -### 1. اپنا GitHub ٹوکن حاصل کریں - -1. [GitHub Settings → Personal Access Tokens](https://github.com/settings/personal-access-tokens) پر جائیں -2. "Generate new token" پر کلک کریں -3. ایک وضاحتی نام دیں (مثلاً "LangChain4j Demo") -4. مدت ختم ہونے کی مدت مقرر کریں (7 دن کی سفارش کی جاتی ہے) -5. "Account permissions" میں "Models" پر جائیں اور اسے "Read-only" پر سیٹ کریں -6. "Generate token" پر کلک کریں -7. اپنا ٹوکن کاپی کریں اور محفوظ رکھیں - آپ کو یہ دوبارہ نظر نہیں آئے گا - -### 2. اپنا ٹوکن سیٹ کریں - -**آپشن 1: VS Code استعمال کرتے ہوئے (تجویز کردہ)** - -اگر آپ VS Code استعمال کر رہے ہیں تو اپنے پراجیکٹ کے روٹ میں `.env` فائل میں اپنا ٹوکن شامل کریں: - -اگر `.env` فائل موجود نہیں، تو `.env.example` کو `.env` میں کاپی کریں یا نیا `.env` فائل بنائیں۔ - -**مثال `.env` فائل:** -```bash -# میں /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -پھر آپ کسی بھی ڈیمو فائل (مثلاً `BasicChatDemo.java`) پر ایکسپلورر میں رائٹ کلک کر کے **"Run Java"** منتخب کریں یا Run and Debug پینل سے لانچ کنفیگریشنز استعمال کریں۔ - -**آپشن 2: ٹرمینل استعمال کرتے ہوئے** - -ٹوکن کو بطور ماحول کا متغیر سیٹ کریں: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - - -## مثالیں چلائیں - -**VS Code استعمال کرتے ہوئے:** کسی بھی ڈیمو فائل پر رائٹ کلک کریں اور **"Run Java"** منتخب کریں، یا Run and Debug پینل سے لانچ کنفیگریشنز استعمال کریں (پہلے `.env` میں اپنا ٹوکن شامل کرنا یقینی بنائیں)۔ - -**Maven استعمال کرتے ہوئے:** متبادل طور پر، آپ کمانڈ لائن سے چلائیں: - -### 1. بنیادی چیٹ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - - -### 2. پرامپٹ پیٹرنز - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -زیرو شاٹ، فیو شاٹ، چین آف تھوٹ، اور رول بیسڈ پرامپٹنگ دکھاتا ہے۔ - -### 3. فنکشن کالنگ - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI ضرورت پڑنے پر خود بخود آپ کے Java طریقے کال کرتا ہے۔ - -### 4. دستاویز سوال و جواب (آسان RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -آسان RAG کے ساتھ خودکار ایمبیڈنگ اور بازیافت کے ذریعے اپنے دستاویزات کے بارے میں سوالات پوچھیں۔ - -### 5. ذمہ دار AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -دیکھیں کہ AI سیفٹی فلٹرز کس طرح نقصان دہ مواد کو روک دیتے ہیں۔ - -## ہر مثال کیا دکھاتی ہے - -**بنیادی چیٹ** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -یہاں شروع کریں تاکہ LangChain4j کو اس کی سادگی میں دیکھ سکیں۔ آپ ایک `OpenAiOfficialChatModel` بنائیں گے، `.chat()` کے ذریعے پرامپٹ بھیجیں گے، اور جواب حاصل کریں گے۔ یہ بنیاد دکھاتا ہے: ماڈلز کو کس طرح کسٹم اینڈ پوائنٹس اور API کیز کے ساتھ initialize کرنا ہے۔ ایک بار جب آپ یہ پیٹرن سمجھ لیں، باقی سب اس پر مبنی ہوگا۔ - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 GitHub Copilot Chat کے ساتھ آزمائیں:** [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) کھولیں اور پوچھیں: -> - "میں اس کوڈ میں GitHub Models سے Azure OpenAI کیسے سوئچ کروں؟" -> - "OpenAiOfficialChatModel.builder() میں کون سے اور پیرامیٹرز مرتب کر سکتا ہوں؟" -> - "میں مکمل جواب کا انتظار کیے بغیر اسٹریم شدہ جوابات کیسے شامل کروں؟" - -**پرامپٹ انجینئرنگ** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -اب جب آپ کو ماڈل سے بات کرنا آتا ہے، تو دیکھیں کہ آپ اس سے کیا کہتے ہیں۔ یہ ڈیمو وہی ماڈل سیٹ اپ استعمال کرتا ہے لیکن پانچ مختلف پرامپٹنگ پیٹرنز دکھاتا ہے۔ براہ راست ہدایتوں کے لیے زیرو شاٹ پرامپٹ آزمائیں، مثالوں سے سیکھنے کے لیے فیو شاٹ، استدلال کے مراحل کے لیے چین آف تھوٹ، اور سیاق و سباق کے لیے رول بیسڈ پرامپٹ۔ آپ دیکھیں گے کہ ایک ہی ماڈل کس قدر مختلف نتائج دیتا ہے کہ آپ اپنی درخواست کیسے فریم کرتے ہیں۔ - -یہ ڈیمو پرامپٹ ٹیمپلیٹس بھی دکھاتا ہے، جو متغیرات کے ساتھ دوبارہ قابل استعمال پرامپٹس بنانے کا ایک طاقتور طریقہ ہے۔ -نیچے والا مثال LangChain4j `PromptTemplate` استعمال کرتا ہے تاکہ متغیرات بھریں۔ AI دی گئی منزل اور سرگرمی کی بنیاد پر جواب دے گا۔ - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 GitHub Copilot Chat کے ساتھ آزمائیں:** [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) کھولیں اور پوچھیں: -> - "زیرو شاٹ اور فیو شاٹ پرامپٹنگ میں کیا فرق ہے، اور مجھے کب کون سا استعمال کرنا چاہیے؟" -> - "درجہ حرارت (temperature) پیرامیٹر ماڈل کے جوابات کو کیسے متاثر کرتا ہے؟" -> - "پروڈکشن میں پرامپٹ انجیکشن حملوں کو روکنے کی کیا تکنیکیں ہیں؟" -> - "عام پیٹرنز کے لیے reusable PromptTemplate آبجیکٹس کیسے بناؤں؟" - -**ٹول انٹیگریشن** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -یہاں LangChain4j طاقتور ہو جاتا ہے۔ آپ `AiServices` استعمال کریں گے تاکہ AI معاون بنائیں جو آپ کے Java طریقے کال کرے۔ بس اپنے طریقوں پر `@Tool("description")` کا ٹیگ لگائیں اور LangChain4j باقی انتظام کرے گا - AI خود بخود فیصلہ کرتا ہے کہ صارف کیا پوچھتا ہے اس کی بنیاد پر کون سا ٹول کب استعمال کرنا ہے۔ یہ فنکشن کالنگ ظاہر کرتا ہے، جو AI کو صرف سوالوں کا جواب دینے کی بجائے عمل کرنے کے قابل بناتا ہے۔ - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 GitHub Copilot Chat کے ساتھ آزمائیں:** [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) کھولیں اور پوچھیں: -> - "@Tool انوٹیشن کیسے کام کرتی ہے اور LangChain4j اس کے پیچھے کیا کرتا ہے؟" -> - "کیا AI ایک سلسلے میں متعدد ٹولز کال کر سکتا ہے تاکہ پیچیدہ مسائل حل کرے؟" -> - "اگر کوئی ٹول استثنا پھینکے تو میں غلطیوں کو کیسے ہینڈل کروں؟" -> - "میں اس کیلکولیٹر مثال کے بجائے اصلی API کیسے انٹیگریٹ کروں؟" - -**دستاویز سوال و جواب (آسان RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -یہاں آپ LangChain4j کی "Easy RAG" اپروچ کے ذریعے RAG (retrieval-augmented generation) دیکھیں گے۔ دستاویزات لوڈ ہوتی ہیں، خودکار طریقے سے تقسیم اور ایمبیڈ کی جاتی ہیں، پھر ایک مواد بازیافت کنندہ وقتِ سوال AI کو متعلقہ حصے فراہم کرتا ہے۔ AI آپ کی دستاویزات کی بنیاد پر جواب دیتا ہے، اپنی عمومی معلومات نہیں۔ - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 GitHub Copilot Chat کے ساتھ آزمائیں:** [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) کھولیں اور پوچھیں: -> - "ماڈل کی تربیتی ڈیٹا کے مقابلے میں RAG AI کے ہیلوسینیشن کو کیسے روکتا ہے؟" -> - "یہ آسان طریقہ اور کسٹم RAG پائپ لائن میں کیا فرق ہے؟" -> - "میں اسے متعدد دستاویزات یا بڑے نالج بیس کے لیے کیسے اسکیل کر سکتا ہوں؟" - -**ذمہ دار AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -گہرائی سے دفاع کے ساتھ AI سیفٹی بنائیں۔ یہ ڈیمو دو حفاظتی پرتیں دکھاتا ہے جو اکٹھے کام کرتی ہیں: - -**حصہ 1: LangChain4j ان پٹ گارڈریل** - خطرناک پرامپٹس کو LLM تک پہنچنے سے پہلے روکتا ہے۔ اپنی کسٹم گارڈریل بنائیں جو ممنوعہ الفاظ یا پیٹرنز کو چیک کرتی ہیں۔ یہ آپ کے کوڈ میں چلتے ہیں، اس لیے تیز اور مفت ہیں۔ - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**حصہ 2: پرووائیڈر سیفٹی فلٹرز** - GitHub Models میں بلٹ ان فلٹرز ہیں جو آپ کی گارڈریل کی ممکنہ کمی کو پورا کرتے ہیں۔ آپ سخت بلاکس (HTTP 400 ایررز) اور نرم انکار دیکھیں گے جہاں AI شائستگی سے انکار کرتا ہے۔ - -> **🤖 GitHub Copilot Chat کے ساتھ آزمائیں:** [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) کھولیں اور پوچھیں: -> - "InputGuardrail کیا ہے اور میں اپنا کیسے بناؤں؟" -> - "سخت بلاک اور نرم انکار میں کیا فرق ہے؟" -> - "گارڈریل اور پرووائیڈر فلٹرز دونوں استعمال کرنے کی کیا وجہ ہے؟" - -## آگے کے مراحل - -**اگلا ماڈیول:** [01-introduction - LangChain4j کے ساتھ شروعات](../01-introduction/README.md) - ---- - -**نیوگیشن:** [← مین پیج پر واپس](../README.md) | [اگلا: ماڈیول 01 - تعارف →](../01-introduction/README.md) - ---- - -## مسائل کا حل - -### پہلی بار Maven بلڈ - -**مسئلہ:** ابتدائی `mvn clean compile` یا `mvn package` میں طویل وقت لگنا (10-15 منٹ) - -**سبب:** Maven کو پہلی بار تمام پروجیکٹ منحصرات ڈاؤن لوڈ کرنے کی ضرورت ہوتی ہے (Spring Boot، LangChain4j لائبریریز، Azure SDKs، وغیرہ)۔ - -**حل:** یہ معمول کی بات ہے۔ بعد کی بلڈز زیادہ تیز ہوں گی کیونکہ منحصرات لوکل کیش ہو چکی ہوتی ہیں۔ ڈاؤن لوڈ کا وقت آپ کے نیٹ ورک کی رفتار پر منحصر ہے۔ - -### PowerShell Maven کمانڈ کی نحو - -**مسئلہ:** Maven کمانڈز `Unknown lifecycle phase ".mainClass=..."` کی خرابی کے ساتھ ناکام ہونا -**وجہ**: PowerShell `=` کو ویری ایبل اسائنمنٹ آپریٹر کے طور پر سمجھتا ہے، جس سے Maven پراپرٹی کا سینٹیکس ٹوٹ جاتا ہے - -**حل**: Maven کمانڈ سے پہلے stop-parsing آپریٹر `--%` استعمال کریں: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` آپریٹر PowerShell کو بتاتا ہے کہ وہ باقی تمام دلائل کو بغیر کسی تشریح کے بالکل ویسے ہی Maven کو بھیج دے۔ - -### Windows PowerShell میں ایموجی کی نمائش - -**مسئلہ**: PowerShell میں AI جوابات ایموجیز کی بجائے بے معنی حروف دکھاتے ہیں (جیسے `????` یا `â??`) - -**وجہ**: PowerShell کی ڈیفالٹ انکوڈنگ UTF-8 ایموجیز کی حمایت نہیں کرتی - -**حل**: جاوا ایپلیکیشنز چلانے سے پہلے یہ کمانڈ چلائیں: -```cmd -chcp 65001 -``` - -یہ ٹرمینل میں UTF-8 انکوڈنگ کو زبردستی فعال کرتا ہے۔ متبادل طور پر، Windows Terminal استعمال کریں جو بہتر یونیکوڈ سپورٹ فراہم کرتا ہے۔ - -### API کالز کی ڈیبگنگ - -**مسئلہ**: تصدیقی غلطیاں، ریٹ لمٹس، یا AI ماڈل سے غیر متوقع جوابات - -**حل**: مثالوں میں `.logRequests(true)` اور `.logResponses(true)` شامل ہیں تاکہ API کالز کنسول میں دکھائی دیں۔ یہ تصدیقی غلطیوں، ریٹ لمٹس، یا غیر متوقع جوابات کو حل کرنے میں مدد دیتا ہے۔ پیداوار میں ان فلیگز کو ہٹا دیں تاکہ لاگ شور کم ہو۔ - ---- - - -**اہم اطلاع**: -یہ دستاویز AI تراجم کی سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ اگرچہ ہم درستگی کی بھرپور کوشش کرتے ہیں، براہ کرم اس بات کا خیال رکھیں کہ خودکار تراجم میں غلطیاں یا نا درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنی مادری زبان میں ہی معتبر ماخذ سمجھی جانی چاہیے۔ اہم معلومات کے لیے پیشہ ورانہ انسانی ترجمہ تجویز کیا جاتا ہے۔ اس ترجمے کے استعمال سے ہونے والی کسی بھی غلط فہمی یا غلط تعبیر کی ذمہ داری ہم پر عائد نہیں ہوتی۔ - \ No newline at end of file diff --git a/translations/ur/01-introduction/README.md b/translations/ur/01-introduction/README.md index 288d6a602..b1b7d37c8 100644 --- a/translations/ur/01-introduction/README.md +++ b/translations/ur/01-introduction/README.md @@ -1,87 +1,87 @@ -# ماڈیول 01: LangChain4j کے ساتھ شروع کرنا +# ماڈیول 01: LangChain4j کے ساتھ شروعات ## فہرست مضامین -- [ویڈیو واک تھرو](../../../01-introduction) -- [آپ کیا سیکھیں گے](../../../01-introduction) -- [مقدمات](../../../01-introduction) -- [بنیادی مسئلہ سمجھنا](../../../01-introduction) -- [ٹوکنز کو سمجھنا](../../../01-introduction) -- [میموری کیسے کام کرتی ہے](../../../01-introduction) -- [یہ LangChain4j کیسے استعمال کرتا ہے](../../../01-introduction) -- [Azure OpenAI انفراسٹرکچر تعینات کریں](../../../01-introduction) -- [ایپلیکیشن کو مقامی طور پر چلائیں](../../../01-introduction) -- [ایپلیکیشن کا استعمال](../../../01-introduction) - - [بے ریاست چیٹ (بائیں پینل)](../../../01-introduction) - - [ریاستی چیٹ (دائیں پینل)](../../../01-introduction) -- [اگلے اقدامات](../../../01-introduction) +- [ویڈیو واک تھرو](#ویڈیو-واک-تھرو) +- [آپ کیا سیکھیں گے](#آپ-کیا-سیکھیں-گے) +- [اہم تقاضے](#اہم-تقاضے) +- [بنیادی مسئلے کو سمجھنا](#بنیادی-مسئلے-کو-سمجھنا) +- [ٹوکنز کو سمجھنا](#ٹوکنز-کو-سمجھنا) +- [میموری کیسے کام کرتی ہے](#میموری-کیسے-کام-کرتی-ہے) +- [LangChain4j کیسے استعمال کرتا ہے](#langchain4j-کیسے-استعمال-کرتا-ہے) +- [Azure OpenAI انفراسٹرکچر تعینات کریں](#azure-openai-انفراسٹرکچر-تعینات-کریں) +- [ایپلیکیشن کو لوکل طور پر چلائیں](#ایپلیکیشن-کو-لوکل-طور-پر-چلائیں) +- [ایپلیکیشن کا استعمال](#ایپلیکیشن-کا-استعمال) + - [بغیر حالت چیٹ (بائیں پینل)](#بغیر-حالت-چیٹ-بائیں-پینل) + - [حالت دار چیٹ (دائیں پینل)](#حالت-دار-چیٹ-دائیں-پینل) +- [اگلے اقدامات](#اگلے-اقدامات) ## ویڈیو واک تھرو -اس لائیو سیشن کو دیکھیں جو اس ماڈیول کے ساتھ شروع کرنے کا طریقہ بتاتا ہے: +اس لائیو سیشن کو دیکھیں جو اس ماڈیول کے ساتھ شروعات کرنے کی وضاحت کرتا ہے: -LangChain4j کے ساتھ شروع کرنا - لائیو سیشن +Getting Started with LangChain4j - Live Session ## آپ کیا سیکھیں گے -اس فوری آغاز میں، آپ نے GitHub ماڈلز استعمال کرکے پرامپٹس بھیجے، ٹولز کال کیے، RAG پائپ لائن بنائی، اور گارڈریل آزمایا۔ وہ ڈیموز دکھاتے ہیں کہ کیا ممکن ہے — اب ہم Azure OpenAI اور GPT-5.2 پر سوئچ کرتے ہیں اور پروڈکشن انداز کی ایپلیکیشنز بنانا شروع کرتے ہیں۔ یہ ماڈیول بات چیت کی AI پر توجہ دیتا ہے جو سیاق و سباق کو یاد رکھتی ہے اور ریاست کو برقرار رکھتی ہے — وہ تصورات جو فوری آغاز کے ڈیموز نے پردے کے پیچھے استعمال کیے لیکن واضح نہیں کیے۔ +یہ LangChain4j اور Azure OpenAI کے ساتھ آپ کی شروعات ہے۔ ہم بنیادی باتوں سے آغاز کرتے ہیں اور پروڈکشن طرز کی ایپلیکیشنز بنانا شروع کرتے ہیں۔ یہ ماڈیول مکالماتی AI پر مرکوز ہے جو سیاق و سباق یاد رکھتا ہے اور حالت برقرار رکھتا ہے — بنیادی تصورات جن پر ہر بعد والا ماڈیول تعمیر ہوتا ہے۔ -ہم اس رہنما میں Azure OpenAI کا GPT-5.2 استعمال کریں گے کیونکہ اس کی اعلیٰ استدلال کی قابلیت مختلف پیٹرنز کے رویے کو زیادہ واضح کرتی ہے۔ جب آپ میموری شامل کریں گے، تو فرق بآسانی دیکھیں گے۔ اس سے آپ کی ایپلیکیشن میں ہر جزو کے کردار کو سمجھنا آسان ہو جائے گا۔ +ہم اس گائیڈ میں Azure OpenAI کا GPT-5.2 استعمال کریں گے کیونکہ اس کی ترقی یافتہ منطق مختلف پیٹرنز کے رویے کو زیادہ واضح بناتی ہے۔ جب آپ میموری شامل کریں گے، تو فرق واضح طور پر نظر آئے گا۔ یہ سمجھنا آسان بناتا ہے کہ ہر جزو آپ کی ایپلیکیشن میں کیا فرق لے کر آتا ہے۔ -آپ ایک ایسی ایپلیکیشن بنائیں گے جو دونوں پیٹرنز کو ظاہر کرتی ہے: +آپ ایک ایسی ایپلیکیشن بنائیں گے جو دونوں پیٹرنز کو ظاہر کرے: -**بے ریاست چیٹ** – ہر درخواست خودمختار ہے۔ ماڈل کو پچھلے پیغامات کا کوئی علم نہیں ہوتا۔ یہ وہی پیٹرن ہے جو آپ نے فوری آغاز میں استعمال کیا تھا۔ +**بغیر حالت چیٹ** - ہر درخواست آزاد ہوتی ہے۔ ماڈل کو پچھلے پیغامات کی کوئی یادداشت نہیں ہوتی۔ یہ سب سے آسان شروعات ہے۔ -**ریاستی بات چیت** – ہر درخواست میں گفتگو کی تاریخ شامل ہوتی ہے۔ ماڈل متعدد چکروں میں سیاق و سباق کو برقرار رکھتا ہے۔ یہی پروڈکشن ایپلیکیشنز کے لیے ضروری ہے۔ +**حالت دار گفتگو** - ہر درخواست میں گفتگو کی تاریخ شامل ہوتی ہے۔ ماڈل متعدد مباحثوں میں سیاق و سباق برقرار رکھتا ہے۔ یہی پروڈکشن ایپلیکیشنز کے لیے ضروری ہے۔ -## مقدمات +## اہم تقاضے - Azure سبسکرپشن جس میں Azure OpenAI تک رسائی ہو -- Java 21، Maven 3.9+ +- جاوا 21، میون 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **نوٹ:** Java، Maven، Azure CLI اور Azure Developer CLI (azd) مہیا کردہ devcontainer میں پہلے سے نصب ہیں۔ +> **نوٹ:** جاوا، میون، Azure CLI اور Azure Developer CLI (azd) فراہم کردہ devcontainer میں پہلے سے انسٹال شدہ ہیں۔ -> **نوٹ:** یہ ماڈیول Azure OpenAI پر GPT-5.2 استعمال کرتا ہے۔ تعیناتی `azd up` کے ذریعے خودکار ہے - کوڈ میں ماڈل کا نام تبدیل نہ کریں۔ +> **نوٹ:** یہ ماڈیول Azure OpenAI پر GPT-5.2 استعمال کرتا ہے۔ تعیناتی خودکار طریقے سے `azd up` کے ذریعے کی جاتی ہے - کوڈ میں ماڈل کا نام تبدیل نہ کریں۔ -## بنیادی مسئلہ سمجھنا +## بنیادی مسئلے کو سمجھنا -لینگویج ماڈلز بے ریاست ہوتے ہیں۔ ہر API کال آزاد ہوتی ہے۔ اگر آپ "میرا نام جان ہے" بھیجیں اور پھر پوچھیں "میرا نام کیا ہے؟"، تو ماڈل کو معلوم نہیں کہ آپ نے خود کو متعارف کرایا تھا۔ یہ ہر درخواست کو پہلی گفتگو کی طرح فرض کرتا ہے۔ +لسانی ماڈلز بغیر حالت کے ہوتے ہیں۔ ہر API کال آزاد ہوتی ہے۔ اگر آپ "میرا نام جان ہے" کہیں اور پھر پوچھیں "میرا نام کیا ہے؟"، تو ماڈل کو معلوم نہیں کہ آپ نے ابھی اپنا تعارف کرایا ہے۔ یہ ہر درخواست کو اس طرح سمجھتا ہے جیسے آپ کا یہ پہلا گفتگو ہو۔ -یہ سادہ سوال و جواب کے لیے ٹھیک ہے لیکن حقیقی ایپلیکیشنز کے لیے بے کار ہے۔ کسٹمر سروس بوٹس کو یاد رکھنا ہوتا ہے کہ آپ نے کیا کہا۔ ذاتی معاونوں کو سیاق و سباق کی ضرورت ہوتی ہے۔ کسی بھی کثیر الجہتی گفتگو کے لیے میموری ضروری ہے۔ +یہ سادہ سوال جواب کے لیے ٹھیک ہے مگر حقیقی ایپلیکیشنز کے لیے غیر کارآمد ہے۔ کسٹمر سروس بوٹس کو یاد رکھنا ضروری ہوتا ہے کہ آپ نے کیا کہا تھا۔ ذاتی اسسٹنٹس کو سیاق و سباق چاہیے۔ کوئی بھی کثیر مباحثہ گفتگو میموری کا تقاضا کرتی ہے۔ -ذیل میں دیا گیا خاکہ دونوں طریقوں کا موازنہ کرتا ہے — بائیں طرف، بے ریاست کال جو آپ کا نام بھول جاتی ہے؛ دائیں طرف، ریاستی کال جسے ChatMemory سپورٹ کرتی ہے اور جو اسے یاد رکھتی ہے۔ +مندرجہ ذیل خاکہ دونوں طریقوں کا موازنہ کرتا ہے — بائیں جانب بغیر حالت کال جو آپ کا نام بھول جاتی ہے؛ دائیں جانب حالت دار کال جو ChatMemory کے ساتھ آپ کا نام یاد رکھتی ہے۔ -بے ریاست بمقابلہ ریاستی گفتگو +Stateless vs Stateful Conversations -*بے ریاست (آزاد کالز) اور ریاستی (سیاق آگاہ) گفتگوؤں کے درمیان فرق* +*بغیر حالت (آزاد کالز) اور حالت دار (سیاق و سباق جاننے والی) گفتگو کے درمیان فرق* ## ٹوکنز کو سمجھنا -بات چیت میں غوطہ لگانے سے پہلے، ٹوکنز کو سمجھنا ضروری ہے — وہ بنیادی یونٹس متن کے جنہیں لینگویج ماڈلز پروسیس کرتے ہیں: +گفتگو میں جانے سے پہلے، ٹوکنز کو سمجھنا ضروری ہے — زبان کے ماڈلز جو متن کو پروسیس کرتے ہیں ان کی بنیادی اکائیاں: -ٹوکن کی وضاحت +Token Explanation -*مثال کہ کس طرح متن کو ٹوکنز میں توڑا جاتا ہے - "I love AI!" چار الگ پروسیسنگ یونٹس بن جاتے ہیں* +*متن کو ٹوکنز میں کیسے توڑا جاتا ہے کی مثال - "I love AI!" چار الگ پروسیسنگ یونٹس بن جاتے ہیں* -ٹوکنز AI ماڈلز کے لیے متن کی پیمائش اور پروسیسنگ کا ذریعہ ہیں۔ الفاظ، رموزِ اعراب، اور یہاں تک کہ خالی جگہیں بھی ٹوکن ہو سکتی ہیں۔ آپ کے ماڈل کی ایک حد ہوتی ہے کہ وہ کتنے ٹوکنز ایک ساتھ پروسیس کر سکتا ہے (GPT-5.2 کے لیے 400,000، جن میں 272,000 ان پٹ ٹوکنز اور 128,000 آؤٹ پٹ ٹوکنز شامل ہیں)۔ ٹوکنز کو سمجھنا آپ کو گفتگو کی طوالت اور اخراجات کا انتظام کرنے میں مدد دیتا ہے۔ +ٹوکنز AI ماڈلز کے لیے متن کو ناپنے اور پروسیس کرنے کا ذریعہ ہیں۔ الفاظ، رموز، اور یہاں تک کہ اسپیسز بھی ٹوکنز ہو سکتے ہیں۔ آپ کے ماڈل کی ایک حد ہے کہ وہ ایک وقت میں کتنے ٹوکنز کو پروسیس کر سکتا ہے (GPT-5.2 کے لیے 400,000، جن میں سے 272,000 ان پٹ اور 128,000 آؤٹ پٹ ٹوکنز ہو سکتے ہیں)۔ ٹوکنز کو سمجھنا مدد دیتا ہے آپ کو گفتگو کی لمبائی اور لاگت کا انتظام کرنے میں۔ ## میموری کیسے کام کرتی ہے -چیٹ میموری بے ریاست مسئلہ حل کرتی ہے کیونکہ یہ گفتگو کی تاریخ کو برقرار رکھتی ہے۔ ماڈل کو درخواست بھیجنے سے پہلے، فریم ورک متعلقہ پچھلے پیغامات کو شامل کرتا ہے۔ جب آپ پوچھتے ہیں "میرا نام کیا ہے؟"، تو نظام حقیقت میں پوری گفتگو کی تاریخ بھیجتا ہے، جس سے ماڈل دیکھ سکتا ہے کہ آپ نے پہلے کہا تھا "میرا نام جان ہے"۔ +چیٹ میموری بغیر حالت کے مسئلے کو گفتگو کی تاریخ برقرار رکھ کر حل کرتی ہے۔ ماڈل کو آپ کی درخواست بھیجنے سے پہلے، فریم ورک متعلقہ پچھلے پیغامات شامل کرتا ہے۔ جب آپ پوچھتے ہیں "میرا نام کیا ہے؟"، تو سسٹم حقیقت میں پوری گفتگو کی تاریخ بھیجتا ہے، جس سے ماڈل دیکھ سکتا ہے کہ آپ نے پہلے کہا تھا "میرا نام جان ہے۔" -LangChain4j میموری کے نفاذ فراہم کرتا ہے جو یہ خودکار طریقے سے ہینڈل کرتا ہے۔ آپ منتخب کرتے ہیں کہ کتنے پیغامات رکھے جائیں اور فریم ورک سیاق و سباق کی ونڈو کا انتظام کرتا ہے۔ ذیل کا خاکہ دکھاتا ہے کہ MessageWindowChatMemory کیسے حالیہ پیغامات کی سلائیڈنگ ونڈو برقرار رکھتا ہے۔ +LangChain4j ایسی میموری کی امپلیمنٹس فراہم کرتا ہے جو خودکار طریقے سے یہ سنبھالتی ہیں۔ آپ طے کرتے ہیں کہ کتنے پیغامات محفوظ کرنے ہیں اور فریم ورک سیاق و سباق کی ونڈو کو منظم کرتا ہے۔ نیچے دیا گیا خاکہ دکھاتا ہے کہ MessageWindowChatMemory حالیہ پیغامات کی سلائڈنگ ونڈو کیسے برقرار رکھتی ہے۔ -میموری ونڈو کا تصور +Memory Window Concept -*MessageWindowChatMemory حالیہ پیغامات کی سلائیڈنگ ونڈو برقرار رکھتا ہے، پرانے پیغامات خود بخود حذف کر دیتا ہے* +*MessageWindowChatMemory حالیہ پیغامات کی سلائڈنگ ونڈو برقرار رکھتی ہے، خود بخود پرانے پیغامات کو حذف کرتی ہے* -## یہ LangChain4j کیسے استعمال کرتا ہے +## LangChain4j کیسے استعمال کرتا ہے -یہ ماڈیول فوری آغاز کو توسیع دیتا ہے، Spring Boot کو شامل کرتا ہے اور بات چیت کی میموری کا اضافہ کرتا ہے۔ یہاں پر اجزاء کیسے جڑتے ہیں: +یہ ماڈیول Spring Boot کو یکجا کرتا ہے اور گفتگو کی میموری شامل کرتا ہے۔ یہ ہے کہ اجزاء کیسے جُڑتے ہیں: -**انحصار** - دو LangChain4j لائبریریاں شامل کریں: +**ڈیپینڈنسیز** — دو LangChain4j لائبریریز شامل کریں: ```xml @@ -94,7 +94,7 @@ LangChain4j میموری کے نفاذ فراہم کرتا ہے جو یہ خود ``` -**چیٹ ماڈل** - Azure OpenAI کو Spring bean کے طور پر کنفیگر کریں ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**چیٹ ماڈل** — Azure OpenAI کو Spring bean کے طور پر کنفیگر کریں ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -بلڈر `azd up` کے ذریعہ سیٹ کی گئی ماحول کی متغیرات سے اسناد پڑھتا ہے۔ `baseUrl` کو اپنے Azure endpoint پر سیٹ کرنے سے OpenAI کلائنٹ Azure OpenAI کے ساتھ کام کرتا ہے۔ +بلڈر environment variables سے اسناد پڑھتا ہے جو `azd up` نے سیٹ کی ہیں۔ `baseUrl` کو آپ کے Azure اینڈپوائنٹ پر سیٹ کرنے سے OpenAI کلائنٹ Azure OpenAI کے ساتھ کام کرتا ہے۔ -**بات چیت کی میموری** - MessageWindowChatMemory کے ساتھ چیٹ ہسٹری کو ٹریک کریں ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): +**گفتگو میموری** — MessageWindowChatMemory کے ساتھ چیٹ ہسٹری کو ٹریک کریں ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,51 +124,51 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -`withMaxMessages(10)` کے ساتھ میموری بنائیں تاکہ آخری 10 پیغامات رکھے جائیں۔ صارف اور AI پیغامات کو ذیلی طبقوں کے ساتھ شامل کریں: `UserMessage.from(text)` اور `AiMessage.from(text)`۔ تاریخ کو `memory.messages()` سے حاصل کریں اور ماڈل کو بھیجیں۔ سروس ہر گفتگو ID کے لیے الگ الگ میموری انسٹنس محفوظ کرتی ہے، جس سے متعدد صارفین بیک وقت بات چیت کر سکتے ہیں۔ +میموری تخلیق کریں `withMaxMessages(10)` کے ساتھ تاکہ آخری 10 پیغامات محفوظ ہوں۔ یوزر اور AI پیغامات کو ٹائپڈ ریپیرز کے ساتھ شامل کریں: `UserMessage.from(text)` اور `AiMessage.from(text)`۔ `memory.messages()` کے ذریعے تاریخ بازیافت کریں اور اسے ماڈل کو بھیجیں۔ سروس ہر گفتگو کی ID کے لیے الگ میموری انسٹنس ذخیرہ کرتی ہے، جو ایک ساتھ متعدد یوزرز کو چیٹ کرنے دیتی ہے۔ -> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ کوشش کریں:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) کھولیں اور پوچھیں: -> - "MessageWindowChatMemory یہ کیسے فیصلہ کرتا ہے کہ ونڈو بھری ہونے پر کون سے پیغامات چھوڑنے ہیں؟" -> - "کیا میں ان میموری اسٹوریج کو ڈیٹابیس کے ساتھ اپنی مرضی کے مطابق لاگو کر سکتا ہوں بجائے In-memory کے؟" -> - "میں پرانی گفتگو کی تاریخ کو کمپریس کرنے کے لیے خلاصہ کیسے شامل کر سکوں؟" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمائیں:** [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) کھولیں اور پوچھیں: +> - "MessageWindowChatMemory جب ونڈو مکمل ہو تو کون سے پیغامات حذف کرنے کا فیصلہ کیسے کرتا ہے؟" +> - "کیا میں میموری کو ان میموری کے بجائے ڈیٹا بیس میں اسٹور کرنے کی اپنی امپلیمنٹیشن کر سکتا ہوں؟" +> - "میں پرانی گفتگو کی تاریخ کو کمپریس کرنے کے لیے سمری کیسے شامل کر سکتا ہوں؟" -بے ریاست چیٹ اینڈپوائنٹ میموری کو بالکل چھوڑ دیتا ہے — بس `chatModel.chat(prompt)` جیسا کہ فوری آغاز میں تھا۔ ریاستی اینڈپوائنٹ پیغامات کو میموری میں شامل کرتا ہے، تاریخ حاصل کرتا ہے، اور ہر درخواست کے ساتھ وہ سیاق و سباق بھیجتا ہے۔ ماڈل کی کنفیگریشن ایک جیسی، لیکن پیٹرنز مختلف۔ +بغیر حالت چیٹ اینڈپوائنٹ میموری کو مکمل نظر انداز کرتا ہے - صرف `chatModel.chat(prompt)` جیسا کہ فوری شروعات میں ہوتا ہے۔ حالت دار اینڈپوائنٹ میموری میں پیغامات شامل کرتا ہے، تاریخ بازیافت کرتا ہے، اور ہر درخواست کے ساتھ وہ سیاق و سباق بھیجتا ہے۔ ماڈل کی کانفیگریشن ایک جیسی ہے، فرق صرف پیٹرنز میں ہے۔ ## Azure OpenAI انفراسٹرکچر تعینات کریں **Bash:** ```bash cd 01-introduction -azd up # رکنیت اور مقام منتخب کریں (eastus2 تجویز کیا گیا) +azd up # سبسکرپشن اور محل وقوع منتخب کریں (eastus2 تجویز کردہ) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # سبسکرپشن اور مقام منتخب کریں (eastus2 تجویز کیا گیا ہے) +azd up # سبسکرپشن اور مقام منتخب کریں (eastus2 کی سفارش کی گئی) ``` -> **نوٹ:** اگر آپ کو ٹائم آؤٹ ایرر (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) ملے تو بس `azd up` دوبارہ چلائیں۔ Azure کے وسائل پس منظر میں تعیناتی کے عمل میں ہو سکتے ہیں، اور دوبارہ کوشش کرنے سے تعیناتی مکمل ہو جاتی ہے جب وسائل حتمی حالت میں آ جائیں۔ +> **نوٹ:** اگر آپ کو ٹائم آؤٹ ایرر (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`) ملے تو بس دوبارہ `azd up` چلائیں۔ Azure ریسورسز ابھی پس منظر میں provision ہو رہے ہوتے ہیں، اور دوبارہ کوشش کرنے سے تعیناتی مکمل ہو جاتی ہے جب ریسورسز terminal state تک پہنچیں۔ یہ کرے گا: -1. GPT-5.2 اور text-embedding-3-small ماڈلز کے ساتھ Azure OpenAI ریسورس تعینات کرے گا -2. پراجیکٹ روٹ میں خودکار طور پر `.env` فائل جنریٹ کرے گا جس میں اسناد ہوں -3. تمام ضروری ماحول کی متغیرات سیٹ کرے گا +1. Azure OpenAI ریسورس کو GPT-5.2 اور text-embedding-3-small ماڈلز کے ساتھ تعینات کرے گا +2. خودکار طریقے سے پراجیکٹ کے روٹ میں `.env` فائل تخلیق کرے گا جس میں اسناد ہوں گی +3. تمام ضروری environment variables سیٹ کرے گا -**تعمیراتی مسائل ہیں؟** تفصیلی ٹربل شوٹنگ کے لیے [Infrastructure README](infra/README.md) دیکھیں جن میں سبڈومین کے نام کی ٹکراؤ، دستی Azure پورٹل تعیناتی کے مراحل، اور ماڈل کنفیگریشن کی ہدایات شامل ہیں۔ +**تعیناتی کے مسائل؟** تفصیلی مسئلہ حل کے لیے [Infrastructure README](infra/README.md) دیکھیں، جس میں سب ڈومین نام کے تنازعات، دستی Azure Portal تعیناتی کے مراحل، اور ماڈل ترتیب کی رہنمائی شامل ہے۔ -**تعیناتی کی کامیابی کی تصدیق کریں:** +**تصدیق کریں کہ تعیناتی کامیاب ہوئی:** **Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT، API_KEY وغیرہ دکھانا چاہیے۔ +cat ../.env # AZURE_OPENAI_ENDPOINT، API_KEY، وغیرہ دکھانا چاہیے۔ ``` **PowerShell:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT، API_KEY وغیرہ کو دکھانا چاہیے۔ +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT، API_KEY، وغیرہ دکھانا چاہئے۔ ``` -> **نوٹ:** `azd up` کمانڈ خودکار طور پر `.env` فائل بناتا ہے۔ اگر آپ بعد میں اسے اپڈیٹ کرنا چاہتے ہیں، تو آپ یا تو `.env` فائل کو دستی طور پر ایڈٹ کریں یا اسے دوبارہ مندرجہ ذیل کمانڈز سے جنریٹ کریں: +> **نوٹ:** `azd up` کمانڈ خودکار طور پر `.env` فائل جنریٹ کرتا ہے۔ اگر آپ کو اسے بعد میں اپ ڈیٹ کرنا ہو، تو آپ یا تو `.env` فائل کو دستی طور پر ایڈیٹ کریں یا اسے دوبارہ بنانے کے لیے چلائیں: > > **Bash:** > ```bash @@ -182,43 +182,43 @@ Get-Content ..\.env # AZURE_OPENAI_ENDPOINT، API_KEY وغیرہ کو دکھا > .\.azd-env.ps1 > ``` -## ایپلیکیشن کو مقامی طور پر چلائیں +## ایپلیکیشن کو لوکل طور پر چلائیں -**تعیناتی کی تصدیق کریں:** +**تصدیق کریں تعیناتی مکمل ہے:** -اس بات کو یقینی بنائیں कि `.env` فائل روٹ ڈائریکٹری میں موجود ہو جس میں Azure کی اسناد ہوں۔ اس ماڈیول کی ڈائریکٹری (`01-introduction/`) سے یہ چلائیں: +یقین دہانی کریں کہ `.env` فائل روٹ ڈائریکٹری میں Azure اسناد کے ساتھ موجود ہے۔ اسے ماڈیول ڈائریکٹری (`01-introduction/`) سے چلائیں: **Bash:** ```bash -cat ../.env # دکھانا چاہیے AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT +cat ../.env # AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT دکھانا چاہئے ``` **PowerShell:** ```powershell -Get-Content ..\.env # دکھانا چاہیے AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT +Get-Content ..\.env # AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT دکھانا چاہیے ``` **ایپلیکیشنز شروع کریں:** -**اختیار 1: Spring Boot ڈیش بورڈ کا استعمال (VS Code صارفین کے لیے سفارش کردہ)** +**اختیار 1: Spring Boot ڈیش بورڈ استعمال کریں (VS Code صارفین کے لیے تجویز کردہ)** -devcontainer میں Spring Boot ڈیش بورڈ ایکسٹینشن شامل ہے جو تمام Spring Boot ایپلیکیشنز کو منظم کرنے کے لیے بصری انٹرفیس فراہم کرتا ہے۔ آپ اسے VS Code کی بائیں طرف ایکٹیویٹی بار میں Spring Boot آئیکن کے ذریعے دیکھ سکتے ہیں۔ +devcontainer میں Spring Boot Dashboard ایکسٹینشن شامل ہے، جو تمام Spring Boot ایپلیکیشنز کو منظم کرنے کے لیے بصری انٹرفیس فراہم کرتا ہے۔ آپ اسے VS Code کی Activity Bar کے بائیں جانب Spring Boot آئیکن کے ذریعے دیکھ سکتے ہیں۔ -Spring Boot ڈیش بورڈ سے آپ کر سکتے ہیں: -- ورک اسپیس کی تمام Spring Boot ایپلیکیشنز دیکھیں +Spring Boot Dashboard سے آپ کر سکتے ہیں: +- ورک اسپیس میں موجود تمام Spring Boot ایپلیکیشنز دیکھیں - ایک کلک سے ایپلیکیشنز شروع/روکیں -- ایپلیکیشن لاگز کو حقیقی وقت میں دیکھیں -- ایپلیکیشن کی حالت مانیٹر کریں +- ریئل ٹائم میں ایپلیکیشن لاگز دیکھیں +- ایپلیکیشن کی صورتحال مانیٹر کریں -بس "introduction" کے ساتھ موجود پلے بٹن پر کلک کریں تاکہ یہ ماڈیول شروع ہو، یا ایک ساتھ تمام ماڈیولز شروع کریں۔ +بس "introduction" کے ساتھ پلے بٹن پر کلک کریں تاکہ یہ ماڈیول شروع ہو، یا تمام ماڈیولز ایک ساتھ شروع کریں۔ -Spring Boot ڈیش بورڈ +Spring Boot Dashboard -*VS Code میں Spring Boot ڈیش بورڈ — ایک جگہ سے تمام ماڈیولز شروع، روکیں، اور مانیٹر کریں* +*VS Code میں Spring Boot Dashboard — تمام ماڈیولز کو ایک جگہ سے شروع، روکیں اور مانیٹر کریں* -**اختیار 2: شیل اسکرپٹس کا استعمال** +**اختیار 2: شیل اسکرپٹس استعمال کریں** -تمام ویب ایپلیکیشنز (ماڈیولز 01-04) شروع کریں: +تمام ویب ایپلیکیشنز شروع کریں (ماڈیولز 01-04): **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -دونوں اسکرپٹ خودکار طور پر روٹ `.env` فائل سے ماحول کی متغیرات لوڈ کرتے ہیں اور اگر JARs موجود نہیں تو بنا دیتے ہیں۔ +دونوں اسکرپٹس خودکار طور پر روٹ `.env` فائل سے environment variables لوڈ کرتے ہیں اور اگر JARs موجود نہ ہوں تو انہیں بنائیں گے۔ -> **نوٹ:** اگر آپ شروع کرنے سے پہلے تمام ماڈیولز خود دستی طور پر بنانا چاہتے ہیں: +> **نوٹ:** اگر آپ تمام ماڈیولز کو شروع کرنے سے پہلے دستی طور پر بنانا چاہیں: > > **Bash:** > ```bash @@ -262,9 +262,9 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -http://localhost:8080 اپنے براؤزر میں کھولیں۔ +اپنے براؤزر میں http://localhost:8080 کھولیں۔ -**روکنے کے لیے:** +**رکنے کے لیے:** **Bash:** ```bash @@ -275,36 +275,36 @@ cd .. && ./stop-all.sh # تمام ماڈیولز **PowerShell:** ```powershell -.\stop.ps1 # صرف یہ ماڈیول +.\stop.ps1 # یہ ماڈیول صرف # یا cd ..; .\stop-all.ps1 # تمام ماڈیولز ``` ## ایپلیکیشن کا استعمال -ایپلیکیشن ایک ویب انٹرفیس فراہم کرتی ہے جس میں دو چیٹ کے نفاذ ساتھ ساتھ ہیں۔ +ایپلیکیشن ویب انٹرفیس فراہم کرتی ہے جس میں دو چیٹ امپلیمنٹیشنز ساتھ ساتھ ہیں۔ -ایپلیکیشن کا ہوم اسکرین +Application Home Screen -*ڈیش بورڈ جو دونوں سادہ چیٹ (بے ریاست) اور گفتگو چیٹ (ریاستی) اختیارات دکھاتا ہے* +*ڈیش بورڈ جو دونوں سادہ چیٹ (بغیر حالت) اور مکالماتی چیٹ (حالت دار) آپشنز دکھاتا ہے* -### بے ریاست چیٹ (بائیں پینل) +### بغیر حالت چیٹ (بائیں پینل) -سب سے پہلے یہ آزمائیں۔ پوچھیں "میرا نام جان ہے" اور فوراً بعد "میرا نام کیا ہے؟" ماڈل یاد نہیں رکھے گا کیونکہ ہر پیغام خود مختار ہوتا ہے۔ یہ بنیادی لینگویج ماڈل انضمام کا بنیادی مسئلہ ظاہر کرتا ہے — کوئی گفتگو کا سیاق و سباق نہیں۔ +پہلے یہ آزمائیں۔ کہیں "میرا نام جان ہے" اور فوراً پوچھیں "میرا نام کیا ہے؟" ماڈل یاد نہیں رکھے گا کیونکہ ہر پیغام آزاد ہوتا ہے۔ یہ بنیادی زبان ماڈل انضمام کی اصل مسئلہ کو ظاہر کرتا ہے - کوئی گفتگو کا سیاق و سباق نہیں۔ -بے ریاست چیٹ ڈیمو +Stateless Chat Demo *AI پچھلے پیغام سے آپ کا نام یاد نہیں رکھتا* -### ریاستی چیٹ (دائیں پینل) +### حالت دار چیٹ (دائیں پینل) -اب وہی سلسلہ یہاں آزمائیں۔ پوچھیں "میرا نام جان ہے" اور پھر "میرا نام کیا ہے؟" اس بار یہ یاد رکھتا ہے۔ فرق MessageWindowChatMemory ہے — یہ گفتگو کی تاریخ برقرار رکھتا ہے اور اسے ہر درخواست کے ساتھ شامل کرتا ہے۔ یہی پروڈکشن گفتگو AI کا طریقہ کار ہے۔ +اب یہاں وہی سلسلہ آزمائیں۔ کہیں "میرا نام جان ہے" اور پھر "میرا نام کیا ہے؟" اس بار یہ یاد رکھتا ہے۔ فرق MessageWindowChatMemory ہے — یہ گفتگو کی تاریخ محفوظ رکھتا ہے اور ہر درخواست کے ساتھ شامل کرتا ہے۔ یہی طریقہ کار پروڈکشن مکالماتی AI میں ہوتا ہے۔ -ریاستی چیٹ ڈیمو +Stateful Chat Demo -*AI گفتگو کے آغاز سے آپ کا نام یاد رکھتا ہے* +*AI آپ کے گفتگو کے شروع میں کہا ہوا نام یاد رکھتا ہے* -دونوں پینلز میں وہی GPT-5.2 ماڈل استعمال ہوتا ہے۔ فرق صرف میموری ہے۔ یہ واضح کرتا ہے کہ میموری آپ کی ایپلیکیشن میں کیا کردار ادا کرتی ہے اور کیوں یہ حقیقی استعمال کے لیے ضروری ہے۔ +دونوں پینلز ایک ہی GPT-5.2 ماڈل استعمال کرتے ہیں۔ واحد فرق میموری ہے۔ یہ واضح کرتا ہے کہ میموری آپ کی ایپلیکیشن میں کیا قدر لاتی ہے اور یہ حقیقی استعمال کے لیے ضروری کیوں ہے۔ ## اگلے اقدامات @@ -312,11 +312,11 @@ cd ..; .\stop-all.ps1 # تمام ماڈیولز --- -**نیویگیشن:** [← پچھلا: ماڈیول 00 - فوری آغاز](../00-quick-start/README.md) | [واپس مرکزی صفحے پر](../README.md) | [اگلا: ماڈیول 02 - پرامپٹ انجینئرنگ →](../02-prompt-engineering/README.md) +**نیویگیشن:** [← واپس مرکزی صفحہ](../README.md) | [آگے: ماڈیول 02 - پرامپٹ انجینئرنگ →](../02-prompt-engineering/README.md) --- -**دستخطی بیان**: -یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ اگرچہ ہم درستگی کے لئے کوشاں ہیں، براہ کرم نوٹ کریں کہ خودکار تراجم میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنی مادری زبان میں معتبر ذریعہ سمجھی جانی چاہیے۔ اہم معلومات کے لیے پیشہ ور انسانی ترجمہ تجویز کیا جاتا ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم پر نہیں ہوگی۔ +**ڈس کلیمر**: +یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔ \ No newline at end of file diff --git a/translations/ur/02-prompt-engineering/README.md b/translations/ur/02-prompt-engineering/README.md index 4fb7a76d1..86b084625 100644 --- a/translations/ur/02-prompt-engineering/README.md +++ b/translations/ur/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ # ماڈیول 02: GPT-5.2 کے ساتھ پرامپٹ انجینئرنگ -## فہرست مضامین - -- [ویڈیو واک تھرو](../../../02-prompt-engineering) -- [آپ کیا سیکھیں گے](../../../02-prompt-engineering) -- [ضروریات](../../../02-prompt-engineering) -- [پرامپٹ انجینئرنگ کی سمجھ](../../../02-prompt-engineering) -- [پرامپٹ انجینئرنگ کی بنیادیں](../../../02-prompt-engineering) - - [زیرو شوٹ پرامپٹنگ](../../../02-prompt-engineering) - - [فیوشوٹ پرامپٹنگ](../../../02-prompt-engineering) - - [چین آف تھوٹ](../../../02-prompt-engineering) - - [رول بیسڈ پرامپٹنگ](../../../02-prompt-engineering) - - [پرامپٹ ٹیمپلیٹس](../../../02-prompt-engineering) -- [اپ گریڈ شدہ پیٹرنز](../../../02-prompt-engineering) -- [ایپلیکیشن چلائیں](../../../02-prompt-engineering) -- [ایپلیکیشن کے اسکرین شاٹس](../../../02-prompt-engineering) -- [پیٹرنز کا جائزہ](../../../02-prompt-engineering) - - [کم بمقابلہ زیادہ ولولہ](../../../02-prompt-engineering) - - [ٹاسک ایکزیکیوشن (ٹول پری ایمبلز)](../../../02-prompt-engineering) - - [سیلف ریفلیکٹنگ کوڈ](../../../02-prompt-engineering) - - [ساختی تجزیہ](../../../02-prompt-engineering) - - [کئی مرحلوں والی بات چیت](../../../02-prompt-engineering) - - [قدم بہ قدم منطق](../../../02-prompt-engineering) - - [محدود خارج](../../../02-prompt-engineering) -- [آپ واقعی کیا سیکھ رہے ہیں](../../../02-prompt-engineering) -- [اگلے اقدامات](../../../02-prompt-engineering) +## مندرجات + +- [ویڈیو واک تھرو](#ویڈیو-واک-تھرو) +- [آپ کیا سیکھیں گے](#آپ-کیا-سیکھیں-گے) +- [درکار شرائط](#درکار-شرائط) +- [پرامپٹ انجینئرنگ کو سمجھنا](#پرامپٹ-انجینئرنگ-کو-سمجھنا) +- [پرامپٹ انجینئرنگ کے بنیادی اصول](#پرامپٹ-انجینئرنگ-کے-بنیادی-اصول) + - [زیرو شاٹ پرامپٹنگ](#زیرو-شاٹ-پرامپٹنگ) + - [فیوشاٹ پرامپٹنگ](#فیوشاٹ-پرامپٹنگ) + - [چین آف تھوٹ](#چین-آف-تھوٹ) + - [رول پر مبنی پرامپٹنگ](#رول-پر-مبنی-پرامپٹنگ) + - [پرامپٹ ٹیمپلیٹس](#پرامپٹ-ٹیمپلیٹس) +- [جدید نمونے](#جدید-نمونے) +- [ایپلیکیشن چلائیں](#ایپلیکیشن-چلائیں) +- [ایپلیکیشن کے اسکرین شاٹس](#ایپلیکیشن-اسکرین-شاٹس) +- [نمونوں کی تلاش](#پیٹرنز-کی-دریافت) + - [کم بمقابلہ زیادہ جوش](#کم-بمقابلہ-زیادہ-جوش) + - [ٹاسک ایکزیکیوشن (ٹول پری ایمبلز)](#ٹاسک-ایگزیکیوشن-ٹول-پری-ایمبلز) + - [خود انعکاسی کوڈ](#خود-عکاسی-کرنے-والا-کوڈ) + - [مُرَتب تجزیہ](#منظم-تجزیہ) + - [کثیر مرحلہ چیٹ](#کثیر-دفعہ-چیٹ) + - [قدم بہ قدم استدلال](#مرحلہ-وار-استدلال) + - [محصور آؤٹ پٹ](#محدود-شدہ-آؤٹ-پٹ) +- [آپ واقعی کیا سیکھ رہے ہیں](#آپ-اصل-میں-کیا-سیکھ-رہے-ہیں) +- [اگلے اقدامات](#اگلے-مراحل) ## ویڈیو واک تھرو -اس لائیو سیشن کو دیکھیں جو وضاحت کرتا ہے کہ اس ماڈیول کے ساتھ کیسے شروع کیا جائے: +اس لائیو سیشن کو دیکھیں جو اس ماڈیول کے ساتھ شروعات کرنے کا طریقہ بتاتا ہے: -Prompt Engineering with LangChain4j - Live Session +LangChain4j کے ساتھ پرامپٹ انجینئرنگ - لائیو سیشن ## آپ کیا سیکھیں گے -مندرجہ ذیل خاکہ اس ماڈیول میں آپ کی ترقی کے لیے کلیدی موضوعات اور مہارتوں کا جائزہ پیش کرتا ہے—پرامپٹ بہتر بنانے کی تکنیکوں سے لے کر وہ مرحلہ وار ورک فلو جو آپ کو اپنانا ہوگا۔ +مندرجہ ذیل خاکہ اس ماڈیول میں آپ کن کلیدی موضوعات اور مہارتوں کو سیکھیں گے اس کا ایک جائزہ فراہم کرتا ہے — پرامپٹ کی بہتری کی تکنیکوں سے لے کر مرحلہ وار ورک فلو تک جو آپ فالو کریں گے۔ -What You'll Learn +آپ کیا سیکھیں گے -پچھلے ماڈیولز میں، آپ نے LangChain4j کے بنیادی تعاملات کو GitHub ماڈلز کے ساتھ دریافت کیا اور دیکھا کہ کس طرح یادداشت Azure OpenAI کے ساتھ بات چیت کرنے والی AI کو ممکن بناتی ہے۔ اب ہم توجہ مرکوز کریں گے کہ آپ سوالات کیسے پوچھتے ہیں—یعنی پرامپٹس خود—Azure OpenAI کے GPT-5.2 کا استعمال کرتے ہوئے۔ آپ کے پرامپٹس کی ساخت آپ کو موصول ہونے والے جوابات کی معیار پر نمایاں اثر ڈالتی ہے۔ ہم بنیادی پرامپٹنگ تکنیکوں کا جائزہ لیتے ہوئے شروع کریں گے، پھر آگے آٹھ اپ گریڈ شدہ پیٹرنز کی طرف بڑھیں گے جو GPT-5.2 کی صلاحیتوں کو مکمل طور پر استعمال کرتے ہیں۔ +پچھلے ماڈیول میں آپ نے دیکھا کہ کس طرح میموری Azure OpenAI کے ساتھ بات چیت کرنے والے AI کو ممکن بناتی ہے۔ اب ہم اس بات پر توجہ دیں گے کہ آپ سوالات کیسے پوچھتے ہیں — یعنی خود پرامپٹس — Azure OpenAI کے GPT-5.2 کا استعمال کرتے ہوئے۔ آپ کے پرامپٹس کی ساخت اس بات کو بہت متاثر کرتی ہے کہ آپ کو جوابات کیسا معیار ملتا ہے۔ ہم بنیادی پرامپٹنگ تکنیکوں کا جائزہ لے کر شروع کرتے ہیں، پھر آٹھ جدید نمونوں پر جاتے ہیں جو GPT-5.2 کی صلاحیتوں کا مکمل فائدہ اٹھاتے ہیں۔ -ہم GPT-5.2 استعمال کریں گے کیونکہ یہ استدلالی کنٹرول متعارف کرواتا ہے—آپ ماڈل کو بتا سکتے ہیں کہ جواب دینے سے پہلے کتنا سوچنا ہے۔ یہ مختلف پرامپٹنگ حکمت عملیوں کو واضح کرتا ہے اور آپ کو سمجھنے میں مدد دیتا ہے کہ کب کون سا طریقہ استعمال کرنا ہے۔ ہم Azure کی GPT-5.2 کے لیے کم ریٹ لمٹس سے بھی فائدہ اٹھائیں گے جو GitHub ماڈلز کے مقابلے میں بہتر ہے۔ +ہم GPT-5.2 استعمال کریں گے کیونکہ یہ استدلال کنٹرول متعارف کرواتا ہے — آپ ماڈل کو بتا سکتے ہیں کہ جواب دینے سے پہلے کتنا سوچنا ہے۔ اس سے مختلف پرامپٹنگ حکمت عملیاں زیادہ واضح ہوتی ہیں اور آپ کو سمجھنے میں مدد ملتی ہے کہ ہر طریقہ کب استعمال کرنا چاہیے۔ -## ضروریات +## درکار شرائط -- ماڈیول 01 مکمل کیا ہوا ہو (Azure OpenAI وسائل ڈپلائے کیے گئے ہوں) -- روٹ ڈائریکٹری میں `.env` فائل Azure کی سندوں کے ساتھ (جو ماڈیول 01 میں `azd up` کے ذریعے بنائی گئی ہو) +- ماڈیول 01 مکمل کر لیا ہو (Azure OpenAI وسائل نافذ کیے گئے) +- `.env` فائل روٹ ڈائرکٹری میں Azure کی اسناد کے ساتھ موجود ہو (جو ماڈیول 01 میں `azd up` سے بنائی گئی ہو) -> **نوٹ:** اگر آپ نے ماڈیول 01 مکمل نہیں کیا ہے، تو پہلے وہاں موجود ڈپلائے کرنے کی ہدایات پر عمل کریں۔ +> **نوٹ:** اگر آپ نے ماڈیول 01 مکمل نہیں کیا تو پہلے وہاں ڈپلائے کرنے کی ہدایات پر عمل کریں۔ -## پرامپٹ انجینئرنگ کی سمجھ +## پرامپٹ انجینئرنگ کو سمجھنا -بنیادی طور پر، پرامپٹ انجینئرنگ مبہم ہدایات اور واضح ہدایات کے درمیان فرق ہے، جیسا کہ درج ذیل موازنہ دکھاتا ہے۔ +بنیادی طور پر، پرامپٹ انجینئرنگ مبہم ہدایات اور واضح ہدایات کے درمیان فرق ہے، جیسا کہ نیچے دیا گیا موازنہ ظاہر کرتا ہے۔ -What is Prompt Engineering? +پرامپٹ انجینئرنگ کیا ہے؟ -پرامپٹ انجینئرنگ ایسی ان پٹ ٹیکسٹ ڈیزائن کرنے کے بارے میں ہے جو مستقل طور پر آپ کو مطلوبہ نتائج دیتی ہے۔ یہ صرف سوالات پوچھنے کی بات نہیں ہے—یہ درخواستوں کو اس طرح مرتب کرنے کی بات ہے کہ ماڈل بالکل سمجھ سکے کہ آپ کیا چاہتے ہیں اور کیسے فراہم کرنا ہے۔ +پرامپٹ انجینئرنگ کا مقصد ایسا ان پٹ متن ڈیزائن کرنا ہے جو مستقل طور پر آپ کو مطلوبہ نتائج دے۔ یہ صرف سوالات پوچھنے کے بارے میں نہیں ہے - بلکہ درخواستوں کو اس طرح ترتیب دینے کے بارے میں ہے کہ ماڈل بالکل سمجھے کہ آپ کیا چاہتے ہیں اور اسے کیسے فراہم کرنا ہے۔ -اسے ایسے سمجھیں جیسے آپ اپنے ساتھی کو ہدایات دے رہے ہوں۔ "Bug درست کریں" مبہم ہے۔ "UserService.java کی لائن 45 میں null pointer exception کو null چیک شامل کر کے درست کریں" مخصوص اور واضح ہے۔ زبان کے ماڈلز بھی اسی طرح کام کرتے ہیں—وضاحت اور ساخت اہمیت رکھتے ہیں۔ +اسے کسی ساتھی کو ہدایات دینے کے مترادف سمجھیں۔ "بگ درست کرو" مبہم ہے۔ "UserService.java کی لائن 45 میں نل پوائنٹر استثنا کو نل چیک شامل کرکے درست کریں" واضح ہے۔ زبان کے ماڈل بھی اسی طرح کام کرتے ہیں - وضاحت اور ساخت اہم ہیں۔ -ذیل کا خاکہ دکھاتا ہے کہ LangChain4j اس پروسیس میں کیسے فٹ ہوتا ہے—آپ کے پرامپٹ پیٹرنز کو SystemMessage اور UserMessage کی تعمیراتی اجزاء کے ذریعے ماڈل سے جوڑنا۔ +نیچے دیا گیا خاکہ دکھاتا ہے کہ LangChain4j اس تصویر میں کہاں فٹ بیٹھتا ہے — جو آپ کے پرامپٹ پیٹرنز کو SystemMessage اور UserMessage بیلڈنگ بلاکس کے ذریعے ماڈل سے جوڑتا ہے۔ -How LangChain4j Fits +LangChain4j کہاں فٹ بیٹھتا ہے -LangChain4j بنیادی ڈھانچہ فراہم کرتا ہے—ماڈل کنکشنز، میموری، اور پیغام کی اقسام—جبکہ پرامپٹ پیٹرنز صرف وہ متن ہوتے ہیں جو آپ اس ڈھانچے کے ذریعے بھیجتے ہیں۔ کلیدی اجزاء `SystemMessage` (جو AI کے رویے اور کردار کو مرتب کرتا ہے) اور `UserMessage` (جو آپ کی اصل درخواست لے کر آتا ہے) ہیں۔ +LangChain4j بنیادی ڈھانچہ مہیا کرتا ہے — ماڈل کنیکشنز، میموری، اور پیغام کی اقسام — جبکہ پرامپٹ پیٹرنز صرف وہ محتاط طور پر مرتب شدہ متن ہیں جو آپ اس بنیادی ڈھانچے کے ذریعے بھیجتے ہیں۔ کلیدی اجزاء ہیں `SystemMessage` (جو AI کے رویے اور کردار کو سیٹ کرتا ہے) اور `UserMessage` (جو آپ کی اصل درخواست لے کر آتا ہے)۔ -## پرامپٹ انجینئرنگ کی بنیادیں +## پرامپٹ انجینئرنگ کے بنیادی اصول -نیچے دکھائی گئی پانچ بنیادی تکنیکیں مؤثر پرامپٹ انجینئرنگ کی بنیاد ہیں۔ ہر ایک زبان کے ماڈلز سے بات چیت کے مختلف پہلو کو حل کرتی ہے۔ +نیچے دکھائی گئی پانچ بنیادی تکنیک موثر پرامپٹ انجینئرنگ کی بنیاد فراہم کرتی ہیں۔ ہر ایک زبان کے ماڈلز کے ساتھ آپ کی بات چیت کے ایک مختلف پہلو کو حل کرتا ہے۔ -Five Prompt Engineering Patterns Overview +پانچ پرامپٹ انجینئرنگ نمونوں کا جائزہ -ہم اس ماڈیول میں اپ گریڈ شدہ پیٹرنز میں جانے سے پہلے پانچ بنیادی پرامپٹنگ تکنیکوں کا جائزہ لیتے ہیں۔ یہ وہ تعمیراتی بلاکس ہیں جو ہر پرامپٹ انجینئر کو جاننا چاہیے۔ اگر آپ پہلے ہی [Quick Start ماڈیول](../00-quick-start/README.md#2-prompt-patterns) سے گزر چکے ہیں، تو آپ نے انہیں عملی طور پر دیکھا ہے—یہاں ان کے پیچھے کا نظریاتی فریم ورک ہے۔ +اس ماڈیول میں موجود جدید نمونوں میں جانے سے پہلے، پانچ بنیادی پرامپٹنگ تکنیکوں کا جائزہ لیتے ہیں۔ یہ وہ بنیادی اجزاء ہیں جو ہر پرامپٹ انجینئر کو معلوم ہونے چاہییں۔ -### زیرو شوٹ پرامپٹنگ +### زیرو شاٹ پرامپٹنگ -سب سے سادہ طریقہ: ماڈل کو براہ راست ہدایت دیں بغیر کسی مثال کے۔ ماڈل پورے عمل کو سمجھنے اور انجام دینے کے لیے اپنی تربیت پر انحصار کرتا ہے۔ یہ سیدھے سادے سوالات کے لیے بہتر کام کرتا ہے جہاں متوقع رویہ واضح ہو۔ +سب سے آسان طریقہ: ماڈل کو بغیر کسی مثال کے براہ راست ہدایت دیں۔ ماڈل مکمل طور پر اپنی تربیت پر انحصار کرتا ہے تاکہ کام کو سمجھ کر انجام دے۔ یہ سیدھے سادے سوالات کے لیے اچھا کام کرتا ہے جہاں متوقع رویہ واضح ہوتا ہے۔ -Zero-Shot Prompting +زیرو شاٹ پرامپٹنگ -*بغیر مثالوں کے براہ راست ہدایت—ماڈل صرف ہدایت سے ہی کام کا اندازہ لگاتا ہے* +*مثالوں کے بغیر براہ راست ہدایت — ماڈل صرف ہدایت سے ہی کام کا اندازہ لگاتا ہے* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// جواب: "مثبت" +// ردعمل: "مثبت" ``` -**استعمال کب کریں:** سادہ درجہ بندیاں، براہ راست سوالات، ترجمے، یا کوئی بھی کام جسے ماڈل بغیر اضافی رہنمائی کے انجام دے سکے۔ +**استعمال کب کریں:** آسان درجہ بندی، سیدھے سوالات، ترجمے، یا کوئی بھی کام جو ماڈل بغیر اضافی رہنمائی کے کر سکتا ہو۔ -### فیوشوٹ پرامپٹنگ +### فیوشاٹ پرامپٹنگ -ایسی مثالیں فراہم کریں جو ماڈل کو وہ پیٹرن سکھائیں جو آپ چاہتے ہیں وہ اپنائے۔ ماڈل آپ کی مثالوں سے مطلوبہ ان پٹ-آؤٹ پٹ فارمیٹ سیکھتا ہے اور نئے ان پٹ پر لاگو کرتا ہے۔ یہ ان کاموں کے لیے مستقل مزاجی کو بہت بہتر بناتا ہے جہاں متوقع انداز یا رویہ واضح نہیں ہوتا۔ +ایسی مثالیں فراہم کریں جو وہ پیٹرن ظاہر کریں جسے آپ چاہتے ہیں کہ ماڈل فالو کرے۔ ماڈل آپ کی مثالوں سے متوقع ان پٹ-آؤٹ پٹ فارمیٹ سیکھتا ہے اور نئے ان پٹس پر لاگو کرتا ہے۔ اس سے اس کام میں مستقل مزاجی بہت بہتر ہوتی ہے جہاں مطلوبہ فارمیٹ یا رویہ واضح نہ ہو۔ -Few-Shot Prompting +فیوشاٹ پرامپٹنگ -*مثالوں سے سیکھنا—ماڈل پیٹرن پہچانتا ہے اور نئے ان پٹس پر لاگو کرتا ہے* +*مثالوں سے سیکھنا — ماڈل پیٹرن کو پہچان کر نئے ان پٹس پر لاگو کرتا ہے* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**استعمال کب کریں:** حسب ضرورت درجہ بندیاں، مستقل فارمیٹنگ، مخصوص ڈومین کے کام، یا جب زیرو شوٹ کے نتائج غیر مستقل ہوں۔ +**استعمال کب کریں:** کسٹم درجہ بندیاں، مستقل فارمیٹنگ، مخصوص دائرہ کار کے کام، یا جب زیرو شاٹ نتائج غیر مستقل ہوں۔ ### چین آف تھوٹ -ماڈل کو اپنے استدلال کو قدم بہ قدم دکھانے کو کہیں۔ براہ راست جواب دینے کی بجائے ماڈل مسئلہ کو توڑ کر ہر حصے کو واضح طور پر حل کرتا ہے۔ یہ ریاضی، منطق، اور کثیر مرحلوں والے استدلال کے کاموں کی درستی میں بہتری لاتا ہے۔ +ماڈل سے کہیں کہ اپنا استدلال قدم بہ قدم ظاہر کرے۔ فوراً جواب دینے کی بجائے، ماڈل مسئلے کو توڑتا ہے اور ہر حصے کو واضح طور پر حل کرتا ہے۔ یہ ریاضی، منطق، اور کثیر مرحلہ استدلالی کاموں کی درستگی کو بہتر بناتا ہے۔ -Chain of Thought Prompting +چین آف تھوٹ پرامپٹنگ -*قدم بہ قدم استدلال—پیچیدہ مسائل کو واضح منطقی مراحل میں توڑنا* +*قدم بہ قدم استدلال — پیچیدہ مسائل کو واضح منطقی مراحل میں تقسیم کرنا* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // ماڈل دکھاتا ہے: 15 - 8 = 7، پھر 7 + 12 = 19 سیب ``` -**استعمال کب کریں:** ریاضی کے مسائل، منطقی پہیلیاں، ڈیبگنگ، یا کوئی بھی کام جہاں استدلالی عمل دکھانے سے درستی اور اعتماد بڑھتا ہے۔ +**استعمال کب کریں:** ریاضی کے مسائل، منطق کی پہیلیاں، ڈیبگنگ، یا کوئی بھی ایسا کام جہاں استدلال کا عمل ظاہر کرنا درستگی اور اعتماد بڑھائے۔ -### رول بیسڈ پرامپٹنگ +### رول پر مبنی پرامپٹنگ -اپنا سوال پوچھنے سے پہلے AI کے لیے ایک کردار یا شخصیت سیٹ کریں۔ یہ سیاق و سباق فراہم کرتا ہے جو جواب کے انداز، گہرائی، اور توجہ کو شکل دیتا ہے۔ "سافٹ ویئر آرکیٹیکٹ" مختلف مشورہ دیتا ہے بجائے "جونئیر ڈیویلپر" یا "سیکورٹی آڈیٹر" کے۔ +اپنا سوال پوچھنے سے پہلے AI کے لیے ایک کردار یا شخصیت سیٹ کریں۔ اس سے وہ سیاق و سباق ملتا ہے جو جواب کے لہجے، گہرائی، اور توجہ کو تشکیل دیتا ہے۔ ایک "سوفٹ ویئر آرکیٹیکٹ" کا مشورہ "جونئیر ڈیویلپر" یا "سیکیورٹی آڈیٹر" سے مختلف ہوتا ہے۔ -Role-Based Prompting +رول پر مبنی پرامپٹنگ -*سیاق و سباق اور کردار سیٹ کرنا—ایک سوال کو مختلف رولز کے تحت مختلف جواب ملتے ہیں* +*سیاق و سباق اور شخصیت کا تعین — ایک ہی سوال کو دیے گئے کردار کے حساب سے مختلف جواب ملتا ہے* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**استعمال کب کریں:** کوڈ ریویوز، ٹیوشنگ، مخصوص ڈومین کا تجزیہ، یا جب آپ کو مخصوص مہارت کے درجے یا نقطہ نظر کے مطابق جوابات چاہئیں۔ +**استعمال کب کریں:** کوڈ ریویوز، ٹیوٹرنگ، مخصوص دائرہ کار کا تجزیہ، یا جب آپ کو مخصوص مہارت کی سطح یا نقطہ نظر کے لیے جوابات درکار ہوں۔ ### پرامپٹ ٹیمپلیٹس -ری یوز ایبل پرامپٹس بنائیں جن میں متغیر جگہیں ہوں۔ ہر بار نیا پرامپٹ لکھنے کی بجائے، ایک ٹیمپلیٹ ایک دفعہ بنائیں اور مختلف قدریں اس میں بھریں۔ LangChain4j کا `PromptTemplate` کلاس یہ آسان بناتا ہے `{{variable}}` کی نحو کے ساتھ۔ +متغیر مقامات کے ساتھ دوبارہ استعمال ہونے والے پرامپٹس بنائیں۔ ہر بار نیا پرامپٹ لکھنے کے بجائے، ایک ٹیمپلیٹ بنائیں اور مختلف اقدار بھر دیں۔ LangChain4j کی `PromptTemplate` کلاس `{{variable}}` نحو کے ساتھ یہ آسان بناتی ہے۔ -Prompt Templates +پرامپٹ ٹیمپلیٹس -*متغیر جگہوں کے ساتھ ری یوز ایبل پرامپٹس—ایک ٹیمپلیٹ، متعدد استعمال* +*متغیر مقامات کے ساتھ دوبارہ استعمال ہونے والے پرامپٹس — ایک ٹیمپلیٹ، متعدد استعمالات* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**استعمال کب کریں:** مختلف ان پٹس کے ساتھ بار بار پوچھے جانے والے سوالات، بیچ پروسیسنگ، ری یوز ایبل AI ورک فلو بنانے، یا کوئی بھی صورت جہاں پرامپٹ کی ساخت وہی رہے مگر ڈیٹا مختلف ہو۔ +**استعمال کب کریں:** مختلف ان پٹس کے ساتھ بار بار سوالات، بیچ پراسیسنگ، دوبارہ استعمال کے قابل AI ورک فلو بنانے کے لیے، یا کوئی بھی ایسا منظر جہاں پرامپٹ کی ساخت ایک جیسی رہے مگر ڈیٹا بدلتا ہو۔ --- -یہ پانچ بنیادی باتیں آپ کو زیادہ تر پرامپٹنگ کاموں کے لیے ایک مضبوط ٹول کٹ دیتی ہیں۔ اس ماڈیول کے باقی حصے میں **آٹھ اپ گریڈ شدہ پیٹرنز** شامل ہیں جو GPT-5.2 کی استدلالی کنٹرول، خود جائزہ، اور ساختی آؤٹ پٹ صلاحیتوں کو استعمال کرتے ہیں۔ +یہ پانچ بنیادی اصول زیادہ تر پرامپٹنگ کاموں کے لیے آپ کو مضبوط ٹول کٹ فراہم کرتے ہیں۔ اس ماڈیول کا باقی حصہ ان پر مبنی ہے اور GPT-5.2 کی استدلال کنٹرول، خود تشخیص، اور مرصع آؤٹ پٹ صلاحیتوں کا فائدہ اٹھانے والے **آٹھ جدید نمونوں** پر مشتمل ہے۔ -## اپ گریڈ شدہ پیٹرنز +## جدید نمونے -بنیادی باتوں کے بعد، آئیں ان آٹھ اپ گریڈ شدہ پیٹرنز کی طرف بڑھیں جو اس ماڈیول کو منفرد بناتے ہیں۔ ہر مسئلہ ایک جیسا طریقہ نہیں مانگتا۔ کچھ سوالات کو فوری جواب چاہیے، کچھ گہری سوچ۔ کچھ کو واضح استدلال چاہیے، کچھ کو صرف نتائج۔ نیچے ہر پیٹرن کو ایک الگ صورت حال کے لیے بہترین بنایا گیا ہے—اور GPT-5.2 کا استدلالی کنٹرول فرق مزید نمایاں کر دیتا ہے۔ +بنیادی اصولوں کے بعد، آئیے آٹھ جدید نمونوں کی طرف بڑھتے ہیں جو اس ماڈیول کو منفرد بناتے ہیں۔ تمام مسائل کے لیے ایک جیسا طریقہ کار ضروری نہیں۔ کچھ سوالات کے فوری جواب درکار ہوتے ہیں، کچھ کے لیے گہرے غور کی ضرورت ہوتی ہے۔ کچھ کو واضح استدلال چاہیے، اور کچھ کو صرف نتائج۔ ذیل میں ہر نمونہ مختلف منظر نامے کے لیے بہتر بنایا گیا ہے — اور GPT-5.2 کی استدلال کنٹرول سے فرق اور واضح ہو جاتے ہیں۔ -Eight Prompting Patterns +آٹھ پرامپٹنگ نمونے -*آٹھ پرامپٹنگ پیٹرنز اور ان کے استعمال کے مواقع کا جائزہ* +*آٹھ پرامپٹ انجینئرنگ نمونوں اور ان کے استعمال کے معاملے کا جائزہ* -GPT-5.2 ان پیٹرنز میں ایک نیا پہلو شامل کرتا ہے: *استدلالی کنٹرول*۔ نیچے دیا گیا سلائیڈر دکھاتا ہے کہ آپ ماڈل کے سوچنے کی مقدار کو کیسے ایڈجسٹ کر سکتے ہیں—تیز، براہ راست جوابات سے گہری، مکمل تجزیہ تک۔ +GPT-5.2 ان نمونوں میں ایک اور جہت شامل کرتا ہے: *استدلال کنٹرول*۔ نیچے سلائیڈر دکھاتا ہے کہ آپ ماڈل کی سوچ کی مقدار کیسے ایڈجسٹ کر سکتے ہیں — فوری، براہ راست جواب سے لے کر گہرے، تفصیلی تجزیے تک۔ -Reasoning Control with GPT-5.2 +GPT-5.2 کے ساتھ استدلال کنٹرول -*GPT-5.2 کا استدلالی کنٹرول آپ کو بتانے دیتا ہے کہ ماڈل کتنا سوچے—تیز، براہ راست جواب سے لے کر گہری دریافت تک* +*GPT-5.2 کا استدلال کنٹرول آپ کو بتانے دیتا ہے کہ ماڈل کو کتنا سوچنا چاہیے — تیز اور براہ راست جواب سے لے کر گہرے تجزیے تک* -**کم ولولہ (تیز اور مرکوز)** - آسان سوالات کے لیے جہاں آپ کو فوری، براہ راست جواب چاہئے۔ ماڈل کم سے کم استدلال کرتا ہے—زیادہ سے زیادہ 2 مراحل۔ اس کا استعمال کیلکولیشن، تلاشی، یا سادہ سوالات کے لیے کریں۔ +**کم جوش (تیز اور مرکوز)** - آسان سوالات کے لیے جہاں آپ تیز، براہ راست جواب چاہتے ہیں۔ ماڈل کم سے کم استدلال کرتا ہے - زیادہ سے زیادہ 2 مراحل۔ حساب کتاب، تلاش، یا سادہ سوالات کے لیے استعمال کریں۔ ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **GitHub Copilot کے ساتھ دریافت کریں:** [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) کھولیں اور پوچھیں: -> - "کم ولولہ اور زیادہ ولولہ پرامپٹنگ پیٹرنز میں کیا فرق ہے؟" -> - "پرامپٹس میں XML ٹیگز AI کے جواب کی ساخت کو کیسے مدد دیتے ہیں؟" -> - "کب خود عکاسی والے پیٹرنز استعمال کرنا چاہیے اور کب براہ راست ہدایت؟" +> - "کم اور زیادہ جوش کے پرامپٹنگ نمونوں میں کیا فرق ہے؟" +> - "پرامپٹس میں XML ٹیگز AI کے جواب کو کیسے منظم کرتے ہیں؟" +> - "میں خود انعکاسی نمونوں اور براہ راست ہدایت میں کب فرق کروں؟" -**زیادہ ولولہ (گہرا اور مکمل)** - پیچیدہ مسائل کے لیے جہاں آپ کو جامع تجزیہ درکار ہو۔ ماڈل پوری طرح تلاش کرتا ہے اور تفصیلی استدلال دکھاتا ہے۔ اس کو سسٹم ڈیزائن، آرکیٹیکچر فیصلے، یا پیچیدہ تحقیق کے لیے استعمال کریں۔ +**زیادہ جوش (گہرا اور مفصل)** - پیچیدہ مسائل کے لیے جہاں آپ تفصیلی تجزیہ چاہتے ہیں۔ ماڈل باریک بینی سے تجزیہ کرتا ہے اور تفصیلی استدلال دکھاتا ہے۔ نظام ڈیزائن، آرکیٹیکچر کے فیصلے، یا پیچیدہ تحقیق کے لیے استعمال کریں۔ ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**ٹاسک ایکزیکیوشن (قدم بہ قدم پیش رفت)** - کثیر مرحلوں والے ورک فلو کے لیے۔ ماڈل پہلے سے منصوبہ فراہم کرتا ہے، ہر قدم کام کے دوران بیان کرتا ہے، پھر خلاصہ پیش کرتا ہے۔ یہ ماگریشنز، عمل درآمد، یا کسی بھی کثیر مرحلوں کے عمل کے لیے موزوں ہے۔ +**ٹاسک ایکزیکیوشن (مرحلہ وار پیش رفت)** - کثیر مرحلہ ورک فلو کے لیے۔ ماڈل پہلے ایک منصوبہ فراہم کرتا ہے، ہر قدم پر کام کی وضاحت کرتا ہے، پھر خلاصہ دیتا ہے۔ مائیگریشنز، عمل درآمد، یا کسی بھی کثیر مرحلہ عمل کے لیے استعمال کریں۔ ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -چین آف تھوٹ پرامپٹنگ خاص طور پر ماڈل سے کہتا ہے کہ اپنی استدلالی فرآیند دکھائے، جس سے پیچیدہ کاموں کی درستی میں بہتری آتی ہے۔ قدم بہ قدم تقسیم انسانوں اور AI دونوں کو منطق سمجھنے میں مدد دیتی ہے۔ +چین آف تھوٹ پرامپٹنگ واضح طور پر ماڈل سے استدلالی عمل ظاہر کرنے کو کہتی ہے، جو پیچیدہ کاموں کی درستگی کو بہتر بناتی ہے۔ قدم بہ قدم تجزیہ انسانوں اور AI دونوں کے لیے منطقی سمجھ کو آسان بناتا ہے۔ -> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ کوشش کریں:** اس پیٹرن کے بارے میں پوچھیں: -> - "لمبے عرصے کے آپریشنز کے لیے ٹاسک ایکزیکیوشن پیٹرن کو کیسے ڈھالوں؟" -> - "پروڈکشن ایپلیکیشنز میں ٹول پری ایمبلز کو ترتیب دینے کے بہترین طریقے کیا ہیں؟" -> - "UI میں مڈل پروگریس اپ ڈیٹس کو کیسے کیپچر اور ڈسپلے کروں؟" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمائیں:** اس نمونے کے بارے میں پوچھیں: +> - "طویل مدتی آپریشنز کے لیے ٹاسک ایکزیکیوشن نمونے کو کیسے ڈھالیں؟" +> - "پیداوار میں ٹول پری ایمبلز کو ترتیب دینے کے بہترین طریقے کیا ہیں؟" +> - "انٹرفیس میں درمیانی پیش رفت کی تازہ کاریوں کو کس طرح پکڑیں اور دکھائیں؟" -ذیل کا خاکہ اس Plan → Execute → Summarize ورک فلو کی وضاحت کرتا ہے۔ +نیچے دیا گیا خاکہ اس پلان → ایکزیکیوشن → خلاصہ ورک فلو کو ظاہر کرتا ہے۔ -Task Execution Pattern +ٹاسک ایکزیکیوشن نمونہ -*کثیر مرحلوں والے کاموں کے لیے Plan → Execute → Summarize ورک فلو* +*کثیر مرحلہ کاموں کے لیے پلان → ایکزیکیوشن → خلاصہ ورک فلو* -**سیلف ریفلیکٹنگ کوڈ** - پروڈکشن معیار کا کوڈ تیار کرنے کے لیے۔ ماڈل پروڈکشن معیار کے مطابق کوڈ جنریٹ کرتا ہے جس میں مناسب ایرر ہینڈلنگ ہو۔ جب نئے فیچرز یا سروسز بنا رہے ہوں تو اس کا استعمال کریں۔ +**خود انعکاسی کوڈ** - پیداوار کے معیار کے کوڈ کی تخلیق کے لیے۔ ماڈل پیداوار کے معیارات کے مطابق کوڈ بناتا ہے جس میں درست ایرر ہینڈلنگ شامل ہوتی ہے۔ نئی خصوصیات یا خدمات بنانے کے وقت استعمال کریں۔ ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ذیل میں یہ تکراری بہتری کا چکر دکھایا گیا ہے—کوڈ پیدا کریں، جائزہ لیں، کمزوریاں معلوم کریں، اور جب تک کوڈ پروڈکشن معیار پر نہ پہنچے بہتری کریں۔ +نیچے دیا گیا خاکہ اس تکراری بہتری کے چکر کو دکھاتا ہے — جنریٹ کریں، جائزہ لیں، کمزوریاں معلوم کریں، اور کوڈ کے معیار تک پہنچنے تک درست کریں۔ -Self-Reflection Cycle +خود انعکاسی چکر -*تکراری بہتری کا چکر—پیدا کریں، جائزہ لیں، مسائل معلوم کریں، بہتر بنائیں، دہرائیں* +*تکراری بہتری کا چکر - بنائیں، جائزہ لیں، مسائل کی نشاندہی کریں، بہتر بنائیں، دہرائیں* -**ساختی تجزیہ** - مستقل جائزہ کے لیے۔ ماڈل کوڈ کو ایک مقررہ فریم ورک کے مطابق ریویو کرتا ہے (درستی، عمل، کارکردگی، سلامتی، قابل دیکھ بھال ہونا)۔ کوڈ ریویوز یا معیار کے جائزے کے لیے استعمال کریں۔ +**مرصع تجزیہ** - مستقل جائزے کے لیے۔ ماڈل کوڈ کو ایک مقررہ فریم ورک (درستی، طریقے، کارکردگی، سیکیورٹی، برقرار رکھنے کی صلاحیت) کے تحت جانچتا ہے۔ کوڈ ریویوز یا معیار کی جانچ کے لیے استعمال کریں۔ ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمائیں:** ساختی تجزیہ کے بارے میں پوچھیں: -> - "مختلف قسم کے کوڈ ریویوز کے لیے تجزیاتی فریم ورک کو کیسے حسب ضرورت بناؤں؟" -> - "ساختی آؤٹ پٹ کو پروگرام کے ذریعے بہترین طور پر کیسے پارس اور عمل کیا جائے؟" -> - "مختلف ریویو سیشنز کے دوران مستقل سطحات شدت کو کیسے یقینی بناؤں؟" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمائیں:** مرصع تجزیے کے بارے میں پوچھیں: +> - "میں مختلف قسم کی کوڈ ریویوز کے لیے تجزیاتی فریم ورک کو کیسے حسبِ منشاء بنا سکتا ہوں؟" +> - "مرصع آؤٹ پٹ کو پروگرام کے ذریعے پارس اور عمل میں کیسے لاؤں؟" +> - "میں ایک ہی شدت کی سطح کو مختلف ریویو سیشنز میں کیسے یقینی بنا سکتا ہوں؟" -مندرجہ ذیل خاکہ دکھاتا ہے کہ یہ ساختی فریم ورک کوڈ ریویو کو مستقل کیٹیگریز اور شدت کی سطحوں میں کیسے منظم کرتا ہے۔ +ذیل کا خاکہ دکھاتا ہے کہ یہ منظم فریم ورک کوڈ ریویو کو مستقل زمروں اور شدت کی سطحوں کے ساتھ کس طرح منظم کرتا ہے۔ -Structured Analysis Pattern +مرصع تجزیہ نمونہ -*شدت کی سطحوں کے ساتھ مستقل کوڈ ریویو کا فریم ورک* +*شدت کی سطحوں کے ساتھ مستقل کوڈ ریویوز کے لیے فریم ورک* -**کئی مرحلوں والی بات چیت** - ایسی گفتگو کے لیے جسے سیاق و سباق کی ضرورت ہو۔ ماڈل پچھلے پیغامات کو یاد رکھتا ہے اور ان پر تعمیر کرتا ہے۔ یہ انٹرایکٹو مدد کے سیشنز یا پیچیدہ سوال جواب کے لیے مفید ہے۔ +**کثیر مرحلہ چیٹ** - ایسے گفتگو کے لیے جنہیں سیاق و سباق کی ضرورت ہوتی ہے۔ ماڈل پچھلے پیغامات یاد رکھتا ہے اور ان پر تعمیر کرتا ہے۔ انٹرایکٹو مدد سیشنز یا پیچیدہ سوال و جواب کے لیے استعمال کریں۔ ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -ذیل کا خاکہ دکھاتا ہے کہ گفتگو کا سیاق و سباق ہر مرحلے کے ساتھ کیسے جمع ہوتا ہے اور ماڈل کی ٹوکن حد سے کیسے جڑا ہوتا ہے۔ +نیچے دیا گیا خاکہ ظاہر کرتا ہے کہ کس طرح گفتگو کا سیاق و سباق ہر بار اضافہ ہوتا ہے اور یہ ماڈل کے ٹوکن کی حد کے ساتھ کیسے تعلق رکھتا ہے۔ -Context Memory +سیاق و سباق اور میموری -*گفتگو کا سیاق و سباق متعدد مراحل کے دوران جمع ہوتا ہے جب تک کہ ٹوکن حد تک نہ پہنچ جائے* -**مرحلہ بہ مرحلہ استدلال** – ان مسائل کے لیے جنہیں واضح منطق کی ضرورت ہو۔ ماڈل ہر قدم کے لیے واضح استدلال دکھاتا ہے۔ اسے ریاضی کے مسائل، منطقی پہیلیوں یا جب آپ سوچنے کے عمل کو سمجھنا چاہتے ہوں تب استعمال کریں۔ +*کس طرح گفتگو کا سیاق و سباق متعدد مراحل میں جمع ہوتا ہے جب تک کہ ٹوکن حد نہ پہنچ جائے* + +**قدم بہ قدم استدلال** - ایسے مسائل کے لیے جنہیں واضح منطق چاہیے۔ ماڈل ہر مرحلہ کے لیے واضح استدلال دکھاتا ہے۔ یہ ریاضی کے مسائل، منطقی پہیلیاں، یا اس موقع پر استعمال کریں جب آپ سمجھنا چاہیں کہ سوچنے کا عمل کیسا ہے۔ ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ذیل کا خاکہ ظاہر کرتا ہے کہ ماڈل مسائل کو واضح، نمبر شدہ منطقی مراحل میں کیسے تقسیم کرتا ہے۔ - -مرحلہ بہ مرحلہ نمونہ +نیچے دیا گیا خاکہ دکھاتا ہے کہ ماڈل کیسے مسائل کو واضح، نمبر والے منطقی مراحل میں تقسیم کرتا ہے۔ -*مسائل کو واضح منطقی مراحل میں تقسیم کرنا* +قدم بہ قدم نمونہ +*مسائل کو واضح منطقی مراحل میں توڑنا* -**محدود آؤٹ پٹ** – مخصوص فارمیٹ کے تقاضوں والے جوابات کے لیے۔ ماڈل سختی سے فارمیٹ اور لمبائی کے قواعد پر عمل کرتا ہے۔ اسے خلاصوں کے لیے یا جب آپ کو درست آؤٹ پٹ کی ساخت چاہیے ہو تب استعمال کریں۔ +**محدود شدہ آؤٹ پٹ** - مخصوص فارمیٹ کی ضروریات والے جوابات کے لیے۔ ماڈل سختی سے فارمیٹ اور لمبائی کے قواعد کی پیروی کرتا ہے۔ خلاصہ یا جب آپ کو بالکل درست آؤٹ پٹ ڈھانچے کی ضرورت ہو، اس کا استعمال کریں۔ ```java String prompt = """ @@ -420,89 +420,89 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -ذیل کا خاکہ دکھاتا ہے کہ کس طرح پابندیاں ماڈل کو ایسا آؤٹ پٹ بنانے پر مجبور کرتی ہیں جو آپ کے فارمیٹ اور لمبائی کی شرائط پر سختی سے عمل کرتا ہے۔ +مندرجہ ذیل خاکہ دکھاتا ہے کہ کس طرح پابندیاں ماڈل کو آپ کی فارمیٹ اور لمبائی کی ضروریات کی سختی سے پابندی کرتے ہوئے آؤٹ پٹ تیار کرنے کی رہنمائی کرتی ہیں۔ -محدود آؤٹ پٹ نمونہ +محدود شدہ آؤٹ پٹ پیٹرن -*مخصوص فارمیٹ، لمبائی، اور ساخت کی شرائط پر عملدرآمد* +*مخصوص فارمیٹ، لمبائی، اور ڈھانچے کی ضروریات کو نافذ کرنا* ## ایپلیکیشن چلائیں -**ڈیپلائمنٹ کی تصدیق کریں:** +**تعینات کی تصدیق کریں:** -یقینی بنائیں کہ `.env` فائل روٹ ڈائریکٹری میں Azure کی اسناد کے ساتھ موجود ہے (جو موڈیول 01 میں بنائی گئی تھی)۔ اسے moڈیول ڈائریکٹری (`02-prompt-engineering/`) سے چلائیں: +یقینی بنائیں کہ روٹ ڈائریکٹری میں `.env` فائل موجود ہے جس میں Azure کے اسناد ہوں (جو ماڈیول 01 کے دوران بنائی گئی ہو)۔ اسے ماڈیول ڈائریکٹری (`02-prompt-engineering/`) سے چلائیں: -**بش:** +**Bash:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT دکھانا چاہیے +cat ../.env # AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT دکھانے چاہئیں ``` -**پاور شیل:** +**PowerShell:** ```powershell -Get-Content ..\.env # دکھانا چاہیے AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT +Get-Content ..\.env # دکھانا چاہیے AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT ``` **ایپلیکیشن شروع کریں:** -> **نوٹ:** اگر آپ نے پہلے ہی تمام ایپلیکیشنز کو `./start-all.sh` کے ذریعے روٹ ڈائریکٹری سے شروع کر دیا ہے (جیسا کہ موڈیول 01 میں بیان کیا گیا ہے)، تو یہ موڈیول پہلے سے پورٹ 8083 پر چل رہا ہے۔ آپ نیچے دیے گئے کمانڈز کو چھوڑ کر سیدھا http://localhost:8083 پر جا سکتے ہیں۔ +> **نوٹ:** اگر آپ نے پہلے ہی روٹ ڈائریکٹری سے `./start-all.sh` استعمال کرتے ہوئے تمام ایپلیکیشنز شروع کر دی ہیں (جیسا کہ ماڈیول 01 میں بیان ہوا)، یہ ماڈیول پہلے ہی پورٹ 8083 پر چل رہا ہے۔ آپ نیچے دیے گئے شروع کرنے کے کمانڈ چھوڑ کر براہ راست http://localhost:8083 پر جا سکتے ہیں۔ -**اختیار 1: سپرنگ بوٹ ڈیش بورڈ استعمال کرنا (VS Code صارفین کے لیے تجویز کردہ)** +**اختیار 1: Spring Boot Dashboard استعمال کرنا (VS کوڈ صارفین کے لیے تجویز کردہ)** -ڈیولپمنٹ کنٹینر میں سپرنگ بوٹ ڈیش بورڈ ایکسٹینشن شامل ہے، جو تمام سپرنگ بوٹ ایپلیکیشنز کو منظم کرنے کے لیے بصری انٹرفیس فراہم کرتا ہے۔ آپ اسے VS Code کے بائیں جانب Activity Bar میں سپرنگ بوٹ آئیکن کے طور پر دیکھ سکتے ہیں۔ +ڈیو کنٹینر میں Spring Boot Dashboard ایکسٹینشن شامل ہے، جو تمام Spring Boot ایپلیکیشنز کو منظم کرنے کے لیے بصری انٹرفیس فراہم کرتا ہے۔ آپ اسے VS کوڈ میں بائیں جانب Activity Bar پر Spring Boot کے آئیکن کے ذریعے دیکھ سکتے ہیں۔ -سپرنگ بوٹ ڈیش بورڈ سے آپ: -- ورک اسپیس میں دستیاب تمام سپرنگ بوٹ ایپلیکیشنز دیکھ سکتے ہیں -- ایک کلک سے ایپلیکیشنز کو شروع/روک سکتے ہیں -- ریئل ٹائم میں ایپلیکیشن لاگز دیکھ سکتے ہیں -- ایپلیکیشن کی حالت کی نگرانی کر سکتے ہیں +Spring Boot Dashboard سے آپ کر سکتے ہیں: +- ورک اسپیس میں دستیاب تمام Spring Boot ایپلیکیشنز دیکھیں +- ایک کلک سے ایپلیکیشنز شروع/روکیں +- ایپلیکیشن لاگز کو حقیقی وقت میں دیکھیں +- ایپلیکیشن کی حالت کی نگرانی کریں -سادہ طور پر "prompt-engineering" کے ساتھ پلے بٹن پر کلک کریں اس موڈیول کو شروع کرنے کے لیے، یا تمام موڈیولز کو ایک ساتھ شروع کریں۔ +بس "prompt-engineering" کے ساتھ پلے بٹن پر کلک کریں تاکہ یہ ماڈیول شروع ہو جائے، یا سبھی ماڈیولز کو ایک ساتھ شروع کریں۔ -سپرنگ بوٹ ڈیش بورڈ +Spring Boot ڈیش بورڈ -*VS Code میں سپرنگ بوٹ ڈیش بورڈ – تمام موڈیولز کو ایک جگہ سے شروع، روک، اور مانیٹر کریں* +*VS کوڈ میں Spring Boot Dashboard — تمام ماڈیولز کو ایک جگہ سے شروع، روک، اور مانیٹر کریں* **اختیار 2: شیل اسکرپٹس استعمال کرنا** -تمام ویب ایپلیکیشنز (موڈیولز 01-04) کو شروع کریں: +تمام ویب ایپلیکیشنز (ماڈیول 01-04) شروع کریں: -**بش:** +**Bash:** ```bash -cd .. # بنیادی ڈائریکٹری سے +cd .. # جڑ ڈائریکٹری سے ./start-all.sh ``` -**پاور شیل:** +**PowerShell:** ```powershell cd .. # روٹ ڈائریکٹری سے .\start-all.ps1 ``` -یا صرف اس موڈیول کو شروع کریں: +یا صرف اس ماڈیول کو شروع کریں: -**بش:** +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` -**پاور شیل:** +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` -دونوں اسکرپٹس خودکار طریقے سے روٹ `.env` فائل سے ماحولیاتی متغیرات لوڈ کرتے ہیں اور اگر JAR موجود نہ ہوں تو انہیں بنائیں گے۔ +دونوں اسکرپٹس خودکار طور پر روٹ `.env` فائل سے ماحولیاتی متغیرات لوڈ کریں گے اور اگر JAR فائلیں موجود نہ ہوں تو انہیں بنائیں گے۔ -> **نوٹ:** اگر آپ شروع کرنے سے پہلے تمام موڈیولز کو دستی طور پر بنانا ترجیح دیتے ہیں: +> **نوٹ:** اگر آپ سبھی ماڈیولز کو دستی طور پر شروع کرنے سے پہلے بنانا چاہتے ہیں: > -> **بش:** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **پاور شیل:** +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests @@ -510,99 +510,99 @@ cd 02-prompt-engineering اپنے براؤزر میں http://localhost:8083 کھولیں۔ -**روکنے کے لیے:** +**بند کرنے کے لیے:** -**بش:** +**Bash:** ```bash ./stop.sh # صرف یہ ماڈیول # یا cd .. && ./stop-all.sh # تمام ماڈیولز ``` -**پاور شیل:** +**PowerShell:** ```powershell -.\stop.ps1 # یہ صرف ماڈیول +.\stop.ps1 # یہ ماڈیول صرف # یا cd ..; .\stop-all.ps1 # تمام ماڈیولز ``` -## ایپلیکیشن کے اسکرین شاٹس +## ایپلیکیشن اسکرین شاٹس -یہاں پرامپٹ انجینئرنگ موڈیول کا مرکزی انٹرفیس ہے، جہاں آپ آٹھوں پیٹرنز کو ایک ساتھ تجربہ کر سکتے ہیں۔ +یہاں prompt engineering ماڈیول کا مرکزی انٹرفیس ہے، جہاں آپ تمام آٹھ پیٹرنز کو ایک ساتھ آزما سکتے ہیں۔ ڈیش بورڈ ہوم -*مرکزی ڈیش بورڈ جو آٹھ پرامپٹ انجینئرنگ پیٹرنز اور ان کی خصوصیات و استعمال کے کیسز دکھاتا ہے* +*مرکزی ڈیش بورڈ جو تمام 8 پرامپٹ انجینئرنگ پیٹرنز کو ان کی خصوصیات اور استعمال کے معاملات کے ساتھ دکھاتا ہے* -## پیٹرنز کو دریافت کرنا +## پیٹرنز کی دریافت -ویب انٹرفیس آپ کو مختلف پرامپٹ حکمت عملیاں آزمانے دیتا ہے۔ ہر پیٹرن مختلف مسائل حل کرتا ہے – تجربہ کریں تاکہ جان سکیں کہ کون سا طریقہ کب بہترین کام کرتا ہے۔ +ویب انٹرفیس آپ کو مختلف پرامپٹنگ حکمت عملیاں آزمانے دیتا ہے۔ ہر پیٹرن مختلف مسائل کو حل کرتا ہے - انہیں آزما کر دیکھیں کہ کب کون سا طریقہ نمایاں ہوتا ہے۔ -> **نوٹ: اسٹریمنگ بمقابلہ نان-اسٹریمنگ** — ہر پیٹرن پیج دو بٹن فراہم کرتا ہے: **🔴 اسٹریم جوابی عمل (لائیو)** اور ایک **نان-اسٹریمنگ** آپشن۔ اسٹریمنگ سرور-سینٹ ایونٹس (SSE) استعمال کرتی ہے تاکہ ماڈل کے بناتے ہوئے ٹوکنز کو فوری طور پر دکھایا جا سکے، جس سے آپ کو پیش رفت فوراً نظر آتی ہے۔ نان-اسٹریمنگ آپشن پورے جواب کے مکمل ہونے کا انتظار کرتا ہے۔ گہری استدلال والے پرامپٹس (مثلاً High Eagerness، Self-Reflecting Code) کے لیے، نان-اسٹریم کال بہت طویل وقت لے سکتی ہے — کبھی کبھی منٹوں تک — بغیر کوئی نظر آنے والا فیڈ بیک۔ **پیچیدہ پرامپٹس کی جانچ کرتے وقت اسٹریمنگ استعمال کریں** تاکہ آپ ماڈل کے کام کو دیکھ سکیں اور یہ تاثر نہ بنے کہ درخواست وقت سے باہر ہو گئی۔ +> **نوٹ: سٹریمنگ vs نان-سٹریمنگ** — ہر پیٹرن کے صفحہ پر دو بٹن ہوتے ہیں: **🔴 Stream Response (Live)** اور **نان-سٹریمنگ** آپشن۔ سٹریمنگ Server-Sent Events (SSE) استعمال کرتی ہے تاکہ ماڈل کے ٹوکنز کو حقیقی وقت میں دکھایا جا سکے، لہٰذا آپ فوری پیش رفت دیکھتے ہیں۔ نان-سٹریمنگ آپشن پوری جواب دہی کا انتظار کرتا ہے پھر دکھاتا ہے۔ پیچیدہ پرامپٹس (مثلاً High Eagerness, Self-Reflecting Code) کے لیے نان-سٹریمنگ کال بہت دیر لے سکتی ہے — بعض اوقات منٹوں تک — بغیر کسی ظاہری فیڈبیک کے۔ **پیچیدہ پرامپٹس کے ساتھ تجربہ کرتے وقت سٹریمنگ استعمال کریں** تاکہ آپ ماڈل کے کام کرنے کو دیکھ سکیں اور یہ تاثر پیدا نہ ہو کہ درخواست ٹائم آؤٹ ہو گئی ہے۔ > -> **نوٹ: براؤزر کی ضرورت** — اسٹریمنگ فیچر Fetch Streams API (`response.body.getReader()`) استعمال کرتا ہے جو مکمل براؤزر (کروم، ایج، فائرفوکس، سفاری) کے لیے ضروری ہے۔ یہ VS Code کے بلٹ-ان سمپل براؤزر میں کام نہیں کرتا کیونکہ اس کا ویب ویو ReadableStream API کو سپورٹ نہیں کرتا۔ اگر آپ سمپل براؤزر استعمال کرتے ہیں، تو نان-اسٹریمنگ بٹنز عام طور پر کام کریں گے — صرف اسٹریمنگ بٹن متاثر ہوں گے۔ بہترین تجربے کے لیے `http://localhost:8083` کو کسی بیرونی براؤزر میں کھولیں۔ +> **نوٹ: براؤزر کی ضرورت** — سٹریمنگ فیچر Fetch Streams API (`response.body.getReader()`) استعمال کرتا ہے جو مکمل براؤزر (Chrome, Edge, Firefox, Safari) چاہتا ہے۔ VS کوڈ کے ان بلٹ Simple Browser میں یہ کام نہیں کرتا کیونکہ اس کا ویب ویو ReadableStream API کو سپورٹ نہیں کرتا۔ اگر آپ Simple Browser استعمال کرتے ہیں تو نان-سٹریمنگ بٹن معمول کے مطابق کام کریں گے — صرف سٹریمنگ بٹن اثر انداز ہوں گے۔ مکمل تجربے کے لیے `http://localhost:8083` کو بیرونی براؤزر میں کھولیں۔ ### کم بمقابلہ زیادہ جوش -ساده سوال جیسے "15% کا 200 کیا ہے؟" کم جوش کے ساتھ پوچھیں۔ آپ کو فوری اور براہ راست جواب ملے گا۔ اب کچھ پیچیدہ پوچھیں جیسے "ہائی ٹریفک API کے لیے کیشنگ حکمت عملی تیار کریں" زیادہ جوش کے ساتھ۔ **🔴 اسٹریم جوابی عمل (لائیو)** پر کلک کریں اور ماڈل کی تفصیلی استدلال کو ٹوکن بہ ٹوکن دیکھیں۔ ایک ہی ماڈل، ایک ہی سوالی ساخت – پرامپٹ بتاتا ہے کہ کتنا سوچنا ہے۔ +ایک آسان سوال پوچھیں جیسے "200 کا 15٪ کیا ہے؟" کم جوش کے ساتھ۔ آپ کو فوری اور براہ راست جواب ملے گا۔ اب کچھ پیچیدہ پوچھیں جیسے "ہائی ٹریفک API کے لیے کیشنگ حکمت عملی ڈیزائن کریں" زیادہ جوش کے ساتھ۔ **🔴 Stream Response (Live)** پر کلک کریں اور ماڈل کی تفصیلی دلیل ٹوکن بہ ٹوکن دیکھیں۔ ایک ہی ماڈل، ایک ہی سوال کا ڈھانچہ - لیکن پرامپٹ بتاتا ہے کہ کتنا سوچنا ہے۔ -### کام کا نفاذ (ٹول پری ایمبلز) +### ٹاسک ایگزیکیوشن (ٹول پری ایمبلز) -کئی مرحلوں کے ورک فلو کو پیشگی منصوبہ بندی اور پیش رفت کی بیانکاری سے فائدہ ہوتا ہے۔ ماڈل بتاتا ہے کہ کیا کرے گا، ہر قدم کی وضاحت کرتا ہے، پھر نتائج کا خلاصہ پیش کرتا ہے۔ +کئی مراحل والے ورک فلو کو ابتدائی منصوبہ بندی اور پیش رفت کی وضاحت سے فائدہ ہوتا ہے۔ ماڈل بتاتا ہے کہ کیا کرنا ہے، ہر قدم کی وضاحت کرتا ہے، پھر نتائج کا خلاصہ دیتا ہے۔ -### خود-عکاسی کرنے والا کوڈ +### خود عکاسی کرنے والا کوڈ -"ای میل ویلیڈیشن سروس بنائیں" آزما کر دیکھیں۔ بس کوڈ بنانے اور روکنے کے بجائے، ماڈل کوڈ جنریٹ کرتا ہے، معیار کی جانچ کرتا ہے، کمزوریاں پہچانتا ہے، اور بہتری لاتا ہے۔ آپ دیکھیں گے کہ یہ تب تک دہرائے گا جب تک کوڈ پروڈکشن معیار پر نہ پہنچ جائے۔ +"ایک ای میل ویلیڈیشن سروس بنائیں" آزمائیں۔ صرف کوڈ تیار کرنے اور رکنے کے بجائے، ماڈل کوڈ تخلیق کرتا ہے، معیار کے خلاف جانچتا ہے، کمزوریاں شناخت کرتا ہے، اور بہتر کرتا ہے۔ آپ اسے اس وقت تک دہرایا ہوا دیکھیں گے جب تک کوڈ پروڈکشن معیارات پر پورا نہ اترے۔ ### منظم تجزیہ -کوڈ ریویوز کے لیے مستقل جانچ کے فریم ورک کی ضرورت ہوتی ہے۔ ماڈل کوڈ کا تجزیہ معین زمروں (صحیح ہونا، طریقے، کارکردگی، حفاظتی پہلو) کے تحت شدت کی سطحوں کے ساتھ کرتا ہے۔ +کوڈ ریویوز کے لیے مستقل تشخیصی فریم ورک کی ضرورت ہوتی ہے۔ ماڈل کوڈ کو معیاری زمروں (صحیح ہونا، طریقہ کار، کارکردگی، سیکیورٹی) اور شدت کی سطحوں کے ساتھ تجزیہ کرتا ہے۔ -### کثیر رفتاری چیٹ +### کثیر دفعہ چیٹ -"سپرنگ بوٹ کیا ہے؟" پوچھیں اور فوراً "ایک مثال دکھائیں" کا سوال کریں۔ ماڈل آپ کے پہلے سوال کو یاد رکھتا ہے اور خاص طور پر سپرنگ بوٹ کی مثال دیتا ہے۔ یادداشت کے بغیر دوسرا سوال بہت مبہم ہوتا۔ +پوچھیں "Spring Boot کیا ہے؟" پھر فوراً "مثال دکھائیں"۔ ماڈل آپ کے پہلے سوال کو یاد رکھتا ہے اور آپ کو خاص طور پر Spring Boot کی مثال دیتا ہے۔ بغیر یادداشت کے، دوسرا سوال بہت مبہم ہوتا۔ -### مرحلہ بہ مرحلہ استدلال +### مرحلہ وار استدلال -کسی ریاضی کے مسئلے کا انتخاب کریں اور اسے مرحلہ بہ مرحلہ استدلال اور کم جوش دونوں کے ساتھ آزما کر دیکھیں۔ کم جوش صرف جواب دیتا ہے — تیز لیکن غیر واضح۔ مرحلہ بہ مرحلہ آپ کو ہر حساب اور فیصلہ دکھاتا ہے۔ +ایک ریاضی کا مسئلہ چنیں اور اسے Step-by-Step Reasoning اور Low Eagerness دونوں کے ساتھ آزمائیں۔ کم جوش صرف جواب دیتا ہے - تیز مگر مبہم۔ مرحلہ وار ہر حساب اور فیصلہ دکھاتا ہے۔ -### محدود آؤٹ پٹ +### محدود شدہ آؤٹ پٹ -جب آپ کو مخصوص فارمیٹ یا لفظوں کی تعداد کی ضرورت ہو، یہ پیٹرن سخت پابندی نافذ کرتا ہے۔ بال پوائنٹس میں عین 100 الفاظ پر مشتمل خلاصہ بنانے کی کوشش کریں۔ +جب آپ کو مخصوص فارمیٹس یا الفاظ کی تعداد کی ضرورت ہو، یہ پیٹرن سخت پابندی کو نافذ کرتا ہے۔ 100 الفاظ کے بلٹ پوائنٹ فارمیٹ میں خلاصہ بنانے کی کوشش کریں۔ ## آپ اصل میں کیا سیکھ رہے ہیں -**استدلال کی کوشش سب کچھ بدل دیتی ہے** +**استدلال کی کوشش ہر چیز بدل دیتی ہے** -GPT-5.2 آپ کو اپنی پرامپٹس کے ذریعے کمپیوٹیشنل کوشش کو کنٹرول کرنے دیتا ہے۔ کم کوشش کا مطلب ہے تیز جوابات، کم گہرائی میں تلاش۔ زیادہ کوشش کا مطلب ہے ماڈل وقت لے کر گہرائی سے سوچتا ہے۔ آپ سیکھ رہے ہیں کہ کوشش کو کام کی پیچیدگی کے مطابق کریں – سادہ سوالات پر وقت ضائع نہ کریں، مگر پیچیدہ فیصلوں میں جلد بازی نہ کریں۔ +GPT-5.2 آپ کو اپنے پرامپٹس کے ذریعے حسابی کوشش کنٹرول کرنے دیتا ہے۔ کم کوشش کا مطلب تیز جوابات کم تلاش کے ساتھ۔ زیادہ کوشش کا مطلب ماڈل گہرائی سے سوچنے میں وقت لگاتا ہے۔ آپ سیکھ رہے ہیں کہ کوشش کو کام کی پیچیدگی کے مطابق ملائیں - آسان سوالات پر وقت ضائع نہ کریں، اور پیچیدہ فیصلوں کو جلد بازی میں نہ لائیں۔ -**ساختی طریقہ کار رویے کی رہنمائی کرتا ہے** +**ڈھانچہ رویے کی رہنمائی کرتا ہے** -کیا آپ نے پرامپٹس میں XML ٹیگز دیکھے؟ وہ صرف سجاوٹ نہیں ہیں۔ ماڈل منظم ہدایات کو آزاد متن کے مقابلے میں زیادہ قابل اعتماد طریقے سے فالو کرتے ہیں۔ جب آپ کو کثیر مرحلہ عمل یا پیچیدہ منطق کی ضرورت ہو، ساخت ماڈل کو اس بات کی نشاندہی میں مدد دیتی ہے کہ وہ کہاں ہے اور آگے کیا کرنا ہے۔ ذیل کا خاکہ ایک اچھے منظم پرامپٹ کو دکھاتا ہے، جس میں ``, ``, ``, ``, اور `` جیسے ٹیگز آپ کی ہدایات کو واضح حصوں میں تقسیم کرتے ہیں۔ +کیا آپ نے پرامپٹس میں XML ٹیگز دیکھے؟ یہ صرف سجانے کے لیے نہیں ہیں۔ ماڈلز ساختی ہدایات کو آزاد متنی ہدایتوں سے زیادہ قابل بھروسہ طریقے سے فالو کرتے ہیں۔ جب آپ کو متعدد مراحل کے عمل یا پیچیدہ منطق کی ضرورت ہوتی ہے، تو ساخت ماڈل کی مدد کرتی ہے کہ وہ اپنی جگہ اور اگلے مرحلے کا پتہ رکھے۔ نیچے دیا گیا خاکہ ایک اچھی طرح منظم پرامپٹ کو توڑ کر دکھاتا ہے، جس میں ``, ``, ``, ``, اور `` جیسے ٹیگز آپ کی ہدایات کو واضح حصوں میں منظم کرتے ہیں۔ -پرومپٹ کی ساخت +پرامپٹ کا ڈھانچہ -*ایک اچھی منظم پرامپٹ کی ترکیب، واضح سیکشنز اور XML طرز کی تنظیم کے ساتھ* +*ایک اچھی طرح منظم پرامپٹ کی تفصیل جس میں واضح حصے اور XML طرز کی تنظیم شامل ہے* -**خود جائزہ کے ذریعے معیار** +**خود تشخیص کے ذریعے معیار** -خود-عکاسی کرنے والے پیٹرنز معیار کے معیارات کو واضح کرتے ہیں۔ ماڈل سے "درست کرنے کی امید" کرنے کے بجائے، آپ بالکل بتاتے ہیں کہ "صحیح" کا مطلب کیا ہے: درست منطق، خرابی کا ہینڈلنگ، کارکردگی، سیکیورٹی۔ ماڈل پھر اپنی ہی پیداوار کا جائزہ لے سکتا ہے اور اسے بہتر بنا سکتا ہے۔ یہ کوڈ بنانے کے عمل کو لاتری سے ایک منظم طریقہ کار میں بدل دیتا ہے۔ +خود عکاسی کرنے والے پیٹرنز اس وقت کام کرتے ہیں جب معیار کے معیارات واضح کیے جائیں۔ ماڈل سے "صحیح طریقے سے کرنے" کی امید کرنے کے بجائے، آپ اسے واضح کرتے ہیں کہ "صحیح" کا مطلب کیا ہے: درست منطق، غلطی سنبھالنا، کارکردگی، سیکیورٹی۔ ماڈل پھر اپنی آؤٹ پٹ کا جائزہ لے کر بہتر کر سکتا ہے۔ یہ کوڈ جنریشن کو ایک قرعہ اندازی سے ایک مستحکم عمل میں بدل دیتا ہے۔ -**سیاق و سباق محدود ہوتا ہے** +**سیاق و سباق محدود ہے** -کثیر مرحلوں کی بات چیت ہر درخواست کے ساتھ پیغام کی تاریخ شامل کر کے کام کرتی ہے۔ لیکن ایک حد ہوتی ہے – ہر ماڈل کا زیادہ سے زیادہ ٹوکن شمار ہوتا ہے۔ جیسے جیسے بات چیت بڑھتی ہے، آپ کو حکمت عملیاں اپنانا ہوں گی تاکہ متعلقہ سیاق و سباق کو برقرار رکھتے ہوئے حد کو نہ پہنچیں۔ یہ موڈیول آپ کو یادداشت کیسے کام کرتی ہے دکھاتا ہے؛ بعد میں آپ سیکھیں گے کہ کب خلاصہ کرنا ہے، کب بھول جانا ہے، اور کب دوبارہ حاصل کرنا ہے۔ +کثیر دفعہ بات چیت ہر درخواست کے ساتھ پیغام کی تاریخ شامل کرنے سے کام کرتی ہے۔ لیکن حد ہوتی ہے - ہر ماڈل میں زیادہ سے زیادہ ٹوکن کی گنتی ہوتی ہے۔ جیسے جیسے بات چیت بڑھتی ہے، آپ کو اس حد کو پہنچے بغیر متعلقہ سیاق و سباق رکھنے کی حکمت عملیاں استعمال کرنی ہوں گی۔ یہ ماڈیول آپ کو یادداشت کیسے کام کرتی ہے دکھاتا ہے؛ بعد میں آپ سیکھیں گے کہ کب خلاصہ کرنا ہے، کب بھولنا ہے، اور کب بازیافت کرنا ہے۔ -## اگلے اقدامات +## اگلے مراحل -**اگلا موڈیول:** [03-rag - RAG (ریٹریول-آگمینٹڈ جنریشن)](../03-rag/README.md) +**اگلا ماڈیول:** [03-rag - RAG (ریٹریول-اگمینٹڈ جنریشن)](../03-rag/README.md) --- -**نیویگیشن:** [← پچھلا: موڈیول 01 - تعارف](../01-introduction/README.md) | [مین پر واپس جائیں](../README.md) | [اگلا: موڈیول 03 - RAG →](../03-rag/README.md) +**نیویگیشن:** [← پچھلا: ماڈیول 01 - تعارف](../01-introduction/README.md) | [واپس مرکزی صفحہ](../README.md) | [آگلا: ماڈیول 03 - RAG →](../03-rag/README.md) --- -**دستاویز کی وضاحت**: -یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ ہم درستگی کے لئے کوشاں ہیں، لیکن براہ کرم نوٹ کریں کہ خودکار ترجمے میں غلطیاں یا نقصاں ہو سکتے ہیں۔ اصل دستاویز اپنی مادری زبان میں قابلِ اعتبار حوالہ سمجھی جانی چاہیے۔ اہم معلومات کے لئے پیشہ ور انسانی ترجمہ تجویز کیا جاتا ہے۔ اس ترجمہ کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا بدفہمی کے لئے ہم ذمہ دار نہیں ہیں۔ +**ڈس کلیمر**: +یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔ \ No newline at end of file diff --git a/translations/ur/03-rag/README.md b/translations/ur/03-rag/README.md index 68cb3982f..464ab0811 100644 --- a/translations/ur/03-rag/README.md +++ b/translations/ur/03-rag/README.md @@ -1,144 +1,143 @@ -# ماڈیول 03: RAG (ریکوریئل-آگمینٹڈ جنریشن) - -## فہرست مواد - -- [ویڈیو واک تھرو](../../../03-rag) -- [آپ کیا سیکھیں گے](../../../03-rag) -- [ضروریات](../../../03-rag) -- [RAG کو سمجھنا](../../../03-rag) - - [یہ ٹیوٹوریل کونسا RAG طریقہ استعمال کرتا ہے؟](../../../03-rag) -- [یہ کیسے کام کرتا ہے](../../../03-rag) - - [دستاویز کی پراسیسنگ](../../../03-rag) - - [ایمبیڈنگ بنانا](../../../03-rag) - - [معنوی تلاش](../../../03-rag) - - [جواب کی تخلیق](../../../03-rag) -- [ایپلیکیشن چلائیں](../../../03-rag) -- [ایپلیکیشن کا استعمال](../../../03-rag) - - [دستاویز اپلوڈ کریں](../../../03-rag) - - [سوال پوچھیں](../../../03-rag) - - [ذریعہ حوالہ جات چیک کریں](../../../03-rag) - - [سوالات کے ساتھ تجربہ کریں](../../../03-rag) -- [اہم تصورات](../../../03-rag) - - [چنکنگ حکمت عملی](../../../03-rag) - - [مشابہت اسکورز](../../../03-rag) - - [ان میموری اسٹوریج](../../../03-rag) - - [سیاق و سباق ونڈو مینجمنٹ](../../../03-rag) -- [جب RAG اہم ہے](../../../03-rag) -- [اگلے اقدامات](../../../03-rag) +# ماڈیول 03: RAG (ریکوری-آگمینٹڈ جنریشن) + +## مواد کی فہرست + +- [ویڈیو واک تھرو](#ویڈیو-واک-تھرو) +- [آپ کیا سیکھیں گے](#آپ-کیا-سیکھیں-گے) +- [پری ریکوزٹس](#پری-ریکوزٹس) +- [RAG کو سمجھنا](#rag-کو-سمجھنا) + - [یہ ٹیوٹوریل کون سا RAG طریقہ استعمال کرتا ہے؟](#یہ-ٹیوٹوریل-کون-سا-rag-طریقہ-استعمال-کرتا-ہے؟) +- [یہ کیسے کام کرتا ہے](#یہ-کیسے-کام-کرتا-ہے) + - [دستاویز کی پراسیسنگ](#دستاویز-کی-پراسیسنگ) + - [ایمبیڈنگز بنانا](#ایمبیڈنگز-بنانا) + - [سیمنٹک سرچ](#سیمنٹک-سرچ) + - [جواب تیار کرنا](#جواب-کی-تخلیق) +- [ایپلیکیشن چلائیں](#ایپلیکیشن-چلائیں) +- [ایپلیکیشن استعمال کرنا](#ایپلیکیشن-کا-استعمال) + - [ایک دستاویز اپ لوڈ کریں](#دستاویز-اپلوڈ-کریں) + - [سوالات پوچھیں](#سوالات-پوچھیں) + - [ذرائع کی حوالہ جات چیک کریں](#ماخذ-حوالہ-جات-چیک-کریں) + - [سوالات کے ساتھ تجربہ کریں](#سوالات-کے-ساتھ-تجربہ-کریں) +- [اہم تصورات](#کلیدی-تصورات) + - [چنکنگ حکمت عملی](#ٹکڑوں-کی-حکمت-عملی-chunking-strategy) + - [مماثلت کے اسکورز](#مماثلت-کے-اسکور) + - [میموری میں اسٹوریج](#میموری-میں-ذخیرہ) + - [کانٹیکسٹ ونڈو مینجمنٹ](#سیاق-و-سباق-ونڈو-مینجمنٹ) +- [جب RAG اہم ہو](#جب-rag-اہم-ہوتا-ہے) +- [اگلے اقدامات](#اگلے-مراحل) ## ویڈیو واک تھرو -اس لائیو سیشن کو دیکھیں جو وضاحت کرتا ہے کہ اس ماڈیول کے ساتھ کیسے شروع کریں: +اس لائیو سیشن کو دیکھیں جو اس ماڈیول کے ساتھ شروع کرنے کا طریقہ بتاتا ہے: RAG with LangChain4j - Live Session ## آپ کیا سیکھیں گے -پچھلے ماڈیولز میں، آپ نے سیکھا کہ AI سے بات چیت کیسے کریں اور اپنے پرامپٹس کو مؤثر طریقے سے کیسے ترتیب دیں۔ لیکن ایک بنیادی حد ہے: زبان کے ماڈل صرف وہی جانتے ہیں جو انہیں ٹریننگ کے دوران سکھایا گیا ہو۔ وہ آپ کی کمپنی کی پالیسیوں، آپ کے پروجیکٹ کی دستاویزات، یا کسی ایسی معلومات کے بارے میں سوالات کا جواب نہیں دے سکتے جن پر انہیں تربیت نہیں دی گئی۔ +پچھلے ماڈیولز میں، آپ نے سیکھا کہ AI کے ساتھ بات چیت کیسے کی جائے اور اپنے پرامپٹس کو مؤثر طریقے سے کیسے ترتیب دیا جائے۔ لیکن ایک بنیادی حد ہے: زبان کے ماڈلز صرف وہی جانتے ہیں جو انہوں نے تربیت کے دوران سیکھا ہوتا ہے۔ وہ آپ کی کمپنی کی پالیسیوں، آپ کے پروجیکٹ کی دستاویزات، یا ایسی کسی معلومات کے بارے میں سوالات کا جواب نہیں دے سکتے جن پر انہیں تربیت نہیں دی گئی۔ -RAG (ریکوریئل-آگمینٹڈ جنریشن) اس مسئلے کو حل کرتا ہے۔ ماڈل کو آپ کی معلومات سکھانے کی کوشش کرنے کے بجائے (جو مہنگا اور غیر عملی ہے)، آپ اسے آپ کی دستاویزات کے ذریعے تلاش کرنے کی صلاحیت دیتے ہیں۔ جب کوئی سوال پوچھتا ہے، تو نظام متعلقہ معلومات تلاش کرتا ہے اور پرامپٹ میں شامل کرتا ہے۔ پھر ماڈل اس بازیافت شدہ سیاق و سباق کی بنیاد پر جواب دیتا ہے۔ +RAG (ریکوری-آگمینٹڈ جنریشن) اس مسئلے کو حل کرتا ہے۔ ماڈل کو آپ کی معلومات سکھانے کی کوشش کرنے کی بجائے (جو مہنگا اور غیر عملی ہے)، آپ اسے اپنی دستاویزات میں تلاش کرنے کی صلاحیت دیتے ہیں۔ جب کوئی سوال کرتا ہے، تو نظام متعلقہ معلومات تلاش کرتا ہے اور اسے پرامپٹ میں شامل کرتا ہے۔ ماڈل پھر اس بازیافت شدہ سیاق و سباق کی بنیاد پر جواب دیتا ہے۔ -RAG کو ماڈل کو ایک حوالہ جات لائبریری دینے کے طور پر سوچیں۔ جب آپ سوال پوچھتے ہیں، تو نظام: +RAG کو ایسے سمجھیں کہ آپ ماڈل کو ایک حوالہ جاتی لائبریری دے رہے ہیں۔ جب آپ سوال کرتے ہیں، تو نظام: -1. **صارف کا سوال** - آپ سوال پوچھتے ہیں -2. **ایمبیڈنگ** - آپ کے سوال کو ویکٹر میں تبدیل کرتا ہے -3. **ویکٹر تلاش** - ملتے جلتے دستاویزی چنکس تلاش کرتا ہے -4. **سیاق و سباق کی ترتیب** - متعلقہ چنکس پرامپٹ میں شامل کرتا ہے -5. **جواب** - ایل ایل ایم اس سیاق و سباق کی بنیاد پر جواب تیار کرتا ہے +1. **صارف کا سوال** - آپ سوال کرتے ہیں +2. **ایمبیڈنگ** - آپ کے سوال کو ویکٹر میں تبدیل کرتا ہے +3. **ویکٹر سرچ** - متعلقہ دستاویز کے چنکس تلاش کرتا ہے +4. **کانٹیکسٹ اسمبلی** - متعلقہ چنکس کو پرامپٹ میں شامل کرتا ہے +5. **جواب** - LLM سیاق و سباق کی بنیاد پر جواب تیار کرتا ہے -یہ ماڈل کے جوابات کو آپ کے حقیقی ڈیٹا پر مبنی بناتا ہے، بجائے اس کے کہ وہ اپنی تربیت کی معلومات پر انحصار کرے یا فرضی جوابات بنائے۔ +یہ ماڈل کے جوابات کو آپ کے اصل ڈیٹا پر قائم کرتا ہے بجائے اس کے کہ وہ اپنی تربیتی معلومات پر انحصار کرے یا جوابات خود بنا سکے۔ -## ضروریات +## پری ریکوزٹس -- مکمل شدہ [ماڈیول 00 - فوری شروعات](../00-quick-start/README.md) (اس ماڈیول میں بعد میں حوالہ دیا گیا آسان RAG مثال کے لیے) -- مکمل شدہ [ماڈیول 01 - تعارف](../01-introduction/README.md) (Azure OpenAI وسائل تعینات کیے ہوئے، بشمول `text-embedding-3-small` ایمبیڈنگ ماڈل) -- روٹ ڈائریکٹری میں `.env` فائل جس میں Azure کی شناختی معلومات ہوں (جو ماڈیول 01 میں `azd up` کے ذریعہ بنائی گئی ہو) +- مکمل شدہ [ماڈیول 01 - تعارف](../01-introduction/README.md) (Azure OpenAI وسائل تعینات کیے گئے، بشمول `text-embedding-3-small` ایمبیڈنگ ماڈل) +- روٹ ڈائریکٹری میں `.env` فائل Azure اسناد کے ساتھ (جو ماڈیول 01 میں `azd up` کی مدد سے بنائی گئی ہے) -> **نوٹ:** اگر آپ نے ماڈیول 01 مکمل نہیں کیا تو سب سے پہلے وہاں دی گئی تعیناتی کی ہدایات پر عمل کریں۔ `azd up` کمانڈ GPT چیٹ ماڈل اور اس ماڈیول میں استعمال ہونے والے ایمبیڈنگ ماڈل دونوں کو تعینات کرتی ہے۔ +> **نوٹ:** اگر آپ نے ماڈیول 01 مکمل نہیں کیا ہے، تو پہلے وہاں دی گئی تعیناتی کی ہدایات پر عمل کریں۔ `azd up` کمانڈ GPT چیٹ ماڈل اور اس ماڈیول میں استعمال ہونے والے ایمبیڈنگ ماڈل دونوں کو تعینات کرتا ہے۔ ## RAG کو سمجھنا -نیچے دیا گیا خاکہ بنیادی تصور کی وضاحت کرتا ہے: ماڈل کی تربیتی ڈیٹا پر انحصار کرنے کے بجائے، RAG اسے آپ کی دستاویزات کی حوالہ جاتی لائبریری دیتا ہے تاکہ ہر جواب تیار کرنے سے پہلے اسے رجوع کیا جا سکے۔ +ذیل میں دیا گیا خاکہ بنیادی تصور کو ظاہر کرتا ہے: ماڈل کی تربیت ڈیٹا پر انحصار کرنے کی بجائے، RAG اسے آپ کی دستاویزات کی ایک حوالہ جاتی لائبریری دیتا ہے تاکہ ہر جواب تیار کرنے سے پہلے اس سے رجوع کیا جا سکے۔ -RAG کیا ہے +What is RAG -*یہ خاکہ عام ایل ایل ایم (جو تربیتی ڈیٹا سے اندازہ لگاتا ہے) اور RAG سے بڑھا ہوا ایل ایل ایم (جو پہلے آپ کی دستاویزات سے رجوع کرتا ہے) کے درمیان فرق دکھاتا ہے۔* +*یہ خاکہ ایک عام LLM (جو تربیتی ڈیٹا سے اندازہ لگاتا ہے) اور ایک RAG سے بہتر بنایا گیا LLM (جو پہلے آپ کی دستاویزات سے رجوع کرتا ہے) کے درمیان فرق دکھاتا ہے۔* -یہاں مرحلہ بہ مرحلہ کنییکشن دکھایا گیا ہے۔ صارف کا سوال چار مراحل سے گزرتا ہے — ایمبیڈنگ، ویکٹر تلاش، سیاق و سباق کی ترتیب، اور جواب سازی — جو ایک دوسرے پر مبنی ہیں: +یہاں بتایا گیا ہے کہ تمام اجزاء آپس میں کیسے جڑتے ہیں۔ صارف کا سوال چار مراحل سے گزرتا ہے — ایمبیڈنگ، ویکٹر سرچ، کانٹیکسٹ اسمبلی، اور جواب کی تخلیق — ہر ایک پچھلے پر مبنی ہے: -RAG آرکیٹیکچر +RAG Architecture -*یہ خاکہ RAG کا مکمل راستہ دکھاتا ہے — صارف کا سوال ایمبیڈنگ، ویکٹر تلاش، سیاق و سباق کی ترتیب، اور جواب سازی سے گزرتا ہے۔* +*یہ خاکہ RAG کی پوری لائن دکھاتا ہے — ایک صارف کا سوال ایمبیڈنگ، ویکٹر سرچ، کانٹیکسٹ اسمبلی، اور جواب کی تخلیق سے گزرتا ہے۔* -اس ماڈیول میں باقی حصہ ہر مرحلے کو تفصیل سے سمجھاتا ہے، جس میں آپ چلانے اور ترمیم کرنے کے لیے کوڈ بھی شامل ہے۔ +ماڈیول کے بقیہ حصے میں ہر مرحلے کو تفصیل سے سمجھایا گیا ہے، ساتھ ہی کوڈ بھی فراہم کیا گیا ہے جسے آپ چلا اور ترمیم کر سکتے ہیں۔ -### یہ ٹیوٹوریل کونسا RAG طریقہ استعمال کرتا ہے؟ +### یہ ٹیوٹوریل کون سا RAG طریقہ استعمال کرتا ہے؟ -LangChain4j تین طریقے پیش کرتا ہے RAG کو نافذ کرنے کے لیے، ہر ایک مختلف سطح کے انتزاع کے ساتھ۔ نیچے دیا گیا خاکہ ان کا موازنہ کرتا ہے: +LangChain4j تین طریقے فراہم کرتا ہے RAG کو نافذ کرنے کے لیے، ہر ایک مختلف سطح کی پیچیدگی کے ساتھ۔ ذیل کا خاکہ انہیں ایک ساتھ موازنہ کرتا ہے: -LangChain4j میں تین RAG طریقے +Three RAG Approaches in LangChain4j -*یہ خاکہ LangChain4j کے تین RAG طریقوں — آسان، نیٹو، اور ایڈوانسڈ — کا موازنہ کرتا ہے، ان کے اہم اجزاء اور استعمال کا وقت دکھاتا ہے۔* +*یہ خاکہ LangChain4j کے تین RAG طریقوں — آسان، نیٹو، اور ایڈوانسڈ — کے کلیدی اجزاء اور استعمال کے اوقات دکھاتا ہے۔* -| طریقہ | یہ کیا کرتا ہے | فائدہ / نقصان | +| طریقہ | کیا کرتا ہے | سود و نقصان | |---|---|---| -| **آسان RAG** | `AiServices` اور `ContentRetriever` کے ذریعہ ہر چیز خودکار طریقے سے کنیکٹ ہوتی ہے۔ آپ انٹرفیس کی تشریح کرتے ہیں، ریٹریور منسلک کرتے ہیں، اور LangChain4j ایمبیڈنگ، تلاش، اور پرامپٹ اسمبلی کو پس منظر میں سنبھالتا ہے۔ | کم کوڈ، مگر آپ ہر مرحلے پر عین کیا ہو رہا ہے نہیں دیکھ پاتے۔ | -| **نیٹو RAG** | آپ خود ایمبیڈنگ ماڈل کو کال کرتے ہیں، اسٹور میں تلاش کرتے ہیں، پرامپٹ بناتے ہیں، اور جواب تیار کرتے ہیں — ہر مرحلے کو واضح طور پر ایک ایک کرکے۔ | زیادہ کوڈ، مگر ہر مرحلہ واضح اور قابل ترمیم ہوتا ہے۔ | -| **ایڈوانسڈ RAG** | `RetrievalAugmentor` فریم ورک استعمال کرتا ہے جس میں قابل تبدیلی سوال ٹرانسفارمرز، راؤٹرز، ری-رینکرز، اور مواد انجیکٹرز ہوتے ہیں جو پروڈکشن گریڈ پائپ لائنز کے لیے۔ | زیادہ سے زیادہ لچکدار، لیکن خاصی پیچیدگی کے ساتھ۔ | +| **آسان RAG** | `AiServices` اور `ContentRetriever` کے ذریعے سب کچھ خود بخود کنفیگر کرتا ہے۔ آپ ایک انٹرفیس اینوٹ کرتے ہیں، ریٹریور لگاتے ہیں، اور LangChain4j ایمبیڈنگ، سرچ، اور پرامپٹ اسمبلی کو پیچھے سے سنبھالتا ہے۔ | کوڈ بہت کم، لیکن ہر مرحلے کی واضح تفصیل نظر نہیں آتی۔ | +| **نیٹو RAG** | آپ خود ایمبیڈنگ ماڈل کو کال کرتے ہیں، اسٹور میں سرچ کرتے ہیں، پرامپٹ بناتے ہیں، اور جواب تخلیق کرتے ہیں — ہر قدم واضح اور خود کنٹرول ہوتا ہے۔ | زیادہ کوڈ، لیکن ہر مرحلہ صاف نظر آتا ہے اور ترمیم کے قابل ہے۔ | +| **ایڈوانسڈ RAG** | `RetrievalAugmentor` فریم ورک استعمال کرتا ہے جس میں پلگ ایبل کوئری ٹرانسفارمرز، راؤٹرز، ری رینکرز، اور مواد ڈالنے والے شامل ہیں، جو پروڈکشن لیول پائپ لائنز کے لیے مناسب ہیں۔ | بے حد لچکدار، لیکن کافی پیچیدہ۔ | -**یہ ٹیوٹوریل نیٹو طریقہ استعمال کرتا ہے۔** RAG کے ہر مرحلے — سوال کی ایمبیڈنگ، ویکٹر اسٹور کی تلاش، سیاق و سباق کی ترتیب، اور جواب کی پیدائش — کو واضح طور پر [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) میں لکھا گیا ہے۔ یہ جان بوجھ کر کیا گیا ہے: ایک تعلیمی وسیلہ کے طور پر، ہر مرحلہ دیکھنا اور سمجھنا زیادہ اہم ہے بجائے اس کے کہ کوڈ کو کم سے کم کیا جائے۔ جب آپ کو یہ سمجھ آ جائے کہ کیسے سب حصے ملتے ہیں، تو آپ آسان RAG پر جا کر تیزی سے پروٹوٹائپس بنا سکتے ہیں یا پیمنت سسٹمز کے لیے ایڈوانسڈ RAG استعمال کر سکتے ہیں۔ +**یہ ٹیوٹوریل نیٹو طریقہ استعمال کرتا ہے۔** RAG پائپ لائن کے ہر مرحلے — کوئری ایمبیڈنگ، ویکٹر اسٹور سرچ، کانٹیکسٹ اسمبلی، اور جواب تیار کرنا — کو [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) میں واضح طور پر لکھا گیا ہے۔ یہ جان بوجھ کر کیا گیا ہے: سیکھنے کے لیے، ہر مرحلے کو دیکھنا اور سمجھنا زیادہ ضروری ہے بجائے اس کے کہ کوڈ کم سے کم ہو۔ جب آپ کو عمل کا اچھا فہم ہو جائے، تو آپ تیز پروٹوٹائپس کے لیے آسان RAG یا پروڈکشن کے لیے ایڈوانسڈ RAG پر جا سکتے ہیں۔ -> **💡 کیا آپ نے آسان RAG پہلے ہی دیکھا ہے؟** [فوری شروعات ماڈیول](../00-quick-start/README.md) میں ایک دستاویز Q&A مثال شامل ہے ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) جو آسان RAG طریقہ استعمال کرتی ہے — LangChain4j خودکار طریقے سے ایمبیڈنگ، تلاش، اور پرامپٹ اسمبلی سنبھالتا ہے۔ یہ ماڈیول اگلا قدم اٹھاتا ہے اور اس پائپ لائن کو کھولتا ہے تاکہ آپ ہر مرحلے کو خود دیکھ سکیں اور کنٹرول کر سکیں۔ +> **💡 آسان RAG میں دلچسپی ہے؟** LangChain4j ایک *آسان RAG* طریقہ بھی پیش کرتا ہے جہاں `AiServices` اور `ContentRetriever` ایمبیڈنگ، سرچ، اور پرامپٹ اسمبلی کو خودکار طریقے سے سنبھالتے ہیں۔ یہ ماڈیول زیادہ واضح راستہ اپناتا ہے — اس پائپ لائن کو کھول کر ہر مرحلے کو خود دیکھنے اور کنٹرول کرنے کے لیے۔ -نیچے دیا گیا خاکہ اسی فوری شروعات مثال سے آسان RAG پائپ لائن دکھاتا ہے۔ دھیان دیں کہ کیسے `AiServices` اور `EmbeddingStoreContentRetriever` تمام پیچیدگی کو چھپاتے ہیں — آپ دستاویز لوڈ کرتے ہیں، ریٹریور جوڑتے ہیں، اور جواب پاتے ہیں۔ اس ماڈیول میں نیٹو طریقہ ان چھپے ہوئے اقدامات کو کھول دیتا ہے: +ذیل کا خاکہ آسان RAG پائپ لائن دکھاتا ہے۔ دھیان دیں کہ `AiServices` اور `EmbeddingStoreContentRetriever` کیسے تمام پیچیدگی کو چھپاتے ہیں — آپ ایک دستاویز لوڈ کرتے ہیں، ریٹریور لگاتے ہیں، اور جوابات حاصل کرتے ہیں۔ اس ماڈیول میں نیٹو طریقہ کار ہر چھپے ہوئے مرحلے کو کھولتا ہے: -آسان RAG پائپ لائن - LangChain4j +Easy RAG Pipeline - LangChain4j -*یہ خاکہ `SimpleReaderDemo.java` سے آسان RAG پائپ لائن دکھاتا ہے۔ اس کا موازنہ اس ماڈیول میں استعمال ہونے والے نیٹو طریقہ سے کریں: آسان RAG ایمبیڈنگ، ریٹریول، اور پرامپٹ اسمبلی کو `AiServices` اور `ContentRetriever` کے پیچھے چھپا دیتا ہے — آپ دستاویز لوڈ کرتے ہیں، ریٹریور جوڑتے ہیں، اور جواب لیتے ہیں۔ نیٹو طریقہ ہر مرحلہ (ایمبیڈ، تلاش، سیاق و سباق ترتیب، جنریشن) کو خود کال کرکے آپ کو مکمل نظر اور کنٹرول دیتا ہے۔* +*یہ خاکہ آسان RAG پائپ لائن دکھاتا ہے۔ اسے اس ماڈیول میں استعمال کیے گئے نیٹو طریقے سے موازنہ کریں: آسان RAG ایمبیڈنگ، بازیافت، اور پرامپٹ اسمبلی کو `AiServices` اور `ContentRetriever` کے پیچھے چھپاتا ہے — آپ دستاویز لوڈ کریں، ریٹریور لگائیں، اور جوابات حاصل کریں۔ اس ماڈیول کا نیٹو طریقہ وہ پائپ لائن کھولتا ہے تاکہ آپ ہر مرحلہ (ایمبیڈ، تلاش، کانٹیکسٹ بنائیں، جواب تیار کریں) خود کال کریں، اس طرح آپ کو مکمل رویت اور کنٹرول ملتا ہے۔* ## یہ کیسے کام کرتا ہے -اس ماڈیول میں RAG پائپ لائن چار مرحلوں میں تقسیم ہے جو صارف کے ہر سوال پر تسلسل سے چلتے ہیں۔ سب سے پہلے، اپلوڈ کی گئی دستاویز کو **پارسی اور چنکس** میں تقسیم کیا جاتا ہے تاکہ آسانی سے سنبھالا جا سکے۔ پھر یہ چنکس **ویکٹر ایمبیڈنگز** میں تبدیل ہوتے ہیں اور محفوظ کیے جاتے ہیں تاکہ ریاضیاتی موازنہ کیا جا سکے۔ جب کوئی سوال آتا ہے، تو نظام **معنوی تلاش** کرتا ہے تاکہ سب سے متعلقہ چنکس فراہم کرے، اور آخر میں انہیں LLM کو **جواب تخلیق** کے لیے سیاق کے طور پر دیتا ہے۔ ذیل کے سیکشنز ہر مرحلے کو کوڈ اور خاکے کے ساتھ وضاحت کرتے ہیں۔ پہلے مرحلے پر نظر ڈالتے ہیں۔ +اس ماڈیول میں RAG پائپ لائن چار مراحل پر مشتمل ہے جو ہر بار جب صارف سوال کرتا ہے ترتیب سے چلتے ہیں۔ سب سے پہلے، اپلوڈ کی گئی دستاویز کو **پارز اور چنکس میں تقسیم** کیا جاتا ہے۔ پھر وہ چنکس **ویکٹر ایمبیڈنگز** میں تبدیل کیے جاتے ہیں اور اس طرح محفوظ کیے جاتے ہیں کہ وہ ریاضیاتی طور پر موازنہ کیے جا سکیں۔ جب کوئی سوال آتا ہے، تو نظام **سیمنٹک سرچ** کرتا ہے تاکہ سب سے متعلقہ چنکس مل سکیں، اور آخر میں انہیں LLM کو **جواب تخلیق** کے لیے بطور سیاق و سباق دیتا ہے۔ ذیل کے سیکشن ہر مرحلے کو کوڈ اور خاکوں کے ساتھ تفصیل سے سمجھاتے ہیں۔ آئیے پہلے مرحلے کو دیکھتے ہیں۔ ### دستاویز کی پراسیسنگ [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -جب آپ دستاویز اپلوڈ کرتے ہیں، تو نظام اسے پارس کرتا ہے (PDF یا سادہ متن)، فائل نام جیسی میٹا ڈیٹا جوڑتا ہے، اور پھر اسے چنکس میں تقسیم کرتا ہے — چھوٹے حصے جو ماڈل کے سیاق و سباق ونڈو میں آسانی سے فٹ ہو جاتے ہیں۔ یہ چنکس معمولی حد تک اوورلیپ کرتے ہیں تاکہ سرحدوں پر سیاق و سباق نہ کھو جائے۔ +جب آپ ایک دستاویز اپلوڈ کرتے ہیں، تو نظام اسے پارز کرتا ہے (PDF یا سادہ متن)، فائل نام جیسی میٹا ڈیٹا لگاتا ہے، اور پھر اسے چنکس میں توڑ دیتا ہے — چھوٹے حصے جو ماڈل کے کانٹیکسٹ ونڈو میں آرام سے فٹ آ جاتے ہیں۔ یہ چنکس تھوڑا سا اوورلیپ کرتے ہیں تاکہ آپ سرحدوں پر سیاق و سباق نہ کھویں۔ ```java -// اپ لوڈ کی گئی فائل کو پارس کریں اور اسے ایک LangChain4j دستاویز میں لپیٹیں +// اپ لوڈ کی گئی فائل کو پارس کریں اور اسے LangChain4j دستاویز میں لپیٹیں Document document = Document.from(content, metadata); -// 300 ٹوکن کے ٹکڑوں میں تقسیم کریں جس میں 30 ٹوکن کی اوورلیپ ہو +// 300 ٹوکن کے ٹکڑوں میں تقسیم کریں جس میں 30 ٹوکن کا اوور لیپ ہو DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -نیچے دیا گیا خاکہ بصری طور پر دکھاتا ہے کہ یہ کیسے کام کرتا ہے۔ دھیان دیں کہ ہر چنک اپنے پڑوسیوں کے ساتھ کچھ ٹوکنز شیئر کرتا ہے — 30 ٹوکن کا اوورلیپ یقینی بناتا ہے کہ کوئی اہم سیاق و سباق درمیان میں چھوٹ نہ جائے: +ذیل کا خاکہ بصری طور پر دکھاتا ہے کہ یہ کیسے کام کرتا ہے۔ دیکھیں کہ ہر چنک اپنے پڑوسیوں کے ساتھ کچھ ٹوکنز شیئر کرتا ہے — 30 ٹوکن اوورلیپ اس بات کو یقینی بناتا ہے کہ کوئی اہم سیاق باہم درمیان میں نہ گم ہو: -دستاویز کی چنکنگ +Document Chunking -*یہ خاکہ دکھاتا ہے کہ دستاویز کو 300-ٹوکن چنکس میں تقسیم کیا جاتا ہے جس میں 30-ٹوکن اوورلیپ ہوتا ہے، تاکہ چنک کی سرحدوں پر سیاق و سباق محفوظ رہے۔* +*یہ خاکہ دکھاتا ہے کہ دستاویز کو 300 ٹوکن کے چنکس میں تقسیم کیا جا رہا ہے جس میں 30 ٹوکن اوورلیپ ہے، تاکہ چنک کی سرحدوں پر سیاق و سباق برقرار رہے۔* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمائیں:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) کھولیں اور پوچھیں: -> - "LangChain4j دستاویزات کو چنکس میں کیسے تقسیم کرتا ہے اور اوورلیپ کیوں اہم ہے؟" -> - "مختلف دستاویز کی اقسام کے لیے مثالی چنک سائز کیا ہے اور کیوں؟" -> - "میں متعدد زبانوں یا خاص فارمیٹنگ والی دستاویزات کو کیسے سنبھالتا ہوں؟" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ کوشش کریں:** [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) کھولیں اور پوچھیں: +> - "LangChain4j دستاویزات کو چنکس میں کیسے تقسیم کرتا ہے اور اوورلیپ کیوں ضروری ہے؟" +> - "مختلف دستاویز کی اقسام کے لیے مثالی چنک سائز کیا ہے اور کیوں؟" +> - "میں متعدد زبانوں یا خاص فارمیٹنگ والی دستاویزات کو کیسے ہینڈل کرتا ہوں؟" -### ایمبیڈنگ بنانا +### ایمبیڈنگز بنانا [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -ہر چنک کو ایک عددی نمائندگی میں تبدیل کیا جاتا ہے جسے ایمبیڈنگ کہا جاتا ہے — بنیادی طور پر ایک معنی سے اعداد میں کنورٹر۔ ایمبیڈنگ ماڈل وہ "ذہین" ماڈل نہیں ہے جیسا کہ چیٹ ماڈل ہے؛ یہ ہدایات پر عمل نہیں کر سکتا، استدلال نہیں کر سکتا، یا سوالات کے جواب نہیں دے سکتا۔ جو یہ کر سکتا ہے وہ ہے متن کو ایک ریاضیاتی جگہ میں میپ کرنا جہاں ملتے جلتے معنی ایک دوسرے کے قریب آتے ہیں — "گاڑی" "آٹوموبائل" کے قریب، "رقم واپس کرنے کی پالیسی" "میری رقم واپس کرو" کے قریب۔ چیٹ ماڈل کو ایک شخص سمجھیں جس سے بات کی جا سکتی ہے؛ ایمبیڈنگ ماڈل ایک بہت عمدہ فائلنگ سسٹم ہے۔ +ہر چنک کو ایک عددی نمائندگی میں تبدیل کیا جاتا ہے جسے ایمبیڈنگ کہتے ہیں — بنیادی طور پر معنی کو نمبرز میں تبدیل کرنے والا آلہ۔ ایمبیڈنگ ماڈل "ذہین" نہیں ہوتا جیسا کہ چیٹ ماڈل ہوتا ہے؛ یہ ہدایات پر عمل نہیں کر سکتا، استدلال نہیں کر سکتا، یا سوالات کا جواب نہیں دے سکتا۔ جو یہ کر سکتا ہے وہ یہ ہے کہ متن کو ایسے ریاضیاتی جگہ میں نقش کر دے جہاں ایک جیسے معنی ایک دوسرے کے قریب واقع ہوتے ہیں — "کار" "گاڑی" کے قریب، "ریفنڈ پالیسی" "میرے پیسے واپس کرو" کے قریب۔ چیٹ ماڈل کو ایک انسان سمجھیں جس سے آپ بات کر سکتے ہیں؛ اور ایمبیڈنگ ماڈل کو ایک بہت ہی اچھا فائلنگ نظام سمجھیں۔ -نیچے دیا گیا خاکہ اس تصور کو تصویری انداز میں دکھاتا ہے — متن اندر جاتا ہے، عددی ویکٹرز باہر آتے ہیں، اور ملتے جلتے معنی قریب قریب ویکٹر بناتے ہیں: +ذیل کا خاکہ اس تصور کو دکھاتا ہے — متن آتا ہے، عددی ویکٹر نکلتے ہیں، اور ایک جیسے معنی قریب ویکٹر پیدا کرتے ہیں: -ایمبیڈنگ ماڈل کا تصور +Embedding Model Concept -*یہ خاکہ دکھاتا ہے کہ ایک ایمبیڈنگ ماڈل متن کو عددی ویکٹرز میں کیسے تبدیل کرتا ہے، جہاں ملتے جلتے معنی — جیسے "گاڑی" اور "آٹوموبائل" — ویکٹر اسپیس میں ایک دوسرے کے قریب ہوتے ہیں۔* +*یہ خاکہ دکھاتا ہے کہ ایمبیڈنگ ماڈل متن کو عددی ویکٹرز میں کیسے تبدیل کرتا ہے، اسی طرح کے معنی مثلاً "کار" اور "گاڑی" کو ویکٹر اسپیس میں ایک دوسرے کے قریب رکھتا ہے۔* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -ذیل میں دیا گیا کلاس ڈایاگرام RAG پائپ لائن کے دو مختلف فلو اور LangChain4j کی وہ کلاسیں دکھاتا ہے جو انہیں نافذ کرتی ہیں۔ **انجیشن فلو** (جو اپلوڈ کے وقت ایک بار چلتا ہے) دستاویز کو تقسیم کرتا ہے، چنکس کو ایمبیڈ کرتا ہے، اور انہیں `.addAll()` کے ذریعہ محفوظ کرتا ہے۔ **سوال فلو** (جو ہر بار جب صارف سوال کرے چلتا ہے) سوال کو ایمبیڈ کرتا ہے، `.search()` کے ذریعہ اسٹور میں تلاش کرتا ہے، اور میچ شدہ سیاق کو چیٹ ماڈل کو منتقل کرتا ہے۔ دونوں فلو مشترکہ `EmbeddingStore` انٹرفیس پر ملتے ہیں: +ذیل کا کلاس ڈایاگرام RAG پائپ لائن میں دو الگ الگ فلوز اور LangChain4j کی کلاسز کو دکھاتا ہے جو انہیں نافذ کرتی ہیں۔ **انریشن فلور** (اپلوڈ کے وقت ایک بار چلتا ہے) دستاویز کو تقسیم کرتا ہے، چنکس کو ایمبیڈ کرتا ہے، اور `.addAll()` کے ذریعے ذخیرہ کرتا ہے۔ **کوئری فلور** (ہر بار جب صارف سوال کرتا ہے) سوال کو ایمبیڈ کرتا ہے، `.search()` کے ذریعے اسٹور میں تلاش کرتا ہے، اور میچ شدہ کانٹیکسٹ کو چیٹ ماڈل کو دیتا ہے۔ دونوں فلوز مشترکہ `EmbeddingStore` انٹرفیس پر ملتے ہیں: -LangChain4j RAG کلاسز +LangChain4j RAG Classes -*یہ خاکہ RAG پائپ لائن میں دو فلو — انجیشن اور سوال — دکھاتا ہے اور یہ کہ وہ مشترکہ EmbeddingStore کے ذریعے کیسے جڑتے ہیں۔* +*یہ خاکہ RAG پائپ لائن کے دونوں فلوز — انریشن اور کوئری — اور ان کے مشترکہ EmbeddingStore کے ذریعے جڑنے کو دکھاتا ہے۔* -ایک بار ایمبیڈنگز محفوظ ہو جانے کے بعد، ملتے جلتے مواد قدرتی طور پر ویکٹر اسپیس میں ایک ساتھ کلسٹر ہوتے ہیں۔ نیچے دیا گیا عکس دکھاتا ہے کہ متعلقہ موضوعات والی دستاویزات کیسے قریب قریب پوائنٹس میں ختم ہوتی ہیں، جو معنوی تلاش کو ممکن بناتا ہے: +ایک بار ایمبیڈنگز محفوظ ہو جائیں، تو مشابہ مواد قدرتی طور پر ویکٹر اسپیس میں ایک ساتھ گروہ بند ہو جاتے ہیں۔ ذیل کی وضاحت دکھاتی ہے کہ متعلقہ موضوعات والی دستاویزات قریب نزدیک پوائنٹس کی صورت میں بنتی ہیں، جو سیمنٹک سرچ کو ممکن بناتی ہے: -ویکٹر ایمبیڈنگ اسپیس +Vector Embeddings Space -*یہ عکس دکھاتا ہے کہ متعلقہ دستاویزات تین جہتی ویکٹر اسپیس میں کیسے کلسٹر ہوتی ہیں، جس میں تکنیکی دستاویزات، کاروباری قواعد، اور سوالات و جوابات کے مختلف گروپس بنتے ہیں۔* +*یہ وضاحت دکھاتی ہے کہ تکنیکی دستاویزات، کاروباری قواعد، اور اکثر پوچھے جانے والے سوالات جیسے موضوعات 3D ویکٹر اسپیس میں ایک خاص گروہ بناتے ہیں۔* -جب صارف تلاش کرتا ہے، تو نظام چار مراحل پر عمل کرتا ہے: دستاویزات کو ایک بار ایمبیڈ کرنا، ہر تلاش پر سوال کو ایمبیڈ کرنا، سوال کے ویکٹر کا اسٹور کے سبھی ویکٹرز سے کوسائن مشابہت کے ذریعے موازنہ کرنا، اور سب سے اوپر کے-K اسکور والے چنکس واپس کرنا۔ نیچے دیا گیا خاکہ اس عمل اور LangChain4j کی شامل کلاسز کو دکھاتا ہے: +جب کوئی صارف تلاش کرتا ہے، تو نظام چار مراحل پر عمل کرتا ہے: دستاویزات کو ایک بار ایمبیڈ کرتا ہے، ہر تلاش پر سوال کو ایمبیڈ کرتا ہے، سوال کے ویکٹر کو تمام ذخیرہ شدہ ویکٹرز سے کوسائن سیمیلیریٹی کے ذریعے موازنہ کرتا ہے، اور سب سے زیادہ اسکورنگ والے چنکس واپس کرتا ہے۔ ذیل کا خاکہ ہر مرحلے اور شامل LangChain4j کلاسز کو دکھاتا ہے: -ایمبیڈنگ تلاش کے مراحل +Embedding Search Steps -*یہ خاکہ ایمبیڈنگ تلاش کے چار مراحل دکھاتا ہے: دستاویزات کو ایمبیڈ کرنا، سوال کو ایمبیڈ کرنا، کوسائن مشابہت کے ساتھ ویکٹرز کا موازنہ کرنا، اور اوپر کے-K نتائج واپس کرنا۔* +*یہ خاکہ چار مرحلے پر مشتمل ایمبیڈنگ سرچ کے عمل کو دکھاتا ہے: دستاویزات کو ایمبیڈ کریں، سوال کو ایمبیڈ کریں، ویکٹرز کا کوسائن سیمیلیریٹی سے موازنہ کریں، اور ٹاپ-K نتائج واپس کریں۔* -### معنوی تلاش +### سیمنٹک سرچ [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -جب آپ سوال پوچھتے ہیں، تو آپ کا سوال بھی ایمبیڈنگ بن جاتا ہے۔ نظام آپ کے سوال کی ایمبیڈنگ کا موازنہ دستاویزی چنکس کی ایمبیڈنگز سے کرتا ہے۔ یہ صرف ملتے جلتے کی ورڈز ہی نہیں دیکھتا بلکہ اصلی معنوی مشابہت کو پہچانتا ہے۔ +جب آپ سوال کرتے ہیں، تو آپ کا سوال بھی ایک ایمبیڈنگ بن جاتا ہے۔ نظام آپ کے سوال کی ایمبیڈنگ کا موازنہ تمام دستاویز چنکس کی ایمبیڈنگز سے کرتا ہے۔ یہ چنکس تلاش کرتا ہے جن کے معنی سب سے زیادہ ملتے جلتے ہوں — صرف کلیدی الفاظ نہیں بلکہ اصل معنوی مماثلت۔ ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -نیچے دیا گیا خاکہ معنوی تلاش کو روایتی کی ورڈ تلاش کے ساتھ موازنہ کرتا ہے۔ "گاڑی" کے کی ورڈ تلاش سے "کار اور ٹرک" والے چنک کو نہیں ملتا، لیکن معنوی تلاش سمجھتا ہے کہ یہ ایک ہی بات ہے اور اسے اعلیٰ اسکورنگ میچ کے طور پر واپس کرتا ہے: +ذیل کا خاکہ سیمنٹک سرچ کو روایتی کلیدی لفظ تلاش کے مقابلے میں دکھاتا ہے۔ "vehicle" کے لیے کلیدی لفظ تلاش "cars and trucks" والے چنک کو نہیں ڈھونڈ پاتی، لیکن سیمنٹک سرچ سمجھتی ہے کہ وہ ایک ہی مطلب رکھتے ہیں اور اسے اعلی اسکور کے ساتھ واپس کرتی ہے: -معنوی تلاش +Semantic Search -*یہ خاکہ کی ورڈ کی بنیاد پر تلاش کو معنوی تلاش کے ساتھ موازنہ کرتا ہے، دکھاتا ہے کہ معنوی تلاش کس طرح ایسی چیزیں تلاش کرتی ہے جو تصوراتی طور پر متعلقہ ہوں چاہے صحیح کی ورڈز مختلف ہوں۔* -اندرونی طور پر، مماثلت کو کوسائن سمتیہ کے ذریعے ناپا جاتا ہے — بنیادی طور پر یہ پوچھتے ہوئے کہ "کیا یہ دونوں تیر ایک ہی سمت میں اشارہ کر رہے ہیں؟" دو ٹکڑے بالکل مختلف الفاظ استعمال کر سکتے ہیں، لیکن اگر ان کا مطلب ایک ہی ہو تو ان کے ویکٹر ایک ہی سمت میں اشارہ کرتے ہیں اور اسکور قریب 1.0 آتا ہے: +*یہ خاکہ کلیدی لفظ پر مبنی تلاش اور سیمنٹک تلاش کا موازنہ کرتا ہے، دکھاتا ہے کہ سیمنٹک تلاش اس مواد کو بھی بازیافت کرتی ہے جس کا تعلق تصوری طور پر ہوتا ہے چاہے کلیدی الفاظ مختلف ہوں۔* -Cosine Similarity +نیچے دیے گئے گرافی میں، ہم کوسائن سیمیلیریٹی کے ذریعے مشابہت کو ناپتے ہیں — یعنی "کیا یہ دو تیر ایک ہی سمت میں اشارہ کر رہے ہیں؟"۔ دو چنکس بالکل مختلف الفاظ استعمال کر سکتے ہیں، لیکن اگر وہ ایک ہی مطلب رکھتے ہیں تو ان کے ویکٹر ایک ہی سمت میں ہوں گے اور اسکور 1.0 کے قریب ہوگا: -*یہ خاکہ کوسائن سمتیہ کو ایمبیڈنگ ویکٹرز کے درمیان زاویہ کے طور پر دکھاتا ہے — زیادہ ہم آہنگ ویکٹرز کا اسکور 1.0 کے قریب ہوتا ہے، جو معنوی مماثلت کی زیادہ سطح ظاہر کرتا ہے۔* +Cosine Similarity +*یہ خاکہ کوسائن مماثلت کو ایمبیڈنگ ویکٹروں کے درمیان زاویہ کے طور پر ظاہر کرتا ہے — زیادہ ہم آہنگ ویکٹرز 1.0 کے قریب اسکور کرتے ہیں، جو زیادہ معنوی مماثلت کی نشاندہی کرتا ہے۔* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمانے کے لیے:** کھولیں [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) اور پوچھیں: -> - "ایمبیڈنگ کے ساتھ مماثلت تلاش کیسے کام کرتی ہے اور اسکور کس چیز سے طے ہوتا ہے؟" -> - "کونسا مماثلت حد استعمال کرنی چاہیے اور اس کے نتائج پر کیا اثرات ہوتے ہیں؟" -> - "جب کوئی متعلقہ دستاویز نہ ملے تو اس صورت میں کیا کرنا چاہیے؟" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ کوشش کریں:** [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) کھولیں اور پوچھیں: +> - "ایمبیڈنگز کے ساتھ مماثلت تلاش کیسے کام کرتی ہے اور اسکور کیا طے کرتا ہے؟" +> - "مجھے کون سا مماثلت کا حد استعمال کرنا چاہیے اور یہ نتائج کو کیسے متاثر کرتا ہے؟" +> - "میں ایسے معاملات کو کیسے ہینڈل کروں جہاں کوئی متعلقہ دستاویزات نہ ملیں؟" -### جواب کی تیاری +### جواب کی تخلیق [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -سب سے متعلقہ ٹکڑے ایک منظم پرامپٹ میں جمع کیے جاتے ہیں جس میں واضح ہدایات، بازیافت شدہ سیاق و سباق، اور یوزر کا سوال شامل ہوتا ہے۔ ماڈل ان مخصوص ٹکڑوں کو پڑھتا ہے اور انہی معلومات کی بنیاد پر جواب دیتا ہے — یہ صرف سامنے موجود مواد استعمال کر سکتا ہے، جو خیالی جوابات کو روکتا ہے۔ +سب سے متعلقہ ٹکڑے ایک منظم پرامپٹ میں جمع کیے جاتے ہیں جس میں واضح ہدایات، بازیافت شدہ سیاق و سباق، اور صارف کا سوال شامل ہوتا ہے۔ ماڈل ان مخصوص ٹکڑوں کو پڑھتا ہے اور اس معلومات کی بنیاد پر جواب دیتا ہے — یہ صرف سامنے موجود مواد استعمال کر سکتا ہے، جو ہیلوسینیشن کو روکتا ہے۔ ```java String context = matches.stream() @@ -237,51 +236,51 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -نیچے دیا گیا خاکہ اس کارکردگی کو دکھاتا ہے — تلاش کے مرحلے سے سب سے زیادہ اسکور والے ٹکڑے پرامپٹ ٹیمپلیٹ میں شامل کیے جاتے ہیں، اور `OpenAiOfficialChatModel` ایک مستند جواب تیار کرتا ہے: +نیچے دیا گیا خاکہ اس اسمبلنگ کو عملی طور پر دکھاتا ہے — تلاش کے مرحلے سے سب سے زیادہ اسکور کرنے والے ٹکڑے پرامپٹ ٹیمپلیٹ میں ڈاInject کیے جاتے ہیں، اور `OpenAiOfficialChatModel` ایک بنیاد فراہم کرنے والا جواب تیار کرتا ہے: Context Assembly -*یہ خاکہ دکھاتا ہے کہ کس طرح سب سے زیادہ اسکور والے ٹکڑے منظم پرامپٹ میں جمع کیے جاتے ہیں، جس سے ماڈل آپ کے ڈیٹا سے ایک مستند جواب پیدا کر سکتا ہے۔* +*یہ خاکہ دکھاتا ہے کہ کیسے سب سے زیادہ اسکور کرنے والے ٹکڑے ایک منظم پرامپٹ میں جمع کیے جاتے ہیں، ماڈل کو آپ کے ڈیٹا سے ایک بنیاد یافتہ جواب تیار کرنے کی اجازت دیتا ہے۔* ## ایپلیکیشن چلائیں -**نصب کرنے کی تصدیق کریں:** +**تصدیق کریں کہ تنصیب مکمل ہے:** -یقینی بنائیں کہ روٹ ڈائریکٹری میں `.env` فائل موجود ہے جس میں Azure اسناد ہیں (جو ماڈیول 01 کے دوران بنائی گئی تھیں)۔ ماڈیول ڈائریکٹری (`03-rag/`) سے اسے چلائیں: +یقین دہانی کریں کہ `.env` فائل روٹ ڈائریکٹری میں موجود ہے جس میں Azure کے اسناد ہیں (جو ماڈیول 01 کے دوران بنائی گئی تھیں)۔ اس کو ماڈیول ڈائریکٹری (`03-rag/`) سے چلائیں: **Bash:** ```bash -cat ../.env # دکھانا چاہیے AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT +cat ../.env # AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT دکھانا چاہیے ``` **PowerShell:** ```powershell -Get-Content ..\.env # دکھانا چاہئے AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT +Get-Content ..\.env # دکھانا چاہیے AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT ``` **ایپلیکیشن شروع کریں:** -> **نوٹ:** اگر آپ نے پہلے سے تمام ایپلیکیشنز کو `./start-all.sh` سے روٹ ڈائریکٹری میں (جیسے ماڈیول 01 میں بتایا گیا ہے) شروع کیا ہے، تو یہ ماڈیول پہلے ہی پورٹ 8081 پر چل رہا ہے۔ آپ نیچے دیے گئے شروع کرنے کے کمانڈز چھوڑ کر براہِ راست http://localhost:8081 پر جا سکتے ہیں۔ +> **نوٹ:** اگر آپ پہلے ہی روٹ ڈائریکٹری سے `./start-all.sh` استعمال کرکے تمام ایپلیکیشنز شروع کر چکے ہیں (جیسا کہ ماڈیول 01 میں بیان کیا گیا ہے)، تو یہ ماڈیول پہلے سے پورٹ 8081 پر چل رہا ہے۔ نیچے دیے گئے شروع کرنے کے کمانڈز کو نظر انداز کریں اور براہ راست http://localhost:8081 پر جائیں۔ -**اختیار 1: Spring Boot ڈیش بورڈ استعمال کریں (VS Code صارفین کے لیے تجویز کردہ)** +**آپشن 1: Spring Boot ڈیش بورڈ کا استعمال کرنا (VS کوڈ صارفین کے لیے تجویز کردہ)** -ڈیو کانٹینر میں Spring Boot ڈیش بورڈ ایکسٹینشن شامل ہے، جو تمام Spring Boot ایپلیکیشنز کو منظم کرنے کے لیے بصری انٹرفیس فراہم کرتا ہے۔ یہ VS Code میں بائیں طرف ایکٹیویٹی بار میں پایا جا سکتا ہے (Spring Boot آئیکن دیکھیں)۔ +ڈویلپمنٹ کنٹینر میں Spring Boot ڈیش بورڈ ایکسٹینشن شامل ہے، جو تمام Spring Boot ایپلیکیشنز کا ایک بصری انٹرفیس فراہم کرتا ہے۔ آپ اسے VS کوڈ کے بائیں جانب ایکٹیویٹی بار میں Spring Boot آئی کن کے طور پر دیکھ سکتے ہیں۔ Spring Boot ڈیش بورڈ سے آپ کر سکتے ہیں: -- ورک اسپیس میں دستیاب تمام Spring Boot ایپلیکیشنز دیکھنا -- ایک کلک سے ایپلیکیشنز شروع/بند کرنا -- ایپلیکیشن کے لاگز کو حقیقی وقت میں دیکھنا -- ایپلیکیشن کی حالت پر نگرانی رکھنا +- ورک اسپیس میں تمام دستیاب Spring Boot ایپلیکیشنز دیکھیں +- ایک کلک سے ایپلیکیشنز کو شروع/روکیں +- ایپلیکیشن لاگز کو حقیقی وقت میں دیکھیں +- ایپلیکیشن کی حالت کی نگرانی کریں -بس "rag" کے ساتھ پلے بٹن پر کلک کریں تاکہ یہ ماڈیول شروع ہو جائے، یا ایک ساتھ تمام ماڈیولز شروع کریں۔ +بس "rag" کے ساتھ موجود پلے بٹن پر کلک کریں تاکہ یہ ماڈیول شروع ہو، یا تمام ماڈیولز کو ایک ساتھ شروع کریں۔ Spring Boot Dashboard -*یہ اسکرین شاٹ VS Code میں Spring Boot ڈیش بورڈ دکھاتا ہے، جہاں آپ بصری طور پر ایپلیکیشنز کو شروع، بند اور مانیٹر کر سکتے ہیں۔* +*یہ اسکرین شاٹ VS کوڈ میں Spring Boot ڈیش بورڈ دکھاتا ہے، جہاں آپ ایپلیکیشنز کو بصری طور پر شروع، روک اور مانیٹر کر سکتے ہیں۔* -**اختیار 2: شیل اسکرپٹس استعمال کریں** +**آپشن 2: شیل اسکرپٹس کا استعمال** -تمام ویب ایپلیکیشنز (ماڈیولز 01-04) شروع کریں: +تمام ویب ایپلیکیشنز (ماڈیول 01-04) شروع کریں: **Bash:** ```bash @@ -295,7 +294,7 @@ cd .. # روٹ ڈائریکٹری سے .\start-all.ps1 ``` -یا صرف یہ ماڈیول شروع کریں: +یا صرف اس ماڈیول کو شروع کریں: **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -دونوں اسکرپٹس خودکار طریقے سے روٹ `.env` فائل سے ماحولیاتی متغیرات لوڈ کرتے ہیں اور اگر JAR فائلیں موجود نہ ہوں تو بناتے ہیں۔ +دونوں اسکرپٹس خودکار طریقے سے روٹ میں موجود `.env` فائل سے ماحول کے متغیرات لوڈ کرتے ہیں اور اگر JAR فائلز موجود نہیں ہوتیں تو انہیں بنائیں گے۔ -> **نوٹ:** اگر آپ پہلے سے تمام ماڈیولز کو دستی طور پر بنانا چاہتے ہیں: +> **نوٹ:** اگر آپ شروع کرنے سے پہلے تمام ماڈیولز کو دستی طور پر بنانا پسند کرتے ہیں تو: > > **Bash:** > ```bash @@ -327,7 +326,7 @@ cd 03-rag اپنے براؤزر میں http://localhost:8081 کھولیں۔ -**بند کرنے کے لیے:** +**رکنے کے لیے:** **Bash:** ```bash @@ -338,100 +337,100 @@ cd .. && ./stop-all.sh # تمام ماڈیولز **PowerShell:** ```powershell -.\stop.ps1 # صرف یہ ماڈیول +.\stop.ps1 # یہ صرف ماڈیول # یا cd ..; .\stop-all.ps1 # تمام ماڈیولز ``` ## ایپلیکیشن کا استعمال -ایپلیکیشن دستاویزات اپ لوڈ اور سوالات کے لیے ویب انٹرفیس فراہم کرتی ہے۔ +یہ ایپلیکیشن دستاویزات اپلوڈ کرنے اور سوال کرنے کے لیے ایک ویب انٹرفیس فراہم کرتی ہے۔ RAG Application Interface -*یہ اسکرین شاٹ RAG ایپلیکیشن انٹرفیس دکھاتا ہے جہاں آپ دستاویزات اپ لوڈ کرتے ہیں اور سوالات پوچھتے ہیں۔* +*یہ اسکرین شاٹ RAG ایپلیکیشن کا انٹرفیس دکھاتا ہے جہاں آپ دستاویزات اپلوڈ کرتے ہیں اور سوال کرتے ہیں۔* -### دستاویز اپ لوڈ کریں +### دستاویز اپلوڈ کریں -شروع کریں دستاویز اپ لوڈ کر کے — TXT فائلیں ٹیسٹنگ کے لیے بہترین ہیں۔ اس ڈائریکٹری میں `sample-document.txt` دیا گیا ہے جس میں LangChain4j فیچرز، RAG عمل درآمد، اور بہترین طریقے شامل ہیں — یہ نظام کی جانچ کے لیے مثالی ہے۔ +شروع کریں ایک دستاویز اپلوڈ کر کے — TXT فائلیں ٹیسٹ کے لیے بہترین کام کرتی ہیں۔ اس ڈائریکٹری میں `sample-document.txt` فراہم کی گئی ہے جس میں LangChain4j کی خصوصیات، RAG نفاذ، اور بہترین عمل کی معلومات شامل ہے — جو نظام کی جانچ کے لیے بہترین ہے۔ -سسٹم آپ کی دستاویز کو پراسیس کرتا ہے، اسے ٹکڑوں میں تقسیم کرتا ہے، اور ہر ٹکڑے کے لیے ایمبیڈنگز بناتا ہے۔ یہ عمل اپ لوڈ کے وقت خودکار ہوتا ہے۔ +نظام آپ کی دستاویز کو پروسیس کرتا ہے، اسے ٹکڑوں میں تقسیم کرتا ہے، اور ہر ٹکڑے کے لیے ایمبیڈنگز بناتا ہے۔ یہ خودکار طریقے سے اپلوڈ کرنے پر ہوتا ہے۔ ### سوالات پوچھیں -اب دستاویز کے مواد کے بارے میں مخصوص سوالات پوچھیں۔ ایسا کوئی حقیقت پر مبنی سوال آزمائیں جو دستاویز میں واضح طور پر بیان کیا گیا ہو۔ نظام متعلقہ ٹکڑوں کی تلاش کرتا ہے، انہیں پرامپٹ میں شامل کرتا ہے، اور جواب تیار کرتا ہے۔ +اب دستاویز کے مواد کے بارے میں مخصوص سوالات پوچھیں۔ ایسی معلومات کی کوشش کریں جو دستاویز میں واضح طور پر بیان کی گئی ہو۔ نظام متعلقہ ٹکڑوں کی تلاش کرتا ہے، انہیں پرامپٹ میں شامل کرتا ہے، اور جواب تیار کرتا ہے۔ ### ماخذ حوالہ جات چیک کریں -نوٹ کریں کہ ہر جواب میں ماخذ حوالہ جات شامل ہوتے ہیں جن کے ساتھ مماثلت اسکور ہوتے ہیں۔ یہ اسکور (0 سے 1 تک) دکھاتے ہیں کہ ہر ٹکڑا آپ کے سوال سے کتنا متعلق تھا۔ زیادہ اسکورز بہتر میل جول ظاہر کرتے ہیں۔ اس سے آپ جواب کو ماخذ مواد کے خلاف تصدیق کر سکتے ہیں۔ +نوٹ کریں کہ ہر جواب میں مماثلت کے اسکور کے ساتھ ماخذ حوالہ جات شامل ہوتے ہیں۔ یہ اسکور (0 سے 1 کے درمیان) دکھاتے ہیں کہ ہر ٹکڑا آپ کے سوال سے کتنا متعلقہ تھا۔ زیادہ اسکور کا مطلب بہتر ملاپ ہے۔ اس سے آپ جواب کی تصدیق ماخذ مواد کے ساتھ کر سکتے ہیں۔ RAG Query Results -*یہ اسکرین شاٹ پوچھے گئے سوالات کے نتائج دکھاتا ہے جن میں تیار کردہ جواب، ماخذ حوالہ جات، اور ہر بازیافت شدہ ٹکڑے کے رشتہ دار اسکور شامل ہیں۔* +*یہ اسکرین شاٹ سوالات کے نتائج دکھاتا ہے، جس میں تیار کردہ جواب، ماخذ حوالہ جات، اور ہر بازیافت شدہ ٹکڑے کے لیے متعلقہ اسکور شامل ہیں۔* ### سوالات کے ساتھ تجربہ کریں -مختلف قسم کے سوالات آزمائیں: -- مخصوص حقائق: "بنیادی موضوع کیا ہے؟" -- موازنہ: "X اور Y میں کیا فرق ہے؟" +مختلف قسم کے سوالات آزما کر دیکھیں: +- مخصوص حقائق: "اہم موضوع کیا ہے؟" +- تقابل: "X اور Y میں کیا فرق ہے؟" - خلاصے: "Z کے بارے میں کلیدی نکات کا خلاصہ کریں" -دیکھیں کہ کس طرح رشتہ دار اسکور مواد سے آپ کے سوال کی مناسبت پر بدلتے ہیں۔ +دیکھیں کہ آپ کے سوال کے مطابق متعلقہ اسکور کیسے بدلتے ہیں۔ -## اہم تصورات +## کلیدی تصورات -### ٹکڑے کرنے کی حکمت عملی +### ٹکڑوں کی حکمت عملی (Chunking Strategy) -دستاویزات کو 300-ٹوکین والے ٹکڑوں میں تقسیم کیا جاتا ہے جن میں 30 ٹوکین کا اوور لیپ ہوتا ہے۔ یہ توازن ہر ٹکڑے کو کافی سیاق و سباق فراہم کرتا ہے تاکہ وہ معنی خیز ہوں جبکہ پرامپٹ میں کئی ٹکڑے بآسانی شامل کیے جا سکیں۔ +دستاویزات کو 300 ٹوکن کے ٹکڑوں میں تقسیم کیا جاتا ہے جن میں 30 ٹوکن کا اوورلیپ ہوتا ہے۔ یہ توازن یقینی بناتا ہے کہ ہر ٹکڑا معنی خیز ہونے کے لیے کافی سیاق و سباق رکھتا ہے جبکہ پرامپٹ میں متعدد ٹکڑے شامل کرنے کے لیے چھوٹا بھی رہتا ہے۔ -### مماثلت اسکور +### مماثلت کے اسکور -ہر بازیافت شدہ ٹکڑے کے ساتھ ایک مماثلت اسکور (0 اور 1 کے درمیان) ہوتا ہے جو دکھاتا ہے کہ وہ یوزر کے سوال کے ساتھ کتنا میل کھاتا ہے۔ نیچے دیا گیا خاکہ اسکور کی حدوں کو ظاہر کرتا ہے اور نظام انہیں نتائج کو چھانٹنے کے لیے کیسے استعمال کرتا ہے: +ہر بازیافت شدہ ٹکڑے کے ساتھ ایک مماثلت کا اسکور ہوتا ہے جو 0 سے 1 کے درمیان ہوتا ہے اور ظاہر کرتا ہے کہ وہ صارف کے سوال سے کتنی قریبی مماثلت رکھتا ہے۔ ذیل میں دیا گیا خاکہ اسکور رینجز اور نظام کے ان کو فلٹر کرنے کے طریقے کو بصری بناتا ہے: Similarity Scores -*یہ خاکہ اسکور کی حدیں 0 سے 1 دکھاتا ہے، جس میں 0.5 کی کم از کم حد شامل ہے جو غیر متعلقہ ٹکڑوں کو فلٹر کرتی ہے۔* +*یہ خاکہ 0 سے 1 کے اسکور رینجز دکھاتا ہے، جس میں 0.5 کی کم از کم حد شامل ہے جو غیر متعلقہ ٹکڑوں کو فلٹر کرتی ہے۔* -اسکور کی حدیں: -- 0.7-1.0: انتہائی متعلقہ، بالکل میل کھاتا ہے +اسکورز کی حد 0 سے 1 تک ہے: +- 0.7-1.0: انتہائی متعلقہ، عین مطابق - 0.5-0.7: متعلقہ، اچھا سیاق و سباق -- 0.5 سے کم: فلٹر شدہ، بہت مختلف +- 0.5 سے کم: فلٹر شدہ، بہت غیر مماثل -نظام صرف کم از کم حد سے اوپر والے ٹکڑے بازیافت کرتا ہے تاکہ معیار یقینی بنایا جا سکے۔ +نظام صرف کم از کم حد سے اوپر کے ٹکڑے بازیافت کرتا ہے تاکہ معیار کو یقینی بنایا جا سکے۔ -ایمبیڈنگز ان صورتوں میں اچھی کارکردگی دکھاتے ہیں جہاں معنی کے کلسٹر واضح ہوں، لیکن ان کی کچھ کمزوریاں بھی ہیں۔ نیچے دیا گیا خاکہ عام ناکامی کے طریقے دکھاتا ہے — بہت بڑے ٹکڑے دھندلے ویکٹر پیدا کرتے ہیں، بہت چھوٹے ٹکڑوں میں سیاق و سباق نہیں ہوتا، مبہم اصطلاحات متعدد کلسٹروں کی طرف اشارہ کرتی ہیں، اور بالکل مماثل تلاشیں (آئی ڈیز، پارٹ نمبرز) ایمبیڈنگز کے ساتھ کام نہیں کرتیں: +ایمبیڈنگز اس وقت اچھی کارکردگی دکھاتے ہیں جب معنی صاف طور پر کلسٹر ہوتے ہیں، لیکن ان میں خامیاں بھی ہوتی ہیں۔ ذیل میں دیا گیا خاکہ عام ناکامی کے حالات دکھاتا ہے — بہت بڑے ٹکڑے مدھم ویکٹر بناتے ہیں، بہت چھوٹے ٹکڑے سیاق و سباق کی کمی رکھتے ہیں، مبہم اصطلاحات متعدد کلسٹر کی طرف اشارہ کرتی ہیں، اور عین مطابق تلاش (IDs، پارٹ نمبر) ایمبیڈنگز کے ساتھ بالکل کام نہیں کرتی: Embedding Failure Modes -*یہ خاکہ عام ایمبیڈنگ ناکامی کے طریقے دکھاتا ہے: بہت بڑے ٹکڑے، بہت چھوٹے ٹکڑے، مبہم اصطلاحات جو متعدد کلسٹروں کی طرف اشارہ کرتی ہیں، اور آئی ڈیز جیسے بالکل مماثل تلاشیں۔* +*یہ خاکہ عام ایمبیڈنگ ناکامیوں کے حالات دکھاتا ہے: بہت بڑے ٹکڑے، بہت چھوٹے ٹکڑے، مبہم اصطلاحات جو متعدد کلسٹر کی طرف اشارہ کرتی ہیں، اور عین مطابق تلاش جیسے IDs۔* -### ان میموری اسٹوریج +### میموری میں ذخیرہ -یہ ماڈیول سادگی کے لیے ان میموری اسٹوریج استعمال کرتا ہے۔ جب آپ ایپلیکیشن کو دوبارہ شروع کرتے ہیں تو اپ لوڈ کی گئی دستاویزات ختم ہو جاتی ہیں۔ پیداوار کے نظام مستقل ویکٹر ڈیٹا بیسز جیسے Qdrant یا Azure AI سرچ استعمال کرتے ہیں۔ +یہ ماڈیول سادگی کے لیے میموری میں ذخیرہ استعمال کرتا ہے۔ جب آپ ایپلیکیشن کو دوبارہ شروع کرتے ہیں تو اپلوڈ شدہ دستاویزات ضائع ہو جاتی ہیں۔ پروڈکشن سسٹمز مستقل ویکٹر ڈیٹا بیس جیسے Qdrant یا Azure AI Search استعمال کرتے ہیں۔ -### سیاق و سباق کی ونڈو کا انتظام +### سیاق و سباق ونڈو مینجمنٹ -ہر ماڈل کی زیادہ سے زیادہ سیاق و سباق کی ونڈو ہوتی ہے۔ آپ بڑی دستاویز کے تمام ٹکڑے شامل نہیں کر سکتے۔ نظام سب سے زیادہ متعلقہ اوپر N ٹکڑے (ڈیفالٹ 5) بازیافت کرتا ہے تاکہ حدود کے اندر رہتے ہوئے درست جواب کے لیے کافی سیاق و سباق فراہم کیا جا سکے۔ +ہر ماڈل کی ایک زیادہ سے زیادہ سیاق و سباق کی ونڈو ہوتی ہے۔ آپ بڑے دستاویز سے ہر ٹکڑا شامل نہیں کر سکتے۔ نظام حدوں کے اندر رہتے ہوئے درست جواب فراہم کرنے کے لیے سب سے زیادہ متعلقہ N ٹکڑے (ڈیفالٹ 5) بازیافت کرتا ہے۔ -## جب RAG کی ضرورت ہوتی ہے +## جب RAG اہم ہوتا ہے -RAG ہمیشہ درست طریقہ نہیں ہوتا۔ نیچے دیا گیا فیصلہ گائیڈ مدد دیتا ہے کہ کب RAG مفید ہے اور کب سادہ طریقے — جیسے براہ راست پرامپٹ میں مواد شامل کرنا یا ماڈل کے اندر موجود معلومات پر انحصار کرنا — کافی ہیں: +RAG ہمیشہ صحیح طریقہ نہیں ہوتا۔ ذیل میں فیصلہ سازی کا گائیڈ ہے جو آپ کو مدد دیتا ہے کہ کب RAG مفید ہوتا ہے اور کب آسان طریقے — جیسے مواد کو براہ راست پرامپٹ میں شامل کرنا یا ماڈل کی بلٹ ان معلومات پر انحصار کرنا — کافی ہوتے ہیں: When to Use RAG -*یہ خاکہ فیصلہ گائیڈ دکھاتا ہے کہ کب RAG فائدہ دیتا ہے اور کب سادہ طریقے کافی ہیں۔* +*یہ خاکہ ایک فیصلہ سازی کا گائیڈ ہے کہ کب RAG مفید ہوتا ہے اور کب آسان طریقے کافی ہوتے ہیں۔* -## اگلے اقدامات +## اگلے مراحل **اگلا ماڈیول:** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**راستہ:** [← پچھلا: ماڈیول 02 - پرامپٹ انجینئرنگ](../02-prompt-engineering/README.md) | [مین پر واپس](../README.md) | [اگلا: ماڈیول 04 - ٹولز →](../04-tools/README.md) +**نیویگیشن:** [← پچھلا: ماڈیول 02 - پرامپٹ انجینئرنگ](../02-prompt-engineering/README.md) | [مرکزی صفحہ پر واپس](../README.md) | [اگلا: ماڈیول 04 - ٹولز →](../04-tools/README.md) --- -**دستخطی دستبرداری**: -یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ اگرچہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم یہ بات مدنظر رکھیں کہ خودکار تراجم میں غلطیاں یا بے ضابطگیاں ہو سکتی ہیں۔ اصل دستاویز اپنی مادری زبان میں ہی معتبر ماخذ سمجھی جائے گی۔ اہم معلومات کے لیے پیشہ ور انسانی ترجمے کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے ہونے والی کسی بھی غلط فہمی یا بدفہمی کی ذمہ داری ہم پر عائد نہیں ہوگی۔ +**ڈس کلیمر**: +یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔ \ No newline at end of file diff --git a/translations/ur/04-tools/README.md b/translations/ur/04-tools/README.md index 03d343b28..4083a8d98 100644 --- a/translations/ur/04-tools/README.md +++ b/translations/ur/04-tools/README.md @@ -2,75 +2,75 @@ ## فہرست مضامین -- [ویڈیو واک تھرو](../../../04-tools) -- [آپ کیا سیکھیں گے](../../../04-tools) -- [ضروریات](../../../04-tools) -- [ٹولز کے ساتھ AI ایجنٹس کو سمجھنا](../../../04-tools) -- [ٹول کالنگ کیسے کام کرتی ہے](../../../04-tools) - - [ٹول کی وضاحتیں](../../../04-tools) - - [فیصلہ سازی](../../../04-tools) - - [عمل درآمد](../../../04-tools) - - [ردعمل تخلیق](../../../04-tools) - - [آرکیٹیکچر: اسپرنگ بوٹ آٹو وائرنگ](../../../04-tools) -- [ٹول چیننگ](../../../04-tools) -- [ایپلیکیشن چلائیں](../../../04-tools) -- [ایپلیکیشن استعمال کرنا](../../../04-tools) - - [سادہ ٹول کا استعمال آزمائیں](../../../04-tools) - - [ٹول چیننگ کی جانچ کریں](../../../04-tools) - - [گفتگو کے بہاؤ کو دیکھیں](../../../04-tools) - - [مختلف درخواستوں کے ساتھ تجربہ کریں](../../../04-tools) -- [اہم تصورات](../../../04-tools) - - [ری ایکٹ پیٹرن (منطق اور عمل)](../../../04-tools) - - [ٹول کی وضاحتیں اہمیت رکھتی ہیں](../../../04-tools) - - [سیشن مینجمنٹ](../../../04-tools) - - [خرابیوں کا انتظام](../../../04-tools) -- [دستیاب ٹولز](../../../04-tools) -- [ٹول بیسڈ ایجنٹس کب استعمال کریں](../../../04-tools) -- [ٹولز بمقابلہ RAG](../../../04-tools) -- [اگلے اقدامات](../../../04-tools) +- [ویڈیو واک تھرو](#ویڈیو-واک-تھرو) +- [آپ کیا سیکھیں گے](#آپ-کیا-سیکھیں-گے) +- [شرائط](#شرائط) +- [ٹولز کے ساتھ AI ایجنٹس کو سمجھنا](#ٹولز-کے-ساتھ-ai-ایجنٹس-کو-سمجھنا) +- [ٹول کالنگ کیسے کام کرتی ہے](#ٹول-کالنگ-کیسے-کام-کرتی-ہے) + - [ٹول کی وضاحتیں](#ٹول-کی-وضاحتیں) + - [فیصلہ سازی](#فیصلہ-سازی) + - [عملدرآمد](#عملدرآمد) + - [جواب کی تیاری](#جواب-کی-تیاری) + - [آرکیٹیکچر: Spring Boot آٹو وائرنگ](#آرکیٹیکچر-spring-boot-آٹو-وائرنگ) +- [ٹول چیننگ](#ٹول-چیننگ) +- [ایپلیکیشن چلائیں](#ایپلیکیشن-چلائیں) +- [ایپلیکیشن کا استعمال](#ایپلیکیشن-کا-استعمال) + - [سادہ ٹول استعمال کرنے کی کوشش کریں](#آسان-آلات-کے-استعمال-کی-کوشش-کریں) + - [ٹول چیننگ کا معائنہ کریں](#آلے-کے-سلسلے-کی-جانچ-کریں) + - [گفتگو کے بہاؤ کو دیکھیں](#گفتگو-کے-بہاؤ-کو-دیکھیں) + - [مختلف درخواستوں کے ساتھ تجربہ کریں](#مختلف-درخواستوں-کے-ساتھ-تجربہ-کریں) +- [کلیدی تصورات](#اہم-تصورات) + - [ReAct پیٹرن (وجہ اور عمل)](#react-پیٹرن-استدلال-اور-عمل) + - [ٹول کی وضاحتیں اہم ہیں](#آلے-کی-وضاحتیں-اہم-ہیں) + - [سیشن مینجمنٹ](#سیشن-مینجمنٹ) + - [خرابیوں سے نمٹنا](#ایرر-ہینڈلنگ) +- [دستیاب ٹولز](#دستیاب-آلات) +- [ٹول بیسڈ ایجنٹس کب استعمال کریں](#آلہ-پر-مبنی-ایجنٹس-کا-استعمال-کب-کریں) +- [ٹولز بمقابلہ RAG](#آلات-بمقابلہ-rag) +- [اگلے اقدامات](#اگلے-اقدامات) ## ویڈیو واک تھرو اس لائیو سیشن کو دیکھیں جو اس ماڈیول کے ساتھ شروع کرنے کا طریقہ بتاتا ہے: -ٹولز کے ساتھ AI ایجنٹس اور MCP - لائیو سیشن +AI Agents with Tools and MCP - Live Session ## آپ کیا سیکھیں گے -اب تک، آپ نے سیکھا ہے کہ AI کے ساتھ گفتگو کیسے کی جائے، مؤثر پرامپٹس کیسے بنائیں، اور جوابات کو اپنے دستاویزات میں کیسے مرتب کریں۔ لیکن ایک بنیادی محدودیت ابھی بھی موجود ہے: زبان کے ماڈل صرف متن پیدا کر سکتے ہیں۔ وہ موسم کا حال چیک نہیں کر سکتے، حسابات نہیں کر سکتے، ڈیٹا بیس سے سوالات نہیں کر سکتے، یا بیرونی نظاموں سے تعامل نہیں کر سکتے۔ +اب تک، آپ نے AI کے ساتھ بات چیت کرنا، مؤثر پرامٹس کی ساخت بنانا، اور جوابات کو اپنے دستاویزات میں زمین پر قائم کرنا سیکھا ہے۔ لیکن ایک بنیادی حد ابھی باقی ہے: زبان کے ماڈلز صرف متن تیار کر سکتے ہیں۔ وہ موسم کا حال معلوم نہیں کر سکتے، حساب کتاب نہیں کر سکتے، ڈیٹا بیس کو کوئری نہیں کر سکتے، یا بیرونی نظاموں کے ساتھ تعامل نہیں کر سکتے۔ -ٹولز اسے بدل دیتے ہیں۔ جب ماڈل کو ایسے فنکشنز تک رسائی دی جاتی ہے جنہیں وہ کال کر سکتا ہے، تو آپ اسے ایک ٹیکسٹ جنریٹر سے ایک ایجنٹ میں بدل دیتے ہیں جو کارروائی کر سکتا ہے۔ ماڈل فیصلہ کرتا ہے کہ اسے کب ٹول کی ضرورت ہے، کون سا ٹول استعمال کرنا ہے، اور کون سے پیرامیٹرز پاس کرنے ہیں۔ آپ کا کوڈ فنکشن کو چلائے گا اور نتیجہ واپس کرے گا۔ ماڈل اس نتیجے کو اپنے جواب میں شامل کر لیتا ہے۔ +ٹولز اس کو بدل دیتے ہیں۔ فنکشنز تک ماڈل کی رسائی دے کر جو وہ کال کر سکتا ہے، آپ اسے صرف متن بنانے سے ایک ایجنٹ میں تبدیل کر دیتے ہیں جو کاروائیاں کر سکتا ہے۔ ماڈل فیصلہ کرتا ہے کہ اسے کب اور کون سا ٹول چاہیے، اور کیا پیرامیٹرز بھیجنے ہیں۔ آپ کے کوڈ فنکشن کو چلاتے ہیں اور نتیجہ واپس کرتے ہیں۔ ماڈل اس نتیجے کو اپنی جواب میں شامل کرتا ہے۔ -## ضروریات +## شرائط -- مکمل شدہ [ماڈیول 01 - تعارف](../01-introduction/README.md) (Azure OpenAI وسائل تعینات کیے گئے) -- پچھلے ماڈیولز کی سفارش کی گئی ہے (یہ ماڈیول ریفرنس کرتا ہے [RAG تصورات ماڈیول 03 سے](../03-rag/README.md) ٹولز بمقابلہ RAG موازنہ میں) -- `.env` فائل روٹ ڈائریکٹری میں Azure کی اسناد کے ساتھ (جو `azd up` نے ماڈیول 01 میں بنائی) +- مکمل شدہ [ماڈیول 01 - تعارف](../01-introduction/README.md) (Azure OpenAI وسائل تعینات کیے ہوئے) +- پچھلے ماڈیولز کی سفارش کی گئی ہے (یہ ماڈیول ٹولز بمقابلہ RAG موازنہ میں [ماڈیول 03 سے RAG تصورات](../03-rag/README.md) کی حوالہ دیتا ہے) +- `.env` فائل روٹ ڈائریکٹری میں Azure اسناد کے ساتھ (ماڈیول 01 میں `azd up` سے بنائی گئی) -> **نوٹ:** اگر آپ نے ماڈیول 01 مکمل نہیں کیا تو پہلے وہاں دی گئی تعیناتی کی ہدایات پر عمل کریں۔ +> **نوٹ:** اگر آپ نے ماڈیول 01 مکمل نہیں کیا تو پہلے وہاں دی گئی تعیناتی ہدایات پر عمل کریں۔ ## ٹولز کے ساتھ AI ایجنٹس کو سمجھنا -> **📝 نوٹ:** اس ماڈیول میں "ایجنٹس" کا مطلب AI معاونین ہیں جو ٹول کالنگ کی خصوصیات کے ساتھ بہتر بنائے گئے ہیں۔ یہ **Agentic AI** پیٹرنز (آزاد ایجنٹس جن میں منصوبہ بندی، یادداشت، اور کثیر مرحلہ منطق ہوتی ہے) سے مختلف ہے، جن کا احاطہ ہم [ماڈیول 05: MCP](../05-mcp/README.md) میں کریں گے۔ +> **📝 نوٹ:** اس ماڈیول میں "ایجنٹس" سے مراد AI اسسٹنٹس ہیں جو ٹول کالنگ صلاحیتوں سے لیس ہیں۔ یہ اس سے مختلف ہے جو ہم [ماڈیول 05: MCP](../05-mcp/README.md) میں کور کریں گے، یعنی **Agentic AI** پیٹرنز (خود مختار ایجنٹس جن میں منصوبہ بندی، میموری، اور کثیر قدمی استدلال ہوتا ہے)۔ -ٹولز کے بغیر، زبان کا ماڈل صرف اپنے تربیتی ڈیٹا سے متن پیدا کر سکتا ہے۔ اگر آپ موسم کا حال پوچھیں، تو اسے اندازہ لگانا پڑتا ہے۔ ٹولز دیں، اور یہ موسم کی API کال کر سکتا ہے، حسابات کر سکتا ہے، یا ڈیٹا بیس سے سوالات کر سکتا ہے — پھر ان حقیقی نتائج کو اپنے جواب میں بُنتا ہے۔ +بغیر ٹولز کے، زبان کا ماڈل صرف اپنے تربیتی ڈیٹا سے متن پیدا کر سکتا ہے۔ اس سے موجودہ موسم پوچھیں، تو اسے اندازہ لگانا پڑتا ہے۔ اگر اسے ٹولز دیے جائیں تو یہ موسم کا API کال کر سکتا ہے، حساب کر سکتا ہے، یا ڈیٹا بیس کو کوئری کر سکتا ہے — پھر ان حقیقی نتائج کو اپنے جواب میں شامل کر سکتا ہے۔ -بغیر ٹولز کے بمقابلہ ٹولز کے ساتھ +Without Tools vs With Tools -*بغیر ٹولز کے ماڈل صرف اندازہ لگا سکتا ہے — ٹولز کے ساتھ یہ APIs کال کر سکتا ہے، حسابات چلا سکتا ہے، اور حقیقی وقت کا ڈیٹا واپس کر سکتا ہے۔* +*ٹولز کے بغیر ماڈل صرف اندازہ لگا سکتا ہے — ٹولز کے ساتھ یہ API کال کر سکتا ہے، حساب چلا سکتا ہے، اور حقیقی وقت کا ڈیٹا واپس کر سکتا ہے۔* -ٹولز کے ساتھ AI ایجنٹ ایک **ریزننگ اور ایکٹنگ (ReAct)** پیٹرن پر عمل کرتا ہے۔ ماڈل صرف جواب نہیں دیتا — یہ سوچتا ہے کہ اسے کیا چاہیے، ایک ٹول کال کر کے عمل کرتا ہے، نتیجہ دیکھتا ہے، اور پھر فیصلہ کرتا ہے کہ دوبارہ عمل کرے یا حتمی جواب دے: +ٹولز والا AI ایجنٹ **Reasoning and Acting (ReAct)** پیٹرن کی پیروی کرتا ہے۔ ماڈل صرف جواب نہیں دیتا — یہ سوچتا ہے کہ اسے کیا چاہیے، ایک ٹول کال کر کے عمل کرتا ہے، نتیجہ دیکھتا ہے، اور پھر فیصلہ کرتا ہے کہ دوبارہ عمل کرنا ہے یا حتمی جواب دینا ہے: -1. **سمجھنا** — ایجنٹ صارف کے سوال کا تجزیہ کرتا ہے اور معلوم کرتا ہے کہ اسے کس معلومات کی ضرورت ہے -2. **عمل کرنا** — ایجنٹ درست ٹول کا انتخاب کرتا ہے، صحیح پیرامیٹرز تیار کرتا ہے، اور اسے کال کرتا ہے -3. **مشاہدہ کرنا** — ایجنٹ ٹول کے آؤٹ پٹ کو وصول کرتا ہے اور نتیجہ کا جائزہ لیتا ہے -4. **دہرائیں یا جواب دیں** — اگر مزید ڈیٹا درکار ہو تو ایجنٹ لوپ میں جاتا ہے؛ ورنہ قدرتی زبان میں جواب ترتیب دیتا ہے +1. **وجہ بنائیں** — ایجنٹ صارف کے سوال کا تجزیہ کرتا ہے اور طے کرتا ہے کہ اسے کس معلومات کی ضرورت ہے +2. **عمل کریں** — ایجنٹ مناسب ٹول کا انتخاب کرتا ہے، درست پیرامیٹرز تیار کرتا ہے، اور اسے کال کرتا ہے +3. **مشاہدہ کریں** — ایجنٹ ٹول کا آؤٹ پٹ وصول کرتا ہے اور نتیجہ کا جائزہ لیتا ہے +4. **دہرائیں یا جواب دیں** — اگر مزید ڈیٹا چاہیے، تو ایجنٹ واپس لوپ میں آتا ہے؛ ورنہ، قدرتی زبان میں جواب بناتا ہے -ری ایکٹ پیٹرن +ReAct Pattern -*ری ایکٹ سائیکل — ایجنٹ سوچتا ہے کہ کیا کرنا ہے، ٹول کال کر کے عمل کرتا ہے، نتیجہ مشاہدہ کرتا ہے، اور جب تک حتمی جواب فراہم نہ کرے لوپ کرتا ہے۔* +*ReAct سائیکل — ایجنٹ سوچتا ہے کہ کیا کرنا ہے، ٹول کال کر کے عمل کرتا ہے، نتیجہ دیکھتا ہے، اور جب تک حتمی جواب دے سکتا ہے لوپ میں رہتا ہے۔* -یہ چیز خودکار طور پر ہوتی ہے۔ آپ ٹولز اور ان کی وضاحتیں ڈیفائن کرتے ہیں۔ ماڈل فیصلہ سازی کرتا ہے کہ کب اور کیسے انہیں استعمال کرنا ہے۔ +یہ خود بخود ہوتا ہے۔ آپ ٹولز اور ان کی وضاحتیں define کرتے ہیں۔ ماڈل فیصلہ سازی سنبھالتا ہے کہ کب اور کیسے انہیں استعمال کرنا ہے۔ ## ٹول کالنگ کیسے کام کرتی ہے @@ -78,7 +78,7 @@ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -آپ فنکشنز واضح وضاحتوں اور پیرامیٹر کی تفصیلات کے ساتھ ڈیفائن کرتے ہیں۔ ماڈل یہ وضاحتیں اپنے سسٹم پرامپٹ میں دیکھتا ہے اور سمجھتا ہے کہ ہر ٹول کیا کرتا ہے۔ +آپ فنکشنز کو واضح وضاحتوں اور پیرامیٹر کی تفصیلات کے ساتھ define کرتے ہیں۔ ماڈل ان وضاحتوں کو اپنے سسٹم پرامپٹ میں دیکھتا ہے اور سمجھتا ہے کہ ہر ٹول کیا کرتا ہے۔ ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // آپ کا موسم تلاش کرنے کا منطق + // آپ کا موسم دریافت کرنے کا منطق return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,177 +96,177 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// اسسٹنٹ Spring Boot کے ذریعے خودکار طریقے سے منسلک ہے: +// اسسٹنٹ خود بخود Spring Boot کے ذریعہ منسلک ہے: // - ChatModel bean -// - @Component کلاسوں سے تمام @Tool طریقے +// - @Component کلاسز کے تمام @Tool طریقے // - سیشن مینجمنٹ کے لیے ChatMemoryProvider ``` -ذیل میں دیا گیا خاکہ ہر اینوٹیشن کو توڑ کر دکھاتا ہے اور یہ کہ ہر حصہ AI کو کب ٹول کال کرنا ہے اور کن ارگومنٹس کو پاس کرنا ہے سمجھانے میں کیسے مدد کرتا ہے: +نیچے دیا گیا خاکہ ہر تشریح کو توڑ کر دکھاتا ہے اور کہتا ہے کہ ہر حصہ AI کو کیسے مدد دیتا ہے یہ سمجھنے میں کہ ٹول کب کال کرنا ہے اور کون سے آرگیومینٹس پاس کرنے ہیں: -ٹول کی وضاحتوں کی ساخت +Anatomy of Tool Definitions -*ٹول کی وضاحت کی ساخت — @Tool AI کو بتاتا ہے کب اسے استعمال کرنا ہے، @P ہر پیرامیٹر کی وضاحت کرتا ہے، اور @AiService سب کچھ اسٹارٹ اپ پر وائر کرتا ہے۔* +*ٹول کی تعریف کا ڈھانچہ — @Tool AI کو بتاتا ہے کہ اسے کب استعمال کرنا ہے، @P ہر پیرامیٹر کو بیان کرتا ہے، اور @AiService سب کچھ اسٹارٹ اپ پر وائر کرتا ہے۔* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمائیں:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) کھولیں اور پوچھیں: -> - "کیا میں حقیقی موسم API جیسے OpenWeatherMap کو جعلی ڈیٹا کی جگہ کیسے انٹیگریٹ کروں گا؟" -> - "ایک اچھی ٹول وضاحت کیا ہوتی ہے جو AI کو اسے صحیح طریقے سے استعمال کرنے میں مدد دے؟" -> - "ٹول کی عمل درآمد میں API کی خامیوں اور ریٹ لیمٹس کو کیسے سنبھالیں؟" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمانا:** [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) کھولیں اور پوچھیں: +> - "اصلی موسم کا API جیسے OpenWeatherMap کو نقلی ڈیٹا کی جگہ کیسے انٹیگریٹ کروں؟" +> - "ایک اچھی ٹول وضاحت کیا ہوتی ہے جو AI کو اسے صحیح استعمال کرنے میں مدد دے؟" +> - "API غلطیوں اور ریٹ لمٹس کو ٹول امپلیمینٹیشنز میں کیسے سنبھالیں؟" ### فیصلہ سازی -جب صارف پوچھتا ہے "سیئیٹل میں موسم کیسا ہے؟"، تو ماڈل تصادفی طور پر کوئی ٹول منتخب نہیں کرتا۔ یہ صارف کے ارادے کو ہر دستیاب ٹول کی وضاحت سے موازنہ کرتا ہے، ہر ایک کو مطابقت کے لیے اسکور کرتا ہے، اور بہترین میچ منتخب کرتا ہے۔ پھر یہ صحیح پیرامیٹرز کے ساتھ ایک ساختہ فنکشن کال جنریٹ کرتا ہے — اس معاملے میں `location` کو `"Seattle"` پر سیٹ کرتے ہوئے۔ +جب صارف پوچھتا ہے "سیئٹل میں موسم کیسا ہے؟"، ماڈل بے ترتیب ٹول منتخب نہیں کرتا۔ یہ صارف کی نیت کو ہر ٹول کی وضاحت سے موازنہ کرتا ہے، ہر ایک کی مطابقت کے حساب سے اسکور کرتا ہے، اور بہترین میچ منتخب کرتا ہے۔ پھر ایک ساختہ فنکشن کال جنریٹ کرتا ہے جس میں درست پیرامیٹرز ہوتے ہیں — اس معاملے میں `location` کو `"Seattle"` سیٹ کرنا۔ -اگر صارف کی درخواست کے لیے کوئی ٹول میچ نہ ہو، تو ماڈل اپنے علم سے جواب دیتا ہے۔ اگر متعدد ٹولز میچ کریں، تو یہ سب سے مخصوص کو چنتا ہے۔ +اگر صارف کی درخواست سے کوئی ٹول میل نہیں کھاتا، تو ماڈل اپنی معلومات سے جواب دیتا ہے۔ اگر متعدد ٹولز میل کھاتے ہیں، تو وہ سب سے مخصوص کو منتخب کرتا ہے۔ -AI اس بات کا فیصلہ کیسے کرتا ہے کہ کون سا ٹول استعمال کرے +How the AI Decides Which Tool to Use -*ماڈل ہر دستیاب ٹول کو صارف کے ارادے کے مقابلے میں جانچتا ہے اور بہترین میچ منتخب کرتا ہے — اسی لیے واضح اور مخصوص ٹول کی وضاحت لکھنا اہم ہے۔* +*ماڈل ہر دستیاب ٹول کو صارف کے ارادے کے خلاف پرکھتا ہے اور بہترین میچ منتخب کرتا ہے — اسی لیے واضح اور مخصوص ٹول وضاحتیں لکھنا اہم ہے۔* -### عمل درآمد +### عملدرآمد [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -اسپرنگ بوٹ ڈیکلیرایٹو `@AiService` انٹرفیس کو تمام رجسٹرڈ ٹولز کے ساتھ خودکار طور پر وائر کرتا ہے، اور LangChain4j خودکار طور پر ٹول کالز کو انجام دیتا ہے۔ پردے کے پیچھے، مکمل ٹول کال چھ مراحل سے گزرتی ہے — صارف کے قدرتی زبان کے سوال سے لے کر قدرتی زبان کے جواب تک: +Spring Boot `@AiService` انٹرفیس کو تمام رجسٹرڈ ٹولز کے ساتھ آٹو وائر کرتا ہے، اور LangChain4j ٹول کالز کو خود بخود انجام دیتا ہے۔ پردے کے پیچھے، مکمل ٹول کال چھ مراحل سے گزرتا ہے — صارف کے قدرتی زبان کے سوال سے لے کر قدرتی زبان کے جواب تک: -ٹول کالنگ کا بہاؤ +Tool Calling Flow -*انتہائی بہاؤ — صارف سوال پوچھتا ہے، ماڈل ٹول منتخب کرتا ہے، LangChain4j اسے چلاتا ہے، اور ماڈل نتیجہ قدرتی جواب میں شامل کرتا ہے۔* +*آخر سے آخر تک بہاؤ — صارف سوال کرتا ہے، ماڈل ایک ٹول منتخب کرتا ہے، LangChain4j اسے چلاتا ہے، اور ماڈل نتیجہ کو قدرتی جواب میں شامل کرتا ہے۔* -اگر آپ نے [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) ماڈیول 00 میں چلایا ہے، تو آپ نے یہ پیٹرن پہلے ہی دیکھا ہے — `Calculator` ٹولز بالکل اسی طرح کال ہوتے تھے۔ نیچے دیا گیا سیکوئنس ڈایاگرام اس ڈیمو کے دوران جو کچھ ہوا بالکل دکھاتا ہے: +پردے کے پیچھے، `AiServices` کسی بھی ٹول کے لیے وہی ٹول کالنگ لوپ چلتا ہے — یہاں ایک سادہ `Calculator` کے ساتھ دکھایا گیا ہے۔ نیچے دیا گیا سیQUENCE ڈایاگرام دکھاتا ہے کہ اندر کیا ہوتا ہے: -ٹول کالنگ سیکوئنس ڈایاگرام +Tool Calling Sequence Diagram -*کوئیک اسٹارٹ ڈیمو سے ٹول کالنگ لوپ — `AiServices` آپ کا پیغام اور ٹول سکیمز LLM کو بھیجتا ہے، LLM ایک فنکشن کال جیسے `add(42, 58)` جواب دیتا ہے، LangChain4j `Calculator` میتھڈ لوکل چلائے گا، اور نتیجہ واپس حتمی جواب کے لیے دیتا ہے۔* +*ٹول کالنگ لوپ — `AiServices` آپ کا پیغام اور ٹول اسکیمہ LLM کو بھیجتا ہے، LLM فنکشن کال جیسے `add(42, 58)` کے ساتھ جواب دیتا ہے، LangChain4j لوکل `Calculator` طریقہ چلاتا ہے، اور نتیجہ واپس حتمی جواب کے لیے دیتا ہے۔* -> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمائیں:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) کھولیں اور پوچھیں: -> - "ری ایکٹ پیٹرن کیسے کام کرتا ہے اور یہ AI ایجنٹس کے لیے کیوں مؤثر ہے؟" -> - "ایجنٹ فیصلہ کیسے کرتا ہے کہ کون سا ٹول استعمال کرنا ہے اور کس ترتیب میں؟" -> - "اگر ٹول کا عمل درآمد ناکام ہو جائے تو کیا ہوتا ہے — میں غلطیوں کو کیسے بہتر طریقے سے ہینڈل کروں؟" +> **🤖 [GitHub Copilot](https://github.com/features/copilot) چیٹ کے ساتھ آزمانا:** [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) کھولیں اور پوچھیں: +> - "ReAct پیٹرن کیسے کام کرتا ہے اور AI ایجنٹس کے لیے یہ موثر کیوں ہے؟" +> - "ایجنٹ کیسے فیصلہ کرتا ہے کہ کون سا ٹول استعمال کرنا ہے اور کس ترتیب میں؟" +> - "اگر ٹول کا عملدرآمد ناکام ہو جاتا ہے تو کیا ہوتا ہے — میں ایررز کو مستحکم طور پر کیسے ہینڈل کروں؟" -### ردعمل تخلیق +### جواب کی تیاری -ماڈل موسم کا ڈیٹا وصول کرتا ہے اور اسے صارف کے لیے قدرتی زبان میں جواب میں تبدیل کرتا ہے۔ +ماڈل موسم کا ڈیٹا وصول کرتا ہے اور اسے صارف کے لیے قدرتی زبان میں جواب کی شکل دیتا ہے۔ -### آرکیٹیکچر: اسپرنگ بوٹ آٹو وائرنگ +### آرکیٹیکچر: Spring Boot آٹو وائرنگ -یہ ماڈیول LangChain4j کی اسپرنگ بوٹ انٹیگریشن استعمال کرتا ہے، جو ڈیکلیرایٹو `@AiService` انٹرفیس کے ساتھ ہے۔ اسٹارٹ اپ پر، اسپرنگ بوٹ ہر وہ `@Component` تلاش کرتا ہے جس میں `@Tool` میتھڈز ہوں، آپ کا `ChatModel` بین، اور `ChatMemoryProvider` — پھر ان سب کو ایک `Assistant` انٹرفیس میں بغیر کسی بقاوت کے جوڑ دیتا ہے۔ +یہ ماڈیول LangChain4j کی Spring Boot انٹیگریشن استعمال کرتا ہے جس میں اعلان کردہ `@AiService` انٹرفیس ہوتے ہیں۔ اسٹارٹ اپ پر Spring Boot ہر `@Component` کو دریافت کرتا ہے جس میں `@Tool` طریقے ہوتے ہیں، آپ کے `ChatModel` بین، اور `ChatMemoryProvider` — پھر انہیں ایک واحد `Assistant` انٹرفیس میں بغیر کسی اضافی کوڈ کے جوڑ دیتا ہے۔ -اسپرنگ بوٹ آٹو وائرنگ آرکیٹیکچر +Spring Boot Auto-Wiring Architecture -*@AiService انٹرفیس ChatModel، ٹول کمپونینٹس، اور میموری پرووائیڈر کو آپس میں جوڑتا ہے — اسپرنگ بوٹ تمام وائرنگ خود بخود سنبھالتا ہے۔* +*@AiService انٹرفیس ChatModel، ٹول کمپونینٹس، اور میموری پرووائیڈر کو آپس میں جوڑتا ہے — Spring Boot یہ تمام وائرنگ خودکار طریقے سے کرتا ہے۔* -یہاں مکمل درخواست کے لائف سائیکل کا سیکوئنس ڈایاگرام ہے — HTTP درخواست سے لے کر کنٹرولر، سروس، آٹو وائرڈ پراکسی، اور پھر ٹول کے عمل درآمد اور واپس: +یہاں پورے درخواست کے لائف سائیکل کا سی퀞نس ڈایاگرام ہے — HTTP درخواست سے لے کر کنٹرولر، سروس، اور آٹو وائرڈ پراکسی کے ذریعے، اور واپس ٹول کے عملدرآمد تک: -اسپرنگ بوٹ ٹول کالنگ سیکوئنس +Spring Boot Tool Calling Sequence -*مکمل اسپرنگ بوٹ درخواست کا لائف سائیکل — HTTP درخواست کنٹرولر اور سروس سے گزر کر آٹو وائرڈ Assistant پراکسی تک پہنچتی ہے، جو LLM اور ٹول کالز کو خودکار طور پر منظم کرتا ہے۔* +*مکمل Spring Boot درخواست کا لائف سائیکل — HTTP درخواست کنٹرولر اور سروس سے آٹو وائرڈ Assistant پراکسی تک جاتی ہے، جو خودکار طریقے سے LLM اور ٹول کالز کو آراستہ کرتا ہے۔* -اس طریقہ کار کے اہم فوائد: +اس طریقے کے کلیدی فوائد: -- **اسپرنگ بوٹ آٹو وائرنگ** — ChatModel اور ٹولز خودکار طور پر داخل کردہ -- **@MemoryId پیٹرن** — خودکار سیشن بیسڈ میموری مینجمنٹ -- **سنگل انسٹینس** — Assistant صرف ایک بار بنائی جاتی ہے اور بہتر کارکردگی کے لیے دوبارہ استعمال -- **ٹائپ سیف ایکزیکیوشن** — جاوا میتھڈز براہ راست ٹائپ کنورژن کے ساتھ کال کیے جاتے ہیں -- **کثیر مرحلہ آراستگی** — خودکار طریقے سے ٹول چیننگ کو ہینڈل کرتا ہے -- **زیرو بویلر پلیٹ** — کوئی دستی `AiServices.builder()` کالز یا میموری ہیش میپ کی ضرورت نہیں +- **Spring Boot آٹو وائرنگ** — ChatModel اور ٹولز خودکار طریقے سے داخل کیے جاتے ہیں +- **@MemoryId پیٹرن** — سیشن پر مبنی میموری مینجمنٹ خودکار +- **واحد انسٹانس** — Assistant ایک بار بنایا جاتا ہے اور کارکردگی کے لیے دوبارہ استعمال ہوتا ہے +- **ٹائپ-سیف عملدرآمد** — جاوا طریقے براہ راست ٹائپ کنورژن کے ساتھ کال ہوتے ہیں +- **کثیر مرحلہ آرکیسٹریشن** — ٹول چیننگ کو خودکار طور پر سنبھالتا ہے +- **زیرو بوائلرپلیٹ** — کوئی دستی `AiServices.builder()` کالز یا میموری ہیش میپ نہیں -متبادل طریقے (دستی `AiServices.builder()`) میں زیادہ کوڈ کی ضرورت ہوتی ہے اور اسپرنگ بوٹ انٹیگریشن کے فوائد کھو جاتے ہیں۔ +متبادل طریقے (دستی `AiServices.builder()`) زیادہ کوڈ کی ضرورت رکھتے ہیں اور Spring Boot انٹیگریشن کے فوائد نہیں دیتے۔ ## ٹول چیننگ -**ٹول چیننگ** — ٹول بیسڈ ایجنٹس کی حقیقی طاقت اس وقت دکھائی دیتی ہے جب ایک سوال متعدد ٹولز کا تقاضا کرتا ہو۔ اگر پوچھیں "سیئیٹل میں فیرن ہائیٹ میں موسم کیسا ہے؟"، تو ایجنٹ خود بخود دو ٹولز کو چین کرتا ہے: پہلے یہ `getCurrentWeather` کال کرتا ہے تاکہ سیلسیس میں درجہ حرارت حاصل کرے، پھر اس ویلیو کو `celsiusToFahrenheit` میں پاس کرتا ہے تاکہ تبدیلی ہو — یہ سب ایک ہی گفتگو کے دور میں ہوتا ہے۔ +**ٹول چیننگ** — ٹول بیسڈ ایجنٹس کی اصل طاقت اس وقت دکھائی دیتی ہے جب ایک سوال کے لیے متعدد ٹولز کی ضرورت ہو۔ پوچھیں "سیئٹل میں فارن ہائیٹ میں موسم کیسا ہے؟" اور ایجنٹ خودکار طور پر دو ٹولز کو چین کرتا ہے: پہلے `getCurrentWeather` کو کال کرتا ہے تاکہ سیلسیئس میں درجہ حرارت ملے، پھر اسے `celsiusToFahrenheit` کو پاس کرتا ہے تاکہ کنورژن ہو — یہ سب ایک ہی گفتگو کے دور میں۔ -ٹول چیننگ کی مثال +Tool Chaining Example -*ٹول چیننگ عمل میں — ایجنٹ پہلے getCurrentWeather کال کرتا ہے، پھر سیلسیس کا نتیجہ celsiusToFahrenheit میں پاس کرتا ہے، اور مربوط جواب دیتا ہے۔* +*ٹول چیننگ عمل میں — ایجنٹ پہلے getCurrentWeather کال کرتا ہے، پھر سیلسیئس کے نتیجے کو celsiusToFahrenheit میں بھیجتا ہے، اور مشترکہ جواب دیتا ہے۔* -**نرمی سے خرابی کا سامنا** — اگر آپ کسی ایسے شہر کا موسم مانگیں جو جعلی ڈیٹا میں نہیں ہے، تو ٹول ایک ایرر میسج واپس کرتا ہے، اور AI وضاحت کرتا ہے کہ یہ مدد نہیں کر سکتا بجائے اس کے کہ ایپلیکیشن کریش ہو جائے۔ ٹول محفوظ طریقے سے ناکام ہوتے ہیں۔ ذیل میں دیا گیا خاکہ دونوں طریقوں کا موازنہ کرتا ہے — درست ایرر ہینڈلنگ کے ساتھ ایجنٹ استثناء پکڑ لیتا ہے اور مددگار جواب دیتا ہے، جبکہ بغیر اس کے پورا ایپلیکیشن کریش ہو جاتا ہے: +**نرمی سے ناکامی** — ایسے شہر کا موسم پوچھیں جو نقلی ڈیٹا میں نہیں ہے۔ ٹول ایرر میسج لوٹاتا ہے، اور AI اس بات کی وضاحت کرتا ہے کہ یہ مدد نہیں کر سکتا بجائے اس کے کہ ایپلیکیشن کریش ہو جائے۔ ٹولز محفوظ طریقے سے ناکام ہوتے ہیں۔ نیچے دیا گیا خاکہ دونوں طریقوں کا موازنہ کرتا ہے — مناسب خرابی سنبھالنے کے ساتھ ایجنٹ استثناء کو پکڑتا ہے اور مددگار جواب دیتا ہے، جبکہ بغیر خرابی ہینڈلنگ کے پورا ایپلیکیشن کریش ہو جاتا ہے: -خرابی سنبھالنے کا بہاؤ +Error Handling Flow -*جب ٹول ناکام ہو جاتا ہے، تو ایجنٹ غلطی کو پکڑ کر مددگار وضاحت کے ساتھ جواب دیتا ہے بجائے کریش کیے۔* +*جب ٹول ناکام ہوتا ہے، تو ایجنٹ خرابی پکڑتا ہے اور کریش ہونے کی بجائے مددگار وضاحت کے ساتھ جواب دیتا ہے۔* -یہ سب ایک ہی گفتگو کے دور میں ہوتا ہے۔ ایجنٹ متعدد ٹول کالز کو خودکار طور پر ترتیب دیتا ہے۔ +یہ سب ایک ہی گفتگو کے دور میں ہوتا ہے۔ ایجنٹ خود کار طریقے سے متعدد ٹول کالز کو سنبھالتا ہے۔ ## ایپلیکیشن چلائیں -**تصدیق کریں کہ تعیناتی مکمل ہے:** +**تصدیق کریں کہ تعیناتی ہوگئی ہے:** -یقین دہانی کریں کہ `.env` فائل روٹ ڈائریکٹری میں Azure کی اسناد کے ساتھ موجود ہے (جو ماڈیول 01 کے دوران بنی تھی)۔ ماڈیول ڈائریکٹری (`04-tools/`) سے یہ چلائیں: +یقینی بنائیں کہ `.env` فائل روٹ ڈائریکٹری میں Azure اسناد کے ساتھ موجود ہے (جو ماڈیول 01 کے دوران بنائی گئی تھی)۔ ماڈیول ڈائریکٹری (`04-tools/`) سے یہ کمانڈ چلائیں: -**باش:** +**بش:** ```bash -cat ../.env # AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT دکھانا چاہیے +cat ../.env # ظاہر کرنا چاہئے AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT ``` **پاور شیل:** ```powershell -Get-Content ..\.env # AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT دکھانا چاہیے +Get-Content ..\.env # دکھانا چاہیے AZURE_OPENAI_ENDPOINT، API_KEY، DEPLOYMENT ``` **ایپلیکیشن شروع کریں:** -> **نوٹ:** اگر آپ نے پہلے سے روٹ ڈائریکٹری سے `./start-all.sh` کے ذریعے تمام ایپلیکیشنز شروع کر دی ہیں (جیسا کہ ماڈیول 01 میں بیان کیا گیا ہے)، تو یہ ماڈیول پہلے ہی پورٹ 8084 پر چل رہا ہے۔ آپ نیچے دیے گئے شروع کرنے والے احکامات سے گزرنے کی ضرورت نہیں اور براہ راست http://localhost:8084 پر جا سکتے ہیں۔ +> **نوٹ:** اگر آپ نے پہلے سے سارے ایپلیکیشنز کو روٹ ڈائریکٹری سے `./start-all.sh` کے ذریعے شروع کیا ہے (جیسا کہ ماڈیول 01 میں بیان کیا گیا ہے)، تو یہ ماڈیول پہلے ہی پورٹ 8084 پر چل رہا ہے۔ آپ نیچے دیے گئے اسٹریٹ کمانڈز کو چھوڑ کر براہ راست http://localhost:8084 پر جا سکتے ہیں۔ -**اختیار 1: اسپرنگ بوٹ ڈیش بورڈ کا استعمال (وی ایس کوڈ صارفین کے لیے سفارش کی جاتی ہے)** +**اختیار 1: Spring Boot ڈیش بورڈ کا استعمال (VS Code صارفین کے لیے سفارش کی گئی)** -ڈیولپمنٹ کنٹینر میں اسپرنگ بوٹ ڈیش بورڈ ایکسٹینشن شامل ہے، جو تمام اسپرنگ بوٹ ایپلیکیشنز کو منظم کرنے کے لیے ایک بصری انٹرفیس فراہم کرتا ہے۔ آپ اسے VS کوڈ کے بائیں جانب ایکٹیویٹی بار میں اسپرنگ بوٹ کے آئیکن کے طور پر دیکھ سکتے ہیں۔ +ڈیولپمنٹ کنٹینر میں Spring Boot ڈیش بورڈ ایکسٹینشن شامل ہے، جو تمام Spring Boot ایپلیکیشنز کو منظم کرنے کے لیے بصری انٹرفیس فراہم کرتا ہے۔ آپ اسے VS Code کی بائیں جانب Activity Bar میں Spring Boot آئیکن کے طور پر دیکھ سکتے ہیں۔ -اسپرنگ بوٹ ڈیش بورڈ سے آپ کر سکتے ہیں: -- ورک اسپیس میں دستیاب تمام اسپرنگ بوٹ ایپلیکیشنز دیکھیں -- ایک کلک سے ایپلیکیشنز شروع یا بند کریں -- حقیقی وقت میں ایپلیکیشن لاگز دیکھیں -- ایپلیکیشن کی حیثیت مانیٹر کریں -بس "tools" کے ساتھ پلے بٹن پر کلک کریں تاکہ اس ماڈیول کو شروع کیا جا سکے، یا تمام ماڈیولز کو ایک ساتھ شروع کریں۔ +Spring Boot ڈیش بورڈ سے، آپ کر سکتے ہیں: +- ورک اسپیس میں تمام دستیاب Spring Boot ایپلیکیشنز دیکھیں +- ایک کلک سے ایپلیکیشنز کو شروع/بند کریں +- ایپلیکیشن لاگز کو حقیقی وقت میں دیکھیں +- ایپلیکیشن کی حالت کی نگرانی کریں -یہ ہے کہ VS Code میں Spring Boot ڈیش بورڈ کیسا دکھائی دیتا ہے: +بس "tools" کے ساتھ پلے بٹن پر کلک کریں تاکہ یہ ماڈیول شروع ہو، یا تمام ماڈیولز کو ایک ساتھ چلائیں۔ -Spring Boot Dashboard +یہ رہا Spring Boot ڈیش بورڈ VS Code میں کیسا دکھتا ہے: +Spring Boot ڈیش بورڈ -*VS Code میں Spring Boot ڈیش بورڈ — تمام ماڈیولز کو ایک جگہ سے شروع کریں، روکیں، اور مانیٹر کریں* +*VS کوڈ میں Spring Boot ڈیش بورڈ — تمام ماڈیولز کو ایک جگہ سے شروع، روکیں، اور مانیٹر کریں* **آپشن 2: شیل اسکرپٹس کا استعمال** تمام ویب ایپلیکیشنز (ماڈیولز 01-04) شروع کریں: -**Bash:** +**بش:** ```bash cd .. # روٹ ڈائریکٹری سے ./start-all.sh ``` -**PowerShell:** +**پاور شیل:** ```powershell -cd .. # روٹ ڈائریکٹری سے +cd .. # جڑ ڈائریکٹری سے .\start-all.ps1 ``` یا صرف اس ماڈیول کو شروع کریں: -**Bash:** +**بش:** ```bash cd 04-tools ./start.sh ``` -**PowerShell:** +**پاور شیل:** ```powershell cd 04-tools .\start.ps1 ``` -دونوں اسکرپٹس خود بخود روٹ `.env` فائل سے ماحول کی متغیرات لوڈ کرتے ہیں اور اگر JARs موجود نہیں ہیں تو انہیں بنائیں گے۔ +دونوں اسکرپٹس خودکار طریقے سے روٹ `.env` فائل سے ماحول کے متغیرات لوڈ کرتے ہیں اور اگر JARs موجود نہ ہوں تو انہیں تعمیر کریں گے۔ -> **نوٹ:** اگر آپ سبھی ماڈیولز کو دستی طور پر بنانا چاہتے ہیں شروع کرنے سے پہلے: +> **نوٹ:** اگر آپ شروع کرنے سے پہلے تمام ماڈیولز کو دستی طور پر تعمیر کرنا چاہتے ہیں: > -> **Bash:** +> **بش:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell:** +> **پاور شیل:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests @@ -276,100 +276,100 @@ cd 04-tools **روکنے کے لیے:** -**Bash:** +**بش:** ```bash -./stop.sh # صرف یہ ماڈیول +./stop.sh # یہ ماڈیول فقط # یا cd .. && ./stop-all.sh # تمام ماڈیولز ``` -**PowerShell:** +**پاور شیل:** ```powershell -.\stop.ps1 # یہ صرف ماڈیول +.\stop.ps1 # صرف یہ ماڈیول # یا cd ..; .\stop-all.ps1 # تمام ماڈیولز ``` ## ایپلیکیشن کا استعمال -یہ ایپلیکیشن ایک ویب انٹرفیس فراہم کرتی ہے جہاں آپ ایک AI ایجنٹ کے ساتھ بات چیت کر سکتے ہیں جسے موسم اور درجہ حرارت کنورژن ٹولز تک رسائی حاصل ہے۔ انٹرفیس کچھ یوں دکھائی دیتا ہے — اس میں فوری آغاز کے نمونے اور درخواستیں بھیجنے کے لیے چیٹ پینل شامل ہے: +یہ ایپلیکیشن ایک ویب انٹرفیس فراہم کرتی ہے جہاں آپ ایک AI ایجنٹ کے ساتھ تعامل کر سکتے ہیں جس کے پاس موسم اور درجہ حرارت کے کنورژن کے آلات تک رسائی ہے۔ انٹرفیس کچھ یوں نظر آتا ہے — جس میں فوری شروع کرنے کی مثالیں اور درخواست بھیجنے کے لیے چیٹ پینل شامل ہے: -AI Agent Tools Interface +AI ایجنٹ آلات کا انٹرفیس -*AI ایجنٹ ٹولز انٹرفیس - فوری نمونے اور ٹولز کے ساتھ بات چیت کے لیے چیٹ انٹرفیس* +*AI ایجنٹ آلات کا انٹرفیس - فوری مثالیں اور آلات کے ساتھ تعامل کے لیے چیٹ انٹرفیس* -### آسان ٹول استعمال کریں +### آسان آلات کے استعمال کی کوشش کریں -سادہ درخواست سے شروع کریں: "100 ڈگری فارن ہائیٹ کو سیلسس میں تبدیل کریں"۔ ایجنٹ پہچانتا ہے کہ اسے درجہ حرارت کنورژن ٹول کی ضرورت ہے، صحیح پیرامیٹرز کے ساتھ اسے کال کرتا ہے، اور نتیجہ لوٹاتا ہے۔ دھیان دیں کہ یہ کتنا قدرتی لگتا ہے - آپ نے مشخص نہیں کیا کہ کون سا ٹول استعمال کرنا ہے یا اسے کیسے کال کرنا ہے۔ +ایک سیدھی سادی درخواست سے شروع کریں: "100 ڈگری فارن ہائیٹ کو سیلسیس میں تبدیل کریں"۔ ایجنٹ کو معلوم ہوتا ہے کہ اسے درجہ حرارت کے کنورژن کے آلے کی ضرورت ہے، وہ اسے درست پیرامیٹرز کے ساتھ کال کرتا ہے اور نتیجہ واپس لاتا ہے۔ دھیان دیں کہ یہ کتنا قدرتی محسوس ہوتا ہے — آپ نے یہ متعین نہیں کیا کہ کون سا آلہ استعمال کرنا ہے یا اسے کیسے کال کرنا ہے۔ -### ٹول چیننگ آزمائیں +### آلے کے سلسلے کی جانچ کریں -اب کچھ زیادہ پیچیدہ آزمائیں: "سیئٹل کا موسم کیسا ہے اور اسے فارن ہائیٹ میں تبدیل کریں؟" دیکھیں کہ ایجنٹ قدم بہ قدم کیسے کام کرتا ہے۔ یہ پہلے موسم حاصل کرتا ہے (جو سیلسس دیتا ہے)، پہچانتا ہے کہ اسے فارن ہائیٹ میں تبدیل کرنے کی ضرورت ہے، کنورژن ٹول کال کرتا ہے، اور دونوں نتائج کو ایک جواب میں یکجا کرتا ہے۔ +اب کچھ زیادہ پیچیدہ آزمانا: "سیئیٹل میں موسم کیسا ہے اور اسے فارن ہائیٹ میں تبدیل کریں؟" دیکھیں کہ ایجنٹ اسے قدم بہ قدم کیسے حل کرتا ہے۔ پہلے موسم معلوم کرتا ہے (جو سیلسیس واپس دیتا ہے)، پھر پہچانتا ہے کہ اسے فارن ہائیٹ میں تبدیل کرنا ہے، کنورژن آلے کو کال کرتا ہے، اور دونوں نتائج کو ایک جواب میں جوڑ دیتا ہے۔ -### گفتگو کا بہاؤ دیکھیں +### گفتگو کے بہاؤ کو دیکھیں -چیٹ انٹرفیس گفتگو کی تاریخ رکھتا ہے، جس سے آپ کو متعدد مرحلوں پر بات چیت کرنے کی سہولت ملتی ہے۔ آپ تمام سابقہ سوالات اور جوابات دیکھ سکتے ہیں، جس سے گفتگو کا پیچھا کرنا اور ایجنٹ کا متعدد تبادلوں کے دوران کانٹیکسٹ بنانے کا طریقہ سمجھنا آسان ہوتا ہے۔ +چیٹ انٹرفیس گفتگو کی تاریخ کو برقرار رکھتا ہے، جس کی مدد سے آپ کثیر مراحل کی بات چیت کر سکتے ہیں۔ آپ پچھلے تمام سوالات اور جوابات دیکھ سکتے ہیں، جس سے بات چیت کا پتہ لگانا اور سمجھنا آسان ہوتا ہے کہ ایجنٹ متعدد تبادلوں کے دوران کیسے سیاق و سباق بناتا ہے۔ -Conversation with Multiple Tool Calls +متعدد آلے کالز کے ساتھ گفتگو -*متعدد چکر کی گفتگو جو سادہ تبادلوں، موسم کی تلاش، اور ٹول چیننگ دکھاتی ہے* +*کئی مرحلوں کی گفتگو میں سادہ تبدیلیاں، موسم کی تلاش، اور آلے کا سلسلہ دکھایا گیا ہے* -### مختلف درخواستیں آزما کر دیکھیں +### مختلف درخواستوں کے ساتھ تجربہ کریں -مختلف امتزاج آزمائیں: -- موسم کی معلومات: "ٹوکیو کا موسم کیسا ہے؟" -- درجہ حرارت کی تبدیلیاں: "25°C کیا کیلون میں ہے؟" -- مشترکہ سوالات: "پیرس میں موسم چیک کریں اور بتائیں کہ کیا یہ 20°C سے اوپر ہے" +مختلف امتزاجات آزمانے کی کوشش کریں: +- موسم کی تلاش: "ٹوکیو میں موسم کیسا ہے؟" +- درجہ حرارت کے کنورژن: "25°C کیلون میں کیا ہے؟" +- مشترکہ سوالات: "پیرس کا موسم چیک کریں اور بتائیں کہ کیا یہ 20°C سے اوپر ہے" -دھیان دیں کہ ایجنٹ قدرتی زبان کو کیسے سمجھتا ہے اور اسے مناسب ٹول کالز سے میپ کرتا ہے۔ +دھیان دیں کہ ایجنٹ قدرتی زبان کیسی تشریح کرتا ہے اور اسے مناسب آلہ کالز سے کیسے میپ کرتا ہے۔ -## کلیدی تصورات +## اہم تصورات -### ReAct پیٹرن (منطق و عمل) +### ReAct پیٹرن (استدلال اور عمل) -ایجنٹ منطق (کیا کرنا ہے فیصلہ کرنا) اور عمل (ٹولز کا استعمال) کے درمیان تبدیلی کرتا ہے۔ یہ پیٹرن خود مختار مسئلہ حل کرنے کی صلاحیت دیتا ہے بجائے صرف ہدایات پر عمل کرنے کے۔ +ایجنٹ استدلال (یہ فیصلہ کرنا کہ کیا کرنا ہے) اور عمل (آلات کا استعمال) کے درمیان باری باری کام کرتا ہے۔ یہ نمونہ خود مختار مسئلہ حل کرنے کا اہل بناتا ہے بجائے صرف ہدایات کے جواب دینے کے۔ -### ٹول کی وضاحتیں اہم ہیں +### آلے کی وضاحتیں اہم ہیں -آپ کے ٹول کی وضاحتوں کا معیار براہِ راست اثر ڈالتا ہے کہ ایجنٹ انہیں کتنی اچھی طرح استعمال کرتا ہے۔ واضح، مخصوص وضاحتیں ماڈل کو سمجھنے میں مدد دیتی ہیں کہ کب اور کیسے ہر ٹول کو کال کرنا ہے۔ +آپ کے آلے کی وضاحتوں کا معیار براہ راست اثر ڈالتا ہے کہ ایجنٹ انہیں کتنی اچھی طرح استعمال کرتا ہے۔ واضح اور مخصوص وضاحتیں ماڈل کو سمجھنے میں مدد دیتی ہیں کہ کب اور کیسے ہر آلے کو کال کرنا ہے۔ ### سیشن مینجمنٹ -`@MemoryId` تشریح خودکار سیشن پر مبنی میموری مینجمنٹ کو فعال کرتی ہے۔ ہر سیشن ID کو اپنی `ChatMemory` کا ایک انسٹانس ملتا ہے جو `ChatMemoryProvider` بین کے ذریعے منظم ہوتا ہے، اس لیے متعدد صارفین بیک وقت ایجنٹ کے ساتھ بات چیت کر سکتے ہیں بغیر ان کی گفتگو ایک دوسرے میں مکس ہوئے۔ درج ذیل خاکہ دکھاتا ہے کہ کس طرح متعدد صارفین کو ان کے سیشن IDs کی بنیاد پر الگ الگ میموری اسٹورز کی طرف بھیجا جاتا ہے: +`@MemoryId` تشریح خود کار سیشن پر مبنی میموری مینجمنٹ کو فعال کرتی ہے۔ ہر سیشن آئی ڈی کو اپنی `ChatMemory` انسٹینس ملتی ہے جسے `ChatMemoryProvider` بین سنبھالتا ہے، تاکہ متعدد صارفین بیک وقت ایجنٹ کے ساتھ بات چیت کر سکیں بغیر ان کی گفتگو آپس میں ملے۔ ذیل میں دکھایا گیا خاکہ کہ کیسے کئی صارفین کو ان کے سیشن آئی ڈی کی بنیاد پر الگ الگ میموری اسٹورز میں بھیجا جاتا ہے: -Session Management with @MemoryId +@MemoryId کے ساتھ سیشن مینجمنٹ -*ہر سیشن ID ایک علیحدہ گفتگو کی تاریخ سے میپ ہوتا ہے — صارفین ایک دوسرے کے پیغامات نہیں دیکھ پاتے۔* +*ہر سیشن آئی ڈی ایک الگ گفتگو کی تاریخ سے منسلک ہوتا ہے — صارفین کبھی ایک دوسرے کے پیغامات نہیں دیکھتے۔* -### غلطی سنبھالنا +### ایرر ہینڈلنگ -ٹولز ناکام ہو سکتے ہیں — APIs ٹائم آؤٹ ہو جاتے ہیں، پیرامیٹرز غلط ہو سکتے ہیں، بیرونی خدمات بند ہو سکتی ہیں۔ پروڈکشن ایجنٹس کو غلطی سنبھالنے کی ضرورت ہوتی ہے تاکہ ماڈل مسائل کو سمجھا سکے یا متبادل آزما سکے، بجائے کہ پوری ایپلیکیشن کریش کر جائے۔ جب کوئی ٹول استثناء پھینکتا ہے، LangChain4j اسے پکڑتا ہے اور غلطی کا پیغام ماڈل کو بھیجتا ہے، جو پھر مسئلے کی وضاحت قدرتی زبان میں کر سکتا ہے۔ +آلات ناکام ہو سکتے ہیں — APIs کا وقت ختم ہو سکتا ہے، پیرامیٹرز غلط ہو سکتے ہیں، بیرونی خدمات بند ہو سکتی ہیں۔ پروڈکشن ایجنٹس کو ایرر ہینڈلنگ کی ضرورت ہوتی ہے تاکہ ماڈل مسائل کی وضاحت کر سکے یا متبادل کوشش کر سکے بجائے اس کے کہ پوری ایپلیکیشن کریش ہو جائے۔ جب کوئی آلہ استثناء پھینکتا ہے، LangChain4j اسے پکڑ لیتا ہے اور ماڈل کو ایرر میسج واپس بھیجتا ہے، جو پھر قدرتی زبان میں مسئلہ بیان کر سکتا ہے۔ -## دستیاب ٹولز +## دستیاب آلات -نیچے دیا گیا خاکہ اس وسیع ماحولی نظام کو دکھاتا ہے جو آپ تعمیر کر سکتے ہیں۔ یہ ماڈیول موسم اور درجہ حرارت کے ٹولز دکھاتا ہے، لیکن وہی `@Tool` پیٹرن کسی جاوا میتھڈ کے لیے کام کرتا ہے — چاہے وہ ڈیٹا بیس کی تلاش ہو یا ادائیگی کی پراسیسنگ۔ +ذیل میں دیا گیا خاکہ ان وسیع آلات کا منظر نامہ دکھاتا ہے جو آپ بنا سکتے ہیں۔ یہ ماڈیول موسم اور درجہ حرارت کے آلات کی مثال دیتا ہے، لیکن وہی `@Tool` پیٹرن کسی بھی جاوا میتھڈ کے لیے کام کرتا ہے — چاہے وہ ڈیٹابیس کی تلاش ہو یا ادائیگی کا عمل۔ -Tool Ecosystem +آلات کا ماحولیاتی نظام -*کسی بھی جاوا میتھڈ پر @Tool کا اینوٹیشن AI کے لیے دستیاب بناتا ہے — یہ پیٹرن ڈیٹا بیسز، APIs، ای میل، فائل آپریشنز، اور مزید تک پھیلتا ہے۔* +*کوئی بھی جاوا میتھڈ جو @Tool سے تشریح شدہ ہو AI کے لیے دستیاب ہو جاتی ہے — یہ پیٹرن ڈیٹابیسز، APIs، ای میل، فائل آپریشنز، اور مزید تک پھیلا ہوا ہے۔* -## ٹول بیسڈ ایجنٹس کب استعمال کریں +## آلہ پر مبنی ایجنٹس کا استعمال کب کریں -ہر درخواست کو ٹولز کی ضرورت نہیں ہوتی۔ فیصلہ اس بات پر ہوتا ہے کہ آیا AI کو بیرونی نظاموں سے بات چیت کرنی ہے یا وہ اپنی معلومات سے جواب دے سکتا ہے۔ درج ذیل گائیڈ خلاصہ کرتا ہے کہ ٹولز کب فائدہ مند ہوتے ہیں اور کب غیر ضروری: +ہر درخواست کو آلات کی ضرورت نہیں ہوتی۔ فیصلہ یہ ہوتا ہے کہ آیا AI کو بیرونی نظاموں کے ساتھ بات چیت کرنے کی ضرورت ہے یا وہ اپنی معلومات سے جواب دے سکتا ہے۔ ذیل میں گائیڈ خلاصہ کرتی ہے کہ آلات کب فائدہ مند ہوتے ہیں اور کب غیر ضروری: -When to Use Tools +آلات کب استعمال کریں -*ایک فوری فیصلہ گائیڈ — ٹولز حقیقی وقت کا ڈیٹا، حساب کتاب، اور کارروائیوں کے لیے ہوتے ہیں؛ عمومی معلومات اور تخلیقی کاموں کو ان کی ضرورت نہیں ہوتی۔* +*ایک فوری فیصلہ گائیڈ — آلات حقیقی وقت کا ڈیٹا، حسابات، اور کارروائیوں کے لیے ہوتے ہیں؛ عمومی علم اور تخلیقی کاموں کے لیے نہیں۔* -## ٹولز بمقابلہ RAG +## آلات بمقابلہ RAG -ماڈیولز 03 اور 04 دونوں AI کی صلاحیتوں کو بڑھاتے ہیں، لیکن بنیادی طور پر مختلف طریقوں سے۔ RAG ماڈل کو دستاویزات کی بازیافت کے ذریعے **علم** فراہم کرتا ہے۔ ٹولز ماڈل کو فنکشنز کال کر کے **عمل** کرنے کے قابل بناتے ہیں۔ نیچے دیا گیا خاکہ ان دونوں طریقوں کا موازنہ کرتا ہے — کس طرح ہر ورک فلو کام کرتا ہے اور ان کے فوائد اور نقصانات کیا ہیں: +ماڈیولز 03 اور 04 دونوں AI کی صلاحیتوں کو بڑھاتے ہیں، مگر بنیادی طور پر مختلف طریقوں سے۔ RAG ماڈل کو **علم** تک رسائی دیتا ہے دستاویزات حاصل کر کے۔ آلات ماڈل کو **عمل** کرنے کی صلاحیت دیتے ہیں فنکشنز کال کر کے۔ ذیل میں دیا گیا خاکہ ان دو طریقوں کا موازنہ کرتا ہے — ہر ورک فلو کیسے چلتا ہے اور ان کے درمیان فوائد و نقصانات: -Tools vs RAG Comparison +آلات بمقابلہ RAG موازنہ -*RAG جامد دستاویزات سے معلومات حاصل کرتا ہے — ٹولز عمل انجام دیتے اور متحرک، حقیقی وقت کا ڈیٹا لاتے ہیں۔ بہت سے پروڈکشن سسٹمز دونوں کو ملا کر استعمال کرتے ہیں۔* +*RAG ساکن دستاویزات سے معلومات حاصل کرتا ہے — آلات عمل انجام دیتے ہیں اور متحرک، حقیقی وقت کا ڈیٹا لاتے ہیں۔ بہت سے پروڈکشن سسٹمز دونوں کو ملاتے ہیں۔* -عملی طور پر، بہت سے پروڈکشن سسٹمز دونوں طریقے ملاتے ہیں: RAG جوابات کو آپ کی دستاویزات میں گراؤنڈ کرنے کے لیے، اور ٹولز براہِ راست ڈیٹا حاصل کرنے یا آپریشنز کرنے کے لیے۔ +عملی طور پر، بہت سے پروڈکشن سسٹمز دونوں طریقے استعمال کرتے ہیں: RAG آپ کی ڈاکیومنٹیشن میں جوابات کو بنیاد فراہم کرنے کے لیے، اور آلات لائیو ڈیٹا حاصل کرنے یا آپریشنز کرنے کے لیے۔ ## اگلے اقدامات @@ -377,11 +377,11 @@ cd ..; .\stop-all.ps1 # تمام ماڈیولز --- -**نیویگیشن:** [← پچھلا: ماڈیول 03 - RAG](../03-rag/README.md) | [واپس مرکزی صفحے پر](../README.md) | [اگلا: ماڈیول 05 - MCP →](../05-mcp/README.md) +**نیوگیشن:** [← پچھلا: ماڈیول 03 - RAG](../03-rag/README.md) | [واپس مرکزی صفحہ](../README.md) | [اگلا: ماڈیول 05 - MCP →](../05-mcp/README.md) --- -**دستخطِ ذمہ داری**: -یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ اگرچہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار تراجم میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز کو اس کی مادری زبان میں معتبر ذریعہ سمجھا جانا چاہیے۔ اہم معلومات کے لیے پیشہ ورانہ انسانی ترجمہ تجویز کیا جاتا ہے۔ ہم اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تعبیر کے ذمہ دار نہیں ہیں۔ +**ڈس کلیمر**: +یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔ \ No newline at end of file diff --git a/translations/ur/README.md b/translations/ur/README.md index d9cc80387..f76ca67ff 100644 --- a/translations/ur/README.md +++ b/translations/ur/README.md @@ -1,19 +1,19 @@ LangChain4j -# ابتدائیوں کے لیے LangChain4j +# نئے صارفین کے لیے LangChain4j LangChain4j اور Azure OpenAI GPT-5.2 کے ساتھ AI ایپلیکیشنز بنانے کا کورس، بنیادی چیٹ سے لے کر AI ایجنٹس تک۔ -### 🌐 کثیراللسانی حمایت +### 🌐 متعدد زبانوں کی حمایت -#### GitHub ایکشن کے ذریعے حمایت یافتہ (خودکار اور ہمیشہ تازہ ترین) +#### GitHub Action کے ذریعے حمایت یافتہ (خودکار اور ہمیشہ تازہ ترین) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](./README.md) | [Vietnamese](../vi/README.md) -> **مقامی طور پر کلون کرنا پسند کریں گے؟** +> **مقامی طور پر کلون کرنا پسند کریں؟** > -> اس رپوزیٹری میں 50+ زبانوں کے تراجم شامل ہیں جو ڈاؤن لوڈ سائز کو نمایاں طور پر بڑھاتے ہیں۔ تراجم کے بغیر کلون کرنے کے لیے، sparse checkout استعمال کریں: +> اس ریپوزٹری میں 50+ زبانوں کے تراجم شامل ہیں جو ڈاؤن لوڈ سائز کو کافی بڑھاتے ہیں۔ تراجم کے بغیر کلون کرنے کے لیے sparse checkout استعمال کریں: > > **Bash / macOS / Linux:** > ```bash @@ -29,62 +29,62 @@ LangChain4j اور Azure OpenAI GPT-5.2 کے ساتھ AI ایپلیکیشنز ب > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> اس سے آپ کو کورس مکمل کرنے کے لیے سب کچھ ملتا ہے اور ڈاؤن لوڈ بھی بہت تیز ہوتا ہے۔ +> اس طرح آپ کو کورس مکمل کرنے کے لیے درکار سب کچھ بہت تیز رفتاری سے ڈاؤن لوڈ ہوتا ہے۔ -## مواد کی فہرست +## فہرست مضامین -1. [فوری آغاز](00-quick-start/README.md) - LangChain4j کے ساتھ شروعات کریں -2. [تعارف](01-introduction/README.md) - LangChain4j کی بنیادی باتیں سیکھیں -3. [پرومپٹ انجینئرنگ](02-prompt-engineering/README.md) - مؤثر پرومپٹ ڈیزائن میں مہارت حاصل کریں -4. [RAG (ریٹریول-آگمینٹڈ جنریشن)](03-rag/README.md) - ذہین علم پر مبنی نظام بنائیں -5. [اوزار](04-tools/README.md) - خارجی اوزار اور سادہ اسسٹنٹس شامل کریں -6. [MCP (ماڈل کانٹیکسٹ پروٹوکول)](05-mcp/README.md) - ماڈل کانٹیکسٹ پروٹوکول (MCP) اور ایجنٹک ماڈیولز کے ساتھ کام کریں +1. [تعارف](01-introduction/README.md) - LangChain4j کی بنیادی باتیں سیکھیں +2. [پرومپٹ انجینئرنگ](02-prompt-engineering/README.md) - موثر پرومپٹ ڈیزائن میں مہارت حاصل کریں +3. [RAG (ریٹریول-اگمینٹڈ جنریشن)](03-rag/README.md) - ذہین علم پر مبنی نظام بنائیں +4. [آلات](04-tools/README.md) - بیرونی آلات اور آسان معاونین کو مربوط کریں +5. [MCP (ماڈل کانٹیکسٹ پروٹوکول)](05-mcp/README.md) - ماڈل کانٹیکسٹ پروٹوکول (MCP) اور ایجینٹک ماڈیولز کے ساتھ کام کریں -### ویڈیو واک تھروز +### ویڈیو واک تھرو -ہر ماڈیول کے ساتھ ایک لائیو سیشن بھی ہوتا ہے جہاں ہم تصورات اور کوڈ کو قدم بہ قدم سمجھاتے ہیں۔ +ہر ماڈیول کے ساتھ ایک لائیو سیشن ہوتا ہے جس میں ہم تصورات اور کوڈ کو مرحلہ وار سمجھاتے ہیں۔ | ماڈیول | ویڈیو | |--------|-------| | 01 - تعارف | [LangChain4j کے ساتھ شروعات](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - پرومپٹ انجینئرنگ | [LangChain4j کے ساتھ پرومپٹ انجینئرنگ](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [LangChain4j کے ساتھ RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - اوزار اور 05 - MCP | [اوزار اور MCP کے ساتھ AI ایجنٹس](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - آلات اور 05 - MCP | [آلات اور MCP کے ساتھ AI ایجنٹس](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## سیکھنے کا راستہ -**LangChain4j میں نیا ہیں؟** اہم اصطلاحات اور تصورات کی تعریف کے لیے [گلاسری](docs/GLOSSARY.md) دیکھیں۔ +**LangChain4j میں نیا ہیں؟** مرکزی اصطلاحات اور تصورات کی تعریف کے لیے [گلاسری](docs/GLOSSARY.md) دیکھیں۔ -> **فوری آغاز** +> **جلدی شروع کریں** -1. اس رپوزیٹری کو اپنے GitHub اکاؤنٹ پر فورک کریں -2. کلک کریں **Code** → **Codespaces** ٹیب → **...** → **New with options...** -3. ڈیفالٹس استعمال کریں – یہ کورس کے لیے بنایا گیا ڈیولپمنٹ کنٹینر منتخب کرے گا -4. کلک کریں **Create codespace** +1. اس ریپوزٹری کو اپنے GitHub اکاؤنٹ پر فورک کریں +2. **Code** → **Codespaces** ٹیب → **...** → **New with options...** پر کلک کریں +3. ڈیفالٹس کا استعمال کریں – یہ اس کورس کے لیے بنایا گیا ڈیولپمنٹ کنٹینر منتخب کرے گا +4. **Create codespace** پر کلک کریں 5. ماحول کے تیار ہونے کے لیے 5-10 منٹ انتظار کریں -6. سیدھے [فوری آغاز](./00-quick-start/README.md) پر جا کر شروع کریں! +6. شروع کرنے کے لیے سیدھا [تعارف](./01-introduction/README.md) پر جائیں! -ماڈیولز مکمل کرنے کے بعد، [Testing Guide](docs/TESTING.md) دریافت کریں تاکہ LangChain4j کے ٹیسٹنگ تصورات کو عملی طور پر دیکھ سکیں۔ +ماڈیولز مکمل کرنے کے بعد، LangChain4j کے ٹیسٹنگ تصورات کو عملی طور پر دیکھنے کے لیے [ٹیسٹنگ گائیڈ](docs/TESTING.md) کو دریافت کریں۔ + +> **نوٹ:** یہ تربیت Azure OpenAI استعمال کرتی ہے۔ اگر آپ کے پاس نہیں ہے تو [مفت Azure اکاؤنٹ](https://aka.ms/azure-free-account) کے ساتھ شروع کریں۔ -> **نوٹ:** یہ تربیت GitHub ماڈلز اور Azure OpenAI دونوں استعمال کرتی ہے۔ [فوری آغاز](00-quick-start/README.md) ماڈیول GitHub ماڈلز استعمال کرتا ہے (Azure سبسکرپشن ضروری نہیں)، جب کہ ماڈیولز 1-5 Azure OpenAI استعمال کرتے ہیں۔ اگر آپ کے پاس نہیں ہے تو [مفت Azure اکاؤنٹ](https://aka.ms/azure-free-account) سے شروع کریں۔ ## GitHub Copilot کے ساتھ سیکھنا -جلدی کوڈنگ شروع کرنے کے لیے، اس پروجیکٹ کو GitHub Codespace یا آپ کے مقامی IDE میں، دیے گئے devcontainer کے ساتھ کھولیں۔ اس کورس میں استعمال ہونے والا devcontainer GitHub Copilot کے ساتھ AI پیئر پروگرامنگ کے لیے پہلے سے ترتیب دیا گیا ہے۔ +کوڈنگ جلد شروع کرنے کے لیے، اس پروجیکٹ کو GitHub Codespace یا اپنے لوکل IDE میں فراہم کردہ devcontainer کے ساتھ کھولیں۔ اس کورس میں استعمال ہونے والا devcontainer GitHub Copilot کے ساتھ پہلے سے ترتیب دیا گیا ہے تاکہ AI جوڑی ہوئی پروگرامنگ کی سہولت ہو۔ -ہر کوڈ مثال میں وہ سوالات شامل ہیں جو آپ GitHub Copilot سے پوچھ سکتے ہیں تاکہ آپ کا فہم گہرا ہو۔ ان سوالات کو 💡/🤖 کے نشانات میں تلاش کریں: +ہر کوڈ مثال میں وہ سوالات شامل ہیں جو آپ GitHub Copilot سے پوچھ کر اپنی سمجھ کو گہرا کر سکتے ہیں۔ 💡/🤖 کے نشان تلاش کریں: -- **جاوا فائل کے ہیڈرز** - ہر مثال سے متعلق مخصوص سوالات -- **ماڈیول کے README** - کوڈ مثالوں کے بعد تفصیلی سوالات +- **جاوا فائل کے ہیڈرز** - ہر مثال کے مخصوص سوالات +- **ماڈیول README** - کوڈ مثالوں کے بعد دریافت کے لئے سوالات -**استعمال کا طریقہ:** کسی بھی کوڈ فائل کو کھولیں اور Copilot سے وہ سوالات پوچھیں۔ اسے پورے کوڈ بیس کا سیاق و سباق معلوم ہے اور یہ وضاحت دے سکتا ہے، بڑھا سکتا ہے، اور متبادل تجویز کر سکتا ہے۔ +**استعمال کا طریقہ:** کوئی بھی کوڈ فائل کھولیں اور Copilot سے مشورہ شدہ سوالات پوچھیں۔ اسے پورے کوڈبیس کا مکمل سیاق و سباق معلوم ہے اور یہ وضاحت، توسیع، اور متبادل مشورے دے سکتا ہے۔ -مزید جاننا چاہتے ہیں؟ دیکھیں [AI پیئر پروگرامنگ کے لیے Copilot](https://aka.ms/GitHubCopilotAI)۔ +مزید جاننا چاہتے ہیں؟ دیکھیں [AI کے لیے Copilot جوڑی ہوئی پروگرامنگ](https://aka.ms/GitHubCopilotAI)۔ -## اضافی ذرائع +## اضافی وسائل ### LangChain @@ -93,7 +93,7 @@ LangChain4j اور Azure OpenAI GPT-5.2 کے ساتھ AI ایپلیکیشنز ب [![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / ایج / MCP / ایجنٹس +### Azure / Edge / MCP / Agents [![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) [![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) [![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -101,7 +101,7 @@ LangChain4j اور Azure OpenAI GPT-5.2 کے ساتھ AI ایپلیکیشنز ب --- -### جنریٹیو AI سیریز +### Generative AI Series [![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) @@ -113,13 +113,28 @@ LangChain4j اور Azure OpenAI GPT-5.2 کے ساتھ AI ایپلیکیشنز ب [![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) [![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) [![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) + +--- + ### کوپائلٹ سیریز +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) + ## مدد حاصل کرنا -اگر آپ پھنس جائیں یا AI ایپس بنانے کے بارے میں کوئی سوال ہو، تو شامل ہوں: +اگر آپ پھنس جائیں یا AI ایپس بنانے کے بارے میں کوئی سوال ہو، شامل ہوں: + +[![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) + +اگر آپ کے پاس پراڈکٹ کے بارے میں تاثرات یا ڈیولپمنٹ کے دوران غلطیاں ہوں تو یہاں جائیں: -اگر آپ کو پروڈکٹ کی رائے یا تعمیر کے دوران کوئی غلطی ہو تو ملاحظہ کریں: +[![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## لائسنس @@ -128,6 +143,6 @@ MIT لائسنس - تفصیلات کے لیے [LICENSE](../../LICENSE) فائل --- -**تحریری دستبرداری**: -یہ دستاویز AI ترجمہ خدمت [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ ہم درستگی کے لیے کوشاں ہیں، لیکن براہ کرم یہ ذہن میں رکھیں کہ خودکار ترجمے میں غلطیاں یا غیر یقینی باتیں ہو سکتی ہیں۔ اصل دستاویز اپنی مادری زبان میں مستند ذریعہ جانی جائے۔ اہم معلومات کے لیے پیشہ ور انسانی ترجمہ تجویز کیا جاتا ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم پر عائد نہیں ہوتی۔ +**ڈس کلیمر**: +یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔ \ No newline at end of file diff --git a/translations/ur/docs/GLOSSARY.md b/translations/ur/docs/GLOSSARY.md index a8867060e..0ec18f1b7 100644 --- a/translations/ur/docs/GLOSSARY.md +++ b/translations/ur/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j اصطلاحات کی فہرست +# LangChain4j لغت نامہ ## فہرست مضامین -- [بنیادی تصورات](../../../docs) -- [LangChain4j کے اجزاء](../../../docs) -- [AI/ML تصورات](../../../docs) -- [گارنٹیلز](../../../docs) -- [پرومپٹ انجینئرنگ](../../../docs) -- [RAG (ریٹریول-آگمینٹڈ جنریشن)](../../../docs) -- [ایجنٹس اور ٹولز](../../../docs) -- [ایجنٹک ماڈیول](../../../docs) -- [ماڈل کانٹیکسٹ پروٹوکول (MCP)](../../../docs) -- [ایزور خدمات](../../../docs) -- [ٹیسٹنگ اور ڈیولپمنٹ](../../../docs) +- [بنیادی تصورات](#بنیادی-تصورات) +- [LangChain4j کے اجزاء](#langchain4j-کے-اجزاء) +- [AI/ML تصورات](#aiml-تصورات) +- [گارڈریل](#گارڈریل) +- [پرومپٹ انجینئرنگ](#prompt-engineering---module-02) +- [RAG (ریٹریول-آگمینٹڈ جنریشن)](#rag-retrieval-augmented-generation---module-03) +- [ایجنٹس اور ٹولز](#agents-and-tools---module-04) +- [ایجنٹک ماڈیول](#agentic-module---module-05) +- [ماڈل کانٹیکسٹ پروٹوکول (MCP)](#model-context-protocol-mcp---module-05) +- [ایژور سروسز](#azure-services---module-01) +- [ٹیسٹنگ اور ڈیولپمنٹ](#testing-and-development---testing-guide) -کورس کے دوران استعمال ہونے والی اصطلاحات اور تصورات کا فوری حوالہ۔ +کورس میں استعمال ہونے والے اصطلاحات اور تصورات کے لئے فوری حوالہ۔ ## بنیادی تصورات -**AI ایجنٹ** - نظام جو AI کا استعمال کرتے ہوئے خودمختار طور پر دلیل دیتا ہے اور عمل کرتا ہے۔ [ماڈیول 04](../04-tools/README.md) +**AI ایجنٹ** - نظام جو AI استعمال کرتا ہے تاکہ خود مختار طور پر سوچے اور عمل کرے۔ [ماڈیول 04](../04-tools/README.md) -**چین** - عملوں کی ترتیب جہاں آؤٹ پٹ اگلے مرحلے میں داخل ہوتی ہے۔ +**چین** - آپریشنز کی ایک ترتیب جہاں آؤٹ پٹ اگلے مرحلے میں داخل ہوتا ہے۔ -**چنکنگ** - دستاویزات کو چھوٹے حصوں میں توڑنا۔ عام: 300-500 ٹوکنز باہمی اوورلیپ کے ساتھ۔ [ماڈیول 03](../03-rag/README.md) +**چنکنگ** - دستاویزات کو چھوٹے ٹکڑوں میں تقسیم کرنا۔ عام: 300-500 ٹوکنز اوورلیپ کے ساتھ۔ [ماڈیول 03](../03-rag/README.md) -**کانٹیکسٹ ونڈو** - زیادہ سے زیادہ ٹوکنز جو ماڈل پروسیس کر سکتا ہے۔ GPT-5.2: 400K ٹوکنز (حد تک 272K ان پٹ، 128K آؤٹ پٹ)۔ +**کانٹیکسٹ ونڈو** - زیادہ سے زیادہ ٹوکن جو ماڈل پروسیس کر سکتا ہے۔ GPT-5.2: 400K ٹوکنز (272K تک ان پٹ، 128K آؤٹ پٹ)۔ -**ایمبیڈنگز** - متن کے معنی کی نمائندگی کرنے والے عددی ویکٹرز۔ [ماڈیول 03](../03-rag/README.md) +**ایمبیڈنگز** - عددی ویکٹرز جو متن کے معنی کو ظاہر کرتے ہیں۔ [ماڈیول 03](../03-rag/README.md) **فنکشن کالنگ** - ماڈل ساختہ درخواستیں جنریٹ کرتا ہے تاکہ بیرونی فنکشنز کو کال کیا جا سکے۔ [ماڈیول 04](../04-tools/README.md) **ہیلوسینیشن** - جب ماڈلز غلط مگر ممکنہ معلومات تخلیق کرتے ہیں۔ -**پرومپٹ** - زبان کے ماڈل کو دیا جانے والا متن۔ [ماڈیول 02](../02-prompt-engineering/README.md) +**پرومپٹ** - زبان کے ماڈل کو دیا جانے والا متنی ان پٹ۔ [ماڈیول 02](../02-prompt-engineering/README.md) -**سیمنٹک سرچ** - ایمبیڈنگز کا استعمال کرتے ہوئے معانی کی بنیاد پر سرچ، نہ کہ کی ورڈز سے۔ [ماڈیول 03](../03-rag/README.md) +**سمینٹک سرچ** - ایمبیڈنگز کے ذریعے معنی کی بنیاد پر تلاش، کی ورڈز کی بجائے۔ [ماڈیول 03](../03-rag/README.md) -**اسٹیٹ فل بمقابلہ اسٹیٹ لیس** - اسٹیٹ لیس: کوئی یادداشت نہیں۔ اسٹیٹ فل: مکالمے کی تاریخ محفوظ رکھتا ہے۔ [ماڈیول 01](../01-introduction/README.md) +**اسٹیٹ فل بمقابلہ اسٹیٹ لیس** - اسٹیٹ لیس: کوئی یادداشت نہیں۔ اسٹیٹ فل: بات چیت کی تاریخ رکھتا ہے۔ [ماڈیول 01](../01-introduction/README.md) -**ٹوکنز** - بنیادی متن کے یونٹس جو ماڈلز پروسیس کرتے ہیں۔ اخراجات اور حدود پر اثر انداز ہوتے ہیں۔ [ماڈیول 01](../01-introduction/README.md) +**ٹوکنز** - وہ بنیادی تحریری اکائیاں جو ماڈلز پروسیس کرتے ہیں۔ لاگت اور حدوں پر اثرانداز ہوتے ہیں۔ [ماڈیول 01](../01-introduction/README.md) -**ٹول چیننگ** - آلات کی ترتیب وار عملدرآمد جہاں آؤٹ پٹ اگلی کال کی معلومات فراہم کرتی ہے۔ [ماڈیول 04](../04-tools/README.md) +**ٹول چیننگ** - ٹولز کو سلسلہ وار چلانا جہاں آؤٹ پٹ اگلی کال کو متاثر کرتی ہے۔ [ماڈیول 04](../04-tools/README.md) ## LangChain4j کے اجزاء -**AiServices** - ٹائپ-سیف AI سروس انٹرفیسز تخلیق کرتا ہے۔ +**AiServices** - قسم محفوظ AI سروس انٹرفیسز تخلیق کرتا ہے۔ -**OpenAiOfficialChatModel** - OpenAI اور Azure OpenAI ماڈلز کے لیے متحدہ کلائنٹ۔ +**OpenAiOfficialChatModel** - OpenAI اور Azure OpenAI ماڈلز کے لئے متحدہ کلائنٹ۔ -**OpenAiOfficialEmbeddingModel** - OpenAI آفیشل کلائنٹ کا استعمال کرتے ہوئے ایمبیڈنگز تخلیق کرتا ہے (OpenAI اور Azure OpenAI دونوں کی حمایت کرتا ہے)۔ +**OpenAiOfficialEmbeddingModel** - وہ ایمبیڈنگز بناتا ہے جو OpenAI آفیشل کلائنٹ استعمال کرتے ہیں (OpenAI اور Azure OpenAI دونوں کو سپورٹ کرتا ہے)۔ **ChatModel** - زبان کے ماڈلز کے لیے بنیادی انٹرفیس۔ -**ChatMemory** - مکالمے کی تاریخ برقرار رکھتا ہے۔ +**ChatMemory** - بات چیت کی تاریخ کو برقرار رکھتا ہے۔ -**ContentRetriever** - RAG کے لیے متعلقہ دستاویز چنکس تلاش کرتا ہے۔ +**ContentRetriever** - RAG کے لیے متعلقہ دستاویز کے ٹکڑے تلاش کرتا ہے۔ **DocumentSplitter** - دستاویزات کو چنکس میں تقسیم کرتا ہے۔ **EmbeddingModel** - متن کو عددی ویکٹرز میں تبدیل کرتا ہے۔ -**EmbeddingStore** - ایمبیڈنگز ذخیرہ اور بازیافت کرتا ہے۔ +**EmbeddingStore** - ایمبیڈنگز کو ذخیرہ اور بازیافت کرتا ہے۔ **MessageWindowChatMemory** - حالیہ پیغامات کی سلائیڈنگ ونڈو کو برقرار رکھتا ہے۔ -**PromptTemplate** - `{{variable}}` پلیس ہولڈرز کے ساتھ دوبارہ قابل استعمال پرومپٹس بناتا ہے۔ +**PromptTemplate** - `{{variable}}` جگہ داروں کے ساتھ قابل استعمال پرومپٹس تخلیق کرتا ہے۔ -**TextSegment** - میٹا ڈیٹا کے ساتھ متن کا چنک۔ RAG میں استعمال ہوتا ہے۔ +**TextSegment** - میٹا ڈیٹا کے ساتھ متن کا ٹکڑا۔ RAG میں استعمال ہوتا ہے۔ -**ToolExecutionRequest** - ٹولز کے عملدرآمد کی درخواست کی نمائندگی کرتا ہے۔ +**ToolExecutionRequest** - ٹول ایکزیکیوشن کی درخواست کی نمائندگی کرتا ہے۔ -**UserMessage / AiMessage / SystemMessage** - مکالمے کے پیغام کی اقسام۔ +**UserMessage / AiMessage / SystemMessage** - بات چیت کے پیغام کی اقسام۔ ## AI/ML تصورات **Few-Shot Learning** - پرومپٹس میں مثالیں فراہم کرنا۔ [ماڈیول 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - وسیع متن کے ڈیٹا پر تربیت یافتہ AI ماڈلز۔ +**بڑا زبان ماڈل (LLM)** - AI ماڈلز جو وسیع متنی ڈیٹا پر تربیت یافتہ ہوتے ہیں۔ -**Reasoning Effort** - GPT-5.2 کا پیرامیٹر جو سوچ کی گہرائی کو کنٹرول کرتا ہے۔ [ماڈیول 02](../02-prompt-engineering/README.md) +**ریزننگ ایفورٹ** - GPT-5.2 پیرامیٹر جو سوچنے کی گہرائی کو کنٹرول کرتا ہے۔ [ماڈیول 02](../02-prompt-engineering/README.md) -**Temperature** - آؤٹ پٹ کی بے ترتیبیت کو کنٹرول کرتا ہے۔ کم = قطعی، زیادہ = تخلیقی۔ +**ٹیمپریچر** - آؤٹ پٹ کی بے ترتیبی کو کنٹرول کرتا ہے۔ کم=حتمی، زیادہ=تخلیقی۔ -**Vector Database** - ایمبیڈنگز کے لیے مخصوص ڈیٹا بیس۔ [ماڈیول 03](../03-rag/README.md) +**ویکٹر ڈیٹا بیس** - ایمبیڈنگز کے لیے خصوصی ڈیٹا بیس۔ [ماڈیول 03](../03-rag/README.md) -**Zero-Shot Learning** - بغیر مثالوں کے کام انجام دینا۔ [ماڈیول 02](../02-prompt-engineering/README.md) +**زیرو شاٹ لرننگ** - بغیر مثال کے کام انجام دینا۔ [ماڈیول 02](../02-prompt-engineering/README.md) -## گارنٹیلز - [ماڈیول 00](../00-quick-start/README.md) +## گارڈریل -**ڈیفنس ان دیپتھ** - ملٹی لیئر سیکیورٹی طریقہ جس میں ایپلیکیشن لیول گارنٹیلز اور پروائیڈر سیفٹی فلٹرز شامل ہوتے ہیں۔ +**ڈیفنس اِن ڈیپتھ** - ملٹی لئیر سیکیورٹی کا طریقہ جو ایپلیکیشن سطح کے گارڈریل کو فراہم کنندہ کے سیفٹی فلٹرز کے ساتھ ملاتا ہے۔ -**ہارڈ بلاک** - سخت مواد کی خلاف ورزیوں پر پروائیڈر HTTP 400 ایرر پھینکتا ہے۔ +**ہارڈ بلاک** - شدید مواد کی خلاف ورزی پر فراہم کنندہ HTTP 400 ایرر دیتا ہے۔ -**InputGuardrail** - LangChain4j انٹرفیس جو ماڈل تک پہنچنے سے پہلے صارف کی ان پٹ کی تصدیق کرتا ہے۔ نقصان دہ پرومپٹس کو ابتدائی طور پر بلاک کر کے لاگت اور تاخیر بچاتا ہے۔ +**InputGuardrail** - LangChain4j انٹرفیس جو LLM تک پہنچنے سے پہلے صارف کے ان پٹ کی تصدیق کرتا ہے۔ نقصان دہ پرومپٹس کو جلد بلاک کر کے لاگت اور تاخیر بچاتا ہے۔ -**InputGuardrailResult** - گارنٹیل کی تصدیق کا ریٹرن ٹائپ: `success()` یا `fatal("reason")`۔ +**InputGuardrailResult** - گارڈریل کی تصدیق کا ریٹرن ٹائپ: `success()` یا `fatal("reason")`۔ -**OutputGuardrail** - AI جوابات کی تصدیق کا انٹرفیس جو صارفین کو بھیجنے سے پہلے ہوتا ہے۔ +**OutputGuardrail** - صارفین کو AI کے جوابات دیں جانے سے پہلے کی تصدیق کا انٹرفیس۔ -**Provider Safety Filters** - AI فراہم کنندگان (مثلاً GitHub ماڈلز) کی بلٹ-ان مواد فلٹرز جو API سطح پر خلاف ورزیوں کو پکڑتے ہیں۔ +**Provider Safety Filters** - AI فراہم کرنے والوں (مثلاً Azure OpenAI) کے بلٹ ان مواد کے فلٹر جو API سطح پر خلاف ورزی پکڑتے ہیں۔ -**Soft Refusal** - ماڈل مہذب انداز میں جواب دینے سے انکار کرتا ہے بغیر کسی ایرر کے۔ +**Soft Refusal** - ماڈل مؤدبانہ انکار کرتا ہے بغیر کسی ایرر کے۔ ## پرومپٹ انجینئرنگ - [ماڈیول 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - بہتر درستگی کے لیے مرحلہ وار دلیل۔ +**Chain-of-Thought** - بہتر درستگی کے لیے مرحلہ وار استدلال۔ -**Constrained Output** - مخصوص فارمیٹ یا ڈھانچہ لاگو کرنا۔ +**Constrained Output** - مخصوص فارمیٹ یا ساخت کی پابندی۔ -**High Eagerness** - GPT-5.2 کا پیٹرن جو مفصل دلیل کے لیے ہوتا ہے۔ +**High Eagerness** - GPT-5.2 پیٹرن جو جامع استدلال کے لیے ہے۔ -**Low Eagerness** - GPT-5.2 کا پیٹرن جو تیز جوابات کے لیے ہوتا ہے۔ +**Low Eagerness** - GPT-5.2 پیٹرن جو فوری جوابات کے لیے ہے۔ **Multi-Turn Conversation** - تبادلے کے دوران کانٹیکسٹ کو برقرار رکھنا۔ -**Role-Based Prompting** - ماڈل کی شخصیت سیٹنگ نظام پیغامات کے ذریعے۔ +**Role-Based Prompting** - ماڈل کی شخصیت کو سسٹم پیغامات کے ذریعے سیٹ کرنا۔ -**Self-Reflection** - ماڈل اپنی آؤٹ پٹ کا جائزہ لیتا اور بہتر بناتا ہے۔ +**Self-Reflection** - ماڈل اپنی آؤٹ پٹ کا جائزہ لے کر بہتری کرتا ہے۔ -**Structured Analysis** - مقررہ تشخیصی فریم ورک۔ +**Structured Analysis** - مقررہ جائزہ لینے کا فریم ورک۔ -**Task Execution Pattern** - منصوبہ بندی → عمل درآمد → خلاصہ۔ +**Task Execution Pattern** - منصوبہ بنائیں → عمل کریں → خلاصہ کریں۔ ## RAG (ریٹریول-آگمینٹڈ جنریشن) - [ماڈیول 03](../03-rag/README.md) -**دستاویز پراسیسنگ پائپ لائن** - لوڈ → چنک → ایمبیڈ → ذخیرہ۔ +**دستاویز پروسیسنگ پائپ لائن** - لوڈ کریں → چنک کریں → ایمبیڈ کریں → اسٹور کریں۔ **In-Memory Embedding Store** - غیر مستقل ذخیرہ ٹیسٹنگ کے لیے۔ -**RAG** - بازیافت کو جنریشن کے ساتھ ملا کر جوابات کو مستند بناتا ہے۔ +**RAG** - بازیافت اور جنریشن کو ملا کر جوابات کو حقیقی بنانا۔ **Similarity Score** - معنوی مماثلت کا پیمانہ (0-1)۔ -**Source Reference** - بازیافت کردہ مواد کی میٹا ڈیٹا۔ +**Source Reference** - بازیافت شدہ مواد کے بارے میں میٹا ڈیٹا۔ ## ایجنٹس اور ٹولز - [ماڈیول 04](../04-tools/README.md) -**@Tool انوٹیشن** - جاوا طریقوں کو AI کال ایبل ٹولز کے طور پر نشان زد کرتا ہے۔ +**@Tool اینوٹیشن** - جاوا میتھڈز کو AI کال کرنے والے ٹولز کے طور پر نشان زد کرتا ہے۔ -**ReAct پیٹرن** - دلیل → عمل → مشاہدہ → دہرائیں۔ +**ReAct پیٹرن** - استدلال کریں → عمل کریں → مشاہدہ کریں → دہراتے رہیں۔ -**Session Management** - مختلف صارفین کے لیے الگ الگ کانٹیکسٹس۔ +**سیشن مینجمنٹ** - مختلف صارفین کے لیے علیحدہ کانٹیکسٹس۔ -**ٹول** - فنکشن جسے AI ایجنٹ کال کر سکتا ہے۔ +**ٹول** - ایسا فنکشن جسے AI ایجنٹ کال کر سکتا ہے۔ -**Tool Description** - ٹول کے مقصد اور پیرامیٹرز کی دستاویزات۔ +**ٹول کی وضاحت** - ٹول کے مقصد اور پیرا میٹرز کی دستاویزی تفصیل۔ ## ایجنٹک ماڈیول - [ماڈیول 05](../05-mcp/README.md) -**@Agent انوٹیشن** - انٹرفیسز کو AI ایجنٹس کے طور پر ظاہر کرتا ہے جس میں طرز عمل کی وضاحت کی جاتی ہے۔ +**@Agent اینوٹیشن** - انٹرفیسز کو AI ایجنٹس کے طور پر نشان زد کرتا ہے جن میں بیانیہ طرز عمل کی تعریف ہوتی ہے۔ -**Agent Listener** - ایجنٹ کے عملدرآمد کی نگرانی کے لیے ہک، `beforeAgentInvocation()` اور `afterAgentInvocation()` کے ذریعے۔ +**Agent Listener** - `beforeAgentInvocation()` اور `afterAgentInvocation()` کے ذریعے ایجنٹ کی کارکردگی کی نگرانی کا ہُک۔ -**Agentic Scope** - مشترکہ میموری جہاں ایجنٹس اپنے نتائج `outputKey` کے ذریعے اسٹور کرتے ہیں تاکہ نیچے والے ایجنٹس استعمال کر سکیں۔ +**Agentic Scope** - مشترکہ میموری جہاں ایجنٹس اپنے آؤٹ پٹ کو `outputKey` کے ذریعے اسٹور کرتے ہیں تاکہ نیچے والے ایجنٹس استعمال کر سکیں۔ -**AgenticServices** - `agentBuilder()` اور `supervisorBuilder()` کے ذریعے ایجنٹس بنانے کی فیکٹری۔ +**AgenticServices** - ایجنٹس بنانے کے لیے فیکٹری جو `agentBuilder()` اور `supervisorBuilder()` فراہم کرتی ہے۔ -**Conditional Workflow** - شرائط کی بنیاد پر مختلف ماہر ایجنٹس کو راستہ دینا۔ +**Conditional Workflow** - شرائط کی بنیاد پر مختلف ماہر ایجنٹس کو راہنمائی کرنا۔ -**Human-in-the-Loop** - ورک فلو پیٹرن جس میں منظوری یا مواد کے جائزے کے لیے انسان شامل ہوتا ہے۔ +**Human-in-the-Loop** - ورک فلو پیٹرن جو منظوری یا مواد کے جائزے کے لیے انسانی چیک پوائنٹس شامل کرتا ہے۔ -**langchain4j-agentic** - ڈیکلریشن ایجنٹ بلڈنگ کے لیے Maven ڈپینڈنسی (تجرباتی)۔ +**langchain4j-agentic** - ڈیکلئریٹو ایجنٹ بنانے کے لیے میون انحصار (تجربی)۔ -**Loop Workflow** - ایجنٹ کے عملدرآمد کو دہرانا جب تک شرط پوری نہ ہو (مثلاً معیار کا سکور ≥ 0.8)۔ +**Loop Workflow** - ایجنٹ کی عمل کاری کو اس وقت تک دہرائیں جب تک شرط پوری نہ ہو جائے (مثلاً کوالٹی اسکور ≥ 0.8)۔ -**outputKey** - ایجنٹ انوٹیشن پیرامیٹر جو یہ تعین کرتا ہے کہ نتائج Agentic اسکاپ میں کہاں محفوظ ہوں گے۔ +**outputKey** - ایجنٹ اینوٹیشن پیرامیٹر جو بتاتا ہے کہ نتائج Agentic Scope میں کہاں محفوظ کیے جائیں۔ -**Parallel Workflow** - آزادانہ کاموں کے لیے ایک ساتھ متعدد ایجنٹس چلانا۔ +**Parallel Workflow** - متعدد ایجنٹس کو ایک ساتھ آزادانہ کاموں کے لیے چلائیں۔ -**Response Strategy** - نگران کس طرح حتمی جواب تشکیل دیتا ہے: LAST، SUMMARY، یا SCORED۔ +**Response Strategy** - سپروائزر کا طریقہ کار جو حتمی جواب تیار کرتا ہے: آخری، خلاصہ، یا اسکور شدہ۔ -**Sequential Workflow** - ایجنٹس کو ترتیب سے چلانا جہاں آؤٹ پٹ اگلے مرحلے میں جاتا ہے۔ +**Sequential Workflow** - ایجنٹس کو ترتیب وار چلائیں جہاں آؤٹ پٹ اگلے مرحلے کو پہنچے۔ -**Supervisor Agent Pattern** - اعلی سطحی ایجنٹک پیٹرن جہاں نگران LLM متحرک طور پر فیصلہ کرتا ہے کہ کون سے سب-ایجنٹس کو کال کرنا ہے۔ +**Supervisor Agent Pattern** - ایک ترقی یافتہ ایجنٹک پیٹرن جہاں سپروائزر LLM متحرک طور پر فیصلہ کرتا ہے کہ کون سے ذیلی ایجنٹس کو بلانا ہے۔ ## ماڈل کانٹیکسٹ پروٹوکول (MCP) - [ماڈیول 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j میں MCP کے انضمام کے لیے Maven ڈپینڈنسی۔ +**langchain4j-mcp** - LangChain4j میں MCP انٹیگریشن کے لیے میون انحصار۔ -**MCP** - ماڈل کانٹیکسٹ پروٹوکول: AI ایپس کو بیرونی ٹولز سے مربوط کرنے کا معیار۔ ایک بار بنائیں، ہر جگہ استعمال کریں۔ +**MCP** - ماڈل کانٹیکسٹ پروٹوکول: AI درخواستوں کو بیرونی ٹولز سے جوڑنے کا معیار۔ ایک بار بنائیں، ہر جگہ استعمال کریں۔ -**MCP کلائنٹ** - ایپلیکیشن جو MCP سرورز سے ٹولز دریافت اور استعمال کے لیے جڑتی ہے۔ +**MCP کلائنٹ** - ایسی درخواست جو MCP سرورز سے کنیکٹ ہو کر ٹولز دریافت اور استعمال کرتی ہے۔ **MCP سرور** - ایسی سروس جو MCP کے ذریعے ٹولز کو واضح وضاحتوں اور پیرامیٹر اسکیموں کے ساتھ فراہم کرتی ہے۔ -**McpToolProvider** - LangChain4j جزو جو MCP ٹولز کو AI سروسز اور ایجنٹس میں استعمال کے لیے لپیٹتا ہے۔ +**McpToolProvider** - LangChain4j جزو جو MCP ٹولز کو AI سروسز اور ایجنٹس کے استعمال کے لیے لپیٹتا ہے۔ -**McpTransport** - MCP مواصلات کے لیے انٹرفیس۔ نفاذ میں Stdio اور HTTP شامل ہیں۔ +**McpTransport** - MCP کمیونیکیشن کا انٹرفیس۔ نفاذ میں Stdio اور HTTP شامل ہیں۔ -**Stdio ٹرانسپورٹ** - stdin/stdout کے ذریعے مقامی عمل کی ترسیل۔ فائل سسٹم تک رسائی یا کمانڈ لائن ٹولز کے لیے مفید۔ +**Stdio ٹرانسپورٹ** - stdin/stdout کے ذریعے لوکل پراسس ٹرانسپورٹ۔ فائل سسٹم رسائی یا کمانڈ لائن ٹولز کے لیے مفید۔ **StdioMcpTransport** - LangChain4j کا نفاذ جو MCP سرور کو subprocess کے طور پر چلاتا ہے۔ -**Tool Discovery** - کلائنٹ دستیاب ٹولز کے لیے سرور سے وضاحتیں اور اسکیمیں پوچھتا ہے۔ +**ٹول دریافت** - کلائنٹ سرور سے دستیاب ٹولز کی وضاحت اور اسکیمہ کے لیے پوچھتا ہے۔ -## ایزور خدمات - [ماڈیول 01](../01-introduction/README.md) +## ایژور سروسز - [ماڈیول 01](../01-introduction/README.md) **Azure AI Search** - ویکٹر صلاحیتوں کے ساتھ کلاؤڈ سرچ۔ [ماڈیول 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - ایزور وسائل کو تعینات کرتا ہے۔ +**Azure Developer CLI (azd)** - Azure وسائل کی تعیناتی۔ **Azure OpenAI** - مائیکروسافٹ کی انٹرپرائز AI سروس۔ -**Bicep** - ایزور انفراسٹرکچر ایز کوڈ زبان۔ [انفراسٹرکچر گائیڈ](../01-introduction/infra/README.md) +**Bicep** - Azure انفراسٹرکچر بحیثیت کوڈ زبان۔ [انفراسٹرکچر گائیڈ](../01-introduction/infra/README.md) -**Deployment Name** - ایزور میں ماڈل تعیناتی کا نام۔ +**ڈیپلائمنٹ کا نام** - Azure میں ماڈل کی تعیناتی کا نام۔ -**GPT-5.2** - تازہ ترین OpenAI ماڈل جس میں دلیل کی کنٹرول شامل ہے۔ [ماڈیول 02](../02-prompt-engineering/README.md) +**GPT-5.2** - جدید ترین OpenAI ماڈل جس میں استدلالی کنٹرول ہے۔ [ماڈیول 02](../02-prompt-engineering/README.md) ## ٹیسٹنگ اور ڈیولپمنٹ - [ٹیسٹنگ گائیڈ](TESTING.md) -**دیولپمنٹ کنٹینر** - کنٹینرائزڈ ڈیولپمنٹ ماحول۔ [ترتیب](../../../.devcontainer/devcontainer.json) - -**GitHub ماڈلز** - مفت AI ماڈل پلے گراؤنڈ۔ [ماڈیول 00](../00-quick-start/README.md) +**Dev Container** - کنٹینرائزڈ ڈیولپمنٹ ماحول۔ [کنفیگریشن](../../../.devcontainer/devcontainer.json) **In-Memory Testing** - ان میموری اسٹوریج کے ساتھ ٹیسٹنگ۔ -**انٹیگریشن ٹیسٹنگ** - حقیقی انفراسٹرکچر کے ساتھ ٹیسٹنگ۔ +**Integration Testing** - حقیقی انفراسٹرکچر کے ساتھ ٹیسٹنگ۔ **Maven** - جاوا بلڈ آٹومیشن ٹول۔ -**Mockito** - جاوا موکنگ فریم ورک۔ +**Mockito** - جاوا ماکنگ فریم ورک۔ **Spring Boot** - جاوا ایپلیکیشن فریم ورک۔ [ماڈیول 01](../01-introduction/README.md) --- -**دستخطی بیان**: -یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کا استعمال کرتے ہوئے ترجمہ کی گئی ہے۔ ہم درستگی کے لیے کوشش کرتے ہیں، لیکن براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا غیر درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنی مادری زبان میں ہی معتبر ذریعہ سمجھی جانی چاہیے۔ اہم معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ ہم اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کے ذمہ دار نہیں ہیں۔ +**ڈس کلیمر**: +یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔ \ No newline at end of file diff --git a/translations/ur/docs/TESTING.md b/translations/ur/docs/TESTING.md index a79957d60..65b962046 100644 --- a/translations/ur/docs/TESTING.md +++ b/translations/ur/docs/TESTING.md @@ -1,20 +1,20 @@ -# LangChain4j ایپلیکیشنز کی جانچ +# LangChain4j ایپلی کیشنز کی ٹیسٹنگ -## فہرست مضامین +## جدولِ مندرجات -- [جلدی شروع کریں](../../../docs) -- [ٹیسٹ کیا شامل کرتے ہیں](../../../docs) -- [ٹیسٹ چلانا](../../../docs) -- [VS کوڈ میں ٹیسٹ چلانا](../../../docs) -- [جانچ کے نمونے](../../../docs) -- [جانچ کا فلسفہ](../../../docs) -- [اگلے اقدامات](../../../docs) +- [جلدی شروع کریں](#جلدی-شروع-کریں) +- [ٹیسٹس میں کیا شامل ہے](#ٹیسٹس-میں-کیا-شامل-ہے) +- [ٹیسٹس چلانا](#ٹیسٹس-چلانا) +- [VS کوڈ میں ٹیسٹس چلانا](#vs-کوڈ-میں-ٹیسٹس-چلانا) +- [ٹیسٹنگ کے نمونے](#ٹیسٹنگ-کے-نمونے) +- [ٹیسٹنگ کا فلسفہ](#ٹیسٹنگ-کا-فلسفہ) +- [اگلے مراحل](#اگلے-مراحل) -یہ رہنما آپ کو ان ٹیسٹوں سے گزارتا ہے جو یہ ظاہر کرتے ہیں کہ AI ایپلیکیشنز کو API کیز یا بیرونی خدمات کی ضرورت کے بغیر کیسے ٹیسٹ کیا جائے۔ +یہ گائیڈ آپ کو ان ٹیسٹس کے ذریعے لے جاتا ہے جو یہ دکھاتے ہیں کہ AI ایپلی کیشنز کو API کیز یا بیرونی سروسز کے بغیر کیسے ٹیسٹ کیا جا سکتا ہے۔ ## جلدی شروع کریں -تمام ٹیسٹ ایک ہی کمانڈ سے چلائیں: +تمام ٹیسٹس ایک ہی کمانڈ سے چلائیں: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -جب تمام ٹیسٹ کامیابی سے گزرتے ہیں، تو آپ کو نیچے دی گئی اسکرین شاٹ جیسا نتیجہ دیکھنا چاہیے — ٹیسٹ صفر نقص کے ساتھ چلتے ہیں۔ +جب تمام ٹیسٹ کامیاب ہو جائیں، تو اسکرین شاٹ کی طرح آؤٹ پٹ نظر آئے گا — ٹیسٹ صفر نقص کے ساتھ چلیں گے۔ -کامیاب ٹیسٹ کے نتائج +Successful Test Results -*کامیاب ٹیسٹ نفاذ دکھا رہا ہے تمام ٹیسٹ صفر ناکامی کے ساتھ پاس ہو رہے ہیں* +*کامیاب ٹیسٹ کا نتیجہ جو تمام ٹیسٹس کے بغیر نقص کے گزرنے کو ظاہر کرتا ہے* -## ٹیسٹ کیا شامل کرتے ہیں +## ٹیسٹس میں کیا شامل ہے -یہ کورس **یونٹ ٹیسٹ** پر مرکوز ہے جو مقامی طور پر چلتے ہیں۔ ہر ٹیسٹ ایک مخصوص LangChain4j تصور کو الگ تھلگ دکھاتا ہے۔ نیچے دی گئی جانچ پائرمیڈ دکھاتی ہے کہ یونٹ ٹیسٹ کہاں فٹ بیٹھتے ہیں — یہ آپ کی باقی ٹیسٹنگ حکمت عملی کے لیے تیز، قابل اعتماد بنیاد فراہم کرتے ہیں۔ +یہ کورس **یونٹ ٹیسٹس** پر مرکوز ہے جو مقامی طور پر چلتے ہیں۔ ہر ٹیسٹ ایک مخصوص LangChain4j تصور کو الگ تھلگ ظاہر کرتا ہے۔ نیچے دیا گیا ٹیسٹنگ پیرامیڈ یہ دکھاتا ہے کہ یونٹ ٹیسٹس کہاں فٹ ہوتے ہیں — یہ تیز، قابل اعتماد بنیاد فراہم کرتے ہیں جس پر آپ کی باقی ٹیسٹنگ حکمت عملی قائم ہوتی ہے۔ -جانچ کا پائرمیڈ +Testing Pyramid -*جانچ کا پائرمیڈ یونٹ ٹیسٹ (تیز، الگ تھلگ)، انٹیگریشن ٹیسٹ (حقیقی اجزاء)، اور اینڈ ٹو اینڈ ٹیسٹ کے درمیان توازن دکھا رہا ہے۔ یہ تربیت یونٹ ٹیسٹنگ پر محیط ہے۔* +*ٹیسٹنگ پیرامیڈ جو یونٹ ٹیسٹس (تیز، الگ تھلگ)، انٹیگریشن ٹیسٹس (حقیقی اجزاء)، اور اینڈ ٹو اینڈ ٹیسٹس کے درمیان توازن دکھاتا ہے۔ یہ تربیت یونٹ ٹیسٹنگ کا احاطہ کرتی ہے۔* -| ماڈیول | ٹیسٹ | توجہ مرکوز | اہم فائلیں | +| ماڈیول | ٹیسٹس | توجہ | اہم فائلز | |--------|-------|-------|-----------| -| **00 - جلدی شروع کریں** | 6 | پرامپٹ ٹیمپلیٹس اور متغیر تبدیلی | `SimpleQuickStartTest.java` | -| **01 - تعارف** | 8 | گفتگو کی یادداشت اور ریاستی چیٹ | `SimpleConversationTest.java` | -| **02 - پرامپٹ انجینئرنگ** | 12 | GPT-5.2 پیٹرنز، خواہش کی سطحیں، ساخت شدہ آؤٹ پٹ | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | دستاویزات کی انٹیک، ایمبیڈنگز، مماثلت کی تلاش | `DocumentServiceTest.java`` | +| **01 - تعارف** | 8 | بات چیت کی میموری اور حیثیت والا چیٹ | `SimpleConversationTest.java` | +| **02 - پرامپٹ انجنیئرنگ** | 12 | GPT-5.2 پیٹرنز، جوش کی سطحیں، منظم آؤٹ پٹ | `SimpleGpt5PromptTest.java` | +| **03 - رَیگ** | 10 | دستاویز اندراج، ایمبیڈنگز، مماثلت کی تلاش | `DocumentServiceTest.java` | | **04 - ٹولز** | 12 | فنکشن کالنگ اور ٹول چیننگ | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | ماڈل کانٹیکسٹ پروٹوکول stdio ٹرانسپورٹ کے ساتھ | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | ماڈل کانٹیکسٹ پروٹوکول استـعمال کرتے ہوئے Stdio ٹرانسپورٹ | `SimpleMcpTest.java` | -## ٹیسٹ چلانا +## ٹیسٹس چلانا -**روٹ سے تمام ٹیسٹ چلائیں:** +**سب ٹیسٹس روٹ سے چلائیں:** **Bash:** ```bash @@ -63,12 +62,12 @@ mvn test mvn --% test ``` -**مخصوص ماڈیول کے ٹیسٹ چلائیں:** +**مخصوص ماڈیول کے لیے ٹیسٹس چلائیں:** **Bash:** ```bash cd 01-introduction && mvn test -# یا جڑ سے +# یا روٹ سے mvn test -pl 01-introduction ``` @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**ایک واحد ٹیسٹ کلاس چلائیں:** +**ایک ٹیسٹ کلاس چلائیں:** **Bash:** ```bash @@ -95,41 +94,41 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#گفتگو کی تاریخ کو برقرار رکھنا چاہیے +mvn test -Dtest=SimpleConversationTest#کیا گفتگو کی تاریخ برقرار رکھنی چاہیے ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#گفتگو کی تاریخ کو برقرار رکھنا چاہیے +mvn --% test -Dtest=SimpleConversationTest#گفتگو کی تاریخ کو برقرار رکھنا چاہئے ``` -## VS کوڈ میں ٹیسٹ چلانا +## VS کوڈ میں ٹیسٹس چلانا -اگر آپ Visual Studio Code استعمال کر رہے ہیں، تو Test Explorer ٹیسٹ چلانے اور ڈیبگ کرنے کے لیے گرافیکل انٹرفیس مہیا کرتا ہے۔ +اگر آپ Visual Studio Code استعمال کر رہے ہیں، تو Test Explorer ٹیسٹس کو چلانے اور ڈیبگ کرنے کے لیے گرافیکل انٹرفیس فراہم کرتا ہے۔ -VS کوڈ ٹیسٹ ایکسپلورر +VS Code Test Explorer -*VS کوڈ ٹیسٹ ایکسپلورر ٹیسٹ ٹری دکھا رہا ہے جس میں تمام جاوا ٹیسٹ کلاسز اور انفرادی ٹیسٹ میتھڈز موجود ہیں* +*VS کوڈ ٹیسٹ ایکسپلورر میں تمام جاوا ٹیسٹ کلاسز اور انفرادی ٹیسٹ میتھڈز کے ساتھ ٹیسٹ ٹری دکھائی دے رہا ہے* -**VS کوڈ میں ٹیسٹ چلانے کے لیے:** +**VS کوڈ میں ٹیسٹس چلانے کے لیے:** -1. ایکٹیویٹی بار میں بیکر آئیکن پر کلک کرکے Test Explorer کھولیں -2. تمام ماڈیولز اور ٹیسٹ کلاسز دیکھنے کے لیے ٹیسٹ ٹری کو پھیلائیں -3. کسی بھی ٹیسٹ کے ساتھ پلے بٹن پر کلک کرکے اسے الگ سے چلائیں -4. "Run All Tests" پر کلک کرکے پوری سُوٹ چلائیں -5. کسی بھی ٹیسٹ پر رائٹ کلک کرکے "Debug Test" منتخب کریں تاکہ بریک پوائنٹس سیٹ کر کے کوڈ میں قدم بہ قدم جائیں +1. فعالیت بار میں بیكر آئیکون پر کلک کر کے Test Explorer کھولیں +2. ٹیسٹ ٹری کو وسعت دیں تاکہ تمام ماڈیولز اور ٹیسٹ کلاسز دیکھ سکیں +3. کسی بھی ٹیسٹ کے ساتھ پلے بٹن پر کلک کریں تاکہ اسے الگ چلایا جا سکے +4. "Run All Tests" پر کلک کریں تاکہ پوری سوئیٹ چلائی جا سکے +5. کسی بھی ٹیسٹ پر رائٹ کلک کر کے "Debug Test" منتخب کریں تاکہ بریک پوائنٹس سیٹ کر کے کوڈ میں قدم بہ قدم جا سکیں -Test Explorer پاس ہونے والے ٹیسٹوں کے لیے سبز نشانیاں دکھاتا ہے اور ناکام ہونے پر تفصیلی نقص پیغامات دیتا ہے۔ +Test Explorer کامیاب ٹیسٹس کے لیے سبز چیک مارکس دکھاتا ہے اور ناکامی کی صورت میں تفصیلی پیغام فراہم کرتا ہے۔ -## جانچ کے نمونے +## ٹیسٹنگ کے نمونے -### نمونہ 1: پرامپٹ ٹیمپلیٹ کی جانچ +### پیٹرن 1: پرامپٹ ٹیمپلیٹس کی جانچ -سب سے آسان نمونہ پرامپٹ ٹیمپلیٹس کو AI ماڈل کو کال کیے بغیر ٹیسٹ کرتا ہے۔ آپ تصدیق کرتے ہیں کہ متغیرات کی تبدیلی صحیح کام کر رہی ہے اور پرامپٹس متوقع انداز میں فارمیٹ ہوئے ہیں۔ +سب سے آسان پیٹرن پرامپٹ ٹیمپلیٹس کو بغير AI ماڈل کال کیے ٹیسٹ کرتا ہے۔ آپ تصدیق کرتے ہیں کہ ویری ایبل کی جگہ صحیح طریقے سے تبدیل ہو رہی ہے اور پرامپٹس مطلوبہ فارمیٹ میں ہیں۔ -پرامپٹ ٹیمپلیٹ کی جانچ +Prompt Template Testing -*پرامپٹ ٹیمپلیٹس کی جانچ دکھا رہی ہے متغیر تبدیلی کا عمل: پلیس ہولڈرز کے ساتھ ٹیمپلیٹ → اقدار کا اطلاق → فارمیٹ شدہ نتیجہ کی تصدیق* +*پرامپٹ ٹیمپلیٹس کی ٹیسٹنگ جو متغیر جگہوں کی تبدیلی کے بہاؤ کو دکھاتی ہے: ٹیمپلیٹ جس میں جگہ دار → اقدار کا اطلاق → فارمیٹ شدہ آؤٹ پٹ کی تصدیق* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -یہ ٹیسٹ `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java` میں ہے۔ - -**چلائیں:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#ٹیسٹ پرامپٹ ٹیمپلیٹ کی فارمیٹنگ -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#ٹیسٹ پرامپٹ ٹیمپلیٹ کی ترتیب -``` +یہ پیٹرن تصدیق کرتا ہے کہ ویری ایبل کی جگہ صحیح کام کرتی ہے اور پرامپٹس متوقع فارمیٹ میں ہیں — کوئی API کی یا ماڈل کال درکار نہیں۔ -### نمونہ 2: زبان کے ماڈلز کی موکنگ +### پیٹرن 2: زبان کے ماڈلز کا مَک کرنا -جب گفتگو کے منطق کو ٹیسٹ کریں، تو Mockito استعمال کریں جعلی ماڈلز بنانے کے لیے جو متعین جوابات واپس دیتے ہیں۔ اس سے ٹیسٹ تیز، مفت، اور قطعی ہو جاتے ہیں۔ +بات چیت کے منطق کی جانچ کرتے وقت، Mockito استعمال کریں تاکہ جعلی ماڈلز بنائیں جو پہلے سے طے شدہ جوابات واپس کریں۔ اس سے ٹیسٹس تیز، مفت، اور یقینی بنتے ہیں۔ -موک اور اصلی API کا موازنہ +Mock vs Real API Comparison -*موازنہ دکھا رہا ہے کہ ٹیسٹنگ کے لیے موکس کیوں ترجیح دی جاتی ہیں: یہ تیز، مفت، قطعی ہیں اور API کیز کی ضرورت نہیں ہوتی* +*موازنہ جو دکھاتا ہے کہ ٹیسٹنگ کے لیے مکس کیوں ترجیح دی جاتی ہے: یہ تیز، مفت، یقینی اور API کیز کے بغیر ہوتی ہے* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 صارف + 3 اے آئی پیغامات + assertThat(history).hasSize(6); // ۳ صارف + ۳ اے آئی پیغامات } } ``` -یہ نمونہ `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` میں ہے۔ موک مستقل رویہ یقینی بناتا ہے تاکہ آپ تصدیق کر سکیں کہ میموری کا انتظام صحیح ہے۔ +یہ پیٹرن `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` میں موجود ہے۔ مَک مسلسل برتاؤ کو یقینی بناتا ہے تاکہ آپ میموری مینجمنٹ کو صحیح طریقے سے جانچ سکیں۔ -### نمونہ 3: گفتگو کی علیحدگی کی جانچ +### پیٹرن 3: بات چیت کی علیحدگی کی جانچ -گفتگو کی یادداشت کو متعدد صارفین کو الگ رکھنا چاہیے۔ یہ ٹیسٹ تصدیق کرتا ہے کہ گفتگو کے متن آپس میں مکس نہیں ہوتے۔ +بات چیت کی میموری کو متعدد صارفین کو الگ رکھنا چاہیے۔ یہ ٹیسٹ تصدیق کرتا ہے کہ بات چیت کے سیاق و سباق مکس نہیں ہوتے۔ -گفتگو کی علیحدگی +Conversation Isolation -*گفتگو کی علیحدگی کی جانچ دکھا رہی ہے کہ مختلف صارفین کے لیے علیحدہ یادداشتیں اس لیے کہ سیاق و سباق مکس نہ ہو* +*بات چیت کی علیحدگی کی ٹیسٹنگ جو مختلف صارفین کے لیے علیحدہ میموری اسٹورز دکھاتی ہے تاکہ سیاق و سباق کی مِکسنگ روکی جا سکے* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -ہر گفتگو اپنی آزاد تاریخ رکھتی ہے۔ پروڈکشن سسٹمز میں یہ علیحدگی کثیر صارف ایپلیکیشنز کے لیے نہایت اہم ہے۔ +ہر بات چیت اپنی آزاد تاریخ رکھتی ہے۔ پروڈکشن سسٹمز میں، یہ علیحدگی ملٹی یوزر ایپلی کیشنز کے لیے انتہائی اہم ہے۔ -### نمونہ 4: ٹولز کی آزادانہ جانچ +### پیٹرن 4: ٹولز کی آزادانہ ٹیسٹنگ -ٹولز وہ فنکشنز ہیں جنہیں AI کال کر سکتا ہے۔ انہیں براہ راست ٹیسٹ کریں تاکہ یہ یقینی بنایا جا سکے کہ وہ AI کے فیصلوں سے قطع نظر صحیح کام کر رہے ہیں۔ +ٹولز فنکشنز ہوتے ہیں جنہیں AI کال کر سکتا ہے۔ انہیں براہِ راست ٹیسٹ کریں تاکہ یقین ہو کہ وہ AI فیصلوں سے قطع نظر صحیح کام کر رہے ہیں۔ -ٹولز کی جانچ +Tools Testing -*ٹولز کی آزادانہ جانچ دکھا رہی ہے موک ٹول کا نفاذ بغیر AI کال کے کاروباری منطق کی تصدیق کے لیے* +*ٹولز کی آزادانہ ٹیسٹنگ جو AI کالز کے بغیر مَک ٹول ایگزیکیوشن دکھاتی ہے تاکہ کاروباری منطق کی تصدیق کی جا سکے* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -یہ ٹیسٹ `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` سے ہیں جو AI مداخلت کے بغیر ٹول منطق کی توثیق کرتے ہیں۔ چیننگ کی مثال دکھاتی ہے کہ کس طرح ایک ٹول کی آؤٹ پٹ دوسرے کے ان پٹ میں جاتی ہے۔ +یہ ٹیسٹس `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` سے ہیں جو AI مداخلت کے بغیر ٹول منطق کی توثیق کرتے ہیں۔ چیننگ کی مثال دکھاتی ہے کہ کس طرح ایک ٹول کا آؤٹ پٹ دوسرے کے ان پٹ میں جاتا ہے۔ -### نمونہ 5: ان-میموری RAG ٹیسٹنگ +### پیٹرن 5: ان میموری RAG ٹیسٹنگ -RAG سسٹمز روایتی طور پر ویکٹر ڈیٹابیسز اور ایمبیڈنگ سروسز کا تقاضا کرتے ہیں۔ ان-میموری نمونہ آپ کو بغیر بیرونی انحصار کے پوری پائپ لائن ٹیسٹ کرنے دیتا ہے۔ +رَیگ سسٹمز روایتی طور پر ویکٹر ڈیٹابیسز اور ایمبیڈنگ سروسز کا تقاضا کرتے ہیں۔ ان میموری پیٹرن آپ کو پورے پائپ لائن کو بیرونی انحصار کے بغیر ٹیسٹ کرنے دیتا ہے۔ -ان-میموری RAG ٹیسٹنگ +In-Memory RAG Testing -*ان-میموری RAG ٹیسٹنگ ورک فلو دکھا رہا ہے دستاویز کی تجزیہ، ایمبیڈنگ اسٹوریج، اور مماثلت کی تلاش بغیر ڈیٹابیس کی ضرورت* +*ان میموری رَیگ ٹیسٹنگ ورک فلو جو دستاویز کی پارسنگ، ایمبیڈنگ اسٹوریج، اور مماثلت کی تلاش بغیر ڈیٹابیس کی ضرورت کے دکھاتا ہے* ```java @Test @@ -308,11 +295,11 @@ void testProcessTextDocument() { یہ ٹیسٹ `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` میں ہے جو دستاویز کو میموری میں بناتا ہے اور چنکنگ اور میٹا ڈیٹا ہینڈلنگ کی تصدیق کرتا ہے۔ -### نمونہ 6: MCP انٹیگریشن ٹیسٹنگ +### پیٹرن 6: MCP انٹیگریشن ٹیسٹنگ -MCP ماڈیول ماڈل کانٹیکسٹ پروٹوکول کی انٹیگریشن stdio ٹرانسپورٹ کے ساتھ ٹیسٹ کرتا ہے۔ یہ ٹیسٹ اس بات کی تصدیق کرتے ہیں کہ آپ کی ایپلیکیشن MCP سرورز کو بطور subprocess پیدا کر کے مواصلت کر سکتی ہے۔ +MCP ماڈیول ماڈل کانٹیکسٹ پروٹوکول انٹیگریشن کو stdio ٹرانسپورٹ استعمال کرتے ہوئے ٹیسٹ کرتا ہے۔ یہ ٹیسٹس یہ دیکھتے ہیں کہ آپ کی ایپلیکیشن MCP سرورز کو subprocess کی طرح اسپان کر کے ان سے بات چیت کر سکتی ہے یا نہیں۔ -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` میں ٹیسٹ MCP کلائنٹ کے رویے کی توثیق کرتے ہیں۔ +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` میں یہ ٹیسٹس MCP کلائنٹ کے رویے کی توثیق کرتے ہیں۔ **انہیں چلائیں:** @@ -326,38 +313,37 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## جانچ کا فلسفہ +## ٹیسٹنگ کا فلسفہ -اپنا کوڈ ٹیسٹ کریں، AI کو نہیں۔ آپ کے ٹیسٹ اس کوڈ کو درست ثابت کرنے چاہئیں جو آپ لکھتے ہیں، یہ دیکھ کر کہ پرامپٹس کیسے بنائے جاتے ہیں، میموری کیسے مینیج کی جاتی ہے، اور ٹولز کیسے چلتے ہیں۔ AI کے جوابات مختلف ہو سکتے ہیں اور انہیں ٹیسٹ کے دعووں کا حصہ نہیں ہونا چاہیے۔ اپنے آپ سے پوچھیں کہ آیا آپ کا پرامپٹ ٹیمپلیٹ متغیرات کو صحیح طریقے سے بدل رہا ہے، نہ کہ AI صحیح جواب دے رہا ہے یا نہیں۔ +اپنا کوڈ ٹیسٹ کریں، AI کو نہیں۔ آپ کے ٹیسٹس آپ کے لکھے ہوئے کوڈ کی تصدیق کریں کہ کس طرح پرامپٹس بنائے جاتے ہیں، میموری کو کیسے منظم کیا جاتا ہے، اور ٹولز کیسے چلتے ہیں۔ AI کے جوابات متغیر ہوتے ہیں اور انہیں ٹیسٹ اسیرشنز کا حصہ نہیں ہونا چاہیے۔ اپنے آپ سے پوچھیں کہ کیا آپ کا پرامپٹ ٹیمپلیٹ صحیح طریقے سے ویری ایبلز کو بدلا ہے، نہ کہ AI صحیح جواب دے رہا ہے۔ -زبان کے ماڈلز کے لیے موکس استعمال کریں۔ وہ بیرونی انحصارات ہیں جو سست، مہنگے، اور غیر قطعی ہوتے ہیں۔ موکنگ ٹیسٹ کو سیکنڈز کی بجائے ملی سیکنڈز میں تیز، مفت اور ہر بار ایک جیسے نتائج فراہم کرتی ہے۔ +زبان کے ماڈلز کے لیے مَک استعمال کریں۔ یہ بیرونی انحصار ہوتے ہیں جو سست، مہنگے، اور غیر یقینی ہوتے ہیں۔ مَکنگ سے ٹیسٹس سیکنڈز کی جگہ ملی سیکنڈز میں تیز، بغیر API اخراجات کے مفت، اور ہر بار ایک جیسا نتیجہ دینے والے یقینی بنتے ہیں۔ -ٹیسٹوں کو خودمختار رکھیں۔ ہر ٹیسٹ اپنا ڈیٹا تیار کرے، دوسرے ٹیسٹوں پر انحصار نہ کرے، اور اپنے بعد صفائی کرے۔ ٹیسٹوں کو کرانے کے حکم سے قطع نظر کامیاب ہونا چاہیے۔ +ٹیسٹس کو آزاد رکھیں۔ ہر ٹیسٹ اپنی ڈیٹا خود سیٹ کرے، دوسرے ٹیسٹس پر انحصار نہ کرے، اور اپنے بعد صفائی کرے۔ ٹیسٹس چاہے کسی بھی ترتیب میں چلیں، کامیاب ہونا چاہیے۔ -خوشگوار راستے سے آگے کنارے کے کیسز ٹیسٹ کریں۔ خالی ان پٹ، بہت بڑے ان پٹ، خاص کردار، غلط پیرا میٹرز، اور بارڈر کنڈیشنز آزمائیں۔ یہ اکثر وہ بگ ظاہر کرتے ہیں جو عام استعمال میں نہیں نکلتے۔ +خوشگوار راستے سے آگے کناروں کے معاملات کی جانچ کریں۔ خالی ان پٹ، بہت بڑے ان پٹ، خاص کریکٹرز، غلط پیرامیٹرز، اور حد بندی کی حالتیں آزمائیں۔ یہ اکثر ایسے بگز کو ظاہر کرتے ہیں جو معمول کے استعمال میں سامنے نہیں آتے۔ -تشریحی نام استعمال کریں۔ `shouldMaintainConversationHistoryAcrossMultipleMessages()` کا موازنہ کریں `test1()` سے۔ پہلا آپ کو بالکل بتاتا ہے کہ کیا ٹیسٹ ہو رہا ہے، جو ناکامی کی ڈیبگنگ کو آسان بناتا ہے۔ +وضاحتی ناموں کا استعمال کریں۔ مثلا `shouldMaintainConversationHistoryAcrossMultipleMessages()` کو `test1()` کے بجائے دیکھیں۔ پہلا نام آپ کو بالکل بتاتا ہے کہ کیا ٹیسٹ ہو رہا ہے، جس سے خرابیاں تلاش کرنا آسان ہو جاتا ہے۔ -## اگلے اقدامات +## اگلے مراحل -اب جب آپ جانچ کے نمونوں کو سمجھ گئے ہیں، تو ہر ماڈیول میں مزید گہرائی میں جائیں: +اب جب آپ ٹیسٹنگ کے نمونوں کو سمجھ گئے ہیں، ہر ماڈیول میں گہرائی سے جائیں: -- **[00 - جلدی شروع کریں](../00-quick-start/README.md)** - پرامپٹ ٹیمپلیٹ کی بنیادی باتوں سے شروع کریں -- **[01 - تعارف](../01-introduction/README.md)** - گفتگو کی یادداشت کا انتظام سیکھیں -- **[02 - پرامپٹ انجینئرنگ](../02-prompt-engineering/README.md)** - GPT-5.2 کے پرامپٹنگ پیٹرنز میں مہارت حاصل کریں -- **[03 - RAG](../03-rag/README.md)** - بازیافت سے بڑھا ہوا جنریشن سسٹمز بنائیں -- **[04 - ٹولز](../04-tools/README.md)** - فنکشن کالنگ اور ٹول چینز کو نافذ کریں -- **[05 - MCP](../05-mcp/README.md)** - ماڈل کانٹیکسٹ پروٹوکول کو انٹیگریٹ کریں +- **[01 - تعارف](../01-introduction/README.md)** - بات چیت کی میموری مینجمنٹ سیکھیں +- **[02 - پرامپٹ انجنیئرنگ](../02-prompt-engineering/README.md)** - GPT-5.2 پرامپٹنگ پیٹرنز میں مہارت حاصل کریں +- **[03 - رَیگ](../03-rag/README.md)** - رٹریول آگمینٹڈ جنریشن سسٹمز بنائیں +- **[04 - ٹولز](../04-tools/README.md)** - فنکشن کالنگ اور ٹول چینز لاگو کریں +- **[05 - MCP](../05-mcp/README.md)** - ماڈل کانٹیکسٹ پروٹوکول انٹیگریٹ کریں ہر ماڈیول کی README یہاں ٹیسٹ کیے گئے تصورات کی تفصیلی وضاحت فراہم کرتی ہے۔ --- -**رہنمائی:** [← مرکزی صفحہ پر واپس جائیں](../README.md) +**نیویگیشن:** [← مرکزی صفحے پر واپس جائیں](../README.md) --- -**ڈس کلیمر**: -اس دستاویز کا ترجمہ AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے کیا گیا ہے۔ اگرچہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات کا خیال رکھیں کہ خودکار ترجمے میں غلطیاں یا نقائص ہو سکتے ہیں۔ اصل دستاویز اپنی مادری زبان میں معتبر ماخذ سمجھا جائے گا۔ اہم معلومات کے لیے پیشہ ورانہ انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے ہونے والی کسی بھی غلط فہمی یا بدفہمی کی ذمہ داری ہم پر عائد نہیں ہوتی۔ +**ڈس کلیمر**: +یہ دستاویز AI ترجمہ سروس [Co-op Translator](https://github.com/Azure/co-op-translator) کے ذریعے ترجمہ کی گئی ہے۔ جبکہ ہم درستگی کے لیے کوشاں ہیں، براہ کرم اس بات سے آگاہ رہیں کہ خودکار ترجمے میں غلطیاں یا عدم درستیاں ہو سکتی ہیں۔ اصل دستاویز اپنے مادری زبان میں مستند ماخذ سمجھی جائے گی۔ حساس معلومات کے لیے پیشہ ور انسانی ترجمہ کی سفارش کی جاتی ہے۔ اس ترجمے کے استعمال سے پیدا ہونے والی کسی بھی غلط فہمی یا غلط تشریح کی ذمہ داری ہم قبول نہیں کرتے۔ \ No newline at end of file diff --git a/translations/vi/.co-op-translator.json b/translations/vi/.co-op-translator.json index 3c3fed1e4..513726e03 100644 --- a/translations/vi/.co-op-translator.json +++ b/translations/vi/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "vi" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-03T03:22:59+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T08:38:43+00:00", "source_file": "01-introduction/README.md", "language_code": "vi" }, @@ -18,20 +18,20 @@ "language_code": "vi" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-03T03:25:15+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T08:33:47+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "vi" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-03T03:26:40+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T08:37:48+00:00", "source_file": "03-rag/README.md", "language_code": "vi" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T10:02:12+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T08:36:21+00:00", "source_file": "04-tools/README.md", "language_code": "vi" }, @@ -54,8 +54,8 @@ "language_code": "vi" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T17:12:35+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T08:32:13+00:00", "source_file": "README.md", "language_code": "vi" }, @@ -72,14 +72,14 @@ "language_code": "vi" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-03T03:29:44+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T08:34:23+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "vi" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-03T03:30:25+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T08:35:01+00:00", "source_file": "docs/TESTING.md", "language_code": "vi" } diff --git a/translations/vi/00-quick-start/README.md b/translations/vi/00-quick-start/README.md deleted file mode 100644 index a25927151..000000000 --- a/translations/vi/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: Bắt Đầu Nhanh - -## Mục Lục - -- [Giới thiệu](../../../00-quick-start) -- [LangChain4j là gì?](../../../00-quick-start) -- [Phụ thuộc của LangChain4j](../../../00-quick-start) -- [Yêu cầu trước](../../../00-quick-start) -- [Cài đặt](../../../00-quick-start) - - [1. Lấy Token GitHub của bạn](../../../00-quick-start) - - [2. Cài đặt Token của bạn](../../../00-quick-start) -- [Chạy Các Ví Dụ](../../../00-quick-start) - - [1. Trò chuyện cơ bản](../../../00-quick-start) - - [2. Mẫu nhắc](../../../00-quick-start) - - [3. Gọi hàm](../../../00-quick-start) - - [4. Hỏi & Đáp tài liệu (Easy RAG)](../../../00-quick-start) - - [5. Trí tuệ nhân tạo có trách nhiệm](../../../00-quick-start) -- [Mỗi Ví Dụ Cho Thấy Điều Gì](../../../00-quick-start) -- [Bước Tiếp Theo](../../../00-quick-start) -- [Khắc phục sự cố](../../../00-quick-start) - -## Giới thiệu - -Bắt đầu nhanh này nhằm giúp bạn nhanh chóng làm quen và chạy với LangChain4j. Nó bao gồm những điều cơ bản nhất về xây dựng ứng dụng AI với LangChain4j và GitHub Models. Trong các module tiếp theo, bạn sẽ chuyển sang Azure OpenAI và GPT-5.2 cũng như đào sâu hơn vào từng khái niệm. - -## LangChain4j là gì? - -LangChain4j là thư viện Java giúp đơn giản hóa việc xây dựng các ứng dụng sử dụng AI. Thay vì phải xử lý các HTTP client và phân tích cú pháp JSON, bạn làm việc với các API Java sạch sẽ. - -“Chain” trong LangChain nghĩa là liên kết các thành phần lại với nhau — bạn có thể liên kết một lời nhắc đến một mô hình đến một bộ phân tích, hoặc liên kết nhiều lần gọi AI mà đầu ra của lần này trở thành đầu vào cho lần kế tiếp. Bắt đầu nhanh này tập trung vào những điều cơ bản trước khi khám phá các chuỗi phức tạp hơn. - -LangChain4j Chaining Concept - -*Liên kết các thành phần trong LangChain4j - các viên gạch xây dựng kết nối tạo nên quy trình AI mạnh mẽ* - -Chúng ta sẽ dùng ba thành phần cốt lõi: - -**ChatModel** - Giao diện tương tác với mô hình AI. Gọi `model.chat("prompt")` và nhận một chuỗi phản hồi. Chúng ta dùng `OpenAiOfficialChatModel` hoạt động với các endpoint tương thích OpenAI như GitHub Models. - -**AiServices** - Tạo giao diện dịch vụ AI an toàn về kiểu dữ liệu. Định nghĩa các phương thức, chú thích chúng bằng `@Tool`, và LangChain4j sẽ điều phối. AI tự động gọi các phương thức Java của bạn khi cần. - -**MessageWindowChatMemory** - Duy trì lịch sử hội thoại. Nếu không có nó, mỗi yêu cầu là độc lập. Có nó, AI sẽ nhớ các tin nhắn trước và giữ ngữ cảnh qua nhiều lượt gọi. - -LangChain4j Architecture - -*Kiến trúc LangChain4j - các thành phần cốt lõi làm việc cùng nhau để cung cấp sức mạnh cho ứng dụng AI của bạn* - -## Phụ thuộc của LangChain4j - -Bắt đầu nhanh này sử dụng ba phụ thuộc Maven trong [`pom.xml`](../../../00-quick-start/pom.xml): - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -Module `langchain4j-open-ai-official` cung cấp lớp `OpenAiOfficialChatModel` kết nối tới API tương thích OpenAI. GitHub Models dùng cùng định dạng API nên không cần bộ chuyển đổi đặc biệt - chỉ cần trỏ URL gốc tới `https://models.github.ai/inference`. - -Module `langchain4j-easy-rag` cung cấp tự động chia nhỏ tài liệu, tạo embedding, và truy xuất nên bạn có thể xây dựng ứng dụng RAG mà không phải cấu hình từng bước thủ công. - -## Yêu cầu trước - -**Dùng Dev Container?** Java và Maven đã được cài sẵn. Bạn chỉ cần Token Truy cập Cá nhân GitHub. - -**Phát triển cục bộ:** -- Java 21+, Maven 3.9+ -- Token Truy cập Cá nhân GitHub (hướng dẫn bên dưới) - -> **Lưu ý:** Module này sử dụng `gpt-4.1-nano` từ GitHub Models. Đừng sửa tên mô hình trong mã — nó được cấu hình để hoạt động với các mô hình có sẵn của GitHub. - -## Cài đặt - -### 1. Lấy Token GitHub của bạn - -1. Truy cập [Cài đặt GitHub → Token Truy cập Cá nhân](https://github.com/settings/personal-access-tokens) -2. Nhấn "Generate new token" -3. Đặt tên mô tả (ví dụ: "LangChain4j Demo") -4. Chọn thời hạn (khuyến nghị 7 ngày) -5. Dưới "Quyền tài khoản", tìm "Models" và đặt là "Chỉ đọc" -6. Nhấn "Generate token" -7. Sao chép và lưu token — bạn sẽ không thấy lại lần nữa - -### 2. Cài đặt Token của bạn - -**Chọn 1: Dùng VS Code (được khuyên dùng)** - -Nếu bạn dùng VS Code, thêm token vào file `.env` ở thư mục gốc dự án: - -Nếu file `.env` không tồn tại, sao chép `.env.example` thành `.env` hoặc tạo file `.env` mới ở gốc dự án. - -**Ví dụ file `.env`:** -```bash -# Trong /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -Sau đó bạn chỉ cần click chuột phải vào bất kỳ file demo nào (ví dụ `BasicChatDemo.java`) trong Explorer và chọn **"Run Java"** hoặc dùng cấu hình khởi chạy ở bảng Run and Debug. - -**Chọn 2: Dùng Terminal** - -Đặt token làm biến môi trường: - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## Chạy Các Ví Dụ - -**Dùng VS Code:** Chỉ cần click chuột phải vào file demo bất kỳ trong Explorer và chọn **"Run Java"**, hoặc dùng cấu hình khởi chạy từ bảng Run and Debug (nhớ đã thêm token vào `.env` trước). - -**Dùng Maven:** Bạn cũng có thể chạy từ dòng lệnh: - -### 1. Trò chuyện cơ bản - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. Mẫu nhắc - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -Hiển thị các mẫu nhắc zero-shot, few-shot, chuỗi suy nghĩ, và dựa trên vai trò. - -### 3. Gọi hàm - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI tự động gọi các phương thức Java của bạn khi cần thiết. - -### 4. Hỏi & Đáp tài liệu (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -Hỏi các câu về tài liệu của bạn sử dụng Easy RAG với nhúng (embedding) và truy xuất tự động. - -### 5. Trí tuệ nhân tạo có trách nhiệm - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -Xem cách bộ lọc an toàn AI chặn nội dung có hại. - -## Mỗi Ví Dụ Cho Thấy Điều Gì - -**Trò chuyện cơ bản** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -Bắt đầu tại đây để thấy LangChain4j đơn giản nhất. Bạn sẽ tạo một `OpenAiOfficialChatModel`, gửi prompt với `.chat()`, và nhận lại câu trả lời. Điều này minh họa nền tảng: cách khởi tạo mô hình với endpoint và API key tùy chỉnh. Khi bạn đã hiểu mẫu này, mọi thứ khác sẽ xây dựng dựa trên đó. - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) và hỏi: -> - "Làm sao để chuyển từ GitHub Models sang Azure OpenAI trong mã này?" -> - "Có những tham số nào khác tôi có thể cấu hình trong OpenAiOfficialChatModel.builder()?" -> - "Làm cách nào để thêm phản hồi dạng streaming thay vì chờ phản hồi hoàn chỉnh?" - -**Kỹ thuật Nhắc** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -Giờ bạn đã biết cách nói chuyện với mô hình, hãy khám phá cách bạn nói với nó. Demo này dùng cùng cấu hình mô hình nhưng trình bày năm mẫu nhắc khác nhau. Thử prompt zero-shot chỉ dẫn trực tiếp, prompt few-shot học từ ví dụ, prompt chuỗi suy nghĩ thể hiện các bước lí luận, và prompt dựa trên vai trò để thiết lập ngữ cảnh. Bạn sẽ thấy mô hình cùng một cách nhưng kết quả khác biệt đáng kể dựa vào cách bạn đặt câu hỏi. - -Demo cũng trình bày các mẫu prompt template, là cách hiệu quả để tạo prompt tái sử dụng với biến số. -Ví dụ dưới dùng `PromptTemplate` của LangChain4j điền biến. AI sẽ trả lời dựa trên điểm đến và hoạt động được cung cấp. - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) và hỏi: -> - "Sự khác nhau giữa zero-shot và few-shot prompting là gì, và khi nào tôi nên dùng mỗi loại?" -> - "Tham số temperature ảnh hưởng thế nào đến câu trả lời của mô hình?" -> - "Có những kỹ thuật nào để ngăn chặn tấn công prompt injection trong sản xuất?" -> - "Làm sao để tạo các object PromptTemplate tái sử dụng cho các mẫu phổ biến?" - -**Tích hợp Công cụ** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -Đây là điểm LangChain4j trở nên mạnh mẽ. Bạn sẽ dùng `AiServices` để tạo trợ lý AI có thể gọi các phương thức Java của bạn. Chỉ cần chú thích phương thức với `@Tool("mô tả")` và LangChain4j sẽ lo phần còn lại — AI tự động quyết định khi nào dùng công cụ nào dựa trên yêu cầu của người dùng. Điều này thể hiện kỹ thuật gọi hàm, một kỹ thuật quan trọng để xây dựng AI có thể thực thi hành động, không chỉ trả lời câu hỏi. - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) và hỏi: -> - "Chú thích @Tool hoạt động ra sao và LangChain4j làm gì với nó phía sau?" -> - "AI có thể gọi nhiều công cụ theo chuỗi để giải quyết vấn đề phức tạp không?" -> - "Nếu một công cụ phát sinh ngoại lệ thì sao — tôi nên xử lý lỗi thế nào?" -> - "Làm sao để tích hợp một API thật thay vì ví dụ máy tính này?" - -**Hỏi & Đáp tài liệu (Easy RAG)** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -Ở đây bạn sẽ thấy RAG (retrieval-augmented generation) sử dụng cách tiếp cận "Easy RAG" của LangChain4j. Tài liệu được tải lên, tự động chia nhỏ và tạo embedding vào bộ nhớ trong, rồi bộ truy xuất nội dung cung cấp các đoạn liên quan cho AI lúc truy vấn. AI trả lời dựa trên tài liệu của bạn, không phải kiến thức chung. - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) và hỏi: -> - "RAG tránh ảo giác AI thế nào so với dùng dữ liệu huấn luyện của mô hình?" -> - "Sự khác biệt giữa cách tiếp cận dễ dàng này và pipeline RAG tùy chỉnh là gì?" -> - "Làm sao tôi mở rộng để xử lý nhiều tài liệu hoặc kho kiến thức lớn?" - -**Trí tuệ nhân tạo có trách nhiệm** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -Xây dựng an toàn AI với phòng thủ nhiều lớp. Demo này trình bày hai tầng bảo vệ phối hợp: - -**Phần 1: LangChain4j Input Guardrails** - Chặn prompt nguy hiểm trước khi chúng đến LLM. Tạo guardrails tùy chỉnh kiểm tra từ khóa hoặc mẫu bị cấm. Chúng chạy trong mã của bạn nên nhanh và miễn phí. - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**Phần 2: Bộ lọc an toàn của nhà cung cấp** - GitHub Models có bộ lọc tích hợp bắt các điều guardrails có thể bỏ sót. Bạn sẽ thấy chặn cứng (lỗi HTTP 400) với vi phạm nghiêm trọng và từ chối nhẹ nhàng khi AI lịch sự từ chối. - -> **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) và hỏi: -> - "InputGuardrail là gì và làm sao tôi tạo guardrail của riêng mình?" -> - "Sự khác nhau giữa chặn cứng và từ chối nhẹ nhàng là gì?" -> - "Tại sao sử dụng đồng thời guardrails và bộ lọc nhà cung cấp?" - -## Bước Tiếp Theo - -**Module tiếp theo:** [01-introduction - Bắt đầu với LangChain4j](../01-introduction/README.md) - ---- - -**Điều hướng:** [← Quay lại Trang chính](../README.md) | [Tiếp theo: Module 01 - Giới thiệu →](../01-introduction/README.md) - ---- - -## Khắc phục sự cố - -### Lần Đầu Xây dựng với Maven - -**Vấn đề**: Lần chạy `mvn clean compile` hoặc `mvn package` đầu tiên rất lâu (10-15 phút) - -**Nguyên nhân**: Maven cần tải về tất cả phụ thuộc dự án (Spring Boot, thư viện LangChain4j, SDK Azure, v.v.) trong lần build đầu tiên. - -**Giải pháp**: Đây là hành vi bình thường. Các lần build sau sẽ nhanh hơn nhiều do phụ thuộc được lưu cache cục bộ. Thời gian tải phụ thuộc tốc độ mạng của bạn. - -### Cú Pháp Lệnh Maven trên PowerShell - -**Vấn đề**: Các lệnh Maven bị lỗi `Unknown lifecycle phase ".mainClass=..."` -**Nguyên nhân**: PowerShell hiểu dấu `=` là toán tử gán biến, khiến cú pháp thuộc tính Maven bị phá vỡ - -**Giải pháp**: Sử dụng toán tử dừng phân tích cú pháp `--%` trước lệnh Maven: - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -Toán tử `--%` cho PowerShell biết truyền tất cả các đối số còn lại một cách nguyên văn đến Maven mà không giải thích. - -### Hiển thị Biểu tượng cảm xúc trên Windows PowerShell - -**Vấn đề**: Phản hồi AI hiển thị ký tự rác (ví dụ: `????` hoặc `â??`) thay vì biểu tượng cảm xúc trong PowerShell - -**Nguyên nhân**: Mã hóa mặc định của PowerShell không hỗ trợ biểu tượng cảm xúc UTF-8 - -**Giải pháp**: Chạy lệnh này trước khi thực thi ứng dụng Java: -```cmd -chcp 65001 -``` - -Lệnh này ép mã hóa UTF-8 trong terminal. Ngoài ra, có thể dùng Windows Terminal vì nó hỗ trợ Unicode tốt hơn. - -### Gỡ lỗi các cuộc gọi API - -**Vấn đề**: Lỗi xác thực, giới hạn tần suất, hoặc phản hồi không mong đợi từ mô hình AI - -**Giải pháp**: Các ví dụ có chứa `.logRequests(true)` và `.logResponses(true)` để hiển thị các cuộc gọi API trên bảng điều khiển. Điều này giúp khắc phục lỗi xác thực, giới hạn tần suất hoặc phản hồi không mong đợi. Hãy loại bỏ các cờ này trong môi trường sản xuất để giảm nhiễu log. - ---- - - -**Tuyên bố từ chối trách nhiệm**: -Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo tính chính xác, xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc không chính xác. Tài liệu gốc bằng ngôn ngữ bản địa nên được coi là nguồn thông tin chính thức. Đối với các thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm về bất kỳ sự hiểu lầm hay nhầm lẫn nào phát sinh từ việc sử dụng bản dịch này. - \ No newline at end of file diff --git a/translations/vi/01-introduction/README.md b/translations/vi/01-introduction/README.md index 8f26803d9..26600376e 100644 --- a/translations/vi/01-introduction/README.md +++ b/translations/vi/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: Bắt đầu với LangChain4j +# Module 01: Bắt Đầu với LangChain4j -## Mục lục +## Mục Lục -- [Hướng dẫn qua video](../../../01-introduction) -- [Bạn sẽ học được gì](../../../01-introduction) -- [Yêu cầu trước](../../../01-introduction) -- [Hiểu về vấn đề cốt lõi](../../../01-introduction) -- [Hiểu về Token](../../../01-introduction) -- [Cách bộ nhớ hoạt động](../../../01-introduction) -- [Cách sử dụng LangChain4j](../../../01-introduction) -- [Triển khai hạ tầng Azure OpenAI](../../../01-introduction) -- [Chạy ứng dụng trên máy cục bộ](../../../01-introduction) -- [Sử dụng ứng dụng](../../../01-introduction) - - [Chat không trạng thái (Bảng bên trái)](../../../01-introduction) - - [Chat có trạng thái (Bảng bên phải)](../../../01-introduction) -- [Bước tiếp theo](../../../01-introduction) +- [Video Hướng Dẫn](#video-hướng-dẫn) +- [Bạn Sẽ Học Được Gì](#bạn-sẽ-học-được-gì) +- [Yêu Cầu Trước](#yêu-cầu-trước) +- [Hiểu Vấn Đề Cốt Lõi](#hiểu-vấn-đề-cốt-lõi) +- [Hiểu Về Token](#hiểu-về-token) +- [Cách Bộ Nhớ Hoạt Động](#cách-bộ-nhớ-hoạt-động) +- [Cách Module Này Sử Dụng LangChain4j](#cách-module-này-sử-dụng-langchain4j) +- [Triển Khai Hạ Tầng Azure OpenAI](#triển-khai-hạ-tầng-azure-openai) +- [Chạy Ứng Dụng Tại Máy](#chạy-ứng-dụng-tại-máy) +- [Sử Dụng Ứng Dụng](#sử-dụng-ứng-dụng) + - [Trò Chuyện Không Trạng Thái (Bảng trái)](#trò-chuyện-không-trạng-thái-bảng-trái) + - [Trò Chuyện Có Trạng Thái (Bảng phải)](#trò-chuyện-có-trạng-thái-bảng-phải) +- [Bước Tiếp Theo](#bước-tiếp-theo) -## Hướng dẫn qua video +## Video Hướng Dẫn -Xem phiên trực tiếp này giải thích cách bắt đầu với module này: +Xem buổi trực tiếp này giải thích cách bắt đầu với module này: Getting Started with LangChain4j - Live Session -## Bạn sẽ học được gì +## Bạn Sẽ Học Được Gì -Trong phần khởi động nhanh, bạn đã dùng GitHub Models để gửi prompt, gọi công cụ, xây dựng pipeline RAG và thử nghiệm guardrails. Những demo đó cho thấy những gì có thể làm — bây giờ chúng ta chuyển sang Azure OpenAI và GPT-5.2 để bắt đầu xây dựng các ứng dụng kiểu sản xuất. Module này tập trung vào AI hội thoại có khả năng ghi nhớ ngữ cảnh và duy trì trạng thái — những khái niệm mà các demo khởi động nhanh đã sử dụng phía sau nhưng không giải thích rõ. +Đây là điểm khởi đầu với LangChain4j và Azure OpenAI. Chúng ta bắt đầu với các kiến thức cơ bản và xây dựng các ứng dụng theo kiểu sản xuất. Module này tập trung vào AI hội thoại có khả năng ghi nhớ ngữ cảnh và duy trì trạng thái — những khái niệm nền tảng mà các module tiếp theo đều dựa vào. -Chúng ta sẽ sử dụng GPT-5.2 của Azure OpenAI xuyên suốt hướng dẫn này vì khả năng suy luận nâng cao giúp nhìn rõ hơn cách các mẫu khác nhau hoạt động. Khi thêm bộ nhớ, bạn sẽ thấy sự khác biệt rõ ràng. Điều này giúp dễ dàng hiểu mỗi thành phần mang lại gì cho ứng dụng của bạn. +Chúng ta sẽ sử dụng GPT-5.2 của Azure OpenAI trong suốt hướng dẫn này vì khả năng lý luận nâng cao của nó làm cho hành vi của các mẫu mô hình dễ nhận biết hơn. Khi bạn thêm bộ nhớ, bạn sẽ thấy sự khác biệt rõ ràng. Điều này giúp bạn dễ hiểu hơn từng thành phần đóng góp gì cho ứng dụng của bạn. Bạn sẽ xây dựng một ứng dụng thể hiện cả hai mẫu: -**Chat không trạng thái** - Mỗi yêu cầu là độc lập. Mô hình không nhớ các tin nhắn trước đó. Đây là mẫu bạn đã sử dụng trong khởi động nhanh. +**Trò chuyện không trạng thái** - Mỗi yêu cầu độc lập. Mô hình không ghi nhớ các tin nhắn trước đó. Đây là điểm khởi đầu đơn giản nhất. -**Hội thoại có trạng thái** - Mỗi yêu cầu bao gồm lịch sử hội thoại. Mô hình duy trì ngữ cảnh qua nhiều lượt. Đây là yêu cầu của các ứng dụng sản xuất. +**Trò chuyện có trạng thái** - Mỗi yêu cầu bao gồm lịch sử hội thoại. Mô hình duy trì ngữ cảnh qua nhiều lượt. Đây là yêu cầu của các ứng dụng sản xuất. -## Yêu cầu trước +## Yêu Cầu Trước -- Tài khoản Azure với quyền truy cập Azure OpenAI -- Java 21, Maven 3.9+ +- Tài khoản Azure có quyền truy cập Azure OpenAI +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **Lưu ý:** Java, Maven, Azure CLI và Azure Developer CLI (azd) được cài sẵn trong devcontainer được cung cấp. +> **Lưu ý:** Java, Maven, Azure CLI và Azure Developer CLI (azd) đã được cài đặt sẵn trong devcontainer được cung cấp. -> **Lưu ý:** Module này sử dụng GPT-5.2 trên Azure OpenAI. Việc triển khai được cấu hình tự động qua `azd up` — không chỉnh sửa tên mô hình trong mã nguồn. +> **Lưu ý:** Module này sử dụng GPT-5.2 trên Azure OpenAI. Việc triển khai được cấu hình tự động qua lệnh `azd up` - không chỉnh sửa tên mô hình trong mã. -## Hiểu về vấn đề cốt lõi +## Hiểu Vấn Đề Cốt Lõi -Các mô hình ngôn ngữ là không trạng thái. Mỗi lần gọi API là độc lập. Nếu bạn gửi "Tên tôi là John" rồi hỏi "Tên tôi là gì?", mô hình không biết bạn vừa giới thiệu bản thân. Nó coi mỗi yêu cầu như là cuộc hội thoại đầu tiên bạn từng có. +Mô hình ngôn ngữ là không trạng thái. Mỗi lần gọi API là độc lập. Nếu bạn gửi "My name is John" rồi sau đó hỏi "What’s my name?", mô hình không biết bạn vừa tự giới thiệu tên mình. Nó đối xử với mỗi yêu cầu như thể đây là lần đầu tiên bạn hội thoại. -Điều này ổn với các câu hỏi đơn giản nhưng vô dụng với ứng dụng thực tế. Các bot dịch vụ khách hàng cần nhớ thông tin bạn đã nói. Trợ lý cá nhân cần có ngữ cảnh. Bất kỳ cuộc hội thoại nhiều lượt nào cũng cần có bộ nhớ. +Điều này ổn với các câu hỏi đơn giản nhưng vô dụng cho ứng dụng thực tế. Bot dịch vụ khách hàng cần nhớ bạn đã nói gì. Trợ lý cá nhân cần ngữ cảnh. Bất kỳ hội thoại đa lượt nào đều cần bộ nhớ. -Sơ đồ dưới đây so sánh hai cách tiếp cận — bên trái là gọi không trạng thái quên tên bạn; bên phải là gọi có trạng thái với ChatMemory ghi nhớ tên bạn. +Hình dưới minh họa sự khác biệt giữa hai cách tiếp cận — bên trái là cuộc gọi không trạng thái quên tên bạn; bên phải là cuộc gọi có trạng thái với ChatMemory ghi nhớ tên. Stateless vs Stateful Conversations -*Sự khác biệt giữa hội thoại không trạng thái (gọi độc lập) và hội thoại có trạng thái (nhận biết ngữ cảnh)* +*Phân biệt hội thoại không trạng thái (gọi độc lập) và có trạng thái (nhận biết ngữ cảnh)* -## Hiểu về Token +## Hiểu Về Token -Trước khi đi sâu vào các cuộc hội thoại, cần hiểu về token - đơn vị cơ bản của văn bản mà các mô hình ngôn ngữ xử lý: +Trước khi bước vào hội thoại, quan trọng phải hiểu token — đơn vị cơ bản của văn bản mà mô hình xử lý: Token Explanation -*Ví dụ về cách đoạn văn bản được tách thành các token - "I love AI!" thành 4 đơn vị xử lý riêng biệt* +*Ví dụ cách văn bản được tách thành các token - "I love AI!" thành 4 đơn vị xử lý riêng biệt* -Token là cách các mô hình AI đo lường và xử lý văn bản. Từ, dấu câu và thậm chí dấu cách đều có thể là token. Mô hình của bạn có giới hạn số token có thể xử lý cùng lúc (400,000 cho GPT-5.2, với tối đa 272,000 token đầu vào và 128,000 token đầu ra). Hiểu token giúp bạn quản lý độ dài hội thoại và chi phí. +Token là cách mô hình AI đo và xử lý văn bản. Từ, dấu câu, thậm chí khoảng trắng đều có thể là token. Mô hình của bạn có giới hạn số token có thể xử lý cùng lúc (400,000 cho GPT-5.2, bao gồm tối đa 272,000 token đầu vào và 128,000 token đầu ra). Hiểu được token giúp bạn quản lý độ dài hội thoại và chi phí. -## Cách bộ nhớ hoạt động +## Cách Bộ Nhớ Hoạt Động -Bộ nhớ chat giải quyết vấn đề không trạng thái bằng cách duy trì lịch sử hội thoại. Trước khi gửi yêu cầu tới mô hình, khung làm việc thêm vào các tin nhắn trước có liên quan. Khi bạn hỏi "Tên tôi là gì?", hệ thống thực sự gửi toàn bộ lịch sử hội thoại, cho phép mô hình thấy rằng bạn đã nói "Tên tôi là John" trước đó. +Bộ nhớ chat giải quyết vấn đề không trạng thái bằng cách duy trì lịch sử hội thoại. Trước khi gửi yêu cầu tới mô hình, framework sẽ thêm các tin nhắn trước có liên quan. Khi bạn hỏi "What’s my name?", hệ thống thực sự gửi toàn bộ lịch sử hội thoại, cho phép mô hình thấy rằng bạn đã nói "My name is John" trước đó. -LangChain4j cung cấp các cài đặt bộ nhớ tự động xử lý việc này. Bạn chọn số lượng tin nhắn giữ lại và khung làm việc quản lý cửa sổ ngữ cảnh. Sơ đồ dưới đây cho thấy cách MessageWindowChatMemory duy trì một cửa sổ trượt các tin nhắn gần đây. +LangChain4j cung cấp các triển khai bộ nhớ xử lý việc này tự động. Bạn chọn số tin nhắn giữ lại và framework quản lý cửa sổ ngữ cảnh. Hình dưới minh họa MessageWindowChatMemory duy trì cửa sổ trượt các tin nhắn gần nhất. Memory Window Concept -*MessageWindowChatMemory duy trì một cửa sổ trượt các tin nhắn gần đây, tự động loại bỏ tin nhắn cũ* +*MessageWindowChatMemory duy trì cửa sổ trượt các tin nhắn gần đây, tự động xóa các tin nhắn cũ* -## Cách sử dụng LangChain4j +## Cách Module Này Sử Dụng LangChain4j -Module này mở rộng khởi động nhanh bằng cách tích hợp Spring Boot và thêm bộ nhớ hội thoại. Đây là cách các phần phối hợp với nhau: +Module này tích hợp Spring Boot và thêm bộ nhớ cuộc hội thoại. Cách các phần ghép lại như sau: -**Dependencies** - Thêm hai thư viện LangChain4j: +**Phụ thuộc** - Thêm hai thư viện LangChain4j: ```xml @@ -94,7 +94,7 @@ Module này mở rộng khởi động nhanh bằng cách tích hợp Spring Boo ``` -**Mô hình Chat** - Cấu hình Azure OpenAI như một bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): +**Mô hình Chat** - Cấu hình Azure OpenAI như bean Spring ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)): ```java @Bean @@ -109,7 +109,7 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Trình tạo đọc thông tin xác thực từ biến môi trường được thiết lập bởi `azd up`. Thiết lập `baseUrl` trỏ đến endpoint Azure của bạn làm cho client OpenAI hoạt động với Azure OpenAI. +Builder lấy thông tin xác thực từ biến môi trường do `azd up` thiết lập. Việc đặt `baseUrl` thành endpoint Azure của bạn giúp client OpenAI hoạt động với Azure OpenAI. **Bộ nhớ hội thoại** - Theo dõi lịch sử chat với MessageWindowChatMemory ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)): @@ -124,37 +124,37 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -Tạo bộ nhớ với `withMaxMessages(10)` để giữ 10 tin nhắn cuối cùng. Thêm tin nhắn người dùng và AI với các wrapper kiểu: `UserMessage.from(text)` và `AiMessage.from(text)`. Lấy lịch sử với `memory.messages()` rồi gửi đến mô hình. Service lưu các phiên bộ nhớ riêng cho từng ID hội thoại, cho phép nhiều người dùng chat đồng thời. +Tạo bộ nhớ với `withMaxMessages(10)` để giữ 10 tin nhắn gần nhất. Thêm tin nhắn người dùng và AI với wrapper kiểu: `UserMessage.from(text)` và `AiMessage.from(text)`. Lấy lịch sử với `memory.messages()` và gửi cho mô hình. Service lưu các instance bộ nhớ riêng theo ID cuộc hội thoại, cho phép nhiều người dùng chat đồng thời. -> **🤖 Thử cùng [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) và hỏi: -> - "MessageWindowChatMemory quyết định loại bỏ tin nhắn nào khi cửa sổ đầy như thế nào?" -> - "Tôi có thể triển khai lưu trữ bộ nhớ tùy chỉnh bằng cơ sở dữ liệu thay vì bộ nhớ trong RAM không?" -> - "Làm thế nào để thêm tóm tắt nén lịch sử hội thoại cũ?" +> **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) và hỏi: +> - "MessageWindowChatMemory quyết định xóa tin nhắn nào khi cửa sổ đầy như thế nào?" +> - "Tôi có thể triển khai bộ nhớ tùy chỉnh sử dụng cơ sở dữ liệu thay vì bộ nhớ trong không?" +> - "Làm sao để thêm tính năng tóm tắt để nén lịch sử hội thoại cũ?" -Điểm cuối chat không trạng thái bỏ qua bộ nhớ hoàn toàn — chỉ `chatModel.chat(prompt)` như khởi động nhanh. Điểm cuối có trạng thái thêm tin nhắn vào bộ nhớ, lấy lịch sử và bao gồm ngữ cảnh này với mỗi yêu cầu. Cấu hình mô hình giống nhau, cách tiếp cận khác nhau. +Điểm cuối chat không trạng thái không dùng bộ nhớ - chỉ `chatModel.chat(prompt)` như khởi đầu nhanh. Điểm cuối có trạng thái thêm tin nhắn vào bộ nhớ, lấy lịch sử và bao gồm ngữ cảnh này với mỗi yêu cầu. Cấu hình mô hình giống nhau, chỉ khác mô hình thao tác. -## Triển khai hạ tầng Azure OpenAI +## Triển Khai Hạ Tầng Azure OpenAI **Bash:** ```bash cd 01-introduction -azd up # Chọn đăng ký và vị trí (khuyến nghị eastus2) +azd up # Chọn gói đăng ký và vị trí (đề xuất eastus2) ``` **PowerShell:** ```powershell cd 01-introduction -azd up # Chọn đăng ký và vị trí (khuyến nghị eastus2) +azd up # Chọn đăng ký và vị trí (khuyên dùng eastus2) ``` -> **Lưu ý:** Nếu bạn gặp lỗi timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), chỉ cần chạy lại `azd up`. Các tài nguyên Azure có thể đang được triển khai ở nền và thử lại cho phép quá trình hoàn tất khi tài nguyên đạt trạng thái cuối. +> **Lưu ý:** Nếu gặp lỗi timeout (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`), hãy chạy lại `azd up`. Tài nguyên Azure có thể vẫn đang triển khai ngầm và thử lại giúp hoàn thành khi tài nguyên đã ở trạng thái cuối cùng. -Điều này sẽ: +Việc này sẽ: 1. Triển khai tài nguyên Azure OpenAI với các mô hình GPT-5.2 và text-embedding-3-small -2. Tự động tạo file `.env` ở thư mục gốc dự án với thông tin xác thực +2. Tự động tạo file `.env` tại thư mục gốc dự án chứa thông tin xác thực 3. Thiết lập tất cả biến môi trường cần thiết -**Gặp vấn đề khi triển khai?** Xem [Infra README](infra/README.md) để biết hướng dẫn xử lý chi tiết bao gồm xung đột tên miền phụ, các bước triển khai thủ công qua Azure Portal và hướng dẫn cấu hình mô hình. +**Gặp vấn đề khi triển khai?** Xem [Infrastructure README](infra/README.md) để có hướng dẫn chi tiết xử lý lỗi bao gồm xung đột tên miền phụ, các bước triển khai thủ công trên Azure Portal và hướng dẫn cấu hình mô hình. **Xác nhận triển khai thành công:** @@ -168,13 +168,14 @@ cat ../.env # Nên hiển thị AZURE_OPENAI_ENDPOINT, API_KEY, v.v. Get-Content ..\.env # Nên hiển thị AZURE_OPENAI_ENDPOINT, API_KEY, v.v. ``` -> **Lưu ý:** Lệnh `azd up` tự động tạo file `.env`. Nếu cần cập nhật sau, có thể chỉnh sửa thủ công hoặc tạo lại bằng cách chạy: +> **Lưu ý:** Lệnh `azd up` tự động tạo file `.env`. Nếu cần cập nhật sau, bạn có thể chỉnh sửa thủ công hoặc tạo lại bằng lệnh: > > **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` + > > **PowerShell:** > ```powershell @@ -182,11 +183,11 @@ Get-Content ..\.env # Nên hiển thị AZURE_OPENAI_ENDPOINT, API_KEY, v.v. > .\.azd-env.ps1 > ``` -## Chạy ứng dụng trên máy cục bộ +## Chạy Ứng Dụng Tại Máy **Xác nhận triển khai:** -Đảm bảo file `.env` tồn tại trong thư mục gốc với thông tin xác thực Azure. Chạy lệnh này từ thư mục module (`01-introduction/`): +Đảm bảo file `.env` tồn tại trong thư mục gốc chứa thông tin xác thực Azure. Chạy lệnh từ thư mục module (`01-introduction/`): **Bash:** ```bash @@ -200,23 +201,23 @@ Get-Content ..\.env # Nên hiển thị AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Khởi động ứng dụng:** -**Lựa chọn 1: Dùng Spring Boot Dashboard (Khuyến nghị cho người dùng VS Code)** +**Lựa chọn 1: Sử dụng Spring Boot Dashboard (Khuyến nghị cho người dùng VS Code)** -Dev container bao gồm tiện ích mở rộng Spring Boot Dashboard, cung cấp giao diện trực quan để quản lý tất cả ứng dụng Spring Boot. Bạn có thể tìm nó trong Thanh hoạt động bên trái VS Code (biểu tượng hình lá cờ Spring Boot). +Dev container bao gồm extension Spring Boot Dashboard, cung cấp giao diện trực quan quản lý tất cả ứng dụng Spring Boot. Bạn có thể tìm thấy nó trên thanh Activity bên trái của VS Code (icon Spring Boot). Từ Spring Boot Dashboard, bạn có thể: -- Xem tất cả ứng dụng Spring Boot có trong workspace -- Khởi động/dừng ứng dụng với một cú nhấp chuột +- Xem tất cả ứng dụng Spring Boot trong workspace +- Khởi động/dừng ứng dụng chỉ với một cú nhấp - Xem nhật ký ứng dụng theo thời gian thực - Giám sát trạng thái ứng dụng -Chỉ cần nhấp nút chạy bên cạnh "introduction" để bắt đầu module này, hoặc chạy tất cả module cùng lúc. +Chỉ cần nhấp nút play bên cạnh "introduction" để chạy module này, hoặc khởi động tất cả các module cùng lúc. Spring Boot Dashboard -*Spring Boot Dashboard trong VS Code — khởi động, dừng và giám sát tất cả module từ một nơi* +*Spring Boot Dashboard trong VS Code — khởi động, dừng và giám sát tất cả module tại một nơi* -**Lựa chọn 2: Dùng script shell** +**Lựa chọn 2: Sử dụng script shell** Khởi động tất cả ứng dụng web (module 01-04): @@ -246,15 +247,16 @@ cd 01-introduction .\start.ps1 ``` -Cả hai script tự động nạp biến môi trường từ file `.env` gốc và sẽ build file JAR nếu chưa tồn tại. +Cả hai script tự động load biến môi trường từ file `.env` gốc và sẽ build các JAR nếu chưa tồn tại. -> **Lưu ý:** Nếu bạn muốn build thủ công tất cả module trước khi chạy: +> **Lưu ý:** Nếu bạn muốn build thủ công các module trước khi khởi động: > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` + > > **PowerShell:** > ```powershell @@ -262,61 +264,61 @@ Cả hai script tự động nạp biến môi trường từ file `.env` gốc > mvn clean package -DskipTests > ``` -Mở http://localhost:8080 trên trình duyệt của bạn. +Mở http://localhost:8080 trên trình duyệt. **Để dừng:** **Bash:** ```bash -./stop.sh # Chỉ module này +./stop.sh # Chỉ mô-đun này # Hoặc -cd .. && ./stop-all.sh # Tất cả các module +cd .. && ./stop-all.sh # Tất cả các mô-đun ``` **PowerShell:** ```powershell -.\stop.ps1 # Chỉ mô-đun này +.\stop.ps1 # Chỉ module này # Hoặc -cd ..; .\stop-all.ps1 # Tất cả các mô-đun +cd ..; .\stop-all.ps1 # Tất cả các module ``` -## Sử dụng ứng dụng +## Sử Dụng Ứng Dụng -Ứng dụng cung cấp giao diện web với hai triển khai chat đặt cạnh nhau. +Ứng dụng cung cấp giao diện web với hai phiên bản chat hiện bên cạnh nhau. Application Home Screen -*Bảng điều khiển hiển thị cả tùy chọn Chat Đơn giản (không trạng thái) và Chat Hội thoại (có trạng thái)* +*Dashboard hiển thị cả hai tùy chọn Chat Đơn Giản (không trạng thái) và Chat Hội Thoại (có trạng thái)* -### Chat không trạng thái (Bảng bên trái) +### Trò Chuyện Không Trạng Thái (Bảng trái) -Thử trước phần này. Hỏi "Tên tôi là John" rồi ngay lập tức hỏi "Tên tôi là gì?" Mô hình sẽ không nhớ vì mỗi tin nhắn là độc lập. Điều này minh họa vấn đề cốt lõi khi tích hợp mô hình ngôn ngữ cơ bản - không có ngữ cảnh hội thoại. +Thử đầu tiên. Hỏi "My name is John" rồi ngay lập tức hỏi "What’s my name?" Mô hình sẽ không nhớ vì mỗi tin nhắn là độc lập. Điều này minh họa vấn đề cốt lõi khi tích hợp mô hình ngôn ngữ cơ bản - không có ngữ cảnh hội thoại. Stateless Chat Demo -*AI không nhớ tên bạn từ tin nhắn trước* +*AI không nhớ tên bạn trong tin nhắn trước* -### Chat có trạng thái (Bảng bên phải) +### Trò Chuyện Có Trạng Thái (Bảng phải) -Bây giờ thử lại chuỗi câu hỏi tương tự ở đây. Hỏi "Tên tôi là John" rồi hỏi "Tên tôi là gì?" Lần này nó nhớ. Khác biệt là MessageWindowChatMemory - nó duy trì lịch sử hội thoại và bao gồm ngữ cảnh với mỗi yêu cầu. Đây là cách AI hội thoại trong sản xuất hoạt động. +Bây giờ thử trình tự tương tự ở đây. Hỏi "My name is John" rồi hỏi "What’s my name?" Lần này nó nhớ. Khác biệt là MessageWindowChatMemory - nó giữ lịch sử hội thoại và gửi kèm trong mỗi yêu cầu. Đây là cách AI hội thoại thực tế hoạt động. Stateful Chat Demo -*AI nhớ tên bạn từ trước trong cuộc hội thoại* +*AI nhớ tên bạn từ lúc trước trong hội thoại* -Cả hai bảng đều dùng chung mô hình GPT-5.2. Điểm khác biệt duy nhất là bộ nhớ. Điều này làm rõ bộ nhớ mang lại gì cho ứng dụng và tại sao nó quan trọng với các trường hợp sử dụng thực tế. +Hai bảng đều dùng chung mô hình GPT-5.2. Khác biệt duy nhất là bộ nhớ. Điều này làm rõ giá trị của bộ nhớ đối với ứng dụng của bạn và tại sao nó thiết yếu cho các trường hợp sử dụng thực. -## Bước tiếp theo +## Bước Tiếp Theo -**Module tiếp theo:** [02-prompt-engineering - Kỹ thuật Prompt với GPT-5.2](../02-prompt-engineering/README.md) +**Module tiếp theo:** [02-prompt-engineering - Kỹ Thuật Prompt với GPT-5.2](../02-prompt-engineering/README.md) --- -**Điều hướng:** [← Trước: Module 00 - Khởi động nhanh](../00-quick-start/README.md) | [Quay về chính](../README.md) | [Tiếp: Module 02 - Kỹ thuật Prompt →](../02-prompt-engineering/README.md) +**Điều hướng:** [← Quay về Trang Chính](../README.md) | [Tiếp Theo: Module 02 - Kỹ Thuật Prompt →](../02-prompt-engineering/README.md) --- -**Tuyên bố từ chối trách nhiệm**: -Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc không chính xác. Tài liệu gốc bằng ngôn ngữ gốc nên được xem là nguồn chính thức. Đối với thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp do con người thực hiện. Chúng tôi không chịu trách nhiệm về bất kỳ sự hiểu lầm hay giải thích sai nào phát sinh từ việc sử dụng bản dịch này. +**Tuyên bố miễn trừ trách nhiệm**: +Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ gốc nên được coi là nguồn tin chính thức. Đối với thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm về bất kỳ hiểu lầm hoặc giải thích sai nào phát sinh từ việc sử dụng bản dịch này. \ No newline at end of file diff --git a/translations/vi/02-prompt-engineering/README.md b/translations/vi/02-prompt-engineering/README.md index 869faa722..9e483e0e7 100644 --- a/translations/vi/02-prompt-engineering/README.md +++ b/translations/vi/02-prompt-engineering/README.md @@ -2,84 +2,84 @@ ## Mục Lục -- [Video Hướng Dẫn](../../../02-prompt-engineering) -- [Bạn Sẽ Học Gì](../../../02-prompt-engineering) -- [Yêu Cầu Tiền Đề](../../../02-prompt-engineering) -- [Hiểu Về Kỹ Thuật Tạo Prompt](../../../02-prompt-engineering) -- [Các Nguyên Tắc Cơ Bản của Kỹ Thuật Tạo Prompt](../../../02-prompt-engineering) - - [Zero-Shot Prompting](../../../02-prompt-engineering) - - [Few-Shot Prompting](../../../02-prompt-engineering) - - [Chain of Thought](../../../02-prompt-engineering) - - [Role-Based Prompting](../../../02-prompt-engineering) - - [Prompt Templates](../../../02-prompt-engineering) -- [Các Mẫu Nâng Cao](../../../02-prompt-engineering) -- [Chạy Ứng Dụng](../../../02-prompt-engineering) -- [Ảnh Chụp Màn Hình Ứng Dụng](../../../02-prompt-engineering) -- [Khám Phá Các Mẫu](../../../02-prompt-engineering) - - [Nhiệt Tình Thấp và Cao](../../../02-prompt-engineering) - - [Thực Thi Nhiệm Vụ (Phần Mở Đầu Công Cụ)](../../../02-prompt-engineering) - - [Mã Tự Đánh Giá](../../../02-prompt-engineering) - - [Phân Tích Cấu Trúc](../../../02-prompt-engineering) - - [Trò Chuyện Nhiều Vòng](../../../02-prompt-engineering) - - [Lý Luận Từng Bước Một](../../../02-prompt-engineering) - - [Đầu Ra Có Ràng Buộc](../../../02-prompt-engineering) -- [Bạn Thực Sự Đang Học Gì](../../../02-prompt-engineering) -- [Bước Tiếp Theo](../../../02-prompt-engineering) +- [Video Hướng Dẫn](#video-hướng-dẫn) +- [Những Gì Bạn Sẽ Học](#những-gì-bạn-sẽ-học) +- [Yêu Cầu Tiên Quyết](#yêu-cầu-tiên-quyết) +- [Hiểu Về Kỹ Thuật Tạo Prompt](#hiểu-về-kỹ-thuật-tạo-prompt) +- [Các Nguyên Tắc Cơ Bản của Kỹ Thuật Tạo Prompt](#các-nguyên-tắc-cơ-bản-của-kỹ-thuật-tạo-prompt) + - [Zero-Shot Prompting](#zero-shot-prompting) + - [Few-Shot Prompting](#few-shot-prompting) + - [Chain of Thought](#chain-of-thought) + - [Role-Based Prompting](#role-based-prompting) + - [Prompt Templates](#prompt-templates) +- [Các Mẫu Nâng Cao](#các-mẫu-nâng-cao) +- [Chạy Ứng Dụng](#chạy-ứng-dụng) +- [Ảnh Chụp Màn Hình Ứng Dụng](#ảnh-chụp-màn-hình-ứng-dụng) +- [Khám Phá Các Mẫu](#khám-phá-các-mẫu) + - [Sự Nhiệt Tình Thấp và Cao](#tham-vọng-thấp-và-tham-vọng-cao) + - [Thực Thi Nhiệm Vụ (Giới Thiệu Công Cụ)](#thực-thi-nhiệm-vụ-tool-preambles) + - [Mã Tự Phản Chiếu](#mã-tự-phản-chiếu) + - [Phân Tích Có Cấu Trúc](#phân-tích-cấu-trúc) + - [Trò Chuyện Nhiều Lần](#hội-thoại-nhiều-lần) + - [Lý Luận Từng Bước](#suy-luận-từng-bước) + - [Đầu Ra Có Ràng Buộc](#đầu-ra-có-giới-hạn) +- [Những Gì Bạn Thật Sự Đang Học](#những-gì-bạn-thực-sự-học-được) +- [Bước Tiếp Theo](#các-bước-tiếp-theo) ## Video Hướng Dẫn -Xem buổi trực tiếp này giải thích cách bắt đầu với module này: +Xem buổi trực tiếp này để hiểu cách bắt đầu với module này: Prompt Engineering with LangChain4j - Live Session -## Bạn Sẽ Học Gì +## Những Gì Bạn Sẽ Học -Sơ đồ dưới đây cung cấp cái nhìn tổng quan về các chủ đề chính và kỹ năng bạn sẽ phát triển trong module này — từ các kỹ thuật tinh chỉnh prompt đến quy trình làm việc từng bước bạn sẽ theo dõi. +Sơ đồ dưới đây cung cấp tổng quan về các chủ đề và kỹ năng chính mà bạn sẽ phát triển trong module này — từ kỹ thuật tinh chỉnh prompt đến quy trình làm việc từng bước bạn sẽ theo dõi. What You'll Learn -Trong các module trước, bạn đã khám phá các tương tác cơ bản với LangChain4j cùng các Mô hình GitHub và thấy cách bộ nhớ cho phép AI hội thoại với Azure OpenAI. Bây giờ chúng ta sẽ tập trung vào cách bạn đặt câu hỏi — chính các prompt — sử dụng GPT-5.2 của Azure OpenAI. Cách bạn cấu trúc prompt ảnh hưởng mạnh mẽ đến chất lượng phản hồi bạn nhận được. Chúng ta bắt đầu với việc ôn lại các kỹ thuật tạo prompt cơ bản, sau đó tiến đến tám mẫu nâng cao tận dụng tối đa khả năng của GPT-5.2. +Trong module trước, bạn đã thấy cách bộ nhớ giúp AI đàm thoại với Azure OpenAI. Bây giờ chúng ta sẽ tập trung vào cách bạn đặt câu hỏi — chính các prompt — sử dụng GPT-5.2 của Azure OpenAI. Cách bạn cấu trúc prompt ảnh hưởng rất lớn đến chất lượng câu trả lời bạn nhận được. Chúng ta bắt đầu với xem lại các kỹ thuật prompt cơ bản, rồi chuyển sang tám mẫu nâng cao tận dụng toàn bộ khả năng của GPT-5.2. -Chúng ta sẽ dùng GPT-5.2 vì nó giới thiệu tính năng điều khiển suy luận — bạn có thể chỉ định cho mô hình biết mức độ suy nghĩ trước khi trả lời. Điều này làm các chiến lược prompt khác nhau hiện rõ hơn và giúp bạn hiểu khi nào nên dùng mỗi cách. Chúng ta cũng sẽ tận dụng lợi thế của Azure với ít giới hạn về tốc độ hơn cho GPT-5.2 so với Mô hình GitHub. +Chúng ta sẽ dùng GPT-5.2 bởi vì nó giới thiệu tính năng kiểm soát suy luận - bạn có thể yêu cầu mô hình suy nghĩ nhiều hay ít trước khi trả lời. Điều này làm cho các chiến lược tạo prompt khác biệt rõ ràng hơn và giúp bạn hiểu khi nào nên dùng từng cách tiếp cận. -## Yêu Cầu Tiền Đề +## Yêu Cầu Tiên Quyết -- Đã hoàn thành Module 01 (đã triển khai tài nguyên Azure OpenAI) -- File `.env` trong thư mục gốc chứa thông tin xác thực Azure (được tạo bởi `azd up` trong Module 01) +- Hoàn thành Module 01 (đã triển khai tài nguyên Azure OpenAI) +- Tập tin `.env` trong thư mục gốc với thông tin xác thực Azure (được tạo bởi `azd up` trong Module 01) > **Lưu ý:** Nếu bạn chưa hoàn thành Module 01, hãy làm theo hướng dẫn triển khai ở đó trước. ## Hiểu Về Kỹ Thuật Tạo Prompt -Về cơ bản, kỹ thuật tạo prompt là sự khác biệt giữa hướng dẫn mơ hồ và hướng dẫn chính xác, như so sánh dưới đây minh họa. +Về cơ bản, kỹ thuật tạo prompt là sự khác biệt giữa chỉ dẫn mơ hồ và chỉ dẫn chính xác, như so sánh dưới đây minh họa. What is Prompt Engineering? -Kỹ thuật tạo prompt là thiết kế văn bản đầu vào sao cho bạn luôn nhận được kết quả mình cần. Nó không chỉ đơn thuần là đặt câu hỏi - mà còn là cấu trúc yêu cầu sao cho mô hình hiểu chính xác bạn muốn gì và cách để đáp ứng. +Kỹ thuật tạo prompt là thiết kế đoạn văn bản đầu vào sao cho luôn đạt kết quả bạn cần. Nó không chỉ đơn thuần là đặt câu hỏi - mà là cấu trúc các yêu cầu để mô hình hiểu chính xác bạn muốn gì và cách trả lời. -Hãy nghĩ giống như đưa hướng dẫn cho đồng nghiệp. "Sửa lỗi" thì mơ hồ. "Sửa lỗi null pointer exception trong UserService.java dòng 45 bằng cách thêm kiểm tra null" thì cụ thể. Các mô hình ngôn ngữ cũng tương tự - sự cụ thể và cấu trúc rất quan trọng. +Hãy tưởng tượng bạn đang đưa chỉ dẫn cho đồng nghiệp. “Sửa lỗi” thì mơ hồ. “Sửa lỗi null pointer exception trong UserService.java dòng 45 bằng cách thêm kiểm tra null” thì cụ thể hơn. Các mô hình ngôn ngữ cũng tương tự — sự cụ thể và cấu trúc rất quan trọng. -Sơ đồ dưới đây cho thấy cách LangChain4j đóng vai trò trong bức tranh này — kết nối các mẫu prompt của bạn với mô hình thông qua các thành phần xây dựng SystemMessage và UserMessage. +Sơ đồ dưới đây cho thấy LangChain4j đóng vai trò thế nào trong bức tranh này — kết nối các mẫu prompt của bạn với mô hình thông qua các thành phần SystemMessage và UserMessage. How LangChain4j Fits -LangChain4j cung cấp cơ sở hạ tầng — kết nối mô hình, bộ nhớ và các loại tin nhắn — trong khi các mẫu prompt chỉ là văn bản có cấu trúc cẩn thận bạn gửi qua cơ sở hạ tầng đó. Các thành phần then chốt là `SystemMessage` (đặt hành vi và vai trò AI) và `UserMessage` (chứa yêu cầu thực tế của bạn). +LangChain4j cung cấp hạ tầng — kết nối mô hình, bộ nhớ và các loại tin nhắn — trong khi các mẫu prompt chỉ là các đoạn văn bản được cấu trúc cẩn thận bạn gửi qua hạ tầng đó. Các thành phần chính là `SystemMessage` (đặt hành vi và vai trò AI) và `UserMessage` (chứa yêu cầu thực tế của bạn). ## Các Nguyên Tắc Cơ Bản của Kỹ Thuật Tạo Prompt -Năm kỹ thuật cốt lõi dưới đây tạo nền tảng cho kỹ thuật tạo prompt hiệu quả. Mỗi kỹ thuật giải quyết một khía cạnh khác nhau trong cách bạn giao tiếp với các mô hình ngôn ngữ. +Năm kỹ thuật cốt lõi dưới đây là nền tảng của kỹ thuật tạo prompt hiệu quả. Mỗi kỹ thuật giải quyết một khía cạnh khác nhau của cách bạn giao tiếp với các mô hình ngôn ngữ. Five Prompt Engineering Patterns Overview -Trước khi đi sâu vào các mẫu nâng cao trong module này, chúng ta hãy ôn lại năm kỹ thuật tạo prompt cơ bản. Đây là những khối xây dựng mà mọi kỹ sư prompt đều nên biết. Nếu bạn đã làm qua [module Khởi Đầu Nhanh](../00-quick-start/README.md#2-prompt-patterns), bạn đã thấy chúng hoạt động — đây là khuôn khổ khái niệm đằng sau chúng. +Trước khi đi sâu vào các mẫu nâng cao trong module này, hãy xem lại năm kỹ thuật tạo prompt nền tảng. Đây là những khối xây dựng mà mọi kỹ sư prompt nên biết. ### Zero-Shot Prompting -Cách tiếp cận đơn giản nhất: đưa cho mô hình một hướng dẫn trực tiếp mà không có ví dụ. Mô hình dựa hoàn toàn vào việc huấn luyện để hiểu và thực hiện nhiệm vụ. Cách này hiệu quả với các yêu cầu đơn giản mà hành vi mong đợi rõ ràng. +Cách đơn giản nhất: đưa cho mô hình một chỉ dẫn trực tiếp không kèm ví dụ. Mô hình hoàn toàn dựa vào đào tạo để hiểu và thực hiện nhiệm vụ. Cách này hiệu quả với các yêu cầu đơn giản mà hành vi mong đợi rõ ràng. Zero-Shot Prompting -*Hướng dẫn trực tiếp không có ví dụ — mô hình suy luận nhiệm vụ chỉ qua hướng dẫn* +*Chỉ dẫn trực tiếp không kèm ví dụ — mô hình suy luận nhiệm vụ chỉ qua chỉ dẫn* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; @@ -87,15 +87,15 @@ String response = model.chat(prompt); // Phản hồi: "Tích cực" ``` -**Khi nào sử dụng:** Phân loại đơn giản, câu hỏi trực tiếp, dịch thuật hoặc bất kỳ nhiệm vụ nào mô hình có thể xử lý mà không cần hướng dẫn thêm. +**Khi nào dùng:** Phân loại đơn giản, câu hỏi trực tiếp, dịch thuật, hoặc bất kỳ nhiệm vụ nào mô hình có thể làm mà không cần hướng dẫn thêm. ### Few-Shot Prompting -Cung cấp các ví dụ thể hiện mẫu bạn muốn mô hình theo. Mô hình học định dạng đầu vào-đầu ra mong đợi từ ví dụ của bạn và áp dụng cho các đầu vào mới. Điều này cải thiện đáng kể sự nhất quán với các nhiệm vụ mà định dạng hoặc hành vi mong muốn không rõ ràng. +Cung cấp các ví dụ thể hiện mẫu bạn muốn mô hình theo. Mô hình học định dạng đầu vào - đầu ra mong đợi từ ví dụ của bạn và áp dụng cho dữ liệu mới. Điều này cải thiện đáng kể tính nhất quán cho các nhiệm vụ mà định dạng hoặc hành vi mong muốn không rõ ràng. Few-Shot Prompting -*Học từ ví dụ — mô hình nhận dạng mẫu và áp dụng cho đầu vào mới* +*Học từ ví dụ — mô hình nhận diện mẫu và áp dụng cho đầu vào mới* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Khi nào sử dụng:** Phân loại tùy chỉnh, định dạng đồng nhất, nhiệm vụ chuyên ngành, hoặc khi kết quả zero-shot không nhất quán. +**Khi nào dùng:** Phân loại tùy chỉnh, định dạng đồng nhất, nhiệm vụ đặc thù lĩnh vực, hoặc khi kết quả zero-shot không ổn định. ### Chain of Thought -Yêu cầu mô hình trình bày suy luận từng bước. Thay vì nhảy ngay đến câu trả lời, mô hình phân tích vấn đề và giải quyết từng phần một cách rõ ràng. Cách này cải thiện độ chính xác cho các bài toán toán học, logic và suy luận nhiều bước. +Yêu cầu mô hình thể hiện suy luận từng bước. Thay vì nhảy ngay đến câu trả lời, mô hình phân tích vấn đề và xử lý từng phần rõ ràng. Điều này cải thiện độ chính xác cho toán học, logic, và các nhiệm vụ suy luận nhiều bước. Chain of Thought Prompting -*Suy luận từng bước — phân tách vấn đề phức tạp thành các bước logic rõ ràng* +*Suy luận từng bước — phân chia vấn đề phức tạp thành các bước logic rõ ràng* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// Mô hình này cho thấy: 15 - 8 = 7, sau đó 7 + 12 = 19 quả táo +// Mô hình cho thấy: 15 - 8 = 7, sau đó 7 + 12 = 19 quả táo ``` -**Khi nào sử dụng:** Bài toán toán học, câu đố logic, gỡ lỗi, hoặc bất kỳ nhiệm vụ nào khi việc thể hiện quá trình suy luận giúp tăng độ chính xác và tin cậy. +**Khi nào dùng:** Bài toán toán học, câu đố logic, gỡ lỗi, hoặc bất kỳ nhiệm vụ nào mà việc thể hiện quá trình suy luận giúp tăng độ chính xác và độ tin cậy. ### Role-Based Prompting -Đặt vai trò hoặc persona cho AI trước khi đặt câu hỏi của bạn. Điều này cung cấp ngữ cảnh định hình giọng điệu, chiều sâu và trọng tâm của phản hồi. Một "kiến trúc sư phần mềm" sẽ đưa ra lời khuyên khác so với một "lập trình viên mới vào nghề" hoặc "kiểm toán viên bảo mật". +Chỉ định một persona hoặc vai trò cho AI trước khi đặt câu hỏi. Điều này cung cấp ngữ cảnh ảnh hưởng đến giọng điệu, độ sâu, và trọng tâm câu trả lời. Một "kiến trúc sư phần mềm" sẽ đưa lời khuyên khác với "lập trình viên mới" hay "kiểm toán viên bảo mật". Role-Based Prompting -*Đặt ngữ cảnh và vai trò — cùng một câu hỏi nhưng nhận được phản hồi khác biệt tùy theo vai trò được giao* +*Đặt ngữ cảnh và vai trò — cùng một câu hỏi nhưng câu trả lời thay đổi tùy vai trò được gán* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**Khi nào sử dụng:** Đánh giá code, gia sư, phân tích chuyên ngành, hoặc khi bạn cần phản hồi phù hợp với trình độ chuyên môn hoặc góc nhìn cụ thể. +**Khi nào dùng:** Đánh giá mã nguồn, dạy kèm, phân tích lĩnh vực đặc thù, hoặc khi bạn cần câu trả lời phù hợp với cấp độ chuyên môn hoặc góc nhìn nhất định. ### Prompt Templates -Tạo prompt có thể tái sử dụng với các chỗ chứa biến. Thay vì viết prompt mới mỗi lần, định nghĩa một mẫu và điền giá trị khác nhau. Lớp `PromptTemplate` của LangChain4j giúp việc này rất dễ dàng với cú pháp `{{variable}}`. +Tạo các prompt có thể tái sử dụng với các biến placeholder. Thay vì viết prompt mới mỗi lần, xác định một khuôn mẫu một lần rồi thay giá trị khác nhau. Lớp `PromptTemplate` của LangChain4j cho phép điều này dễ dàng với cú pháp `{{variable}}`. Prompt Templates -*Prompt tái sử dụng với biến — một mẫu, nhiều lần dùng* +*Prompt tái sử dụng với các biến placeholder — một khuôn mẫu, nhiều lần dùng* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**Khi nào sử dụng:** Truy vấn lặp đi lặp lại với dữ liệu khác nhau, xử lý hàng loạt, xây dựng quy trình AI tái sử dụng, hoặc bất kỳ tình huống nào cấu trúc prompt giữ nguyên mà dữ liệu thay đổi. +**Khi nào dùng:** Các truy vấn lặp lại với đầu vào khác nhau, xử lý hàng loạt, xây dựng quy trình AI tái sử dụng, hoặc bất cứ trường hợp nào cấu trúc prompt giữ nguyên nhưng dữ liệu thay đổi. --- -Năm nguyên tắc cơ bản này cung cấp cho bạn bộ công cụ vững chắc cho hầu hết các nhiệm vụ tạo prompt. Phần còn lại của module sẽ xây dựng trên đó với **tám mẫu nâng cao** tận dụng khả năng điều khiển suy luận, tự đánh giá và đầu ra có cấu trúc của GPT-5.2. +Năm kỹ thuật cơ bản này cung cấp cho bạn bộ công cụ vững chắc cho hầu hết nhiệm vụ tạo prompt. Phần còn lại của module xây dựng dựa trên đó với **tám mẫu nâng cao** tận dụng khả năng kiểm soát suy luận, tự đánh giá, và đầu ra có cấu trúc của GPT-5.2. ## Các Mẫu Nâng Cao -Sau khi đã hiểu cơ bản, chúng ta chuyển sang tám mẫu nâng cao tạo nên sự độc đáo của module này. Không phải vấn đề nào cũng cần cùng một cách tiếp cận. Một số câu hỏi cần câu trả lời nhanh, số khác cần suy nghĩ sâu. Một vài cần thể hiện suy luận cụ thể, số khác chỉ cần kết quả. Mỗi mẫu dưới đây được tối ưu cho bối cảnh khác nhau — và điều khiển suy luận của GPT-5.2 càng làm rõ sự khác biệt đó. +Sau khi đã có kiến thức cơ bản, ta chuyển sang tám mẫu nâng cao làm module này nổi bật. Không phải vấn đề nào cũng dùng chung một cách tiếp cận. Một số câu hỏi cần câu trả lời nhanh, số khác cần suy nghĩ sâu. Một số cần suy luận rõ ràng, số khác chỉ cần kết quả. Mỗi mẫu dưới đây được tối ưu cho từng tình huống — và khả năng kiểm soát suy luận của GPT-5.2 làm các khác biệt này càng rõ ràng hơn. Eight Prompting Patterns -*Tổng quan về tám mẫu kỹ thuật tạo prompt và trường hợp sử dụng của chúng* +*Tổng quan tám mẫu kỹ thuật tạo prompt và các trường hợp sử dụng* -GPT-5.2 thêm một chiều kích nữa vào các mẫu này: *điều khiển suy luận*. Thanh trượt dưới đây cho thấy bạn có thể điều chỉnh mức độ suy nghĩ của mô hình — từ trả lời nhanh và trực tiếp đến phân tích sâu và toàn diện. +GPT-5.2 thêm chiều kích mới vào các mẫu này: *kiểm soát suy luận*. Thanh trượt dưới đây cho thấy bạn có thể điều chỉnh mức độ suy nghĩ của mô hình — từ trả lời nhanh, trực tiếp đến phân tích sâu, kỹ lưỡng. Reasoning Control with GPT-5.2 -*Điều khiển suy luận của GPT-5.2 cho phép bạn chỉ định mức độ suy nghĩ của mô hình — từ câu trả lời nhanh tới phân tích sâu sắc* +*Kiểm soát suy luận của GPT-5.2 cho phép bạn chỉ định mô hình nên suy nghĩ bao nhiêu — từ trả lời nhanh đến tìm hiểu sâu* -**Nhiệt Tình Thấp (Nhanh & Tập Trung)** - Dùng cho câu hỏi đơn giản bạn muốn câu trả lời nhanh, trực tiếp. Mô hình suy luận tối thiểu - tối đa 2 bước. Dùng cho tính toán, tra cứu hoặc câu hỏi đơn giản. +**Nhiệt Tình Thấp (Nhanh & Tập Trung)** - Dành cho câu hỏi đơn giản bạn muốn câu trả lời nhanh, trực tiếp. Mô hình suy luận tối thiểu - tối đa 2 bước. Dùng cho phép tính, tra cứu, hoặc câu hỏi đơn giản. ```java String prompt = """ @@ -220,11 +220,11 @@ String response = chatModel.chat(prompt); ``` > 💡 **Khám phá với GitHub Copilot:** Mở [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) và hỏi: -> - "Sự khác biệt giữa mẫu nhiệt tình thấp và cao trong tạo prompt là gì?" -> - "Các thẻ XML trong prompt giúp cấu trúc phản hồi AI như thế nào?" -> - "Khi nào nên dùng mẫu tự phản ánh so với hướng dẫn trực tiếp?" +> - "Sự khác biệt giữa mẫu nhiệt tình thấp và cao là gì?" +> - "Các thẻ XML trong prompt giúp cấu trúc câu trả lời AI như thế nào?" +> - "Khi nào nên dùng mẫu tự phản chiếu so với chỉ dẫn trực tiếp?" -**Nhiệt Tình Cao (Sâu & Toàn Diện)** - Dùng cho vấn đề phức tạp bạn muốn phân tích toàn diện. Mô hình khám phá chi tiết và trình bày suy luận cụ thể. Dùng cho thiết kế hệ thống, quyết định kiến trúc, hoặc nghiên cứu phức tạp. +**Nhiệt Tình Cao (Sâu & Kỹ Lưỡng)** - Dành cho vấn đề phức tạp cần phân tích toàn diện. Mô hình suy nghĩ kỹ lưỡng và trình bày lý luận chi tiết. Dùng cho thiết kế hệ thống, quyết định kiến trúc, hoặc nghiên cứu phức tạp. ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**Thực Thi Nhiệm Vụ (Tiến Trình Từng Bước)** - Dùng quy trình nhiều bước. Mô hình cung cấp kế hoạch trước, mô tả từng bước khi thực hiện, rồi đưa ra tóm tắt. Dùng cho di cư, triển khai hoặc quy trình đa bước. +**Thực Thi Nhiệm Vụ (Tiến Trình Từng Bước)** - Dành cho quy trình nhiều bước. Mô hình cung cấp kế hoạch ban đầu, mô tả từng bước khi thực hiện, rồi tóm tắt lại. Dùng cho di cư, triển khai, hoặc quy trình nhiều bước. ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Prompt chuỗi suy nghĩ (Chain-of-Thought) yêu cầu mô hình trình bày quá trình suy luận, cải thiện độ chính xác công việc phức tạp. Các bước từng bước giúp cả người và AI hiểu logic. +Chain-of-Thought prompting yêu cầu mô hình trình bày quá trình suy luận, tăng độ chính xác cho các nhiệm vụ phức tạp. Phân tích từng bước giúp cả người và AI hiểu rõ logic. -> **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Hỏi về mẫu này: -> - "Làm thế nào để điều chỉnh mẫu thực thi nhiệm vụ cho các công việc chạy lâu?" -> - "Các thực tiễn tốt nhất để cấu trúc phần mở đầu công cụ trong ứng dụng sản xuất là gì?" -> - "Làm sao để ghi lại và hiển thị tiến trình trung gian trong giao diện người dùng?" +> **🤖 Thử với Chat [GitHub Copilot](https://github.com/features/copilot):** Hỏi về mẫu này: +> - "Làm sao tôi điều chỉnh mẫu thực thi nhiệm vụ cho các thao tác chạy lâu?" +> - "Các thực hành tốt nhất khi cấu trúc giới thiệu công cụ trong ứng dụng sản xuất là gì?" +> - "Làm sao tôi có thể thu thập và hiển thị tiến trình trung gian trong giao diện người dùng?" -Sơ đồ dưới thể hiện quy trình Kế Hoạch → Thực Thi → Tóm Tắt. +Sơ đồ dưới đây minh họa quy trình Lập Kế Hoạch → Thực Thi → Tóm Tắt. Task Execution Pattern -*Quy trình Kế Hoạch → Thực Thi → Tóm Tắt cho các nhiệm vụ đa bước* +*Quy trình Lập Kế Hoạch → Thực Thi → Tóm Tắt cho nhiệm vụ đa bước* -**Mã Tự Đánh Giá** - Dùng để tạo mã chất lượng sản xuất. Mô hình tạo code theo chuẩn chất lượng với xử lý lỗi thích hợp. Dùng khi xây dựng tính năng hoặc dịch vụ mới. +**Mã Tự Phản Chiếu** - Dành cho tạo mã chất lượng sản xuất. Mô hình tạo mã theo tiêu chuẩn sản xuất với xử lý lỗi thích hợp. Dùng khi xây dựng tính năng hay dịch vụ mới. ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Sơ đồ dưới đây mô tả vòng lặp cải tiến lặp đi lặp lại — tạo mã, đánh giá, xác định điểm yếu, tinh chỉnh cho đến khi mã đạt chuẩn sản xuất. +Sơ đồ dưới đây thể hiện vòng lặp cải tiến tuần hoàn — tạo, đánh giá, xác định điểm yếu, và tinh chỉnh cho tới khi mã đạt chuẩn. Self-Reflection Cycle -*Vòng lặp cải tiến lặp lại - tạo, đánh giá, xác định lỗi, cải thiện, lặp lại* +*Vòng lặp cải tiến tuần hoàn - tạo, đánh giá, nhận diện vấn đề, cải thiện, lặp lại* -**Phân Tích Có Cấu Trúc** - Dùng để đánh giá nhất quán. Mô hình xem xét code theo khung cố định (đúng sai, thực hành tốt, hiệu năng, bảo mật, khả năng bảo trì). Dùng cho đánh giá code hoặc kiểm định chất lượng. +**Phân Tích Có Cấu Trúc** - Dành cho đánh giá nhất quán. Mô hình đánh giá mã theo khung cố định (độ chính xác, thực hành, hiệu năng, bảo mật, khả năng bảo trì). Dùng cho đánh giá mã hoặc đánh giá chất lượng. ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Hỏi về phân tích có cấu trúc: -> - "Làm sao tùy chỉnh khung phân tích cho các dạng đánh giá code khác nhau?" -> - "Cách tốt nhất để phân tích và xử lý đầu ra có cấu trúc một cách lập trình là gì?" -> - "Làm thế nào để đảm bảo mức độ nghiêm trọng nhất quán qua các phiên đánh giá khác nhau?" +> **🤖 Thử với Chat [GitHub Copilot](https://github.com/features/copilot):** Hỏi về phân tích có cấu trúc: +> - "Làm thế nào tùy chỉnh khung phân tích cho các loại đánh giá mã khác nhau?" +> - "Cách tốt nhất để phân tích và xử lý đầu ra có cấu trúc bằng lập trình là gì?" +> - "Làm sao đảm bảo mức độ nghiêm trọng đồng nhất qua các phiên đánh giá khác nhau?" -Sơ đồ dưới đây thể hiện khung phân tích tổ chức đánh giá code thành các hạng mục nhất quán với mức độ nghiêm trọng. +Sơ đồ dưới đây mô tả cách khung phân tích tổ chức đánh giá mã thành các hạng mục đồng nhất với mức độ nghiêm trọng. Structured Analysis Pattern -*Khung đánh giá code nhất quán với các mức độ nghiêm trọng* +*Khung cho đánh giá mã nhất quán với mức độ nghiêm trọng* -**Trò Chuyện Nhiều Vòng** - Dùng cho các cuộc hội thoại cần ngữ cảnh. Mô hình nhớ các tin nhắn trước và xây dựng dựa trên đó. Dùng cho các phiên trợ giúp tương tác hoặc hỏi đáp phức tạp. +**Trò Chuyện Nhiều Lần** - Dành cho các cuộc hội thoại cần bối cảnh. Mô hình nhớ các tin nhắn trước và xây dựng dựa trên chúng. Dùng cho các buổi trợ giúp tương tác hoặc Q&A phức tạp. ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -Sơ đồ dưới đây trực quan hóa cách ngữ cảnh cuộc hội thoại tích lũy qua nhiều vòng và liên quan tới giới hạn token của mô hình. +Sơ đồ dưới đây minh họa cách bối cảnh hội thoại tích lũy qua nhiều lượt và liên quan đến giới hạn token của mô hình. Context Memory -*Cách ngữ cảnh hội thoại được tích lũy qua nhiều lượt cho đến giới hạn token* -**Lý luận từng bước** - Dành cho các bài toán yêu cầu logic rõ ràng. Mô hình trình bày lý luận cụ thể cho từng bước. Sử dụng cách này cho các bài toán toán học, câu đố logic, hoặc khi bạn cần hiểu quy trình suy nghĩ. +*Cách bối cảnh hội thoại tích tụ qua nhiều lượt cho đến khi đạt giới hạn token* + +**Lý Luận Từng Bước** - Dành cho các vấn đề cần logic rõ ràng. Mô hình thể hiện suy luận rõ ràng từng bước. Dùng cho bài toán toán học, câu đố logic, hoặc khi bạn cần hiểu quá trình suy nghĩ. ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -Sơ đồ dưới đây minh họa cách mô hình phân tách các bài toán thành các bước logic rõ ràng, được đánh số. - -Mẫu từng bước +Sơ đồ dưới đây minh họa cách mô hình phân chia vấn đề thành các bước logic rõ ràng, đánh số từng bước. -*Phân tách vấn đề thành các bước logic rõ ràng* +Step-by-Step Pattern +*Phân tích vấn đề thành các bước logic rõ ràng* -**Đầu ra có giới hạn** - Dành cho câu trả lời yêu cầu định dạng cụ thể. Mô hình tuân thủ nghiêm ngặt các quy tắc về định dạng và độ dài. Sử dụng cách này cho các bản tóm tắt hoặc khi bạn cần kết quả chính xác theo cấu trúc yêu cầu. +**Đầu ra có giới hạn** - Dành cho các phản hồi yêu cầu định dạng cụ thể. Mô hình tuân thủ nghiêm ngặt các quy tắc về định dạng và độ dài. Sử dụng điều này cho các bản tóm tắt hoặc khi bạn cần cấu trúc đầu ra chính xác. ```java String prompt = """ @@ -419,190 +419,190 @@ String prompt = """ String response = chatModel.chat(prompt); ``` + +Sơ đồ sau thể hiện cách các ràng buộc hướng dẫn mô hình tạo ra đầu ra tuân thủ nghiêm ngặt các yêu cầu định dạng và độ dài của bạn. -Sơ đồ sau cho thấy cách ràng buộc định dạng hướng dẫn mô hình tạo ra đầu ra tuân thủ đúng định dạng và độ dài của bạn. +Constrained Output Pattern -Mẫu đầu ra có giới hạn - -*Tuân thủ nghiêm ngặt các yêu cầu về định dạng, độ dài và cấu trúc* +*Thực thi yêu cầu cụ thể về định dạng, độ dài và cấu trúc* ## Chạy Ứng Dụng -**Xác minh triển khai:** +**Xác minh triển khai:** -Đảm bảo tồn tại tệp `.env` trong thư mục gốc với thông tin xác thực Azure (đã tạo trong Module 01). Chạy từ thư mục module (`02-prompt-engineering/`): +Đảm bảo file `.env` tồn tại trong thư mục gốc với thông tin đăng nhập Azure (đã tạo trong Module 01). Chạy lệnh này từ thư mục module (`02-prompt-engineering/`): -**Bash:** +**Bash:** ```bash cat ../.env # Nên hiển thị AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # Nên hiển thị AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` + +**Khởi động ứng dụng:** -**Khởi động ứng dụng:** - -> **Lưu ý:** Nếu bạn đã khởi động tất cả các ứng dụng bằng `./start-all.sh` từ thư mục gốc (như mô tả trong Module 01), module này đã chạy trên cổng 8083. Bạn có thể bỏ qua các lệnh khởi động bên dưới và truy cập trực tiếp http://localhost:8083. +> **Lưu ý:** Nếu bạn đã khởi động tất cả ứng dụng bằng `./start-all.sh` từ thư mục gốc (như mô tả trong Module 01), module này đã chạy trên cổng 8083. Bạn có thể bỏ qua các lệnh khởi động dưới đây và truy cập trực tiếp http://localhost:8083. **Lựa chọn 1: Sử dụng Spring Boot Dashboard (Khuyên dùng cho người dùng VS Code)** -Dev container bao gồm tiện ích mở rộng Spring Boot Dashboard, cung cấp giao diện trực quan để quản lý tất cả các ứng dụng Spring Boot. Bạn có thể tìm thấy nó trong Thanh Hoạt Động bên trái của VS Code (tìm biểu tượng Spring Boot). +Dev container bao gồm tiện ích mở rộng Spring Boot Dashboard, cung cấp giao diện trực quan để quản lý tất cả ứng dụng Spring Boot. Bạn có thể tìm thấy nó trên Thanh Hoạt Động bên trái VS Code (tìm biểu tượng Spring Boot). -Từ Spring Boot Dashboard, bạn có thể: -- Xem tất cả các ứng dụng Spring Boot có trong workspace -- Khởi động/dừng ứng dụng chỉ với một cú nhấp chuột -- Xem nhật ký ứng dụng theo thời gian thực -- Giám sát trạng thái ứng dụng +Từ Spring Boot Dashboard, bạn có thể: +- Xem tất cả ứng dụng Spring Boot có trong workspace +- Bắt đầu/dừng ứng dụng chỉ với một cú nhấp +- Xem nhật ký ứng dụng theo thời gian thực +- Giám sát trạng thái ứng dụng -Chỉ cần nhấn nút play bên cạnh "prompt-engineering" để khởi động module này, hoặc khởi động tất cả modules cùng lúc. +Chỉ cần nhấp nút chạy bên cạnh "prompt-engineering" để khởi động module này, hoặc khởi động tất cả các module cùng lúc. -Bảng điều khiển Spring Boot +Spring Boot Dashboard -*Spring Boot Dashboard trong VS Code — khởi động, dừng, và giám sát tất cả các module từ một chỗ* +*Spring Boot Dashboard trong VS Code — khởi động, dừng và giám sát tất cả các module tại một nơi* -**Lựa chọn 2: Sử dụng script shell** +**Lựa chọn 2: Sử dụng shell script** -Khởi động tất cả các ứng dụng web (modules 01-04): +Khởi động tất cả ứng dụng web (module 01-04): -**Bash:** +**Bash:** ```bash cd .. # Từ thư mục gốc ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd .. # Từ thư mục gốc .\start-all.ps1 ``` - + Hoặc chỉ khởi động module này: -**Bash:** +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` + +Cả hai script tự động tải biến môi trường từ file `.env` ở thư mục gốc và sẽ xây dựng các JAR nếu chúng chưa tồn tại. -Cả hai script tự động nạp biến môi trường từ tệp `.env` ở thư mục gốc và sẽ build các JAR nếu chưa tồn tại. - -> **Lưu ý:** Nếu bạn muốn build thủ công tất cả các module trước khi khởi động: -> -> **Bash:** +> **Lưu ý:** Nếu bạn muốn xây dựng tất cả các module thủ công trước khi khởi động: +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -> **PowerShell:** + +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - + Mở http://localhost:8083 trong trình duyệt của bạn. -**Để dừng:** +**Để dừng:** -**Bash:** +**Bash:** ```bash ./stop.sh # Chỉ mô-đun này # Hoặc cd .. && ./stop-all.sh # Tất cả các mô-đun ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # Chỉ mô-đun này # Hoặc -cd ..; .\stop-all.ps1 # Tất cả mô-đun +cd ..; .\stop-all.ps1 # Tất cả các mô-đun ``` - + ## Ảnh chụp màn hình ứng dụng -Đây là giao diện chính của module prompt engineering, nơi bạn có thể thử nghiệm tất cả tám mẫu cạnh nhau. +Đây là giao diện chính của module kỹ thuật prompt, nơi bạn có thể thử nghiệm cùng lúc tất cả tám mẫu. -Trang chủ Dashboard +Dashboard Home -*Bảng điều khiển chính hiển thị 8 mẫu prompt engineering cùng với đặc điểm và cách sử dụng* +*Bảng điều khiển chính hiển thị tất cả 8 mẫu kỹ thuật prompt với đặc điểm và trường hợp sử dụng* ## Khám phá các Mẫu -Giao diện web cho phép bạn thử nghiệm các chiến lược prompt khác nhau. Mỗi mẫu giải quyết các vấn đề khác nhau - hãy thử để xem khi nào từng cách thực sự hiệu quả. +Giao diện web cho phép bạn thử nghiệm các chiến lược prompt khác nhau. Mỗi mẫu giải quyết các vấn đề khác nhau - hãy thử để xem khi nào cách tiếp cận nào phát huy tác dụng. -> **Lưu ý: Streaming so với Không streaming** — Mỗi trang mẫu đều cung cấp hai nút: **🔴 Phát trực tiếp (Live)** và tùy chọn **Không streaming**. Streaming sử dụng Server-Sent Events (SSE) để hiển thị token theo thời gian thực khi mô hình tạo ra chúng, giúp bạn thấy tiến trình ngay lập tức. Tùy chọn không streaming sẽ đợi đến khi trả về toàn bộ phản hồi mới hiển thị. Với các prompt đòi hỏi suy luận sâu (ví dụ: High Eagerness, Self-Reflecting Code), gọi không streaming có thể mất rất lâu — đôi khi vài phút — mà không có phản hồi trực quan. **Dùng streaming khi thử nghiệm các prompt phức tạp** để bạn thấy mô hình đang hoạt động và tránh hiểu nhầm là yêu cầu đã hết time out. -> -> **Lưu ý: Yêu cầu trình duyệt** — Tính năng streaming sử dụng Fetch Streams API (`response.body.getReader()`) cần trình duyệt đầy đủ (Chrome, Edge, Firefox, Safari). Nó **không hoạt động** trong Simple Browser tích hợp của VS Code vì webview không hỗ trợ ReadableStream API. Nếu bạn dùng Simple Browser, các nút không streaming vẫn hoạt động bình thường — chỉ các nút streaming bị ảnh hưởng. Mở `http://localhost:8083` bằng trình duyệt bên ngoài để trải nghiệm đầy đủ. +> **Lưu ý: Streaming và Không Streaming** — Mỗi trang mẫu cung cấp hai nút: **🔴 Stream Response (Live)** và tùy chọn **Không streaming**. Streaming sử dụng Server-Sent Events (SSE) để hiển thị token theo thời gian thực khi mô hình tạo ra chúng, giúp bạn thấy tiến trình ngay lập tức. Tùy chọn không streaming chờ cho đến khi toàn bộ phản hồi được tạo xong mới hiển thị. Với các prompt kích hoạt suy luận sâu (ví dụ: High Eagerness, Self-Reflecting Code), gọi không streaming có thể mất rất lâu — đôi khi vài phút — mà không có phản hồi rõ ràng. **Sử dụng streaming khi thử nghiệm các prompt phức tạp** để bạn có thể thấy mô hình đang hoạt động và tránh cảm giác yêu cầu bị treo. +> +> **Lưu ý: Yêu cầu trình duyệt** — Tính năng streaming sử dụng Fetch Streams API (`response.body.getReader()`), yêu cầu trình duyệt đầy đủ (Chrome, Edge, Firefox, Safari). Nó **không** hoạt động trong Simple Browser tích hợp của VS Code, vì webview của nó không hỗ trợ ReadableStream API. Nếu bạn dùng Simple Browser, các nút không streaming vẫn dùng bình thường — chỉ có nút streaming mới bị ảnh hưởng. Mở `http://localhost:8083` trong trình duyệt ngoài để có trải nghiệm đầy đủ. -### Low vs High Eagerness +### Tham Vọng Thấp và Tham Vọng Cao -Hỏi một câu đơn giản như "15% của 200 là bao nhiêu?" bằng Low Eagerness. Bạn sẽ nhận được câu trả lời trực tiếp ngay lập tức. Bây giờ hỏi một câu phức tạp như "Thiết kế chiến lược caching cho API có lưu lượng cao" với High Eagerness. Nhấn **🔴 Phát trực tiếp (Live)** và theo dõi quá trình suy luận chi tiết của mô hình từng token một. Cùng một mô hình, cùng dạng câu hỏi - nhưng prompt xác định mức độ suy nghĩ. +Hỏi câu đơn giản như "15% của 200 là bao nhiêu?" với Tham Vọng Thấp. Bạn sẽ nhận câu trả lời ngay lập tức, trực tiếp. Bây giờ thử hỏi điều phức tạp hơn như "Thiết kế chiến lược caching cho API lưu lượng lớn" với Tham Vọng Cao. Nhấp **🔴 Stream Response (Live)** và quan sát cách mô hình suy luận chi tiết hiện dần qua từng token. Mô hình vẫn như cũ, câu hỏi như cũ nhưng prompt chỉ đạo mức độ suy nghĩ cho mô hình. -### Thực thi tác vụ (Tool Preambles) +### Thực thi Nhiệm vụ (Tool Preambles) -Các quy trình nhiều bước hưởng lợi từ việc lập kế hoạch trước và mô tả tiến trình. Mô hình sẽ phác thảo những việc sẽ làm, mô tả từng bước, rồi tóm tắt kết quả. +Các luồng công việc nhiều bước cần kế hoạch trước và mô tả tiến trình. Mô hình sẽ vạch ra những bước sẽ làm, mô tả từng bước, rồi tóm tắt kết quả. -### Self-Reflecting Code +### Mã Tự Phản Chiếu -Thử "Tạo dịch vụ xác thực email". Thay vì chỉ tạo code rồi dừng, mô hình sẽ tạo, đánh giá theo tiêu chí chất lượng, chỉ ra điểm yếu và cải tiến. Bạn sẽ thấy nó lặp lại cho đến khi code đạt chuẩn sản xuất. +Thử "Tạo dịch vụ kiểm tra email". Thay vì chỉ sinh code rồi dừng, mô hình sinh, đánh giá theo tiêu chuẩn chất lượng, nhận diện điểm yếu và cải thiện. Bạn sẽ thấy nó lặp đi lặp lại cho tới khi mã đạt chuẩn sản xuất. -### Phân tích cấu trúc +### Phân Tích Cấu Trúc -Đánh giá code cần khung đánh giá nhất quán. Mô hình phân tích code theo các hạng mục cố định (độ chính xác, thực hành, hiệu năng, bảo mật) với cấp độ nghiêm trọng. +Đánh giá code cần khung đánh giá nhất quán. Mô hình phân tích code theo các mục cố định (độ chính xác, thực hành, hiệu năng, bảo mật) với các mức độ nghiêm trọng. -### Chat đa lượt +### Hội Thoại Nhiều Lần -Hỏi "Spring Boot là gì?" rồi ngay lập tức tiếp tục với "Cho tôi xem một ví dụ". Mô hình nhớ câu hỏi đầu tiên và đưa ra ví dụ Spring Boot cụ thể. Nếu không có bộ nhớ, câu hỏi thứ hai sẽ quá chung chung. +Hỏi "Spring Boot là gì?" rồi ngay lập tức hỏi tiếp "Cho tôi ví dụ". Mô hình nhớ câu hỏi đầu và cho ví dụ Spring Boot cụ thể. Nếu không nhớ, câu hỏi thứ hai sẽ quá chung chung. -### Lý luận từng bước +### Suy Luận Từng Bước -Chọn một bài toán toán học và thử cả Step-by-Step Reasoning và Low Eagerness. Low eagerness chỉ cho bạn đáp án - nhanh nhưng mơ hồ. Lý luận từng bước cho thấy từng phép tính và quyết định. +Chọn một bài toán toán học và thử với cả Suy Luận Từng Bước và Tham Vọng Thấp. Tham Vọng Thấp chỉ cho bạn kết quả nhanh nhưng không rõ ràng, Suy Luận Từng Bước cho bạn thấy từng phép tính và quyết định. -### Đầu ra có giới hạn +### Đầu Ra Có Giới Hạn -Khi bạn cần định dạng hoặc số từ cụ thể, mẫu này giúp tuân thủ nghiêm ngặt. Thử tạo tóm tắt đúng 100 từ với dạng gạch đầu dòng. +Khi bạn cần định dạng hoặc số từ chính xác, mẫu này giúp bắt buộc mô hình tuân thủ nghiêm ngặt. Thử tạo một bản tóm tắt 100 từ chính xác ở dạng gạch đầu dòng. -## Bạn đang học gì thực sự +## Những Gì Bạn Thực Sự Học Được **Nỗ lực suy luận thay đổi mọi thứ** -GPT-5.2 cho phép bạn kiểm soát nỗ lực tính toán thông qua prompt. Nỗ lực thấp nghĩa là phản hồi nhanh với ít khám phá. Nỗ lực cao nghĩa là mô hình dành thời gian suy nghĩ sâu sắc. Bạn học cách điều chỉnh nỗ lực theo độ phức tạp công việc - không phí thời gian cho câu hỏi đơn giản, nhưng cũng không vội vàng trong những quyết định phức tạp. +GPT-5.2 cho phép bạn kiểm soát nỗ lực tính toán thông qua prompt. Nỗ lực thấp có nghĩa phản hồi nhanh với ít khám phá. Nỗ lực cao nghĩa mô hình dành thời gian suy nghĩ sâu hơn. Bạn học cách điều chỉnh nỗ lực phù hợp với độ phức tạp nhiệm vụ — đừng lãng phí thời gian cho câu hỏi đơn giản, nhưng cũng đừng vội vàng với quyết định phức tạp. -**Cấu trúc hướng dẫn hành vi** +**Cấu trúc dẫn hướng hành vi** -Bạn có thấy các thẻ XML trong prompt không? Chúng không chỉ là trang trí. Mô hình theo dõi chỉ dẫn có cấu trúc đáng tin cậy hơn so với văn bản tự do. Khi bạn cần quy trình nhiều bước hoặc logic phức tạp, cấu trúc giúp mô hình biết đang ở đâu và bước tiếp theo là gì. Sơ đồ dưới đây phân tích một prompt có cấu trúc tốt, chỉ ra cách các thẻ như ``, ``, ``, ``, và `` tổ chức hướng dẫn thành các phần rõ ràng. +Có để ý thấy các thẻ XML trong prompt không? Chúng không phải để trang trí. Mô hình tuân theo các hướng dẫn có cấu trúc đáng tin cậy hơn so với văn bản tự do. Khi bạn cần các quá trình nhiều bước hoặc logic phức tạp, cấu trúc giúp mô hình theo dõi vị trí và bước tiếp theo. Sơ đồ dưới đây phân tích một prompt được cấu trúc tốt, cho thấy cách các thẻ như ``, ``, ``, ``, và `` tổ chức chỉ dẫn của bạn thành các phần rõ ràng. -Cấu trúc Prompt +Prompt Structure -*Giải phẫu một prompt cấu trúc tốt với các phần rõ ràng và tổ chức theo kiểu XML* +*Cấu trúc của một prompt được tổ chức tốt với các phần rõ ràng và kiểu XML* **Chất lượng qua tự đánh giá** -Các mẫu tự phản ánh hoạt động bằng cách làm rõ các tiêu chí chất lượng. Thay vì hy vọng mô hình "làm đúng", bạn chỉ cho nó chính xác nghĩa của "đúng": logic chính xác, xử lý lỗi, hiệu năng, bảo mật. Mô hình có thể tự đánh giá đầu ra và cải tiến. Điều này biến việc tạo code từ một trò chơi may rủi thành một quy trình. +Các mẫu tự phản chiếu hoạt động bằng cách làm tiêu chuẩn chất lượng trở nên rõ ràng. Thay vì hy vọng mô hình “làm đúng”, bạn chỉ rõ "đúng" nghĩa là gì: logic chính xác, xử lý lỗi, hiệu năng, bảo mật. Mô hình có thể tự đánh giá đầu ra và cải thiện. Điều này biến việc sinh code từ trò may rủi thành quá trình có kiểm soát. -**Ngữ cảnh hữu hạn** +**Ngữ cảnh là hữu hạn** -Đàm thoại nhiều lượt hoạt động bằng cách kèm theo lịch sử tin nhắn với mỗi yêu cầu. Nhưng có giới hạn - mỗi mô hình có số token tối đa. Khi cuộc hội thoại mở rộng, bạn cần các chiến lược giữ ngữ cảnh liên quan mà không vượt quá giới hạn đó. Module này hướng dẫn bạn cách bộ nhớ hoạt động; sau này bạn sẽ học khi nào tóm tắt, khi nào quên, và khi nào truy xuất. +Hội thoại nhiều lượt hoạt động bằng cách bao gồm lịch sử tin nhắn trong mỗi yêu cầu. Nhưng có giới hạn - mỗi mô hình có số token tối đa. Khi hội thoại lớn dần, bạn cần chiến lược giữ ngữ cảnh liên quan mà không vượt quá giới hạn. Module này cho bạn thấy cách hoạt động của bộ nhớ; sau này bạn sẽ học khi nào nên tóm tắt, khi nào quên, và khi nào truy xuất. -## Bước tiếp theo +## Các bước Tiếp theo -**Module kế tiếp:** [03-rag - RAG (Tạo văn bản có hỗ trợ truy xuất)](../03-rag/README.md) +**Module tiếp theo:** [03-rag - RAG (Tạo sinh tăng cường truy xuất)](../03-rag/README.md) --- -**Điều hướng:** [← Trước: Module 01 - Giới thiệu](../01-introduction/README.md) | [Trở về Chính](../README.md) | [Tiếp theo: Module 03 - RAG →](../03-rag/README.md) +**Điều hướng:** [← Trước: Module 01 - Giới thiệu](../01-introduction/README.md) | [Quay lại trang chính](../README.md) | [Tiếp: Module 03 - RAG →](../03-rag/README.md) --- -**Tuyên bố từ chối trách nhiệm**: -Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo sự chính xác, nhưng xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc không chính xác. Tài liệu gốc bằng ngôn ngữ ban đầu của nó vẫn được coi là nguồn tham khảo uy tín nhất. Đối với thông tin quan trọng, chúng tôi khuyến nghị sử dụng dịch vụ dịch thuật chuyên nghiệp do con người thực hiện. Chúng tôi không chịu trách nhiệm về bất kỳ sự hiểu lầm hoặc diễn giải sai nào phát sinh từ việc sử dụng bản dịch này. +**Tuyên bố miễn trừ trách nhiệm**: +Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ gốc nên được coi là nguồn tin chính thức. Đối với thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm về bất kỳ hiểu lầm hoặc giải thích sai nào phát sinh từ việc sử dụng bản dịch này. \ No newline at end of file diff --git a/translations/vi/03-rag/README.md b/translations/vi/03-rag/README.md index ec52c88eb..ad36005ae 100644 --- a/translations/vi/03-rag/README.md +++ b/translations/vi/03-rag/README.md @@ -1,144 +1,143 @@ -# Module 03: RAG (Tạo nội dung tăng cường truy xuất) +# Module 03: RAG (Tăng cường truy xuất - Retrieval-Augmented Generation) ## Mục lục -- [Video hướng dẫn](../../../03-rag) -- [Bạn sẽ học được gì](../../../03-rag) -- [Yêu cầu trước](../../../03-rag) -- [Hiểu về RAG](../../../03-rag) - - [Phương pháp RAG nào được sử dụng trong hướng dẫn này?](../../../03-rag) -- [Cách hoạt động](../../../03-rag) - - [Xử lý tài liệu](../../../03-rag) - - [Tạo embeddings](../../../03-rag) - - [Tìm kiếm ngữ nghĩa](../../../03-rag) - - [Tạo câu trả lời](../../../03-rag) -- [Chạy ứng dụng](../../../03-rag) -- [Sử dụng ứng dụng](../../../03-rag) - - [Tải lên tài liệu](../../../03-rag) - - [Đặt câu hỏi](../../../03-rag) - - [Kiểm tra nguồn tham khảo](../../../03-rag) - - [Thử nghiệm với các câu hỏi](../../../03-rag) -- [Khái niệm chính](../../../03-rag) - - [Chiến lược chia đoạn](../../../03-rag) - - [Điểm tương đồng](../../../03-rag) - - [Lưu trữ trong bộ nhớ](../../../03-rag) - - [Quản lý cửa sổ ngữ cảnh](../../../03-rag) -- [Khi nào RAG quan trọng](../../../03-rag) -- [Bước tiếp theo](../../../03-rag) - -## Video hướng dẫn +- [Video Hướng dẫn](#video-hướng-dẫn) +- [Những gì bạn sẽ học](#những-gì-bạn-sẽ-học) +- [Yêu cầu trước](#yêu-cầu-trước) +- [Hiểu về RAG](#hiểu-về-rag) + - [Phương pháp RAG nào mà hướng dẫn này sử dụng?](#phương-pháp-rag-nào-mà-hướng-dẫn-này-sử-dụng) +- [Cách hoạt động](#cách-hoạt-động) + - [Xử lý tài liệu](#xử-lý-tài-liệu) + - [Tạo embedding](#tạo-embedding) + - [Tìm kiếm ngữ nghĩa](#tìm-kiếm-ngữ-nghĩa) + - [Tạo câu trả lời](#tạo-câu-trả-lời) +- [Chạy ứng dụng](#chạy-ứng-dụng) +- [Sử dụng ứng dụng](#sử-dụng-ứng-dụng) + - [Tải tài liệu lên](#tải-tài-liệu-lên) + - [Đặt câu hỏi](#đặt-câu-hỏi) + - [Kiểm tra nguồn tham khảo](#kiểm-tra-tham-chiếu-nguồn) + - [Thử nghiệm với các câu hỏi](#thử-nghiệm-với-các-câu-hỏi) +- [Các khái niệm chính](#các-khái-niệm-chính) + - [Chiến lược chia đoạn](#chiến-lược-chia-chunk) + - [Điểm tương đồng](#điểm-tương-đồng) + - [Lưu trữ trong bộ nhớ](#lưu-trữ-trong-bộ-nhớ) + - [Quản lý cửa sổ ngữ cảnh](#quản-lý-cửa-sổ-ngữ-cảnh) +- [Khi nào RAG quan trọng](#khi-nào-rag-quan-trọng) +- [Bước tiếp theo](#các-bước-tiếp-theo) + +## Video Hướng dẫn Xem buổi trực tiếp này giải thích cách bắt đầu với module này: RAG with LangChain4j - Live Session -## Bạn sẽ học được gì +## Những gì bạn sẽ học -Trong các module trước, bạn đã học cách trò chuyện với AI và cấu trúc các prompt hiệu quả. Nhưng có một giới hạn cơ bản: các mô hình ngôn ngữ chỉ biết những gì chúng học được trong quá trình huấn luyện. Chúng không thể trả lời các câu hỏi về chính sách của công ty bạn, tài liệu dự án của bạn, hoặc bất kỳ thông tin nào mà chúng không được huấn luyện. +Trong các module trước, bạn đã học cách trò chuyện với AI và cấu trúc các prompt hiệu quả. Nhưng có một giới hạn cơ bản: các mô hình ngôn ngữ chỉ biết những gì chúng học trong quá trình huấn luyện. Chúng không thể trả lời các câu hỏi về chính sách công ty bạn, tài liệu dự án của bạn, hoặc bất kỳ thông tin nào mà chúng không được huấn luyện. -RAG (Tạo nội dung tăng cường truy xuất) giải quyết vấn đề này. Thay vì cố gắng dạy mô hình thông tin của bạn (điều này tốn kém và không thực tế), bạn cho nó khả năng tìm kiếm qua các tài liệu của bạn. Khi ai đó hỏi câu hỏi, hệ thống sẽ tìm thông tin liên quan và thêm nó vào prompt. Mô hình sau đó trả lời dựa trên ngữ cảnh được truy xuất đó. +RAG (Tăng cường truy xuất) giải quyết vấn đề này. Thay vì cố gắng dạy mô hình thông tin của bạn (điều này tốn kém và không thực tế), bạn cho nó khả năng tìm kiếm trong các tài liệu của bạn. Khi ai đó đặt câu hỏi, hệ thống tìm thông tin liên quan và bao gồm nó vào prompt. Mô hình sau đó trả lời dựa trên ngữ cảnh đã truy xuất. -Hãy coi RAG như việc cung cấp cho mô hình một thư viện tham khảo. Khi bạn đặt câu hỏi, hệ thống: +Hãy nghĩ về RAG như việc cung cấp cho mô hình một thư viện tham khảo. Khi bạn đặt câu hỏi, hệ thống: 1. **Truy vấn người dùng** - Bạn đặt câu hỏi -2. **Embedding** - Chuyển câu hỏi thành vector -3. **Tìm kiếm vector** - Tìm các đoạn tài liệu tương tự +2. **Embedding** - Chuyển câu hỏi của bạn thành vector +3. **Tìm kiếm Vector** - Tìm các đoạn tài liệu tương tự 4. **Tập hợp ngữ cảnh** - Thêm các đoạn liên quan vào prompt 5. **Phản hồi** - LLM tạo câu trả lời dựa trên ngữ cảnh -Điều này giúp câu trả lời của mô hình dựa trên dữ liệu thực tế của bạn thay vì dựa vào kiến thức huấn luyện hoặc bịa câu trả lời. +Điều này giúp câu trả lời của mô hình dựa trên dữ liệu thật sự của bạn thay vì dựa vào kiến thức huấn luyện hoặc tự sáng tạo. ## Yêu cầu trước -- Đã hoàn thành [Module 00 - Bắt đầu nhanh](../00-quick-start/README.md) (cho ví dụ Easy RAG được tham chiếu sau trong module này) -- Đã hoàn thành [Module 01 - Giới thiệu](../01-introduction/README.md) (đã triển khai tài nguyên Azure OpenAI, bao gồm mô hình embedding `text-embedding-3-small`) -- File `.env` trong thư mục gốc chứa thông tin xác thực Azure (tạo bởi `azd up` trong Module 01) +- Hoàn thành [Module 01 - Giới thiệu](../01-introduction/README.md) (đã triển khai tài nguyên Azure OpenAI, bao gồm mô hình embedding `text-embedding-3-small`) +- Tệp `.env` trong thư mục gốc có thông tin xác thực Azure (được tạo bởi lệnh `azd up` trong Module 01) -> **Lưu ý:** Nếu bạn chưa hoàn thành Module 01, hãy làm theo hướng dẫn triển khai ở đó trước. Lệnh `azd up` triển khai cả mô hình chat GPT và mô hình embedding được sử dụng trong module này. +> **Lưu ý:** Nếu bạn chưa hoàn thành Module 01, hãy làm theo hướng dẫn triển khai ở đó trước. Lệnh `azd up` sẽ triển khai cả mô hình chat GPT và mô hình embedding được sử dụng trong module này. ## Hiểu về RAG -Sơ đồ dưới đây minh họa khái niệm cốt lõi: thay vì chỉ dựa trên dữ liệu huấn luyện của mô hình, RAG cung cấp cho nó một thư viện tham khảo gồm các tài liệu của bạn để tham khảo trước khi sinh câu trả lời. +Sơ đồ dưới đây minh họa khái niệm chính: thay vì chỉ dựa vào dữ liệu huấn luyện của mô hình, RAG cung cấp cho nó một thư viện tham khảo các tài liệu của bạn để tham khảo trước khi tạo câu trả lời. What is RAG -*Sơ đồ này thể hiện sự khác biệt giữa một LLM chuẩn (dự đoán dựa trên dữ liệu đào tạo) và một LLM được cải tiến bởi RAG (tham khảo tài liệu của bạn trước).* +*Sơ đồ này cho thấy sự khác biệt giữa một LLM tiêu chuẩn (phán đoán dựa trên dữ liệu huấn luyện) và một LLM được tăng cường RAG (tham khảo tài liệu của bạn trước).* -Dưới đây là cách các bước kết nối từ đầu đến cuối. Câu hỏi của người dùng đi qua bốn giai đoạn — embedding, tìm kiếm vector, tập hợp ngữ cảnh và tạo câu trả lời — mỗi bước xây dựng trên bước trước: +Dưới đây là cách các phần kết nối từ đầu đến cuối. Câu hỏi của người dùng trải qua bốn giai đoạn — embedding, tìm kiếm vector, tập hợp ngữ cảnh và tạo câu trả lời — mỗi giai đoạn xây dựng trên cái trước: RAG Architecture -*Sơ đồ này thể hiện quy trình RAG từ đầu đến cuối — câu hỏi người dùng đi qua embedding, tìm kiếm vector, tập hợp ngữ cảnh và tạo câu trả lời.* +*Sơ đồ này minh họa đường dây RAG từ đầu đến cuối — truy vấn người dùng đi qua embedding, tìm kiếm vector, tập hợp ngữ cảnh và tạo câu trả lời.* -Phần còn lại của module này sẽ hướng dẫn chi tiết từng giai đoạn, với mã bạn có thể chạy và sửa đổi. +Phần còn lại của module sẽ đi qua từng giai đoạn chi tiết, với mã bạn có thể chạy và sửa đổi. -### Phương pháp RAG nào được sử dụng trong hướng dẫn này? +### Phương pháp RAG nào mà hướng dẫn này sử dụng? -LangChain4j cung cấp ba cách để triển khai RAG, mỗi cách có mức độ trừu tượng khác nhau. Sơ đồ dưới đây so sánh chúng cạnh nhau: +LangChain4j cung cấp ba cách để triển khai RAG, mỗi cách với mức độ trừu tượng khác nhau. Sơ đồ dưới đây so sánh các cách đó: Three RAG Approaches in LangChain4j -*Sơ đồ này so sánh ba phương pháp RAG của LangChain4j — Easy, Native và Advanced — thể hiện các thành phần chính và khi nào nên dùng từng loại.* +*Sơ đồ này so sánh ba cách tiếp cận RAG của LangChain4j — Easy, Native, và Advanced — với các thành phần chính và thời điểm sử dụng mỗi cách.* -| Phương pháp | Điều nó làm | Đánh đổi | +| Phương pháp | Chức năng | Đánh đổi | |---|---|---| -| **Easy RAG** | Kết nối mọi thứ tự động qua `AiServices` và `ContentRetriever`. Bạn chú thích một interface, gắn bộ truy xuất, LangChain4j xử lý embedding, tìm kiếm và ráp prompt phía sau. | Ít mã nhất, nhưng bạn không thấy các bước bên trong. | -| **Native RAG** | Bạn gọi mô hình embedding, tìm kiếm trong kho, xây dựng prompt và tạo câu trả lời theo từng bước rõ ràng. | Mã nhiều hơn, nhưng từng giai đoạn đều rõ ràng và có thể sửa đổi. | -| **Advanced RAG** | Dùng framework `RetrievalAugmentor` với các bộ biến đổi truy vấn, bộ điều hướng, bộ xếp lại, và bộ chèn nội dung cắm thêm cho hệ thống sản xuất. | Linh hoạt tối đa, nhưng phức tạp đáng kể. | +| **Easy RAG** | Tự động kết nối mọi thứ qua `AiServices` và `ContentRetriever`. Bạn chỉ cần chú thích một interface, gắn một retriever, LangChain4j sẽ xử lý embedding, tìm kiếm và tập hợp prompt phía sau. | Ít mã, nhưng bạn không nhìn thấy từng bước diễn ra như thế nào. | +| **Native RAG** | Bạn tự gọi mô hình embedding, tìm kiếm trong kho lưu trữ, xây dựng prompt và tạo câu trả lời — từng bước rõ ràng. | Mã nhiều hơn nhưng bạn thấy và có thể sửa đổi từng giai đoạn. | +| **Advanced RAG** | Sử dụng framework `RetrievalAugmentor` với các bộ biến đổi truy vấn, bộ định tuyến, bộ xếp lại, và bộ chèn nội dung có thể cắm cho pipeline chuẩn sản xuất. | Linh hoạt tối đa, nhưng phức tạp nhiều hơn. | -**Hướng dẫn này sử dụng phương pháp Native.** Mỗi bước trong pipeline RAG — embedding truy vấn, tìm kiếm trong kho vector, tập hợp ngữ cảnh, và tạo câu trả lời — được viết rõ ràng trong [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Điều này là có chủ ý: như một tài nguyên học tập, điều quan trọng hơn là bạn thấy và hiểu từng bước hơn là rút gọn mã. Khi bạn đã quen với cách các phần nối với nhau, bạn có thể chuyển sang Easy RAG cho prototype nhanh hoặc Advanced RAG cho hệ thống sản xuất. +**Hướng dẫn này sử dụng phương pháp Native.** Mỗi bước trong pipeline RAG — embedding truy vấn, tìm kiếm trong kho vector, tập hợp ngữ cảnh và tạo câu trả lời — được viết rõ ràng trong [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java). Việc này là có chủ đích: như một tài nguyên học tập, quan trọng hơn là bạn thấy và hiểu từng giai đoạn thay vì code được tối giản. Khi bạn quen thuộc cách các phần khớp nhau, bạn có thể chuyển sang Easy RAG để tạo mẫu nhanh hoặc Advanced RAG cho hệ thống sản xuất. -> **💡 Đã từng thấy Easy RAG hoạt động?** Module [Bắt đầu nhanh](../00-quick-start/README.md) bao gồm ví dụ Hỏi đáp tài liệu ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) dùng phương pháp Easy RAG — LangChain4j tự động xử lý embedding, tìm kiếm, và ráp prompt. Module này sẽ đi sâu hơn bằng cách mở rộng pipeline đó để bạn có thể thấy và kiểm soát từng bước. +> **💡 Tò mò về Easy RAG?** LangChain4j cũng cung cấp cách *Easy RAG* nơi `AiServices` và một `ContentRetriever` tự động xử lý embedding, tìm kiếm, và tập hợp prompt. Module này chọn con đường rõ ràng hơn — mở từng bước trong pipeline để bạn có thể xem và kiểm soát từng giai đoạn. -Sơ đồ dưới đây thể hiện pipeline Easy RAG từ ví dụ Bắt đầu nhanh đó. Hãy chú ý cách `AiServices` và `EmbeddingStoreContentRetriever` ẩn đi toàn bộ sự phức tạp — bạn tải tài liệu, gắn bộ truy xuất, và nhận câu trả lời. Phương pháp Native trong module này sẽ mở rộng từng bước ẩn đó: +Sơ đồ dưới đây cho thấy pipeline Easy RAG. Bạn thấy `AiServices` và `EmbeddingStoreContentRetriever` ẩn toàn bộ sự phức tạp — bạn tải tài liệu, gắn một retriever và nhận câu trả lời. Phương pháp Native trong module này mở từng bước ẩn đó: Easy RAG Pipeline - LangChain4j -*Sơ đồ này thể hiện pipeline Easy RAG từ `SimpleReaderDemo.java`. So sánh với phương pháp Native dùng trong module này: Easy RAG ẩn embedding, truy xuất, và ráp prompt phía sau `AiServices` và `ContentRetriever` — bạn tải tài liệu, gắn bộ truy xuất, và nhận câu trả lời. Phương pháp Native trong module này mở pipeline đó ra để bạn gọi từng bước (embed, tìm kiếm, ráp ngữ cảnh, tạo câu trả lời) trực tiếp, cho phép bạn thấy và kiểm soát toàn bộ.* +*Sơ đồ này minh họa pipeline Easy RAG. So sánh với phương pháp Native được dùng trong module: Easy RAG ẩn embedding, truy xuất và tập hợp prompt bên trong `AiServices` và `ContentRetriever` — bạn tải tài liệu, gắn retriever và nhận câu trả lời. Native mở pipeline đó để bạn tự gọi từng bước (embedding, tìm kiếm, tập hợp ngữ cảnh, tạo) cho phép bạn quan sát và kiểm soát đầy đủ.* ## Cách hoạt động -Pipeline RAG trong module này chia thành bốn giai đoạn chạy tuần tự mỗi lần người dùng hỏi. Đầu tiên, tài liệu tải lên được **phân tích và chia thành các đoạn nhỏ** vừa phải. Các đoạn này sau đó được chuyển thành **embedding vector** và lưu trữ để có thể so sánh về mặt toán học. Khi có truy vấn, hệ thống thực hiện **tìm kiếm ngữ nghĩa** để tìm các đoạn có liên quan nhất, và cuối cùng chuyển chúng làm ngữ cảnh cho LLM để **tạo câu trả lời**. Các phần dưới đây sẽ hướng dẫn từng bước với mã thực tế và sơ đồ. Bắt đầu với bước đầu tiên. +Pipeline RAG trong module này chia thành bốn giai đoạn chạy tuần tự mỗi khi người dùng đặt câu hỏi. Đầu tiên, tài liệu được tải lên sẽ **được phân tích và chia đoạn nhỏ** thành những phần dễ quản lý. Những đoạn này sau đó được chuyển thành **vector embedding** và lưu trữ để có thể so sánh toán học. Khi có truy vấn, hệ thống thực hiện **tìm kiếm ngữ nghĩa** để tìm các đoạn phù hợp nhất, rồi cuối cùng truyền chúng làm ngữ cảnh cho LLM để **tạo câu trả lời**. Các phần dưới đây sẽ đi qua từng giai đoạn với mã thực và sơ đồ. Hãy xem bước đầu tiên. ### Xử lý tài liệu [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -Khi bạn tải một tài liệu lên, hệ thống sẽ phân tích nó (dạng PDF hoặc văn bản thuần túy), gắn thêm metadata như tên file, rồi chia nó thành các đoạn nhỏ — các phần nhỏ hơn phù hợp với cửa sổ ngữ cảnh của mô hình. Các đoạn này đan xen một chút để bạn không mất ngữ cảnh ở các điểm giới hạn. +Khi bạn tải lên một tài liệu, hệ thống sẽ phân tích nó (PDF hoặc văn bản thuần), gán các siêu dữ liệu như tên tệp, rồi chia nó thành các đoạn nhỏ — những phần nhỏ vừa vặn trong cửa sổ ngữ cảnh của mô hình. Các đoạn này chồng lấn nhẹ để không mất bối cảnh ở ranh giới. ```java -// Phân tích tệp đã tải lên và bao gói nó trong một tài liệu LangChain4j +// Phân tích tệp đã tải lên và bao bọc nó trong một Tài liệu LangChain4j Document document = Document.from(content, metadata); -// Chia thành các đoạn 300 token với chồng lấn 30 token +// Chia thành các đoạn 300 token với chồng lặp 30 token DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -Sơ đồ dưới đây thể hiện cách hoạt động một cách trực quan. Chú ý cách mỗi đoạn chia sẻ một số token với các đoạn xung quanh — sự chồng lấp 30 token đảm bảo không mất ngữ cảnh quan trọng tại ranh giới: +Sơ đồ dưới đây minh họa trực quan cách hoạt động này. Bạn thấy mỗi đoạn chia sẻ một số token với đoạn liền kề — sự chồng lấn 30-token đảm bảo không mất thông tin quan trọng tại ranh giới: Document Chunking -*Sơ đồ này thể hiện một tài liệu được chia thành các đoạn 300 token với 30 token chồng lấp, giữ nguyên ngữ cảnh ở ranh giới các đoạn.* +*Sơ đồ này cho thấy một tài liệu được chia thành các đoạn 300-token với 30-token chồng lấn, giữ nguyên ngữ cảnh ở biên giới đoạn.* > **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) và hỏi: -> - "LangChain4j chia tài liệu thành các đoạn như thế nào và tại sao sự chồng lấp lại quan trọng?" -> - "Kích thước đoạn tối ưu cho các loại tài liệu khác nhau là bao nhiêu và tại sao?" -> - "Làm sao để xử lý tài liệu bằng nhiều ngôn ngữ hoặc có định dạng đặc biệt?" +> - "LangChain4j chia tài liệu thành các đoạn thế nào và tại sao chồng token lại quan trọng?" +> - "Kích thước đoạn tối ưu cho các loại tài liệu khác nhau là bao nhiêu và vì sao?" +> - "Làm sao xử lý tài liệu đa ngôn ngữ hoặc có định dạng đặc biệt?" -### Tạo embeddings +### Tạo embedding [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -Mỗi đoạn được chuyển thành một biểu diễn số gọi là embedding — cơ bản là bộ chuyển đổi từ ý nghĩa thành số. Mô hình embedding không "thông minh" như mô hình chat; nó không thể theo lệnh, lý luận, hoặc trả lời câu hỏi. Điều nó làm được là ánh xạ văn bản vào một không gian toán học, nơi các ý nghĩa tương tự nằm gần nhau — "car" gần "automobile", "refund policy" gần "return my money." Hãy nghĩ mô hình chat như một người bạn nói chuyện được; còn mô hình embedding là hệ thống lưu trữ siêu tốt. +Mỗi đoạn được chuyển đổi thành một đại diện số gọi là embedding — về cơ bản là một bộ chuyển đổi ý nghĩa sang số. Mô hình embedding không "thông minh" như mô hình chat; nó không thể theo chỉ dẫn, suy luận, hoặc trả lời câu hỏi. Điều nó làm được là ánh xạ văn bản vào không gian toán học nơi các ý nghĩa tương tự đặt gần nhau — "car" gần "automobile," "refund policy" gần "return my money." Nghĩ mô hình chat như một người để bạn trò chuyện; mô hình embedding là hệ thống phân loại siêu hiệu quả. -Sơ đồ dưới đây thể hiện khái niệm này — văn bản vào, vector số ra, và các ý nghĩa tương tự tạo ra các vector gần nhau: +Sơ đồ dưới đây minh họa khái niệm này — văn bản đi vào, véc-tơ số đi ra, và các ý nghĩa tương tự tạo ra các véc-tơ gần nhau: Embedding Model Concept -*Sơ đồ này thể hiện cách mô hình embedding chuyển văn bản thành vector số, đặt các ý nghĩa tương tự — như "car" và "automobile" — nằm sát nhau trong không gian vector.* +*Sơ đồ này cho thấy cách mô hình embedding chuyển văn bản thành véc-tơ số, đặt các ý nghĩa tương tự — như "car" và "automobile" — gần nhau trong không gian véc-tơ.* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -Sơ đồ lớp dưới đây mô tả hai luồng riêng biệt trong pipeline RAG và các lớp LangChain4j triển khai chúng. Luồng **nhập liệu** (chạy một lần khi tải lên) chia tài liệu, tạo embedding cho các đoạn, và lưu chúng qua `.addAll()`. Luồng **truy vấn** (chạy mỗi khi người dùng hỏi) tạo embedding câu hỏi, tìm kiếm trong kho qua `.search()`, và đưa ngữ cảnh phù hợp cho mô hình chat. Hai luồng này gặp nhau tại interface chung `EmbeddingStore`: +Sơ đồ lớp dưới đây hiển thị hai luồng riêng biệt trong pipeline RAG và các lớp LangChain4j triển khai chúng. Luồng **nhập liệu** (chạy một lần khi tải lên) chia tài liệu, tạo embedding cho đoạn và lưu trữ qua `.addAll()`. Luồng **truy vấn** (chạy mỗi lần người dùng hỏi) tạo embedding cho câu hỏi, tìm kiếm trong kho qua `.search()`, và truyền ngữ cảnh phù hợp đến mô hình chat. Hai luồng được kết nối tại giao diện chung `EmbeddingStore`: LangChain4j RAG Classes -*Sơ đồ này thể hiện hai luồng trong pipeline RAG — nhập liệu và truy vấn — và cách chúng kết nối qua EmbeddingStore chung.* +*Sơ đồ này cho thấy hai luồng trong pipeline RAG — nhập liệu và truy vấn — và cách chúng kết nối qua một EmbeddingStore chung.* -Khi embeddings được lưu, nội dung tương tự tự nhiên gom vào gần nhau trong không gian vector. Hình dưới đây thể hiện cách các tài liệu về chủ đề liên quan tụ lại thành các điểm gần nhau, điều này làm cho tìm kiếm ngữ nghĩa khả thi: +Khi embedding được lưu, các nội dung tương tự tự nhiên sẽ tụ lại gần nhau trong không gian véc-tơ. Hình minh họa dưới đây cho thấy các tài liệu về chủ đề liên quan tụ lại thành các điểm gần nhau, điều này làm cho tìm kiếm ngữ nghĩa khả thi: Vector Embeddings Space -*Hình minh họa cách các tài liệu liên quan được gom nhóm trong không gian vector 3D, với các chủ đề như Tài liệu kỹ thuật, Quy tắc kinh doanh, và Câu hỏi thường gặp tạo thành các nhóm riêng biệt.* +*Hình minh họa này cho thấy cách các tài liệu liên quan tụ lại cùng nhau trong không gian véc-tơ 3 chiều, với các chủ đề như Tài liệu Kỹ thuật, Quy định Kinh doanh, và FAQ tạo thành các nhóm riêng biệt.* -Khi người dùng tìm kiếm, hệ thống thực hiện bốn bước: tạo embedding cho tài liệu một lần, tạo embedding cho truy vấn mỗi lần tìm, so sánh vector truy vấn với tất cả vector đã lưu bằng độ tương đồng cosine, và trả về top-K đoạn có điểm cao nhất. Sơ đồ dưới đây minh họa từng bước và các lớp LangChain4j liên quan: +Khi người dùng tìm kiếm, hệ thống thực hiện bốn bước: tạo embedding cho tài liệu một lần, tạo embedding cho truy vấn mỗi lần tìm kiếm, so sánh véc-tơ truy vấn với tất cả véc-tơ đã lưu bằng độ tương đồng cosine và trả về top-K đoạn có điểm cao nhất. Sơ đồ dưới đây minh họa từng bước và các lớp LangChain4j liên quan: Embedding Search Steps -*Sơ đồ thể hiện quy trình tìm kiếm embedding bốn bước: tạo embedding tài liệu, tạo embedding truy vấn, so sánh vector bằng độ tương đồng cosine, và trả về kết quả top-K.* +*Sơ đồ này minh họa quá trình tìm kiếm embedding gồm bốn bước: tạo embedding tài liệu, tạo embedding truy vấn, so sánh véc-tơ bằng độ tương đồng cosine, và trả về kết quả top-K.* ### Tìm kiếm ngữ nghĩa [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Khi bạn hỏi một câu, câu hỏi của bạn cũng được chuyển thành embedding. Hệ thống so sánh embedding của câu hỏi với tất cả embedding của các đoạn tài liệu. Nó tìm các đoạn có ý nghĩa tương tự nhất — không chỉ khớp từ khóa mà còn là tương đồng ngữ nghĩa thực tế. +Khi bạn đặt câu hỏi, câu hỏi cũng được chuyển thành embedding. Hệ thống so sánh embedding câu hỏi với embedding của các đoạn tài liệu. Nó tìm các đoạn có ý nghĩa tương tự nhất — không chỉ khớp từ khóa mà là sự tương đồng về ngữ nghĩa thật sự. ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -Sơ đồ dưới đây đối chiếu tìm kiếm ngữ nghĩa với tìm kiếm từ khóa truyền thống. Tìm kiếm từ khóa "vehicle" bỏ sót đoạn nói về "cars and trucks," nhưng tìm kiếm ngữ nghĩa hiểu rằng chúng có nghĩa như nhau và trả về kết quả với điểm cao: +Sơ đồ dưới đây so sánh tìm kiếm ngữ nghĩa với tìm kiếm từ khóa truyền thống. Tìm kiếm từ khóa cho "vehicle" bỏ qua một đoạn về "cars and trucks," nhưng tìm kiếm ngữ nghĩa hiểu chúng cùng nghĩa và trả về đoạn đó với điểm cao: Semantic Search -*Sơ đồ so sánh tìm kiếm dựa trên từ khóa với tìm kiếm ngữ nghĩa, thể hiện cách tìm kiếm ngữ nghĩa truy xuất nội dung liên quan về mặt khái niệm ngay cả khi từ khóa chính xác khác nhau.* -Dưới bề mặt, sự tương đồng được đo bằng độ tương đồng cosin — về cơ bản hỏi "liệu hai mũi tên này có đang chỉ cùng một hướng không?" Hai đoạn văn có thể sử dụng từ ngữ hoàn toàn khác nhau, nhưng nếu chúng có cùng ý nghĩa thì các vec-tơ của chúng sẽ chỉ cùng một hướng và điểm số sẽ gần bằng 1.0: +*Sơ đồ này so sánh tìm kiếm dựa trên từ khóa với tìm kiếm ngữ nghĩa, cho thấy cách tìm kiếm ngữ nghĩa truy xuất nội dung liên quan về mặt khái niệm ngay cả khi từ khóa chính xác khác nhau.* -Độ tương đồng Cosin +Bên trong, độ tương đồng được đo bằng cosine similarity — cơ bản là hỏi "hai mũi tên này có chỉ về cùng hướng không?" Hai đoạn có thể dùng từ hoàn toàn khác nhưng nếu nghĩa giống nhau thì véc-tơ chỉ cùng hướng và điểm gần bằng 1.0: -*Biểu đồ này minh họa độ tương đồng cosin như góc giữa các vec-tơ embedding — các vec-tơ càng đồng hướng thì điểm số càng gần 1.0, cho thấy sự tương đồng ngữ nghĩa cao hơn.* +Cosine Similarity +*Biểu đồ này minh họa độ tương đồng cosine như góc giữa các vector embedding — các vector càng căn chỉnh gần nhau hơn thì điểm số càng gần 1.0, chỉ ra sự tương đồng ngữ nghĩa cao hơn.* > **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) và hỏi: -> - "Cách tìm kiếm tương đồng hoạt động với embeddings như thế nào và điều gì quyết định điểm số?" -> - "Ngưỡng tương đồng nào tôi nên dùng và nó ảnh hưởng thế nào đến kết quả?" -> - "Tôi xử lý trường hợp không tìm thấy tài liệu liên quan ra sao?" +> - "Tìm kiếm sự tương đồng hoạt động như thế nào với embeddings và điều gì quyết định điểm số?" +> - "Ngưỡng tương đồng nên sử dụng là bao nhiêu và nó ảnh hưởng thế nào đến kết quả?" +> - "Làm thế nào để xử lý trường hợp không tìm thấy tài liệu liên quan?" ### Tạo Câu Trả Lời [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -Các đoạn văn liên quan nhất được tập hợp thành một lời nhắc có cấu trúc bao gồm hướng dẫn rõ ràng, ngữ cảnh được lấy ra, và câu hỏi của người dùng. Mô hình đọc các đoạn văn cụ thể đó và trả lời dựa trên thông tin đó — nó chỉ có thể sử dụng những gì đang có trước mặt, điều này ngăn chặn việc tạo ra thông tin không chính xác. +Các đoạn chunk liên quan nhất được tập hợp thành một prompt cấu trúc bao gồm hướng dẫn rõ ràng, ngữ cảnh được truy xuất và câu hỏi của người dùng. Mô hình đọc các đoạn chunk cụ thể đó và trả lời dựa trên thông tin đó — nó chỉ có thể sử dụng những gì hiện diện trước mặt, điều này ngăn ngừa việc tưởng tượng ra thông tin không có thật. ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -Biểu đồ dưới đây cho thấy quá trình tập hợp này — các đoạn văn có điểm cao nhất từ bước tìm kiếm được chèn vào mẫu lời nhắc, và `OpenAiOfficialChatModel` tạo ra một câu trả lời có căn cứ: +Biểu đồ dưới đây cho thấy cách tập hợp này hoạt động — các đoạn chunk có điểm cao nhất từ bước tìm kiếm được chèn vào mẫu prompt, và `OpenAiOfficialChatModel` tạo ra câu trả lời có cơ sở: -Tập hợp Ngữ cảnh +Context Assembly -*Biểu đồ này cho thấy cách các đoạn văn điểm cao nhất được tập hợp thành lời nhắc có cấu trúc, cho phép mô hình tạo ra câu trả lời dựa trên dữ liệu của bạn.* +*Biểu đồ này cho thấy cách các đoạn chunk có điểm cao nhất được tập hợp thành một prompt cấu trúc, cho phép mô hình tạo câu trả lời dựa trên dữ liệu của bạn.* ## Chạy Ứng Dụng -**Xác minh triển khai:** +**Xác nhận việc triển khai:** -Đảm bảo file `.env` tồn tại trong thư mục gốc với thông tin xác thực Azure (đã tạo trong Module 01). Chạy lệnh này từ thư mục module (`03-rag/`): +Đảm bảo file `.env` tồn tại ở thư mục gốc với thông tin Azure credentials (đã tạo trong Module 01). Chạy lệnh này từ thư mục module (`03-rag/`): **Bash:** ```bash @@ -261,27 +260,27 @@ Get-Content ..\.env # Nên hiển thị AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Khởi động ứng dụng:** -> **Lưu ý:** Nếu bạn đã khởi chạy tất cả ứng dụng bằng `./start-all.sh` từ thư mục gốc (theo mô tả trong Module 01), module này đã chạy trên cổng 8081. Bạn có thể bỏ qua các lệnh khởi động dưới đây và truy cập trực tiếp http://localhost:8081. +> **Lưu ý:** Nếu bạn đã khởi động tất cả ứng dụng dùng lệnh `./start-all.sh` từ thư mục gốc (theo mô tả trong Module 01), module này đã chạy trên cổng 8081. Bạn có thể bỏ qua các lệnh khởi động dưới đây và truy cập trực tiếp http://localhost:8081. -**Lựa chọn 1: Dùng Spring Boot Dashboard (Khuyến nghị cho người dùng VS Code)** +**Lựa chọn 1: Sử dụng Spring Boot Dashboard (Khuyến nghị cho người dùng VS Code)** -Dev container bao gồm extension Spring Boot Dashboard, cung cấp giao diện trực quan để quản lý tất cả ứng dụng Spring Boot. Bạn có thể tìm thấy ở thanh hoạt động bên trái VS Code (tìm biểu tượng Spring Boot). +Dev container bao gồm tiện ích mở rộng Spring Boot Dashboard, cung cấp giao diện trực quan để quản lý tất cả ứng dụng Spring Boot. Bạn có thể tìm thấy nó ở Thanh Hoạt Động bên trái VS Code (tìm biểu tượng Spring Boot). Từ Spring Boot Dashboard, bạn có thể: -- Xem tất cả các ứng dụng Spring Boot có trong workspace -- Khởi động/dừng ứng dụng chỉ với một cú click -- Xem nhật ký ứng dụng theo thời gian thực +- Xem tất cả ứng dụng Spring Boot có trong workspace +- Khởi động/dừng ứng dụng chỉ với một cú nhấp +- Xem nhật ký ứng dụng thời gian thực - Giám sát trạng thái ứng dụng -Chỉ cần nhấn nút play cạnh "rag" để khởi động module này, hoặc khởi động tất cả các module cùng lúc. +Chỉ cần nhấn nút play bên cạnh "rag" để khởi động module này, hoặc khởi động tất cả module cùng lúc. -Bảng điều khiển Spring Boot +Spring Boot Dashboard -*Ảnh chụp màn hình này hiển thị Spring Boot Dashboard trong VS Code, nơi bạn có thể khởi động, dừng và giám sát các ứng dụng một cách trực quan.* +*Ảnh chụp màn hình này hiển thị Spring Boot Dashboard trong VS Code, nơi bạn có thể khởi động, dừng và giám sát ứng dụng một cách trực quan.* -**Lựa chọn 2: Dùng các script shell** +**Lựa chọn 2: Dùng shell scripts** -Khởi động tất cả các ứng dụng web (modules 01-04): +Khởi động tất cả ứng dụng web (module 01-04): **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -Cả hai script tự động tải biến môi trường từ file `.env` ở thư mục gốc và sẽ build JAR nếu chưa tồn tại. +Cả hai script tự động tải biến môi trường từ file `.env` ở thư mục gốc và sẽ xây dựng file JAR nếu chúng chưa tồn tại. -> **Lưu ý:** Nếu bạn muốn build tất cả các module thủ công trước khi khởi động: +> **Lưu ý:** Nếu bạn muốn tự xây dựng tất cả module thủ công trước khi khởi động: > > **Bash:** > ```bash @@ -325,7 +324,7 @@ Cả hai script tự động tải biến môi trường từ file `.env` ở th > mvn clean package -DskipTests > ``` -Mở http://localhost:8081 trong trình duyệt của bạn. +Mở http://localhost:8081 trên trình duyệt của bạn. **Để dừng:** @@ -343,95 +342,95 @@ cd .. && ./stop-all.sh # Tất cả các mô-đun cd ..; .\stop-all.ps1 # Tất cả các mô-đun ``` -## Sử dụng Ứng Dụng +## Sử Dụng Ứng Dụng Ứng dụng cung cấp giao diện web để tải tài liệu lên và đặt câu hỏi. -Giao diện Ứng dụng RAG +RAG Application Interface -*Ảnh chụp màn hình này hiển thị giao diện ứng dụng RAG, nơi bạn có thể tải tài liệu lên và đặt câu hỏi.* +*Ảnh chụp màn hình giao diện ứng dụng RAG, nơi bạn tải tài liệu lên và hỏi câu hỏi.* -### Tải Lên Một Tài Liệu +### Tải Tài Liệu Lên -Bắt đầu bằng cách tải lên một tài liệu - các file TXT là lựa chọn tốt nhất để thử nghiệm. Một file `sample-document.txt` được cung cấp trong thư mục này với thông tin về các tính năng của LangChain4j, cách triển khai RAG, và các thực hành tốt nhất - rất phù hợp để thử hệ thống. +Bắt đầu bằng cách tải lên một tài liệu - các file TXT hoạt động tốt nhất để thử nghiệm. Một file `sample-document.txt` có sẵn trong thư mục này chứa thông tin về các tính năng của LangChain4j, triển khai RAG, và các thực hành tốt nhất - rất phù hợp để thử nghiệm hệ thống. -Hệ thống xử lý tài liệu của bạn, chia nhỏ thành các đoạn, và tạo embeddings cho mỗi đoạn. Quá trình này diễn ra tự động khi bạn tải lên. +Hệ thống sẽ xử lý tài liệu của bạn, chia nhỏ nó thành các đoạn chunk và tạo embeddings cho mỗi chunk. Việc này xảy ra tự động khi bạn tải lên. ### Đặt Câu Hỏi -Bây giờ hãy hỏi những câu hỏi cụ thể về nội dung tài liệu. Thử một điều gì đó có tính thực tế được trình bày rõ ràng trong tài liệu. Hệ thống sẽ tìm kiếm các đoạn liên quan, đưa vào lời nhắc, và tạo ra câu trả lời. +Giờ hãy đặt những câu hỏi cụ thể về nội dung tài liệu. Thử các câu hỏi thực tế rõ ràng trong tài liệu. Hệ thống sẽ tìm các đoạn chunk liên quan, đưa chúng vào prompt, và tạo câu trả lời. ### Kiểm Tra Tham Chiếu Nguồn -Lưu ý mỗi câu trả lời đều có tham chiếu nguồn kèm theo điểm số tương đồng. Những điểm số này (từ 0 đến 1) cho thấy mức độ liên quan của từng đoạn với câu hỏi của bạn. Điểm càng cao đồng nghĩa với sự phù hợp càng tốt. Điều này cho phép bạn kiểm chứng câu trả lời với tài liệu nguồn. +Lưu ý mỗi câu trả lời đều bao gồm các tham chiếu nguồn với điểm tương đồng. Những điểm số này (từ 0 đến 1) cho thấy mức độ liên quan của từng đoạn chunk với câu hỏi của bạn. Điểm cao hơn nghĩa là phù hợp hơn. Điều này giúp bạn xác minh câu trả lời dựa trên tài liệu gốc. -Kết quả Truy vấn RAG +RAG Query Results -*Ảnh chụp màn hình này hiển thị kết quả truy vấn với câu trả lời được tạo, tham chiếu nguồn, và điểm tương đồng cho mỗi đoạn được truy xuất.* +*Ảnh chụp màn hình kết quả truy vấn với câu trả lời được tạo, tham chiếu nguồn, và điểm liên quan cho từng đoạn chunk được truy xuất.* ### Thử Nghiệm Với Các Câu Hỏi Thử các loại câu hỏi khác nhau: -- Các sự kiện cụ thể: "Chủ đề chính là gì?" +- Thông tin cụ thể: "Chủ đề chính là gì?" - So sánh: "Sự khác biệt giữa X và Y là gì?" -- Tóm tắt: "Tóm tắt những điểm chính về Z" +- Tóm tắt: "Tóm tắt các điểm chính về Z" -Theo dõi cách điểm số tương đồng thay đổi dựa trên mức độ phù hợp câu hỏi với nội dung tài liệu. +Quan sát cách điểm liên quan thay đổi dựa trên mức độ phù hợp của câu hỏi với nội dung tài liệu. ## Các Khái Niệm Chính -### Chiến lược Chia Đoạn +### Chiến Lược Chia Chunk -Tài liệu được chia thành các đoạn 300 token với 30 token chồng lắp. Cân bằng này đảm bảo mỗi đoạn có đủ ngữ cảnh để có ý nghĩa trong khi vẫn đủ nhỏ để có thể đưa nhiều đoạn vào lời nhắc. +Tài liệu được chia thành các đoạn chunk 300 token với 30 token chồng lấn. Cách chia này đảm bảo mỗi chunk có đủ ngữ cảnh để có ý nghĩa trong khi vẫn đủ nhỏ để có thể gồm nhiều chunk trong một prompt. ### Điểm Tương Đồng -Mỗi đoạn được truy xuất đều có điểm tương đồng từ 0 đến 1 biểu thị mức độ phù hợp với câu hỏi người dùng. Biểu đồ dưới đây trực quan hóa phạm vi điểm và cách hệ thống sử dụng để lọc kết quả: +Mỗi đoạn chunk được truy xuất kèm theo điểm tương đồng từ 0 đến 1 thể hiện mức độ phù hợp với câu hỏi người dùng. Biểu đồ dưới đây trực quan hóa các phạm vi điểm và cách hệ thống sử dụng chúng để lọc kết quả: -Điểm Tương đồng +Similarity Scores -*Biểu đồ này hiển thị phạm vi điểm từ 0 đến 1, với ngưỡng tối thiểu 0.5 để lọc bỏ những đoạn không phù hợp.* +*Biểu đồ này hiển thị phạm vi điểm từ 0 đến 1, với ngưỡng tối thiểu 0.5 để lọc các đoạn chunk không liên quan.* Điểm số dao động từ 0 đến 1: -- 0.7-1.0: Rất liên quan, trùng khớp chính xác -- 0.5-0.7: Liên quan, ngữ cảnh tốt -- Dưới 0.5: Bị loại, quá khác biệt +- 0.7-1.0: Rất liên quan, khớp chính xác +- 0.5-0.7: Liên quan, có ngữ cảnh tốt +- Dưới 0.5: Bị lọc bỏ, quá khác biệt -Hệ thống chỉ truy xuất các đoạn trên ngưỡng tối thiểu để đảm bảo chất lượng. +Hệ thống chỉ truy xuất các đoạn chunk có điểm trên ngưỡng tối thiểu để đảm bảo chất lượng. -Embeddings hoạt động tốt khi các ý nghĩa cụ thể được nhóm rõ ràng, nhưng vẫn có điểm mù. Biểu đồ dưới đây cho thấy các lỗi phổ biến — đoạn quá lớn tạo ra vec-tơ mờ nhạt, đoạn quá nhỏ thiếu ngữ cảnh, thuật ngữ mơ hồ chỉ đến nhiều nhóm, và tra cứu trùng khớp chính xác (ID, số bộ phận) hoàn toàn không hoạt động với embeddings: +Embeddings hoạt động hiệu quả khi các nghĩa được nhóm rõ ràng, nhưng chúng cũng có điểm mù. Biểu đồ dưới đây cho thấy các chế độ lỗi phổ biến — các đoạn chunk quá lớn tạo vector mơ hồ, các đoạn chunk quá nhỏ thiếu ngữ cảnh, các thuật ngữ mơ hồ chỉ tới nhiều cluster khác nhau, và các tra cứu khớp chính xác (ID, số bộ phận) không hoạt động với embeddings: -Các lỗi thường gặp với Embedding +Embedding Failure Modes -*Biểu đồ này chỉ ra các lỗi thường gặp với embeddings: đoạn quá lớn, đoạn quá nhỏ, thuật ngữ mơ hồ chỉ đến nhiều nhóm, và tra cứu chính xác như ID.* +*Biểu đồ này cho thấy các chế độ lỗi embedding phổ biến: chunk quá lớn, chunk quá nhỏ, thuật ngữ mơ hồ chỉ đến nhiều cluster, và các tra cứu khớp chính xác như ID.* -### Lưu trữ Trong Bộ Nhớ +### Lưu Trữ Trong Bộ Nhớ -Module này sử dụng lưu trữ trong bộ nhớ cho đơn giản. Khi bạn khởi động lại ứng dụng, các tài liệu đã tải lên sẽ bị mất. Hệ thống sản xuất sử dụng cơ sở dữ liệu vector bền vững như Qdrant hoặc Azure AI Search. +Module này sử dụng lưu trữ trong bộ nhớ để đơn giản hóa. Khi bạn khởi động lại ứng dụng, các tài liệu đã tải lên sẽ mất. Hệ thống thực tế sử dụng cơ sở dữ liệu vector bền vững như Qdrant hoặc Azure AI Search. -### Quản lý Cửa Sổ Ngữ Cảnh +### Quản Lý Cửa Sổ Ngữ Cảnh -Mỗi mô hình có giới hạn tối đa về cửa sổ ngữ cảnh. Bạn không thể đưa mọi đoạn từ một tài liệu lớn vào lời nhắc. Hệ thống lấy ra N đoạn liên quan nhất (mặc định là 5) để giữ trong giới hạn, đồng thời cung cấp đủ ngữ cảnh cho câu trả lời chính xác. +Mỗi mô hình có một cửa sổ ngữ cảnh tối đa. Bạn không thể đưa mọi đoạn chunk từ một tài liệu lớn vào. Hệ thống truy xuất N đoạn chunk có liên quan nhất (mặc định là 5) để nằm trong giới hạn và cung cấp đủ ngữ cảnh cho câu trả lời chính xác. -## Khi Nào Nên Dùng RAG +## Khi Nào RAG Quan Trọng -RAG không phải lúc nào cũng là lựa chọn phù hợp. Hướng dẫn quyết định dưới đây giúp bạn xác định khi nào RAG mang lại giá trị so với các phương pháp đơn giản hơn — như đưa nội dung trực tiếp vào lời nhắc hoặc dựa vào kiến thức tích hợp của mô hình — là đủ: +RAG không phải lúc nào cũng là phương án phù hợp. Hướng dẫn quyết định dưới đây giúp bạn xác định khi nào RAG mang lại giá trị so với khi các phương pháp đơn giản hơn — như đưa nội dung trực tiếp vào prompt hoặc dựa vào kiến thức tích hợp của mô hình — là đủ: -Khi nào sử dụng RAG +When to Use RAG -*Biểu đồ này minh họa hướng dẫn quyết định khi nào RAG có giá trị so với khi nào phương pháp đơn giản hơn là đủ.* +*Biểu đồ này cho thấy hướng dẫn quyết định khi nào RAG mang lại giá trị so với khi các phương pháp đơn giản hơn là đủ.* ## Các Bước Tiếp Theo -**Module tiếp theo:** [04-tools - AI Agents with Tools](../04-tools/README.md) +**Module tiếp theo:** [04-tools - Các đại lý AI với Công cụ](../04-tools/README.md) --- -**Điều hướng:** [← Trước: Module 02 - Kỹ thuật tạo Prompt](../02-prompt-engineering/README.md) | [Quay lại Trang chính](../README.md) | [Tiếp: Module 04 - Công cụ →](../04-tools/README.md) +**Điều hướng:** [← Trước: Module 02 - Kỹ Thuật Prompt](../02-prompt-engineering/README.md) | [Quay lại Trang Chính](../README.md) | [Tiếp: Module 04 - Công Cụ →](../04-tools/README.md) --- -**Tuyên bố từ chối trách nhiệm**: -Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi nỗ lực để đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc thiếu chính xác. Tài liệu gốc bằng ngôn ngữ bản địa nên được xem là nguồn chính xác và đáng tin cậy. Đối với các thông tin quan trọng, việc dịch thuật chuyên nghiệp do con người thực hiện được khuyến nghị. Chúng tôi không chịu trách nhiệm cho bất kỳ sự hiểu nhầm hoặc diễn giải sai nào phát sinh từ việc sử dụng bản dịch này. +**Tuyên bố miễn trừ trách nhiệm**: +Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ gốc nên được coi là nguồn tin chính thức. Đối với thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm về bất kỳ hiểu lầm hoặc giải thích sai nào phát sinh từ việc sử dụng bản dịch này. \ No newline at end of file diff --git a/translations/vi/04-tools/README.md b/translations/vi/04-tools/README.md index 3943f34b9..dff87146a 100644 --- a/translations/vi/04-tools/README.md +++ b/translations/vi/04-tools/README.md @@ -2,83 +2,83 @@ ## Mục lục -- [Video hướng dẫn](../../../04-tools) -- [Những gì bạn sẽ học](../../../04-tools) -- [Yêu cầu trước](../../../04-tools) -- [Hiểu về Đại lý AI với Công cụ](../../../04-tools) -- [Cách gọi Công cụ hoạt động](../../../04-tools) - - [Định nghĩa Công cụ](../../../04-tools) - - [Quyết định](../../../04-tools) - - [Thực thi](../../../04-tools) - - [Tạo phản hồi](../../../04-tools) - - [Kiến trúc: Tự động kết nối Spring Boot](../../../04-tools) -- [Chuỗi Công cụ](../../../04-tools) -- [Chạy Ứng dụng](../../../04-tools) -- [Sử dụng Ứng dụng](../../../04-tools) - - [Thử sử dụng Công cụ đơn giản](../../../04-tools) - - [Kiểm tra Chuỗi Công cụ](../../../04-tools) - - [Xem luồng cuộc trò chuyện](../../../04-tools) - - [Thử nghiệm với các yêu cầu khác nhau](../../../04-tools) -- [Khái niệm chính](../../../04-tools) - - [Mẫu ReAct (Lý luận và Hành động)](../../../04-tools) - - [Mô tả Công cụ quan trọng](../../../04-tools) - - [Quản lý Phiên làm việc](../../../04-tools) - - [Xử lý lỗi](../../../04-tools) -- [Các công cụ có sẵn](../../../04-tools) -- [Khi nào nên dùng đại lý dựa trên công cụ](../../../04-tools) -- [Công cụ so với RAG](../../../04-tools) -- [Bước tiếp theo](../../../04-tools) - -## Video hướng dẫn - -Xem buổi trực tiếp này giải thích cách bắt đầu với module này: +- [Hướng dẫn qua video](#hướng-dẫn-qua-video) +- [Những gì bạn sẽ học](#những-gì-bạn-sẽ-học) +- [Yêu cầu trước](#yêu-cầu-trước) +- [Hiểu về Đại lý AI với Công cụ](#hiểu-về-đại-lý-ai-với-công-cụ) +- [Cách hoạt động của gọi công cụ](#cách-hoạt-động-của-gọi-công-cụ) + - [Định nghĩa công cụ](#định-nghĩa-công-cụ) + - [Quyết định](#quyết-định) + - [Thực thi](#thực-thi) + - [Tạo phản hồi](#tạo-phản-hồi) + - [Kiến trúc: Spring Boot Tự động kết nối](#kiến-trúc-spring-boot-tự-động-kết-nối) +- [Chuỗi công cụ](#chuỗi-công-cụ) +- [Chạy ứng dụng](#chạy-ứng-dụng) +- [Sử dụng ứng dụng](#sử-dụng-ứng-dụng) + - [Thử sử dụng công cụ đơn giản](#thử-sử-dụng-công-cụ-đơn-giản) + - [Kiểm tra chuỗi công cụ](#thử-chuỗi-công-cụ) + - [Xem luồng hội thoại](#xem-luồng-cuộc-trò-chuyện) + - [Thử nghiệm với các yêu cầu khác nhau](#thử-nghiệm-với-các-yêu-cầu-khác-nhau) +- [Các khái niệm chính](#các-khái-niệm-chính) + - [Mẫu ReAct (Suy luận và Hành động)](#mẫu-react-lý-giải-và-hành-động) + - [Mô tả công cụ quan trọng](#mô-tả-công-cụ-quan-trọng) + - [Quản lý phiên làm việc](#quản-lý-phiên-làm-việc) + - [Xử lý lỗi](#xử-lý-lỗi) +- [Công cụ có sẵn](#các-công-cụ-có-sẵn) +- [Khi nào sử dụng đại lý dựa trên công cụ](#khi-nào-nên-dùng-đại-lý-dựa-trên-công-cụ) +- [Công cụ vs RAG](#công-cụ-và-rag) +- [Bước tiếp theo](#các-bước-tiếp-theo) + +## Hướng dẫn qua video + +Xem buổi phát trực tiếp này giải thích cách bắt đầu với module này: AI Agents with Tools and MCP - Live Session ## Những gì bạn sẽ học -Cho đến nay, bạn đã học cách trò chuyện với AI, cấu trúc prompt hiệu quả, và căn cứ câu trả lời trong tài liệu của bạn. Nhưng vẫn còn một hạn chế cơ bản: các mô hình ngôn ngữ chỉ có thể tạo ra văn bản. Chúng không thể kiểm tra thời tiết, thực hiện phép tính, truy vấn cơ sở dữ liệu hay tương tác với các hệ thống bên ngoài. +Cho đến nay, bạn đã học cách trò chuyện với AI, cấu trúc prompt hiệu quả và dựa trên tài liệu để tạo câu trả lời. Nhưng vẫn còn một hạn chế cơ bản: các mô hình ngôn ngữ chỉ có thể tạo văn bản. Chúng không thể kiểm tra thời tiết, tính toán, truy vấn cơ sở dữ liệu, hoặc tương tác với các hệ thống bên ngoài. -Công cụ sẽ thay đổi điều này. Bằng cách cung cấp cho mô hình quyền truy cập vào các hàm mà nó có thể gọi, bạn biến nó từ một trình tạo văn bản thành một đại lý có thể thực hiện hành động. Mô hình quyết định khi nào cần công cụ, công cụ nào để dùng và các tham số cần truyền. Mã của bạn thực thi hàm và trả về kết quả. Mô hình đưa kết quả đó vào phản hồi của nó. +Công cụ thay đổi điều này. Bằng cách cung cấp cho mô hình quyền truy cập các hàm mà nó có thể gọi, bạn biến nó từ một trình tạo văn bản thành một đại lý có thể thực hiện hành động. Mô hình quyết định khi nào cần dùng công cụ, công cụ nào để dùng, và truyền tham số gì. Mã của bạn thực thi hàm đó và trả về kết quả. Mô hình kết hợp kết quả đó vào câu trả lời của nó. ## Yêu cầu trước -- Hoàn thành [Module 01 - Giới thiệu](../01-introduction/README.md) (tài nguyên Azure OpenAI đã được triển khai) -- Các module trước được khuyên hoàn thành (module này tham chiếu [khái niệm RAG từ Module 03](../03-rag/README.md) trong so sánh Công cụ vs RAG) -- File `.env` ở thư mục gốc với thông tin đăng nhập Azure (được tạo bởi `azd up` trong Module 01) +- Đã hoàn thành [Module 01 - Giới thiệu](../01-introduction/README.md) (các tài nguyên Azure OpenAI được triển khai) +- Nên hoàn thành các module trước (module này tham chiếu các [khái niệm RAG từ Module 03](../03-rag/README.md) trong phần so sánh Công cụ vs RAG) +- Tệp `.env` trong thư mục gốc chứa thông tin đăng nhập Azure (được tạo bởi `azd up` trong Module 01) -> **Lưu ý:** Nếu bạn chưa hoàn thành Module 01, hãy làm theo hướng dẫn triển khai ở đó trước. +> **Lưu ý:** Nếu bạn chưa hoàn thành Module 01, vui lòng làm theo hướng dẫn triển khai ở đó trước. ## Hiểu về Đại lý AI với Công cụ -> **📝 Lưu ý:** Thuật ngữ "đại lý" trong module này chỉ các trợ lý AI được tăng cường với khả năng gọi công cụ. Điều này khác với các mẫu **Agentic AI** (đại lý tự động có lập kế hoạch, bộ nhớ và suy luận đa bước) mà chúng ta sẽ đề cập trong [Module 05: MCP](../05-mcp/README.md). +> **📝 Lưu ý:** Thuật ngữ "đại lý" trong module này chỉ các trợ lý AI được nâng cao với khả năng gọi công cụ. Điều này khác với các mẫu **Agentic AI** (đại lý tự chủ với lập kế hoạch, ghi nhớ và suy luận đa bước) mà chúng ta sẽ đề cập trong [Module 05: MCP](../05-mcp/README.md). -Không có công cụ, mô hình ngôn ngữ chỉ có thể tạo ra văn bản từ dữ liệu đào tạo. Hỏi nó về thời tiết hiện tại, nó phải đoán. Cho nó công cụ, nó có thể gọi API thời tiết, thực hiện phép tính, hoặc truy vấn cơ sở dữ liệu — rồi khéo léo lồng ghép kết quả thực tế vào câu trả lời. +Nếu không có công cụ, mô hình ngôn ngữ chỉ có thể tạo ra văn bản dựa trên dữ liệu huấn luyện. Hỏi nó về thời tiết hiện tại, nó phải đoán. Nếu có công cụ, nó có thể gọi API thời tiết, thực hiện tính toán, hoặc truy vấn cơ sở dữ liệu — rồi dệt những kết quả thực vào câu trả lời. Without Tools vs With Tools -*Không có công cụ, mô hình chỉ đoán — có công cụ, nó có thể gọi API, thực hiện phép tính và trả dữ liệu thời gian thực.* +*Không có công cụ, mô hình chỉ đoán — có công cụ, nó có thể gọi API, tính toán, và trả dữ liệu thời gian thực.* -Một đại lý AI với công cụ theo mẫu **Reasoning and Acting (ReAct)**. Mô hình không chỉ phản hồi — nó suy nghĩ về những gì cần, hành động bằng cách gọi công cụ, quan sát kết quả, rồi quyết định có hành động tiếp hay đưa ra câu trả lời cuối cùng: +Một đại lý AI với công cụ tuân theo mẫu **Suy luận và Hành động (ReAct)**. Mô hình không chỉ phản hồi — nó suy nghĩ điều cần thiết, hành động bằng cách gọi công cụ, quan sát kết quả, rồi quyết định tiếp tục hành động hay đưa ra câu trả lời cuối cùng: -1. **Lý luận** — Đại lý phân tích câu hỏi người dùng và xác định thông tin cần -2. **Hành động** — Đại lý chọn công cụ phù hợp, tạo tham số đúng và gọi nó -3. **Quan sát** — Đại lý nhận kết quả công cụ và đánh giá -4. **Lặp lại hoặc Phản hồi** — Nếu cần thêm dữ liệu, đại lý quay lại bước đầu; nếu không, nó tạo câu trả lời tự nhiên +1. **Suy luận** — Đại lý phân tích câu hỏi người dùng và xác định thông tin cần thiết +2. **Hành động** — Đại lý chọn công cụ phù hợp, tạo tham số đúng, và gọi nó +3. **Quan sát** — Đại lý nhận kết quả từ công cụ và đánh giá +4. **Lặp lại hoặc phản hồi** — Nếu cần thêm dữ liệu, đại lý quay vòng lặp; nếu không thì tạo câu trả lời bằng ngôn ngữ tự nhiên ReAct Pattern -*Chu kỳ ReAct — đại lý suy nghĩ cần làm gì, hành động qua gọi công cụ, quan sát kết quả, và lặp lại cho tới khi có câu trả lời cuối.* +*Vòng lặp ReAct — đại lý suy luận việc cần làm, hành động gọi công cụ, quan sát kết quả, và lặp lại cho đến khi đưa ra câu trả lời cuối cùng.* -Việc này xảy ra tự động. Bạn định nghĩa công cụ và mô tả của chúng. Mô hình xử lý quyết định khi nào và làm sao dùng chúng. +Điều này diễn ra tự động. Bạn định nghĩa công cụ và mô tả của chúng. Mô hình xử lý việc quyết định khi nào và cách sử dụng. -## Cách gọi Công cụ hoạt động +## Cách hoạt động của gọi công cụ -### Định nghĩa Công cụ +### Định nghĩa công cụ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -Bạn định nghĩa các hàm với mô tả rõ ràng và các tham số. Mô hình nhìn thấy mô tả này trong prompt hệ thống và hiểu mỗi công cụ làm gì. +Bạn định nghĩa hàm với mô tả rõ ràng và thông số kỹ thuật tham số. Mô hình nhìn thấy mô tả đó trong prompt hệ thống và hiểu công cụ làm gì. ```java @Component @@ -96,104 +96,104 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Trợ lý được tự động kết nối bởi Spring Boot với: +// Trợ lý được Spring Boot tự động cấu hình với: // - Bean ChatModel // - Tất cả các phương thức @Tool từ các lớp @Component // - ChatMemoryProvider để quản lý phiên làm việc ``` -Sơ đồ dưới đây phân tích từng chú thích và cho thấy mỗi phần giúp AI hiểu khi nào gọi công cụ và truyền tham số ra sao: +Sơ đồ dưới đây phân tích từng chú thích và cho thấy từng phần giúp AI hiểu khi nào gọi công cụ và truyền tham số nào: Anatomy of Tool Definitions -*Cấu tạo định nghĩa công cụ — @Tool báo cho AI khi dùng, @P mô tả tham số, và @AiService tự động liên kết lúc khởi động.* +*Cấu trúc định nghĩa công cụ — @Tool cho AI biết khi nào dùng, @P mô tả từng tham số, và @AiService kết nối mọi thứ lúc khởi động.* > **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) và hỏi: -> - "Làm sao tích hợp API thời tiết thực như OpenWeatherMap thay vì dữ liệu giả?" -> - "Mô tả công cụ tốt giúp AI dùng đúng là như thế nào?" -> - "Làm sao xử lý lỗi API và giới hạn tần suất trong cài đặt công cụ?" +> - "Làm thế nào để tích hợp API thời tiết thật như OpenWeatherMap thay vì dữ liệu giả?" +> - "Điều gì tạo nên mô tả công cụ tốt giúp AI dùng đúng cách?" +> - "Làm sao xử lý lỗi API và giới hạn tốc độ trong triển khai công cụ?" ### Quyết định -Khi người dùng hỏi "Thời tiết ở Seattle thế nào?", mô hình không chọn ngẫu nhiên. Nó so sánh ý định với từng mô tả công cụ có, chấm điểm mức liên quan, và chọn công cụ phù hợp nhất. Sau đó tạo ra lời gọi hàm có cấu trúc với tham số đúng — trong trường hợp này, đặt `location` thành `"Seattle"`. +Khi người dùng hỏi "Thời tiết ở Seattle thế nào?", mô hình không chọn công cụ ngẫu nhiên. Nó so sánh ý định người dùng với từng mô tả công cụ mình có, chấm điểm mức liên quan, rồi chọn công cụ phù hợp nhất. Sau đó mô hình tạo cuộc gọi hàm có cấu trúc với tham số đúng — ví dụ thiết lập `location` là `"Seattle"`. -Nếu không có công cụ phù hợp, mô hình trả lời từ kiến thức của nó. Nếu nhiều công cụ phù hợp, nó chọn cái cụ thể nhất. +Nếu không có công cụ phù hợp, mô hình sẽ trả lời dựa trên kiến thức riêng. Nếu nhiều công cụ phù hợp, nó chọn công cụ cụ thể nhất. How the AI Decides Which Tool to Use -*Mô hình đánh giá công cụ có sẵn theo ý định người dùng và chọn phù hợp nhất — nên việc viết mô tả công cụ rõ ràng, cụ thể rất quan trọng.* +*Mô hình đánh giá từng công cụ khả dụng so với ý định người dùng và chọn phù hợp nhất — đó là lý do vì sao việc viết mô tả công cụ rõ ràng, cụ thể quan trọng.* ### Thực thi [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot tự động liên kết interface khai báo `@AiService` với tất cả công cụ đã đăng ký, và LangChain4j tự động thực thi các cuộc gọi công cụ. Ở hậu trường, một cuộc gọi công cụ hoàn chỉnh trải qua sáu giai đoạn — từ câu hỏi ngôn ngữ tự nhiên của người dùng tới câu trả lời ngôn ngữ tự nhiên: +Spring Boot tự động kết nối giao diện khai báo `@AiService` với tất cả các công cụ đã đăng ký, và LangChain4j tự động thực hiện các cuộc gọi công cụ. Ở hậu trường, một cuộc gọi công cụ hoàn chỉnh đi qua sáu giai đoạn — từ câu hỏi ngôn ngữ tự nhiên của người dùng đến trả lời ngôn ngữ tự nhiên: Tool Calling Flow -*Luồng end-to-end — người dùng hỏi, mô hình chọn công cụ, LangChain4j thực thi, và mô hình kết hợp kết quả vào câu trả lời.* +*Quy trình đầu-cuối — người dùng hỏi, mô hình chọn công cụ, LangChain4j thực thi, mô hình kết hợp kết quả vào câu trả lời tự nhiên.* -Nếu bạn đã chạy [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) trong Module 00, bạn đã thấy mẫu này — các công cụ `Calculator` được gọi tương tự. Sơ đồ tuần tự dưới đây mô tả chính xác chuyện gì xảy ra phía sau màn hình trong demo đó: +Ở hậu trường, `AiServices` chạy vòng gọi công cụ cho bất kỳ công cụ nào — ở đây minh họa với `Calculator` đơn giản. Sơ đồ tuần tự dưới đây cho thấy chính xác điều gì xảy ra: Tool Calling Sequence Diagram -*Vòng gọi công cụ trong demo Quick Start — `AiServices` gửi tin nhắn và lược đồ công cụ đến LLM, LLM trả lời với hàm gọi như `add(42, 58)`, LangChain4j chạy phương thức `Calculator` cục bộ, và trả kết quả lại để tạo câu trả lời cuối.* +*Vòng lặp gọi công cụ — `AiServices` gửi tin nhắn và mô tả công cụ đến LLM, LLM trả lời với cuộc gọi hàm kiểu `add(42, 58)`, LangChain4j thực thi phương thức `Calculator` cục bộ, và trả kết quả lại để đưa ra câu trả lời cuối.* > **🤖 Thử với [GitHub Copilot](https://github.com/features/copilot) Chat:** Mở [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) và hỏi: -> - "Mẫu ReAct hoạt động như thế nào và vì sao hiệu quả với đại lý AI?" -> - "Đại lý quyết định công cụ dùng và thứ tự ra sao?" -> - "Nếu thực thi công cụ thất bại thì sao - tôi nên xử lý lỗi thế nào bền vững?" +> - "Mẫu ReAct hoạt động thế nào và tại sao hiệu quả cho đại lý AI?" +> - "Đại lý quyết định dùng công cụ nào và theo thứ tự nào?" +> - "Nếu thực thi công cụ thất bại - tôi nên xử lý lỗi ra sao để bền vững?" ### Tạo phản hồi Mô hình nhận dữ liệu thời tiết và định dạng thành câu trả lời ngôn ngữ tự nhiên cho người dùng. -### Kiến trúc: Tự động kết nối Spring Boot +### Kiến trúc: Spring Boot Tự động kết nối -Module này dùng tích hợp Spring Boot của LangChain4j với interface khai báo `@AiService`. Khi khởi động, Spring Boot phát hiện tất cả `@Component` có phương thức `@Tool`, bean `ChatModel`, và `ChatMemoryProvider` — rồi liên kết tất cả thành interface `Assistant` duy nhất không cần mã lặp lại. +Module này sử dụng tích hợp LangChain4j với Spring Boot qua các giao diện khai báo `@AiService`. Khi khởi động, Spring Boot phát hiện mọi `@Component` chứa phương thức `@Tool`, bean `ChatModel` của bạn, và `ChatMemoryProvider` — rồi tự động kết nối tất cả thành một giao diện `Assistant` mà không cần mã lặp lại. Spring Boot Auto-Wiring Architecture -*Interface @AiService liên kết ChatModel, các component công cụ và bộ nhớ — Spring Boot tự xử lý liên kết.* +*Giao diện @AiService kết nối ChatModel, các thành phần công cụ và bộ nhớ — Spring Boot xử lý kết nối tự động.* -Đây là vòng đời yêu cầu đầy đủ dưới dạng sơ đồ tuần tự — từ yêu cầu HTTP qua controller, service, và proxy được tự động liên kết, đến thực thi công cụ và trả lại kết quả: +Dưới đây là toàn bộ vòng đời yêu cầu dưới dạng sơ đồ tuần tự — từ yêu cầu HTTP qua controller, service, proxy tự động kết nối, đến thực thi công cụ và trả về: Spring Boot Tool Calling Sequence -*Toàn bộ vòng đời yêu cầu Spring Boot — yêu cầu HTTP đi qua controller và service tới proxy Assistant tự động, điều phối LLM và gọi công cụ tự động.* +*Vòng đời yêu cầu Spring Boot hoàn chỉnh — yêu cầu HTTP đi qua controller và service đến proxy Assistant tự động kết nối, là nơi phối hợp giữa LLM và gọi công cụ tự động.* -Các lợi ích chính của cách này: +Lợi ích chính của cách làm này: -- **Tự động liên kết Spring Boot** — ChatModel và công cụ tự động được chèn -- **Mẫu @MemoryId** — Quản lý bộ nhớ theo phiên tự động -- **Một thể hiện duy nhất** — Assistant tạo một lần, dùng lại để nâng cao hiệu suất -- **Thực thi an toàn kiểu** — Gọi trực tiếp phương thức Java với chuyển đổi kiểu -- **Điều phối đa bước** — Xử lý chuỗi công cụ tự động -- **Không mã lặp** — Không cần gọi `AiServices.builder()` hoặc map bộ nhớ thủ công +- **Tự động kết nối Spring Boot** — ChatModel và công cụ được tiêm tự động +- **Mẫu @MemoryId** — Quản lý bộ nhớ theo phiên làm việc tự động +- **Một thực thể duy nhất** — Tạo Assistant duy nhất dùng lại cho hiệu năng tốt hơn +- **Thực thi an toàn kiểu** — Gọi phương thức Java trực tiếp với chuyển đổi kiểu +- **Điều phối đa bước** — Tự động xử lý chuỗi gọi công cụ +- **Không mã lặp lại** — Không cần gọi thủ công AiServices.builder() hay HashMap bộ nhớ -Các phương án khác (gọi thủ công `AiServices.builder()`) tốn nhiều mã hơn và không có lợi ích tích hợp Spring Boot. +Các cách khác (thủ công gọi AiServices.builder()) cần nhiều mã hơn và không có lợi ích tích hợp Spring Boot. -## Chuỗi Công cụ +## Chuỗi công cụ -**Chuỗi Công cụ** — Sức mạnh thực sự của đại lý dựa trên công cụ thể hiện khi một câu hỏi cần nhiều công cụ. Hỏi "Thời tiết ở Seattle theo Fahrenheit là bao nhiêu?" thì đại lý tự động chuỗi hai công cụ: đầu tiên gọi `getCurrentWeather` lấy nhiệt độ Celsius, rồi truyền giá trị đó vào `celsiusToFahrenheit` để chuyển đổi — tất cả trong một lượt trò chuyện. +**Chuỗi công cụ** — Sức mạnh thật sự của đại lý dựa trên công cụ thể hiện khi một câu hỏi cần nhiều công cụ. Hỏi "Thời tiết ở Seattle theo Fahrenheit thế nào?" và đại lý tự động chuỗi hai công cụ: đầu tiên gọi `getCurrentWeather` để lấy nhiệt độ theo Celsius, sau đó truyền giá trị đó cho `celsiusToFahrenheit` để quy đổi — tất cả trong một lượt hội thoại. Tool Chaining Example -*Chuỗi công cụ hoạt động — đại lý gọi getCurrentWeather trước, rồi chuyển kết quả Celsius sang celsiusToFahrenheit, và trả câu trả lời kết hợp.* +*Chuỗi công cụ trong thực tế — đại lý gọi getCurrentWeather trước, rồi truyền kết quả Celsius vào celsiusToFahrenheit, và đưa câu trả lời tổng hợp.* -**Xử lý lỗi nhẹ nhàng** — Hỏi về thời tiết ở thành phố không có trong dữ liệu giả. Công cụ trả lỗi, AI giải thích không giúp được thay vì bị crash. Công cụ thất bại an toàn. Sơ đồ dưới so sánh hai cách tiếp cận — với xử lý lỗi đúng, đại lý bắt ngoại lệ và trả lời hữu ích, không thì ứng dụng sẽ sập: +**Xử lý lỗi mềm mại** — Hỏi thời tiết ở một thành phố không có trong dữ liệu giả. Công cụ trả về thông báo lỗi, và AI giải thích không thể giúp thay vì bị lỗi. Công cụ thất bại an toàn. Sơ đồ phía dưới so sánh hai cách — với xử lý lỗi đúng, đại lý bắt lỗi và trả lời hỗ trợ, còn nếu không thì ứng dụng bị sập: Error Handling Flow -*Khi công cụ lỗi, đại lý bắt lỗi và phản hồi giải thích hữu ích thay vì sập.* +*Khi công cụ thất bại, đại lý bắt lỗi và trả lời bằng lời giải thích hữu ích thay vì ứng dụng bị sập.* -Việc này xảy ra trong một lượt trò chuyện duy nhất. Đại lý tự điều phối nhiều cuộc gọi công cụ. +Điều này diễn ra trong một lượt hội thoại. Đại lý tự động điều phối nhiều cuộc gọi công cụ. -## Chạy Ứng dụng +## Chạy ứng dụng -**Kiểm tra triển khai:** +**Xác nhận triển khai:** -Đảm bảo file `.env` tồn tại ở thư mục gốc với thông tin Azure (được tạo trong Module 01). Chạy lệnh này từ thư mục module (`04-tools/`): +Đảm bảo tệp `.env` tồn tại trong thư mục gốc chứa thông tin đăng nhập Azure (được tạo trong Module 01). Chạy lệnh này từ thư mục module (`04-tools/`): **Bash:** ```bash @@ -207,28 +207,28 @@ Get-Content ..\.env # Nên hiển thị AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYM **Khởi động ứng dụng:** -> **Lưu ý:** Nếu bạn đã khởi động tất cả ứng dụng bằng `./start-all.sh` từ thư mục gốc (như mô tả trong Module 01), module này đã chạy ở cổng 8084. Bạn có thể bỏ qua lệnh khởi động bên dưới và truy cập trực tiếp http://localhost:8084. +> **Lưu ý:** Nếu bạn đã khởi động tất cả ứng dụng bằng `./start-all.sh` từ thư mục gốc (như mô tả trong Module 01), module này đã chạy trên cổng 8084. Bạn có thể bỏ qua các lệnh khởi động bên dưới và truy cập trực tiếp http://localhost:8084. -**Tùy chọn 1: Dùng Spring Boot Dashboard (Khuyên dùng cho người dùng VS Code)** +**Cách 1: Sử dụng Spring Boot Dashboard (Khuyến nghị cho người dùng VS Code)** -Container phát triển bao gồm extension Spring Boot Dashboard, cung cấp giao diện trực quan để quản lý tất cả ứng dụng Spring Boot. Bạn có thể tìm thấy nó trên Thanh hoạt động bên trái VS Code (tìm biểu tượng Spring Boot). +Dev container bao gồm tiện ích mở rộng Spring Boot Dashboard, cung cấp giao diện trực quan để quản lý tất cả ứng dụng Spring Boot. Bạn có thể tìm thấy nó trong Thanh hoạt động bên trái của VS Code (tìm biểu tượng Spring Boot). Từ Spring Boot Dashboard, bạn có thể: - Xem tất cả ứng dụng Spring Boot có trong workspace -- Khởi động/dừng ứng dụng chỉ với một cú click +- Khởi động/dừng ứng dụng chỉ bằng một nhấp chuột - Xem nhật ký ứng dụng theo thời gian thực - Giám sát trạng thái ứng dụng -Chỉ cần nhấp vào nút phát bên cạnh "tools" để bắt đầu module này, hoặc khởi động tất cả các module cùng một lúc. -Đây là giao diện Spring Boot Dashboard trong VS Code: +Chỉ cần bấm nút chạy bên cạnh "tools" để khởi động module này, hoặc khởi động tất cả các module cùng lúc. +Dưới đây là hình ảnh giao diện Spring Boot Dashboard trong VS Code: Bảng điều khiển Spring Boot -*Bảng điều khiển Spring Boot trong VS Code — khởi động, dừng và giám sát tất cả các module từ một nơi duy nhất* +*Bảng điều khiển Spring Boot trong VS Code — bắt đầu, dừng, và giám sát tất cả các module từ một nơi duy nhất* -**Tùy chọn 2: Sử dụng shell scripts** +**Lựa chọn 2: Sử dụng shell scripts** -Khởi động tất cả các ứng dụng web (các module 01-04): +Khởi động tất cả các ứng dụng web (module 01-04): **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -Cả hai script đều tự động tải biến môi trường từ file `.env` gốc và sẽ build các JAR nếu chúng chưa tồn tại. +Cả hai script đều tự động tải biến môi trường từ file `.env` ở thư mục gốc và sẽ xây dựng các file JAR nếu chúng chưa tồn tại. -> **Lưu ý:** Nếu bạn muốn build thủ công tất cả các module trước khi khởi động: +> **Lưu ý:** Nếu bạn muốn tự xây dựng tất cả các module thủ công trước khi bắt đầu: > > **Bash:** > ```bash @@ -272,7 +272,7 @@ Cả hai script đều tự động tải biến môi trường từ file `.env` > mvn clean package -DskipTests > ``` -Mở http://localhost:8084 trong trình duyệt của bạn. +Mở http://localhost:8084 trên trình duyệt của bạn. **Để dừng:** @@ -285,103 +285,103 @@ cd .. && ./stop-all.sh # Tất cả các mô-đun **PowerShell:** ```powershell -.\stop.ps1 # Chỉ mô-đun này +.\stop.ps1 # Chỉ module này # Hoặc -cd ..; .\stop-all.ps1 # Tất cả các mô-đun +cd ..; .\stop-all.ps1 # Tất cả các module ``` ## Sử dụng Ứng dụng -Ứng dụng cung cấp giao diện web nơi bạn có thể tương tác với tác nhân AI có quyền truy cập vào các công cụ thời tiết và chuyển đổi nhiệt độ. Đây là giao diện — bao gồm các ví dụ nhanh và bảng chat để gửi yêu cầu: +Ứng dụng cung cấp một giao diện web nơi bạn có thể tương tác với một đại lý AI có quyền truy cập các công cụ dự báo thời tiết và chuyển đổi nhiệt độ. Đây là giao diện — nó bao gồm các ví dụ khởi động nhanh và một bảng chat để gửi yêu cầu: -Giao diện Công cụ Tác nhân AI +Giao diện Công cụ Đại lý AI -*Giao diện Công cụ Tác nhân AI - ví dụ nhanh và giao diện chat để tương tác với các công cụ* +*Giao diện Công cụ Đại lý AI - các ví dụ nhanh và giao diện trò chuyện để tương tác với công cụ* ### Thử Sử Dụng Công Cụ Đơn Giản -Bắt đầu với yêu cầu đơn giản: "Chuyển đổi 100 độ Fahrenheit sang Celsius". Tác nhân nhận biết cần dùng công cụ chuyển đổi nhiệt độ, gọi hàm với tham số đúng, và trả về kết quả. Hãy để ý việc này rất tự nhiên - bạn không cần chỉ rõ dùng công cụ nào hay cách gọi ra sao. +Bắt đầu với một yêu cầu đơn giản: "Chuyển 100 độ Fahrenheit sang Celsius". Đại lý nhận biết cần sử dụng công cụ chuyển đổi nhiệt độ, gọi công cụ với các tham số đúng, và trả về kết quả. Hãy chú ý sự tự nhiên khi bạn không cần chỉ định công cụ nào hoặc cách gọi nó. ### Thử Chuỗi Công Cụ -Bây giờ thử yêu cầu phức tạp hơn: "Thời tiết ở Seattle như thế nào và chuyển sang Fahrenheit?" Xem cách tác nhân xử lý từng bước. Nó đầu tiên lấy thông tin thời tiết (trả về độ Celsius), nhận ra cần chuyển sang Fahrenheit, gọi công cụ chuyển đổi, rồi kết hợp cả hai kết quả thành một phản hồi duy nhất. +Bây giờ thử cái phức tạp hơn: "Thời tiết ở Seattle thế nào và chuyển sang Fahrenheit?" Xem đại lý thực hiện các bước. Lần đầu lấy dữ liệu thời tiết (trả về độ C), nhận ra cần chuyển sang Fahrenheit, gọi công cụ chuyển đổi, và kết hợp cả hai kết quả trong một phản hồi. -### Quan Sát Luồng Hội Thoại +### Xem Luồng Cuộc Trò Chuyện -Giao diện chat duy trì lịch sử hội thoại, cho phép bạn tương tác đa lượt. Bạn có thể xem tất cả các truy vấn và phản hồi trước đó, giúp dễ dàng theo dõi cuộc trò chuyện và hiểu cách tác nhân xây dựng ngữ cảnh qua nhiều lượt trao đổi. +Giao diện chat duy trì lịch sử cuộc trò chuyện, cho phép bạn thực hiện nhiều lượt tương tác. Bạn có thể xem tất cả câu hỏi và phản hồi trước đó, dễ dàng theo dõi và hiểu cách đại lý xây dựng ngữ cảnh qua nhiều lượt trao đổi. -Hội thoại với Nhiều Lần Gọi Công Cụ +Cuộc trò chuyện với nhiều lần gọi Công cụ -*Hội thoại đa lượt thể hiện các chuyển đổi đơn giản, tra cứu thời tiết và chuỗi công cụ* +*Cuộc trò chuyện nhiều lượt cho thấy các chuyển đổi đơn giản, tra cứu thời tiết và chuỗi công cụ* ### Thử Nghiệm với Các Yêu Cầu Khác Nhau -Thử các tổ hợp khác: +Thử các kết hợp khác nhau: - Tra cứu thời tiết: "Thời tiết ở Tokyo thế nào?" - Chuyển đổi nhiệt độ: "25°C bằng bao nhiêu Kelvin?" -- Truy vấn kết hợp: "Kiểm tra thời tiết ở Paris và cho biết có trên 20°C không" +- Yêu cầu kết hợp: "Kiểm tra thời tiết ở Paris và cho biết liệu có trên 20°C không" -Chú ý cách tác nhân hiểu ngôn ngữ tự nhiên và chuyển sang các lời gọi công cụ phù hợp. +Chú ý cách đại lý diễn giải ngôn ngữ tự nhiên và ánh xạ tới các gọi công cụ phù hợp. ## Các Khái Niệm Chính -### Mẫu ReAct (Lý luận và Hành động) +### Mẫu ReAct (Lý giải và Hành động) -Tác nhân luân phiên giữa lý luận (quyết định phải làm gì) và hành động (sử dụng công cụ). Mẫu này cho phép giải quyết vấn đề tự động thay vì chỉ đáp lại các lệnh. +Đại lý luân phiên giữa lý giải (quyết định làm gì) và hành động (sử dụng công cụ). Mẫu này cho phép giải quyết vấn đề tự động thay vì chỉ phản hồi theo mệnh lệnh. -### Mô tả Công Cụ Quan Trọng +### Mô tả Công cụ Quan trọng -Chất lượng mô tả công cụ ảnh hưởng trực tiếp đến hiệu quả sử dụng của tác nhân. Mô tả rõ ràng, cụ thể giúp mô hình hiểu khi nào và cách gọi từng công cụ. +Chất lượng mô tả công cụ ảnh hưởng trực tiếp đến cách đại lý sử dụng chúng. Mô tả rõ ràng, cụ thể giúp mô hình hiểu khi nào và cách gọi từng công cụ. ### Quản lý Phiên làm việc -Chú thích `@MemoryId` cho phép quản lý bộ nhớ theo phiên tự động. Mỗi ID phiên có một thể hiện `ChatMemory` riêng do bean `ChatMemoryProvider` quản lý, nên nhiều người dùng có thể tương tác với tác nhân đồng thời mà các cuộc trò chuyện không trộn lẫn. Sơ đồ dưới đây thể hiện cách các người dùng được chuyển đến các bộ nhớ riêng biệt dựa trên ID phiên: +Chú thích `@MemoryId` cho phép quản lý bộ nhớ dựa trên phiên làm việc tự động. Mỗi ID phiên có một thể hiện `ChatMemory` riêng do bean `ChatMemoryProvider` quản lý, để nhiều người dùng có thể tương tác với đại lý cùng lúc mà không lẫn lộn cuộc trò chuyện. Hình dưới minh họa cách nhiều người dùng được định tuyến tới các bộ nhớ riêng biệt dựa trên ID phiên của họ: -Quản lý Phiên làm việc với @MemoryId +Quản lý Phiên với @MemoryId -*Mỗi ID phiên tương ứng một lịch sử hội thoại riêng biệt — người dùng không thấy tin nhắn của nhau.* +*Mỗi ID phiên tương ứng với lịch sử trò chuyện riêng biệt — người dùng không bao giờ thấy tin nhắn của nhau.* ### Xử lý Lỗi -Công cụ có thể thất bại — API timeout, tham số sai, dịch vụ bên ngoài ngưng hoạt động. Tác nhân trong môi trường sản xuất cần có xử lý lỗi để mô hình giải thích vấn đề hoặc thử phương án khác thay vì làm sập toàn bộ ứng dụng. Khi công cụ ném ra ngoại lệ, LangChain4j sẽ bắt và gửi lại thông báo lỗi cho mô hình, giúp nó giải thích sự cố bằng ngôn ngữ tự nhiên. +Công cụ có thể gặp lỗi — API hết hạn, tham số không hợp lệ, dịch vụ bên ngoài ngưng hoạt động. Đại lý trong môi trường sản xuất cần xử lý lỗi để mô hình có thể giải thích vấn đề hoặc thử lựa chọn khác thay vì làm sập toàn bộ ứng dụng. Khi công cụ ném ngoại lệ, LangChain4j bắt lỗi đó và chuyển thông báo lỗi cho mô hình, giúp mô hình giải thích vấn đề bằng ngôn ngữ tự nhiên. -## Các Công Cụ Có Sẵn +## Các Công cụ Có Sẵn -Sơ đồ dưới đây cho thấy hệ sinh thái rộng lớn các công cụ bạn có thể xây dựng. Module này minh họa các công cụ thời tiết và chuyển đổi nhiệt độ, nhưng mẫu `@Tool` áp dụng với bất kỳ phương thức Java nào — từ truy vấn cơ sở dữ liệu đến xử lý thanh toán. +Sơ đồ dưới đây trình bày hệ sinh thái rộng lớn các công cụ bạn có thể xây dựng. Module này minh họa công cụ dự báo thời tiết và chuyển đổi nhiệt độ, nhưng cùng mẫu `@Tool` áp dụng cho bất cứ phương thức Java nào — từ truy vấn cơ sở dữ liệu đến xử lý thanh toán. Hệ sinh thái Công cụ -*Bất kỳ phương thức Java nào được chú thích @Tool đều có thể dùng cho AI — mẫu này mở rộng tới cơ sở dữ liệu, API, email, thao tác file và nhiều hơn nữa.* +*Mọi phương thức Java có chú thích @Tool trở nên sẵn dùng cho AI — mẫu này mở rộng tới cơ sở dữ liệu, API, email, thao tác file, và nhiều hơn nữa.* -## Khi Nào Nên Dùng Tác nhân Dựa trên Công cụ +## Khi Nào Nên Dùng Đại lý Dựa Trên Công Cụ -Không phải yêu cầu nào cũng cần công cụ. Quyết định dựa trên việc AI có cần tương tác với hệ thống bên ngoài hay có thể trả lời từ kiến thức sẵn có. Hướng dẫn dưới đây tóm tắt khi nào công cụ có giá trị và khi nào không cần thiết: +Không phải mọi yêu cầu đều cần công cụ. Quyết định dựa trên việc AI có cần tương tác với hệ thống bên ngoài hay có thể trả lời dựa trên kiến thức riêng của nó. Hướng dẫn sau tóm tắt khi nào công cụ mang lại giá trị và khi nào không cần: -Khi Nào Nên Dùng Công Cụ +Khi Nên Dùng Công cụ -*Hướng dẫn nhanh — công cụ dành cho dữ liệu thời gian thực, tính toán và hành động; kiến thức chung và tác vụ sáng tạo không cần.* +*Hướng dẫn quyết định nhanh — công cụ dành cho dữ liệu thời gian thực, tính toán, và hành động; kiến thức chung và nhiệm vụ sáng tạo thì không cần.* ## Công Cụ và RAG -Các module 03 và 04 đều mở rộng khả năng của AI nhưng theo cách khác biệt cơ bản. RAG cung cấp cho mô hình quyền truy cập vào **kiến thức** bằng cách truy xuất tài liệu. Công cụ cho phép mô hình thực hiện **hành động** bằng cách gọi hàm. Sơ đồ dưới đây so sánh hai cách tiếp cận này cạnh nhau — từ cách mỗi quy trình vận hành đến sự đánh đổi giữa chúng: +Module 03 và 04 đều mở rộng khả năng của AI nhưng theo những cách cơ bản khác nhau. RAG cho phép mô hình truy cập **kiến thức** bằng cách truy xuất tài liệu. Công cụ cho phép mô hình thực hiện **hành động** bằng cách gọi các hàm. Hình so sánh dưới đây đặt hai phương pháp cạnh nhau — từ cách hoạt động của từng luồng công việc đến những điểm đánh đổi giữa chúng: -So sánh Công Cụ và RAG +So sánh Công cụ và RAG *RAG truy xuất thông tin từ tài liệu tĩnh — Công cụ thực thi hành động và lấy dữ liệu động, thời gian thực. Nhiều hệ thống sản xuất kết hợp cả hai.* -Trong thực tế, nhiều hệ thống sản xuất kết hợp cả hai cách: RAG để căn cứ câu trả lời trong tài liệu của bạn, và Công cụ để lấy dữ liệu trực tiếp hoặc thực hiện thao tác. +Thực tế, nhiều hệ thống sản xuất kết hợp cả hai: RAG để căn cứ câu trả lời trên tài liệu, và Công cụ để lấy dữ liệu trực tiếp hoặc thực hiện tác vụ. -## Bước Tiếp Theo +## Các Bước Tiếp Theo -**Module tiếp theo:** [05-mcp - Model Context Protocol (MCP)](../05-mcp/README.md) +**Module tiếp theo:** [05-mcp - Giao thức ngữ cảnh mô hình (MCP)](../05-mcp/README.md) --- -**Điều hướng:** [← Trước: Module 03 - RAG](../03-rag/README.md) | [Về Trang Chính](../README.md) | [Tiếp: Module 05 - MCP →](../05-mcp/README.md) +**Điều hướng:** [← Trước: Module 03 - RAG](../03-rag/README.md) | [Quay lại Chính](../README.md) | [Tiếp theo: Module 05 - MCP →](../05-mcp/README.md) --- -**Tuyên bố từ chối trách nhiệm**: -Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc không chính xác. Tài liệu gốc bằng ngôn ngữ bản địa nên được xem là nguồn đáng tin cậy. Đối với các thông tin quan trọng, khuyến nghị sử dụng dịch thuật chuyên nghiệp do con người thực hiện. Chúng tôi không chịu trách nhiệm về bất kỳ sự hiểu lầm hay giải thích sai nào phát sinh từ việc sử dụng bản dịch này. +**Tuyên bố miễn trừ trách nhiệm**: +Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ gốc nên được coi là nguồn tin chính thức. Đối với thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm về bất kỳ hiểu lầm hoặc giải thích sai nào phát sinh từ việc sử dụng bản dịch này. \ No newline at end of file diff --git a/translations/vi/README.md b/translations/vi/README.md index 1efc7f660..1d251ebea 100644 --- a/translations/vi/README.md +++ b/translations/vi/README.md @@ -2,18 +2,18 @@ # LangChain4j cho Người mới bắt đầu -Một khóa học xây dựng ứng dụng AI với LangChain4j và Azure OpenAI GPT-5.2, từ chat cơ bản đến các tác nhân AI. +Một khóa học xây dựng ứng dụng AI với LangChain4j và Azure OpenAI GPT-5.2, từ trò chuyện cơ bản đến đại lý AI. -### 🌐 Hỗ trợ Đa Ngôn Ngữ +### 🌐 Hỗ trợ đa ngôn ngữ -#### Hỗ trợ qua GitHub Action (Tự động & Luôn Cập Nhật) +#### Được hỗ trợ qua GitHub Action (Tự động & Luôn cập nhật) [Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](./README.md) -> **Ưu tiên Clone Tại Máy?** +> **Ưu tiên clone về máy?** > -> Kho lưu trữ này bao gồm hơn 50 bản dịch ngôn ngữ làm tăng đáng kể kích thước tải xuống. Để clone mà không có các bản dịch, hãy sử dụng sparse checkout: +> Kho lưu trữ này bao gồm hơn 50 bản dịch ngôn ngữ làm tăng đáng kể dung lượng tải về. Để clone mà không cần bản dịch, sử dụng sparse checkout: > > **Bash / macOS / Linux:** > ```bash @@ -29,107 +29,106 @@ Một khóa học xây dựng ứng dụng AI với LangChain4j và Azure OpenAI > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> Điều này cung cấp cho bạn mọi thứ cần thiết để hoàn thành khóa học với tốc độ tải xuống nhanh hơn nhiều. +> Điều này cung cấp mọi thứ bạn cần để hoàn thành khóa học với tốc độ tải nhanh hơn nhiều. -## Mục Lục +## Mục lục -1. [Bắt đầu Nhanh](00-quick-start/README.md) - Bắt đầu với LangChain4j -2. [Giới thiệu](01-introduction/README.md) - Tìm hiểu các kiến thức cơ bản của LangChain4j -3. [Kỹ thuật Prompt](02-prompt-engineering/README.md) - Thành thạo thiết kế prompt hiệu quả -4. [RAG (Tạo nội dung kết hợp truy xuất)](03-rag/README.md) - Xây dựng hệ thống kiến thức thông minh -5. [Công Cụ](04-tools/README.md) - Tích hợp công cụ bên ngoài và trợ lý đơn giản -6. [MCP (Giao thức Bối cảnh Mô hình)](05-mcp/README.md) - Làm việc với Giao thức Bối cảnh Mô hình (MCP) và các module tác nhân +1. [Giới thiệu](01-introduction/README.md) - Học các nguyên tắc cơ bản của LangChain4j +2. [Kỹ thuật Prompt](02-prompt-engineering/README.md) - Thành thạo thiết kế prompt hiệu quả +3. [RAG (Tăng cường truy xuất thông tin)](03-rag/README.md) - Xây dựng hệ thống dựa trên kiến thức thông minh +4. [Công cụ](04-tools/README.md) - Tích hợp các công cụ bên ngoài và trợ lý đơn giản +5. [MCP (Giao thức ngữ cảnh mô hình)](05-mcp/README.md) - Làm việc với giao thức ngữ cảnh mô hình và các mô-đun đại lý -### Hướng dẫn Video +### Video hướng dẫn -Mỗi module có phiên trực tiếp đi kèm, nơi chúng ta đi qua từng khái niệm và mã nguồn từng bước. +Mỗi mô-đun có một buổi học trực tiếp đi kèm nơi chúng ta trình bày các khái niệm và mã nguồn từng bước. -| Module | Video | +| Mô-đun | Video | |--------|-------| | 01 - Giới thiệu | [Bắt đầu với LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - Kỹ thuật Prompt | [Kỹ thuật Prompt với LangChain4j](https://www.youtube.com/live/PJ6aBaE6bog) | | 03 - RAG | [RAG với LangChain4j](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - Công Cụ & 05 - MCP | [Tác nhân AI với Công Cụ và MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 04 - Công cụ & 05 - MCP | [Đại lý AI với Công cụ và MCP](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## Lộ Trình Học +## Lộ trình học -**Mới với LangChain4j?** Xem phần [Thuật ngữ](docs/GLOSSARY.md) để biết các định nghĩa về các thuật ngữ và khái niệm chính. +**Mới với LangChain4j?** Xem [Thuật ngữ](docs/GLOSSARY.md) để định nghĩa các thuật ngữ và khái niệm chính. -> **Bắt đầu Nhanh** +> **Bắt đầu nhanh** 1. Fork kho lưu trữ này vào tài khoản GitHub của bạn -2. Nhấp vào **Code** → tab **Codespaces** → **...** → **New with options...** -3. Sử dụng các tùy chọn mặc định – đây sẽ chọn container Phát triển được tạo cho khóa học này -4. Nhấp **Create codespace** -5. Chờ 5-10 phút để môi trường sẵn sàng -6. Vào ngay [Bắt đầu Nhanh](./00-quick-start/README.md) để bắt đầu! +2. Nhấn **Code** → tab **Codespaces** → **...** → **New with options...** +3. Sử dụng mặc định – điều này sẽ chọn container phát triển được tạo cho khóa học này +4. Nhấn **Create codespace** +5. Đợi 5-10 phút để môi trường sẵn sàng +6. Tới ngay [Giới thiệu](./01-introduction/README.md) để bắt đầu! -Sau khi hoàn thành các module, tham khảo [Hướng dẫn Kiểm thử](docs/TESTING.md) để xem các khái niệm kiểm thử LangChain4j trong thực tế. +Sau khi hoàn thành các mô-đun, khám phá [Hướng dẫn thử nghiệm](docs/TESTING.md) để xem các khái niệm kiểm thử LangChain4j trong thực tế. -> **Lưu ý:** Khóa đào tạo này sử dụng cả Mô hình GitHub và Azure OpenAI. Module [Bắt đầu Nhanh](00-quick-start/README.md) sử dụng Mô hình GitHub (không cần đăng ký Azure), trong khi các module 1-5 dùng Azure OpenAI. Bắt đầu với tài khoản Azure [MIỄN PHÍ](https://aka.ms/azure-free-account) nếu bạn chưa có. +> **Lưu ý:** Khóa đào tạo này sử dụng Azure OpenAI. Bắt đầu với [tài khoản Azure MIỄN PHÍ](https://aka.ms/azure-free-account) nếu bạn chưa có. -## Học với GitHub Copilot +## Học cùng GitHub Copilot -Để nhanh chóng bắt đầu code, mở dự án này trong GitHub Codespace hoặc IDE cục bộ của bạn với devcontainer được cung cấp. Devcontainer sử dụng trong khóa học này đã được cấu hình sẵn với GitHub Copilot cho lập trình đôi AI. +Để bắt đầu lập trình nhanh, mở dự án này trong GitHub Codespace hoặc IDE cục bộ của bạn với devcontainer được cung cấp. Devcontainer sử dụng trong khóa học này đã được cấu hình sẵn với GitHub Copilot cho lập trình cùng AI. -Mỗi ví dụ mã bao gồm các câu hỏi gợi ý bạn có thể hỏi GitHub Copilot để tìm hiểu sâu hơn. Tìm các dấu hiệu 💡/🤖 trong: +Mỗi ví dụ mã đều có các câu hỏi gợi ý bạn có thể hỏi GitHub Copilot để hiểu sâu hơn. Tìm các gợi ý 💡/🤖 trong: -- **Tiêu đề file Java** - Các câu hỏi cụ thể cho từng ví dụ -- **README các module** - Các câu hỏi khám phá sau ví dụ mã +- **Tiêu đề file Java** - Câu hỏi đặc thù cho từng ví dụ +- **README mô-đun** - Gợi ý khám phá sau ví dụ mã -**Cách dùng:** Mở bất kỳ file mã nào và hỏi Copilot các câu hỏi gợi ý. Copilot có đầy đủ bối cảnh mã nguồn và có thể giải thích, mở rộng, và đề xuất các phương án khác. +**Cách dùng:** Mở bất kỳ file mã nào và hỏi Copilot các câu hỏi gợi ý. Nó có đầy đủ ngữ cảnh của mã nguồn và có thể giải thích, mở rộng, và đề xuất các lựa chọn thay thế. -Muốn học thêm? Xem [Copilot cho Lập trình Đôi AI](https://aka.ms/GitHubCopilotAI). +Muốn học thêm? Xem [Copilot cho lập trình cùng AI](https://aka.ms/GitHubCopilotAI). - -## Tài Nguyên Bổ Sung +## Tài nguyên bổ sung ### LangChain -[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j cho Người mới bắt đầu](https://img.shields.io/badge/LangChain4j%20cho%20Người%20mới%20bắt%20đầu-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js cho Người mới bắt đầu](https://img.shields.io/badge/LangChain.js%20cho%20Người%20mới%20bắt%20đầu-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain cho Người mới bắt đầu](https://img.shields.io/badge/LangChain%20cho%20Người%20mới%20bắt%20đầu-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents -[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Đại lý +[![AZD cho Người mới bắt đầu](https://img.shields.io/badge/AZD%20cho%20Người%20mới%20bắt%20đầu-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI cho Người mới bắt đầu](https://img.shields.io/badge/Edge%20AI%20cho%20Người%20mới%20bắt%20đầu-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP cho Người mới bắt đầu](https://img.shields.io/badge/MCP%20cho%20Người%20mới%20bắt%20đầu-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Đại lý AI cho Người mới bắt đầu](https://img.shields.io/badge/Đại%20lý%20AI%20cho%20Người%20mới%20bắt%20đầu-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Loạt AI Tạo Sinh -[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +### Series AI tạo sinh +[![AI tạo sinh cho Người mới bắt đầu](https://img.shields.io/badge/AI%20tạo%20sinh%20cho%20Người%20mới%20bắt%20đầu-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI tạo sinh (.NET)](https://img.shields.io/badge/AI%20tạo%20sinh%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![AI tạo sinh (Java)](https://img.shields.io/badge/AI%20tạo%20sinh%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![AI tạo sinh (JavaScript)](https://img.shields.io/badge/AI%20tạo%20sinh%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- -### Học Cốt lõi -[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![An ninh mạng cho người mới bắt đầu](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![Phát triển web cho người mới bắt đầu](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![IoT cho người mới bắt đầu](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![Phát triển XR cho người mới bắt đầu](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +### Học cốt lõi +[![ML cho Người mới bắt đầu](https://img.shields.io/badge/ML%20cho%20Người%20mới%20bắt%20đầu-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Khoa học dữ liệu cho Người mới bắt đầu](https://img.shields.io/badge/Khoa%20học%20dữ%20liệu%20cho%20Người%20mới%20bắt%20đầu-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI cho Người mới bắt đầu](https://img.shields.io/badge/AI%20cho%20Người%20mới%20bắt%20đầu-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![An ninh mạng cho Người mới bắt đầu](https://img.shields.io/badge/An%20ninh%20mạng%20cho%20Người%20mới%20bắt%20đầu-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- -### Series Copilot -[![Copilot cho Lập trình cặp với AI](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![Copilot cho C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Cuộc phiêu lưu Copilot](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +### Chuỗi Copilot +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## Nhận trợ giúp -Nếu bạn gặp khó khăn hoặc có bất kỳ câu hỏi nào về xây dựng ứng dụng AI, hãy tham gia: +Nếu bạn gặp khó khăn hoặc có bất kỳ câu hỏi nào về việc xây dựng ứng dụng AI, hãy tham gia: [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) @@ -139,11 +138,11 @@ Nếu bạn có phản hồi về sản phẩm hoặc lỗi khi xây dựng, hã ## Giấy phép -Giấy phép MIT - Xem file [LICENSE](../../LICENSE) để biết chi tiết. +Giấy phép MIT - Xem tệp [LICENSE](../../LICENSE) để biết chi tiết. --- -**Tuyên bố từ chối trách nhiệm**: -Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc không chính xác. Văn bản gốc bằng ngôn ngữ gốc của tài liệu nên được coi là nguồn đáng tin cậy và chính xác nhất. Đối với các thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm về bất kỳ sự hiểu nhầm hoặc giải thích sai nào phát sinh từ việc sử dụng bản dịch này. +**Tuyên bố miễn trừ trách nhiệm**: +Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ gốc nên được coi là nguồn tin chính thức. Đối với thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm về bất kỳ hiểu lầm hoặc giải thích sai nào phát sinh từ việc sử dụng bản dịch này. \ No newline at end of file diff --git a/translations/vi/docs/GLOSSARY.md b/translations/vi/docs/GLOSSARY.md index b659e7ef5..fde2b8926 100644 --- a/translations/vi/docs/GLOSSARY.md +++ b/translations/vi/docs/GLOSSARY.md @@ -1,112 +1,112 @@ -# Bảng Thuật Ngữ LangChain4j +# Thuật ngữ LangChain4j -## Mục Lục +## Mục lục -- [Khái Niệm Cốt Lõi](../../../docs) -- [Các Thành Phần LangChain4j](../../../docs) -- [Khái Niệm AI/ML](../../../docs) -- [Hàng Rào Bảo Vệ](../../../docs) -- [Kỹ Thuật Prompt](../../../docs) -- [RAG (Tạo Văn Bản Kèm Truy Xuất)](../../../docs) -- [Agent và Công Cụ](../../../docs) -- [Module Agentic](../../../docs) -- [Giao Thức Ngữ Cảnh Mô Hình (MCP)](../../../docs) -- [Dịch Vụ Azure](../../../docs) -- [Kiểm Thử và Phát Triển](../../../docs) +- [Khái niệm cốt lõi](#khái-niệm-cốt-lõi) +- [Thành phần LangChain4j](#thành-phần-langchain4j) +- [Khái niệm AI/ML](#khái-niệm-aiml) +- [Hàng rào bảo vệ](#hàng-rào-bảo-vệ) +- [Kỹ thuật Prompt](#prompt-engineering---module-02) +- [RAG (Sinh Tăng cường Truy xuất)](#rag-retrieval-augmented-generation---module-03) +- [Tác nhân và Công cụ](#agents-and-tools---module-04) +- [Module Agentic](#agentic-module---module-05) +- [Giao thức Ngữ cảnh Mô hình (MCP)](#model-context-protocol-mcp---module-05) +- [Dịch vụ Azure](#azure-services---module-01) +- [Kiểm thử và Phát triển](#testing-and-development---testing-guide) -Tham khảo nhanh các thuật ngữ và khái niệm được sử dụng trong suốt khóa học. +Tham khảo nhanh các thuật ngữ và khái niệm sử dụng xuyên suốt khóa học. -## Khái Niệm Cốt Lõi +## Khái niệm cốt lõi -**AI Agent** - Hệ thống sử dụng AI để suy luận và hành động một cách tự động. [Module 04](../04-tools/README.md) +**AI Agent** - Hệ thống sử dụng AI để suy luận và hành động tự chủ. [Module 04](../04-tools/README.md) -**Chain** - Chuỗi các thao tác mà kết quả đầu ra được truyền vào bước tiếp theo. +**Chain** - Chuỗi các thao tác, đầu ra của bước trước là đầu vào cho bước tiếp theo. -**Chunking** - Phân tách tài liệu thành các mảnh nhỏ hơn. Thông thường: 300-500 token với phần chồng lặp. [Module 03](../03-rag/README.md) +**Chunking** - Chia nhỏ tài liệu thành các đoạn nhỏ hơn. Thông thường: 300-500 token với phần chồng lấn. [Module 03](../03-rag/README.md) **Context Window** - Số token tối đa mà mô hình có thể xử lý. GPT-5.2: 400K token (tối đa 272K đầu vào, 128K đầu ra). **Embeddings** - Vector số biểu diễn ý nghĩa văn bản. [Module 03](../03-rag/README.md) -**Function Calling** - Mô hình tạo các yêu cầu có cấu trúc để gọi hàm bên ngoài. [Module 04](../04-tools/README.md) +**Function Calling** - Mô hình tạo yêu cầu có cấu trúc để gọi hàm bên ngoài. [Module 04](../04-tools/README.md) **Hallucination** - Khi mô hình tạo ra thông tin sai nhưng có vẻ hợp lý. **Prompt** - Văn bản đầu vào cho mô hình ngôn ngữ. [Module 02](../02-prompt-engineering/README.md) -**Semantic Search** - Tìm kiếm theo ý nghĩa sử dụng embeddings, không phải từ khóa. [Module 03](../03-rag/README.md) +**Semantic Search** - Tìm kiếm theo nghĩa sử dụng embeddings, không dùng từ khóa. [Module 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless: không có bộ nhớ. Stateful: duy trì lịch sử cuộc trò chuyện. [Module 01](../01-introduction/README.md) +**Stateful vs Stateless** - Stateless: không nhớ. Stateful: duy trì lịch sử hội thoại. [Module 01](../01-introduction/README.md) **Tokens** - Đơn vị văn bản cơ bản mà mô hình xử lý. Ảnh hưởng đến chi phí và giới hạn. [Module 01](../01-introduction/README.md) -**Tool Chaining** - Thực thi công cụ tuần tự nơi kết quả đầu ra điều chỉnh cuộc gọi tiếp theo. [Module 04](../04-tools/README.md) +**Tool Chaining** - Thực thi công cụ tuần tự, đầu ra của công cụ này là đầu vào cho công cụ tiếp theo. [Module 04](../04-tools/README.md) -## Các Thành Phần LangChain4j +## Thành phần LangChain4j **AiServices** - Tạo giao diện dịch vụ AI kiểu an toàn. -**OpenAiOfficialChatModel** - Khách hàng đồng nhất cho các mô hình OpenAI và Azure OpenAI. +**OpenAiOfficialChatModel** - Client thống nhất cho các mô hình OpenAI và Azure OpenAI. -**OpenAiOfficialEmbeddingModel** - Tạo embeddings sử dụng khách OpenAI chính thức (hỗ trợ cả OpenAI và Azure OpenAI). +**OpenAiOfficialEmbeddingModel** - Tạo embeddings sử dụng client OpenAI Official (hỗ trợ cả OpenAI và Azure OpenAI). -**ChatModel** - Giao diện cốt lõi cho các mô hình ngôn ngữ. +**ChatModel** - Giao diện lõi cho các mô hình ngôn ngữ. -**ChatMemory** - Duy trì lịch sử cuộc trò chuyện. +**ChatMemory** - Duy trì lịch sử hội thoại. **ContentRetriever** - Tìm các đoạn tài liệu phù hợp cho RAG. -**DocumentSplitter** - Phân tách tài liệu thành các đoạn nhỏ. +**DocumentSplitter** - Chia tài liệu thành các đoạn nhỏ. -**EmbeddingModel** - Chuyển đổi văn bản thành vector số. +**EmbeddingModel** - Chuyển văn bản thành vector số. -**EmbeddingStore** - Lưu trữ và truy xuất embeddings. +**EmbeddingStore** - Lưu trữ và truy vấn embeddings. **MessageWindowChatMemory** - Duy trì cửa sổ trượt các tin nhắn gần đây. -**PromptTemplate** - Tạo prompt tái sử dụng với các chỗ giữ chỗ `{{variable}}`. +**PromptTemplate** - Tạo các prompt tái sử dụng với các chỗ giữ chỗ `{{variable}}`. -**TextSegment** - Đoạn văn bản có metadata. Dùng trong RAG. +**TextSegment** - Đoạn văn bản kèm siêu dữ liệu. Dùng trong RAG. -**ToolExecutionRequest** - Đại diện cho yêu cầu thực thi công cụ. +**ToolExecutionRequest** - Biểu diễn yêu cầu thực thi công cụ. -**UserMessage / AiMessage / SystemMessage** - Các loại tin nhắn trong cuộc trò chuyện. +**UserMessage / AiMessage / SystemMessage** - Các loại tin nhắn trong hội thoại. -## Khái Niệm AI/ML +## Khái niệm AI/ML **Few-Shot Learning** - Cung cấp ví dụ trong prompt. [Module 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - Các mô hình AI được huấn luyện trên lượng lớn dữ liệu văn bản. +**Large Language Model (LLM)** - Mô hình AI được huấn luyện trên lượng lớn dữ liệu văn bản. -**Reasoning Effort** - Tham số GPT-5.2 điều khiển độ sâu suy nghĩ. [Module 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - Tham số GPT-5.2 điều chỉnh độ sâu suy luận. [Module 02](../02-prompt-engineering/README.md) -**Temperature** - Điều khiển độ ngẫu nhiên của đầu ra. Thấp = xác định, cao = sáng tạo. +**Temperature** - Điều chỉnh độ ngẫu nhiên đầu ra. Thấp = xác định, cao = sáng tạo. -**Vector Database** - Cơ sở dữ liệu chuyên biệt cho embeddings. [Module 03](../03-rag/README.md) +**Vector Database** - Cơ sở dữ liệu chuyên dụng cho embeddings. [Module 03](../03-rag/README.md) **Zero-Shot Learning** - Thực hiện nhiệm vụ mà không có ví dụ. [Module 02](../02-prompt-engineering/README.md) -## Hàng Rào Bảo Vệ - [Module 00](../00-quick-start/README.md) +## Hàng rào bảo vệ -**Defense in Depth** - Phương pháp bảo mật đa lớp kết hợp hàng rào ứng dụng với bộ lọc an toàn nhà cung cấp. +**Defense in Depth** - Cách tiếp cận an ninh đa lớp kết hợp hàng rào cấp ứng dụng và bộ lọc an toàn của nhà cung cấp. **Hard Block** - Nhà cung cấp trả lỗi HTTP 400 cho vi phạm nội dung nghiêm trọng. -**InputGuardrail** - Giao diện LangChain4j để kiểm tra đầu vào người dùng trước khi tới LLM. Tiết kiệm chi phí và giảm độ trễ bằng cách chặn prompt độc hại sớm. +**InputGuardrail** - Giao diện LangChain4j để kiểm tra đầu vào người dùng trước khi tới LLM. Tiết kiệm chi phí và giảm độ trễ bằng cách chặn prompt có hại từ sớm. -**InputGuardrailResult** - Kiểu trả về cho kiểm tra guardrail: `success()` hoặc `fatal("lý do")`. +**InputGuardrailResult** - Kiểu trả về kiểm tra hàng rào: `success()` hoặc `fatal("lý do")`. -**OutputGuardrail** - Giao diện xác thực phản hồi AI trước khi trả cho người dùng. +**OutputGuardrail** - Giao diện kiểm tra phản hồi AI trước khi trả lại cho người dùng. -**Provider Safety Filters** - Bộ lọc nội dung tích hợp sẵn từ nhà cung cấp AI (ví dụ GitHub Models) bắt vi phạm ngay cấp API. +**Provider Safety Filters** - Bộ lọc nội dung tích hợp của các nhà cung cấp AI (ví dụ Azure OpenAI) bắt lỗi ở cấp API. -**Soft Refusal** - Mô hình từ chối trả lời một cách lịch sự mà không gây lỗi. +**Soft Refusal** - Mô hình lịch sự từ chối trả lời mà không lỗi. -## Kỹ Thuật Prompt - [Module 02](../02-prompt-engineering/README.md) +## Kỹ thuật Prompt - [Module 02](../02-prompt-engineering/README.md) **Chain-of-Thought** - Suy luận từng bước để tăng độ chính xác. -**Constrained Output** - Áp đặt định dạng hoặc cấu trúc cụ thể. +**Constrained Output** - Bắt đầu theo định dạng hoặc cấu trúc cụ thể. **High Eagerness** - Mẫu GPT-5.2 cho suy luận kỹ lưỡng. @@ -114,87 +114,87 @@ Tham khảo nhanh các thuật ngữ và khái niệm được sử dụng trong **Multi-Turn Conversation** - Duy trì ngữ cảnh qua nhiều lượt trao đổi. -**Role-Based Prompting** - Thiết lập nhân vật cho mô hình qua tin nhắn hệ thống. +**Role-Based Prompting** - Thiết lập cá tính mô hình qua tin nhắn hệ thống. -**Self-Reflection** - Mô hình tự đánh giá và cải thiện kết quả. +**Self-Reflection** - Mô hình đánh giá và cải tiến đầu ra của chính nó. **Structured Analysis** - Khung đánh giá cố định. -**Task Execution Pattern** - Lập kế hoạch → Thực thi → Tóm tắt. +**Task Execution Pattern** - Lên kế hoạch → Thực thi → Tóm tắt. -## RAG (Tạo Văn Bản Kèm Truy Xuất) - [Module 03](../03-rag/README.md) +## RAG (Sinh Tăng cường Truy xuất) - [Module 03](../03-rag/README.md) -**Document Processing Pipeline** - Tải → chia đoạn → nhúng → lưu trữ. +**Document Processing Pipeline** - Tải → chia đoạn → chuyển vector → lưu trữ. -**In-Memory Embedding Store** - Kho lưu trữ không bền dùng cho thử nghiệm. +**In-Memory Embedding Store** - Bộ lưu trữ không bền dùng để kiểm thử. -**RAG** - Kết hợp truy xuất dữ liệu với tạo văn bản để củng cố phản hồi. +**RAG** - Kết hợp truy xuất với sinh để tăng độ xác thực của câu trả lời. -**Similarity Score** - Đo lường (0-1) độ tương đồng ngữ nghĩa. +**Similarity Score** - Thang đo (0-1) về mức độ tương đồng ngữ nghĩa. -**Source Reference** - Metadata về nội dung được truy xuất. +**Source Reference** - Siêu dữ liệu về nội dung được truy xuất. -## Agent và Công Cụ - [Module 04](../04-tools/README.md) +## Tác nhân và Công cụ - [Module 04](../04-tools/README.md) **@Tool Annotation** - Đánh dấu phương thức Java là công cụ có thể gọi bởi AI. -**ReAct Pattern** - Suy nghĩ → Hành động → Quan sát → Lặp lại. +**ReAct Pattern** - Suy luận → Hành động → Quan sát → Lặp lại. -**Session Management** - Tách biệt ngữ cảnh cho các người dùng khác nhau. +**Session Management** - Quản lý ngữ cảnh riêng biệt cho từng người dùng. **Tool** - Hàm mà AI agent có thể gọi. -**Tool Description** - Tài liệu về mục đích và tham số của công cụ. +**Tool Description** - Tài liệu về mục đích và tham số công cụ. ## Module Agentic - [Module 05](../05-mcp/README.md) -**@Agent Annotation** - Đánh dấu giao diện là agent AI với định nghĩa hành vi khai báo. +**@Agent Annotation** - Đánh dấu giao diện là agent AI với hành vi khai báo. **Agent Listener** - Hook để giám sát thực thi agent qua `beforeAgentInvocation()` và `afterAgentInvocation()`. -**Agentic Scope** - Bộ nhớ chia sẻ nơi agent lưu kết quả sử dụng `outputKey` để agent khác sử dụng. +**Agentic Scope** - Bộ nhớ chia sẻ nơi các agent lưu kết quả sử dụng `outputKey` cho agent phía sau truy xuất. -**AgenticServices** - Nhà máy tạo agent qua `agentBuilder()` và `supervisorBuilder()`. +**AgenticServices** - Nhà máy tạo agent dùng `agentBuilder()` và `supervisorBuilder()`. -**Conditional Workflow** - Định tuyến dựa trên điều kiện tới các agent chuyên gia khác nhau. +**Conditional Workflow** - Chuyển hướng theo điều kiện tới các agent chuyên môn khác nhau. -**Human-in-the-Loop** - Mẫu luồng công việc thêm điểm kiểm duyệt con người để phê duyệt hoặc xem xét nội dung. +**Human-in-the-Loop** - Mẫu quy trình thêm bước kiểm duyệt hoặc xem xét nội dung từ con người. -**langchain4j-agentic** - Phụ thuộc Maven cho xây dựng agent khai báo (thử nghiệm). +**langchain4j-agentic** - Định nghĩa Maven cho xây dựng agent khai báo (thử nghiệm). -**Loop Workflow** - Lặp thực thi agent đến khi thỏa điều kiện (ví dụ điểm chất lượng ≥ 0.8). +**Loop Workflow** - Thực thi agent lặp lại tới khi thỏa điều kiện (ví dụ điểm chất lượng ≥ 0.8). -**outputKey** - Tham số chú thích agent chỉ ra nơi lưu kết quả trong Agentic Scope. +**outputKey** - Tham số đánh dấu agent chỉ định nơi lưu kết quả trong Agentic Scope. -**Parallel Workflow** - Chạy nhiều agent đồng thời cho các nhiệm vụ độc lập. +**Parallel Workflow** - Chạy đồng thời nhiều agent cho các nhiệm vụ độc lập. -**Response Strategy** - Cách supervisor tạo câu trả lời cuối cùng: LAST (cuối cùng), SUMMARY (tóm tắt), hoặc SCORED (được điểm). +**Response Strategy** - Cách supervisor xác định câu trả lời cuối cùng: LAST, SUMMARY, hoặc SCORED. -**Sequential Workflow** - Thực thi agent theo thứ tự, kết quả đầu ra chảy sang bước tiếp theo. +**Sequential Workflow** - Thực thi tuần tự các agent, đầu ra là đầu vào tiếp theo. -**Supervisor Agent Pattern** - Mẫu agentic nâng cao nơi supervisor LLM quyết định động các sub-agent cần gọi. +**Supervisor Agent Pattern** - Mẫu agent nâng cao, nơi supervisor LLM quyết định động các sub-agent cần gọi. -## Giao Thức Ngữ Cảnh Mô Hình (MCP) - [Module 05](../05-mcp/README.md) +## Giao thức Ngữ cảnh Mô hình (MCP) - [Module 05](../05-mcp/README.md) -**langchain4j-mcp** - Phụ thuộc Maven cho tích hợp MCP trong LangChain4j. +**langchain4j-mcp** - Định nghĩa Maven cho tích hợp MCP trong LangChain4j. -**MCP** - Giao thức Ngữ Cảnh Mô Hình: chuẩn kết nối ứng dụng AI với công cụ bên ngoài. Xây một lần, dùng khắp nơi. +**MCP** - Model Context Protocol: chuẩn kết nối ứng dụng AI với công cụ bên ngoài. Viết một lần, dùng khắp nơi. -**MCP Client** - Ứng dụng kết nối tới máy chủ MCP để phát hiện và sử dụng công cụ. +**MCP Client** - Ứng dụng kết nối tới MCP server để khám phá và sử dụng công cụ. -**MCP Server** - Dịch vụ công khai công cụ qua MCP với mô tả rõ ràng và schema tham số. +**MCP Server** - Dịch vụ phơi bày công cụ qua MCP với mô tả rõ ràng và schema tham số. -**McpToolProvider** - Thành phần LangChain4j bao gói công cụ MCP dùng trong dịch vụ AI và agent. +**McpToolProvider** - Thành phần LangChain4j đóng gói công cụ MCP dùng trong dịch vụ AI và agent. -**McpTransport** - Giao diện truyền thông MCP. Các triển khai gồm Stdio và HTTP. +**McpTransport** - Giao diện giao tiếp MCP. Các triển khai gồm Stdio và HTTP. -**Stdio Transport** - Truyền thông process cục bộ qua stdin/stdout. Hữu ích với truy cập hệ thống file hoặc công cụ dòng lệnh. +**Stdio Transport** - Giao thức truyền tại máy qua stdin/stdout. Dùng cho truy cập hệ thống tập tin hoặc công cụ dòng lệnh. -**StdioMcpTransport** - Triển khai LangChain4j khởi tạo MCP server dưới dạng tiến trình con. +**StdioMcpTransport** - Triển khai LangChain4j khởi tạo MCP server làm tiến trình con. -**Tool Discovery** - Client truy vấn server để lấy danh sách công cụ có mô tả và schema. +**Tool Discovery** - Client truy vấn server về công cụ sẵn có cùng mô tả và schema. -## Dịch Vụ Azure - [Module 01](../01-introduction/README.md) +## Dịch vụ Azure - [Module 01](../01-introduction/README.md) **Azure AI Search** - Dịch vụ tìm kiếm đám mây với khả năng vector. [Module 03](../03-rag/README.md) @@ -202,31 +202,29 @@ Tham khảo nhanh các thuật ngữ và khái niệm được sử dụng trong **Azure OpenAI** - Dịch vụ AI doanh nghiệp của Microsoft. -**Bicep** - Ngôn ngữ hạ tầng dưới dạng mã của Azure. [Hướng dẫn hạ tầng](../01-introduction/infra/README.md) +**Bicep** - Ngôn ngữ hạ tầng dưới dạng mã cho Azure. [Hướng dẫn hạ tầng](../01-introduction/infra/README.md) -**Deployment Name** - Tên triển khai mô hình trong Azure. +**Deployment Name** - Tên triển khai mô hình trên Azure. **GPT-5.2** - Mô hình OpenAI mới nhất với kiểm soát suy luận. [Module 02](../02-prompt-engineering/README.md) -## Kiểm Thử và Phát Triển - [Hướng Dẫn Kiểm Thử](TESTING.md) +## Kiểm thử và Phát triển - [Hướng dẫn kiểm thử](TESTING.md) -**Dev Container** - Môi trường phát triển dưới dạng container. [Cấu hình](../../../.devcontainer/devcontainer.json) +**Dev Container** - Môi trường phát triển đóng gói. [Cấu hình](../../../.devcontainer/devcontainer.json) -**GitHub Models** - Sân chơi mô hình AI miễn phí. [Module 00](../00-quick-start/README.md) +**In-Memory Testing** - Kiểm thử với lưu trữ trong bộ nhớ. -**In-Memory Testing** - Kiểm thử với kho lưu trữ trong bộ nhớ. - -**Integration Testing** - Kiểm thử với hạ tầng thực tế. +**Integration Testing** - Kiểm thử với hạ tầng thật. **Maven** - Công cụ tự động hóa xây dựng Java. -**Mockito** - Thư viện giả lập trong Java. +**Mockito** - Framework tạo mocking trong Java. **Spring Boot** - Framework ứng dụng Java. [Module 01](../01-introduction/README.md) --- -**Tuyên bố miễn trừ trách nhiệm**: -Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc sự không chính xác. Tài liệu gốc bằng ngôn ngữ ban đầu nên được coi là nguồn tham khảo chính thức. Đối với thông tin quan trọng, khuyến nghị sử dụng dịch vụ dịch thuật chuyên nghiệp do con người thực hiện. Chúng tôi không chịu trách nhiệm về bất kỳ sự hiểu lầm hay giải thích sai nào phát sinh từ việc sử dụng bản dịch này. +**Tuyên bố miễn trừ trách nhiệm**: +Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ gốc nên được coi là nguồn tin chính thức. Đối với thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm về bất kỳ hiểu lầm hoặc giải thích sai nào phát sinh từ việc sử dụng bản dịch này. \ No newline at end of file diff --git a/translations/vi/docs/TESTING.md b/translations/vi/docs/TESTING.md index 2720082b9..fdac717cb 100644 --- a/translations/vi/docs/TESTING.md +++ b/translations/vi/docs/TESTING.md @@ -2,19 +2,19 @@ ## Mục Lục -- [Bắt đầu Nhanh](../../../docs) -- [Nội dung Kiểm thử](../../../docs) -- [Chạy Các Kiểm thử](../../../docs) -- [Chạy Kiểm thử trong VS Code](../../../docs) -- [Mẫu Kiểm thử](../../../docs) -- [Triết lý Kiểm thử](../../../docs) -- [Bước Tiếp theo](../../../docs) +- [Bắt đầu nhanh](#bắt-đầu-nhanh) +- [Những gì kiểm thử bao quát](#những-gì-kiểm-thử-bao-quát) +- [Chạy các bài kiểm thử](#chạy-các-bài-kiểm-thử) +- [Chạy kiểm thử trong VS Code](#chạy-kiểm-thử-trong-vs-code) +- [Mẫu kiểm thử](#mẫu-kiểm-thử) +- [Triết lý kiểm thử](#triết-lý-kiểm-thử) +- [Bước tiếp theo](#bước-tiếp-theo) -Hướng dẫn này giúp bạn hiểu các kiểm thử minh họa cách kiểm thử ứng dụng AI mà không cần khóa API hoặc dịch vụ bên ngoài. +Hướng dẫn này sẽ giúp bạn thực hiện các bài kiểm thử minh họa cách kiểm thử các ứng dụng AI mà không cần khóa API hay dịch vụ bên ngoài. -## Bắt đầu Nhanh +## Bắt đầu nhanh -Chạy tất cả các kiểm thử chỉ với một lệnh: +Chạy tất cả các bài kiểm thử bằng một lệnh duy nhất: **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -Khi tất cả các kiểm thử đều thành công, bạn sẽ thấy kết quả giống ảnh chụp màn hình dưới đây — các kiểm thử chạy với không có lỗi nào. +Khi tất cả các bài kiểm thử đều thành công, bạn sẽ thấy đầu ra như trong ảnh chụp màn hình bên dưới — các bài kiểm thử chạy không lỗi nào. Successful Test Results -*Thực thi kiểm thử thành công hiển thị tất cả các kiểm thử đều đạt* +*Chạy kiểm thử thành công với tất cả các bài kiểm thử vượt qua không lỗi* -## Nội dung Kiểm thử +## Những gì kiểm thử bao quát -Khóa học này tập trung vào **kiểm thử đơn vị** chạy tại chỗ. Mỗi kiểm thử minh họa một khái niệm LangChain4j riêng biệt. Kim tự tháp kiểm thử bên dưới cho thấy vị trí của kiểm thử đơn vị — chúng tạo thành nền tảng nhanh chóng và đáng tin cậy để xây dựng chiến lược kiểm thử của bạn. +Khóa học này tập trung vào **kiểm thử đơn vị** chạy tại máy cục bộ. Mỗi bài kiểm thử minh họa một khái niệm cụ thể của LangChain4j một cách riêng biệt. Kim tự tháp kiểm thử dưới đây cho thấy vị trí của kiểm thử đơn vị — chúng tạo thành nền tảng nhanh và đáng tin cậy mà chiến lược kiểm thử tổng thể của bạn dựa vào. Testing Pyramid -*Kim tự tháp kiểm thử biểu thị sự cân bằng giữa kiểm thử đơn vị (nhanh, tách biệt), kiểm thử tích hợp (các thành phần thực) và kiểm thử đầu-cuối. Khóa học này bao gồm kiểm thử đơn vị.* +*Kim tự tháp kiểm thử cho thấy sự cân bằng giữa kiểm thử đơn vị (nhanh, tách biệt), kiểm thử tích hợp (thành phần thực), và kiểm thử end-to-end. Khóa học này chỉ đề cập tới kiểm thử đơn vị.* -| Module | Các Kiểm Thử | Trọng Tâm | Tập Tin Chính | -|--------|--------------|-----------|---------------| -| **00 - Bắt đầu Nhanh** | 6 | Mẫu prompt và thay thế biến | `SimpleQuickStartTest.java` | -| **01 - Giới thiệu** | 8 | Bộ nhớ hội thoại và trạng thái chat | `SimpleConversationTest.java` | -| **02 - Kỹ thuật Prompt** | 12 | Mẫu GPT-5.2, mức độ háo hức, đầu ra có cấu trúc | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | Nhập văn bản, embeddings, tìm kiếm tương đồng | `DocumentServiceTest.java` | -| **04 - Công Cụ** | 12 | Gọi hàm và xâu chuỗi công cụ | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | Model Context Protocol với giao tiếp Stdio | `SimpleMcpTest.java` | +| Module | Kiểm thử | Trọng tâm | Tệp chính | +|--------|----------|-----------|-----------| +| **01 - Giới thiệu** | 8 | Bộ nhớ hội thoại và chat trạng thái | `SimpleConversationTest.java` | +| **02 - Thiết kế Prompt** | 12 | Mẫu GPT-5.2, các mức hăm hở, đầu ra có cấu trúc | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | Tiêu thụ tài liệu, embeddings, tìm kiếm tương đồng | `DocumentServiceTest.java` | +| **04 - Công cụ** | 12 | Gọi hàm và nối chuỗi công cụ | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | Model Context Protocol với giao thức Stdio | `SimpleMcpTest.java` | -## Chạy Các Kiểm thử +## Chạy các bài kiểm thử -**Chạy tất cả kiểm thử từ thư mục gốc:** +**Chạy tất cả các bài kiểm thử từ thư mục gốc:** **Bash:** ```bash @@ -95,41 +94,41 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#nên duy trì lịch sử cuộc trò chuyện +mvn test -Dtest=SimpleConversationTest#nênDuyTrìLịchSửCuộcTròChuyện ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#nênDuyTrìLịchSửCuộcTròChuyện +mvn --% test -Dtest=SimpleConversationTest#nênDuyTrìLịchSửCuộcHộiThoại ``` ## Chạy Kiểm thử trong VS Code -Nếu bạn sử dụng Visual Studio Code, Test Explorer cung cấp giao diện đồ họa để chạy và gỡ lỗi các kiểm thử. +Nếu bạn sử dụng Visual Studio Code, Test Explorer cung cấp giao diện đồ họa để chạy và gỡ lỗi các bài kiểm thử. VS Code Test Explorer -*Test Explorer của VS Code hiển thị cây kiểm thử với tất cả các lớp kiểm thử Java và các phương thức kiểm thử riêng lẻ* +*VS Code Test Explorer hiển thị cây kiểm thử với tất cả các lớp kiểm thử Java và các phương thức kiểm thử riêng biệt* **Để chạy kiểm thử trong VS Code:** -1. Mở Test Explorer bằng cách nhấp vào biểu tượng bình thử nghiệm ở Thanh Hoạt động -2. Mở rộng cây kiểm thử để xem tất cả các module và lớp kiểm thử -3. Nhấp nút chạy bên cạnh bất kỳ kiểm thử nào để chạy riêng -4. Nhấp "Run All Tests" để thực thi toàn bộ bộ kiểm thử -5. Nhấp chuột phải lên kiểm thử và chọn "Debug Test" để thiết lập điểm dừng và bước qua mã +1. Mở Test Explorer bằng cách nhấn vào biểu tượng cốc thử nghiệm trên thanh Activity Bar +2. Mở rộng cây kiểm thử để xem tất cả các module và các lớp kiểm thử +3. Nhấn nút phát bên cạnh bất kỳ bài kiểm thử nào để chạy riêng bài đó +4. Nhấp "Run All Tests" để chạy toàn bộ bộ kiểm thử +5. Nhấp chuột phải vào bất kỳ bài kiểm thử nào và chọn "Debug Test" để đặt breakpoint và bước qua mã -Test Explorer hiển thị dấu tích màu xanh khi kiểm thử thành công và cung cấp thông báo lỗi chi tiết khi kiểm thử thất bại. +Test Explorer hiển thị dấu tích xanh cho các bài kiểm thử thành công và cung cấp thông báo lỗi chi tiết nếu kiểm thử thất bại. -## Mẫu Kiểm thử +## Mẫu kiểm thử ### Mẫu 1: Kiểm thử Mẫu Prompt -Mẫu đơn giản nhất kiểm thử các mẫu prompt mà không gọi mô hình AI. Bạn kiểm tra rằng thay thế biến hoạt động chính xác và prompt được định dạng như mong đợi. +Mẫu đơn giản nhất kiểm thử các mẫu prompt mà không gọi bất kỳ mô hình AI nào. Bạn sẽ kiểm tra sự thay thế biến hoạt động đúng và prompt được định dạng như mong đợi. Prompt Template Testing -*Kiểm thử mẫu prompt hiển thị luồng thay thế biến: mẫu với các chỗ giữ chỗ → áp dụng giá trị → xác nhận đầu ra đã định dạng* +*Kiểm thử mẫu prompt thể hiện luồng thay thế biến: mẫu với chỗ giữ chỗ → áp dụng giá trị → kiểm tra đầu ra được định dạng* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -Kiểm thử này nằm trong `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`. - -**Chạy nó:** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#định dạngMẫuCâuHỏiKiểmTra -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#kiểm traĐịnhDạngMẫuCâuLệnh -``` +Mẫu này xác nhận rằng thay thế biến hoạt động chính xác và prompt được định dạng theo mong muốn — không cần khóa API hay gọi mô hình. ### Mẫu 2: Giả lập Mô hình Ngôn ngữ -Khi kiểm thử logic hội thoại, dùng Mockito để tạo mô hình giả trả về phản hồi đã định trước. Điều này làm cho kiểm thử nhanh, miễn phí và xác định được kết quả. +Khi kiểm thử logic hội thoại, dùng Mockito để tạo mô hình giả trả về phản hồi đã định trước. Điều này khiến kiểm thử nhanh, miễn phí, và xác định được kết quả. Mock vs Real API Comparison -*So sánh cho thấy vì sao mocks được ưa thích trong kiểm thử: nhanh, miễn phí, xác định, không cần khóa API* +*So sánh lý do tại sao mô phỏng được ưu tiên để kiểm thử: nhanh, miễn phí, xác định, không cần khóa API* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -Mẫu này xuất hiện trong `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mô hình giả đảm bảo hành vi nhất quán để bạn có thể xác nhận quản lý bộ nhớ hoạt động đúng. +Mẫu này xuất hiện trong `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`. Mô hình giả giúp đảm bảo hành vi nhất quán để bạn có thể xác minh việc quản lý bộ nhớ hoạt động đúng. ### Mẫu 3: Kiểm thử Tách biệt Hội thoại -Bộ nhớ hội thoại phải giữ các người dùng riêng biệt. Kiểm thử này xác nhận rằng không có sự trộn lẫn ngữ cảnh giữa các hội thoại. +Bộ nhớ hội thoại cần giữ các người dùng riêng biệt. Bài kiểm thử này xác nhận rằng các hội thoại không bị trộn lẫn bối cảnh. Conversation Isolation -*Kiểm thử tách biệt hội thoại cho thấy bộ nhớ lưu trữ riêng của từng người dùng để tránh trộn lẫn ngữ cảnh* +*Kiểm thử tách biệt hội thoại thể hiện các bộ nhớ riêng cho từng người dùng để tránh trộn bối cảnh* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -Mỗi hội thoại duy trì lịch sử độc lập riêng. Trong hệ thống sản xuất, tách biệt này rất quan trọng cho các ứng dụng đa người dùng. +Mỗi hội thoại duy trì lịch sử riêng biệt. Trong hệ thống sản xuất, tách biệt này rất quan trọng cho các ứng dụng đa người dùng. -### Mẫu 4: Kiểm thử Công Cụ Riêng biệt +### Mẫu 4: Kiểm thử Công cụ Độc lập -Công cụ là các hàm mà AI có thể gọi. Kiểm thử trực tiếp để đảm bảo chúng hoạt động đúng bất kể quyết định của AI. +Công cụ là các hàm AI có thể gọi. Kiểm thử chúng trực tiếp để đảm bảo chúng hoạt động chính xác bất kể quyết định của AI. Tools Testing -*Kiểm thử công cụ độc lập cho thấy thực thi công cụ giả mà không gọi AI để xác nhận logic nghiệp vụ* +*Kiểm thử công cụ độc lập hiển thị việc giả lập chạy công cụ mà không cần gọi AI để kiểm tra logic nghiệp vụ* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -Các kiểm thử này từ `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` xác nhận logic công cụ mà không liên quan AI. Ví dụ xâu chuỗi cho thấy đầu ra của một công cụ được đưa làm đầu vào cho công cụ khác. +Các kiểm thử này từ `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java` xác nhận logic công cụ không phụ thuộc vào AI. Ví dụ nối chuỗi cho thấy đầu ra của công cụ này làm đầu vào cho công cụ khác. -### Mẫu 5: Kiểm thử RAG Tại Bộ Nhớ Trong +### Mẫu 5: Kiểm thử RAG trong Bộ nhớ -Hệ thống RAG truyền thống yêu cầu cơ sở dữ liệu vector và dịch vụ embedding. Mẫu tại bộ nhớ trong cho phép bạn kiểm thử toàn bộ quy trình mà không cần phụ thuộc bên ngoài. +Hệ thống RAG truyền thống cần cơ sở dữ liệu vector và dịch vụ embedding. Mẫu bộ nhớ cho phép kiểm thử toàn bộ quy trình mà không phụ thuộc bên ngoài. In-Memory RAG Testing -*Quy trình kiểm thử RAG trong bộ nhớ cho thấy phân tích tài liệu, lưu trữ embedding và tìm kiếm tương đồng mà không cần cơ sở dữ liệu* +*Quy trình kiểm thử RAG trong bộ nhớ thể hiện phân tích tài liệu, lưu trữ embedding, và tìm kiếm tương đồng mà không cần cơ sở dữ liệu* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -Kiểm thử này ở `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` tạo tài liệu trong bộ nhớ và xác nhận việc chia nhỏ và xử lý metadata. +Kiểm thử này từ `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java` tạo một tài liệu trong bộ nhớ và xác nhận phân mảnh cũng như xử lý siêu dữ liệu. ### Mẫu 6: Kiểm thử Tích hợp MCP -Module MCP kiểm thử tích hợp Model Context Protocol sử dụng giao tiếp stdio. Các kiểm thử này xác nhận ứng dụng của bạn có thể sinh và giao tiếp với các máy chủ MCP dưới dạng tiến trình phụ. +Module MCP kiểm thử tích hợp Model Context Protocol sử dụng giao thức stdio. Các bài kiểm thử xác nhận ứng dụng của bạn có thể khởi tạo và giao tiếp với máy chủ MCP như tiến trình con. -Các kiểm thử trong `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` xác nhận hành vi client MCP. +Kiểm thử trong `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` xác thực hành vi của client MCP. **Chạy chúng:** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## Triết lý Kiểm thử -Kiểm thử mã của bạn, không phải AI. Các kiểm thử nên xác nhận mã bạn viết bằng cách kiểm tra cách xây dựng prompt, cách quản lý bộ nhớ, và cách công cụ thực thi. Phản hồi AI thay đổi và không nên là một phần của các khẳng định kiểm thử. Hãy tự hỏi mẫu prompt của bạn có thay thế biến đúng không, chứ không phải AI có đưa ra câu trả lời đúng hay không. +Hãy kiểm thử code của bạn, không phải AI. Các bài kiểm thử nên xác minh code bạn viết bằng cách kiểm tra cách prompt được xây dựng, cách quản lý bộ nhớ và cách các công cụ thực thi. Phản hồi AI biến đổi và không nên là một phần của các khẳng định kiểm thử. Hãy hỏi bản thân liệu mẫu prompt đã thay thế biến đúng chưa, chứ không phải AI trả lời đúng hay sai. -Sử dụng giả lập cho các mô hình ngôn ngữ. Chúng là phụ thuộc bên ngoài chậm chạp, đắt đỏ và không xác định được kết quả. Giả lập làm kiểm thử nhanh với mili giây thay vì giây, miễn phí không tốn phí API, và xác định được cùng một kết quả mỗi lần. +Dùng mô phỏng cho các mô hình ngôn ngữ. Chúng là các phụ thuộc bên ngoài chậm, tốn kém và không xác định. Mô phỏng giúp các bài kiểm thử nhanh với mili-giây thay vì giây, miễn phí không mất chi phí API, và xác định với kết quả giống nhau mỗi lần. -Giữ cho kiểm thử độc lập. Mỗi kiểm thử nên tự thiết lập dữ liệu riêng, không phụ thuộc kiểm thử khác, và dọn dẹp sau khi chạy. Kiểm thử nên thành công bất kể thứ tự chạy như thế nào. +Giữ các bài kiểm thử độc lập. Mỗi bài kiểm thử nên tự thiết lập dữ liệu của nó, không phụ thuộc vào các bài kiểm thử khác, và dọn dẹp sau khi chạy. Kiểm thử nên thành công bất kể thứ tự thực hiện. -Kiểm thử các trường hợp biên bên cạnh đường đi thuận lợi. Thử đầu vào rỗng, đầu vào rất lớn, ký tự đặc biệt, tham số không hợp lệ, và điều kiện biên. Những trường hợp này thường phát hiện lỗi mà sử dụng bình thường không thấy. +Kiểm thử các trường hợp biên ngoài đường đi thuận lợi. Thử đầu vào trống, đầu vào rất lớn, ký tự đặc biệt, tham số không hợp lệ, và các điều kiện biên. Thường thì những trường hợp này tiết lộ lỗi mà sử dụng thông thường không phát hiện. -Dùng tên mô tả. So sánh `shouldMaintainConversationHistoryAcrossMultipleMessages()` với `test1()`. Cái đầu tiên cho bạn biết chính xác điều gì đang được kiểm thử, giúp gỡ lỗi dễ dàng hơn nhiều. +Dùng tên mô tả. So sánh `shouldMaintainConversationHistoryAcrossMultipleMessages()` với `test1()`. Cái đầu tiên nói rõ chính xác điều gì đang được kiểm thử, giúp gỡ lỗi khi thất bại dễ dàng hơn nhiều. -## Bước Tiếp theo +## Bước tiếp theo -Bây giờ bạn đã hiểu các mẫu kiểm thử, hãy đi sâu hơn vào từng module: +Bây giờ khi bạn đã hiểu các mẫu kiểm thử, hãy đi sâu hơn vào từng module: -- **[00 - Bắt đầu Nhanh](../00-quick-start/README.md)** - Bắt đầu với kiến thức cơ bản về mẫu prompt - **[01 - Giới thiệu](../01-introduction/README.md)** - Tìm hiểu quản lý bộ nhớ hội thoại -- **[02 - Kỹ thuật Prompt](../02-prompt-engineering/README.md)** - Làm chủ các mẫu prompt GPT-5.2 -- **[03 - RAG](../03-rag/README.md)** - Xây dựng hệ thống tạo nội dung tăng cường truy xuất -- **[04 - Công Cụ](../04-tools/README.md)** - Triển khai gọi hàm và xâu chuỗi công cụ +- **[02 - Thiết kế Prompt](../02/prompt-engineering/README.md)** - Thành thạo mẫu prompt GPT-5.2 +- **[03 - RAG](../03-rag/README.md)** - Xây dựng hệ thống tạo văn bản tăng cường truy xuất +- **[04 - Công cụ](../04-tools/README.md)** - Thực hiện gọi hàm và chuỗi công cụ - **[05 - MCP](../05-mcp/README.md)** - Tích hợp Model Context Protocol -README của từng module cung cấp giải thích chi tiết các khái niệm kiểm thử tại đây. +README của từng module cung cấp giải thích chi tiết về các khái niệm được kiểm thử ở đây. --- -**Điều hướng:** [← Quay lại Chính](../README.md) +**Điều hướng:** [← Quay lại Trang Chính](../README.md) --- -**Tuyên bố từ chối trách nhiệm**: -Tài liệu này đã được dịch sử dụng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng các bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ mẹ đẻ được coi là nguồn chính thức và có thẩm quyền. Đối với các thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp do con người thực hiện. Chúng tôi không chịu trách nhiệm đối với bất kỳ sự hiểu lầm hoặc giải thích sai nào phát sinh từ việc sử dụng bản dịch này. +**Tuyên bố miễn trừ trách nhiệm**: +Tài liệu này đã được dịch bằng dịch vụ dịch thuật AI [Co-op Translator](https://github.com/Azure/co-op-translator). Mặc dù chúng tôi cố gắng đảm bảo độ chính xác, xin lưu ý rằng bản dịch tự động có thể chứa lỗi hoặc sai sót. Tài liệu gốc bằng ngôn ngữ gốc nên được coi là nguồn tin chính thức. Đối với thông tin quan trọng, nên sử dụng dịch vụ dịch thuật chuyên nghiệp bởi con người. Chúng tôi không chịu trách nhiệm về bất kỳ hiểu lầm hoặc giải thích sai nào phát sinh từ việc sử dụng bản dịch này. \ No newline at end of file diff --git a/translations/zh-CN/.co-op-translator.json b/translations/zh-CN/.co-op-translator.json index eca4f9fe8..40a2ba382 100644 --- a/translations/zh-CN/.co-op-translator.json +++ b/translations/zh-CN/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "zh-CN" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T22:44:59+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T07:31:17+00:00", "source_file": "01-introduction/README.md", "language_code": "zh-CN" }, @@ -18,20 +18,20 @@ "language_code": "zh-CN" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T22:46:44+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T07:27:47+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "zh-CN" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T22:47:57+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T07:30:31+00:00", "source_file": "03-rag/README.md", "language_code": "zh-CN" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T12:28:33+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T07:29:29+00:00", "source_file": "04-tools/README.md", "language_code": "zh-CN" }, @@ -54,8 +54,8 @@ "language_code": "zh-CN" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:36:16+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T07:26:49+00:00", "source_file": "README.md", "language_code": "zh-CN" }, @@ -72,14 +72,14 @@ "language_code": "zh-CN" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T22:50:36+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T07:28:08+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "zh-CN" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T22:51:13+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T07:28:36+00:00", "source_file": "docs/TESTING.md", "language_code": "zh-CN" } diff --git a/translations/zh-CN/00-quick-start/README.md b/translations/zh-CN/00-quick-start/README.md deleted file mode 100644 index 822498349..000000000 --- a/translations/zh-CN/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: 快速开始 - -## 目录 - -- [介绍](../../../00-quick-start) -- [什么是 LangChain4j？](../../../00-quick-start) -- [LangChain4j 依赖](../../../00-quick-start) -- [前提条件](../../../00-quick-start) -- [设置](../../../00-quick-start) - - [1. 获取你的 GitHub 令牌](../../../00-quick-start) - - [2. 设置你的令牌](../../../00-quick-start) -- [运行示例](../../../00-quick-start) - - [1. 基础聊天](../../../00-quick-start) - - [2. 提示模式](../../../00-quick-start) - - [3. 函数调用](../../../00-quick-start) - - [4. 文档问答（简单 RAG）](../../../00-quick-start) - - [5. 负责任的 AI](../../../00-quick-start) -- [每个示例展示内容](../../../00-quick-start) -- [下一步](../../../00-quick-start) -- [故障排除](../../../00-quick-start) - -## 介绍 - -此快速入门旨在帮助你尽快使用 LangChain4j 启动运行。它涵盖了使用 LangChain4j 和 GitHub 模型构建 AI 应用程序的基础知识。在接下来的模块中，你将切换到 Azure OpenAI 和 GPT-5.2，深入探索每个概念。 - -## 什么是 LangChain4j？ - -LangChain4j 是一个简化构建 AI 驱动应用程序的 Java 库。你无需处理 HTTP 客户端和 JSON 解析，而是使用干净的 Java API。 - -LangChain 中的“链”指的是将多个组件串联起来——你可能将一个提示连接到模型，再连接到解析器，或者将多个 AI 调用串联起来，一个输出作为下一个输入。此快速开始侧重于基础知识，随后再探讨更复杂的链。 - -LangChain4j Chaining Concept - -*在 LangChain4j 中串联组件——通过构建模块连接创建强大的 AI 工作流* - -我们将使用三个核心组件： - -**ChatModel** — 用于与 AI 模型交互的接口。调用 `model.chat("prompt")` 得到响应字符串。我们使用 `OpenAiOfficialChatModel`，它支持与 OpenAI 兼容的端点，如 GitHub 模型。 - -**AiServices** — 创建类型安全的 AI 服务接口。定义方法，用 `@Tool` 注解它们，LangChain4j 负责协调。AI 会在需要时自动调用你的 Java 方法。 - -**MessageWindowChatMemory** — 维护对话历史。没有它，每个请求都是独立的。使用它后，AI 会记住之前的消息，并在多轮对话中保持上下文。 - -LangChain4j Architecture - -*LangChain4j 架构——核心组件协同工作，为你的 AI 应用提供动力* - -## LangChain4j 依赖 - -此快速入门在 [`pom.xml`](../../../00-quick-start/pom.xml) 中使用三个 Maven 依赖： - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` 模块提供了连接 OpenAI 兼容 API 的 `OpenAiOfficialChatModel` 类。GitHub 模型使用相同的 API 格式，因此不需要特殊适配器——只需将基础 URL 指向 `https://models.github.ai/inference`。 - -`langchain4j-easy-rag` 模块提供自动文档拆分、嵌入和检索，方便你构建 RAG 应用，无需手动配置每个步骤。 - -## 前提条件 - -**使用开发容器？** Java 和 Maven 已预装。你只需要一个 GitHub 个人访问令牌。 - -**本地开发：** -- Java 21+，Maven 3.9+ -- GitHub 个人访问令牌（见下方说明） - -> **注意：** 本模块使用 GitHub 模型中的 `gpt-4.1-nano`。请勿修改代码中的模型名称——它已配置为与 GitHub 提供的模型兼容。 - -## 设置 - -### 1. 获取你的 GitHub 令牌 - -1. 前往 [GitHub 设置 → 个人访问令牌](https://github.com/settings/personal-access-tokens) -2. 点击“生成新令牌” -3. 设置描述性名称（例如 “LangChain4j Demo”） -4. 设置过期时间（建议7天） -5. 在“账户权限”下，找到“Models”，设置为“只读” -6. 点击“生成令牌” -7. 复制并保存令牌——你将无法再次看到它 - -### 2. 设置你的令牌 - -**选项 1：使用 VS Code（推荐）** - -如果你使用 VS Code，将令牌添加到项目根目录的 `.env` 文件中： - -如果 `.env` 文件不存在，请复制 `.env.example` 为 `.env`，或在根目录创建新 `.env` 文件。 - -**示例 `.env` 文件：** -```bash -# 在 /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -然后你可以在资源管理器中右键点击任意示例文件（如 `BasicChatDemo.java`）并选择 **“Run Java”**，或者使用运行与调试面板的启动配置。 - -**选项 2：使用终端** - -将令牌设置为环境变量： - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## 运行示例 - -**使用 VS Code：** 只需在资源管理器中右键点击任意示例文件，并选择 **“Run Java”**，或者使用运行与调试面板的启动配置（确保已先添加令牌到 `.env` 文件）。 - -**使用 Maven：** 你也可以从命令行运行： - -### 1. 基础聊天 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. 提示模式 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -展示零样本、少样本、思维链和角色扮演提示。 - -### 3. 函数调用 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI 会在需要时自动调用你的 Java 方法。 - -### 4. 文档问答（简单 RAG） - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -使用 Easy RAG 自动嵌入和检索，根据你的文档提问。 - -### 5. 负责任的 AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -观察 AI 安全过滤器如何阻止有害内容。 - -## 每个示例展示内容 - -**基础聊天** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -从这里开始，了解 LangChain4j 的最简单用法。你将创建一个 `OpenAiOfficialChatModel`，用 `.chat()` 发送提示，并获得回复。这演示了基础：如何用自定义端点和 API 密钥初始化模型。理解这个模式后，所有其它内容都基于它。 - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 试试用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) 并提问： -> - “如何在这段代码中将 GitHub 模型切换到 Azure OpenAI？” -> - “OpenAiOfficialChatModel.builder() 还能配置哪些参数？” -> - “如何添加流式响应，而不是等待完整回复？” - -**提示工程** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -既然你知道如何与模型交互，让我们看看你说什么给它听。此示例使用相同模型设置，但展示五种不同提示模式。尝试零样本提示直接指令，少样本提示从示例学习，思维链提示展现推理步骤，角色提示设定上下文。你会看到相同模型依据请求方式产生截然不同的结果。 - -示例还展示了提示模板，这是一种强大的方法，用变量创建可重用提示。 -以下示例展示使用 LangChain4j `PromptTemplate` 填充变量。AI 会根据指定目的地和活动作答。 - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 试试用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) 并提问： -> - “零样本与少样本提示有什么区别，何时使用？” -> - “温度参数如何影响模型的回答？” -> - “生产环境中有哪些防止提示注入攻击的技巧？” -> - “如何为常见模式创建可重用的 PromptTemplate 对象？” - -**工具集成** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -这是 LangChain4j 展示强大功能的地方。你将使用 `AiServices` 创建一个 AI 助手，它可以调用你的 Java 方法。只需用 `@Tool("说明")` 注解方法，LangChain4j 会处理其余部分——AI 会根据用户请求自动决定何时使用哪个工具。这展示了函数调用，这是构建能执行操作的 AI 的关键技术，而不仅仅是回答问题。 - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 试试用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) 并提问： -> - “@Tool 注解如何工作，LangChain4j 在幕后做了什么？” -> - “AI 能否顺序调用多个工具以解决复杂问题？” -> - “如果工具抛出异常，应该如何处理错误？” -> - “如何集成真实 API，而不是这个计算器示例？” - -**文档问答（简单 RAG）** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -这里你将看到使用 LangChain4j “简单 RAG” 的检索增强生成。文档被加载，自动拆分并嵌入到内存存储中，然后内容检索器在查询时为 AI 提供相关片段。AI 根据你的文档作答，而非其通用知识。 - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 试试用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) 并提问： -> - “与只用模型训练数据相比，RAG 如何防止 AI 幻觉？” -> - “这种简单方法与自定义 RAG 流程有何不同？” -> - “如何扩展以支持多文档或更大知识库？” - -**负责任的 AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -构建层层防御的 AI 安全。此示例展示两层保护协同工作： - -**第一部分：LangChain4j 输入保护措施** — 在请求到达大语言模型前阻止危险提示。创建自定义保护措施，检测被禁关键词或模式。这些在你的代码中运行，快速且免费。 - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**第二部分：提供商安全过滤** — GitHub 模型内置过滤，拦截保护措施可能遗漏的内容。你将看到严重违规的硬阻断（HTTP 400 错误）和 AI 礼貌拒绝的软拒绝。 - -> **🤖 试试用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) 并提问： -> - “什么是 InputGuardrail，我如何创建自己的？” -> - “硬阻断和软拒绝有什么区别？” -> - “为什么要同时使用保护措施和提供商过滤？” - -## 下一步 - -**下一模块：** [01-介绍 - LangChain4j 入门](../01-introduction/README.md) - ---- - -**导航：** [← 返回主页](../README.md) | [下一页：模块 01 - 介绍 →](../01-introduction/README.md) - ---- - -## 故障排除 - -### 第一次 Maven 构建 - -**问题：** 初次运行 `mvn clean compile` 或 `mvn package` 很慢（10-15 分钟） - -**原因：** Maven 第一次构建时需要下载所有项目依赖（Spring Boot、LangChain4j 库、Azure SDK 等）。 - -**解决方案：** 这是正常现象。后续构建将更快，因为依赖已本地缓存。下载速度取决于你的网络状况。 - -### PowerShell 中的 Maven 命令语法 - -**问题：** Maven 命令失败，报错 `Unknown lifecycle phase ".mainClass=..."` -**原因**：PowerShell 将 `=` 解释为变量赋值操作符，破坏了 Maven 属性语法 - -**解决方案**：在 Maven 命令前使用停止解析操作符 `--%`： - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` 操作符告诉 PowerShell 以字面形式将所有剩余参数传递给 Maven，而不进行解释。 - -### Windows PowerShell 表情符号显示 - -**问题**：在 PowerShell 中，AI 响应显示乱码（例如 `????` 或 `â??`）而不是表情符号 - -**原因**：PowerShell 默认编码不支持 UTF-8 表情符号 - -**解决方案**：在执行 Java 应用程序前运行此命令： -```cmd -chcp 65001 -``` - -这会强制终端使用 UTF-8 编码。或者使用支持更好 Unicode 的 Windows Terminal。 - -### 调试 API 调用 - -**问题**：AI 模型出现身份验证错误、速率限制或意外响应 - -**解决方案**：示例中包含 `.logRequests(true)` 和 `.logResponses(true)`，用于在控制台显示 API 调用。这有助于排查身份验证错误、速率限制或意外响应。在生产环境中移除这些标志以减少日志噪音。 - ---- - - -**免责声明**： -本文件由AI翻译服务【Co-op Translator】（https://github.com/Azure/co-op-translator）翻译而成。虽然我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。原始语言的文档应被视为权威来源。对于重要信息，建议使用专业人工翻译。我们不对因使用本翻译而产生的任何误解或误释承担责任。 - \ No newline at end of file diff --git a/translations/zh-CN/01-introduction/README.md b/translations/zh-CN/01-introduction/README.md index 49b766954..ab8ff1f98 100644 --- a/translations/zh-CN/01-introduction/README.md +++ b/translations/zh-CN/01-introduction/README.md @@ -1,77 +1,77 @@ -# Module 01: 开始使用 LangChain4j +# 模块 01：开始使用 LangChain4j ## 目录 -- [视频演练](../../../01-introduction) -- [你将学到什么](../../../01-introduction) -- [先决条件](../../../01-introduction) -- [理解核心问题](../../../01-introduction) -- [理解 Tokens](../../../01-introduction) -- [内存如何工作](../../../01-introduction) -- [本模块如何使用 LangChain4j](../../../01-introduction) -- [部署 Azure OpenAI 基础设施](../../../01-introduction) -- [本地运行应用](../../../01-introduction) -- [使用应用](../../../01-introduction) - - [无状态聊天（左侧面板）](../../../01-introduction) - - [有状态聊天（右侧面板）](../../../01-introduction) -- [下一步](../../../01-introduction) +- [视频演练](#视频演练) +- [你将学到什么](#你将学到什么) +- [先决条件](#先决条件) +- [理解核心问题](#理解核心问题) +- [理解 Tokens](#理解-tokens) +- [内存是如何工作的](#内存是如何工作的) +- [本模块如何使用 LangChain4j](#本模块如何使用-langchain4j) +- [部署 Azure OpenAI 基础设施](#部署-azure-openai-基础设施) +- [本地运行应用](#本地运行应用) +- [使用应用](#使用应用) + - [无状态聊天（左侧面板）](#无状态聊天（左侧面板）) + - [有状态聊天（右侧面板）](#有状态聊天（右侧面板）) +- [接下来的步骤](#接下来的步骤) ## 视频演练 -观看本直播课程，讲解如何开始使用本模块： +观看这段直播，讲解如何开始使用本模块： Getting Started with LangChain4j - Live Session ## 你将学到什么 -在快速入门中，你使用了 GitHub 模型发送提示、调用工具、构建 RAG 流水线并测试安全保护。这些演示展示了可能性——现在我们转向 Azure OpenAI 和 GPT-5.2，开始构建生产级应用。本模块专注于具有记忆上下文与维护状态能力的会话 AI —— 这是那些快速入门演示背后使用但未解释的概念。 +这是你学习 LangChain4j 和 Azure OpenAI 的起点。我们从基础开始，逐步构建生产级应用。本模块专注于能够记忆上下文并保持状态的对话式 AI —— 这是后续所有模块的基础概念。 -在本指南中我们将始终使用 Azure OpenAI 的 GPT-5.2，因为它的高级推理能力使不同模式的行为更加明显。添加内存后，你会清晰见到差异，这有助于理解各组件为你的应用带来的价值。 +整个指南中，我们将使用 Azure OpenAI 的 GPT-5.2。它先进的推理能力使不同模式的行为更为明显。添加内存后，你将清楚地看到差别，也更容易理解各组件为你的应用带来的价值。 -你将构建一个演示两种模式的应用： +你将构建一个同时演示两种模式的应用： -**无状态聊天** - 每次请求独立。模型不记得之前的消息。这是你在快速入门中使用的模式。 +无状态聊天 — 每次请求独立。模型不记得之前的消息。这是最简单的起点。 -**有状态对话** - 每次请求包含会话历史。模型维护多轮会话上下文。这是生产应用所需。 +有状态对话 — 每次请求包含对话历史。模型跨多轮维持上下文状态。这是生产环境应用所必需的。 ## 先决条件 -- 拥有访问 Azure OpenAI 的 Azure 订阅 -- Java 21，Maven 3.9 及以上版本 +- 拥有可以访问 Azure OpenAI 的 Azure 订阅 +- Java 21，Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **注意：** 提供的开发容器中已预装 Java、Maven、Azure CLI 和 Azure Developer CLI (azd)。 +> **注意：** 提供的开发容器中预装了 Java、Maven、Azure CLI 和 Azure Developer CLI (azd)。 -> **注意：** 本模块使用 Azure OpenAI 上的 GPT-5.2。部署通过 `azd up` 自动配置 - 不要修改代码中的模型名称。 +> **注意：** 本模块使用 Azure OpenAI 上的 GPT-5.2。部署通过 `azd up` 自动配置——请勿修改代码中的模型名称。 ## 理解核心问题 -语言模型是无状态的。每个 API 调用都是独立的。如果你发送“我叫 John”，然后问“我叫什么名字？”，模型不会知道你刚刚介绍过自己。它把每个请求都当作是与你的“第一次对话”。 +语言模型是无状态的。每个 API 调用都是独立的。如果你先发送“我的名字是 John”，然后问“我叫什么名字？”，模型不会知道你刚刚介绍了自己。它把每次请求当作是你第一次对话。 -这对于简单问答可以，但对真正的应用没用。客服机器人需要记住你告诉他们的信息。个人助理需要上下文。任何多轮对话都需要记忆。 +这对于简单的问答还行，但对于实际应用毫无用处。客服机器人需要记住你告诉它的信息。个人助手需要上下文。任何多轮对话都需要内存。 -下图对比了两种方式——左侧是无状态调用，忘记了你的名字；右侧是由 ChatMemory 支持的有状态调用，记住了名字。 +下面的图展示了两种方法对比 —— 左边是无状态调用，它会忘记你的名字；右边是有状态调用，使用 ChatMemory 记住了它。 Stateless vs Stateful Conversations -*无状态（独立调用）和有状态（上下文感知）会话的区别* +*无状态（独立调用）与有状态（上下文感知）对话的区别* ## 理解 Tokens -在深入会话之前，理解 token 很重要——它是语言模型处理的文本基本单位： +在深入对话前，重要的是理解 tokens —— 语言模型处理的基本文本单位： Token Explanation -*文本如何拆分为 tokens 的示例 —— “I love AI!” 被拆成4个独立的处理单元* +*文本如何拆分成 tokens 的示例 —— “I love AI!” 拆成 4 个独立处理单元* -token 是 AI 模型测量和处理文本的方式。单词、标点符号甚至空格都可以是 token。你的模型对一次能处理的 token 数有限制（GPT-5.2 最大400,000个，包括最多272,000输入token和128,000输出token）。理解 token 有助于管理对话长度和成本。 +Tokens 是 AI 模型测量和处理文本的方式。单词、标点符号，甚至空格都可以是 token。你使用的模型有一次能处理的 token 限制（GPT-5.2 为 400,000 个 token，包含最多 272,000 输入和 128,000 输出）。理解 tokens 有助于你管理对话长度和费用。 -## 内存如何工作 +## 内存是如何工作的 -聊天内存通过维护对话历史解决了无状态问题。在将请求发送给模型之前，框架会预先添加相关的前面消息。当你问“我叫什么名字？”时，系统实际上发送了整个对话历史，使模型看到你之前说过“我叫 John”。 +聊天内存通过维护对话历史解决了无状态问题。发送请求给模型前，框架会预先添加相关的历史消息。当你问“我叫什么名字？”，系统实际上发送了整个对话历史，模型就能看到你之前说了“我的名字是 John”。 -LangChain4j 提供了自动处理这部分的内存实现。你可以选择保留多少条消息，框架自动管理上下文窗口。下图展示了 MessageWindowChatMemory 如何维护最近消息的滑动窗口。 +LangChain4j 提供了自动处理内存的实现。你指定保留多少条消息，框架会管理上下文窗口。下图展示了 MessageWindowChatMemory 如何维护最近消息的滑动窗口。 Memory Window Concept @@ -79,9 +79,9 @@ LangChain4j 提供了自动处理这部分的内存实现。你可以选择保 ## 本模块如何使用 LangChain4j -本模块在快速入门基础上集成了 Spring Boot 并添加了对话内存。组件关系如下： +本模块结合 Spring Boot，并添加对话内存。各部分如何协同： -**依赖项** - 添加两个 LangChain4j 库： +依赖 — 添加两个 LangChain4j 库： ```xml @@ -94,7 +94,7 @@ LangChain4j 提供了自动处理这部分的内存实现。你可以选择保 ``` -**聊天模型** - 配置 Azure OpenAI 作为 Spring bean（[LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)）： +聊天模型 — 配置 Azure OpenAI 作为 Spring Bean（[LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)）： ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -构建器从 `azd up` 设置的环境变量读取凭据。将 `baseUrl` 设置为你的 Azure 端点，使 OpenAI 客户端可适配 Azure OpenAI。 +构建器从 `azd up` 设置的环境变量读取凭证。将 `baseUrl` 设为你的 Azure 端点，使 OpenAI 客户端能与 Azure OpenAI 配合使用。 -**会话内存** - 使用 MessageWindowChatMemory 跟踪聊天历史（[ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)）： +对话内存 — 使用 MessageWindowChatMemory 跟踪聊天历史（[ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)）： ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,59 +124,59 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -使用 `withMaxMessages(10)` 创建内存，保留最近10条消息。使用类型包装器 `UserMessage.from(text)` 和 `AiMessage.from(text)` 添加用户和 AI 消息。用 `memory.messages()` 获取历史并发送给模型。服务为每个会话 ID 存储独立的内存实例，支持多个用户同时聊天。 +用 `withMaxMessages(10)` 创建内存，保留最近 10 条消息。通过类型包装器添加用户和 AI 消息：`UserMessage.from(text)` 和 `AiMessage.from(text)`。用 `memory.messages()` 获取历史，并发送给模型。服务为每个会话 ID 存储独立内存实例，支持多个用户同时聊天。 -> **🤖 试试 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) 并询问： -> - “MessageWindowChatMemory 满窗口时如何决定丢弃哪些消息？” -> - “我能用数据库实现自定义内存存储而非内存中存储吗？” -> - “如何添加摘要功能压缩旧对话历史？” +> **🤖 试试用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)，问： +> - “MessageWindowChatMemory 在窗口满时如何决定丢弃哪些消息？” +> - “我可以用数据库代替内存来实现自定义内存存储吗？” +> - “如何添加摘要功能以压缩旧的对话历史？” -无状态聊天接口完全跳过内存 —— 直接调用 `chatModel.chat(prompt)`，如快速入门。状态接口则向内存添加消息，获取历史，并将上下文包含在请求中。模型配置相同，模式不同。 +无状态聊天端点完全跳过内存——只调用 `chatModel.chat(prompt)`，如快速开始一样。有状态端点则添加消息到内存，检索历史，用上下文随着每次请求发送。模型配置相同，模式不同。 ## 部署 Azure OpenAI 基础设施 -**Bash：** +**Bash:** ```bash cd 01-introduction azd up # 选择订阅和位置（推荐 eastus2） ``` -**PowerShell：** +**PowerShell:** ```powershell cd 01-introduction -azd up # 选择订阅和位置（推荐eastus2） +azd up # 选择订阅和位置（推荐 eastus2） ``` -> **注意：** 如果遇到超时错误 (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`)，只需重新运行 `azd up`。Azure 资源可能仍在后台部署，重试能让部署在资源达到终态后完成。 +> **注意：** 如果遇到超时错误（`RequestConflict: Cannot modify resource ... provisioning state is not terminal`），只需再次运行 `azd up`。Azure 资源可能仍在后台创建中，重试可让部署在资源达到终止状态后完成。 -此操作将： -1. 部署带 GPT-5.2 和 text-embedding-3-small 模型的 Azure OpenAI 资源 -2. 自动在项目根目录生成 `.env` 文件，其中包含凭据 +这会： +1. 部署包含 GPT-5.2 和 text-embedding-3-small 模型的 Azure OpenAI 资源 +2. 在项目根目录自动生成带有凭证的 `.env` 文件 3. 设置所有必需的环境变量 -**部署遇到问题？** 请查看 [基础设施 README](infra/README.md) 获得详细故障排查，包括子域名冲突、手动 Azure 门户部署步骤及模型配置指导。 +**部署有问题？** 请查阅 [基础设施 README](infra/README.md)，包含子域名冲突、手动 Azure 门户部署步骤、模型配置指导等详细排查方法。 **验证部署是否成功：** -**Bash：** +**Bash:** ```bash -cat ../.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 +cat ../.env # 应该显示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 ``` -**PowerShell：** +**PowerShell:** ```powershell -Get-Content ..\.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 +Get-Content ..\.env # 应该显示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 ``` -> **注意：** `azd up` 命令会自动生成 `.env` 文件。如果稍后需要更新，你可以编辑 `.env` 文件，或者通过运行以下命令重新生成： +> **注意：** `azd up` 命令会自动生成 `.env` 文件。如需后续更新，可以手动编辑 `.env` 文件，或通过以下命令重新生成： > -> **Bash：** +> **Bash:** > ```bash > cd .. > bash .azd-env.sh > ``` > -> **PowerShell：** +> **PowerShell:** > ```powershell > cd .. > .\.azd-env.ps1 @@ -186,94 +186,94 @@ Get-Content ..\.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 **验证部署：** -确认在根目录有 `.env` 文件并包含 Azure 凭据。在本模块目录（`01-introduction/`）运行： +确认根目录存在带有 Azure 凭证的 `.env` 文件。从模块目录（`01-introduction/`）运行： -**Bash：** +**Bash:** ```bash cat ../.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` -**PowerShell：** +**PowerShell:** ```powershell Get-Content ..\.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` **启动应用：** -**选项1：使用 Spring Boot Dashboard（推荐 VS Code 用户）** +**方案 1：使用 Spring Boot Dashboard（推荐 VS Code 用户）** -开发容器中包含了 Spring Boot Dashboard 扩展，提供可视化界面管理所有 Spring Boot 应用。可在 VS Code 左侧活动栏找到（Spring Boot 图标）。 +开发容器包含 Spring Boot Dashboard 扩展，为所有 Spring Boot 应用提供可视化管理界面。你可以在 VS Code 左侧活动栏找到这个图标（Spring Boot 图标）。 通过 Spring Boot Dashboard，你可以： - 查看工作区中的所有 Spring Boot 应用 - 一键启动/停止应用 - 实时查看应用日志 -- 监视应用状态 +- 监控应用状态 -点击 “introduction” 旁的播放按钮启动本模块，或一次启动所有模块。 +点击 “introduction” 旁的播放按钮启动此模块，或一次启动所有模块。 Spring Boot Dashboard -*VS Code 中的 Spring Boot Dashboard —— 一处启动、停止和监视所有模块* +*VS Code 中的 Spring Boot Dashboard —— 从一个界面启动、停止并监控所有模块* -**选项2：使用 shell 脚本** +**方案 2：使用 shell 脚本** 启动所有 Web 应用（模块 01-04）： -**Bash：** +**Bash:** ```bash cd .. # 从根目录 ./start-all.sh ``` -**PowerShell：** +**PowerShell:** ```powershell -cd .. # 来自根目录 +cd .. # 从根目录 .\start-all.ps1 ``` -或者只启动本模块： +或仅启动本模块： -**Bash：** +**Bash:** ```bash cd 01-introduction ./start.sh ``` -**PowerShell：** +**PowerShell:** ```powershell cd 01-introduction .\start.ps1 ``` -两个脚本都会自动从根目录 `.env` 文件加载环境变量，且如果 JAR 不存在会自动构建。 +两个脚本均自动从根目录 `.env` 文件加载环境变量，如果 JAR 文件不存在，则会构建。 -> **注意：** 如果希望先手动构建所有模块然后再启动： +> **注意：** 如果你想先手动构建所有模块再启动： > -> **Bash：** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell：** +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -在浏览器打开 http://localhost:8080 。 +打开浏览器访问 http://localhost:8080 。 -**停止运行：** +**停止应用：** -**Bash：** +**Bash:** ```bash ./stop.sh # 仅此模块 # 或 cd .. && ./stop-all.sh # 所有模块 ``` -**PowerShell：** +**PowerShell:** ```powershell .\stop.ps1 # 仅此模块 # 或 @@ -282,41 +282,41 @@ cd ..; .\stop-all.ps1 # 所有模块 ## 使用应用 -该应用提供了两个并列的聊天实现的网页界面。 +该应用提供网页界面，左右并排显示两种聊天实现。 Application Home Screen -*仪表盘展示了简单聊天（无状态）与对话聊天（有状态）选项* +*仪表盘显示简单聊天（无状态）和对话聊天（有状态）选项* ### 无状态聊天（左侧面板） -先试试这个。问“我叫 John”，然后马上问“我叫什么名字？”模型不会记住，因为每条消息都是独立的。这展示了基础语言模型集成的核心问题 —— 无对话上下文。 +先试试这个。先输入“我的名字是 John”，然后立即问“我叫什么名字？”。模型不会记住，因为每条消息都是独立的。这展示了基本语言模型集成的核心问题——没有对话上下文。 Stateless Chat Demo -*AI 不记得你之前说的名字* +*AI 不会记得你上一条消息中的名字* ### 有状态聊天（右侧面板） -现在在这里重复相同步骤。问“我叫 John”，再问“我叫什么名字？”这次它记住了。区别是 MessageWindowChatMemory —— 它维护对话历史，并在每次请求时包含上下文信息。这就是生产级会话 AI 的实现方式。 +然后在这里做同样操作。先说“我的名字是 John”，再问“我叫什么名字？”。这次模型会记得。差别在于 MessageWindowChatMemory —— 它维护对话历史，并在每次请求时附带上下文。这就是生产级对话 AI 的工作方式。 Stateful Chat Demo -*AI 记得对话早前告诉它的名字* +*AI 记得对话中早先告诉它的名字* -两个面板使用的是同一个 GPT-5.2 模型。唯一的不同是内存。这能清楚展示内存给你的应用带来的价值，以及为什么它对真实用例至关重要。 +两个面板都使用相同的 GPT-5.2 模型。唯一区别是内存。这清楚展示了内存对你的应用带来了什么，以及为什么它对实际应用至关重要。 -## 下一步 +## 接下来的步骤 -**下一模块：** [02-prompt-engineering - 使用 GPT-5.2 的提示工程](../02-prompt-engineering/README.md) +**下一个模块：** [02-prompt-engineering - 使用 GPT-5.2 的提示工程](../02-prompt-engineering/README.md) --- -**导航：** [← 上一节：模块 00 - 快速入门](../00-quick-start/README.md) | [返回首页](../README.md) | [下一节：模块 02 - 提示工程 →](../02-prompt-engineering/README.md) +**导航：** [← 返回主目录](../README.md) | [下一个：模块 02 - 提示工程 →](../02-prompt-engineering/README.md) --- -**免责声明**： -本文件由AI翻译服务[Co-op Translator](https://github.com/Azure/co-op-translator)翻译而成。尽管我们努力保证准确性，但请注意，自动翻译可能包含错误或不准确之处。原始文件的原文应被视为权威来源。对于重要信息，建议使用专业人工翻译。因使用本翻译而产生的任何误解或误释，我们概不负责。 +**免责声明**： +本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。 \ No newline at end of file diff --git a/translations/zh-CN/02-prompt-engineering/README.md b/translations/zh-CN/02-prompt-engineering/README.md index 6d9ae594c..dd4021584 100644 --- a/translations/zh-CN/02-prompt-engineering/README.md +++ b/translations/zh-CN/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# 模块 02：使用 GPT-5.2 的提示工程 +# Module 02: 使用 GPT-5.2 进行提示工程 ## 目录 -- [视频演示](../../../02-prompt-engineering) -- [你将学到什么](../../../02-prompt-engineering) -- [先决条件](../../../02-prompt-engineering) -- [理解提示工程](../../../02-prompt-engineering) -- [提示工程基础](../../../02-prompt-engineering) - - [零样本提示](../../../02-prompt-engineering) - - [少样本提示](../../../02-prompt-engineering) - - [思维链](../../../02-prompt-engineering) - - [基于角色的提示](../../../02-prompt-engineering) - - [提示模板](../../../02-prompt-engineering) -- [高级模式](../../../02-prompt-engineering) -- [运行应用程序](../../../02-prompt-engineering) -- [应用程序截图](../../../02-prompt-engineering) -- [探索模式](../../../02-prompt-engineering) - - [低渴望 vs 高渴望](../../../02-prompt-engineering) - - [任务执行（工具前言）](../../../02-prompt-engineering) - - [自我反思代码](../../../02-prompt-engineering) - - [结构化分析](../../../02-prompt-engineering) - - [多轮对话](../../../02-prompt-engineering) - - [逐步推理](../../../02-prompt-engineering) - - [受限输出](../../../02-prompt-engineering) -- [你真正学到了什么](../../../02-prompt-engineering) -- [后续步骤](../../../02-prompt-engineering) - -## 视频演示 - -观看这段直播课程，讲解如何开始本模块： +- [视频讲解](#视频讲解) +- [你将学到什么](#你将学到什么) +- [先决条件](#先决条件) +- [理解提示工程](#理解提示工程) +- [提示工程基础](#提示工程基础) + - [零样本提示](#零样本提示) + - [少样本提示](#少样本提示) + - [思维链](#思维链) + - [基于角色的提示](#基于角色的提示) + - [提示模板](#提示模板) +- [高级模式](#高级模式) +- [运行应用程序](#运行应用程序) +- [应用程序截图](#应用截图) +- [探索模式](#探索模式) + - [低渴望与高渴望](#低关注度-vs-高关注度) + - [任务执行（工具前言）](#任务执行（工具前言）) + - [自我反思代码](#自省代码) + - [结构化分析](#结构化分析) + - [多轮聊天](#多轮对话) + - [逐步推理](#逐步推理) + - [受限输出](#受限输出) +- [你真正学到了什么](#你真正学到了什么) +- [接下来的步骤](#下一步) + +## 视频讲解 + +观看本直播课程，了解如何开始本模块： Prompt Engineering with LangChain4j - Live Session ## 你将学到什么 -下图概述了你将在本模块中掌握的关键主题和技能——从提示优化技巧到你将遵循的逐步工作流程。 +下面的图表概述了你将在本模块中学习的关键主题和技能——从提示优化技巧到你将遵循的逐步工作流程。 What You'll Learn -在之前的模块中，你探索了 LangChain4j 与 GitHub 模型的基础交互，并看到内存如何借助 Azure OpenAI 实现对话式 AI。现在，我们将关注如何提问——也就是提示本身——使用 Azure OpenAI 的 GPT-5.2。你构造提示的方式会极大影响得到的回答质量。我们先回顾基础提示技术，然后深入八种高级模式，充分利用 GPT-5.2 的能力。 +在上一个模块中，你了解了内存如何支持基于 Azure OpenAI 的对话式 AI。现在我们将重点放在如何提问——提示本身的设计，使用 Azure OpenAI 的 GPT-5.2。你结构化提示的方式会极大地影响你获得的回复质量。我们先回顾基本的提示技巧，然后进入八种高级模式，充分利用 GPT-5.2 的能力。 -我们使用 GPT-5.2，是因为它引入了推理控制——你可以告诉模型在回答前需要思考多少。这让不同的提示策略更清晰，也帮助你理解何时使用哪种方法。相比 GitHub 模型，Azure 对 GPT-5.2 的调用限额也更宽松。 +我们选择 GPT-5.2，因为它引入了推理控制——你可以告诉模型在回答前思考多少。这使得不同的提示策略更加明显，帮助你了解何时使用每种方法。 ## 先决条件 -- 已完成模块 01（部署 Azure OpenAI 资源） -- 根目录下的 `.env` 文件包含 Azure 凭据（由模块 01 中的 `azd up` 创建） +- 完成模块01（已部署 Azure OpenAI 资源） +- 根目录有 `.env` 文件，包含 Azure 凭据（由模块01中的`azd up`创建） -> **注意：** 如果你尚未完成模块 01，请先按照那里的部署说明操作。 +> **注意：** 如果你尚未完成模块01，请先按照那里的部署说明操作。 ## 理解提示工程 -提示工程的核心，是模糊指令和精准指令之间的区别，下图对此进行了说明。 +提示工程的本质是模糊指令与精确指令之间的区别，如下图所示。 What is Prompt Engineering? -提示工程是设计输入文本，确保你持续获得所需结果。它不仅仅是提问——而是构造请求，让模型准确理解你想要什么以及如何交付。 +提示工程就是设计输入文本，使你能持续获得所需结果。它不仅仅是提问——而是结构化请求，让模型准确理解你想要什么以及如何交付。 -把它想象成给同事下达指令。“修复 bug”很模糊。“通过添加空检查修复 UserService.java 第 45 行的空指针异常”则具体。语言模型的工作方式也是如此——具体和结构化很重要。 +把它比作给同事下指令。“修复 bug”就很模糊。“通过添加空值检查，修复 UserService.java 第45行的空指针异常”则很具体。语言模型也是如此——具体性和结构非常重要。 -下图展示了 LangChain4j 在其中的角色——通过 SystemMessage 和 UserMessage 构建块，将你的提示模式连接到模型。 +下图展示了 LangChain4j 在这其中的角色——通过 `SystemMessage` 和 `UserMessage` 构建块，将你的提示模式连接至模型。 How LangChain4j Fits -LangChain4j 提供基础架构——模型连接、内存和消息类型——而提示模式只是你通过这套架构传递的精心结构化文本。关键构建块是 `SystemMessage`（设置 AI 的行为和角色）和 `UserMessage`（承载你的实际请求）。 +LangChain4j 提供基础设施——模型连接、内存和消息类型——而提示模式只是你通过这套基础设施发送的精心结构化文本。关键构建块是 `SystemMessage`（设定 AI 的行为和角色）和 `UserMessage`（承载你的具体请求）。 ## 提示工程基础 -下图展示的五种核心技术，构成了有效提示工程的基础。每种技术都解决你与语言模型交流的不同方面。 +以下五种核心技巧构成有效提示工程的基础。每种都针对你与语言模型沟通的不同方面。 Five Prompt Engineering Patterns Overview -在深入本模块的高级模式前，我们先回顾五种基础提示技术。这些是每位提示工程师都应该了解的构建模块。如果你已经完成了[快速入门模块](../00-quick-start/README.md#2-prompt-patterns)，你会在实践中见过这些——以下是它们背后的概念框架。 +在探讨本模块的高级模式前，我们先回顾五种基础提示技巧。这些是每个提示工程师都应掌握的基石。 ### 零样本提示 -最简单的方法：给模型直接指令，无需示例。模型完全依赖其训练去理解并执行任务。适合预期行为明显的简单请求。 +最简单的方法：不给示例，直接给模型指令。模型完全依赖其训练来理解和执行任务。适用于行为明显的简单请求。 Zero-Shot Prompting -*无示例的直接指令——模型仅从指令本身推断任务* +*无示例的直接指令——模型仅从指令推断任务* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// 响应：“积极” +// 回复：“阳性” ``` -**何时使用：** 简单分类、直接提问、翻译，或任何模型无需额外指导即可完成的任务。 +**适用场景：** 简单分类、直接提问、翻译或任何无需额外指导模型可处理的任务。 ### 少样本提示 -提供示例，展示你期望模型遵循的模式。模型从示例中学习输入-输出格式，并应用到新输入上。大幅提升了那些所需格式或行为不明显任务的一致性。 +给出示例，展示你希望模型遵循的模式。模型从示例中学输入输出格式，然后应用于新输入。这极大提高了格式或行为不明显任务的一致性。 Few-Shot Prompting -*通过示例学习——模型识别模式并应用到新输入* +*从示例中学习——识别模式并应用于新输入* ```java String prompt = """ @@ -112,11 +112,11 @@ String prompt = """ String response = model.chat(prompt); ``` -**何时使用：** 定制分类、一致格式、领域特定任务，或零样本结果不稳定时。 +**适用场景：** 自定义分类、一致格式化、特定领域任务，或零样本结果不稳定时。 ### 思维链 -让模型逐步展示其推理过程。模型不是直接给出答案，而是分解问题，明确每一步推理。提升数学、逻辑和多步骤推理任务的准确率。 +让模型逐步展示推理过程。不是直接给答案，而是分解问题，清晰处理每个部分。提升数学、逻辑、多步推理任务的准确度。 Chain of Thought Prompting @@ -133,15 +133,15 @@ String response = model.chat(prompt); // 模型显示：15 - 8 = 7，然后 7 + 12 = 19 个苹果 ``` -**何时使用：** 数学题、逻辑难题、调试，或任何展示推理过程能提升准确率和可信度的任务。 +**适用场景：** 数学题、逻辑谜题、调试，或任何清晰展示推理过程能提升准确性和信任的任务。 ### 基于角色的提示 -在提问前为 AI 设定一个身份或角色。这样提供了上下文，影响回答的语气、深度和重点。“软件架构师”给出的建议会与“初级开发者”或“安全审计员”不同。 +在提问前设定 AI 的身份或角色。为回复提供上下文，影响语气、深度和焦点。“软件架构师”与“初级开发者”或“安全审计员”会给出不同的建议。 Role-Based Prompting -*设置上下文和角色——同一问题根据指定角色得到不同回答* +*设定上下文和角色——同一问题根据角色会有不同回复* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**何时使用：** 代码审查、辅导、领域特定分析，或需要针对特定专业水平或视角定制回答时。 +**适用场景：** 代码审查、辅导、领域分析，或需要针对特定专业水平或视角的回答时。 ### 提示模板 -创建带变量占位符的可重用提示。不必每次写新提示，定义好模板后填入不同数值。LangChain4j 的 `PromptTemplate` 类使用 `{{variable}}` 语法，操作简便。 +创建带变量占位符的可复用提示。不必每次写新提示，只需定义一次模板，填入不同值。LangChain4j 的 `PromptTemplate` 类用 `{{variable}}` 语法轻松实现。 Prompt Templates -*带变量占位符的可重用提示——一个模板，多种用法* +*带变量占位符的可复用提示——一份模板，多次使用* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**何时使用：** 不同输入的重复查询、批量处理、构建可复用 AI 工作流，或任何提示结构固定但数据变化的场景。 +**适用场景：** 重复查询不同输入、批量处理、构建可复用 AI 流程，或提示结构固定但数据变化的场景。 --- -这五种基础技术为你大多数提示任务提供了坚实工具包。本模块接下来的内容，将基于它们展开**八种高级模式**，利用 GPT-5.2 的推理控制、自我评估和结构化输出能力。 +这五个基础技巧为你大部分提示任务提供了坚实工具集。本模块其余内容基于此，介绍八种高级模式，利用 GPT-5.2 的推理控制、自我评估和结构化输出能力。 ## 高级模式 -基础内容讲完，让我们进入本模块独特的八种高级模式。不是所有问题都适合同一种方法。有些问题需要快速回答，有些则需要深入思考。有些需要展示推理过程，有些只要结果。下图中每个模式针对不同场景进行了优化——而 GPT-5.2 的推理控制让这些差异更加显著。 +掌握基础后，让我们进入本模块独具特色的八种高级模式。并非所有问题都需同一方法。有的要迅速回答，有的需深度思考。有的需展示推理，有的只要结果。下面每种模式针对不同场景优化——GPT-5.2 的推理控制让这些差异更加明显。 Eight Prompting Patterns -*八种提示工程模式及其应用场景概览* +八种提示工程模式及其用例概览 -GPT-5.2 为这些模式增加了另一个维度：*推理控制*。下方滑块展示你如何调节模型的思考深度——从快速直接回答到深入彻底分析。 +GPT-5.2 为这些模式增加了新维度：推理控制。下面的滑块展示你如何调节模型的思考力度——从快速直接回答到深入彻底分析。 Reasoning Control with GPT-5.2 -*GPT-5.2 的推理控制允许你指定模型应进行多少思考——从快捷直接到深度探索* +*GPT-5.2 的推理控制让你决定模型思考多少——从快速答复到深入探索* -**低渴望（快速且聚焦）** - 适合简单问题，快速直接回答。模型推理步骤极少，最多 2 步。用于计算、查阅或直接问题。 +**低渴望（快速且专注）** - 简单问题快速直达答案。模型推理最少，最多两步。适合计算、查找或简单提问。 ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **可用 GitHub Copilot 探索：** 打开 [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java)，尝试提问： -> - “低渴望与高渴望提示模式有何区别？” -> - “提示中的 XML 标签如何帮助构造 AI 回答？” -> - “何时使用自我反思模式，何时直接指令？” +> 💡 **用 GitHub Copilot 探索：** 打开 [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java)，问： +> - “低渴望和高渴望提示模式有什么区别？” +> - “提示中的 XML 标签如何帮助结构化 AI 的回答？” +> - “什么时候使用自我反思模式，什么时候用直接指令？” -**高渴望（深入且彻底）** - 针对复杂问题，给予全面分析。模型深入探索，展现详细推理。适用于系统设计、架构决策或复杂研究。 +**高渴望（深度且彻底）** - 复杂问题，需全面分析。模型详细推理、充分探索。适合系统设计、架构决策或复杂研究。 ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**任务执行（逐步进展）** - 适合多步骤工作流。模型先给出计划，执行时逐步叙述过程，最后总结。用于迁移、实现或任意多步骤进程。 +**任务执行（逐步进度）** - 多步骤工作流。模型先给计划，再边做边讲，最后总结。适用于迁移、实现或任何多步骤过程。 ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -思维链提示明确要求模型展示推理过程，提高复杂任务准确率。逐步拆解有助于人类和 AI 理解逻辑。 +思维链提示明确要求模型展示推理过程，提升复杂任务准确性。逐步拆解帮助人和 AI 理解逻辑。 -> **🤖 可用 [GitHub Copilot](https://github.com/features/copilot) 聊天尝试提问：** -> - “如何改造任务执行模式支持长时间运行操作？” -> - “在生产应用中安排工具前言的最佳实践是什么？” -> - “如何捕获并在 UI 中显示中间进展更新？” +> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) Chat 试试：** 询问该模式： +> - “如何调整任务执行模式以支持长时间运行操作？” +> - “生产应用中如何设计工具前言的最佳实践？” +> - “如何捕获并展示 UI 中的中间进度更新？” -下图展示了此计划 → 执行 → 总结的工作流程。 +下图展示计划 → 执行 → 总结的工作流程。 Task Execution Pattern -*多步骤任务的计划 → 执行 → 总结工作流程* +*多步骤任务的计划 → 执行 → 总结工作流* -**自我反思代码** - 生成生产级代码。模型生成符合生产标准、具备适当错误处理的代码。用于构建新功能或服务。 +自我反思代码 - 生成生产质量代码。模型产出符合生产标准的代码，带有适当错误处理。适合新功能或服务开发。 ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下图展示了此迭代改进循环——生成、评估、识别缺陷、完善，直到代码达到生产标准。 +下图描绘迭代改进循环——生成、评估、识别问题、改进，直到代码符合生产要求。 Self-Reflection Cycle -*迭代改进循环——生成、评估、识别问题、改进、重复* +*迭代改进循环——生成、评估、发现问题、改进、重复* -**结构化分析** - 进行一致的评估。模型使用固定框架评审代码（包括正确性、实践、性能、安全性、可维护性）。适合代码审查或质量评估。 +结构化分析 - 一致评估。模型使用固定框架（正确性、实践、性能、安全、可维护性）审查代码。适合代码审查或质量评估。 ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 可用 [GitHub Copilot](https://github.com/features/copilot) 聊天尝试提问：** -> - “如何为不同类型的代码审查自定义分析框架？” -> - “如何以编程方式解析并处理结构化输出？” -> - “如何确保不同审查会话中的严重性等级一致？” +> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) Chat 试试：** 询问结构化分析： +> - “如何为不同类型代码审查定制分析框架？” +> - “程序化解析和处理结构化输出的最佳方法？” +> - “如何保持不同审查会话中严重级别的一致性？” -下图展示该结构化框架如何将代码审查组织成一致类别，并附带严重等级。 +下面图展示如何用结构化框架将代码审查分为不同类别，附带严重级别。 Structured Analysis Pattern -*带严重等级的代码审查一致性框架* +带严重级别的一致代码审查框架 -**多轮对话** - 适合需要上下文的对话。模型记忆之前消息并在此基础上构建。用于交互式帮助会话或复杂问答。 +多轮聊天 - 需要上下文的对话。模型记住此前消息并基于此回复。适合交互式帮助或复杂问答。 ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -下图可视化了对话上下文如何随着多轮累积，以及它与模型令牌限制的关系。 +下图展示对话上下文如何随着轮次积累，以及它如何关联模型的 token 限制。 Context Memory -*对话上下文如何随多轮累积，直至达到令牌上限* -**逐步推理** - 适用于需要显示逻辑的问题。模型展示每一步的明确推理。用于数学题、逻辑谜题或需要理解思考过程的场景。 +*对话上下文如何随多轮积累，直到达到 token 限制* + +逐步推理 - 需要展示逻辑的难题。模型展示每一步明确推理。适合数学题、逻辑谜题，或者需理解思考过程的场景。 ```java String prompt = """ @@ -397,14 +398,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -下图展示模型如何将问题分解为明确且编号的逻辑步骤。 -逐步模式 +下图展示模型如何将问题拆解成明确编号的逻辑步骤。 -*将问题分解为明确的逻辑步骤* +Step-by-Step Pattern +将问题分解为明确的逻辑步骤 -**受限输出** - 适用于对格式有具体要求的回答。模型严格遵守格式和长度规则。用于摘要或需要精确输出结构的场景。 +受限输出 - 适用于有特定格式要求的回复。模型严格遵守格式和长度规则。用于摘要或需要精确输出结构的场景。 ```java String prompt = """ @@ -419,190 +419,190 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -下图展示约束如何指导模型产出严格符合格式和长度要求的输出。 + +下图展示了约束如何引导模型生成严格符合您格式和长度要求的输出。 受限输出模式 -*强制执行特定格式、长度和结构要求* +*强制特定格式、长度和结构要求* ## 运行应用程序 **验证部署：** -确保根目录下存在包含 Azure 凭据的 `.env` 文件（在模块 01 中创建）。在模块目录（`02-prompt-engineering/`）中运行： +确保根目录下存在包含 Azure 凭据的 `.env` 文件（在模块01中创建）。从模块目录 (`02-prompt-engineering/`) 运行： -**Bash：** +**Bash:** ```bash -cat ../.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +cat ../.env # 应该显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` - -**PowerShell：** + +**PowerShell:** ```powershell Get-Content ..\.env # 应该显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` - + **启动应用程序：** -> **注意：** 如果你已使用根目录中的 `./start-all.sh` 启动了所有应用（如模块 01 所述），则本模块已经在端口 8083 运行。可以跳过下面的启动命令，直接访问 http://localhost:8083。 +> **注意：** 如果您已使用根目录下的 `./start-all.sh` 启动所有应用程序（如模块01中所述），本模块已在端口8083上运行。您可以跳过下面的启动命令，直接访问 http://localhost:8083。 -**选项 1：使用 Spring Boot Dashboard（推荐 VS Code 用户）** +**选项1：使用 Spring Boot Dashboard（推荐 VS Code 用户）** -开发容器包含 Spring Boot Dashboard 扩展，为管理所有 Spring Boot 应用程序提供可视化界面。可在 VS Code 左侧活动栏找到（Spring Boot 图标）。 +开发容器包含 Spring Boot Dashboard 扩展，提供管理所有 Spring Boot 应用的可视界面。您可以在 VS Code 左侧的活动栏中找到它（查找 Spring Boot 图标）。 -通过 Spring Boot Dashboard，你可以： -- 查看工作区内所有可用的 Spring Boot 应用 -- 一键启动/停止应用 -- 实时查看应用日志 +通过 Spring Boot Dashboard，您可以： +- 查看工作区内所有可用的 Spring Boot 应用 +- 一键启动/停止应用 +- 实时查看应用日志 - 监控应用状态 -只需点击 "prompt-engineering" 旁的播放按钮启动此模块，或一次性启动所有模块。 +只需点击“prompt-engineering”旁的播放按钮即可启动此模块，或一次启动所有模块。 Spring Boot Dashboard -*VS Code 中的 Spring Boot Dashboard — 一处启动、停止并监控所有模块* +*VS Code 中的 Spring Boot Dashboard — 从一个地方启动、停止并监控所有模块* -**选项 2：使用 shell 脚本** +**选项2：使用 shell 脚本** -启动所有 Web 应用（模块 01-04）： +启动所有 Web 应用（模块01-04）： -**Bash：** +**Bash:** ```bash cd .. # 从根目录 ./start-all.sh ``` - -**PowerShell：** + +**PowerShell:** ```powershell cd .. # 从根目录 .\start-all.ps1 ``` - -或仅启动此模块： -**Bash：** +或者仅启动本模块： + +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` - -**PowerShell：** + +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` - -两个脚本会自动从根目录 `.env` 文件加载环境变量，且如果 JAR 文件不存在会自动构建。 -> **注意：** 如果你更倾向于先手动构建所有模块再启动： +两个脚本会自动从根目录 `.env` 文件加载环境变量，如果 JAR 文件不存在则会构建。 + +> **注意：** 如果你想手动构建所有模块后再启动： > -> **Bash：** +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -> **PowerShell：** +> +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -在浏览器中打开 http://localhost:8083。 -**停止操作：** +在浏览器中打开 http://localhost:8083 。 -**Bash：** +**停止应用：** + +**Bash:** ```bash ./stop.sh # 仅此模块 -# 或 +# 或者 cd .. && ./stop-all.sh # 所有模块 ``` - -**PowerShell：** + +**PowerShell:** ```powershell .\stop.ps1 # 仅此模块 # 或 cd ..; .\stop-all.ps1 # 所有模块 ``` - + ## 应用截图 -这是提示工程模块的主界面，你可以在这里并排试验全部八种模式。 +这是提示工程模块的主界面，您可以在此并排试验全部八种模式。 -仪表盘主页 +仪表板主页 -*主仪表盘展示全部8种提示工程模式及其特性和用例* +*主仪表板显示全部8个提示工程模式及其特点和应用场景* ## 探索模式 -Web 界面允许你试验不同提示策略。每种模式解决不同问题——试试它们，看看每种方法何时表现最佳。 +Web 界面允许您试验不同的提示策略。每种模式解决不同的问题——试试它们，看看每种方法何时发挥效用。 -> **注意：流式与非流式** — 每个模式页面均提供两个按钮：**🔴 流式响应（实时）** 和 **非流式** 选项。流式使用服务端事件（SSE）实时显示模型生成的标记，能即时看到进展。非流式则等待服务器返回完整响应才显示。对于需要深入推理的提示（如高渴望、自我反思代码），非流式调用可能耗时很长——有时达到几分钟，且无任何可见反馈。**实验复杂提示时建议使用流式**，这样能实时观看模型工作，避免误以为请求超时。 -> -> **浏览器要求** — 流式功能使用 Fetch Streams API（`response.body.getReader()`），需要完整浏览器支持（Chrome、Edge、Firefox、Safari）。VS Code 内置的 Simple Browser 不支持此 API，因其 WebView 不支持 ReadableStream API。使用 Simple Browser 时非流式按钮正常，唯独流式按钮无效。建议在外部浏览器打开 `http://localhost:8083` 以获得完整体验。 +> **注意：流式与非流式** — 每个模式页面都提供两个按钮：**🔴 流式响应（实时）** 和 非流式 选项。流式使用服务器发送事件（SSE）实时显示模型生成的每个 token，您可即时见到进度。非流式会等待全部响应生成完毕后才显示。对于触发深度推理的提示（如高关注度、高自省代码），非流式调用可能非常耗时——有时几分钟且无明显反馈。在试验复杂提示时请使用流式，这样可看到模型工作过程，避免误判请求超时。 +> +> **注意：浏览器要求** — 流式功能依赖 Fetch Streams API (`response.body.getReader()`)，需要完整版浏览器（Chrome、Edge、Firefox、Safari）。VS Code 内置的简单浏览器不支持 ReadableStream API，因此不支持流式。使用简单浏览器时，非流式按钮可以正常使用——仅流式按钮受限。请在外部浏览器打开 `http://localhost:8083` 以获得完整体验。 -### 低渴望 vs 高渴望 +### 低关注度 vs 高关注度 -用低渴望试问简单问题如 “200 的 15% 是多少？”你会得到一个即时的直接答案。用高渴望试问复杂问题如 “为高流量 API 设计缓存策略”，点击 **🔴 流式响应（实时）**，你会看到模型逐字逐句给出详细推理。同样的模型、相同的问题结构，不同的是提示告诉它思考多少。 +用低关注度问个简单问题：“200 的 15% 是多少？”您会得到即时、直接的答案。再用高关注度问个复杂问题：“为高流量 API 设计缓存策略”。点击 **🔴 流式响应（实时）**，观察模型逐个 token 详细推理。这是同一模型、相似的问法——区别在于提示告诉它要思考多少。 ### 任务执行（工具前言） -多步骤工作流受益于事先规划和过程解说。模型概述它将做什么，讲述每一步，最终总结结果。 +多步骤工作流受益于提前规划和进度讲解。模型会先概述要做什么，再逐步讲解，然后总结结果。 -### 自我反思代码 +### 自省代码 -试试 “创建一个邮件验证服务”。模型不会仅生成代码后停止，而是会生成、根据质量标准评估、识别缺陷并改进。你会看到它反复迭代直到代码符合生产标准。 +试试“创建一个邮件验证服务”。模型不仅生成代码，而且根据质量标准自我评估，找出弱点并改进。您会看到它反复迭代直到代码达到生产标准。 ### 结构化分析 -代码评审需要统一的评估框架。模型使用固定类别（正确性、实践、性能、安全）和严重等级分析代码。 +代码审查需一致评估框架。模型用固定分类（正确性、实践、性能、安全）并附严重级别分析代码。 -### 多轮聊天 +### 多轮对话 -问 “什么是 Spring Boot？”然后立刻跟进 “给我个例子”。模型记住你的第一个问题，专门给你一个 Spring Boot 示例。若无记忆，第二个问题太模糊无法准确回答。 +问“小春 Boot 是什么？”然后紧接着问“给我看个例子”。模型会记住第一个问题，给你一个针对 Spring Boot 的具体示例。没有记忆的话，第二个问题太笼统。 ### 逐步推理 -选一个数学题，用逐步推理和低渴望两种模式试试。低渴望直接给答案——快但不透明。逐步推理则展示每个计算和决策。 +选个数学题，同时用逐步推理和低关注度尝试。低关注度只给答案——快速但不透明；逐步推理展示所有计算和决策步骤。 ### 受限输出 -需要特定格式或字数时，此模式确保严格遵守。尝试产出一个精确 100 字且使用项目符号的摘要。 +当你需要特定格式或字数时，这种模式会强制严格遵守。试试生成正好100字的项目符号格式摘要。 -## 你真正学到的是什么 +## 你真正学到了什么 -**推理努力决定一切** +推理投入改变一切 -GPT-5.2 允许你通过提示控制计算努力。低努力意味着快速响应且探索少。高努力意味着模型花时间深入思考。你学会了匹配努力程度与任务复杂度——简单问题不浪费时间，复杂决策也不草率。 +GPT-5.2 允许你通过提示控制计算投入。低投入意味着快速响应，探索少；高投入则让模型花时间深入思考。你正在学习如何匹配投入与任务复杂度——简单问题不浪费时间，复杂决策不急躁。 -**结构引导行为** +结构引导行为 -注意提示中的 XML 标签？它们不是装饰。模型比随意文本更可靠地遵循结构化指令。当你需要多步流程或复杂逻辑时，结构帮助模型跟踪位置和后续步骤。下图分解了一个结构良好的提示，显示 ``、``、``、`` 和 `` 等标签如何将指令组织成清晰部分。 +注意提示中的 XML 标签？它们不是装饰。模型比自由文本更可靠地遵循结构化指令。需要多步骤或复杂逻辑时，结构有助于模型跟踪当前状态和下一步。下图分解了一个结构良好的提示，展示 ``、``、``、``、`` 等标签如何将指令划分为清晰部分。 提示结构 -*一个结构良好的提示剖析，包含清晰分区和 XML 风格组织* +*结构良好提示的组成，清晰分段和 XML 风格组织* -**通过自我评估提升质量** +质量来自自我评估 -自我反思模式通过将质量标准显式化实现。这不是靠“希望模型做对”，而是明确告诉模型“正确”意味着什么：逻辑正确、错误处理、性能、安全等。模型随后自我评估产出并改进。代码生成由此从彩票变过程。 +自省模式通过明确质量标准工作。不再依赖模型“做对”，而是告诉它“对”的定义：逻辑正确、错误处理、性能、安全。模型可以评估自身输出并改进。这样代码生成从抽奖变成一个过程。 -**上下文是有限的** +上下文是有限的 -多轮对话通过在每次请求中包含消息历史实现。但有最大令牌数限制。随着对话增长，你需要策略保持相关上下文而不超限。本模块展示记忆机制；后续你将学习何时总结、何时遗忘、何时检索。 +多轮对话通过附加消息历史实现。但有上限——每个模型有最大 token 数。对话增长时，你需要策略来保持相关上下文同时不超限。本模块展示记忆如何工作；后续你将学习何时总结、何时忘记、何时检索。 ## 下一步 -**下一个模块：** [03-rag - RAG（检索增强生成）](../03-rag/README.md) +**下一模块：** [03-rag - RAG（检索增强生成）](../03-rag/README.md) --- -**导航：** [← 上一模块：模块 01 - 介绍](../01-introduction/README.md) | [返回主目录](../README.md) | [下一模块：模块 03 - RAG →](../03-rag/README.md) +**导航：** [← 上一节：模块01 - 介绍](../01-introduction/README.md) | [返回主页](../README.md) | [下一节：模块03 - RAG →](../03-rag/README.md) --- -**免责声明**： -本文件由AI翻译服务【Co-op Translator】（https://github.com/Azure/co-op-translator）翻译而成。尽管我们力求准确，但请注意自动翻译可能存在错误或不准确之处。原始文档的原语言版本应视为权威来源。对于关键信息，建议采用专业人工翻译。因使用本翻译内容而产生的任何误解或误释，我们概不负责。 +**免责声明**： +本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。 \ No newline at end of file diff --git a/translations/zh-CN/03-rag/README.md b/translations/zh-CN/03-rag/README.md index 737a9974f..c10fb6ecf 100644 --- a/translations/zh-CN/03-rag/README.md +++ b/translations/zh-CN/03-rag/README.md @@ -1,144 +1,144 @@ -# Module 03: RAG（检索增强生成） +# 模块 03：RAG（检索增强生成） ## 目录 -- [视频演示](../../../03-rag) -- [你将学到什么](../../../03-rag) -- [前置条件](../../../03-rag) -- [理解 RAG](../../../03-rag) - - [本教程使用哪种 RAG 方法？](../../../03-rag) -- [工作原理](../../../03-rag) - - [文档处理](../../../03-rag) - - [创建嵌入](../../../03-rag) - - [语义搜索](../../../03-rag) - - [答案生成](../../../03-rag) -- [运行应用程序](../../../03-rag) -- [使用应用程序](../../../03-rag) - - [上传文档](../../../03-rag) - - [提问](../../../03-rag) - - [查看来源参考](../../../03-rag) - - [实验问题](../../../03-rag) -- [关键概念](../../../03-rag) - - [分块策略](../../../03-rag) - - [相似度评分](../../../03-rag) - - [内存存储](../../../03-rag) - - [上下文窗口管理](../../../03-rag) -- [RAG 何时重要](../../../03-rag) -- [下一步](../../../03-rag) +- [视频讲解](#视频讲解) +- [你将学习到的内容](#你将学习到的内容) +- [先决条件](#先决条件) +- [理解 RAG](#理解-rag) + - [本教程使用哪种 RAG 方法？](#本教程使用哪种-rag-方法？) +- [工作原理](#工作原理) + - [文档处理](#文档处理) + - [创建嵌入](#创建嵌入) + - [语义搜索](#语义搜索) + - [答案生成](#答案生成) +- [运行应用程序](#运行应用) +- [使用应用程序](#使用应用) + - [上传文档](#上传文档) + - [提问](#提问) + - [检查来源引用](#检查来源引用) + - [试验提问](#试验不同问题) +- [关键概念](#关键概念) + - [分块策略](#分块策略) + - [相似度分数](#相似度分数) + - [内存存储](#内存存储) + - [上下文窗口管理](#上下文窗口管理) +- [何时使用 RAG](#适用场景) +- [下一步](#后续步骤) -## 视频演示 +## 视频讲解 -观看本直播课程，了解如何开始本模块： +观看此直播环节，讲解如何开始使用本模块： -RAG with LangChain4j - Live Session +LangChain4j 的 RAG - 直播环节 -## 你将学到什么 +## 你将学习到的内容 -在前面的模块中，你学习了如何与 AI 对话以及如何有效构建提示。但有一个根本限制：语言模型只知道它们训练时学到的内容。它们无法回答关于你公司政策、项目文档或其他未经过训练的信息的问题。 +在之前的模块中，你学会了如何与 AI 进行对话及有效构建提示，但存在一个根本限制：语言模型仅知道训练时学到的内容。它们无法回答有关你公司政策、项目文档或任何未被训练过信息的问题。 -RAG（检索增强生成）解决了这个问题。它不是试图教会模型你的信息（既昂贵又不现实），而是赋予它在你的文档中搜索的能力。当有人提问时，系统会找到相关信息并将其包含进提示中。模型随后根据检索到的上下文进行回答。 +RAG（检索增强生成）解决了这个问题。它不是试图教模型你的信息（这既昂贵又不实际），而是赋予它搜索你文档的能力。当有人提问时，系统会找到相关信息并将其包含在提示中，模型基于该检索到的上下文回答。 -把 RAG 想象成给模型提供了一个参考图书馆。当你提问时，系统： +把 RAG 看作给模型提供一本参考书。当你提问时，系统： -1. **用户查询** - 你提出问题 -2. **嵌入** - 将你的问题转换为向量 -3. **向量搜索** - 找到相似的文档分块 -4. **上下文组装** - 将相关分块加入提示 -5. **响应** - LLM 基于上下文生成答案 +1. 用户查询 – 你提出问题 +2. 嵌入转换 – 将你的问题转为向量 +3. 向量搜索 – 找到相似的文档块 +4. 上下文组装 – 将相关块加入提示 +5. 回应 – LLM 根据上下文生成答案 -这使模型的回答基于你的实际数据，而不是依赖其训练知识或杜撰答案。 +这样模型的回答基于你的实际数据，而非仅靠训练知识或虚构答案。 -## 前置条件 +## 先决条件 -- 完成 [Module 00 - 快速入门](../00-quick-start/README.md)（为本模块后面引用的 Easy RAG 示例做准备） -- 完成 [Module 01 - 介绍](../01-introduction/README.md)（已经部署 Azure OpenAI 资源，包括 `text-embedding-3-small` 嵌入模型） -- 项目根目录下有 `.env` 文件，包含 Azure 认证（由 Module 01 中的 `azd up` 命令创建） +- 完成 [模块 01 - 介绍](../01-introduction/README.md)（已部署 Azure OpenAI 资源，包括 `text-embedding-3-small` 嵌入模型） +- 根目录下包含含 Azure 凭证的 `.env` 文件（由模块 01 的 `azd up` 创建） -> **注意：** 如果你还没有完成 Module 01，请先按照模块中的部署说明操作。`azd up` 命令会部署 GPT 聊天模型和本模块使用的嵌入模型。 +> **注意：** 如果尚未完成模块 01，请先按照那里的部署说明操作。`azd up` 命令会部署本模块所用的 GPT 聊天模型和嵌入模型。 ## 理解 RAG -下图展示了核心概念：RAG 不仅仅依赖模型的训练数据，而是给它一个你的文档参考库，允许在生成每个答案之前先查阅。 +下图说明核心概念：RAG 不只依赖模型训练数据，而是先让模型查询你的文档参考库，才生成答案。 -What is RAG +什么是 RAG -*该图展示了标准 LLM（根据训练数据猜测）与 RAG 增强 LLM（优先使用你的文档进行检索）之间的区别。* +*此图展示普通大语言模型（从训练数据猜测）与 RAG 增强模型（先查询你的文档）的区别。* -以下是端到端的流程。用户提问经历四个阶段——嵌入、向量搜索、上下文组装和答案生成——每个阶段都建立在之前的基础上： +下图展示端到端流程。用户问题经过嵌入、向量搜索、上下文组装，再到答案生成，每步基于前一步： -RAG Architecture +RAG 架构 -*该图显示了端到端的 RAG 流程——用户查询经过嵌入、向量搜索、上下文组装和答案生成。* +*此图展示端到端 RAG 流程 — 用户查询经历嵌入、向量搜索、上下文组装和答案生成。* -本模块接下来会详细介绍各个阶段，并带有可执行和修改的代码。 +本模块接下来会逐步详解每个阶段，附带可运行和修改的代码。 ### 本教程使用哪种 RAG 方法？ -LangChain4j 提供了三种实现 RAG 的方式，每种抽象级别不同。下图并列对比了这三种方法： +LangChain4j 提供三种实现 RAG 的方式，抽象层级不同。下图并列比较： -Three RAG Approaches in LangChain4j +LangChain4j 中的三种 RAG 方法 -*该图比较了 LangChain4j 的三种 RAG 方法——Easy、Native 和 Advanced，展示它们的关键组件及适用场合。* +*此图比较 LangChain4j 的三种 RAG 方法 — Easy、Native 和 Advanced — 展示关键组件及适用场景。* -| 方法 | 功能 | 权衡 | +| 方法 | 功能描述 | 权衡 | |---|---|---| -| **Easy RAG** | 通过 `AiServices` 和 `ContentRetriever` 自动连接所有流程。你只需给接口注解，挂载检索器，LangChain4j 会自动处理嵌入、搜索和提示组装。 | 代码量最小，但每个步骤的细节不可见。 | -| **Native RAG** | 你自己调用嵌入模型、搜索存储、构建提示和生成答案——逐步显式完成。 | 代码更多，但每个阶段都清晰且可修改。 | -| **Advanced RAG** | 利用 `RetrievalAugmentor` 框架，支持可插拔的查询转换器、路由器、重排序器和内容注入器，适合生产级流水线。 | 灵活性最大，但复杂度显著增加。 | +| **Easy RAG** | 通过 `AiServices` 和 `ContentRetriever` 自动完成所有流程。你只需注解接口，挂载检索器，LangChain4j 在后台处理嵌入、搜索和提示组装。 | 代码量最少，但看不到每步细节。 | +| **Native RAG** | 你自己调用嵌入模型、搜索存储、构建提示和生成答案——逐步明确地。 | 代码更多，但每个阶段透明且可修改。 | +| **Advanced RAG** | 使用 `RetrievalAugmentor` 框架，支持可插拔的查询转换器、路由器、再排序器和内容注入器，适合生产级流水线。 | 灵活度最高，但复杂度显著提升。 | -**本教程采用 Native 方法。** RAG 流程的每一步——查询嵌入、向量库搜索、上下文组装与答案生成——都在 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 中明确写出。这是有意为之：作为学习资源，看到和理解每个阶段比代码最简更重要。熟悉了流程后，你可以转向 Easy RAG 快速原型或 Advanced RAG 用于生产系统。 +**本教程采用 Native 方式。** RAG 各阶段——查询嵌入、向量存储搜索、上下文组装和答案生成——均在 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 明确实现。这是为了学习，重要的是看到并理解每个步骤，代码是否简洁次之。一旦熟悉流程，你可以转用 Easy RAG 快速原型开发，或 Advanced RAG 构建生产系统。 -> **💡 之前见过 Easy RAG 吗？** [快速入门模块](../00-quick-start/README.md) 包含一个文档问答示例（[`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)），用的是 Easy RAG 方法——LangChain4j 会自动处理嵌入、搜索和提示组装。本模块则拆解流水线，让你自己实现和控制每个阶段。 +> **💡 想了解 Easy RAG？** LangChain4j 也支持 Easy RAG，由 `AiServices` 和 `ContentRetriever` 自动完成嵌入、搜索和提示组装。本模块走的是更明确的路径——拆开流水线，让你亲自看见并控制每个阶段。 -下图显示快速入门示例中的 Easy RAG 流程。你会注意到 `AiServices` 和 `EmbeddingStoreContentRetriever` 隐藏了所有复杂细节——加载文档，挂上检索器，就能得到答案。本模块的 Native 方法则把这背后的步骤拆开： +下图展示 Easy RAG 流程。注意 `AiServices` 和 `EmbeddingStoreContentRetriever` 如何隐藏复杂性——加载文档、附加检索器，就是获取答案。本模块的 Native 实现则拆开隐蔽步骤： -Easy RAG Pipeline - LangChain4j +Easy RAG 流程 - LangChain4j -*该图展示了 `SimpleReaderDemo.java` 中的 Easy RAG 流程。相比本模块的 Native 方法：Easy RAG 把嵌入、检索和提示组装藏于 `AiServices` 和 `ContentRetriever` 背后——你只需加载文档、挂检索器、获得答案。Native 方法则拆开这些步骤，让你自己调用（嵌入、搜索、组装上下文、生成），全流程可见和可控。* +*此图显示 Easy RAG 流程。对比本模块使用的 Native 方式：Easy RAG 背后由 `AiServices` 和 `ContentRetriever` 隐藏嵌入、检索和提示组装——你只需加载文档、附加检索器，得到答案。Native 方式则拆开流程，自己调用每个步骤（嵌入、搜索、组装上下文、生成答案），实现全程可视和可控。* ## 工作原理 -本模块的 RAG 流程分成四个依次运行的阶段，每当用户提问时触发。首先，上传文档会被**解析和分块**成可管理的小片段。然后将这些分块转换成**向量嵌入**并存储，便于数学上比较。查询到来时，系统进行**语义搜索**，寻找最相关的分块，最终将它们作为上下文传给 LLM，以实现**答案生成**。下面各节配合代码和图示详细讲解每个阶段。先看第一步。 +本模块 RAG 流程分为四个阶段，用户每提问运行一次。首先，将上传的文档解析并分块为合适大小片段。然后，这些片段被转换成向量嵌入，存储后可用数学方式比较。查询进来时，系统执行语义搜索找到最相关的片段，最终将它们作为上下文传给大语言模型生成答案。以下章节将通过代码和图示逐步演示。先来看第一步。 ### 文档处理 [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -当你上传文档（PDF 或纯文本），系统会解析文件，附加包含文件名等的元数据，然后拆成分块——更小的片段，大小适合模型上下文窗口。这些分块间略微重叠，避免边界处丢失上下文。 +上传文档后，系统解析（PDF 或纯文本），附加文件名等元数据，然后切割成小块——每块大小适合模型上下文窗口。这些片段略有重叠，保证边界处不丢失上下文。 ```java -// 解析上传的文件并将其包装在 LangChain4j 文档中 +// 解析上传的文件并将其封装在LangChain4j文档中 Document document = Document.from(content, metadata); -// 拆分成300令牌的块，每块重叠30令牌 +// 分割成300个令牌的块，重叠30个令牌 DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -下图直观展示工作流程。注意每个分块与邻近分块共享部分令牌——30 令牌重叠，确保不会在分块边界丢失重要上下文： -Document Chunking -*该图展示文档被拆分成 300 令牌的分块，分块间有 30 令牌重叠，保证分块边界上下文完整。* +下图直观展示此过程。注意每个块与相邻块令牌重叠30个以保留完整上下文： -> **🤖 试试用 [GitHub Copilot](https://github.com/features/copilot) Chat:** 打开 [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) 并提问： -> - “LangChain4j 如何拆分文档成分块，为什么重叠重要？” -> - “不同类型文档的最佳分块大小是多少，为什么？” -> - “如何处理多语言或带特殊格式的文档？” +文档分块 + +*此图显示将文档切分为300令牌块，每块重叠30令牌，保证分块边界上下文连接。* + +> **🤖 可尝试 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) 并提问： +> - “LangChain4j 如何将文档拆分成块？为何重叠重要？” +> - “不同文档类型的最优块大小是多少？为什么？” +> - “如何处理多语言文档或带特殊格式的文档？” ### 创建嵌入 [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -每个分块会被转换成一种数值表示，称为嵌入——本质上是意义到数字的转换器。嵌入模型不像聊天模型那么“智能”，它不能遵循指令、推理或回答问题。它能做的是将文本映射到数学空间，相似意义的词会彼此靠近——比如“car”和“automobile”，“refund policy”和“return my money”。把聊天模型想象成你能交谈的人，嵌入模型则是极好的归档系统。 +每个文档块被转换成一种叫做嵌入的数值表示——实际上是将含义转为数字。嵌入模型不像聊天模型那样“智能”；它无法理解指令、推理或回答问题。它能做的是将文本映射到数学空间，类似含义的文本会被映射在邻近位置——比如“car”（车）与“automobile”（汽车）相近，“refund policy”（退款政策）与“return my money”（退钱）相近。可以把聊天模型想象成一个能对话的人，嵌入模型则是超强的归档系统。 -下图形象说明这一概念——文本输入，数值向量输出，类似意思的词向量会聚集在一起： +下图可视化该原理——文本输入，数值向量输出，含义相似的文本向量接近： -Embedding Model Concept +嵌入模型概念 -*该图展示嵌入模型如何将文本转成数值向量，使相似含义的词（如“car”和“automobile”）在向量空间中彼此靠近。* +*此图显示嵌入模型如何将文本转换为数值向量，类似含义如“car”和“automobile”在向量空间中相邻。* ```java @Bean @@ -153,30 +153,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -下图显示了 RAG 流程的两条主线和 LangChain4j 实现它们的类。**摄取流程**（上传时运行一次）拆分文档、生成分块嵌入并通过 `.addAll()` 存储。**查询流程**（用户每次提问时运行）生成问题嵌入，通过 `.search()` 搜索，并将匹配上下文传给聊天模型。两条流程共享 `EmbeddingStore` 接口： -LangChain4j RAG Classes +下图展示 RAG 流程中两个独立的执行路径及 LangChain4j 的类实现。摄取流（上传时运行一次）负责分块、嵌入并通过 `.addAll()` 存储。查询流（每次提问时运行）负责嵌入问题、通过 `.search()` 搜索存储，将匹配到的上下文传递给聊天模型。两条流程通过共享的 `EmbeddingStore` 接口连接： -*该图展示 RAG 的两条流程——摄取与查询，它们如何通过共享 EmbeddingStore 接口连接。* +LangChain4j RAG 类 -嵌入存储后，语义相近内容自然在向量空间中聚集。下面的可视化展示了相关主题文档的点聚集在一起，这使得语义搜索成为可能： +*此图显示 RAG 流程中摄取与查询两条路径如何通过共享的 EmbeddingStore 相联结。* -Vector Embeddings Space +嵌入存储完成后，相关内容自然而然地聚集在向量空间。以下可视化显示有关联主题的文档如何在三维向量空间聚集成簇，这就是语义搜索实现的基础： -*该图展示了相关文档如何在 3D 向量空间聚集，技术文档、业务规则和常见问题各形成独立群组。* +向量嵌入空间 -用户搜索时，系统遵循四步：文档先嵌入一次，每次搜索时嵌入查询，使用余弦相似度比较查询向量和所有存储向量，并返回得分最高的前 K 个分块。下图演示每步及其对应的 LangChain4j 类： +*此图展示相关文档在 3D 向量空间聚类，如技术文档、业务规则和常见问题形成不同群组。* -Embedding Search Steps +用户搜索时，系统遵循四步：先嵌入文档（一次），然后每次搜索时嵌入查询，使用余弦相似度比较查询向量和所有存储向量，返回得分最高的前K个块。下图展示步骤及涉及的 LangChain4j 类： -*该图展示四步嵌入搜索过程：文档嵌入、查询嵌入、余弦相似度比较和返回前 K 结果。* +嵌入搜索步骤 + +*此图展示嵌入搜索的四步流程：嵌入文档、嵌入查询、通过余弦相似度比较向量、返回前K结果。* ### 语义搜索 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -你提问时，问题也会被嵌入成向量。系统将你的问题嵌入与所有文档分块嵌入进行比较。它找到语义最相近的分块——不仅是关键词匹配，而是真正的语义相似。 +提问时，你的问题也会被嵌入向量。系统将你的问题向量与所有文档块的向量进行比较。它找到含义最相近的块——不仅仅是关键词匹配，而是语义层面的相似。 ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +195,29 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -下图对比了语义搜索与传统关键词搜索。关键词搜索“vehicle”会错过关于“cars and trucks”的分块，而语义搜索理解它们含义相同，因而将其作为高分匹配返回： -Semantic Search -*该图比较基于关键词的搜索与语义搜索，展示语义搜索如何即使关键词不匹配也能检索到相关概念内容。* -底层使用余弦相似度来衡量相似度 —— 本质上是在问“这两个箭头是否指向相同方向？” 两个块可能使用完全不同的词语，但如果它们的含义相同，它们的向量指向同一方向，得分接近 1.0： +下图对比语义搜索与传统关键词搜索。关键词搜索查找“vehicle”（车辆）时，忽略了关于“cars and trucks”（汽车和卡车）的块，而语义搜索理解它们的同义含义，返回该块作为高分匹配： -余弦相似度 +语义搜索 -*此图展示了余弦相似度，即嵌入向量之间的角度 —— 向量越对齐，得分越接近 1.0，表示语义相似度越高。* +*此图比较基于关键词的搜索与语义搜索，展示语义搜索如何检索含义相关内容，即使关键词不完全匹配。* -> **🤖 试试使用 [GitHub Copilot](https://github.com/features/copilot) 聊天功能：** 打开 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 并提问： -> - “相似度搜索如何与嵌入向量配合工作，分数由什么决定？” +内部相似度用余弦相似度衡量——本质上是在问“两支箭头是否指向同方向？” 即使两个块使用完全不同的词，如果含义相同，它们的向量方向一致，得分接近 1.0： + +余弦相似度 +*此图示意了余弦相似度作为嵌入向量之间的角度 — 越对齐的向量得分越接近1.0，表示语义相似度越高。* + +> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) 聊天尝试：** 打开 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 并提问： +> - “相似度搜索如何结合嵌入向量工作，得分由什么决定？” > - “我应该使用什么相似度阈值，它如何影响结果？” -> - “如果没有找到相关文档，我该如何处理？” +> - “如何处理找不到相关文档的情况？” ### 答案生成 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -最相关的块会被组装成一个结构化的提示，包含明确的指令、检索到的上下文和用户的问题。模型读取这些特定块，并基于这些信息回答 —— 它只能使用面前的信息，这避免了幻觉。 +最相关的文本块被组装成一个结构化提示，其中包括明确指令、检索到的上下文和用户的问题。模型读取这些特定的块并基于这些信息进行回答 —— 它只能使用当前呈现的信息，从而防止幻觉生成。 ```java String context = matches.stream() @@ -237,51 +238,51 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -下图展示了这个组装过程 —— 从搜索步骤中得分最高的块被注入提示模板，`OpenAiOfficialChatModel` 生成一个有根据的答案： +下图展示了这种组装的实际效果 —— 搜索步骤中得分最高的文本块被注入到提示模板中，`OpenAiOfficialChatModel` 生成基于上下文的回答： -上下文组装 +Context Assembly -*此图展示得分最高的块如何被组装成一个结构化提示，使模型能够基于你的数据生成有根据的答案。* +*此图显示了如何将得分最高的文本块组装成结构化提示，允许模型从您的数据生成有依据的回答。* -## 运行应用程序 +## 运行应用 **验证部署：** -确保根目录存在 `.env` 文件，并包含 Azure 凭据（在模块01中创建）。从模块目录（`03-rag/`）运行： +确保根目录下存在 `.env` 文件并包含 Azure 凭据（在模块01中创建）。在模块目录下（`03-rag/`）运行： **Bash:** ```bash -cat ../.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +cat ../.env # 应显示 AZURE_OPENAI_ENDPOINT，API_KEY，DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +Get-Content ..\.env # 应该显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` -**启动应用程序：** +**启动应用：** -> **注意：** 如果你已从根目录使用 `./start-all.sh` 启动所有应用（如模块01所述），本模块已在端口8081运行。你可以跳过下面的启动命令，直接访问 http://localhost:8081。 +> **注意：** 如果您已经在根目录通过 `./start-all.sh` 启动所有应用（如模块01所述），此模块已在 8081 端口运行。可跳过以下启动命令，直接访问 http://localhost:8081。 -**选项1：使用 Spring Boot 仪表板（推荐 VS Code 用户）** +**选项1：使用 Spring Boot 仪表盘（VS Code 用户推荐）** -开发容器包含 Spring Boot 仪表板扩展，提供可视化界面管理所有 Spring Boot 应用。你可以在 VS Code 左侧的活动栏中找到它（查找 Spring Boot 图标）。 +开发容器内含 Spring Boot 仪表盘扩展，提供可视化界面管理所有 Spring Boot 应用。您可以在 VS Code 左侧活动栏找到（查找 Spring Boot 图标）。 -通过 Spring Boot 仪表板，你可以： -- 查看工作区内所有可用的 Spring Boot 应用 +通过 Spring Boot 仪表盘，您可以： +- 查看工作区内所有 Spring Boot 应用 - 一键启动/停止应用 - 实时查看应用日志 - 监控应用状态 -只需点击“rag”旁的播放按钮启动此模块，或一次启动所有模块。 +点击 “rag” 旁的播放按钮启动此模块，或一次启动所有模块。 -Spring Boot 仪表板 +Spring Boot Dashboard -*此截图展示了 VS Code 中的 Spring Boot 仪表板，你可以可视化地启动、停止和监控应用。* +*此截图展示了 VS Code 中的 Spring Boot 仪表盘，您可以直观地启动、停止和监控应用。* **选项2：使用 shell 脚本** -启动所有 Web 应用（模块 01-04）： +启动所有 web 应用（模块01-04）： **Bash:** ```bash @@ -295,7 +296,7 @@ cd .. # 从根目录 .\start-all.ps1 ``` -或者只启动本模块： +或者只启动此模块： **Bash:** ```bash @@ -309,9 +310,9 @@ cd 03-rag .\start.ps1 ``` -两个脚本都会自动从根 `.env` 文件加载环境变量，如果 JAR 文件不存在则会构建。 +这两个脚本都会自动从根目录的 `.env` 文件加载环境变量，并且如果 JAR 文件不存在则构建它们。 -> **注意：** 如果你想先手动构建所有模块再启动： +> **注意：** 如果您愿意先手动构建所有模块再启动： > > **Bash:** > ```bash @@ -325,7 +326,7 @@ cd 03-rag > mvn clean package -DskipTests > ``` -在浏览器打开 http://localhost:8081。 +在浏览器打开 http://localhost:8081 。 **停止应用：** @@ -339,99 +340,99 @@ cd .. && ./stop-all.sh # 所有模块 **PowerShell:** ```powershell .\stop.ps1 # 仅此模块 -# 或 +# 或者 cd ..; .\stop-all.ps1 # 所有模块 ``` -## 使用应用程序 +## 使用应用 该应用提供文档上传和提问的网页界面。 -RAG 应用界面 +RAG Application Interface -*此截图展示了 RAG 应用界面，你可以上传文档并提问。* +*此截图展示 RAG 应用界面，您可以上传文档并提问。* ### 上传文档 -从上传文档开始 —— TXT 文件最适合测试。此目录中提供了一个 `sample-document.txt`，包含 LangChain4j 功能、RAG 实现和最佳实践的信息 —— 非常适合测试系统。 +首先上传文档——测试时推荐使用 TXT 文件。本目录下提供了一个 `sample-document.txt`，包含 LangChain4j 功能、RAG 实现和最佳实践等信息，适合测试系统。 -系统会处理你的文档，将其拆分成块，并为每个块创建嵌入。这一切在你上传时自动进行。 +系统会处理您的文档，将其拆分为多个文本块，并为每个块创建嵌入。这一过程在上传时自动完成。 ### 提问 -现在，针对文档内容提具体问题。尝试问一些文档中清晰阐述的事实性问题。系统会搜索相关的块，将它们包含在提示中，并生成答案。 +现在就可以针对文档内容提出具体问题。尝试提出文档中明确表述的事实性问题。系统会搜索相关块，将它们包含到提示中，并生成答案。 -### 检查来源参考 +### 检查来源引用 -注意每个答案都会包含来源参考和相似度分数。这些分数（0 到 1）显示每个块与问题的相关度。分数越高，匹配越好。这样你可以依据原始资料验证答案。 +注意每个答案都包含带有相似度分数的来源引用。这些分数（0到1）表明每个文本块与您的问题的相关度。分数越高表示匹配越好。这样您可以核对答案与原始材料的一致性。 -RAG 查询结果 +RAG Query Results -*此截图展示查询结果，其中包括生成的答案、来源参考及每个检索块的相关度得分。* +*此截图展示查询结果，包括生成的答案、来源引用及每个检索块的相关度分数。* ### 试验不同问题 尝试不同类型的问题： -- 具体事实：“主要话题是什么？” -- 比较：“X 和 Y 有什么区别？” -- 总结：“总结关于 Z 的要点” +- 具体事实：“主要主题是什么？” +- 比较：“X 和 Y 有何区别？” +- 总结：“请总结关于 Z 的关键点” -观察相关度分数如何根据你的问题与文档内容的匹配程度变化。 +观察相关度分数如何随问题与文档内容匹配度的变化而变化。 ## 关键概念 ### 分块策略 -文档被拆分成每块 300 令牌，重叠 30 令牌。该平衡确保每块有足够上下文且块大小适中，方便在提示中包含多个块。 +文档被拆分为 300 令牌的文本块，且相邻块之间有30令牌的重叠。这种平衡确保每个块含有足够上下文且保持较小，方便在提示中包含多个块。 ### 相似度分数 -每个检索到的块都带有一个 0 到 1 之间的相似度分数，表示它与用户问题的匹配程度。下图可视化了分数范围及系统如何利用它们过滤结果： +每个检索到的块都附带一个0到1之间的相似度分数，表示它与用户问题的匹配程度。下图展示分数范围及系统如何利用它们过滤结果： -相似度分数 +Similarity Scores -*此图显示了从 0 到 1 的分数范围，设置了 0.5 的最低阈值过滤无关块。* +*此图显示分数从0到1，设定了0.5的最低阈值过滤无关文本块。* -分数范围： -- 0.7-1.0：高度相关，完全匹配 -- 0.5-0.7：相关，提供良好上下文 -- 低于 0.5：被过滤，差异太大 +分数范围如下： +- 0.7-1.0：高度相关，精确匹配 +- 0.5-0.7：相关，有良好上下文 +- 低于0.5：被过滤，差异较大 -系统仅检索超过最低阈值的块以保证质量。 +系统仅检索高于最低阈值的块以确保质量。 -嵌入在语义清晰聚类时效果很好，但也有盲点。下图示常见失败模式 —— 块太大导致向量模糊，块太小缺少上下文，模糊术语指向多重聚类，且准确匹配检索（ID、零件号）嵌入完全不起作用： +嵌入表现良好时意义清晰聚类，但其也有局限。下图展示常见失败模式——块过大导致向量模糊，块过小缺乏上下文，歧义词指向多个簇，且精确匹配查找（如ID、零件号）根本不适用嵌入： -嵌入失败模式 +Embedding Failure Modes -*此图展示常见嵌入失败模式：块太大，块太小，模糊术语指向多个聚类，及基于ID的精确匹配。* +*此图展示嵌入常见失败模式：块过大、块过小、歧义词指向多个簇，以及像ID的精确匹配查找。* ### 内存存储 -出于简易考虑，本模块使用内存存储。重启应用后上传的文档会丢失。生产系统使用持久化向量数据库，例如 Qdrant 或 Azure AI Search。 +此模块采用内存存储以简化实现。重启应用时，上传的文档会丢失。生产环境一般使用持久化向量数据库，如 Qdrant 或 Azure AI Search。 ### 上下文窗口管理 -每个模型有最大上下文窗口限制。大文档的所有块无法全部包含。系统检索排名前 N 的块（默认 5 个），以在限制内提供足够上下文，实现准确回答。 +每个模型都有最大上下文窗口限制。无法包含大型文档中的所有块。系统取前 N 个最相关的块（默认5个），以控制大小同时提供充足上下文确保回答准确。 -## 何时使用 RAG +## 适用场景 -RAG 并非总是合适。下面的决策指南帮助判断何时 RAG 增值，何时简单方案（例如直接将内容包含在提示中或依赖模型内置知识）就足够： +RAG 并非总是最佳方案。下图决策指南帮助确定何时使用 RAG 增值，何时直接包含内容进提示或依赖模型内置知识即可： -何时使用 RAG +When to Use RAG -*此图展示 RAG 何时增值，与简单方案足以解决的决策指南。* +*此图展示何时使用 RAG 增强效果，何时简单方案足够的决策指南。* ## 后续步骤 -**下一模块：** [04-tools - 使用工具的 AI 代理](../04-tools/README.md) +**下一个模块：** [04-tools - 带工具的 AI 代理](../04-tools/README.md) --- -**导航：** [← 上一：模块 02 - 提示工程](../02-prompt-engineering/README.md) | [返回主页](../README.md) | [下一：模块 04 - 工具 →](../04-tools/README.md) +**导航：** [← 前一模块：模块 02 - 提示工程](../02-prompt-engineering/README.md) | [返回主页](../README.md) | [下一模块：模块 04 - 工具 →](../04-tools/README.md) --- -**免责声明**： -本文件由AI翻译服务[Co-op Translator](https://github.com/Azure/co-op-translator)翻译。虽然我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原文应被视为权威来源。对于重要信息，建议使用专业人工翻译。我们不对因使用本翻译而导致的任何误解或误释承担责任。 +**免责声明**： +本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。 \ No newline at end of file diff --git a/translations/zh-CN/04-tools/README.md b/translations/zh-CN/04-tools/README.md index 1da4fe43f..adb683277 100644 --- a/translations/zh-CN/04-tools/README.md +++ b/translations/zh-CN/04-tools/README.md @@ -1,76 +1,76 @@ -# 模块 04：带工具的 AI 代理 +# Module 04: 带工具的 AI 代理 ## 目录 -- [视频演练](../../../04-tools) -- [你将学到什么](../../../04-tools) -- [先决条件](../../../04-tools) -- [理解带工具的 AI 代理](../../../04-tools) -- [工具调用是如何工作的](../../../04-tools) - - [工具定义](../../../04-tools) - - [决策过程](../../../04-tools) - - [执行](../../../04-tools) - - [响应生成](../../../04-tools) - - [架构：Spring Boot 自动装配](../../../04-tools) -- [工具链](../../../04-tools) -- [运行应用](../../../04-tools) -- [使用应用](../../../04-tools) - - [尝试简单工具使用](../../../04-tools) - - [测试工具链](../../../04-tools) - - [查看对话流程](../../../04-tools) - - [实验不同请求](../../../04-tools) -- [关键概念](../../../04-tools) - - [ReAct 模式（推理与行动）](../../../04-tools) - - [工具描述的重要性](../../../04-tools) - - [会话管理](../../../04-tools) - - [错误处理](../../../04-tools) -- [可用工具](../../../04-tools) -- [何时使用基于工具的代理](../../../04-tools) -- [工具与 RAG 的比较](../../../04-tools) -- [后续步骤](../../../04-tools) - -## 视频演练 - -观看本直播课程，了解本模块入门方法： - -带工具的 AI 代理和 MCP - 直播课程 +- [视频讲解](#视频讲解) +- [你将学到什么](#你将学到什么) +- [前置条件](#前置条件) +- [理解带工具的 AI 代理](#理解带工具的-ai-代理) +- [工具调用是如何工作的](#工具调用是如何工作的) + - [工具定义](#工具定义) + - [决策过程](#决策过程) + - [执行](#执行) + - [响应生成](#响应生成) + - [架构：Spring Boot 自动装配](#架构：spring-boot-自动装配) +- [工具链](#工具链) +- [运行应用](#运行应用) +- [使用应用](#使用应用) + - [尝试简单工具使用](#试用简单工具使用) + - [测试工具链](#测试工具链) + - [查看对话流程](#查看对话流程) + - [尝试不同请求](#尝试不同请求) +- [关键概念](#关键概念) + - [ReAct 模式（推理与行动）](#react-模式（推理和行动）) + - [工具描述的重要性](#工具描述很重要) + - [会话管理](#会话管理) + - [错误处理](#错误处理) +- [可用工具](#可用工具) +- [何时使用基于工具的代理](#何时使用基于工具的代理) +- [工具与 RAG 的对比](#工具与-rag) +- [下一步](#下一步) + +## 视频讲解 + +观看本直播课程，了解如何开始本模块： + +AI Agents with Tools and MCP - Live Session ## 你将学到什么 -到目前为止，你已经学会了如何与 AI 进行对话、有效构造提示并将回答基于文档内容。但仍有一个根本限制：语言模型只能生成文本，不能查询天气、执行计算、访问数据库或与外部系统交互。 +到目前为止，你已经学会如何与 AI 进行对话，如何有效构造提示，以及如何将回答基于你的文档。但仍有一个根本限制：语言模型只能生成文本。它们无法查询天气、执行计算、查询数据库或与外部系统交互。 -工具改变了这一点。通过让模型可以调用的函数，你将它从文本生成器转变成了能够采取行动的代理。模型决定何时需要工具、使用哪个工具、以及传递哪些参数。你的代码执行函数并返回结果，模型将结果纳入回复中。 +工具改变了这一点。通过给模型调用的功能，你将其从一个文本生成器转变成一个可以采取行动的代理。模型决定何时需要工具，使用哪个工具，以及传入什么参数。你的代码执行函数并返回结果，模型将该结果融入其回应中。 -## 先决条件 +## 前置条件 -- 完成 [模块 01 - 介绍](../01-introduction/README.md)（Azure OpenAI 资源已部署） -- 建议完成之前的模块（本模块在“工具与 RAG 比较”中引用了[模块 03 的 RAG 概念](../03-rag/README.md)） -- 根目录下有包含 Azure 凭据的 `.env` 文件（由模块 01 中的 `azd up` 创建） +- 已完成[模块 01 - 介绍](../01-introduction/README.md)（部署了 Azure OpenAI 资源） +- 推荐完成之前的模块（本模块在工具与 RAG 对比中引用了[模块 03 的 RAG 概念](../03-rag/README.md)） +- 在根目录有包含 Azure 凭据的 `.env` 文件（由模块 01 中的 `azd up` 创建） -> **注意：** 如果你还未完成模块 01，请先按照那里的部署说明操作。 +> **注意：** 如果未完成模块 01，请先按部署说明完成。 ## 理解带工具的 AI 代理 -> **📝 注意：** 本模块中“代理”一词指的是带有工具调用能力的 AI 助手。这不同于我们将在[模块 05: MCP](../05-mcp/README.md)中介绍的**Agentic AI** 模式（具有规划、记忆和多步推理的自主代理）。 +> **📝 注意：** 本模块所指 “代理” 是指带有工具调用能力的 AI 助手。这与我们将在[模块 05: MCP](../05-mcp/README.md)中介绍的智能代理模式（具备规划、记忆和多步推理的自主代理）不同。 -没有工具，语言模型只能根据训练数据生成文本。问当前天气，它只能猜测。给它工具后，它可以调用天气 API、执行计算或查询数据库——然后将真实结果融合进回复。 +没有工具时，语言模型只能基于训练数据生成文本。问它当前天气，它只能猜测。给它工具后，它可以调用天气 API，执行计算，或查询数据库——然后将这些真实结果融入回答中。 -无工具 vs 有工具 +Without Tools vs With Tools -*没有工具时模型只能猜测，有了工具它可以调用 API、运行计算并返回实时数据。* +*没有工具，模型只能猜测——有了工具，它可以调用 API、运行计算并返回实时数据。* -配备工具的 AI 代理遵循**推理与行动（ReAct）**模式。模型不仅是回应——它会思考所需内容，调用工具采取行动，观察结果，再决定是继续行动还是给出最终答案： +带工具的 AI 代理遵循推理与行动（ReAct）模式。模型不只是回答——它考虑自己需要什么，调用工具采取行动，观察结果，然后决定是否继续行动或给出最终答案： -1. **推理** —— 代理分析用户的问题，确定需要什么信息 -2. **行动** —— 代理选择合适工具，生成正确参数并调用 -3. **观察** —— 代理接收工具输出，评估结果 -4. **重复或回应** —— 若需更多数据，循环回推理；否则生成自然语言答案 +1. 推理 — 代理分析用户问题，确定所需信息 +2. 行动 — 代理选择合适的工具，生成正确参数并调用它 +3. 观察 — 代理接收工具输出并评估结果 +4. 重复或回答 — 如果需要更多数据，循环回步骤；否则生成自然语言回答 -ReAct 模式 +ReAct Pattern -*ReAct 循环——代理推理应做何事，调用工具行动，观察结果，循环直到能给出最终答案。* +*ReAct 循环——代理推理该做什么，通过调用工具行动，观察结果，循环直到能给出最终答案。* -这一过程自动完成。你定义工具及其描述，模型负责决策何时如何使用它们。 +这完全自动进行。你定义工具及其描述，模型处理何时如何使用。 ## 工具调用是如何工作的 @@ -78,7 +78,7 @@ [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -你定义带有清晰描述和参数规格的函数。模型在系统提示中看到这些描述，并理解每个工具的功能。 +你定义具有清晰描述和参数规范的函数。模型在系统提示中看到这些描述，理解每个工具的功能。 ```java @Component @@ -86,7 +86,7 @@ public class WeatherTool { @Tool("Get the current weather for a location") public String getCurrentWeather(@P("Location name") String location) { - // 您的天气查询逻辑 + // 你的天气查询逻辑 return "Weather in " + location + ": 22°C, cloudy"; } } @@ -96,135 +96,135 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// Assistant 由 Spring Boot 自动连接： +// Assistant 由 Spring Boot 自动连接: // - ChatModel Bean -// - 来自 @Component 类的所有 @Tool 方法 +// - 所有来自 @Component 类的 @Tool 方法 // - 用于会话管理的 ChatMemoryProvider ``` -下图拆解了每个注解，展示各部分如何帮助 AI 理解何时调用工具以及传递哪些参数： +下图详细解析每个注解，展示它们如何帮助 AI 理解何时调用工具以及传递什么参数： -工具定义解析 +Anatomy of Tool Definitions -*工具定义构成——@Tool 告诉 AI 何时使用，@P 描述每个参数，@AiService 在启动时自动装配所有内容。* +*工具定义结构——@Tool 告诉 AI 何时使用，@P 描述每个参数，@AiService 启动时自动装配。* -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天试试：** 打开 [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java)，问： -> - “如何集成像 OpenWeatherMap 这样真实的天气 API 替代模拟数据？” -> - “什么样的工具描述能帮助 AI 正确使用它？” -> - “我如何在工具实现中处理 API 错误和速率限制？” +> **🤖 试试用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java)，询问： +> - “如何集成像 OpenWeatherMap 这类真实天气 API 而非模拟数据？” +> - “怎样的工具描述能帮助 AI 正确使用工具？” +> - “如何在工具实现中处理 API 错误和速率限制？” ### 决策过程 -当用户问“西雅图的天气怎么样？”，模型不会随机选择工具。它将用户意图与所有工具描述进行匹配评分，选出最相关的。然后生成带正确参数的结构化函数调用——此例中将 `location` 设置为 `"Seattle"`。 +当用户问“西雅图的天气怎样？”，模型不会随机选工具。它将用户意图与每个工具描述对比，评估相关性，选出最匹配的。然后生成结构化函数调用和正确参数——本例中将 `location` 设置为 `"Seattle"`。 -如果没有工具匹配请求，模型就基于自身知识回答。若多工具匹配，则选择最具体的。 +如果无工具匹配请求，模型则退回自身知识回答。若多个匹配，则选择最具体的。 -AI 如何决定使用哪个工具 +How the AI Decides Which Tool to Use -*模型对每个可用工具评估与用户意图的相关性，选择最佳匹配——这也是为何写清晰具体的工具描述至关重要。* +*模型评估所有可用工具与用户意图的匹配度，选出最合适工具——所以写清晰具体的工具描述很重要。* ### 执行 [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot 自动装配带有 `@AiService` 注解的接口和所有注册工具，LangChain4j 自动执行工具调用。幕后，一个完整的工具调用通过六个阶段流转——从用户的自然语言问题至自然语言回答： +Spring Boot 使用声明式 `@AiService` 接口自动装配所有注册的工具，LangChain4j 自动执行工具调用。幕后，完整调用流程经过六个阶段——从用户自然语言问题，到返回自然语言回答： -工具调用流程 +Tool Calling Flow -*端到端流程——用户提问，模型选择工具，LangChain4j 执行调用，模型将结果融合为自然语言回复。* +*端到端流程——用户提问，模型选工具，LangChain4j 执行，模型将结果融入自然回答中。* -如果你运行过模块 00 里的 [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java)，你已经见过该模式——`Calculator` 工具的调用完全一样。下图序列图展示了该示例背后的调用细节： +幕后，`AiServices` 为任何工具运行相同的调用循环——这里以简单 `Calculator` 举例。下图顺序图精确展示底层发生的事情： -工具调用序列图 +Tool Calling Sequence Diagram -*快速入门演示中的工具调用循环——`AiServices` 发送信息和工具模式到 LLM，LLM 回复函数调用如 `add(42, 58)`，LangChain4j 在本地执行 `Calculator` 方法并返回结果供最终回答。* +*调用循环——`AiServices` 将消息和工具模式发送给 LLM，LLM 以函数调用响应如 `add(42, 58)`，LangChain4j 本地执行，结果回传最终回答。* -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天试试：** 打开 [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java)，问： -> - “ReAct 模式如何运作，为什么对 AI 代理有效？” -> - “代理如何决定使用哪个工具及调用顺序？” -> - “若工具执行失败怎么办？如何稳健处理错误？” +> **🤖 试试用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打开 [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java)，询问： +> - “ReAct 模式是如何工作的？为什么它对 AI 代理有效？” +> - “代理如何决定用哪个工具，执行顺序如何？” +> - “如果工具执行失败，会发生什么？如何稳健处理错误？” ### 响应生成 -模型接收天气数据，格式化为自然语言回应用户。 +模型接收天气数据，生成自然语言响应给用户。 ### 架构：Spring Boot 自动装配 -本模块使用 LangChain4j 的 Spring Boot 集成和声明式 `@AiService` 接口。启动时，Spring Boot 发现所有带 `@Component` 的包含 `@Tool` 方法的组件，你的 `ChatModel` Bean，以及 `ChatMemoryProvider`，然后将它们零样板代码组装成单一 `Assistant` 接口。 +本模块使用 LangChain4j 的 Spring Boot 集成，通过声明式 `@AiService` 接口。启动时，Spring Boot 发现所有包含 `@Tool` 方法的 `@Component`、你的 `ChatModel` bean 和 `ChatMemoryProvider`，并将它们全部装配成单个 `Assistant` 接口，无需样板代码。 -Spring Boot 自动装配架构 +Spring Boot Auto-Wiring Architecture -*@AiService 接口将 ChatModel、工具组件和内存提供者绑定在一起——Spring Boot 自动处理所有装配。* +*@AiService 接口将 ChatModel、工具组件和内存提供者连接起来——Spring Boot 自动管理装配。* -下面是完整请求生命周期的序列图——从 HTTP 请求，经控制器、服务和自动装配的代理，直到工具执行及返回： +下面是完整请求生命周期的顺序图——从 HTTP 请求，经控制器、服务和自动装配代理，直到工具执行与返回： -Spring Boot 工具调用序列 +Spring Boot Tool Calling Sequence -*完整的 Spring Boot 请求流程——HTTP 请求通过控制器和服务到自动装配的 Assistant 代理，代理自动调度 LLM 和工具调用。* +*完整 Spring Boot 请求生命周期——HTTP 请求流经控制器和服务，传到自动装配的 Assistant 代理，自动编排 LLM 与工具调用。* -此方法的关键优势： +此方法主要优势： -- **Spring Boot 自动装配**——自动注入 ChatModel 和工具 -- **@MemoryId 模式**——自动进行基于会话的内存管理 -- **单例实例**——Assistant 只创建一次，性能更佳 -- **类型安全执行**——Java 方法直接调用，支持类型转换 -- **多轮交互编排**——自动处理工具链调用 -- **零样板代码**——无需手写 `AiServices.builder()` 或维护内存哈希映射 +- **Spring Boot 自动装配**——ChatModel 和工具自动注入 +- **@MemoryId 模式**——自动的基于会话的内存管理 +- 单实例——Assistant 仅创建一次，性能更佳 +- 类型安全执行——Java 方法直接调用并类型转换 +- 多轮编排——自动处理工具链调用 +- 零样板代码——无需手写 `AiServices.builder()` 或内存 HashMap -替代方案（手动调用 `AiServices.builder()`）代码量更大且失去 Spring Boot 集成优势。 +手动写 `AiServices.builder()` 代码量更大，且缺少 Spring Boot 集成的好处。 ## 工具链 -**工具链**——基于工具的代理的真正威力在于单个问题需要调用多个工具。问“西雅图的天气是多少华氏度？”时，代理自动串联两个工具：先调用 `getCurrentWeather` 获得摄氏度温度，再将其传给 `celsiusToFahrenheit` 转换——全在一次对话中完成。 +工具链——基于工具的代理真正强大之处在于当单个问题需用多个工具。问“西雅图的天气是多少华氏度？”时，代理会自动串联两个工具：先调用 `getCurrentWeather` 取摄氏温度，再将结果传给 `celsiusToFahrenheit` 转换——均在一次对话轮中完成。 -工具链示例 +Tool Chaining Example -*工具链实战——代理先调用 getCurrentWeather，再把摄氏结果传给 celsiusToFahrenheit，最后给出综合答案。* +*工具链实战——代理先调用 getCurrentWeather，然后将摄氏结果传给 celsiusToFahrenheit，并给出合并回答。* -**优雅失败**——请求查询模拟数据中不存在的城市天气时，工具返回错误消息，AI 解释无法帮助而非崩溃。工具失败安全。下图对比了这两种方式——正确错误处理时代理捕获异常并提供帮助回答，否则整个应用崩溃： +优雅失败——请求模拟数据中不存在的城市天气。工具返回错误信息，AI 说明无法帮助，而不是崩溃。工具失败安全。下图对比两种处理方式——正确错误处理时，代理捕获异常并给出有用解释；否则整个应用崩溃： -错误处理流程 +Error Handling Flow -*工具调用失败时，代理捕获错误并给予帮助而非程序崩溃。* +*当工具失败，代理捕获错误并以帮助性解释回应，而不是崩溃。* -这一切都在单轮对话中自动完成，代理自主编排多次调用。 +这一切在一次对话轮内完成。代理自主编排多个工具调用。 ## 运行应用 **验证部署：** -确保根目录存在包含 Azure 凭据的 `.env` 文件（模块 01 创建）。从本模块目录 (`04-tools/`) 运行： +确保根目录有包含 Azure 凭据的 `.env` 文件（模块 01 中创建）。在本模块目录（`04-tools/`）运行： **Bash:** ```bash -cat ../.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +cat ../.env # 应该显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` **PowerShell:** ```powershell -Get-Content ..\.env # 应显示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +Get-Content ..\.env # 应该显示 AZURE_OPENAI_ENDPOINT, API_KEY, DEPLOYMENT ``` **启动应用：** -> **注意：** 如果已用根目录下的 `./start-all.sh` 启动所有应用（见模块 01 说明），本模块已在端口 8084 运行。你可以跳过下面启动命令，直接访问 http://localhost:8084。 +> **注意：** 如果之前已从根目录运行了 `./start-all.sh`（如模块 01 所述），本模块已在 8084 端口运行。可跳过下面启动命令，直接访问 http://localhost:8084 。 -**选项1：使用 Spring Boot 控制面板（推荐 VS Code 用户）** +**选项 1：使用 Spring Boot 仪表板（建议 VS Code 用户）** -开发容器包含 Spring Boot Dashboard 扩展，提供管理所有 Spring Boot 应用的可视界面。你可以在 VS Code 左侧活动栏找到它（寻找 Spring Boot 图标）。 +开发容器包含 Spring Boot 仪表板扩展，提供管理所有 Spring Boot 应用的可视界面。你可在 VS Code 左侧活动栏找到它（Spring Boot 图标）。 -通过 Spring Boot 控制面板，你可以： -- 查看工作区所有可用的 Spring Boot 应用 +通过 Spring Boot 仪表板，你可以： +- 查看工作区内所有可用的 Spring Boot 应用 - 一键启动/停止应用 -- 实时查看应用日志 +- 实时查看日志 - 监控应用状态 -只需点击“tools”旁边的播放按钮即可启动此模块，或者一次启动所有模块。 -以下是在 VS Code 中的 Spring Boot Dashboard 界面： +只需点击 “tools” 旁的播放按钮启动本模块，或一次启动所有模块。 +下面是 VS Code 中 Spring Boot 仪表板的界面示例： Spring Boot Dashboard -*VS Code 中的 Spring Boot Dashboard —— 从一个地方启动、停止和监控所有模块* +*VS Code 中的 Spring Boot 仪表盘 — 从一个地方启动、停止并监控所有模块* **选项 2：使用 shell 脚本** @@ -256,7 +256,7 @@ cd 04-tools .\start.ps1 ``` -两个脚本都会自动从根目录 `.env` 文件加载环境变量，如果 JAR 文件不存在则会构建它们。 +这两个脚本会自动从根目录的 `.env` 文件加载环境变量，并且如果 JAR 不存在会自动构建。 > **注意：** 如果你更喜欢在启动前手动构建所有模块： > @@ -272,9 +272,9 @@ cd 04-tools > mvn clean package -DskipTests > ``` -在浏览器中打开 http://localhost:8084 。 +在浏览器中打开 http://localhost:8084。 -**停止方法：** +**停止：** **Bash:** ```bash @@ -292,96 +292,96 @@ cd ..; .\stop-all.ps1 # 所有模块 ## 使用应用 -该应用提供了一个网页界面，你可以与一个能访问天气和温度转换工具的 AI 代理进行交互。界面如下 —— 包含快速入门示例和用于发送请求的聊天面板： +该应用提供了一个网页界面，你可以在这里与一个拥有天气和温度转换工具访问权限的 AI 代理交互。界面如下所示 — 包括快速启动示例和用于发送请求的聊天面板： AI Agent Tools Interface -*AI 代理工具界面 —— 快速示例和用于与工具交互的聊天界面* +*AI 代理工具界面 - 快速示例和用于与工具互动的聊天界面* -### 试试简单的工具用法 +### 试用简单工具使用 -从一个简单的请求开始：“把 100 华氏度转换成摄氏度”。代理识别出需要使用温度转换工具，调用它传入正确的参数，并返回结果。注意这有多自然 —— 你没有指定用哪个工具或怎么调用它。 +从一个简单请求开始：“将 100 华氏度转换为摄氏度”。代理会识别到需要使用温度转换工具，用正确参数调用该工具并返回结果。注意这感觉多么自然 —— 你没有明确指定用哪个工具，或如何调用它。 ### 测试工具链 -现在试试更复杂的请求：“西雅图的天气如何，并把它转换成华氏度？”观察代理分步处理：它先获取天气（返回摄氏度），识别出需要转换为华氏度，调用转换工具，然后将两个结果合并为一个回答。 +现在尝试更复杂的请求：“西雅图的天气如何，顺便转换为华氏度？”观察代理如何分步骤处理。它首先获取天气（返回摄氏度），然后识别需要转换为华氏度，并调用转换工具，最后将两者结果合并成一个响应。 ### 查看对话流程 -聊天界面会保留对话历史，支持多轮交互。你可以看到之前所有的查询和回复，方便追踪对话，理解代理如何在多轮交流中构建上下文。 +聊天界面会维护对话历史，使你能够进行多轮交流。你可以看到之前的所有查询和回复，方便追踪对话内容并理解代理如何在多次交互中建立上下文。 Conversation with Multiple Tool Calls -*多轮对话展示简单转换、天气查询和工具链* +*多轮对话展示简单转换、天气查询和工具链调用* -### 试用不同请求 +### 尝试不同请求 尝试各种组合： -- 天气查询：“东京天气怎么样？” -- 温度转换：“25°C 是多少开尔文？” -- 组合查询：“查一下巴黎的天气，告诉我是否超过 20°C” +- 天气查询：“东京的天气怎么样？” +- 温度转换：“25°C 等于多少开尔文？” +- 组合查询：“查一下巴黎天气，告诉我是否高于 20°C” -注意代理如何理解自然语言，并映射成合适的工具调用。 +观察代理如何理解自然语言并映射到对应的工具调用。 ## 关键概念 -### ReAct 模式（推理与行动） +### ReAct 模式（推理和行动） -代理在推理（决定做什么）和行动（使用工具）之间交替。这个模式使其能够自主解决问题，而不仅是简单回应指令。 +代理在推理（决定做什么）和行动（使用工具）之间交替。这种模式使其能自主解决问题，而不仅仅是响应指令。 ### 工具描述很重要 -工具描述的质量直接影响代理使用工具的效果。清晰、具体的描述帮助模型理解何时、如何调用每个工具。 +工具描述质量直接影响代理使用工具的效果。清晰、具体的描述帮助模型理解何时以及如何调用每个工具。 ### 会话管理 -`@MemoryId` 注解启用自动的基于会话的内存管理。每个会话 ID 都获得一个 `ChatMemory` 实例，由 `ChatMemoryProvider` bean 管理，因此多个用户可以同时与代理交互，且彼此对话互不干扰。下图展示多用户如何根据会话 ID 路由到隔离的内存存储： +`@MemoryId` 注解开启自动的基于会话的记忆管理。每个会话 ID 拥有自己的 `ChatMemory` 实例，由 `ChatMemoryProvider` bean 管理，从而允许多个用户同时与代理交互而不混淆各自对话。下图展示了基于会话 ID 如何路由到独立的记忆存储： Session Management with @MemoryId -*每个会话 ID 映射到一个独立的对话历史 —— 用户永远看不到彼此的消息。* +*每个会话 ID 映射到独立的对话历史 — 用户间永远看不到彼此的信息。* ### 错误处理 -工具可能出错 — API 超时、参数无效、外部服务中断等。生产环境中的代理需要错误处理，以便模型能解释问题或尝试替代方案，而不是导致整个应用崩溃。当工具抛出异常时，LangChain4j 会捕获它，并将错误信息反馈给模型，模型随后可以用自然语言解释问题。 +工具可能会失败 —— API 超时、参数无效、外部服务故障。生产环境代理需要错误处理，使模型能解释问题或尝试备选方案，而不是让整个应用崩溃。当工具抛出异常时，LangChain4j 会捕获并将错误信息反馈给模型，模型接着以自然语言解释问题。 ## 可用工具 -下图展示了你可以构建的工具生态系统的广泛范围。本模块演示了天气和温度工具，但相同的 `@Tool` 模式适用于任何 Java 方法 —— 从数据库查询到支付处理。 +下图展示了你可以构建的广泛工具生态系统。本模块示范了天气和温度工具，但相同的 `@Tool` 模式适用于任何 Java 方法 —— 从数据库查询到支付处理。 Tool Ecosystem -*任何用 @Tool 注解的 Java 方法都可供 AI 使用 — 该模式可扩展到数据库、API、邮箱、文件操作等。* +*任何用 @Tool 注解的 Java 方法都可供 AI 调用 —— 该模式可扩展至数据库、API、邮件、文件操作等。* ## 何时使用基于工具的代理 -并非所有请求都需要工具。关键在于 AI 是否需要与外部系统交互，或者仅凭自身知识即可回答。下图总结了工具何时有价值，何时不必要： +并非所有请求都需要工具。判断依据是 AI 是否需要与外部系统交互，还是可以凭借自身知识回答。下图总结了工具有用与否的情况： When to Use Tools -*快速决策指南 — 工具适合实时数据、计算和执行动作；通用知识和创造性任务则不需要。* +*简易决策指南 —— 工具适用于实时数据、运算和操作；常识和创造性任务不需要。* ## 工具与 RAG -模块 03 和 04 都扩展了 AI 的能力，但本质上不同。RAG 通过检索文档给模型提供**知识**。工具则通过调用函数提供模型执行**操作**的能力。下图并列比较这两种方法 —— 从各自的工作流程到它们的优缺点： +模块 03 和 04 都扩展了 AI 的能力，但方式截然不同。RAG 通过检索文档为模型提供知识；工具通过调用函数赋予模型执行动作的能力。下图对比两者 —— 从工作流程到各自取舍： Tools vs RAG Comparison -*RAG 从静态文档检索信息 — 工具则执行动作并获取动态实时数据。许多生产系统结合使用两者。* +*RAG 从静态文档中检索信息 —— 工具执行动作并获取动态实时数据。许多生产系统结合二者使用。* -实际上，许多生产系统结合这两种方法：RAG 用于在文档中确定答案，工具用于获取实时数据或执行操作。 +实际上，许多生产系统都会结合这两种方法：用 RAG 让答案基于你的文档，用工具来获取实时数据或执行操作。 -## 后续步骤 +## 下一步 -**下一个模块：** [05-mcp - 模型上下文协议 (MCP)](../05-mcp/README.md) +**下一个模块：** [05-mcp - 模型上下文协议（MCP）](../05-mcp/README.md) --- -**导航：** [← 上一节：模块 03 - RAG](../03-rag/README.md) | [回主目录](../README.md) | [下一节：模块 05 - MCP →](../05-mcp/README.md) +**导航：** [← 上一章：模块 03 - RAG](../03-rag/README.md) | [回到首页](../README.md) | [下一章：模块 05 - MCP →](../05-mcp/README.md) --- -**免责声明**： -本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 进行翻译。虽然我们努力保证译文的准确性，但请注意自动翻译可能存在错误或不准确之处。原始文档的母语版本应被视为权威来源。对于重要信息，建议采用专业人工翻译。对于因使用本翻译而引起的任何误解或错误理解，我们不承担任何责任。 +**免责声明**： +本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。 \ No newline at end of file diff --git a/translations/zh-CN/README.md b/translations/zh-CN/README.md index ddac5142d..d454787f4 100644 --- a/translations/zh-CN/README.md +++ b/translations/zh-CN/README.md @@ -1,149 +1,148 @@ LangChain4j -# LangChain4j 初学者教程 +# LangChain4j 初学者课程 -一门使用 LangChain4j 和 Azure OpenAI GPT-5.2 构建 AI 应用的课程，从基础聊天到 AI 代理。 +使用 LangChain4j 和 Azure OpenAI GPT-5.2 构建 AI 应用的课程，从基础聊天到 AI 代理。 ### 🌐 多语言支持 -#### 通过 GitHub Action 支持（自动且始终最新） +#### 通过 GitHub Action 支持（自动且始终保持最新） -[阿拉伯语](../ar/README.md) | [孟加拉语](../bn/README.md) | [保加利亚语](../bg/README.md) | [缅甸语（缅甸）](../my/README.md) | [中文（简体）](./README.md) | [中文（繁体，香港）](../zh-HK/README.md) | [中文（繁体，澳门）](../zh-MO/README.md) | [中文（繁体，台湾）](../zh-TW/README.md) | [克罗地亚语](../hr/README.md) | [捷克语](../cs/README.md) | [丹麦语](../da/README.md) | [荷兰语](../nl/README.md) | [爱沙尼亚语](../et/README.md) | [芬兰语](../fi/README.md) | [法语](../fr/README.md) | [德语](../de/README.md) | [希腊语](../el/README.md) | [希伯来语](../he/README.md) | [印地语](../hi/README.md) | [匈牙利语](../hu/README.md) | [印度尼西亚语](../id/README.md) | [意大利语](../it/README.md) | [日语](../ja/README.md) | [卡纳达语](../kn/README.md) | [高棉语](../km/README.md) | [韩语](../ko/README.md) | [立陶宛语](../lt/README.md) | [马来语](../ms/README.md) | [马拉雅拉姆语](../ml/README.md) | [马拉地语](../mr/README.md) | [尼泊尔语](../ne/README.md) | [尼日利亚皮钦语](../pcm/README.md) | [挪威语](../no/README.md) | [波斯语（法尔西语）](../fa/README.md) | [波兰语](../pl/README.md) | [葡萄牙语（巴西）](../pt-BR/README.md) | [葡萄牙语（葡萄牙）](../pt-PT/README.md) | [旁遮普语（古鲁姆刻）](../pa/README.md) | [罗马尼亚语](../ro/README.md) | [俄语](../ru/README.md) | [塞尔维亚语（西里尔字母）](../sr/README.md) | [斯洛伐克语](../sk/README.md) | [斯洛文尼亚语](../sl/README.md) | [西班牙语](../es/README.md) | [斯瓦希里语](../sw/README.md) | [瑞典语](../sv/README.md) | [塔加路语（菲律宾语）](../tl/README.md) | [泰米尔语](../ta/README.md) | [泰卢固语](../te/README.md) | [泰语](../th/README.md) | [土耳其语](../tr/README.md) | [乌克兰语](../uk/README.md) | [乌尔都语](../ur/README.md) | [越南语](../vi/README.md) +[阿拉伯语](../ar/README.md) | [孟加拉语](../bn/README.md) | [保加利亚语](../bg/README.md) | [缅甸语 (Myanmar)](../my/README.md) | [中文（简体）](./README.md) | [中文（繁体，香港）](../zh-HK/README.md) | [中文（繁体，澳门）](../zh-MO/README.md) | [中文（繁体，台湾）](../zh-TW/README.md) | [克罗地亚语](../hr/README.md) | [捷克语](../cs/README.md) | [丹麦语](../da/README.md) | [荷兰语](../nl/README.md) | [爱沙尼亚语](../et/README.md) | [芬兰语](../fi/README.md) | [法语](../fr/README.md) | [德语](../de/README.md) | [希腊语](../el/README.md) | [希伯来语](../he/README.md) | [印地语](../hi/README.md) | [匈牙利语](../hu/README.md) | [印尼语](../id/README.md) | [意大利语](../it/README.md) | [日语](../ja/README.md) | [卡纳达语](../kn/README.md) | [高棉语](../km/README.md) | [韩语](../ko/README.md) | [立陶宛语](../lt/README.md) | [马来语](../ms/README.md) | [马拉雅拉姆语](../ml/README.md) | [马拉地语](../mr/README.md) | [尼泊尔语](../ne/README.md) | [尼日利亚皮钦语](../pcm/README.md) | [挪威语](../no/README.md) | [波斯语 (法尔西)](../fa/README.md) | [波兰语](../pl/README.md) | [葡萄牙语（巴西）](../pt-BR/README.md) | [葡萄牙语（葡萄牙）](../pt-PT/README.md) | [旁遮普语 (古鲁穆奇)](../pa/README.md) | [罗马尼亚语](../ro/README.md) | [俄语](../ru/README.md) | [塞尔维亚语（西里尔字母）](../sr/README.md) | [斯洛伐克语](../sk/README.md) | [斯洛文尼亚语](../sl/README.md) | [西班牙语](../es/README.md) | [斯瓦希里语](../sw/README.md) | [瑞典语](../sv/README.md) | [他加禄语（菲律宾语）](../tl/README.md) | [泰米尔语](../ta/README.md) | [泰卢固语](../te/README.md) | [泰语](../th/README.md) | [土耳其语](../tr/README.md) | [乌克兰语](../uk/README.md) | [乌尔都语](../ur/README.md) | [越南语](../vi/README.md) -> **更喜欢本地克隆？** +> **想本地克隆？** > -> 本仓库包含 50 多种语言翻译，显著增加了下载大小。要不带翻译克隆，请使用稀疏检出： +> 本仓库包含 50 多种语言的翻译，这显著增加了下载大小。若要不带翻译地克隆，请使用稀疏检出： > -> **Bash / macOS / Linux：** +> **Bash / macOS / Linux:** > ```bash > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone '/*' '!translations' '!translated_images' > ``` > -> **CMD（Windows）：** +> **CMD （Windows）:** > ```cmd > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> 这样能让你用更快的下载速度完成课程所需的所有内容。 +> 这样你可以更快地下载到完成课程所需的所有内容。 ## 目录 -1. [快速开始](00-quick-start/README.md) - 快速体验 LangChain4j -2. [介绍](01-introduction/README.md) - 了解 LangChain4j 基础知识 -3. [提示工程](02-prompt-engineering/README.md) - 掌握有效提示设计 -4. [RAG（检索增强生成）](03-rag/README.md) - 构建智能知识库系统 -5. [工具](04-tools/README.md) - 集成外部工具与简单助手 -6. [MCP（模型上下文协议）](05-mcp/README.md) - 使用模型上下文协议（MCP）和代理模块 +1. [介绍](01-introduction/README.md) - 学习 LangChain4j 的基础知识 +2. [Prompt 工程](02-prompt-engineering/README.md) - 掌握高效的提示设计 +3. [RAG（检索增强生成）](03-rag/README.md) - 构建智能的知识库系统 +4. [工具](04-tools/README.md) - 集成外部工具和简单助手 +5. [MCP（模型上下文协议）](05-mcp/README.md) - 使用模型上下文协议 (MCP) 和 Agentic 模块 -### 视频讲解 +### 视频演示 -每个模块配有同伴直播课程，逐步讲解概念和代码。 +每个模块都有配套的直播课程，逐步讲解概念和代码。 | 模块 | 视频 | |--------|-------| -| 01 - 介绍 | [开始使用 LangChain4j](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - 提示工程 | [使用 LangChain4j 进行提示工程](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [LangChain4j 的 RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - 工具 & 05 - MCP | [使用工具和 MCP 构建 AI 代理](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 01 - 介绍 | [使用 LangChain4j 入门](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - Prompt 工程 | [使用 LangChain4j 进行提示工程](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [使用 LangChain4j 的 RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 04 - 工具 & 05 - MCP | [带工具与 MCP 的 AI 代理](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## 学习路线 +## 学习路径 -**刚接触 LangChain4j？** 请参阅 [术语表](docs/GLOSSARY.md) 了解关键术语和概念定义。 +**刚接触 LangChain4j？** 查阅[术语表](docs/GLOSSARY.md)了解关键术语和概念的定义。 > 快速开始 -1. 将此仓库 Fork 到你的 GitHub 账户 -2. 点击 **Code** → **Codespaces** 标签 → **...** → **New with options...** -3. 保持默认设置——这将选择为本课程创建的开发容器 -4. 点击 **Create codespace** -5. 等待 5-10 分钟环境准备就绪 -6. 立刻跳到 [快速开始](./00-quick-start/README.md) 体验入门！ +1. 将此仓库 Fork 到你的 GitHub 账户 +2. 点击 **Code** → **Codespaces** 标签 → **...** → **New with options...** +3. 使用默认设置 – 这将选择为本课程创建的开发容器 +4. 点击 **Create codespace** +5. 等待 5-10 分钟直至环境准备就绪 +6. 直接跳转到 [介绍](./01-introduction/README.md) 开始学习！ -完成模块后，进一步查看[测试指南](docs/TESTING.md)，了解 LangChain4j 测试概念实际应用。 +完成所有模块后，探索[测试指南](docs/TESTING.md)，了解 LangChain4j 的测试概念实操。 -> **注意：** 本培训同时使用 GitHub 模型和 Azure OpenAI。[快速开始](00-quick-start/README.md) 模块使用 GitHub 模型（无需 Azure 订阅），而模块 1-5 使用 Azure OpenAI。若没有，请先通过[免费 Azure 账户](https://aka.ms/azure-free-account) 开始。 +> **注意：** 本培训使用 Azure OpenAI。如果你还没有账户，请使用 [免费 Azure 账户](https://aka.ms/azure-free-account) 开始。 ## 使用 GitHub Copilot 学习 -为了快速开始编码，可以在 GitHub Codespace 或本地 IDE 中打开此项目，配合提供的 devcontainer。本课程使用的 devcontainer 预配置了 GitHub Copilot，实现 AI 配对编程。 +要快速开始编写代码，可在 GitHub Codespace 或本地 IDE 中使用提供的 devcontainer 打开本项目。本课程使用的 devcontainer 预配置了 GitHub Copilot，便于 AI 配对编程。 -每个代码示例都包含你可以向 GitHub Copilot 提问的建议问题，帮助你加深理解。可在以下位置查找 💡/🤖 提示： +每个代码示例中都包含你可以问 GitHub Copilot 的建议问题，帮助你加深理解。留意以下位置的 💡/🤖 提示： -- **Java 文件头部** - 针对每个示例的特定问题 -- **模块 README** - 代码示例后的探索提示 +- **Java 文件头部** - 针对每个示例的特定问题 +- **模块 README** - 代码示例后探索问题 -**使用方法：** 打开任意代码文件，向 Copilot 询问建议问题。它拥有完整代码库上下文，能够解释、扩展及建议替代方案。 +**使用方法：** 打开任意代码文件并向 Copilot 提问建议问题。它拥有完整的代码库上下文，能解释、扩展或建议替代方案。 -想了解更多？请查看[用于 AI 配对编程的 Copilot](https://aka.ms/GitHubCopilotAI)。 +想了解更多？浏览 [AI 配对编程的 Copilot](https://aka.ms/GitHubCopilotAI)。 - -## 额外资源 +## 其他资源 ### LangChain -[![面向初学者的 LangChain4j](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![面向初学者的 LangChain.js](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![面向初学者的 LangChain](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j 初学者](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js 初学者](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain 初学者](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- ### Azure / Edge / MCP / 代理 -[![面向初学者的 AZD](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![面向初学者的 Edge AI](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![面向初学者的 MCP](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![面向初学者的 AI 代理](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AZD 初学者](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI 初学者](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP 初学者](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI 代理 初学者](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### 生成式 AI 系列 -[![面向初学者的生成式 AI](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![生成式 AI 初学者](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![生成式 AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![生成式 AI（Java）](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![生成式 AI（JavaScript）](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +[![生成式 AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![生成式 AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- ### 核心学习 -[![面向初学者的机器学习](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![面向初学者的数据科学](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![面向初学者的 AI](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![面向初学者的网络安全](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![面向初学者的网页开发](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![面向初学者的物联网](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![面向初学者的XR开发](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![机器学习 初学者](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![数据科学 初学者](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![人工智能 初学者](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![网络安全 初学者](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- - + ### Copilot 系列 -[![AI 配对编程 Copilot](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET Copilot](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot 冒险](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## 获取帮助 -如果遇到困难或有任何关于构建 AI 应用的问题，加入： +如果您遇到困难或对构建 AI 应用有任何疑问，请加入： [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -如果在构建过程中有产品反馈或错误，访问： +如果您在构建过程中有产品反馈或遇到错误，请访问： [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) -## 许可 +## 许可证 -MIT 许可证 - 详情见 [LICENSE](../../LICENSE) 文件。 +MIT 许可证 - 详情请参阅 [LICENSE](../../LICENSE) 文件。 --- -**免责声明**： -本文档使用 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 进行翻译。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。应以本文件的原始语言版本为权威来源。对于重要信息，建议使用专业人工翻译。对于因使用本翻译而产生的任何误解或错误解释，我们概不负责。 +**免责声明**： +本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。 \ No newline at end of file diff --git a/translations/zh-CN/docs/GLOSSARY.md b/translations/zh-CN/docs/GLOSSARY.md index 3626129fc..ee9a26ced 100644 --- a/translations/zh-CN/docs/GLOSSARY.md +++ b/translations/zh-CN/docs/GLOSSARY.md @@ -2,69 +2,69 @@ ## 目录 -- [核心概念](../../../docs) -- [LangChain4j 组件](../../../docs) -- [AI/ML 概念](../../../docs) -- [防护措施](../../../docs) -- [提示工程](../../../docs) -- [RAG（检索增强生成）](../../../docs) -- [代理与工具](../../../docs) -- [Agentic 模块](../../../docs) -- [模型上下文协议（MCP）](../../../docs) -- [Azure 服务](../../../docs) -- [测试与开发](../../../docs) - -课程中使用的术语和概念快速参考。 +- [核心概念](#核心概念) +- [LangChain4j 组件](#langchain4j-组件) +- [AI/ML 概念](#aiml-概念) +- [防护机制](#防护机制) +- [提示工程](#prompt-engineering---module-02) +- [RAG（检索增强生成）](#rag-retrieval-augmented-generation---module-03) +- [代理与工具](#agents-and-tools---module-04) +- [代理模块](#agentic-module---module-05) +- [模型上下文协议（MCP）](#model-context-protocol-mcp---module-05) +- [Azure 服务](#azure-services---module-01) +- [测试与开发](#testing-and-development---testing-guide) + +课程中使用术语和概念的快速参考。 ## 核心概念 -**AI 代理** - 使用 AI 进行推理和自主行动的系统。 [模块 04](../04-tools/README.md) +**AI Agent** - 使用 AI 进行推理和自主行动的系统。[模块 04](../04-tools/README.md) -**链** - 一系列操作，输出作为下一步的输入。 +**Chain** - 输出作为下一步输入的操作序列。 -**分块** - 将文档拆分成较小的片段。典型大小：300-500 令牌，带重叠。 [模块 03](../03-rag/README.md) +**Chunking** - 将文档拆分为更小部分。典型为 300-500 令牌，带重叠。[模块 03](../03-rag/README.md) -**上下文窗口** - 模型可处理的最大令牌数。GPT-5.2：40 万令牌（最多 27.2 万输入，12.8 万输出）。 +**Context Window** - 模型可处理的最大令牌数。GPT-5.2：400K 令牌（最多 272K 输入，128K 输出）。 -**嵌入** - 表示文本意义的数值向量。 [模块 03](../03-rag/README.md) +**Embeddings** - 表示文本含义的数值向量。[模块 03](../03-rag/README.md) -**函数调用** - 模型生成结构化请求以调用外部函数。 [模块 04](../04-tools/README.md) +**Function Calling** - 模型生成结构化请求调用外部函数。[模块 04](../04-tools/README.md) -**幻觉** - 模型生成错误但看似合理的信息。 +**Hallucination** - 模型生成错误但看似合理的信息。 -**提示** - 语言模型的文本输入。 [模块 02](../02-prompt-engineering/README.md) +**Prompt** - 语言模型的文本输入。[模块 02](../02-prompt-engineering/README.md) -**语义搜索** - 基于意义的搜索，使用嵌入而非关键词。 [模块 03](../03-rag/README.md) +**Semantic Search** - 利用嵌入进行基于意义的搜索，而非基于关键词。[模块 03](../03-rag/README.md) -**有状态 vs 无状态** - 无状态：无记忆。 有状态：保持对话历史。 [模块 01](../01-introduction/README.md) +**Stateful vs Stateless** - 无状态：无记忆；有状态：维护对话历史。[模块 01](../01-introduction/README.md) -**令牌** - 模型处理的基本文本单元。影响成本和限制。 [模块 01](../01-introduction/README.md) +**Tokens** - 模型处理的基本文本单位。影响成本和限制。[模块 01](../01-introduction/README.md) -**工具链** - 顺序执行工具，输出指导下一次调用。 [模块 04](../04-tools/README.md) +**Tool Chaining** - 顺序执行工具，输出用作下一个调用的信息。[模块 04](../04-tools/README.md) ## LangChain4j 组件 **AiServices** - 创建类型安全的 AI 服务接口。 -**OpenAiOfficialChatModel** - OpenAI 及 Azure OpenAI 模型的统一客户端。 +**OpenAiOfficialChatModel** - OpenAI 和 Azure OpenAI 模型的统一客户端。 -**OpenAiOfficialEmbeddingModel** - 使用 OpenAI Official 客户端创建嵌入（支持 OpenAI 和 Azure OpenAI）。 +**OpenAiOfficialEmbeddingModel** - 使用 OpenAI 官方客户端创建嵌入（支持 OpenAI 和 Azure OpenAI）。 -**ChatModel** - 语言模型核心接口。 +**ChatModel** - 语言模型的核心接口。 **ChatMemory** - 维护对话历史。 -**ContentRetriever** - 查找与 RAG 相关的文档块。 +**ContentRetriever** - 查找 RAG 所需的相关文档块。 -**DocumentSplitter** - 将文档拆分成块。 +**DocumentSplitter** - 将文档拆分为块。 -**EmbeddingModel** - 将文本转为数值向量。 +**EmbeddingModel** - 将文本转换为数值向量。 **EmbeddingStore** - 存储和检索嵌入。 **MessageWindowChatMemory** - 维护最近消息的滑动窗口。 -**PromptTemplate** - 使用 `{{variable}}` 占位符创建可复用的提示。 +**PromptTemplate** - 创建带有 `{{variable}}` 占位符的可重用提示。 **TextSegment** - 带元数据的文本块。用于 RAG。 @@ -74,159 +74,157 @@ ## AI/ML 概念 -**少样本学习** - 在提示中提供示例。 [模块 02](../02-prompt-engineering/README.md) +**Few-Shot Learning** - 在提示中提供示例。[模块 02](../02-prompt-engineering/README.md) -**大型语言模型（LLM）** - 在大量文本数据上训练的 AI 模型。 +**Large Language Model (LLM)** - 基于大量文本数据训练的 AI 模型。 -**推理努力** - GPT-5.2 控制思考深度的参数。 [模块 02](../02-prompt-engineering/README.md) +**Reasoning Effort** - GPT-5.2 控制推理深度的参数。[模块 02](../02-prompt-engineering/README.md) -**温度** - 控制输出随机性。低=确定性，高=创造性。 +**Temperature** - 控制输出随机程度。低=确定性，高=创造性。 -**向量数据库** - 用于嵌入的专用数据库。 [模块 03](../03-rag/README.md) +**Vector Database** - 用于嵌入的专用数据库。[模块 03](../03-rag/README.md) -**零样本学习** - 无需示例即可执行任务。 [模块 02](../02-prompt-engineering/README.md) +**Zero-Shot Learning** - 无示例完成任务。[模块 02](../02-prompt-engineering/README.md) -## 防护措施 - [模块 00](../00-quick-start/README.md) +## 防护机制 -**纵深防御** - 多层安全方法，结合应用级防护与提供商安全过滤器。 +**Defense in Depth** - 多层安全方法，结合应用层防护和提供商安全过滤。 -**硬性阻断** - 提供商对严重内容违规返回 HTTP 400 错误。 +**Hard Block** - 提供商因严重内容违规返回 HTTP 400 错误。 -**输入防护** - LangChain4j 接口，用于验证用户输入在到达 LLM 前。提前阻断有害提示，节省成本和延迟。 +**InputGuardrail** - LangChain4j 接口，用于在输入进入 LLM 前验证用户输入，节省成本和延迟。 -**输入防护结果** - 防护验证返回类型：`success()` 或 `fatal("原因")`。 +**InputGuardrailResult** - 防护验证返回类型：`success()` 或 `fatal("reason")`。 -**输出防护** - 验证 AI 响应后再返回给用户的接口。 +**OutputGuardrail** - 验证 AI 回复的接口，防止违规输出给用户。 -**提供商安全过滤器** - AI 提供商内置的内容过滤器（如 GitHub Models），在 API 层捕捉违规。 +**Provider Safety Filters** - AI 提供商（如 Azure OpenAI）内置的内容过滤器，API 级别捕捉违规。 -**软拒绝** - 模型礼貌地拒绝回答且不抛出错误。 +**Soft Refusal** - 模型礼貌拒绝回答，且不抛出错误。 ## 提示工程 - [模块 02](../02-prompt-engineering/README.md) -**思路链** - 逐步推理以提升准确性。 +**Chain-of-Thought** - 分步推理以提高准确度。 -**约束输出** - 强制指定格式或结构。 +**Constrained Output** - 强制特定格式或结构。 -**高热情** - GPT-5.2 用于彻底推理的模式。 +**High Eagerness** - GPT-5.2 的全面推理模式。 -**低热情** - GPT-5.2 用于快速回答的模式。 +**Low Eagerness** - GPT-5.2 的快速回答模式。 -**多轮对话** - 在多轮交流中保持上下文。 +**Multi-Turn Conversation** - 跨轮保持上下文。 -**角色提示** - 通过系统消息设置模型角色身份。 +**Role-Based Prompting** - 通过系统消息设定模型角色。 -**自我反思** - 模型评估并改进自己的输出。 +**Self-Reflection** - 模型自我评估并改进输出。 -**结构化分析** - 固定的评估框架。 +**Structured Analysis** - 固定的评估框架。 -**任务执行模式** - 计划 → 执行 → 总结。 +**Task Execution Pattern** - 计划 → 执行 → 总结。 ## RAG（检索增强生成） - [模块 03](../03-rag/README.md) -**文档处理流水线** - 加载 → 分块 → 嵌入 → 存储。 +**Document Processing Pipeline** - 加载 → 拆分 → 嵌入 → 存储。 -**内存嵌入存储** - 用于测试的非持久存储。 +**In-Memory Embedding Store** - 用于测试的非持久存储。 -**RAG** - 结合检索与生成以增强回答依据。 +**RAG** - 将检索与生成结合以增强响应可靠性。 -**相似度分数** - 衡量语义相似度的分数（0-1）。 +**Similarity Score** - 表示语义相似度的分数（0-1）。 -**来源引用** - 关于检索内容的元数据。 +**Source Reference** - 检索内容的元数据信息。 ## 代理与工具 - [模块 04](../04-tools/README.md) -**@Tool 注解** - 标记 Java 方法为可由 AI 调用的工具。 +**@Tool 注解** - 标记 Java 方法为 AI 可调用工具。 -**ReAct 模式** - 推理 → 行动 → 观察 → 重复。 +**ReAct Pattern** - 推理 → 行动 → 观察 → 重复。 -**会话管理** - 为不同用户分离上下文。 +**Session Management** - 不同用户分离上下文管理。 -**工具** - AI 代理可调用的功能。 +**Tool** - AI 代理可调用的功能。 -**工具描述** - 工具用途和参数文档。 +**Tool Description** - 工具用途和参数的文档说明。 -## Agentic 模块 - [模块 05](../05-mcp/README.md) +## 代理模块 - [模块 05](../05-mcp/README.md) -**@Agent 注解** - 标记接口为 AI 代理，使用声明式行为定义。 +**@Agent 注解** - 标记接口为 AI 代理，支持声明式行为定义。 -**代理监听器** - 通过 `beforeAgentInvocation()` 和 `afterAgentInvocation()` 监控代理执行的钩子。 +**Agent Listener** - 通过 `beforeAgentInvocation()` 和 `afterAgentInvocation()` 监控代理执行的挂钩。 -**Agentic 范围** - 代理使用 `outputKey` 存储结果的共享内存，供下游代理消费。 +**Agentic Scope** - 共享内存，代理使用 `outputKey` 存储输出以供下游代理使用。 **AgenticServices** - 使用 `agentBuilder()` 和 `supervisorBuilder()` 创建代理的工厂。 -**条件工作流** - 基于条件路由至不同专业代理。 +**Conditional Workflow** - 基于条件路由到不同领域专家代理。 -**人机协作** - 添加人工检查点以批准或审查内容的工作流模式。 +**Human-in-the-Loop** - 增加人工检查站点的工作流程模式，用于审批或内容审核。 **langchain4j-agentic** - 用于声明式代理构建的 Maven 依赖（实验性）。 -**循环工作流** - 迭代执行代理直到满足条件（例如质量分 ≥ 0.8）。 +**Loop Workflow** - 代理执行迭代，直到满足条件（例如质量评分 ≥ 0.8）。 -**outputKey** - 代理注解参数，指定结果在 Agentic 范围中的存储位置。 +**outputKey** - 代理注解参数，指定结果存储在 Agentic Scope 的位置。 -**并行工作流** - 多代理同时运行，处理独立任务。 +**Parallel Workflow** - 同时运行多个代理处理独立任务。 -**响应策略** - 主管如何形成最终答案：LAST（最后）、SUMMARY（汇总）或 SCORED（评分）。 +**Response Strategy** - 主管如何制定最终答案：LAST、SUMMARY 或 SCORED。 -**顺序工作流** - 按顺序执行代理，输出传递下一步。 +**Sequential Workflow** - 依次执行代理，输出用于下一步骤。 -**主管代理模式** - 高级代理模式，主管 LLM 动态决定调用哪些子代理。 +**Supervisor Agent Pattern** - 高级代理模式，主管 LLM 动态决定调用哪些子代理。 ## 模型上下文协议（MCP） - [模块 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j 中用于 MCP 集成的 Maven 依赖。 +**langchain4j-mcp** - LangChain4j 中 MCP 集成的 Maven 依赖。 -**MCP** - 模型上下文协议：连接 AI 应用与外部工具的标准。一次构建，到处使用。 +**MCP** - 模型上下文协议：连接 AI 应用与外部工具的标准。一次构建，处处可用。 -**MCP 客户端** - 连接 MCP 服务器以发现和使用工具的应用。 +**MCP Client** - 连接 MCP 服务器以发现并使用工具的应用。 -**MCP 服务器** - 通过 MCP 暴露工具的服务，提供清晰描述和参数 schema。 +**MCP Server** - 通过 MCP 暴露工具，并提供清晰描述和参数模式的服务。 **McpToolProvider** - LangChain4j 组件，封装 MCP 工具供 AI 服务和代理使用。 -**McpTransport** - MCP 通信接口，包含 Stdio 和 HTTP 实现。 +**McpTransport** - MCP 通信接口。实现包括 Stdio 和 HTTP。 -**Stdio 传输** - 通过 stdin/stdout 的本地进程传输。适合访问文件系统或命令行工具。 +**Stdio Transport** - 通过 stdin/stdout 进行本地进程传输。适用于文件系统访问或命令行工具。 -**StdioMcpTransport** - LangChain4j 实现，作为子进程启动 MCP 服务器。 +**StdioMcpTransport** - LangChain4j 实现，将 MCP 服务器作为子进程启动。 -**工具发现** - 客户端查询服务器可用工具及其描述和 schema。 +**Tool Discovery** - 客户端查询服务器，获取可用工具及其描述和模式。 ## Azure 服务 - [模块 01](../01-introduction/README.md) -**Azure AI Search** - 支持向量功能的云搜索。 [模块 03](../03-rag/README.md) +**Azure AI Search** - 具有向量功能的云搜索服务。[模块 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - 部署 Azure 资源。 +**Azure Developer CLI (azd)** - 部署 Azure 资源的命令行工具。 -**Azure OpenAI** - 微软企业 AI 服务。 +**Azure OpenAI** - 微软的企业级 AI 服务。 -**Bicep** - Azure 基础设施即代码语言。 [基础设施指南](../01-introduction/infra/README.md) +**Bicep** - Azure 基础设施即代码语言。[基础架构指南](../01-introduction/infra/README.md) -**部署名称** - Azure 中模型部署的名称。 +**Deployment Name** - Azure 中模型部署名称。 -**GPT-5.2** - 具有推理控制的最新 OpenAI 模型。 [模块 02](../02-prompt-engineering/README.md) +**GPT-5.2** - 最新的 OpenAI 模型，支持推理控制。[模块 02](../02-prompt-engineering/README.md) ## 测试与开发 - [测试指南](TESTING.md) -**开发容器** - 容器化开发环境。 [配置](../../../.devcontainer/devcontainer.json) +**Dev Container** - 容器化开发环境。[配置](../../../.devcontainer/devcontainer.json) -**GitHub Models** - 免费 AI 模型试验场。 [模块 00](../00-quick-start/README.md) +**In-Memory Testing** - 使用内存存储进行测试。 -**内存测试** - 使用内存存储进行测试。 - -**集成测试** - 使用真实基础设施的测试。 +**Integration Testing** - 使用真实基础设施进行测试。 **Maven** - Java 构建自动化工具。 **Mockito** - Java 模拟框架。 -**Spring Boot** - Java 应用框架。 [模块 01](../01-introduction/README.md) +**Spring Boot** - Java 应用框架。[模块 01](../01-introduction/README.md) --- -**免责声明**： -本文件使用AI翻译服务【Co-op Translator】（https://github.com/Azure/co-op-translator）翻译完成。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。原始语言的文件应被视为权威来源。对于重要信息，建议采用专业人工翻译。我们不对因使用此翻译而产生的任何误解或误释承担责任。 +**免责声明**： +本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。 \ No newline at end of file diff --git a/translations/zh-CN/docs/TESTING.md b/translations/zh-CN/docs/TESTING.md index b1fbc04aa..aa8794024 100644 --- a/translations/zh-CN/docs/TESTING.md +++ b/translations/zh-CN/docs/TESTING.md @@ -2,19 +2,19 @@ ## 目录 -- [快速开始](../../../docs) -- [测试涵盖内容](../../../docs) -- [运行测试](../../../docs) -- [在 VS Code 中运行测试](../../../docs) -- [测试模式](../../../docs) -- [测试理念](../../../docs) -- [后续步骤](../../../docs) +- [快速开始](#快速开始) +- [测试涵盖内容](#测试涵盖内容) +- [运行测试](#运行测试) +- [在 VS Code 中运行测试](#在-vs-code-中运行测试) +- [测试模式](#测试模式) +- [测试理念](#测试理念) +- [下一步](#下一步) -本指南将带您了解演示如何测试 AI 应用程序的测试步骤，无需 API 密钥或外部服务。 +本指南将带您了解展示如何测试 AI 应用程序的测试，这些测试不需要 API 密钥或外部服务。 ## 快速开始 -运行所有测试，只需一个命令： +使用以下单个命令运行所有测试： **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -当所有测试通过时，您应该看到如下截图中的输出——测试运行无一失败。 +当所有测试通过时，您应该看到如下截图中的输出——测试零失败运行。 Successful Test Results -*成功执行测试，显示所有测试全部通过且无失败* +*成功的测试执行，显示所有测试均通过且无失败* ## 测试涵盖内容 -本课程关注于本地运行的**单元测试**。每个测试都演示了一个具体的 LangChain4j 概念的独立实现。下面的测试金字塔展示了单元测试所在的位置——它们构成了快速、可靠的基础，构建您其余测试策略的基石。 +本课程专注于在本地运行的单元测试。每个测试都展示了一个特定的 LangChain4j 概念的隔离演示。下图的测试金字塔展示了单元测试的位置——它们构成了快速、可靠的基础，其他测试策略在此基础上构建。 Testing Pyramid -*测试金字塔展示单元测试（快速，隔离）、集成测试（真实组件）和端到端测试之间的平衡。本课程覆盖单元测试。* +*测试金字塔显示单元测试（快速、隔离）、集成测试（真实组件）和端到端测试之间的平衡。本培训涵盖单元测试。* -| 模块 | 测试数 | 重点 | 关键文件 | +| 模块 | 测试数量 | 关注点 | 关键文件 | |--------|-------|-------|-----------| -| **00 - 快速开始** | 6 | 提示模板与变量替换 | `SimpleQuickStartTest.java` | -| **01 - 介绍** | 8 | 会话内存和有状态聊天 | `SimpleConversationTest.java` | -| **02 - 提示工程** | 12 | GPT-5.2 模式、积极性等级、结构化输出 | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | 文档导入、嵌入、相似度搜索 | `DocumentServiceTest.java` | +| **01 - 介绍** | 8 | 会话内存与有状态对话 | `SimpleConversationTest.java` | +| **02 - 提示工程** | 12 | GPT-5.2 模式、急切度等级、结构化输出 | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | 文档摄取、嵌入、相似度搜索 | `DocumentServiceTest.java` | | **04 - 工具** | 12 | 函数调用与工具链 | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | 带有 Stdio 传输的模型上下文协议 | `SimpleMcpTest.java` | +| **05 - MCP** | 8 | 使用 stdio 传输的模型上下文协议 | `SimpleMcpTest.java` | ## 运行测试 -**在根目录运行所有测试：** +**从根目录运行所有测试：** **Bash:** ```bash @@ -68,14 +67,14 @@ mvn --% test **Bash:** ```bash cd 01-introduction && mvn test -# 或者从根目录开始 +# 或从根目录 mvn test -pl 01-introduction ``` **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# 或来自根目录 +# 或者从根目录开始 mvn --% test -pl 01-introduction ``` @@ -95,41 +94,41 @@ mvn --% test -Dtest=SimpleConversationTest **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#应该维护对话历史 +mvn test -Dtest=SimpleConversationTest#应该保持对话历史 ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#应保持对话历史 +mvn --% test -Dtest=SimpleConversationTest#应该保持对话历史 ``` ## 在 VS Code 中运行测试 -如果您使用 Visual Studio Code，测试资源管理器提供了图形界面，用于运行和调试测试。 +如果您使用 Visual Studio Code，测试资源管理器提供了一个用于运行和调试测试的图形界面。 VS Code Test Explorer -*VS Code 测试资源管理器显示所有 Java 测试类和单个测试方法的测试树* +*VS Code 测试资源管理器显示测试树，包含所有 Java 测试类和单独测试方法* -**在 VS Code 中运行测试的方法：** +**在 VS Code 中运行测试步骤：** -1. 点击活动栏中的烧杯图标以打开测试资源管理器 +1. 点击活动栏中的烧杯图标打开测试资源管理器 2. 展开测试树查看所有模块和测试类 -3. 点击任何测试旁的播放按钮单独运行 +3. 点击任意测试旁的播放按钮单独运行该测试 4. 点击“运行所有测试”执行整个测试套件 -5. 右键点击任意测试选择“调试测试”，可设置断点并逐步调试代码 +5. 右击任何测试选择“调试测试”设置断点并逐步调试代码 -测试资源管理器用绿色对勾显示通过测试，测试失败时提供详细的错误信息。 +测试资源管理器用绿色勾号表示通过的测试，失败时会提供详细的失败信息。 ## 测试模式 ### 模式 1：测试提示模板 -最简单的模式是测试提示模板，而不调用任何 AI 模型。您验证变量替换是否正确，提示是否格式化符合预期。 +最简单的模式是测试提示模板，不调用任何 AI 模型。您验证变量替换是否正确，并确保提示格式符合预期。 Prompt Template Testing -*测试提示模板演示变量替换流程：带占位符的模板 → 应用变量值 → 验证格式化输出* +*测试提示模板显示变量替换流程：包含占位符的模板 → 应用值 → 验证格式化输出* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -此测试位于 `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`。 - -**运行方法：** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#测试提示模板格式化 -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#测试提示模板格式化 -``` +此模式验证变量替换是否正确，提示是否格式化如预期—无须 API 密钥或模型调用。 ### 模式 2：模拟语言模型 -测试会话逻辑时，使用 Mockito 创建返回预设响应的假模型。这使测试快速、免费且结果确定。 +测试会话逻辑时，使用 Mockito 创建返回预设响应的假模型。这使测试快速、免费且确定性强。 Mock vs Real API Comparison -*对比显示为何测试首选模拟：快速、免费、确定且无需 API 密钥* +*比较说明为何测试首选模拟：它们快速、免费、确定性高，无需 API 密钥* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 条用户消息 + 3 条 AI 消息 + assertThat(history).hasSize(6); // 3 个用户 + 3 个 AI 消息 } } ``` -此模式出现在 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`。模拟确保行为一致，便于验证内存管理的正确性。 +此模式见于 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`。模拟确保行为一致，便于验证内存管理正确。 ### 模式 3：测试会话隔离 -会话内存必须将多个用户分开存储。此测试验证对话不会混淆上下文。 +会话内存必须保持多用户隔离。此测试验证对话不会混淆上下文。 Conversation Isolation -*测试会话隔离展示不同用户的独立内存存储，防止上下文混合* +*测试会话隔离，显示不同用户的独立内存存储，防止上下文混淆* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -每个会话维持独立的历史记录。在生产系统中，这种隔离对多用户应用至关重要。 +每个会话维护独立历史。生产系统中，这种隔离对于多用户应用至关重要。 ### 模式 4：独立测试工具 -工具是 AI 可以调用的函数。直接测试它们，确保无论 AI 决策如何，工具都能正确工作。 +工具是 AI 可以调用的函数。直接测试它们，确保其工作正常，无论 AI 决策如何。 Tools Testing -*独立测试工具显示模拟工具执行，无 AI 调用，以验证业务逻辑* +*独立测试工具，显示模拟工具执行，无 AI 调用验证业务逻辑* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -这些测试来自 `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`，验证工具逻辑，无需 AI 参与。链式调用示例展示一个工具的输出如何作为下一个工具的输入。 +这些测试来自 `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`，验证工具逻辑不依赖 AI。链式示例演示一个工具的输出如何作为另一个工具的输入。 ### 模式 5：内存中 RAG 测试 -传统 RAG 系统需要向量数据库和嵌入服务。内存中模式允许您在无外部依赖的情况下测试整个管道。 +RAG 系统传统上依赖向量数据库和嵌入服务。内存中模式让您无需外部依赖即可测试整个流程。 In-Memory RAG Testing -*内存中 RAG 测试工作流显示文档解析、嵌入存储和相似度搜索，无需数据库* +*内存中 RAG 测试工作流，展示文档解析、嵌入存储和相似度搜索，无需数据库* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -此测试来自 `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`，在内存中创建文档，验证拆分及元数据处理。 +此测试来自 `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`，在内存中创建文档，验证分块和元数据处理。 ### 模式 6：MCP 集成测试 -MCP 模块测试使用 stdio 传输的模型上下文协议集成。这些测试验证您的应用是否能以子进程方式启动并与 MCP 服务器通信。 +MCP 模块测试使用 stdio 传输的模型上下文协议集成。这些测试验证您的应用程序可以作为子进程启动 MCP 服务器并通信。 `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` 中的测试验证 MCP 客户端行为。 -**运行方法：** +**运行：** **Bash:** ```bash @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## 测试理念 -测试您的代码，而非 AI。您的测试应通过检查提示如何构造、内存如何管理、工具如何执行来验证您编写的代码。AI 响应不稳定， 不应用于断言。问自己，提示模板是否正确替换变量，而非 AI 是否给出正确答案。 +测试您的代码，而非 AI。您的测试应通过检查提示构造方式、内存管理和工具执行来验证代码。AI 响应各异，不应成为测试断言的一部分。问自己提示模板是否正确替换了变量，而不是 AI 是否给出了正确答案。 -语言模型使用模拟。它们是外部依赖，速度慢、费用高且结果不确定。模拟让测试速度以毫秒级而非秒级，免费无 API 成本，且每次结果一致。 +对语言模型使用模拟。它们是外部依赖，速度慢、费用高且非确定性。模拟让测试快速（毫秒级而非秒级），免费且结果确定。 -保持测试独立。每个测试应自行搭建数据环境，不依赖其他测试，且完成后清理环境。测试通过与否不依赖执行顺序。 +保持测试独立。每个测试应自行设置数据，不依赖其他测试，并自行清理。无论执行顺序如何，测试都应通过。 -测试边界情况，超出理想路径。尝试空输入、超大输入、特殊字符、无效参数和边界条件。它们通常揭示正常使用未发现的漏洞。 +测试边界情况，超出正常路径。尝试空输入、超大输入、特殊字符、无效参数和边界条件。这些往往揭露正常使用不易发现的漏洞。 -使用描述性命名。对比 `shouldMaintainConversationHistoryAcrossMultipleMessages()` 与 `test1()`。前者告诉您具体测试内容，更易定位故障。 +使用描述性名称。比较 `shouldMaintainConversationHistoryAcrossMultipleMessages()` 和 `test1()`。前者准确说明测试内容，调试失败更容易。 -## 后续步骤 +## 下一步 -理解测试模式后，请深入学习各模块： +既然您了解了测试模式，深入学习各模块： -- **[00 - 快速开始](../00-quick-start/README.md)** - 从提示模板基础开始 -- **[01 - 介绍](../01-introduction/README.md)** - 了解会话内存管理 -- **[02 - 提示工程](../02-prompt-engineering/README.md)** - 精通 GPT-5.2 提示模式 +- **[01 - 介绍](../01-introduction/README.md)** - 学习会话内存管理 +- **[02 - 提示工程](../02/prompt-engineering/README.md)** - 掌握 GPT-5.2 提示模式 - **[03 - RAG](../03-rag/README.md)** - 构建检索增强生成系统 -- **[04 - 工具](../04-tools/README.md)** - 实现函数调用与工具链 +- **[04 - 工具](../04-tools/README.md)** - 实现函数调用和工具链 - **[05 - MCP](../05-mcp/README.md)** - 集成模型上下文协议 -各模块的 README 提供对本处测试概念的详细解释。 +每个模块的自述文件详细讲解此处测试的概念。 --- -**导航：** [← 返回主页](../README.md) +**导航：** [← 返回主页面](../README.md) --- -**免责声明**： -本文件使用AI翻译服务[Co-op Translator](https://github.com/Azure/co-op-translator)翻译。虽然我们努力确保准确性，但请注意自动翻译可能包含错误或不准确之处。原文应被视为权威来源。对于重要信息，建议采用专业人工翻译。本公司对因使用本翻译而产生的任何误解或误释不承担责任。 +**免责声明**： +本文件由 AI 翻译服务 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻译完成。尽管我们力求准确，但请注意，自动翻译可能包含错误或不准确之处。原始语言版文件应视为权威来源。对于重要信息，建议使用专业人工翻译。我们对因使用本翻译而产生的任何误解或误释不承担责任。 \ No newline at end of file diff --git a/translations/zh-HK/.co-op-translator.json b/translations/zh-HK/.co-op-translator.json index c5e749012..b4ca29a5d 100644 --- a/translations/zh-HK/.co-op-translator.json +++ b/translations/zh-HK/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "zh-HK" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T19:28:44+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T14:07:38+00:00", "source_file": "01-introduction/README.md", "language_code": "zh-HK" }, @@ -18,20 +18,20 @@ "language_code": "zh-HK" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T19:31:10+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T14:04:13+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "zh-HK" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T19:32:36+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T14:06:58+00:00", "source_file": "03-rag/README.md", "language_code": "zh-HK" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:44:19+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T14:05:58+00:00", "source_file": "04-tools/README.md", "language_code": "zh-HK" }, @@ -54,8 +54,8 @@ "language_code": "zh-HK" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:39:21+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T14:03:10+00:00", "source_file": "README.md", "language_code": "zh-HK" }, @@ -72,14 +72,14 @@ "language_code": "zh-HK" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T19:35:40+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T14:04:35+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "zh-HK" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T19:36:24+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T14:05:05+00:00", "source_file": "docs/TESTING.md", "language_code": "zh-HK" } diff --git a/translations/zh-HK/00-quick-start/README.md b/translations/zh-HK/00-quick-start/README.md deleted file mode 100644 index e40039e27..000000000 --- a/translations/zh-HK/00-quick-start/README.md +++ /dev/null @@ -1,386 +0,0 @@ -# Module 00: 快速開始 - -## 目錄 - -- [簡介](../../../00-quick-start) -- [什麼是 LangChain4j？](../../../00-quick-start) -- [LangChain4j 依賴項](../../../00-quick-start) -- [先決條件](../../../00-quick-start) -- [設置](../../../00-quick-start) - - [1. 取得您的 GitHub 令牌](../../../00-quick-start) - - [2. 設置您的令牌](../../../00-quick-start) -- [運行範例](../../../00-quick-start) - - [1. 基本聊天](../../../00-quick-start) - - [2. 提示模式](../../../00-quick-start) - - [3. 函數調用](../../../00-quick-start) - - [4. 文件問答 (Easy RAG)](../../../00-quick-start) - - [5. 負責任的 AI](../../../00-quick-start) -- [每個範例展示什麼](../../../00-quick-start) -- [下一步](../../../00-quick-start) -- [故障排除](../../../00-quick-start) - -## 簡介 - -此快速入門旨在讓您盡快開始使用 LangChain4j。它涵蓋了使用 LangChain4j 和 GitHub 模型構建 AI 應用程序的絕對基礎。在接下來的模塊中，您將切換到 Azure OpenAI 和 GPT-5.2，並深入探討每個概念。 - -## 什麼是 LangChain4j？ - -LangChain4j 是一個簡化構建 AI 驅動應用程式的 Java 庫。您不需要處理 HTTP 客戶端和 JSON 解析，而是使用清晰的 Java API。 - -LangChain 中的「鏈」是指將多個組件鏈接起來——您可能會將提示鏈接到模型，再鏈接到解析器，或者將多個 AI 調用連接起來，其中一個輸出用於下一個輸入。這個快速入門聚焦於基礎，在此基礎上再探索更複雜的鏈。 - -LangChain4j Chaining Concept - -*LangChain4j 中的鏈接組件 - 建立連接創造強大 AI 工作流程的積木* - -我們將使用三個核心組件： - -**ChatModel** — AI 模型互動的介面。呼叫 `model.chat("prompt")` 並獲得回應字串。我們使用 `OpenAiOfficialChatModel`，它支援類 OpenAI 端點，如 GitHub 模型。 - -**AiServices** — 創建類型安全的 AI 服務介面。定義方法，使用 `@Tool` 註解它們，LangChain4j 負責協調。AI 會在需要時自動呼叫您的 Java 方法。 - -**MessageWindowChatMemory** — 維護對話歷史。沒有它，每次請求都是獨立的。使用它，AI 會記住先前訊息並跨多輪對話維持上下文。 - -LangChain4j Architecture - -*LangChain4j 架構 - 核心組件協作，為您的 AI 應用提供動力* - -## LangChain4j 依賴項 - -本快速入門在 [`pom.xml`](../../../00-quick-start/pom.xml) 中使用三個 Maven 依賴： - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` 模組提供 `OpenAiOfficialChatModel` 類，用於連接 OpenAI 兼容的 API。GitHub 模型使用相同的 API 格式，因此不需要特別的適配器——只需將基礎 URL 指向 `https://models.github.ai/inference`。 - -`langchain4j-easy-rag` 模組提供自動文件拆分、嵌入和檢索功能，讓您無需手動配置每個步驟即可構建 RAG 應用。 - -## 先決條件 - -**使用開發容器嗎？** Java 和 Maven 已安裝好，您只需要 GitHub 個人訪問令牌。 - -**本地開發：** -- Java 21+，Maven 3.9+ -- GitHub 個人訪問令牌（以下說明） - -> **注意：** 此模塊使用 GitHub 模型的 `gpt-4.1-nano`。請勿修改程式碼中的模型名稱——已配置以適配 GitHub 可用模型。 - -## 設置 - -### 1. 取得您的 GitHub 令牌 - -1. 前往 [GitHub 設定 → 個人訪問令牌](https://github.com/settings/personal-access-tokens) -2. 點選「生成新令牌」 -3. 設置描述名稱（例如：「LangChain4j Demo」） -4. 設置令牌有效期（建議 7 天） -5. 在「帳戶許可權」下找到「Models」並設為「唯讀」 -6. 點選「生成令牌」 -7. 複製並保存令牌——之後無法再次查看 - -### 2. 設置您的令牌 - -**方案一：使用 VS Code（推薦）** - -如果您使用 VS Code，將令牌新增到專案根目錄的 `.env` 文件中： - -如果 `.env` 文件不存在，請複製 `.env.example` 為 `.env`，或在專案根目錄新建一個 `.env` 文件。 - -**示例 `.env` 文件：** -```bash -# 在 /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -然後您只需在資源管理器中右鍵點擊任何示範檔案（例如 `BasicChatDemo.java`），選擇 **「Run Java」**，或使用「執行與偵錯」面板中的啟動配置執行。 - -**方案二：使用終端機** - -將令牌設為環境變數： - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## 運行範例 - -**使用 VS Code：** 只需在資源管理器中右鍵點擊任何示範檔案並選擇 **「Run Java」**，或使用「執行與偵錯」面板的啟動配置（確保您先將令牌加到 `.env` 文件）。 - -**使用 Maven：** 您也可以從命令列執行： - -### 1. 基本聊天 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. 提示模式 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -展示零樣本（zero-shot）、少樣本（few-shot）、思維鏈（chain-of-thought）和角色基礎提示。 - -### 3. 函數調用 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI 會在需要時自動呼叫您的 Java 方法。 - -### 4. 文件問答 (Easy RAG) - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -使用 Easy RAG 的自動嵌入和檢索功能，針對文件提問。 - -### 5. 負責任的 AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -查看 AI 如何透過安全過濾器阻擋有害內容。 - -## 每個範例展示什麼 - -**基本聊天** — [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -從這裡開始了解 LangChain4j 最簡單的使用方式。您將創建一個 `OpenAiOfficialChatModel`，使用 `.chat()` 傳送提示並獲取回應。這展示了基礎：如何使用自定義端點和 API 金鑰初始化模型。理解此模式後，一切更複雜的用法均建立在此之上。 - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試看：** 打開 [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java)，問： -> - 「我如何在此程式碼中從 GitHub 模型切換到 Azure OpenAI？」 -> - 「OpenAiOfficialChatModel.builder() 可以配置哪些其他參數？」 -> - 「如何新增串流回應，而不是等待完整回應？」 - -**提示工程** — [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -您已知道如何與模型交談，現在讓我們深入探討您對模型說什麼。此示範使用相同模型設定，展示五種不同的提示模式。嘗試零樣本提示以直接指令，少樣本提示學習範例，思維鏈提示顯示推理步驟，角色基礎提示設定上下文。您將看到同一模型因提示方式不同而產生截然不同的結果。 - -示範中還展示了提示模板，這是創建帶變數可重用提示的強大方式。下例展示如何使用 LangChain4j `PromptTemplate` 填充變數。AI 將根據指定的目的地和活動回答。 - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試看：** 打開 [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java)，問： -> - 「零樣本與少樣本提示有什麼差異？何時應該使用哪種？」 -> - 「溫度參數如何影響模型回答？」 -> - 「有哪些方法可防止生產環境中的提示注入攻擊？」 -> - 「如何為常見模式創建可重用的 PromptTemplate 物件？」 - -**工具整合** — [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -這是 LangChain4j 強大的地方。您將使用 `AiServices` 創建 AI 助手來呼叫您的 Java 方法。只需用 `@Tool("描述")` 註解方法，LangChain4j 負責其他工作—AI 會根據使用者的問題自動決定何時使用哪個工具。這展示了函數調用，是打造能採取行動而非僅回答問題的 AI 的關鍵技巧。 - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試看：** 打開 [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java)，問： -> - 「@Tool 註解是如何運作的？LangChain4j 背後做了什麼？」 -> - 「AI 能串接多個工具來解決複雜問題嗎？」 -> - 「如果工具拋出異常，該如何處理錯誤？」 -> - 「如何將此計算器示例換成呼叫真實 API？」 - -**文件問答 (Easy RAG)** — [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -這裡展示了使用 LangChain4j 「Easy RAG」 方法的 RAG（檢索增強生成）。文件被加載，自動拆分並嵌入記憶體資料庫，查詢時由內容檢索器供給相關片段給 AI。AI 的回答基於您的文件，而非其一般知識。 - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試看：** 打開 [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)，問： -> - 「RAG 如何防止 AI 幻覺，與使用模型訓練數據相比有何不同？」 -> - 「這個簡易方法與自訂 RAG 管線有什麼差異？」 -> - 「如何擴展以處理多個文件或更大知識庫？」 - -**負責任的 AI** — [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -建立縝密的 AI 安全防護。此示範展示兩層保護合力發揮效用： - -**第 1 部分：LangChain4j 輸入守衛** — 在請求到達 LLM 前阻擋危險提示。建立自訂守衛，檢查禁止關鍵詞或模式。它們在您的程式碼中運行，因此快速且免費。 - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**第 2 部分：供應商安全過濾器** — GitHub 模型有內建過濾器，可捕捉守衛可能錯過的內容。您將看到嚴重違規的硬性封鎖（HTTP 400 錯誤）與 AI 委婉拒絕的軟性拒絕。 - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試看：** 打開 [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java)，問： -> - 「什麼是 InputGuardrail？如何自行製作？」 -> - 「硬性阻擋與軟性拒絕有何差別？」 -> - 「為什麼要同時使用守衛和供應商過濾器？」 - -## 下一步 - -**下一模組：** [01-introduction - LangChain4j 入門](../01-introduction/README.md) - ---- - -**導覽：** [← 返回主頁](../README.md) | [下一步：模組 01 - 簡介 →](../01-introduction/README.md) - ---- - -## 故障排除 - -### 第一次 Maven 編譯 - -**問題：** 初次執行 `mvn clean compile` 或 `mvn package` 時，耗時很長（10-15 分鐘） - -**原因：** Maven 需要在第一次編譯時下載所有專案依賴（Spring Boot、LangChain4j 函式庫、Azure SDK 等）。 - -**解決方案：** 這是正常行為。之後的編譯會快得多，因為依賴已快取至本地。下載速度取決於您的網絡品質。 - -### PowerShell Maven 命令語法 - -**問題：** Maven 命令執行失敗，出現錯誤 `Unknown lifecycle phase ".mainClass=..."` -**原因**：PowerShell 將 `=` 解釋為變量賦值運算符，導致 Maven 屬性語法出錯 - -**解決方法**：在 Maven 命令前使用停止解析運算符 `--%`： - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` 運算符告訴 PowerShell 將所有剩餘參數以字面形式傳遞給 Maven，無需解析。 - -### Windows PowerShell Emoji 顯示 - -**問題**：AI 回應在 PowerShell 中顯示亂碼（例如 `????` 或 `â??`）而非表情符號 - -**原因**：PowerShell 預設編碼不支援 UTF-8 表情符號 - -**解決方法**：執行 Java 應用程式前先運行此命令： -```cmd -chcp 65001 -``` - -這會強制終端使用 UTF-8 編碼。或者，使用 Windows Terminal，其 Unicode 支援更佳。 - -### 偵錯 API 呼叫 - -**問題**：AI 模型驗證失敗、速率限制或非預期回應 - -**解決方法**：範例中包含 `.logRequests(true)` 和 `.logResponses(true)`，會在控制台顯示 API 呼叫，方便排查驗證錯誤、頻率限制或非預期回應。生產環境中移除此設定以減少日誌雜訊。 - ---- - - -**免責聲明**： -本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。儘管我們致力於準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用此翻譯而引起的任何誤解或誤譯承擔責任。 - \ No newline at end of file diff --git a/translations/zh-HK/01-introduction/README.md b/translations/zh-HK/01-introduction/README.md index 234af6d1f..1093474b2 100644 --- a/translations/zh-HK/01-introduction/README.md +++ b/translations/zh-HK/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j 入門 +# Module 01: LangChain4j 入門指南 ## 目錄 -- [影片導覽](../../../01-introduction) -- [你將學到的內容](../../../01-introduction) -- [先決條件](../../../01-introduction) -- [理解核心問題](../../../01-introduction) -- [理解 Tokens](../../../01-introduction) -- [記憶如何運作](../../../01-introduction) -- [本模組如何使用 LangChain4j](../../../01-introduction) -- [部署 Azure OpenAI 基礎設施](../../../01-introduction) -- [在本機執行應用程式](../../../01-introduction) -- [使用應用程式](../../../01-introduction) - - [無狀態聊天（左側面板）](../../../01-introduction) - - [有狀態聊天（右側面板）](../../../01-introduction) -- [後續步驟](../../../01-introduction) +- [影片導覽](#影片導覽) +- [您將學到的內容](#您將學到的內容) +- [前置需求](#前置需求) +- [理解核心問題](#理解核心問題) +- [理解 Tokens](#理解-tokens) +- [記憶如何運作](#記憶如何運作) +- [本示例如何使用 LangChain4j](#本示例如何使用-langchain4j) +- [部署 Azure OpenAI 基礎設施](#部署-azure-openai-基礎設施) +- [在本地運行應用](#在本地運行應用) +- [使用應用程式](#使用應用程式) + - [無狀態聊天（左側面板）](#無狀態聊天（左側面板）) + - [有狀態聊天（右側面板）](#有狀態聊天（右側面板）) +- [下一步](#下一步) ## 影片導覽 -觀看此直播教學，說明如何開始本模組： +觀看此現場教學，說明如何開始使用這個模組： -LangChain4j 開始使用 - 直播教學 +Getting Started with LangChain4j - Live Session -## 你將學到的內容 +## 您將學到的內容 -在快速入門中，你使用 GitHub Models 來發送提示、調用工具、建構 RAG 管線並測試護欄。這些示範展示了可能性—現在我們轉向 Azure OpenAI 與 GPT-5.2，開始建立生產風格的應用程式。本模組聚焦於記憶上下文並維持狀態的對話式 AI — 這是快速入門示範背後用到但沒有解釋的概念。 +這是您使用 LangChain4j 和 Azure OpenAI 的起點。我們從基礎開始，並逐步構建生產級別的應用程式。本模組聚焦於能夠記憶上下文並維持狀態的對話式 AI — 這是後續每個模組所依據的基礎概念。 -整個指南中我們將使用 Azure OpenAI 的 GPT-5.2，因為其進階推理能力讓不同模式的行為更明顯。加入記憶後，你會清楚看到差異。這幫助你更容易理解每個組件帶給應用的價值。 +本指南將使用 Azure OpenAI 的 GPT-5.2 ，因其高級推理能力讓不同模式的行為更明顯。當您加入記憶功能時，差異會非常清楚，這有助於理解每個組件對應用帶來的效果。 -你將建置一個示範兩種模式的應用： +您將建立一個示範兩種模式的應用程式： -**無狀態聊天** — 每次請求彼此獨立。模型不記得之前的訊息。這是你在快速入門中使用過的模式。 +無狀態聊天 - 每個請求獨立，模型不會記得前一條消息。這是最簡單的起點。 -**有狀態對話** — 每次請求都包含對話歷史。模型維持多輪對話的上下文。這才是生產應用所需。 +有狀態對話 - 每個請求包含對話歷史，模型在多輪對話中維持上下文。這是生產應用所需的模式。 -## 先決條件 +## 前置需求 -- 具備 Azure OpenAI 存取權的 Azure 訂閱 -- Java 21, Maven 3.9+ +- 擁有 Azure 訂閱及 Azure OpenAI 存取權限 +- Java 21、Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **注意：** 提供的開發容器內已預裝 Java、Maven、Azure CLI 及 Azure Developer CLI（azd）。 +> **注意：** Java、Maven、Azure CLI 及 Azure Developer CLI (azd) 已於提供的開發容器中預先安裝。 -> **注意：** 本模組使用 Azure OpenAI 上的 GPT-5.2。部署會透過 `azd up` 自動設定，請勿修改程式中的模型名稱。 +> **注意：** 本模組使用 Azure OpenAI 的 GPT-5.2，部署會自動透過 `azd up` 完成，不要修改程式碼中模型名稱。 ## 理解核心問題 -語言模型本身是無狀態的。每次 API 呼叫彼此獨立。如果你說「我的名字是 John」後，再問「我的名字是什麼？」，模型無法得知你剛剛自我介紹過。它將每次請求視為你第一次對話。 +語言模型是無狀態的。每次 API 呼叫皆獨立。如果您先發送「我叫 John」，然後問「我叫什麼名字？」，模型不會知道您剛自我介紹。它視每個請求為您第一次對話。 -這對簡單問答沒問題，但對真正的應用無用。客服機器人需記得你告訴他們的訊息。個人助理需要上下文。任何多輪對話都需要記憶。 +這對於簡單問答還好，但對實際應用毫無幫助。客服機器人需要記住您說過的話。個人助理需要上下文。任何多輪對話都需要記憶。 -下圖比較兩種方式 — 左邊是無狀態呼叫會忘記你的名字；右邊是由 ChatMemory 支援的有狀態呼叫會記得你的名字。 +下圖比較兩種方法 — 左邊是忘記您名字的無狀態呼叫；右邊是由 ChatMemory 支持、有記憶的有狀態呼叫。 -無狀態與有狀態對話 +Stateless vs Stateful Conversations -*無狀態（獨立呼叫）與有狀態（具上下文認知）對話的差異* +*無狀態（獨立呼叫）與有狀態（具上下文感知）對話之差異* ## 理解 Tokens -在深入對話前，理解 Tokens 很重要 — 這是語言模型處理文字的基本單位： +在探索對話之前，了解 tokens 很重要 — 它們是語言模型處理的文本基本單位： -Tokens 說明 +Token Explanation -*範例：文字如何被拆成 tokens — 「I love AI!」變成四個獨立處理單位* +*文本拆解成 tokens 的示例 —「I love AI!」變成 4 個獨立處理單元* -Tokens 為 AI 模型衡量並處理文字的方式。單字、標點符號，甚至空格都可能是 tokens。你的模型有單次可處理的 token 限制（GPT-5.2 為 400,000，包括最多 272,000 輸入 tokens 與 128,000 輸出 tokens）。理解 tokens 有助管理對話長短與費用。 +tokens 是 AI 模型如何度量與處理文字的方式。詞彙、標點甚至空格都能是 token。模型可一次處理的最大 token 數有限制（GPT-5.2 為 400,000，其中最多 272,000 為輸入 tokens，128,000 為輸出 tokens）。理解 tokens 有助於管理對話長度與成本。 ## 記憶如何運作 -聊天記憶解決了無狀態問題，維持對話歷史。發送請求前，框架會加上相關以往訊息。當你問「我的名字是什麼？」，系統實際上會送出完整歷史讓模型看到你之前說過「我的名字是 John」。 +聊天記憶解決無狀態的問題，透過維持對話歷史。在傳送請求前，框架會預先附加相關的前置訊息。當你問「我叫什麼名字？」時，系統其實會傳送整段對話歷史，讓模型能知道你之前說了「我叫 John」。 -LangChain4j 提供自動處理此事的記憶實作。你決定保留多少訊息，框架管理上下文窗口。下圖展示 MessageWindowChatMemory 如何維持一個滑動窗口，保留最近訊息。 +LangChain4j 提供的記憶實作會自動處理這件事。您可設定保留多少條訊息，框架會管理上下文視窗。下圖顯示 MessageWindowChatMemory 如何維持一個滑動的近期訊息視窗。 -記憶窗口概念 +Memory Window Concept -*MessageWindowChatMemory 維持最近訊息的滑動窗口，自動丟棄舊訊息* +*MessageWindowChatMemory 維持一個滑動視窗，自動丟棄舊訊息* -## 本模組如何使用 LangChain4j +## 本示例如何使用 LangChain4j -本模組在快速入門基礎上，整合 Spring Boot 並加入對話記憶。以下是各部分如何組合： +本模組結合 Spring Boot 並增加對話記憶。元件組合如下： -**依賴** — 添加兩個 LangChain4j 庫： +依賴庫 — 新增兩個 LangChain4j 函式庫： ```xml @@ -94,7 +94,7 @@ LangChain4j 提供自動處理此事的記憶實作。你決定保留多少訊 ``` -**聊天模型** — 將 Azure OpenAI 設定為 Spring Bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java))： +聊天模型 — 以 Spring Bean 配置 Azure OpenAI ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java))： ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -Builder 從 `azd up` 設定的環境變數讀取憑證。設定 `baseUrl` 為你的 Azure 終端點，讓 OpenAI 用戶端支援 Azure OpenAI。 +建構器從由 `azd up` 設定的環境變數讀取認證。設置 `baseUrl` 指向您的 Azure 端點，使 OpenAI 用戶端可在 Azure OpenAI 上運作。 -**對話記憶** — 使用 MessageWindowChatMemory 追蹤聊天歷史 ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java))： +對話記憶 — 使用 MessageWindowChatMemory 追蹤聊天歷史 ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java))： ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,14 +124,14 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -用 `withMaxMessages(10)` 建立記憶，保留最舊 10 則訊息。用型別包裝器添加用戶和 AI 訊息：`UserMessage.from(text)` 和 `AiMessage.from(text)`。用 `memory.messages()` 取得歷史，送到模型。服務按對話 ID 維護不同記憶實例，允許多用戶同時聊天。 +建立記憶時用 `withMaxMessages(10)` 限制保留最後 10 條訊息。用強類型包裝類別新增使用者與 AI 訊息：`UserMessage.from(text)` 和 `AiMessage.from(text)`。用 `memory.messages()` 取得歷史，並傳給模型。此服務會依會話 ID 儲存各自的記憶實例，允許多個用戶同時聊天。 -> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試看：** 開啟 [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) 並詢問： -> - 「MessageWindowChatMemory 滿了時怎麼決定丟棄哪些訊息？」 -> - 「可不可以用資料庫代替記憶體中實作，打造自訂記憶存儲？」 -> - 「我要如何加入摘要功能來壓縮舊的對話內容？」 +> **🤖 透過 [GitHub Copilot](https://github.com/features/copilot) 聊天試試：** 打開 [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) 並詢問： +> - 「當視窗滿了時，MessageWindowChatMemory 如何決定丟棄哪些訊息？」 +> - 「我可以實作用資料庫來儲存記憶，取代記憶體儲存嗎？」 +> - 「要如何新增摘要功能來壓縮舊的對話歷史？」 -無狀態聊天端點完全不使用記憶 — 只是像快速入門一樣呼叫 `chatModel.chat(prompt)`。有狀態端點則是加入訊息到記憶，擷取歷史並與每次請求一起送出。模型配置相同，模式不同。 +無狀態聊天端點完全跳過記憶，僅使用 `chatModel.chat(prompt)`，與快速入門相同。有狀態端點則是新增訊息至記憶，取得歷史並包含此上下文，每次請求都帶上。模型配置相同，模式不同。 ## 部署 Azure OpenAI 基礎設施 @@ -144,19 +144,19 @@ azd up # 選擇訂閱和位置（建議使用 eastus2） **PowerShell:** ```powershell cd 01-introduction -azd up # 選擇訂閱及地點（建議使用 eastus2） +azd up # 選擇訂閱和地區（建議使用 eastus2） ``` -> **注意：** 若出現逾時錯誤（`RequestConflict: Cannot modify resource ... provisioning state is not terminal`），只需重新執行 `azd up` 即可。Azure 資源可能還在背景佈建中，重試可待資源達終態時完成部署。 +> **注意：** 遇到逾時錯誤（`RequestConflict: Cannot modify resource ... provisioning state is not terminal`）時，只需再次執行 `azd up`。Azure 資源可能尚在背景配置中，重試後待資源進入終態即可完成部署。 -此命令將會： +這將會： 1. 部署帶有 GPT-5.2 和 text-embedding-3-small 模型的 Azure OpenAI 資源 -2. 自動在專案根目錄建立 `.env` 憑證檔案 -3. 設定所有必需的環境變數 +2. 自動在專案根目錄生成 `.env` 檔案，內含認證 +3. 設置所有必要的環境變數 -**部署遇到問題？** 請查看 [Infrastructure README](infra/README.md)，內容含副域名衝突、手動 Azure Portal 部署步驟及模型配置指引。 +**部署有困難？** 請參閱 [基礎設施說明文件](infra/README.md) ，包括子域名衝突排除手冊、手動 Azure 入口網站部署步驟及模型配置說明。 -**確認部署成功：** +**驗證部署是否成功：** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 ``` -> **注意：** `azd up` 會自動產生 `.env` 檔。若後續需要更新，可手動編輯 `.env` 或重新執行： +> **注意：** `azd up` 指令會自動生成 `.env` 檔案。若需後續更新，可手動編輯 `.env` 檔案或重新生成： > > **Bash:** > ```bash @@ -182,11 +182,11 @@ Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 > .\.azd-env.ps1 > ``` -## 在本機執行應用程式 +## 在本地運行應用 **驗證部署：** -確保根目錄有 `.env` 文件且內含 Azure 憑證。從模組目錄 (`01-introduction/`) 執行： +確認 `.env` 檔案存在根目錄並包含 Azure 認證。在模組目錄 (`01-introduction/`) 執行： **Bash:** ```bash @@ -195,34 +195,34 @@ cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT **PowerShell:** ```powershell -Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +Get-Content ..\.env # 應顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` **啟動應用程式：** -**方法一：使用 Spring Boot 儀表板（推薦 VS Code 使用者）** +**選項 1：使用 Spring Boot 儀表板（推薦 VS Code 用戶）** -開發容器包含 Spring Boot 儀表板擴充套件，提供視覺介面管理所有 Spring Boot 應用。你可在 VS Code 左側活動列找到（尋找 Spring Boot 圖示）。 +開發容器包含 Spring Boot 儀表板擴充，提供視覺化介面管理所有 Spring Boot 應用程式。可於 VS Code 左側活動欄找到（尋找 Spring Boot 圖示）。 -從 Spring Boot 儀表板可以： -- 查看工作區所有 Spring Boot 應用程式 -- 一鍵啟動/停止應用 -- 實時檢視應用日誌 +從 Spring Boot 儀表板您可以： +- 查看工作區中所有可用的 Spring Boot 應用程式 +- 單擊啟動/停止應用程式 +- 即時查看應用程式日誌 - 監控應用狀態 -只需點擊 "introduction" 旁的播放按鈕啟動本模組，或同時啟動所有模組。 +只要點擊「introduction」旁的播放按鈕即可啟動此模組，或同時啟動全部模組。 -Spring Boot 儀表板 +Spring Boot Dashboard -*VS Code 的 Spring Boot 儀表板 — 一處管理全部模組啟動、停止與監控* +*VS Code 中的 Spring Boot 儀表板 — 從一處啟動、停止並監控所有模組* -**方法二：使用 shell 腳本** +**選項 2：使用 shell 腳本** -啟動全部網頁應用（模組 01-04）： +啟動所有網頁應用（模組 01-04）： **Bash:** ```bash -cd .. # 從根目錄開始 +cd .. # 從根目錄 ./start-all.sh ``` @@ -232,7 +232,7 @@ cd .. # 由根目錄開始 .\start-all.ps1 ``` -或只啟動本模組： +或僅啟動本模組： **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -兩個腳本均會自動從根目錄 `.env` 載入環境變數，並於無 JAR 檔時自動編譯。 +兩者腳本都會自動從根目錄 `.env` 載入環境變數，並在不存在 JAR 時進行建置。 -> **注意：** 若想先手動編譯全部模組，再啟動： +> **注意：** 若您想先手動建置所有模組，再啟動： > > **Bash:** > ```bash @@ -262,61 +262,61 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -在瀏覽器開啟 http://localhost:8080 。 +開啟 http://localhost:8080 在瀏覽器。 **停止應用：** **Bash:** ```bash -./stop.sh # 只限此模組 -# 或者 +./stop.sh # 僅此模組 +# 或 cd .. && ./stop-all.sh # 所有模組 ``` **PowerShell:** ```powershell -.\stop.ps1 # 只有此模組 -# 或 +.\stop.ps1 # 只有這個模組 +# 或者 cd ..; .\stop-all.ps1 # 所有模組 ``` ## 使用應用程式 -應用提供網頁介面，左、右兩邊實現不同聊天模式。 +應用提供網頁介面，左、右側並排展示兩種聊天實作。 -應用程式主畫面 +Application Home Screen -*面板同時顯示簡單聊天（無狀態）與對話聊天（有狀態）選項* +*儀表板展示簡易聊天（無狀態）及對話式聊天（有狀態）選項* ### 無狀態聊天（左側面板） -先試試看。問「我的名字是 John」，接著立刻問「我的名字是什麼？」。模型不會記得，因為每則訊息獨立。這展示了基本語言模型整合的核心問題 — 無對話上下文。 +先試這個。問「我叫 John」，接著立即問「我叫什麼名字？」模型不會記得，因為每條訊息皆獨立。這突顯基礎語言模型整合的核心問題 — 無對話上下文。 -無狀態聊天示範 +Stateless Chat Demo -*AI 不會記得上一則訊息中的名字* +*AI 不會記得您先前的名字* ### 有狀態聊天（右側面板） -在這裡試試同樣的順序。說「我的名字是 John」，接著問「我的名字是什麼？」這次它會記得。差異就在 MessageWindowChatMemory — 它會維持對話歷史並附加到每次請求。這就是生產對話式 AI 的工作方式。 +現在在這裡試同樣序列。問「我叫 John」，接著「我叫什麼名字？」這次模型會記得。差異在於 MessageWindowChatMemory — 它維持對話歷史，並隨每次請求附上上下文。這即是生產對話式 AI 的運作方式。 -有狀態聊天示範 +Stateful Chat Demo -*AI 會記得之前對話裡你的名字* +*AI 記得您在對話中較早時說過的名字* -兩個面板使用相同 GPT-5.2 模型，唯一差別是記憶。這清楚表明記憶對應用程式的價值及其必要性。 +左右面板都使用相同 GPT-5.2 模型。唯一差別是是否有記憶。這清楚顯示記憶對應用的重要性及必要性。 -## 後續步驟 +## 下一步 **下一模組：** [02-prompt-engineering - GPT-5.2 的提示工程](../02-prompt-engineering/README.md) --- -**導覽：** [← 上一章：Module 00 - 快速入門](../00-quick-start/README.md) | [回主頁](../README.md) | [下一章：Module 02 - 提示工程 →](../02-prompt-engineering/README.md) +**導覽：** [← 回到首頁](../README.md) | [下一步：模組 02 - 提示工程 →](../02-prompt-engineering/README.md) --- -**免責聲明**： -本文件經由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們致力於提供準確的翻譯，但請注意自動翻譯可能包含錯誤或不準確之處。原文件以其母語版本為權威來源。如涉及重要資訊，建議尋求專業人工翻譯。我們不對因使用此翻譯而產生的任何誤解或誤釋負責。 +**免責聲明**： +本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們致力於確保準確性，但請注意，機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議進行專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤釋承擔責任。 \ No newline at end of file diff --git a/translations/zh-HK/02-prompt-engineering/README.md b/translations/zh-HK/02-prompt-engineering/README.md index f49134341..3aedbc3e3 100644 --- a/translations/zh-HK/02-prompt-engineering/README.md +++ b/translations/zh-HK/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# 模組 02：使用 GPT-5.2 進行提示工程 +# Module 02: 使用 GPT-5.2 進行提示工程 ## 目錄 -- [影片導覽](../../../02-prompt-engineering) -- [你將學到的內容](../../../02-prompt-engineering) -- [先決條件](../../../02-prompt-engineering) -- [了解提示工程](../../../02-prompt-engineering) -- [提示工程基礎](../../../02-prompt-engineering) - - [零次示範提示](../../../02-prompt-engineering) - - [少量示範提示](../../../02-prompt-engineering) - - [思維鏈](../../../02-prompt-engineering) - - [角色導向提示](../../../02-prompt-engineering) - - [提示模板](../../../02-prompt-engineering) -- [進階模式](../../../02-prompt-engineering) -- [執行應用程式](../../../02-prompt-engineering) -- [應用程式截圖](../../../02-prompt-engineering) -- [探索模式](../../../02-prompt-engineering) - - [低與高積極度](../../../02-prompt-engineering) - - [任務執行（工具序言）](../../../02-prompt-engineering) - - [自我反思程式碼](../../../02-prompt-engineering) - - [結構化分析](../../../02-prompt-engineering) - - [多輪對話](../../../02-prompt-engineering) - - [逐步推理](../../../02-prompt-engineering) - - [受限輸出](../../../02-prompt-engineering) -- [你真正學到的是什麼](../../../02-prompt-engineering) -- [下一步](../../../02-prompt-engineering) +- [影片示範](#影片示範) +- [你將學到什麼](#你將學到什麼) +- [前置條件](#前置條件) +- [了解提示工程](#了解提示工程) +- [提示工程基礎](#提示工程基礎) + - [零範例提示](#零範例提示) + - [少範例提示](#少範例提示) + - [思維鏈](#思維鏈) + - [角色式提示](#角色式提示) + - [提示模板](#提示模板) +- [進階範式](#進階範式) +- [執行應用程式](#執行應用程式) +- [應用程式截圖](#應用程式截圖) +- [探索範式](#探索各種模式) + - [低 vs 高積極性](#低積極性-vs-高積極性) + - [任務執行（工具前言）](#任務執行（工具前言）) + - [自我反思程式碼](#自我反思程式碼) + - [結構化分析](#結構化分析) + - [多輪聊天](#多輪對話) + - [逐步推理](#逐步推理) + - [受限輸出](#受限輸出) +- [你真正學到的是什麼](#您真正學到的是什麼) +- [後續步驟](#下一步) -## 影片導覽 +## 影片示範 -觀看此直播課程，說明如何開始此模組： +觀看本直播說明如何開始本模組： -LangChain4j 提示工程 - 直播課程 +Prompt Engineering with LangChain4j - Live Session -## 你將學到的內容 +## 你將學到什麼 -以下圖解概述了你在本模組中將發展的主要主題和技能 — 從提示細化技術到你將遵循的逐步工作流程。 +下圖提供本模組關鍵主題與技能的概觀 — 從提示精煉技術到你將遵循的逐步工作流程。 -你將學到的內容 +What You'll Learn -在之前的模組中，你探索了與 GitHub 模型的基本 LangChain4j 互動，並了解記憶如何使 Azure OpenAI 的對話式 AI 成為可能。現在我們將聚焦於如何提出問題—即提示本身—使用 Azure OpenAI 的 GPT-5.2。你如何結構提示會極大地影響你獲得的回應品質。我們先回顧基本提示技術，然後進入八種利用 GPT-5.2 全面能力的進階模式。 +在上一模組中，你了解記憶如何啟用 Azure OpenAI 的對話 AI。現在我們聚焦於如何問問題 — 即提示本身 — 使用 Azure OpenAI 的 GPT-5.2。你組織提示的方式會大幅影響回應品質。我們先回顧基本提示技術，然後進入八種進階範式，充分利用 GPT-5.2 的能力。 -我們選擇 GPT-5.2 是因為它引入了推理控制——你可以告訴模型在回答前要思考多少。這使不同提示策略更加明顯，幫助你理解何時使用每種方法。我們還能受益於 GPT-5.2 在 Azure 上比 GitHub 模型更少的速率限制。 +我們選用 GPT-5.2 是因為它引入了推理控制 — 你可以指示模型回答前應該思考多少。這使不同提示策略更易區分，也幫助你理解何時使用各種方法。 -## 先決條件 +## 前置條件 -- 完成模組 01（已部署 Azure OpenAI 資源） -- 在根目錄存在 `.env` 檔案並含有 Azure 認證（由模組 01 的 `azd up` 建立） +- 完成 Module 01（已部署 Azure OpenAI 資源） +- 根目錄有含 Azure 認證的 `.env` 檔案（由 Module 01 執行 `azd up` 建立） -> **注意：** 若尚未完成模組 01，請先按照該模組中的部署說明進行。 +> **注意：** 如果未完成 Module 01，請先依該模組中的部署指示操作。 ## 了解提示工程 -本質上，提示工程是抽象指令與精確指令之間的差異，以下比較說明了這點。 +從根本上說，提示工程是模糊指令與精確指令的差異，下面圖示說明了這點。 -什麼是提示工程？ +What is Prompt Engineering? -提示工程是設計輸入文本，使你能持續獲得所需結果。這不僅是提問，更是構造請求，使模型精確理解你想要什麼及如何回應。 +提示工程是設計輸入文字，讓你穩定得到所需結果的技術。它不僅是提問——而是組織請求，使模型精準理解你想要什麼及如何交付。 -想像你在給同事下達指令。「修正錯誤」很模糊。「修正 UserService.java 第 45 行的 null 指針異常，新增 null 檢查」則很具體。語言模型運作亦然 — 明確性與結構同等重要。 +把它想成你給同事指示。“修復錯誤”很模糊。“在 UserService.java 第 45 行因加入空值檢查修復 NullPointerException”就很具體。語言模型也是同理——具體與結構都很重要。 -下圖顯示 LangChain4j 如何融入此流程—透過 SystemMessage 與 UserMessage 構建塊，將你的提示模式連接到模型。 +下圖展示 LangChain4j 在這個過程中的角色 — 將你的提示範式透過 SystemMessage 與 UserMessage 模組連結到模型。 -LangChain4j 的作用 +How LangChain4j Fits -LangChain4j 提供基礎架構—模型連接、記憶與訊息類型—而提示模式則是透過這些基礎架構傳遞的精心結構化文本。關鍵的建構塊是 `SystemMessage`（設定 AI 行為和角色）與 `UserMessage`（承載你的實際請求）。 +LangChain4j 提供基礎架構 — 模型連結、記憶與訊息類型 — 提示範式則是你透過該架構傳送的精心結構化文字。主要建構區塊是 `SystemMessage`（設定 AI 行為與角色）與 `UserMessage`（攜帶你實際請求）。 ## 提示工程基礎 -以下五種核心技術構成有效提示工程的基礎。每種技巧都處理你與語言模型溝通的不同面向。 +下列五種核心技術構成有效提示工程的基石。它們各自解決如何與語言模型溝通的不同面向。 -五種提示工程模式概覽 +Five Prompt Engineering Patterns Overview -在深入本模組的進階模式之前，先回顧五種基礎提示技術。這是每位提示工程師應掌握的基石。如果你已閱覽過[快速入門模組](../00-quick-start/README.md#2-prompt-patterns)，你應該對這些有所了解 — 以下為其概念框架。 +在本模組深入進階範式前，我們先回顧五種基礎提示技巧。這是每個提示工程師應知的基礎建構。 -### 零次示範提示 +### 零範例提示 -最簡單的方法：給模型直接指令，無需範例。模型完全依訓練去理解與執行任務。適用於期望行為明確的簡單請求。 +最簡單的方法：直接給模型指令，無需範例。模型完全依訓練理解與執行任務。這適用於預期行為明確的簡單請求。 -零次示範提示 +Zero-Shot Prompting -*沒有範例的直接指令 — 模型僅從指令推理任務* +*無範例的直接指令 — 模型僅從指令推斷任務* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// 回應:「正面」 +// 回覆：「正面」 ``` -**使用時機：** 簡單分類、直接提問、翻譯或任何模型能無額外指導完成的任務。 +**適用時機：** 簡單分類、直接提問、翻譯或任何模型能無需額外指引執行的任務。 -### 少量示範提示 +### 少範例提示 -提供示例以展示期望模型遵循的模式。模型從範例學習輸入輸出格式並應用於新輸入。對於目標格式或行為不明顯的任務，大幅提升一致性。 +提供示例展示你希望模型採用的模式。模型從示例學習預期的輸入輸出格式，並套用於新輸入。這大幅提升對格式或行為不明顯任務的一致性。 -少量示範提示 +Few-Shot Prompting -*從示例學習 — 模型識別模式並套用至新輸入* +*從範例學習 — 模型辨識模式並應用於新輸入* ```java String prompt = """ @@ -112,15 +112,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**使用時機：** 自訂分類、一致格式、領域特定任務，或零次示範表現不穩定時。 +**適用時機：** 自訂分類、一致格式、特定領域任務，或零範例結果不一致時。 ### 思維鏈 -要求模型逐步展示其推理過程。模型不直接給答案，而是分解問題逐步說明。提升數學、邏輯與多步推理任務的準確度。 +要求模型逐步顯示推理過程。模型不直接給答案，而是拆解問題並明確處理各部分，有助提升數學、邏輯與多步推理任務的準確度。 -思維鏈提示 +Chain of Thought Prompting -*逐步推理 — 將複雜問題分解成明確邏輯步驟* +*逐步推理 — 將複雜問題拆成清楚的邏輯步驟* ```java String prompt = """ @@ -133,15 +133,15 @@ String response = model.chat(prompt); // 模型顯示：15 - 8 = 7，然後 7 + 12 = 19 個蘋果 ``` -**使用時機：** 數學題、邏輯謎題、除錯，或任何展示推理過程能提升準確度與信任的任務。 +**適用時機：** 數學問題、邏輯謎題、除錯或任何展示推理過程能提升精確度與信任的情境。 -### 角色導向提示 +### 角色式提示 -在提問前設定 AI 的角色或身份。此上下文塑造回應的語氣、深度與焦點。「軟件架構師」的建議與「初級開發者」或「安全稽核員」截然不同。 +在提問前設定 AI 的身份或角色。這提供上下文，影響回應的語氣、深度與焦點。軟體架構師、初級開發者或安全審計員給出的建議會不同。 -角色導向提示 +Role-Based Prompting -*設定上下文與角色 — 相同問題因角色不同而獲得不同回答* +*設定上下文與角色 — 相同問題因角色不同而獲不同回答* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**使用時機：** 代碼審查、教學、領域特定分析，或需要根據專業層次或視角定制回應時。 +**適用時機：** 程式碼審查、教學、特定領域分析，或需要依專業層級或角度客製答案時。 ### 提示模板 -創建具可變佔位符的可重用提示。無須每次撰寫新提示，定義模板後只需填入不同數值。LangChain4j 的 `PromptTemplate` 類透過 `{{variable}}` 語法輕鬆實現。 +建立可重複使用的提示，內含變數佔位符。不必每次撰寫新提示，只要定義模板並填入不同值。LangChain4j 的 `PromptTemplate` 類提供簡易的 `{{variable}}` 語法。 -提示模板 +Prompt Templates -*具可變佔位符的可重用提示 — 一個模板，多種使用* +*變數佔位符的可重用提示 — 一個模板，多種用途* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**使用時機：** 需重複查詢且輸入不同、批量處理、構建可重用 AI 工作流，或任何提示結構不變但數據改變的場景。 +**適用時機：** 多次請求不同輸入、批次處理、建立可重用 AI 工作流程，或任何提示結構固定、資料不同的場景。 --- -這五個基礎給你建立了一套適用於大多數提示任務的工具組。本模組餘下部分，基於此構建了**八種進階模式**，充分利用 GPT-5.2 的推理控制、自我評估與結構化輸出功能。 +這五項基礎技術提供大多數提示任務的穩固工具組。本模組接下來將以 八種進階範式 補充，善用 GPT-5.2 的推理控制、自我評估與結構化輸出功能。 -## 進階模式 +## 進階範式 -基礎理論講解完畢，讓我們來看看本模組獨特的八種進階模式。並非所有問題都適用同一策略。有些問題需要快速回應，有些需要深度思考。有些需展現推理過程，有些只求結果。以下每種模式都針對不同場景最佳化——GPT-5.2 的推理控制讓這些差異更為明顯。 +基礎技巧穩固後，讓我們探討讓本模組獨特的八種進階範式。並非所有問題都需相同做法，有些問題需要快速回答，有些需深度思考。有些需顯式推理，有些只要結果。下列每種範式針對不同場景優化，而 GPT-5.2 的推理控制更凸顯出差異。 -八種提示工程模式 +Eight Prompting Patterns -*八種提示工程模式及其使用場景概覽* +八種提示工程範式及其使用案例概覽 -GPT-5.2 增加了另一維度：*推理控制*。下方滑桿展示你如何調整模型的思考努力程度 — 從快速直接回答到深度詳盡分析。 +GPT-5.2 為這些範式帶來另一層面向：推理控制。下方滑桿示範如何調整模型的思考深度 — 從快速直接回答至深度細緻分析。 -GPT-5.2 推理控制 +Reasoning Control with GPT-5.2 -*GPT-5.2 的推理控制讓你指定模型要思考多少 — 從快速直接答覆到深度探索* +*GPT-5.2 的推理控制可指定模型思考量 — 從快速直接回答到深度探索* -**低積極度（快速與聚焦）** — 適用於你想要快速且直接回答的簡單問題。模型只進行最少推理 - 最多兩步。用於計算、查詢或直白問題。 +**低積極性（快速與聚焦）** — 適用簡單問題需快速直接答案。模型推理步驟極少，不超過 2 步。用於運算、查詢或直白問題。 ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **用 GitHub Copilot 探索：** 開啟 [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) 並提問： -> - 「低積極度和高積極度提示模式有何不同？」 -> - 「提示中的 XML 標籤如何幫助結構 AI 回應？」 -> - 「何時應使用自我反思模式而非直接指令？」 +> 💡 **使用 GitHub Copilot 探索：** 開啟 [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) 並提問： +> - 「低積極性與高積極性提示範式有何差異？」 +> - 「提示中的 XML 標籤如何協助組織 AI 回應？」 +> - 「何時應使用自我反思範式而非直接指令？」 -**高積極度（深入與周全）** — 適用於你想要全面分析的複雜問題。模型深入探索並呈現詳細推理。用於系統設計、架構決策或複雜研究。 +**高積極性（深入與全面）** — 適用複雜問題需全面分析。模型徹底探索並展示詳細推理。運用於系統設計、架構決策或複雜研究。 ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**任務執行（逐步進展）** — 適用於多步工作流。模型事先提供計劃，邊工作邊敘述步驟，最後做總結。用於遷移、實作或任何多步驟流程。 +**任務執行（逐步進展）** — 適用多步流程。模型提出明確計劃，工作時逐步解說，最後給出總結。用於遷移、實作或任何多步操作。 ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -思維鏈提示明確要求模型展示推理過程，提升複雜任務的準確度。逐步分解有助於人類與 AI 理解邏輯。 +思維鏈提示明確要求模型展示推理過程，增進複雜任務精確度。逐步拆解助人與 AI 理解邏輯。 -> **🤖 嘗試用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 詢問此模式： -> - 「如何改編任務執行模式以支援長時間運行操作？」 -> - 「生產應用中工具序言結構的最佳實踐是什麼？」 -> - 「如何捕捉並在使用者介面中顯示中間進度更新？」 +> **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 詢問此範式： +> - 「如何調整任務執行範式以應對長時間運行操作？」 +> - 「如何在生產應用中結構化工具前言的最佳實踐？」 +> - 「如何在 UI 中捕捉與顯示中間進度更新？」 -下圖說明此計劃 → 執行 → 總結的工作流程。 +下圖展示此計劃 → 執行 → 總結工作流程。 -任務執行模式 +Task Execution Pattern -*多步任務的計劃 → 執行 → 總結工作流程* +*多步任務的 計劃 → 執行 → 總結 流程* -**自我反思程式碼** — 用於產出生產品質程式碼。模型根據生產標準生成程式碼，具備妥善錯誤處理。用於構建新功能或服務。 +自我反思程式碼 — 產出符合生產標準的程式碼。模型生成遵守生產標準且具適當錯誤處理的程式碼。用於建立新功能或服務。 ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下圖展示此迭代改進循環 — 生成、評估、識別弱點，反覆修正直至達生產標準。 +下圖呈現此反覆改進迴圈 — 生成、評估、找出問題、改進，直到程式碼符合生產標準。 -自我反思循環 +Self-Reflection Cycle -*迭代改進循環 — 生成、評估、識別問題、改進、重複* +*反覆改進迴圈 — 生成、評估、找出問題、改進、重複* -**結構化分析** — 用於一致性評估。模型依固定框架檢視程式碼（正確性、實踐、效能、安全、可維護性）。適用於代碼審查或品質評估。 +結構化分析 — 用於一致評估。模型使用固定框架（正確性、慣例、效能、安全性、可維護性）審查程式碼。適用程式碼審查或品質評估。 ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 嘗試用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 詢問結構化分析： -> - 「如何為不同類型的代碼審查自訂分析框架？」 -> - 「以程式化方式解析並操作結構化輸出的最佳方法？」 -> - 「如何確保不同審查會議間嚴重程度的一致？」 +> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 詢問結構化分析： +> - 「如何為不同程式碼審查類型客製分析框架？」 +> - 「如何以程式化方式解析並運用結構化輸出？」 +> - 「如何確保不同審查會話中嚴重性評級的一致性？」 -下圖展示如何用此結構化框架將代碼審查組織成一致分類並標明嚴重等級。 +下圖展示此結構化框架如何將程式碼審查組織成一致類別並配以嚴重性等級。 -結構化分析模式 +Structured Analysis Pattern -*具嚴重程度等級的一致性代碼審查框架* +帶有嚴重性等級的一致程式碼審查框架 -**多輪對話** — 用於需要上下文的對話。模型記憶先前訊息並基於該上下文回應。用於互動幫助或複雜問答。 +多輪聊天 — 用於需上下文的對話。模型記住前訊息並累積回應。用於互動式輔助或複雜問答。 ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -下圖視覺化對話上下文如何隨多輪交流累積，以及其與模型代幣限制的關係。 +下圖視覺化對話上下文如何隨多輪累積，以及它如何影響模型令牌限制。 -上下文記憶 +Context Memory -*對話上下文隨多輪交流累積，直到接近代幣限制* -**逐步推理** - 適用於需要清晰邏輯的問題。模型會為每個步驟展示明確的推理。用於數學題、邏輯謎題，或當你需要了解思考過程時。 +多輪對話中上下文如何累積直至達到令牌限制 + +逐步推理 — 適用需可見邏輯的問題。模型逐步展示明確推理。用於數學問題、邏輯謎題或你希望理解思考過程的場景。 ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下圖展示模型如何將問題拆解為明確編號的邏輯步驟。 +下圖示模型如何將問題拆解成明確、編號的邏輯步驟。 Step-by-Step Pattern +將問題拆解為明確的邏輯步驟 -*將問題拆解為明確的邏輯步驟* - -**受限輸出** - 適用於有特定格式需求的回應。模型嚴格遵守格式和長度規則。用於摘要或需要精確輸出結構的情況。 +受限輸出 - 用於具有特定格式要求的回應。模型嚴格遵守格式及長度規則。適用於摘要或需要精確輸出結構的情境。 ```java String prompt = """ @@ -420,21 +420,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下圖展示約束如何引導模型產出嚴格符合格式和長度要求的結果。 +以下圖表顯示約束如何引導模型產生嚴格符合您格式及長度要求的輸出。 -Constrained Output Pattern +受限輸出模式 -*強制執行特定格式、長度和結構要求* +*強制特定格式、長度及結構要求* -## 運行應用程式 +## 執行應用程式 -**驗證部署：** +**驗證部署:** -確保根目錄存在 `.env` 文件且內含 Azure 憑證（在模組 01 中建立）。從模組目錄（`02-prompt-engineering/`）執行： +確保根目錄存在帶有 Azure 憑證的`.env`檔案（在 Module 01 中建立）。從模組目錄(`02-prompt-engineering/`)執行該指令： **Bash:** ```bash -cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +cat ../.env # 應顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` **PowerShell:** @@ -442,43 +442,43 @@ cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` -**啟動應用程式：** +**啟動應用程式:** -> **注意：** 如果你已經從根目錄使用 `./start-all.sh` 啟動所有應用程式（模組 01 中說明），該模組已在 8083 埠運行。你可以跳過以下啟動指令，直接訪問 http://localhost:8083。 +> **注意:** 若您已使用根目錄的`./start-all.sh`啟動所有應用程式（如 Module 01 所述），此模組已在 8083 埠執行。您可跳過以下啟動指令，直接前往 http://localhost:8083。 -**選項 1：使用 Spring Boot 儀表板（建議 VS Code 使用者）** +**選項 1：使用 Spring Boot Dashboard（建議 VS Code 使用者）** -開發容器包含 Spring Boot 儀表板擴充功能，提供管理所有 Spring Boot 應用程式的可視介面。你可以在 VS Code 左側活動列中找到（尋找 Spring Boot 圖示）。 +開發容器已包含 Spring Boot Dashboard 擴充，可視覺化管理所有 Spring Boot 應用程式。可在 VS Code 左側活動列找到（尋找 Spring Boot 圖示）。 -在 Spring Boot 儀表板中，你可以： -- 查看工作區中所有可用的 Spring Boot 應用程式 +從 Spring Boot Dashboard，您可以： +- 查看工作區內所有可用的 Spring Boot 應用程式 - 一鍵啟動/停止應用程式 -- 實時查看應用程式日誌 +- 即時查看應用程式日誌 - 監控應用程式狀態 -只需點擊 "prompt-engineering" 旁的播放按鈕啟動該模組，或一次啟動全部模組。 +只需點擊「prompt-engineering」旁的播放按鈕啟動此模組，或一次啟動所有模組。 -Spring Boot Dashboard +Spring Boot 儀表板 -*VS Code 中的 Spring Boot 儀表板 — 從一處啟動、停止及監控所有模組* +*VS Code 的 Spring Boot 儀表板 — 從一處啟動、停止及監控所有模組* **選項 2：使用 shell 腳本** -啟動所有 Web 應用程式（模組 01-04）： +啟動所有網頁應用程式（模組 01-04）： **Bash:** ```bash -cd .. # 從根目錄 +cd .. # 從根目錄開始 ./start-all.sh ``` **PowerShell:** ```powershell -cd .. # 從根目錄 +cd .. # 從根目錄開始 .\start-all.ps1 ``` -或只啟動此模組： +或只啟動本模組： **Bash:** ```bash @@ -492,9 +492,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -兩個腳本會自動從根目錄的 `.env` 文件載入環境變數，且如果 JAR 文件不存在，會自動構建。 +兩個脚本均會自動從根目錄`.env`載入環境變數，且若尚未建置 JAR 檔案會自動建置。 -> **注意：** 如果你偏好先手動構建所有模組，然後再啟動： +> **注意:** 若您想要先手動建置所有模組，再執行啟動： > > **Bash:** > ```bash @@ -508,101 +508,101 @@ cd 02-prompt-engineering > mvn clean package -DskipTests > ``` -在瀏覽器打開 http://localhost:8083 。 +在瀏覽器開啟 http://localhost:8083 。 -**停止應用程式：** +**停止應用:** **Bash:** ```bash -./stop.sh # 僅此模組 -# 或 +./stop.sh # 只有這個模組 +# 或者 cd .. && ./stop-all.sh # 所有模組 ``` **PowerShell:** ```powershell -.\stop.ps1 # 僅限此模組 +.\stop.ps1 # 只有這個模組 # 或 cd ..; .\stop-all.ps1 # 所有模組 ``` ## 應用程式截圖 -下面是 prompt engineering 模組的主介面，你可以在這裡並排嘗試全部八種模式。 +以下是提示工程模組的主介面，您可以並排試驗所有八種模式。 -Dashboard Home +儀表板主頁 -*主儀表板顯示全部 8 種 prompt engineering 模式及其特性和使用案例* +*主要儀表板展示所有 8 種提示工程模式及其特性和使用案例* ## 探索各種模式 -網頁介面讓你嘗試不同的提示策略。每個模式解決不同問題 — 試試看，了解各種方法何時最有效。 +網頁介面允許您嘗試不同的提示策略。每個模式解決不同問題 — 試試看，看看哪種方式最合適。 -> **注意：串流與非串流** — 每個模式頁面都有兩個按鈕：**🔴 串流回應（實時）** 及 **非串流** 選項。串流利用 Server-Sent Events (SSE)，在模型生成時立即呈現標記，因此你能即時看到進度。非串流則會等整個回答產生完才顯示。對於會觸發深度推理的提示（如高積極度、具自我反思的程式碼），非串流呼叫可能耗時甚久，甚至數分鐘而無任何可見回饋。**嘗試複雜提示時建議使用串流，這樣可以看到模型運作，避免誤以為請求超時。** +> **注意: 直播 vs 非直播** — 每個模式頁面提供兩個按鈕：**🔴 直播回應（實時）** 和 非直播 選項。直播採用伺服器發送事件（SSE）以即時顯示模型生成的詞元，您可立即看到進度。非直播則等待整段回應生成完畢後才顯示。對於觸發深度推理的提示（如高積極性、自我反思程式碼），非直播呼叫可能需要很長時間（有時甚至數分鐘），且無任何可見回饋。**進行複雜提示實驗時請使用直播，這樣您能看到模型運作，避免以為請求已超時。** > -> **注意：瀏覽器需求** — 串流功能使用 Fetch Streams API (`response.body.getReader()`)，需完整瀏覽器（Chrome、Edge、Firefox、Safari）。VS Code 內建的 Simple Browser 不支援 ReadableStream API，故不支援串流功能。若使用 Simple Browser，非串流按鈕仍正常工作，僅串流按鈕受影響。建議使用外部瀏覽器在 `http://localhost:8083` 享用完整體驗。 +> **注意: 瀏覽器需求** — 直播功能使用 Fetch Streams API（`response.body.getReader()`），需要完整瀏覽器（Chrome、Edge、Firefox、Safari）。VS Code 內建的 Simple Browser 不支援 ReadableStream API，因此無法直播。若使用 Simple Browser，非直播按鈕仍可正常運作，只有直播按鈕無效。請於外部瀏覽器開啟 `http://localhost:8083` 以獲得完整體驗。 -### 低積極度 vs 高積極度 +### 低積極性 vs 高積極性 -用低積極度問一個簡單問題，例如「200 的 15% 是多少？」，會快速得到直接答案。再用高積極度問複雜問題，例如「設計一個高流量 API 的快取策略」，點擊 **🔴 串流回應（實時）**，看模型逐字生成詳細推理。相同模型，相同問題結構 — 差別在輸入提示告訴模型思考的深度。 +用低積極性問個簡單問題：「200 的 15% 是多少？」您會立即得到直接答案。再用高積極性問復雜問題：「設計一個高流量 API 的快取策略。」點擊 **🔴 直播回應（實時）**，觀看模型逐詞展現詳細推理。相同模型，相同問題結構 — 但提示告訴它要思考多少。 -### 任務執行（工具前置提示） +### 任務執行（工具前言） -多步流程需要事先計劃並逐步解說。模型會先概述計劃，敘述每一步執行，最後總結結果。 +多步工作流程需要事前規劃和進度描述。模型會先概要要做的事，邊做邊說明每一步，最後總結結果。 ### 自我反思程式碼 -試試「建立一個電子郵件驗證服務」。模型不只產生程式碼然後停止，而是生成、依品質標準評估、找出弱點並改進。你將看到它持續迭代直到程式碼符合生產標準。 +試試「建立一個電子郵件驗證服務」。模型不只生成程式碼然後停止，而是生成後依品質標準評估、找出缺陷並改進。您會看到它反覆迭代，直到程式碼符合生產標準。 ### 結構化分析 -程式碼檢視需一致的評估框架。模型會以固定分類（正確性、實務、效能、安全）分析程式碼，並給予嚴重度等級。 +程式碼審查需要一致評估架構。模型使用固定類別（正確性、慣例、效能、安全性）並帶有嚴重性等級來分析程式碼。 ### 多輪對話 -問「什麼是 Spring Boot？」接著馬上追問「示範一個範例」。模型會記住第一題，並給你專門針對 Spring Boot 的範例。沒記憶的話，第二題就太模糊了。 +問「什麼是 Spring Boot？」然後緊接著問「給我一個範例」。模型記得您第一個問題，並特別給出 Spring Boot 範例。若無記憶，第二個問題會太模糊。 ### 逐步推理 -選一個數學問題，分別用逐步推理與低積極度嘗試。低積極度只給答案 — 快速但不透明。逐步推理會展示每個計算與決策。 +挑選一道數學題，用逐步推理及低積極性各試一次。低積極性只給答案 — 快但不透明。逐步推理會呈現每步計算和決策。 ### 受限輸出 -當你需要特定格式或字數限制時，該模式嚴格執行規則。試生成一個正好 100 字的列點摘要。 +當您需要特定格式或字數時，此模式嚴格執行規則。試試產生一則用 100 個字精確的點列摘要。 -## 你真正學會的是什麼 +## 您真正學到的是什麼 -**推理深度改變一切** +推理努力決定一切 -GPT-5.2 讓你可透過提示控制計算努力程度。低努力意味快速回應且探索有限。高努力則投入更多時間深入思考。你學會將努力度配合任務複雜性 — 簡單題勿浪費時間，複雜決策也別匆忙。 +GPT-5.2 讓您可透過提示調控計算努力。低努力就是快速回應但探索少。高努力則花時間深度思考。您正在學習依任務複雜度匹配努力 — 簡單問題別浪費時間，複雜決策也別草率。 -**結構引導行為** +結構引導行為 -注意提示中的 XML 標籤？它們非裝飾用。模型更可靠地遵照結構化指示執行任務。多步程序或複雜邏輯時，結構有助模型追蹤進度及下一步行動。下圖解析一個良好結構化提示，展示 ``、``、``、``、`` 如何將指令分段明確整理。 +注意提示中的 XML 標籤？它們不是裝飾。模型比起自由文本，更可靠地遵循有結構指令。當需要多步驟流程或複雜邏輯時，結構幫助模型追蹤位置及下一步。下圖拆解一個良好結構的提示，展示 ``、``、``、``、`` 等標籤如何將指令組織成明確區段。 -Prompt Structure +提示結構 -*精良結構化提示的組成，清晰分段與 XML 風格組織* +*精心結構化提示的解剖 — 明確區段，XML 風格組織* -**品質來自自我評估** +透過自我評估提升品質 -自我反思模式藉由明確品質標準運作。不是寄望模型「做對」，而是告訴它「對」的定義：正確邏輯、錯誤處理、效能、安全。模型可自我評估輸出並改進。這讓程式碼生成不是賭運氣，而是流程。 +自我反思模式會明確列出品質標準。您不必希望模型「做對」，而是告訴它什麼是「對的」：邏輯正確、錯誤處理、效能、安全。模型能自我評估輸出並改進。這將程式碼生成從彩票變成有章可循的過程。 -**上下文有限** +上下文是有限的 -多輪對話透過在每次請求中包含訊息歷史實現。但有上限 — 每個模型皆有最大代幣數。隨著對話成長，你必須運用策略保留重要上下文且不超限。本模組展示記憶運作；未來你會學習何時摘要、何時遺忘、何時回溯。 +多輪對話依賴每次請求都帶上訊息歷史。但有限制 — 每個模型都有最大詞元數上限。對話越長，需想策略保留重要上下文而不超標。此模組教您記憶如何運作；往後您將學何時摘要、忘記、取回。 ## 下一步 -**下一模組：** [03-rag - RAG (檢索增強生成)](../03-rag/README.md) +**下一模組：** [03-rag - RAG（檢索增強生成）](../03-rag/README.md) --- -**導航：** [← 上一頁：模組 01 - 簡介](../01-introduction/README.md) | [回主頁](../README.md) | [下一頁：模組 03 - RAG →](../03-rag/README.md) +**導航：** [← 上一章節：Module 01 - 介紹](../01-introduction/README.md) | [回主頁](../README.md) | [下一章節：Module 03 - RAG →](../03-rag/README.md) --- -**免責聲明**： -本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們致力於確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議使用專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或誤釋承擔責任。 +**免責聲明**： +本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們致力於確保準確性，但請注意，機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議進行專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤釋承擔責任。 \ No newline at end of file diff --git a/translations/zh-HK/03-rag/README.md b/translations/zh-HK/03-rag/README.md index 6dbcc139d..588c85542 100644 --- a/translations/zh-HK/03-rag/README.md +++ b/translations/zh-HK/03-rag/README.md @@ -1,144 +1,143 @@ # Module 03: RAG (檢索增強生成) -## Table of Contents - -- [Video Walkthrough](../../../03-rag) -- [What You'll Learn](../../../03-rag) -- [Prerequisites](../../../03-rag) -- [Understanding RAG](../../../03-rag) - - [Which RAG Approach Does This Tutorial Use?](../../../03-rag) -- [How It Works](../../../03-rag) - - [Document Processing](../../../03-rag) - - [Creating Embeddings](../../../03-rag) - - [Semantic Search](../../../03-rag) - - [Answer Generation](../../../03-rag) -- [Run the Application](../../../03-rag) -- [Using the Application](../../../03-rag) - - [Upload a Document](../../../03-rag) - - [Ask Questions](../../../03-rag) - - [Check Source References](../../../03-rag) - - [Experiment with Questions](../../../03-rag) -- [Key Concepts](../../../03-rag) - - [Chunking Strategy](../../../03-rag) - - [Similarity Scores](../../../03-rag) - - [In-Memory Storage](../../../03-rag) - - [Context Window Management](../../../03-rag) -- [When RAG Matters](../../../03-rag) -- [Next Steps](../../../03-rag) - -## Video Walkthrough - -觀看此直播課程，講解如何開始使用本模組： +## 目錄 + +- [影片導覽](#影片導覽) +- [你將學習到的內容](#你將學習到的內容) +- [先決條件](#先決條件) +- [理解 RAG](#理解-rag) + - [本教學使用哪種 RAG 方法？](#本教學使用哪種-rag-方法？) +- [運作原理](#運作原理) + - [文件處理](#文件處理) + - [建立嵌入](#建立嵌入) + - [語意搜尋](#語意搜尋) + - [答案生成](#回答生成) +- [執行應用程式](#運行應用程式) +- [使用應用程式](#使用應用程式) + - [上傳文件](#上傳文件) + - [提問](#提問) + - [檢查來源參考](#檢查來源參考) + - [試驗提問](#試驗不同問題) +- [關鍵概念](#關鍵概念) + - [分塊策略](#片段策略) + - [相似度分數](#相似度分數) + - [記憶體存儲](#記憶體存儲) + - [上下文視窗管理](#上下文視窗管理) +- [何時需要 RAG](#何時使用-rag) +- [下一步](#下一步) + +## 影片導覽 + +觀看這場說明如何開始本模組的直播： RAG with LangChain4j - Live Session -## What You'll Learn +## 你將學習到的內容 -在前面的模組中，你學會了如何與 AI 進行對話，並有效構建提示語。但有一個根本限制：語言模型只知道它在訓練期間學到的東西。它無法回答關於你公司政策、專案文件或任何未被訓練過的資訊的問題。 +在之前的模組中，你學會了如何與 AI 進行對話以及有效地結構化提示。但有個根本限制：語言模型只能知道它在訓練期間學到的知識。它們無法回答有關你公司政策、專案文件或未曾訓練過的資訊的問題。 -RAG（檢索增強生成）解決了這個問題。它不是試圖教模型你的資訊（這既昂貴又不實際），而是賦予模型搜尋你的文件的能力。當有人提問時，系統會找到相關資訊並包含在提示中，模型根據檢索到的上下文來回答。 +RAG（檢索增強生成）解決了這個問題。它不是嘗試教模型你的資訊（這樣費時又不切實際），而是賦予模型搜尋你文件的能力。當有人提問時，系統會找出相關資訊並把它包含進提示中。模型則根據這些檢索到的上下文來回答。 -你可以將 RAG 想像成給模型一個參考圖書館。當你提出問題時，系統： +把 RAG 想像成給模型一個參考圖書館。當你提問時，系統會： -1. **使用者查詢** — 你提出問題 -2. **嵌入** — 將問題轉換成向量 -3. **向量搜尋** — 找到相似的文件片段 -4. **上下文組合** — 將相關片段加入提示 -5. **回應** — 大型語言模型根據上下文生成答案 +1. 使用者查詢 - 你提出問題 +2. 嵌入 - 將問題轉成向量 +3. 向量搜尋 - 找出相似的文件區塊 +4. 上下文組裝 - 將相關區塊加入提示中 +5. 回應 - LLM 根據上下文生成答案 -這讓模型的回應基於你的實際數據，而不是依賴其訓練知識或捏造答案。 +這讓模型的回應基於你的實際資料，而不是依賴訓練知識或憑空編造答案。 -## Prerequisites +## 先決條件 -- 完成 [Module 00 - Quick Start](../00-quick-start/README.md)（用於本模組後面提及的簡易 RAG 範例） -- 完成 [Module 01 - Introduction](../01-introduction/README.md)（已部署 Azure OpenAI 資源，包括 `text-embedding-3-small` 嵌入模型） -- 根目錄下有包含 Azure 憑證的 `.env` 檔案（由模組 01 中的 `azd up` 建立） +- 完成 [Module 01 - 介紹](../01-introduction/README.md)（已部署 Azure OpenAI 資源，包括 `text-embedding-3-small` 嵌入模型） +- 根目錄有 `.env` 檔案包含 Azure 憑證（由 Module 01 的 `azd up` 指令建立） -> **注意：** 如果尚未完成 Module 01，請先依該模組的部署說明操作。`azd up` 命令會部署本模組使用的 GPT 聊天模型與嵌入模型。 +> **注意：** 如果尚未完成 Module 01，請先依該模組的部署說明操作。`azd up` 指令會部署 GPT 聊天模型與本模組所用的嵌入模型。 -## Understanding RAG +## 理解 RAG -下方圖示說明核心概念：RAG 不僅依賴模型訓練數據，還給模型提供了你的文件參考庫，讓它在生成每個答案前先查閱這些資料。 +下圖說明了核心概念：RAG 不僅依賴模型的訓練資料，而是給模型一個你的文件參考庫，讓它在生成答案之前先查閱。 What is RAG -*此圖展示標準大型語言模型（依訓練資料推測）與 RAG 增強大型語言模型（先查閱你的文件）的不同。* +*此圖展示標準 LLM（從訓練數據猜測）與 RAG 增強型 LLM（先檢索你的文件）的差異。* -以下展示整個流程如何連結成端到端體系。使用者問題經過四個階段——嵌入、向量搜尋、上下文組合及答案生成——階段層層遞進： +下面是端到端的流程。使用者問題經過四個階段 —— 嵌入、向量搜尋、上下文組裝、答案生成 —— 每階段基於前一階段： RAG Architecture -*此圖顯示端到端 RAG 管道——使用者查詢依序經過嵌入、向量搜尋、上下文組合和答案生成。* +*此圖展示完整的 RAG 流程——使用者查詢依序經過嵌入、向量搜尋、上下文組裝與答案生成。* -本模組接下來將詳細說明各個階段，並附上可執行與修改的程式碼。 +本模組其餘部分會一一說明每個階段，並附上可執行及可修改的程式碼。 -### Which RAG Approach Does This Tutorial Use? +### 本教學使用哪種 RAG 方法？ -LangChain4j 提供三種 RAG 實作方式，抽象層級各異。下圖並列比較： +LangChain4j 提供三種實現 RAG 的方法，抽象程度不同。下圖比較三者： Three RAG Approaches in LangChain4j -*此圖比較 LangChain4j 的三種 RAG 方法——Easy、Native 和 Advanced——展示主要組件及使用場合。* +*此圖比較 LangChain4j 三種 RAG 方法——Easy、Native 和 Advanced，說明其主要元件及適用時機。* -| 方式 | 功能說明 | 均衡考量 | +| 方法 | 功能說明 | 取捨 | |---|---|---| -| **Easy RAG** | 透過 `AiServices` 和 `ContentRetriever` 自動串接所有流程。你只需註解接口，掛上檢索器，LangChain4j 背後自動執行嵌入、搜尋及提示組合。 | 代碼最少，但看不見每個步驟的運作。 | -| **Native RAG** | 你自己呼叫嵌入模型，搜尋存儲，組提示，生成答案——明確拆分每個步驟。 | 代碼較多，但每階段清晰可見且可修改。 | -| **Advanced RAG** | 使用帶可插拔查詢轉換器、路由器、重排序器及內容注入器的 `RetrievalAugmentor` 框架，適用於生產級管線。 | 彈性最大，但複雜度也最高。 | +| **Easy RAG** | 透過 `AiServices` 和 `ContentRetriever` 自動串接所有流程。你只需註解介面，附加檢索器，LangChain4j 背後負責嵌入、搜尋和提示組裝。 | 程式碼極簡，但無法看見每個步驟細節。 | +| **Native RAG** | 你自己呼叫嵌入模型、搜尋庫、組裝提示、生成答案，各步驟明確分開。 | 程式碼較多，可視化且可修改每個階段。 | +| **Advanced RAG** | 使用可組件化的 `RetrievalAugmentor` 框架，含查詢轉換、路由、重排序和內容注入，適用生產級流程。 | 靈活度最高，但複雜度顯著提升。 | -**本教程採用 Native 方式。** RAG 管線的每一階段——查詢嵌入、向量搜尋、上下文組合與答案生成——都明確寫於 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java)。此設計是故意如此：作為學習資源，比起代碼簡短，更重要的是看到並理解每個階段如何運作。一旦熟悉整體架構，便可轉向 Easy RAG 快速原型或 Advanced RAG 生產系統。 +**本教學採用 Native 方法。** RAG 流程中每一步 —— 查詢嵌入、向量庫搜尋、上下文組裝及答案生成 —— 都在 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 中清楚呈現。這是刻意為之：作為學習資源，比起程式碼極簡，更重視讓你看到並理解每個階段的運作。熟悉後，可以選擇 Easy RAG 快速原型，或 Advanced RAG 用於生產系統。 -> **💡 已經看過 Easy RAG 範例？** [Quick Start 模組](../00-quick-start/README.md) 包含一個使用 Easy RAG 方法的文件問答範例（[`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)），LangChain4j 可自動執行嵌入、搜尋及提示組合。此模組進一步拆解該管線，讓你掌控各階段。 +> **💡 想了解 Easy RAG？** LangChain4j 另有一種 *Easy RAG* 方法，由 `AiServices` 和 `ContentRetriever` 自動處理嵌入、搜尋與提示組裝。本模組則走較明確的路線——拆解流程讓你能看見並控制每一階段。 -下圖展現 Quick Start 範例中的 Easy RAG 管線。注意 `AiServices` 和 `EmbeddingStoreContentRetriever` 如何隱藏複雜度——你只需載入文件、掛上檢索器，便能獲得答案。本模組的 Native 方法則拆解這些隱藏步驟： +下圖展示 Easy RAG 流程。注意 `AiServices` 與 `EmbeddingStoreContentRetriever` 隱藏所有複雜性——載入文件、附加檢索器，再取得答案。本模組的 Native 方法則拆開這些隱藏步驟： Easy RAG Pipeline - LangChain4j -*此圖源自 `SimpleReaderDemo.java` 的 Easy RAG 管線。比對本模組使用的 Native 方法：Easy RAG 透過 `AiServices` 和 `ContentRetriever` 將嵌入、檢索和提示組合隱藏起來——你載入文件、掛檢索器，輕鬆獲答案。而 Native 方法則自己呼叫每個階段（嵌入、搜尋、組合上下文、生成）以提供完全的可視性與控制權。* +*此圖顯示 Easy RAG 流程。與本模組的 Native 方法比較：Easy RAG 把嵌入、檢索和提示組裝藏在 `AiServices` 和 `ContentRetriever` 後面，你只需載入文件、附檢索器，直接取得答案。Native 方法拆解該流程，每階段（嵌入、搜尋、組裝上下文、生成）都由你呼叫，給你完全可見與控制權。* -## How It Works +## 運作原理 -本模組的 RAG 管線分為四個階段，每次使用者提問時依序執行。首先，上傳文件被 **解析與切塊** 成可管理的區塊。這些區塊接著轉成 **向量嵌入** 並存儲，以進行數學比對。當查詢進來，系統執行 **語義搜尋** 找出最相關區塊，最後將它們當作上下文交給大型語言模型進行 **答案生成**。以下章節逐步解析每一環節並附上程式碼與圖示。我們先從第一步開始。 +本模組的 RAG 流程分成四個階段，當使用者提問時依序執行。首先，已上傳的文件會被 解析與分塊 成易於處理的小片段。接著這些區塊會被轉成 向量嵌入 並存儲，方便數學上比較相似度。當收到查詢時，系統會進行 語意搜尋，挑出最相關的區塊，最後將這些內容作為上下文，交由 LLM 進行 答案生成。以下章節將逐步說明每個階段，附程式碼與示意圖。先來看看第一步。 -### Document Processing +### 文件處理 [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -當你上傳文件時，系統會解析它（PDF 或純文字），附加檔名等元資料，然後將文件切成多個切塊——較小的片段，方便放入模型的上下文視窗。這些切塊彼此有些許重疊，以免上下文在分界處丟失。 +當你上傳文件時，系統會解析它（PDF 或純文字格式），附加如檔名等元資料，然後拆成分塊——也就是適合模型上下文視窗大小的小片段。這些分塊彼此有少量重疊，以免在邊界處遺失上下文。 ```java -// 解析已上傳的檔案並包裝成 LangChain4j 文件 +// 解析上載的文件並包裝成 LangChain4j 文件 Document document = Document.from(content, metadata); -// 分割成每塊 300 個 token，並重疊 30 個 token +// 分割成每塊 300 個標記，重疊部分為 30 個標記 DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -下圖視覺化展示此流程。注意每個切塊與鄰近切塊共享部分標記——30 標記重疊確保不會遺失重要上下文： +下圖示意這個過程。注意每個分塊和鄰近分塊有約 30 個 token 重疊——確保重要上下文不會遺漏： Document Chunking -*此圖展示文件被拆成 300 標記切塊，每個切塊有 30 標記重疊，維護切塊邊界的上下文連續性。* +*此圖展示文件被分割成 300 token 的分塊，且每個分塊有 30 token 交疊，維持分塊邊界的上下文內容。* -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試：** 開啟 [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) 並問： -> - 「LangChain4j 如何將文件拆成切塊，為什麼重疊重要？」 -> - 「不同文件類型的最佳切塊大小是什麼？為什麼？」 -> - 「如何處理多語言或特殊格式文件？」 +> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試看：** 開啟 [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) 並問： +> - 「LangChain4j 如何將文件拆成分塊？為什麼重疊很重要？」 +> - 「不同文件類型的最佳分塊大小是多少？為什麼？」 +> - 「該如何處理多語言或特殊格式的文件？」 -### Creating Embeddings +### 建立嵌入 [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -每個切塊會被轉成一種數值表示，稱為嵌入——本質上是將意義轉成數字。嵌入模型不像聊天模型「聰明」，它無法執行指令、推理或回答問題。它能做的是將文本映射到一個數學空間，讓意義相似的文字在向量空間中互相靠近——「汽車」和「車子」會靠得很近，「退款政策」會和「退錢」附近。你可以把聊天模型想像成一個會說話的人，而嵌入模型就是超級優秀的檔案系統。 +每個分塊都會轉成一種數字化的表示法，稱為嵌入（embedding）——本質上是意義到數字的轉換。嵌入模型不像聊天模型「智能」；它無法執行指令、推理或回答問題。它能做的是把文本映射到一個數學空間，讓意義相近的內容落在彼此附近——像是「車」和「汽車」、「退款政策」和「退錢」。把聊天模型想像成能交談的人，嵌入模型則像極好用的歸檔系統。 -下圖視覺化此概念——輸入文字，產出數值向量，意義相近的文字彼此位置相近： +下圖視覺化這個概念——文本進入，數值向量輸出，意義相近的詞會被映射到相鄰向量空間： Embedding Model Concept -*此圖示範嵌入模型如何將文字轉成數值向量，讓像是「汽車」和「車子」這類相近意思的詞，在向量空間中彼此靠近。* +*此圖展示嵌入模型如何將文本轉成數值向量，並將意義相近的詞彙（如「車」和「汽車」）放置在向量空間中的鄰近位置。* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -下圖為類圖，描繪 RAG 管線的兩條流程及 LangChain4j 對應類別。**資料匯入流程**（於上傳時執行一次）拆文件、嵌入切塊，透過 `.addAll()` 儲存。**查詢流程**（每次用戶提問時執行）嵌入問題、透過 `.search()` 搜尋存儲，再將匹配的上下文傳給聊天模型。兩條流程共用 `EmbeddingStore` 接口： +下方類別圖顯示 RAG 流程的兩條分支及對應的 LangChain4j 類別。攝取流程（上傳時執行一次）負責切分文件、嵌入分塊並透過 `.addAll()` 儲存。查詢流程（每次用戶提問時執行）負責將問題嵌入，透過 `.search()` 搜尋庫，並將匹配的上下文傳給聊天模型。兩者以共用的 `EmbeddingStore` 介面連接： LangChain4j RAG Classes -*此圖顯示 RAG 管線的兩條流程——資料匯入與查詢——如何透過共用的 EmbeddingStore 連結。* +*此圖展示 RAG 流程的兩條分支——攝取與查詢，以及它們如何透過共用的 EmbeddingStore 接口連接。* -嵌入存入後，相似內容會自然於向量空間群聚。下圖展示相關主題的文件如何聚集為附近點群，讓語義搜尋成為可能： +嵌入儲存後，類似的內容自然會在向量空間中群聚。以下視覺化展示與相關主題相似的文件如何形成鄰近點，這是實現語意搜尋的基礎： Vector Embeddings Space -*此視覺化展示在三維向量空間中，相關的文件如技術文件、商業規則和常見問題，會聚集成不同群組。* +*此圖展示相關文件在 3D 向量空間中群聚，像是技術文檔、商業規則及常見問答形成明顯的群組。* -使用時，系統遵循四步驟：文檔先嵌入一次，每次搜索嵌入查詢，利用餘弦相似度比對查詢向量和所有存向量，並回傳最高分的前 K 個切塊。下圖逐步說明流程及相關 LangChain4j 類別： +當使用者搜尋時，系統執行四步：先嵌入文檔（一次），然後每次搜尋嵌入查詢，接著用餘弦相似度比較查詢向量與所有已存向量，最後回傳前 K 名最高分分塊。下圖逐步示範該流程與相應的 LangChain4j 類別： Embedding Search Steps -*此圖展示嵌入搜尋的四步驟：嵌入文檔、嵌入查詢、利用餘弦相似度比較向量，並返回前 K 名結果。* +*此圖展示四步嵌入搜尋流程：嵌入文件、嵌入查詢、用餘弦相似度比對向量，最後返回最高分的前 K 筆結果。* -### Semantic Search +### 語意搜尋 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -當你提問時，問題本身也會被嵌入。系統將你的問題嵌入向量與所有文件切塊嵌入向量比對，找出意義最相近的切塊——不僅是字面關鍵詞匹配，而是真正的語義相似。 +當你提出問題時，問題本身也會被轉成嵌入。系統將你的問題嵌入與所有文件分塊的嵌入比對。它找出意義最相近的區塊——不只是字詞匹配，而是真正的語意相似。 ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -下圖比較語義搜尋與傳統關鍵詞搜尋。關鍵詞搜尋「vehicle」會漏掉一個談論「汽車與卡車」的切塊，但語義搜尋明白它們意思相同，並將其視為高分匹配結果： +下圖對比語意搜尋與傳統關鍵字搜尋。對 “vehicle” (車輛) 的關鍵字搜尋不會找到「cars and trucks」的區塊，而語意搜尋理解它們是相同概念，會回傳高分匹配結果： Semantic Search -*此圖比較基於關鍵字的搜尋和語義搜尋，展示語義搜尋如何擷取即使關鍵詞不同，但概念相近的內容。* -在底層，使用餘弦相似度來衡量相似性 — 本質上是在問「這兩支箭頭是否指向相同方向？」兩個文本區塊可以用完全不同的詞語，但如果它們的意思相同，它們的向量就會指向相同方向，分數接近 1.0： +*此圖比較關鍵字搜尋與語意搜尋，說明語意搜尋如何在關鍵字不同時仍能抓取概念上相關的內容。* -Cosine Similarity +在底層，相似度是用餘弦相似度衡量——本質上在問「這兩支箭頭是否指向相同方向？」兩個用詞完全不同的區塊，但若意義相近，其向量指向會相同，得分會接近 1.0： -*此圖說明餘弦相似度為嵌入向量間的角度 — 向量越一致，分數越接近 1.0，表示語意相似度越高。* +Cosine Similarity +*此圖示說明餘弦相似度作為嵌入向量間的角度—越貼近對齊的向量分數越接近 1.0，表示語義相似度越高。* -> **🤖 試試 [GitHub Copilot](https://github.com/features/copilot) Chat：** 打開 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 並詢問： -> - 「相似度搜尋如何使用嵌入向量運作，分數由什麼決定？」 -> - 「我應該使用什麼相似度閾值？這如何影響結果？」 -> - 「如果找不到相關文件，要怎麼處理？」 +> **🤖 試試看用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打開 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 並問： +> - 「嵌入和相似度搜尋的工作原理是什麼？分數是如何決定的？」 +> - 「我應該使用什麼相似度閾值？它如何影響結果？」 +> - 「當找不到相關文件時，我該如何處理？」 -### 答案生成 +### 回答生成 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -最相關的文本區塊會組裝成一個結構化提示，其中包含明確指令、取回的上下文，及用戶問題。模型依據這些特定區塊來回答 — 它只能使用眼前的資料，這防止了幻覺現象。 +最相關的片段會被組合成結構化提示，包括明確指示、檢索到的上下文，以及用戶問題。模型會讀取這些特定片段並根據該資訊回答——它只能使用眼前呈現的內容，以避免幻想。 ```java String context = matches.stream() @@ -236,80 +235,80 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` - -下圖展示此組裝流程 — 從搜尋步驟中獲得最高分的區塊會注入到提示模板中，而 `OpenAiOfficialChatModel` 生成基於真實資訊的答案： + +下方圖示說明這種組合的運作——搜尋步驟中得分最高的片段會被注入提示模板，`OpenAiOfficialChatModel` 生成有根據的回答： Context Assembly -*此圖顯示如何將最高分的文本區塊組裝成結構化提示，使模型能從你的資料中生成有根據的答案。* +*此圖說明如何將得分最高的片段組合成結構化提示，讓模型根據你的資料生成有根據的答案。* ## 運行應用程式 -**確認部署：** +**驗證部署：** -確保根目錄有 `.env` 檔案，內含 Azure 憑證（於模組 01 建立）。從本模組目錄（`03-rag/`）執行： +確保根目錄存在 `.env` 檔案且包含 Azure 憑證（已於模組01建立）。從模組目錄（`03-rag/`）執行： **Bash:** ```bash -cat ../.env # 應顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` - + **PowerShell:** ```powershell Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` - + **啟動應用程式：** -> **注意：** 如果你已從根目錄使用 `./start-all.sh` 啟動所有應用程式（如模組 01 所述），本模組已在 8081 埠執行。你可以跳過以下啟動指令，直接瀏覽 http://localhost:8081。 +> **注意：** 如果你已經從根目錄使用 `./start-all.sh` 啟動所有應用（如模組01所述），此模組已在 8081 埠執行。你可以跳過以下啟動指令，直接訪問 http://localhost:8081。 -**選項 1：使用 Spring Boot Dashboard（推薦給 VS Code 用戶）** +**選項一：使用 Spring Boot Dashboard（推薦 VS Code 使用者）** -開發容器內建 Spring Boot Dashboard 擴充功能，提供可視化介面管理所有 Spring Boot 應用程式。可在 VS Code 左側活動欄找到（尋找 Spring Boot 圖示）。 +開發容器已包含 Spring Boot Dashboard 擴充功能，提供管理所有 Spring Boot 應用的視覺介面。可在 VS Code 左側活動欄找到（尋找 Spring Boot 圖示）。 -從 Spring Boot Dashboard 你可以： -- 查看工作區內所有可用 Spring Boot 應用程式 -- 一鍵啟動/停止應用程式 -- 實時查看應用程式日誌 -- 監控應用程式狀態 +透過 Spring Boot Dashboard，你可以： +- 查看工作區中所有可用 Spring Boot 應用 +- 一鍵啟動/停止應用 +- 即時查看應用日誌 +- 監控應用狀態 -只需點擊「rag」旁的播放按鈕即可啟動本模組，或一次啟動所有模組。 +點擊 "rag" 旁的播放按鈕即可啟動此模組，或一次啟動所有模組。 Spring Boot Dashboard -*此截圖展示 VS Code 的 Spring Boot Dashboard，讓你可視化啟動、停止並監控應用程式。* +*此截圖展示 VS Code 中的 Spring Boot Dashboard，你可以視覺化方式啟動、停止及監控應用。* -**選項 2：使用 shell 腳本** +**選項二：使用 shell 腳本** -啟動所有網頁應用程式（模組 01-04）： +啟動所有網頁應用（模組 01-04）： **Bash:** ```bash -cd .. # 從根目錄開始 +cd .. # 從根目錄 ./start-all.sh ``` - + **PowerShell:** ```powershell -cd .. # 從根目錄開始 +cd .. # 從根目錄出發 .\start-all.ps1 ``` - -或只啟動本模組： + +或只啟動此模組： **Bash:** ```bash cd 03-rag ./start.sh ``` - + **PowerShell:** ```powershell cd 03-rag .\start.ps1 ``` - -兩個腳本會自動從根目錄 `.env` 載入環境變數，且如果 JAR 存在，就會進行建置。 + +這兩個腳本會自動載入根目錄 `.env` 的環境變數，並會在 JAR 檔不存在時建置。 > **注意：** 若你想在啟動前手動建置所有模組： > @@ -318,120 +317,121 @@ cd 03-rag > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` + +在瀏覽器開啟 http://localhost:8081。 -在瀏覽器打開 http://localhost:8081。 - -**停止指令：** +**停止方法：** **Bash:** ```bash -./stop.sh # 只有此模塊 +./stop.sh # 僅此模組 # 或者 -cd .. && ./stop-all.sh # 所有模塊 +cd .. && ./stop-all.sh # 所有模組 ``` - + **PowerShell:** ```powershell .\stop.ps1 # 僅此模組 -# 或者 +# 或 cd ..; .\stop-all.ps1 # 所有模組 ``` + ## 使用應用程式 -此應用程式提供文件上傳及提問的網頁介面。 +此應用程式提供文件上傳與提問的網頁介面。 RAG Application Interface -*此截圖展示 RAG 應用界面，讓你上傳文件並提出問題。* +*此截圖展示 RAG 應用介面，你可上傳文件並提問。* ### 上傳文件 -從上傳文件開始 — TXT 格式最適合測試。本目錄提供了一份 `sample-document.txt`，內容關於 LangChain4j 功能、RAG 實作與最佳實踐，適合用來測試系統。 +首先上傳文件—TXT 檔最佳以用於測試。此目錄中提供的 `sample-document.txt` 含有 LangChain4j 特色、RAG 實作及最佳實踐資訊，非常適合測試系統。 -系統會處理你的文件，拆分成多個區塊，並為每個區塊建立嵌入向量。這些過程會在上傳時自動執行。 +系統會處理你的文件，將其拆成片段，並為每個片段建立嵌入。這會在你上傳時自動完成。 ### 提問 -現在可以針對文件內容問具體問題。試著問內容中明確說明的事實。系統會搜尋相關區塊，將它們包含到提示中，並生成答案。 +現在可對文件內容提出具體問題。試著問些文件中明確陳述的事實。系統會搜尋相關片段，將它們包含於提示中，並生成回答。 -### 檢查來源引用 +### 檢查來源參考 -每個答案都帶有帶有相似度分數的來源引用。這些分數（0 至 1）顯示每個區塊跟你的問題貼合度。分數越高，表示匹配越好。這讓你能夠根據原始資料驗證答案。 +每個回答都包含帶有相似度分數的來源參考。這些分數（0 到 1）顯示每個片段與你的問題的相關程度。分數越高代表匹配越好。這讓你能對照來源資料驗證回答。 RAG Query Results -*此截圖展示查詢結果，包括生成的答案、來源引用及每個檢索區塊的相關性分數。* +*此截圖展示查詢結果，包括生成答案、來源參考與每個檢索片段的相關分數。* -### 嘗試問不同問題 +### 試驗不同問題 試試不同類型的問題： - 具體事實：「主要主題是什麼？」 -- 比較：「X 和 Y 有什麼不同？」 -- 摘要：「總結關於 Z 的重點」 +- 比較問題：「X 和 Y 有什麼差異？」 +- 摘要問題：「請總結 Z 的重點」 -觀察相關性分數如何依你的問題與文件內容匹配度變化。 +觀察相關分數如何隨著你的問題與文件內容匹配度變化。 -## 主要概念 +## 關鍵概念 -### 拆分策略 +### 片段策略 -文件被拆成 300 代幣的區塊，重疊 30 代幣。此平衡讓每個區塊擁有足夠上下文，且大小適中，能在提示中包含多個區塊。 +文件被拆成每個 300 個 token 的片段，片段間有 30 token 的重疊。這樣的平衡確保每個片段有足夠的上下文意義，且小到可以在提示中加入多個片段。 ### 相似度分數 -每個檢索的區塊都附帶 0 到 1 範圍的相似度分數，用來表示和用戶問題的匹配程度。下圖視覺化分數範圍及系統如何利用它們過濾結果： +每個檢索到的片段都帶有 0 到 1 之間的相似度分數，表示其與使用者問題的匹配緊密度。下圖視覺化分數範圍以及系統如何利用這些範圍來過濾結果： Similarity Scores -*此圖示範分數範圍從 0 到 1，最低閾值為 0.5，用以過濾不相關區塊。* +*此圖示展示分數範圍從 0 到 1，並設定 0.5 最低閾值過濾不相關片段。* 分數範圍： - 0.7-1.0：高度相關，精確匹配 -- 0.5-0.7：相關，良好上下文 -- 低於 0.5：被過濾，過於不相似 +- 0.5-0.7：相關，提供良好上下文 +- 低於 0.5：過濾掉，過於不相似 -系統只會檢索高於最低閾值的區塊以保證品質。 +系統只會檢索超過最低閾值的片段以確保品質。 -嵌入向量適用於意義分群清晰的情境，但也有盲點。下圖展示常見失效模式 — 區塊過大導致向量模糊，區塊過小缺乏上下文，模糊詞彙連向多個群集，以及基於嵌入無法運作的精確匹配查詢（如ID、零件號）： +嵌入表徵在語義分群明確時表現良好，但也有盲點。下圖顯示常見失效模式——片段太大導致向量混淆，片段太小缺乏上下文，曖昧詞彙指向多個語群，以及純精確匹配（ID、部件編號）完全不適用嵌入： Embedding Failure Modes -*此圖展示嵌入失效的常見模式：區塊過大、區塊過小、模糊詞彙指向多重群集、及ID等精確匹配查詢。* +*此圖說明常見的嵌入失效模式：片段過大、片段過小、曖昧詞彙指向多重語群、以及像 ID 這類精確匹配查詢。* -### 記憶體內存儲 +### 記憶體存儲 -此模組為簡易起見使用記憶體內存儲。每次重新啟動應用，已上傳文件會遺失。生產系統則使用持久性向量資料庫，如 Qdrant 或 Azure AI Search。 +此模組為簡化用例使用記憶體存儲。當你重啟應用時，上傳的文件會遺失。生產環境通常採用持久向量資料庫，如 Qdrant 或 Azure AI Search。 ### 上下文視窗管理 -各模型有最大上下文視窗限制。你不能把大型檔案的所有區塊都包含進去。系統會檢索前 N 個最相關的區塊（預設為 5）以確保在限制內，並提供足夠上下文來產生正確答案。 +每個模型有最大上下文視窗限制。無法包含大型文件的每個片段。系統僅檢索排名前 N 的相關片段（預設5），在限制內提供足夠上下文以生成精準回答。 ## 何時使用 RAG -RAG 並非總是最佳方案。下圖決策指南幫助你判斷何時使用 RAG 具有價值，何時簡單方式已足夠 — 比如將內容直接放入提示或倚賴模型內建知識： +RAG 並非隨時適用。以下決策指南協助你判斷何時 RAG 有意義，何時可直接在提示中包含內容或使用模型內建知識即可： When to Use RAG -*此圖示決策指南說明何時 RAG 有價值，何時簡單方法已足夠。* +*此圖示展示判斷何時採用 RAG 有價值，何時簡易方法已足夠的決策指南。* ## 下一步 -**下一模組：** [04-tools - 使用工具的 AI 代理](../04-tools/README.md) +**下一模組：** [04-tools - 具備工具的 AI 代理](../04-tools/README.md) --- -**導覽：** [← 上一節：模組 02 - 提示工程](../02-prompt-engineering/README.md) | [回主頁](../README.md) | [下一節：模組 04 - 工具 →](../04-tools/README.md) +**導覽：** [← 上一個：模組 02 - 提示工程](../02-prompt-engineering/README.md) | [返回主頁](../README.md) | [下一個：模組 04 - 工具 →](../04-tools/README.md) --- -**免責聲明**： -本文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們致力於提供準確的翻譯，但請注意自動翻譯可能包含錯誤或不準確之處。原始語言的文件應視為權威版本。對於重要資訊，建議使用專業人工翻譯。我們不對因使用本翻譯而引致的任何誤解或誤釋承擔責任。 +**免責聲明**： +本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們致力於確保準確性，但請注意，機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議進行專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤釋承擔責任。 \ No newline at end of file diff --git a/translations/zh-HK/04-tools/README.md b/translations/zh-HK/04-tools/README.md index 99cec6726..52e9f2a28 100644 --- a/translations/zh-HK/04-tools/README.md +++ b/translations/zh-HK/04-tools/README.md @@ -1,84 +1,84 @@ # Module 04: AI Agents with Tools -## 目錄 - -- [視頻演示](../../../04-tools) -- [你將學到什麼](../../../04-tools) -- [前置條件](../../../04-tools) -- [了解帶有工具的 AI 智能代理](../../../04-tools) -- [工具調用運作方式](../../../04-tools) - - [工具定義](../../../04-tools) - - [決策制定](../../../04-tools) - - [執行](../../../04-tools) - - [回應生成](../../../04-tools) - - [架構：Spring Boot 自動注入](../../../04-tools) -- [工具串聯](../../../04-tools) -- [運行應用程式](../../../04-tools) -- [使用應用程式](../../../04-tools) - - [嘗試簡單工具使用](../../../04-tools) - - [測試工具串聯](../../../04-tools) - - [查看對話流程](../../../04-tools) - - [嘗試不同請求](../../../04-tools) -- [關鍵概念](../../../04-tools) - - [ReAct 模式（推理與行動）](../../../04-tools) - - [工具描述很重要](../../../04-tools) - - [會話管理](../../../04-tools) - - [錯誤處理](../../../04-tools) -- [可用工具](../../../04-tools) -- [何時使用基於工具的代理](../../../04-tools) -- [工具與 RAG 的比較](../../../04-tools) -- [後續步驟](../../../04-tools) - -## 視頻演示 - -觀看本直播課程，了解如何開始使用本模組： +## Table of Contents + +- [Video Walkthrough](#video-walkthrough) +- [What You'll Learn](#what-youll-learn) +- [Prerequisites](#prerequisites) +- [Understanding AI Agents with Tools](#understanding-ai-agents-with-tools) +- [How Tool Calling Works](#how-tool-calling-works) + - [Tool Definitions](#tool-definitions) + - [Decision Making](#decision-making) + - [Execution](#execution) + - [Response Generation](#response-generation) + - [Architecture: Spring Boot Auto-Wiring](#architecture-spring-boot-auto-wiring) +- [Tool Chaining](#tool-chaining) +- [Run the Application](#run-the-application) +- [Using the Application](#使用此應用程式) + - [Try Simple Tool Usage](#嘗試簡單工具使用) + - [Test Tool Chaining](#測試工具串接) + - [See Conversation Flow](#觀看對話流程) + - [Experiment with Different Requests](#嘗試不同請求) +- [Key Concepts](#主要概念) + - [ReAct Pattern (Reasoning and Acting)](#react-模式（推理與行動）) + - [Tool Descriptions Matter](#工具描述很重要) + - [Session Management](#會話管理) + - [Error Handling](#錯誤處理) +- [Available Tools](#可用工具) +- [When to Use Tool-Based Agents](#何時使用基於工具的代理) +- [Tools vs RAG](#工具與-rag) +- [Next Steps](#下一步) + +## Video Walkthrough + +Watch this live session that explains how to get started with this module: AI Agents with Tools and MCP - Live Session -## 你將學到什麼 +## What You'll Learn -到目前為止，你已學會如何與 AI 進行對話，如何有效結構提示，以及如何將回應根據你的文件做出基礎。但仍有一個根本限制：語言模型只能生成文本。它無法查詢天氣、執行計算、查詢數據庫或與外部系統互動。 +So far, you've learned how to have conversations with AI, structure prompts effectively, and ground responses in your documents. But there's still a fundamental limitation: language models can only generate text. They can't check the weather, perform calculations, query databases, or interact with external systems. -工具改變了這一點。通過給模型訪問可調用的函數，你將它從純文字生成器轉變為能採取行動的代理。模型決定什麼時候需要工具、使用哪個工具以及傳遞哪些參數。你的程式碼執行函數並返回結果。模型再將結果融合到回應中。 +Tools change this. By giving the model access to functions it can call, you transform it from a text generator into an agent that can take actions. The model decides when it needs a tool, which tool to use, and what parameters to pass. Your code executes the function and returns the result. The model incorporates that result into its response. -## 前置條件 +## Prerequisites -- 完成 [模組 01 - 介紹](../01-introduction/README.md)（Azure OpenAI 資源已部署） -- 建議完成前置模組（本模組在工具與 RAG 比較中參考了 [模組 03 的 RAG 概念](../03-rag/README.md)） -- 根目錄中有 `.env` 文件包含 Azure 認證（由模組 01 的 `azd up` 創建） +- Completed [Module 01 - Introduction](../01-introduction/README.md) (Azure OpenAI resources deployed) +- Completed previous modules recommended (this module references [RAG concepts from Module 03](../03-rag/README.md) in the Tools vs RAG comparison) +- `.env` file in root directory with Azure credentials (created by `azd up` in Module 01) -> **注意：** 如果尚未完成模組 01，請先按照那裡的部署說明操作。 +> **Note:** If you haven't completed Module 01, follow the deployment instructions there first. -## 了解帶有工具的 AI 智能代理 +## Understanding AI Agents with Tools -> **📝 注意：** 本模組中「agents」指的是具備工具調用能力的 AI 助手。這與我們將在 [模組 05: MCP](../05-mcp/README.md) 中介紹的 **Agentic AI** 模式（具備自主規劃、記憶和多步推理的自主代理）不同。 +> **📝 Note:** The term "agents" in this module refers to AI assistants enhanced with tool-calling capabilities. This is different from the **Agentic AI** patterns (autonomous agents with planning, memory, and multi-step reasoning) that we'll cover in [Module 05: MCP](../05-mcp/README.md). -沒有工具時，語言模型只能基於訓練數據生成文本。問它當前天氣，它只能猜測。給它工具，它可以調用天氣 API、執行計算或查詢資料庫，然後將這些真實結果融合入回答。 +Without tools, a language model can only generate text from its training data. Ask it for the current weather, and it has to guess. Give it tools, and it can call a weather API, perform calculations, or query a database — then weave those real results into its response. Without Tools vs With Tools -*沒有工具時模型只能猜測 — 有了工具它可以調用 API、執行計算並回傳實時數據。* +*Without tools the model can only guess — with tools it can call APIs, run calculations, and return real-time data.* -帶工具的 AI 代理遵循 **推理與行動（ReAct）** 模式。模型不只是回應——它會思考自己需要什麼，透過調用工具行動，觀察結果，然後決定是否繼續行動或給出最終答案： +An AI agent with tools follows a **Reasoning and Acting (ReAct)** pattern. The model doesn't just respond — it thinks about what it needs, acts by calling a tool, observes the result, and then decides whether to act again or deliver the final answer: -1. **推理** — 代理分析使用者問題並判斷需要什麼資訊 -2. **行動** — 代理選擇合適工具，生成正確參數並呼叫它 -3. **觀察** — 代理接收工具輸出並評估結果 -4. **重複或回應** — 如果需要更多資料，迴圈返回；否則組合出自然語言回應 +1. **Reason** — The agent analyzes the user's question and determines what information it needs +2. **Act** — The agent selects the right tool, generates the correct parameters, and calls it +3. **Observe** — The agent receives the tool's output and evaluates the result +4. **Repeat or Respond** — If more data is needed, the agent loops back; otherwise, it composes a natural language answer ReAct Pattern -*ReAct 循環——代理推理要做什麼，透過調用工具行動，觀察結果，迴圈直到給出最佳回應。* +*The ReAct cycle — the agent reasons about what to do, acts by calling a tool, observes the result, and loops until it can deliver the final answer.* -這個過程是自動進行的。你定義工具和它們的描述，模型則自動決定何時以及如何使用它們。 +This happens automatically. You define the tools and their descriptions. The model handles the decision-making about when and how to use them. -## 工具調用運作方式 +## How Tool Calling Works -### 工具定義 +### Tool Definitions [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -你定義具備清晰說明和參數規定的函數。模型在系統提示中看到這些描述，理解每個工具的功能。 +You define functions with clear descriptions and parameter specifications. The model sees these descriptions in its system prompt and understands what each tool does. ```java @Component @@ -96,135 +96,135 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// 助手由 Spring Boot 自動連接，包含： -// - ChatModel bean +// 助手由 Spring Boot 自動連接包括： +// - ChatModel 組件 // - 所有來自 @Component 類別的 @Tool 方法 // - 用於會話管理的 ChatMemoryProvider ``` -下圖解析每個註解，展示如何協助 AI 理解何時調用工具及傳遞哪些參數： +The diagram below breaks down every annotation and shows how each piece helps the AI understand when to call the tool and what arguments to pass: Anatomy of Tool Definitions -*工具定義剖析 — @Tool 告訴 AI 何時使用，@P 說明每個參數，@AiService 在啟動時串接所有元素。* +*Anatomy of a tool definition — @Tool tells the AI when to use it, @P describes each parameter, and @AiService wires everything together at startup.* -> **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 打開 [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) 並詢問： -> - 「如何集成像 OpenWeatherMap 這樣的真實天氣 API，而非模擬數據？」 -> - 「什麼樣的工具描述能幫助 AI 正確使用該工具？」 -> - 「如何在工具實現中處理 API 錯誤和速率限制？」 +> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) and ask: +> - "How would I integrate a real weather API like OpenWeatherMap instead of mock data?" +> - "What makes a good tool description that helps the AI use it correctly?" +> - "How do I handle API errors and rate limits in tool implementations?" -### 決策制定 +### Decision Making -當使用者詢問「西雅圖的天氣如何？」時，模型不會隨便選擇工具。它將使用者意圖與所有工具描述比對，評分相關性，然後選出最佳匹配。接著產生結構化函數調用，帶上正確參數 — 這例子中是將 `location` 設為 `"Seattle"`。 +When a user asks "What's the weather in Seattle?", the model doesn't randomly pick a tool. It compares the user's intent against every tool description it has access to, scores each one for relevance, and selects the best match. It then generates a structured function call with the right parameters — in this case, setting `location` to `"Seattle"`. -若無匹配工具，模型會退回用自身知識回答。若多個工具匹配，模型會選擇最具體的那個。 +If no tool matches the user's request, the model falls back to answering from its own knowledge. If multiple tools match, it picks the most specific one. How the AI Decides Which Tool to Use -*模型評估每個可用工具和使用者意圖的匹配程度，選出最佳工具—因此編寫清晰、具體的工具描述至關重要。* +*The model evaluates every available tool against the user's intent and selects the best match — this is why writing clear, specific tool descriptions matters.* -### 執行 +### Execution [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot 自動為所有註冊工具注入宣告式的 `@AiService` 介面，LangChain4j 自動執行工具調用。背後完整的工具調用流程涵蓋六個階段——從使用者的自然語言問題到最終的自然語言回答： +Spring Boot auto-wires the declarative `@AiService` interface with all registered tools, and LangChain4j executes tool calls automatically. Behind the scenes, a complete tool call flows through six stages — from the user's natural language question all the way back to a natural language answer: Tool Calling Flow -*端到端流程——使用者提問，模型挑選工具，LangChain4j 執行該工具，模型將結果編織成自然的回覆。* +*The end-to-end flow — the user asks a question, the model selects a tool, LangChain4j executes it, and the model weaves the result into a natural response.* -如果你執行過模組 00 的 [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java)，已見過這個模式—— `Calculator` 工具的調用即是如此。下面的序列圖展示當時背後發生了什麼： +Behind the scenes, `AiServices` runs the same tool-calling loop for any tool — here illustrated with a simple `Calculator`. The sequence diagram below shows exactly what happens under the hood: Tool Calling Sequence Diagram -*快速入門演示中的工具調用循環——`AiServices` 將訊息和工具結構傳給 LLM，LLM 回傳函數調用像是 `add(42, 58)`，LangChain4j 本地執行 `Calculator` 方法，然後傳回結果產生最終回答。* +*The tool-calling loop — `AiServices` sends your message and tool schemas to the LLM, the LLM replies with a function call like `add(42, 58)`, LangChain4j executes the `Calculator` method locally, and feeds the result back for the final answer.* -> **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 打開 [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) 並詢問： -> - 「ReAct 模式如何運作，為何對 AI 代理有效？」 -> - 「代理如何決定使用哪個工具以及順序？」 -> - 「工具執行失敗會怎樣？如何穩健處理錯誤？」 +> **🤖 Try with [GitHub Copilot](https://github.com/features/copilot) Chat:** Open [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) and ask: +> - "How does the ReAct pattern work and why is it effective for AI agents?" +> - "How does the agent decide which tool to use and in what order?" +> - "What happens if a tool execution fails - how should I handle errors robustly?" -### 回應生成 +### Response Generation -模型接收天氣資料，並將其格式化成自然語言回應給使用者。 +The model receives the weather data and formats it into a natural language response for the user. -### 架構：Spring Boot 自動注入 +### Architecture: Spring Boot Auto-Wiring -本模組使用 LangChain4j 的 Spring Boot 集成，使用宣告式的 `@AiService` 介面。啟動時，Spring Boot 會發現所有帶 `@Tool` 的 `@Component`、你的 `ChatModel` Bean，以及 `ChatMemoryProvider`，然後將它們通通注入至單一的 `Assistant` 介面，毫無冗餘代碼。 +This module uses LangChain4j's Spring Boot integration with declarative `@AiService` interfaces. At startup Spring Boot discovers every `@Component` that contains `@Tool` methods, your `ChatModel` bean, and the `ChatMemoryProvider` — then wires them all into a single `Assistant` interface with zero boilerplate. Spring Boot Auto-Wiring Architecture -*@AiService 介面整合了 ChatModel、工具組件和記憶提供者 — Spring Boot 自動處理所有注入。* +*The @AiService interface ties together the ChatModel, tool components, and memory provider — Spring Boot handles all the wiring automatically.* -以下是完整請求生命週期的序列圖——從 HTTP 請求透過控制器、服務、自動注入代理，一直到工具執行和回傳： +Here's the full request lifecycle as a sequence diagram — from the HTTP request through the controller, service, and auto-wired proxy, all the way to the tool execution and back: Spring Boot Tool Calling Sequence -*完整 Spring Boot 請求生命週期——HTTP 請求從控制器和服務流向自動注入的 Assistant 代理，由其自動協調 LLM 和工具調用。* +*The complete Spring Boot request lifecycle — HTTP request flows through the controller and service to the auto-wired Assistant proxy, which orchestrates the LLM and tool calls automatically.* -此方法的主要優點： +Key benefits of this approach: -- **Spring Boot 自動注入** — ChatModel 與工具自動注入 -- **@MemoryId 模式** — 自動會話記憶管理 -- **單例實例** — Assistant 創建一次重複使用，提高效能 -- **類型安全執行** — Java 方法直接呼叫並轉換類型 -- **多輪調度** — 自動處理工具串聯 -- **零冗餘代碼** — 無需手動調用 `AiServices.builder()` 或管理記憶 HashMap +- **Spring Boot auto-wiring** — ChatModel and tools automatically injected +- **@MemoryId pattern** — Automatic session-based memory management +- **Single instance** — Assistant created once and reused for better performance +- **Type-safe execution** — Java methods called directly with type conversion +- **Multi-turn orchestration** — Handles tool chaining automatically +- **Zero boilerplate** — No manual `AiServices.builder()` calls or memory HashMap -手動 `AiServices.builder()` 的替代方案需要更多代碼且無法享受 Spring Boot 集成的便利。 +Alternative approaches (manual `AiServices.builder()`) require more code and miss Spring Boot integration benefits. -## 工具串聯 +## Tool Chaining -**工具串聯** — 工具型代理真正強大的地方在於需要多個工具回答同一問題。問「西雅圖的天氣是多少華氏度？」時，代理會自動串接兩個工具：先調用 `getCurrentWeather` 取得攝氏溫度，然後將該結果傳給 `celsiusToFahrenheit` 進行換算——全部在單次對話回合內完成。 +**Tool Chaining** — The real power of tool-based agents shows when a single question requires multiple tools. Ask "What's the weather in Seattle in Fahrenheit?" and the agent automatically chains two tools: first it calls `getCurrentWeather` to get the temperature in Celsius, then it passes that value to `celsiusToFahrenheit` for conversion — all in a single conversation turn. Tool Chaining Example -*工具串聯實例——代理先調用 getCurrentWeather，再將攝氏溫度作為輸入傳給 celsiusToFahrenheit，最後給出綜合回答。* +*Tool chaining in action — the agent calls getCurrentWeather first, then pipes the Celsius result into celsiusToFahrenheit, and delivers a combined answer.* -**優雅失敗** — 詢問不存在於模擬數據中的城市天氣，工具返回錯誤訊息，AI 會解釋無法提供幫助而非崩潰。工具錯誤安全失效。下圖對比了兩種做法——妥善錯誤處理時，代理捕捉例外並提供合理回應，未處理時則導致整個應用崩潰： +**Graceful Failures** — Ask for weather in a city that's not in the mock data. The tool returns an error message, and the AI explains it can't help rather than crashing. Tools fail safely. The diagram below contrasts the two approaches — with proper error handling, the agent catches the exception and responds helpfully, while without it the entire application crashes: Error Handling Flow -*工具發生錯誤時，代理捕捉並回覆有用的說明，而非使應用崩潰。* +*When a tool fails, the agent catches the error and responds with a helpful explanation instead of crashing.* -此流程於單次對話回合完成。代理自動協調多工具調用。 +This happens in a single conversation turn. The agent orchestrates multiple tool calls autonomously. -## 運行應用程式 +## Run the Application -**驗證部署：** +**Verify deployment:** -確保根目錄有 `.env` 文件並包含 Azure 認證（在模組 01 期間已建立）。切換本模組目錄 (`04-tools/`) 執行： +Ensure the `.env` file exists in the root directory with Azure credentials (created during Module 01). Run this from the module directory (`04-tools/`): -**Bash：** +**Bash:** ```bash cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` -**PowerShell：** +**PowerShell:** ```powershell -Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +Get-Content ..\.env # 應顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` -**啟動應用程式：** +**Start the application:** -> **注意：** 如果你已使用根目錄的 `./start-all.sh` 啟動所有應用（模組 01 中說明），本模組已在 8084 端口運行。可跳過以下啟動指令，直接訪問 http://localhost:8084。 +> **Note:** If you already started all applications using `./start-all.sh` from the root directory (as described in Module 01), this module is already running on port 8084. You can skip the start commands below and go directly to http://localhost:8084. -**方案 1：使用 Spring Boot 儀表板（推薦 VS Code 使用者）** +**Option 1: Using Spring Boot Dashboard (Recommended for VS Code users)** -開發容器包含 Spring Boot 儀表板擴充，提供可視化介面管理所有 Spring Boot 應用。此工具位於 VS Code 左側活動欄（尋找 Spring Boot 圖示）。 +The dev container includes the Spring Boot Dashboard extension, which provides a visual interface to manage all Spring Boot applications. You can find it in the Activity Bar on the left side of VS Code (look for the Spring Boot icon). -在 Spring Boot 儀表板，你可以： -- 看到工作區中所有可用的 Spring Boot 應用 -- 一鍵啟動/停止應用 -- 實時查看應用日誌 -- 監控應用狀態 -只需點擊「tools」旁邊的播放按鈕即可啟動此模組，或一次啟動所有模組。 +From the Spring Boot Dashboard, you can: +- See all available Spring Boot applications in the workspace +- Start/stop applications with a single click +- View application logs in real-time +- Monitor application status -以下是 VS Code 中的 Spring Boot Dashboard 介面： +Simply click the play button next to "tools" to start this module, or start all modules at once. -Spring Boot Dashboard +Here's what the Spring Boot Dashboard looks like in VS Code: +Spring Boot 偵測器 -*VS Code 中的 Spring Boot Dashboard — 從一處啟動、停止及監控所有模組* +*VS Code 的 Spring Boot 偵測器 — 從一處啟動、停止及監控所有模組* **選項 2：使用 shell 腳本** @@ -238,11 +238,11 @@ cd .. # 從根目錄 **PowerShell:** ```powershell -cd .. # 從根目錄 +cd .. # 從根目錄出發 .\start-all.ps1 ``` -或只啟動此模組： +或只啟動這個模組： **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -兩個腳本會自動從根目錄的 `.env` 文件載入環境變數，並在 JAR 不存在時自動建立。 +兩個腳本會自動從根目錄的 `.env` 檔載入環境變數，且在 JAR 不存在時會自動編譯。 -> **注意：** 如果您偏好在啟動前手動建置所有模組： +> **注意：** 若你偏好在啟動前手動編譯所有模組： > > **Bash:** > ```bash @@ -272,14 +272,14 @@ cd 04-tools > mvn clean package -DskipTests > ``` -在瀏覽器中開啟 http://localhost:8084 。 +在瀏覽器開啟 http://localhost:8084 。 -**停止指令：** +**停止方法：** **Bash:** ```bash -./stop.sh # 僅此模組 -# 或 +./stop.sh # 只有此模組 +# 或者 cd .. && ./stop-all.sh # 所有模組 ``` @@ -290,98 +290,98 @@ cd .. && ./stop-all.sh # 所有模組 cd ..; .\stop-all.ps1 # 所有模組 ``` -## 使用應用程式 +## 使用此應用程式 -此應用程式提供網頁介面，可讓您與擁有天氣和溫度轉換工具的 AI 代理互動。以下是介面截圖 — 包含快速入門範例和聊天面板以發送請求： +此應用程式提供一個網頁介面，讓你與能使用天氣及溫度轉換工具的 AI 代理互動。介面如下所示 — 包含快速示範範例以及可發送請求的聊天面板： -AI Agent Tools Interface +AI 代理工具介面 -*AI 代理工具介面 — 快速範例與聊天介面，用於與工具互動* +*AI 代理工具介面 — 快速範例與聊天介面用於與工具互動* -### 嘗試簡單的工具使用 +### 嘗試簡單工具使用 -從簡單請求開始：「將華氏 100 度轉換成攝氏度」。代理會識別需要使用溫度轉換工具，呼叫正確的參數並回傳結果。注意這感覺多麼自然 — 您並未指定使用哪個工具或如何呼叫。 +從簡單請求開始：「將 100 華氏度轉為攝氏度」。代理會辨識需要使用溫度轉換工具，帶入正確參數呼叫，並回傳結果。注意這感覺多自然 — 你不需要明確指定用哪個工具或如何呼叫它。 ### 測試工具串接 -現在試試較複雜的請求：「西雅圖的天氣如何，並將其轉換成華氏度？」觀看代理如何分步處理：它先取得天氣（回傳攝氏度），判斷需要轉換成華氏度，呼叫轉換工具，並將兩者結果合併回覆。 +現在試點複雜一點的：「西雅圖的天氣如何，並且將其轉換成華氏度？」觀察代理分步驟處理。它先取得天氣（回傳攝氏度），判斷需轉換成華氏度，呼叫轉換工具，並合併兩項結果成一個回應。 -### 查看對話流程 +### 觀看對話流程 -聊天介面會保留對話歷史，允許您進行多回合互動。您可以看到所有先前的查詢和回應，方便追蹤對話進度，並理解代理如何在多次交換中建立語境。 +聊天介面會保留對話歷史，讓你能進行多輪互動。你可以看到所有先前查詢與回應，方便追蹤對話內容，理解代理如何在多輪交換中建立上下文。 -Conversation with Multiple Tool Calls +多工具呼叫對話 -*多回合對話，顯示簡單轉換、天氣查詢和工具串接* +*多輪對話展示簡單轉換、天氣查詢與工具串接* ### 嘗試不同請求 -嘗試各種組合： -- 天氣查詢：「東京天氣如何？」 -- 溫度轉換：「25°C 是多少開爾文？」 -- 結合查詢：「查詢巴黎的天氣，告訴我是否高於 20°C」 +試試多種組合： +- 天氣查詢：「東京的天氣如何？」 +- 溫度轉換：「25°C 等於多少開爾文？」 +- 複合查詢：「查巴黎天氣並告訴我是否高於 20°C」 -注意代理如何解讀自然語言並映射到適當工具呼叫。 +注意代理如何理解自然語言，並對應合適工具呼叫。 ## 主要概念 ### ReAct 模式（推理與行動） -代理在推理（決定要做什麼）和行動（使用工具）之間交替。此模式賦予自主解決問題的能力，而不僅是回應指示。 +代理在推理（決定要做什麼）及行動（使用工具）間交替。此模式讓它能自主解決問題，而非僅是照指令回應。 -### 工具描述的重要性 +### 工具描述很重要 -工具描述的品質直接影響代理使用工具的效果。清楚、具體的描述幫助模型理解何時及如何呼叫每個工具。 +工具描述的品質會直接影響代理使用的效果。清晰且具體的描述幫助模型判斷何時及如何呼叫各工具。 ### 會話管理 -`@MemoryId` 註解啟用自動的基於會話的記憶管理。每個會話 ID 都獲得由 `ChatMemoryProvider` 管理的專屬 `ChatMemory` 實例，讓多位使用者同時與代理互動時不會混淆對話歷史。下圖顯示多用戶如何根據其會話 ID 路由至隔離的記憶存儲： +`@MemoryId` 註解啟用自動會話記憶管理。每個會話 ID 都有自己的 `ChatMemory` 實例，由 `ChatMemoryProvider` bean 管理，讓多位用戶可同時與代理互動且不會互相干擾。下圖示意多位用戶如何基於會話 ID 分流至獨立記憶庫： -Session Management with @MemoryId +具有 @MemoryId 的會話管理 -*每個會話 ID 映射至一個獨立的對話歷史 — 使用者永遠看不到彼此訊息。* +*每個會話 ID 對應獨立對話歷史 — 用戶看不到彼此訊息。* ### 錯誤處理 -工具可能失敗 — API 超時、參數無效、外部服務中斷。生產環境的代理需要錯誤處理機制，以便模型能解釋問題或嘗試替代方案，而非導致應用程式崩潰。當工具拋出異常時，LangChain4j 會捕捉並將錯誤訊息傳回模型，模型再用自然語言說明問題。 +工具可能失敗 — API 超時、參數無效、外部服務異常。生產環境的代理需要錯誤處理，使模型能解釋問題或嘗試替代方案，而不是整個應用崩潰。當工具丟出例外時，LangChain4j 會捕捉並將錯誤訊息回饋給模型，模型便可用自然語言說明問題。 ## 可用工具 -下圖展示可建構的廣泛工具生態系。此模組示範天氣和溫度工具，但相同的 `@Tool` 模式可套用於任何 Java 方法 — 從資料庫查詢到支付處理皆適用。 +下圖展示你能建立的各類工具生態系。本模組示範了天氣和溫度工具，但同樣的 `@Tool` 模式適用於任何 Java 方法 — 從資料庫查詢到付款處理均可。 -Tool Ecosystem +工具生態系 -*任何使用 @Tool 註解的 Java 方法都可對 AI 開放 — 此模式涵蓋資料庫、API、電子郵件、檔案操作等。* +*任何加註 @Tool 的 Java 方法都可供 AI 使用 — 此模式亦適用於資料庫、API、電子郵件、檔案操作等。* -## 何時使用工具型代理 +## 何時使用基於工具的代理 -並非每個請求都需要工具。判斷依據在於 AI 是否需與外部系統互動，或可僅從自身知識庫回答。下圖總結何時工具有價值、何時無須使用： +非所有請求都需要工具。判斷依據是 AI 是否需與外部系統互動，或能直接從自身知識庫回答。下圖簡述何時工具能發揮作用，何時則非必需： -When to Use Tools +何時使用工具 -*快速決策指引 — 工具適用於即時資料、計算和操作；一般知識和創意任務不需使用。* +*快速決策指南 — 工具用於即時資料、計算和操作；一般知識與創作任務通常不需工具。* -## 工具與 RAG 比較 +## 工具與 RAG -模組 03 和 04 都擴展了 AI 的能力，但方式根本不同。RAG 透過檢索文件提供模型**知識**。工具則讓模型能透過函式呼叫執行**動作**。下圖並列比較這兩種方法 — 從工作流程運作到彼此取捨： +模組 03 和 04 均擴充了 AI 功能，但方式截然不同。RAG 讓模型透過擷取文件取得知識，工具讓模型透過呼叫函式執行行動。下圖比較兩者作業流程及取捨： -Tools vs RAG Comparison +工具 vs RAG 比較 -*RAG 從靜態文件檢索資訊 — 工具執行動作並取得動態即時資料。許多生產系統結合兩者使用。* +*RAG 從靜態文件擷取資訊 — 工具執行動作並取得動態即時資料。許多生產系統會結合兩者使用。* -實務上，許多生產系統結合兩種方法：RAG 以文件為基礎解答，工具則用於取得即時數據或執行操作。 +實務上，許多生產系統會同時用兩種方法：RAG 用於根據文件作答，工具用於獲取即時資料或執行操作。 ## 下一步 -**下一模組：** [05-mcp - 模型上下文協議 (MCP)](../05-mcp/README.md) +**下一個模組：** [05-mcp - 模型上下文協定 (MCP)](../05-mcp/README.md) --- -**導覽：** [← 上一頁：模組 03 - RAG](../03-rag/README.md) | [回主頁](../README.md) | [下一頁：模組 05 - MCP →](../05-mcp/README.md) +**導覽：** [← 上一個：模組 03 - RAG](../03-rag/README.md) | [返回主頁](../README.md) | [下一個：模組 05 - MCP →](../05-mcp/README.md) --- -**免責聲明**： -本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 所翻譯。雖然我們致力於準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的原文版本應被視為權威來源。對於重要資訊，建議聘請專業人工翻譯。本公司對因使用此翻譯所引起的任何誤解或錯誤詮釋概不負責。 +**免責聲明**： +本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們致力於確保準確性，但請注意，機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議進行專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤釋承擔責任。 \ No newline at end of file diff --git a/translations/zh-HK/README.md b/translations/zh-HK/README.md index 44fd043bb..0ef361a3c 100644 --- a/translations/zh-HK/README.md +++ b/translations/zh-HK/README.md @@ -2,118 +2,118 @@ # LangChain4j 初學者課程 -使用 LangChain4j 與 Azure OpenAI GPT-5.2 建構 AI 應用程式的課程，從基本聊天到 AI 代理人。 +使用 LangChain4j 及 Azure OpenAI GPT-5.2 建立 AI 應用程式的課程，涵蓋從基本聊天到 AI 代理人。 ### 🌐 多語言支援 -#### 透過 GitHub Action 支援（自動且隨時更新） +#### 透過 GitHub Action 支援（自動且持續更新） -[阿拉伯語](../ar/README.md) | [孟加拉語](../bn/README.md) | [保加利亞語](../bg/README.md) | [緬甸語](../my/README.md) | [中文 (簡體)](../zh-CN/README.md) | [中文 (繁體，香港)](./README.md) | [中文 (繁體，澳門)](../zh-MO/README.md) | [中文 (繁體，台灣)](../zh-TW/README.md) | [克羅地亞語](../hr/README.md) | [捷克語](../cs/README.md) | [丹麥語](../da/README.md) | [荷蘭語](../nl/README.md) | [愛沙尼亞語](../et/README.md) | [芬蘭語](../fi/README.md) | [法語](../fr/README.md) | [德語](../de/README.md) | [希臘語](../el/README.md) | [希伯來語](../he/README.md) | [印地語](../hi/README.md) | [匈牙利語](../hu/README.md) | [印尼語](../id/README.md) | [義大利語](../it/README.md) | [日語](../ja/README.md) | [坎納達語](../kn/README.md) | [高棉語](../km/README.md) | [韓語](../ko/README.md) | [立陶宛語](../lt/README.md) | [馬來語](../ms/README.md) | [馬拉雅拉姆語](../ml/README.md) | [馬拉地語](../mr/README.md) | [尼泊爾語](../ne/README.md) | [奈及利亞皮欽語](../pcm/README.md) | [挪威語](../no/README.md) | [波斯語 (法爾西語)](../fa/README.md) | [波蘭語](../pl/README.md) | [葡萄牙語 (巴西)](../pt-BR/README.md) | [葡萄牙語 (葡萄牙)](../pt-PT/README.md) | [旁遮普語 (古魯穆奇文)](../pa/README.md) | [羅馬尼亞語](../ro/README.md) | [俄語](../ru/README.md) | [塞爾維亞語 (西里爾字母)](../sr/README.md) | [斯洛伐克語](../sk/README.md) | [斯洛維尼亞語](../sl/README.md) | [西班牙語](../es/README.md) | [斯瓦希里語](../sw/README.md) | [瑞典語](../sv/README.md) | [他加祿語 (菲律賓語)](../tl/README.md) | [泰米爾語](../ta/README.md) | [泰盧固語](../te/README.md) | [泰語](../th/README.md) | [土耳其語](../tr/README.md) | [烏克蘭語](../uk/README.md) | [烏爾都語](../ur/README.md) | [越南語](../vi/README.md) +[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](./README.md) | [Chinese (Traditional, Macau)](../zh-MO/README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **想本地複製？** +> **想要本地複製？** > -> 此儲存庫包含 50 多種語言翻譯，會大幅增加下載大小。若想不含翻譯地複製，請使用稀疏檢出： +> 此資源庫包含 50 多種語言的翻譯，下載大小會大幅增加。若要在不下載翻譯的情況下複製，請使用稀疏檢出： > -> **Bash / macOS / Linux:** +> **Bash / macOS / Linux：** > ```bash > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone '/*' '!translations' '!translated_images' > ``` > -> **CMD（Windows）:** +> **CMD（Windows）：** > ```cmd > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> 這提供了完成課程所需的所有內容，且下載速度更快。 +> 這樣可更快速下載，並包含完成課程所需的所有內容。 ## 目錄 -1. [快速開始](00-quick-start/README.md) - 快速上手 LangChain4j -2. [介紹](01-introduction/README.md) - 了解 LangChain4j 的基本概念 -3. [提示工程](02-prompt-engineering/README.md) - 精通有效的提示設計 -4. [RAG（檢索式生成）](03-rag/README.md) - 建立智能的知識庫系統 -5. [工具](04-tools/README.md) - 整合外部工具與簡易助理 -6. [MCP（模型上下文協議）](05-mcp/README.md) - 使用模型上下文協議 (MCP) 與智能代理模組 +1. [介紹](01-introduction/README.md) - 學習 LangChain4j 的基本原理 +2. [提示工程](02-prompt-engineering/README.md) - 精通有效提示設計 +3. [RAG（檢索增強生成）](03-rag/README.md) - 建立智慧知識庫系統 +4. [工具](04-tools/README.md) - 整合外部工具與簡易助手 +5. [MCP（模型上下文協定）](05-mcp/README.md) - 使用模型上下文協定（MCP）與 Agentic 模組 -### 影片導覽 +### 影片教學 -每個模組皆有直播教學，逐步說明概念與程式碼。 +每個模組都有搭配的現場教學課程，逐步解說概念與程式碼。 | 模組 | 影片 | |--------|-------| -| 01 - 介紹 | [LangChain4j 入門教學](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - 提示工程 | [使用 LangChain4j 的提示工程](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [LangChain4j 的 RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 01 - 介紹 | [LangChain4j 初學入門](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - 提示工程 | [LangChain4j 提示工程](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [LangChain4j RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | | 04 - 工具 & 05 - MCP | [搭配工具與 MCP 的 AI 代理人](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## 學習路徑 -**LangChain4j 新手？** 請參考 [術語表](docs/GLOSSARY.md) 了解關鍵詞與概念定義。 +**對 LangChain4j 新手？** 請參考 [術語表](docs/GLOSSARY.md)，了解重要詞彙與概念。 > 快速開始 -1. 將本儲存庫 fork 至你的 GitHub 帳戶 -2. 點選 **Code** → **Codespaces** 分頁 → **...** → **New with options...** -3. 使用預設值 — 這會選擇為本課程建立的開發容器 +1. 將本資源庫分叉到您的 GitHub 帳號 +2. 點選 **Code** → **Codespaces** 標籤 → **...** → **New with options...** +3. 使用預設設定 — 會選擇為本課程建立的開發容器 4. 點選 **Create codespace** -5. 等待 5-10 分鐘讓環境準備就緒 -6. 直接跳至 [快速開始](./00-quick-start/README.md) 開始學習！ +5. 等待 5-10 分鐘環境準備完成 +6. 直接前往 [介紹](./01-introduction/README.md) 開始學習！ -完成所有模組後，可探索 [測試指南](docs/TESTING.md) 了解 LangChain4j 的測試概念實作。 +完成模組後，可探索 [測試指南](docs/TESTING.md)，了解 LangChain4j 測試概念的實作。 -> **注意：** 本訓練使用 GitHub 模型與 Azure OpenAI。 [快速開始](00-quick-start/README.md) 模組使用 GitHub 模型（無需 Azure 訂閱），而第1-5模組則使用 Azure OpenAI。如未擁有會員，請先註冊 [免費 Azure 帳戶](https://aka.ms/azure-free-account)。 +> **注意：** 本訓練使用 Azure OpenAI。若無帳號，請先申請 [免費 Azure 帳號](https://aka.ms/azure-free-account)。 ## 使用 GitHub Copilot 學習 -若想快速開始編碼，請透過 GitHub Codespace 或本地 IDE 開啟此專案並使用提供的開發容器。此開發容器已預先配置 GitHub Copilot，提供 AI 配對程式設計輔助。 +要快速開始撰寫程式，請在 GitHub Codespace 或搭配本課程所提供的 devcontainer 的本機 IDE 打開專案。本課程使用的 devcontainer 已預先配置 GitHub Copilot，支援 AI 配對程式設計。 -每個程式碼示例都包含你能問 GitHub Copilot 的建議問題，幫助你更深入理解。請參考： +每個程式碼範例都包含您可以詢問 GitHub Copilot 的建議問題，幫助您加深理解。請留意以下範圍中的 💡/🤖 提示： -- **Java 程式檔案標頭** — 針對每個範例的問題 -- **模組 README** — 程式碼示例後的探索提示 +- **Java 檔頭** — 針對各例子設計的問題 +- **模組 README** — 程式碼範例後的探索提示 -**使用方式：** 開啟任意程式文件，詢問 Copilot 建議的問題。它擁有完整程式碼庫的上下文，能解析、延伸、建議替代方案。 +**如何使用：** 開啟任意程式檔案並詢問 Copilot 建議的問題。它具備完整的程式碼基礎上下文，能說明、擴充及建議替代方案。 想了解更多？請參考 [AI 配對程式設計的 Copilot](https://aka.ms/GitHubCopilotAI)。 -## 其他資源 +## 額外資源 ### LangChain -[![LangChain4j 初學者](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js 初學者](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain 初學者](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / 代理人 -[![AZD 初學者](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI 初學者](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP 初學者](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI 代理人 初學者](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / Agents +[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### 生成式 AI 系列 -[![生成式 AI 初學者](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![生成式 AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![生成式 AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![生成式 AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- ### 核心學習 -[![機器學習初學者](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![資料科學初學者](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI 初學者](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) [![Cybersecurity for Beginners](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + [![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) [![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) [![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) @@ -126,23 +126,23 @@ [![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## 尋求幫助 +## 獲取幫助 -如果你在建立 AI 應用程式時遇到困難或有任何問題，歡迎加入： +如果你遇到困難或有任何關於建立 AI 應用程式的問題，歡迎加入： [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -如果你在開發時有產品反饋或錯誤，請訪問： +如果你在開發過程中有產品反饋或錯誤，請到： [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) -## 授權許可 +## 許可證 -MIT 授權條款 - 詳情請參閱[LICENSE](../../LICENSE)檔案。 +MIT 許可證 - 詳細內容請參閱 [LICENSE](../../LICENSE) 檔案。 --- -**免責聲明**： -本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們致力於確保準確性，但請注意自動翻譯可能存在錯誤或不準確之處。原始文件的母語版本應被視為權威資料來源。對於重要資訊，建議進行專業人工翻譯。對因使用本翻譯而引起的任何誤解或誤釋，我們概不負責。 +**免責聲明**： +本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們致力於確保準確性，但請注意，機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議進行專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤釋承擔責任。 \ No newline at end of file diff --git a/translations/zh-HK/docs/GLOSSARY.md b/translations/zh-HK/docs/GLOSSARY.md index 34d3cd420..2abf1368e 100644 --- a/translations/zh-HK/docs/GLOSSARY.md +++ b/translations/zh-HK/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j 詞彙表 +# LangChain4j 術語表 ## 目錄 -- [核心概念](../../../docs) -- [LangChain4j 元件](../../../docs) -- [AI/ML 概念](../../../docs) -- [安全守則](../../../docs) -- [提示工程](../../../docs) -- [RAG（檢索增強生成）](../../../docs) -- [代理人與工具](../../../docs) -- [Agentic 模組](../../../docs) -- [模型上下文協議（MCP）](../../../docs) -- [Azure 服務](../../../docs) -- [測試與開發](../../../docs) +- [核心概念](#核心概念) +- [LangChain4j 組件](#langchain4j-組件) +- [AI/ML 概念](#aiml-概念) +- [Guardrails](#guardrails) +- [提示工程](#prompt-engineering---module-02) +- [RAG（檢索增強生成）](#rag-retrieval-augmented-generation---module-03) +- [代理與工具](#agents-and-tools---module-04) +- [Agentic 模組](#agentic-module---module-05) +- [模型上下文協定 (MCP)](#model-context-protocol-mcp---module-05) +- [Azure 服務](#azure-services---module-01) +- [測試與開發](#testing-and-development---testing-guide) -快速參考課程中使用的術語與概念。 +課程中使用的術語與概念快速參考。 ## 核心概念 -**AI 代理人** - 使用 AI 進行推理並自主行動的系統。[模組 04](../04-tools/README.md) +**AI 代理** - 使用 AI 進行推理與自主行動的系統。[模組 04](../04-tools/README.md) -**鏈（Chain）** - 輸出作為下一步輸入的操作序列。 +鏈 - 輸出作為下一步輸入的操作序列。 -**分塊（Chunking）** - 將文件切割成較小片段。典型大小：300-500 個標記且有重疊。[模組 03](../03-rag/README.md) +分塊 - 將文件拆分成較小的部分。典型大小：300-500 個 token 並帶交疊。[模組 03](../03-rag/README.md) -**上下文視窗（Context Window）** - 模型能處理的最大標記數。GPT-5.2：400K 標記（最高272K 輸入，128K 輸出）。 +上下文窗口 - 模型可處理的最大 tokens 数量。GPT-5.2：400K tokens（最多 272K 輸入，128K 輸出）。 -**嵌入（Embeddings）** - 表示文本語意的數值向量。[模組 03](../03-rag/README.md) +嵌入 - 表示文本含義的數值向量。[模組 03](../03-rag/README.md) -**函數呼叫（Function Calling）** - 模型生成結構化請求來調用外部函數。[模組 04](../04-tools/README.md) +函式調用 - 模型生成結構化請求以調用外部函式。[模組 04](../04-tools/README.md) -**幻覺（Hallucination）** - 當模型生成錯誤但看似合理的資訊。 +幻覺 - 模型生成錯誤但看似合理的資訊。 -**提示（Prompt）** - 輸入給語言模型的文本。[模組 02](../02-prompt-engineering/README.md) +提示 - 輸入給語言模型的文本。[模組 02](../02-prompt-engineering/README.md) -**語意搜尋（Semantic Search）** - 透過語意嵌入而非關鍵字進行搜尋。[模組 03](../03-rag/README.md) +語義搜尋 - 以含義搜尋，使用嵌入而非關鍵字。[模組 03](../03-rag/README.md) -**有狀態與無狀態（Stateful vs Stateless）** - 無狀態：無記憶。有狀態：維持對話歷史。[模組 01](../01-introduction/README.md) +**有狀態 vs 無狀態** - 無狀態：無記憶。有狀態：維護對話歷史。[模組 01](../01-introduction/README.md) -**標記（Tokens）** - 模型處理的基本文字單位。影響成本和限制。[模組 01](../01-introduction/README.md) +**Token** - 模型處理的基本文本單位，影響成本與限制。[模組 01](../01-introduction/README.md) -**工具鏈接（Tool Chaining）** - 按順序執行工具，其中輸出用於下一次呼叫。[模組 04](../04-tools/README.md) +工具鏈 - 工具按順序執行，輸出作為下一次調用依據。[模組 04](../04-tools/README.md) -## LangChain4j 元件 +## LangChain4j 組件 -**AiServices** - 創建類型安全的 AI 服務介面。 +**AiServices** - 建立類型安全的 AI 服務介面。 -**OpenAiOfficialChatModel** - 統一用戶端，支援 OpenAI 和 Azure OpenAI 模型。 +**OpenAiOfficialChatModel** - 統一用戶端，支持 OpenAI 和 Azure OpenAI 模型。 -**OpenAiOfficialEmbeddingModel** - 使用 OpenAI 官方用戶端製作嵌入（同時支援 OpenAI 與 Azure OpenAI）。 +**OpenAiOfficialEmbeddingModel** - 使用官方 OpenAI 用戶端建立嵌入（同時支持 OpenAI 與 Azure OpenAI）。 -**ChatModel** - 語言模型的核心介面。 +**ChatModel** - 語言模型核心介面。 -**ChatMemory** - 維護對話歷史。 +**ChatMemory** - 保持對話歷史。 -**ContentRetriever** - 找出 RAG 相關的文件片段。 +**ContentRetriever** - 為 RAG 找到相關文件分塊。 -**DocumentSplitter** - 將文件拆成多個片段。 +**DocumentSplitter** - 將文件拆分成分塊。 -**EmbeddingModel** - 將文本轉換為數值向量。 +**EmbeddingModel** - 將文本轉換成數值向量。 -**EmbeddingStore** - 存取並檢索嵌入。 +**EmbeddingStore** - 存取嵌入向量。 -**MessageWindowChatMemory** - 維持最近消息的滑動視窗。 +**MessageWindowChatMemory** - 維護最近訊息的滑動視窗。 -**PromptTemplate** - 使用 `{{variable}}` 佔位符建立可重用提示。 +**PromptTemplate** - 建立帶有 `{{variable}}` 佔位符的可重用提示。 -**TextSegment** - 附帶元資料的文本片段。在 RAG 中使用。 +**TextSegment** - 搭配元資料的文本分塊，用於 RAG。 -**ToolExecutionRequest** - 工具執行請求物件。 +**ToolExecutionRequest** - 表示工具執行請求。 **UserMessage / AiMessage / SystemMessage** - 對話訊息類型。 ## AI/ML 概念 -**少量示例學習（Few-Shot Learning）** - 在提示中提供範例。[模組 02](../02-prompt-engineering/README.md) +少量示範學習 - 在提示中提供範例。[模組 02](../02-prompt-engineering/README.md) -**大型語言模型（LLM）** - 以大量文本資料訓練的 AI 模型。 +**大型語言模型 (LLM)** - 以大量文本資料訓練的 AI 模型。 -**推理深度（Reasoning Effort）** - GPT-5.2 用以控制思考深度的參數。[模組 02](../02-prompt-engineering/README.md) +推理深度 - GPT-5.2 中控制思考深度的參數。[模組 02](../02-prompt-engineering/README.md) -**溫度（Temperature）** - 控制輸出隨機性。低=確定性，高=創造性。 +溫度 - 控制生成輸出的隨機性。低=決定性，高=創意。 -**向量資料庫（Vector Database）** - 專為嵌入設計的資料庫。[模組 03](../03-rag/README.md) +向量資料庫 - 專門存取嵌入的資料庫。[模組 03](../03-rag/README.md) -**零示範學習（Zero-Shot Learning）** - 無範例執行任務。[模組 02](../02-prompt-engineering/README.md) +零示範學習 - 無範例執行任務。[模組 02](../02-prompt-engineering/README.md) -## 安全守則 - [模組 00](../00-quick-start/README.md) +## Guardrails -**多重防禦（Defense in Depth）** - 多層安全策略，結合應用層守則與供應商安全過濾器。 +多層防禦 - 結合應用層 Guardrails 與供應商安全過濾的多層安全策略。 -**硬阻擋（Hard Block）** - 嚴重內容違規時供應商回傳 HTTP 400 錯誤。 +嚴格封鎖 - 供應商對嚴重違規內容回傳 HTTP 400 錯誤。 -**InputGuardrail** - LangChain4j 介面，用於在提示送入 LLM 前驗證用戶輸入，提早阻擋有害提示，節省成本和延遲。 +**InputGuardrail** - LangChain4j 用於在送入 LLM 前驗證用戶輸入的介面。提前阻止有害提示節省成本與延遲。 -**InputGuardrailResult** - 守則驗證回傳類型：`success()` 或 `fatal("原因")`。 +**InputGuardrailResult** - Guardrail 驗證回傳類型：`success()` 或 `fatal("原因")`。 -**OutputGuardrail** - 驗證 AI 回應介面，防止不當內容回傳給用戶。 +**OutputGuardrail** - 驗證 AI 回應是否合規的介面，回傳使用者前進行檢查。 -**供應商安全過濾器** - AI 供應商內建 API 層的內容過濾（例如 GitHub Models）。 +供應商安全過濾 - AI 供應商（例如 Azure OpenAI）的內建內容過濾，API 級別捕獲違規。 -**軟拒絕（Soft Refusal）** - 模型禮貌拒絕回答，但不引發錯誤。 +委婉拒絕 - 模型禮貌拒絕回答但不丟錯誤。 ## 提示工程 - [模組 02](../02-prompt-engineering/README.md) -**思路鏈（Chain-of-Thought）** - 逐步推理以提升準確度。 +**思維鏈 (Chain-of-Thought)** - 逐步推理以提升準確率。 -**約束輸出（Constrained Output）** - 強制特定格式或結構。 +限制輸出 - 強制特定格式或結構。 -**高度求解度（High Eagerness）** - GPT-5.2 模式，重度推理。 +高度積極 - GPT-5.2 中用於深入推理的模式。 -**低度求解度（Low Eagerness）** - GPT-5.2 模式，快速回答。 +低度積極 - GPT-5.2 中用於快速回答的模式。 -**多輪對話（Multi-Turn Conversation）** - 保持跨輪上下文。 +多輪對話 - 跨輪保持上下文。 -**基於角色的提示（Role-Based Prompting）** - 透過系統訊息設定模型角色。 +角色提示 - 透過系統訊息設定模型人物角色。 -**自我反省（Self-Reflection）** - 模型評估並改進自己的輸出。 +自我反思 - 模型評估並改進自己的輸出。 -**結構化分析（Structured Analysis）** - 固定評估框架。 +結構化分析 - 固定評估框架。 -**任務執行模式（Task Execution Pattern）** - 計畫 → 執行 → 總結。 +任務執行模式 - 計畫→執行→總結。 ## RAG（檢索增強生成）- [模組 03](../03-rag/README.md) -**文件處理管線** - 載入 → 分塊 → 嵌入 → 儲存。 +文件處理管線 - 載入 → 分塊 → 嵌入 → 儲存。 -**記憶體內嵌入庫** - 非持久性儲存，用於測試。 +記憶體中嵌入庫 - 用於測試的非持久化儲存。 -**RAG** - 結合檢索與生成，以使回應有依據。 +**RAG** - 結合檢索與生成以提供有根據的回答。 -**相似度分數** - 表示語意相似度的度量（0-1）。 +相似度分數 - 語義相似度的量度（0-1）。 -**來源引用** - 檢索內容的元資料。 +來源引用 - 取回內容的元資料。 -## 代理人與工具 - [模組 04](../04-tools/README.md) +## 代理與工具 - [模組 04](../04-tools/README.md) -**@Tool 標註** - 將 Java 方法標記為 AI 可呼叫工具。 +**@Tool 註解** - 標記 Java 方法為 AI 可調用工具。 -**ReAct 模式** - 推理 → 行動 → 觀察 → 重複。 +**ReAct 模式** - 推理→行動→觀察→重複。 -**會話管理** - 不同用戶使用分離上下文。 +會話管理 - 不同用戶分離上下文。 -**工具（Tool）** - AI 代理人可呼叫的功能。 +工具 - AI 代理可調用的函式。 -**工具說明** - 工具目的與參數文件。 +工具說明 - 工具用途及參數文件。 ## Agentic 模組 - [模組 05](../05-mcp/README.md) -**@Agent 標註** - 將介面標記為 AI 代理人，使用宣告式行為定義。 +**@Agent 註解** - 標記介面為 AI 代理並宣告行為定義。 -**代理人監聽器（Agent Listener）** - 透過 `beforeAgentInvocation()` 和 `afterAgentInvocation()` 鉤子監控代理人執行。 +代理監聽器 - 透過 `beforeAgentInvocation()` 和 `afterAgentInvocation()` 監控代理執行。 -**Agentic 範圍** - 代理人存放輸出供下游代理人使用的共用記憶體，使用 `outputKey` 參數指定位置。 +**Agentic Scope** - 代理使用的共享記憶，透過 `outputKey` 儲存結果以供後續代理使用。 -**AgenticServices** - 用於透過 `agentBuilder()` 和 `supervisorBuilder()` 創建代理人的工廠。 +**AgenticServices** - 用於創建代理的工廠，包含 `agentBuilder()` 和 `supervisorBuilder()`。 -**條件工作流程（Conditional Workflow）** - 根據條件導向不同專家代理人。 +條件工作流 - 根據條件導向不同專家代理。 -**人機協作（Human-in-the-Loop）** - 增加人工審核或內容檢查節點的工作流程模式。 +**人類審核（Human-in-the-Loop）** - 加入人工審核或內容審查的工作流模式。 -**langchain4j-agentic** - 用於宣告式代理構建的 Maven 依賴（實驗性）。 +**langchain4j-agentic** - 用於宣告式代理構建的 Maven 依賴（實驗中）。 -**循環工作流程（Loop Workflow）** - 反覆執行代理人直到達成條件（例如品質分數 ≥ 0.8）。 +迴圈工作流 - 重複代理執行直到達到條件（例如品質分數 ≥ 0.8）。 -**outputKey** - 代理人註解參數，指定結果儲存於 Agentic 範圍的位置。 +**outputKey** - 代理註解參數，指定結果在 Agentic Scope 中存儲位置。 -**並行工作流程（Parallel Workflow）** - 同時執行多個獨立任務代理人。 +平行工作流 - 多代理同時執行獨立任務。 -**回應策略（Response Strategy）** - 監督者制定最終答案的方式：LAST、SUMMARY 或 SCORED。 +回應策略 - 監督者組裝最終答案方式：LAST、SUMMARY 或 SCORED。 -**連續工作流程（Sequential Workflow）** - 按順序執行代理人，輸出流向下一步。 +串行工作流 - 代理依序執行，輸出流向下一步。 -**監督代理人模式（Supervisor Agent Pattern）** - 進階 agentic 模式，由監督者 LLM 動態決定呼叫哪些子代理人。 +監督者代理模式 - 先進的代理模式，監督者 LLM 動態決定調用哪些子代理。 -## 模型上下文協議（MCP）- [模組 05](../05-mcp/README.md) +## 模型上下文協定 (MCP) - [模組 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j 中整合 MCP 的 Maven 依賴。 +**langchain4j-mcp** - LangChain4j 中 MCP 整合的 Maven 依賴。 -**MCP** - 模型上下文協議：連接 AI 應用到外部工具的標準，開發一次多處使用。 +**MCP** - 模型上下文協定：連結 AI 應用與外部工具的標準。一次建造，到處使用。 -**MCP 用戶端** - 連接 MCP 伺服器，發現並使用工具的應用程式。 +**MCP 用戶端** - 連接 MCP 伺服器以發現及使用工具的應用。 -**MCP 伺服器** - 以 MCP 協議公開工具，附有清晰描述與參數模式的服務。 +**MCP 伺服器** - 透過 MCP 暴露工具，附帶明確描述與參數結構的服務。 -**McpToolProvider** - LangChain4j 元件，包裝 MCP 工具以供 AI 服務和代理人使用。 +**McpToolProvider** - LangChain4j 組件，封裝 MCP 工具用於 AI 服務和代理。 -**McpTransport** - MCP 通訊介面，實作包含 Stdio 與 HTTP。 +**McpTransport** - MCP 通訊介面。實現包括 Stdio 和 HTTP。 -**Stdio 傳輸** - 透過 stdin/stdout 的本地程序傳輸，適用於檔案系統存取或命令列工具。 +**Stdio 傳輸** - 透過 stdin/stdout 的本地進程傳輸。適用於檔案系統存取或命令行工具。 -**StdioMcpTransport** - LangChain4j 實作，將 MCP 伺服器作為子程序啟動。 +**StdioMcpTransport** - LangChain4j 實作，以子程序形式啟動 MCP 伺服器。 -**工具發現（Tool Discovery）** - 用戶端查詢伺服器取得可用工具的描述與模式。 +工具發現 - 用戶端查詢伺服器可用工具及其描述與結構。 ## Azure 服務 - [模組 01](../01-introduction/README.md) -**Azure AI Search** - 具備向量能力的雲端搜尋。[模組 03](../03-rag/README.md) +**Azure AI 搜尋** - 支援向量功能的雲端搜尋。[模組 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - 部署 Azure 資源。 +**Azure Developer CLI (azd)** - 部署 Azure 資源工具。 -**Azure OpenAI** - 微軟企業級 AI 服務。 +**Azure OpenAI** - 微軟的企業 AI 服務。 -**Bicep** - Azure 基礎架構即程式碼語言。[基礎架構指南](../01-introduction/infra/README.md) +**Bicep** - Azure 基礎設施即代碼語言。[基礎設施指南](../01-introduction/infra/README.md) -**部署名稱** - Azure 中模型部署的名稱。 +部署名稱 - Azure 上模型部署的名稱。 -**GPT-5.2** - 最新 OpenAI 模型，具推理控制能力。[模組 02](../02-prompt-engineering/README.md) +**GPT-5.2** - 最新 OpenAI 模型，具推理控制功能。[模組 02](../02-prompt-engineering/README.md) ## 測試與開發 - [測試指南](TESTING.md) -**開發容器（Dev Container）** - 容器化開發環境。[設定檔](../../../.devcontainer/devcontainer.json) +開發容器 - 容器化的開發環境。[設定](../../../.devcontainer/devcontainer.json) -**GitHub Models** - 免費 AI 模型試驗場。[模組 00](../00-quick-start/README.md) +記憶體中測試 - 使用記憶體中儲存進行測試。 -**記憶體內測試** - 使用記憶體儲存的測試。 +整合測試 - 使用實際基礎設施的測試。 -**整合測試（Integration Testing）** - 使用真實基礎架構的測試。 +**Maven** - Java 構建自動化工具。 -**Maven** - Java 自動建構工具。 - -**Mockito** - Java 模擬測試框架。 +**Mockito** - Java 模擬框架。 **Spring Boot** - Java 應用框架。[模組 01](../01-introduction/README.md) --- -**免責聲明**： -本文件乃使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 所翻譯。儘管我們致力於確保準確性，但請注意自動翻譯可能存在錯誤或不準確之處。原文應以其母語版本為權威來源。對於重要資訊，建議採用專業人工翻譯。我們不對因使用此翻譯而引起的任何誤解或誤釋負責。 +**免責聲明**： +本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們致力於確保準確性，但請注意，機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議進行專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤釋承擔責任。 \ No newline at end of file diff --git a/translations/zh-HK/docs/TESTING.md b/translations/zh-HK/docs/TESTING.md index ecb9dcfb3..e35a4b1d2 100644 --- a/translations/zh-HK/docs/TESTING.md +++ b/translations/zh-HK/docs/TESTING.md @@ -2,19 +2,19 @@ ## 目錄 -- [快速開始](../../../docs) -- [測試涵蓋範圍](../../../docs) -- [執行測試](../../../docs) -- [在 VS Code 中執行測試](../../../docs) -- [測試模式](../../../docs) -- [測試理念](../../../docs) -- [後續步驟](../../../docs) +- [快速開始](#快速開始) +- [測試涵蓋的範圍](#測試涵蓋的範圍) +- [執行測試](#執行測試) +- [在 VS Code 中執行測試](#在-vs-code-中執行測試) +- [測試範式](#測試範式) +- [測試理念](#測試理念) +- [後續步驟](#後續步驟) -本指南引導你透過測試示範如何在不需要 API 金鑰或外部服務的情況下測試 AI 應用程式。 +本指南帶你了解示範如何測試 AI 應用程式的測試案例，無需 API 金鑰或外部服務。 ## 快速開始 -使用一條命令執行所有測試： +使用單一指令運行所有測試： **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -當所有測試通過時，您應該會看到類似下方截圖的輸出結果—測試以零失敗完成執行。 +當所有測試通過時，您會看到類似以下截圖的輸出 — 測試以零失敗運行。 -Successful Test Results +成功的測試結果 -*成功執行測試，全部測試以零失敗通過* +成功執行測試顯示所有測試均通過且無失敗 -## 測試涵蓋範圍 +## 測試涵蓋的範圍 -本課程專注於本地執行的**單元測試**。每個測試展示一個 LangChain4j 的特定概念。下方測試金字塔展示了單元測試的位置——它們構成快速、可靠的基礎，亦是你整體測試策略的根基。 +本課程專注於於本地執行的 單元測試。每個測試獨立展示 LangChain4j 的特定概念。下圖測試金字塔顯示單元測試的位置 — 它們構成快速且可靠的基礎，其他測試策略均建立在此之上。 -Testing Pyramid +測試金字塔 -*測試金字塔顯示單元測試（快速、獨立）、整合測試（真實組件）與端對端測試的比例。本培訓涵蓋單元測試。* +*測試金字塔展現單元測試（快速、獨立）、整合測試（實體元件）和端到端測試的平衡。本訓練涵蓋單元測試。* -| 模組 | 測試數 | 重點 | 主要檔案 | +| 模組 | 測試數量 | 聚焦點 | 主要檔案 | |--------|-------|-------|-----------| -| **00 - 快速開始** | 6 | 提示模板與變數替換 | `SimpleQuickStartTest.java` | -| **01 - 介紹** | 8 | 對話記憶與狀態聊天 | `SimpleConversationTest.java` | -| **02 - 提示工程** | 12 | GPT-5.2 模式、 eager 級別、結構化輸出 | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | 文件導入、嵌入向量、相似度搜索 | `DocumentServiceTest.java` | -| **04 - 工具** | 12 | 函數呼叫與工具串接 | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | 利用 Stdio 傳輸的模型上下文協定 | `SimpleMcpTest.java` | +| **01 - 介紹** | 8 | 會話記憶與有狀態聊天 | `SimpleConversationTest.java` | +| **02 - 提示工程** | 12 | GPT-5.2 範式、急切級別、結構化輸出 | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | 文件攝取、向量嵌入、相似度搜尋 | `DocumentServiceTest.java` | +| **04 - 工具** | 12 | 函數呼叫及工具串接 | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | 模型上下文協議與標準輸入輸出傳輸 | `SimpleMcpTest.java` | ## 執行測試 -**從根目錄執行所有測試：** +**從根目錄運行所有測試：** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**執行特定模組的測試：** +**運行特定模組的測試：** **Bash:** ```bash @@ -75,11 +74,11 @@ mvn test -pl 01-introduction **PowerShell:** ```powershell cd 01-introduction; mvn --% test -# 或者從根目錄開始 +# 或從根目錄 mvn --% test -pl 01-introduction ``` -**執行單一測試類別：** +**運行單一測試類別：** **Bash:** ```bash @@ -91,11 +90,11 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**執行特定測試方法：** +**運行特定測試方法：** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#應該保持對話歷史 +mvn test -Dtest=SimpleConversationTest#是否應該保持對話歷史 ``` **PowerShell:** @@ -105,31 +104,31 @@ mvn --% test -Dtest=SimpleConversationTest#應該保持對話歷史 ## 在 VS Code 中執行測試 -如果你使用 Visual Studio Code，Test Explorer 提供圖形介面來執行與除錯測試。 +如果您使用 Visual Studio Code，測試總管提供圖形介面來執行和除錯測試。 -VS Code Test Explorer +VS Code 測試總管 -*VS Code 測試總管顯示所有 Java 測試類別與各個測試方法的樹狀清單* +*VS Code 測試總管顯示所有 Java 測試類別及個別測試方法的測試樹* -**在 VS Code 中執行測試步驟：** +**在 VS Code 中執行測試：** -1. 點擊活動欄中的燒杯圖示開啟測試總管 -2. 展開測試樹狀結構查看所有模組及測試類別 -3. 點擊任一測試旁的播放按鈕執行該測試 -4. 點擊「Run All Tests」執行全部測試套件 -5. 右鍵任一測試並選擇「Debug Test」設置斷點並逐步除錯程式碼 +1. 點擊活動列中的燒杯圖示開啟測試總管 +2. 展開測試樹以查看所有模組和測試類別 +3. 點擊任何測試旁的播放按鈕以單獨執行該測試 +4. 點擊「執行所有測試」執行整個測試套件 +5. 右鍵點擊任一測試並選擇「除錯測試」以設置斷點及逐步執行程式碼 -測試總管使用綠色勾選標示通過的測試，失敗時會提供詳細錯誤訊息。 +測試總管以綠色勾號顯示通過的測試，且在測試失敗時提供詳細的失敗訊息。 -## 測試模式 +## 測試範式 -### 模式 1：測試提示模板 +### 範式 1：測試提示模板 -最簡單的模式是測試提示模板，本身不呼叫任何 AI 模型。你確認變量替換正確無誤，且提示格式符合預期。 +最簡單的範式是測試提示模板，而不呼叫任何 AI 模型。您驗證變數替換正確，且提示格式如預期。 -Prompt Template Testing +提示模板測試 -*測試提示模板顯示變量替換流程：模板帶有佔位符 → 應用值 → 驗證格式化後輸出* +*測試提示模板顯示變數替換流程：模板含佔位符 → 應用值 → 驗證格式化輸出* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -此測試位於 `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`。 +此範式驗證變數替換正確無誤且提示格式符合預期 — 無需 API 金鑰或模型呼叫。 -**執行方法：** +### 範式 2：模擬語言模型 -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#測試提示模板格式化 -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#測試提示模板格式化 -``` - -### 模式 2：模擬語言模型 - -測試對話邏輯時，使用 Mockito 建立返回預定義結果的假模型。這使測試快速、免費且結果確定。 +測試會話邏輯時，使用 Mockito 創建假模型回傳預設回應，使測試快速、免費且可預測。 -Mock vs Real API Comparison +模擬與真實 API 比較 -*比較展示為何模擬優於真實：模擬快速、免費、確定性高，且無需 API 金鑰* +*比較顯示為何偏好使用模擬進行測試：快速、免費、可預測且無需 API 金鑰* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -該模式出現在 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`。模擬確保行為一致，讓你能驗證記憶管理運作正常。 +此範式出現在 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`。模擬確保行為一致，從而驗證記憶管理正確運作。 -### 模式 3：測試對話隔離 +### 範式 3：測試會話隔離 -對話記憶必須保持多用戶間隔離。該測試驗證對話上下文不會交叉混淆。 +會話記憶須保持多用戶分離。此測試驗證對話不會混淆上下文。 -Conversation Isolation +會話隔離 -*測試對話隔離顯示不同用戶有獨立記憶庫以避免上下文混合* +測試會話隔離示意不同用戶使用獨立記憶存儲以避免上下文混合 ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -每個對話皆維持獨立歷史。在生產系統中，此隔離對多用戶應用非常重要。 +每個會話維護自己的獨立歷史記錄。在生產系統中，這種隔離對多用戶應用至關重要。 -### 模式 4：獨立測試工具 +### 範式 4：獨立測試工具 -工具是 AI 可呼叫的函數。直接測試它們以確保無論 AI 決策如何，工具都能正常運作。 +工具是 AI 可呼叫的函數。直接測試它們以確保功能正確，無論 AI 決策如何。 -Tools Testing +工具測試 -*獨立測試工具展示模擬工具執行、無需 AI 呼叫以驗證業務邏輯* +*獨立測試工具示例，模擬工具執行無需 AI 呼叫，以驗證業務邏輯* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -這些測試來自 `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`，用於驗證工具邏輯不受 AI 影響。串接範例展示一個工具輸出如何成為另一個工具輸入。 +這些測試位於 `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`，驗證工具邏輯與 AI 無關。串接示例展示一個工具的輸出如何作為另一工具的輸入。 -### 模式 5：記憶內 RAG 測試 +### 範式 5：記憶內 RAG 測試 -RAG 系統傳統上需用向量資料庫及嵌入服務。此記憶內模式讓你在無外部依賴下測試整個流程。 +RAG 系統傳統上依賴向量資料庫及嵌入服務。記憶內範式允許您測試整個流程而無外部依賴。 -In-Memory RAG Testing +記憶內 RAG 測試 -*記憶內 RAG 測試工作流程，展示文件解析、向量存儲與相似度搜尋，無需資料庫* +*記憶內 RAG 測試流程示意文件解析、嵌入存儲及相似度搜尋，無需資料庫* ```java @Test @@ -306,11 +293,11 @@ void testProcessTextDocument() { } ``` -此測試來自 `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`，建立記憶中文件並驗證分塊與元資料處理。 +此測試來自 `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`，在記憶體中建立文件並驗證分塊與元資料處理。 -### 模式 6：MCP 整合測試 +### 範式 6：MCP 整合測試 -MCP 模組測試使用 stdio 傳輸的模型上下文協定整合。這些測試驗證你的應用能以子程序形式啟動並與 MCP 伺服器通信。 +MCP 模組測試使用 stdio 傳輸的模型上下文協議整合。這些測試驗證應用是否能作為子程序啟動並與 MCP 伺服器通訊。 `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` 中的測試驗證 MCP 用戶端行為。 @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## 測試理念 -測試你的程式碼，而非 AI。你的測試應驗證你寫的程式碼，檢查提示如何構造、記憶如何管理、工具如何執行。AI 回應會變化，不應納入測試斷言。問自己的是「你的提示模板是否正確替換了變數」，而不是「AI 是否給出正確答案」。 +測試您的程式碼，而非 AI。您的測試應驗證程式碼的構建方式，例如提示如何構造、記憶如何管理及工具如何執行。AI 回應多變，不應成為測試斷言的一環。您應檢查提示模板是否正確替換變數，而非 AI 是否給出正確答案。 -使用模擬語言模型。它們是外部依賴，執行慢、昂貴且非確定性。模擬讓測試快速（毫秒級而非秒級）、免費且結果一致。 +對於語言模型使用模擬。它們是外部依賴，速度慢、成本高且不可預測。模擬使測試快速（毫秒級而非秒級）、免費（無需 API 成本）且可預測（每次結果相同）。 -保持測試獨立。每個測試都應自行設置資料、不依賴其他測試且執行完畢會清理自身。無論執行順序如何，測試皆會通過。 +保持測試獨立。每個測試應自行建立數據，不依賴其他測試，並執行清理。測試結果不應受執行順序影響。 -測試邊界狀況與極端案例，超越理想情況。嘗試空輸入、極大輸入、特殊字元、無效參數及邊緣條件。這些常揭露正常使用無法發現的 bug。 +測試邊界條件，超越成功路徑。嘗試空輸入、極大輸入、特殊字符、無效參數及邊緣情況。這些常揭示正常用例下不易發現的錯誤。 -使用具描述性的命名。將 `shouldMaintainConversationHistoryAcrossMultipleMessages()` 與 `test1()` 比較。前者明確說明測試內容，讓除錯失敗更容易。 +使用具描述性的名稱。對比 `shouldMaintainConversationHistoryAcrossMultipleMessages()` 與 `test1()`。前者明確告訴您正在測試什麼，使除錯失敗更輕鬆。 ## 後續步驟 -既然你已了解測試模式，可深入學習各模組： +既然您已了解測試範式，請深入探索每個模組： -- **[00 - 快速開始](../00-quick-start/README.md)** — 從提示模板基礎開始 -- **[01 - 介紹](../01-introduction/README.md)** — 學習對話記憶管理 -- **[02 - 提示工程](../02/prompt-engineering/README.md)** — 精通 GPT-5.2 的提示模式 -- **[03 - RAG](../03-rag/README.md)** — 建構檢索增強生成系統 -- **[04 - 工具](../04-tools/README.md)** — 實作函數呼叫與工具串接 -- **[05 - MCP](../05-mcp/README.md)** — 整合模型上下文協定 +- **[01 - 介紹](../01-introduction/README.md)** - 學習會話記憶管理 +- **[02 - 提示工程](../02-prompt-engineering/README.md)** - 精通 GPT-5.2 提示範式 +- **[03 - RAG](../03-rag/README.md)** - 建立檢索增強生成系統 +- **[04 - 工具](../04-tools/README.md)** - 實作函數呼叫與工具串接 +- **[05 - MCP](../05-mcp/README.md)** - 整合模型上下文協議 -各模組的 README 提供本章測試概念的詳細說明。 +每個模組的 README 提供本指南中測試概念的詳盡說明。 --- -**導航：** [← 返回主頁](../README.md) +**導覽：** [← 返回主頁](../README.md) --- -**免責聲明**： -本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意自動翻譯可能包含錯誤或不準確之處。原文文件的原始語言版本應視為權威來源。對於重要資訊，建議採用專業人工翻譯。我們不對因使用此翻譯而引起的任何誤解或曲解承擔責任。 +**免責聲明**： +本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們致力於確保準確性，但請注意，機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議進行專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤釋承擔責任。 \ No newline at end of file diff --git a/translations/zh-MO/.co-op-translator.json b/translations/zh-MO/.co-op-translator.json index 7e9836586..686e548e8 100644 --- a/translations/zh-MO/.co-op-translator.json +++ b/translations/zh-MO/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "zh-MO" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T19:20:11+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T14:02:35+00:00", "source_file": "01-introduction/README.md", "language_code": "zh-MO" }, @@ -18,20 +18,20 @@ "language_code": "zh-MO" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T19:22:33+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T13:58:27+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "zh-MO" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T19:23:57+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T14:01:41+00:00", "source_file": "03-rag/README.md", "language_code": "zh-MO" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:39:58+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T14:00:31+00:00", "source_file": "04-tools/README.md", "language_code": "zh-MO" }, @@ -54,8 +54,8 @@ "language_code": "zh-MO" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:38:25+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T13:57:27+00:00", "source_file": "README.md", "language_code": "zh-MO" }, @@ -72,14 +72,14 @@ "language_code": "zh-MO" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T19:26:59+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T13:58:52+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "zh-MO" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T19:27:43+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T13:59:22+00:00", "source_file": "docs/TESTING.md", "language_code": "zh-MO" } diff --git a/translations/zh-MO/00-quick-start/README.md b/translations/zh-MO/00-quick-start/README.md deleted file mode 100644 index d80c85a20..000000000 --- a/translations/zh-MO/00-quick-start/README.md +++ /dev/null @@ -1,387 +0,0 @@ -# Module 00: 快速開始 - -## 目錄 - -- [介紹](../../../00-quick-start) -- [什麼是 LangChain4j？](../../../00-quick-start) -- [LangChain4j 依賴](../../../00-quick-start) -- [先決條件](../../../00-quick-start) -- [設置](../../../00-quick-start) - - [1. 取得您的 GitHub 令牌](../../../00-quick-start) - - [2. 設定您的令牌](../../../00-quick-start) -- [運行範例](../../../00-quick-start) - - [1. 基本聊天](../../../00-quick-start) - - [2. 提示模式](../../../00-quick-start) - - [3. 函式呼叫](../../../00-quick-start) - - [4. 文件問答（簡易 RAG）](../../../00-quick-start) - - [5. 負責任的 AI](../../../00-quick-start) -- [每個範例展示的內容](../../../00-quick-start) -- [下一步](../../../00-quick-start) -- [故障排除](../../../00-quick-start) - -## 介紹 - -此快速入門旨在讓您盡快開始使用 LangChain4j。它涵蓋使用 LangChain4j 和 GitHub 模型構建 AI 應用的基本知識。在接下來的模組中，您將轉向使用 Azure OpenAI 和 GPT-5.2，並深入探討每個概念。 - -## 什麼是 LangChain4j？ - -LangChain4j 是一個 Java 庫，簡化了 AI 驅動應用的構建。您不需要處理 HTTP 客戶端和 JSON 解析，而只需使用乾淨的 Java API。 - -LangChain 中的“鏈”指的是將多個組件連接起來——您可以將提示鏈接到模型，再鏈接到解析器，或將多個 AI 調用串聯，其中一個輸出成為下一個輸入。本快速開始聚焦於基礎知識，之後會探索更複雜的鏈。 - -LangChain4j Chaining Concept - -*LangChain4j 中的組件鏈接 — 組件積木連接起來，創造強大的 AI 工作流程* - -我們將使用三個核心組件： - -**ChatModel** — AI 模型交互的介面。呼叫 `model.chat("prompt")` 並得到回應字串。我們使用 `OpenAiOfficialChatModel`，它可與 OpenAI 兼容的端點（如 GitHub 模型）配合使用。 - -**AiServices** — 建立類型安全的 AI 服務介面。定義方法，使用 `@Tool` 標註，LangChain4j 負責協調。AI 在需要時會自動呼叫您的 Java 方法。 - -**MessageWindowChatMemory** — 維護對話歷史。沒有它，每次請求都是獨立的。有了它，AI 會記住之前的訊息，在多輪對話中保持上下文。 - -LangChain4j Architecture - -*LangChain4j 架構 — 核心組件協同工作，驅動您的 AI 應用* - -## LangChain4j 依賴 - -此快速開始使用了 [`pom.xml`](../../../00-quick-start/pom.xml) 中的三個 Maven 依賴： - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` 模組提供了 `OpenAiOfficialChatModel` 類，用於連接 OpenAI 兼容的 API。GitHub 模型使用相同的 API 格式，因此不需要特殊的適配器——只需設定基底 URL 為 `https://models.github.ai/inference`。 - -`langchain4j-easy-rag` 模組提供自動文件切割、嵌入和檢索功能，讓您在不需手動配置每個步驟的情況下構建 RAG 應用。 - -## 先決條件 - -**使用開發容器？** 已預裝 Java 和 Maven，您只需一個 GitHub 個人存取令牌。 - -**本地開發：** -- Java 21+、Maven 3.9+ -- GitHub 個人存取令牌（以下有指示） - -> **注意：** 本模組使用來自 GitHub 模型的 `gpt-4.1-nano`。請勿修改程式碼中的模型名稱——此名稱已設定為與 GitHub 可用模型相容。 - -## 設置 - -### 1. 取得您的 GitHub 令牌 - -1. 前往 [GitHub 設定 → 個人存取令牌](https://github.com/settings/personal-access-tokens) -2. 點擊「產生新令牌」 -3. 設定一個描述性名稱（例如「LangChain4j Demo」） -4. 設定過期時間（建議 7 天） -5. 在「帳戶權限」中找到「Models」，設為「唯讀」 -6. 點擊「產生令牌」 -7. 複製並保存您的令牌——之後將無法再次查看 - -### 2. 設定您的令牌 - -**選項一：使用 VS Code（推薦）** - -如果您使用 VS Code，請將令牌加入專案根目錄下的 `.env` 文件： - -若無 `.env` 檔案，請將 `.env.example` 複製為 `.env`，或在專案根目錄建立一個新的 `.env` 文件。 - -**範例 `.env` 檔案：** -```bash -# 在 /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -之後您只需在檔案總管右鍵點擊任何示範檔案（如 `BasicChatDemo.java`），並選擇 **"Run Java"**，或使用「執行與除錯」面板中的啟動配置。 - -**選項二：使用終端機** - -將令牌設為環境變數： - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## 運行範例 - -**使用 VS Code:** 只需在檔案總管右鍵點擊任何示範檔案，選擇 **"Run Java"**，或使用「執行與除錯」面板的啟動配置（請先將令牌加入 `.env` 文件）。 - -**使用 Maven:** 您也可以從命令行運行： - -### 1. 基本聊天 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. 提示模式 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -示範零樣本、少樣本、思維鏈及角色基礎提示。 - -### 3. 函式呼叫 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI 在需要時會自動呼叫您的 Java 方法。 - -### 4. 文件問答（簡易 RAG） - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -使用簡易 RAG 以自動嵌入與檢索方式，根據您的文件提問。 - -### 5. 負責任的 AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -查看 AI 安全篩選如何阻擋有害內容。 - -## 每個範例展示的內容 - -**基本聊天** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -從這裡開始看看最簡單的 LangChain4j 用法。您將建立一個 `OpenAiOfficialChatModel`，用 `.chat()` 傳送提示並收到回應。這展示了基礎：如何用自訂端點和 API 鍵初始化模型。理解此模式後，其它所有內容都基於此。 - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試：** 開啟 [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java)，並詢問： -> - 「我如何將此程式碼從 GitHub 模型切換到 Azure OpenAI？」 -> - 「在 OpenAiOfficialChatModel.builder() 中還可以設定哪些參數？」 -> - 「如何新增串流回應，而不是等完整回應？」 - -**提示工程** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -既然您已學會如何與模型對話，接下來看看怎麼說。此範例使用相同模型設定，但展示五種不同的提示模式。試試零樣本提示進行直接指令、少樣本提示學習範例、思維鏈提示揭露推理步驟，以及角色基礎提示設定上下文。您將看到，同一模型根據提示方式呈現截然不同的結果。 - -範例還展示提示模板，它能用變數創建可重用提示。 -以下示例使用 LangChain4j 的 `PromptTemplate` 填入變數。AI 將根據給定的目的地和活動回答。 - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試：** 開啟 [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java)，並詢問： -> - 「零樣本和少樣本提示有何差別？何時應該用哪種？」 -> - 「溫度參數如何影響模型回應？」 -> - 「有哪些技術能防止生產環境的提示注入攻擊？」 -> - 「如何為常用模式建立可重用的 PromptTemplate 物件？」 - -**工具整合** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -這裡展現了 LangChain4j 的強大功能。您將使用 `AiServices` 建立可呼叫您 Java 方法的 AI 助手。只需用 `@Tool("說明")` 標註方法，LangChain4j 會處理其餘——AI 會根據使用者需求自動決定何時使用每個工具。這展示函式呼叫，是構建能採取行動，而不僅僅回答問題的 AI 的關鍵技巧。 - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試：** 開啟 [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java)，並詢問： -> - 「@Tool 標註如何運作？LangChain4j 背後做了什麼？」 -> - 「AI 能否依序呼叫多個工具來解決複雜問題？」 -> - 「如果工具丟出例外，要如何處理錯誤？」 -> - 「如何整合真實 API，而不是這個計算機示例？」 - -**文件問答（簡易 RAG）** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -您將看到使用 LangChain4j「簡易 RAG」方法的檢索強化生成。文件被載入、自動切割並嵌入至記憶體存儲，再由內容檢索器於查詢時提供關聯片段給 AI。AI 回答基於您的文件，不是它的一般知識。 - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試：** 開啟 [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)，並詢問： -> - 「RAG 如何防止 AI 產生錯誤，而不是依賴模型訓練資料？」 -> - 「這種簡易做法與自訂 RAG 流程有何不同？」 -> - 「如何擴充以處理多份文件或更大的知識庫？」 - -**負責任的 AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -建構深度防禦的 AI 安全。此示範展示兩層保護如何協同運作： - -**第一部分：LangChain4j 輸入護欄** — 阻擋危險提示，防止它們送入 LLM。建立自訂護欄，檢查禁止關鍵字或模式。這些在您的程式碼中執行，速度快且免費。 - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**第二部分：供應商安全過濾** — GitHub 模型內建過濾器，捕捉護欄可能漏掉的內容。您會看到嚴重違規時的硬拒絕（HTTP 400 錯誤）以及軟拒絕，AI 禮貌地拒絕回答。 - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試：** 開啟 [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java)，並詢問： -> - 「什麼是 InputGuardrail？如何建立自己的？」 -> - 「硬拒絕和軟拒絕有什麼差別？」 -> - 「為什麼要同時使用護欄和供應商過濾？」 - -## 下一步 - -**下一模組：** [01-introduction - LangChain4j 快速入門](../01-introduction/README.md) - ---- - -**導航：** [← 返回主頁](../README.md) | [下一步：Module 01 - 介紹 →](../01-introduction/README.md) - ---- - -## 故障排除 - -### 首次 Maven 建置 - -**問題：** 初次執行 `mvn clean compile` 或 `mvn package` 花費較長時間（10-15 分鐘） - -**原因：** Maven 首次建置時需下載所有專案依賴（Spring Boot、LangChain4j 函式庫、Azure SDK 等）。 - -**解決方式：** 這是正常行為。後續建置速度會快很多，因為依賴已緩存在本機。下載時間視網絡速度而定。 - -### PowerShell 下的 Maven 指令語法 - -**問題：** Maven 指令失敗，錯誤為 `Unknown lifecycle phase ".mainClass=..."` -**原因**：PowerShell 將 `=` 解釋為變數指派運算子，導致 Maven 屬性語法錯誤 - -**解決方法**：在 Maven 指令前使用停止解析運算子 `--%`： - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` 運算子告知 PowerShell 將後續所有參數直接傳遞給 Maven，不進行解析。 - -### Windows PowerShell Emoji 顯示問題 - -**問題**：AI 回應在 PowerShell 中顯示亂碼（例如 `????` 或 `â??`）而非表情符號 - -**原因**：PowerShell 預設編碼不支援 UTF-8 表情符號 - -**解決方法**：在執行 Java 應用程式前執行此指令： -```cmd -chcp 65001 -``` - -此指令強制終端機採用 UTF-8 編碼。或者，可以使用對 Unicode 支援較佳的 Windows Terminal。 - -### API 呼叫除錯 - -**問題**：AI 模型出現身份驗證錯誤、速率限制，或非預期回應 - -**解決方法**：範例中包含了 `.logRequests(true)` 和 `.logResponses(true)`，用於在主控台顯示 API 呼叫，有助追蹤身份驗證錯誤、速率限制或非預期回應。正式環境中請移除這些標記以減少日誌干擾。 - ---- - - -**免責聲明**： -本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力確保翻譯的準確性，但請注意，機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議採用專業人工翻譯。我們對因使用本翻譯而產生的任何誤解或誤釋不承擔任何責任。 - \ No newline at end of file diff --git a/translations/zh-MO/01-introduction/README.md b/translations/zh-MO/01-introduction/README.md index 247bdb0fa..78cfdb47f 100644 --- a/translations/zh-MO/01-introduction/README.md +++ b/translations/zh-MO/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: 開始使用 LangChain4j +# Module 01: 使用 LangChain4j 入門 ## 目錄 -- [影片導覽](../../../01-introduction) -- [你將學習到的內容](../../../01-introduction) -- [先決條件](../../../01-introduction) -- [了解核心問題](../../../01-introduction) -- [了解 Tokens](../../../01-introduction) -- [記憶如何運作](../../../01-introduction) -- [如何使用 LangChain4j](../../../01-introduction) -- [部署 Azure OpenAI 基礎設施](../../../01-introduction) -- [本地執行應用程式](../../../01-introduction) -- [使用應用程式](../../../01-introduction) - - [無狀態聊天（左側面板）](../../../01-introduction) - - [有狀態聊天（右側面板）](../../../01-introduction) -- [下一步](../../../01-introduction) +- [影片導覽](#影片導覽) +- [您將學習到什麼](#您將學習到什麼) +- [先決條件](#先決條件) +- [了解核心問題](#了解核心問題) +- [了解 Tokens](#了解-tokens) +- [記憶是如何運作的](#記憶是如何運作的) +- [這模組如何使用 LangChain4j](#這模組如何使用-langchain4j) +- [部署 Azure OpenAI 基礎架構](#部署-azure-openai-基礎架構) +- [在本機執行應用程式](#在本機執行應用程式) +- [使用應用程式](#使用應用程式) + - [無狀態聊天（左側面板）](#無狀態聊天（左側面板）) + - [有狀態聊天（右側面板）](#有狀態聊天（右側面板）) +- [後續步驟](#後續步驟) ## 影片導覽 -觀看此現場會議，說明如何開始使用本模組： +觀看這個說明如何開始本模組的現場教學影片： Getting Started with LangChain4j - Live Session -## 你將學習到的內容 +## 您將學習到什麼 -在快速入門中，你使用 GitHub 模型來發送提示、呼叫工具、建立 RAG 管道，並測試防護措施。那些示範展現了可能性 — 現在我們轉到 Azure OpenAI 與 GPT-5.2，開始打造生產風格的應用程式。本模組專注於記憶對話上下文與狀態維持的會話式 AI — 這正是快速入門示範在背後使用但未解釋的概念。 +這是您使用 LangChain4j 和 Azure OpenAI 的起點。我們將從基礎開始，並開始構建具生產風格的應用程式。本模組著重於會記得上下文並維持狀態的對話式 AI——這是後續所有模組的基礎概念。 -整個指南將使用 Azure OpenAI 的 GPT-5.2，因其先進的推理能力令不同模式的行為更明顯。當你加入記憶時，差異一目了然。這使得理解每個組件為應用程式帶來什麼更容易。 +在整個指南中，我們會使用 Azure OpenAI 的 GPT-5.2，因為其先進的推理能力能讓不同模式的行為更加明顯。當您加入記憶功能時，您會清楚看出差異。這讓您更容易理解每個元件為應用程式帶來的價值。 -你將構建一個示範兩種模式的應用程式： +您將建立一個展示兩種模式的應用程式： -**無狀態聊天** - 每個請求獨立。模型不記得先前訊息。這是快速入門時使用的模式。 +無狀態聊天 - 每次請求獨立。模型不會記得之前的訊息。這是最簡單的起點。 -**有狀態對話** - 每個請求包含對話歷史。模型跨多輪維持上下文。這是生產環境應用程式所需。 +有狀態對話 - 每次請求都包含對話歷史。模型能跨多輪保持上下文。這是生產應用程式的必要條件。 ## 先決條件 -- 具 Azure OpenAI 存取權限的 Azure 訂閱 -- Java 21，Maven 3.9+ +- 具備 Azure 訂閱且可使用 Azure OpenAI +- Java 21、Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **注意：** 提供的開發容器中已預裝 Java、Maven、Azure CLI 與 Azure Developer CLI (azd)。 +> **注意：** Java、Maven、Azure CLI 及 Azure Developer CLI (azd) 已預先安裝於提供的 devcontainer 中。 -> **注意：** 本模組使用 Azure OpenAI 的 GPT-5.2。部署會透過 `azd up` 自動設定 — 請勿修改程式碼中的模型名稱。 +> **注意：** 本模組使用 Azure OpenAI 上的 GPT-5.2。部署會透過 `azd up` 自動設定 — 請勿修改程式碼中模型名稱。 ## 了解核心問題 -語言模型是無狀態的。每次 API 呼叫都是獨立的。如果你先傳「我的名字是 John」然後問「我的名字是什麼？」，模型不知道你剛自我介紹過。它將每個請求視為你第一次對話。 +語言模型是無狀態的。每一個 API 呼叫都獨立。如果您先說「我叫 John」然後問「我的名字是什麼？」模型根本不知道您剛剛自我介紹過。它將每個請求視為您第一次對話。 -這對簡單的問答沒問題，但對真實應用程式無用。客服機器人需要記住你告訴它的事。個人助理需要上下文。任何多輪對話都需要記憶。 +這對簡單問答尚可，但對真實應用毫無用處。客服機器人需要記得您說了什麼。個人助理需要上下文。任何多輪對話都需要記憶。 -下圖對比兩種方法 — 左邊是會忘記你名字的無狀態呼叫；右邊是有 ChatMemory 記憶機制的有狀態呼叫。 +下圖對比兩種方法 — 左邊是忘記您名字的無狀態呼叫；右邊是以 ChatMemory 支持的有狀態呼叫，它會記得。 Stateless vs Stateful Conversations -*無狀態（獨立呼叫）和有狀態（具上下文意識）對話的差異* +*無狀態（獨立呼叫）與有狀態（具上下文感知）對話的差異* ## 了解 Tokens -深入對話前，先了解 tokens — 語言模型處理的基本文字單位： +在深入對話前，理解 tokens 很重要——它是語言模型處理的文字基本單位： Token Explanation -*文字如何被切分為 tokens 範例 - "I love AI!" 變成 4 個分離處理單元* +*文字如何被拆成 tokens 的範例——"I love AI!" 變成四個獨立處理單位* -Tokens 是 AI 模型衡量與處理文字的方式。單字、標點甚至空白都可以是 token。您的模型有限制同時處理多少 tokens（GPT-5.2 是 400,000 個，包含最多 272,000 輸入 tokens 和 128,000 輸出 tokens）。了解 tokens 有助於管理對話長度與成本。 +tokens 是 AI 模型衡量和處理文字的單位。詞語、標點，甚至空格都可能是 token。您的模型有最大 token 數限制（GPT-5.2 為 400,000，最多輸入 272,000 個，輸出 128,000 個）。理解 tokens 有助於您管理對話長度及成本。 -## 記憶如何運作 +## 記憶是如何運作的 -聊天記憶解決無狀態問題，透過維持對話歷史。在送出請求給模型前，框架會將相關先前訊息置於前端。當你問「我的名字是什麼？」時，系統實際發送整段對話歷史，讓模型看到你之前說過「我的名字是 John」。 +聊天記憶解決了無狀態問題，它會維護對話歷史。在送出請求到模型之前，框架會先加上相關的前面訊息。當您問「我的名字是什麼？」時，系統其實會送整段對話歷史，讓模型看到您之前說過「我叫 John」。 -LangChain4j 提供的記憶實作會自動處理這一切。你決定保留多少訊息，框架管理上下文視窗。下圖顯示 MessageWindowChatMemory 如何維持最近訊息的滑動窗口。 +LangChain4j 提供了自動處理的記憶實作。您只需設定保留幾條訊息，框架會管理上下文視窗。下圖示範 MessageWindowChatMemory 如何維持一個最近訊息的滑動視窗。 Memory Window Concept -*MessageWindowChatMemory 維持最近訊息的滑動窗口，自動丟棄舊訊息* +*MessageWindowChatMemory 維護最近訊息的滑動視窗，並自動丟棄舊訊息* -## 如何使用 LangChain4j +## 這模組如何使用 LangChain4j -本模組在快速入門基礎上，整合 Spring Boot 並加入會話記憶。組件如下： +本模組整合 Spring Boot 並加入對話記憶。這些元件如何配合： -**相依性** — 增加兩個 LangChain4j 函式庫： +依賴項 - 新增兩個 LangChain4j 程式庫： ```xml @@ -94,7 +94,7 @@ LangChain4j 提供的記憶實作會自動處理這一切。你決定保留多 ``` -**聊天模型** — 將 Azure OpenAI 配置為 Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java))： +聊天模型 - 將 Azure OpenAI 配置為 Spring bean（[LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)）： ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -建構器從 `azd up` 設定的環境變數讀取憑證。設定 `baseUrl` 為您的 Azure 端點，使 OpenAI 用戶端能與 Azure OpenAI 配合。 +建構器從 `azd up` 設定的環境變數讀取認證。設定 `baseUrl` 為您的 Azure 端點可讓 OpenAI 用戶端搭配 Azure OpenAI 運作。 -**會話記憶** — 用 MessageWindowChatMemory 追蹤聊天歷史 ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java))： +對話記憶 - 使用 MessageWindowChatMemory 追蹤聊天歷史（[ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)）： ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,16 +124,16 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -用 `withMaxMessages(10)` 建立只保留最近 10 則訊息的記憶。使用經型別封裝的 `UserMessage.from(text)` 和 `AiMessage.from(text)` 加入用戶與 AI 訊息。用 `memory.messages()` 取得歷史並送給模型。服務對每個對話 ID 儲存分開的記憶實例，允許多用戶同時聊天。 +用 `withMaxMessages(10)` 建立一個最多保留 10 條訊息的記憶。用類型包裝加入使用者與 AI 訊息：`UserMessage.from(text)` 和 `AiMessage.from(text)`。用 `memory.messages()` 取得歷史並送給模型。該服務會針對每個對話 ID 儲存不同的記憶實例，支援多個使用者同時聊天。 -> **🤖 嘗試用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 打開 [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)，並詢問： -> - "MessageWindowChatMemory 在視窗滿了時如何決定丟棄哪些訊息？" -> - "我可以用資料庫實作自訂記憶儲存，而非採用記憶體嗎？" -> - "如何新增摘要功能，以壓縮舊的對話歷史？" +> **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) 聊天功能：** 開啟 [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) 並詢問： +> - 「當滑動視窗滿了，MessageWindowChatMemory 如何決定要丟棄哪條訊息？」 +> - 「我可以用資料庫實作自訂記憶儲存，取代記憶體嗎？」 +> - 「我要如何加入摘要功能來壓縮舊的對話歷史？」 -無狀態聊天端點完全不使用記憶 — 就是 `chatModel.chat(prompt)`，與快速入門相同。有狀態端點則將訊息加到記憶中，撈歷史，並隨每次請求附加上下文。相同模型配置，不同模式。 +無狀態的聊天端點完全不使用記憶 — 就像快速開始一樣用 `chatModel.chat(prompt)`。有狀態端點則先加入訊息，取出歷史，並將上下文包含在每次請求中。相同模型設定，不同使用模式。 -## 部署 Azure OpenAI 基礎設施 +## 部署 Azure OpenAI 基礎架構 **Bash:** ```bash @@ -144,19 +144,19 @@ azd up # 選擇訂閱和位置（建議使用 eastus2） **PowerShell:** ```powershell cd 01-introduction -azd up # 選擇訂閱和位置（建議使用 eastus2） +azd up # 選擇訂閱和地點（建議使用 eastus2） ``` -> **注意：** 若遇到逾時錯誤 (`RequestConflict: Cannot modify resource ... provisioning state is not terminal`)，只要重新執行 `azd up` 即可。Azure 資源可能仍在背景部署中，重試操作可讓部署在資源進入終態後完成。 +> **注意：** 若遇到逾時錯誤（`RequestConflict: Cannot modify resource ... provisioning state is not terminal`），請重新執行 `azd up`。背景中的 Azure 資源可能仍在佈署中，多嘗試幾次可讓佈署完成。 -此操作將： -1. 部署含 GPT-5.2 和 text-embedding-3-small 模型的 Azure OpenAI 資源 -2. 自動於專案根目錄生成包含憑證的 `.env` 檔案 -3. 設定所有必要的環境變數 +此操作會： +1. 部署 Azure OpenAI 資源及 GPT-5.2 和 text-embedding-3-small 模型 +2. 自動在專案根目錄產生帶有認證的 `.env` 檔案 +3. 設定所有所需的環境變數 -**部署遇到問題？** 請參閱 [基礎設施 README](infra/README.md) 詳細故障排除，包括子域名衝突、手動 Azure 门户部署流程及模型設定指南。 +**部署遇到問題？** 請參考 [Infrastructure README](infra/README.md) 獲取詳盡疑難排解，包括子網域名稱衝突、手動 Azure Portal 部署步驟，以及模型配置說明。 -**驗證部署是否成功：** +**確認部署成功：** **Bash:** ```bash @@ -168,7 +168,7 @@ cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 ``` -> **注意：** `azd up` 指令會自動生成 `.env` 檔。如需更新，您可手動編輯 `.env` 檔或重新生成： +> **注意：** `azd up` 指令會自動產生 `.env` 檔。若日後需更新，可以手動編輯 `.env` 或重新產生： > > **Bash:** > ```bash @@ -182,11 +182,11 @@ Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 > .\.azd-env.ps1 > ``` -## 本地執行應用程式 +## 在本機執行應用程式 -**驗證部署：** +**確認部署：** -確保根目錄有 `.env` 檔並正確設置 Azure 憑證。於模組目錄 (`01-introduction/`) 執行： +確保根目錄存在帶 Azure 認證的 `.env` 檔。於模組目錄 (`01-introduction/`) 執行： **Bash:** ```bash @@ -200,25 +200,25 @@ Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT **啟動應用程式：** -**選項 1：使用 Spring Boot Dashboard（建議 VS Code 使用者）** +**選項 1：使用 Spring Boot Dashboard（VS Code 使用者推薦）** -開發容器已包含 Spring Boot Dashboard 擴充套件，提供視覺化介面管理所有 Spring Boot 應用。請於 VS Code 左側活動欄尋找 Spring Boot 圖示。 +dev container 包含 Spring Boot Dashboard 擴充套件，提供視覺化介面來管理所有 Spring Boot 應用。您可在 VS Code 左側活動欄找到（尋找 Spring Boot 圖示）。 -透過 Spring Boot Dashboard，你能： -- 看到工作區內所有 Spring Boot 應用 +從 Spring Boot Dashboard 可以： +- 查看工作區中所有可用 Spring Boot 應用 - 一鍵啟動/停止應用 -- 即時查看應用程式日誌 +- 即時檢視應用日誌 - 監控應用狀態 -點擊「introduction」旁播放按鈕開始此模組，或一次啟動所有模組。 +只需點擊「introduction」旁的播放按鈕即可啟動本模組，或一次啟動所有模組。 Spring Boot Dashboard -*VS Code 中的 Spring Boot Dashboard — 從一處啟動、停止並監控所有模組* +*VS Code 中的 Spring Boot Dashboard — 從一處啟動、停止與監控所有模組* -**選項 2：使用 shell 指令腳本** +**選項 2：使用 shell 腳本** -啟動全部網頁應用（模組 01-04）： +啟動所有 Web 應用（模組 01-04）： **Bash:** ```bash @@ -232,7 +232,7 @@ cd .. # 從根目錄 .\start-all.ps1 ``` -或只啟動此模組： +或只啟動本模組： **Bash:** ```bash @@ -246,9 +246,9 @@ cd 01-introduction .\start.ps1 ``` -兩者腳本皆自動從根目錄 `.env` 檔載入環境變數，若 JAR 不存在則建置。 +兩個腳本會自動從根目錄 `.env` 檔載入環境變數，且若 JAR 不存在會自行編譯。 -> **注意：** 若你偏好先手動建置所有模組再啟動： +> **注意：** 若您偏好先手動建置所有模組後再啟動： > > **Bash:** > ```bash @@ -262,61 +262,61 @@ cd 01-introduction > mvn clean package -DskipTests > ``` -於瀏覽器開啟 http://localhost:8080 。 +於瀏覽器開啟 http://localhost:8080。 **停止應用：** **Bash:** ```bash -./stop.sh # 僅此模組 -# 或者 +./stop.sh # 只限於此模組 +# 或 cd .. && ./stop-all.sh # 所有模組 ``` **PowerShell:** ```powershell -.\stop.ps1 # 僅此模組 +.\stop.ps1 # 只有此模塊 # 或者 -cd ..; .\stop-all.ps1 # 所有模組 +cd ..; .\stop-all.ps1 # 所有模塊 ``` ## 使用應用程式 -應用程式提供網頁介面，並排展示兩種聊天實作。 +應用提供一個包含兩種聊天實作的網頁介面，並排顯示。 Application Home Screen -*儀表板展示簡易聊天（無狀態）與會話聊天（有狀態）選項* +*儀表板顯示簡單聊天（無狀態）及對話式聊天（有狀態）選項* ### 無狀態聊天（左側面板） -先試試這個。輸入「我的名字是 John」，接著立刻問「我的名字是什麼？」模型不會記得，因為每則訊息都是獨立的。這展示了基本語言模型整合的核心問題 — 沒有對話上下文。 +先嘗試這個。先說「我叫 John」，然後立即問「我的名字是什麼？」模型不會記得，因為每條訊息皆獨立。這示範了基本語言模型整合的核心問題 — 沒有對話上下文。 Stateless Chat Demo -*AI 不會記得你前一則訊息中的名字* +*AI 不會記得您前一條訊息說的名字* ### 有狀態聊天（右側面板） -現在在這裡試同樣序列。輸入「我的名字是 John」，再問「我的名字是什麼？」這次它會記得。原因在於 MessageWindowChatMemory — 它維持對話歷史並隨每次請求包含之。這就是生產級會話式 AI 的作法。 +現在在這邊嘗試同樣的順序。先說「我叫 John」，再問「我的名字是什麼？」這次會記得。差異在 MessageWindowChatMemory—它維持對話歷史並且將其包含在每次請求中。這正是生產對話式 AI 的運作方式。 Stateful Chat Demo -*AI 記得對話早先說過你的名字* +*AI 會記得早前對話中您說的名字* -兩側皆使用相同 GPT-5.2 模型。唯一差異是有無記憶。這清楚展現了記憶為應用帶來的價值，以及它為什麼對真正使用場景至關重要。 +兩個面板均使用相同 GPT-5.2 模型。唯一差別是記憶。這明確顯示記憶為您的應用帶來什麼，及為何它對真實案例不可或缺。 -## 下一步 +## 後續步驟 -**下一模組：** [02-prompt-engineering - 用 GPT-5.2 進行提示工程](../02-prompt-engineering/README.md) +**下一模組：** [02-prompt-engineering - 使用 GPT-5.2 的 Prompt 工程](../02-prompt-engineering/README.md) --- -**導覽：** [← 上一課程：Module 00 - 快速入門](../00-quick-start/README.md) | [回主頁](../README.md) | [下一課程：Module 02 - 提示工程 →](../02-prompt-engineering/README.md) +**導覽：** [← 回主頁](../README.md) | [下一步：Module 02 - Prompt Engineering →](../02-prompt-engineering/README.md) --- **免責聲明**： -本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。文件的原始語言版本應被視為權威來源。對於重要資訊，建議使用專業人工翻譯。本公司不對因使用本翻譯而引起的任何誤解或誤釋負責。 +本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。 \ No newline at end of file diff --git a/translations/zh-MO/02-prompt-engineering/README.md b/translations/zh-MO/02-prompt-engineering/README.md index cde93e452..f209d2e2c 100644 --- a/translations/zh-MO/02-prompt-engineering/README.md +++ b/translations/zh-MO/02-prompt-engineering/README.md @@ -1,99 +1,99 @@ -# 模組 02：使用 GPT-5.2 的提示工程 +# Module 02: 使用 GPT-5.2 的提示工程 ## 目錄 -- [影片導覽](../../../02-prompt-engineering) -- [你將學到什麼](../../../02-prompt-engineering) -- [先決條件](../../../02-prompt-engineering) -- [理解提示工程](../../../02-prompt-engineering) -- [提示工程基礎](../../../02-prompt-engineering) - - [零樣本提示](../../../02-prompt-engineering) - - [少量示例提示](../../../02-prompt-engineering) - - [思路鏈](../../../02-prompt-engineering) - - [角色基礎提示](../../../02-prompt-engineering) - - [提示模板](../../../02-prompt-engineering) -- [進階模式](../../../02-prompt-engineering) -- [執行應用程式](../../../02-prompt-engineering) -- [應用程式截圖](../../../02-prompt-engineering) -- [探索模式](../../../02-prompt-engineering) - - [低急迫感與高急迫感](../../../02-prompt-engineering) - - [任務執行（工具前言）](../../../02-prompt-engineering) - - [自我反思程式碼](../../../02-prompt-engineering) - - [結構化分析](../../../02-prompt-engineering) - - [多輪對話](../../../02-prompt-engineering) - - [逐步推理](../../../02-prompt-engineering) - - [受限輸出](../../../02-prompt-engineering) -- [你真正學到的是](../../../02-prompt-engineering) -- [下一步](../../../02-prompt-engineering) +- [影片導覽](#影片導覽) +- [你將學習什麼](#你將學習什麼) +- [先決條件](#先決條件) +- [了解提示工程](#了解提示工程) +- [提示工程基礎](#提示工程基礎) + - [零次提示](#零次提示) + - [少次提示](#少次提示) + - [思路鏈](#思路鏈) + - [基於角色的提示](#基於角色的提示) + - [提示模板](#提示模板) +- [進階模式](#進階模式) +- [執行應用程式](#運行應用程式) +- [應用程式截圖](#應用程式截圖) +- [探索模式](#探索模式) + - [低慾望與高慾望](#低-vs-高積極性) + - [任務執行（工具前置語）](#任務執行（工具前言）) + - [自我反思程式碼](#自我反思代碼) + - [結構化分析](#結構化分析) + - [多輪對話](#多輪聊天) + - [逐步推理](#逐步推理) + - [受限輸出](#受限輸出) +- [你真正學到的是什麼](#你真正學到的是) +- [下一步](#後續步驟) ## 影片導覽 -觀看這段現場教學，說明如何開始使用本模組： +觀看本次直播說明，了解如何開始本模組： -使用 LangChain4j 的提示工程 - 現場教學 +使用 LangChain4j 的提示工程 - 直播 -## 你將學到什麼 +## 你將學習什麼 -以下圖示概述了本模組中你將發展的關鍵主題和技能——從提示精煉技巧到你將遵循的逐步工作流程。 +下圖提供本模組中你將學到的關鍵主題與技能概覽——從提示優化技巧到你將遵循的逐步工作流程。 -你將學到什麼 +你將學習什麼 -在前一個模組中，你探索了與 GitHub 模型的基本 LangChain4j 互動，並瞭解到記憶如何使 Azure OpenAI 實現對話式 AI。現在我們將專注於你如何提問——提示本身——使用 Azure OpenAI 的 GPT-5.2。你構建提示的方式會大幅影響回答的品質。我們先回顧基本的提示技巧，接著進入利用 GPT-5.2 能力的八個進階模式。 +在上一模組中，你了解了記憶如何透過 Azure OpenAI 啟動會話式 AI。現在，我們將專注於如何提出問題——也就是提示本身——使用 Azure OpenAI 的 GPT-5.2。你組織提示的方式會大幅影響你收到回應的品質。我們先回顧基本的提示技術，然後進入八種充分發揮 GPT-5.2 功能的進階模式。 -我們選用 GPT-5.2，是因為它引入了推理控制——你可以告訴模型在回應前要思考多少。這讓不同的提示策略變得更明顯，並幫助你瞭解何時使用哪種方法。我們也將受益於 Azure 相較 GitHub 模型對 GPT-5.2 的較低限制率。 +我們會使用 GPT-5.2，因為它引入了推理控制功能——你可以告訴模型回答前要思考多少。這讓不同的提示策略更為明顯，也幫助你理解何時該使用哪種方式。 ## 先決條件 -- 已完成模組 01（Azure OpenAI 資源已部署） -- 根目錄下有 `.env` 檔案，內含 Azure 憑證（由模組 01 中的 `azd up` 建立） +- 完成模組 01（部署了 Azure OpenAI 資源） +- 根目錄中有包含 Azure 憑證的 `.env` 文件（由模組 01 中的 `azd up` 建立） -> **注意：** 如果尚未完成模組 01，請先依照那裡的部署指南操作。 +> **注意：** 如果你尚未完成模組 01，請先遵循那裡的部署說明。 -## 理解提示工程 +## 了解提示工程 -本質上，提示工程是模糊指令和精確指令之間的差異，如下方比較所示。 +提示工程的核心是在於介於模糊指令與精確指令之間的差異，如下圖所示。 什麼是提示工程？ -提示工程旨在設計能穩定取得所需結果的輸入文字。它不只是在提問——而是組織請求，讓模型完全理解你想要什麼，以及該如何給出。 +提示工程是設計輸入文字，使你能穩定獲得所需結果。它不只是問問題——而是結構化請求，使模型完全理解你想要什麼以及如何交付。 -想像你在向同事下指示。「修正錯誤」很模糊。「在 UserService.java 第 45 行的 null pointer 例外中加入 null 檢查」則很具體。語言模型也是如此——具體性與結構很重要。 +想像你在給同事指示。「修正錯誤」是模糊的。「在 UserService.java 第 45 行透過新增空指標檢查修正空指標異常」則具體明確。語言模型也是一樣——具體和結構化很重要。 -以下圖示說明 LangChain4j 如何融入這個過程——通過 SystemMessage 和 UserMessage 這些基本組件，將你的提示模式連接到模型。 +下圖展示 LangChain4j 在此的角色——透過 SystemMessage 和 UserMessage 建立積木將你的提示模式連接到模型。 LangChain4j 的角色 -LangChain4j 提供基礎設施——模型連接、記憶與訊息類型——而提示模式則是你傳送過此基礎設施的精心結構化文字。關鍵組成是 `SystemMessage`（設定 AI 行為與角色）以及 `UserMessage`（承載你實際的請求）。 +LangChain4j 提供基礎設施——模型連接、記憶與訊息類型——而提示模式只不過是經過精心結構的文字，透過該基礎設施傳送。重要積木是 `SystemMessage`（設定 AI 行為與角色）與 `UserMessage`（承載你的實際請求）。 ## 提示工程基礎 -以下五個核心技巧構成有效提示工程的基礎。每項技巧針對你與語言模型溝通的不同面向。 +下方展示的五種核心技巧構成有效提示工程的基礎。每種技巧皆針對你與語言模型溝通的不同面向。 五種提示工程模式概覽 -在深入本模組的進階模式之前，讓我們回顧五種基礎提示技巧。這些是每位提示工程師應該掌握的基石。假如你已經完成了[快速入門模組](../00-quick-start/README.md#2-prompt-patterns)，你會見識到這些技巧的實際應用——以下是其概念框架。 +在探討本模組的進階模式之前，先回顧五種基礎提示技術。這是每個提示工程師應具備的基本技能。 -### 零樣本提示 +### 零次提示 -最簡單的方法：給模型直接指令而不附示例。模型完全依賴其訓練來理解並執行任務。這適用於期望行為明顯的簡單任務。 +最簡單的方式：給模型直接指示，不帶範例。模型完全依賴訓練去理解並執行任務。適合明確的直接需求。 -零樣本提示 +零次提示 -*不帶示例的直接指令——模型僅從指令推斷任務* +*無範例直接指示——模型根據指示推斷任務* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// 回應：「正面」 +// 回應:「正面」 ``` -**使用時機：** 簡單分類、直接問題、翻譯或任何模型無需額外指引便能處理的任務。 +**適用時機：** 簡單分類、直接問題、翻譯，或任何不需額外指導的任務。 -### 少量示例提示 +### 少次提示 -提供範例來展示你希望模型遵循的模式。模型從你的範例學習預期的輸入輸出格式，並應用至新輸入。這大幅提升需要特定格式或行為的任務一致性。 +提供範例示範你希望模型遵循的模式。模型從範例學習預期輸入輸出格式，並應用於新輸入。大幅提升格式或行為不明顯任務的一致性。 -少量示例提示 +少次提示 *從範例學習——模型識別模式並應用於新輸入* @@ -112,11 +112,11 @@ String prompt = """ String response = model.chat(prompt); ``` -**使用時機：** 自訂分類、一致的格式設定、領域專屬任務，或零樣本結果不穩定時。 +**適用時機：** 自訂分類、一致性格式、專業領域任務，或零次提示結果不穩定時。 ### 思路鏈 -要求模型逐步展示其推理過程。模型不直接給出答案，而是分解問題，明確執行每個步驟。這提升數學、邏輯與多步推理任務的準確度。 +要求模型逐步展開推理。模型不急著給答案，而是分解問題逐步說明。提升數學、邏輯及多步推理任務的準確度。 思路鏈提示 @@ -133,15 +133,15 @@ String response = model.chat(prompt); // 模型顯示：15 - 8 = 7，然後 7 + 12 = 19 個蘋果 ``` -**使用時機：** 數學題、邏輯謎題、除錯，或任何展示推理過程可增加準確性與信任度的任務。 +**適用時機：** 數學題、邏輯謎題、除錯，或任何需要展現推理過程以提升準確度與信賴度的任務。 -### 角色基礎提示 +### 基於角色的提示 -在提問前設定 AI 的身份或角色。此設定提供上下文，影響回答的語氣、深度與焦點。像是「軟體架構師」給出建議，會與「初級開發者」或「安全稽核員」不同。 +在提問前設定 AI 的身份或角色。提供上下文以影響回答的語氣、深度與焦點。「軟件架構師」給出建議與「初級開發者」或「安全審核員」不同。 -角色基礎提示 +基於角色的提示 -*設定上下文與角色——相同問題因分配角色而有不同回答* +*設定上下文與角色——同一問題依指定角色將獲得不同回答* ```java String prompt = """ @@ -157,15 +157,15 @@ String prompt = """ String response = model.chat(prompt); ``` -**使用時機：** 代碼審查、輔導、領域專屬分析，或需要依據不同專業水準或視角給出回應時。 +**適用時機：** 程式碼審查、教學、專業分析，或需要根據專業程度或角度調整回應。 ### 提示模板 -創建可重複使用且帶有變數佔位符的提示。不是每次都寫新提示，而是定義一份模板，然後填入不同的變數。LangChain4j 的 `PromptTemplate` 類用 `{{variable}}` 語法輕鬆實現。 +創建可重用的提示，使用變數佔位符。不必每次手寫提示，定義一次模板，填入不同值。LangChain4j 的 `PromptTemplate` 類別用 `{{variable}}` 語法讓此事變簡單。 提示模板 -*帶變數佔位符的可重用提示——一個模板，多種用途* +*含變數佔位符的可重複使用提示——一套模板，多重用途* ```java PromptTemplate template = PromptTemplate.from( @@ -180,27 +180,27 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` -**使用時機：** 重複查詢帶不同輸入、批量處理、建立可重複使用的 AI 工作流程，或任何提示結構相同但數據不同的場景。 +**適用時機：** 多次查詢不同輸入、批次處理、建構可重用 AI 工作流程，或任何提示結構相同但資料不同的情況。 --- -這五大基礎提供了絕大多數提示任務的堅實工具包。本模組餘下內容建立於此，聚焦 GPT-5.2 的推理控制、自我評估與結構化輸出功能的 **八個進階模式**。 +這五種基礎技巧為你提供大多數提示任務的扎實工具組。接著本模組將結合 GPT-5.2 的推理控制、自我評估與結構化輸出能力，介紹八種進階模式。 ## 進階模式 -基礎技能已覆蓋，接下來進入讓本模組獨特的八種進階模式。不是所有問題都需要一致方法。有些需要快速回答，有些則須深入思考。有的需要顯示推理過程，有的只要結果。以下模式各適不同場景——而 GPT-5.2 的推理控制使差異更為顯著。 +在基礎建立後，我們來看看本模組獨特的八種進階模式。不是所有問題都需要相同方法。有些問題需要快速回應，有些則需深入思考。有些需顯示推理，有些只要結果。以下各模式針對不同場景優化——GPT-5.2 的推理控制讓差異更鮮明。 八種提示工程模式 -*八種提示工程模式及其使用案例概覽* +八種提示工程模式及其應用場景概覽 -GPT-5.2 為這些模式加上一維度：*推理控制*。下方滑桿展示如何調整模型的思考力度——從快速直接回應到深入詳盡分析。 +GPT-5.2 對這些模式還增添一個維度：推理控制。下方滑桿展示如何調整模型的思考努力——從快速直接回答到深度徹底分析。 GPT-5.2 的推理控制 -*GPT-5.2 的推理控制讓你指定模型應思考多少——從快速直接回應到深入探索皆可* +*GPT-5.2 的推理控制讓你指定模型應思考多少——從快速直接到深入探索* -**低急迫感（快速且聚焦）** - 適用於需要快速、直接回答的簡單問題。模型進行最少推理，最多兩步。用於計算、查詢或直接問題。 +**低慾望（快速且專注）** - 用於簡單問題，想要快速直接回應。模型推理極少——最多兩步。適用計算、查詢或直白問題。 ```java String prompt = """ @@ -219,12 +219,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> 💡 **利用 GitHub Copilot 探索：** 開啟 [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) 並詢問： -> - 「低急迫感和高急迫感提示模式有何差異？」 -> - 「提示中的 XML 標籤如何幫助架構 AI 回答？」 -> - 「何時該使用自我反思模式，何時該使用直接指令？」 +> 💡 **使用 GitHub Copilot 探索：** 開啟 [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java)，詢問： +> - 「低慾望和高慾望提示模式有何異同？」 +> - 「提示中的 XML 標籤如何幫助結構化 AI 回答？」 +> - 「何時該使用自我反思模式或直接指令？」 -**高急迫感（深度且全面）** - 適用於需要全面分析的複雜問題。模型徹底探索並展示詳盡推理。用於系統設計、架構決策或複雜研究。 +**高慾望（深入且徹底）** - 用於複雜問題，需全面分析。模型全面探索，展示詳盡推理。適用系統設計、架構決策或複雜研究。 ```java String prompt = """ @@ -238,7 +238,7 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -**任務執行（逐步進展）** - 適用多步工作流程。模型提供事前規劃，邊做邊敘述每步，最後給出總結。適用於遷移、實作或任何多步流程。 +**任務執行（逐步進展）** - 用於多步工作流程。模型預先規劃，執行時逐步敘述，最後總結。適合遷移、執行、或任何多步流程。 ```java String prompt = """ @@ -276,20 +276,20 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -思路鏈提示明確要求模型展示推理過程，提升複雜任務的準確度。逐步拆解有助於人與 AI 理解邏輯。 +思路鏈提示明確要求模型展示推理過程，提升複雜任務準確率。逐步拆解幫助人類與 AI 理解邏輯。 -> **🤖 試試 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 詢問此模式： +> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天嘗試：** 詢問此模式： > - 「如何調整任務執行模式以處理長時間運行操作？」 -> - 「生產環境中如何最佳結構化工具前言？」 +> - 「生產應用中，結構化工具前置語的最佳實踐是什麼？」 > - 「如何在 UI 中捕捉並顯示中間進度更新？」 -以下圖說明此規劃 → 執行 → 總結工作流程。 +下圖說明此計劃 → 執行 → 總結流程。 任務執行模式 -*多步任務的規劃 → 執行 → 總結流程* +*計劃 → 執行 → 總結的多步任務工作流程* -**自我反思程式碼** - 用於產出生產等級代碼。模型生成符合生產標準且具適當錯誤處理的程式碼。用於建置新功能或服務。 +自我反思程式碼 - 生成符合生產標準的程式碼。模型產出有錯誤處理的優質代碼。適合建構新功能或服務時使用。 ```java String prompt = """ @@ -300,13 +300,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下圖示範此反覆迭代改進迴圈——生成、評估、找出弱點，並持續優化直至符合生產標準。 +下圖展示此迭代改進循環——生成、評估、找出弱點，再改進，直到符合生產標準。 自我反思循環 -*迭代改進迴圈——生成、評估、識別問題、改善、重複* +*迭代改進循環 - 產生、評估、找問題、改進、重複* -**結構化分析** - 用於一致性評估。模型使用固定架構檢視代碼（正確性、實務、效能、安全、可維護性）。用於程式碼審查或品質評估。 +結構化分析 - 用於一致性評價。模型使用固定架構檢視程式碼（正確性、實踐、效能、安全性、可維護性）。適合程式碼審查或品質評估。 ```java String prompt = """ @@ -354,18 +354,18 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -> **🤖 試試 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 詢問結構化分析： -> - 「如何針對不同類型程式碼審查自訂分析框架？」 -> - 「程式化解析並處理結構化輸出的最佳方式是什麼？」 -> - 「如何確保不同審查會議中嚴重性等級一致？」 +> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天嘗試：** 詢問結構化分析： +> - 「如何為不同程式碼審查自訂分析架構？」 +> - 「如何最有效程式化解析並採用結構化輸出？」 +> - 「如何確保不同審查會話中嚴重性級別一致？」 -下圖顯示此結構化框架如何組織程式碼審查，將檢視內容劃分為一致類別並配有嚴重性等級。 +下圖展示此結構化架構如何組織程式碼審查為一致分類及嚴重度等級。 結構化分析模式 -*帶嚴重性等級的一致性程式碼審查框架* +用於一致程式碼審查的帶嚴重度等級的框架 -**多輪對話** - 適合需要上下文的對話。模型記憶前訊息並基於此持續構建回應。適用於互動式協助或複雜問答。 +多輪對話 - 用於需要上下文的對話。模型記住先前訊息並基於它們回應。適合互動式協助會話或複雜 QA。 ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -379,12 +379,13 @@ AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` -下圖視覺化說明對話上下文如何隨輪次累積以及它與模型 token 限制的關係。 +下圖視覺化對話上下文如何隨多輪累積，以及其與模型 token 限制的關係。 上下文記憶 -*對話上下文隨多輪累積直到達到 token 限制* -**逐步推理** - 用於需要顯示邏輯的問題。模型會對每一步驟進行明確推理。適用於數學問題、邏輯謎題或當你需要理解思考過程時使用。 +*多輪對話中對話上下文如何累積直到到達 token 限制* + +逐步推理 - 適用需顯示具體邏輯的問題。模型對每一步驟顯示明確推理。用於數學題、邏輯謎題，或需要理解思考過程時。 ```java String prompt = """ @@ -398,13 +399,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下圖展示模型如何將問題拆分成明確編號的邏輯步驟。 +下圖說明模型如何將問題拆解為明確編號的邏輯步驟。 -Step-by-Step Pattern +逐步模式 -*將問題拆解為明確的邏輯步驟* +將問題拆解為明確的邏輯步驟 -**受限輸出** - 用於具有特定格式要求的回應。模型嚴格遵守格式和長度規則。適用於摘要或需要精確輸出結構時。 +受限輸出 - 用於需要特定格式要求的回應。模型嚴格遵守格式和長度規則。用於摘要或需要精確輸出結構時。 ```java String prompt = """ @@ -420,9 +421,9 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下圖展示約束如何引導模型產生嚴格遵守格式和長度要求的輸出。 +下圖顯示約束如何引導模型產生嚴格遵守您格式和長度要求的輸出。 -Constrained Output Pattern +受限輸出模式 *強制執行特定格式、長度和結構要求* @@ -430,11 +431,11 @@ String response = chatModel.chat(prompt); **驗證部署：** -確保在根目錄存在帶有 Azure 憑證的 `.env` 檔案（在模組 01 創建）。從模組目錄 (`02-prompt-engineering/`) 執行此命令： +確保根目錄存在 `.env` 文件，裡面有 Azure 資料（在模塊 01 中建立）。從模塊目錄 (`02-prompt-engineering/`) 運行： **Bash:** ```bash -cat ../.env # 應顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` **PowerShell:** @@ -444,27 +445,27 @@ Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT **啟動應用程式：** -> **注意：** 如果你已經從根目錄使用 `./start-all.sh` 啟動所有應用程式（如模組 01 所述），則此模組已在 8083 埠運行。你可以跳過以下啟動命令，直接訪問 http://localhost:8083。 +> **注意：** 如果您已經使用根目錄的 `./start-all.sh` 啟動所有應用程式（如模塊 01 所述），本模塊已在 8083 埠運行。您可以跳過下面的啟動指令，直接訪問 http://localhost:8083。 -**選項 1：使用 Spring Boot 儀表板（推薦 VS Code 用戶）** +**選項 1：使用 Spring Boot 控制面板（建議 VS Code 用戶）** -開發容器包含 Spring Boot 儀表板擴充套件，提供視覺化介面管理所有 Spring Boot 應用程式。你可以在 VS Code 左側的活動列找到它（尋找 Spring Boot 圖示）。 +開發容器包含 Spring Boot 控制面板擴展，可視覺化管理所有 Spring Boot 應用程式。您可以在 VS Code 左側的活動欄找到（尋找 Spring Boot 圖示）。 -透過 Spring Boot 儀表板，你可以： +透過 Spring Boot 控制面板，您可以： - 查看工作區中所有可用的 Spring Boot 應用程式 - 一鍵啟動/停止應用程式 -- 實時查看應用程式日誌 +- 即時檢視應用程式日誌 - 監控應用程式狀態 -只需點擊 "prompt-engineering" 旁的播放按鈕啟動此模組，或一次啟動所有模組。 +只需點擊 "prompt-engineering" 旁的播放按鈕就能啟動本模塊，或一次啟動所有模塊。 -Spring Boot Dashboard +Spring Boot 控制面板 -*VS Code 中的 Spring Boot 儀表板 — 從一處啟動、停止並監控所有模組* +*VS Code 中的 Spring Boot 控制面板 — 從一處啟動、停止並監控所有模塊* **選項 2：使用 Shell 腳本** -啟動所有網頁應用程式（模組 01-04）： +啟動所有 Web 應用程式（模塊 01-04）： **Bash:** ```bash @@ -478,7 +479,7 @@ cd .. # 從根目錄 .\start-all.ps1 ``` -或單獨啟動此模組： +或只啟動本模塊： **Bash:** ```bash @@ -492,9 +493,9 @@ cd 02-prompt-engineering .\start.ps1 ``` -兩個腳本會自動從根目錄的 `.env` 檔案載入環境變數，並在不存在 JAR 時進行編譯。 +兩個腳本會自動從根目錄 `.env` 文件載入環境變數，並在 JAR 不存在時編譯。 -> **注意：** 若你想在啟動前手動編譯所有模組： +> **注意：** 若您希望在啟動前手動編譯所有模塊： > > **Bash:** > ```bash @@ -508,13 +509,13 @@ cd 02-prompt-engineering > mvn clean package -DskipTests > ``` -在你的瀏覽器中打開 http://localhost:8083 。 +在瀏覽器中開啟 http://localhost:8083。 -**停止：** +**停止應用程式：** **Bash:** ```bash -./stop.sh # 僅限於此模組 +./stop.sh # 僅此模組 # 或者 cd .. && ./stop-all.sh # 所有模組 ``` @@ -528,81 +529,81 @@ cd ..; .\stop-all.ps1 # 所有模組 ## 應用程式截圖 -這是 prompt engineering 模組的主介面，你可以並排嘗試所有八種範式。 +這是提示工程模塊的主界面，您可以在此同時試驗所有八種模式。 -Dashboard Home +首頁控制面板 -*主儀表板展示所有 8 種提示工程範式及其特點和使用案例* +*主控制面板顯示所有 8 種提示工程模式及其特性和使用場景* -## 探索範式 +## 探索模式 -網頁介面讓你嘗試不同的提問策略。每個範式解決不同問題 — 嘗試看看何時每種方法最合適。 +Web 介面讓您試驗不同的提示策略。每種模式解決不同問題，嘗試看看每種方法在何時特別有效。 -> **注意：串流與非串流** — 每個範式頁面均提供兩個按鈕：**🔴 串流回應（即時）** 與 **非串流** 選項。串流使用伺服器發送事件（SSE）即時顯示模型生成的字元，因此你能立即看到回應進度。非串流選項則等待整個回應完成才顯示。對於觸發深度推理的提示（例如，高熱忱、自我反思代碼），非串流呼叫可能花費很長時間 — 有時甚至數分鐘 — 沒有任何可見反饋。**在試驗複雜提示時請使用串流功能**，既可見模型運作，也避免誤以為請求超時。 +> **注意：串流與非串流** — 每個模式頁面提供兩個按鈕：**🔴 串流回應（實時）** 和 非串流 選項。串流使用伺服器發送事件 (SSE)，在模型生成令牌時即時顯示，您可即時看到進展。非串流選項則會等整個回應完成後才顯示。對於需要深度推理的提示（如高積極性、自我反思代碼），非串流可能等很久，有時需數分鐘且無任何可見回饋。**在試驗複雜提示時請使用串流，這樣您可看到模型運作，避免誤以為請求逾時。** > -> **注意：瀏覽器要求** — 串流功能使用 Fetch Streams API（`response.body.getReader()`），需完整瀏覽器支援（Chrome、Edge、Firefox、Safari）。 VS Code 內建的 Simple Browser 不支援 ReadableStream API，故無法串流。使用 Simple Browser 時，非串流按鈕仍正常，只有串流按鈕受影響。請用外部瀏覽器開啟 `http://localhost:8083` 以獲得完整體驗。 +> **注意：瀏覽器需求** — 串流功能使用 Fetch Streams API（`response.body.getReader()`），需要完整瀏覽器（Chrome、Edge、Firefox、Safari）。VS Code 內建簡易瀏覽器不支援 ReadableStream API，因此不適用。若使用簡易瀏覽器，非串流按鈕仍正常工作，僅串流按鈕受影響。請使用外部瀏覽器開啟 `http://localhost:8083` 以獲得完整體驗。 -### 低熱忱 vs 高熱忱 +### 低 vs 高積極性 -用低熱忱提問簡單問題，如「15% 的 200 是多少？」將獲得即時且直接的答案。現在用高熱忱提問複雜問題，如「設計一個高流量 API 的快取策略」。點擊 **🔴 串流回應（即時）**，觀看模型詳細推理逐字元顯現。是同一模型，同一問題結構 — 但提示決定了思考深度。 +使用低積極性提問「200 的 15% 是多少？」會立即得到直接答案。改用高積極性提問「設計高流量 API 的快取策略」。點擊 **🔴 串流回應（實時）**，觀看模型逐字推理展開。相同模型、同樣問題結構，但提示決定模型思考深度。 -### 任務執行（工具前置語） +### 任務執行（工具前言） -多步工作流受益於事先規劃與過程敘述。模型會概述要做的事，敘述每步，最後總結結果。 +多步驟工作流程受益於事前規劃和過程講述。模型會先概述將做什麼，逐步說明，再總結結果。 ### 自我反思代碼 -嘗試「建立一個電郵驗證服務」。模型不只是生成代碼並停下，而是生成、依品質標準評估、找出弱點並改進。你會看到它反覆迭代，直至代碼符合生產標準。 +嘗試「建立 email 驗證服務」。模型不只是生成代碼並停止，而是生成後依品質標準評估，找出弱點並改進。您將看到它反覆迭代直到代碼符合生產標準。 ### 結構化分析 -程式碼審查需一致評估框架。模型使用固定類別（正確性、實踐、效能、安全性）及嚴重程度分析代碼。 +代碼審查需要一致的評估框架。模型依固定分類（正確性、慣例、性能、安全）並搭配嚴重程度進行分析。 -### 多輪對話 +### 多輪聊天 -提問「什麼是 Spring Boot？」，緊接著再問「舉例說明」。模型記得第一個問題，並給你一個具體的 Spring Boot 範例。沒有記憶，第二個問題太模糊。 +問「什麼是 Spring Boot？」接著立刻追問「給我一個範例」。模型記住你的第一個問題，並給出具體的 Spring Boot 範例。無記憶，第二個問題會太模糊。 ### 逐步推理 -挑選數學問題，用逐步推理和低熱忱測試。低熱忱快速給答案，但不透明。逐步推理則展示所有計算和判斷。 +挑選數學問題，分別用逐步推理和低積極性嘗試。低積極性只給答案 — 快而難理解。逐步推理展示所有計算和判斷過程。 ### 受限輸出 -需要特定格式或字數時，此範式強制嚴格遵守。試著生成精確 100 字的列點摘要。 +當您需要特定格式或字數時，這種模式嚴格執行。試著生成正好 100 字的重點摘要。 -## 你真正學到的 +## 你真正學到的是 -**推理努力改變一切** +推理努力改變一切 -GPT-5.2 讓你透過提示控制計算努力。低努力意味快速回應、最少探索。高努力則意謂模型花時間深入思考。你在學習根據任務複雜度匹配努力 — 簡單問題不要浪費時間，複雜決策也不要急促。 +GPT-5.2 讓您透過提示控制計算努力程度。低努力代表快速回應、探索少。高努力意指模型投注時間深度思考。您正在學習根據任務複雜度調整努力 — 簡單問題不用浪費時間，複雜決策也別急促。 -**結構引導行為** +結構引導行為 -注意提示中的 XML 標籤？它們不是裝飾品。模型比自由文本更可靠地遵循結構化指令。需要多步驟流程或複雜邏輯時，結構有助模型追蹤進度和下一步。下圖將一個結構良好的提示拆解，顯示 ``, ``, ``, ``, `` 等標籤如何將指令劃分清晰區塊。 +注意提示中的 XML 標籤？它們非裝飾。模型比起自由文本，更可靠遵守有結構的指令。需要多步或複雜邏輯時，結構協助模型追蹤進度和接續動作。下圖拆解一個結構良好的提示，展示 ``, ``, ``, ``, `` 等標籤如何將指令劃分成清晰區塊。 -Prompt Structure +提示結構 -*結構良好提示的解剖，有清晰區段和 XML 風格組織* +*一個結構良好提示的結構剖析，清晰區塊與 XML 式組織* -**品質來自自我評估** +自我評估提升品質 -自我反思範式透過明確品質標準工作。你不再希望模型「表現正確」，而是直接告訴它「正確」定義為：邏輯正確、錯誤處理、效能、安全。這使模型能評估自身輸出並改進。代碼生成從抽獎變成流程。 +自我反思模式透過明確品質標準運作。不再寄望模型「做對」，而是指明「對」意指何物：正確邏輯、錯誤處理、性能、安全。模型能自我評估輸出並改進。將代碼生成從抽獎變成穩定流程。 -**上下文有限** +上下文是有限的 -多輪對話通過每次請求包含訊息歷史來運作。但有字元限制 — 每個模型有最大字元數。隨對話成長，你將學習策略保持相關上下文而不超限。本模組展示記憶機制；稍後你會知道何時總結、忘記及檢索。 +多輪對話靠附帶訊息歷史實現。但有上限——每個模型的最大令牌數有限。對話愈長，您需用策略保持相關上下文同時不超限。本模塊展示記憶如何運作；之後您將學習何時摘要、遺忘及召回。 -## 下一步 +## 後續步驟 -**下一模組：** [03-rag - RAG（檢索增強生成）](../03-rag/README.md) +**下一模塊：** [03-rag - RAG (檢索增強生成)](../03-rag/README.md) --- -**導覽：** [← 上一個：模組 01 - 介紹](../01-introduction/README.md) | [回主頁](../README.md) | [下一個：模組 03 - RAG →](../03-rag/README.md) +**導覽：** [← 上一節：模塊 01 - 簡介](../01-introduction/README.md) | [返回主頁](../README.md) | [下一節：模塊 03 - RAG →](../03-rag/README.md) --- **免責聲明**： -本文件係使用人工智能翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們致力於確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件之母語版本應被視為權威來源。對於重要資訊，建議採用專業人工作翻譯。我們對因使用本翻譯而引致之任何誤解或誤譯概不負責。 +本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。 \ No newline at end of file diff --git a/translations/zh-MO/03-rag/README.md b/translations/zh-MO/03-rag/README.md index 6733646bd..058eeedf4 100644 --- a/translations/zh-MO/03-rag/README.md +++ b/translations/zh-MO/03-rag/README.md @@ -2,143 +2,142 @@ ## 目錄 -- [影片導讀](../../../03-rag) -- [你將學到的內容](../../../03-rag) -- [先決條件](../../../03-rag) -- [理解 RAG](../../../03-rag) - - [本教程使用哪種 RAG 方法？](../../../03-rag) -- [運作原理](../../../03-rag) - - [文件處理](../../../03-rag) - - [建立嵌入](../../../03-rag) - - [語義搜尋](../../../03-rag) - - [答案生成](../../../03-rag) -- [運行應用程式](../../../03-rag) -- [使用應用程式](../../../03-rag) - - [上傳文件](../../../03-rag) - - [提問](../../../03-rag) - - [檢查來源參考](../../../03-rag) - - [實驗問題](../../../03-rag) -- [關鍵概念](../../../03-rag) - - [分塊策略](../../../03-rag) - - [相似度分數](../../../03-rag) - - [記憶體儲存](../../../03-rag) - - [上下文視窗管理](../../../03-rag) -- [何時 RAG 很重要](../../../03-rag) -- [下一步](../../../03-rag) - -## 影片導讀 - -觀看這場直播說明如何開始使用本模組： - -LangChain4j 的 RAG - 直播課程 - -## 你將學到的內容 - -在前面的模組中，你學會了如何與 AI 對話及有效組織提示詞，但有個根本限制：語言模型僅知道訓練期間學到的知識。它無法回答關於你的公司政策、專案文件或任何未被訓練過的資訊。 - -RAG（檢索增強生成）解決了這個問題。與其嘗試教模型你的資料（既昂貴又不實際），你給它能力去搜尋你的文件。當有人提問時，系統找出相關資訊並納入提示中。模型再根據檢索到的上下文作答。 - -你可以把 RAG 想像成給模型一個參考圖書館。當你提問時，系統： - -1. **使用者查詢** – 你提出問題 -2. **嵌入** – 將你的問題轉成向量 -3. **向量搜尋** – 找出相似文件塊 -4. **上下文組合** – 將相關塊加入提示 -5. **回應** – LLM 根據上下文產生答案 - -這讓模型的回應有根據你的實際資料，而非僅依賴訓練知識或自己杜撰答案。 +- [影片導覽](#影片導覽) +- [您將學到的內容](#您將學到的內容) +- [先決條件](#先決條件) +- [理解 RAG](#理解-rag) + - [本教程使用哪種 RAG 方法？](#本教程使用哪種-rag-方法？) +- [運作原理](#運作原理) + - [文件處理](#文件處理) + - [建立嵌入向量](#建立嵌入向量) + - [語義搜尋](#語義搜尋) + - [生成回答](#答案生成) +- [執行應用程式](#運行應用程式) +- [使用應用程式](#使用應用程式) + - [上傳文件](#上載文件) + - [提問](#提問) + - [查看來源參考](#檢查來源參考) + - [試驗提問](#試驗提問) +- [關鍵概念](#主要概念) + - [切塊策略](#分片策略) + - [相似度分數](#相似度分數) + - [記憶體儲存](#記憶體存儲) + - [上下文視窗管理](#上下文視窗管理) +- [何時 RAG 才重要](#何時使用-rag) +- [後續步驟](#後續步驟) + +## 影片導覽 + +觀看這個現場說明會，了解如何開始本模組： + +RAG with LangChain4j - Live Session + +## 您將學到的內容 + +在之前的模組中，您學習了如何與 AI 對話以及有效結構化提示。但這有一個根本限制：語言模型只知道它們在訓練期間學到的知識。它們無法回答關於您公司政策、項目文件或任何未受訓練資訊的問題。 + +RAG（檢索增強生成）解決了這個問題。它不是試圖教模型您的資訊（這既昂貴又不切實際），而是賦予模型能夠在您的文件中搜尋的能力。當有人提問時，系統找到相關資訊並將其包含在提示中。模型接著根據檢索到的上下文回答。 + +將 RAG 想像成給模型提供一個參考資料庫。當您提問時，系統： + +1. 使用者查詢 — 您提出問題 +2. 嵌入向量 — 將您的問題轉換為向量 +3. 向量搜尋 — 找出類似的文件切塊 +4. 上下文組合 — 將相關切塊加入提示 +5. 回應 — 大型語言模型根據上下文產生答案 + +這使模型的回答立足於您的真實資料，而不是依賴訓練知識或捏造答案。 ## 先決條件 -- 完成 [Module 00 - Quick Start](../00-quick-start/README.md)（後續本模組參考的 Easy RAG 範例） -- 完成 [Module 01 - Introduction](../01-introduction/README.md)（部署 Azure OpenAI 資源，包括 `text-embedding-3-small` 嵌入模型） -- 專案根目錄有 `.env` 檔案並含 Azure 憑證（由 Module 01 的 `azd up` 指令建立） +- 完成 [Module 01 - Introduction](../01-introduction/README.md)（部署完 Azure OpenAI 資源，包括 `text-embedding-3-small` 嵌入模型） +- 根目錄有 `.env` 檔案，包含 Azure 憑證（由 Module 01 的 `azd up` 指令產生） -> **注意：** 若尚未完成 Module 01，請先依那邊的部署說明進行。`azd up` 指令會部署本模組使用的 GPT 聊天模型與嵌入模型。 +> **注意：** 如果尚未完成 Module 01，請先依該模組的部署指示操作。`azd up` 指令會部署 GPT 聊天模型和本模組所使用的嵌入模型。 ## 理解 RAG -下圖展示核心概念：不僅依賴模型訓練資料，RAG 是先給模型一個你的文件參考庫，讓它在每次生成答案前先查閱。 +下面的圖示說明了核心概念：RAG 不只依賴模型的訓練數據，而是讓模型有一個您的文件參考資料庫，在生成每個回答前先查閱。 -什麼是 RAG +What is RAG -*此圖示出標準 LLM（僅根據訓練資料猜測）與 RAG 增強 LLM（先查閱你的文件）的差異。* +*此圖顯示了標準大型語言模型（從訓練數據猜測）與加強了 RAG 的大型語言模型（先查閱您的文件）的差異。* -以下展示整個流程如何串接：使用者的問題經過四個階段 —— 嵌入、向量搜尋、上下文組合、答案生成 —— 每個階段都建立在前一個基礎上： +以下是整體流程的端到端連結。使用者的提問經過四個階段—嵌入、向量搜尋、上下文組合、回答生成—每步接續上一步： -RAG 架構 +RAG Architecture -*此圖展示完整 RAG 流程 — 使用者查詢依序通過嵌入、向量搜尋、上下文組合與答案生成階段。* +*此圖展示完整 RAG 管線—使用者查詢經過嵌入、向量搜尋、上下文組合及回答生成。* -接下來模組將詳細說明每個階段，並附上可執行與修改的程式碼。 +本模組的其餘部分將逐步詳細講解每個階段，並附上可執行及可修改的程式碼。 ### 本教程使用哪種 RAG 方法？ -LangChain4j 提供三種實作 RAG 的方式，各有不同抽象層次。下圖比較這三者： +LangChain4j 提供三種實現 RAG 的方式，各有不同抽象層級。以下圖比較它們： -LangChain4j 三種 RAG 方法 +Three RAG Approaches in LangChain4j -*此圖比較 LangChain4j 的 Easy、Native、Advanced 三種 RAG 方法，說明其主要組件與使用時機。* +*此圖比較 LangChain4j 的三種 RAG 方法—Easy、Native 與 Advanced—展示其主要元件及適用時機。* -| 方法 | 功能描述 | 取捨 | +| 方法 | 功能說明 | 權衡取捨 | |---|---|---| -| **Easy RAG** | 透過 `AiServices` 和 `ContentRetriever` 自動連接所有流程。你只需註解接口、掛載檢索器，LangChain4j 幕後處理嵌入、搜尋及提示組裝。 | 程式碼最少，但看不到每步驟細節。 | -| **Native RAG** | 你明確呼叫嵌入模型、搜尋資料庫、建立提示並生成答案 —— 每一步都清楚呈現。 | 程式碼較多，但每階段均可見且可修改。 | -| **Advanced RAG** | 利用 `RetrievalAugmentor` 框架，擁有可插拔查詢轉換器、路由器、重排器與內容注入器，適合生產級流程。 | 靈活性最高，但也複雜度最高。 | +| **Easy RAG** | 透過 `AiServices` 與 `ContentRetriever` 自動連接所有流程。您註解介面，附加取回器，LangChain4j 自動負責嵌入、搜尋與提示組合。 | 代碼最少，但無法看到每個階段的細節。 | +| **Native RAG** | 您自行呼叫嵌入模型、搜尋儲存、建立提示及生成答案—每一步都明確操作。 | 代碼較多，但每個階段皆明確且可調整。 | +| **Advanced RAG** | 使用 `RetrievalAugmentor` 框架，具備可插拔的查詢轉換器、路由器、重排序器與內容注入器，適用生產級管線。 | 柔韌性最高，但複雜度也最高。 | -**本教程採用 Native 方法。** RAG 流程中每一步 —— 問題嵌入、向量庫搜尋、上下文組合、答案生成 —— 均在 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 明確寫出。這是刻意設計：作為學習資源，讓你看到並理解每個階段比單純縮短程式碼重要。一旦熟悉流程再考慮用 Easy RAG 快速原型或 Advanced RAG 建立生產系統。 +**本教程使用 Native 方法。** 每個 RAG 階段—查詢的向量嵌入、在向量庫搜尋、上下文組合及答案生成—都在 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 明確撰寫。這是故意的：作為學習資源，讓您看見並理解每個階段比簡化代碼更重要。熟悉後，您可轉向 Easy RAG 進行快速原型，或者 Advanced RAG 構建生產系統。 -> **💡 已看過 Easy RAG 範例？** [Quick Start 模組](../00-quick-start/README.md) 有 Document Q&A 範例 ([`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)) 使用 Easy RAG —— LangChain4j 幕後自動處理嵌入、搜尋和提示組裝。本模組進一步拆解流程，讓你看見並控制每階段。 +> **💡想了解 Easy RAG？** LangChain4j 也提供 *Easy RAG* 方法，由 `AiServices` 和 `ContentRetriever` 自動處理嵌入、搜尋與提示組合。本模組採用較顯式的路徑—拆解管線，讓您自主控制每個階段。 -下圖展示 Quick Start 範例中 Easy RAG 流程。請注意 `AiServices` 與 `EmbeddingStoreContentRetriever` 隱藏了整個複雜度 —— 你只需載入文件、掛載檢索器，便可得到答案。本模組的 Native 方法則拆解這些幕後步驟： +以下圖展示 Easy RAG 管線。注意 `AiServices` 及 `EmbeddingStoreContentRetriever` 將所有複雜流程隱藏—您只需載入文件，附加取回器，即能獲取答案。本模組的 Native 方法拆開了這些隱藏步驟： -LangChain4j Easy RAG 流程 +Easy RAG Pipeline - LangChain4j -*此圖展示 `SimpleReaderDemo.java` 的 Easy RAG 流程。和本模組使用的 Native 方法對比：Easy RAG 把嵌入、檢索、提示組裝隱藏在 `AiServices` 與 `ContentRetriever` 之後 — 你載入文件、掛載檢索器後直接取得答案；Native 則拆解流程，讓你自己呼叫每一步（嵌入、檢索、組合上下文、生成），提供完整可見性及控制權。* +*此圖展示 Easy RAG 管線。與本模組的 Native 方法比較：Easy RAG 將嵌入、搜尋和提示組合隱藏於 `AiServices` 與 `ContentRetriever` 後。您載入文件、附加取回器，即可獲答案。Native 方法將管線打開，您自行呼叫每個階段（嵌入、搜尋、組合上下文、生成），擁有完整可視性與控制權。* ## 運作原理 -本模組的 RAG 流程分成四個階段，每次使用者提問時依序執行。首先，將上傳的文件**解析並切分**成便於處理的小塊。接著將這些小塊轉成**向量嵌入**並儲存，方便數學比較。當查詢來臨時，系統執行**語義搜尋**找出最相關的小塊，最後將它們作為上下文傳入 LLM，進行**答案生成**。以下章節搭配實際程式碼與圖解介紹各階段。先看第一步。 +本模組的 RAG 管線分為四個階段，當使用者提問時連續執行。首先，上傳的文件被解析及切塊成可管理的小段。這些切塊再轉成向量嵌入並存儲，以便進行數學比對。查詢來時，系統執行語義搜尋找出最相關切塊，最後將它們作為上下文傳給大型語言模型，進行答案生成。以下章節將透過程式碼與圖示逐步說明每個階段。先從第一步開始。 ### 文件處理 [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -當你上傳文件，系統將其解析（PDF 或純文字格式），附加檔案名稱等元資料，然後切成小塊 — 即適合模型上下文視窗的小段。這些小塊會有些重疊，避免邊界處遺失重要上下文。 +當您上傳文件時，系統會解析文件（PDF 或純文字），附加檔名等元資料，然後將其切成切塊—較小的片段，方便放入模型的上下文視窗。這些切塊間有些微重疊，以避免在邊界丟失上下文。 ```java -// 解析上載的檔案並將其包裝在 LangChain4j 文件中 +// 解析上傳的檔案並包裝成 LangChain4j 文件 Document document = Document.from(content, metadata); -// 分割成300標記的區塊，重疊30標記 +// 分割成300字元區塊，重疊30字元 DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` -下圖視覺化說明此過程。可見每個分塊與相鄰分塊間共享部分標記符 —— 30 標記的重疊確保不遺漏重要上下文： +下圖直觀展示此過程。注意每個切塊與鄰近切塊共享部分標記—30標記的重疊確保重要上下文不會落入空白： -文件分塊 +Document Chunking -*此圖展示文件被切成 300 標記大小、30 標記重疊的小塊，保留分塊邊界的上下文。* +*此圖展示文件切成 300 標記切塊，彼此重疊 30 標記，保存了切塊邊界處的上下文。* -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試看：** 開啟 [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) 並問： -> - 「LangChain4j 如何將文件切成小塊，為何重疊很重要？」 -> - 「不同文件類型的最佳分塊大小是多少，為什麼？」 -> - 「如何處理多語言或帶特殊格式的文件？」 +> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) 聊天試試看：** 開啟 [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java)，並問： +> - 「LangChain4j 如何將文件拆分為切塊？為何重疊很重要？」 +> - 「不同文件類型最佳切塊大小為何？為什麼？」 +> - 「如何處理多語言文件或有特殊格式的文件？」 -### 建立嵌入 +### 建立嵌入向量 [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -每個分塊會被轉成稱為嵌入的數值表示 —— 本質上是意義到數字的轉換器。嵌入模型不同於聊天模型，它不「智能」，無法執行指令、推理或回答問題。但它能把文字映射到數學空間，使相近意義的詞彙相近 —— 例如「car」接近「automobile」；「refund policy」接近「return my money」。你可把聊天模型想像成可以對話的人，嵌入模型則是一個超優秀的資料編目系統。 +每個切塊會轉換為一組數字表示，稱為嵌入向量—本質上就是將意義轉成數字。嵌入模型不像聊天模型具備「智能」；它無法執行指令、推理或回答問題。嵌入模型能做的是將文字映射到數學空間，讓相似意義靠得更近—例如「汽車」靠近「汽車（automobile）」、「退貨政策」靠近「退款條款」。可把聊天模型想成您可以對話的人，嵌入模型則像超棒的檔案整理系統。 -下圖呈現這概念 —— 文字進去，數值向量出來，相似意義彼此靠近： +下圖可視化此概念—文字輸入，數字向量輸出，意味相近的向量彼此鄰近： -嵌入模型概念 +Embedding Model Concept -*此圖展示嵌入模型如何將文字轉為數字向量，將意義相近的詞（如「car」與「automobile」）聚集在向量空間中。* +*此圖示意嵌入模型如何將文字轉為數字向量，並在向量空間中讓相似意義（如「車」與「汽車」）鄰近排列。* ```java @Bean @@ -154,29 +153,29 @@ EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` -下圖類別圖展示 RAG 流程中的兩條分支及 LangChain4j 的對應類別。**導入流程**（上傳時執行一次）負責文件切分、分塊嵌入及通過 `.addAll()` 存至向量庫。**查詢流程**（每次提問時執行）會將問題嵌入、用 `.search()` 搜尋庫，再將匹配的上下文傳給聊天模型。兩者藉由共用的 `EmbeddingStore` 介面對接： +下圖顯示 RAG 管線的兩個不同流程與 LangChain4j 的類別實現。匯入流程在上傳時運行一次，拆分文件、嵌入切塊、並透過 `.addAll()` 儲存。查詢流程每次使用者提問時執行，先嵌入問題，透過 `.search()` 搜尋儲存庫，將匹配的上下文傳給聊天模型。兩者共享介面 `EmbeddingStore` 連接： -LangChain4j RAG 類別 +LangChain4j RAG Classes -*此圖展示 RAG 流程中的兩個分支：導入與查詢，並說明它們如何經由共用 EmbeddingStore 互連。* +*此圖展示 RAG 管線的兩個流程—匯入與查詢—以及它們如何透過共用的 EmbeddingStore 互聯。* -嵌入一旦存入，相關內容自然在向量空間聚集。下圖顯示關於相似主題的文件會成為鄰近的點，正是語義搜尋的基礎： +嵌入儲存後，相似内容在向量空間自然聚集。下圖說明相關主題的文件如何聚集為鄰近點，使語義搜尋成真： -向量嵌入空間 +Vector Embeddings Space -*此圖視覺化展示技術文件、商業規則、FAQ 等主題如何在三維向量空間聚集成不同群組。* +*此視覺化展示相關文件如何在三維向量空間中聚集，技術文件、商業規則與常見問答形成不同群組。* -當使用者搜尋時，系統執行四步驟：文件嵌入一次（導入）、每次搜尋問題嵌入，利用餘弦相似度比較問題向量與所有存儲向量，返回分數最高的前 K 個分塊。下圖說明每步與相應的 LangChain4j 類別： +當使用者搜尋時，系統採四步驟：文件嵌入一次，查詢每次嵌入，利用餘弦相似度比較查詢向量與所有儲存向量，並回傳前 K 個得分最高的切塊。以下圖解說每步及對應 LangChain4j 類別： -嵌入搜尋步驟 +Embedding Search Steps -*此圖展示四步嵌入搜尋流程：文件嵌入、查詢嵌入、透過餘弦相似度比較向量，及返回前 K 結果。* +*此圖展示四步嵌入搜尋流程：嵌入文件，嵌入查詢，利用餘弦相似度比較向量，回傳排名前 K 的結果。* ### 語義搜尋 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -當你提問，你的問題同樣會被轉成嵌入向量。系統將問題向量與所有文件分塊向量比較，找出意義最相近的分塊 —— 不只是關鍵字匹配，而是全方位語義相似。 +當您提出問題時，該問題也會被轉成嵌入向量。系統比較您的問題嵌入向量與所有文件切塊的嵌入向量，找出意義最相近的切塊—不只是關鍵字匹配，而是真正的語義相似。 ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -196,27 +195,27 @@ for (EmbeddingMatch match : matches) { } ``` -下圖比較語義搜尋與傳統關鍵字搜尋。關鍵字搜尋若搜尋「vehicle」會錯過描述「cars and trucks」的分塊，但語義搜尋理解兩者意義相同，且將其列為高分匹配： +下圖對比語義搜尋與傳統關鍵字搜尋。關鍵字搜尋「vehicle」會漏掉提及「汽車與卡車」的切塊，而語義搜尋因理解它們意義相同，將此切塊作為高分匹配返回： -語義搜尋 +Semantic Search -*此圖比較基於關鍵字與語義的搜尋方式，展示語義搜尋可檢索到概念相關內容，即使具體關鍵字不同。* -底層中，相似度是透過餘弦相似度來測量 — 本質上是在問「這兩個箭頭是否指向相同方向？」兩段文字可以使用完全不同的詞彙，但如果它們的意思相同，向量就會指向同一方向，且分數接近 1.0： +*此圖比較基於關鍵字的搜尋與語義搜尋，顯示語義搜尋即使關鍵字不同，依然能找到概念相關的內容。* -Cosine Similarity +底層相似度以餘弦相似度衡量—本質問的是「這兩支箭頭指向同方向嗎？」兩個切塊可能用完全不同詞彙，但若意義相同，其向量方向相近，分數接近 1.0： -*此圖展示餘弦相似度作為嵌入向量間的角度 — 向量越一致，分數越接近 1.0，表示語義相似度越高。* +Cosine Similarity +*此圖說明餘弦相似度作為嵌入向量之間的角度——向量越對齊，得分越接近1.0，表示語義相似度越高。* -> **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 開啟 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 並詢問： -> - 「嵌入向量的相似度搜尋如何運作？分數由什麼決定？」 -> - 「我應該使用什麼相似度門檻？這如何影響結果？」 -> - 「如果找不到相關文件，我該如何處理？」 +> **🤖 試試用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 打開 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 並問： +> -「相似性搜索是如何利用嵌入運作的？得分是如何決定的？」 +> -「我應該使用什麼相似度閾值？它如何影響結果？」 +> -「當找不到相關文檔時，該如何處理？」 ### 答案生成 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -最相關的片段會被組裝成結構化提示，包含明確指示、檢索到的上下文以及使用者問題。模型閱讀這些特定片段並根據此資訊回答 — 它只能使用眼前的資料，避免出現虛構內容。 +最相關的片段會組裝成結構化提示，其中包含明確指令、檢索到的上下文和用戶問題。模型僅閱讀這些特定片段並根據這些資訊回答——只能使用眼前的內容，避免幻覺。 ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -下圖展示此組裝過程 — 來自搜尋步驟得分最高的片段被注入提示模板，`OpenAiOfficialChatModel` 生成一個有根據的答案： +以下圖示展示此組裝過程——來自搜尋步驟的最高得分片段被注入提示模板，`OpenAiOfficialChatModel` 產生有根據的答案： Context Assembly -*此圖展示如何將得分最高的片段組裝成結構化提示，使模型能從您的資料中生成有根據的答案。* +*此圖示如何將最高得分的片段組合成結構化提示，使模型能從您的數據中產生有根據的答案。* -## 執行應用程式 +## 運行應用程式 -**驗證部署：** +**確認部署：** -確保在根目錄存在 `.env` 檔案且包含 Azure 憑證（於模組 01 過程中建立）。從模組目錄 (`03-rag/`) 執行： +確保 `.env` 檔案存在於根目錄，包含 Azure 資訊（在模組 01 中建立）。從模組目錄 (`03-rag/`) 執行： **Bash:** ```bash @@ -261,27 +260,27 @@ Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT **啟動應用程式：** -> **注意：** 若您已從根目錄使用 `./start-all.sh` 啟動所有應用程式（如模組 01 所述），本模組已於 8081 埠運行。您可跳過以下啟動指令，直接前往 http://localhost:8081。 +> **注意：** 若您已從根目錄使用 `./start-all.sh` 啟動所有應用程式（如模組 01 描述），則此模組已在 8081 端口運行。您可跳過以下啟動命令，直接訪問 http://localhost:8081。 -**選項 1：使用 Spring Boot 儀表板（推薦 VS Code 使用者）** +**選項 1：使用 Spring Boot Dashboard（推薦 VS Code 用戶）** -開發容器包含 Spring Boot 儀表板擴充套件，提供視覺界面管理所有 Spring Boot 應用程式。您可在 VS Code 左側活動列找到（尋找 Spring Boot 圖示）。 +開發容器含有 Spring Boot Dashboard 擴展，提供視覺介面管理所有 Spring Boot 應用程式。在 VS Code 左側活動欄可找到（尋找 Spring Boot 圖示）。 -從 Spring Boot 儀表板，您可以： -- 查看工作區內所有可用的 Spring Boot 應用程式 +在 Spring Boot Dashboard，您可： +- 查看工作區內所有可用 Spring Boot 應用程式 - 一鍵啟動/停止應用程式 - 即時查看應用程式日誌 - 監控應用程式狀態 -只要按一下「rag」旁的播放按鈕即可啟動此模組，或一次啟動所有模組。 +點擊「rag」旁的播放按鈕以啟動此模組，或同時啟動所有模組。 Spring Boot Dashboard -*此截圖顯示 VS Code 中的 Spring Boot 儀表板，您可視覺化地啟動、停止及監控應用程式。* +*此截圖顯示 VS Code 中的 Spring Boot Dashboard，可視化地啟動、停止及監控應用程式。* **選項 2：使用 shell 腳本** -啟動所有網頁應用程式（模組 01-04）： +啟動全部網頁應用程式（模組 01-04）： **Bash:** ```bash @@ -295,7 +294,7 @@ cd .. # 從根目錄 .\start-all.ps1 ``` -或僅啟動此模組： +或只啟動本模組： **Bash:** ```bash @@ -309,9 +308,9 @@ cd 03-rag .\start.ps1 ``` -兩個腳本會自動從根目錄的 `.env` 檔載入環境變數，若 JAR 檔不存在會自動建置。 +這些腳本會自動從根目錄 `.env` 檔加載環境變數，若 JAR 不存在會自動編譯。 -> **注意：** 若您偏好先手動建置所有模組再啟動： +> **注意：** 若您想手動編譯所有模組再啟動： > > **Bash:** > ```bash @@ -325,113 +324,113 @@ cd 03-rag > mvn clean package -DskipTests > ``` -在瀏覽器開啟 http://localhost:8081 。 +請在瀏覽器開啟 http://localhost:8081。 **停止應用程式：** **Bash:** ```bash -./stop.sh # 僅此模組 +./stop.sh # 只有本模組 # 或者 cd .. && ./stop-all.sh # 所有模組 ``` **PowerShell:** ```powershell -.\stop.ps1 # 僅限此模組 +.\stop.ps1 # 只有此模組 # 或者 cd ..; .\stop-all.ps1 # 所有模組 ``` ## 使用應用程式 -應用程式提供文件上傳與提問的網頁介面。 +應用程式提供上載文件及提問的網頁介面。 RAG Application Interface -*此截圖展示 RAG 應用介面，您可在此處上傳文件並提問。* +*此截圖展示 RAG 應用介面，可上載文件並提出問題。* -### 上傳文件 +### 上載文件 -先上傳一份文件 — 測試用以 TXT 檔為佳。本目錄內有一個 `sample-document.txt`，包含 LangChain4j 功能、RAG 實作及最佳實務資訊，適合用來測試系統。 +首先上載文件——TXT 格式最適合測試。此資料夾中附有 `sample-document.txt`，內含 LangChain4j 功能、RAG 實作與最佳實踐資訊，非常適合測試系統。 -系統會處理您上傳的文件，將其分割成多個片段，並為每個片段建立嵌入向量。這個過程在上傳時自動完成。 +系統會處理您的文件，拆分成多個片段並為每個片段創建嵌入，這在您上載時自動完成。 ### 提問 -現在可針對文件內容提問具體問題。嘗試問一些文件中明確陳述的事實。系統會搜尋相關片段，將它們納入提示，並產生回答。 +接著詢問關於文件內容的具體問題。試問些文件中明確陳述的事實性問題。系統搜尋相關片段，將其納入提示並生成答案。 -### 檢查來源引用 +### 檢查來源參考 -留意每個回答都包含來源引用及相似度分數。這些分數（介於 0 到 1）表示每個片段與您的問題的相關程度。分數越高，匹配越好。這能讓您核對答案是否符合來源內容。 +每個答案包含來源片段及相似度分數。這些分數（0 到 1）表示每個片段與您的問題相關程度。分數越高表示匹配越好，讓您可以核對答案與來源材料。 RAG Query Results -*此截圖展示查詢結果，包括生成的答案、來源引用與擷取片段之相關分數。* +*此截圖顯示查詢結果，包括生成答案、來源參考及每個檢索片段的相關性分數。* -### 嘗試不同問題 +### 試驗提問 嘗試不同類型的問題： - 具體事實：「主要主題是什麼？」 -- 比較：「X 和 Y 有何不同？」 -- 摘要：「請總結關於 Z 的要點」 +- 比較：「X 與 Y 有何不同？」 +- 摘要：「請總結關於 Z 的重點」 -觀察相關分數隨著問題與文件內容匹配度的變化。 +觀察相關性分數如何隨問題與文件內容匹配度改變。 ## 主要概念 -### 分段策略 +### 分片策略 -文件被切成 300 個標記的段落，並重疊 30 個標記。這種設定能確保每段有足夠上下文意義，同時段落仍足夠小，能包含多段於一個提示中。 +文件被拆分成含 300 個 token 的片段，重疊 30 個 token。此設計確保每個片段有足夠上下文且仍足夠小，方便多片段同時納入提示。 ### 相似度分數 -每擷取的片段都有一個 0 到 1 之間的相似度分數，表示與使用者問題的匹配程度。下圖視覺化分數範圍及系統如何利用它們過濾結果： +每個檢索到的片段附帶與用戶問題相符程度的相似度分數（0 到 1）。下圖顯示分數範圍及系統如何用它們過濾結果： Similarity Scores -*此圖展示分數範圍從 0 到 1，系統設有 0.5 最低門檻過濾不相關的片段。* +*此圖展示分數範圍從0到1，最低閾值為0.5，用以過濾不相關片段。* -分數範圍如下： +分數範圍說明： - 0.7-1.0：高度相關，精確匹配 - 0.5-0.7：相關，具良好上下文 -- 低於 0.5：已過濾，不相關 +- 低於0.5：被過濾，差異過大 -系統僅擷取高於最低門檻的片段以確保品質。 +系統只檢索超過最低閾值的片段以確保質量。 -嵌入向量在意義清晰群聚時表現良好，但存在盲點。下圖展示常見的失敗模式 — 片段太大導致向量模糊、片段太小缺乏上下文、不明確詞彙指向多群聚，以及精確匹配查找（ID、零件號）完全無法透過嵌入實現： +嵌入效果極佳於清晰聚類語義，但會有盲點。下圖示常見失敗模式——片段太大導致向量混淆，片段太小缺乏上下文，歧義詞指向多個群集，且ID或零件號等精確匹配無法用嵌入處理： Embedding Failure Modes -*此圖展示常見的嵌入失敗模式：片段過大、片段過小、多義詞指向多群聚，以及像 ID 這類精確匹配查找。* +*此圖展示常見嵌入失敗模式：片段過大、片段過小、指向多個群集的模糊詞彙，以及像ID之類的精確匹配。* -### 記憶體儲存 +### 記憶體存儲 -為簡化，本模組使用記憶體儲存。重啟應用程式時，上傳的文件資料會遺失。生產環境系統會使用持久化向量資料庫，如 Qdrant 或 Azure AI Search。 +本模組為簡便起見使用記憶體存儲。重啟應用程式後，上載的文件會遺失。生產系統採用像 Qdrant 或 Azure AI Search 等持久化向量資料庫。 ### 上下文視窗管理 -每款模型有最大上下文視窗限制。您無法將大型文件的所有片段全部納入。系統會擷取相關性最高的前 N 個片段（預設 5 個），在限制內提供足夠上下文以保持回答正確。 +每個模型有最大上下文視窗。無法納入大型文件的所有片段。系統檢索最相關的前 N 個片段（預設5個），在限制內提供足夠上下文確保回答準確。 -## RAG 何時適用 +## 何時使用 RAG -RAG 並非總是最佳選擇。下圖決策指南幫助您判斷何時使用 RAG 有效，何時簡單方法 — 如直接將內容放入提示或依賴模型固有知識 — 已足夠： +RAG 並非總是適用。下圖決策指南可協助判斷何時 RAG 有價值，何時使用更簡單方法如將內容直接放進提示或倚賴模型內建知識即可： When to Use RAG -*此圖展示決策指南，協助判斷何時 RAG 添增價值，何時簡單方法足夠。* +*此圖為決策指南，指示何時使用 RAG 會帶來價值，何時簡單方式足夠。* -## 下一步 +## 後續步驟 -**下一模組：** [04-tools - 使用工具的 AI 代理](../04-tools/README.md) +**下一模組：** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**導覽：** [← 上一頁：模組 02 - 提示工程](../02-prompt-engineering/README.md) | [返回主頁](../README.md) | [下一頁：模組 04 - 工具 →](../04-tools/README.md) +**導覽：** [← 上一節：模組 02 - 提示工程](../02-prompt-engineering/README.md) | [返回主頁](../README.md) | [下一節：模組 04 - 工具 →](../04-tools/README.md) --- **免責聲明**： -本文件是使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 所翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議採用專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或誤釋承擔責任。 +本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。 \ No newline at end of file diff --git a/translations/zh-MO/04-tools/README.md b/translations/zh-MO/04-tools/README.md index 27691ac79..292f91315 100644 --- a/translations/zh-MO/04-tools/README.md +++ b/translations/zh-MO/04-tools/README.md @@ -1,84 +1,84 @@ -# Module 04: 使用工具的 AI 代理 +# Module 04: 具備工具的 AI 代理 ## 目錄 -- [影片導覽](../../../04-tools) -- [你將會學到的內容](../../../04-tools) -- [前置條件](../../../04-tools) -- [了解使用工具的 AI 代理](../../../04-tools) -- [工具呼叫原理](../../../04-tools) - - [工具定義](../../../04-tools) - - [決策過程](../../../04-tools) - - [執行](../../../04-tools) - - [回應生成](../../../04-tools) - - [架構：Spring Boot 自動接線](../../../04-tools) -- [工具串接](../../../04-tools) -- [執行應用程序](../../../04-tools) -- [使用應用程序](../../../04-tools) - - [嘗試簡單工具使用](../../../04-tools) - - [測試工具串接](../../../04-tools) - - [觀察對話流程](../../../04-tools) - - [實驗不同請求](../../../04-tools) -- [關鍵概念](../../../04-tools) - - [ReAct 模式（推理與行動）](../../../04-tools) - - [工具描述很重要](../../../04-tools) - - [會話管理](../../../04-tools) - - [錯誤處理](../../../04-tools) -- [可用工具](../../../04-tools) -- [何時使用基於工具的代理](../../../04-tools) -- [工具與 RAG 比較](../../../04-tools) -- [下一步](../../../04-tools) +- [影片導覽](#影片導覽) +- [你將學到什麼](#你將學到什麼) +- [先決條件](#先決條件) +- [理解具備工具的 AI 代理](#理解具備工具的-ai-代理) +- [工具呼叫如何運作](#工具呼叫如何運作) + - [工具定義](#工具定義) + - [決策制定](#決策制定) + - [執行](#執行) + - [回應生成](#回應生成) + - [架構：Spring Boot 自動注入](#架構：spring-boot-自動注入) +- [工具串接](#工具串接) +- [執行應用程式](#執行應用程式) +- [使用應用程式](#使用應用程式) + - [嘗試簡單工具使用](#嘗試簡單工具使用) + - [測試工具串接](#測試工具鏈結) + - [查看對話流程](#查看對話流程) + - [嘗試不同請求](#嘗試不同請求) +- [核心概念](#關鍵概念) + - [ReAct 範式（推理與行動）](#react-模式（推理與行動）) + - [工具描述的重要性](#工具描述很重要) + - [會話管理](#會話管理) + - [錯誤處理](#錯誤處理) +- [可用工具](#可用工具) +- [何時使用基於工具的代理](#何時使用工具驅動代理) +- [工具與 RAG 的比較](#工具與-rag) +- [下一步](#下一步) ## 影片導覽 -觀看本次直播課程，說明如何開始本模組： +觀看本直播，說明如何開始本模組： -使用工具的 AI 代理與 MCP - 直播課程 +具備工具的 AI 代理與 MCP - 直播 -## 你將會學到的內容 +## 你將學到什麼 -到目前為止，你已經學會如何與 AI 對話、有效組織提示詞，以及如何根據文件產生回應。但有一個根本限制：語言模型只能產生文字，它無法查詢天氣、執行計算、查詢資料庫，或與外部系統互動。 +到目前為止，你已學會如何與 AI 對話、有效組織提示語，並以文件作為回應依據。但仍有根本限制：語言模型只能生成文字。它們不能查看天氣、執行計算、查詢資料庫或跟外部系統互動。 -工具改變了這一點。透過提供模型可調用的函數，你將它從純文字產生器轉化為可以採取行動的代理。模型決定何時需要工具，使用哪個工具，以及傳入什麼參數。你的程式碼執行函數並回傳結果。模型在回應中納入該結果。 +工具改變了這一點。透過給模型存取可呼叫的函式，你將它從文字生成器轉變成能夠採取行動的代理。模型決定何時需要工具、使用哪一個工具，以及傳遞什麼參數。你的程式碼執行該函式並回傳結果。模型將該結果整合進回應中。 -## 前置條件 +## 先決條件 -- 完成 [Module 01 - 簡介](../01-introduction/README.md)（部署 Azure OpenAI 資源） -- 建議完成前置模組（本模組在「工具 vs RAG」比較中引用了 [Module 03 的 RAG 概念](../03-rag/README.md)） -- 根目錄下有 `.env` 檔案，包含 Azure 認證（由 Module 01 中的 `azd up` 建立） +- 完成 [Module 01 - 介紹](../01-introduction/README.md) （部署 Azure OpenAI 資源） +- 建議完成先前模組（本模組在工具與 RAG 比較中引用了 [Module 03 的 RAG 概念](../03-rag/README.md)） +- 專案根目錄中有包含 Azure 認證的 `.env` 檔案（由 Module 01 的 `azd up` 建立） -> **注意：** 如果尚未完成 Module 01，請先依照該模組的部署說明進行。 +> **注意：** 若尚未完成 Module 01，請先依照該模組的部署指示進行。 -## 了解使用工具的 AI 代理 +## 理解具備工具的 AI 代理 -> **📝 注意：** 本模組中「代理（agents）」一詞指的是增強了工具呼叫功能的 AI 助理。這與我們會在 [Module 05: MCP](../05-mcp/README.md) 探討的 **Agentic AI** 模式（具備自主規劃、記憶和多步推理的自主代理）不同。 +> **📝 注意：** 本模組中「代理」一詞指強化了工具呼叫能力的 AI 助理。這與在 [Module 05: MCP](../05-mcp/README.md) 將介紹的 **Agentic AI** 模式（具備規劃、記憶及多步推理的自主代理）不同。 -沒有工具時，語言模型只能根據訓練數據來產生文字。問它當前天氣怎樣，它只能猜測。賦予工具後，它可以呼叫天氣 API、執行計算或查詢資料庫，然後將這些真實結果編織進回應裡。 +沒有工具時，語言模型只能根據訓練資料生成文字。問它當前天氣，它只能猜測。給它工具，它就能呼叫天氣 API、執行計算，或查詢資料庫 — 然後將那些真實結果編織入回應。 無工具 vs 有工具 -*無工具時模型只能猜測——有工具時它可以呼叫 API、執行計算並回傳即時資料。* +*沒有工具時模型只能猜 — 有工具時可呼叫 API、執行計算並回傳即時資料。* -帶工具的 AI 代理遵循 **推理與行動（Reasoning and Acting，ReAct）** 模式。模型不僅回應，它會思考自己需要什麼、透過呼叫工具來行動、觀察結果，然後判斷是否繼續行動或給出最終答案： +具備工具的 AI 代理遵循 **推理與行動 (ReAct)** 範式。模型不只回應 — 它會思考所需、以呼叫工具行動、觀察結果，然後決定是否再行動或給出最終答案： -1. **推理** — 分析用戶問題，決定需要什麼資訊 -2. **行動** — 選擇合適工具，產生正確參數並呼叫它 -3. **觀察** — 接收工具輸出並評估結果 -4. **重複或回應** — 若需要更多資料就迴圈，否則組成自然語言答案 +1. 推理 — 代理分析使用者問題，判斷需要什麼資訊 +2. 行動 — 代理選擇合適工具，生成正確參數並呼叫該工具 +3. 觀察 — 代理接收工具輸出並評估結果 +4. 重複或回應 — 需要更多資料時迴圈回推理；否則組成自然語言答案 -ReAct 模式 +ReAct 範式 -*ReAct 循環——代理推理要做什麼，透過呼叫工具來行動，觀察結果並迴圈，直到給出最終答案。* +*ReAct 循環 — 代理推理要做什麼，以呼叫工具行動，觀察結果，迴圈直到能交付最終答案。* -這一切會自動發生。你定義工具及其描述，模型則處理何時及如何使用這些工具的決策。 +這一切都自動發生。你定義工具及描述，模型處理何時和如何使用它們的決策。 -## 工具呼叫原理 +## 工具呼叫如何運作 ### 工具定義 [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -你定義函數，並提供清晰描述與參數規格。模型在系統提示中看到這些描述，理解每個工具的功能。 +你定義函式並附上清晰描述和參數規範。模型在系統提示中看到這些描述並了解每個工具的用途。 ```java @Component @@ -96,139 +96,139 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// 助手由 Spring Boot 自動配置，含： +// 助手由 Spring Boot 自動配置： // - ChatModel bean // - 所有來自 @Component 類別的 @Tool 方法 // - 用於會話管理的 ChatMemoryProvider ``` -下圖解析每個註解，展示如何幫助 AI 了解何時呼叫工具以及傳入哪些參數： +下圖拆解各註釋說明每個部分如何幫助 AI 理解何時呼叫工具和帶入哪些參數： -工具定義結構 +工具定義構造 -*工具定義結構——@Tool 告訴 AI 何時使用它，@P 描述每個參數，@AiService 在啟動時串接所有元件。* +*工具定義構造 — @Tool 告訴 AI 何時使用，@P 描述每個參數，@AiService 在啟動時串接所有元件。* -> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 嘗試：** 打開 [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) 並詢問： -> - 「如何整合像 OpenWeatherMap 這樣的真實天氣 API，而非使用模擬數據？」 -> - 「什麼樣的工具描述能幫助 AI 正確使用該工具？」 -> - 「在工具實作中如何處理 API 錯誤與速率限制？」 +> **🤖 試試用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 打開 [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) 並提問： +> - 「我如何整合像 OpenWeatherMap 這樣的真實天氣 API，而非模擬資料？」 +> - 「什麼樣的工具描述最能幫助 AI 正確使用？」 +> - 「在工具實作中如何處理 API 錯誤和流量限制？」 -### 決策過程 +### 決策制定 -當用戶問「Seattle 的天氣如何？」模型不會隨機選擇工具。它會對照每個工具描述評分，判斷與用戶意圖的相關性，選出最佳工具。然後產生結構化函數調用，這例中會設定 `location` 為 `"Seattle"`。 +當使用者問「西雅圖的天氣如何？」時，模型不會隨機挑工具。它會將使用者意圖與所有工具描述比對，依關聯度評分，挑出最佳匹配。然後生成結構化函式呼叫並帶上正確參數 — 這裡是將 `location` 設為 `"Seattle"`。 -若無工具匹配用戶需求，模型則會用自身知識回應。若多個工具符合，會挑選最具體的一個。 +若無工具匹配使用者請求，模型會退回以自身知識回答。若多工具匹配，則選最具體的。 AI 如何決定使用哪個工具 -*模型評估所有可用工具與用戶意圖的匹配度，選出最適合的工具——這就是為什麼撰寫清楚又具體的工具描述很重要。* +*模型評估每個可用工具與使用者意圖的關聯，選出最佳匹配 — 因此清楚且具體的工具描述非常重要。* ### 執行 [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot 自動將所有註冊的工具與宣告的 `@AiService` 介面接線，LangChain4j 自動執行工具調用。幕後流程涵蓋六個階段，從用戶自然語言問題到產生自然語言回答： +Spring Boot 自動串接具聲明式 `@AiService` 介面的所有已註冊工具，LangChain4j 自動執行工具呼叫。幕後，完整工具呼叫流程經六個階段 — 從使用者自然語言問題，一直到自然語言答案： 工具呼叫流程 -*完整端到端流程——用戶提出問題，模型挑選工具，LangChain4j 執行工具，模型整合結果生成自然回應。* +*端到端流程 — 使用者提問，模型選擇工具，LangChain4j 執行，模型將結果編織成自然回應。* -如果你執行過 Module 00 的 [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java)，已看過這種模式——`Calculator` 工具就是以相同方式呼叫。下圖序列圖精確展示示範中幕後發生的事情： +幕後，`AiServices` 對任何工具都執行相同的工具呼叫迴圈 — 這裡以簡單 `Calculator` 示範。以下時序圖清楚說明底層發生的流程： -工具呼叫序列圖 +工具呼叫時序圖 -*Quick Start 示範的工具呼叫迴圈——`AiServices` 傳送訊息與工具結構給 LLM，LLM 回覆結構化函數調用如 `add(42, 58)`，LangChain4j 在本地執行 `Calculator` 方法，結果送回模型作最終回應。* +*工具呼叫迴圈 — `AiServices` 傳送訊息和工具結構至大模型，模型回覆類似 `add(42, 58)` 的函式呼叫，LangChain4j 在本地執行 `Calculator` 方法，並回傳結果作為最終答案。* -> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 嘗試：** 打開 [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) 並詢問： -> - 「ReAct 模式如何運作？為什麼它對 AI 代理有效？」 -> - 「代理如何決定要使用哪個工具及其順序？」 -> - 「若工具執行失敗，該如何穩健錯誤處理？」 +> **🤖 試試用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 打開 [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) 並提問： +> - 「ReAct 範式如何運作，為何有效於 AI 代理？」 +> - 「代理如何決定使用哪個工具及使用順序？」 +> - 「如果工具執行失敗怎麼辦 — 如何健壯地處理錯誤？」 ### 回應生成 -模型接收天氣資料，將其格式化為對用戶的自然語言回應。 +模型接收天氣資料並格式化為自然語言回應給使用者。 -### 架構：Spring Boot 自動接線 +### 架構：Spring Boot 自動注入 -本模組使用 LangChain4j 與 Spring Boot 整合的宣告式 `@AiService` 介面。啟動時 Spring Boot 掃描包含 `@Tool` 方法的每個 `@Component`、你的 `ChatModel` Bean，與 `ChatMemoryProvider`，然後將它們全數接線到單一 `Assistant` 介面，無需樣板程式碼。 +本模組使用 LangChain4j 的 Spring Boot 整合搭配聲明式 `@AiService` 介面。啟動時，Spring Boot 掃描所有含有 `@Tool` 方法的 `@Component`、你的 `ChatModel` bean 與 `ChatMemoryProvider` — 並統一串接成單一 `Assistant` 介面，不需任何樣板碼。 -Spring Boot 自動接線架構 +Spring Boot 自動組線架構 -*@AiService 介面串聯了 ChatModel、工具元件與記憶體提供者——Spring Boot 自動處理所有接線。* +*@AiService 介面將 ChatModel、工具元件與記憶體提供者串接起來 — Spring Boot 全自動接線。* -下方為整個請求生命週期序列圖——從 HTTP 請求流經控制器、服務以及自動接線代理，直到工具執行並返回： +以下為完整請求生命週期的時序圖 — 從 HTTP 請求經控制器、服務及自動注入的代理到工具執行，再返回的流程： -Spring Boot 工具呼叫序列 +Spring Boot 工具呼叫時序 -*完整 Spring Boot 請求生命週期——HTTP 請求透過控制器與服務流到自動接線的 Assistant 代理，該代理自動調度 LLM 與工具呼叫。* +*完整 Spring Boot 請求生命週期 — HTTP 請求流經控制器與服務到自動注入的 Assistant 代理，後者自動協調大模型與工具呼叫。* -此法關鍵優點： +此方法主要優點： -- **Spring Boot 自動接線** — ChatModel 與工具自動注入 -- **@MemoryId 模式** — 自動的基於會話的記憶管理 -- **單一實例** — Assistant 創建一次，多次重用提升效能 -- **類型安全執行** — 直接呼叫 Java 方法並自動型別轉換 -- **多回合協調** — 自動處理工具串接 -- **無樣板程式碼** — 無需手動 `AiServices.builder()` 調用或記憶體 HashMap +- **Spring Boot 自動注入** — ChatModel 與工具自動注入 +- **@MemoryId 模式** — 自動化基於會話的記憶管理 +- 單一實例 — Assistant 實例只建立一次，提升效能 +- 型別安全執行 — Java 方法可直接呼叫，具型別轉換 +- 多輪協調 — 自動處理工具串接流程 +- 零樣板碼 — 無須手動撰寫 `AiServices.builder()` 或管理記憶 HashMap -手動 `AiServices.builder()` 的方式需寫更多代碼，且無法獲得 Spring Boot 整合的優勢。 +替代作法（手動 `AiServices.builder()`）需較多程式碼且缺乏 Spring Boot 整合優勢。 ## 工具串接 -**工具串接** — 基於工具的代理真正威力在於單一問題需要多個工具。問「Seattle 的天氣用華氏怎麼說？」時，代理會自動串接兩個工具：先呼叫 `getCurrentWeather` 取得攝氏溫度，再將該結果傳給 `celsiusToFahrenheit` 轉換，完成單回合回答。 +工具串接 — 基於工具的代理真正威力展現於單一問題需多工具合作時。問「西雅圖的天氣用華氏計算是多少？」時，代理會自動串接兩個工具：先呼叫 `getCurrentWeather` 取得攝氏溫度，再將該數值傳給 `celsiusToFahrenheit` 轉換 — 均在一次對話回合完成。 工具串接範例 -*工具串接實例——代理先呼叫 getCurrentWeather，再將攝氏結果傳給 celsiusToFahrenheit，最後給出合併答覆。* +*工具串接實例 — 代理先呼叫 getCurrentWeather，然後將攝氏結果轉給 celsiusToFahrenheit，並給出整合答案。* -**優雅失敗** — 詢問不在模擬資料中的城市天氣，工具回傳錯誤訊息，AI 解釋無法協助而非當機。工具會安全失敗。下圖對比兩種情況——有適當錯誤處理時，代理捕捉例外並給出有幫助的答案，反之則整個應用崩潰： +優雅失敗 — 請求不存在於模擬資料的城市天氣時，工具傳回錯誤訊息，AI 解釋無法協助而非程式崩潰。工具安全失敗。下圖對比兩種做法 — 適當錯誤處理下，代理捕捉例外並給予有用回應；未處理則整個應用程式掛掉： 錯誤處理流程 -*工具失敗時，代理捕捉錯誤並以有用解釋回應，用戶端不會當機。* +*工具失敗時，代理捕獲錯誤並用有幫助的解釋回應，而非程式崩潰。* -這發生在單次對話回合中，代理自主協調多次工具調用。 +此流程於單次對話回合完成，代理自主協調多重工具呼叫。 -## 執行應用程序 +## 執行應用程式 **確認部署狀態：** -確定根目錄下有 `.env` 檔案，且含 Azure 認證（在 Module 01 部署時建立）。於本模組資料夾（`04-tools/`）執行： +確保專案根目錄中已有包含 Azure 認證的 `.env` 檔案（在 Module 01 部署時建立）。於本模組目錄（`04-tools/`）執行： -**Bash:** +**Bash：** ```bash cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` -**PowerShell:** +**PowerShell：** ```powershell Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` -**啟動應用程序：** +**啟動應用程式：** -> **注意：** 若你已使用根目錄的 `./start-all.sh`（如 Module 01 所述）啟動所有應用，本模組已在 8084 埠口運行，可跳過下列啟動指令，直接前往 http://localhost:8084 。 +> **注意：** 若已於根目錄使用 `./start-all.sh` 啟動所有應用（如 Module 01 所示），本模組已在 8084 埠運行。你可略過以下啟動指令，直接訪問 http://localhost:8084 。 -**方案一：使用 Spring Boot 控制台（建議 VS Code 使用者）** +**方案一：使用 Spring Boot 控制面板（推薦 VS Code 使用者）** -開發容器已包含 Spring Boot 控制台擴充功能，提供圖形化介面管理所有 Spring Boot 應用。可在 VS Code 左側活動列找到 Spring Boot 圖示。 +開發容器包含 Spring Boot 控制面板擴充，提供視覺介面管理所有 Spring Boot 應用程式。可於 VS Code 左側活動欄找到（尋找 Spring Boot 圖示）。 -在 Spring Boot 控制台，你可以： -- 查看工作區中的所有 Spring Boot 應用 -- 一鍵啟動/停止應用 -- 實時觀看應用日誌 +在 Spring Boot 控制面板中，你可以： +- 查看工作區中所有可用的 Spring Boot 應用 +- 一鍵啟動/停止應用程式 +- 實時查看應用日誌 - 監控應用狀態 -只需按一下「tools」旁邊的播放按鈕即可啟動此模組，或者同時啟動所有模組。 -以下是在 VS Code 中 Spring Boot Dashboard 的外觀： +只要點擊「tools」旁的播放鈕啟動本模組，或一次啟動所有模組。 -Spring Boot Dashboard +以下為 VS Code 中 Spring Boot 控制面板的樣貌： +Spring Boot 儀錶板 -*VS Code 中的 Spring Boot Dashboard — 從一處啟動、停止並監控所有模組* +*VS Code 裡的 Spring Boot 儀錶板 — 從一處啟動、停止及監視所有模組* -**選項二：使用 shell 腳本** +**選項 2：使用 shell 腳本** -啟動所有 Web 應用程式（模組 01-04）： +啟動所有網頁應用程式（模組 01-04）： **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -這兩個腳本會自動從根目錄的 `.env` 檔案載入環境變數，並會在 JAR 不存在時進行建置。 +兩個腳本會自動從根目錄的 `.env` 檔案載入環境變數，且如果 JAR 檔不存在則會自動建構。 -> **注意：** 如果你希望在啟動前手動建置所有模組： +> **注意：** 如果你想手動建置所有模組再啟動： > > **Bash:** > ```bash @@ -272,13 +272,13 @@ cd 04-tools > mvn clean package -DskipTests > ``` -在瀏覽器中開啟 http://localhost:8084 。 +在瀏覽器開啟 http://localhost:8084 。 -**要停止：** +**停止方法：** **Bash:** ```bash -./stop.sh # 僅此模組 +./stop.sh # 僅限此模組 # 或 cd .. && ./stop-all.sh # 所有模組 ``` @@ -286,90 +286,90 @@ cd .. && ./stop-all.sh # 所有模組 **PowerShell:** ```powershell .\stop.ps1 # 僅此模組 -# 或者 -cd ..; .\stop-all.ps1 # 所有模組 +# 或 +cd ..; .\stop-all.ps1 # 全部模組 ``` ## 使用應用程式 -此應用程式提供一個網頁介面，可與擁有天氣和溫度轉換工具的 AI 代理互動。以下是介面外觀 — 包含快速啟動範例和用於發送請求的聊天面板： +本應用程式提供一個網頁介面，讓你可以與擁有存取天氣和溫度轉換工具權限的 AI 代理互動。介面長這樣 — 包含快速入門範例和對話面板，可用來發送請求： -AI Agent Tools Interface +AI 代理工具介面 -*AI 代理工具介面 - 互動快速範例與聊天介面* +*AI 代理工具介面 - 快速範例和與工具互動的對話介面* ### 嘗試簡單工具使用 -從簡單請求開始：「將 100 華氏度轉換為攝氏度」。代理會辨識需要使用溫度轉換工具，帶入正確參數呼叫，並返回結果。注意這感覺多麼自然 — 你沒有指定使用哪個工具或如何呼叫。 +從簡單的請求開始：「將 100 華氏度轉換為攝氏度」。代理會識別需要調用溫度轉換工具，以正確參數呼叫並回傳結果。注意這感覺多自然 — 你沒指定使用哪個工具或怎麼呼叫。 ### 測試工具鏈結 -現在試試更複雜的：「西雅圖的天氣如何，並轉換成華氏度？」觀察代理如何分步處理。它先取得天氣（回傳攝氏度），辨識需轉換成華氏度，呼叫轉換工具，並將兩者結果結合成一個回應。 +現在試試更複雜的說法：「西雅圖的天氣如何，並轉換成華氏？」觀看代理如何分步執行。它先取得天氣（回傳攝氏），再識別需要轉換成華氏，呼叫轉換工具，最後將結果合併回應。 ### 查看對話流程 -聊天介面會保留對話歷史，使你能進行多輪互動。你可以看到所有先前的查詢和回應，方便追蹤對話並理解代理如何在多次交流中建立上下文。 +對話介面會保存對話歷史，支持多輪互動。你可以看到所有先前的查詢和回答，方便追蹤對話並理解代理如何在多次交換中建構上下文。 -Conversation with Multiple Tool Calls +多次工具呼叫的對話 -*多輪對話示範簡單轉換、天氣查詢與工具鏈結* +*多輪對話範例，展示簡單轉換、天氣查詢與工具鏈結* ### 嘗試不同請求 -試試多種組合： +試試各種組合： - 天氣查詢：「東京的天氣如何？」 -- 溫度轉換：「25°C 等於多少開爾文？」 -- 綜合查詢：「查詢巴黎的天氣，告訴我是否超過 20°C」 +- 溫度轉換：「25°C 是多少開爾文？」 +- 結合查詢：「查詢巴黎天氣並告訴我是不是超過 20°C」 -注意代理如何解讀自然語言並映射到合適的工具呼叫。 +注意代理如何解讀自然語言並映射到適當的工具呼叫。 -## 主要概念 +## 關鍵概念 -### ReAct 模式（推理與執行） +### ReAct 模式（推理與行動） -代理交替進行推理（決定該做什麼）和執行（使用工具）。此模式讓代理自主解決問題，而非僅是回應指令。 +代理在推理（決定做什麼）和行動（使用工具）間交替。此模式賦能自動化解決問題，而非僅回應指令。 -### 工具描述重要性 +### 工具描述很重要 -你的工具描述品質會直接影響代理的使用效果。清晰、具體的描述有助模型理解何時及如何呼叫每個工具。 +工具描述的品質直接影響代理如何使用它們。清楚具體的描述幫助模型了解何時及如何呼叫工具。 ### 會話管理 -`@MemoryId` 註解實現自動的會話記憶管理。每個會話 ID 對應一個 `ChatMemory` 實例，由 `ChatMemoryProvider` bean 管理，因此多個使用者可同時與代理互動，且不會互相干擾。下圖示範多個使用者如何根據會話 ID 被導向獨立的記憶體存取： +`@MemoryId` 註解啟用自動的基於會話的記憶體管理。每個會話 ID 會有自己的 `ChatMemory` 實例，由 `ChatMemoryProvider` 管理，讓多個用戶能同時與代理互動且不會互相干擾。下圖展示多用戶如何根據會話 ID 導向各自獨立記憶庫： -Session Management with @MemoryId +使用 @MemoryId 的會話管理 -*每個會話 ID 映射到獨立的對話歷史 — 使用者看不到彼此訊息。* +*每個會話 ID 對應獨立的對話歷史 — 用戶永遠看不到彼此訊息。* ### 錯誤處理 -工具可能失敗 — API 超時、參數無效、外部服務故障。生產環境的代理需具備錯誤處理，讓模型說明問題或嘗試備用方案，而不會直接崩潰。當工具觸發異常，LangChain4j 會捕捉並回饋錯誤訊息給模型，模型便能自然語言解釋問題。 +工具可能失敗 — API 請求逾時、參數無效、外部服務中斷。生產環境代理需要錯誤處理，讓模型能解釋問題或嘗試其他方案，而非整個應用崩潰。當工具拋出例外時，LangChain4j 會捕捉並回傳錯誤訊息給模型，模型便能用自然語言解釋問題所在。 ## 可用工具 -下圖顯示你可以建立的工具生態系。此模組展示天氣及溫度工具，但相同的 `@Tool` 模式適用於任何 Java 方法 — 從資料庫查詢到支付處理。 +下圖展示你可以建構的工具生態系統。本模組示範天氣和溫度工具，但相同的 `@Tool` 模式適用於任何 Java 方法 — 從資料庫查詢到支付處理。 -Tool Ecosystem +工具生態系統 -*任何加註 @Tool 的 Java 方法都能被 AI 使用 — 該模式延伸至資料庫、API、郵件、檔案操作等。* +*任何加註 @Tool 的 Java 方法都會可供 AI 使用 — 此模式可擴展至資料庫、API、電郵、檔案操作等等。* -## 何時使用基於工具的代理 +## 何時使用工具驅動代理 -非所有請求都需用工具。決策關鍵在於 AI 是否需與外部系統互動，或僅用自身知識回答。以下指南總結何時使用工具具價值，何時不必要： +並非每個請求都需要工具。抉擇關鍵在於 AI 是否需要跟外部系統互動，或是靠自身知識回答。下方指南總結何時工具能加值，何時不必使用： -When to Use Tools +何時使用工具 -*快速判斷指南 — 工具用於即時資料、計算及動作；一般知識與創作任務則無需。* +*簡易決策指南 — 工具用於即時資料、計算與操作；一般知識和創作任務則不必。* -## 工具 vs RAG +## 工具與 RAG -模組 03 與 04 都擴展 AI 能力，但方式根本不同。RAG 透過檢索文件提供模型**知識**，工具則讓模型能透過函式呼叫採取**行動**。下圖比較這兩種方法 — 從工作流運行到各自取捨： +模組 03 和 04 都擴展 AI 的能力，但方式根本不同。RAG 透過檢索文件給模型存取知識。工具則賦予模型實現行動的能力，透過呼叫函數。下圖並列比較兩者 — 從各自工作流程到各種權衡： -Tools vs RAG Comparison +工具 vs RAG 比較 -*RAG 從靜態文件檢索資訊 — 工具執行動作並抓取即時動態資料。許多生產系統結合兩者。* +*RAG 從靜態文件檢索資訊 — 工具執行動作並擷取動態即時資料。許多生產系統結合兩者。* -實務上，許多系統同時採用兩種方法：RAG 為文件提供基礎答案，工具用於擷取現場資料或執行操作。 +實務中，很多生產系統同時使用 RAG（以文件為依據）和工具（抓取即時數據或執行操作）。 ## 下一步 @@ -377,11 +377,11 @@ cd ..; .\stop-all.ps1 # 所有模組 --- -**導覽：** [← 上一個：模組 03 - RAG](../03-rag/README.md) | [返回主頁](../README.md) | [下一個：模組 05 - MCP →](../05-mcp/README.md) +**導覽：** [← 上一章：模組 03 - RAG](../03-rag/README.md) | [回主頁](../README.md) | [下一章：模組 05 - MCP →](../05-mcp/README.md) --- -**免責聲明**： -本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 所翻譯。雖然我哋致力保持準確性，但請留意自動翻譯可能存在錯誤或不準確之處。原文文件以其本地語言版本應為具權威性之資料來源。對於重要資訊，建議採用專業人工翻譯。我哋對因使用本翻譯而引起嘅任何誤解或誤釋概不負責。 +**免責聲明**： +本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。 \ No newline at end of file diff --git a/translations/zh-MO/README.md b/translations/zh-MO/README.md index 79ccdffb4..b6081851f 100644 --- a/translations/zh-MO/README.md +++ b/translations/zh-MO/README.md @@ -2,148 +2,148 @@ # LangChain4j 初學者課程 -一個用 LangChain4j 及 Azure OpenAI GPT-5.2 建構 AI 應用的課程，涵蓋從基礎聊天到 AI 代理。 +一門使用 LangChain4j 與 Azure OpenAI GPT-5.2 建構 AI 應用程式的課程，涵蓋從基礎對話到 AI 代理人。 ### 🌐 多語言支援 -#### 由 GitHub Action 支援 (自動且持續更新) +#### 透過 GitHub 行動支援（自動且隨時更新） -[阿拉伯文](../ar/README.md) | [孟加拉文](../bn/README.md) | [保加利亞文](../bg/README.md) | [緬甸文 (緬甸)](../my/README.md) | [中文（簡體）](../zh-CN/README.md) | [中文（繁體，香港）](../zh-HK/README.md) | [中文（繁體，澳門）](./README.md) | [中文（繁體，台灣）](../zh-TW/README.md) | [克羅地亞文](../hr/README.md) | [捷克文](../cs/README.md) | [丹麥文](../da/README.md) | [荷蘭文](../nl/README.md) | [愛沙尼亞文](../et/README.md) | [芬蘭文](../fi/README.md) | [法文](../fr/README.md) | [德文](../de/README.md) | [希臘文](../el/README.md) | [希伯來文](../he/README.md) | [印地文](../hi/README.md) | [匈牙利文](../hu/README.md) | [印尼文](../id/README.md) | [意大利文](../it/README.md) | [日文](../ja/README.md) | [坎那達文](../kn/README.md) | [高棉文](../km/README.md) | [韓文](../ko/README.md) | [立陶宛文](../lt/README.md) | [馬來文](../ms/README.md) | [馬拉雅拉姆文](../ml/README.md) | [馬拉地文](../mr/README.md) | [尼泊爾文](../ne/README.md) | [奈及利亞皮欽語](../pcm/README.md) | [挪威文](../no/README.md) | [波斯文 (法爾西)](../fa/README.md) | [波蘭文](../pl/README.md) | [葡萄牙文 (巴西)](../pt-BR/README.md) | [葡萄牙文 (葡萄牙)](../pt-PT/README.md) | [旁遮普文 (古魯穆奇)](../pa/README.md) | [羅馬尼亞文](../ro/README.md) | [俄文](../ru/README.md) | [塞爾維亞文 (西里爾字母)](../sr/README.md) | [斯洛伐克文](../sk/README.md) | [斯洛文尼亞文](../sl/README.md) | [西班牙文](../es/README.md) | [斯瓦希里文](../sw/README.md) | [瑞典文](../sv/README.md) | [他加祿文 (菲律賓語)](../tl/README.md) | [泰米爾文](../ta/README.md) | [泰盧固文](../te/README.md) | [泰文](../th/README.md) | [土耳其文](../tr/README.md) | [烏克蘭文](../uk/README.md) | [烏爾都文](../ur/README.md) | [越南文](../vi/README.md) +[Arabic](../ar/README.md) | [Bengali](../bn/README.md) | [Bulgarian](../bg/README.md) | [Burmese (Myanmar)](../my/README.md) | [Chinese (Simplified)](../zh-CN/README.md) | [Chinese (Traditional, Hong Kong)](../zh-HK/README.md) | [Chinese (Traditional, Macau)](./README.md) | [Chinese (Traditional, Taiwan)](../zh-TW/README.md) | [Croatian](../hr/README.md) | [Czech](../cs/README.md) | [Danish](../da/README.md) | [Dutch](../nl/README.md) | [Estonian](../et/README.md) | [Finnish](../fi/README.md) | [French](../fr/README.md) | [German](../de/README.md) | [Greek](../el/README.md) | [Hebrew](../he/README.md) | [Hindi](../hi/README.md) | [Hungarian](../hu/README.md) | [Indonesian](../id/README.md) | [Italian](../it/README.md) | [Japanese](../ja/README.md) | [Kannada](../kn/README.md) | [Khmer](../km/README.md) | [Korean](../ko/README.md) | [Lithuanian](../lt/README.md) | [Malay](../ms/README.md) | [Malayalam](../ml/README.md) | [Marathi](../mr/README.md) | [Nepali](../ne/README.md) | [Nigerian Pidgin](../pcm/README.md) | [Norwegian](../no/README.md) | [Persian (Farsi)](../fa/README.md) | [Polish](../pl/README.md) | [Portuguese (Brazil)](../pt-BR/README.md) | [Portuguese (Portugal)](../pt-PT/README.md) | [Punjabi (Gurmukhi)](../pa/README.md) | [Romanian](../ro/README.md) | [Russian](../ru/README.md) | [Serbian (Cyrillic)](../sr/README.md) | [Slovak](../sk/README.md) | [Slovenian](../sl/README.md) | [Spanish](../es/README.md) | [Swahili](../sw/README.md) | [Swedish](../sv/README.md) | [Tagalog (Filipino)](../tl/README.md) | [Tamil](../ta/README.md) | [Telugu](../te/README.md) | [Thai](../th/README.md) | [Turkish](../tr/README.md) | [Ukrainian](../uk/README.md) | [Urdu](../ur/README.md) | [Vietnamese](../vi/README.md) -> **偏好本地 Git 克隆？** +> **想本地克隆？** > -> 這個儲存庫包含超過 50 種語言翻譯，會顯著增加下載大小。想要克隆但不含翻譯，請使用稀疏檢出： +> 此儲存庫包含 50 多種語言翻譯，會顯著增加下載大小。若想不含翻譯地克隆，請使用稀疏檢出： > -> **Bash / macOS / Linux:** +> **Bash / macOS / Linux：** > ```bash > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone '/*' '!translations' '!translated_images' > ``` > -> **CMD (Windows):** +> **CMD (Windows)：** > ```cmd > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> 這樣能幫你以更快的速度下載，並獲得完成課程所需的所有內容。 +> 這樣你將獲得完成本課程所需的所有資料，且下載速度更快。 ## 目錄 -1. [快速入門](00-quick-start/README.md) - 開始使用 LangChain4j -2. [介紹](01-introduction/README.md) - 學習 LangChain4j 基礎知識 -3. [提示工程](02-prompt-engineering/README.md) - 掌握有效的提示設計 -4. [RAG（檢索強化生成）](03-rag/README.md) - 建立智慧知識系統 -5. [工具](04-tools/README.md) - 整合外部工具與簡易助理 -6. [MCP（模型上下文協議）](05-mcp/README.md) - 使用模型上下文協議（MCP）和代理模組 +1. [介紹](01-introduction/README.md) - 學習 LangChain4j 的基本原理 +2. [提示工程](02-prompt-engineering/README.md) - 精通有效的提示設計 +3. [RAG（檢索增強生成）](03-rag/README.md) - 建構智能知識基礎系統 +4. [工具](04-tools/README.md) - 整合外部工具及簡易助理 +5. [MCP（模型上下文協議）](05-mcp/README.md) - 使用模型上下文協議（MCP）與代理模組 ### 影片導覽 -每個模組都配有直播課程，逐步介紹概念與程式碼。 +每個模組附有線上直播課程，逐步帶你理解概念與程式碼。 | 模組 | 影片 | |--------|-------| -| 01 - 介紹 | [LangChain4j 快速入門](https://www.youtube.com/live/nl_troDm8rQ) | -| 02 - 提示工程 | [LangChain4j 提示工程](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [LangChain4j RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - 工具 & 05 - MCP | [帶工具與 MCP 的 AI 代理](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 01 - 介紹 | [LangChain4j 入門教學](https://www.youtube.com/live/nl_troDm8rQ) | +| 02 - 提示工程 | [LangChain4j 的提示工程](https://www.youtube.com/live/PJ6aBaE6bog) | +| 03 - RAG | [LangChain4j 的 RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 04 - 工具 & 05 - MCP | [具工具和 MCP 的 AI 代理人](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- ## 學習路徑 -**剛接觸 LangChain4j？** 請查閱 [詞彙表](docs/GLOSSARY.md) 了解關鍵術語與概念定義。 +**LangChain4j 新手？** 查看 [術語表](docs/GLOSSARY.md) 以瞭解重要術語和概念。 -> 快速入門 +> 快速開始 -1. 將本儲存庫 fork 到你的 GitHub 帳號 -2. 點擊 **Code** → **Codespaces** 頁籤 → **...** → **New with options...** -3. 使用預設選項 — 將選擇本課程的開發容器 +1. 將此儲存庫 fork 到你的 GitHub 帳號 +2. 點選 **Code** → **Codespaces** 標籤 → **...** → **從選項新建...** +3. 使用預設設定 — 此設定將選擇為本課程建立的開發容器 4. 點擊 **Create codespace** -5. 等待 5-10 分鐘讓環境準備就緒 -6. 直接跳到 [快速入門](./00-quick-start/README.md) 開始！ +5. 等待 5-10 分鐘，直到環境準備就緒 +6. 直接跳至 [介紹](./01-introduction/README.md) 開始學習！ -完成模組後，探索 [測試指南](docs/TESTING.md) 實際應用 LangChain4j 測試概念。 +完成模組後，探索 [測試指南](docs/TESTING.md)，了解 LangChain4j 的測試實務。 -> **注意：** 本課程同時使用 GitHub 模型與 Azure OpenAI。[快速入門](00-quick-start/README.md) 模組使用 GitHub 模型（無需 Azure 訂閱），而模組 1-5 使用 Azure OpenAI。尚未擁有者，請先註冊 [免費 Azure 帳號](https://aka.ms/azure-free-account)。 +> **注意：** 本訓練使用 Azure OpenAI。如尚無帳號，請使用 [免費 Azure 帳號](https://aka.ms/azure-free-account) 開始。 ## 使用 GitHub Copilot 學習 -想快速開始編碼，請用 GitHub Codespace 或本地 IDE 開啟此專案，使用配備的 devcontainer。本課程的 devcontainer 預設已安裝 GitHub Copilot，方便 AI 配對程式設計。 +想快速開始撰寫程式？可在 GitHub Codespace 或本機 IDE 中開啟此專案，搭配提供的 devcontainer。該 devcontainer 已預先配置 GitHub Copilot，支援 AI 配對編程。 -每個範例程式碼均附帶建議問題，可詢問 GitHub Copilot 加深理解。請留意程式碼中的 💡/🤖 提示： +每個程式碼範例都包含建議問題，可提問 GitHub Copilot 以加深理解。請留意以下位置的 💡/🤖 提示： -- **Java 檔案標頭** — 針對範例提出的問題 +- **Java 檔案標頭** — 針對個別範例的問題 - **模組 README** — 程式碼範例後的探索提示 -**使用方式：** 開啟任何程式碼文件，向 Copilot 詢問建議問題。它擁有完整程式碼庫上下文，能說明、擴充並提出替代方案。 +**使用方式：** 開啟任一程式碼檔案，向 Copilot 詢問建議問題。它擁有完整程式碼庫上下文，能說明、延伸、並提出替代方案。 -想了解更多？請查看 [AI 配對程式設計的 Copilot](https://aka.ms/GitHubCopilotAI)。 +想瞭解更多？請參考 [AI 配對編程的 Copilot](https://aka.ms/GitHubCopilotAI)。 -## 附加資源 + +## 額外資源 ### LangChain -[![LangChain4j for Beginners](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js for Beginners](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain for Beginners](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j 初學者課程](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js 初學者課程](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain 初學者課程](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- ### Azure / Edge / MCP / Agents -[![AZD for Beginners](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI for Beginners](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP for Beginners](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI Agents for Beginners](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AZD 初學者課程](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI 初學者課程](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP 初學者課程](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI 代理人初學者課程](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### 生成式 AI 系列 -[![Generative AI for Beginners](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Generative AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) -[![Generative AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) -[![Generative AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) +[![生成式 AI 初學者課程](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![生成式 AI（.NET）](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) +[![生成式 AI（Java）](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) +[![生成式 AI（JavaScript）](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) --- ### 核心學習 -[![ML for Beginners](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![Data Science for Beginners](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![AI for Beginners](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![初學者網絡安全](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![初學者網頁開發](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![初學者物聯網](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![初學者XR開發](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![機器學習初學者課程](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![資料科學初學者課程](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![人工智能初學者課程](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![網絡安全初學者課程](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Copilot 系列 -[![AI 配對編程的 Copilot](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET 的 Copilot](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot 冒險](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) ## 獲取幫助 -如果遇到困難或有關構建 AI 應用的任何問題，請加入： +如果你遇到困難或對構建 AI 應用有任何疑問，請加入： [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -如果在開發過程中有產品反饋或錯誤，請訪問： +如果你在構建過程中有產品反饋或錯誤，請訪問： [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## 授權 -MIT 授權 - 請參閱 [LICENSE](../../LICENSE) 文件了解詳情。 +MIT 授權 - 詳情請見 [LICENSE](../../LICENSE) 檔案。 --- -**免責聲明**： -本文件是使用AI翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。儘管我們努力確保準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於重要資訊，建議採用專業人工翻譯。對於因使用本翻譯而產生的任何誤解或誤釋，我們概不負責。 +**免責聲明**： +本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。 \ No newline at end of file diff --git a/translations/zh-MO/docs/GLOSSARY.md b/translations/zh-MO/docs/GLOSSARY.md index c8f3fd950..94dbfb40f 100644 --- a/translations/zh-MO/docs/GLOSSARY.md +++ b/translations/zh-MO/docs/GLOSSARY.md @@ -2,231 +2,229 @@ ## 目錄 -- [核心概念](../../../docs) -- [LangChain4j 組件](../../../docs) -- [AI/ML 概念](../../../docs) -- [防護措施](../../../docs) -- [提示工程](../../../docs) -- [RAG（檢索增強生成）](../../../docs) -- [代理與工具](../../../docs) -- [代理模組](../../../docs) -- [模型上下文協議 (MCP)](../../../docs) -- [Azure 服務](../../../docs) -- [測試與開發](../../../docs) - -課程中使用的術語和概念快速參考。 +- [核心概念](#核心概念) +- [LangChain4j 元件](#langchain4j-元件) +- [AI/ML 概念](#aiml-概念) +- [安全防護](#安全防護) +- [提示詞工程](#prompt-engineering---module-02) +- [RAG（檢索增強生成）](#rag-retrieval-augmented-generation---module-03) +- [代理與工具](#agents-and-tools---module-04) +- [代理模組](#agentic-module---module-05) +- [模型上下文協定 (MCP)](#model-context-protocol-mcp---module-05) +- [Azure 服務](#azure-services---module-01) +- [測試與開發](#testing-and-development---testing-guide) + +課程中使用的術語與概念快速參考。 ## 核心概念 -**AI Agent** - 使用 AI 進行推理和自主行動的系統。 [模組 04](../04-tools/README.md) +**AI 代理** – 使用 AI 進行推理並自主行動的系統。[模組 04](../04-tools/README.md) -**Chain** - 一系列操作，輸出作為下一步輸入。 +**鏈（Chain）** – 操作序列，其輸出餵給下一步。 -**Chunking** - 將文件分割成較小片段。典型大小：300-500 代幣，帶有重疊。 [模組 03](../03-rag/README.md) +**分塊（Chunking）** – 把文件拆成較小片段。典型為300-500個標記，有重疊。[模組 03](../03-rag/README.md) -**Context Window** - 模型可處理的最大代幣數。GPT-5.2：400K 代幣（最多 272K 輸入，128K 輸出）。 +上下文視窗 – 模型可處理的最大標記數。GPT-5.2：400K標記（最多272K輸入，128K輸出）。 -**Embeddings** - 表示文本含義的數值向量。 [模組 03](../03-rag/README.md) +**嵌入（Embeddings）** – 表示文字意義的數值向量。[模組 03](../03-rag/README.md) -**Function Calling** - 模型生成結構化請求以調用外部函數。 [模組 04](../04-tools/README.md) +函式呼叫 – 模型生成結構化請求以呼叫外部函式。[模組 04](../04-tools/README.md) -**Hallucination** - 模型生成錯誤但似是而非的信息。 +**幻覺（Hallucination）** – 模型產生錯誤但看似合理的資訊。 -**Prompt** - 語言模型的文本輸入。 [模組 02](../02-prompt-engineering/README.md) +**提示詞（Prompt）** – 輸入給語言模型的文字。[模組 02](../02-prompt-engineering/README.md) -**Semantic Search** - 使用嵌入向量按意義搜尋，而非關鍵詞。 [模組 03](../03-rag/README.md) +語義搜尋 – 使用嵌入按意義搜尋，而非關鍵字。[模組 03](../03-rag/README.md) -**Stateful vs Stateless** - Stateless：無記憶。Stateful：保留對話歷史。 [模組 01](../01-introduction/README.md) +**有狀態 vs 無狀態** – 無狀態：無記憶。 有狀態：保留對話歷史。[模組 01](../01-introduction/README.md) -**Tokens** - 模型處理的基本文本單位。影響成本與限制。 [模組 01](../01-introduction/README.md) +**標記（Tokens）** – 模型處理的基本文字單位。影響成本與限制。[模組 01](../01-introduction/README.md) -**Tool Chaining** - 工具依序執行，輸出用於下一次調用。 [模組 04](../04-tools/README.md) +工具鏈接 – 按序執行工具，輸出成為後續調用依據。[模組 04](../04-tools/README.md) -## LangChain4j 組件 +## LangChain4j 元件 -**AiServices** - 建立類型安全的 AI 服務介面。 +**AiServices** – 創建型別安全的 AI 服務接口。 -**OpenAiOfficialChatModel** - OpenAI 與 Azure OpenAI 模型的統一客戶端。 +**OpenAiOfficialChatModel** – 用於 OpenAI 及 Azure OpenAI 模型的統一客戶端。 -**OpenAiOfficialEmbeddingModel** - 使用 OpenAI 官方客戶端建立嵌入（支援 OpenAI 與 Azure OpenAI）。 +**OpenAiOfficialEmbeddingModel** – 使用 OpenAI 官方客戶端建立嵌入（同時支持 OpenAI 和 Azure OpenAI）。 -**ChatModel** - 語言模型核心介面。 +**ChatModel** – 語言模型核心介面。 -**ChatMemory** - 保持會話歷史。 +**ChatMemory** – 維護對話歷史。 -**ContentRetriever** - 尋找 RAG 相關的文件片段。 +**ContentRetriever** – 查找與 RAG 相關的文件片段。 -**DocumentSplitter** - 將文件拆分成片段。 +**DocumentSplitter** – 將文件拆成片段。 -**EmbeddingModel** - 將文本轉換為數值向量。 +**EmbeddingModel** – 將文字轉為數值向量。 -**EmbeddingStore** - 儲存與檢索嵌入。 +**EmbeddingStore** – 儲存及檢索嵌入。 -**MessageWindowChatMemory** - 維持近期訊息的滑動視窗。 +**MessageWindowChatMemory** – 維護近期訊息的滑動視窗。 -**PromptTemplate** - 建立可重用提示，包含 `{{variable}}` 佔位符。 +**PromptTemplate** – 使用 `{{variable}}` 佔位符創建可重用的提示詞。 -**TextSegment** - 帶有元數據的文本塊，用於 RAG。 +**TextSegment** – 含有元資料的文字區段，用於 RAG。 -**ToolExecutionRequest** - 代表工具執行請求。 +**ToolExecutionRequest** – 代表工具執行請求。 -**UserMessage / AiMessage / SystemMessage** - 會話消息類型。 +**UserMessage / AiMessage / SystemMessage** – 對話訊息類型。 ## AI/ML 概念 -**Few-Shot Learning** - 在提示中提供範例。 [模組 02](../02-prompt-engineering/README.md) +**少量示例學習（Few-Shot Learning）** – 在提示中提供示例。[模組 02](../02-prompt-engineering/README.md) -**Large Language Model (LLM)** - 以大量文本數據訓練的 AI 模型。 +**大型語言模型 (LLM)** – 在大量文本資料上訓練的 AI 模型。 -**Reasoning Effort** - GPT-5.2 控制推理深度的參數。 [模組 02](../02-prompt-engineering/README.md) +**推理努力（Reasoning Effort）** – GPT-5.2 控制推理深度的參數。[模組 02](../02-prompt-engineering/README.md) -**Temperature** - 控制輸出隨機性。低溫＝決定性，高溫＝創造性。 +**溫度（Temperature）** – 控制輸出隨機性。低＝確定性，高＝創造性。 -**Vector Database** - 專為嵌入設計的資料庫。 [模組 03](../03-rag/README.md) +向量資料庫 – 專為嵌入設計的資料庫。[模組 03](../03-rag/README.md) -**Zero-Shot Learning** - 無範例執行任務。 [模組 02](../02-prompt-engineering/README.md) +**零示例學習（Zero-Shot Learning）** – 在無示例情況下執行任務。[模組 02](../02-prompt-engineering/README.md) -## 防護措施 - [模組 00](../00-quick-start/README.md) +## 安全防護 -**Defense in Depth** - 多層次安全策略，結合應用層防護與供應商安全過濾。 +**多層防禦（Defense in Depth）** – 結合應用層防護與提供者安全過濾的多層安全策略。 -**Hard Block** - 供應商對嚴重違規內容直接回傳 HTTP 400 錯誤。 +**硬性封鎖（Hard Block）** – 提供者針對嚴重內容違規回傳 HTTP 400 錯誤。 -**InputGuardrail** - LangChain4j 介面，用於在輸入到 LLM 前驗證用戶輸入。透過早期封鎖惡意提示節省成本與延遲。 +**InputGuardrail** – LangChain4j 介面，用於在提示送入 LLM 前驗證用戶輸入。透過早期阻擋有害提示節省成本與延遲。 -**InputGuardrailResult** - 防護檢查返回類型：`success()` 或 `fatal("原因")`。 +**InputGuardrailResult** – 防護驗證返回類型：`success()` 或 `fatal("reason")`。 -**OutputGuardrail** - 驗證 AI 回應後再返回給用戶的介面。 +**OutputGuardrail** – 驗證 AI 回應再返回使用者前的接口。 -**Provider Safety Filters** - AI 供應商（如 GitHub Models）內建內容過濾器，在 API 層阻擋違規。 +提供者安全過濾器 – AI 提供者（如 Azure OpenAI）內建的內容過濾器，在 API 層捕捉違規。 -**Soft Refusal** - 模型禮貌拒絕回答但不返回錯誤。 +**軟性拒絕（Soft Refusal）** – 模型禮貌拒答，無錯誤丟出。 -## 提示工程 - [模組 02](../02-prompt-engineering/README.md) +## 提示詞工程 - [模組 02](../02-prompt-engineering/README.md) -**Chain-of-Thought** - 逐步推理以提升準確度。 +**鏈式思考（Chain-of-Thought）** – 逐步推理以提高精準度。 -**Constrained Output** - 強制特定格式或結構。 +**約束輸出（Constrained Output）** – 強制特定格式或結構。 -**High Eagerness** - GPT-5.2 模式，要求徹底推理。 +**高熱情（High Eagerness）** – GPT-5.2 的細緻推理模式。 -**Low Eagerness** - GPT-5.2 模式，快速回答。 +**低熱情（Low Eagerness）** – GPT-5.2 的快速回應模式。 -**Multi-Turn Conversation** - 談話串保持上下文。 +**多輪對話（Multi-Turn Conversation）** – 在多次交流中維持上下文。 -**Role-Based Prompting** - 透過系統消息設定模型角色。 +**角色提示（Role-Based Prompting）** – 透過系統訊息設定模型角色。 -**Self-Reflection** - 模型自我評估並改進輸出。 +**自我反思（Self-Reflection）** – 模型評估並改進自身輸出。 -**Structured Analysis** - 固定評估框架。 +**結構化分析（Structured Analysis）** – 固定評估框架。 -**Task Execution Pattern** - 計畫 → 執行 → 總結。 +**任務執行模式（Task Execution Pattern）** – 計劃 → 執行 → 總結。 ## RAG（檢索增強生成） - [模組 03](../03-rag/README.md) -**Document Processing Pipeline** - 載入 → 切割 → 嵌入 → 儲存。 +文件處理管線 – 載入 → 分塊 → 嵌入 → 儲存。 -**In-Memory Embedding Store** - 用於測試的非持久儲存。 +記憶體嵌入庫 – 用於測試的非持久性儲存。 -**RAG** - 結合檢索與生成以增強回答可靠性。 +**RAG** – 結合檢索與生成以增強回答的依據。 -**Similarity Score** - 語義相似度量（0-1）。 +相似度分數 – 語義相似度量度（0-1）。 -**Source Reference** - 檢索內容的元資料。 +來源參考 – 取回內容的元資料。 ## 代理與工具 - [模組 04](../04-tools/README.md) -**@Tool Annotation** - 標註 Java 方法為 AI 可調用工具。 +**@Tool 標註** – 標記 Java 方法為 AI 可調用工具。 -**ReAct Pattern** - 推理 → 行動 → 觀察 → 重複。 +**ReAct 模式** – 推理 → 行動 → 觀察 → 重複。 -**Session Management** - 為不同用戶區分上下文。 +會話管理 – 為不同用戶分離上下文。 -**Tool** - AI 代理可調用的功能。 +工具 – AI 代理可呼叫的函式。 -**Tool Description** - 工具功能與參數文件。 +工具描述 – 工具目的與參數的文件。 ## 代理模組 - [模組 05](../05-mcp/README.md) -**@Agent Annotation** - 標註介面為具宣告式行為定義的 AI 代理。 +**@Agent 標註** – 將介面標註為 AI 代理，並用聲明式定義行為。 -**Agent Listener** - 透過 `beforeAgentInvocation()` 和 `afterAgentInvocation()` 監控代理執行的掛勾。 +代理監聽器 – 透過 `beforeAgentInvocation()` 與 `afterAgentInvocation()` 監控代理執行的鉤子。 -**Agentic Scope** - 代理共享記憶區，代理使用 `outputKey` 儲存輸出給下游代理使用。 +代理作用域 – 共享記憶體，代理使用 `outputKey` 儲存輸出，供後續代理使用。 -**AgenticServices** - 建立代理的工廠，提供 `agentBuilder()` 與 `supervisorBuilder()`。 +**AgenticServices** – 透過 `agentBuilder()` 和 `supervisorBuilder()` 創建代理的工廠。 -**Conditional Workflow** - 根據條件路由至不同專家代理。 +條件工作流程 – 根據條件路由至不同專家代理。 -**Human-in-the-Loop** - 工作流加入人工審核或內容審查節點。 +**人機協同流程（Human-in-the-Loop）** – 增加人工審核或內容審查的工作流模式。 -**langchain4j-agentic** - 宣告式代理工廠的 Maven 依賴（實驗性質）。 +**langchain4j-agentic** – 用於聲明式代理構建的 Maven 依賴（實驗性）。 -**Loop Workflow** - 持續迭代代理執行直到滿足條件（如質量分數 ≥ 0.8）。 +迴圈工作流程 – 迭代執行代理直到達成條件（例如品質分數 ≥ 0.8）。 -**outputKey** - 代理註解參數，指定結果存放於 Agentic Scope 的位置。 +**outputKey** – 代理標註參數，指定結果在代理作用域中的存放位置。 -**Parallel Workflow** - 同時執行多個獨立任務代理。 +平行工作流程 – 同時執行多名代理以處理獨立任務。 -**Response Strategy** - 主管如何形成最終回答策略：LAST、SUMMARY 或 SCORED。 +回應策略 – 主管代理形成最終答覆的方法：LAST、SUMMARY 或 SCORED。 -**Sequential Workflow** - 依序執行代理，輸出作為下一步輸入。 +序列工作流程 – 按順序執行代理，輸出流向下一步。 -**Supervisor Agent Pattern** - 進階代理模式，主管 LLM 動態決定調用哪些子代理。 +**監督代理模式（Supervisor Agent Pattern）** – 進階代理模式，由主管 LLM 動態決定召喚哪些子代理。 -## 模型上下文協議 (MCP) - [模組 05](../05-mcp/README.md) +## 模型上下文協定 (MCP) - [模組 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j 中 MCP 整合的 Maven 依賴。 +**langchain4j-mcp** – LangChain4j 中 MCP 整合的 Maven 依賴。 -**MCP** - 模型上下文協議：連接 AI 應用與外部工具的標準。一次構建，到處使用。 +**MCP** – 模型上下文協定：將 AI 應用與外部工具連接的標準。一次構建，到處使用。 -**MCP Client** - 連接 MCP 伺服器，發現並使用工具的應用。 +**MCP 客戶端** – 連接 MCP 伺服器以發現和使用工具的應用程式。 -**MCP Server** - 透過 MCP 提供工具的服務，附帶清晰描述與參數結構。 +**MCP 伺服器** – 透過 MCP 提供工具的服務，附帶明確描述與參數結構。 -**McpToolProvider** - LangChain4j 元件，包裝 MCP 工具供 AI 服務與代理使用。 +**McpToolProvider** – LangChain4j 元件，封裝 MCP 工具供 AI 服務與代理使用。 -**McpTransport** - MCP 通信介面，實現包括 Stdio 和 HTTP。 +**McpTransport** – MCP 通訊介面。實作包括 Stdio 與 HTTP。 -**Stdio Transport** - 透過 stdin/stdout 的本地流程傳輸。適用於存取文件系統或命令列工具。 +**Stdio 傳輸** – 經 stdin/stdout 的本地處理程序傳輸。適用於檔案系統存取或命令列工具。 -**StdioMcpTransport** - LangChain4j 實現，啟動 MCP 伺服器子程序。 +**StdioMcpTransport** – LangChain4j 實作，啟動 MCP 伺服器作為子程序。 -**Tool Discovery** - 客戶端查詢伺服器可用工具及其描述與結構。 +工具發現 – 客戶端查詢伺服器提供的工具及其描述與結構。 ## Azure 服務 - [模組 01](../01-introduction/README.md) -**Azure AI Search** - 支援向量功能的雲端搜尋服務。 [模組 03](../03-rag/README.md) +**Azure AI Search** – 支援向量能力的雲端搜尋。[模組 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - 部署 Azure 資源工具。 +**Azure Developer CLI (azd)** – 部署 Azure 資源。 -**Azure OpenAI** - 微軟的企業級 AI 服務。 +**Azure OpenAI** – 微軟企業級 AI 服務。 -**Bicep** - Azure 基礎架構即代碼語言。 [基礎設施指南](../01-introduction/infra/README.md) +**Bicep** – Azure 基礎架構即程式碼語言。[基礎架構指南](../01-introduction/infra/README.md) -**Deployment Name** - Azure 中模型部署的名稱。 +部署名稱 – Azure 中模型部署的名稱。 -**GPT-5.2** - 最新 OpenAI 模型，具備推理控制能力。 [模組 02](../02-prompt-engineering/README.md) +**GPT-5.2** – 最新 OpenAI 模型，帶有推理控制。[模組 02](../02-prompt-engineering/README.md) ## 測試與開發 - [測試指南](TESTING.md) -**Dev Container** - 容器化開發環境。 [設定](../../../.devcontainer/devcontainer.json) +開發容器 – 容器化的開發環境。[設定](../../../.devcontainer/devcontainer.json) -**GitHub Models** - 免費 AI 模型試驗場。 [模組 00](../00-quick-start/README.md) +記憶體測試 – 使用記憶體儲存的測試。 -**In-Memory Testing** - 使用記憶體儲存執行測試。 +整合測試 – 使用真實基礎架構的測試。 -**Integration Testing** - 使用真實基礎設施進行測試。 +**Maven** – Java 建置自動化工具。 -**Maven** - Java 建構自動化工具。 +**Mockito** – Java 模擬框架。 -**Mockito** - Java 模擬框架。 - -**Spring Boot** - Java 應用框架。 [模組 01](../01-introduction/README.md) +**Spring Boot** – Java 應用框架。[模組 01](../01-introduction/README.md) --- -**免責聲明**： -本文件是使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。雖然我們努力確保翻譯的準確性，但請注意，機器自動翻譯可能會包含錯誤或不準確之處。原始語言版本的文件應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用此翻譯而引起的任何誤解或誤譯承擔責任。 +**免責聲明**： +本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。 \ No newline at end of file diff --git a/translations/zh-MO/docs/TESTING.md b/translations/zh-MO/docs/TESTING.md index 0823ca279..b80b3209b 100644 --- a/translations/zh-MO/docs/TESTING.md +++ b/translations/zh-MO/docs/TESTING.md @@ -2,19 +2,19 @@ ## 目錄 -- [快速開始](../../../docs) -- [測試範圍](../../../docs) -- [執行測試](../../../docs) -- [在 VS Code 中執行測試](../../../docs) -- [測試模式](../../../docs) -- [測試理念](../../../docs) -- [下一步](../../../docs) +- [快速入門](#快速入門) +- [測試涵蓋範圍](#測試涵蓋範圍) +- [執行測試](#執行測試) +- [在 VS Code 中執行測試](#在-vs-code-中執行測試) +- [測試範式](#測試範式) +- [測試哲學](#測試哲學) +- [下一步](#下一步) -本指南引導您了解示範如何測試 AI 應用程式，而無需 API 金鑰或外部服務的測試。 +本指南將帶領你了解如何在不需使用 API 金鑰或外部服務的情況下，測試 AI 應用程式的內容。 -## 快速開始 +## 快速入門 -使用一個指令運行所有測試： +使用單一指令執行所有測試： **Bash:** ```bash @@ -26,32 +26,31 @@ mvn test mvn --% test ``` -當所有測試通過時，您應該會看到如下截圖的輸出 — 測試沒有失敗。 +全部測試通過後，你應該會看到如下截圖所示的輸出 — 沒有失敗的測試。 Successful Test Results -*成功執行測試，所有測試通過且無失敗* +*成功執行測試，顯示所有測試均通過，無失敗* -## 測試範圍 +## 測試涵蓋範圍 -本課程專注於本地執行的 **單元測試**。每個測試獨立示範了 LangChain4j 的特定概念。下面的測試金字塔展示了單元測試的位置 — 它們構成快速且可靠的基礎，您其餘的測試策略都建立於此。 +本課程主要關注於本地執行的單元測試。每個測試演示一個獨立的 LangChain4j 概念。下方的測試金字塔展示單元測試的位置 — 它們構成快速且可靠的基礎，支撐你其餘的測試策略。 Testing Pyramid -*測試金字塔顯示單元測試（快速、獨立）、整合測試（真實組件）及端對端測試的比例。本培訓涵蓋單元測試。* +*測試金字塔展示單元測試（快速、獨立）、整合測試（實體組件）與端對端測試的平衡。本訓練涵蓋單元測試。* -| 模組 | 測試 | 重點 | 主要檔案 | +| 模塊 | 測試數 | 焦點 | 主要檔案 | |--------|-------|-------|-----------| -| **00 - 快速開始** | 6 | 提示模板與變數替換 | `SimpleQuickStartTest.java` | | **01 - 介紹** | 8 | 會話記憶與有狀態聊天 | `SimpleConversationTest.java` | -| **02 - 提示工程** | 12 | GPT-5.2 模式、積極性等級、結構化輸出 | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | 文件攝取、嵌入、相似度搜尋 | `DocumentServiceTest.java` | -| **04 - 工具** | 12 | 函數呼叫與工具串接 | `SimpleToolsTest.java` | -| **05 - MCP** | 8 | 搭配 Stdio 傳輸的模型上下文協定 | `SimpleMcpTest.java` | +| **02 - 提示工程** | 12 | GPT-5.2 範式、急切程度、結構化輸出 | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | 文件攝取、嵌入、相似度搜索 | `DocumentServiceTest.java` | +| **04 - 工具** | 12 | 函數呼叫與工具鏈接 | `SimpleToolsTest.java` | +| **05 - MCP** | 8 | 透過 Stdio 傳輸的模型上下文協議 | `SimpleMcpTest.java` | ## 執行測試 -**從根目錄運行所有測試：** +**從根目錄執行所有測試：** **Bash:** ```bash @@ -63,7 +62,7 @@ mvn test mvn --% test ``` -**運行指定模組的測試：** +**執行特定模塊的測試：** **Bash:** ```bash @@ -79,7 +78,7 @@ cd 01-introduction; mvn --% test mvn --% test -pl 01-introduction ``` -**運行單一測試類別：** +**執行單一測試類別：** **Bash:** ```bash @@ -91,45 +90,45 @@ mvn test -Dtest=SimpleConversationTest mvn --% test -Dtest=SimpleConversationTest ``` -**運行指定測試方法：** +**執行特定測試方法：** **Bash:** ```bash -mvn test -Dtest=SimpleConversationTest#應該保持對話歷史 +mvn test -Dtest=SimpleConversationTest#應該維持對話歷史 ``` **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#應該保持對話記錄 +mvn --% test -Dtest=SimpleConversationTest#應該保持對話歷史 ``` ## 在 VS Code 中執行測試 -如果您使用 Visual Studio Code，測試總覽器提供了圖形介面來執行和除錯測試。 +若使用 Visual Studio Code，測試瀏覽器提供圖形介面以執行與除錯測試。 VS Code Test Explorer -*VS Code 測試總覽器顯示測試樹，包含所有 Java 測試類及個別測試方法* +*VS Code 測試瀏覽器顯示具有所有 Java 測試類與各個測試方法的樹狀結構* -**在 VS Code 中執行測試：** +**在 VS Code 中執行測試步驟：** -1. 點擊活動列的燒杯圖示打開測試總覽器 -2. 展開測試樹以查看所有模組和測試類別 -3. 點擊任一測試旁的播放按鈕個別執行 +1. 點擊活動欄中的試管圖示以開啟測試瀏覽器 +2. 展開測試樹以查看所有模組和測試類 +3. 點擊任一測試旁的播放按鈕以單獨執行該測試 4. 點擊「執行所有測試」以執行整個測試套件 -5. 右鍵點擊任一測試並選擇「除錯測試」以設定斷點並逐步檢視程式碼 +5. 右鍵點擊任一測試並選擇「除錯測試」以設定斷點並逐步執行程式碼 -測試總覽器對通過的測試顯示綠色勾號，失敗時提供詳細的錯誤訊息。 +通過的測試會顯示綠色勾號，失敗時則會提供詳細的錯誤訊息。 -## 測試模式 +## 測試範式 -### 模式 1：測試提示模板 +### 範式 1：測試提示範本 -最簡單的模式是在不呼叫任何 AI 模型的情況下測試提示模板。您驗證變數替換是否正確，提示是否格式化如預期。 +最簡單的範式是測試提示範本而不呼叫任何 AI 模型。你將驗證變數替換是否正確，以及提示是否按預期格式化。 Prompt Template Testing -*提示模板測試展示變數替換流程：帶有佔位符的模板 → 套用值 → 驗證格式化輸出* +*測試提示範本展示變數替換流程：帶有佔位符的範本 → 應用變數值 → 驗證格式化輸出* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -此測試位於 `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`。 +此範式驗證變數替換功能是否正確，並確保提示格式符合預期 — 無需 API 金鑰或模型呼叫。 -**執行方式：** +### 範式 2：模擬語言模型 -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#測試提示模板格式化 -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#測試提示模板格式 -``` - -### 模式 2：模擬語言模型 - -測試會話邏輯時，使用 Mockito 創建假模型返回預設回應。這使測試快速、免費且可預測。 +在測試會話邏輯時，使用 Mockito 建立假模型，讓其返回預設回應。這使測試快速、免費且具決定性。 Mock vs Real API Comparison -*比較展示為何測試優先使用模擬：快速、免費、可預測，且無需 API 金鑰* +*比較展示為何測試偏好使用模擬：模擬快速、免費、決定性且不需 API 金鑰* ```java @ExtendWith(MockitoExtension.class) @@ -213,20 +200,20 @@ class SimpleConversationTest { conversationService.chat(conversationId, "Third message"); List history = conversationService.getHistory(conversationId); - assertThat(history).hasSize(6); // 3 用戶 + 3 AI 訊息 + assertThat(history).hasSize(6); // 3 個用戶 + 3 個 AI 訊息 } } ``` -此模式出現在 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`。模擬確保行為一致，便於驗證記憶管理正常。 +此範式出現在 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`。模擬確保一致行為，因此你可以驗證記憶管理的正確性。 -### 模式 3：測試會話隔離 +### 範式 3：測試會話隔離 -會話記憶必須將多用戶分離。此測試驗證會話不會混淆上下文。 +會話記憶必須區分多位使用者。本測試確認會話不會混淆使用者上下文。 Conversation Isolation -*測試會話隔離，展示不同用戶分開的記憶存儲以防止上下文混淆* +*測試會話隔離，顯示不同用戶的獨立記憶存儲以防混淆上下文* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -每個會話保持獨立歷史。於生產系統中，此隔離對多用戶應用至關重要。 +每個會話維持自己的獨立歷史。在生產系統中，這種隔離對於多用戶應用程式至關重要。 -### 模式 4：獨立測試工具 +### 範式 4：獨立測試工具 -工具是 AI 可呼叫的函數。直接測試它們確保即使 AI 不決定仍能正常運作。 +工具是 AI 可呼叫的函數。直接測試工具以確保其功能正確，無需依賴 AI 決策。 Tools Testing -*獨立測試工具，展示用模擬工具執行，不須 AI 呼叫以驗證商業邏輯* +*獨立測試工具，顯示模擬工具執行而不含 AI 呼叫以驗證業務邏輯* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -此測試來自 `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`，驗證工具邏輯無需 AI 參與。串接範例說明一工具輸出如何作為另一工具輸入。 +這些測試來自 `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`，用來驗證工具邏輯無需 AI 參與。鏈接範例展示一個工具的輸出如何作為另一個工具的輸入。 -### 模式 5：記憶體內 RAG 測試 +### 範式 5：記憶中 RAG 測試 -RAG 系統通常依賴向量資料庫和嵌入服務。記憶體內模式讓您無需外部依賴測試整條管線。 +RAG 系統一般需向量資料庫與嵌入服務。記憶中範式讓你不依賴外部套件，測試整個流程。 In-Memory RAG Testing -*記憶體內 RAG 測試流程，展示文件解析、嵌入儲存與相似度搜索，無需資料庫* +*記憶中 RAG 測試流程，展示文件解析、嵌入存儲及相似度搜索，無需資料庫* ```java @Test @@ -306,15 +293,15 @@ void testProcessTextDocument() { } ``` -此測試來自 `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`，在記憶體建文件並驗證分塊與元資料處理。 +此測試出自 `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`，在記憶中創建文件，並驗證分段與元資料處理。 -### 模式 6：MCP 整合測試 +### 範式 6：MCP 整合測試 -MCP 模組測試使用 stdio 傳輸的模型上下文協定整合。這些測試驗證應用程式可作為子程序啟動並與 MCP 伺服器通訊。 +MCP 模組測試透過 stdio 傳輸的模型上下文協議整合。這些測試確認你的應用能啟動並與 MCP 伺服器子程序通訊。 -`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` 中的測試驗證 MCP 用戶端行為。 +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` 中包含相關驗證 MCP 用戶端行為的測試。 -**執行方式：** +**執行命令：** **Bash:** ```bash @@ -326,30 +313,29 @@ cd 05-mcp && mvn test cd 05-mcp; mvn --% test ``` -## 測試理念 +## 測試哲學 -測試您的程式碼，不是 AI。測試應驗證您撰寫的程式碼，檢查提示如何建構、記憶如何管理、工具如何執行。AI 回應有變化，不應成為測試斷言的一部分。要問自己您的提示模板是否正確替換變數，而不是 AI 是否給正確答案。 +測試你的程式碼，而不是 AI。本測試應該驗證你撰寫的程式碼，例如提示如何建構、記憶如何管理、工具如何執行。AI 回應會變化，不應成為測試斷言的一部分。你應該確認提示範本是否正確替換變數，而非 AI 是否給出正確答案。 -對語言模型使用模擬。它們是慢、貴且非決定性的外部依賴。使用模擬能讓測試快速（毫秒而非秒）、免費（無 API 費用）、決定性（每次結果一致）。 +對語言模型使用模擬。它們是外部依賴，執行緩慢、昂貴且非決定性。模擬讓測試快速（毫秒級而非秒）、免費且結果一致。 -保持測試獨立。每個測試應自行準備資料，不依賴其他測試且執行後清理。測試不應受執行順序影響皆能通過。 +保持測試獨立。每個測試應自行建立資料，不依賴其他測試，且執行後會清理環境。不論測試順序如何，皆應通過。 -測試邊界條件，超越正常流程。嘗試空輸入、非常大輸入、特殊字元、無效參數與邊界條件。這些通常揭露一般使用不會發現的錯誤。 +測試邊界情況，而非只有理想情況。嘗試空輸入、極大輸入、特殊字元、無效參數與邊界條件。這些通常能揭露日常使用未暴露的錯誤。 -使用具描述性的名稱。比較 `shouldMaintainConversationHistoryAcrossMultipleMessages()` 與 `test1()`。前者明確指出測試內容，方便除錯失敗。 +使用具描述性的名稱。對比 `shouldMaintainConversationHistoryAcrossMultipleMessages()` 和 `test1()`。前者明確說明測試內容，令除錯失敗更容易。 ## 下一步 -既然您了解測試模式，請深入瞭解各模組： +了解測試範式後，深入探索每個模組： -- **[00 - 快速開始](../00-quick-start/README.md)** - 從提示模板基礎開始 - **[01 - 介紹](../01-introduction/README.md)** - 學習會話記憶管理 -- **[02 - 提示工程](../02/prompt-engineering/README.md)** - 精通 GPT-5.2 提示模式 -- **[03 - RAG](../03-rag/README.md)** - 建置檢索增強生成系統 -- **[04 - 工具](../04-tools/README.md)** - 實作函數呼叫與工具串接 -- **[05 - MCP](../05-mcp/README.md)** - 整合模型上下文協定 +- **[02 - 提示工程](../02/prompt-engineering/README.md)** - 精通 GPT-5.2 提示範式 +- **[03 - RAG](../03-rag/README.md)** - 建立檢索增強生成系統 +- **[04 - 工具](../04-tools/README.md)** - 實作函數呼叫與工具鏈 +- **[05 - MCP](../05-mcp/README.md)** - 整合模型上下文協議 -各模組 README 提供本處測試概念的詳細說明。 +各模組 README 對此處所測試的概念提供詳細介紹。 --- @@ -358,6 +344,6 @@ cd 05-mcp; mvn --% test --- -**免責聲明**： -本文件係使用人工智能翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 所翻譯。雖然我哋致力追求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件之母語版本應被視為權威來源。對於重要資訊，建議採用專業人工翻譯。我哋不對因使用本翻譯而引致嘅任何誤解或錯誤解讀承擔責任。 +**免責聲明**： +本文件使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。 \ No newline at end of file diff --git a/translations/zh-TW/.co-op-translator.json b/translations/zh-TW/.co-op-translator.json index 91f738a61..04e8ddff5 100644 --- a/translations/zh-TW/.co-op-translator.json +++ b/translations/zh-TW/.co-op-translator.json @@ -6,8 +6,8 @@ "language_code": "zh-TW" }, "01-introduction/README.md": { - "original_hash": "9973acb599099b6ebad23063fcfc5739", - "translation_date": "2026-03-02T19:37:15+00:00", + "original_hash": "693678a589b4c81f3441a13ae1dcaf47", + "translation_date": "2026-07-03T14:13:25+00:00", "source_file": "01-introduction/README.md", "language_code": "zh-TW" }, @@ -18,20 +18,20 @@ "language_code": "zh-TW" }, "02-prompt-engineering/README.md": { - "original_hash": "7dc83a7a5b158f7e34adcc04042d370d", - "translation_date": "2026-03-02T19:39:06+00:00", + "original_hash": "0f0dc6973a544dc44279aeecbb2a0ae6", + "translation_date": "2026-07-03T14:09:30+00:00", "source_file": "02-prompt-engineering/README.md", "language_code": "zh-TW" }, "03-rag/README.md": { - "original_hash": "a965d4e6009b5bbce2033e9618b6a896", - "translation_date": "2026-03-02T19:40:16+00:00", + "original_hash": "68de4eff7477b1a18165d07baefc89b8", + "translation_date": "2026-07-03T14:12:36+00:00", "source_file": "03-rag/README.md", "language_code": "zh-TW" }, "04-tools/README.md": { - "original_hash": "2f3bcf70da63b0b57951b4928df23b4a", - "translation_date": "2026-03-10T09:48:18+00:00", + "original_hash": "7bfea11bf2e891d2347bc92495f73550", + "translation_date": "2026-07-03T14:11:30+00:00", "source_file": "04-tools/README.md", "language_code": "zh-TW" }, @@ -54,8 +54,8 @@ "language_code": "zh-TW" }, "README.md": { - "original_hash": "017a029136d87b82b4f9b9d821dad1f3", - "translation_date": "2026-04-06T15:40:26+00:00", + "original_hash": "bdb3cb8ff72e607754f65b3e6bb7ba23", + "translation_date": "2026-07-03T14:08:16+00:00", "source_file": "README.md", "language_code": "zh-TW" }, @@ -72,14 +72,14 @@ "language_code": "zh-TW" }, "docs/GLOSSARY.md": { - "original_hash": "f8fbe9fb0f3adc92eb3cd3835d140a4a", - "translation_date": "2026-03-02T19:42:57+00:00", + "original_hash": "d7b72d50668bfc542725e8fa4053eb58", + "translation_date": "2026-07-03T14:09:56+00:00", "source_file": "docs/GLOSSARY.md", "language_code": "zh-TW" }, "docs/TESTING.md": { - "original_hash": "608e564906adcffddb1033c48d76934e", - "translation_date": "2026-03-02T19:43:36+00:00", + "original_hash": "e1b03b752e8570c3d21edf76c9384527", + "translation_date": "2026-07-03T14:10:27+00:00", "source_file": "docs/TESTING.md", "language_code": "zh-TW" } diff --git a/translations/zh-TW/00-quick-start/README.md b/translations/zh-TW/00-quick-start/README.md deleted file mode 100644 index e42ba48fc..000000000 --- a/translations/zh-TW/00-quick-start/README.md +++ /dev/null @@ -1,386 +0,0 @@ -# Module 00: 快速開始 - -## 目錄 - -- [介紹](../../../00-quick-start) -- [什麼是 LangChain4j？](../../../00-quick-start) -- [LangChain4j 依賴項](../../../00-quick-start) -- [先決條件](../../../00-quick-start) -- [設定](../../../00-quick-start) - - [1. 取得你的 GitHub 代幣](../../../00-quick-start) - - [2. 設定你的代幣](../../../00-quick-start) -- [執行範例](../../../00-quick-start) - - [1. 基本對話](../../../00-quick-start) - - [2. 提示模式](../../../00-quick-start) - - [3. 函數呼叫](../../../00-quick-start) - - [4. 文件問答（簡易 RAG）](../../../00-quick-start) - - [5. 負責任的 AI](../../../00-quick-start) -- [每個範例展示的內容](../../../00-quick-start) -- [下一步](../../../00-quick-start) -- [疑難排解](../../../00-quick-start) - -## 介紹 - -本快速開始旨在讓你盡快開始使用 LangChain4j。它涵蓋了使用 LangChain4j 與 GitHub 模型構建 AI 應用的基本知識。在接下來的模組中，你將轉用 Azure OpenAI 和 GPT-5.2，並深入探討每個概念。 - -## 什麼是 LangChain4j？ - -LangChain4j 是一個 Java 函式庫，簡化了使用 AI 技術的應用程式建構。你不需處理 HTTP 用戶端和 JSON 解析，而是使用清晰的 Java API。 - -LangChain 中的「鏈」指的是將多個組件串接在一起——你可能將一個提示串接到模型，再串接到解析器，或將多個 AI 呼叫串接在一起，其中一個輸出作為下一個輸入。本快速開始專注於基礎原理，之後再探討更複雜的鏈結。 - -LangChain4j Chaining Concept - -*LangChain4j 中的串接組件—構建塊連接以創造強大的 AI 工作流程* - -我們將使用三個核心組件： - -**ChatModel** - AI 模型互動的介面。呼叫 `model.chat("prompt")` 並取得回應字串。我們使用 `OpenAiOfficialChatModel`，它可用於與兼容 OpenAI 的端點（例如 GitHub 模型）配合使用。 - -**AiServices** - 創建類型安全的 AI 服務介面。定義方法，使用 `@Tool` 註解，LangChain4j 負責協調。當需要時，AI 會自動呼叫你的 Java 方法。 - -**MessageWindowChatMemory** - 維護對話歷史。沒有它時，每個請求是獨立的。使用它時，AI 會記住之前的訊息並在多輪對話中維持上下文。 - -LangChain4j Architecture - -*LangChain4j 架構—核心組件協同運作以為你的 AI 應用提供動力* - -## LangChain4j 依賴項 - -本快速開始在 [`pom.xml`](../../../00-quick-start/pom.xml) 中使用三個 Maven 依賴項： - -```xml - - - dev.langchain4j - langchain4j - - - - - dev.langchain4j - langchain4j-open-ai-official - - - - - dev.langchain4j - langchain4j-easy-rag - -``` - -`langchain4j-open-ai-official` 模組提供了連接至 OpenAI 兼容 API 的 `OpenAiOfficialChatModel` 類別。GitHub 模型使用相同的 API 格式，因此不需要特殊適配器，只要將基底 URL 指向 `https://models.github.ai/inference` 即可。 - -`langchain4j-easy-rag` 模組提供自動文件分割、嵌入和檢索功能，讓你能建立 RAG 應用，而無需手動配置每一步。 - -## 先決條件 - -**使用開發容器？** Java 和 Maven 已預裝。你只需要 GitHub 個人存取權杖。 - -**本地開發：** -- Java 21+，Maven 3.9+ -- GitHub 個人存取權杖（以下有說明） - -> **注意：** 本模組使用 GitHub 模型的 `gpt-4.1-nano`。請勿更改程式碼中的模型名稱——它經過配置以配合 GitHub 可用的模型。 - -## 設定 - -### 1. 取得你的 GitHub 代幣 - -1. 前往 [GitHub 設定 → 個人存取權杖](https://github.com/settings/personal-access-tokens) -2. 點擊「Generate new token」 -3. 設定描述性名稱（例如 "LangChain4j Demo"） -4. 設定有效期限（建議 7 天） -5. 在「帳戶權限」中找到「Models」並設為「唯讀」 -6. 點擊「Generate token」 -7. 複製並保存你的代幣—此後將無法再看到 - -### 2. 設定你的代幣 - -**選項 1：使用 VS Code（推薦）** - -如果使用 VS Code，將代幣新增到專案根目錄的 `.env` 檔案： - -若 `.env` 檔案不存在，可複製 `.env.example` 為 `.env`，或在專案根目錄自行建立 `.env` 檔案。 - -**範例 `.env` 檔案：** -```bash -# 在 /workspaces/LangChain4j-for-Beginners/.env -GITHUB_TOKEN=your_token_here -``` - -之後你只需在檔案總管中右鍵點擊任何範例檔（如 `BasicChatDemo.java`），選擇 **「Run Java」**，或者從「執行與除錯」面板使用啟動配置。 - -**選項 2：使用終端機** - -將代幣設定成環境變數： - -**Bash:** -```bash -export GITHUB_TOKEN=your_token_here -``` - -**PowerShell:** -```powershell -$env:GITHUB_TOKEN=your_token_here -``` - -## 執行範例 - -**使用 VS Code：** 在檔案總管中右鍵點擊任何範例檔，選擇 **「Run Java」**，或從「執行與除錯」面板使用啟動配置（請先將代幣加入 `.env` 檔案）。 - -**使用 Maven：** 也可從命令列執行： - -### 1. 基本對話 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -### 2. 提示模式 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.PromptEngineeringDemo -``` - -展示零次示範、少次示範、思維連鎖和角色基礎的提示模式。 - -### 3. 函數呼叫 - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ToolIntegrationDemo -``` - -AI 會在需要時自動呼叫你的 Java 方法。 - -### 4. 文件問答（簡易 RAG） - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.SimpleReaderDemo -``` - -使用簡易 RAG 透過自動嵌入和檢索，對文件提出問題。 - -### 5. 負責任的 AI - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.ResponsibleAIDemo -``` - -查看 AI 安全過濾器如何阻擋有害內容。 - -## 每個範例展示的內容 - -**基本對話** - [BasicChatDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) - -從這裡開始了解最簡單的 LangChain4j。你將建立一個 `OpenAiOfficialChatModel`，使用 `.chat()` 傳送提示並取得回應。這展示了基礎：如何使用自訂端點和 API 金鑰初始化模型。理解這個模式後，其它依此展開。 - -```java -OpenAiOfficialChatModel model = OpenAiOfficialChatModel.builder() - .baseUrl("https://models.github.ai/inference") - .apiKey(System.getenv("GITHUB_TOKEN")) - .modelName("gpt-4.1-nano") - .build(); - -String response = model.chat("What is LangChain4j?"); -System.out.println(response); -``` - -> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試看：** 開啟 [`BasicChatDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/BasicChatDemo.java) 並問： -> - 「我如何在這段程式碼中從 GitHub 模型切換到 Azure OpenAI？」 -> - 「OpenAiOfficialChatModel.builder() 還可以設定哪些參數？」 -> - 「如何加入串流回應，而不必等完整回應？」 - -**提示工程** - [PromptEngineeringDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) - -現在你已知道如何和模型對話，接著探索應該對它說什麼。此範例使用相同模型設置，但展示五種不同的提示模式。嘗試零次示範直接指令、少次示範學習範例、思維連鎖揭示推理過程，與角色基礎提示設定上下文。你會看到同一模型根據請求的框架，結果截然不同。 - -範例也展示提示模板，這是建立可重用帶變數提示的有力方式。以下範例使用 LangChain4j 的 `PromptTemplate` 填入變數。AI 將根據提供的目的地與活動回答問題。 - -```java -PromptTemplate template = PromptTemplate.from( - "What's the best time to visit {{destination}} for {{activity}}?" -); - -Prompt prompt = template.apply(Map.of( - "destination", "Paris", - "activity", "sightseeing" -)); - -String response = model.chat(prompt.text()); -``` - -> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試看：** 開啟 [`PromptEngineeringDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/PromptEngineeringDemo.java) 並問： -> - 「零次示範和少次示範提示有何差異，何時該使用哪個？」 -> - 「溫度參數如何影響模型回應？」 -> - 「有哪些技術可防止生產環境中的提示注入攻擊？」 -> - 「如何建立常用模式的 reusable PromptTemplate 物件？」 - -**工具整合** - [ToolIntegrationDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) - -這是 LangChain4j 強大的地方。你將使用 `AiServices` 創建能呼叫你 Java 方法的 AI 助手。只需在方法上註解 `@Tool("描述")`，LangChain4j 會處理其餘工作——AI 會根據用戶請求自動決定何時使用各工具。這示範函數呼叫，為建構能執行動作而不只是回答問題的 AI 關鍵技術。 - -```java -@Tool("Performs addition of two numeric values") -public double add(double a, double b) { - return a + b; -} - -MathAssistant assistant = AiServices.builder(MathAssistant.class) - .chatModel(model) - .tools(new Calculator()) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .build(); -String response = assistant.chat("What is 25 plus 17?"); -``` - -> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試看：** 開啟 [`ToolIntegrationDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java) 並問： -> - 「@Tool 註解如何運作，LangChain4j 背後如何處理它？」 -> - 「AI 可以連續呼叫多個工具來解決複雜問題嗎？」 -> - 「如果工具拋出例外，該如何處理錯誤？」 -> - 「如何整合真實 API，而非此計算機範例？」 - -**文件問答（簡易 RAG）** - [SimpleReaderDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) - -這裡你會看到使用 LangChain4j 「簡易 RAG」的 RAG（檢索增強生成）。文件會被載入、自動拆分並嵌入到記憶體中，然後內容檢索器在查詢時供應相關段落給 AI。AI 根據你的文件回答，而非依賴其一般知識。 - -```java -Document document = loadDocument(Paths.get("document.txt")); - -InMemoryEmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); -EmbeddingStoreIngestor.ingest(List.of(document), embeddingStore); - -Assistant assistant = AiServices.builder(Assistant.class) - .chatModel(chatModel) - .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) - .contentRetriever(EmbeddingStoreContentRetriever.from(embeddingStore)) - .build(); - -String answer = assistant.chat("What is the main topic?"); -``` - -> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試看：** 開啟 [`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java) 並問： -> - 「RAG 如何防止 AI 幻覺，相較於使用模型訓練資料？」 -> - 「這種簡易方法與自訂 RAG 流程有何差異？」 -> - 「如何擴展以支援多份文件或更大知識庫？」 - -**負責任的 AI** - [ResponsibleAIDemo.java](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) - -建立深度防禦的 AI 安全。此範例展示兩層保護同時運作： - -**第一部分：LangChain4j 輸入防護措施** — 在提示到達 LLM 前阻擋危險內容。建立自訂防護措施檢查禁止關鍵字或模式。此部分在程式碼中執行，速度快且免費。 - -```java -class DangerousContentGuardrail implements InputGuardrail { - @Override - public InputGuardrailResult validate(UserMessage userMessage) { - String text = userMessage.singleText().toLowerCase(); - if (text.contains("explosives")) { - return fatal("Blocked: contains prohibited keyword"); - } - return success(); - } -} -``` - -**第二部分：供應商安全過濾器** — GitHub 模型有內建過濾機制，攔截你防護措施可能遺漏的內容。你會看到嚴重違規時的硬封鎖（HTTP 400 錯誤）以及軟拒絕，AI 客氣地拒絕回答。 - -> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試看：** 開啟 [`ResponsibleAIDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ResponsibleAIDemo.java) 並問： -> - 「什麼是 InputGuardrail？如何建立自己的？」 -> - 「硬封鎖和軟拒絕有何不同？」 -> - 「為何要同時使用防護措施和供應商過濾器？」 - -## 下一步 - -**下一模組：** [01-introduction - LangChain4j 入門](../01-introduction/README.md) - ---- - -**導覽：** [← 返回主頁](../README.md) | [下一頁：模組 01 - 介紹 →](../01-introduction/README.md) - ---- - -## 疑難排解 - -### 第一次 Maven 建置 - -**問題**：首次執行 `mvn clean compile` 或 `mvn package` 需時較長（10-15 分鐘） - -**原因**：Maven 需要首次下載所有專案依賴（Spring Boot、LangChain4j 函式庫、Azure SDK 等） - -**解決方案**：此為正常行為。之後重複建置會快許多，因為依賴已快取至本地。下載時間取決於你的網路速度。 - -### PowerShell Maven 指令語法 - -**問題**：Maven 指令執行錯誤，顯示 `Unknown lifecycle phase ".mainClass=..."` -**原因**：PowerShell 將 `=` 解釋為變數賦值運算子，破壞了 Maven 屬性語法 - -**解決方案**：在 Maven 命令前使用停止解析運算子 `--%`： - -**PowerShell:** -```powershell -mvn --% compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -**Bash:** -```bash -mvn compile exec:java -Dexec.mainClass=com.example.langchain4j.quickstart.BasicChatDemo -``` - -`--%` 運算子告訴 PowerShell 將所有剩餘的參數原樣傳遞給 Maven，不加以解析。 - -### Windows PowerShell 表情符號顯示 - -**問題**：AI 回應在 PowerShell 中顯示亂碼（例如 `????` 或 `â??`）而非表情符號 - -**原因**：PowerShell 預設編碼不支援 UTF-8 表情符號 - -**解決方案**：在執行 Java 應用程式前運行此命令： -```cmd -chcp 65001 -``` - -這會強制終端機使用 UTF-8 編碼。或者，改用對 Unicode 支援更佳的 Windows Terminal。 - -### 除錯 API 呼叫 - -**問題**：AI 模型出現認證錯誤、速率限制或非預期回應 - -**解決方案**：範例程式碼包含 `.logRequests(true)` 和 `.logResponses(true)`，會在主控台顯示 API 呼叫，有助於排查認證錯誤、速率限制或非預期回應。上線時移除這些設定以減少日誌雜訊。 - ---- - - -**免責聲明**： -本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們致力於確保翻譯的準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件以其母語版本為權威依據。對於關鍵資訊，建議採用專業人工翻譯。本公司不對因使用本翻譯所產生的任何誤解或錯誤詮釋負責。 - \ No newline at end of file diff --git a/translations/zh-TW/01-introduction/README.md b/translations/zh-TW/01-introduction/README.md index a216d8d0c..0247eb0c4 100644 --- a/translations/zh-TW/01-introduction/README.md +++ b/translations/zh-TW/01-introduction/README.md @@ -1,87 +1,87 @@ -# Module 01: LangChain4j 入門 +# Module 01: 使用 LangChain4j 入門 ## 目錄 -- [影片導覽](../../../01-introduction) -- [你將學到什麼](../../../01-introduction) -- [先決條件](../../../01-introduction) -- [理解核心問題](../../../01-introduction) -- [理解 Tokens](../../../01-introduction) -- [記憶是如何運作的](../../../01-introduction) -- [如何使用 LangChain4j](../../../01-introduction) -- [部署 Azure OpenAI 基礎架構](../../../01-introduction) -- [在本機執行應用程式](../../../01-introduction) -- [使用應用程式](../../../01-introduction) - - [無狀態聊天（左側面板）](../../../01-introduction) - - [有狀態聊天（右側面板）](../../../01-introduction) -- [下一步](../../../01-introduction) +- [影片導覽](#影片導覽) +- [您將學到什麼](#您將學到什麼) +- [先決條件](#先決條件) +- [理解核心問題](#理解核心問題) +- [理解 Tokens](#理解-tokens) +- [記憶如何運作](#記憶如何運作) +- [本模組如何使用 LangChain4j](#本模組如何使用-langchain4j) +- [部署 Azure OpenAI 基礎架構](#部署-azure-openai-基礎架構) +- [在本機執行應用程式](#在本機執行應用程式) +- [使用應用程式](#使用應用程式) + - [無狀態聊天（左側面板）](#無狀態聊天（左側面板）) + - [有狀態聊天（右側面板）](#有狀態聊天（右側面板）) +- [後續步驟](#後續步驟) ## 影片導覽 -觀看這場直播，說明如何開始使用本模組： +觀看此直播課程，說明如何開始使用本模組： -Getting Started with LangChain4j - Live Session +LangChain4j 入門 - 直播課程 -## 你將學到什麼 +## 您將學到什麼 -在快速入門中，你使用 GitHub Models 傳送提示、呼叫工具、建立 RAG 流程並測試保護措施。這些展示了可能的方式 — 現在我們轉向 Azure OpenAI 和 GPT-5.2，開始建立生產樣式的應用程式。本模組專注於會記得上下文並維持狀態的對話式 AI — 這些概念在快速入門的示範中有用到但沒有詳細說明。 +這是您使用 LangChain4j 和 Azure OpenAI 的起點。我們從基礎開始，逐步構建生產級應用程式。本模組專注於會記憶上下文且維持狀態的對話式 AI——這是後續所有模組的基礎概念。 -本指南全程使用 Azure OpenAI 的 GPT-5.2，因為其先進的推理能力讓不同模式的行為更明顯。加入記憶後，你會清楚看到差異。這讓你更容易理解每個元件為你的應用帶來什麼。 +整個指南中，我們將使用 Azure OpenAI 的 GPT-5.2，因為其強大的推理能力能讓不同模式的行為差異更為明顯。當您加入記憶功能時，即可明確看出差異。這讓您更容易理解每個組件如何強化您的應用程式。 -你將建立一個示範兩種模式的應用程式： +您將建立一個示範兩種模式的應用： -**無狀態聊天** — 每次請求都是獨立的。模型不會記得之前的訊息。這是你在快速入門中使用的模式。 +無狀態聊天 - 每個請求彼此獨立。模型不會記憶先前訊息。這是最簡單的起點。 -**有狀態對話** — 每次請求包含對話歷史。模型能跨多輪維持上下文。這是生產應用需要的模式。 +有狀態對話 - 每次請求包含對話歷史。模型跨多輪保持上下文。這是生產應用所需。 ## 先決條件 -- 具有 Azure OpenAI 使用權限的 Azure 訂閱 -- Java 21、Maven 3.9+ +- 具有 Azure OpenAI 權限的 Azure 訂閱 +- Java 21, Maven 3.9+ - Azure CLI (https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - Azure Developer CLI (azd) (https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) -> **注意：** 提供的 devcontainer 預先安裝了 Java、Maven、Azure CLI 和 Azure Developer CLI (azd)。 +> **注意：** 提供的開發容器中已預先安裝 Java、Maven、Azure CLI 和 Azure Developer CLI (azd)。 -> **注意：** 本模組使用 Azure OpenAI 上的 GPT-5.2。部署是透過 `azd up` 自動設定，請不要修改程式碼中的模型名稱。 +> **注意：** 本模組使用 Azure OpenAI 上的 GPT-5.2。部署會透過 `azd up` 自動設定，請勿在程式碼中修改模型名稱。 ## 理解核心問題 -語言模型是無狀態的。每次 API 呼叫都是獨立的。如果你送出「我的名字是約翰」，然後問「我的名字是什麼？」模型根本不知道你剛剛自我介紹了。它把每次請求當作你第一次對話。 +語言模型是無狀態的。每個 API 呼叫都是獨立的。如果您說「我的名字是 John」，接著問「我叫什麼名字？」，模型其實不知道您剛剛自我介紹。它會把每個請求視為您人生中第一次對話。 -這對於簡單問答沒問題，但對真正應用沒用。客服機器人需要記得你跟它說過什麼。個人助理需要上下文。任何多輪對話都需要記憶。 +這對簡單問答問題沒問題，但對實際應用卻毫無用處。客服聊天機器人需要記憶您告訴他的資訊。個人助理需要上下文。任何多輪對話都需要記憶。 -下面的圖示對比兩種方式 — 左側是無狀態呼叫，忘記你的名字；右側是有狀態呼叫，使用 ChatMemory 記得你的名字。 +下面圖示對比兩種做法——左邊是無狀態呼叫，會忘記您的名字；右邊是有 ChatMemory 支援的有狀態呼叫，記得您的名字。 -Stateless vs Stateful Conversations +無狀態與有狀態對話示意圖 -*無狀態（獨立呼叫）與有狀態（上下文感知）對話的差別* +*無狀態（獨立呼叫）與有狀態（上下文感知）對話的差異* ## 理解 Tokens -在深入對話前，了解 tokens 很重要 — tokens 是語言模型處理的基本文字單元： +在探討對話前，先了解 tokens －語言模型處理文本的基本單位，非常重要： -Token Explanation +Token 說明 -*文字如何被拆成 tokens 範例 — 「I love AI!」變成 4 個獨立的處理單元* +*文本如何拆解成 tokens 的範例 — 「I love AI!」變成 4 個獨立處理單位* -tokens 是 AI 模型衡量和處理文字的方式。詞語、標點甚至空格都可能是 tokens。你的模型有一次能處理的 token 數量上限（GPT-5.2 為 400,000，含最多 272,000 輸入 tokens 與 128,000 輸出 tokens）。了解 tokens 有助管理對話長度和成本。 +tokens 是 AI 模型衡量與處理文本的方式。字詞、標點符號甚至空格都能成為 tokens。您的模型一次可處理的 token 數有限（GPT-5.2 為 40 萬，輸入最高 272,000，輸出最高 128,000）。了解 tokens 有助於管理對話長度與花費。 -## 記憶是如何運作的 +## 記憶如何運作 -聊天記憶透過維持對話歷史解決無狀態問題。在送請求給模型前，框架會將相關的先前訊息加到前面。當你問「我的名字是什麼？」系統實際上是送出整段對話歷史，讓模型看到你之前說了「我的名字是約翰」。 +聊天記憶解決了無狀態問題，維持對話歷史。在您送出請求給模型前，框架會先放入相關的先前訊息。當您問「我叫什麼名字？」時，系統會把整個對話歷史送出，讓模型知道您之前說過「我的名字是 John」。 -LangChain4j 提供自動處理此事的記憶實作。你選擇保留幾則訊息，框架管理上下文視窗。下面圖示顯示 MessageWindowChatMemory 如何管理近期訊息的滑動視窗。 +LangChain4j 提供的記憶實作會自動處理這些問題。您可以設定保留的訊息數量，框架會管理上下文視窗。下圖顯示 MessageWindowChatMemory 如何維持近期訊息的滑動視窗。 -Memory Window Concept +記憶視窗概念 -*MessageWindowChatMemory 維持近期訊息的滑動視窗，自動捨棄較舊的訊息* +*MessageWindowChatMemory 維持近期訊息的滑動視窗，自動丟棄舊訊息* -## 如何使用 LangChain4j +## 本模組如何使用 LangChain4j -本模組在快速入門基礎上整合 Spring Boot 並加入對話記憶。組件搭配如下： +本模組整合了 Spring Boot 並加入對話記憶。整體架構如下： -**依賴項** — 新增兩個 LangChain4j 函式庫： +相依套件 - 新增兩個 LangChain4j 函式庫： ```xml @@ -94,7 +94,7 @@ LangChain4j 提供自動處理此事的記憶實作。你選擇保留幾則訊 ``` -**聊天模型** — 以 Spring bean 配置 Azure OpenAI（[LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java)）： +聊天模型 - 配置 Azure OpenAI 為 Spring bean ([LangChainConfig.java](../../../01-introduction/src/main/java/com/example/langchain4j/config/LangChainConfig.java))： ```java @Bean @@ -109,9 +109,9 @@ public OpenAiOfficialChatModel openAiOfficialChatModel() { } ``` -建構器從 `azd up` 設定的環境變數讀取認證。設定 `baseUrl` 為你的 Azure 端點，使 OpenAI 用戶端可與 Azure OpenAI 一起使用。 +建構器會從 `azd up` 設定的環境變數讀取憑證。設定 `baseUrl` 為您的 Azure 端點可讓 OpenAI 用戶端正確使用 Azure OpenAI。 -**對話記憶** — 使用 MessageWindowChatMemory 追蹤聊天歷史（[ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)）： +對話記憶 - 使用 MessageWindowChatMemory 跟蹤聊天歷史 ([ConversationService.java](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java))： ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -124,59 +124,59 @@ AiMessage aiMessage = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage); ``` -用 `withMaxMessages(10)` 建立記憶，保留最近 10 則訊息。用型別包裝器新增使用者與 AI 訊息：`UserMessage.from(text)` 與 `AiMessage.from(text)`。用 `memory.messages()` 取得歷史並送給模型。服務依對話 ID 保存獨立記憶，允許多使用者同時聊天。 +建立時調用 `withMaxMessages(10)` 保留最近 10 則訊息。使用帶型別包裝的方式新增使用者和 AI 訊息：`UserMessage.from(text)` 和 `AiMessage.from(text)`。透過 `memory.messages()` 取得歷史訊息，再送至模型。服務會依對話 ID 儲存不同記憶實體，允許多用戶同時聊天。 -> **🤖 可嘗試使用 [GitHub Copilot](https://github.com/features/copilot) 聊天功能：打開 [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java) 並問：** -> - 「MessageWindowChatMemory 在視窗滿時如何決定要丟棄哪些訊息？」 -> - 「我能用資料庫實作自訂記憶存儲嗎，取代記憶體？」 +> **🤖 嘗試用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打開 [`ConversationService.java`](../../../01-introduction/src/main/java/com/example/langchain4j/service/ConversationService.java)，問： +> - 「MessageWindowChatMemory 滑動視窗滿時如何決定丟棄哪些訊息？」 +> - 「我可以用資料庫實作自訂記憶存儲取代記憶體中儲存嗎？」 > - 「要如何加入摘要功能以壓縮舊的對話歷史？」 -無狀態聊天端點完全跳過記憶 — 就像快速入門的 `chatModel.chat(prompt)`。有狀態端點則是將訊息加入記憶、取得歷史，並在每次請求時包含該上下文。模型配置相同，模式不同。 +無狀態聊天端點完全跳過記憶，像快篩一樣直接呼叫 `chatModel.chat(prompt)`。有狀態端點會將訊息加入記憶，抓取歷史並在每次請求中包含上下文。模型設定同樣，模式不同。 ## 部署 Azure OpenAI 基礎架構 -**Bash:** +**Bash 指令：** ```bash cd 01-introduction azd up # 選擇訂閱和位置（建議使用 eastus2） ``` -**PowerShell:** +**PowerShell 指令：** ```powershell cd 01-introduction azd up # 選擇訂閱和位置（建議使用 eastus2） ``` -> **注意：** 若遇到逾時錯誤（`RequestConflict: Cannot modify resource ... provisioning state is not terminal`），只要再執行一次 `azd up` 即可。Azure 資源可能仍在背景部署，再試一次能讓部署在資源到達終止狀態後順利完成。 +> **注意：** 若遇到逾時錯誤（`RequestConflict: Cannot modify resource ... provisioning state is not terminal`），只需再執行一次 `azd up`。Azure 資源可能還在背景佈建，重試即可等資源進入最終狀態完成佈署。 -這將會： -1. 部署 Azure OpenAI 資源，包含 GPT-5.2 與 text-embedding-3-small 模型 -2. 自動在專案根目錄產生 `.env` 憑證檔案 -3. 設定所有需要的環境變數 +此步驟會： +1. 部署 Azure OpenAI 資源，包含 GPT-5.2 和 text-embedding-3-small 模型 +2. 自動生成根目錄的 `.env` 憑證檔案 +3. 設定所有必要的環境變數 -**部署遇到困難？** 請參考 [Infrastructure README](infra/README.md) 取得詳細疑難排解，包含子網域名稱衝突、手動 Azure Portal 部署步驟與模型設定指引。 +**部署有問題？** 請參考 [Infrastructure README](infra/README.md) 詳盡故障排除說明，包括子網域名稱衝突、手動 Azure 入口網站部署步驟及模型設定指導。 -**確認部署成功：** +**驗證部署成功：** -**Bash:** +**Bash 指令：** ```bash -cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等等。 +cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 ``` -**PowerShell:** +**PowerShell 指令：** ```powershell -Get-Content ..\.env # 應顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 +Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等等。 ``` -> **注意：** `azd up` 命令會自動生成 `.env` 檔案。若要之後更新，可手動編輯 `.env` 檔案或重新執行： +> **注意：** `azd up` 會自動生成 `.env` 檔。若日後需更新，您可手動編輯 `.env` 或重新生成： > -> **Bash:** +> **Bash 指令：** > ```bash > cd .. > bash .azd-env.sh > ``` > -> **PowerShell:** +> **PowerShell 指令：** > ```powershell > cd .. > .\.azd-env.ps1 @@ -184,139 +184,139 @@ Get-Content ..\.env # 應顯示 AZURE_OPENAI_ENDPOINT、API_KEY 等。 ## 在本機執行應用程式 -**確認部署狀態：** +**驗證部署：** -確保 `.env` 檔案存在根目錄且含有 Azure 認證。於模組目錄（`01-introduction/`）執行： +確保根目錄存在含 Azure 憑證的 `.env` 檔。於模組目錄（`01-introduction/`）執行： -**Bash:** +**Bash 指令：** ```bash cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` -**PowerShell:** +**PowerShell 指令：** ```powershell Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` **啟動應用程式：** -**選項 1：使用 Spring Boot Dashboard（推薦給 VS Code 使用者）** +**選項 1：使用 Spring Boot Dashboard（建議 VS Code 使用者）** -開發容器內含 Spring Boot Dashboard 擴充套件，提供管理所有 Spring Boot 應用的視覺介面。可在 VS Code 的側邊欄活動列找到（尋找 Spring Boot 圖示）。 +開發容器內含 Spring Boot Dashboard 擴充套件，提供視覺化介面管理所有 Spring Boot 應用程式。可在 VS Code 左側活動列找到（尋找 Spring Boot 圖示）。 -在 Spring Boot Dashboard，你可以： -- 查看工作區內所有 Spring Boot 應用程式 -- 一鍵啟動／停止應用程式 -- 實時查看應用日誌 -- 監控應用狀態 +透過 Spring Boot Dashboard，您可以： +- 查看工作區內所有可用的 Spring Boot 應用程式 +- 一鍵啟動/停止應用程式 +- 實時查看應用程式日誌 +- 監控應用程式狀態 -只要點選「introduction」旁的播放按鈕即可啟用此模組，或一次啟動所有模組。 +只要點擊「introduction」旁的播放按鈕即可啟動本模組，或同時啟動所有模組。 Spring Boot Dashboard -*VS Code 中的 Spring Boot Dashboard — 從同一位置啟動、停止及監控所有模組* +*VS Code 中的 Spring Boot Dashboard — 從同一介面啟動、停止與監控所有模組* -**選項 2：使用 shell 腳本** +**選項 2：使用 shell 指令腳本** -啟動所有網頁應用（模組 01-04）： +啟動所有 Web 應用（模組 01-04）： -**Bash:** +**Bash 指令：** ```bash -cd .. # 從根目錄 +cd .. # 從根目錄開始 ./start-all.sh ``` -**PowerShell:** +**PowerShell 指令：** ```powershell -cd .. # 從根目錄 +cd .. # 從根目錄開始 .\start-all.ps1 ``` -或者只啟動本模組： +或僅啟動本模組： -**Bash:** +**Bash 指令：** ```bash cd 01-introduction ./start.sh ``` -**PowerShell:** +**PowerShell 指令：** ```powershell cd 01-introduction .\start.ps1 ``` -這兩個腳本會自動從根目錄 `.env` 載入環境變數，且如果不存在 JAR 檔會先編譯。 +兩個腳本會自動從根目錄 `.env` 讀取環境變數，且若 JAR 檔不存在會進行編譯。 -> **注意：** 若你偏好先手動編譯所有模組，再啟動： +> **注意：** 若您想在啟動前手動建置所有模組： > -> **Bash:** +> **Bash 指令：** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` > -> **PowerShell:** +> **PowerShell 指令：** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -於瀏覽器開啟 http://localhost:8080 。 +開啟瀏覽器並造訪 http://localhost:8080 。 -**停止應用程式：** +**停止應用：** -**Bash:** +**Bash 指令：** ```bash -./stop.sh # 僅此模組 -# 或者 +./stop.sh # 僅限此模組 +# 或 cd .. && ./stop-all.sh # 所有模組 ``` -**PowerShell:** +**PowerShell 指令：** ```powershell -.\stop.ps1 # 僅限此模組 +.\stop.ps1 # 僅此模組 # 或 cd ..; .\stop-all.ps1 # 所有模組 ``` ## 使用應用程式 -應用程式呈現一個網頁介面，左右並排兩種不同聊天實作。 +應用程式提供 Web 介面，並排展示兩種聊天實作。 -Application Home Screen +應用程式主畫面 -*主畫面展示簡易聊天（無狀態）與對話聊天（有狀態）兩種選項* +*儀錶板呈現「簡單聊天（無狀態）」和「對話式聊天（有狀態）」選項* ### 無狀態聊天（左側面板） -先試試看這個。問「我的名字是約翰」，緊接著問「我的名字是什麼？」模型不會記得，因為每則訊息都是獨立的。這展現了基礎語言模型整合的核心問題 — 無對話上下文。 +先試試這個。輸入「我的名字是 John」，接著立刻問「我叫什麼名字？」模型不會記住，因每則訊息獨立。這說明基本語言模型整合的核心問題 — 無上下文。 -Stateless Chat Demo +無狀態聊天示範 -*AI 不會記得你上一句話中的名字* +*AI 不會記得您剛剛告訴它的名字* ### 有狀態聊天（右側面板） -現在在這裡試同樣流程。問「我的名字是約翰」，再問「我的名字是什麼？」這次模型會記得。關鍵是 MessageWindowChatMemory — 它維持對話歷史且每次請求都帶上。這就是生產環境對話式 AI 的工作方式。 +現在在這裡試同樣的流程。輸入「我的名字是 John」，再問「我叫什麼名字？」這次它會記住。關鍵是 MessageWindowChatMemory — 它維持會話歷史並包含在每次請求中。這是生產級對話 AI 的運作方式。 -Stateful Chat Demo +有狀態聊天示範 -*AI 記得對話早先提過的名字* +*AI 會記得您先前對話中的名字* -兩個面板都使用相同的 GPT-5.2 模型，唯一不同就是記憶。這讓你清楚了解記憶為應用程式帶來的價值及其對實務需求的必要性。 +兩個面板皆使用相同 GPT-5.2 模型。唯一不同是記憶。這清楚呈現記憶為應用程式帶來的功能及為何真實應用必須。 -## 下一步 +## 後續步驟 -**下一模組：** [02-prompt-engineering - GPT-5.2 的提示工程](../02-prompt-engineering/README.md) +**下一模組：** [02-prompt-engineering - 使用 GPT-5.2 的提示工程學](../02-prompt-engineering/README.md) --- -**導航：** [← 上一節：模組 00 - 快速入門](../00-quick-start/README.md) | [回主頁](../README.md) | [下一節：模組 02 - 提示工程 →](../02-prompt-engineering/README.md) +**導覽：** [← 返回主頁](../README.md) | [下一步：模組 02 - 提示工程 →](../02-prompt-engineering/README.md) --- -**免責聲明**： -本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們力求準確，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的原文版本應視為權威來源。對於關鍵資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤譯承擔責任。 +**免責聲明**： +此文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力追求準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們不對因使用此翻譯所產生的任何誤解或誤譯承擔責任。 \ No newline at end of file diff --git a/translations/zh-TW/02-prompt-engineering/README.md b/translations/zh-TW/02-prompt-engineering/README.md index 0ed015f74..c236d6f7a 100644 --- a/translations/zh-TW/02-prompt-engineering/README.md +++ b/translations/zh-TW/02-prompt-engineering/README.md @@ -1,101 +1,101 @@ -# Module 02: 使用 GPT-5.2 進行提示工程 - -## 內容目錄 - -- [影片導覽](../../../02-prompt-engineering) -- [您將學到什麼](../../../02-prompt-engineering) -- [先決條件](../../../02-prompt-engineering) -- [了解提示工程](../../../02-prompt-engineering) -- [提示工程基礎](../../../02-prompt-engineering) - - [零次提示](../../../02-prompt-engineering) - - [少量示例提示](../../../02-prompt-engineering) - - [思維鏈](../../../02-prompt-engineering) - - [角色導向提示](../../../02-prompt-engineering) - - [提示模板](../../../02-prompt-engineering) -- [進階模式](../../../02-prompt-engineering) -- [執行應用程式](../../../02-prompt-engineering) -- [應用程式截圖](../../../02-prompt-engineering) -- [探索模式](../../../02-prompt-engineering) - - [低熱忱 vs 高熱忱](../../../02-prompt-engineering) - - [任務執行（工具前言）](../../../02-prompt-engineering) - - [自我反思程式碼](../../../02-prompt-engineering) - - [結構化分析](../../../02-prompt-engineering) - - [多回合聊天](../../../02-prompt-engineering) - - [逐步推理](../../../02-prompt-engineering) - - [受限輸出](../../../02-prompt-engineering) -- [您真正學到的是什麼](../../../02-prompt-engineering) -- [下一步](../../../02-prompt-engineering) +# 模組 02：使用 GPT-5.2 的提示工程 + +## 目錄 + +- [影片導覽](#影片導覽) +- [你將學到的內容](#你將學到的內容) +- [先決條件](#先決條件) +- [理解提示工程](#理解提示工程) +- [提示工程基礎](#提示工程基礎) + - [零次提示 (Zero-Shot Prompting)](#零次提示-zero-shot-prompting) + - [少量示例提示 (Few-Shot Prompting)](#少量示例提示-few-shot-prompting) + - [思維鏈 (Chain of Thought)](#思維鏈-chain-of-thought) + - [角色基礎提示 (Role-Based Prompting)](#角色基礎提示-role-based-prompting) + - [提示範本 (Prompt Templates)](#提示範本-prompt-templates) +- [進階模式](#進階模式) +- [執行應用程式](#執行應用程式) +- [應用程式螢幕截圖](#應用程式截圖) +- [探索提示模式](#探索各種模式) + - [低 vs 高積極度](#低與高積極度) + - [任務執行（工具前導語）](#任務執行（工具前置詞）) + - [自我反省程式碼](#自省式程式碼) + - [結構化分析](#結構化分析) + - [多輪聊天](#多輪對話) + - [逐步推理](#逐步推理) + - [受限輸出](#受限輸出) +- [你真正學到的是什麼](#您真正學到的是什麼) +- [下一步](#下一步) ## 影片導覽 -觀看此現場講解影片，了解如何開始本模組： +觀看此現場會議，說明如何開始本模組： -與 LangChain4j 的提示工程 - 現場講解 +使用 LangChain4j 的提示工程 - 現場會議 -## 您將學到什麼 +## 你將學到的內容 -下圖提供了本模組關鍵主題與技能的概覽——從提示優化技術到您將使用的逐步工作流程。 +下圖概述了本模組中你將發展的關鍵主題和技能——從提示優化技術到你將遵循的逐步工作流程。 -您將學到什麼 +你將學到的內容 -在之前的模組中，您探索了與 GitHub 模型的基本 LangChain4j 互動，並見識了記憶如何透過 Azure OpenAI 啟用對話式 AI。現在，我們將專注於您如何提問——也就是提示本身——利用 Azure OpenAI 的 GPT-5.2。您設計的提示結構會大幅影響回應品質。我們從提示基本技巧回顧開始，接著探討八種進階模式，充分利用 GPT-5.2 的能力。 +在前一個模組中，你已瞭解記憶如何透過 Azure OpenAI 促成對話式 AI。現在，我們將專注於你如何提出問題——也就是提示本身——使用 Azure OpenAI 的 GPT-5.2。你結構提示的方式將大幅影響你獲得的回應品質。我們先回顧基本提示技術，接著進入八種利用 GPT-5.2 功能的進階模式。 -我們使用 GPT-5.2 是因為它引入了推理控制——您可以告訴模型在回答前要思考多少。這讓不同的提示策略更加明顯，幫助您了解何時該使用每種方法。此外，與 GitHub 模型相比，Azure 對 GPT-5.2 的速率限制較少，我們也將因此受益。 +我們使用 GPT-5.2 是因為它引入了推理控制——你可以告訴模型在回答前應該思考多少。這使不同提示策略變得更加明顯，也幫助你理解何時使用每種方法。 ## 先決條件 -- 完成模組 01（已部署 Azure OpenAI 資源） -- 根目錄下有 `.env` 檔案，包含 Azure 憑證（由模組 01 中的 `azd up` 產生） +- 已完成模組 01（部署好 Azure OpenAI 資源） +- 專案根目錄下的 `.env` 檔案包含 Azure 認證（在模組 01 透過 `azd up` 建立） -> **注意：** 如果尚未完成模組 01，請先依照那裡的部署說明操作。 +> **注意：** 如果你尚未完成模組 01，請先遵循那裡的部署指示。 -## 了解提示工程 +## 理解提示工程 -提示工程的核心，是模糊指令與精確指令之間的差異，以下圖說明。 +提示工程的核心，是模糊指示與精確指示的差異，正如下方比較所示。 什麼是提示工程？ -提示工程就是設計輸入文字以穩定獲得所需結果。它不只是問問題——而是構建請求，讓模型能精準了解您要什麼，並該怎麼回覆。 +提示工程就是設計輸入文字，使你能穩定得到所需結果。它不只是問問題——而是結構化請求，讓模型確切理解你的需求與如何交付。 -想像您在給同事指示。「修復錯誤」很模糊。「在 UserService.java 第 45 行針對 null 指標例外新增空值檢查」則很具體。語言模型的運作也是如此——具體與結構同樣重要。 +可以想像成給同事指示。「修復錯誤」很模糊；「在 UserService.java 第 45 行加上 null 檢查修復空指標異常」就是具體。語言模型也是如此——精確與結構非常重要。 -下圖展示了 LangChain4j 如何融入這個流程——透過 SystemMessage 和 UserMessage 建構塊將您的提示模式與模型連接起來。 +下圖說明 LangChain4j 適合如何使用——透過 SystemMessage 與 UserMessage 建構塊將提示模式連上模型。 -LangChain4j 如何融入 +LangChain4j 的適用方式 -LangChain4j 提供基礎架構——模型連接、記憶體及訊息類型，而提示模式則是您透過該架構傳送的精心結構化文字。關鍵建構元是 `SystemMessage`（設定 AI 行為與角色）與 `UserMessage`（承載您的實際請求）。 +LangChain4j 提供基礎架構——模型連接、記憶體與訊息類型——而提示模式是你透過該架構傳遞的精心結構化文字。關鍵建構塊是 `SystemMessage`（設定 AI 行為與角色）與 `UserMessage`（攜帶你實際的請求）。 ## 提示工程基礎 -以下五種核心技巧構成有效提示工程的基石。每一種都涵蓋您與語言模型溝通的不同面向。 +以下五種核心技術構成有效提示工程的基礎。每種技術處理你與語言模型溝通的不同面向。 -五種提示工程模式概覽 +五種提示工程模式總覽 -在深入本模組的進階模式前，讓我們回顧五個基礎提示技巧。這些是每個提示工程師都應了解的基礎。若您已完成 [快速入門模組](../00-quick-start/README.md#2-prompt-patterns)，便見過它們的實作——以下為其背後的概念框架。 +在深入本模組的進階模式前，先回顧五個基礎提示技術。這些是每位提示工程師應了解的建構塊。 -### 零次提示 +### 零次提示 (Zero-Shot Prompting) -最簡單的方式：直接給模型指令，沒有示例。模型完全依靠訓練來理解與執行任務。適合行為明確的簡單請求。 +最簡單的方法：給模型直接指示，無需範例。模型完全依靠訓練來理解和執行任務。適用於預期行為清楚的直接請求。 零次提示 -*沒有示例的直接指令——模型僅從指令本身推斷任務* +*不附範例之直接指示——模型僅用指示推斷任務* ```java String prompt = "Classify this sentiment: 'I absolutely loved the movie!'"; String response = model.chat(prompt); -// 回應:「正面」 +// 回應："正面" ``` - -**適用時機：** 簡單分類、直接提問、翻譯，或模型能在無額外指引下處理的任何任務。 -### 少量示例提示 +**使用時機：** 簡單分類、直接提問、翻譯，或模型能在無其他引導下執行的任何任務。 -提供示例，示範您希望模型遵循的模式。模型學習示例的輸入輸出格式，並應用於新輸入。此法大幅提升格式或行為不明顯任務的一致性。 +### 少量示例提示 (Few-Shot Prompting) + +提供示例以展示你希望模型遵守的模式。模型從示例中學習期望輸入輸出格式，並套用到新輸入。大幅提升格式或行為模糊任務的一致性。 少量示例提示 -*從示例學習——模型辨識模式，且套用於新輸入* +*從示例學習——模型辨識模式並套用於新輸入* ```java String prompt = """ @@ -111,16 +111,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**適用時機：** 客製分類、一致格式化、領域特定任務，或零次提示結果不一致時。 -### 思維鏈 +**使用時機：** 自訂分類、一致格式、領域專屬任務，或零次提示結果不穩定時。 + +### 思維鏈 (Chain of Thought) -要求模型逐步展現推理過程。模型不直接跳到答案，而是明確拆解問題並逐步處理。此法提高數學、邏輯與多步推理任務的準確性。 +請模型逐步展示推理。模型不直接跳到答案，而是拆解問題並逐部分明確處理。提升數學、邏輯和多步推理任務的準確度。 思維鏈提示 -*逐步推理——將複雜問題拆成清楚邏輯步驟* +*逐步推理——將複雜問題拆成明確邏輯步驟* ```java String prompt = """ @@ -130,18 +130,18 @@ String prompt = """ Let's solve this step-by-step: """; String response = model.chat(prompt); -// 模型顯示：15 - 8 = 7，然後 7 + 12 = 19 顆蘋果 +// 模型顯示：15 - 8 = 7，接著 7 + 12 = 19 顆蘋果 ``` - -**適用時機：** 數學題、邏輯謎題、除錯，或者任何展現推理過程能提升準確性與可信度的任務。 -### 角色導向提示 +**使用時機：** 數學問題、邏輯謎題、除錯，或任何顯示推理過程可提升準確性與信任的任務。 + +### 角色基礎提示 (Role-Based Prompting) -在提問前設定 AI 的角色或身份。這提供上下文，塑造回答的語氣、深度與焦點。例如「軟體架構師」與「初級開發者」或「資安審計員」會給不同建議。 +在提問前設定 AI 的角色或身份。這提供上下文，塑造回應的語氣、深度與焦點。「軟體架構師」給的建議與「初級開發者」或「安全稽核員」不同。 -角色導向提示 +角色基礎提示 -*設定上下文與身份——同一問題因角色不同而得到不同回答* +*設定上下文與角色——相同問題根據指定角色得到不同回應* ```java String prompt = """ @@ -156,16 +156,16 @@ String prompt = """ """; String response = model.chat(prompt); ``` - -**適用時機：** 程式碼審查、教學、領域特定分析，或您需要依據特定專業層次或觀點量身訂做回應時。 -### 提示模板 +**使用時機：** 程式碼審查、教學、領域專業分析，或需要針對特定專業層級或視角量身調整回應時。 -建立可重用提示，含變數占位符。無需每次重寫提示，只要定義模板並填入不同值即可。LangChain4j 的 `PromptTemplate` 類以 `{{variable}}` 語法協助此工作。 +### 提示範本 (Prompt Templates) -提示模板 +建立可重用的提示，內含變數佔位符。不是每次都寫新提示，定義範本後填入不同值即可。LangChain4j 的 `PromptTemplate` 類別用 `{{variable}}` 語法輕鬆完成。 -*含變數占位的可重用提示——一個模板，多次使用* +提示範本 + +*帶變數佔位符的可重複使用提示——一個範本，多種用途* ```java PromptTemplate template = PromptTemplate.from( @@ -179,28 +179,28 @@ Prompt prompt = template.apply(Map.of( String response = model.chat(prompt.text()); ``` - -**適用時機：** 多次查詢不同輸入、批次處理、建立可重用 AI 工作流程，或任何提示結構固定但資料會變的場景。 + +**使用時機：** 多次查詢不同輸入、批次處理、建立可重複使用的 AI 工作流程，或任何提示結構固定但資料變動的情況。 --- -這五種基礎技巧為您提供大部分提示任務的強大工具組。本模組餘下內容將基於此，融入 GPT-5.2 的推理控制、自我評估及結構化輸出功能，展開 **八種進階模式**。 +這五項基礎提供你大部分提示任務的強大工具組。本模組其餘內容建立在此基礎上，介紹利用 GPT-5.2 的推理控制、自我評估與結構化輸出的 八種進階模式。 ## 進階模式 -基礎技巧說明完畢，我們轉向本模組獨有的八種進階模式。不是所有問題都適用相同方法。有些問題需迅速回答，有些需要深入思考。有些需展現明確推理，有些只要結果。以下每種模式都為不同情境優化，而 GPT-5.2 的推理控制更突顯出差異。 +基礎說明後，接著介紹本模組獨特的八種進階模式。不同問題不需相同方法。有些問題需求快速回答，有些需要深度思考。有些需要顯示推理，有些只要結果。以下每種模式都為不同情境優化——GPT-5.2 的推理控制令差異更為顯著。 八種提示工程模式 -*八種提示工程模式及其使用情境概覽* +八種提示工程模式及其使用情境總覽 -GPT-5.2 為這些模式增添一個新維度：*推理控制*。下面滑桿顯示您如何調整模型的思考深度——從快速直接的答案到深入徹底的分析。 +GPT-5.2 在這些模式中加入了另一維度：推理控制。下方滑桿展示你可如何調整模型的思考深度——從快速直接答案到深度徹底分析。 -GPT-5.2 推理控制 +使用 GPT-5.2 的推理控制 -*GPT-5.2 的推理控制讓您指定模型思考量——從迅速直接回答到深入探索皆可* +*GPT-5.2 推理控制讓你指定模型思考量——從快速直接答覆到深入探索* -**低熱忱（快速且聚焦）** - 適合簡單問題，需快速且直接答案。模型進行最少推理——最多兩步。用於計算、查詢或直接問題。 +**低積極度 (快速且聚焦)** — 適合想要快速直接回答的簡單問題。模型進行最少推理，最多兩步。用於計算、查詢或簡單問題。 ```java String prompt = """ @@ -218,13 +218,13 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> 💡 **用 GitHub Copilot 探索：** 開啟 [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) 並詢問： -> - 「低熱忱與高熱忱提示模式有何差異？」 -> - 「提示中的 XML 標籤如何幫助結構化 AI 回答？」 -> - 「什麼情況應使用自我反思模式，什麼情況用直接指令？」 -**高熱忱（深入且徹底）** - 適合複雜問題，需全面分析。模型徹底探索並展示詳盡推理。用於系統設計、架構決策或複雜研究。 +> 💡 **用 GitHub Copilot 探索：** 打開 [`Gpt5PromptService.java`](../../../02-prompt-engineering/src/main/java/com/example/langchain4j/prompts/service/Gpt5PromptService.java) 並詢問： +> - 「低積極度和高積極度提示模式差別是什麼？」 +> - 「提示中的 XML 標籤如何幫助構建 AI 回應？」 +> - 「什麼時候該用自我反思模式或直接指示？」 + +**高積極度 (深度且徹底)** — 適合需要全面分析的複雜問題。模型徹底探索並展示詳細推理。用於系統設計、架構決策或複雜研究。 ```java String prompt = """ @@ -237,8 +237,8 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -**任務執行（逐步進度）** - 適用於多步工作流程。模型提供事先計劃，工作時口述每步，最後再彙整。用於遷移、實作或任意多步程序。 + +**任務執行（逐步進行）** — 用於多步工作流程。模型提供先前計畫，一邊執行一邊敘述每步，最後總結。用於遷移、實作或任何多步程序。 ```java String prompt = """ @@ -275,21 +275,21 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -思維鏈提示明確要求模型展現推理流程，提升複雜任務精確度。逐步拆解幫助人類與 AI 了解邏輯。 -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試：** 詢問此模式： -> - 「我怎麼為長時間執行操作調整任務執行模式？」 -> - 「生產環境應用中，工具前言該如何結構化？」 -> - 「如何在 UI 中擷取並顯示中間進度更新？」 +思維鏈提示明確要求模型展示推理過程，提升複雜任務的準確度。逐步拆解幫助人類與 AI 理解邏輯。 + +> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試：** 詢問此模式： +> - 「如何調整任務執行模式處理長時間操作？」 +> - 「生產環境應用中，工具前導語結構最佳實踐是什麼？」 +> - 「如何捕捉並在 UI 顯示中間進度更新？」 -下圖描繪此 計劃 → 執行 → 彙整 工作流程。 +下圖說明此「規劃 → 執行 → 總結」流程。 任務執行模式 -*多步任務的計劃 → 執行 → 彙整工作流程* +*多步任務的 計劃 → 執行 → 總結 工作流程* -**自我反思程式碼** - 用於生成生產級程式碼。模型產生符合生產標準且具備適當錯誤處理的程式碼。建置新功能或服務時使用。 +自我反省程式碼 — 用來產生生產品質程式。模型產出符合生產標準且含完善錯誤處理的程式碼。用於開發新功能或服務。 ```java String prompt = """ @@ -299,14 +299,14 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -下圖展示此反覆改進迴圈——產生、評估、找出弱點並改良，直至滿足生產標準。 + +下圖展示此反覆改進循環——產生、評估、找出弱點，修正直到程式碼符合法規。 自我反思循環 -*反覆改進迴圈——產生、評估、識別問題、改良、重複* +*反覆改進循環——產生、評估、找問題、改進、重複* -**結構化分析** - 用於一致性評價。模型依據固定框架（正確性、慣例、效能、安全性、維護性）審查程式碼。適用程式碼審查或品質評估。 +結構化分析 — 用於一致性評估。模型依固定框架（正確性、實務、效能、安全性、可維護性）審查程式碼。用於程式碼審查或品質檢核。 ```java String prompt = """ @@ -353,19 +353,19 @@ String prompt = """ String response = chatModel.chat(prompt); ``` - -> **🤖 用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試：** 詢問結構化分析： -> - 「如何客製不同類型程式碼審查的分析框架？」 -> - 「程式化解析並利用結構化輸出的最佳作法？」 -> - 「如何確保不同審查回合間的嚴重性等級一致？」 -下圖展示此結構化框架如何將程式碼審查組織成一致類別並附嚴重程度。 +> **🤖 使用 [GitHub Copilot](https://github.com/features/copilot) Chat 試試：** 詢問結構化分析： +> - 「如何為不同類型程式碼審查自訂分析框架？」 +> - 「以程式方式解析並採取結構化輸出最佳方法是？」 +> - 「如何確保不同審查會話中嚴重程度一致？」 + +下圖展示此結構化框架將程式碼評論組織成一致類別並標示嚴重性等級。 結構化分析模式 -*一致程式碼審查的框架與嚴重性分類* +有嚴重性等級的程式碼審查一致性框架 -**多回合聊天** - 適用需要上下文的對話。模型記住先前訊息並在基礎上回應。用於互動式協助會話或複雜問答。 +多輪聊天 — 用於需要上下文的對話。模型記住前面的訊息並以之為基礎展開。用於互動式支援或複雜問答。 ```java ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10); @@ -378,13 +378,14 @@ memory.add(UserMessage.from("Show me an example")); AiMessage aiMessage2 = chatModel.chat(memory.messages()).aiMessage(); memory.add(aiMessage2); ``` - -下圖視覺化對話上下文如何累積以及它與模型代幣限制的關係。 + +下圖可視化每輪如何累積對話上下文，以及如何影響模型的 token 限制。 上下文記憶 -*多回合對話中上下文如何累積，直至達到代幣限制* -**逐步推理** - 適用於需要明確邏輯的問題。模型對每個步驟進行明確推理。用於數學題、邏輯謎題，或當你需要理解思考過程時。 +*多輪累積對話上下文直到接近 token 限制* + +逐步推理 — 適用需可視邏輯的問題。模型展示每步具體推理。用於數學問題、邏輯謎題或你要理解思考過程時。 ```java String prompt = """ @@ -398,13 +399,12 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下圖展示模型如何將問題拆解成明確、有編號的邏輯步驟。 +下圖說明模型如何將問題拆成清楚編號的邏輯步驟。 -Step-by-Step Pattern +逐步推理模式 +將問題拆解為明確的邏輯步驟 -*將問題拆解為明確的邏輯步驟* - -**受限輸出** - 適用於有特定格式要求的回應。模型嚴格遵守格式與長度規則。用於摘要或需要精確輸出結構的情況。 +受限輸出 - 用於具有特定格式需求的回應。模型嚴格遵守格式和長度規則。適用於摘要或需要精確輸出結構的情況。 ```java String prompt = """ @@ -420,9 +420,9 @@ String prompt = """ String response = chatModel.chat(prompt); ``` -下圖顯示如何藉由約束，讓模型產出嚴格符合格式與長度要求的內容。 +下圖顯示限制條件如何引導模型產出嚴格符合您格式和長度需求的輸出。 -Constrained Output Pattern +受限輸出範例 *強制特定格式、長度及結構要求* @@ -430,179 +430,179 @@ String response = chatModel.chat(prompt); **驗證部署：** -確保根目錄有 `.env` 檔案，並包含 Azure 憑證（在模組 01 中建立）。請在模組資料夾 (`02-prompt-engineering/`) 執行： +確保根目錄存在 `.env` 檔案，內含 Azure 憑證（在模組 01 中建立）。請從模組目錄 (`02-prompt-engineering/`) 執行： -**Bash:** +**Bash:** ```bash cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` - -**PowerShell:** + +**PowerShell:** ```powershell Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` - + **啟動應用程式：** -> **注意：** 如果你已從根目錄執行過 `./start-all.sh` （如模組 01 所述），這個模組已在 8083 埠執行。可跳過以下啟動指令，直接訪問 http://localhost:8083。 +> **注意：** 若您已經在根目錄使用 `./start-all.sh` 啟動所有應用程式（如模組 01 所述），則此模組已在 8083 埠上運行。您可以跳過以下啟動指令，直接開啟 http://localhost:8083。 -**選項 1：使用 Spring Boot Dashboard（建議 VS Code 使用者）** +**選項 1：使用 Spring Boot 控制台（建議 VS Code 使用者）** -開發容器包含 Spring Boot Dashboard 擴充功能，提供視覺化介面管理所有 Spring Boot 應用程式。可在 VS Code 左邊活動欄找到 Spring Boot 圖示。 +開發容器中包含 Spring Boot 控制台擴充套件，提供管理所有 Spring Boot 應用程式的視覺介面。它位於 VS Code 左側活動列（尋找 Spring Boot 圖示）。 -在 Spring Boot Dashboard 中，你可以： -- 查看工作區所有可用的 Spring Boot 應用程式 -- 一鍵啟動或停止應用程式 -- 實時查看應用日誌 -- 監控應用狀態 +透過 Spring Boot 控制台，您可以： +- 查看工作區內所有可用的 Spring Boot 應用程式 +- 一鍵啟動/停止應用程式 +- 實時檢視應用日誌 +- 監控應用程式狀態 -只需點擊 "prompt-engineering" 旁的播放按鈕，即可啟動此模組，或同時啟動所有模組。 +只要點擊「prompt-engineering」旁的播放鈕即可啟動此模組，或一併啟動所有模組。 -Spring Boot Dashboard +Spring Boot 控制台 -*VS Code 中的 Spring Boot Dashboard — 從一處啟動、停止與監控所有模組* +*VS Code 中的 Spring Boot 控制台 — 從一處啟動、停止並監控所有模組* **選項 2：使用 shell 腳本** -啟動所有網頁應用（模組 01-04）： +啟動所有網頁應用程式（模組 01-04）： -**Bash:** +**Bash:** ```bash cd .. # 從根目錄開始 ./start-all.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd .. # 從根目錄 .\start-all.ps1 ``` - -或只啟動此模組： -**Bash:** +或者只啟動此模組： + +**Bash:** ```bash cd 02-prompt-engineering ./start.sh ``` - -**PowerShell:** + +**PowerShell:** ```powershell cd 02-prompt-engineering .\start.ps1 ``` - -兩個腳本會自動從根目錄的 `.env` 載入環境變數，且如不存在 JAR 檔會自動編譯。 -> **注意：** 若你偏好先手動編譯所有模組，再啟動： -> -> **Bash:** +兩個腳本均會自動從根目錄的 `.env` 檔案載入環境變數，且若 JAR 檔不存在會自動建立。 + +> **注意：** 若您想先手動編譯所有模組再啟動： +> +> **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> -> **PowerShell:** + +> **PowerShell:** > ```powershell > cd .. # Go to root directory > mvn clean package -DskipTests > ``` - -以瀏覽器開啟 http://localhost:8083 。 -**停止：** +在瀏覽器開啟 http://localhost:8083 。 + +**停止應用程式：** -**Bash:** +**Bash:** ```bash ./stop.sh # 僅此模組 -# 或者 +# 或 cd .. && ./stop-all.sh # 所有模組 ``` - -**PowerShell:** + +**PowerShell:** ```powershell .\stop.ps1 # 僅此模組 # 或 cd ..; .\stop-all.ps1 # 所有模組 ``` - -## 應用截圖 -這是 prompt engineering 模組的主介面，能讓你並排實驗所有八種模式。 +## 應用程式截圖 + +這是 prompt engineering 模組的主介面，您可以並排測試所有八種範例。 -Dashboard Home +主控台首頁 -*主控台顯示全部 8 種 prompt engineering 模式及其特性與適用情境* +*主控台展示所有 8 種提示工程模式及其特性和使用案例* ## 探索各種模式 -網頁介面允許你嘗試不同提示策略。每個模式解決不同問題—嘗試看看何時適合使用哪種方法。 +網頁介面讓您嘗試不同提示策略。各模式解決不同問題 — 嘗試看看何時哪種方法最適用。 -> **注意：串流與非串流** — 每個模式頁面有兩個按鈕：**🔴 串流回應（即時）** 和 **非串流**。串流採用 Server-Sent Events (SSE)，在模型生成 token 時即時顯示，讓你立即看到進度。非串流則會等待整段回應完成後才顯示。對於需要深度推理的提示（如 高渴望、自我反思代碼），非串流可能非常耗時，可能需要數分鐘且無任何反饋。**試驗複雜提示時請使用串流，讓你看到模型運作，避免誤認請求逾時。** -> -> **注意：瀏覽器需求** — 串流功能使用 Fetch Streams API（`response.body.getReader()`），需完整瀏覽器（Chrome、Edge、Firefox、Safari）。不支援 VS Code 內建的 Simple Browser，因其 WebView 不支援 ReadableStream API。使用 Simple Browser 時，非串流按鈕正常，只有串流按鈕受限。建議用外部瀏覽器開啟 `http://localhost:8083` 以獲得完整體驗。 +> **注意：串流與非串流** — 每個模式頁面都提供兩個按鈕：**🔴 串流回應（即時）** 和 非串流 選項。串流使用 Server-Sent Events (SSE)，將模型生成的 token 及時呈現，讓您立即看到進度。非串流則是等待整個回應完成才顯示。對於引發深度推理的提示（例如高積極度、高自省程式碼等），非串流呼叫可能非常漫長 — 甚至數分鐘，且無明顯回饋。**嘗試複雜提示時建議使用串流，能即時看到模型運作，避免誤以為請求逾時。** +> +> **注意：瀏覽器需求** — 串流功能使用 Fetch Streams API（`response.body.getReader()`），需要完整瀏覽器（Chrome、Edge、Firefox、Safari）。VS Code 內建的簡易瀏覽器不支援 ReadableStream API，故無法使用串流功能。若使用簡易瀏覽器，非串流按鈕仍可正常使用，僅串流按鈕受限。請於外部瀏覽器開啟 `http://localhost:8083` 以獲得完整體驗。 -### 低渴望 vs 高渴望 +### 低與高積極度 -用低渴望問簡單問題，例如「200 的 15% 是多少？」你會即時收到直接答案。再用高渴望問複雜問題，例如「設計高流量 API 的快取策略」。點擊 **🔴 串流回應（即時）**，觀看模型逐字展現詳細推理。同一模型，同一問題結構，唯提示決定思考深度。 +以低積極度詢問簡單問題，例如「200 的 15% 是多少？」會立即得到直接答案。換成用高積極度詢問「設計高流量 API 的快取策略」，點擊 **🔴 串流回應（即時）**，您將看到模型詳細的逐字推理。相同模型、相同問題結構，提示決定模型要思考多少。 -### 任務執行（工具前置指令） +### 任務執行（工具前置詞） -多步驟工作流程適合先規劃並敘述進程。模型會列出將採取的步驟，逐步敘述，最後彙整結果。 +多步工作流程受益於預先規劃及進度說明。模型會概述要執行的內容，逐步說明，再總結結果。 -### 自我反思思考代碼 +### 自省式程式碼 -試試「建立電子郵件驗證服務」。模型不只是生成代碼並停下，而是產出、對照品質標準評估、找出不足並改進。你會看到它反覆迭代直到代碼符合生產標準。 +試著輸入「建立電子郵件驗證服務」。模型不會只生成程式碼就停，而是生成、根據品質標準評估、找出弱點並改進。您會看到其重複迭代直到程式碼達到生產標準。 ### 結構化分析 -程式碼審查需要一致評估框架。模型會用固定分類（正確性、慣例、效能、安全）進行分析，並設置嚴重度等級。 +程式碼檢視需要一致的評估架構。模型使用固定分類（正確性、實務、效能、安全）與嚴重度等級來分析程式碼。 ### 多輪對話 -問「什麼是 Spring Boot？」後立即追問「給我範例」。模型會記住前一問題，提供專門的 Spring Boot 範例。沒有記憶，第二題太模糊。 +先問「什麼是 Spring Boot？」，緊接著問「給我一個範例」。模型會記得前一問，給您專屬的 Spring Boot 範例。沒記憶功能的話，第二個問題會過於模糊。 ### 逐步推理 -選一道數學題，分別用逐步推理和低渴望嘗試。低渴望只給答案，快速但不透明。逐步推理顯示每個計算和決策過程。 +挑一個數學題，分別用逐步推理和低積極度嘗試。低積極度直接給解答 — 快速但不透明。逐步推理則展示每個計算和決策過程。 ### 受限輸出 -需要特定格式或字數，此模式強制嚴格遵守。試試用分點方式產生正好 100 字的摘要。 +需要特定格式或字數時，此模式強制嚴格遵守。試試產生剛好 100 字的條列式摘要。 -## 你真正學到的是什麼 +## 您真正學到的是什麼 -**推理努力決定一切** +推理努力決定一切 -GPT-5.2 讓你透過提示控制計算努力程度。低努力輸出快速且探索少。高努力意味模型花時間深度思考。你學會調整努力與任務複雜度匹配—別浪費時間在簡單問題，但也別急於複雜決策。 +GPT-5.2 讓您透過提示控制計算努力。低努力意即快速回應且探索少。高努力令模型花時間深度思考。您學會依任務複雜度調節努力 — 不浪費時間回答簡單問題，也不急於做複雜決策。 -**結構引導行為** +結構引導行為 -注意提示中的 XML 標籤？它們非裝飾用。模型比起自由文本，更容易遵循結構化指令。多步驟流程或複雜邏輯時，結構幫助模型追蹤目前狀態與接下來步驟。下圖拆解良好結構化的提示，說明 ``、``、``、`` 與 `` 如何將指令分門別類。 +注意提示中的 XML 標籤？它們非裝飾。模型較能可靠遵循結構化指令，而非自由文本。當需要多步程序或複雜邏輯時，結構有助模型追蹤進度和下一步。下圖拆解良好結構化提示，展示 ``, ``, ``, ``, `` 等標籤如何組織您的指令為清晰區塊。 -Prompt Structure +提示結構 -*具明確區段與 XML 式組織的良好結構化提示構造* +*良好結構化提示的組成，具清楚區塊與 XML 風格組織* -**透過自我評估提升品質** +自我評估帶來品質 -自我反思模式明確傳達品質標準。別只是希望模型「做對」，而是告訴它「對」的定義：正確邏輯、錯誤處理、效能、安全。模型能自評並改善輸出，讓程式碼生成從抽獎變為流程。 +自省模式透過明確化品質標準運作。您不再期望模型「做對」，而是告訴它「對」的意義為何：邏輯正確、錯誤處理、效能、安全。模型能自行評估輸出並改進。此法將程式碼生成從碰運氣變成流程。 -**上下文有限** +上下文有限 -多輪對話透過每次請求夾帶訊息歷史，但有限制—模型有最大 token 數。對話逐漸增長，需要策略保留相關上下文且不超過限制。本模組示範記憶運作，日後你會學會何時摘要、何時忘記、何時檢索。 +多輪對話通過隨請求攜帶訊息歷史達成。但有上限—每個模型有最大 Token 數。隨會話膨脹，您將學會策略保留相關上下文，避免超標。本模組示範記憶如何運作；後續您會學習何時摘要、何時遺忘，何時檢索。 ## 下一步 -**下一模組：** [03-rag - RAG（檢索增強生成）](../03-rag/README.md) +**下一模組：** [03-rag - RAG (檢索強化生成)](../03-rag/README.md) --- -**導航：** [← 上一章：模組 01 - 簡介](../01-introduction/README.md) | [回主目錄](../README.md) | [下一章：模組 03 - RAG →](../03-rag/README.md) +**導覽：** [← 上一頁：模組 01 - 介紹](../01-introduction/README.md) | [回主頁](../README.md) | [下一頁：模組 03 - RAG →](../03-rag/README.md) --- -**免責聲明**： -本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們盡力確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件之母語版本應視為權威來源。對於重要資訊，建議使用專業人工翻譯。我們對於因使用本翻譯而產生之任何誤解或誤譯不負任何責任。 +**免責聲明**： +此文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力追求準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們不對因使用此翻譯所產生的任何誤解或誤譯承擔責任。 \ No newline at end of file diff --git a/translations/zh-TW/03-rag/README.md b/translations/zh-TW/03-rag/README.md index 4dd6d95d5..21a95533d 100644 --- a/translations/zh-TW/03-rag/README.md +++ b/translations/zh-TW/03-rag/README.md @@ -2,143 +2,142 @@ ## 目錄 -- [影片導覽](../../../03-rag) -- [你將學到什麼](../../../03-rag) -- [先決條件](../../../03-rag) -- [理解 RAG](../../../03-rag) - - [本教程使用哪種 RAG 方法？](../../../03-rag) -- [工作原理](../../../03-rag) - - [文件處理](../../../03-rag) - - [建立嵌入](../../../03-rag) - - [語意搜尋](../../../03-rag) - - [答案生成](../../../03-rag) -- [執行應用程式](../../../03-rag) -- [使用應用程式](../../../03-rag) - - [上傳文件](../../../03-rag) - - [提問](../../../03-rag) - - [檢查來源參考](../../../03-rag) - - [嘗試不同問題](../../../03-rag) -- [關鍵概念](../../../03-rag) - - [切塊策略](../../../03-rag) - - [相似度分數](../../../03-rag) - - [記憶體儲存](../../../03-rag) - - [上下文視窗管理](../../../03-rag) -- [何時使用 RAG](../../../03-rag) -- [下一步](../../../03-rag) +- [影片導覽](#影片導覽) +- [您將學到什麼](#您將學到什麼) +- [先決條件](#先決條件) +- [理解 RAG](#理解-rag) + - [本教學使用哪種 RAG 方法？](#本教學使用哪種-rag-方法？) +- [運作原理](#運作原理) + - [文件處理](#文件處理) + - [建立向量表示](#建立向量表示) + - [語意搜尋](#語意搜尋) + - [答案生成](#答案生成) +- [執行應用程式](#執行應用程式) +- [使用應用程式](#使用應用程式) + - [上傳文件](#上傳文件) + - [提問](#提問) + - [檢查來源參考](#檢查來源引用) + - [嘗試不同問題](#試驗不同問題) +- [關鍵概念](#關鍵概念) + - [切塊策略](#拆分策略) + - [相似度分數](#相似度分數) + - [記憶體內存儲](#記憶體儲存) + - [上下文視窗管理](#上下文視窗管理) +- [何時 RAG 才重要](#何時選用-rag) +- [下一步](#後續步驟) ## 影片導覽 -觀看此現場講解，了解如何開始使用本模組： +觀看此現場說明，了解如何開始本模組： RAG with LangChain4j - Live Session -## 你將學到什麼 +## 您將學到什麼 -在前面的模組中，你學會了如何與 AI 進行對話並有效構建提示。但有一個根本限制：語言模型只知道它在訓練期間學到的知識。它無法回答關於你公司的政策、你的專案文件或其他未經訓練的信息。 +在前面的模組中，您學會了如何與 AI 對話並有效結構提示。但有一個根本限制：語言模型只能知道訓練期間學到的知識。它們無法回答關於您公司政策、專案文件或未受訓練的任何資訊的問題。 -RAG（檢索增強生成）解決了這個問題。與其嘗試教模型你的資訊（這既昂貴又不切實際），你給它能力去檢索你的文件。當有人提問時，系統會找到相關資訊並將其納入提示中。模型接著根據這些檢索到的上下文來回答。 +RAG（檢索增強生成）解決了這個問題。與其嘗試教模型您的資訊（既昂貴又不切實際），您給它能力去搜尋您的文件。當有人提問時，系統找到相關資訊並把它包含在提示中。模型然後根據檢索到的上下文回答。 -把 RAG 想像成給模型一個參考圖書館。當你提問時，系統： +將 RAG 想像成給模型一本參考圖書館。當您提問時，系統會： -1. **使用者查詢** - 你提出問題 -2. **嵌入** - 將你的問題轉為向量 -3. **向量搜尋** - 找到相似的文件切塊 -4. **上下文組合** - 把相關切塊添加到提示中 -5. **回應** - LLM 根據上下文生成答案 +1. 使用者查詢 — 您提出問題 +2. 嵌入向量 — 將問題轉換為向量 +3. 向量搜尋 — 找到相似的文件切塊 +4. 上下文組合 — 將相關切塊加入提示中 +5. 回應 — LLM 根據上下文生成答案 -這使模型的回應基於你的實際資料，而不是僅依賴其訓練知識或臆造答案。 +這使模型的回應根植於您的實際數據，而非僅依賴訓練知識或杜撰答案。 ## 先決條件 -- 完成 [Module 00 - 快速開始](../00-quick-start/README.md)（用於本模組後面引用的 Easy RAG 範例） -- 完成 [Module 01 - 介紹](../01-introduction/README.md)（Azure OpenAI 資源已部署，包括 `text-embedding-3-small` 嵌入模型） -- 根目錄有 `.env` 檔，包含 Azure 憑證（由 Module 01 中的 `azd up` 建立） +- 完成 [Module 01 - 介紹](../01-introduction/README.md)（已部署 Azure OpenAI 資源，包括 `text-embedding-3-small` 嵌入模型） +- 根目錄下有 `.env` 檔案並包含 Azure 憑證（由 Module 01 的 `azd up` 指令建立） -> **注意：** 如果你尚未完成 Module 01，請先按照該模組中的部署說明執行。`azd up` 指令同時部署 GPT 聊天模型及本模組使用的嵌入模型。 +> **注意：** 若尚未完成 Module 01，請先依指示完成部署。`azd up` 指令同時部署本模組使用的 GPT 聊天模型與嵌入模型。 ## 理解 RAG -下圖說明了核心概念：RAG 不單依賴模型的訓練資料，而是讓模型先查閱你的文件參考庫，再生成每個答案。 +下圖說明核心概念：RAG 不僅依賴模型訓練資料，而是給它一本您文件的參考圖書館，可在生成答案前先查閱。 What is RAG -*此圖展示標準 LLM（從訓練資料猜測）與 RAG 增強型 LLM（先咨詢你的文件）的區別。* +*此圖展示標準 LLM（依訓練資料猜測）與 RAG 增強 LLM（先查閱您的文件）的差異。* -以下說明整個流程的連接方式。使用者的問題經歷四個階段 —— 嵌入、向量搜尋、上下文組合及答案生成 —— 串聯起來： +以下是從頭到尾的流程圖。使用者的問題通過四個階段——嵌入、向量搜尋、上下文組合、答案生成——每個階段都建立在前一階段基礎上： RAG Architecture -*此圖展示完整的 RAG 管線—使用者查詢依序經歷嵌入、向量搜尋、上下文組合與答案生成。* +*此圖顯示完整 RAG 流程——使用者查詢依序通過嵌入、向量搜尋、上下文組合和答案生成。* -本模組之後將詳細走訪每個階段，包含可執行且可修改的程式碼。 +本模組餘下部分將詳細介紹每個階段，附上可運行與修改的程式碼。 -### 本教程使用哪種 RAG 方法？ +### 本教學使用哪種 RAG 方法？ -LangChain4j 提供三種實作 RAG 的方式，抽象層不同。下圖並列比較： +LangChain4j 提供三種實作 RAG 的方式，抽象層級各異。下圖比較三者： Three RAG Approaches in LangChain4j -*此圖比較 LangChain4j 的三種 RAG 方法 —— Easy、Native 和 Advanced —— 顯示其主要組件及適用情境。* +*此圖比較 LangChain4j 的三種 RAG 方法——Easy、Native 與 Advanced，展示主要組件及適用時機。* -| 方法 | 功能說明 | 權衡 | +| 方法 | 功能說明 | 取捨 | |---|---|---| -| **Easy RAG** | 透過 `AiServices` 和 `ContentRetriever` 自動連線各項功能。你只需標註介面並附加檢索器，LangChain4j 背後處理嵌入、搜尋和提示組合。 | 程式碼最少，但無法看到每步發生的細節。 | -| **Native RAG** | 你自行呼叫嵌入模型、搜尋資料庫、構建提示、生成答案，每一步都清楚明白。 | 程式碼較多，但每階段都可見且可修改。 | -| **Advanced RAG** | 利用 `RetrievalAugmentor` 架構，配合可插拔的查詢轉換器、路由器、重排器和內容注入器，打造生產級管線。 | 靈活度最高，但複雜度也大幅提升。 | +| **Easy RAG** | 利用 `AiServices` 與 `ContentRetriever` 自動串接。您只需註解一個介面並接上擷取器，LangChain4j 在背後處理嵌入、搜尋和提示組合。 | 程式碼量少，但無法看見每步驟細節。 | +| **Native RAG** | 您自己呼叫嵌入模型、搜尋資料庫、建立提示並生成答案——每步驟皆明確。 | 程式碼較多，但每個階段透明且可修改。 | +| **Advanced RAG** | 使用 `RetrievalAugmentor` 框架，包含可插拔的查詢轉換器、路由器、重新排序器和內容注入器，適合專業量產管線。 | 彈性最大，但複雜度也最高。 | -**本教程採用 Native 方式。** RAG 管線的每個階段 —— 問句嵌入、向量搜尋、上下文組合及答案生成 —— 都明確寫在 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 中。這是故意為之：作為學習資源，讓你能完整看到並理解每個步驟比縮減程式碼更重要。當你熟悉各部分如何串接後，可進階使用 Easy RAG 做快速原型，或使用 Advanced RAG 建置生產系統。 +**本教學使用 Native 方式。** RAG 管線的每一步——查詢嵌入、向量庫搜尋、上下文組合、答案生成——皆在 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 明確撰寫。這是有意為之：為了學習，看到且理解每個階段比精簡程式碼更重要。熟悉流程後，您可以轉向 Easy RAG 進行快速原型開發，或用 Advanced RAG 實現生產系統。 -> **💡 已經見過 Easy RAG 的實作嗎？** [快速開始模組](../00-quick-start/README.md) 中包含一個文件問答範例（[`SimpleReaderDemo.java`](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/SimpleReaderDemo.java)），採用 Easy RAG 方式 —— LangChain4j 自動處理嵌入、搜尋和提示組合。本模組則進一步拆解該流程，讓你能自行控制每個階段。 +> **💡 想了解 Easy RAG？** LangChain4j 也提供一種 *Easy RAG* 方式，`AiServices` 與 `ContentRetriever` 自動處理嵌入、搜尋和提示組合。此模組採用更明確的路徑——拆解管線，讓您自行掌控每個階段。 -下圖展示快速開始範例中的 Easy RAG 管線。可見 `AiServices` 和 `EmbeddingStoreContentRetriever` 將所有複雜度隱藏——你只需載入文件、附加檢索器，便能取得答案。本模組的 Native 方式則拆解這些隱藏步驟： +下圖展示 Easy RAG 管線。看到 `AiServices` 和 `EmbeddingStoreContentRetriever` 隱藏了所有複雜流程——您只需載入文件、接上擷取器並獲得答案。本文模組採 Native 方式，將這些隱藏的步驟拆開： Easy RAG Pipeline - LangChain4j -*此圖展示 `SimpleReaderDemo.java` 中的 Easy RAG 管線。與本模組使用的 Native 方式相比：Easy RAG 把嵌入、檢索與提示組合隱藏在 `AiServices` 和 `ContentRetriever` 背後 —— 你只是載入文件、附加檢索器，然後直接取得答案。本模組的 Native 方式則讓你自行呼叫各階段（嵌入、搜尋、組合上下文、生成），獲得完整透明且可控的流程。* +*此圖展示 Easy RAG 管線，與本模組用的 Native 方式作對比：Easy RAG 隱藏嵌入、檢索與提示組合在 `AiServices` 和 `ContentRetriever` 之中——您載入文件、接擷取器、取得答案。Native 方式打開這些流程，您自己呼叫每個階段（嵌入、搜尋、組合上下文、生成），完全掌控且了解每步。* -## 工作原理 +## 運作原理 -本模組的 RAG 管線分成四個階段，當使用者提問時依序執行。首先，上傳的文件會被 **解析並切塊** 成容易處理的小段。這些切塊接著被轉成 **向量嵌入**，並儲存用以數學比較。當有查詢時，系統會執行 **語意搜尋** 找出最相關切塊，最後將這些切塊作為上下文傳給 LLM 進行 **答案生成**。以下章節逐步說明每個階段，包含實際程式碼與圖表。先來看第一步。 +本模組中的 RAG 管線分四個階段，每當使用者提出問題時依序執行。首先，上傳文件被解析並切成小塊。這些切塊再轉成向量嵌入表示並儲存起來，方便數學計算對比。當有查詢時，系統執行語意搜尋找出最相關的切塊，最後將它們作為上下文傳給 LLM 生成答案。下文詳解每階段並附程式碼與示意圖。先從第一步開始。 ### 文件處理 [DocumentService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) -當你上傳文件時，系統會解析它（PDF 或純文字），附加檔名等元資料，然後將文件切分為切塊 —— 能在模型上下文視窗內舒適處理的較小段落。這些切塊略有重疊，避免上下文在切割點丟失。 +當您上傳文件時，系統會解析它（PDF 或純文字），附加檔名等元資料，然後切成切塊——即大小適中、可容納進模型上下文視窗的較小區段。這些切塊有些重疊，避免切割處訊息中斷。 ```java -// 解析上傳的檔案並包裝成 LangChain4j 文件 +// 解析上傳的檔案並封裝成 LangChain4j 文件 Document document = Document.from(content, metadata); -// 分割成 300 代幣的區塊，重疊 30 代幣 +// 分割成每塊 300 代幣，重疊 30 代幣 DocumentSplitter splitter = DocumentSplitters .recursive(300, 30); List segments = splitter.split(document); ``` - -下圖展示視覺化的運作方式。請注意每個切塊與鄰近切塊間共享一些令牌 —— 30 令牌的重疊確保不會有重要上下文落在切割縫隙中： + +以下示意圖說明此流程。注意每個切塊與相鄰切塊有 30 個 token 的重疊 —— 確保不漏掉重要上下文： Document Chunking -*此圖展示文件如何被切成每塊 300 令牌且相互重疊 30 令牌的切塊，確保切塊邊界上下文連貫。* +*此圖示文件被拆成 300 token 大小的切塊，並且有 30 token 重疊，保留切塊接口上下文。* -> **🤖 嘗試用 [GitHub Copilot](https://github.com/features/copilot) 聊天：**開啟 [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java)，並提出： -> - 「LangChain4j 如何將文件切成塊？為什麼重疊很重要？」 -> - 「不同文件類型的最佳切塊大小是多少？為什麼？」 -> - 「如何處理多語言或特殊格式的文件？」 +> **🤖 試試看用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 開啟 [`DocumentService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/DocumentService.java) 並問： +> - 「LangChain4j 如何將文件拆成切塊？為何重疊重要？」 +> - 「不同文件類型的最佳切塊大小為何？」 +> - 「怎麼處理多語言或特殊格式的文件？」 -### 建立嵌入 +### 建立向量表示 [LangChainRagConfig.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/config/LangChainRagConfig.java) -每個切塊會被轉成一種數值表示，稱為嵌入 —— 本質上是一個意義到數字的轉換器。嵌入模型不像聊天模型那樣「智能」；它不能理解指令、推理或回答問題。它做得到的是將文本映射到一個數學空間，意義相近的詞彙會落在鄰近位置 —— 「car」與「automobile」、「refund policy」與「return my money」靠得很近。把聊天模型想成一個能互動的人，而嵌入模型是超好的檔案歸檔系統。 +每個切塊會被轉換成稱為嵌入（embedding）的數字表示——實質上是將語意轉成數字的轉換器。嵌入模型不像聊天模型那般「智能」；它不會執行指令、推理或回答問題。它能做的是將文字映射到一個數學空間，使相似語意的向量彼此靠近——例如「car」和「automobile」相近，「refund policy」和「return my money」相近。把聊天模型想像成會說話的人，嵌入模型則是非常棒的檔案管理系統。 -下圖視覺化此概念 —— 文本輸入，數字向量輸出，類似意義的文本在向量空間中相互接近： +以下圖說明這概念——文字進去，數字向量出來，相似語意會產生彼此接近的向量： Embedding Model Concept -*此圖展示嵌入模型如何將文本轉為數值向量，讓「car」和「automobile」等相似意義詞彙在向量空間中靠近。* +*此圖展示嵌入模型如何將文字轉為數字向量，讓相似語意「car」與「automobile」在向量空間中靠近。* ```java @Bean @@ -153,30 +152,30 @@ public EmbeddingModel embeddingModel() { EmbeddingStore embeddingStore = new InMemoryEmbeddingStore<>(); ``` - -下圖呈現 RAG 管線中兩條分流及其對應的 LangChain4j 類別。**攝取流程**（上傳時執行一次）分割文件、產生切塊嵌入，並透過 `.addAll()` 儲存。**查詢流程**（每次使用者提問執行）將問題嵌入，透過 `.search()` 搜索存儲，回傳匹配的上下文給聊天模型。兩流程皆連接同一個 `EmbeddingStore` 介面： + +下方類別圖展示 RAG 管線中兩條獨立流程與 LangChain4j 實作類別。匯入流程（上傳時執行一次）分割文件、建立切塊嵌入、並透過 `.addAll()` 儲存。查詢流程（使用者每次提問執行）嵌入問題、用 `.search()` 搜尋資料庫，並將符合上下文傳給聊天模型。兩流程共用 `EmbeddingStore` 介面： LangChain4j RAG Classes -*此圖呈現 RAG 管線中的兩條流程——攝取與查詢——及其如何透過共用 EmbeddingStore 介面銜接。* +*此圖顯示 RAG 管線中兩條流程——匯入與查詢——如何透過共用的 EmbeddingStore 介面連接。* -一旦嵌入儲存完成，類似內容會自然聚集在向量空間中。下圖示範關聯主題的文件如何在三維向量空間中集群，實現語意搜尋的基礎： +嵌入儲存後，內容在向量空間自然形成群聚。以下視覺化圖示說明關聯主題的文件如何成為鄰近點，這是語意搜尋的關鍵： Vector Embeddings Space -*此視覺化呈現相關文件如何在三維向量空間聚集，技術文件、商務規則與常見問題組成不同群組。* +*本視覺化說明相關文件在三維向量空間中群聚，例如技術文檔、商業規則與常見問題形成獨立群組。* -當使用者搜尋時，系統執行四個步驟：文件嵌入只做一次、每次搜尋對查詢進行嵌入、使用餘弦相似度比較查詢向量和所有儲存向量，最後回傳排名前 K 的切塊。下圖走訪每步及相應 LangChain4j 類別： +使用者查詢時，系統執行四步驟：文件嵌入建好、每次搜尋時問題轉嵌入、計算問題向量與所有儲存向量的餘弦相似度、回傳最高分的前 K 個切塊。下圖展示每步及 LangChain4j 用到的類別： Embedding Search Steps -*此圖示範四步嵌入搜尋流程：文件嵌入、查詢嵌入、利用餘弦相似度比較向量、回傳前 K 結果。* +*此圖說明嵌入搜尋的四步驟流程：建文件嵌入、建問題嵌入、用餘弦相似度比對向量、回傳前 K 名結果。* ### 語意搜尋 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -當你提出問題時，問題本身也會被轉為嵌入。系統將你的問題嵌入與所有文件切塊的嵌入比對。它找出語意最相近的切塊 —— 不只匹配關鍵字，而是實際上的語意相似。 +當您提問時，系統會先將問題轉成嵌入向量，並與所有文件切塊的嵌入向量比對。系統找出語意最相近的切塊——不只是字詞匹配，而是真正語意層面接近。 ```java Embedding queryEmbedding = embeddingModel.embed(question).content(); @@ -195,28 +194,28 @@ for (EmbeddingMatch match : matches) { double score = match.score(); } ``` - -下圖對照語意搜尋與傳統關鍵字搜尋。搜尋「vehicle」的關鍵字法會錯過「cars and trucks」的切塊，但語意搜尋明白兩者意義相同，將該切塊高分回傳： + +下圖將語意搜尋與傳統關鍵字搜尋做對比。關鍵字搜尋「vehicle」無法找到「cars and trucks」相關切塊，但語意搜尋理解它們同義並回傳高分匹配： Semantic Search -*此圖比較關鍵字搜尋與語意搜尋，展示語意搜尋如何在關鍵字不同時也能檢索到概念相關內容。* -底層中，相似度是使用餘弦相似度測量 — 本質上是在問「這兩支箭頭是否指向相同方向？」兩段文字的用詞可以完全不同，但如果意思相同，它們的向量指向相同方向，得分接近 1.0： +*此圖比較基於關鍵字與語意的搜尋，展示語意搜尋能在關鍵字不同時檢索出相關概念內容。* -Cosine Similarity +底層使用餘弦相似度衡量相似度——可以理解為「兩箭頭方向是否一致？」兩段文字可用完全不同詞彙，但若意義相同，向量會指向相同方向，分數接近 1.0： -*此圖示意餘弦相似度為嵌入向量間的角度 — 向量越一致，得分越接近 1.0，表示語意相似度越高。* +Cosine Similarity +*此圖示說明餘弦相似度作為嵌入向量之間的角度 — 向量越對齊，分數越接近 1.0，表示語意相似度越高。* -> **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) Chat：** 開啟 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 並詢問： -> - 「相似度搜尋如何使用嵌入向量運作？分數是怎麼決定的？」 -> - 「應該使用什麼相似度門檻？這會如何影響結果？」 -> - 「如果找不到相關文件，我應該怎麼處理？」 +> **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 開啟 [`RagService.java`](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) 並詢問： +> - 「相似度搜尋是如何用嵌入向量工作的？分數由什麼決定？」 +> - 「應該使用什麼相似度閾值？它如何影響結果？」 +> - 「遇到找不到相關文件時，該如何處理？」 -### 答案產生 +### 答案生成 [RagService.java](../../../03-rag/src/main/java/com/example/langchain4j/rag/service/RagService.java) -最相關的文字片段會組裝成結構化提示，包括明確指示、檢索到的上下文和使用者問題。模型讀取這些特定片段並根據這些資訊回答 — 它只能使用眼前的內容，避免幻覺。 +最相關的區塊會被組裝成結構化提示，包含明確指示、檢索到的上下文及使用者問題。模型會閱讀這些特定區塊並根據這些資訊回答 — 它只能使用面前的資訊，防止幻覺產生。 ```java String context = matches.stream() @@ -237,17 +236,17 @@ String prompt = String.format(""" String answer = chatModel.chat(prompt); ``` -下圖顯示此組裝的運作方式 — 搜尋步驟中最高分的片段注入提示模板，`OpenAiOfficialChatModel` 則生成有根據的答案： +下圖展示這個組裝過程 — 搜尋步驟中得分最高的區塊被注入提示範本，`OpenAiOfficialChatModel` 產生根據事實的答案： Context Assembly -*此圖顯示如何將最高得分的片段組裝成結構化提示，讓模型從你的數據中生成有根據的答案。* +*此圖示展示如何將得分最高的區塊組裝成結構化提示，使模型能根據您的資料產生根據事實的答案。* ## 執行應用程式 **確認部署：** -確保專案根目錄存在 `.env` 檔案，內含 Azure 憑證（於模組 01 建立）。於此模組目錄 (`03-rag/`) 中執行： +確保根目錄有 `.env` 檔案，內含 Azure 憑證（於模組 01 建立）。從模組目錄（`03-rag/`）執行： **Bash:** ```bash @@ -261,25 +260,25 @@ Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT **啟動應用程式：** -> **注意：** 如果你已從根目錄使用 `./start-all.sh` 啟動所有應用程式（如模組 01 所述），此模組已在 8081 埠執行。你可以跳過以下啟動指令，直接造訪 http://localhost:8081。 +> **注意：** 如果您已從根目錄使用 `./start-all.sh` 開啟所有應用程式（如模組 01 所述），此模組已運行在埠號 8081。您可以跳過下列啟動指令，直接開啟 http://localhost:8081。 -**選項 1：使用 Spring Boot Dashboard（建議 VS Code 用戶）** +**選項 1：使用 Spring Boot Dashboard（建議 VS Code 使用者）** -開發容器包含 Spring Boot Dashboard 擴充套件，提供視覺介面管理所有 Spring Boot 應用。你可在 VS Code 左側活動列找到（尋找 Spring Boot 圖示）。 +開發容器內含 Spring Boot Dashboard 擴充，可視化管理所有 Spring Boot 應用。可在 VS Code 左側活動列找到（尋找 Spring Boot 圖示）。 -透過 Spring Boot Dashboard，你可以： +透過 Spring Boot Dashboard，您可以： - 查看工作區中所有可用的 Spring Boot 應用 -- 一鍵啟動/停止應用 -- 即時觀看應用日誌 +- 一鍵啟動/停止應用程式 +- 即時檢視應用程式日誌 - 監控應用狀態 -點擊「rag」旁的播放按鈕啟動此模組，或一次啟動全部模組。 +只需點擊 "rag" 旁的播放按鈕即可啟動此模組，或一次啟動所有模組。 Spring Boot Dashboard -*此截圖展示 VS Code 中的 Spring Boot Dashboard，讓你可視化啟動、停止與監控應用。* +*此截圖顯示 VS Code 中的 Spring Boot Dashboard，您可以視覺化啟動、停止及監控應用程式。* -**選項 2：使用 Shell 腳本** +**選項 2：使用 shell 腳本** 啟動所有網頁應用（模組 01-04）： @@ -291,7 +290,7 @@ cd .. # 從根目錄 **PowerShell:** ```powershell -cd .. # 從根目錄開始 +cd .. # 從根目錄 .\start-all.ps1 ``` @@ -309,16 +308,16 @@ cd 03-rag .\start.ps1 ``` -兩套腳本會自動從根目錄 `.env` 載入環境變數，若 JAR 不存在則會建構。 +這兩個腳本會自動從根目錄的 `.env` 檔載入環境變數，且若尚未編譯 JAR 檔，會自動執行編譯。 -> **注意：** 若你偏好先手動建構所有模組，再啟動： +> **注意：** 若您想手動先編譯所有模組再啟動： > > **Bash:** > ```bash > cd .. # Go to root directory > mvn clean package -DskipTests > ``` -> + > **PowerShell:** > ```powershell > cd .. # Go to root directory @@ -331,107 +330,107 @@ cd 03-rag **Bash:** ```bash -./stop.sh # 僅限此模組 -# 或 +./stop.sh # 僅此模組 +# 或者 cd .. && ./stop-all.sh # 所有模組 ``` **PowerShell:** ```powershell .\stop.ps1 # 僅此模組 -# 或者 +# 或 cd ..; .\stop-all.ps1 # 所有模組 ``` ## 使用應用程式 -應用提供文件上傳及提問的網頁介面。 +該應用程式提供文件上傳及提問的網頁介面。 RAG Application Interface -*此截圖顯示 RAG 應用介面，供上傳文件與提問。* +*此截圖顯示 RAG 應用介面，您可以上傳文件並提出問題。* ### 上傳文件 -先上傳一個文件 — TXT 格式最適合測試。本目錄中提供一份 `sample-document.txt`，涵蓋 LangChain4j 特性、RAG 實作與最佳實務，非常適合測試系統。 +先上傳文件 — TXT 檔案適合測試。此目錄下提供 `sample-document.txt`，內含 LangChain4j 功能、RAG 實作及最佳實務說明 — 非常適合測試系統。 -系統會處理你的文件，拆分成多個片段，並為每個片段建立嵌入向量。這會在上傳時自動執行。 +系統會處理您的文件，將其拆分成區塊並為每個區塊建立嵌入向量。上傳時自動執行這些程序。 ### 提問 -現在針對文件內容提出具體問題。試著問一些文件中明確敘述的事實性問題。系統會搜尋相關片段，將它們包含進提示，並生成答案。 +現在，可以針對文件內容提出具體問題。嘗試問文件中明確敘述的事實。系統會尋找相關區塊，將它們納入提示並生成答案。 ### 檢查來源引用 -注意每個答案都附有來源參考及相似度分數。這些分數 (0 到 1) 表示片段與你問題的相關程度。分數越高表示匹配越好。這讓你能核對答案是否符合原始資料。 +每個答案都包含帶有相似度分數的來源引用。這些分數（介於 0 至 1）表示每個區塊與問題的相關程度。分數越高，匹配越好。這讓您能根據來源資料驗證答案。 RAG Query Results -*此截圖顯示查詢結果，包括生成答案、來源參考以及每個擷取片段的相關性分數。* +*此截圖展示查詢結果，包括產生的答案、來源引用與每個檢索區塊的相關度分數。* -### 嘗試不同問題 +### 試驗不同問題 -試試不同類型的問題： +嘗試不同類型問題： - 具體事實：「主要主題是什麼？」 -- 比較：「X 和 Y 有什麼不同？」 -- 摘要：「總結關於 Z 的要點」 +- 比較：「X 與 Y 有何不同？」 +- 摘要：「請總結 Z 的重點」 -觀察相關性分數如何依你的問題與文件內容符合程度改變。 +觀察相關度分數隨您的問題與文件內容匹配程度的變化。 -## 核心概念 +## 關鍵概念 -### 分段策略 +### 拆分策略 -文件分割成 300 個 token 的片段，重疊 30 個 token。此平衡確保每段具有足夠上下文且大小適中，能在提示中包含多個片段。 +文件拆成 300 個 token 的區塊，區塊間重疊 30 個 token。此平衡可確保每個區塊有足夠上下文有意義，同時讓多個區塊能同時放入提示內。 ### 相似度分數 -每個擷取的片段都會帶有 0 到 1 的相似度分數，表示與用戶問題的匹配程度。下圖展示分數範圍及系統如何用它來篩選結果： +每個檢索到的區塊都附帶介於 0 到 1 的相似度分數，表示與使用者問題的匹配程度。下圖視覺化分數區間以及系統如何利用它們過濾結果： Similarity Scores -*此圖展示 0 到 1 的分數範圍，系統設定最低 0.5 門檻以過濾無關片段。* +*此圖示展示相似度分數區間為 0 至 1，並有 0.5 的最低門檻用來過濾不相關的區塊。* -分數範圍為： +分數區間說明： - 0.7-1.0：高度相關，精確匹配 - 0.5-0.7：相關，具良好上下文 -- 低於 0.5：過濾掉，過於不同 +- 低於 0.5：過濾掉，差異太大 -系統僅擷取高於最低門檻的片段以確保品質。 +系統只會擷取高於最低門檻的區塊，以確保品質。 -嵌入在語意群聚清晰時效果良好，但也存在盲點。下圖顯示常見失敗模式 — 片段過大造成向量模糊，片段過小缺乏上下文，模糊詞彙對應多個群聚，以及精確匹配查詢（ID、零件號）完全無法用嵌入： +嵌入適合意義聚集明確時，但存在盲點。下圖顯示常見失敗模式 — 區塊太大造成向量模糊，區塊太小缺乏上下文，含糊詞彙指向多個群集，以及精確匹配（識別碼、零件號）根本不適用嵌入： Embedding Failure Modes -*此圖顯示常見嵌入失敗模式：片段過大、片段過小、模糊詞彙對應多群聚，以及像 ID 這類精確匹配無法用嵌入解決。* +*此圖示顯示嵌入的常見失敗模式：區塊太大、區塊太小、含糊詞指向多個群集、以及識別碼等精確匹配查詢。* ### 記憶體儲存 -此模組使用記憶體儲存以簡化設計。重啟應用時，已上傳文件會遺失。正式環境會使用持久向量資料庫，例如 Qdrant 或 Azure AI Search。 +此模組為簡便起見使用記憶體儲存，應用程式重啟時已上傳文件會遺失。生產系統採用持久化向量資料庫，如 Qdrant 或 Azure AI Search。 ### 上下文視窗管理 -每個模型均有最大上下文視窗大小限制。無法涵蓋大型文件的所有片段。系統會擷取前 N 個最高相關片段（預設 5 個），在限制內提供足夠上下文以產生準確答案。 +每個模型有最大上下文視窗限制。無法包含大型文件的所有區塊。系統會檢索前 N 個最相關區塊（預設 5 個），保持在限制內同時提供足夠上下文以獲得準確答案。 -## RAG 何時重要 +## 何時選用 RAG -RAG 並非總是最佳解決方案。下圖決策指南幫助你判斷何時 RAG 有幫助，何時簡單作法（直接將內容包含在提示或依賴模型內建知識）即可： +RAG 並非總是最佳方案。下列決策導引幫助您判斷何時 RAG 有價值，何時簡單方式即可 — 如直接包含內容於提示或依賴模型內建知識： When to Use RAG -*此圖展示何時使用 RAG 可增值，何時可用簡單方法即可應付的決策指南。* +*此圖示為決策導引，說明何時 RAG 增加價值，何時簡單方法已足夠。* ## 後續步驟 -**下一模組：** [04-tools - 使用工具的 AI 代理](../04-tools/README.md) +**下一模組：** [04-tools - AI Agents with Tools](../04-tools/README.md) --- -**導覽：** [← 上一節：模組 02 - 提示工程](../02-prompt-engineering/README.md) | [回主頁](../README.md) | [下一節：模組 04 - 工具 →](../04-tools/README.md) +**導覽：** [← 上一章：模組 02 - Prompt Engineering](../02-prompt-engineering/README.md) | [回主頁](../README.md) | [下一章：模組 04 - Tools →](../04-tools/README.md) --- -**免責聲明**： -本文件是使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯的。雖然我們力求準確，但請注意自動翻譯可能包含錯誤或不準確之處。文件的原始語言版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤譯負責。 +**免責聲明**： +此文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力追求準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們不對因使用此翻譯所產生的任何誤解或誤譯承擔責任。 \ No newline at end of file diff --git a/translations/zh-TW/04-tools/README.md b/translations/zh-TW/04-tools/README.md index 769dbe45d..cf71b6654 100644 --- a/translations/zh-TW/04-tools/README.md +++ b/translations/zh-TW/04-tools/README.md @@ -1,84 +1,84 @@ -# Module 04：具備工具功能的 AI 代理 +# Module 04: 使用工具的 AI 代理 ## 目錄 -- [影片導覽](../../../04-tools) -- [你將學到什麼](../../../04-tools) -- [先決條件](../../../04-tools) -- [了解具備工具功能的 AI 代理](../../../04-tools) -- [工具呼叫的運作原理](../../../04-tools) - - [工具定義](../../../04-tools) - - [決策過程](../../../04-tools) - - [執行](../../../04-tools) - - [回應產生](../../../04-tools) - - [架構：Spring Boot 自動裝配](../../../04-tools) -- [工具鏈結](../../../04-tools) -- [執行應用程式](../../../04-tools) -- [使用應用程式](../../../04-tools) - - [嘗試簡單工具使用](../../../04-tools) - - [測試工具鏈結](../../../04-tools) - - [查看對話流程](../../../04-tools) - - [嘗試不同請求](../../../04-tools) -- [關鍵概念](../../../04-tools) - - [ReAct 模式（推理與行動）](../../../04-tools) - - [工具描述很重要](../../../04-tools) - - [會話管理](../../../04-tools) - - [錯誤處理](../../../04-tools) -- [可用工具](../../../04-tools) -- [何時使用基於工具的代理](../../../04-tools) -- [工具與 RAG 比較](../../../04-tools) -- [後續步驟](../../../04-tools) +- [影片導覽](#影片導覽) +- [你將學到的內容](#你將學到的內容) +- [先決條件](#先決條件) +- [理解帶有工具的 AI 代理](#理解帶有工具的-ai-代理) +- [工具呼叫如何運作](#工具呼叫如何運作) + - [工具定義](#工具定義) + - [決策制定](#決策制定) + - [執行](#執行) + - [回應生成](#回應生成) + - [架構：Spring Boot 自動配線](#架構：spring-boot-自動配線) +- [工具串連](#工具串連) +- [執行應用程式](#執行應用程式) +- [使用應用程式](#使用應用程式) + - [嘗試簡單工具用法](#嘗試簡單工具使用) + - [測試工具串連](#測試工具串接) + - [查看對話流程](#觀看對話流程) + - [嘗試不同請求](#嘗試不同請求組合) +- [核心概念](#主要概念) + - [ReAct 模式（推理與行動）](#react-模式（推理與行動）) + - [工具描述的重要性](#工具描述很重要) + - [會話管理](#會話管理) + - [錯誤處理](#錯誤處理) +- [可用工具](#可用工具) +- [何時使用基於工具的代理](#何時使用基於工具的代理) +- [工具與 RAG 的比較](#工具-vs-rag) +- [下一步](#下一步) ## 影片導覽 -觀看本直播課程，了解如何開始使用本模組： +觀看這個現場教學，了解如何開始使用本模組： -AI Agents with Tools and MCP - Live Session +帶有工具的 AI 代理與 MCP - 現場教學 -## 你將學到什麼 +## 你將學到的內容 -到目前為止，你已學會如何與 AI 進行對話、有效結構提示，以及如何將回答依據你的文件。然而仍存在基本限制：語言模型只能生成文字，無法查詢天氣、進行計算、查詢資料庫或與外部系統互動。 +到目前為止，你已經學會如何與 AI 進行對話、有效結構化提示語，並以文件為基礎生成回應。但仍有一個根本限制：語言模型只能生成文本。它不能查詢天氣、執行計算、查詢資料庫或與外部系統互動。 -工具改變了這點。透過賦予模型可呼叫的函式，將它從純文字生成器轉變為能採取行動的代理。模型會決定何時需要工具、使用哪個工具，及傳遞什麼參數。你的程式碼執行函式並回傳結果，模型則將此結果整合進回應中。 +工具改變了這一點。通過給模型調用函數的能力，你將它從純文字生成器轉變為能執行動作的代理。模型決定什麼時候需要工具、使用哪個工具，以及傳遞什麼參數。你的程式碼執行該函數並返回結果，模型將結果整合到回應中。 ## 先決條件 -- 已完成[模組 01 - 介紹](../01-introduction/README.md)（部署 Azure OpenAI 資源） -- 建議完成之前的模組（本模組在 Tools vs RAG 比較中，參考了[模組 03 的 RAG 概念](../03-rag/README.md)） -- 根目錄含有 `.env` 檔，內含 Azure 認證（由模組 01 的 `azd up` 建立） +- 完成 [Module 01 - 介紹](../01-introduction/README.md)（部署了 Azure OpenAI 資源） +- 建議完成之前的模組（本模組在 Tools vs RAG 比較中參考了[Module 03 中的 RAG 概念](../03-rag/README.md)） +- 在根目錄擁有包含 Azure 憑證的 `.env` 檔案（由 Module 01 中的 `azd up` 指令創建） -> **注意：** 如果尚未完成模組 01，請先依照那裡的部署說明操作。 +> **注意：** 若尚未完成 Module 01，請先按照那裡的部署說明操作。 -## 了解具備工具功能的 AI 代理 +## 理解帶有工具的 AI 代理 -> **📝 注意：** 本模組中「代理（agents）」指的是具備工具呼叫功能的 AI 助理。與我們在[模組 05：MCP](../05-mcp/README.md)中介紹的**自主代理 AI（Agentic AI）**—具備規劃、記憶及多步推理的代理—不同。 +> **📝 注意：** 本模組中「代理」一詞指的是具備工具呼叫能力的 AI 助理。這與我們將在 [Module 05: MCP](../05-mcp/README.md) 裡涵蓋的Agentic AI 模式（具備規劃、記憶及多步推理的自主代理）不同。 -無工具時，語言模型只能基於訓練資料生成文字。問它當前天氣，它只能猜測。給它工具，模型便能呼叫天氣 API、進行計算或查詢資料庫，並將真實結果編織到回答中。 +沒有工具時，語言模型只能從訓練資料生成文字。問當前天氣，它只能猜測。給它工具，它就能呼叫天氣 API、執行計算或查詢資料庫，然後將這些真實結果融入回應。 -Without Tools vs With Tools +無工具 vs 有工具 -*無工具時模型只能猜測，有工具時可呼叫 API、執行計算，回傳即時資料。* +*沒有工具時模型只能猜測；有了工具，它可以呼叫 API、跑計算並返回即時資料。* -具備工具的 AI 代理遵循**推理與行動（ReAct）**模式。模型不只是回應，而是思考需求、透過呼叫工具採取行動、觀察結果，然後決定是否繼續行動或給出最終答案： +搭載工具的 AI 代理遵循一種 **推理與行動（ReAct）** 模式。模型不只是回應——它思考需求、透過呼叫工具行動、觀察結果，接著決定是否再行動或給出最終答案： -1. **推理** — 代理分析使用者問題並判斷需要什麼資訊 -2. **行動** — 選擇合適工具，產生正確參數並呼叫 -3. **觀察** — 接收工具輸出並評估結果 -4. **重複或回應** — 若需要更多資料，則迴圈；否則生成自然語言回答 +1. 推理 — 代理分析用戶問題，判斷需要什麼資訊 +2. 行動 — 選擇合適工具、生成正確參數並呼叫 +3. 觀察 — 接收工具輸出並評估結果 +4. 重複或回應 — 若需更多資料，回到第一步；否則撰寫自然語言答案 -ReAct Pattern +ReAct 模式 -*ReAct 循環 — 代理推理行動方案、呼叫工具、觀察結果並多次迴圈，直到給出最終答案。* +*ReAct 循環 — 代理推理需做什麼，呼叫工具行動，觀察結果，反覆迴圈直到能給出答案。* -此流程自動執行。你定義工具及其描述，模型負責決定何時、如何使用工具。 +這是自動發生的。你定義工具及其描述，模型負責判斷何時、如何使用它們。 -## 工具呼叫的運作原理 +## 工具呼叫如何運作 ### 工具定義 [WeatherTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) | [TemperatureTool.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/TemperatureTool.java) -你定義帶有清晰描述與參數規範的函式。模型透過系統提示看到這些描述，理解每個工具的功能。 +你定義具清晰描述和參數規格的函數。模型會在系統提示中看到這些描述，明白每個工具的功能。 ```java @Component @@ -96,108 +96,108 @@ public interface Assistant { String chat(@MemoryId String sessionId, @UserMessage String message); } -// 助理由 Spring Boot 自動配置： -// - ChatModel bean +// 助理由 Spring Boot 自動連接: +// - ChatModel Bean // - 所有來自 @Component 類別的 @Tool 方法 // - 用於會話管理的 ChatMemoryProvider ``` -下圖解析各註解，展示每個部分如何幫助 AI 理解何時呼叫工具及傳遞哪些引數： +下圖解構每個註解，展示每部分如何幫助 AI 理解何時呼叫工具及傳遞哪些參數： -Anatomy of Tool Definitions +工具定義結構 -*工具定義結構 — @Tool 告訴 AI 何時使用，@P 描述每個參數，@AiService 在啟動時自動裝配。* +*工具定義結構 — @Tool 告訴 AI 何時使用它，@P 描述每個參數，@AiService 在啟動時自動連接所有部分。* -> **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 開啟 [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) 並詢問： -> - 「我該如何整合像 OpenWeatherMap 這類真正的天氣 API，而非模擬資料？」 -> - 「什麼樣的工具描述能幫助 AI 正確使用它？」 -> - 「如何在工具實作中處理 API 錯誤及速率限制？」 +> **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 打開 [`WeatherTool.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/tools/WeatherTool.java) 並詢問： +> - 「我該如何整合像 OpenWeatherMap 這樣的真實天氣 API，而不是使用模擬資料？」 +> - 「什麼樣的工具描述能幫助 AI 正確使用工具？」 +> - 「如何在工具實作中處理 API 錯誤和速率限制？」 -### 決策過程 +### 決策制定 -當使用者問「西雅圖的天氣如何？」時，模型不會隨機選擇工具。它會比對使用者意圖與已知工具描述，針對相關性打分並選出最佳匹配。接著產生帶有正確參數的結構化函式呼叫，此例中將 `location` 設為 `"Seattle"`。 +當用戶問「西雅圖今天天氣如何？」時，模型不會隨機選工具。它將用戶意圖與所有工具描述比對，針對相關性打分並選擇最適合的工具。接著生成結構化函數調用，這裡是設置 `location` 為 `"Seattle"`。 -若無工具匹配使用者請求，模型則退回以自身知識回答。若多工具匹配，則選最具體者。 +若沒有工具匹配用戶請求，模型則從自身知識庫回答。若多個工具匹配，則選擇最具體的。 -How the AI Decides Which Tool to Use +AI 如何決定使用哪個工具 -*模型根據使用者意圖評估所有可用工具並選擇最佳匹配，這就是為何撰寫清晰、具體的工具描述很重要。* +*模型評估所有可用工具與用戶意圖比對並挑選最佳匹配——這就是為何撰寫清晰、具體的工具描述很重要。* ### 執行 [AgentService.java](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) -Spring Boot 自動將所有已註冊工具與宣告式 `@AiService` 介面裝配，LangChain4j 自動執行工具呼叫。幕後，完整的工具呼叫流程涵蓋六個階段——從使用者自然語言問題到自然語言回答： +Spring Boot 自動配線所有用 `@AiService` 宣告的工具介面，LangChain4j 會自動執行工具呼叫。幕後，一個完整的工具呼叫流程涵蓋六個階段——從用戶的自然語言提問一直到回覆自然語言的答案： -Tool Calling Flow +工具呼叫流程 -*完整流程 — 使用者提問，模型選擇工具，LangChain4j 執行，模型將結果融入自然回應。* +*端到端流程——用戶問問題，模型選擇工具，LangChain4j 執行工具，模型將結果融入自然回應中。* -如果你在模組 00 執行過 [ToolIntegrationDemo](../../../00-quick-start/src/main/java/com/example/langchain4j/quickstart/ToolIntegrationDemo.java)，你已看過此模式 —— `Calculator` 工具就是用相同流程呼叫。下面的時序圖精確顯示示範當中幕後發生了什麼： +幕後，`AiServices` 對任一工具運行相同的工具呼叫循環——此處以簡單的 `Calculator` 展示。下方時序圖精確呈現幕後發生的流程： -Tool Calling Sequence Diagram +工具呼叫時序圖 -*Quick Start 示範中的工具呼叫循環 — `AiServices` 傳送訊息與工具結構給 LLM，LLM 以函式呼叫如 `add(42, 58)` 回應，LangChain4j 在本地執行 `Calculator` 方法並回傳結果給最終回答。* +*工具呼叫循環——`AiServices` 傳送你的訊息與工具結構給 LLM，LLM 回覆如 `add(42, 58)` 的函數調用，LangChain4j 在本機執行 `Calculator` 方法，並將結果回饋用於最終答案。* > **🤖 嘗試使用 [GitHub Copilot](https://github.com/features/copilot) 聊天：** 開啟 [`AgentService.java`](../../../04-tools/src/main/java/com/example/langchain4j/agents/service/AgentService.java) 並詢問： -> - 「ReAct 模式如何運作，為何對 AI 代理有效？」 -> - 「代理如何決定使用哪個工具及順序？」 -> - 「工具執行失敗時會發生什麼，我該怎麼健全處理錯誤？」 +> - 「ReAct 模式如何運作，為什麼對 AI 代理有效？」 +> - 「代理如何決定使用哪個工具以及順序？」 +> - 「如果工具執行失敗，怎麼穩健處理錯誤？」 -### 回應產生 +### 回應生成 -模型接收天氣資料，格式化並以自然語言回覆使用者。 +模型接收天氣資料，並將其格式化為自然語言回應給用戶。 -### 架構：Spring Boot 自動裝配 +### 架構：Spring Boot 自動配線 -本模組使用 LangChain4j 的 Spring Boot 整合及宣告式 `@AiService` 介面。啟動時，Spring Boot 探測所有包含 `@Tool` 方法的 `@Component`、你的 `ChatModel` bean 及 `ChatMemoryProvider`，然後全部裝配到單一 `Assistant` 介面，無需樣板程式碼。 +本模組使用 LangChain4j 與 Spring Boot 的整合，搭配宣告式 `@AiService` 介面。Spring Boot 啟動時會發現所有包含 `@Tool` 的 `@Component`，你的 `ChatModel` bean，以及 `ChatMemoryProvider`，然後全部自動配線成單一的 `Assistant` 介面，免去手動撰寫樣板程式。 -Spring Boot Auto-Wiring Architecture +Spring Boot 自動配線架構 -*@AiService 介面串聯 ChatModel、工具元件及記憶提供者 — Spring Boot 自動處理所有裝配。* +*@AiService 介面將 ChatModel、工具組件與記憶提供者串接在一起——Spring Boot 自動負責所有配線。* -以下是請求生命週期完整時序圖——從 HTTP 請求經控制器、服務及自動裝配代理，直至工具執行完畢回傳： +完整請求生命週期如下時序圖示——從 HTTP 請求經過控制器、服務、及自動配線代理，一路到工具執行及回應： -Spring Boot Tool Calling Sequence +Spring Boot 工具呼叫時序圖 -*完整 Spring Boot 請求流程 — HTTP 請求經控制器及服務傳至自動裝配的 Assistant 代理，該代理自動協調 LLM 與工具呼叫。* +*完整 Spring Boot 請求生命週期——HTTP 請求流經控制器與服務到自動配線的 Assistant 代理，再自動協作 LLM 與工具呼叫。* 此方法的主要優勢： -- **Spring Boot 自動裝配** — 自動注入 ChatModel 與工具 -- **@MemoryId 模式** — 自動基於會話的記憶管理 -- **單一實例** — Assistant 只建立一次，重用提升效能 -- **型別安全執行** — Java 方法直接呼叫並完成型別轉換 -- **多回合協調** — 自動處理工具鏈結 -- **零樣板程式碼** — 無須手動呼叫 `AiServices.builder()` 或自行管理記憶 HashMap +- **Spring Boot 自動配線** — ChatModel 與工具自動注入 +- **@MemoryId 模式** — 自動處理基於會話的記憶管理 +- 單一實例 — Assistant 實例只建立一次，提高效能 +- 型別安全執行 — 直接用 Java 方法呼叫並轉換型別 +- 多輪協調 — 自動處理工具串連 +- 零樣板程式 — 無需手寫 `AiServices.builder()` 或管理記憶 HashMap -手動使用 `AiServices.builder()` 的方法需更多程式碼，且無法享受 Spring Boot 整合優勢。 +手動方式（自行使用 `AiServices.builder()`）需更多程式碼，且失去 Spring Boot 整合的優勢。 -## 工具鏈結 +## 工具串連 -**工具鏈結** — 當單一問題需要多個工具時，基於工具的代理展現真正的威力。問「西雅圖的天氣多少華氏度？」時，代理會自動串接兩個工具：先呼叫 `getCurrentWeather` 取得攝氏溫度，再將結果傳入 `celsiusToFahrenheit` 轉換成華氏，全部在一次對話回合完成。 +工具串連 — 基於工具的代理真正威力在於一個問題需要多個工具時展現。問「西雅圖的天氣是幾華氏度？」代理會自動串連兩個工具：先呼叫 `getCurrentWeather` 取得攝氏溫度，再將該值傳入 `celsiusToFahrenheit` 轉換——整個流程在同一回合對話中完成。 -Tool Chaining Example +工具串連範例 -*工具鏈結示例 — 代理先呼叫 getCurrentWeather，將攝氏結果送入 celsiusToFahrenheit，最終給出綜合答案。* +*工具串連實例——代理先呼叫 getCurrentWeather，然後將攝氏結果傳給 celsiusToFahrenheit，最後給出合成答案。* -**優雅的失敗** — 詢問模擬資料中不存在的城市天氣時，工具會回傳錯誤訊息，AI 會解釋無法協助，而非崩潰。工具失敗時安全處理。下圖比較兩種做法——正確錯誤處理時，代理捕捉例外並給予友善回應；未處理時整個應用崩潰： +優雅失敗 — 詢問模擬資料內沒有的城市天氣，工具會回傳錯誤訊息，AI 會說明無法提供幫助而非崩潰。工具故障安全。下圖對比兩種方式——有適當錯誤處理時，代理捕捉例外並以協助回應；無則整個應用崩潰： -Error Handling Flow +錯誤處理流程 -*工具失敗時，代理捕捉錯誤並提供有幫助的說明，而非崩潰。* +*當工具失敗時，代理會捕捉錯誤並以有用說明回應，而非崩潰。* -這在單回合對話中發生，代理自主協調多重工具呼叫。 +這發生在單一次對話回合內。代理可以自主協調多次工具呼叫。 ## 執行應用程式 -**驗證部署：** +**確認部署：** -確保根目錄存在 `.env` 檔並含有 Azure 認證（於模組 01 建立）。從本模組目錄（`04-tools/`）執行： +確保根目錄存在包含 Azure 憑證的 `.env` 檔案（在 Module 01 部署期間建立）。從本模組目錄 (`04-tools/`) 執行： **Bash:** ```bash -cat ../.env # 應顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT +cat ../.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT ``` **PowerShell:** @@ -207,24 +207,24 @@ Get-Content ..\.env # 應該顯示 AZURE_OPENAI_ENDPOINT、API_KEY、DEPLOYMENT **啟動應用程式：** -> **注意：** 若你已透過根目錄的 `./start-all.sh`（模組 01 中描述）啟動全部應用，本模組已在 8084 埠執行。可跳過以下啟動指令，直接前往 http://localhost:8084。 +> **注意：** 若你已從根目錄用 `./start-all.sh` 啟動所有應用程式（如 Module 01 所述），本模組已在 8084 埠運行，可跳過下列啟動指令，直接前往 http://localhost:8084。 -**方案 1：使用 Spring Boot 儀表板（建議 VS Code 用戶）** +**選項 1：使用 Spring Boot Dashboard（推薦 VS Code 使用者）** -開發容器內含 Spring Boot 儀表板擴充，提供視覺化介面管理所有 Spring Boot 應用。可在 VS Code 左側活動欄找到（尋找 Spring Boot 圖示）。 +開發容器已包含 Spring Boot Dashboard 擴充套件，提供視覺化介面管理所有 Spring Boot 應用程式。在 VS Code 左側活動列可看到（尋找 Spring Boot 圖示）。 -你可以透過 Spring Boot 儀表板： -- 查看工作區中所有可用的 Spring Boot 應用 -- 一鍵啟動/停止應用 -- 即時檢視應用日誌 -- 監控應用狀態 -只要點擊「tools」旁邊的播放按鈕即可啟動此模組，或一次啟動所有模組。 +透過 Spring Boot Dashboard，你可以： +- 查看工作區內所有 Spring Boot 應用程式 +- 一鍵啟動/停止應用程式 +- 即時檢視應用程式日誌 +- 監控應用程式狀態 -以下是在 VS Code 中的 Spring Boot 儀表板畫面： +只要點擊「tools」旁的播放按鈕即可啟動本模組，或者一次啟動所有模組。 +以下是 VS Code 中 Spring Boot Dashboard 的介面： Spring Boot Dashboard -*VS Code 中的 Spring Boot 儀表板 — 可從一處啟動、停止並監控所有模組* +*VS Code 中的 Spring Boot 儀表板 — 從一個地方啟動、停止並監控所有模組* **選項 2：使用 shell 腳本** @@ -238,11 +238,11 @@ cd .. # 從根目錄 **PowerShell:** ```powershell -cd .. # 從根目錄 +cd .. # 從根目錄開始 .\start-all.ps1 ``` -或者只啟動此模組： +或僅啟動此模組： **Bash:** ```bash @@ -256,9 +256,9 @@ cd 04-tools .\start.ps1 ``` -這兩個腳本會自動從根目錄的 `.env` 檔案載入環境變數，如果 JAR 檔不存在，則會進行編譯。 +這兩個腳本會自動從根目錄的 `.env` 檔案載入環境變數，若 JAR 檔案不存在會自動建置。 -> **注意：** 如果你偏好先手動編譯所有模組再啟動： +> **注意：** 如果你偏好在啟動前手動建置所有模組： > > **Bash:** > ```bash @@ -272,14 +272,14 @@ cd 04-tools > mvn clean package -DskipTests > ``` -在瀏覽器中開啟 http://localhost:8084 。 +在瀏覽器開啟 http://localhost:8084 。 -**停止方法：** +**停止命令：** **Bash:** ```bash ./stop.sh # 僅此模組 -# 或者 +# 或 cd .. && ./stop-all.sh # 所有模組 ``` @@ -292,96 +292,96 @@ cd ..; .\stop-all.ps1 # 所有模組 ## 使用應用程式 -此應用程式提供一個網頁介面，讓你可以與具備天氣查詢及溫度轉換工具的 AI 代理互動。以下是介面長什麼樣子 — 包含快速啟動示例和用於發送請求的聊天面板： +應用程式提供一個網頁界面，可以與一個能存取天氣和溫度轉換工具的 AI 代理互動。介面長這樣 — 包含快速示範範例以及用於發送請求的聊天面板： AI Agent Tools Interface -*AI 代理工具介面 — 快速示例與互動聊天介面* +*AI 代理工具介面 — 快速範例與用於互動的聊天介面* ### 嘗試簡單工具使用 -從簡單請求開始：「將 100 華氏度轉換為攝氏度」。代理會判斷需要使用溫度轉換工具，並以正確參數呼叫，然後回傳結果。這種流程感覺非常自然 — 你並不需要指定要用哪個工具或如何呼叫。 +從一個簡單請求開始：「將 100 華氏度轉換為攝氏度」。代理能辨識到需要使用溫度轉換工具，並以正確參數呼叫，返回結果。你會發現非常自然 — 你沒指定要用哪個工具、該如何呼叫。 ### 測試工具串接 -現在試試比較複雜的請求：「西雅圖的天氣如何，並將結果轉換成華氏度？」觀看代理分步驟處理。首先取得天氣（回傳攝氏），判斷必須轉換為華氏度，再呼叫轉換工具，最後將兩者結果合併成一個回答。 +接著嘗試更複雜的請求：「西雅圖的天氣如何，並將其轉換為華氏度？」觀察代理如何步驟式處理。它先取得天氣（回傳攝氏度），辨識後續需轉成華氏度，再呼叫轉換工具，最後將兩者結果合併回應。 -### 查看對話流程 +### 觀看對話流程 -聊天介面會保留對話歷史，允許多輪互動。你可以看到所有先前的查詢及回覆，有助於追蹤對話並了解代理如何從多次交流中建立上下文。 +聊天介面會保留對話歷史，讓你能多輪互動。你能看到所有先前查詢與回答，方便追蹤對話並理解代理如何在多次交換中建立上下文。 Conversation with Multiple Tool Calls -*多輪對話示範簡單轉換、天氣查詢和工具串接* +*多輪對話示範，包含簡單轉換、天氣查詢與工具串接* -### 嘗試不同請求 +### 嘗試不同請求組合 -嘗試各種組合： -- 天氣查詢：「東京的天氣如何？」 -- 溫度轉換：「25°C 是多少開爾文？」 -- 綜合查詢：「查詢巴黎的天氣，告訴我是否高於 20°C」 +嘗試以下各種情境： +- 天氣查詢：「東京今天天氣如何？」 +- 溫度轉換：「25°C 是幾開爾文？」 +- 結合查詢：「查巴黎天氣，並告訴我是否超過 20°C」 -注意代理如何理解自然語言並將其映射到適合的工具呼叫。 +注意代理是如何將自然語言解讀成適合的工具呼叫。 -## 關鍵概念 +## 主要概念 ### ReAct 模式（推理與行動） -代理在推理（決定要做什麼）與行動（使用工具）之間交替。此模式使其能自動解決問題，而非僅僅照指令回應。 +代理在推理（決定要做什麼）與行動（使用工具）之間交替。這種模式使其能自主解決問題，而非僅是回覆指令。 -### 工具說明很重要 +### 工具描述很重要 -工具說明的品質直接影響代理使用工具的準確度。清楚、具體的說明有助模型理解何時以及如何呼叫每個工具。 +工具的描述品質直接影響代理使用工具的效能。清楚、具體的描述能幫助模型了解何時以及如何呼叫各工具。 ### 會話管理 -`@MemoryId` 標註可自動啟用基於會話的記憶管理。每個會話 ID 都會對應一個由 `ChatMemoryProvider` 受管理的獨立 `ChatMemory` 實例，因此多位用戶可同時互動，且對話不會互相混淆。下圖展示多用戶如何根據其會話 ID 導向各自隔離的記憶庫： +`@MemoryId` 標註啟用自動的會話記憶管理。每個會話 ID 都會有屬於自己的 `ChatMemory` 實例，由 `ChatMemoryProvider` bean 管理，因此多個使用者能同時和代理互動，彼此對話不會互相干擾。下圖展示如何根據會話 ID 將多個使用者導向隔離的記憶存儲： Session Management with @MemoryId -*每個會話 ID 對應獨立的對話歷史 — 用戶彼此看不到對方訊息。* +*每個會話 ID 對應獨立的對話歷史 — 使用者永遠不會看到彼此訊息。* ### 錯誤處理 -工具可能失敗 — API 超時、參數可能錯誤、外部服務可能宕機。生產環境中的代理需要錯誤處理，讓模型能解釋問題或嘗試替代方案，而不是整個應用崩潰。當工具拋出例外時，LangChain4j 會捕捉並將錯誤訊息回饋給模型，模型即可用自然語言說明問題。 +工具可能會失敗——API 超時、參數不合法、外部服務故障。正式環境中的代理需要錯誤處理，讓模型能解釋問題或嘗試替代方案，而不是讓整個應用崩潰。工具拋出例外時，LangChain4j 會捕捉並將錯誤訊息回饋給模型，模型接著用自然語言解釋問題。 ## 可用工具 -下圖展示你可以建構的廣泛工具生態系。此模組示範了天氣與溫度工具，但相同的 `@Tool` 模式可用於任何 Java 方法——從資料庫查詢到支付處理。 +下圖展示你可以建立的廣泛工具生態系統。此模組示範天氣和溫度工具，但同樣的 `@Tool` 模式適用於任何 Java 方法——從資料庫查詢到支付處理皆可。 Tool Ecosystem -*任何用 @Tool 標註的 Java 方法都可供 AI 使用 — 此模式可延伸至資料庫、API、電子郵件、檔案操作等。* +*任何用 @Tool 標註的 Java 方法都能讓 AI 使用——此模式擴及資料庫、API、電子郵件、檔案操作等。* ## 何時使用基於工具的代理 -不是每個請求都需要工具。決策點在於 AI 是需要與外部系統互動，或僅從自身知識庫回答。下圖指南總結何時工具會增值，何時是多餘的： +並非每個請求都需要工具。決策基準是 AI 是否需要和外部系統互動，或能從自身知識庫回答。下圖總結何時工具能增加價值，何時則無需： When to Use Tools -*簡易決策指南 — 工具用於即時資料、計算及執行動作；一般知識與創意任務則不需要。* +*快速決策參考——工具適用於即時資料、計算與操作；一般知識與創意工作不需要。* -## 工具與 RAG +## 工具 vs RAG -模組 03 與 04 都擴展 AI 的能力，但方式根本不同。RAG 透過檢索文件提供模型**知識**，工具則賦予模型呼叫函式執行**動作**的能力。下圖並列比較這兩種方法──從工作流程到其各自的取捨： +模組 03 與 04 都擴展 AI 功能，但方式本質不同。RAG 透過文件檢索給模型提供知識，工具讓模型能呼叫函數執行動作。下圖並列比較兩種方法工作流程及權衡： Tools vs RAG Comparison -*RAG 從靜態文件檢索資訊 — 工具執行動作並取得動態、即時資料。許多生產系統會同時結合兩者。* +*RAG 從靜態文件檢索資訊——工具則執行操作並取得即時動態資料。許多正式系統同時結合兩者。* -實務上，許多生產系統會同時運用兩者：RAG 用於基於文檔給出根據，工具用於擷取即時資料或執行操作。 +實務上，許多正式系統會結合兩種方法：用 RAG 讓答案有文件依據，用工具抓取即時資料或執行操作。 -## 後續步驟 +## 下一步 -**下一模組:** [05-mcp - 模型上下文協定 (MCP)](../05-mcp/README.md) +**下一模組：** [05-mcp - 模型上下文協定 (MCP)](../05-mcp/README.md) --- -**導覽:** [← 上一節：模組 03 - RAG](../03-rag/README.md) | [回主頁](../README.md) | [下一節：模組 05 - MCP →](../05-mcp/README.md) +**導覽：** [← 上一章：模組 03 - RAG](../03-rag/README.md) | [回主頁](../README.md) | [下一章：模組 05 - MCP →](../05-mcp/README.md) --- -**免責聲明**： -本文件由人工智慧翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 所翻譯。雖然我們力求準確，但請注意自動翻譯結果可能包含錯誤或不準確之處。文件的原始語言版本應視為權威版本。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯所產生的任何誤解或錯誤詮釋承擔責任。 +**免責聲明**： +此文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力追求準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們不對因使用此翻譯所產生的任何誤解或誤譯承擔責任。 \ No newline at end of file diff --git a/translations/zh-TW/README.md b/translations/zh-TW/README.md index e313bb480..4b01c1b17 100644 --- a/translations/zh-TW/README.md +++ b/translations/zh-TW/README.md @@ -1,108 +1,108 @@ LangChain4j -# LangChain4j 初學者指南 +# LangChain4j 新手入門 -使用 LangChain4j 及 Azure OpenAI GPT-5.2 建立 AI 應用程式的課程，從基礎聊天到 AI 代理人。 +一門使用 LangChain4j 和 Azure OpenAI GPT-5.2 構建 AI 應用的課程，從基礎聊天到 AI 代理。 ### 🌐 多語言支援 -#### 透過 GitHub Action 支援（自動化且永遠保持最新） +#### 透過 GitHub Action 支援（自動且保持最新） -[阿拉伯文](../ar/README.md) | [孟加拉文](../bn/README.md) | [保加利亞文](../bg/README.md) | [緬甸語 (Myanmar)](../my/README.md) | [中文 (簡體)](../zh-CN/README.md) | [中文 (繁體, 香港)](../zh-HK/README.md) | [中文 (繁體, 澳門)](../zh-MO/README.md) | [中文 (繁體, 台灣)](./README.md) | [克羅地亞文](../hr/README.md) | [捷克文](../cs/README.md) | [丹麥文](../da/README.md) | [荷蘭文](../nl/README.md) | [愛沙尼亞文](../et/README.md) | [芬蘭文](../fi/README.md) | [法文](../fr/README.md) | [德文](../de/README.md) | [希臘文](../el/README.md) | [希伯來文](../he/README.md) | [印地文](../hi/README.md) | [匈牙利文](../hu/README.md) | [印尼文](../id/README.md) | [義大利文](../it/README.md) | [日文](../ja/README.md) | [坎納達文](../kn/README.md) | [高棉文](../km/README.md) | [韓文](../ko/README.md) | [立陶宛文](../lt/README.md) | [馬來文](../ms/README.md) | [馬拉雅拉姆文](../ml/README.md) | [馬拉地文](../mr/README.md) | [尼泊爾文](../ne/README.md) | [奈及利亞皮欽語](../pcm/README.md) | [挪威文](../no/README.md) | [波斯文 (Farsi)](../fa/README.md) | [波蘭文](../pl/README.md) | [葡萄牙文 (巴西)](../pt-BR/README.md) | [葡萄牙文 (葡萄牙)](../pt-PT/README.md) | [旁遮普文 (Gurmukhi)](../pa/README.md) | [羅馬尼亞文](../ro/README.md) | [俄文](../ru/README.md) | [塞爾維亞文 (西里爾字母)](../sr/README.md) | [斯洛伐克文](../sk/README.md) | [斯洛維尼亞文](../sl/README.md) | [西班牙文](../es/README.md) | [斯瓦希里文](../sw/README.md) | [瑞典文](../sv/README.md) | [塔加洛語 (菲律賓語)](../tl/README.md) | [泰米爾文](../ta/README.md) | [泰盧固文](../te/README.md) | [泰文](../th/README.md) | [土耳其文](../tr/README.md) | [烏克蘭文](../uk/README.md) | [烏爾都文](../ur/README.md) | [越南文](../vi/README.md) +[阿拉伯文](../ar/README.md) | [孟加拉文](../bn/README.md) | [保加利亞文](../bg/README.md) | [緬甸文](../my/README.md) | [中文（簡體）](../zh-CN/README.md) | [中文（繁體，香港）](../zh-HK/README.md) | [中文（繁體，澳門）](../zh-MO/README.md) | [中文（繁體，台灣）](./README.md) | [克羅地亞文](../hr/README.md) | [捷克文](../cs/README.md) | [丹麥文](../da/README.md) | [荷蘭文](../nl/README.md) | [愛沙尼亞文](../et/README.md) | [芬蘭文](../fi/README.md) | [法文](../fr/README.md) | [德文](../de/README.md) | [希臘文](../el/README.md) | [希伯來文](../he/README.md) | [印地文](../hi/README.md) | [匈牙利文](../hu/README.md) | [印尼文](../id/README.md) | [義大利文](../it/README.md) | [日文](../ja/README.md) | [卡納達文](../kn/README.md) | [高棉文](../km/README.md) | [韓文](../ko/README.md) | [立陶宛文](../lt/README.md) | [馬來文](../ms/README.md) | [馬拉雅拉姆文](../ml/README.md) | [馬拉地文](../mr/README.md) | [尼泊爾文](../ne/README.md) | [奈及利亞皮欽語](../pcm/README.md) | [挪威文](../no/README.md) | [波斯文 (法爾西語)](../fa/README.md) | [波蘭文](../pl/README.md) | [葡萄牙文（巴西）](../pt-BR/README.md) | [葡萄牙文（葡萄牙）](../pt-PT/README.md) | [旁遮普文（古魯穆奇文）](../pa/README.md) | [羅馬尼亞文](../ro/README.md) | [俄文](../ru/README.md) | [塞爾維亞文（西里爾字母）](../sr/README.md) | [斯洛伐克文](../sk/README.md) | [斯洛維尼亞文](../sl/README.md) | [西班牙文](../es/README.md) | [斯瓦希里文](../sw/README.md) | [瑞典文](../sv/README.md) | [他加祿文（菲律賓語）](../tl/README.md) | [泰米爾文](../ta/README.md) | [泰盧固文](../te/README.md) | [泰文](../th/README.md) | [土耳其文](../tr/README.md) | [烏克蘭文](../uk/README.md) | [烏爾都文](../ur/README.md) | [越南文](../vi/README.md) -> **想要本地化克隆？** +> **想要本機克隆嗎？** > -> 此存儲庫包含 50 多種語言的翻譯，因此下載檔案體積會大幅增加。若要不包含翻譯進行克隆，請使用稀疏檢出： +> 此存儲庫包括 50 多種語言的翻譯，會大幅增加下載大小。若要在不包含翻譯的情況下克隆，請使用稀疏檢出： > -> **Bash / macOS / Linux:** +> **Bash / macOS / Linux：** > ```bash > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone '/*' '!translations' '!translated_images' > ``` > -> **CMD (Windows):** +> **CMD（Windows）：** > ```cmd > git clone --filter=blob:none --sparse https://github.com/microsoft/LangChain4j-for-Beginners.git > cd LangChain4j-for-Beginners > git sparse-checkout set --no-cone "/*" "!translations" "!translated_images" > ``` > -> 這樣可以讓您快速下載並取得完成課程所需的所有內容。 +> 這提供了完成課程所需的一切，且下載速度更快。 + ## 目錄 -1. [快速入門](00-quick-start/README.md) - 快速開始使用 LangChain4j -2. [介紹](01-introduction/README.md) - 學習 LangChain4j 基本概念 -3. [提示工程](02-prompt-engineering/README.md) - 精通有效的提示設計 -4. [RAG (檢索增強生成)](03-rag/README.md) - 建立智慧型知識系統 -5. [工具](04-tools/README.md) - 整合外部工具與簡易助理 -6. [MCP (模型上下文協議)](05-mcp/README.md) - 操作模型上下文協議 (MCP) 及代理模組 +1. [導論](01-introduction/README.md) - 學習 LangChain4j 的基礎知識 +2. [提示工程](02-prompt-engineering/README.md) - 精通有效的提示設計 +3. [RAG（檢索增強生成）](03-rag/README.md) - 建構智能知識基礎系統 +4. [工具](04-tools/README.md) - 整合外部工具與簡易助理 +5. [MCP（模型上下文協定）](05-mcp/README.md) - 使用模型上下文協定（MCP）與代理模組 ### 影片導覽 -每個模組都配有直播教學，我們逐步講解相關概念與程式碼。 +每個模組都有伴隨的直播課程，逐步講解概念與程式碼。 | 模組 | 影片 | |--------|-------| -| 01 - 介紹 | [LangChain4j 快速入門](https://www.youtube.com/live/nl_troDm8rQ) | +| 01 - 導論 | [LangChain4j 入門指南](https://www.youtube.com/live/nl_troDm8rQ) | | 02 - 提示工程 | [LangChain4j 提示工程](https://www.youtube.com/live/PJ6aBaE6bog) | -| 03 - RAG | [LangChain4j 的 RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | -| 04 - 工具 & 05 - MCP | [結合工具與 MCP 的 AI 代理人](https://www.youtube.com/watch?v=O_J30kZc0rw) | +| 03 - RAG | [LangChain4j RAG](https://www.youtube.com/watch?v=_olq75ZH_eY) | +| 04 - 工具 ＆ 05 - MCP | [搭配工具與 MCP 的 AI 代理](https://www.youtube.com/watch?v=O_J30kZc0rw) | --- -## 學習路線 +## 學習路徑 -**第一次接觸 LangChain4j？** 請參考 [詞彙表](docs/GLOSSARY.md) 了解重要術語與概念。 +**初次接觸 LangChain4j？** 請參閱 [術語表](docs/GLOSSARY.md) 以了解關鍵詞與概念定義。 -> 快速入門 +> 快速開始 -1. 將本存儲庫 Fork 到您的 GitHub 帳號 -2. 點選 **Code** → **Codespaces** 分頁 → **...** → **New with options...** -3. 使用預設設定 - 這會選擇為本課程建立的開發容器 -4. 點擊 **Create codespace** -5. 等待 5-10 分鐘讓環境準備好 -6. 直接跳至 [快速入門](./00-quick-start/README.md) 開始學習！ +1. 將本存儲庫分支到你的 GitHub 帳號 +2. 點選 **Code** → **Codespaces** 標籤 → **...** → **New with options...** +3. 使用預設值—這將選擇本課程創建的開發容器 +4. 點選 **Create codespace** +5. 等待 5-10 分鐘，環境就緒 +6. 直接跳到 [導論](./01-introduction/README.md) 開始學習！ -完成所有模組後，探究 [測試指南](docs/TESTING.md) 以實際了解 LangChain4j 測試概念。 +完成模組後，探索 [測試指南](docs/TESTING.md)，親自體驗 LangChain4j 測試概念。 -> **注意：** 本培訓課程同時使用 GitHub 模型與 Azure OpenAI。 [快速入門](00-quick-start/README.md) 模組使用 GitHub 模型（不需 Azure 訂閱），模組 1-5 使用 Azure OpenAI。若您還沒有，請先使用 [免費 Azure 帳戶](https://aka.ms/azure-free-account) 開始。 +> **注意：** 本訓練使用 Azure OpenAI。若尚未擁有帳號，請先申請 [免費 Azure 帳戶](https://aka.ms/azure-free-account)。 -## 使用 GitHub Copilot 學習 +## 使用 GitHub Copilot 進行學習 -想快速開始寫程式，可在 GitHub Codespace 或本機 IDE 以本課程提供的 devcontainer 開啟此專案。課程使用的 devcontainer 預先配置 GitHub Copilot，支援 AI 配對編程。 +要快速開始寫程式，請在 GitHub Codespace 或帶有提供的 devcontainer 的本地 IDE 中打開此專案。本課程中的 devcontainer 預先配置了 GitHub Copilot，支援 AI 配對程式設計。 -每個程式範例均包含建議可問 GitHub Copilot 的問題，幫助加深理解。請留意以下的 💡/🤖 提示： +每個程式碼範例都包含你可以問 GitHub Copilot 的建議問題，幫助你深化理解。請留意以下中的 💡/🤖 提示： -- **Java 檔案標頭** - 針對每個範例的專屬問題 -- **模組 README** - 程式範例後的探索提示 +- **Java 檔案標頭** - 專屬於每個範例的問題 +- **模組 README** - 程式碼範例後的深度探索提示 -**使用方法：** 打開任意程式檔案，問 Copilot 建議問題。它了解完整程式碼庫，可以解說、擴充並提供替代方案。 +**使用方式：** 打開任一程式碼檔案，並提出建議中的問題。Copilot 擁有完整程式碼庫上下文，可為你解說、擴展及建議替代方案。 -想了解更多？請參閱 [AI 配對編程的 Copilot](https://aka.ms/GitHubCopilotAI)。 +想了解更多？請參考 [GitHub Copilot 的 AI 配對程式設計](https://aka.ms/GitHubCopilotAI)。 ## 其他資源 ### LangChain -[![LangChain4j 初學者](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) -[![LangChain.js 初學者](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) -[![LangChain 初學者](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain4j 新手入門](https://img.shields.io/badge/LangChain4j%20for%20Beginners-22C55E?style=for-the-badge&&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchain4j-for-beginners) +[![LangChain.js 新手入門](https://img.shields.io/badge/LangChain.js%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://aka.ms/langchainjs-for-beginners?WT.mc_id=m365-94501-dwahlin) +[![LangChain 新手入門](https://img.shields.io/badge/LangChain%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=0553D6)](https://github.com/microsoft/langchain-for-beginners?WT.mc_id=m365-94501-dwahlin) --- -### Azure / Edge / MCP / Agents -[![AZD 初學者](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) -[![Edge AI 初學者](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) -[![MCP 初學者](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) -[![AI 代理人 初學者](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) +### Azure / Edge / MCP / 代理 +[![AZD 新手入門](https://img.shields.io/badge/AZD%20for%20Beginners-0078D4?style=for-the-badge&labelColor=E5E7EB&color=0078D4)](https://github.com/microsoft/AZD-for-beginners?WT.mc_id=academic-105485-koreyst) +[![Edge AI 新手入門](https://img.shields.io/badge/Edge%20AI%20for%20Beginners-00B8E4?style=for-the-badge&labelColor=E5E7EB&color=00B8E4)](https://github.com/microsoft/edgeai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![MCP 新手入門](https://img.shields.io/badge/MCP%20for%20Beginners-009688?style=for-the-badge&labelColor=E5E7EB&color=009688)](https://github.com/microsoft/mcp-for-beginners?WT.mc_id=academic-105485-koreyst) +[![AI 代理新手入門](https://img.shields.io/badge/AI%20Agents%20for%20Beginners-00C49A?style=for-the-badge&labelColor=E5E7EB&color=00C49A)](https://github.com/microsoft/ai-agents-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### 生成式 AI 系列 -[![生成式 AI 初學者](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) +[![生成式 AI 新手入門](https://img.shields.io/badge/Generative%20AI%20for%20Beginners-8B5CF6?style=for-the-badge&labelColor=E5E7EB&color=8B5CF6)](https://github.com/microsoft/generative-ai-for-beginners?WT.mc_id=academic-105485-koreyst) [![生成式 AI (.NET)](https://img.shields.io/badge/Generative%20AI%20(.NET)-9333EA?style=for-the-badge&labelColor=E5E7EB&color=9333EA)](https://github.com/microsoft/Generative-AI-for-beginners-dotnet?WT.mc_id=academic-105485-koreyst) [![生成式 AI (Java)](https://img.shields.io/badge/Generative%20AI%20(Java)-C084FC?style=for-the-badge&labelColor=E5E7EB&color=C084FC)](https://github.com/microsoft/generative-ai-for-beginners-java?WT.mc_id=academic-105485-koreyst) [![生成式 AI (JavaScript)](https://img.shields.io/badge/Generative%20AI%20(JavaScript)-E879F9?style=for-the-badge&labelColor=E5E7EB&color=E879F9)](https://github.com/microsoft/generative-ai-with-javascript?WT.mc_id=academic-105485-koreyst) @@ -110,39 +110,40 @@ --- ### 核心學習 -[![機器學習 初學者](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) -[![資料科學 初學者](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) -[![人工智慧 初學者](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) -[![初學者網路安全](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) -[![初學者網頁開發](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) -[![初學者物聯網](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) -[![初學者XR開發](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) +[![機器學習新手](https://img.shields.io/badge/ML%20for%20Beginners-22C55E?style=for-the-badge&labelColor=E5E7EB&color=22C55E)](https://aka.ms/ml-beginners?WT.mc_id=academic-105485-koreyst) +[![資料科學新手](https://img.shields.io/badge/Data%20Science%20for%20Beginners-84CC16?style=for-the-badge&labelColor=E5E7EB&color=84CC16)](https://aka.ms/datascience-beginners?WT.mc_id=academic-105485-koreyst) +[![人工智慧新手](https://img.shields.io/badge/AI%20for%20Beginners-A3E635?style=for-the-badge&labelColor=E5E7EB&color=A3E635)](https://aka.ms/ai-beginners?WT.mc_id=academic-105485-koreyst) +[![資安新手](https://img.shields.io/badge/Cybersecurity%20for%20Beginners-F97316?style=for-the-badge&labelColor=E5E7EB&color=F97316)](https://github.com/microsoft/Security-101?WT.mc_id=academic-96948-sayoung) + +[![Web Dev for Beginners](https://img.shields.io/badge/Web%20Dev%20for%20Beginners-EC4899?style=for-the-badge&labelColor=E5E7EB&color=EC4899)](https://aka.ms/webdev-beginners?WT.mc_id=academic-105485-koreyst) +[![IoT for Beginners](https://img.shields.io/badge/IoT%20for%20Beginners-14B8A6?style=for-the-badge&labelColor=E5E7EB&color=14B8A6)](https://aka.ms/iot-beginners?WT.mc_id=academic-105485-koreyst) +[![XR Development for Beginners](https://img.shields.io/badge/XR%20Development%20for%20Beginners-38BDF8?style=for-the-badge&labelColor=E5E7EB&color=38BDF8)](https://github.com/microsoft/xr-development-for-beginners?WT.mc_id=academic-105485-koreyst) --- ### Copilot 系列 -[![AI 配對程式設計的 Copilot](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) -[![C#/.NET 的 Copilot](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) -[![Copilot 冒險](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) +[![Copilot for AI Paired Programming](https://img.shields.io/badge/Copilot%20for%20AI%20Paired%20Programming-FACC15?style=for-the-badge&labelColor=E5E7EB&color=FACC15)](https://aka.ms/GitHubCopilotAI?WT.mc_id=academic-105485-koreyst) +[![Copilot for C#/.NET](https://img.shields.io/badge/Copilot%20for%20C%23/.NET-FBBF24?style=for-the-badge&labelColor=E5E7EB&color=FBBF24)](https://github.com/microsoft/mastering-github-copilot-for-dotnet-csharp-developers?WT.mc_id=academic-105485-koreyst) +[![Copilot Adventure](https://img.shields.io/badge/Copilot%20Adventure-FDE68A?style=for-the-badge&labelColor=E5E7EB&color=FDE68A)](https://github.com/microsoft/CopilotAdventures?WT.mc_id=academic-105485-koreyst) -## 尋求協助 +## 獲取幫助 -如果您卡住或對建立 AI 應用程式有任何疑問，請加入： +如果遇到困難或對建立 AI 應用有任何問題，請加入： [![Microsoft Foundry Discord](https://img.shields.io/badge/Discord-Microsoft_Foundry_Community_Discord-blue?style=for-the-badge&logo=discord&color=5865f2&logoColor=fff)](https://aka.ms/foundry/discord) -如果您在建置過程中有產品反饋或錯誤，請造訪： +如果您在開發過程中有產品反饋或錯誤，請訪問： [![Microsoft Foundry Developer Forum](https://img.shields.io/badge/GitHub-Microsoft_Foundry_Developer_Forum-blue?style=for-the-badge&logo=github&color=000000&logoColor=fff)](https://aka.ms/foundry/forum) ## 授權 -MIT 授權條款 - 詳情請參閱 [LICENSE](../../LICENSE) 檔案。 +MIT 授權 - 請參閱 [LICENSE](../../LICENSE) 文件了解詳情。 --- -**免責聲明**： -本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力確保翻譯的準確性，但請注意，自動翻譯可能包含錯誤或不精確之處。原始文件的母語版本應視為權威資料來源。對於重要資訊，建議採用專業人工翻譯。我們不對因使用本翻譯而導致的任何誤解或錯誤解釋負責。 +**免責聲明**： +此文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力追求準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們不對因使用此翻譯所產生的任何誤解或誤譯承擔責任。 \ No newline at end of file diff --git a/translations/zh-TW/docs/GLOSSARY.md b/translations/zh-TW/docs/GLOSSARY.md index ef03213ea..617b2afc5 100644 --- a/translations/zh-TW/docs/GLOSSARY.md +++ b/translations/zh-TW/docs/GLOSSARY.md @@ -1,232 +1,230 @@ -# LangChain4j 術語表 +# LangChain4j 詞彙表 ## 目錄 -- [核心概念](../../../docs) -- [LangChain4j 元件](../../../docs) -- [AI/ML 概念](../../../docs) -- [守護措施](../../../docs) -- [提示工程](../../../docs) -- [RAG（檢索增強生成）](../../../docs) -- [代理程式與工具](../../../docs) -- [Agentic 模組](../../../docs) -- [模型上下文協定（MCP）](../../../docs) -- [Azure 服務](../../../docs) -- [測試與開發](../../../docs) +- [核心概念](#核心概念) +- [LangChain4j 元件](#langchain4j-元件) +- [AI/ML 概念](#aiml-概念) +- [防護欄](#防護欄) +- [提示工程](#prompt-engineering---module-02) +- [RAG（檢索增強生成）](#rag-retrieval-augmented-generation---module-03) +- [代理和工具](#agents-and-tools---module-04) +- [Agentic 模組](#agentic-module---module-05) +- [模型上下文協定（MCP）](#model-context-protocol-mcp---module-05) +- [Azure 服務](#azure-services---module-01) +- [測試與開發](#testing-and-development---testing-guide) -本課程所用術語與概念的快速參考。 +快速參考課程中使用的術語和概念。 ## 核心概念 -**AI 代理程式** - 使用 AI 自主推理與行動的系統。 [模組 04](../04-tools/README.md) +**AI 代理** - 使用 AI 進行推理並自主行動的系統。[模組 04](../04-tools/README.md) -**鏈（Chain）** - 依序執行操作，輸出作為下一步輸入的序列。 +**鏈（Chain）** - 輸出作為下一步的輸入的一系列操作。 -**分塊（Chunking）** - 將文件拆分成較小部分。典型大小：300-500 個標記，有重疊。 [模組 03](../03-rag/README.md) +**拆塊（Chunking）** - 將文件拆分為較小部分。典型大小：300-500 個標記，帶有重疊。[模組 03](../03-rag/README.md) -**上下文視窗** - 模型可處理的最大標記數。GPT-5.2：400K 標記（最多 272K 輸入，128K 輸出）。 +上下文窗口 - 模型可處理的最大標記數。GPT-5.2：400K 標記（輸入最高 272K，輸出最高 128K）。 -**嵌入（Embeddings）** - 表示文字意義的數值向量。 [模組 03](../03-rag/README.md) +**嵌入（Embeddings）** - 表示文本意義的數值向量。[模組 03](../03-rag/README.md) -**函數呼叫（Function Calling）** - 模型生成結構化請求以呼叫外部函數。 [模組 04](../04-tools/README.md) +函數調用 - 模型生成結構化請求來調用外部函數。[模組 04](../04-tools/README.md) -**幻覺（Hallucination）** - 模型生成錯誤但看似合理的資訊。 +**幻覺（Hallucination）** - 模型生成錯誤但貌似合理的信息。 -**提示（Prompt）** - 輸入給語言模型的文字。 [模組 02](../02-prompt-engineering/README.md) +**提示（Prompt）** - 輸入給語言模型的文本。[模組 02](../02-prompt-engineering/README.md) -**語意搜尋（Semantic Search）** - 透過意義使用嵌入搜尋，不是關鍵字。 [模組 03](../03-rag/README.md) +語義搜索 - 使用嵌入按意義進行搜索，而非關鍵字。[模組 03](../03-rag/README.md) -**有狀態 vs 無狀態** - 無狀態：無記憶。有狀態：保留對話歷史。 [模組 01](../01-introduction/README.md) +**有狀態 vs 無狀態** - 無狀態：無記憶；有狀態：保持對話記錄。[模組 01](../01-introduction/README.md) -**標記（Tokens）** - 模型處理的基本文字單位。影響成本和限制。 [模組 01](../01-introduction/README.md) +**標記（Tokens）** - 模型處理的基本文本單位。影響成本和限制。[模組 01](../01-introduction/README.md) -**工具串接（Tool Chaining）** - 依序執行工具，輸出作為下一次呼叫的資訊。 [模組 04](../04-tools/README.md) +工具鏈接 - 按順序執行工具，其中輸出用於下一次調用。[模組 04](../04-tools/README.md) ## LangChain4j 元件 -**AiServices** - 建立型別安全的 AI 服務介面。 +**AiServices** - 創建類型安全的 AI 服務介面。 -**OpenAiOfficialChatModel** - OpenAI 和 Azure OpenAI 模型的統一用戶端。 +**OpenAiOfficialChatModel** - 用於 OpenAI 和 Azure OpenAI 模型的統一客戶端。 -**OpenAiOfficialEmbeddingModel** - 使用 OpenAI 官方用戶端建立嵌入（支援 OpenAI 與 Azure OpenAI）。 +**OpenAiOfficialEmbeddingModel** - 使用 OpenAI 官方客戶端創建嵌入（支援 OpenAI 和 Azure OpenAI）。 -**ChatModel** - 語言模型核心介面。 +**ChatModel** - 語言模型的核心介面。 -**ChatMemory** - 維護對話歷史。 +**ChatMemory** - 保持對話歷史。 -**ContentRetriever** - 尋找 RAG 用的相關文件片段。 +**ContentRetriever** - 為 RAG 尋找相關文件塊。 -**DocumentSplitter** - 將文件拆成多個片段。 +**DocumentSplitter** - 將文件拆分為塊。 -**EmbeddingModel** - 將文字轉換成數值向量。 +**EmbeddingModel** - 將文本轉換為數值向量。 -**EmbeddingStore** - 儲存與檢索嵌入。 +**EmbeddingStore** - 存儲和檢索嵌入。 -**MessageWindowChatMemory** - 維持最近訊息的滑動視窗。 +**MessageWindowChatMemory** - 保持最近消息的滑動窗口。 -**PromptTemplate** - 使用 `{{variable}}` 變數建立可重用提示。 +**PromptTemplate** - 使用 `{{variable}}` 佔位符創建可重用提示。 -**TextSegment** - 附帶元資料的文字片段，用於 RAG。 +**TextSegment** - 帶有元資料的文本塊。用於 RAG。 -**ToolExecutionRequest** - 表示工具執行請求。 +**ToolExecutionRequest** - 代表工具執行請求。 -**UserMessage / AiMessage / SystemMessage** - 對話的訊息類型。 +**UserMessage / AiMessage / SystemMessage** - 對話消息類型。 ## AI/ML 概念 -**少量示例學習（Few-Shot Learning）** - 在提示中提供示範範例。 [模組 02](../02-prompt-engineering/README.md) +**少量示例學習（Few-Shot Learning）** - 在提示中提供範例。[模組 02](../02-prompt-engineering/README.md) -**大型語言模型（LLM）** - 在龐大文字資料上訓練的 AI 模型。 +**大型語言模型（LLM）** - 在大量文本資料上訓練的 AI 模型。 -**推理深度（Reasoning Effort）** - GPT-5.2 參數，用於控制思考深度。 [模組 02](../02-prompt-engineering/README.md) +**推理力度（Reasoning Effort）** - GPT-5.2 中控制思考深度的參數。[模組 02](../02-prompt-engineering/README.md) -**溫度（Temperature）** - 控制輸出隨機性。低值＝決定性，高值＝有創意。 +**溫度（Temperature）** - 控制輸出隨機性。低值=確定性，高值=創造性。 -**向量資料庫（Vector Database）** - 專門儲存嵌入的資料庫。 [模組 03](../03-rag/README.md) +向量資料庫 - 專為嵌入設計的資料庫。[模組 03](../03-rag/README.md) -**零示例學習（Zero-Shot Learning）** - 無範例直接執行任務。 [模組 02](../02-prompt-engineering/README.md) +**零樣本學習（Zero-Shot Learning）** - 無示例執行任務。[模組 02](../02-prompt-engineering/README.md) -## 守護措施 - [模組 00](../00-quick-start/README.md) +## 防護欄 -**多層防禦（Defense in Depth）** - 多層安控策略，結合應用層守護與供應商安全篩選。 +**深度防護（Defense in Depth）** - 多層安全策略，結合應用層防護欄與服務提供商安全過濾器。 -**硬封鎖（Hard Block）** - 嚴重內容違規導致供應商返回 HTTP 400 錯誤。 +**硬性阻擋（Hard Block）** - 嚴重內容違規時，供應商拋出 HTTP 400 錯誤。 -**InputGuardrail** - LangChain4j 介面，驗證使用者輸入避免送至 LLM，節省成本與延遲並阻擋有害提示。 +**輸入防護欄（InputGuardrail）** - LangChain4j 介面，用於在輸入到 LLM 前驗證用戶輸入。提前阻擋有害提示，可節省成本和延遲。 -**InputGuardrailResult** - 守護結果回傳類型：`success()` 或 `fatal("reason")`。 +**輸入防護欄結果（InputGuardrailResult）** - 防護欄驗證的返回類型：`success()` 或 `fatal("reason")`。 -**OutputGuardrail** - 驗證 AI 回應內容，確保安全再回傳使用者。 +**輸出防護欄（OutputGuardrail）** - 驗證 AI 回應後，才返回給用戶的介面。 -**供應商安全篩選（Provider Safety Filters）** - AI 供應商內建內容篩選（如 GitHub Models），API 階段攔截違規。 +供應商安全過濾器 - AI 供應商（例如 Azure OpenAI）在 API 級別捕捉違規內容的內建過濾器。 -**軟拒絕（Soft Refusal）** - 模型禮貌拒絕回答但不丟錯誤。 +**軟性拒絕（Soft Refusal）** - 模型禮貌地拒絕回答，無錯誤拋出。 ## 提示工程 - [模組 02](../02-prompt-engineering/README.md) -**思維鏈（Chain-of-Thought）** - 逐步推理提高準確度。 +**思維鏈（Chain-of-Thought）** - 分步推理以提高準確性。 **受限輸出（Constrained Output）** - 強制特定格式或結構。 -**高推理模式（High Eagerness）** - GPT-5.2 的詳盡推理模式。 +**高推理力度（High Eagerness）** - GPT-5.2 推理深入模式。 -**低推理模式（Low Eagerness）** - GPT-5.2 的快速回答模式。 +**低推理力度（Low Eagerness）** - GPT-5.2 快速回答模式。 -**多輪對話（Multi-Turn Conversation）** - 保持跨回合上下文。 +**多輪對話（Multi-Turn Conversation）** - 保持交流上下文。 -**角色指定提示（Role-Based Prompting）** - 透過系統訊息設定模型身份。 +**角色基礎提示（Role-Based Prompting）** - 通過系統消息設定模型角色。 -**自我反省（Self-Reflection）** - 模型自行評估並改進輸出。 +**自我反思（Self-Reflection）** - 模型評估並改進自身輸出。 -**結構化分析（Structured Analysis）** - 固定評估框架。 +**結構化分析（Structured Analysis）** - 固定的評估框架。 -**任務執行模式（Task Execution Pattern）** - 計畫 → 執行 → 彙總。 +**任務執行模式（Task Execution Pattern）** - 計劃 → 執行 → 總結。 ## RAG（檢索增強生成）- [模組 03](../03-rag/README.md) -**文件處理流程（Document Processing Pipeline）** - 載入 → 分塊 → 嵌入 → 儲存。 +文件處理管線 - 載入 → 拆塊 → 嵌入 → 存儲。 -**記憶體中嵌入存儲（In-Memory Embedding Store）** - 測試用非持久化存儲。 +記憶體內嵌入存儲 - 非持久化存儲，用於測試。 -**RAG** - 結合檢索與生成以確保回應有根據。 +**RAG** - 結合檢索和生成以根據來源回答。 -**相似度分數（Similarity Score）** - 語意相似度評分（0-1）。 +相似度分數 - 意義相似度度量（0-1）。 -**來源引用（Source Reference）** - 檢索內容的元資料。 +來源參考 - 取回內容的元資料。 -## 代理程式與工具 - [模組 04](../04-tools/README.md) +## 代理和工具 - [模組 04](../04-tools/README.md) -**@Tool 註解** - 標記 Java 方法為 AI 可呼叫工具。 +**@Tool 註解** - 標記 Java 方法為 AI 可調用工具。 **ReAct 模式** - 推理 → 行動 → 觀察 → 重複。 -**會話管理（Session Management）** - 為不同用戶分開上下文。 +會話管理 - 為不同用戶分離上下文。 -**工具（Tool）** - AI 代理程式可呼叫的函數。 +**工具（Tool）** - AI 代理可調用的函數。 -**工具說明（Tool Description）** - 工具目的與參數文件。 +工具描述 - 工具目的和參數的文檔。 ## Agentic 模組 - [模組 05](../05-mcp/README.md) -**@Agent 註解** - 標記介面為 AI 代理程式並以聲明方式定義行為。 +**@Agent 註解** - 將介面標記為帶聲明式行為定義的 AI 代理。 -**Agent 監聽器（Agent Listener）** - 透過 `beforeAgentInvocation()` 和 `afterAgentInvocation()` 監控代理執行。 +**代理監聽器（Agent Listener）** - 通過 `beforeAgentInvocation()` 和 `afterAgentInvocation()` 監控代理執行的鉤子。 -**Agentic 範圍** - 代理共享記憶，使用 `outputKey` 存放輸出以供下游代理消費。 +**Agentic 範圍** - 代理使用 `outputKey` 存儲輸出的共享記憶供下游代理使用。 -**AgenticServices** - 使用 `agentBuilder()` 和 `supervisorBuilder()` 建立代理工廠。 +**AgenticServices** - 使用 `agentBuilder()` 和 `supervisorBuilder()` 創建代理的工廠。 -**條件化工作流（Conditional Workflow）** - 根據條件路由至不同專家代理。 +**條件工作流（Conditional Workflow）** - 根據條件路由到不同專家代理。 -**人類監督（Human-in-the-Loop）** - 增設人為審查或批准工作流模式。 +**人類介入環（Human-in-the-Loop）** - 工作流程模式，增加人類審核或內容檢查點。 -**langchain4j-agentic** - 用於聲明式代理建立的 Maven 依賴（實驗性）。 +**langchain4j-agentic** - 用於聲明式代理構建的 Maven 依賴（實驗性）。 -**迴圈工作流（Loop Workflow）** - 重複執行代理直到條件達成（例如品質分數 ≥ 0.8）。 +**循環工作流（Loop Workflow）** - 迭代代理執行直到條件達成（如質量分 ≥ 0.8）。 **outputKey** - 代理註解參數，指定結果存放於 Agentic 範圍的位置。 -**平行工作流（Parallel Workflow）** - 同時執行多個獨立代理任務。 +**並行工作流（Parallel Workflow）** - 同時運行多個代理以執行獨立任務。 -**回應策略（Response Strategy）** - 主管代理形成最終答案的方式：LAST（最後一次）、SUMMARY（彙整）、SCORED（打分）。 +**回應策略（Response Strategy）** - 監督者形成最終答案的方式：LAST、SUMMARY 或 SCORED。 -**序列工作流（Sequential Workflow）** - 按順序執行代理，輸出作為下一步輸入。 +**序列工作流（Sequential Workflow）** - 按順序執行代理，輸出流向下一步。 -**主管代理模式（Supervisor Agent Pattern）** - 高階代理模式，主管 LLM 動態決定呼叫哪些子代理。 +**監督代理模式（Supervisor Agent Pattern）** - 高級 agentic 模式，由監督者 LLM 動態決定調用哪些子代理。 ## 模型上下文協定（MCP）- [模組 05](../05-mcp/README.md) -**langchain4j-mcp** - LangChain4j 的 MCP 整合 Maven 依賴。 +**langchain4j-mcp** - 用於 LangChain4j 中 MCP 集成的 Maven 依賴。 -**MCP** - 模型上下文協定：連結 AI 應用與外部工具的標準。一次建置，到處可用。 +**MCP** - 模型上下文協定：連接 AI 應用與外部工具的標準。一次構建，到處使用。 -**MCP 用戶端** - 連接 MCP 服務器以發現與使用工具的應用程式。 +**MCP 客戶端** - 連接 MCP 服務器以發現和使用工具的應用。 -**MCP 服務器** - 透過 MCP 對外曝工具服務，包含清楚說明與參數規範。 +**MCP 服務器** - 通過 MCP 對外暴露工具，提供清晰描述和參數結構。 -**McpToolProvider** - LangChain4j 元件，封裝 MCP 工具供 AI 服務與代理使用。 +**McpToolProvider** - LangChain4j 元件，將 MCP 工具包裝為 AI 服務和代理可用。 -**McpTransport** - MCP 通訊介面。實作包含 Stdio 與 HTTP。 +**McpTransport** - MCP 通信介面。實現包括 Stdio 和 HTTP。 -**Stdio 傳輸** - 透過 stdin/stdout 的本地程序傳輸。適用於檔案系統訪問或命令列工具。 +**Stdio 傳輸** - 使用 stdin/stdout 的本地進程傳輸。適用於檔案系統訪問或命令行工具。 -**StdioMcpTransport** - LangChain4j 實作，以子流程啟動 MCP 服務器。 +**StdioMcpTransport** - LangChain4j 實現，作為子進程啟動 MCP 服務器。 -**工具發現（Tool Discovery）** - 用戶端查詢服務器以取得可用工具及說明和參數結構。 +工具發現 - 客戶端查詢服務器獲取可用工具及其說明和結構。 ## Azure 服務 - [模組 01](../01-introduction/README.md) -**Azure AI 搜尋** - 具向量功能的雲端搜尋服務。 [模組 03](../03-rag/README.md) +**Azure AI 搜索** - 支援向量功能的雲端搜索。[模組 03](../03-rag/README.md) -**Azure Developer CLI (azd)** - 部署 Azure 資源。 +**Azure 開發者 CLI (azd)** - 部署 Azure 資源。 -**Azure OpenAI** - 微軟的企業級 AI 服務。 +**Azure OpenAI** - 微軟企業級 AI 服務。 -**Bicep** - Azure 基礎設施即程式碼語言。 [基礎設施指南](../01-introduction/infra/README.md) +**Bicep** - Azure 基礎架構即代碼語言。[基礎架構指南](../01-introduction/infra/README.md) -**部署名稱** - Azure 中模型部署的名稱。 +部署名稱 - Azure 中模型部署的名稱。 -**GPT-5.2** - 具備推理控制的最新 OpenAI 模型。 [模組 02](../02-prompt-engineering/README.md) +**GPT-5.2** - 最新 OpenAI 模型，具備推理控制。[模組 02](../02-prompt-engineering/README.md) ## 測試與開發 - [測試指南](TESTING.md) -**開發容器（Dev Container）** - 容器化開發環境。 [設定](../../../.devcontainer/devcontainer.json) +**開發容器（Dev Container）** - 容器化開發環境。[配置](../../../.devcontainer/devcontainer.json) -**GitHub 模型** - 免費 AI 模型試用平台。 [模組 00](../00-quick-start/README.md) +記憶體內測試 - 使用記憶體中存儲進行測試。 -**記憶體中測試（In-Memory Testing）** - 使用記憶體存儲執行測試。 +整合測試 - 使用實際基礎設施進行測試。 -**整合測試（Integration Testing）** - 使用真實基礎設施執行測試。 - -**Maven** - Java 建置自動化工具。 +**Maven** - Java 建構自動化工具。 **Mockito** - Java 模擬框架。 -**Spring Boot** - Java 應用程式框架。 [模組 01](../01-introduction/README.md) +**Spring Boot** - Java 應用程式框架。[模組 01](../01-introduction/README.md) --- -**免責聲明**： -本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們致力於確保準確性，但請注意，自動翻譯可能包含錯誤或不精確之處。原始文件之母語版本應視為權威來源。對於重要資訊，建議採用專業人工翻譯。我們不對因使用本翻譯內容所產生之任何誤解或誤譯負責。 +**免責聲明**： +此文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力追求準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們不對因使用此翻譯所產生的任何誤解或誤譯承擔責任。 \ No newline at end of file diff --git a/translations/zh-TW/docs/TESTING.md b/translations/zh-TW/docs/TESTING.md index b4a0704b3..c50d33961 100644 --- a/translations/zh-TW/docs/TESTING.md +++ b/translations/zh-TW/docs/TESTING.md @@ -2,19 +2,19 @@ ## 目錄 -- [快速開始](../../../docs) -- [測試涵蓋範圍](../../../docs) -- [執行測試](../../../docs) -- [在 VS Code 中執行測試](../../../docs) -- [測試模式](../../../docs) -- [測試理念](../../../docs) -- [後續步驟](../../../docs) +- [快速開始](#快速開始) +- [測試涵蓋範圍](#測試涵蓋範圍) +- [執行測試](#執行測試) +- [在 VS Code 中執行測試](#在-vs-code-中執行測試) +- [測試模式](#測試模式) +- [測試理念](#測試理念) +- [後續步驟](#後續步驟) -本指南將帶您了解示範如何在不要求 API 金鑰或外部服務的情況下測試 AI 應用程式的測試。 +本指南引導您了解如何測試 AI 應用程式，而不需要 API 金鑰或外部服務。 ## 快速開始 -使用單一指令執行全部測試： +使用單一指令執行所有測試： **Bash:** ```bash @@ -26,27 +26,26 @@ mvn test mvn --% test ``` -當所有測試通過後，您應該會看到如下截圖所示的輸出 — 測試完全通過且無失敗。 +當所有測試通過時，您會看到類似下圖的輸出 — 測試全數成功且無錯誤。 Successful Test Results -*成功執行測試，所有測試通過且無失敗* +*成功執行測試，所有測試皆通過且無錯誤* ## 測試涵蓋範圍 -本課程專注於本地執行的**單元測試**。每個測試皆獨立展示特定的 LangChain4j 概念。下圖的測試金字塔顯示單元測試的位置 — 它們是快速且可靠的基礎，後續測試策略皆建構於此之上。 +本課程專注於在本地執行的 單元測試。每個測試分別展示 LangChain4j 的特定概念。下方的測試金字塔展示單元測試的位置 — 它是快速且可靠的基礎，也是整體測試策略的根基。 Testing Pyramid -*測試金字塔顯示單元測試（快速、獨立）、整合測試（使用真實元件）、端對端測試之間的平衡。本課程涵蓋單元測試。* +*測試金字塔展示單元測試（快速、獨立）、整合測試（實體元件）及端對端測試的平衡。本教程涵蓋單元測試。* -| 模組 | 測試數 | 焦點 | 主要檔案 | +| 模組 | 測試數量 | 重點 | 主要檔案 | |--------|-------|-------|-----------| -| **00 - 快速開始** | 6 | 提示範本與變數代換 | `SimpleQuickStartTest.java` | -| **01 - 介紹** | 8 | 對話記憶與有狀態聊天 | `SimpleConversationTest.java` | -| **02 - 提示工程** | 12 | GPT-5.2 模式、積極程度、結構化輸出 | `SimpleGpt5PromptTest.java` | -| **03 - RAG** | 10 | 文件輸入、嵌入、相似度搜尋 | `DocumentServiceTest.java` | -| **04 - 工具** | 12 | 函式呼叫與工具鍊結 | `SimpleToolsTest.java` | +| **01 - 介紹** | 8 | 對話記憶與狀態對話 | `SimpleConversationTest.java` | +| **02 - 提示工程** | 12 | GPT-5.2 範例、急迫度、結構化輸出 | `SimpleGpt5PromptTest.java` | +| **03 - RAG** | 10 | 文件攝取、嵌入、相似度搜尋 | `DocumentServiceTest.java` | +| **04 - 工具** | 12 | 函式呼叫與工具串接 | `SimpleToolsTest.java` | | **05 - MCP** | 8 | 使用 Stdio 傳輸的模型上下文協定 | `SimpleMcpTest.java` | ## 執行測試 @@ -100,36 +99,36 @@ mvn test -Dtest=SimpleConversationTest#應該維持對話歷史 **PowerShell:** ```powershell -mvn --% test -Dtest=SimpleConversationTest#是否應維持對話歷史 +mvn --% test -Dtest=SimpleConversationTest#應該維持對話歷史 ``` ## 在 VS Code 中執行測試 -若您使用 Visual Studio Code，測試總管（Test Explorer）提供圖形介面來執行及偵錯測試。 +若您使用 Visual Studio Code，測試探索器能提供圖形化介面用於執行及除錯測試。 VS Code Test Explorer -*VS Code 測試總管顯示測試樹，包括所有 Java 測試類別與個別測試方法* +*VS Code 測試探索器展示完整的 Java 測試類別與各個測試方法的樹狀結構* -**於 VS Code 執行測試：** +**在 VS Code 執行測試的方法：** -1. 點擊活動列（Activity Bar）中的燒杯圖示開啟測試總管 -2. 展開測試樹以檢視所有模組與測試類別 -3. 點擊任一測試旁的播放鈕以執行該測試 -4. 點擊「執行所有測試」來執行整個測試套件 -5. 右鍵點擊任一測試並選擇「偵錯測試」以設定斷點並逐步除錯程式碼 +1. 點擊活動列上的燒杯圖示開啟測試探索器 +2. 展開測試樹以檢視所有模組和測試類別 +3. 點擊任一測試旁的播放按鈕，執行該測試 +4. 點擊「Run All Tests」執行全部測試 +5. 右鍵點擊測試選擇「Debug Test」設置斷點並逐步執行 -測試總管以綠色核取符號顯示通過測試，失敗時則提供詳細錯誤訊息。 +測試探索器會以綠色勾號標示通過測試，失敗時會提供詳細錯誤訊息。 ## 測試模式 -### 模式 1：測試提示範本 +### 模式 1：測試提示模板 -最簡單的模式是測試提示範本，不呼叫任何 AI 模型。您驗證變數代換是否正確且提示格式符合預期。 +最簡單的模式是測試提示模板，並不會呼叫任何 AI 模型。目的是驗證變數的替換是否正確，以及提示格式是否如預期。 Prompt Template Testing -*測試提示範本顯示變數代換流程：帶有佔位符的範本 → 套用數值 → 驗證格式化輸出* +*測試提示模板示意變數替換流程：帶有佔位符的模板 → 套用值 → 驗證格式化輸出* ```java @Test @@ -148,27 +147,15 @@ void testPromptTemplateFormatting() { } ``` -此測試位於 `00-quick-start/src/test/java/com/example/langchain4j/quickstart/SimpleQuickStartTest.java`。 - -**執行方式：** - -**Bash:** -```bash -cd 00-quick-start && mvn test -Dtest=SimpleQuickStartTest#測試提示範本格式化 -``` - -**PowerShell:** -```powershell -cd 00-quick-start; mvn --% test -Dtest=SimpleQuickStartTest#測試提示模板格式化 -``` +此模式驗證變數替換功能正常，提示格式符合預期 — 不需 API 金鑰或模型呼叫。 ### 模式 2：模擬語言模型 -測試對話邏輯時，使用 Mockito 創建回傳預先設定響應的假模型。這使測試快速、免費且可重複。 +測試對話邏輯時，可使用 Mockito 建立假模型，回傳預設的回應。這使測試快速、免費且具決定性。 Mock vs Real API Comparison -*比較說明模擬測試的優勢：快速、免費、可重複，且不需 API 金鑰* +*比較示意說明為何模擬測試首選：它快速、免費、具決定性，且無須 API 金鑰* ```java @ExtendWith(MockitoExtension.class) @@ -218,15 +205,15 @@ class SimpleConversationTest { } ``` -此模式實現在 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java`。模擬保證行為一致，讓您能驗證記憶管理是否正常。 +此模式出現在 `01-introduction/src/test/java/com/example/langchain4j/service/SimpleConversationTest.java` 中。此模擬確保行為穩定，方便驗證記憶管理是否正確。 ### 模式 3：測試對話隔離 -對話記憶必須保持多用戶隔離。本測試確保不同對話不混淆上下文。 +對話記憶需區分多個使用者。此測試用以驗證對話不會混合上下文。 Conversation Isolation -*測試對話隔離顯示不同用戶有獨立記憶儲存，避免上下文混淆* +*測試對話隔離，顯示不同使用者有獨立記憶，防止上下文混淆* ```java @Test @@ -250,15 +237,15 @@ void shouldIsolateConversationsByid() { } ``` -每個對話維護獨立歷史。在生產系統中，多用戶應用必須確保此隔離。 +每個對話維持獨立歷史。在生產系統中，此隔離對於多用戶應用至關重要。 ### 模式 4：獨立測試工具 -工具是 AI 可以呼叫的函式。直接測試工具確保它們運作正常，不依賴 AI 決策。 +工具是 AI 可以呼叫的函式。直接測試工具可確保功能正確，無論 AI 判斷如何。 Tools Testing -*獨立測試工具展示模擬工具執行、不呼叫 AI 以驗證業務邏輯* +*獨立測試工具示意，使用模擬工具執行而非 AI 呼叫，以驗證商業邏輯* ```java @Test @@ -281,15 +268,15 @@ void shouldDemonstrateToolChaining() { } ``` -這些測試來自 `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`，驗證工具邏輯無需 AI 介入。鍊結範例顯示如何將一工具輸出輸入到另一工具。 +此測試來自 `04-tools/src/test/java/com/example/langchain4j/agents/tools/SimpleToolsTest.java`，驗證未透過 AI 的工具邏輯。串接範例展現一個工具的輸出如何成為另一工具的輸入。 -### 模式 5：記憶體內 RAG 測試 +### 模式 5：記憶中 RAG 測試 -RAG 系統傳統上需要向量資料庫與嵌入服務。記憶體內模式讓您在無外部依賴下測試整體流程。 +傳統 RAG 系統須依賴向量資料庫與嵌入服務。記憶中測試模式可於不依賴外部資源下測試完整管線。 In-Memory RAG Testing -*記憶體內 RAG 測試流程示意文件解析、嵌入儲存與相似度搜尋，無需資料庫* +*記憶中 RAG 測試流程示意，涵蓋文件解析、嵌入儲存與相似度搜尋，無須資料庫* ```java @Test @@ -306,13 +293,13 @@ void testProcessTextDocument() { } ``` -此測試來自 `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`，在記憶體內建立文件並驗證切段及元資料處理。 +此測試出自 `03-rag/src/test/java/com/example/langchain4j/rag/service/DocumentServiceTest.java`，在記憶中建立文件並驗證切塊與元資料處理。 ### 模式 6：MCP 整合測試 -MCP 模組測試使用 stdio 傳輸的模型上下文協定整合。測試驗證您的應用可作為子程序啟動並與 MCP 伺服器通訊。 +MCP 模組測試使用 stdio 傳輸的模型上下文協定整合。測試驗證應用程式是否能以子程序形式啟動與通信 MCP 伺服器。 -位於 `05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` 的測試驗證 MCP 客戶端行為。 +`05-mcp/src/test/java/com/example/langchain4j/mcp/SimpleMcpTest.java` 中的測試驗證 MCP 用戶端行為。 **執行方式：** @@ -328,36 +315,35 @@ cd 05-mcp; mvn --% test ## 測試理念 -測試您的程式碼，而非 AI。測試應驗證您撰寫的程式碼，檢查提示如何建立、記憶如何管理以及工具如何執行。AI 回應會變動，因此不應納入測試斷言。問自己提示範本是否正確代換變數，而非 AI 是否回答正確。 +測試的是您的程式碼，而不是 AI。您的測試應驗證您所寫的程式：確認提示模板如何建構、記憶如何管理以及工具如何執行。AI 回應有變化，不宜作為斷言依據。關注提示模板是否正確替換變數，而非 AI 是否給出正確答案。 -使用模擬語言模型。它們是慢、昂貴、不可重複的外部依賴。模擬讓測試快（毫秒級而非秒級）、免費（無 API 成本）且重複性高（結果一致）。 +對語言模型使用模擬。它們是外部依賴，速度慢、成本高且結果不具決定性。模擬讓測試快速（毫秒級而非秒）、免費且結果一致。 -保持測試獨立。每個測試應自行建立資料，不依賴其他測試，且執行後清理。測試結果不應受執行順序影響。 +保持測試獨立。每個測試應單獨準備資料，不依賴其他測試，且測試後能清理環境。測試順序不同時都應通過。 -測試邊界條件與非理想情境。嘗試空輸入、非常大輸入、特殊字元、無效參數及邊界條件。這些常揭露正常使用不易發現的錯誤。 +涵蓋邊界情況，不只測試理想情境。嘗試空輸入、極大輸入、特殊字元、無效參數與界限條件。這些經常揭露平常使用看不見的錯誤。 -使用描述性名稱。比較 `shouldMaintainConversationHistoryAcrossMultipleMessages()` 與 `test1()`。前者明確說明測試內容，除錯失敗時更容易。 +使用描述性命名。比較 `shouldMaintainConversationHistoryAcrossMultipleMessages()` 與 `test1()`。前者明確告訴您測試目標，讓錯誤除錯更容易。 ## 後續步驟 -既然您已了解測試模式，深入學習每個模組： +既然您已理解測試模式，接著深入研究各模組： -- **[00 - 快速開始](../00-quick-start/README.md)** - 從提示範本基礎開始 - **[01 - 介紹](../01-introduction/README.md)** - 學習對話記憶管理 -- **[02 - 提示工程](../02-prompt-engineering/README.md)** - 精通 GPT-5.2 提示模式 -- **[03 - RAG](../03-rag/README.md)** - 建立檢索增強生成系統 -- **[04 - 工具](../04-tools/README.md)** - 實作函式呼叫與工具鍊結 +- **[02 - 提示工程](../02/prompt-engineering/README.md)** - 掌握 GPT-5.2 提示範例 +- **[03 - RAG](../03-rag/README.md)** - 建置檢索增強生成系統 +- **[04 - 工具](../04-tools/README.md)** - 實作函式呼叫與工具串接 - **[05 - MCP](../05-mcp/README.md)** - 整合模型上下文協定 -每個模組的 README 都詳細解釋此處測試的概念。 +每個模組的 README 提供此處測試概念的詳細說明。 --- -**導覽：** [← 返回主頁](../README.md) +**導航：** [← 返回主頁](../README.md) --- -**免責聲明**： -本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們致力於提供準確的翻譯，但請注意自動翻譯可能包含錯誤或不準確之處。原始語言版本之文件應視為權威來源。對於重要資訊，建議採用專業人工翻譯。我們不對因使用本翻譯而產生之任何誤解或曲解負責。 +**免責聲明**： +此文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們努力追求準確性，但請注意自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應視為權威來源。對於關鍵資訊，建議採用專業人工翻譯。我們不對因使用此翻譯所產生的任何誤解或誤譯承擔責任。 \ No newline at end of file